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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.19",
+  "version": "1.0.0-alpha.20",
   "description": "Client & relay server for triaging of automated reports",
   "license": "MIT",
   "author": {
@@ -31,15 +31,20 @@
   "exports": {
     "./reap": "./api/reap.ts",
     "./report": "./report/index.js",
-    "./server": "./server-e2e/index.ts",
+    "./server": "./server.ts",
+    "./server-e2e": "./server-e2e/index.ts",
     "./strip-types-loader": "./strip-types-loader.js",
     "./package.json": "./package.json"
   },
   "bin": {
-    "triage-server": "server-e2e/cli.js"
+    "triage-server": "cli.js",
+    "triage-e2e-server": "server-e2e/cli.js",
+    "triage-managed-server": "server-managed/cli.js"
   },
   "files": [
     "api/reap.ts",
+    "cli.js",
+    "server.ts",
     "server-e2e/app.ts",
     "server-e2e/auth.ts",
     "server-e2e/bus-receiver.ts",
@@ -81,6 +86,56 @@
     "server-e2e/validation.ts",
     "server-e2e/ws-server.ts",
     "server-e2e/config.example.json",
+    "server-managed/activity.ts",
+    "server-managed/avatar-store.ts",
+    "server-managed/blob-store.ts",
+    "server-managed/blob-vercel.ts",
+    "server-managed/brotli.ts",
+    "server-managed/bundle-cache.ts",
+    "server-managed/bundle-catalog.ts",
+    "server-managed/bundle-store.ts",
+    "server-managed/bundle-summary-cache.ts",
+    "server-managed/bundle.ts",
+    "server-managed/cache-storage.ts",
+    "server-managed/cli.js",
+    "server-managed/combined.ts",
+    "server-managed/comments.ts",
+    "server-managed/config.ts",
+    "server-managed/content-access.ts",
+    "server-managed/crypto.ts",
+    "server-managed/db-methods.ts",
+    "server-managed/db-neon.ts",
+    "server-managed/db-schema.ts",
+    "server-managed/db-table-names.ts",
+    "server-managed/db.ts",
+    "server-managed/github-app.ts",
+    "server-managed/github-metadata.ts",
+    "server-managed/github-oauth.ts",
+    "server-managed/github-pulls.ts",
+    "server-managed/http-response.ts",
+    "server-managed/http.ts",
+    "server-managed/import-triage.ts",
+    "server-managed/index.ts",
+    "server-managed/public-workspace.ts",
+    "server-managed/repo-path.ts",
+    "server-managed/report-migration.ts",
+    "server-managed/report-query.ts",
+    "server-managed/report-response.ts",
+    "server-managed/report-sources.ts",
+    "server-managed/repository-discovery.ts",
+    "server-managed/repository-policy.ts",
+    "server-managed/session.ts",
+    "server-managed/slugs.ts",
+    "server-managed/sql-postgres.ts",
+    "server-managed/sql.ts",
+    "server-managed/static.ts",
+    "server-managed/storage.ts",
+    "server-managed/team-catalog.ts",
+    "server-managed/team-feed.ts",
+    "server-managed/team-reports.ts",
+    "server-managed/triage-response.ts",
+    "server-managed/uploads.ts",
+    "server-managed/workspace-shares.ts",
     "server-common/database-config.ts",
     "server-common/initialize.ts",
     "server-common/reap.ts",
@@ -111,11 +166,35 @@
     "report/src/utf8.js",
     "report/src/write-md-finding.js",
     "report/src/write-md.js",
+    "common/bundle-metadata.d.ts",
+    "common/bundle-metadata.js",
+    "common/bundle-reasons.d.ts",
+    "common/bundle-reasons.js",
+    "common/bundle-sources.d.ts",
+    "common/bundle-sources.js",
+    "common/bundle-stats.js",
+    "common/bundle-tabs.js",
+    "common/code-language.js",
+    "common/default-scan-models.ts",
+    "common/finding-id.js",
+    "common/github-pr.ts",
+    "common/managed/comments.ts",
+    "common/managed/permissions.ts",
+    "common/managed/report-content.ts",
+    "common/managed/report-filter.ts",
+    "common/managed/roles.ts",
+    "common/managed/routes.d.ts",
+    "common/managed/routes.js",
+    "common/managed/scan-models.ts",
+    "common/managed/triage.ts",
     "common/save-error-reason.ts",
     "common/server-info.ts",
     "common/scan-server.ts",
     "common/utf8.d.ts",
     "common/utf8.js",
+    "client/finding-link.js",
+    "client/linked-findings.d.ts",
+    "client/linked-findings.js",
     "out/brotli-fallback.js",
     "out/client-managed.js",
     "out/client-managed-import.js",

package/server-e2e/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Executable entry for the `triage-server` bin.
+// Executable entry for the `triage-e2e-server` bin.
 //
 // Node refuses to strip TypeScript types from files under node_modules
 // (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so once this package is

package/server-managed/activity.ts

@@ -0,0 +1,231 @@
+// Persistent workspace activity. Uploads are recorded in the same transaction
+// as their metadata; triage reuses its existing immutable trail, including
+// legacy entries. Never copy annotation bodies or credentials into this feed.
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import type { ManagedSql } from './sql.ts'
+
+export interface ActivityInput {
+  kind: 'access' | 'repository' | 'visibility' | 'delete'
+  actor: string
+  actorId?: string | null
+  action: string
+  repo?: string | null
+  reportId?: string | null
+  bundleId?: string | null
+  repoId?: number | null
+  repoDirectory?: string | null
+  report?: string | null
+}
+
+export interface ActivityContext {
+  finding: string
+  reportId: string
+  report: string
+  repo: string | null
+}
+
+export type ActivityEntry = {
+  id: string; kind: string; actor: string | null; action: string
+  repo: string | null; reportId: string | null; report: string | null
+  finding: string | null; at: number
+}
+
+export interface ActivityQuery {
+  page: number
+  limit: number
+  kind: string
+  query: string
+  repo?: string
+  actor?: string
+  // null = admin; [] = no accessible findings. Context is supplied by the
+  // server, never by the client. It also replaces potentially private context
+  // from an old report carrying the same globally shared finding.
+  contexts: ActivityContext[] | null
+  userId?: string
+}
+
+export interface ActivityFilters {
+  repos: string[]
+  users: { id: string; login: string; detail: string | null }[]
+}
+
+export interface ActivityStore {
+  recordActivity(entry: ActivityInput, at: number): Promise<void>
+  listActivityReports(userId: string): Promise<Omit<ActivityContext, 'finding'>[]>
+  listActivity(query: ActivityQuery): Promise<{ history: ActivityEntry[]; total: number; page: number; limit: number; filters: ActivityFilters }>
+}
+
+const triageFields = `'triage:' || e.seq AS id, 'triage' AS kind,
+  COALESCE(u.login, e.actor_login) AS actor, e.actor_id AS actorId,
+  CASE WHEN e.color IS NULL AND e.triage IS NULL AND e.comment IS NULL AND e.fix IS NULL AND e.flagged IS NULL
+    THEN 'cleared triage' ELSE 'updated triage' END AS action`
+const triage = `SELECT ${triageFields}, e.repo, e.report_id AS reportId, e.report, e.finding_id AS finding, e.at
+  FROM managed_finding_triage_event e LEFT JOIN managed_user u ON u.id = e.actor_id`
+const commentFields = `'comment:' || e.seq AS id, 'triage' AS kind,
+  COALESCE(u.login, e.actor_login) AS actor, e.actor_id AS actorId, e.action`
+const comments = `SELECT ${commentFields}, e.repo, e.report_id AS reportId, e.report, e.finding_id AS finding, e.at
+  FROM managed_finding_comment_event e LEFT JOIN managed_user u ON u.id = e.actor_id`
+const adminSource = `${triage} UNION ALL ${comments} UNION ALL
+  SELECT id, kind, actor, actor_id AS actorId, action, repo, report_id AS reportId, report, NULL AS finding, at FROM managed_activity`
+// Keep the finite set of accessible findings outside the indexed event
+// lookup. Scanning all events against json_each for every row is quadratic.
+const managerSource = `SELECT ${triageFields},
+  json_extract(c.value, '$.repo') AS repo, json_extract(c.value, '$.reportId') AS reportId,
+  json_extract(c.value, '$.report') AS report, e.finding_id AS finding, e.at
+  FROM json_each(:contexts) c
+  CROSS JOIN managed_finding_triage_event e ON e.finding_id = json_extract(c.value, '$.finding')
+  LEFT JOIN managed_user u ON u.id = e.actor_id
+  UNION ALL SELECT ${commentFields},
+    json_extract(c.value, '$.repo') AS repo, json_extract(c.value, '$.reportId') AS reportId,
+    json_extract(c.value, '$.report') AS report, e.finding_id AS finding, e.at
+  FROM json_each(:contexts) c
+  CROSS JOIN managed_finding_comment_event e ON e.finding_id = json_extract(c.value, '$.finding')
+  LEFT JOIN managed_user u ON u.id = e.actor_id
+  UNION ALL SELECT a.id, a.kind, a.actor, a.actor_id AS actorId,
+    CASE WHEN a.kind = 'repository' THEN 'changed a report repository assignment' ELSE a.action END AS action,
+    p.full_name AS repo, r.id AS reportId, r.filename AS report, NULL AS finding, a.at
+  FROM managed_activity a JOIN managed_report r ON r.id = a.report_id
+  LEFT JOIN managed_selected_repo p ON p.repo_id = r.repo_id
+  WHERE EXISTS (
+    SELECT 1 FROM managed_team_repo tr JOIN managed_team_user tu ON tu.team_id = tr.team_id
+    WHERE tu.user_id = :userId AND tr.repo_id = r.repo_id AND ${withinTeamPath('r.repo_directory')}
+  )
+  UNION ALL SELECT a.id, a.kind, a.actor, a.actor_id AS actorId,
+    CASE WHEN a.kind = 'repository' THEN 'changed a bundle repository assignment' ELSE a.action END AS action,
+    p.full_name AS repo, NULL AS reportId, b.filename AS report, NULL AS finding, a.at
+  FROM managed_activity a JOIN managed_bundle b ON b.id = a.bundle_id
+  LEFT JOIN managed_selected_repo p ON p.repo_id = b.repo_id
+  WHERE a.report_id IS NULL AND EXISTS (
+    SELECT 1 FROM managed_team_repo tr JOIN managed_team_user tu ON tu.team_id = tr.team_id
+    WHERE tu.user_id = :userId AND tr.repo_id = b.repo_id AND ${withinTeamPath('b.repo_directory')}
+  )
+  UNION ALL SELECT a.id, a.kind, a.actor, a.actor_id AS actorId, a.action, a.repo, a.report_id AS reportId,
+    a.report, NULL AS finding, a.at FROM managed_activity a
+  WHERE a.kind = 'delete' AND (a.report_id IS NOT NULL OR a.bundle_id IS NOT NULL)
+    AND NOT EXISTS (SELECT 1 FROM managed_report WHERE id = a.report_id)
+    AND NOT EXISTS (SELECT 1 FROM managed_bundle WHERE id = a.bundle_id)
+    AND EXISTS (SELECT 1 FROM managed_team_repo tr JOIN managed_team_user tu ON tu.team_id = tr.team_id
+      WHERE tu.user_id = :userId AND tr.repo_id = a.repo_id
+      AND ${withinTeamPath('a.repo_directory')})`
+
+export const ACTIVITY_SCHEMA = `
+    CREATE TABLE IF NOT EXISTS managed_activity (
+      id TEXT PRIMARY KEY, kind TEXT NOT NULL, actor TEXT, action TEXT NOT NULL,
+      repo TEXT, report_id TEXT, report TEXT, at INTEGER NOT NULL,
+      bundle_id TEXT, repo_id INTEGER, repo_directory TEXT, actor_id TEXT
+    ) STRICT;
+    CREATE INDEX IF NOT EXISTS managed_activity_at_idx ON managed_activity(at, id);
+    CREATE INDEX IF NOT EXISTS finding_triage_event_at_idx ON managed_finding_triage_event(at, seq);
+`
+
+export function initActivityMethods(db: DatabaseSync): void {
+  db.exec(ACTIVITY_SCHEMA)
+  migrateActivityScope(db)
+  db.exec('CREATE INDEX IF NOT EXISTS managed_activity_actor_at_idx ON managed_activity(actor_id, at)')
+  // Stable upload IDs make backfill idempotent, including after restarts.
+  // Snapshots deliberately have no cascading FKs: deletion is itself activity.
+  for (const type of ['report', 'bundle']) {
+    const columns = `id, kind, actor, action, repo, report_id, report, at, bundle_id, actor_id`
+    const values = (alias: string) => `'${type}-upload:' || ${alias}.id, 'upload',
+      COALESCE(${alias}.uploaded_by_login, (SELECT login FROM managed_user WHERE id = ${alias}.uploaded_by)), 'uploaded a ${type}',
+      (SELECT full_name FROM managed_selected_repo WHERE repo_id = ${alias}.repo_id),
+      ${type === 'report' ? `${alias}.id` : 'NULL'}, ${alias}.filename, ${alias}.uploaded_at,
+      ${type === 'bundle' ? `${alias}.id` : 'NULL'}, ${alias}.uploaded_by`
+    db.exec(`
+      CREATE TRIGGER IF NOT EXISTS managed_${type}_activity AFTER INSERT ON managed_${type}
+      BEGIN INSERT INTO managed_activity (${columns}) SELECT ${values('NEW')}; END;
+      INSERT OR IGNORE INTO managed_activity (${columns}) SELECT ${values('source')} FROM managed_${type} source;
+    `)
+  }
+}
+
+export function activityMethods(db: ManagedSql): ActivityStore {
+  const insert = db.prepare(`INSERT INTO managed_activity (id, kind, actor, action, repo, report_id, report, at, bundle_id, repo_id, repo_directory, actor_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+  const admin = activityStatements(db, adminSource)
+  const manager = activityStatements(db, managerSource)
+  const reports = db.prepare(`SELECT r.id AS reportId, r.filename AS report, p.full_name AS repo
+    FROM managed_report r JOIN managed_selected_repo p ON p.repo_id = r.repo_id
+    WHERE EXISTS (SELECT 1 FROM managed_team_repo tr JOIN managed_team_user tu ON tu.team_id = tr.team_id
+      WHERE tu.user_id = ? AND tr.repo_id = r.repo_id AND ${withinTeamPath('r.repo_directory')})
+    ORDER BY r.uploaded_at DESC, r.id`)
+  return {
+    async recordActivity(entry, at) {
+      await insert.run(randomUUID(), entry.kind, entry.actor, entry.action, entry.repo ?? null, entry.reportId ?? null, entry.report ?? null, at,
+        entry.bundleId ?? null, entry.repoId ?? null, entry.repoDirectory ?? null, entry.actorId ?? null)
+    },
+    async listActivityReports(userId) {
+      return (await reports.all(userId)) as Omit<ActivityContext, 'finding'>[]
+    },
+    async listActivity({ page, limit, kind, query, repo = '', actor = '', contexts, userId }) {
+      const stmts = contexts == null ? admin : manager
+      const scope = contexts == null ? {} : { contexts: JSON.stringify(contexts), userId: userId ?? '' }
+      const params = { ...scope, kind, query, repo, actor }
+      const { total } = (await stmts.count.get(params)) as { total: number }
+      const currentPage = Math.min(page, Math.max(1, Math.ceil(total / limit)))
+      const history = (await stmts.rows.all({ ...params, limit, offset: (currentPage - 1) * limit })) as ActivityEntry[]
+      const filters: ActivityFilters = {
+        repos: ((await stmts.repos.all(scope)) as { repo: string }[]).map(row => row.repo),
+        users: ((await stmts.users.all(scope)) as ActivityFilters['users']).map(row => ({ id: row.id, login: row.login, detail: row.detail })),
+      }
+      return { history, total, page: currentPage, limit, filters }
+    },
+  }
+}
+
+// Both rows and selector choices come from the authorized source. Keep legacy
+// login-only actors separate: a historical login is not proof of user identity.
+function activityStatements(db: ManagedSql, source: string) {
+  const activity = `WITH events AS (${source}), activity AS (
+    SELECT events.*, COALESCE('user:' || actorId, 'legacy:' || actor) AS actorKey FROM events
+  )`
+  const filtered = `${activity} SELECT id, kind, actor, action, repo, reportId, report, finding, at FROM activity
+    WHERE (:kind = 'all' OR kind = :kind)
+    AND (:repo = '' OR repo = :repo) AND (:actor = '' OR actorKey = :actor)
+    AND (:query = '' OR instr(lower(coalesce(actor, '') || ' ' || action || ' ' ||
+      coalesce(repo, '') || ' ' || coalesce(report, '') || ' ' || coalesce(finding, '')), lower(:query)) > 0)`
+  return {
+    count: db.prepare(`SELECT count(*) AS total FROM (${filtered}) AS filtered`),
+    rows: db.prepare(`${filtered} ORDER BY at DESC,
+      CASE WHEN kind = 'triage' THEN CAST(substr(id, instr(id, ':') + 1) AS INTEGER) ELSE 0 END DESC,
+      id DESC LIMIT :limit OFFSET :offset`),
+    repos: db.prepare(`${activity} SELECT DISTINCT repo FROM activity WHERE repo IS NOT NULL AND repo <> '' ORDER BY repo`),
+    users: db.prepare(`${activity} SELECT a.actorKey AS id, COALESCE(u.login, a.actor, a.actorId) AS login,
+      CASE WHEN a.actorId IS NULL THEN 'Legacy actor' ELSE NULL END AS detail FROM (
+        SELECT actorKey, actorId, actor, ROW_NUMBER() OVER (PARTITION BY actorKey ORDER BY at DESC, id DESC) AS position
+        FROM activity WHERE actorKey IS NOT NULL AND actorKey <> 'legacy:'
+      ) a LEFT JOIN managed_user u ON u.id = a.actorId WHERE a.position = 1 ORDER BY login, a.actorKey`),
+  }
+}
+
+// Literal path comparison preserves separators, case and SQL wildcard chars.
+function withinTeamPath(path: string): string {
+  return `(tr.path IS NULL OR tr.path = '' OR ${path} = tr.path OR substr(${path}, 1, length(tr.path) + 1) = tr.path || '/')`
+}
+
+function migrateActivityScope(db: DatabaseSync): void {
+  const columns = new Set((db.prepare('PRAGMA table_info(managed_activity)').all() as { name: string }[]).map(column => column.name))
+  const missing = [['bundle_id', 'TEXT'], ['repo_id', 'INTEGER'], ['repo_directory', 'TEXT'], ['actor_id', 'TEXT']].filter(([name]) => !columns.has(name!))
+  if (missing.length === 0) return
+  db.exec('BEGIN')
+  try {
+    for (const [name, type] of missing) db.exec(`ALTER TABLE managed_activity ADD COLUMN ${name} ${type}`)
+    if (!columns.has('bundle_id') || !columns.has('actor_id')) {
+      db.exec('DROP TRIGGER IF EXISTS managed_report_activity; DROP TRIGGER IF EXISTS managed_bundle_activity;')
+    }
+    if (!columns.has('bundle_id')) db.exec("UPDATE managed_activity SET bundle_id = substr(id, 15) WHERE id LIKE 'bundle-upload:%'")
+    if (!columns.has('actor_id')) {
+      // Existing upload targets retain a reliable uploader identity. Do not
+      // guess identities from historical logins: names can change or be reused.
+      for (const type of ['report', 'bundle']) {
+        db.exec(`UPDATE managed_activity SET actor_id = (
+          SELECT uploaded_by FROM managed_${type} WHERE id = substr(managed_activity.id, 15)
+        ) WHERE id LIKE '${type}-upload:%'`)
+      }
+    }
+    // Legacy deletions/assignments without a durable target/scope remain
+    // admin-only; neither filenames nor repository names authorize access.
+    db.exec('COMMIT')
+  } catch (err) { db.exec('ROLLBACK'); throw err }
+}

package/server-managed/avatar-store.ts

@@ -0,0 +1,51 @@
+// Avatar cache for the managed server. The user's GitHub avatar is fetched once
+// at login (see github-oauth.ts) and served same-origin from GET
+// /api/auth/avatar — the app's CSP is `img-src 'self'`, so the GitHub-hosted
+// original can't be loaded by the page directly.
+//
+// The disk backend uses a dir beside SQLite; blob-vercel.ts implements the
+// same AvatarStore interface for remote storage. Keyed by the user's opaque `id`.
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { Buffer } from 'node:buffer'
+
+export interface CachedAvatar {
+  contentType: string
+  bytes: Buffer
+}
+
+export interface AvatarStore {
+  put(id: string, contentType: string, bytes: Buffer): Promise<void>
+  get(id: string): Promise<CachedAvatar | null>
+}
+
+// The user id is a v4 uuid (crypto.randomUUID) — lowercase hex + dashes, no
+// path separators. Validated anyway so a crafted id can't escape the store dir.
+const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u
+
+export function createDiskAvatarStore(dir: string): AvatarStore {
+  function pathFor(id: string): string {
+    if (!ID_RE.test(id)) throw new Error('invalid avatar id')
+    return join(dir, id)
+  }
+  return {
+    async put(id, contentType, bytes) {
+      const p = pathFor(id)
+      await mkdir(dirname(p), { recursive: true })
+      // Bytes first, then the content-type sidecar — a crash between the two
+      // leaves a typeless blob that `get` treats as missing (re-fetched next
+      // login) rather than serving with a wrong/absent type.
+      await writeFile(p, bytes)
+      await writeFile(`${p}.type`, contentType, 'utf8')
+    },
+    async get(id) {
+      try {
+        const p = pathFor(id)
+        const [bytes, contentType] = await Promise.all([readFile(p), readFile(`${p}.type`, 'utf8')])
+        return { bytes, contentType: contentType.trim() || 'application/octet-stream' }
+      } catch {
+        return null
+      }
+    },
+  }
+}

package/server-managed/blob-store.ts

@@ -0,0 +1,66 @@
+// Disk byte-store for the managed server's stored blobs (uploaded reports and
+// bundles). Unlike the e2e relay (which only ever holds opaque client-encrypted
+// blobs), a managed server is TRUSTED and stores the bytes in the clear so it
+// can operate on them — the metadata + attribution live in the DB, the bytes
+// live here, keyed by the blob's opaque `id`.
+//
+// The disk backend uses a dir beside SQLite (data/reports/<uuid> or
+// data/bundles/<uuid>); blob-vercel.ts implements the same interface remotely. Bytes only — the
+// content-type / filename / integrity ride the DB row, so there's no sidecar.
+import { mkdir, open, readFile, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import type { Buffer } from 'node:buffer'
+import type { Readable } from 'node:stream'
+
+export interface OpenedBlob {
+  // Remote streams may omit their size; callers then omit Content-Length.
+  size: number | null
+  stream: Readable
+}
+
+export interface BlobStore {
+  put(id: string, bytes: Buffer): Promise<void>
+  get(id: string): Promise<Buffer | null>
+  open(id: string): Promise<OpenedBlob | null>
+  delete(id: string): Promise<void>
+}
+
+// The blob id is a v4 uuid (crypto.randomUUID) — lowercase hex + dashes, no
+// path separators. Validated anyway so a crafted id can't escape the store dir.
+const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u
+
+export function createDiskBlobStore(dir: string, suffix = ''): BlobStore {
+  function pathFor(id: string): string {
+    if (!ID_RE.test(id)) throw new Error('invalid blob id')
+    return join(dir, id + suffix)
+  }
+  return {
+    async put(id, bytes) {
+      const p = pathFor(id)
+      await mkdir(dirname(p), { recursive: true })
+      await writeFile(p, bytes)
+    },
+    async get(id) {
+      try {
+        return await readFile(pathFor(id))
+      } catch {
+        return null
+      }
+    },
+    async open(id) {
+      let file
+      try { file = await open(pathFor(id), 'r') }
+      catch (err) { if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null; throw err }
+      try {
+        const info = await file.stat()
+        // Remain paused until piped. HEAD can close without reading the body.
+        return { size: info.size, stream: file.createReadStream() }
+      } catch (err) { await file.close(); throw err }
+    },
+    async delete(id) {
+      // `force` so a missing file (already gone) is a no-op, not a throw — the
+      // metadata row is the source of truth for whether a blob "exists".
+      await rm(pathFor(id), { force: true })
+    },
+  }
+}

package/server-managed/blob-vercel.ts

@@ -0,0 +1,125 @@
+import { Buffer } from 'node:buffer'
+import { Readable } from 'node:stream'
+import { type VercelBlobSdk, isNotFound, loadVercelBlobSdk } from '../server-common/vercel-blob.ts'
+import type { AvatarStore } from './avatar-store.ts'
+import type { BlobStore } from './blob-store.ts'
+import { type CacheStorage, validateCacheKey } from './cache-storage.ts'
+import type { BundleCacheStorage } from './bundle-cache.ts'
+import { createBundleStore } from './bundle-store.ts'
+
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u
+function validate(id: string): string {
+  if (!ID.test(id)) throw new Error('Invalid managed blob id')
+  return id
+}
+
+type ListedBlob = Awaited<ReturnType<VercelBlobSdk['list']>>['blobs'][number]
+
+async function deletePrefix(blobs: VercelBlobSdk, token: string, prefix: string, remove: (path: string) => Promise<void>, matches = (_blob: ListedBlob) => true): Promise<void> {
+  const cursors = new Set<string>(), paths = new Set<string>()
+  let cursor: string | undefined
+  // Finish listing before deleting so pagination cannot skip objects as the
+  // listed set shrinks. Callers supply a trailing slash to isolate a namespace.
+  do {
+    const page = await blobs.list({ token, prefix, ...(cursor ? { cursor } : {}) })
+    for (const blob of page.blobs) if (blob.pathname.startsWith(prefix) && matches(blob)) paths.add(blob.pathname)
+    if (!page.hasMore) break
+    if (!page.cursor || cursors.has(page.cursor)) throw new Error('Invalid blob pagination')
+    cursor = page.cursor
+    cursors.add(cursor)
+  } while (cursor)
+  for (const path of paths) await remove(path)
+}
+
+function createBlobAvatarStore(avatarBlobs: BlobStore): AvatarStore {
+  return {
+    put(id, contentType, bytes) {
+      const type = contentType.split(';', 1)[0]!.trim()
+      if (!/^image\/[a-z0-9.+-]+$/iu.test(type)) throw new Error('Invalid avatar type')
+      return avatarBlobs.put(id, Buffer.concat([Buffer.from(`${type}\n`), bytes]))
+    },
+    async get(id) {
+      const bytes = await avatarBlobs.get(id)
+      if (!bytes) return null
+      const split = bytes.indexOf(10)
+      if (split < 0 || split > 100) throw new Error('Invalid cached avatar')
+      return { contentType: bytes.subarray(0, split).toString(), bytes: bytes.subarray(split + 1) }
+    },
+  }
+}
+
+export async function openManagedVercelStorage(token: string, sdk?: VercelBlobSdk) {
+  const blobs = sdk ?? await loadVercelBlobSdk()
+  const options = { token, access: 'private' as const, useCache: false }
+  async function put(path: string, bytes: Buffer) {
+    await blobs.put(path, bytes, { token, access: 'private', addRandomSuffix: false,
+      allowOverwrite: true, contentType: 'application/octet-stream', cacheControlMaxAge: 60 })
+  }
+  async function open(path: string) {
+    try {
+      const result = await blobs.get(path, options)
+      if (!result) return null
+      if (result.statusCode !== 200 || !result.stream) throw new Error('Unexpected blob response')
+      // Private SDK GETs may report zero for a nonempty body. Stream without
+      // Content-Length in that case so HTTP clients do not truncate the body.
+      const size = result.blob.size === 0 ? null : result.blob.size
+      return { size, stream: Readable.fromWeb(result.stream as Parameters<typeof Readable.fromWeb>[0]) }
+    } catch (err) { if (isNotFound(err)) return null; throw err }
+  }
+  async function get(path: string) {
+    const result = await open(path)
+    if (!result) return null
+    const parts: Buffer[] = []
+    for await (const chunk of result.stream) parts.push(Buffer.from(chunk))
+    return Buffer.concat(parts)
+  }
+  async function remove(path: string) {
+    try { await blobs.del(path, { token }) } catch (err) { if (!isNotFound(err)) throw err }
+  }
+  function store(name: string, suffix = ''): BlobStore {
+    const path = (id: string) => `.managed/${name}/${validate(id)}${suffix}`
+    return {
+      async put(id, bytes) { await put(path(id), bytes) },
+      async get(id) { return await get(path(id)) },
+      open: id => open(path(id)),
+      async delete(id) { await remove(path(id)) },
+    }
+  }
+  const avatarStore = createBlobAvatarStore(store('avatars'))
+  const cachePath = (id: string, file: string) => `.managed/cache/bundles/${validate(id)}/${file}`
+  const cacheStorage: BundleCacheStorage = {
+    async exists(id, file) {
+      try { await blobs.head(cachePath(id, file), { token }); return true }
+      catch (err) { if (isNotFound(err)) return false; throw err }
+    },
+    put: (id, file, bytes) => put(cachePath(id, file), bytes),
+    async open(id, file) {
+      const result = await open(cachePath(id, file))
+      if (!result) throw new Error('Bundle cache unavailable')
+      return result
+    },
+    delete: id => deletePrefix(blobs, token, cachePath(id, ''), remove),
+  }
+  // Staging uploads are never published. An interrupted browser leaves only
+  // parts here; the authenticated cron removes them after a full day.
+  function reapUploads(now = Date.now()) {
+    return deletePrefix(blobs, token, '.managed/uploads/', remove,
+      blob => new Date(blob.uploadedAt ?? now).getTime() < now - 86_400_000)
+  }
+  const sourcesPath = (key: string) => `.managed/cache/report-sources/${validateCacheKey(key)}`
+  const reportSourcesStorage: CacheStorage = {
+    async exists(key) {
+      try { await blobs.head(sourcesPath(key), { token }); return true }
+      catch (err) { if (isNotFound(err)) return false; throw err }
+    },
+    put: (key, bytes) => put(sourcesPath(key), bytes),
+    async open(key) {
+      const result = await open(sourcesPath(key))
+      if (!result) throw new Error('Report sources cache unavailable')
+      return result
+    },
+    delete: prefix => deletePrefix(blobs, token, `${sourcesPath(prefix)}/`, remove),
+  }
+  const bundleStore = createBundleStore(store('bundles'), store('bundles', '.map.br'))
+  return { reportStore: store('reports'), bundleStore, uploadStore: store('uploads'), avatarStore, cacheStorage, reportSourcesStorage, reapUploads }
+}

package/server-managed/brotli.ts

@@ -0,0 +1,10 @@
+import { brotliCompress, constants } from 'node:zlib'
+import { promisify } from 'node:util'
+import type { Buffer } from 'node:buffer'
+
+const compress = promisify(brotliCompress)
+
+// Quality 4 avoids Brotli's expensive default (11) for uploads and cold caches.
+export function encodeBrotli(bytes: Uint8Array): Promise<Buffer> {
+  return compress(bytes, { params: { [constants.BROTLI_PARAM_QUALITY]: 4 } })
+}