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

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

package/server-managed/bundle-cache.ts

@@ -0,0 +1,185 @@
+// Metadata is cached as Brotli. Contents use the stored Brotli bytes directly:
+// unchanged Stasis uploads or sourcemaps compressed once at upload.
+import { Buffer } from 'node:buffer'
+import { mkdir, open, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { brotliDecompress } from 'node:zlib'
+import { promisify } from 'node:util'
+import { BUNDLE_METADATA_VERSION, type BundleDetails, createBundleMetadata, createBundleSummary, parseBundleContents } from '../common/bundle-metadata.js'
+import { bundleReasons } from '../common/bundle-reasons.js'
+import { bundlePackageVersions } from '../common/bundle-sources.js'
+import { decodeUtf8 } from '../common/utf8.js'
+import type { OpenedBlob } from './blob-store.ts'
+import type { BundleStore } from './bundle-store.ts'
+import { encodeBrotli } from './brotli.ts'
+import type { ManagedBundle, ManagedDb } from './db.ts'
+import { SUMMARY_FILENAME, createBundleSummaryCache } from './bundle-summary-cache.ts'
+
+const decompress = promisify(brotliDecompress)
+const MAX_DECODED_BYTES = 512 * 1024 * 1024
+export const MAX_PACKAGE_INVENTORY_BYTES = 1024 * 1024
+export type BundleCachePart = 'metadata' | 'contents'
+export type BundleCacheRecord = Pick<ManagedBundle, 'id' | 'integrity' | 'filename' | 'kind' | 'byteSize'>
+export interface BundleSummary { files: number; codeFiles: number; lines: number }
+
+export async function readBundleDetails(record: BundleCacheRecord, store: BundleStore) {
+  const bytes = await store.get(record.id, record.kind)
+  if (!bytes) return null
+  const decoded = record.kind === 'stasis' || record.kind === 'sourcemap' ? await decompress(bytes, { maxOutputLength: MAX_DECODED_BYTES }) : bytes
+  if (decoded.length > MAX_DECODED_BYTES) throw new Error('Decoded bundle too large')
+  return parseBundleContents(decodeUtf8(decoded), { integrity: record.integrity, kind: record.kind, size: record.byteSize })
+}
+
+export interface BundleCacheStorage {
+  exists(id: string, file: string): Promise<boolean>
+  put(id: string, file: string, bytes: Buffer): Promise<void>
+  open(id: string, file: string): Promise<OpenedBlob>
+  // Remove all cached versions for this bundle, including legacy derivatives.
+  delete(id: string): Promise<void>
+}
+
+const filename = `v${BUNDLE_METADATA_VERSION}-metadata.json.br`
+const packagesFilename = 'v2-package-versions.json'
+
+// All scopes share one bounded derivative. Never decode full bundle metadata
+// on advisory requests, including when selecting a reason. Persist null when
+// the combined inventory exceeds the budget, without disabling metadata.
+function encodePackageInventory(details: BundleDetails): Buffer {
+  const parts: string[] = []
+  let size = 0
+  function append(part: string) {
+    size += Buffer.byteLength(part)
+    if (size > MAX_PACKAGE_INVENTORY_BYTES) return false
+    parts.push(part)
+    return true
+  }
+  function inventory(paths: Set<string> | null) {
+    if (!append('{')) return false
+    let first = true
+    for (const [name, versions] of bundlePackageVersions(details, paths)) {
+      if (!append(`${first ? '' : ','}${JSON.stringify(name)}:${JSON.stringify([...versions].toSorted())}`)) return false
+      first = false
+    }
+    return append('}')
+  }
+  append('{"all":')
+  if (!inventory(null) || !append(',"reasons":{')) return Buffer.from('null')
+  let first = true
+  for (const [reason, paths] of bundleReasons(details)) {
+    if (!append(`${first ? '' : ','}${JSON.stringify(reason)}:`) || !inventory(paths)) return Buffer.from('null')
+    first = false
+  }
+  if (!append('}}')) return Buffer.from('null')
+  return Buffer.from(parts.join(''))
+}
+
+async function build(record: BundleCacheRecord, storage: BundleCacheStorage, db: ManagedDb, store: BundleStore) {
+  const details = await readBundleDetails(record, store)
+  if (!details) throw new Error('Bundle bytes unavailable')
+  const metadata = { ...await createBundleMetadata(details), id: record.id, filename: record.filename }
+  const body = await encodeBrotli(Buffer.from(JSON.stringify(metadata)))
+  if (!(await db.getBundle(record.id))) throw new Error('Bundle deleted')
+  await storage.put(record.id, filename, body)
+  if (record.kind === 'stasis') await storage.put(record.id, packagesFilename, encodePackageInventory(details))
+  const summary = createBundleSummary(details, metadata)
+  await storage.put(record.id, SUMMARY_FILENAME, Buffer.from(JSON.stringify(summary)))
+  // A different instance may have deleted the row while these writes ran.
+  // Reconcile after publishing so its cleanup cannot be undone by us.
+  if (!(await db.getBundle(record.id))) {
+    await storage.delete(record.id)
+    throw new Error('Bundle deleted')
+  }
+  return summary
+}
+
+export function createBundleCache(storage: BundleCacheStorage, db: ManagedDb, store: BundleStore) {
+  const pending = new Map<string, Promise<void>>()
+  // The database deduplicates by integrity, so each hash has one persistent
+  // bundle/cache directory, shared across teams and repeated uploads.
+  const summaries = createBundleSummaryCache(storage, async record => {
+    const details = await readBundleDetails(record, store)
+    if (!details) throw new Error('Bundle bytes unavailable')
+    return createBundleSummary(details)
+  }, id => db.getBundle(id))
+  let queue = Promise.resolve()
+  async function ensure(record: BundleCacheRecord): Promise<void> {
+    const existing = pending.get(record.id)
+    if (existing) return existing
+    const job = (async () => {
+      if (await storage.exists(record.id, filename) && (record.kind !== 'stasis' || await storage.exists(record.id, packagesFilename))) return
+      const work = queue.then(async () => summaries.remember(record, await build(record, storage, db, store)))
+      queue = work.catch(() => {})
+      await work
+    })()
+    pending.set(record.id, job)
+    try { await job } finally { if (pending.get(record.id) === job) pending.delete(record.id) }
+  }
+  return {
+    prebuild: ensure,
+    summary: summaries.summary,
+    summaryStatus: summaries.summaryStatus,
+    backfillSummaries: summaries.backfill,
+    async open(record: ManagedBundle, part: BundleCachePart) {
+      if (part === 'contents') {
+        if (record.kind !== 'stasis' && record.kind !== 'sourcemap') throw new Error('Unsupported bundle')
+        const stored = await store.open(record.id, record.kind)
+        if (!stored) throw new Error('Bundle bytes unavailable')
+        return stored
+      }
+      await ensure(record)
+      return storage.open(record.id, filename)
+    },
+    async packageVersions(record: ManagedBundle, reason = ''): Promise<Record<string, string[]> | null | undefined> {
+      if (record.kind !== 'stasis') return {}
+      await ensure(record)
+      const cached = await storage.open(record.id, packagesFilename)
+      try {
+        if (cached.size != null && cached.size > MAX_PACKAGE_INVENTORY_BYTES) return null
+        const chunks: Buffer[] = []
+        let size = 0
+        for await (const chunk of cached.stream) {
+          size += chunk.length
+          if (size > MAX_PACKAGE_INVENTORY_BYTES) return null
+          chunks.push(Buffer.from(chunk))
+        }
+        const inventory = JSON.parse(decodeUtf8(Buffer.concat(chunks)))
+        if (inventory === null) return null
+        return reason ? (Object.hasOwn(inventory.reasons, reason) ? inventory.reasons[reason] : undefined) : inventory.all
+      } finally { cached.stream.destroy() }
+    },
+    async delete(id: string) {
+      // Call after deleting the row. Waiting prevents an in-flight builder
+      // from recreating its files after deletion has completed.
+      await pending.get(id)?.catch(() => {})
+      await summaries.forget(id)
+      await storage.delete(id)
+    },
+  }
+}
+export type BundleCache = ReturnType<typeof createBundleCache>
+
+export function createDiskBundleCache(dir: string, db: ManagedDb, store: BundleStore): BundleCache {
+  function directory(id: string) {
+    if (!/^[a-f\d-]{36}$/iu.test(id)) throw new Error('Invalid bundle id')
+    return join(dir, id)
+  }
+  return createBundleCache({
+    async exists(id, file) {
+      try { await stat(join(directory(id), file)); return true }
+      catch (err) { if ((err as NodeJS.ErrnoException).code === 'ENOENT') return false; throw err }
+    },
+    async put(id, file, bytes) {
+      await mkdir(directory(id), { recursive: true })
+      const target = join(directory(id), file), temp = `${target}.${randomUUID()}.tmp`
+      try { await writeFile(temp, bytes); await rename(temp, target) }
+      finally { await rm(temp, { force: true }) }
+    },
+    async open(id, name) {
+      const file = await open(join(directory(id), name), 'r')
+      try { return { size: (await file.stat()).size, stream: file.createReadStream() } }
+      catch (err) { await file.close(); throw err }
+    },
+    async delete(id) { await rm(directory(id), { recursive: true, force: true }) },
+  }, db, store)
+}