@agent-custody/receipts 0.5.9 → 0.6.1

package/README.md

@@ -228,6 +228,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
@@ -238,7 +239,8 @@ src/policy.ts      Cedar evaluation wrapper, fail-closed
 src/delegation.ts  signed delegation grants
 src/receipt.ts     receipt and authorization statement types and provenance labels
 src/issue.ts       sign, log, and write a receipt, or commit an authorization first; shared by both producers
-src/gateway.ts     the MCP proxy: scope check, facts, policy, forward, receipt
+src/gateway.ts     the MCP proxy: a host (key, policy, upstreams, log) and a session per grant; scope check, facts, policy, forward, receipt
+src/gateway-http.ts the gateway over Streamable HTTP: one process, a session per connection, each under the grant it presents
 src/sdk/index.ts   the interceptor: policy decision, record, wrap(tool fn)
 src/sdk/claude.ts  Claude Code command hook and Claude Agent SDK in-process hooks
 src/sdk/openai-agents.ts, vercel-ai.ts, langchain.ts   framework adapters, tested against the real packages
@@ -286,6 +288,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.
@@ -294,6 +297,8 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 - The log over Postgres: `log --db-env`, leaves as hashes in one table keyed by tenant, one writer per tenant by advisory lock, tenants and hashed tokens in tables managed by `log-admin`, rate limits and a body cap, retries in the sink, and `import` for an existing file log. Phase 2 of [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 - A log for someone else: `hashOnly` sends leaf hashes so the log never holds a receipt; the reference server runs several tenant logs at `/t/<tenant>/` with their own tokens and ids; tree heads name their log and the verifier checks it with `--log-id`. Phase 1 of the hosted log, [issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 - OpenTelemetry export: with `otel` in either config, every receipt is also one span at the collector the team already runs, trace id equal to the receipt id, attributes for tool, agent, principal, status, decision, and log position; after the receipt, best effort, never on the evidence path.
+- Delegation chains for sub-agents: a grant that names the agent's key lets it delegate a narrower grant, with the parent embedded, up to three deep; the verifier and the gateway walk the chain to the principal, refusing any link that escalates scope, widens the window, changes the principal, or is signed by the wrong key; the receipt names the sub-agent and the principal and carries the chain. Pinned by the `gateway-chain-*` vectors and mirrored in the browser verifier.
+- One gateway for many agents: `gateway --http` serves the gateway over Streamable HTTP, one session per connection under the grant that connection presents, sessions sharing the upstreams and the policy and nothing else; a platform team runs one gateway in front of the tools instead of one process per agent.
 - Splunk export: with `splunk` in either config, every receipt is also one event at the HTTP Event Collector, with the receipt id, tool, agent, principal, status, decision, and log position as searchable fields and the token from the environment; the same best-effort rule.
 - The REST connector: a plain HTTP API described as tools in the gateway config, credentials from the environment, so an agent's direct API calls become receipted, policy-checked tool calls through the gateway.
 - Pre-commit authorization for consequential tools: named in `precommit`, a call is signed and logged before it is forwarded, withheld if the log will not take it, and its receipt carries the committed authorization with proof that it precedes the execution.
@@ -302,9 +307,7 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 
 1. Run the witness for log.agent-custody.dev on a machine and under an account that is not ours, and require it in the welcome sheet. The code is done; what it needs is a second operator. [Issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 2. Post-quantum signatures: ML-DSA beside Ed25519 in the same DSSE envelope, hybrid by default when a PQ key is present, in every signed artefact and in the browser verifier. [Issue #11](https://github.com/ch4r10t33r/agent-custody/issues/11).
-3. An HTTP transport for the gateway, with the grant presented per connection, for a shared deployment rather than one process per agent session.
-4. Delegation chains for sub-agents.
-5. Receiver-attested receipts for agent-to-agent calls.
-6. A TEE-hosted signer, then SD-JWT redaction, then ZK proofs of policy compliance. Not before.
+3. Receiver-attested receipts for agent-to-agent calls.
+4. A TEE-hosted signer, then SD-JWT redaction, then ZK proofs of policy compliance. Not before.
 
 A Python SDK follows the same shape once the TypeScript adapters have settled.

package/dist/cli.js

@@ -5,14 +5,16 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { loadConfig, loadSdkConfig } from "./config.js";
 import { generateKeyPair, loadPrivateKey, loadPublicKey, writeKeyPair } from "./crypto.js";
-import { createDelegation } from "./delegation.js";
-import { createGateway, serveStdio } from "./gateway.js";
+import { createDelegation, decodeDelegation, delegateFrom } from "./delegation.js";
+import { createGateway, createGatewayHost, serveStdio } from "./gateway.js";
 import { postgresResolver, serveLog } from "./log-sink.js";
 import { importLogFile, PostgresTenancy } from "./log-store.js";
 import { bothCheckpoints, dirCheckpoints, postgresCheckpoints } from "./checkpoints.js";
 import { connectSigner, fetchLogKeys, localSigner, serveSigner } from "./signer.js";
 import { 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";
@@ -33,8 +35,13 @@ function secretFrom(envName) {
 const USAGE = `agent-custody <command>
 
   keygen  --dir <dir> --name <name>
-  grant   --key <principal.key> --principal <id> --agent <id> --scopes <a,b> [--ttl-hours 24] --out <file>
-  gateway --config <gateway.json>
+  grant   --key <principal.key> --principal <id> --agent <id> --scopes <a,b> [--ttl-hours 24] [--agent-key <agent.pub>] --out <file>
+                                                   --agent-key names the agent's own key in the grant, so the agent may delegate
+  delegate --key <agent.key> --parent <grant.json> --agent <sub-agent> --scopes <a,b> [--ttl-hours N] [--agent-key <sub.pub>] --out <file>
+                                                   a narrower grant for a sub-agent, signed by the agent the parent names; the parent travels inside
+  gateway --config <gateway.json> [--http [--port 8790] [--host 127.0.0.1] [--idle-minutes 30]]
+                                                   stdio: one gateway for the grant the config names. --http: one shared gateway, MCP over
+                                                   Streamable HTTP at /mcp, each connection presenting its own grant as Authorization: Bearer
   hook    [--config <sdk.json>]        Claude Code hook command; reads the event on stdin (or AGENT_CUSTODY_CONFIG)
   serve   --config <sdk.json> [--port 8788] [--host 127.0.0.1]   the SDK as a local HTTP API for agents in other languages
   prune   --log <log.jsonl> --before <ISO instant> [--receipts <dir>]
@@ -64,9 +71,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
+  log-admin --db-env NAME audit [--tenant <id>]
+  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   who did what to tenants and tokens, newest first
   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
@@ -126,6 +136,7 @@ async function main(argv) {
                     agent: { type: "string" },
                     scopes: { type: "string" },
                     "ttl-hours": { type: "string", default: "24" },
+                    "agent-key": { type: "string" },
                     out: { type: "string" },
                 },
             });
@@ -139,15 +150,41 @@ async function main(argv) {
                 scopes: values.scopes.split(",").map((s) => s.trim()).filter(Boolean),
                 issuedAt: new Date(now).toISOString(),
                 expiresAt: new Date(now + Number(values["ttl-hours"]) * 3600_000).toISOString(),
+                ...(values["agent-key"] ? { agentKey: readFileSync(values["agent-key"], "utf8") } : {}),
             });
             writeFileSync(values.out, JSON.stringify(env, null, 2));
             console.log(`wrote ${values.out}`);
             return 0;
         }
+        case "delegate": {
+            const { values } = parseArgs({ args: rest, options: { key: { type: "string" }, parent: { type: "string" }, agent: { type: "string" }, scopes: { type: "string" }, "ttl-hours": { type: "string" }, "agent-key": { type: "string" }, out: { type: "string" } } });
+            if (!values.key || !values.parent || !values.agent || !values.scopes || !values.out)
+                throw new Error("delegate needs --key --parent --agent --scopes --out");
+            const parent = JSON.parse(readFileSync(values.parent, "utf8"));
+            const env = delegateFrom(parent, loadPrivateKey(values.key), {
+                agent: values.agent,
+                scopes: values.scopes.split(",").map((s) => s.trim()).filter(Boolean),
+                ...(values["ttl-hours"] ? { expiresAt: new Date(Date.now() + Number(values["ttl-hours"]) * 3600_000).toISOString() } : {}),
+                ...(values["agent-key"] ? { agentKey: readFileSync(values["agent-key"], "utf8") } : {}),
+            });
+            writeFileSync(values.out, JSON.stringify(env, null, 2));
+            const chain = decodeDelegation(env);
+            console.log(`delegated to ${chain.agent}: scopes [${chain.scopes.join(", ")}] until ${chain.expiresAt}, under ${decodeDelegation(parent).agent}'s grant from ${chain.principal}`);
+            return 0;
+        }
         case "gateway": {
-            const { values } = parseArgs({ args: rest, options: { config: { type: "string" } } });
+            const { values } = parseArgs({ args: rest, options: { config: { type: "string" }, http: { type: "boolean", default: false }, port: { type: "string", default: "8790" }, host: { type: "string", default: "127.0.0.1" }, "idle-minutes": { type: "string", default: "30" } } });
             if (!values.config)
                 throw new Error("gateway needs --config");
+            if (values.http) {
+                const host = await createGatewayHost(loadConfig(values.config));
+                const running = await serveHttp(host, { port: Number(values.port), host: values.host, idleMs: Number(values["idle-minutes"]) * 60_000 });
+                console.error(`agent-custody gateway: ${running.url} keyid=${host.keyid} one session per grant; GET /health`);
+                await new Promise((resolve) => process.once("SIGINT", resolve));
+                await running.close();
+                await host.close();
+                return 0;
+            }
             const gw = await createGateway(loadConfig(values.config));
             console.error(`agent-custody gateway: agent=${gw.agentId} principal=${gw.delegation.principal} scopes=[${gw.delegation.scopes.join(", ")}]`);
             await serveStdio(gw);
@@ -228,6 +265,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"])
@@ -241,7 +310,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);

package/dist/config.d.ts

@@ -158,7 +158,7 @@ export declare const GatewayConfigSchema: z.ZodObject<{
     }, z.core.$strip>]>, z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strip>>>>;
-    grantFile: z.ZodString;
+    grantFile: z.ZodOptional<z.ZodString>;
     trustedPrincipalKeys: z.ZodArray<z.ZodString>;
     policyFile: z.ZodString;
     facts: z.ZodDefault<z.ZodArray<z.ZodObject<{

package/dist/config.js

@@ -53,7 +53,8 @@ export const GatewayConfigSchema = z.object({
     upstream: UpstreamSchema.optional(),
     /** several upstreams behind one gateway and one grant; each tool name must belong to exactly one of them */
     upstreams: z.array(UpstreamSchema.and(z.object({ name: z.string().min(1) }))).min(1).optional(),
-    grantFile: z.string(),
+    /** the one grant a stdio gateway serves; over HTTP each connection presents its own, and this is not needed */
+    grantFile: z.string().optional(),
     trustedPrincipalKeys: z.array(z.string()).min(1),
     policyFile: z.string(),
     facts: z.array(FactSchema).default([]),
@@ -76,7 +77,7 @@ export function loadConfig(path) {
     return {
         ...cfg,
         identity: { keyFile: r(cfg.identity.keyFile) },
-        grantFile: r(cfg.grantFile),
+        ...(cfg.grantFile ? { grantFile: r(cfg.grantFile) } : {}),
         trustedPrincipalKeys: cfg.trustedPrincipalKeys.map(r),
         policyFile: r(cfg.policyFile),
         receiptsDir: r(cfg.receiptsDir),

package/dist/crypto.d.ts

@@ -22,6 +22,8 @@ export declare function writeKeyPair(kp: KeyPair, dir: string, name: string): {
 export declare function loadPrivateKey(path: string): KeyPair;
 export declare function loadPublicKey(path: string): PublicKeyRef;
 /** A public key from its SPKI PEM text, as found in a .pub file or a conformance vector. */
+/** The SPKI PEM of a public key: what a grant carries as `agentKey`, and what `.pub` files hold. */
+export declare function publicKeyToPem(publicKey: KeyObject): string;
 export declare function publicKeyFromPem(pem: string): PublicKeyRef;
 export interface Envelope {
     payloadType: string;

package/dist/crypto.js

@@ -53,6 +53,10 @@ export function loadPublicKey(path) {
     return publicKeyFromPem(readFileSync(path, "utf8"));
 }
 /** A public key from its SPKI PEM text, as found in a .pub file or a conformance vector. */
+/** The SPKI PEM of a public key: what a grant carries as `agentKey`, and what `.pub` files hold. */
+export function publicKeyToPem(publicKey) {
+    return publicKey.export({ type: "spki", format: "pem" }).toString();
+}
 export function publicKeyFromPem(pem) {
     const publicKey = createPublicKey(pem);
     return { publicKey, keyid: keyidOf(publicKey) };

package/dist/delegation.d.ts

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { type Envelope, type KeyPair, type PublicKeyRef } from "./crypto.ts";
 export declare const DELEGATION_TYPE = "application/vnd.agent-custody.delegation+json";
+/** the longest chain a verifier walks: the principal's grant and up to three delegations below it */
+export declare const MAX_DELEGATION_DEPTH = 4;
 export declare const DelegationSchema: z.ZodObject<{
     version: z.ZodLiteral<"0.1">;
     principal: z.ZodString;
@@ -8,17 +10,48 @@ export declare const DelegationSchema: z.ZodObject<{
     scopes: z.ZodArray<z.ZodString>;
     issuedAt: z.ZodISODateTime;
     expiresAt: z.ZodISODateTime;
+    agentKey: z.ZodOptional<z.ZodString>;
+    parent: z.ZodOptional<z.ZodObject<{
+        payloadType: z.ZodString;
+        payload: z.ZodString;
+        signatures: z.ZodArray<z.ZodObject<{
+            keyid: z.ZodString;
+            sig: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Delegation = z.infer<typeof DelegationSchema>;
 export declare function createDelegation(principalKey: KeyPair, d: Delegation): Envelope;
+export interface SubDelegation {
+    agent: string;
+    scopes: string[];
+    issuedAt?: string;
+    expiresAt?: string;
+    /** the sub-agent's own public key, so it may delegate further */
+    agentKey?: string;
+}
+/** The parent's payload as written, without verifying it; the verifier does that. */
+export declare function decodeDelegation(env: Envelope): Delegation | null;
+/**
+ * An agent delegates part of its grant to a sub-agent. `agentKey` is the delegating agent's key, the one its own grant
+ * names. The result embeds the parent; it is refused here, before signing, when it asks for more than the parent has.
+ */
+export declare function delegateFrom(parent: Envelope, agentKey: KeyPair, sub: SubDelegation): Envelope;
 export type DelegationVerifyResult = {
     ok: true;
+    /** the grant the receipt was issued under: the leaf of the chain */
     delegation: Delegation;
+    /** the principal's key: the signer of the root grant */
     keyid: string;
+    /** root first, leaf last; one entry for a direct grant */
+    chain: Delegation[];
 } | {
     ok: false;
     error: string;
 };
-export declare function verifyDelegation(env: Envelope, trustedPrincipals: PublicKeyRef[]): DelegationVerifyResult;
+/** Verifies a grant, walking its chain to a grant signed by one of the trusted principal keys. */
+export declare function verifyDelegation(env: Envelope, trustedPrincipals: PublicKeyRef[], depth?: number): DelegationVerifyResult;
 /** True when `at` (ISO) lies inside the grant's validity window. */
 export declare function delegationValidAt(d: Delegation, at: string): boolean;
+/** "principal → agent → sub-agent", for reports. */
+export declare function describeChain(chain: Delegation[]): string;

package/dist/delegation.js

@@ -1,7 +1,16 @@
 // A delegation grant: a principal signs a statement that an agent may use certain tools for a window of time.
+//
+// A grant may carry the agent's own public key (`agentKey`); an agent so named may delegate to a sub-agent by signing
+// a narrower grant that embeds the grant it came from (`parent`). A verifier walks the chain to the principal: every
+// link is signed by the key its parent names, every scope is one its parent holds, every window lies inside its
+// parent's, and the principal is the same throughout. The receipt then names the sub-agent as the agent and the
+// principal as the principal, exactly as with a direct grant, and the whole chain travels inside the receipt.
 import { z } from "zod";
-import { dsseSign, dsseVerify } from "./crypto.js";
+import { dsseSign, dsseVerify, publicKeyFromPem } from "./crypto.js";
 export const DELEGATION_TYPE = "application/vnd.agent-custody.delegation+json";
+/** the longest chain a verifier walks: the principal's grant and up to three delegations below it */
+export const MAX_DELEGATION_DEPTH = 4;
+const EnvelopeSchema = z.object({ payloadType: z.string(), payload: z.string(), signatures: z.array(z.object({ keyid: z.string(), sig: z.string() })).min(1) });
 export const DelegationSchema = z.object({
     version: z.literal("0.1"),
     principal: z.string().min(1),
@@ -9,23 +18,98 @@ export const DelegationSchema = z.object({
     scopes: z.array(z.string().min(1)).min(1),
     issuedAt: z.iso.datetime(),
     expiresAt: z.iso.datetime(),
+    /** 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 */
+    parent: EnvelopeSchema.optional(),
 });
 export function createDelegation(principalKey, d) {
     return dsseSign(DELEGATION_TYPE, DelegationSchema.parse(d), principalKey);
 }
-export function verifyDelegation(env, trustedPrincipals) {
+/** The parent's payload as written, without verifying it; the verifier does that. */
+export function decodeDelegation(env) {
+    try {
+        const parsed = DelegationSchema.safeParse(JSON.parse(Buffer.from(env.payload, "base64").toString("utf8")));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * An agent delegates part of its grant to a sub-agent. `agentKey` is the delegating agent's key, the one its own grant
+ * names. The result embeds the parent; it is refused here, before signing, when it asks for more than the parent has.
+ */
+export function delegateFrom(parent, agentKey, sub) {
+    const p = decodeDelegation(parent);
+    if (!p)
+        throw new Error("the parent grant is not a delegation");
+    if (!p.agentKey)
+        throw new Error(`the parent grant names no agent key, so ${p.agent} cannot delegate`);
+    if (publicKeyFromPem(p.agentKey).keyid !== agentKey.keyid)
+        throw new Error(`this key is not the one the parent grant names for ${p.agent}`);
+    const extra = sub.scopes.filter((s) => !p.scopes.includes(s));
+    if (extra.length)
+        throw new Error(`a sub-agent cannot be given scopes its delegator lacks: ${extra.join(", ")}`);
+    const issuedAt = sub.issuedAt ?? new Date().toISOString();
+    const expiresAt = sub.expiresAt ?? p.expiresAt;
+    if (Date.parse(issuedAt) < Date.parse(p.issuedAt) || Date.parse(expiresAt) > Date.parse(p.expiresAt))
+        throw new Error("a sub-agent's window must lie inside its delegator's");
+    return createDelegation(agentKey, { version: "0.1", principal: p.principal, agent: sub.agent, scopes: sub.scopes, issuedAt, expiresAt, ...(sub.agentKey ? { agentKey: sub.agentKey } : {}), parent });
+}
+/** Verifies a grant, walking its chain to a grant signed by one of the trusted principal keys. */
+export function verifyDelegation(env, trustedPrincipals, depth = 1) {
     if (env.payloadType !== DELEGATION_TYPE)
         return { ok: false, error: `unexpected payloadType ${env.payloadType}` };
-    const r = dsseVerify(env, trustedPrincipals);
+    if (depth > MAX_DELEGATION_DEPTH)
+        return { ok: false, error: `delegation chain deeper than ${MAX_DELEGATION_DEPTH}` };
+    const unverified = decodeDelegation(env);
+    if (!unverified)
+        return { ok: false, error: "invalid delegation" };
+    if (!unverified.parent) {
+        const r = dsseVerify(env, trustedPrincipals);
+        if (!r.ok)
+            return r;
+        const parsed = DelegationSchema.safeParse(r.payload);
+        if (!parsed.success)
+            return { ok: false, error: `invalid delegation: ${parsed.error.message}` };
+        return { ok: true, delegation: parsed.data, keyid: r.keyid, chain: [parsed.data] };
+    }
+    const up = verifyDelegation(unverified.parent, trustedPrincipals, depth + 1);
+    if (!up.ok)
+        return { ok: false, error: `link ${depth}: ${up.error}` };
+    const parent = up.delegation;
+    if (!parent.agentKey)
+        return { ok: false, error: `link ${depth}: ${parent.agent} holds no agent key and cannot delegate` };
+    let parentKey;
+    try {
+        parentKey = publicKeyFromPem(parent.agentKey);
+    }
+    catch {
+        return { ok: false, error: `link ${depth}: the agent key named for ${parent.agent} is not a public key` };
+    }
+    const r = dsseVerify(env, [parentKey]);
     if (!r.ok)
-        return r;
+        return { ok: false, error: `link ${depth}: not signed by ${parent.agent}'s key: ${r.error}` };
     const parsed = DelegationSchema.safeParse(r.payload);
     if (!parsed.success)
         return { ok: false, error: `invalid delegation: ${parsed.error.message}` };
-    return { ok: true, delegation: parsed.data, keyid: r.keyid };
+    const d = parsed.data;
+    if (d.principal !== parent.principal)
+        return { ok: false, error: `link ${depth}: principal changed from ${parent.principal} to ${d.principal}` };
+    const extra = d.scopes.filter((s) => !parent.scopes.includes(s));
+    if (extra.length)
+        return { ok: false, error: `link ${depth}: ${d.agent} was given scopes ${parent.agent} does not hold: ${extra.join(", ")}` };
+    if (Date.parse(d.issuedAt) < Date.parse(parent.issuedAt) || Date.parse(d.expiresAt) > Date.parse(parent.expiresAt))
+        return { ok: false, error: `link ${depth}: ${d.agent}'s window is not inside ${parent.agent}'s` };
+    return { ok: true, delegation: d, keyid: up.keyid, chain: [...up.chain, d] };
 }
 /** True when `at` (ISO) lies inside the grant's validity window. */
 export function delegationValidAt(d, at) {
     const t = Date.parse(at);
     return t >= Date.parse(d.issuedAt) && t <= Date.parse(d.expiresAt);
 }
+/** "principal → agent → sub-agent", for reports. */
+export function describeChain(chain) {
+    return [chain[0].principal, ...chain.map((d) => d.agent)].join(" → ");
+}

package/dist/gateway-http.d.ts

@@ -0,0 +1,30 @@
+import { type IncomingMessage } from "node:http";
+import type { Envelope } from "./crypto.ts";
+import { type GatewayHost } from "./gateway.ts";
+export declare const GRANT_HEADER = "x-agent-custody-grant";
+/** The header value that presents a grant: the DSSE envelope as base64url JSON. Send it as `Authorization: Bearer <value>` or as `X-Agent-Custody-Grant`. */
+export declare function grantHeader(envelope: Envelope): string;
+export declare function parseGrantHeader(req: IncomingMessage): Envelope | null;
+export interface HttpGatewayOptions {
+    port: number;
+    host?: string;
+    /** the MCP endpoint path; default /mcp */
+    path?: string;
+    /** a session with no request for this long is closed; default thirty minutes */
+    idleMs?: number;
+    /** where session events are reported; default stderr */
+    log?: (message: string) => void;
+}
+export interface RunningHttpGateway {
+    url: string;
+    /** live sessions by MCP session id */
+    sessions(): {
+        id: string;
+        agent: string;
+        principal: string;
+        since: string;
+    }[];
+    close(): Promise<void>;
+}
+/** Serves a gateway host as an MCP server over Streamable HTTP, a session per grant. */
+export declare function serveHttp(host: GatewayHost, opts: HttpGatewayOptions): Promise<RunningHttpGateway>;

package/dist/gateway-http.js

@@ -0,0 +1,139 @@
+// The gateway over HTTP: one process, many agents, each connection under its own grant. A platform team runs one
+// gateway in front of the tools; every agent connects with MCP over Streamable HTTP and presents the grant its
+// principal signed, and the gateway opens a session for exactly that grant. Sessions share the upstreams, the policy,
+// the key, and the log; each has its own consumed facts and its own receipts, and none can see another's tools.
+// The grant is the credential: it is signed by a principal key the gateway trusts, so nothing else is needed to
+// authenticate a connection, and a grant that is expired, revoked by time, or signed by a stranger gets 403 with the
+// reason in the body. (Not 401: the MCP client transport treats 401 as an OAuth challenge and hides the body.)
+// Bind to loopback or put TLS in front; the transport itself is plain HTTP.
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, isInitializeRequest, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { GATEWAY_VERSION } from "./gateway.js";
+export const GRANT_HEADER = "x-agent-custody-grant";
+/** The header value that presents a grant: the DSSE envelope as base64url JSON. Send it as `Authorization: Bearer <value>` or as `X-Agent-Custody-Grant`. */
+export function grantHeader(envelope) {
+    return Buffer.from(JSON.stringify(envelope)).toString("base64url");
+}
+export function parseGrantHeader(req) {
+    const explicit = req.headers[GRANT_HEADER];
+    const auth = req.headers.authorization ?? "";
+    const raw = typeof explicit === "string" && explicit ? explicit : auth.startsWith("Bearer ") ? auth.slice(7) : "";
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+        return parsed && typeof parsed === "object" && typeof parsed.payload === "string" && Array.isArray(parsed.signatures) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Serves a gateway host as an MCP server over Streamable HTTP, a session per grant. */
+export async function serveHttp(host, opts) {
+    const bind = opts.host ?? "127.0.0.1";
+    const path = opts.path ?? "/mcp";
+    const idleMs = opts.idleMs ?? 30 * 60_000;
+    const log = opts.log ?? ((m) => console.error(m));
+    const sessions = new Map();
+    const json = (res, status, body) => {
+        res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+        res.end(JSON.stringify(body));
+    };
+    const rpcError = (res, status, message) => json(res, status, { jsonrpc: "2.0", error: { code: -32000, message }, id: null });
+    const readBody = async (req) => {
+        let text = "";
+        for await (const chunk of req) {
+            text += chunk;
+            if (text.length > 4_194_304)
+                throw new Error("body larger than 4 MB");
+        }
+        return text ? JSON.parse(text) : undefined;
+    };
+    const closeSession = async (id, why) => {
+        const s = sessions.get(id);
+        if (!s)
+            return;
+        sessions.delete(id);
+        log(`agent-custody gateway: session ${id.slice(0, 8)} for ${s.gateway.agentId} closed (${why})`);
+        await s.gateway.close();
+        await s.transport.close().catch(() => { });
+    };
+    const openSession = async (req, res, body) => {
+        const envelope = parseGrantHeader(req);
+        if (!envelope)
+            return rpcError(res, 403, `a grant is required: send the delegation envelope as base64url in Authorization: Bearer or ${GRANT_HEADER}`);
+        let gateway;
+        try {
+            gateway = host.open(envelope);
+        }
+        catch (e) {
+            return rpcError(res, 403, e instanceof Error ? e.message : String(e));
+        }
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (id) => {
+                sessions.set(id, { gateway, transport, server, since: new Date().toISOString(), lastSeen: Date.now() });
+                log(`agent-custody gateway: session ${id.slice(0, 8)} opened for agent=${gateway.agentId} principal=${gateway.delegation.principal} scopes=[${gateway.delegation.scopes.join(", ")}]`);
+            },
+            onsessionclosed: (id) => void closeSession(id, "closed by the client"),
+        });
+        const server = new Server({ name: "agent-custody-gateway", version: GATEWAY_VERSION }, { capabilities: { tools: {} } });
+        server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: await gateway.listTools() }));
+        server.setRequestHandler(CallToolRequestSchema, async (r) => gateway.handleCall(r.params));
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    };
+    const handler = async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        if (req.method === "GET" && url.pathname === "/health")
+            return json(res, 200, { ok: true, sessions: sessions.size, keyid: host.keyid });
+        if (url.pathname !== path)
+            return json(res, 404, { error: "not found" });
+        try {
+            const sid = req.headers["mcp-session-id"];
+            const existing = typeof sid === "string" ? sessions.get(sid) : undefined;
+            if (existing) {
+                existing.lastSeen = Date.now();
+                const body = req.method === "POST" ? await readBody(req) : undefined;
+                await existing.transport.handleRequest(req, res, body);
+                return;
+            }
+            if (typeof sid === "string")
+                return rpcError(res, 404, "unknown or expired session; initialize again with your grant");
+            if (req.method !== "POST")
+                return rpcError(res, 400, "initialize first: POST an initialize request with your grant");
+            const body = await readBody(req);
+            if (!isInitializeRequest(body))
+                return rpcError(res, 400, "the first request of a session must be initialize");
+            await openSession(req, res, body);
+        }
+        catch (e) {
+            if (!res.headersSent)
+                rpcError(res, 500, e instanceof Error ? e.message : String(e));
+        }
+    };
+    const server = createServer((req, res) => void handler(req, res));
+    const reaper = setInterval(() => {
+        const cutoff = Date.now() - idleMs;
+        for (const [id, s] of sessions)
+            if (s.lastSeen < cutoff)
+                void closeSession(id, "idle");
+    }, Math.min(idleMs, 60_000));
+    reaper.unref?.();
+    await new Promise((resolve) => server.listen(opts.port, bind, resolve));
+    const { port } = server.address();
+    return {
+        url: `http://${bind}:${port}${path}`,
+        sessions: () => [...sessions.entries()].map(([id, s]) => ({ id, agent: s.gateway.agentId, principal: s.gateway.delegation.principal, since: s.since })),
+        async close() {
+            clearInterval(reaper);
+            for (const id of [...sessions.keys()])
+                await closeSession(id, "server closing");
+            server.closeAllConnections?.();
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}

package/dist/gateway.d.ts

@@ -1,5 +1,6 @@
 import { type CallToolResult, type Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { GatewayConfig } from "./config.ts";
+import { type Envelope } from "./crypto.ts";
 import { type Delegation } from "./delegation.ts";
 import { type LogSink } from "./log-sink.ts";
 import { type ReceiptExporter } from "./otel.ts";
@@ -31,6 +32,19 @@ export interface GatewayOptions {
     /** told about every receipt after it is written, in place of the exporter the config names */
     exporter?: ReceiptExporter;
 }
+/**
+ * The shared part of a gateway: the key, the policy, the issuer, the log, the upstreams, and the fact lookups. One host
+ * serves many sessions, each opened with its own grant; over stdio there is exactly one, over HTTP one per connection.
+ */
+export interface GatewayHost {
+    keyid: string;
+    /** a session for this grant: the grant is verified against the trusted principal keys and its validity window first */
+    open(grantEnvelope: Envelope): Gateway;
+    /** closes the upstreams; every session opened from this host is finished with */
+    close(): Promise<void>;
+}
+export declare function createGatewayHost(cfg: GatewayConfig, options?: GatewayOptions): Promise<GatewayHost>;
+/** One gateway for the grant the config names: what `agent-custody gateway` serves over stdio. Closing it closes the host. */
 export declare function createGateway(cfg: GatewayConfig, options?: GatewayOptions): Promise<Gateway>;
 /** Exposes the gateway as an MCP server over stdio. Everything diagnostic must go to stderr. */
 export declare function serveStdio(gw: Gateway): Promise<void>;