@agent-custody/receipts 0.1.0 → 0.1.2

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): fifteen runnable examples, one per aspect of the code, all executed by the test suite
 - [Usage guide](docs/usage.md): gateway setup, wiring into Claude Desktop, Claude Code, or your own agent loop
 - [The interceptor SDK](docs/sdk.md): Claude Code hooks, the Claude Agent SDK, adapters for the OpenAI Agents SDK, Vercel AI SDK and LangChain, and wrapping tool functions in anything else
 - [Writing policies](docs/policies.md): how a tool call becomes a Cedar request, with tested examples
@@ -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"]
 
@@ -109,6 +103,9 @@ Every receipt names its issuer, and the verifier prints what that issuer kind is
 | Vercel AI SDK | SDK | `wrapTools` | | a real `generateText` loop over the SDK's mock model |
 | LangChain / LangGraph (JS) | SDK | `tool(issuer.wrap(fn))` | `ReceiptCallbackHandler` | real `StructuredTool` invocations |
 | anything else | SDK | `issuer.wrap(name, fn)` | `issuer.record` | plain functions |
+| Python: LangChain, OpenAI Agents SDK, Claude Agent SDK | sidecar + [Python package](../python/README.md) | `wrap_tools`, `claude_hook` PreToolUse deny, `client.wrap` | `ReceiptCallbackHandler` | the real Python packages, receipts checked by this verifier |
+| Go, Java, Rust, any language with HTTP | sidecar | decide then record | record | [examples/languages](examples/languages), each run against a live sidecar |
+| any MCP host in any language: Claude Agent SDK Python, OpenAI Agents Python | gateway | yes | | the gateway is an MCP server; [usage.md](docs/usage.md#python-hosts) |
 
 The framework packages are optional peer dependencies. Each adapter imports only from its own package.
 
@@ -173,7 +170,7 @@ Every field carries a provenance label. This is the design decision that matters
 bun install                              # from the repository root, once for the workspace
 cd packages/receipts
 node scripts/demo.ts                     # gateway: keys, grant, policy, four tool calls, verification, a tampering attempt; then the SDK wrapping the same tool
-node examples/01-keys-and-signing.ts     # first of twelve step-by-step examples, see docs/tutorials.md
+node examples/01-keys-and-signing.ts     # first of fifteen step-by-step examples, see docs/tutorials.md
 bun run test                             # this package; `bun run test` at the root runs every package
 ```
 
@@ -223,7 +220,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 +230,13 @@ 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/sidecar.ts     the SDK issuer behind a local HTTP API, for agents in other languages
+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, serve, log, verify, audit
 src/index.ts       the package's public surface; adapters are exported on ./sdk/<framework> subpaths
 tsconfig.build.json  emits dist/ (JavaScript plus declarations) for consumers; the repo itself runs the .ts directly
 scripts/           fake Stripe upstream, fixture builders for gateway and SDK, demo
-examples/          twelve runnable tutorials, one per aspect; each is run by the test suite
+examples/          fifteen runnable tutorials, plus examples/languages/: Python, Go, Java, and Rust clients of the sidecar, run by the test suite, one per aspect; each is run by the test suite
 test/              unit tests per module, end-to-end gateway test, SDK and hook tests,
                    adapter tests against the real packages, and a test that runs every policy in docs/policies.md
 docs/              tutorials, usage (gateway), sdk, policies, verification
@@ -254,16 +253,18 @@ 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.
+- Sidecar: the SDK issuer behind a local HTTP API (`serve`), with a Python package on PyPI-ready footing and Go, Java, and Rust clients, so agents in any language get the same receipts from one signing implementation.
+- Consistency proofs between tree heads (RFC 9162), served by the log and checked by the `audit` command, so an auditor holding an old tree head can prove nothing before it was rewritten.
+- Remote log: the issuer can append to a log run by someone else over HTTP, whose key then signs the tree heads, so a verifier learns the receipt was in a log the operator could not rewrite. Includes the reference log server, bearer-token auth, and a root endpoint for auditors.
 - Framework adapters, each tested against the real package with a scripted model and no network: OpenAI Agents SDK (`wrapTools` enforces, `observeRunner` records from lifecycle events), Vercel AI SDK (`wrapTools` over a real `generateText` loop), LangChain (`ReceiptCallbackHandler` records, `issuer.wrap` enforces).
 
 **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,23 @@ 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 { serveSidecar } from "./sidecar.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]
+  serve   --config <sdk.json> [--port 8788] [--host 127.0.0.1]   the SDK as a local HTTP API for agents in other languages
+  log     --file <log.jsonl> --key <log.key> [--port 8787] [--host 127.0.0.1] [--token-env <NAME>]   reference log server
+  verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--log <log.jsonl>] [--json]
+  audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--json]
+          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 +78,38 @@ 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 "serve": {
+            const { values } = parseArgs({ args: rest, options: { config: { type: "string" }, port: { type: "string", default: "8788" }, host: { type: "string", default: "127.0.0.1" } } });
+            if (!values.config)
+                throw new Error("serve needs --config");
+            const issuer = createSdkIssuer(loadSdkConfig(values.config));
+            const running = await serveSidecar(issuer, { port: Number(values.port), host: values.host });
+            console.error(`agent-custody serve: ${running.url} agent=${issuer.agentId} keyid=${issuer.keyid} log=${issuer.log.kind}:${issuer.log.where}`);
+            await new Promise((resolve) => process.once("SIGINT", resolve));
+            await running.close();
+            return 0;
+        }
+        case "log": {
+            const { values } = parseArgs({
+                args: rest,
+                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 +118,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 +131,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,7 +4,9 @@ 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";
 export * from "./sdk/index.ts";
+export * from "./sidecar.ts";

package/dist/index.js

@@ -5,7 +5,9 @@ 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";
 export * from "./sdk/index.js";
+export * from "./sidecar.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;
 }