@preventive/triage 1.0.0-alpha.26 → 1.0.0-alpha.27

package/server-managed/object-storage.ts

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

package/server-managed/repository-browser.ts

@@ -2,6 +2,7 @@ import type { ManagedConfig } from './config.ts'
 import type { SelectedRepo } from './db.ts'
 import { GithubApiError, githubJson, githubRepoReadPermission, githubUserIdentity, repoAccessToken } from './github-app.ts'
 import { MAX_PACKAGE_BYTES, readPackageEntryPoints } from './package-entry-points.ts'
+import { readSolidityEntryPoints } from './solidity-entry-points.ts'
 
 export interface RepositoryEntry { name: string; path: string; type: 'dir' | 'file' | 'symlink' | 'submodule' }
 
@@ -126,7 +127,10 @@ async function repositoryReader(repo: SelectedRepo, userToken: string | null, in
       const manifest = data.find(item => item?.path === manifestPath && item.name === 'package.json' && item.type === 'file' && !item.submodule_git_url
         && typeof item.size === 'number' && item.size >= 0 && item.size <= MAX_PACKAGE_BYTES && typeof item.sha === 'string' && /^[a-f\d]{40}$/iu.test(item.sha))
       const packageEntryPoints = manifest ? await readPackageEntryPoints(manifest.sha, path, read) : undefined
-      return { entries, limited: data.length >= 1000, ...(packageEntryPoints ? { packageEntryPoints } : {}) }
+      const solidity = await readSolidityEntryPoints(path, data, read)
+      return { entries, limited: data.length >= 1000, ...(packageEntryPoints ? { packageEntryPoints } : {}),
+        ...(solidity.paths.length > 0 || solidity.limited ? { solidityEntryPoints: solidity.paths, soliditySuggestionsLimited: solidity.limited } : {}),
+      }
     },
   }
 }

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

@@ -0,0 +1,69 @@
+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
+  }
+  for (const root of roots) {
+    if (!sourcePath(`${root.path}/Contract.sol`)) continue
+    try {
+      const data = await read(`/git/trees/${root.sha}?recursive=1`) as { tree?: unknown; truncated?: unknown }
+      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.ts

@@ -4,11 +4,6 @@ import type { DatabaseSync, SQLInputValue } from 'node:sqlite'
 import type { ManagedDb } from './db-methods.ts'
 
 type MaybePromise<T> = T | Promise<T>
-// A failed COMMIT acknowledgement (or connection close after COMMIT) does not
-// establish rollback. Callers must retain primary bytes until reconciled.
-export class ManagedCommitError extends Error {
-  constructor(cause: unknown) { super('Managed commit outcome is uncertain', { cause }) }
-}
 export interface ManagedSql {
   prepare(sql: string): {
     get(...params: unknown[]): MaybePromise<unknown>

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,168 @@
+// 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
+}
+
+export async function storageState(db: ManagedSql, key: StorageKey | null): Promise<StorageEncryptionState | null> {
+  const row = await db.prepare(`SELECT test_value AS testValue, enabled_at AS enabledAt, cursor, complete, migrated,
+    cleanup_cursor AS cleanupCursor, cleanup_found AS cleanupFound, cleanup_complete AS cleanupComplete
+    FROM managed_storage_encryption WHERE id = 1`).get() as (StorageEncryptionState & { testValue: string }) | undefined
+  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) }
+}
+
+const PENDING = `SELECT 'bundle:' || id AS position, id, 'bundle' AS type FROM managed_bundle WHERE storage_encrypted = 0
+  UNION ALL SELECT 'report:' || id AS position, id, 'report' AS type FROM managed_report WHERE storage_encrypted = 0
+  UNION ALL SELECT 'user:' || 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)`
+
+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(after ?? '', limit) as StorageMigrationRow[]
+    },
+    async advanceStorageMigration(expected, next) {
+      await requireEnabled()
+      if (expected !== null && next !== null && next <= 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()
+    },
+  }
+}

package/server-managed/storage-encryption.ts

@@ -0,0 +1,211 @@
+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 { inspectStorageObject, storageOwner, storageRowPath, 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]
+
+// 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) {
+    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 && storageRowPath(owner.type, row) !== 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)
+    const current = await openObjectVersion(raw, identity, stored.version)
+    if (current) return current
+  }
+  throw new Error('Storage changed repeatedly during read')
+}
+
+// Startup enables encryption before constructing stores; validate the persisted
+// requirement even when this adapter is opened without a key.
+async function storagePolicy(db: StorageDb, key: StorageKey | null) {
+  let enabled = 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): Promise<ObjectStorage> {
+  const mode = await storagePolicy(db, key)
+  async function open(identity: string): ReturnType<ObjectStorage['open']> {
+    logicalKey(identity)
+    const state = await mode()
+    if (identity.startsWith('avatars/')) 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 : storageRowPath(owner.type, row) !== identity)) return false
+      }
+      // Existence is metadata only; open() authenticates the actual bytes.
+      return await raw.head(state && owner?.cache ? encryptedCachePath(identity) : identity) !== null
+    },
+    async put(identity, bytes) {
+      logicalKey(identity)
+      const state = await mode()
+      if (identity.startsWith('avatars/')) { await raw.put(identity, bytes); return null }
+      if (!state) return putPlaintext(raw, identity, bytes, () => mode(true))
+      const owner = storageOwner(identity)
+      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/')) throw new Error('Unknown managed storage owner')
+        dataKey = Buffer.from(key!.bytes)
+      }
+      const target = owner?.cache ? 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) {
+      logicalKey(`${prefix}validate`)
+      if (!prefix.endsWith('/')) throw new Error('Invalid storage prefix')
+      await mode()
+      const signal = AbortSignal.timeout(STORAGE_WRITE_MS)
+      for (const target of deletionPaths(prefix)) {
+        await deleteObjects(raw, target, signal)
+        await raw.prune?.(target, signal)
+      }
+    },
+  }
+}