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

package/server-managed/repository-policy.ts

@@ -0,0 +1,27 @@
+import type { StoredUser } from './db.ts'
+
+const WHITEHAT = [
+  291301, // ChALkeR
+  259122746, // exo-nikita
+  247161625, // ex0sec
+]
+const whitehatIds = new Set(WHITEHAT)
+
+// (1) Server permission to add repositories. Keep this independent of GitHub
+// identity and ecosystem exceptions if other install modes broaden it later.
+export function canAddRepositories(user: StoredUser): boolean {
+  return user.role === 'admin'
+}
+
+// (3b) Only the ecosystem safeguard for public repositories is bypassed by
+// WHITEHAT. Callers must separately establish (0) server readability, (1) add
+// permission, and (2) server admin or GitHub access to this repository.
+export function passesPublicRepositorySafeguard(githubUserId: number | null, involved: boolean): boolean {
+  return involved || (githubUserId != null && whitehatIds.has(githubUserId))
+}
+
+// Arbitrary public repositories have no involvement evidence, so (2) requires
+// admin even if (1) expands in the future. This capability is also the UI gate.
+export function canAddAnyPublicRepository(user: StoredUser, githubUserId: number | null): boolean {
+  return canAddRepositories(user) && user.role === 'admin' && passesPublicRepositorySafeguard(githubUserId, false)
+}

package/server-managed/session.ts

@@ -0,0 +1,78 @@
+// Session + cookie plumbing for the managed auth server. The raw session
+// token lives ONLY in the cookie; the DB row id is its SHA-256 (see crypto.ts)
+// so a DB read can't reconstruct a live cookie. A double-submit CSRF token is
+// minted per session and returned to the client (echoed back on mutations).
+//
+// Async throughout — the store (db.ts) is async so a future non-SQLite
+// backend slots in without touching these helpers.
+import type { ManagedConfig } from './config.ts'
+import type { ManagedDb, ManagedSession, ManagedUser, StoredUser } from './db.ts'
+import { hashToken, randomToken } from './crypto.ts'
+
+// Base name for the short-lived OAuth-state cookie; `__Host-` is prefixed via
+// `cookieName` when cookies are Secure.
+export const STATE_COOKIE = 'dvstate'
+
+// `__Host-`-prefix the base name when cookies are Secure (the prefix mandates
+// Secure + Path=/ + no Domain, which `buildCookie` already emits).
+export function cookieName(config: ManagedConfig, base: string): string {
+  return config.cookieSecure ? `__Host-${base}` : base
+}
+
+export function buildCookie(
+  name: string, value: string,
+  opts: { maxAgeS: number; secure: boolean; sameSite?: 'Lax' | 'Strict' },
+): string {
+  const parts = [`${name}=${value}`, 'Path=/', 'HttpOnly', `SameSite=${opts.sameSite ?? 'Lax'}`, `Max-Age=${opts.maxAgeS}`]
+  if (opts.secure) parts.push('Secure')
+  return parts.join('; ')
+}
+
+// Expire a cookie now (Max-Age=0).
+export function clearCookie(name: string, secure: boolean): string {
+  return buildCookie(name, '', { maxAgeS: 0, secure })
+}
+
+export function parseCookies(header: string | undefined): Map<string, string> {
+  const out = new Map<string, string>()
+  if (!header) return out
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=')
+    if (eq < 0) continue
+    const k = part.slice(0, eq).trim()
+    if (k) out.set(k, part.slice(eq + 1).trim())
+  }
+  return out
+}
+
+// Mint a session for a freshly-authenticated user. Upserts the identity, then
+// stores the session keyed by the cookie token's hash. Returns the cookie to
+// set and the CSRF token (also persisted on the row).
+export async function createSession(
+  config: ManagedConfig, db: ManagedDb, user: ManagedUser, now: number,
+): Promise<{ setCookie: string; csrfToken: string; userId: string }> {
+  const token = randomToken()
+  const csrfToken = randomToken()
+  const userId = await db.upsertUser(user, now, config.initialAdminGithubId)
+  await db.createSession({ id: hashToken(token), userId, csrfToken, expiresAt: now + config.sessionTtlMs }, now)
+  const setCookie = buildCookie(config.sessionCookieName, token, {
+    maxAgeS: Math.floor(config.sessionTtlMs / 1000), secure: config.cookieSecure, sameSite: 'Lax',
+  })
+  return { setCookie, csrfToken, userId }
+}
+
+// Resolve the current session (+ user) from the request's cookies, or null.
+export function readSession(
+  config: ManagedConfig, db: ManagedDb, cookieHeader: string | undefined, now: number,
+): Promise<{ session: ManagedSession; user: StoredUser } | null> {
+  const token = parseCookies(cookieHeader).get(config.sessionCookieName)
+  if (token == null || token === '') return Promise.resolve(null)
+  return db.sessionWithUser(hashToken(token), now)
+}
+
+// Drop the session named by the request's cookie (logout). The caller also
+// clears the cookie client-side.
+export async function endSession(config: ManagedConfig, db: ManagedDb, cookieHeader: string | undefined): Promise<void> {
+  const token = parseCookies(cookieHeader).get(config.sessionCookieName)
+  if (token != null && token !== '') await db.deleteSession(hashToken(token))
+}

package/server-managed/slugs.ts

@@ -0,0 +1,38 @@
+import type { DatabaseSync } from 'node:sqlite'
+
+// Legacy non-UUID IDs stay intact. Production IDs are UUIDs; only their final
+// component is proposed as a slug, never an arbitrary prefix or abbreviation.
+export function preferredSlug(id: string): string {
+  return /^[a-f\d]{8}(?:-[a-f\d]{4}){3}-([a-f\d]{12})$/iu.exec(id)?.[1] ?? id
+}
+
+export function allocateMissingSlugs(rows: { id: string; slug: string | null }[]): { id: string; slug: string }[] {
+  // Reserve legacy IDs before UUID suffixes can claim them.
+  const used = new Set(rows.flatMap(row => row.slug == null ? [row.id] : [row.id, row.slug]))
+  const allocated = []
+  for (const row of rows) {
+    if (row.slug != null) continue
+    const candidate = preferredSlug(row.id)
+    const slug = used.has(candidate) ? row.id : candidate
+    allocated.push({ id: row.id, slug })
+    used.add(slug)
+  }
+  return allocated
+}
+
+// Allocate once, across the entire namespace rather than a viewer's teams.
+// Keep existing slugs stable when names, memberships, or collisions change.
+export function migrateSlugs(db: DatabaseSync): void {
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    for (const table of ['managed_team', 'managed_report', 'managed_bundle']) {
+      const columns = db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[]
+      if (!columns.some(column => column.name === 'slug')) db.exec(`ALTER TABLE ${table} ADD COLUMN slug TEXT`)
+      const rows = db.prepare(`SELECT id, slug FROM ${table} ORDER BY id`).all() as { id: string; slug: string | null }[]
+      const update = db.prepare(`UPDATE ${table} SET slug = ? WHERE id = ?`)
+      for (const row of allocateMissingSlugs(rows)) update.run(row.slug, row.id)
+      db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS ${table}_slug_idx ON ${table}(slug)`)
+    }
+    db.exec('COMMIT')
+  } catch (err) { db.exec('ROLLBACK'); throw err }
+}

package/server-managed/sql-postgres.ts

@@ -0,0 +1,30 @@
+// The small SQL dialect used by the shared store. Parameter values never pass
+// through these rewrites; only our own SQL does. Keep aliases case-sensitive.
+export function postgresSql(source: string): { sql: string; names: string[] } {
+  const names: string[] = []
+  let position = 0
+  let sql = source.replaceAll('json_each(:contexts)', 'jsonb_array_elements(:contexts::jsonb)')
+    .replaceAll(/json_extract\((\w+\.value), '\$\.(\w+)'\)/gu, "($1->>'$2')")
+    .replaceAll('json_each(?)', 'jsonb_array_elements_text(?::jsonb)')
+    .replaceAll('INSERT OR IGNORE INTO', 'INSERT INTO')
+    .replaceAll('CROSS JOIN', 'JOIN')
+    .replaceAll(/\binstr\(/gu, 'strpos(')
+  // Quoted literals (including ':') are never placeholders or identifiers.
+  sql = sql.split(/('(?:''|[^'])*')/u).map((part, i) => i % 2 ? part : part
+    .replaceAll(/\?|(?<!:):([a-zA-Z]\w*)/gu, (_match, name: string | undefined) => {
+      if (!name) return `$${++position}`
+      let index = names.indexOf(name)
+      if (index < 0) { index = names.length; names.push(name) }
+      return `$${index + 1}`
+    })
+    .replaceAll(/\b[a-z]+[A-Z]\w*\b/gu, name => `"${name}"`)
+  ).join('')
+  sql = sql.replaceAll(/(\$\d+) IS NULL/gu, '$1::text IS NULL')
+  if (source.includes('INSERT OR IGNORE')) sql += ' ON CONFLICT DO NOTHING'
+  return { sql, names }
+}
+
+export function postgresSchema(sql: string): string {
+  return sql.replaceAll(') STRICT;', ');').replaceAll(/\bINTEGER\b/gu, 'BIGINT')
+    .replaceAll(/seq\s+BIGINT PRIMARY KEY/gu, 'seq BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY')
+}

package/server-managed/sql.ts

@@ -0,0 +1,61 @@
+// Each public store operation owns a transaction. SQLite serializes access to
+// its single connection across awaits; Neon binds one connection per operation.
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite'
+import type { ManagedDb } from './db-methods.ts'
+
+type MaybePromise<T> = T | Promise<T>
+export interface ManagedSql {
+  prepare(sql: string): {
+    get(...params: unknown[]): MaybePromise<unknown>
+    all(...params: unknown[]): MaybePromise<unknown[]>
+    run(...params: unknown[]): MaybePromise<{ changes: number | bigint }>
+  }
+  close(): MaybePromise<void>
+}
+export interface ManagedSqlDriver extends ManagedSql {
+  scope<T>(write: boolean, work: () => Promise<T>): Promise<T>
+}
+
+export function scopeManagedMethods(methods: ManagedDb, driver: ManagedSqlDriver): ManagedDb {
+  const entries = Object.entries(methods).map(([name, method]) => {
+    if (name === 'close') return [name, async () => { await driver.close() }]
+    const write = !/^(?:get|list|userCanRead|reportPermissionsFor)/u.test(name)
+    return [name, (...args: unknown[]) => driver.scope(write, () => method(...args))]
+  })
+  return Object.fromEntries(entries) as ManagedDb
+}
+
+export function createSqliteDriver(db: DatabaseSync): ManagedSqlDriver {
+  let queue = Promise.resolve()
+  let closed = false
+  function enqueue<T>(work: () => Promise<T>): Promise<T> {
+    const result = queue.then(work)
+    queue = result.then(() => undefined, () => undefined)
+    return result
+  }
+  return {
+    prepare(sql) {
+      const stmt = db.prepare(sql)
+      return {
+        get: (...args) => stmt.get(...args as SQLInputValue[]),
+        all: (...args) => stmt.all(...args as SQLInputValue[]),
+        run: (...args) => stmt.run(...args as SQLInputValue[]),
+      }
+    },
+    scope(write, work) {
+      if (closed) return Promise.reject(new Error('Managed database is closed'))
+      return enqueue(async () => {
+        db.exec(write ? 'BEGIN IMMEDIATE' : 'BEGIN')
+        try {
+          const result = await work()
+          db.exec('COMMIT')
+          return result
+        } catch (err) {
+          db.exec('ROLLBACK')
+          throw err
+        }
+      })
+    },
+    async close() { closed = true; await queue; db.close() },
+  }
+}

package/server-managed/static.ts

@@ -0,0 +1,28 @@
+import { type StaticHandler, loadStatic } from '../server-e2e/static.ts'
+import { parseManagedRoute } from '../common/managed/routes.js'
+
+// A deep page URL must still resolve every asset at the app root. Preload
+// headers resolve against the request URL, so their hrefs must be absolute too.
+export function managedPageHtml(html: string): string {
+  return html.replaceAll(/(href|src)="\.\//gu, '$1="/')
+}
+
+export function loadManagedStatic(staticDir: string, { indexOnly = false, scanServer = null }: { indexOnly?: boolean, scanServer?: string | null } = {}): StaticHandler {
+  const serve = loadStatic(staticDir, scanServer, { transformIndex: managedPageHtml, indexOnly })
+  return (req, res) => {
+    if (!req.url?.startsWith('/') || req.url.startsWith('//')) return false
+    const url = new URL(req.url, 'http://localhost')
+    let path
+    try { path = decodeURIComponent(url.pathname) } catch { return false }
+    // No API request, including an unknown API route, may receive app HTML.
+    if (path === '/api' || path.startsWith('/api/')) return false
+    if (serve(req, res)) return true
+    if (req.method !== 'GET' && req.method !== 'HEAD') return false
+    // Finding IDs can contain dots (including URL-shaped IDs). Recognised
+    // pages still receive HTML; missing assets retain a 404.
+    if (path.split('/').at(-1)?.includes('.') && !parseManagedRoute(url)) return false
+    const original = req.url
+    req.url = '/'
+    try { return serve(req, res) } finally { req.url = original }
+  }
+}

package/server-managed/storage.ts

@@ -0,0 +1,34 @@
+// Backend selection is shared by standalone, combined and function entrypoints.
+import { dirname, join } from 'node:path'
+import { createDiskAvatarStore } from './avatar-store.ts'
+import { createDiskBlobStore } from './blob-store.ts'
+import { createDiskBundleStore } from './bundle-store.ts'
+import { createBundleCache, createDiskBundleCache } from './bundle-cache.ts'
+import { createDiskCacheStorage } from './cache-storage.ts'
+import { createReportSourcesCache } from './report-sources.ts'
+import { openManagedVercelStorage } from './blob-vercel.ts'
+import { openNeonManagedDb } from './db-neon.ts'
+import type { ManagedConfig } from './config.ts'
+
+export async function openManagedStorage(config: ManagedConfig) {
+  const options = { triageHistoryLimit: config.triageHistoryLimit }
+  if (config.neonUrl) {
+    if (!config.blobToken) throw new Error('Managed Neon mode requires BLOB_READ_WRITE_TOKEN')
+    const storage = await openManagedVercelStorage(config.blobToken)
+    const db = await openNeonManagedDb(config.neonUrl, options)
+    return { ...storage, db, bundleCache: createBundleCache(storage.cacheStorage, db, storage.bundleStore),
+      reportSourcesCache: createReportSourcesCache(storage.reportSourcesStorage, db, storage.reportStore, storage.bundleStore),
+    }
+  }
+  if (config.serverless) throw new Error('Serverless managed storage requires Neon')
+  const { openSqliteManagedDb } = await import('./db.ts')
+  const db = openSqliteManagedDb(config.dbPath, options)
+  const dir = dirname(config.dbPath)
+  const reportStore = createDiskBlobStore(join(dir, 'reports'))
+  const bundleStore = createDiskBundleStore(join(dir, 'bundles'))
+  return { db, reportStore, bundleStore,
+    reportSourcesCache: createReportSourcesCache(createDiskCacheStorage(join(dir, 'cache', 'report-sources')), db, reportStore, bundleStore),
+    avatarStore: createDiskAvatarStore(join(dir, 'avatars')),
+    bundleCache: createDiskBundleCache(join(dir, 'cache', 'bundles'), db, bundleStore),
+  }
+}

package/server-managed/team-catalog.ts

@@ -0,0 +1,7 @@
+import { createHash } from 'node:crypto'
+
+// Version only this user's visible catalog, including access and content keys.
+// REST and the live feed must describe exactly the same snapshot.
+export function teamCatalogRevision(teams: readonly unknown[]): string {
+  return createHash('sha256').update(JSON.stringify(teams)).digest('base64url')
+}

package/server-managed/team-feed.ts

@@ -0,0 +1,128 @@
+import type { ServerResponse } from 'node:http'
+import { setTimeout as delay } from 'node:timers/promises'
+import type { ManagedHttpDeps } from './http.ts'
+import type { StoredUser, TeamReportAccessSnapshot } from './db.ts'
+import { TeamReportsError, teamSnapshotKey, teamWorkspaceFindingIds } from './team-reports.ts'
+
+// Short database reads work across instances without pinning a Neon connection.
+// All polling belongs to the awaited request; nothing runs after it completes.
+export const TEAM_FEED_POLL_MS = 3_000
+export const TEAM_FEED_LIFETIME_MS = 240_000 // below the configured Vercel 300s
+const HEARTBEAT_MS = 15_000
+
+type FeedOptions = { pollMs?: number; lifetimeMs?: number }
+type Publish = (event: 'teams' | 'triage', revision: string | undefined) => boolean
+
+// Public capabilities remain scoped to their single shared workspace.
+export async function serveTeamFeed(res: ServerResponse, deps: ManagedHttpDeps,
+  snapshot: TeamReportAccessSnapshot, recheck: () => Promise<void>, options: FeedOptions = {}): Promise<void> {
+  let ids: string[] | undefined
+  await serveFeed(res, deps, async publish => {
+    await recheck()
+    ids ??= [...await teamWorkspaceFindingIds(deps.db, deps.reportStore, snapshot)]
+    const triage = await deps.db.getAnnotationRevision(ids)
+    await recheck()
+    publish('triage', triage)
+  }, options)
+}
+
+// Membership and content notifications cover all of the user's teams. Only
+// the focused team needs report parsing or annotation reads; null is the
+// catalog-only subscription used on landing and management pages.
+export async function serveUserTeamFeed(res: ServerResponse, deps: ManagedHttpDeps,
+  sessionId: string, user: StoredUser, teamId: string | null, options: FeedOptions = {}): Promise<void> {
+  let ids: string[] = [], visibilityKey: string | undefined
+  const checkUser = (current: { user: Pick<StoredUser, 'id' | 'role'> } | null) => {
+    if (!current) throw new TeamReportsError(401, 'unauthenticated')
+    if (current.user.id !== user.id || current.user.role !== user.role || current.user.role === 'none') {
+      throw new TeamReportsError(403, 'access-changed')
+    }
+  }
+  await serveFeed(res, deps, async publish => {
+    const catalog = await deps.db.getUserTeamFeedSnapshot(sessionId, Date.now())
+    checkUser(catalog)
+    checkUser(await deps.db.getReportAccessSnapshot(sessionId, Date.now(), []))
+    // Publish catalog state before loading any report blobs. A slow or broken
+    // focused report must not hide membership/content changes from the client.
+    if (!publish('teams', catalog!.revision) || !teamId) return
+    let triage: string | undefined
+    const snapshot = await deps.db.getTeamReportAccessSnapshot(sessionId, Date.now(), teamId)
+    if (!snapshot) throw new TeamReportsError(401, 'unauthenticated')
+    checkUser(snapshot)
+    const key = teamSnapshotKey(snapshot)
+    if (key !== visibilityKey) {
+      try {
+        ids = snapshot.teamId ? [...await teamWorkspaceFindingIds(deps.db, deps.reportStore, snapshot)] : []
+        visibilityKey = key
+      } catch {
+        // Missing, malformed or temporarily unavailable blobs only suspend
+        // triage. Retry visibility on the next poll, even for the same key.
+        publish('triage', undefined)
+        return
+      }
+    }
+    if (snapshot.teamId) triage = JSON.stringify([key, await deps.db.getAnnotationRevision(ids)])
+    const current = await deps.db.getTeamReportAccessSnapshot(sessionId, Date.now(), teamId)
+    // A concurrent access/content change discards only the annotation read.
+    checkUser(current)
+    if (!current || teamSnapshotKey(current) !== key) return
+    publish('triage', triage)
+  }, options)
+}
+
+async function serveFeed(res: ServerResponse, deps: ManagedHttpDeps, read: (publish: Publish) => Promise<void>,
+  { pollMs = TEAM_FEED_POLL_MS, lifetimeMs = TEAM_FEED_LIFETIME_MS }: FeedOptions): Promise<void> {
+  const controller = new AbortController()
+  const close = () => controller.abort()
+  res.once('close', close)
+  const deadline = setTimeout(close, lifetimeMs)
+  const stopped = () => controller.signal.aborted || res.destroyed || deps.isShuttingDown()
+  // Notifications carry no annotation bodies, finding IDs, or global cursors.
+  // The catalog's opaque version lets clients reuse an identical REST snapshot;
+  // every connection still confirms current access, including after reconnects.
+  function write(frame: string): boolean {
+    if (stopped()) return false
+    if (res.write(frame)) return true
+    // Slow consumers reconnect and read current state; never queue a backlog.
+    res.destroy()
+    return false
+  }
+  try {
+    if (stopped()) return
+    res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'private, no-store, no-transform', 'x-accel-buffering': 'no',
+      'x-content-type-options': 'nosniff', 'referrer-policy': 'no-referrer' })
+    res.flushHeaders()
+    let heartbeat = Date.now()
+    const previous = new Map<string, string>()
+    const publish: Publish = (event, revision) => {
+      if (stopped()) return false
+      if (revision === undefined) { previous.delete(event); return true }
+      if (revision === previous.get(event)) return true
+      const data = event === 'teams' ? JSON.stringify({ revision }) : '{}'
+      if (!write(`event: ${event}\ndata: ${data}\n\n`)) return false
+      previous.set(event, revision)
+      heartbeat = Date.now()
+      return true
+    }
+    while (!stopped()) {
+      await read(publish)
+      if (stopped()) break
+      if (Date.now() - heartbeat >= HEARTBEAT_MS) {
+        if (!write(': keepalive\n\n')) break
+        heartbeat = Date.now()
+      }
+      await delay(pollMs, undefined, { signal: controller.signal }).catch(error => {
+        if (!controller.signal.aborted) throw error
+      })
+    }
+  } catch (error) {
+    if (!res.headersSent) throw error
+    if (error instanceof TeamReportsError) write('event: close\ndata: {}\n\n')
+    else if (!stopped()) throw error
+  } finally {
+    clearTimeout(deadline)
+    res.off('close', close)
+    if (res.headersSent && !res.destroyed) res.end()
+  }
+}

package/server-managed/team-reports.ts

@@ -0,0 +1,156 @@
+// Team content is filtered as one workspace, with separate report envelopes.
+// Only the visibility index is retained in memory for annotations/source reads.
+import { Buffer } from 'node:buffer'
+import { backfillFindingIds, reportEntries, stampSecurityGroups } from '../report/index.js'
+import { managedFindingSourcePaths, readManagedReport } from '../common/managed/report-content.ts'
+import { filterReportData, projectFinding } from '../common/managed/report-filter.ts'
+import type { BlobStore } from './blob-store.ts'
+import type { ManagedDb, TeamReportAccessSnapshot } from './db.ts'
+import { MAX_REPORT_QUERY_BYTES, MAX_REPORT_QUERY_COUNT } from './report-query.ts'
+
+type Finding = Record<string, unknown>
+type TeamReport = { id: string; filename: string; data: unknown; repo: { github: string | null; directory: string } }
+type ReportVisibility = { ids: Set<string>; sourcePaths: Set<string> }
+type Visibility = Map<string, ReportVisibility>
+const VISIBILITY_CACHE_MAX_ITEMS = 250_000
+const VISIBILITY_CACHE_MAX_SNAPSHOTS = 32
+const caches = new WeakMap<ManagedDb, Map<string, Visibility>>()
+function visibilityWeight(visible: Visibility): number {
+  return [...visible.values()].reduce((sum, v) => sum + v.ids.size + v.sourcePaths.size, 0)
+}
+function retainVisibility(db: ManagedDb, key: string, visible: Visibility): void {
+  let cache = caches.get(db)
+  // Replacement contributes its weight once and does not evict a peer merely
+  // because the cache already holds the maximum number of snapshots.
+  cache?.delete(key)
+  const incoming = visibilityWeight(visible)
+  if (incoming > VISIBILITY_CACHE_MAX_ITEMS) return
+  if (!cache) { cache = new Map(); caches.set(db, cache) }
+  let total = incoming + [...cache.values()].reduce((sum, entry) => sum + visibilityWeight(entry), 0)
+  for (const [oldest, entry] of cache) {
+    if (cache.size < VISIBILITY_CACHE_MAX_SNAPSHOTS && total <= VISIBILITY_CACHE_MAX_ITEMS) break
+    cache.delete(oldest)
+    total -= visibilityWeight(entry)
+  }
+  cache.set(key, visible)
+}
+export class TeamReportsError extends Error {
+  status: number
+  constructor(status: number, error: string) { super(error); this.status = status }
+}
+export function teamSnapshotKey(snapshot: TeamReportAccessSnapshot): string {
+  return JSON.stringify([snapshot.user.id, snapshot.user.role, snapshot.teamId, snapshot.reports, snapshot.repositories])
+}
+export async function teamSnapshot(db: ManagedDb, sessionId: string, teamId: string): Promise<TeamReportAccessSnapshot> {
+  const snapshot = await db.getTeamReportAccessSnapshot(sessionId, Date.now(), teamId)
+  if (!snapshot) throw new TeamReportsError(401, 'unauthenticated')
+  if (!snapshot.teamId) throw new TeamReportsError(404, 'no-team')
+  return snapshot
+}
+export async function recheckTeam(db: ManagedDb, sessionId: string, snapshot: TeamReportAccessSnapshot): Promise<void> {
+  if (teamSnapshotKey(await teamSnapshot(db, sessionId, snapshot.teamId!)) !== teamSnapshotKey(snapshot)) throw new TeamReportsError(404, 'workspace-changed')
+}
+function groupsOf(data: unknown): Finding[][] {
+  return (reportEntries(data) ?? []).map(entry => (Array.isArray(entry) ? entry : [entry]).filter(
+    (finding): finding is Finding => finding !== null && typeof finding === 'object' && !Array.isArray(finding),
+  ))
+}
+function linksOf(data: unknown): string[][] | null {
+  const record = data as { source?: string; links?: string[][] }
+  if (record?.source !== 'links' || !Array.isArray(record.links)) return null
+  if (!record.links.every(ids => Array.isArray(ids) && ids.every(id => typeof id === 'string'))) throw new TeamReportsError(422, 'unreadable-links')
+  return record.links
+}
+async function loadTeamWorkspace(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<{ reports: TeamReport[]; visible: Visibility }> {
+  if (snapshot.reports.length > MAX_REPORT_QUERY_COUNT || snapshot.reports.reduce((n, r) => n + r.byteSize, 0) > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+  const reports: TeamReport[] = []
+  let inputBytes = 0
+  // Retain parsed reports for cross-report classification; release raw bytes
+  // after each parse. No unbounded burst of remote reads or duplicate buffers.
+  for (const access of snapshot.reports) {
+    const bytes = await store.get(access.id)
+    if (!bytes) throw new TeamReportsError(503, 'unavailable')
+    inputBytes += bytes.length
+    if (inputBytes > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+    const parsed = readManagedReport(bytes.toString('utf8'), access.filename)
+    if (!parsed.data) throw new TeamReportsError(422, 'unreadable-report')
+    // Backfill before filtering so links, annotations and the client agree on
+    // IDs even when hiding a component would change the original row shape.
+    await backfillFindingIds(groupsOf(parsed.data).flat())
+    reports.push({ id: access.id, filename: access.filename, data: parsed.data, repo: access.repo })
+  }
+  const edges = new Map<string, Set<string>>()
+  const connect = (a: string, b: string) => {
+    if (!edges.has(a)) edges.set(a, new Set())
+    edges.get(a)!.add(b)
+  }
+  // A star is enough for transitive security propagation, without a quadratic
+  // expansion for large links. Unknown IDs can connect known findings.
+  for (const report of reports) {
+    for (const ids of linksOf(report.data) ?? []) {
+      for (const id of ids.slice(1)) { connect(ids[0]!, id); connect(id, ids[0]!) }
+    }
+  }
+  const groups = reports.flatMap(report => groupsOf(report.data).map(group => group.map(f => projectFinding(f, report.data as Finding)!)))
+  stampSecurityGroups(groups, { linkedIds: id => edges.get(id) ?? [] })
+  const securityIds = new Set(groups.flat().filter(f => f['isSecurity'] === true).map(f => String(f['id'])))
+  const allIds = new Set<string>(), visible: Visibility = new Map()
+  for (let i = 0; i < reports.length; i++) {
+    const access = snapshot.reports[i]!, report = reports[i]!
+    report.data = filterReportData(report.data, access.permissions, access.repo, securityIds)
+    const ids = new Set<string>()
+    for (const finding of groupsOf(report.data).flat()) {
+      // Preserve linked security classification for the UI lens, including a
+      // linked component that a dependency permission will hide from the UI.
+      finding['isSecurity'] = securityIds.has(String(finding['id']))
+      if (typeof finding['id'] === 'string') { ids.add(finding['id']); allIds.add(finding['id']) }
+    }
+    visible.set(report.id, { ids, sourcePaths: managedFindingSourcePaths(groupsOf(report.data).flat()) })
+  }
+  for (const report of reports) {
+    const links = linksOf(report.data)
+    if (links) report.data = { source: 'links', findings: [], links: links.map(ids => [...new Set(ids.filter(id => allIds.has(id)))]).filter(ids => ids.length >= 2) }
+  }
+  let outputBytes = 14
+  for (const report of reports) {
+    outputBytes += Buffer.byteLength(JSON.stringify(report)) + 1
+    if (outputBytes > MAX_REPORT_QUERY_BYTES) throw new TeamReportsError(413, 'batch-too-large')
+  }
+  retainVisibility(db, teamSnapshotKey(snapshot), visible)
+  return { reports, visible }
+}
+export async function loadTeamReports(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<TeamReport[]> {
+  return (await loadTeamWorkspace(db, store, snapshot)).reports
+}
+async function teamVisibility(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<Visibility> {
+  const key = teamSnapshotKey(snapshot)
+  let visible = caches.get(db)?.get(key)
+  if (!visible) {
+    // A large snapshot may deliberately remain uncached, or be evicted by
+    // another request. Authorization uses this load's result in either case.
+    visible = (await loadTeamWorkspace(db, store, snapshot)).visible
+  }
+  return visible
+}
+export async function teamWorkspaceFindingIds(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot): Promise<Set<string>> {
+  const ids = new Set<string>()
+  for (const report of (await teamVisibility(db, store, snapshot)).values()) for (const id of report.ids) ids.add(id)
+  return ids
+}
+export async function teamReportVisibility(db: ManagedDb, store: BlobStore, snapshot: TeamReportAccessSnapshot, reportId: string): Promise<ReportVisibility> {
+  if (!snapshot.reports.some(r => r.id === reportId)) throw new TeamReportsError(404, 'no-report')
+  const visible = await teamVisibility(db, store, snapshot)
+  return visible.get(reportId)!
+}
+export async function teamFindingIds(db: ManagedDb, store: BlobStore, sessionId: string, teamId: string, reportId: string): Promise<Set<string>> {
+  const snapshot = await teamSnapshot(db, sessionId, teamId)
+  const visible = await teamReportVisibility(db, store, snapshot, reportId)
+  await recheckTeam(db, sessionId, snapshot)
+  return visible.ids
+}
+export async function teamSourcePaths(db: ManagedDb, store: BlobStore, sessionId: string, teamId: string, reportId: string): Promise<Set<string>> {
+  const snapshot = await teamSnapshot(db, sessionId, teamId)
+  const visible = await teamReportVisibility(db, store, snapshot, reportId)
+  await recheckTeam(db, sessionId, snapshot)
+  return visible.sourcePaths
+}

package/server-managed/triage-response.ts

@@ -0,0 +1,16 @@
+import type { TriageRow } from './db.ts'
+import { type TriageEntryPatch, isTriageBucket } from '../common/managed/triage.ts'
+
+// A stored triage row (current state or a trail event) → its wire entry: only
+// set fields present, `false` kept for flagged (the explicit un-flag tombstone
+// must round-trip), and null for the row of a cleared entry (every field
+// null) — the reader adopts the clear.
+export function triageWireEntry(row: Pick<TriageRow, 'color' | 'triage' | 'comment' | 'fix' | 'flagged'>, legacyHistory = false): TriageEntryPatch | null {
+  const e: TriageEntryPatch = {}
+  if (row.color != null) e.color = row.color
+  if (isTriageBucket(row.triage)) e.triage = row.triage
+  if (legacyHistory && row.comment != null) e.comment = row.comment
+  if (row.fix != null) e.fix = row.fix
+  if (row.flagged != null) e.flagged = row.flagged
+  return Object.keys(e).length > 0 ? e : null
+}