tersign 0.2.0 → 0.3.0

package/README.md

@@ -79,6 +79,27 @@ npm i tersign
 | Venue envelopes | Internet Court (5,000-char slot) · Kleros ERC-1497 · UMA · generic |
 | Evidence packs | `format=art50` · `format=safr` (beta) |
 | Idempotency | In-memory + Cloudflare D1 stores |
+| `tersign intercept` | Audit capture at the MCP boundary — a signed, digest-only action record per tool call (experimental) |
+
+## Capture at the MCP Boundary — `tersign intercept`
+
+An agent's tool calls are usually recorded, if at all, by the party running the agent. Put a
+recording clamp on the wire instead:
+
+```sh
+npx tersign intercept -- npx your-mcp-server
+```
+
+The proxy is a **pure observer**: bytes reach the server and the client exactly as sent, in
+order, unmodified. Every `tools/call` it sees becomes an `ActionRecordV1` signed by *your* key
+and counter-signed into a hash chain — **digests only**, so the record proves what happened
+without carrying arguments or results anywhere. Records go to a configured ledger, and fall
+back to a local `~/.tersign/intercepts-<date>.jsonl` so evidence is never silently dropped.
+
+Experimental, and deliberately unopinionated about where the protocol lands: it implements the
+observation semantics of the audit-mode validator described in MCP **SEP-2624** (Draft) as a
+transport-level proxy today, and is structured to move onto the interceptor primitive if and
+when that stabilizes. It makes no conformance claim to that draft.
 
 ## For Agents — the MCP Server
 

package/dist/cli.js

@@ -23,6 +23,10 @@ else if (sub === 'disclose') {
     process.argv.splice(2, 1);
     await import('./disclose-bin.js');
 }
+else if (sub === 'intercept') {
+    process.argv.splice(2, 1);
+    await import('./intercept-bin.js');
+}
 else if (sub === 'help' || sub === '--help' || sub === '-h') {
     console.log('tersign — evidence layer for the agent economy\n\n' +
         '  tersign                 start the MCP server (stdio)\n' +
@@ -31,7 +35,14 @@ else if (sub === 'help' || sub === '--help' || sub === '-h') {
         '                          verify a receipt: local signature recovery + public chain check\n' +
         '  tersign disclose "<text>" [--medium chat] [--agent-id id] [--url resourceUrl]\n' +
         '                          counter-signed disclosure evidence — text digested locally,\n' +
-        '                          only the digest travels; key created on first use\n');
+        '                          only the digest travels; key created on first use\n' +
+        '  tersign intercept [--events m1,m2] [--agent-id id] [--ledger url] -- <server cmd…>\n' +
+        '                          byte-faithful MCP stdio proxy — signed, digest-only\n' +
+        '                          tool-call evidence for the wrapped server (experimental).\n' +
+        '                          Hosted ledger mode requires the signer key registered for\n' +
+        '                          the sellerId (TERSIGN_SELLER_KEY); rejected records fall\n' +
+        "                          back to ~/.tersign. Exits with the child's code; 1 if\n" +
+        '                          evidence was lost while the child exited 0\n');
 }
 else {
     console.error(`unknown subcommand '${sub}' — did you mean: tersign verify ${sub}\nrun 'tersign help' for usage`);

package/dist/intercept/capture.d.ts

@@ -0,0 +1,51 @@
+import type { Account } from 'viem/accounts';
+import { type SignedActionRecord } from '../evidence/action.js';
+/** Direction-aware JSON-RPC pairing → signed, digest-only ActionRecordV1 evidence.
+ *
+ * JSON-RPC ids are independent per direction in MCP v1 — client→server requests and
+ * server→client requests (sampling, elicitation) coexist, so the same id can be in flight
+ * both ways at once. Pending requests key on (request direction, id); a response observed
+ * in direction D answers the request that travelled in the OPPOSITE direction.
+ *
+ * The prototype captures client→server requests only, and notifications (no id) are not
+ * captured. DIGESTS ONLY: a record carries digestOf(arguments) and digestOf(result ?? error),
+ * never the content itself — the data-minimized posture of evidence/action.ts. */
+export type Direction = 'client' | 'server';
+export declare const DEFAULT_EVENTS: readonly string[];
+export interface McpCaptureOptions {
+    /** agent identity stamped on every record */
+    agentId: string;
+    /** deployer signing account (keystore-resolved on the CLI path) */
+    account: Account;
+    /** captured client→server request methods; '*' captures every method */
+    events?: readonly string[];
+    clock?: () => number;
+    /** receives each signed record — wire this to the sink */
+    onRecord: (signed: SignedActionRecord) => void;
+    /** signing failures land here; the observer never throws into the proxy path */
+    onError?: (err: unknown) => void;
+}
+export declare class McpCapture {
+    private readonly opts;
+    private readonly events;
+    private readonly clock;
+    private readonly pending;
+    private tail;
+    private stopped;
+    private emitted;
+    private evicted;
+    private collided;
+    constructor(opts: McpCaptureOptions);
+    /** signed records emitted so far (for the exit summary) */
+    get recordCount(): number;
+    /** pending entries evicted at the MAX_PENDING cap — each is a request that can no longer pair */
+    get evictedCount(): number;
+    /** same-direction id collisions — each dropped a stale pending request without emitting */
+    get collisionCount(): number;
+    /** Observe one complete frame (a COPY — the proxied bytes are already on their way). */
+    onFrame(direction: Direction, line: Buffer): void;
+    /** Stop observing new frames (shutdown began); already-queued signings still complete. */
+    stop(): void;
+    /** Resolves once every queued record has been signed and delivered to onRecord. */
+    settle(): Promise<void>;
+}

package/dist/intercept/capture.js

@@ -0,0 +1,134 @@
+import { digestOf } from '../canonical.js';
+import { signActionRecord } from '../evidence/action.js';
+import { tryParseFrame } from './frames.js';
+export const DEFAULT_EVENTS = ['tools/call'];
+/** pending-map ceiling — cancelled-and-lost or never-answered requests must not grow memory
+ * forever; on overflow the oldest entry is evicted (counted, warned once via onError) */
+const MAX_PENDING = 4096;
+export class McpCapture {
+    opts;
+    events;
+    clock;
+    pending = new Map();
+    tail = Promise.resolve();
+    stopped = false;
+    emitted = 0;
+    evicted = 0;
+    collided = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.events = new Set(opts.events ?? DEFAULT_EVENTS);
+        this.clock = opts.clock ?? (() => Math.floor(Date.now() / 1000));
+    }
+    /** signed records emitted so far (for the exit summary) */
+    get recordCount() {
+        return this.emitted;
+    }
+    /** pending entries evicted at the MAX_PENDING cap — each is a request that can no longer pair */
+    get evictedCount() {
+        return this.evicted;
+    }
+    /** same-direction id collisions — each dropped a stale pending request without emitting */
+    get collisionCount() {
+        return this.collided;
+    }
+    /** Observe one complete frame (a COPY — the proxied bytes are already on their way). */
+    onFrame(direction, line) {
+        if (this.stopped)
+            return;
+        const msg = tryParseFrame(line);
+        if (msg === undefined || msg === null || typeof msg !== 'object' || Array.isArray(msg))
+            return;
+        const frame = msg;
+        // MCP cancellation: the request this direction sent will not be answered — drop its
+        // pending entry so cancelled calls cannot accumulate forever.
+        if (frame.method === 'notifications/cancelled') {
+            const params = typeof frame.params === 'object' && frame.params !== null && !Array.isArray(frame.params)
+                ? frame.params
+                : {};
+            const requestId = params.requestId;
+            if (typeof requestId === 'string' || typeof requestId === 'number') {
+                this.pending.delete(pendingKey(direction, requestId));
+            }
+            return;
+        }
+        const id = frame.id;
+        if (typeof id !== 'string' && typeof id !== 'number')
+            return; // notifications / null-id errors
+        if (typeof frame.method === 'string') {
+            if (direction !== 'client')
+                return; // prototype: client→server requests only
+            if (!this.events.has('*') && !this.events.has(frame.method))
+                return;
+            const params = typeof frame.params === 'object' && frame.params !== null && !Array.isArray(frame.params)
+                ? frame.params
+                : {};
+            const key = pendingKey('client', id);
+            if (this.pending.has(key)) {
+                // Same-direction id reuse while the first request is still pending (a JSON-RPC
+                // violation): the stale entry can no longer be paired truthfully — drop it WITHOUT
+                // emitting a record (never fabricate a pairing). The delete keeps insertion order
+                // honest for cap eviction.
+                this.pending.delete(key);
+                this.collided += 1;
+                this.opts.onError?.(new Error(`duplicate in-flight JSON-RPC id ${String(id)} (client) — dropped the stale pending request without emitting a record`));
+            }
+            else if (this.pending.size >= MAX_PENDING) {
+                const oldest = this.pending.keys().next().value;
+                if (oldest !== undefined)
+                    this.pending.delete(oldest);
+                this.evicted += 1;
+                if (this.evicted === 1) {
+                    this.opts.onError?.(new Error(`pending-request map hit its ${MAX_PENDING}-entry cap — evicting oldest unanswered requests (counted, warned once)`));
+                }
+            }
+            this.pending.set(key, {
+                method: frame.method,
+                ...(typeof params.name === 'string' ? { toolName: params.name } : {}),
+                inputDigest: digestOf(params.arguments ?? null),
+                at: this.clock(),
+            });
+            return;
+        }
+        if (!('result' in frame) && !('error' in frame))
+            return;
+        // A response in direction D answers the request that travelled the opposite way.
+        const key = pendingKey(direction === 'server' ? 'client' : 'server', id);
+        const entry = this.pending.get(key);
+        if (entry === undefined)
+            return;
+        this.pending.delete(key);
+        // JSON-RPC error responses still produce a record — the digest covers the error object.
+        const outputDigest = digestOf(frame.result ?? frame.error ?? null);
+        this.tail = this.tail
+            .then(async () => {
+            const record = {
+                version: 1,
+                agent: { id: this.opts.agentId },
+                action: {
+                    kind: 'tool-call',
+                    ...(entry.toolName !== undefined ? { name: entry.toolName } : {}),
+                    inputDigest: entry.inputDigest,
+                    outputDigest,
+                },
+                occurredAt: entry.at,
+            };
+            const signed = await signActionRecord(record, this.opts.account);
+            this.emitted += 1;
+            this.opts.onRecord(signed);
+        })
+            .catch((err) => this.opts.onError?.(err));
+    }
+    /** Stop observing new frames (shutdown began); already-queued signings still complete. */
+    stop() {
+        this.stopped = true;
+    }
+    /** Resolves once every queued record has been signed and delivered to onRecord. */
+    async settle() {
+        await this.tail;
+    }
+}
+/** ids are string-or-number and independent per direction — 1 and '1' must not collide. */
+function pendingKey(direction, id) {
+    return `${direction}:${typeof id}:${String(id)}`;
+}

package/dist/intercept/flags.d.ts

@@ -0,0 +1,18 @@
+/** Flag parsing for `tersign intercept` — the tokens strictly BEFORE '--' (everything after
+ * belongs to the child verbatim). Supports both '--flag value' and '--flag=value'; unknown
+ * flags and flags missing their value are errors, never silent misreads (a bare '--agent-id'
+ * must not consume a following '--ledger' as its value — that once signed records with
+ * agent.id '--ledger'). Split out of intercept-bin so tests can drive it directly. */
+export interface InterceptFlags {
+    events?: string;
+    agentId?: string;
+    ledger?: string;
+}
+export type ParsedInterceptFlags = {
+    ok: true;
+    flags: InterceptFlags;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseInterceptFlags(tokens: readonly string[]): ParsedInterceptFlags;

package/dist/intercept/flags.js

@@ -0,0 +1,38 @@
+/** Flag parsing for `tersign intercept` — the tokens strictly BEFORE '--' (everything after
+ * belongs to the child verbatim). Supports both '--flag value' and '--flag=value'; unknown
+ * flags and flags missing their value are errors, never silent misreads (a bare '--agent-id'
+ * must not consume a following '--ledger' as its value — that once signed records with
+ * agent.id '--ledger'). Split out of intercept-bin so tests can drive it directly. */
+const FLAG_KEYS = new Map([
+    ['--events', 'events'],
+    ['--agent-id', 'agentId'],
+    ['--ledger', 'ledger'],
+]);
+export function parseInterceptFlags(tokens) {
+    const flags = {};
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        const eq = token.indexOf('=');
+        const name = eq === -1 ? token : token.slice(0, eq);
+        const key = FLAG_KEYS.get(name);
+        if (key === undefined) {
+            return {
+                ok: false,
+                error: name.startsWith('--')
+                    ? `unknown flag '${name}'`
+                    : `unexpected argument '${token}' — flags go before '--', the server command after`,
+            };
+        }
+        if (eq !== -1) {
+            flags[key] = token.slice(eq + 1);
+            continue;
+        }
+        const next = tokens[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            return { ok: false, error: `flag '${name}' requires a value` };
+        }
+        flags[key] = next;
+        i += 1;
+    }
+    return { ok: true, flags };
+}

package/dist/intercept/frames.d.ts

@@ -0,0 +1,19 @@
+/** Newline-delimited JSON-RPC framing for the MCP stdio transport.
+ *
+ * Observation only: the proxied byte path never flows through this module — the proxy pipes
+ * raw bytes straight through and feeds COPIES here, so the child receives exactly the bytes
+ * the client sent and vice versa (parse a copy, never a re-serialization). Frames may arrive
+ * split across reads or coalesced several-per-chunk, and can be arbitrarily large (buffered
+ * until the newline arrives). */
+/** Splits a byte stream into newline-delimited frames. Yielded lines exclude the trailing
+ * `\n` (a trailing `\r` is left in place — `tryParseFrame` tolerates it). Partial pieces
+ * accumulate as an array and concatenate once per completed line, so a large frame fed in
+ * many chunks costs O(bytes), not O(bytes²). */
+export declare class LineSplitter {
+    private pending;
+    feed(chunk: Buffer): Buffer[];
+}
+/** Parse one frame for observation. Returns the parsed JSON value, or undefined for empty
+ * and non-JSON lines — those pass through the proxy untouched and are never captured.
+ * Never throws into the proxy path. */
+export declare function tryParseFrame(line: Buffer): unknown;

package/dist/intercept/frames.js

@@ -0,0 +1,50 @@
+/** Newline-delimited JSON-RPC framing for the MCP stdio transport.
+ *
+ * Observation only: the proxied byte path never flows through this module — the proxy pipes
+ * raw bytes straight through and feeds COPIES here, so the child receives exactly the bytes
+ * the client sent and vice versa (parse a copy, never a re-serialization). Frames may arrive
+ * split across reads or coalesced several-per-chunk, and can be arbitrarily large (buffered
+ * until the newline arrives). */
+/** Splits a byte stream into newline-delimited frames. Yielded lines exclude the trailing
+ * `\n` (a trailing `\r` is left in place — `tryParseFrame` tolerates it). Partial pieces
+ * accumulate as an array and concatenate once per completed line, so a large frame fed in
+ * many chunks costs O(bytes), not O(bytes²). */
+export class LineSplitter {
+    pending = [];
+    feed(chunk) {
+        const lines = [];
+        let start = 0;
+        let nl;
+        while ((nl = chunk.indexOf(0x0a, start)) !== -1) {
+            const piece = chunk.subarray(start, nl);
+            if (this.pending.length > 0) {
+                this.pending.push(piece);
+                lines.push(Buffer.concat(this.pending));
+                this.pending = [];
+            }
+            else {
+                lines.push(piece);
+            }
+            start = nl + 1;
+        }
+        if (start < chunk.length)
+            this.pending.push(chunk.subarray(start));
+        return lines;
+    }
+}
+/** Parse one frame for observation. Returns the parsed JSON value, or undefined for empty
+ * and non-JSON lines — those pass through the proxy untouched and are never captured.
+ * Never throws into the proxy path. */
+export function tryParseFrame(line) {
+    let end = line.length;
+    if (end > 0 && line[end - 1] === 0x0d)
+        end -= 1; // CRLF tolerance
+    if (end === 0)
+        return undefined;
+    try {
+        return JSON.parse(line.subarray(0, end).toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/intercept/proxy.d.ts

@@ -0,0 +1,29 @@
+import { type ChildProcess } from 'node:child_process';
+import type { Readable, Writable } from 'node:stream';
+import type { McpCapture } from './capture.js';
+import type { EvidenceSink } from './sink.js';
+/** The byte-faithful proxy core: spawn the MCP server, pipe raw bytes straight through in
+ * both directions, and tee COPIES into the frame splitter → capture. The proxy is a pure
+ * observer — it never injects, reorders, delays, or modifies frames; the child receives
+ * exactly the bytes the client sent and vice versa. Split out of intercept-bin so tests can
+ * drive it with in-memory streams while spawning a real child. */
+export interface StartInterceptOptions {
+    command: string;
+    args: readonly string[];
+    capture: McpCapture;
+    sink: EvidenceSink;
+    /** client→server bytes (process.stdin on the CLI path) */
+    stdin: Readable;
+    /** server→client bytes (process.stdout on the CLI path) */
+    stdout: Writable;
+    /** child stderr disposition: 'inherit' passes it through to our stderr */
+    stderr: 'inherit' | 'ignore';
+}
+export interface RunningIntercept {
+    child: ChildProcess;
+    /** resolves with the child's exit code after the outbound writable has drained, capture
+     * settles and the sink is flushed; rejects if the child could not be spawned (the sink is
+     * still flushed first) */
+    done: Promise<number>;
+}
+export declare function startIntercept(opts: StartInterceptOptions): RunningIntercept;

package/dist/intercept/proxy.js

@@ -0,0 +1,60 @@
+import { spawn } from 'node:child_process';
+import { LineSplitter } from './frames.js';
+export function startIntercept(opts) {
+    const child = spawn(opts.command, [...opts.args], { stdio: ['pipe', 'pipe', opts.stderr] });
+    const clientFrames = new LineSplitter();
+    const serverFrames = new LineSplitter();
+    // Byte path: raw pipes. Observer path: 'data' taps feeding frame COPIES to capture —
+    // parsing never touches the proxied bytes, and a malformed frame changes nothing.
+    opts.stdin.on('data', (chunk) => {
+        for (const line of clientFrames.feed(chunk))
+            opts.capture.onFrame('client', line);
+    });
+    opts.stdin.pipe(child.stdin);
+    child.stdout.on('data', (chunk) => {
+        for (const line of serverFrames.feed(chunk))
+            opts.capture.onFrame('server', line);
+    });
+    // end: false — process.stdout cannot be closed; the exit path decides when we are done
+    child.stdout.pipe(opts.stdout, { end: false });
+    // EPIPE when the child exits mid-write — the close path below reports the outcome
+    child.stdin.on('error', () => { });
+    // Exit-path drain: the child's 'close' means its output has been READ into Node userspace —
+    // not that the outbound writable has flushed it. For a slow reader the tail of a large final
+    // response is still queued here, and resolving 'done' before it drains lets the CLI exit and
+    // discard it mid-frame. Wait until the writable holds nothing before settling.
+    const drainOutbound = async () => {
+        while (!opts.stdout.destroyed && opts.stdout.writableLength > 0) {
+            await new Promise((resolve) => {
+                const settle = () => {
+                    clearTimeout(timer);
+                    opts.stdout.off('drain', settle);
+                    opts.stdout.off('close', settle);
+                    opts.stdout.off('error', settle);
+                    resolve();
+                };
+                // 'drain' only fires after a write returned false; the timer covers bytes queued
+                // below the high-water mark, and 'close'/'error' cover a reader that went away.
+                const timer = setTimeout(settle, 20);
+                opts.stdout.once('drain', settle);
+                opts.stdout.once('close', settle);
+                opts.stdout.once('error', settle);
+            });
+        }
+    };
+    const done = new Promise((resolve, reject) => {
+        const finish = async () => {
+            opts.capture.stop();
+            await drainOutbound();
+            await opts.capture.settle();
+            await opts.sink.close();
+        };
+        child.once('error', (err) => {
+            void finish().then(() => reject(err));
+        });
+        child.once('close', (code, signal) => {
+            void finish().then(() => resolve(code ?? (signal !== null ? 1 : 0)));
+        });
+    });
+    return { child, done };
+}

package/dist/intercept/sink.d.ts

@@ -0,0 +1,40 @@
+import type { SignedActionRecord } from '../evidence/action.js';
+export interface EvidenceSinkOptions {
+    /** ledger base URL (used only when apiKey + sellerId are both set) */
+    ledgerUrl: string;
+    apiKey?: string;
+    sellerId?: string;
+    /** local sink directory — defaults to ~/.tersign; injectable for tests */
+    dir?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+    /** per-POST cap in ms before falling back to the local file (default 10s) */
+    ledgerTimeoutMs?: number;
+    /** diagnostic line sink — defaults to stderr */
+    warn?: (line: string) => void;
+}
+export declare class EvidenceSink {
+    private readonly opts;
+    private readonly ledgerUrl;
+    private readonly dir;
+    private readonly warn;
+    private tail;
+    private closed;
+    /** records the ledger accepted */
+    ledgerCount: number;
+    /** records written to the local file (including ledger fallbacks) */
+    localCount: number;
+    /** records lost to both paths (local append failed) */
+    failedCount: number;
+    /** non-ok ledger responses — the first is warned with status + body excerpt, the rest count silently */
+    ledgerRejectCount: number;
+    /** the local file, once anything was written there (for the exit summary) */
+    localPath: string | null;
+    constructor(opts: EvidenceSinkOptions);
+    /** Queue one signed record. Returns immediately; never throws. */
+    push(signed: SignedActionRecord): void;
+    /** Stop accepting and flush everything queued. */
+    close(): Promise<void>;
+    private write;
+    private appendLocal;
+}

package/dist/intercept/sink.js

@@ -0,0 +1,102 @@
+import { appendFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Non-blocking evidence sink — records queue here and flush sequentially in the
+ * background, so evidence I/O never delays the proxied traffic.
+ *
+ * Ledger mode (apiKey + sellerId configured): POST each signed record to
+ * {ledger}/v1/evidence — bearer-key authed, the ledgerClient.ts convention; an HTTP or
+ * network failure (each POST capped at 10s) falls back to the local file so no record is
+ * dropped. The ledger's /v1/evidence gate only accepts the seller's REGISTERED signing key,
+ * so a mismatched signer is warned on the first rejection. Local mode: one
+ * JSON line per record appended to <dir>/intercepts-YYYY-MM-DD.jsonl (0600, dir 0700 —
+ * the keyfile conventions from keystore.ts). close() drains the queue fully. */
+/** default cap on a single ledger POST — a hung request must never wedge close() */
+const LEDGER_TIMEOUT_MS = 10_000;
+export class EvidenceSink {
+    opts;
+    ledgerUrl;
+    dir;
+    warn;
+    tail = Promise.resolve();
+    closed = false;
+    /** records the ledger accepted */
+    ledgerCount = 0;
+    /** records written to the local file (including ledger fallbacks) */
+    localCount = 0;
+    /** records lost to both paths (local append failed) */
+    failedCount = 0;
+    /** non-ok ledger responses — the first is warned with status + body excerpt, the rest count silently */
+    ledgerRejectCount = 0;
+    /** the local file, once anything was written there (for the exit summary) */
+    localPath = null;
+    constructor(opts) {
+        this.opts = opts;
+        this.ledgerUrl = opts.ledgerUrl.replace(/\/$/, '');
+        this.dir = opts.dir ?? join(homedir(), '.tersign');
+        this.warn = opts.warn ?? ((line) => console.error(line));
+    }
+    /** Queue one signed record. Returns immediately; never throws. */
+    push(signed) {
+        if (this.closed)
+            return;
+        this.tail = this.tail.then(() => this.write(signed));
+    }
+    /** Stop accepting and flush everything queued. */
+    async close() {
+        this.closed = true;
+        await this.tail;
+    }
+    async write(signed) {
+        if (this.opts.apiKey !== undefined && this.opts.sellerId !== undefined) {
+            try {
+                const f = this.opts.fetchImpl ?? fetch;
+                const signal = AbortSignal.timeout(this.opts.ledgerTimeoutMs ?? LEDGER_TIMEOUT_MS);
+                // Raced explicitly against the abort: even a fetch impl that ignores the signal must
+                // not wedge close() — the record falls back to the local file instead.
+                const res = await Promise.race([
+                    f(`${this.ledgerUrl}/v1/evidence`, {
+                        method: 'POST',
+                        headers: { 'content-type': 'application/json', authorization: `Bearer ${this.opts.apiKey}` },
+                        body: JSON.stringify({ sellerId: this.opts.sellerId, artifact: signed }),
+                        signal,
+                    }),
+                    new Promise((_, reject) => {
+                        signal.addEventListener('abort', () => reject(new Error('ledger request timed out')), { once: true });
+                    }),
+                ]);
+                // Always consume the body — an unread body pins the connection in undici's pool.
+                const body = await res.text().catch(() => '');
+                if (res.ok) {
+                    this.ledgerCount += 1;
+                    return;
+                }
+                this.ledgerRejectCount += 1;
+                if (this.ledgerRejectCount === 1) {
+                    const excerpt = body.replace(/\s+/g, ' ').trim().slice(0, 160);
+                    this.warn(`tersign intercept: ledger rejected the record (HTTP ${res.status}${excerpt !== '' ? ` — ${excerpt}` : ''}); ` +
+                        'writing to the local file instead. Hosted mode requires your registered signer key — ' +
+                        'set TERSIGN_SELLER_KEY to the key registered for this sellerId.');
+                }
+            }
+            catch {
+                // network failure or timeout — fall through to the local file
+            }
+        }
+        try {
+            await this.appendLocal(signed);
+            this.localCount += 1;
+        }
+        catch {
+            this.failedCount += 1;
+        }
+    }
+    async appendLocal(signed) {
+        if (this.localPath === null) {
+            await mkdir(this.dir, { recursive: true, mode: 0o700 });
+            const day = (this.opts.now ?? (() => new Date()))().toISOString().slice(0, 10);
+            this.localPath = join(this.dir, `intercepts-${day}.jsonl`);
+        }
+        await appendFile(this.localPath, `${JSON.stringify(signed)}\n`, { mode: 0o600 });
+    }
+}

package/dist/intercept-bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/intercept-bin.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/** tersign intercept — byte-faithful MCP stdio proxy with signed, digest-only evidence.
+ *
+ *   tersign intercept [--events tools/call,prompts/get] [--agent-id id] [--ledger url] \
+ *                     -- npx some-mcp-server --its-flags
+ *
+ * Sits between an MCP client and a stdio MCP server, passes every byte through untouched,
+ * and emits one signed ActionRecordV1 per captured tool call — digests of arguments and
+ * results only, never content (data-minimization by construction). Records go to the hosted
+ * ledger when TERSIGN_LEDGER_API_KEY + TERSIGN_LEDGER_SELLER_ID are set, else to
+ * ~/.tersign/intercepts-YYYY-MM-DD.jsonl. The hosted /v1/evidence gate only accepts the
+ * seller's REGISTERED signing key: set TERSIGN_SELLER_KEY to that key, or every POST is
+ * rejected (warned once) and records fall back to the local file.
+ *
+ * Exit code: the child's, except 1 when evidence was lost (failed both sinks) while the
+ * child itself exited 0 — a child failure code is never masked.
+ *
+ * SEP-2624 ("Interceptors for the Model Context Protocol" — Draft, Bloomberg/Saxo-led)
+ * defines audit-mode validators that observe traffic without mutating it; this prototype
+ * implements that capture semantics as a transport-level proxy today and is structured to
+ * migrate to the interceptor primitive when the SEP stabilizes. It makes no conformance
+ * claim against the SEP — the SEP is a draft proposal, not a released spec. */
+import { privateKeyToAccount } from 'viem/accounts';
+import { DEFAULT_EVENTS, McpCapture } from './intercept/capture.js';
+import { parseInterceptFlags } from './intercept/flags.js';
+import { startIntercept } from './intercept/proxy.js';
+import { EvidenceSink } from './intercept/sink.js';
+import { resolveSignerKey } from './keystore.js';
+const USAGE = 'usage: tersign intercept [--events tools/call,prompts/get] [--agent-id id] [--ledger url] -- <mcp server command> [args…]\n' +
+    'hosted ledger mode (TERSIGN_LEDGER_API_KEY + TERSIGN_LEDGER_SELLER_ID) requires the signer key\n' +
+    'registered for that sellerId — set TERSIGN_SELLER_KEY; rejected records fall back to ~/.tersign.\n' +
+    "exits with the child's code; 1 if evidence was lost while the child exited 0";
+const sep = process.argv.indexOf('--');
+const command = sep === -1 ? [] : process.argv.slice(sep + 1);
+if (sep === -1 || command.length === 0) {
+    console.error(USAGE);
+    process.exit(2);
+}
+// Flags live strictly BEFORE '--'; everything after belongs to the child verbatim.
+const parsed = parseInterceptFlags(process.argv.slice(2, sep));
+if (!parsed.ok) {
+    console.error(`tersign intercept: ${parsed.error}\n${USAGE}`);
+    process.exit(2);
+}
+const flags = parsed.flags;
+// --events ADDS to the default set; '*' captures every client→server request method.
+const events = [...DEFAULT_EVENTS];
+for (const e of (flags.events ?? '').split(',')) {
+    const method = e.trim();
+    if (method !== '' && !events.includes(method))
+        events.push(method);
+}
+const envAgentId = process.env.TERSIGN_AGENT_ID;
+const agentId = flags.agentId ?? (envAgentId !== undefined && envAgentId !== '' ? envAgentId : 'mcp-intercept');
+const ledgerUrl = flags.ledger ?? process.env.TERSIGN_LEDGER_URL ?? 'https://tersign.ai';
+const apiKey = process.env.TERSIGN_LEDGER_API_KEY;
+const sellerId = process.env.TERSIGN_LEDGER_SELLER_ID;
+try {
+    const { key, source } = resolveSignerKey({ create: true });
+    const account = privateKeyToAccount(key);
+    console.error(`signing key: ${account.address} (${source})`);
+    const sink = new EvidenceSink({
+        ledgerUrl,
+        ...(apiKey !== undefined && apiKey !== '' ? { apiKey } : {}),
+        ...(sellerId !== undefined && sellerId !== '' ? { sellerId } : {}),
+    });
+    // Capture warnings (dropped stale pairings, cap evictions, signing failures) are
+    // diagnostics, not traffic — rate-limited so a pathological stream cannot flood stderr.
+    let captureWarnings = 0;
+    const onError = (err) => {
+        captureWarnings += 1;
+        if (captureWarnings <= 5)
+            console.error(`tersign intercept: ${err instanceof Error ? err.message : String(err)}`);
+        if (captureWarnings === 6)
+            console.error('tersign intercept: further capture warnings suppressed');
+    };
+    const capture = new McpCapture({ agentId, account, events, onRecord: (r) => sink.push(r), onError });
+    const { child, done } = startIntercept({
+        command: command[0],
+        args: command.slice(1),
+        capture,
+        sink,
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: 'inherit',
+    });
+    let childClosed = false;
+    child.once('close', () => {
+        childClosed = true;
+    });
+    let signalled = false;
+    for (const sig of ['SIGINT', 'SIGTERM']) {
+        const code = sig === 'SIGINT' ? 130 : 143; // 128 + signal number
+        process.on(sig, () => {
+            if (signalled)
+                process.exit(code); // a second signal always force-exits immediately
+            signalled = true;
+            if (childClosed) {
+                // the child is already gone, so there is nothing to forward to — flush best-effort
+                // (every sink write is time-capped), then force-exit
+                void sink.close().finally(() => process.exit(code));
+            }
+            else {
+                // forward to the child; its close event drives the flush + summary below
+                child.kill(sig);
+            }
+        });
+    }
+    const code = await done;
+    console.error(`tersign intercept: ${capture.recordCount} tool-call records (${sink.ledgerCount} ledger, ${sink.localCount} local` +
+        (sink.failedCount > 0 ? `, ${sink.failedCount} FAILED — evidence lost` : '') +
+        ')' +
+        (sink.localPath !== null ? ` — ${sink.localPath}` : ''));
+    // Natural exit (exitCode + stdin teardown, never process.exit()) so Node flushes any stdout
+    // still queued for a slow reader; evidence loss becomes exit 1 only when the child exited 0.
+    process.stdin.pause();
+    process.exitCode = sink.failedCount > 0 && code === 0 ? 1 : code;
+}
+catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.stdin.pause();
+    process.exitCode = 1;
+}

package/dist/mcp/server.d.ts

@@ -8,6 +8,6 @@ export declare function envDeps(env?: Record<string, string | undefined>): McpDe
  * every client; mcp.test.ts pins it against package.json so a release bump can't drift it. */
 export declare const MCP_SERVER_IDENTITY: {
     readonly name: "tersign";
-    readonly version: "0.2.0";
+    readonly version: "0.3.0";
 };
 export declare function buildServer(deps: McpDeps): McpServer;

package/dist/mcp/server.js

@@ -45,7 +45,7 @@ function json(value) {
 }
 /** MUST match package.json name/version — the MCP handshake self-reports this identity to
  * every client; mcp.test.ts pins it against package.json so a release bump can't drift it. */
-export const MCP_SERVER_IDENTITY = { name: 'tersign', version: '0.2.0' };
+export const MCP_SERVER_IDENTITY = { name: 'tersign', version: '0.3.0' };
 export function buildServer(deps) {
     const server = new McpServer(MCP_SERVER_IDENTITY);
     server.registerTool('issue_receipt', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tersign",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Tersign \u2014 the evidence layer for the agent economy. Counter-signed receipts, agent action records, idempotency enforcement, refunds, disputes, and jury-ready evidence envelopes for x402/agent-commerce sellers.",
   "license": "MIT",
   "type": "module",