@preventive/triage 1.0.0-alpha.3 → 1.0.0-alpha.30

package/server-managed/import-triage.ts

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto'
+import type { ManagedDb } from './db-methods.ts'
+import type { ManagedComment } from '../common/managed/comments.ts'
+import type { TriageEntryPatch } from '../common/managed/triage.ts'
+import { triageWireEntry } from './triage-response.ts'
+
+export interface ImportTriageSnapshot {
+  entry: TriageEntryPatch | null
+  comments: ManagedComment[]
+  version: string
+}
+export interface ImportTriageStore {
+  getImportTriage(ids: readonly string[]): Promise<Record<string, ImportTriageSnapshot>>
+  importTriage(entries: [string, TriageEntryPatch | null][], expected: Record<string, string>, actor: { id: string; login: string }, reportId: string, now: number): Promise<boolean>
+}
+
+// Raw store methods share one transaction for comparison, triage, and comments.
+export function importTriageMethods(store: Pick<ManagedDb, 'getReport' | 'listTriage' | 'listComments' | 'setTriageEntries' | 'createComment'>): ImportTriageStore {
+  async function snapshot(ids: readonly string[]) {
+    const rows = new Map((await store.listTriage(ids)).map(row => [row.findingId, row]))
+    const comments = await store.listComments(ids)
+    return Object.fromEntries(ids.map(id => {
+      const row = rows.get(id)
+      const entry = row ? triageWireEntry(row) : null
+      const own = comments.filter(comment => comment.findingId === id)
+      const version = createHash('sha256').update(JSON.stringify([entry, row?.updatedAt, own])).digest('hex')
+      return [id, { entry, comments: own, version }]
+    }))
+  }
+  return {
+    getImportTriage: snapshot,
+    async importTriage(entries, expected, actor, reportId, now) {
+      // A report deleted after the HTTP membership check must not leave newly
+      // imported annotations behind. Check existence in the write transaction.
+      if (!reportId || !(await store.getReport(reportId))) return false
+      const current = await snapshot(entries.map(([id]) => id))
+      if (entries.some(([id]) => current[id]!.version !== expected[id])) return false
+      const changes: [string, TriageEntryPatch | null][] = []
+      for (const [id, value] of entries) {
+        const { comment, ...entry } = value ?? {}
+        changes.push([id, Object.keys(entry).length > 0 ? entry : null])
+        if (comment && !current[id]!.comments.some(existing => existing.body === comment)) {
+          await store.createComment({ findingId: id, body: comment, authorId: null, authorLogin: null,
+            actor, createdAt: null, updatedAt: null, reportId }, now)
+        }
+      }
+      await store.setTriageEntries(changes, actor.id, actor.login, now, reportId)
+      return true
+    },
+  }
+}

package/server-managed/index.ts

@@ -0,0 +1,175 @@
+// Managed HTTP app and standalone boot. The combined launcher mounts this
+// same app on e2e's listener; storage, routing and cleanup stay here.
+import { randomUUID } from 'node:crypto'
+import { type Server, createServer } from 'node:http'
+import { fileURLToPath } from 'node:url'
+import { createOriginGate } from '../server-common/origin.ts'
+import { managedStorageLines } from '../server-common/storage-log.ts'
+import { runReapers, withReap } from '../server-common/reap.ts'
+import { startServer } from '../server-common/standalone.ts'
+import { initializeApp } from '../server-common/initialize.ts'
+import { type ManagedConfig, loadManagedConfig } from './config.ts'
+import { type ManagedHttpDeps, createManagedRequestHandler } from './http.ts'
+import { loadManagedStatic } from './static.ts'
+import { openManagedStorage } from './storage.ts'
+
+// Housekeeping runs on ordinary traffic too, including serverless instances
+// without a timer or cron. Failed sweeps retry on later traffic after a minute.
+const REAP_INTERVAL_MS = 3_600_000
+const REAP_RETRY_MS = 60_000
+
+type ManagedAppOptions = Partial<Pick<ManagedHttpDeps, 'next' | 'serverInfo' | 'isShuttingDown'>>
+
+export async function createManagedApp(config: ManagedConfig, options: ManagedAppOptions = {}) {
+  return await initializeApp(rollback => assembleManagedApp(config, options, rollback))
+}
+
+async function assembleManagedApp(config: ManagedConfig, options: ManagedAppOptions, rollback: AsyncDisposableStack) {
+  const storage = await openManagedStorage(config)
+  const { db, avatarStore, reportStore, bundleStore, bundleCache, reportSourcesCache } = storage
+  rollback.defer(() => db.close())
+  const originGate = createOriginGate(config.host, config.trustProxyEnv)
+
+  let shuttingDown = false
+  const isShuttingDown = () => shuttingDown || options.isShuttingDown?.() === true
+  const inFlight = new Set<Promise<unknown>>()
+  function track(p: Promise<unknown>): void {
+    inFlight.add(p)
+    p.finally(() => inFlight.delete(p)).catch(() => {})
+  }
+
+  const serveStatic = loadManagedStatic(fileURLToPath(new URL('../out/', import.meta.url)), {
+    indexOnly: options.next != null, scanServer: options.serverInfo?.deepviewScanServer ?? null,
+  })
+  const routeRequest = createManagedRequestHandler({
+    ...options, config, db, avatarStore, reportStore, bundleStore, bundleCache, reportSourcesCache, originGate, serveStatic,
+    ...(storage.uploadStore ? { uploadStore: storage.uploadStore } : {}),
+    isShuttingDown, track,
+  })
+
+  let cleanup: Promise<void> | undefined
+  let nextCleanupAt = 0
+  const maintenance = new AbortController()
+  function reap(automatic = false): Promise<void> {
+    if (cleanup) return cleanup
+    if (isShuttingDown()) return Promise.resolve()
+    const startedAt = Date.now()
+    nextCleanupAt = startedAt + REAP_INTERVAL_MS
+    let sessions = 0, uploads = 0
+    cleanup = (async () => {
+      const owner = automatic && config.serverless ? randomUUID() : null
+      if (owner && !await db.claimMaintenanceLease(owner, startedAt, startedAt + Math.max(300_000, (config.storageEncryptionMigrateMaxMs ?? 0) + 60_000), config.storageEncryptionMigrate)) return false
+      let succeeded = false
+      try {
+        await runReapers({
+          sessions: async () => { sessions = await db.deleteExpiredSessions(Date.now()) },
+          ...(storage.reapUploads ? { uploads: async () => { uploads = await storage.reapUploads!(maintenance.signal) } } : {}),
+          ...('reapStorage' in storage ? { storage: () => storage.reapStorage(maintenance.signal) } : {}),
+        })
+        succeeded = true
+        return true
+      } finally {
+        if (owner) await db.finishMaintenanceLease(owner, Date.now() + (succeeded ? REAP_INTERVAL_MS : REAP_RETRY_MS))
+      }
+    })().then(ran => {
+      nextCleanupAt = Date.now() + REAP_INTERVAL_MS
+      if (!ran) return
+      return console.info(`managed-reaper: removed ${sessions} expired session(s), ${uploads} stale upload part(s) in ${Date.now() - startedAt}ms`)
+    }, err => {
+      nextCleanupAt = Date.now() + REAP_RETRY_MS
+      throw err
+    }).finally(() => { cleanup = undefined })
+    track(cleanup)
+    return cleanup
+  }
+  function automaticReap(): Promise<void> {
+    if (isShuttingDown() || cleanup || Date.now() < nextCleanupAt) return Promise.resolve()
+    return reap(true).catch(err => console.warn('managed-reaper: cleanup failed:', err))
+  }
+  async function handleRequest(req: Parameters<typeof routeRequest>[0], res: Parameters<typeof routeRequest>[1]): Promise<void> {
+    const pendingMaintenance = automaticReap()
+    // Send the normal response without waiting for storage housekeeping. The
+    // Vercel entrypoint registers this whole promise with waitUntil; awaiting
+    // work after res.end() alone cannot extend a serverless invocation.
+    try { await routeRequest(req, res) }
+    finally { await pendingMaintenance }
+  }
+  const gcTimer = config.serverless ? null : setInterval(() => {
+    void automaticReap()
+  }, REAP_INTERVAL_MS)
+  rollback.defer(stop)
+
+  function stop(): void {
+    shuttingDown = true
+    maintenance.abort()
+    if (gcTimer) clearInterval(gcTimer)
+  }
+
+  async function close(): Promise<void> {
+    stop()
+    if (inFlight.size > 0) await Promise.allSettled([...inFlight])
+    await db.close()
+  }
+  return { handleRequest, reap, isShuttingDown, stop, close }
+}
+
+export function logManagedStartup(config: ManagedConfig, port: number, mode = 'managed'): void {
+  console.log([
+    `DeepView managed server (${mode}):`,
+    `  HTTP: http://${config.host}:${port}/`,
+    ...managedStorageLines(config),
+  ].join('\n'))
+}
+
+export async function init(config = loadManagedConfig()): Promise<Server> {
+  const app = await createManagedApp(config)
+  const server = createServer(withReap(app.handleRequest, { managed: app.reap }, { isShuttingDown: app.isShuttingDown }))
+  let disposal: Promise<void> | undefined
+  function dispose(): Promise<void> {
+    if (!disposal) {
+      app.stop()
+      disposal = (async () => {
+        try {
+          if (server.listening) {
+            await new Promise<void>((resolve, reject) => {
+              server.close(err => { if (err) reject(err); else resolve() })
+            })
+          }
+        } finally {
+          try { await app.close() }
+          finally {
+            server.off('error', onError)
+            server.off('close', onClose)
+            server.off('listening', onListening)
+          }
+        }
+      })()
+    }
+    return disposal
+  }
+  // Embedding hosts can await full cleanup even when they only copied the
+  // request listener and never bound this server. Repeated disposal is safe.
+  server[Symbol.asyncDispose] = dispose
+
+  function onError(): void { onClose() }
+  function onClose(): void {
+    if (!disposal) void dispose().catch(err => { console.error('Managed server cleanup failed:', err) })
+  }
+  function onListening(): void {
+    const address = server.address()
+    const port = typeof address === 'object' && address ? address.port : config.port
+    logManagedStartup(config, port)
+  }
+  server.on('error', onError)
+  server.once('close', onClose)
+  server.on('listening', onListening)
+  return server
+}
+
+export async function start(): Promise<void> {
+  const config = loadManagedConfig()
+  const server = await init(config)
+  startServer(server, config)
+}
+
+if (import.meta.main) await start()

package/server-managed/managed-issues.ts

@@ -0,0 +1,47 @@
+import type { ManagedSql } from './sql.ts'
+
+// One immutable reference per finding, shared across reports and teams. Keep
+// reservations across crashes/uncertain GitHub responses to prevent duplicates.
+// No triage/import/admin patch accepts these fields.
+export const MANAGED_ISSUE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_finding_issue (
+  finding_id TEXT PRIMARY KEY,
+  repo_id INTEGER NOT NULL,
+  repository TEXT NOT NULL,
+  request_id TEXT NOT NULL,
+  issue_url TEXT,
+  created_by TEXT REFERENCES managed_user(id) ON DELETE SET NULL,
+  created_at INTEGER NOT NULL
+) STRICT;
+`
+export interface ManagedIssue {
+  findingId: string
+  repoId: number
+  repository: string
+  requestId: string
+  issueUrl: string | null
+  createdBy: string | null
+  createdAt: number
+}
+export interface ManagedIssueStore {
+  getManagedIssue(findingId: string): Promise<ManagedIssue | null>
+  claimManagedIssue(issue: Omit<ManagedIssue, 'issueUrl'>): Promise<boolean>
+  finishManagedIssue(findingId: string, requestId: string, url: string): Promise<boolean>
+  releaseManagedIssue(findingId: string, requestId: string): Promise<void>
+}
+export function managedIssueMethods(db: ManagedSql): ManagedIssueStore {
+  const get = db.prepare(`SELECT finding_id AS findingId, repo_id AS repoId, repository, request_id AS requestId,
+    issue_url AS issueUrl, created_by AS createdBy, created_at AS createdAt FROM managed_finding_issue WHERE finding_id = ?`)
+  const claim = db.prepare(`INSERT INTO managed_finding_issue (finding_id, repo_id, repository, request_id, created_by, created_at)
+    VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (finding_id) DO NOTHING`)
+  const finish = db.prepare(`UPDATE managed_finding_issue SET issue_url = ? WHERE finding_id = ? AND request_id = ? AND issue_url IS NULL`)
+  const release = db.prepare(`DELETE FROM managed_finding_issue WHERE finding_id = ? AND request_id = ? AND issue_url IS NULL`)
+  return {
+    async getManagedIssue(findingId) { return (await get.get(findingId) as ManagedIssue | undefined) ?? null },
+    async claimManagedIssue(issue) {
+      return Number((await claim.run(issue.findingId, issue.repoId, issue.repository, issue.requestId, issue.createdBy, issue.createdAt)).changes) > 0
+    },
+    async finishManagedIssue(findingId, requestId, url) { return Number((await finish.run(url, findingId, requestId)).changes) > 0 },
+    async releaseManagedIssue(findingId, requestId) { await release.run(findingId, requestId) },
+  }
+}

package/server-managed/management-catalog.ts

@@ -0,0 +1,45 @@
+import { roleAtLeast } from '../common/managed/roles.ts'
+import { type RepoScope, contentAccess } from './content-access.ts'
+import type { AdminBundle, AdminReport, ManagedDb } from './db-methods.ts'
+import { ManagedMutationError } from './management.ts'
+
+type CatalogAccess = { repos: { repoId: number; fullName: string }[]; repoScopes: RepoScope[] | null }
+export interface ManagementCatalogStore {
+  getReportCatalog(sessionId: string, now: number): Promise<CatalogAccess & { reports: (AdminReport & { canChangeRepo: boolean })[] }>
+  getBundleCatalog(sessionId: string, now: number): Promise<CatalogAccess & { bundles: (AdminBundle & { canChangeRepo: boolean })[] }>
+}
+type CatalogDb = Pick<ManagedDb, 'getReportAccessSnapshot' | 'listRepoScopesForUser' | 'listSelectedRepos'
+  | 'listReports' | 'listBundles' | 'listReadableBundleIds'>
+
+// The outer store method owns one read snapshot. Use raw methods here so the
+// session, grants, rows and action flags agree without per-row transactions.
+export function managementCatalogMethods(db: CatalogDb): ManagementCatalogStore {
+  async function access(sessionId: string, now: number) {
+    const snapshot = await db.getReportAccessSnapshot(sessionId, now, [])
+    if (!snapshot) throw new ManagedMutationError(401, 'unauthenticated')
+    if (!roleAtLeast(snapshot.user.role, 'manage')) throw new ManagedMutationError(403, 'forbidden')
+    const scope = await contentAccess(db, snapshot.user)
+    const repos = (await db.listSelectedRepos()).filter(scope.bundle).map(({ repoId, fullName }) => ({ repoId, fullName }))
+    return { userId: snapshot.user.role === 'admin' ? undefined : snapshot.user.id, scope, repos }
+  }
+  return {
+    async getReportCatalog(sessionId, now) {
+      const { userId, scope, repos } = await access(sessionId, now)
+      const reports = await db.listReports(userId)
+      const linked = reports.flatMap(report => report.bundleId ? [report.bundleId] : [])
+      const readable = userId === undefined ? new Set(linked) : new Set(await db.listReadableBundleIds(userId, linked))
+      return { repos, repoScopes: scope.scopes, reports: reports.map(report => ({ ...report,
+        canChangeRepo: report.repoId === null || scope.report(report),
+        bundleId: report.bundleId && readable.has(report.bundleId) ? report.bundleId : null,
+        bundleFilename: report.bundleId && readable.has(report.bundleId) ? report.bundleFilename : null,
+      })) }
+    },
+    async getBundleCatalog(sessionId, now) {
+      const { userId, scope, repos } = await access(sessionId, now)
+      const bundles = await db.listBundles(userId)
+      return { repos, repoScopes: scope.scopes, bundles: bundles.map(bundle => ({ ...bundle,
+        canChangeRepo: bundle.repoId === null || scope.report(bundle),
+      })) }
+    },
+  }
+}

package/server-managed/management.ts

@@ -0,0 +1,86 @@
+import type { AdminReport, ManagedBundle, ManagedDb, ManagedRepo, RepoDataItem, RepoReportItem, ReportRecord, StoredUser } from './db-methods.ts'
+import { roleAtLeast } from '../common/managed/roles.ts'
+
+export class ManagedMutationError extends Error {
+  status: number
+  constructor(status: number, message: string) { super(message); this.status = status }
+}
+
+export type ContentMutation = { type: 'delete' } | { type: 'repo'; repoId: number | null; directory: string }
+export type ReportMutation = ContentMutation | { type: 'visibility'; visible: boolean }
+type RemovalRepo = Pick<ManagedRepo, 'repoId' | 'fullName' | 'addedAt'>
+type RemovalAnnotations = { reports: string; ids: string[] }
+export interface ManagementStore {
+  mutateReport(sessionId: string, id: string, change: ReportMutation): Promise<{ report: ReportRecord; user: StoredUser }>
+  mutateBundle(sessionId: string, id: string, change: ContentMutation): Promise<{ bundle: ManagedBundle; user: StoredUser }>
+  removeRepository(sessionId: string, expected: RemovalRepo, annotations: RemovalAnnotations | null): Promise<{
+    reports: RepoReportItem[]; bundles: RepoDataItem[]; deletedReports: number; deletedBundles: number; deletedTriage: number
+  }>
+}
+type ManagementDb = Pick<ManagedDb, 'sessionWithUser' | 'getReport' | 'getBundle' | 'listReports' | 'listReportsForRepo'
+  | 'listBundlesForRepo' | 'listAllRepos' | 'listSelectedRepos' | 'userCanReadReport' | 'userCanReadBundle' | 'userCanReadRepoPath'
+  | 'deleteReport' | 'setReportRepo' | 'setReportVisible' | 'deleteBundle' | 'setBundleRepo'
+  | 'deleteReportsForRepo' | 'deleteBundlesForRepo' | 'deleteRepo' | 'deleteTriage' | 'recordActivity'>
+
+// Only immutable bytes/format and repository membership affect the overlap
+// scan. Ignore publication, user display names, and unrelated bundle links.
+export function reportReferenceSnapshot(reports: readonly Pick<AdminReport, 'id' | 'sha256' | 'filename' | 'repoId'>[]): string {
+  return JSON.stringify(reports.map(r => [r.id, r.sha256, r.filename, r.repoId]).toSorted((a, b) => String(a[0]).localeCompare(String(b[0]))))
+}
+
+// These methods are wrapped by scopeManagedMethods: authorization, comparison,
+// metadata changes (and repository-removal audit) share the writer transaction. Blob reads
+// and deletes stay outside it. Use the raw store here, never nested scopes.
+export function managementMethods(db: ManagementDb): ManagementStore {
+  async function authorize(sessionId: string, role: 'admin' | 'manage') {
+    const s = await db.sessionWithUser(sessionId, Date.now())
+    if (!s) throw new ManagedMutationError(401, 'unauthenticated')
+    if (!roleAtLeast(s.user.role, role)) throw new ManagedMutationError(403, 'forbidden')
+    return s.user
+  }
+  async function destination(user: { id: string; role: string }, change: ContentMutation) {
+    if (change.type !== 'repo' || change.repoId === null) return
+    if (!(await db.listSelectedRepos()).some(repo => repo.repoId === change.repoId)) throw new ManagedMutationError(400, 'bad-repo')
+    if (user.role !== 'admin' && !await db.userCanReadRepoPath(user.id, change.repoId, change.directory)) throw new ManagedMutationError(403, 'repo-forbidden')
+  }
+  return {
+    async mutateReport(sessionId: string, id: string, change: ReportMutation) {
+      const user = await authorize(sessionId, 'manage')
+      const report = await db.getReport(id)
+      if (!report || (user.role !== 'admin' && report.uploadedBy !== user.id && !await db.userCanReadReport(user.id, id))) throw new ManagedMutationError(404, 'no-report')
+      if (user.role !== 'admin' && report.repoId !== null && !await db.userCanReadReport(user.id, id)) throw new ManagedMutationError(403, 'repo-forbidden')
+      if (change.type === 'repo' && report.repoEmbedded) throw new ManagedMutationError(409, 'repo-in-report')
+      if (change.type !== 'visibility') await destination(user, change)
+      if (change.type === 'delete') await db.deleteReport(id)
+      else if (change.type === 'visibility') await db.setReportVisible(id, change.visible)
+      else await db.setReportRepo(id, change.repoId, change.directory)
+      return { report, user }
+    },
+    async mutateBundle(sessionId: string, id: string, change: ContentMutation) {
+      const user = await authorize(sessionId, 'manage')
+      const bundle = await db.getBundle(id)
+      if (!bundle || (user.role !== 'admin' && !await db.userCanReadBundle(user.id, id))) throw new ManagedMutationError(404, 'no-bundle')
+      if (user.role !== 'admin' && bundle.repoId !== null && !await db.userCanReadRepoPath(user.id, bundle.repoId, bundle.repoDirectory)) throw new ManagedMutationError(403, 'repo-forbidden')
+      await destination(user, change)
+      if (change.type === 'delete') await db.deleteBundle(id)
+      else await db.setBundleRepo(id, change.repoId, change.directory)
+      return { bundle, user }
+    },
+    async removeRepository(sessionId: string, expected: RemovalRepo, annotations: RemovalAnnotations | null) {
+      const user = await authorize(sessionId, 'admin')
+      const repo = (await db.listAllRepos()).find(r => r.repoId === expected.repoId)
+      if (!repo) throw new ManagedMutationError(404, 'no-repo')
+      if (repo.fullName !== expected.fullName || repo.addedAt !== expected.addedAt) throw new ManagedMutationError(409, 'repository-changed')
+      if (annotations && reportReferenceSnapshot(await db.listReports()) !== annotations.reports) throw new ManagedMutationError(409, 'repository-changed')
+      const reports = await db.listReportsForRepo(repo.repoId)
+      const bundles = await db.listBundlesForRepo(repo.repoId)
+      const deletedReports = await db.deleteReportsForRepo(repo.repoId)
+      const deletedBundles = await db.deleteBundlesForRepo(repo.repoId)
+      const deletedTriage = await db.deleteTriage(annotations?.ids ?? [])
+      await db.deleteRepo(repo.repoId)
+      await db.recordActivity({ kind: 'delete', actor: user.login, actorId: user.id, repo: repo.fullName,
+        action: `removed a repository (${deletedReports} reports, ${deletedBundles} bundles, ${deletedTriage} triage entries)` }, Date.now())
+      return { reports, bundles, deletedReports, deletedBundles, deletedTriage }
+    },
+  }
+}

package/server-managed/object-storage-disk.ts

@@ -0,0 +1,144 @@
+import { randomUUID } from 'node:crypto'
+import { lstat, mkdir, open, readdir, rename, rm, rmdir, stat } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { type ObjectPage, type RawObjectStorage, objectPath } from './object-storage.ts'
+
+function missing(err: unknown): boolean { return (err as NodeJS.ErrnoException).code === 'ENOENT' }
+function version(info: { dev: number; ino: number; size: number; mtimeMs: number; ctimeMs: number }): string {
+  return JSON.stringify([info.dev, info.ino, info.size, info.mtimeMs, info.ctimeMs])
+}
+
+async function syncDirectory(dir: string): Promise<void> {
+  try {
+    const directory = await open(dir, 'r')
+    try { await directory.sync() } finally { await directory.close() }
+  } catch (err) {
+    // Windows and some mounted filesystems cannot open/fsync directories.
+    // Preserve real I/O failures; file fsync remains mandatory on every write.
+    if (!['EINVAL', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS', 'EISDIR', 'EBADF', 'EPERM'].includes((err as NodeJS.ErrnoException).code ?? '')) throw err
+  }
+}
+
+// Keyset pagination survives concurrent file creation/deletion. A final sweep
+// catches objects inserted before the cursor during migration.
+async function listFiles(dir: string, prefix: string, cursor: string | null, limit: number, signal?: AbortSignal): Promise<ObjectPage> {
+  const objects: ObjectPage['objects'] = []
+  async function visit(key: string): Promise<void> {
+    signal?.throwIfAborted()
+    let entries
+    try {
+      if (!(await lstat(join(dir, key))).isDirectory()) {
+        console.warn('managed-storage: skipping unsupported directory', JSON.stringify(key))
+        return
+      }
+      entries = await readdir(join(dir, key), { withFileTypes: true })
+    }
+    catch (err) { if (missing(err)) return; throw err }
+    const order = (entry: typeof entries[number]) => `${entry.name}${entry.isDirectory() ? '/' : ''}`
+    entries.sort((a, b) => order(a) < order(b) ? -1 : order(a) > order(b) ? 1 : 0)
+    for (const entry of entries) {
+      signal?.throwIfAborted()
+      const child = `${key}${entry.name}`
+      if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) {
+        console.warn('managed-storage: skipping unsupported entry', JSON.stringify(child))
+        continue
+      }
+      try { objectPath(child) }
+      catch { console.warn('managed-storage: skipping invalid entry', JSON.stringify(child)); continue }
+      if (entry.isDirectory()) {
+        const folder = `${child}/`
+        if (cursor && folder < cursor && !cursor.startsWith(folder)) continue
+        await visit(folder)
+        if (objects.length > limit) return
+      }
+      else if (entry.isFile() && (!cursor || child > cursor)) {
+        try { objects.push({ key: objectPath(child), modifiedAt: (await stat(join(dir, child))).mtimeMs }) }
+        catch (err) { if (!missing(err)) throw err }
+        if (objects.length > limit) return
+      }
+    }
+    // Another migration worker can observe an unlink before its writer has
+    // synced the directory. Persist those observed removals before an empty
+    // inventory can mark the shared migration complete.
+    try { await syncDirectory(join(dir, key)) } catch (err) { if (!missing(err)) throw err }
+  }
+  if (!prefix.endsWith('/') || !Number.isInteger(limit) || limit < 1) throw new Error('Invalid storage page')
+  objectPath(`${prefix}validate`)
+  await visit(prefix)
+  return { objects: objects.slice(0, limit), cursor: objects.length > limit ? objects[limit - 1]!.key : null }
+}
+
+export function createDiskObjectStorage(dir: string): RawObjectStorage {
+  const path = (key: string) => join(dir, objectPath(key))
+  return {
+    async head(key, signal) {
+      signal?.throwIfAborted()
+      try {
+        const info = await stat(path(key))
+        return { size: info.size, version: version(info), modifiedAt: info.mtimeMs }
+      } catch (err) { if (missing(err)) return null; throw err }
+    },
+    async open(key, signal) {
+      signal?.throwIfAborted()
+      let file
+      try { file = await open(path(key), 'r') }
+      catch (err) { if (missing(err)) return null; throw err }
+      try {
+        const info = await file.stat()
+        return { size: info.size, version: version(info), modifiedAt: info.mtimeMs,
+          stream: file.createReadStream(signal ? { signal } : {}) }
+      } catch (err) { await file.close(); throw err }
+    },
+    async put(key, bytes, signal, expected) {
+      const target = path(key)
+      // Temp-file + rename makes replacement atomic to readers. Concurrent
+      // migrations use the same persisted data key and immutable plaintext.
+      const temp = `${target}.${randomUUID()}.tmp`
+      await mkdir(dirname(target), { recursive: true })
+      const file = await open(temp, 'wx', 0o600)
+      try {
+        await file.writeFile(bytes, signal ? { signal } : {})
+        await file.sync(); await file.close()
+        signal?.throwIfAborted()
+        if (expected !== undefined) {
+          try { if (version(await stat(target)) !== expected) return false }
+          catch (err) { if (missing(err)) return false; throw err }
+        }
+        await rename(temp, target)
+        await syncDirectory(dirname(target))
+        return true
+      } finally { await file.close(); await rm(temp, { force: true }) }
+    },
+    async delete(key, expected, signal) {
+      signal?.throwIfAborted()
+      try {
+        if (expected !== undefined && version(await stat(path(key))) !== expected) return false
+        await rm(path(key), { force: true })
+        // Persist plaintext removal before migration checkpoints completion.
+        // Otherwise a crash could restore the directory entry after SQL has
+        // durably disabled further plaintext inventory sweeps.
+        await syncDirectory(dirname(path(key)))
+        return true
+      } catch (err) { if (missing(err)) return true; throw err }
+    },
+    async sync(key, signal) { signal?.throwIfAborted(); await syncDirectory(dirname(path(key))) },
+    async prune(prefix, signal) {
+      if (!prefix.endsWith('/')) throw new Error('Invalid storage prefix')
+      objectPath(`${prefix}validate`)
+      async function visit(folder: string): Promise<void> {
+        signal?.throwIfAborted()
+        let entries
+        try {
+          if (!(await lstat(folder)).isDirectory()) return
+          entries = await readdir(folder, { withFileTypes: true })
+        }
+        catch (err) { if (missing(err)) return; throw err }
+        for (const entry of entries) if (entry.isDirectory()) await visit(join(folder, entry.name))
+        try { await rmdir(folder); await syncDirectory(dirname(folder)) }
+        catch (err) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((err as NodeJS.ErrnoException).code ?? '')) throw err }
+      }
+      await visit(join(dir, prefix))
+    },
+    list: (prefix, cursor, limit, signal) => listFiles(dir, prefix, cursor, limit, signal),
+  }
+}

package/server-managed/object-storage-vercel.ts

@@ -0,0 +1,60 @@
+import { Readable } from 'node:stream'
+import { Buffer } from 'node:buffer'
+import { type VercelBlobSdk, isNotFound, loadVercelBlobSdk } from '../server-common/vercel-blob.ts'
+import { type RawObjectStorage, objectPath } from './object-storage.ts'
+
+export async function openVercelObjectStorage(token: string, sdk?: VercelBlobSdk): Promise<RawObjectStorage> {
+  const blobs = sdk ?? await loadVercelBlobSdk()
+  const path = (key: string) => `.managed/${objectPath(key)}`
+  return {
+    async head(key, signal) {
+      try {
+        const meta = await blobs.head(path(key), { token, ...(signal ? { abortSignal: signal } : {}) })
+        if (!meta.etag) throw new Error('Missing object version')
+        return { size: meta.size, version: meta.etag, modifiedAt: new Date(meta.uploadedAt ?? Date.now()).getTime() }
+      } catch (err) { if (isNotFound(err, blobs)) return null; throw err }
+    },
+    async open(key, signal) {
+      try {
+        const result = await blobs.get(path(key), { token, access: 'private', useCache: false, ...(signal ? { abortSignal: signal } : {}) })
+        if (!result) return null
+        if (result.statusCode !== 200 || !result.stream || !result.blob.etag) {
+          await result.stream?.cancel()
+          throw new Error('Unexpected blob response or missing object version')
+        }
+        return { size: result.blob.size === 0 ? null : result.blob.size, version: result.blob.etag,
+          modifiedAt: new Date(result.blob.uploadedAt ?? Date.now()).getTime(),
+          stream: Readable.fromWeb(result.stream as Parameters<typeof Readable.fromWeb>[0], signal ? { signal } : {}) }
+      } catch (err) { if (isNotFound(err, blobs)) return null; throw err }
+    },
+    async put(key, bytes, signal, expected, sizeHint) {
+      const multipart = (sizeHint ?? (Buffer.isBuffer(bytes) ? bytes.length : Infinity)) >= 5 * 1024 * 1024
+      try { await blobs.put(path(key), bytes, { token, access: 'private', addRandomSuffix: false, allowOverwrite: true,
+        ...(expected ? { ifMatch: expected } : {}), multipart, contentType: 'application/octet-stream', cacheControlMaxAge: 60, ...(signal ? { abortSignal: signal } : {}) })
+        return true
+      } catch (err) {
+        if (blobs.BlobPreconditionFailedError && err instanceof blobs.BlobPreconditionFailedError) return false
+        throw err
+      }
+    },
+    async delete(key, version, signal) {
+      signal?.throwIfAborted()
+      try { await blobs.del(path(key), { token, ...(version ? { ifMatch: version } : {}), ...(signal ? { abortSignal: signal } : {}) }); return true }
+      catch (err) {
+        if (isNotFound(err, blobs)) return true
+        if (blobs.BlobPreconditionFailedError && err instanceof blobs.BlobPreconditionFailedError) return false
+        throw err
+      }
+    },
+    async list(prefix, cursor, limit, signal) {
+      signal?.throwIfAborted()
+      if (!prefix.endsWith('/') || !Number.isInteger(limit) || limit < 1) throw new Error('Invalid storage page')
+      objectPath(`${prefix}validate`)
+      const page = await blobs.list({ prefix: `.managed/${prefix}`, token, limit, ...(cursor ? { cursor } : {}), ...(signal ? { abortSignal: signal } : {}) })
+      if (page.hasMore && (!page.cursor || page.cursor === cursor)) throw new Error('Invalid blob pagination')
+      return { objects: page.blobs.filter(blob => blob.pathname.startsWith(`.managed/${prefix}`)).map(blob => ({ key: blob.pathname.slice('.managed/'.length),
+        modifiedAt: new Date(blob.uploadedAt ?? Date.now()).getTime() })),
+      cursor: page.hasMore ? page.cursor! : null }
+    },
+  }
+}