@agent-custody/receipts 0.3.0 → 0.4.0

package/README.md

@@ -277,13 +277,14 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 - 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).
 
+- A log for someone else: `hashOnly` sends leaf hashes so the log never holds a receipt; the reference server runs several tenant logs at `/t/<tenant>/` with their own tokens and ids; tree heads name their log and the verifier checks it with `--log-id`. Phase 1 of the hosted log, [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 - OpenTelemetry export: with `otel` in either config, every receipt is also one span at the collector the team already runs, trace id equal to the receipt id, attributes for tool, agent, principal, status, decision, and log position; after the receipt, best effort, never on the evidence path.
 - The REST connector: a plain HTTP API described as tools in the gateway config, credentials from the environment, so an agent's direct API calls become receipted, policy-checked tool calls through the gateway.
 - Pre-commit authorization for consequential tools: named in `precommit`, a call is signed and logged before it is forwarded, withheld if the log will not take it, and its receipt carries the committed authorization with proof that it precedes the execution.
 
 **Next, in the order it pays off**
 
-1. A log run by someone who is not the operator, hosted: a tenant with a bearer token per fleet, consistency proofs served, retention. The reference log server is here; the tenanted service is [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6), and it comes before everything below.
+1. The hosted log, [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6), phases 2 and 3: the Postgres store with one writer per tenant, tokens and rate limits, the signer as its own process, published checkpoints, and well-known keys fetched with `--log-url`. Phase 1 is done; it comes before everything below.
 2. Post-quantum signatures: ML-DSA beside Ed25519 in the same DSSE envelope, hybrid by default when a PQ key is present, in every signed artefact and in the browser verifier. [Issue #11](https://github.com/ch4r10t33r/agent-custody/issues/11).
 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.

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
 import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { loadConfig, loadSdkConfig } from "./config.js";
 import { generateKeyPair, loadPrivateKey, loadPublicKey, writeKeyPair } from "./crypto.js";
 import { createDelegation } from "./delegation.js";
@@ -29,10 +30,24 @@ const USAGE = `agent-custody <command>
   prune   --log <log.jsonl> --before <ISO instant> [--receipts <dir>]
           retention on the receipt log: replaces older leaves with their hashes, so proofs still verify and the content is gone
   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>] [--upstream-key <pub>] [--stripe-secret-env NAME] [--github-secret-env NAME] [--log <log.jsonl>] [--json]
-  audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--json]
+  verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--log-id <id>] [--upstream-key <pub>] [--stripe-secret-env NAME] [--github-secret-env NAME] [--log <log.jsonl>] [--json]
+  audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--log-id <id>] [--json]
           checks that the newer receipt's log extends the older one's: nothing between them was rewritten
 `;
+/** The tenants file for `log --tenants`: paths relative to the file, tokens from the environment, ids default to the tenant name. */
+function loadTenants(path) {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const out = {};
+    for (const [name, t] of Object.entries(raw)) {
+        if (!/^[A-Za-z0-9_.-]+$/.test(name) || typeof t?.file !== "string")
+            throw new Error(`tenants: "${name}" needs a file, and its name must be a plain identifier`);
+        const token = t.tokenEnv ? process.env[t.tokenEnv] : undefined;
+        if (t.tokenEnv && !token)
+            throw new Error(`tenants: environment variable ${t.tokenEnv} for "${name}" is not set`);
+        out[name] = { file: resolve(dirname(resolve(path)), t.file), ...(token ? { tokens: [token] } : {}), ...(t.logId ? { logId: t.logId } : {}) };
+    }
+    return out;
+}
 async function main(argv) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
@@ -116,7 +131,7 @@ async function main(argv) {
         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" } },
+                options: { file: { type: "string" }, key: { type: "string" }, port: { type: "string", default: "8787" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" }, "log-id": { type: "string" }, tenants: { type: "string" } },
             });
             if (!values.file || !values.key)
                 throw new Error("log needs --file and --key");
@@ -124,8 +139,10 @@ async function main(argv) {
             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"}`);
+            // --tenants names a JSON file { "<tenant>": { "file": "...", "tokenEnv": "NAME", "logId": "..." } }; each is reached at /t/<tenant>/.
+            const tenants = values.tenants ? loadTenants(values.tenants) : undefined;
+            const running = await serveLog(values.file, key, { port: Number(values.port), host: values.host, ...(token ? { tokens: [token] } : {}), ...(values["log-id"] ? { logId: values["log-id"] } : {}), ...(tenants ? { tenants } : {}) });
+            console.error(`agent-custody log: ${running.url} keyid=${key.keyid} file=${values.file}${values["log-id"] ? ` log=${values["log-id"]}` : ""} ${token ? "bearer token required" : "open, anyone may append"}${tenants ? ` tenants=${Object.keys(tenants).join(",")}` : ""}`);
             await new Promise((resolve) => process.once("SIGINT", resolve));
             await running.close();
             return 0;
@@ -139,6 +156,7 @@ async function main(argv) {
                     "gateway-key": { type: "string", multiple: true },
                     "principal-key": { type: "string", multiple: true },
                     "log-key": { type: "string", multiple: true },
+                    "log-id": { type: "string" },
                     "upstream-key": { type: "string", multiple: true },
                     "stripe-secret-env": { type: "string" },
                     "github-secret-env": { type: "string" },
@@ -155,6 +173,7 @@ async function main(argv) {
                 issuerKeys: issuerKeyFiles.map(loadPublicKey),
                 principalKeys: (values["principal-key"] ?? []).map(loadPublicKey),
                 ...(values["log-key"] ? { logKeys: values["log-key"].map(loadPublicKey) } : {}),
+                ...(values["log-id"] ? { logId: values["log-id"] } : {}),
                 ...(values["upstream-key"] ? { upstreamKeys: values["upstream-key"].map(loadPublicKey) } : {}),
                 ...(values["stripe-secret-env"] || values["github-secret-env"] ? { providerSecrets: { ...(values["stripe-secret-env"] ? { stripe: secretFrom(values["stripe-secret-env"]) } : {}), ...(values["github-secret-env"] ? { github: secretFrom(values["github-secret-env"]) } : {}) } } : {}),
                 ...(values.log ? { logFile: values.log } : {}),
@@ -172,6 +191,7 @@ async function main(argv) {
                     "log-url": { type: "string" },
                     "issuer-key": { type: "string", multiple: true },
                     "log-key": { type: "string", multiple: true },
+                    "log-id": { type: "string" },
                     json: { type: "boolean", default: false },
                 },
             });
@@ -193,7 +213,7 @@ async function main(argv) {
                     throw new Error(`log refused the consistency query: ${res.status}`);
                 proof = (await res.json()).hashes;
             }
-            const result = auditExtends(older, newer, proof, keyFiles.map(loadPublicKey));
+            const result = auditExtends(older, newer, proof, keyFiles.map(loadPublicKey), values["log-id"]);
             if (values.json)
                 console.log(JSON.stringify(result, null, 2));
             else {

package/dist/config.d.ts

@@ -174,6 +174,7 @@ export declare const GatewayConfigSchema: z.ZodObject<{
     log: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
         tokenEnv: z.ZodOptional<z.ZodString>;
+        hashOnly: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     otel: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
@@ -197,6 +198,7 @@ export declare const SdkConfigSchema: z.ZodObject<{
     log: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
         tokenEnv: z.ZodOptional<z.ZodString>;
+        hashOnly: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     otel: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;

package/dist/config.js

@@ -2,7 +2,7 @@ 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 LogSchema = z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional(), /** send leaf hashes only; the log never holds the receipt. Use it for any log run by someone else */ hashOnly: z.boolean().optional() });
 const oneLog = { message: "exactly one of logFile or log is required" };
 /** Optional OpenTelemetry export: every receipt also becomes a span at this OTLP/HTTP collector, after it is issued. Never on the evidence path. */
 const OtelSchema = z.object({ url: z.string().url(), headersEnv: z.record(z.string(), z.string().min(1)).optional(), serviceName: z.string().min(1).optional() });

package/dist/log-sink.d.ts

@@ -17,6 +17,8 @@ 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;
+    /** send only the leaf hash; the log then commits to the receipt without ever holding it. Use it for any log run by someone else. */
+    hashOnly?: boolean;
     fetch?: typeof fetch;
 }
 /** A log reached over HTTP: POST <url>/append with {leaf}, expecting a LogAppend back. */
@@ -26,6 +28,7 @@ export interface LogConfig {
     log?: {
         url: string;
         tokenEnv?: string | undefined;
+        hashOnly?: boolean | undefined;
     } | undefined;
 }
 /** The sink a config asks for: a remote log when `log` is set, otherwise the local file. */
@@ -33,6 +36,18 @@ 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 id written into every tree head this log signs, so a head cannot be presented as another log's */
+    logId?: string;
+    /**
+     * More logs behind the same server, one per tenant, reached at /t/<tenant>/...: each with its own file, tokens,
+     * and id. The default log stays at the root paths. This is the shape a hosted log takes; the reference server
+     * runs it from a small JSON file.
+     */
+    tenants?: Record<string, {
+        file: string;
+        tokens?: string[];
+        logId?: string;
+    }>;
 }
 /**
  * The reference log server as a node:http request handler.

package/dist/log-sink.js

@@ -6,11 +6,11 @@
 import { timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import { dsseSign } from "./crypto.js";
-import { MerkleLog } from "./log.js";
+import { leafHash, 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() };
+function appendSigned(log, key, leaf, logId) {
+    const e = "leaf" in leaf ? log.append(leaf.leaf) : log.appendHash(leaf.leafHash);
+    const head = { treeSize: e.treeSize, rootHash: e.rootHash, timestamp: new Date().toISOString(), ...(logId ? { log: logId } : {}) };
     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. */
@@ -20,7 +20,7 @@ export function fileLog(file, key) {
         kind: "file",
         where: file,
         async append(leaf) {
-            return appendSigned(log, key, leaf);
+            return appendSigned(log, key, { leaf });
         },
     };
 }
@@ -35,7 +35,7 @@ export function httpLog(url, opts = {}) {
             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 }),
+                body: JSON.stringify(opts.hashOnly ? { leafHash: leafHash(leaf).toString("hex") } : { leaf }),
             });
             if (!res.ok)
                 throw new Error(`log ${url} refused the append: ${res.status} ${(await res.text()).slice(0, 200)}`);
@@ -52,7 +52,7 @@ export function openLog(cfg, key) {
         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 });
+        return httpLog(cfg.log.url, { ...(token === undefined ? {} : { token }), ...(cfg.log.hashOnly ? { hashOnly: true } : {}) });
     }
     if (!cfg.logFile)
         throw new Error("config needs logFile or log.url");
@@ -66,9 +66,11 @@ export function openLog(cfg, key) {
  *   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) => {
+    const root = { log: new MerkleLog(file), tokens: opts.tokens ?? [], logId: opts.logId };
+    const tenants = new Map();
+    for (const [name, t] of Object.entries(opts.tenants ?? {}))
+        tenants.set(name, { log: new MerkleLog(t.file), tokens: t.tokens ?? [], logId: t.logId ?? name });
+    const authorized = (req, tokens) => {
         if (tokens.length === 0)
             return true;
         const h = req.headers.authorization ?? "";
@@ -84,22 +86,33 @@ export function logHandler(file, key, opts = {}) {
             res.end(JSON.stringify(body));
         };
         const url = new URL(req.url ?? "/", "http://localhost");
+        // /t/<tenant>/<op> reaches that tenant's log; anything else is the default log.
+        const m = /^\/t\/([A-Za-z0-9_.-]+)\/(append|root|consistency|head)$/.exec(url.pathname);
+        const which = m ? tenants.get(m[1]) : root;
+        if (!which)
+            return json(404, { error: "unknown log" });
+        const { log, tokens, logId } = which;
         if (req.method === "POST" && url.pathname.endsWith("/append")) {
-            if (!authorized(req))
+            if (!authorized(req, tokens))
                 return json(401, { error: "unauthorized" });
             let body = "";
             for await (const chunk of req)
                 body += chunk;
-            let leaf;
+            let parsed;
             try {
-                leaf = JSON.parse(body).leaf;
+                parsed = JSON.parse(body);
             }
             catch {
-                return json(400, { error: "body must be JSON {leaf}" });
+                return json(400, { error: "body must be JSON {leaf} or {leafHash}" });
+            }
+            if (typeof parsed.leafHash === "string") {
+                if (!/^[0-9a-f]{64}$/.test(parsed.leafHash))
+                    return json(400, { error: "leafHash must be 64 lowercase hex characters" });
+                return json(200, appendSigned(log, key, { leafHash: parsed.leafHash }, logId));
             }
-            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 (typeof parsed.leaf !== "string" || parsed.leaf.length === 0)
+                return json(400, { error: "leaf must be a non-empty string, or send leafHash" });
+            return json(200, appendSigned(log, key, { leaf: parsed.leaf }, logId));
         }
         if (req.method === "GET" && url.pathname.endsWith("/root")) {
             const size = url.searchParams.has("size") ? Number(url.searchParams.get("size")) : log.size;
@@ -115,7 +128,7 @@ export function logHandler(file, key, opts = {}) {
             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() };
+            const head = { treeSize: log.size, rootHash: log.root(), timestamp: new Date().toISOString(), ...(logId ? { log: logId } : {}) };
             return json(200, { treeHead: dsseSign(TREEHEAD_TYPE, head, key) });
         }
         return json(404, { error: "not found" });

package/dist/log.d.ts

@@ -22,6 +22,14 @@ export declare class MerkleLog {
     append(leaf: string): InclusionProof & {
         rootHash: string;
     };
+    /**
+     * Appends a leaf by its RFC 6962 leaf hash, sha256(0x00 || leaf), as hex. The log commits to the leaf without ever
+     * holding it, which is what a log run for someone else should do: the receipt stays with its issuer.
+     */
+    appendHash(leafHashHex: string): InclusionProof & {
+        rootHash: string;
+    };
+    private pushHash;
     root(size?: number): string;
     /** Proof that this log at newSize extends its own earlier state at oldSize. */
     consistencyProof(oldSize: number, newSize?: number): string[];

package/dist/log.js

@@ -165,8 +165,9 @@ export class MerkleLog {
                 if (!line.trim())
                     continue;
                 const parsed = JSON.parse(line);
-                // A pruned leaf keeps only its hash: the tree, its roots, and every proof are unchanged; the content is gone.
-                this.hashes.push(typeof parsed === "string" ? leafHash(parsed) : Buffer.from(parsed.pruned, "hex"));
+                // A pruned leaf keeps only its hash, and a leaf appended by hash never had content here: the tree, its
+                // roots, and every proof are the same either way.
+                this.hashes.push(typeof parsed === "string" ? leafHash(parsed) : Buffer.from((parsed.pruned ?? parsed.hash), "hex"));
             }
         }
         else {
@@ -179,7 +180,20 @@ export class MerkleLog {
     /** Appends a leaf (an opaque string, typically a canonical JSON envelope). Returns its proof against the new root. */
     append(leaf) {
         appendFileSync(this.file, JSON.stringify(leaf) + "\n");
-        this.hashes.push(leafHash(leaf));
+        return this.pushHash(leafHash(leaf));
+    }
+    /**
+     * Appends a leaf by its RFC 6962 leaf hash, sha256(0x00 || leaf), as hex. The log commits to the leaf without ever
+     * holding it, which is what a log run for someone else should do: the receipt stays with its issuer.
+     */
+    appendHash(leafHashHex) {
+        if (!/^[0-9a-f]{64}$/.test(leafHashHex))
+            throw new Error("leafHash must be 64 lowercase hex characters");
+        appendFileSync(this.file, JSON.stringify({ hash: leafHashHex }) + "\n");
+        return this.pushHash(Buffer.from(leafHashHex, "hex"));
+    }
+    pushHash(hash) {
+        this.hashes.push(hash);
         const treeSize = this.hashes.length;
         return { leafIndex: treeSize - 1, treeSize, hashes: this.tree.path(treeSize - 1, 0, treeSize).map((b) => b.toString("hex")), rootHash: this.tree.mth(0, treeSize).toString("hex") };
     }

package/dist/receipt.d.ts

@@ -153,6 +153,8 @@ export interface TreeHead {
     treeSize: number;
     rootHash: string;
     timestamp: string;
+    /** which log this head belongs to, when the log serves more than one; a verifier told which log to expect checks it */
+    log?: string;
 }
 /** What gets written to disk and handed to a verifier. Self-contained apart from public keys. */
 export interface ReceiptBundle {

package/dist/verify.d.ts

@@ -18,6 +18,8 @@ export interface VerifyOptions {
     providerSecrets?: ProviderSecrets;
     /** If given, the root is recomputed from this log file at the receipt's tree size and compared. */
     logFile?: string;
+    /** If given, every tree head in the bundle must name this log, so a head from another tenant's log cannot be presented as this one's. */
+    logId?: string;
 }
 export interface VerifyResult {
     ok: boolean;
@@ -35,6 +37,6 @@ export interface AuditResult {
  * 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;
+export declare function auditExtends(older: Envelope, newer: Envelope, proof: string[], keys: PublicKeyRef[], logId?: string): 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

@@ -92,6 +92,8 @@ export function verifyBundle(bundle, opts) {
     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;
+        if (opts.logId !== undefined)
+            add("tree head names the expected log", head.log === opts.logId, head.log ? `log ${head.log}` : "tree head names no log");
         add("tree head matches inclusion proof size", head.treeSize === bundle.inclusion.treeSize);
         const included = verifyInclusion(leafHash(canonicalize(bundle.envelope)), bundle.inclusion, head.rootHash);
         add("log inclusion proof", included, `leaf ${bundle.inclusion.leafIndex} of ${bundle.inclusion.treeSize}, root ${short(head.rootHash)}`);
@@ -113,7 +115,7 @@ export function verifyBundle(bundle, opts) {
  * 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) {
+export function auditExtends(older, newer, proof, keys, logId) {
     const checks = [];
     const add = (name, ok, detail) => {
         checks.push(detail === undefined ? { name, ok } : { name, ok, detail });
@@ -128,6 +130,10 @@ export function auditExtends(older, newer, proof, keys) {
     const b = decode("newer", newer);
     if (!a || !b)
         return { ok: false, checks, older: a, newer: b };
+    if (logId !== undefined)
+        add("both tree heads name the expected log", a.log === logId && b.log === logId, `expected ${logId}, got ${a.log ?? "none"} and ${b.log ?? "none"}`);
+    else if (a.log !== b.log)
+        add("both tree heads name the same log", false, `${a.log ?? "none"} and ${b.log ?? "none"}`);
     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);

package/docs/usage.md

@@ -105,7 +105,7 @@ An upstream need not be an MCP server. A plain HTTP API is described as tools:
   "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 ordinary call the upstream action has already happened by then, and the error says so; a receipt that was never logged must not be handed out. For a tool named in `precommit` the order is reversed, below, and the action never happens. The reference log server is `node src/cli.ts log --file log.jsonl --key keys/log.key --port 8787 --token-env AGENT_CUSTODY_LOG_TOKEN`. It serves `POST /append` (token required when one is configured), `GET /root?size=N`, `GET /consistency?old=M&new=N`, and `GET /head`; [verification.md](verification.md) says what each proves.
+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. Add `"hashOnly": true` for any log run by someone else: the gateway then sends only the leaf hash, sha256 of the receipt envelope with the RFC 6962 prefix, so the log commits to the receipt without ever holding it, and the receipts with their arguments and results stay in `receiptsDir`. The verifier does not change; it hashes the envelope itself. A log that serves several tenants is reached at `<url>/t/<tenant>/`, and each of its tree heads names its log, which a verifier checks with `--log-id`. With a remote log the tree head in each receipt is signed by the log's key, and a verifier must be given that key with `--log-key`. If the log refuses a leaf, the receipt is not issued and the call returns an error to the agent. For an ordinary call the upstream action has already happened by then, and the error says so; a receipt that was never logged must not be handed out. For a tool named in `precommit` the order is reversed, below, and the action never happens. The reference log server is `node src/cli.ts log --file log.jsonl --key keys/log.key --port 8787 --token-env AGENT_CUSTODY_LOG_TOKEN [--log-id <id>] [--tenants tenants.json]`. It serves `POST /append` with `{leaf}` or `{leafHash}` (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. `--log-id` writes that id into every tree head. `--tenants` names a JSON file, `{ "acme": { "file": "acme.jsonl", "tokenEnv": "ACME_TOKEN", "logId": "acme-eu" } }`, and each tenant is its own log at `/t/acme/…` with its own token and id; the default log stays at the root paths. [deploy/](../../deploy/README.md) runs the server as a container.
 
 `otel`, optional in both the gateway and SDK configs, sends every receipt to the collector you already run as one span over OTLP/HTTP, after the receipt is issued: `"otel": { "url": "http://localhost:4318", "headersEnv": { "x-api-key": "OTEL_KEY" }, "serviceName": "support-agents" }`. The span's trace id is the receipt id, its attributes carry the tool, agent, principal, execution status, policy decision, and log position, and its status is an error only when the upstream failed or errored, since a denial is the policy working. Export is best effort: a collector that is down or refuses costs a line on stderr, never a receipt. Tutorial 18 shows it against a stand-in collector.
 

package/docs/verification.md

@@ -83,6 +83,7 @@ execution       observed    executed
 | authorization log inclusion proof | the authorization statement is a leaf of that tree | an authorization that was never logged |
 | authorization logged before execution | the authorization's leaf precedes the receipt's leaf, at a tree size no larger than the receipt's | evidence written after the side effect, dressed up as before |
 | tree head signature | the tree head was signed by a trusted issuer key | forged log position |
+| tree head names the expected log | with `--log-id`: the tree head carries that log id, so a head from another tenant's log on the same server cannot be presented as this one's | a receipt logged to a different log than claimed |
 | tree head matches inclusion proof size | the proof and the tree head describe the same tree | mismatched bundle parts |
 | log inclusion proof | this exact envelope is a leaf of the tree with that root | receipt never logged, or logged then changed |
 | log file root matches tree head | recomputing the root from your copy of the log at that size gives the same value | your log copy and the issuer's history diverge: deletion, reordering, or edit |
@@ -160,7 +161,7 @@ An inclusion proof says a receipt was in the log at one moment. It does not say
 
 ```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
+node src/cli.ts audit --older receipts/<earlier>.json --newer receipts/<later>.json --log-url https://log.example.com/t/acme/ --log-key keys/log.pub --log-id acme
 ```
 
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Chain of custody for AI agents: signed, independently verifiable receipts for tool calls. MCP gateway + Cedar policy + Merkle transparency log",
   "license": "Apache-2.0",
   "repository": {

package/vectors/audit.json

@@ -7,26 +7,26 @@
       "description": "The tree head from the first remote receipt and the log's later head, with the proof the log served.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjY5NTU0NGFkNTA4YTEzYTk4NTUxM2YzYjJhMjU0MzhlZjk1MWIyMzk2MGQ1ODU0YjczZjFjYWRkMzJmOTI1YmQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1NVoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJsb2ciOiJ2ZWN0b3JzLWxvZyIsInJvb3RIYXNoIjoiODViYjZhMjk1YzYxYmIzMzg5MWYyNTFiNWNiZGQ4NzNjNGVkYTU5OTBkMWE4MzVjNDRjYjZiMDgwNTBhY2U2MiIsInRpbWVzdGFtcCI6IjIwMjYtMDktMDhUMDY6MzA6MDQuNjkzWiIsInRyZWVTaXplIjoxfQ==",
         "signatures": [
           {
-            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
-            "sig": "Dy7+sDttHIIQCUzGlIL7Yro+UFGLSPjnLuBJYxFdq2wiqkkAdA3ipo09aSoS0h5BwJMOOEqOTmrGb/ot7HZTCQ=="
+            "keyid": "74356bcffe957c1c3a3bde6702505f536d4e8bab2aac3b0f36419e846da1a8d5",
+            "sig": "xhkG/l7l3ElnvGnxrFfK2nYUCkRo0ktj0+6ctv6V1qKiXihMYexcOu/qepdqWWN0mWFq2u8/Aqo6kbdoWhiFDQ=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjU0YzBkNDY1NDhjYzdlYzcyMTQ1MDNlMzFjNzhhYTY5MDZhMmRkY2VhZTI3OTI0N2M5NzRjMjljYmY3Y2Q4NGMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1OFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJsb2ciOiJ2ZWN0b3JzLWxvZyIsInJvb3RIYXNoIjoiODY0N2E0MTczNTIxYzE5Mzg4NTg2Y2U1MzYyNGU3MGZiYWEyMzc0NGRiYjIzNTQ0ZDU2N2Q5NDY0NmE0ZTM3MiIsInRpbWVzdGFtcCI6IjIwMjYtMDktMDhUMDY6MzA6MDQuNjk3WiIsInRyZWVTaXplIjoyfQ==",
         "signatures": [
           {
-            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
-            "sig": "4belmD02Vv4dufyaCY2N8J48+bxQmMtMfg+jNyD3wadZftcYgQPkZJ2mUx7gCfoh5lOwEu+Wzd5Id1yZlHYvAQ=="
+            "keyid": "74356bcffe957c1c3a3bde6702505f536d4e8bab2aac3b0f36419e846da1a8d5",
+            "sig": "iaweKtCddKNA0R+dkq+0qyzwe8RhZdKgK6y9o21adUCjhMAGlpl+YDe1chzn4NvT7jIZvn+HDdll136TmqcmCQ=="
           }
         ]
       },
       "proof": [
-        "32a570791cc4546f2b7cf560a2fe3459eb504e0cae52f0ce521fea311f9f15ba"
+        "f8e988293efa93dd5e5ea2af96b88588f4a1fba5c786848e997aa985c95e2f81"
       ],
       "keys": [
         "log"
@@ -41,26 +41,26 @@
       "description": "The same heads the wrong way round.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjU0YzBkNDY1NDhjYzdlYzcyMTQ1MDNlMzFjNzhhYTY5MDZhMmRkY2VhZTI3OTI0N2M5NzRjMjljYmY3Y2Q4NGMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1OFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJsb2ciOiJ2ZWN0b3JzLWxvZyIsInJvb3RIYXNoIjoiODY0N2E0MTczNTIxYzE5Mzg4NTg2Y2U1MzYyNGU3MGZiYWEyMzc0NGRiYjIzNTQ0ZDU2N2Q5NDY0NmE0ZTM3MiIsInRpbWVzdGFtcCI6IjIwMjYtMDktMDhUMDY6MzA6MDQuNjk3WiIsInRyZWVTaXplIjoyfQ==",
         "signatures": [
           {
-            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
-            "sig": "4belmD02Vv4dufyaCY2N8J48+bxQmMtMfg+jNyD3wadZftcYgQPkZJ2mUx7gCfoh5lOwEu+Wzd5Id1yZlHYvAQ=="
+            "keyid": "74356bcffe957c1c3a3bde6702505f536d4e8bab2aac3b0f36419e846da1a8d5",
+            "sig": "iaweKtCddKNA0R+dkq+0qyzwe8RhZdKgK6y9o21adUCjhMAGlpl+YDe1chzn4NvT7jIZvn+HDdll136TmqcmCQ=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjY5NTU0NGFkNTA4YTEzYTk4NTUxM2YzYjJhMjU0MzhlZjk1MWIyMzk2MGQ1ODU0YjczZjFjYWRkMzJmOTI1YmQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1NVoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJsb2ciOiJ2ZWN0b3JzLWxvZyIsInJvb3RIYXNoIjoiODViYjZhMjk1YzYxYmIzMzg5MWYyNTFiNWNiZGQ4NzNjNGVkYTU5OTBkMWE4MzVjNDRjYjZiMDgwNTBhY2U2MiIsInRpbWVzdGFtcCI6IjIwMjYtMDktMDhUMDY6MzA6MDQuNjkzWiIsInRyZWVTaXplIjoxfQ==",
         "signatures": [
           {
-            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
-            "sig": "Dy7+sDttHIIQCUzGlIL7Yro+UFGLSPjnLuBJYxFdq2wiqkkAdA3ipo09aSoS0h5BwJMOOEqOTmrGb/ot7HZTCQ=="
+            "keyid": "74356bcffe957c1c3a3bde6702505f536d4e8bab2aac3b0f36419e846da1a8d5",
+            "sig": "xhkG/l7l3ElnvGnxrFfK2nYUCkRo0ktj0+6ctv6V1qKiXihMYexcOu/qepdqWWN0mWFq2u8/Aqo6kbdoWhiFDQ=="
           }
         ]
       },
       "proof": [
-        "32a570791cc4546f2b7cf560a2fe3459eb504e0cae52f0ce521fea311f9f15ba"
+        "f8e988293efa93dd5e5ea2af96b88588f4a1fba5c786848e997aa985c95e2f81"
       ],
       "keys": [
         "log"
@@ -77,26 +77,26 @@
       "description": "Tree heads checked against the app key, which did not sign them.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjY5NTU0NGFkNTA4YTEzYTk4NTUxM2YzYjJhMjU0MzhlZjk1MWIyMzk2MGQ1ODU0YjczZjFjYWRkMzJmOTI1YmQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1NVoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJsb2ciOiJ2ZWN0b3JzLWxvZyIsInJvb3RIYXNoIjoiODViYjZhMjk1YzYxYmIzMzg5MWYyNTFiNWNiZGQ4NzNjNGVkYTU5OTBkMWE4MzVjNDRjYjZiMDgwNTBhY2U2MiIsInRpbWVzdGFtcCI6IjIwMjYtMDktMDhUMDY6MzA6MDQuNjkzWiIsInRyZWVTaXplIjoxfQ==",
         "signatures": [
           {
-            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
-            "sig": "Dy7+sDttHIIQCUzGlIL7Yro+UFGLSPjnLuBJYxFdq2wiqkkAdA3ipo09aSoS0h5BwJMOOEqOTmrGb/ot7HZTCQ=="
+            "keyid": "74356bcffe957c1c3a3bde6702505f536d4e8bab2aac3b0f36419e846da1a8d5",
+            "sig": "xhkG/l7l3ElnvGnxrFfK2nYUCkRo0ktj0+6ctv6V1qKiXihMYexcOu/qepdqWWN0mWFq2u8/Aqo6kbdoWhiFDQ=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjU0YzBkNDY1NDhjYzdlYzcyMTQ1MDNlMzFjNzhhYTY5MDZhMmRkY2VhZTI3OTI0N2M5NzRjMjljYmY3Y2Q4NGMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1OFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJsb2ciOiJ2ZWN0b3JzLWxvZyIsInJvb3RIYXNoIjoiODY0N2E0MTczNTIxYzE5Mzg4NTg2Y2U1MzYyNGU3MGZiYWEyMzc0NGRiYjIzNTQ0ZDU2N2Q5NDY0NmE0ZTM3MiIsInRpbWVzdGFtcCI6IjIwMjYtMDktMDhUMDY6MzA6MDQuNjk3WiIsInRyZWVTaXplIjoyfQ==",
         "signatures": [
           {
-            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
-            "sig": "4belmD02Vv4dufyaCY2N8J48+bxQmMtMfg+jNyD3wadZftcYgQPkZJ2mUx7gCfoh5lOwEu+Wzd5Id1yZlHYvAQ=="
+            "keyid": "74356bcffe957c1c3a3bde6702505f536d4e8bab2aac3b0f36419e846da1a8d5",
+            "sig": "iaweKtCddKNA0R+dkq+0qyzwe8RhZdKgK6y9o21adUCjhMAGlpl+YDe1chzn4NvT7jIZvn+HDdll136TmqcmCQ=="
           }
         ]
       },
       "proof": [
-        "32a570791cc4546f2b7cf560a2fe3459eb504e0cae52f0ce521fea311f9f15ba"
+        "f8e988293efa93dd5e5ea2af96b88588f4a1fba5c786848e997aa985c95e2f81"
       ],
       "keys": [
         "app"
@@ -114,21 +114,21 @@
       "description": "A proof with a hash removed.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjY5NTU0NGFkNTA4YTEzYTk4NTUxM2YzYjJhMjU0MzhlZjk1MWIyMzk2MGQ1ODU0YjczZjFjYWRkMzJmOTI1YmQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1NVoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJsb2ciOiJ2ZWN0b3JzLWxvZyIsInJvb3RIYXNoIjoiODViYjZhMjk1YzYxYmIzMzg5MWYyNTFiNWNiZGQ4NzNjNGVkYTU5OTBkMWE4MzVjNDRjYjZiMDgwNTBhY2U2MiIsInRpbWVzdGFtcCI6IjIwMjYtMDktMDhUMDY6MzA6MDQuNjkzWiIsInRyZWVTaXplIjoxfQ==",
         "signatures": [
           {
-            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
-            "sig": "Dy7+sDttHIIQCUzGlIL7Yro+UFGLSPjnLuBJYxFdq2wiqkkAdA3ipo09aSoS0h5BwJMOOEqOTmrGb/ot7HZTCQ=="
+            "keyid": "74356bcffe957c1c3a3bde6702505f536d4e8bab2aac3b0f36419e846da1a8d5",
+            "sig": "xhkG/l7l3ElnvGnxrFfK2nYUCkRo0ktj0+6ctv6V1qKiXihMYexcOu/qepdqWWN0mWFq2u8/Aqo6kbdoWhiFDQ=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6IjU0YzBkNDY1NDhjYzdlYzcyMTQ1MDNlMzFjNzhhYTY5MDZhMmRkY2VhZTI3OTI0N2M5NzRjMjljYmY3Y2Q4NGMiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA4VDAxOjUwOjE1Ljc1OFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJsb2ciOiJ2ZWN0b3JzLWxvZyIsInJvb3RIYXNoIjoiODY0N2E0MTczNTIxYzE5Mzg4NTg2Y2U1MzYyNGU3MGZiYWEyMzc0NGRiYjIzNTQ0ZDU2N2Q5NDY0NmE0ZTM3MiIsInRpbWVzdGFtcCI6IjIwMjYtMDktMDhUMDY6MzA6MDQuNjk3WiIsInRyZWVTaXplIjoyfQ==",
         "signatures": [
           {
-            "keyid": "c150ba37105c4e66f85239796e4f07b97c0fc431a9c1118d2bd1554ba35dab54",
-            "sig": "4belmD02Vv4dufyaCY2N8J48+bxQmMtMfg+jNyD3wadZftcYgQPkZJ2mUx7gCfoh5lOwEu+Wzd5Id1yZlHYvAQ=="
+            "keyid": "74356bcffe957c1c3a3bde6702505f536d4e8bab2aac3b0f36419e846da1a8d5",
+            "sig": "iaweKtCddKNA0R+dkq+0qyzwe8RhZdKgK6y9o21adUCjhMAGlpl+YDe1chzn4NvT7jIZvn+HDdll136TmqcmCQ=="
           }
         ]
       },

package/vectors/canonical.json

@@ -53,18 +53,18 @@
     }
   ],
   "keyid": {
-    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEABAiIObrUZgS8uRY1zr5NCUnkr2HqN3K/b+P75pkPX1I=\n-----END PUBLIC KEY-----\n",
-    "keyid": "f660c2bc47886be244642e60bbe1235946e88b8ca864c1c55ef7a8c7a424e184"
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0ZCk/vXbGqi5xjdFAok3XGPWbCT9yO2OeGbMF1nvH5w=\n-----END PUBLIC KEY-----\n",
+    "keyid": "3df0af0ec3abda622a30f7a3273fc6ca4eda229404122f02e2cae12923a861ad"
   },
   "dsse": {
-    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEABAiIObrUZgS8uRY1zr5NCUnkr2HqN3K/b+P75pkPX1I=\n-----END PUBLIC KEY-----\n",
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0ZCk/vXbGqi5xjdFAok3XGPWbCT9yO2OeGbMF1nvH5w=\n-----END PUBLIC KEY-----\n",
     "envelope": {
       "payloadType": "application/vnd.example+json",
       "payload": "eyJoZWxsbyI6IndvcmxkIn0=",
       "signatures": [
         {
-          "keyid": "f660c2bc47886be244642e60bbe1235946e88b8ca864c1c55ef7a8c7a424e184",
-          "sig": "DY3PDf89eYVsOJeQJYxT4W2c4NsNeWup+P+Oi/yvp9Fr34uSct3SfueWkmdaAtrmjrenoAdNt8BWV0N+6f0JDA=="
+          "keyid": "3df0af0ec3abda622a30f7a3273fc6ca4eda229404122f02e2cae12923a861ad",
+          "sig": "aGI6lAPRJs17z+UUezv/7iGyZ1rHbjKRWBELgeC4YjLGytQLUZsH+2jwFKhmTasJIyssry1ob+HMt4V20WCzBQ=="
         }
       ]
     },