@agent-custody/receipts 0.5.8 → 0.6.0

package/README.md

@@ -238,7 +238,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
@@ -294,6 +295,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 +305,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/checkpoints.js

@@ -55,7 +55,7 @@ export function postgresCheckpoints(client, prefix = "log_") {
     return {
         async save(c) {
             await init();
-            await client.query(`INSERT INTO ${table} (tenant_id, tree_size, log_id, root_hash, signed_at, envelope) VALUES ($1, $2, $3, $4, $5, $6) ON CONFLICT (tenant_id, tree_size) DO NOTHING`, [c.tenant, c.treeSize, c.logId ?? null, c.rootHash, c.signedAt, JSON.stringify(c.envelope)]);
+            await client.query(`INSERT INTO ${table} (tenant_id, tree_size, log_id, root_hash, signed_at, envelope) VALUES ($1, $2, $3, $4, $5, $6) ON CONFLICT (tenant_id, tree_size) DO UPDATE SET signed_at = EXCLUDED.signed_at, envelope = EXCLUDED.envelope WHERE ${table}.root_hash = EXCLUDED.root_hash`, [c.tenant, c.treeSize, c.logId ?? null, c.rootHash, c.signedAt, JSON.stringify(c.envelope)]);
         },
         async list(tenant, since = -1) {
             await init();

package/dist/cli.js

@@ -5,14 +5,15 @@ 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 { exportLog, formatExport } from "./log-export.js";
 import { CheckpointPublisher, fileResolver } from "./log-sink.js";
 import { createRequire } from "node:module";
@@ -33,8 +34,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>]
@@ -43,7 +49,7 @@ const USAGE = `agent-custody <command>
   verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub> | --log-url <url>] [--log-id <id>] [--upstream-key <pub>] [--stripe-secret-env NAME] [--github-secret-env NAME] [--log <log.jsonl>] [--json]
   log     ... --db-env NAME                     the same server over Postgres: tenants and tokens from the database, one writer per tenant,
                                                  root paths serve the tenant "default" (created with --log-id). Needs the pg package.
-  log     ... (--key <log.key> [--retired-key <pub>]... | --signer-url <url> [--signer-token-env NAME]) [--checkpoint-dir <dir>] [--checkpoint-every <seconds>]
+  log     ... (--key <log.key> [--retired-key <pub>]... | --signer-url <url> [--signer-token-env NAME]) [--checkpoint-dir <dir>] [--checkpoint-every <seconds>] [--checkpoint-heartbeat <seconds>]
                                                  sign with a key in this process, or through a signer process that holds it; publish a signed
                                                  checkpoint per log that has grown, every 300 s by default, to the directory (and, with a
                                                  database, to its heads table); serve the key document at /.well-known/agent-custody-log.json
@@ -126,6 +132,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 +146,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);
@@ -292,7 +325,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" }, "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 } },
             });
             if (!values.key === !values["signer-url"])
                 throw new Error("log needs exactly one of --key or --signer-url");
@@ -312,6 +345,9 @@ async function main(argv) {
             const everyMs = Number(values["checkpoint-every"]) * 1000;
             if (!(everyMs > 0))
                 throw new Error("--checkpoint-every must be a positive number of seconds");
+            const heartbeatMs = Number(values["checkpoint-heartbeat"]) * 1000;
+            if (!(heartbeatMs > 0))
+                throw new Error("--checkpoint-heartbeat must be a positive number of seconds");
             let resolver;
             let checkpoints = values["checkpoint-dir"] ? dirCheckpoints(values["checkpoint-dir"]) : undefined;
             let where;
@@ -345,7 +381,7 @@ async function main(argv) {
                 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 publisher = checkpoints ? new CheckpointPublisher(resolver, signer, checkpoints, everyMs) : null;
+            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" : ""}`);
             await new Promise((resolve) => process.once("SIGINT", resolve));

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>;