@agent-custody/receipts 0.4.0 → 0.5.0

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): phases 1 to 3 are done; what remains is running it for the first tenant, and then a 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,22 @@
+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. */
+export declare function bothCheckpoints(...stores: CheckpointStore[]): CheckpointStore;

package/dist/checkpoints.js

@@ -0,0 +1,81 @@
+// 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. */
+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),
+        latest: (t) => stores[0].latest(t),
+    };
+}

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,40 @@ 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
+  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 +153,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 +226,55 @@ 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" } },
             });
-            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;
+            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;
+                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.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 } : {}) });
+            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"]}` : ""}` : ""}`);
             await new Promise((resolve) => process.once("SIGINT", resolve));
+            publisher?.stop();
             await running.close();
             return 0;
         }
@@ -156,6 +287,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 +301,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 +330,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 +350,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,12 @@ 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 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,9 @@
 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 * from "./config.js";
 export * from "./crypto.js";
 export * from "./delegation.js";

package/dist/log-sink.d.ts

@@ -1,6 +1,9 @@
 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";
 export interface LogAppend {
     inclusion: InclusionProof;
     /** signed TreeHead; the signature's keyid says who runs the log */
@@ -19,9 +22,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 +56,51 @@ 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;
+}
+/** 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 +109,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>;