@agent-custody/receipts 0.5.7 → 0.5.8

package/README.md

@@ -15,6 +15,7 @@ Anyone holding the public keys can verify a receipt offline. The agent is not tr
 - [Writing policies](docs/policies.md): how a tool call becomes a Cedar request, with tested examples
 - [Verifying a receipt](docs/verification.md): what each check means and what a verified receipt does and does not prove
 - [What the evidence satisfies](docs/compliance.md): the receipts, packs, and certificates mapped to SOC 2, ISO 27001, the EU AI Act, and UK GDPR, with what none of them claims
+- [Threat model](docs/threat-model.md): every party who could make a receipt false, the move, what stops it, and whether that is a property of the evidence or of the deployment; and what is not defended
 
 ## Getting started
 
@@ -285,6 +286,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).
 
+- An audit trail of administrative actions: every tenant created or disabled and every token minted or revoked is recorded with who did it, from the admin page or the command line, shown on the page and carried in the tenant's export.
 - 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).

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { hostname, userInfo } from "node:os";
 import { parseArgs } from "node:util";
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
@@ -65,6 +66,7 @@ const USAGE = `agent-custody <command>
                                                  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 audit [--tenant <id>]   who did what to tenants and tokens, newest first
   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>] [--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
@@ -232,8 +234,9 @@ async function main(argv) {
                 throw new Error("log-admin needs --db-env NAME");
             const tenancy = new PostgresTenancy(openPostgres(values["db-env"]));
             const [what, verb, ...args] = positionals;
+            const actor = `cli:${userInfo().username}@${hostname()}`;
             if (what === "tenant" && verb === "add" && args[0]) {
-                const t = await tenancy.addTenant(args[0], values["log-id"] ?? args[0]);
+                const t = await tenancy.addTenant(args[0], values["log-id"] ?? args[0], actor);
                 console.log(`tenant ${t.id} log=${t.logId} reached at /t/${t.id}/`);
             }
             else if (what === "tenant" && verb === "list") {
@@ -241,13 +244,13 @@ async function main(argv) {
                     console.log(`${t.id.padEnd(24)} log=${t.logId.padEnd(28)} created ${t.createdAt}${t.disabledAt ? `  DISABLED ${t.disabledAt}` : ""}`);
             }
             else if (what === "tenant" && verb === "disable" && args[0]) {
-                await tenancy.disableTenant(args[0]);
+                await tenancy.disableTenant(args[0], actor);
                 console.log(`tenant ${args[0]} disabled`);
             }
             else if (what === "token" && verb === "add" && args[0]) {
                 if (!values.label)
                     throw new Error("token add needs --label");
-                const { token, tokenHash } = await tenancy.addToken(args[0], values.label);
+                const { token, tokenHash } = await tenancy.addToken(args[0], values.label, actor);
                 console.error(`token for ${args[0]} (${values.label}); shown once, stored as hash ${tokenHash.slice(0, 12)}…:`);
                 console.log(token);
             }
@@ -256,7 +259,11 @@ async function main(argv) {
                     console.log(`${t.tokenHash.slice(0, 12)}  ${t.label.padEnd(24)} created ${t.createdAt}${t.revokedAt ? `  REVOKED ${t.revokedAt}` : ""}`);
             }
             else if (what === "token" && verb === "revoke" && args[0] && args[1]) {
-                console.log(`revoked ${await tenancy.revokeToken(args[0], args[1])} token(s)`);
+                console.log(`revoked ${await tenancy.revokeToken(args[0], args[1], actor)} token(s)`);
+            }
+            else if (what === "audit") {
+                for (const e of await tenancy.audit({ ...(values.tenant !== "default" ? { tenant: values.tenant } : {}), limit: 100 }))
+                    console.log(`${e.at}  ${e.actor.padEnd(40)} ${e.action.padEnd(14)} ${(e.tenantId ?? "").padEnd(20)} ${Object.entries(e.detail).map(([k, v]) => `${k}=${v}`).join(" ")}`);
             }
             else if (what === "import") {
                 if (!values.file)

package/dist/index.d.ts

@@ -7,6 +7,7 @@ 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 type { AuditEntry } from "./log-store.ts";
 export { connectSigner, fetchLogKeys, localSigner, serveSigner, signerHandler } from "./signer.ts";
 export type { KeyDocument, RemoteSignerOptions, RetiredKey, RunningSigner, Signer, SignerServerOptions } from "./signer.ts";
 export { bothCheckpoints, dirCheckpoints, postgresCheckpoints } from "./checkpoints.ts";

package/dist/log-admin.js

@@ -64,11 +64,11 @@ export function adminRoutes(opts) {
     const presented = (req) => {
         const h = req.headers.authorization ?? "";
         if (h.startsWith("Bearer ") && h.length > 7)
-            return h.slice(7);
+            return { token: h.slice(7), user: null };
         if (h.startsWith("Basic ") && h.length > 6) {
             const pair = Buffer.from(h.slice(6), "base64").toString();
             const at = pair.indexOf(":");
-            return at >= 0 ? pair.slice(at + 1) : pair;
+            return at >= 0 ? { token: pair.slice(at + 1), user: pair.slice(0, at) } : { token: pair, user: null };
         }
         return null;
     };
@@ -81,7 +81,7 @@ export function adminRoutes(opts) {
         };
         const addr = clientAddress(req, opts.trustProxy);
         const given = presented(req);
-        if (given === null || !same(given, opts.token)) {
+        if (given === null || !same(given.token, opts.token)) {
             if (!failures.take(`admin:${addr}`))
                 return json(429, { error: "too many attempts; wait a minute" }, { "retry-after": "60" }), true;
             // The challenge makes the browser ask; the same 401 tells an API client what is missing.
@@ -101,6 +101,10 @@ export function adminRoutes(opts) {
             }
             return text ? JSON.parse(text) : {};
         };
+        // Who did it, for the audit trail: the user name the browser prompt asked for (any name, but it is recorded), or
+        // "bearer" for an API client, and the address either came from. There is one admin token; the name is what
+        // tells two operators apart.
+        const actor = `admin:${given.user?.replace(/[^\w.@-]/g, "").slice(0, 64) || "bearer"}@${addr}`;
         try {
             const t = opts.tenancy;
             const parts = url.pathname.split("/").filter(Boolean); // ["admin", ...]
@@ -114,6 +118,13 @@ export function adminRoutes(opts) {
                 res.writeHead(200, { "content-type": "text/csv; charset=utf-8", "content-disposition": `attachment; filename="agent-custody-usage-${u.month}.csv"`, "cache-control": "no-store" });
                 res.end(csv);
             }
+            else if (req.method === "GET" && parts.length === 2 && parts[1] === "audit") {
+                const tenant = url.searchParams.get("tenant");
+                const limit = url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : 200;
+                if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+                    return json(400, { error: "limit must be an integer in 1..1000" }), true;
+                json(200, { entries: await t.audit({ ...(tenant ? { tenant } : {}), limit }) });
+            }
             else if (req.method === "GET" && parts.length === 2 && parts[1] === "info") {
                 json(200, { publicUrl: opts.publicUrl ?? null, checkpointsUrl: opts.checkpointsUrl ?? null, keyid: opts.keyid ?? null });
             }
@@ -125,10 +136,10 @@ export function adminRoutes(opts) {
                 const b = await body();
                 if (typeof b.id !== "string" || !/^[A-Za-z0-9_.-]+$/.test(b.id))
                     return json(400, { error: "id must be a plain identifier" }), true;
-                json(200, await t.addTenant(b.id, typeof b.logId === "string" && b.logId ? b.logId : b.id));
+                json(200, await t.addTenant(b.id, typeof b.logId === "string" && b.logId ? b.logId : b.id, actor));
             }
             else if (req.method === "POST" && parts.length === 4 && parts[1] === "tenants" && parts[3] === "disable") {
-                await t.disableTenant(parts[2]);
+                await t.disableTenant(parts[2], actor);
                 json(200, { disabled: parts[2] });
             }
             else if (req.method === "GET" && parts.length === 4 && parts[1] === "tenants" && parts[3] === "tokens") {
@@ -140,12 +151,12 @@ export function adminRoutes(opts) {
                 const tenant = await t.tenant(parts[2]);
                 if (!tenant)
                     return json(404, { error: "unknown tenant" }), true;
-                const minted = await t.addToken(tenant.id, label);
+                const minted = await t.addToken(tenant.id, label, actor);
                 const welcome = opts.publicUrl ? welcomeSheet({ tenant: tenant.id, logId: tenant.logId, publicUrl: opts.publicUrl, ...(opts.checkpointsUrl ? { checkpointsUrl: opts.checkpointsUrl } : {}), ...(opts.keyid ? { keyid: opts.keyid } : {}) }) : null;
                 json(200, { ...minted, welcome });
             }
             else if (req.method === "POST" && parts.length === 6 && parts[1] === "tenants" && parts[3] === "tokens" && parts[5] === "revoke") {
-                json(200, { revoked: await t.revokeToken(parts[2], parts[4]) });
+                json(200, { revoked: await t.revokeToken(parts[2], parts[4], actor) });
             }
             else {
                 json(404, { error: "not found" });
@@ -214,6 +225,9 @@ const ADMIN_PAGE = `<!doctype html>
     <h2>Tokens of a tenant</h2>
     <div class="row"><label>tenant<input id="ltid" placeholder="acme" autocomplete="off"></label><button class="quiet" id="listTokens">List</button></div>
     <table><thead><tr><th>label</th><th>hash</th><th>created</th><th>state</th><th></th></tr></thead><tbody id="tokens"></tbody></table>
+    <h2>Activity</h2>
+    <p class="muted">Every tenant and token change on this log, newest first, with who made it: the name entered at the sign-in prompt, or the command line on the server. Tenants see their own rows in their export.</p>
+    <table><thead><tr><th>when</th><th>who</th><th>action</th><th>tenant</th><th>detail</th></tr></thead><tbody id="audit"></tbody></table>
     <p class="muted" id="msg"></p>
   </section>
 </main>
@@ -244,15 +258,17 @@ const ADMIN_PAGE = `<!doctype html>
       $("where").textContent = (info.publicUrl || location.origin) + " · keyid " + (info.keyid ? info.keyid.slice(0, 12) : "?") + (info.checkpointsUrl ? " · checkpoints at " + info.checkpointsUrl : "");
       await loadTenants();
       await loadUsage();
+      await loadAudit();
     } catch (e) { say(e.message, "err"); }
   };
-  $("addTenant").onclick = async () => { try { const t = await api("POST", "/admin/tenants", { id: $("tid").value.trim(), logId: $("lid").value.trim() }); say("tenant " + t.id + " created; reached at /t/" + t.id + "/", "ok"); $("ttid").value = t.id; await loadTenants(); } catch (e) { say(e.message, "err"); } };
+  $("addTenant").onclick = async () => { try { const t = await api("POST", "/admin/tenants", { id: $("tid").value.trim(), logId: $("lid").value.trim() }); say("tenant " + t.id + " created; reached at /t/" + t.id + "/", "ok"); $("ttid").value = t.id; await loadTenants(); await loadAudit(); } catch (e) { say(e.message, "err"); } };
   $("mint").onclick = async () => {
     try {
       const r = await api("POST", "/admin/tenants/" + encodeURIComponent($("ttid").value.trim()) + "/tokens", { label: $("label").value.trim() });
       $("tokval").textContent = r.token; $("sheet").textContent = r.welcome || "(set --public-url on the server for the welcome sheet)"; $("minted").hidden = false;
       say("token minted for " + $("ttid").value.trim() + "; stored as hash " + r.tokenHash.slice(0, 12), "ok");
       await loadTenants();
+      await loadAudit();
     } catch (e) { say(e.message, "err"); }
   };
   $("copyTok").onclick = () => navigator.clipboard.writeText($("tokval").textContent).then(() => say("token copied", "ok"));
@@ -264,12 +280,16 @@ const ADMIN_PAGE = `<!doctype html>
     $("csv").href = "/admin/usage.csv?month=" + encodeURIComponent(month);
     $("usage").innerHTML = u.tenants.map((t) => "<tr><td><code>" + esc(t.id) + "</code>" + (t.disabled ? " <span class=muted>disabled</span>" : "") + "</td><td><code>" + esc(t.logId) + "</code></td><td>" + t.appends + "</td><td>" + t.totalLeaves + "</td><td>" + t.liveTokens + "</td></tr>").join("") || "<tr><td colspan=5 class=muted>no tenants</td></tr>";
   };
+  const loadAudit = async () => {
+    const a = await api("GET", "/admin/audit?limit=100");
+    $("audit").innerHTML = a.entries.map((e) => "<tr><td>" + esc(e.at.replace("T", " ").slice(0, 19)) + "</td><td><code>" + esc(e.actor) + "</code></td><td>" + esc(e.action) + "</td><td><code>" + esc(e.tenantId || "") + "</code></td><td class=muted>" + esc(Object.entries(e.detail).map(([k, v]) => k + "=" + v).join(" ")) + "</td></tr>").join("") || "<tr><td colspan=5 class=muted>nothing yet</td></tr>";
+  };
   $("loadUsage").onclick = () => loadUsage().catch((e) => say(e.message, "err"));
   $("month").value = new Date().toISOString().slice(0, 7);
   document.addEventListener("click", async (e) => {
     const b = e.target.closest("button"); if (!b) return;
-    if (b.dataset.disable && confirm("Disable tenant " + b.dataset.disable + "? Its paths answer 404 within ten seconds.")) { try { await api("POST", "/admin/tenants/" + encodeURIComponent(b.dataset.disable) + "/disable"); await loadTenants(); say("disabled " + b.dataset.disable, "ok"); } catch (err) { say(err.message, "err"); } }
-    if (b.dataset.revoke) { const [id, prefix] = b.dataset.revoke.split("|"); if (confirm("Revoke token " + prefix + " of " + id + "?")) { try { await api("POST", "/admin/tenants/" + encodeURIComponent(id) + "/tokens/" + prefix + "/revoke"); await loadTokens(id); await loadTenants(); say("revoked", "ok"); } catch (err) { say(err.message, "err"); } } }
+    if (b.dataset.disable && confirm("Disable tenant " + b.dataset.disable + "? Its paths answer 404 within ten seconds.")) { try { await api("POST", "/admin/tenants/" + encodeURIComponent(b.dataset.disable) + "/disable"); await loadTenants(); await loadAudit(); say("disabled " + b.dataset.disable, "ok"); } catch (err) { say(err.message, "err"); } }
+    if (b.dataset.revoke) { const [id, prefix] = b.dataset.revoke.split("|"); if (confirm("Revoke token " + prefix + " of " + id + "?")) { try { await api("POST", "/admin/tenants/" + encodeURIComponent(id) + "/tokens/" + prefix + "/revoke"); await loadTokens(id); await loadTenants(); await loadAudit(); say("revoked", "ok"); } catch (err) { say(err.message, "err"); } } }
   });
   enter();
 })();

package/dist/log-export.d.ts

@@ -15,6 +15,8 @@ export interface ExportResult {
     rootHash: string;
     keyid: string;
     checkpoints: number;
+    /** administrative actions on this tenant: tokens minted and revoked, the tenant created or disabled, by whom */
+    audit: number;
     usage: {
         month: string;
         appends: number;

package/dist/log-export.js

@@ -61,20 +61,28 @@ export async function exportLog(o) {
             problems.push(`usage for ${month}: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
+    let audit = [];
+    try {
+        audit = (await get(new URL("?limit=1000", path("audit")), true)).entries;
+    }
+    catch (e) {
+        problems.push(`audit trail: ${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, "audit.json"), JSON.stringify(audit, null, 2));
+    const result = { outDir: o.outDir, logId: head.log ?? null, treeSize: head.treeSize, rootHash: head.rootHash, keyid: v.keyid, checkpoints: cps.checkpoints.length, audit: audit.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)`,
+        `head root ${r.rootHash.slice(0, 16)}, signed by ${r.keyid.slice(0, 12)}, ${r.checkpoints} checkpoint(s), ${r.audit} administrative action(s) on this tenant`,
         ...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 ...",

package/dist/log-sink.d.ts

@@ -1,7 +1,7 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import { type Envelope, type KeyPair } from "./crypto.ts";
 import { type InclusionProof } from "./log.ts";
-import { type LogBackend, type PostgresTenancy, type RateLimitOptions } from "./log-store.ts";
+import { type AuditEntry, type LogBackend, type PostgresTenancy, type RateLimitOptions } from "./log-store.ts";
 import { type Signer } from "./signer.ts";
 import type { Checkpoint, CheckpointStore } from "./checkpoints.ts";
 import { type AdminOptions } from "./log-admin.ts";
@@ -90,6 +90,8 @@ export interface ResolvedLog {
     authorize(token: string | null): Promise<boolean>;
     /** this log's own metering for a month, where the store keeps it */
     usage?(month: string): Promise<TenantUsage>;
+    /** administrative actions on this log, newest first, where the store keeps them */
+    audit?(limit: number): Promise<AuditEntry[]>;
 }
 /** Turns the tenant in a path, or null for the root paths, into a log. */
 export interface LogResolver {

package/dist/log-sink.js

@@ -154,6 +154,7 @@ export function postgresResolver(tenancy, opts = {}) {
                     const row = u.tenants.find((t) => t.id === id);
                     return { month, appends: row?.appends ?? 0, totalLeaves: row?.totalLeaves ?? 0, liveTokens: row?.liveTokens ?? 0 };
                 },
+                audit: (limit) => tenancy.audit({ tenant: id, limit }),
             };
         },
         async tenants() {
@@ -266,7 +267,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|leaves|usage)$/.exec(url.pathname);
+        const m = /^\/t\/([A-Za-z0-9_.-]+)\/(append|root|consistency|head|checkpoints|leaves|usage|audit)$/.exec(url.pathname);
         let which;
         try {
             which = await resolver.resolve(m ? m[1] : null);
@@ -310,9 +311,17 @@ export function logHandler(source, keyOrSigner, opts = {}) {
             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 (req.method === "GET" && (url.pathname.endsWith("/leaves") || url.pathname.endsWith("/usage") || url.pathname.endsWith("/audit"))) {
                 if (!(await which.authorize(bearer(req))))
                     return json(401, { error: "unauthorized" });
+                if (url.pathname.endsWith("/audit")) {
+                    if (!which.audit)
+                        return json(404, { error: "this log keeps no audit trail" });
+                    const limit = url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : 200;
+                    if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+                        return json(400, { error: "limit must be an integer in 1..1000" });
+                    return json(200, { entries: await which.audit(limit) }, { "cache-control": "no-store" });
+                }
                 if (url.pathname.endsWith("/usage")) {
                     if (!which.usage)
                         return json(404, { error: "this log keeps no usage" });

package/dist/log-store.d.ts

@@ -71,6 +71,15 @@ export interface TokenRecord {
     createdAt: string;
     revokedAt: string | null;
 }
+/** One administrative action: who did what to which tenant, when. Written by every mutation and never deleted. */
+export interface AuditEntry {
+    id: number;
+    at: string;
+    actor: string;
+    action: "tenant.add" | "tenant.disable" | "token.add" | "token.revoke";
+    tenantId: string | null;
+    detail: Record<string, unknown>;
+}
 /** Tenants and their tokens, in Postgres. Tokens are stored hashed; a lookup hashes what the caller presented. */
 export declare class PostgresTenancy {
     private readonly client;
@@ -81,6 +90,12 @@ export declare class PostgresTenancy {
     private ready;
     constructor(client: PostgresLike, opts?: PostgresLogOptions);
     private init;
+    private record;
+    /** Administrative actions, newest first; for one tenant when given. What the admin page shows and a tenant's export carries. */
+    audit(opts?: {
+        tenant?: string;
+        limit?: number;
+    }): Promise<AuditEntry[]>;
     private row;
     /** The tenant, or null. Answers from a ten-second cache, so a disabled tenant is refused within that. */
     tenant(id: string): Promise<Tenant | null>;
@@ -88,16 +103,17 @@ export declare class PostgresTenancy {
     authorize(tenantId: string, token: string | null): Promise<boolean>;
     /** The tenant's log, one instance per tenant per process. */
     log(tenantId: string): Promise<PostgresLog>;
-    addTenant(id: string, logId?: string): Promise<Tenant>;
-    disableTenant(id: string): Promise<void>;
+    /** Creates a tenant, or renames its log id. `by` names who did it in the audit trail. */
+    addTenant(id: string, logId?: string, by?: string): Promise<Tenant>;
+    disableTenant(id: string, by?: string): Promise<void>;
     listTenants(): Promise<Tenant[]>;
     /** Mints a token for a tenant. The token is returned once and stored only as its hash. */
-    addToken(tenantId: string, label: string): Promise<{
+    addToken(tenantId: string, label: string, by?: string): Promise<{
         token: string;
         tokenHash: string;
     }>;
     /** Revokes the tokens of a tenant whose hash starts with the prefix; returns how many. */
-    revokeToken(tenantId: string, hashPrefix: string): Promise<number>;
+    revokeToken(tenantId: string, hashPrefix: string, by?: string): Promise<number>;
     /**
      * Appends per tenant for one month, YYYY-MM in UTC, plus each tenant's total leaves and live tokens: the numbers
      * any pricing rests on. One query on the leaves table, grouped; tenants with no appends that month show zero.

package/dist/log-store.js

@@ -190,10 +190,23 @@ export class PostgresTenancy {
                 await PostgresLog.ensureSchema(this.client, p);
                 await this.client.query(`CREATE TABLE IF NOT EXISTS ${p}tenants (id TEXT PRIMARY KEY, log_id TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), disabled_at TIMESTAMPTZ)`);
                 await this.client.query(`CREATE TABLE IF NOT EXISTS ${p}tokens (token_hash TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES ${p}tenants(id), label TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), revoked_at TIMESTAMPTZ)`);
+                await this.client.query(`CREATE TABLE IF NOT EXISTS ${p}audit (id BIGSERIAL PRIMARY KEY, at TIMESTAMPTZ NOT NULL DEFAULT now(), actor TEXT NOT NULL, action TEXT NOT NULL, tenant_id TEXT, detail JSONB NOT NULL DEFAULT '{}')`);
             })();
         }
         return this.ready;
     }
+    async record(actor, action, tenantId, detail) {
+        await this.client.query(`INSERT INTO ${this.prefix}audit (actor, action, tenant_id, detail) VALUES ($1, $2, $3, $4)`, [actor ?? "unattributed", action, tenantId, JSON.stringify(detail)]);
+    }
+    /** Administrative actions, newest first; for one tenant when given. What the admin page shows and a tenant's export carries. */
+    async audit(opts = {}) {
+        await this.init();
+        const limit = Math.min(Math.max(1, opts.limit ?? 200), 1000);
+        const rows = (opts.tenant
+            ? await this.client.query(`SELECT id, at, actor, action, tenant_id, detail FROM ${this.prefix}audit WHERE tenant_id = $1 ORDER BY id DESC LIMIT ${limit}`, [opts.tenant])
+            : await this.client.query(`SELECT id, at, actor, action, tenant_id, detail FROM ${this.prefix}audit ORDER BY id DESC LIMIT ${limit}`)).rows;
+        return rows.map((r) => ({ id: Number(r.id), at: new Date(r.at).toISOString(), actor: String(r.actor), action: r.action, tenantId: r.tenant_id === null || r.tenant_id === undefined ? null : String(r.tenant_id), detail: (typeof r.detail === "string" ? JSON.parse(r.detail) : r.detail) }));
+    }
     row(r) {
         return { id: String(r.id), logId: String(r.log_id), createdAt: new Date(r.created_at).toISOString(), disabledAt: r.disabled_at ? new Date(r.disabled_at).toISOString() : null };
     }
@@ -233,42 +246,48 @@ export class PostgresTenancy {
         }
         return l;
     }
-    async addTenant(id, logId = id) {
+    /** Creates a tenant, or renames its log id. `by` names who did it in the audit trail. */
+    async addTenant(id, logId = id, by) {
         if (!/^[A-Za-z0-9_.-]+$/.test(id))
             throw new Error(`tenant id must be a plain identifier; got "${id}"`);
         await this.init();
         const rows = (await this.client.query(`INSERT INTO ${this.prefix}tenants (id, log_id) VALUES ($1, $2) ON CONFLICT (id) DO UPDATE SET log_id = EXCLUDED.log_id RETURNING id, log_id, created_at, disabled_at`, [id, logId])).rows;
         this.tenantCache.delete(id);
+        await this.record(by, "tenant.add", id, { logId });
         return this.row(rows[0]);
     }
-    async disableTenant(id) {
+    async disableTenant(id, by) {
         await this.init();
         await this.client.query(`UPDATE ${this.prefix}tenants SET disabled_at = now() WHERE id = $1 AND disabled_at IS NULL`, [id]);
         this.tenantCache.delete(id);
+        await this.record(by, "tenant.disable", id, {});
     }
     async listTenants() {
         await this.init();
         return (await this.client.query(`SELECT id, log_id, created_at, disabled_at FROM ${this.prefix}tenants ORDER BY created_at`)).rows.map((r) => this.row(r));
     }
     /** Mints a token for a tenant. The token is returned once and stored only as its hash. */
-    async addToken(tenantId, label) {
+    async addToken(tenantId, label, by) {
         await this.init();
         if (!(await this.tenant(tenantId)))
             throw new Error(`unknown tenant ${tenantId}`);
         const token = randomBytes(32).toString("hex");
         const tokenHash = sha256hex(token);
         await this.client.query(`INSERT INTO ${this.prefix}tokens (token_hash, tenant_id, label) VALUES ($1, $2, $3)`, [tokenHash, tenantId, label]);
+        await this.record(by, "token.add", tenantId, { label, tokenHash: tokenHash.slice(0, 12) });
         return { token, tokenHash };
     }
     /** Revokes the tokens of a tenant whose hash starts with the prefix; returns how many. */
-    async revokeToken(tenantId, hashPrefix) {
+    async revokeToken(tenantId, hashPrefix, by) {
         await this.init();
         if (hashPrefix.length < 8)
             throw new Error("give at least eight characters of the token hash");
         const rows = (await this.client.query(`UPDATE ${this.prefix}tokens SET revoked_at = now() WHERE tenant_id = $1 AND token_hash LIKE $2 AND revoked_at IS NULL RETURNING token_hash`, [tenantId, `${hashPrefix}%`])).rows;
         for (const r of rows)
             this.tokenCache.delete(`${tenantId}:${r.token_hash}`);
-        return rows.length;
+        const revoked = rows.length;
+        await this.record(by, "token.revoke", tenantId, { hashPrefix: hashPrefix.slice(0, 12), revoked });
+        return revoked;
     }
     /**
      * Appends per tenant for one month, YYYY-MM in UTC, plus each tenant's total leaves and live tokens: the numbers

package/docs/threat-model.md

@@ -0,0 +1,114 @@
+# Threat model
+
+What agent-custody is built to withstand, what it is not, and who has to be trusted in each setup. Written for the security reviewer who has to decide whether the evidence this produces would hold in a dispute, and for us, since every design decision in the packages traces to a row here. Read [verification.md](verification.md) for what each check proves and [compliance.md](compliance.md) for which control each artefact satisfies; this page is about attackers.
+
+## The claim being defended
+
+A receipt is a signed statement that a named agent, acting for a named principal under a specific grant and policy, asked for a specific tool call at a specific time, and that the call was allowed, denied, withheld, executed, or failed, with the arguments and the result digested. The remote log commits to the receipt's existence before or shortly after the action, in a tree whose heads are signed by a key the agent's operator does not hold. The claim under attack is therefore: **this receipt describes what actually happened, and it was not written, altered, or dropped after the fact.**
+
+Everything below asks who could make that claim false, and what stops them.
+
+## Parties
+
+| party | holds | wants, if hostile |
+| --- | --- | --- |
+| **the agent** (the model and its process) | its own arguments, whatever credentials are in its environment | to act outside its grant, to hide an action, to make a denied action look allowed |
+| **the operator** (the team running the agent and the gateway) | the gateway key, the receipts directory, the local log, the policy | to rewrite history after an incident, to produce receipts for actions that did not happen, to drop receipts for ones that did |
+| **the principal** (whoever the agent acts for) | their signing key | to disown a grant they signed, or to claim a grant they never gave |
+| **the upstream** (the tool, API, or MCP server) | its own key if it signs results, its own records | to deny it served a result, or to claim it served a different one |
+| **the log operator** (us, for the hosted log) | the log's signing key, every tenant's leaf hashes, token hashes | to rewrite a tenant's tree, to show different histories to different verifiers, to read receipt contents |
+| **the witness** (a second operator) | its own key | to countersign a rewritten history, or to refuse a true one |
+| **a network attacker** | the wire between any two of the above | to replay, drop, or alter appends and results |
+| **a verifier** (auditor, counsel, regulator) | public keys and receipts they were handed | to be misled by any of the above |
+
+## What the design assumes
+
+- Ed25519 signatures and SHA-256 are sound. Post-quantum signatures are [issue #11](https://github.com/ch4r10t33r/agent-custody/issues/11), not present.
+- Private keys stay private to their holder. Key custody is the holder's problem; the packages read keys from files or a signer process and never transmit them.
+- The gateway runs where the agent cannot read its key or its receipts directory. A gateway in the agent's own container, with the key readable by the agent, is an SDK with extra steps and the receipts it produces are worth exactly that.
+- Clocks are roughly right. Timestamps in receipts are the producer's; the log's checkpoint times and the witness's countersignature times are the only times a verifier can hold anyone to.
+- A verifier obtains public keys from somewhere the attacker does not control: the log's key document over TLS, or a key file handed over out of band.
+
+## Attacks and what stops them
+
+Each row names the attacker, the move, the defence, and whether the defence is a property of the evidence (holds against anyone later) or a property of the deployment (holds only if the deployment is as described).
+
+### By the agent
+
+| attack | defence | kind |
+| --- | --- | --- |
+| Call a tool the grant does not allow | The gateway evaluates the policy against the grant the principal signed; the agent never sees the policy or the key. A denied call never reaches the upstream and still produces a receipt. | deployment: only calls through the gateway are covered |
+| Feed the policy lies in the arguments | `context.args` is `claimed`; policies that matter read `context.facts`, which the gateway fetched itself and marks `observed`. A policy that decides on args alone is the operator's choice and the receipt shows it. | evidence: provenance is in the receipt |
+| Bypass the gateway with a credential in its own environment | Nothing in the packages prevents this. The gateway covers the tools behind it and no others. | not covered; the deployment must keep credentials out of the agent |
+| Skip an in-process hook or SDK wrapper | Same: an SDK receipt is the agent's own report, and every field in it is `claimed`. | not covered; use the gateway for anything consequential |
+| Write memory the fleet will trust | Writes not made through the gateway are `claimed` and quarantined until a gateway confirms them; reads leave them out unless asked for. | deployment |
+| Exhaust the log so its own calls are withheld rather than recorded | A withheld call shows `allow` next to `withheld` and nothing happened upstream; there is no state in which an action occurs without a receipt when `precommit` names the tool. | evidence |
+
+### By the operator
+
+| attack | defence | kind |
+| --- | --- | --- |
+| Rewrite a receipt after the fact | The receipt's envelope is signed by the gateway key, which the operator holds, so the signature alone does not stop this. What stops it is the log: the leaf hash of the original envelope is in a tree whose head the log signed, and a rewritten receipt has a different hash with no inclusion proof. | evidence, with a remote log; deployment, with a local log the operator can rewrite |
+| Drop a receipt | The log's tree only grows, and consistency proofs between any two heads show nothing was removed. A receipt the operator never logged never existed as evidence, which is the point of `precommit` for consequential calls: the authorization leaf goes in before the action. | evidence for logged receipts; withheld calls for pre-committed tools |
+| Forge a receipt for an action that never happened | Nothing in the log stops the operator logging a fabricated receipt; the log commits to existence, not truth. What limits it: the upstream's signature over the result when the upstream signs, provider attestations where the provider delivers them, and the principal's signature on the grant. A forged receipt for a signing upstream fails its `upstream` checks. | evidence, where the upstream signs; otherwise the operator's word |
+| Replace the policy and claim a different one decided | The receipt carries the sha256 of the policy text; a verifier with the policy file can check it, and a policy change is a different digest in every later receipt. | evidence |
+| Produce a second, cleaner history | With a remote log, both histories would need heads signed by the log's key at the same size with different roots; the checkpoints host and the witness make that detectable. With a local log, a copy taken earlier by someone else is the only defence. | evidence with a witnessed remote log |
+| Erase what an agent believed | `forget` erases the value and leaves a digest keyed by a forget key held outside the ledger, so the erasure is provable without the value. A forget with `none` leaves nothing and the custody pack says so. | evidence |
+
+### By the principal
+
+| attack | defence | kind |
+| --- | --- | --- |
+| Disown a grant | The grant is signed with the principal's key and embedded in every receipt issued under it; the verifier checks the signature against the principal's public key. | evidence |
+| Claim a grant they never gave | Nobody else holds their key. A leaked principal key is the principal's problem and the reason grants carry expiry. | assumption |
+
+### By the upstream
+
+| attack | defence | kind |
+| --- | --- | --- |
+| Deny it served a result | When the upstream signs `{ receiptId, tool, contentDigest }` the receipt carries its signature. When it does not sign, the receipt carries the gateway's digest of what the gateway saw, which is the operator's word against the upstream's. | evidence, where the upstream signs |
+| Serve a different result to the gateway than it records | Same signature. Providers that deliver attestations (Stripe, GitHub webhooks) are checked against the provider's secret. | evidence, where available |
+
+### By the log operator
+
+| attack | defence | kind |
+| --- | --- | --- |
+| Read receipt contents | With `hashOnly`, the log never receives them; only leaf hashes cross the wire. This is the default in the welcome sheet and the runbook, and it is the tenant's setting, not ours. | deployment on the tenant's side |
+| Rewrite a tenant's tree | Every head is signed and published as a checkpoint on a second host; a rewrite means two signed heads at one size with different roots, or a later head that does not extend an earlier one. Anyone holding an earlier head detects it with `audit`; the monitor does it every ten minutes; the witness countersigns only heads that extend the last it signed. | evidence, given a witness or an earlier head held elsewhere |
+| Show different histories to different verifiers | Same: checkpoints are public and the witness sees one history. Without a witness, two verifiers who compare heads detect it, and nobody else does. | evidence with a witness; otherwise detection needs comparison |
+| Mint a token for a tenant and append noise | Appends are hashes with no content; the tenant's export and usage show leaves and live tokens they did not make, and the audit trail, which the tenant's export carries, records who minted what and from where. | deployment |
+| Sign with a key not in the key document | Verifiers pin by keyid from the published document; a head signed by an unpublished key fails. Retired keys stay published so old heads keep verifying, and a rotation is announced with its date. | evidence |
+| Disappear | The tenant's export carries every leaf hash, the signed head, the keys, and the checkpoints; `verify --log` and `audit --log` work against it with no server. | evidence |
+
+### By the witness
+
+| attack | defence | kind |
+| --- | --- | --- |
+| Countersign a rewritten history | It cannot without also holding the log's key; a countersignature is over the log's own signed head. A witness that countersigns two heads at one size has published its own dishonesty. | evidence |
+| Refuse a true history | An alarm with no consistency failure behind it is a false alarm; the log's consistency proof settles it in public. Verifiers who require a witness signature see a gap, which is the correct outcome for a disputed period. | evidence |
+| Collude with the log operator | Two independent operators are the assumption. A witness on the log operator's machine proves nothing, and the deployment guide says so. | assumption |
+
+### On the network
+
+| attack | defence | kind |
+| --- | --- | --- |
+| Replay an append | Appends are idempotent in effect: the same leaf hash appended twice is two leaves, both true. Nothing an attacker replays creates a receipt the gateway did not sign. | evidence |
+| Alter an append in flight | TLS between gateway and log; the leaf hash is over a signed envelope, so an altered hash simply fails inclusion for the real receipt. | evidence |
+| Drop the log's answer | The gateway retries, then errors or withholds; no receipt is handed out without an inclusion proof. Timeouts bound the wait. | evidence |
+| Steal a tenant token | Tokens are bearer secrets; a stolen one appends noise to that tenant's log until revoked. Rate limits bound the damage per second; the tenant's usage shows it. | deployment |
+
+## What is not defended
+
+Stated plainly, because a security review that finds these itself will not believe the rest.
+
+- **Actions outside the gateway.** A credential the agent holds directly is used directly. The gateway is a choke point only for what goes through it.
+- **Truth of SDK receipts.** An in-process receipt is the process's own report. It is history, not evidence against that process.
+- **Truth of what the upstream did** when the upstream does not sign. The receipt proves what the gateway sent and what it got back, on the gateway's word.
+- **The operator's key custody.** A stolen gateway key signs receipts the verifier cannot tell from real ones; the log still bounds when they were created.
+- **Availability.** A log that is down withholds pre-committed calls. That is the designed behaviour and it is a denial of service on the agent. Run the log with the runbook's monitoring, and expect a tenant to ask for the SLA.
+- **Post-quantum adversaries.** Issue #11.
+- **A dishonest log operator with a dishonest witness.** Two colluding parties can present a consistent false history. The defence is choosing them independently.
+
+## How the hosted log is run against this model
+
+The deployment in [deploy/](../../deploy/README.md) and its [runbook](../../deploy/RUNBOOK.md): the signer alone holds the key and is reachable only inside the compose network; the log process facing the internet holds no key; tenant tokens are hashed at rest and shown once; every admin action requires the admin token and is throttled; checkpoints are published on a second host; the monitor runs from machines that are not ours every ten minutes; backups are nightly, with an off-machine mirror the runbook installs once a destination is configured; the key rotates yearly and on suspicion, with retired keys published; the witness runs on another operator's machine, or the site says it does not yet.

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`. 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.
+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. Every change made there or with `log-admin` is recorded: who (the name entered at the browser prompt and the address, `bearer` for an API client, or the user and host for the command line), what (`tenant.add`, `tenant.disable`, `token.add`, `token.revoke`), which tenant, and the detail, never the token itself; the page shows it under Activity, `GET /admin/audit?tenant=&limit=` and `log-admin audit` list it, and a tenant reads their own rows at `GET /t/<name>/audit` with their token. Nothing else 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, their own usage (`GET /t/<name>/usage?month=`), and the administrative actions on their tenant (`GET /t/<name>/audit`, into `audit.json`), 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.7",
+  "version": "0.5.8",
   "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": {