@preventive/triage 1.0.0-alpha.3 → 1.0.0-alpha.31

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 {}
-  }
-}

package/{server → server-e2e}/objstore/blob-fs.ts

@@ -48,13 +48,13 @@ async function fsOpenLiveReader(dir: string, tag: string, contentHash: string):
   const path = liveFilePath(dir, tag, contentHash)
   let fh
   try { fh = await open(path, 'r') } catch (err: unknown) {
-    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return { ok: false, reason: 'unavailable' }
+    if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return { ok: false, reason: 'unavailable', detail: 'fs-enoent' }
     throw err
   }
   let size: number
   try { size = (await fh.stat()).size } catch {
     await fh.close().catch(() => {})
-    return { ok: false, reason: 'unavailable' }
+    return { ok: false, reason: 'unavailable', detail: 'fs-stat-failed' }
   }
   const stream = fh.createReadStream()
   let closed = false

package/{server → server-e2e}/objstore/blob-vercel.ts

@@ -1,5 +1,5 @@
 // Vercel Blob Private Storage BlobBackend. Paired with the Neon DB
-// plane in `server/index.ts` when `BLOB_READ_WRITE_TOKEN` is set;
+// plane in `server-e2e/index.ts` when `BLOB_READ_WRITE_TOKEN` is set;
 // the combination is the supported multi-replica deployment shape
 // (Neon for metadata, Vercel Blob for bytes — both serverless, both
 // HTTP-backed, no shared filesystem required).
@@ -35,108 +35,10 @@
 // any single resource), and the stale-staging TTL sweep drops orphan
 // staging blobs.
 
-import { PassThrough, type Readable } from 'node:stream'
-import { Buffer } from 'node:buffer'
+import { PassThrough } from 'node:stream'
 import type { BlobBackend, OpenLiveResult, StagingWriter } from './blob.ts'
 import { errMsg } from '../util.ts'
-
-// Minimal structural shape of the bits of `@vercel/blob` we use.
-// Kept local so the optional peer dep doesn't have to type-resolve
-// for SQLite-only deployments. Real type details live in the
-// installed package; the fields/parameters we touch here are stable
-// per the SDK v2 public surface.
-//
-// `put` accepts the SDK's full `PutBody` union (string | Readable |
-// Buffer | Blob | ArrayBuffer | ReadableStream | File). We only ever
-// pass a Node `PassThrough` (a Readable), but the wider type lets
-// callers reuse this signature for future buffer/blob bodies without
-// type gymnastics. `copy` accepts `allowOverwrite` — REQUIRED for
-// version bumps since the live pathname is reused on re-upload.
-type VercelBlobBody = Readable | Buffer | string | Blob | ArrayBuffer | ReadableStream<Uint8Array>
-type VercelBlobSdk = {
-  put: (
-    pathname: string,
-    body: VercelBlobBody,
-    options: {
-      access: 'private' | 'public'
-      allowOverwrite?: boolean
-      contentType?: string
-      token?: string
-      multipart?: boolean
-      abortSignal?: AbortSignal
-      cacheControlMaxAge?: number
-    },
-  ) => Promise<{ url: string; pathname: string }>
-  head: (
-    pathname: string,
-    options?: { token?: string; abortSignal?: AbortSignal },
-  ) => Promise<{ size: number; pathname: string; url: string }>
-  get: (
-    pathname: string,
-    options: {
-      access: 'private' | 'public'
-      token?: string
-      useCache?: boolean
-      abortSignal?: AbortSignal
-    },
-  ) => Promise<{
-    statusCode: 200 | 304
-    stream: ReadableStream<Uint8Array> | null
-    blob: { size: number | null }
-  } | null>
-  copy: (
-    fromPathname: string,
-    toPathname: string,
-    options: {
-      access: 'private' | 'public'
-      allowOverwrite?: boolean
-      token?: string
-      contentType?: string
-      cacheControlMaxAge?: number
-    },
-  ) => Promise<{ url: string; pathname: string }>
-  del: (
-    urlOrPathname: string | string[],
-    options?: { token?: string; abortSignal?: AbortSignal },
-  ) => Promise<void>
-  list: (options: {
-    prefix?: string
-    cursor?: string
-    limit?: number
-    mode?: 'expanded' | 'folded'
-    token?: string
-  }) => Promise<{
-    // `uploadedAt` (a Date per the SDK v2 surface) is the blob's
-    // creation time — used by the reaper's GC grace window. Optional
-    // in the type because the `folded` listing path ignores it (only
-    // `listLiveBlobs` reads it, and it uses the default expanded mode).
-    blobs: Array<{ pathname: string; size: number; uploadedAt?: Date | string | number }>
-    folders?: string[]
-    cursor?: string
-    hasMore: boolean
-  }>
-}
-
-// Recognise "blob is gone" errors uniformly across read/write/delete
-// paths so callers can treat them as success (delete) or
-// not-found (read). The SDK exposes BlobNotFoundError as a class with
-// `.name === 'BlobNotFoundError'`; checking the name string avoids
-// importing the class at the top level (which would force the optional
-// peer dep to resolve).
-//
-// Class-name check ONLY — the SDK's internal mapper turns every API
-// `not_found` into BlobNotFoundError-by-name, so a bare-404 transport
-// leak doesn't reach here. A broader `/does not exist|\b404\b/` match
-// is DANGEROUS: it also matches BlobStoreNotFoundError's "This store
-// does not exist.", so a config fault (revoked token, deleted store)
-// would silently surface as every-blob-missing across reads/unlinks,
-// masking the fatal misconfiguration. The tight name check lets
-// BlobStoreNotFoundError / other classes propagate as real exceptions.
-function isNotFound(err: unknown): boolean {
-  if (err == null || typeof err !== 'object') return false
-  const name = (err as { name?: unknown }).name
-  return typeof name === 'string' && name === 'BlobNotFoundError'
-}
+import { type VercelBlobSdk, isNotFound, loadVercelBlobSdk } from '../../server-common/vercel-blob.ts'
 
 function liveBlobPath(tag: string, contentHash: string): string {
   return `${tag}/${contentHash}.bin`
@@ -293,7 +195,7 @@ function buildStatStaging(sdk: VercelBlobSdk, token: string): BlobBackend['statS
       const h = await sdk.head(stagingBlobPath(tag, stagingId), { token })
       return h.size
     } catch (err) {
-      if (isNotFound(err)) return null
+      if (isNotFound(err, sdk)) return null
       throw err
     }
   }
@@ -363,20 +265,20 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
       // `not-found` would emit a 404 the FS backend never emits for the
       // same condition (blob-fs.ts maps ENOENT → `unavailable`), telling
       // the client the resource is gone for good when it should refetch.
-      // See server/README.md's GET status table.
-      if (isNotFound(err)) return { ok: false, reason: 'unavailable' }
+      // See server-e2e/README.md's GET status table.
+      if (isNotFound(err, sdk)) return { ok: false, reason: 'unavailable', detail: 'vercel-get-not-found' }
       throw err
     }
     // SDK returned null (no blob) — same "bytes missing for a live row"
     // transient as the BlobNotFoundError branch above → `unavailable`, not
     // `not-found`.
-    if (res == null) return { ok: false, reason: 'unavailable' }
+    if (res == null) return { ok: false, reason: 'unavailable', detail: 'vercel-get-null' }
     // statusCode 304 doesn't reach here in practice — the REST
     // GET layer doesn't pass If-None-Match — but a future call
     // site could. Treat as unavailable rather than streaming a
     // null body.
     if (res.statusCode !== 200 || res.stream == null) {
-      return { ok: false, reason: 'unavailable' }
+      return { ok: false, reason: 'unavailable', detail: `vercel-get-status-${res.statusCode}` }
     }
     // `@vercel/blob@2.x`'s streaming `get()` for private blobs returns
     // the body but does NOT populate `blob.size` nor pass a
@@ -395,11 +297,11 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
         // Blob vanished between get() and the head() size fallback (a
         // racing reaper GC) — still the "live row present, bytes gone"
         // transient, so `unavailable` (503), matching the get() path above.
-        if (isNotFound(headErr)) return { ok: false, reason: 'unavailable' }
+        if (isNotFound(headErr, sdk)) return { ok: false, reason: 'unavailable', detail: 'vercel-head-not-found' }
         throw headErr
       }
     }
-    if (size == null) return { ok: false, reason: 'unavailable' }
+    if (size == null) return { ok: false, reason: 'unavailable', detail: 'vercel-no-size' }
     // SDK returns a web ReadableStream<Uint8Array>; the REST layer
     // expects a Node Readable for pipeline(). Convert via
     // Readable.fromWeb — built-in and zero-copy where possible.
@@ -426,7 +328,7 @@ function buildOpenLiveReader(sdk: VercelBlobSdk, token: string): BlobBackend['op
 function buildUnlink(sdk: VercelBlobSdk, token: string, op: 'staging' | 'live', toPath: (tag: string, id: string) => string): (tag: string, id: string) => Promise<void> {
   return async (tag, id) => {
     try { await sdk.del(toPath(tag, id), { token }) } catch (err) {
-      if (isNotFound(err)) return
+      if (isNotFound(err, sdk)) return
       // Don't propagate — the DB-side row drop has already
       // committed by the time the caller reaches here, and the
       // reaper picks up the stranded blob on its next sweep. Same
@@ -493,7 +395,7 @@ export type VercelBlobBackendOptions = {
   // Vercel Blob R/W token, typically from BLOB_READ_WRITE_TOKEN.
   // The SDK also reads it from process.env, but passing it
   // explicitly here keeps the env-var → boot config path single-
-  // sourced through server/index.ts (matches the Neon DATABASE_URL
+  // sourced through server-e2e/index.ts (matches the Neon database URL
   // handling — env-read at boot, threaded as a parameter).
   token: string
   // Test seam: inject a stub of the @vercel/blob module to avoid
@@ -507,7 +409,7 @@ export async function openVercelBlobBackend(opts: VercelBlobBackendOptions): Pro
   // dep. `@ts-ignore` (not `@ts-expect-error`) so an operator who
   // DOES install `@vercel/blob` doesn't trip TS2578 "unused
   // directive" — same pattern as db-neon.ts.
-  const sdk: VercelBlobSdk = opts.sdk ?? (await loadSdk())
+  const sdk: VercelBlobSdk = opts.sdk ?? (await loadVercelBlobSdk())
   const token = opts.token
   return {
     // No-op: Vercel Blob has no folder concept. The pathname's
@@ -533,9 +435,3 @@ export async function openVercelBlobBackend(opts: VercelBlobBackendOptions): Pro
     listStagingIds: buildListStagingIds(sdk, token, (tag) => `${tag}/.staging/`),
   }
 }
-
-async function loadSdk(): Promise<VercelBlobSdk> {
-  // @ts-ignore optional peer dep: '@vercel/blob'
-  const mod = (await import('@vercel/blob')) as VercelBlobSdk
-  return mod
-}

package/{server → server-e2e}/objstore/blob.ts

@@ -11,7 +11,7 @@
 //                         the Neon DB plane for multi-replica
 //                         deployments)
 //
-// Selected at boot in `server/index.ts` and passed to `openObjstore`
+// Selected at boot in `server-e2e/index.ts` and passed to `openObjstore`
 // / `openNeonObjstore`. The DB-plane code in ./store.ts, ./rest.ts,
 // and ./reaper.ts goes through `handle.blob.*` and is backend-
 // agnostic — no `if (vercel) … else` branching in consumers.
@@ -94,9 +94,16 @@ export type LiveReader = {
 // `unavailable`/503 contract, which the client retries. Both backends MUST
 // map a missing blob to `unavailable` (FS: ENOENT; Vercel: BlobNotFoundError
 // / null get()). No 404-mapping variant exists here so that bug can't recur.
+//
+// `detail` is a short, NON-SENSITIVE machine tag for the specific cause
+// (e.g. 'vercel-get-not-found', 'fs-enoent', 'vercel-no-size'). Every
+// byte-side failure collapses to the same 503 on the wire, so a permanent
+// loss (reaper GC'd the bytes) and a transient read fault are otherwise
+// indistinguishable — the REST layer logs `detail` so an operator can tell
+// them apart. Purely diagnostic; the REST status is unchanged.
 export type OpenLiveResult =
   | { ok: true; reader: LiveReader }
-  | { ok: false; reason: 'unavailable' }
+  | { ok: false; reason: 'unavailable'; detail?: string }
 
 export type BlobBackend = {
   // Per-workspace setup. FS creates the on-disk staging directory;

package/server-e2e/objstore/fetch-mint-guard.ts

@@ -0,0 +1,74 @@
+// Anti-replay guard for the REST fetch-mint endpoint (POST
+// /api/objstore/{tag}/{res}, see ./rest.ts). The WS fetch handshake binds
+// the per-connection challenge nonce so a captured frame can't be
+// replayed; the REST mint has no connection, so it binds a client
+// timestamp instead and this guard supplies the matching freshness +
+// dedup the nonce gave for free:
+//
+//   - FRESHNESS: reject a request whose `ts` is outside ±`windowMs` of
+//     server time (an old captured request, or a future-dated one).
+//   - DEDUP: within the window, a signature is accepted at most once — a
+//     captured-and-replayed request (same `ts` ⇒ same signature) is
+//     rejected on the second presentation.
+//
+// Memory: each accepted signature is held for `windowMs` then pruned.
+// Entries share a uniform TTL and the Map preserves insertion order, so
+// the oldest entries expire first and a cheap front-prune (amortised
+// O(1) per entry) keeps the set bounded; a hard `maxEntries` cap drops
+// the oldest beyond it as a flood backstop.
+//
+// Scope: per-process. In a multi-replica deployment a captured request
+// could be replayed once per replica that hasn't seen its signature yet
+// (bounded by the replica count, within the window) — acceptable because
+// the mint only ever yields a short-TTL GET token over AEAD ciphertext
+// the relay can't read. A shared-store dedup (Redis/Neon) would close
+// that residual gap if ever needed.
+
+export type FetchMintVerdict = 'ok' | 'stale' | 'replay'
+
+export type FetchMintGuard = {
+  // `signature` is the request's Ed25519 signature (unique per
+  // (tag, res, ts) tuple, so it doubles as the dedup key). `ts` is the
+  // client epoch-ms timestamp the signature commits to; `now` is the
+  // server clock (injectable for tests).
+  admit: (signature: string, ts: number, now?: number) => FetchMintVerdict
+  size: () => number
+}
+
+export const DEFAULT_FETCH_MINT_WINDOW_MS = 60_000
+export const DEFAULT_FETCH_MINT_MAX_ENTRIES = 50_000
+
+export function createFetchMintGuard(
+  { windowMs = DEFAULT_FETCH_MINT_WINDOW_MS, maxEntries = DEFAULT_FETCH_MINT_MAX_ENTRIES }:
+    { windowMs?: number; maxEntries?: number } = {},
+): FetchMintGuard {
+  // signature → expiry (ms). Insertion-ordered; uniform TTL ⇒ the head is
+  // always the soonest to expire.
+  const seen = new Map<string, number>()
+
+  function admit(signature: string, ts: number, now: number = Date.now()): FetchMintVerdict {
+    // Freshness first — a stale/future request never touches the cache, so
+    // it can't be used to grow the set.
+    if (!Number.isFinite(ts) || Math.abs(now - ts) > windowMs) return 'stale'
+    // Front-prune expired entries (contiguous at the head under the
+    // uniform TTL). Breaks at the first live entry.
+    for (const [key, exp] of seen) {
+      if (exp > now) break
+      seen.delete(key)
+    }
+    // Post-prune, any remaining entry is live, so a hit is a genuine replay.
+    if (seen.has(signature)) return 'replay'
+    seen.set(signature, now + windowMs)
+    // Flood backstop: drop the oldest beyond the cap. Those are the
+    // closest to expiry anyway; dropping them only shortens their dedup
+    // window (still freshness-gated).
+    while (seen.size > maxEntries) {
+      const oldest = seen.keys().next().value
+      if (oldest === undefined) break
+      seen.delete(oldest)
+    }
+    return 'ok'
+  }
+
+  return { admit, size: () => seen.size }
+}