tina4-nodejs 3.13.37 → 3.13.39

package/packages/core/src/websocket.ts

@@ -29,6 +29,9 @@ import type { Server } from "node:http";
 import type { WebSocketConnection } from "./websocketConnection.js";
 import type { WebSocketRouteHandler } from "./types.js";
 import { Router } from "./router.js";
+import { Log } from "./logger.js";
+import { validToken } from "./auth.js";
+import { WsBackplaneManager, type WsEnvelope } from "./websocketBackplane.js";
 
 // ── Constants ────────────────────────────────────────────────
 
@@ -46,6 +49,7 @@ export const OP_PONG = 0xa;
 export const CLOSE_NORMAL = 1000;
 export const CLOSE_GOING_AWAY = 1001;
 export const CLOSE_PROTOCOL_ERROR = 1002;
+export const CLOSE_POLICY_VIOLATION = 1008;
 
 // ── Types ────────────────────────────────────────────────────
 
@@ -57,6 +61,18 @@ export interface WebSocketClient {
   closed: boolean;
   /** The URL path this client connected on (e.g. "/chat", "/notifications"). */
   path: string;
+  /**
+   * Epoch ms of the last inbound frame. Updated on every frame; the idle
+   * reaper closes connections silent longer than `TINA4_WS_IDLE_TIMEOUT`
+   * (opt-in). Optional so externally-injected/legacy client objects still fit.
+   */
+  lastActivity?: number;
+  /**
+   * Verified JWT payload when this client connected on a secured WS route, or
+   * `null` on a public route. Mirrors Python's `connection.auth`. Optional so
+   * externally-injected/legacy client objects still fit.
+   */
+  auth?: Record<string, unknown> | null;
 }
 
 type EventHandler = (...args: unknown[]) => void;
@@ -72,6 +88,121 @@ export function computeAcceptKey(key: string): string {
     .digest("base64");
 }
 
+/**
+ * Return true if the upgrade request's `Origin` is permitted.
+ *
+ * Controlled by `TINA4_WS_ALLOWED_ORIGINS` (comma-separated list of exact
+ * origins, e.g. `https://app.example.com,https://admin.example.com`).
+ *
+ * Empty/unset = allow ALL origins (current behaviour, non-breaking). When set,
+ * only requests whose `Origin` header exactly matches a listed value are
+ * allowed; a missing `Origin` header is rejected once the allow-list is active.
+ * Header lookup is case-insensitive on the key (Node lowercases header keys,
+ * but the helper also checks an exact `Origin` so it works with raw maps too).
+ */
+export function originAllowed(headers: Record<string, string | string[] | undefined>): boolean {
+  const raw = (process.env.TINA4_WS_ALLOWED_ORIGINS ?? "").trim();
+  if (!raw) return true; // No allow-list configured — permit everything.
+  const allowed = new Set(
+    raw.split(",").map((o) => o.trim()).filter((o) => o.length > 0),
+  );
+  if (allowed.size === 0) return true;
+  const rawOrigin = headers["origin"] ?? headers["Origin"];
+  const origin = Array.isArray(rawOrigin) ? rawOrigin[0] : rawOrigin;
+  return origin !== undefined && allowed.has(origin);
+}
+
+/** Read a (possibly array-valued) header case-insensitively, return a single string. */
+function headerValue(
+  headers: Record<string, string | string[] | undefined>,
+  name: string,
+): string {
+  const lower = name.toLowerCase();
+  // Node lowercases header keys, but a raw map (or a test) may carry any case —
+  // match case-insensitively on the key, like Python's helper.
+  let raw = headers[lower] ?? headers[name];
+  if (raw === undefined) {
+    for (const [k, v] of Object.entries(headers)) {
+      if (k.toLowerCase() === lower) {
+        raw = v;
+        break;
+      }
+    }
+  }
+  if (raw === undefined) return "";
+  return Array.isArray(raw) ? (raw[0] ?? "") : raw;
+}
+
+/**
+ * Extract a bearer token from a WebSocket upgrade handshake.
+ *
+ * Order (mirrors Python's `ws_token`): the `Authorization: Bearer` header (set
+ * by server/CLI/mobile clients), then the `Sec-WebSocket-Protocol` subprotocol
+ * in the form `"bearer, <token>"` (the only way a *browser* can pass a token,
+ * since `new WebSocket()` cannot set headers), then a `?token=` query param.
+ * Returns the token string or `null`.
+ *
+ * @param headers       - Upgrade-request headers (case-insensitive lookup).
+ * @param queryString   - Raw query string (without the leading `?`), e.g. `token=abc`.
+ * @param subprotocol   - The offered `Sec-WebSocket-Protocol` value, if already parsed out.
+ */
+export function wsToken(
+  headers: Record<string, string | string[] | undefined>,
+  queryString = "",
+  subprotocol = "",
+): string | null {
+  const auth = headerValue(headers, "authorization");
+  if (auth.slice(0, 7).toLowerCase() === "bearer ") {
+    return auth.slice(7).trim() || null;
+  }
+  const proto = subprotocol || headerValue(headers, "sec-websocket-protocol");
+  const parts = proto.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+  if (parts.length >= 2 && parts[0].toLowerCase() === "bearer") {
+    return parts[1] || null;
+  }
+  if (queryString) {
+    // WHATWG URLSearchParams handles decoding; a leading "?" is tolerated.
+    const tok = new URLSearchParams(queryString.replace(/^\?/, "")).get("token");
+    if (tok) return tok;
+  }
+  return null;
+}
+
+/**
+ * Per-route WebSocket authentication, checked on the upgrade.
+ *
+ * A route is secured when `authRequired` is truthy (set by `.secure()` /
+ * `{ secured: true }` on the WS route, or a `_secured` flag on the handler).
+ * Public routes (the default) always pass. A secured route needs a valid JWT
+ * via the Authorization header, the `bearer` subprotocol, or `?token=`.
+ *
+ * Returns `[payload, ok]` — the verified token payload (or `null`) and whether
+ * the upgrade may proceed. Mirrors Python's `ws_authorized`.
+ */
+export function wsAuthorized(
+  route: { authRequired?: boolean } | null | undefined,
+  headers: Record<string, string | string[] | undefined>,
+  queryString = "",
+  subprotocol = "",
+): [Record<string, unknown> | null, boolean] {
+  if (!route?.authRequired) return [null, true];
+  const token = wsToken(headers, queryString, subprotocol);
+  if (!token) return [null, false];
+  const payload = validToken(token);
+  return [payload, payload !== null];
+}
+
+/**
+ * Whether the client offered the `bearer` subprotocol — if so, the server MUST
+ * echo `bearer` back as the accepted `Sec-WebSocket-Protocol` in the handshake
+ * (RFC 6455 §1.3; browsers send the token as the second subprotocol token).
+ */
+export function offeredBearerSubprotocol(subprotocol: string): boolean {
+  return subprotocol
+    .split(",")
+    .some((p) => p.trim().toLowerCase() === "bearer");
+}
+
 /**
  * Parse HTTP headers from raw upgrade request data.
  */
@@ -179,11 +310,26 @@ export class WebSocketServer {
   private clientRooms: Map<string, Set<string>> = new Map();
   /** Route-style handlers registered via route(), keyed by path */
   private _routeHandlers: Map<string, (conn: WebSocketConnection) => void | Promise<void>> = new Map();
+  /**
+   * Backplane (multi-instance scaling). Lazily wired on the first broadcast
+   * via {@link ensureBackplane}. Each instance owns a stable id so it can
+   * ignore its own echoes coming back over the shared pub/sub channel.
+   */
+  private backplane: WsBackplaneManager = new WsBackplaneManager();
+  /** Set once ensureBackplane() has fired so we only attempt the wiring once. */
+  private backplaneStarted = false;
+  /** Idle-connection reaper timer (opt-in via TINA4_WS_IDLE_TIMEOUT). */
+  private reaperTimer: ReturnType<typeof setInterval> | null = null;
 
   constructor(options?: { port?: number }) {
     this.port = options?.port ?? parseInt(process.env.TINA4_WS_PORT ?? "8080", 10);
   }
 
+  /** Test/diagnostic helper: this instance's stable backplane id. */
+  get instanceId(): string {
+    return this.backplane.instanceId;
+  }
+
   /**
    * Register an event handler.
    */
@@ -204,7 +350,11 @@ export class WebSocketServer {
    * to the Router's `(conn, event, data)` style and registers it via
    * `Router.websocket()`.
    */
-  route(path: string, handler: (conn: WebSocketConnection) => void | Promise<void>): void {
+  route(
+    path: string,
+    handler: (conn: WebSocketConnection) => void | Promise<void>,
+    options?: { secured?: boolean },
+  ): void {
     this._routeHandlers.set(path, handler);
 
     // Adapt to Router's (conn, event, data) style
@@ -231,7 +381,9 @@ export class WebSocketServer {
       }
     };
 
-    Router.websocket(path, adapter);
+    // Carry the secured flag through so the upgrade enforces auth. Public by
+    // default (mirrors GET); pass { secured: true } to require a valid JWT.
+    Router.websocket(path, adapter, options);
   }
 
   /**
@@ -242,35 +394,34 @@ export class WebSocketServer {
    * When `path` is omitted/undefined, all clients receive the message
    * (backward compatible).
    */
-  broadcast(message: string, excludeIds?: string[], path?: string): void {
-    const frame = buildFrame(OP_TEXT, Buffer.from(message, "utf-8"));
+  broadcast(message: string | Buffer, excludeIds?: string[], path?: string): void {
+    this.ensureBackplane();
     const exclude = new Set(excludeIds ?? []);
-
-    for (const [id, client] of this.clients) {
+    // Deliver to LOCAL connections first (resilient — a dead client is pruned,
+    // never aborts the loop), then fan out to sibling instances.
+    for (const [id, client] of Array.from(this.clients)) {
       if (exclude.has(id)) continue;
-      if (client.closed) continue;
       if (path !== undefined && client.path !== path) continue;
-      try {
-        client.socket.write(frame);
-      } catch {
-        // client disconnected
-      }
+      this.safeSend(client, message);
     }
+    this.backplane.publish(
+      path !== undefined ? "path" : "all",
+      message,
+      { path: path ?? null, exclude: excludeIds?.[0] ?? null },
+      Log,
+    );
   }
 
   /**
    * Send a message to a specific client by ID.
+   *
+   * Local-only: a connection lives on exactly one instance, so there is
+   * nothing to fan out over the backplane.
    */
-  sendTo(clientId: string, message: string): void {
+  sendTo(clientId: string, message: string | Buffer): void {
     const client = this.clients.get(clientId);
-    if (!client || client.closed) return;
-
-    const frame = buildFrame(OP_TEXT, Buffer.from(message, "utf-8"));
-    try {
-      client.socket.write(frame);
-    } catch {
-      // client disconnected
-    }
+    if (!client) return;
+    this.safeSend(client, message);
   }
 
   /**
@@ -288,6 +439,7 @@ export class WebSocketServer {
       });
 
       this.server.listen(this.port, () => {
+        this.startIdleReaper();
         resolve();
       });
 
@@ -302,6 +454,11 @@ export class WebSocketServer {
    * Stop the server and disconnect all clients.
    */
   stop(): void {
+    // Cancel the idle reaper if it was started.
+    if (this.reaperTimer !== null) {
+      clearInterval(this.reaperTimer);
+      this.reaperTimer = null;
+    }
     // Close all client connections
     for (const [id, client] of this.clients) {
       if (!client.closed) {
@@ -395,24 +552,26 @@ export class WebSocketServer {
 
   /**
    * Broadcast a message to all clients in a room.
+   *
+   * Resilient to dead clients (a failed send prunes the client, never aborts
+   * the loop) and fans out to sibling instances over the backplane when
+   * configured — a room can span instances, so each one delivers to its own
+   * members.
    */
-  broadcastToRoom(roomName: string, message: string, excludeIds?: string[]): void {
+  broadcastToRoom(roomName: string, message: string | Buffer, excludeIds?: string[]): void {
+    this.ensureBackplane();
     const members = this.rooms.get(roomName);
-    if (!members) return;
-
-    const frame = buildFrame(OP_TEXT, Buffer.from(message, "utf-8"));
     const exclude = new Set(excludeIds ?? []);
 
-    for (const clientId of members) {
-      if (exclude.has(clientId)) continue;
-      const client = this.clients.get(clientId);
-      if (!client || client.closed) continue;
-      try {
-        client.socket.write(frame);
-      } catch {
-        // client disconnected
+    if (members) {
+      for (const clientId of Array.from(members)) {
+        if (exclude.has(clientId)) continue;
+        const client = this.clients.get(clientId);
+        if (!client) continue;
+        this.safeSend(client, message);
       }
     }
+    this.backplane.publish("room", message, { room: roomName, exclude: excludeIds?.[0] ?? null }, Log);
   }
 
   // ── Private ────────────────────────────────────────────────
@@ -424,6 +583,155 @@ export class WebSocketServer {
     }
   }
 
+  // ── Backplane (multi-instance scaling) ─────────────────────
+  //
+  // When TINA4_WS_BACKPLANE is configured, every broadcast is ALSO published
+  // to a shared pub/sub channel so sibling server instances can relay it to
+  // their own local connections. Node is single-threaded async, so the
+  // subscribe callback relays directly on the event loop (no thread bridge) —
+  // it still applies the origin guard (drop our own echo) and never
+  // re-publishes (which would loop the cluster). The wiring is best-effort: a
+  // backplane failure logs and degrades to local-only, never crashing a
+  // broadcast.
+
+  /** Lazily wire the backplane on the first broadcast. Idempotent. */
+  private ensureBackplane(): void {
+    if (this.backplaneStarted) return;
+    this.backplaneStarted = true;
+    // Fire-and-forget: ensure() is async (connecting to the bus), but the
+    // local delivery that just happened must not wait on it. Any failure is
+    // logged inside ensure() and degrades to local-only.
+    void this.backplane.ensure((env) => this.relayLocal(env), Log);
+  }
+
+  /**
+   * Deliver a remote-originated envelope to LOCAL connections only. NEVER
+   * re-publishes (that would loop the message around the cluster). Dispatches
+   * by `kind`: room / path / all.
+   */
+  private relayLocal(env: WsEnvelope): void {
+    const message = WsBackplaneManager.decodeMessage(env);
+    if (message === null) return;
+    const exclude = env.exclude ?? null;
+
+    let targets: WebSocketClient[];
+    if (env.kind === "room") {
+      const members = env.room ? this.rooms.get(env.room) : undefined;
+      targets = members
+        ? Array.from(members).map((id) => this.clients.get(id)).filter((c): c is WebSocketClient => !!c)
+        : [];
+    } else if (env.kind === "path") {
+      targets = env.path
+        ? Array.from(this.clients.values()).filter((c) => c.path === env.path)
+        : [];
+    } else {
+      // "all" (and anything unknown) → every local connection
+      targets = Array.from(this.clients.values());
+    }
+
+    for (const client of targets) {
+      if (exclude && client.id === exclude) continue;
+      this.safeSend(client, message);
+    }
+  }
+
+  /**
+   * Send to ONE client without letting a single dead/slow client abort a
+   * broadcast loop. A write failure (or an already-closed client) is logged
+   * and the client is pruned. Returns true if the frame was handed to the
+   * socket.
+   *
+   * Slow-client backpressure: `socket.write()` returns false when the kernel
+   * send buffer is full. We don't unboundedly buffer — a client whose backlog
+   * has blown past TINA4_WS_MAX_BACKLOG bytes is hopelessly behind, so we drop
+   * and close it rather than let it grow the process heap without bound.
+   */
+  private safeSend(client: WebSocketClient, message: string | Buffer): boolean {
+    if (client.closed) {
+      this.pruneClient(client);
+      return false;
+    }
+    const payload = typeof message === "string" ? Buffer.from(message, "utf-8") : message;
+    const opcode = typeof message === "string" ? OP_TEXT : OP_BINARY;
+    const frame = buildFrame(opcode, payload);
+    try {
+      // A saturated socket buffer means the client can't keep up. write()
+      // still queues the frame and returns false; if the queued backlog is
+      // hopeless, close the client rather than buffer without bound.
+      client.socket.write(frame);
+      const backlog = client.socket.writableLength ?? 0;
+      const maxBacklog = parseInt(process.env.TINA4_WS_MAX_BACKLOG ?? "1048576", 10);
+      if (maxBacklog > 0 && backlog > maxBacklog) {
+        Log.warn(`WebSocket client ${client.id} backlog ${backlog}B exceeds limit, dropping slow client`);
+        this.pruneClient(client);
+        return false;
+      }
+      return true;
+    } catch (err) {
+      Log.warn(`WebSocket send to ${client.id} failed, pruning: ${(err as Error).message}`);
+      this.pruneClient(client);
+      return false;
+    }
+  }
+
+  /** Remove a client from the manager, rooms, and close its socket. */
+  private pruneClient(client: WebSocketClient): void {
+    client.closed = true;
+    this.clients.delete(client.id);
+    this.removeClientFromAllRooms(client.id);
+    try {
+      client.socket.destroy();
+    } catch {
+      /* already gone */
+    }
+  }
+
+  // ── Idle reaper (opt-in via TINA4_WS_IDLE_TIMEOUT) ──────────
+
+  /**
+   * Close connections whose last inbound frame is older than `timeoutSeconds`.
+   * Returns the number reaped. `timeoutSeconds <= 0` is a no-op (the reaper is
+   * opt-in via TINA4_WS_IDLE_TIMEOUT).
+   */
+  reapIdle(timeoutSeconds: number): number {
+    if (timeoutSeconds <= 0) return 0;
+    const now = Date.now();
+    const cutoff = timeoutSeconds * 1000;
+    const stale = Array.from(this.clients.values()).filter(
+      (c) => now - (c.lastActivity ?? c.connectedAt ?? now) > cutoff,
+    );
+    for (const client of stale) {
+      this.close(client.id, CLOSE_GOING_AWAY, "idle timeout");
+    }
+    if (stale.length > 0) {
+      Log.info(`WebSocket idle reaper closed ${stale.length} connection(s)`);
+    }
+    return stale.length;
+  }
+
+  /**
+   * Spin up the idle-connection reaper when TINA4_WS_IDLE_TIMEOUT is a
+   * positive number of seconds. Opt-in and non-breaking — unset/0 means no
+   * timer is created at all (current behaviour). Called from start().
+   */
+  private startIdleReaper(): void {
+    const raw = process.env.TINA4_WS_IDLE_TIMEOUT ?? "0";
+    const timeout = parseFloat(raw);
+    if (!Number.isFinite(timeout) || timeout <= 0 || this.reaperTimer !== null) return;
+    // Sweep at a fraction of the timeout (min 1s) so an idle conn is closed
+    // within roughly one timeout window of going silent.
+    const intervalMs = Math.max(1000, (timeout / 2) * 1000);
+    this.reaperTimer = setInterval(() => {
+      try {
+        this.reapIdle(timeout);
+      } catch (err) {
+        Log.error(`WebSocket idle reaper sweep failed: ${(err as Error).message}`);
+      }
+    }, intervalMs);
+    // Don't keep the event loop alive just for the reaper.
+    this.reaperTimer.unref?.();
+  }
+
   private handleUpgrade(req: IncomingMessage, socket: Socket, head: Buffer): void {
     const wsKey = req.headers["sec-websocket-key"];
     if (!wsKey) {
@@ -439,18 +747,44 @@ export class WebSocketServer {
       return;
     }
 
-    // Compute accept key and send upgrade response
-    const acceptKey = computeAcceptKey(wsKey);
-    const response = [
+    // Origin allow-list (opt-in via TINA4_WS_ALLOWED_ORIGINS). Unset = allow
+    // all, so this never breaks an existing deployment.
+    if (!originAllowed(req.headers)) {
+      socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+
+    // Per-route auth — checked AFTER the origin allow-list, BEFORE accept.
+    // A WS route is public by default (mirrors GET); a secured route requires a
+    // valid JWT via the Authorization header, the `bearer` subprotocol, or
+    // `?token=`. Missing/invalid → reject the upgrade (HTTP 401, never accept).
+    // Public routes (and any path with no registered route) always pass —
+    // non-breaking. The verified payload is exposed as client.auth.
+    const [reqPath, reqQuery = ""] = (req.url ?? "/").split("?");
+    const wsRoute = Router.matchWebSocket(reqPath);
+    const offeredProto = (req.headers["sec-websocket-protocol"] as string | undefined) ?? "";
+    const [authPayload, authOk] = wsAuthorized(wsRoute, req.headers, reqQuery, offeredProto);
+    if (!authOk) {
+      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+      socket.destroy();
+      return;
+    }
+
+    // Compute accept key and send upgrade response. Echo the `bearer`
+    // subprotocol when the client offered it (the browser token transport).
+    const acceptKey = computeAcceptKey(Array.isArray(wsKey) ? wsKey[0] : wsKey);
+    const responseLines = [
       "HTTP/1.1 101 Switching Protocols",
       "Upgrade: websocket",
       "Connection: Upgrade",
       `Sec-WebSocket-Accept: ${acceptKey}`,
-      "",
-      "",
-    ].join("\r\n");
-
-    socket.write(response);
+    ];
+    if (offeredBearerSubprotocol(offeredProto)) {
+      responseLines.push("Sec-WebSocket-Protocol: bearer");
+    }
+    responseLines.push("", "");
+    socket.write(responseLines.join("\r\n"));
 
     // Create client — track the URL path for path-scoped broadcast
     const clientId = randomUUID().slice(0, 8);
@@ -461,13 +795,15 @@ export class WebSocketServer {
       connectedAt: Date.now(),
       closed: false,
       path: req.url ?? "/",
+      lastActivity: Date.now(),
+      auth: authPayload,
     };
 
     this.clients.set(clientId, client);
     this.emit("open", client);
 
     // Handle incoming data
-    let buffer = Buffer.alloc(0);
+    let buffer: Buffer = Buffer.alloc(0);
     if (head.length > 0) {
       buffer = Buffer.concat([buffer, head]);
     }
@@ -506,6 +842,7 @@ export class WebSocketServer {
       if (!frame) break;
 
       remaining = remaining.subarray(frame.bytesConsumed);
+      client.lastActivity = Date.now(); // mark activity for the idle reaper
 
       switch (frame.opcode) {
         case OP_TEXT:
@@ -563,6 +900,293 @@ export class WebSocketServer {
   }
 }
 
+// ── Integrated WebSocket route manager (server.ts upgrade path) ──
+//
+// The standalone WebSocketServer above owns its own HTTP server. The INTEGRATED
+// Tina4 server (server.ts) runs one HTTP server for everything, so user WS
+// routes registered via Router.websocket() / WebSocketServer.route() must be
+// driven from server.ts's `upgrade` handler. This module-level manager mirrors
+// Python's `_ws_manager`: it holds the live route connections, drives the
+// open/message/close lifecycle on the raw socket, and powers path-scoped
+// broadcast / rooms for those connections. Auth is enforced on the upgrade
+// BEFORE a connection is created (see serveWebSocketRoute).
+
+/** A live route connection in the integrated server. */
+interface RouteConnState {
+  conn: WebSocketConnection;
+  socket: Socket;
+  path: string;
+  rooms: Set<string>;
+  closed: boolean;
+  /** Optional dev-admin tracker id so the connection shows in the websockets list. */
+  trackerId?: string;
+}
+
+/**
+ * Process-wide manager for user WebSocket route connections served by the
+ * integrated server. Path-scoped broadcast + rooms mirror the standalone
+ * WebSocketServer semantics so a route handler behaves the same either way.
+ */
+class WsRouteManager {
+  private connections = new Map<string, RouteConnState>();
+  private rooms = new Map<string, Set<string>>();
+  private onAdd?: (remoteAddress: string, path: string) => string;
+  private onRemove?: (id: string) => void;
+
+  /** Wire dev-admin tracking callbacks (WsTracker.add / WsTracker.remove). */
+  setTracker(onAdd: (remoteAddress: string, path: string) => string, onRemove: (id: string) => void): void {
+    this.onAdd = onAdd;
+    this.onRemove = onRemove;
+  }
+
+  /** Currently-open route connections (test/diagnostic helper). */
+  get size(): number {
+    return this.connections.size;
+  }
+
+  add(state: RouteConnState): void {
+    if (this.onAdd) state.trackerId = this.onAdd(state.socket.remoteAddress ?? "unknown", state.path);
+    this.connections.set(state.conn.id, state);
+  }
+
+  remove(id: string): void {
+    const state = this.connections.get(id);
+    if (!state) return;
+    for (const room of state.rooms) this.rooms.get(room)?.delete(id);
+    this.connections.delete(id);
+    if (state.trackerId && this.onRemove) this.onRemove(state.trackerId);
+  }
+
+  /** Send a text frame to one connection (best-effort). */
+  sendTo(id: string, message: string): void {
+    const state = this.connections.get(id);
+    if (!state || state.closed) return;
+    try {
+      state.socket.write(buildFrame(OP_TEXT, Buffer.from(message, "utf-8")));
+    } catch {
+      /* dropped */
+    }
+  }
+
+  /** Broadcast a text frame to every connection on the same path. */
+  broadcastPath(path: string, message: string): void {
+    const frame = buildFrame(OP_TEXT, Buffer.from(message, "utf-8"));
+    for (const state of this.connections.values()) {
+      if (state.path !== path || state.closed) continue;
+      try {
+        state.socket.write(frame);
+      } catch {
+        /* dropped */
+      }
+    }
+  }
+
+  joinRoom(id: string, room: string): void {
+    const state = this.connections.get(id);
+    if (!state) return;
+    state.rooms.add(room);
+    if (!this.rooms.has(room)) this.rooms.set(room, new Set());
+    this.rooms.get(room)!.add(id);
+  }
+
+  leaveRoom(id: string, room: string): void {
+    this.connections.get(id)?.rooms.delete(room);
+    this.rooms.get(room)?.delete(id);
+  }
+}
+
+/** Process-wide manager for integrated-server user WS route connections. */
+export const wsRouteManager = new WsRouteManager();
+
+/**
+ * Build a concrete {@link WebSocketConnection} bound to a raw socket, for a
+ * route served by the integrated server.
+ */
+function createRouteConnection(
+  socket: Socket,
+  path: string,
+  headers: Record<string, string>,
+  params: Record<string, string>,
+  auth: Record<string, unknown> | null,
+): WebSocketConnection {
+  const id = randomUUID().slice(0, 8);
+  const send = (message: string): void => {
+    try {
+      socket.write(buildFrame(OP_TEXT, Buffer.from(message, "utf-8")));
+    } catch {
+      /* socket gone */
+    }
+  };
+  const conn: WebSocketConnection = {
+    id,
+    path,
+    ip: socket.remoteAddress ?? "unknown",
+    headers,
+    params,
+    auth,
+    send,
+    sendJson: (data: unknown) => send(JSON.stringify(data)),
+    broadcast: (message: string) => wsRouteManager.broadcastPath(path, message),
+    joinRoom: (room: string) => wsRouteManager.joinRoom(id, room),
+    leaveRoom: (room: string) => wsRouteManager.leaveRoom(id, room),
+    close: () => {
+      try {
+        socket.write(buildFrame(OP_CLOSE, Buffer.from([0x03, 0xe8]))); // 1000
+        socket.end();
+      } catch {
+        /* already closed */
+      }
+    },
+    _onMessage: null,
+    _onClose: null,
+    onMessage(handler) {
+      this._onMessage = handler;
+    },
+    onClose(handler) {
+      this._onClose = handler;
+    },
+  };
+  return conn;
+}
+
+/**
+ * Reject a WebSocket upgrade on the raw socket with an HTTP status line.
+ * Used before the handshake completes (origin/auth failures).
+ */
+function rejectUpgrade(socket: Socket, statusLine: string): void {
+  try {
+    socket.write(`HTTP/1.1 ${statusLine}\r\n\r\n`);
+    socket.destroy();
+  } catch {
+    /* socket already gone */
+  }
+}
+
+/**
+ * Serve a user WebSocket route on the integrated server's `upgrade` event.
+ *
+ * This is the second half of per-route WS auth in Node: it's the entry point
+ * that wires a user-registered WS route (the WS route table) into the integrated
+ * server so the route actually gets a live open/message/close lifecycle on a
+ * real connection — parity with Python/PHP/Ruby — AND enforces per-route auth.
+ *
+ * Order mirrors Python's `_handle_dev_websocket` / `_handle_asgi_websocket`:
+ *   1. require a Sec-WebSocket-Key (else 400);
+ *   2. origin allow-list (else 403) — TINA4_WS_ALLOWED_ORIGINS, unset = allow all;
+ *   3. per-route auth (else 401) — public by default, secured needs a valid JWT;
+ *   4. accept the handshake, echoing `bearer` when offered;
+ *   5. build the connection (conn.auth = payload), fire "open", then pump
+ *      frames into "message" / "close".
+ *
+ * Returns true if a matching route was found and handled (accepted OR rejected),
+ * false if no WS route matched this path (caller falls through to its 404).
+ */
+export function serveWebSocketRoute(req: IncomingMessage, socket: Socket, head: Buffer): boolean {
+  const [reqPath, reqQuery = ""] = (req.url ?? "/").split("?");
+  const route = Router.matchWebSocket(reqPath);
+  if (!route) return false;
+
+  const wsKey = req.headers["sec-websocket-key"];
+  if (!wsKey || (typeof wsKey === "string" && wsKey.length === 0)) {
+    rejectUpgrade(socket, "400 Bad Request");
+    return true;
+  }
+
+  // Origin allow-list (opt-in via TINA4_WS_ALLOWED_ORIGINS). Unset = allow all.
+  if (!originAllowed(req.headers)) {
+    rejectUpgrade(socket, "403 Forbidden");
+    return true;
+  }
+
+  // Per-route auth: AFTER the origin check, BEFORE accept. Public by default;
+  // a secured route requires a valid JWT (header / bearer subprotocol / ?token=).
+  const offeredProto = (req.headers["sec-websocket-protocol"] as string | undefined) ?? "";
+  const [authPayload, authOk] = wsAuthorized(route, req.headers, reqQuery, offeredProto);
+  if (!authOk) {
+    rejectUpgrade(socket, "401 Unauthorized");
+    return true;
+  }
+
+  // Accept — echo the `bearer` subprotocol when the client offered it.
+  const acceptKey = computeAcceptKey(Array.isArray(wsKey) ? wsKey[0] : wsKey);
+  const responseLines = [
+    "HTTP/1.1 101 Switching Protocols",
+    "Upgrade: websocket",
+    "Connection: Upgrade",
+    `Sec-WebSocket-Accept: ${acceptKey}`,
+  ];
+  if (offeredBearerSubprotocol(offeredProto)) {
+    responseLines.push("Sec-WebSocket-Protocol: bearer");
+  }
+  responseLines.push("", "");
+  try {
+    socket.write(responseLines.join("\r\n"));
+  } catch {
+    return true; // socket died during handshake
+  }
+
+  const headerMap: Record<string, string> = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    headerMap[k] = Array.isArray(v) ? (v[0] ?? "") : (v ?? "");
+  }
+  const conn = createRouteConnection(socket, reqPath, headerMap, {}, authPayload);
+  const state: RouteConnState = { conn, socket, path: reqPath, rooms: new Set(), closed: false };
+  wsRouteManager.add(state);
+
+  const handler = route.handler;
+  // Fire "open" — may set conn._onMessage / conn._onClose (decorator style).
+  void Promise.resolve()
+    .then(() => handler(conn, "open", ""))
+    .catch((e) => Log.error(`WebSocket open handler error: ${(e as Error).message}`));
+
+  let buffer = head && head.length > 0 ? Buffer.from(head) : Buffer.alloc(0);
+  const fireClose = () => {
+    if (state.closed) return;
+    state.closed = true;
+    void Promise.resolve()
+      .then(() => (conn._onClose ? conn._onClose() : handler(conn, "close", "")))
+      .catch((e) => Log.error(`WebSocket close handler error: ${(e as Error).message}`))
+      .finally(() => wsRouteManager.remove(conn.id));
+  };
+
+  socket.on("data", (chunk: Buffer) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length > 0) {
+      const frame = parseFrame(buffer);
+      if (!frame) break;
+      buffer = buffer.subarray(frame.bytesConsumed);
+      switch (frame.opcode) {
+        case OP_TEXT: {
+          const text = frame.payload.toString("utf-8");
+          void Promise.resolve()
+            .then(() => (conn._onMessage ? conn._onMessage(text) : handler(conn, "message", text)))
+            .catch((e) => Log.error(`WebSocket message handler error: ${(e as Error).message}`));
+          break;
+        }
+        case OP_PING:
+          try {
+            socket.write(buildFrame(OP_PONG, frame.payload));
+          } catch {
+            /* client gone */
+          }
+          break;
+        case OP_CLOSE:
+          try {
+            socket.write(buildFrame(OP_CLOSE, Buffer.from([0x03, 0xe8])));
+            socket.end();
+          } catch {
+            /* already closed */
+          }
+          fireClose();
+          return;
+      }
+    }
+  });
+  socket.on("close", fireClose);
+  socket.on("error", fireClose);
+  return true;
+}
+
 // ── Dev-reload WebSocket manager ─────────────────────────────
 
 /** A single accepted /__dev_reload socket plus its dashboard tracker id. */