@agent-custody/receipts 0.1.0

package/dist/verify.js

@@ -0,0 +1,107 @@
+// Independent verification of a receipt bundle. Needs only public keys, and optionally a copy of the log.
+import { canonicalize, digestOf, dsseVerify } from "./crypto.js";
+import { delegationValidAt, verifyDelegation } from "./delegation.js";
+import { leafHash, MerkleLog, verifyInclusion } from "./log.js";
+import { RECEIPT_PREDICATE_TYPE, RECEIPT_TYPE, TREEHEAD_TYPE } from "./receipt.js";
+const short = (s) => s.slice(0, 12);
+export function verifyBundle(bundle, opts) {
+    const checks = [];
+    const add = (name, ok, detail) => {
+        checks.push(detail === undefined ? { name, ok } : { name, ok, detail });
+        return ok;
+    };
+    const done = (statement) => ({ ok: checks.every((c) => c.ok), checks, statement });
+    const sig = dsseVerify(bundle.envelope, opts.issuerKeys);
+    if (!sig.ok) {
+        add("receipt signature (issuer key)", false, sig.error);
+        return done(null);
+    }
+    add("receipt signature (issuer key)", true, `keyid ${short(sig.keyid)}`);
+    const st = sig.payload;
+    if (!add("receipt payload type", bundle.envelope.payloadType === RECEIPT_TYPE && st.predicateType === RECEIPT_PREDICATE_TYPE))
+        return done(null);
+    const p = st.predicate;
+    add("issuer kind is known", p.issuer.kind === "gateway" || p.issuer.kind === "sdk", `${p.issuer.kind}${p.issuer.framework ? ` / ${p.issuer.framework}` : ""}`);
+    add("issuer keyid matches signer", p.issuer.keyid === sig.keyid);
+    if (p.issuer.kind === "gateway") {
+        add("gateway receipt carries a delegation", p.delegation !== undefined);
+        add("gateway receipt carries a policy decision", p.policy !== null);
+    }
+    if (p.delegation) {
+        const del = verifyDelegation(p.delegation.envelope, opts.principalKeys);
+        add("delegation signature (principal key)", del.ok, del.ok ? `signed by ${short(del.keyid)}` : del.error);
+        if (del.ok) {
+            const d = del.delegation;
+            const principalKeyid = p.principal.provenance === "attested" ? p.principal.keyid : null;
+            add("delegation binds principal and agent", d.principal === p.principal.id && d.agent === p.agent.id && del.keyid === principalKeyid);
+            add("delegation valid at receipt time", delegationValidAt(d, p.timestamp), `${d.issuedAt} .. ${d.expiresAt}`);
+            const inScope = d.scopes.includes(p.tool.name);
+            const executed = p.execution.status === "executed" || p.execution.status === "failed";
+            add("executed tool within delegated scope", !executed || inScope, inScope ? p.tool.name : `${p.tool.name} not in [${d.scopes.join(", ")}]`);
+        }
+    }
+    else {
+        add("principal is claimed, not attested", p.principal.provenance === "claimed", "no signed delegation in this receipt");
+    }
+    add("request args digest", digestOf(p.request.args) === p.request.argsDigest && st.subject[0]?.digest.sha256 === p.request.argsDigest);
+    if (p.policy) {
+        const consistent = p.policy.decision === "allow" ? p.execution.status !== "denied" : p.execution.status === "denied";
+        add("policy decision consistent with execution", consistent, `${p.policy.decision} -> ${p.execution.status}`);
+        add("no policy errors on an allow", !(p.policy.decision === "allow" && p.policy.errors.length > 0));
+    }
+    const th = dsseVerify(bundle.treeHead, opts.issuerKeys);
+    add("tree head signature", th.ok && bundle.treeHead.payloadType === TREEHEAD_TYPE, th.ok ? undefined : th.error);
+    if (th.ok) {
+        const head = th.payload;
+        add("tree head matches inclusion proof size", head.treeSize === bundle.inclusion.treeSize);
+        const included = verifyInclusion(leafHash(canonicalize(bundle.envelope)), bundle.inclusion, head.rootHash);
+        add("log inclusion proof", included, `leaf ${bundle.inclusion.leafIndex} of ${bundle.inclusion.treeSize}, root ${short(head.rootHash)}`);
+        if (opts.logFile) {
+            let root = "";
+            try {
+                root = MerkleLog.rootFromFile(opts.logFile, head.treeSize);
+            }
+            catch (e) {
+                add("log file root matches tree head", false, String(e instanceof Error ? e.message : e));
+            }
+            if (root)
+                add("log file root matches tree head", root === head.rootHash, `recomputed ${short(root)}`);
+        }
+    }
+    return done(st);
+}
+const ISSUER_NOTE = {
+    gateway: "enforced outside the agent's process; the agent could neither skip nor forge this receipt",
+    sdk: "self-reported by the agent's own process; tamper-evident after issue, but nothing here was enforced outside the agent",
+};
+/** Human-readable report: checks, then every field with its provenance so the reader knows what was proven vs. claimed. */
+export function formatReport(r) {
+    const lines = [];
+    for (const c of r.checks)
+        lines.push(`${c.ok ? "PASS" : "FAIL"}  ${c.name}${c.detail ? `  (${c.detail})` : ""}`);
+    lines.push("");
+    lines.push(r.ok ? "RESULT: VERIFIED" : "RESULT: NOT VERIFIED");
+    if (!r.statement)
+        return lines.join("\n");
+    const p = r.statement.predicate;
+    lines.push("");
+    lines.push(`ISSUER: ${p.issuer.kind}${p.issuer.framework ? ` (${p.issuer.framework})` : ""}, ${ISSUER_NOTE[p.issuer.kind] ?? "unknown issuer kind"}`);
+    lines.push("");
+    lines.push("field           provenance  value");
+    const row = (f, prov, v) => lines.push(`${f.padEnd(15)} ${prov.padEnd(11)} ${typeof v === "string" ? v : JSON.stringify(v)}`);
+    row("principal", p.principal.provenance, p.principal.id ?? "(none)");
+    row("agent", p.agent.provenance, p.agent.id);
+    if (p.session.id || p.session.toolUseId)
+        row("session", p.session.provenance, `${p.session.id ?? "-"} / ${p.session.toolUseId ?? "-"}`);
+    row("model", p.model.provenance, p.model.id ?? "(none supplied)");
+    row("tool", p.tool.provenance, p.tool.name);
+    row("args", p.request.provenance, p.request.args);
+    for (const [k, f] of Object.entries(p.facts))
+        row(`fact.${k}`, f.provenance, f.value);
+    if (p.policy)
+        row("policy", p.policy.provenance, `${p.policy.decision} [${p.policy.reasons.join(",")}] policy ${short(p.policy.policyDigest)}`);
+    else
+        row("policy", "-", "(none evaluated)");
+    row("execution", p.execution.provenance, p.execution.status);
+    return lines.join("\n");
+}

package/docs/policies.md

@@ -0,0 +1,138 @@
+# Writing policies
+
+Policies are written in [Cedar](https://www.cedarpolicy.com/), the language AWS uses for AgentCore and Verified Permissions. There is no home-grown policy language here. Every example on this page is executed against the real evaluator in the test suite.
+
+## How a tool call becomes a Cedar request
+
+For an intercepted call to tool `T` by the agent named in the grant:
+
+| Cedar slot | value |
+| --- | --- |
+| `principal` | `Agent::"<agent id from the grant>"` |
+| `action` | `Action::"<T>"` |
+| `resource` | `Tool::"<T>"` |
+| `context.args` | the call's arguments, exactly as the agent sent them. **Provenance: claimed.** |
+| `context.facts` | results of the gateway's own upstream lookups configured in `facts`. **Provenance: observed.** |
+| `context.grant` | `{ principal, scopes }` from the signed delegation. **Provenance: attested.** |
+
+No entity hierarchy or schema is loaded yet, so policies reason about `context` and the three identifiers above.
+
+Two things happen before Cedar runs and cannot be overridden by policy:
+
+1. If `T` is not in the grant's scopes, the call is denied. No facts are fetched.
+2. Each configured fact for `T` is fetched from upstream. If any lookup fails, the call is denied.
+
+## The rules Cedar applies
+
+- **Default deny.** With no matching `permit`, the decision is deny.
+- **`forbid` wins.** A matching `forbid` overrides every `permit`.
+- **Errors deny.** If evaluating any policy raises an error, such as a missing attribute or a float, the gateway denies regardless of what other policies said. The errors are recorded in the receipt.
+- **The policy is pinned.** The receipt carries the sha256 of the policy file, so a verifier knows which text produced the decision.
+
+## Examples
+
+Each of these is a complete, valid policy file.
+
+**Permit a read to any agent holding the scope.**
+
+```cedar
+permit(principal, action == Action::"customer.lookup", resource);
+```
+
+**Cap an amount.** Amounts are integer minor units. 100000 pence is £1,000.
+
+```cedar
+permit(principal, action == Action::"stripe.refund", resource)
+when { context.args.amount <= 100000 };
+```
+
+A call without `amount` is an error, hence a deny. That is the behaviour you want from a payments policy.
+
+**Require a fact the gateway fetched, not something the agent asserted.** This is the pattern the whole project exists for.
+
+```cedar
+permit(principal, action == Action::"stripe.refund", resource)
+when {
+  context.args.amount <= 100000 &&
+  context.facts has customer &&
+  context.facts.customer.verified == true
+};
+```
+
+With the matching `facts` entry in the gateway config, `context.facts.customer` is whatever `customer.lookup` returned for the customer id in the call. An agent that sends `{ "verified": true }` in its arguments changes nothing, because the policy never reads `context.args.verified`.
+
+**Restrict to a named agent.**
+
+```cedar
+permit(principal == Agent::"support-agent", action == Action::"stripe.refund", resource);
+```
+
+**Several tools in one rule.**
+
+```cedar
+permit(principal, action in [Action::"customer.lookup", Action::"customer.search"], resource);
+```
+
+**A hard block that no permit can override.**
+
+```cedar
+permit(principal, action == Action::"stripe.refund", resource)
+when { context.args.amount <= 100000 };
+
+forbid(principal, action == Action::"stripe.refund", resource)
+when { context.facts has customer && context.facts.customer.flagged == true };
+```
+
+**Pattern-match a string argument.**
+
+```cedar
+permit(principal, action == Action::"github.merge", resource)
+when { context.args.repo like "acme/*" && context.args.base == "main" };
+```
+
+**`unless` reads better for exceptions.**
+
+```cedar
+permit(principal, action == Action::"stripe.refund", resource)
+unless { context.args.currency != "GBP" };
+```
+
+**Reach the grant itself.**
+
+```cedar
+permit(principal, action, resource)
+when { context.grant.principal == "user_456" };
+```
+
+## Gotchas
+
+- **Integers only.** `12.50` is not a Cedar value. Send `1250`.
+- **Test `has` before reading an optional attribute.** `context.facts.customer.verified` errors if there is no `customer` fact, and an error is a deny. Sometimes that is what you want. When it is not, guard with `context.facts has customer`.
+- **No schema means no typo protection.** A policy that reads `context.args.ammount` never matches and every refund is denied. Fail-closed hides typos as denials, so test your policies.
+- **Scope is enforced outside Cedar.** You cannot use a policy to grant a tool the delegation did not include.
+
+## Testing a policy
+
+The evaluator is a pure function, so a policy test is a unit test. See [test/policy.test.ts](../test/policy.test.ts).
+
+```ts
+import { evaluate } from "../src/policy.ts";
+import { readFileSync } from "node:fs";
+
+const policy = readFileSync("policy.cedar", "utf8");
+const d = evaluate(policy, {
+  agentId: "support-agent",
+  tool: "stripe.refund",
+  context: {
+    args: { customer_id: "cust_123", amount: 50000 },
+    facts: { customer: { verified: true } },
+    grant: { principal: "user_456", scopes: ["customer.lookup", "stripe.refund"] },
+  },
+});
+// d.decision  "allow" | "deny"
+// d.reasons   ids of the policies that decided it
+// d.errors    evaluation errors, non-empty always means deny
+// d.policyDigest  sha256 of the policy text, the same value a receipt will carry
+```
+
+Write one case per branch of every `when` clause, plus one for the missing-attribute path.

package/docs/sdk.md

@@ -0,0 +1,177 @@
+# The interceptor SDK
+
+The gateway sees only MCP traffic. The SDK sees whatever the agent framework lets it hook, from inside the agent's own process. It issues the same receipt format, verified by the same command, with one difference a verifier cannot miss: the receipt names its issuer as `sdk`, and every field is `claimed`.
+
+| | gateway | SDK |
+| --- | --- | --- |
+| runs | as a separate process between agent and tools | inside the agent's process |
+| sees | MCP tool calls only | whatever the framework's hooks expose |
+| can enforce | yes, the call never reaches upstream on deny | only where the hook can block, and only if nobody bypasses the hook |
+| facts | fetched by the gateway itself, `observed` | none; policies see `context.args` only |
+| delegation | required, signed by the principal | none; principal is a config string, `claimed` |
+| a verifier learns | the agent could not have skipped or forged this | the agent's process reported this, and it has not changed since |
+| install | change one line in the host's MCP config | add a hook or wrap a tool function |
+
+Use the SDK for reach. Use the gateway for anything that moves money, touches production, or handles personal data. Both write to the same receipt directory and log if you point them there.
+
+## Configuration
+
+```json
+{
+  "agentId": "billing-bot",
+  "principalId": "user_456",
+  "identity": { "keyFile": "keys/app.key" },
+  "policyFile": "policy.cedar",
+  "receiptsDir": "receipts",
+  "logFile": "log.jsonl",
+  "framework": "claude-code"
+}
+```
+
+`policyFile` and `principalId` are optional. Without a policy the SDK records and never denies. Paths resolve relative to the config file. Generate the key with `node src/cli.ts keygen --dir keys --name app`.
+
+Policies see `context.args` and an empty `context.facts`. A policy that reads `context.facts` or `context.grant` errors, which is a deny. That is intended: an SDK policy cannot pretend it checked something outside the agent's process.
+
+## Claude Code
+
+Register the hook command in `.claude/settings.json`. The same command handles all three events.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "mcp__.*|Bash|Write|Edit", "hooks": [{ "type": "command", "command": "node /abs/path/agent-custody/packages/receipts/src/cli.ts hook --config /abs/path/sdk.json" }] }
+    ],
+    "PostToolUse": [
+      { "hooks": [{ "type": "command", "command": "node /abs/path/agent-custody/packages/receipts/src/cli.ts hook --config /abs/path/sdk.json" }] }
+    ],
+    "PostToolUseFailure": [
+      { "hooks": [{ "type": "command", "command": "node /abs/path/agent-custody/packages/receipts/src/cli.ts hook --config /abs/path/sdk.json" }] }
+    ]
+  }
+}
+```
+
+`AGENT_CUSTODY_CONFIG` works instead of `--config`. Behaviour per event:
+
+- **PreToolUse.** Evaluates the policy. On deny, issues a denial receipt and returns `permissionDecision: "deny"` with the receipt id in the reason. On allow, or with no policy, returns no decision, so Claude Code's own permission prompts still apply. The hook never auto-approves.
+- **PostToolUse.** Issues an executed receipt carrying `tool_response`.
+- **PostToolUseFailure.** Issues a failed receipt.
+
+Session and tool-use ids from the event are recorded so a receipt can be matched to the transcript. If the user declines a call at the permission prompt, no PostToolUse fires and no receipt is issued for it. Claude Code records that in its own transcript, not here.
+
+## Claude Agent SDK, in-process
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { loadSdkConfig } from "@agent-custody/receipts";
+import { claudeAgentHooks, createSdkIssuer } from "@agent-custody/receipts/sdk/claude";
+
+const issuer = createSdkIssuer(loadSdkConfig("./sdk.json"));
+
+for await (const msg of query({
+  prompt: "Refund the customer",
+  options: { hooks: claudeAgentHooks(issuer) },
+})) {
+  // ...
+}
+```
+
+`claudeAgentHooks(issuer, matcher?)` returns entries for `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` with the same behaviour as the command hook. The hook callback receives the same JSON fields, so the handler is shared. This adapter is typed loosely and does not import the SDK package; it has been exercised against the documented hook contract, not against a live `query()` run.
+
+## OpenAI Agents SDK (JS)
+
+Two adapters in [src/sdk/openai-agents.ts](../src/sdk/openai-agents.ts). Both are tested against the real package with a scripted model and a real `Runner`, no network.
+
+```ts
+import { Agent, Runner } from "@openai/agents";
+import { wrapTools, observeRunner } from "@agent-custody/receipts/sdk/openai-agents";
+
+// enforcement + receipts: wrap the tools you hand to the agent
+const agent = new Agent({ name: "billing", tools: wrapTools(issuer, [refundTool, lookupTool]) });
+
+// receipts only: attach to the runner's lifecycle events, nothing to wrap, no policy evaluated
+const runner = new Runner();
+observeRunner(issuer, runner);
+```
+
+`wrapTools` wraps each tool's `invoke`. On a policy deny the tool never runs; the model receives the denial text as the tool result, with the receipt id, and the run continues. That matches what a model sees when a human declines a tool. `observeRunner` listens to `agent_tool_start` and `agent_tool_end`, pairs them by call id, and records executed receipts with no policy. Use one or the other for a given tool, not both.
+
+## Vercel AI SDK
+
+[src/sdk/vercel-ai.ts](../src/sdk/vercel-ai.ts), tested with a real `generateText` loop over a mock model.
+
+```ts
+import { generateText } from "ai";
+import { wrapTools } from "@agent-custody/receipts/sdk/vercel-ai";
+
+const result = await generateText({ model, prompt, tools: wrapTools(issuer, tools) });
+```
+
+`wrapTools` returns a new tool set with every `execute` wrapped. Tools without `execute` pass through untouched. On deny it throws `PolicyDeniedError`, which the AI SDK turns into a `tool-error` part that the model sees; the loop continues. The receipt records the `toolCallId`.
+
+## LangChain / LangGraph (JS)
+
+[src/sdk/langchain.ts](../src/sdk/langchain.ts), tested against real `StructuredTool` invocations.
+
+```ts
+import { tool } from "@langchain/core/tools";
+import { receiptCallbacks, ReceiptCallbackHandler } from "@agent-custody/receipts/sdk/langchain";
+
+// receipts only: a callback handler, attach per call or on the whole graph
+await refund.invoke({ customer_id, amount }, receiptCallbacks(issuer));
+const graph = workflow.compile().withConfig({ callbacks: [new ReceiptCallbackHandler(issuer)] });
+
+// enforcement: build the tool from issuer.wrap()
+const refund = tool(issuer.wrap("stripe.refund", fn), { name: "stripe.refund", schema });
+```
+
+LangChain callbacks cannot block a tool, so the handler evaluates no policy; it records what happened, including the `tool_call_id` when one is present, and unwraps `ToolMessage` outputs. For enforcement wrap the function at construction. Do not do both on one tool or it will be recorded twice.
+
+## Any other framework: wrap the function
+
+Every agent framework ends up calling a function. Wrap it.
+
+```ts
+import { loadSdkConfig } from "@agent-custody/receipts";
+import { createSdkIssuer, PolicyDeniedError } from "@agent-custody/receipts";
+
+const issuer = createSdkIssuer(loadSdkConfig("./sdk.json"));
+
+const refund = issuer.wrap("stripe.refund", async (args: { customer_id: string; amount: number }) => {
+  return stripe.refunds.create({ customer: args.customer_id, amount: args.amount });
+});
+
+try {
+  await refund({ customer_id: "cust_123", amount: 50000 });   // executed receipt
+} catch (e) {
+  if (e instanceof PolicyDeniedError) console.log(e.receiptId); // denial receipt, tool never ran
+  throw e;                                                       // any other error: error receipt, rethrown
+}
+```
+
+For finer control use the two primitives `wrap` is built from:
+
+```ts
+const decision = issuer.decide({ tool, args });                       // PolicyDecision | null
+const bundle = issuer.record({ tool, args, model, session }, { status: "executed", result }, decision);
+```
+
+## Which adapter enforces
+
+| framework | enforce + record | record only |
+| --- | --- | --- |
+| Claude Code | `hook` command, PreToolUse deny | PostToolUse |
+| Claude Agent SDK | `claudeAgentHooks` | same |
+| OpenAI Agents SDK | `wrapTools` | `observeRunner` |
+| Vercel AI SDK | `wrapTools` | wrap with a policy-less issuer |
+| LangChain / LangGraph | `tool(issuer.wrap(...))` | `ReceiptCallbackHandler` |
+| anything else | `issuer.wrap` | `issuer.record` |
+
+Record-only adapters evaluate no policy on purpose. A receipt that said "policy: deny" next to "execution: executed" would fail verification, and the verifier would be right: that is not a receipt, that is a finding. Enforce, or observe, but do not pretend.
+
+The three framework packages are optional peer dependencies. Each adapter imports only from its own package, so installing none of them costs nothing.
+
+## 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.

package/docs/tutorials.md

@@ -0,0 +1,35 @@
+# Tutorials
+
+One runnable example per aspect of the code. Each prints what it is doing, step by step, and ends with `OK`. The test suite runs all of them, so what you read here is what the code does today.
+
+```bash
+node examples/01-keys-and-signing.ts
+```
+
+Suggested reading order is the numbering. Output lands in `examples-out/`, which is gitignored.
+
+| # | aspect | file | you will see | source |
+| --- | --- | --- | --- | --- |
+| 01 | identities and signatures | [01-keys-and-signing.ts](../examples/01-keys-and-signing.ts) | key generation, keyids, a DSSE envelope, verification with the public key, a tampered payload rejected | `src/crypto.ts` |
+| 02 | delegated authority | [02-delegation-grant.ts](../examples/02-delegation-grant.ts) | a principal signs a grant, a stranger's key is rejected, validity windows, scopes | `src/delegation.ts` |
+| 03 | policies | [03-policies.ts](../examples/03-policies.ts) | a Cedar policy evaluated against eight calls: reads, limits, gateway facts versus agent claims, forbid, floats, default deny, the policy digest | `src/policy.ts` |
+| 04 | the transparency log | [04-merkle-log.ts](../examples/04-merkle-log.ts) | appends, inclusion proofs, recomputing the root from the file, an edited line detected | `src/log.ts` |
+| 05 | the gateway | [05-gateway.ts](../examples/05-gateway.ts) | an MCP client connects to the gateway over stdio, sees filtered tools, gets one execution and one denial with receipt ids | `src/gateway.ts`, `src/cli.ts` |
+| 06 | verification and auditing | [06-verify-and-audit.ts](../examples/06-verify-and-audit.ts) | the full check list, with and without a log copy, a tampered receipt, an untrusted key, checks as data for CI | `src/verify.ts` |
+| 07 | the in-process SDK | [07-sdk-wrap.ts](../examples/07-sdk-wrap.ts) | wrap a function, allowed and denied and errored calls, the decide/record primitives, an SDK receipt's report | `src/sdk/index.ts` |
+| 08 | Claude Code and Agent SDK hooks | [08-claude-code-hook.ts](../examples/08-claude-code-hook.ts) | the settings.json entry, PreToolUse allow and deny, PostToolUse, the real command over stdin, Agent SDK hooks | `src/sdk/claude.ts` |
+| 09 | OpenAI Agents SDK | [09-openai-agents.ts](../examples/09-openai-agents.ts) | a real Runner with a scripted model, enforcement via wrapped tools, what the model sees on deny, record-only via lifecycle events | `src/sdk/openai-agents.ts` |
+| 10 | Vercel AI SDK | [10-vercel-ai.ts](../examples/10-vercel-ai.ts) | a real generateText loop over the SDK's mock model, a denial as a tool-error part | `src/sdk/vercel-ai.ts` |
+| 11 | LangChain | [11-langchain.ts](../examples/11-langchain.ts) | the callback handler, tool_call ids, enforcement by wrapping the function | `src/sdk/langchain.ts` |
+| 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` |
+
+## How policies are defined, in one paragraph
+
+A policy is a Cedar file. The gateway turns each tool call into a Cedar request: the principal is `Agent::"<agent id from the grant>"`, the action and resource are the tool name, and the context has three parts. `context.args` is what the agent sent and is only ever claimed. `context.facts` is what the gateway fetched itself before deciding, configured per tool in `gateway.json`, and is observed. `context.grant` is the signed delegation and is attested. Nothing matches means deny. A `forbid` beats every `permit`. An evaluation error, such as a missing attribute or a float, is a deny and is written into the receipt. The receipt also carries the sha256 of the policy text, so a verifier knows exactly which policy decided. Example 03 runs one; [policies.md](policies.md) has nine more, each executed by the test suite.
+
+## Where each guide goes deeper
+
+- [usage.md](usage.md): gateway setup and wiring into hosts
+- [sdk.md](sdk.md): the interceptor and every adapter
+- [policies.md](policies.md): the Cedar mapping, evaluation rules, tested examples, gotchas
+- [verification.md](verification.md): every check and what a verified receipt does and does not prove

package/docs/usage.md

@@ -0,0 +1,166 @@
+# Usage guide: the gateway
+
+This page covers the gateway, the out-of-process producer. For the in-process interceptor that hooks Claude Code, the Claude Agent SDK, or any framework's tool functions, see [sdk.md](sdk.md).
+
+## The parts
+
+| part | what it is | who controls it |
+| --- | --- | --- |
+| principal | the human or organisation on whose authority the agent acts | you |
+| agent | any MCP client: Claude Desktop, Claude Code, a LangGraph node, your own loop | you, but its behaviour is not trusted |
+| gateway | this project, run as an MCP server over stdio | you, holds the gateway signing key |
+| upstream | the real MCP server the agent wants: Stripe, a database, GitHub | the tool provider |
+| grant | a signed statement: principal P lets agent A use tools [..] from T1 to T2 | signed by the principal's key |
+| policy | a Cedar file evaluated on every call | you |
+| receipt bundle | one JSON file per call, signed, with a log inclusion proof | produced by the gateway |
+| log | an append-only JSONL file whose Merkle root every receipt commits to | produced by the gateway |
+
+One gateway process serves one delegation grant. That maps cleanly onto "one agent session, spawned per user, with a scoped grant". Run several gateways for several agents.
+
+## Setup, step by step
+
+All commands run from `packages/receipts`. `node src/cli.ts` works on Node 22 and later without a build step.
+
+**1. Generate keys.** One pair for the gateway, one for the principal. Keep the `.key` files private; distribute the `.pub` files to anyone who will verify receipts.
+
+```bash
+node src/cli.ts keygen --dir ./keys --name gateway
+node src/cli.ts keygen --dir ./keys --name principal
+```
+
+**2. Issue a grant.** The principal signs which agent may use which tools, and for how long.
+
+```bash
+node src/cli.ts grant \
+  --key ./keys/principal.key \
+  --principal user_456 \
+  --agent support-agent \
+  --scopes customer.lookup,stripe.refund \
+  --ttl-hours 8 \
+  --out ./grant.json
+```
+
+The gateway refuses to start if the grant is outside its validity window, and every receipt records the grant so a verifier can re-check it.
+
+**3. Write a policy.** A Cedar file. Default is deny. See [policies.md](policies.md).
+
+```cedar
+permit(principal, action == Action::"customer.lookup", resource);
+
+permit(principal, action == Action::"stripe.refund", resource)
+when {
+  context.args.amount <= 100000 &&
+  context.facts has customer &&
+  context.facts.customer.verified == true
+};
+```
+
+**4. Write the gateway config.** Paths resolve relative to the config file.
+
+```json
+{
+  "identity": { "keyFile": "keys/gateway.key" },
+  "upstream": { "command": "node", "args": ["/path/to/stripe-mcp-server.js"], "env": { "STRIPE_KEY": "sk_..." } },
+  "grantFile": "grant.json",
+  "trustedPrincipalKeys": ["keys/principal.pub"],
+  "policyFile": "policy.cedar",
+  "facts": [
+    {
+      "name": "customer",
+      "tool": "customer.lookup",
+      "args": { "customer_id": "$args.customer_id" },
+      "forTools": ["stripe.refund"]
+    }
+  ],
+  "receiptsDir": "receipts",
+  "logFile": "log.jsonl"
+}
+```
+
+`upstream` is spawned by the gateway exactly as an MCP host would spawn it. `env` is passed through, which is where upstream credentials go. The agent never sees them.
+
+`facts` tells the gateway which upstream tool to call before evaluating policy for a given tool. `$args.<key>` copies a value from the intercepted call. The result appears in Cedar as `context.facts.<name>` and in the receipt with its own digest, labelled `observed`. If a fact lookup fails, the call is denied and the receipt says why.
+
+**5. Run the gateway.** It speaks MCP on stdin/stdout and logs to stderr only.
+
+```bash
+node src/cli.ts gateway --config ./gateway.json
+```
+
+You will not normally run this by hand. The agent host spawns it, as below.
+
+## Wiring it into an agent host
+
+The gateway is an ordinary MCP server, so any host that can launch a stdio MCP server can use it. Point the host at the gateway instead of at the upstream server.
+
+### Claude Desktop
+
+In `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stripe": {
+      "command": "node",
+      "args": ["/abs/path/agent-custody/packages/receipts/src/cli.ts", "gateway", "--config", "/abs/path/gateway.json"]
+    }
+  }
+}
+```
+
+Claude sees only the tools inside the grant's scopes. Every call it makes produces a receipt. Denials come back as tool errors with the receipt id in the text.
+
+### Claude Code
+
+```bash
+claude mcp add stripe -- node /abs/path/agent-custody/packages/receipts/src/cli.ts gateway --config /abs/path/gateway.json
+```
+
+### Your own agent loop (TypeScript)
+
+This is what [scripts/demo.ts](../scripts/demo.ts) does.
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const agent = new Client({ name: "my-agent", version: "1.0.0" });
+await agent.connect(new StdioClientTransport({
+  command: "node",
+  args: ["/abs/path/agent-custody/packages/receipts/src/cli.ts", "gateway", "--config", "/abs/path/gateway.json"],
+}));
+
+const { tools } = await agent.listTools();               // only tools in the grant's scopes
+
+const result = await agent.callTool({
+  name: "stripe.refund",
+  arguments: { customer_id: "cust_123", amount: 50000 },
+  _meta: { "agent-custody/model": "claude-fable-5-1" },  // optional, recorded as "claimed"
+});
+
+const receiptId = result._meta?.["agent-custody/receipt"];
+if (result.isError) {
+  // denied by scope or policy, or upstream failed; the text says which, and a receipt exists either way
+}
+```
+
+Any other MCP client works the same way: Python's `mcp` package, LangGraph's MCP adapters, or the OpenAI Agents SDK MCP support. None of them need to know the gateway is there.
+
+## What the agent gets back
+
+| outcome | `isError` | content | receipt |
+| --- | --- | --- | --- |
+| executed | as returned by upstream | upstream's content, untouched | `_meta["agent-custody/receipt"]` |
+| upstream returned an error | `true` | upstream's content | same |
+| denied by scope or policy | `true` | `Denied by policy: <reason> (receipt <id>)` | same |
+| upstream unreachable | `true` | `Upstream error: <message> (receipt <id>)` | same |
+
+The receipt id is the file name under `receiptsDir`.
+
+## 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.
+- **The gateway key is the trust root for receipts.** Keep it out of the agent's reach. The upstream credentials in `upstream.env` are likewise never exposed to the agent.
+- **Rotate keys by adding, not replacing.** The verifier accepts a list of gateway keys and principal keys and matches by keyid, so old receipts stay verifiable.
+- **The log is append-only by convention, not enforcement.** Copy it somewhere the operator cannot rewrite, on a schedule. The receipts' tree heads let an auditor check that the copy matches.
+- **stdout is the MCP channel.** Anything the gateway prints goes to stderr. Do not add `console.log` to gateway code paths.