@agent-custody/receipts 0.1.6 → 0.1.8

package/README.md

@@ -234,7 +234,8 @@ src/sidecar.ts     the SDK issuer behind a local HTTP API, for agents in other l
 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
+src/cli.ts         keygen, grant, gateway, hook, serve, log, prune, verify, audit
+src/retention.ts   pruning the log: leaves become their hashes, bundles are removed, proofs survive
 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 (signs its results with --key), a second fake upstream, fixture builders for gateway and SDK, demo
@@ -255,6 +256,9 @@ 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.
+- Provider-native deliveries: an upstream wrapping Stripe or GitHub attaches the signed webhook or delivery for the call; a verifier with the shared secret checks the HMAC, the timestamp, and the binding to the result, and reports the execution as attested by shared secret.
+- Logarithmic appends: the Merkle log caches complete subtrees, so issuing a receipt costs the same at the millionth leaf as at the first; measured at 0.15 ms per receipt and about half a millisecond per gateway call including policy, a fact lookup, and the upstream signature.
+- Retention on the log: `prune` replaces leaves older than a cutoff with their hashes and removes their bundles, so proofs still verify and the content is gone.
 - 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.
@@ -270,10 +274,9 @@ 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. 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.
-6. A TEE-hosted signer, then SD-JWT redaction, then ZK proofs of policy compliance. Not before.
+2. An HTTP transport for the gateway, with the grant presented per connection, for a shared deployment rather than one process per agent session.
+3. Delegation chains for sub-agents.
+4. Receiver-attested receipts for agent-to-agent calls.
+5. A TEE-hosted signer, then SD-JWT redaction, then ZK proofs of policy compliance. Not before.
 
 A Python SDK follows the same shape once the TypeScript adapters have settled.

package/dist/cli.js

@@ -6,11 +6,19 @@ import { generateKeyPair, loadPrivateKey, loadPublicKey, writeKeyPair } from "./
 import { createDelegation } from "./delegation.js";
 import { createGateway, serveStdio } from "./gateway.js";
 import { serveLog } from "./log-sink.js";
+import { pruneLog } from "./retention.js";
 import { serveSidecar } from "./sidecar.js";
 import { MerkleLog } from "./log.js";
 import { createSdkIssuer } from "./sdk/index.js";
 import { handleHookEvent } from "./sdk/claude.js";
 import { auditExtends, formatReport, verifyBundle } from "./verify.js";
+/** A shared secret from an environment variable; never from the command line, where it would land in shell history. */
+function secretFrom(envName) {
+    const v = process.env[envName];
+    if (!v)
+        throw new Error(`environment variable ${envName} is not set`);
+    return v;
+}
 const USAGE = `agent-custody <command>
 
   keygen  --dir <dir> --name <name>
@@ -18,8 +26,10 @@ const USAGE = `agent-custody <command>
   gateway --config <gateway.json>
   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>]
+          retention on the receipt log: replaces older leaves with their hashes, so proofs still verify and the content is gone
   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>] [--upstream-key <pub>] [--log <log.jsonl>] [--json]
+  verify  <bundle.json> --issuer-key <pub> [--principal-key <pub>] [--log-key <pub>] [--upstream-key <pub>] [--stripe-secret-env NAME] [--github-secret-env NAME] [--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
 `;
@@ -93,6 +103,16 @@ async function main(argv) {
             await running.close();
             return 0;
         }
+        case "prune": {
+            const { values } = parseArgs({ args: rest, options: { log: { type: "string" }, before: { type: "string" }, receipts: { type: "string" } } });
+            if (!values.log || !values.before)
+                throw new Error("prune needs --log and --before");
+            const r = pruneLog(values.log, new Date(values.before).toISOString(), values.receipts);
+            console.log(`pruned ${r.pruned.length} leaf(s), kept ${r.kept}, removed ${r.bundlesRemoved} bundle file(s)`);
+            for (const p of r.pruned)
+                console.log(`  leaf ${p.leafIndex}  ${p.timestamp}  receipt ${p.receiptId ?? "?"}`);
+            return 0;
+        }
         case "log": {
             const { values } = parseArgs({
                 args: rest,
@@ -120,6 +140,8 @@ async function main(argv) {
                     "principal-key": { type: "string", multiple: true },
                     "log-key": { type: "string", multiple: true },
                     "upstream-key": { type: "string", multiple: true },
+                    "stripe-secret-env": { type: "string" },
+                    "github-secret-env": { type: "string" },
                     log: { type: "string" },
                     json: { type: "boolean", default: false },
                 },
@@ -134,6 +156,7 @@ async function main(argv) {
                 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["stripe-secret-env"] || values["github-secret-env"] ? { providerSecrets: { ...(values["stripe-secret-env"] ? { stripe: secretFrom(values["stripe-secret-env"]) } : {}), ...(values["github-secret-env"] ? { github: secretFrom(values["github-secret-env"]) } : {}) } } : {}),
                 ...(values.log ? { logFile: values.log } : {}),
             });
             console.log(values.json ? JSON.stringify(result, null, 2) : formatReport(result));

package/dist/gateway.js

@@ -12,7 +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 { upstreamEvidenceOf } from "./upstream.js";
 import { evaluate, policyDigest } from "./policy.js";
 export const GATEWAY_VERSION = "0.1.0";
 export const RECEIPT_META_KEY = "agent-custody/receipt";
@@ -164,8 +164,8 @@ export async function createGateway(cfg) {
                 // state, such as the memory server, cites the receipt as the source of what it stores.
                 const observed = Object.fromEntries(Object.entries(facts).map(([k, f]) => [k, f.value]));
                 const result = await callUpstream(tool, args, { ...upstreamMeta, [OBSERVED_META_KEY]: observed });
-                const upstreamSig = upstreamSignatureOf(result);
-                execution = { status: result.isError ? "failed" : "executed", result, resultDigest: digestOf(result), provenance: "observed", ...(upstreamSig ? { upstream: { envelope: upstreamSig } } : {}) };
+                const evidence = upstreamEvidenceOf(result);
+                execution = { status: result.isError ? "failed" : "executed", result, resultDigest: digestOf(result), provenance: "observed", ...(evidence ? { upstream: evidence } : {}) };
                 noteServedFacts(result);
             }
             catch (e) {

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/log.d.ts

@@ -14,6 +14,7 @@ export declare function inclusionProof(leafHashes: Buffer[], leafIndex: number,
 export declare function verifyInclusion(leaf: Buffer, proof: InclusionProof, rootHex: string): boolean;
 export declare class MerkleLog {
     private hashes;
+    private readonly tree;
     private readonly file;
     constructor(file: string);
     get size(): number;

package/dist/log.js

@@ -20,34 +20,55 @@ function split(n) {
         k *= 2;
     return k;
 }
-function mth(leaves, lo, hi) {
-    const n = hi - lo;
-    if (n === 0)
-        return createHash("sha256").digest();
-    if (n === 1)
-        return leaves[lo];
-    const k = split(n);
-    return nodeHash(mth(leaves, lo, lo + k), mth(leaves, lo + k, hi));
-}
-function path(m, leaves, lo, hi) {
-    const n = hi - lo;
-    if (n <= 1)
-        return [];
-    const k = split(n);
-    return m < k
-        ? [...path(m, leaves, lo, lo + k), mth(leaves, lo + k, hi)]
-        : [...path(m - k, leaves, lo + k, hi), mth(leaves, lo, lo + k)];
+/**
+ * Subtree hashes over a growing list of leaves. A subtree over an aligned, complete, power-of-two range never changes
+ * once its leaves exist, so those are cached; everything else is recomputed from at most log(n) cached parts. That
+ * makes appends, roots, and proofs O(log n) instead of O(n), which is what keeps a long session's receipts cheap.
+ */
+class SubtreeCache {
+    perfect = new Map();
+    leaves;
+    constructor(leaves) {
+        this.leaves = leaves;
+    }
+    mth(lo, hi) {
+        const n = hi - lo;
+        if (n === 0)
+            return createHash("sha256").digest();
+        if (n === 1)
+            return this.leaves[lo];
+        const aligned = (n & (n - 1)) === 0 && lo % n === 0;
+        const key = aligned ? `${lo}:${hi}` : "";
+        if (aligned) {
+            const hit = this.perfect.get(key);
+            if (hit)
+                return hit;
+        }
+        const k = split(n);
+        const h = nodeHash(this.mth(lo, lo + k), this.mth(lo + k, hi));
+        if (aligned)
+            this.perfect.set(key, h);
+        return h;
+    }
+    path(m, lo, hi) {
+        const n = hi - lo;
+        if (n <= 1)
+            return [];
+        const k = split(n);
+        return m < k ? [...this.path(m, lo, lo + k), this.mth(lo + k, hi)] : [...this.path(m - k, lo + k, hi), this.mth(lo, lo + k)];
+    }
+    subproof(m, lo, hi, b) {
+        const n = hi - lo;
+        if (m === n)
+            return b ? [] : [this.mth(lo, hi)];
+        const k = split(n);
+        return m <= k ? [...this.subproof(m, lo, lo + k, b), this.mth(lo + k, hi)] : [...this.subproof(m - k, lo + k, hi, false), this.mth(lo, lo + k)];
+    }
 }
+const mth = (leaves, lo, hi) => new SubtreeCache(leaves).mth(lo, hi);
+const path = (m, leaves, lo, hi) => new SubtreeCache(leaves).path(m, lo, hi);
 /** RFC 9162 section 2.1.4.1: SUBPROOF(m, D[n], b). */
-function subproof(m, leaves, lo, hi, b) {
-    const n = hi - lo;
-    if (m === n)
-        return b ? [] : [mth(leaves, lo, hi)];
-    const k = split(n);
-    return m <= k
-        ? [...subproof(m, leaves, lo, lo + k, b), mth(leaves, lo + k, hi)]
-        : [...subproof(m - k, leaves, lo + k, hi, false), mth(leaves, lo, lo + k)];
-}
+const subproof = (m, leaves, lo, hi, b) => new SubtreeCache(leaves).subproof(m, lo, hi, b);
 /** Proof that the tree of size newSize extends the tree of size oldSize. Empty when oldSize is 0 or equal to newSize. */
 export function consistencyProof(leafHashes, oldSize, newSize = leafHashes.length) {
     if (oldSize < 0 || oldSize > newSize || newSize > leafHashes.length)
@@ -134,13 +155,18 @@ export function verifyInclusion(leaf, proof, rootHex) {
 }
 export class MerkleLog {
     hashes = [];
+    tree;
     file;
     constructor(file) {
         this.file = file;
+        this.tree = new SubtreeCache(this.hashes);
         if (existsSync(file)) {
             for (const line of readFileSync(file, "utf8").split("\n")) {
-                if (line.trim())
-                    this.hashes.push(leafHash(JSON.parse(line)));
+                if (!line.trim())
+                    continue;
+                const parsed = JSON.parse(line);
+                // A pruned leaf keeps only its hash: the tree, its roots, and every proof are unchanged; the content is gone.
+                this.hashes.push(typeof parsed === "string" ? leafHash(parsed) : Buffer.from(parsed.pruned, "hex"));
             }
         }
         else {
@@ -155,14 +181,20 @@ export class MerkleLog {
         appendFileSync(this.file, JSON.stringify(leaf) + "\n");
         this.hashes.push(leafHash(leaf));
         const treeSize = this.hashes.length;
-        return { ...inclusionProof(this.hashes, treeSize - 1, treeSize), rootHash: rootOf(this.hashes, treeSize) };
+        return { leafIndex: treeSize - 1, treeSize, hashes: this.tree.path(treeSize - 1, 0, treeSize).map((b) => b.toString("hex")), rootHash: this.tree.mth(0, treeSize).toString("hex") };
     }
     root(size = this.size) {
-        return rootOf(this.hashes, size);
+        if (size < 0 || size > this.size)
+            throw new Error("size out of range");
+        return this.tree.mth(0, size).toString("hex");
     }
     /** Proof that this log at newSize extends its own earlier state at oldSize. */
     consistencyProof(oldSize, newSize = this.size) {
-        return consistencyProof(this.hashes, oldSize, newSize);
+        if (oldSize < 0 || oldSize > newSize || newSize > this.size)
+            throw new Error("sizes out of range");
+        if (oldSize === 0 || oldSize === newSize)
+            return [];
+        return this.tree.subproof(oldSize, 0, newSize, true).map((b) => b.toString("hex"));
     }
     /** Reads a log file and returns the root at the given size, for auditors holding a copy of the log. */
     static rootFromFile(file, size) {

package/dist/receipt.d.ts

@@ -1,6 +1,7 @@
 import type { Envelope } from "./crypto.ts";
 import type { InclusionProof } from "./log.ts";
 import type { PolicyDecision } from "./policy.ts";
+import type { UpstreamEvidence } from "./upstream.ts";
 export declare const RECEIPT_TYPE = "application/vnd.in-toto+json";
 export declare const RECEIPT_PREDICATE_TYPE = "https://agent-custody.dev/receipt/v0.2";
 export declare const TREEHEAD_TYPE = "application/vnd.agent-custody.treehead+json";
@@ -90,10 +91,8 @@ 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;
-        };
+        /** an upstream's own signature over what it returned, bound to this receipt and checked with the upstream's key; or a provider's delivery, checked with the provider's shared secret */
+        upstream?: UpstreamEvidence;
     } | {
         status: "denied";
         reason: string;

package/dist/retention.d.ts

@@ -0,0 +1,14 @@
+export interface PruneResult {
+    pruned: {
+        leafIndex: number;
+        receiptId: string | null;
+        timestamp: string | null;
+    }[];
+    kept: number;
+    bundlesRemoved: number;
+}
+/**
+ * Prunes every leaf whose receipt timestamp is before the cutoff. Leaves already pruned, and leaves that are not
+ * receipts, are left as they are. Rewrites the log file in place and deletes the pruned receipts' bundle files.
+ */
+export declare function pruneLog(logFile: string, before: string, receiptsDir?: string): PruneResult;

package/dist/retention.js

@@ -0,0 +1,54 @@
+// Retention on the receipt log. A receipt's request arguments and results hold values, and the log is append-only and
+// hashed, so values cannot simply be deleted. Pruning replaces a leaf's content in the log file with its leaf hash:
+// the Merkle tree, every root, and every inclusion and consistency proof for the remaining leaves are unchanged, while
+// the pruned receipt's content is gone from the log and its bundle file is removed. A verifier holding a pruned
+// receipt's bundle can still prove inclusion; nobody holding only the log can recover what the receipt said.
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { leafHash } from "./log.js";
+function receiptOf(leaf) {
+    try {
+        const env = JSON.parse(leaf);
+        const st = JSON.parse(Buffer.from(env.payload, "base64").toString());
+        return { receiptId: st.predicate?.receiptId ?? null, timestamp: st.predicate?.timestamp ?? null };
+    }
+    catch {
+        return { receiptId: null, timestamp: null };
+    }
+}
+/**
+ * Prunes every leaf whose receipt timestamp is before the cutoff. Leaves already pruned, and leaves that are not
+ * receipts, are left as they are. Rewrites the log file in place and deletes the pruned receipts' bundle files.
+ */
+export function pruneLog(logFile, before, receiptsDir) {
+    const lines = readFileSync(logFile, "utf8").split("\n").filter((l) => l.trim());
+    const out = [];
+    const result = { pruned: [], kept: 0, bundlesRemoved: 0 };
+    lines.forEach((line, i) => {
+        const parsed = JSON.parse(line);
+        if (typeof parsed !== "string") {
+            out.push(line);
+            return;
+        }
+        const { receiptId, timestamp } = receiptOf(parsed);
+        if (timestamp !== null && timestamp < before) {
+            out.push(JSON.stringify({ pruned: leafHash(parsed).toString("hex") }));
+            result.pruned.push({ leafIndex: i, receiptId, timestamp });
+            if (receiptsDir && receiptId) {
+                const bundle = join(receiptsDir, `${receiptId}.json`);
+                if (existsSync(bundle)) {
+                    unlinkSync(bundle);
+                    result.bundlesRemoved++;
+                }
+            }
+        }
+        else {
+            out.push(line);
+            result.kept++;
+        }
+    });
+    const tmp = `${logFile}.tmp`;
+    writeFileSync(tmp, out.join("\n") + "\n");
+    renameSync(tmp, logFile);
+    return result;
+}

package/dist/upstream.d.ts

@@ -25,3 +25,40 @@ export type UpstreamCheck = {
 };
 /** 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;
+export interface ProviderAttestation {
+    provider: "stripe-webhook" | "github-delivery";
+    /** the delivery body exactly as received; the HMAC is over these bytes */
+    rawBody: string;
+    /** Stripe: the Stripe-Signature header; GitHub: the X-Hub-Signature-256 header */
+    signature: string;
+    /** dot path into the parsed body whose value must appear in the receipt's result, e.g. data.object.id */
+    bind: string;
+    /** GitHub: the X-GitHub-Delivery id, for the record */
+    deliveryId?: string;
+}
+export type UpstreamEvidence = {
+    envelope: Envelope;
+} | ProviderAttestation;
+export declare function isProviderAttestation(v: unknown): v is ProviderAttestation;
+/** For upstreams wrapping a provider: attaches the provider's own delivery for this call. */
+export declare function attachProviderAttestation<R extends CallToolResult>(result: R, attestation: ProviderAttestation): R;
+/** For the gateway: whatever upstream evidence the result carries, a signed envelope or a provider delivery. */
+export declare function upstreamEvidenceOf(result: CallToolResult): UpstreamEvidence | null;
+export interface ProviderSecrets {
+    stripe?: string;
+    github?: string;
+}
+export interface ProviderCheckContext {
+    /** the receipt's timestamp, for Stripe's timestamp tolerance */
+    timestamp: string;
+    /** the receipt's execution result; the bound value must appear in it */
+    result: unknown;
+    /** seconds a Stripe timestamp may differ from the receipt's; default 300 */
+    toleranceSeconds?: number;
+}
+/** Stripe: header `t=<unix>,v1=<hex>`, HMAC-SHA256 over `<t>.<rawBody>`; GitHub: header `sha256=<hex>` over rawBody. */
+export declare function checkProvider(att: ProviderAttestation, secrets: ProviderSecrets, ctx: ProviderCheckContext): UpstreamCheck;
+/** For fake providers and tests: a Stripe-Signature header for a body at a time. */
+export declare function stripeSignature(rawBody: string, secret: string, unixSeconds: number): string;
+/** For fake providers and tests: an X-Hub-Signature-256 header for a body. */
+export declare function githubSignature(rawBody: string, secret: string): string;

package/dist/upstream.js

@@ -1,3 +1,8 @@
+// Attested execution. An upstream that holds a key can sign what it returned, bound to the receipt the gateway is
+// issuing, so the receipt's execution is no longer only what the gateway observed but what the upstream itself vouches
+// for. The upstream puts a DSSE envelope on its result's _meta; the gateway embeds it; a verifier who trusts the
+// upstream's key checks it. Provider-native formats, such as Stripe's webhook signatures, are adapters on top of this.
+import { createHmac, timingSafeEqual } from "node:crypto";
 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";
@@ -30,3 +35,66 @@ export function checkUpstream(envelope, keys, expected) {
         return { ok: false, error: "signed content differs from the result in the receipt" };
     return { ok: true, keyid: v.keyid };
 }
+export function isProviderAttestation(v) {
+    const p = v;
+    return !!p && (p.provider === "stripe-webhook" || p.provider === "github-delivery") && typeof p.rawBody === "string" && typeof p.signature === "string" && typeof p.bind === "string";
+}
+/** For upstreams wrapping a provider: attaches the provider's own delivery for this call. */
+export function attachProviderAttestation(result, attestation) {
+    return { ...result, _meta: { ...result._meta, [UPSTREAM_SIG_META_KEY]: attestation } };
+}
+/** For the gateway: whatever upstream evidence the result carries, a signed envelope or a provider delivery. */
+export function upstreamEvidenceOf(result) {
+    const v = result._meta?.[UPSTREAM_SIG_META_KEY];
+    if (isProviderAttestation(v))
+        return v;
+    const env = upstreamSignatureOf(result);
+    return env ? { envelope: env } : null;
+}
+const pathValue = (body, path) => path.split(".").reduce((v, k) => (v && typeof v === "object" ? v[k] : undefined), body);
+/** Stripe: header `t=<unix>,v1=<hex>`, HMAC-SHA256 over `<t>.<rawBody>`; GitHub: header `sha256=<hex>` over rawBody. */
+export function checkProvider(att, secrets, ctx) {
+    const secret = att.provider === "stripe-webhook" ? secrets.stripe : secrets.github;
+    if (!secret)
+        return { ok: false, error: `no ${att.provider === "stripe-webhook" ? "Stripe" : "GitHub"} secret given` };
+    const hmac = (data) => createHmac("sha256", secret).update(data).digest("hex");
+    const equal = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+    if (att.provider === "stripe-webhook") {
+        const parts = Object.fromEntries(att.signature.split(",").map((kv) => kv.split("=")));
+        const t = parts.t;
+        const v1 = parts.v1;
+        if (!t || !v1)
+            return { ok: false, error: "Stripe-Signature header lacks t or v1" };
+        if (!equal(hmac(`${t}.${att.rawBody}`), v1))
+            return { ok: false, error: "Stripe signature does not verify with this secret" };
+        const skew = Math.abs(Number(t) * 1000 - Date.parse(ctx.timestamp)) / 1000;
+        if (!(skew <= (ctx.toleranceSeconds ?? 300)))
+            return { ok: false, error: `Stripe timestamp is ${Math.round(skew)}s from the receipt, beyond tolerance` };
+    }
+    else {
+        const hex = att.signature.startsWith("sha256=") ? att.signature.slice(7) : "";
+        if (!hex || !equal(hmac(att.rawBody), hex))
+            return { ok: false, error: "GitHub signature does not verify with this secret" };
+    }
+    let body;
+    try {
+        body = JSON.parse(att.rawBody);
+    }
+    catch {
+        return { ok: false, error: "delivery body is not JSON" };
+    }
+    const bound = pathValue(body, att.bind);
+    if (bound === undefined || bound === null || bound === "")
+        return { ok: false, error: `delivery has no value at ${att.bind}` };
+    if (!JSON.stringify(ctx.result).includes(JSON.stringify(bound).replace(/^"|"$/g, "")))
+        return { ok: false, error: `delivery's ${att.bind} (${String(bound)}) does not appear in the receipt's result` };
+    return { ok: true, keyid: `shared secret (${att.provider}, bound on ${att.bind})` };
+}
+/** For fake providers and tests: a Stripe-Signature header for a body at a time. */
+export function stripeSignature(rawBody, secret, unixSeconds) {
+    return `t=${unixSeconds},v1=${createHmac("sha256", secret).update(`${unixSeconds}.${rawBody}`).digest("hex")}`;
+}
+/** For fake providers and tests: an X-Hub-Signature-256 header for a body. */
+export function githubSignature(rawBody, secret) {
+    return `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`;
+}

package/dist/verify.d.ts

@@ -1,4 +1,5 @@
 import { type Envelope, type PublicKeyRef } from "./crypto.ts";
+import { type ProviderSecrets } from "./upstream.ts";
 import { type ReceiptBundle, type ReceiptStatement, type TreeHead } from "./receipt.ts";
 export interface Check {
     name: string;
@@ -13,6 +14,8 @@ export interface VerifyOptions {
     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[];
+    /** shared secrets for provider-native deliveries; with the matching one given, an execution carrying a Stripe or GitHub delivery is checked */
+    providerSecrets?: ProviderSecrets;
     /** 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,7 +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 { checkProvider, checkUpstream, contentDigest, isProviderAttestation } 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) {
@@ -45,10 +45,18 @@ 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) {
+    if ((p.execution.status === "executed" || p.execution.status === "failed") && p.execution.upstream) {
         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 (isProviderAttestation(p.execution.upstream)) {
+            if (opts.providerSecrets) {
+                const u = checkProvider(p.execution.upstream, opts.providerSecrets, { timestamp: p.timestamp, result });
+                add("upstream signature (provider secret)", u.ok, u.ok ? u.keyid : u.error);
+            }
+        }
+        else if ((opts.upstreamKeys?.length ?? 0) > 0) {
+            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";
@@ -137,8 +145,11 @@ export function formatReport(r) {
         row("policy", "-", "(none evaluated)");
     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 upstreamCheck = r.checks.find((c) => c.name === "upstream signature (upstream key)" || c.name === "upstream signature (provider secret)");
     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)") : ""}`);
+    const byProvider = hasUpstream && isProviderAttestation(p.execution.upstream);
+    const attestedAs = upstreamCheck?.ok ? (byProvider ? "attested (shared secret)" : "attested") : p.execution.provenance;
+    const note = !hasUpstream ? "" : upstreamCheck ? (upstreamCheck.ok ? ` (${byProvider ? upstreamCheck.detail : `signed by upstream ${upstreamCheck.detail}`})` : " (upstream signature FAILED)") : byProvider ? " (carries a provider delivery; pass the provider secret to check it)" : " (carries an upstream signature; pass --upstream-key to check it)";
+    row("execution", attestedAs, `${p.execution.status}${note}`);
     return lines.join("\n");
 }

package/docs/policies.md

@@ -104,6 +104,69 @@ permit(principal, action, resource)
 when { context.grant.principal == "user_456" };
 ```
 
+## Policies for memory
+
+The memory server in `@agent-custody/state` is an upstream like any other, so its tools are governed by the same policy file with the same request shape. What differs is what is in the context:
+
+| for | `context.args` carries | `context.facts` can carry |
+| --- | --- | --- |
+| `memory.write` | `subject`, `predicate`, `value`, `space`, and optionally `supersedes` and `evidence` | `target`, the fact being superseded, when the gateway is configured to look it up with `memory.get` |
+| `memory.read` | the query, and `includeClaimed` or `requireVerified` when the caller asks for them | |
+| `memory.retract`, `memory.forget`, `memory.hold`, `memory.release` | `factId` and `reason` | `target`, the fact being changed |
+| `memory.sweep` | `before`, `space`, `reason` | |
+| `memory.confirm` | `factId` | |
+
+A looked-up `target` has `space`, `actor`, `provenance` (`claimed`, `attested`, or `verified`), `subject`, `predicate`, `value`, and `retracted`. Fields that would be null are absent, so test with `has`. The lookup config that makes `target` available is in the [state package README](../../state/README.md#the-memory-server).
+
+**Confine an agent to its team's space.** Reads anywhere, writes only to one space.
+
+```cedar
+permit(principal, action == Action::"memory.read", resource);
+permit(principal, action == Action::"memory.write", resource)
+when { context.args.space == "team:support" };
+```
+
+**Keep quarantine closed.** Only a named reviewer may read claimed facts or lift them out of quarantine.
+
+```cedar
+permit(principal, action == Action::"memory.read", resource)
+unless { context.args has includeClaimed && context.args.includeClaimed == true && principal != Agent::"reviewer" };
+permit(principal == Agent::"reviewer", action == Action::"memory.confirm", resource);
+```
+
+**Require evidence for org memory.** A write to the org space must cite a fact the gateway fetched itself; the memory server then checks the value against it and writes it as verified, or refuses.
+
+```cedar
+permit(principal, action == Action::"memory.write", resource)
+when { context.args.space != "org" || context.args has evidence };
+```
+
+**Protect attested org facts from being displaced or retracted.** Needs the `target` lookup. A self-reported org note can be replaced; an attested one cannot.
+
+```cedar
+permit(principal, action in [Action::"memory.write", Action::"memory.retract"], resource);
+forbid(principal, action in [Action::"memory.write", Action::"memory.retract"], resource)
+when { context.facts has target && context.facts.target.space == "org" && context.facts.target.provenance == "attested" };
+```
+
+**Erasure and holds belong to named roles.** Everyone else is denied by default.
+
+```cedar
+permit(principal == Agent::"privacy-officer", action in [Action::"memory.forget", Action::"memory.sweep"], resource);
+permit(principal == Agent::"legal", action in [Action::"memory.hold", Action::"memory.release"], resource);
+```
+
+**A complete policy for a support agent.** The pieces above, together: read anywhere but not into quarantine, write team memory freely, write org memory only with evidence, retract only claimed facts, and no erasure or holds at all.
+
+```cedar
+permit(principal, action == Action::"memory.read", resource)
+unless { context.args has includeClaimed && context.args.includeClaimed == true };
+permit(principal, action == Action::"memory.write", resource)
+when { context.args.space == "team:support" || (context.args.space == "org" && context.args has evidence) };
+permit(principal, action == Action::"memory.retract", resource)
+when { context.facts has target && context.facts.target.provenance == "claimed" };
+```
+
 ## Gotchas
 
 - **Integers only.** `12.50` is not a Cedar value. Send `1250`.