@plainid/openclaw-authorizer

Standalone OpenClaw plugin package for PlainID authorization.

It supports two runtime modes:

• principal-context: PlainID sees the authenticated user as the primary identity and the OpenClaw agent as a secondary identity.
• agent-only: PlainID sees only the OpenClaw agent as the primary identity.

This sibling project is the publish target. The larger development repo remains the source of truth for the compose stack, sidecar deployment bundle, and demo infrastructure.

Tested against OpenClaw 2026.3.28.

Install

npm install @plainid/openclaw-authorizer

Load it from your OpenClaw config:

{
  plugins: {
    enabled: true,
    load: {
      paths: ["./plugins/plainid-openclaw-authorizer"]
    },
    entries: {
      "plainid-authorizer": {
        enabled: true,
        config: {
          enabled: true,
          authorization: {
            mode: "agent-only"
          },
          pdp: {
            baseUrl: "https://plainid.example.com",
            clientId: "plainid-client",
            clientSecret: "replace-with-secret"
          }
        }
      }
    }
  }
}

How To Operate The Plugin

This publish target supports the same two runtime modes as the development repo.

Recommended Community Mode: agent-only

This is the default operating recommendation for marketplace/community users.

Use it when:

• you want a pure plugin install
• there is no sidecar bridge
• PlainID should authorize the OpenClaw agent itself

Behavior:

• the OpenClaw agentId is the PlainID primary identity
• no secondary identity is sent
• principal-context routes are not required
• no sidecar or ingress upsert flow is needed

Minimal example:

{
  plugins: {
    enabled: true,
    entries: {
      "plainid-authorizer": {
        enabled: true,
        config: {
          enabled: true,
          authorization: {
            mode: "agent-only"
          },
          pdp: {
            baseUrl: "https://plainid.example.com",
            clientId: "plainid-client",
            clientSecret: "replace-with-secret"
          }
        }
      }
    }
  }
}

Sidecar-Assisted Mode: principal-context

Use it when:

• your ingress authenticates an end user
• PlainID must authorize on behalf of that user
• the OpenClaw agent should be sent as a secondary identity

Behavior:

• the authenticated user is the PlainID primary identity
• the OpenClaw agentId is sent as a secondary identity
• the plugin exposes principal-context internal routes
• an ingress bridge or equivalent context-upsert flow is required

Minimal example:

{
  plugins: {
    enabled: true,
    entries: {
      "plainid-authorizer": {
        enabled: true,
        config: {
          enabled: true,
          authorization: {
            mode: "principal-context"
          },
          principalContext: {
            ingressSharedSecret: "replace-with-shared-secret",
            enableInternalRoute: true
          },
          pdp: {
            baseUrl: "https://plainid.example.com",
            clientId: "plainid-client",
            clientSecret: "replace-with-secret"
          }
        }
      }
    }
  }
}

This published package does not include the sidecar bundle itself. For the full compose deployment, ingress bridge, and demo infrastructure, use the companion development repo alongside this package.

Modes

agent-only

Use this when you want a pure plugin deployment with no sidecar and no principal-context bridge.

Behavior:

• the PlainID primary identity is the OpenClaw agentId
• no secondary identity is sent
• principal-context routes are not registered
• tool and model authorization do not depend on end-user context

Starter example: examples/agent-only.config.json5

principal-context

Use this when your deployment has an ingress or bridge path that can upsert authenticated user context into the plugin.

Behavior:

• the PlainID primary identity is the authenticated user
• the OpenClaw agentId is sent as a secondary identity
• the plugin exposes /_plainid/context/upsert and /_plainid/context/health
• high-risk authorization can require principal context

Starter example: examples/principal-context.config.json5

This package does not ship the compose stack or customer ingress bundle. If you want a sidecar-assisted deployment, keep using the companion development repo alongside this publish target.

Switching Modes

Change only:

{
  authorization: {
    mode: "agent-only" // or "principal-context"
  }
}

When switching from agent-only to principal-context, you must also provide:

• a principal-context upsert path
• a shared secret for that path
• authenticated ingress that resolves the user identity before OpenClaw

When switching from principal-context back to agent-only, remove the ingress dependency and keep only the plugin config plus PlainID PDP credentials.

What The Plugin Enforces

• PlainID authorization in before_tool_call
• PlainID authorization in before_model_resolve
• transcript redaction in tool_result_persist
• optional prompt hints and optional experimental hooks

Build And Test

npm install
npm run build
npm test
npm run pack:check

Publish Checklist

• verify openclaw.plugin.json matches the runtime schema
• verify package.json contains openclaw.extensions, openclaw.compat, and openclaw.build
• run npm run build
• run npm test
• run npm run pack:check
• verify openclaw plugins install ./plainid-openclaw-authorizer-<version>.tgz succeeds in a clean OpenClaw state
• verify README examples for both agent-only and principal-context
• publish the package or submit it to the OpenClaw community repository

Security Notes

• keep /tools/invoke blocked publicly
• do not treat the plugin as a tenant isolation boundary
• keep shared agents sandboxed
• in principal-context mode, keep /_plainid/* private
• use agent-only for community installs unless you already operate trusted

ingress and context-upsert infrastructure

• keep experimental.enableBeforeDispatch = false unless you have verified hook coverage in your runtime
• keep experimental.enableMessageSending = false unless you have verified hook coverage in your runtime

Files Included In The Published Package

• dist/
• openclaw.plugin.json
• README.md
• LICENSE
• examples/