๐Ÿ”’ OVID-ME

Mandate evaluation for delegated agent authority.

When Agent A spawns Agent B with narrower permissions, OVID-ME is the thing that actually enforces those permissions at tool-call time.

The Problem โ€ข The Model โ€ข How It Works โ€ข Quick Start โ€ข API โ€ข AuthZEN PDP โ€ข Two-Layer Enforcement โ€ข Related Work

--- ## New here? Read this first (no background assumed) **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. **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. **Plain-English glossary for the terms below:** - **Agent / sub-agent** โ€” an automated AI worker; a sub-agent is a helper spawned by another. - **Mandate** โ€” the list of allowed actions written on a helper's badge. - **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. - **PDP / policy decision point** โ€” industry term for "the component that answers *is this action allowed?*" That's what this library is. - **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.") - **Audit log** โ€” a permanent record of every allow/deny decision, so you can review after the fact. **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)**. The rest of this README is aimed at developers integrating the library directly, and uses more precise terminology (with links to the relevant standards). --- ## The Problem Agent delegation is broken. When 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. Authority 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. OVID-ME is our answer to: **how do you actually enforce attenuated permissions at every hop?** ## The Model OVID-ME builds on three ideas that already exist in standards โ€” it just combines them for the agent delegation use case: ### 1. SPIFFE-style trust: the spawner is the attestor In [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. Each 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. ### 2. OAuth Token Exchange + RAR: scope narrows at every hop When 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. These aren't vague scope strings like `jira:read`. They're Cedar policies โ€” executable, auditable, formally verifiable authorization rules: ``` permit( principal, action == Okta::Action::"read_attribute", resource == Okta::UserAttr::"title" ); ``` **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. This 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. ### 3. Cedar: real policy evaluation, not string matching The 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. OVID-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. ## How It Works ``` Human โ”‚ "resolve the support ticket" โ–ผ Primary Agent (OVID: full mandate) โ”‚ โ”‚ issues narrower OVID via token exchange โ–ผ Sub-Agent (OVID: can only read Okta attributes) โ”‚ โ”‚ calls tool: read_attribute("title") โ–ผ OVID-ME evaluates: โ”œโ”€ Verify OVID signature chain โœ“ โ”œโ”€ Extract Cedar mandate from authorization_details โœ“ โ”œโ”€ Evaluate: does mandate permit this action? โœ“ โ””โ”€ Decision: ALLOW โ”‚ calls tool: update_security_settings() โ–ผ OVID-ME evaluates: โ”œโ”€ Verify OVID signature chain โœ“ โ”œโ”€ Extract Cedar mandate from authorization_details โœ“ โ”œโ”€ Evaluate: does mandate permit this action? โœ— โ””โ”€ Decision: DENY โ†’ escalate to parent ``` **Three modes:** | Mode | Behavior | Use case | |------|----------|----------| | **enforce** | Deny means deny | Production | | **dry-run** | Evaluate + log, always allow | Testing, onboarding | | **shadow** | Enforce current + evaluate candidate | Policy migration | **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. ## Quick Start ### Install ```bash npm install @clawdreyhepburn/ovid-me @clawdreyhepburn/ovid ``` **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: ```bash npm run rebuild:native # or: npm rebuild better-sqlite3 ``` If 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. **OpenClaw users:** prefer the plugins rather than wiring the library by hand: ```bash openclaw plugins install @clawdreyhepburn/openclaw-ovid openclaw plugins install @clawdreyhepburn/openclaw-ovid-me # optional deployment ceiling: openclaw plugins install @clawdreyhepburn/carapace openclaw carapace setup ``` ### Evaluate a mandate ```typescript import { generateKeypair, createOvid } from '@clawdreyhepburn/ovid'; import { MandateEngine } from '@clawdreyhepburn/ovid-me'; // Parent creates a sub-agent with a narrow mandate const keys = await generateKeypair(); const subAgent = await createOvid({ issuerKeys: keys, issuer: 'primary-agent', mandate: { rarFormat: 'cedar', policySet: `permit( principal, action == Ovid::Action::"read_file", resource ) when { resource.path like "/src/*" };`, }, }); // Evaluate tool calls against the mandate const engine = new MandateEngine({ mandateMode: 'enforce' }); const mandate = subAgent.claims.authorization_details[0]; // This is allowed const r1 = await engine.evaluate(subAgent.claims.jti, mandate, { action: 'read_file', resource: '/src/main.ts', }); // โ†’ { decision: 'allow', mode: 'enforce' } // This is denied โ€” not in the mandate const r2 = await engine.evaluate(subAgent.claims.jti, mandate, { action: 'exec', resource: 'rm -rf /', }); // โ†’ { decision: 'deny', mode: 'enforce', reason: 'no matching permit' } ``` ### Configuration ```typescript import { resolveConfig } from '@clawdreyhepburn/ovid-me'; const config = resolveConfig({ mandateMode: 'enforce', // 'enforce' | 'dry-run' | 'shadow' engine: 'wasm', // 'wasm' | 'fallback' | 'auto' (auto = wasm, fail-closed; no silent matcher) subsetProof: 'advisory', // 'required' | 'advisory' | 'off' auditLog: '~/.ovid/audit.jsonl', auditDb: '~/.ovid/audit.db', dashboardPort: 19831, }); ``` See [docs/CONFIG.md](docs/CONFIG.md) for deployment profiles (development, startup, enterprise). ## API ### MandateEngine The core evaluation engine. Wraps Cedar evaluation with mode-aware behavior, audit logging, and optional subset proofs. ```typescript const engine = new MandateEngine(config?); const result = await engine.evaluate(agentJti, mandate, { action, resource, context? }); ``` ### AuditLogger Append-only JSONL audit log + optional SQLite database for structured queries. ```typescript import { createAuditLogger } from '@clawdreyhepburn/ovid-me'; const logger = createAuditLogger('./audit.jsonl'); logger.logDecision(agentJti, action, resource, decision, matchedPolicies); ``` ### Forensics Dashboard ```typescript import { startDashboard } from '@clawdreyhepburn/ovid-me'; const server = await startDashboard({ port: 19831, dbPath: '~/.ovid/audit.db', }); // โ†’ OVID Dashboard: http://localhost:19831 ``` ## AuthZEN PDP OVID-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. ```typescript import { AuthZenServer } from '@clawdreyhepburn/ovid-me'; const server = new AuthZenServer({ defaultPolicy: 'permit(principal, action == Ovid::Action::"read_file", resource);', }); await server.start(19832); ``` ```bash # Single evaluation curl -X POST http://localhost:19832/access/v1/evaluation \ -H "Content-Type: application/json" \ -d '{ "subject": { "type": "agent", "id": "agent-47" }, "action": { "name": "read_file" }, "resource": { "type": "file", "id": "/src/index.ts" } }' # โ†’ { "decision": true } # Batch evaluation curl -X POST http://localhost:19832/access/v1/evaluations \ -H "Content-Type: application/json" \ -d '{ "evaluations": [ { "subject": {"type":"agent","id":"a1"}, "action": {"name":"read_file"}, "resource": {"type":"file","id":"/src/index.ts"} }, { "subject": {"type":"agent","id":"a1"}, "action": {"name":"exec"}, "resource": {"type":"command","id":"rm -rf /"} } ] }' ``` | AuthZEN Feature | Status | |---------|--------| | Access Evaluation API (ยง6) | โœ… | | Access Evaluations API (ยง7) | โœ… | | PDP Metadata (ยง9) | โœ… | | Search APIs (ยง8) | โŒ (requires reverse policy analysis) | ## Two-Layer Enforcement OVID-ME is one half of a two-layer authorization stack: ``` Tool call arrives โ”‚ โ–ผ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ Carapace โ”‚ โ† Human's ceiling. Binary allow/deny. โ”‚ (layer 1) โ”‚ "No agent may ever call rm." โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ allowed? โ–ผ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ OVID-ME โ”‚ โ† Parent's mandate. Cedar evaluation. โ”‚ (layer 2) โ”‚ "This agent may only read /src/*." โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ allowed? โ–ผ Tool runs ``` | Layer | What it enforces | Who defines it | Runs when | |-------|-----------------|----------------|-----------| | [Carapace](https://github.com/clawdreyhepburn/carapace) | Deployment ceiling โ€” what's allowed at all | The human | Every tool call | | OVID-ME | Parent mandate โ€” what the spawner delegated | The parent agent | Every tool call | Both 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. Carapace 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. ## Related Work OVID-ME is informed by and builds on: - **[SPIFFE](https://spiffe.io/)** โ€” workload identity model (the spawner is the attestor) - **[OAuth Token Exchange (RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693)** โ€” pairwise delegation - **[Rich Authorization Requests (RFC 9396)](https://www.rfc-editor.org/rfc/rfc9396)** โ€” structured `authorization_details` claims - **[Transaction Tokens (draft-ietf-oauth-transaction-tokens)](https://datatracker.ietf.org/doc/draft-ietf-oauth-transaction-tokens/)** โ€” scope-narrowing across trust domains - **[Cedar](https://www.cedarpolicy.com/)** โ€” deterministic, analyzable policy evaluation - **[AuthZEN](https://openid.github.io/authzen/)** โ€” interoperable authorization API - **[OVID](https://github.com/clawdreyhepburn/ovid)** โ€” cryptographic agent identity (Ed25519 JWTs, delegation chains); the library that issues the badges this one evaluates - **[Carapace](https://github.com/clawdreyhepburn/carapace)** โ€” deployment-level Cedar policy enforcement (the human's absolute ceiling) ### The ready-to-use OpenClaw plugins If you just want this working inside [OpenClaw](https://github.com/openclaw/openclaw) without writing code, install the plugin family rather than the libraries directly: - **[@clawdreyhepburn/openclaw-ovid](https://github.com/clawdreyhepburn/openclaw-ovid)** โ€” issues a badge to every spawned sub-agent. - **[@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. - **[@clawdreyhepburn/carapace](https://github.com/clawdreyhepburn/carapace)** โ€” the human-set ceiling. ## License Apache-2.0