Tools
Authorizer
By PlainID authorization plugin for OpenClaw with principal-context and agent-only modes
Install
npm install @plainid/openclaw-authorizerREADME
# `@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
```bash
npm install @plainid/openclaw-authorizer
```
Load it from your OpenClaw config:
```json5
{
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:
```json5
{
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:
```json5
{
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](./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](./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:
```json5
{
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
```bash
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/`
tools
Comments
Sign in to leave a comment