tunnel-mcp 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -11,6 +11,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Nothing yet.
 
+## [0.1.2] - 2026-07-01
+
+### Added
+
+- **`install-skill` command and automatic skill install.** `tunnel-mcp
+install-skill` copies the `tunnel-etiquette` skill into `~/.claude/skills`
+  (override with `--dir`/`$TUNNEL_SKILLS_DIR`, overwrite with `--force`), and a
+  global `npm install` now installs it best-effort via a postinstall script.
+  Set `TUNNEL_SKIP_SKILL_INSTALL=1` to opt out; the postinstall never fails an
+  install and is a no-op under `npx`, `--ignore-scripts`, and CI.
+- **`--help` and `--version` flags**, plus a one-line stderr startup banner, so
+  running the server by hand no longer looks like a silent hang. The server also
+  hints how to install the etiquette skill when it isn't present.
+- **`TUNNEL_SKIP_REACHABILITY_CHECK` escape hatch.** Opens a tunnel even when the
+  host can't reach `*.trycloudflare.com` itself — useful when only the guest's
+  network needs to reach the URL.
+
+### Fixed
+
+- The MCP server reported a hardcoded, stale version (`0.1.0`) in its handshake;
+  it now reports the real package version.
+- A failed cloudflared reachability probe surfaced a generic "never became
+  reachable" error. It now names the host and, when the failure is DNS
+  resolution, points at `*.trycloudflare.com` being blocked (a common
+  corporate/filtered-DNS cause) and mentions the escape hatch above.
+
+## [0.1.1] - 2026-07-01
+
+### Security
+
+- **Join links are now single-use and expiring.** A join link is consumed by
+  the first guest who successfully authenticates and can no longer be redeemed
+  afterward — even once that guest disconnects — and links expire on their own
+  after 10 minutes (`DEFAULT_JOIN_LINK_TTL_MS`). This bounds the damage from a
+  leaked link, which previously stayed valid for the whole session.
+  `tunnel_open` now returns `joinLinkExpiresInSec` so the host can tell the
+  human how long the link is good for.
+
 ## [0.1.0] - 2026-06-30
 
 ### Added
@@ -42,5 +80,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
+[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/zachlikefolio/tunnel-mcp/releases/tag/v0.1.0

package/README.md

@@ -4,7 +4,6 @@
 
 [![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,
@@ -51,13 +50,29 @@ npx tunnel-mcp
 Register it with Claude Code (both developers do this once):
 
 ```bash
-claude mcp add tunnel -- tunnel-mcp
+claude mcp add tunnel -- tunnel-mcp          # if globally installed
+# or, with no global install:
+claude mcp add tunnel -- npx -y 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).
+> `tunnel-mcp` is a stdio MCP server, not an interactive CLI. Launching it by
+> hand just waits silently for a client — that's expected. Run
+> `tunnel-mcp --help` for usage, or `tunnel-mcp --version`.
+
+The **tunnel-etiquette skill** teaches each agent how to behave inside a tunnel
+(treat the peer as untrusted input, and check with its human before acting on
+anything the peer says). Installing the package copies it into `~/.claude/skills/`
+automatically (best-effort). If install scripts are disabled
+(`npm install --ignore-scripts`), or you want it in a custom directory or force an
+update, run it explicitly:
+
+```bash
+npx tunnel-mcp install-skill                       # into ~/.claude/skills
+npx tunnel-mcp install-skill --dir <path> --force  # elsewhere / overwrite
+```
+
+Set `TUNNEL_SKILLS_DIR` to change the default target, or
+`TUNNEL_SKIP_SKILL_INSTALL=1` to opt out of the automatic copy.
 
 `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.
@@ -70,7 +85,9 @@ it isn't already on your `PATH` — there's nothing extra to install.
 
 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.
+secret**, since it contains the encryption key for the session. The link is
+**single-use and expires after ~10 minutes** (`tunnel_open` reports
+`joinLinkExpiresInSec`), so share it promptly.
 
 **Guest** — paste the link and ask Claude to join:
 
@@ -113,9 +130,12 @@ between two AI agents. Here's exactly what it does and does not protect:
 - **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.
+- **The join link is a single-use, expiring 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. It is consumed
+  by the first guest who joins (and can't be reused, even after they leave) and
+  expires on its own after ~10 minutes, so a leaked link has a short, bounded
+  window of exposure.
 - **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
@@ -142,7 +162,7 @@ vulnerability.
 
 ```bash
 npm ci                  # install dependencies
-npm test                # run the test suite (109 tests, TDD)
+npm test                # run the test suite (136 tests, TDD)
 npm run build           # compile TypeScript
 npm run lint            # eslint
 npm run format:check    # prettier --check .
@@ -151,6 +171,23 @@ npm run test:coverage   # vitest run --coverage
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to propose changes.
 
+## Troubleshooting
+
+**`tunnel-mcp` / `npx tunnel-mcp` "does nothing".** It's a stdio MCP server, not
+an interactive CLI — with no arguments it starts and waits for an MCP client to
+connect over stdin/stdout. That's working as intended. Register it with a client
+(above), or run `tunnel-mcp --help`.
+
+**`tunnel_open` fails with "never became reachable" / can't resolve
+`*.trycloudflare.com`.** cloudflared reaches Cloudflare's edge over its own
+protocol, but the public `*.trycloudflare.com` hostname still has to resolve via
+normal DNS — and some networks (corporate/filtered networks, and a few public
+DNS resolvers) block `trycloudflare.com`. Both you **and your guest** need to be
+able to resolve it. Check with `dig +short <random>.trycloudflare.com` or
+`curl -sI https://<the-url>`. If only your guest's network needs to reach the
+URL, set `TUNNEL_SKIP_REACHABILITY_CHECK=1` to open the tunnel without the
+host-side reachability probe.
+
 ## Roadmap / not yet supported
 
 This is an MVP. The following are explicitly out of scope for now:
@@ -158,7 +195,7 @@ 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
+- Join-link rotation (re-issuing a fresh link mid-session; note that links are already single-use and expiring — see the security model above)
 - Encrypting the goal or other metadata
 
 ## License

package/SECURITY.md

@@ -63,9 +63,15 @@ share a join link with anyone.
   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.
+- **Join links are single-use and expiring.** A join link is consumed by the
+  first guest who successfully authenticates and can never be redeemed again —
+  even after that guest disconnects. Links also expire on their own (10 minutes
+  by default), so a link that is never used stops working. This bounds the
+  damage from a leaked link to a short window before it is used or expires.
 - **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.
+  a second concurrent join attempt is rejected ("tunnel full"), and any join
+  after the link has been consumed is rejected ("join link already used").
 - **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
@@ -89,13 +95,15 @@ protect against:
   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.
+- **A leaked link can still be redeemed within its window, before your guest
+  joins.** Join links are single-use and expire (10 minutes by default), so a
+  leaked link that is never used, has already been used, or has aged out can no
+  longer admit anyone. The residual risk is a race: if a link leaks and an
+  attacker redeems it faster than your intended guest — within the expiry
+  window and before that guest connects — the attacker consumes the single-use
+  link, joins as the guest, and locks out the real one. Share links only over
+  trusted channels, and open a fresh tunnel if you suspect a link was exposed
+  before it was used. There is no in-session key rotation.
 - **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.
@@ -113,9 +121,9 @@ protect against:
   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.
+  in-session key/link rotation, 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

package/dist/cli.d.ts

@@ -0,0 +1,21 @@
+export type ParsedArgs = {
+    mode: 'serve';
+} | {
+    mode: 'help';
+} | {
+    mode: 'version';
+} | {
+    mode: 'install-skill';
+    dir?: string;
+    force: boolean;
+} | {
+    mode: 'error';
+    message: string;
+};
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function helpText(version?: string): string;
+/** Runs the `install-skill` command. Returns a process exit code. */
+export declare function runInstallSkill(args: {
+    dir?: string;
+    force: boolean;
+}, out: (msg: string) => void): number;

package/dist/cli.js

@@ -0,0 +1,87 @@
+import { installSkill, readVersion } from './skillInstall.js';
+export function parseArgs(argv) {
+    if (argv.length === 0)
+        return { mode: 'serve' };
+    const [cmd, ...rest] = argv;
+    if (cmd === '--help' || cmd === '-h' || cmd === 'help')
+        return { mode: 'help' };
+    if (cmd === '--version' || cmd === '-v')
+        return { mode: 'version' };
+    if (cmd === 'install-skill') {
+        let dir;
+        let force = false;
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a === '--force' || a === '-f')
+                force = true;
+            else if (a === '--dir') {
+                const next = rest[++i];
+                // Guard against `--dir --force` (eats the flag) and a trailing `--dir`.
+                if (next === undefined || next.startsWith('-')) {
+                    return { mode: 'error', message: '--dir requires a path' };
+                }
+                dir = next;
+            }
+            else if (a.startsWith('--dir=')) {
+                dir = a.slice('--dir='.length);
+                if (dir === '')
+                    return { mode: 'error', message: '--dir requires a path' };
+            }
+            else
+                return { mode: 'error', message: `unknown option for install-skill: ${a}` };
+        }
+        return { mode: 'install-skill', dir, force };
+    }
+    return { mode: 'error', message: `unknown command: ${cmd}` };
+}
+export function helpText(version = readVersion()) {
+    return [
+        `tunnel-mcp v${version}`,
+        `An MCP server that lets two developers' Claude agents talk directly through an`,
+        `ephemeral, end-to-end-encrypted tunnel.`,
+        ``,
+        `This is a stdio MCP server, NOT an interactive CLI. With no arguments it starts`,
+        `the server and waits for an MCP client to connect over stdin/stdout, so running`,
+        `it by hand in a terminal will look like it "does nothing" — that's expected.`,
+        `You add it to an MCP client instead:`,
+        ``,
+        `  claude mcp add tunnel -- npx -y tunnel-mcp          # Claude Code (this project)`,
+        `  claude mcp add -s user tunnel -- npx -y tunnel-mcp  # ...available everywhere`,
+        ``,
+        `Commands:`,
+        `  (no args)        Start the MCP server on stdio (for an MCP client to launch)`,
+        `  install-skill    Install the tunnel-etiquette skill into your skills directory`,
+        `  --help, -h       Show this help and exit`,
+        `  --version, -v    Print the version and exit`,
+        ``,
+        `install-skill options:`,
+        `  --dir <path>     Target skills directory (default: ~/.claude/skills or`,
+        `                   $TUNNEL_SKILLS_DIR)`,
+        `  --force, -f      Overwrite an existing install`,
+        ``,
+        `Environment:`,
+        `  TUNNEL_SKILLS_DIR                 Override the skills directory`,
+        `  TUNNEL_SKIP_SKILL_INSTALL=1       Skip the automatic skill install on npm install`,
+        `  TUNNEL_SKIP_REACHABILITY_CHECK=1  Open a tunnel even if this machine can't reach`,
+        `                                    *.trycloudflare.com (your guest still must)`,
+        ``,
+        `Docs: https://github.com/zachlikefolio/tunnel-mcp`,
+    ].join('\n');
+}
+/** Runs the `install-skill` command. Returns a process exit code. */
+export function runInstallSkill(args, out) {
+    try {
+        const res = installSkill({ skillsDir: args.dir, overwrite: args.force });
+        if (res.installed) {
+            out(`Installed the tunnel-etiquette skill to ${res.target}${res.updated ? ' (overwrote the existing copy)' : ''}.`);
+        }
+        else {
+            out(`The tunnel-etiquette skill is already present at ${res.target}. Re-run with --force to overwrite it.`);
+        }
+        return 0;
+    }
+    catch (e) {
+        out(`Failed to install the skill: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}

package/dist/cloudflared/tunnelProcess.d.ts

@@ -9,9 +9,12 @@ export interface StartOptions {
     intervalMs?: number;
     healthCheck?: (url: string) => Promise<boolean>;
     probeTimeoutMs?: number;
+    skipHealthCheck?: boolean;
 }
 export declare function parsePublicUrl(line: string): string | null;
+export declare function describeProbeError(e: unknown): string;
 export declare function defaultHealthCheck(url: string): Promise<boolean>;
+export declare function unreachableMessage(url: string, attempts: number, lastReason?: string): string;
 /**
  * `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.

package/dist/cloudflared/tunnelProcess.js

@@ -8,49 +8,95 @@ 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.
+// undici (Node's global fetch) reports the real network error on `.cause`, e.g.
+// a DNS failure surfaces as `cause.code === 'ENOTFOUND'`. Pull that out so the
+// caller can tell "DNS can't resolve the host" apart from "edge not ready yet".
+export function describeProbeError(e) {
+    const err = e;
+    const code = err?.cause?.code;
+    if (code)
+        return err.cause?.message ? `${code}: ${err.cause.message}` : code;
+    if (err?.name === 'TimeoutError')
+        return 'probe timed out';
+    return err?.message || 'unknown error';
+}
+// Any HTTP response (even 404/502/426) means the Cloudflare edge is routing to
+// us. A thrown error carries why it failed (DNS, TLS, refused, timeout).
+async function reachabilityProbe(url, probeTimeoutMs) {
+    try {
+        await fetch(url, { method: 'GET', signal: AbortSignal.timeout(probeTimeoutMs) });
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, reason: describeProbeError(e) };
+    }
+}
+// Back-compat boolean probe (kept for external callers/tests).
 export async function defaultHealthCheck(url) {
+    return (await reachabilityProbe(url, DEFAULT_PROBE_TIMEOUT_MS)).ok;
+}
+// Builds the actionable "never became reachable" error. Names the host and,
+// when the failure looks like DNS resolution, points at *.trycloudflare.com
+// blocking — the single most common real-world cause. Always mentions the
+// escape hatch, since the guest's network (not the host's) is what must reach
+// the URL for messaging.
+export function unreachableMessage(url, attempts, lastReason) {
+    let host = url;
     try {
-        await fetch(url, { method: 'GET', signal: AbortSignal.timeout(DEFAULT_PROBE_TIMEOUT_MS) });
-        return true;
+        host = new URL(url).host;
     }
     catch {
-        return false; // network/DNS error/timeout → edge not ready yet
+        /* keep the raw url */
+    }
+    const dnsish = !!lastReason && /ENOTFOUND|EAI_AGAIN|getaddrinfo|\bdns\b/i.test(lastReason);
+    let msg = `cloudflared reported ${url} but it never became reachable from this machine after ${attempts} probe(s)`;
+    if (lastReason)
+        msg += ` (last error: ${lastReason})`;
+    msg += '.';
+    if (dnsish) {
+        msg +=
+            ` This machine can't resolve ${host} — your DNS or network may be blocking *.trycloudflare.com` +
+                ` (common on filtered/corporate networks and some public DNS resolvers). You and your guest both` +
+                ` need to be able to resolve it.`;
     }
+    msg += ` If you're confident your guest's network can reach the URL, set TUNNEL_SKIP_REACHABILITY_CHECK=1 to open the tunnel anyway.`;
+    return msg;
 }
-// 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) {
+// Races a single probe 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.
+function probeOnce(url, probe, probeTimeoutMs) {
     return new Promise((resolve) => {
         let settled = false;
-        const finish = (ok) => {
+        const finish = (r) => {
             if (!settled) {
                 settled = true;
-                resolve(ok);
+                resolve(r);
             }
         };
-        const timer = setTimeout(() => finish(false), probeTimeoutMs);
+        const timer = setTimeout(() => finish({ ok: false, reason: 'probe timed out' }), probeTimeoutMs);
         Promise.resolve()
-            .then(() => check(url))
-            .then((ok) => {
+            .then(() => probe(url))
+            .then((r) => {
             clearTimeout(timer);
-            finish(ok);
+            finish(r);
         })
-            .catch(() => {
+            .catch((err) => {
             clearTimeout(timer);
-            finish(false);
+            finish({ ok: false, reason: describeProbeError(err) });
         });
     });
 }
-async function waitHealthy(url, attempts, intervalMs, check, probeTimeoutMs) {
+async function waitHealthy(url, attempts, intervalMs, probe, probeTimeoutMs) {
+    let lastReason;
     for (let i = 0; i < attempts; i++) {
-        if (await probeOnce(url, check, probeTimeoutMs))
-            return true;
-        await new Promise((r) => setTimeout(r, intervalMs));
+        const r = await probeOnce(url, probe, probeTimeoutMs);
+        if (r.ok)
+            return r;
+        lastReason = r.reason;
+        await new Promise((res) => setTimeout(res, intervalMs));
     }
-    return false;
+    return { ok: false, reason: lastReason };
 }
 /**
  * `extraArgs` exists for tests: it lets a fake binary (e.g. `node fake.mjs`) be
@@ -63,8 +109,13 @@ export function startCloudflared(binPath, localPort, opts = {}) {
     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;
+    // A caller-supplied boolean healthCheck carries no failure reason; the default
+    // probe does. Adapt the former into a ProbeResult either way.
+    const custom = opts.healthCheck;
+    const probe = custom
+        ? async (u) => ({ ok: await custom(u) })
+        : (u) => reachabilityProbe(u, probeTimeoutMs);
     return new Promise((resolve, reject) => {
         const child = spawn(binPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
         let settled = false;
@@ -91,13 +142,20 @@ export function startCloudflared(binPath, localPort, opts = {}) {
                 if (url && !settled) {
                     settled = true;
                     clearTimeout(timer);
-                    waitHealthy(url, attempts, intervalMs, check, probeTimeoutMs)
-                        .then((ok) => {
-                        if (ok)
+                    // Escape hatch: the reachability probe runs on the *host*, but only the
+                    // guest's network must reach the URL for messaging. A host on a filtered
+                    // network can opt to skip the probe and hand out the link regardless.
+                    if (opts.skipHealthCheck) {
+                        resolve({ publicUrl: url, stop });
+                        return;
+                    }
+                    waitHealthy(url, attempts, intervalMs, probe, probeTimeoutMs)
+                        .then((res) => {
+                        if (res.ok)
                             resolve({ publicUrl: url, stop });
                         else {
                             stop();
-                            reject(new Error('cloudflared tunnel never became reachable'));
+                            reject(new Error(unreachableMessage(url, attempts, res.reason)));
                         }
                     })
                         .catch((err) => {

package/dist/config.d.ts

@@ -3,6 +3,7 @@ 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 DEFAULT_JOIN_LINK_TTL_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;

package/dist/config.js

@@ -5,6 +5,9 @@ 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;
+// Join links are single-use and expire after this window; a leaked link that
+// is never used (or is reused after the guest joined) can't admit anyone.
+export const DEFAULT_JOIN_LINK_TTL_MS = 10 * 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

package/dist/env.d.ts

@@ -0,0 +1,7 @@
+/**
+ * True only when an env var is set to a meaningfully "on" value. Unset, '', '0',
+ * 'false', 'no', and 'off' (any case, trimmed) all read as off — so `FOO=0`
+ * disables a flag instead of accidentally enabling it (a plain `process.env.FOO`
+ * truthiness check treats "0"/"false" as true).
+ */
+export declare function envFlag(name: string): boolean;

package/dist/env.js

@@ -0,0 +1,13 @@
+/**
+ * True only when an env var is set to a meaningfully "on" value. Unset, '', '0',
+ * 'false', 'no', and 'off' (any case, trimmed) all read as off — so `FOO=0`
+ * disables a flag instead of accidentally enabling it (a plain `process.env.FOO`
+ * truthiness check treats "0"/"false" as true).
+ */
+export function envFlag(name) {
+    const v = process.env[name];
+    if (v === undefined)
+        return false;
+    const s = v.trim().toLowerCase();
+    return s !== '' && s !== '0' && s !== 'false' && s !== 'no' && s !== 'off';
+}

package/dist/index.js

@@ -3,35 +3,71 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { TunnelSession } from './session.js';
 import { registerTools, defaultDisplayName } from './tools.js';
-const session = new TunnelSession();
-const server = new McpServer({ name: 'tunnel', version: '0.1.0' });
-registerTools(server, session, { displayName: defaultDisplayName() });
-let closing = false;
-async function teardown() {
-    if (closing)
-        return;
-    closing = true;
-    try {
-        await session.close('process exit');
+import { parseArgs, helpText, runInstallSkill } from './cli.js';
+import { readVersion, isSkillInstalled } from './skillInstall.js';
+// Write a one-shot command's output, then exit only once it has flushed — a bare
+// write()+exit() can truncate output piped to another process.
+function writeThenExit(stream, text, code) {
+    stream.write(text.endsWith('\n') ? text : text + '\n', () => process.exit(code));
+}
+async function main() {
+    const version = readVersion();
+    const parsed = parseArgs(process.argv.slice(2));
+    // One-shot commands print and exit without ever opening the JSON-RPC channel.
+    if (parsed.mode === 'help')
+        return writeThenExit(process.stdout, helpText(version), 0);
+    if (parsed.mode === 'version')
+        return writeThenExit(process.stdout, version, 0);
+    if (parsed.mode === 'error') {
+        return writeThenExit(process.stderr, `tunnel-mcp: ${parsed.message}\n\n${helpText(version)}`, 2);
+    }
+    if (parsed.mode === 'install-skill') {
+        const lines = [];
+        const code = runInstallSkill({ dir: parsed.dir, force: parsed.force }, (m) => lines.push(m));
+        // Success → stdout; failure → stderr.
+        return writeThenExit(code === 0 ? process.stdout : process.stderr, lines.join('\n'), code);
+    }
+    // Serve. stdout is reserved for the JSON-RPC transport, so all human-facing
+    // output goes to stderr (MCP clients capture it into their logs).
+    const session = new TunnelSession();
+    const server = new McpServer({ name: 'tunnel', version });
+    registerTools(server, session, { displayName: defaultDisplayName() });
+    let closing = false;
+    async function teardown() {
+        if (closing)
+            return;
+        closing = true;
+        try {
+            await session.close('process exit');
+        }
+        catch {
+            /* best effort */
+        }
+        process.exit(0);
     }
-    catch {
-        /* best effort */
+    process.on('SIGINT', teardown);
+    process.on('SIGTERM', teardown);
+    const transport = new StdioServerTransport();
+    // The host holds an HTTP/WS listener + a cloudflared child, so the event loop
+    // never drains and `beforeExit` would never fire. Drive teardown off the stdio
+    // pipe closing instead, which is how an MCP client actually ends the server.
+    transport.onclose = () => {
+        void teardown();
+    };
+    process.stdin.on('end', () => {
+        void teardown();
+    });
+    process.stdin.on('close', () => {
+        void teardown();
+    });
+    // Startup banner so a human who runs this by hand isn't staring at a silent,
+    // seemingly-hung process (this is a server, not an interactive CLI).
+    process.stderr.write(`tunnel-mcp v${version} ready on stdio — this is an MCP server, not an interactive CLI. ` +
+        `Add it to an MCP client (run \`tunnel-mcp --help\`).\n`);
+    if (!isSkillInstalled()) {
+        process.stderr.write(`tip: run \`npx tunnel-mcp install-skill\` to install the tunnel-etiquette skill ` +
+            `(teaches agents to treat the peer as untrusted input).\n`);
     }
-    process.exit(0);
+    await server.connect(transport);
 }
-process.on('SIGINT', teardown);
-process.on('SIGTERM', teardown);
-const transport = new StdioServerTransport();
-// The host holds an HTTP/WS listener + a cloudflared child, so the event loop
-// never drains and `beforeExit` would never fire. Drive teardown off the stdio
-// pipe closing instead, which is how an MCP client actually ends the server.
-transport.onclose = () => {
-    void teardown();
-};
-process.stdin.on('end', () => {
-    void teardown();
-});
-process.stdin.on('close', () => {
-    void teardown();
-});
-await server.connect(transport);
+void main();

package/dist/relay/hostRelay.d.ts

@@ -8,6 +8,7 @@ export interface HostRelayOptions {
     goal: string;
     hostName: string;
     idleMs?: number;
+    joinTtlMs?: number;
 }
 export declare class HostRelay extends EventEmitter {
     private opts;
@@ -19,9 +20,12 @@ export declare class HostRelay extends EventEmitter {
     private challenges;
     private idleTimer?;
     private tearingDown;
+    private consumed;
+    private joinDeadline;
     constructor(opts: HostRelayOptions, log: SessionLog);
     start(): Promise<number>;
     get peerConnected(): boolean;
+    armJoinDeadline(ttlMs?: number): void;
     submitLocal(msg: WireMessage): WireMessage;
     private resetIdle;
     private submit;

package/dist/relay/hostRelay.js

@@ -3,7 +3,7 @@ import { EventEmitter } from 'node:events';
 import { WebSocketServer, WebSocket } from 'ws';
 import { makeChallenge, verifyChallenge } from '../protocol/crypto.js';
 import { encodeFrame, decodeFrame, buildSystem, } from '../protocol/messages.js';
-import { DEFAULT_IDLE_TEARDOWN_MS } from '../config.js';
+import { DEFAULT_IDLE_TEARDOWN_MS, DEFAULT_JOIN_LINK_TTL_MS } from '../config.js';
 export class HostRelay extends EventEmitter {
     opts;
     log;
@@ -14,10 +14,16 @@ export class HostRelay extends EventEmitter {
     challenges = new WeakMap();
     idleTimer;
     tearingDown = false;
+    // Single-use, expiring join link: the link is valid until `joinDeadline`, and
+    // is consumed by the first successful authentication so it can never be reused
+    // (even after that guest disconnects).
+    consumed = false;
+    joinDeadline;
     constructor(opts, log) {
         super();
         this.opts = opts;
         this.log = log;
+        this.joinDeadline = Date.now() + (opts.joinTtlMs ?? DEFAULT_JOIN_LINK_TTL_MS);
         this.server = http.createServer();
         this.wss = new WebSocketServer({ server: this.server, path: `/t/${opts.tunnelId}` });
         this.wss.on('connection', (ws) => this.onConnection(ws));
@@ -39,6 +45,13 @@ export class HostRelay extends EventEmitter {
     get peerConnected() {
         return !!this.guest && this.guest.readyState === WebSocket.OPEN;
     }
+    // (Re)start the single-use join link's expiry window. The session calls this
+    // once the link is actually minted (after cloudflared provisioning), so the
+    // window is measured from when the host receives the link to share — not from
+    // relay construction, which happens before provisioning could burn time.
+    armJoinDeadline(ttlMs) {
+        this.joinDeadline = Date.now() + (ttlMs ?? this.opts.joinTtlMs ?? DEFAULT_JOIN_LINK_TTL_MS);
+    }
     submitLocal(msg) {
         return this.submit(msg);
     }
@@ -95,11 +108,24 @@ export class HostRelay extends EventEmitter {
                         ws.close();
                         return;
                     }
-                    if (this.guest && this.guest !== ws && this.guest.readyState === WebSocket.OPEN) {
-                        ws.send(encodeFrame({ t: 'auth_fail', reason: 'tunnel full' }));
+                    if (Date.now() > this.joinDeadline) {
+                        ws.send(encodeFrame({ t: 'auth_fail', reason: 'join link expired' }));
+                        ws.close();
+                        return;
+                    }
+                    if (this.consumed) {
+                        // The single-use link was already redeemed. Distinguish the case
+                        // where the original guest is still connected ('tunnel full') from a
+                        // reuse attempt after they left ('join link already used').
+                        const connected = !!this.guest && this.guest.readyState === WebSocket.OPEN;
+                        ws.send(encodeFrame({
+                            t: 'auth_fail',
+                            reason: connected ? 'tunnel full' : 'join link already used',
+                        }));
                         ws.close();
                         return;
                     }
+                    this.consumed = true;
                     this.guest = ws;
                     this.guestName = frame.name;
                     const sinceSeq = Number.isFinite(frame.sinceSeq) ? frame.sinceSeq : 0;

package/dist/session.d.ts

@@ -4,6 +4,7 @@ export interface SessionDeps {
     ensureCloudflared: () => Promise<string>;
     startCloudflared: (bin: string, port: number) => Promise<TunnelHandle>;
     idleMs?: number;
+    joinTtlMs?: number;
 }
 export interface SessionStatus {
     role: Role;
@@ -30,6 +31,7 @@ export declare class TunnelSession {
         tunnelId: string;
         joinLink: string;
         status: string;
+        joinLinkExpiresInSec: number;
     }>;
     join(joinLink: string, guestName: string): Promise<{
         tunnelId: string;

package/dist/session.js

@@ -6,10 +6,13 @@ import { HostRelay } from './relay/hostRelay.js';
 import { GuestClient } from './relay/guestClient.js';
 import { ensureCloudflared as realEnsure } from './cloudflared/provision.js';
 import { startCloudflared as realStart } from './cloudflared/tunnelProcess.js';
-import { DEFAULT_LISTEN_TIMEOUT_MS, DEFAULT_IDLE_TEARDOWN_MS, OPEN_RETRY_ATTEMPTS, } from './config.js';
+import { DEFAULT_LISTEN_TIMEOUT_MS, DEFAULT_IDLE_TEARDOWN_MS, DEFAULT_JOIN_LINK_TTL_MS, OPEN_RETRY_ATTEMPTS, } from './config.js';
+import { envFlag } from './env.js';
 const DEFAULT_DEPS = {
     ensureCloudflared: realEnsure,
-    startCloudflared: (bin, port) => realStart(bin, port),
+    // Read the escape hatch per-call (not at module load) so it can be set right
+    // before opening a tunnel.
+    startCloudflared: (bin, port) => realStart(bin, port, envFlag('TUNNEL_SKIP_REACHABILITY_CHECK') ? { skipHealthCheck: true } : {}),
 };
 export class TunnelSession {
     deps;
@@ -35,8 +38,9 @@ export class TunnelSession {
         const key = generateKey();
         const tunnelId = generateTunnelId();
         const idleMs = this.deps.idleMs ?? DEFAULT_IDLE_TEARDOWN_MS;
+        const joinTtlMs = this.deps.joinTtlMs ?? DEFAULT_JOIN_LINK_TTL_MS;
         const log = new SessionLog(tunnelId);
-        const relay = new HostRelay({ tunnelId, key, goal, hostName, idleMs }, log);
+        const relay = new HostRelay({ tunnelId, key, goal, hostName, idleMs, joinTtlMs }, log);
         const port = await relay.start();
         // Bounded retry: cloudflared may crash or never yield a URL; re-spawn before giving up.
         let tunnel;
@@ -56,6 +60,10 @@ export class TunnelSession {
             log.delete();
             throw new Error(`could not establish a cloudflared tunnel after ${OPEN_RETRY_ATTEMPTS} attempts: ${String(lastErr)}`);
         }
+        // Start the single-use link's expiry window now that the link exists —
+        // measured from mint time, not from relay construction (which happened
+        // before cloudflared provisioning could burn part of the window).
+        relay.armJoinDeadline();
         const joinLink = mintLink(tunnel.publicUrl, tunnelId, key);
         this.role = 'host';
         this.key = key;
@@ -71,7 +79,12 @@ export class TunnelSession {
             void this.close();
         });
         relay.submitLocal(buildSystem('host', `tunnel opened — goal: ${goal}`));
-        return { tunnelId, joinLink, status: 'waiting_for_guest' };
+        return {
+            tunnelId,
+            joinLink,
+            status: 'waiting_for_guest',
+            joinLinkExpiresInSec: Math.round(joinTtlMs / 1000),
+        };
     }
     async join(joinLink, guestName) {
         if (this.isOpen)

package/dist/skillInstall.d.ts

@@ -0,0 +1,23 @@
+export declare function bundledSkillDir(): string;
+export declare function readVersion(): string;
+export declare function defaultSkillsDir(): string;
+/** Precedence: explicit arg → $TUNNEL_SKILLS_DIR → ~/.claude/skills. */
+export declare function resolveSkillsDir(explicit?: string): string;
+export declare function isSkillInstalled(skillsDir?: string): boolean;
+export interface InstallResult {
+    installed: boolean;
+    updated: boolean;
+    target: string;
+    source: string;
+}
+export declare function installSkill(opts?: {
+    skillsDir?: string;
+    overwrite?: boolean;
+}): InstallResult;
+/**
+ * Called from the postinstall script. Best-effort by contract: it must never
+ * throw (a failed skill copy must not fail `npm install`), it only installs
+ * when absent (never clobbers a user's copy on reinstall), and it bows out
+ * under CI or when the user opts out.
+ */
+export declare function installSkillBestEffort(log?: (msg: string) => void): void;

package/dist/skillInstall.js

@@ -0,0 +1,69 @@
+import { cpSync, existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { envFlag } from './env.js';
+const SKILL_NAME = 'tunnel-etiquette';
+// dist/skillInstall.js → package root is one level up. During tests (tsx runs
+// src/skillInstall.ts) this resolves to the repo root, which has the same
+// `skill/` and `package.json` layout as the published package.
+function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+export function bundledSkillDir() {
+    return path.join(packageRoot(), 'skill', SKILL_NAME);
+}
+export function readVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(packageRoot(), 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export function defaultSkillsDir() {
+    return path.join(os.homedir(), '.claude', 'skills');
+}
+/** Precedence: explicit arg → $TUNNEL_SKILLS_DIR → ~/.claude/skills. */
+export function resolveSkillsDir(explicit) {
+    return explicit || process.env.TUNNEL_SKILLS_DIR || defaultSkillsDir();
+}
+function targetDir(skillsDir) {
+    return path.join(skillsDir, SKILL_NAME);
+}
+export function isSkillInstalled(skillsDir = resolveSkillsDir()) {
+    return existsSync(path.join(targetDir(skillsDir), 'SKILL.md'));
+}
+export function installSkill(opts = {}) {
+    const source = bundledSkillDir();
+    if (!existsSync(path.join(source, 'SKILL.md'))) {
+        throw new Error(`bundled tunnel-etiquette skill not found at ${source}`);
+    }
+    const skillsDir = resolveSkillsDir(opts.skillsDir);
+    const target = targetDir(skillsDir);
+    const existed = existsSync(path.join(target, 'SKILL.md'));
+    if (existed && !opts.overwrite) {
+        return { installed: false, updated: false, target, source };
+    }
+    cpSync(source, target, { recursive: true });
+    return { installed: true, updated: existed, target, source };
+}
+/**
+ * Called from the postinstall script. Best-effort by contract: it must never
+ * throw (a failed skill copy must not fail `npm install`), it only installs
+ * when absent (never clobbers a user's copy on reinstall), and it bows out
+ * under CI or when the user opts out.
+ */
+export function installSkillBestEffort(log = () => { }) {
+    if (envFlag('TUNNEL_SKIP_SKILL_INSTALL') || envFlag('CI'))
+        return;
+    try {
+        const res = installSkill({ overwrite: false });
+        if (res.installed)
+            log(`tunnel-mcp: installed the tunnel-etiquette skill to ${res.target}`);
+    }
+    catch {
+        /* never break an install */
+    }
+}

package/dist/tools.js

@@ -28,7 +28,7 @@ function register(server, name, schema, cb) {
 }
 export function registerTools(server, session, opts) {
     register(server, 'tunnel_open', {
-        description: 'Open a tunnel as host and get a join link to share.',
+        description: 'Open a tunnel as host and get a join link to share. The link is a secret — share it over a trusted channel. It is single-use (works for exactly one guest) and expires (see joinLinkExpiresInSec in the result), so tell the human to share it promptly.',
         inputSchema: { goal: z.string() },
     }, async ({ goal }) => ok(await session.open(goal, opts.displayName)));
     register(server, 'tunnel_join', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnel-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Let two developers' Claude agents talk directly through an ephemeral, end-to-end-encrypted tunnel.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "skill",
+    "postinstall.mjs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
@@ -28,6 +29,8 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "dev": "tsx src/index.ts",
+    "e2e": "tsx scripts/e2e-two-agents.ts",
+    "postinstall": "node postinstall.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -62,6 +65,7 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.109.0",
     "@types/node": "^20.14.0",
     "@types/ws": "^8.5.10",
     "@vitest/coverage-v8": "^2.0.0",

package/postinstall.mjs

@@ -0,0 +1,13 @@
+// Best-effort: install the tunnel-etiquette skill into ~/.claude/skills when the
+// package is installed. This MUST never fail an install and is deliberately a
+// no-op in the cases where it can't or shouldn't run:
+//   - `npm install --ignore-scripts` (and hosts that disable scripts) skip it
+//   - CI, or TUNNEL_SKIP_SKILL_INSTALL=1, opt out (see installSkillBestEffort)
+//   - a dev checkout before `npm run build` has no dist/ yet → import throws → ignored
+// It IS idempotent, so running again (e.g. npx populating its cache) is harmless.
+try {
+  const { installSkillBestEffort } = await import('./dist/skillInstall.js');
+  installSkillBestEffort((m) => console.error(m));
+} catch {
+  /* dist not built yet, or any other error — never break the install */
+}