@agent-custody/receipts 0.1.1 → 0.1.3

package/README.md

@@ -9,7 +9,7 @@ Two producers, one receipt format, one verifier.
 
 Anyone holding the public keys can verify a receipt offline. The agent is not trusted. The layer around it is, and the receipt says exactly how far that trust extends, starting with who issued it.
 
-- [Tutorials](docs/tutorials.md): fourteen runnable examples, one per aspect of the code, all executed by the test suite
+- [Tutorials](docs/tutorials.md): fifteen runnable examples, one per aspect of the code, all executed by the test suite
 - [Usage guide](docs/usage.md): gateway setup, wiring into Claude Desktop, Claude Code, or your own agent loop
 - [The interceptor SDK](docs/sdk.md): Claude Code hooks, the Claude Agent SDK, adapters for the OpenAI Agents SDK, Vercel AI SDK and LangChain, and wrapping tool functions in anything else
 - [Writing policies](docs/policies.md): how a tool call becomes a Cedar request, with tested examples
@@ -103,6 +103,9 @@ Every receipt names its issuer, and the verifier prints what that issuer kind is
 | Vercel AI SDK | SDK | `wrapTools` | | a real `generateText` loop over the SDK's mock model |
 | LangChain / LangGraph (JS) | SDK | `tool(issuer.wrap(fn))` | `ReceiptCallbackHandler` | real `StructuredTool` invocations |
 | anything else | SDK | `issuer.wrap(name, fn)` | `issuer.record` | plain functions |
+| Python: LangChain, OpenAI Agents SDK, Claude Agent SDK | sidecar + [Python package](../python/README.md) | `wrap_tools`, `claude_hook` PreToolUse deny, `client.wrap` | `ReceiptCallbackHandler` | the real Python packages, receipts checked by this verifier |
+| Go, Java, Rust, any language with HTTP | sidecar | decide then record | record | [examples/languages](examples/languages), each run against a live sidecar |
+| any MCP host in any language: Claude Agent SDK Python, OpenAI Agents Python | gateway | yes | | the gateway is an MCP server; [usage.md](docs/usage.md#python-hosts) |
 
 The framework packages are optional peer dependencies. Each adapter imports only from its own package.
 
@@ -167,7 +170,7 @@ Every field carries a provenance label. This is the design decision that matters
 bun install                              # from the repository root, once for the workspace
 cd packages/receipts
 node scripts/demo.ts                     # gateway: keys, grant, policy, four tool calls, verification, a tampering attempt; then the SDK wrapping the same tool
-node examples/01-keys-and-signing.ts     # first of fourteen step-by-step examples, see docs/tutorials.md
+node examples/01-keys-and-signing.ts     # first of fifteen step-by-step examples, see docs/tutorials.md
 bun run test                             # this package; `bun run test` at the root runs every package
 ```
 
@@ -227,12 +230,14 @@ src/gateway.ts     the MCP proxy: scope check, facts, policy, forward, receipt
 src/sdk/index.ts   the interceptor: policy decision, record, wrap(tool fn)
 src/sdk/claude.ts  Claude Code command hook and Claude Agent SDK in-process hooks
 src/sdk/openai-agents.ts, vercel-ai.ts, langchain.ts   framework adapters, tested against the real packages
+src/sidecar.ts     the SDK issuer behind a local HTTP API, for agents in other languages
+vectors/           conformance vectors: receipts, keys, logs, proofs, and expected verdicts; `bun run vectors` regenerates them
 src/verify.ts      offline verification, the human-readable report, and the audit that a later log extends an earlier one
-src/cli.ts         keygen, grant, gateway, hook, log, verify, audit
+src/cli.ts         keygen, grant, gateway, hook, serve, log, verify, audit
 src/index.ts       the package's public surface; adapters are exported on ./sdk/<framework> subpaths
 tsconfig.build.json  emits dist/ (JavaScript plus declarations) for consumers; the repo itself runs the .ts directly
 scripts/           fake Stripe upstream, fixture builders for gateway and SDK, demo
-examples/          fourteen runnable tutorials, one per aspect; each is run by the test suite
+examples/          fifteen runnable tutorials, plus examples/languages/: Python, Go, Java, and Rust clients of the sidecar, run by the test suite, one per aspect; each is run by the test suite
 test/              unit tests per module, end-to-end gateway test, SDK and hook tests,
                    adapter tests against the real packages, and a test that runs every policy in docs/policies.md
 docs/              tutorials, usage (gateway), sdk, policies, verification
@@ -249,6 +254,9 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 - SDK core: policy decision, record, and a generic `wrap(tool, fn)` for any framework whose tools are functions.
 - Claude Code command hook for PreToolUse, PostToolUse, and PostToolUseFailure, with blocking on deny.
 - Claude Agent SDK in-process hooks over the same handler.
+- The forwarded call carries the receipt id and the attested agent and principal in `_meta`, so a stateful upstream can cite the receipt; the memory server in `@agent-custody/state` runs this way.
+- Conformance vectors, generated by the test suite and published with the spec, and a browser verifier on agent-custody.dev that passes all of them.
+- Sidecar: the SDK issuer behind a local HTTP API (`serve`), with a Python package on PyPI-ready footing and Go, Java, and Rust clients, so agents in any language get the same receipts from one signing implementation.
 - Consistency proofs between tree heads (RFC 9162), served by the log and checked by the `audit` command, so an auditor holding an old tree head can prove nothing before it was rewritten.
 - Remote log: the issuer can append to a log run by someone else over HTTP, whose key then signs the tree heads, so a verifier learns the receipt was in a log the operator could not rewrite. Includes the reference log server, bearer-token auth, and a root endpoint for auditors.
 - Framework adapters, each tested against the real package with a scripted model and no network: OpenAI Agents SDK (`wrapTools` enforces, `observeRunner` records from lifecycle events), Vercel AI SDK (`wrapTools` over a real `generateText` loop), LangChain (`ReceiptCallbackHandler` records, `issuer.wrap` enforces).

package/dist/cli.js

@@ -6,6 +6,7 @@ import { generateKeyPair, loadPrivateKey, loadPublicKey, writeKeyPair } from "./
 import { createDelegation } from "./delegation.js";
 import { createGateway, serveStdio } from "./gateway.js";
 import { serveLog } from "./log-sink.js";
+import { serveSidecar } from "./sidecar.js";
 import { MerkleLog } from "./log.js";
 import { createSdkIssuer } from "./sdk/index.js";
 import { handleHookEvent } from "./sdk/claude.js";
@@ -16,6 +17,7 @@ const USAGE = `agent-custody <command>
   grant   --key <principal.key> --principal <id> --agent <id> --scopes <a,b> [--ttl-hours 24] --out <file>
   gateway --config <gateway.json>
   hook    [--config <sdk.json>]        Claude Code hook command; reads the event on stdin (or AGENT_CUSTODY_CONFIG)
+  serve   --config <sdk.json> [--port 8788] [--host 127.0.0.1]   the SDK as a local HTTP API for agents in other languages
   log     --file <log.jsonl> --key <log.key> [--port 8787] [--host 127.0.0.1] [--token-env <NAME>]   reference log server
   verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--log <log.jsonl>] [--json]
   audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--json]
@@ -80,6 +82,17 @@ async function main(argv) {
             console.log(JSON.stringify(out));
             return 0;
         }
+        case "serve": {
+            const { values } = parseArgs({ args: rest, options: { config: { type: "string" }, port: { type: "string", default: "8788" }, host: { type: "string", default: "127.0.0.1" } } });
+            if (!values.config)
+                throw new Error("serve needs --config");
+            const issuer = createSdkIssuer(loadSdkConfig(values.config));
+            const running = await serveSidecar(issuer, { port: Number(values.port), host: values.host });
+            console.error(`agent-custody serve: ${running.url} agent=${issuer.agentId} keyid=${issuer.keyid} log=${issuer.log.kind}:${issuer.log.where}`);
+            await new Promise((resolve) => process.once("SIGINT", resolve));
+            await running.close();
+            return 0;
+        }
         case "log": {
             const { values } = parseArgs({
                 args: rest,

package/dist/crypto.d.ts

@@ -21,6 +21,8 @@ export declare function writeKeyPair(kp: KeyPair, dir: string, name: string): {
 };
 export declare function loadPrivateKey(path: string): KeyPair;
 export declare function loadPublicKey(path: string): PublicKeyRef;
+/** A public key from its SPKI PEM text, as found in a .pub file or a conformance vector. */
+export declare function publicKeyFromPem(pem: string): PublicKeyRef;
 export interface Envelope {
     payloadType: string;
     payload: string;

package/dist/crypto.js

@@ -50,7 +50,11 @@ export function loadPrivateKey(path) {
     return { privateKey, publicKey, keyid: keyidOf(publicKey) };
 }
 export function loadPublicKey(path) {
-    const publicKey = createPublicKey(readFileSync(path));
+    return publicKeyFromPem(readFileSync(path, "utf8"));
+}
+/** A public key from its SPKI PEM text, as found in a .pub file or a conformance vector. */
+export function publicKeyFromPem(pem) {
+    const publicKey = createPublicKey(pem);
     return { publicKey, keyid: keyidOf(publicKey) };
 }
 function pae(payloadType, payload) {

package/dist/gateway.d.ts

@@ -4,6 +4,9 @@ import { type Delegation } from "./delegation.ts";
 export declare const GATEWAY_VERSION = "0.1.0";
 export declare const RECEIPT_META_KEY = "agent-custody/receipt";
 export declare const MODEL_META_KEY = "agent-custody/model";
+/** Set by the gateway on the call it forwards upstream: the receipt id, and the agent and principal from the attested grant. */
+export declare const AGENT_META_KEY = "agent-custody/agent";
+export declare const PRINCIPAL_META_KEY = "agent-custody/principal";
 export interface CallParams {
     name: string;
     arguments?: Record<string, unknown>;

package/dist/gateway.js

@@ -15,6 +15,9 @@ import { evaluate, policyDigest } from "./policy.js";
 export const GATEWAY_VERSION = "0.1.0";
 export const RECEIPT_META_KEY = "agent-custody/receipt";
 export const MODEL_META_KEY = "agent-custody/model";
+/** Set by the gateway on the call it forwards upstream: the receipt id, and the agent and principal from the attested grant. */
+export const AGENT_META_KEY = "agent-custody/agent";
+export const PRINCIPAL_META_KEY = "agent-custody/principal";
 function resolveFactArgs(template, args) {
     const out = {};
     for (const [k, v] of Object.entries(template)) {
@@ -58,7 +61,7 @@ export async function createGateway(cfg) {
     const issuer = createIssuer(gatewayKey, cfg.receiptsDir, openLog(cfg, gatewayKey));
     const upstream = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
     await upstream.connect(new StdioClientTransport({ command: cfg.upstream.command, args: cfg.upstream.args, env: cfg.upstream.env, stderr: "inherit" }));
-    const callUpstream = async (name, args) => (await upstream.callTool({ name, arguments: args }));
+    const callUpstream = async (name, args, meta) => (await upstream.callTool({ name, arguments: args, ...(meta ? { _meta: meta } : {}) }));
     async function gatherFacts(tool, args) {
         const facts = {};
         for (const f of cfg.facts.filter((f) => f.forTools.includes(tool))) {
@@ -98,7 +101,9 @@ export async function createGateway(cfg) {
         }
         if (policy.decision === "allow") {
             try {
-                const result = await callUpstream(tool, args);
+                // The upstream learns which receipt this call is, and who the grant says is calling. An upstream that keeps
+                // state, such as the memory server, cites the receipt as the source of what it stores.
+                const result = await callUpstream(tool, args, { [RECEIPT_META_KEY]: receiptId, [AGENT_META_KEY]: delegation.agent, [PRINCIPAL_META_KEY]: delegation.principal });
                 execution = { status: result.isError ? "failed" : "executed", result, resultDigest: digestOf(result), provenance: "observed" };
             }
             catch (e) {

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from "./policy.ts";
 export * from "./receipt.ts";
 export * from "./verify.ts";
 export * from "./sdk/index.ts";
+export * from "./sidecar.ts";

package/dist/index.js

@@ -10,3 +10,4 @@ export * from "./policy.js";
 export * from "./receipt.js";
 export * from "./verify.js";
 export * from "./sdk/index.js";
+export * from "./sidecar.js";

package/dist/sidecar.d.ts

@@ -0,0 +1,12 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { SdkIssuer } from "./sdk/index.ts";
+export declare function sidecarHandler(issuer: SdkIssuer): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface RunningSidecar {
+    url: string;
+    close(): Promise<void>;
+}
+/** Starts the sidecar. Port 0 picks a free port. Host defaults to loopback on purpose. */
+export declare function serveSidecar(issuer: SdkIssuer, opts: {
+    port: number;
+    host?: string;
+}): Promise<RunningSidecar>;

package/dist/sidecar.js

@@ -0,0 +1,93 @@
+// The sidecar: the SDK issuer behind a local HTTP API, so agents written in any language can decide and record.
+// Same config file, same receipts, same key. Everything it records is claimed, exactly as with the in-process SDK:
+// the sidecar trusts what the agent's process tells it. Bind it to localhost; it is a per-host companion, not a service.
+//   GET  /health                      -> { agentId, keyid, log: { kind, where } }
+//   POST /decide  ToolEvent           -> PolicyDecision | null
+//   POST /record  { event, outcome, policy? } -> ReceiptBundle, or 4xx/5xx with { error }
+import { createServer } from "node:http";
+const isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function parseEvent(v) {
+    if (!isRecord(v) || typeof v.tool !== "string" || v.tool.length === 0)
+        throw new Error("event needs a non-empty string tool");
+    const args = isRecord(v.args) ? v.args : v.args === undefined ? {} : { input: v.args };
+    const ev = { tool: v.tool, args };
+    if (typeof v.model === "string")
+        ev.model = v.model;
+    if (isRecord(v.session))
+        ev.session = { id: typeof v.session.id === "string" ? v.session.id : null, toolUseId: typeof v.session.toolUseId === "string" ? v.session.toolUseId : null };
+    return ev;
+}
+function parseOutcome(v) {
+    if (!isRecord(v) || typeof v.status !== "string")
+        throw new Error("outcome needs a status");
+    switch (v.status) {
+        case "executed":
+        case "failed":
+            return { status: v.status, result: v.result ?? null };
+        case "denied":
+            return { status: "denied", reason: typeof v.reason === "string" ? v.reason : "denied" };
+        case "error":
+            return { status: "error", error: typeof v.error === "string" ? v.error : "error" };
+        default:
+            throw new Error(`unknown outcome status ${v.status}`);
+    }
+}
+function parsePolicy(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (!isRecord(v) || (v.decision !== "allow" && v.decision !== "deny") || !Array.isArray(v.reasons) || !Array.isArray(v.errors) || typeof v.policyDigest !== "string")
+        throw new Error("policy must be a PolicyDecision from /decide");
+    return { decision: v.decision, reasons: v.reasons.map(String), errors: v.errors.map(String), policyDigest: v.policyDigest };
+}
+export function sidecarHandler(issuer) {
+    return async (req, res) => {
+        const json = (status, body) => {
+            res.writeHead(status, { "content-type": "application/json" });
+            res.end(JSON.stringify(body));
+        };
+        const url = new URL(req.url ?? "/", "http://localhost");
+        try {
+            if (req.method === "GET" && url.pathname === "/health")
+                return json(200, { agentId: issuer.agentId, keyid: issuer.keyid, log: { kind: issuer.log.kind, where: issuer.log.where } });
+            if (req.method !== "POST")
+                return json(404, { error: "not found" });
+            let raw = "";
+            for await (const chunk of req)
+                raw += chunk;
+            let body;
+            try {
+                body = JSON.parse(raw);
+            }
+            catch {
+                return json(400, { error: "body must be JSON" });
+            }
+            if (url.pathname === "/decide")
+                return json(200, issuer.decide(parseEvent(body)));
+            if (url.pathname === "/record") {
+                if (!isRecord(body))
+                    return json(400, { error: "body must be {event, outcome, policy?}" });
+                const bundle = await issuer.record(parseEvent(body.event), parseOutcome(body.outcome), parsePolicy(body.policy));
+                return json(200, bundle);
+            }
+            return json(404, { error: "not found" });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return json(/needs|must|unknown outcome/.test(msg) ? 400 : 502, { error: msg });
+        }
+    };
+}
+/** Starts the sidecar. Port 0 picks a free port. Host defaults to loopback on purpose. */
+export function serveSidecar(issuer, opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const handler = sidecarHandler(issuer);
+    const server = createServer((req, res) => {
+        void handler(req, res);
+    });
+    return new Promise((resolve) => {
+        server.listen(opts.port, host, () => {
+            const { port } = server.address();
+            resolve({ url: `http://${host}:${port}/`, close: () => new Promise((r) => server.close(() => r())) });
+        });
+    });
+}

package/docs/sdk.md

@@ -177,3 +177,26 @@ The three framework packages are optional peer dependencies. Each adapter import
 ## What an SDK receipt is worth
 
 A verified SDK receipt establishes that a process holding the application key reported this call, at this time, with these arguments and this result, and that the record has not changed since. It does not establish that the process reported every call, that the arguments are what the tool really received, or that anyone outside the process checked anything. The verifier prints exactly that sentence under `ISSUER`. Keep it in the dashboard too.
+
+## Other languages: the sidecar
+
+The interceptor above is TypeScript. Agents in any other language get the same receipts through the sidecar: the SDK issuer behind a local HTTP API, started from the same config file.
+
+```bash
+agent-custody serve --config sdk.json          # 127.0.0.1:8788 by default; --port and --host to change
+```
+
+| | |
+| --- | --- |
+| `GET /health` | `{ agentId, keyid, log: { kind, where } }` |
+| `POST /decide` with a `ToolEvent` `{ tool, args, model?, session? }` | the `PolicyDecision`, or `null` when no policy is configured |
+| `POST /record` with `{ event, outcome, policy? }` | the `ReceiptBundle`; `outcome` is `{ status: "executed" \| "failed", result }`, `{ status: "denied", reason }`, or `{ status: "error", error }` |
+
+The client's loop is decide, run the tool, record. A malformed body gets a 400 and nothing is written; a log that refuses the leaf gets a 502 and nothing is written. Bind the sidecar to loopback: it is a per-host companion holding the signing key, not a shared service, and everything it records is `claimed` exactly as with the in-process SDK, because it trusts what the client reports.
+
+**Python** has a real package, [packages/python](../../python/README.md): `pip install agent-custody`, a standard-library client with `decide`, `record`, and `wrap`, and adapters for LangChain callbacks, OpenAI Agents function tools, and Claude Agent SDK hooks, each tested against the real package with receipts checked by this verifier.
+
+**Go, Java, Rust, and Python without the package** each have a complete client in [examples/languages](../examples/languages): one file, standard library where the language has an HTTP client, decide then record. The test suite runs every one of them against a live sidecar. Any language with an HTTP client is the same forty lines.
+
+The gateway needs none of this. It is an MCP server, so a Python or Go agent host that speaks MCP puts it in front of its tools with a config change; [usage.md](usage.md) shows the Python hosts.
+

package/docs/tutorials.md

@@ -24,6 +24,7 @@ Suggested reading order is the numbering. Output lands in `examples-out/`, which
 | 12 | inside a receipt | [12-read-a-receipt.ts](../examples/12-read-a-receipt.ts) | the bundle's three parts, the in-toto statement, every predicate field with its provenance, the tree head | `src/receipt.ts` |
 | 13 | a log run by someone else | [13-remote-log.ts](../examples/13-remote-log.ts) | the reference log server on a free port, an SDK config that logs to it, a tree head signed by the log's key, verification failing without that key and passing with it, the root endpoint, a refused token | `src/log-sink.ts` |
 | 14 | proving history was not rewritten | [14-audit-history.ts](../examples/14-audit-history.ts) | three receipts and a kept tree head, a consistency proof that passes, the operator rewriting one leaf and appending a fourth call, the audit failing while the fourth receipt still verifies alone | `src/log.ts`, `src/verify.ts` |
+| 15 | agents in other languages | [15-sidecar.ts](../examples/15-sidecar.ts) | the sidecar on a free port, a client written as a Python or Go program would write it: decide, run, record; a denial recorded without running the tool; both receipts verified | `src/sidecar.ts` |
 
 ## How policies are defined, in one paragraph
 

package/docs/usage.md

@@ -124,6 +124,31 @@ Claude sees only the tools inside the grant's scopes. Every call it makes produc
 claude mcp add stripe -- node /abs/path/agent-custody/packages/receipts/src/cli.ts gateway --config /abs/path/gateway.json
 ```
 
+### Python hosts
+
+The gateway is language-neutral: any host that can launch a stdio MCP server can use it. Claude Agent SDK for Python:
+
+```python
+from claude_agent_sdk import ClaudeAgentOptions, query
+
+options = ClaudeAgentOptions(mcp_servers={"stripe": {"command": "node", "args": ["/abs/path/agent-custody/packages/receipts/src/cli.ts", "gateway", "--config", "/abs/path/gateway.json"]}})
+async for message in query(prompt="Refund customer cust_123 by 50 dollars", options=options):
+    ...
+```
+
+OpenAI Agents SDK for Python:
+
+```python
+from agents import Agent, Runner
+from agents.mcp import MCPServerStdio
+
+async with MCPServerStdio(params={"command": "node", "args": ["/abs/path/agent-custody/packages/receipts/src/cli.ts", "gateway", "--config", "/abs/path/gateway.json"]}) as stripe:
+    agent = Agent(name="support", instructions="...", mcp_servers=[stripe])
+    result = await Runner.run(agent, "Refund customer cust_123 by 50 dollars")
+```
+
+With the npm package installed globally, `"command": "agent-custody", "args": ["gateway", "--config", ...]` replaces the node invocation. Every tool the agent sees comes through the gateway; denied calls never reach Stripe and still produce a receipt. For receipts from tools that are plain Python functions rather than MCP servers, use the sidecar and the Python package, in [sdk.md](sdk.md).
+
 ### Your own agent loop (TypeScript)
 
 This is what [scripts/demo.ts](../scripts/demo.ts) does.
@@ -165,6 +190,10 @@ Any other MCP client works the same way: Python's `mcp` package, LangGraph's MCP
 
 The receipt id is the file name under `receiptsDir`.
 
+## What the upstream gets
+
+The call the gateway forwards carries three `_meta` keys the agent cannot set: `agent-custody/receipt`, the id of the receipt being issued for this call; `agent-custody/agent` and `agent-custody/principal`, from the signed delegation grant. An upstream that keeps state can cite the receipt as the source of what it stores and record the attested caller rather than a claimed one. The memory server in `@agent-custody/state` does exactly that. Fact lookups do not carry them; only the forwarded call does.
+
 ## Operational notes
 
 - **Money is integer minor units.** Cedar has no floating point. A float in `args` that a policy touches is an evaluation error, which is a deny.

package/docs/verification.md

@@ -98,6 +98,10 @@ A gateway receipt does **not** support:
 - that the model named in `model` produced the call. No hosted provider signs model identity.
 - that the gateway operator is honest. The operator holds the gateway key. Against a dishonest operator you need a log copy taken out of their control, or a signer they do not control. See the threat model table in the README.
 
+## In the browser
+
+[agent-custody.dev/verify](https://agent-custody.dev/verify) runs the same checks in the page over WebCrypto, nothing uploaded. It is a second implementation of this verifier, and it passes every published [conformance vector](https://agent-custody.dev/receipt/vectors).
+
 ## Programmatic verification
 
 ```ts
@@ -157,3 +161,7 @@ Programmatically, `auditExtends(older.treeHead, newer.treeHead, proof, keys)` re
 
 The remote log also serves `GET /head`, its current tree head signed with the log's key, so an auditor can record heads on a schedule and later audit any two of them without holding a receipt for each.
 
+## Conformance vectors
+
+`vectors/` in the package holds fixed receipts, keys, logs, proofs, and the verdicts this verifier produces for them, generated by `bun run vectors` and checked by the test suite on every run. A verifier written elsewhere proves it agrees by reproducing every verdict. They are published at [agent-custody.dev/receipt/vectors](https://agent-custody.dev/receipt/vectors).
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Chain of custody for AI agents: signed, independently verifiable receipts for tool calls. MCP gateway + Cedar policy + Merkle transparency log",
   "license": "Apache-2.0",
   "repository": {
@@ -43,13 +43,15 @@
   },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "vectors"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "demo": "tsx scripts/demo.ts"
+    "demo": "tsx scripts/demo.ts",
+    "vectors": "tsx scripts/vectors.ts"
   },
   "engines": {
     "node": ">=22"

package/vectors/audit.json

@@ -0,0 +1,147 @@
+{
+  "version": "0.2",
+  "note": "auditExtends(older, newer, proof, keys): both tree heads must verify against a listed key; the proof is the log's consistency proof between their sizes.",
+  "cases": [
+    {
+      "name": "remote-log-extends",
+      "description": "The tree head from the first remote receipt and the log's later head, with the proof the log served.",
+      "older": {
+        "payloadType": "application/vnd.agent-custody.treehead+json",
+        "payload": "eyJyb290SGFzaCI6Ijg3MzM5M2E4ZTQ4ZmFkNzVlMmRkMzY1MzRjNmRjNzUzMTc5YmM0NmEzMTAxNDZjZTI2OGUxNTc2ODZiOGMwZTQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExMFoiLCJ0cmVlU2l6ZSI6MX0=",
+        "signatures": [
+          {
+            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
+            "sig": "vydFxb4Z753KUPOXLEFiYnE0nntaoU9xXtBe7IMW8eucYeef+XpGu+4+bXpo/zYZATcx4h+7bMmDd3frqizkBg=="
+          }
+        ]
+      },
+      "newer": {
+        "payloadType": "application/vnd.agent-custody.treehead+json",
+        "payload": "eyJyb290SGFzaCI6ImNlYmViNDAzYjNlZWYzYzgwNWVjYzg5OTI2NTM0ZGM0NjkxY2I4OWJlN2I0ZjFjNjE3Njg5MDFkMzIxNDkzYmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExNFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "signatures": [
+          {
+            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
+            "sig": "iyUBqiJcZd/RaEDXWhhxl34ekqy6tQ9qgsMQjAXlvuHS75aqPLeh0NRtUQB89LS2UMJYihmcSUdg/Z82uORqCQ=="
+          }
+        ]
+      },
+      "proof": [
+        "4869289b5853ed3431c235a1f4e97d1d4205723e622dc71bd836018c62572723"
+      ],
+      "keys": [
+        "log"
+      ],
+      "expected": {
+        "ok": true,
+        "failing": []
+      }
+    },
+    {
+      "name": "remote-log-wrong-order",
+      "description": "The same heads the wrong way round.",
+      "older": {
+        "payloadType": "application/vnd.agent-custody.treehead+json",
+        "payload": "eyJyb290SGFzaCI6ImNlYmViNDAzYjNlZWYzYzgwNWVjYzg5OTI2NTM0ZGM0NjkxY2I4OWJlN2I0ZjFjNjE3Njg5MDFkMzIxNDkzYmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExNFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "signatures": [
+          {
+            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
+            "sig": "iyUBqiJcZd/RaEDXWhhxl34ekqy6tQ9qgsMQjAXlvuHS75aqPLeh0NRtUQB89LS2UMJYihmcSUdg/Z82uORqCQ=="
+          }
+        ]
+      },
+      "newer": {
+        "payloadType": "application/vnd.agent-custody.treehead+json",
+        "payload": "eyJyb290SGFzaCI6Ijg3MzM5M2E4ZTQ4ZmFkNzVlMmRkMzY1MzRjNmRjNzUzMTc5YmM0NmEzMTAxNDZjZTI2OGUxNTc2ODZiOGMwZTQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExMFoiLCJ0cmVlU2l6ZSI6MX0=",
+        "signatures": [
+          {
+            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
+            "sig": "vydFxb4Z753KUPOXLEFiYnE0nntaoU9xXtBe7IMW8eucYeef+XpGu+4+bXpo/zYZATcx4h+7bMmDd3frqizkBg=="
+          }
+        ]
+      },
+      "proof": [
+        "4869289b5853ed3431c235a1f4e97d1d4205723e622dc71bd836018c62572723"
+      ],
+      "keys": [
+        "log"
+      ],
+      "expected": {
+        "ok": false,
+        "failing": [
+          "older is not larger than newer"
+        ]
+      }
+    },
+    {
+      "name": "remote-log-wrong-key",
+      "description": "Tree heads checked against the app key, which did not sign them.",
+      "older": {
+        "payloadType": "application/vnd.agent-custody.treehead+json",
+        "payload": "eyJyb290SGFzaCI6Ijg3MzM5M2E4ZTQ4ZmFkNzVlMmRkMzY1MzRjNmRjNzUzMTc5YmM0NmEzMTAxNDZjZTI2OGUxNTc2ODZiOGMwZTQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExMFoiLCJ0cmVlU2l6ZSI6MX0=",
+        "signatures": [
+          {
+            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
+            "sig": "vydFxb4Z753KUPOXLEFiYnE0nntaoU9xXtBe7IMW8eucYeef+XpGu+4+bXpo/zYZATcx4h+7bMmDd3frqizkBg=="
+          }
+        ]
+      },
+      "newer": {
+        "payloadType": "application/vnd.agent-custody.treehead+json",
+        "payload": "eyJyb290SGFzaCI6ImNlYmViNDAzYjNlZWYzYzgwNWVjYzg5OTI2NTM0ZGM0NjkxY2I4OWJlN2I0ZjFjNjE3Njg5MDFkMzIxNDkzYmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExNFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "signatures": [
+          {
+            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
+            "sig": "iyUBqiJcZd/RaEDXWhhxl34ekqy6tQ9qgsMQjAXlvuHS75aqPLeh0NRtUQB89LS2UMJYihmcSUdg/Z82uORqCQ=="
+          }
+        ]
+      },
+      "proof": [
+        "4869289b5853ed3431c235a1f4e97d1d4205723e622dc71bd836018c62572723"
+      ],
+      "keys": [
+        "app"
+      ],
+      "expected": {
+        "ok": false,
+        "failing": [
+          "older tree head signature",
+          "newer tree head signature"
+        ]
+      }
+    },
+    {
+      "name": "remote-log-bad-proof",
+      "description": "A proof with a hash removed.",
+      "older": {
+        "payloadType": "application/vnd.agent-custody.treehead+json",
+        "payload": "eyJyb290SGFzaCI6Ijg3MzM5M2E4ZTQ4ZmFkNzVlMmRkMzY1MzRjNmRjNzUzMTc5YmM0NmEzMTAxNDZjZTI2OGUxNTc2ODZiOGMwZTQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExMFoiLCJ0cmVlU2l6ZSI6MX0=",
+        "signatures": [
+          {
+            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
+            "sig": "vydFxb4Z753KUPOXLEFiYnE0nntaoU9xXtBe7IMW8eucYeef+XpGu+4+bXpo/zYZATcx4h+7bMmDd3frqizkBg=="
+          }
+        ]
+      },
+      "newer": {
+        "payloadType": "application/vnd.agent-custody.treehead+json",
+        "payload": "eyJyb290SGFzaCI6ImNlYmViNDAzYjNlZWYzYzgwNWVjYzg5OTI2NTM0ZGM0NjkxY2I4OWJlN2I0ZjFjNjE3Njg5MDFkMzIxNDkzYmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExNFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "signatures": [
+          {
+            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
+            "sig": "iyUBqiJcZd/RaEDXWhhxl34ekqy6tQ9qgsMQjAXlvuHS75aqPLeh0NRtUQB89LS2UMJYihmcSUdg/Z82uORqCQ=="
+          }
+        ]
+      },
+      "proof": [],
+      "keys": [
+        "log"
+      ],
+      "expected": {
+        "ok": false,
+        "failing": [
+          "newer log extends older log"
+        ]
+      }
+    }
+  ]
+}

package/vectors/canonical.json

@@ -0,0 +1,76 @@
+{
+  "version": "0.2",
+  "note": "canonical JSON: keys sorted, no whitespace, undefined dropped. digest = hex sha256 of the canonical string. keyid = hex sha256 of the SPKI DER public key. DSSE PAE = 'DSSEv1 ' + len(type) + ' ' + type + ' ' + len(payload) + ' ' + payload, signed with Ed25519.",
+  "values": [
+    {
+      "value": {
+        "b": 1,
+        "a": [
+          3,
+          {
+            "z": null,
+            "y": "ÿ"
+          }
+        ]
+      },
+      "canonical": "{\"a\":[3,{\"y\":\"ÿ\",\"z\":null}],\"b\":1}",
+      "digest": "894fec1144463457d74d1eb8599cf2e04a42723765ec1d1aabb77d658d860f2b"
+    },
+    {
+      "value": "plain",
+      "canonical": "\"plain\"",
+      "digest": "945603a8f587786b463c3f94fce115c0fae88fac2728cc96ddf5981cf7f61741"
+    },
+    {
+      "value": 42,
+      "canonical": "42",
+      "digest": "73475cb40a568e8da8a045ced110137e159f890ac4da883b6b17dc651b3a8049"
+    },
+    {
+      "value": [
+        1,
+        2,
+        3
+      ],
+      "canonical": "[1,2,3]",
+      "digest": "a615eeaee21de5179de080de8c3052c8da901138406ba71c38c032845f7d54f4"
+    },
+    {
+      "value": {
+        "nested": {
+          "deep": {
+            "deeper": true
+          }
+        }
+      },
+      "canonical": "{\"nested\":{\"deep\":{\"deeper\":true}}}",
+      "digest": "d64d85fa17b84e33888c36e22c9543527721099faee1e070943096aa3c9ba4c2"
+    },
+    {
+      "value": {},
+      "canonical": "{}",
+      "digest": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
+    }
+  ],
+  "keyid": {
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAEb81f6KaNmH1pNR7KbeIUo9DW65Y0Qsfdxqbtnhs7cg=\n-----END PUBLIC KEY-----\n",
+    "keyid": "0ecde3bf114156b895ceb4ea63daa345271e8ee979f47bc69cbf0266bb93f6f5"
+  },
+  "dsse": {
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAEb81f6KaNmH1pNR7KbeIUo9DW65Y0Qsfdxqbtnhs7cg=\n-----END PUBLIC KEY-----\n",
+    "envelope": {
+      "payloadType": "application/vnd.example+json",
+      "payload": "eyJoZWxsbyI6IndvcmxkIn0=",
+      "signatures": [
+        {
+          "keyid": "0ecde3bf114156b895ceb4ea63daa345271e8ee979f47bc69cbf0266bb93f6f5",
+          "sig": "wkH8ufuyC3BJldxmhFUCImAOo38KyQO/uQMITvTjgikPeE9GIv6OwYEFtQnjcBNzY0+MRTn++dGeMwvVKzIBDw=="
+        }
+      ]
+    },
+    "payloadJson": "{\"hello\":\"world\"}",
+    "paeHex": "445353457631203238206170706c69636174696f6e2f766e642e6578616d706c652b6a736f6e203137207b2268656c6c6f223a22776f726c64227d",
+    "paeSha256": "8a321059588971b8abbbfeb3a5c7f629a14fc46d2ecf12895a79483dde78532e",
+    "expected": true
+  }
+}