@kevros/openclaw-plugin

Cryptographic policy enforcement for agent tool calls via the Kevros governance gateway.

Every action verified. Every decision signed. Every record hash-chained.

What it does

This plugin intercepts agent tool calls and enforces governance policy before execution:

1. before_tool_call -- Calls POST /governance/verify for high-risk tools. Returns ALLOW, CLAMP, or DENY with a cryptographic release token.
2. after_tool_call -- Calls POST /governance/attest after execution, building a hash-chained provenance record for the agent.

The plugin also registers two callable tools:

• kevros_verify -- Verify any action against governance policy on demand.
• kevros_passport -- Look up an agent's trust passport (score, tier, badges).

Installation

npm install @kevros/openclaw-plugin

Configuration

Add to your OpenClaw configuration:

{
  "plugins": [
    {
      "name": "kevros-governance",
      "config": {
        "gatewayUrl": "https://governance.taskhawktech.com",
        "apiKey": "your-api-key",
        "agentId": "my-agent",
        "mode": "enforce",
        "highRiskTools": ["bash", "computer", "terminal", "exec", "write_file", "edit_file"],
        "autoAttest": true
      }
    }
  ]
}

Configuration options

| Option | Type | Default | Description | |--------|------|---------|-------------| | gatewayUrl | string | https://governance.taskhawktech.com | Kevros gateway base URL | | apiKey | string | (auto-provisions) | API key. If not set, the plugin auto-signs up for a free tier key (1,000 calls/month) | | agentId | string | hostname | Agent identifier for governance tracking | | mode | string | enforce | enforce (fail-closed), advisory (log-only), or deny (block all) | | highRiskTools | string[] | ["bash", "computer", ...] | Tool names requiring governance verification | | autoAttest | boolean | true | Automatically attest tool executions after completion |

Enforcement modes

enforce (default)

Fail-closed. If the gateway returns DENY, the tool call is blocked. If the gateway is unreachable, the tool call is blocked. This is the recommended mode for production.

advisory

Fail-open. All decisions are logged but never enforced. Use this to evaluate governance impact before switching to enforce.

deny

Hard block. All high-risk tool calls are unconditionally blocked regardless of gateway state. Use this as a kill-switch.

Auto-provisioning

If no apiKey is configured, the plugin automatically calls POST /signup on first use to provision a free-tier API key:

• 1,000 governance calls per month
• 10 requests per minute rate limit
• No credit card or email required

The key is cached in memory for the duration of the session. For persistent usage, set the apiKey in your configuration after signup.

How verification works

When a high-risk tool is called:

Agent calls bash("rm -rf /tmp/data")
    |
    v
before_tool_call hook fires
    |
    v
POST /governance/verify
  action_type: "tool:bash"
  action_payload: { tool: "bash", input: { command: "rm -rf /tmp/data" } }
    |
    v
Gateway returns: { decision: "ALLOW", release_token: "abc123...", epoch: 42 }
    |
    v
Tool executes
    |
    v
after_tool_call hook fires
    |
    v
POST /governance/attest
  action_description: "Executed tool: bash"
  action_payload: { tool: "bash", input: {...}, output_summary: "...", release_token: "abc123..." }
    |
    v
Hash-chained provenance record created (epoch 43)

Using the tools

The plugin registers two tools that agents can call directly:

kevros_verify

kevros_verify({
  action_type: "api_call",
  action_payload: { endpoint: "/users", method: "DELETE", user_id: "123" }
})

Returns the verification decision, reason, and release token.

kevros_passport

kevros_passport({ agent_id: "some-agent" })

Returns trust score, tier, badges, verification/attestation counts, and chain integrity status.

Requirements

• Node.js 18+ (uses native fetch)
• Zero runtime dependencies

Building from source

npm install
npm run build

License

MIT