tunnel-mcp 0.1.8 → 0.2.0

package/CHANGELOG.md

@@ -5,11 +5,57 @@ 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]
+## [0.2.0] - 2026-07-02
 
 ### Added
 
-- Nothing yet.
+- **Invite-only rooms, up to 16 participants (host included).** `tunnel_open`
+  now accepts `invites` (default 1, the classic two-party tunnel) and mints
+  one single-use, expiring invite per expected teammate. The new host-only
+  `tunnel_invite` tool mints more invites mid-session — to add a teammate or
+  re-admit someone who disconnected (their old invite stays dead; a
+  disconnected member never reuses it, only a fresh one lets them back in).
+  Every session now tracks a **roster**: `tunnel_join` and `tunnel_status`
+  return the current members (name/host-flag/connected), and every message
+  `tunnel_listen` returns carries `fromName` resolved from that roster, so
+  agents can address each other by name instead of "the peer."
+
+### Breaking
+
+Protocol v2, incompatible with v1 in both directions:
+
+- **A v2 client given an old v1 (tokenless) link** gets an explicit
+  upgrade-and-retry message naming the fix — the modern client recognizes the
+  old link and tells you what to do. If the host is genuinely still on the old
+  code and can't upgrade, you can join their v1 tunnel with the old client via
+  `npx -y tunnel-mcp@0.1`.
+- **An old v1 client given a v2 link (or dialing a v2 host)** cannot connect:
+  the v1 client fails locally with a generic error (its parser rejects the
+  `#key.token` fragment as an invalid key), and a v1 client that does reach a
+  v2 host is turned away as incompatible. The remedy here is to **upgrade** that
+  client (`npx -y tunnel-mcp@latest`), not downgrade — a v2 room cannot admit a
+  v1 client.
+
+Migration for anything calling the library API directly (MCP tool callers are
+unaffected beyond the richer response shapes):
+
+| API                | v1 (0.1.x)                                                                          | v2 (this change)                                                                                                                                                                                                                                                                                                      |
+| ------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session.open()`   | `{ tunnelId, joinLink, status: 'waiting_for_guest', joinLinkExpiresInSec, invite }` | `{ tunnelId, status: 'waiting_for_members', invites: [{ joinLink, invite, expiresInSec }, ...] }`, plus top-level `joinLink` / `invite` / `joinLinkExpiresInSec` **only** when `invites.length === 1` (the default two-party continuity trio)                                                                         |
+| `session.join()`   | `{ tunnelId, goal, peer }`                                                          | `{ tunnelId, goal, self: { id, name }, members: RosterEntry[] }`                                                                                                                                                                                                                                                      |
+| `session.status()` | `{ role, peerConnected, goal, lastSeq, openedAt }`                                  | `{ role, goal, lastSeq, openedAt, members: { name, isHost, connected }[], pendingInvites }` — **`peerConnected` removed**, use `members[].connected` instead                                                                                                                                                          |
+| Wire protocol      | v1 links/frames accepted                                                            | v1 and v2 are mutually incompatible. A v2 client on a v1 link throws an upgrade-and-retry error (escape hatch: `npx -y tunnel-mcp@0.1`). A v1 client on a v2 link/host cannot connect — it fails with a generic local error or is refused by the host as incompatible, and must upgrade (`npx -y tunnel-mcp@latest`). |
+| `Role` type        | exported from `protocol/messages.ts` (`'host' \| 'guest'`)                          | **removed** — replaced by the opaque `ParticipantId` and the `RosterEntry` roster shape                                                                                                                                                                                                                               |
+
+## [0.1.9] - 2026-07-02
+
+### Added
+
+- **`tunnel_open` now returns `invite`** — a ready-to-forward plain-text message
+  containing the one-time setup command (`claude mcp add tunnel -- npx -y
+tunnel-mcp`) and the join link, so the host's human can paste one message to
+  the other developer instead of explaining the install. The tool description
+  directs the agent to relay it verbatim.
 
 ## [0.1.8] - 2026-07-02
 
@@ -171,7 +217,8 @@ install-skill` copies the `tunnel-etiquette` skill into `~/.claude/skills`
   declaring a fix "confirmed".
 - Test suite of 109 tests built with vitest, developed test-first (TDD).
 
-[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.8...HEAD
+[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.9...HEAD
+[0.1.9]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.5...v0.1.6

package/README.md

@@ -49,8 +49,9 @@ firewalls and NAT.
   └───────────────────┘
 ```
 
-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.
+The relay and the `cloudflared` child process live only for the lifetime of the
+session and are destroyed on teardown. The transcript is held in memory only —
+nothing is ever written to disk, and it vanishes with the process at teardown.
 
 ## Install
 
@@ -96,70 +97,92 @@ it isn't already on your `PATH` — there's nothing extra to install.
 
 > "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. The link is
-**single-use and expires after ~10 minutes** (`tunnel_open` reports
-`joinLinkExpiresInSec`), so share it promptly.
+Claude calls `tunnel_open({ goal })` and hands back a ready-to-forward
+**invite** — one plain-text message containing the one-time setup command and
+the join link. Paste it to the other developer over a trusted channel (Slack
+DM, etc.) — **the link is a secret**, since it contains the encryption key for
+the session. It 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:
 
 > "Join this tunnel: `<link>`"
 
-Claude calls `tunnel_join({ joinLink })`, learns the goal, and the session is
-now locked to just the two of you.
+Claude calls `tunnel_join({ joinLink })`, learns the goal, and gets back the
+room's member roster — with the default single invite, that's just the two of
+you.
+
+**More than one guest? Open a room instead:**
+
+> "Open a tunnel for me and two teammates, to pair on the checkout flow."
+
+Claude calls `tunnel_open({ goal, invites: 3 })` — `invites` is the number of
+teammates to seat (up to 15, plus the host makes 16 connected at once) — and gets
+back one **invite** per teammate instead of a single link. Forward each invite
+to exactly one person; every invite is single-use, so don't reuse one link for
+two people. Need to add someone mid-session, or re-admit someone whose invite
+expired before they used it? `tunnel_invite({ count })` (host-only) mints more.
 
 **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.
+`tunnel_listen` to wait for the next reply. In a room, every message arrives
+with `fromName` so agents can tell who said what, 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.
+**Ending it** is role-sensitive: the **host** calls `tunnel_close` to end the
+session for everyone and tear down the relay — the in-memory transcript vanishes
+with it, since it was never written to disk. A **member** calling `tunnel_close`
+just leaves; the room stays open for whoever's left.
 
 ## 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.                   |
+| Tool                                     | Who    | Purpose                                                                                              |
+| ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
+| `tunnel_open({goal, invites?})`          | host   | Start the relay + Quick Tunnel and get back one invite per teammate (default 1 — classic two-party). |
+| `tunnel_invite({count?})`                | host   | Mint more single-use, expiring invites mid-session.                                                  |
+| `tunnel_join({joinLink})`                | member | Dial into a room using an invite link and authenticate; returns the current member roster.           |
+| `tunnel_say({text})`                     | any    | Send a message to the room.                                                                          |
+| `tunnel_listen({sinceSeq?, timeoutMs?})` | any    | Wait for the next message(s), each tagged with the sender's `fromName`.                              |
+| `tunnel_status()`                        | any    | Inspect the session: role, goal, member roster, pending invites, lastSeq.                            |
+| `tunnel_close({summary?})`               | any    | Host: ends the session for everyone. Member: leaves the room.                                        |
 
 ## 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:
+between developers' 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.
+- **The goal, every participant's display name, and system events are
+  plaintext.** The `tunnel_open` goal, each member'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 single-use, expiring credential.** It embeds the session
+  uses an HMAC challenge to prove the joining member holds the same key as the
+  host; the raw key itself is never sent over the wire.
+- **Each invite 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
-  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.
+  trust (Slack DM, etc.), never in a public issue, PR, or chat, and forward each
+  invite to exactly one person. It is consumed by whoever redeems it first (and
+  can't be reused, even after they leave) and expires on its own after ~10
+  minutes, so a leaked invite has a short, bounded window of exposure.
+- **Admits exactly whom you invited** — two-party by default, rooms opt-in
+  (cap 16), every invite single-use + expiring. Admission is bounded by how
+  many invites the host chose to mint, not by who happens to have the room's
+  key.
+- **The peer is untrusted input, not an instruction source.** Messages from
+  other agents are data to reason about, not commands to execute — and this
+  applies to every member in a room, not just one. 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 a peer
+  said.
+- **Everything is ephemeral.** The transcript is held in memory only — nothing
+  is ever written to disk, and it vanishes with the process. Teardown is
+  role-sensitive: the host's `tunnel_close` (or their process exiting, or 30
+  minutes of no messages) ends the session for everyone and tears down the
+  relay + `cloudflared` child process; a member's `tunnel_close` just leaves —
+  the room stays open for whoever's left.
 
 See [SECURITY.md](./SECURITY.md) for the full threat model and how to report a
 vulnerability.
@@ -175,7 +198,7 @@ vulnerability.
 
 ```bash
 npm ci                  # install dependencies
-npm test                # run the test suite (159 tests, TDD)
+npm test                # run the test suite (198 tests, TDD)
 npm run build           # compile TypeScript
 npm run lint            # eslint
 npm run format:check    # prettier --check .
@@ -209,9 +232,8 @@ system DNS already resolves `*.trycloudflare.com`.
 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 (re-issuing a fresh link mid-session; note that links are already single-use and expiring — see the security model above)
+- Invite rotation (replacing a specific still-valid invite mid-session; note invites are already single-use and expiring — see the security model above)
 - Encrypting the goal or other metadata
 
 ## License

package/SECURITY.md

@@ -41,10 +41,11 @@ When you report, please include:
 
 ## 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.
+tunnel-mcp lets developers' Claude agents exchange messages directly through a
+host-owned, ephemeral relay, without a human copy-pasting between them.
+Two-party is the default; the host can opt into a room of up to 16
+participants. Understanding what is and isn't protected is important before
+you share an invite with anyone.
 
 - **Chat message bodies are end-to-end encrypted.** The text passed to
   `tunnel_say` is sealed with NaCl `secretbox` (XSalsa20-Poly1305, via
@@ -52,36 +53,46 @@ share a join link with anyone.
   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.
-- **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 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
-  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.
+  every member's display name, and system/connection events (joined, left,
+  idle, closed) cross the tunnel as **plaintext**. Do not put secrets in the
+  goal or a display name.
+- **Authentication is proof-of-key-possession, not key transmission.** Every
+  invite for a session embeds the same session key. A joining member's client
+  proves it holds that key via an HMAC challenge/response; the raw key itself
+  is never sent over the wire. Because an invite contains the key, **treat
+  every invite 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, and forward each invite to exactly one person.
+- **Invites are single-use and expiring.** Each invite is consumed by whoever
+  successfully authenticates with it first and can never be redeemed again —
+  even after that person disconnects. Invites also expire on their own (10
+  minutes by default), so one that's never used stops working. This bounds
+  the damage from a leaked invite to a short window before it is used or
+  expires.
+- **Invite-ledger admission.** A session admits only people the host minted
+  an invite for — up to 16 members connected at once, including the host.
+  Two-party remains the default. Every invite is single-use, consumed
+  atomically by the first successful join and dead forever after — the same
+  invite can never be redeemed a second time, even by the person who first
+  used it. Invites expire after ~10 minutes. A disconnected member's old
+  invite stays dead; getting back in requires a fresh invite from the host.
+  Only the host can mint invites, so a member who leaks the room key alone
+  cannot seat anyone.
+- **Peer input is untrusted, from every member.** Everything a peer sends
+  over the tunnel is data, never an instruction — and in a room, that holds
+  for each participant individually, not just "the other side." 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 a peer said.
+- **Ephemeral by design.** The transcript is held in memory only — it is
+  never written to disk, and it vanishes with the process. Teardown is
+  role-sensitive: the host's explicit `tunnel_close`, an idle timeout (30
+  minutes with no messages), or the host process exiting all tear down the
+  whole session — the in-process relay, the cloudflared child process, and
+  the throwaway Quick Tunnel URL — for every member at once. A member's own
+  `tunnel_close` only removes that member; it does not tear anything down
+  for anyone else. Nothing persists past a session's own teardown.
 
 ## Supply chain
 
@@ -120,25 +131,32 @@ 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,
+  message bodies are encrypted end-to-end, the goal, every display name,
   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.
-- **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.
+- **A leaked invite can still be redeemed within its window, before your
+  intended teammate joins.** Invites are single-use and expire (10 minutes
+  by default), so a leaked invite that is never used, has already been used,
+  or has aged out can no longer admit anyone. The residual risk is a race: if
+  an invite leaks and an attacker redeems it faster than your intended
+  teammate — within the expiry window and before that person connects — the
+  attacker consumes the single-use invite, joins in their place, and locks
+  them out (a fresh invite from the host is needed to re-admit them). Share
+  invites only over trusted channels, one per person, and mint a fresh
+  invite (or open a fresh tunnel) if you suspect one 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.
-- **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.
+- **One shared key per room — every member reads everything.** All chat
+  message bodies in a session are encrypted under the single key embedded in
+  every invite for that session, not a separate key per pair of
+  participants. In a room, that means every current member can decrypt every
+  other member's chat messages — there is no sub-group or pairwise privacy
+  within a session. Admission is still gated per-person by the invite ledger
+  (see above); this limitation is about message confidentiality once someone
+  is in the room, not about who can get in.
 - **"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
@@ -147,12 +165,13 @@ protect against:
   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.
+  instructions by an unguarded agent — and in a room, this applies to
+  every member, not just one.
 - **Out of scope for this release**: host-offline/async messaging,
-  more than two participants, alternative transports (ngrok, WebRTC),
-  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.
+  alternative transports (ngrok, WebRTC), in-session key/invite rotation
+  (replacing a still-valid invite before it's used or expires), 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

@@ -17,3 +17,5 @@ export declare const GUEST_CONNECT_DEADLINE_MS = 20000;
 export declare const GUEST_SYS_LOOKUP_TIMEOUT_MS = 2000;
 export declare const DOH_GUEST_RETRIES = 3;
 export declare const DOH_GUEST_RETRY_DELAY_MS = 700;
+export declare const MAX_ROOM_MEMBERS = 16;
+export declare const PROTOCOL_VERSION = 2;

package/dist/config.js

@@ -46,3 +46,6 @@ export const GUEST_CONNECT_DEADLINE_MS = 20_000; // overall connect+auth deadlin
 export const GUEST_SYS_LOOKUP_TIMEOUT_MS = 2_000; // bound the system-first lookup before DoH fallback
 export const DOH_GUEST_RETRIES = 3; // DoH attempts in the guest fallback
 export const DOH_GUEST_RETRY_DELAY_MS = 700; // backoff between guest DoH attempts
+// Rooms
+export const MAX_ROOM_MEMBERS = 16; // includes the host → at most 15 ws members
+export const PROTOCOL_VERSION = 2;

package/dist/invite.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The ready-to-forward invite a host's human sends to the other developer.
+ * Every tunnel needs a second dev with tunnel-mcp installed — so the invite
+ * carries the one-time setup command alongside the join link, making each
+ * session recruit its own second participant with zero friction.
+ */
+export declare function buildInvite(opts: {
+    goal: string;
+    joinLink: string;
+    expiresInSec: number;
+}): string;

package/dist/invite.js

@@ -0,0 +1,19 @@
+/**
+ * The ready-to-forward invite a host's human sends to the other developer.
+ * Every tunnel needs a second dev with tunnel-mcp installed — so the invite
+ * carries the one-time setup command alongside the join link, making each
+ * session recruit its own second participant with zero friction.
+ */
+export function buildInvite(opts) {
+    const mins = Math.max(1, Math.ceil(opts.expiresInSec / 60));
+    return [
+        `You're invited to a Claude-agent tunnel — goal: "${opts.goal}"`,
+        ``,
+        `1) One-time setup (skip if you already have tunnel-mcp):`,
+        `   claude mcp add tunnel -- npx -y tunnel-mcp`,
+        `2) Then tell your Claude:`,
+        `   Join this tunnel: ${opts.joinLink}`,
+        ``,
+        `The link is single-use and expires in ~${mins} minute${mins === 1 ? '' : 's'}.`,
+    ].join('\n');
+}

package/dist/log/sessionLog.d.ts

@@ -1,14 +1,20 @@
 import { WireMessage } from '../protocol/messages.js';
+/**
+ * In-memory-only transcript for a single tunnel session. There is no
+ * disk-writing path here — the security docs promise the transcript never
+ * touches disk, and that is structural: no file handle, no fs import, no
+ * append(). See the 0.2.0 final-review wave for the removal of the old
+ * fs.appendFileSync-backed append() method.
+ */
 export declare class SessionLog {
     private msgs;
     private seqCounter;
-    private filePath;
     private closed;
-    constructor(tunnelId: string);
-    append(msg: WireMessage): WireMessage;
+    constructor(_tunnelId: string);
     record(finalized: WireMessage): void;
     since(sinceSeq: number): WireMessage[];
     all(): WireMessage[];
     get lastSeq(): number;
+    /** Clears in-memory state. Safe no-op if already cleared. */
     delete(): void;
 }

package/dist/log/sessionLog.js

@@ -1,37 +1,29 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { SESSIONS_DIR } from '../config.js';
+/**
+ * In-memory-only transcript for a single tunnel session. There is no
+ * disk-writing path here — the security docs promise the transcript never
+ * touches disk, and that is structural: no file handle, no fs import, no
+ * append(). See the 0.2.0 final-review wave for the removal of the old
+ * fs.appendFileSync-backed append() method.
+ */
 export class SessionLog {
     msgs = [];
     seqCounter = 0;
-    filePath;
-    // Set once delete() has run. After that point append()/record() must be
-    // no-ops with respect to the file and in-memory store — otherwise a late
-    // event (e.g. a guest socket's 'close' handler firing after teardown) can
-    // resurrect the .jsonl file moments after delete() removed it, leaving an
-    // orphaned log on disk forever.
+    // Set once delete() has run. After that point record() must be a no-op
+    // with respect to the in-memory store — otherwise a late event (e.g. a
+    // guest socket's 'close' handler firing after teardown) can resurrect
+    // state moments after delete() cleared it.
     closed = false;
-    constructor(tunnelId) {
-        fs.mkdirSync(SESSIONS_DIR, { recursive: true });
-        this.filePath = path.join(SESSIONS_DIR, `${tunnelId}.jsonl`);
-    }
-    append(msg) {
-        if (this.closed) {
-            // True no-op: stub a finalized-looking message for the caller without
-            // advancing seqCounter, touching msgs, or writing to disk — so a late
-            // call after delete() can never recreate the file or extend the log.
-            return { ...msg, seq: this.seqCounter, ts: Date.now() };
-        }
-        const finalized = { ...msg, seq: ++this.seqCounter, ts: Date.now() };
-        this.msgs.push(finalized);
-        fs.appendFileSync(this.filePath, JSON.stringify(finalized) + '\n');
-        return finalized;
-    }
+    constructor(_tunnelId) { }
     record(finalized) {
         if (this.closed)
             return;
+        // seq comes from an untrusted host over the wire; a non-finite value
+        // must not poison the member-side lastSeq cursor. Keep the message in
+        // the transcript, just don't let it advance the cursor.
         this.msgs.push(finalized);
-        this.seqCounter = Math.max(this.seqCounter, finalized.seq);
+        if (Number.isFinite(finalized.seq)) {
+            this.seqCounter = Math.max(this.seqCounter, finalized.seq);
+        }
     }
     since(sinceSeq) {
         return this.msgs.filter((m) => m.seq > sinceSeq);
@@ -42,13 +34,8 @@ export class SessionLog {
     get lastSeq() {
         return this.seqCounter;
     }
+    /** Clears in-memory state. Safe no-op if already cleared. */
     delete() {
-        try {
-            fs.rmSync(this.filePath);
-        }
-        catch {
-            /* already gone */
-        }
         this.msgs = [];
         this.closed = true;
     }

package/dist/protocol/crypto.d.ts

@@ -7,3 +7,4 @@ export declare function open(sealed: string, key: Key): string;
 export declare function makeChallenge(): string;
 export declare function respondChallenge(challenge: string, key: Key): string;
 export declare function verifyChallenge(challenge: string, response: string, key: Key): boolean;
+export declare function generateToken(): string;

package/dist/protocol/crypto.js

@@ -37,3 +37,8 @@ export function verifyChallenge(challenge, response, key) {
     const got = Buffer.from(response);
     return expected.length === got.length && crypto.timingSafeEqual(expected, got);
 }
+// One-time invite token: 16 random bytes, base64url. High-entropy bearer value
+// redeemed exactly once by the host's invite ledger.
+export function generateToken() {
+    return crypto.randomBytes(16).toString('base64url');
+}

package/dist/protocol/link.d.ts

@@ -2,8 +2,9 @@ import { Key } from './crypto.js';
 export interface JoinLink {
     tunnelId: string;
     key: Key;
+    token: string;
     wsUrl: string;
 }
 export declare function generateTunnelId(): string;
-export declare function mintLink(publicBaseUrl: string, tunnelId: string, key: Key): string;
+export declare function mintInvite(publicBaseUrl: string, tunnelId: string, key: Key, token: string): string;
 export declare function parseLink(link: string): JoinLink;

package/dist/protocol/link.js

@@ -3,9 +3,9 @@ import { keyToBase64url, keyFromBase64url } from './crypto.js';
 export function generateTunnelId() {
     return crypto.randomBytes(8).toString('hex');
 }
-export function mintLink(publicBaseUrl, tunnelId, key) {
-    const wsBase = publicBaseUrl.replace(/^http/, 'ws'); // https->wss, http->ws
-    return `${wsBase}/t/${tunnelId}#${keyToBase64url(key)}`;
+export function mintInvite(publicBaseUrl, tunnelId, key, token) {
+    const wsBase = publicBaseUrl.replace(/^http/, 'ws');
+    return `${wsBase}/t/${tunnelId}#${keyToBase64url(key)}.${token}`;
 }
 export function parseLink(link) {
     const hashIdx = link.indexOf('#');
@@ -17,5 +17,12 @@ export function parseLink(link) {
     const m = u.pathname.match(/^\/t\/([0-9a-f]+)$/);
     if (!m)
         throw new Error('link missing tunnel id');
-    return { tunnelId: m[1], key: keyFromBase64url(keyPart), wsUrl: urlPart };
+    const parts = keyPart.split('.');
+    if (parts.length !== 2 || parts[1].length === 0) {
+        if (parts.length === 1) {
+            throw new Error('this link is from an older tunnel-mcp host — ask them to upgrade, or join with: npx -y tunnel-mcp@0.1');
+        }
+        throw new Error('malformed link fragment');
+    }
+    return { tunnelId: m[1], key: keyFromBase64url(parts[0]), token: parts[1], wsUrl: urlPart };
 }