patchwork-os 0.2.0-alpha.9 → 0.2.0-beta.0

package/dist/traceEncryption.js

@@ -0,0 +1,124 @@
+/**
+ * Trace bundle encryption/decryption — AES-256-GCM with scrypt KDF.
+ *
+ * Binary format (all multi-byte values big-endian):
+ *
+ *   Offset  Len  Field
+ *   0       8    Magic: ASCII "PWTRACE\0"
+ *   8       1    Version: 0x01
+ *   9       16   Salt (random, for scrypt)
+ *   25      12   IV / nonce (random, for AES-GCM)
+ *   37      16   GCM authentication tag
+ *   53      N    Ciphertext (the original .jsonl.gz bytes)
+ *
+ * Key derivation: scrypt(passphrase, salt, N=16384, r=8, p=1, keyLen=32).
+ * N=2^14 matches Node's `crypto.scryptSync` default and is safe for
+ * interactive use on a modern laptop (~50ms, 16MB RAM). They are stored implicitly
+ * (fixed); changing them is a version bump.
+ *
+ * Security properties:
+ * - Unique salt per export → unique key per file even with the same passphrase.
+ * - GCM authentication tag → any tamper of ciphertext or header is detected.
+ * - scrypt → GPU-resistant brute-force on passphrase.
+ * - Buffer.fill(0) on key material after use → minimise in-process lifetime.
+ *
+ * The encrypted file is NOT gzip-compressed on top (the plaintext already
+ * is). Compressing ciphertext adds no size benefit and obscures the magic
+ * header used by the import command to auto-detect the format.
+ */
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync, } from "node:crypto";
+export const TRACE_ENCRYPT_MAGIC = Buffer.from("PWTRACE\0", "ascii");
+export const TRACE_ENCRYPT_VERSION = 0x01;
+const SALT_LEN = 16;
+const IV_LEN = 12;
+const TAG_LEN = 16;
+const HEADER_LEN = TRACE_ENCRYPT_MAGIC.length + 1 + SALT_LEN + IV_LEN + TAG_LEN; // 53
+const SCRYPT_N = 16384; // 2^14 — Node scryptSync default; needs 128*N*r = 16MB RAM
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const KEY_LEN = 32;
+function deriveKey(passphrase, salt) {
+    return scryptSync(passphrase, salt, KEY_LEN, {
+        N: SCRYPT_N,
+        r: SCRYPT_R,
+        p: SCRYPT_P,
+    });
+}
+/**
+ * Encrypt a Buffer (the gzip-compressed trace bundle) with a passphrase.
+ * Returns a new Buffer in the wire format described above.
+ */
+export function encryptTraceBundle(plaintext, passphrase) {
+    const salt = randomBytes(SALT_LEN);
+    const iv = randomBytes(IV_LEN);
+    const key = deriveKey(passphrase, salt);
+    try {
+        const cipher = createCipheriv("aes-256-gcm", key, iv);
+        const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        const header = Buffer.alloc(HEADER_LEN);
+        let offset = 0;
+        TRACE_ENCRYPT_MAGIC.copy(header, offset);
+        offset += TRACE_ENCRYPT_MAGIC.length;
+        header[offset++] = TRACE_ENCRYPT_VERSION;
+        salt.copy(header, offset);
+        offset += SALT_LEN;
+        iv.copy(header, offset);
+        offset += IV_LEN;
+        tag.copy(header, offset);
+        return Buffer.concat([header, encrypted]);
+    }
+    finally {
+        key.fill(0);
+    }
+}
+/**
+ * Decrypt a Buffer that was produced by `encryptTraceBundle`.
+ * Returns the original plaintext (the gzip-compressed trace bundle).
+ * Throws if the magic, version, or GCM tag don't match.
+ */
+export function decryptTraceBundle(ciphertext, passphrase) {
+    if (ciphertext.length < HEADER_LEN) {
+        throw new Error("Trace bundle too short to be a valid encrypted file");
+    }
+    const magic = ciphertext.subarray(0, TRACE_ENCRYPT_MAGIC.length);
+    if (!magic.equals(TRACE_ENCRYPT_MAGIC)) {
+        throw new Error("Not an encrypted Patchwork trace bundle (magic mismatch)");
+    }
+    const version = ciphertext[TRACE_ENCRYPT_MAGIC.length];
+    if (version !== TRACE_ENCRYPT_VERSION) {
+        throw new Error(`Unsupported encrypted bundle version: 0x${version?.toString(16) ?? "??"} (expected 0x01)`);
+    }
+    let offset = TRACE_ENCRYPT_MAGIC.length + 1;
+    const salt = ciphertext.subarray(offset, offset + SALT_LEN);
+    offset += SALT_LEN;
+    const iv = ciphertext.subarray(offset, offset + IV_LEN);
+    offset += IV_LEN;
+    const tag = ciphertext.subarray(offset, offset + TAG_LEN);
+    offset += TAG_LEN;
+    const encrypted = ciphertext.subarray(offset);
+    const key = deriveKey(passphrase, salt);
+    try {
+        const decipher = createDecipheriv("aes-256-gcm", key, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(encrypted), decipher.final()]);
+    }
+    catch {
+        throw new Error("Decryption failed — wrong passphrase or corrupted file");
+    }
+    finally {
+        key.fill(0);
+    }
+}
+/**
+ * Returns true if the buffer starts with the encrypted trace bundle magic.
+ * Use this to auto-detect encrypted bundles at import time.
+ */
+export function isEncryptedTraceBundle(buf) {
+    if (buf.length < TRACE_ENCRYPT_MAGIC.length)
+        return false;
+    return buf
+        .subarray(0, TRACE_ENCRYPT_MAGIC.length)
+        .equals(TRACE_ENCRYPT_MAGIC);
+}
+//# sourceMappingURL=traceEncryption.js.map

package/dist/traceEncryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceEncryption.js","sourceRoot":"","sources":["../src/traceEncryption.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -49,6 +49,15 @@ export declare class McpTransport {
     private activeListener;
     private inFlightControllers;
     private inFlightToolNames;
+    /**
+     * Snapshot of in-flight tool-call ids captured at `detachSoft()` time.
+     * Used by the per-call `finally` clause to clean up `inFlightControllers`
+     * + `activeToolCalls` even after attach() bumped `this.generation`. Without
+     * this set, an old-gen tool that settles after grace-period reattach would
+     * leak its slot in inFlightControllers AND its activeToolCalls count,
+     * which in turn makes HTTP eviction skip the session forever.
+     */
+    private detachSoftInflight;
     /** Pending elicitation/create requests waiting for a client response. */
     private pendingElicitations;
     private initialized;
@@ -57,6 +66,13 @@ export declare class McpTransport {
     private activeToolCalls;
     private callCount;
     private errorCount;
+    /**
+     * Tool calls rejected/expired by the human approval gate. Tracked
+     * separately from errorCount so dashboard stats and getSessionUsage can
+     * distinguish "human said no" from "tool blew up". Rejections never
+     * increment errorCount and never produce a tool-stats entry.
+     */
+    private approvalRejectionCount;
     private generation;
     private readonly sessionStartedAt;
     private readonly resultSizeTracker;
@@ -78,8 +94,12 @@ export declare class McpTransport {
     private readonly ajv;
     private readonly schemaValidators;
     private readonly outputValidators;
-    /** Cached wire-schema array for tools/list. Invalidated on any tool registration change. */
+    /** Cached wire-schema array for tools/list (full mode). Invalidated on any tool registration change. */
     private wireSchemaCache;
+    /** Cached wire-schema array for tools/list in lazy mode (inputSchema stripped). */
+    private wireSchemaCacheLazy;
+    /** When true, tools/list omits inputSchema. Clients must call tools/schema before tools/call. */
+    private lazyTools;
     /** Per-session tool-call rate limit (calls/minute). 0 = disabled. */
     private toolRateLimit;
     /**
@@ -112,6 +132,8 @@ export declare class McpTransport {
      * Called at HTTP session initialize time from X-Bridge-Deny-Tools header.
      */
     setDenyTools(tools: Set<string>): void;
+    /** Enable lazy-tools mode: tools/list omits inputSchema; clients use tools/schema to fetch it. */
+    setLazyTools(enabled: boolean): void;
     /** Configure per-session tool call rate limiting (calls/minute, 0 = disabled). */
     setToolRateLimit(limit: number): void;
     /**
@@ -173,10 +195,33 @@ export declare class McpTransport {
     /** Remove all tools whose name starts with `prefix`. Returns count removed. */
     deregisterTool(name: string): boolean;
     deregisterToolsByPrefix(prefix: string): number;
+    /**
+     * Soft cleanup of stale per-connection state, used by the bridge's
+     * grace-period resumption path BEFORE calling `attach(ws)` with a new
+     * WebSocket. Unlike `detach()`, this does NOT abort in-flight tool calls
+     * or zero `activeToolCalls` — grace-period semantics preserve those
+     * across the reconnect. It only:
+     *
+     *  1. Removes the old WebSocket's "message" listener so it can't fire
+     *     against the new connection's state.
+     *  2. Rejects any pending elicitation requests, because the original
+     *     client that issued them may not be the one reattaching, and an
+     *     unrelated client should not be allowed to answer another client's
+     *     elicitation by id collision.
+     *
+     * Without this, two leaks survive a resumption:
+     *  - The old `ws.on("message", ...)` listener accumulates (gen-guarded
+     *    so it no-ops, but still attached to the now-closed socket).
+     *  - `pendingElicitations` from the old connection persist in the map;
+     *    the elicit timer keeps ticking and resolving against the NEW
+     *    `activeWs`, surfacing prompts to a client that didn't request them.
+     */
+    detachSoft(): void;
     detach(): void;
     getStats(): {
         callCount: number;
         errorCount: number;
+        approvalRejectionCount: number;
         activeToolCalls: number;
         inFlightTools: string[];
         startedAt: number;

package/dist/transport.js

@@ -41,6 +41,15 @@ export class McpTransport {
     activeListener = null;
     inFlightControllers = new Map();
     inFlightToolNames = new Map();
+    /**
+     * Snapshot of in-flight tool-call ids captured at `detachSoft()` time.
+     * Used by the per-call `finally` clause to clean up `inFlightControllers`
+     * + `activeToolCalls` even after attach() bumped `this.generation`. Without
+     * this set, an old-gen tool that settles after grace-period reattach would
+     * leak its slot in inFlightControllers AND its activeToolCalls count,
+     * which in turn makes HTTP eviction skip the session forever.
+     */
+    detachSoftInflight = new Set();
     /** Pending elicitation/create requests waiting for a client response. */
     pendingElicitations = new Map();
     initialized = false;
@@ -49,6 +58,13 @@ export class McpTransport {
     activeToolCalls = 0;
     callCount = 0;
     errorCount = 0;
+    /**
+     * Tool calls rejected/expired by the human approval gate. Tracked
+     * separately from errorCount so dashboard stats and getSessionUsage can
+     * distinguish "human said no" from "tool blew up". Rejections never
+     * increment errorCount and never produce a tool-stats entry.
+     */
+    approvalRejectionCount = 0;
     generation = 0; // incremented on each attach; stale handlers check this
     sessionStartedAt = Date.now();
     resultSizeTracker = new Map();
@@ -72,8 +88,12 @@ export class McpTransport {
     ajv = new Ajv({ strict: false, allErrors: true });
     schemaValidators = new Map();
     outputValidators = new Map();
-    /** Cached wire-schema array for tools/list. Invalidated on any tool registration change. */
+    /** Cached wire-schema array for tools/list (full mode). Invalidated on any tool registration change. */
     wireSchemaCache = null;
+    /** Cached wire-schema array for tools/list in lazy mode (inputSchema stripped). */
+    wireSchemaCacheLazy = null;
+    /** When true, tools/list omits inputSchema. Clients must call tools/schema before tools/call. */
+    lazyTools = false;
     /** Per-session tool-call rate limit (calls/minute). 0 = disabled. */
     toolRateLimit = 60;
     /**
@@ -113,6 +133,10 @@ export class McpTransport {
     setDenyTools(tools) {
         this.denyTools = tools;
     }
+    /** Enable lazy-tools mode: tools/list omits inputSchema; clients use tools/schema to fetch it. */
+    setLazyTools(enabled) {
+        this.lazyTools = enabled;
+    }
     /** Configure per-session tool call rate limiting (calls/minute, 0 = disabled). */
     setToolRateLimit(limit) {
         this.toolRateLimit = limit;
@@ -281,6 +305,7 @@ export class McpTransport {
         this.schemaValidators.delete(schema.name);
         this.outputValidators.delete(schema.name);
         this.wireSchemaCache = null;
+        this.wireSchemaCacheLazy = null;
         this.tools.set(schema.name, {
             schema,
             handler,
@@ -292,6 +317,7 @@ export class McpTransport {
         this.schemaValidators.delete(name);
         this.outputValidators.delete(name);
         this.wireSchemaCache = null;
+        this.wireSchemaCacheLazy = null;
         return this.tools.delete(name);
     }
     deregisterToolsByPrefix(prefix) {
@@ -306,10 +332,51 @@ export class McpTransport {
                 count++;
             }
         }
-        if (count > 0)
+        if (count > 0) {
             this.wireSchemaCache = null;
+            this.wireSchemaCacheLazy = null;
+        }
         return count;
     }
+    /**
+     * Soft cleanup of stale per-connection state, used by the bridge's
+     * grace-period resumption path BEFORE calling `attach(ws)` with a new
+     * WebSocket. Unlike `detach()`, this does NOT abort in-flight tool calls
+     * or zero `activeToolCalls` — grace-period semantics preserve those
+     * across the reconnect. It only:
+     *
+     *  1. Removes the old WebSocket's "message" listener so it can't fire
+     *     against the new connection's state.
+     *  2. Rejects any pending elicitation requests, because the original
+     *     client that issued them may not be the one reattaching, and an
+     *     unrelated client should not be allowed to answer another client's
+     *     elicitation by id collision.
+     *
+     * Without this, two leaks survive a resumption:
+     *  - The old `ws.on("message", ...)` listener accumulates (gen-guarded
+     *    so it no-ops, but still attached to the now-closed socket).
+     *  - `pendingElicitations` from the old connection persist in the map;
+     *    the elicit timer keeps ticking and resolving against the NEW
+     *    `activeWs`, surfacing prompts to a client that didn't request them.
+     */
+    detachSoft() {
+        if (this.activeWs && this.activeListener) {
+            this.activeWs.removeListener("message", this.activeListener);
+            this.activeListener = null;
+        }
+        for (const [, pending] of this.pendingElicitations) {
+            pending.reject(new Error("Client disconnected before responding to elicitation"));
+        }
+        this.pendingElicitations.clear();
+        // Snapshot in-flight ids so the per-call finally can clean them up after
+        // attach() flips `this.generation`. Merge into the existing set rather
+        // than replacing it — multiple back-to-back grace-period reconnects can
+        // leave several "old" generations of tool calls in flight, and a later
+        // detachSoft must not lose ids carried over from an earlier one.
+        for (const id of this.inFlightControllers.keys()) {
+            this.detachSoftInflight.add(id);
+        }
+    }
     detach() {
         // Remove listener from old WebSocket to prevent accumulation
         if (this.activeWs && this.activeListener) {
@@ -322,6 +389,9 @@ export class McpTransport {
         }
         this.inFlightControllers.clear();
         this.inFlightToolNames.clear();
+        // Hard detach also drops any pending detachSoft snapshot — those calls
+        // are aborted, their finally clauses can no longer leak.
+        this.detachSoftInflight.clear();
         // Reject all pending elicitation requests so callers don't hang after disconnect
         for (const [, pending] of this.pendingElicitations) {
             pending.reject(new Error("Client disconnected before responding to elicitation"));
@@ -342,6 +412,7 @@ export class McpTransport {
         return {
             callCount: this.callCount,
             errorCount: this.errorCount,
+            approvalRejectionCount: this.approvalRejectionCount,
             activeToolCalls: this.activeToolCalls,
             inFlightTools: [...this.inFlightToolNames.values()],
             startedAt: this.sessionStartedAt,
@@ -363,6 +434,7 @@ export class McpTransport {
         }
         // Invalidate wire cache — categories are stripped but getToolSchemas reads them
         this.wireSchemaCache = null;
+        this.wireSchemaCacheLazy = null;
     }
     /** Returns all registered tool schemas — used by searchTools for keyword/category discovery. */
     getToolSchemas() {
@@ -608,15 +680,33 @@ export class McpTransport {
                             };
                             break;
                         }
-                        if (!this.wireSchemaCache) {
-                            this.wireSchemaCache = Array.from(this.tools.values()).map((t) => {
-                                // Strip internal-only fields before sending on the wire.
-                                // cache_control is intentionally NOT stripped — it passes through to clients.
-                                const { extensionRequired: _ext, timeoutMs: _timeout, categories: _cat, outputSchema: _outputSchema, ...wireSchema } = t.schema;
-                                return wireSchema;
-                            });
+                        if (this.lazyTools) {
+                            // Lazy mode: strip inputSchema from wire response.
+                            // Clients must call tools/schema to fetch the full schema before tools/call.
+                            if (!this.wireSchemaCacheLazy) {
+                                this.wireSchemaCacheLazy = Array.from(this.tools.values()).map((t) => {
+                                    // Strip internal-only fields AND inputSchema in lazy mode.
+                                    // cache_control is intentionally NOT stripped — it passes through to clients.
+                                    const { extensionRequired: _ext, timeoutMs: _timeout, categories: _cat, outputSchema: _outputSchema, inputSchema: _inputSchema, ...wireSchema } = t.schema;
+                                    return wireSchema;
+                                });
+                            }
+                        }
+                        else {
+                            if (!this.wireSchemaCache) {
+                                this.wireSchemaCache = Array.from(this.tools.values()).map((t) => {
+                                    // Strip internal-only fields before sending on the wire.
+                                    // cache_control is intentionally NOT stripped — it passes through to clients.
+                                    const { extensionRequired: _ext, timeoutMs: _timeout, categories: _cat, outputSchema: _outputSchema, ...wireSchema } = t.schema;
+                                    return wireSchema;
+                                });
+                            }
                         }
-                        const allTools = this.wireSchemaCache;
+                        const allTools = this.lazyTools
+                            ? // biome-ignore lint/style/noNonNullAssertion: built above
+                                this.wireSchemaCacheLazy
+                            : // biome-ignore lint/style/noNonNullAssertion: built above
+                                this.wireSchemaCache;
                         // Parse cursor (opaque base64-encoded decimal offset)
                         const listParams = msg.params;
                         let offset = 0;
@@ -649,6 +739,48 @@ export class McpTransport {
                         };
                         break;
                     }
+                    case "tools/schema": {
+                        // Fetch full schema for a single tool by name.
+                        // Always available regardless of lazyTools mode.
+                        // Schema validation uses in-memory schema regardless of lazyTools mode.
+                        const schemaParams = msg.params;
+                        if (typeof schemaParams?.name !== "string" || !schemaParams.name) {
+                            response = {
+                                jsonrpc: "2.0",
+                                id: msg.id,
+                                error: {
+                                    code: ErrorCodes.INVALID_PARAMS,
+                                    message: 'Missing required param: "name"',
+                                },
+                            };
+                            break;
+                        }
+                        const toolEntry = this.tools.get(schemaParams.name);
+                        if (!toolEntry) {
+                            response = {
+                                jsonrpc: "2.0",
+                                id: msg.id,
+                                error: {
+                                    code: ErrorCodes.METHOD_NOT_FOUND,
+                                    message: `Tool not found: ${schemaParams.name}`,
+                                },
+                            };
+                            break;
+                        }
+                        response = {
+                            jsonrpc: "2.0",
+                            id: msg.id,
+                            result: {
+                                name: toolEntry.schema.name,
+                                description: toolEntry.schema.description,
+                                inputSchema: toolEntry.schema.inputSchema,
+                                ...(toolEntry.schema.outputSchema !== undefined && {
+                                    outputSchema: toolEntry.schema.outputSchema,
+                                }),
+                            },
+                        };
+                        break;
+                    }
                     case "tools/call": {
                         if (!this.initialized) {
                             response = {
@@ -832,7 +964,11 @@ export class McpTransport {
                             };
                         }
                         else {
-                            const startTime = Date.now();
+                            // startTime is captured AFTER the approval gate (below) so that
+                            // human-decision wait time is excluded from tool stats. Capturing
+                            // it here would inflate avgDurationMs / p95 / p99 by the entire
+                            // approval wait — see fix for approval-gate stats pollution bug.
+                            let startTime = 0;
                             const callId = Math.random().toString(36).slice(2, 10);
                             const callLog = this.logger.child({ tool: params.name, callId });
                             let timedOut = false;
@@ -874,7 +1010,8 @@ export class McpTransport {
                                 // schemas use additionalProperties:false, so leaving it in causes
                                 // AJV to reject the call with -32602.
                                 const { _meta: _stripped, ...toolArgs } = rawArgs;
-                                // AJV structural validation
+                                // Schema validation uses in-memory schema regardless of lazyTools mode.
+                                // AJV compiles from tool.schema.inputSchema, not from the wire response.
                                 const validate = this.getValidator(params.name);
                                 if (validate && !validate(toolArgs)) {
                                     this.callCount++;
@@ -923,8 +1060,15 @@ export class McpTransport {
                                         this.activeToolCalls--;
                                         this.inFlightToolNames.delete(msg.id);
                                         this.inFlightControllers.delete(msg.id);
-                                        this.errorCount++;
-                                        this.activityLog?.record(params.name, Date.now() - startTime, "error", undefined, this.sessionId ?? undefined);
+                                        // Approval rejections/expiries are NOT tool failures — track
+                                        // them on a dedicated counter and record a lifecycle event
+                                        // (not a tool entry) so stats() avg/p95/p99 stay clean.
+                                        this.approvalRejectionCount++;
+                                        this.activityLog?.recordEvent("approval_rejected", {
+                                            tool: params.name,
+                                            decision,
+                                            sessionId: this.sessionId ?? undefined,
+                                        });
                                         response = {
                                             jsonrpc: "2.0",
                                             id: msg.id,
@@ -943,6 +1087,10 @@ export class McpTransport {
                                         break;
                                     }
                                 }
+                                // Start the duration clock now — AFTER the approval gate has
+                                // resolved — so stats reflect actual tool execution time, not
+                                // the time the human spent thinking about the approval.
+                                startTime = Date.now();
                                 try {
                                     const effectiveTimeout = tool.timeoutMs ?? TOOL_TIMEOUT_MS;
                                     const timeoutPromise = new Promise((_, reject) => {
@@ -1024,11 +1172,17 @@ export class McpTransport {
                                 finally {
                                     if (timeoutHandle !== undefined)
                                         clearTimeout(timeoutHandle);
-                                    // Only touch shared state if we're still on the same generation.
-                                    // detach() clears inFlightControllers and resets activeToolCalls for
-                                    // new connections; an orphaned finally from a previous generation must
-                                    // not delete the new session's controller or skew its counter.
-                                    if (gen === this.generation) {
+                                    // Only touch shared state if we're still on the same generation,
+                                    // OR if this id was snapshotted by detachSoft() (grace-period
+                                    // resumption). detach() clears inFlightControllers and resets
+                                    // activeToolCalls for hard reconnects; an orphaned finally
+                                    // from a previous generation must not delete the new session's
+                                    // controller or skew its counter — UNLESS detachSoft preserved
+                                    // this id, in which case its slot in inFlightControllers and
+                                    // its activeToolCalls count survived the reattach and MUST be
+                                    // released now that the call has settled.
+                                    const wasSoftPreserved = this.detachSoftInflight.delete(msg.id);
+                                    if (gen === this.generation || wasSoftPreserved) {
                                         this.inFlightControllers.delete(msg.id);
                                         this.inFlightToolNames.delete(msg.id);
                                         this.activeToolCalls = Math.max(0, this.activeToolCalls - 1);