tunnel-mcp 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -11,6 +11,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Nothing yet.
 
+## [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

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,
@@ -70,7 +69,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 +114,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

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/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/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,7 +6,7 @@ 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';
 const DEFAULT_DEPS = {
     ensureCloudflared: realEnsure,
     startCloudflared: (bin, port) => realStart(bin, port),
@@ -35,8 +35,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 +57,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 +76,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/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.1",
   "description": "Let two developers' Claude agents talk directly through an ephemeral, end-to-end-encrypted tunnel.",
   "type": "module",
   "bin": {
@@ -28,6 +28,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "dev": "tsx src/index.ts",
+    "e2e": "tsx scripts/e2e-two-agents.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -62,6 +63,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",