@agent-custody/receipts 0.5.3 → 0.5.4

package/README.md

@@ -225,6 +225,7 @@ 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 and consistency proofs, verify, JSONL persistence
+src/witness.ts     the witness: countersigns the log's checkpoints from another operator's machine, or refuses with an alarm
 src/signer.ts      the signer: the log's key in its own process, the key document verifiers fetch
 src/checkpoints.ts signed heads published on a schedule, to files and to Postgres
 src/log-store.ts   the log server's backends: the file, and Postgres with tenants, hashed tokens, one writer per tenant, rate limits
@@ -280,6 +281,7 @@ 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).
 
+- The witness: a second signer on a machine the log's operator does not control countersigns each checkpoint after proving it extends the last one it signed, refuses a rewritten or forked history with an alarm, and publishes its key; `audit --witness-url` requires it. Phase 6 of [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 - The signer, keys, and checkpoints: the key in its own process (`signer`, `--signer-url`), the key document at `/.well-known/agent-custody-log.json` fetched and pinned by `verify --log-url` and `audit --log-url`, and signed checkpoints per log published to a directory and a table for a verifier who was not watching. Phase 3 of [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 - The log over Postgres: `log --db-env`, leaves as hashes in one table keyed by tenant, one writer per tenant by advisory lock, tenants and hashed tokens in tables managed by `log-admin`, rate limits and a body cap, retries in the sink, and `import` for an existing file log. Phase 2 of [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 - 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).
@@ -289,7 +291,7 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 
 **Next, in the order it pays off**
 
-1. The hosted log, [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6): running at log.agent-custody.dev with keys published and checkpoints on a second host, taking its first tenants. What remains is the witness that countersigns checkpoints.
+1. Run the witness for log.agent-custody.dev on a machine and under an account that is not ours, and require it in the welcome sheet. The code is done; what it needs is a second operator. [Issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 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

@@ -10,10 +10,12 @@ import { postgresResolver, serveLog } from "./log-sink.js";
 import { importLogFile, PostgresTenancy } from "./log-store.js";
 import { bothCheckpoints, dirCheckpoints, postgresCheckpoints } from "./checkpoints.js";
 import { connectSigner, fetchLogKeys, localSigner, serveSigner } from "./signer.js";
+import { fetchWitnessKeys, Witness } from "./witness.js";
 import { CheckpointPublisher, fileResolver } from "./log-sink.js";
 import { createRequire } from "node:module";
 import { pruneLog } from "./retention.js";
 import { serveSidecar } from "./sidecar.js";
+import { TREEHEAD_TYPE } from "./receipt.js";
 import { MerkleLog } from "./log.js";
 import { createSdkIssuer } from "./sdk/index.js";
 import { handleHookEvent } from "./sdk/claude.js";
@@ -46,13 +48,18 @@ const USAGE = `agent-custody <command>
   log     ... --db-env NAME --admin-token-env NAME [--public-url <https://log.example.com/>] [--checkpoints-url <https://checkpoints.example.com/>]
                                                  the operator's admin page at /admin and its API, behind the admin token: tenants, tokens shown once,
                                                  the welcome sheet; the public URLs fill the sheet in
+  witness --key <witness.key> --log-url <url> --checkpoints-url <url> --out <dir> [--tenant <name>]... [--every <seconds>] [--once]
+                                                 a second signer, run by someone who is not the log's operator: fetches the log's latest
+                                                 checkpoint per watched log, proves it extends the last one it signed, and countersigns it
+                                                 into <dir>; refuses and writes an alarm otherwise. Serve <dir> from a host of your own.
   signer  --key <log.key> --port 8790 [--host 127.0.0.1] [--token-env NAME] [--retired-key <pub>]...
                                                  the one process that holds the log's key: POST /sign, GET /keys
   log-admin --db-env NAME tenant add <id> [--log-id <id>] | tenant list | tenant disable <id>
   log-admin --db-env NAME token add <tenant> --label <text> | token list <tenant> | token revoke <tenant> <hash-prefix>
   log-admin --db-env NAME import --file <log.jsonl> [--tenant default]      copies a file log into the database as hashes
-  audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) [--issuer-key <pub>] [--log-key <pub>] [--log-id <id>] [--json]
-                                                 with --log-url the log's published keys are fetched and pinned by keyid
+  audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) [--issuer-key <pub>] [--log-key <pub>] [--log-id <id>] [--witness-key <pub> | --witness-url <url>] [--json]
+                                                 with --log-url the log's published keys are fetched and pinned by keyid; with a witness key or
+                                                 URL the newer head must also carry the witness's countersignature
           checks that the newer receipt's log extends the older one's: nothing between them was rewritten
 `;
 /** A retired public key for the key document, from a .pub file; still listed so heads it signed keep verifying. */
@@ -157,6 +164,26 @@ async function main(argv) {
             await running.close();
             return 0;
         }
+        case "witness": {
+            const { values } = parseArgs({ args: rest, options: { key: { type: "string" }, "log-url": { type: "string" }, "checkpoints-url": { type: "string" }, out: { type: "string" }, tenant: { type: "string", multiple: true }, every: { type: "string", default: "300" }, once: { type: "boolean", default: false } } });
+            if (!values.key || !values["log-url"] || !values["checkpoints-url"] || !values.out)
+                throw new Error("witness needs --key, --log-url, --checkpoints-url, and --out");
+            const w = new Witness({ logUrl: values["log-url"], checkpointsUrl: values["checkpoints-url"], tenants: values.tenant?.length ? values.tenant : ["default"], key: loadPrivateKey(values.key), outDir: values.out });
+            const everyMs = Number(values.every) * 1000;
+            if (!(everyMs > 0))
+                throw new Error("--every must be a positive number of seconds");
+            if (values.once) {
+                const outcomes = await w.runOnce();
+                for (const o of outcomes)
+                    console.log(`${o.tenant.padEnd(20)} ${o.outcome}${"treeSize" in o ? ` at ${o.treeSize}` : ""}${"reason" in o ? `: ${o.reason}` : ""}`);
+                return outcomes.some((o) => o.outcome === "refused") ? 1 : 0;
+            }
+            console.error(`agent-custody witness: keyid=${w.keyid} watching ${values["log-url"]} via ${values["checkpoints-url"]} every ${values.every}s, writing to ${values.out}`);
+            w.start(everyMs);
+            await new Promise((resolve) => process.once("SIGINT", resolve));
+            w.stop();
+            return 0;
+        }
         case "signer": {
             const { values } = parseArgs({ args: rest, options: { key: { type: "string" }, port: { type: "string", default: "8790" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" }, "retired-key": { type: "string", multiple: true } } });
             if (!values.key)
@@ -339,19 +366,31 @@ async function main(argv) {
                     "issuer-key": { type: "string", multiple: true },
                     "log-key": { type: "string", multiple: true },
                     "log-id": { type: "string" },
+                    "witness-key": { type: "string", multiple: true },
+                    "witness-url": { type: "string" },
                     json: { type: "boolean", default: false },
                 },
             });
             const keyFiles = [...(values["issuer-key"] ?? []), ...(values["log-key"] ?? [])];
             if (!values.older || !values.newer)
                 throw new Error("audit needs --older and --newer");
+            const witnessKeys = [...(values["witness-key"] ?? []).map(loadPublicKey), ...(values["witness-url"] ? await fetchWitnessKeys(values["witness-url"]) : [])];
             if (!values.log === !values["log-url"])
                 throw new Error("audit needs exactly one of --log or --log-url");
             const auditKeys = [...keyFiles.map(loadPublicKey), ...(values["log-url"] ? (await fetchLogKeys(values["log-url"])).keys : [])];
             if (auditKeys.length === 0)
                 throw new Error("audit needs a key: --issuer-key, --log-key, or a --log-url that publishes its keys");
-            const older = JSON.parse(readFileSync(values.older, "utf8")).treeHead;
-            const newer = JSON.parse(readFileSync(values.newer, "utf8")).treeHead;
+            // --older and --newer take a receipt bundle, or a checkpoint file from the log's or the witness's host
+            const headOf = (file) => {
+                const j = JSON.parse(readFileSync(file, "utf8"));
+                if (j.treeHead)
+                    return j.treeHead;
+                if (j.envelope && j.envelope.payloadType === TREEHEAD_TYPE)
+                    return j.envelope;
+                throw new Error(`${file} is neither a receipt bundle nor a checkpoint`);
+            };
+            const older = headOf(values.older);
+            const newer = headOf(values.newer);
             const sizeOf = (env) => JSON.parse(Buffer.from(env.payload, "base64").toString()).treeSize;
             const [m, n] = [sizeOf(older), sizeOf(newer)];
             let proof;
@@ -363,7 +402,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, auditKeys, values["log-id"]);
+            const result = auditExtends(older, newer, proof, auditKeys, values["log-id"], witnessKeys.length ? { witnessKeys } : {});
             if (values.json)
                 console.log(JSON.stringify(result, null, 2));
             else {

package/dist/crypto.d.ts

@@ -32,6 +32,10 @@ export interface Envelope {
     }[];
 }
 export declare function dsseSign(payloadType: string, payloadObj: unknown, kp: KeyPair): Envelope;
+/** Adds a signature over the same payload: a countersignature, the DSSE way. The envelope keeps every earlier signature. */
+export declare function dsseCountersign(env: Envelope, kp: KeyPair): Envelope;
+/** Every trusted key whose signature on the envelope verifies, by keyid. Empty when none does. */
+export declare function dsseVerifiers(env: Envelope, trusted: PublicKeyRef[]): string[];
 export type DsseVerifyResult = {
     ok: true;
     payload: unknown;

package/dist/crypto.js

@@ -70,6 +70,26 @@ export function dsseSign(payloadType, payloadObj, kp) {
         signatures: [{ keyid: kp.keyid, sig: sig.toString("base64") }],
     };
 }
+/** Adds a signature over the same payload: a countersignature, the DSSE way. The envelope keeps every earlier signature. */
+export function dsseCountersign(env, kp) {
+    const payload = Buffer.from(env.payload, "base64");
+    const sig = sign(null, pae(env.payloadType, payload), kp.privateKey);
+    return { ...env, signatures: [...env.signatures.filter((s) => s.keyid !== kp.keyid), { keyid: kp.keyid, sig: sig.toString("base64") }] };
+}
+/** Every trusted key whose signature on the envelope verifies, by keyid. Empty when none does. */
+export function dsseVerifiers(env, trusted) {
+    if (!env || typeof env.payload !== "string" || !Array.isArray(env.signatures))
+        return [];
+    const payload = Buffer.from(env.payload, "base64");
+    const data = pae(env.payloadType, payload);
+    const out = [];
+    for (const s of env.signatures) {
+        const key = trusted.find((t) => t.keyid === s.keyid);
+        if (key && verify(null, data, key.publicKey, Buffer.from(s.sig, "base64")))
+            out.push(s.keyid);
+    }
+    return out;
+}
 /** Verifies the envelope against any of the given trusted keys, matched by keyid. */
 export function dsseVerify(env, trusted) {
     if (!env || typeof env.payload !== "string" || !Array.isArray(env.signatures) || env.signatures.length === 0) {

package/dist/index.d.ts

@@ -8,6 +8,9 @@ export { connectSigner, fetchLogKeys, localSigner, serveSigner, signerHandler }
 export type { KeyDocument, RemoteSignerOptions, RetiredKey, RunningSigner, Signer, SignerServerOptions } from "./signer.ts";
 export { bothCheckpoints, dirCheckpoints, postgresCheckpoints } from "./checkpoints.ts";
 export { adminRoutes, welcomeSheet } from "./log-admin.ts";
+export { fetchWitnessKeys, Witness } from "./witness.ts";
+export type { WitnessOptions, WitnessOutcome, WitnessedCheckpoint } from "./witness.ts";
+export type { AuditOptions } from "./verify.ts";
 export type { AdminOptions } from "./log-admin.ts";
 export type { Checkpoint, CheckpointStore } from "./checkpoints.ts";
 export type { AppendResult, LogBackend, PostgresLike, PostgresLogOptions, RateLimitOptions, Tenant, TokenRecord } from "./log-store.ts";

package/dist/index.js

@@ -6,6 +6,7 @@ export { fileBackend, importLogFile, PostgresLog, PostgresTenancy, RateLimiter }
 export { connectSigner, fetchLogKeys, localSigner, serveSigner, signerHandler } from "./signer.js";
 export { bothCheckpoints, dirCheckpoints, postgresCheckpoints } from "./checkpoints.js";
 export { adminRoutes, welcomeSheet } from "./log-admin.js";
+export { fetchWitnessKeys, Witness } from "./witness.js";
 export * from "./config.js";
 export * from "./crypto.js";
 export * from "./delegation.js";

package/dist/verify.d.ts

@@ -37,6 +37,10 @@ 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[], logId?: string): AuditResult;
+export interface AuditOptions {
+    /** with these, the newer head must also carry a signature by one of them: a witness that is not the log's operator */
+    witnessKeys?: PublicKeyRef[];
+}
+export declare function auditExtends(older: Envelope, newer: Envelope, proof: string[], keys: PublicKeyRef[], logId?: string, opts?: AuditOptions): 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,5 +1,5 @@
 // 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 { canonicalize, digestOf, dsseVerifiers, dsseVerify } from "./crypto.js";
 import { delegationValidAt, verifyDelegation } from "./delegation.js";
 import { leafHash, MerkleLog, verifyConsistency, verifyInclusion } from "./log.js";
 import { checkProvider, checkUpstream, contentDigest, isProviderAttestation } from "./upstream.js";
@@ -111,11 +111,7 @@ 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, logId) {
+export function auditExtends(older, newer, proof, keys, logId, opts = {}) {
     const checks = [];
     const add = (name, ok, detail) => {
         checks.push(detail === undefined ? { name, ok } : { name, ok, detail });
@@ -138,6 +134,10 @@ export function auditExtends(older, newer, proof, keys, logId) {
         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");
+    if (opts.witnessKeys && opts.witnessKeys.length > 0) {
+        const by = dsseVerifiers(newer, opts.witnessKeys);
+        add("newer tree head countersigned by a witness", by.length > 0, by.length ? `witness ${short(by[0])}` : "no witness signature on the newer head");
+    }
     return { ok: checks.every((c) => c.ok), checks, older: a, newer: b };
 }
 const ISSUER_NOTE = {

package/dist/witness.d.ts

@@ -0,0 +1,65 @@
+import { type Envelope, type KeyPair, type PublicKeyRef } from "./crypto.ts";
+export interface WitnessOptions {
+    /** the log's API base, e.g. https://log.example.com/; the key document and consistency proofs come from here */
+    logUrl: string;
+    /** where the log publishes checkpoints, e.g. https://checkpoints.example.com/ */
+    checkpointsUrl: string;
+    /** which logs to watch: "default" for the root paths, else tenant names */
+    tenants: string[];
+    key: KeyPair;
+    /** where countersigned checkpoints, alarms, the witness's own key document, and its state go */
+    outDir: string;
+    fetch?: typeof fetch;
+    warn?: (message: string) => void;
+}
+export interface WitnessedCheckpoint {
+    tenant: string;
+    logId: string | undefined;
+    treeSize: number;
+    rootHash: string;
+    /** the log's checkpoint envelope with the witness's signature added */
+    envelope: Envelope;
+    witness: {
+        keyid: string;
+        at: string;
+    };
+}
+export type WitnessOutcome = {
+    tenant: string;
+    outcome: "countersigned";
+    treeSize: number;
+} | {
+    tenant: string;
+    outcome: "unchanged";
+    treeSize: number;
+} | {
+    tenant: string;
+    outcome: "refused";
+    reason: string;
+} | {
+    tenant: string;
+    outcome: "unavailable";
+    reason: string;
+};
+export declare class Witness {
+    private readonly o;
+    private readonly f;
+    private readonly warn;
+    private timer;
+    constructor(opts: WitnessOptions);
+    get keyid(): string;
+    private folder;
+    private state;
+    private logKeys;
+    private latest;
+    private proof;
+    /** One pass over every watched log. Never throws; every outcome is returned and the bad ones are also on disk. */
+    runOnce(): Promise<WitnessOutcome[]>;
+    private witnessOne;
+    /** A refusal is written where the countersignatures would have gone, so whoever reads the witness's host sees it. */
+    private refuse;
+    start(everyMs?: number): void;
+    stop(): void;
+}
+/** For verifiers: the witness's published keys, fetched from its host and pinned by keyid. */
+export declare function fetchWitnessKeys(witnessUrl: string, f?: typeof fetch): Promise<PublicKeyRef[]>;

package/dist/witness.js

@@ -0,0 +1,155 @@
+// The witness: a second signer, run by someone who is not the log's operator, that watches a log's published
+// checkpoints and countersigns each one only after proving to itself that it extends the last one it signed. A
+// verifier who requires the witness's signature on a head is protected against the log showing different histories
+// to different people, and against the log's operator rewriting history, because the witness kept the earlier
+// head and refuses, loudly, when the new one does not extend it. It is the phase of the hosted log that makes the
+// log hold against us. It publishes what it signs as files, to be served from a host of its own.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dsseCountersign, dsseVerify, publicKeyFromPem } from "./crypto.js";
+import { verifyConsistency } from "./log.js";
+import { TREEHEAD_TYPE } from "./receipt.js";
+const safe = (s) => s.replace(/[^A-Za-z0-9_.-]/g, "_");
+export class Witness {
+    o;
+    f;
+    warn;
+    timer = null;
+    constructor(opts) {
+        this.o = opts;
+        this.f = opts.fetch ?? fetch;
+        this.warn = opts.warn ?? ((m) => console.error(m));
+        mkdirSync(join(opts.outDir, ".well-known"), { recursive: true });
+        // The witness's own key document, for verifiers to pin the way they pin the log's.
+        const doc = { keys: [{ keyid: opts.key.keyid, alg: "ed25519", publicKeyPem: opts.key.publicKey.export({ type: "spki", format: "pem" }), validFrom: new Date().toISOString() }] };
+        writeFileSync(join(opts.outDir, ".well-known", "agent-custody-witness.json"), JSON.stringify(doc, null, 2));
+    }
+    get keyid() {
+        return this.o.key.keyid;
+    }
+    folder(tenant) {
+        const d = join(this.o.outDir, safe(tenant));
+        mkdirSync(d, { recursive: true });
+        return d;
+    }
+    state(tenant) {
+        try {
+            return JSON.parse(readFileSync(join(this.folder(tenant), "state.json"), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    async logKeys() {
+        const res = await this.f(new URL("/.well-known/agent-custody-log.json", this.o.logUrl));
+        if (!res.ok)
+            throw new Error(`log key document: ${res.status}`);
+        const doc = (await res.json());
+        return doc.keys.map((k) => publicKeyFromPem(k.publicKeyPem));
+    }
+    async latest(tenant) {
+        const base = this.o.checkpointsUrl.endsWith("/") ? this.o.checkpointsUrl : `${this.o.checkpointsUrl}/`;
+        const res = await this.f(new URL(`${safe(tenant)}/latest.json`, base));
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`checkpoint for ${tenant}: ${res.status}`);
+        return (await res.json());
+    }
+    async proof(tenant, oldSize, newSize) {
+        const base = this.o.logUrl.endsWith("/") ? this.o.logUrl : `${this.o.logUrl}/`;
+        const path = tenant === "default" ? `consistency?old=${oldSize}&new=${newSize}` : `t/${tenant}/consistency?old=${oldSize}&new=${newSize}`;
+        const res = await this.f(new URL(path, base));
+        if (!res.ok)
+            throw new Error(`consistency proof for ${tenant}: ${res.status}`);
+        return (await res.json()).hashes;
+    }
+    /** One pass over every watched log. Never throws; every outcome is returned and the bad ones are also on disk. */
+    async runOnce() {
+        const out = [];
+        let keys;
+        try {
+            keys = await this.logKeys();
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            this.warn(`agent-custody witness: ${reason}`);
+            return this.o.tenants.map((tenant) => ({ tenant, outcome: "unavailable", reason }));
+        }
+        for (const tenant of this.o.tenants) {
+            try {
+                out.push(await this.witnessOne(tenant, keys));
+            }
+            catch (e) {
+                const reason = e instanceof Error ? e.message : String(e);
+                this.warn(`agent-custody witness: ${tenant}: ${reason}`);
+                out.push({ tenant, outcome: "unavailable", reason });
+            }
+        }
+        return out;
+    }
+    async witnessOne(tenant, keys) {
+        const cp = await this.latest(tenant);
+        if (!cp)
+            return { tenant, outcome: "unavailable", reason: "no checkpoint published yet" };
+        const v = dsseVerify(cp.envelope, keys);
+        if (!v.ok || cp.envelope.payloadType !== TREEHEAD_TYPE)
+            return this.refuse(tenant, `checkpoint does not verify against the log's published keys: ${v.ok ? "not a tree head" : v.error}`, cp.envelope);
+        const head = v.payload;
+        const prev = this.state(tenant);
+        if (prev) {
+            if (prev.logId !== head.log)
+                return this.refuse(tenant, `checkpoint names log ${head.log ?? "none"}, the last one signed named ${prev.logId ?? "none"}`, cp.envelope);
+            if (head.treeSize < prev.treeSize)
+                return this.refuse(tenant, `checkpoint at size ${head.treeSize} is smaller than the last one signed at ${prev.treeSize}`, cp.envelope);
+            if (head.treeSize === prev.treeSize) {
+                if (head.rootHash !== prev.rootHash)
+                    return this.refuse(tenant, `a different root at the same size ${head.treeSize}: the log shows two histories`, cp.envelope);
+                return { tenant, outcome: "unchanged", treeSize: head.treeSize };
+            }
+            const proof = await this.proof(tenant, prev.treeSize, head.treeSize);
+            if (!verifyConsistency(prev.treeSize, prev.rootHash, head.treeSize, head.rootHash, proof))
+                return this.refuse(tenant, `the log at ${head.treeSize} does not extend the head signed at ${prev.treeSize}: history was rewritten`, cp.envelope);
+        }
+        const envelope = dsseCountersign(cp.envelope, this.o.key);
+        const at = new Date().toISOString();
+        const record = { tenant, logId: head.log, treeSize: head.treeSize, rootHash: head.rootHash, envelope, witness: { keyid: this.o.key.keyid, at } };
+        const dir = this.folder(tenant);
+        const text = JSON.stringify(record, null, 2);
+        writeFileSync(join(dir, `${head.treeSize}.json`), text);
+        writeFileSync(join(dir, "latest.json"), text);
+        writeFileSync(join(dir, "state.json"), JSON.stringify({ treeSize: head.treeSize, rootHash: head.rootHash, logId: head.log }));
+        return { tenant, outcome: "countersigned", treeSize: head.treeSize };
+    }
+    /** A refusal is written where the countersignatures would have gone, so whoever reads the witness's host sees it. */
+    refuse(tenant, reason, envelope) {
+        const dir = this.folder(tenant);
+        const at = new Date().toISOString();
+        writeFileSync(join(dir, `ALARM-${at.replace(/[:.]/g, "-")}.json`), JSON.stringify({ tenant, at, reason, checkpoint: envelope }, null, 2));
+        writeFileSync(join(dir, "ALARM.json"), JSON.stringify({ tenant, at, reason }, null, 2));
+        this.warn(`agent-custody witness: REFUSED ${tenant}: ${reason}`);
+        return { tenant, outcome: "refused", reason };
+    }
+    start(everyMs = 300_000) {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => void this.runOnce(), everyMs);
+        this.timer.unref?.();
+        void this.runOnce();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+}
+/** For verifiers: the witness's published keys, fetched from its host and pinned by keyid. */
+export async function fetchWitnessKeys(witnessUrl, f = fetch) {
+    const res = await f(new URL("/.well-known/agent-custody-witness.json", witnessUrl));
+    if (!res.ok)
+        throw new Error(`witness ${witnessUrl} serves no key document: ${res.status}`);
+    const doc = (await res.json());
+    if (!Array.isArray(doc.keys) || doc.keys.length === 0)
+        throw new Error(`witness ${witnessUrl} lists no keys`);
+    return doc.keys.map((k) => publicKeyFromPem(k.publicKeyPem));
+}

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. 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. With `--db-env DATABASE_URL` the server keeps its logs in Postgres instead of files, and needs the `pg` package beside it: leaves as hashes in one table keyed by tenant, one writer per tenant enforced with an advisory lock so a second instance is safe, tenants and their tokens in tables of their own with tokens stored only as hashes, and rate limits per token (50 appends a second, burst 100, a 64 KB body cap; a refused append answers 429 with `retry-after`, and the gateway's sink retries a few times). Tenants are managed with `log-admin --db-env DATABASE_URL`: `tenant add <id> [--log-id <id>]`, `token add <tenant> --label <text>` (the token is printed once), `token revoke <tenant> <hash-prefix>`, `tenant disable <id>`, and `import --file log.jsonl [--tenant default]` to bring an existing file log in as hashes. The root paths serve the tenant `default`, created on first start with `--log-id`, and `--token-env` still works for it. The key that signs tree heads can live in its own process: `agent-custody signer --key keys/log.key --port 8790 --token-env SIGNER_TOKEN` holds it and answers `POST /sign` with the shared secret and `GET /keys` to anyone; the log server then runs with `--signer-url http://signer:8790/ --signer-token-env SIGNER_TOKEN` instead of `--key`, and the process that faces the internet never holds the key. Either way the log serves its keys at `/.well-known/agent-custody-log.json`, current key first and retired keys (`--retired-key old.pub`) after it, so verifiers fetch and pin them with `verify --log-url` and `audit --log-url` rather than receiving a key file from the operator. With `--checkpoint-dir <dir>` the server publishes a signed checkpoint, every `--checkpoint-every` seconds (default 300), for each log whose tree has grown, as `<dir>/<tenant>/<treeSize>.json` and `latest.json`, and with a database also as rows; `GET /checkpoints?since=<size>` and `GET /t/<tenant>/checkpoints` list them. Serve the directory read-only from a second host, so the record of what the log signed does not depend on the log's API being up; a verifier who kept an earlier head audits against a later checkpoint with `audit --older <bundle> --newer <checkpoint> --log-url <url>`. With `--admin-token-env ADMIN_TOKEN` (Postgres only) the server also serves the operator's page at `/admin` and its API under `/admin/`: list and create tenants, mint a token that is shown once beside the tenant's welcome sheet, revoke tokens, disable tenants. Everything under `/admin`, the page included, needs the admin token: the browser asks for it (any user name, the token as the password) and an API client sends it as a bearer; a handful of wrong attempts from one address are throttled for a minute. Nothing is stored by the page. Behind a reverse proxy, start the server with `--trust-proxy` so those per-address limits key on `X-Forwarded-For` instead of on the proxy's own address, and only there, since the header is otherwise the client's to forge. `--public-url` and `--checkpoints-url` fill the sheet in. [deploy/](../../deploy/README.md) runs the server, the signer, Postgres, and the checkpoints host as containers.
+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. With `--db-env DATABASE_URL` the server keeps its logs in Postgres instead of files, and needs the `pg` package beside it: leaves as hashes in one table keyed by tenant, one writer per tenant enforced with an advisory lock so a second instance is safe, tenants and their tokens in tables of their own with tokens stored only as hashes, and rate limits per token (50 appends a second, burst 100, a 64 KB body cap; a refused append answers 429 with `retry-after`, and the gateway's sink retries a few times). Tenants are managed with `log-admin --db-env DATABASE_URL`: `tenant add <id> [--log-id <id>]`, `token add <tenant> --label <text>` (the token is printed once), `token revoke <tenant> <hash-prefix>`, `tenant disable <id>`, and `import --file log.jsonl [--tenant default]` to bring an existing file log in as hashes. The root paths serve the tenant `default`, created on first start with `--log-id`, and `--token-env` still works for it. The key that signs tree heads can live in its own process: `agent-custody signer --key keys/log.key --port 8790 --token-env SIGNER_TOKEN` holds it and answers `POST /sign` with the shared secret and `GET /keys` to anyone; the log server then runs with `--signer-url http://signer:8790/ --signer-token-env SIGNER_TOKEN` instead of `--key`, and the process that faces the internet never holds the key. Either way the log serves its keys at `/.well-known/agent-custody-log.json`, current key first and retired keys (`--retired-key old.pub`) after it, so verifiers fetch and pin them with `verify --log-url` and `audit --log-url` rather than receiving a key file from the operator. With `--checkpoint-dir <dir>` the server publishes a signed checkpoint, every `--checkpoint-every` seconds (default 300), for each log whose tree has grown, as `<dir>/<tenant>/<treeSize>.json` and `latest.json`, and with a database also as rows; `GET /checkpoints?since=<size>` and `GET /t/<tenant>/checkpoints` list them. Serve the directory read-only from a second host, so the record of what the log signed does not depend on the log's API being up; a verifier who kept an earlier head audits against a later checkpoint with `audit --older <bundle> --newer <checkpoint> --log-url <url>`. With `--admin-token-env ADMIN_TOKEN` (Postgres only) the server also serves the operator's page at `/admin` and its API under `/admin/`: list and create tenants, mint a token that is shown once beside the tenant's welcome sheet, revoke tokens, disable tenants. Everything under `/admin`, the page included, needs the admin token: the browser asks for it (any user name, the token as the password) and an API client sends it as a bearer; a handful of wrong attempts from one address are throttled for a minute. Nothing is stored by the page. Behind a reverse proxy, start the server with `--trust-proxy` so those per-address limits key on `X-Forwarded-For` instead of on the proxy's own address, and only there, since the header is otherwise the client's to forge. `--public-url` and `--checkpoints-url` fill the sheet in. The witness closes the last gap: `agent-custody witness --key witness.key --log-url <url> --checkpoints-url <url> --out <dir> [--tenant <name>]...` runs on a machine the log's operator does not control, fetches each watched log's latest checkpoint, verifies it against the log's published keys, proves with the log's consistency proof that it extends the last head the witness signed, and countersigns it into `<dir>/<tenant>/<size>.json` and `latest.json`; a checkpoint that does not extend, or a second history at the same size, gets `ALARM.json` instead. Its key document is `<dir>/.well-known/agent-custody-witness.json`. Serve `<dir>` from the witness's own host; verifiers add `--witness-url` (or `--witness-key`) to `audit`, and the newer head must then carry the witness's signature. [deploy/](../../deploy/README.md) runs the server, the signer, Postgres, and the checkpoints host as containers, and [deploy/witness/](../../deploy/witness/) the witness.
 
 `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

@@ -163,7 +163,7 @@ An inclusion proof says a receipt was in the log at one moment. It does not say
 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/t/acme/ --log-id acme
 
-`--log-url` also fetches the log's published keys from `/.well-known/agent-custody-log.json` and pins them by keyid, so no key file changes hands; `--log-key` still works for a key you were handed. The same flag on `verify` does the same for a receipt.
+A witness that countersigns the log's checkpoints from a machine the operator does not control is required with `--witness-url https://witness.example.org/` or `--witness-key witness.pub`: the check `newer tree head countersigned by a witness` then has to pass, and `--newer` may be a checkpoint file from the witness's host. `--log-url` also fetches the log's published keys from `/.well-known/agent-custody-log.json` and pins them by keyid, so no key file changes hands; `--log-key` still works for a key you were handed. The same flag on `verify` does the same for a receipt.
 ```
 
 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.5.3",
+  "version": "0.5.4",
   "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": {