tunnel-mcp 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -11,6 +11,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Nothing yet.
 
+## [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 +148,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.5...HEAD
+[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.6...HEAD
+[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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnel-mcp",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Let two developers' Claude agents talk directly through an ephemeral, end-to-end-encrypted tunnel.",
   "type": "module",
   "bin": {