@agent-custody/receipts 0.4.0 → 0.5.1

package/README.md

@@ -225,6 +225,9 @@ If a vendor tells you their receipts prove more than the first five rows, ask th
 src/config.ts      gateway and SDK config schemas, path resolution
 src/crypto.ts      canonical JSON, sha256, Ed25519 keys, DSSE sign/verify
 src/log.ts         Merkle log: append, root, inclusion and consistency proofs, verify, JSONL persistence
+src/signer.ts      the signer: the log's key in its own process, the key document verifiers fetch
+src/checkpoints.ts signed heads published on a schedule, to files and to Postgres
+src/log-store.ts   the log server's backends: the file, and Postgres with tenants, hashed tokens, one writer per tenant, rate limits
 src/log-sink.ts    where leaves go: the local file, or a remote log over HTTP; plus the reference log server
 src/policy.ts      Cedar evaluation wrapper, fail-closed
 src/delegation.ts  signed delegation grants
@@ -277,6 +280,8 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 - Remote log: the issuer can append to a log run by someone else over HTTP, whose key then signs the tree heads, so a verifier learns the receipt was in a log the operator could not rewrite. Includes the reference log server, bearer-token auth, and a root endpoint for auditors.
 - Framework adapters, each tested against the real package with a scripted model and no network: OpenAI Agents SDK (`wrapTools` enforces, `observeRunner` records from lifecycle events), Vercel AI SDK (`wrapTools` over a real `generateText` loop), LangChain (`ReceiptCallbackHandler` records, `issuer.wrap` enforces).
 
+- The signer, keys, and checkpoints: the key in its own process (`signer`, `--signer-url`), the key document at `/.well-known/agent-custody-log.json` fetched and pinned by `verify --log-url` and `audit --log-url`, and signed checkpoints per log published to a directory and a table for a verifier who was not watching. Phase 3 of [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
+- The log over Postgres: `log --db-env`, leaves as hashes in one table keyed by tenant, one writer per tenant by advisory lock, tenants and hashed tokens in tables managed by `log-admin`, rate limits and a body cap, retries in the sink, and `import` for an existing file log. Phase 2 of [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 - A log for someone else: `hashOnly` sends leaf hashes so the log never holds a receipt; the reference server runs several tenant logs at `/t/<tenant>/` with their own tokens and ids; tree heads name their log and the verifier checks it with `--log-id`. Phase 1 of the hosted log, [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 - OpenTelemetry export: with `otel` in either config, every receipt is also one span at the collector the team already runs, trace id equal to the receipt id, attributes for tool, agent, principal, status, decision, and log position; after the receipt, best effort, never on the evidence path.
 - The REST connector: a plain HTTP API described as tools in the gateway config, credentials from the environment, so an agent's direct API calls become receipted, policy-checked tool calls through the gateway.
@@ -284,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 2 and 3: the Postgres store with one writer per tenant, tokens and rate limits, the signer as its own process, published checkpoints, and well-known keys fetched with `--log-url`. Phase 1 is done; it comes before everything below.
+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

@@ -0,0 +1,26 @@
+import type { Envelope } from "./crypto.ts";
+import type { PostgresLike } from "./log-store.ts";
+export interface Checkpoint {
+    tenant: string;
+    logId: string | undefined;
+    treeSize: number;
+    rootHash: string;
+    signedAt: string;
+    envelope: Envelope;
+}
+export interface CheckpointStore {
+    save(c: Checkpoint): Promise<void>;
+    /** checkpoints of a tenant with treeSize > since, oldest first */
+    list(tenant: string, since?: number): Promise<Checkpoint[]>;
+    latest(tenant: string): Promise<Checkpoint | null>;
+}
+/** Files: <dir>/<tenant>/<treeSize>.json and <dir>/<tenant>/latest.json. Serve the directory read-only from the checkpoints host. */
+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. `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

@@ -0,0 +1,95 @@
+// Checkpoints: signed tree heads published on a schedule to a place the log's own API does not have to be up to
+// serve. A verifier who kept a head can fetch a later checkpoint and the consistency proof between them, and
+// learn that nothing was rewritten while nobody was watching. On disk they are plain files, one per tree size,
+// meant to be served statically from a second host; in Postgres they are rows, so the API can list them too.
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const safe = (s) => s.replace(/[^A-Za-z0-9_.-]/g, "_");
+/** Files: <dir>/<tenant>/<treeSize>.json and <dir>/<tenant>/latest.json. Serve the directory read-only from the checkpoints host. */
+export function dirCheckpoints(dir) {
+    const folder = (tenant) => join(dir, safe(tenant));
+    const read = (tenant, name) => {
+        try {
+            return JSON.parse(readFileSync(join(folder(tenant), name), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        async save(c) {
+            mkdirSync(folder(c.tenant), { recursive: true });
+            const text = JSON.stringify(c, null, 2);
+            writeFileSync(join(folder(c.tenant), `${c.treeSize}.json`), text);
+            writeFileSync(join(folder(c.tenant), "latest.json"), text);
+        },
+        async list(tenant, since = -1) {
+            let names;
+            try {
+                names = readdirSync(folder(tenant));
+            }
+            catch {
+                return [];
+            }
+            return names
+                .filter((n) => /^\d+\.json$/.test(n))
+                .map((n) => Number(n.slice(0, -5)))
+                .filter((n) => n > since)
+                .sort((a, b) => a - b)
+                .map((n) => read(tenant, `${n}.json`))
+                .filter((c) => c !== null);
+        },
+        async latest(tenant) {
+            return read(tenant, "latest.json");
+        },
+    };
+}
+/** Rows in <prefix>heads, one per tenant and tree size. */
+export function postgresCheckpoints(client, prefix = "log_") {
+    if (!/^[a-z_][a-z0-9_]*$/.test(prefix))
+        throw new Error(`prefix must be a plain lowercase identifier; got "${prefix}"`);
+    const table = `${prefix}heads`;
+    let ready = null;
+    const init = () => (ready ??= client.query(`CREATE TABLE IF NOT EXISTS ${table} (tenant_id TEXT NOT NULL, tree_size BIGINT NOT NULL, log_id TEXT, root_hash TEXT NOT NULL, signed_at TIMESTAMPTZ NOT NULL, envelope TEXT NOT NULL, PRIMARY KEY (tenant_id, tree_size))`).then(() => { }));
+    const row = (r) => ({ tenant: String(r.tenant_id), logId: r.log_id ? String(r.log_id) : undefined, treeSize: Number(r.tree_size), rootHash: String(r.root_hash), signedAt: new Date(r.signed_at).toISOString(), envelope: JSON.parse(String(r.envelope)) });
+    return {
+        async save(c) {
+            await init();
+            await client.query(`INSERT INTO ${table} (tenant_id, tree_size, log_id, root_hash, signed_at, envelope) VALUES ($1, $2, $3, $4, $5, $6) ON CONFLICT (tenant_id, tree_size) DO NOTHING`, [c.tenant, c.treeSize, c.logId ?? null, c.rootHash, c.signedAt, JSON.stringify(c.envelope)]);
+        },
+        async list(tenant, since = -1) {
+            await init();
+            return (await client.query(`SELECT tenant_id, tree_size, log_id, root_hash, signed_at, envelope FROM ${table} WHERE tenant_id = $1 AND tree_size > $2 ORDER BY tree_size`, [tenant, since])).rows.map(row);
+        },
+        async latest(tenant) {
+            await init();
+            const rows = (await client.query(`SELECT tenant_id, tree_size, log_id, root_hash, signed_at, envelope FROM ${table} WHERE tenant_id = $1 ORDER BY tree_size DESC LIMIT 1`, [tenant])).rows;
+            return rows[0] ? row(rows[0]) : null;
+        },
+    };
+}
+/**
+ * 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) {
+            for (const s of stores)
+                await s.save(c);
+        },
+        list: (t, since) => stores[0].list(t, since),
+        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

@@ -6,7 +6,12 @@ import { loadConfig, loadSdkConfig } from "./config.js";
 import { generateKeyPair, loadPrivateKey, loadPublicKey, writeKeyPair } from "./crypto.js";
 import { createDelegation } from "./delegation.js";
 import { createGateway, serveStdio } from "./gateway.js";
-import { serveLog } from "./log-sink.js";
+import { postgresResolver, serveLog } from "./log-sink.js";
+import { importLogFile, PostgresTenancy } from "./log-store.js";
+import { bothCheckpoints, dirCheckpoints, postgresCheckpoints } from "./checkpoints.js";
+import { connectSigner, fetchLogKeys, localSigner, serveSigner } from "./signer.js";
+import { CheckpointPublisher, fileResolver } from "./log-sink.js";
+import { createRequire } from "node:module";
 import { pruneLog } from "./retention.js";
 import { serveSidecar } from "./sidecar.js";
 import { MerkleLog } from "./log.js";
@@ -30,10 +35,43 @@ const USAGE = `agent-custody <command>
   prune   --log <log.jsonl> --before <ISO instant> [--receipts <dir>]
           retention on the receipt log: replaces older leaves with their hashes, so proofs still verify and the content is gone
   log     --file <log.jsonl> --key <log.key> [--port 8787] [--host 127.0.0.1] [--token-env <NAME>]   reference log server
-  verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--log-id <id>] [--upstream-key <pub>] [--stripe-secret-env NAME] [--github-secret-env NAME] [--log <log.jsonl>] [--json]
-  audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--log-id <id>] [--json]
+  verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub> | --log-url <url>] [--log-id <id>] [--upstream-key <pub>] [--stripe-secret-env NAME] [--github-secret-env NAME] [--log <log.jsonl>] [--json]
+  log     ... --db-env NAME                     the same server over Postgres: tenants and tokens from the database, one writer per tenant,
+                                                 root paths serve the tenant "default" (created with --log-id). Needs the pg package.
+  log     ... (--key <log.key> [--retired-key <pub>]... | --signer-url <url> [--signer-token-env NAME]) [--checkpoint-dir <dir>] [--checkpoint-every <seconds>]
+                                                 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>
+  log-admin --db-env NAME token add <tenant> --label <text> | token list <tenant> | token revoke <tenant> <hash-prefix>
+  log-admin --db-env NAME import --file <log.jsonl> [--tenant default]      copies a file log into the database as hashes
+  audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) [--issuer-key <pub>] [--log-key <pub>] [--log-id <id>] [--json]
+                                                 with --log-url the log's published keys are fetched and pinned by keyid
           checks that the newer receipt's log extends the older one's: nothing between them was rewritten
 `;
+/** A retired public key for the key document, from a .pub file; still listed so heads it signed keep verifying. */
+function retiredKey(pubFile) {
+    return { key: loadPublicKey(pubFile), pem: readFileSync(pubFile, "utf8") };
+}
+/** A pg Pool from the URL in an environment variable. pg is an optional peer: it is loaded only here, and its absence says what to install. */
+function openPostgres(envName) {
+    const url = process.env[envName];
+    if (!url)
+        throw new Error(`environment variable ${envName} is not set`);
+    let Pool;
+    try {
+        ({ Pool } = createRequire(import.meta.url)("pg"));
+    }
+    catch {
+        throw new Error("a Postgres log needs the pg package: npm install pg");
+    }
+    return new Pool({ connectionString: url });
+}
 /** The tenants file for `log --tenants`: paths relative to the file, tokens from the environment, ids default to the tenant name. */
 function loadTenants(path) {
     const raw = JSON.parse(readFileSync(path, "utf8"));
@@ -118,6 +156,66 @@ async function main(argv) {
             await running.close();
             return 0;
         }
+        case "signer": {
+            const { values } = parseArgs({ args: rest, options: { key: { type: "string" }, port: { type: "string", default: "8790" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" }, "retired-key": { type: "string", multiple: true } } });
+            if (!values.key)
+                throw new Error("signer needs --key");
+            const token = values["token-env"] ? process.env[values["token-env"]] : undefined;
+            if (values["token-env"] && !token)
+                throw new Error(`signer: environment variable ${values["token-env"]} is not set`);
+            const kp = loadPrivateKey(values.key);
+            const running = await serveSigner(kp, { port: Number(values.port), host: values.host, ...(token ? { token } : {}), retired: (values["retired-key"] ?? []).map(retiredKey) });
+            console.error(`agent-custody signer: ${running.url} keyid=${kp.keyid} ${token ? "token required" : "open: bind this to a private network"}${values["retired-key"]?.length ? ` retired=${values["retired-key"].length}` : ""}`);
+            await new Promise((resolve) => process.once("SIGINT", resolve));
+            await running.close();
+            return 0;
+        }
+        case "log-admin": {
+            const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { "db-env": { type: "string" }, "log-id": { type: "string" }, label: { type: "string" }, file: { type: "string" }, tenant: { type: "string", default: "default" } } });
+            if (!values["db-env"])
+                throw new Error("log-admin needs --db-env NAME");
+            const tenancy = new PostgresTenancy(openPostgres(values["db-env"]));
+            const [what, verb, ...args] = positionals;
+            if (what === "tenant" && verb === "add" && args[0]) {
+                const t = await tenancy.addTenant(args[0], values["log-id"] ?? args[0]);
+                console.log(`tenant ${t.id} log=${t.logId} reached at /t/${t.id}/`);
+            }
+            else if (what === "tenant" && verb === "list") {
+                for (const t of await tenancy.listTenants())
+                    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]);
+                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);
+                console.error(`token for ${args[0]} (${values.label}); shown once, stored as hash ${tokenHash.slice(0, 12)}…:`);
+                console.log(token);
+            }
+            else if (what === "token" && verb === "list" && args[0]) {
+                for (const t of await tenancy.listTokens(args[0]))
+                    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)`);
+            }
+            else if (what === "import") {
+                if (!values.file)
+                    throw new Error("import needs --file <log.jsonl>");
+                if (!(await tenancy.tenant(values.tenant)))
+                    throw new Error(`unknown tenant ${values.tenant}; add it first`);
+                const r = await importLogFile(values.file, await tenancy.log(values.tenant));
+                console.log(`imported ${r.added} leaf hash(es) into ${values.tenant}; the log now has ${r.total}`);
+            }
+            else {
+                console.error(USAGE);
+                return 2;
+            }
+            return 0;
+        }
         case "prune": {
             const { values } = parseArgs({ args: rest, options: { log: { type: "string" }, before: { type: "string" }, receipts: { type: "string" } } });
             if (!values.log || !values.before)
@@ -131,19 +229,64 @@ 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" } },
+                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.file || !values.key)
-                throw new Error("log needs --file and --key");
+            if (!values.key === !values["signer-url"])
+                throw new Error("log needs exactly one of --key or --signer-url");
             const token = values["token-env"] ? process.env[values["token-env"]] : undefined;
             if (values["token-env"] && !token)
                 throw new Error(`log: environment variable ${values["token-env"]} is not set`);
-            const key = loadPrivateKey(values.key);
-            // --tenants names a JSON file { "<tenant>": { "file": "...", "tokenEnv": "NAME", "logId": "..." } }; each is reached at /t/<tenant>/.
-            const tenants = values.tenants ? loadTenants(values.tenants) : undefined;
-            const running = await serveLog(values.file, key, { port: Number(values.port), host: values.host, ...(token ? { tokens: [token] } : {}), ...(values["log-id"] ? { logId: values["log-id"] } : {}), ...(tenants ? { tenants } : {}) });
-            console.error(`agent-custody log: ${running.url} keyid=${key.keyid} file=${values.file}${values["log-id"] ? ` log=${values["log-id"]}` : ""} ${token ? "bearer token required" : "open, anyone may append"}${tenants ? ` tenants=${Object.keys(tenants).join(",")}` : ""}`);
+            // The signer: a key in this process, or the signer service that holds it.
+            let signer;
+            if (values.key)
+                signer = localSigner(loadPrivateKey(values.key), { retired: (values["retired-key"] ?? []).map(retiredKey) });
+            else {
+                const st = values["signer-token-env"] ? process.env[values["signer-token-env"]] : undefined;
+                if (values["signer-token-env"] && !st)
+                    throw new Error(`log: environment variable ${values["signer-token-env"]} is not set`);
+                signer = await connectSigner(values["signer-url"], st ? { token: st } : {});
+            }
+            const everyMs = Number(values["checkpoint-every"]) * 1000;
+            if (!(everyMs > 0))
+                throw new Error("--checkpoint-every must be a positive number of seconds");
+            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"]);
+                const tenancy = new PostgresTenancy(client);
+                const defaultId = values["log-id"] ?? "default";
+                if (!(await tenancy.tenant("default")))
+                    await tenancy.addTenant("default", defaultId);
+                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>/.
+                const tenants = values.tenants ? loadTenants(values.tenants) : undefined;
+                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 } : {}), ...(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"]}` : ""}` : ""}${admin ? " admin page at /admin" : ""}`);
             await new Promise((resolve) => process.once("SIGINT", resolve));
+            publisher?.stop();
             await running.close();
             return 0;
         }
@@ -156,6 +299,7 @@ async function main(argv) {
                     "gateway-key": { type: "string", multiple: true },
                     "principal-key": { type: "string", multiple: true },
                     "log-key": { type: "string", multiple: true },
+                    "log-url": { type: "string" },
                     "log-id": { type: "string" },
                     "upstream-key": { type: "string", multiple: true },
                     "stripe-secret-env": { type: "string" },
@@ -169,10 +313,12 @@ async function main(argv) {
             if (!file || issuerKeyFiles.length === 0)
                 throw new Error("verify needs <bundle> --issuer-key (alias --gateway-key)");
             const bundle = JSON.parse(readFileSync(file, "utf8"));
+            const fetchedLogKeys = values["log-url"] ? (await fetchLogKeys(values["log-url"])).keys : [];
+            const logKeys = [...(values["log-key"] ?? []).map(loadPublicKey), ...fetchedLogKeys];
             const result = verifyBundle(bundle, {
                 issuerKeys: issuerKeyFiles.map(loadPublicKey),
                 principalKeys: (values["principal-key"] ?? []).map(loadPublicKey),
-                ...(values["log-key"] ? { logKeys: values["log-key"].map(loadPublicKey) } : {}),
+                ...(logKeys.length ? { logKeys } : {}),
                 ...(values["log-id"] ? { logId: values["log-id"] } : {}),
                 ...(values["upstream-key"] ? { upstreamKeys: values["upstream-key"].map(loadPublicKey) } : {}),
                 ...(values["stripe-secret-env"] || values["github-secret-env"] ? { providerSecrets: { ...(values["stripe-secret-env"] ? { stripe: secretFrom(values["stripe-secret-env"]) } : {}), ...(values["github-secret-env"] ? { github: secretFrom(values["github-secret-env"]) } : {}) } } : {}),
@@ -196,10 +342,13 @@ async function main(argv) {
                 },
             });
             const keyFiles = [...(values["issuer-key"] ?? []), ...(values["log-key"] ?? [])];
-            if (!values.older || !values.newer || keyFiles.length === 0)
-                throw new Error("audit needs --older, --newer, and at least one --issuer-key or --log-key");
+            if (!values.older || !values.newer)
+                throw new Error("audit needs --older and --newer");
             if (!values.log === !values["log-url"])
                 throw new Error("audit needs exactly one of --log or --log-url");
+            const auditKeys = [...keyFiles.map(loadPublicKey), ...(values["log-url"] ? (await fetchLogKeys(values["log-url"])).keys : [])];
+            if (auditKeys.length === 0)
+                throw new Error("audit needs a key: --issuer-key, --log-key, or a --log-url that publishes its keys");
             const older = JSON.parse(readFileSync(values.older, "utf8")).treeHead;
             const newer = JSON.parse(readFileSync(values.newer, "utf8")).treeHead;
             const sizeOf = (env) => JSON.parse(Buffer.from(env.payload, "base64").toString()).treeSize;
@@ -213,7 +362,7 @@ async function main(argv) {
                     throw new Error(`log refused the consistency query: ${res.status}`);
                 proof = (await res.json()).hashes;
             }
-            const result = auditExtends(older, newer, proof, keyFiles.map(loadPublicKey), values["log-id"]);
+            const result = auditExtends(older, newer, proof, auditKeys, values["log-id"]);
             if (values.json)
                 console.log(JSON.stringify(result, null, 2));
             else {

package/dist/index.d.ts

@@ -3,6 +3,14 @@ export type { AuthorizationBundle, AuthorizationPredicate, AuthorizationStatemen
 export type { GatewayOptions } from "./gateway.ts";
 export { buildRequest, restUpstream } from "./rest.ts";
 export { openExporter, otlpExporter, spanFor } from "./otel.ts";
+export { fileBackend, importLogFile, PostgresLog, PostgresTenancy, RateLimiter } from "./log-store.ts";
+export { connectSigner, fetchLogKeys, localSigner, serveSigner, signerHandler } from "./signer.ts";
+export type { KeyDocument, RemoteSignerOptions, RetiredKey, RunningSigner, Signer, SignerServerOptions } from "./signer.ts";
+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";
 export type { IssuerOptions } from "./issue.ts";
 export type { RestOptions, UpstreamClient } from "./rest.ts";

package/dist/index.js

@@ -2,6 +2,10 @@
 export { AUTHORIZATION_PREDICATE_TYPE, buildAuthorizationStatement } from "./receipt.js";
 export { buildRequest, restUpstream } from "./rest.js";
 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>;