@agent-custody/receipts 0.6.0 → 0.6.2

package/README.md

@@ -9,7 +9,8 @@ Two producers, one receipt format, one verifier.
 
 Anyone holding the public keys can verify a receipt offline. The agent is not trusted. The layer around it is, and the receipt says exactly how far that trust extends, starting with who issued it.
 
-- [Tutorials](docs/tutorials.md): eighteen runnable examples, one per aspect of the code, all executed by the test suite
+- [Reference](https://docs.agent-custody.dev/reference/): every function, endpoint, MCP tool, and command with its request and response
+- [Tutorials](docs/tutorials.md): twenty runnable examples, one per aspect of the code, all executed by the test suite
 - [Usage guide](docs/usage.md): gateway setup, wiring into Claude Desktop, Claude Code, or your own agent loop
 - [The interceptor SDK](docs/sdk.md): Claude Code hooks, the Claude Agent SDK, adapters for the OpenAI Agents SDK, Vercel AI SDK and LangChain, and wrapping tool functions in anything else
 - [Writing policies](docs/policies.md): how a tool call becomes a Cedar request, with tested examples
@@ -228,6 +229,7 @@ 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/log-check.ts   the outside monitor: verifies the head, checkpoints, and witness of a running log
+src/portal.ts      the tenant portal: register, first key, usage against plan, keys, Stripe billing, export, on the log's Postgres
 src/log-export.ts  a tenant's export of their own log, self-checked, as a log file the verifier reads
 src/witness.ts     the witness: countersigns the log's checkpoints from another operator's machine, or refuses with an alarm
 src/signer.ts      the signer: the log's key in its own process, the key document verifiers fetch
@@ -287,6 +289,7 @@ 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).
 
+- Plans and the tenant portal: every tenant is on a plan (free, ten thousand appends a month; team, a million; enterprise, no allowance) enforced at append with a clear 429; the portal at the operator's `PORTAL_HOST` lets a team register, get its tenant and first key, watch usage against the plan, mint and revoke keys, buy the team plan through Stripe, and copy the export command, with every action in the audit trail.
 - An audit trail of administrative actions: every tenant created or disabled and every token minted or revoked is recorded with who did it, from the admin page or the command line, shown on the page and carried in the tenant's export.
 - A tenant's export: `log-export` takes, with the tenant's own token, every leaf hash, the signed head, the published keys, the checkpoints, and their usage, checks that they add up, and writes a log copy the verifier reads offline; the evidence never depends on the operator staying in business.
 - Monitoring and metering: `log-check`, the outside probe that verifies the head, the checkpoints, and the witness and exits 1 on trouble, run every ten minutes by the `monitor` workflow; `GET /health`; and usage per tenant per month on the admin page and as CSV.

package/dist/cli.js

@@ -14,6 +14,7 @@ import { connectSigner, fetchLogKeys, localSigner, serveSigner } from "./signer.
 import { fetchWitnessKeys, Witness } from "./witness.js";
 import { checkLog, formatLogCheck } from "./log-check.js";
 import { serveHttp } from "./gateway-http.js";
+import { servePortal } from "./portal.js";
 import { exportLog, formatExport } from "./log-export.js";
 import { CheckpointPublisher, fileResolver } from "./log-sink.js";
 import { createRequire } from "node:module";
@@ -53,7 +54,8 @@ const USAGE = `agent-custody <command>
                                                  sign with a key in this process, or through a signer process that holds it; publish a signed
                                                  checkpoint per log that has grown, every 300 s by default, to the directory (and, with a
                                                  database, to its heads table); serve the key document at /.well-known/agent-custody-log.json
-  log     ... [--trust-proxy]                    behind a reverse proxy you run: key per-address limits by X-Forwarded-For
+  log     ... [--trust-proxy]                    behind a reverse proxy you run: key per-address limits by the address the proxy appended
+  log     ... [--hash-only]                      accept only leaf hashes on append; a log run for other people must never receive a receipt
   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
@@ -70,9 +72,12 @@ const USAGE = `agent-custody <command>
                                                  into <dir>; refuses and writes an alarm otherwise. Serve <dir> from a host of your own.
   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 tenant add <id> [--log-id <id>] | tenant list | tenant disable <id> | tenant plan <id> <free|team|enterprise>
   log-admin --db-env NAME token add <tenant> --label <text> | token list <tenant> | token revoke <tenant> <hash-prefix>
   log-admin --db-env NAME audit [--tenant <id>]   who did what to tenants and tokens, newest first
+  portal  --db-env NAME --secret-env NAME --public-url <log url> [--checkpoints-url <url>] [--portal-url <url>] [--port 8792] [--host 127.0.0.1]
+          [--stripe-key-env NAME --stripe-webhook-env NAME --stripe-price-team <price id>] [--trust-proxy]
+                                                   the tenant portal: register, first key, usage against plan, keys, billing, export
   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>] [--witness-key <pub> | --witness-url <url>] [--json]
                                                  with --log-url the log's published keys are fetched and pinned by keyid; with a witness key or
@@ -261,6 +266,38 @@ async function main(argv) {
             await running.close();
             return 0;
         }
+        case "portal": {
+            const { values } = parseArgs({ args: rest, options: { "db-env": { type: "string" }, "secret-env": { type: "string" }, "public-url": { type: "string" }, "checkpoints-url": { type: "string" }, "portal-url": { type: "string" }, port: { type: "string", default: "8792" }, host: { type: "string", default: "127.0.0.1" }, "stripe-key-env": { type: "string" }, "stripe-webhook-env": { type: "string" }, "stripe-price-team": { type: "string" }, "trust-proxy": { type: "boolean", default: false } } });
+            if (!values["db-env"] || !values["secret-env"] || !values["public-url"])
+                throw new Error("portal needs --db-env, --secret-env, and --public-url");
+            const secret = process.env[values["secret-env"]];
+            if (!secret || secret.length < 32)
+                throw new Error(`environment variable ${values["secret-env"]} must hold a secret of at least 32 characters`);
+            let stripe;
+            if (values["stripe-key-env"] || values["stripe-webhook-env"] || values["stripe-price-team"]) {
+                if (!values["stripe-key-env"] || !values["stripe-webhook-env"] || !values["stripe-price-team"])
+                    throw new Error("billing needs all three of --stripe-key-env, --stripe-webhook-env, --stripe-price-team");
+                const secretKey = process.env[values["stripe-key-env"]];
+                const webhookSecret = process.env[values["stripe-webhook-env"]];
+                if (!secretKey || !webhookSecret)
+                    throw new Error("the Stripe key and webhook secret variables must both be set");
+                stripe = { secretKey, webhookSecret, priceTeam: values["stripe-price-team"] };
+            }
+            const client = openPostgres(values["db-env"]);
+            const tenancy = new PostgresTenancy(client);
+            let keyid;
+            try {
+                keyid = (await fetchLogKeys(values["public-url"])).keys[0]?.keyid;
+            }
+            catch {
+                // the log may not be reachable from here at start; the sheet then omits the keyid
+            }
+            const running = await servePortal({ tenancy, client, secret, publicUrl: values["public-url"], ...(values["checkpoints-url"] ? { checkpointsUrl: values["checkpoints-url"] } : {}), ...(values["portal-url"] ? { portalUrl: values["portal-url"] } : {}), ...(keyid ? { keyid } : {}), ...(stripe ? { stripe } : {}), trustProxy: values["trust-proxy"] }, { port: Number(values.port), host: values.host });
+            console.error(`agent-custody portal: ${running.url} log=${values["public-url"]} billing=${stripe ? "stripe" : "off"}${values["trust-proxy"] ? " trust-proxy" : ""}`);
+            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"])
@@ -274,7 +311,11 @@ async function main(argv) {
             }
             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}` : ""}`);
+                    console.log(`${t.id.padEnd(24)} log=${t.logId.padEnd(28)} plan=${t.plan.padEnd(10)} created ${t.createdAt}${t.disabledAt ? `  DISABLED ${t.disabledAt}` : ""}`);
+            }
+            else if (what === "tenant" && verb === "plan" && args[0] && args[1]) {
+                const t = await tenancy.setPlan(args[0], args[1], actor);
+                console.log(`tenant ${t.id} on plan ${t.plan}`);
             }
             else if (what === "tenant" && verb === "disable" && args[0]) {
                 await tenancy.disableTenant(args[0], actor);
@@ -325,7 +366,7 @@ async function main(argv) {
         case "log": {
             const { values } = parseArgs({
                 args: rest,
-                options: { file: { type: "string" }, key: { type: "string" }, port: { type: "string", default: "8787" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" }, "log-id": { type: "string" }, tenants: { type: "string" }, "db-env": { type: "string" }, "signer-url": { type: "string" }, "signer-token-env": { type: "string" }, "retired-key": { type: "string", multiple: true }, "checkpoint-dir": { type: "string" }, "checkpoint-every": { type: "string", default: "300" }, "checkpoint-heartbeat": { type: "string", default: "21600" }, "admin-token-env": { type: "string" }, "public-url": { type: "string" }, "checkpoints-url": { type: "string" }, "trust-proxy": { type: "boolean", default: false } },
+                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" }, "checkpoint-heartbeat": { type: "string", default: "21600" }, "admin-token-env": { type: "string" }, "public-url": { type: "string" }, "checkpoints-url": { type: "string" }, "trust-proxy": { type: "boolean", default: false }, "hash-only": { type: "boolean", default: false } },
             });
             if (!values.key === !values["signer-url"])
                 throw new Error("log needs exactly one of --key or --signer-url");
@@ -380,7 +421,7 @@ async function main(argv) {
                 resolver = fileResolver(values.file, { ...(token ? { tokens: [token] } : {}), ...(values["log-id"] ? { logId: values["log-id"] } : {}), ...(tenants ? { tenants } : {}) });
                 where = `file=${values.file}${values["log-id"] ? ` log=${values["log-id"]}` : ""} ${token ? "bearer token required" : "open, anyone may append"}${tenants ? ` tenants=${Object.keys(tenants).join(",")}` : ""}`;
             }
-            const running = await serveLog(resolver, signer, { port: Number(values.port), host: values.host, ...(checkpoints ? { checkpoints } : {}), ...(admin ? { admin } : {}), trustProxy: values["trust-proxy"] });
+            const running = await serveLog(resolver, signer, { port: Number(values.port), host: values.host, ...(checkpoints ? { checkpoints } : {}), ...(admin ? { admin } : {}), trustProxy: values["trust-proxy"], hashOnly: values["hash-only"] });
             const publisher = checkpoints ? new CheckpointPublisher(resolver, signer, checkpoints, everyMs, undefined, heartbeatMs) : 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" : ""}`);

package/dist/delegation.d.ts

@@ -30,6 +30,8 @@ export interface SubDelegation {
     /** the sub-agent's own public key, so it may delegate further */
     agentKey?: string;
 }
+/** True when the envelope's payload, verified or not, carries a parent: what decides whether the chain check is reported. */
+export declare function delegationHasParent(env: Envelope): boolean;
 /** The parent's payload as written, without verifying it; the verifier does that. */
 export declare function decodeDelegation(env: Envelope): Delegation | null;
 /**

package/dist/delegation.js

@@ -16,8 +16,8 @@ export const DelegationSchema = z.object({
     principal: z.string().min(1),
     agent: z.string().min(1),
     scopes: z.array(z.string().min(1)).min(1),
-    issuedAt: z.iso.datetime(),
-    expiresAt: z.iso.datetime(),
+    issuedAt: z.iso.datetime({ offset: true }),
+    expiresAt: z.iso.datetime({ offset: true }),
     /** the agent's own public key, SPKI PEM; with it the agent may delegate to a sub-agent */
     agentKey: z.string().min(1).optional(),
     /** the grant this one was delegated from; the chain ends at a grant signed by a trusted principal */
@@ -26,6 +26,16 @@ export const DelegationSchema = z.object({
 export function createDelegation(principalKey, d) {
     return dsseSign(DELEGATION_TYPE, DelegationSchema.parse(d), principalKey);
 }
+/** True when the envelope's payload, verified or not, carries a parent: what decides whether the chain check is reported. */
+export function delegationHasParent(env) {
+    try {
+        const raw = JSON.parse(Buffer.from(env.payload, "base64").toString("utf8"));
+        return !!raw && typeof raw === "object" && raw.parent !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
 /** The parent's payload as written, without verifying it; the verifier does that. */
 export function decodeDelegation(env) {
     try {

package/dist/gateway.d.ts

@@ -26,6 +26,12 @@ export interface Gateway {
     handleCall(params: CallParams): Promise<CallToolResult>;
     close(): Promise<void>;
 }
+/**
+ * The environment a stdio upstream is started with: what a child process needs to run, plus what the config names.
+ * Never the gateway's own environment, which holds the tokens other upstreams and the log are given. An explicit
+ * `env` in the config is added to this base, not to the gateway's variables.
+ */
+export declare function upstreamEnv(extra?: Record<string, string>): Record<string, string>;
 export interface GatewayOptions {
     /** the log to append to, in place of the one the config names; for embedding and tests */
     log?: LogSink;

package/dist/gateway.js

@@ -57,6 +57,20 @@ function extractValue(result) {
         return text.text;
     }
 }
+/**
+ * The environment a stdio upstream is started with: what a child process needs to run, plus what the config names.
+ * Never the gateway's own environment, which holds the tokens other upstreams and the log are given. An explicit
+ * `env` in the config is added to this base, not to the gateway's variables.
+ */
+export function upstreamEnv(extra) {
+    const base = {};
+    for (const k of ["PATH", "HOME", "TMPDIR", "TEMP", "TMP", "LANG", "LC_ALL", "SystemRoot", "SYSTEMROOT", "USERPROFILE", "APPDATA", "NODE_OPTIONS"]) {
+        const v = process.env[k];
+        if (v !== undefined)
+            base[k] = v;
+    }
+    return { ...base, ...(extra ?? {}) };
+}
 export async function createGatewayHost(cfg, options = {}) {
     const gatewayKey = loadPrivateKey(cfg.identity.keyFile);
     const trusted = cfg.trustedPrincipalKeys.map(loadPublicKey);
@@ -65,6 +79,13 @@ export async function createGatewayHost(cfg, options = {}) {
     const issuer = createIssuer(gatewayKey, cfg.receiptsDir, options.log ?? openLog(cfg, gatewayKey), { exporter: options.exporter ?? openExporter(cfg) });
     const precommit = new Set(cfg.precommit);
     const consequential = (tool) => precommit.has("*") || precommit.has(tool);
+    // A fact lookup runs before the policy can decide, because the policy decides on it. It is therefore a read the
+    // gateway makes on the agent's request, never a consequential call: a fact tool named in precommit is a config error.
+    // "*" covers the tools the agent calls; a lookup is the gateway's own read, so only an explicit name makes it consequential.
+    for (const f of cfg.facts) {
+        if (precommit.has(f.tool))
+            throw new Error(`fact "${f.name}" uses tool ${f.tool}, which precommit names as consequential; a fact lookup runs before the policy decides and must be a read`);
+    }
     // One host, as many upstreams as the agents' jobs need. Each tool name belongs to exactly one upstream, decided at
     // startup, so a receipt's tool is unambiguous and consumed facts flow across them.
     const upstreamConfigs = cfg.upstreams ? cfg.upstreams.map((u) => ({ name: u.name, cfg: u })) : [{ name: "upstream", cfg: cfg.upstream }];
@@ -85,7 +106,7 @@ export async function createGatewayHost(cfg, options = {}) {
         }
         else {
             client = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
-            await client.connect(new StdioClientTransport({ command: u.command, args: u.args, env: u.env, stderr: "inherit" }));
+            await client.connect(new StdioClientTransport({ command: u.command, args: u.args, env: upstreamEnv(u.env), stderr: "inherit" }));
         }
         upstreams.set(name, client);
         const { tools } = await client.listTools();

package/dist/index.d.ts

@@ -5,11 +5,14 @@ export { buildRequest, restUpstream } from "./rest.ts";
 export { openExporter, otlpExporter, spanFor } from "./otel.ts";
 export { hecEvent, splunkExporter } from "./splunk.ts";
 export { GRANT_HEADER, grantHeader, parseGrantHeader, serveHttp } from "./gateway-http.ts";
+export { PortalStore, portalHandler, readSession, servePortal, signSession, stripeRequest, verifyStripeSignature } from "./portal.ts";
+export type { PortalOptions, PortalUser, RunningPortal, StripeOptions } from "./portal.ts";
 export type { HttpGatewayOptions, RunningHttpGateway } from "./gateway-http.ts";
 export { exportLog, formatExport } from "./log-export.ts";
 export type { ExportOptions, ExportResult } from "./log-export.ts";
 export { fileBackend, importLogFile, PostgresLog, PostgresTenancy, RateLimiter } from "./log-store.ts";
-export type { AuditEntry } from "./log-store.ts";
+export type { AuditEntry, Plan, QuotaState } from "./log-store.ts";
+export { PLAN_QUOTAS, PLANS } 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";

package/dist/index.js

@@ -4,8 +4,10 @@ export { buildRequest, restUpstream } from "./rest.js";
 export { openExporter, otlpExporter, spanFor } from "./otel.js";
 export { hecEvent, splunkExporter } from "./splunk.js";
 export { GRANT_HEADER, grantHeader, parseGrantHeader, serveHttp } from "./gateway-http.js";
+export { PortalStore, portalHandler, readSession, servePortal, signSession, stripeRequest, verifyStripeSignature } from "./portal.js";
 export { exportLog, formatExport } from "./log-export.js";
 export { fileBackend, importLogFile, PostgresLog, PostgresTenancy, RateLimiter } from "./log-store.js";
+export { PLAN_QUOTAS, PLANS } 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";

package/dist/log-admin.js

@@ -5,7 +5,7 @@
 // throttled. A minted token is shown once, beside the welcome sheet the tenant gets. Nothing here touches
 // receipts; the log holds hashes and the panel holds names.
 import { timingSafeEqual } from "node:crypto";
-import { RateLimiter } from "./log-store.js";
+import { RateLimiter, PLANS } from "./log-store.js";
 import { clientAddress } from "./log-sink.js";
 const same = (a, b) => {
     const x = Buffer.from(a);
@@ -114,7 +114,7 @@ export function adminRoutes(opts) {
             }
             else if (req.method === "GET" && parts.length === 2 && parts[1] === "usage.csv") {
                 const u = await t.usage(month);
-                const csv = ["month,tenant,log_id,appends,total_leaves,live_tokens,disabled", ...u.tenants.map((x) => [u.month, x.id, x.logId, x.appends, x.totalLeaves, x.liveTokens, x.disabled].join(","))].join("\n") + "\n";
+                const csv = ["month,tenant,log_id,plan,quota,appends,total_leaves,live_tokens,disabled", ...u.tenants.map((x) => [u.month, x.id, x.logId, x.plan, x.quota ?? "", x.appends, x.totalLeaves, x.liveTokens, x.disabled].join(","))].join("\n") + "\n";
                 res.writeHead(200, { "content-type": "text/csv; charset=utf-8", "content-disposition": `attachment; filename="agent-custody-usage-${u.month}.csv"`, "cache-control": "no-store" });
                 res.end(csv);
             }
@@ -138,6 +138,12 @@ export function adminRoutes(opts) {
                     return json(400, { error: "id must be a plain identifier" }), true;
                 json(200, await t.addTenant(b.id, typeof b.logId === "string" && b.logId ? b.logId : b.id, actor));
             }
+            else if (req.method === "POST" && parts.length === 4 && parts[1] === "tenants" && parts[3] === "plan") {
+                const b = await body();
+                if (typeof b.plan !== "string" || !PLANS.includes(b.plan))
+                    return json(400, { error: `plan must be one of ${PLANS.join(", ")}` }), true;
+                json(200, await t.setPlan(parts[2], b.plan, actor));
+            }
             else if (req.method === "POST" && parts.length === 4 && parts[1] === "tenants" && parts[3] === "disable") {
                 await t.disableTenant(parts[2], actor);
                 json(200, { disabled: parts[2] });
@@ -200,7 +206,7 @@ const ADMIN_PAGE = `<!doctype html>
   <p class="sub" id="where">Tenants and tokens on this log.</p>
   <section id="app">
     <h2>Tenants</h2>
-    <table><thead><tr><th>tenant</th><th>log id</th><th>live tokens</th><th>created</th><th></th></tr></thead><tbody id="tenants"></tbody></table>
+    <table><thead><tr><th>tenant</th><th>log id</th><th>plan</th><th>live tokens</th><th>created</th><th></th></tr></thead><tbody id="tenants"></tbody></table>
     <h2>New tenant</h2>
     <div class="row">
       <label>tenant id (in the URL)<input id="tid" placeholder="acme" autocomplete="off"></label>
@@ -221,7 +227,7 @@ const ADMIN_PAGE = `<!doctype html>
     </div>
     <h2>Usage</h2>
     <div class="row"><label>month<input id="month" type="month"></label><button class="quiet" id="loadUsage">Show</button><a id="csv" class="quiet" href="#" style="align-self:center">Download CSV</a></div>
-    <table><thead><tr><th>tenant</th><th>log id</th><th>appends this month</th><th>leaves in total</th><th>live tokens</th></tr></thead><tbody id="usage"></tbody></table>
+    <table><thead><tr><th>tenant</th><th>log id</th><th>plan</th><th>appends this month</th><th>quota</th><th>leaves in total</th><th>live tokens</th></tr></thead><tbody id="usage"></tbody></table>
     <h2>Tokens of a tenant</h2>
     <div class="row"><label>tenant<input id="ltid" placeholder="acme" autocomplete="off"></label><button class="quiet" id="listTokens">List</button></div>
     <table><thead><tr><th>label</th><th>hash</th><th>created</th><th>state</th><th></th></tr></thead><tbody id="tokens"></tbody></table>
@@ -246,7 +252,8 @@ const ADMIN_PAGE = `<!doctype html>
   const say = (t, cls) => { $("msg").textContent = t; $("msg").className = cls || "muted"; };
   const loadTenants = async () => {
     const list = await api("GET", "/admin/tenants");
-    $("tenants").innerHTML = list.map((t) => "<tr><td><code>" + esc(t.id) + "</code></td><td><code>" + esc(t.logId) + "</code></td><td>" + t.tokens + "</td><td>" + esc(t.createdAt.slice(0, 10)) + "</td><td>" + (t.disabledAt ? "<span class=muted>disabled</span>" : "<button class=quiet data-disable=\\"" + esc(t.id) + "\\">Disable</button>") + "</td></tr>").join("") || "<tr><td colspan=5 class=muted>none yet</td></tr>";
+    const planPick = (t) => "<select data-plan=\\"" + esc(t.id) + "\\">" + ["free", "team", "enterprise"].map((p) => "<option" + (p === t.plan ? " selected" : "") + ">" + p + "</option>").join("") + "</select>";
+    $("tenants").innerHTML = list.map((t) => "<tr><td><code>" + esc(t.id) + "</code></td><td><code>" + esc(t.logId) + "</code></td><td>" + planPick(t) + "</td><td>" + t.tokens + "</td><td>" + esc(t.createdAt.slice(0, 10)) + "</td><td>" + (t.disabledAt ? "<span class=muted>disabled</span>" : "<button class=quiet data-disable=\\"" + esc(t.id) + "\\">Disable</button>") + "</td></tr>").join("") || "<tr><td colspan=6 class=muted>none yet</td></tr>";
   };
   const loadTokens = async (id) => {
     const list = await api("GET", "/admin/tenants/" + encodeURIComponent(id) + "/tokens");
@@ -278,7 +285,7 @@ const ADMIN_PAGE = `<!doctype html>
     const month = $("month").value || new Date().toISOString().slice(0, 7);
     const u = await api("GET", "/admin/usage?month=" + encodeURIComponent(month));
     $("csv").href = "/admin/usage.csv?month=" + encodeURIComponent(month);
-    $("usage").innerHTML = u.tenants.map((t) => "<tr><td><code>" + esc(t.id) + "</code>" + (t.disabled ? " <span class=muted>disabled</span>" : "") + "</td><td><code>" + esc(t.logId) + "</code></td><td>" + t.appends + "</td><td>" + t.totalLeaves + "</td><td>" + t.liveTokens + "</td></tr>").join("") || "<tr><td colspan=5 class=muted>no tenants</td></tr>";
+    $("usage").innerHTML = u.tenants.map((t) => "<tr><td><code>" + esc(t.id) + "</code>" + (t.disabled ? " <span class=muted>disabled</span>" : "") + "</td><td><code>" + esc(t.logId) + "</code></td><td>" + esc(t.plan) + "</td><td>" + t.appends + "</td><td>" + (t.quota === null ? "none" : t.quota) + "</td><td>" + t.totalLeaves + "</td><td>" + t.liveTokens + "</td></tr>").join("") || "<tr><td colspan=7 class=muted>no tenants</td></tr>";
   };
   const loadAudit = async () => {
     const a = await api("GET", "/admin/audit?limit=100");
@@ -286,6 +293,10 @@ const ADMIN_PAGE = `<!doctype html>
   };
   $("loadUsage").onclick = () => loadUsage().catch((e) => say(e.message, "err"));
   $("month").value = new Date().toISOString().slice(0, 7);
+  document.addEventListener("change", async (e) => {
+    const s = e.target.closest("select[data-plan]"); if (!s) return;
+    try { await api("POST", "/admin/tenants/" + encodeURIComponent(s.dataset.plan) + "/plan", { plan: s.value }); say("plan of " + s.dataset.plan + " set to " + s.value, "ok"); await loadUsage(); await loadAudit(); } catch (err) { say(err.message, "err"); await loadTenants(); }
+  });
   document.addEventListener("click", async (e) => {
     const b = e.target.closest("button"); if (!b) return;
     if (b.dataset.disable && confirm("Disable tenant " + b.dataset.disable + "? Its paths answer 404 within ten seconds.")) { try { await api("POST", "/admin/tenants/" + encodeURIComponent(b.dataset.disable) + "/disable"); await loadTenants(); await loadAudit(); say("disabled " + b.dataset.disable, "ok"); } catch (err) { say(err.message, "err"); } }

package/dist/log-sink.d.ts

@@ -1,7 +1,7 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import { type Envelope, type KeyPair } from "./crypto.ts";
 import { type InclusionProof } from "./log.ts";
-import { type AuditEntry, type LogBackend, type PostgresTenancy, type RateLimitOptions } from "./log-store.ts";
+import { type AuditEntry, type QuotaState, type LogBackend, type PostgresTenancy, type RateLimitOptions } from "./log-store.ts";
 import { type Signer } from "./signer.ts";
 import type { Checkpoint, CheckpointStore } from "./checkpoints.ts";
 import { type AdminOptions } from "./log-admin.ts";
@@ -62,6 +62,8 @@ export interface LogServerOptions {
     }>;
     /** appends per token (or per address without one); default 50 a second, burst 100 */
     rateLimit?: RateLimitOptions;
+    /** accept only { leafHash } on append: a log run for other people must never receive a receipt */
+    hashOnly?: boolean;
     /** largest append body accepted, in bytes; default 65536 */
     maxBodyBytes?: number;
     /** where published checkpoints go and are listed from; without one, /checkpoints answers with none */
@@ -76,6 +78,10 @@ export interface LogServerOptions {
     trustProxy?: boolean;
 }
 /** The address a limit is keyed by: the socket's, or the proxy's forwarded one when the proxy is trusted. */
+/**
+ * The address a per-client limit keys on. Behind a proxy you run, the proxy appends the real client to
+ * X-Forwarded-For, so the rightmost entry is the one it wrote; everything left of it is whatever the client sent.
+ */
 export declare function clientAddress(req: IncomingMessage, trustProxy?: boolean): string;
 /** One log as the handler sees it, whatever stands behind it. */
 export interface TenantUsage {
@@ -92,6 +98,10 @@ export interface ResolvedLog {
     usage?(month: string): Promise<TenantUsage>;
     /** administrative actions on this log, newest first, where the store keeps them */
     audit?(limit: number): Promise<AuditEntry[]>;
+    /** the plan's monthly allowance and what is used, where the store keeps plans */
+    quota?(): Promise<QuotaState>;
+    /** told after an append lands, so a cached quota count stays honest */
+    appended?(): void;
 }
 /** Turns the tenant in a path, or null for the root paths, into a log. */
 export interface LogResolver {

package/dist/log-sink.js

@@ -97,12 +97,17 @@ export function openLog(cfg, key) {
     return fileLog(cfg.logFile, key);
 }
 /** The address a limit is keyed by: the socket's, or the proxy's forwarded one when the proxy is trusted. */
+/**
+ * The address a per-client limit keys on. Behind a proxy you run, the proxy appends the real client to
+ * X-Forwarded-For, so the rightmost entry is the one it wrote; everything left of it is whatever the client sent.
+ */
 export function clientAddress(req, trustProxy = false) {
     if (trustProxy) {
         const xff = req.headers["x-forwarded-for"];
-        const first = (Array.isArray(xff) ? xff[0] : xff)?.split(",")[0]?.trim();
-        if (first)
-            return first;
+        const entries = (Array.isArray(xff) ? xff.join(",") : xff ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+        const last = entries[entries.length - 1];
+        if (last)
+            return last;
     }
     return req.socket.remoteAddress ?? "?";
 }
@@ -155,6 +160,8 @@ export function postgresResolver(tenancy, opts = {}) {
                     return { month, appends: row?.appends ?? 0, totalLeaves: row?.totalLeaves ?? 0, liveTokens: row?.liveTokens ?? 0 };
                 },
                 audit: (limit) => tenancy.audit({ tenant: id, limit }),
+                quota: () => tenancy.quota(id),
+                appended: () => tenancy.noteAppend(id),
             };
         },
         async tenants() {
@@ -289,6 +296,16 @@ export function logHandler(source, keyOrSigner, opts = {}) {
                 const token = bearer(req);
                 if (!(await which.authorize(token)))
                     return json(401, { error: "unauthorized" });
+                if (which.quota) {
+                    // The plan's monthly allowance. Over it, the append is refused with the numbers, and the gateway behind it
+                    // withholds pre-committed calls: a tenant out of quota never acts without evidence.
+                    const q = await which.quota();
+                    if (q.quota !== null && q.used >= q.quota) {
+                        const now = new Date();
+                        const monthEnd = Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1);
+                        return json(429, { error: `monthly quota reached: ${q.used} of ${q.quota} appends on the ${q.plan} plan; it resets at the start of next month, or move to a larger plan` }, { "retry-after": String(Math.max(1, Math.ceil((monthEnd - now.getTime()) / 1000))) });
+                    }
+                }
                 const limitKey = token ? createHash("sha256").update(token).digest("hex").slice(0, 16) : `addr:${clientAddress(req, opts.trustProxy)}`;
                 if (!limiter.take(limitKey))
                     return json(429, { error: "too many appends; retry shortly" }, { "retry-after": "1" });
@@ -308,11 +325,17 @@ export function logHandler(source, keyOrSigner, opts = {}) {
                 if (typeof parsed.leafHash === "string") {
                     if (!/^[0-9a-f]{64}$/.test(parsed.leafHash))
                         return json(400, { error: "leafHash must be 64 lowercase hex characters" });
-                    return json(200, await appendSigned(log, signer, { leafHash: parsed.leafHash }, logId));
+                    const r = await appendSigned(log, signer, { leafHash: parsed.leafHash }, logId);
+                    which.appended?.();
+                    return json(200, r);
                 }
+                if (opts.hashOnly)
+                    return json(400, { error: "this log accepts leaf hashes only; set \"hashOnly\": true in your log config so the receipt never leaves your machine" });
                 if (typeof parsed.leaf !== "string" || parsed.leaf.length === 0)
                     return json(400, { error: "leaf must be a non-empty string, or send leafHash" });
-                return json(200, await appendSigned(log, signer, { leaf: parsed.leaf }, logId));
+                const r = await appendSigned(log, signer, { leaf: parsed.leaf }, logId);
+                which.appended?.();
+                return json(200, r);
             }
             const current = await log.size();
             // A tenant's own data, with their token: every leaf hash, in pages, and their metering. The export command
@@ -334,7 +357,9 @@ export function logHandler(source, keyOrSigner, opts = {}) {
                     const month = url.searchParams.get("month") ?? new Date().toISOString().slice(0, 7);
                     if (!/^\d{4}-(0[1-9]|1[0-2])$/.test(month))
                         return json(400, { error: "month must be YYYY-MM" });
-                    return json(200, await which.usage(month), { "cache-control": "no-store" });
+                    const u = await which.usage(month);
+                    const q = which.quota ? await which.quota() : null;
+                    return json(200, { ...u, ...(q ? { plan: q.plan, quota: q.quota } : {}) }, { "cache-control": "no-store" });
                 }
                 const since = url.searchParams.has("since") ? Number(url.searchParams.get("since")) : 0;
                 const limit = url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : 10_000;

package/dist/log-store.d.ts

@@ -57,12 +57,24 @@ export declare class PostgresLog implements LogBackend {
     root(size?: number): Promise<string>;
     consistencyProof(oldSize: number, newSize?: number): Promise<string[]>;
 }
+/** A tenant's plan decides its monthly append quota; enterprise has none. The names are what the pricing page sells. */
+export type Plan = "free" | "team" | "enterprise";
+export declare const PLANS: readonly Plan[];
+export declare const PLAN_QUOTAS: Readonly<Record<Plan, number | null>>;
 export interface Tenant {
     id: string;
     logId: string;
+    plan: Plan;
     createdAt: string;
     disabledAt: string | null;
 }
+export interface QuotaState {
+    plan: Plan;
+    /** appends so far this calendar month, UTC */
+    used: number;
+    /** the plan's monthly allowance, or null for none */
+    quota: number | null;
+}
 export interface TokenRecord {
     tenantId: string;
     label: string;
@@ -76,7 +88,7 @@ export interface AuditEntry {
     id: number;
     at: string;
     actor: string;
-    action: "tenant.add" | "tenant.disable" | "token.add" | "token.revoke";
+    action: "tenant.add" | "tenant.disable" | "tenant.plan" | "token.add" | "token.revoke";
     tenantId: string | null;
     detail: Record<string, unknown>;
 }
@@ -87,8 +99,12 @@ export declare class PostgresTenancy {
     private readonly logs;
     private readonly tenantCache;
     private readonly tokenCache;
+    private readonly quotaCache;
+    private readonly quotas;
     private ready;
-    constructor(client: PostgresLike, opts?: PostgresLogOptions);
+    constructor(client: PostgresLike, opts?: PostgresLogOptions & {
+        quotas?: Partial<Record<Plan, number | null>>;
+    });
     private init;
     private record;
     /** Administrative actions, newest first; for one tenant when given. What the admin page shows and a tenant's export carries. */
@@ -105,6 +121,12 @@ export declare class PostgresTenancy {
     log(tenantId: string): Promise<PostgresLog>;
     /** Creates a tenant, or renames its log id. `by` names who did it in the audit trail. */
     addTenant(id: string, logId?: string, by?: string): Promise<Tenant>;
+    /** Moves a tenant to a plan; the quota applies from the next append. */
+    setPlan(id: string, plan: Plan, by?: string): Promise<Tenant>;
+    /** The tenant's plan, appends this month, and the plan's quota. Cached ten seconds, so a burst may overshoot slightly. */
+    quota(id: string): Promise<QuotaState>;
+    /** Called after an append lands, so the cached count stays honest between refreshes. */
+    noteAppend(id: string): void;
     disableTenant(id: string, by?: string): Promise<void>;
     listTenants(): Promise<Tenant[]>;
     /** Mints a token for a tenant. The token is returned once and stored only as its hash. */
@@ -123,6 +145,8 @@ export declare class PostgresTenancy {
         tenants: {
             id: string;
             logId: string;
+            plan: Plan;
+            quota: number | null;
             appends: number;
             totalLeaves: number;
             liveTokens: number;