@flame0510/project-aether 1.7.0 → 1.9.0

package/server.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * Rev4a web server — Next.js plus the container terminal on the same port.
+ *
+ * `rev4a serve` runs this instead of `next start`. Every HTTP request goes to Next.js
+ * unchanged. The one addition is the WebSocket upgrade on `/api/terminal-ws`: the browser
+ * opens the terminal on the dashboard's own host and port, and this server forwards it to
+ * the terminal server (terminal-ws-server.js, 127.0.0.1 only) — so the terminal works with
+ * no reverse proxy in front, locally and on a plain-IP VPS. Before forwarding it checks:
+ *
+ *   1. the session cookie (`rev4a_token`, the same JWT the dashboard pages require);
+ *   2. the Origin header matches the host the browser addressed — `Host`, or
+ *      `X-Forwarded-Host` behind a proxy that rewrites Host — so a page on another site
+ *      cannot open a shell with the user's cookie (cross-site WebSocket hijacking; a
+ *      browser cannot set X-Forwarded-Host on a WebSocket, so trusting it opens nothing);
+ *   3. the container name is well formed (the terminal server checks it exists and runs).
+ *
+ * The forwarded request carries a per-boot secret (REV4A_TERMINAL_SECRET, generated by
+ * `rev4a serve` for both processes) and no cookie; the terminal server refuses anything
+ * without that secret, so reaching 127.0.0.1:3741 directly gives nothing.
+ */
+'use strict';
+
+const http = require('http');
+const net = require('net');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const next = require('next');
+
+const PORT = parseInt(process.env.PORT || '3740', 10);
+const TERMINAL_WS_PORT = parseInt(process.env.TERMINAL_WS_PORT || '3741', 10);
+const TERMINAL_SECRET = process.env.REV4A_TERMINAL_SECRET || '';
+const TERMINAL_PATH = '/api/terminal-ws';
+/** Docker container names and ids: what `docker exec` accepts, nothing a shell could read. */
+const CONTAINER_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/;
+
+// Same data directory rule as lib/rev4a-paths.ts, for the JWT secret fallback below.
+const DATA_DIR = process.env.REV4A_DATA_DIR
+  || (process.platform === 'win32'
+    ? path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'rev4a')
+    : path.join(os.homedir(), '.config', 'rev4a'));
+
+/** REV4A_JWT_SECRET from the environment, else from .env — the rule lib/rev4a-auth.js follows. */
+function jwtSecret() {
+  if (process.env.REV4A_JWT_SECRET) return process.env.REV4A_JWT_SECRET;
+  try {
+    const m = /^REV4A_JWT_SECRET=(.*)$/m.exec(fs.readFileSync(path.join(DATA_DIR, '.env'), 'utf8'));
+    return m ? m[1].trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+function cookieValue(header, name) {
+  for (const part of String(header || '').split(';')) {
+    const i = part.indexOf('=');
+    if (i > 0 && part.slice(0, i).trim() === name) {
+      try {
+        return decodeURIComponent(part.slice(i + 1).trim());
+      } catch {
+        return ''; // malformed escape: treated as no cookie (401)
+      }
+    }
+  }
+  return '';
+}
+
+/** Answer an upgrade with a plain HTTP status and close — the browser sees a failed connection. */
+function refuse(socket, status, reason) {
+  if (socket.writable) {
+    socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+  }
+  socket.destroy();
+}
+
+let jwtVerify = null;
+
+async function authorised(req) {
+  const token = cookieValue(req.headers.cookie, 'rev4a_token');
+  const secret = jwtSecret();
+  if (!token || !secret) return false;
+  try {
+    jwtVerify = jwtVerify || (await import('jose')).jwtVerify;
+    await jwtVerify(token, new TextEncoder().encode(secret));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** host[:port] lower-cased, without the scheme's default port (`x:80` on http is `x`). */
+function normaliseHost(host, protocol) {
+  const h = String(host || '').trim().toLowerCase();
+  const port = protocol === 'https:' ? ':443' : ':80';
+  return h.endsWith(port) ? h.slice(0, -port.length) : h;
+}
+
+function sameOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return false; // browsers always send it on a WebSocket handshake
+  let url;
+  try {
+    url = new URL(origin);
+  } catch {
+    return false;
+  }
+  const want = normaliseHost(url.host, url.protocol);
+  const forwarded = String(req.headers['x-forwarded-host'] || '').split(',')[0];
+  return [req.headers.host, forwarded].some((h) => h && normaliseHost(h, url.protocol) === want);
+}
+
+/** Replay the handshake to the terminal server — without the cookie, with the secret — then splice the sockets. */
+function forwardToTerminal(req, socket, head) {
+  const upstream = net.connect(TERMINAL_WS_PORT, '127.0.0.1');
+  let connected = false;
+  // Until the terminal server answers the handshake: a hung server must not hold the browser forever.
+  upstream.setTimeout(10000, () => (connected ? close() : refuse(socket, 504, 'Gateway Timeout')));
+  upstream.once('data', () => upstream.setTimeout(0));
+  upstream.on('connect', () => {
+    connected = true;
+    const lines = [`${req.method} ${req.url} HTTP/1.1`];
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+      const name = req.rawHeaders[i];
+      const lower = name.toLowerCase();
+      if (lower === 'cookie' || lower === 'x-rev4a-terminal-secret') continue;
+      lines.push(`${name}: ${req.rawHeaders[i + 1]}`);
+    }
+    lines.push(`X-Rev4a-Terminal-Secret: ${TERMINAL_SECRET}`);
+    upstream.write(lines.join('\r\n') + '\r\n\r\n');
+    if (head && head.length) upstream.write(head);
+    socket.pipe(upstream).pipe(socket);
+  });
+  const close = () => { socket.destroy(); upstream.destroy(); };
+  // Before the splice an error is answered as HTTP; after it, the stream is WebSocket frames.
+  upstream.on('error', () => (connected ? close() : refuse(socket, 502, 'Bad Gateway')));
+  upstream.on('close', close);
+  socket.on('error', close);
+  socket.on('close', close);
+}
+
+async function onUpgrade(req, socket, head) {
+  socket.on('error', () => socket.destroy());
+  let url;
+  try {
+    url = new URL(req.url || '/', 'http://localhost');
+  } catch {
+    return refuse(socket, 400, 'Bad Request');
+  }
+  // Production Next.js takes no other upgrade (hot reload is a `next dev` feature).
+  if (url.pathname !== TERMINAL_PATH) return refuse(socket, 404, 'Not Found');
+  if (!sameOrigin(req)) return refuse(socket, 403, 'Forbidden');
+  if (!(await authorised(req))) return refuse(socket, 401, 'Unauthorized');
+  if (!CONTAINER_RE.test(url.searchParams.get('id') || '')) return refuse(socket, 400, 'Bad Request');
+  if (!TERMINAL_SECRET) return refuse(socket, 503, 'Service Unavailable');
+  forwardToTerminal(req, socket, head);
+}
+
+async function main() {
+  const app = next({ dev: false, dir: __dirname, port: PORT });
+  await app.prepare();
+  const handle = app.getRequestHandler();
+  const server = http.createServer((req, res) => handle(req, res));
+  server.on('upgrade', (req, socket, head) => {
+    onUpgrade(req, socket, head).catch(() => socket.destroy());
+  });
+  server.listen(PORT, () => {
+    console.log(`[rev4a] Ready on port ${PORT} (terminal on ${TERMINAL_PATH} → 127.0.0.1:${TERMINAL_WS_PORT})`);
+    if (!TERMINAL_SECRET) console.log('[rev4a] REV4A_TERMINAL_SECRET is not set: the terminal is disabled (start with `rev4a serve`).');
+  });
+  // Open terminal sockets keep close() waiting; give them a moment, then go.
+  const stop = () => {
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 3000).unref();
+  };
+  process.on('SIGTERM', stop);
+  process.on('SIGINT', stop);
+}
+
+main().catch((err) => {
+  console.error('[rev4a] Failed to start:', err);
+  process.exit(1);
+});

package/terminal-ws-server.js

@@ -1,139 +1,372 @@
 // Terminal WebSocket Server — standalone
-// Uses node-pty for real PTY with docker exec - fully interactive
+// Uses node-pty for real PTY with docker exec - fully interactive.
+//
+// Reached only through server.js (the dashboard's own port), which checks the session
+// cookie and the Origin and forwards the handshake with REV4A_TERMINAL_SECRET. This
+// server listens on 127.0.0.1 and refuses any handshake without that secret.
+//
+// Sessions outlive a dropped connection: the browser names its session (`session=<uuid>`
+// in the URL); when the socket drops the shell keeps running for DETACHED_GRACE_MS, its
+// output queued, and a reconnect with the same id picks it up where it was. A deliberate
+// close (code 1000), the shell exiting, DETACHED_GRACE_MS without a client, or
+// IDLE_TIMEOUT_MS without input or output ends it — and ending it kills the shell and
+// everything it started *inside the container*: killing the host's `docker exec` client
+// alone leaves them running (Docker does not stop an exec when its client goes away).
 const { WebSocketServer } = require('ws');
 const http = require('http');
 const path = require('path');
+const { execFile } = require('child_process');
+const { createHash, randomUUID, timingSafeEqual } = require('crypto');
 
 const pty = require(path.resolve(__dirname, 'node_modules/node-pty'));
 
-const PORT = parseInt(process.env.TERMINAL_WS_PORT || '3741', 10);
-const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
-const IDLE_RESET_TIMEOUT_MS = 60 * 1000;
+// node-pty 1.1 ships its macOS `spawn-helper` without the execute bit, and every spawn
+// then fails with "posix_spawnp failed" (Linux does not use the helper). Restore it once.
+if (process.platform === 'darwin') {
+  const fs = require('fs');
+  const prebuilds = path.resolve(__dirname, 'node_modules/node-pty/prebuilds');
+  try {
+    for (const arch of fs.readdirSync(prebuilds)) {
+      const helper = path.join(prebuilds, arch, 'spawn-helper');
+      if (fs.existsSync(helper) && (fs.statSync(helper).mode & 0o111) === 0) fs.chmodSync(helper, 0o755);
+    }
+  } catch (err) {
+    console.log(`[TerminalWS] Could not make node-pty's spawn-helper executable: ${err.message}`);
+  }
+}
 
-const server = http.createServer((_req, res) => {
-  res.writeHead(426, { 'Content-Type': 'text/plain' });
-  res.end('Use WebSocket');
-});
+const PORT = parseInt(process.env.TERMINAL_WS_PORT || '3741', 10);
+const SECRET = process.env.REV4A_TERMINAL_SECRET || '';
+const CONTAINER_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/;
+const SESSION_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Ping interval: keeps idle links open through NAT and finds dead peers. */
+const HEARTBEAT_MS = 25 * 1000;
+/** How long a shell waits for its browser to come back after the connection drops. */
+const DETACHED_GRACE_MS = 2 * 60 * 1000;
+/** A shell with no input and no output for this long is ended. */
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+/** Output kept for a detached session, replayed on reattach (the newest part, in characters). */
+const DETACHED_BUFFER_CHARS = 64 * 1024;
+/** Live shells at once; a runaway loop of new tabs cannot fill the host with `docker exec`. */
+const MAX_SESSIONS = 20;
+/** Keystrokes queued while the container is checked (before the shell exists). */
+const MAX_EARLY_INPUT_CHARS = 64 * 1024;
+/** Backpressure: the shell is paused while this much output waits for a slow client. */
+const PAUSE_ABOVE_BYTES = 1024 * 1024;
+const RESUME_BELOW_BYTES = 256 * 1024;
+/** Marks the shell's processes inside the container, so they can be found and ended. */
+const MARKER = 'REV4A_TERMINAL_SESSION';
 
-const wss = new WebSocketServer({ server });
+// Close codes the client acts on: it stops retrying and says why.
+const CLOSE_EXITED = 4001; // the shell exited (`exit`, Ctrl-D)
+const CLOSE_ENDED = 4002; // idle too long, or a resume found the shell already gone
+const CLOSE_REPLACED = 4003; // the same session was opened in another tab
+const CLOSE_NOT_FOUND = 4404; // no such container
+const CLOSE_NOT_RUNNING = 4409; // the container is stopped
+const CLOSE_NO_SHELL = 4410; // neither bash nor sh in the container
+const CLOSE_TOO_MANY = 4429; // MAX_SESSIONS shells already open
+const CLOSE_SPAWN_FAILED = 4500; // the PTY could not be started on this host
 
-wss.on('connection', (ws, req) => {
-  const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
-  const containerId = url.searchParams.get('id');
+function secretMatches(supplied) {
+  if (!SECRET || typeof supplied !== 'string') return false;
+  const digest = (v) => createHash('sha256').update(v, 'utf8').digest();
+  return timingSafeEqual(digest(supplied), digest(SECRET));
+}
 
-  if (!containerId) {
-    ws.send(`\r\n[Error: Missing container id]\r\n`);
-    ws.close();
-    return;
+/** A resize message from the client ({"type":"resize","cols":n,"rows":n}), or null. */
+function parseResize(msg) {
+  if (!msg.startsWith('{"type":"resize"')) return null;
+  try {
+    const { type, cols, rows } = JSON.parse(msg);
+    const ok = (n) => Number.isInteger(n) && n >= 2 && n <= 1000;
+    return type === 'resize' && ok(cols) && ok(rows) ? { cols, rows } : null;
+  } catch {
+    return null;
   }
+}
 
-  let term = null;
-  let idleTimer = setTimeout(() => {
-    ws.send('\r\n[Session timeout: 30 minutes]\r\n');
-    try { ws.close(); } catch {}
-  }, SESSION_TIMEOUT_MS);
-
-  function resetIdleTimer() {
-    clearTimeout(idleTimer);
-    idleTimer = setTimeout(() => {
-      ws.send('\r\n[Session timeout: 30 minutes]\r\n');
-      try { ws.close(); } catch {}
-    }, SESSION_TIMEOUT_MS);
-  }
+/** 'running' | 'stopped' | 'missing' — from `docker inspect`, argv only. */
+function containerState(id) {
+  return new Promise((resolve) => {
+    execFile('docker', ['inspect', '-f', '{{.State.Running}}', id], { timeout: 10000 }, (err, stdout) => {
+      if (err) return resolve('missing');
+      resolve(String(stdout).trim() === 'true' ? 'running' : 'stopped');
+    });
+  });
+}
 
-  try {
-    term = pty.spawn('docker', ['exec', '-it', containerId, 'env', 'TERM=xterm-256color', 'bash'], {
-      name: 'xterm-256color',
-      cols: 80,
-      rows: 30,
+/** bash when the container has it, else sh; null when it has neither. */
+function pickShell(id) {
+  return new Promise((resolve) => {
+    execFile('docker', ['exec', id, 'sh', '-c', 'command -v bash || command -v sh'], { timeout: 10000 }, (err, stdout) => {
+      const found = String(stdout || '').trim().split('\n')[0];
+      resolve(err || !found ? null : found);
     });
-  } catch (err) {
-    ws.send(`\r\n[Error: ${err.message}]\r\n`);
-    ws.close();
-    clearTimeout(idleTimer);
-    return;
+  });
+}
+
+// Ends every process in the container that carries the session's marker — the shell and
+// whatever it started (children inherit the environment): SIGHUP first, as a terminal
+// hangup would, then SIGKILL for what ignored it. The session id is passed as an argument,
+// never interpolated into the script.
+const KILL_SCRIPT = [
+  'm="$1"',
+  'hit() { for p in /proc/[0-9]*; do tr "\\0" "\\n" < "$p/environ" 2>/dev/null | grep -qx "$m" && echo "${p#/proc/}"; done; }',
+  'pids=$(hit); [ -n "$pids" ] || exit 0',
+  'kill -HUP $pids 2>/dev/null; sleep 1',
+  'pids=$(hit); [ -n "$pids" ] && kill -KILL $pids 2>/dev/null; exit 0',
+].join('\n');
+
+function killInContainer(containerId, sessionId) {
+  execFile('docker', ['exec', containerId, 'sh', '-c', KILL_SCRIPT, 'rev4a-kill', `${MARKER}=${sessionId}`], { timeout: 15000 }, (err) => {
+    if (err) console.log(`[TerminalWS] Could not end session ${sessionId.slice(0, 8)} in ${containerId}: ${err.message.split('\n')[0]}`);
+  });
+}
+
+/** Live shells by session id. */
+const sessions = new Map();
+/** Shells being started, by session id: a second socket for the same id waits for it. */
+const starting = new Map();
+
+function closeSocket(ws, code, reason) {
+  if (ws && (ws.readyState === ws.OPEN || ws.readyState === ws.CONNECTING)) {
+    try { ws.close(code, String(reason).slice(0, 120)); } catch {}
   }
+}
+
+function endSession(session, code, reason) {
+  if (!sessions.has(session.id)) return;
+  sessions.delete(session.id);
+  clearTimeout(session.detachTimer);
+  clearTimeout(session.flushTimer);
+  clearTimeout(session.drainTimer);
+  try { session.term.kill(); } catch {}
+  killInContainer(session.containerId, session.id);
+  closeSocket(session.ws, code, reason);
+}
 
-  // PTY output → WebSocket.
-  // Use a queue + micro-delay to avoid flooding xterm.js with one giant chunk.
-  let outputBuf = '';
-  let outputTimer = null;
-
-  function flushOutput() {
-    outputTimer = null;
-    if (!outputBuf) return;
-    if (ws.readyState !== ws.OPEN) { outputBuf = ''; return; }
-    ws.send(outputBuf);
-    outputBuf = '';
+/** Keep the newest DETACHED_BUFFER_CHARS, cut at a line start so the replay begins cleanly. */
+function trimQueued(out) {
+  if (out.length <= DETACHED_BUFFER_CHARS) return out;
+  const tail = out.slice(-DETACHED_BUFFER_CHARS);
+  const nl = tail.indexOf('\n');
+  return nl >= 0 && nl < 4096 ? tail.slice(nl + 1) : tail;
+}
+
+/** Resume a paused shell once the client has taken most of what was sent. */
+function watchDrain(session) {
+  clearTimeout(session.drainTimer);
+  session.drainTimer = setTimeout(() => {
+    const ws = session.ws;
+    if (!sessions.has(session.id)) return;
+    if (!ws || ws.readyState !== ws.OPEN || ws.bufferedAmount < RESUME_BELOW_BYTES) {
+      session.paused = false;
+      try { session.term.resume(); } catch {}
+      return;
+    }
+    watchDrain(session);
+  }, 50);
+}
+
+/** Send the coalesced output (at most every 10 ms: a DOM-friendly rate under a flood). */
+function flush(session) {
+  session.flushTimer = null;
+  if (!session.out) return;
+  const ws = session.ws;
+  if (ws && ws.readyState === ws.OPEN) {
+    ws.send(session.out);
+    session.out = '';
+    if (!session.paused && ws.bufferedAmount > PAUSE_ABOVE_BYTES) {
+      session.paused = true;
+      try { session.term.pause(); } catch {}
+      watchDrain(session);
+    }
+  } else {
+    session.out = trimQueued(session.out);
   }
+}
 
+function startSession(id, containerId, shell, size) {
+  const term = pty.spawn(
+    'docker',
+    ['exec', '-it', '-e', `${MARKER}=${id}`, containerId, 'env', 'TERM=xterm-256color', shell],
+    { name: 'xterm-256color', cols: size.cols, rows: size.rows },
+  );
+  const session = {
+    id, containerId, term, ws: null, out: '',
+    flushTimer: null, detachTimer: null, drainTimer: null, paused: false, lastActivity: Date.now(),
+  };
+  sessions.set(id, session);
   term.onData((data) => {
-    if (!data) return;
-    outputBuf += data;
-    // Flush every 10ms max (roughly 30-40 chunks/sec — safe for DOM renderer)
-    if (!outputTimer) {
-      outputTimer = setTimeout(flushOutput, 10);
-    }
-    // If buffer grows huge, flush immediately in chunks
-    if (outputBuf.length > 4000) {
-      // Split into 2k chunks
-      while (outputBuf.length > 2000) {
-        const chunk = outputBuf.slice(0, 2000);
-        outputBuf = outputBuf.slice(2000);
-        if (ws.readyState === ws.OPEN) ws.send(chunk);
-      }
+    session.lastActivity = Date.now();
+    session.out += data;
+    if (session.ws && session.ws.readyState === session.ws.OPEN) {
+      if (!session.flushTimer) session.flushTimer = setTimeout(() => flush(session), 10);
+    } else {
+      session.out = trimQueued(session.out);
     }
   });
+  term.onExit(({ exitCode }) => {
+    flush(session);
+    endSession(session, CLOSE_EXITED, `The shell exited (code ${exitCode})`);
+  });
+  return session;
+}
 
-  // WebSocket input → PTY
-  ws.on('message', (data) => {
-    resetIdleTimer();
-    if (!term) return;
+/**
+ * Bind a socket to a session: input and resizes go to the shell, queued output is sent.
+ * `size` is applied only when the client sent one — a reattach must not squeeze the shell
+ * to the 80×30 default and back.
+ */
+function attach(session, ws, size, earlyInput) {
+  if (session.ws && session.ws !== ws) closeSocket(session.ws, CLOSE_REPLACED, 'This session was opened in another tab');
+  session.ws = ws;
+  clearTimeout(session.detachTimer);
+  session.detachTimer = null;
+  session.lastActivity = Date.now();
+  if (size) {
+    try { session.term.resize(size.cols, size.rows); } catch {}
+  }
+  for (const input of earlyInput) session.term.write(input);
+  flush(session);
 
+  ws.on('message', (data) => {
+    if (session.ws !== ws) return;
+    session.lastActivity = Date.now();
     const msg = data.toString();
-
-    // Handle resize message from client
-    if (msg.startsWith('{"type":"resize"}') || msg.startsWith('{"type":"resize"') && msg.includes('"cols"')) {
-      try {
-        const parsed = JSON.parse(msg);
-        if (parsed.type === 'resize' && parsed.cols && parsed.rows) {
-          term.resize(parsed.cols, parsed.rows);
-        }
-      } catch {}
+    const resize = parseResize(msg);
+    if (resize) {
+      try { session.term.resize(resize.cols, resize.rows); } catch {}
       return;
     }
-
-    term.write(msg);
+    session.term.write(msg);
   });
-
-  term.onExit(({ exitCode, signal }) => {
-    clearTimeout(idleTimer);
-    if (ws.readyState === ws.OPEN) {
-      ws.send(`\r\n[Process exited with code ${exitCode}]\r\n`);
-      ws.close();
-    }
+  ws.on('close', (code) => {
+    if (session.ws !== ws) return;
+    session.ws = null;
+    // 1000 is the page closing the terminal on purpose; anything else may come back.
+    if (code === 1000) return endSession(session, 1000, 'Closed');
+    session.detachTimer = setTimeout(() => endSession(session, CLOSE_ENDED, 'Disconnected for too long'), DETACHED_GRACE_MS);
   });
+}
 
-  ws.on('close', () => {
-    clearTimeout(idleTimer);
-    if (term) term.kill('SIGTERM');
-  });
+const server = http.createServer((_req, res) => {
+  res.writeHead(426, { 'Content-Type': 'text/plain' });
+  res.end('Use WebSocket');
+});
+
+const wss = new WebSocketServer({
+  server,
+  maxPayload: 1024 * 1024, // keystrokes and pastes, not files
+  verifyClient: ({ req }, done) => {
+    if (secretMatches(req.headers['x-rev4a-terminal-secret'])) return done(true);
+    done(false, 401, 'Unauthorized');
+  },
+});
 
-  ws.on('error', () => {
-    clearTimeout(idleTimer);
-    if (term) term.kill('SIGTERM');
+// Heartbeat: every connection must answer a ping within one interval, or it is dropped
+// (its session then waits DETACHED_GRACE_MS). Idle sessions end here too.
+const heartbeat = setInterval(() => {
+  for (const ws of wss.clients) {
+    if (ws.isAlive === false) { ws.terminate(); continue; }
+    ws.isAlive = false;
+    try { ws.ping(); } catch {}
+  }
+  const now = Date.now();
+  for (const session of sessions.values()) {
+    if (now - session.lastActivity > IDLE_TIMEOUT_MS) endSession(session, CLOSE_ENDED, 'Ended after 30 minutes without activity');
+  }
+}, HEARTBEAT_MS);
+
+/** Start the shell for a new session id (container checked first), or null after closing `ws` with the reason. */
+async function createSession(ws, sessionId, containerId, size) {
+  if (sessions.size + starting.size >= MAX_SESSIONS) {
+    closeSocket(ws, CLOSE_TOO_MANY, `${MAX_SESSIONS} terminals are already open — close one first`);
+    return null;
+  }
+  const state = await containerState(containerId);
+  if (state === 'missing') { closeSocket(ws, CLOSE_NOT_FOUND, `No container named ${containerId}`); return null; }
+  if (state !== 'running') { closeSocket(ws, CLOSE_NOT_RUNNING, `${containerId} is not running — start it first`); return null; }
+  const shell = await pickShell(containerId);
+  if (!shell) { closeSocket(ws, CLOSE_NO_SHELL, `${containerId} has no bash or sh`); return null; }
+  try {
+    return startSession(sessionId, containerId, shell, size());
+  } catch (err) {
+    closeSocket(ws, CLOSE_SPAWN_FAILED, `Could not start the shell: ${err.message}`);
+    return null;
+  }
+}
+
+wss.on('connection', async (ws, req) => {
+  ws.isAlive = true;
+  ws.on('pong', () => { ws.isAlive = true; });
+  ws.on('error', () => {});
+
+  // The browser sends its size (and may type) as soon as the socket opens, while the checks
+  // below still run: keep the last size and the input, and apply them on attach.
+  let attached = false;
+  let clientSize = null;
+  const earlyInput = [];
+  let earlyChars = 0;
+  ws.on('message', (data) => {
+    if (attached) return;
+    const msg = data.toString();
+    const resize = parseResize(msg);
+    if (resize) clientSize = resize;
+    else if (earlyChars + msg.length <= MAX_EARLY_INPUT_CHARS) { earlyInput.push(msg); earlyChars += msg.length; }
   });
 
-  term.write('\n');
-  ws.send(`\r\n[Connected to container: ${containerId}]\r\n`);
+  const url = new URL(req.url || '/', 'http://localhost');
+  const containerId = url.searchParams.get('id') || '';
+  const requested = url.searchParams.get('session') || '';
+  // `resume=1`: the page is reconnecting to a shell it had — if that shell is gone, say so
+  // instead of silently handing over a new one.
+  const resuming = url.searchParams.get('resume') === '1';
+  const sessionId = SESSION_RE.test(requested) ? requested.toLowerCase() : randomUUID();
+
+  if (!CONTAINER_RE.test(containerId)) return closeSocket(ws, CLOSE_NOT_FOUND, 'Invalid container name');
+
+  // Another socket is starting this very session (a duplicated tab while connecting): wait for it.
+  if (starting.has(sessionId)) await starting.get(sessionId);
+
+  const existing = sessions.get(sessionId);
+  if (existing && existing.containerId === containerId) {
+    if (ws.readyState !== ws.OPEN) return;
+    attached = true;
+    return attach(existing, ws, clientSize, earlyInput.splice(0));
+  }
+  if (resuming) {
+    return closeSocket(ws, CLOSE_ENDED, 'The previous shell has ended (disconnected for more than 2 minutes, or Rev4a restarted)');
+  }
+
+  // A session id already used for another container starts fresh under a new id.
+  const id = existing ? randomUUID() : sessionId;
+  const creation = createSession(ws, id, containerId, () => clientSize || { cols: 80, rows: 30 });
+  starting.set(id, creation);
+  const session = await creation.finally(() => starting.delete(id));
+  if (!session) return;
+  if (ws.readyState !== ws.OPEN) {
+    // The browser left while the shell started: keep it for a reconnect, as after a drop.
+    session.detachTimer = setTimeout(() => endSession(session, CLOSE_ENDED, 'Disconnected for too long'), DETACHED_GRACE_MS);
+    return;
+  }
+  attached = true;
+  attach(session, ws, null, earlyInput.splice(0));
 });
 
 server.listen(PORT, '127.0.0.1', () => {
   console.log(`[TerminalWS] Server listening on ws://127.0.0.1:${PORT}`);
 });
 
+if (!SECRET) console.log('[TerminalWS] REV4A_TERMINAL_SECRET is not set: every connection will be refused (start with `rev4a serve`).');
+
 process.on('SIGTERM', () => {
   console.log('[TerminalWS] Shutting down...');
+  clearInterval(heartbeat);
+  for (const session of sessions.values()) endSession(session, 1001, 'Server shutting down');
+  for (const ws of wss.clients) ws.terminate();
   wss.close();
-  server.close(() => process.exit(0));
+  // Give the in-container clean-ups (`docker exec … kill`) a moment before exiting.
+  setTimeout(() => server.close(() => process.exit(0)), 1500).unref();
+  setTimeout(() => process.exit(0), 3000).unref();
 });