diff --git a/docs/policy-engine-implementation.md b/docs/policy-engine-implementation.md new file mode 100644 index 00000000..4866de76 --- /dev/null +++ b/docs/policy-engine-implementation.md @@ -0,0 +1,139 @@ +# Policy Engine Implementation Guide + +> A practical guide for implementing and integrating the OWS policy engine. +> For the normative specification, see [03-policy-engine.md](03-policy-engine.md). + +## Overview + +The policy engine gates every agent signing request before any key material +is touched. This guide covers: creating policies, attaching them to API keys, +writing custom executable policies, and testing policy decisions. + +## 1. Your First Policy + +Create a policy JSON file and register it: + + # my-first-policy.json + { + "id": "my-first-policy", + "name": "Restrict to Base mainnet", + "version": 1, + "created_at": "2026-01-01T00:00:00Z", + "rules": [ + { "type": "allowed_chains", "chain_ids": ["eip155:8453"] } + ], + "action": "deny" + } + + ows policy create --file my-first-policy.json + ows key create --name "my-agent" --wallet my-wallet --policy my-first-policy + +## 2. Common Policy Patterns + +### Time-limited access + + { "type": "expires_at", "timestamp": "2026-12-31T23:59:59Z" } + +### Chain restriction + expiry + + { + "id": "base-limits", + "name": "Base Agent Safety Limits", + "version": 1, + "created_at": "2026-01-01T00:00:00Z", + "rules": [ + { "type": "allowed_chains", "chain_ids": ["eip155:8453", "eip155:84532"] }, + { "type": "expires_at", "timestamp": "2026-12-31T23:59:59Z" } + ], + "action": "deny" + } + +### EIP-712 contract restriction + + { + "type": "allowed_typed_data_contracts", + "contracts": ["0x000000000022D473030F116dDEE9F6B43aC78BA3"] + } + +## 3. Multiple Policies on One Key + +All attached policies must allow (AND semantics): + + ows key create --name "agent" --wallet treasury --policy base-limits --policy permit2-only + +## 4. Custom Executable Policies + +Use executables for spending limits, on-chain simulation, or external API calls. +The executable receives PolicyContext JSON on stdin and must write PolicyResult to stdout. + +Minimal Python example: + + import json, sys + ctx = json.load(sys.stdin) + value = int(ctx["transaction"].get("value", "0")) + limit = 10_000_000_000_000_000 # 0.01 ETH + if value > limit: + json.dump({"allow": False, "reason": "Value exceeds limit"}, sys.stdout) + else: + json.dump({"allow": True}, sys.stdout) + +Reference it in the policy file: + + { + "id": "value-limit", + "name": "Max 0.01 ETH per transaction", + "version": 1, + "created_at": "2026-01-01T00:00:00Z", + "rules": [{ "type": "allowed_chains", "chain_ids": ["eip155:8453"] }], + "executable": "/home/user/.ows/plugins/policies/value-limit.py", + "action": "deny" + } + +## 5. PolicyContext Fields + +| Field | Description | +|---|---| +| chain_id | CAIP-2 chain ID (e.g. eip155:8453) | +| wallet_id | Wallet UUID | +| api_key_id | API key UUID | +| transaction.to | Recipient address (EVM) | +| transaction.value | Value in wei as string | +| transaction.data | Calldata hex | +| transaction.raw_hex | Raw unsigned transaction hex | +| spending.daily_total | Cumulative value signed today (wei) | +| timestamp | ISO-8601 signing request time | + +## 6. Testing Policies + +Test executable policies without real signing: + + echo '{"chain_id": "eip155:8453", "wallet_id": "test", "api_key_id": "test", + "transaction": {"to": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD0C", + "value": "5000000000000000", "raw_hex": "0x", "data": "0x"}, + "spending": {"daily_total": "0", "date": "2026-01-01"}, + "timestamp": "2026-01-01T00:00:00Z"}' | python3 value-limit.py + +## 7. Failure Semantics + +The policy engine fails closed. Any failure results in denial: + +| Scenario | Result | +|---|---| +| Executable not found | Deny | +| Executable exits non-zero | Deny | +| Executable returns invalid JSON | Deny | +| Executable times out (5s) | Deny | +| Unknown declarative rule type | Deny | + +## 8. Managing Policies via CLI + + ows policy list + ows policy show --id base-limits + ows policy delete --id base-limits + ows key list + +## References + +- [03-policy-engine.md](03-policy-engine.md) - Normative policy engine specification +- [04-agent-access-layer.md](04-agent-access-layer.md) - Agent access and API key management +- [05-key-isolation.md](05-key-isolation.md) - Key isolation and HD derivation