tunnel-mcp 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -11,6 +11,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Nothing yet.
 
+## [0.1.7] - 2026-07-01
+
+### Security
+
+- **Hardened the untrusted-input decoders against malformed frames.** Added
+  property-based fuzzing (`fast-check`) of `decrypt`, `decodeFrame`, and
+  `parseLink`, which surfaced two robustness bugs — both now fixed:
+  - `decodeFrame` did a blind `JSON.parse(...) as ControlFrame`; a payload that
+    parsed to `null` or a primitive could crash a downstream `frame.t` access. It
+    now rejects anything that isn't a proper frame object with a string `t`.
+  - The guest's WebSocket message handler only guarded frame decoding, so a
+    malformed frame from an untrusted host (e.g. an `auth_ok` with no `backlog`)
+    could throw uncaught and crash the guest. The whole handler is now defended,
+    matching the host relay.
+
 ## [0.1.6] - 2026-07-01
 
 ### Security
@@ -148,7 +163,8 @@ install-skill` copies the `tunnel-etiquette` skill into `~/.claude/skills`
   declaring a fix "confirmed".
 - Test suite of 109 tests built with vitest, developed test-first (TDD).
 
-[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.6...HEAD
+[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.7...HEAD
+[0.1.7]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.3...v0.1.4

package/dist/protocol/messages.js

@@ -30,6 +30,17 @@ export function decrypt(msg, key) {
 export function encodeFrame(frame) {
     return JSON.stringify(frame);
 }
+// Validate enough of the shape that the `as ControlFrame` cast is honest: every
+// caller switches on `frame.t`, so a parsed value that is null, a primitive, an
+// array, or lacks a string `t` must be rejected here (callers wrap this in
+// try/catch) rather than handed back as a frame that crashes `frame.t`.
 export function decodeFrame(data) {
-    return JSON.parse(data);
+    const parsed = JSON.parse(data);
+    if (parsed === null ||
+        typeof parsed !== 'object' ||
+        Array.isArray(parsed) ||
+        typeof parsed.t !== 'string') {
+        throw new Error('malformed control frame');
+    }
+    return parsed;
 }

package/dist/relay/guestClient.js

@@ -58,38 +58,48 @@ export class GuestClient extends EventEmitter {
                 reject(e);
             };
             ws.on('message', (data) => {
-                let frame;
+                // The host is untrusted: a malformed or schema-invalid frame must never
+                // crash the guest. decodeFrame guarantees a string `t`, but a variant's
+                // fields (e.g. auth_ok.backlog) are still unchecked, so defend the whole
+                // handler like the host relay does. A swallowed frame just stalls, and
+                // the overall connect deadline rejects on a stall.
                 try {
-                    frame = decodeFrame(data.toString());
+                    let frame;
+                    try {
+                        frame = decodeFrame(data.toString());
+                    }
+                    catch {
+                        return;
+                    }
+                    if (frame.t === 'challenge') {
+                        ws.send(encodeFrame({
+                            t: 'auth',
+                            response: respondChallenge(frame.nonce, this.link.key),
+                            name: this.guestName,
+                            sinceSeq,
+                        }));
+                    }
+                    else if (frame.t === 'auth_ok') {
+                        for (const m of frame.backlog)
+                            this.log.record(m);
+                        settleResolve({ goal: frame.goal, peerName: frame.peerName });
+                    }
+                    else if (frame.t === 'auth_fail') {
+                        settleReject(new Error(`auth failed: ${frame.reason}`));
+                        ws.close();
+                    }
+                    else if (frame.t === 'msg') {
+                        this.log.record(frame.msg);
+                        const waiter = this.pending.get(frame.msg.id);
+                        if (waiter) {
+                            this.pending.delete(frame.msg.id);
+                            waiter.resolve(frame.msg.seq);
+                        }
+                        this.emit('message', frame.msg);
+                    }
                 }
                 catch {
-                    return;
-                }
-                if (frame.t === 'challenge') {
-                    ws.send(encodeFrame({
-                        t: 'auth',
-                        response: respondChallenge(frame.nonce, this.link.key),
-                        name: this.guestName,
-                        sinceSeq,
-                    }));
-                }
-                else if (frame.t === 'auth_ok') {
-                    for (const m of frame.backlog)
-                        this.log.record(m);
-                    settleResolve({ goal: frame.goal, peerName: frame.peerName });
-                }
-                else if (frame.t === 'auth_fail') {
-                    settleReject(new Error(`auth failed: ${frame.reason}`));
-                    ws.close();
-                }
-                else if (frame.t === 'msg') {
-                    this.log.record(frame.msg);
-                    const waiter = this.pending.get(frame.msg.id);
-                    if (waiter) {
-                        this.pending.delete(frame.msg.id);
-                        waiter.resolve(frame.msg.seq);
-                    }
-                    this.emit('message', frame.msg);
+                    /* untrusted-frame guard: ignore anything malformed */
                 }
             });
             ws.on('close', () => this.failPending(new Error('tunnel disconnected')));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnel-mcp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Let two developers' Claude agents talk directly through an ephemeral, end-to-end-encrypted tunnel.",
   "type": "module",
   "bin": {
@@ -68,12 +68,13 @@
     "@anthropic-ai/sdk": "^0.109.0",
     "@types/node": "^20.14.0",
     "@types/ws": "^8.5.10",
-    "@vitest/coverage-v8": "^2.0.0",
+    "@vitest/coverage-v8": "^4.1.9",
     "eslint": "^9.9.0",
+    "fast-check": "^4.8.0",
     "prettier": "^3.3.0",
     "tsx": "^4.16.0",
     "typescript": "^5.5.0",
     "typescript-eslint": "^8.0.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.9"
   }
 }