@preventive/triage 1.0.0-alpha.1 → 1.0.0-alpha.11

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

@@ -8,9 +8,10 @@
 //
 // One route, POSTs only:
 //
-//   POST /api/sync/sse[?id=<sid>]
+//   POST /api/sync/sse
 //       Request body:
-//         { password?: string,                   — cached client password
+//         { id?: string,                         — session continuation token
+//           password?: string,                   — cached client password
 //           frames?:   Array<protocol-frame>     — WS-style JSON frames
 //         }
 //       Response:
@@ -25,14 +26,23 @@
 //         carrying the WS protocol's JSON envelopes.
 //
 // Continuation: each POST replaces the previous POST's response as the
-// session's downstream channel. If the `?id=<sid>` in the URL 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).
+// 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
@@ -47,17 +57,35 @@ 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/http.ts WS_UPGRADE_PATH
+// 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/http.ts:
+  // 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
@@ -65,17 +93,11 @@ export type SseServerDeps = {
   // 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/index.ts so the SSE plane can't accept frames the WS plane
+  // 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
-  // Idle timeout for a session with no inbound POSTs. Detects the
-  // wandered-off browser tab the WS heartbeat sweep handles via
-  // ping/pong on real sockets. The client's JSON ping/pong heartbeat
-  // (every 15s) is the steady-state liveness signal; this is the
-  // hard ceiling.
-  sessionIdleMs: number
   debug: boolean
 }
 
@@ -86,48 +108,37 @@ export type SseServer = {
   // 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.
+// 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, sessionIdleMs, debug } = deps
+  const { peerDeps, isShuttingDown, maxSessions, maxBodyBytes, debug } = deps
 
   // Active SSE sessions, keyed by the random session id `createSession`
-  // mints on the first POST that lacks a `?id=` (or whose id this
-  // replica doesn't recognise) and that subsequent POSTs echo back 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.
+  // 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>()
-  // Per-session idle timer handle. Reset on every inbound POST; fires
-  // after `sessionIdleMs` of silence to close a stranded session.
-  const idleTimers = new Map<string, ReturnType<typeof setTimeout>>()
-
-  function armIdleTimer(sid: string, session: SseSession): void {
-    clearTimeout(idleTimers.get(sid))
-    if (sessionIdleMs <= 0) return
-    const t = setTimeout(() => {
-      if (debug) console.warn(`sse: session ${sid.slice(0, 8)}… idle ${sessionIdleMs}ms → close`)
-      try { session.terminate() } catch {}
-    }, sessionIdleMs)
-    t.unref?.()
-    idleTimers.set(sid, t)
-  }
 
   function dropSession(sid: string): void {
     sessions.delete(sid)
-    const t = idleTimers.get(sid)
-    if (t) clearTimeout(t)
-    idleTimers.delete(sid)
   }
 
   function writeSseHeaders(res: ServerResponse): void {
@@ -149,7 +160,7 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     res.write('retry: 1000\n\n')
   }
 
-  function createSession(res: ServerResponse, req: HttpRequest): { sid: string; session: SseSession } | null {
+  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
@@ -158,7 +169,6 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     const sid = randomId()
     const session = new SseSession(res)
     sessions.set(sid, session)
-    armIdleTimer(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
@@ -168,11 +178,10 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     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` sends the protocol `challenge` frame as
-    // its first action; that re-uses the normal default-named SSE
-    // message channel.
+    // `setupPeerConnection`'s first action is the protocol `challenge`
+    // frame, on the default-named SSE channel.
     setupPeerConnection(session as unknown as WebSocket, req, peerDeps)
-    return { sid, session }
+    return session
   }
 
   // Drives a POST body's `password` and `frames` through the shared
@@ -255,6 +264,12 @@ export function installSseServer(deps: SseServerDeps): SseServer {
           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
@@ -269,19 +284,16 @@ export function installSseServer(deps: SseServerDeps): SseServer {
       // through to createSession with `res` still header-virgin, so
       // the new session can writeSseHeaders without ERR_HTTP_HEADERS_SENT.
       let session: SseSession | null = null
-      let sid: string | null = null
-      if (sidFromUrl) {
-        const existing = sessions.get(sidFromUrl)
+      if (sid) {
+        const existing = sessions.get(sid)
         if (existing && existing.readyState === existing.OPEN && existing.attachResponse(res)) {
           writeSseHeaders(res)
           session = existing
-          sid = sidFromUrl
-          armIdleTimer(sid, session)
         }
       }
       if (!session) {
-        const created = createSession(res, req)
-        if (!created) {
+        session = createSession(res, req)
+        if (!session) {
           // Cap exceeded; createSession already logged. Response
           // headers not yet written by writeSseHeaders, so send a
           // 503 JSON instead.
@@ -289,8 +301,6 @@ export function installSseServer(deps: SseServerDeps): SseServer {
           res.end(JSON.stringify({ error: 'too-many-sessions' }))
           return
         }
-        session = created.session
-        sid = created.sid
       }
       dispatchBody(session, body)
       // Do NOT res.end() — the response stays open as the session's
@@ -324,29 +334,51 @@ export function installSseServer(deps: SseServerDeps): SseServer {
     return true
   }
 
-  return { handle, sessions: () => sessions.values() }
+  // 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 }
 }
 
-// Bare-bones query parse for `id=<base64url>`. Avoids URLSearchParams
-// (which decodes percent-escapes) — `randomId()` mints a 22-char
-// base64url string, and the client echoes it back unchanged, so no
-// escapes are possible on the legitimate path. The {1,64} bound is a
+// 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 (and a missing id is treated as "no id"); a
-// client that sent a sid this regex doesn't recognise just gets a
-// fresh session minted by createSession, no failure mode. The wide
-// length window means a future randomId-length change here doesn't
-// silently break old clients that round-trip a longer or shorter
-// token. Returns null on missing / malformed.
+// 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
-    const v = part.slice(eq + 1)
-    if (!/^[A-Za-z0-9_-]{1,64}$/u.test(v)) return null
-    return v
+    return parseSid(part.slice(eq + 1))
   }
   return null
 }

package/{server → server-e2e}/sse-session.ts

@@ -28,6 +28,20 @@ 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
@@ -62,21 +76,19 @@ export class SseSession extends EventEmitter {
   // 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', () => {
-      // Only the *current* response's close terminates the session. A
-      // swapped-out previous response closes naturally during takeover
-      // and must not knock the session offline.
-      if (res !== this.currentRes) return
+      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) => {
-      // Same identity guard as close: drained-out previous responses
-      // may emit RST/EPIPE during flush and we don't want those to
-      // pseudo-fail the healthy session that's now on a new response.
-      if (res !== this.currentRes) return
+      if (res !== this.currentRes) return  // current-response guard (see above)
       this.emit('error', err)
     })
   }
@@ -148,9 +160,8 @@ export class SseSession extends EventEmitter {
   // 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 — sessions / hub.subscribers / idleTimers would leak per
-  // close. The wireResponse guard then ensures the later async fire
-  // is a no-op.
+  // 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
@@ -179,11 +190,14 @@ export class SseSession extends EventEmitter {
     this.emit('close')
   }
 
-  // The heartbeat sweep ping()s every WS client to detect dead sockets
-  // via the unanswered-pong path. SSE has no `pong` equivalent, so we
-  // write a comment line that keeps the channel alive across proxies
-  // without expecting a reply. The per-session idle timeout in
-  // sse-server.ts owns the dead-client detection.
+  // 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

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 = [