@preventive/triage 1.0.0-alpha.4 → 1.0.0-alpha.40

package/risk/npm/specs.js

@@ -0,0 +1,124 @@
+// Where npm installs a dependency from, read off its spec as npm-package-arg
+// reads one: the registry (a version, a range, a tag, an `npm:` alias), a
+// path, a repository on a host npm knows, a git URL or a tarball's.
+
+// The hosts npm takes a repository on (hosted-git-info, which npm-package-arg
+// reads a spec with): by name (`github:owner/repo`), or by its domain over
+// the protocols each takes, where its path names a repository, `[user,
+// project, committish]`, and not a tarball or a file.
+const trim = project => project?.replace(/\.git$/u, '')
+const GIT_HOSTS = new Map([
+  ['github', { label: 'GitHub', domain: 'github.com', protocols: ['git:', 'http:', 'git+ssh:', 'git+https:', 'ssh:', 'https:'], repo({ pathname, hash }) {
+    const [, user, project, type, committish] = pathname.split('/', 5)
+    return (!type || type === 'tree') && user && trim(project) ? [user, trim(project), type ? committish : hash.slice(1)] : null
+  } }],
+  ['bitbucket', { label: 'Bitbucket', domain: 'bitbucket.org', protocols: ['git+ssh:', 'git+https:', 'ssh:', 'https:'], repo({ pathname, hash }) {
+    const [, user, project, aux] = pathname.split('/', 4)
+    return aux !== 'get' && user && trim(project) ? [user, trim(project), hash.slice(1)] : null
+  } }],
+  ['gitlab', { label: 'GitLab', domain: 'gitlab.com', protocols: ['git+ssh:', 'git+https:', 'ssh:', 'https:'], repo({ pathname, hash }) {
+    const path = pathname.slice(1)
+    const at = path.lastIndexOf('/')
+    if (path.includes('/-/') || path.includes('/archive.tar.gz')) return null
+    return path.slice(0, Math.max(at, 0)) && trim(path.slice(at + 1)) ? [path.slice(0, at), trim(path.slice(at + 1)), hash.slice(1)] : null
+  } }],
+  ['gist', { label: 'Gist', domain: 'gist.github.com', protocols: ['git:', 'git+ssh:', 'git+https:', 'ssh:', 'https:'], repo({ pathname, hash }) {
+    const [, user, project, aux] = pathname.split('/', 4)
+    return aux !== 'raw' && (user || project) ? [project ? user : null, trim(project || user), hash.slice(1)] : null
+  } }],
+  ['sourcehut', { label: 'SourceHut', domain: 'git.sr.ht', protocols: ['git+ssh:', 'https:'], repo({ pathname, hash }) {
+    const [, user, project, aux] = pathname.split('/', 4)
+    return aux !== 'archive' && user && trim(project) ? [user, trim(project), hash.slice(1)] : null
+  } }],
+])
+const BY_DOMAIN = new Map([...GIT_HOSTS.values()].map(host => [host.domain, host]))
+// The protocols hosted-git-info reads a URL by as it is, the hosts' names too.
+const PROTOCOLS = new Set(['git+ssh:', 'ssh:', 'git+https:', 'git:', 'http:', 'https:', 'git+http:', ...[...GIT_HOSTS.keys()].map(name => `${name}:`)])
+
+// GitHub's `owner/repo` shorthand, before a commit, branch or tag
+// (`#v1.0.0`) or not, as hosted-git-info tells it: a slash, not first, nor
+// last before any `#`; no `.` first; and no space, `@`, `:` or second slash
+// before any `#`.
+function githubShorthand(spec) {
+  const hash = spec.indexOf('#'), slash = spec.indexOf('/')
+  const beforeHash = at => at > -1 && !(hash > -1 && at > hash)
+  return slash > 0 && !spec.startsWith('.') && (hash > -1 ? spec[hash - 1] !== '/' : !spec.endsWith('/'))
+    && ![/\s/u.exec(spec)?.index ?? -1, spec.indexOf('@'), spec.indexOf(':'), spec.indexOf('/', slash + 1)].some(beforeHash)
+}
+
+// A URL as hosted-git-info parses one: a protocol it doesn't know put
+// before a `git@host:path` (as `git+ssh://`) or given its `//`, and else
+// `host:path` read as `host/path`.
+const safeUrl = text => { try { return new URL(text) } catch { return null } }
+function hostedUrl(spec) {
+  const at = spec.indexOf('@'), colon = spec.indexOf(':')
+  const corrected = PROTOCOLS.has(spec.slice(0, colon + 1)) || at > -1 && at < colon ? spec : at > -1 ? `git+ssh://${spec}`
+    : spec.indexOf('//') === colon + 1 ? spec : `${spec.slice(0, colon + 1)}//${spec.slice(colon + 1)}`
+  if (safeUrl(corrected)) return safeUrl(corrected)
+  const before = char => { const hash = corrected.indexOf('#'); return corrected.lastIndexOf(char, hash > -1 ? hash : Infinity) }
+  let scp = before(':') > before('@') ? `${corrected.slice(0, before(':'))}/${corrected.slice(before(':') + 1)}` : corrected
+  if (scp.lastIndexOf(':', scp.indexOf('#') > -1 ? scp.indexOf('#') : Infinity) === -1 && !scp.includes('//')) scp = `git+ssh://${scp}`
+  return safeUrl(scp)
+}
+
+// The host npm takes a spec's repository on (hosted-git-info's fromUrl), or
+// null: one by its name, whatever its path, or by its domain over a protocol
+// it takes, where its path names a repository; none whose parts don't
+// decode.
+function gitHost(spec) {
+  if (!spec) return null
+  const url = hostedUrl(githubShorthand(spec) ? `github:${spec}` : spec)
+  if (!url) return null
+  const named = GIT_HOSTS.get(url.protocol.slice(0, -1))
+  const host = named ?? BY_DOMAIN.get(url.hostname.replace(/^www\./u, ''))
+  const parts = named ? [url.pathname.replace(/^\/?[^@]*@|^\//u, ''), url.hash.slice(1)] : host?.protocols.includes(url.protocol) && host.repo(url)
+  try { return parts ? (parts.forEach(part => part && decodeURIComponent(part)), host) : null } catch { return null }
+}
+
+// Where npm installs a dependency's spec from, read once in
+// npm-package-arg's resolve order: `path` for a path (`./x`, `~/x`, `/x`,
+// `c:/x`, `file:`); `registry` for an `npm:` alias of a registry package,
+// or a spec with no `/` or `:` that names no tarball, which no later step
+// takes; a repository on a host npm knows (gitHost), named for it
+// (`GitHub`); for a URL, `git` for a repository's (`git:`, `git+https:`,
+// `git+ssh:`, `git+http:`, `git+rsync:`, `git+ftp:`, `git+file:`, and
+// `git+ssh://` to `user@host:path`), `URL` for a tarball's (`https:`,
+// `http:`), and null for one npm doesn't install (`workspace:`, `ssh:` on
+// another host); then `path` again for one with a `/` or a tarball's name
+// (`a/b/c`, `x.tgz`, `git@example.com:x/y`), and else `registry`: a
+// version, a range or a tag.
+function specFrom(spec) {
+  const value = String(spec ?? '').trim()
+  if (/^(?:[.]|~\/|\/|[a-z]:|file:)/iu.test(value)) return 'path'
+  if (/^npm:/iu.test(value) || !/[/:]|[.](?:tgz|tar\.gz|tar)$/iu.test(value)) return 'registry'
+  const host = gitHost(value)
+  if (host) return host.label
+  if (/^(?:git\+)?[a-z]+:/iu.test(value)) {
+    const scp = /^git\+ssh:\/\/([^:#]+:[^#]+(?:\.git)?)(?:#.*)?$/iu.exec(value)
+    if (value.startsWith('git+ssh:') && scp && !/:\d+(?:\/|$)/u.test(scp[1])) return 'git'
+    const protocol = safeUrl(value)?.protocol
+    return /^(?:git|git\+(?:https?|rsync|ftp|file|ssh)):$/u.test(protocol) ? 'git' : /^https?:$/u.test(protocol) ? 'URL' : null
+  }
+  return /\/|[.](?:tgz|tar\.gz|tar)$/iu.test(value) ? 'path' : 'registry'
+}
+
+// Where a dependency's spec has npm fetch it from, where that isn't its
+// registry (specFrom): a host's name (`GitHub`), `git` or `URL`. Null for
+// the registry's ranges and tags, a path, and what npm doesn't install.
+export function npmDependencySource(spec) {
+  const from = specFrom(spec)
+  return from === 'registry' || from === 'path' ? null : from
+}
+
+// The package and spec an `npm:` alias names (`npm:pkg@^1.2.3`), as
+// specFrom reads one; null for a spec that isn't one.
+export function npmAlias(spec) {
+  const [, name, range = ''] = /^npm:((?:@[^/@]+\/)?[^/@]+)(?:@(.*))?$/iu.exec(String(spec ?? '').trim()) ?? []
+  return name ? { name, spec: range } : null
+}
+
+// Whether npm installs a dependency's spec from its registry (specFrom):
+// not from a path, a repository or a URL, nor a scheme npm doesn't install
+// (`workspace:`), the registry's package of that name being what npm
+// installs for none of those.
+export const npmRegistrySpec = spec => specFrom(spec) === 'registry'

package/risk/npm/tarball.js

@@ -0,0 +1,113 @@
+// A package's files from its tarball, as npm installs them: gunzipped, read as
+// a tar archive (ustar, pax and GNU long names), each file by the path npm
+// installs it at, its first component dropped, none escaping the package; a
+// text where it is UTF-8 with no NUL, else null. Held to the npm viewer's
+// bounds (server-managed/npm-packages.ts readNpmTar).
+const MAX_PACKAGE_FILES = 20_000
+export const MAX_PACKAGE_BYTES = 64 * 1024 * 1024
+// What its tar stream may unpack to, its headers and padding beside its
+// files, as npm-loads.ts bounds it (MAX_TAR_BYTES).
+export const MAX_TAR_BYTES = 96 * 1024 * 1024
+
+const latin1 = new TextDecoder('latin1')
+const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+const utf8Lenient = bytes => new TextDecoder().decode(bytes)
+// A header's text field, to its first NUL.
+const textOf = (bytes, start, length) => {
+  const field = bytes.subarray(start, start + length)
+  const end = field.indexOf(0)
+  return utf8Lenient(end === -1 ? field : field.subarray(0, end))
+}
+
+// A header's size field: octal, or GNU base-256 past its 11 digits.
+function sizeOf(bytes, offset) {
+  if (bytes[offset] & 0x80) {
+    let size = bytes[offset] & 0x7f
+    for (let i = 1; i < 12; i++) size = size * 256 + bytes[offset + i]
+    return size
+  }
+  const text = textOf(bytes, offset, 12).trim()
+  return /^[0-7]+$/u.test(text) ? Number.parseInt(text, 8) : Number.NaN
+}
+
+// A pax header's path: records `<length> <key>=<value>\n`, their lengths in
+// bytes.
+function paxPath(data) {
+  let at = 0, path = null
+  while (at < data.length) {
+    const space = data.indexOf(0x20, at)
+    const length = Number.parseInt(latin1.decode(data.subarray(at, space)), 10)
+    if (space === -1 || !Number.isSafeInteger(length) || length <= 0) break
+    const record = utf8Lenient(data.subarray(space + 1, at + length - 1))
+    if (record.startsWith('path=')) path = record.slice(5)
+    at += length
+  }
+  return path
+}
+
+const packagePath = raw => {
+  const parts = raw.split('/').slice(1).filter(part => part !== '' && part !== '.')
+  return parts.length === 0 || parts.includes('..') ? null : parts.join('/')
+}
+
+// The files of a tar archive, by path: their bytes.
+function npmTarFiles(tar) {
+  const files = new Map()
+  let longName = null, offset = 0, total = 0
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512)
+    if (header.every(byte => byte === 0)) break
+    const size = sizeOf(header, 124), start = offset + 512, type = String.fromCodePoint(header[156])
+    if (!Number.isSafeInteger(size) || size < 0 || start + size > tar.length) throw new Error('bad-tarball')
+    const data = tar.subarray(start, start + size)
+    offset = start + Math.ceil(size / 512) * 512
+    if (type === 'x' || type === 'L') { longName = type === 'x' ? paxPath(data) : textOf(data, 0, data.length); continue }
+    if (type === 'g' || type === 'K') continue
+    const prefix = textOf(header, 257, 6) === 'ustar' ? textOf(header, 345, 155) : ''
+    const name = longName ?? (prefix ? `${prefix}/${textOf(header, 0, 100)}` : textOf(header, 0, 100))
+    longName = null
+    const path = ['0', '\0', '7'].includes(type) ? packagePath(name) : null
+    if (path === null) continue
+    total += size - (files.get(path)?.length ?? 0)
+    files.set(path, data)
+    if (files.size > MAX_PACKAGE_FILES || total > MAX_PACKAGE_BYTES) throw new Error('package-too-large')
+  }
+  return files
+}
+
+// A file's text: UTF-8 with no NUL, else null.
+export function npmFileText(bytes) {
+  if (bytes.includes(0)) return null
+  try { return utf8.decode(bytes) } catch { return null }
+}
+
+// A gzipped tarball's tar stream, given up on as `package-too-large` once it
+// unpacks past MAX_TAR_BYTES, before any more of it is held.
+async function gunzip(gzipped) {
+  const reader = new Blob([gzipped]).stream().pipeThrough(new DecompressionStream('gzip')).getReader()
+  const chunks = []
+  let size = 0
+  for (let read = await reader.read(); !read.done; read = await reader.read()) {
+    size += read.value.byteLength
+    if (size > MAX_TAR_BYTES) { await reader.cancel(); throw new Error('package-too-large') }
+    chunks.push(read.value)
+  }
+  return new Uint8Array(await new Blob(chunks).arrayBuffer())
+}
+
+// A file's bytes' digest, as the managed server gives one of a file that
+// isn't text (server-managed/npm-packages.ts).
+const sha256 = async bytes => `sha256-${btoa(String.fromCodePoint(...new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))))}`
+
+// A gzipped tarball's files as a version holds them for risk, as the npm
+// viewer holds a version (ui/view/npm-package.js npmPackageDetails), a source
+// map listing them (`kind: 'sourcemap'`): `json.sources` their paths, sorted,
+// `json.sourcesContent` their texts, `fileSizes` by path, and `npmBinaries`,
+// those that aren't text, `{ size, digest }` by path, which compare.js and
+// diff.js tell them by.
+export async function npmTarballVersion(gzipped) {
+  const files = [...npmTarFiles(await gunzip(gzipped))].toSorted(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+  const texts = files.map(([, bytes]) => npmFileText(bytes))
+  const binaries = await Promise.all(files.filter((_, at) => texts[at] === null).map(async ([path, bytes]) => [path, { size: bytes.length, digest: await sha256(bytes) }]))
+  return { kind: 'sourcemap', json: { version: 3, sources: files.map(([path]) => path), sourcesContent: texts }, fileSizes: new Map(files.map(([path, bytes]) => [path, bytes.length])), npmBinaries: new Map(binaries) }
+}

package/server-common/database-config.ts

@@ -0,0 +1,16 @@
+import { env } from 'node:process'
+
+// One shared URL or per-mode URLs. Validate before opening either store so
+// an ambiguous configuration cannot send application traffic and GC elsewhere.
+export function databaseUrls({ combined = false } = {}) {
+  const shared = env['DATABASE_URL'] || null
+  const e2e = env['E2E_DATABASE_URL'] || null
+  const managed = env['MANAGED_DATABASE_URL'] || null
+  if (shared && (e2e || managed)) {
+    throw new Error('DATABASE_URL cannot be combined with E2E_DATABASE_URL or MANAGED_DATABASE_URL. Use the shared URL alone, or only the per-mode URLs.')
+  }
+  if (combined && Boolean(e2e) !== Boolean(managed)) {
+    throw new Error('Combined mode requires both E2E_DATABASE_URL and MANAGED_DATABASE_URL, DATABASE_URL alone, or no database URLs. Mixing Neon and SQLite is not supported.')
+  }
+  return { e2e: shared ?? e2e, managed: shared ?? managed }
+}

package/server-common/initialize.ts

@@ -0,0 +1,18 @@
+// Register resources as they are acquired. Failed assembly rolls them back in
+// reverse order; successful assembly transfers ownership to the returned app.
+export async function initializeApp<T>(assemble: (rollback: AsyncDisposableStack) => T | Promise<T>): Promise<T> {
+  const rollback = new AsyncDisposableStack()
+  try {
+    const app = await assemble(rollback)
+    rollback.move()
+    return app
+  } catch (error) {
+    try { await rollback.disposeAsync() }
+    catch (cleanupError) {
+      // AsyncDisposableStack runs every cleanup even if one fails. Preserve
+      // both failures so cleanup errors cannot hide the initialization error.
+      throw new SuppressedError(cleanupError, error, 'App initialization and cleanup failed')
+    }
+    throw error
+  }
+}

package/server-common/npm-advisories.ts

@@ -0,0 +1,101 @@
+import { Buffer } from 'node:buffer'
+
+const UPSTREAM_URL = 'https://registry.npmjs.org/-/npm/v1/security/advisories/bulk'
+const RESPONSE_BODY_LIMIT = 4 * 1024 * 1024
+export const NPM_ADVISORIES_TIMEOUT_MS = 30_000
+
+export async function fetchNpmAdvisories(body: Buffer, signal: AbortSignal, debug = false): Promise<{ status: number; body: unknown }> {
+  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 (debug) console.warn('npm-advisories upstream error:', err)
+    return { status: 502, body: { error: 'upstream-unreachable' } }
+  }
+  // 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 (debug) console.warn('npm-advisories upstream body error:', err)
+    return { status: 502, body: { error: 'upstream-unreachable' } }
+  }
+  if (buffered === null) {
+    if (debug) console.warn(`npm-advisories upstream too large: status=${upstream.status}`)
+    return { status: 502, body: { error: 'upstream-too-large', upstreamStatus: upstream.status } }
+  }
+  // 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 (debug) console.warn(`npm-advisories upstream non-JSON: status=${upstream.status} ct=${upstreamContentType || '<none>'} bytes=${buffered.byteLength}`)
+    return { status: 502, body: {
+      error: 'upstream-not-json',
+      upstreamStatus: upstream.status,
+      upstreamContentType: upstreamContentType || null,
+    } }
+  }
+  return { status: upstream.status, body: parsed }
+}
+
+// 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-common}/origin.ts

@@ -1,8 +1,8 @@
-// Same-origin gate for the WS upgrade and REST data plane. We don't
-// support cross-origin browser clients, so any Origin header present
-// on an incoming request MUST match the server's own host (derived
-// from `req.headers.host`, or from `X-Forwarded-Host` /
-// `X-Forwarded-Proto` when a trusted reverse proxy is in front).
+// Same-origin gate, shared by the e2e and managed servers (server-common).
+// We don't support cross-origin browser clients, so any Origin header present
+// on an incoming request MUST match the server's own host (derived from
+// `req.headers.host`, or from `X-Forwarded-Host` / `X-Forwarded-Proto` when a
+// trusted reverse proxy is in front).
 //
 // Why "present-must-match" rather than "always required":
 // - Browser WebSocket handshakes always carry Origin (RFC 6455), so a

package/server-common/reap.ts

@@ -0,0 +1,48 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+type Handler = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+type Reapers = Record<string, () => Promise<unknown>>
+type Options = { secret?: string; isShuttingDown?: () => boolean }
+
+// Start every cleanup and wait for all of them, including when one fails.
+// The caller must not close storage or return success with work still running.
+export async function runReapers(reapers: Reapers): Promise<void> {
+  const results = await Promise.allSettled(Object.values(reapers).map(reap => Promise.resolve().then(reap)))
+  const errors = results.filter(result => result.status === 'rejected').map(result => result.reason)
+  if (errors.length > 0) throw new AggregateError(errors, 'Cleanup failed')
+}
+
+export function createReapHandler(reapers: Reapers, { secret = process.env['CRON_SECRET'], isShuttingDown = () => false }: Options = {}) {
+  const key = randomBytes(32)
+  const hash = (value: string) => createHmac('sha256', key).update(value).digest()
+  const expected = secret ? hash(`Bearer ${secret}`) : null
+  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const send = (status: number, body: object, headers = {}) => {
+      res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', ...headers })
+      res.end(JSON.stringify(body))
+    }
+    const authorization = req.headers.authorization
+    if (req.headers['x-deepview-share'] !== undefined) { send(403, { error: 'share-scope-required' }); return }
+    if (!expected || typeof authorization !== 'string' || !timingSafeEqual(hash(authorization), expected)) {
+      send(401, { error: 'unauthorized' }); return
+    }
+    if (req.method !== 'GET') { send(405, { error: 'method-not-allowed' }, { allow: 'GET' }); return }
+    if (isShuttingDown()) { send(503, { error: 'shutting-down' }); return }
+    const startedAt = Date.now()
+    try {
+      await runReapers(reapers)
+      send(200, { ok: true, reaped: Object.keys(reapers), ms: Date.now() - startedAt })
+    } catch (err) {
+      console.error('reap failed:', err)
+      send(500, { error: 'reap-failed' })
+    }
+  }
+}
+
+// Only top-level servers compose this route. Domain routers stay unaware of
+// other modes, and cleanup uses the stores those servers have already opened.
+export function withReap(next: Handler, reapers: Reapers, options: Options = {}): Handler {
+  const reap = createReapHandler(reapers, options)
+  return (req, res) => req.url?.split('?', 1)[0] === '/api/reap' ? reap(req, res) : next(req, res)
+}

package/server-common/scan-config.ts

@@ -0,0 +1,19 @@
+import { normalizeScanServer } from '../common/scan-server.ts'
+
+export function configuredScanServer(value: string | undefined): string | null {
+  if (!value?.trim()) return null
+  const server = normalizeScanServer(value)
+  if (!server) throw new Error('DEEPVIEW_SCAN_SERVER must be an absolute HTTP(S) URL without credentials, query, or fragment')
+  return server
+}
+
+// Apply at serve time, before compression and ETag generation. Packaged HTML
+// stays strict and does not bake in the build machine's configuration.
+export function scanServerHtml(html: string, server: string | null, { advertise = false } = {}): string {
+  if (!server) return html
+  const origin = new URL(server).origin
+  const result = html.replace(/(connect-src 'self')(?=[;"])/u, `$1 ${origin}`)
+  if (!advertise) return result
+  const content = server.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;')
+  return result.replace('</head>', `<meta name="deepview-scan-server" content="${content}">\n</head>`)
+}

package/server-common/standalone.ts

@@ -0,0 +1,29 @@
+import type { Server } from 'node:http'
+
+// Only CLI entry points own process signals and termination. Embedded servers
+// expose async disposal and error events to their host instead.
+export function startServer(server: Server, config: { port: number; host: string }): void {
+  let shuttingDown = false
+  let exitCode = 0
+  function shutdown(code: number): void {
+    if (code !== 0) exitCode = code
+    if (shuttingDown) return
+    shuttingDown = true
+    console.log('Shutting down…')
+    void server[Symbol.asyncDispose]().catch(err => {
+      console.error('Shutdown failed:', err)
+      exitCode = 1
+    }).finally(() => process.exit(exitCode))
+  }
+  function onSignal(): void { shutdown(0) }
+  function onError(err: unknown): void {
+    console.error('Server error:', err)
+    shutdown(1)
+  }
+  server.on('error', onError)
+  process.on('SIGINT', onSignal)
+  process.on('SIGTERM', onSignal)
+  process.on('unhandledRejection', onError)
+  process.on('uncaughtException', onError)
+  server.listen(config.port, config.host)
+}