tunnel-mcp 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -11,6 +11,37 @@ 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
+
+- **The auto-downloaded cloudflared binary is now pinned and integrity-verified.**
+  Instead of pulling `releases/latest` unverified, tunnel-mcp downloads a pinned
+  cloudflared version and checks its SHA-256 against a hash committed in the
+  source (and covered by the npm provenance attestation) before the binary is
+  extracted, installed, or made executable — so a tampered or wrong-version
+  binary is refused, not run. Bump with `scripts/refresh-cloudflared-hashes.mjs`.
+- **Supply-chain hardening of the pipeline:** every GitHub Action is pinned to a
+  full commit SHA (not a mutable tag), workflow token permissions default to
+  read-only, a `dependency-review` gate blocks PRs that introduce known-vulnerable
+  dependencies, and OpenSSF Scorecard + CodeQL scanning run on the repository. See
+  the new "Supply chain" section in `SECURITY.md`.
+
 ## [0.1.5] - 2026-07-01
 
 ### Changed
@@ -132,7 +163,9 @@ 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.5...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
 [0.1.3]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.2...v0.1.3

package/SECURITY.md

@@ -83,6 +83,36 @@ share a join link with anyone.
   `tunnel_close`, an idle timeout (30 minutes with no messages), or the
   host process exiting. Nothing persists past teardown.
 
+## Supply chain
+
+tunnel-mcp is a security-sensitive tool, so its build and distribution chain is
+hardened against tampering:
+
+- **npm provenance.** Releases are published from GitHub Actions via npm Trusted
+  Publishing (OIDC) — no long-lived npm token exists — and every published
+  version carries a signed provenance attestation. You can verify a release was
+  built from this repository with `npm audit signatures`.
+- **The auto-downloaded cloudflared binary is pinned and verified.** tunnel-mcp
+  fetches a specific pinned cloudflared version and checks the artifact's SHA-256
+  against a hash committed in the source (and covered by the provenance
+  attestation) **before** it is extracted, moved into place, or made executable.
+  A mismatched or tampered binary is refused, not run.
+- **Pinned, reviewed dependencies.** Production dependencies are minimal and
+  installed from a committed lockfile with integrity hashes (`npm ci`).
+  Dependabot proposes updates, and a `dependency-review` gate blocks any pull
+  request that would introduce a dependency with a known high-severity
+  vulnerability.
+- **Pinned GitHub Actions + least privilege.** Every third-party GitHub Action is
+  pinned to a full commit SHA (not a mutable tag), and workflow `GITHUB_TOKEN`
+  permissions default to read-only, scoped up only where a job requires it.
+- **Continuous scanning.** OpenSSF Scorecard tracks the repository's
+  supply-chain posture, and CodeQL runs static analysis on every push and pull
+  request.
+
+To bump the pinned cloudflared version, a maintainer runs
+`node scripts/refresh-cloudflared-hashes.mjs <version>` and commits the updated
+version and checksums, keeping the pin auditable.
+
 ## Known Limitations / Threat Model
 
 This is an MVP and it is important to be honest about what it does **not**

package/dist/cloudflared/provision.d.ts

@@ -1,18 +1,27 @@
+export declare const CLOUDFLARED_VERSION = "2026.6.1";
+export declare const CLOUDFLARED_SHA256: Record<string, string>;
 export declare function cloudflaredBinName(platform: NodeJS.Platform): string;
+export declare function cloudflaredAsset(platform: NodeJS.Platform, arch: string): string;
 export declare function cloudflaredDownloadUrl(platform: NodeJS.Platform, arch: string): string;
+export declare function expectedSha256(platform: NodeJS.Platform, arch: string): string;
 export interface DownloadDeps {
     fetchImpl?: typeof fetch;
+    expectedSha256?: string;
 }
 /**
  * Download cloudflared from `url` and install it at `destBinPath`.
  *
+ * Integrity: when `deps.expectedSha256` is provided, the downloaded artifact is
+ * hashed and rejected on any mismatch BEFORE it is extracted, moved into place,
+ * or made executable — so a corrupt, tampered, or wrong-version binary never
+ * reaches the cache or runs.
+ *
  * Atomic: the binary is downloaded/extracted into a unique location under
  * os.tmpdir() and only moved into `destBinPath` once it is fully present and
- * valid, so a failed/partial download never poisons the destination (callers
- * that check `fs.existsSync(destBinPath)` to skip re-downloading are safe).
+ * verified, so a failed/partial download never poisons the destination.
  *
- * Any failure anywhere in this path (network, tar extraction, fs ops) is
- * caught, temp artifacts (and any partially-installed dest) are cleaned up,
+ * Any failure anywhere in this path (network, checksum, tar extraction, fs ops)
+ * is caught, temp artifacts (and any partially-installed dest) are cleaned up,
  * and a single readable error with a manual-install pointer is thrown.
  */
 export declare function downloadCloudflared(url: string, destBinPath: string, deps?: DownloadDeps): Promise<void>;

package/dist/cloudflared/provision.js

@@ -6,8 +6,23 @@ import { execSync, execFileSync } from 'node:child_process';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
 import { BIN_DIR } from '../config.js';
-const RELEASE_BASE = 'https://github.com/cloudflare/cloudflared/releases/latest/download';
+// Pin a specific cloudflared release and verify the downloaded artifact against a
+// SHA-256 committed here (and provenance-attested when the package is published),
+// so the tool never executes an unverified binary and never silently picks up a
+// changed "latest". Bump both together with:
+//   node scripts/refresh-cloudflared-hashes.mjs <version>
+export const CLOUDFLARED_VERSION = '2026.6.1';
+const RELEASE_BASE = `https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}`;
 const MANUAL_INSTALL_POINTER = 'https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/';
+// SHA-256 of each pinned release asset (Cloudflare does not publish a checksum
+// manifest, so these are computed from the official assets by the refresh script).
+export const CLOUDFLARED_SHA256 = {
+    'cloudflared-darwin-amd64.tgz': 'd7a66b525fe76820da6e5406611b61e48b40de682368ac00454d9158f085be4b',
+    'cloudflared-darwin-arm64.tgz': 'f6d4c439c6c782b83264951d327989ce5e23373acc5942b872411601fedb020d',
+    'cloudflared-linux-amd64': '5861a10a438fe8ddcfebb3b830f83966cbf193edafce0fe2eeb198fbae1f7a22',
+    'cloudflared-linux-arm64': '59816ce9b16db71f5bc2a86d59b3632a96c8c3ee934bde2bc8641ee83a6070eb',
+    'cloudflared-windows-amd64.exe': '5253e66f1f493c4e13539749f1aa86fd0c61e3072900fec29a44ba046a6d97e2',
+};
 function arch2cf(arch) {
     if (arch === 'x64')
         return 'amd64';
@@ -18,16 +33,34 @@ function arch2cf(arch) {
 export function cloudflaredBinName(platform) {
     return platform === 'win32' ? 'cloudflared.exe' : 'cloudflared';
 }
-export function cloudflaredDownloadUrl(platform, arch) {
+// The release asset filename for this platform/arch — the single key shared by
+// the download URL and the pinned-checksum lookup, so they can never disagree.
+export function cloudflaredAsset(platform, arch) {
     const a = arch2cf(arch);
     if (platform === 'darwin')
-        return `${RELEASE_BASE}/cloudflared-darwin-${a}.tgz`;
+        return `cloudflared-darwin-${a}.tgz`;
     if (platform === 'linux')
-        return `${RELEASE_BASE}/cloudflared-linux-${a}`;
+        return `cloudflared-linux-${a}`;
     if (platform === 'win32')
-        return `${RELEASE_BASE}/cloudflared-windows-${a}.exe`;
+        return `cloudflared-windows-${a}.exe`;
     throw new Error(`unsupported platform: ${platform}`);
 }
+export function cloudflaredDownloadUrl(platform, arch) {
+    return `${RELEASE_BASE}/${cloudflaredAsset(platform, arch)}`;
+}
+export function expectedSha256(platform, arch) {
+    const asset = cloudflaredAsset(platform, arch);
+    const sha = CLOUDFLARED_SHA256[asset];
+    if (!sha) {
+        throw new Error(`no pinned checksum for ${asset} (cloudflared ${CLOUDFLARED_VERSION})`);
+    }
+    return sha;
+}
+async function sha256File(p) {
+    const hash = crypto.createHash('sha256');
+    await pipeline(fs.createReadStream(p), hash);
+    return hash.digest('hex');
+}
 function onPath() {
     try {
         const cmd = process.platform === 'win32' ? 'where cloudflared' : 'command -v cloudflared';
@@ -68,13 +101,17 @@ function rmQuiet(p) {
 /**
  * Download cloudflared from `url` and install it at `destBinPath`.
  *
+ * Integrity: when `deps.expectedSha256` is provided, the downloaded artifact is
+ * hashed and rejected on any mismatch BEFORE it is extracted, moved into place,
+ * or made executable — so a corrupt, tampered, or wrong-version binary never
+ * reaches the cache or runs.
+ *
  * Atomic: the binary is downloaded/extracted into a unique location under
  * os.tmpdir() and only moved into `destBinPath` once it is fully present and
- * valid, so a failed/partial download never poisons the destination (callers
- * that check `fs.existsSync(destBinPath)` to skip re-downloading are safe).
+ * verified, so a failed/partial download never poisons the destination.
  *
- * Any failure anywhere in this path (network, tar extraction, fs ops) is
- * caught, temp artifacts (and any partially-installed dest) are cleaned up,
+ * Any failure anywhere in this path (network, checksum, tar extraction, fs ops)
+ * is caught, temp artifacts (and any partially-installed dest) are cleaned up,
  * and a single readable error with a manual-install pointer is thrown.
  */
 export async function downloadCloudflared(url, destBinPath, deps = {}) {
@@ -90,6 +127,13 @@ export async function downloadCloudflared(url, destBinPath, deps = {}) {
             throw new Error(`cloudflared download failed${status}`);
         }
         await pipeline(Readable.fromWeb(res.body), fs.createWriteStream(tmpFile));
+        // Verify integrity of the downloaded asset before trusting it in any way.
+        if (deps.expectedSha256) {
+            const actual = await sha256File(tmpFile);
+            if (actual.toLowerCase() !== deps.expectedSha256.toLowerCase()) {
+                throw new Error(`checksum mismatch — expected ${deps.expectedSha256}, got ${actual}. Refusing to install a binary that does not match the pinned cloudflared release`);
+            }
+        }
         if (url.endsWith('.tgz')) {
             fs.mkdirSync(tmpExtractDir, { recursive: true });
             execFileSync('tar', ['-xzf', tmpFile, '-C', tmpExtractDir]); // extracts a `cloudflared` binary
@@ -125,6 +169,8 @@ export async function ensureCloudflared() {
         return dest;
     fs.mkdirSync(BIN_DIR, { recursive: true });
     const url = cloudflaredDownloadUrl(process.platform, process.arch);
-    await downloadCloudflared(url, dest);
+    await downloadCloudflared(url, dest, {
+        expectedSha256: expectedSha256(process.platform, process.arch),
+    });
     return dest;
 }

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.5",
+  "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"
   }
 }