pipework 0.252.0 → 0.252.1

package/src/infra/storage/handle.ts

@@ -0,0 +1,513 @@
+import { createHash, randomUUID } from 'node:crypto'
+import type { Readable } from 'node:stream'
+import { sql } from '../../data/db/sql.js'
+import { pipe, pipeSystem, pipeFrameworkDoor } from '../../data/db/db.js'
+import type { DB } from '../../data/db/index.js'
+import { requireContext } from '../../request/context/store.js'
+import type { Flow } from '../../request/context/types.js'
+import { inTenant } from '../../auth/tenant/in-tenant.js'
+import { resolveActorId } from '../../data/write/audit/actor.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { recordFault, faultMessage } from '../alerts/faults.js'
+import { NotFoundError, PayloadTooLargeError, ValidationError } from '../../core/errors/index.js'
+import type { StorageBackend } from './backend.js'
+
+const DEFAULT_MAX_BYTES = 1024 ** 3
+const MAX_BACKEND_BYTES = 5 * 1024 ** 3
+const MAX_SIGNED_SECONDS = 604800
+const DEFAULT_SIGNED_SECONDS = 900
+const DEFAULT_SWEEP_LIMIT = 1000
+const TMP_MAX_AGE_MS = 24 * 3_600_000
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const OBJECT_KEY = /^tenants\/([0-9a-f-]{36})\/sha256\/([0-9a-f]{64})$/
+const TMP_KEY = /^tenants\/[0-9a-f-]{36}\/tmp\/[0-9a-f-]{36}$/
+
+export interface StorageConfig {
+  readonly backend: StorageBackend
+  /** Largest file `put` accepts, in bytes. Default 1 GiB; at most 5 GiB. */
+  readonly maxBytes?: number
+  /** The app's environment. The local backend is refused when this is `production`. */
+  readonly environment?: string
+}
+
+/** The metadata row of a stored file. */
+export interface StoredFile {
+  readonly id: string
+  readonly tenantId: string
+  /** Lowercase hex SHA-256 of the content. */
+  readonly sha256: string
+  readonly size: number
+  readonly mediaType: string
+  readonly filename: string | null
+  readonly createdAt: Date
+  /** The Flow's `auth.userId` when `put` ran. */
+  readonly createdBy: string | null
+  /** `null` = kept until deleted. */
+  readonly expiresAt: Date | null
+  readonly metadata: unknown
+}
+
+export interface PutOptions {
+  /** The bytes. Read once, never held whole; the length need not be known. */
+  readonly body: Readable
+  readonly mediaType: string
+  readonly filename?: string
+  /** Hex SHA-256 the content must have; a different digest fails with 422 and stores nothing. */
+  readonly expectedSha256?: string
+  /** After this time the file is no longer returned and `sweep` deletes it. */
+  readonly expiresAt?: Date
+  readonly metadata?: unknown
+}
+
+export interface SignedUrlOptions {
+  /** 1 to 604800 (seven days). Default 900. */
+  readonly expiresInSeconds?: number
+  /** `'attachment'` (default) downloads; `'inline'` lets the browser display it. */
+  readonly disposition?: 'attachment' | 'inline'
+  /** Name the browser saves under; default the stored filename. */
+  readonly filename?: string
+}
+
+export interface FindOptions {
+  /** Hex SHA-256 of the content, any case. */
+  readonly sha256?: string
+  /** Rows whose metadata contains this object (jsonb `@>`); nested objects match by containment. */
+  readonly metadata?: Record<string, unknown>
+  /** Most rows returned. Default 1000, at most 10000. */
+  readonly limit?: number
+}
+
+export interface SweepOptions {
+  /** Most rows expired and most objects deleted in one call (each). Default 1000. */
+  readonly limit?: number
+}
+
+export interface SweepResult {
+  /** Rows past `expiresAt` deleted. */
+  readonly expired: number
+  /** Content objects deleted because no row referenced them. */
+  readonly objects: number
+  /** Abandoned upload temp objects (over 24 hours old) deleted. */
+  readonly temp: number
+}
+
+export interface Storage {
+  /**
+   * Stores a stream for the Flow's tenant and returns its metadata row. The bytes are written to a
+   * temporary object while hashed and counted, then moved to the tenant's content address
+   * (`tenants/<tenantId>/sha256/<hex>`); the same bytes put again by the tenant add a row and no
+   * object. Over `maxBytes` throws `PayloadTooLargeError` (413); a digest other than `expectedSha256`
+   * throws `ValidationError` (422); either leaves no row and no object. The blob is written first
+   * and the row in the Flow's transaction, so a rolled-back transaction leaves an object that
+   * `sweep()` removes. An `StoredFile:put` audit record is written when the Flow has an open trace step.
+   */
+  put(options: PutOptions): Promise<StoredFile>
+  putFor(tenantId: string, options: PutOptions): Promise<StoredFile>
+  /** The file's row, or `null` when there is none (or it has expired). */
+  get(id: string): Promise<StoredFile | null>
+  getFor(tenantId: string, id: string): Promise<StoredFile | null>
+  /**
+   * The tenant's live (unexpired) files matching every given filter, oldest first. Give `sha256`,
+   * `metadata` or both; none throws `ValidationError`. Runs in the Flow's transaction, under the same RLS as `get`.
+   */
+  find(query: FindOptions): Promise<StoredFile[]>
+  findFor(tenantId: string, query: FindOptions): Promise<StoredFile[]>
+  /** The row and a stream of the content (pass `file.size` as `length` to `http.file()`). Throws `NotFoundError` when there is no row. */
+  open(id: string): Promise<{ file: StoredFile; stream: Readable }>
+  openFor(tenantId: string, id: string): Promise<{ file: StoredFile; stream: Readable }>
+  /**
+   * A URL that serves the content to anyone holding it until it expires, with the requested
+   * Content-Disposition and the stored media type. S3 backend only; the local backend throws.
+   */
+  signedUrl(id: string, options?: SignedUrlOptions): Promise<{ url: string; expiresAt: Date }>
+  signedUrlFor(tenantId: string, id: string, options?: SignedUrlOptions): Promise<{ url: string; expiresAt: Date }>
+  /** Deletes the row (audit `StoredFile:delete`); the object goes at the next `sweep()` once no row references it. Returns whether there was a row. */
+  delete(id: string): Promise<boolean>
+  deleteFor(tenantId: string, id: string): Promise<boolean>
+  /**
+   * For a cron (system, all tenants). Deletes rows past `expiresAt` (audit `StoredFile:expire`), then
+   * content objects no row references and upload temp objects over 24 hours old. Needs a Flow
+   * (a job or schedule run). Audit records need an open trace step, as in `put`.
+   */
+  sweep(options?: SweepOptions): Promise<SweepResult>
+}
+
+function toDate(value: unknown): Date {
+  if (value instanceof Date) return value
+  const text = String(value)
+  return new Date(/(Z|[+-]\d\d(:?\d\d)?)$/.test(text) ? text : `${text.replace(' ', 'T')}Z`)
+}
+
+function rowToFile(row: Record<string, unknown>): StoredFile {
+  const expires = row['expires_at']
+  return {
+    id: row['id'] as string,
+    tenantId: row['tenant_id'] as string,
+    sha256: row['sha256'] as string,
+    size: Number(row['size']),
+    mediaType: row['media_type'] as string,
+    filename: (row['filename'] as string | null) ?? null,
+    createdAt: toDate(row['created_at']),
+    createdBy: (row['created_by'] as string | null) ?? null,
+    expiresAt: expires === null || expires === undefined ? null : toDate(expires),
+    metadata: row['metadata'] ?? null,
+  }
+}
+
+function auditProjection(file: StoredFile): Record<string, unknown> {
+  return {
+    id: file.id, sha256: file.sha256, size: file.size, mediaType: file.mediaType, filename: file.filename,
+    createdBy: file.createdBy, expiresAt: file.expiresAt,
+  }
+}
+
+function requireId(name: string, value: string): void {
+  if (typeof value !== 'string' || !UUID.test(value)) {
+    throw new ValidationError({ [name]: ['must be a UUID'] }, `Storage ${name} must be a UUID.`)
+  }
+}
+
+function keyFor(tenantId: string, sha256: string): string {
+  return `tenants/${tenantId.toLowerCase()}/sha256/${sha256}`
+}
+
+/**
+ * Tenant-scoped, content-addressed file storage over a backend (`storage.s3(...)` or
+ * `storage.local(...)`). Requires blueprint `storage: {}` for the `storage_file` table.
+ * Throws when the local backend is used with `environment: 'production'`, or `maxBytes`
+ * is not an integer from 1 to 5 GiB.
+ */
+export function createStorage(config: StorageConfig): Storage {
+  const backend = config.backend
+  const maxBytes = config.maxBytes ?? DEFAULT_MAX_BYTES
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_BACKEND_BYTES) {
+    throw new Error('[pipework] storage maxBytes must be an integer from 1 to 5 GiB (5368709120).\n')
+  }
+  if (backend.name === 'local' && config.environment === 'production') {
+    throw new Error(
+      '[pipework] storage.local is refused in production.\n\n' +
+      '  It keeps files on this machine\'s disk. Configure storage.s3({ bucket, region, credentials }).\n',
+    )
+  }
+
+  function tenantOf(explicit: string | null, flow: Flow): string {
+    if (explicit !== null) {
+      requireId('tenantId', explicit)
+      return explicit
+    }
+    if (flow.tenant === null) {
+      throw new Error(
+        '[pipework] This storage method needs a tenant in the Flow.\n\n' +
+        '  Call it from an authenticated tenant route, or use the ...For(tenantId, ...) form\n' +
+        '  (putFor, getFor, openFor, ...) from a webhook or a job with no tenant.\n',
+      )
+    }
+    return flow.tenant
+  }
+
+  async function run<T>(explicit: string | null, fn: (tx: DB, tenantId: string, flow: Flow) => Promise<T>): Promise<T> {
+    const flow = requireContext()
+    const tenantId = tenantOf(explicit, flow)
+    if (explicit !== null) return inTenant(flow, tenantId, tx => fn(tx, tenantId, flow))
+    return pipe.transaction((tx: DB) => fn(tx, tenantId, flow))
+  }
+
+  async function audit(flow: Flow, tx: DB, tenantId: string, verb: string, fileId: string, details: Record<string, unknown>): Promise<void> {
+    const trace = flow.trace
+    const stepId = trace?.buffer.openStepId ?? null
+    if (trace === null || stepId === null) return
+    try {
+      await tx.transaction(async (sp: DB) => {
+        await sp.execute(sql`
+          INSERT INTO audit_record
+            (trace_day, trace_id, trace_step_id, tenant_id, actor_id, entity, verb, entity_id, after, occurred_at)
+          VALUES (${trace.openedDay}, ${trace.id}, ${stepId}, ${tenantId}, ${resolveActorId(flow)},
+            'StoredFile', ${verb}, ${fileId}, ${JSON.stringify(details)}::jsonb, now())
+        `)
+      })
+    } catch (err) {
+      getBaseLogger().error({ err, traceId: trace.id }, `Failed to write the stored file ${verb} audit record`)
+      void recordFault('audit-write', faultMessage(err), { entity: 'StoredFile', verb })
+    }
+  }
+
+  // One tenant-and-content lock orders a put's "does the object exist, then the row" against a
+  // sweep's "is there a row, then delete the object". Held to the end of the transaction.
+  async function lockContent(tx: DB, tenantId: string, sha256: string): Promise<void> {
+    await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtextextended(${`pipework.storage:${tenantId.toLowerCase()}:${sha256}`}, 0))`)
+  }
+
+  async function discard(key: string): Promise<void> {
+    try {
+      await backend.remove(key)
+    } catch (err) {
+      getBaseLogger().error({ err, key }, 'storage failed to remove a temporary object; sweep() will')
+    }
+  }
+
+  async function doPut(explicit: string | null, options: PutOptions): Promise<StoredFile> {
+    if (typeof options.mediaType !== 'string' || options.mediaType.trim() === '' || /[\r\n]/.test(options.mediaType)) {
+      throw new ValidationError({ mediaType: ['must be a media type such as "application/pdf"'] }, 'Storage mediaType must be a non-empty single line.')
+    }
+    let expected: string | null = null
+    if (options.expectedSha256 !== undefined) {
+      if (!/^[0-9a-f]{64}$/i.test(options.expectedSha256)) {
+        throw new ValidationError({ expectedSha256: ['must be 64 hex characters'] }, 'Storage expectedSha256 must be a hex SHA-256.')
+      }
+      expected = options.expectedSha256.toLowerCase()
+    }
+    if (options.expiresAt !== undefined && !(options.expiresAt instanceof Date && !Number.isNaN(options.expiresAt.getTime()))) {
+      throw new ValidationError({ expiresAt: ['must be a valid Date'] }, 'Storage expiresAt must be a Date.')
+    }
+    // Resolve the tenant before any byte is written.
+    const flow = requireContext()
+    const tenantId = tenantOf(explicit, flow)
+
+    const hash = createHash('sha256')
+    let size = 0
+    const measured = (async function* (): AsyncGenerator<Buffer> {
+      for await (const chunk of options.body) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array)
+        size += buf.length
+        if (size > maxBytes) throw new PayloadTooLargeError(`File is larger than ${maxBytes} bytes`, { maxBytes })
+        hash.update(buf)
+        yield buf
+      }
+    })()
+
+    const tmpKey = `tenants/${tenantId.toLowerCase()}/tmp/${randomUUID()}`
+    try {
+      await backend.put(tmpKey, measured)
+    } catch (err) {
+      options.body.destroy()
+      await discard(tmpKey)
+      throw err
+    }
+    const sha256 = hash.digest('hex')
+    if (expected !== null && expected !== sha256) {
+      await discard(tmpKey)
+      throw new ValidationError(
+        { expectedSha256: [`content has sha256 ${sha256}`] },
+        'The uploaded content does not match expectedSha256.',
+      )
+    }
+
+    const finalKey = keyFor(tenantId, sha256)
+    try {
+      return await run(explicit, async (tx, tenant, f) => {
+        await lockContent(tx, tenant, sha256)
+        if (!(await backend.exists(finalKey))) await backend.copy(tmpKey, finalKey)
+        const metadata = options.metadata === undefined ? null : JSON.stringify(options.metadata)
+        const rows = await tx.execute(sql`
+          INSERT INTO storage_file (tenant_id, sha256, size, media_type, filename, created_by, expires_at, metadata)
+          VALUES (${tenant}, ${sha256}, ${size}, ${options.mediaType.trim()}, ${options.filename ?? null},
+            ${resolveActorId(f)}, ${options.expiresAt?.toISOString() ?? null},
+            ${metadata === null ? sql`NULL` : sql`${metadata}::jsonb`})
+          RETURNING *
+        `)
+        const file = rowToFile(rows[0]!)
+        await audit(f, tx, tenant, 'put', file.id, auditProjection(file))
+        return file
+      })
+    } finally {
+      await discard(tmpKey)
+    }
+  }
+
+  async function findFile(tx: DB, tenantId: string, id: string, includeExpired: boolean): Promise<StoredFile | null> {
+    const rows = await tx.execute(includeExpired
+      ? sql`SELECT * FROM storage_file WHERE tenant_id = ${tenantId} AND id = ${id}`
+      : sql`SELECT * FROM storage_file WHERE tenant_id = ${tenantId} AND id = ${id} AND (expires_at IS NULL OR expires_at > now())`)
+    return rows.length === 0 ? null : rowToFile(rows[0]!)
+  }
+
+  async function doGet(explicit: string | null, id: string): Promise<StoredFile | null> {
+    requireId('id', id)
+    return run(explicit, (tx, tenantId) => findFile(tx, tenantId, id, false))
+  }
+
+  async function doFind(explicit: string | null, query: FindOptions): Promise<StoredFile[]> {
+    if ((query as unknown) === null || typeof query !== 'object') {
+      throw new ValidationError({ query: ['give sha256, metadata or both'] }, 'Storage find needs sha256, metadata or both.')
+    }
+    let hash: string | null = null
+    if (query.sha256 !== undefined) {
+      if (typeof query.sha256 !== 'string' || !/^[0-9a-f]{64}$/i.test(query.sha256)) {
+        throw new ValidationError({ sha256: ['must be 64 hex characters'] }, 'Storage find sha256 must be a hex SHA-256.')
+      }
+      hash = query.sha256.toLowerCase()
+    }
+    let contains: string | null = null
+    if (query.metadata !== undefined) {
+      const given: unknown = query.metadata
+      const proto: unknown = given === null || typeof given !== 'object' ? undefined : Object.getPrototypeOf(given)
+      if (proto !== Object.prototype && proto !== null) {
+        throw new ValidationError({ metadata: ['must be a plain object'] }, 'Storage find metadata must be a plain object.')
+      }
+      contains = JSON.stringify(query.metadata)
+    }
+    if (hash === null && contains === null) {
+      throw new ValidationError({ query: ['give sha256, metadata or both'] }, 'Storage find needs sha256, metadata or both.')
+    }
+    const limit = query.limit ?? 1000
+    if (!Number.isInteger(limit) || limit < 1 || limit > 10000) {
+      throw new ValidationError({ limit: ['must be an integer from 1 to 10000'] }, 'Storage find limit must be an integer from 1 to 10000.')
+    }
+    return run(explicit, async (tx, tenantId) => {
+      const rows = await tx.execute(sql`
+        SELECT * FROM storage_file
+        WHERE tenant_id = ${tenantId} AND (expires_at IS NULL OR expires_at > now())
+          ${hash === null ? sql`` : sql`AND sha256 = ${hash}`}
+          ${contains === null ? sql`` : sql`AND metadata @> ${contains}::jsonb`}
+        ORDER BY created_at, id
+        LIMIT ${limit}
+      `)
+      return rows.map(r => rowToFile(r))
+    })
+  }
+
+  async function doOpen(explicit: string | null, id: string): Promise<{ file: StoredFile; stream: Readable }> {
+    const file = await doGet(explicit, id)
+    if (file === null) throw new NotFoundError('File', { id })
+    return { file, stream: await backend.read(keyFor(file.tenantId, file.sha256)) }
+  }
+
+  async function doSignedUrl(explicit: string | null, id: string, options: SignedUrlOptions = {}): Promise<{ url: string; expiresAt: Date }> {
+    const seconds = options.expiresInSeconds ?? DEFAULT_SIGNED_SECONDS
+    if (!Number.isInteger(seconds) || seconds < 1 || seconds > MAX_SIGNED_SECONDS) {
+      throw new ValidationError({ expiresInSeconds: [`must be an integer from 1 to ${MAX_SIGNED_SECONDS}`] }, 'Storage expiresInSeconds is out of range.')
+    }
+    const disposition: string = options.disposition ?? 'attachment'
+    if (disposition !== 'attachment' && disposition !== 'inline') {
+      throw new ValidationError({ disposition: ["must be 'attachment' or 'inline'"] }, 'Storage disposition must be attachment or inline.')
+    }
+    const file = await doGet(explicit, id)
+    if (file === null) throw new NotFoundError('File', { id })
+    const filename = options.filename ?? file.filename ?? undefined
+    const issued = Date.now()
+    const url = await backend.signedUrl(keyFor(file.tenantId, file.sha256), {
+      expiresInSeconds: seconds, disposition: disposition as 'attachment' | 'inline', mediaType: file.mediaType, ...(filename !== undefined ? { filename } : {}),
+    })
+    return { url, expiresAt: new Date(issued + seconds * 1000) }
+  }
+
+  async function doDelete(explicit: string | null, id: string): Promise<boolean> {
+    requireId('id', id)
+    return run(explicit, async (tx, tenantId, flow) => {
+      const rows = await tx.execute(sql`DELETE FROM storage_file WHERE tenant_id = ${tenantId} AND id = ${id} RETURNING *`)
+      if (rows.length === 0) return false
+      const file = rowToFile(rows[0]!)
+      await audit(flow, tx, tenantId, 'delete', file.id, auditProjection(file))
+      return true
+    })
+  }
+
+  async function requireSweepDoor(): Promise<void> {
+    const wanted = ['pipework_door_pipework__storage_sweep', 'pipework_door_pipework__storage_sweep__delete']
+    const found = await pipeSystem().execute(sql`
+      SELECT p.polname FROM pg_policy p JOIN pg_class c ON c.oid = p.polrelid
+      WHERE c.relname = 'storage_file' AND c.relnamespace = 'public'::regnamespace AND p.polname IN ('pipework_door_pipework__storage_sweep', 'pipework_door_pipework__storage_sweep__delete')`)
+    const have = new Set(found.map(r => r['polname'] as string))
+    const missing = wanted.filter(n => !have.has(n))
+    if (missing.length > 0) {
+      throw new Error(
+        `[pipework] storage.sweep() refused: the door "pipework.storage_sweep" is missing its policy on storage_file (${missing.join(', ')}).\n\n` +
+        '  The database runs its system channel on a platform role, which sees storage_file only through that door; without it the sweep would\n' +
+        '  find no file referencing any object. Nothing was removed. Fix: run `pipework generate` and `pipework migrate`.\n',
+      )
+    }
+  }
+
+  async function doSweep(options: SweepOptions = {}): Promise<SweepResult> {
+    const limit = options.limit ?? DEFAULT_SWEEP_LIMIT
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+      throw new ValidationError({ limit: ['must be a positive integer'] }, 'Storage sweep limit must be a positive integer.')
+    }
+    const flow = requireContext()
+    let expired = 0
+    let objects = 0
+    let temp = 0
+
+    // Where the database has a platform role, `storage_file` is readable and deletable by it only through the
+    // sweep's door. A missing door policy would read as "no file references anything" and remove every object,
+    // so it is checked first and the sweep refuses before it lists one.
+    const platform = flow.instance.config.database().rls?.platformRole !== undefined
+    if (platform) await requireSweepDoor()
+    // Row locking in the subselect needs an UPDATE policy as well, which the door does not grant; the
+    // DELETE takes the row locks itself, and a concurrent sweep deletes nothing twice.
+    const inSweepDoor = <R>(fn: (tx: DB) => Promise<R>): Promise<R> =>
+      platform ? pipeFrameworkDoor('pipework.storage_sweep', fn) : pipeSystem().transaction(fn)
+
+    await inSweepDoor(async (tx: DB) => {
+      const rows = await tx.execute(sql`
+        DELETE FROM storage_file WHERE id IN (
+          SELECT id FROM storage_file WHERE expires_at IS NOT NULL AND expires_at <= now()
+          ORDER BY expires_at LIMIT ${limit} ${platform ? sql`` : sql`FOR UPDATE SKIP LOCKED`}
+        ) RETURNING *
+      `)
+      for (const row of rows) {
+        const file = rowToFile(row)
+        await audit(flow, tx, file.tenantId, 'expire', file.id, auditProjection(file))
+      }
+      expired = rows.length
+    })
+
+    const cutoff = Date.now() - TMP_MAX_AGE_MS
+    let batch: { tenantId: string; sha256: string; key: string }[] = []
+
+    const settle = async (): Promise<void> => {
+      if (batch.length === 0) return
+      const candidates = batch
+      batch = []
+      const present = await inSweepDoor(tx => tx.execute(sql`
+        SELECT tenant_id::text AS t, sha256 AS h FROM storage_file
+        WHERE tenant_id::text || ':' || sha256 IN (SELECT jsonb_array_elements_text(${JSON.stringify(candidates.map(c => `${c.tenantId}:${c.sha256}`))}::jsonb))
+      `))
+      const referenced = new Set(present.map(r => `${r['t'] as string}:${r['h'] as string}`))
+      for (const c of candidates) {
+        if (objects >= limit) return
+        if (referenced.has(`${c.tenantId}:${c.sha256}`)) continue
+        const removed = await inSweepDoor(async (tx: DB) => {
+          await lockContent(tx, c.tenantId, c.sha256)
+          const again = await tx.execute(sql`
+            SELECT 1 FROM storage_file WHERE tenant_id = ${c.tenantId} AND sha256 = ${c.sha256} LIMIT 1
+          `)
+          if (again.length > 0) return false
+          await backend.remove(c.key)
+          return true
+        })
+        if (removed) objects += 1
+      }
+    }
+
+    for await (const object of backend.list('tenants/')) {
+      if (objects >= limit && temp >= limit) break
+      const match = OBJECT_KEY.exec(object.key)
+      if (match !== null) {
+        if (objects < limit) batch.push({ tenantId: match[1]!, sha256: match[2]!, key: object.key })
+        if (batch.length >= 200) await settle()
+      } else if (TMP_KEY.test(object.key) && object.lastModified.getTime() < cutoff && temp < limit) {
+        await backend.remove(object.key)
+        temp += 1
+      }
+    }
+    await settle()
+    return { expired, objects, temp }
+  }
+
+  return {
+    put: o => doPut(null, o),
+    putFor: (t, o) => doPut(t, o),
+    get: id => doGet(null, id),
+    getFor: (t, id) => doGet(t, id),
+    find: q => doFind(null, q),
+    findFor: (t, q) => doFind(t, q),
+    open: id => doOpen(null, id),
+    openFor: (t, id) => doOpen(t, id),
+    signedUrl: (id, o) => doSignedUrl(null, id, o),
+    signedUrlFor: (t, id, o) => doSignedUrl(t, id, o),
+    delete: id => doDelete(null, id),
+    deleteFor: (t, id) => doDelete(t, id),
+    sweep: o => doSweep(o),
+  }
+}

package/src/infra/storage/index.ts

@@ -0,0 +1,9 @@
+export { createStorage } from './handle.js'
+export { s3, encryptionHeaders, PART_SIZE } from './s3.js'
+export { local } from './local.js'
+export type { S3Config, S3Encryption } from './s3.js'
+export type { LocalConfig } from './local.js'
+export type { StorageBackend, BackendObject, BackendSignedUrlOptions } from './backend.js'
+export type {
+  Storage, StorageConfig, StoredFile, PutOptions, FindOptions, SignedUrlOptions, SweepOptions, SweepResult,
+} from './handle.js'

package/src/infra/storage/local.ts

@@ -0,0 +1,104 @@
+import { createReadStream, createWriteStream } from 'node:fs'
+import { copyFile, mkdir, readdir, rename, rm, stat } from 'node:fs/promises'
+import { dirname, join, resolve, sep } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { pipeline } from 'node:stream/promises'
+import { Readable } from 'node:stream'
+import type { BackendObject, StorageBackend } from './backend.js'
+
+export interface LocalConfig {
+  /** Directory the files are written under; created on first write. */
+  readonly dir: string
+}
+
+/**
+ * Files on local disk, for development and tests. Refused by `storage.create` when
+ * its `environment` is `production`. There are no signed URLs: `signedUrl` throws
+ * here, so serve a file by streaming `open()` through `http.file()`.
+ *
+ * In a test, give each file its own directory (`mkdtemp`) and remove it in `afterAll`;
+ * rows written through the test harness roll back with its transaction, and the
+ * leftover blobs are then plain files in that directory.
+ */
+export function local(config: LocalConfig): StorageBackend {
+  const root = resolve(config.dir)
+
+  function pathOf(key: string): string {
+    const full = resolve(root, ...key.split('/'))
+    if (full !== root && !full.startsWith(root + sep)) {
+      throw new Error(`[pipework] storage local: key "${key}" escapes the storage directory.\n`)
+    }
+    return full
+  }
+
+  return {
+    name: 'local',
+
+    async put(key, body) {
+      const target = pathOf(key)
+      await mkdir(dirname(target), { recursive: true })
+      const partial = `${target}.${randomUUID()}.partial`
+      try {
+        await pipeline(Readable.from(body, { objectMode: false }), createWriteStream(partial))
+        await rename(partial, target)
+      } catch (err) {
+        await rm(partial, { force: true })
+        throw err
+      }
+    },
+
+    async exists(key) {
+      try {
+        return (await stat(pathOf(key))).isFile()
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return false
+        throw err
+      }
+    },
+
+    async copy(from, to) {
+      const target = pathOf(to)
+      await mkdir(dirname(target), { recursive: true })
+      await copyFile(pathOf(from), target)
+    },
+
+    async remove(key) {
+      await rm(pathOf(key), { force: true })
+    },
+
+    async read(key) {
+      const path = pathOf(key)
+      await stat(path)
+      return createReadStream(path)
+    },
+
+    async *list(prefix): AsyncGenerator<BackendObject> {
+      const walk = async function* (dir: string): AsyncGenerator<string> {
+        let entries
+        try {
+          entries = await readdir(dir, { withFileTypes: true })
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code === 'ENOENT') return
+          throw err
+        }
+        for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+          const full = join(dir, entry.name)
+          if (entry.isDirectory()) yield* walk(full)
+          else if (entry.isFile() && !entry.name.endsWith('.partial')) yield full
+        }
+      }
+      for await (const file of walk(root)) {
+        const key = file.slice(root.length + 1).split(sep).join('/')
+        if (!key.startsWith(prefix)) continue
+        yield { key, lastModified: (await stat(file)).mtime }
+      }
+    },
+
+    signedUrl() {
+      return Promise.reject(new Error(
+        '[pipework] The local storage backend has no signed URLs.\n\n' +
+        '  Stream the file with storage.open(id) and send it with http.file(), or use storage.s3(...).\n',
+      ))
+    },
+  }
+}

package/src/infra/storage/namespace.ts

@@ -0,0 +1,13 @@
+import { createStorage } from './handle.js'
+import { s3 } from './s3.js'
+import { local } from './local.js'
+
+/** Storage namespace — tenant-scoped, content-addressed file storage with signed URLs and retention. */
+export const storage = {
+  /** Creates a storage handle over a backend. */
+  create: createStorage,
+  /** S3-compatible backend (AWS S3, MinIO, R2): SigV4 over `fetch`, multipart streaming upload, optional server-side encryption. */
+  s3,
+  /** Local-disk backend for development and tests; refused in production. */
+  local,
+} as const