\n
Cryptographic identity for AI agents.
\n\n Ed25519 signed JWTs with delegation chains — tells you exactly who a sub-agent is, who created it, and when it expires.\n
\n\n The Problem •\n How It Works •\n Quick Start •\n API •\n Mandate Evaluation •\n Security Guide •\n FAQ\n
\n\n\n---\n\n## New here? Read this first (no background assumed)\n\n**What is this, in one sentence?** OVID is a small software library that gives each automated AI helper its own tamper-proof **ID badge**, so you always know who a helper is, who created it, what it's allowed to do, and when its access expires.\n\n**Why does that matter?** When an AI assistant is given a big job, it often spawns smaller **helper programs** (\"sub-agents\") to handle pieces of it. By default, each helper inherits *all* the power of the thing that created it — like handing a house-painter the keys to your house, car, and bank account when they only needed one room. OVID replaces that with a specific, limited, unforgeable badge for each helper.\n\n**A few terms you'll see, in plain English:**\n\n- **Agent / sub-agent** — an automated AI worker. A \"sub-agent\" is a helper spawned by another agent.\n- **Badge / identity document / \"OVID\"** — a small signed file that proves who a helper is and what it may do. (OVID = **O**penClaw **V**erifiable **I**dentity **D**ocument.)\n- **Mandate** — the list of allowed actions printed on the badge.\n- **Signing / cryptographic signature** — unforgeable digital math (the same kind that secures websites) that makes a badge impossible to fake or alter.\n- **Chain** — because a helper can spawn its own helper, badges link together in a traceable chain leading back to you, the human.\n- **JWT** — a common, standard file format for signed digital tokens. An OVID badge *is* a JWT with some extra fields. You don't need to know the format to use the library.\n\n**What OVID does and doesn't do:** OVID *issues and verifies* badges (identity + expiry + traceability). It does **not** by itself stop a helper from misbehaving — that enforcement is a separate, companion job. See [How OVID Fits the Stack](#how-ovid-fits-the-stack). Think: OVID prints and validates the ID card; a separate security desk checks it at every door.\n\nThe rest of this README goes deeper and is aimed at developers integrating the library. If you just want the OpenClaw plugin that does all of this automatically, see **[@clawdreyhepburn/openclaw-ovid](https://github.com/clawdreyhepburn/openclaw-ovid)**.\n\n---\n\n## The Problem\n\nWhen an AI agent spawns a sub-agent, the sub-agent inherits everything — API keys, credentials, tool access, filesystem. The code reviewer has a credit card. The browser worker can send tweets. The research agent can read every file on the machine.\n\nThis is [ambient authority](https://en.wikipedia.org/wiki/Ambient_authority), and it's the same mistake we made with Unix root shells, shared browser cookies, and unsandboxed containers. The fix has always been the same: **explicit, attenuated credentials.**\n\nOVID gives every sub-agent its own identity document — a signed JWT that says who it is, what mandate it carries, who created it, and when it expires. The spawning agent signs it. The chain is verifiable back to the human.\n\nRead more: [Your Sub-Agents Are Running With Scissors](https://clawdrey.com/blog/your-sub-agents-are-running-with-scissors.html)\n\n## How It Works\n\n```\nHuman (root of trust)\n │\n │ delegates authority to\n ▼\nPrimary Agent (long-lived, has keypair)\n │\n │ issues OVID to\n ▼\nSub-Agent (ephemeral, carries OVID JWT with Cedar mandate)\n │\n │ can issue derived OVID to\n ▼\nSub-Sub-Agent (shorter lifetime, auditable chain)\n```\n\n**Four principles:**\n\n1. **The spawner is the attestor.** You trust a sub-agent because you trust the thing that created it — and that trust is cryptographically verifiable.\n2. **Lifetime can only shorten.** A child's OVID can't outlive its parent's. When the parent expires, everything downstream expires.\n3. **Identity is self-contained.** An OVID carries everything needed for verification. No database. No central server. No network calls.\n4. **The chain is the proof.** Each OVID embeds its full parent chain of cryptographic attestations. Walk it back to the root and verify every signature against a trusted root public key. No intermediate JWTs required.\n\n### What OVID verifies — and what it doesn't\n\nOVID is an **identity and lifetime** layer. A successful `verifyOvid` proves:\n\n- The leaf agent's keypair was attested by the chain of parents back to a\n trusted root.\n- Every `iat`/`exp` along the chain is internally consistent (lifetimes can\n only shorten, and the JWT's `iat` cannot predate the parent's attestation).\n- The JWT was authored by the leaf's own keypair (not forged by a sibling).\n- The token has not yet expired.\n\nOVID does **not** verify:\n\n- **Mandate attenuation.** OVID will happily sign a chain where a child's\n `policySet` is broader than its parent's. A rogue parent can mint a\n wide-open child token if it wants to. Enforcing that children only receive\n a subset of their parent's authority is the job of\n [`@clawdreyhepburn/ovid-me`](https://github.com/clawdreyhepburn/ovid-me)\n (or any policy engine that consumes the verified mandate). Use OVID for\n identity, OVID-ME for policy evaluation and subset proof.\n- **Resource authorization.** OVID carries a Cedar policy set but doesn't\n evaluate it. Pass the verified mandate to Cedar (Cedarling, OVID-ME, etc.)\n to make an allow/deny decision for any specific action.\n\n## Quick Start\n\n### Install\n\n```bash\nnpm install @clawdreyhepburn/ovid\n```\n\n### Issue an OVID\n\n```typescript\nimport { generateKeypair, createOvid } from '@clawdreyhepburn/ovid';\n\n// Primary agent creates a keypair (do this once, persist it)\nconst primaryKeys = await generateKeypair();\n\n// Spawn a sub-agent with a signed identity and Cedar mandate\nconst reviewer = await createOvid({\n issuerKeys: primaryKeys,\n issuer: 'clawdrey',\n mandate: {\n rarFormat: 'cedar',\n policySet: 'permit(principal, action == Ovid::Action::\"read_file\", resource);',\n },\n ttlSeconds: 1800, // 30 minutes\n});\n\nconsole.log(reviewer.jwt); // standard JWT string\nconsole.log(reviewer.claims.authorization_details[0].policySet); // Cedar policy\n// In v0.4.0+, parent_chain is a ChainLink[] with cryptographic attestations.\n// A root token has exactly one self-signed link (binding its own agent_pub).\nconsole.log(reviewer.claims.authorization_details[0].parent_chain);\n```\n\n### Verify an OVID\n\n```typescript\nimport { verifyOvid } from '@clawdreyhepburn/ovid';\n\n// Preferred: options form with trustedRoots (v0.4.0+).\nconst result = await verifyOvid(reviewer.jwt, {\n trustedRoots: [primaryKeys.publicKey],\n maxChainDepth: 5, // optional, defaults to 5\n});\n\nif (result.valid) {\n console.log(result.principal); // \"clawdrey/agent-7f3a\"\n console.log(result.mandate); // { type, rarFormat, policySet, ... }\n console.log(result.chain); // [\"clawdrey/agent-7f3a\"] — flattened sub list\n console.log(result.expiresIn); // seconds until expiry\n}\n\n// Legacy single-key overload (deprecated, emits console warning):\n// const result = await verifyOvid(reviewer.jwt, primaryKeys.publicKey);\n```\n\n### Delegation chains\n\nSub-agents can issue OVIDs to their own sub-agents:\n\n```typescript\nconst helper = await createOvid({\n issuerKeys: reviewer.keys,\n issuerOvid: reviewer,\n mandate: {\n rarFormat: 'cedar',\n policySet: 'permit(principal, action == Ovid::Action::\"read_file\", resource);',\n },\n ttlSeconds: 600, // shorter than parent ✅\n});\n\n// v0.4.0: parent_chain is ChainLink[] with root first, leaf last.\nconst chain = helper.claims.authorization_details[0].parent_chain;\nconsole.log(chain.length); // 2\nconsole.log(chain[0].sub); // root's sub (e.g. \"clawdrey\")\nconsole.log(chain[1].sub); // helper's sub\n// Each link carries { sub, agent_pub, iat, exp, sig } — the parent's signed\n// attestation binding the child's identity.\n```\n\n### Chain verification (v0.4.0+)\n\nEach delegation step emits a **ChainLink**: a compact signed attestation from\nthe parent binding the child's identity. The verifier walks the chain from\nleaf to root, verifying each link's signature against the preceding link's\n`agent_pub`, and anchors the root link against a caller-supplied set of\ntrusted root public keys.\n\nA `ChainLink` is:\n\n```typescript\ninterface ChainLink {\n sub: string; // the agent this link represents\n agent_pub: string; // base64url Ed25519 pubkey bound to sub\n iat: number; // issue time (unix seconds)\n exp: number; // expiry (unix seconds)\n sig: string; // base64url Ed25519 sig by PARENT over canonical bytes\n}\n```\n\nThe signature covers this exact byte string (UTF-8):\n\n```\novid-chain-link/v1\\n\\n\n OVID — OpenClaw Verifiable Identity Documents.\n
\n","readmeFilename":"README.md"}