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

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)
+}

package/server-common/storage-log.ts

@@ -0,0 +1,34 @@
+import { dirname, resolve } from 'node:path'
+
+type DatabaseConfig = { dbPath: string; neonUrl?: string | null }
+
+function databaseLocation({ dbPath, neonUrl }: DatabaseConfig): string {
+  if (!neonUrl) return `SQLite ${dbPath === ':memory:' ? dbPath : resolve(dbPath)}`
+  // Report the destination, never URL credentials or query-string secrets.
+  try {
+    const url = new URL(neonUrl)
+    return `Neon Postgres ${url.host}${url.pathname}`
+  } catch { return 'Neon Postgres' }
+}
+
+export function e2eStorageLines(config: DatabaseConfig & { objstoreDir: string }): string[] {
+  return [
+    `  E2E database: ${databaseLocation(config)}`,
+    `  E2E objects: ${config.neonUrl ? 'Vercel Blob (private), {workspaceTag}/' : resolve(config.objstoreDir)}`,
+    `  E2E staging: ${config.neonUrl ? 'Vercel Blob (private), {workspaceTag}/.staging/' : resolve(config.objstoreDir, '{workspaceTag}', '.staging')}`,
+  ]
+}
+
+export function managedStorageLines(config: DatabaseConfig): string[] {
+  const dir = dirname(config.dbPath)
+  const location = (path: string) => config.neonUrl ? `Vercel Blob (private), .managed/${path}/` : resolve(dir, path)
+  return [
+    `  Managed database: ${databaseLocation(config)}`,
+    `  Managed reports: ${location('reports')}`,
+    `  Managed bundles: ${location('bundles')}`,
+    `  Managed avatars: ${location('avatars')}`,
+    `  Managed bundle cache: ${location('cache/bundles')}`,
+    `  Managed report sources cache: ${location('cache/report-sources')}`,
+    ...(config.neonUrl ? [`  Managed upload parts: ${location('uploads')}`] : []),
+  ]
+}

package/server-common/vercel-blob.ts

@@ -0,0 +1,110 @@
+// Shared optional Vercel Blob SDK boundary for both server modes.
+import type { Readable } from 'node:stream'
+import type { Buffer } from 'node:buffer'
+
+// Minimal structural shape of the bits of `@vercel/blob` we use.
+// Shared 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>
+export type VercelBlobSdk = {
+  put: (
+    pathname: string,
+    body: VercelBlobBody,
+    options: {
+      access: 'private' | 'public'
+      addRandomSuffix?: boolean
+      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'
+      addRandomSuffix?: boolean
+      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.
+export 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'
+}
+
+export async function loadVercelBlobSdk(): Promise<VercelBlobSdk> {
+  // @ts-ignore optional peer dep: '@vercel/blob'
+  const mod = (await import('@vercel/blob')) as VercelBlobSdk
+  return mod
+}