@preventive/triage 1.0.0-alpha.0 → 1.0.0-alpha.10

package/server-e2e/sse-server.ts

@@ -0,0 +1,384 @@
+// SSE+POST fallback for clients that can't establish a WebSocket
+// upgrade — corporate proxies that strip `Upgrade: websocket`, legacy
+// HTTP/1.0 intermediaries, or environments where `new WebSocket(…)`
+// errors before `open`. Wire protocol on the SSE downstream is
+// identical to the WS plane (same JSON message taxonomy, same Ed25519-
+// signed canonicals, same `challenge` / `pong` / `authenticate` flow);
+// the upstream direction batches frames into HTTP POSTs.
+//
+// One route, POSTs only:
+//
+//   POST /api/sync/sse
+//       Request body:
+//         { id?: string,                         — session continuation token
+//           password?: string,                   — cached client password
+//           frames?:   Array<protocol-frame>     — WS-style JSON frames
+//         }
+//       Response:
+//         200 OK, content-type: text/event-stream
+//         First frame on a *fresh* session is an SSE event named
+//         `session` whose data is the raw continuation-token string
+//         (22-char base64url, from `randomId()`). The per-session
+//         challenge nonce is delivered separately on the next default-
+//         named `data:` event as the standard protocol `challenge`
+//         frame, so the SSE plane uses the SAME nonce-handshake the WS
+//         plane does. Subsequent frames are default-named SSE messages
+//         carrying the WS protocol's JSON envelopes.
+//
+// Continuation: each POST replaces the previous POST's response as the
+// session's downstream channel. If the body's `id` matches a session
+// this replica knows, the session continues (new outbound stream
+// attached, old one end()ed). If the id is unknown (different replica
+// picked up the POST, or session expired), a fresh session with a new
+// id is created and announced via the first `session` event; the
+// client uses the new id on all subsequent POSTs and re-sends its
+// subscribe frames on the next POST (its `frames` carry the signed
+// subscribes — they always do, see client/sync/sse-transport.ts).
+//
+// The id rides the JSON body, NOT the URL: the sid is a live bearer
+// capability (whoever presents it attaches to the session's downstream
+// and inherits its operator-auth flag), and a query-string token leaks
+// into proxy / LB access logs — the same reason the objstore bearer
+// tokens ride the Authorization header, never the URL. A legacy
+// `?id=<sid>` query form is still ACCEPTED (older client bundles sent
+// it; rejecting would churn them through a fresh session per POST),
+// but current clients never emit it.
+//
+// Why POSTs only: a long-lived GET pins the client to one replica via
+// TCP affinity, which would mean POSTs from the same client must be
+// sticky-routed to the same replica. POSTs-only makes the protocol
+// stateless across replicas — any replica can pick up the next POST
+// from any client.
+
+import type { IncomingMessage as HttpRequest, ServerResponse } from 'node:http'
+import { Buffer } from 'node:buffer'
+import type { WebSocket } from 'ws'
+import { type PeerConnectionDeps, setupPeerConnection } from './ws-server.ts'
+import { SseSession } from './sse-session.ts'
+import { errMsg, randomId } from './util.ts'
+
+// Same prefix the WS upgrade lives under (server-e2e/http.ts WS_UPGRADE_PATH
+// = '/api/sync'); subroute keeps the SSE plane sibling to the upgrade
+// path so the same `location` block routes both.
+export const SSE_OPEN_PATH = '/api/sync/sse'
+
+// Cadence of the server-driven keepalive sweep: every tick we write a `:`
+// comment to each open session's downstream so intermediary proxies don't
+// idle-close it (nginx et al. default to a ~60s read timeout). This is the
+// server's own liveness upkeep — the client no longer POSTs a periodic ping
+// (which forced a stream takeover every tick).
+//
+// Reaping model (replaces the old POST-driven idle timer): a session is
+// dropped on its downstream response `close` — clean disconnect, or a
+// half-open socket the per-session TCP keepalive forces closed (see
+// SseSession.SOCKET_KEEPALIVE_MS) — NOT by this sweep. We intentionally
+// trust connection-level liveness. The one topology this can't see is a
+// buffering / TLS-terminating proxy that holds the upstream open after the
+// real client vanished (keepalive then probes the proxy hop, not the
+// client); such a session lingers until `maxSessions`, the hard backstop.
+// This is the same exposure the WS heartbeat already has (its ping only
+// proves the proxy↔server hop too), not a new class of leak.
+const KEEPALIVE_SWEEP_MS = 30_000
+
+export type SseServerDeps = {
+  // The WS dispatch is the cohesive unit; SSE just provides another
+  // transport into it. Closure over the same handler / hub / objstore
+  // / track / debug surface the WS path uses.
+  peerDeps: PeerConnectionDeps
+  // Shutdown gate. Mirror of the REST + WS branches in server-e2e/http.ts:
+  // an SSE POST arriving on an existing keep-alive socket after
+  // SIGTERM should be rejected, not dispatched against a draining DB.
+  isShuttingDown: () => boolean
+  // Max number of concurrent SSE sessions per process. Above this we
+  // 503 the open request. Caps the SSE-side equivalent of `wss.clients`.
+  maxSessions: number
+  // Max body size for one POST. Matches the WS `maxPayload` in
+  // server-e2e/index.ts so the SSE plane can't accept frames the WS plane
+  // would reject. The POST body envelope can hold multiple frames so
+  // the per-frame budget is the same as the WS plane after the
+  // dispatcher splits them.
+  maxBodyBytes: number
+  debug: boolean
+}
+
+export type SseServer = {
+  // Returns true if the request matched an SSE route (caller should
+  // not fall through to other handlers). false otherwise.
+  handle: (req: HttpRequest, res: ServerResponse) => boolean
+  // Iterates active sessions. Lifecycle's graceful-shutdown loop
+  // reads this to close SSE sessions alongside WS clients.
+  sessions: () => Iterable<SseSession>
+  // The keepalive-sweep timer. Lifecycle clears it on shutdown (parity
+  // with the WS heartbeat timer) so a tick can't fire mid-teardown.
+  keepaliveTimer: ReturnType<typeof setInterval>
+}
+
+// Inbound POST body. Every field optional — an empty-body POST is a
+// valid "wake the session" probe (the response stream rides on every
+// POST), and a body that carries only `password` or only `frames` is
+// a normal partial update. `id` is the session continuation token
+// (see the header's "Continuation" note for why it rides the body).
+type SseBody = {
+  id?: unknown
+  password?: unknown
+  frames?: unknown
+}
+
+export function installSseServer(deps: SseServerDeps): SseServer {
+  const { peerDeps, isShuttingDown, maxSessions, maxBodyBytes, debug } = deps
+
+  // Active SSE sessions, keyed by the random session id `createSession`
+  // mints on the first POST that carries no continuation id (or whose
+  // id this replica doesn't recognise) and that subsequent POSTs echo
+  // back (body `id` field) to continue the session. Bounded by
+  // `maxSessions` — over the cap, new POSTs get a 503. POSTs against an
+  // unknown id are NOT 404'd — they mint a fresh session instead, so a
+  // multi-replica deployment doesn't require sticky LB routing to
+  // recover.
+  const sessions = new Map<string, SseSession>()
+
+  function dropSession(sid: string): void {
+    sessions.delete(sid)
+  }
+
+  function writeSseHeaders(res: ServerResponse): void {
+    // `no-store` keeps stale event copies out of intermediate caches;
+    // `x-accel-buffering: no` is the nginx-specific opt-out from
+    // response buffering (without it nginx queues up to its
+    // `proxy_buffer_size` of events before flushing, breaking the
+    // realtime contract).
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-cache, no-store, no-transform',
+      'connection': 'keep-alive',
+      'x-accel-buffering': 'no',
+    })
+    // Retry hint for any auto-reconnect machinery on the client side.
+    // The production client (client/sync/sse-transport.ts) does its own
+    // reconnect via the outer socket-transport loop, so this is just
+    // defence in depth.
+    res.write('retry: 1000\n\n')
+  }
+
+  function createSession(res: ServerResponse, req: HttpRequest): SseSession | null {
+    if (sessions.size >= maxSessions) {
+      if (debug) console.warn(`sse: refused open — sessions ${sessions.size} >= ${maxSessions}`)
+      return null
+    }
+    writeSseHeaders(res)
+    const sid = randomId()
+    const session = new SseSession(res)
+    sessions.set(sid, session)
+    session.on('close', () => { dropSession(sid) })
+    // Announce the continuation token BEFORE the dispatcher emits its
+    // `challenge` frame so the client latches the id first and the
+    // protocol-level challenge lands on a stream the client is already
+    // tracking. Both ride the same response — order is a wire-shape
+    // nicety, not a correctness requirement (events are independent).
+    session.writeEvent('session', sid)
+    // Hand the session to the shared WS connection setup so it joins
+    // the same Peer / dispatcher / hub lifecycle as a real WebSocket.
+    // `setupPeerConnection`'s first action is the protocol `challenge`
+    // frame, on the default-named SSE channel.
+    setupPeerConnection(session as unknown as WebSocket, req, peerDeps)
+    return session
+  }
+
+  // Drives a POST body's `password` and `frames` through the shared
+  // dispatcher. The dispatcher's `ping` / `authenticate` fast paths
+  // handle the trivial cases inline; everything else spawns a tracked
+  // handler. We synthesise one synthetic frame per inbound bit so the
+  // dispatcher reads identically whether it's reading WS frames or
+  // SSE POST batches.
+  function dispatchBody(session: SseSession, body: SseBody): void {
+    // Password → synthetic `authenticate` frame so the shared
+    // dispatcher's existing fast path runs unchanged. Client caches
+    // the password and re-sends on every POST, so the first POST
+    // after a session takeover re-authenticates silently on the new
+    // replica without an extra round-trip.
+    if (typeof body.password === 'string' && body.password.length > 0) {
+      const buf = Buffer.from(JSON.stringify({ type: 'authenticate', password: body.password }), 'utf8')
+      session.receiveMessage(buf)
+    }
+    if (Array.isArray(body.frames)) {
+      for (const frame of body.frames) {
+        if (!frame || typeof frame !== 'object') continue
+        const buf = Buffer.from(JSON.stringify(frame), 'utf8')
+        session.receiveMessage(buf)
+      }
+    }
+  }
+
+  function handlePost(req: HttpRequest, res: ServerResponse, sidFromUrl: string | null): void {
+    if (isShuttingDown()) {
+      res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
+      res.end(JSON.stringify({ error: 'shutting-down' }))
+      return
+    }
+    // Bound the body the same way `WebSocketServer({ maxPayload })`
+    // bounds a WS frame. Slurp into a single buffer rather than
+    // streaming — every protocol frame fits comfortably under
+    // `maxBodyBytes` (4 MiB) and the dispatcher takes one buffer at a
+    // time anyway. `content-length` may be missing on chunked-encoded
+    // requests; rely on the accumulating size check.
+    const chunks: Buffer[] = []
+    let total = 0
+    let aborted = false
+    req.on('data', (chunk: Buffer) => {
+      if (aborted) return
+      total += chunk.length
+      if (total > maxBodyBytes) {
+        aborted = true
+        if (debug) console.warn(`sse: POST body too large (${total} > ${maxBodyBytes})`)
+        res.writeHead(413, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ error: 'too-large' }))
+        try { req.destroy() } catch {}
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      if (aborted) return
+      // Re-check shutdown: the entry gate at handlePost runs at request
+      // arrival, but the body read is async — a slow upload that
+      // started pre-SIGTERM can fire 'end' AFTER the lifecycle's
+      // sseSessions() close-loop has already iterated, and createSession
+      // would otherwise add a NEW session post-iteration that only
+      // gets force-killed by the terminate-grace timer (no graceful
+      // event:close frame). Bail with 503 so the client distinguishes
+      // shutdown from a transport error and short-circuits backoff.
+      if (isShuttingDown()) {
+        res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
+        res.end(JSON.stringify({ error: 'shutting-down' }))
+        return
+      }
+      let body: SseBody = {}
+      if (chunks.length > 0) {
+        try {
+          const parsed: unknown = JSON.parse(Buffer.concat(chunks, total).toString('utf8'))
+          if (parsed && typeof parsed === 'object') body = parsed as SseBody
+        } catch (err) {
+          if (debug) console.warn('sse: malformed POST body:', errMsg(err))
+          res.writeHead(400, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ error: 'bad-json' }))
+          return
+        }
+      }
+      // Resolve the continuation token: the JSON body's `id` is the
+      // canonical carrier; the `?id=` query form is the legacy
+      // fallback for older client bundles (see the header note — a
+      // query sid leaks into access logs). Body wins when both are
+      // present (current clients only ever send one).
+      const sid = parseSid(body.id) ?? sidFromUrl
+      // Look up the session by id (if the client sent one). If found
+      // and alive, attach the new response and dispatch. If not (or
+      // session is closed), mint a fresh one — the response stream
+      // carries the new id as the first `session` event so the client
+      // switches over on the next POST.
+      //
+      // Attach-then-write ordering: attachResponse runs FIRST and only
+      // on success do we writeSseHeaders. If attachResponse returns
+      // false (today only when the session transitions out of OPEN
+      // between the lookup and the attach — a future backpressure /
+      // takeover-rate path could surface that legitimately) we fall
+      // through to createSession with `res` still header-virgin, so
+      // the new session can writeSseHeaders without ERR_HTTP_HEADERS_SENT.
+      let session: SseSession | null = null
+      if (sid) {
+        const existing = sessions.get(sid)
+        if (existing && existing.readyState === existing.OPEN && existing.attachResponse(res)) {
+          writeSseHeaders(res)
+          session = existing
+        }
+      }
+      if (!session) {
+        session = createSession(res, req)
+        if (!session) {
+          // Cap exceeded; createSession already logged. Response
+          // headers not yet written by writeSseHeaders, so send a
+          // 503 JSON instead.
+          res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
+          res.end(JSON.stringify({ error: 'too-many-sessions' }))
+          return
+        }
+      }
+      dispatchBody(session, body)
+      // Do NOT res.end() — the response stays open as the session's
+      // downstream channel until the next POST takes over (or the
+      // client disconnects).
+    })
+    req.on('error', (err) => {
+      if (debug) console.warn('sse: POST stream error:', errMsg(err))
+      if (res.headersSent) {
+        try { res.destroy() } catch {}
+      } else {
+        try { res.writeHead(400, { 'content-type': 'application/json' }).end(JSON.stringify({ error: 'bad-request' })) } catch {}
+      }
+    })
+  }
+
+  function handle(req: HttpRequest, res: ServerResponse): boolean {
+    if (typeof req.url !== 'string') return false
+    const [path, query] = req.url.split('?', 2)
+    if (path !== SSE_OPEN_PATH) return false
+    if (req.method !== 'POST') {
+      // `connection: close` so a probing client (e.g. accidental GET)
+      // can't pipeline N more 405s on the same keep-alive socket.
+      // Sibling 503 paths set this for the same reason.
+      res.writeHead(405, { 'content-type': 'application/json', 'allow': 'POST', 'connection': 'close' })
+      res.end(JSON.stringify({ error: 'method-not-allowed' }))
+      return true
+    }
+    const sid = parseSidQuery(query)
+    handlePost(req, res, sid)
+    return true
+  }
+
+  // Server-driven keepalive sweep. Writes a `:` comment to every open
+  // session's downstream so proxies don't idle-close it. `unref` so it can't
+  // by itself hold the event loop open (parity with the WS heartbeat timer);
+  // skipped during shutdown so a tick can't write to a session the close
+  // loop is tearing down. Dead-session reaping is the response `close` event
+  // (see SseSession.wireResponse + the per-session TCP keepalive), NOT this
+  // sweep — so a half-open client is dropped without ever POSTing.
+  const keepaliveTimer = setInterval(() => {
+    if (isShuttingDown()) return
+    for (const session of sessions.values()) {
+      try { session.ping() } catch {}
+    }
+  }, KEEPALIVE_SWEEP_MS)
+  keepaliveTimer.unref?.()
+
+  return { handle, sessions: () => sessions.values(), keepaliveTimer }
+}
+
+// Shape gate for a continuation token from either carrier (body `id`
+// field or the legacy `?id=` query). The {1,64} bound is a
+// deliberately lenient sanity gate: anything outside the base64url
+// alphabet is rejected; an unrecognised sid just gets a fresh session
+// from createSession (no failure mode), and the wide length window
+// keeps a future randomId-length change from silently breaking old
+// clients that round-trip a longer/shorter token. Returns null on
+// missing / non-string / malformed.
+function parseSid(v: unknown): string | null {
+  if (typeof v !== 'string') return null
+  if (!/^[A-Za-z0-9_-]{1,64}$/u.test(v)) return null
+  return v
+}
+
+// Bare-bones query parse for the LEGACY `id=<base64url>` carrier
+// (older client bundles; current clients send the sid in the POST
+// body — see the header's "Continuation" note). Avoids URLSearchParams
+// (which decodes percent-escapes) — `randomId()` mints a 22-char
+// base64url string echoed back unchanged, so no escapes are possible
+// on the legitimate path.
+function parseSidQuery(query: string | undefined): string | null {
+  if (typeof query !== 'string') return null
+  for (const part of query.split('&')) {
+    const eq = part.indexOf('=')
+    if (eq <= 0) continue
+    if (part.slice(0, eq) !== 'id') continue
+    return parseSid(part.slice(eq + 1))
+  }
+  return null
+}

package/server-e2e/sse-session.ts

@@ -0,0 +1,216 @@
+// Per-connection state for the SSE+POST fallback. Each session pins to
+// the *latest* POST's response stream — the previous POST's response
+// is closed when a new POST takes over. This shape sidesteps sticky-
+// routing in multi-replica deployments: a POST that lands on a
+// replica that doesn't know the session id mints a fresh session with
+// a new id (returned via the first `session` event); the client then
+// continues against the new id with all subsequent POSTs. Subscriptions
+// and auth state ride re-sendable signed frames + a client-cached
+// password, so the new replica reconstructs locally.
+//
+// Mimics the subset of `ws.WebSocket` that `setupPeerConnection` (in
+// ./ws-server.ts), the hub (./hub.ts) and the lifecycle shutdown loop
+// (./lifecycle.ts) read: `readyState` + `OPEN`/`CLOSING` constants,
+// `send` / `close` / `terminate` / `ping`, the `bufferedAmount`
+// backpressure signal, and the `message` / `close` / `error` / `pong`
+// EventEmitter surface. The per-connection dispatcher is single-
+// sourced — it doesn't know whether it's talking to a real WebSocket
+// or this adapter.
+//
+// Wire shape: each outbound frame becomes a single SSE `data:` field.
+// The dispatcher emits JSON via `JSON.stringify` (no embedded newlines
+// after that round-trip), so a single-line `data:` is enough; we still
+// split-on-newline defensively for any future caller that hands raw
+// multi-line text. Inbound frames are injected via `receiveMessage`
+// after the POST plane reads the body.
+
+import { EventEmitter } from 'node:events'
+import type { Buffer } from 'node:buffer'
+import type { ServerResponse } from 'node:http'
+
+// TCP keepalive idle delay for the downstream socket. With the client no
+// longer POSTing a periodic ping (see client/sync/socket-transport.ts), a
+// QUIET session whose client vanished without a FIN (crash, NAT/idle drop)
+// has no application-level liveness signal — so we lean on the kernel:
+// after this much idle the kernel starts probing, and a dead half-open
+// socket surfaces as a `close`/`error` here. Node's `setKeepAlive` sets
+// only TCP_KEEPIDLE (the delay to the FIRST probe), not the probe
+// interval/count — so full teardown is this delay PLUS the OS's
+// TCP_KEEPINTVL × TCP_KEEPCNT (~minutes on Linux defaults), still bounded
+// and far below the kernel's hours-long default-off behaviour. `maxSessions`
+// is the hard backstop. Behind a TLS-terminating / buffering proxy this
+// probes the proxy hop, not the client — see the reaping note in sse-server.ts.
+const SOCKET_KEEPALIVE_MS = 30_000
+
+export class SseSession extends EventEmitter {
+  static readonly CONNECTING = 0
+  static readonly OPEN = 1
+  static readonly CLOSING = 2
+  static readonly CLOSED = 3
+  // Per-instance constants so `socket.OPEN` reads identically to the
+  // `ws.WebSocket` shape the dispatcher and hub strict-compare against.
+  readonly CONNECTING = SseSession.CONNECTING
+  readonly OPEN = SseSession.OPEN
+  readonly CLOSING = SseSession.CLOSING
+  readonly CLOSED = SseSession.CLOSED
+
+  readyState: number = SseSession.OPEN
+  // The current downstream stream the session writes to. Each POST
+  // replaces this; broadcasts and ack frames flow on the latest one.
+  // Null between POSTs is *only* a transient state during swap — the
+  // session is created with a response in hand and the swap is
+  // synchronous from the dispatcher's perspective.
+  private currentRes: ServerResponse | null
+
+  constructor(res: ServerResponse) {
+    super()
+    this.currentRes = res
+    this.wireResponse(res)
+  }
+
+  // Wire the close / error events on a freshly-attached response. The
+  // close event only matters for the *current* response — a previous
+  // response's close (after it was swapped out) is not a session-level
+  // signal. Same guard applies to error: a TCP-level error during
+  // res.end() flush on a swapped-out response would otherwise emit a
+  // spurious session 'error' that operators read as a real transport
+  // failure on a healthy session.
+  private wireResponse(res: ServerResponse): void {
+    // Probe half-open downstreams at the kernel level (see SOCKET_KEEPALIVE_MS).
+    // A failed probe trips the `close`/`error` handlers below, which is how a
+    // dead-but-quiet SSE client is reaped now that there's no client ping.
+    try { res.socket?.setKeepAlive(true, SOCKET_KEEPALIVE_MS) } catch {}
+    res.on('close', () => {
+      if (res !== this.currentRes) return  // current-response guard (see above)
+      if (this.readyState === SseSession.CLOSED) return
+      this.readyState = SseSession.CLOSED
+      this.currentRes = null
+      this.emit('close')
+    })
+    res.on('error', (err: Error) => {
+      if (res !== this.currentRes) return  // current-response guard (see above)
+      this.emit('error', err)
+    })
+  }
+
+  // Swap in a new response (the latest POST's body). The previous
+  // response is end()ed cleanly so the client's reader sees EOF and
+  // stops draining; the takeover-grace handling for in-flight buffered
+  // bytes is on the client side (it keeps reading the old stream until
+  // EOF before switching). Returns true when the session was alive and
+  // the swap happened; false when the session is closed and the new
+  // response should be ended by the caller.
+  attachResponse(res: ServerResponse): boolean {
+    if (this.readyState !== SseSession.OPEN) return false
+    const prev = this.currentRes
+    this.currentRes = res
+    this.wireResponse(res)
+    // End the previous stream AFTER the new one is wired so any
+    // broadcast racing the swap lands on the new response, not on the
+    // half-closed old one. `end()` flushes Node's send buffer before
+    // sending FIN — frames already written drain to the client.
+    if (prev) { try { prev.end() } catch {} }
+    return true
+  }
+
+  // `hub.sendRaw` consults this before each send to decide whether to
+  // terminate (slow / blackholed peer). `writableLength` is the count
+  // of bytes queued in Node's HTTP stream that haven't drained to the
+  // kernel yet — the SSE-channel equivalent of `ws`'s `bufferedAmount`.
+  get bufferedAmount(): number {
+    return this.currentRes?.writableLength ?? 0
+  }
+
+  // Encodes one JSON frame as a single SSE event. Splits on `\n` so a
+  // multi-line payload still produces a well-formed event (each `data:`
+  // line is concatenated with `\n` by the SSE parser on the client),
+  // but `JSON.stringify` output won't trigger that branch.
+  send(payload: string | Buffer): void {
+    if (this.readyState !== SseSession.OPEN) return
+    const res = this.currentRes
+    if (!res) return
+    const text = typeof payload === 'string' ? payload : payload.toString('utf8')
+    const lines = text.split('\n')
+    const wire = `${lines.map((l) => `data: ${l}`).join('\n')}\n\n`
+    try { res.write(wire) } catch {}
+  }
+
+  // Writes a named SSE event (e.g. `session` for the continuation token
+  // handshake). Used by sse-server.ts on session creation; not part of
+  // the WebSocket-shaped surface and never called by the shared
+  // dispatcher.
+  writeEvent(event: string, data: string): void {
+    if (this.readyState !== SseSession.OPEN) return
+    const res = this.currentRes
+    if (!res) return
+    const lines = data.split('\n')
+    const body = `${lines.map((l) => `data: ${l}`).join('\n')}`
+    try { res.write(`event: ${event}\n${body}\n\n`) } catch {}
+  }
+
+  // Lifecycle's graceful-shutdown loop calls this with `(1001, '…')` to
+  // signal a server-initiated close. SSE has no native close code, so
+  // we emit a structured `close` event with the WS-style `{ code,
+  // reason }` payload — the client's transport reads it and bypasses
+  // its reconnect backoff (parity with the WS 1001 path).
+  //
+  // emit('close') is fired EXPLICITLY here, not via the res.on('close')
+  // listener: that listener short-circuits on `readyState === CLOSED`
+  // (so a later async res-close after we've flipped state doesn't
+  // double-emit), which means without the explicit emit here neither
+  // sse-server's dropSession cleanup nor setupPeerConnection's
+  // unsubscribeAll/peers.delete would run on any server-initiated
+  // teardown — the sessions map / hub.subscribers would leak per close.
+  // The wireResponse guard then ensures the later async fire is a no-op.
+  close(code?: number, reason?: string): void {
+    if (this.readyState === SseSession.CLOSED) return
+    const res = this.currentRes
+    if (this.readyState === SseSession.OPEN && code != null && res) {
+      try { res.write(`event: close\ndata: ${JSON.stringify({ code, reason: reason ?? '' })}\n\n`) } catch {}
+    }
+    this.readyState = SseSession.CLOSING
+    if (res) { try { res.end() } catch {} }
+    this.currentRes = null
+    this.readyState = SseSession.CLOSED
+    this.emit('close')
+  }
+
+  // Force-tear without flushing — mirrors `ws.terminate()`. Hub's
+  // backpressure path and the lifecycle's terminate-grace timer call
+  // this to drop unresponsive peers. Same explicit `emit('close')`
+  // story as close() above — without it, the wireResponse guard would
+  // swallow the later async res-close and the cleanup callbacks
+  // (dropSession, peers.delete, unsubscribeAll) would never run.
+  terminate(): void {
+    if (this.readyState === SseSession.CLOSED) return
+    this.readyState = SseSession.CLOSED
+    const res = this.currentRes
+    this.currentRes = null
+    if (res) { try { res.destroy() } catch {} }
+    this.emit('close')
+  }
+
+  // Server-driven keepalive, called on the SSE keepalive sweep in
+  // sse-server.ts. SSE has no `pong` equivalent, so we write a `:` comment
+  // line — ignored by the client parser — that keeps the downstream from
+  // being idle-closed by intermediary proxies (nginx et al. default to a
+  // ~60s read timeout). Dead-client detection is the response `close` event
+  // (clean disconnect, or a half-open socket the TCP keepalive in
+  // `wireResponse` forces closed), NOT this write: a `:`-comment write to a
+  // half-open socket just buffers, it doesn't synchronously throw.
+  ping(): void {
+    if (this.readyState !== SseSession.OPEN) return
+    const res = this.currentRes
+    if (!res) return
+    try { res.write(':\n\n') } catch {}
+  }
+
+  // Injects a client-to-server frame from the POST plane into the same
+  // `message` event the dispatcher already listens for on real WSs.
+  // `isBinary=false` because the SSE+POST plane is JSON-only by
+  // contract — the binary-frame drop in the dispatcher reads this.
+  receiveMessage(data: Buffer): void {
+    if (this.readyState !== SseSession.OPEN) return
+    this.emit('message', data, false)
+  }
+}

package/{server → server-e2e}/static.ts

@@ -64,15 +64,24 @@ const COMPRESSIBLE = new Set(['.html', '.css', '.js', '.svg', '.webmanifest'])
 // navigated `image/svg+xml` icon into something script-executable.
 // `no-referrer` keeps URLs of this (potentially sensitive) viewer out
 // of outbound Referer headers, and `same-origin` CORP stops other
-// origins embedding these bytes. CSP is deliberately NOT here: the
-// HTML documents carry their own per-page `<meta http-equiv>` policy
-// (and the three pages differ), so a blanket header CSP would just AND
-// against the meta one and risk breaking a page — non-document assets
-// get their own flat CSP via `StaticEntry.csp` instead.
+// origins embedding these bytes. COOP `same-origin` severs the
+// window.opener link to any cross-origin opener/popup (so an external
+// `target=_blank` GitHub/Claude link can't reach back into this context),
+// and COEP `require-corp` bars the document from loading any cross-origin
+// subresource that doesn't opt in via CORP/CORS. Together they also make
+// the page cross-origin-isolated. Safe here because the bundle is fully
+// same-origin (no external scripts/images/fonts/iframes) — switch COEP to
+// `credentialless` if a cross-origin resource is ever added. CSP is
+// deliberately NOT here: the HTML documents carry their own per-page
+// `<meta http-equiv>` policy (and the three pages differ), so a blanket
+// header CSP would just AND against the meta one and risk breaking a page
+// — non-document assets get their own flat CSP via `StaticEntry.csp`.
 const SECURITY_HEADERS = {
   'x-content-type-options': 'nosniff',
   'referrer-policy': 'no-referrer',
   'cross-origin-resource-policy': 'same-origin',
+  'cross-origin-opener-policy': 'same-origin',
+  'cross-origin-embedder-policy': 'require-corp',
 } as const
 
 type StaticEntry = {
@@ -169,11 +178,9 @@ function buildEntry(staticDir: string, name: string): StaticEntry {
   const ext = extname(name)
   const raw = readFileSync(join(staticDir, name))
   const type = CONTENT_TYPE[ext] ?? 'application/octet-stream'
-  // HTML: lift `<link rel="(module)preload" …>` into a Link header
-  // and drop the tags from the served body so the bytes ship without
-  // the now-redundant in-body hint. ETag + compression run against
-  // the stripped body — the on-disk file and the served body diverge
-  // by exactly the lifted tags.
+  // HTML: lift `<link rel="(module)preload" …>` into a Link header and
+  // drop the tags from the served body. ETag + compression run against
+  // the stripped body (see the header note on the divergence).
   let identity = raw
   let link: string | null = null
   if (ext === '.html') {
@@ -273,13 +280,11 @@ function isUnsafeAttr(s: string): boolean {
   return /[\r\n",;<>]/u.test(s)
 }
 
-// Find character ranges in `html` whose contents are NOT real HTML
-// content: comment bodies and script / noscript raw-text bodies. A
-// `<link>` whose match offset falls inside any range is preserved
-// verbatim (no header lift). Heuristic: a real HTML parser is
-// overkill here — the build emits clean, well-formed markup; this is
-// defence against the build (or a hand edit) accidentally mentioning
-// `<link rel="preload">` somewhere it isn't meant to fire.
+// Char ranges in `html` whose contents are NOT real HTML content:
+// comment bodies and script / noscript raw-text bodies. A `<link>`
+// whose match offset falls in any range is preserved verbatim (no
+// header lift — see the call site for why). Heuristic, not a real
+// parser: the build emits clean, well-formed markup.
 function findSkipRanges(html: string): Array<[number, number]> {
   const ranges: Array<[number, number]> = []
   const patterns = [