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, 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.

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) 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, 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 — 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 — but instead of exchanging for flat scopes, it issues an OVID with structured Rich Authorization Requests (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 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 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

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:

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:

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

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

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 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.

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.

import { createAuditLogger } from '@clawdreyhepburn/ovid-me';

const logger = createAuditLogger('./audit.jsonl');
logger.logDecision(agentJti, action, resource, decision, matchedPolicies);

Forensics Dashboard

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-compliant Policy Decision Point API, so you can integrate it with any authorization architecture that speaks the OpenID AuthZEN protocol.

import { AuthZenServer } from '@clawdreyhepburn/ovid-me';

const server = new AuthZenServer({
  defaultPolicy: 'permit(principal, action == Ovid::Action::"read_file", resource);',
});
await server.start(19832);

# 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 | 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 — workload identity model (the spawner is the attestor)
• OAuth Token Exchange (RFC 8693) — pairwise delegation
• Rich Authorization Requests (RFC 9396) — structured authorization_details claims
• Transaction Tokens (draft-ietf-oauth-transaction-tokens) — scope-narrowing across trust domains
• Cedar — deterministic, analyzable policy evaluation
• AuthZEN — interoperable authorization API
• OVID — cryptographic agent identity (Ed25519 JWTs, delegation chains); the library that issues the badges this one evaluates
• 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 without writing code, install the plugin family rather than the libraries directly:

• @clawdreyhepburn/openclaw-ovid — issues a badge to every spawned sub-agent.
• @clawdreyhepburn/openclaw-ovid-me — the OpenClaw plugin built on this library; enforces those badges at every tool call.
• @clawdreyhepburn/carapace — the human-set ceiling.

License

Apache-2.0