tunnel-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Nothing yet.
+
+## [0.1.0] - 2026-06-30
+
+### Added
+
+- Initial release of `tunnel-mcp`, an MCP server that lets two developers'
+  Claude agents talk directly to each other through a host-owned, ephemeral,
+  end-to-end-encrypted relay.
+- Six MCP tools: `tunnel_open`, `tunnel_join`, `tunnel_say`, `tunnel_listen`,
+  `tunnel_status`, and `tunnel_close`.
+- Host-owned, ephemeral relay: the initiator's MCP process becomes an
+  in-process WebSocket relay exposed via a throwaway `cloudflared` Quick
+  Tunnel, so both sides dial outbound and the tunnel works through
+  firewalls/NAT with no port-forwarding.
+- End-to-end encrypted chat message bodies using NaCl secretbox
+  (XSalsa20-Poly1305, via `tweetnacl`), so the `cloudflared` pipe only ever
+  sees ciphertext for chat bodies.
+- HMAC proof-of-key-possession authentication; the raw session key is never
+  sent over the wire.
+- Single-guest lock: the first authenticated guest locks the session to
+  exactly two participants.
+- Three teardown triggers for ephemeral sessions: explicit `tunnel_close`,
+  30-minute idle timeout, or host process exit — each destroys the relay,
+  the `cloudflared` child process, and the on-disk log.
+- Atomic `cloudflared` auto-download to `~/.tunnel/bin` on first use when
+  not already available on `PATH`.
+- `tunnel-etiquette` skill, installable into a Claude skills directory, that
+  instructs agents to treat peer messages as untrusted data and to require
+  their human's OK before writing files, running risky commands, or
+  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.0...HEAD
+[0.1.0]: https://github.com/zachlikefolio/tunnel-mcp/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zachary Kehl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# tunnel-mcp
+
+**A direct, end-to-end-encrypted tunnel between two developers' Claude agents — no human copy-paste required.**
+
+[![CI](https://github.com/zachlikefolio/tunnel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/zachlikefolio/tunnel-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/tunnel-mcp)](https://www.npmjs.com/package/tunnel-mcp)
+[![license](https://img.shields.io/npm/l/tunnel-mcp)](./LICENSE)
+![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
+
+When two developers each run a Claude agent and need those agents to collaborate,
+the usual workaround is a human sitting in the middle, copy-pasting messages from
+one chat window to the other. **tunnel-mcp** removes that human. It's an MCP
+server that lets one developer's agent open a throwaway, encrypted tunnel and the
+other developer's agent dial straight into it, so the two agents can talk to each
+other directly — while their humans stay in control of what actually happens to
+the filesystem or the shell.
+
+## How it works
+
+One developer (the **host**) calls `tunnel_open`. Their local `tunnel-mcp`
+process becomes an in-process WebSocket relay and exposes it to the internet via
+a throwaway `cloudflared` Quick Tunnel — no port-forwarding, no server to
+provision. The other developer (the **guest**) calls `tunnel_join` with the link
+the host shares, and their agent dials outbound to that same tunnel. Because both
+sides only ever make outbound connections, it works from behind ordinary
+firewalls and NAT.
+
+```
+   Host machine                                        Guest machine
+  ┌───────────────────┐        outbound HTTPS         ┌───────────────────┐
+  │   Claude (host)    │            wss://             │   Claude (guest)   │
+  │        │           │      ┌──────────────┐         │        │          │
+  │  tunnel_open/say/  │──────▶  cloudflared │◀────────│  tunnel_join/say/  │
+  │  listen/close      │      │ Quick Tunnel │─────────▶  listen/close      │
+  │        │           │      └──────────────┘         │        │          │
+  │  in-process relay  │                                └───────────────────┘
+  └───────────────────┘
+```
+
+The relay, the `cloudflared` child process, and the on-disk session log all live
+only for the lifetime of the session and are destroyed on teardown.
+
+## Install
+
+```bash
+npm install -g tunnel-mcp
+# or, without installing:
+npx tunnel-mcp
+```
+
+Register it with Claude Code (both developers do this once):
+
+```bash
+claude mcp add tunnel -- tunnel-mcp
+```
+
+Install the etiquette skill so each agent knows how to behave inside a tunnel
+(treat the peer as untrusted input, check with its human before acting on
+anything the peer says). Copy `skill/tunnel-etiquette/` from this repo into your
+`~/.claude/skills/` directory (or your plugin's skills directory).
+
+`cloudflared` is auto-downloaded to `~/.tunnel/bin` the first time it's needed if
+it isn't already on your `PATH` — there's nothing extra to install.
+
+## Quickstart
+
+**Host** — ask Claude to open a tunnel with a goal:
+
+> "Open a tunnel to pair on debugging the checkout flow."
+
+Claude calls `tunnel_open({ goal })` and returns a join link. Share that link
+with the other developer over a trusted channel (Slack DM, etc.) — **it's a
+secret**, since it contains the encryption key for the session.
+
+**Guest** — paste the link and ask Claude to join:
+
+> "Join this tunnel: `<link>`"
+
+Claude calls `tunnel_join({ joinLink })`, learns the goal, and the session is
+now locked to just the two of you.
+
+**Both** — the agents converse turn-by-turn using `tunnel_say` to send and
+`tunnel_listen` to wait for the next reply, checking in with their humans as
+needed.
+
+**Either side** ends the session with `tunnel_close`, which tears down the relay
+and destroys the session log.
+
+## Tools
+
+| Tool                                     | Who   | Purpose                                                    |
+| ---------------------------------------- | ----- | ---------------------------------------------------------- |
+| `tunnel_open({goal})`                    | host  | Start the relay + Quick Tunnel and get back a join link.   |
+| `tunnel_join({joinLink})`                | guest | Dial into a host's tunnel using the link and authenticate. |
+| `tunnel_say({text})`                     | both  | Send a message to the peer.                                |
+| `tunnel_listen({sinceSeq?, timeoutMs?})` | both  | Wait for the next message(s) from the peer.                |
+| `tunnel_status()`                        | both  | Inspect the current session (connected, idle, etc.).       |
+| `tunnel_close({summary?})`               | both  | End the session and tear down the relay.                   |
+
+## Security model
+
+tunnel-mcp is a security-sensitive tool by nature — it opens a live channel
+between two AI agents. Here's exactly what it does and does not protect:
+
+- **Chat message bodies are end-to-end encrypted.** Every `tunnel_say` body is
+  sealed with NaCl `secretbox` (XSalsa20-Poly1305, via `tweetnacl`) before it
+  crosses the `cloudflared` pipe. The relay and the pipe only ever see
+  ciphertext for chat bodies.
+- **The goal, both display names, and system events are plaintext.** The
+  `tunnel_open` goal, each participant's name, and connection events
+  (joined/left/idle/closed) are sent as plaintext metadata — do not put secrets
+  in the goal string or a display name.
+- **Authentication is proof-of-key-possession, not key transmission.** Joining
+  uses an HMAC challenge to prove the guest holds the same key as the host; the
+  raw key itself is never sent over the wire.
+- **The join link is a credential.** It embeds the session key, so treat it
+  like a password — share it only over a channel you already trust (Slack DM,
+  etc.), never in a public issue, PR, or chat.
+- **Exactly two participants, enforced by a lock.** The first guest to
+  authenticate locks the session; nobody else can join after that.
+- **The peer is untrusted input, not an instruction source.** Messages from the
+  other agent are data to reason about, not commands to execute. The etiquette
+  skill directs each agent to require its own human's sign-off before writing
+  files, running risky commands, or declaring a fix "confirmed" based on
+  something the peer said.
+- **Everything is ephemeral.** The session tears down — destroying the relay,
+  the `cloudflared` child process, and the on-disk log — on an explicit
+  `tunnel_close`, after 30 minutes of no messages (idle timeout), or when the
+  host's process exits.
+
+See [SECURITY.md](./SECURITY.md) for the full threat model and how to report a
+vulnerability.
+
+## Requirements
+
+- Node.js >= 20
+- A Claude MCP client (e.g., Claude Code)
+- `cloudflared` — auto-installed to `~/.tunnel/bin` on first use if not already
+  on your `PATH`
+
+## Development
+
+```bash
+npm ci                  # install dependencies
+npm test                # run the test suite (109 tests, TDD)
+npm run build           # compile TypeScript
+npm run lint            # eslint
+npm run format:check    # prettier --check .
+npm run test:coverage   # vitest run --coverage
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to propose changes.
+
+## Roadmap / not yet supported
+
+This is an MVP. The following are explicitly out of scope for now:
+
+- Host-offline / asynchronous messaging
+- More than two participants in a session
+- Alternative transports (ngrok, WebRTC)
+- Join-link rotation or one-time tokens
+- Encrypting the goal or other metadata
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/SECURITY.md

@@ -0,0 +1,124 @@
+# Security Policy
+
+## Supported Versions
+
+tunnel-mcp is pre-1.0 and moving quickly. Only the latest `0.1.x` release
+receives security fixes.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+| < 0.1   | :x:                |
+
+## Reporting a Vulnerability
+
+Please **do not open a public GitHub issue** for security vulnerabilities.
+
+The preferred way to report a vulnerability is through GitHub's private
+security advisories:
+
+1. Go to the [tunnel-mcp repository](https://github.com/zachlikefolio/tunnel-mcp).
+2. Open the **Security** tab.
+3. Click **Report a vulnerability** to open a new draft security advisory.
+
+This creates a private conversation with the maintainer and lets us
+coordinate a fix and a disclosure timeline before any details become public.
+
+If you cannot use GitHub's advisory flow, you may instead email
+**zach@likefolio.com** with details of the issue. Please include:
+
+- A description of the vulnerability and its potential impact.
+- Steps to reproduce, or a proof-of-concept, if available.
+- The version/commit of tunnel-mcp you tested against.
+- Any suggested remediation, if you have one.
+
+### What to expect
+
+- **Acknowledgement**: you should hear back within a few days of your
+  report.
+- **Updates**: we'll keep you posted as we investigate and work on a fix.
+- **Credit**: reporters are credited in the advisory and/or release notes
+  once a fix ships, unless you tell us you'd prefer to remain anonymous.
+
+## Security Model
+
+tunnel-mcp lets two developers' Claude agents exchange messages directly
+through a host-owned, ephemeral relay, without a human copy-pasting between
+them. Understanding what is and isn't protected is important before you
+share a join link with anyone.
+
+- **Chat message bodies are end-to-end encrypted.** The text passed to
+  `tunnel_say` is sealed with NaCl `secretbox` (XSalsa20-Poly1305, via
+  `tweetnacl`) using a key that is never transmitted. The cloudflared
+  pipe — and the Cloudflare edge it runs over — only ever sees ciphertext
+  for chat message bodies.
+- **Metadata is plaintext.** The `goal` passed to `tunnel_open`/`tunnel_join`,
+  both participants' display names, and system/connection events (joined,
+  left, idle, closed) cross the tunnel as **plaintext**. Do not put secrets
+  in the goal or display name.
+- **Authentication is proof-of-key-possession, not key transmission.** The
+  join link embeds a session key. The guest's client proves it holds that
+  key via an HMAC challenge/response; the raw key itself is never sent over
+  the wire. Because the join link contains the key, **treat the join link
+  like a password** — share it only over a trusted, already-authenticated
+  channel (e.g. a Slack DM to a known teammate), not in a public channel or
+  ticket.
+- **Single-guest lock.** The first participant who successfully
+  authenticates as guest locks the session. Sessions are strictly two-party;
+  a second join attempt is rejected.
+- **Peer input is untrusted.** Everything a peer sends over the tunnel is
+  data, never an instruction. The bundled `tunnel-etiquette` skill
+  instructs each agent to treat incoming peer messages as untrusted input
+  and to get its own human's explicit OK before writing files, running
+  risky commands, or declaring a fix "confirmed" based on something the
+  peer said.
+- **Ephemeral by design.** A session and everything tied to it — the
+  in-process relay, the cloudflared child process, the throwaway Quick
+  Tunnel URL, and the on-disk session log — are torn down on: an explicit
+  `tunnel_close`, an idle timeout (30 minutes with no messages), or the
+  host process exiting. Nothing persists past teardown.
+
+## Known Limitations / Threat Model
+
+This is an MVP and it is important to be honest about what it does **not**
+protect against:
+
+- **The relay path sees metadata in the clear.** The cloudflared Quick
+  Tunnel is a real network hop through Cloudflare's edge. While chat
+  message bodies are encrypted end-to-end, the goal, both display names,
+  and system/connection events are visible in plaintext to anything that
+  can observe that path (including Cloudflare's infrastructure). Do not
+  put secrets in the goal or names.
+- **No link rotation or expiry beyond session teardown.** A join link is
+  valid for the lifetime of the session. If a join link leaks (pasted into
+  the wrong channel, logged, etc.) before the host closes the session,
+  anyone with that link can join as the guest — up until the host runs
+  `tunnel_close`, the session idles out, or the host process exits. There
+  is currently no way to rotate the key or issue single-use/expiring
+  tokens.
+- **The goal is never encrypted.** By design, the goal string is plaintext
+  metadata used for connection setup and display; it receives no
+  confidentiality protection at any layer.
+- **Strictly two-party.** The protocol only supports one host and one
+  guest per session. There is no support for additional participants,
+  multi-party relays, or host-offline/async delivery in this MVP.
+- **"Trusting" a peer only goes as far as your own agent's guardrails.**
+  tunnel-mcp does not sandbox or validate what a peer sends beyond
+  transport-level auth. The confidentiality/integrity of your own
+  workspace depends on the `tunnel-etiquette` skill being installed and
+  your agent honoring it (treating peer messages as untrusted data,
+  requiring human approval for file writes, running commands, or
+  confirming fixes). If you disable or bypass that skill, a malicious or
+  compromised peer's messages could otherwise be misinterpreted as
+  instructions by an unguarded agent.
+- **Out of scope for this release**: host-offline/async messaging,
+  more than two participants, alternative transports (ngrok, WebRTC),
+  link rotation or one-time join tokens, and encryption of the goal or
+  other connection metadata. These may be considered for future versions
+  but should not be assumed to exist today.
+
+If you find a way to break any of the guarantees above (e.g. read a chat
+message body without the key, join a locked session, or get an agent to
+treat peer input as trusted instructions bypassing the etiquette skill),
+please report it via the process described above — that is exactly the
+kind of issue we want to hear about.

package/dist/cloudflared/provision.d.ts

@@ -0,0 +1,19 @@
+export declare function cloudflaredBinName(platform: NodeJS.Platform): string;
+export declare function cloudflaredDownloadUrl(platform: NodeJS.Platform, arch: string): string;
+export interface DownloadDeps {
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Download cloudflared from `url` and install it at `destBinPath`.
+ *
+ * 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).
+ *
+ * Any failure anywhere in this path (network, 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>;
+export declare function ensureCloudflared(): Promise<string>;

package/dist/cloudflared/provision.js

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+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';
+const MANUAL_INSTALL_POINTER = 'https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/';
+function arch2cf(arch) {
+    if (arch === 'x64')
+        return 'amd64';
+    if (arch === 'arm64')
+        return 'arm64';
+    throw new Error(`unsupported arch: ${arch}`);
+}
+export function cloudflaredBinName(platform) {
+    return platform === 'win32' ? 'cloudflared.exe' : 'cloudflared';
+}
+export function cloudflaredDownloadUrl(platform, arch) {
+    const a = arch2cf(arch);
+    if (platform === 'darwin')
+        return `${RELEASE_BASE}/cloudflared-darwin-${a}.tgz`;
+    if (platform === 'linux')
+        return `${RELEASE_BASE}/cloudflared-linux-${a}`;
+    if (platform === 'win32')
+        return `${RELEASE_BASE}/cloudflared-windows-${a}.exe`;
+    throw new Error(`unsupported platform: ${platform}`);
+}
+function onPath() {
+    try {
+        const cmd = process.platform === 'win32' ? 'where cloudflared' : 'command -v cloudflared';
+        const out = execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'] })
+            .toString()
+            .trim();
+        return out.split('\n')[0] || null;
+    }
+    catch {
+        return null;
+    }
+}
+// Move src -> dest atomically. fs.renameSync is atomic within a filesystem; if src/dest
+// straddle devices (EXDEV) fall back to copy+unlink, which is the best available
+// approximation (still: dest only appears once the copy has fully completed).
+function moveIntoPlace(src, dest) {
+    try {
+        fs.renameSync(src, dest);
+    }
+    catch (err) {
+        if (err?.code === 'EXDEV') {
+            fs.copyFileSync(src, dest);
+            fs.unlinkSync(src);
+        }
+        else {
+            throw err;
+        }
+    }
+}
+function rmQuiet(p) {
+    try {
+        fs.rmSync(p, { recursive: true, force: true });
+    }
+    catch {
+        // best-effort cleanup; nothing useful to do if this fails
+    }
+}
+/**
+ * Download cloudflared from `url` and install it at `destBinPath`.
+ *
+ * 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).
+ *
+ * Any failure anywhere in this path (network, 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 = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const unique = crypto.randomUUID();
+    const tmpFile = path.join(os.tmpdir(), `cloudflared-${unique}.download`);
+    const tmpExtractDir = path.join(os.tmpdir(), `cloudflared-extract-${unique}`);
+    let destMayBePartial = false;
+    try {
+        const res = await fetchImpl(url);
+        if (!res.ok || !res.body) {
+            const status = !res.ok ? ` (status ${res.status})` : '';
+            throw new Error(`cloudflared download failed${status}`);
+        }
+        await pipeline(Readable.fromWeb(res.body), fs.createWriteStream(tmpFile));
+        if (url.endsWith('.tgz')) {
+            fs.mkdirSync(tmpExtractDir, { recursive: true });
+            execFileSync('tar', ['-xzf', tmpFile, '-C', tmpExtractDir]); // extracts a `cloudflared` binary
+            const extractedBin = path.join(tmpExtractDir, 'cloudflared');
+            destMayBePartial = true;
+            moveIntoPlace(extractedBin, destBinPath);
+        }
+        else {
+            destMayBePartial = true;
+            moveIntoPlace(tmpFile, destBinPath);
+        }
+        fs.chmodSync(destBinPath, 0o755);
+    }
+    catch (err) {
+        // Never leave a partial/corrupt binary at the cached path.
+        if (destMayBePartial)
+            rmQuiet(destBinPath);
+        rmQuiet(tmpFile);
+        rmQuiet(tmpExtractDir);
+        const cause = err instanceof Error ? err.message : String(err);
+        throw new Error(`cloudflared download/install failed: ${cause}. Install it manually: ${MANUAL_INSTALL_POINTER}`);
+    }
+    rmQuiet(tmpFile);
+    rmQuiet(tmpExtractDir);
+}
+export async function ensureCloudflared() {
+    const onpath = onPath();
+    if (onpath)
+        return onpath;
+    const binName = cloudflaredBinName(process.platform);
+    const dest = path.join(BIN_DIR, binName);
+    if (fs.existsSync(dest))
+        return dest;
+    fs.mkdirSync(BIN_DIR, { recursive: true });
+    const url = cloudflaredDownloadUrl(process.platform, process.arch);
+    await downloadCloudflared(url, dest);
+    return dest;
+}

package/dist/cloudflared/tunnelProcess.d.ts

@@ -0,0 +1,21 @@
+export interface TunnelHandle {
+    publicUrl: string;
+    stop(): void;
+}
+export interface StartOptions {
+    timeoutMs?: number;
+    extraArgs?: string[];
+    attempts?: number;
+    intervalMs?: number;
+    healthCheck?: (url: string) => Promise<boolean>;
+    probeTimeoutMs?: number;
+}
+export declare function parsePublicUrl(line: string): string | null;
+export declare function defaultHealthCheck(url: string): Promise<boolean>;
+/**
+ * `extraArgs` exists for tests: it lets a fake binary (e.g. `node fake.mjs`) be
+ * launched in place of `cloudflared tunnel --url ...`. Production passes none.
+ * The URL is surfaced only after a health probe confirms the edge is reachable
+ * (cloudflared prints the hostname before routing is live).
+ */
+export declare function startCloudflared(binPath: string, localPort: number, opts?: StartOptions): Promise<TunnelHandle>;

package/dist/cloudflared/tunnelProcess.js

@@ -0,0 +1,120 @@
+import { spawn } from 'node:child_process';
+import { CLOUDFLARED_URL_TIMEOUT_MS, CLOUDFLARED_HEALTH_ATTEMPTS, CLOUDFLARED_HEALTH_INTERVAL_MS, } from '../config.js';
+const URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+// Bounds a single probe so a black-hole connection (or a caller-supplied
+// healthCheck that hangs/throws) can't stall the health-check loop forever.
+const DEFAULT_PROBE_TIMEOUT_MS = 5000;
+export function parsePublicUrl(line) {
+    const m = line.match(URL_RE);
+    return m ? m[0] : null;
+}
+// Any HTTP response (even 404/502/426) means the Cloudflare edge is routing to us.
+export async function defaultHealthCheck(url) {
+    try {
+        await fetch(url, { method: 'GET', signal: AbortSignal.timeout(DEFAULT_PROBE_TIMEOUT_MS) });
+        return true;
+    }
+    catch {
+        return false; // network/DNS error/timeout → edge not ready yet
+    }
+}
+// Races a single health-check attempt against a per-attempt timeout so that a
+// caller-supplied `check` that throws, rejects, or simply never resolves can
+// never leave the loop (and therefore the outer startCloudflared promise)
+// hanging. Any failure mode here just counts as "not healthy yet".
+function probeOnce(url, check, probeTimeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (ok) => {
+            if (!settled) {
+                settled = true;
+                resolve(ok);
+            }
+        };
+        const timer = setTimeout(() => finish(false), probeTimeoutMs);
+        Promise.resolve()
+            .then(() => check(url))
+            .then((ok) => {
+            clearTimeout(timer);
+            finish(ok);
+        })
+            .catch(() => {
+            clearTimeout(timer);
+            finish(false);
+        });
+    });
+}
+async function waitHealthy(url, attempts, intervalMs, check, probeTimeoutMs) {
+    for (let i = 0; i < attempts; i++) {
+        if (await probeOnce(url, check, probeTimeoutMs))
+            return true;
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+    return false;
+}
+/**
+ * `extraArgs` exists for tests: it lets a fake binary (e.g. `node fake.mjs`) be
+ * launched in place of `cloudflared tunnel --url ...`. Production passes none.
+ * The URL is surfaced only after a health probe confirms the edge is reachable
+ * (cloudflared prints the hostname before routing is live).
+ */
+export function startCloudflared(binPath, localPort, opts = {}) {
+    const args = opts.extraArgs ?? ['tunnel', '--url', `http://localhost:${localPort}`];
+    const timeoutMs = opts.timeoutMs ?? CLOUDFLARED_URL_TIMEOUT_MS;
+    const attempts = opts.attempts ?? CLOUDFLARED_HEALTH_ATTEMPTS;
+    const intervalMs = opts.intervalMs ?? CLOUDFLARED_HEALTH_INTERVAL_MS;
+    const check = opts.healthCheck ?? defaultHealthCheck;
+    const probeTimeoutMs = opts.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+        const child = spawn(binPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let settled = false;
+        const stop = () => {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                /* gone */
+            }
+        };
+        const fail = (err) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                stop();
+                reject(err);
+            }
+        };
+        const timer = setTimeout(() => fail(new Error('cloudflared did not report a URL in time')), timeoutMs);
+        const onData = (buf) => {
+            for (const line of buf.toString().split('\n')) {
+                const url = parsePublicUrl(line);
+                if (url && !settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    waitHealthy(url, attempts, intervalMs, check, probeTimeoutMs)
+                        .then((ok) => {
+                        if (ok)
+                            resolve({ publicUrl: url, stop });
+                        else {
+                            stop();
+                            reject(new Error('cloudflared tunnel never became reachable'));
+                        }
+                    })
+                        .catch((err) => {
+                        // Should be unreachable (waitHealthy/probeOnce never reject), but
+                        // this guarantees the child is never orphaned and the outer
+                        // promise always settles, even on a future bug or surprise throw.
+                        stop();
+                        const reason = err instanceof Error ? err.message : String(err);
+                        reject(new Error(`cloudflared health check failed unexpectedly: ${reason}`));
+                    });
+                    return;
+                }
+            }
+        };
+        child.stdout?.on('data', onData);
+        child.stderr?.on('data', onData);
+        child.on('error', (err) => fail(err));
+        child.on('exit', (code) => fail(new Error(`cloudflared exited (${code})`)));
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export declare const TUNNEL_HOME: string;
+export declare const BIN_DIR: string;
+export declare const SESSIONS_DIR: string;
+export declare const DEFAULT_LISTEN_TIMEOUT_MS = 60000;
+export declare const DEFAULT_IDLE_TEARDOWN_MS: number;
+export declare const CLOUDFLARED_URL_TIMEOUT_MS = 30000;
+export declare const CLOUDFLARED_HEALTH_ATTEMPTS = 10;
+export declare const CLOUDFLARED_HEALTH_INTERVAL_MS = 1000;
+export declare const OPEN_RETRY_ATTEMPTS = 3;

package/dist/config.js

@@ -0,0 +1,12 @@
+import os from 'node:os';
+import path from 'node:path';
+export const TUNNEL_HOME = path.join(os.homedir(), '.tunnel');
+export const BIN_DIR = path.join(TUNNEL_HOME, 'bin');
+export const SESSIONS_DIR = path.join(TUNNEL_HOME, 'sessions');
+export const DEFAULT_LISTEN_TIMEOUT_MS = 60_000;
+export const DEFAULT_IDLE_TEARDOWN_MS = 30 * 60_000;
+// cloudflared startup robustness
+export const CLOUDFLARED_URL_TIMEOUT_MS = 30_000; // wait for the URL line
+export const CLOUDFLARED_HEALTH_ATTEMPTS = 10; // edge-reachability probes
+export const CLOUDFLARED_HEALTH_INTERVAL_MS = 1_000; // delay between probes
+export const OPEN_RETRY_ATTEMPTS = 3; // re-spawn attempts in session.open