@agent-custody/receipts 0.4.0 → 0.5.1

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

@@ -1,6 +1,10 @@
 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 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 */
@@ -19,9 +23,14 @@ export interface HttpLogOptions {
     token?: string;
     /** send only the leaf hash; the log then commits to the receipt without ever holding it. Use it for any log run by someone else. */
     hashOnly?: boolean;
+    /** attempts on 429 and 5xx; default 3 */
+    retries?: number;
     fetch?: typeof fetch;
 }
-/** A log reached over HTTP: POST <url>/append with {leaf}, expecting a LogAppend back. */
+/**
+ * A log reached over HTTP: POST <url>/append with {leaf} or {leafHash}, expecting a LogAppend back. A 429 or a 5xx
+ * is retried a few times with backoff, honouring Retry-After; anything else, or the last failure, is the caller's.
+ */
 export declare function httpLog(url: string, opts?: HttpLogOptions): LogSink;
 export interface LogConfig {
     logFile?: string | undefined;
@@ -48,6 +57,53 @@ export interface LogServerOptions {
         tokens?: string[];
         logId?: string;
     }>;
+    /** appends per token (or per address without one); default 50 a second, burst 100 */
+    rateLimit?: RateLimitOptions;
+    /** largest append body accepted, in bytes; default 65536 */
+    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 {
+    backend: LogBackend;
+    logId: string | undefined;
+    authorize(token: string | null): Promise<boolean>;
+}
+/** Turns the tenant in a path, or null for the root paths, into a log. */
+export interface LogResolver {
+    resolve(tenant: string | null): Promise<ResolvedLog | null>;
+    /** every log this server has, null for the root one; what the checkpoint publisher walks */
+    tenants(): Promise<(string | null)[]>;
+}
+/** The reference server's logs: one file for the root paths and, optionally, a file per tenant from the options. */
+export declare function fileResolver(file: string, opts?: LogServerOptions): LogResolver;
+/**
+ * Logs in Postgres: every tenant from the tenants table, each with its own log and tokens; the root paths serve the
+ * tenant named `defaultTenant`, which also accepts `staticTokens` so a server can keep its environment token.
+ */
+export declare function postgresResolver(tenancy: PostgresTenancy, opts?: {
+    defaultTenant?: string;
+    staticTokens?: string[];
+}): LogResolver;
+/**
+ * Publishes one checkpoint per log whose tree has grown since the last one: the current head, signed, into the
+ * checkpoint store. Call publishOnce on a timer, or start() to run it every `everyMs`.
+ */
+export declare class CheckpointPublisher {
+    private timer;
+    private readonly resolver;
+    private readonly signer;
+    private readonly store;
+    private readonly everyMs;
+    private readonly warn;
+    constructor(resolver: LogResolver, signer: Signer, store: CheckpointStore, everyMs?: number, warn?: (m: string) => void);
+    /** Publishes for every log that has grown; returns the checkpoints written. */
+    publishOnce(): Promise<Checkpoint[]>;
+    start(): void;
+    stop(): void;
 }
 /**
  * The reference log server as a node:http request handler.
@@ -56,13 +112,13 @@ export interface LogServerOptions {
  *   GET  /consistency?old=M&new=N -> {oldSize, newSize, hashes}, proof that the log at N extends the log at M
  *   GET  /head             -> {treeHead}, the current tree head signed with the log's key
  */
-export declare function logHandler(file: string, key: KeyPair, opts?: LogServerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export declare function logHandler(source: string | LogResolver, keyOrSigner: KeyPair | Signer, opts?: LogServerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
 export interface RunningLog {
     url: string;
     close(): Promise<void>;
 }
 /** Starts the reference log server. Port 0 picks a free port. */
-export declare function serveLog(file: string, key: KeyPair, opts: LogServerOptions & {
+export declare function serveLog(source: string | LogResolver, keyOrSigner: KeyPair | Signer, opts: LogServerOptions & {
     port: number;
     host?: string;
 }): Promise<RunningLog>;