\n
Mandate evaluation for delegated agent authority.
\n\n When Agent A spawns Agent B with narrower permissions, OVID-ME is the thing that actually enforces those permissions at tool-call time.\n
\n\n The Problem •\n The Model •\n How It Works •\n Quick Start •\n API •\n AuthZEN PDP •\n Two-Layer Enforcement •\n Related Work\n
\n\n\n---\n\n## New here? Read this first (no background assumed)\n\n**What is this, in one sentence?** OVID-ME is a software library that checks, before an AI helper does anything, whether the helper's **ID badge** actually permits that action — and can allow, log, or block it accordingly.\n\n**The situation it fixes:** When an AI assistant hands part of a job to a smaller **helper program** (a \"sub-agent\"), that helper usually inherits *all* of the assistant's power — far more than its little task requires. A companion tool, [OVID](https://github.com/clawdreyhepburn/ovid), stamps each helper with a signed **badge** listing exactly what it may do. OVID-ME is the part that **reads that badge and enforces it** on every single action.\n\n**Plain-English glossary for the terms below:**\n\n- **Agent / sub-agent** — an automated AI worker; a sub-agent is a helper spawned by another.\n- **Mandate** — the list of allowed actions written on a helper's badge.\n- **Cedar** — a small, precise permission language (created by Amazon) used to write those rules. You rarely write it by hand when using the OpenClaw plugins.\n- **PDP / policy decision point** — industry term for \"the component that answers *is this action allowed?*\" That's what this library is.\n- **Subset proof** — a mathematical check that a helper isn't being granted more power than the helper that created it. (\"You can't give away more than you have.\")\n- **Audit log** — a permanent record of every allow/deny decision, so you can review after the fact.\n\n**The one thing to remember:** this library answers a single question, over and over — *\"does this helper's badge permit what it's trying to do right now?\"* — and records the answer. If you just want the OpenClaw plugin that wires this in automatically, see **[@clawdreyhepburn/openclaw-ovid-me](https://github.com/clawdreyhepburn/openclaw-ovid-me)**.\n\nThe rest of this README is aimed at developers integrating the library directly, and uses more precise terminology (with links to the relevant standards).\n\n---\n\n## The Problem\n\nAgent delegation is broken.\n\nWhen a primary agent spawns a sub-agent, the sub-agent typically inherits the parent's full credentials — same API keys, same OAuth tokens, same tool access. A helpdesk agent that spawns a \"check Okta attributes\" sub-agent has inadvertently created something with the power to reconfigure Active Directory. The permissions don't narrow. The context does.\n\nAuthority moves across hops, but nothing in the system ensures that scope narrows as work gets delegated. OAuth Token Exchange ([RFC 8693](https://www.rfc-editor.org/rfc/rfc8693)) can express pairwise delegation, but it wasn't built for multi-hop agent chains. It doesn't require stepwise scope narrowing. It doesn't bind tokens to specific transactions. It doesn't give you the auditability you need when the fifth agent in a chain does something the first agent never intended.\n\nOVID-ME is our answer to: **how do you actually enforce attenuated permissions at every hop?**\n\n## The Model\n\nOVID-ME builds on three ideas that already exist in standards — it just combines them for the agent delegation use case:\n\n### 1. SPIFFE-style trust: the spawner is the attestor\n\nIn [SPIFFE](https://spiffe.io/), workload identity is rooted in the platform, not in shared secrets. OVID applies the same model to agents: the thing that created a sub-agent is the thing that vouches for it. Trust is cryptographic (Ed25519 signatures) and verifiable without a central authority.\n\nEach agent gets an [OVID token](https://github.com/clawdreyhepburn/ovid) — a signed JWT that says who it is, who created it, what it's allowed to do, and when it expires. The chain is walkable back to the human. No ambient authority. No credential sharing.\n\n### 2. OAuth Token Exchange + RAR: scope narrows at every hop\n\nWhen an agent delegates to a sub-agent, it performs the equivalent of an [OAuth Token Exchange](https://www.rfc-editor.org/rfc/rfc8693) — but instead of exchanging for flat scopes, it issues an OVID with structured [Rich Authorization Requests](https://www.rfc-editor.org/rfc/rfc9396) (RFC 9396) in the `authorization_details` claim.\n\nThese aren't vague scope strings like `jira:read`. They're Cedar policies — executable, auditable, formally verifiable authorization rules:\n\n```\npermit(\n principal,\n action == Okta::Action::\"read_attribute\",\n resource == Okta::UserAttr::\"title\"\n);\n```\n\n**Lifetime can only shorten.** A child token can't outlive its parent. **Permissions can only narrow.** A child mandate must be a provable subset of the parent's effective policy. OVID-ME enforces both constraints — the first at issuance time, the second at evaluation time.\n\nThis is the \"stepwise scope narrowing\" that's missing from raw RFC 8693, and it's what [Transaction Tokens](https://datatracker.ietf.org/doc/draft-ietf-oauth-transaction-tokens/) are reaching toward for workloads. OVID-ME makes it concrete for agents.\n\n### 3. Cedar: real policy evaluation, not string matching\n\nThe mandate inside each OVID token is a Cedar policy set. [Cedar](https://www.cedarpolicy.com/) is Amazon's authorization language — deterministic, analyzable, built for exactly this kind of structured policy evaluation.\n\nOVID-ME evaluates these mandates against tool calls using native `@cedar-policy/cedar-wasm` (same family as Carapace). Default engine is `wasm` and fail-closed — the string-matcher path is an explicit `engine: \"fallback\"` opt-in only (it cannot evaluate `when`/context). Default-deny semantics. Forbid overrides permit. No ambiguity.\n\n## How It Works\n\n```\nHuman\n │ \"resolve the support ticket\"\n ▼\nPrimary Agent (OVID: full mandate)\n │\n │ issues narrower OVID via token exchange\n ▼\nSub-Agent (OVID: can only read Okta attributes)\n │\n │ calls tool: read_attribute(\"title\")\n ▼\nOVID-ME evaluates:\n ├─ Verify OVID signature chain ✓\n ├─ Extract Cedar mandate from authorization_details ✓\n ├─ Evaluate: does mandate permit this action? ✓\n └─ Decision: ALLOW\n \n │ calls tool: update_security_settings()\n ▼\nOVID-ME evaluates:\n ├─ Verify OVID signature chain ✓\n ├─ Extract Cedar mandate from authorization_details ✓\n ├─ Evaluate: does mandate permit this action? ✗\n └─ Decision: DENY → escalate to parent\n```\n\n**Three modes:**\n\n| Mode | Behavior | Use case |\n|------|----------|----------|\n| **enforce** | Deny means deny | Production |\n| **dry-run** | Evaluate + log, always allow | Testing, onboarding |\n| **shadow** | Enforce current + evaluate candidate | Policy migration |\n\n**Subset proof at issuance time:** When a parent issues an OVID to a child, OVID-ME can verify (via SMT solver or string analysis) that the child's mandate is a provable subset of the parent's effective policy. Mint fails if the child would get more authority than the parent has. This catches policy errors at delegation time, not at enforcement time.\n\n## Quick Start\n\n### Install\n\n```bash\nnpm install @clawdreyhepburn/ovid-me @clawdreyhepburn/ovid\n```\n\n**Native audit DB (optional):** SQLite auditing uses `better-sqlite3`. After a Node upgrade, if tests or the dashboard fail with a `NODE_MODULE_VERSION` / bindings error, rebuild once:\n\n```bash\nnpm run rebuild:native\n# or: npm rebuild better-sqlite3\n```\n\nIf the native addon is unavailable (e.g. `npm install --ignore-scripts`), evaluation still works; audit falls back to JSONL and the forensics dashboard stays off.\n\n**OpenClaw users:** prefer the plugins rather than wiring the library by hand:\n\n```bash\nopenclaw plugins install @clawdreyhepburn/openclaw-ovid\nopenclaw plugins install @clawdreyhepburn/openclaw-ovid-me\n# optional deployment ceiling:\nopenclaw plugins install @clawdreyhepburn/carapace\nopenclaw carapace setup\n```\n\n### Evaluate a mandate\n\n```typescript\nimport { generateKeypair, createOvid } from '@clawdreyhepburn/ovid';\nimport { MandateEngine } from '@clawdreyhepburn/ovid-me';\n\n// Parent creates a sub-agent with a narrow mandate\nconst keys = await generateKeypair();\nconst subAgent = await createOvid({\n issuerKeys: keys,\n issuer: 'primary-agent',\n mandate: {\n rarFormat: 'cedar',\n policySet: `permit(\n principal,\n action == Ovid::Action::\"read_file\",\n resource\n ) when { resource.path like \"/src/*\" };`,\n },\n});\n\n// Evaluate tool calls against the mandate\nconst engine = new MandateEngine({ mandateMode: 'enforce' });\nconst mandate = subAgent.claims.authorization_details[0];\n\n// This is allowed\nconst r1 = await engine.evaluate(subAgent.claims.jti, mandate, {\n action: 'read_file',\n resource: '/src/main.ts',\n});\n// → { decision: 'allow', mode: 'enforce' }\n\n// This is denied — not in the mandate\nconst r2 = await engine.evaluate(subAgent.claims.jti, mandate, {\n action: 'exec',\n resource: 'rm -rf /',\n});\n// → { decision: 'deny', mode: 'enforce', reason: 'no matching permit' }\n```\n\n### Configuration\n\n```typescript\nimport { resolveConfig } from '@clawdreyhepburn/ovid-me';\n\nconst config = resolveConfig({\n mandateMode: 'enforce', // 'enforce' | 'dry-run' | 'shadow'\n engine: 'wasm', // 'wasm' | 'fallback' | 'auto' (auto = wasm, fail-closed; no silent matcher)\n subsetProof: 'advisory', // 'required' | 'advisory' | 'off'\n auditLog: '~/.ovid/audit.jsonl',\n auditDb: '~/.ovid/audit.db',\n dashboardPort: 19831,\n});\n```\n\nSee [docs/CONFIG.md](docs/CONFIG.md) for deployment profiles (development, startup, enterprise).\n\n## API\n\n### MandateEngine\n\nThe core evaluation engine. Wraps Cedar evaluation with mode-aware behavior, audit logging, and optional subset proofs.\n\n```typescript\nconst engine = new MandateEngine(config?);\nconst result = await engine.evaluate(agentJti, mandate, { action, resource, context? });\n```\n\n### AuditLogger\n\nAppend-only JSONL audit log + optional SQLite database for structured queries.\n\n```typescript\nimport { createAuditLogger } from '@clawdreyhepburn/ovid-me';\n\nconst logger = createAuditLogger('./audit.jsonl');\nlogger.logDecision(agentJti, action, resource, decision, matchedPolicies);\n```\n\n### Forensics Dashboard\n\n```typescript\nimport { startDashboard } from '@clawdreyhepburn/ovid-me';\n\nconst server = await startDashboard({\n port: 19831,\n dbPath: '~/.ovid/audit.db',\n});\n// → OVID Dashboard: http://localhost:19831\n```\n\n## AuthZEN PDP\n\nOVID-ME includes an [AuthZEN](https://openid.github.io/authzen/)-compliant Policy Decision Point API, so you can integrate it with any authorization architecture that speaks the OpenID AuthZEN protocol.\n\n```typescript\nimport { AuthZenServer } from '@clawdreyhepburn/ovid-me';\n\nconst server = new AuthZenServer({\n defaultPolicy: 'permit(principal, action == Ovid::Action::\"read_file\", resource);',\n});\nawait server.start(19832);\n```\n\n```bash\n# Single evaluation\ncurl -X POST http://localhost:19832/access/v1/evaluation \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"subject\": { \"type\": \"agent\", \"id\": \"agent-47\" },\n \"action\": { \"name\": \"read_file\" },\n \"resource\": { \"type\": \"file\", \"id\": \"/src/index.ts\" }\n }'\n# → { \"decision\": true }\n\n# Batch evaluation\ncurl -X POST http://localhost:19832/access/v1/evaluations \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"evaluations\": [\n { \"subject\": {\"type\":\"agent\",\"id\":\"a1\"}, \"action\": {\"name\":\"read_file\"}, \"resource\": {\"type\":\"file\",\"id\":\"/src/index.ts\"} },\n { \"subject\": {\"type\":\"agent\",\"id\":\"a1\"}, \"action\": {\"name\":\"exec\"}, \"resource\": {\"type\":\"command\",\"id\":\"rm -rf /\"} }\n ]\n }'\n```\n\n| AuthZEN Feature | Status |\n|---------|--------|\n| Access Evaluation API (§6) | ✅ |\n| Access Evaluations API (§7) | ✅ |\n| PDP Metadata (§9) | ✅ |\n| Search APIs (§8) | ❌ (requires reverse policy analysis) |\n\n## Two-Layer Enforcement\n\nOVID-ME is one half of a two-layer authorization stack:\n\n```\nTool call arrives\n │\n ▼\n┌─────────────┐\n│ Carapace │ ← Human's ceiling. Binary allow/deny.\n│ (layer 1) │ \"No agent may ever call rm.\"\n└──────┬──────┘\n │ allowed?\n ▼\n┌─────────────┐\n│ OVID-ME │ ← Parent's mandate. Cedar evaluation.\n│ (layer 2) │ \"This agent may only read /src/*.\"\n└──────┬──────┘\n │ allowed?\n ▼\n Tool runs\n```\n\n| Layer | What it enforces | Who defines it | Runs when |\n|-------|-----------------|----------------|-----------|\n| [Carapace](https://github.com/clawdreyhepburn/carapace) | Deployment ceiling — what's allowed at all | The human | Every tool call |\n| OVID-ME | Parent mandate — what the spawner delegated | The parent agent | Every tool call |\n\nBoth must allow. A sub-agent with a broad mandate can't exceed the human's ceiling. A permissive deployment can't override a narrow mandate.\n\nCarapace implements the `PolicySource` interface, which OVID-ME queries at mandate issuance time to verify new mandates are a subset of the deployment ceiling. Policy conflicts are caught at delegation time, not at enforcement time.\n\n## Related Work\n\nOVID-ME is informed by and builds on:\n\n- **[SPIFFE](https://spiffe.io/)** — workload identity model (the spawner is the attestor)\n- **[OAuth Token Exchange (RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693)** — pairwise delegation\n- **[Rich Authorization Requests (RFC 9396)](https://www.rfc-editor.org/rfc/rfc9396)** — structured `authorization_details` claims\n- **[Transaction Tokens (draft-ietf-oauth-transaction-tokens)](https://datatracker.ietf.org/doc/draft-ietf-oauth-transaction-tokens/)** — scope-narrowing across trust domains\n- **[Cedar](https://www.cedarpolicy.com/)** — deterministic, analyzable policy evaluation\n- **[AuthZEN](https://openid.github.io/authzen/)** — interoperable authorization API\n- **[OVID](https://github.com/clawdreyhepburn/ovid)** — cryptographic agent identity (Ed25519 JWTs, delegation chains); the library that issues the badges this one evaluates\n- **[Carapace](https://github.com/clawdreyhepburn/carapace)** — deployment-level Cedar policy enforcement (the human's absolute ceiling)\n\n### The ready-to-use OpenClaw plugins\n\nIf you just want this working inside [OpenClaw](https://github.com/openclaw/openclaw) without writing code, install the plugin family rather than the libraries directly:\n\n- **[@clawdreyhepburn/openclaw-ovid](https://github.com/clawdreyhepburn/openclaw-ovid)** — issues a badge to every spawned sub-agent.\n- **[@clawdreyhepburn/openclaw-ovid-me](https://github.com/clawdreyhepburn/openclaw-ovid-me)** — the OpenClaw plugin built on *this* library; enforces those badges at every tool call.\n- **[@clawdreyhepburn/carapace](https://github.com/clawdreyhepburn/carapace)** — the human-set ceiling.\n\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}