cli-tunnel 1.2.0-beta.1 → 1.2.0-beta.3

package/README.md

@@ -77,12 +77,55 @@ cli-tunnel copilot
 
 ## Security
 
-Tunnels are **private by default** — only the Microsoft/GitHub account that created the tunnel can connect. Auth is enforced at Microsoft's relay layer before traffic reaches your machine.
+cli-tunnel uses a layered security model:
 
-- No inbound ports opened
-- No anonymous access
-- No central server
-- TLS encryption via devtunnel relay
+**Network layer** — Microsoft Dev Tunnels are private by default. Only the Microsoft or GitHub account that created the tunnel can connect. TLS encryption is handled by Microsoft's relay infrastructure. No inbound ports are opened on your machine.
+
+**Session authentication** — Each session generates a unique token (cryptographic random UUID). All HTTP API and WebSocket connections require this token. The token is embedded in the URL you receive at startup — anyone without it cannot connect.
+
+**WebSocket auth** — cli-tunnel uses a ticket-based handshake: the browser exchanges the session token for a single-use, short-lived ticket (60 seconds) to establish the WebSocket connection. This avoids keeping the long-lived token in WebSocket upgrade logs.
+
+**Input validation** — Only structured JSON messages are accepted over WebSocket. Raw text is rejected and logged. Terminal resize commands are bounds-checked to prevent abuse.
+
+**Environment isolation** — The child process receives a filtered set of environment variables (an allowlist of ~40 safe variables like PATH, HOME, TERM). Sensitive variables and NODE_OPTIONS are excluded to prevent code injection.
+
+**Audit logging** — All remote keyboard input is logged to `~/.cli-tunnel/audit/` in JSONL format with timestamps and source addresses. Secrets are automatically redacted from audit entries.
+
+**Connection limits** — Maximum 5 concurrent WebSocket connections. Sessions expire after 24 hours.
+
+## Terminal Size Behavior
+
+cli-tunnel uses a single PTY (pseudo-terminal) shared between your local terminal and all remote viewers. When a phone or tablet connects, the PTY resizes to match the remote device's screen dimensions. This ensures the CLI app renders correctly on the device you're actively using to interact with it.
+
+Because the PTY can only have one size at a time, the local terminal on your machine will reflect the remote device's dimensions while it's connected. This is by design — cli-tunnel prioritizes the remote viewing experience since the primary use case is controlling your CLI from another device.
+
+**Tips for the best experience:**
+- Rotate your phone to landscape for a wider terminal
+- Use the key bar (↑↓←→ Tab Enter Esc Ctrl+C) at the bottom for navigation
+- If multiple devices connect, the last one to resize wins
+
+## FAQ
+
+**Can multiple devices connect to the same session?**
+Yes, up to 5 devices simultaneously. All viewers see the same terminal output in real time. Input from any device goes to the same CLI session.
+
+**What happens if my phone disconnects?**
+The CLI session keeps running on your machine. When you reconnect, you'll see live output from that point forward. Use `--replay` to enable history replay so reconnecting devices catch up on what they missed.
+
+**Does cli-tunnel work with any CLI app?**
+Yes. Any command that runs in a terminal works — copilot, vim, htop, python, ssh, k9s, node, and more. cli-tunnel doesn't interpret the command's output; it streams raw terminal bytes.
+
+**Is there a central server?**
+No. cli-tunnel runs entirely on your machine. Microsoft Dev Tunnels provides the relay infrastructure, but no third-party server sees your terminal content.
+
+**What about the anti-phishing page?**
+The first time you open a devtunnel URL, Microsoft shows an interstitial warning page. This is a devtunnel security feature — it confirms you trust the tunnel. You only see it once per tunnel.
+
+**Does the tool work without devtunnel?**
+Yes. Use `--local` to skip tunnel creation. The terminal is available at `http://127.0.0.1:<port>` on your local network only.
+
+**What's hub mode?**
+Run `cli-tunnel` with no command to start hub mode — a sessions dashboard that shows all active cli-tunnel sessions on your machine. Tap any online session to connect to it.
 
 ## How It's Built
 

package/dist/index.js

@@ -20,8 +20,15 @@ import crypto from 'node:crypto';
 import { execSync, execFileSync, spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import http from 'node:http';
+import readline from 'node:readline';
 import { WebSocketServer, WebSocket } from 'ws';
 import os from 'node:os';
+function askUser(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => { rl.close(); resolve(answer.trim().toLowerCase()); });
+    });
+}
 const BOLD = '\x1b[1m';
 const RESET = '\x1b[0m';
 const DIM = '\x1b[2m';
@@ -421,35 +428,83 @@ async function main() {
         }
         catch {
             console.log(`\n  ${YELLOW}⚠ devtunnel CLI not found!${RESET}\n`);
-            console.log(`  ${BOLD}To enable remote access, install Microsoft Dev Tunnels:${RESET}\n`);
+            let installCmd = '';
             if (process.platform === 'win32') {
-                console.log(`    ${GREEN}winget install Microsoft.devtunnel${RESET}`);
+                installCmd = 'winget install Microsoft.devtunnel';
             }
             else if (process.platform === 'darwin') {
-                console.log(`    ${GREEN}brew install --cask devtunnel${RESET}`);
+                installCmd = 'brew install --cask devtunnel';
             }
             else {
-                console.log(`    ${GREEN}curl -sL https://aka.ms/DevTunnelCliInstall | bash${RESET}`);
+                installCmd = 'curl -sL https://aka.ms/DevTunnelCliInstall | bash';
             }
-            console.log(`\n  Then authenticate once:\n`);
-            console.log(`    ${GREEN}devtunnel user login${RESET}\n`);
-            console.log(`  ${DIM}More info: https://aka.ms/devtunnels/doc${RESET}\n`);
-            console.log(`  ${DIM}Continuing without tunnel (local only)...${RESET}\n`);
-        }
-        // Check if logged in
-        if (devtunnelInstalled) {
-            try {
-                const userInfo = execFileSync('devtunnel', ['user', 'show'], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
-                if (userInfo.includes('not logged in') || userInfo.includes('No user')) {
-                    throw new Error('not logged in');
+            const answer = await askUser(`  Would you like to install it now? (${GREEN}${installCmd}${RESET}) [Y/n] `);
+            if (answer === '' || answer === 'y' || answer === 'yes') {
+                console.log(`\n  ${DIM}Installing devtunnel...${RESET}\n`);
+                try {
+                    const installParts = installCmd.split(' ');
+                    const installProc = spawn(installParts[0], installParts.slice(1), { stdio: 'inherit', shell: process.platform !== 'win32' && installCmd.includes('|') });
+                    await new Promise((resolve, reject) => {
+                        installProc.on('close', (code) => code === 0 ? resolve() : reject(new Error(`Install exited with code ${code}`)));
+                        installProc.on('error', reject);
+                    });
+                    // Refresh PATH — winget updates the registry but current process has stale PATH
+                    if (process.platform === 'win32') {
+                        try {
+                            const userPath = execFileSync('reg', ['query', 'HKCU\\Environment', '/v', 'Path'], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+                            const sysPath = execFileSync('reg', ['query', 'HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment', '/v', 'Path'], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+                            const extractPath = (out) => out.split('\n').find(l => l.includes('REG_'))?.split('REG_EXPAND_SZ')[1]?.trim() || out.split('\n').find(l => l.includes('REG_'))?.split('REG_SZ')[1]?.trim() || '';
+                            process.env.PATH = `${extractPath(userPath)};${extractPath(sysPath)}`;
+                        }
+                        catch { /* keep existing PATH */ }
+                    }
+                    // Verify installation
+                    execFileSync('devtunnel', ['--version'], { stdio: 'pipe' });
+                    console.log(`\n  ${GREEN}✓${RESET} devtunnel installed successfully!\n`);
+                    devtunnelInstalled = true;
+                }
+                catch (err) {
+                    console.log(`\n  ${YELLOW}⚠${RESET} Installation failed: ${err.message}`);
+                    console.log(`  ${DIM}You can install it manually: ${installCmd}${RESET}\n`);
+                    console.log(`  ${DIM}Continuing without tunnel (local only)...${RESET}\n`);
                 }
             }
-            catch {
-                console.log(`\n  ${YELLOW}⚠ devtunnel not authenticated!${RESET}\n`);
-                console.log(`  Run this once to log in:\n`);
-                console.log(`    ${GREEN}devtunnel user login${RESET}\n`);
+            else {
+                console.log(`\n  ${DIM}More info: https://aka.ms/devtunnels/doc${RESET}`);
                 console.log(`  ${DIM}Continuing without tunnel (local only)...${RESET}\n`);
-                devtunnelInstalled = false;
+            }
+            // If just installed, check login
+            if (devtunnelInstalled) {
+                try {
+                    const userInfo = execFileSync('devtunnel', ['user', 'show'], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+                    if (userInfo.includes('not logged in') || userInfo.includes('No user')) {
+                        throw new Error('not logged in');
+                    }
+                }
+                catch {
+                    console.log(`  ${YELLOW}⚠ devtunnel not authenticated.${RESET}\n`);
+                    const loginAnswer = await askUser(`  Would you like to log in now? [Y/n] `);
+                    if (loginAnswer === '' || loginAnswer === 'y' || loginAnswer === 'yes') {
+                        try {
+                            const loginProc = spawn('devtunnel', ['user', 'login'], { stdio: 'inherit' });
+                            await new Promise((resolve, reject) => {
+                                loginProc.on('close', (code) => code === 0 ? resolve() : reject(new Error(`Login exited with code ${code}`)));
+                                loginProc.on('error', reject);
+                            });
+                            console.log(`\n  ${GREEN}✓${RESET} Logged in successfully!\n`);
+                        }
+                        catch {
+                            console.log(`\n  ${YELLOW}⚠${RESET} Login failed. Run manually: ${GREEN}devtunnel user login${RESET}\n`);
+                            console.log(`  ${DIM}Continuing without tunnel (local only)...${RESET}\n`);
+                            devtunnelInstalled = false;
+                        }
+                    }
+                    else {
+                        console.log(`\n  ${DIM}Run this once to log in: ${GREEN}devtunnel user login${RESET}`);
+                        console.log(`  ${DIM}Continuing without tunnel (local only)...${RESET}\n`);
+                        devtunnelInstalled = false;
+                    }
+                }
             }
         }
         if (devtunnelInstalled) {
@@ -556,6 +611,46 @@ async function main() {
         cols, rows, cwd,
         env: safeEnv,
     });
+    // Detect CSPRNG crash (Node.js 23 + node-pty issue) and retry via cmd.exe wrapper
+    let ptyExitedEarly = false;
+    const earlyExitCheck = new Promise((resolve) => {
+        ptyProcess.onExit(({ exitCode }) => {
+            if (exitCode === 134 || exitCode === 3221226505) { // 134 = SIGABRT, 3221226505 = STATUS_BREAKPOINT
+                ptyExitedEarly = true;
+                resolve();
+            }
+        });
+        setTimeout(resolve, 2000); // Wait 2s — if still running, it's fine
+    });
+    await earlyExitCheck;
+    if (ptyExitedEarly && process.platform === 'win32') {
+        console.log(`  ${YELLOW}⚠${RESET} CSPRNG crash detected (Node.js + PTY issue), retrying via cmd.exe wrapper...\n`);
+        // Spawn through cmd.exe /c — this adds a shell layer that avoids the crash
+        const cmdLine = [resolvedCmd, ...commandArgs].map(a => a.includes(' ') ? `"${a}"` : a).join(' ');
+        ptyProcess = nodePty.spawn('cmd.exe', ['/c', cmdLine], {
+            name: 'xterm-256color',
+            cols, rows, cwd,
+            env: safeEnv,
+        });
+        // Check if cmd.exe wrapper also fails
+        let retryFailed = false;
+        const retryCheck = new Promise((resolve) => {
+            ptyProcess.onExit(({ exitCode }) => {
+                if (exitCode === 134 || exitCode === 3221226505) {
+                    retryFailed = true;
+                    resolve();
+                }
+            });
+            setTimeout(resolve, 2000);
+        });
+        await retryCheck;
+        if (retryFailed) {
+            const nodeVer = process.version;
+            console.log(`  ${YELLOW}⚠${RESET} The command crashed due to a known Node.js ${nodeVer} + PTY compatibility issue.`);
+            console.log(`  ${BOLD}Fix:${RESET} Install Node.js 22 LTS: ${GREEN}nvm install 22${RESET} or ${GREEN}winget install OpenJS.NodeJS.LTS${RESET}\n`);
+            process.exit(1);
+        }
+    }
     ptyProcess.onData((data) => {
         process.stdout.write(data);
         broadcast(data);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cli-tunnel",
-  "version": "1.2.0-beta.1",
-  "description": "Tunnel any CLI app to your phone - PTY + devtunnel + xterm.js",
+  "version": "1.2.0-beta.3",
+  "description": "Tunnel any CLI app to your phone — PTY + devtunnel + xterm.js",
   "type": "module",
   "main": "dist/index.js",
   "bin": {