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

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

@@ -10,6 +10,7 @@ import { type IncomingMessage as HttpRequest, type Server, type ServerResponse,
 import { Buffer } from 'node:buffer'
 import { fileURLToPath } from 'node:url'
 import type { WebSocketServer } from 'ws'
+import { CONFIG_PATH, type ServerInfo } from '../common/server-info.ts'
 import { type ObjstoreRestDeps, handleRest, matchRoute } from './objstore/rest.ts'
 import { SSE_OPEN_PATH, type SseServer } from './sse-server.ts'
 import { dispatchNpmAdvisories } from './npm-proxy.ts'
@@ -20,6 +21,12 @@ import { errStack } from './util.ts'
 // similar) can route `/api/*` → this process and `/*` → the static UI
 // bundle with a single location block.
 export const WS_UPGRADE_PATH = '/api/sync'
+// Session-independent triage-sync save plane: `POST /api/sync/save`. The
+// SSE-mode alternative to the in-band `workspace-save` frame — a save POSTed
+// here commits + broadcasts WITHOUT taking over the client's SSE event-stream
+// (each in-band POST forces a stream takeover; see sse-server.ts). Sibling of
+// the WS upgrade path so one nginx `/api/*` block routes both.
+export const SAVE_REST_PATH = '/api/sync/save'
 function isUpgradePath(url: string | undefined): boolean {
   if (typeof url !== 'string') return false
   // Strip `?…` so clients can carry build / debug tags. Exact match
@@ -34,6 +41,10 @@ type HasHeaders = { headers: HttpRequest['headers'] }
 export type HttpServerDeps = {
   wss: WebSocketServer
   restDeps: ObjstoreRestDeps
+  // This server's `server-info` (mode advertisement), served as JSON at
+  // GET /api/config so a client can detect the protocol without a sync
+  // connection (the WS connect frame stays the source of truth).
+  serverInfo: ServerInfo
   // SSE+POST fallback. Owns its own session map + lifecycle; we just
   // give it first crack at requests that match `SSE_OPEN_PATH`. Same
   // same-origin / shutdown gates run BEFORE the dispatch so the SSE
@@ -42,19 +53,88 @@ export type HttpServerDeps = {
   isOriginAllowed: (req: HasHeaders) => boolean
   isShuttingDown: () => boolean
   track: (promise: Promise<unknown>) => void
+  // Handler for `POST /api/sync/save` (see SAVE_REST_PATH). Owns body parse +
+  // the save pipeline + JSON response; this module owns the gates (method,
+  // same-origin, shutdown, idle-timeout) and the graceful-drain tracking.
+  handleSaveRest: (req: HttpRequest, res: ServerResponse) => Promise<void>
   restPutIdleTimeoutMs: number
   debug: boolean
 }
 
+// `POST /api/sync/save` dispatch. Returns the in-flight handler promise when
+// the request matched the route (the caller `track`s it for graceful drain),
+// or null when it's for a different route. The gate ladder — method →
+// shutdown → same-origin → idle-timeout — mirrors the objstore REST branch; a
+// gate rejection writes its own response and returns an already-settled
+// promise. Kept out of `createHttpServer` so that dispatcher stays compact.
+function dispatchSaveRest(
+  req: HttpRequest, res: ServerResponse,
+  deps: {
+    handleSaveRest: (req: HttpRequest, res: ServerResponse) => Promise<void>
+    isOriginAllowed: (req: HasHeaders) => boolean
+    isShuttingDown: () => boolean
+    restPutIdleTimeoutMs: number
+    debug: boolean
+  },
+): Promise<void> | null {
+  if (typeof req.url !== 'string' || req.url.split('?', 1)[0] !== SAVE_REST_PATH) return null
+  if (req.method !== 'POST') {
+    res.writeHead(405, { 'content-type': 'application/json', 'allow': 'POST', 'connection': 'close' })
+    res.end(JSON.stringify({ error: 'method-not-allowed' }))
+    return Promise.resolve()
+  }
+  // Shutdown gate — parity with the objstore REST branch (a POST on an
+  // existing keep-alive socket after SIGTERM but before close() drains).
+  if (deps.isShuttingDown()) {
+    res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
+    res.end(JSON.stringify({ error: 'shutting-down' }))
+    return Promise.resolve()
+  }
+  // Same-origin gate — a hostile cross-origin page would carry an Origin
+  // header (browser-set on fetch); same-origin XHR may omit it (allowed).
+  if (!deps.isOriginAllowed(req)) {
+    res.writeHead(403, { 'content-type': 'application/json' })
+    res.end(JSON.stringify({ error: 'origin-denied' }))
+    return Promise.resolve()
+  }
+  // Idle-body timeout — a slow-loris trickling the JSON body would otherwise
+  // hold the connection indefinitely.
+  req.setTimeout(deps.restPutIdleTimeoutMs, () => {
+    if (deps.debug) console.warn(`sync-save REST idle ${deps.restPutIdleTimeoutMs}ms → abort`)
+    try { req.destroy(new Error('idle-timeout')) } catch {}
+  })
+  // Outer catch is the unhandled-rejection guard for a throw OUTSIDE the
+  // handler's own try/catch — logs and terminates the response so the TCP
+  // socket doesn't dangle (same policy as the objstore handleRest wrapper).
+  return deps.handleSaveRest(req, res).catch((err) => {
+    console.warn('sync-save REST 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 {} }
+  })
+}
+
 export function createHttpServer(deps: HttpServerDeps): Server {
-  const { wss, restDeps, sseServer, isOriginAllowed, isShuttingDown, track, restPutIdleTimeoutMs, debug } = deps
+  const { wss, restDeps, sseServer, serverInfo, isOriginAllowed, isShuttingDown, track, handleSaveRest, restPutIdleTimeoutMs, debug } = deps
   // Static-file plane (see ./static.ts). The directory is the
   // `build.js build` output sibling to this file; the loader handles
   // enumeration, pre-compression, and ETag derivation. Plugged in after
   // the `/api/objstore/...` REST branch.
-  const handleStatic = loadStatic(fileURLToPath(new URL('../out', import.meta.url)))
+  const handleStatic = loadStatic(fileURLToPath(new URL('../out', import.meta.url)), serverInfo.deepviewScanServer ?? null)
 
   const httpServer = createServer((req: HttpRequest, res: ServerResponse) => {
+    // Static mode probe: GET /api/config → this server's `server-info` as JSON.
+    // A client uses it to detect the protocol up front; the WS connect frame
+    // stays the source of truth and catches a later mode change. Public, no body.
+    if (typeof req.url === 'string' && req.url.split('?', 1)[0] === CONFIG_PATH) {
+      if (req.method !== 'GET') {
+        res.writeHead(405, { 'content-type': 'application/json', allow: 'GET' })
+        res.end(JSON.stringify({ error: 'method-not-allowed' }))
+        return
+      }
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' })
+      res.end(JSON.stringify(serverInfo))
+      return
+    }
     // SSE+POST fallback plane. Same-origin gate first (Origin header
     // is set by the browser on cross-origin EventSource + fetch, so
     // a hostile origin would surface here just like it does on the
@@ -76,6 +156,12 @@ export function createHttpServer(deps: HttpServerDeps): Server {
       // the lifecycle's sseSessions() close loop.
       if (sseServer.handle(req, res)) return
     }
+    // Triage-sync save REST plane (see SAVE_REST_PATH) — session-independent
+    // `POST /api/sync/save` so an SSE-mode save doesn't take over the
+    // event-stream. The dispatch helper owns the gate ladder; we `track` the
+    // returned in-flight promise so SIGTERM drains it (mirrors npm-advisories).
+    const saveP = dispatchSaveRest(req, res, { handleSaveRest, isOriginAllowed, isShuttingDown, restPutIdleTimeoutMs, debug })
+    if (saveP) { track(saveP); return }
     // npm advisories proxy — same-origin + shutdown gates live in the
     // helper so this dispatcher stays compact. `dispatchNpmAdvisories`
     // returns the in-flight promise (or null when the route didn't
@@ -103,20 +189,22 @@ export function createHttpServer(deps: HttpServerDeps): Server {
       // that holds a valid token (e.g. via XSS that read a freshly-minted
       // one) would PUT with its own Origin header — caught here.
       // Same-origin XHR/fetch may omit Origin; that path is allowed (see
-      // `isOriginAllowed`). Transport audit `server/objstore/rest.ts:103`.
+      // `isOriginAllowed`). Transport audit `server-e2e/objstore/rest.ts:103`.
       if (!isOriginAllowed(req)) {
         res.writeHead(403, { 'content-type': 'application/json' })
         res.end(JSON.stringify({ error: 'origin-denied' }))
         return
       }
-      // PUT idle-body timeout — a slow-loris client trickling bytes
-      // within the declared Content-Length holds the staging fd + an
-      // inFlightSids slot indefinitely. `req.setTimeout` fires on
-      // inactivity; we destroy the request, aborting the body pipeline.
-      // Transport audit `server/objstore/rest.ts:218`.
-      if (req.method === 'PUT') {
+      // Idle-body timeout for the body-bearing REST methods — a slow-loris
+      // client trickling bytes holds the connection (and, for PUT, the
+      // staging fd + inFlightSids slot) indefinitely. PUT carries the raw
+      // blob within its declared Content-Length; POST carries the small
+      // fetch-mint JSON body. `req.setTimeout` fires on inactivity; we
+      // destroy the request, aborting the body pipeline.
+      // Transport audit `server-e2e/objstore/rest.ts:218`.
+      if (req.method === 'PUT' || req.method === 'POST') {
         req.setTimeout(restPutIdleTimeoutMs, () => {
-          if (debug) console.warn(`REST PUT idle ${restPutIdleTimeoutMs}ms → abort`)
+          if (debug) console.warn(`REST ${req.method} idle ${restPutIdleTimeoutMs}ms → abort`)
           try { req.destroy(new Error('idle-timeout')) } catch {}
         })
       }
@@ -142,7 +230,19 @@ export function createHttpServer(deps: HttpServerDeps): Server {
     res.end(NOT_FOUND_BODY)
   })
 
+  installUpgradeHandler(httpServer, wss, isOriginAllowed)
+
+  return httpServer
+}
+
+function installUpgradeHandler(httpServer: Server, wss: WebSocketServer, isOriginAllowed: HttpServerDeps['isOriginAllowed']): void {
   httpServer.on('upgrade', (req, socket, head) => {
+    // Combined deployments must not let a managed share capability enter the
+    // unscoped sync transport, which bypasses the normal HTTP router.
+    if (req.headers['x-deepview-share'] !== undefined) {
+      socket.end('HTTP/1.1 403 Forbidden\r\nContent-Length: 0\r\nConnection: close\r\n\r\n')
+      return
+    }
     // RFC 6455: the WS upgrade IS an HTTP request; reject with a normal
     // HTTP response so a misconfigured client sees the JSON body instead
     // of ECONNRESET. `socket.end(body)` flushes before sending FIN.
@@ -173,6 +273,4 @@ export function createHttpServer(deps: HttpServerDeps): Server {
     }
     wss.handleUpgrade(req, socket, head, (ws) => { wss.emit('connection', ws, req) })
   })
-
-  return httpServer
 }

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

@@ -7,9 +7,13 @@
 // testable and reasoned about on its own.
 
 import type { WebSocket } from 'ws'
+import { Buffer } from 'node:buffer'
 import type { PeerRegistry } from './peer.ts'
 
 export type Hub = {
+  // Buffer broadcasts during async subscription snapshots. The returned
+  // release flushes them after the snapshot/chain replies, preserving order.
+  pauseBroadcasts(socket: WebSocket): () => void
   subscribe(socket: WebSocket, tag: string): void
   unsubscribeAll(socket: WebSocket): void
   send(socket: WebSocket, msg: object): void
@@ -21,13 +25,13 @@ export type Hub = {
   // WS-originated broadcasts pass the originator so it doesn't see its
   // own message echoed back. Local-only: callers that ALSO want a
   // cross-instance fan-out are expected to publish to the pubsub bus
-  // alongside this call (server/pubsub.ts). The hub deliberately stays
+  // alongside this call (server-e2e/pubsub.ts). The hub deliberately stays
   // ignorant of the bus so its transport invariants (backpressure cap,
   // stringify-once, terminate-on-overflow) are unchanged.
   broadcast(tag: string, msg: object, except: WebSocket | null): void
   // Broadcasts an ALREADY-SERIALISED payload to every local subscriber
   // for `tag`. Used by the pubsub bus receiver
-  // (server/bus-receiver.ts, wired up from server/index.ts) to relay
+  // (server-e2e/bus-receiver.ts, wired up from server-e2e/index.ts) to relay
   // a remote-instance event into this instance's fan-out. No `except`:
   // the originator is on a different instance by construction.
   broadcastLocalRaw(tag: string, payload: string): void
@@ -38,18 +42,34 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
   // workspaceTag → Set<WebSocket>. The per-socket reverse index lives on
   // `Peer.tags` (see ./peer.ts) and is read by `unsubscribeAll` on close.
   const subscribers = new Map<string, Set<WebSocket>>()
+  const paused = new WeakMap<WebSocket, { depth: number; payloads: string[]; bytes: number }>()
+
+  function pauseBroadcasts(socket: WebSocket): () => void {
+    const pending = paused.get(socket) ?? { depth: 0, payloads: [], bytes: 0 }
+    pending.depth++
+    paused.set(socket, pending)
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      if (--pending.depth > 0 || paused.get(socket) !== pending) return
+      paused.delete(socket)
+      for (const payload of pending.payloads) sendRaw(socket, payload)
+      pending.payloads.length = 0
+    }
+  }
 
   function subscribe(socket: WebSocket, tag: string): void {
     let set = subscribers.get(tag)
-    if (!set) {
-      set = new Set()
-      subscribers.set(tag, set)
-    }
+    if (!set) { set = new Set(); subscribers.set(tag, set) }
     set.add(socket)
     peers.get(socket)?.tags.add(tag)
   }
 
   function unsubscribeAll(socket: WebSocket): void {
+    const pending = paused.get(socket)
+    if (pending) pending.payloads.length = 0
+    paused.delete(socket)
     const tags = peers.get(socket)?.tags
     if (!tags) return
     for (const tag of tags) {
@@ -71,7 +91,7 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
     // kernel yet — a slow / blackholed peer accumulates them unboundedly
     // during fan-out broadcasts. Drop above the cap and terminate the
     // socket so the heartbeat doesn't keep it alive on ping/pong while
-    // every broadcast piles up. Transport audit `server/index.ts:225`.
+    // every broadcast piles up. Transport audit `server-e2e/index.ts:225`.
     if (socket.bufferedAmount > maxBufferedBytes) {
       if (debug) console.warn(`drop broadcast: socket buffered ${socket.bufferedAmount}B > cap`)
       try { socket.terminate() } catch {}
@@ -102,17 +122,27 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
   }
 
   function fanOut(set: Set<WebSocket>, payload: string, except: WebSocket | null): void {
-    // Snapshot before iterating — `send`'s try/catch swallows
-    // socket.send errors, but a socket transitioning to CLOSED
+    const payloadBytes = Buffer.byteLength(payload)
+    // Snapshot before iterating — a socket transitioning to CLOSED
     // mid-broadcast triggers `unsubscribeAll` from the 'close' handler,
-    // which mutates `set` while we're walking it. The snapshot keeps a
-    // future refactor (different collection, async send) from silently
-    // skipping subscribers. Audit M4 round-3.
+    // mutating `set` while we walk it. The snapshot also keeps a future
+    // refactor (different collection, async send) from silently skipping
+    // subscribers. Audit M4 round-3.
     for (const s of [...set]) {
       if (s === except) continue
-      sendRaw(s, payload)
+      const pending = paused.get(s)
+      if (!pending) { sendRaw(s, payload); continue }
+      pending.bytes += payloadBytes
+      if (pending.bytes > maxBufferedBytes) {
+        // Snapshot waits must obey the same memory bound as socket writes.
+        pending.payloads.length = 0
+        paused.delete(s)
+        try { s.terminate() } catch {}
+        continue
+      }
+      pending.payloads.push(payload)
     }
   }
 
-  return { subscribe, unsubscribeAll, send, sendRaw, broadcast, broadcastLocalRaw }
+  return { pauseBroadcasts, subscribe, unsubscribeAll, send, sendRaw, broadcast, broadcastLocalRaw }
 }

package/server-e2e/index.ts

@@ -0,0 +1,17 @@
+// Compatibility entry point for the published e2e server. Importing exposes
+// one unbound instance; the combined launcher uses the factory directly.
+import { startServer } from '../server-common/standalone.ts'
+import { createE2eApp } from './app.ts'
+import { HELP, loadConfig } from './config.ts'
+
+if (import.meta.main && (process.argv.includes('--help') || process.argv.includes('-h'))) {
+  console.log(HELP)
+  process.exit(0)
+}
+
+const config = loadConfig()
+export const { httpServer, wss, isShuttingDown, reap, handleRequest, onShutdown } = await createE2eApp(config)
+
+export function start(): void { startServer(httpServer, config) }
+
+if (import.meta.main) start()

package/server-e2e/lifecycle.ts

@@ -0,0 +1,95 @@
+// Per-instance request tracking and graceful disposal. Process shutdown belongs
+// to the standalone launcher; embedded hosts retain their signals and errors.
+import type { Server } from 'node:http'
+import type { WebSocketServer } from 'ws'
+import type { SseSession } from './sse-session.ts'
+
+export type ShutdownDeps = {
+  httpServer: Server
+  wss: WebSocketServer
+  heartbeatTimer: ReturnType<typeof setInterval>
+  sseKeepaliveTimer: ReturnType<typeof setInterval>
+  stopReaper: () => Promise<void>
+  sseSessions: () => Iterable<SseSession>
+  closeDb: () => Promise<void>
+}
+
+export type Lifecycle = {
+  track: (promise: Promise<unknown>) => void
+  isShuttingDown: () => boolean
+  install: (deps: ShutdownDeps) => void
+}
+
+function closePeers({ wss, sseSessions }: ShutdownDeps): void {
+  for (const peer of [...wss.clients, ...sseSessions()]) {
+    try { peer.close(1001, 'Server shutting down') } catch {}
+  }
+}
+
+function terminatePeers({ httpServer, wss, sseSessions }: ShutdownDeps): void {
+  for (const peer of [...wss.clients, ...sseSessions()]) {
+    if (peer.readyState === peer.OPEN || peer.readyState === peer.CLOSING) {
+      try { peer.terminate() } catch {}
+    }
+  }
+  httpServer.closeAllConnections()
+}
+
+async function drain(deps: ShutdownDeps, inFlight: Set<Promise<unknown>>): Promise<void> {
+  const { httpServer, wss, stopReaper, closeDb } = deps
+  // Bound unresponsive WS/SSE peers and HTTP keep-alives to a one-second
+  // grace period. Also works when the listeners are mounted on another host.
+  const terminateTimer = setTimeout(() => terminatePeers(deps), 1000)
+  terminateTimer.unref()
+  try {
+    await stopReaper()
+    httpServer.closeIdleConnections()
+    if (httpServer.listening) {
+      await new Promise<void>(resolve => { httpServer.close(() => resolve()) })
+    }
+    await new Promise<void>(resolve => { wss.close(() => resolve()) })
+    if (inFlight.size > 0) await Promise.allSettled([...inFlight])
+  } finally {
+    clearTimeout(terminateTimer)
+    await closeDb()
+  }
+}
+
+export function createLifecycle(): Lifecycle {
+  const inFlight = new Set<Promise<unknown>>()
+  function track(promise: Promise<unknown>): void {
+    inFlight.add(promise)
+    promise.finally(() => inFlight.delete(promise)).catch(() => {})
+  }
+  let shuttingDown = false
+
+  function install(deps: ShutdownDeps): void {
+    const { httpServer, wss, heartbeatTimer, sseKeepaliveTimer } = deps
+    let disposal: Promise<void> | undefined
+    function dispose(): Promise<void> {
+      if (!disposal) {
+        shuttingDown = true
+        clearInterval(heartbeatTimer)
+        clearInterval(sseKeepaliveTimer)
+        // Store the promise before any close/error callback can re-enter.
+        disposal = Promise.resolve().then(() => drain(deps, inFlight)).finally(() => {
+          httpServer.off('close', onClose)
+          httpServer.off('error', onClose)
+          wss.off('error', onWsError)
+        })
+        closePeers(deps)
+      }
+      return disposal
+    }
+    function onClose(): void {
+      void dispose().catch(err => { console.error('Server cleanup failed:', err) })
+    }
+    function onWsError(err: Error): void { httpServer.emit('error', err) }
+    httpServer[Symbol.asyncDispose] = dispose
+    httpServer.once('close', onClose)
+    httpServer.on('error', onClose)
+    wss.on('error', onWsError)
+  }
+
+  return { track, isShuttingDown: () => shuttingDown, install }
+}

package/{server → server-e2e}/neon-driver.ts

@@ -13,10 +13,10 @@
 // so the absent peer dep is never loaded under test.
 //
 // In production the wrapper is only ever imported on the Neon path
-// (`DATABASE_URL` set), where the operator has installed the peer dep
+// (an e2e database URL set), where the operator has installed the peer dep
 // (`pnpm add @neondatabase/serverless`) so the re-export resolves. A
 // SQLite-only deploy never imports this module — the dynamic `import()`
-// sites are gated behind the `DATABASE_URL` branch in `index.ts`.
+// sites are gated behind the configured database URL branch in `index.ts`.
 //
 // `@ts-ignore` rather than `@ts-expect-error`: when the peer dep IS
 // installed the specifier resolves and tsc sees a real type, which

package/{server → server-e2e}/npm-proxy.ts

@@ -8,7 +8,7 @@
 // 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
+// gate runs inside `dispatchNpmAdvisories` below (server-e2e/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
@@ -25,37 +25,23 @@
 //
 // 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
+// `NPM_ADVISORIES_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'
+import { NPM_ADVISORIES_TIMEOUT_MS, fetchNpmAdvisories } from '../server-common/npm-advisories.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
 }
@@ -129,11 +115,12 @@ function deny(res: ServerResponse, status: number, reason: string): void {
 // 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 {
+function writeJsonEnvelope(res: ServerResponse, status: number, body: unknown): void {
   if (!canWrite(res)) return
   try {
-    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' })
-    res.end(JSON.stringify(body))
+    const out = JSON.stringify(body)
+    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', 'content-length': Buffer.byteLength(out) })
+    res.end(out)
   } catch {}
 }
 
@@ -162,7 +149,7 @@ export async function handleNpmAdvisories(
   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
+  // NPM_ADVISORIES_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
@@ -187,7 +174,7 @@ export async function handleNpmAdvisories(
   // 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 timer = setTimeout(() => { try { controller.abort() } catch {} }, NPM_ADVISORIES_TIMEOUT_MS)
   const onResClose = (): void => {
     if (!res.writableEnded) controller.abort()
   }
@@ -219,130 +206,10 @@ export async function handleNpmAdvisories(
       try { req.destroy() } catch {}
       return
     }
-    await handleNpmAdvisoriesInner(deps, body, res, controller.signal)
+    const result = await fetchNpmAdvisories(body, controller.signal, deps.debug)
+    writeJsonEnvelope(res, result.status, result.body)
   } 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 {}
-  }
-}