@strav/storage 1.0.0-alpha.27

package/README.md

@@ -0,0 +1,36 @@
+# @strav/storage
+
+Object storage / filesystem abstraction for Strav 1.0. Two drivers — local filesystem and S3-compatible (AWS / R2 / B2 / Tigris / MinIO via the `endpoint` option). Apps inject the abstract `Storage` token; the provider in the container picks the concrete driver. Same dependency shape as `@strav/cache` and `@strav/broadcast`.
+
+```ts
+import { Storage } from '@strav/storage'
+
+@inject()
+class ReportsController {
+  constructor(private readonly storage: Storage) {}
+
+  async upload(req: Request): Promise<Response> {
+    const body = await req.arrayBuffer()
+    await this.storage.put(`reports/${ulid()}.pdf`, body, {
+      contentType: 'application/pdf',
+      visibility: 'private',
+    })
+    return new Response(null, { status: 201 })
+  }
+
+  async share(path: string): Promise<string> {
+    return this.storage.signedUrl(path, { expiresIn: 3600 })
+  }
+}
+```
+
+Canonical docs live in [`docs/storage/README.md`](../../docs/storage/README.md).
+
+## What ships
+
+| Driver | Subpath | Notes |
+|---|---|---|
+| Local | `@strav/storage` (root) + `@strav/storage/local` | `Bun.file` + `Bun.write` + `node:fs/promises`. Single-node deployments + dev. |
+| S3-compatible | `@strav/storage/s3` | Bun's built-in `S3Client` — no third-party Bun S3 client dep. Works with AWS S3, Cloudflare R2, Backblaze B2, Tigris, MinIO via the `endpoint` option. |
+
+All paths funnel through a strict normalizer (no `../`, no absolute paths, no backslashes) so controller code stays portable between drivers. Visibility maps to S3 ACL ('public' → `public-read`, 'private' → `private`); on LocalStorage it's a hint only — apps serving uploads via a static handler get the "public" semantic for free.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@strav/storage",
+  "version": "1.0.0-alpha.27",
+  "description": "Strav storage layer — Storage abstraction + LocalStorage (Bun.file + node:fs) + S3Storage (Bun.S3Client, works with AWS / R2 / B2 / Tigris / MinIO via the endpoint option). Kernel-free; mirrors @strav/cache + @strav/broadcast.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./local": "./src/drivers/local/index.ts",
+    "./s3": "./src/drivers/s3/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/kernel": "1.0.0-alpha.27"
+  },
+  "peerDependencies": {
+    "@types/bun": ">=1.3.14"
+  },
+  "devDependencies": null
+}

package/src/drivers/local/index.ts

@@ -0,0 +1 @@
+export { LocalStorage, type LocalStorageOptions } from './local_storage.ts'

package/src/drivers/local/local_storage.ts

@@ -0,0 +1,363 @@
+/**
+ * `LocalStorage` — filesystem driver backed by `Bun.file` + `Bun.write`
+ * + `node:fs/promises`.
+ *
+ * Right driver for: dev, tests, single-node deployments with a real
+ * volume. Wrong driver for: serverless platforms with ephemeral disk
+ * (Fly Machines, Vercel, etc.), multi-node deployments where every
+ * node needs to see every file.
+ *
+ * `Bun.write` handles streams + Blobs + ArrayBuffers + strings
+ * natively. We surface a single `put` that takes any of them. Parent
+ * directories are created on demand — apps don't need to `mkdir`
+ * before `put`.
+ *
+ * Listing walks `fs.readdir({ withFileTypes: true })`. `recursive:
+ * true` traverses subdirectories; the default returns direct
+ * children only (matching the S3 driver's delimiter semantic).
+ *
+ * `visibility` is recorded but not enforced — POSIX mode bits don't
+ * map cleanly to "public vs private" across deployments. Apps that
+ * serve uploads via a static handler against `root` get the
+ * "public" semantic for free; signed-URL semantics live on the S3
+ * driver.
+ */
+
+import type { Dirent } from 'node:fs'
+import * as fs from 'node:fs/promises'
+import { dirname, join, sep as nativeSep, normalize, posix } from 'node:path'
+import { normalizePrefix } from '../../path.ts'
+import { Storage } from '../../storage.ts'
+import { StorageDriverError, StorageNotFoundError } from '../../storage_error.ts'
+import type {
+  ListEntry,
+  ListOptions,
+  ListResult,
+  PutOptions,
+  SignedUrlOptions,
+  StorageStat,
+  StorageWriteable,
+} from '../../types.ts'
+
+export interface LocalStorageOptions {
+  /**
+   * Absolute root directory. All `put`/`get`/`delete` paths join with
+   * this. Created on demand if missing.
+   */
+  root: string
+  /**
+   * Base URL prepended by `publicUrl()`. Typically the URL your static
+   * handler serves `root` at — e.g. `'https://cdn.acme.com'` or
+   * `'http://localhost:3000/files'`. Unset → `publicUrl()` throws.
+   */
+  publicBase?: string
+}
+
+const DEFAULT_LIST_LIMIT = 100
+const MAX_LIST_LIMIT = 1000
+
+export class LocalStorage extends Storage {
+  private readonly root: string
+  private readonly publicBase: string | undefined
+
+  constructor(options: LocalStorageOptions) {
+    super()
+    this.root = options.root
+    this.publicBase = options.publicBase
+  }
+
+  // ─── Reads ────────────────────────────────────────────────────────────────
+
+  override async get(path: string): Promise<Uint8Array> {
+    const key = this._normalize(path)
+    const file = Bun.file(this.full(key))
+    if (!(await file.exists())) {
+      throw new StorageNotFoundError(`LocalStorage: no object at "${key}".`, {
+        context: { path: key },
+      })
+    }
+    return new Uint8Array(await file.arrayBuffer())
+  }
+
+  override async getString(path: string): Promise<string> {
+    const key = this._normalize(path)
+    const file = Bun.file(this.full(key))
+    if (!(await file.exists())) {
+      throw new StorageNotFoundError(`LocalStorage: no object at "${key}".`, {
+        context: { path: key },
+      })
+    }
+    return file.text()
+  }
+
+  override async getStream(path: string): Promise<ReadableStream<Uint8Array>> {
+    const key = this._normalize(path)
+    const file = Bun.file(this.full(key))
+    if (!(await file.exists())) {
+      throw new StorageNotFoundError(`LocalStorage: no object at "${key}".`, {
+        context: { path: key },
+      })
+    }
+    return file.stream()
+  }
+
+  // ─── Writes ───────────────────────────────────────────────────────────────
+
+  override async put(
+    path: string,
+    contents: StorageWriteable,
+    // PutOptions are ignored on FS — recorded in docs.
+    _options?: PutOptions,
+  ): Promise<void> {
+    const key = this._normalize(path)
+    const target = this.full(key)
+    await fs.mkdir(dirname(target), { recursive: true })
+    try {
+      // `Bun.write` accepts string / Uint8Array / ArrayBuffer / Blob
+      // directly. ReadableStream isn't supported there — wrap it in a
+      // Response first so we can let `Bun.write` consume the buffered
+      // body. Memory-bounded by the caller's stream chunks; for large
+      // uploads to FS this is fine.
+      if (contents instanceof ReadableStream) {
+        // Drain the stream into a Uint8Array before write. Bun.write
+        // doesn't accept ReadableStream directly. For very large
+        // payloads, callers should stream to S3 instead — the FS
+        // driver is for single-node deployments where in-memory
+        // buffering of an upload is acceptable.
+        const buffered = await new Response(contents).bytes()
+        await Bun.write(target, buffered)
+      } else {
+        await Bun.write(target, contents as Parameters<typeof Bun.write>[1])
+      }
+    } catch (cause) {
+      throw new StorageDriverError(`LocalStorage: write failed for "${key}".`, {
+        context: { path: key },
+        cause,
+      })
+    }
+  }
+
+  // ─── Metadata ─────────────────────────────────────────────────────────────
+
+  override async exists(path: string): Promise<boolean> {
+    const key = this._normalize(path)
+    try {
+      await fs.access(this.full(key))
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  override async stat(path: string): Promise<StorageStat> {
+    const key = this._normalize(path)
+    let st: Awaited<ReturnType<typeof fs.stat>>
+    try {
+      st = await fs.stat(this.full(key))
+    } catch (cause) {
+      const code = (cause as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') {
+        throw new StorageNotFoundError(`LocalStorage: no object at "${key}".`, {
+          context: { path: key },
+        })
+      }
+      throw new StorageDriverError(`LocalStorage: stat failed for "${key}".`, {
+        context: { path: key, code },
+        cause,
+      })
+    }
+    return {
+      size: Number(st.size),
+      lastModified: st.mtime,
+    }
+  }
+
+  // ─── Lifecycle ────────────────────────────────────────────────────────────
+
+  override async delete(path: string): Promise<boolean> {
+    const key = this._normalize(path)
+    try {
+      await fs.unlink(this.full(key))
+      return true
+    } catch (cause) {
+      const code = (cause as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') return false
+      throw new StorageDriverError(`LocalStorage: delete failed for "${key}".`, {
+        context: { path: key, code },
+        cause,
+      })
+    }
+  }
+
+  override async copy(from: string, to: string): Promise<void> {
+    const src = this._normalize(from)
+    const dst = this._normalize(to)
+    const target = this.full(dst)
+    await fs.mkdir(dirname(target), { recursive: true })
+    try {
+      await fs.copyFile(this.full(src), target)
+    } catch (cause) {
+      const code = (cause as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') {
+        throw new StorageNotFoundError(`LocalStorage: source "${src}" does not exist.`, {
+          context: { from: src, to: dst },
+        })
+      }
+      throw new StorageDriverError(`LocalStorage: copy "${src}" → "${dst}" failed.`, {
+        context: { from: src, to: dst, code },
+        cause,
+      })
+    }
+  }
+
+  override async move(from: string, to: string): Promise<void> {
+    const src = this._normalize(from)
+    const dst = this._normalize(to)
+    const target = this.full(dst)
+    await fs.mkdir(dirname(target), { recursive: true })
+    try {
+      await fs.rename(this.full(src), target)
+      return
+    } catch (cause) {
+      const code = (cause as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') {
+        throw new StorageNotFoundError(`LocalStorage: source "${src}" does not exist.`, {
+          context: { from: src, to: dst },
+        })
+      }
+      if (code === 'EXDEV') {
+        // Cross-volume — fall back to copy + delete.
+        await fs.copyFile(this.full(src), target)
+        await fs.unlink(this.full(src))
+        return
+      }
+      throw new StorageDriverError(`LocalStorage: move "${src}" → "${dst}" failed.`, {
+        context: { from: src, to: dst, code },
+        cause,
+      })
+    }
+  }
+
+  // ─── Listing ──────────────────────────────────────────────────────────────
+
+  override async list(options: ListOptions = {}): Promise<ListResult> {
+    const limit = Math.min(options.limit ?? DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT)
+    const recursive = options.recursive ?? false
+    const prefix = options.prefix !== undefined ? normalizePrefix(options.prefix) : ''
+    const after = options.after
+
+    // If the prefix is a directory path (`reports/2026/`), descend
+    // straight into it. Otherwise walk the root + filter — that's the
+    // path for partial-prefix matches (`prefix: 'reports/2026/jan-'`).
+    let base = this.root
+    let walkRelBase = ''
+    let filterPrefix = prefix
+    if (prefix !== '' && prefix.endsWith('/')) {
+      // Strip the trailing slash and see if it's a real directory.
+      const dirPath = prefix.slice(0, -1)
+      try {
+        const st = await fs.stat(join(this.root, dirPath))
+        if (st.isDirectory()) {
+          base = join(this.root, dirPath)
+          walkRelBase = dirPath
+          filterPrefix = ''
+        }
+      } catch {
+        // Not a directory — fall through to root-walk + filter.
+      }
+    }
+
+    const collected: ListEntry[] = []
+    await this.walk(base, walkRelBase, recursive, (relPath, entry) => {
+      if (filterPrefix !== '' && !relPath.startsWith(filterPrefix)) return false
+      if (after !== undefined && relPath <= after) return false
+      collected.push({
+        path: relPath,
+        ...(entry.isDirectory()
+          ? { isDirectory: true }
+          : {
+              size: Number(entry.size),
+              lastModified: entry.mtime,
+              isDirectory: false,
+            }),
+      } as ListEntry)
+      return collected.length < limit + 1 // gather one extra so we know there's a next page
+    })
+
+    const entries = collected.slice(0, limit)
+    const cursor = collected.length > limit ? (entries.at(-1)?.path ?? undefined) : undefined
+    return cursor !== undefined ? { entries, cursor } : { entries }
+  }
+
+  // ─── URLs ─────────────────────────────────────────────────────────────────
+
+  override publicUrl(path: string): string {
+    const key = this._normalize(path)
+    if (this.publicBase === undefined) {
+      throw new StorageDriverError(
+        `LocalStorage: publicUrl("${key}") needs a configured \`publicBase\` (the URL your static handler serves \`root\` at).`,
+        { context: { path: key } },
+      )
+    }
+    return `${this.publicBase.replace(/\/$/, '')}/${key}`
+  }
+
+  override async signedUrl(_path: string, _options: SignedUrlOptions): Promise<string> {
+    throw new StorageDriverError(
+      'LocalStorage does not support signed URLs — there is no signing authority. Configure `publicBase` and serve via your static handler, or switch to the S3 driver for production.',
+    )
+  }
+
+  // ─── Internals ───────────────────────────────────────────────────────────
+
+  private full(key: string): string {
+    // Reassemble using the native separator (Windows compat) but
+    // collapse `..` defensively via `normalize` even though
+    // `normalizePath` already rejected them.
+    return normalize(join(this.root, key.split(posix.sep).join(nativeSep)))
+  }
+
+  private async walk(
+    dir: string,
+    relBase: string,
+    recursive: boolean,
+    visit: (
+      relPath: string,
+      entry: Awaited<ReturnType<typeof fs.stat>> & { isDirectory(): boolean },
+    ) => boolean,
+  ): Promise<boolean> {
+    let entries: Dirent[]
+    try {
+      entries = (await fs.readdir(dir, { withFileTypes: true })) as Dirent[]
+    } catch (cause) {
+      const code = (cause as NodeJS.ErrnoException).code
+      if (code === 'ENOENT') return true
+      throw new StorageDriverError(`LocalStorage: list walk failed at "${dir}".`, {
+        context: { dir, code },
+        cause,
+      })
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name))
+    for (const dirent of entries) {
+      const rel = relBase === '' ? dirent.name : `${relBase}/${dirent.name}`
+      if (dirent.isDirectory()) {
+        if (!recursive) {
+          // Emit the directory entry then skip its contents.
+          const cont = visit(rel, {
+            ...(await fs.stat(join(dir, dirent.name))),
+            isDirectory: () => true,
+          })
+          if (!cont) return false
+          continue
+        }
+        const cont = await this.walk(join(dir, dirent.name), rel, true, visit)
+        if (!cont) return false
+        continue
+      }
+      const st = await fs.stat(join(dir, dirent.name))
+      const cont = visit(rel, { ...st, isDirectory: () => false })
+      if (!cont) return false
+    }
+    return true
+  }
+}

package/src/drivers/s3/index.ts

@@ -0,0 +1,2 @@
+export { S3Storage, type S3StorageOptions } from './s3_storage.ts'
+export { type S3StorageConfig, S3StorageProvider } from './s3_storage_provider.ts'

package/src/drivers/s3/s3_storage.ts

@@ -0,0 +1,345 @@
+/**
+ * `S3Storage` — S3-compatible object storage driver backed by Bun's
+ * built-in `S3Client`.
+ *
+ * Works with AWS S3, Cloudflare R2, Backblaze B2, Tigris, MinIO, and
+ * anything else that speaks the S3 API. Region + bucket + credentials
+ * + endpoint (for non-AWS providers) configure the target. No
+ * third-party Bun S3 client dependency.
+ *
+ * Wire mapping:
+ *
+ *   - `get` / `getStream` → `client.file(key).arrayBuffer()` /
+ *     `client.file(key).stream()`.
+ *   - `put` → `client.write(key, data, { type, cacheControl, … })`.
+ *     Bun handles strings, Buffers, Blobs, Requests, Responses,
+ *     ReadableStreams (wrapped) and multipart upload chunking.
+ *   - `exists` / `stat` / `delete` → straight-through to the bucket
+ *     methods of the same name.
+ *   - `copy` — no native single-call copy in Bun's S3 surface; we
+ *     stream the source to the destination via `client.write(toKey,
+ *     client.file(fromKey))`.
+ *   - `list` → `client.list({ prefix, startAfter, maxKeys, delimiter })`
+ *     mapped to our `ListResult` shape. Cursor is the
+ *     `nextContinuationToken`.
+ *   - `publicUrl` → `publicBase + '/' + key`, throws when unset.
+ *   - `signedUrl` → `client.presign(key, { expiresIn, method })`.
+ *
+ * ACL mapping for `put({ visibility })`:
+ *
+ *   - `'public'`  → `acl: 'public-read'`
+ *   - `'private'` → `acl: 'private'` (also the default when omitted)
+ */
+
+import { S3Client, type S3ListObjectsOptions, type S3Options } from 'bun'
+import { normalizePrefix } from '../../path.ts'
+import { Storage } from '../../storage.ts'
+import { StorageDriverError, StorageNotFoundError } from '../../storage_error.ts'
+import type {
+  ListEntry,
+  ListOptions,
+  ListResult,
+  PutOptions,
+  SignedUrlOptions,
+  StorageStat,
+  StorageWriteable,
+} from '../../types.ts'
+
+export interface S3StorageOptions {
+  accessKeyId: string
+  secretAccessKey: string
+  bucket: string
+  /**
+   * AWS region — used for the default endpoint and signing.
+   * Non-AWS providers (R2, MinIO, B2) ignore the region; set it
+   * anyway (`'auto'` works) for signing.
+   */
+  region?: string
+  /**
+   * Override the S3 endpoint. Required for non-AWS providers:
+   *
+   *   - Cloudflare R2: `https://<account>.r2.cloudflarestorage.com`
+   *   - Backblaze B2:  `https://s3.<region>.backblazeb2.com`
+   *   - Tigris:        `https://t3.storage.dev`
+   *   - MinIO:         `http://localhost:9000` (dev / self-hosted)
+   */
+  endpoint?: string
+  /** Optional STS session token. */
+  sessionToken?: string
+  /** Force virtual-hosted-style addressing (vs path-style). Default backend's choice. */
+  virtualHostedStyle?: boolean
+  /**
+   * Public URL prefix returned by `publicUrl()`. Unset → `publicUrl()`
+   * throws (the bucket might be private; the framework doesn't try to
+   * guess). For AWS S3 buckets this is typically
+   * `https://<bucket>.s3.<region>.amazonaws.com`; for R2 it's the
+   * `r2.dev` URL or your custom domain.
+   */
+  publicBase?: string
+  /** Pre-constructed client for tests. */
+  client?: S3Client
+}
+
+const DEFAULT_LIST_LIMIT = 100
+const MAX_LIST_LIMIT = 1000
+
+export class S3Storage extends Storage {
+  private readonly client: S3Client
+  private readonly publicBase: string | undefined
+
+  constructor(options: S3StorageOptions) {
+    super()
+    this.publicBase = options.publicBase
+    if (options.client !== undefined) {
+      this.client = options.client
+    } else {
+      const clientOpts: S3Options = {
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+        bucket: options.bucket,
+      }
+      if (options.region !== undefined) clientOpts.region = options.region
+      if (options.endpoint !== undefined) clientOpts.endpoint = options.endpoint
+      if (options.sessionToken !== undefined) clientOpts.sessionToken = options.sessionToken
+      if (options.virtualHostedStyle !== undefined) {
+        clientOpts.virtualHostedStyle = options.virtualHostedStyle
+      }
+      this.client = new S3Client(clientOpts)
+    }
+  }
+
+  // ─── Reads ────────────────────────────────────────────────────────────────
+
+  override async get(path: string): Promise<Uint8Array> {
+    const key = this._normalize(path)
+    const file = this.client.file(key)
+    try {
+      const buffer = await file.arrayBuffer()
+      return new Uint8Array(buffer)
+    } catch (cause) {
+      throw this.wrapNotFoundOrDriver(cause, key, 'get')
+    }
+  }
+
+  override async getString(path: string): Promise<string> {
+    const key = this._normalize(path)
+    try {
+      return await this.client.file(key).text()
+    } catch (cause) {
+      throw this.wrapNotFoundOrDriver(cause, key, 'getString')
+    }
+  }
+
+  override async getStream(path: string): Promise<ReadableStream<Uint8Array>> {
+    const key = this._normalize(path)
+    try {
+      // Bun's S3File supports `.stream()` natively.
+      return this.client.file(key).stream() as unknown as ReadableStream<Uint8Array>
+    } catch (cause) {
+      throw this.wrapNotFoundOrDriver(cause, key, 'getStream')
+    }
+  }
+
+  // ─── Writes ───────────────────────────────────────────────────────────────
+
+  override async put(
+    path: string,
+    contents: StorageWriteable,
+    options: PutOptions = {},
+  ): Promise<void> {
+    const key = this._normalize(path)
+    const writeOpts: S3Options = {}
+    if (options.contentType !== undefined) writeOpts.type = options.contentType
+    if (options.contentEncoding !== undefined) writeOpts.contentEncoding = options.contentEncoding
+    // PutOptions.cacheControl and .metadata aren't exposed on Bun's
+    // current S3Options surface — when Bun lands them, plumb here.
+    // Today they're silently dropped; documented in docs/storage/api.md.
+    writeOpts.acl = options.visibility === 'public' ? 'public-read' : 'private'
+    try {
+      const payload = await this.coerceToWriteable(contents)
+      await this.client.write(key, payload, writeOpts)
+    } catch (cause) {
+      throw new StorageDriverError(`S3Storage: write failed for "${key}".`, {
+        context: { path: key },
+        cause,
+      })
+    }
+  }
+
+  // ─── Metadata ─────────────────────────────────────────────────────────────
+
+  override async exists(path: string): Promise<boolean> {
+    const key = this._normalize(path)
+    try {
+      return await this.client.exists(key)
+    } catch (cause) {
+      throw new StorageDriverError(`S3Storage: exists failed for "${key}".`, {
+        context: { path: key },
+        cause,
+      })
+    }
+  }
+
+  override async stat(path: string): Promise<StorageStat> {
+    const key = this._normalize(path)
+    let st: Awaited<ReturnType<S3Client['stat']>>
+    try {
+      st = await this.client.stat(key)
+    } catch (cause) {
+      throw this.wrapNotFoundOrDriver(cause, key, 'stat')
+    }
+    const result: StorageStat = {
+      size: Number(st.size ?? 0),
+      lastModified: st.lastModified ? new Date(st.lastModified) : new Date(0),
+    }
+    if (st.type !== undefined) result.contentType = st.type
+    if (st.etag !== undefined) result.etag = st.etag
+    return result
+  }
+
+  // ─── Lifecycle ────────────────────────────────────────────────────────────
+
+  override async delete(path: string): Promise<boolean> {
+    const key = this._normalize(path)
+    // S3 doesn't tell us whether the key was actually there (DELETE is
+    // idempotent on S3). Check first to give the same semantics as
+    // LocalStorage.delete — true iff a real object went away.
+    const existed = await this.exists(key)
+    if (!existed) return false
+    try {
+      await this.client.delete(key)
+      return true
+    } catch (cause) {
+      throw new StorageDriverError(`S3Storage: delete failed for "${key}".`, {
+        context: { path: key },
+        cause,
+      })
+    }
+  }
+
+  override async copy(from: string, to: string): Promise<void> {
+    const src = this._normalize(from)
+    const dst = this._normalize(to)
+    if (!(await this.exists(src))) {
+      throw new StorageNotFoundError(`S3Storage: source "${src}" does not exist.`, {
+        context: { from: src, to: dst },
+      })
+    }
+    try {
+      // S3Client.write accepts an S3File — Bun streams source → dest
+      // via the bucket's own copy operation when possible.
+      await this.client.write(dst, this.client.file(src))
+    } catch (cause) {
+      throw new StorageDriverError(`S3Storage: copy "${src}" → "${dst}" failed.`, {
+        context: { from: src, to: dst },
+        cause,
+      })
+    }
+  }
+
+  // `move` falls back to the base implementation (copy + delete).
+  // Server-side rename isn't a single S3 op anyway — that's exactly
+  // what the base does.
+
+  // ─── Listing ──────────────────────────────────────────────────────────────
+
+  override async list(options: ListOptions = {}): Promise<ListResult> {
+    const limit = Math.min(options.limit ?? DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT)
+    const recursive = options.recursive ?? false
+    const prefix = options.prefix !== undefined ? normalizePrefix(options.prefix) : ''
+
+    const input: S3ListObjectsOptions = { maxKeys: limit }
+    if (prefix !== '') input.prefix = prefix
+    if (!recursive) input.delimiter = '/'
+    if (options.after !== undefined) {
+      // `after` is our cursor — interpret as Bun's continuationToken first
+      // since that's how we issue cursors. Apps that pass an
+      // arbitrary key value also work via `startAfter`.
+      input.continuationToken = options.after
+    }
+
+    let resp: Awaited<ReturnType<S3Client['list']>>
+    try {
+      resp = await this.client.list(input)
+    } catch (cause) {
+      throw new StorageDriverError('S3Storage: list failed.', {
+        context: { prefix, recursive },
+        cause,
+      })
+    }
+
+    const entries: ListEntry[] = []
+    for (const cp of resp.commonPrefixes ?? []) {
+      entries.push({ path: cp.prefix, isDirectory: true })
+    }
+    for (const obj of resp.contents ?? []) {
+      const entry: ListEntry = { path: obj.key }
+      if (obj.size !== undefined) entry.size = obj.size
+      if (obj.lastModified !== undefined) entry.lastModified = new Date(obj.lastModified)
+      entries.push(entry)
+    }
+
+    const result: ListResult = { entries }
+    if (resp.isTruncated && resp.nextContinuationToken !== undefined) {
+      result.cursor = resp.nextContinuationToken
+    }
+    return result
+  }
+
+  // ─── URLs ─────────────────────────────────────────────────────────────────
+
+  override publicUrl(path: string): string {
+    const key = this._normalize(path)
+    if (this.publicBase === undefined) {
+      throw new StorageDriverError(
+        `S3Storage: publicUrl("${key}") needs a configured \`publicBase\` (the URL your bucket is served at; e.g. https://<bucket>.s3.<region>.amazonaws.com for AWS, or your r2.dev / custom domain for R2).`,
+        { context: { path: key } },
+      )
+    }
+    return `${this.publicBase.replace(/\/$/, '')}/${key}`
+  }
+
+  override async signedUrl(path: string, options: SignedUrlOptions): Promise<string> {
+    const key = this._normalize(path)
+    try {
+      return this.client.presign(key, {
+        expiresIn: options.expiresIn,
+        method: options.method ?? 'GET',
+      })
+    } catch (cause) {
+      throw new StorageDriverError(`S3Storage: presign failed for "${key}".`, {
+        context: { path: key },
+        cause,
+      })
+    }
+  }
+
+  // ─── Internals ────────────────────────────────────────────────────────────
+
+  private wrapNotFoundOrDriver(cause: unknown, key: string, op: string): Error {
+    const message = (cause as { message?: string }).message ?? ''
+    const code = (cause as { code?: string }).code
+    // Bun surfaces missing keys as either NoSuchKey, 404, or "not
+    // found" depending on the backend. Match liberally.
+    if (code === 'NoSuchKey' || message.includes('404') || /not\s*found/i.test(message)) {
+      return new StorageNotFoundError(`S3Storage: no object at "${key}".`, {
+        context: { path: key, op },
+      })
+    }
+    return new StorageDriverError(`S3Storage: ${op} failed for "${key}".`, {
+      context: { path: key, op },
+      cause,
+    })
+  }
+
+  private async coerceToWriteable(
+    contents: StorageWriteable,
+  ): Promise<Parameters<S3Client['write']>[1]> {
+    if (contents instanceof ReadableStream) {
+      // Bun's S3 write accepts Response — wrap so multipart upload
+      // streams the stream chunk-by-chunk.
+      return new Response(contents)
+    }
+    return contents as Parameters<S3Client['write']>[1]
+  }
+}

package/src/drivers/s3/s3_storage_provider.ts

@@ -0,0 +1,55 @@
+/**
+ * `S3StorageProvider` — wires `S3Storage` under the `Storage` token.
+ * Apps register this INSTEAD OF `StorageProvider` to use an
+ * S3-compatible backplane (AWS / R2 / B2 / Tigris / MinIO).
+ */
+
+import { type Application, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { Storage } from '../../storage.ts'
+import { StorageConfigError } from '../../storage_error.ts'
+import { S3Storage, type S3StorageOptions } from './s3_storage.ts'
+
+export interface S3StorageConfig extends Omit<S3StorageOptions, 'client'> {
+  driver: 's3'
+}
+
+export class S3StorageProvider extends ServiceProvider {
+  override readonly name = 'storage'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(Storage, (c) => {
+      const cfg = c.resolve(ConfigRepository).get('storage') as S3StorageConfig | undefined
+      if (cfg === undefined || cfg.driver !== 's3') {
+        throw new StorageConfigError(
+          'S3StorageProvider: `config.storage` must have `driver: "s3"`.',
+        )
+      }
+      if (!cfg.accessKeyId || !cfg.secretAccessKey || !cfg.bucket) {
+        throw new StorageConfigError(
+          'S3StorageProvider: `accessKeyId`, `secretAccessKey`, and `bucket` are required.',
+        )
+      }
+      return new S3Storage({
+        accessKeyId: cfg.accessKeyId,
+        secretAccessKey: cfg.secretAccessKey,
+        bucket: cfg.bucket,
+        ...(cfg.region !== undefined ? { region: cfg.region } : {}),
+        ...(cfg.endpoint !== undefined ? { endpoint: cfg.endpoint } : {}),
+        ...(cfg.sessionToken !== undefined ? { sessionToken: cfg.sessionToken } : {}),
+        ...(cfg.virtualHostedStyle !== undefined
+          ? { virtualHostedStyle: cfg.virtualHostedStyle }
+          : {}),
+        ...(cfg.publicBase !== undefined ? { publicBase: cfg.publicBase } : {}),
+      })
+    })
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(Storage)
+  }
+
+  override async shutdown(app: Application): Promise<void> {
+    await app.resolve(Storage).close()
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// Public API of @strav/storage.
+//
+// Root barrel exports the primitive — `Storage` base class + types +
+// errors + the LocalStorage provider. Drivers ship under subpaths:
+//   - `@strav/storage/local`  (re-exports for explicit construction)
+//   - `@strav/storage/s3`     (S3-compatible: AWS / R2 / B2 / Tigris / MinIO)
+
+export { LocalStorage, type LocalStorageOptions } from './drivers/local/local_storage.ts'
+export { normalizePath, normalizePrefix } from './path.ts'
+export { Storage } from './storage.ts'
+export {
+  StorageConfigError,
+  StorageDriverError,
+  StorageError,
+  StorageNotFoundError,
+  StoragePathError,
+} from './storage_error.ts'
+export { type LocalStorageConfig, StorageProvider } from './storage_provider.ts'
+export type {
+  ListEntry,
+  ListOptions,
+  ListResult,
+  PutOptions,
+  SignedUrlOptions,
+  StorageStat,
+  StorageWriteable,
+} from './types.ts'

package/src/path.ts

@@ -0,0 +1,100 @@
+/**
+ * Path normalization + safety check.
+ *
+ * All public `Storage` methods funnel input through `normalizePath()`
+ * before handing to the driver. The rules:
+ *
+ *   - POSIX-style only. Backslashes are illegal (would let Windows
+ *     callers smuggle path-segment confusion past S3 → FS portability).
+ *   - No `..` segments anywhere — even `a/../b` is rejected (collapsing
+ *     would conflate two distinct caller intents; rejecting forces
+ *     callers to be explicit).
+ *   - No absolute paths (leading `/`). The FS driver joins the input
+ *     with its `root`; an absolute path would escape that root.
+ *   - No empty segments (`a//b`), no `.` segments (`a/./b`) — both
+ *     trip the parser on some backends; reject for cross-driver
+ *     parity.
+ *   - No control characters (< 0x20, 0x7F).
+ *   - Leading + trailing whitespace trimmed; bare paths rejected.
+ *
+ * Throws `StoragePathError` on any rejection. The error includes the
+ * offending path so callers can log + fix at the source.
+ */
+
+import { StoragePathError } from './storage_error.ts'
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching control chars is the point — we reject paths containing them
+const CONTROL_CHAR = /[\x00-\x1f\x7f]/
+
+/**
+ * Same rules as `normalizePath` but tolerates a trailing `/` —
+ * prefixes describe ranges of keys, not individual objects, and
+ * `reports/2026/` is the natural shape for "everything under 2026".
+ * The trailing slash is preserved on output so drivers can use the
+ * result verbatim in their backend's prefix-match logic.
+ *
+ * The empty string is allowed (return as-is — "everything from root").
+ */
+export function normalizePrefix(input: string): string {
+  if (typeof input !== 'string') {
+    throw new StoragePathError(`Storage prefix must be a string; got: ${typeof input}`)
+  }
+  const trimmed = input.trim()
+  if (trimmed.length === 0) return ''
+  const hasTrailing = trimmed.endsWith('/')
+  const stripped = hasTrailing ? trimmed.slice(0, -1) : trimmed
+  if (stripped.length === 0) {
+    // Bare "/" — same problem as an absolute path.
+    throw new StoragePathError('Storage prefix "/" is not valid — use the empty string for root.')
+  }
+  const normalized = normalizePath(stripped)
+  return hasTrailing ? `${normalized}/` : normalized
+}
+
+export function normalizePath(input: string): string {
+  if (typeof input !== 'string') {
+    throw new StoragePathError(`Storage path must be a string; got: ${typeof input}`)
+  }
+  const trimmed = input.trim()
+  if (trimmed.length === 0) {
+    throw new StoragePathError('Storage path is empty.')
+  }
+  if (trimmed.includes('\\')) {
+    throw new StoragePathError(
+      `Storage path "${trimmed}" contains backslashes — use forward slashes only.`,
+      { context: { path: trimmed } },
+    )
+  }
+  if (trimmed.startsWith('/')) {
+    throw new StoragePathError(
+      `Storage path "${trimmed}" must be relative — leading "/" not allowed.`,
+      { context: { path: trimmed } },
+    )
+  }
+  if (CONTROL_CHAR.test(trimmed)) {
+    throw new StoragePathError(`Storage path "${trimmed}" contains a control character.`, {
+      context: { path: trimmed },
+    })
+  }
+  const segments = trimmed.split('/')
+  for (const segment of segments) {
+    if (segment.length === 0) {
+      throw new StoragePathError(
+        `Storage path "${trimmed}" has an empty segment (consecutive slashes).`,
+        { context: { path: trimmed } },
+      )
+    }
+    if (segment === '..') {
+      throw new StoragePathError(
+        `Storage path "${trimmed}" contains ".." — directory traversal not allowed.`,
+        { context: { path: trimmed } },
+      )
+    }
+    if (segment === '.') {
+      throw new StoragePathError(`Storage path "${trimmed}" contains "." segment — strip it.`, {
+        context: { path: trimmed },
+      })
+    }
+  }
+  return trimmed
+}

package/src/storage.ts

@@ -0,0 +1,140 @@
+/**
+ * `Storage` — abstract base + container token.
+ *
+ * Non-`abstract` on purpose: serves as the `app.singleton(Storage,
+ * factory)` token (same trade-off as `Cache` / `Broadcaster`).
+ * Subclasses MUST override the primitives; the defaults throw to
+ * surface forgotten overrides during development.
+ *
+ * Driver primitives:
+ *
+ *   - `get(path)` → `Uint8Array`
+ *   - `put(path, contents, options?)`
+ *   - `exists(path)` → `boolean`
+ *   - `stat(path)` → `StorageStat`
+ *   - `delete(path)` → `boolean` (true if a row was actually removed)
+ *   - `copy(from, to)`
+ *   - `list(options?)` → `ListResult`
+ *   - `publicUrl(path)` → `string` (throws when `publicBase` unset)
+ *   - `signedUrl(path, options)` → `string`
+ *
+ * The base provides:
+ *
+ *   - `getString(path, encoding?)` — UTF-8 decoded `get`
+ *   - `getStream(path)` — driver overrides to stream; the base
+ *     synthesizes a one-chunk `ReadableStream` from `get` as a
+ *     fallback so apps can always rely on the API
+ *   - `move(from, to)` — `copy` then `delete`. Drivers override when
+ *     the backend has a single-call equivalent (S3 `copyObject` +
+ *     `deleteObject`, FS `rename`)
+ *   - `close()` — default no-op
+ *
+ * All path arguments funnel through `normalizePath` (see `path.ts`)
+ * before reaching the driver. The base handles the normalization;
+ * driver overrides receive already-normalized strings.
+ */
+
+import { normalizePath } from './path.ts'
+import type {
+  ListOptions,
+  ListResult,
+  PutOptions,
+  SignedUrlOptions,
+  StorageStat,
+  StorageWriteable,
+} from './types.ts'
+
+export class Storage {
+  // ─── Primitives — subclass MUST override ─────────────────────────────────
+
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  get(path: string): Promise<Uint8Array> {
+    throw new Error('Storage.get must be overridden by the driver subclass.')
+  }
+  put(
+    // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+    path: string,
+    // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+    contents: StorageWriteable,
+    // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+    options?: PutOptions,
+  ): Promise<void> {
+    throw new Error('Storage.put must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  exists(path: string): Promise<boolean> {
+    throw new Error('Storage.exists must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  stat(path: string): Promise<StorageStat> {
+    throw new Error('Storage.stat must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  delete(path: string): Promise<boolean> {
+    throw new Error('Storage.delete must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  copy(from: string, to: string): Promise<void> {
+    throw new Error('Storage.copy must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  list(options?: ListOptions): Promise<ListResult> {
+    throw new Error('Storage.list must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  publicUrl(path: string): string {
+    throw new Error('Storage.publicUrl must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  signedUrl(path: string, options: SignedUrlOptions): Promise<string> {
+    throw new Error('Storage.signedUrl must be overridden by the driver subclass.')
+  }
+
+  // ─── Base-class compositions ─────────────────────────────────────────────
+
+  /** UTF-8 decoded `get`. Drivers may override for efficiency. */
+  async getString(path: string): Promise<string> {
+    const bytes = await this.get(path)
+    return new TextDecoder().decode(bytes)
+  }
+
+  /**
+   * Stream a key's contents. The default implementation reads the
+   * whole object via `get` and emits a single chunk — drivers that
+   * have native streaming (LocalStorage via `Bun.file().stream()`,
+   * S3 via `S3File.stream()`) should override.
+   */
+  async getStream(path: string): Promise<ReadableStream<Uint8Array>> {
+    const bytes = await this.get(path)
+    return new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(bytes)
+        controller.close()
+      },
+    })
+  }
+
+  /**
+   * `copy` then `delete`. Drivers with a server-side rename
+   * (LocalStorage via `fs.rename`) override; the base fallback works
+   * for every driver.
+   */
+  async move(from: string, to: string): Promise<void> {
+    await this.copy(from, to)
+    await this.delete(from)
+  }
+
+  /** Resource cleanup. Default no-op; S3Storage doesn't need teardown. */
+  async close(): Promise<void> {}
+
+  // ─── Internal helpers — drivers call into these ──────────────────────────
+
+  /**
+   * Validate + normalize a single path. Drivers wrap their entry
+   * points via `this._normalize(path)` so the rejection happens
+   * BEFORE any backend call — saves a round-trip on garbage input.
+   */
+  protected _normalize(path: string): string {
+    return normalizePath(path)
+  }
+}

package/src/storage_error.ts

@@ -0,0 +1,75 @@
+/**
+ * Typed error hierarchy. Same shape as `@strav/cache` /
+ * `@strav/broadcast` — base `StorageError` extending `StravError`,
+ * narrower subclasses with stable `code`s apps branch on.
+ */
+
+import { StravError } from '@strav/kernel'
+
+interface StorageErrorOptions {
+  code?: string
+  status?: number
+  context?: Record<string, unknown>
+  cause?: unknown
+}
+
+export class StorageError extends StravError {
+  constructor(message: string, options: StorageErrorOptions = {}) {
+    super(
+      message,
+      { code: options.code ?? 'storage.error', status: options.status ?? 500 },
+      {
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      },
+    )
+  }
+}
+
+/** Provider boot — missing config, unreachable backend at construction. */
+export class StorageConfigError extends StorageError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'storage.config',
+      status: 500,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+/** Driver-side I/O failure (network, disk, signed-URL refused, etc.). */
+export class StorageDriverError extends StorageError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'storage.driver',
+      status: 502,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}
+
+/** `get` / `stat` / `copy` / `move` on a missing key. `delete` returns `false` instead. */
+export class StorageNotFoundError extends StorageError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'storage.not_found',
+      status: 404,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+/** Path normalization rejection — `../` traversal, absolute path, illegal chars. */
+export class StoragePathError extends StorageError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'storage.path',
+      status: 400,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}

package/src/storage_provider.ts

@@ -0,0 +1,57 @@
+/**
+ * `StorageProvider` — wires `LocalStorage` under the `Storage` token
+ * by default.
+ *
+ * Apps that want the S3 backplane swap providers:
+ *
+ *   import { StorageProvider } from '@strav/storage'
+ *   import { S3StorageProvider } from '@strav/storage/s3'
+ *
+ *   providers: [
+ *     ...,
+ *     new S3StorageProvider(),    // instead of StorageProvider
+ *   ]
+ *
+ * Both providers register under the same `Storage` token, so app code
+ * injecting `Storage` doesn't change between dev and prod.
+ *
+ * Eager singleton — config errors surface at boot rather than on the
+ * first `storage.put()` call.
+ */
+
+import { type Application, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { LocalStorage, type LocalStorageOptions } from './drivers/local/local_storage.ts'
+import { Storage } from './storage.ts'
+import { StorageConfigError } from './storage_error.ts'
+
+export interface LocalStorageConfig extends LocalStorageOptions {
+  driver: 'local'
+}
+
+export class StorageProvider extends ServiceProvider {
+  override readonly name = 'storage'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(Storage, (c) => {
+      const cfg = c.resolve(ConfigRepository).get('storage') as LocalStorageConfig | undefined
+      if (cfg === undefined || cfg.driver !== 'local' || !cfg.root) {
+        throw new StorageConfigError(
+          'StorageProvider: `config.storage.root` is required (set `config/storage.ts` with `{ driver: "local", root: "storage/uploads" }`).',
+        )
+      }
+      return new LocalStorage({
+        root: cfg.root,
+        ...(cfg.publicBase !== undefined ? { publicBase: cfg.publicBase } : {}),
+      })
+    })
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(Storage)
+  }
+
+  override async shutdown(app: Application): Promise<void> {
+    await app.resolve(Storage).close()
+  }
+}

package/src/types.ts

@@ -0,0 +1,121 @@
+/**
+ * Public types for `@strav/storage`.
+ *
+ * Drivers implement a tight set of primitive ops + URL helpers; the
+ * abstract base composes higher-level helpers (`getString`,
+ * `getStream`, `move`) on top.
+ */
+
+/**
+ * What `put()` accepts as a body. Strings are encoded as UTF-8.
+ * `ReadableStream` is preferred for large uploads — drivers stream
+ * the payload to the backend instead of buffering in memory.
+ */
+export type StorageWriteable = string | Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>
+
+/**
+ * What `stat()` returns about an object.
+ *
+ * `contentType` and `etag` are optional — drivers populate them when
+ * the backend supplies them (S3 always; LocalStorage doesn't track
+ * content-type, leaves it `undefined`).
+ */
+export interface StorageStat {
+  /** Byte count. */
+  size: number
+  lastModified: Date
+  /** MIME type the object was stored under. Optional. */
+  contentType?: string
+  /** Provider-side strong hash, when available. */
+  etag?: string
+}
+
+export interface PutOptions {
+  /**
+   * MIME type. On S3 this rides on the `Content-Type` header and is
+   * returned from `stat()`. On LocalStorage it's ignored — the FS
+   * stores bytes, not media types.
+   */
+  contentType?: string
+  /** Sets the `Cache-Control` response header on S3 GETs. Ignored on FS. */
+  cacheControl?: string
+  /** Sets `Content-Encoding`. Ignored on FS. */
+  contentEncoding?: string
+  /**
+   * User-defined key/value metadata stored alongside the object.
+   * Round-trips on S3 (as `x-amz-meta-*`); ignored on FS.
+   */
+  metadata?: Record<string, string>
+  /**
+   * Object visibility. Default `'private'`.
+   *
+   *   - `'private'` — the object is only accessible via signed URLs.
+   *     S3 sets `acl: 'private'`; LocalStorage records this as a hint
+   *     but enforces nothing (filesystem permissions don't map
+   *     cleanly across deployments).
+   *   - `'public'` — anyone can read the object. S3 sets
+   *     `acl: 'public-read'`. LocalStorage assumes the configured
+   *     `publicBase` is served by your static handler.
+   */
+  visibility?: 'private' | 'public'
+}
+
+export interface ListOptions {
+  /**
+   * Limit results to keys beginning with this prefix. POSIX-style
+   * (`reports/2026/`).
+   */
+  prefix?: string
+  /**
+   * Cursor from a previous `ListResult.cursor`. Resume listing past
+   * the last key returned.
+   */
+  after?: string
+  /**
+   * Max entries to return in one page. Drivers cap higher values:
+   * S3 maxes at 1000, the filesystem driver matches that ceiling.
+   * Default `100`.
+   */
+  limit?: number
+  /**
+   * When `true`, walks into subdirectories (FS) / treats every key
+   * as a flat namespace (S3 — keys with `/` already span "folders").
+   * Default `false`: FS returns only direct children; S3 honours the
+   * `Delimiter: '/'` semantic so subdirectory prefixes surface as
+   * `isDirectory: true` entries.
+   */
+  recursive?: boolean
+}
+
+export interface ListEntry {
+  /** Key relative to the storage root. POSIX-style. */
+  path: string
+  /** Byte count. Undefined for directory entries on FS. */
+  size?: number
+  lastModified?: Date
+  /**
+   * `true` for "common prefix" entries on S3 with delimiter
+   * semantics, and for FS directories. `false` / undefined for
+   * regular files.
+   */
+  isDirectory?: boolean
+}
+
+export interface ListResult {
+  entries: ListEntry[]
+  /** When set, pass back as `ListOptions.after` to fetch the next page. */
+  cursor?: string
+}
+
+export interface SignedUrlOptions {
+  /** Expiry in seconds. Required — pre-signed URLs without bounds are an anti-pattern. */
+  expiresIn: number
+  /** HTTP method the URL is signed for. Default `'GET'`. */
+  method?: 'GET' | 'PUT' | 'HEAD' | 'DELETE'
+  /**
+   * Override the response `Content-Type` when the URL is fetched.
+   * S3 sets the `response-content-type` query param; ignored on FS
+   * (which can't sign URLs anyway).
+   */
+  responseContentType?: string
+}