herdr-remote-relay 0.2.1 → 0.2.3

package/src/relay-server.js

@@ -11,13 +11,26 @@ const { loadRelayConfig, defaultStateDir, PACKAGE_ROOT } = require('./relay-conf
 const { AuthStore } = require('./auth-store');
 const { RelayMetrics } = require('./metrics');
 const { unpackStreamFrame, packStreamFrame, sanitizeTerminalPalette } = require('./stream-frame');
-const { isWheelOnlyInput } = require('./scroll-input');
 const { ensureDir } = require('./state');
 
 const VERSION = require('../package.json').version;
 const { PROTOCOL_VERSION } = require('./stream-frame');
 const MAX_DIMENSION = 500;
 
+/**
+ * How much recent PTY output the relay keeps per shared session.
+ *
+ * A browser that joins a session already in progress has missed everything
+ * printed before it arrived. Replaying the tail of the stream is what makes
+ * "every window shows the same thing" true on the *first* frame rather than
+ * only after the next repaint.
+ */
+const SESSION_REPLAY_BYTES = 512 * 1024;
+
+/** Never shrink a shared grid below something a program can still draw in. */
+const MIN_SHARED_COLS = 20;
+const MIN_SHARED_ROWS = 6;
+
 function randomId(prefix) {
   return `${prefix}-${crypto.randomBytes(9).toString('base64url')}`;
 }
@@ -70,11 +83,24 @@ function tokenMatches(candidate, expected) {
 
 class RelayServer {
   constructor(config = loadRelayConfig().config, options = {}) {
-    this.config = config;
+    this.config = {
+      ...config,
+      relay: {
+        ...config.relay,
+        maxHosts: config.relay?.maxHosts ?? 1024,
+        maxPendingHandshakes: config.relay?.maxPendingHandshakes ?? 1024,
+        maxBufferedBytesPerClient: config.relay?.maxBufferedBytesPerClient ?? 4 * 1024 * 1024,
+        hostReconnectGraceMs: config.relay?.hostReconnectGraceMs ?? 30 * 1000,
+      },
+    };
+    config = this.config;
     this.relayMode = config.relay?.mode === 'local' ? 'local' : 'remote';
     this.hosts = new Map();
     this.clients = new Map();
     this.pairAttempts = new Map();
+    this.clientHandshakeAttempts = new Map();
+    this.hostHandshakeAttempts = new Map();
+    this.pendingHandshakes = new Set();
     this.startedAt = Date.now();
     this.metrics = options.metrics || new RelayMetrics({ version: VERSION, protocolVersion: PROTOCOL_VERSION });
     this.stateFile = options.stateFile || config.auth?.stateFile || path.join(defaultStateDir(), 'relay-auth.json');
@@ -89,7 +115,14 @@ class RelayServer {
       password: this.password,
     });
     this.server = http.createServer((req, res) => this.handleHttp(req, res));
-    this.wss = new WebSocketServer({ noServer: true, clientTracking: false, maxPayload: config.relay.maxPayloadBytes });
+    this.wss = new WebSocketServer({
+      noServer: true,
+      clientTracking: false,
+      maxPayload: config.relay.maxPayloadBytes,
+      // Terminal data is already compact and latency-sensitive. Compression
+      // adds CPU and buffering without helping the usual ANSI payloads.
+      perMessageDeflate: false,
+    });
     this.heartbeatTimer = null;
     this.cleanupTimer = null;
     this.server.on('upgrade', (req, socket, head) => this.handleUpgrade(req, socket, head));
@@ -127,6 +160,10 @@ class RelayServer {
     this.cleanupTimer = null;
     for (const client of [...this.clients.values()]) this.detachClient(client, { notify: false });
     for (const host of [...this.hosts.values()]) this.detachHost(host, { notify: false });
+    this.pairAttempts.clear();
+    this.clientHandshakeAttempts.clear();
+    this.hostHandshakeAttempts.clear();
+    this.pendingHandshakes.clear();
     this.metrics.close();
     await new Promise((resolve) => {
       if (!this.server.listening) return resolve();
@@ -164,7 +201,21 @@ class RelayServer {
       socket.destroy();
       return;
     }
+    if (this.pendingHandshakes.size >= this.config.relay.maxPendingHandshakes) {
+      socket.write('HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n');
+      socket.destroy();
+      return;
+    }
+    // Small ANSI/input frames should not wait behind Nagle's timer. This is
+    // safe for both plain HTTP and TLS sockets and also benefits a relay behind
+    // a reverse proxy by keeping the relay leg immediately writable.
+    try {
+      socket.setNoDelay(true);
+      socket.setKeepAlive?.(true, this.config.cleanup.heartbeatIntervalMs);
+    } catch {}
     this.wss.handleUpgrade(req, socket, head, (ws) => {
+      this.pendingHandshakes.add(ws);
+      ws.once('close', () => this.finishHandshake(ws));
       if (pathname === '/ws/host') this.handleHostConnection(ws, req);
       else this.handleClientConnection(ws, req);
     });
@@ -176,7 +227,7 @@ class RelayServer {
     res.setHeader('X-Content-Type-Options', 'nosniff');
     res.setHeader('X-Frame-Options', 'DENY');
     res.setHeader('Referrer-Policy', 'no-referrer');
-    res.setHeader('Content-Security-Policy', "default-src 'self'; connect-src 'self' ws: wss:; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self'");
+    res.setHeader('Content-Security-Policy', "default-src 'self'; base-uri 'none'; object-src 'none'; frame-ancestors 'none'; connect-src 'self' ws: wss:; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self'");
   }
 
   sendJsonResponse(res, status, payload) {
@@ -203,6 +254,27 @@ class RelayServer {
     return token ? this.auth.authenticateDevice(token) : null;
   }
 
+  /**
+   * Resolve the request to one tenant. Supplying both authentication schemes is
+   * allowed only when they identify the same host; otherwise a caller could
+   * accidentally combine credentials from two workstations and receive the
+   * result selected by whichever branch happened to run first.
+   */
+  authorizedSubject(req) {
+    const hostIdHeader = req.headers['x-herdr-host-id'];
+    const hostTokenHeader = req.headers['x-herdr-host-token'];
+    const hasHostCredentials = hostIdHeader !== undefined || hostTokenHeader !== undefined;
+    const hasBearer = req.headers.authorization !== undefined;
+    const hostId = this.authorizedHost(req);
+    const device = this.authorizedDevice(req);
+    if (hasHostCredentials && !hostId) return null;
+    if (hasBearer && !device) return null;
+    if (hostId && device && hostId !== device.hostId) return null;
+    if (hostId) return { kind: 'host', hostId };
+    if (device) return { kind: 'device', hostId: device.hostId, deviceId: device.deviceId };
+    return null;
+  }
+
   /** Authenticate the operator of this relay, not a workstation or device. */
   authorizedAdmin(req) {
     return tokenMatches(req.headers['x-relay-admin-token'], this.adminToken);
@@ -226,19 +298,42 @@ class RelayServer {
     return req.socket.remoteAddress || 'unknown';
   }
 
-  allowPairAttempt(req) {
+  allowAttempt(store, req, limit = 20) {
     const key = this.rateLimitKey(req);
     const now = Date.now();
-    const current = this.pairAttempts.get(key);
+    const current = store.get(key);
     if (!current || now - current.startedAt >= 60_000) {
-      this.pairAttempts.set(key, { startedAt: now, count: 1 });
+      // Bound the map even when an attacker rotates source addresses. Expired
+      // entries are removed by sweep; the oldest live entry is the least
+      // useful one to retain when the cap is reached.
+      if (store.size >= 4096) {
+        const oldest = store.keys().next().value;
+        if (oldest !== undefined) store.delete(oldest);
+      }
+      store.set(key, { startedAt: now, count: 1 });
       return true;
     }
-    if (current.count >= 20) return false;
+    if (current.count >= limit) return false;
     current.count += 1;
     return true;
   }
 
+  allowPairAttempt(req) {
+    return this.allowAttempt(this.pairAttempts, req, 20);
+  }
+
+  allowClientHandshake(req) {
+    return this.allowAttempt(this.clientHandshakeAttempts, req, 60);
+  }
+
+  allowHostHandshake(req) {
+    return this.allowAttempt(this.hostHandshakeAttempts, req, 60);
+  }
+
+  finishHandshake(ws) {
+    this.pendingHandshakes.delete(ws);
+  }
+
   handleHttp(req, res) {
     let requestUrl;
     try {
@@ -255,7 +350,7 @@ class RelayServer {
       res.writeHead(204, {
         'Access-Control-Allow-Origin': req.headers.origin || '*',
         'Access-Control-Allow-Headers': 'Authorization, Content-Type, X-Herdr-Host-Id, X-Herdr-Host-Token, X-Relay-Admin-Token',
-        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+        'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
         Vary: 'Origin',
       });
       res.end();
@@ -265,16 +360,21 @@ class RelayServer {
       this.sendJsonResponse(res, 403, { ok: false, code: 'origin_denied', message: 'origin is not allowed' });
       return;
     }
+    // Only echo an origin after the exact allowlist/same-host check above. This
+    // makes explicitly configured cross-origin WebUI profiles usable without
+    // reflecting an attacker-controlled Origin header.
+    if (req.headers.origin) {
+      res.setHeader('Access-Control-Allow-Origin', req.headers.origin);
+      res.setHeader('Vary', 'Origin');
+    }
     if (requestUrl.pathname === '/healthz' && req.method === 'GET') {
-      const snapshot = this.statusSnapshot({ sample: false });
+      // Liveness is intentionally tenant-blind. Host/client counts let an
+      // unauthenticated caller learn whether other workstations are present.
       this.sendJsonResponse(res, 200, {
         ok: true,
         version: VERSION,
         protocol: PROTOCOL_VERSION,
-        hosts: snapshot.hostCount,
-        clients: snapshot.clientCount,
-        uptimeSeconds: snapshot.uptimeSeconds,
-        load1m: snapshot.cpu.load1m,
+        uptimeSeconds: Math.floor((Date.now() - this.startedAt) / 1000),
       });
       return;
     }
@@ -295,11 +395,12 @@ class RelayServer {
       return;
     }
     if (requestUrl.pathname === '/api/status' && req.method === 'GET') {
-      if (!this.authorizedHost(req) && !this.authorizedDevice(req)) {
+      const subject = this.authorizedSubject(req);
+      if (!subject) {
         this.sendJsonResponse(res, 401, { ok: false, code: 'auth_required', message: 'an authorized device or host token is required' });
         return;
       }
-      this.sendJsonResponse(res, 200, this.statusSnapshot());
+      this.sendJsonResponse(res, 200, this.statusSnapshot({ scopeHostId: subject.hostId }));
       return;
     }
     if (requestUrl.pathname === '/api/admin/status' && req.method === 'GET') {
@@ -345,7 +446,8 @@ class RelayServer {
         this.sendJsonResponse(res, 401, { ok: false, code: 'host_auth_required', message: 'a valid host id and token are required' });
         return;
       }
-      if (!this.hosts.has(hostId)) {
+      const host = this.hosts.get(hostId);
+      if (!host || host.reconnecting || !isOpen(host.ws)) {
         this.sendJsonResponse(res, 409, { ok: false, code: 'host_offline', message: 'no Herdr host is connected' });
         return;
       }
@@ -404,6 +506,66 @@ class RelayServer {
     });
   }
 
+  createHostRecord(message, ws, pending, clients = new Set()) {
+    const capabilities = Array.isArray(message.capabilities) ? message.capabilities : [];
+    return {
+      id: message.hostId,
+      ws,
+      hostname: typeof message.hostname === 'string' ? message.hostname.slice(0, 128) : os.hostname(),
+      platform: typeof message.platform === 'string' ? message.platform.slice(0, 32) : process.platform,
+      arch: typeof message.arch === 'string' ? message.arch.slice(0, 32) : process.arch,
+      connectedAt: new Date(pending.connectedAt).toISOString(),
+      connectedAtMs: pending.connectedAt,
+      // One shared terminal per workstation. Every browser attached to this
+      // host reads and writes the same PTY, so what one of them shows is what
+      // all of them show.
+      session: null,
+      terminalPalette: sanitizeTerminalPalette(message.terminalPalette),
+      lastSeenAt: Date.now(),
+      clients,
+      controllerId: null,
+      load: {},
+      ptys: [],
+      reconnecting: false,
+      reconnectTimer: null,
+      connectionGeneration: randomId('host-connection'),
+      handoffCapable: capabilities.includes('host_handoff'),
+      shutdownRequested: false,
+    };
+  }
+
+  canHandoffHost(host) {
+    if (!host?.handoffCapable || host.clients.size === 0) return false;
+    for (const clientId of host.clients) {
+      const client = this.clients.get(clientId);
+      if (!client?.handoffCapable) return false;
+    }
+    return true;
+  }
+
+  beginHostReconnect(host, reason = 'host_disconnected') {
+    if (!host || this.hosts.get(host.id) !== host || host.reconnecting) return;
+    if (!this.canHandoffHost(host)) {
+      this.detachHost(host, { notify: true, reason });
+      return;
+    }
+    host.ws = null;
+    host.reconnecting = true;
+    host.reconnectStartedAt = Date.now();
+    host.lastSeenAt = Date.now();
+    host.load = {};
+    host.ptys = [];
+    host.session = null;
+    this.broadcastToClients(host, () => ({ type: 'host_reconnecting', code: reason }));
+    host.reconnectTimer = setTimeout(() => {
+      host.reconnectTimer = null;
+      if (this.hosts.get(host.id) === host && host.reconnecting) {
+        this.detachHost(host, { notify: true, reason: 'host_reconnect_timeout' });
+      }
+    }, this.config.relay.hostReconnectGraceMs);
+    host.reconnectTimer.unref?.();
+  }
+
   handleHostConnection(ws, req) {
     const pending = { ws, remoteAddress: req.socket.remoteAddress, connectedAt: Date.now(), authenticated: false };
     const deadline = setTimeout(() => {
@@ -419,39 +581,65 @@ class RelayServer {
         if (isBinary) return this.rejectHandshake(ws, 'host hello must be JSON');
         const message = parseJson(raw.toString());
         if (!message || message.type !== 'host_hello' || message.protocol !== PROTOCOL_VERSION) return this.rejectHandshake(ws, 'invalid host hello');
+        if (!this.allowHostHandshake(req)) return this.rejectHandshake(ws, 'too many connection attempts', 'rate_limited');
+        const oldHost = this.hosts.get(message.hostId);
+        if (!oldHost && this.hosts.size >= this.config.relay.maxHosts) {
+          return this.rejectHandshake(ws, 'relay host limit reached', 'too_many_hosts');
+        }
         const registration = this.auth.registerHost(message.hostId, message.token, message.password ?? null);
         if (!registration.ok) return this.rejectHandshake(ws, registration.message, registration.code);
         clearTimeout(deadline);
         pending.authenticated = true;
-        const oldHost = this.hosts.get(message.hostId);
-        if (oldHost) this.detachHost(oldHost, { notify: true, reason: 'host_replaced' });
-        const host = {
-          id: message.hostId,
-          ws,
-          hostname: typeof message.hostname === 'string' ? message.hostname.slice(0, 128) : os.hostname(),
-          platform: typeof message.platform === 'string' ? message.platform.slice(0, 32) : process.platform,
-          arch: typeof message.arch === 'string' ? message.arch.slice(0, 32) : process.arch,
-          connectedAt: new Date(pending.connectedAt).toISOString(),
-          connectedAtMs: pending.connectedAt,
-          // Colors are the workstation's to declare, but only in the one shape
-          // a browser renderer accepts.
-          terminalPalette: sanitizeTerminalPalette(message.terminalPalette),
-          lastSeenAt: Date.now(),
-          clients: new Set(),
-          controllerId: null,
-          load: {},
-          ptys: [],
-        };
+        this.finishHandshake(ws);
+
+        const handoff = this.canHandoffHost(oldHost);
+        const retainedClients = handoff ? oldHost.clients : new Set();
+        if (oldHost) {
+          if (oldHost.reconnectTimer) clearTimeout(oldHost.reconnectTimer);
+          oldHost.reconnectTimer = null;
+          if (handoff) {
+            if (oldHost.session && isOpen(oldHost.ws)) {
+              jsonSend(oldHost.ws, { type: 'session_stop', clientId: oldHost.session.streamId, streamId: oldHost.session.streamId });
+            }
+            oldHost.session = null;
+            oldHost.load = {};
+            oldHost.ptys = [];
+            this.broadcastToClients(oldHost, () => ({ type: 'host_reconnecting', code: 'host_replaced' }));
+          } else {
+            this.detachHost(oldHost, { notify: true, reason: 'host_replaced' });
+          }
+        }
+
+        const host = this.createHostRecord(message, ws, pending, retainedClients);
         pending.host = host;
+        // Install the new record before closing the old socket. Its delayed
+        // close handler then fails the identity check instead of detaching the
+        // freshly authenticated host.
         this.hosts.set(host.id, host);
-        jsonSend(ws, { type: 'host_ready', protocol: PROTOCOL_VERSION, hostId: host.id });
+        if (oldHost && handoff) closeSocket(oldHost.ws, 1000, 'host_replaced');
+        jsonSend(ws, {
+          type: 'host_ready',
+          protocol: PROTOCOL_VERSION,
+          hostId: host.id,
+          clientCount: host.clients.size,
+        });
+        this.notifyHostClientCount(host);
+        if (handoff) this.startSession(host, { restarted: true });
         return;
       }
       this.handleHostMessage(pending.host, raw, isBinary);
     });
-    ws.on('close', () => {
+    ws.on('close', (_code, rawReason) => {
       clearTimeout(deadline);
-      if (pending.host) this.detachHost(pending.host, { notify: true, reason: 'host_disconnected' });
+      const host = pending.host;
+      if (!host || this.hosts.get(host.id) !== host || host.ws !== ws) return;
+      const reason = rawReason ? rawReason.toString() : '';
+      if (reason === 'host_shutdown') host.shutdownRequested = true;
+      if (host.shutdownRequested || !this.canHandoffHost(host)) {
+        this.detachHost(host, { notify: true, reason: host.shutdownRequested ? 'host_shutdown' : 'host_disconnected' });
+        return;
+      }
+      this.beginHostReconnect(host, 'host_disconnected');
     });
     ws.on('error', () => {});
   }
@@ -472,12 +660,15 @@ class RelayServer {
         closeSocket(host.ws, 1003, error.message);
         return;
       }
-      const client = this.clients.get(frame.streamId);
-      if (frame.type !== 'output' || !client || client.hostId !== host.id) return;
-      if (isOpen(client.ws)) {
-        client.ws.send(frame.payload);
-        client.bytesSent += frame.payload.length;
-        this.metrics.recordOut(frame.payload.length);
+      // Output belongs to the workstation's one shared session, so it goes to
+      // every browser attached to it rather than to a single stream owner.
+      const session = host.session;
+      if (frame.type !== 'output' || !session || session.streamId !== frame.streamId) return;
+      this.rememberOutput(session, frame.payload);
+      for (const clientId of [...host.clients]) {
+        const client = this.clients.get(clientId);
+        if (!client || !isOpen(client.ws)) continue;
+        this.sendClientBinary(host, client, frame.payload);
       }
       return;
     }
@@ -488,18 +679,219 @@ class RelayServer {
       host.ptys = Array.isArray(message.ptys) ? message.ptys.slice(0, 256) : [];
       return;
     }
-    const client = typeof message.clientId === 'string' ? this.clients.get(message.clientId) : null;
-    if (!client || client.hostId !== host.id) return;
+    if (message.type === 'host_shutdown') {
+      host.shutdownRequested = true;
+      if (this.hosts.get(host.id) === host) this.detachHost(host, { notify: true, reason: 'host_shutdown' });
+      return;
+    }
+    // Session-level news concerns the whole room: the host talks about the one
+    // shared stream, and every attached browser has to hear it.
+    const session = host.session;
+    const streamId = typeof message.clientId === 'string' ? message.clientId : message.streamId;
+    if (!session || (streamId && streamId !== session.streamId)) return;
     if (message.type === 'session_ready') {
-      jsonSend(client.ws, { type: 'session_ready', clientId: client.id });
+      session.ready = true;
+      this.broadcastToClients(host, (client) => ({ type: 'session_ready', clientId: client.id }));
     } else if (message.type === 'session_exit') {
-      jsonSend(client.ws, { type: 'exit', code: Number.isInteger(message.code) ? message.code : null });
-      this.detachClient(client, { notify: false });
+      const code = Number.isInteger(message.code) ? message.code : null;
+      host.session = null;
+      this.broadcastToClients(host, () => ({ type: 'exit', code }));
+      for (const clientId of [...host.clients]) {
+        const client = this.clients.get(clientId);
+        if (client) this.detachClient(client, { notify: false });
+      }
     } else if (message.type === 'error') {
-      jsonSend(client.ws, { type: 'error', code: message.code || 'host_error', message: String(message.message || 'Host connector error') });
+      this.broadcastToClients(host, () => ({
+        type: 'error',
+        code: message.code || 'host_error',
+        message: String(message.message || 'Host connector error'),
+      }));
+    }
+  }
+
+  /** Notify the host whether any browser currently needs business telemetry. */
+  notifyHostClientCount(host) {
+    if (!host || !isOpen(host.ws)) return;
+    jsonSend(host.ws, { type: 'client_count', clientCount: host.clients.size });
+  }
+
+  /**
+   * Forward output without allowing one slow browser to grow an unbounded ws
+   * queue. Closing only that browser preserves low latency for the other views.
+   */
+  sendClientBinary(host, client, payload) {
+    if (!client || !isOpen(client.ws)) return false;
+    const limit = this.config.relay.maxBufferedBytesPerClient;
+    const buffered = Number(client.ws.bufferedAmount) || 0;
+    if (buffered + payload.length > limit) {
+      this.metrics.recordCleanup('slowClientsDropped');
+      this.detachClient(client, { notify: true, reason: 'slow_client', closeCode: 1013 });
+      return false;
+    }
+    try {
+      client.ws.send(payload);
+      client.bytesSent += payload.length;
+      this.metrics.recordOut(payload.length, host.id);
+      return true;
+    } catch {
+      this.detachClient(client, { notify: false, reason: 'client_send_failed', closeCode: 1011 });
+      return false;
     }
   }
 
+  /** Send one JSON message to every browser attached to `host`. */
+  broadcastToClients(host, build) {
+    for (const clientId of [...host.clients]) {
+      const client = this.clients.get(clientId);
+      if (!client) continue;
+      const payload = build(client);
+      if (payload) jsonSend(client.ws, payload);
+    }
+  }
+
+  /** Keep the tail of the shared stream so a late joiner can be caught up. */
+  rememberOutput(session, payload) {
+    session.replay.push(Buffer.from(payload));
+    session.replayBytes += payload.length;
+    while (session.replayBytes > SESSION_REPLAY_BYTES && session.replay.length > 1) {
+      session.replayBytes -= session.replay.shift().length;
+    }
+  }
+
+  /**
+   * The grid the shared PTY runs at.
+   *
+   * The smallest attached window wins, exactly as it does in tmux: a column a
+   * phone cannot show is a column the program must not paint, or every other
+   * window sees wrapped rubbish. Nothing else keeps a shared terminal legible
+   * on two different screens at once.
+   */
+  sharedDimensions(host) {
+    let cols = MAX_DIMENSION;
+    let rows = MAX_DIMENSION;
+    let found = false;
+    for (const clientId of host.clients) {
+      const client = this.clients.get(clientId);
+      if (!client) continue;
+      found = true;
+      cols = Math.min(cols, client.cols);
+      rows = Math.min(rows, client.rows);
+    }
+    if (!found) return null;
+    return {
+      cols: Math.max(MIN_SHARED_COLS, cols),
+      rows: Math.max(MIN_SHARED_ROWS, rows),
+    };
+  }
+
+  /** Start the one shared PTY for a host's currently attached clients. */
+  startSession(host, { restarted = false } = {}) {
+    const firstClientId = [...host.clients][0];
+    const firstClient = firstClientId ? this.clients.get(firstClientId) : null;
+    if (!firstClient || !isOpen(host.ws)) return;
+    host.session = {
+      streamId: randomId('session'),
+      cols: firstClient.cols,
+      rows: firstClient.rows,
+      ready: false,
+      replay: [],
+      replayBytes: 0,
+    };
+    const dims = this.sharedDimensions(host) || { cols: firstClient.cols, rows: firstClient.rows };
+    host.session.cols = dims.cols;
+    host.session.rows = dims.rows;
+    jsonSend(host.ws, {
+      type: 'session_start',
+      clientId: host.session.streamId,
+      streamId: host.session.streamId,
+      cols: dims.cols,
+      rows: dims.rows,
+      role: 'controller',
+    });
+    this.broadcastToClients(host, () => ({ type: 'shared_resize', cols: dims.cols, rows: dims.rows }));
+    if (restarted) {
+      this.broadcastToClients(host, () => ({
+        type: 'session_restarted',
+        streamId: host.session.streamId,
+        cols: dims.cols,
+        rows: dims.rows,
+        hostname: host.hostname,
+        terminalPalette: host.terminalPalette || null,
+      }));
+    }
+  }
+
+  /**
+   * Attach `client` to the workstation's shared terminal, starting it if this
+   * is the first browser through the door.
+   *
+   * A later arrival does not get its own PTY: it is handed the stream already
+   * running, the output that has been printed so far, and — once the geometry
+   * has settled — a repaint, so it lands on the same screen everyone else is
+   * looking at.
+   */
+  attachSession(host, client) {
+    if (!host.session) {
+      this.startSession(host);
+      return;
+    }
+
+    const session = host.session;
+    if (session.ready) jsonSend(client.ws, { type: 'session_ready', clientId: client.id });
+    for (const chunk of session.replay) {
+      if (!isOpen(client.ws)) break;
+      this.sendClientBinary(host, client, chunk);
+    }
+    // Geometry may now be smaller than it was; the resize doubles as the
+    // repaint that puts the newcomer on the same screen as everyone else.
+    this.syncDimensions(host, { force: true });
+  }
+
+  /**
+   * Push the shared grid to the workstation.
+   *
+   * `force` asks for a repaint even when the numbers did not move: a browser
+   * that just joined needs the program to draw itself again, and a resize is
+   * the only signal a PTY has for "paint everything".
+   */
+  syncDimensions(host, { force = false } = {}) {
+    const session = host.session;
+    if (!session) return;
+    const dims = this.sharedDimensions(host);
+    if (!dims) return;
+    const changed = dims.cols !== session.cols || dims.rows !== session.rows;
+    session.cols = dims.cols;
+    session.rows = dims.rows;
+    if (!changed && !force) return;
+    // Every window has to be told what the shared grid became, not just the
+    // workstation. A browser that keeps rendering at its own width would wrap
+    // a stream written for a narrower terminal, which is the one thing a
+    // shared session must not do: the same bytes have to look the same in
+    // every window.
+    this.broadcastToClients(host, () => ({
+      type: 'shared_resize',
+      cols: dims.cols,
+      rows: dims.rows,
+    }));
+    if (!changed && force) {
+      // A no-op resize is ignored by the PTY, so bounce one row and come back.
+      jsonSend(host.ws, {
+        type: 'resize',
+        clientId: session.streamId,
+        streamId: session.streamId,
+        cols: dims.cols,
+        rows: Math.max(MIN_SHARED_ROWS, dims.rows - 1),
+      });
+    }
+    jsonSend(host.ws, {
+      type: 'resize',
+      clientId: session.streamId,
+      streamId: session.streamId,
+      cols: dims.cols,
+      rows: dims.rows,
+    });
+  }
+
   handleClientConnection(ws, req) {
     const pending = { ws, req, authenticated: false };
     const deadline = setTimeout(() => {
@@ -510,6 +902,7 @@ class RelayServer {
         if (isBinary) return this.rejectHandshake(ws, 'client hello must be JSON');
         const message = parseJson(raw.toString());
         if (!message || message.type !== 'hello' || message.protocol !== PROTOCOL_VERSION) return this.rejectHandshake(ws, 'invalid client hello');
+        if (!this.allowClientHandshake(req)) return this.rejectHandshake(ws, 'too many connection attempts', 'rate_limited');
         let device = null;
         let paired = null;
         if (message.pairCode) {
@@ -520,22 +913,17 @@ class RelayServer {
         else if (message.token) device = this.auth.authenticateDevice(message.token);
         if (!device) return this.rejectHandshake(ws, 'valid device token or pairing code required', 'auth_required');
         const host = this.hosts.get(device.hostId);
-        if (!host) return this.rejectHandshake(ws, 'paired Herdr host is offline', 'host_offline');
-
-        // One live session per browser. A browser that reconnects before the
-        // relay has noticed the old socket is gone would otherwise end up
-        // holding two sessions: the stale one keeps the controller lease, so
-        // the reconnected tab is stuck read-only against its own ghost. Retire
-        // that session first; the controller lease is released with it and this
-        // connection can take it again.
-        //
-        // Keyed on the browser-supplied client id, not on the device token:
-        // sharing one token across two browsers is the supported multi-viewer
-        // case and must keep working.
-        this.detachSupersededSession(device.deviceId, message.clientId, host);
+        if (!host || host.reconnecting || !isOpen(host.ws)) return this.rejectHandshake(ws, 'paired Herdr host is offline', host?.reconnecting ? 'host_reconnecting' : 'host_offline');
 
+        // Two tabs of one browser are two windows onto the same terminal, not
+        // rivals. Nothing is retired here: the relay used to close whichever
+        // session shared this browser's client id, which made two open tabs
+        // evict each other in a loop that never converged — each eviction
+        // triggered the other tab's auto-reconnect, which evicted this one
+        // back, forever.
         if (host.clients.size >= this.config.relay.maxClientsPerHost) return this.rejectHandshake(ws, 'host client limit reached', 'too_many_clients');
         clearTimeout(deadline);
+        this.finishHandshake(ws);
         const clientId = randomId('client');
         const client = {
           id: clientId,
@@ -544,9 +932,13 @@ class RelayServer {
           deviceId: device.deviceId,
           // Stable per browser profile; used to recognise a reconnect from the
           // same browser rather than a genuinely separate viewer.
-          browserClientId: typeof message.clientId === 'string' ? message.clientId : null,
-          role: host.controllerId ? 'viewer' : 'controller',
-          controllerId: host.controllerId,
+          browserClientId: typeof message.clientId === 'string' ? message.clientId.slice(0, 128) : null,
+          handoffCapable: Array.isArray(message.capabilities) && message.capabilities.includes('host_handoff'),
+          // Every paired window may type. Pairing is the permission boundary;
+          // once a device is through it, holding a second window read-only
+          // serves nobody — they are all views of one shared terminal.
+          role: 'controller',
+          controllerId: null,
           connectedAt: new Date().toISOString(),
           connectedAtMs: Date.now(),
           lastSeenAt: Date.now(),
@@ -558,8 +950,7 @@ class RelayServer {
           cols: clampDimension(message.cols, 80),
           rows: clampDimension(message.rows, 24),
         };
-        if (client.role === 'controller') host.controllerId = client.id;
-        client.controllerId = host.controllerId;
+        client.controllerId = null;
         // Persist how this device identifies itself so the operator dashboard
         // can name it in the revoke list instead of showing a bare device id.
         this.auth.noteDeviceSeen(device.deviceId, { userAgent: client.userAgent, ip: client.ip });
@@ -567,6 +958,7 @@ class RelayServer {
         pending.client = client;
         this.clients.set(client.id, client);
         host.clients.add(client.id);
+        this.notifyHostClientCount(host);
         ws.isAlive = true;
         ws.on('pong', () => {
           ws.isAlive = true;
@@ -580,14 +972,20 @@ class RelayServer {
         jsonSend(ws, {
           type: 'ready',
           role: client.role,
-          controllerId: host.controllerId,
+          // There is no controller to name: every window has full input. The
+          // field stays in the message for clients built against protocol 1,
+          // which read it to decide whether somebody else held the lease — and
+          // `null` is exactly the answer that means "nobody does".
+          controllerId: null,
           hostId: host.id,
+          hostname: host.hostname,
           clientId: client.id,
           // Delivered with `ready`, before the first PTY byte, so the terminal
           // is painted in the host's colors from its very first frame.
           terminalPalette: host.terminalPalette || null,
+          clientCount: host.clients.size,
         });
-        jsonSend(host.ws, { type: 'session_start', clientId: client.id, streamId: client.id, cols: client.cols, rows: client.rows, role: client.role });
+        this.attachSession(host, client);
         this.broadcastControlState(host);
         return;
       }
@@ -605,20 +1003,20 @@ class RelayServer {
     const host = this.hosts.get(client.hostId);
     if (!host) return this.detachClient(client, { notify: true, reason: 'host_offline' });
     if (isBinary) {
-      // A read-only device may still scroll. Like `resize` below, scrolling is
-      // not a shared-terminal action: each client drives its own PTY stream, so
-      // a wheel report moves only that viewer's own screen. Everything else —
-      // keystrokes, clicks, drags — stays behind the control lease.
-      if (client.role !== 'controller' && !isWheelOnlyInput(raw)) {
-        jsonSend(client.ws, { type: 'control_denied', message: 'this device is read-only' });
-        return;
-      }
       if (raw.length > this.config.relay.maxPayloadBytes) return;
-      const frame = packStreamFrame('input', client.id, raw);
+      const session = host.session;
+      if (!session) return;
+      // Every window writes into the one shared terminal, so input is stamped
+      // with the session's stream id rather than the sender's.
+      const frame = packStreamFrame('input', session.streamId, raw);
       if (isOpen(host.ws)) {
-        host.ws.send(frame);
-        client.bytesReceived += raw.length;
-        this.metrics.recordIn(raw.length);
+        try {
+          host.ws.send(frame);
+          client.bytesReceived += raw.length;
+          this.metrics.recordIn(raw.length, host.id);
+        } catch {
+          this.beginHostReconnect(host, 'host_send_failed');
+        }
       }
       return;
     }
@@ -631,47 +1029,41 @@ class RelayServer {
       client.lastPingAt = new Date().toISOString();
       jsonSend(client.ws, { type: 'pong' });
     } else if (message.type === 'resize') {
-      // Every client drives its *own* PTY stream — `session_start` is emitted
-      // per client with `streamId: client.id`, and the host resizes only that
-      // session — so geometry is not a shared-terminal action and must not
-      // require the control lease. Gating it here left a viewer's PTY at the
-      // 80x24 it was opened with: the agent then painted into a grid the
-      // terminal did not have, leaving blank rows under the content and
-      // columns clipped off the right edge.
+      // The shared grid is the smallest attached window, so one client's resize
+      // is recomputed across the room rather than applied on its own.
       client.cols = clampDimension(message.cols, client.cols);
       client.rows = clampDimension(message.rows, client.rows);
-      jsonSend(host.ws, { type: 'resize', clientId: client.id, cols: client.cols, rows: client.rows });
+      this.syncDimensions(host);
     } else if (message.type === 'claim_control') {
-      this.claimControl(host, client, Boolean(message.force));
+      // Control is no longer a lease. Answering the old request keeps clients
+      // built against the previous protocol working.
+      client.role = 'controller';
+      jsonSend(client.ws, { type: 'control_granted' });
     } else if (message.type === 'release_control') {
-      if (host.controllerId === client.id) {
-        host.controllerId = null;
-        this.broadcastControlState(host);
-      }
+      // Nothing to release: the window keeps its input either way, and saying
+      // so beats a silence an older client would wait on.
+      jsonSend(client.ws, { type: 'control_state', role: 'controller', controllerId: null });
     }
   }
 
-  claimControl(host, client, force) {
-    if (host.controllerId === client.id) return jsonSend(client.ws, { type: 'control_granted' });
-    if (host.controllerId && !force) return jsonSend(client.ws, { type: 'control_denied', message: 'another device currently controls this Herdr' });
-    const previous = host.controllerId ? this.clients.get(host.controllerId) : null;
-    if (previous) {
-      previous.role = 'viewer';
-      jsonSend(previous.ws, { type: 'control_revoked', controllerId: client.id });
-    }
-    host.controllerId = client.id;
-    client.role = 'controller';
-    jsonSend(client.ws, { type: 'control_granted' });
-    this.broadcastControlState(host);
-  }
-
+  /**
+   * Tell every window who is attached.
+   *
+   * There is no controller to announce any more, so this carries the one fact
+   * that changed: how many windows now share this terminal.
+   */
   broadcastControlState(host) {
     for (const clientId of host.clients) {
       const client = this.clients.get(clientId);
       if (!client) continue;
-      client.role = host.controllerId === client.id ? 'controller' : 'viewer';
-      client.controllerId = host.controllerId;
-      jsonSend(client.ws, { type: 'control_state', role: client.role, controllerId: host.controllerId || null });
+      client.role = 'controller';
+      client.controllerId = null;
+      jsonSend(client.ws, {
+        type: 'control_state',
+        role: 'controller',
+        controllerId: null,
+        clientCount: host.clients.size,
+      });
     }
   }
 
@@ -693,57 +1085,42 @@ class RelayServer {
     return closed;
   }
 
-  /**
-   * Retire the session the same browser already holds on this host, if any.
-   *
-   * `browserClientId` is the identifier the browser persists for itself, so two
-   * tabs of one browser collapse to a single session while two genuinely
-   * different browsers sharing a device token stay independent viewers. A
-   * client that sends no id cannot be matched and is left alone.
-   */
-  detachSupersededSession(deviceId, browserClientId, host) {
-    if (!deviceId || typeof browserClientId !== 'string' || !browserClientId) return 0;
-    let closed = 0;
-    for (const clientId of [...host.clients]) {
-      const existing = this.clients.get(clientId);
-      if (!existing || existing.deviceId !== deviceId) continue;
-      if (existing.browserClientId !== browserClientId) continue;
-      this.detachClient(existing, { notify: false, reason: 'superseded_by_new_session' });
-      closeSocket(existing.ws, 1000, 'replaced by a newer session from the same browser');
-      closed += 1;
-    }
-    return closed;
-  }
-
-  detachClient(client, { notify = true, reason = 'client_disconnected' } = {}) {
+  detachClient(client, { notify = true, reason = 'client_disconnected', closeCode = 1000 } = {}) {
     if (!client || !this.clients.has(client.id)) return;
     this.clients.delete(client.id);
     const host = this.hosts.get(client.hostId);
     if (host) {
       host.clients.delete(client.id);
-      if (isOpen(host.ws)) jsonSend(host.ws, { type: 'session_stop', clientId: client.id });
-      const wasController = host.controllerId === client.id;
-      if (wasController) {
-        host.controllerId = null;
-        const next = [...host.clients]
-          .map((id) => this.clients.get(id))
-          .filter(Boolean)
-          .sort((a, b) => a.connectedAtMs - b.connectedAtMs)[0];
-        if (next) {
-          host.controllerId = next.id;
-          next.role = 'controller';
-          jsonSend(next.ws, { type: 'control_granted' });
+      // The shared terminal outlives any one window: it is torn down only when
+      // the last of them has gone, so closing a tab never kills the session the
+      // other tabs are still watching.
+      if (host.clients.size === 0) {
+        if (host.session) {
+          if (isOpen(host.ws)) {
+            jsonSend(host.ws, { type: 'session_stop', clientId: host.session.streamId, streamId: host.session.streamId });
+          }
+          host.session = null;
         }
+        host.controllerId = null;
+      } else {
+        this.notifyHostClientCount(host);
+        this.syncDimensions(host);
         this.broadcastControlState(host);
       }
+      if (host.clients.size === 0) {
+        this.notifyHostClientCount(host);
+        if (host.reconnecting) this.detachHost(host, { notify: false, reason: 'no_clients' });
+      }
     }
     if (notify) jsonSend(client.ws, { type: 'error', code: reason, message: reason === 'host_offline' ? 'Herdr host is offline' : 'connection closed' });
-    closeSocket(client.ws, 1000, reason);
+    closeSocket(client.ws, closeCode, reason);
     this.metrics.recordCleanup('closedPtysCleaned');
   }
 
   detachHost(host, { notify = true, reason = 'host_disconnected' } = {}) {
     if (!host || this.hosts.get(host.id) !== host) return;
+    if (host.reconnectTimer) clearTimeout(host.reconnectTimer);
+    host.reconnectTimer = null;
     this.hosts.delete(host.id);
     for (const clientId of [...host.clients]) {
       const client = this.clients.get(clientId);
@@ -753,14 +1130,17 @@ class RelayServer {
       closeSocket(client.ws, 1012, reason);
     }
     host.clients.clear();
-    closeSocket(host.ws, 1000, reason);
+    this.metrics.forgetHost(host.id);
+    const hostSocket = host.ws;
+    host.ws = null;
+    closeSocket(hostSocket, 1000, reason);
   }
 
   heartbeat() {
     const sockets = [
       ...[...this.hosts.values()].map((host) => host.ws),
       ...[...this.clients.values()].map((client) => client.ws),
-    ];
+    ].filter(isOpen);
     for (const socket of sockets) {
       if (!socket.isAlive) {
         this.metrics.recordCleanup('deadConnectionsClosed');
@@ -780,6 +1160,12 @@ class RelayServer {
     for (const [key, attempt] of this.pairAttempts.entries()) {
       if (now - attempt.startedAt >= 60_000) this.pairAttempts.delete(key);
     }
+    for (const [key, attempt] of this.clientHandshakeAttempts.entries()) {
+      if (now - attempt.startedAt >= 60_000) this.clientHandshakeAttempts.delete(key);
+    }
+    for (const [key, attempt] of this.hostHandshakeAttempts.entries()) {
+      if (now - attempt.startedAt >= 60_000) this.hostHandshakeAttempts.delete(key);
+    }
     for (const client of [...this.clients.values()]) {
       if (now - client.lastSeenAt > staleAfter) {
         this.metrics.recordCleanup('staleClientsPurged');
@@ -787,6 +1173,7 @@ class RelayServer {
       }
     }
     for (const host of [...this.hosts.values()]) {
+      if (host.reconnecting) continue;
       if (now - host.lastSeenAt > staleAfter) {
         this.metrics.recordCleanup('deadConnectionsClosed');
         this.detachHost(host, { notify: true, reason: 'stale_host' });
@@ -797,12 +1184,18 @@ class RelayServer {
     this.metrics.cleanup.lastCleanupAt = new Date(now).toISOString();
   }
 
-  statusSnapshot({ sample = true, includeDevices = false } = {}) {
-    const clients = [...this.clients.values()].map((client) => ({
+  statusSnapshot({ sample = true, includeDevices = false, scopeHostId = null } = {}) {
+    const scopedClients = scopeHostId
+      ? [...this.clients.values()].filter((client) => client.hostId === scopeHostId)
+      : [...this.clients.values()];
+    const scopedHosts = scopeHostId
+      ? [...this.hosts.values()].filter((host) => host.id === scopeHostId)
+      : [...this.hosts.values()];
+    const clients = scopedClients.map((client) => ({
       id: client.id,
       role: client.role,
-      hostId: client.hostId,
-      deviceId: client.deviceId,
+      ...(scopeHostId ? {} : { hostId: client.hostId }),
+      ...(includeDevices ? { deviceId: client.deviceId } : {}),
       userAgent: client.userAgent,
       connectedAt: client.connectedAt,
       lastPingAt: client.lastPingAt,
@@ -810,23 +1203,31 @@ class RelayServer {
       bytesSent: client.bytesSent,
       ip: client.ip,
     }));
-    const hosts = [...this.hosts.values()].map((host) => ({
+    const hosts = scopedHosts.map((host) => ({
       id: host.id,
       hostname: host.hostname,
       platform: host.platform,
       arch: host.arch,
-      status: host.clients.size ? 'busy' : 'online',
+      status: host.reconnecting ? 'reconnecting' : host.clients.size ? 'busy' : 'online',
       connectedAt: host.connectedAt,
       activePtyCount: host.ptys.length,
       load: host.load,
     }));
-    const ptys = [...this.hosts.values()].flatMap((host) => host.ptys.map((pty) => ({ ...pty, hostId: host.id })));
+    // The workstation counts one PTY per stream and cannot know how many
+    // windows are watching it; the relay does, and that is the number an
+    // operator needs when the session is shared. Scoped callers only receive
+    // the PTYs belonging to their authenticated host.
+    const ptys = scopedHosts.flatMap((host) => host.ptys.map((pty) => ({
+      ...pty,
+      ...(scopeHostId ? {} : { hostId: host.id }),
+      activeClients: host.clients.size,
+    })));
     // The paired-device roster identifies people's hardware, so it is served to
     // the relay operator only — never on /api/status, which any paired device
     // may read.
     const devices = includeDevices ? this.auth.listDevices() : undefined;
     return {
-      ...this.metrics.snapshot({ clients, hosts, ptys, sample }),
+      ...this.metrics.snapshot({ clients, hosts, ptys, sample, scopeHostId }),
       ...(devices ? { devices } : {}),
       relayMode: this.relayMode,
       isRemoteRelay: this.relayMode === 'remote',
@@ -839,6 +1240,10 @@ class RelayServer {
         bind: this.config.relay.host,
         port: this.address()?.port || this.config.relay.port,
         maxClientsPerHost: this.config.relay.maxClientsPerHost,
+        maxHosts: this.config.relay.maxHosts,
+        maxPendingHandshakes: this.config.relay.maxPendingHandshakes,
+        maxBufferedBytesPerClient: this.config.relay.maxBufferedBytesPerClient,
+        hostReconnectGraceMs: this.config.relay.hostReconnectGraceMs,
         adminConfigured: Boolean(this.adminToken),
         adminStatusPath: '/api/admin/status',
         dashboardPath: '/admin',