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

package/server-managed/storage-maintenance.ts

@@ -0,0 +1,259 @@
+import type { Buffer } from 'node:buffer'
+import { type StorageKey, decryptStorageStream, encryptStorageStream } from '../server-common/storage-crypto.ts'
+import { ENCRYPTED_CACHE_PREFIX, type RawObjectStorage, deleteObjects, isBlobId, openObjectVersion } from './object-storage.ts'
+import { type StorageDb, type StorageEncryptionState, type StorageMigrationRow, type StorageRow, type StorageRowKind, unwrapDataKey } from './storage-db.ts'
+import { STORAGE_UPLOAD_TTL_MS } from './storage-encryption.ts'
+import { StoragePayloadError, inspectStorageObject, masterKeyCache, storageOwner, storageRowPaths, verifiedStoragePayload, verifyStoragePayload } from './storage-payload.ts'
+
+async function replacementFailure(raw: RawObjectStorage, identity: string, version: string, signal: AbortSignal): Promise<string> {
+  const format = (value: string) => value.startsWith('W/') ? 'weak' : value.startsWith('"') && value.endsWith('"') ? 'quoted' : 'unquoted'
+  const reason = `Conditional replacement rejected (object version precondition failed); download=${format(version)}`
+  // Diagnose only failed writes. A metadata read cannot authorize a retry with
+  // a different version: the downloaded bytes must remain bound to their own.
+  let current
+  try { current = await raw.head(identity, signal) }
+  catch { return `${reason}; metadata=unavailable` }
+  if (!current) return `${reason}; metadata=missing`
+  // Normalization is diagnostic only. Never use it for conditional writes or
+  // log the actual ETags, which can contain hashes of private payloads.
+  const value = (tag: string) => tag.replace(/^W\//u, '').replace(/^"(.*)"$/u, '$1')
+  const comparison = current.version === version ? 'same' : value(current.version) === value(version) ? 'format-only' : 'different'
+  return `${reason}; metadata=${format(current.version)}; comparison=${comparison}`
+}
+
+type MigrationPhase = 'prepare-key' | 'open-payload' | 'verify-existing' | 'encrypt-upload' | 'verify-replacement' | 'checkpoint'
+async function migratePayload(raw: RawObjectStorage, db: StorageDb, type: StorageRowKind, row: StorageRow,
+  dataKey: Buffer, identity: string, signal: AbortSignal, progress: (phase: MigrationPhase) => void): Promise<boolean | string | null> {
+  progress('open-payload')
+  const source = await raw.open(identity, signal)
+  if (!source) return false
+  let inspected = await inspectStorageObject(source)
+  if (inspected.encrypted) {
+    progress('verify-existing')
+    // A previous PUT may have completed before a timeout or lost SQL ack.
+    try {
+      const decoded = await decryptStorageStream(inspected.stream, dataKey, identity)
+      await verifyStoragePayload(type, row, decoded.stream, signal, identity)
+    } catch {
+      signal.throwIfAborted()
+      // Legacy arbitrary bytes can share the magic prefix. A matching
+      // original upload hash is required before encrypting them as plaintext.
+      const legacy = await openObjectVersion(raw, identity, source.version, signal)
+      if (!legacy) return 'Payload disappeared or changed version before plaintext verification'
+      inspected = { ...legacy, encrypted: false }
+    }
+  }
+  if (!inspected.encrypted) {
+    progress('encrypt-upload')
+    signal.throwIfAborted()
+    const verified = verifiedStoragePayload(type, row, inspected.stream, signal, identity)
+    const encrypted = encryptStorageStream(verified, dataKey, identity, inspected.size)
+    let replaced: boolean
+    try { replaced = await raw.put(identity, encrypted, signal, source.version, inspected.size ?? undefined) }
+    // A provider may wrap a request-body error; keep safe payload diagnostics.
+    catch (err) { throw verified.errored ?? err }
+    finally { encrypted.destroy(); verified.destroy(); inspected.stream.destroy(); source.stream.destroy() }
+    if (!replaced) return await replacementFailure(raw, identity, source.version, signal)
+    // Do not mark the row encrypted until the stored bytes authenticate and
+    // match the original upload (including Brotli decompression).
+    progress('verify-replacement')
+    const replacement = await raw.open(identity, signal)
+    if (!replacement) {
+      if (!await db.getStorageRow(type, row.id)) return null
+      throw new StoragePayloadError('Migrated payload unavailable')
+    }
+    const decoded = await decryptStorageStream(replacement.stream, dataKey, identity)
+    await verifyStoragePayload(type, row, decoded.stream, signal, identity)
+  }
+  signal.throwIfAborted()
+  // Persist observed replacements, including both report representations
+  // if they coexist, before marking the whole row encrypted.
+  progress('checkpoint')
+  await raw.sync?.(identity, signal)
+  return true
+}
+
+async function migrateRow(raw: RawObjectStorage, db: StorageDb, key: StorageKey, item: StorageMigrationRow, signal: AbortSignal,
+  progress: (phase: MigrationPhase) => void): Promise<string | void> {
+  if (item.type === 'user') { await db.migrateStorageUserTokens(item.id); return }
+  progress('prepare-key')
+  const row = await db.ensureStorageDataKey(item.type, item.id)
+  if (!row || row.encrypted) return
+  const dataKey = unwrapDataKey(key, item.type, row)
+  try {
+    let found = false
+    for (const identity of storageRowPaths(item.type, row)) {
+      const result = await migratePayload(raw, db, item.type, row, dataKey, identity, signal, progress)
+      if (result === null) return
+      if (typeof result === 'string') return result
+      found ||= result
+    }
+    if (!found) {
+      if (!await db.getStorageRow(item.type, item.id)) return
+      throw new StoragePayloadError('Migration payload unavailable')
+    }
+    signal.throwIfAborted()
+    await db.markStorageEncrypted(item.type, item.id, row.dataKey!)
+  } finally { dataKey.fill(0) }
+}
+
+const CLEANUP_PREFIXES = ['cache/', 'reports/', 'bundles/', ENCRYPTED_CACHE_PREFIX]
+function cleanupPosition(state: StorageEncryptionState): { prefix: number; cursor: string | null } {
+  const value = state.cleanupCursor === null ? { prefix: 0, cursor: null } : JSON.parse(state.cleanupCursor)
+  if (!Number.isInteger(value.prefix) || value.prefix < 0 || value.prefix >= CLEANUP_PREFIXES.length
+    || (value.cursor !== null && typeof value.cursor !== 'string')) throw new Error('Invalid legacy cleanup cursor')
+  return value
+}
+
+// The database directory may be shared. Recognize managed paths, including
+// disk atomic-write temps, before treating any listed file as ours to remove.
+function cleanupTarget(identity: string) {
+  const temp = /^(.+)\.([^.]+)\.tmp$/u.exec(identity)
+  const temporary = !!temp && isBlobId(temp[2]!)
+  const path = temporary ? temp![1]! : identity
+  const encryptedCache = path.startsWith(ENCRYPTED_CACHE_PREFIX)
+  if (encryptedCache && !temporary) return null
+  const logical = encryptedCache ? `cache/${path.slice(ENCRYPTED_CACHE_PREFIX.length)}` : path
+  // A cache no row owns is a cache all the same: its plaintext legacy, and
+  // its temporary files removed past the staging window.
+  const owner = storageOwner(logical) ?? (masterKeyCache(logical) ? { cache: true as const } : null)
+  return owner ? { owner, temporary } : null
+}
+
+// Referenced-data migration never depends on Blob listings. A separate bounded
+// inventory removes legacy caches and unreferenced plaintext; ciphertext
+// orphans do not hold a recoverable data key and need no manifest-based GC.
+async function cleanupLegacy(raw: RawObjectStorage, db: StorageDb, state: StorageEncryptionState, limit: number, signal: AbortSignal) {
+  const position = cleanupPosition(state), prefix = CLEANUP_PREFIXES[position.prefix]!
+  const page = await raw.list(prefix, position.cursor, Math.min(limit, 16), signal)
+  let found = 0, retryAt: number | null = null
+  for (const object of page.objects) {
+    signal.throwIfAborted()
+    const target = cleanupTarget(object.key)
+    if (!target) continue
+    const { owner, temporary } = target
+    if (!temporary && !owner.cache) {
+      const row = await db.getStorageRow(owner.type, owner.id)
+      if (row && storageRowPaths(owner.type, row).includes(object.key)) continue
+    }
+    const stored = await raw.head(object.key, signal)
+    if (!stored) continue
+    // A killed disk writer can leave plaintext or ciphertext in its temp file.
+    // Recheck its current age and give live writes a full staging grace window.
+    if (temporary && stored.modifiedAt > Date.now() - STORAGE_UPLOAD_TTL_MS) {
+      found++
+      retryAt = Math.min(retryAt ?? Infinity, stored.modifiedAt + STORAGE_UPLOAD_TTL_MS)
+      continue
+    }
+    // Old pre-activation orphans are legacy even when their arbitrary bytes
+    // share the magic prefix. Keep a full staging grace window around enable:
+    // Blob Last-Modified has only second precision, and a new encrypted upload
+    // may still be waiting for its SQL insert.
+    let legacy = temporary || owner.cache || stored.modifiedAt < state.enabledAt - STORAGE_UPLOAD_TTL_MS
+    if (!legacy) {
+      const source = await raw.open(object.key, signal)
+      if (!source) continue
+      try {
+        if (source.version !== stored.version) throw new Error('Legacy object changed during cleanup')
+        const inspected = await inspectStorageObject(source)
+        legacy = !inspected.encrypted
+        inspected.stream.destroy()
+      } finally { source.stream.destroy() }
+    }
+    if (legacy) {
+      found++
+      if (!await raw.delete(object.key, stored.version, signal)) throw new Error('Legacy object changed during cleanup')
+    }
+  }
+  const next = page.cursor === null ? position.prefix + 1 < CLEANUP_PREFIXES.length ? { prefix: position.prefix + 1, cursor: null } : null
+    : { ...position, cursor: page.cursor }
+  // A full pass without removals closes offset-pagination gaps left by deletes.
+  await db.advanceStorageCleanup(state.cleanupCursor, next === null ? null : JSON.stringify(next), found)
+  return { processed: page.objects.length || 1, retryAt }
+}
+
+interface StorageMigrationResult extends StorageEncryptionState {
+  retryAt: number | null
+  failures: { type: StorageMigrationRow['type']; id: string; message: string }[]
+}
+function rowFailure(row: StorageMigrationRow, message: string) {
+  const failure = { type: row.type, id: row.id, message }
+  // Emit before continuing: a later failure or terminated invocation must not
+  // hide earlier diagnostics. Never include provider errors or storage values.
+  console.warn('managed-storage-migration-row:', JSON.stringify(failure))
+  return failure
+}
+interface MigrationOptions { maxObjects?: number; maxMs?: number | undefined; signal?: AbortSignal | undefined }
+export async function migrateStorage(raw: RawObjectStorage, db: StorageDb, key: StorageKey,
+  { maxObjects = 64, maxMs = 150_000, signal: stopping }: MigrationOptions = {}): Promise<StorageMigrationResult> {
+  if (!Number.isSafeInteger(maxObjects) || maxObjects < 1 || !Number.isSafeInteger(maxMs) || maxMs < 1) throw new Error('Invalid migration budget')
+  const deadline = Date.now() + maxMs, timeout = AbortSignal.timeout(maxMs)
+  const signal = stopping ? AbortSignal.any([stopping, timeout]) : timeout
+  const errors: unknown[] = []
+  const failures: StorageMigrationResult['failures'] = []
+  let processed = 0, retryAt: number | null = null, state = await db.getStorageEncryption()
+  if (!state) throw new Error('Storage encryption is not enabled; configure MANAGED_STORAGE_ENCRYPTION_KEY')
+  // At most one SQL pass per invocation. Checkpoint each row, including a
+  // failure: other rows progress, and the failed row is retried next pass.
+  while (!state.complete && processed < maxObjects && Date.now() < deadline && !signal.aborted) {
+    const rows = await db.listStorageMigrationRows(state.cursor, Math.min(16, maxObjects - processed))
+    if (stopping?.aborted) break
+    if (rows.length === 0) { await db.advanceStorageMigration(state.cursor, null); break }
+    for (const row of rows) {
+      if (Date.now() >= deadline || signal.aborted) break
+      console.info('managed-storage-migration-row-start:', JSON.stringify({ type: row.type, id: row.id }))
+      const startedAt = Date.now()
+      let phase: MigrationPhase | 'tokens' = 'tokens'
+      const logPhase = (aborted = false) => console.info('managed-storage-migration-row-phase:', JSON.stringify({
+        type: row.type, id: row.id, phase, elapsedMs: Date.now() - startedAt, ...(aborted ? { aborted: true } : {}),
+      }))
+      // Log directly on cancellation even if an underlying operation stalls
+      // while unwinding. These fixed phases contain no object/provider data.
+      const aborted = () => logPhase(true)
+      signal.addEventListener('abort', aborted, { once: true })
+      try {
+        const pending = await migrateRow(raw, db, key, row, signal, next => { phase = next; logPhase() })
+        if (pending) failures.push(rowFailure(row, pending))
+      }
+      catch (err) {
+        // A row started late gets a full budget next time. Skip an oversized
+        // first row until the next pass so later rows and tokens can advance.
+        if (stopping?.aborted || (signal.aborted && processed > 0)) break
+        const failure = signal.aborted
+          ? `Could not migrate ${row.type} ${row.id} within MANAGED_STORAGE_ENCRYPTION_MIGRATE_MAX_MS=${maxMs}; increase the budget`
+          : err instanceof StoragePayloadError ? err.message : null
+        if (failure === null) {
+          rowFailure(row, 'Migration operation failed')
+          errors.push(new Error(`Could not migrate ${row.type} ${row.id}`, { cause: err }))
+        } else failures.push(rowFailure(row, failure))
+      }
+      finally { signal.removeEventListener('abort', aborted) }
+      if (stopping?.aborted) break
+      await db.advanceStorageMigration(state.cursor, row.position)
+      processed++
+      state = (await db.getStorageEncryption())!
+    }
+  }
+  state = (await db.getStorageEncryption())!
+  while (!state.cleanupComplete && processed < maxObjects && Date.now() < deadline && !signal.aborted) {
+    try {
+      const cleanup = await cleanupLegacy(raw, db, state, maxObjects - processed, signal)
+      processed += cleanup.processed
+      retryAt = cleanup.retryAt
+    }
+    catch (err) { if (!signal.aborted) errors.push(err); break }
+    state = (await db.getStorageEncryption())!
+    if (retryAt !== null) break // Wait for staging grace rather than spinning over live temp files.
+  }
+  if (errors.length > 0) throw new AggregateError(errors, 'Storage migration has pending failures', { cause: errors[0] })
+  return { ...state, retryAt, failures }
+}
+
+export async function reapStorageUploads(raw: RawObjectStorage, db: StorageDb, now = Date.now(), stopping?: AbortSignal): Promise<number> {
+  if (stopping?.aborted) return 0
+  const timeout = AbortSignal.timeout(150_000)
+  const signal = stopping ? AbortSignal.any([stopping, timeout]) : timeout
+  await db.getStorageEncryption()
+  try { return await deleteObjects(raw, 'uploads/', signal, now - STORAGE_UPLOAD_TTL_MS) }
+  catch (err) { if (stopping?.aborted) return 0; throw err }
+}

package/server-managed/storage-payload.ts

@@ -0,0 +1,121 @@
+import { Buffer } from 'node:buffer'
+import { createHash } from 'node:crypto'
+import { PassThrough, Readable, Writable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import { createBrotliDecompress } from 'node:zlib'
+import { STORAGE_MAGIC } from '../server-common/storage-crypto.ts'
+import { type RawObject, isBlobId } from './object-storage.ts'
+import type { StorageRow, StorageRowKind } from './storage-db.ts'
+
+// A damaged/missing payload needs repair; retrying the whole cleanup job does
+// not fix it. Keep this distinct from database, storage and cancellation errors.
+export class StoragePayloadError extends Error {}
+
+export function storageRowPaths(type: StorageRowKind, row: Pick<StorageRow, 'id' | 'kind'>): string[] {
+  return type === 'report' ? [`reports/${row.id}.br`, `reports/${row.id}`]
+    : [`bundles/${row.id}${row.kind === 'sourcemap' ? '.map.br' : ''}`]
+}
+// A cache of public content, which no row owns, kept unencrypted as avatars
+// are: public npm versions' pretty-printed files (pretty-print.ts).
+export const PUBLIC_CACHE = 'npm'
+export const PUBLIC_CACHE_PREFIX = `cache/${PUBLIC_CACHE}/`
+// A cache of private content no row owns: the code viewer's directories at
+// repositories' default branches' heads (repository-code.ts
+// repositoryCodeKept), by repository. Plaintext while storage is not
+// encrypted, as other caches are; once it is, kept apart under
+// ENCRYPTED_CACHE_PREFIX as a bundle's caches are, so that what was kept
+// before is never read and legacy cleanup removes it, and encrypted with the
+// master key, as upload parts are, each write's key derived from its path,
+// so that one path's ciphertext fails to authenticate at another. No storage
+// row holds a repository's code for a data key of its own to be wrapped in:
+// its selection is none, and stays as it is deactivated. A key of its own
+// would add a column and its migration only for its deletion to make what is
+// left unreadable at once, as a deleted bundle's caches are; here deletion
+// is physical, by the repository's prefix, at best, as an upload part's is,
+// and what a failed one leaves is a directory as GitHub has it at a commit,
+// read only by a reader GitHub lets read that repository.
+export const REPOSITORY_CODE_CACHE = 'repository-code'
+const REPOSITORY_CODE_CACHE_PREFIX = `cache/${REPOSITORY_CODE_CACHE}/`
+export const masterKeyCache = (identity: string) => identity.startsWith(REPOSITORY_CODE_CACHE_PREFIX)
+export function storageOwner(identity: string): { type: StorageRowKind; id: string; cache: boolean } | null {
+  const match = /^(reports|bundles)\/([^/]+)$/u.exec(identity)
+  if (match) {
+    const id = match[2]!.replace(match[1] === 'bundles' ? /\.map\.br$/u : /\.br$/u, '')
+    if (isBlobId(id)) return { type: match[1] === 'reports' ? 'report' : 'bundle', id, cache: false }
+  }
+  const cache = /^cache\/(?:bundles|report-sources)\/([a-f\d-]{36})\//u.exec(identity)
+  return cache && isBlobId(cache[1]!) ? { type: 'bundle', id: cache[1]!, cache: true } : null
+}
+
+// Peek without buffering the object or consuming bytes from its next reader.
+export async function inspectStorageObject(stored: RawObject): Promise<RawObject & { encrypted: boolean }> {
+  const original = stored.stream
+  const iterator = original[Symbol.asyncIterator]()
+  const first: Buffer[] = [], prefix = Buffer.alloc(STORAGE_MAGIC.length)
+  let length = 0
+  try {
+    while (length < prefix.length) {
+      const next = await iterator.next()
+      if (next.done) break
+      const bytes = Buffer.from(next.value)
+      first.push(bytes)
+      length += bytes.copy(prefix, length, 0, prefix.length - length)
+    }
+  } catch (err) { original.destroy(); throw err }
+  async function* joined() {
+    try {
+      yield* first
+      for (;;) { const next = await iterator.next(); if (next.done) return; yield next.value }
+    } finally { await iterator.return?.(); original.destroy() }
+  }
+  const stream = Readable.from(joined(), { objectMode: false })
+  stream.once('close', () => original.destroy())
+  return { ...stored, stream, encrypted: length === prefix.length && prefix.equals(STORAGE_MAGIC) }
+}
+
+// Report hashes and sourcemap integrity describe the original upload, before Brotli storage.
+// Hash incrementally, including decompression, so migration stays streaming.
+export async function verifyStoragePayload(type: StorageRowKind, row: StorageRow, source: Readable, signal?: AbortSignal, identity?: string): Promise<void> {
+  const hash = createHash(type === 'report' ? 'sha256' : 'sha512')
+  const sink = new Writable({ write(chunk, _encoding, next) { hash.update(chunk); next() } })
+  const options = signal ? { signal } : {}
+  try {
+    if (type === 'bundle' && row.kind === 'sourcemap' || type === 'report' && identity?.endsWith('.br')) {
+      await pipeline(source, createBrotliDecompress(), sink, options)
+    } else await pipeline(source, sink, options)
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code ?? ''
+    if (['Z_DATA_ERROR', 'Z_BUF_ERROR'].includes(code) || code.startsWith('ERR__ERROR_FORMAT_')) {
+      throw new StoragePayloadError(`Stored ${type === 'report' ? 'report' : 'sourcemap'} cannot be decompressed`, { cause: err })
+    }
+    throw err
+  }
+  const actual = type === 'report' ? hash.digest('base64url') : `sha512-${hash.digest('base64')}`
+  if (actual !== row.hash) throw new StoragePayloadError('Stored payload does not match its upload hash')
+}
+
+// Forward the stored representation with backpressure, but withhold EOF until
+// its upload hash passes. Encryption cannot emit its final frame, and an atomic
+// PUT cannot commit, until verification (including Brotli decompression) ends.
+export function verifiedStoragePayload(type: StorageRowKind, row: StorageRow, source: Readable, signal?: AbortSignal, identity?: string): Readable {
+  const input = new PassThrough(), output = new PassThrough()
+  const verification = verifyStoragePayload(type, row, input, signal, identity)
+  // Propagate asynchronous decompression errors even if the source is stalled.
+  void verification.catch(err => { source.destroy(err); output.destroy(err) })
+  const forwarding = pipeline(source, async function* (chunks) {
+    try {
+      for await (const chunk of chunks) {
+        await new Promise<void>((resolve, reject) => { input.write(chunk, err => err ? reject(err) : resolve()) })
+        yield chunk
+      }
+      input.end()
+      await verification
+    } finally {
+      input.destroy()
+      await verification.catch(() => {})
+    }
+  }, output, signal ? { signal } : {})
+  // pipeline forwards errors to output and tears down input on early cancellation.
+  void forwarding.catch(() => {})
+  return output
+}

package/server-managed/storage-stores.ts

@@ -0,0 +1,91 @@
+// Logical stores share one encryption boundary. Compression, identifiers and
+// public response bytes stay the same with either physical backend.
+import { Buffer } from 'node:buffer'
+import type { AvatarStore } from './avatar-store.ts'
+import type { BlobStore } from './blob-store.ts'
+import type { BundleCacheStorage } from './bundle-cache.ts'
+import { createBundleStore } from './bundle-store.ts'
+import { createReportStore } from './report-store.ts'
+import { CacheMissError, type CacheStorage, validateCacheKey } from './cache-storage.ts'
+import { type ObjectStorage, isBlobId } from './object-storage.ts'
+import { PUBLIC_CACHE, REPOSITORY_CODE_CACHE } from './storage-payload.ts'
+
+function id(value: string): string {
+  if (!isBlobId(value)) throw new Error('Invalid managed blob id')
+  return value
+}
+
+function blobStore(objects: ObjectStorage, name: string, suffix = ''): BlobStore {
+  const path = (value: string) => `${name}/${id(value)}${suffix}`
+  return {
+    put: (value, bytes) => objects.put(path(value), bytes),
+    get: value => objects.get(path(value)),
+    open: value => objects.open(path(value)),
+    delete: value => objects.delete(path(value)),
+  }
+}
+
+function cacheStore(objects: ObjectStorage, name: string): CacheStorage {
+  const path = (key: string) => `cache/${name}/${validateCacheKey(key)}`
+  return {
+    exists: key => objects.exists(path(key)),
+    put: async (key, bytes) => { await objects.put(path(key), bytes) },
+    async open(key) {
+      const value = await objects.open(path(key))
+      if (!value) throw new CacheMissError()
+      return value
+    },
+    delete: (prefix, keep) => objects.deletePrefix(`${path(prefix)}/`, keep === undefined ? undefined : `${path(`${prefix}/${keep}`)}/`),
+  }
+}
+
+function avatarStore(objects: ObjectStorage, sidecar: boolean): AvatarStore {
+  return {
+    async put(value, contentType, bytes) {
+      const path = `avatars/${id(value)}`, type = contentType.split(';', 1)[0]!.trim()
+      if (!/^image\/[a-z0-9.+-]+$/iu.test(type)) throw new Error('Invalid avatar type')
+      if (sidecar) {
+        await objects.put(path, bytes)
+        await objects.put(`${path}.type`, Buffer.from(type))
+      } else await objects.put(path, Buffer.concat([Buffer.from(`${type}\n`), bytes]))
+    },
+    async get(value) {
+      const path = `avatars/${id(value)}`
+      const bytes = await objects.get(path)
+      if (!bytes) return null
+      if (sidecar) {
+        const type = await objects.get(`${path}.type`)
+        return type ? { bytes, contentType: type.toString().trim() || 'application/octet-stream' } : 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) }
+    },
+    async delete(value) {
+      const path = `avatars/${id(value)}`
+      await objects.delete(path)
+      if (sidecar) await objects.delete(`${path}.type`)
+    },
+  }
+}
+
+export function createManagedStores(objects: ObjectStorage, avatarSidecar: boolean) {
+  const bundles = cacheStore(objects, 'bundles')
+  const cacheStorage: BundleCacheStorage = {
+    exists: (value, file) => bundles.exists(`${id(value)}/${file}`),
+    put: (value, file, bytes) => bundles.put(`${id(value)}/${file}`, bytes),
+    open: (value, file) => bundles.open(`${id(value)}/${file}`),
+    delete: value => bundles.delete(id(value)),
+  }
+  return {
+    reportStore: createReportStore(blobStore(objects, 'reports'), blobStore(objects, 'reports', '.br'),
+      (value, bytes) => objects.put(`reports/${id(value)}.br`, bytes, { replaceReport: true })),
+    bundleStore: createBundleStore(blobStore(objects, 'bundles'), blobStore(objects, 'bundles', '.map.br')),
+    uploadStore: blobStore(objects, 'uploads'),
+    avatarStore: avatarStore(objects, avatarSidecar),
+    cacheStorage,
+    reportSourcesStorage: cacheStore(objects, 'report-sources'),
+    npmCacheStorage: cacheStore(objects, PUBLIC_CACHE),
+    repositoryCodeStorage: cacheStore(objects, REPOSITORY_CODE_CACHE),
+  }
+}

package/server-managed/storage.ts

@@ -0,0 +1,82 @@
+// Backend selection is shared by standalone, combined and function entrypoints.
+import { dirname } from 'node:path'
+import { parseStorageKey } from '../server-common/storage-crypto.ts'
+import { createBundleCache } from './bundle-cache.ts'
+import { createPrettyCache, stalePrettyRemover } from './pretty-print.ts'
+import { createReportSourcesCache } from './report-sources.ts'
+import { openNeonManagedDb } from './db-neon.ts'
+import type { ManagedConfig } from './config.ts'
+import { createEncryptedObjectStorage } from './storage-encryption.ts'
+import { createManagedStores } from './storage-stores.ts'
+import { createDiskObjectStorage } from './object-storage-disk.ts'
+import { openVercelObjectStorage } from './object-storage-vercel.ts'
+import { migrateStorage, reapStorageUploads } from './storage-maintenance.ts'
+
+// Database-only callers (notably status) must not activate byte encryption.
+export async function openManagedStorageDb(config: ManagedConfig) {
+  const options = { triageHistoryLimit: config.triageHistoryLimit, storageEncryptionKey: parseStorageKey(config.storageEncryptionKey) }
+  if (!config.neonUrl) return (await import('./db.ts')).openSqliteManagedDb(config.dbPath, options)
+  // Serverless instances hold pooled connections only while an invocation lasts.
+  const attachPool = config.serverless ? (await import('@vercel/functions')).attachDatabasePool : undefined
+  return openNeonManagedDb(config.neonUrl, options, attachPool)
+}
+
+export async function openManagedStorage(config: ManagedConfig) {
+  const key = parseStorageKey(config.storageEncryptionKey)
+  if (config.storageEncryptionMigrate && !key) throw new Error('MANAGED_STORAGE_ENCRYPTION_MIGRATE requires MANAGED_STORAGE_ENCRYPTION_KEY')
+  if (config.neonUrl && !config.blobToken) throw new Error('Managed Neon mode requires BLOB_READ_WRITE_TOKEN')
+  if (config.serverless && !config.neonUrl) throw new Error('Serverless managed storage requires Neon')
+  const db = await openManagedStorageDb(config)
+  try {
+    const raw = config.neonUrl ? await openVercelObjectStorage(config.blobToken!) : createDiskObjectStorage(dirname(config.dbPath))
+    // Enable before exposing stores or token writers. Concurrent first starts
+    // serialize activation in the database and validate the winning key.
+    const enabled = key ? await db.getStorageEncryption() : null
+    if (key && !enabled) {
+      if (config.vercelPreview) throw new Error('Storage encryption must be enabled outside a Vercel preview deployment')
+      await db.enableStorageEncryption()
+    }
+    // Enabled already: that state, not read again.
+    const objects = await createEncryptedObjectStorage(raw, db, key, enabled)
+    const storage = createManagedStores(objects, !config.neonUrl)
+    // Move legacy team link uploads into encrypted SQL before serving catalogs.
+    // The DB transaction commits first; a failed blob cleanup cannot lose links.
+    for (const report of await db.listLegacyLinkReports()) {
+      if (!key) throw new Error('Migrating managed link reports requires MANAGED_STORAGE_ENCRYPTION_KEY')
+      let bytes
+      try { bytes = await storage.reportStore.get(report.id) } catch (error) {
+        if (!await db.getReport(report.id)) continue // another instance completed migration
+        throw error
+      }
+      if (!bytes) {
+        if (!await db.getReport(report.id)) continue
+        throw new Error(`Missing legacy link report: ${report.id}`)
+      }
+      if (await db.migrateLinkReport(report.id, bytes.toString('utf8'))) {
+        await storage.reportStore.delete(report.id).catch(error => console.warn('managed: legacy link cleanup failed:', error))
+      }
+    }
+    const bundleCache = createBundleCache(storage.cacheStorage, db, storage.bundleStore)
+    return { ...storage, db, uploadStore: config.neonUrl ? storage.uploadStore : undefined, bundleCache,
+      reportSourcesCache: createReportSourcesCache(storage.reportSourcesStorage, db, storage.reportStore, storage.bundleStore, bundle => bundleCache.sourcemapEdges(bundle)),
+      prettyCache: createPrettyCache(storage.cacheStorage, storage.npmCacheStorage, db, storage.bundleStore),
+      reapPrettyCopies: stalePrettyRemover(storage.npmCacheStorage),
+      async reapStorage(signal?: AbortSignal) {
+        if (!config.storageEncryptionMigrate || signal?.aborted) return
+        const state = await db.getStorageEncryption()
+        if (state?.complete && state.cleanupComplete) return
+        console.info('managed-storage-migration-start:', JSON.stringify({ migrated: state?.migrated, cursor: state?.cursor }))
+        const result = await migrateStorage(raw, db, key!, { maxMs: config.storageEncryptionMigrateMaxMs, signal })
+        console.info('managed-storage-migration:', JSON.stringify({
+          complete: result.complete === 1, cleanupComplete: result.cleanupComplete === 1,
+          migrated: result.migrated, cursor: result.cursor, retryAt: result.retryAt,
+          failed: result.failures.length, cancelled: signal?.aborted === true,
+        }))
+      },
+      ...(config.neonUrl ? { reapUploads: (signal?: AbortSignal) => reapStorageUploads(raw, db, Date.now(), signal) } : {}),
+    }
+  } catch (err) {
+    await db.close()
+    throw err
+  }
+}