@agent-custody/receipts 0.1.6 → 0.1.7

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,8 @@ 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.
+- 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,7 +273,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. Provider-native upstream signatures (Stripe webhook signatures, GitHub delivery signatures) as adapters onto the upstream attestation field.
+2. Provider-native upstream signatures (Stripe webhook signatures, GitHub delivery signatures) as adapters onto the upstream attestation field. [Issue #7](https://github.com/ch4r10t33r/agent-custody/issues/7).
 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

@@ -6,6 +6,7 @@ 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";
@@ -18,6 +19,8 @@ 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]
   audit   --older <bundle.json> --newer <bundle.json> (--log <log.jsonl> | --log-url <url>) --issuer-key <pub> [--log-key <pub>] [--json]
@@ -93,6 +96,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,

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/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/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`.

package/docs/verification.md

@@ -173,3 +173,13 @@ On a gateway receipt the execution is `observed`: the gateway saw what the upstr
 
 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.
 
+## Retention on the log
+
+Receipts hold values: request arguments, results, facts. The log is append-only and hashed, so nothing can simply be deleted from it. `prune` is how retention reaches it without breaking a proof:
+
+```bash
+node src/cli.ts prune --log log.jsonl --before 2026-06-01T00:00:00Z --receipts receipts
+```
+
+Every leaf whose receipt is older than the cutoff is replaced in the file by its leaf hash, and the receipt's bundle file is deleted. The Merkle tree is built from leaf hashes, so every root, every inclusion proof, and every consistency proof for the remaining leaves is unchanged, and `--log` verification of later receipts still passes. Someone who kept a pruned receipt's bundle can still prove it was in the log; nobody holding only the log can recover what it said. Run it on the same schedule as memory retention.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "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": {
@@ -39,6 +39,10 @@
     "./sdk/langchain": {
       "types": "./dist/sdk/langchain.d.ts",
       "default": "./dist/sdk/langchain.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
     }
   },
   "files": [