@agent-custody/receipts 0.1.5 → 0.1.6

package/README.md

@@ -237,7 +237,7 @@ src/verify.ts      offline verification, the human-readable report, and the audi
 src/cli.ts         keygen, grant, gateway, hook, serve, log, verify, audit
 src/index.ts       the package's public surface; adapters are exported on ./sdk/<framework> subpaths
 tsconfig.build.json  emits dist/ (JavaScript plus declarations) for consumers; the repo itself runs the .ts directly
-scripts/           fake Stripe upstream, fixture builders for gateway and SDK, demo
+scripts/           fake Stripe upstream (signs its results with --key), a second fake upstream, fixture builders for gateway and SDK, demo
 examples/          fifteen runnable tutorials, plus examples/languages/: Python, Go, Java, and Rust clients of the sidecar, run by the test suite, one per aspect; each is run by the test suite
 test/              unit tests per module, end-to-end gateway test, SDK and hook tests,
                    adapter tests against the real packages, and a test that runs every policy in docs/policies.md
@@ -255,6 +255,7 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 - SDK core: policy decision, record, and a generic `wrap(tool, fn)` for any framework whose tools are functions.
 - Claude Code command hook for PreToolUse, PostToolUse, and PostToolUseFailure, with blocking on deny.
 - Claude Agent SDK in-process hooks over the same handler.
+- Several upstreams under one gateway and one grant, each tool owned by exactly one, with the receipt naming which served the call; consumed facts flow across them.
 - Attested execution: an upstream that holds a key signs its result for the receipt, the gateway embeds it, and a verifier given the upstream key reports the execution as attested rather than observed. The memory server and the demo upstream sign.
 - HTTP upstreams: the gateway reaches an already-running MCP server over Streamable HTTP with a bearer token from the environment, as well as spawning one over stdio.
 - Optional fact lookups: a lookup that references a call argument the call does not carry is skipped rather than denying, so policy can see the fact a write is about to supersede without refusing writes that supersede nothing.

package/dist/config.d.ts

@@ -1,4 +1,13 @@
 import { z } from "zod";
+declare const UpstreamSchema: z.ZodUnion<readonly [z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    url: z.ZodString;
+    tokenEnv: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+export type UpstreamConfig = z.infer<typeof UpstreamSchema>;
 declare const FactSchema: z.ZodObject<{
     name: z.ZodString;
     tool: z.ZodString;
@@ -10,14 +19,24 @@ export declare const GatewayConfigSchema: z.ZodObject<{
     identity: z.ZodObject<{
         keyFile: z.ZodString;
     }, z.core.$strip>;
-    upstream: z.ZodUnion<readonly [z.ZodObject<{
+    upstream: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         command: z.ZodString;
         args: z.ZodDefault<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strip>, z.ZodObject<{
         url: z.ZodString;
         tokenEnv: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>]>;
+    }, z.core.$strip>]>>;
+    upstreams: z.ZodOptional<z.ZodArray<z.ZodIntersection<z.ZodUnion<readonly [z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        url: z.ZodString;
+        tokenEnv: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>, z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strip>>>>;
     grantFile: z.ZodString;
     trustedPrincipalKeys: z.ZodArray<z.ZodString>;
     policyFile: z.ZodString;

package/dist/config.js

@@ -5,6 +5,10 @@ import { dirname, resolve } from "node:path";
 const LogSchema = z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional() });
 const oneLog = { message: "exactly one of logFile or log is required" };
 const hasOneLog = (c) => (c.logFile ? 1 : 0) + (c.log ? 1 : 0) === 1;
+const UpstreamSchema = z.union([
+    z.object({ command: z.string(), args: z.array(z.string()).default([]), env: z.record(z.string(), z.string()).optional() }),
+    z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional() }),
+]);
 const FactSchema = z.object({
     /** key under context.facts */
     name: z.string().min(1),
@@ -20,10 +24,9 @@ const FactSchema = z.object({
 export const GatewayConfigSchema = z.object({
     identity: z.object({ keyFile: z.string() }),
     /** the upstream MCP server: a process to spawn over stdio, or a URL to reach over Streamable HTTP with an optional bearer token from the environment */
-    upstream: z.union([
-        z.object({ command: z.string(), args: z.array(z.string()).default([]), env: z.record(z.string(), z.string()).optional() }),
-        z.object({ url: z.string().url(), tokenEnv: z.string().min(1).optional() }),
-    ]),
+    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(),
     trustedPrincipalKeys: z.array(z.string()).min(1),
     policyFile: z.string(),
@@ -31,7 +34,7 @@ export const GatewayConfigSchema = z.object({
     receiptsDir: z.string(),
     logFile: z.string().optional(),
     log: LogSchema.optional(),
-}).refine(hasOneLog, oneLog);
+}).refine(hasOneLog, oneLog).refine((c) => (c.upstream ? 1 : 0) + (c.upstreams ? 1 : 0) === 1, { message: "exactly one of upstream or upstreams is required" });
 /** Loads a config file and resolves every path relative to the file's directory. */
 export function loadConfig(path) {
     const cfg = GatewayConfigSchema.parse(JSON.parse(readFileSync(path, "utf8")));

package/dist/gateway.d.ts

@@ -7,6 +7,8 @@ export declare const MODEL_META_KEY = "agent-custody/model";
 /** Set by the gateway on the call it forwards upstream: the receipt id, and the agent and principal from the attested grant. */
 export declare const AGENT_META_KEY = "agent-custody/agent";
 export declare const PRINCIPAL_META_KEY = "agent-custody/principal";
+/** Set by the gateway on the forwarded call: the values of the facts it fetched itself for this call, by name, so an upstream can check a claimed value against what the gateway observed. */
+export declare const OBSERVED_META_KEY = "agent-custody/observed";
 /** Set by an upstream on its result: the ids of the facts it served in this call. The gateway remembers them for the session. */
 export declare const FACTS_META_KEY = "agent-custody/facts";
 export interface CallParams {

package/dist/gateway.js

@@ -20,6 +20,8 @@ export const MODEL_META_KEY = "agent-custody/model";
 /** Set by the gateway on the call it forwards upstream: the receipt id, and the agent and principal from the attested grant. */
 export const AGENT_META_KEY = "agent-custody/agent";
 export const PRINCIPAL_META_KEY = "agent-custody/principal";
+/** Set by the gateway on the forwarded call: the values of the facts it fetched itself for this call, by name, so an upstream can check a claimed value against what the gateway observed. */
+export const OBSERVED_META_KEY = "agent-custody/observed";
 /** Set by an upstream on its result: the ids of the facts it served in this call. The gateway remembers them for the session. */
 export const FACTS_META_KEY = "agent-custody/facts";
 /** Returns null when an optional lookup references a call argument that is absent. */
@@ -67,17 +69,42 @@ export async function createGateway(cfg) {
     const policyText = readFileSync(cfg.policyFile, "utf8");
     const pDigest = policyDigest(policyText);
     const issuer = createIssuer(gatewayKey, cfg.receiptsDir, openLog(cfg, gatewayKey));
-    const upstream = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
-    if ("url" in cfg.upstream) {
-        const token = cfg.upstream.tokenEnv ? process.env[cfg.upstream.tokenEnv] : undefined;
-        if (cfg.upstream.tokenEnv && !token)
-            throw new Error(`upstream token: environment variable ${cfg.upstream.tokenEnv} is not set`);
-        await upstream.connect(new StreamableHTTPClientTransport(new URL(cfg.upstream.url), token ? { requestInit: { headers: { authorization: `Bearer ${token}` } } } : {}));
-    }
-    else {
-        await upstream.connect(new StdioClientTransport({ command: cfg.upstream.command, args: cfg.upstream.args, env: cfg.upstream.env, stderr: "inherit" }));
+    // 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.
+    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();
+    const advertised = [];
+    for (const { name, cfg: u } of upstreamConfigs) {
+        const client = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
+        if ("url" in u) {
+            const token = u.tokenEnv ? process.env[u.tokenEnv] : undefined;
+            if (u.tokenEnv && !token)
+                throw new Error(`upstream ${name}: environment variable ${u.tokenEnv} is not set`);
+            await client.connect(new StreamableHTTPClientTransport(new URL(u.url), token ? { requestInit: { headers: { authorization: `Bearer ${token}` } } } : {}));
+        }
+        else {
+            await client.connect(new StdioClientTransport({ command: u.command, args: u.args, env: u.env, stderr: "inherit" }));
+        }
+        upstreams.set(name, client);
+        const { tools } = await client.listTools();
+        for (const t of tools) {
+            const other = owner.get(t.name);
+            if (other) {
+                for (const c of upstreams.values())
+                    await c.close();
+                throw new Error(`tool "${t.name}" is offered by both upstream "${other}" and upstream "${name}"; a gateway needs one owner per tool`);
+            }
+            owner.set(t.name, name);
+            advertised.push(t);
+        }
     }
-    const callUpstream = async (name, args, meta) => (await upstream.callTool({ name, arguments: args, ...(meta ? { _meta: meta } : {}) }));
+    const callUpstream = async (name, args, meta) => {
+        const via = owner.get(name);
+        if (!via)
+            throw new Error(`no upstream offers tool "${name}"`);
+        return (await upstreams.get(via).callTool({ name, arguments: args, ...(meta ? { _meta: meta } : {}) }));
+    };
     async function gatherFacts(tool, args, meta) {
         const facts = {};
         for (const f of cfg.facts.filter((f) => f.forTools.includes(tool))) {
@@ -135,7 +162,8 @@ export async function createGateway(cfg) {
             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 result = await callUpstream(tool, args, upstreamMeta);
+                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 upstreamSig = upstreamSignatureOf(result);
                 execution = { status: result.isError ? "failed" : "executed", result, resultDigest: digestOf(result), provenance: "observed", ...(upstreamSig ? { upstream: { envelope: upstreamSig } } : {}) };
                 noteServedFacts(result);
@@ -156,7 +184,7 @@ export async function createGateway(cfg) {
             delegation: { envelope: grantEnvelope, provenance: "attested" },
             session: { id: null, toolUseId: null, provenance: "claimed" },
             model: { id: typeof modelClaim === "string" ? modelClaim : null, provenance: "claimed" },
-            tool: { name: tool, provenance: "observed" },
+            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" },
@@ -180,11 +208,13 @@ export async function createGateway(cfg) {
         agentId: delegation.agent,
         delegation,
         async listTools() {
-            const { tools } = await upstream.listTools();
-            return tools.filter((t) => delegation.scopes.includes(t.name));
+            return advertised.filter((t) => delegation.scopes.includes(t.name));
         },
         handleCall,
-        close: () => upstream.close(),
+        async close() {
+            for (const c of upstreams.values())
+                await c.close();
+        },
     };
 }
 /** Exposes the gateway as an MCP server over stdio. Everything diagnostic must go to stderr. */

package/dist/receipt.d.ts

@@ -60,9 +60,11 @@ export interface ReceiptPredicate {
         id: string | null;
         provenance: "claimed";
     };
+    /** upstream names which of several upstreams served the tool; absent when the gateway has one */
     tool: {
         name: string;
         provenance: Provenance;
+        upstream?: string;
     };
     request: {
         args: Record<string, unknown>;

package/docs/usage.md

@@ -77,7 +77,7 @@ when {
 }
 ```
 
-`upstream` is spawned by the gateway exactly as an MCP host would spawn it. `env` is passed through, which is where upstream credentials go. The agent never sees them. An upstream that is already running is reached instead with `"upstream": { "url": "https://memory.internal/mcp", "tokenEnv": "MEMORY_TOKEN" }`, over Streamable HTTP with a bearer token from the environment; the shared memory server in `@agent-custody/state` is the usual case.
+`upstream` is spawned by the gateway exactly as an MCP host would spawn it. `env` is passed through, which is where upstream credentials go. The agent never sees them. Several upstreams sit behind one gateway and one grant with `"upstreams": [{ "name": "memory", "command": ..., "args": [...] }, { "name": "payments", "url": ... }]` in place of `upstream`. Each tool name must be offered by exactly one of them, checked at startup; the receipt's `tool.upstream` says which served the call, and consumed facts flow across them, so a refund made after a memory read carries the facts the agent had been shown. An upstream that is already running is reached instead with `"upstream": { "url": "https://memory.internal/mcp", "tokenEnv": "MEMORY_TOKEN" }`, over Streamable HTTP with a bearer token from the environment; the shared memory server in `@agent-custody/state` is the usual case.
 
 `logFile` is the local Merkle log, with tree heads signed by the gateway's own key. To log to a server the operator does not control, replace it with `log`:
 
@@ -194,6 +194,8 @@ The receipt id is the file name under `receiptsDir`.
 
 The call the gateway forwards carries three `_meta` keys the agent cannot set: `agent-custody/receipt`, the id of the receipt being issued for this call; `agent-custody/agent` and `agent-custody/principal`, from the signed delegation grant. An upstream that keeps state can cite the receipt as the source of what it stores and record the attested caller rather than a claimed one. The memory server in `@agent-custody/state` does exactly that. Fact lookups carry the same keys, since they are the gateway acting for the same receipt.
 
+The forwarded call also carries `agent-custody/observed`: the values of the facts the gateway fetched for this call, by name, so an upstream can check a value the agent claims against what the gateway itself saw. The memory server's evidence check works this way.
+
 The upstream can answer in kind. A result whose `_meta` carries `agent-custody/facts`, an array of fact ids, tells the gateway which facts it just served; the gateway remembers them for the rest of the session and every later receipt carries them as `consumed`, labelled `observed` because the gateway saw those results itself. That is what the agent had been shown by the time of each call, an upper bound on what it relied on, and it is what the state package's blast-radius query walks.
 
 ## Operational notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Chain of custody for AI agents: signed, independently verifiable receipts for tool calls. MCP gateway + Cedar policy + Merkle transparency log",
   "license": "Apache-2.0",
   "repository": {