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

package/server/index.ts

@@ -73,7 +73,7 @@
 // and would not reject the attaching socket.
 
 import { type WebSocket, WebSocketServer } from 'ws'
-import { errMsg } from './util.ts'
+import { errMsg, errStack } from './util.ts'
 import type { PeerRegistry } from './peer.ts'
 import { LOOPBACK_HOSTS, createOriginGate } from './origin.ts'
 import { createHub } from './hub.ts'
@@ -81,6 +81,7 @@ import { createAuth } from './auth.ts'
 import { createSyncHandlers } from './sync-handlers.ts'
 import { WS_UPGRADE_PATH, createHttpServer } from './http.ts'
 import { installWsServer } from './ws-server.ts'
+import { SSE_OPEN_PATH, installSseServer } from './sse-server.ts'
 import { createLifecycle } from './lifecycle.ts'
 import { loadConfig } from './config.ts'
 import { type Handle, openDb } from './db.ts'
@@ -89,6 +90,11 @@ import { initObjstore } from './objstore/init.ts'
 import { type Handle as ObjstoreHandle, listLive, objectMetaWire, openObjstore } from './objstore/store.ts'
 import { openNeonObjstore } from './objstore/store-neon.ts'
 import { openVercelBlobBackend } from './objstore/blob-vercel.ts'
+import {
+  type NeonClientCtor, type PubSub,
+  createNeonPubSub, createNoopPubSub,
+} from './pubsub.ts'
+import { createBusReceiver } from './bus-receiver.ts'
 
 // All external inputs (env vars + optional config.json) are parsed
 // and validated in ./config.ts. Destructure into the existing
@@ -235,7 +241,39 @@ async function workspaceExists(tag: string): Promise<boolean> {
 // broadcast (see ./hub.ts). Destructure into the existing names so the
 // handlers / dispatcher / objstore wiring below read unchanged.
 const hub = createHub({ peers, maxBufferedBytes: MAX_BUFFERED_BYTES, debug: DEBUG })
-const { send, broadcast, subscribe, unsubscribeAll } = hub
+const { send, broadcast, subscribe, unsubscribeAll, broadcastLocalRaw } = hub
+
+// Cross-instance pub/sub for live broadcasts (see ./pubsub.ts). SQLite
+// mode is single-process by construction so it gets a no-op; Neon mode
+// uses Postgres LISTEN/NOTIFY on a dedicated long-lived Client
+// connection (separate from the HTTP `neon()` callable the queries flow
+// over — LISTEN needs a session-bound socket, the HTTP path is
+// stateless). The bus carries lookup hints, not the full wire payload:
+// the `workspace-state` broadcast's ciphertext alone can exceed the
+// ~8 KB NOTIFY payload cap, so the receiver re-fetches from the shared
+// DB to construct the wire frame. The bus is best-effort fan-out, not a
+// durability layer — the DB itself is the source of truth, and a
+// dropped publish only means peers on other instances miss the live
+// push (they still catch up via the chain on their next subscribe).
+let pubsub: PubSub = createNoopPubSub()
+if (NEON_URL) {
+  // Dynamic import: the Client export lives in the same optional peer
+  // dep as the HTTP `neon()` callable (see ./neon-driver.ts), but the
+  // dep itself is only present on a Neon-mode deploy. The wrapper path
+  // also lets tests swap in a PGlite-backed shim (`tests/pubsub.test.js`).
+  const mod = (await import('./neon-driver.ts')) as unknown as { Client?: NeonClientCtor }
+  if (!mod.Client) {
+    console.error('DATABASE_URL is set but the @neondatabase/serverless Client export is not available.')
+    console.error('Cross-instance broadcasts require the WebSocket-based Client (the HTTP `neon()` callable cannot LISTEN).')
+    console.error('Reinstall the peer dep: pnpm add @neondatabase/serverless')
+    process.exit(1)
+  }
+  const NeonClientImpl = mod.Client
+  pubsub = createNeonPubSub({
+    newClient: () => new NeonClientImpl(NEON_URL),
+    debug: DEBUG,
+  })
+}
 
 // Password gate (see ./auth.ts) — HMAC derivation + the `authenticate`
 // handshake. Destructure into the existing names for the wiring below.
@@ -247,8 +285,18 @@ const { requiresAuth, handleAuthenticate, sendUnauthorized } = auth
 // wiring below; `sendSaveError` is reused by the dispatcher's `busy`
 // inflight-cap NACK path.
 const getNonce = (socket: WebSocket): string | undefined => peers.get(socket)?.challenge
+const publishRevision = (tag: string, revisionId: string): void => {
+  pubsub.publish({ kind: 'rev', tag, id: revisionId })
+}
+const publishObjPut = (tag: string, resourceTag: string): void => {
+  pubsub.publish({ kind: 'objput', tag, res: resourceTag })
+}
+const publishObjDeleted = (tag: string, resourceTag: string, version: number): void => {
+  pubsub.publish({ kind: 'objdel', tag, res: resourceTag, ver: version })
+}
+
 const { handleSave, handleSubscribe, sendSaveError } = createSyncHandlers({
-  handle, send, broadcast, subscribe, getNonce,
+  handle, send, broadcast, publishRevision, subscribe, getNonce,
   requiresAuth, sendUnauthorized, workspaceExists,
   // Folds the objstore inventory into the `workspace-subscribed` ack.
   // The objstore store keeps its own richer `Handle`, so we wire the
@@ -260,7 +308,8 @@ const { handleSave, handleSubscribe, sendSaveError } = createSyncHandlers({
 
 const { handlers: objstore, restDeps: objstoreRestDeps, startupReap, stopReaper } = initObjstore({
   handle: objstoreHandle, reapIntervalMs: OBJSTORE_REAP_INTERVAL_MS,
-  send, broadcast, getNonce, debug: DEBUG,
+  send, broadcast, publishObjPut, publishObjDeleted,
+  getNonce, debug: DEBUG,
   // Auth gate for the FIRST objstore-put-begin against a workspace
   // that doesn't yet exist on the server. Mirrors handleSave's gate
   // below; handlers.ts calls this AFTER sig verify so the
@@ -289,12 +338,46 @@ const wss = new WebSocketServer({ noServer: true, maxPayload: 4 * 1024 * 1024 })
 // every server object exists.
 const { track, isShuttingDown, install: installLifecycle } = createLifecycle()
 
-// HTTP plane: REST byte-transfer routing + the WS upgrade gate (see
-// ./http.ts). Built after the lifecycle state above because the REST
-// shutdown gate reads `shuttingDown` and the request drain uses
-// `track`. The WS connection handler is wired on `wss` below.
+// Shared per-connection dispatch surface. Both the WS plane
+// (installWsServer below) and the SSE+POST fallback (installSseServer
+// below) drive `setupPeerConnection` with this; one Peer per accepted
+// connection, one message-handler tree.
+const peerConnectionDeps = {
+  peers, send, unsubscribeAll,
+  handleSave, handleSubscribe, handleAuthenticate, sendSaveError, objstore,
+  track, isShuttingDown,
+  maxInflightPerSocket: MAX_INFLIGHT_PER_SOCKET,
+  debug: DEBUG,
+}
+
+// SSE+POST fallback transport (see ./sse-server.ts). The WS upgrade is
+// the preferred path; clients fall back to SSE when `new WebSocket(…)`
+// fails to open (corporate proxies that strip the Upgrade header,
+// hostile network middleboxes, etc.). Same protocol on the wire — only
+// the byte transport differs.
+const sseServer = installSseServer({
+  peerDeps: peerConnectionDeps, isShuttingDown,
+  // Same cap shape as `wss` (no explicit per-process cap; OS FD limits
+  // are the upstream bound). 1024 leaves room above the typical web
+  // session count without being a soft DoS hammer.
+  maxSessions: 1024,
+  // Mirror the WS `maxPayload` so the SSE plane can't accept frames
+  // the WS plane would reject.
+  maxBodyBytes: 4 * 1024 * 1024,
+  // 90s idle ceiling. The client's JSON ping/pong is 15s; this is ~6
+  // missed pings before we close — well past any transient network
+  // hiccup, much shorter than the kernel's hours-long TCP keepalive.
+  sessionIdleMs: 90_000,
+  debug: DEBUG,
+})
+
+// HTTP plane: REST byte-transfer routing + SSE fallback + the WS
+// upgrade gate (see ./http.ts). Built after the lifecycle state above
+// because the REST shutdown gate reads `shuttingDown` and the request
+// drain uses `track`. The WS connection handler is wired on `wss`
+// below.
 const httpServer = createHttpServer({
-  wss, restDeps: objstoreRestDeps, isOriginAllowed,
+  wss, restDeps: objstoreRestDeps, sseServer, isOriginAllowed,
   isShuttingDown, track,
   restPutIdleTimeoutMs: REST_PUT_IDLE_TIMEOUT_MS, debug: DEBUG,
 })
@@ -303,11 +386,8 @@ const httpServer = createHttpServer({
 // sweep (see ./ws-server.ts). Returns the heartbeat timer so shutdown
 // can clear it.
 const { heartbeatTimer } = installWsServer({
-  wss, peers, send, unsubscribeAll,
-  handleSave, handleSubscribe, handleAuthenticate, sendSaveError, objstore,
-  track, isShuttingDown,
-  maxInflightPerSocket: MAX_INFLIGHT_PER_SOCKET, heartbeatIntervalMs: HEARTBEAT_INTERVAL_MS,
-  debug: DEBUG,
+  wss, heartbeatIntervalMs: HEARTBEAT_INTERVAL_MS,
+  ...peerConnectionDeps,
 })
 
 httpServer.on('listening', () => {
@@ -323,12 +403,40 @@ httpServer.on('listening', () => {
   // doesn't claim a misleading DB_PATH under Neon, or a misleading
   // OBJSTORE_DIR under Vercel Blob.
   const dbBanner = NEON_URL ? 'db: neon-postgres' : `db: ${DB_PATH}`
-  console.log(`DeepView triage-sync server: ws://${HOST}:${boundPort}${WS_UPGRADE_PATH} http://${HOST}:${boundPort}/api/objstore/{workspaceTag}/{resourceTag} (${dbBanner}, ${objstoreBanner})`)
+  console.log(`DeepView triage-sync server: ws://${HOST}:${boundPort}${WS_UPGRADE_PATH} (sse fallback http://${HOST}:${boundPort}${SSE_OPEN_PATH}) http://${HOST}:${boundPort}/api/objstore/{workspaceTag}/{resourceTag} (${dbBanner}, ${objstoreBanner})`)
+})
+
+// Cross-instance bus receiver (see ./bus-receiver.ts): a remote NOTIFY
+// lands here, we re-fetch any data the bus payload only hinted at,
+// then broadcast to local peers via `broadcastLocalRaw`. Extracted so
+// the rev / objput / objdel mapping (including the keyframe boolean
+// coercion and the `objectMetaWire` shape) is testable without the
+// full server bring-up.
+const onBusMessage = createBusReceiver({
+  handle, objstoreHandle, broadcastLocalRaw, debug: DEBUG,
+})
+
+// Kick off the LISTEN loop in the background. `pubsub.start` resolves
+// only after the FIRST successful connect, and the internal reconnect
+// loop retries indefinitely on transport / LISTEN failure — awaiting
+// it here would convert a transient Neon WS hiccup at boot into a
+// server that never binds (and a `.catch` that never runs). Instead
+// the server binds immediately and the bus comes up async; publishes
+// during the down window drop silently (best-effort semantics
+// documented in pubsub.ts). The SQLite no-op resolves immediately,
+// so the behaviour is identical in that mode.
+void pubsub.start(onBusMessage).catch((err) => {
+  console.warn('pubsub: startup error:', errStack(err))
 })
 
 // App-specific shutdown step (run after the in-flight drain), wired
 // into the lifecycle teardown below.
 const closeDb = async (): Promise<void> => {
+  // Stop the bus first so a publish from a still-draining handler
+  // can't fire into a half-closed Client. The in-flight drain runs
+  // before this (see lifecycle.ts), so by here all `broadcast` →
+  // `publish*` calls are settled.
+  try { await pubsub.stop() } catch (err) { console.warn('pubsub close error:', errMsg(err)) }
   // objstoreHandle has no close(): SQLite shares this DatabaseSync and
   // Neon has no persistent connection; `handle.close()` covers both.
   try { await handle.close() } catch (err) { console.warn('DB close error:', errMsg(err)) }
@@ -338,16 +446,36 @@ const closeDb = async (): Promise<void> => {
 // and the heartbeat timer all exist.
 installLifecycle({
   httpServer, wss, heartbeatTimer, stopReaper,
+  sseSessions: sseServer.sessions,
   closeDb,
 })
 
 // Bind only after the startup orphan sweep finishes — otherwise a
 // fresh boot could serve traffic against tags whose on-disk state
-// still has residue from a prior crash. Top-level await is fine
-// for an entry-point ESM module (no other module imports this for
-// its exports — the side effect IS the program). `startupReap`
-// already resolves on any error (the reaper's own catch logs the
-// failure unconditionally and returns void), so no outer `.catch`
-// is needed here.
+// still has residue from a prior crash. `startupReap` already
+// resolves on any error (the reaper's own catch logs the failure
+// unconditionally and returns void), so no outer `.catch` is
+// needed here.
 await startupReap
-httpServer.listen(PORT, HOST)
+
+// Start serving: bind the HTTP/WS plane on the configured PORT/HOST.
+// Exported as `start()` so a launcher (server/cli.js — the triage-server
+// bin) or any consumer that `import`ed this module can begin serving once
+// the top-level `await startupReap` above has settled (the server is fully
+// ready — DB open, DDL bootstrapped, objstore reaper swept — by the time
+// the import resolves).
+export function start(): void {
+  httpServer.listen(PORT, HOST)
+}
+
+export { httpServer, wss }
+
+// Library mode: when this module is `import`ed (rather than run as the
+// entry script) skip the auto-start so consumers can own the bind — e.g.
+// wrap CF Access / framework-preset shims around the assembled
+// `httpServer`, or just call `start()` when ready. Direct invocation via
+// `node server/index.ts` (or the `triage-server` bin) still listens.
+if (import.meta.main) {
+  start()
+}
+

package/server/lifecycle.ts

@@ -7,6 +7,7 @@
 
 import type { Server } from 'node:http'
 import type { WebSocketServer } from 'ws'
+import type { SseSession } from './sse-session.ts'
 import { errStack } from './util.ts'
 
 export type ShutdownDeps = {
@@ -15,6 +16,11 @@ export type ShutdownDeps = {
   heartbeatTimer: ReturnType<typeof setInterval>
   // Stops the periodic reaper AND awaits any in-flight sweep.
   stopReaper: () => Promise<void>
+  // Live SSE+POST session iterator (mirrors `wss.clients` for the SSE
+  // fallback transport). Walked alongside `wss.clients` to send the
+  // 1001 close frame and apply the terminate-grace timer to both
+  // transports uniformly.
+  sseSessions: () => Iterable<SseSession>
   // App-specific teardown, run AFTER the in-flight drain: close the DB.
   // Swallows its own errors (a failed close shouldn't abort the exit).
   closeDb: () => Promise<void>
@@ -40,7 +46,12 @@ export function createLifecycle(): Lifecycle {
   const inFlight = new Set<Promise<unknown>>()
   function track(promise: Promise<unknown>): void {
     inFlight.add(promise)
-    promise.finally(() => inFlight.delete(promise))
+    // Trailing `.catch(() => {})` swallows the rejection that `.finally`
+    // propagates through its returned promise — without it, a tracked
+    // handler that rejects (or whose caller's catch handler itself
+    // throws) trips the `unhandledRejection` catchall below and crashes
+    // the process via `fireShutdown(1)`.
+    promise.finally(() => inFlight.delete(promise)).catch(() => {})
   }
   let shuttingDown = false
   // Live exit code the in-progress shutdown will pass to `process.exit`.
@@ -51,7 +62,7 @@ export function createLifecycle(): Lifecycle {
   let pendingExitCode = 0
 
   function install(deps: ShutdownDeps): void {
-    const { httpServer, wss, heartbeatTimer, stopReaper, closeDb } = deps
+    const { httpServer, wss, heartbeatTimer, stopReaper, sseSessions, closeDb } = deps
 
     async function shutdown(exitCode: number = 0): Promise<void> {
       // Re-entry: don't restart the teardown, but escalate the pending
@@ -78,6 +89,13 @@ export function createLifecycle(): Lifecycle {
       for (const socket of wss.clients) {
         try { socket.close(1001, 'Server shutting down') } catch {}
       }
+      // Same close frame on every SSE+POST session — the adapter
+      // translates `close(1001, …)` into a structured `event: close`
+      // record on the SSE stream so the client transport can read the
+      // code and skip its reconnect backoff (parity with the WS path).
+      for (const session of sseSessions()) {
+        try { session.close(1001, 'Server shutting down') } catch {}
+      }
       // Force-terminate any client that doesn't ack the close frame
       // within a short grace window. `wss.close()` waits for every client
       // to emit `'close'`, and `ws` only TCP-RSTs unresponsive peers
@@ -92,6 +110,15 @@ export function createLifecycle(): Lifecycle {
             try { socket.terminate() } catch {}
           }
         }
+        // SSE sessions are tracked separately from `wss.clients`; apply
+        // the same terminate-grace policy so a stranded SSE response
+        // can't pin the HTTP keep-alive shutdown branch below.
+        for (const session of sseSessions()) {
+          const rs = session.readyState
+          if (rs === session.OPEN || rs === session.CLOSING) {
+            try { session.terminate() } catch {}
+          }
+        }
         // Same grace for HTTP keep-alive sockets that didn't respect the
         // `Connection: close` hint, which would otherwise hold
         // `httpServer.close()` until their TCP timeout.

package/server/npm-proxy.ts

@@ -0,0 +1,348 @@
+// Same-origin proxy for the npm registry's bulk advisories endpoint
+// (`POST https://registry.npmjs.org/-/npm/v1/security/advisories/bulk`).
+// The UI's Advisories tab on stasis bundles fans out the bundle's
+// (package → versions) map through this endpoint to enrich the view
+// with upstream vulnerability data; calling the registry directly
+// from the browser would cross-origin (the npm registry doesn't
+// emit CORS headers for arbitrary callers), so the relay forwards
+// the request body and answers with the upstream's JSON.
+//
+// The route is mounted at `/api/npm-advisories`. The same-origin
+// gate runs inside `dispatchNpmAdvisories` below (server/http.ts
+// calls the dispatcher directly without a pre-check), so any
+// browser request from a foreign origin is rejected with 403 before
+// we ever issue a fetch — non-browser callers that omit Origin are
+// allowed (their trust boundary is the network, same posture as
+// every other /api/* route).
+//
+// Request body is capped at `REQUEST_BODY_LIMIT` (the registry caps
+// a single bulk lookup well under that); upstream response is
+// buffered up to `RESPONSE_BODY_LIMIT` and then `JSON.parse`-asserted
+// before we writeHead, so the client's `await res.json()` never
+// chokes on a Cloudflare HTML 503 page or a captive-portal banner.
+// A non-parseable upstream collapses to a 502 with a documented
+// `{ error, upstreamStatus, upstreamContentType }` envelope.
+//
+// Outbound fetch carries an `AbortController` so a hung upstream
+// (slow-loris response, TLS stall) tears down after
+// `UPSTREAM_TIMEOUT_MS`, and a client that closes its connection
+// mid-fetch propagates an abort through the same controller — so a
+// stranded in-flight call doesn't block SIGTERM drain.
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { Buffer } from 'node:buffer'
+import { errStack } from './util.ts'
+
+type HasHeaders = { headers: IncomingMessage['headers'] }
+
+export const NPM_ADVISORIES_PATH = '/api/npm-advisories'
+const UPSTREAM_URL = 'https://registry.npmjs.org/-/npm/v1/security/advisories/bulk'
+
+// 1 MiB is generous: the bulk endpoint accepts `{ packageName:
+// [versions] }` maps, and even a bundle with thousands of pinned
+// versions serialises to well under this. Anything bigger is almost
+// certainly malformed input or a probe.
+const REQUEST_BODY_LIMIT = 1 * 1024 * 1024
+// 4 MiB caps the upstream response. The advisories endpoint
+// returns at most a few CVEs per package, so even a bundle with
+// hundreds of affected packages comes in well under this — a
+// runaway / hostile upstream gets cut off before we burn arbitrary
+// memory buffering it.
+const RESPONSE_BODY_LIMIT = 4 * 1024 * 1024
+// Hard deadline on the upstream call. The bulk endpoint typically
+// answers in well under a second; 30 s leaves plenty of headroom
+// for a slow path but caps a hung TLS / slow-loris connection so
+// a stranded fetch can't pin the inflight slot through SIGTERM
+// drain. Triggered via AbortController.
+const UPSTREAM_TIMEOUT_MS = 30_000
+
+export type NpmProxyDeps = {
+  debug: boolean
+}
+
+export function matchNpmAdvisoriesRoute(url: string | undefined): boolean {
+  if (typeof url !== 'string') return false
+  return url.split('?', 1)[0] === NPM_ADVISORIES_PATH
+}
+
+export type DispatchDeps = {
+  isOriginAllowed: (req: HasHeaders) => boolean
+  isShuttingDown: () => boolean
+  debug: boolean
+}
+
+// Combined route-match + shutdown-gate + same-origin-gate + handler
+// dispatch. Returns the in-flight Promise when the request matched
+// (caller `track`s it so SIGTERM awaits drainage), or null when the
+// route wasn't ours (caller falls through to the next branch).
+export function dispatchNpmAdvisories(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: DispatchDeps,
+): Promise<void> | null {
+  if (!matchNpmAdvisoriesRoute(req.url)) return null
+  if (deps.isShuttingDown()) {
+    res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
+    res.end(JSON.stringify({ error: 'shutting-down' }))
+    return Promise.resolve()
+  }
+  if (!deps.isOriginAllowed(req)) {
+    res.writeHead(403, { 'content-type': 'application/json' })
+    res.end(JSON.stringify({ error: 'origin-denied' }))
+    return Promise.resolve()
+  }
+  return handleNpmAdvisories({ debug: deps.debug }, req, res).catch((err) => {
+    console.warn('npm-advisories handler error:', errStack(err))
+    if (res.headersSent) { try { res.destroy() } catch {} }
+    else {
+      try {
+        res.writeHead(500, { 'content-type': 'application/json' })
+        res.end(JSON.stringify({ error: 'internal' }))
+      } catch {}
+    }
+  })
+}
+
+// True iff the response is still in a writable state. `writableEnded`
+// flips only after `res.end()` resolves; a client-disconnect tears
+// the socket down asynchronously, leaving a brief window where
+// `writableEnded` is still false but `destroyed` is true and any
+// write throws ERR_STREAM_DESTROYED. Checking both keeps the
+// after-disconnect log path quiet.
+function canWrite(res: ServerResponse): boolean {
+  return !res.writableEnded && !res.destroyed
+}
+
+// Write a JSON error envelope, swallowing throws if the socket
+// already closed mid-write. The outer try/catch is the belt to
+// `canWrite`'s suspenders — a `destroyed` flip between the gate
+// check and `res.end()` is rare but possible on a busy connection,
+// and there's nothing useful to do besides drop the write.
+function deny(res: ServerResponse, status: number, reason: string): void {
+  if (!canWrite(res)) return
+  try {
+    res.writeHead(status, { 'content-type': 'application/json' })
+    res.end(JSON.stringify({ error: reason }))
+  } catch {}
+}
+
+// Same shape as `deny` but for the richer multi-field envelopes
+// (upstream-not-json / upstream-too-large) — these can't reuse
+// `deny` because the body carries more than `{ error }`.
+function writeJsonEnvelope(res: ServerResponse, status: number, body: object): void {
+  if (!canWrite(res)) return
+  try {
+    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' })
+    res.end(JSON.stringify(body))
+  } catch {}
+}
+
+// Drain the incoming request body into a single Buffer, rejecting
+// once REQUEST_BODY_LIMIT is exceeded. We don't try to parse here —
+// we forward the bytes verbatim so the registry sees exactly what
+// the client sent (preserving key order / whitespace doesn't matter
+// to the upstream, but parse-then-restringify is wasted work).
+async function readRequestBody(req: IncomingMessage): Promise<Buffer | null> {
+  const chunks: Buffer[] = []
+  let received = 0
+  for await (const chunk of req) {
+    const buf = chunk as Buffer
+    received += buf.byteLength
+    if (received > REQUEST_BODY_LIMIT) return null
+    chunks.push(buf)
+  }
+  return Buffer.concat(chunks)
+}
+
+export async function handleNpmAdvisories(
+  deps: NpmProxyDeps,
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  if (req.method !== 'POST') { deny(res, 405, 'method-not-allowed'); return }
+  // Single controller drives both the upstream deadline timer AND
+  // the client-disconnect propagation: a fetch hung past
+  // UPSTREAM_TIMEOUT_MS and a browser tab closed mid-fetch both end
+  // up aborting the same signal, which undici threads through into
+  // the body reader. Without this the inflight slot pinned by
+  // `track()` could outlive both a dead client and a wedged
+  // upstream, holding SIGTERM drain open.
+  //
+  // Install the listener + timer BEFORE the body read so a client
+  // disconnect during the upload window also flips the controller
+  // (and so a tail-end disconnect doesn't race the listener
+  // registration). The timer is overall budget — running across the
+  // body read + upstream call together is fine; the body read is
+  // bounded by REQUEST_BODY_LIMIT and finishes in ms.
+  //
+  // `res.on('close')` (NOT `req.on('close')`) is the right
+  // disconnect signal here: IncomingMessage's `close` fires when
+  // the REQUEST is fully drained — even on a clean POST that's
+  // followed by a healthy response — and would always trigger an
+  // abort the instant we finished reading the body. The
+  // ServerResponse's `close` event only fires when the underlying
+  // socket gets destroyed before `res.end()` completes, which is
+  // exactly the "browser tab closed mid-fetch" case we want to
+  // propagate. (Gate on `writableEnded` so a post-success close
+  // doesn't fire a no-op abort — itself a no-op on a settled
+  // controller, but skipping the log noise.)
+  const controller = new AbortController()
+  const timer = setTimeout(() => { try { controller.abort() } catch {} }, UPSTREAM_TIMEOUT_MS)
+  const onResClose = (): void => {
+    if (!res.writableEnded) controller.abort()
+  }
+  res.on('close', onResClose)
+  try {
+    let body: Buffer | null
+    try {
+      body = await readRequestBody(req)
+    } catch (err: unknown) {
+      // `for await (chunk of req)` throws on mid-upload connection
+      // drops (ECONNRESET / aborted). The client is already gone,
+      // so there's no useful response to write — and bubbling up
+      // to the dispatcher's catch would just emit a misleading
+      // "handler error" log. Same posture other handlers take for
+      // mid-body aborts: swallow + return.
+      if (deps.debug) console.warn('npm-advisories request body error:', errStack(err))
+      return
+    }
+    if (body === null) {
+      // Respond BEFORE destroying so the client sees the 413
+      // envelope (writeHead on a destroyed socket would silently
+      // drop). Then destroy: a bare `return` leaves the unread
+      // tail of the request body in the kernel buffer, which on
+      // an HTTP/1.1 keep-alive connection becomes the
+      // start-of-line for the NEXT request and corrupts request
+      // framing. Matches the sse-server.ts pattern
+      // (`{ error: 'too-large' }` then `req.destroy()`).
+      deny(res, 413, 'payload-too-large')
+      try { req.destroy() } catch {}
+      return
+    }
+    await handleNpmAdvisoriesInner(deps, body, res, controller.signal)
+  } finally {
+    clearTimeout(timer)
+    res.off('close', onResClose)
+  }
+}
+
+async function handleNpmAdvisoriesInner(
+  deps: NpmProxyDeps,
+  body: Buffer,
+  res: ServerResponse,
+  signal: AbortSignal,
+): Promise<void> {
+  let upstream: Response
+  try {
+    upstream = await fetch(UPSTREAM_URL, {
+      method: 'POST',
+      // Force JSON — the bulk endpoint requires it. Drop every
+      // client-supplied header to keep an upstream fingerprint from
+      // leaking through (cookies, auth, custom UA, ...). The
+      // registry's bulk endpoint doesn't need any of them for a
+      // public lookup.
+      headers: { 'content-type': 'application/json', 'accept': 'application/json' },
+      // Re-wrap as a plain Uint8Array — Buffer's underlying
+      // ArrayBufferLike type doesn't satisfy fetch's BodyInit
+      // narrowing (it can't statically rule out SharedArrayBuffer),
+      // but a copy through Uint8Array is zero-cost in practice and
+      // unambiguously typed.
+      body: new Uint8Array(body),
+      signal,
+    })
+  } catch (err: unknown) {
+    if (deps.debug) console.warn('npm-advisories upstream error:', errStack(err))
+    // Client already gone — `canWrite` (inside `deny`) gates the
+    // write so a destroyed / writableEnded socket doesn't trip
+    // ERR_STREAM_DESTROYED on the way out.
+    deny(res, 502, 'upstream-unreachable')
+    return
+  }
+  // Assert JSON on the upstream body. The Content-Type header is
+  // unreliable (Cloudflare in front of registry.npmjs.org strips it
+  // from some responses; a captive portal / WAF can declare HTML on
+  // a body that's actually JSON or vice-versa), so we don't lean on
+  // it — instead we buffer the body and parse. A successful
+  // JSON.parse is the strongest guarantee we can hand the UI's
+  // `await res.json()`. Buffering is bounded by
+  // `RESPONSE_BODY_LIMIT`; the advisories endpoint's payloads sit
+  // well under that.
+  const upstreamContentType = upstream.headers.get('content-type') ?? ''
+  let buffered: Buffer | null
+  try {
+    buffered = await readUpstreamBody(upstream)
+  } catch (err: unknown) {
+    if (deps.debug) console.warn('npm-advisories upstream body error:', errStack(err))
+    deny(res, 502, 'upstream-unreachable')
+    return
+  }
+  if (buffered === null) {
+    if (deps.debug) console.warn(`npm-advisories upstream too large: status=${upstream.status}`)
+    writeJsonEnvelope(res, 502, { error: 'upstream-too-large', upstreamStatus: upstream.status })
+    return
+  }
+  // Treat the body as UTF-8 — `JSON.parse` operates on a string and
+  // the registry's responses are always UTF-8 in practice. A
+  // non-UTF-8 byte sequence still decodes (with U+FFFD
+  // substitution); the subsequent JSON.parse fails and routes
+  // through the error branch.
+  const text = buffered.toString('utf8')
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    if (deps.debug) console.warn(`npm-advisories upstream non-JSON: status=${upstream.status} ct=${upstreamContentType || '<none>'} bytes=${buffered.byteLength}`)
+    writeJsonEnvelope(res, 502, {
+      error: 'upstream-not-json',
+      upstreamStatus: upstream.status,
+      upstreamContentType: upstreamContentType || null,
+    })
+    return
+  }
+  if (!canWrite(res)) return
+  // Re-stringify rather than echoing `text` so the wire shape we
+  // emit is canonical (no upstream whitespace / BOM / trailing
+  // junk after the parsed value rides along), and so the client
+  // can rely on a single JSON document per response.
+  const out = JSON.stringify(parsed)
+  try {
+    res.writeHead(upstream.status, {
+      'content-type': 'application/json',
+      'cache-control': 'no-store',
+      'content-length': Buffer.byteLength(out),
+    })
+    res.end(out)
+  } catch {}
+}
+
+// Buffer the upstream response body up to RESPONSE_BODY_LIMIT.
+// Returns null if the cap is exceeded (caller maps to a 502
+// `upstream-too-large`), or the cumulative Buffer otherwise. A
+// transport error mid-read (e.g. AbortSignal fired by the deadline
+// timer or by `req` close) throws — the caller catches it.
+//
+// `finally { reader.cancel() }` is load-bearing on the error and
+// cap-exceeded paths: leaving the reader locked to the body holds
+// the underlying undici TCP socket out of the connection pool until
+// GC, and the cap-exceeded path explicitly needs to tear the
+// transfer down so we don't keep buffering bytes we'll never use.
+// On the clean-drain path (done:true), cancel() is a no-op.
+async function readUpstreamBody(upstream: Response): Promise<Buffer | null> {
+  if (!upstream.body) return Buffer.alloc(0)
+  const reader = upstream.body.getReader()
+  const chunks: Uint8Array[] = []
+  let received = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (!value) continue
+      received += value.byteLength
+      if (received > RESPONSE_BODY_LIMIT) return null
+      chunks.push(value)
+    }
+    return Buffer.concat(chunks)
+  } finally {
+    try { await reader.cancel() } catch {}
+  }
+}