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

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

@@ -55,15 +55,6 @@ export type SubscribeMsg = {
 // `Uint8Array<ArrayBuffer>` (not `<ArrayBufferLike>`) so the bytes
 // thread directly into `crypto.subtle.digest` — `BufferSource`
 // rejects SharedArrayBuffer-backed views.
-//
-// NOTE: `verifySaveSigAndCanonical` is a test-friendly composition
-// helper. Production `handleSave` in `server/index.ts` does NOT
-// call it — it composes `canonicalSave` +
-// `computeRevisionIdFromCanonical` + `verifyEd25519` separately so
-// the dup-precheck (`revisionExists`) can fire BEFORE the Ed25519
-// verify, closing the round-9 H1 CPU-DoS vector where a passive
-// observer floods captured saves. The wrapper exists for unit
-// tests that don't need the precheck ordering.
 export type VerifyResult =
   | { ok: true; canonical: Uint8Array<ArrayBuffer> }
   | { ok: false; canonical: null }
@@ -101,7 +92,7 @@ export function canonicalSave(
   // confusing diff in the canonical bytes rather than a clean drop.
   // Mirrors the `isSafeNonNegativeInt` rigor that the objstore
   // canonical builders apply. Input-validation audit
-  // `server/sign.ts:88`.
+  // `server-e2e/sign.ts:88`.
   if (typeof workspaceTag !== 'string') throw new TypeError('canonicalSave: workspaceTag must be string')
   if (typeof nonce !== 'string') throw new TypeError('canonicalSave: nonce must be string')
   if (typeof ciphertext !== 'string') throw new TypeError('canonicalSave: ciphertext must be string')
@@ -120,11 +111,18 @@ function canonicalSubscribe(
   { workspaceTag, from }: SubscribeMsg,
   connectionNonce: string,
 ): Uint8Array<ArrayBuffer> {
-  const fromStr = from == null ? '' : String(from)
+  // Strict `from` typing, mirroring canonicalSave's `base` check: `from`
+  // is `string | null`. A non-string non-null value would otherwise
+  // coerce via `String(...)` to canonical bytes the client could never
+  // reproduce (123 → "123", {} → "[object Object]"), so a signature
+  // computed over that coercion would verify against a malformed wire
+  // shape. verifySubscribeSig wraps this call in try/catch → clean drop.
+  if (from != null && typeof from !== 'string') throw new TypeError('canonicalSubscribe: from must be string or null')
+  const fromStr = from == null ? '' : from
   return encodeUtf8([SUBSCRIBE_DOMAIN, workspaceTag as string, fromStr, connectionNonce].join('\n'))
 }
 
-// Exported because the v1.objstore signing module (server/objstore/sign.ts)
+// Exported because the v1.objstore signing module (server-e2e/objstore/sign.ts)
 // reuses it for its four verifiers — same workspaceTag-as-pubkey contract,
 // same domain-separated canonical bytes. Keeping the WebCrypto plumbing
 // in one place avoids drift between the triage-sync and objstore verify
@@ -159,7 +157,7 @@ export async function verifyEd25519(
 // `{ ok: false, canonical: null }` on bad shape / bad sig;
 // `{ ok: true, canonical: <bytes> }` on success.
 //
-// NOT used by `server/index.ts handleSave`. Production composes
+// NOT used by `server-e2e/index.ts handleSave`. Production composes
 // the smaller helpers (`canonicalSave`, `computeRevisionIdFromCanonical`,
 // `verifyEd25519`) separately so the dup-precheck via
 // `revisionExists` can fire BEFORE Ed25519-verify and skip the
@@ -206,7 +204,7 @@ export async function computeRevisionIdFromCanonical(canonical: Uint8Array<Array
 
 // `connectionNonce` is the per-socket challenge the server issued
 // to the originating connection (see `Peer.challenge` in
-// server/peer.ts). The client signs a canonical that includes the
+// server-e2e/peer.ts). The client signs a canonical that includes the
 // nonce; verifying against the SAME nonce here is what blocks
 // cross-connection replay of a captured subscribe frame. Audit
 // round-9 H2.

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

@@ -6,8 +6,8 @@
 // `join(staticDir, dirent.name)` from `readdirSync` at boot — the
 // request URL is only used as a Map key, never joined with the
 // filesystem — so the handler has no path-traversal surface at all:
-// `..`, percent-encoded slashes, nested subpaths and absolute-form
-// URIs all just produce a key that isn't in the map and 404.
+// `..`, percent-encoded slashes and absolute-form URIs all just
+// produce a key that isn't in the map and 404.
 //
 // Compression: every entry whose extension is in COMPRESSIBLE gets
 // pre-computed brotli + gzip at boot. The handler picks brotli over
@@ -38,6 +38,7 @@ import { readFileSync, readdirSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { brotliCompressSync, gzipSync, constants as zlibConstants } from 'node:zlib'
 import { extname, join } from 'node:path'
+import { scanServerHtml } from '../server-common/scan-config.ts'
 
 // MIME types for extensions the production UI bundle currently
 // emits. Anything else falls through to `application/octet-stream`
@@ -64,15 +65,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 = {
@@ -93,8 +103,10 @@ export type StaticHandler = (req: HttpRequest, res: ServerResponse) => boolean
 // caller falls through to its next route. Missing `staticDir`
 // (pre-build case) logs a warning and returns a handler that always
 // answers false; the API/WS planes are unaffected.
-export function loadStatic(staticDir: string): StaticHandler {
-  const files = readStaticFiles(staticDir)
+type StaticOptions = { transformIndex?: (html: string) => string, indexOnly?: boolean }
+
+export function loadStatic(staticDir: string, deepviewScanServer: string | null = null, options: StaticOptions = {}): StaticHandler {
+  const files = readStaticFiles(staticDir, deepviewScanServer, options)
   return function handleStatic(req: HttpRequest, res: ServerResponse): boolean {
     if (req.method !== 'GET' && req.method !== 'HEAD') return false
     if (typeof req.url !== 'string') return false
@@ -142,7 +154,7 @@ export function loadStatic(staticDir: string): StaticHandler {
   }
 }
 
-function readStaticFiles(staticDir: string): ReadonlyMap<string, StaticEntry> {
+function readStaticFiles(staticDir: string, deepviewScanServer: string | null, options: StaticOptions): ReadonlyMap<string, StaticEntry> {
   const files = new Map<string, StaticEntry>()
   let entries
   try { entries = readdirSync(staticDir, { withFileTypes: true }) } catch (err) {
@@ -156,24 +168,21 @@ function readStaticFiles(staticDir: string): ReadonlyMap<string, StaticEntry> {
     throw err
   }
   for (const entry of entries) {
-    // `isFile()` filters subdirectories, symlinks, FIFOs etc. The
-    // build emits a flat tree; dropping anything else keeps the
-    // surface minimal even if a stray non-file sneaks in.
-    if (!entry.isFile()) continue
-    files.set(entry.name, buildEntry(staticDir, entry.name))
+    // Exclude subdirectories, symlinks and non-file entries.
+    if (!entry.isFile() || (options.indexOnly && entry.name !== 'index.html')) continue
+    files.set(entry.name, buildEntry(staticDir, entry.name, deepviewScanServer, options.transformIndex))
   }
   return files
 }
 
-function buildEntry(staticDir: string, name: string): StaticEntry {
+function buildEntry(staticDir: string, name: string, deepviewScanServer: string | null = null, transformIndex: (html: string) => string = html => html): StaticEntry {
   const ext = extname(name)
-  const raw = readFileSync(join(staticDir, name))
+  const source = readFileSync(join(staticDir, name))
+  const raw = name === 'index.html' ? Buffer.from(transformIndex(scanServerHtml(source.toString('utf8'), deepviewScanServer))) : source
   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 +282,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 = [