termbeam 0.1.1 → 1.0.1

package/README.md

@@ -105,8 +105,9 @@ termbeam --host 127.0.0.1        # restrict to localhost (default: 0.0.0.0)
 | `--persisted-tunnel`  | Create a reusable devtunnel URL          | Off              |
 | `--port <port>`       | Server port                              | `3456`           |
 | `--host <addr>`       | Bind address                             | `0.0.0.0`        |
+| `--log-level <level>` | Log verbosity (error/warn/info/debug) | `info` |
 
-Environment variables: `PORT`, `TERMBEAM_PASSWORD`, `TERMBEAM_CWD`, `SHELL` (Unix fallback), `COMSPEC` (Windows fallback). See [Configuration docs](https://dorlugasigal.github.io/TermBeam/configuration/).
+Environment variables: `PORT`, `TERMBEAM_PASSWORD`, `TERMBEAM_CWD`, `TERMBEAM_LOG_LEVEL`, `SHELL` (Unix fallback), `COMSPEC` (Windows fallback). See [Configuration docs](https://dorlugasigal.github.io/TermBeam/configuration/).
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termbeam",
-  "version": "0.1.1",
+  "version": "1.0.1",
   "description": "Beam your terminal to any device — mobile-optimized web terminal with multi-session support",
   "main": "src/server.js",
   "bin": {
@@ -9,8 +9,8 @@
   "scripts": {
     "start": "node bin/termbeam.js",
     "dev": "node bin/termbeam.js --generate-password",
-    "test": "node --test test/*.test.js",
-    "test:coverage": "c8 --reporter=text --reporter=lcov --reporter=json-summary --reporter=json node --test --test-reporter=spec --test-reporter-destination=stdout test/*.test.js",
+    "test": "node -e \"require('child_process').execFileSync(process.execPath,['--test',...require('fs').readdirSync('test').filter(f=>f.endsWith('.test.js')).map(f=>'test/'+f)],{stdio:'inherit'})\"",
+    "test:coverage": "c8 --exclude=src/tunnel.js --reporter=text --reporter=lcov --reporter=json-summary --reporter=json node -e \"require('child_process').execFileSync(process.execPath,['--test','--test-reporter=spec','--test-reporter-destination=stdout',...require('fs').readdirSync('test').filter(f=>f.endsWith('.test.js')).map(f=>'test/'+f)],{stdio:'inherit'})\"",
     "prepare": "husky",
     "format": "prettier --write .",
     "lint": "node --check src/*.js bin/*.js",
@@ -24,9 +24,18 @@
     "remote-terminal",
     "xterm",
     "websocket",
-    "ssh-alternative"
+    "ssh-alternative",
+    "mobile-terminal",
+    "terminal-sharing",
+    "browser-terminal",
+    "remote-access",
+    "qr-code",
+    "touch-terminal",
+    "terminal-emulator",
+    "devtools",
+    "cli"
   ],
-  "author": "",
+  "author": "Dor Lugasi <dorlugasigal@gmail.com>",
   "license": "MIT",
   "homepage": "https://github.com/dorlugasigal/TermBeam",
   "repository": {

package/public/index.html

@@ -9,9 +9,10 @@
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="mobile-web-app-capable" content="yes" />
     <meta name="theme-color" content="#1e1e1e" />
+    <meta name="description" content="TermBeam — beam your terminal to any device. Mobile-optimized web terminal with multi-session support, touch controls, and QR code connection. No SSH needed." />
     <link rel="manifest" href="/manifest.json" />
     <link rel="apple-touch-icon" href="/icons/icon-192.png" />
-    <title>TermBeam</title>
+    <title>TermBeam — Beam Your Terminal to Any Device</title>
     <style>
       :root {
         --bg: #1e1e1e;
@@ -958,7 +959,13 @@
       let currentBrowsePath = '/';
       let hubServerCwd = '/';
 
-      document.getElementById('browse-btn').addEventListener('click', () => {
+      document.getElementById('browse-btn').addEventListener('click', async () => {
+        if (hubServerCwd === '/') {
+          try {
+            const data = await fetch('/api/shells').then(r => r.json());
+            if (data.cwd) hubServerCwd = data.cwd;
+          } catch {}
+        }
         const initial = cwdInput.value.trim() || hubServerCwd;
         navigateTo(initial);
         browserOverlay.classList.add('visible');

package/public/terminal.html

@@ -6,6 +6,7 @@
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="mobile-web-app-capable" content="yes" />
     <meta name="theme-color" content="#1e1e1e" />
+    <meta name="description" content="TermBeam terminal session — access your terminal remotely from any browser with a mobile-optimized touch interface." />
     <link rel="manifest" href="/manifest.json" />
     <link rel="apple-touch-icon" href="/icons/icon-192.png" />
     <title>TermBeam — Terminal</title>
@@ -1349,12 +1350,16 @@
       }
 
       async function removeSession(id) {
-        try { await fetch('/api/sessions/' + encodeURIComponent(id), { method: 'DELETE' }); } catch {}
-
         const ms = managed.get(id);
         if (ms) {
+          ms.exited = true;
+          if (ms.reconnectTimer) { clearTimeout(ms.reconnectTimer); ms.reconnectTimer = null; }
           if (ms.ws) try { ms.ws.close(); } catch {}
-          if (ms.reconnectTimer) clearTimeout(ms.reconnectTimer);
+        }
+
+        try { await fetch('/api/sessions/' + encodeURIComponent(id), { method: 'DELETE' }); } catch {}
+
+        if (ms) {
           ms.term.dispose();
           ms.container.remove();
           managed.delete(id);
@@ -2007,7 +2012,13 @@
         let nsBrowsePath = '/';
         let serverCwd = '/';
 
-        document.getElementById('ns-browse-btn').addEventListener('click', () => {
+        document.getElementById('ns-browse-btn').addEventListener('click', async () => {
+          if (serverCwd === '/') {
+            try {
+              const data = await fetch('/api/shells').then(r => r.json());
+              if (data.cwd) serverCwd = data.cwd;
+            } catch {}
+          }
           const initial = nsCwdInput.value.trim() || serverCwd;
           nsBrowseNavigate(initial);
           nsBrowserOverlay.classList.add('visible');
@@ -2162,8 +2173,9 @@
             for (const id of [...managed.keys()]) {
               if (!serverIds.has(id)) {
                 const ms = managed.get(id);
+                ms.exited = true;
+                if (ms.reconnectTimer) { clearTimeout(ms.reconnectTimer); ms.reconnectTimer = null; }
                 if (ms.ws) try { ms.ws.close(); } catch {}
-                if (ms.reconnectTimer) clearTimeout(ms.reconnectTimer);
                 ms.term.dispose();
                 ms.container.remove();
                 managed.delete(id);

package/src/auth.js

@@ -1,4 +1,5 @@
 const crypto = require('crypto');
+const log = require('./logger');
 
 const LOGIN_HTML = `<!DOCTYPE html>
 <html lang="en">
@@ -107,7 +108,7 @@ function createAuth(password) {
     const attempts = authAttempts.get(ip) || [];
     const recent = attempts.filter((t) => now - t < window);
     if (recent.length >= maxAttempts) {
-      console.warn(`[termbeam] Auth: rate limit exceeded for ${ip}`);
+      log.warn(`Auth: rate limit exceeded for ${ip}`);
       return res.status(429).json({ error: 'Too many attempts. Try again later.' });
     }
     recent.push(now);

package/src/cli.js

@@ -1,6 +1,7 @@
 const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
+const log = require('./logger');
 
 function printHelp() {
   console.log(`
@@ -18,6 +19,7 @@ Options:
   --persisted-tunnel    Create a reusable devtunnel URL (stable across restarts)
   --port <port>         Set port (default: 3456, or PORT env var)
   --host <addr>         Bind address (default: 0.0.0.0)
+  --log-level <level>   Set log verbosity: error, warn, info, debug (default: info)
   -h, --help            Show this help
   -v, --version         Show version
 
@@ -37,6 +39,7 @@ Environment:
   PORT                  Server port (default: 3456)
   TERMBEAM_PASSWORD     Access password
   TERMBEAM_CWD          Working directory
+  TERMBEAM_LOG_LEVEL    Log level (default: info)
 `);
 }
 
@@ -82,13 +85,13 @@ function getWindowsAncestors(startPid, maxDepth = 4) {
     for (let i = 0; i < maxDepth; i++) {
       const proc = processes.get(currentPid);
       if (!proc) break;
-      console.log(`[termbeam] Process tree: ${proc.name}`);
+      log.debug(`Process tree: ${proc.name}`);
       names.push(proc.name);
       if (!Number.isFinite(proc.ppid) || proc.ppid === 0 || proc.ppid === currentPid) break;
       currentPid = proc.ppid;
     }
   } catch (err) {
-    console.log(`[termbeam] Could not query process tree: ${err.message}`);
+    log.debug(`Could not query process tree: ${err.message}`);
   }
 
   return names;
@@ -97,7 +100,7 @@ function getWindowsAncestors(startPid, maxDepth = 4) {
 function getDefaultShell() {
   const { execFileSync } = require('child_process');
   const ppid = process.ppid;
-  console.log(`[termbeam] Detecting shell (parent PID: ${ppid}, platform: ${os.platform()})`);
+  log.debug(`Detecting shell (parent PID: ${ppid}, platform: ${os.platform()})`);
 
   if (os.platform() === 'win32') {
     // Walk up the process tree (up to 4 ancestors) to find the real user shell.
@@ -109,18 +112,18 @@ function getDefaultShell() {
     let foundCmd = false;
     for (const name of ancestors) {
       if (preferredShells.includes(name)) {
-        console.log(`[termbeam] Found shell in process tree: ${name}`);
+        log.debug(`Found shell in process tree: ${name}`);
         return name;
       }
       if (name === 'cmd.exe') foundCmd = true;
     }
 
     if (foundCmd) {
-      console.log(`[termbeam] Using detected shell: cmd.exe`);
+      log.debug(`Using detected shell: cmd.exe`);
       return 'cmd.exe';
     }
     const fallback = process.env.COMSPEC || 'cmd.exe';
-    console.log(`[termbeam] Falling back to: ${fallback}`);
+    log.debug(`Falling back to: ${fallback}`);
     return fallback;
   }
 
@@ -134,22 +137,33 @@ function getDefaultShell() {
     const comm = result.trim();
     if (comm) {
       const shell = comm.startsWith('-') ? comm.slice(1) : comm;
-      console.log(`[termbeam] Detected parent shell: ${shell}`);
+      log.debug(`Detected parent shell: ${shell}`);
       return shell;
     }
   } catch (err) {
-    console.log(`[termbeam] Could not detect parent shell: ${err.message}`);
+    log.debug(`Could not detect parent shell: ${err.message}`);
   }
 
   // Fallback to SHELL env or /bin/sh
   const fallback = process.env.SHELL || '/bin/sh';
-  console.log(`[termbeam] Falling back to: ${fallback}`);
+  log.debug(`Falling back to: ${fallback}`);
   return fallback;
 }
 
 function parseArgs() {
   let port = parseInt(process.env.PORT || '3456', 10);
   let host = '0.0.0.0';
+
+  // Resolve log level early (env + args) so shell detection logs are visible
+  let logLevel = process.env.TERMBEAM_LOG_LEVEL || 'info';
+  for (const arg of process.argv.slice(2)) {
+    if (arg.startsWith('--log-level=')) { logLevel = arg.split('=')[1]; break; }
+  }
+  for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i] === '--log-level' && process.argv[i + 1]) { logLevel = process.argv[i + 1]; break; }
+  }
+  log.setLevel(logLevel);
+
   const defaultShell = getDefaultShell();
   const cwd = process.env.TERMBEAM_CWD || process.env.PTY_CWD || process.cwd();
   let password = process.env.TERMBEAM_PASSWORD || process.env.PTY_PASSWORD || null;
@@ -192,6 +206,8 @@ function parseArgs() {
       port = parseInt(args[++i], 10);
     } else if (args[i] === '--host' && args[i + 1]) {
       host = args[++i];
+    } else if (args[i] === '--log-level' && args[i + 1]) {
+      logLevel = args[++i];
     } else {
       filteredArgs.push(args[i]);
     }
@@ -211,7 +227,7 @@ function parseArgs() {
   const { getVersion } = require('./version');
   const version = getVersion();
 
-  return { port, host, password, useTunnel, persistedTunnel, shell, shellArgs, cwd, defaultShell, version };
+  return { port, host, password, useTunnel, persistedTunnel, shell, shellArgs, cwd, defaultShell, version, logLevel };
 }
 
 module.exports = { parseArgs, printHelp };

package/src/logger.js

@@ -0,0 +1,32 @@
+const LEVELS = { error: 0, warn: 1, info: 2, debug: 3 };
+const LABELS = { error: 'ERROR', warn: 'WARN', info: 'INFO', debug: 'DEBUG' };
+
+let currentLevel = LEVELS.info;
+
+function timestamp() {
+  return new Date().toLocaleTimeString('en-GB', { hour12: false });
+}
+
+const log = {
+  setLevel(level) {
+    const l = LEVELS[level];
+    if (l !== undefined) currentLevel = l;
+  },
+  getLevel() {
+    return Object.keys(LEVELS).find(k => LEVELS[k] === currentLevel);
+  },
+  error(...args) {
+    if (currentLevel >= LEVELS.error) console.error(`[${timestamp()}]`, `[${LABELS.error}]`, ...args);
+  },
+  warn(...args) {
+    if (currentLevel >= LEVELS.warn) console.warn(`[${timestamp()}]`, `[${LABELS.warn}]`, ...args);
+  },
+  info(...args) {
+    if (currentLevel >= LEVELS.info) console.log(`[${timestamp()}]`, `[${LABELS.info}]`, ...args);
+  },
+  debug(...args) {
+    if (currentLevel >= LEVELS.debug) console.log(`[${timestamp()}]`, `[${LABELS.debug}]`, ...args);
+  },
+};
+
+module.exports = log;

package/src/routes.js

@@ -4,8 +4,10 @@ const fs = require('fs');
 const crypto = require('crypto');
 const express = require('express');
 const { detectShells } = require('./shells');
+const log = require('./logger');
 
 const PUBLIC_DIR = path.join(__dirname, '..', 'public');
+const uploadedFiles = [];
 
 function setupRoutes(app, { auth, sessions, config }) {
   // Serve static files (manifest.json, sw.js, icons, etc.)
@@ -28,10 +30,10 @@ function setupRoutes(app, { auth, sessions, config }) {
         maxAge: 24 * 60 * 60 * 1000,
         secure: false,
       });
-      console.log(`[termbeam] Auth: login success from ${req.ip}`);
+      log.info(`Auth: login success from ${req.ip}`);
       res.json({ ok: true });
     } else {
-      console.warn(`[termbeam] Auth: login failed from ${req.ip}`);
+      log.warn(`Auth: login failed from ${req.ip}`);
       res.status(401).json({ error: 'wrong password' });
     }
   });
@@ -55,6 +57,30 @@ function setupRoutes(app, { auth, sessions, config }) {
 
   app.post('/api/sessions', auth.middleware, (req, res) => {
     const { name, shell, args: shellArgs, cwd, initialCommand, color } = req.body || {};
+
+    // Validate shell field
+    if (shell) {
+      const availableShells = detectShells();
+      const isValid = availableShells.some(s => s.path === shell || s.cmd === shell);
+      if (!isValid) {
+        return res.status(400).json({ error: 'Invalid shell' });
+      }
+    }
+
+    // Validate cwd field
+    if (cwd) {
+      if (!path.isAbsolute(cwd)) {
+        return res.status(400).json({ error: 'cwd must be an absolute path' });
+      }
+      try {
+        if (!fs.statSync(cwd).isDirectory()) {
+          return res.status(400).json({ error: 'cwd is not a directory' });
+        }
+      } catch {
+        return res.status(400).json({ error: 'cwd does not exist' });
+      }
+    }
+
     const id = sessions.create({
       name: name || `Session ${sessions.sessions.size + 1}`,
       shell: shell || config.defaultShell,
@@ -96,7 +122,7 @@ function setupRoutes(app, { auth, sessions, config }) {
   app.post('/api/upload', auth.middleware, (req, res) => {
     const contentType = req.headers['content-type'] || '';
     if (!contentType.startsWith('image/')) {
-      console.warn(`[termbeam] Upload rejected: invalid content-type "${contentType}"`);
+      log.warn(`Upload rejected: invalid content-type "${contentType}"`);
       return res.status(400).json({ error: 'Invalid content type' });
     }
 
@@ -110,7 +136,7 @@ function setupRoutes(app, { auth, sessions, config }) {
       size += chunk.length;
       if (size > limit) {
         aborted = true;
-        console.warn(`[termbeam] Upload rejected: file too large (${size} bytes)`);
+        log.warn(`Upload rejected: file too large (${size} bytes)`);
         res.status(413).json({ error: 'File too large' });
         req.resume(); // drain remaining data
         return;
@@ -134,12 +160,13 @@ function setupRoutes(app, { auth, sessions, config }) {
       const filename = `termbeam-${crypto.randomUUID()}${ext}`;
       const filepath = path.join(os.tmpdir(), filename);
       fs.writeFileSync(filepath, buffer);
-      console.log(`[termbeam] Upload: ${filename} (${buffer.length} bytes)`);
+      uploadedFiles.push(filepath);
+      log.info(`Upload: ${filename} (${buffer.length} bytes)`);
       res.json({ path: filepath });
     });
 
     req.on('error', (err) => {
-      console.error(`[termbeam] Upload error: ${err.message}`);
+      log.error(`Upload error: ${err.message}`);
       res.status(500).json({ error: 'Upload failed' });
     });
   });
@@ -165,4 +192,17 @@ function setupRoutes(app, { auth, sessions, config }) {
   });
 }
 
-module.exports = { setupRoutes };
+function cleanupUploadedFiles() {
+  for (const filepath of uploadedFiles) {
+    try {
+      if (fs.existsSync(filepath)) {
+        fs.unlinkSync(filepath);
+      }
+    } catch (err) {
+      log.error(`Failed to cleanup ${filepath}: ${err.message}`);
+    }
+  }
+  uploadedFiles.length = 0;
+}
+
+module.exports = { setupRoutes, cleanupUploadedFiles };

package/src/server.js

@@ -10,57 +10,11 @@ const QRCode = require('qrcode');
 const { parseArgs } = require('./cli');
 const { createAuth } = require('./auth');
 const { SessionManager } = require('./sessions');
-const { setupRoutes } = require('./routes');
+const { setupRoutes, cleanupUploadedFiles } = require('./routes');
 const { setupWebSocket } = require('./websocket');
 const { startTunnel, cleanupTunnel } = require('./tunnel');
 
-// --- Config ---
-const config = parseArgs();
-const auth = createAuth(config.password);
-const sessions = new SessionManager();
-
-// --- Express ---
-const app = express();
-app.use(express.json());
-app.use(cookieParser());
-app.use((_req, res, next) => {
-  res.setHeader('X-Content-Type-Options', 'nosniff');
-  res.setHeader('X-Frame-Options', 'DENY');
-  res.setHeader('Referrer-Policy', 'no-referrer');
-  res.setHeader('Cache-Control', 'no-store');
-  res.setHeader('Content-Security-Policy', "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; connect-src 'self' ws: wss:; font-src 'self' https://cdn.jsdelivr.net");
-  next();
-});
-
-const server = http.createServer(app);
-const wss = new WebSocketServer({ server, path: '/ws', maxPayload: 1 * 1024 * 1024 });
-
-setupRoutes(app, { auth, sessions, config });
-setupWebSocket(wss, { auth, sessions });
-
-// --- Lifecycle ---
-let shuttingDown = false;
-function shutdown() {
-  if (shuttingDown) return;
-  shuttingDown = true;
-  console.log('\n[termbeam] Shutting down...');
-  sessions.shutdown();
-  cleanupTunnel();
-  server.close();
-  wss.close();
-  // Force exit after giving connections time to close
-  setTimeout(() => process.exit(0), 500).unref();
-}
-
-process.on('SIGINT', shutdown);
-process.on('SIGTERM', shutdown);
-process.on('uncaughtException', (err) => {
-  console.error('[termbeam] Uncaught exception:', err.message);
-  cleanupTunnel();
-  process.exit(1);
-});
-
-// --- Start ---
+// --- Helpers ---
 function getLocalIP() {
   const interfaces = os.networkInterfaces();
   for (const name of Object.keys(interfaces)) {
@@ -71,80 +25,163 @@ function getLocalIP() {
   return '127.0.0.1';
 }
 
-server.listen(config.port, config.host, async () => {
-  const ip = getLocalIP();
-  const localUrl = `http://${ip}:${config.port}`;
-
-  const defaultId = sessions.create({
-    name: path.basename(config.cwd),
-    shell: config.shell,
-    args: config.shellArgs,
-    cwd: config.cwd,
+/**
+ * Create a TermBeam server instance without starting it.
+ * @param {object} [overrides] - Optional overrides
+ * @param {object} [overrides.config] - Full config object (skips parseArgs)
+ * @returns {{ app, server, wss, sessions, config, auth, start, shutdown }}
+ */
+function createTermBeamServer(overrides = {}) {
+  const config = overrides.config || parseArgs();
+  const log = require('./logger');
+  if (config.logLevel) log.setLevel(config.logLevel);
+  const auth = createAuth(config.password);
+  const sessions = new SessionManager();
+
+  // --- Express ---
+  const app = express();
+  app.use(express.json());
+  app.use(cookieParser());
+  app.use((_req, res, next) => {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('X-Frame-Options', 'DENY');
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader(
+      'Content-Security-Policy',
+      "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; connect-src 'self' ws: wss:; font-src 'self' https://cdn.jsdelivr.net",
+    );
+    next();
   });
 
-  const lp = '\x1b[38;5;141m'; // light purple
-  const rs = '\x1b[0m'; // reset
-  console.log('');
-  console.log(
-    `${lp}  ████████╗███████╗██████╗ ███╗   ███╗██████╗ ███████╗ █████╗ ███╗   ███╗${rs}`,
-  );
-  console.log(
-    `${lp}  ╚══██╔══╝██╔════╝██╔══██╗████╗ ████║██╔══██╗██╔════╝██╔══██╗████╗ ████║${rs}`,
-  );
-  console.log(
-    `${lp}     ██║   █████╗  ██████╔╝██╔████╔██║██████╔╝█████╗  ███████║██╔████╔██║${rs}`,
-  );
-  console.log(
-    `${lp}     ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║██╔══██╗██╔══╝  ██╔══██║██║╚██╔╝██║${rs}`,
-  );
-  console.log(
-    `${lp}     ██║   ███████╗██║  ██║██║ ╚═╝ ██║██████╔╝███████╗██║  ██║██║ ╚═╝ ██║${rs}`,
-  );
-  console.log(
-    `${lp}     ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝${rs}`,
-  );
-  console.log('');
-  console.log(`  Beam your terminal to any device 📡  v${config.version}`);
-  console.log('');
-  const isLanReachable = config.host === '0.0.0.0' || config.host === '::' || config.host === ip;
-  const gn = '\x1b[38;5;114m'; // green
-  const dm = '\x1b[2m'; // dim
-
-  let publicUrl = null;
-  if (config.useTunnel) {
-    const tunnel = await startTunnel(config.port, { persisted: config.persistedTunnel });
-    if (tunnel) {
-      publicUrl = tunnel.url;
-    } else {
-      console.log('  ⚠️  Tunnel failed to start. Using LAN only.');
-    }
+  const server = http.createServer(app);
+  const wss = new WebSocketServer({ server, path: '/ws', maxPayload: 1 * 1024 * 1024 });
+
+  setupRoutes(app, { auth, sessions, config });
+  setupWebSocket(wss, { auth, sessions });
+
+  // --- Lifecycle ---
+  let shuttingDown = false;
+  function shutdown() {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    sessions.shutdown();
+    cleanupUploadedFiles();
+    cleanupTunnel();
+    server.close();
+    wss.close();
   }
 
-  console.log(`  Shell:    ${config.shell}`);
-  console.log(`  Session:  ${defaultId}`);
-  console.log(`  Auth:     ${config.password ? `${gn}🔒 password${rs}` : '🔓 none'}`);
-  console.log('');
-
-  if (publicUrl) {
-    console.log(`  🌐 Public:  ${publicUrl}`);
-  }
-  console.log(`  Local:    http://localhost:${config.port}`);
-  if (isLanReachable) {
-    console.log(`  LAN:      ${localUrl}`);
+  function start() {
+    return new Promise((resolve) => {
+      server.listen(config.port, config.host, async () => {
+        const ip = getLocalIP();
+        const localUrl = `http://${ip}:${config.port}`;
+
+        const defaultId = sessions.create({
+          name: path.basename(config.cwd),
+          shell: config.shell,
+          args: config.shellArgs,
+          cwd: config.cwd,
+        });
+
+        const lp = '\x1b[38;5;141m'; // light purple
+        const rs = '\x1b[0m'; // reset
+        console.log('');
+        console.log(
+          `${lp}  ████████╗███████╗██████╗ ███╗   ███╗██████╗ ███████╗ █████╗ ███╗   ███╗${rs}`,
+        );
+        console.log(
+          `${lp}  ╚══██╔══╝██╔════╝██╔══██╗████╗ ████║██╔══██╗██╔════╝██╔══██╗████╗ ████║${rs}`,
+        );
+        console.log(
+          `${lp}     ██║   █████╗  ██████╔╝██╔████╔██║██████╔╝█████╗  ███████║██╔████╔██║${rs}`,
+        );
+        console.log(
+          `${lp}     ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║██╔══██╗██╔══╝  ██╔══██║██║╚██╔╝██║${rs}`,
+        );
+        console.log(
+          `${lp}     ██║   ███████╗██║  ██║██║ ╚═╝ ██║██████╔╝███████╗██║  ██║██║ ╚═╝ ██║${rs}`,
+        );
+        console.log(
+          `${lp}     ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝${rs}`,
+        );
+        console.log('');
+        console.log(`  Beam your terminal to any device 📡  v${config.version}`);
+        console.log('');
+        const isLanReachable =
+          config.host === '0.0.0.0' || config.host === '::' || config.host === ip;
+        const gn = '\x1b[38;5;114m'; // green
+        const dm = '\x1b[2m'; // dim
+
+        let publicUrl = null;
+        if (config.useTunnel) {
+          const tunnel = await startTunnel(config.port, { persisted: config.persistedTunnel });
+          if (tunnel) {
+            publicUrl = tunnel.url;
+          } else {
+            console.log('  ⚠️  Tunnel failed to start. Using LAN only.');
+          }
+        }
+
+        console.log(`  Shell:    ${config.shell}`);
+        console.log(`  Session:  ${defaultId}`);
+        console.log(`  Auth:     ${config.password ? `${gn}🔒 password${rs}` : '🔓 none'}`);
+        console.log('');
+
+        if (publicUrl) {
+          console.log(`  🌐 Public:  ${publicUrl}`);
+        }
+        console.log(`  Local:    http://localhost:${config.port}`);
+        if (isLanReachable) {
+          console.log(`  LAN:      ${localUrl}`);
+        }
+
+        const qrUrl = publicUrl || (isLanReachable ? localUrl : `http://localhost:${config.port}`);
+        console.log('');
+        console.log(`  ${dm}📋 Clipboard requires HTTPS — use the Public or localhost URL${rs}`);
+        console.log('');
+        try {
+          const qr = await QRCode.toString(qrUrl, { type: 'terminal', small: true });
+          console.log(qr);
+        } catch {
+          /* ignore */
+        }
+
+        console.log(`  Scan the QR code or open: ${qrUrl}`);
+        if (config.password) console.log(`  Password: ${gn}${config.password}${rs}`);
+        console.log('');
+
+        resolve({ url: `http://localhost:${config.port}`, defaultId });
+      });
+    });
   }
 
-  const qrUrl = publicUrl || (isLanReachable ? localUrl : `http://localhost:${config.port}`);
-  console.log('');
-  console.log(`  ${dm}📋 Clipboard requires HTTPS — use the Public or localhost URL${rs}`);
-  console.log('');
-  try {
-    const qr = await QRCode.toString(qrUrl, { type: 'terminal', small: true });
-    console.log(qr);
-  } catch {
-    /* ignore */
-  }
+  return { app, server, wss, sessions, config, auth, start, shutdown };
+}
+
+module.exports = { createTermBeamServer };
+
+// Auto-start when run directly (CLI entry point)
+const _entryBase = path.basename(process.argv[1] || '');
+if (require.main === module || _entryBase === 'termbeam' || _entryBase === 'termbeam.js') {
+  const instance = createTermBeamServer();
+
+  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();
+  });
+  process.on('uncaughtException', (err) => {
+    console.error('[termbeam] Uncaught exception:', err.message);
+    cleanupTunnel();
+    process.exit(1);
+  });
 
-  console.log(`  Scan the QR code or open: ${qrUrl}`);
-  if (config.password) console.log(`  Password: ${gn}${config.password}${rs}`);
-  console.log('');
-});
+  instance.start();
+}

package/src/sessions.js

@@ -1,5 +1,6 @@
 const crypto = require('crypto');
 const pty = require('node-pty');
+const log = require('./logger');
 
 const SESSION_COLORS = [
   '#4a9eff', '#4ade80', '#fbbf24', '#c084fc',
@@ -12,7 +13,7 @@ class SessionManager {
   }
 
   create({ name, shell, args = [], cwd, initialCommand = null, color = null }) {
-    const id = crypto.randomBytes(4).toString('hex');
+    const id = crypto.randomBytes(16).toString('hex');
     if (!color) {
       color = SESSION_COLORS[this.sessions.size % SESSION_COLORS.length];
     }
@@ -55,7 +56,7 @@ class SessionManager {
     });
 
     ptyProcess.onExit(({ exitCode }) => {
-      console.log(`[termbeam] Session "${name}" (${id}) exited (code ${exitCode})`);
+      log.info(`Session "${name}" (${id}) exited (code ${exitCode})`);
       for (const ws of session.clients) {
         if (ws.readyState === 1) ws.send(JSON.stringify({ type: 'exit', code: exitCode }));
       }
@@ -63,7 +64,7 @@ class SessionManager {
     });
 
     this.sessions.set(id, session);
-    console.log(`[termbeam] Session "${name}" created (id=${id}, pid=${ptyProcess.pid})`);
+    log.info(`Session "${name}" created (id=${id}, pid=${ptyProcess.pid})`);
     return id;
   }
 
@@ -82,7 +83,7 @@ class SessionManager {
   delete(id) {
     const s = this.sessions.get(id);
     if (!s) return false;
-    console.log(`[termbeam] Session "${s.name}" deleted (id=${id})`);
+    log.info(`Session "${s.name}" deleted (id=${id})`);
     s.pty.kill();
     return true;
   }

package/src/tunnel.js

@@ -2,6 +2,7 @@ const { execSync, execFileSync, spawn } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
+const log = require('./logger');
 
 const TUNNEL_CONFIG_DIR = path.join(os.homedir(), '.termbeam');
 const TUNNEL_CONFIG_PATH = path.join(TUNNEL_CONFIG_DIR, 'tunnel.json');
@@ -55,7 +56,7 @@ function deletePersisted() {
     try {
       if (SAFE_ID_RE.test(persisted.tunnelId)) {
         execFileSync(devtunnelCmd, ['delete', persisted.tunnelId, '-f'], { stdio: 'pipe' });
-        console.log(`[termbeam] Deleted persisted tunnel ${persisted.tunnelId}`);
+        log.info(`Deleted persisted tunnel ${persisted.tunnelId}`);
       }
     } catch {}
     try {
@@ -80,24 +81,24 @@ async function startTunnel(port, options = {}) {
   // Check if devtunnel CLI is installed
   const found = findDevtunnel();
   if (!found) {
-    console.error('[termbeam] ❌ devtunnel CLI is not installed.');
-    console.error('');
-    console.error('  The --tunnel flag requires the Azure Dev Tunnels CLI.');
-    console.error('');
-    console.error('  Install it:');
-    console.error('    Windows:  winget install Microsoft.devtunnel');
-    console.error('             or: Invoke-WebRequest -Uri https://aka.ms/TunnelsCliDownload/win-x64 -OutFile devtunnel.exe');
-    console.error('    macOS:    brew install --cask devtunnel');
-    console.error('    Linux:    curl -sL https://aka.ms/DevTunnelCliInstall | bash');
-    console.error('');
-    console.error('  Then restart your terminal and try again.');
-    console.error('  Docs: https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started');
-    console.error('');
+    log.error('❌ devtunnel CLI is not installed.');
+    log.error('');
+    log.error('  The --tunnel flag requires the Azure Dev Tunnels CLI.');
+    log.error('');
+    log.error('  Install it:');
+    log.error('    Windows:  winget install Microsoft.devtunnel');
+    log.error('             or: Invoke-WebRequest -Uri https://aka.ms/TunnelsCliDownload/win-x64 -OutFile devtunnel.exe');
+    log.error('    macOS:    brew install --cask devtunnel');
+    log.error('    Linux:    curl -sL https://aka.ms/DevTunnelCliInstall | bash');
+    log.error('');
+    log.error('  Then restart your terminal and try again.');
+    log.error('  Docs: https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started');
+    log.error('');
     return null;
   }
   devtunnelCmd = found;
 
-  console.log('[termbeam] Starting devtunnel...');
+  log.info('Starting devtunnel...');
   try {
     // Ensure user is logged in
     let loggedIn = false;
@@ -108,8 +109,8 @@ async function startTunnel(port, options = {}) {
     } catch {}
 
     if (!loggedIn) {
-      console.log('[termbeam] devtunnel not logged in, launching login...');
-      console.log('[termbeam] A browser window will open for authentication.');
+      log.info('devtunnel not logged in, launching login...');
+      log.info('A browser window will open for authentication.');
       execFileSync(devtunnelCmd, ['user', 'login'], { stdio: 'inherit' });
     }
 
@@ -124,16 +125,16 @@ async function startTunnel(port, options = {}) {
       const saved = loadPersistedTunnel();
       if (saved && isTunnelValid(saved.tunnelId)) {
         tunnelId = saved.tunnelId;
-        console.log(`[termbeam] Reusing persisted tunnel ${tunnelId}`);
+        log.info(`Reusing persisted tunnel ${tunnelId}`);
       } else {
         if (saved) {
-          console.log('[termbeam] Persisted tunnel expired, creating new one');
+          log.info('Persisted tunnel expired, creating new one');
         }
         const createOut = execFileSync(devtunnelCmd, ['create', '--expiration', '30d', '--json'], { encoding: 'utf-8' });
         const tunnelData = JSON.parse(createOut);
         tunnelId = tunnelData.tunnel.tunnelId;
         savePersistedTunnel(tunnelId);
-        console.log(`[termbeam] Created new persisted tunnel ${tunnelId}`);
+        log.info(`Created new persisted tunnel ${tunnelId}`);
       }
     } else {
       tunnelMode = 'ephemeral';
@@ -142,7 +143,7 @@ async function startTunnel(port, options = {}) {
       const createOut = execFileSync(devtunnelCmd, ['create', '--expiration', '1d', '--json'], { encoding: 'utf-8' });
       const tunnelData = JSON.parse(createOut);
       tunnelId = tunnelData.tunnel.tunnelId;
-      console.log(`[termbeam] Created ephemeral tunnel ${tunnelId}`);
+      log.info(`Created ephemeral tunnel ${tunnelId}`);
     }
 
     // Idempotent port and access setup
@@ -174,13 +175,13 @@ async function startTunnel(port, options = {}) {
         output += data.toString();
       });
       hostProc.on('error', (err) => {
-        console.error(`[termbeam] Tunnel process error: ${err.message}`);
+        log.error(`Tunnel process error: ${err.message}`);
         clearTimeout(timeout);
         resolve(null);
       });
     });
   } catch (e) {
-    console.error(`[termbeam] Tunnel error: ${e.message}`);
+    log.error(`Tunnel error: ${e.message}`);
     return null;
   }
 }
@@ -205,11 +206,11 @@ function cleanupTunnel() {
   if (id) {
     tunnelId = null;
     if (isPersisted) {
-      console.log('[termbeam] Tunnel host stopped (tunnel preserved for reuse)');
+      log.info('Tunnel host stopped (tunnel preserved for reuse)');
     } else {
       try {
         execFileSync(devtunnelCmd, ['delete', id, '-f'], { stdio: 'pipe', timeout: 10000 });
-        console.log('[termbeam] Tunnel cleaned up');
+        log.info('Tunnel cleaned up');
       } catch {
         /* best effort — tunnel will expire on its own */
       }

package/src/websocket.js

@@ -1,3 +1,5 @@
+const log = require('./logger');
+
 function recalcPtySize(session) {
   let minCols = Infinity;
   let minRows = Infinity;
@@ -16,6 +18,23 @@ function recalcPtySize(session) {
 
 function setupWebSocket(wss, { auth, sessions }) {
   wss.on('connection', (ws, req) => {
+    const origin = req.headers.origin;
+    if (origin) {
+      try {
+        const originHost = new URL(origin).hostname;
+        const reqHost = (req.headers.host || '').split(':')[0];
+        if (originHost !== reqHost && originHost !== 'localhost' && reqHost !== 'localhost') {
+          log.warn(`WS: rejected cross-origin connection from ${origin}`);
+          ws.close(1008, 'Origin not allowed');
+          return;
+        }
+      } catch {
+        log.warn(`WS: rejected invalid origin: ${origin}`);
+        ws.close(1008, 'Invalid origin');
+        return;
+      }
+    }
+
     let authenticated = !auth.password;
     let attached = null;
 
@@ -35,9 +54,9 @@ function setupWebSocket(wss, { auth, sessions }) {
           if (msg.password === auth.password || auth.validateToken(msg.token)) {
             authenticated = true;
             ws.send(JSON.stringify({ type: 'auth_ok' }));
-            console.log('[termbeam] WS: auth success');
+            log.info('WS: auth success');
           } else {
-            console.warn('[termbeam] WS: auth failed');
+            log.warn('WS: auth failed');
             ws.send(JSON.stringify({ type: 'error', message: 'Unauthorized' }));
             ws.close();
           }
@@ -54,7 +73,7 @@ function setupWebSocket(wss, { auth, sessions }) {
           const session = sessions.get(msg.sessionId);
           if (!session) {
             ws.send(JSON.stringify({ type: 'error', message: 'Session not found' }));
-            console.warn(`[termbeam] WS: attach failed — session ${msg.sessionId} not found`);
+            log.warn(`WS: attach failed — session ${msg.sessionId} not found`);
             return;
           }
           attached = session;
@@ -63,7 +82,7 @@ function setupWebSocket(wss, { auth, sessions }) {
             ws.send(JSON.stringify({ type: 'output', data: session.scrollbackBuf }));
           }
           ws.send(JSON.stringify({ type: 'attached', sessionId: msg.sessionId }));
-          console.log(`[termbeam] Client attached to session ${msg.sessionId}`);
+          log.info(`Client attached to session ${msg.sessionId}`);
           return;
         }
 
@@ -80,7 +99,7 @@ function setupWebSocket(wss, { auth, sessions }) {
           }
         }
       } catch (err) {
-        console.warn('WS: dropped unparseable message:', err.message);
+        log.warn(`WS: dropped unparseable message: ${err.message}`);
       }
     });
 
@@ -88,7 +107,7 @@ function setupWebSocket(wss, { auth, sessions }) {
       if (attached) {
         attached.clients.delete(ws);
         recalcPtySize(attached);
-        console.log('[termbeam] Client detached');
+        log.info('Client detached');
       }
     });
   });