@agent-custody/receipts 0.4.0 → 0.5.1

package/dist/log-store.js

@@ -0,0 +1,312 @@
+// Where a log server keeps its logs. The file backend is the reference server as it was: one JSONL file per log,
+// read into memory. The Postgres backend is a log run for other people: leaves in one table keyed by tenant, one
+// writer per tenant enforced by an advisory lock so a second instance is safe, tenants and their tokens in tables of
+// their own, and rate limits per token. The subtree cache stays in memory on every instance and resyncs from the
+// table whenever the table has moved on without it.
+import { createHash, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { leafHash, MerkleLog, SubtreeCache } from "./log.js";
+/** The JSONL file log behind the asynchronous interface. */
+export function fileBackend(file) {
+    const log = new MerkleLog(file);
+    return {
+        async size() {
+            return log.size;
+        },
+        async append(leaf) {
+            return log.append(leaf);
+        },
+        async appendHash(hex) {
+            return log.appendHash(hex);
+        },
+        async root(size) {
+            return log.root(size);
+        },
+        async consistencyProof(oldSize, newSize) {
+            return log.consistencyProof(oldSize, newSize);
+        },
+    };
+}
+const ident = (s, what) => {
+    if (!/^[a-z_][a-z0-9_]*$/.test(s))
+        throw new Error(`${what} must be a plain lowercase identifier; got "${s}"`);
+    return s;
+};
+/**
+ * A client without `connect` is one connection (PGlite, a single pg Client), so its transactions must not interleave:
+ * they are queued per client. A pool hands out a connection per transaction and the advisory lock does the rest.
+ */
+const queues = new WeakMap();
+function queued(client, fn) {
+    const prev = queues.get(client) ?? Promise.resolve();
+    const next = prev.then(fn, fn);
+    queues.set(client, next.catch(() => { }));
+    return next;
+}
+/** Runs `fn` inside one transaction on one connection, whichever kind of client this is. */
+async function transaction(client, fn) {
+    if (!client.connect)
+        return queued(client, () => singleConnectionTransaction(client, fn));
+    {
+        const c = await client.connect();
+        try {
+            await c.query("BEGIN");
+            const out = await fn((t, v) => c.query(t, v));
+            await c.query("COMMIT");
+            return out;
+        }
+        catch (e) {
+            await c.query("ROLLBACK").catch(() => { });
+            throw e;
+        }
+        finally {
+            c.release();
+        }
+    }
+}
+async function singleConnectionTransaction(client, fn) {
+    await client.query("BEGIN");
+    try {
+        const out = await fn((t, v) => client.query(t, v));
+        await client.query("COMMIT");
+        return out;
+    }
+    catch (e) {
+        await client.query("ROLLBACK").catch(() => { });
+        throw e;
+    }
+}
+/** One tenant's log in Postgres. Leaves are hashes only; the table never holds a receipt. */
+export class PostgresLog {
+    tenant;
+    client;
+    leaves;
+    hashes = [];
+    cache = new SubtreeCache(this.hashes);
+    ready = null;
+    chain = Promise.resolve();
+    constructor(client, tenant, opts = {}) {
+        this.client = client;
+        this.tenant = tenant;
+        this.leaves = `${ident(opts.prefix ?? "log_", "prefix")}leaves`;
+    }
+    static async ensureSchema(client, prefix = "log_") {
+        const p = ident(prefix, "prefix");
+        await client.query(`CREATE TABLE IF NOT EXISTS ${p}leaves (tenant_id TEXT NOT NULL, seq BIGINT NOT NULL, leaf_hash BYTEA NOT NULL, appended_at TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (tenant_id, seq))`);
+    }
+    init() {
+        if (!this.ready)
+            this.ready = PostgresLog.ensureSchema(this.client, this.leaves.slice(0, -"leaves".length)).then(() => this.reload(this.client.query.bind(this.client)));
+        return this.ready;
+    }
+    /** Replaces the in-memory tree with what the table holds. Called when the table has moved on without this instance. */
+    async reload(q) {
+        const rows = (await q(`SELECT leaf_hash FROM ${this.leaves} WHERE tenant_id = $1 ORDER BY seq`, [this.tenant])).rows;
+        this.hashes = rows.map((r) => (typeof r.leaf_hash === "string" ? Buffer.from(r.leaf_hash.replace(/^\\x/, ""), "hex") : Buffer.from(r.leaf_hash)));
+        this.cache = new SubtreeCache(this.hashes);
+    }
+    async count(q) {
+        return Number((await q(`SELECT COALESCE(MAX(seq) + 1, 0) AS n FROM ${this.leaves} WHERE tenant_id = $1`, [this.tenant])).rows[0].n);
+    }
+    async sync() {
+        await this.init();
+        const n = await this.count(this.client.query.bind(this.client));
+        if (n !== this.hashes.length)
+            await this.reload(this.client.query.bind(this.client));
+    }
+    async size() {
+        await this.sync();
+        return this.hashes.length;
+    }
+    commit(hash) {
+        const run = async () => {
+            await this.init();
+            // One writer per tenant: the advisory lock serialises appends across instances, and the count check inside the
+            // lock catches a tree that another instance has extended, so the in-memory cache is rebuilt before this leaf.
+            await transaction(this.client, async (q) => {
+                await q("SELECT pg_advisory_xact_lock(hashtext($1))", [this.tenant]);
+                const n = await this.count(q);
+                if (n !== this.hashes.length)
+                    await this.reload(q);
+                await q(`INSERT INTO ${this.leaves} (tenant_id, seq, leaf_hash) VALUES ($1, $2, $3)`, [this.tenant, this.hashes.length, hash]);
+            });
+            this.hashes.push(hash);
+            const treeSize = this.hashes.length;
+            return { leafIndex: treeSize - 1, treeSize, hashes: this.cache.path(treeSize - 1, 0, treeSize).map((b) => b.toString("hex")), rootHash: this.cache.mth(0, treeSize).toString("hex") };
+        };
+        const next = this.chain.then(run, run);
+        this.chain = next.catch(() => { });
+        return next;
+    }
+    async append(leaf) {
+        return this.commit(leafHash(leaf));
+    }
+    async appendHash(leafHashHex) {
+        if (!/^[0-9a-f]{64}$/.test(leafHashHex))
+            throw new Error("leafHash must be 64 lowercase hex characters");
+        return this.commit(Buffer.from(leafHashHex, "hex"));
+    }
+    async root(size) {
+        await this.sync();
+        const n = size ?? this.hashes.length;
+        if (n < 0 || n > this.hashes.length)
+            throw new Error("size out of range");
+        return this.cache.mth(0, n).toString("hex");
+    }
+    async consistencyProof(oldSize, newSize) {
+        await this.sync();
+        const n = newSize ?? this.hashes.length;
+        if (oldSize < 0 || oldSize > n || n > this.hashes.length)
+            throw new Error("sizes out of range");
+        if (oldSize === 0 || oldSize === n)
+            return [];
+        return this.cache.subproof(oldSize, 0, n, true).map((b) => b.toString("hex"));
+    }
+}
+const sha256hex = (s) => createHash("sha256").update(s).digest("hex");
+/** Tenants and their tokens, in Postgres. Tokens are stored hashed; a lookup hashes what the caller presented. */
+export class PostgresTenancy {
+    client;
+    prefix;
+    logs = new Map();
+    tenantCache = new Map();
+    tokenCache = new Map();
+    ready = null;
+    constructor(client, opts = {}) {
+        this.client = client;
+        this.prefix = ident(opts.prefix ?? "log_", "prefix");
+    }
+    init() {
+        if (!this.ready) {
+            const p = this.prefix;
+            this.ready = (async () => {
+                await PostgresLog.ensureSchema(this.client, p);
+                await this.client.query(`CREATE TABLE IF NOT EXISTS ${p}tenants (id TEXT PRIMARY KEY, log_id TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), disabled_at TIMESTAMPTZ)`);
+                await this.client.query(`CREATE TABLE IF NOT EXISTS ${p}tokens (token_hash TEXT PRIMARY KEY, tenant_id TEXT NOT NULL REFERENCES ${p}tenants(id), label TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), revoked_at TIMESTAMPTZ)`);
+            })();
+        }
+        return this.ready;
+    }
+    row(r) {
+        return { id: String(r.id), logId: String(r.log_id), createdAt: new Date(r.created_at).toISOString(), disabledAt: r.disabled_at ? new Date(r.disabled_at).toISOString() : null };
+    }
+    /** The tenant, or null. Answers from a ten-second cache, so a disabled tenant is refused within that. */
+    async tenant(id) {
+        await this.init();
+        const hit = this.tenantCache.get(id);
+        if (hit && Date.now() - hit.at < 10_000)
+            return hit.tenant;
+        const rows = (await this.client.query(`SELECT id, log_id, created_at, disabled_at FROM ${this.prefix}tenants WHERE id = $1`, [id])).rows;
+        const tenant = rows[0] ? this.row(rows[0]) : null;
+        this.tenantCache.set(id, { at: Date.now(), tenant });
+        return tenant;
+    }
+    /** Whether the presented token is a live token of this tenant. Positive answers are cached for thirty seconds. */
+    async authorize(tenantId, token) {
+        if (!token)
+            return false;
+        await this.init();
+        const hash = sha256hex(token);
+        const key = `${tenantId}:${hash}`;
+        const at = this.tokenCache.get(key);
+        if (at && Date.now() - at < 30_000)
+            return true;
+        const rows = (await this.client.query(`SELECT 1 FROM ${this.prefix}tokens WHERE token_hash = $1 AND tenant_id = $2 AND revoked_at IS NULL`, [hash, tenantId])).rows;
+        if (rows.length === 0)
+            return false;
+        this.tokenCache.set(key, Date.now());
+        return true;
+    }
+    /** The tenant's log, one instance per tenant per process. */
+    async log(tenantId) {
+        let l = this.logs.get(tenantId);
+        if (!l) {
+            l = new PostgresLog(this.client, tenantId, { prefix: this.prefix });
+            this.logs.set(tenantId, l);
+        }
+        return l;
+    }
+    async addTenant(id, logId = id) {
+        if (!/^[A-Za-z0-9_.-]+$/.test(id))
+            throw new Error(`tenant id must be a plain identifier; got "${id}"`);
+        await this.init();
+        const rows = (await this.client.query(`INSERT INTO ${this.prefix}tenants (id, log_id) VALUES ($1, $2) ON CONFLICT (id) DO UPDATE SET log_id = EXCLUDED.log_id RETURNING id, log_id, created_at, disabled_at`, [id, logId])).rows;
+        this.tenantCache.delete(id);
+        return this.row(rows[0]);
+    }
+    async disableTenant(id) {
+        await this.init();
+        await this.client.query(`UPDATE ${this.prefix}tenants SET disabled_at = now() WHERE id = $1 AND disabled_at IS NULL`, [id]);
+        this.tenantCache.delete(id);
+    }
+    async listTenants() {
+        await this.init();
+        return (await this.client.query(`SELECT id, log_id, created_at, disabled_at FROM ${this.prefix}tenants ORDER BY created_at`)).rows.map((r) => this.row(r));
+    }
+    /** Mints a token for a tenant. The token is returned once and stored only as its hash. */
+    async addToken(tenantId, label) {
+        await this.init();
+        if (!(await this.tenant(tenantId)))
+            throw new Error(`unknown tenant ${tenantId}`);
+        const token = randomBytes(32).toString("hex");
+        const tokenHash = sha256hex(token);
+        await this.client.query(`INSERT INTO ${this.prefix}tokens (token_hash, tenant_id, label) VALUES ($1, $2, $3)`, [tokenHash, tenantId, label]);
+        return { token, tokenHash };
+    }
+    /** Revokes the tokens of a tenant whose hash starts with the prefix; returns how many. */
+    async revokeToken(tenantId, hashPrefix) {
+        await this.init();
+        if (hashPrefix.length < 8)
+            throw new Error("give at least eight characters of the token hash");
+        const rows = (await this.client.query(`UPDATE ${this.prefix}tokens SET revoked_at = now() WHERE tenant_id = $1 AND token_hash LIKE $2 AND revoked_at IS NULL RETURNING token_hash`, [tenantId, `${hashPrefix}%`])).rows;
+        for (const r of rows)
+            this.tokenCache.delete(`${tenantId}:${r.token_hash}`);
+        return rows.length;
+    }
+    async listTokens(tenantId) {
+        await this.init();
+        return (await this.client.query(`SELECT tenant_id, label, token_hash, created_at, revoked_at FROM ${this.prefix}tokens WHERE tenant_id = $1 ORDER BY created_at`, [tenantId])).rows.map((r) => ({ tenantId: String(r.tenant_id), label: String(r.label), tokenHash: String(r.token_hash), createdAt: new Date(r.created_at).toISOString(), revokedAt: r.revoked_at ? new Date(r.revoked_at).toISOString() : null }));
+    }
+}
+/**
+ * Copies a JSONL log file into a backend as hashes: leaf strings are hashed, {pruned} and {hash} lines are taken as
+ * they are. Skips the leaves the backend already has, so it can be re-run. Returns how many were added.
+ */
+export async function importLogFile(file, into) {
+    const lines = readFileSync(file, "utf8").split("\n").filter((l) => l.trim());
+    const have = await into.size();
+    let added = 0;
+    for (let i = have; i < lines.length; i++) {
+        const parsed = JSON.parse(lines[i]);
+        await into.appendHash(typeof parsed === "string" ? leafHash(parsed).toString("hex") : (parsed.pruned ?? parsed.hash));
+        added++;
+    }
+    return { added, total: lines.length };
+}
+/** A token bucket per key, in memory: enough to keep one tenant from crowding out the rest on one instance. */
+export class RateLimiter {
+    perSecond;
+    burst;
+    buckets = new Map();
+    constructor(opts = {}) {
+        this.perSecond = opts.perSecond ?? 50;
+        this.burst = opts.burst ?? 100;
+    }
+    /** Takes one unit for the key; false when the key must wait. */
+    take(key, now = Date.now()) {
+        const b = this.buckets.get(key) ?? { tokens: this.burst, at: now };
+        b.tokens = Math.min(this.burst, b.tokens + ((now - b.at) / 1000) * this.perSecond);
+        b.at = now;
+        if (b.tokens < 1) {
+            this.buckets.set(key, b);
+            return false;
+        }
+        b.tokens -= 1;
+        this.buckets.set(key, b);
+        if (this.buckets.size > 10_000)
+            for (const [k, v] of this.buckets)
+                if (now - v.at > 60_000)
+                    this.buckets.delete(k);
+        return true;
+    }
+}

package/dist/log.d.ts

@@ -4,6 +4,19 @@ export interface InclusionProof {
     hashes: string[];
 }
 export declare function leafHash(data: string): Buffer;
+/**
+ * Subtree hashes over a growing list of leaves. A subtree over an aligned, complete, power-of-two range never changes
+ * once its leaves exist, so those are cached; everything else is recomputed from at most log(n) cached parts. That
+ * makes appends, roots, and proofs O(log n) instead of O(n), which is what keeps a long session's receipts cheap.
+ */
+export declare class SubtreeCache {
+    private readonly perfect;
+    private readonly leaves;
+    constructor(leaves: Buffer[]);
+    mth(lo: number, hi: number): Buffer;
+    path(m: number, lo: number, hi: number): Buffer[];
+    subproof(m: number, lo: number, hi: number, b: boolean): Buffer[];
+}
 /** Proof that the tree of size newSize extends the tree of size oldSize. Empty when oldSize is 0 or equal to newSize. */
 export declare function consistencyProof(leafHashes: Buffer[], oldSize: number, newSize?: number): string[];
 /** RFC 9162 section 2.1.4.2. Pure: needs only the two sizes, the two roots, and the proof. */

package/dist/log.js

@@ -25,7 +25,7 @@ function split(n) {
  * once its leaves exist, so those are cached; everything else is recomputed from at most log(n) cached parts. That
  * makes appends, roots, and proofs O(log n) instead of O(n), which is what keeps a long session's receipts cheap.
  */
-class SubtreeCache {
+export class SubtreeCache {
     perfect = new Map();
     leaves;
     constructor(leaves) {

package/dist/signer.d.ts

@@ -0,0 +1,64 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import { type Envelope, type KeyPair, type PublicKeyRef } from "./crypto.ts";
+/** What a log publishes about its keys. Verifiers pin by keyid; retired keys stay listed so old heads keep verifying. */
+export interface KeyDocument {
+    /** the id of the log served at the root paths, when it has one */
+    log?: string;
+    keys: {
+        keyid: string;
+        alg: "ed25519";
+        publicKeyPem: string;
+        validFrom: string;
+        validTo?: string;
+    }[];
+}
+export interface Signer {
+    readonly keyid: string;
+    sign(payloadType: string, payload: unknown): Promise<Envelope>;
+    keys(): Promise<KeyDocument>;
+}
+export interface RetiredKey {
+    key: PublicKeyRef;
+    pem: string;
+    validFrom?: string;
+    validTo?: string;
+}
+/** A key held in this process. `retired` keys are listed in the document, never used to sign. */
+export declare function localSigner(kp: KeyPair, opts?: {
+    retired?: RetiredKey[];
+    validFrom?: string;
+}): Signer;
+export interface RemoteSignerOptions {
+    /** the shared secret the signer requires */
+    token?: string;
+    fetch?: typeof fetch;
+}
+/** The signer over HTTP. Fetches the key document once to learn the keyid, then signs through POST /sign. */
+export declare function connectSigner(url: string, opts?: RemoteSignerOptions): Promise<Signer>;
+export interface SignerServerOptions {
+    /** the shared secret; without one, anyone who can reach the port may sign, so bind to loopback or a private network */
+    token?: string;
+    retired?: RetiredKey[];
+    validFrom?: string;
+}
+/**
+ * The signer as a node:http handler.
+ *   POST /sign  {payloadType, payload}  -> DSSE envelope     (token required when one is configured)
+ *   GET  /keys                          -> KeyDocument
+ *   GET  /health                        -> {keyid}
+ */
+export declare function signerHandler(kp: KeyPair, opts?: SignerServerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface RunningSigner {
+    url: string;
+    keyid: string;
+    close(): Promise<void>;
+}
+export declare function serveSigner(kp: KeyPair, opts: SignerServerOptions & {
+    port: number;
+    host?: string;
+}): Promise<RunningSigner>;
+/** For verifiers: the keys a log publishes, fetched from its origin and returned as key references pinned by keyid. */
+export declare function fetchLogKeys(logUrl: string, f?: typeof fetch): Promise<{
+    doc: KeyDocument;
+    keys: PublicKeyRef[];
+}>;

package/dist/signer.js

@@ -0,0 +1,136 @@
+// The signer: the one process that holds the log's key. The log server asks it to sign tree heads over a private
+// HTTP call with a shared secret, so the key never sits in the process that faces the internet, and the same key
+// document it serves is what the log publishes at /.well-known/agent-custody-log.json for verifiers to pin.
+// A local signer wraps a key in-process for the reference server and for tests; both look the same to the handler.
+import { timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { dsseSign, publicKeyFromPem } from "./crypto.js";
+const pemOf = (k) => k.publicKey.export({ type: "spki", format: "pem" });
+/** A key held in this process. `retired` keys are listed in the document, never used to sign. */
+export function localSigner(kp, opts = {}) {
+    const validFrom = opts.validFrom ?? new Date().toISOString();
+    const doc = {
+        keys: [
+            { keyid: kp.keyid, alg: "ed25519", publicKeyPem: pemOf(kp), validFrom },
+            ...(opts.retired ?? []).map((r) => ({ keyid: r.key.keyid, alg: "ed25519", publicKeyPem: r.pem, validFrom: r.validFrom ?? "1970-01-01T00:00:00.000Z", ...(r.validTo ? { validTo: r.validTo } : {}) })),
+        ],
+    };
+    return {
+        keyid: kp.keyid,
+        async sign(payloadType, payload) {
+            return dsseSign(payloadType, payload, kp);
+        },
+        async keys() {
+            return structuredClone(doc);
+        },
+    };
+}
+/** The signer over HTTP. Fetches the key document once to learn the keyid, then signs through POST /sign. */
+export async function connectSigner(url, opts = {}) {
+    const f = opts.fetch ?? fetch;
+    const base = url.endsWith("/") ? url : `${url}/`;
+    const headers = { "content-type": "application/json", ...(opts.token ? { authorization: `Bearer ${opts.token}` } : {}) };
+    const res = await f(new URL("keys", base), { headers });
+    if (!res.ok)
+        throw new Error(`signer ${url} refused the key request: ${res.status}`);
+    const doc = (await res.json());
+    const current = doc.keys[0];
+    if (!current)
+        throw new Error(`signer ${url} lists no key`);
+    return {
+        keyid: current.keyid,
+        async sign(payloadType, payload) {
+            const r = await f(new URL("sign", base), { method: "POST", headers, body: JSON.stringify({ payloadType, payload }), signal: AbortSignal.timeout(5000) });
+            if (!r.ok)
+                throw new Error(`signer ${url} refused to sign: ${r.status} ${(await r.text()).slice(0, 200)}`);
+            const env = (await r.json());
+            if (typeof env.payload !== "string" || !Array.isArray(env.signatures))
+                throw new Error(`signer ${url} returned a malformed envelope`);
+            return env;
+        },
+        async keys() {
+            const k = await f(new URL("keys", base), { headers });
+            if (!k.ok)
+                throw new Error(`signer ${url} refused the key request: ${k.status}`);
+            return (await k.json());
+        },
+    };
+}
+/**
+ * The signer as a node:http handler.
+ *   POST /sign  {payloadType, payload}  -> DSSE envelope     (token required when one is configured)
+ *   GET  /keys                          -> KeyDocument
+ *   GET  /health                        -> {keyid}
+ */
+export function signerHandler(kp, opts = {}) {
+    const signer = localSigner(kp, opts);
+    const authorized = (req) => {
+        if (!opts.token)
+            return true;
+        const h = req.headers.authorization ?? "";
+        const given = Buffer.from(h.startsWith("Bearer ") ? h.slice(7) : "");
+        const want = Buffer.from(opts.token);
+        return want.length === given.length && timingSafeEqual(want, given);
+    };
+    return async (req, res) => {
+        const json = (status, body) => {
+            res.writeHead(status, { "content-type": "application/json" });
+            res.end(JSON.stringify(body));
+        };
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (req.method === "GET" && url.pathname === "/health")
+            return json(200, { keyid: kp.keyid });
+        if (req.method === "GET" && url.pathname === "/keys")
+            return json(200, await signer.keys());
+        if (req.method === "POST" && url.pathname === "/sign") {
+            if (!authorized(req))
+                return json(401, { error: "unauthorized" });
+            let body = "";
+            for await (const chunk of req) {
+                body += chunk;
+                if (body.length > 65_536)
+                    return json(413, { error: "payload too large" });
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                return json(400, { error: "body must be JSON {payloadType, payload}" });
+            }
+            if (typeof parsed.payloadType !== "string" || parsed.payload === undefined)
+                return json(400, { error: "body must be JSON {payloadType, payload}" });
+            return json(200, await signer.sign(parsed.payloadType, parsed.payload));
+        }
+        return json(404, { error: "not found" });
+    };
+}
+export function serveSigner(kp, opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const handler = signerHandler(kp, opts);
+    const server = createServer((req, res) => {
+        void handler(req, res);
+    });
+    return new Promise((resolve) => {
+        server.listen(opts.port, host, () => {
+            const { port } = server.address();
+            resolve({ url: `http://${host}:${port}/`, keyid: kp.keyid, close: () => new Promise((r) => server.close(() => r())) });
+        });
+    });
+}
+/** For verifiers: the keys a log publishes, fetched from its origin and returned as key references pinned by keyid. */
+export async function fetchLogKeys(logUrl, f = fetch) {
+    const res = await f(new URL("/.well-known/agent-custody-log.json", logUrl));
+    if (!res.ok)
+        throw new Error(`log ${logUrl} serves no key document: ${res.status}`);
+    const doc = (await res.json());
+    if (!Array.isArray(doc.keys) || doc.keys.length === 0)
+        throw new Error(`log ${logUrl} lists no keys`);
+    const keys = doc.keys.map((k) => {
+        const ref = publicKeyFromPem(k.publicKeyPem);
+        if (ref.keyid !== k.keyid)
+            throw new Error(`log ${logUrl} lists key ${k.keyid.slice(0, 12)} whose pem has keyid ${ref.keyid.slice(0, 12)}`);
+        return ref;
+    });
+    return { doc, 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. [deploy/](../../deploy/README.md) runs the server as a container.
+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/docs/verification.md

@@ -161,7 +161,9 @@ An inclusion proof says a receipt was in the log at one moment. It does not say
 
 ```bash
 node src/cli.ts audit --older receipts/<earlier>.json --newer receipts/<later>.json --log log.jsonl --issuer-key keys/gateway.pub
-node src/cli.ts audit --older receipts/<earlier>.json --newer receipts/<later>.json --log-url https://log.example.com/t/acme/ --log-key keys/log.pub --log-id acme
+node src/cli.ts audit --older receipts/<earlier>.json --newer receipts/<later>.json --log-url https://log.example.com/t/acme/ --log-id acme
+
+`--log-url` also fetches the log's published keys from `/.well-known/agent-custody-log.json` and pins them by keyid, so no key file changes hands; `--log-key` still works for a key you were handed. The same flag on `verify` does the same for a receipt.
 ```
 
 Both tree heads must be signed by a trusted key. With `--log` the proof is computed from a copy of the log; with `--log-url` it is fetched from the log's `GET /consistency?old=M&new=N`. Exit code 0 means the newer log extends the older one. A failure means either history was rewritten between the two heads or the proof belongs to other tree heads; example 14 shows a rewritten log failing this way while every individual receipt still verifies.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.4.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": {
@@ -72,12 +72,14 @@
     "ai": "^7.0.92",
     "tsx": "^4.23.13",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.0",
+    "@electric-sql/pglite": "0.5.8"
   },
   "peerDependencies": {
     "@langchain/core": ">=1.0.0",
     "@openai/agents": ">=0.1.0",
-    "ai": ">=5.0.0"
+    "ai": ">=5.0.0",
+    "pg": ">=8"
   },
   "peerDependenciesMeta": {
     "@langchain/core": {
@@ -88,6 +90,9 @@
     },
     "ai": {
       "optional": true
+    },
+    "pg": {
+      "optional": true
     }
   }
 }