@agent-custody/receipts 0.5.6 → 0.5.7

package/README.md

@@ -227,6 +227,7 @@ 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/log-check.ts   the outside monitor: verifies the head, checkpoints, and witness of a running log
+src/log-export.ts  a tenant's export of their own log, self-checked, as a log file the verifier reads
 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
@@ -284,6 +285,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).
 
+- A tenant's export: `log-export` takes, with the tenant's own token, every leaf hash, the signed head, the published keys, the checkpoints, and their usage, checks that they add up, and writes a log copy the verifier reads offline; the evidence never depends on the operator staying in business.
 - Monitoring and metering: `log-check`, the outside probe that verifies the head, the checkpoints, and the witness and exits 1 on trouble, run every ten minutes by the `monitor` workflow; `GET /health`; and usage per tenant per month on the admin page and as CSV.
 - 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).

package/dist/cli.js

@@ -12,6 +12,7 @@ import { bothCheckpoints, dirCheckpoints, postgresCheckpoints } from "./checkpoi
 import { connectSigner, fetchLogKeys, localSigner, serveSigner } from "./signer.js";
 import { fetchWitnessKeys, Witness } from "./witness.js";
 import { checkLog, formatLogCheck } from "./log-check.js";
+import { exportLog, formatExport } from "./log-export.js";
 import { CheckpointPublisher, fileResolver } from "./log-sink.js";
 import { createRequire } from "node:module";
 import { pruneLog } from "./retention.js";
@@ -50,6 +51,9 @@ const USAGE = `agent-custody <command>
                                                  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
   log-check --log-url <url> [--checkpoints-url <url>] [--witness-url <url>] [--tenant <name>]... [--max-lag <seconds>] [--json]
+  log-export --log-url <url> [--tenant <name>] --token-env NAME --out <dir> [--month YYYY-MM]... [--json]
+                                                   a tenant's own log, with their token: every leaf hash as a log file the verifier
+                                                   reads, the signed head, the published keys, the checkpoints, and their usage
                                                  the outside monitor: verifies the head against the published keys, that checkpoints keep up
                                                  with the head and the head extends them, and that the witness countersigns and raises no
                                                  alarm; exits 1 on any failure. Run it from cron or a scheduled workflow elsewhere.
@@ -177,6 +181,17 @@ async function main(argv) {
             console.log(values.json ? JSON.stringify(r, null, 2) : formatLogCheck(r));
             return r.ok ? 0 : 1;
         }
+        case "log-export": {
+            const { values } = parseArgs({ args: rest, options: { "log-url": { type: "string" }, tenant: { type: "string" }, "token-env": { type: "string" }, out: { type: "string" }, month: { type: "string", multiple: true }, json: { type: "boolean", default: false } } });
+            if (!values["log-url"] || !values["token-env"] || !values.out)
+                throw new Error("log-export needs --log-url, --token-env, and --out");
+            const token = process.env[values["token-env"]];
+            if (!token)
+                throw new Error(`environment variable ${values["token-env"]} is not set`);
+            const r = await exportLog({ logUrl: values["log-url"], ...(values.tenant ? { tenant: values.tenant } : {}), token, outDir: values.out, ...(values.month?.length ? { months: values.month } : {}) });
+            console.log(values.json ? JSON.stringify(r, null, 2) : formatExport(r));
+            return r.problems.length ? 1 : 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)
@@ -410,7 +425,7 @@ async function main(argv) {
             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"]}/`));
+                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"]}/`), { signal: AbortSignal.timeout(10_000) });
                 if (!res.ok)
                     throw new Error(`log refused the consistency query: ${res.status}`);
                 proof = (await res.json()).hashes;

package/dist/config.d.ts

@@ -175,6 +175,7 @@ export declare const GatewayConfigSchema: z.ZodObject<{
         url: z.ZodString;
         tokenEnv: z.ZodOptional<z.ZodString>;
         hashOnly: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     otel: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
@@ -207,6 +208,7 @@ export declare const SdkConfigSchema: z.ZodObject<{
         url: z.ZodString;
         tokenEnv: z.ZodOptional<z.ZodString>;
         hashOnly: z.ZodOptional<z.ZodBoolean>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
     }, 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(), /** send leaf hashes only; the log never holds the receipt. Use it for any log run by someone else */ hashOnly: z.boolean().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(), /** milliseconds one append may take before the log counts as unreachable; default 10000 */ timeoutMs: z.number().int().positive().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/index.d.ts

@@ -4,6 +4,8 @@ export type { GatewayOptions } from "./gateway.ts";
 export { buildRequest, restUpstream } from "./rest.ts";
 export { openExporter, otlpExporter, spanFor } from "./otel.ts";
 export { hecEvent, splunkExporter } from "./splunk.ts";
+export { exportLog, formatExport } from "./log-export.ts";
+export type { ExportOptions, ExportResult } from "./log-export.ts";
 export { fileBackend, importLogFile, PostgresLog, PostgresTenancy, RateLimiter } from "./log-store.ts";
 export { connectSigner, fetchLogKeys, localSigner, serveSigner, signerHandler } from "./signer.ts";
 export type { KeyDocument, RemoteSignerOptions, RetiredKey, RunningSigner, Signer, SignerServerOptions } from "./signer.ts";

package/dist/index.js

@@ -3,6 +3,7 @@ export { AUTHORIZATION_PREDICATE_TYPE, buildAuthorizationStatement } from "./rec
 export { buildRequest, restUpstream } from "./rest.js";
 export { openExporter, otlpExporter, spanFor } from "./otel.js";
 export { hecEvent, splunkExporter } from "./splunk.js";
+export { exportLog, formatExport } from "./log-export.js";
 export { fileBackend, importLogFile, PostgresLog, PostgresTenancy, RateLimiter } from "./log-store.js";
 export { connectSigner, fetchLogKeys, localSigner, serveSigner, signerHandler } from "./signer.js";
 export { bothCheckpoints, dirCheckpoints, postgresCheckpoints } from "./checkpoints.js";

package/dist/log-admin.js

@@ -35,6 +35,11 @@ export function welcomeSheet(o) {
         `  npx agent-custody audit --older receipts/<earlier>.json --newer receipts/<later>.json --log-url ${url} --log-id ${o.logId}`,
         "--log-url fetches this log's published keys and pins them; --log-id makes sure the tree heads are this log's.",
         "",
+        "Your log is yours to take, any time, with your token:",
+        `  npx agent-custody log-export --log-url ${url} --tenant ${o.tenant} --token-env AGENT_CUSTODY_LOG_TOKEN --out custody-export/`,
+        "It fetches every leaf hash, the signed head, the keys, the checkpoints, and your usage, checks they add up, and writes",
+        "a log copy that verify --log and audit --log read with no server.",
+        "",
         "What this log does not do: hold receipt contents, forge a receipt (your gateway key signs those), or, today,",
         "countersign with a second independent witness. The proof table: https://agent-custody.dev/receipts/#what-a-receipt-proves-and-what-it-does-not",
     ];

package/dist/log-export.d.ts

@@ -0,0 +1,28 @@
+export interface ExportOptions {
+    logUrl: string;
+    /** the tenant whose log to export; omitted, the log at the root paths */
+    tenant?: string | undefined;
+    token: string;
+    outDir: string;
+    /** months of usage to include, YYYY-MM; default the current and the previous month */
+    months?: string[] | undefined;
+    fetch?: typeof fetch;
+}
+export interface ExportResult {
+    outDir: string;
+    logId: string | null;
+    treeSize: number;
+    rootHash: string;
+    keyid: string;
+    checkpoints: number;
+    usage: {
+        month: string;
+        appends: number;
+        totalLeaves: number;
+        liveTokens: number;
+    }[];
+    /** what did not add up; an export with problems is still written, and says so */
+    problems: string[];
+}
+export declare function exportLog(o: ExportOptions): Promise<ExportResult>;
+export declare function formatExport(r: ExportResult): string;

package/dist/log-export.js

@@ -0,0 +1,84 @@
+// A tenant's export of their own log: every leaf hash, the signed head, the published keys, the signed checkpoints,
+// and their metering, fetched with their own token and written as files they can keep. The leaves go into a log
+// file in the format the verifier already reads, so `verify --log` and `audit --log` work against the export with
+// no server at all. The export checks itself before it is written: the head must verify against the published keys
+// and its root must be the root of the leaves fetched, and the same for every checkpoint. A tenant who leaves takes
+// this with them; a tenant who stays runs it on a schedule so the evidence never depends on one operator.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dsseVerify } from "./crypto.js";
+import { rootOf } from "./log.js";
+import { TREEHEAD_TYPE } from "./receipt.js";
+import { fetchLogKeys } from "./signer.js";
+const monthOf = (d) => d.toISOString().slice(0, 7);
+const previousMonth = (d) => monthOf(new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() - 1, 1)));
+export async function exportLog(o) {
+    const f = o.fetch ?? fetch;
+    const base = o.logUrl.endsWith("/") ? o.logUrl : `${o.logUrl}/`;
+    const path = (op) => new URL(o.tenant ? `t/${o.tenant}/${op}` : op, base);
+    const headers = { authorization: `Bearer ${o.token}` };
+    const get = async (url, auth) => {
+        const res = await f(url, { signal: AbortSignal.timeout(30_000), ...(auth ? { headers } : {}) });
+        if (res.status === 401)
+            throw new Error(`the log refused the token for ${url.pathname}`);
+        if (!res.ok)
+            throw new Error(`${res.status} from ${url.pathname}`);
+        return res.json();
+    };
+    const problems = [];
+    const { doc, keys } = await fetchLogKeys(base, f);
+    const { treeHead } = (await get(path("head"), false));
+    const v = dsseVerify(treeHead, keys);
+    if (!v.ok || treeHead.payloadType !== TREEHEAD_TYPE)
+        throw new Error(`the head does not verify against the published keys: ${v.ok ? "not a tree head" : v.error}`);
+    const head = v.payload;
+    // every leaf, in pages, as of the head's size; leaves appended meanwhile are the next export's
+    const leaves = [];
+    while (leaves.length < head.treeSize) {
+        const page = (await get(new URL(`?since=${leaves.length}&limit=10000`, path("leaves")), true));
+        if (page.leaves.length === 0)
+            throw new Error(`the log returned no leaves past ${leaves.length} of ${head.treeSize}`);
+        leaves.push(...page.leaves.slice(0, head.treeSize - leaves.length));
+    }
+    const hashes = leaves.map((h) => Buffer.from(h, "hex"));
+    const root = rootOf(hashes);
+    if (root !== head.rootHash)
+        problems.push(`the root of the ${leaves.length} leaves fetched (${root.slice(0, 12)}) is not the head's (${head.rootHash.slice(0, 12)})`);
+    const cps = (await get(path("checkpoints"), false));
+    for (const c of cps.checkpoints) {
+        const cv = dsseVerify(c.treeHead, keys);
+        if (!cv.ok)
+            problems.push(`checkpoint at ${c.treeSize} does not verify: ${cv.error}`);
+        else if (c.treeSize <= head.treeSize && rootOf(hashes, c.treeSize) !== c.rootHash)
+            problems.push(`checkpoint at ${c.treeSize} has root ${c.rootHash.slice(0, 12)}, the leaves give ${rootOf(hashes, c.treeSize).slice(0, 12)}`);
+    }
+    const usage = [];
+    for (const month of o.months ?? [monthOf(new Date()), previousMonth(new Date())]) {
+        try {
+            usage.push((await get(new URL(`?month=${month}`, path("usage")), true)));
+        }
+        catch (e) {
+            problems.push(`usage for ${month}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    mkdirSync(o.outDir, { recursive: true });
+    writeFileSync(join(o.outDir, "log.jsonl"), leaves.map((h) => JSON.stringify({ hash: h })).join("\n") + (leaves.length ? "\n" : ""));
+    writeFileSync(join(o.outDir, "head.json"), JSON.stringify({ treeHead, ...head }, null, 2));
+    writeFileSync(join(o.outDir, "keys.json"), JSON.stringify(doc, null, 2));
+    writeFileSync(join(o.outDir, "checkpoints.json"), JSON.stringify(cps.checkpoints, null, 2));
+    writeFileSync(join(o.outDir, "usage.json"), JSON.stringify(usage, null, 2));
+    const result = { outDir: o.outDir, logId: head.log ?? null, treeSize: head.treeSize, rootHash: head.rootHash, keyid: v.keyid, checkpoints: cps.checkpoints.length, usage, problems };
+    writeFileSync(join(o.outDir, "export.json"), JSON.stringify({ exportedAt: new Date().toISOString(), logUrl: base, tenant: o.tenant ?? null, ...result }, null, 2));
+    return result;
+}
+export function formatExport(r) {
+    const lines = [
+        `exported ${r.treeSize} leaf hash(es) of log ${r.logId ?? "(unnamed)"} to ${r.outDir}`,
+        `head root ${r.rootHash.slice(0, 16)}, signed by ${r.keyid.slice(0, 12)}, ${r.checkpoints} checkpoint(s)`,
+        ...r.usage.map((u) => `usage ${u.month}: ${u.appends} append(s), ${u.totalLeaves} leaves in total, ${u.liveTokens} live token(s)`),
+        "",
+        "log.jsonl is a log copy the verifier reads: agent-custody verify <receipt> --log <outDir>/log.jsonl --issuer-key ...",
+        ...(r.problems.length ? ["", ...r.problems.map((p) => `PROBLEM: ${p}`), "", "RESULT: EXPORT DOES NOT ADD UP"] : ["", "RESULT: EXPORT VERIFIED"]),
+    ];
+    return lines.join("\n");
+}

package/dist/log-sink.d.ts

@@ -25,6 +25,8 @@ export interface HttpLogOptions {
     hashOnly?: boolean;
     /** attempts on 429 and 5xx; default 3 */
     retries?: number;
+    /** how long one append may take before it counts as unreachable; default 10000. A log that accepts and never answers must not hold a call forever. */
+    timeoutMs?: number;
     fetch?: typeof fetch;
 }
 /**
@@ -38,6 +40,7 @@ export interface LogConfig {
         url: string;
         tokenEnv?: string | undefined;
         hashOnly?: boolean | undefined;
+        timeoutMs?: number | undefined;
     } | undefined;
 }
 /** The sink a config asks for: a remote log when `log` is set, otherwise the local file. */
@@ -75,10 +78,18 @@ export interface LogServerOptions {
 /** The address a limit is keyed by: the socket's, or the proxy's forwarded one when the proxy is trusted. */
 export declare function clientAddress(req: IncomingMessage, trustProxy?: boolean): string;
 /** One log as the handler sees it, whatever stands behind it. */
+export interface TenantUsage {
+    month: string;
+    appends: number;
+    totalLeaves: number;
+    liveTokens: number;
+}
 export interface ResolvedLog {
     backend: LogBackend;
     logId: string | undefined;
     authorize(token: string | null): Promise<boolean>;
+    /** this log's own metering for a month, where the store keeps it */
+    usage?(month: string): Promise<TenantUsage>;
 }
 /** Turns the tenant in a path, or null for the root paths, into a log. */
 export interface LogResolver {

package/dist/log-sink.js

@@ -44,6 +44,7 @@ export function httpLog(url, opts = {}) {
     const f = opts.fetch ?? fetch;
     const base = url.endsWith("/") ? url : `${url}/`;
     const attempts = opts.retries ?? 3;
+    const timeoutMs = opts.timeoutMs ?? 10_000;
     return {
         kind: "http",
         where: url,
@@ -56,6 +57,7 @@ export function httpLog(url, opts = {}) {
                         method: "POST",
                         headers: { "content-type": "application/json", ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}) },
                         body: JSON.stringify(opts.hashOnly ? { leafHash: leafHash(leaf).toString("hex") } : { leaf }),
+                        signal: AbortSignal.timeout(timeoutMs),
                     });
                 }
                 catch (e) {
@@ -88,7 +90,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 }), ...(cfg.log.hashOnly ? { hashOnly: true } : {}) });
+        return httpLog(cfg.log.url, { ...(token === undefined ? {} : { token }), ...(cfg.log.hashOnly ? { hashOnly: true } : {}), ...(cfg.log.timeoutMs ? { timeoutMs: cfg.log.timeoutMs } : {}) });
     }
     if (!cfg.logFile)
         throw new Error("config needs logFile or log.url");
@@ -147,6 +149,11 @@ export function postgresResolver(tenancy, opts = {}) {
                 backend,
                 logId: t.logId,
                 authorize: async (tok) => (tenant === null && (opts.staticTokens?.length ?? 0) > 0 && tokenMatches(opts.staticTokens, tok)) || (await tenancy.authorize(id, tok)),
+                usage: async (month) => {
+                    const u = await tenancy.usage(month);
+                    const row = u.tenants.find((t) => t.id === id);
+                    return { month, appends: row?.appends ?? 0, totalLeaves: row?.totalLeaves ?? 0, liveTokens: row?.liveTokens ?? 0 };
+                },
             };
         },
         async tenants() {
@@ -259,7 +266,7 @@ export function logHandler(source, keyOrSigner, opts = {}) {
             }
         }
         // /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|checkpoints)$/.exec(url.pathname);
+        const m = /^\/t\/([A-Za-z0-9_.-]+)\/(append|root|consistency|head|checkpoints|leaves|usage)$/.exec(url.pathname);
         let which;
         try {
             which = await resolver.resolve(m ? m[1] : null);
@@ -301,6 +308,27 @@ export function logHandler(source, keyOrSigner, opts = {}) {
                 return json(200, await appendSigned(log, signer, { leaf: parsed.leaf }, logId));
             }
             const current = await log.size();
+            // A tenant's own data, with their token: every leaf hash, in pages, and their metering. The export command
+            // pages through these and rebuilds a log file the verifier reads directly.
+            if (req.method === "GET" && (url.pathname.endsWith("/leaves") || url.pathname.endsWith("/usage"))) {
+                if (!(await which.authorize(bearer(req))))
+                    return json(401, { error: "unauthorized" });
+                if (url.pathname.endsWith("/usage")) {
+                    if (!which.usage)
+                        return json(404, { error: "this log keeps no usage" });
+                    const month = url.searchParams.get("month") ?? new Date().toISOString().slice(0, 7);
+                    if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(month))
+                        return json(400, { error: "month must be YYYY-MM" });
+                    return json(200, await which.usage(month), { "cache-control": "no-store" });
+                }
+                const since = url.searchParams.has("since") ? Number(url.searchParams.get("since")) : 0;
+                const limit = url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : 10_000;
+                if (!Number.isInteger(since) || since < 0 || since > current)
+                    return json(400, { error: `since must be an integer in 0..${current}` });
+                if (!Number.isInteger(limit) || limit < 1 || limit > 10_000)
+                    return json(400, { error: "limit must be an integer in 1..10000" });
+                return json(200, { since, size: current, leaves: await log.leafHashes(since, since + limit) }, { "cache-control": "no-store" });
+            }
             if (req.method === "GET" && url.pathname.endsWith("/root")) {
                 const size = url.searchParams.has("size") ? Number(url.searchParams.get("size")) : current;
                 if (!Number.isInteger(size) || size < 0 || size > current)

package/dist/log-store.d.ts

@@ -9,6 +9,8 @@ export interface LogBackend {
     appendHash(leafHashHex: string): Promise<AppendResult>;
     root(size?: number): Promise<string>;
     consistencyProof(oldSize: number, newSize?: number): Promise<string[]>;
+    /** leaf hashes from (inclusive) to (exclusive), hex */
+    leafHashes(from: number, to: number): Promise<string[]>;
 }
 /** The JSONL file log behind the asynchronous interface. */
 export declare function fileBackend(file: string): LogBackend;
@@ -51,6 +53,7 @@ export declare class PostgresLog implements LogBackend {
     private commit;
     append(leaf: string): Promise<AppendResult>;
     appendHash(leafHashHex: string): Promise<AppendResult>;
+    leafHashes(from: number, to: number): Promise<string[]>;
     root(size?: number): Promise<string>;
     consistencyProof(oldSize: number, newSize?: number): Promise<string[]>;
 }

package/dist/log-store.js

@@ -22,6 +22,9 @@ export function fileBackend(file) {
         async root(size) {
             return log.root(size);
         },
+        async leafHashes(from, to) {
+            return log.leafHashes(from, to);
+        },
         async consistencyProof(oldSize, newSize) {
             return log.consistencyProof(oldSize, newSize);
         },
@@ -146,6 +149,10 @@ export class PostgresLog {
             throw new Error("leafHash must be 64 lowercase hex characters");
         return this.commit(Buffer.from(leafHashHex, "hex"));
     }
+    async leafHashes(from, to) {
+        const n = await this.size();
+        return this.hashes.slice(Math.max(0, from), Math.min(to, n)).map((h) => h.toString("hex"));
+    }
     async root(size) {
         await this.sync();
         const n = size ?? this.hashes.length;

package/dist/log.d.ts

@@ -31,6 +31,8 @@ export declare class MerkleLog {
     private readonly file;
     constructor(file: string);
     get size(): number;
+    /** Leaf hashes `from` (inclusive) to `to` (exclusive), as hex: what an export carries and what a copy is rebuilt from. */
+    leafHashes(from: number, to?: number): string[];
     /** Appends a leaf (an opaque string, typically a canonical JSON envelope). Returns its proof against the new root. */
     append(leaf: string): InclusionProof & {
         rootHash: string;

package/dist/log.js

@@ -177,6 +177,10 @@ export class MerkleLog {
     get size() {
         return this.hashes.length;
     }
+    /** Leaf hashes `from` (inclusive) to `to` (exclusive), as hex: what an export carries and what a copy is rebuilt from. */
+    leafHashes(from, to = this.hashes.length) {
+        return this.hashes.slice(Math.max(0, from), Math.min(to, this.hashes.length)).map((h) => h.toString("hex"));
+    }
     /** 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");

package/dist/signer.js

@@ -30,7 +30,7 @@ export async function connectSigner(url, opts = {}) {
     const f = opts.fetch ?? fetch;
     const base = url.endsWith("/") ? url : `${url}/`;
     const headers = { "content-type": "application/json", ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}) };
-    const res = await f(new URL("keys", base), { headers });
+    const res = await f(new URL("keys", base), { headers, signal: AbortSignal.timeout(10_000) });
     if (!res.ok)
         throw new Error(`signer ${url} refused the key request: ${res.status}`);
     const doc = (await res.json());
@@ -49,7 +49,7 @@ export async function connectSigner(url, opts = {}) {
             return env;
         },
         async keys() {
-            const k = await f(new URL("keys", base), { headers });
+            const k = await f(new URL("keys", base), { headers, signal: AbortSignal.timeout(10_000) });
             if (!k.ok)
                 throw new Error(`signer ${url} refused the key request: ${k.status}`);
             return (await k.json());
@@ -120,7 +120,7 @@ export function serveSigner(kp, opts) {
 }
 /** For verifiers: the keys a log publishes, fetched from its origin and returned as key references pinned by keyid. */
 export async function fetchLogKeys(logUrl, f = fetch) {
-    const res = await f(new URL("/.well-known/agent-custody-log.json", logUrl));
+    const res = await f(new URL("/.well-known/agent-custody-log.json", logUrl), { signal: AbortSignal.timeout(10_000) });
     if (!res.ok)
         throw new Error(`log ${logUrl} serves no key document: ${res.status}`);
     const doc = (await res.json());

package/dist/witness.js

@@ -145,7 +145,7 @@ export class Witness {
 }
 /** 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));
+    const res = await f(new URL("/.well-known/agent-custody-witness.json", witnessUrl), { signal: AbortSignal.timeout(10_000) });
     if (!res.ok)
         throw new Error(`witness ${witnessUrl} serves no key document: ${res.status}`);
     const doc = (await res.json());

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. 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. Two more things an operator needs. `agent-custody log-check --log-url <url> --checkpoints-url <url> [--witness-url <url>] [--tenant <name>]... [--max-lag <seconds>]` is the outside monitor: it verifies the head against the published keys, that the latest checkpoint verifies and keeps up with the head, that the head extends the checkpoint, and, with a witness, that the witness has countersigned, keeps up, and has raised no alarm; it exits 1 on any failure, so cron or a scheduled workflow on a machine that is not the log's turns it into an alert. `GET /health` on the server is the liveness check for a load balancer. And `GET /admin/usage?month=YYYY-MM`, on the admin page and as `/admin/usage.csv`, is the metering: appends per tenant for the month, leaves in total, live tokens, the numbers any invoice rests on. [deploy/](../../deploy/README.md) runs the server, the signer, Postgres, and the checkpoints host as containers, and [deploy/witness/](../../deploy/witness/) the witness.
+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`. An append that gets no answer within `timeoutMs` (default 10000) counts as unreachable and is retried like a server error, so a log that accepts connections and never answers cannot hold a call forever. 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. Two more things an operator needs. `agent-custody log-check --log-url <url> --checkpoints-url <url> [--witness-url <url>] [--tenant <name>]... [--max-lag <seconds>]` is the outside monitor: it verifies the head against the published keys, that the latest checkpoint verifies and keeps up with the head, that the head extends the checkpoint, and, with a witness, that the witness has countersigned, keeps up, and has raised no alarm; it exits 1 on any failure, so cron or a scheduled workflow on a machine that is not the log's turns it into an alert. `GET /health` on the server is the liveness check for a load balancer. And `GET /admin/usage?month=YYYY-MM`, on the admin page and as `/admin/usage.csv`, is the metering: appends per tenant for the month, leaves in total, live tokens, the numbers any invoice rests on. A tenant needs none of that to leave with their evidence: `agent-custody log-export --log-url <url> --tenant <name> --token-env AGENT_CUSTODY_LOG_TOKEN --out <dir>` fetches, with their own token, every leaf hash (`GET /t/<name>/leaves?since=&limit=`, pages of up to ten thousand), the signed head, the published keys, the signed checkpoints, and their own usage (`GET /t/<name>/usage?month=`), checks that the head and every checkpoint verify against the keys and that the leaves fetched hash to their roots, and writes `log.jsonl` in the format `verify --log` and `audit --log` read, so the export verifies receipts with no server at all. It exits 1 and says what did not add up if anything does not. Both routes answer only to that tenant's token. [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/package.json

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