@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.51

package/risk/npm/release.js

@@ -0,0 +1,85 @@
+// What calls for a look at a version beside its files: one too new to
+// trust yet, one npm says is deprecated, a publisher that changed, provenance
+// the version before had and this one lost, and install scripts it adds or
+// changes. Each from what npm's version documents say, as manifest.js reads
+// them (`publisher`, `knownAccounts`, `provenance`, `installScripts`,
+// `deprecated`).
+import { DAY_MS } from './downloads.js'
+import { npmInstallScripts } from './install-scripts.js'
+
+// How old a version must be to be trusted, by default: two weeks, as a
+// compromised release is mostly found and pulled within days, so one this
+// new hasn't yet had the time to be. A caller's own packages (a team's npm
+// scopes) take 0: trusted however new.
+export const DEFAULT_MINIMUM_RELEASE_AGE = 14 * DAY_MS
+
+// Whether a version published at `published` (an ISO time) is too new to
+// trust at `now`: younger than `minimumReleaseAge`, none at 0.
+export const npmTooNew = (published, { minimumReleaseAge = DEFAULT_MINIMUM_RELEASE_AGE, now = Date.now() } = {}) =>
+  minimumReleaseAge > 0 && typeof published === 'string' && now - Date.parse(published) < minimumReleaseAge
+
+// How long before a version an account has published its package to be one
+// of its maintainers: three months, as an account given a package to take it
+// publishes its attack within weeks.
+const TENURE_MS = 90 * DAY_MS
+
+// Each account's standing on a package when a version of it was published
+// (`at`, an ISO time), by the package's versions as npm's document lists them
+// (`releases`, registry.js, `{ publisher, published }` each), as
+// `(account, known) => standing`: `known` where it publishes one of npm's
+// most downloaded packages (`known`, manifest.js `knownAccounts`), green;
+// `maintainer` where it published the package three months or more before,
+// or first, as its sole maintainer has, yellow; else `new`, as an account
+// taking the package from its maintainers is, orange. An account published it
+// first only where its versions tell so: the earliest npm lists a time of
+// was its, none of another's (or of none npm names, as one since removed) as
+// early, and each npm lists no time of was its too, as any could be earlier.
+export function npmAccountStanding(releases, at) {
+  const since = new Map()
+  let earliest = null
+  for (const { publisher, published } of releases) {
+    const time = Date.parse(published)
+    if (Number.isNaN(time)) continue
+    if (publisher && !(since.get(publisher) <= time)) since.set(publisher, time)
+    if (earliest === null || time < earliest.time) earliest = { publisher, time }
+    else if (time === earliest.time && publisher !== earliest.publisher) earliest.publisher = null
+  }
+  const first = earliest?.publisher && releases.every(({ publisher, published }) => publisher === earliest.publisher || !Number.isNaN(Date.parse(published)))
+    ? earliest.publisher : null
+  return (account, known) => known ? 'known' : account && (account === first || Date.parse(at) - since.get(account) >= TENURE_MS) ? 'maintainer' : 'new'
+}
+
+// The npm account that published each version, where npm says for both and
+// they differ, as when a package changes hands, or is taken over: `{ was,
+// now, wasKnown, nowKnown, severity }`, each account known where it publishes
+// one of npm's most downloaded packages (`knownAccounts`), and with the
+// package's versions told (`standing`, npmAccountStanding's of the open
+// version), each one's standing on it (`wasStanding`, `nowStanding`);
+// `moderate` where the open version's is known, or one of the package's
+// maintainers, `critical` where a known one gave way to one that isn't, else
+// `high`. Null where it didn't change.
+export function npmPublisherChange(from, to, standing = null) {
+  const now = to?.publisher, was = from?.publisher
+  if (!was || !now || was === now) return null
+  const nowKnown = to.knownAccounts?.includes(now) === true, wasKnown = from.knownAccounts?.includes(was) === true
+  const told = standing ? { wasStanding: standing(was, wasKnown), nowStanding: standing(now, nowKnown) } : {}
+  return { was, now, wasKnown, nowKnown, ...told, severity: nowKnown || told.nowStanding === 'maintainer' ? 'moderate' : wasKnown ? 'critical' : 'high' }
+}
+
+// Provenance the one compared with has and the open version hasn't, as a
+// version published by hand, with a token taken from its maintainers,
+// wouldn't.
+export const npmProvenanceLost = (from, to) => Boolean(from?.provenance && !to?.provenance)
+
+// The scripts npm runs installing the open version (`other`, its manifest
+// and `paths`, its files; install-scripts.js npmInstallScripts, node-gyp's
+// for a binding.gyp among them) that the one compared with (`base`) didn't,
+// or ran another command for: `{ was, now, flagged }`, each version's
+// scripts by name and the names flagged; null for none. One dropped isn't
+// flagged.
+export function npmInstallScriptsChange(base, other) {
+  const scripts = ({ manifest, paths }) => new Map(npmInstallScripts(manifest, paths))
+  const now = scripts(other), was = scripts(base)
+  const flagged = [...now].filter(([script, command]) => was.get(script) !== command).map(([script]) => script)
+  return flagged.length === 0 ? null : { was, now, flagged }
+}

package/risk/npm/score.js

@@ -0,0 +1,59 @@
+// A version's risk as one number, out of 100: what its findings call for,
+// lowered by how long it has been out among how many who would have noticed.
+// Its findings stay what a reviewer reads; the score orders what to read
+// first.
+import { DAY_MS } from './downloads.js'
+
+// How much each finding raises the score, by its severity: a version's
+// findings combined as independent chances are (1 − Π(1 − weight)), so that
+// each adds less the more there are, none past 100. One red finding alone is
+// 50; two are 75, and one with two orange 68, as attacks show.
+const WEIGHTS = { critical: 0.5, high: 0.2, moderate: 0.08, low: 0.03, notice: 0 }
+// What the version's age tells instead (`too-new`), as exposure does below.
+const TOLD_BY_AGE = new Set(['too-new'])
+
+// How much a version's exposure lowers the score, at most: a version out for
+// years among millions keeps a tenth of what its findings call for, as an
+// attack that long among that many would have been found and pulled.
+const MOST_LOWERED = 0.9
+// From how old a version is lowered at all, and how old fully: two weeks, as
+// risk's minimum release age (release.js), and two years, on a log scale.
+const EXPOSED_FROM_DAYS = 14
+const EXPOSED_DAYS = 730
+// How much who downloads a package lowers it, by its tier (downloads.js): its
+// rank by downloads. The top 200 fully; one few download hardly, as few would
+// notice; one whose downloads aren't known (null, a caller's own package, or
+// one npm counts none of) a little.
+const TIER_EXPOSURE = [[200, 1], [1000, 0.95], [5000, 0.85], [20_000, 0.65], [100_000, 0.35], [Infinity, 0.1]]
+const UNKNOWN_TIER_EXPOSURE = 0.25
+
+// The score's levels, as the findings' severities name theirs.
+const LEVELS = [[75, 'critical'], [50, 'high'], [25, 'moderate'], [0, 'low']]
+export const npmRiskLevel = score => LEVELS.find(([from]) => score >= from)[1]
+
+// How exposed a version has been, from 0 to 1: how long it has been out
+// (`published` an ISO time, at `now`) times how widely its package is
+// downloaded (`tier`, null where unknown).
+export function npmExposure(published, now, tier) {
+  const days = typeof published === 'string' ? (now - Date.parse(published)) / DAY_MS : NaN
+  if (!(days > EXPOSED_FROM_DAYS)) return 0
+  const age = Math.min(1, Math.log(days / EXPOSED_FROM_DAYS) / Math.log(EXPOSED_DAYS / EXPOSED_FROM_DAYS))
+  const wide = tier === null ? UNKNOWN_TIER_EXPOSURE : TIER_EXPOSURE.find(([upTo]) => tier <= upTo)[1]
+  return age * wide
+}
+
+// A version's risk score (`score`, 0 to 100) and its `level`, from its
+// assessment's `findings` and its exposure (npmExposure): 100 where malware
+// is told of it, however old; else what its findings call for (`raised`, each
+// `{ id, severity }` it counts), lowered by its exposure (`lowered`: its
+// `days` out, its `tier`, and by how much, a share), none lowered under two
+// weeks.
+export function npmRiskScore(findings, { published = null, now = Date.now(), tier = null } = {}) {
+  if (findings.some(({ id }) => id === 'malware')) return { score: 100, level: 'critical', raised: [{ id: 'malware', severity: 'critical' }] }
+  const raised = findings.filter(({ id, severity }) => !TOLD_BY_AGE.has(id) && WEIGHTS[severity] > 0).map(({ id, severity }) => ({ id, severity }))
+  const called = 1 - raised.reduce((left, { severity }) => left * (1 - WEIGHTS[severity]), 1)
+  const exposure = npmExposure(published, now, tier)
+  const score = Math.round(100 * called * (1 - MOST_LOWERED * exposure))
+  return { score, level: npmRiskLevel(score), raised,
+    ...exposure > 0 ? { lowered: { days: Math.floor((now - Date.parse(published)) / DAY_MS), tier: Number.isFinite(tier) ? tier : null, by: Math.round(100 * MOST_LOWERED * exposure) / 100 } } : {} }
+}

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,96 @@
+// A package's files from its tarball, as it holds them, whatever installs it
+// (npm renames a .gitignore .npmignore, pnpm and yarn keep it): gunzipped and
+// read as a tar archive by @preventive/archive, which refuses one malformed, a
+// name or a symlink that would climb out of it, and a name repeated as another
+// entry; each file by its path there, its first component dropped; 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).
+import { CompressionError, decompress } from '@preventive/archive/compression.js'
+import { ArchiveError, unpack } from '@preventive/archive/tar.js'
+
+const MAX_PACKAGE_FILES = 20_000
+export const MAX_PACKAGE_BYTES = 64 * 1024 * 1024
+// The entries its tar stream may hold, a directory's too, read before any is
+// counted as a file, as npm-packages.ts bounds them (MAX_NPM_TAR_ENTRIES).
+export const MAX_TAR_ENTRIES = 2 * MAX_PACKAGE_FILES
+// 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 utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+
+// The files of a tar archive, by path: their bytes. A file at its top is not
+// extracted, and one under another top directory at the same path replaces
+// an earlier one, as extraction would. Past MAX_TAR_ENTRIES it is given up on
+// as `package-too-large`, before any more of it is read.
+function npmTarFiles(tar) {
+  let entries
+  try {
+    entries = unpack(tar, { maxEntries: MAX_TAR_ENTRIES })
+  } catch (error) {
+    if (error instanceof ArchiveError && error.limited) throw new Error('package-too-large', { cause: error })
+    throw error
+  }
+  const files = new Map()
+  let total = 0
+  for (const { name, type, data } of entries) {
+    const slash = name.indexOf('/')
+    if ((type !== 'file' && type !== 'contiguous-file') || slash === -1) continue
+    const path = name.slice(slash + 1)
+    total += data.length - (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, through @preventive/archive's gzip, 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) {
+  try {
+    return await decompress(gzipped, 'gzip', { limit: MAX_TAR_BYTES })
+  } catch (error) {
+    if (error instanceof CompressionError && error.limited) throw new Error('package-too-large', { cause: error })
+    throw error
+  }
+}
+
+// Whether a file that isn't text may run as JavaScript all the same, as node
+// decodes it as UTF-8 (npm/files.js npmLoadedScripts): only where its first
+// character no UTF-8 encodes, or its first NUL, which JavaScript holds only
+// in a string, a template, a regular expression or a comment, may sit in
+// one, after a quote, a backtick, a slash, a `<` or `-` (an HTML-like
+// comment, `<!--`, `-->`) or on a hashbang's line. An image's, a font's or
+// WebAssembly's is in its first bytes, before any.
+const OPENS = [0x27, 0x22, 0x60, 0x2F, 0x3C, 0x2D]
+function npmRunnable(bytes) {
+  const start = bytes[0] === 0xEF && bytes[1] === 0xBB && bytes[2] === 0xBF ? 3 : 0
+  if (bytes[start] === 0x23 && bytes[start + 1] === 0x21) return true
+  const opens = Math.min(...OPENS.map(byte => bytes.indexOf(byte, start)).filter(at => at !== -1))
+  return Number.isFinite(opens) && npmFileText(bytes.subarray(0, opens)) !== null
+}
+
+// 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, runnable }` by path (npmRunnable),
+// 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), runnable: npmRunnable(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)
+}