@agent-custody/receipts 0.1.0 → 0.1.2

package/dist/log.js

@@ -38,6 +38,64 @@ function path(m, leaves, lo, hi) {
         ? [...path(m, leaves, lo, lo + k), mth(leaves, lo + k, hi)]
         : [...path(m - k, leaves, lo + k, hi), mth(leaves, lo, lo + k)];
 }
+/** 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)];
+}
+/** 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)
+        throw new Error("sizes out of range");
+    if (oldSize === 0 || oldSize === newSize)
+        return [];
+    return subproof(oldSize, leafHashes, 0, newSize, true).map((b) => b.toString("hex"));
+}
+/** RFC 9162 section 2.1.4.2. Pure: needs only the two sizes, the two roots, and the proof. */
+export function verifyConsistency(oldSize, oldRootHex, newSize, newRootHex, proofHex) {
+    if (oldSize < 0 || oldSize > newSize)
+        return false;
+    if (oldSize === newSize)
+        return proofHex.length === 0 && oldRootHex === newRootHex;
+    if (oldSize === 0)
+        return proofHex.length === 0;
+    if (proofHex.length === 0)
+        return false;
+    const proof = proofHex.map((x) => Buffer.from(x, "hex"));
+    if ((oldSize & (oldSize - 1)) === 0)
+        proof.unshift(Buffer.from(oldRootHex, "hex"));
+    let fn = oldSize - 1;
+    let sn = newSize - 1;
+    while (fn % 2 === 1) {
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    let fr = proof[0];
+    let sr = proof[0];
+    for (const c of proof.slice(1)) {
+        if (sn === 0)
+            return false;
+        if (fn % 2 === 1 || fn === sn) {
+            fr = nodeHash(c, fr);
+            sr = nodeHash(c, sr);
+            while (fn % 2 === 0 && fn !== 0) {
+                fn = Math.floor(fn / 2);
+                sn = Math.floor(sn / 2);
+            }
+        }
+        else {
+            sr = nodeHash(sr, c);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 && fr.toString("hex") === oldRootHex && sr.toString("hex") === newRootHex;
+}
 export function rootOf(leafHashes, size = leafHashes.length) {
     return mth(leafHashes, 0, size).toString("hex");
 }
@@ -102,6 +160,10 @@ export class MerkleLog {
     root(size = this.size) {
         return rootOf(this.hashes, size);
     }
+    /** Proof that this log at newSize extends its own earlier state at oldSize. */
+    consistencyProof(oldSize, newSize = this.size) {
+        return consistencyProof(this.hashes, oldSize, newSize);
+    }
     /** Reads a log file and returns the root at the given size, for auditors holding a copy of the log. */
     static rootFromFile(file, size) {
         return new MerkleLog(file).root(size);

package/dist/sdk/claude.d.ts

@@ -22,7 +22,7 @@ export interface HookOutput {
  * so the host's normal permission flow still applies. This adapter never auto-approves.
  * PostToolUse / PostToolUseFailure: issue the receipt for the completed call.
  */
-export declare function handleHookEvent(issuer: SdkIssuer, input: HookInput): HookOutput;
+export declare function handleHookEvent(issuer: SdkIssuer, input: HookInput): Promise<HookOutput>;
 /**
  * Hooks for the Claude Agent SDK's query({ hooks }) option. Register all three events.
  * Typed loosely on purpose so this file does not depend on the SDK package.

package/dist/sdk/claude.js

@@ -11,14 +11,14 @@ function toEvent(input) {
  * so the host's normal permission flow still applies. This adapter never auto-approves.
  * PostToolUse / PostToolUseFailure: issue the receipt for the completed call.
  */
-export function handleHookEvent(issuer, input) {
+export async function handleHookEvent(issuer, input) {
     const ev = toEvent(input);
     switch (input.hook_event_name) {
         case "PreToolUse": {
             const policy = issuer.decide(ev);
             if (policy && policy.decision === "deny") {
                 const reason = [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched";
-                const bundle = issuer.record(ev, { status: "denied", reason }, policy);
+                const bundle = await issuer.record(ev, { status: "denied", reason }, policy);
                 return {
                     continue: true,
                     hookSpecificOutput: {
@@ -31,10 +31,10 @@ export function handleHookEvent(issuer, input) {
             return {};
         }
         case "PostToolUse":
-            issuer.record(ev, { status: "executed", result: input.tool_response ?? null }, issuer.decide(ev));
+            await issuer.record(ev, { status: "executed", result: input.tool_response ?? null }, issuer.decide(ev));
             return {};
         case "PostToolUseFailure":
-            issuer.record(ev, { status: "failed", result: input.error ?? input.tool_response ?? null }, issuer.decide(ev));
+            await issuer.record(ev, { status: "failed", result: input.error ?? input.tool_response ?? null }, issuer.decide(ev));
             return {};
         default:
             return {};

package/dist/sdk/index.d.ts

@@ -1,4 +1,5 @@
 import type { SdkConfig } from "../config.ts";
+import { type LogSink } from "../log-sink.ts";
 import { type PolicyDecision } from "../policy.ts";
 import type { ReceiptBundle } from "../receipt.ts";
 export declare const SDK_VERSION = "0.1.0";
@@ -24,10 +25,12 @@ export type Outcome = {
 export interface SdkIssuer {
     agentId: string;
     keyid: string;
+    /** where the leaves go: the local file or the remote log */
+    log: LogSink;
     /** Evaluates the configured policy for a call. Returns null when no policy is configured. */
     decide(ev: ToolEvent): PolicyDecision | null;
-    /** Issues one receipt for a completed, failed, denied, or errored call. */
-    record(ev: ToolEvent, outcome: Outcome, policy?: PolicyDecision | null): ReceiptBundle;
+    /** Issues one receipt for a completed, failed, denied, or errored call. Rejects if the log refuses it. */
+    record(ev: ToolEvent, outcome: Outcome, policy?: PolicyDecision | null): Promise<ReceiptBundle>;
     /** Wraps a tool function: decide, run, record. Throws PolicyDeniedError on deny, after issuing the denial receipt. */
     wrap<A extends Record<string, unknown>, R>(tool: string, fn: (args: A) => R | Promise<R>, meta?: Omit<ToolEvent, "tool" | "args">): (args: A) => Promise<R>;
 }

package/dist/sdk/index.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { digestOf, loadPrivateKey } from "../crypto.js";
 import { createIssuer } from "../issue.js";
+import { openLog } from "../log-sink.js";
 import { evaluate } from "../policy.js";
 export const SDK_VERSION = "0.1.0";
 export class PolicyDeniedError extends Error {
@@ -20,7 +21,7 @@ export class PolicyDeniedError extends Error {
 }
 export function createSdkIssuer(cfg) {
     const key = loadPrivateKey(cfg.identity.keyFile);
-    const issuer = createIssuer(key, cfg.receiptsDir, cfg.logFile);
+    const issuer = createIssuer(key, cfg.receiptsDir, openLog(cfg, key));
     const policyText = cfg.policyFile ? readFileSync(cfg.policyFile, "utf8") : null;
     const decide = (ev) => policyText === null ? null : evaluate(policyText, { agentId: cfg.agentId, tool: ev.tool, context: { args: ev.args, facts: {} } });
     function record(ev, outcome, policy = null) {
@@ -47,6 +48,7 @@ export function createSdkIssuer(cfg) {
     return {
         agentId: cfg.agentId,
         keyid: issuer.keyid,
+        log: issuer.log,
         decide,
         record,
         wrap(tool, fn, meta = {}) {
@@ -55,16 +57,16 @@ export function createSdkIssuer(cfg) {
                 const policy = decide(ev);
                 if (policy && policy.decision === "deny") {
                     const reason = [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched";
-                    const bundle = record(ev, { status: "denied", reason }, policy);
+                    const bundle = await record(ev, { status: "denied", reason }, policy);
                     throw new PolicyDeniedError(tool, reason, receiptIdOf(bundle));
                 }
                 try {
                     const result = await fn(args);
-                    record(ev, { status: "executed", result }, policy);
+                    await record(ev, { status: "executed", result }, policy);
                     return result;
                 }
                 catch (e) {
-                    record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
+                    await record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
                     throw e;
                 }
             };

package/dist/sdk/langchain.d.ts

@@ -8,8 +8,8 @@ export declare class ReceiptCallbackHandler extends BaseCallbackHandler {
     handleToolStart(tool: {
         name?: string;
     }, input: string, runId: string, _parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, runName?: string, toolCallId?: string): void;
-    handleToolEnd(output: unknown, runId: string): void;
-    handleToolError(err: Error, runId: string): void;
+    handleToolEnd(output: unknown, runId: string): Promise<void>;
+    handleToolError(err: Error, runId: string): Promise<void>;
 }
 /** Convenience: `tool.invoke(args, receiptCallbacks(issuer))`, or spread into any RunnableConfig. */
 export declare function receiptCallbacks(issuer: SdkIssuer): {

package/dist/sdk/langchain.js

@@ -40,19 +40,19 @@ export class ReceiptCallbackHandler extends BaseCallbackHandler {
         const name = runName ?? tool.name ?? "unknown";
         this.pending.set(runId, { tool: name, args: parseArgs(input), session: { id: null, toolUseId: toolCallId ?? null } });
     }
-    handleToolEnd(output, runId) {
+    async handleToolEnd(output, runId) {
         const ev = this.pending.get(runId);
         if (!ev)
             return;
         this.pending.delete(runId);
-        this.issuer.record(ev, { status: "executed", result: unwrapOutput(output) }, null);
+        await this.issuer.record(ev, { status: "executed", result: unwrapOutput(output) }, null);
     }
-    handleToolError(err, runId) {
+    async handleToolError(err, runId) {
         const ev = this.pending.get(runId);
         if (!ev)
             return;
         this.pending.delete(runId);
-        this.issuer.record(ev, { status: "error", error: err.message }, null);
+        await this.issuer.record(ev, { status: "error", error: err.message }, null);
     }
 }
 /** Convenience: `tool.invoke(args, receiptCallbacks(issuer))`, or spread into any RunnableConfig. */

package/dist/sdk/openai-agents.js

@@ -33,16 +33,16 @@ export function wrapTools(issuer, tools) {
             const policy = issuer.decide(ev);
             if (policy && policy.decision === "deny") {
                 const reason = [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched";
-                const bundle = issuer.record(ev, { status: "denied", reason }, policy);
+                const bundle = await issuer.record(ev, { status: "denied", reason }, policy);
                 return `Denied by policy: ${reason} (receipt ${receiptIdOf(bundle)})`;
             }
             try {
                 const result = await t.invoke(ctx, input, details);
-                issuer.record(ev, { status: "executed", result: parseResult(result) }, policy);
+                await issuer.record(ev, { status: "executed", result: parseResult(result) }, policy);
                 return result;
             }
             catch (e) {
-                issuer.record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
+                await issuer.record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
                 throw e;
             }
         };
@@ -61,6 +61,7 @@ export function observeRunner(issuer, runner) {
         const callId = details?.toolCall?.callId ?? "";
         const ev = pending.get(callId) ?? { tool: tool.name, args: {}, session: { id: null, toolUseId: callId || null } };
         pending.delete(callId);
-        issuer.record(ev, { status: "executed", result: parseResult(result) }, null);
+        // The runner does not await listeners. A log that refuses the leaf is reported on stderr; nothing else can see it here.
+        issuer.record(ev, { status: "executed", result: parseResult(result) }, null).catch((e) => console.error(`agent-custody: receipt not issued: ${e instanceof Error ? e.message : e}`));
     });
 }

package/dist/sdk/vercel-ai.js

@@ -16,16 +16,16 @@ export function wrapTools(issuer, tools) {
             const policy = issuer.decide(ev);
             if (policy && policy.decision === "deny") {
                 const reason = [...policy.reasons, ...policy.errors].join("; ") || "no permit policy matched";
-                const bundle = issuer.record(ev, { status: "denied", reason }, policy);
+                const bundle = await issuer.record(ev, { status: "denied", reason }, policy);
                 throw new PolicyDeniedError(name, reason, receiptIdOf(bundle));
             }
             try {
                 const result = await original(input, options);
-                issuer.record(ev, { status: "executed", result }, policy);
+                await issuer.record(ev, { status: "executed", result }, policy);
                 return result;
             }
             catch (e) {
-                issuer.record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
+                await issuer.record(ev, { status: "error", error: e instanceof Error ? e.message : String(e) }, policy);
                 throw e;
             }
         };

package/dist/sidecar.d.ts

@@ -0,0 +1,12 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { SdkIssuer } from "./sdk/index.ts";
+export declare function sidecarHandler(issuer: SdkIssuer): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface RunningSidecar {
+    url: string;
+    close(): Promise<void>;
+}
+/** Starts the sidecar. Port 0 picks a free port. Host defaults to loopback on purpose. */
+export declare function serveSidecar(issuer: SdkIssuer, opts: {
+    port: number;
+    host?: string;
+}): Promise<RunningSidecar>;

package/dist/sidecar.js

@@ -0,0 +1,93 @@
+// The sidecar: the SDK issuer behind a local HTTP API, so agents written in any language can decide and record.
+// Same config file, same receipts, same key. Everything it records is claimed, exactly as with the in-process SDK:
+// the sidecar trusts what the agent's process tells it. Bind it to localhost; it is a per-host companion, not a service.
+//   GET  /health                      -> { agentId, keyid, log: { kind, where } }
+//   POST /decide  ToolEvent           -> PolicyDecision | null
+//   POST /record  { event, outcome, policy? } -> ReceiptBundle, or 4xx/5xx with { error }
+import { createServer } from "node:http";
+const isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function parseEvent(v) {
+    if (!isRecord(v) || typeof v.tool !== "string" || v.tool.length === 0)
+        throw new Error("event needs a non-empty string tool");
+    const args = isRecord(v.args) ? v.args : v.args === undefined ? {} : { input: v.args };
+    const ev = { tool: v.tool, args };
+    if (typeof v.model === "string")
+        ev.model = v.model;
+    if (isRecord(v.session))
+        ev.session = { id: typeof v.session.id === "string" ? v.session.id : null, toolUseId: typeof v.session.toolUseId === "string" ? v.session.toolUseId : null };
+    return ev;
+}
+function parseOutcome(v) {
+    if (!isRecord(v) || typeof v.status !== "string")
+        throw new Error("outcome needs a status");
+    switch (v.status) {
+        case "executed":
+        case "failed":
+            return { status: v.status, result: v.result ?? null };
+        case "denied":
+            return { status: "denied", reason: typeof v.reason === "string" ? v.reason : "denied" };
+        case "error":
+            return { status: "error", error: typeof v.error === "string" ? v.error : "error" };
+        default:
+            throw new Error(`unknown outcome status ${v.status}`);
+    }
+}
+function parsePolicy(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (!isRecord(v) || (v.decision !== "allow" && v.decision !== "deny") || !Array.isArray(v.reasons) || !Array.isArray(v.errors) || typeof v.policyDigest !== "string")
+        throw new Error("policy must be a PolicyDecision from /decide");
+    return { decision: v.decision, reasons: v.reasons.map(String), errors: v.errors.map(String), policyDigest: v.policyDigest };
+}
+export function sidecarHandler(issuer) {
+    return async (req, res) => {
+        const json = (status, body) => {
+            res.writeHead(status, { "content-type": "application/json" });
+            res.end(JSON.stringify(body));
+        };
+        const url = new URL(req.url ?? "/", "http://localhost");
+        try {
+            if (req.method === "GET" && url.pathname === "/health")
+                return json(200, { agentId: issuer.agentId, keyid: issuer.keyid, log: { kind: issuer.log.kind, where: issuer.log.where } });
+            if (req.method !== "POST")
+                return json(404, { error: "not found" });
+            let raw = "";
+            for await (const chunk of req)
+                raw += chunk;
+            let body;
+            try {
+                body = JSON.parse(raw);
+            }
+            catch {
+                return json(400, { error: "body must be JSON" });
+            }
+            if (url.pathname === "/decide")
+                return json(200, issuer.decide(parseEvent(body)));
+            if (url.pathname === "/record") {
+                if (!isRecord(body))
+                    return json(400, { error: "body must be {event, outcome, policy?}" });
+                const bundle = await issuer.record(parseEvent(body.event), parseOutcome(body.outcome), parsePolicy(body.policy));
+                return json(200, bundle);
+            }
+            return json(404, { error: "not found" });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return json(/needs|must|unknown outcome/.test(msg) ? 400 : 502, { error: msg });
+        }
+    };
+}
+/** Starts the sidecar. Port 0 picks a free port. Host defaults to loopback on purpose. */
+export function serveSidecar(issuer, opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const handler = sidecarHandler(issuer);
+    const server = createServer((req, res) => {
+        void handler(req, res);
+    });
+    return new Promise((resolve) => {
+        server.listen(opts.port, host, () => {
+            const { port } = server.address();
+            resolve({ url: `http://${host}:${port}/`, close: () => new Promise((r) => server.close(() => r())) });
+        });
+    });
+}

package/dist/verify.d.ts

@@ -1,5 +1,5 @@
-import { type PublicKeyRef } from "./crypto.ts";
-import { type ReceiptBundle, type ReceiptStatement } from "./receipt.ts";
+import { type Envelope, type PublicKeyRef } from "./crypto.ts";
+import { type ReceiptBundle, type ReceiptStatement, type TreeHead } from "./receipt.ts";
 export interface Check {
     name: string;
     ok: boolean;
@@ -9,6 +9,8 @@ export interface VerifyOptions {
     /** keys trusted to have issued receipts: gateway keys, SDK application keys */
     issuerKeys: PublicKeyRef[];
     principalKeys: PublicKeyRef[];
+    /** keys of logs run by someone other than the issuer; tree heads are checked against these and the issuer keys */
+    logKeys?: PublicKeyRef[];
     /** If given, the root is recomputed from this log file at the receipt's tree size and compared. */
     logFile?: string;
 }
@@ -18,5 +20,16 @@ export interface VerifyResult {
     statement: ReceiptStatement | null;
 }
 export declare function verifyBundle(bundle: ReceiptBundle, opts: VerifyOptions): VerifyResult;
+export interface AuditResult {
+    ok: boolean;
+    checks: Check[];
+    older: TreeHead | null;
+    newer: TreeHead | null;
+}
+/**
+ * Does the newer tree head extend the older one? Both must be signed by a trusted log or issuer key, and the proof
+ * must be the log's consistency proof between the two sizes. A pass means nothing in the older log was rewritten.
+ */
+export declare function auditExtends(older: Envelope, newer: Envelope, proof: string[], keys: PublicKeyRef[]): AuditResult;
 /** Human-readable report: checks, then every field with its provenance so the reader knows what was proven vs. claimed. */
 export declare function formatReport(r: VerifyResult): string;

package/dist/verify.js

@@ -1,7 +1,7 @@
 // Independent verification of a receipt bundle. Needs only public keys, and optionally a copy of the log.
 import { canonicalize, digestOf, dsseVerify } from "./crypto.js";
 import { delegationValidAt, verifyDelegation } from "./delegation.js";
-import { leafHash, MerkleLog, verifyInclusion } from "./log.js";
+import { leafHash, MerkleLog, verifyConsistency, verifyInclusion } from "./log.js";
 import { RECEIPT_PREDICATE_TYPE, RECEIPT_TYPE, TREEHEAD_TYPE } from "./receipt.js";
 const short = (s) => s.slice(0, 12);
 export function verifyBundle(bundle, opts) {
@@ -49,8 +49,10 @@ export function verifyBundle(bundle, opts) {
         add("policy decision consistent with execution", consistent, `${p.policy.decision} -> ${p.execution.status}`);
         add("no policy errors on an allow", !(p.policy.decision === "allow" && p.policy.errors.length > 0));
     }
-    const th = dsseVerify(bundle.treeHead, opts.issuerKeys);
-    add("tree head signature", th.ok && bundle.treeHead.payloadType === TREEHEAD_TYPE, th.ok ? undefined : th.error);
+    const logKeys = opts.logKeys ?? [];
+    const th = dsseVerify(bundle.treeHead, [...logKeys, ...opts.issuerKeys]);
+    const byLog = th.ok && logKeys.some((k) => k.keyid === th.keyid);
+    add("tree head signature", th.ok && bundle.treeHead.payloadType === TREEHEAD_TYPE, th.ok ? `${byLog ? "log key" : "issuer key"} ${short(th.keyid)}` : th.error);
     if (th.ok) {
         const head = th.payload;
         add("tree head matches inclusion proof size", head.treeSize === bundle.inclusion.treeSize);
@@ -70,6 +72,31 @@ export function verifyBundle(bundle, opts) {
     }
     return done(st);
 }
+/**
+ * Does the newer tree head extend the older one? Both must be signed by a trusted log or issuer key, and the proof
+ * must be the log's consistency proof between the two sizes. A pass means nothing in the older log was rewritten.
+ */
+export function auditExtends(older, newer, proof, keys) {
+    const checks = [];
+    const add = (name, ok, detail) => {
+        checks.push(detail === undefined ? { name, ok } : { name, ok, detail });
+        return ok;
+    };
+    const decode = (label, env) => {
+        const v = dsseVerify(env, keys);
+        add(`${label} tree head signature`, v.ok && env.payloadType === TREEHEAD_TYPE, v.ok ? `keyid ${short(v.keyid)}` : v.error);
+        return v.ok ? v.payload : null;
+    };
+    const a = decode("older", older);
+    const b = decode("newer", newer);
+    if (!a || !b)
+        return { ok: false, checks, older: a, newer: b };
+    if (!add("older is not larger than newer", a.treeSize <= b.treeSize, `${a.treeSize} -> ${b.treeSize}`))
+        return { ok: false, checks, older: a, newer: b };
+    const consistent = verifyConsistency(a.treeSize, a.rootHash, b.treeSize, b.rootHash, proof);
+    add("newer log extends older log", consistent, consistent ? `${proof.length} proof hashes` : "history was rewritten, or the proof is for other tree heads");
+    return { ok: checks.every((c) => c.ok), checks, older: a, newer: b };
+}
 const ISSUER_NOTE = {
     gateway: "enforced outside the agent's process; the agent could neither skip nor forge this receipt",
     sdk: "self-reported by the agent's own process; tamper-evident after issue, but nothing here was enforced outside the agent",

package/docs/sdk.md

@@ -28,7 +28,7 @@ Use the SDK for reach. Use the gateway for anything that moves money, touches pr
 }
 ```
 
-`policyFile` and `principalId` are optional. Without a policy the SDK records and never denies. Paths resolve relative to the config file. Generate the key with `node src/cli.ts keygen --dir keys --name app`.
+`policyFile` and `principalId` are optional. Without a policy the SDK records and never denies. Paths resolve relative to the config file. Instead of `logFile`, `"log": { "url": "https://log.example.com/", "tokenEnv": "AGENT_CUSTODY_LOG_TOKEN" }` sends every leaf to a log run by someone else, whose key then signs the tree heads; see [usage.md](usage.md) for what that changes and [verification.md](verification.md) for what it proves. Generate the key with `node src/cli.ts keygen --dir keys --name app`.
 
 Policies see `context.args` and an empty `context.facts`. A policy that reads `context.facts` or `context.grant` errors, which is a deny. That is intended: an SDK policy cannot pretend it checked something outside the agent's process.
 
@@ -154,9 +154,11 @@ For finer control use the two primitives `wrap` is built from:
 
 ```ts
 const decision = issuer.decide({ tool, args });                       // PolicyDecision | null
-const bundle = issuer.record({ tool, args, model, session }, { status: "executed", result }, decision);
+const bundle = await issuer.record({ tool, args, model, session }, { status: "executed", result }, decision);
 ```
 
+`record` returns a promise because the log may be remote. It rejects, and writes no bundle, if the log refuses the leaf. `handleHookEvent` is asynchronous for the same reason. The record-only adapters that cannot await, such as `observeRunner`, report a refused leaf on stderr.
+
 ## Which adapter enforces
 
 | framework | enforce + record | record only |
@@ -175,3 +177,26 @@ The three framework packages are optional peer dependencies. Each adapter import
 ## What an SDK receipt is worth
 
 A verified SDK receipt establishes that a process holding the application key reported this call, at this time, with these arguments and this result, and that the record has not changed since. It does not establish that the process reported every call, that the arguments are what the tool really received, or that anyone outside the process checked anything. The verifier prints exactly that sentence under `ISSUER`. Keep it in the dashboard too.
+
+## Other languages: the sidecar
+
+The interceptor above is TypeScript. Agents in any other language get the same receipts through the sidecar: the SDK issuer behind a local HTTP API, started from the same config file.
+
+```bash
+agent-custody serve --config sdk.json          # 127.0.0.1:8788 by default; --port and --host to change
+```
+
+| | |
+| --- | --- |
+| `GET /health` | `{ agentId, keyid, log: { kind, where } }` |
+| `POST /decide` with a `ToolEvent` `{ tool, args, model?, session? }` | the `PolicyDecision`, or `null` when no policy is configured |
+| `POST /record` with `{ event, outcome, policy? }` | the `ReceiptBundle`; `outcome` is `{ status: "executed" \| "failed", result }`, `{ status: "denied", reason }`, or `{ status: "error", error }` |
+
+The client's loop is decide, run the tool, record. A malformed body gets a 400 and nothing is written; a log that refuses the leaf gets a 502 and nothing is written. Bind the sidecar to loopback: it is a per-host companion holding the signing key, not a shared service, and everything it records is `claimed` exactly as with the in-process SDK, because it trusts what the client reports.
+
+**Python** has a real package, [packages/python](../../python/README.md): `pip install agent-custody`, a standard-library client with `decide`, `record`, and `wrap`, and adapters for LangChain callbacks, OpenAI Agents function tools, and Claude Agent SDK hooks, each tested against the real package with receipts checked by this verifier.
+
+**Go, Java, Rust, and Python without the package** each have a complete client in [examples/languages](../examples/languages): one file, standard library where the language has an HTTP client, decide then record. The test suite runs every one of them against a live sidecar. Any language with an HTTP client is the same forty lines.
+
+The gateway needs none of this. It is an MCP server, so a Python or Go agent host that speaks MCP puts it in front of its tools with a config change; [usage.md](usage.md) shows the Python hosts.
+

package/docs/tutorials.md

@@ -22,6 +22,9 @@ Suggested reading order is the numbering. Output lands in `examples-out/`, which
 | 10 | Vercel AI SDK | [10-vercel-ai.ts](../examples/10-vercel-ai.ts) | a real generateText loop over the SDK's mock model, a denial as a tool-error part | `src/sdk/vercel-ai.ts` |
 | 11 | LangChain | [11-langchain.ts](../examples/11-langchain.ts) | the callback handler, tool_call ids, enforcement by wrapping the function | `src/sdk/langchain.ts` |
 | 12 | inside a receipt | [12-read-a-receipt.ts](../examples/12-read-a-receipt.ts) | the bundle's three parts, the in-toto statement, every predicate field with its provenance, the tree head | `src/receipt.ts` |
+| 13 | a log run by someone else | [13-remote-log.ts](../examples/13-remote-log.ts) | the reference log server on a free port, an SDK config that logs to it, a tree head signed by the log's key, verification failing without that key and passing with it, the root endpoint, a refused token | `src/log-sink.ts` |
+| 14 | proving history was not rewritten | [14-audit-history.ts](../examples/14-audit-history.ts) | three receipts and a kept tree head, a consistency proof that passes, the operator rewriting one leaf and appending a fourth call, the audit failing while the fourth receipt still verifies alone | `src/log.ts`, `src/verify.ts` |
+| 15 | agents in other languages | [15-sidecar.ts](../examples/15-sidecar.ts) | the sidecar on a free port, a client written as a Python or Go program would write it: decide, run, record; a denial recorded without running the tool; both receipts verified | `src/sidecar.ts` |
 
 ## How policies are defined, in one paragraph
 

package/docs/usage.md

@@ -79,6 +79,14 @@ 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.
 
+`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`:
+
+```json
+  "log": { "url": "https://log.example.com/", "tokenEnv": "AGENT_CUSTODY_LOG_TOKEN" }
+```
+
+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.
 
 **5. Run the gateway.** It speaks MCP on stdin/stdout and logs to stderr only.
@@ -116,6 +124,31 @@ Claude sees only the tools inside the grant's scopes. Every call it makes produc
 claude mcp add stripe -- node /abs/path/agent-custody/packages/receipts/src/cli.ts gateway --config /abs/path/gateway.json
 ```
 
+### Python hosts
+
+The gateway is language-neutral: any host that can launch a stdio MCP server can use it. Claude Agent SDK for Python:
+
+```python
+from claude_agent_sdk import ClaudeAgentOptions, query
+
+options = ClaudeAgentOptions(mcp_servers={"stripe": {"command": "node", "args": ["/abs/path/agent-custody/packages/receipts/src/cli.ts", "gateway", "--config", "/abs/path/gateway.json"]}})
+async for message in query(prompt="Refund customer cust_123 by 50 dollars", options=options):
+    ...
+```
+
+OpenAI Agents SDK for Python:
+
+```python
+from agents import Agent, Runner
+from agents.mcp import MCPServerStdio
+
+async with MCPServerStdio(params={"command": "node", "args": ["/abs/path/agent-custody/packages/receipts/src/cli.ts", "gateway", "--config", "/abs/path/gateway.json"]}) as stripe:
+    agent = Agent(name="support", instructions="...", mcp_servers=[stripe])
+    result = await Runner.run(agent, "Refund customer cust_123 by 50 dollars")
+```
+
+With the npm package installed globally, `"command": "agent-custody", "args": ["gateway", "--config", ...]` replaces the node invocation. Every tool the agent sees comes through the gateway; denied calls never reach Stripe and still produce a receipt. For receipts from tools that are plain Python functions rather than MCP servers, use the sidecar and the Python package, in [sdk.md](sdk.md).
+
 ### Your own agent loop (TypeScript)
 
 This is what [scripts/demo.ts](../scripts/demo.ts) does.

package/docs/verification.md

@@ -6,7 +6,9 @@ A verifier needs three things and no network access:
 2. the issuer's public key: the gateway key, or the application key for SDK receipts
 3. the principal's public key, for gateway receipts, which carry a signed delegation
 
-A fourth is optional: a copy of the issuer's log file, which lets the verifier confirm the receipt sits in a log whose root the verifier recomputed, not one the issuer merely asserted.
+A fourth is optional: a copy of the log file, which lets the verifier confirm the receipt sits in a log whose root the verifier recomputed, not one the issuer merely asserted.
+
+When the issuer logs to a remote log, the tree head is signed by the log's key rather than the issuer's. The verifier then needs that public key too, and the report says which key signed the tree head. That is the point of a remote log: a tree head signed by a party that is not the operator says the receipt was in a log the operator could not rewrite. A tree head signed by the issuer's own key says only that the issuer has not changed its story since.
 
 ## From the command line
 
@@ -14,6 +16,7 @@ A fourth is optional: a copy of the issuer's log file, which lets the verifier c
 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
   --log log.jsonl          # optional
 ```
 
@@ -106,6 +109,7 @@ const bundle = JSON.parse(readFileSync("receipts/<id>.json", "utf8"));
 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
   logFile: "log.jsonl",           // optional
 });
 
@@ -128,7 +132,7 @@ The formats are standard on purpose, so a verifier in another language needs no
 
 ## Auditing a log copy
 
-Take copies of `log.jsonl` on a schedule and keep them where the operator cannot write. Then for any receipt:
+Take copies of `log.jsonl` on a schedule and keep them where the operator cannot write. A remote log serves `GET /root?size=N` so an auditor can compare a tree head with the log's own root without a copy; example 13 does this. Then for any receipt:
 
 ```bash
 node src/cli.ts verify receipts/<id>.json --issuer-key ... --principal-key ... --log /audit/copies/log-2026-09-04.jsonl
@@ -137,3 +141,19 @@ node src/cli.ts verify receipts/<id>.json --issuer-key ... --principal-key ... -
 The last check recomputes the root at the receipt's tree size from your copy. If the operator later deletes, reorders, or edits a line before that position, the recomputed root changes and the check fails.
 
 Today a copy must be at least as long as the receipt's tree size. Consistency proofs between two tree heads, which would let you check that a newer log extends an older copy without holding the whole file, are on the roadmap.
+
+## Proving history was not rewritten
+
+An inclusion proof says a receipt was in the log at one moment. It does not say the log still contains, unchanged, everything it contained earlier. That is what a consistency proof is for: given two tree heads, it proves the larger tree extends the smaller one, so nothing before the older head was rewritten. Keep the tree head from any receipt; it is the older head in every later audit.
+
+```bash
+node src/cli.ts audit --older receipts/<earlier>.json --newer receipts/<later>.json --log log.jsonl --issuer-key keys/gateway.pub
+node src/cli.ts audit --older receipts/<earlier>.json --newer receipts/<later>.json --log-url https://log.example.com/ --log-key keys/log.pub
+```
+
+Both tree heads must be signed by a trusted key. With `--log` the proof is computed from a copy of the log; with `--log-url` it is fetched from the log's `GET /consistency?old=M&new=N`. Exit code 0 means the newer log extends the older one. A failure means either history was rewritten between the two heads or the proof belongs to other tree heads; example 14 shows a rewritten log failing this way while every individual receipt still verifies.
+
+Programmatically, `auditExtends(older.treeHead, newer.treeHead, proof, keys)` returns the same checks. The proof algorithm is RFC 9162 section 2.1.4, so any log implementing it can answer, and any verifier implementing it can check.
+
+The remote log also serves `GET /head`, its current tree head signed with the log's key, so an auditor can record heads on a schedule and later audit any two of them without holding a receipt for each.
+