@agent-custody/receipts 0.5.0 → 0.5.1

package/README.md

@@ -289,7 +289,7 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 
 **Next, in the order it pays off**
 
-1. The hosted log, [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6): phases 1 to 3 are done; what remains is running it for the first tenant, and then a witness that countersigns checkpoints.
+1. The hosted log, [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6): running at log.agent-custody.dev with keys published and checkpoints on a second host, taking its first tenants. What remains is the witness that countersigns checkpoints.
 2. Post-quantum signatures: ML-DSA beside Ed25519 in the same DSSE envelope, hybrid by default when a PQ key is present, in every signed artefact and in the browser verifier. [Issue #11](https://github.com/ch4r10t33r/agent-custody/issues/11).
 3. An HTTP transport for the gateway, with the grant presented per connection, for a shared deployment rather than one process per agent session.
 4. Delegation chains for sub-agents.

package/dist/checkpoints.d.ts

@@ -18,5 +18,9 @@ export interface CheckpointStore {
 export declare function dirCheckpoints(dir: string): CheckpointStore;
 /** Rows in <prefix>heads, one per tenant and tree size. */
 export declare function postgresCheckpoints(client: PostgresLike, prefix?: string): CheckpointStore;
-/** Writes every checkpoint to each store: the directory the checkpoints host serves and the database the API lists from. */
+/**
+ * Writes every checkpoint to each store: the directory the checkpoints host serves and the database the API lists
+ * from. `latest` is the store that is furthest behind, so a store that missed a write (a directory that was not yet
+ * writable, say) is caught up on the next publication; saves are idempotent in every store.
+ */
 export declare function bothCheckpoints(...stores: CheckpointStore[]): CheckpointStore;

package/dist/checkpoints.js

@@ -68,7 +68,11 @@ export function postgresCheckpoints(client, prefix = "log_") {
         },
     };
 }
-/** Writes every checkpoint to each store: the directory the checkpoints host serves and the database the API lists from. */
+/**
+ * Writes every checkpoint to each store: the directory the checkpoints host serves and the database the API lists
+ * from. `latest` is the store that is furthest behind, so a store that missed a write (a directory that was not yet
+ * writable, say) is caught up on the next publication; saves are idempotent in every store.
+ */
 export function bothCheckpoints(...stores) {
     return {
         async save(c) {
@@ -76,6 +80,16 @@ export function bothCheckpoints(...stores) {
                 await s.save(c);
         },
         list: (t, since) => stores[0].list(t, since),
-        latest: (t) => stores[0].latest(t),
+        async latest(t) {
+            let behind;
+            for (const s of stores) {
+                const l = await s.latest(t);
+                if (l === null)
+                    return null;
+                if (behind === undefined || l.treeSize < behind.treeSize)
+                    behind = l;
+            }
+            return behind ?? null;
+        },
     };
 }

package/dist/cli.js

@@ -42,6 +42,9 @@ const USAGE = `agent-custody <command>
                                                  sign with a key in this process, or through a signer process that holds it; publish a signed
                                                  checkpoint per log that has grown, every 300 s by default, to the directory (and, with a
                                                  database, to its heads table); serve the key document at /.well-known/agent-custody-log.json
+  log     ... --db-env NAME --admin-token-env NAME [--public-url <https://log.example.com/>] [--checkpoints-url <https://checkpoints.example.com/>]
+                                                 the operator's admin page at /admin and its API, behind the admin token: tenants, tokens shown once,
+                                                 the welcome sheet; the public URLs fill the sheet in
   signer  --key <log.key> --port 8790 [--host 127.0.0.1] [--token-env NAME] [--retired-key <pub>]...
                                                  the one process that holds the log's key: POST /sign, GET /keys
   log-admin --db-env NAME tenant add <id> [--log-id <id>] | tenant list | tenant disable <id>
@@ -226,7 +229,7 @@ async function main(argv) {
         case "log": {
             const { values } = parseArgs({
                 args: rest,
-                options: { file: { type: "string" }, key: { type: "string" }, port: { type: "string", default: "8787" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" }, "log-id": { type: "string" }, tenants: { type: "string" }, "db-env": { type: "string" }, "signer-url": { type: "string" }, "signer-token-env": { type: "string" }, "retired-key": { type: "string", multiple: true }, "checkpoint-dir": { type: "string" }, "checkpoint-every": { type: "string", default: "300" } },
+                options: { file: { type: "string" }, key: { type: "string" }, port: { type: "string", default: "8787" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" }, "log-id": { type: "string" }, tenants: { type: "string" }, "db-env": { type: "string" }, "signer-url": { type: "string" }, "signer-token-env": { type: "string" }, "retired-key": { type: "string", multiple: true }, "checkpoint-dir": { type: "string" }, "checkpoint-every": { type: "string", default: "300" }, "admin-token-env": { type: "string" }, "public-url": { type: "string" }, "checkpoints-url": { type: "string" } },
             });
             if (!values.key === !values["signer-url"])
                 throw new Error("log needs exactly one of --key or --signer-url");
@@ -249,6 +252,7 @@ async function main(argv) {
             let resolver;
             let checkpoints = values["checkpoint-dir"] ? dirCheckpoints(values["checkpoint-dir"]) : undefined;
             let where;
+            let admin;
             if (values["db-env"]) {
                 // Postgres: the file is not used; tenants, tokens, leaves, and checkpoints live in the database.
                 const client = openPostgres(values["db-env"]);
@@ -259,9 +263,17 @@ async function main(argv) {
                 resolver = postgresResolver(tenancy, { defaultTenant: "default", ...(token ? { staticTokens: [token] } : {}) });
                 const table = postgresCheckpoints(client);
                 checkpoints = checkpoints ? bothCheckpoints(table, checkpoints) : table;
+                if (values["admin-token-env"]) {
+                    const adminToken = process.env[values["admin-token-env"]];
+                    if (!adminToken)
+                        throw new Error(`log: environment variable ${values["admin-token-env"]} is not set`);
+                    admin = { tenancy, token: adminToken, ...(values["public-url"] ? { publicUrl: values["public-url"] } : {}), ...(values["checkpoints-url"] ? { checkpointsUrl: values["checkpoints-url"] } : {}) };
+                }
                 where = `store=postgres default-log=${(await tenancy.tenant("default"))?.logId} ${token ? "environment token accepted for the default log; " : ""}tokens from the database`;
             }
             else {
+                if (values["admin-token-env"])
+                    throw new Error("the admin page needs --db-env; tenants live in the database");
                 if (!values.file)
                     throw new Error("log needs --file, or --db-env");
                 // --tenants names a JSON file { "<tenant>": { "file": "...", "tokenEnv": "NAME", "logId": "..." } }; each is reached at /t/<tenant>/.
@@ -269,10 +281,10 @@ async function main(argv) {
                 resolver = fileResolver(values.file, { ...(token ? { tokens: [token] } : {}), ...(values["log-id"] ? { logId: values["log-id"] } : {}), ...(tenants ? { tenants } : {}) });
                 where = `file=${values.file}${values["log-id"] ? ` log=${values["log-id"]}` : ""} ${token ? "bearer token required" : "open, anyone may append"}${tenants ? ` tenants=${Object.keys(tenants).join(",")}` : ""}`;
             }
-            const running = await serveLog(resolver, signer, { port: Number(values.port), host: values.host, ...(checkpoints ? { checkpoints } : {}) });
+            const running = await serveLog(resolver, signer, { port: Number(values.port), host: values.host, ...(checkpoints ? { checkpoints } : {}), ...(admin ? { admin } : {}) });
             const publisher = checkpoints ? new CheckpointPublisher(resolver, signer, checkpoints, everyMs) : null;
             publisher?.start();
-            console.error(`agent-custody log: ${running.url} keyid=${signer.keyid} ${values["signer-url"] ? `signer=${values["signer-url"]} ` : ""}${where}${checkpoints ? ` checkpoints every ${values["checkpoint-every"]}s${values["checkpoint-dir"] ? ` to ${values["checkpoint-dir"]}` : ""}` : ""}`);
+            console.error(`agent-custody log: ${running.url} keyid=${signer.keyid} ${values["signer-url"] ? `signer=${values["signer-url"]} ` : ""}${where}${checkpoints ? ` checkpoints every ${values["checkpoint-every"]}s${values["checkpoint-dir"] ? ` to ${values["checkpoint-dir"]}` : ""}` : ""}${admin ? " admin page at /admin" : ""}`);
             await new Promise((resolve) => process.once("SIGINT", resolve));
             publisher?.stop();
             await running.close();

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export { fileBackend, importLogFile, PostgresLog, PostgresTenancy, RateLimiter }
 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";
+export { adminRoutes, welcomeSheet } from "./log-admin.ts";
+export type { AdminOptions } from "./log-admin.ts";
 export type { Checkpoint, CheckpointStore } from "./checkpoints.ts";
 export type { AppendResult, LogBackend, PostgresLike, PostgresLogOptions, RateLimitOptions, Tenant, TokenRecord } from "./log-store.ts";
 export type { OtelConfig, OtlpOptions, ReceiptExporter } from "./otel.ts";

package/dist/index.js

@@ -5,6 +5,7 @@ export { openExporter, otlpExporter, spanFor } from "./otel.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";
+export { adminRoutes, welcomeSheet } from "./log-admin.js";
 export * from "./config.js";
 export * from "./crypto.js";
 export * from "./delegation.js";

package/dist/log-admin.d.ts

@@ -0,0 +1,33 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { PostgresTenancy } from "./log-store.ts";
+export interface AdminOptions {
+    tenancy: PostgresTenancy;
+    /** the admin token; every /admin route needs it as a bearer */
+    token: string;
+    /** the log's public base URL, for the welcome sheet, e.g. https://log.example.com/ */
+    publicUrl?: string;
+    /** the checkpoints host, e.g. https://checkpoints.example.com/ */
+    checkpointsUrl?: string;
+    /** the current signing keyid, for the sheet */
+    keyid?: string;
+}
+/** The welcome sheet as text, the same one deploy/onboard-tenant.sh prints. */
+export declare function welcomeSheet(o: {
+    tenant: string;
+    logId: string;
+    publicUrl: string;
+    checkpointsUrl?: string;
+    keyid?: string;
+}): string;
+/**
+ * Routes under /admin. Returns true when it handled the request.
+ *   GET  /admin                                   the page
+ *   GET  /admin/info                              { publicUrl, checkpointsUrl, keyid }
+ *   GET  /admin/tenants                           [{ id, logId, createdAt, disabledAt, tokens }]
+ *   POST /admin/tenants        { id, logId? }     the tenant
+ *   POST /admin/tenants/:id/disable
+ *   GET  /admin/tenants/:id/tokens                [{ label, tokenHash, createdAt, revokedAt }]
+ *   POST /admin/tenants/:id/tokens { label }      { token, tokenHash, welcome }   token shown once
+ *   POST /admin/tenants/:id/tokens/:prefix/revoke { revoked }
+ */
+export declare function adminRoutes(opts: AdminOptions): (req: IncomingMessage, res: ServerResponse, url: URL) => Promise<boolean>;

package/dist/log-admin.js

@@ -0,0 +1,235 @@
+// The operator's admin surface for a hosted log: tenants and their tokens, over HTTP behind an admin token, and a
+// single page at /admin that drives it. It is for whoever runs the log, never for tenants: every route needs the
+// admin token, the page keeps that token in the browser session only, and a minted token is shown once, beside the
+// welcome sheet the tenant gets. Nothing here touches receipts; the log holds hashes and the panel holds names.
+import { timingSafeEqual } from "node:crypto";
+const same = (a, b) => {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+};
+/** The welcome sheet as text, the same one deploy/onboard-tenant.sh prints. */
+export function welcomeSheet(o) {
+    const base = o.publicUrl.endsWith("/") ? o.publicUrl : `${o.publicUrl}/`;
+    const url = `${base}t/${o.tenant}/`;
+    const lines = [
+        `agent-custody log: welcome sheet for tenant "${o.tenant}"`,
+        "",
+        `Your log            ${url}`,
+        `Your log id         ${o.logId}`,
+        ...(o.checkpointsUrl ? [`Your checkpoints    ${o.checkpointsUrl.replace(/\/?$/, "/")}${o.tenant}/latest.json`] : []),
+        `The log's keys      ${base}.well-known/agent-custody-log.json${o.keyid ? `  (current keyid ${o.keyid})` : ""}`,
+        "",
+        "Your token was shown once when it was made; the log keeps only its hash. Lose it and ask for a new one.",
+        "",
+        "In your gateway or SDK config:",
+        `  "log": { "url": "${url}", "tokenEnv": "AGENT_CUSTODY_LOG_TOKEN", "hashOnly": true }`,
+        "hashOnly means this log never receives your receipts, only their hashes.",
+        "",
+        "For whoever verifies your receipts:",
+        `  npx agent-custody verify receipts/<id>.json --issuer-key <your gateway.pub> --principal-key <your principal.pub> --log-url ${url} --log-id ${o.logId}`,
+        `  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.",
+        "",
+        "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",
+    ];
+    return lines.join("\n");
+}
+/**
+ * Routes under /admin. Returns true when it handled the request.
+ *   GET  /admin                                   the page
+ *   GET  /admin/info                              { publicUrl, checkpointsUrl, keyid }
+ *   GET  /admin/tenants                           [{ id, logId, createdAt, disabledAt, tokens }]
+ *   POST /admin/tenants        { id, logId? }     the tenant
+ *   POST /admin/tenants/:id/disable
+ *   GET  /admin/tenants/:id/tokens                [{ label, tokenHash, createdAt, revokedAt }]
+ *   POST /admin/tenants/:id/tokens { label }      { token, tokenHash, welcome }   token shown once
+ *   POST /admin/tenants/:id/tokens/:prefix/revoke { revoked }
+ */
+export function adminRoutes(opts) {
+    return async (req, res, url) => {
+        if (url.pathname !== "/admin" && !url.pathname.startsWith("/admin/"))
+            return false;
+        const json = (status, body) => {
+            res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+            res.end(JSON.stringify(body));
+        };
+        if (req.method === "GET" && url.pathname === "/admin") {
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "x-frame-options": "DENY", "content-security-policy": "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'" });
+            res.end(ADMIN_PAGE);
+            return true;
+        }
+        const h = req.headers.authorization ?? "";
+        if (!(h.startsWith("Bearer ") && h.length > 7 && same(h.slice(7), opts.token))) {
+            json(401, { error: "admin token required" });
+            return true;
+        }
+        const body = async () => {
+            let text = "";
+            for await (const chunk of req) {
+                text += chunk;
+                if (text.length > 16_384)
+                    throw new Error("body too large");
+            }
+            return text ? JSON.parse(text) : {};
+        };
+        try {
+            const t = opts.tenancy;
+            const parts = url.pathname.split("/").filter(Boolean); // ["admin", ...]
+            if (req.method === "GET" && parts.length === 2 && parts[1] === "info") {
+                json(200, { publicUrl: opts.publicUrl ?? null, checkpointsUrl: opts.checkpointsUrl ?? null, keyid: opts.keyid ?? null });
+            }
+            else if (req.method === "GET" && parts.length === 2 && parts[1] === "tenants") {
+                const tenants = await t.listTenants();
+                json(200, await Promise.all(tenants.map(async (x) => ({ ...x, tokens: (await t.listTokens(x.id)).filter((k) => !k.revokedAt).length }))));
+            }
+            else if (req.method === "POST" && parts.length === 2 && parts[1] === "tenants") {
+                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));
+            }
+            else if (req.method === "POST" && parts.length === 4 && parts[1] === "tenants" && parts[3] === "disable") {
+                await t.disableTenant(parts[2]);
+                json(200, { disabled: parts[2] });
+            }
+            else if (req.method === "GET" && parts.length === 4 && parts[1] === "tenants" && parts[3] === "tokens") {
+                json(200, await t.listTokens(parts[2]));
+            }
+            else if (req.method === "POST" && parts.length === 4 && parts[1] === "tenants" && parts[3] === "tokens") {
+                const b = await body();
+                const label = typeof b.label === "string" && b.label.trim() ? b.label.trim() : "fleet";
+                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 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]) });
+            }
+            else {
+                json(404, { error: "not found" });
+            }
+        }
+        catch (e) {
+            json(400, { error: e instanceof Error ? e.message : String(e) });
+        }
+        return true;
+    };
+}
+/** The page. One file, no framework, no third-party requests; the admin token lives in sessionStorage for the tab. */
+const ADMIN_PAGE = `<!doctype html>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>agent-custody log admin</title>
+<style>
+  :root { color-scheme: light dark; --ink: #1b2430; --ink2: #5b6b7a; --line: #d7dfe5; --bg: #fafbfc; --panel: #ffffff; --accent: #0f6e63; --warn: #8a5a00; --warnbg: #fbf1dc; --mono: ui-monospace, Menlo, monospace; }
+  @media (prefers-color-scheme: dark) { :root { --ink: #e6ecf0; --ink2: #9fb0bd; --line: #27333c; --bg: #0e1418; --panel: #151d23; --accent: #4fc3b0; --warn: #e2b862; --warnbg: #2d2412; } }
+  body { margin: 0; background: var(--bg); color: var(--ink); font: 15px/1.5 system-ui, sans-serif; }
+  main { max-width: 72rem; margin: 0 auto; padding: 2rem 1.25rem 4rem; }
+  h1 { font-size: 1.4rem; margin: 0 0 .25rem; } h2 { font-size: 1.05rem; margin: 2rem 0 .75rem; }
+  .sub { color: var(--ink2); margin: 0 0 1.5rem; }
+  .row { display: flex; gap: .6rem; flex-wrap: wrap; align-items: end; }
+  label { display: grid; gap: .25rem; font-size: .85rem; color: var(--ink2); }
+  input { font: inherit; padding: .45rem .6rem; border: 1px solid var(--line); border-radius: 4px; background: var(--panel); color: var(--ink); min-width: 14rem; }
+  button { font: inherit; padding: .5rem .9rem; border: 1px solid var(--accent); border-radius: 4px; background: var(--accent); color: #fff; cursor: pointer; }
+  button.quiet { background: transparent; color: var(--accent); }
+  button:disabled { opacity: .5; cursor: default; }
+  table { border-collapse: collapse; width: 100%; font-size: .93rem; }
+  th, td { text-align: left; padding: .5rem .6rem; border-bottom: 1px solid var(--line); vertical-align: top; }
+  th { font-size: .78rem; letter-spacing: .04em; text-transform: uppercase; color: var(--ink2); }
+  code, pre { font-family: var(--mono); font-size: .86em; }
+  pre { background: var(--panel); border: 1px solid var(--line); border-radius: 4px; padding: .9rem 1rem; overflow-x: auto; white-space: pre-wrap; }
+  .once { border-left: 3px solid var(--warn); background: var(--warnbg); padding: .8rem 1rem; border-radius: 0 4px 4px 0; margin: 1rem 0; }
+  .muted { color: var(--ink2); } .err { color: #b3261e; } .ok { color: var(--accent); }
+  .tok { font-family: var(--mono); font-size: 1.05rem; word-break: break-all; user-select: all; }
+  [hidden] { display: none !important; }
+</style>
+<main>
+  <h1>Log admin</h1>
+  <p class="sub" id="where">Tenants and tokens on this log. The admin token stays in this tab.</p>
+  <section id="login">
+    <div class="row"><label>Admin token<input id="token" type="password" autocomplete="off"></label><button id="enter">Enter</button></div>
+    <p class="err" id="loginErr" hidden></p>
+  </section>
+  <section id="app" hidden>
+    <h2>Tenants</h2>
+    <table><thead><tr><th>tenant</th><th>log id</th><th>live tokens</th><th>created</th><th></th></tr></thead><tbody id="tenants"></tbody></table>
+    <h2>New tenant</h2>
+    <div class="row">
+      <label>tenant id (in the URL)<input id="tid" placeholder="acme" autocomplete="off"></label>
+      <label>log id (on tree heads; default = tenant id)<input id="lid" placeholder="acme-eu" autocomplete="off"></label>
+      <button id="addTenant">Create</button>
+    </div>
+    <h2>New token</h2>
+    <div class="row">
+      <label>tenant<input id="ttid" placeholder="acme" autocomplete="off"></label>
+      <label>label (which fleet)<input id="label" placeholder="support fleet" autocomplete="off"></label>
+      <button id="mint">Mint token</button>
+    </div>
+    <div id="minted" class="once" hidden>
+      <p><b>Shown once.</b> Hand it over by a channel you trust; the log keeps only its hash.</p>
+      <p class="tok" id="tokval"></p>
+      <button class="quiet" id="copyTok">Copy token</button> <button class="quiet" id="copySheet">Copy welcome sheet</button>
+      <pre id="sheet"></pre>
+    </div>
+    <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>
+    <p class="muted" id="msg"></p>
+  </section>
+</main>
+<script>
+(() => {
+  const $ = (id) => document.getElementById(id);
+  let token = sessionStorage.getItem("agent-custody-admin") || "";
+  const api = async (method, path, body) => {
+    const r = await fetch(path, { method, headers: { authorization: "Bearer " + token, ...(body ? { "content-type": "application/json" } : {}) }, body: body ? JSON.stringify(body) : undefined });
+    const j = await r.json().catch(() => ({}));
+    if (!r.ok) throw new Error(j.error || r.statusText);
+    return j;
+  };
+  const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+  const say = (t, cls) => { $("msg").textContent = t; $("msg").className = cls || "muted"; };
+  const loadTenants = async () => {
+    const list = await api("GET", "/admin/tenants");
+    $("tenants").innerHTML = list.map((t) => "<tr><td><code>" + esc(t.id) + "</code></td><td><code>" + esc(t.logId) + "</code></td><td>" + t.tokens + "</td><td>" + esc(t.createdAt.slice(0, 10)) + "</td><td>" + (t.disabledAt ? "<span class=muted>disabled</span>" : "<button class=quiet data-disable=\\"" + esc(t.id) + "\\">Disable</button>") + "</td></tr>").join("") || "<tr><td colspan=5 class=muted>none yet</td></tr>";
+  };
+  const loadTokens = async (id) => {
+    const list = await api("GET", "/admin/tenants/" + encodeURIComponent(id) + "/tokens");
+    $("tokens").innerHTML = list.map((k) => "<tr><td>" + esc(k.label) + "</td><td><code>" + esc(k.tokenHash.slice(0, 12)) + "</code></td><td>" + esc(k.createdAt.slice(0, 10)) + "</td><td>" + (k.revokedAt ? "revoked " + esc(k.revokedAt.slice(0, 10)) : "<span class=ok>live</span>") + "</td><td>" + (k.revokedAt ? "" : "<button class=quiet data-revoke=\\"" + esc(id) + "|" + esc(k.tokenHash.slice(0, 12)) + "\\">Revoke</button>") + "</td></tr>").join("") || "<tr><td colspan=5 class=muted>no tokens</td></tr>";
+  };
+  const enter = async () => {
+    try {
+      const info = await api("GET", "/admin/info");
+      $("where").textContent = (info.publicUrl || location.origin) + " · keyid " + (info.keyid ? info.keyid.slice(0, 12) : "?") + (info.checkpointsUrl ? " · checkpoints at " + info.checkpointsUrl : "");
+      $("login").hidden = true; $("app").hidden = false;
+      sessionStorage.setItem("agent-custody-admin", token);
+      await loadTenants();
+    } catch (e) { $("loginErr").hidden = false; $("loginErr").textContent = e.message; }
+  };
+  $("enter").onclick = () => { token = $("token").value.trim(); enter(); };
+  $("token").onkeydown = (e) => { if (e.key === "Enter") $("enter").click(); };
+  $("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"); } };
+  $("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();
+    } catch (e) { say(e.message, "err"); }
+  };
+  $("copyTok").onclick = () => navigator.clipboard.writeText($("tokval").textContent).then(() => say("token copied", "ok"));
+  $("copySheet").onclick = () => navigator.clipboard.writeText($("sheet").textContent).then(() => say("welcome sheet copied", "ok"));
+  $("listTokens").onclick = () => loadTokens($("ltid").value.trim()).catch((e) => say(e.message, "err"));
+  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 (token) enter();
+})();
+</script>
+`;

package/dist/log-sink.d.ts

@@ -4,6 +4,7 @@ import { type InclusionProof } from "./log.ts";
 import { 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";
 export interface LogAppend {
     inclusion: InclusionProof;
     /** signed TreeHead; the signature's keyid says who runs the log */
@@ -62,6 +63,8 @@ export interface LogServerOptions {
     maxBodyBytes?: number;
     /** where published checkpoints go and are listed from; without one, /checkpoints answers with none */
     checkpoints?: CheckpointStore;
+    /** the operator's admin API and page under /admin, behind its own token; only with a Postgres tenancy */
+    admin?: AdminOptions;
 }
 /** One log as the handler sees it, whatever stands behind it. */
 export interface ResolvedLog {

package/dist/log-sink.js

@@ -10,6 +10,7 @@ import { createHash } from "node:crypto";
 import { leafHash, MerkleLog } from "./log.js";
 import { fileBackend, RateLimiter } from "./log-store.js";
 import { localSigner } from "./signer.js";
+import { adminRoutes } from "./log-admin.js";
 import { TREEHEAD_TYPE } from "./receipt.js";
 function signedHead(e, key, logId) {
     const head = { treeSize: e.treeSize, rootHash: e.rootHash, timestamp: new Date().toISOString(), ...(logId ? { log: logId } : {}) };
@@ -211,6 +212,7 @@ export class CheckpointPublisher {
 export function logHandler(source, keyOrSigner, opts = {}) {
     const resolver = typeof source === "string" ? fileResolver(source, opts) : source;
     const signer = "privateKey" in keyOrSigner ? localSigner(keyOrSigner) : keyOrSigner;
+    const admin = opts.admin ? adminRoutes({ ...opts.admin, keyid: opts.admin.keyid ?? signer.keyid }) : null;
     const limiter = new RateLimiter(opts.rateLimit);
     const maxBody = opts.maxBodyBytes ?? 65_536;
     const bearer = (req) => {
@@ -223,6 +225,8 @@ export function logHandler(source, keyOrSigner, opts = {}) {
             res.end(JSON.stringify(body));
         };
         const url = new URL(req.url ?? "/", "http://localhost");
+        if (admin && (await admin(req, res, url)))
+            return;
         if (req.method === "GET" && url.pathname === "/.well-known/agent-custody-log.json") {
             try {
                 const doc = await signer.keys();

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>`. [deploy/](../../deploy/README.md) runs the server, the signer, Postgres, and the checkpoints host as containers.
+Exactly one of the two. The bearer token comes from the named environment variable, never from the file, and a missing variable fails at startup. Add `"hashOnly": true` for any log run by someone else: the gateway then sends only the leaf hash, sha256 of the receipt envelope with the RFC 6962 prefix, so the log commits to the receipt without ever holding it, and the receipts with their arguments and results stay in `receiptsDir`. The verifier does not change; it hashes the envelope itself. A log that serves several tenants is reached at `<url>/t/<tenant>/`, and each of its tree heads names its log, which a verifier checks with `--log-id`. With a remote log the tree head in each receipt is signed by the log's key, and a verifier must be given that key with `--log-key`. If the log refuses a leaf, the receipt is not issued and the call returns an error to the agent. For an ordinary call the upstream action has already happened by then, and the error says so; a receipt that was never logged must not be handed out. For a tool named in `precommit` the order is reversed, below, and the action never happens. The reference log server is `node src/cli.ts log --file log.jsonl --key keys/log.key --port 8787 --token-env AGENT_CUSTODY_LOG_TOKEN [--log-id <id>] [--tenants tenants.json]`. It serves `POST /append` with `{leaf}` or `{leafHash}` (token required when one is configured), `GET /root?size=N`, `GET /consistency?old=M&new=N`, and `GET /head`; [verification.md](verification.md) says what each proves. `--log-id` writes that id into every tree head. `--tenants` names a JSON file, `{ "acme": { "file": "acme.jsonl", "tokenEnv": "ACME_TOKEN", "logId": "acme-eu" } }`, and each tenant is its own log at `/t/acme/…` with its own token and id; the default log stays at the root paths. With `--db-env DATABASE_URL` the server keeps its logs in Postgres instead of files, and needs the `pg` package beside it: leaves as hashes in one table keyed by tenant, one writer per tenant enforced with an advisory lock so a second instance is safe, tenants and their tokens in tables of their own with tokens stored only as hashes, and rate limits per token (50 appends a second, burst 100, a 64 KB body cap; a refused append answers 429 with `retry-after`, and the gateway's sink retries a few times). Tenants are managed with `log-admin --db-env DATABASE_URL`: `tenant add <id> [--log-id <id>]`, `token add <tenant> --label <text>` (the token is printed once), `token revoke <tenant> <hash-prefix>`, `tenant disable <id>`, and `import --file log.jsonl [--tenant default]` to bring an existing file log in as hashes. The root paths serve the tenant `default`, created on first start with `--log-id`, and `--token-env` still works for it. The key that signs tree heads can live in its own process: `agent-custody signer --key keys/log.key --port 8790 --token-env SIGNER_TOKEN` holds it and answers `POST /sign` with the shared secret and `GET /keys` to anyone; the log server then runs with `--signer-url http://signer:8790/ --signer-token-env SIGNER_TOKEN` instead of `--key`, and the process that faces the internet never holds the key. Either way the log serves its keys at `/.well-known/agent-custody-log.json`, current key first and retired keys (`--retired-key old.pub`) after it, so verifiers fetch and pin them with `verify --log-url` and `audit --log-url` rather than receiving a key file from the operator. With `--checkpoint-dir <dir>` the server publishes a signed checkpoint, every `--checkpoint-every` seconds (default 300), for each log whose tree has grown, as `<dir>/<tenant>/<treeSize>.json` and `latest.json`, and with a database also as rows; `GET /checkpoints?since=<size>` and `GET /t/<tenant>/checkpoints` list them. Serve the directory read-only from a second host, so the record of what the log signed does not depend on the log's API being up; a verifier who kept an earlier head audits against a later checkpoint with `audit --older <bundle> --newer <checkpoint> --log-url <url>`. With `--admin-token-env ADMIN_TOKEN` (Postgres only) the server also serves the operator's page at `/admin` and its API under `/admin/`: list and create tenants, mint a token that is shown once beside the tenant's welcome sheet, revoke tokens, disable tenants. Every route needs the admin token as a bearer; the page keeps it in the browser session. `--public-url` and `--checkpoints-url` fill the sheet in. [deploy/](../../deploy/README.md) runs the server, the signer, Postgres, and the checkpoints host as containers.
 
 `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.0",
+  "version": "0.5.1",
   "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": {