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

package/server-managed/storage-encryption.ts

@@ -0,0 +1,290 @@
+import { Buffer } from 'node:buffer'
+import { randomBytes } from 'node:crypto'
+import { Readable } from 'node:stream'
+import { type StorageKey, decryptStorageStream, encryptStorageStream, wrapStorageValue } from '../server-common/storage-crypto.ts'
+import { ENCRYPTED_CACHE_PREFIX, type ObjectStorage, type RawObject, type RawObjectStorage, deleteObjects, objectPath, openObjectVersion } from './object-storage.ts'
+import { type StorageDb, type StorageEncryptionState, type StorageRow, type StorageRowKind, dataKeyIdentity, unwrapDataKey } from './storage-db.ts'
+import { PUBLIC_CACHE_PREFIX, inspectStorageObject, masterKeyCache, storageOwner, storageRowPaths, verifyStoragePayload } from './storage-payload.ts'
+
+const STORAGE_WRITE_MS = 180_000
+export const STORAGE_UPLOAD_TTL_MS = 86_400_000
+export const STORAGE_DISABLED_TTL_MS = 5_000
+
+async function readBytes(stored: Awaited<ReturnType<ObjectStorage['open']>>): Promise<Buffer | null> {
+  if (!stored) return null
+  const parts: Buffer[] = []
+  try { for await (const part of stored.stream) parts.push(Buffer.from(part)); return Buffer.concat(parts) }
+  finally { stored.stream.destroy() }
+}
+function logicalKey(identity: string) {
+  objectPath(identity)
+  if (identity.startsWith(ENCRYPTED_CACHE_PREFIX)) throw new Error('Encrypted cache paths are internal')
+}
+const encryptedCachePath = (identity: string) => `${ENCRYPTED_CACHE_PREFIX}${identity.slice('cache/'.length)}`
+const deletionPaths = (identity: string) => identity.startsWith('cache/') ? [identity, encryptedCachePath(identity)] : [identity]
+// Public bytes, stored as they are whether or not storage is encrypted.
+const publicPath = (identity: string) => identity.startsWith('avatars/') || identity.startsWith(PUBLIC_CACHE_PREFIX)
+
+// A PUT can commit and still throw. Remove only this attempted plaintext,
+// comparing bytes rather than magic: arbitrary uploads can share the header.
+// A concurrent migration's ciphertext must survive this reconciliation.
+async function discardPlaintextWrite(raw: RawObjectStorage, identity: string, bytes: Buffer): Promise<void> {
+  // Leave time to report the original failure inside a serverless invocation.
+  const signal = AbortSignal.timeout(30_000)
+  const current = await raw.open(identity, signal)
+  if (!current) return
+  try {
+    let offset = 0
+    for await (const part of current.stream) {
+      const chunk = Buffer.from(part)
+      if (!chunk.equals(bytes.subarray(offset, offset + chunk.length))) return
+      offset += chunk.length
+    }
+    if (offset === bytes.length) await raw.delete(identity, current.version, signal)
+  } finally { current.stream.destroy() }
+}
+
+async function putPlaintext(raw: RawObjectStorage, identity: string, bytes: Buffer, mode: () => Promise<StorageEncryptionState | null>): Promise<null> {
+  try {
+    await raw.put(identity, bytes, AbortSignal.timeout(STORAGE_WRITE_MS))
+    if (!await mode()) return null
+    throw new Error('Storage encryption was enabled during upload; retry the upload')
+  } catch (err) {
+    try { await discardPlaintextWrite(raw, identity, bytes) }
+    catch (cleanup) { throw new AggregateError([err, cleanup], 'Storage write and plaintext cleanup failed', { cause: cleanup }) }
+    throw err
+  }
+}
+
+async function decryptOwned(stored: RawObject, key: StorageKey, type: StorageRowKind, row: StorageRow, identity: string) {
+  let dataKey: Buffer | undefined
+  try {
+    dataKey = unwrapDataKey(key, type, row)
+    return await decryptStorageStream(stored.stream, dataKey, identity)
+  } catch (err) { stored.stream.destroy(); throw err }
+  finally { dataKey?.fill(0) }
+}
+
+async function openEncrypted(raw: RawObjectStorage, db: StorageDb, key: StorageKey, identity: string, state: StorageEncryptionState): ReturnType<ObjectStorage['open']> {
+  const owner = storageOwner(identity)
+  if (!owner) {
+    // A cache no row owns: its ciphertext alone, what was kept as plaintext
+    // before activation never read.
+    if (masterKeyCache(identity)) {
+      const stored = await raw.open(encryptedCachePath(identity))
+      return stored && decryptStorageStream(stored.stream, key.bytes, identity)
+    }
+    if (!identity.startsWith('uploads/')) throw new Error('Unknown managed storage owner')
+    const stored = await raw.open(identity)
+    if (!stored) return null
+    const inspected = await inspectStorageObject(stored)
+    if (inspected.encrypted) return decryptStorageStream(inspected.stream, key.bytes, identity)
+    if (stored.modifiedAt <= state.enabledAt && Date.now() < state.enabledAt + STORAGE_UPLOAD_TTL_MS) return inspected
+    inspected.stream.destroy()
+    throw new Error('Unexpected plaintext upload part')
+  }
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const row = await db.getStorageRow(owner.type, owner.id)
+    if (!row) return null
+    if (!owner.cache && !storageRowPaths(owner.type, row).includes(identity)) return null
+    if (owner.cache && !row.dataKey) return null
+    if (!owner.cache && !row.encrypted) state = (await db.getStorageEncryption())!
+    const stored = await raw.open(owner.cache ? encryptedCachePath(identity) : identity)
+    if (!stored) return null
+    // Completed uploads and all new caches are always encrypted. Only legacy
+    // pending rows need header inspection and hash-verified plaintext fallback.
+    if (row.encrypted || owner.cache || state.complete) {
+      return decryptOwned(stored, key, owner.type, row, identity)
+    }
+    let inspected = await inspectStorageObject(stored)
+    if (inspected.encrypted && !row.dataKey && (await db.getStorageRow(owner.type, owner.id))?.dataKey) {
+      inspected.stream.destroy(); continue
+    }
+    if (inspected.encrypted && row.dataKey) {
+      try { return await decryptOwned(inspected, key, owner.type, row, identity) }
+      catch {
+        // An arbitrary legacy upload can begin with our magic bytes. Only
+        // its original SQL hash can authorize that plaintext interpretation.
+        const legacy = await openObjectVersion(raw, identity, stored.version)
+        if (!legacy) continue
+        inspected = { ...legacy, encrypted: false }
+      }
+    }
+    // Only a pending row may read plaintext, and only the original upload.
+    // Verify first, then reopen that exact version before exposing bytes.
+    await verifyStoragePayload(owner.type, row, inspected.stream, undefined, identity)
+    const current = await openObjectVersion(raw, identity, stored.version)
+    if (current) return current
+  }
+  throw new Error('Storage changed repeatedly during read')
+}
+
+async function verifyReportConversion(db: StorageDb, identity: string, bytes: Buffer): Promise<string> {
+  const owner = storageOwner(identity)
+  if (owner?.type !== 'report' || owner.cache || identity !== `reports/${owner.id}.br`) throw new Error('Invalid report conversion')
+  const row = await db.getStorageRow('report', owner.id)
+  if (!row) throw new Error('Report deleted during compression')
+  // Representation changes must preserve the immutable upload hash.
+  await verifyStoragePayload('report', row, Readable.from([bytes]), undefined, identity)
+  return owner.id
+}
+
+async function finishReportConversion(raw: RawObjectStorage, db: StorageDb, id: string, encrypted: boolean): Promise<void> {
+  const row = await db.getStorageRow('report', id)
+  if (!row) { await raw.delete(`reports/${id}.br`); throw new Error('Report deleted during compression') }
+  // Conversion preserves the original row/key. Keep the original until the
+  // compressed PUT has succeeded, and mark encrypted only after removing it.
+  await raw.delete(`reports/${id}`)
+  if (encrypted) await db.markStorageEncrypted('report', id, row.dataKey!)
+}
+
+async function existingReportConversion(raw: RawObjectStorage, identity: string, row: StorageRow, key: StorageKey | null,
+  encryptedMode: boolean): Promise<{ version: string; encrypted: boolean } | null> {
+  const stored = await raw.open(identity)
+  if (!stored) return null
+  const inspected = await inspectStorageObject(stored)
+  // Activation or a concurrent key allocation can win after the SQL read.
+  // Retry with fresh policy/row state before interpreting any ciphertext.
+  if (inspected.encrypted && (!encryptedMode || !row.dataKey)) {
+    inspected.stream.destroy()
+    return { version: stored.version, encrypted: true }
+  }
+  const source = inspected.encrypted ? await decryptOwned(inspected, key!, 'report', row, identity) : inspected
+  await verifyStoragePayload('report', row, source.stream, undefined, identity)
+  return { version: stored.version, encrypted: inspected.encrypted }
+}
+
+async function publishReportConversion(raw: RawObjectStorage, identity: string, bytes: Buffer, row: StorageRow,
+  key: StorageKey | null, expected: string | null, encrypted: boolean): Promise<boolean> {
+  if (!encrypted) return raw.put(identity, bytes, AbortSignal.timeout(STORAGE_WRITE_MS), expected)
+  const dataKey = unwrapDataKey(key!, 'report', row)
+  const source = encryptStorageStream(Readable.from([bytes]), dataKey, identity, bytes.length)
+  try { return await raw.put(identity, source, AbortSignal.timeout(STORAGE_WRITE_MS), expected, bytes.length) }
+  finally { source.destroy(); dataKey.fill(0) }
+}
+
+async function convertStoredReport(raw: RawObjectStorage, db: StorageDb, key: StorageKey | null, identity: string, bytes: Buffer,
+  mode: (fresh?: boolean) => Promise<StorageEncryptionState | null>): Promise<null> {
+  const id = await verifyReportConversion(db, identity, bytes)
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const state = await mode(true)
+    const row = state ? await db.ensureStorageDataKey('report', id) : await db.getStorageRow('report', id)
+    if (!row) throw new Error('Report deleted during compression')
+    const current = await existingReportConversion(raw, identity, row, key, Boolean(state))
+    if (current?.encrypted && (!state || !row.dataKey)) continue
+    // A stale plaintext writer must never replace a concurrent encrypted
+    // winner. Retain the original on uncertain writes; the next open resumes.
+    if ((!current || state && !current.encrypted) &&
+      !await publishReportConversion(raw, identity, bytes, row, key, current?.version ?? null, Boolean(state))) continue
+    if (!state && await mode(true)) continue
+    await raw.sync?.(identity)
+    await finishReportConversion(raw, db, id, Boolean(state))
+    return null
+  }
+  throw new Error('Report changed repeatedly during compression')
+}
+
+// Startup enables encryption before constructing stores; validate the persisted
+// requirement even when this adapter is opened without a key.
+// `known` is the state the caller read a moment before, where it found it
+// enabled, so a cold start reads it once.
+async function storagePolicy(db: StorageDb, key: StorageKey | null, known: StorageEncryptionState | null) {
+  let enabled = known ?? await db.getStorageEncryption()
+  let checkedAt = Date.now()
+  return async (fresh = false) => {
+    // Enabled is irreversible. Keyless instances cache "off" briefly, while
+    // writes and detected ciphertext always recheck the activation fence.
+    if (!enabled && (fresh || key || Date.now() - checkedAt >= STORAGE_DISABLED_TTL_MS)) {
+      const state = await db.getStorageEncryption()
+      if (state) enabled = state // A delayed disabled read cannot undo "on".
+      checkedAt = Date.now()
+    }
+    if (enabled && !key) throw new Error('Managed storage requires its configured encryption key')
+    return enabled
+  }
+}
+
+export async function createEncryptedObjectStorage(raw: RawObjectStorage, db: StorageDb, key: StorageKey | null,
+  known: StorageEncryptionState | null = null): Promise<ObjectStorage> {
+  const mode = await storagePolicy(db, key, known)
+  async function open(identity: string): ReturnType<ObjectStorage['open']> {
+    logicalKey(identity)
+    const state = await mode()
+    if (publicPath(identity)) return raw.open(identity)
+    if (state) return openEncrypted(raw, db, key!, identity, state)
+    const stored = await raw.open(identity)
+    if (!stored) return null
+    const inspected = await inspectStorageObject(stored)
+    // Activation/migration can win after the disabled-state read. Never send
+    // that ciphertext to a caller expecting the original plaintext bytes.
+    if (inspected.encrypted) {
+      let current: StorageEncryptionState | null
+      try { current = await mode(true) } catch (err) { inspected.stream.destroy(); throw err }
+      if (current) { inspected.stream.destroy(); return openEncrypted(raw, db, key!, identity, current) }
+    }
+    return inspected
+  }
+  return {
+    open,
+    get: async identity => readBytes(await open(identity)),
+    async exists(identity) {
+      logicalKey(identity)
+      const owner = storageOwner(identity), state = await mode()
+      if (state && owner) {
+        const row = await db.getStorageRow(owner.type, owner.id)
+        if (!row || (owner.cache ? !row.dataKey : !storageRowPaths(owner.type, row).includes(identity))) return false
+      }
+      // Existence is metadata only; open() authenticates the actual bytes.
+      return await raw.head(state && (owner?.cache || masterKeyCache(identity)) ? encryptedCachePath(identity) : identity) !== null
+    },
+    async put(identity, bytes, { replaceReport = false } = {}) {
+      logicalKey(identity)
+      if (replaceReport) return convertStoredReport(raw, db, key, identity, bytes, mode)
+      const state = await mode()
+      const owner = storageOwner(identity)
+      if (publicPath(identity)) { await raw.put(identity, bytes); return null }
+      if (!state) return putPlaintext(raw, identity, bytes, () => mode(true))
+      let dataKey: Buffer, wrapped: string | null = null
+      if (owner?.cache) {
+        const row = await db.ensureStorageDataKey(owner.type, owner.id)
+        if (!row) throw new Error('Cache owner unavailable')
+        dataKey = unwrapDataKey(key!, owner.type, row)
+      } else if (owner) {
+        if (await db.getStorageRow(owner.type, owner.id)) throw new Error('Stored payloads are immutable')
+        dataKey = randomBytes(32)
+        wrapped = wrapStorageValue(key!, dataKeyIdentity(owner.type, owner.id), dataKey)
+      } else {
+        if (!identity.startsWith('uploads/') && !masterKeyCache(identity)) throw new Error('Unknown managed storage owner')
+        dataKey = Buffer.from(key!.bytes)
+      }
+      const target = owner?.cache || masterKeyCache(identity) ? encryptedCachePath(identity) : identity
+      const encrypted = encryptStorageStream(Readable.from([bytes]), dataKey, identity, bytes.length)
+      try {
+        await raw.put(target, encrypted, AbortSignal.timeout(STORAGE_WRITE_MS), undefined, bytes.length)
+        // A late cache builder must not leave a readable cache for a deleted
+        // bundle. The missing SQL key also makes failed cleanup unreadable.
+        if (owner?.cache && !await db.getStorageRow(owner.type, owner.id)) await raw.delete(target)
+        return wrapped
+      } finally { encrypted.destroy(); dataKey.fill(0) }
+    },
+    async delete(identity) {
+      logicalKey(identity)
+      await mode()
+      // Always remove both generations, including caches predating activation
+      // when migration is disabled or another instance has just enabled it.
+      for (const target of deletionPaths(identity)) await raw.delete(target)
+    },
+    async deletePrefix(prefix, keep) {
+      logicalKey(`${prefix}validate`)
+      if (!prefix.endsWith('/') || (keep !== undefined && (!keep.startsWith(prefix) || !keep.endsWith('/')))) throw new Error('Invalid storage prefix')
+      await mode()
+      const signal = AbortSignal.timeout(STORAGE_WRITE_MS)
+      // What is kept, in the same generation as each removed.
+      const kept = keep === undefined ? [] : deletionPaths(keep)
+      for (const [i, target] of deletionPaths(prefix).entries()) {
+        await deleteObjects(raw, target, signal, undefined, kept[i])
+        await raw.prune?.(target, signal)
+      }
+    },
+  }
+}

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