tunnel-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+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');
+    }
+    catch {
+        /* best effort */
+    }
+    process.exit(0);
+}
+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);

package/dist/log/sessionLog.d.ts

@@ -0,0 +1,14 @@
+import { WireMessage } from '../protocol/messages.js';
+export declare class SessionLog {
+    private msgs;
+    private seqCounter;
+    private filePath;
+    private closed;
+    constructor(tunnelId: string);
+    append(msg: WireMessage): WireMessage;
+    record(finalized: WireMessage): void;
+    since(sinceSeq: number): WireMessage[];
+    all(): WireMessage[];
+    get lastSeq(): number;
+    delete(): void;
+}

package/dist/log/sessionLog.js

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { SESSIONS_DIR } from '../config.js';
+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.
+    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;
+    }
+    record(finalized) {
+        if (this.closed)
+            return;
+        this.msgs.push(finalized);
+        this.seqCounter = Math.max(this.seqCounter, finalized.seq);
+    }
+    since(sinceSeq) {
+        return this.msgs.filter((m) => m.seq > sinceSeq);
+    }
+    all() {
+        return [...this.msgs];
+    }
+    get lastSeq() {
+        return this.seqCounter;
+    }
+    delete() {
+        try {
+            fs.rmSync(this.filePath);
+        }
+        catch {
+            /* already gone */
+        }
+        this.msgs = [];
+        this.closed = true;
+    }
+}

package/dist/protocol/crypto.d.ts

@@ -0,0 +1,9 @@
+export type Key = Uint8Array;
+export declare function generateKey(): Key;
+export declare function keyToBase64url(key: Key): string;
+export declare function keyFromBase64url(s: string): Key;
+export declare function seal(plaintext: string, key: Key): string;
+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;

package/dist/protocol/crypto.js

@@ -0,0 +1,39 @@
+import nacl from 'tweetnacl';
+import crypto from 'node:crypto';
+export function generateKey() {
+    return nacl.randomBytes(nacl.secretbox.keyLength);
+}
+export function keyToBase64url(key) {
+    return Buffer.from(key).toString('base64url');
+}
+export function keyFromBase64url(s) {
+    const b = Buffer.from(s, 'base64url');
+    if (b.length !== nacl.secretbox.keyLength)
+        throw new Error('invalid key length');
+    return new Uint8Array(b);
+}
+export function seal(plaintext, key) {
+    const nonce = nacl.randomBytes(nacl.secretbox.nonceLength);
+    const box = nacl.secretbox(Buffer.from(plaintext, 'utf8'), nonce, key);
+    return Buffer.concat([Buffer.from(nonce), Buffer.from(box)]).toString('base64url');
+}
+export function open(sealed, key) {
+    const data = Buffer.from(sealed, 'base64url');
+    const nonce = new Uint8Array(data.subarray(0, nacl.secretbox.nonceLength));
+    const box = new Uint8Array(data.subarray(nacl.secretbox.nonceLength));
+    const plain = nacl.secretbox.open(box, nonce, key);
+    if (!plain)
+        throw new Error('decryption failed');
+    return Buffer.from(plain).toString('utf8');
+}
+export function makeChallenge() {
+    return crypto.randomBytes(32).toString('base64url');
+}
+export function respondChallenge(challenge, key) {
+    return crypto.createHmac('sha256', Buffer.from(key)).update(challenge).digest('base64url');
+}
+export function verifyChallenge(challenge, response, key) {
+    const expected = Buffer.from(respondChallenge(challenge, key));
+    const got = Buffer.from(response);
+    return expected.length === got.length && crypto.timingSafeEqual(expected, got);
+}

package/dist/protocol/link.d.ts

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

package/dist/protocol/link.js

@@ -0,0 +1,21 @@
+import crypto from 'node:crypto';
+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 parseLink(link) {
+    const hashIdx = link.indexOf('#');
+    if (hashIdx < 0)
+        throw new Error('link missing key fragment');
+    const urlPart = link.slice(0, hashIdx);
+    const keyPart = link.slice(hashIdx + 1);
+    const u = new URL(urlPart);
+    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 };
+}

package/dist/protocol/messages.d.ts

@@ -0,0 +1,48 @@
+import { Key } from './crypto.js';
+export type MessageKind = 'chat' | 'system' | 'presence';
+export type Role = 'host' | 'guest';
+export interface WireMessage {
+    id: string;
+    seq: number;
+    from: Role;
+    kind: MessageKind;
+    body: string;
+    ts: number;
+}
+export interface PlainMessage {
+    id: string;
+    seq: number;
+    from: Role;
+    kind: MessageKind;
+    text: string;
+    ts: number;
+}
+export declare function newId(): string;
+export declare function buildChat(from: Role, text: string, key: Key): WireMessage;
+export declare function buildSystem(from: Role, text: string): WireMessage;
+export declare function decrypt(msg: WireMessage, key: Key): PlainMessage;
+export type ControlFrame = {
+    t: 'challenge';
+    nonce: string;
+} | {
+    t: 'auth';
+    response: string;
+    name: string;
+    sinceSeq: number;
+} | {
+    t: 'auth_ok';
+    goal: string;
+    peerName: string;
+    backlog: WireMessage[];
+} | {
+    t: 'auth_fail';
+    reason: string;
+} | {
+    t: 'msg';
+    msg: WireMessage;
+} | {
+    t: 'send';
+    msg: WireMessage;
+};
+export declare function encodeFrame(frame: ControlFrame): string;
+export declare function decodeFrame(data: string): ControlFrame;

package/dist/protocol/messages.js

@@ -0,0 +1,35 @@
+import crypto from 'node:crypto';
+import { seal, open } from './crypto.js';
+export function newId() {
+    return crypto.randomBytes(8).toString('hex');
+}
+export function buildChat(from, text, key) {
+    return { id: newId(), seq: -1, from, kind: 'chat', body: seal(text, key), ts: 0 };
+}
+export function buildSystem(from, text) {
+    return { id: newId(), seq: -1, from, kind: 'system', body: text, ts: 0 };
+}
+// decrypt() must be TOTAL: a malformed/forged peer chat body must never
+// throw here, or one bad message poisons every listen() batch that includes
+// it (the untrusted guest could otherwise deny the host's receive loop).
+export function decrypt(msg, key) {
+    let text;
+    if (msg.kind === 'chat') {
+        try {
+            text = open(msg.body, key);
+        }
+        catch {
+            text = '[unreadable]';
+        }
+    }
+    else {
+        text = msg.body;
+    }
+    return { id: msg.id, seq: msg.seq, from: msg.from, kind: msg.kind, text, ts: msg.ts };
+}
+export function encodeFrame(frame) {
+    return JSON.stringify(frame);
+}
+export function decodeFrame(data) {
+    return JSON.parse(data);
+}

package/dist/relay/guestClient.d.ts

@@ -0,0 +1,20 @@
+import { EventEmitter } from 'node:events';
+import { JoinLink } from '../protocol/link.js';
+import { SessionLog } from '../log/sessionLog.js';
+import { WireMessage } from '../protocol/messages.js';
+export declare class GuestClient extends EventEmitter {
+    private link;
+    private guestName;
+    private log;
+    private ws?;
+    private pending;
+    constructor(link: JoinLink, guestName: string, log: SessionLog);
+    connect(sinceSeq?: number): Promise<{
+        goal: string;
+        peerName: string;
+    }>;
+    private failPending;
+    say(msg: WireMessage): Promise<number>;
+    get connected(): boolean;
+    close(): void;
+}

package/dist/relay/guestClient.js

@@ -0,0 +1,98 @@
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+import { respondChallenge } from '../protocol/crypto.js';
+import { encodeFrame, decodeFrame } from '../protocol/messages.js';
+import { DEFAULT_LISTEN_TIMEOUT_MS } from '../config.js';
+export class GuestClient extends EventEmitter {
+    link;
+    guestName;
+    log;
+    ws;
+    pending = new Map();
+    constructor(link, guestName, log) {
+        super();
+        this.link = link;
+        this.guestName = guestName;
+        this.log = log;
+    }
+    connect(sinceSeq = 0) {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(this.link.wsUrl);
+            this.ws = ws;
+            ws.on('message', (data) => {
+                let frame;
+                try {
+                    frame = decodeFrame(data.toString());
+                }
+                catch {
+                    return;
+                }
+                if (frame.t === 'challenge') {
+                    ws.send(encodeFrame({
+                        t: 'auth',
+                        response: respondChallenge(frame.nonce, this.link.key),
+                        name: this.guestName,
+                        sinceSeq,
+                    }));
+                }
+                else if (frame.t === 'auth_ok') {
+                    for (const m of frame.backlog)
+                        this.log.record(m);
+                    resolve({ goal: frame.goal, peerName: frame.peerName });
+                }
+                else if (frame.t === 'auth_fail') {
+                    reject(new Error(`auth failed: ${frame.reason}`));
+                    ws.close();
+                }
+                else if (frame.t === 'msg') {
+                    this.log.record(frame.msg);
+                    const waiter = this.pending.get(frame.msg.id);
+                    if (waiter) {
+                        this.pending.delete(frame.msg.id);
+                        waiter.resolve(frame.msg.seq);
+                    }
+                    this.emit('message', frame.msg);
+                }
+            });
+            ws.on('close', () => this.failPending(new Error('tunnel disconnected')));
+            ws.on('error', (err) => {
+                reject(err);
+                this.failPending(err);
+            });
+        });
+    }
+    // Reject every in-flight say() so a lost echo surfaces as an error, never a hang.
+    failPending(err) {
+        for (const [, p] of this.pending)
+            p.reject(err);
+        this.pending.clear();
+    }
+    say(msg) {
+        return new Promise((resolve, reject) => {
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+                return reject(new Error('not connected'));
+            const timer = setTimeout(() => {
+                if (this.pending.delete(msg.id))
+                    reject(new Error('timed out waiting for host ack'));
+            }, DEFAULT_LISTEN_TIMEOUT_MS);
+            this.pending.set(msg.id, {
+                resolve: (seq) => {
+                    clearTimeout(timer);
+                    resolve(seq);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            this.ws.send(encodeFrame({ t: 'send', msg }));
+        });
+    }
+    get connected() {
+        return !!this.ws && this.ws.readyState === WebSocket.OPEN;
+    }
+    close() {
+        this.failPending(new Error('closed'));
+        this.ws?.close();
+    }
+}

package/dist/relay/hostRelay.d.ts

@@ -0,0 +1,31 @@
+import { EventEmitter } from 'node:events';
+import { Key } from '../protocol/crypto.js';
+import { SessionLog } from '../log/sessionLog.js';
+import { WireMessage } from '../protocol/messages.js';
+export interface HostRelayOptions {
+    tunnelId: string;
+    key: Key;
+    goal: string;
+    hostName: string;
+    idleMs?: number;
+}
+export declare class HostRelay extends EventEmitter {
+    private opts;
+    private log;
+    private server;
+    private wss;
+    private guest?;
+    private guestName?;
+    private challenges;
+    private idleTimer?;
+    private tearingDown;
+    constructor(opts: HostRelayOptions, log: SessionLog);
+    start(): Promise<number>;
+    get peerConnected(): boolean;
+    submitLocal(msg: WireMessage): WireMessage;
+    private resetIdle;
+    private submit;
+    private broadcast;
+    private onConnection;
+    close(): Promise<void>;
+}

package/dist/relay/hostRelay.js

@@ -0,0 +1,162 @@
+import http from 'node:http';
+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';
+export class HostRelay extends EventEmitter {
+    opts;
+    log;
+    server;
+    wss;
+    guest;
+    guestName;
+    challenges = new WeakMap();
+    idleTimer;
+    tearingDown = false;
+    constructor(opts, log) {
+        super();
+        this.opts = opts;
+        this.log = log;
+        this.server = http.createServer();
+        this.wss = new WebSocketServer({ server: this.server, path: `/t/${opts.tunnelId}` });
+        this.wss.on('connection', (ws) => this.onConnection(ws));
+        // A routine socket-level error (e.g. ECONNRESET on a flaky tunnel hop)
+        // must never crash the host process.
+        this.wss.on('error', (err) => {
+            console.error('[tunnel] relay server error:', err);
+        });
+    }
+    start() {
+        return new Promise((resolve) => {
+            this.server.listen(0, '127.0.0.1', () => {
+                this.resetIdle();
+                const addr = this.server.address();
+                resolve(typeof addr === 'object' && addr ? addr.port : 0);
+            });
+        });
+    }
+    get peerConnected() {
+        return !!this.guest && this.guest.readyState === WebSocket.OPEN;
+    }
+    submitLocal(msg) {
+        return this.submit(msg);
+    }
+    // Third teardown trigger: no activity within idleMs → warn, then emit 'idle'.
+    resetIdle() {
+        if (this.tearingDown)
+            return;
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => {
+            this.tearingDown = true; // stop further reschedules from the warning's submit()
+            this.submit(buildSystem('host', 'idle timeout — closing tunnel'));
+            this.emit('idle');
+        }, this.opts.idleMs ?? DEFAULT_IDLE_TEARDOWN_MS);
+    }
+    submit(msg) {
+        this.resetIdle();
+        const finalized = this.log.append(msg);
+        this.broadcast({ t: 'msg', msg: finalized });
+        this.emit('message', finalized);
+        return finalized;
+    }
+    broadcast(frame) {
+        if (this.guest && this.guest.readyState === WebSocket.OPEN) {
+            this.guest.send(encodeFrame(frame));
+        }
+    }
+    onConnection(ws) {
+        const nonce = makeChallenge();
+        this.challenges.set(ws, nonce);
+        ws.send(encodeFrame({ t: 'challenge', nonce }));
+        ws.on('message', (data) => {
+            // A malformed or schema-invalid frame must never crash the process.
+            // decodeFrame is a blind `as ControlFrame` cast (no runtime
+            // validation), so anything downstream that assumes a field's shape
+            // must be defensively checked here, inside the try/catch.
+            try {
+                let frame;
+                try {
+                    frame = decodeFrame(data.toString());
+                }
+                catch {
+                    return;
+                }
+                if (frame.t === 'auth') {
+                    if (typeof frame.response !== 'string' || typeof frame.name !== 'string') {
+                        ws.send(encodeFrame({ t: 'auth_fail', reason: 'malformed auth' }));
+                        ws.close();
+                        return;
+                    }
+                    const challenge = this.challenges.get(ws);
+                    if (!challenge || !verifyChallenge(challenge, frame.response, this.opts.key)) {
+                        ws.send(encodeFrame({ t: 'auth_fail', reason: 'bad key' }));
+                        ws.close();
+                        return;
+                    }
+                    if (this.guest && this.guest !== ws && this.guest.readyState === WebSocket.OPEN) {
+                        ws.send(encodeFrame({ t: 'auth_fail', reason: 'tunnel full' }));
+                        ws.close();
+                        return;
+                    }
+                    this.guest = ws;
+                    this.guestName = frame.name;
+                    const sinceSeq = Number.isFinite(frame.sinceSeq) ? frame.sinceSeq : 0;
+                    ws.send(encodeFrame({
+                        t: 'auth_ok',
+                        goal: this.opts.goal,
+                        peerName: this.opts.hostName,
+                        backlog: this.log.since(sinceSeq),
+                    }));
+                    this.submit(buildSystem('host', `${frame.name} joined`));
+                }
+                else if (frame.t === 'send') {
+                    if (ws !== this.guest)
+                        return; // only the authenticated guest may send
+                    const msg = frame.msg;
+                    if (!msg ||
+                        typeof msg !== 'object' ||
+                        typeof msg.id !== 'string' ||
+                        typeof msg.body !== 'string' ||
+                        msg.kind !== 'chat' // a guest may only originate chat; system/presence are host-only events
+                    ) {
+                        return; // ignore malformed or forged send frames
+                    }
+                    this.submit({ ...msg, from: 'guest', seq: -1, ts: 0 });
+                }
+            }
+            catch (err) {
+                // Never let a bad frame (or a downstream throw) crash the host
+                // process. stderr only — stdout is the MCP stdio channel.
+                console.error('[tunnel] relay frame error:', err);
+                return;
+            }
+        });
+        ws.on('close', () => {
+            if (ws === this.guest) {
+                this.guest = undefined;
+                // During teardown, close() has already terminated this socket and
+                // may have already deleted the session log; don't emit a "left"
+                // event (and don't let this late callback resurrect the log file —
+                // SessionLog.append() is itself a no-op once closed, belt-and-suspenders).
+                if (!this.tearingDown)
+                    this.submit(buildSystem('host', `${this.guestName ?? 'guest'} left`));
+            }
+        });
+        // A routine socket-level error must never crash the process.
+        ws.on('error', (err) => {
+            console.error('[tunnel] relay connection error:', err);
+        });
+    }
+    close() {
+        this.tearingDown = true;
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        return new Promise((resolve) => {
+            for (const c of this.wss.clients)
+                c.terminate();
+            this.wss.close(() => this.server.close(() => resolve()));
+        });
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,50 @@
+import { PlainMessage, Role } from './protocol/messages.js';
+import { TunnelHandle } from './cloudflared/tunnelProcess.js';
+export interface SessionDeps {
+    ensureCloudflared: () => Promise<string>;
+    startCloudflared: (bin: string, port: number) => Promise<TunnelHandle>;
+    idleMs?: number;
+}
+export interface SessionStatus {
+    role: Role;
+    peerConnected: boolean;
+    goal: string;
+    lastSeq: number;
+    openedAt: number;
+}
+export declare class TunnelSession {
+    private deps;
+    private role?;
+    private key?;
+    private tunnelId?;
+    private goal;
+    private openedAt;
+    private log?;
+    private source?;
+    private relay?;
+    private guest?;
+    private tunnel?;
+    constructor(deps?: SessionDeps);
+    get isOpen(): boolean;
+    open(goal: string, hostName: string): Promise<{
+        tunnelId: string;
+        joinLink: string;
+        status: string;
+    }>;
+    join(joinLink: string, guestName: string): Promise<{
+        tunnelId: string;
+        goal: string;
+        peer: string;
+    }>;
+    say(text: string): Promise<{
+        seq: number;
+    }>;
+    listen(sinceSeq: number, timeoutMs?: number): Promise<{
+        messages: PlainMessage[];
+        status: SessionStatus;
+    }>;
+    status(): SessionStatus;
+    close(summary?: string): Promise<{
+        ok: true;
+    }>;
+}