agent-passport-system-openclaw-plugin

OpenClaw plugin: Agent Passport System trust verification provider. Reference implementation of Agent Trust Verification Provider Pattern v0.1.

The plugin gates skill installs against the APS public trust registry, gates high-risk tool calls behind explicit approval, and exposes APS primitives (grade lookup, delegation verification, message signing) via OpenClaw gateway RPC. It runs entirely in the OpenClaw plugin lifecycle and adds no requirement on OpenClaw core.

Install

clawhub install agent-passport-system-openclaw-plugin
# or
npm install agent-passport-system-openclaw-plugin

Configuration

Config is read from, in order:

1. $OPENCLAW_APS_CONFIG_PATH (env var)
2. ~/.openclaw/aps.config.json
3. Built-in defaults (permissive-with-warnings)

Schema (matches spec section 8):

{
  "provider": "aps",
  "endpoints": {
    "verifier": "https://gateway.aeoess.com/api/v1/public/trust",
    "jwks": "https://gateway.aeoess.com/.well-known/jwks.json"
  },
  "credentials": { "passportPath": "~/.openclaw/aps-credentials.json" },
  "policy": {
    "skillAuthor": { "minGrade": 0, "warnBelow": 1, "blockBelow": null },
    "toolCalls": { "enforceScope": true, "highRiskTools": ["bash", "exec", "fetch"], "highRiskBehavior": "approval" },
    "inboundMessages": { "requireSignature": false, "warnUnsigned": true }
  }
}

Hook coverage (v0.1)

Gateway RPC methods

Exposed via api.registerGatewayMethod(), namespaced aps.:

• aps.checkGrade(agentId) → TrustProfile | null from the public APS gateway
• aps.verifyDelegation(token) → result of APS SDK verifyDelegation()
• aps.signMessage(payload) → Ed25519 signature using local passport's private key

Other plugins can call these by their namespaced names.

Conformance

This plugin claims conformance to Agent Trust Verification Provider Pattern v0.1. Specifically:

• ✅ Registers before_install, before_tool_call, gateway_start (criterion 1)
• ✅ Accepts the section-8 configuration schema (criterion 2)
• ✅ Defaults to permissive-with-warnings (criterion 3)
• ✅ Handles missing-author and missing-credential without crash (criterion 4)
• ✅ Cold-case before_tool_call is in-process — no gateway call in v0.1 (criterion 5)
• ✅ All gateway RPC methods namespaced aps. (criterion 6)
• ⏸ before_dispatch headers — deferred to v0.2 (criterion 7 N/A in v0.1)
• ✅ No state mutation outside plugin directory (criterion 8)
• ✅ Verifier endpoint published at gateway.aeoess.com/api/v1/public/trust/{agentId} (criterion 9)
• ✅ Trust signal semantics documented in The Agent Social Contract (criterion 10)

v0.1 scope and known limitations

• High-risk-tool gate is the only before_tool_call enforcement. Full delegation-scope verification requires the agent to be running with an APS passport context; that ships in v0.2 with caching to keep the typical-case latency under 100ms (spec section 9 #5).
• inbound_claim and before_dispatch deferred. The agent runtime context for inter-agent messaging is still being formalized; v0.2 adds these hooks once the surface is stable.
• Author identifier extraction is best-effort. OpenClaw hook event types at commit 45146913007d do not expose author on event.skill or event.plugin. The plugin reads author if present (forward-compat), falls back to npm scope from packageName for plugins, and treats local archives without a derivable author as missing-author (warning, not block).
• No retry layer. If the gateway is slow (>500ms) the install proceeds with a warning. Caching of grade lookups is also a v0.2 item.

Examples

Default (permissive-with-warnings)

No config file needed. The defaults block nothing, surface warnings for unknown or low-grade authors, and require user approval for bash/exec/fetch.

Strict mode

{
  "provider": "aps",
  "policy": {
    "skillAuthor": { "minGrade": 0, "warnBelow": 2, "blockBelow": 1 },
    "toolCalls": { "enforceScope": true, "highRiskTools": ["bash", "exec", "fetch", "shell"], "highRiskBehavior": "block" },
    "inboundMessages": { "requireSignature": true, "warnUnsigned": false }
  }
}

Place at ~/.openclaw/aps.config.json or set $OPENCLAW_APS_CONFIG_PATH to its location.

Development

npm install
npm run build      # tsc -> dist/
npm test           # vitest
npm run lint       # tsc --noEmit --strict --noUnusedLocals --noUnusedParameters

To link locally into an OpenClaw checkout:

cd /path/to/openclaw-plugin-aps && npm link
cd /path/to/openclaw && npm link agent-passport-system-openclaw-plugin

License

Apache-2.0. Copyright 2026 Tymofii Pidlisnyi.