@agent-custody/receipts 0.5.9 → 0.6.1

package/dist/gateway.js

@@ -57,24 +57,16 @@ function extractValue(result) {
         return text.text;
     }
 }
-export async function createGateway(cfg, options = {}) {
+export async function createGatewayHost(cfg, options = {}) {
     const gatewayKey = loadPrivateKey(cfg.identity.keyFile);
     const trusted = cfg.trustedPrincipalKeys.map(loadPublicKey);
-    const grantEnvelope = JSON.parse(readFileSync(cfg.grantFile, "utf8"));
-    const grant = verifyDelegation(grantEnvelope, trusted);
-    if (!grant.ok)
-        throw new Error(`delegation grant rejected: ${grant.error}`);
-    if (!delegationValidAt(grant.delegation, new Date().toISOString()))
-        throw new Error("delegation grant is outside its validity window");
-    const delegation = grant.delegation;
-    const principalKeyid = grant.keyid;
     const policyText = readFileSync(cfg.policyFile, "utf8");
     const pDigest = policyDigest(policyText);
     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);
-    // One gateway, one grant, one session, and as many upstreams as the agent's job needs. Each tool name belongs to
-    // exactly one upstream, decided at startup, so a receipt's tool is unambiguous and consumed facts flow across them.
+    // 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 }];
     const upstreams = new Map();
     const owner = new Map();
@@ -128,124 +120,161 @@ export async function createGateway(cfg, options = {}) {
         }
         return facts;
     }
-    /** Every fact id an upstream has declared it served, in order of first sight. One gateway process is one agent session. */
-    const consumed = [];
-    const noteServedFacts = (result) => {
-        const ids = result._meta?.[FACTS_META_KEY];
-        if (!Array.isArray(ids))
-            return;
-        for (const id of ids)
-            if (typeof id === "string" && !consumed.includes(id))
-                consumed.push(id);
-    };
-    async function handleCall(params) {
-        const tool = params.name;
-        const args = params.arguments ?? {};
-        const receiptId = randomUUID();
-        const timestamp = new Date().toISOString();
-        const modelClaim = params._meta?.[MODEL_META_KEY];
-        // What the agent had been shown before this call; recorded before this call's own result is seen.
-        const consumedNow = [...consumed];
-        const upstreamMeta = { [RECEIPT_META_KEY]: receiptId, [AGENT_META_KEY]: delegation.agent, [PRINCIPAL_META_KEY]: delegation.principal };
-        let facts = {};
-        let policy;
-        let execution;
-        let authorization;
-        if (!delegation.scopes.includes(tool)) {
-            policy = { decision: "deny", reasons: [], errors: [`tool "${tool}" is not in the delegation scopes`], policyDigest: pDigest };
-        }
-        else {
-            try {
-                facts = await gatherFacts(tool, args, upstreamMeta);
-                const factValues = Object.fromEntries(Object.entries(facts).map(([k, f]) => [k, f.value]));
-                policy = evaluate(policyText, {
-                    agentId: delegation.agent,
-                    tool,
-                    context: { args, facts: factValues, grant: { principal: delegation.principal, scopes: delegation.scopes } },
-                });
+    function open(grantEnvelope) {
+        const grant = verifyDelegation(grantEnvelope, trusted);
+        if (!grant.ok)
+            throw new Error(`delegation grant rejected: ${grant.error}`);
+        if (!delegationValidAt(grant.delegation, new Date().toISOString()))
+            throw new Error("delegation grant is outside its validity window");
+        const delegation = grant.delegation;
+        const principalKeyid = grant.keyid;
+        /** Every fact id an upstream has declared it served to this session, in order of first sight. A session is one agent under one grant. */
+        const consumed = [];
+        const noteServedFacts = (result) => {
+            const ids = result._meta?.[FACTS_META_KEY];
+            if (!Array.isArray(ids))
+                return;
+            for (const id of ids)
+                if (typeof id === "string" && !consumed.includes(id))
+                    consumed.push(id);
+        };
+        async function handleCall(params) {
+            const tool = params.name;
+            const args = params.arguments ?? {};
+            const receiptId = randomUUID();
+            const timestamp = new Date().toISOString();
+            const modelClaim = params._meta?.[MODEL_META_KEY];
+            // What the agent had been shown before this call; recorded before this call's own result is seen.
+            const consumedNow = [...consumed];
+            const upstreamMeta = { [RECEIPT_META_KEY]: receiptId, [AGENT_META_KEY]: delegation.agent, [PRINCIPAL_META_KEY]: delegation.principal };
+            let facts = {};
+            let policy;
+            let execution;
+            let authorization;
+            if (!delegation.scopes.includes(tool)) {
+                policy = { decision: "deny", reasons: [], errors: [`tool "${tool}" is not in the delegation scopes`], policyDigest: pDigest };
             }
-            catch (e) {
-                policy = { decision: "deny", reasons: [], errors: [String(e instanceof Error ? e.message : e)], policyDigest: pDigest };
+            else {
+                try {
+                    facts = await gatherFacts(tool, args, upstreamMeta);
+                    const factValues = Object.fromEntries(Object.entries(facts).map(([k, f]) => [k, f.value]));
+                    policy = evaluate(policyText, {
+                        agentId: delegation.agent,
+                        tool,
+                        context: { args, facts: factValues, grant: { principal: delegation.principal, scopes: delegation.scopes } },
+                    });
+                }
+                catch (e) {
+                    policy = { decision: "deny", reasons: [], errors: [String(e instanceof Error ? e.message : e)], policyDigest: pDigest };
+                }
             }
-        }
-        const head = {
-            receiptId,
-            timestamp,
-            issuer: { kind: "gateway", keyid: issuer.keyid, version: GATEWAY_VERSION },
-            principal: { id: delegation.principal, keyid: principalKeyid, provenance: "attested" },
-            agent: { id: delegation.agent, provenance: "attested" },
-            delegation: { envelope: grantEnvelope, provenance: "attested" },
-            tool: { name: tool, provenance: "observed", ...(owner.has(tool) && upstreamConfigs.length > 1 ? { upstream: owner.get(tool) } : {}) },
-            request: { args, argsDigest: digestOf(args), provenance: "claimed" },
-            facts,
-            consumed: { factIds: consumedNow, provenance: "observed" },
-        };
-        if (policy.decision === "allow" && consequential(tool)) {
-            // A consequential call is committed to the log before it goes out, so that evidence of the side effect exists
-            // before the side effect does. If the log will not take the authorization, the call is not forwarded.
-            try {
-                authorization = await issuer.authorize({ ...head, policy: { ...policy, provenance: "observed" } });
+            const head = {
+                receiptId,
+                timestamp,
+                issuer: { kind: "gateway", keyid: issuer.keyid, version: GATEWAY_VERSION },
+                principal: { id: delegation.principal, keyid: principalKeyid, provenance: "attested" },
+                agent: { id: delegation.agent, provenance: "attested" },
+                delegation: { envelope: grantEnvelope, provenance: "attested" },
+                tool: { name: tool, provenance: "observed", ...(owner.has(tool) && upstreamConfigs.length > 1 ? { upstream: owner.get(tool) } : {}) },
+                request: { args, argsDigest: digestOf(args), provenance: "claimed" },
+                facts,
+                consumed: { factIds: consumedNow, provenance: "observed" },
+            };
+            if (policy.decision === "allow" && consequential(tool)) {
+                // A consequential call is committed to the log before it goes out, so that evidence of the side effect exists
+                // before the side effect does. If the log will not take the authorization, the call is not forwarded.
+                try {
+                    authorization = await issuer.authorize({ ...head, policy: { ...policy, provenance: "observed" } });
+                }
+                catch (e) {
+                    execution = { status: "withheld", reason: `the log did not commit the authorization, so the call was not forwarded: ${String(e instanceof Error ? e.message : e)}`, provenance: "observed" };
+                }
             }
-            catch (e) {
-                execution = { status: "withheld", reason: `the log did not commit the authorization, so the call was not forwarded: ${String(e instanceof Error ? e.message : e)}`, provenance: "observed" };
+            if (execution) {
+                // withheld: nothing was forwarded
             }
-        }
-        if (execution) {
-            // withheld: nothing was forwarded
-        }
-        else if (policy.decision === "allow") {
-            try {
-                // The upstream learns which receipt this call is, and who the grant says is calling. An upstream that keeps
-                // state, such as the memory server, cites the receipt as the source of what it stores.
-                const observed = Object.fromEntries(Object.entries(facts).map(([k, f]) => [k, f.value]));
-                const result = await callUpstream(tool, args, { ...upstreamMeta, [OBSERVED_META_KEY]: observed });
-                const evidence = upstreamEvidenceOf(result);
-                execution = { status: result.isError ? "failed" : "executed", result, resultDigest: digestOf(result), provenance: "observed", ...(evidence ? { upstream: evidence } : {}) };
-                noteServedFacts(result);
+            else if (policy.decision === "allow") {
+                try {
+                    // The upstream learns which receipt this call is, and who the grant says is calling. An upstream that keeps
+                    // state, such as the memory server, cites the receipt as the source of what it stores.
+                    const observed = Object.fromEntries(Object.entries(facts).map(([k, f]) => [k, f.value]));
+                    const result = await callUpstream(tool, args, { ...upstreamMeta, [OBSERVED_META_KEY]: observed });
+                    const evidence = upstreamEvidenceOf(result);
+                    execution = { status: result.isError ? "failed" : "executed", result, resultDigest: digestOf(result), provenance: "observed", ...(evidence ? { upstream: evidence } : {}) };
+                    noteServedFacts(result);
+                }
+                catch (e) {
+                    execution = { status: "error", error: String(e instanceof Error ? e.message : e), provenance: "observed" };
+                }
             }
-            catch (e) {
-                execution = { status: "error", error: String(e instanceof Error ? e.message : e), provenance: "observed" };
+            else {
+                execution = { status: "denied", reason: [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched", provenance: "observed" };
             }
-        }
-        else {
-            execution = { status: "denied", reason: [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched", provenance: "observed" };
-        }
-        await issuer.issue({
-            ...head,
-            session: { id: null, toolUseId: null, provenance: "claimed" },
-            model: { id: typeof modelClaim === "string" ? modelClaim : null, provenance: "claimed" },
-            policy: { ...policy, provenance: "observed" },
-            ...(authorization ? { authorization } : {}),
-            execution,
-        });
-        const meta = { [RECEIPT_META_KEY]: receiptId };
-        const refuse = (text) => ({ isError: true, content: [{ type: "text", text: `${text} (receipt ${receiptId})` }], _meta: meta });
-        switch (execution.status) {
-            case "denied":
-                return refuse(`Denied by policy: ${execution.reason}`);
-            case "error":
-                return refuse(`Upstream error: ${execution.error}`);
-            case "withheld":
-                return refuse(`Not executed: ${execution.reason}`);
-            default: {
-                const result = execution.result;
-                return { ...result, _meta: { ...result._meta, ...meta } };
+            await issuer.issue({
+                ...head,
+                session: { id: null, toolUseId: null, provenance: "claimed" },
+                model: { id: typeof modelClaim === "string" ? modelClaim : null, provenance: "claimed" },
+                policy: { ...policy, provenance: "observed" },
+                ...(authorization ? { authorization } : {}),
+                execution,
+            });
+            const meta = { [RECEIPT_META_KEY]: receiptId };
+            const refuse = (text) => ({ isError: true, content: [{ type: "text", text: `${text} (receipt ${receiptId})` }], _meta: meta });
+            switch (execution.status) {
+                case "denied":
+                    return refuse(`Denied by policy: ${execution.reason}`);
+                case "error":
+                    return refuse(`Upstream error: ${execution.error}`);
+                case "withheld":
+                    return refuse(`Not executed: ${execution.reason}`);
+                default: {
+                    const result = execution.result;
+                    return { ...result, _meta: { ...result._meta, ...meta } };
+                }
             }
         }
+        return {
+            agentId: delegation.agent,
+            delegation,
+            async listTools() {
+                return advertised.filter((t) => delegation.scopes.includes(t.name));
+            },
+            handleCall,
+            async close() {
+                // a session holds nothing of its own beyond what it consumed; the host owns the upstreams
+            },
+        };
     }
     return {
-        agentId: delegation.agent,
-        delegation,
-        async listTools() {
-            return advertised.filter((t) => delegation.scopes.includes(t.name));
-        },
-        handleCall,
+        keyid: issuer.keyid,
+        open,
         async close() {
             for (const c of upstreams.values())
                 await c.close();
         },
     };
 }
+/** One gateway for the grant the config names: what `agent-custody gateway` serves over stdio. Closing it closes the host. */
+export async function createGateway(cfg, options = {}) {
+    if (!cfg.grantFile)
+        throw new Error("config needs grantFile for a single-grant gateway; over HTTP each connection presents its own grant");
+    const host = await createGatewayHost(cfg, options);
+    let session;
+    try {
+        session = host.open(JSON.parse(readFileSync(cfg.grantFile, "utf8")));
+    }
+    catch (e) {
+        await host.close();
+        throw e;
+    }
+    return {
+        ...session,
+        async close() {
+            await session.close();
+            await host.close();
+        },
+    };
+}
 /** Exposes the gateway as an MCP server over stdio. Everything diagnostic must go to stderr. */
 export async function serveStdio(gw) {
     const server = new Server({ name: "agent-custody-gateway", version: GATEWAY_VERSION }, { capabilities: { tools: {} } });

package/dist/index.d.ts

@@ -4,10 +4,15 @@ export type { GatewayOptions } from "./gateway.ts";
 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

@@ -3,8 +3,11 @@ export { AUTHORIZATION_PREDICATE_TYPE, buildAuthorizationStatement } from "./rec
 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";
@@ -92,6 +92,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

@@ -155,6 +155,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 +291,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 +320,15 @@ 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 (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 +350,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;