@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.51

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/solidity-entry-points.ts

@@ -0,0 +1,71 @@
+import { normalizeTeamPath } from './repo-path.ts'
+
+const MAX_SUGGESTIONS = 100
+const EXCLUDED_DIRECTORIES = new Set(['test', 'tests', 'script', 'scripts', 'mock', 'mocks', 'node_modules', 'vendor', 'out', 'artifacts', 'cache', 'build', 'dist', 'broadcast'])
+
+function sourcePath(value: unknown): value is string {
+  if (typeof value !== 'string' || !value.endsWith('.sol') || /\.(?:t|s|test|spec)\.sol$/iu.test(value)) return false
+  const normalized = normalizeTeamPath(value)
+  const directories = value.split('/').slice(0, -1).map(part => part.toLowerCase())
+  const sourceRoot = directories.findIndex(part => part === 'src' || part === 'contracts')
+  return normalized.ok && normalized.path === value && !directories.some((part, index) =>
+    EXCLUDED_DIRECTORIES.has(part) || (part === 'lib' && (sourceRoot < 0 || index < sourceRoot)))
+}
+
+type ListingEntry = { name?: unknown; path?: unknown; type?: unknown; sha?: unknown; submodule_git_url?: unknown }
+
+// Maintain the alphabetically first 100 unique candidates even when GitHub's
+// input is unordered. Return whether a unique candidate exceeds the capacity.
+export function addSoliditySuggestion(paths: string[], path: string): boolean {
+  let start = 0
+  let end = paths.length
+  while (start < end) {
+    const middle = Math.floor((start + end) / 2)
+    if (paths[middle]! < path) start = middle + 1
+    else end = middle
+  }
+  if (paths[start] === path) return false
+  const full = paths.length === MAX_SUGGESTIONS
+  if (start < MAX_SUGGESTIONS) {
+    // Evict before inserting, so retained candidates never exceed the cap.
+    if (full) paths.pop()
+    paths.splice(start, 0, path)
+  }
+  return full
+}
+
+// Suggestions from filenames, not deployability or import analysis. Read at
+// most two source trees, using SHAs from the authorized pinned directory.
+export async function readSolidityEntryPoints(directory: string, listing: unknown[], read: (suffix: string) => Promise<unknown>) {
+  const prefix = directory ? directory + '/' : ''
+  const entries = listing.filter((entry): entry is ListingEntry => !!entry && typeof entry === 'object').filter(entry =>
+    typeof entry.name === 'string' && !entry.name.includes('/') && entry.path === prefix + entry.name && !entry.submodule_git_url)
+  const hasFramework = entries.some(entry => entry.type === 'file' && typeof entry.name === 'string'
+    && (entry.name === 'foundry.toml' || /^hardhat\.config\.(?:[cm]?js|ts)$/u.test(entry.name)))
+  const roots = entries.filter(entry => entry.type === 'dir' && (entry.name === 'contracts' || (hasFramework && entry.name === 'src'))
+    && typeof entry.sha === 'string' && /^[a-f\d]{40}$/iu.test(entry.sha)).slice(0, 2)
+  const paths: string[] = []
+  let limited = false
+  for (const entry of entries) {
+    if (entry.type === 'file' && sourcePath(entry.path) && addSoliditySuggestion(paths, entry.path)) limited = true
+  }
+  // Both roots' listings asked together, then read in order.
+  const listings = roots.map(root => Promise.resolve().then(() => (sourcePath(`${root.path}/Contract.sol`) ? read(`/git/trees/${root.sha}?recursive=1`) : null)))
+  for (const listed of listings) listed.catch(() => {})
+  for (const [i, root] of roots.entries()) {
+    try {
+      const data = await listings[i] as { tree?: unknown; truncated?: unknown } | null
+      if (!Array.isArray(data?.tree)) continue
+      limited ||= data.truncated === true
+      for (const entry of data.tree) {
+        if (entry?.type !== 'blob' || !['100644', '100755'].includes(entry.mode) || typeof entry.path !== 'string') continue
+        const path = `${root.path}/${entry.path}`
+        if (sourcePath(path) && addSoliditySuggestion(paths, path)) limited = true
+      }
+    } catch {
+      // Optional suggestions must not block browsing. The request handler
+      // rechecks GitHub access and local path grants after all reads.
+    }
+  }
+  return { paths, limited }
+}

package/server-managed/sql-postgres.ts

@@ -0,0 +1,34 @@
+// 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("CAST(unixepoch('subsec') * 1000 AS INTEGER)", 'CAST(EXTRACT(EPOCH FROM clock_timestamp()) * 1000 AS BIGINT)')
+    .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(')
+    // Rows gathered as one JSON array value, NULL (not '[]') where none are.
+    .replaceAll(/\bjson_group_array\(/gu, 'json_agg(')
+    .replaceAll(/\bjson_object\(/gu, 'json_build_object(')
+  // 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,88 @@
+// Each public store operation owns a transaction. SQLite serializes access to
+// its single connection across awaits; Neon can reuse a request-owned connection.
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite'
+import type { ManagedDb } from './db-methods.ts'
+import { countStatement, timed } from './request-timing.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>, options?: { lock?: boolean; statement?: boolean }): Promise<T>
+}
+
+// These operations execute exactly one SQL statement. Postgres already gives
+// that statement an atomic snapshot; an explicit BEGIN/COMMIT adds only trips.
+// Lease and cache writes coordinate through their conditional UPSERT/UPDATE alone.
+const SINGLE_STATEMENTS = new Set(['getReport', 'getBundle', 'getStorageRow', 'getStorageEncryption', 'getTeam', 'getComment',
+  'userCanReadReport', 'userCanReadRepo', 'userCanReadRepoPath', 'userCanReadBundle', 'reportPermissionsFor', 'listComments', 'listManagedIssues',
+  'listTriageHistory', 'listUsers', 'listUserOptions', 'listActivityReports', 'getRepoFullName', 'getUser', 'getSessionWithUser', 'getViewSessionWithUser',
+  'listTriageFixes', 'getRepoDependencyReviews', 'listTeamDependencyReviews', 'getNpmReviewReader',
+  'listDependencyReviewTeams', 'listDependencyReviewEnabledTeams', 'listUserNpmScopes', 'listTeamNpmScopes', 'hasTeamNpmScope',
+  'listGithubMetadata', 'listGithubRepositoryVisibility', 'setGithubMetadata', 'recordGithubMetadataAttempts', 'setGithubRepositoryVisibility',
+  'listLinkReports', 'listLegacyLinkReports', 'listReportFilenamesWithBundleHash', 'listReportsForRepo', 'listBundlesForRepo',
+  'listFindingCatalogReports', 'userCanReadBundleAdvisories',
+  'sessionWithUser', 'getTeamReportAccessSnapshot', 'getReportAccessSnapshot', 'getBundleAccessSnapshot', 'getReportView', 'getUserGithubId', 'getUserTeamFeedSnapshot', 'getAnnotations', 'getAnnotationRevision', 'getUserTokens',
+  'listReports', 'listBundles', 'listReadableBundleIds', 'listAllRepos', 'listSelectedRepos', 'listRepoScopesForUser', 'listTriage',
+  'getFeedState', 'getWorkspaceShareFeedState', 'claimMaintenanceLease', 'finishMaintenanceLease', 'cacheRepoDefaultBranch', 'releaseBundleBuildLease',
+  'getUpstreamCacheEntry', 'getUpstreamCacheEntries', 'getFirstUpstreamCacheEntries', 'setUpstreamCacheEntry', 'setUpstreamCacheEntries', 'ensureSessionUploadKey',
+  'listGithubCommits', 'listGithubCommitTags', 'setGithubCommits', 'getAvatarKey', 'listUsersByAccount'])
+// Session presence and upload keys change only their own rows.
+const UNLOCKED_WRITES = new Set(['sessionWithUser', 'viewSessionWithUser', 'ensureSessionUploadKey'])
+
+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|has|userCanRead|reportPermissionsFor)/u.test(name)
+    // Each operation's time told in its request's Server-Timing (request-timing.ts).
+    return [name, (...args: unknown[]) => timed('db', () => driver.scope(write, () => method(...args), {
+      // Presence writes only one user's timestamp; they need no application
+      // writer lock. Keep the session/user read and timestamp in one transaction.
+      lock: write && !UNLOCKED_WRITES.has(name), statement: SINGLE_STATEMENTS.has(name),
+    }))]
+  })
+  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) => { countStatement(); return stmt.get(...args as SQLInputValue[]) },
+        all: (...args) => { countStatement(); return stmt.all(...args as SQLInputValue[]) },
+        run: (...args) => { countStatement(); return stmt.run(...args as SQLInputValue[]) },
+      }
+    },
+    scope(write, work) {
+      if (closed) return Promise.reject(new Error('Managed database is closed'))
+      return enqueue(async () => {
+        countStatement()
+        db.exec(write ? 'BEGIN IMMEDIATE' : 'BEGIN')
+        try {
+          const result = await work()
+          countStatement()
+          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-command.ts

@@ -0,0 +1,16 @@
+import { loadManagedConfig } from './config.ts'
+import { openManagedStorageDb } from './storage.ts'
+
+// Require the deployment mode: DB_PATH belongs to e2e in combined deployments.
+// Read the database requirement without opening bytes or enabling encryption.
+export async function storageCommand(mode: string | undefined): Promise<void> {
+  if (mode !== 'managed' && mode !== 'managed-e2e' && mode !== 'e2e-managed') throw new Error('Storage status requires a deployment mode: --storage-encryption-status managed|managed-e2e|e2e-managed')
+  const db = await openManagedStorageDb(loadManagedConfig({ combined: mode !== 'managed' }))
+  try {
+    const status = await db.getStorageEncryption()
+    console.log(JSON.stringify(status ? {
+      encryption: 'chacha20-poly1305', complete: status.complete === 1, cleanupComplete: status.cleanupComplete === 1,
+      migrated: status.migrated, cursor: status.cursor,
+    } : { encryption: 'disabled' }))
+  } finally { await db.close() }
+}

package/server-managed/storage-db.ts

@@ -0,0 +1,183 @@
+// Keys belong to the existing upload rows. Only installation state and bounded
+// migration progress need a separate table; payload paths never move.
+import { Buffer } from 'node:buffer'
+import { randomBytes } from 'node:crypto'
+import { type StorageKey, unwrapStorageValue, wrapStorageValue } from '../server-common/storage-crypto.ts'
+import type { ManagedSql } from './sql.ts'
+
+export const STORAGE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_storage_encryption (
+  id INTEGER PRIMARY KEY CHECK (id = 1), test_value TEXT NOT NULL,
+  enabled_at INTEGER NOT NULL, cursor TEXT, complete INTEGER NOT NULL DEFAULT 0,
+  migrated INTEGER NOT NULL DEFAULT 0, cleanup_cursor TEXT,
+  cleanup_found INTEGER NOT NULL DEFAULT 0, cleanup_complete INTEGER NOT NULL DEFAULT 0
+) STRICT;
+`
+const SENTINEL = Buffer.from('deepview.storage.required.v1')
+export type StorageRowKind = 'report' | 'bundle'
+export interface StorageEncryptionState {
+  enabledAt: number; cursor: string | null; complete: number; migrated: number
+  cleanupCursor: string | null; cleanupFound: number; cleanupComplete: number
+}
+export interface StorageRow {
+  id: string; dataKey: string | null; encrypted: number; hash: string; kind: string | null
+}
+export interface StorageMigrationRow { position: string; id: string; type: StorageRowKind | 'user' }
+export interface StorageDb {
+  enableStorageEncryption(): Promise<StorageEncryptionState>
+  getStorageEncryption(): Promise<StorageEncryptionState | null>
+  getStorageRow(type: StorageRowKind, id: string): Promise<StorageRow | null>
+  ensureStorageDataKey(type: StorageRowKind, id: string): Promise<StorageRow | null>
+  markStorageEncrypted(type: StorageRowKind, id: string, dataKey: string): Promise<void>
+  listStorageMigrationRows(after: string | null, limit: number): Promise<StorageMigrationRow[]>
+  advanceStorageMigration(expected: string | null, next: string | null): Promise<void>
+  advanceStorageCleanup(expected: string | null, next: string | null, removed: number): Promise<void>
+  migrateStorageUserTokens(id: string): Promise<void>
+}
+
+function table(type: StorageRowKind): string {
+  if (type !== 'report' && type !== 'bundle') throw new Error('Invalid storage row type')
+  return `managed_${type}`
+}
+export const dataKeyIdentity = (type: StorageRowKind, id: string): string => `${table(type)}:${id}`
+export function unwrapDataKey(key: StorageKey, type: StorageRowKind, row: Pick<StorageRow, 'id' | 'dataKey'>): Buffer {
+  if (!row.dataKey) throw new Error('Missing storage data key')
+  const value = unwrapStorageValue(key, dataKeyIdentity(type, row.id), row.dataKey)
+  if (value.length !== 32) { value.fill(0); throw new Error('Invalid storage data key') }
+  return value
+}
+
+// What storageState reads of managed_storage_encryption, as `alias` names it,
+// for a statement reading it with more (storageStateOf).
+export const storageStateColumns = (alias: string) => `${alias}.test_value AS testValue, ${alias}.enabled_at AS enabledAt,
+  ${alias}.cursor AS cursor, ${alias}.complete AS complete, ${alias}.migrated AS migrated, ${alias}.cleanup_cursor AS cleanupCursor,
+  ${alias}.cleanup_found AS cleanupFound, ${alias}.cleanup_complete AS cleanupComplete`
+export async function storageState(db: ManagedSql, key: StorageKey | null): Promise<StorageEncryptionState | null> {
+  return storageStateOf(await db.prepare(`SELECT ${storageStateColumns('e')} FROM managed_storage_encryption e WHERE e.id = 1`).get() as StoredState | undefined, key)
+}
+type StoredState = StorageEncryptionState & { testValue: string }
+// The state storageStateColumns read, none where its row is missing, its
+// test value checked against `key`.
+export function storageStateOf(row: StoredState | undefined, key: StorageKey | null): StorageEncryptionState | null {
+  if (!row) return null
+  if (!key) throw new Error('Managed storage requires its configured encryption key')
+  const plain = unwrapStorageValue(key, 'managed_storage_encryption:1', row.testValue)
+  try { if (!plain.equals(SENTINEL)) throw new Error('Invalid storage encryption test value') }
+  finally { plain.fill(0) }
+  const { testValue: _testValue, ...state } = row
+  return state
+}
+
+// Called inside the insert transaction, fencing an old/plain upload that raced
+// activation. The wrapped key never enters public report/bundle DTOs.
+export async function validateStorageUpload(db: ManagedSql, key: StorageKey | null, type: StorageRowKind,
+  id: string, dataKey: string | null | undefined): Promise<void> {
+  const state = await storageState(db, key)
+  if (state) unwrapDataKey(key!, type, { id, dataKey: dataKey ?? null }).fill(0)
+  else if (dataKey) throw new Error('Storage encryption is not enabled')
+}
+
+export interface StoredTokens { access: string | null; refresh: string | null; exp: number | null; encrypted: number }
+const tokenIdentity = (id: string, field: string) => `managed_user.gh_${field}_token:${id}`
+export function encodeStorageTokens(key: StorageKey, id: string, access: string | null, refresh: string | null) {
+  const encode = (field: string, value: string | null) => value === null ? null : wrapStorageValue(key, tokenIdentity(id, field), Buffer.from(value))
+  return { access: encode('access', access), refresh: encode('refresh', refresh) }
+}
+export function decodeStorageTokens(key: StorageKey, id: string, row: StoredTokens) {
+  const decode = (field: string, value: string | null) => {
+    if (value === null) return null
+    const plain = unwrapStorageValue(key, tokenIdentity(id, field), value)
+    try { return plain.toString('utf8') } finally { plain.fill(0) }
+  }
+  return { access: decode('access', row.access), refresh: decode('refresh', row.refresh) }
+}
+
+// Fixed-width sizes make the saved position sort by type, then numeric byte
+// size, then ID in both SQLite and Postgres. Sixteen digits cover JS safe sizes.
+const PADDED_SIZE = "substr('0000000000000000', 1, 16 - length(CAST(byte_size AS TEXT))) || CAST(byte_size AS TEXT)"
+const PENDING = `SELECT '0:' || ${PADDED_SIZE} || ':' || id AS position, id, 'report' AS type FROM managed_report WHERE storage_encrypted = 0
+  UNION ALL SELECT '1:' || ${PADDED_SIZE} || ':' || id AS position, id, 'bundle' AS type FROM managed_bundle WHERE storage_encrypted = 0
+  UNION ALL SELECT '2:0000000000000000:' || id AS position, id, 'user' AS type FROM managed_user
+    WHERE gh_tokens_encrypted = 0 AND (gh_access_token IS NOT NULL OR gh_refresh_token IS NOT NULL)`
+
+// Restart the pending pass for a cursor saved under the previous ID ordering.
+// Completed rows are excluded by PENDING; the original cursor still fences CAS.
+const orderedCursor = (cursor: string | null): string => cursor && /^[012]:[0-9]{16}:/u.test(cursor) ? cursor : ''
+
+export function storageMethods(db: ManagedSql, key: StorageKey | null): StorageDb {
+  async function requireEnabled() {
+    const state = await storageState(db, key)
+    if (!state) throw new Error('Storage encryption is not enabled; configure MANAGED_STORAGE_ENCRYPTION_KEY')
+    return state
+  }
+  async function getRow(type: StorageRowKind, id: string): Promise<StorageRow | null> {
+    const row = await db.prepare(`SELECT id, data_key AS dataKey, storage_encrypted AS encrypted,
+      ${type === 'report' ? 'sha256 AS hash, NULL AS kind' : 'integrity AS hash, kind'} FROM ${table(type)} WHERE id = ?`).get(id) as StorageRow | undefined ?? null
+    if (row && row.encrypted !== 0 && row.encrypted !== 1) throw new Error('Invalid storage encryption state')
+    if (row?.encrypted && !row.dataKey) throw new Error('Encrypted storage row is missing its data key')
+    return row
+  }
+  return {
+    async enableStorageEncryption() {
+      if (!key) throw new Error('Set MANAGED_STORAGE_ENCRYPTION_KEY before enabling storage encryption')
+      // Called during startup in a writer transaction. Concurrent instances
+      // must reuse the marker and validate its key before serving requests.
+      const existing = await storageState(db, key)
+      if (existing) return existing
+      await db.prepare('INSERT INTO managed_storage_encryption (id, test_value, enabled_at) VALUES (1, ?, ?)')
+        .run(wrapStorageValue(key, 'managed_storage_encryption:1', SENTINEL), Date.now())
+      return (await storageState(db, key))!
+    },
+    getStorageEncryption: () => storageState(db, key),
+    getStorageRow: getRow,
+    async ensureStorageDataKey(type, id) {
+      await requireEnabled()
+      const current = await getRow(type, id)
+      if (!current || current.dataKey) return current
+      const bytes = randomBytes(32)
+      let wrapped: string
+      try { wrapped = wrapStorageValue(key!, dataKeyIdentity(type, id), bytes) } finally { bytes.fill(0) }
+      await db.prepare(`UPDATE ${table(type)} SET data_key = ? WHERE id = ? AND data_key IS NULL`).run(wrapped, id)
+      // Return the persisted winner, never a worker's uncommitted candidate.
+      return getRow(type, id)
+    },
+    async markStorageEncrypted(type, id, wrapped) {
+      await requireEnabled()
+      const result = await db.prepare(`UPDATE ${table(type)} SET storage_encrypted = 1
+        WHERE id = ? AND data_key = ? AND storage_encrypted = 0`).run(id, wrapped)
+      if (Number(result.changes)) await db.prepare('UPDATE managed_storage_encryption SET migrated = migrated + 1 WHERE id = 1').run()
+    },
+    async listStorageMigrationRows(after, limit) {
+      await requireEnabled()
+      return await db.prepare(`SELECT position, id, type FROM (${PENDING}) AS pending
+        WHERE position > ? ORDER BY position LIMIT ?`).all(orderedCursor(after), limit) as StorageMigrationRow[]
+    },
+    async advanceStorageMigration(expected, next) {
+      await requireEnabled()
+      if (next !== null && next <= orderedCursor(expected)) return
+      // End-of-pass completion checks every pending row, including failed rows
+      // before the cursor. A failure cannot be mistaken for a finished pass.
+      await db.prepare(`UPDATE managed_storage_encryption SET cursor = ?, complete =
+        CASE WHEN ? IS NULL AND NOT EXISTS (SELECT 1 FROM (${PENDING}) AS pending) THEN 1 ELSE 0 END
+        WHERE id = 1 AND (cursor = ? OR (cursor IS NULL AND ? IS NULL))`).run(next, next, expected, expected)
+    },
+    async advanceStorageCleanup(expected, next, removed) {
+      const state = await requireEnabled()
+      const found = state.cleanupFound + removed
+      await db.prepare(`UPDATE managed_storage_encryption SET cleanup_cursor = ?, cleanup_found = ?, cleanup_complete = ?
+        WHERE id = 1 AND (cleanup_cursor = ? OR (cleanup_cursor IS NULL AND ? IS NULL))`).run(next, next === null ? 0 : found, next === null && found === 0 ? 1 : 0, expected, expected)
+    },
+    async migrateStorageUserTokens(id) {
+      await requireEnabled()
+      const row = await db.prepare(`SELECT gh_access_token AS access, gh_refresh_token AS refresh, gh_token_expires_at AS exp,
+        gh_tokens_encrypted AS encrypted FROM managed_user WHERE id = ?`).get(id) as StoredTokens | undefined
+      if (!row || row.encrypted || (row.access === null && row.refresh === null)) return
+      const value = encodeStorageTokens(key!, id, row.access, row.refresh)
+      // This operation holds the writer transaction; token refresh cannot be
+      // overwritten by a migration that read an earlier token value.
+      await db.prepare('UPDATE managed_user SET gh_access_token = ?, gh_refresh_token = ?, gh_tokens_encrypted = 1 WHERE id = ?')
+        .run(value.access, value.refresh, id)
+      await db.prepare('UPDATE managed_storage_encryption SET migrated = migrated + 1 WHERE id = 1').run()
+    },
+  }
+}