Tools
Gateproof Openclaw
By GateProof plugin for OpenClaw with local receipts, trust-based authorization, target ranking, and optional sharing
Install
npm install
```Configuration Example
{
"pattern": "^exec$",
"contextTag": "gateproof:ctx:code-exec",
"capability": "code-exec",
"taskType": "command_execution",
"riskTier": "high",
"constraints": {
"ttlSeconds": 60
}
}README
# GateProof OpenClaw
GateProof plugin for OpenClaw. The plugin is local-first:
- signed `gateproof-receipt` receipts for all observed mapped calls
- receipt-derived local authorization with `ALLOW` / `DENY` / `ESCALATE`
- local `why` explanations and candidate ranking
- local trust workflows for target overrides and trusted emitters
- async aggregate, receipt, or receipt-invalidation upload queue with redaction-aware previews
## Step-by-step setup in OpenClaw
1. Place this repo where OpenClaw can load it, for example `./plugin-openclaw` relative to your OpenClaw config.
2. Install the plugin dependencies:
```bash
cd plugin-openclaw
npm install
```
3. Create your tool map from [tool_map.example.json](./tool_map.example.json) and adjust the regex patterns to match the OpenClaw tool names you actually use.
```bash
cp tool_map.example.json tool_map.json
```
4. Add the plugin to your OpenClaw config. A minimal starting point looks like this:
```json5
{
plugins: {
load: {
paths: ["./plugin-openclaw"]
},
entries: {
"gateproof-openclaw": {
enabled: true,
config: {
decider: "0xDECIDER...",
toolMapPath: "./plugin-openclaw/tool_map.json",
trustStorePath: "./.gateproof/local-trust.db",
receiptOutDir: "./.gateproof/receipts",
receiptSignerKeyPath: "./.gateproof/receipt-signer.ed25519.key",
sharing: {
mode: "local_only"
}
}
}
}
}
}
```
See [config.example.json5](./config.example.json5) for the full configuration surface.
5. Start OpenClaw with that config.
6. Run a mapped tool once. The plugin will evaluate the call in `before_tool_call`, emit a signed receipt in `after_tool_call`, and attach GateProof metadata during `tool_result_persist`.
7. Verify the plugin is active:
- confirm `trustStorePath` exists and contains the local GateProof SQLite store
- confirm `receiptOutDir` contains JSON receipts if you enabled local receipt output
- use `gateproofAuthorizeAction`, `gateproofWhyAction`, or `gateproofUploadAction` to inspect decisions, explanations, and sharing state
8. After local-only mode is working, optionally enable sharing by setting `sharing.mode` to `aggregate` or `receipt` and configuring `apiBaseUrl` plus any `workspaceId` or redaction rules you need.
## Local store
The SQLite trust store keeps:
- `receipts`
- `receipt_invalidations`
- `normalized_signals`
- `policy_events`
- `target_aliases`
- `trusted_emitters`
- `upload_queue`
- `trust_cache`
- `agents`
- `workflow_tickets`
Receipts and normalized signals are the primary source of truth.
## Runtime hooks
Normal OpenClaw execution uses:
- `before_tool_call`: local authorize from receipt-derived signals
- `after_tool_call`: emit and persist a signed receipt plus normalized signal
- `tool_result_persist`: attach GateProof metadata to the persisted tool result
Manual control actions available through hook payloads:
- `gateproofAuthorizeAction`: explicit local authorize query
- `gateproofWhyAction`: explicit local why query
- `gateproofRankAction`: rank candidate targets from local evidence
- `gateproofIdentityAction`: explicit target identity link / status
- `gateproofReceiptAction`: local receipt status / invalidation
- `gateproofUploadAction`: upload queue status / preview / flush
- `gateproofTrustAction`: trust workflow actions (`trust`, `block`, `endorse`, `status`, `confirm`, `cancel`)
- `gateproofAgentCardAction`: Agent Card import / status
## Configuration
See [config.example.json5](./config.example.json5) and [tool_map.example.json](./tool_map.example.json).
Key config points:
- `decider`: stable local decider identifier; emitted receipt `emitterId` is bound to the signer key as `<emitterType>:<decider>@<keyId>`
- `tenantId`: optional tenant/workspace identity carried in emitted receipts
- `emitterType`: runtime identity class (`runtime`, `gateway`, `device`, `service`)
- `emitterVerificationLevel`: emitter verification tier (`self_asserted`, `verified`, `attested`)
- `toolMapPath`: tool-to-context mapping
- `trustStorePath`: SQLite store location
- `receiptOutDir`: optional local JSON receipt copies
- `sharing.mode`: `local_only`, `aggregate`, or `receipt`
- `trustCircles`: which emitters count locally
- `retention`: optional local pruning policy for receipts, queue entries, and cached trust snapshots
`apiBaseUrl` is optional. It is only used to flush queued uploads to `/receipts`, `/receipt-invalidations`, or `/aggregates`.
## Tool map format
Each entry is GateProof-native:
```json
{
"pattern": "^exec$",
"contextTag": "gateproof:ctx:code-exec",
"capability": "code-exec",
"taskType": "command_execution",
"riskTier": "high",
"constraints": {
"ttlSeconds": 60
}
}
```
`contextTag` is required. `contextId` is not used.
## Sharing modes
- `local_only`: default; no upload leaves the runtime
- `aggregate`: queue aggregate snapshots for `/aggregates`
- `receipt`: queue redaction-aware full receipts for `/receipts` plus signed invalidations for `/receipt-invalidations`
Uploads are asynchronous relative to the tool execution path.
`receipt` mode preserves the original signed receipt payload. If a privacy rule would require mutating a signed field such as `target.targetRef`, or if the stored receipt was signed under different sharing metadata, the plugin marks that receipt preview as unshareable instead of uploading an invalid or rewritten signed artifact. Upload previews also fail closed when the active sharing policy would not actually upload that context. Use `aggregate` mode when `target_ref` redaction is required.
## Query policy surface
`gateproofAuthorizeAction`, `gateproofWhyAction`, and `gateproofRankAction` accept policy/view hints in addition to the context fields:
- `view`: requested trust view, default `local`
- `fallbackBehavior`: `allow_local_fallback` or `require_exact_view`
- `objective`: `safest_choice`, `best_quality_under_budget`, `fastest_acceptable_provider`, or `lowest_cost_acceptable_provider`
- `allowScore`, `allowConfidence`, `askScore`, `askConfidence`
- `minSampleSizeToAllow`, `requiredEvidenceFreshnessMs`, `maxSignalAgeMs`
- `grantTtlSeconds`, `scope`, `amountCapUsd`
When a non-local view is requested, the plugin either falls back explicitly to the local view or returns an unavailable result, depending on `fallbackBehavior`.
`gateproofAuthorizeAction` also supports a separate requested action payload:
```json
{
"targetPrincipalId": "0xagent",
"contextTag": "gateproof:ctx:payments",
"action": {
"actionType": "payment",
"amountUsd": 45,
"scope": {
"repo": "example/repo",
"branch": "main"
}
},
"policy": {
"amountCapUsd": 50,
"scope": {
"repo": "example/repo",
"branch": "main"
}
}
}
```
If `policy.scope` or `policy.amountCapUsd` is set, the plugin evaluates the requested `action` before returning `ALLOW`.
## Retention
Optional `retention` config can prune local data automatically:
- `receiptsDays`
- `uploadsDays`
- `trustCacheDays`
This gives the plugin a basic local deletion/expiration hook for privacy-sensitive deployments.
## Trust workflows
`gateproofTrustAction` supports:
- `trust`: create a positive local policy override event for a target/context
- `block`: create a deny local policy override event for a target/context
- `endorse`: add an emitter to a local trust circle
- `status`: show current local authorize state and trusted emitters
- `confirm` / `cancel`: resolve a confirmation ticket
All mutations require confirmation and are stored durably in `workflow_tickets`.
## Validation
```bash
cd /Users/ogi/dev/gateproof-openclaw
npm run lint
npm run typecheck
npm test
```
tools
Comments
Sign in to leave a comment