@agent-custody/receipts 0.1.0 → 0.1.1

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): twelve runnable examples, one per aspect of the code, all executed by the test suite
+- [Tutorials](docs/tutorials.md): fourteen 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
@@ -21,13 +21,7 @@ Anyone holding the public keys can verify a receipt offline. The agent is not tr
 npm install @agent-custody/receipts        # or bun add, pnpm add
 ```
 
-Not on npm yet: the `@agent-custody` scope is still to be claimed. Until then, build from a clone and install the tarball:
-
-```bash
-bun install && bun run build               # at the repository root
-cd packages/receipts && bun pm pack        # writes agent-custody-receipts-0.1.0.tgz here
-npm install /path/to/agent-custody/packages/receipts/agent-custody-receipts-0.1.0.tgz   # in your project
-```
+Published on npm as [`@agent-custody/receipts`](https://www.npmjs.com/package/@agent-custody/receipts): compiled JavaScript with type declarations, Node 22 or later, Apache-2.0.
 
 Record receipts from inside your own agent, no gateway needed. Generate a signing key, point a config at it, wrap the functions the agent calls:
 
@@ -62,7 +56,7 @@ flowchart LR
     G["agent-custody gateway<br/>scope check → fact lookups → Cedar policy"]
     U["Upstream MCP server<br/>Stripe, database, GitHub, ..."]
     R[("receipt bundles<br/>receipts/*.json")]
-    L[("Merkle log<br/>log.jsonl")]
+    L[("Merkle log<br/>local file, or a remote log<br/>run by someone else")]
     V["Verifier<br/>auditor, counterparty, CI job"]
     O["Observability<br/>OTel, LangSmith, Arize"]
 
@@ -173,7 +167,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 twelve step-by-step examples, see docs/tutorials.md
+node examples/01-keys-and-signing.ts     # first of fourteen step-by-step examples, see docs/tutorials.md
 bun run test                             # this package; `bun run test` at the root runs every package
 ```
 
@@ -223,7 +217,8 @@ If a vendor tells you their receipts prove more than the first five rows, ask th
 ```
 src/config.ts      gateway and SDK config schemas, path resolution
 src/crypto.ts      canonical JSON, sha256, Ed25519 keys, DSSE sign/verify
-src/log.ts         Merkle log: append, root, inclusion proof, verify, JSONL persistence
+src/log.ts         Merkle log: append, root, inclusion and consistency proofs, verify, JSONL persistence
+src/log-sink.ts    where leaves go: the local file, or a remote log over HTTP; plus the reference log server
 src/policy.ts      Cedar evaluation wrapper, fail-closed
 src/delegation.ts  signed delegation grants
 src/receipt.ts     receipt statement types and provenance labels
@@ -232,12 +227,12 @@ 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/verify.ts      offline verification and the human-readable report
-src/cli.ts         keygen, grant, gateway, hook, verify
+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/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/          twelve runnable tutorials, one per aspect; each is run by the test suite
+examples/          fourteen runnable tutorials, 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
@@ -254,16 +249,17 @@ 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.
+- 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).
 
 **Next, in the order it pays off**
 
 1. OpenTelemetry export: emit each receipt as a span with the receipt id and issuer kind as attributes, so existing collectors and dashboards carry them without a new pipeline.
 2. Embed upstream signed responses (Stripe webhook signatures, GitHub delivery signatures) so gateway execution can move from `observed` to `attested`.
-3. Consistency proofs between tree heads, so an auditor can check that a later log extends an earlier copy.
-4. An HTTP transport for the gateway, with the grant presented per connection, for a shared deployment rather than one process per agent session.
-5. Delegation chains for sub-agents.
-6. Receiver-attested receipts for agent-to-agent calls.
-7. A TEE-hosted signer, then SD-JWT redaction, then ZK proofs of policy compliance. Not before.
+3. An HTTP transport for the gateway, with the grant presented per connection, for a shared deployment rather than one process per agent session.
+4. Delegation chains for sub-agents.
+5. Receiver-attested receipts for agent-to-agent calls.
+6. A TEE-hosted signer, then SD-JWT redaction, then ZK proofs of policy compliance. Not before.
 
 A Python SDK follows the same shape once the TypeScript adapters have settled.

package/dist/cli.js

@@ -5,16 +5,21 @@ import { loadConfig, loadSdkConfig } from "./config.js";
 import { generateKeyPair, loadPrivateKey, loadPublicKey, writeKeyPair } from "./crypto.js";
 import { createDelegation } from "./delegation.js";
 import { createGateway, serveStdio } from "./gateway.js";
+import { serveLog } from "./log-sink.js";
+import { MerkleLog } from "./log.js";
 import { createSdkIssuer } from "./sdk/index.js";
 import { handleHookEvent } from "./sdk/claude.js";
-import { formatReport, verifyBundle } from "./verify.js";
+import { auditExtends, formatReport, verifyBundle } from "./verify.js";
 const USAGE = `agent-custody <command>
 
   keygen  --dir <dir> --name <name>
   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)
-  verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log <log.jsonl>] [--json]
+  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]
+          checks that the newer receipt's log extends the older one's: nothing between them was rewritten
 `;
 async function main(argv) {
     const [cmd, ...rest] = argv;
@@ -71,10 +76,27 @@ async function main(argv) {
             if (!configPath)
                 throw new Error("hook needs --config or AGENT_CUSTODY_CONFIG");
             const input = JSON.parse(readFileSync(0, "utf8"));
-            const out = handleHookEvent(createSdkIssuer(loadSdkConfig(configPath)), input);
+            const out = await handleHookEvent(createSdkIssuer(loadSdkConfig(configPath)), input);
             console.log(JSON.stringify(out));
             return 0;
         }
+        case "log": {
+            const { values } = parseArgs({
+                args: rest,
+                options: { file: { type: "string" }, key: { type: "string" }, port: { type: "string", default: "8787" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" } },
+            });
+            if (!values.file || !values.key)
+                throw new Error("log needs --file and --key");
+            const token = values["token-env"] ? process.env[values["token-env"]] : undefined;
+            if (values["token-env"] && !token)
+                throw new Error(`log: environment variable ${values["token-env"]} is not set`);
+            const key = loadPrivateKey(values.key);
+            const running = await serveLog(values.file, key, { port: Number(values.port), host: values.host, ...(token ? { tokens: [token] } : {}) });
+            console.error(`agent-custody log: ${running.url} keyid=${key.keyid} file=${values.file} ${token ? "bearer token required" : "open, anyone may append"}`);
+            await new Promise((resolve) => process.once("SIGINT", resolve));
+            await running.close();
+            return 0;
+        }
         case "verify": {
             const { values, positionals } = parseArgs({
                 args: rest,
@@ -83,6 +105,7 @@ async function main(argv) {
                     "issuer-key": { type: "string", multiple: true },
                     "gateway-key": { type: "string", multiple: true },
                     "principal-key": { type: "string", multiple: true },
+                    "log-key": { type: "string", multiple: true },
                     log: { type: "string" },
                     json: { type: "boolean", default: false },
                 },
@@ -95,11 +118,53 @@ async function main(argv) {
             const result = verifyBundle(bundle, {
                 issuerKeys: issuerKeyFiles.map(loadPublicKey),
                 principalKeys: (values["principal-key"] ?? []).map(loadPublicKey),
+                ...(values["log-key"] ? { logKeys: values["log-key"].map(loadPublicKey) } : {}),
                 ...(values.log ? { logFile: values.log } : {}),
             });
             console.log(values.json ? JSON.stringify(result, null, 2) : formatReport(result));
             return result.ok ? 0 : 1;
         }
+        case "audit": {
+            const { values } = parseArgs({
+                args: rest,
+                options: {
+                    older: { type: "string" },
+                    newer: { type: "string" },
+                    log: { type: "string" },
+                    "log-url": { type: "string" },
+                    "issuer-key": { type: "string", multiple: true },
+                    "log-key": { type: "string", multiple: true },
+                    json: { type: "boolean", default: false },
+                },
+            });
+            const keyFiles = [...(values["issuer-key"] ?? []), ...(values["log-key"] ?? [])];
+            if (!values.older || !values.newer || keyFiles.length === 0)
+                throw new Error("audit needs --older, --newer, and at least one --issuer-key or --log-key");
+            if (!values.log === !values["log-url"])
+                throw new Error("audit needs exactly one of --log or --log-url");
+            const older = JSON.parse(readFileSync(values.older, "utf8")).treeHead;
+            const newer = JSON.parse(readFileSync(values.newer, "utf8")).treeHead;
+            const sizeOf = (env) => JSON.parse(Buffer.from(env.payload, "base64").toString()).treeSize;
+            const [m, n] = [sizeOf(older), sizeOf(newer)];
+            let proof;
+            if (values.log)
+                proof = new MerkleLog(values.log).consistencyProof(Math.min(m, n), Math.max(m, n));
+            else {
+                const res = await fetch(new URL(`consistency?old=${Math.min(m, n)}&new=${Math.max(m, n)}`, values["log-url"].endsWith("/") ? values["log-url"] : `${values["log-url"]}/`));
+                if (!res.ok)
+                    throw new Error(`log refused the consistency query: ${res.status}`);
+                proof = (await res.json()).hashes;
+            }
+            const result = auditExtends(older, newer, proof, keyFiles.map(loadPublicKey));
+            if (values.json)
+                console.log(JSON.stringify(result, null, 2));
+            else {
+                for (const c of result.checks)
+                    console.log(`${c.ok ? "PASS" : "FAIL"}  ${c.name}${c.detail ? `  (${c.detail})` : ""}`);
+                console.log(`\nRESULT: ${result.ok ? "NEWER LOG EXTENDS OLDER LOG" : "NOT CONSISTENT"}`);
+            }
+            return result.ok ? 0 : 1;
+        }
         default:
             console.error(USAGE);
             return cmd === undefined || cmd === "--help" || cmd === "-h" ? 0 : 2;

package/dist/config.d.ts

@@ -24,7 +24,11 @@ export declare const GatewayConfigSchema: z.ZodObject<{
         forTools: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>>;
     receiptsDir: z.ZodString;
-    logFile: z.ZodString;
+    logFile: z.ZodOptional<z.ZodString>;
+    log: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        tokenEnv: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;
 export type FactConfig = z.infer<typeof FactSchema>;
@@ -38,7 +42,11 @@ export declare const SdkConfigSchema: z.ZodObject<{
     }, z.core.$strip>;
     policyFile: z.ZodOptional<z.ZodString>;
     receiptsDir: z.ZodString;
-    logFile: z.ZodString;
+    logFile: z.ZodOptional<z.ZodString>;
+    log: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        tokenEnv: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     framework: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SdkConfig = z.infer<typeof SdkConfigSchema>;

package/dist/config.js

@@ -1,6 +1,10 @@
 import { z } from "zod";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
+/** Where receipts are logged: a local file, or a log reached over HTTP whose bearer token comes from an environment variable. */
+const LogSchema = z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional() });
+const oneLog = { message: "exactly one of logFile or log is required" };
+const hasOneLog = (c) => (c.logFile ? 1 : 0) + (c.log ? 1 : 0) === 1;
 const FactSchema = z.object({
     /** key under context.facts */
     name: z.string().min(1),
@@ -23,8 +27,9 @@ export const GatewayConfigSchema = z.object({
     policyFile: z.string(),
     facts: z.array(FactSchema).default([]),
     receiptsDir: z.string(),
-    logFile: z.string(),
-});
+    logFile: z.string().optional(),
+    log: LogSchema.optional(),
+}).refine(hasOneLog, oneLog);
 /** Loads a config file and resolves every path relative to the file's directory. */
 export function loadConfig(path) {
     const cfg = GatewayConfigSchema.parse(JSON.parse(readFileSync(path, "utf8")));
@@ -37,7 +42,7 @@ export function loadConfig(path) {
         trustedPrincipalKeys: cfg.trustedPrincipalKeys.map(r),
         policyFile: r(cfg.policyFile),
         receiptsDir: r(cfg.receiptsDir),
-        logFile: r(cfg.logFile),
+        ...(cfg.logFile ? { logFile: r(cfg.logFile) } : {}),
     };
 }
 export const SdkConfigSchema = z.object({
@@ -48,10 +53,11 @@ export const SdkConfigSchema = z.object({
     /** optional Cedar policy; when present, wrapped tools and PreToolUse hooks can deny */
     policyFile: z.string().optional(),
     receiptsDir: z.string(),
-    logFile: z.string(),
+    logFile: z.string().optional(),
+    log: LogSchema.optional(),
     /** free-text label of the host framework, e.g. "claude-code", "openai-agents" */
     framework: z.string().optional(),
-});
+}).refine(hasOneLog, oneLog);
 export function loadSdkConfig(path) {
     const cfg = SdkConfigSchema.parse(JSON.parse(readFileSync(path, "utf8")));
     const base = dirname(resolve(path));
@@ -61,6 +67,6 @@ export function loadSdkConfig(path) {
         identity: { keyFile: r(cfg.identity.keyFile) },
         ...(cfg.policyFile ? { policyFile: r(cfg.policyFile) } : {}),
         receiptsDir: r(cfg.receiptsDir),
-        logFile: r(cfg.logFile),
+        ...(cfg.logFile ? { logFile: r(cfg.logFile) } : {}),
     };
 }

package/dist/gateway.js

@@ -10,6 +10,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { digestOf, loadPrivateKey, loadPublicKey } from "./crypto.js";
 import { delegationValidAt, verifyDelegation } from "./delegation.js";
 import { createIssuer } from "./issue.js";
+import { openLog } from "./log-sink.js";
 import { evaluate, policyDigest } from "./policy.js";
 export const GATEWAY_VERSION = "0.1.0";
 export const RECEIPT_META_KEY = "agent-custody/receipt";
@@ -54,7 +55,7 @@ export async function createGateway(cfg) {
     const principalKeyid = grant.keyid;
     const policyText = readFileSync(cfg.policyFile, "utf8");
     const pDigest = policyDigest(policyText);
-    const issuer = createIssuer(gatewayKey, cfg.receiptsDir, cfg.logFile);
+    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 }));
@@ -107,7 +108,7 @@ export async function createGateway(cfg) {
         else {
             execution = { status: "denied", reason: [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched", provenance: "observed" };
         }
-        issuer.issue({
+        await issuer.issue({
             receiptId,
             timestamp,
             issuer: { kind: "gateway", keyid: issuer.keyid, version: GATEWAY_VERSION },

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from "./delegation.ts";
 export * from "./gateway.ts";
 export * from "./issue.ts";
 export * from "./log.ts";
+export * from "./log-sink.ts";
 export * from "./policy.ts";
 export * from "./receipt.ts";
 export * from "./verify.ts";

package/dist/index.js

@@ -5,6 +5,7 @@ export * from "./delegation.js";
 export * from "./gateway.js";
 export * from "./issue.js";
 export * from "./log.js";
+export * from "./log-sink.js";
 export * from "./policy.js";
 export * from "./receipt.js";
 export * from "./verify.js";

package/dist/issue.d.ts

@@ -1,7 +1,11 @@
 import { type KeyPair } from "./crypto.ts";
+import { type LogSink } from "./log-sink.ts";
 import { type ReceiptBundle, type ReceiptPredicate } from "./receipt.ts";
 export interface Issuer {
     keyid: string;
-    issue(predicate: ReceiptPredicate): ReceiptBundle;
+    log: LogSink;
+    /** Signs the statement, appends it to the log, writes the bundle. Rejects if the log refuses the leaf; no bundle is written then. */
+    issue(predicate: ReceiptPredicate): Promise<ReceiptBundle>;
 }
-export declare function createIssuer(key: KeyPair, receiptsDir: string, logFile: string): Issuer;
+/** `log` is a sink, or a file path for the local log with tree heads signed by the issuer's key. */
+export declare function createIssuer(key: KeyPair, receiptsDir: string, log: string | LogSink): Issuer;

package/dist/issue.js

@@ -2,18 +2,19 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { canonicalize, dsseSign } from "./crypto.js";
-import { MerkleLog } from "./log.js";
-import { buildStatement, RECEIPT_TYPE, TREEHEAD_TYPE } from "./receipt.js";
-export function createIssuer(key, receiptsDir, logFile) {
-    const log = new MerkleLog(logFile);
+import { fileLog } from "./log-sink.js";
+import { buildStatement, RECEIPT_TYPE } from "./receipt.js";
+/** `log` is a sink, or a file path for the local log with tree heads signed by the issuer's key. */
+export function createIssuer(key, receiptsDir, log) {
+    const sink = typeof log === "string" ? fileLog(log, key) : log;
     mkdirSync(receiptsDir, { recursive: true });
     return {
         keyid: key.keyid,
-        issue(predicate) {
+        log: sink,
+        async issue(predicate) {
             const envelope = dsseSign(RECEIPT_TYPE, buildStatement(predicate), key);
-            const entry = log.append(canonicalize(envelope));
-            const treeHead = dsseSign(TREEHEAD_TYPE, { treeSize: entry.treeSize, rootHash: entry.rootHash, timestamp: new Date().toISOString() }, key);
-            const bundle = { envelope, treeHead, inclusion: { leafIndex: entry.leafIndex, treeSize: entry.treeSize, hashes: entry.hashes } };
+            const entry = await sink.append(canonicalize(envelope));
+            const bundle = { envelope, treeHead: entry.treeHead, inclusion: entry.inclusion };
             writeFileSync(join(receiptsDir, `${predicate.receiptId}.json`), JSON.stringify(bundle, null, 2));
             return bundle;
         },

package/dist/log-sink.d.ts

@@ -0,0 +1,53 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type Envelope, type KeyPair } from "./crypto.ts";
+import { type InclusionProof } from "./log.ts";
+export interface LogAppend {
+    inclusion: InclusionProof;
+    /** signed TreeHead; the signature's keyid says who runs the log */
+    treeHead: Envelope;
+}
+export interface LogSink {
+    readonly kind: "file" | "http";
+    /** the file path or the URL, for reports */
+    readonly where: string;
+    append(leaf: string): Promise<LogAppend>;
+}
+/** A local JSONL Merkle log. Tree heads are signed with the given key, normally the issuer's own. */
+export declare function fileLog(file: string, key: KeyPair): LogSink;
+export interface HttpLogOptions {
+    /** sent as a bearer token; the log decides what it is worth */
+    token?: string;
+    fetch?: typeof fetch;
+}
+/** A log reached over HTTP: POST <url>/append with {leaf}, expecting a LogAppend back. */
+export declare function httpLog(url: string, opts?: HttpLogOptions): LogSink;
+export interface LogConfig {
+    logFile?: string | undefined;
+    log?: {
+        url: string;
+        tokenEnv?: string | undefined;
+    } | undefined;
+}
+/** The sink a config asks for: a remote log when `log` is set, otherwise the local file. */
+export declare function openLog(cfg: LogConfig, key: KeyPair): LogSink;
+export interface LogServerOptions {
+    /** bearer tokens accepted on append; when empty, anyone may append */
+    tokens?: string[];
+}
+/**
+ * The reference log server as a node:http request handler.
+ *   POST /append  {leaf}   -> LogAppend, tree head signed with the log's key
+ *   GET  /root?size=N      -> {treeSize, rootHash}, for auditors checking a tree head against the log
+ *   GET  /consistency?old=M&new=N -> {oldSize, newSize, hashes}, proof that the log at N extends the log at M
+ *   GET  /head             -> {treeHead}, the current tree head signed with the log's key
+ */
+export declare function logHandler(file: string, key: KeyPair, opts?: LogServerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface RunningLog {
+    url: string;
+    close(): Promise<void>;
+}
+/** Starts the reference log server. Port 0 picks a free port. */
+export declare function serveLog(file: string, key: KeyPair, opts: LogServerOptions & {
+    port: number;
+    host?: string;
+}): Promise<RunningLog>;

package/dist/log-sink.js

@@ -0,0 +1,136 @@
+// Where log leaves go.
+// The file sink is the local Merkle log, with tree heads signed by the issuer's own key: tamper-evident, but the
+// operator holds the file. The HTTP sink hands each leaf to a log run by someone else, who signs the tree head with
+// their key. A verifier who trusts that key learns the receipt was in a log the operator cannot rewrite.
+// logHandler and serveLog are the other side: a reference log server over node:http, the same code a hosted log runs.
+import { timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { dsseSign } from "./crypto.js";
+import { MerkleLog } from "./log.js";
+import { TREEHEAD_TYPE } from "./receipt.js";
+function appendSigned(log, key, leaf) {
+    const e = log.append(leaf);
+    const head = { treeSize: e.treeSize, rootHash: e.rootHash, timestamp: new Date().toISOString() };
+    return { inclusion: { leafIndex: e.leafIndex, treeSize: e.treeSize, hashes: e.hashes }, treeHead: dsseSign(TREEHEAD_TYPE, head, key) };
+}
+/** A local JSONL Merkle log. Tree heads are signed with the given key, normally the issuer's own. */
+export function fileLog(file, key) {
+    const log = new MerkleLog(file);
+    return {
+        kind: "file",
+        where: file,
+        async append(leaf) {
+            return appendSigned(log, key, leaf);
+        },
+    };
+}
+/** A log reached over HTTP: POST <url>/append with {leaf}, expecting a LogAppend back. */
+export function httpLog(url, opts = {}) {
+    const f = opts.fetch ?? fetch;
+    const base = url.endsWith("/") ? url : `${url}/`;
+    return {
+        kind: "http",
+        where: url,
+        async append(leaf) {
+            const res = await f(new URL("append", base), {
+                method: "POST",
+                headers: { "content-type": "application/json", ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}) },
+                body: JSON.stringify({ leaf }),
+            });
+            if (!res.ok)
+                throw new Error(`log ${url} refused the append: ${res.status} ${(await res.text()).slice(0, 200)}`);
+            const body = (await res.json());
+            if (!body.inclusion || !body.treeHead)
+                throw new Error(`log ${url} returned a malformed append result`);
+            return body;
+        },
+    };
+}
+/** The sink a config asks for: a remote log when `log` is set, otherwise the local file. */
+export function openLog(cfg, key) {
+    if (cfg.log) {
+        const token = cfg.log.tokenEnv ? process.env[cfg.log.tokenEnv] : undefined;
+        if (cfg.log.tokenEnv && !token)
+            throw new Error(`log token: environment variable ${cfg.log.tokenEnv} is not set`);
+        return httpLog(cfg.log.url, token === undefined ? {} : { token });
+    }
+    if (!cfg.logFile)
+        throw new Error("config needs logFile or log.url");
+    return fileLog(cfg.logFile, key);
+}
+/**
+ * The reference log server as a node:http request handler.
+ *   POST /append  {leaf}   -> LogAppend, tree head signed with the log's key
+ *   GET  /root?size=N      -> {treeSize, rootHash}, for auditors checking a tree head against the log
+ *   GET  /consistency?old=M&new=N -> {oldSize, newSize, hashes}, proof that the log at N extends the log at M
+ *   GET  /head             -> {treeHead}, the current tree head signed with the log's key
+ */
+export function logHandler(file, key, opts = {}) {
+    const log = new MerkleLog(file);
+    const tokens = opts.tokens ?? [];
+    const authorized = (req) => {
+        if (tokens.length === 0)
+            return true;
+        const h = req.headers.authorization ?? "";
+        const given = Buffer.from(h.startsWith("Bearer ") ? h.slice(7) : "");
+        return tokens.some((t) => {
+            const want = Buffer.from(t);
+            return want.length === given.length && timingSafeEqual(want, given);
+        });
+    };
+    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");
+        if (req.method === "POST" && url.pathname.endsWith("/append")) {
+            if (!authorized(req))
+                return json(401, { error: "unauthorized" });
+            let body = "";
+            for await (const chunk of req)
+                body += chunk;
+            let leaf;
+            try {
+                leaf = JSON.parse(body).leaf;
+            }
+            catch {
+                return json(400, { error: "body must be JSON {leaf}" });
+            }
+            if (typeof leaf !== "string" || leaf.length === 0)
+                return json(400, { error: "leaf must be a non-empty string" });
+            return json(200, appendSigned(log, key, leaf));
+        }
+        if (req.method === "GET" && url.pathname.endsWith("/root")) {
+            const size = url.searchParams.has("size") ? Number(url.searchParams.get("size")) : log.size;
+            if (!Number.isInteger(size) || size < 0 || size > log.size)
+                return json(400, { error: `size must be an integer in 0..${log.size}` });
+            return json(200, { treeSize: size, rootHash: log.root(size) });
+        }
+        if (req.method === "GET" && url.pathname.endsWith("/consistency")) {
+            const oldSize = Number(url.searchParams.get("old"));
+            const newSize = url.searchParams.has("new") ? Number(url.searchParams.get("new")) : log.size;
+            if (![oldSize, newSize].every(Number.isInteger) || oldSize < 0 || oldSize > newSize || newSize > log.size)
+                return json(400, { error: `old and new must be integers with 0 <= old <= new <= ${log.size}` });
+            return json(200, { oldSize, newSize, hashes: log.consistencyProof(oldSize, newSize) });
+        }
+        if (req.method === "GET" && url.pathname.endsWith("/head")) {
+            const head = { treeSize: log.size, rootHash: log.root(), timestamp: new Date().toISOString() };
+            return json(200, { treeHead: dsseSign(TREEHEAD_TYPE, head, key) });
+        }
+        return json(404, { error: "not found" });
+    };
+}
+/** Starts the reference log server. Port 0 picks a free port. */
+export function serveLog(file, key, opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const server = createServer((req, res) => {
+        void logHandler(file, key, opts)(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/dist/log.d.ts

@@ -4,6 +4,10 @@ export interface InclusionProof {
     hashes: string[];
 }
 export declare function leafHash(data: string): Buffer;
+/** Proof that the tree of size newSize extends the tree of size oldSize. Empty when oldSize is 0 or equal to newSize. */
+export declare function consistencyProof(leafHashes: Buffer[], oldSize: number, newSize?: number): string[];
+/** RFC 9162 section 2.1.4.2. Pure: needs only the two sizes, the two roots, and the proof. */
+export declare function verifyConsistency(oldSize: number, oldRootHex: string, newSize: number, newRootHex: string, proofHex: string[]): boolean;
 export declare function rootOf(leafHashes: Buffer[], size?: number): string;
 export declare function inclusionProof(leafHashes: Buffer[], leafIndex: number, treeSize?: number): InclusionProof;
 /** RFC 9162 section 2.1.3.2 verification. Pure function: needs only the leaf hash, proof and claimed root. */
@@ -18,6 +22,8 @@ export declare class MerkleLog {
         rootHash: string;
     };
     root(size?: number): string;
+    /** Proof that this log at newSize extends its own earlier state at oldSize. */
+    consistencyProof(oldSize: number, newSize?: number): string[];
     /** Reads a log file and returns the root at the given size, for auditors holding a copy of the log. */
     static rootFromFile(file: string, size: number): string;
 }

package/dist/log.js

@@ -38,6 +38,64 @@ function path(m, leaves, lo, hi) {
         ? [...path(m, leaves, lo, lo + k), mth(leaves, lo + k, hi)]
         : [...path(m - k, leaves, lo + k, hi), mth(leaves, lo, lo + k)];
 }
+/** RFC 9162 section 2.1.4.1: SUBPROOF(m, D[n], b). */
+function subproof(m, leaves, lo, hi, b) {
+    const n = hi - lo;
+    if (m === n)
+        return b ? [] : [mth(leaves, lo, hi)];
+    const k = split(n);
+    return m <= k
+        ? [...subproof(m, leaves, lo, lo + k, b), mth(leaves, lo + k, hi)]
+        : [...subproof(m - k, leaves, lo + k, hi, false), mth(leaves, lo, lo + k)];
+}
+/** Proof that the tree of size newSize extends the tree of size oldSize. Empty when oldSize is 0 or equal to newSize. */
+export function consistencyProof(leafHashes, oldSize, newSize = leafHashes.length) {
+    if (oldSize < 0 || oldSize > newSize || newSize > leafHashes.length)
+        throw new Error("sizes out of range");
+    if (oldSize === 0 || oldSize === newSize)
+        return [];
+    return subproof(oldSize, leafHashes, 0, newSize, true).map((b) => b.toString("hex"));
+}
+/** RFC 9162 section 2.1.4.2. Pure: needs only the two sizes, the two roots, and the proof. */
+export function verifyConsistency(oldSize, oldRootHex, newSize, newRootHex, proofHex) {
+    if (oldSize < 0 || oldSize > newSize)
+        return false;
+    if (oldSize === newSize)
+        return proofHex.length === 0 && oldRootHex === newRootHex;
+    if (oldSize === 0)
+        return proofHex.length === 0;
+    if (proofHex.length === 0)
+        return false;
+    const proof = proofHex.map((x) => Buffer.from(x, "hex"));
+    if ((oldSize & (oldSize - 1)) === 0)
+        proof.unshift(Buffer.from(oldRootHex, "hex"));
+    let fn = oldSize - 1;
+    let sn = newSize - 1;
+    while (fn % 2 === 1) {
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    let fr = proof[0];
+    let sr = proof[0];
+    for (const c of proof.slice(1)) {
+        if (sn === 0)
+            return false;
+        if (fn % 2 === 1 || fn === sn) {
+            fr = nodeHash(c, fr);
+            sr = nodeHash(c, sr);
+            while (fn % 2 === 0 && fn !== 0) {
+                fn = Math.floor(fn / 2);
+                sn = Math.floor(sn / 2);
+            }
+        }
+        else {
+            sr = nodeHash(sr, c);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 && fr.toString("hex") === oldRootHex && sr.toString("hex") === newRootHex;
+}
 export function rootOf(leafHashes, size = leafHashes.length) {
     return mth(leafHashes, 0, size).toString("hex");
 }
@@ -102,6 +160,10 @@ export class MerkleLog {
     root(size = this.size) {
         return rootOf(this.hashes, size);
     }
+    /** Proof that this log at newSize extends its own earlier state at oldSize. */
+    consistencyProof(oldSize, newSize = this.size) {
+        return consistencyProof(this.hashes, oldSize, newSize);
+    }
     /** Reads a log file and returns the root at the given size, for auditors holding a copy of the log. */
     static rootFromFile(file, size) {
         return new MerkleLog(file).root(size);

package/dist/sdk/claude.d.ts

@@ -22,7 +22,7 @@ export interface HookOutput {
  * so the host's normal permission flow still applies. This adapter never auto-approves.
  * PostToolUse / PostToolUseFailure: issue the receipt for the completed call.
  */
-export declare function handleHookEvent(issuer: SdkIssuer, input: HookInput): HookOutput;
+export declare function handleHookEvent(issuer: SdkIssuer, input: HookInput): Promise<HookOutput>;
 /**
  * Hooks for the Claude Agent SDK's query({ hooks }) option. Register all three events.
  * Typed loosely on purpose so this file does not depend on the SDK package.

package/dist/sdk/claude.js

@@ -11,14 +11,14 @@ function toEvent(input) {
  * so the host's normal permission flow still applies. This adapter never auto-approves.
  * PostToolUse / PostToolUseFailure: issue the receipt for the completed call.
  */
-export function handleHookEvent(issuer, input) {
+export async function handleHookEvent(issuer, input) {
     const ev = toEvent(input);
     switch (input.hook_event_name) {
         case "PreToolUse": {
             const policy = issuer.decide(ev);
             if (policy && policy.decision === "deny") {
                 const reason = [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched";
-                const bundle = issuer.record(ev, { status: "denied", reason }, policy);
+                const bundle = await issuer.record(ev, { status: "denied", reason }, policy);
                 return {
                     continue: true,
                     hookSpecificOutput: {
@@ -31,10 +31,10 @@ export function handleHookEvent(issuer, input) {
             return {};
         }
         case "PostToolUse":
-            issuer.record(ev, { status: "executed", result: input.tool_response ?? null }, issuer.decide(ev));
+            await issuer.record(ev, { status: "executed", result: input.tool_response ?? null }, issuer.decide(ev));
             return {};
         case "PostToolUseFailure":
-            issuer.record(ev, { status: "failed", result: input.error ?? input.tool_response ?? null }, issuer.decide(ev));
+            await issuer.record(ev, { status: "failed", result: input.error ?? input.tool_response ?? null }, issuer.decide(ev));
             return {};
         default:
             return {};

package/dist/sdk/index.d.ts

@@ -1,4 +1,5 @@
 import type { SdkConfig } from "../config.ts";
+import { type LogSink } from "../log-sink.ts";
 import { type PolicyDecision } from "../policy.ts";
 import type { ReceiptBundle } from "../receipt.ts";
 export declare const SDK_VERSION = "0.1.0";
@@ -24,10 +25,12 @@ export type Outcome = {
 export interface SdkIssuer {
     agentId: string;
     keyid: string;
+    /** where the leaves go: the local file or the remote log */
+    log: LogSink;
     /** Evaluates the configured policy for a call. Returns null when no policy is configured. */
     decide(ev: ToolEvent): PolicyDecision | null;
-    /** Issues one receipt for a completed, failed, denied, or errored call. */
-    record(ev: ToolEvent, outcome: Outcome, policy?: PolicyDecision | null): ReceiptBundle;
+    /** Issues one receipt for a completed, failed, denied, or errored call. Rejects if the log refuses it. */
+    record(ev: ToolEvent, outcome: Outcome, policy?: PolicyDecision | null): Promise<ReceiptBundle>;
     /** Wraps a tool function: decide, run, record. Throws PolicyDeniedError on deny, after issuing the denial receipt. */
     wrap<A extends Record<string, unknown>, R>(tool: string, fn: (args: A) => R | Promise<R>, meta?: Omit<ToolEvent, "tool" | "args">): (args: A) => Promise<R>;
 }

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 { openLog } from "../log-sink.js";
 import { evaluate } from "../policy.js";
 export const SDK_VERSION = "0.1.0";
 export class PolicyDeniedError extends Error {
@@ -20,7 +21,7 @@ export class PolicyDeniedError extends Error {
 }
 export function createSdkIssuer(cfg) {
     const key = loadPrivateKey(cfg.identity.keyFile);
-    const issuer = createIssuer(key, cfg.receiptsDir, cfg.logFile);
+    const issuer = createIssuer(key, cfg.receiptsDir, openLog(cfg, key));
     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) {
@@ -47,6 +48,7 @@ export function createSdkIssuer(cfg) {
     return {
         agentId: cfg.agentId,
         keyid: issuer.keyid,
+        log: issuer.log,
         decide,
         record,
         wrap(tool, fn, meta = {}) {
@@ -55,16 +57,16 @@ export function createSdkIssuer(cfg) {
                 const policy = decide(ev);
                 if (policy && policy.decision === "deny") {
                     const reason = [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched";
-                    const bundle = record(ev, { status: "denied", reason }, policy);
+                    const bundle = await record(ev, { status: "denied", reason }, policy);
                     throw new PolicyDeniedError(tool, reason, receiptIdOf(bundle));
                 }
                 try {
                     const result = await fn(args);
-                    record(ev, { status: "executed", result }, policy);
+                    await record(ev, { status: "executed", result }, policy);
                     return result;
                 }
                 catch (e) {
-                    record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
+                    await record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
                     throw e;
                 }
             };

package/dist/sdk/langchain.d.ts

@@ -8,8 +8,8 @@ export declare class ReceiptCallbackHandler extends BaseCallbackHandler {
     handleToolStart(tool: {
         name?: string;
     }, input: string, runId: string, _parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, runName?: string, toolCallId?: string): void;
-    handleToolEnd(output: unknown, runId: string): void;
-    handleToolError(err: Error, runId: string): void;
+    handleToolEnd(output: unknown, runId: string): Promise<void>;
+    handleToolError(err: Error, runId: string): Promise<void>;
 }
 /** Convenience: `tool.invoke(args, receiptCallbacks(issuer))`, or spread into any RunnableConfig. */
 export declare function receiptCallbacks(issuer: SdkIssuer): {

package/dist/sdk/langchain.js

@@ -40,19 +40,19 @@ export class ReceiptCallbackHandler extends BaseCallbackHandler {
         const name = runName ?? tool.name ?? "unknown";
         this.pending.set(runId, { tool: name, args: parseArgs(input), session: { id: null, toolUseId: toolCallId ?? null } });
     }
-    handleToolEnd(output, runId) {
+    async handleToolEnd(output, runId) {
         const ev = this.pending.get(runId);
         if (!ev)
             return;
         this.pending.delete(runId);
-        this.issuer.record(ev, { status: "executed", result: unwrapOutput(output) }, null);
+        await this.issuer.record(ev, { status: "executed", result: unwrapOutput(output) }, null);
     }
-    handleToolError(err, runId) {
+    async handleToolError(err, runId) {
         const ev = this.pending.get(runId);
         if (!ev)
             return;
         this.pending.delete(runId);
-        this.issuer.record(ev, { status: "error", error: err.message }, null);
+        await this.issuer.record(ev, { status: "error", error: err.message }, null);
     }
 }
 /** Convenience: `tool.invoke(args, receiptCallbacks(issuer))`, or spread into any RunnableConfig. */

package/dist/sdk/openai-agents.js

@@ -33,16 +33,16 @@ export function wrapTools(issuer, tools) {
             const policy = issuer.decide(ev);
             if (policy && policy.decision === "deny") {
                 const reason = [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched";
-                const bundle = issuer.record(ev, { status: "denied", reason }, policy);
+                const bundle = await issuer.record(ev, { status: "denied", reason }, policy);
                 return `Denied by policy: ${reason} (receipt ${receiptIdOf(bundle)})`;
             }
             try {
                 const result = await t.invoke(ctx, input, details);
-                issuer.record(ev, { status: "executed", result: parseResult(result) }, policy);
+                await issuer.record(ev, { status: "executed", result: parseResult(result) }, policy);
                 return result;
             }
             catch (e) {
-                issuer.record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
+                await issuer.record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
                 throw e;
             }
         };
@@ -61,6 +61,7 @@ export function observeRunner(issuer, runner) {
         const callId = details?.toolCall?.callId ?? "";
         const ev = pending.get(callId) ?? { tool: tool.name, args: {}, session: { id: null, toolUseId: callId || null } };
         pending.delete(callId);
-        issuer.record(ev, { status: "executed", result: parseResult(result) }, null);
+        // The runner does not await listeners. A log that refuses the leaf is reported on stderr; nothing else can see it here.
+        issuer.record(ev, { status: "executed", result: parseResult(result) }, null).catch((e) => console.error(`agent-custody: receipt not issued: ${e instanceof Error ? e.message : e}`));
     });
 }

package/dist/sdk/vercel-ai.js

@@ -16,16 +16,16 @@ export function wrapTools(issuer, tools) {
             const policy = issuer.decide(ev);
             if (policy && policy.decision === "deny") {
                 const reason = [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched";
-                const bundle = issuer.record(ev, { status: "denied", reason }, policy);
+                const bundle = await issuer.record(ev, { status: "denied", reason }, policy);
                 throw new PolicyDeniedError(name, reason, receiptIdOf(bundle));
             }
             try {
                 const result = await original(input, options);
-                issuer.record(ev, { status: "executed", result }, policy);
+                await issuer.record(ev, { status: "executed", result }, policy);
                 return result;
             }
             catch (e) {
-                issuer.record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
+                await issuer.record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
                 throw e;
             }
         };

package/dist/verify.d.ts

@@ -1,5 +1,5 @@
-import { type PublicKeyRef } from "./crypto.ts";
-import { type ReceiptBundle, type ReceiptStatement } from "./receipt.ts";
+import { type Envelope, type PublicKeyRef } from "./crypto.ts";
+import { type ReceiptBundle, type ReceiptStatement, type TreeHead } from "./receipt.ts";
 export interface Check {
     name: string;
     ok: boolean;
@@ -9,6 +9,8 @@ export interface VerifyOptions {
     /** keys trusted to have issued receipts: gateway keys, SDK application keys */
     issuerKeys: PublicKeyRef[];
     principalKeys: PublicKeyRef[];
+    /** keys of logs run by someone other than the issuer; tree heads are checked against these and the issuer keys */
+    logKeys?: PublicKeyRef[];
     /** If given, the root is recomputed from this log file at the receipt's tree size and compared. */
     logFile?: string;
 }
@@ -18,5 +20,16 @@ export interface VerifyResult {
     statement: ReceiptStatement | null;
 }
 export declare function verifyBundle(bundle: ReceiptBundle, opts: VerifyOptions): VerifyResult;
+export interface AuditResult {
+    ok: boolean;
+    checks: Check[];
+    older: TreeHead | null;
+    newer: TreeHead | null;
+}
+/**
+ * Does the newer tree head extend the older one? Both must be signed by a trusted log or issuer key, and the proof
+ * must be the log's consistency proof between the two sizes. A pass means nothing in the older log was rewritten.
+ */
+export declare function auditExtends(older: Envelope, newer: Envelope, proof: string[], keys: PublicKeyRef[]): AuditResult;
 /** Human-readable report: checks, then every field with its provenance so the reader knows what was proven vs. claimed. */
 export declare function formatReport(r: VerifyResult): string;

package/dist/verify.js

@@ -1,7 +1,7 @@
 // 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 { leafHash, MerkleLog, verifyConsistency, 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) {
@@ -49,8 +49,10 @@ export function verifyBundle(bundle, opts) {
         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);
+    const logKeys = opts.logKeys ?? [];
+    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);
     if (th.ok) {
         const head = th.payload;
         add("tree head matches inclusion proof size", head.treeSize === bundle.inclusion.treeSize);
@@ -70,6 +72,31 @@ export function verifyBundle(bundle, opts) {
     }
     return done(st);
 }
+/**
+ * Does the newer tree head extend the older one? Both must be signed by a trusted log or issuer key, and the proof
+ * must be the log's consistency proof between the two sizes. A pass means nothing in the older log was rewritten.
+ */
+export function auditExtends(older, newer, proof, keys) {
+    const checks = [];
+    const add = (name, ok, detail) => {
+        checks.push(detail === undefined ? { name, ok } : { name, ok, detail });
+        return ok;
+    };
+    const decode = (label, env) => {
+        const v = dsseVerify(env, keys);
+        add(`${label} tree head signature`, v.ok && env.payloadType === TREEHEAD_TYPE, v.ok ? `keyid ${short(v.keyid)}` : v.error);
+        return v.ok ? v.payload : null;
+    };
+    const a = decode("older", older);
+    const b = decode("newer", newer);
+    if (!a || !b)
+        return { ok: false, checks, older: a, newer: b };
+    if (!add("older is not larger than newer", a.treeSize <= b.treeSize, `${a.treeSize} -> ${b.treeSize}`))
+        return { ok: false, checks, older: a, newer: b };
+    const consistent = verifyConsistency(a.treeSize, a.rootHash, b.treeSize, b.rootHash, proof);
+    add("newer log extends older log", consistent, consistent ? `${proof.length} proof hashes` : "history was rewritten, or the proof is for other tree heads");
+    return { ok: checks.every((c) => c.ok), checks, older: a, newer: b };
+}
 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",

package/docs/sdk.md

@@ -28,7 +28,7 @@ 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. Generate the key with `node src/cli.ts keygen --dir keys --name app`.
+`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`.
 
 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.
 
@@ -154,9 +154,11 @@ 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);
+const bundle = await issuer.record({ tool, args, model, session }, { status: "executed", result }, decision);
 ```
 
+`record` returns a promise because the log may be remote. It rejects, and writes no bundle, if the log refuses the leaf. `handleHookEvent` is asynchronous for the same reason. The record-only adapters that cannot await, such as `observeRunner`, report a refused leaf on stderr.
+
 ## Which adapter enforces
 
 | framework | enforce + record | record only |

package/docs/tutorials.md

@@ -22,6 +22,8 @@ Suggested reading order is the numbering. Output lands in `examples-out/`, which
 | 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` |
+| 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` |
 
 ## How policies are defined, in one paragraph
 

package/docs/usage.md

@@ -79,6 +79,14 @@ 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.
 
+`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.
+
 `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.

package/docs/verification.md

@@ -6,7 +6,9 @@ A verifier needs three things and no network access:
 2. the issuer's public key: the gateway key, or the application key for SDK receipts
 3. the principal's public key, for gateway receipts, which carry a signed delegation
 
-A fourth is optional: a copy of the issuer's log file, which lets the verifier confirm the receipt sits in a log whose root the verifier recomputed, not one the issuer merely asserted.
+A fourth is optional: a copy of the log file, which lets the verifier confirm the receipt sits in a log whose root the verifier recomputed, not one the issuer merely asserted.
+
+When the issuer logs to a remote log, the tree head is signed by the log's key rather than the issuer's. The verifier then needs that public key too, and the report says which key signed the tree head. That is the point of a remote log: a tree head signed by a party that is not the operator says the receipt was in a log the operator could not rewrite. A tree head signed by the issuer's own key says only that the issuer has not changed its story since.
 
 ## From the command line
 
@@ -14,6 +16,7 @@ A fourth is optional: a copy of the issuer's log file, which lets the verifier c
 node src/cli.ts verify receipts/<id>.json \
   --issuer-key keys/gateway.pub \
   --principal-key keys/principal.pub \
+  --log-key keys/log.pub \  # only for receipts logged to a remote log
   --log log.jsonl          # optional
 ```
 
@@ -106,6 +109,7 @@ const bundle = JSON.parse(readFileSync("receipts/<id>.json", "utf8"));
 const result = verifyBundle(bundle, {
   issuerKeys: [loadPublicKey("keys/gateway.pub")],   // gateway keys and SDK application keys
   principalKeys: [loadPublicKey("keys/principal.pub")],
+  logKeys: [loadPublicKey("keys/log.pub")],           // only for receipts logged to a remote log
   logFile: "log.jsonl",           // optional
 });
 
@@ -128,7 +132,7 @@ The formats are standard on purpose, so a verifier in another language needs no
 
 ## Auditing a log copy
 
-Take copies of `log.jsonl` on a schedule and keep them where the operator cannot write. Then for any receipt:
+Take copies of `log.jsonl` on a schedule and keep them where the operator cannot write. A remote log serves `GET /root?size=N` so an auditor can compare a tree head with the log's own root without a copy; example 13 does this. Then for any receipt:
 
 ```bash
 node src/cli.ts verify receipts/<id>.json --issuer-key ... --principal-key ... --log /audit/copies/log-2026-09-04.jsonl
@@ -137,3 +141,19 @@ node src/cli.ts verify receipts/<id>.json --issuer-key ... --principal-key ... -
 The last check recomputes the root at the receipt's tree size from your copy. If the operator later deletes, reorders, or edits a line before that position, the recomputed root changes and the check fails.
 
 Today a copy must be at least as long as the receipt's tree size. Consistency proofs between two tree heads, which would let you check that a newer log extends an older copy without holding the whole file, are on the roadmap.
+
+## Proving history was not rewritten
+
+An inclusion proof says a receipt was in the log at one moment. It does not say the log still contains, unchanged, everything it contained earlier. That is what a consistency proof is for: given two tree heads, it proves the larger tree extends the smaller one, so nothing before the older head was rewritten. Keep the tree head from any receipt; it is the older head in every later audit.
+
+```bash
+node src/cli.ts audit --older receipts/<earlier>.json --newer receipts/<later>.json --log log.jsonl --issuer-key keys/gateway.pub
+node src/cli.ts audit --older receipts/<earlier>.json --newer receipts/<later>.json --log-url https://log.example.com/ --log-key keys/log.pub
+```
+
+Both tree heads must be signed by a trusted key. With `--log` the proof is computed from a copy of the log; with `--log-url` it is fetched from the log's `GET /consistency?old=M&new=N`. Exit code 0 means the newer log extends the older one. A failure means either history was rewritten between the two heads or the proof belongs to other tree heads; example 14 shows a rewritten log failing this way while every individual receipt still verifies.
+
+Programmatically, `auditExtends(older.treeHead, newer.treeHead, proof, keys)` returns the same checks. The proof algorithm is RFC 9162 section 2.1.4, so any log implementing it can answer, and any verifier implementing it can check.
+
+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.
+

package/package.json

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