Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

12.8 KB
Raw Blame
// Authenticated WebSocket endpoint for the Server Edition.
//
// Attaches a `WebSocketServer({ noServer: true })` to an existing http.Server and
// handles the `upgrade` event ONLY for path `/ws`. The upgrade is gated by the
// session cookie AND (when an Origin header is present) an Origin/Host same-host
// check that blocks cross-site WebSocket hijacking — native clients (curl/ws)
// without an Origin still pass the gate but must present a valid cookie.
//
// Once connected, each socket attaches to the ServerPlatform as one UI: text
// frames are parsed as RPC (req → dispatch → response; cast → cast; anything else
// ignored), and the platform pushes JSON events / binary pty frames back through
// the sink. Binary client→server frames are ignored in Phase 2 (pty input rides
// JSON casts). See task-5-brief.md.
import type http from 'http'
import type { Duplex } from 'stream'
import { WebSocketServer, type WebSocket } from 'ws'
import type { Auth } from './auth'
import type { ServerPlatform } from './platform-server'
import { sessionTokenFromCookie } from './http'
import { noteProxyRefusal, proxyAuthDecision, type TrustProxyConfig } from './proxy-trust'
import { sameOriginRequest } from './origin'
import { parseRpcMessage } from '../shared/rpc'
import { presenceHub } from '../core/presence/hub'
import { WS_CLIENT_FRAME_MAX } from '../shared/ws-frame'

/**
 * Heartbeat period. Every WS_HEARTBEAT_MS the server pings each socket; a socket that answered
 * nothing since the previous round is terminated (miss policy: ONE missed round). A dead peer is
 * therefore reaped in 30–60 s — fast enough that a ghost cursor / phantom facepile entry is a blip
 * rather than a permanent fixture, slow enough to survive a stalled tab or a brief network hiccup
 * (a live browser answers a ping from the protocol layer, with no page JS involved) and to stay
 * well inside the ~60 s idle timeout of common reverse proxies, which the ping traffic also keeps
 * the connection alive against.
 */
export const WS_HEARTBEAT_MS = 30_000

/**
 * Largest client→server frame the receiver will accept (8 MiB). `ws` defaults to 100 MiB, which is
 * a remote DoS on a process that is shared by every user of the box: one client holding the single
 * Server Edition password can loop 100 MB frames and OOM the server, taking down everyone's ptys,
 * the hook server and the workspace store. The receiver drops an oversized frame with close code
 * 1009 before it ever reaches dispatch, so nothing buffers it.
 *
 * Why 8 MiB — what actually rides this socket, client→server:
 *   - `pty:write` casts: keystrokes and clipboard pastes (kilobytes; a giant paste is not a thing
 *     a terminal survives anyway),
 *   - presence casts: cursor points, and chat/name/focus strings the hub itself caps at 200 / 32 /
 *     128 code points,
 *   - RPC requests, of which the biggest by far is `fs:write` — an editor node saving its file,
 *     JSON-escaped. 8 MiB comfortably covers any text file a Monaco editor is usable on (a 1 MB
 *     source file is already an outlier, and JSON escaping roughly doubles it in the worst case),
 *     plus `workspace:save` (a whole canvas: nodes + sticky text, tens of KB).
 * That leaves ~an order of magnitude of headroom over the largest legitimate frame while cutting
 * the worst case a single frame can cost the process by ~12×.
 */
export const WS_MAX_PAYLOAD = WS_CLIENT_FRAME_MAX

/**
 * Close code for a socket whose session was signed out (S3): `/auth/logout`, "Sign out everywhere",
 * or the session's 30-day TTL running out. An application code (4000–4999) so it cannot be
 * mistaken for a network drop in a log.
 */
export const WS_CLOSE_SIGNED_OUT = 4401

export interface WsServerOpts {
  platform: ServerPlatform
  auth: Auth
  /**
   * A connection is GONE (tab closed — the normal way to leave the Server Edition — reload, or a
   * peer reaped by the heartbeat). Wired to `PtyManager.dropClient` at boot, so the sessions that
   * client was watching lose it as a subscriber and the ones nobody watches any more are released.
   * Passed in rather than imported, because `src/server` owns the wiring and `src/core` may not
   * know about `ws`.
   */
  onClientGone?: (uiId: number) => void
  /** TEST ONLY: shorten the heartbeat period. Production always uses WS_HEARTBEAT_MS. */
  heartbeatMs?: number
  /** Reverse-proxy SSO trust (issue #29) — same object the HTTP handler gets. */
  trustProxy?: TrustProxyConfig
  /** NODETERM_PUBLIC_ORIGIN — an `Origin` equal to it passes the same-origin check (see origin.ts). */
  publicOrigin?: string
}

/**
 * Decide whether an upgrade request is allowed. Allowed only when the request is authenticated — a
 * valid session cookie OR reverse-proxy header trust (issue #29; with the proxy secret when one is
 * configured, S2) — AND it passes the same-origin check (origin.ts; the cross-site WS hijacking
 * check applies to both auth paths). A malformed Origin is a rejection (never throws).
 *
 * Returns the session token the socket rides on when it was authenticated by its cookie — the
 * socket is closed when that session is signed out or expires (S3). A proxy-authenticated socket
 * carries no token: its identity is the proxy's, not a cookie's.
 */
function upgradeAllowed(
  req: http.IncomingMessage,
  auth: Auth,
  trustProxy: TrustProxyConfig | undefined,
  publicOrigin: string | undefined
): { ok: false } | { ok: true; token: string | null } {
  const token = sessionTokenFromCookie(req.headers['cookie'])
  const decision =
    trustProxy !== undefined ? proxyAuthDecision(trustProxy, req.headers, req.socket.remoteAddress) : 'none'
  noteProxyRefusal(decision)
  const proxyAuthed = decision === 'trusted'
  if (!proxyAuthed && !auth.validateSession(token)) return { ok: false }
  if (!sameOriginRequest(req.headers, publicOrigin)) return { ok: false }
  return { ok: true, token: proxyAuthed || token === undefined ? null : token }
}

export function attachWsServer(server: http.Server, opts: WsServerOpts): WebSocketServer {
  const { platform, auth, onClientGone, heartbeatMs = WS_HEARTBEAT_MS, trustProxy, publicOrigin } = opts
  const wss = new WebSocketServer({ noServer: true, maxPayload: WS_MAX_PAYLOAD })

  // The session each cookie-authenticated socket rides on (S3). A socket used to be checked once at
  // upgrade and never again, so signing out — or the session expiring — left an open tab fully
  // connected. Now a revoke closes the affected sockets at once, and the heartbeat re-checks the
  // rest every round (that is what catches the 30-day expiry, which emits nothing).
  const tokenOf = new Map<WebSocket, string>()
  const signedOut = new WeakSet<WebSocket>()
  const endIfSignedOut = (ws: WebSocket): boolean => {
    const token = tokenOf.get(ws)
    if (token === undefined || auth.validateSession(token)) return false
    tokenOf.delete(ws)
    // Drop anything it sends from here on — the close handshake can take a moment, and a frame
    // that arrives in it must not reach dispatch.
    signedOut.add(ws)
    ws.close(WS_CLOSE_SIGNED_OUT, 'signed out')
    return true
  }
  const offRevoke = auth.onSessionsRevoked(() => {
    for (const ws of [...tokenOf.keys()]) endIfSignedOut(ws)
  })
  server.on('close', () => offRevoke())

  // The one teardown for a connection that is GONE — whether by a clean 'close', or because its sink
  // proved dead (the registry evicted it after consecutive throwing sends and called this back).
  // Order matches 'close': leave the hub, hand the pty layer its subscriber back, detach the sink.
  // Idempotent, so a sink-gone eviction that races the real 'close' is harmless.
  const teardown = (uiId: number): void => {
    presenceHub.leave(uiId)
    // This client is a pty subscriber, and nothing else would ever tell PtyManager it is gone (a
    // closed tab sends no `pty:kill`). Leaving it subscribed leaks the pty client, skips the
    // detach-time scrollback snapshot, and can strand a session it had paused — a client joining
    // that node later would inherit a frozen pty.
    onClientGone?.(uiId)
    platform.detach(uiId)
  }
  // `ws.send` does not throw synchronously on a dead socket, so this rarely fires server-side — but
  // if a sink ever does throw consecutively, treat it exactly like a close rather than shouting into
  // a dead socket forever (the registry already dropped the sink before calling back).
  platform.setSinkGoneHandler(teardown)

  // Liveness heartbeat. Node enables no TCP keepalive on an upgraded socket, so a browser that
  // simply VANISHES (laptop asleep, wifi dropped, NAT idle-reap) leaves a half-open socket: no FIN
  // ever arrives, 'close' never fires, and the peer would sit in the presence hub — a ghost cursor
  // and a phantom facepile entry, its colour consumed by nextFreeColor — for the life of the
  // process. So: mark a socket alive on any inbound traffic, ping every round, and terminate
  // whatever answered nothing since the previous one. terminate() fires 'close', which is the ONE
  // path that leaves the hub / detaches the UI (see the connection handler) — never leave() here.
  const alive = new WeakSet<WebSocket>()
  const heartbeat = setInterval(() => {
    for (const ws of wss.clients) {
      if (endIfSignedOut(ws)) continue
      if (!alive.has(ws)) {
        ws.terminate()
        continue
      }
      alive.delete(ws)
      ws.ping()
    }
  }, heartbeatMs)
  // Must never hold the process (or a vitest run) open, and must stop with its server.
  if (heartbeat.unref) heartbeat.unref()
  server.on('close', () => clearInterval(heartbeat))

  server.on('upgrade', (req: http.IncomingMessage, socket: Duplex, head: Buffer) => {
    // Only handle our path; a mismatched path is left for any other upgrade
    // listener (and, if none, the socket eventually times out / is destroyed by node).
    const pathname = new URL(req.url || '/', 'http://x').pathname
    if (pathname !== '/ws') return

    const allowed = upgradeAllowed(req, auth, trustProxy, publicOrigin)
    if (!allowed.ok) {
      // Guard the raw socket: writing to an already-dead peer emits 'error', and an
      // unhandled 'error' on a socket (EventEmitter) throws → crashes the process.
      socket.on('error', () => {})
      socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n')
      socket.destroy()
      return
    }

    wss.handleUpgrade(req, socket, head, (ws) => {
      if (allowed.token !== null) tokenOf.set(ws, allowed.token)
      // Signed out between the upgrade check and now: never attach it.
      if (endIfSignedOut(ws)) return
      wss.emit('connection', ws, req)
    })
  })

  wss.on('connection', (ws: WebSocket) => {
    alive.add(ws)
    // A pong is the protocol-level proof of life (the browser's stack answers it with no page JS
    // involved, so it works even while the tab is frozen or the app is wedged).
    ws.on('pong', () => alive.add(ws))

    // `owner`: this socket passed `upgradeAllowed` (session cookie or trusted proxy auth), so it is
    // the server's one user. Relay-hosted peers attach elsewhere (index.ts) and never get it.
    const uiId = platform.attach(
      {
        sendText: (json) => ws.send(json),
        sendBinary: (buf) => ws.send(buf, { binary: true }),
        bufferedAmount: () => ws.bufferedAmount
      },
      { owner: true }
    )
    // Team presence: each authenticated socket is one peer. Joining AFTER attach means the hub's
    // `presence:sync` sendTo lands on a live sink; the browser bridge buffers it until the app
    // subscribes. The peer stays nameless ("Someone") until it sends `presence:hello`.
    presenceHub.join(uiId, 'browser')

    ws.on('message', (data: unknown, isBinary: boolean) => {
      if (signedOut.has(ws)) return
      // Any inbound frame proves the peer is there, pong or not.
      alive.add(ws)
      // Binary client→server frames are ignored in Phase 2 (pty input rides JSON casts).
      if (isBinary) return
      const text = Buffer.isBuffer(data)
        ? data.toString('utf8')
        : Array.isArray(data)
          ? Buffer.concat(data).toString('utf8')
          : String(data)
      const m = parseRpcMessage(text)
      if (!m) return
      if (m.t === 'req') {
        void platform.dispatch(uiId, m).then((res) => ws.send(JSON.stringify(res)))
      } else if (m.t === 'cast') {
        platform.cast(uiId, m.method, m.args)
      }
      // res/ev from a client are ignored.
    })

    // Without an 'error' listener, a receiver protocol error (malformed/unmasked
    // frame, corrupted proxy frame) emits 'error' on the socket with no listener,
    // which THROWS → uncaughtException → the whole server exits, tearing down every
    // session's pty. Log and let 'close' fire for this one connection only.
    ws.on('error', (e: NodeJS.ErrnoException) => {
      console.warn('[nodeterm-server] ws socket error', (e && e.code) || e)
    })

    ws.on('close', () => {
      tokenOf.delete(ws)
      teardown(uiId)
    })
  })
  return wss
}