@preventive/triage 1.0.0-alpha.3 → 1.0.0-alpha.31

package/server-managed/object-storage.ts

@@ -0,0 +1,71 @@
+import type { Buffer } from 'node:buffer'
+import type { Readable } from 'node:stream'
+import type { OpenedBlob } from './blob-store.ts'
+import { validateCacheKey } from './cache-storage.ts'
+
+export const ENCRYPTED_CACHE_PREFIX = 'cache-encrypted-v1/'
+const STORAGE_PREFIXES = ['reports/', 'bundles/', 'avatars/', 'uploads/', 'cache/', ENCRYPTED_CACHE_PREFIX]
+export interface RawObject extends OpenedBlob { version: string; modifiedAt: number }
+type ObjectMetadata = Omit<RawObject, 'stream'>
+interface ListedObject { key: string; modifiedAt: number }
+export interface ObjectPage { objects: ListedObject[]; cursor: string | null }
+export interface RawObjectStorage {
+  open(key: string, signal?: AbortSignal): Promise<RawObject | null>
+  head(key: string, signal?: AbortSignal): Promise<ObjectMetadata | null>
+  prune?(prefix: string, signal?: AbortSignal): Promise<void>
+  // Persist an observed disk replacement before its SQL migration checkpoint.
+  sync?(key: string, signal?: AbortSignal): Promise<void>
+  // A plaintext size hint selects multipart uploads without buffering streams.
+  put(key: string, bytes: Buffer | Readable, signal?: AbortSignal, expected?: string, sizeHint?: number): Promise<boolean>
+  // Return false if the original version changed; do not delete its replacement.
+  delete(key: string, version?: string, signal?: AbortSignal): Promise<boolean>
+  list(prefix: string, cursor: string | null, limit: number, signal?: AbortSignal): Promise<ObjectPage>
+}
+export interface ObjectStorage {
+  open(key: string): Promise<OpenedBlob | null>
+  get(key: string): Promise<Buffer | null>
+  exists(key: string): Promise<boolean>
+  put(key: string, bytes: Buffer): Promise<string | null>
+  delete(key: string): Promise<void>
+  deletePrefix(prefix: string): Promise<void>
+}
+
+export function isBlobId(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(value)
+}
+
+export function objectPath(key: string): string {
+  validateCacheKey(key)
+  if (!STORAGE_PREFIXES.some(prefix => key.startsWith(prefix))) throw new Error('Invalid managed storage namespace')
+  return key
+}
+
+// Hash verification and migration may consume a stream before it can be used.
+// Reopen only the same object version, closing any concurrent replacement.
+export async function openObjectVersion(raw: RawObjectStorage, key: string, version: string, signal?: AbortSignal): Promise<RawObject | null> {
+  const current = await raw.open(key, signal)
+  if (current?.version === version) return current
+  current?.stream.destroy()
+  return null
+}
+
+export async function deleteObjects(raw: RawObjectStorage, prefix: string, signal: AbortSignal, before?: number): Promise<number> {
+  const eligible = (modifiedAt: number) => before === undefined || modifiedAt < before
+  // Finish listing before deleting: provider cursors may be offset-based.
+  const cursors = new Set<string>(), keys = new Set<string>()
+  let cursor: string | null = null
+  do {
+    const page = await raw.list(prefix, cursor, 100, signal)
+    for (const object of page.objects) if (eligible(object.modifiedAt)) keys.add(object.key)
+    cursor = page.cursor
+    if (cursor !== null && cursors.has(cursor)) throw new Error('Invalid blob pagination')
+    if (cursor !== null) cursors.add(cursor)
+  } while (cursor !== null)
+  let removed = 0
+  for (const key of keys) {
+    const stored = await raw.head(key, signal)
+    // Ignore stale listings and preserve concurrent replacements.
+    if (stored && eligible(stored.modifiedAt) && await raw.delete(key, stored.version, signal)) removed++
+  }
+  return removed
+}

package/server-managed/package-entry-points.ts

@@ -0,0 +1,51 @@
+import { Buffer } from 'node:buffer'
+import { normalizeTeamPath } from './repo-path.ts'
+
+export const MAX_PACKAGE_BYTES = 256 * 1024
+const MAX_ENTRY_POINTS = 100
+
+// Declared paths, not a Node resolver: never guess defaults, expand export
+// patterns, or execute package code. Keep every suggestion in its package.
+export function packageEntryPoints(manifest: unknown, directory: string): string[] {
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) return []
+  const pkg = manifest as { main?: unknown; exports?: unknown; bin?: unknown }
+  const paths = new Set<string>()
+  const add = (value: unknown) => {
+    if (typeof value !== 'string' || value.startsWith('/') || value.endsWith('/') || /[*?]|^[a-z][a-z\d+.-]*:/iu.test(value)) return
+    const normalized = normalizeTeamPath(value)
+    if (!normalized.ok || !normalized.path || normalized.path === 'package.json') return
+    const path = directory ? `${directory}/${normalized.path}` : normalized.path
+    if (path.length <= 500 && paths.size < MAX_ENTRY_POINTS) paths.add(path)
+  }
+  add(pkg.main)
+  const pending = [pkg.exports]
+  for (let visited = 0; pending.length > 0 && visited < 4096; visited++) {
+    const value = pending.pop()
+    if (typeof value === 'string') { if (value.startsWith('./')) add(value); continue }
+    if (Array.isArray(value)) pending.push(...value.slice(0, 4096 - visited).toReversed())
+    else if (value && typeof value === 'object') {
+      const entries = Object.entries(value).filter(([key]) => key !== 'types' && !key.startsWith('types@'))
+      pending.push(...entries.slice(0, 4096 - visited).toReversed().map(([, target]) => target))
+    }
+  }
+  if (typeof pkg.bin === 'string') add(pkg.bin)
+  else if (pkg.bin && typeof pkg.bin === 'object' && !Array.isArray(pkg.bin)) Object.values(pkg.bin).forEach(add)
+  return [...paths]
+}
+
+// Use the immutable blob from the authorized listing, never download_url or a
+// resolved symlink target. Malformed or oversized manifests are optional.
+export async function readPackageEntryPoints(sha: string, directory: string, read: (suffix: string) => Promise<unknown>): Promise<string[]> {
+  try {
+    const blob = await read(`/git/blobs/${sha}`) as { encoding?: unknown; content?: unknown; size?: unknown }
+    if (blob?.encoding !== 'base64' || typeof blob.content !== 'string' || typeof blob.size !== 'number'
+      || blob.size < 0 || blob.size > MAX_PACKAGE_BYTES || blob.content.length > MAX_PACKAGE_BYTES * 2) return []
+    const bytes = Buffer.from(blob.content, 'base64')
+    if (bytes.length !== blob.size || bytes.length > MAX_PACKAGE_BYTES) return []
+    return packageEntryPoints(JSON.parse(bytes.toString('utf8')), directory)
+  } catch {
+    // Suggestions must not prevent browsing. The handler still rechecks
+    // GitHub and managed access after this optional upstream read.
+    return []
+  }
+}

package/server-managed/public-workspace.ts

@@ -0,0 +1,146 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { pipeline } from 'node:stream/promises'
+import { Buffer } from 'node:buffer'
+import type { ManagedHttpDeps } from './http.ts'
+import type { ManagedBundle } from './db.ts'
+import type { OpenedBlob } from './blob-store.ts'
+import type { WorkspaceShareSnapshot } from './workspace-shares.ts'
+import { sendJson, writeResponse } from './http-response.ts'
+import { hashToken } from './crypto.ts'
+import { TeamReportsError, loadTeamAnnotations, loadTeamReportsResponse, teamReportVisibility } from './team-reports.ts'
+import { triageWireEntry } from './triage-response.ts'
+import { MAX_PACKAGE_INVENTORY_BYTES } from './bundle-cache.ts'
+import { backfillBundleSummaries, bundleSummaries } from './bundle-catalog.ts'
+import { ADVISORIES_TIMEOUT_MS, fetchBundleAdvisories } from './bundle-advisories.ts'
+import { serveTeamFeed } from './team-feed.ts'
+
+function json(res: ServerResponse, status: number, body: unknown): void {
+  sendJson(res, status, body, { 'cache-control': 'private, no-store', 'referrer-policy': 'no-referrer' })
+}
+
+// Called before ALL other routing, including OAuth, discovery, static and the
+// combined server fallback. A supplied capability never inherits cookie auth.
+export async function handlePublicWorkspace(req: IncomingMessage, res: ServerResponse, deps: ManagedHttpDeps, url: URL): Promise<void> {
+  const token = req.headers['x-deepview-share']
+  if (!deps.config.allowShare || typeof token !== 'string' || !/^[A-Za-z0-9_-]{43}$/u.test(token)) {
+    json(res, 401, { error: 'invalid-share' }); return
+  }
+  const method = req.method ?? 'GET'
+  if (method !== 'GET' && method !== 'HEAD') { json(res, 403, { error: 'share-read-only' }); return }
+  const shareRoute = /^\/api\/shares\/([A-Za-z0-9_-]+)\/workspace$/u.exec(url.pathname)
+  const teamRoute = /^\/api\/teams\/([^/]+)\/(shared|reports|feed|annotations)$/u.exec(url.pathname)
+  const reportRoute = /^\/api\/reports\/([^/]+)\/(triage|comments|sources)$/u.exec(url.pathname)
+  const bundleRoute = /^\/api\/bundles\/([^/]+)\/(metadata|contents|download|advisories)$/u.exec(url.pathname)
+  if (!shareRoute && !teamRoute && !reportRoute && !bundleRoute) { json(res, 403, { error: 'share-scope-required' }); return }
+  const tokenHash = hashToken(token)
+  const snapshot = await deps.db.getWorkspaceShare(tokenHash)
+  if (!snapshot) { json(res, 401, { error: 'invalid-share' }); return }
+  const recheck = async () => {
+    const current = deps.config.allowShare && await deps.db.getWorkspaceShare(tokenHash)
+    if (!current || JSON.stringify(current) !== JSON.stringify(snapshot)) throw new TeamReportsError(404, 'workspace-changed')
+  }
+  const send = async (body: unknown) => { await recheck(); json(res, 200, body) }
+  const sendTeam = async () => {
+    const summaries = await bundleSummaries(snapshot.team.bundles, deps.bundleCache)
+    await send({ user: snapshot.user, team: { ...snapshot.team,
+      bundles: snapshot.team.bundles.map(bundle => ({ ...bundle, ...(summaries.get(bundle.integrity) ?? { summary: null, summaryRetryAt: null }) })),
+    } })
+    await backfillBundleSummaries(snapshot.team.bundles, deps.bundleCache)
+  }
+  const stream = async (stored: OpenedBlob, encoding: string | null, contentType = 'application/json') => {
+    try { await recheck() } catch (error) { stored.stream.destroy(); throw error }
+    res.writeHead(200, { 'content-type': contentType, 'cache-control': 'private, no-store',
+      'x-content-type-options': 'nosniff', ...(encoding ? { 'content-encoding': encoding } : {}),
+      ...(stored.size == null ? {} : { 'content-length': String(stored.size) }),
+    })
+    if (method === 'HEAD') { stored.stream.destroy(); res.end(); return }
+    try { await pipeline(stored.stream, res) } catch { res.destroy() }
+  }
+  if (url.searchParams.has('team') && (url.searchParams.getAll('team').length !== 1 || url.searchParams.get('team') !== snapshot.teamId)) {
+    json(res, 404, { error: 'no-team' }); return
+  }
+  if (shareRoute) {
+    // The short hash is a recognizable link ID, never an access grant. Resolve
+    // with the full token so colliding IDs or slugs cannot broaden its scope.
+    // Existing links used the team ID as their fragment prefix.
+    if (shareRoute[1] !== tokenHash.slice(0, 8) && shareRoute[1] !== snapshot.teamId) {
+      json(res, 404, { error: 'no-share' }); return
+    }
+    await sendTeam(); return
+  }
+  if (teamRoute) {
+    if (teamRoute[1] !== snapshot.teamId) { json(res, 404, { error: 'no-team' }); return }
+    if (teamRoute[2] === 'feed') {
+      if (method !== 'GET') { json(res, 405, { error: 'method-not-allowed' }); return }
+      await serveTeamFeed(res, deps, snapshot, recheck, { readState: () => deps.db.getWorkspaceShareFeedState(tokenHash) }); return
+    }
+    if (teamRoute[2] === 'annotations') {
+      await send(await loadTeamAnnotations(deps.db, deps.reportStore, snapshot, url.searchParams.get('reportId'))); return
+    }
+    if (teamRoute[2] === 'shared') { await sendTeam(); return }
+    const body = await loadTeamReportsResponse(deps.db, deps.reportStore, snapshot)
+    await recheck()
+    res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'private, no-store', 'referrer-policy': 'no-referrer' })
+    writeResponse(res, body); return
+  }
+  if (reportRoute) {
+    const id = reportRoute[1]!, part = reportRoute[2]!
+    if (!snapshot.reports.some(report => report.id === id)) { json(res, 404, { error: 'no-report' }); return }
+    const visible = await teamReportVisibility(deps.db, deps.reportStore, snapshot, id)
+    await recheck()
+    if (part === 'sources') { await sources(res, deps, snapshot, id, visible.sourcePaths, recheck, stream); return }
+    if (part === 'comments') { await send({ comments: await deps.db.listComments([...visible.ids]) }); return }
+    const entries = Object.fromEntries((await deps.db.listTriage([...visible.ids])).map(row => [row.findingId, triageWireEntry(row)]))
+    await send({ entries }); return
+  }
+  const bundle = snapshot.bundles.find(item => item.id === bundleRoute![1])
+  if (!bundle) { json(res, 404, { error: 'no-bundle' }); return }
+  if (bundleRoute![2] === 'advisories' && !snapshot.permissions.security) { json(res, 403, { error: 'security-access-required' }); return }
+  await serveBundle(res, deps, bundle, bundleRoute![2]!, url, recheck, stream)
+}
+
+async function serveBundle(res: ServerResponse, deps: ManagedHttpDeps, bundle: ManagedBundle, part: string, url: URL,
+  recheck: () => Promise<void>, stream: (stored: OpenedBlob, encoding: string | null, contentType?: string) => Promise<void>) {
+  if (part === 'download') {
+    const stored = await deps.bundleStore.open(bundle.id, bundle.kind)
+    if (!stored) { json(res, 503, { error: 'unavailable' }); return }
+    await stream(stored, bundle.kind === 'sourcemap' ? 'br' : null, 'application/octet-stream'); return
+  }
+  if (!deps.bundleCache) { json(res, 503, { error: 'unavailable' }); return }
+  if (part === 'advisories') {
+    if (bundle.kind !== 'stasis') { json(res, 422, { error: 'unsupported-bundle' }); return }
+    const inventory = await deps.bundleCache.advisoryInventory(bundle, url.searchParams.get('reason') ?? '')
+    await recheck()
+    if (inventory === null) { json(res, 413, { error: 'payload-too-large' }); return }
+    if (inventory === undefined) { json(res, 400, { error: 'unknown-reason' }); return }
+    if (Buffer.byteLength(JSON.stringify(inventory)) > MAX_PACKAGE_INVENTORY_BYTES) { json(res, 413, { error: 'payload-too-large' }); return }
+    const result = await fetchBundleAdvisories(inventory.packages, AbortSignal.timeout(ADVISORIES_TIMEOUT_MS), {
+      debug: deps.config.debug, repoAdvisories: url.searchParams.get('repoAdvisories') === 'true',
+    })
+    await recheck()
+    json(res, result.status, result.status === 200 ? { ...inventory, advisories: result.body } : result.body); return
+  }
+  let cached
+  try { cached = await deps.bundleCache.open(bundle, part as 'metadata' | 'contents') }
+  catch { json(res, 422, { error: 'bundle-unavailable' }); return }
+  await stream(cached, 'br')
+}
+
+async function sources(res: ServerResponse, deps: ManagedHttpDeps, snapshot: WorkspaceShareSnapshot,
+  id: string, paths: Set<string>, recheck: () => Promise<void>, stream: (stored: OpenedBlob, encoding: string | null) => Promise<void>) {
+  const report = await deps.db.getReport(id)
+  const bundle = report?.bundleId ? await deps.db.getBundle(report.bundleId) : null
+  const empty = async () => { await recheck(); res.writeHead(204, { 'cache-control': 'private, no-store' }); res.end() }
+  if (!report || !bundle || !['stasis', 'sourcemap'].includes(bundle.kind ?? '') || bundle.repoId !== report.repoId) { await empty(); return }
+  if (!deps.reportSourcesCache) { json(res, 503, { error: 'unavailable' }); return }
+  let cached
+  try { cached = await deps.reportSourcesCache.open(report, bundle, snapshot.permissions, paths) }
+  catch { await empty(); return }
+  if (!cached) { await empty(); return }
+  const current = await deps.db.getReport(id), currentBundle = await deps.db.getBundle(bundle.id)
+  if (JSON.stringify(current) !== JSON.stringify(report) || JSON.stringify(currentBundle) !== JSON.stringify(bundle)
+      || snapshot.reports.find(item => item.id === id)?.repo.github !== cached.repo.github) {
+    cached.stream.destroy(); throw new TeamReportsError(404, 'workspace-changed')
+  }
+  await stream(cached, 'gzip')
+}

package/server-managed/repo-path.ts

@@ -0,0 +1,21 @@
+const MAX_TEAM_PATH = 500
+
+// Canonicalize only equivalent Git paths: '/' separates components and empty
+// or '.' components do not change the directory. Reject ambiguous input rather
+// than deleting characters from directory names used for authorization.
+// `{ ok:false }` makes the handler 400; `{ path:null }` means the whole repo.
+export function normalizeTeamPath(raw: unknown): { ok: true; path: string | null } | { ok: false } {
+  if (typeof raw !== 'string') return { ok: true, path: null }
+  // Spaces and backslashes can be literal parts of Git directory names.
+  // Neither trimming nor treating '\\' as a separator preserves that identity.
+  if (/\p{Cc}/u.test(raw) || raw.includes('\\') || raw !== raw.trim()) return { ok: false }
+  const segments: string[] = []
+  for (const seg of raw.split('/')) {
+    if (seg === '' || seg === '.') continue
+    if (seg === '..' || seg !== seg.trim()) return { ok: false }
+    segments.push(seg)
+  }
+  const path = segments.join('/')
+  if (path.length > MAX_TEAM_PATH) return { ok: false }
+  return { ok: true, path: path === '' ? null : path }
+}

package/server-managed/report-migration.ts

@@ -0,0 +1,35 @@
+// SQLite deployments store report blobs beside the database. Recover location
+// metadata before introducing directory-based team access. Schema and data move
+// together so a missing/corrupt blob leaves the migration retryable after repair.
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { DatabaseSync } from 'node:sqlite'
+import { reportRepoGithub } from '@preventive/report'
+import { readManagedReport } from '../common/managed/report-content.ts'
+import { normalizeTeamPath } from './repo-path.ts'
+
+export function migrateReportLocations(db: DatabaseSync, reportDir: string): void {
+  const columns = db.prepare('PRAGMA table_info(managed_report)').all() as { name: string }[]
+  if (columns.some((column) => column.name === 'repo_directory')) return
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    db.exec("ALTER TABLE managed_report ADD COLUMN repo_directory TEXT NOT NULL DEFAULT ''")
+    const update = db.prepare('UPDATE managed_report SET repo_directory = ?, repo_embedded = ? WHERE id = ?')
+    const reports = db.prepare('SELECT id, filename FROM managed_report').all() as { id: string, filename: string }[]
+    for (const { id, filename } of reports) {
+      // Same opaque UUID boundary as the blob store; never splice arbitrary
+      // database text into a filesystem path during an upgrade.
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(id)) throw new Error(`Invalid legacy report id: ${id}`)
+      const { data } = readManagedReport(readFileSync(join(reportDir, id), 'utf8'), filename)
+      if (data == null) throw new Error(`Cannot migrate location of unreadable report ${id}`)
+      const embedded = reportRepoGithub(data) != null
+      const directory = normalizeTeamPath(data.repo?.directory)
+      if (!directory.ok) throw new Error(`Cannot migrate invalid directory of report ${id}`)
+      update.run(directory.path ?? '', embedded ? 1 : 0, id)
+    }
+    db.exec('COMMIT')
+  } catch (err) {
+    db.exec('ROLLBACK')
+    throw err
+  }
+}

package/server-managed/report-query.ts

@@ -0,0 +1,10 @@
+// Large workspaces remain a single request. Bound both the stored input and
+// the encoded response, independently of the per-upload size limit.
+export const MAX_REPORT_QUERY_COUNT = 4096
+export const MAX_REPORT_QUERY_BYTES = 1024 * 1024 * 1024
+
+// The import catalog scans a bounded page, not the whole installation. A
+// report larger than the byte target occupies a page by itself; upload limits
+// still bound that single report and the cursor must always make progress.
+export const FINDING_CATALOG_PAGE_COUNT = 128
+export const FINDING_CATALOG_PAGE_BYTES = 32 * 1024 * 1024

package/server-managed/report-response.ts

@@ -0,0 +1,16 @@
+import { MIMEType } from 'node:util'
+
+// The metadata envelope is opt-in. Wildcards keep the legacy raw report;
+// an explicit, acceptable application/json range requests the envelope.
+export function acceptsReportMetadata(accept: string | undefined): boolean {
+  // Commas inside quoted media-type parameters do not separate ranges.
+  for (const range of accept?.match(/(?:[^",]|"(?:\\.|[^"\\])*")+/gu) ?? []) {
+    try {
+      const media = new MIMEType(range.trim())
+      if (media.essence !== 'application/json') continue
+      const quality = media.params.get('q') ?? '1'
+      if (/^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/u.test(quality) && Number(quality) > 0) return true
+    } catch { /* Ignore malformed media ranges. */ }
+  }
+  return false
+}

package/server-managed/report-sources.ts

@@ -0,0 +1,166 @@
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { extname } from 'node:path'
+import { promisify } from 'node:util'
+import { gzip } from 'node:zlib'
+import { bundleSourcesAsMap } from '../common/bundle-sources.js'
+import { bundleSourceImports } from '../common/bundle-source-links.js'
+import type { BundleDetails } from '../common/bundle-metadata.js'
+import { loadManagedFindings, managedFindingSourcePaths } from '../common/managed/report-content.ts'
+import { type ViewerPermissions, filterReportContent } from '../common/managed/report-filter.ts'
+import { CacheMissError, type CacheStorage } from './cache-storage.ts'
+import { readBundleDetails } from './bundle-cache.ts'
+import type { BlobStore } from './blob-store.ts'
+import type { BundleStore } from './bundle-store.ts'
+import type { ManagedBundle, ManagedDb, ReportRecord } from './db.ts'
+
+const compress = promisify(gzip)
+const reportFormat = (filename: string) => extname(filename).toLowerCase()
+
+function bundleDirectory(id: string) {
+  if (!/^[a-f\d-]{36}$/iu.test(id)) throw new Error('Invalid bundle id')
+  return id
+}
+function reportDirectory(bundleId: string, sha256: string) {
+  return `${bundleDirectory(bundleId)}/v1-${createHash('sha256').update(sha256).digest('hex')}`
+}
+function formatDirectory(bundleId: string, sha256: string, name: string) {
+  return `${reportDirectory(bundleId, sha256)}/${createHash('sha256').update(reportFormat(name)).digest('hex')}`
+}
+function sourceCacheFilename(report: ReportRecord, bundle: ManagedBundle, permissions: ViewerPermissions, repo: { github: string | null }, sourcePaths?: Set<string>) {
+  const key = createHash('sha256').update(JSON.stringify([
+    'finding-access-v6', sourcePaths ? [...sourcePaths].toSorted() : null, bundle.integrity, bundle.kind, permissions.dependencies, permissions.security, repo,
+  ])).digest('hex')
+  return `${formatDirectory(bundle.id, report.sha256, report.filename)}/${key}.json.gz`
+}
+
+// Match the report's spelling exactly, then an unambiguous path suffix. Never
+// guess between duplicate basenames or treat a bundle path as a disk pathname.
+function selectSources(sourcePaths: Set<string>, sources: Map<string, string>) {
+  const byBasename = new Map<string, string[]>()
+  for (const file of sources.keys()) {
+    const basename = file.split('/').at(-1)!
+    const candidates = byBasename.get(basename) ?? []
+    candidates.push(file)
+    byBasename.set(basename, candidates)
+  }
+  const files = new Map<string, string>(), paths = new Map<string, string>()
+  function add(path: unknown) {
+    if (typeof path !== 'string' || !path || paths.has(path)) return
+    let file = sources.has(path) ? path : null
+    if (file === null) {
+      const suffix = path.startsWith('/') ? path : `/${path}`
+      const matches = byBasename.get(path.split('/').at(-1)!)?.filter(candidate => candidate.endsWith(suffix)) ?? []
+      if (matches.length === 1) file = matches[0]!
+    }
+    if (file === null) return
+    paths.set(path, file)
+    files.set(file, sources.get(file)!)
+  }
+  for (const path of sourcePaths) add(path)
+  return { files: [...files], paths: [...paths] }
+}
+
+function encodeSources(integrity: string, details: BundleDetails, selection: ReturnType<typeof selectSources>) {
+  const sources = new Map(selection.files)
+  const imports = [...bundleSourceImports(details, sources)].map(([parent, targets]) => [parent, [...targets]])
+  const bundle = details.kind === 'stasis' ? details.bundle as { formats: Map<string, string> } : null
+  const formats = [...(bundle?.formats ?? [])].filter(([file]) => sources.has(file))
+  return compress(Buffer.from(JSON.stringify({ integrity, ...selection, imports, formats })), { level: 6 })
+}
+
+// Immutable report hashes share a derivative across duplicate uploads. Bundle
+// identity and visibility are part of the key: a broader viewer's sources must
+// never populate a restricted response. Group derivatives by hash and filename
+// format so each format's permissions can be removed after its last deletion.
+export function createReportSourcesCache(storage: CacheStorage, db: ManagedDb, reports: BlobStore, bundles: BundleStore) {
+  const pending = new Map<string, { reportId: string; job: Promise<boolean> }>()
+  let queue = Promise.resolve()
+  function enqueue<T>(work: () => Promise<T>): Promise<T> {
+    const job = queue.then(work)
+    queue = job.then(() => undefined, () => undefined)
+    return job
+  }
+  async function referenced(report: ReportRecord, bundle: ManagedBundle) {
+    const names = await db.listReportFilenamesWithBundleHash(bundle.id, report.sha256)
+    return names.some(name => reportFormat(name) === reportFormat(report.filename)) && await db.getBundle(bundle.id) != null
+  }
+  async function build(target: string, report: ReportRecord, bundle: ManagedBundle, permissions: ViewerPermissions, repo: { github: string | null }, sourcePaths?: Set<string>) {
+    // Team requests supply paths from their already-filtered members. Reopening
+    // the original report by ID would conflate visible and hidden occurrences.
+    if (!sourcePaths) {
+      const bytes = await reports.get(report.id)
+      if (!bytes) return false
+      const parsed = await loadManagedFindings(filterReportContent(bytes.toString('utf8'), permissions, report.filename, repo), report.filename)
+      if (!parsed) return false
+      sourcePaths = managedFindingSourcePaths(parsed.findings)
+    }
+    const details = await readBundleDetails(bundle, bundles)
+    if (!details) return false
+    const selection = selectSources(sourcePaths, bundleSourcesAsMap(details))
+    const body = await encodeSources(bundle.integrity, details, selection)
+    // A duplicate with the same hash AND format can use these parsed bytes.
+    // Another format must not keep a deleted variant's late build alive.
+    if (!(await referenced(report, bundle))) return false
+    await storage.put(target, body)
+    // Another instance may finish deletion while this write is in flight.
+    // Recheck after publishing so a late builder cannot resurrect its cache.
+    if (!(await referenced(report, bundle))) {
+      await storage.delete(formatDirectory(bundle.id, report.sha256, report.filename))
+      return false
+    }
+    return true
+  }
+  async function ensure(target: string, report: ReportRecord, bundle: ManagedBundle, permissions: ViewerPermissions, repo: { github: string | null }, sourcePaths?: Set<string>): Promise<boolean> {
+    const existing = pending.get(target)
+    if (existing) {
+      const ready = await existing.job
+      if (ready || existing.reportId === report.id) return ready
+      // Deletion can also win before the initiator reads its blob. Retry with
+      // this request's row instead of caching that other row's miss as 204.
+      const initiator = await db.getReport(existing.reportId)
+      if (initiator?.bundleId === bundle.id && initiator.sha256 === report.sha256) return false
+      if (pending.get(target) === existing) pending.delete(target)
+      return ensure(target, report, bundle, permissions, repo, sourcePaths)
+    }
+    const job = (async () => {
+      if (await storage.exists(target)) return true
+      // Serial cold builds bound peak decompression/parsing memory.
+      return enqueue(() => build(target, report, bundle, permissions, repo, sourcePaths))
+    })()
+    const entry = { reportId: report.id, job }
+    pending.set(target, entry)
+    try { return await job } finally { if (pending.get(target) === entry) pending.delete(target) }
+  }
+  return {
+    async open(report: ReportRecord, bundle: ManagedBundle, permissions: ViewerPermissions, sourcePaths?: Set<string>) {
+      const repo = { github: (await db.listAllRepos()).find(entry => entry.repoId === report.repoId)?.fullName ?? null }
+      const target = sourceCacheFilename(report, bundle, permissions, repo, sourcePaths)
+      try { return { ...await storage.open(target), repo } }
+      catch (error) { if (!(error instanceof CacheMissError)) throw error }
+      if (!(await ensure(target, report, bundle, permissions, repo, sourcePaths))) return null
+      const opened = await storage.open(target)
+      return { ...opened, repo }
+    },
+    async deleteBundle(id: string) {
+      const prefix = `${bundleDirectory(id)}/`
+      await Promise.allSettled([...pending].filter(([key]) => key.startsWith(prefix)).map(([, entry]) => entry.job))
+      await storage.delete(bundleDirectory(id))
+    },
+    async deleteReport(report: Pick<ReportRecord, 'bundleId' | 'sha256' | 'filename'>) {
+      const { bundleId, sha256 } = report
+      if (bundleId === null) return
+      // Called after metadata deletion. Serialize with builders so a cold
+      // request cannot recreate a derivative after its cleanup has finished.
+      await enqueue(async () => {
+        const names = await db.listReportFilenamesWithBundleHash(bundleId, sha256)
+        if (names.length === 0) {
+          await storage.delete(reportDirectory(bundleId, sha256))
+        } else if (!names.some(name => reportFormat(name) === reportFormat(report.filename))) {
+          await storage.delete(formatDirectory(bundleId, sha256, report.filename))
+        }
+      })
+    },
+  }
+}
+export type ReportSourcesCache = ReturnType<typeof createReportSourcesCache>