@agent-custody/receipts 0.2.0 → 0.3.0

package/dist/otel.js

@@ -0,0 +1,87 @@
+const str = (key, v) => (v === null || v === undefined ? [] : [{ key, value: { stringValue: v } }]);
+const int = (key, v) => [{ key, value: { intValue: String(v) } }];
+/** The span for one receipt, as the OTLP JSON a collector accepts on /v1/traces. Exported so a test or another transport can reuse it. */
+export function spanFor(p, bundle, serviceName) {
+    const hex = p.receiptId.replace(/-/g, "");
+    const traceId = hex.length === 32 ? hex : hex.padEnd(32, "0").slice(0, 32);
+    const start = BigInt(Date.parse(p.timestamp)) * 1000000n;
+    const end = BigInt(Date.now()) * 1000000n;
+    const status = p.execution.status;
+    const auth = p.authorization;
+    const attributes = [
+        ...str("agent_custody.receipt_id", p.receiptId),
+        ...str("agent_custody.issuer.kind", p.issuer.kind),
+        ...str("agent_custody.issuer.keyid", p.issuer.keyid),
+        ...str("agent_custody.tool", p.tool.name),
+        ...str("agent_custody.upstream", p.tool.upstream),
+        ...str("agent_custody.agent", p.agent.id),
+        ...str("agent_custody.agent.provenance", p.agent.provenance),
+        ...str("agent_custody.principal", p.principal.id),
+        ...str("agent_custody.execution.status", status),
+        ...str("agent_custody.policy.decision", p.policy?.decision),
+        ...str("agent_custody.policy.digest", p.policy?.policyDigest),
+        ...int("agent_custody.log.leaf_index", bundle.inclusion.leafIndex),
+        ...int("agent_custody.log.tree_size", bundle.inclusion.treeSize),
+        ...(auth ? int("agent_custody.authorization.leaf_index", auth.inclusion.leafIndex) : []),
+        ...int("agent_custody.consumed.count", p.consumed?.factIds.length ?? 0),
+        ...str("agent_custody.model", p.model.id),
+        ...str("agent_custody.session", p.session.id),
+    ];
+    return {
+        resourceSpans: [
+            {
+                resource: { attributes: str("service.name", serviceName) },
+                scopeSpans: [
+                    {
+                        scope: { name: "agent-custody", version: p.issuer.version },
+                        spans: [
+                            {
+                                traceId,
+                                spanId: traceId.slice(0, 16),
+                                name: `${p.tool.name}`,
+                                kind: 3, // CLIENT: the agent calling out
+                                startTimeUnixNano: start.toString(),
+                                endTimeUnixNano: (end > start ? end : start).toString(),
+                                attributes,
+                                status: status === "executed" || status === "denied" || status === "withheld" ? { code: 1 } : { code: 2, message: status === "failed" ? "the upstream reported failure" : p.execution.error ?? status },
+                            },
+                        ],
+                    },
+                ],
+            },
+        ],
+    };
+}
+/** An exporter that posts each receipt's span to an OTLP/HTTP collector. Failures are reported, never thrown. */
+export function otlpExporter(cfg, opts = {}) {
+    const f = opts.fetch ?? fetch;
+    const env = opts.env ?? process.env;
+    const warn = opts.warn ?? ((m) => console.error(m));
+    const headers = { "content-type": "application/json" };
+    for (const [header, variable] of Object.entries(cfg.headersEnv ?? {})) {
+        const v = env[variable];
+        if (!v)
+            throw new Error(`otel: environment variable ${variable} is not set`);
+        headers[header] = v;
+    }
+    const base = cfg.url.endsWith("/") ? cfg.url : `${cfg.url}/`;
+    const url = new URL("v1/traces", base);
+    const serviceName = cfg.serviceName ?? "agent-custody";
+    return {
+        where: cfg.url,
+        async exported(p, bundle) {
+            try {
+                const res = await f(url, { method: "POST", headers, body: JSON.stringify(spanFor(p, bundle, serviceName)), signal: AbortSignal.timeout(5000) });
+                if (!res.ok)
+                    warn(`agent-custody: otel export of receipt ${p.receiptId} refused by ${cfg.url}: ${res.status}`);
+            }
+            catch (e) {
+                warn(`agent-custody: otel export of receipt ${p.receiptId} failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        },
+    };
+}
+/** The exporter a config asks for, or undefined. */
+export function openExporter(cfg) {
+    return cfg.otel ? otlpExporter(cfg.otel) : undefined;
+}

package/dist/receipt.d.ts

@@ -4,6 +4,8 @@ import type { PolicyDecision } from "./policy.ts";
 import type { UpstreamEvidence } from "./upstream.ts";
 export declare const RECEIPT_TYPE = "application/vnd.in-toto+json";
 export declare const RECEIPT_PREDICATE_TYPE = "https://agent-custody.dev/receipt/v0.2";
+/** The statement a gateway commits to the log before forwarding a consequential call; the receipt for that call embeds it. */
+export declare const AUTHORIZATION_PREDICATE_TYPE = "https://agent-custody.dev/authorization/v0.1";
 export declare const TREEHEAD_TYPE = "application/vnd.agent-custody.treehead+json";
 /**
  * Provenance of a receipt field. This is the honest part of the design.
@@ -86,6 +88,13 @@ export interface ReceiptPredicate {
     policy: (PolicyDecision & {
         provenance: Provenance;
     }) | null;
+    /**
+     * Present when the tool is one the gateway treats as consequential: the authorization statement it committed to the
+     * log before forwarding the call, with that leaf's inclusion proof and tree head. A verifier checks that it names
+     * this receipt, this tool, and these arguments, and that its leaf precedes the receipt's. Without it, evidence of a
+     * side effect exists only after the side effect.
+     */
+    authorization?: AuthorizationBundle;
     execution: {
         status: "executed" | "failed";
         result: unknown;
@@ -101,8 +110,34 @@ export interface ReceiptPredicate {
         status: "error";
         error: string;
         provenance: Provenance;
+    }
+    /** the policy allowed the call but the gateway did not forward it, because the log would not commit the authorization first */
+     | {
+        status: "withheld";
+        reason: string;
+        provenance: Provenance;
     };
 }
+/** What the gateway commits before a consequential call goes out: everything the receipt will say, except the outcome. */
+export type AuthorizationPredicate = Pick<ReceiptPredicate, "receiptId" | "timestamp" | "issuer" | "principal" | "agent" | "delegation" | "tool" | "request" | "facts" | "consumed" | "policy">;
+export interface AuthorizationStatement {
+    _type: "https://in-toto.io/Statement/v1";
+    subject: {
+        name: string;
+        digest: {
+            sha256: string;
+        };
+    }[];
+    predicateType: typeof AUTHORIZATION_PREDICATE_TYPE;
+    predicate: AuthorizationPredicate;
+}
+/** The committed authorization: the same three parts as a receipt bundle. Written to `receipts/<receiptId>.authorization.json` and embedded in the receipt. */
+export interface AuthorizationBundle {
+    envelope: Envelope;
+    treeHead: Envelope;
+    inclusion: InclusionProof;
+}
+export declare function buildAuthorizationStatement(p: AuthorizationPredicate): AuthorizationStatement;
 export interface ReceiptStatement {
     _type: "https://in-toto.io/Statement/v1";
     subject: {

package/dist/receipt.js

@@ -1,6 +1,16 @@
 export const RECEIPT_TYPE = "application/vnd.in-toto+json";
 export const RECEIPT_PREDICATE_TYPE = "https://agent-custody.dev/receipt/v0.2";
+/** The statement a gateway commits to the log before forwarding a consequential call; the receipt for that call embeds it. */
+export const AUTHORIZATION_PREDICATE_TYPE = "https://agent-custody.dev/authorization/v0.1";
 export const TREEHEAD_TYPE = "application/vnd.agent-custody.treehead+json";
+export function buildAuthorizationStatement(p) {
+    return {
+        _type: "https://in-toto.io/Statement/v1",
+        subject: [{ name: `tool-call:${p.tool.name}:${p.receiptId}`, digest: { sha256: p.request.argsDigest } }],
+        predicateType: AUTHORIZATION_PREDICATE_TYPE,
+        predicate: p,
+    };
+}
 export function buildStatement(p) {
     return {
         _type: "https://in-toto.io/Statement/v1",

package/dist/rest.d.ts

@@ -0,0 +1,27 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { RestToolConfig, RestUpstreamConfig } from "./config.ts";
+/** The part of an MCP client the gateway uses, so a REST connector can stand where an MCP upstream stands. */
+export interface UpstreamClient {
+    listTools(): Promise<{
+        tools: Tool[];
+    }>;
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+}
+export interface RestOptions {
+    fetch?: typeof fetch;
+    /** the environment the header secrets are read from; default process.env */
+    env?: Record<string, string | undefined>;
+}
+/** Builds the request for one tool call: path parameters substituted, the rest of the arguments as query or body. */
+export declare function buildRequest(base: string, tool: RestToolConfig, args: Record<string, unknown>): {
+    url: URL;
+    method: string;
+    body: string | null;
+};
+/** A REST API as an upstream. Tools are what the config declares; credentials come from the environment at startup, never from the agent. */
+export declare function restUpstream(name: string, cfg: RestUpstreamConfig, opts?: RestOptions): UpstreamClient;

package/dist/rest.js

@@ -0,0 +1,52 @@
+const encode = (v) => encodeURIComponent(typeof v === "string" ? v : JSON.stringify(v));
+/** Builds the request for one tool call: path parameters substituted, the rest of the arguments as query or body. */
+export function buildRequest(base, tool, args) {
+    const rest = { ...args };
+    const path = tool.path.replace(/\{([A-Za-z0-9_]+)\}/g, (_, name) => {
+        if (!(name in rest) || rest[name] === undefined)
+            throw new Error(`tool ${tool.name}: path needs argument "${name}", which is missing`);
+        const v = rest[name];
+        delete rest[name];
+        return encode(v);
+    });
+    const url = new URL(path.replace(/^\//, ""), base.endsWith("/") ? base : `${base}/`);
+    const method = tool.method;
+    const queryNames = tool.query ?? (method === "GET" || method === "DELETE" ? Object.keys(rest) : []);
+    for (const name of queryNames) {
+        if (rest[name] === undefined)
+            continue;
+        url.searchParams.set(name, typeof rest[name] === "string" ? rest[name] : JSON.stringify(rest[name]));
+        delete rest[name];
+    }
+    const body = method === "GET" || method === "DELETE" || tool.body === "none" ? null : JSON.stringify(rest);
+    return { url, method, body };
+}
+/** A REST API as an upstream. Tools are what the config declares; credentials come from the environment at startup, never from the agent. */
+export function restUpstream(name, cfg, opts = {}) {
+    const f = opts.fetch ?? fetch;
+    const env = opts.env ?? process.env;
+    const headers = { ...(cfg.headers ?? {}) };
+    for (const [header, variable] of Object.entries(cfg.headerEnv ?? {})) {
+        const v = env[variable];
+        if (!v)
+            throw new Error(`upstream ${name}: environment variable ${variable} is not set`);
+        headers[header] = v;
+    }
+    const tools = new Map(cfg.tools.map((t) => [t.name, t]));
+    return {
+        async listTools() {
+            return { tools: cfg.tools.map((t) => ({ name: t.name, description: t.description ?? `${t.method} ${t.path}`, inputSchema: t.inputSchema })) };
+        },
+        async callTool(params) {
+            const tool = tools.get(params.name);
+            if (!tool)
+                throw new Error(`upstream ${name} has no tool "${params.name}"`);
+            const { url, method, body } = buildRequest(cfg.baseUrl, tool, params.arguments ?? {});
+            const res = await f(url, { method, headers: { accept: "application/json", ...(body !== null ? { "content-type": "application/json" } : {}), ...headers }, ...(body !== null ? { body } : {}), signal: AbortSignal.timeout(cfg.timeoutMs) });
+            const text = await res.text();
+            // The result is what the API returned, as text. JSON stays JSON so policy facts and consumers can read it.
+            return { content: [{ type: "text", text: text.length ? text : JSON.stringify({ status: res.status }) }], ...(res.ok ? {} : { isError: true }) };
+        },
+        async close() { },
+    };
+}

package/dist/sdk/index.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { digestOf, loadPrivateKey } from "../crypto.js";
 import { createIssuer } from "../issue.js";
+import { openExporter } from "../otel.js";
 import { openLog } from "../log-sink.js";
 import { evaluate } from "../policy.js";
 export const SDK_VERSION = "0.1.0";
@@ -21,7 +22,7 @@ export class PolicyDeniedError extends Error {
 }
 export function createSdkIssuer(cfg) {
     const key = loadPrivateKey(cfg.identity.keyFile);
-    const issuer = createIssuer(key, cfg.receiptsDir, openLog(cfg, key));
+    const issuer = createIssuer(key, cfg.receiptsDir, openLog(cfg, key), { exporter: openExporter(cfg) });
     const policyText = cfg.policyFile ? readFileSync(cfg.policyFile, "utf8") : null;
     const decide = (ev) => policyText === null ? null : evaluate(policyText, { agentId: cfg.agentId, tool: ev.tool, context: { args: ev.args, facts: {} } });
     function record(ev, outcome, policy = null) {

package/dist/verify.js

@@ -3,7 +3,7 @@ import { canonicalize, digestOf, dsseVerify } from "./crypto.js";
 import { delegationValidAt, verifyDelegation } from "./delegation.js";
 import { leafHash, MerkleLog, verifyConsistency, verifyInclusion } from "./log.js";
 import { checkProvider, checkUpstream, contentDigest, isProviderAttestation } from "./upstream.js";
-import { RECEIPT_PREDICATE_TYPE, RECEIPT_TYPE, TREEHEAD_TYPE } from "./receipt.js";
+import { AUTHORIZATION_PREDICATE_TYPE, RECEIPT_PREDICATE_TYPE, RECEIPT_TYPE, TREEHEAD_TYPE } from "./receipt.js";
 const short = (s) => s.slice(0, 12);
 export function verifyBundle(bundle, opts) {
     const checks = [];
@@ -64,6 +64,29 @@ export function verifyBundle(bundle, opts) {
         add("no policy errors on an allow", !(p.policy.decision === "allow" && p.policy.errors.length > 0));
     }
     const logKeys = opts.logKeys ?? [];
+    if (p.authorization) {
+        // The gateway says it committed this call to the log before forwarding it. Check that the committed statement is
+        // the issuer's, describes this very call, sits in the log, and sits there before the receipt does.
+        const a = p.authorization;
+        const asig = dsseVerify(a.envelope, opts.issuerKeys);
+        const ast = asig.ok ? asig.payload : null;
+        const typed = !!ast && a.envelope.payloadType === RECEIPT_TYPE && ast.predicateType === AUTHORIZATION_PREDICATE_TYPE;
+        add("authorization signature (issuer key)", asig.ok && typed && asig.keyid === sig.keyid, asig.ok ? (typed ? `keyid ${short(asig.keyid)}` : "not an authorization statement") : asig.error);
+        if (ast && typed) {
+            const ap = ast.predicate;
+            const same = ap.receiptId === p.receiptId && ap.tool.name === p.tool.name && ap.request.argsDigest === p.request.argsDigest && ap.agent.id === p.agent.id && ap.principal.id === p.principal.id && ap.policy?.decision === "allow";
+            add("authorization names this call", same, same ? `${ap.tool.name} for receipt ${short(ap.receiptId)}` : "committed for a different receipt, tool, arguments, agent, or decision");
+            const ath = dsseVerify(a.treeHead, [...logKeys, ...opts.issuerKeys]);
+            add("authorization tree head signature", ath.ok && a.treeHead.payloadType === TREEHEAD_TYPE, ath.ok ? `keyid ${short(ath.keyid)}` : ath.error);
+            if (ath.ok) {
+                const ahead = ath.payload;
+                const included = ahead.treeSize === a.inclusion.treeSize && verifyInclusion(leafHash(canonicalize(a.envelope)), a.inclusion, ahead.rootHash);
+                add("authorization log inclusion proof", included, `leaf ${a.inclusion.leafIndex} of ${a.inclusion.treeSize}`);
+                const before = a.inclusion.leafIndex < bundle.inclusion.leafIndex && a.inclusion.treeSize <= bundle.inclusion.treeSize;
+                add("authorization logged before execution", before, `authorization leaf ${a.inclusion.leafIndex}, receipt leaf ${bundle.inclusion.leafIndex}`);
+            }
+        }
+    }
     const th = dsseVerify(bundle.treeHead, [...logKeys, ...opts.issuerKeys]);
     const byLog = th.ok && logKeys.some((k) => k.keyid === th.keyid);
     add("tree head signature", th.ok && bundle.treeHead.payloadType === TREEHEAD_TYPE, th.ok ? `${byLog ? "log key" : "issuer key"} ${short(th.keyid)}` : th.error);
@@ -145,6 +168,12 @@ export function formatReport(r) {
         row("policy", "-", "(none evaluated)");
     if (p.consumed)
         row("consumed", p.consumed.provenance, p.consumed.factIds.length === 0 ? "(no facts shown before this call)" : p.consumed.factIds);
+    if (p.authorization) {
+        const committed = r.checks.filter((c) => c.name.startsWith("authorization ")).every((c) => c.ok);
+        row("authorization", "observed", committed ? `committed to the log as leaf ${p.authorization.inclusion.leafIndex}, before the call was forwarded` : "carried, but its checks FAILED");
+    }
+    else if (p.execution.status === "withheld")
+        row("authorization", "observed", "the log would not commit it; the call was not forwarded");
     const upstreamCheck = r.checks.find((c) => c.name === "upstream signature (upstream key)" || c.name === "upstream signature (provider secret)");
     const hasUpstream = (p.execution.status === "executed" || p.execution.status === "failed") && !!p.execution.upstream;
     const byProvider = hasUpstream && isProviderAttestation(p.execution.upstream);

package/docs/sdk.md

@@ -30,6 +30,8 @@ Use the SDK for reach. Use the gateway for anything that moves money, touches pr
 
 `policyFile` and `principalId` are optional. Without a policy the SDK records and never denies. Paths resolve relative to the config file. Instead of `logFile`, `"log": { "url": "https://log.example.com/", "tokenEnv": "AGENT_CUSTODY_LOG_TOKEN" }` sends every leaf to a log run by someone else, whose key then signs the tree heads; see [usage.md](usage.md) for what that changes and [verification.md](verification.md) for what it proves. Generate the key with `node src/cli.ts keygen --dir keys --name app`.
 
+`"otel": { "url": "http://localhost:4318" }` additionally exports every receipt as one span to that OTLP/HTTP collector, after the receipt is written, with the receipt id as the trace id; see the [usage guide](usage.md#setup-step-by-step) for the fields. Export never blocks or fails a receipt.
+
 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

package/docs/tutorials.md

@@ -25,6 +25,9 @@ Suggested reading order is the numbering. Output lands in `examples-out/`, which
 | 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` |
+| 16 | consequential tools, committed first | [16-precommit.ts](../examples/16-precommit.ts) | a refund named in `precommit`: the authorization leaf before the receipt leaf, the five authorization checks in the report, and the same call withheld when the log refuses | `src/gateway.ts`, `src/issue.ts`, `src/verify.ts` |
+| 17 | a REST API as an upstream | [17-rest-upstream.ts](../examples/17-rest-upstream.ts) | a stand-in payments API described as two tools, the token from the environment, a refund allowed on the gateway's own lookup and one denied before reaching the API, the receipt verified | `src/rest.ts`, `src/gateway.ts` |
+| 18 | OpenTelemetry export | [18-opentelemetry.ts](../examples/18-opentelemetry.ts) | a stand-in OTLP collector, `otel` in the config, one span per receipt with the receipt id as trace id, the collector going away and the next receipt still issued | `src/otel.ts`, `src/issue.ts` |
 
 ## How policies are defined, in one paragraph
 

package/docs/usage.md

@@ -72,6 +72,7 @@ when {
       "forTools": ["stripe.refund"]
     }
   ],
+  "precommit": ["stripe.refund"],
   "receiptsDir": "receipts",
   "logFile": "log.jsonl"
 }
@@ -79,16 +80,39 @@ when {
 
 `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. Several upstreams sit behind one gateway and one grant with `"upstreams": [{ "name": "memory", "command": ..., "args": [...] }, { "name": "payments", "url": ... }]` in place of `upstream`. Each tool name must be offered by exactly one of them, checked at startup; the receipt's `tool.upstream` says which served the call, and consumed facts flow across them, so a refund made after a memory read carries the facts the agent had been shown. An upstream that is already running is reached instead with `"upstream": { "url": "https://memory.internal/mcp", "tokenEnv": "MEMORY_TOKEN" }`, over Streamable HTTP with a bearer token from the environment; the shared memory server in `@agent-custody/state` is the usual case.
 
+An upstream need not be an MCP server. A plain HTTP API is described as tools:
+
+```json
+  "upstream": {
+    "rest": {
+      "baseUrl": "https://api.stripe.com",
+      "headerEnv": { "authorization": "STRIPE_BEARER" },
+      "tools": [
+        { "name": "customer.lookup", "method": "GET", "path": "/v1/customers/{customer_id}",
+          "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string" } }, "required": ["customer_id"] } },
+        { "name": "stripe.refund", "method": "POST", "path": "/v1/refunds", "description": "Refund a customer, amount in minor units",
+          "inputSchema": { "type": "object", "properties": { "customer_id": { "type": "string" }, "amount": { "type": "integer" } }, "required": ["customer_id", "amount"] } }
+      ]
+    }
+  }
+```
+
+`{name}` segments in `path` are filled from the call's arguments; the remaining arguments go to the query string on GET and DELETE and to a JSON body otherwise, or `query` names the ones that go to the query and `body: "none"` sends no body. `headers` are sent as written; `headerEnv` maps a header to an environment variable read once at startup, so the credential is never in the file and never reaches the agent, and a missing variable fails at startup. The response body is the tool result, JSON kept as JSON, and a non-2xx status is a failed execution with the API's answer in the receipt. Everything else is unchanged: the tools appear in the grant's scopes, `facts` may name a REST tool for a lookup, `precommit` applies, and each call has a receipt. `rest` can be one of several `upstreams` beside MCP servers. This is how an agent's direct HTTP calls come under custody: they become tool calls through the gateway. Tutorial 17 runs one against a stand-in API.
+
 `logFile` is the local Merkle log, with tree heads signed by the gateway's own key. To log to a server the operator does not control, replace it with `log`:
 
 ```json
   "log": { "url": "https://log.example.com/", "tokenEnv": "AGENT_CUSTODY_LOG_TOKEN" }
 ```
 
-Exactly one of the two. The bearer token comes from the named environment variable, never from the file, and a missing variable fails at startup. With a remote log the tree head in each receipt is signed by the log's key, and a verifier must be given that key with `--log-key`. If the log refuses a leaf, the receipt is not issued and the call returns an error to the agent; for an executed call the upstream action has already happened by then, which is the honest outcome, since a receipt that was never logged must not be handed out. The reference log server is `node src/cli.ts log --file log.jsonl --key keys/log.key --port 8787 --token-env AGENT_CUSTODY_LOG_TOKEN`. It serves `POST /append` (token required when one is configured), `GET /root?size=N`, `GET /consistency?old=M&new=N`, and `GET /head`; [verification.md](verification.md) says what each proves.
+Exactly one of the two. The bearer token comes from the named environment variable, never from the file, and a missing variable fails at startup. With a remote log the tree head in each receipt is signed by the log's key, and a verifier must be given that key with `--log-key`. If the log refuses a leaf, the receipt is not issued and the call returns an error to the agent. For an ordinary call the upstream action has already happened by then, and the error says so; a receipt that was never logged must not be handed out. For a tool named in `precommit` the order is reversed, below, and the action never happens. The reference log server is `node src/cli.ts log --file log.jsonl --key keys/log.key --port 8787 --token-env AGENT_CUSTODY_LOG_TOKEN`. It serves `POST /append` (token required when one is configured), `GET /root?size=N`, `GET /consistency?old=M&new=N`, and `GET /head`; [verification.md](verification.md) says what each proves.
+
+`otel`, optional in both the gateway and SDK configs, sends every receipt to the collector you already run as one span over OTLP/HTTP, after the receipt is issued: `"otel": { "url": "http://localhost:4318", "headersEnv": { "x-api-key": "OTEL_KEY" }, "serviceName": "support-agents" }`. The span's trace id is the receipt id, its attributes carry the tool, agent, principal, execution status, policy decision, and log position, and its status is an error only when the upstream failed or errored, since a denial is the policy working. Export is best effort: a collector that is down or refuses costs a line on stderr, never a receipt. Tutorial 18 shows it against a stand-in collector.
 
 `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. A lookup with `"optional": true` is skipped when a `$args.<key>` it needs is absent from the call, and the fact is then simply not present, which a policy tests with `context.facts has <name>`; this is how a policy sees the fact a `memory.write` is about to supersede without denying every write that supersedes nothing.
 
+`precommit` names the consequential tools, or `["*"]` for all of them. For every other tool the gateway forwards the call and then records it, so if the log is unreachable at that moment the side effect exists before its evidence does. For a tool in `precommit` the gateway first signs an authorization statement, everything the receipt will say except the outcome, and appends it to the log. Only if the log took it does the call go upstream. The receipt then embeds that authorization with its own inclusion proof, and a verifier checks that it names this call and sits in the log before the receipt does. If the log will not take it, the call is not forwarded, the agent is told `Not executed`, and the receipt records `execution.status: "withheld"` with the policy's `allow` beside it. The authorization is also written on its own as `receipts/<receiptId>.authorization.json`, which is the evidence that survives if the gateway dies between forwarding and the receipt. Use it for money, for anything irreversible, and for anything a counterparty could later dispute; the cost is one extra log append per call.
+
 **5. Run the gateway.** It speaks MCP on stdin/stdout and logs to stderr only.
 
 ```bash
@@ -203,5 +227,6 @@ The upstream can answer in kind. A result whose `_meta` carries `agent-custody/f
 - **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.
+- **Evidence before the side effect, for the calls that matter.** Without `precommit`, a call is forwarded and then logged, and a log outage at that moment leaves an executed action with no receipt (the agent gets an error saying so). With `precommit`, the authorization is logged first and the call is withheld if that fails. The receipt of a withheld call shows `allow` next to `withheld`, so an auditor can tell a log outage from a denial.
 - **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.

package/docs/verification.md

@@ -77,12 +77,17 @@ execution       observed    executed
 | request args digest | the args in the predicate hash to the digest in the subject | edited arguments |
 | policy decision consistent with execution | allow went with executed or failed; deny went with denied. Skipped when no policy was evaluated | an issuer that executed after a deny |
 | no policy errors on an allow | an allow was not produced while Cedar reported errors | broken fail-closed behaviour |
+| authorization signature (issuer key) | pre-commit receipts only: the embedded authorization statement was signed by the same issuer key as the receipt | an authorization from another gateway, or none the issuer signed |
+| authorization names this call | the committed authorization names this receipt id, tool, argument digest, agent, and principal, and recorded an allow | an authorization spliced in from a different call |
+| authorization tree head signature | the authorization's own tree head is signed by a trusted log or issuer key | a fabricated log position for the authorization |
+| authorization log inclusion proof | the authorization statement is a leaf of that tree | an authorization that was never logged |
+| authorization logged before execution | the authorization's leaf precedes the receipt's leaf, at a tree size no larger than the receipt's | evidence written after the side effect, dressed up as before |
 | tree head signature | the tree head was signed by a trusted issuer key | forged log position |
 | tree head matches inclusion proof size | the proof and the tree head describe the same tree | mismatched bundle parts |
 | log inclusion proof | this exact envelope is a leaf of the tree with that root | receipt never logged, or logged then changed |
 | log file root matches tree head | recomputing the root from your copy of the log at that size gives the same value | your log copy and the issuer's history diverge: deletion, reordering, or edit |
 
-Gateway receipts run seventeen checks, eighteen with a log file. SDK receipts run fewer, because there is no delegation to check, and the report says so on the `principal is claimed` line.
+Gateway receipts run seventeen checks, eighteen with a log file, and five more when the tool was committed before it ran (`precommit` in the gateway config). SDK receipts run fewer, because there is no delegation to check, and the report says so on the `principal is claimed` line.
 
 ## What a verified receipt lets you conclude
 
@@ -95,6 +100,7 @@ For an SDK receipt the statement is shorter: a process holding the application k
 A gateway receipt does **not** support:
 
 - that Stripe really executed the refund. The upstream result is `observed`, not signed by Stripe. That is the first roadmap item.
+- that the side effect exists because the receipt does, unless the receipt carries an authorization. Without one, the call was forwarded first and logged second. With one, the five `authorization` checks establish that the gateway had committed the call to the log before it went out, and a `withheld` execution establishes that it never went out.
 - that the arguments were correct. They are `claimed`: they are what the agent asked for, which is what a receipt should record.
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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": {

package/vectors/audit.json

@@ -7,26 +7,26 @@
       "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": "eyJyb290SGFzaCI6ImFmYjZhMmJjNThiZmQwNDk4YWNjZTZiYTY1MTAxM2IwY2JiYjlmNTI1MWM1NTI0Nzg3NGY5ZWYzOGM3YjAxMjMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDEzOjQ4OjQyLjQ0OVoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJyb290SGFzaCI6IjY5NTU0NGFkNTA4YTEzYTk4NTUxM2YzYjJhMjU0MzhlZjk1MWIyMzk2MGQ1ODU0YjczZjFjYWRkMzJmOTI1YmQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1NVoiLCJ0cmVlU2l6ZSI6MX0=",
         "signatures": [
           {
-            "keyid": "402c5fa71d8055eadffe3e33d7847e543551d24c002a9adf86286f03eb5e4538",
-            "sig": "ZcTaC2tLzE32o+sIj0qFr9lRWaidilkLf6VkVTt6N3McGnp/lISpE0f+naKlRvvQR70kreVm43mwHeMnLBUPCw=="
+            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
+            "sig": "Dy7+sDttHIIQCUzGlIL7Yro+UFGLSPjnLuBJYxFdq2wiqkkAdA3ipo09aSoS0h5BwJMOOEqOTmrGb/ot7HZTCQ=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjJlZTc2MmUzYzdlYzdhODE4ODc4MjUwNDhiZGMwZTEyMWFjNDQzM2VjM2FlNjFjYjU5MjM3MWNmYWMxNDVjZmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDEzOjQ4OjQyLjQ1M1oiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJyb290SGFzaCI6IjU0YzBkNDY1NDhjYzdlYzcyMTQ1MDNlMzFjNzhhYTY5MDZhMmRkY2VhZTI3OTI0N2M5NzRjMjljYmY3Y2Q4NGMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1OFoiLCJ0cmVlU2l6ZSI6Mn0=",
         "signatures": [
           {
-            "keyid": "402c5fa71d8055eadffe3e33d7847e543551d24c002a9adf86286f03eb5e4538",
-            "sig": "++9Ra+7i8vejqY418WnWH4CXA9Rxgb/gDHWrEWgZLYpSPjOdbEXB3XlEArIKaP3+I19eTjK4EQQ07mI2WM3ZCQ=="
+            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
+            "sig": "4belmD02Vv4dufyaCY2N8J48+bxQmMtMfg+jNyD3wadZftcYgQPkZJ2mUx7gCfoh5lOwEu+Wzd5Id1yZlHYvAQ=="
           }
         ]
       },
       "proof": [
-        "ae2d0fcc4034cc32db9e07e9f039358baaef3ae6e22533b9c273ee9042a51d5b"
+        "32a570791cc4546f2b7cf560a2fe3459eb504e0cae52f0ce521fea311f9f15ba"
       ],
       "keys": [
         "log"
@@ -41,26 +41,26 @@
       "description": "The same heads the wrong way round.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjJlZTc2MmUzYzdlYzdhODE4ODc4MjUwNDhiZGMwZTEyMWFjNDQzM2VjM2FlNjFjYjU5MjM3MWNmYWMxNDVjZmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDEzOjQ4OjQyLjQ1M1oiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJyb290SGFzaCI6IjU0YzBkNDY1NDhjYzdlYzcyMTQ1MDNlMzFjNzhhYTY5MDZhMmRkY2VhZTI3OTI0N2M5NzRjMjljYmY3Y2Q4NGMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1OFoiLCJ0cmVlU2l6ZSI6Mn0=",
         "signatures": [
           {
-            "keyid": "402c5fa71d8055eadffe3e33d7847e543551d24c002a9adf86286f03eb5e4538",
-            "sig": "++9Ra+7i8vejqY418WnWH4CXA9Rxgb/gDHWrEWgZLYpSPjOdbEXB3XlEArIKaP3+I19eTjK4EQQ07mI2WM3ZCQ=="
+            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
+            "sig": "4belmD02Vv4dufyaCY2N8J48+bxQmMtMfg+jNyD3wadZftcYgQPkZJ2mUx7gCfoh5lOwEu+Wzd5Id1yZlHYvAQ=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6ImFmYjZhMmJjNThiZmQwNDk4YWNjZTZiYTY1MTAxM2IwY2JiYjlmNTI1MWM1NTI0Nzg3NGY5ZWYzOGM3YjAxMjMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDEzOjQ4OjQyLjQ0OVoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJyb290SGFzaCI6IjY5NTU0NGFkNTA4YTEzYTk4NTUxM2YzYjJhMjU0MzhlZjk1MWIyMzk2MGQ1ODU0YjczZjFjYWRkMzJmOTI1YmQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1NVoiLCJ0cmVlU2l6ZSI6MX0=",
         "signatures": [
           {
-            "keyid": "402c5fa71d8055eadffe3e33d7847e543551d24c002a9adf86286f03eb5e4538",
-            "sig": "ZcTaC2tLzE32o+sIj0qFr9lRWaidilkLf6VkVTt6N3McGnp/lISpE0f+naKlRvvQR70kreVm43mwHeMnLBUPCw=="
+            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
+            "sig": "Dy7+sDttHIIQCUzGlIL7Yro+UFGLSPjnLuBJYxFdq2wiqkkAdA3ipo09aSoS0h5BwJMOOEqOTmrGb/ot7HZTCQ=="
           }
         ]
       },
       "proof": [
-        "ae2d0fcc4034cc32db9e07e9f039358baaef3ae6e22533b9c273ee9042a51d5b"
+        "32a570791cc4546f2b7cf560a2fe3459eb504e0cae52f0ce521fea311f9f15ba"
       ],
       "keys": [
         "log"
@@ -77,26 +77,26 @@
       "description": "Tree heads checked against the app key, which did not sign them.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6ImFmYjZhMmJjNThiZmQwNDk4YWNjZTZiYTY1MTAxM2IwY2JiYjlmNTI1MWM1NTI0Nzg3NGY5ZWYzOGM3YjAxMjMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDEzOjQ4OjQyLjQ0OVoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJyb290SGFzaCI6IjY5NTU0NGFkNTA4YTEzYTk4NTUxM2YzYjJhMjU0MzhlZjk1MWIyMzk2MGQ1ODU0YjczZjFjYWRkMzJmOTI1YmQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1NVoiLCJ0cmVlU2l6ZSI6MX0=",
         "signatures": [
           {
-            "keyid": "402c5fa71d8055eadffe3e33d7847e543551d24c002a9adf86286f03eb5e4538",
-            "sig": "ZcTaC2tLzE32o+sIj0qFr9lRWaidilkLf6VkVTt6N3McGnp/lISpE0f+naKlRvvQR70kreVm43mwHeMnLBUPCw=="
+            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
+            "sig": "Dy7+sDttHIIQCUzGlIL7Yro+UFGLSPjnLuBJYxFdq2wiqkkAdA3ipo09aSoS0h5BwJMOOEqOTmrGb/ot7HZTCQ=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjJlZTc2MmUzYzdlYzdhODE4ODc4MjUwNDhiZGMwZTEyMWFjNDQzM2VjM2FlNjFjYjU5MjM3MWNmYWMxNDVjZmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDEzOjQ4OjQyLjQ1M1oiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJyb290SGFzaCI6IjU0YzBkNDY1NDhjYzdlYzcyMTQ1MDNlMzFjNzhhYTY5MDZhMmRkY2VhZTI3OTI0N2M5NzRjMjljYmY3Y2Q4NGMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1OFoiLCJ0cmVlU2l6ZSI6Mn0=",
         "signatures": [
           {
-            "keyid": "402c5fa71d8055eadffe3e33d7847e543551d24c002a9adf86286f03eb5e4538",
-            "sig": "++9Ra+7i8vejqY418WnWH4CXA9Rxgb/gDHWrEWgZLYpSPjOdbEXB3XlEArIKaP3+I19eTjK4EQQ07mI2WM3ZCQ=="
+            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
+            "sig": "4belmD02Vv4dufyaCY2N8J48+bxQmMtMfg+jNyD3wadZftcYgQPkZJ2mUx7gCfoh5lOwEu+Wzd5Id1yZlHYvAQ=="
           }
         ]
       },
       "proof": [
-        "ae2d0fcc4034cc32db9e07e9f039358baaef3ae6e22533b9c273ee9042a51d5b"
+        "32a570791cc4546f2b7cf560a2fe3459eb504e0cae52f0ce521fea311f9f15ba"
       ],
       "keys": [
         "app"
@@ -114,21 +114,21 @@
       "description": "A proof with a hash removed.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6ImFmYjZhMmJjNThiZmQwNDk4YWNjZTZiYTY1MTAxM2IwY2JiYjlmNTI1MWM1NTI0Nzg3NGY5ZWYzOGM3YjAxMjMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDEzOjQ4OjQyLjQ0OVoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJyb290SGFzaCI6IjY5NTU0NGFkNTA4YTEzYTk4NTUxM2YzYjJhMjU0MzhlZjk1MWIyMzk2MGQ1ODU0YjczZjFjYWRkMzJmOTI1YmQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1NVoiLCJ0cmVlU2l6ZSI6MX0=",
         "signatures": [
           {
-            "keyid": "402c5fa71d8055eadffe3e33d7847e543551d24c002a9adf86286f03eb5e4538",
-            "sig": "ZcTaC2tLzE32o+sIj0qFr9lRWaidilkLf6VkVTt6N3McGnp/lISpE0f+naKlRvvQR70kreVm43mwHeMnLBUPCw=="
+            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
+            "sig": "Dy7+sDttHIIQCUzGlIL7Yro+UFGLSPjnLuBJYxFdq2wiqkkAdA3ipo09aSoS0h5BwJMOOEqOTmrGb/ot7HZTCQ=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjJlZTc2MmUzYzdlYzdhODE4ODc4MjUwNDhiZGMwZTEyMWFjNDQzM2VjM2FlNjFjYjU5MjM3MWNmYWMxNDVjZmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDEzOjQ4OjQyLjQ1M1oiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJyb290SGFzaCI6IjU0YzBkNDY1NDhjYzdlYzcyMTQ1MDNlMzFjNzhhYTY5MDZhMmRkY2VhZTI3OTI0N2M5NzRjMjljYmY3Y2Q4NGMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1OFoiLCJ0cmVlU2l6ZSI6Mn0=",
         "signatures": [
           {
-            "keyid": "402c5fa71d8055eadffe3e33d7847e543551d24c002a9adf86286f03eb5e4538",
-            "sig": "++9Ra+7i8vejqY418WnWH4CXA9Rxgb/gDHWrEWgZLYpSPjOdbEXB3XlEArIKaP3+I19eTjK4EQQ07mI2WM3ZCQ=="
+            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
+            "sig": "4belmD02Vv4dufyaCY2N8J48+bxQmMtMfg+jNyD3wadZftcYgQPkZJ2mUx7gCfoh5lOwEu+Wzd5Id1yZlHYvAQ=="
           }
         ]
       },

package/vectors/canonical.json

@@ -53,18 +53,18 @@
     }
   ],
   "keyid": {
-    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAPkUEkHrnkfYttWXvl/rsSvOqIW8k0HvjQknUWhsI0tI=\n-----END PUBLIC KEY-----\n",
-    "keyid": "b8f05ee956d16bc7e981e1cc6e62739623e3a169d8e14aa43d2c2b32ce956b44"
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEABAiIObrUZgS8uRY1zr5NCUnkr2HqN3K/b+P75pkPX1I=\n-----END PUBLIC KEY-----\n",
+    "keyid": "f660c2bc47886be244642e60bbe1235946e88b8ca864c1c55ef7a8c7a424e184"
   },
   "dsse": {
-    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAPkUEkHrnkfYttWXvl/rsSvOqIW8k0HvjQknUWhsI0tI=\n-----END PUBLIC KEY-----\n",
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEABAiIObrUZgS8uRY1zr5NCUnkr2HqN3K/b+P75pkPX1I=\n-----END PUBLIC KEY-----\n",
     "envelope": {
       "payloadType": "application/vnd.example+json",
       "payload": "eyJoZWxsbyI6IndvcmxkIn0=",
       "signatures": [
         {
-          "keyid": "b8f05ee956d16bc7e981e1cc6e62739623e3a169d8e14aa43d2c2b32ce956b44",
-          "sig": "sSViplEmHbNqomtr8I67F+jIH8JDbmFhGkioDN8nXxpb1yg21/FLP2wqBVHrTMveuCtF4O+EoxO7dlBITeoIBw=="
+          "keyid": "f660c2bc47886be244642e60bbe1235946e88b8ca864c1c55ef7a8c7a424e184",
+          "sig": "DY3PDf89eYVsOJeQJYxT4W2c4NsNeWup+P+Oi/yvp9Fr34uSct3SfueWkmdaAtrmjrenoAdNt8BWV0N+6f0JDA=="
         }
       ]
     },