@ultimat3/storage 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @ultimat3/storage 🗄️
+
+Named disks. **Call sites name a disk, never a driver.**
+
+```ts
+import { defineStorage, disk, localDriver, s3Driver, scopedKey } from '@ultimat3/storage';
+
+defineStorage({
+  disks: {
+    uploads: localDriver({ root: '.storage/uploads' }),
+    media: s3Driver({ bucket: 'media', endpoint: process.env.S3_ENDPOINT, forcePathStyle: true }),
+  },
+  default: 'uploads', // omit and the first disk wins
+});
+
+await disk('media').put(scopedKey(orgId, 'avatars', 'a.png'), bytes, { contentType: 'image/png' });
+```
+
+Swapping `local` for `s3` in `app.config.ts` changes no call site. `x dev` needs no MinIO.
+
+## Drivers
+
+| Driver | Backing | For | Signed URLs |
+|---|---|---|---|
+| `localDriver` | `Bun.file`/`Bun.write`, one root dir | dev, tests, single-node | HMAC + dev route |
+| `s3Driver` | `Bun.s3` | prod: MinIO, R2, AWS | provider presign |
+
+One S3 driver covers all three backends — the difference is `endpoint` + `forcePathStyle`.
+Credentials are **env var NAMES** (`accessKeyIdEnv`, default `S3_ACCESS_KEY_ID`), never
+literals: a key in `app.config.ts` is a key in git. Missing ones throw `X_ENV_MISSING`.
+`localDriver` keeps content type and etag in a `<root>/.meta/` sidecar so `get()` round-trips
+`put()`; sidecars never appear in `list()`.
+
+## Keys
+
+`assertSafeKey()` runs on every key before it reaches a driver. Rejected: `..` segments,
+absolute keys, backslashes, NUL/control bytes, percent-encoded separators (`%2e`, `%2f`),
+empty segments, over 1024 chars. No sanitising — a key that needed fixing was built wrong.
+`scopedKey('org-1', 'avatars', 'a.png')` is `org/org-1/avatars/a.png`; guard every
+client-supplied key with `isWithinOrg(key, ctx.actor.orgId)`.
+
+## Signed URLs
+
+The HMAC covers the **constraints**, not just the key —
+`v1 \n METHOD \n key \n expiresAt \n maxBytes \n contentType`.
+A client that edits `?x-max=` invalidates the signature — it cannot widen what it was granted.
+Verification is constant-time, checks the signature *before* the expiry (a forged URL never
+learns it was merely late), takes a `Clock` so tests freeze time, and returns
+`{ ok: false, reason }` rather than throwing — `malformed | unsafe-key | signature-mismatch |
+expired`. S3 presign covers method, expiry and content type but **not** `maxBytes`: S3 has no
+header for it, so size stays a server-side `validateUpload()` check.
+
+## Uploads sniff the content type
+
+`Content-Type` is attacker-controlled. A `.png` that is really an HTML document is stored XSS
+the moment a surface serves it back with the declared type. `validateUpload()` reads the magic
+bytes (PNG, JPEG, GIF, WebP, PDF, ZIP/OOXML, SVG, MP4, HTML, plain text) and rejects any
+payload whose bytes contradict the declaration. Checks run cheapest-first: key → size →
+allowlist → sniff → checksum.
+
+`validateUpload({ key, declaredContentType, bytes }, uploadPolicy({ maxBytes: 5e6 }))`
+
+## Errors
+
+| Code | Fires when |
+|---|---|
+| `X_STORAGE_DISK_UNKNOWN` | `disk(name)` is not in `storage.disks`; cause lists the real ones |
+| `X_STORAGE_NOT_FOUND` | `get`/`stream` on a key that does not exist |
+| `X_STORAGE_PATH_UNSAFE` | traversal, absolute key, backslash, NUL, `%2e`, empty segment |
+| `X_STORAGE_TOO_LARGE` | payload over the policy `maxBytes` |
+| `X_STORAGE_TYPE_REJECTED` | declared type off the allowlist, or contradicted by magic bytes |
+| `X_STORAGE_CHECKSUM_MISMATCH` | supplied base64 SHA-256 does not describe the bytes |
+| `X_NOT_IMPLEMENTED` | S3 user metadata |
+| `X_IMAGE_UNSUPPORTED` | core's: an `avif`/`webp` encode, or a source no built-in decoder reads |
+| `X_IMAGE_DECODE_FAILED` | core's: truncated or corrupt image bytes |
+
+## Images
+
+`variantKey()`, `srcsetDescriptors()`, `fitDimensions()` are pure — `@ultimat3/seo` builds
+`srcset` from them without decoding a byte.
+
+`transformImage()` and `blurPlaceholder()` are real, over `@ultimat3/core`'s zero-dependency
+pipeline. **It encodes `png` and `jpeg`, nothing else** — `avif`/`webp` remain key and `srcset`
+math, and asking for their bytes rejects with core's `X_IMAGE_UNSUPPORTED` naming the two that
+work; produce them through a CDN or a custom `ImageTransformDriver`. `png` is the only output
+that keeps alpha. The encoded size is always exactly `fitDimensions()`, so the `width`/`height`
+`@ultimat3/seo` already wrote into the tag match the bytes — `contain` fits inside the box, it
+does not letterbox to it. `blurPlaceholder()` returns a real 16px-wide PNG `data:` URI.
+`bun test` from `packages/storage`.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ultimat3/storage",
+  "version": "1.0.0",
+  "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/storage"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0"
+  }
+}

package/src/driver-local.ts

@@ -0,0 +1,196 @@
+// Single responsibility: the dev-default disk — a real, working driver over `Bun.file` /
+// `Bun.write` rooted at one directory, so `x dev` needs no MinIO and no cloud account.
+// Content type, etag and user metadata live in a sidecar under `.meta/`: a POSIX file has
+// nowhere to keep them, and `get` must round-trip exactly what `put` was handed.
+
+import { type Clock, systemClock } from '@ultimat3/core';
+import {
+  DEFAULT_CONTENT_TYPE,
+  DEFAULT_LIST_LIMIT,
+  etagOf,
+  type ListOptions,
+  type ListPage,
+  type PutOptions,
+  type SignedUrlOptions,
+  type StorageBody,
+  type StorageDriver,
+  type StorageObject,
+  type StorageRead,
+  sha256Base64,
+  toBytes,
+} from './driver';
+import { checksumMismatch, objectNotFound } from './errors';
+import { assertSafeKey } from './path';
+import { buildSignedUrl } from './signed-url';
+
+const META_DIR = '.meta';
+const DRIVER_NAME = 'local';
+
+export interface LocalDriverOptions {
+  /** Directory the disk owns outright. Created on first write. */
+  readonly root: string;
+  /** HMAC secret for signed URLs. Production must pass one; dev falls back to a fixed string. */
+  readonly signingSecret?: string | undefined;
+  /** Route prefix the dev server serves signed URLs from. */
+  readonly baseUrl?: string | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+interface Sidecar {
+  readonly contentType: string;
+  readonly etag: string;
+  readonly cacheControl?: string | undefined;
+  readonly metadata?: Readonly<Record<string, string>> | undefined;
+}
+
+function parseSidecar(raw: unknown): Sidecar | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const record = raw as Record<string, unknown>;
+  const contentType = record['contentType'];
+  const etag = record['etag'];
+  if (typeof contentType !== 'string' || typeof etag !== 'string') return undefined;
+  return { contentType, etag };
+}
+
+export function localDriver(options: LocalDriverOptions): StorageDriver {
+  const root = options.root.replace(/\/+$/, '');
+  const clock = options.clock ?? systemClock;
+  const baseUrl = options.baseUrl ?? `/_storage/${DRIVER_NAME}`;
+  // A dev disk must work with zero config; a production disk that forgets the secret still
+  // gets a *shared* secret, never a per-process random one that breaks on restart.
+  const secret =
+    options.signingSecret ?? process.env['STORAGE_SIGNING_SECRET'] ?? 'ultimate-dev-signing-secret';
+
+  const filePath = (key: string): string => `${root}/${key}`;
+  const metaPath = (key: string): string => `${root}/${META_DIR}/${key}.json`;
+
+  const readSidecar = async (key: string): Promise<Sidecar | undefined> => {
+    const file = Bun.file(metaPath(key));
+    if (!(await file.exists())) return undefined;
+    try {
+      const raw: unknown = await file.json();
+      return parseSidecar(raw);
+    } catch {
+      return undefined;
+    }
+  };
+
+  const head = async (key: string): Promise<StorageObject | undefined> => {
+    const file = Bun.file(filePath(key));
+    if (!(await file.exists())) return undefined;
+    const sidecar = await readSidecar(key);
+    // Only hash when the sidecar is gone — `list()` must not read every file it lists.
+    const etag = sidecar?.etag ?? etagOf(new Uint8Array(await file.arrayBuffer()));
+    return {
+      key,
+      size: file.size,
+      contentType: sidecar?.contentType ?? DEFAULT_CONTENT_TYPE,
+      etag,
+      lastModified: new Date(file.lastModified),
+    };
+  };
+
+  return {
+    name: DRIVER_NAME,
+
+    async put(key: string, body: StorageBody, putOptions?: PutOptions): Promise<StorageObject> {
+      const safe = assertSafeKey(key);
+      const bytes = await toBytes(body);
+      const claimed = putOptions?.checksum;
+      if (claimed !== undefined) {
+        const actual = sha256Base64(bytes);
+        if (claimed !== actual) throw checksumMismatch(safe, claimed, actual);
+      }
+      const sidecar: Sidecar = {
+        contentType: putOptions?.contentType ?? DEFAULT_CONTENT_TYPE,
+        etag: etagOf(bytes),
+        cacheControl: putOptions?.cacheControl,
+        metadata: putOptions?.metadata,
+      };
+      await Bun.write(filePath(safe), bytes);
+      await Bun.write(metaPath(safe), JSON.stringify(sidecar));
+      return {
+        key: safe,
+        size: bytes.byteLength,
+        contentType: sidecar.contentType,
+        etag: sidecar.etag,
+        lastModified: clock.now(),
+      };
+    },
+
+    async get(key: string): Promise<StorageRead> {
+      const safe = assertSafeKey(key);
+      const object = await head(safe);
+      if (object === undefined) throw objectNotFound(DRIVER_NAME, safe);
+      const bytes = new Uint8Array(await Bun.file(filePath(safe)).arrayBuffer());
+      return { object, bytes };
+    },
+
+    async stream(key: string): Promise<ReadableStream<Uint8Array>> {
+      const safe = assertSafeKey(key);
+      const file = Bun.file(filePath(safe));
+      if (!(await file.exists())) throw objectNotFound(DRIVER_NAME, safe);
+      return file.stream();
+    },
+
+    async delete(key: string): Promise<void> {
+      const safe = assertSafeKey(key);
+      // Idempotent by contract: a missing key is already in the desired state.
+      await Bun.file(filePath(safe))
+        .delete()
+        .catch(() => undefined);
+      await Bun.file(metaPath(safe))
+        .delete()
+        .catch(() => undefined);
+    },
+
+    async exists(key: string): Promise<boolean> {
+      return Bun.file(filePath(assertSafeKey(key))).exists();
+    },
+
+    async list(listOptions?: ListOptions): Promise<ListPage> {
+      const prefix = listOptions?.prefix ?? '';
+      const limit = listOptions?.limit ?? DEFAULT_LIST_LIMIT;
+      const cursor = listOptions?.cursor;
+      const keys: string[] = [];
+      try {
+        for await (const entry of new Bun.Glob('**/*').scan({ cwd: root, onlyFiles: true })) {
+          const key = entry.replaceAll('\\', '/');
+          if (key.startsWith(`${META_DIR}/`)) continue;
+          if (!key.startsWith(prefix)) continue;
+          // The cursor IS the last key of the previous page — lexicographic order keeps it stable.
+          if (cursor !== undefined && key <= cursor) continue;
+          keys.push(key);
+        }
+      } catch {
+        // A disk nobody has written to yet has no directory: an empty listing, not an error.
+        return { objects: [], truncated: false };
+      }
+      keys.sort();
+      const page = keys.slice(0, limit);
+      const objects: StorageObject[] = [];
+      for (const key of page) {
+        const object = await head(key);
+        if (object !== undefined) objects.push(object);
+      }
+      const truncated = keys.length > page.length;
+      const last = page.at(-1);
+      return truncated && last !== undefined
+        ? { objects, truncated, cursor: last }
+        : { objects, truncated: false };
+    },
+
+    async signedUrl(key: string, urlOptions?: SignedUrlOptions): Promise<string> {
+      return buildSignedUrl({
+        secret,
+        key: assertSafeKey(key),
+        method: urlOptions?.method,
+        expiresInMs: urlOptions?.expiresInMs,
+        maxBytes: urlOptions?.maxBytes,
+        contentType: urlOptions?.contentType,
+        baseUrl,
+        clock,
+      });
+    },
+  };
+}

package/src/driver-s3.ts

@@ -0,0 +1,249 @@
+// Single responsibility: the production disk over Bun's native S3 client. One driver covers
+// MinIO, Cloudflare R2 and AWS — the difference is `endpoint` + `forcePathStyle`, nothing else.
+// The client is built lazily on first use so importing this module never opens a socket, and
+// credentials arrive as env var NAMES: a literal key in app.config.ts is a key in git.
+
+import { ConfigInvalidError, EnvMissingError } from '@ultimat3/core';
+import {
+  DEFAULT_CONTENT_TYPE,
+  DEFAULT_LIST_LIMIT,
+  type ListOptions,
+  type ListPage,
+  type PutOptions,
+  type SignedUrlOptions,
+  type StorageBody,
+  type StorageDriver,
+  type StorageObject,
+  type StorageRead,
+  sha256Base64,
+  toBytes,
+} from './driver';
+import { checksumMismatch, objectNotFound, storageNotImplemented } from './errors';
+import { assertSafeKey } from './path';
+
+const DRIVER_NAME = 's3';
+
+/** Structural view of `Bun.S3Client` — typing it here keeps `bun-types` out of the contract. */
+export interface S3FileLike {
+  write(data: Uint8Array | Blob, options?: { type?: string }): Promise<number>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  exists(): Promise<boolean>;
+  delete(): Promise<void>;
+  stream(): ReadableStream<Uint8Array>;
+  stat(): Promise<S3StatLike>;
+  presign(options: { method?: string; expiresIn?: number; type?: string }): string;
+}
+
+export interface S3StatLike {
+  readonly size: number;
+  readonly type?: string | undefined;
+  readonly etag?: string | undefined;
+  readonly lastModified?: string | Date | undefined;
+}
+
+export interface S3ListEntryLike {
+  readonly key?: string | undefined;
+  readonly size?: number | undefined;
+  readonly eTag?: string | undefined;
+  readonly lastModified?: string | Date | undefined;
+}
+
+export interface S3ListResultLike {
+  readonly contents?: readonly S3ListEntryLike[] | undefined;
+  readonly isTruncated?: boolean | undefined;
+  readonly nextContinuationToken?: string | undefined;
+}
+
+export interface S3ClientLike {
+  file(key: string): S3FileLike;
+  list(input: {
+    prefix?: string;
+    maxKeys?: number;
+    continuationToken?: string;
+  }): Promise<S3ListResultLike>;
+}
+
+export interface S3DriverOptions {
+  readonly bucket: string;
+  readonly region?: string | undefined;
+  /** MinIO: `http://localhost:9000`. R2: `https://<account>.r2.cloudflarestorage.com`. */
+  readonly endpoint?: string | undefined;
+  /** MinIO needs `true`; AWS and R2 do not. */
+  readonly forcePathStyle?: boolean | undefined;
+  /** Env var NAME holding the key id. Default `S3_ACCESS_KEY_ID`. */
+  readonly accessKeyIdEnv?: string | undefined;
+  /** Env var NAME holding the secret. Default `S3_SECRET_ACCESS_KEY`. */
+  readonly secretAccessKeyEnv?: string | undefined;
+  readonly sessionTokenEnv?: string | undefined;
+  /** Injected in tests; production reads `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /** Injected in tests; production constructs `Bun.S3Client`. */
+  readonly client?: S3ClientLike | undefined;
+}
+
+interface S3ClientConstructor {
+  new (options: Record<string, unknown>): S3ClientLike;
+}
+
+function requireEnv(
+  env: Readonly<Record<string, string | undefined>>,
+  name: string,
+  partner: string,
+): string {
+  const value = env[name];
+  if (value === undefined || value === '') {
+    throw new EnvMissingError({
+      cause: `${name} is not set, so the s3 disk cannot authenticate`,
+      fix: `set ${name} and ${partner} in .env (or the container's secret store), then re-run`,
+      meta: { missing: name },
+    });
+  }
+  return value;
+}
+
+function buildClient(options: S3DriverOptions): S3ClientLike {
+  if (options.client !== undefined) return options.client;
+  if (options.bucket === '') {
+    throw new ConfigInvalidError({
+      cause: 's3 disk was defined without a bucket',
+      fix: 'set storage.disks.<name>.bucket in app.config.ts',
+    });
+  }
+  const env = options.env ?? process.env;
+  const idVar = options.accessKeyIdEnv ?? 'S3_ACCESS_KEY_ID';
+  const secretVar = options.secretAccessKeyEnv ?? 'S3_SECRET_ACCESS_KEY';
+  const Client = (Bun as unknown as { S3Client?: S3ClientConstructor }).S3Client;
+  if (Client === undefined) {
+    throw new ConfigInvalidError({
+      cause: 'Bun.S3Client is unavailable in this runtime',
+      fix: 'upgrade the runtime: bun upgrade   # the s3 disk needs bun >= 1.3',
+    });
+  }
+  const tokenVar = options.sessionTokenEnv;
+  const sessionToken = tokenVar === undefined ? undefined : env[tokenVar];
+  // Bun's flag is the inverse: MinIO's path style means "not virtual hosted".
+  const pathStyle = options.forcePathStyle;
+  return new Client({
+    bucket: options.bucket,
+    accessKeyId: requireEnv(env, idVar, secretVar),
+    secretAccessKey: requireEnv(env, secretVar, idVar),
+    ...(options.region === undefined ? {} : { region: options.region }),
+    ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
+    ...(pathStyle === undefined ? {} : { virtualHostedStyle: !pathStyle }),
+    ...(sessionToken === undefined ? {} : { sessionToken }),
+  });
+}
+
+const toDate = (value: string | Date | undefined): Date =>
+  value === undefined ? new Date(0) : value instanceof Date ? value : new Date(value);
+
+export function s3Driver(options: S3DriverOptions): StorageDriver {
+  let client: S3ClientLike | undefined;
+  const conn = (): S3ClientLike => {
+    client ??= buildClient(options);
+    return client;
+  };
+
+  const statObject = async (key: string): Promise<StorageObject> => {
+    const stat = await conn().file(key).stat();
+    return {
+      key,
+      size: stat.size,
+      contentType: stat.type ?? DEFAULT_CONTENT_TYPE,
+      etag: stat.etag ?? '',
+      lastModified: toDate(stat.lastModified),
+    };
+  };
+
+  return {
+    name: DRIVER_NAME,
+
+    async put(key: string, body: StorageBody, putOptions?: PutOptions): Promise<StorageObject> {
+      const safe = assertSafeKey(key);
+      if (putOptions?.metadata !== undefined || putOptions?.cacheControl !== undefined) {
+        const uri = `s3://${options.bucket}/${safe}`;
+        throw storageNotImplemented(
+          'user metadata and cache-control on the s3 driver (Bun exposes no header hook yet)',
+          `drop metadata/cacheControl from put(), or set them out of band: ` +
+            `aws s3 cp ${uri} ${uri} --metadata-directive REPLACE`,
+        );
+      }
+      // Buffered on purpose: size and checksum must be known before the object exists.
+      // Multipart streaming upload is a later optimisation, not a correctness change.
+      const bytes = await toBytes(body);
+      const claimed = putOptions?.checksum;
+      if (claimed !== undefined) {
+        const actual = sha256Base64(bytes);
+        if (claimed !== actual) throw checksumMismatch(safe, claimed, actual);
+      }
+      await conn()
+        .file(safe)
+        .write(bytes, { type: putOptions?.contentType ?? DEFAULT_CONTENT_TYPE });
+      return statObject(safe);
+    },
+
+    async get(key: string): Promise<StorageRead> {
+      const safe = assertSafeKey(key);
+      const file = conn().file(safe);
+      if (!(await file.exists())) throw objectNotFound(DRIVER_NAME, safe);
+      const bytes = new Uint8Array(await file.arrayBuffer());
+      return { object: await statObject(safe), bytes };
+    },
+
+    async stream(key: string): Promise<ReadableStream<Uint8Array>> {
+      const safe = assertSafeKey(key);
+      const file = conn().file(safe);
+      if (!(await file.exists())) throw objectNotFound(DRIVER_NAME, safe);
+      return file.stream();
+    },
+
+    async delete(key: string): Promise<void> {
+      await conn()
+        .file(assertSafeKey(key))
+        .delete()
+        .catch(() => undefined);
+    },
+
+    async exists(key: string): Promise<boolean> {
+      return conn().file(assertSafeKey(key)).exists();
+    },
+
+    async list(listOptions?: ListOptions): Promise<ListPage> {
+      const result = await conn().list({
+        maxKeys: listOptions?.limit ?? DEFAULT_LIST_LIMIT,
+        ...(listOptions?.prefix === undefined ? {} : { prefix: listOptions.prefix }),
+        ...(listOptions?.cursor === undefined ? {} : { continuationToken: listOptions.cursor }),
+      });
+      const objects: StorageObject[] = [];
+      for (const entry of result.contents ?? []) {
+        if (entry.key === undefined) continue;
+        objects.push({
+          key: entry.key,
+          size: entry.size ?? 0,
+          contentType: DEFAULT_CONTENT_TYPE,
+          etag: entry.eTag ?? '',
+          lastModified: toDate(entry.lastModified),
+        });
+      }
+      const cursor = result.nextContinuationToken;
+      return result.isTruncated === true && cursor !== undefined
+        ? { objects, truncated: true, cursor }
+        : { objects, truncated: false };
+    },
+
+    /**
+     * Provider presigning. The signature covers method, expiry and content type but NOT
+     * `maxBytes` — S3 has no header for it, so size stays a server-side policy check.
+     */
+    async signedUrl(key: string, urlOptions?: SignedUrlOptions): Promise<string> {
+      const expiresInMs = urlOptions?.expiresInMs ?? 900_000;
+      return conn()
+        .file(assertSafeKey(key))
+        .presign({
+          method: urlOptions?.method ?? 'GET',
+          expiresIn: Math.ceil(expiresInMs / 1000),
+          ...(urlOptions?.contentType === undefined ? {} : { type: urlOptions.contentType }),
+        });
+    },
+  };
+}

package/src/driver.ts

@@ -0,0 +1,83 @@
+// Single responsibility: the driver contract every disk implements, plus the byte helpers all
+// drivers share (body normalisation, SHA-256 etag/checksum). Bytes never travel as strings —
+// a base64 round trip through JSON is how a "small" upload becomes a 33%-larger OOM.
+
+export type StorageBody = Uint8Array | ReadableStream<Uint8Array> | Blob;
+
+export interface StorageObject {
+  readonly key: string;
+  readonly size: number;
+  readonly contentType: string;
+  readonly etag: string;
+  readonly lastModified: Date;
+}
+
+export interface PutOptions {
+  readonly contentType?: string | undefined;
+  readonly cacheControl?: string | undefined;
+  readonly metadata?: Readonly<Record<string, string>> | undefined;
+  /** base64 SHA-256 of the body. Supplied means verified: a mismatch is a rejected write. */
+  readonly checksum?: string | undefined;
+}
+
+export interface ListOptions {
+  readonly prefix?: string | undefined;
+  /** Opaque; pass back the `cursor` of the previous page. */
+  readonly cursor?: string | undefined;
+  readonly limit?: number | undefined;
+}
+
+export interface ListPage {
+  readonly objects: readonly StorageObject[];
+  readonly truncated: boolean;
+  /** Absent when `truncated` is false. */
+  readonly cursor?: string | undefined;
+}
+
+export interface StorageRead {
+  readonly object: StorageObject;
+  readonly bytes: Uint8Array;
+}
+
+export type SignedUrlMethod = 'GET' | 'PUT';
+
+export interface SignedUrlOptions {
+  readonly method?: SignedUrlMethod | undefined;
+  readonly expiresInMs?: number | undefined;
+  /** Constrains a `PUT`: the signature covers it, so a client cannot widen it. */
+  readonly maxBytes?: number | undefined;
+  readonly contentType?: string | undefined;
+}
+
+export interface StorageDriver {
+  /** Disk-independent driver name (`local`, `s3`) — appears in every error cause. */
+  readonly name: string;
+  put(key: string, body: StorageBody, options?: PutOptions): Promise<StorageObject>;
+  get(key: string): Promise<StorageRead>;
+  /** Bytes without buffering — the only safe path for anything over a few MB. */
+  stream(key: string): Promise<ReadableStream<Uint8Array>>;
+  /** Idempotent: deleting an absent key is not an error. */
+  delete(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+  list(options?: ListOptions): Promise<ListPage>;
+  signedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+}
+
+export const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+export const DEFAULT_LIST_LIMIT = 1000;
+
+export async function toBytes(body: StorageBody): Promise<Uint8Array> {
+  if (body instanceof Uint8Array) return body;
+  if (body instanceof Blob) return new Uint8Array(await body.arrayBuffer());
+  return new Uint8Array(await new Response(body).arrayBuffer());
+}
+
+/** base64 SHA-256 — the wire form for `PutOptions.checksum` and `ValidatedUpload.checksum`. */
+export function sha256Base64(bytes: Uint8Array): string {
+  return new Bun.CryptoHasher('sha256').update(bytes).digest('base64');
+}
+
+/** Local etag. S3 returns the provider's etag instead, so never compare across drivers. */
+export function etagOf(bytes: Uint8Array): string {
+  return new Bun.CryptoHasher('sha256').update(bytes).digest('hex').slice(0, 32);
+}