termbeam 1.7.0 → 1.8.1

package/README.md

@@ -8,6 +8,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/termbeam.svg)](https://www.npmjs.com/package/termbeam)
 [![CI](https://github.com/dorlugasigal/TermBeam/actions/workflows/ci.yml/badge.svg)](https://github.com/dorlugasigal/TermBeam/actions/workflows/ci.yml)
 [![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/dorlugasigal/TermBeam/coverage-data/endpoint.json)](https://github.com/dorlugasigal/TermBeam/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/dorlugasigal/TermBeam/badge)](https://securityscorecards.dev/viewer/?uri=github.com/dorlugasigal/TermBeam)
 [![Node.js](https://img.shields.io/node/v/termbeam.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -46,6 +47,8 @@ termbeam
 
 Scan the QR code printed in your terminal, or open the URL on any device.
 
+> **First time?** Run `termbeam -i` for a guided setup wizard that walks you through password, port, and access mode.
+
 ### Secure by default
 
 TermBeam starts with a tunnel and auto-generated password out of the box — just run `termbeam` and scan the QR code.
@@ -55,6 +58,7 @@ termbeam                        # tunnel + auto-password (default)
 termbeam --password mysecret    # use a specific password
 termbeam --no-tunnel            # LAN-only (no tunnel)
 termbeam --no-password          # disable password protection
+termbeam -i                     # interactive setup wizard
 ```
 
 ## Remote Access
@@ -85,6 +89,7 @@ termbeam [shell] [args...]        # start with a specific shell (default: auto-d
 termbeam --port 8080              # custom port (default: 3456)
 termbeam --host 0.0.0.0           # allow LAN access (default: 127.0.0.1)
 termbeam --lan                    # shortcut for --host 0.0.0.0
+termbeam -i                       # interactive setup wizard
 termbeam service install          # interactive PM2 service setup wizard
 termbeam service uninstall        # stop & remove PM2 service
 termbeam service status           # show PM2 service status
@@ -105,6 +110,7 @@ termbeam service restart          # restart PM2 service
 | `--host <addr>`       | Bind address                                         | `127.0.0.1`    |
 | `--lan`               | Bind to all interfaces (LAN access)                  | Off            |
 | `--log-level <level>` | Log verbosity (error/warn/info/debug)                | `info`         |
+| `-i, --interactive`   | Interactive setup wizard (guided configuration)      | Off            |
 | `-h, --help`          | Show help                                            | —              |
 | `-v, --version`       | Show version                                         | —              |
 

package/bin/termbeam.js

@@ -10,18 +10,33 @@ if (subcommand === 'service') {
   });
 } else {
   const { createTermBeamServer } = require('../src/server.js');
-  const instance = createTermBeamServer();
+  const { parseArgs } = require('../src/cli');
+  const { runInteractiveSetup } = require('../src/interactive');
 
-  process.on('SIGINT', () => {
-    console.log('\n[termbeam] Shutting down...');
-    instance.shutdown();
-    setTimeout(() => process.exit(0), 500).unref();
-  });
-  process.on('SIGTERM', () => {
-    console.log('\n[termbeam] Shutting down...');
-    instance.shutdown();
-    setTimeout(() => process.exit(0), 500).unref();
-  });
+  async function main() {
+    const baseConfig = parseArgs();
+    let config;
+    if (baseConfig.interactive) {
+      config = await runInteractiveSetup(baseConfig);
+    }
+    const instance = createTermBeamServer(config ? { config } : undefined);
+
+    process.on('SIGINT', () => {
+      console.log('\n[termbeam] Shutting down...');
+      instance.shutdown();
+      setTimeout(() => process.exit(0), 500).unref();
+    });
+    process.on('SIGTERM', () => {
+      console.log('\n[termbeam] Shutting down...');
+      instance.shutdown();
+      setTimeout(() => process.exit(0), 500).unref();
+    });
+
+    instance.start();
+  }
 
-  instance.start();
+  main().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termbeam",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "Beam your terminal to any device — mobile-optimized web terminal with multi-session support",
   "main": "src/server.js",
   "bin": {
@@ -68,13 +68,17 @@
   "dependencies": {
     "cookie-parser": "^1.4.7",
     "express": "^5.2.1",
+    "express-rate-limit": "^8.2.1",
     "node-pty": "^1.1.0",
     "qrcode": "^1.5.4",
     "ws": "^8.19.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.3",
     "@playwright/test": "^1.58.2",
     "c8": "^11.0.0",
+    "eslint": "^10.0.2",
+    "eslint-plugin-security": "^4.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
     "prettier": "^3.8.1"

package/src/cli.js

@@ -31,6 +31,7 @@ Options:
   --host <addr>         Bind address (default: 127.0.0.1)
   --lan                 Bind to 0.0.0.0 (allow LAN access, default: localhost only)
   --log-level <level>   Set log verbosity: error, warn, info, debug (default: info)
+  -i, --interactive     Interactive setup wizard (guided configuration)
   -h, --help            Show this help
   -v, --version         Show version
 
@@ -47,6 +48,7 @@ Examples:
   termbeam --password secret        Start with specific password
   termbeam --persisted-tunnel       Stable tunnel URL across restarts
   termbeam /bin/bash                Use bash instead of default shell
+  termbeam --interactive               Guided setup wizard
   termbeam service install          Set up as background service (PM2)
 
 Environment:
@@ -241,6 +243,7 @@ function parseArgs() {
   let noTunnel = false;
   let persistedTunnel = false;
   let publicTunnel = false;
+  let interactive = false;
   let explicitPassword = !!password;
 
   const args = process.argv.slice(2);
@@ -281,6 +284,8 @@ function parseArgs() {
       host = '0.0.0.0';
     } else if (args[i] === '--host' && args[i + 1]) {
       host = args[++i];
+    } else if (args[i] === '--interactive' || (args[i] === '-i' && filteredArgs.length === 0)) {
+      interactive = true;
     } else if (args[i] === '--log-level' && args[i + 1]) {
       logLevel = args[++i];
     } else {
@@ -335,6 +340,7 @@ function parseArgs() {
     defaultShell,
     version,
     logLevel,
+    interactive,
   };
 }
 

package/src/interactive.js

@@ -0,0 +1,269 @@
+const crypto = require('crypto');
+const {
+  green,
+  yellow,
+  red,
+  cyan,
+  bold,
+  dim,
+  ask,
+  choose,
+  confirm,
+  createRL,
+} = require('./prompts');
+
+// ── Interactive Setup Wizard ─────────────────────────────────────────────────
+
+async function runInteractiveSetup(baseConfig) {
+  // Enter alternate screen buffer for a clean wizard (like vim/htop)
+  process.stdout.write('\x1b[?1049h');
+  const exitAltScreen = () => process.stdout.write('\x1b[?1049l');
+  process.on('exit', exitAltScreen);
+
+  const rl = createRL();
+
+  const steps = ['Password', 'Port', 'Access', 'Log level', 'Confirm'];
+  const decisions = [];
+
+  function showProgress(stepIndex) {
+    process.stdout.write('\x1b[2J\x1b[H');
+
+    console.log(bold('🚀 TermBeam Interactive Setup'));
+    console.log('');
+    const total = steps.length;
+    const filled = stepIndex + 1;
+    const bar = steps
+      .map((s, i) => {
+        if (i < stepIndex) return green('●');
+        if (i === stepIndex) return cyan('●');
+        return dim('○');
+      })
+      .join(dim(' ─ '));
+    console.log(`${dim(`Step ${filled}/${total}`)}  ${bar}  ${cyan(steps[stepIndex])}`);
+
+    if (decisions.length > 0) {
+      console.log('');
+      for (const { label, value } of decisions) {
+        console.log(`  ${dim(label + ':')} ${value}`);
+      }
+    }
+  }
+
+  // Build config from base
+  const config = {
+    port: baseConfig.port,
+    host: baseConfig.host,
+    password: baseConfig.password,
+    useTunnel: baseConfig.useTunnel,
+    persistedTunnel: baseConfig.persistedTunnel,
+    publicTunnel: baseConfig.publicTunnel,
+    shell: baseConfig.shell,
+    shellArgs: baseConfig.shellArgs,
+    cwd: baseConfig.cwd,
+    defaultShell: baseConfig.defaultShell,
+    version: baseConfig.version,
+    logLevel: baseConfig.logLevel,
+  };
+
+  // Step 1: Password
+  showProgress(0);
+  const pwChoice = await choose(rl, 'Password authentication:', [
+    {
+      label: 'Auto-generate',
+      hint: 'Random password, shown on screen and embedded in the QR code',
+    },
+    {
+      label: 'Custom password',
+      hint: 'You type a password to use for this session',
+    },
+    {
+      label: 'No password',
+      hint: '⚠ No authentication — anyone who can reach the server gets shell access',
+      warn: true,
+    },
+  ]);
+  let passwordMode = 'auto';
+  if (pwChoice.index === 0) {
+    config.password = crypto.randomBytes(16).toString('base64url');
+    process.stdout.write(dim(`  Generated password: ${config.password}`) + '\n');
+  } else if (pwChoice.index === 1) {
+    passwordMode = 'custom';
+    config.password = await ask(rl, 'Enter password:');
+    while (!config.password) {
+      console.log(red('  Password cannot be empty.'));
+      config.password = await ask(rl, 'Enter password:');
+    }
+  } else {
+    passwordMode = 'none';
+    config.password = null;
+  }
+  decisions.push({
+    label: 'Password',
+    value: config.password === null ? yellow('disabled') : '••••••••',
+  });
+
+  // Step 2: Port
+  showProgress(1);
+  const portStr = await ask(rl, 'Port:', String(config.port));
+  const portNum = parseInt(portStr, 10);
+  config.port = portNum >= 1 && portNum <= 65535 ? portNum : 3456;
+  decisions.push({ label: 'Port', value: String(config.port) });
+
+  // Step 3: Access mode
+  showProgress(2);
+  const accessChoice = await choose(rl, 'How will you connect to TermBeam?', [
+    {
+      label: 'DevTunnel (internet)',
+      hint: 'HTTPS tunnel — accessible from any network, secured with your Microsoft account',
+    },
+    {
+      label: 'LAN',
+      hint: 'Binds to 0.0.0.0 — accessible from devices on the same network',
+    },
+    {
+      label: 'Localhost only',
+      hint: 'Binds to 127.0.0.1 — only this machine can connect',
+    },
+  ]);
+
+  if (accessChoice.index === 0) {
+    // DevTunnel mode
+    config.host = '127.0.0.1';
+    config.useTunnel = true;
+
+    // Sub-question: tunnel persistence
+    showProgress(2);
+    const persistChoice = await choose(rl, 'Tunnel persistence:', [
+      {
+        label: 'Ephemeral',
+        hint: 'New URL each run, automatically deleted when TermBeam exits',
+      },
+      {
+        label: 'Persisted',
+        hint: 'Stable URL that survives restarts (expires after 30 days idle)',
+      },
+    ]);
+    config.persistedTunnel = persistChoice.index === 1;
+
+    // Sub-question: access level
+    showProgress(2);
+    const publicChoice = await choose(rl, 'Tunnel access:', [
+      {
+        label: 'Private (owner-only)',
+        hint: 'Only the Microsoft account that created the tunnel can access it',
+      },
+      {
+        label: 'Public',
+        hint: '🚨 No Microsoft login — anyone with the URL can reach your terminal',
+        danger: true,
+      },
+    ]);
+    config.publicTunnel = publicChoice.index === 1;
+
+    // Auto-generate password if public tunnel with no password
+    if (config.publicTunnel && !config.password) {
+      console.log(yellow('  ⚠ Public tunnels require password authentication.'));
+      config.password = crypto.randomBytes(16).toString('base64url');
+      process.stdout.write(dim(`  Auto-generated password: ${config.password}`) + '\n');
+      passwordMode = 'auto';
+      // Update the password decision
+      decisions[0] = { label: 'Password', value: '••••••••' };
+    }
+  } else if (accessChoice.index === 1) {
+    // LAN mode
+    config.host = '0.0.0.0';
+    config.useTunnel = false;
+    config.persistedTunnel = false;
+    config.publicTunnel = false;
+  } else {
+    // Localhost only
+    config.host = '127.0.0.1';
+    config.useTunnel = false;
+    config.persistedTunnel = false;
+    config.publicTunnel = false;
+  }
+
+  const accessLabel = !config.useTunnel
+    ? config.host === '0.0.0.0'
+      ? 'LAN (0.0.0.0)'
+      : 'Localhost only'
+    : config.publicTunnel
+      ? 'DevTunnel (public)'
+      : 'DevTunnel (private)';
+  decisions.push({ label: 'Access', value: accessLabel });
+
+  // Step 4: Log level
+  showProgress(3);
+  const logChoice = await choose(
+    rl,
+    'Log level:',
+    [
+      { label: 'info', hint: 'Logs startup, connections, sessions, and errors (default)' },
+      { label: 'debug', hint: 'Includes all info logs plus WebSocket frames and internal state' },
+      { label: 'warn', hint: 'Only logs warnings and errors' },
+      { label: 'error', hint: 'Only logs critical errors' },
+    ],
+    0,
+  );
+  config.logLevel = logChoice.value;
+  decisions.push({ label: 'Log level', value: config.logLevel });
+
+  // Step 5: Confirmation
+  showProgress(4);
+  console.log(bold('\n── Configuration Summary ──────────────────'));
+  console.log(
+    `  Password:      ${config.password === null ? yellow('disabled') : cyan('••••••••')}`,
+  );
+  console.log(`  Port:          ${cyan(String(config.port))}`);
+  console.log(
+    `  Host:          ${cyan(config.host === '0.0.0.0' ? '0.0.0.0 (LAN)' : config.host)}`,
+  );
+  console.log(`  Tunnel:        ${config.useTunnel ? cyan('enabled') : yellow('disabled')}`);
+  if (config.useTunnel) {
+    console.log(`  Persisted:     ${config.persistedTunnel ? cyan('yes') : dim('no')}`);
+    console.log(`  Public:        ${config.publicTunnel ? yellow('yes') : dim('no')}`);
+  }
+  console.log(`  Shell:         ${cyan(config.shell || 'default')}`);
+  console.log(`  Directory:     ${cyan(config.cwd)}`);
+  console.log(`  Log level:     ${cyan(config.logLevel)}`);
+  console.log(dim('─'.repeat(44)));
+
+  // Build the equivalent CLI command
+  const cmdParts = ['termbeam'];
+  if (passwordMode === 'none') {
+    cmdParts.push('--no-password');
+  } else if (passwordMode === 'custom') {
+    cmdParts.push('--password', '"<your-password>"');
+  }
+  // auto-generate is the default — no flag needed
+  if (config.port !== 3456) cmdParts.push('--port', String(config.port));
+  if (!config.useTunnel) {
+    cmdParts.push('--no-tunnel');
+    if (config.host === '0.0.0.0') cmdParts.push('--lan');
+  } else {
+    if (config.persistedTunnel) cmdParts.push('--persisted-tunnel');
+    if (config.publicTunnel) cmdParts.push('--public');
+  }
+  if (config.logLevel !== 'info') cmdParts.push('--log-level', config.logLevel);
+  const cliCommand = cmdParts.join(' ');
+
+  console.log('');
+  console.log(dim('  To reuse this configuration without the wizard:'));
+  console.log(`  ${cyan(cliCommand)}`);
+
+  const proceed = await confirm(rl, '\nStart TermBeam with this configuration?', true);
+  rl.close();
+
+  // Exit alternate screen — return to normal terminal
+  exitAltScreen();
+  process.removeListener('exit', exitAltScreen);
+
+  if (!proceed) {
+    console.log(dim('Cancelled.'));
+    process.exit(0);
+  }
+
+  return config;
+}
+
+module.exports = { runInteractiveSetup };

package/src/prompts.js

@@ -0,0 +1,146 @@
+const readline = require('readline');
+
+// ── Color helpers ────────────────────────────────────────────────────────────
+
+function color(code, text) {
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+const green = (t) => color('32', t);
+const yellow = (t) => color('33', t);
+const red = (t) => color('31', t);
+const cyan = (t) => color('36', t);
+const bold = (t) => color('1', t);
+const dim = (t) => color('2', t);
+
+// ── Interactive prompts ──────────────────────────────────────────────────────
+
+/**
+ * Prompt the user with a question. Returns the trimmed answer.
+ * If `defaultValue` is provided, it's shown in brackets and used when the user presses Enter.
+ */
+function ask(rl, question, defaultValue) {
+  const suffix = defaultValue != null ? ` ${dim(`[${defaultValue}]`)} ` : ' '; // eslint-disable-line eqeqeq
+  return new Promise((resolve) => {
+    rl.question(`${question}${suffix}`, (answer) => {
+      const trimmed = answer.trim();
+      resolve(trimmed || (defaultValue != null ? String(defaultValue) : '')); // eslint-disable-line eqeqeq
+    });
+  });
+}
+
+/**
+ * Prompt the user with a list of choices using arrow keys.
+ * Each choice can be a string or { label, hint } object.
+ * Up/Down to move, Enter to select. Returns the chosen value.
+ */
+function choose(rl, question, choices, defaultIndex = 0) {
+  // Normalize choices to { label, hint } objects
+  const items = choices.map((c) => (typeof c === 'string' ? { label: c, hint: '' } : c));
+
+  return new Promise((resolve) => {
+    let selected = defaultIndex;
+
+    function lineCount() {
+      return items.reduce((n, item) => n + 1 + (item.hint ? 1 : 0), 0);
+    }
+
+    function render(clear) {
+      if (clear) {
+        process.stdout.write(`\x1b[${lineCount()}A\r\x1b[J`);
+      }
+      items.forEach((item, i) => {
+        const marker = i === selected ? cyan('→') : ' ';
+        const label = i === selected ? bold(item.label) : item.label;
+        process.stdout.write(`  ${marker} ${label}\n`);
+        if (item.hint) {
+          const hintText = item.danger
+            ? red(item.hint)
+            : item.warn
+              ? yellow(item.hint)
+              : dim(item.hint);
+          process.stdout.write(`      ${hintText}\n`);
+        }
+      });
+      process.stdout.write(dim('  ↑/↓ to move, Enter to select'));
+    }
+
+    rl.pause();
+    console.log(`\n${question}`);
+    render(false);
+
+    const wasRaw = process.stdin.isRaw;
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+
+    function onKey(buf) {
+      const key = buf.toString();
+
+      if (key === '\x1b[A' || key === 'k') {
+        selected = (selected - 1 + items.length) % items.length;
+        render(true);
+      } else if (key === '\x1b[B' || key === 'j') {
+        selected = (selected + 1) % items.length;
+        render(true);
+      } else if (key === '\r' || key === '\n') {
+        cleanup();
+        process.stdout.write('\r\x1b[K\n');
+        console.log(dim(`  Selected: ${items[selected].label}`));
+        resolve({ index: selected, value: items[selected].label });
+      } else if (key === '\x03') {
+        cleanup();
+        process.stdout.write('\x1b[?1049l');
+        process.exit(0);
+      }
+    }
+
+    function cleanup() {
+      process.stdin.removeListener('data', onKey);
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(wasRaw || false);
+      }
+      process.stdin.pause();
+      rl.resume();
+    }
+
+    process.stdin.on('data', onKey);
+  });
+}
+
+/**
+ * Ask a yes/no question. Returns boolean.
+ */
+function confirm(rl, question, defaultYes = true) {
+  const hint = defaultYes ? 'Y/n' : 'y/N';
+  return new Promise((resolve) => {
+    rl.question(`${question} ${dim(`[${hint}]`)} `, (answer) => {
+      const a = answer.trim().toLowerCase();
+      if (a === '') resolve(defaultYes);
+      else resolve(a === 'y' || a === 'yes');
+    });
+  });
+}
+
+// ── readline factory ─────────────────────────────────────────────────────────
+
+function createRL() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+module.exports = {
+  color,
+  green,
+  yellow,
+  red,
+  cyan,
+  bold,
+  dim,
+  ask,
+  choose,
+  confirm,
+  createRL,
+};

package/src/routes.js

@@ -5,10 +5,29 @@ const crypto = require('crypto');
 const express = require('express');
 const { detectShells } = require('./shells');
 const log = require('./logger');
+const rateLimit = require('express-rate-limit');
 
 const PUBLIC_DIR = path.join(__dirname, '..', 'public');
 const uploadedFiles = new Map(); // id -> filepath
 
+const pageRateLimit = rateLimit({
+  windowMs: 1 * 60 * 1000,
+  max: 120,
+  standardHeaders: true,
+  legacyHeaders: false,
+  handler: (_req, res) =>
+    res.status(429).json({ error: 'Too many requests, please try again later.' }),
+});
+
+const apiRateLimit = rateLimit({
+  windowMs: 1 * 60 * 1000,
+  max: 120,
+  standardHeaders: true,
+  legacyHeaders: false,
+  handler: (_req, res) =>
+    res.status(429).json({ error: 'Too many requests, please try again later.' }),
+});
+
 const IMAGE_SIGNATURES = [
   { type: 'image/png', bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] },
   { type: 'image/jpeg', bytes: [0xff, 0xd8, 0xff] },
@@ -74,7 +93,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
     if (!ott || !auth.password) return next();
     // Already authenticated (e.g. DevTunnel anti-phishing re-sent the request) — just redirect
     if (req.cookies.pty_token && auth.validateToken(req.cookies.pty_token)) {
-      return res.redirect(req.path);
+      return res.redirect(req.path === '/terminal' ? '/terminal' : '/');
     }
     if (auth.validateShareToken(ott)) {
       const token = auth.generateToken();
@@ -86,17 +105,17 @@ function setupRoutes(app, { auth, sessions, config, state }) {
       });
       log.info(`Auth: share-token auto-login from ${req.ip}`);
       // Redirect to the same path without ?ott= to keep the URL clean
-      return res.redirect(req.path);
+      return res.redirect(req.path === '/terminal' ? '/terminal' : '/');
     }
     log.warn(`Auth: invalid or expired share token from ${req.ip}`);
     next();
   }
 
   // Pages
-  app.get('/', autoLogin, auth.middleware, (_req, res) =>
+  app.get('/', pageRateLimit, autoLogin, auth.middleware, (_req, res) =>
     res.sendFile('index.html', { root: PUBLIC_DIR }),
   );
-  app.get('/terminal', autoLogin, auth.middleware, (_req, res) =>
+  app.get('/terminal', pageRateLimit, autoLogin, auth.middleware, (_req, res) =>
     res.sendFile('terminal.html', { root: PUBLIC_DIR }),
   );
 
@@ -109,11 +128,11 @@ function setupRoutes(app, { auth, sessions, config, state }) {
   });
 
   // Session API
-  app.get('/api/sessions', auth.middleware, (_req, res) => {
+  app.get('/api/sessions', apiRateLimit, auth.middleware, (_req, res) => {
     res.json(sessions.list());
   });
 
-  app.post('/api/sessions', auth.middleware, (req, res) => {
+  app.post('/api/sessions', apiRateLimit, auth.middleware, (req, res) => {
     const { name, shell, args: shellArgs, cwd, initialCommand, color, cols, rows } = req.body || {};
 
     // Validate shell field
@@ -125,6 +144,20 @@ function setupRoutes(app, { auth, sessions, config, state }) {
       }
     }
 
+    // Validate args field — must be an array of strings
+    if (shellArgs !== undefined) {
+      if (!Array.isArray(shellArgs) || !shellArgs.every((a) => typeof a === 'string')) {
+        return res.status(400).json({ error: 'args must be an array of strings' });
+      }
+    }
+
+    // Validate initialCommand field — must be a string
+    if (initialCommand !== undefined && initialCommand !== null) {
+      if (typeof initialCommand !== 'string') {
+        return res.status(400).json({ error: 'initialCommand must be a string' });
+      }
+    }
+
     // Validate cwd field
     if (cwd) {
       if (!path.isAbsolute(cwd)) {
@@ -139,16 +172,21 @@ function setupRoutes(app, { auth, sessions, config, state }) {
       }
     }
 
-    const id = sessions.create({
-      name: name || `Session ${sessions.sessions.size + 1}`,
-      shell: shell || config.defaultShell,
-      args: shellArgs || [],
-      cwd: cwd || config.cwd,
-      initialCommand: initialCommand || null,
-      color: color || null,
-      cols: typeof cols === 'number' && cols > 0 && cols <= 500 ? Math.floor(cols) : undefined,
-      rows: typeof rows === 'number' && rows > 0 && rows <= 200 ? Math.floor(rows) : undefined,
-    });
+    let id;
+    try {
+      id = sessions.create({
+        name: name || `Session ${sessions.sessions.size + 1}`,
+        shell: shell || config.defaultShell,
+        args: shellArgs || [],
+        cwd: cwd ? path.resolve(cwd) : config.cwd,
+        initialCommand: initialCommand ?? null,
+        color: color || null,
+        cols: typeof cols === 'number' && cols > 0 && cols <= 500 ? Math.floor(cols) : undefined,
+        rows: typeof rows === 'number' && rows > 0 && rows <= 200 ? Math.floor(rows) : undefined,
+      });
+    } catch (err) {
+      return res.status(400).json({ error: err.message || 'Failed to create session' });
+    }
     res.json({ id, url: `/terminal?id=${id}` });
   });
 
@@ -260,7 +298,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
   });
 
   // Serve uploaded files by opaque ID
-  app.get('/uploads/:id', auth.middleware, (req, res) => {
+  app.get('/uploads/:id', pageRateLimit, auth.middleware, (req, res) => {
     const filepath = uploadedFiles.get(req.params.id);
     if (!filepath) return res.status(404).json({ error: 'not found' });
     if (!fs.existsSync(filepath)) {
@@ -271,10 +309,10 @@ function setupRoutes(app, { auth, sessions, config, state }) {
   });
 
   // Directory listing for folder browser
-  app.get('/api/dirs', auth.middleware, (req, res) => {
+  app.get('/api/dirs', apiRateLimit, auth.middleware, (req, res) => {
     const query = req.query.q || config.cwd + path.sep;
     const endsWithSep = query.endsWith('/') || query.endsWith('\\');
-    const dir = endsWithSep ? query : path.dirname(query);
+    const dir = path.resolve(endsWithSep ? query : path.dirname(query));
     const prefix = endsWithSep ? '' : path.basename(query);
 
     try {
@@ -292,7 +330,7 @@ function setupRoutes(app, { auth, sessions, config, state }) {
 }
 
 function cleanupUploadedFiles() {
-  for (const [id, filepath] of uploadedFiles) {
+  for (const [_id, filepath] of uploadedFiles) {
     try {
       if (fs.existsSync(filepath)) {
         fs.unlinkSync(filepath);

package/src/server.js

@@ -172,7 +172,7 @@ function createTermBeamServer(overrides = {}) {
           config.host === '0.0.0.0' || config.host === '::' || config.host === ip;
         state.shareBaseUrl = isLanReachable ? localUrl : `http://localhost:${config.port}`;
         const gn = '\x1b[38;5;114m'; // green
-        const dm = '\x1b[2m'; // dim
+        const _dm = '\x1b[2m'; // dim
 
         const bl = '\x1b[38;5;75m'; // light blue
 
@@ -220,7 +220,7 @@ function createTermBeamServer(overrides = {}) {
         }
 
         console.log(`  Scan the QR code or open: ${bl}${qrDisplayUrl}${rs}`);
-        if (config.password) console.log(`  Password: ${gn}${config.password}${rs}`);
+        if (config.password) process.stdout.write(`  Password: ${gn}${config.password}${rs}\n`);
         console.log('');
 
         resolve({ url: `http://localhost:${config.port}`, defaultId });

package/src/service.js

@@ -1,133 +1,26 @@
-const { execFileSync, execFile } = require('child_process');
+const { execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
-const readline = require('readline');
+const {
+  color,
+  green,
+  yellow,
+  red,
+  cyan,
+  bold,
+  dim,
+  ask,
+  choose,
+  confirm,
+  createRL,
+} = require('./prompts');
 
 const TERMBEAM_DIR = path.join(os.homedir(), '.termbeam');
 const ECOSYSTEM_FILE = path.join(TERMBEAM_DIR, 'ecosystem.config.js');
 const DEFAULT_SERVICE_NAME = 'termbeam';
 
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function color(code, text) {
-  return `\x1b[${code}m${text}\x1b[0m`;
-}
-const green = (t) => color('32', t);
-const yellow = (t) => color('33', t);
-const red = (t) => color('31', t);
-const cyan = (t) => color('36', t);
-const bold = (t) => color('1', t);
-const dim = (t) => color('2', t);
-
-/**
- * Prompt the user with a question. Returns the trimmed answer.
- * If `defaultValue` is provided, it's shown in brackets and used when the user presses Enter.
- */
-function ask(rl, question, defaultValue) {
-  const suffix = defaultValue != null ? ` ${dim(`[${defaultValue}]`)} ` : ' ';
-  return new Promise((resolve) => {
-    rl.question(`${question}${suffix}`, (answer) => {
-      const trimmed = answer.trim();
-      resolve(trimmed || (defaultValue != null ? String(defaultValue) : ''));
-    });
-  });
-}
-
-/**
- * Prompt the user with a list of choices using arrow keys.
- * Each choice can be a string or { label, hint } object.
- * Up/Down to move, Enter to select. Returns the chosen value.
- */
-function choose(rl, question, choices, defaultIndex = 0) {
-  // Normalize choices to { label, hint } objects
-  const items = choices.map((c) => (typeof c === 'string' ? { label: c, hint: '' } : c));
-
-  return new Promise((resolve) => {
-    let selected = defaultIndex;
-
-    function lineCount() {
-      return items.reduce((n, item) => n + 1 + (item.hint ? 1 : 0), 0);
-    }
-
-    function render(clear) {
-      if (clear) {
-        process.stdout.write(`\x1b[${lineCount()}A\r\x1b[J`);
-      }
-      items.forEach((item, i) => {
-        const marker = i === selected ? cyan('→') : ' ';
-        const label = i === selected ? bold(item.label) : item.label;
-        process.stdout.write(`  ${marker} ${label}\n`);
-        if (item.hint) {
-          const hintText = item.danger
-            ? red(item.hint)
-            : item.warn
-              ? yellow(item.hint)
-              : dim(item.hint);
-          process.stdout.write(`      ${hintText}\n`);
-        }
-      });
-      process.stdout.write(dim('  ↑/↓ to move, Enter to select'));
-    }
-
-    rl.pause();
-    console.log(`\n${question}`);
-    render(false);
-
-    const wasRaw = process.stdin.isRaw;
-    if (process.stdin.isTTY) {
-      process.stdin.setRawMode(true);
-    }
-    process.stdin.resume();
-
-    function onKey(buf) {
-      const key = buf.toString();
-
-      if (key === '\x1b[A' || key === 'k') {
-        selected = (selected - 1 + items.length) % items.length;
-        render(true);
-      } else if (key === '\x1b[B' || key === 'j') {
-        selected = (selected + 1) % items.length;
-        render(true);
-      } else if (key === '\r' || key === '\n') {
-        cleanup();
-        process.stdout.write('\r\x1b[K\n');
-        console.log(dim(`  Selected: ${items[selected].label}`));
-        resolve({ index: selected, value: items[selected].label });
-      } else if (key === '\x03') {
-        cleanup();
-        process.exit(0);
-      }
-    }
-
-    function cleanup() {
-      process.stdin.removeListener('data', onKey);
-      if (process.stdin.isTTY) {
-        process.stdin.setRawMode(wasRaw || false);
-      }
-      process.stdin.pause();
-      rl.resume();
-    }
-
-    process.stdin.on('data', onKey);
-  });
-}
-
-/**
- * Ask a yes/no question. Returns boolean.
- */
-function confirm(rl, question, defaultYes = true) {
-  const hint = defaultYes ? 'Y/n' : 'y/N';
-  return new Promise((resolve) => {
-    rl.question(`${question} ${dim(`[${hint}]`)} `, (answer) => {
-      const a = answer.trim().toLowerCase();
-      if (a === '') resolve(defaultYes);
-      else resolve(a === 'y' || a === 'yes');
-    });
-  });
-}
-
 // ── PM2 Detection ────────────────────────────────────────────────────────────
 
 function findPm2() {
@@ -344,7 +237,7 @@ async function actionInstall() {
   ]);
   if (pwChoice.index === 0) {
     config.password = crypto.randomBytes(16).toString('base64url');
-    console.log(dim(`  Generated password: ${config.password}`));
+    process.stdout.write(dim(`  Generated password: ${config.password}`) + '\n');
   } else if (pwChoice.index === 1) {
     config.password = await ask(rl, 'Enter password:');
     while (!config.password) {
@@ -404,7 +297,7 @@ async function actionInstall() {
     if (config.publicTunnel && config.password === false) {
       console.log(yellow('  ⚠ Public tunnels require password authentication.'));
       config.password = crypto.randomBytes(16).toString('base64url');
-      console.log(dim(`  Auto-generated password: ${config.password}`));
+      process.stdout.write(dim(`  Auto-generated password: ${config.password}`) + '\n');
     }
   } else if (accessChoice.index === 1) {
     // LAN mode: bind to all interfaces, no tunnel
@@ -459,7 +352,7 @@ async function actionInstall() {
   console.log(bold('\n── Configuration Summary ──────────────────'));
   console.log(`  Service name:  ${cyan(config.name)}`);
   console.log(
-    `  Password:      ${config.password === false ? yellow('disabled') : cyan(config.password)}`,
+    `  Password:      ${config.password === false ? yellow('disabled') : cyan('••••••••')}`,
   );
   console.log(`  Port:          ${cyan(String(config.port))}`);
   console.log(
@@ -651,15 +544,6 @@ function actionRestart() {
   console.log(green('\n✓ TermBeam service restarted.\n'));
 }
 
-// ── readline factory ─────────────────────────────────────────────────────────
-
-function createRL() {
-  return readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-}
-
 // ── Entrypoint ───────────────────────────────────────────────────────────────
 
 function printServiceHelp() {

package/src/sessions.js

@@ -1,11 +1,12 @@
 const crypto = require('crypto');
+const path = require('path');
 const { execSync, exec } = require('child_process');
 const fs = require('fs');
 const pty = require('node-pty');
 const log = require('./logger');
 const { getGitInfo } = require('./git');
 
-function getProcessCwd(pid) {
+function _getProcessCwd(pid) {
   try {
     if (process.platform === 'linux') {
       return fs.readlinkSync(`/proc/${pid}/cwd`);
@@ -108,6 +109,24 @@ class SessionManager {
     cols = 120,
     rows = 30,
   }) {
+    // Defense-in-depth: reject shells with dangerous characters or relative paths
+    if (
+      typeof shell !== 'string' ||
+      !shell ||
+      /[;&|`$(){}\[\]!#~]/.test(shell) ||
+      (!path.isAbsolute(shell) && !shell.match(/^[a-zA-Z0-9._-]+(\.exe)?$/))
+    ) {
+      throw new Error('Invalid shell');
+    }
+
+    // Defense-in-depth: validate args and initialCommand types
+    if (!Array.isArray(args) || !args.every((a) => typeof a === 'string')) {
+      throw new Error('args must be an array of strings');
+    }
+    if (initialCommand !== null && typeof initialCommand !== 'string') {
+      throw new Error('initialCommand must be a string');
+    }
+
     const id = crypto.randomBytes(16).toString('hex');
     if (!color) {
       color = SESSION_COLORS[this.sessions.size % SESSION_COLORS.length];
@@ -209,7 +228,7 @@ class SessionManager {
   }
 
   shutdown() {
-    for (const [id, s] of this.sessions) {
+    for (const [_id, s] of this.sessions) {
       try {
         s.pty.kill();
       } catch {

package/src/tunnel.js

@@ -67,7 +67,7 @@ function savePersistedTunnel(id) {
   );
 }
 
-function deletePersisted() {
+function _deletePersisted() {
   const persisted = loadPersistedTunnel();
   if (persisted) {
     try {
@@ -139,7 +139,7 @@ async function startTunnel(port, options = {}) {
         log.info('A code will be displayed — open the URL on any device to authenticate.');
         try {
           execFileSync(devtunnelCmd, ['user', 'login', '-d'], { stdio: 'inherit' });
-        } catch (loginErr) {
+        } catch (_loginErr) {
           log.error('');
           log.error('  DevTunnel login failed. To use tunnels, run:');
           log.error('    devtunnel user login');