@preventive/triage 1.0.0-alpha.17 → 1.0.0-alpha.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.17",
+  "version": "1.0.0-alpha.19",
   "description": "Client & relay server for triaging of automated reports",
   "license": "MIT",
   "author": {
@@ -40,6 +40,7 @@
   },
   "files": [
     "api/reap.ts",
+    "server-e2e/app.ts",
     "server-e2e/auth.ts",
     "server-e2e/bus-receiver.ts",
     "server-e2e/cli.js",
@@ -80,11 +81,19 @@
     "server-e2e/validation.ts",
     "server-e2e/ws-server.ts",
     "server-e2e/config.example.json",
+    "server-common/database-config.ts",
+    "server-common/initialize.ts",
+    "server-common/reap.ts",
+    "server-common/npm-advisories.ts",
     "server-common/origin.ts",
+    "server-common/standalone.ts",
+    "server-common/storage-log.ts",
+    "server-common/vercel-blob.ts",
     "server-common/scan-config.ts",
     "report/index.js",
     "report/src/finding-id.js",
     "report/src/finding.js",
+    "report/src/security.js",
     "report/src/labels.js",
     "report/src/md-structure.js",
     "report/src/md-text.js",
@@ -109,6 +118,7 @@
     "common/utf8.js",
     "out/brotli-fallback.js",
     "out/client-managed.js",
+    "out/client-managed-import.js",
     "out/client-sync.js",
     "out/graph.js",
     "out/icon-maskable.svg",
@@ -116,7 +126,6 @@
     "out/index.html",
     "out/manifest.webmanifest",
     "out/prism.js",
-    "out/provider-icons",
     "out/stasis.svg",
     "out/terminal.js",
     "out/view.css",
@@ -126,20 +135,20 @@
   ],
   "scripts": {
     "lint": "node --run lint:js && node --run lint:css && node --run lint:ts",
-    "lint:js": "oxlint -c .oxlintrc.json --ignore-pattern=ui/logs.js ./tests/ ./common/ ./report/ ./server-common/ ./server-e2e/ ./server-managed/ ./client/ ./ui/ ./api/",
+    "lint:js": "oxlint -c .oxlintrc.json --ignore-pattern=ui/logs.js ./cli.js ./server.ts ./tests/ ./common/ ./report/ ./server-common/ ./server-e2e/ ./server-managed/ ./client/ ./ui/ ./api/",
     "lint:css": "stylelint 'ui/**/*.css'",
     "lint:ts": "tsc --noEmit",
     "prepack": "node --run build",
     "build": "node build.js build",
     "serve": "node build.js serve",
-    "server": "node server-e2e/index.ts",
+    "server": "node --run server-e2e --",
+    "server-e2e": "node server-e2e/index.ts",
     "server-managed": "node server-managed/index.ts",
     "server-managed-test": "node server-managed/test-server.ts",
-    "test": "node --js-base-64 --experimental-test-module-mocks --test-timeout=120000 --test ./tests/*.test.js ./report/tests/*.test.js"
+    "test": "node --js-base-64 --import=./tests/_resource-loader.js --experimental-test-module-mocks --test-timeout=120000 --test ./tests/*.test.js ./report/tests/*.test.js"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.5",
-    "@exodus/stasis-core": "^1.0.0-beta.4",
     "@noble/ciphers": "^2.3.0",
     "@preventive/diff": "^1.0.0",
     "@preventive/terminal": "2.0.0-beta.1",
@@ -158,6 +167,7 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
+    "@exodus/stasis-core": "^1.0.0-beta.4",
     "ws": "^8.20.1"
   },
   "peerDependencies": {

package/report/index.js

@@ -89,6 +89,7 @@ import { deriveFindingId } from './src/finding-id.js'
 export { parseCodexCsvToScans } from './src/parse-codex.js'
 export { computeFileHash, deriveFindingId, findingId } from './src/finding-id.js'
 export { META_FIELDS, inheritReportMeta, repoDirectory, reportRepoGithub } from './src/meta.js'
+export { stampSecurityGroups } from './src/security.js'
 // The writing side: the document writer, and the label tables it
 // spells the app's enumerations with, for the viewer's surfaces that
 // describe the same things in prose.
@@ -104,7 +105,7 @@ export { COLOR_LABELS, SEVERITY_LABELS, SOURCE_LABELS, TRIAGE_LABELS, severityLa
 export {
   REVALIDATE_KINDS, SEVERITIES, SEVERITY_ORDER, correctedVariants, descriptionSections,
   displayedSeverity, effectiveSeverity, evidenceNote, findingDisplayName, findingTitle,
-  firstLine, hasSeverityCorrection, isAppFinding, locationLabel, prettyModel, revalidateKindOf,
+  firstLine, hasSeverityCorrection, isAppFinding, isSecurityFinding, locationLabel, prettyModel, revalidateKindOf,
   runMetaLine, splitDescription, stripExportMarker, titledDescription,
 } from './src/finding.js'
 

package/report/src/finding.js

@@ -105,6 +105,18 @@ export function isAppFinding(f, source = f?.source) {
   return Object.hasOwn(SOURCE_LABELS, source) || revalidateKindOf(f) === 'revalidation'
 }
 
+// Security involvement is independent of the App/code layer and the displayed
+// (possibly corrected) severity. External reports use their original severity,
+// not the synthetic report-level `type: security` supplied by their parsers.
+// `security: false` opts out of the analyzer default, not the other OR rules.
+export function isSecurityFinding(f, source = f?._source ?? f?.source) {
+  const external = typeof source === 'string' && source !== '' && source !== 'deepview'
+  const analyzer = external ? source : f?.analyzer ?? f?.type ?? f?._analyzer
+  return f?.security === true
+    || ((analyzer === 'security' || analyzer === 'dependencies') && f?.security !== false)
+    || (external && ['critical', 'high', 'medium', 'low'].includes(f?.severity))
+}
+
 // ── Run meta ─────────────────────────────────────────────────────────
 export function prettyModel(model) {
   if (!model) return model

package/report/src/security.js

@@ -0,0 +1,63 @@
+import { isSecurityFinding } from './finding.js'
+
+function securityGraph() {
+  const ids = [], nodes = new Map()
+  const nodeFor = (key) => {
+    if (!nodes.has(key)) {
+      const node = { security: false }
+      node.parent = node
+      nodes.set(key, node)
+      if (typeof key === 'string') ids.push(key)
+    }
+    return nodes.get(key)
+  }
+  const root = (node) => {
+    let current = node
+    while (current.parent !== current) current = current.parent
+    while (node.parent !== node) { const next = node.parent; node.parent = current; node = next }
+    return current
+  }
+  const join = (a, b) => {
+    a = root(a); b = root(b)
+    if (a !== b) { b.parent = a; a.security ||= b.security }
+  }
+  return { nodeFor, root, join, ids }
+}
+
+// Stamp the complete row/link component, before any display lens hides tabs.
+// The callbacks are synchronous lookups of already-known links and index rows;
+// this never loads reports. Only the supplied findings are mutated. Recompute
+// from intrinsic evidence so removing a sibling/link does not latch a true flag.
+export function stampSecurityGroups(groups, { source, linkedIds = () => [], knownRows = () => [] } = {}) {
+  const { nodeFor, root, join, ids } = securityGraph()
+  const findings = []
+  const addRow = (group, known = false) => {
+    let first
+    for (const f of group) {
+      if (!f || typeof f !== 'object') continue
+      const node = nodeFor(f.id || f)
+      root(node).security ||= known ? f.isSecurity === true : isSecurityFinding(f, f._source ?? f.source ?? source)
+      if (first) join(first, node)
+      else first = node
+      if (!known) findings.push([f, node])
+    }
+  }
+  for (const group of groups) addRow(group)
+  const seenRows = new Set()
+  // Growing queue: a known linked row can have siblings with links of their own.
+  for (let i = 0; i < ids.length; i++) {
+    const id = ids[i], node = nodeFor(id)
+    for (const other of linkedIds(id)) join(node, nodeFor(other))
+    for (const row of knownRows([id])) {
+      if (seenRows.has(row)) continue
+      seenRows.add(row)
+      addRow(row.members, true)
+    }
+  }
+  let changed = false
+  for (const [f, node] of findings) {
+    const security = root(node).security
+    if (f.isSecurity !== security) { f.isSecurity = security; changed = true }
+  }
+  return changed
+}

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