herdr-remote-relay 0.2.0 → 0.2.2

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')}`;
 }
@@ -311,7 +324,28 @@ class RelayServer {
         this.sendJsonResponse(res, 401, { ok: false, code: 'admin_auth_required', message: 'a valid relay admin token is required' });
         return;
       }
-      this.sendJsonResponse(res, 200, this.statusSnapshot());
+      this.sendJsonResponse(res, 200, this.statusSnapshot({ includeDevices: true }));
+      return;
+    }
+    if (requestUrl.pathname.startsWith('/api/admin/devices/') && req.method === 'DELETE') {
+      if (!this.adminToken) {
+        this.sendJsonResponse(res, 503, { ok: false, code: 'admin_not_configured', message: 'configure RELAY_ADMIN_TOKEN to access the relay dashboard' });
+        return;
+      }
+      if (!this.authorizedAdmin(req)) {
+        this.sendJsonResponse(res, 401, { ok: false, code: 'admin_auth_required', message: 'a valid relay admin token is required' });
+        return;
+      }
+      const deviceId = decodeURIComponent(requestUrl.pathname.slice('/api/admin/devices/'.length));
+      const revoked = this.auth.revokeDevice(deviceId);
+      if (!revoked) {
+        this.sendJsonResponse(res, 404, { ok: false, code: 'device_not_found', message: 'no such paired device' });
+        return;
+      }
+      // Revocation has to take effect now, not at the next reconnect: drop any
+      // socket the device still holds so the terminal closes immediately.
+      const disconnected = this.detachDeviceSessions(deviceId);
+      this.sendJsonResponse(res, 200, { ok: true, deviceId: revoked.deviceId, disconnected });
       return;
     }
     if (requestUrl.pathname === '/api/pair/start' && req.method === 'POST') {
@@ -412,6 +446,10 @@ class RelayServer {
           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 window shows is
+          // what all of them show.
+          session: null,
           // Colors are the workstation's to declare, but only in the one shape
           // a browser renderer accepts.
           terminalPalette: sanitizeTerminalPalette(message.terminalPalette),
@@ -451,9 +489,14 @@ 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)) {
+      // 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;
         client.ws.send(frame.payload);
         client.bytesSent += frame.payload.length;
         this.metrics.recordOut(frame.payload.length);
@@ -467,18 +510,170 @@ 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;
+    // 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'),
+      }));
+    }
+  }
+
+  /** 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),
+    };
+  }
+
+  /**
+   * 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) {
+      host.session = {
+        streamId: randomId('session'),
+        cols: client.cols,
+        rows: client.rows,
+        ready: false,
+        replay: [],
+        replayBytes: 0,
+      };
+      const dims = this.sharedDimensions(host) || { cols: client.cols, rows: client.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',
+      });
+      // Said out loud even when this window is the only one, so a browser that
+      // reconnects is never left painting the grid of a session that has since
+      // been torn down and started again at a different size.
+      jsonSend(client.ws, { type: 'shared_resize', cols: dims.cols, rows: dims.rows });
+      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;
+      client.ws.send(chunk);
+      client.bytesSent += chunk.length;
+    }
+    // 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(() => {
@@ -500,6 +695,13 @@ class RelayServer {
         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');
+
+        // 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);
         const clientId = randomId('client');
@@ -508,8 +710,14 @@ class RelayServer {
           ws,
           hostId: host.id,
           deviceId: device.deviceId,
-          role: host.controllerId ? 'viewer' : 'controller',
-          controllerId: host.controllerId,
+          // 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,
+          // 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(),
@@ -521,8 +729,10 @@ 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 });
         pending.authenticated = true;
         pending.client = client;
         this.clients.set(client.id, client);
@@ -540,14 +750,19 @@ 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,
           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;
       }
@@ -565,16 +780,12 @@ 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;
@@ -591,69 +802,81 @@ 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,
+      });
     }
   }
 
+  /**
+   * Close every existing session belonging to `deviceId` on `host`.
+   *
+   * Called just before a freshly authenticated connection is registered, so the
+   * same physical device never occupies two client slots (and two PTYs) at once.
+   */
+  detachDeviceSessions(deviceId) {
+    if (!deviceId) return 0;
+    let closed = 0;
+    for (const existing of [...this.clients.values()]) {
+      if (!existing || existing.deviceId !== deviceId) continue;
+      this.detachClient(existing, { notify: false, reason: 'device_revoked' });
+      closeSocket(existing.ws, 1000, 'this device has been revoked by the relay operator');
+      closed += 1;
+    }
+    return closed;
+  }
+
   detachClient(client, { notify = true, reason = 'client_disconnected' } = {}) {
     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.syncDimensions(host);
         this.broadcastControlState(host);
       }
     }
@@ -717,7 +940,7 @@ class RelayServer {
     this.metrics.cleanup.lastCleanupAt = new Date(now).toISOString();
   }
 
-  statusSnapshot({ sample = true } = {}) {
+  statusSnapshot({ sample = true, includeDevices = false } = {}) {
     const clients = [...this.clients.values()].map((client) => ({
       id: client.id,
       role: client.role,
@@ -740,9 +963,21 @@ class RelayServer {
       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.
+    const ptys = [...this.hosts.values()].flatMap((host) => host.ptys.map((pty) => ({
+      ...pty,
+      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 }),
+      ...(devices ? { devices } : {}),
       relayMode: this.relayMode,
       isRemoteRelay: this.relayMode === 'remote',
       remoteAdminUrl: this.relayMode === 'remote'