fix(security): harden error handling, add WS rate limiting, validate CLI args (#117)

Security hardening and code quality improvements from a 10-agent
parallel audit.

Sanitizes internal error messages leaked to API clients, adds WebSocket
auth rate limiting (5 attempts/min/IP matching HTTP auth), validates CLI
args (port range, empty password, log-level whitelist), adds response.ok
checks to all frontend fetch calls, fixes server shutdown to close
active WS connections, makes auth cleanup interval cancellable, uses
proper HTTP status codes (201/204), removes dead code, and fixes doc
inaccuracies.

Closes #116.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dorlugasigal

README.md

@@ -109,6 +109,7 @@ flowchart LR
 | `--port <port>`       | Server port                                     | `3456`         |
 | `--host <addr>`       | Bind address                                    | `127.0.0.1`    |
 | `--lan`               | Bind to all interfaces (LAN access)             | Off            |
+| `--public`            | Allow public tunnel access (no Microsoft login) | Off            |
 | `-i, --interactive`   | Interactive setup wizard                        | Off            |
 | `--log-level <level>` | Log verbosity (error/warn/info/debug)           | `info`         |
 

docs/api.md

@@ -116,7 +116,7 @@ All fields are optional. If `initialCommand` is provided, it will be sent to the
 
 The `shell` field is validated against the list of detected shells (see `GET /api/shells`). The `cwd` field must be an absolute path to an existing directory.
 
-**Response (200):**
+**Response (201):**
 
 ```json
 {
@@ -200,11 +200,7 @@ Scan a session's scrollback buffer for the last `localhost` or `127.0.0.1` URL a
 
 Kill and remove a session.
 
-**Response (200):**
-
-```json
-{ "ok": true }
-```
+**Response (204):** No content.
 
 **Response (404):**
 
@@ -298,7 +294,7 @@ Upload an image file. The request body is the raw image data with the appropriat
 
 - `Content-Type`: Must be an `image/*` type
 
-**Response (200):**
+**Response (201):**
 
 ```json
 { "id": "uuid", "url": "/uploads/uuid", "path": "/tmp/termbeam-uuid.png" }
@@ -338,7 +334,7 @@ Upload a file to a session's working directory. The request body is the raw file
 - `X-Filename`: Original filename (required)
 - `X-Target-Dir`: Override destination directory (optional, defaults to session cwd)
 
-**Response (200):**
+**Response (201):**
 
 ```json
 { "name": "script.sh", "path": "/home/user/project/script.sh", "size": 1024 }

docs/configuration.md

@@ -16,7 +16,7 @@ description: All TermBeam CLI flags and options — ports, passwords, tunnels, s
 | `--no-tunnel`         | Disable tunnel                                                                                                | —              |
 | `--persisted-tunnel`  | Create a reusable devtunnel URL (stable across restarts)                                                      | Off            |
 | `--public`            | Allow public tunnel access (no Microsoft login required)                                                      | Off            |
-| `--port <port>`       | Server port                                                                                                   | `3456`         |
+| `--port <port>`       | Server port (must be 1-65535)                                                                                 | `3456`         |
 | `--host <addr>`       | Bind address                                                                                                  | `127.0.0.1`    |
 | `--lan`               | Bind to all interfaces (LAN access)                                                                           | Off            |
 | `-i, --interactive`   | Interactive setup wizard — walks through password, port, access mode (tunnel type, visibility), and log level | Off            |

docs/running-in-background.md

@@ -50,6 +50,7 @@ The wizard checks if PM2 is installed (and offers to install it globally if not)
 | 5. **Working directory** | Default terminal directory | Default: current directory                                        |
 | 6. **Log level**         | Logging verbosity          | `info` (default), `debug`, `warn`, or `error`                     |
 | 7. **Boot auto-start**   | Start on system boot?      | Default: Yes — runs `pm2 startup`                                 |
+| 8. **Confirm**           | Review and proceed         | Proceed or cancel                                                 |
 
 If you choose **DevTunnel** access, a follow-up question asks whether the tunnel should be **private** (Microsoft login required) or **public** (anyone with the link). Choosing public with no password will auto-generate one for safety.
 

docs/security.md

@@ -147,7 +147,8 @@ Before running TermBeam, verify:
 ### Rate Limiting
 
 - Login endpoint limited to **5 attempts per minute** per IP
-- Returns HTTP 429 when exceeded
+- WebSocket auth limited to **5 attempts per minute** per IP
+- Returns HTTP 429 (or WebSocket close) when exceeded
 
 ### HTTP Security Headers
 

landing/src/main.js

@@ -31,7 +31,7 @@ const qrLines = [
 
 const infoLines = [
   '',
-  '  Beam your terminal to any device 📡  <span class="out-dim">v1.3.0</span>',
+  '  Beam your terminal to any device 📡  <span class="out-dim">v1.10.0</span>',
   '',
   '  Shell:    <span class="out-white">zsh</span>',
   '  Session:  <span class="out-white">termbeam</span>',

public/index.html

@@ -991,17 +991,22 @@ <h3>
       }
 
       async function loadSessions() {
-        const res = await fetch('/api/sessions');
-        const sessions = await res.json();
+        try {
+          const res = await fetch('/api/sessions');
+          if (!res.ok) {
+            console.error(`Failed to load sessions: ${res.status}`);
+            return;
+          }
+          const sessions = await res.json();
 
-        if (sessions.length === 0) {
-          listEl.innerHTML = '<div class="empty-state">No active sessions</div>';
-          return;
-        }
+          if (sessions.length === 0) {
+            listEl.innerHTML = '<div class="empty-state">No active sessions</div>';
+            return;
+          }
 
-        listEl.innerHTML = sessions
-          .map(
-            (s) => `
+          listEl.innerHTML = sessions
+            .map(
+              (s) => `
         <div class="swipe-wrap" data-session-id="${esc(s.id)}">
           <div class="swipe-delete">
             <button data-delete-id="${esc(s.id)}"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/><path d="M10 11v6"/><path d="M14 11v6"/><path d="M9 6V4a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2"/></svg><span>Delete</span></button>
@@ -1031,22 +1036,25 @@ <h3>
           </div>
         </div>
       `,
-          )
-          .join('');
+            )
+            .join('');
 
-        // Attach swipe handlers and click handlers after rendering
-        listEl.querySelectorAll('.swipe-wrap').forEach(initSwipe);
-        listEl.querySelectorAll('[data-delete-id]').forEach((btn) => {
-          btn.addEventListener('click', (e) => deleteSession(btn.dataset.deleteId, e));
-        });
-        listEl.querySelectorAll('[data-nav-id]').forEach((card) => {
-          card.addEventListener('click', () => {
-            location.href = '/terminal?id=' + encodeURIComponent(card.dataset.navId);
+          // Attach swipe handlers and click handlers after rendering
+          listEl.querySelectorAll('.swipe-wrap').forEach(initSwipe);
+          listEl.querySelectorAll('[data-delete-id]').forEach((btn) => {
+            btn.addEventListener('click', (e) => deleteSession(btn.dataset.deleteId, e));
           });
-        });
-        listEl.querySelectorAll('.dot[data-color]').forEach((dot) => {
-          dot.style.background = dot.dataset.color || 'var(--success)';
-        });
+          listEl.querySelectorAll('[data-nav-id]').forEach((card) => {
+            card.addEventListener('click', () => {
+              location.href = '/terminal?id=' + encodeURIComponent(card.dataset.navId);
+            });
+          });
+          listEl.querySelectorAll('.dot[data-color]').forEach((dot) => {
+            dot.style.background = dot.dataset.color || 'var(--success)';
+          });
+        } catch (err) {
+          console.error('Failed to load sessions:', err);
+        }
       }
 
       document.getElementById('new-session-btn').addEventListener('click', () => {
@@ -1085,13 +1093,21 @@ <h3>
         if (initialCommand) body.initialCommand = initialCommand;
         if (color) body.color = color;
 
-        const res = await fetch('/api/sessions', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(body),
-        });
-        const data = await res.json();
-        location.href = data.url;
+        try {
+          const res = await fetch('/api/sessions', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+          });
+          if (!res.ok) {
+            console.error(`Failed to create session: ${res.status}`);
+            return;
+          }
+          const data = await res.json();
+          location.href = data.url;
+        } catch (err) {
+          console.error('Failed to create session:', err);
+        }
       });
 
       // --- Shell detection ---
@@ -1101,6 +1117,7 @@ <h3>
         const shellSelect = document.getElementById('sess-shell');
         try {
           const res = await fetch('/api/shells');
+          if (!res.ok) throw new Error(`Failed to load shells: ${res.status}`);
           const data = await res.json();
           if (data.cwd) {
             document.getElementById('sess-cwd').placeholder = data.cwd;
@@ -1225,7 +1242,10 @@ <h3>
       document.getElementById('browse-btn').addEventListener('click', async () => {
         if (hubServerCwd === '/') {
           try {
-            const data = await fetch('/api/shells').then((r) => r.json());
+            const data = await fetch('/api/shells').then((r) => {
+              if (!r.ok) throw new Error(`${r.status}`);
+              return r.json();
+            });
             if (data.cwd) hubServerCwd = data.cwd;
           } catch {}
         }
@@ -1254,6 +1274,7 @@ <h3>
 
         try {
           const res = await fetch(`/api/dirs?q=${encodeURIComponent(dir + '/')}`);
+          if (!res.ok) throw new Error(`Failed to load directories: ${res.status}`);
           const data = await res.json();
           let items = '';
           // Add parent (..) entry unless at root
@@ -1310,7 +1331,10 @@ <h3>
 
       // Fetch version
       fetch('/api/version')
-        .then((r) => r.json())
+        .then((r) => {
+          if (!r.ok) throw new Error(`${r.status}`);
+          return r.json();
+        })
         .then((d) => {
           document.getElementById('version').textContent = 'v' + d.version;
         })

public/terminal.html

@@ -2476,7 +2476,14 @@ <h3>
 
       // ===== Init =====
       async function init() {
-        const sessionList = await fetch('/api/sessions').then((r) => r.json());
+        let sessionList = [];
+        try {
+          const res = await fetch('/api/sessions');
+          if (!res.ok) throw new Error(`${res.status}`);
+          sessionList = await res.json();
+        } catch (err) {
+          console.error('Failed to load sessions:', err);
+        }
         const initialId = new URLSearchParams(location.search).get('id');
 
         for (const s of sessionList) addSession(s);
@@ -2678,7 +2685,10 @@ <h3>
 
         // Version
         fetch('/api/version')
-          .then((r) => r.json())
+          .then((r) => {
+            if (!r.ok) throw new Error(`${r.status}`);
+            return r.json();
+          })
           .then((d) => {
             window._termbeamVersion = 'v' + d.version;
             document.getElementById('side-panel-version').textContent = 'v' + d.version;
@@ -3884,6 +3894,7 @@ <h3>
             const res = await fetch('/api/dirs?q=' + encodeURIComponent(q ? q + '/' : ''), {
               credentials: 'same-origin',
             });
+            if (!res.ok) throw new Error(`Failed to browse directories: ${res.status}`);
             const data = await res.json();
             if (!data.dirs || !data.dirs.length) return;
             browseDropdown = document.createElement('div');
@@ -3997,7 +4008,10 @@ <h3>
         document.getElementById('ns-browse-btn').addEventListener('click', async () => {
           if (serverCwd === '/') {
             try {
-              const data = await fetch('/api/shells').then((r) => r.json());
+              const data = await fetch('/api/shells').then((r) => {
+                if (!r.ok) throw new Error(`${r.status}`);
+                return r.json();
+              });
               if (data.cwd) serverCwd = data.cwd;
             } catch {}
           }
@@ -4025,6 +4039,7 @@ <h3>
           nsBrowserList.innerHTML = '<div class="browser-empty">Loading…</div>';
           try {
             const res = await fetch(`/api/dirs?q=${encodeURIComponent(dir + '/')}`);
+            if (!res.ok) throw new Error(`Failed to load directories: ${res.status}`);
             const data = await res.json();
             let items = '';
             // Add parent (..) entry unless at root
@@ -4082,7 +4097,10 @@ <h3>
         if (shellsLoaded) return;
         const sel = document.getElementById('ns-shell');
         try {
-          const data = await fetch('/api/shells').then((r) => r.json());
+          const data = await fetch('/api/shells').then((r) => {
+            if (!r.ok) throw new Error(`${r.status}`);
+            return r.json();
+          });
           if (data.cwd) {
             serverCwd = data.cwd;
             document.getElementById('ns-cwd').placeholder = data.cwd;
@@ -4140,10 +4158,16 @@ <h3>
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(body),
           });
+          if (!res.ok) {
+            console.error(`Failed to create session: ${res.status}`);
+            return;
+          }
           const data = await res.json();
 
           // Fetch full session list to get the new session data
-          const list = await fetch('/api/sessions').then((r) => r.json());
+          const listRes = await fetch('/api/sessions');
+          if (!listRes.ok) throw new Error(`Failed to list sessions: ${listRes.status}`);
+          const list = await listRes.json();
           const newSession = list.find((s) => s.id === data.id);
           if (newSession) {
             addSession(newSession);
@@ -4163,7 +4187,9 @@ <h3>
       function startPolling() {
         setInterval(async () => {
           try {
-            const list = await fetch('/api/sessions').then((r) => r.json());
+            const pollRes = await fetch('/api/sessions');
+            if (!pollRes.ok) throw new Error(`${pollRes.status}`);
+            const list = await pollRes.json();
             const serverIds = new Set(list.map((s) => s.id));
 
             // Add new sessions created elsewhere

src/auth.js

@@ -177,7 +177,7 @@ function createAuth(password) {
   const shareTokens = new Map(); // share tokens: token -> expiry
 
   // Periodically clean up expired tokens and stale rate-limit entries
-  setInterval(
+  const cleanupInterval = setInterval(
     () => {
       const now = Date.now();
       for (const [token, expiry] of tokens) {
@@ -296,6 +296,7 @@ function createAuth(password) {
     rateLimit,
     parseCookies,
     loginHTML: LOGIN_HTML,
+    cleanup: () => clearInterval(cleanupInterval),
   };
 }
 

src/cli.js

@@ -270,6 +270,10 @@ function parseArgs() {
       publicTunnel = true;
     } else if (args[i].startsWith('--password=')) {
       password = args[i].split('=')[1];
+      if (!password) {
+        console.error('Error: --password= requires a non-empty value\n');
+        process.exit(1);
+      }
       explicitPassword = true;
     } else if (args[i] === '--help' || args[i] === '-h') {
       printHelp();
@@ -286,6 +290,10 @@ function parseArgs() {
       explicitPassword = true;
     } else if (args[i] === '--port' && args[i + 1]) {
       port = parseInt(args[++i], 10);
+      if (!Number.isFinite(port) || port < 1 || port > 65535) {
+        console.error('Error: --port must be a number between 1 and 65535\n');
+        process.exit(1);
+      }
     } else if (args[i] === '--lan') {
       host = '0.0.0.0';
     } else if (args[i] === '--host' && args[i + 1]) {
@@ -307,6 +315,12 @@ function parseArgs() {
     }
   }
 
+  const validLogLevels = ['error', 'warn', 'info', 'debug'];
+  if (!validLogLevels.includes(logLevel)) {
+    console.error(`Error: --log-level must be one of: ${validLogLevels.join(', ')}\n`);
+    process.exit(1);
+  }
+
   // Default: auto-generate password if none specified
   if (!explicitPassword && !password) {
     password = crypto.randomBytes(16).toString('base64url');