@agent-custody/receipts 0.1.4 → 0.1.5

package/README.md

@@ -231,6 +231,7 @@ 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
 src/sidecar.ts     the SDK issuer behind a local HTTP API, for agents in other languages
+src/upstream.ts    attested execution: an upstream signs its result for the receipt; the verifier checks it with the upstream key
 vectors/           conformance vectors: receipts, keys, logs, proofs, and expected verdicts; `bun run vectors` regenerates them
 src/verify.ts      offline verification, the human-readable report, and the audit that a later log extends an earlier one
 src/cli.ts         keygen, grant, gateway, hook, serve, log, verify, audit
@@ -254,6 +255,10 @@ 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.
+- 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.
+- Consumed facts: an upstream declares the facts it served in its result `_meta`, and every later gateway receipt in the session carries those ids as `consumed`, observed, so what the agent had been shown before each call is on the record.
 - The forwarded call carries the receipt id and the attested agent and principal in `_meta`, so a stateful upstream can cite the receipt; the memory server in `@agent-custody/state` runs this way.
 - Conformance vectors, generated by the test suite and published with the spec, and a browser verifier on agent-custody.dev that passes all of them.
 - Sidecar: the SDK issuer behind a local HTTP API (`serve`), with a Python package on PyPI-ready footing and Go, Java, and Rust clients, so agents in any language get the same receipts from one signing implementation.
@@ -264,7 +269,7 @@ The design is two producers feeding one verifier. The SDK is the top of the funn
 **Next, in the order it pays off**
 
 1. OpenTelemetry export: emit each receipt as a span with the receipt id and issuer kind as attributes, so existing collectors and dashboards carry them without a new pipeline.
-2. Embed upstream signed responses (Stripe webhook signatures, GitHub delivery signatures) so gateway execution can move from `observed` to `attested`.
+2. Provider-native upstream signatures (Stripe webhook signatures, GitHub delivery signatures) as adapters onto the upstream attestation field.
 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.

package/dist/cli.js

@@ -19,7 +19,7 @@ const USAGE = `agent-custody <command>
   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
   log     --file <log.jsonl> --key <log.key> [--port 8787] [--host 127.0.0.1] [--token-env <NAME>]   reference log server
-  verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--log <log.jsonl>] [--json]
+  verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--upstream-key <pub>] [--log <log.jsonl>] [--json]
   audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--json]
           checks that the newer receipt's log extends the older one's: nothing between them was rewritten
 `;
@@ -119,6 +119,7 @@ async function main(argv) {
                     "gateway-key": { type: "string", multiple: true },
                     "principal-key": { type: "string", multiple: true },
                     "log-key": { type: "string", multiple: true },
+                    "upstream-key": { type: "string", multiple: true },
                     log: { type: "string" },
                     json: { type: "boolean", default: false },
                 },
@@ -132,6 +133,7 @@ async function main(argv) {
                 issuerKeys: issuerKeyFiles.map(loadPublicKey),
                 principalKeys: (values["principal-key"] ?? []).map(loadPublicKey),
                 ...(values["log-key"] ? { logKeys: values["log-key"].map(loadPublicKey) } : {}),
+                ...(values["upstream-key"] ? { upstreamKeys: values["upstream-key"].map(loadPublicKey) } : {}),
                 ...(values.log ? { logFile: values.log } : {}),
             });
             console.log(values.json ? JSON.stringify(result, null, 2) : formatReport(result));

package/dist/config.d.ts

@@ -4,16 +4,20 @@ declare const FactSchema: z.ZodObject<{
     tool: z.ZodString;
     args: z.ZodRecord<z.ZodString, z.ZodString>;
     forTools: z.ZodArray<z.ZodString>;
+    optional: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const GatewayConfigSchema: z.ZodObject<{
     identity: z.ZodObject<{
         keyFile: z.ZodString;
     }, z.core.$strip>;
-    upstream: z.ZodObject<{
+    upstream: 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.core.$strip>, z.ZodObject<{
+        url: z.ZodString;
+        tokenEnv: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>;
     grantFile: z.ZodString;
     trustedPrincipalKeys: z.ZodArray<z.ZodString>;
     policyFile: z.ZodString;
@@ -22,6 +26,7 @@ export declare const GatewayConfigSchema: z.ZodObject<{
         tool: z.ZodString;
         args: z.ZodRecord<z.ZodString, z.ZodString>;
         forTools: z.ZodArray<z.ZodString>;
+        optional: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>>;
     receiptsDir: z.ZodString;
     logFile: z.ZodOptional<z.ZodString>;

package/dist/config.js

@@ -14,14 +14,16 @@ const FactSchema = z.object({
     args: z.record(z.string(), z.string()),
     /** which intercepted tools trigger this lookup */
     forTools: z.array(z.string().min(1)).min(1),
+    /** when true and a "$args.<key>" the template needs is absent from the call, the lookup is skipped and the fact is simply not present */
+    optional: z.boolean().default(false),
 });
 export const GatewayConfigSchema = z.object({
     identity: z.object({ keyFile: z.string() }),
-    upstream: z.object({
-        command: z.string(),
-        args: z.array(z.string()).default([]),
-        env: z.record(z.string(), z.string()).optional(),
-    }),
+    /** 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() }),
+    ]),
     grantFile: z.string(),
     trustedPrincipalKeys: z.array(z.string()).min(1),
     policyFile: z.string(),

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 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 {
     name: string;
     arguments?: Record<string, unknown>;

package/dist/gateway.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -11,6 +12,7 @@ import { digestOf, loadPrivateKey, loadPublicKey } from "./crypto.js";
 import { delegationValidAt, verifyDelegation } from "./delegation.js";
 import { createIssuer } from "./issue.js";
 import { openLog } from "./log-sink.js";
+import { upstreamSignatureOf } from "./upstream.js";
 import { evaluate, policyDigest } from "./policy.js";
 export const GATEWAY_VERSION = "0.1.0";
 export const RECEIPT_META_KEY = "agent-custody/receipt";
@@ -18,13 +20,19 @@ 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";
-function resolveFactArgs(template, args) {
+/** 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. */
+function resolveFactArgs(template, args, optional = false) {
     const out = {};
     for (const [k, v] of Object.entries(template)) {
         if (v.startsWith("$args.")) {
             const key = v.slice("$args.".length);
-            if (!(key in args))
+            if (!(key in args) || args[key] === undefined) {
+                if (optional)
+                    return null;
                 throw new Error(`fact argument "${k}" needs call argument "${key}", which is missing`);
+            }
             out[k] = args[key];
         }
         else {
@@ -60,25 +68,49 @@ export async function createGateway(cfg) {
     const pDigest = policyDigest(policyText);
     const issuer = createIssuer(gatewayKey, cfg.receiptsDir, openLog(cfg, gatewayKey));
     const upstream = new Client({ name: "agent-custody-gateway", version: GATEWAY_VERSION });
-    await upstream.connect(new StdioClientTransport({ command: cfg.upstream.command, args: cfg.upstream.args, env: cfg.upstream.env, stderr: "inherit" }));
+    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" }));
+    }
     const callUpstream = async (name, args, meta) => (await upstream.callTool({ name, arguments: args, ...(meta ? { _meta: meta } : {}) }));
-    async function gatherFacts(tool, args) {
+    async function gatherFacts(tool, args, meta) {
         const facts = {};
         for (const f of cfg.facts.filter((f) => f.forTools.includes(tool))) {
-            const fargs = resolveFactArgs(f.args, args);
-            const result = await callUpstream(f.tool, fargs);
+            const fargs = resolveFactArgs(f.args, args, f.optional);
+            if (fargs === null)
+                continue;
+            // Lookups carry the same metadata as the forwarded call: they are the gateway acting for this receipt.
+            const result = await callUpstream(f.tool, fargs, meta);
             if (result.isError)
                 throw new Error(`fact "${f.name}" lookup via ${f.tool} failed: ${JSON.stringify(extractValue(result))}`);
             facts[f.name] = { tool: f.tool, args: fargs, value: extractValue(result), resultDigest: digestOf(result), provenance: "observed" };
         }
         return facts;
     }
+    /** Every fact id an upstream has declared it served, in order of first sight. One gateway process is one agent session. */
+    const consumed = [];
+    const noteServedFacts = (result) => {
+        const ids = result._meta?.[FACTS_META_KEY];
+        if (!Array.isArray(ids))
+            return;
+        for (const id of ids)
+            if (typeof id === "string" && !consumed.includes(id))
+                consumed.push(id);
+    };
     async function handleCall(params) {
         const tool = params.name;
         const args = params.arguments ?? {};
         const receiptId = randomUUID();
         const timestamp = new Date().toISOString();
         const modelClaim = params._meta?.[MODEL_META_KEY];
+        // What the agent had been shown before this call; recorded before this call's own result is seen.
+        const consumedNow = [...consumed];
+        const upstreamMeta = { [RECEIPT_META_KEY]: receiptId, [AGENT_META_KEY]: delegation.agent, [PRINCIPAL_META_KEY]: delegation.principal };
         let facts = {};
         let policy;
         let execution;
@@ -87,7 +119,7 @@ export async function createGateway(cfg) {
         }
         else {
             try {
-                facts = await gatherFacts(tool, args);
+                facts = await gatherFacts(tool, args, upstreamMeta);
                 const factValues = Object.fromEntries(Object.entries(facts).map(([k, f]) => [k, f.value]));
                 policy = evaluate(policyText, {
                     agentId: delegation.agent,
@@ -103,8 +135,10 @@ 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, { [RECEIPT_META_KEY]: receiptId, [AGENT_META_KEY]: delegation.agent, [PRINCIPAL_META_KEY]: delegation.principal });
-                execution = { status: result.isError ? "failed" : "executed", result, resultDigest: digestOf(result), provenance: "observed" };
+                const result = await callUpstream(tool, args, upstreamMeta);
+                const upstreamSig = upstreamSignatureOf(result);
+                execution = { status: result.isError ? "failed" : "executed", result, resultDigest: digestOf(result), provenance: "observed", ...(upstreamSig ? { upstream: { envelope: upstreamSig } } : {}) };
+                noteServedFacts(result);
             }
             catch (e) {
                 execution = { status: "error", error: String(e instanceof Error ? e.message : e), provenance: "observed" };
@@ -125,6 +159,7 @@ export async function createGateway(cfg) {
             tool: { name: tool, provenance: "observed" },
             request: { args, argsDigest: digestOf(args), provenance: "claimed" },
             facts,
+            consumed: { factIds: consumedNow, provenance: "observed" },
             policy: { ...policy, provenance: "observed" },
             execution,
         });

package/dist/index.d.ts

@@ -10,3 +10,4 @@ export * from "./receipt.ts";
 export * from "./verify.ts";
 export * from "./sdk/index.ts";
 export * from "./sidecar.ts";
+export * from "./upstream.ts";

package/dist/index.js

@@ -11,3 +11,4 @@ export * from "./receipt.js";
 export * from "./verify.js";
 export * from "./sdk/index.js";
 export * from "./sidecar.js";
+export * from "./upstream.js";

package/dist/receipt.d.ts

@@ -70,6 +70,15 @@ export interface ReceiptPredicate {
         provenance: "claimed";
     };
     facts: Record<string, FactRecord>;
+    /**
+     * Fact ids the agent had been shown, through this gateway, by the time of this call: every id an upstream declared
+     * in its result _meta under "agent-custody/facts" on an earlier call in the session. Observed, because the gateway
+     * saw those results itself. Absent on SDK receipts. This is what the agent relied on, as an upper bound.
+     */
+    consumed?: {
+        factIds: string[];
+        provenance: "observed";
+    };
     /** null when the issuer evaluated no policy. */
     policy: (PolicyDecision & {
         provenance: Provenance;
@@ -79,6 +88,10 @@ export interface ReceiptPredicate {
         result: unknown;
         resultDigest: string;
         provenance: Provenance;
+        /** an upstream's own signature over what it returned, bound to this receipt; checked by a verifier holding the upstream's key */
+        upstream?: {
+            envelope: Envelope;
+        };
     } | {
         status: "denied";
         reason: string;

package/dist/upstream.d.ts

@@ -0,0 +1,27 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type Envelope, type KeyPair, type PublicKeyRef } from "./crypto.ts";
+export declare const UPSTREAM_SIG_META_KEY = "agent-custody/upstream-signature";
+export declare const UPSTREAM_TYPE = "application/vnd.agent-custody.upstream+json";
+export interface UpstreamAttestation {
+    receiptId: string;
+    tool: string;
+    /** digest of { content, isError } of the result: what the agent received, without the _meta the signature lives in */
+    contentDigest: string;
+}
+export declare function contentDigest(result: {
+    content: unknown;
+    isError?: boolean | undefined;
+}): string;
+/** For upstreams: signs the result for this receipt and returns it with the envelope attached. */
+export declare function signResult<R extends CallToolResult>(result: R, key: KeyPair, receiptId: string, tool: string): R;
+/** For the gateway: the envelope an upstream attached, if any. */
+export declare function upstreamSignatureOf(result: CallToolResult): Envelope | null;
+export type UpstreamCheck = {
+    ok: true;
+    keyid: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** For verifiers: the envelope must verify against a trusted upstream key and bind to this receipt, tool, and content. */
+export declare function checkUpstream(envelope: Envelope, keys: PublicKeyRef[], expected: UpstreamAttestation): UpstreamCheck;

package/dist/upstream.js

@@ -0,0 +1,32 @@
+import { digestOf, dsseSign, dsseVerify } from "./crypto.js";
+export const UPSTREAM_SIG_META_KEY = "agent-custody/upstream-signature";
+export const UPSTREAM_TYPE = "application/vnd.agent-custody.upstream+json";
+export function contentDigest(result) {
+    return digestOf({ content: result.content, isError: !!result.isError });
+}
+/** For upstreams: signs the result for this receipt and returns it with the envelope attached. */
+export function signResult(result, key, receiptId, tool) {
+    const payload = { receiptId, tool, contentDigest: contentDigest(result) };
+    return { ...result, _meta: { ...result._meta, [UPSTREAM_SIG_META_KEY]: dsseSign(UPSTREAM_TYPE, payload, key) } };
+}
+/** For the gateway: the envelope an upstream attached, if any. */
+export function upstreamSignatureOf(result) {
+    const env = result._meta?.[UPSTREAM_SIG_META_KEY];
+    return env && typeof env.payload === "string" && Array.isArray(env.signatures) ? env : null;
+}
+/** For verifiers: the envelope must verify against a trusted upstream key and bind to this receipt, tool, and content. */
+export function checkUpstream(envelope, keys, expected) {
+    const v = dsseVerify(envelope, keys);
+    if (!v.ok)
+        return { ok: false, error: v.error };
+    if (envelope.payloadType !== UPSTREAM_TYPE)
+        return { ok: false, error: `payload type ${envelope.payloadType}` };
+    const p = v.payload;
+    if (p.receiptId !== expected.receiptId)
+        return { ok: false, error: "signed for a different receipt" };
+    if (p.tool !== expected.tool)
+        return { ok: false, error: `signed for tool ${String(p.tool)}` };
+    if (p.contentDigest !== expected.contentDigest)
+        return { ok: false, error: "signed content differs from the result in the receipt" };
+    return { ok: true, keyid: v.keyid };
+}

package/dist/verify.d.ts

@@ -11,6 +11,8 @@ export interface VerifyOptions {
     principalKeys: PublicKeyRef[];
     /** keys of logs run by someone other than the issuer; tree heads are checked against these and the issuer keys */
     logKeys?: PublicKeyRef[];
+    /** keys of upstreams that sign their results; with one given, an execution carrying an upstream signature is checked and becomes attested */
+    upstreamKeys?: PublicKeyRef[];
     /** If given, the root is recomputed from this log file at the receipt's tree size and compared. */
     logFile?: string;
 }

package/dist/verify.js

@@ -2,6 +2,7 @@
 import { canonicalize, digestOf, dsseVerify } from "./crypto.js";
 import { delegationValidAt, verifyDelegation } from "./delegation.js";
 import { leafHash, MerkleLog, verifyConsistency, verifyInclusion } from "./log.js";
+import { checkUpstream, contentDigest } from "./upstream.js";
 import { RECEIPT_PREDICATE_TYPE, RECEIPT_TYPE, TREEHEAD_TYPE } from "./receipt.js";
 const short = (s) => s.slice(0, 12);
 export function verifyBundle(bundle, opts) {
@@ -44,6 +45,11 @@ export function verifyBundle(bundle, opts) {
         add("principal is claimed, not attested", p.principal.provenance === "claimed", "no signed delegation in this receipt");
     }
     add("request args digest", digestOf(p.request.args) === p.request.argsDigest && st.subject[0]?.digest.sha256 === p.request.argsDigest);
+    if ((p.execution.status === "executed" || p.execution.status === "failed") && p.execution.upstream && (opts.upstreamKeys?.length ?? 0) > 0) {
+        const result = p.execution.result;
+        const u = checkUpstream(p.execution.upstream.envelope, opts.upstreamKeys, { receiptId: p.receiptId, tool: p.tool.name, contentDigest: contentDigest(result) });
+        add("upstream signature (upstream key)", u.ok, u.ok ? `keyid ${short(u.keyid)}` : u.error);
+    }
     if (p.policy) {
         const consistent = p.policy.decision === "allow" ? p.execution.status !== "denied" : p.execution.status === "denied";
         add("policy decision consistent with execution", consistent, `${p.policy.decision} -> ${p.execution.status}`);
@@ -129,6 +135,10 @@ export function formatReport(r) {
         row("policy", p.policy.provenance, `${p.policy.decision} [${p.policy.reasons.join(",")}] policy ${short(p.policy.policyDigest)}`);
     else
         row("policy", "-", "(none evaluated)");
-    row("execution", p.execution.provenance, p.execution.status);
+    if (p.consumed)
+        row("consumed", p.consumed.provenance, p.consumed.factIds.length === 0 ? "(no facts shown before this call)" : p.consumed.factIds);
+    const upstreamCheck = r.checks.find((c) => c.name === "upstream signature (upstream key)");
+    const hasUpstream = (p.execution.status === "executed" || p.execution.status === "failed") && !!p.execution.upstream;
+    row("execution", upstreamCheck?.ok ? "attested" : p.execution.provenance, `${p.execution.status}${hasUpstream ? (upstreamCheck ? (upstreamCheck.ok ? ` (signed by upstream ${upstreamCheck.detail})` : " (upstream signature FAILED)") : " (carries an upstream signature; pass --upstream-key to check it)") : ""}`);
     return lines.join("\n");
 }

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.
+`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.
 
 `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`:
 
@@ -87,7 +87,7 @@ when {
 
 Exactly one of the two. The bearer token comes from the named environment variable, never from the file, and a missing variable fails at startup. With a remote log the tree head in each receipt is signed by the log's key, and a verifier must be given that key with `--log-key`. If the log refuses a leaf, the receipt is not issued and the call returns an error to the agent; for an executed call the upstream action has already happened by then, which is the honest outcome, since a receipt that was never logged must not be handed out. The reference log server is `node src/cli.ts log --file log.jsonl --key keys/log.key --port 8787 --token-env AGENT_CUSTODY_LOG_TOKEN`. It serves `POST /append` (token required when one is configured), `GET /root?size=N`, `GET /consistency?old=M&new=N`, and `GET /head`; [verification.md](verification.md) says what each proves.
 
-`facts` tells the gateway which upstream tool to call before evaluating policy for a given tool. `$args.<key>` copies a value from the intercepted call. The result appears in Cedar as `context.facts.<name>` and in the receipt with its own digest, labelled `observed`. If a fact lookup fails, the call is denied and the receipt says why.
+`facts` tells the gateway which upstream tool to call before evaluating policy for a given tool. `$args.<key>` copies a value from the intercepted call. The result appears in Cedar as `context.facts.<name>` and in the receipt with its own digest, labelled `observed`. If a fact lookup fails, the call is denied and the receipt says why. A lookup with `"optional": true` is skipped when a `$args.<key>` it needs is absent from the call, and the fact is then simply not present, which a policy tests with `context.facts has <name>`; this is how a policy sees the fact a `memory.write` is about to supersede without denying every write that supersedes nothing.
 
 **5. Run the gateway.** It speaks MCP on stdin/stdout and logs to stderr only.
 
@@ -192,7 +192,9 @@ The receipt id is the file name under `receiptsDir`.
 
 ## What the upstream gets
 
-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 do not carry them; only the forwarded call does.
+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 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/docs/verification.md

@@ -17,6 +17,7 @@ node src/cli.ts verify receipts/<id>.json \
   --issuer-key keys/gateway.pub \
   --principal-key keys/principal.pub \
   --log-key keys/log.pub \  # only for receipts logged to a remote log
+  --upstream-key keys/upstream.pub \  # only when the upstream signed its result
   --log log.jsonl          # optional
 ```
 
@@ -114,6 +115,7 @@ const result = verifyBundle(bundle, {
   issuerKeys: [loadPublicKey("keys/gateway.pub")],   // gateway keys and SDK application keys
   principalKeys: [loadPublicKey("keys/principal.pub")],
   logKeys: [loadPublicKey("keys/log.pub")],           // only for receipts logged to a remote log
+  upstreamKeys: [loadPublicKey("keys/upstream.pub")], // only when the upstream signed its result
   logFile: "log.jsonl",           // optional
 });
 
@@ -165,3 +167,9 @@ The remote log also serves `GET /head`, its current tree head signed with the lo
 
 `vectors/` in the package holds fixed receipts, keys, logs, proofs, and the verdicts this verifier produces for them, generated by `bun run vectors` and checked by the test suite on every run. A verifier written elsewhere proves it agrees by reproducing every verdict. They are published at [agent-custody.dev/receipt/vectors](https://agent-custody.dev/receipt/vectors).
 
+## Attested execution
+
+On a gateway receipt the execution is `observed`: the gateway saw what the upstream returned. An upstream that holds a key can do better and sign its result for the receipt being issued; the gateway embeds the signature, and a verifier given the upstream's public key checks it and reports the execution as `attested` by that key. The check binds the signature to the receipt id, the tool, and the digest of the result content, so a signature cannot be moved between receipts.
+
+For upstream authors, `signResult(result, key, receiptId, tool)` from `@agent-custody/receipts` does the signing; the receipt id arrives in the call's `_meta["agent-custody/receipt"]`. The memory server in `@agent-custody/state` signs when started with `--key`, and the demo's fake upstream does too. Provider-native signatures, such as Stripe's webhook signatures, are adapters on top of the same field and are not implemented yet.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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": {

package/vectors/audit.json

@@ -7,26 +7,26 @@
       "description": "The tree head from the first remote receipt and the log's later head, with the proof the log served.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6Ijg3MzM5M2E4ZTQ4ZmFkNzVlMmRkMzY1MzRjNmRjNzUzMTc5YmM0NmEzMTAxNDZjZTI2OGUxNTc2ODZiOGMwZTQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExMFoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJyb290SGFzaCI6IjY4ODlmODQyNmVkODg4YTVlNzI0Y2YzNThlNmI0Y2E3ZmI3YWVmMTkwODkxOWE5MGYxZjNlNzFjMWU3MmNkODUiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA4OjM3OjM0LjkyOVoiLCJ0cmVlU2l6ZSI6MX0=",
         "signatures": [
           {
-            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
-            "sig": "vydFxb4Z753KUPOXLEFiYnE0nntaoU9xXtBe7IMW8eucYeef+XpGu+4+bXpo/zYZATcx4h+7bMmDd3frqizkBg=="
+            "keyid": "48967bd6051d66cebf961f226a6ae4e90dce91ead9ac10c0f9aaa427d40c4c16",
+            "sig": "FL7TL3y1JgXinAkxywmKfoULNe2V8D+JpIcsJWok54rIun70z7bmj78R1VnNe9aADLSGQb0JTYhdaODn9mOnCg=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6ImNlYmViNDAzYjNlZWYzYzgwNWVjYzg5OTI2NTM0ZGM0NjkxY2I4OWJlN2I0ZjFjNjE3Njg5MDFkMzIxNDkzYmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExNFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJyb290SGFzaCI6IjUxY2MyNzIzMzM0NzhmMjYxNDU1MWFmMWM1NjExMzBjOTBlODEwM2JhYmI1NzNkZjY2YjM3ZTVhMDk1YjI0ZWYiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA4OjM3OjM0LjkzM1oiLCJ0cmVlU2l6ZSI6Mn0=",
         "signatures": [
           {
-            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
-            "sig": "iyUBqiJcZd/RaEDXWhhxl34ekqy6tQ9qgsMQjAXlvuHS75aqPLeh0NRtUQB89LS2UMJYihmcSUdg/Z82uORqCQ=="
+            "keyid": "48967bd6051d66cebf961f226a6ae4e90dce91ead9ac10c0f9aaa427d40c4c16",
+            "sig": "o/zrDH6/I3VPabSVS4RozKm945Nd+hiwt6JTytpyMavxizlR8ZuGmG6lX56+A0M4wAk/H0qmmHXoLCGuobhdCw=="
           }
         ]
       },
       "proof": [
-        "4869289b5853ed3431c235a1f4e97d1d4205723e622dc71bd836018c62572723"
+        "e74d1e2874003df276b93e2e764da876201bcc1a9efe8752118676eafc4ce5eb"
       ],
       "keys": [
         "log"
@@ -41,26 +41,26 @@
       "description": "The same heads the wrong way round.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6ImNlYmViNDAzYjNlZWYzYzgwNWVjYzg5OTI2NTM0ZGM0NjkxY2I4OWJlN2I0ZjFjNjE3Njg5MDFkMzIxNDkzYmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExNFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJyb290SGFzaCI6IjUxY2MyNzIzMzM0NzhmMjYxNDU1MWFmMWM1NjExMzBjOTBlODEwM2JhYmI1NzNkZjY2YjM3ZTVhMDk1YjI0ZWYiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA4OjM3OjM0LjkzM1oiLCJ0cmVlU2l6ZSI6Mn0=",
         "signatures": [
           {
-            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
-            "sig": "iyUBqiJcZd/RaEDXWhhxl34ekqy6tQ9qgsMQjAXlvuHS75aqPLeh0NRtUQB89LS2UMJYihmcSUdg/Z82uORqCQ=="
+            "keyid": "48967bd6051d66cebf961f226a6ae4e90dce91ead9ac10c0f9aaa427d40c4c16",
+            "sig": "o/zrDH6/I3VPabSVS4RozKm945Nd+hiwt6JTytpyMavxizlR8ZuGmG6lX56+A0M4wAk/H0qmmHXoLCGuobhdCw=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6Ijg3MzM5M2E4ZTQ4ZmFkNzVlMmRkMzY1MzRjNmRjNzUzMTc5YmM0NmEzMTAxNDZjZTI2OGUxNTc2ODZiOGMwZTQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExMFoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJyb290SGFzaCI6IjY4ODlmODQyNmVkODg4YTVlNzI0Y2YzNThlNmI0Y2E3ZmI3YWVmMTkwODkxOWE5MGYxZjNlNzFjMWU3MmNkODUiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA4OjM3OjM0LjkyOVoiLCJ0cmVlU2l6ZSI6MX0=",
         "signatures": [
           {
-            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
-            "sig": "vydFxb4Z753KUPOXLEFiYnE0nntaoU9xXtBe7IMW8eucYeef+XpGu+4+bXpo/zYZATcx4h+7bMmDd3frqizkBg=="
+            "keyid": "48967bd6051d66cebf961f226a6ae4e90dce91ead9ac10c0f9aaa427d40c4c16",
+            "sig": "FL7TL3y1JgXinAkxywmKfoULNe2V8D+JpIcsJWok54rIun70z7bmj78R1VnNe9aADLSGQb0JTYhdaODn9mOnCg=="
           }
         ]
       },
       "proof": [
-        "4869289b5853ed3431c235a1f4e97d1d4205723e622dc71bd836018c62572723"
+        "e74d1e2874003df276b93e2e764da876201bcc1a9efe8752118676eafc4ce5eb"
       ],
       "keys": [
         "log"
@@ -77,26 +77,26 @@
       "description": "Tree heads checked against the app key, which did not sign them.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6Ijg3MzM5M2E4ZTQ4ZmFkNzVlMmRkMzY1MzRjNmRjNzUzMTc5YmM0NmEzMTAxNDZjZTI2OGUxNTc2ODZiOGMwZTQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExMFoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJyb290SGFzaCI6IjY4ODlmODQyNmVkODg4YTVlNzI0Y2YzNThlNmI0Y2E3ZmI3YWVmMTkwODkxOWE5MGYxZjNlNzFjMWU3MmNkODUiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA4OjM3OjM0LjkyOVoiLCJ0cmVlU2l6ZSI6MX0=",
         "signatures": [
           {
-            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
-            "sig": "vydFxb4Z753KUPOXLEFiYnE0nntaoU9xXtBe7IMW8eucYeef+XpGu+4+bXpo/zYZATcx4h+7bMmDd3frqizkBg=="
+            "keyid": "48967bd6051d66cebf961f226a6ae4e90dce91ead9ac10c0f9aaa427d40c4c16",
+            "sig": "FL7TL3y1JgXinAkxywmKfoULNe2V8D+JpIcsJWok54rIun70z7bmj78R1VnNe9aADLSGQb0JTYhdaODn9mOnCg=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6ImNlYmViNDAzYjNlZWYzYzgwNWVjYzg5OTI2NTM0ZGM0NjkxY2I4OWJlN2I0ZjFjNjE3Njg5MDFkMzIxNDkzYmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExNFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJyb290SGFzaCI6IjUxY2MyNzIzMzM0NzhmMjYxNDU1MWFmMWM1NjExMzBjOTBlODEwM2JhYmI1NzNkZjY2YjM3ZTVhMDk1YjI0ZWYiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA4OjM3OjM0LjkzM1oiLCJ0cmVlU2l6ZSI6Mn0=",
         "signatures": [
           {
-            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
-            "sig": "iyUBqiJcZd/RaEDXWhhxl34ekqy6tQ9qgsMQjAXlvuHS75aqPLeh0NRtUQB89LS2UMJYihmcSUdg/Z82uORqCQ=="
+            "keyid": "48967bd6051d66cebf961f226a6ae4e90dce91ead9ac10c0f9aaa427d40c4c16",
+            "sig": "o/zrDH6/I3VPabSVS4RozKm945Nd+hiwt6JTytpyMavxizlR8ZuGmG6lX56+A0M4wAk/H0qmmHXoLCGuobhdCw=="
           }
         ]
       },
       "proof": [
-        "4869289b5853ed3431c235a1f4e97d1d4205723e622dc71bd836018c62572723"
+        "e74d1e2874003df276b93e2e764da876201bcc1a9efe8752118676eafc4ce5eb"
       ],
       "keys": [
         "app"
@@ -114,21 +114,21 @@
       "description": "A proof with a hash removed.",
       "older": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6Ijg3MzM5M2E4ZTQ4ZmFkNzVlMmRkMzY1MzRjNmRjNzUzMTc5YmM0NmEzMTAxNDZjZTI2OGUxNTc2ODZiOGMwZTQiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExMFoiLCJ0cmVlU2l6ZSI6MX0=",
+        "payload": "eyJyb290SGFzaCI6IjY4ODlmODQyNmVkODg4YTVlNzI0Y2YzNThlNmI0Y2E3ZmI3YWVmMTkwODkxOWE5MGYxZjNlNzFjMWU3MmNkODUiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA4OjM3OjM0LjkyOVoiLCJ0cmVlU2l6ZSI6MX0=",
         "signatures": [
           {
-            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
-            "sig": "vydFxb4Z753KUPOXLEFiYnE0nntaoU9xXtBe7IMW8eucYeef+XpGu+4+bXpo/zYZATcx4h+7bMmDd3frqizkBg=="
+            "keyid": "48967bd6051d66cebf961f226a6ae4e90dce91ead9ac10c0f9aaa427d40c4c16",
+            "sig": "FL7TL3y1JgXinAkxywmKfoULNe2V8D+JpIcsJWok54rIun70z7bmj78R1VnNe9aADLSGQb0JTYhdaODn9mOnCg=="
           }
         ]
       },
       "newer": {
         "payloadType": "application/vnd.agent-custody.treehead+json",
-        "payload": "eyJyb290SGFzaCI6ImNlYmViNDAzYjNlZWYzYzgwNWVjYzg5OTI2NTM0ZGM0NjkxY2I4OWJlN2I0ZjFjNjE3Njg5MDFkMzIxNDkzYmEiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA2OjUyOjUxLjExNFoiLCJ0cmVlU2l6ZSI6Mn0=",
+        "payload": "eyJyb290SGFzaCI6IjUxY2MyNzIzMzM0NzhmMjYxNDU1MWFmMWM1NjExMzBjOTBlODEwM2JhYmI1NzNkZjY2YjM3ZTVhMDk1YjI0ZWYiLCJ0aW1lc3RhbXAiOiIyMDI2LTA5LTA3VDA4OjM3OjM0LjkzM1oiLCJ0cmVlU2l6ZSI6Mn0=",
         "signatures": [
           {
-            "keyid": "e1ed29255a4bd710006fe9ad333514e71c705608b769029088a818f57bcf080a",
-            "sig": "iyUBqiJcZd/RaEDXWhhxl34ekqy6tQ9qgsMQjAXlvuHS75aqPLeh0NRtUQB89LS2UMJYihmcSUdg/Z82uORqCQ=="
+            "keyid": "48967bd6051d66cebf961f226a6ae4e90dce91ead9ac10c0f9aaa427d40c4c16",
+            "sig": "o/zrDH6/I3VPabSVS4RozKm945Nd+hiwt6JTytpyMavxizlR8ZuGmG6lX56+A0M4wAk/H0qmmHXoLCGuobhdCw=="
           }
         ]
       },

package/vectors/canonical.json

@@ -53,18 +53,18 @@
     }
   ],
   "keyid": {
-    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAEb81f6KaNmH1pNR7KbeIUo9DW65Y0Qsfdxqbtnhs7cg=\n-----END PUBLIC KEY-----\n",
-    "keyid": "0ecde3bf114156b895ceb4ea63daa345271e8ee979f47bc69cbf0266bb93f6f5"
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEADBTs73puK6sTeOys85s6w1yJCBPt+eiQheOIszKqBiU=\n-----END PUBLIC KEY-----\n",
+    "keyid": "9dd265bc328e448488e35ec8ca89cc3b4270bfc6c8a0ba01845bb8867f1c7c60"
   },
   "dsse": {
-    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAEb81f6KaNmH1pNR7KbeIUo9DW65Y0Qsfdxqbtnhs7cg=\n-----END PUBLIC KEY-----\n",
+    "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEADBTs73puK6sTeOys85s6w1yJCBPt+eiQheOIszKqBiU=\n-----END PUBLIC KEY-----\n",
     "envelope": {
       "payloadType": "application/vnd.example+json",
       "payload": "eyJoZWxsbyI6IndvcmxkIn0=",
       "signatures": [
         {
-          "keyid": "0ecde3bf114156b895ceb4ea63daa345271e8ee979f47bc69cbf0266bb93f6f5",
-          "sig": "wkH8ufuyC3BJldxmhFUCImAOo38KyQO/uQMITvTjgikPeE9GIv6OwYEFtQnjcBNzY0+MRTn++dGeMwvVKzIBDw=="
+          "keyid": "9dd265bc328e448488e35ec8ca89cc3b4270bfc6c8a0ba01845bb8867f1c7c60",
+          "sig": "6zlQBbpy7oGNtH2d5gJ5ZmHzrKIjF8gT0XDkjhzafjCWWphFCcyZaVzZumJOjl6hnhzvu73FgHenAjyImMA0Cg=="
         }
       ]
     },