@ultimat3/storage 22.15.0 → 23.0.0

package/CLAUDE.md

@@ -39,7 +39,9 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
 |---|---|
 | `driver.ts` | `StorageDriver` contract (8 methods) + bounded `toBytes`/`sha256Base64`/`etagOf` |
 | `driver-local.ts` | dev default over `Bun.file`, `.meta/` sidecars, `Bun.Glob` listing |
+| `driver-memory.ts` | `memoryDriver()` — a test's disk over a `Map`: `localDriver`'s contract and refusals, `objects()` for an assertion about the bucket. `driver-memory.test.ts` runs each claim on BOTH disks. Signs through `resolveSigningSecret` (`driver-local.ts`), the one rule both share |
 | `driver-s3.ts` | `Bun.S3Client`, built lazily (import must never open a socket) |
+| `driver-s3-region.ts` | a provider's wrong-region refusal → `X_CONFIG_INVALID` whose fix names `S3_REGION` |
 | `path.ts` | key validation + `META_DIR` + `scopedKey`/`isWithinOrg`/`isTenantScoped` tenant boundary |
 | `signed-url.ts` | HMAC over the constraint tuple, constant-time verify |
 | `upload.ts` | magic-byte sniff + size/allowlist/checksum policy |
@@ -187,6 +189,12 @@ Gotchas:
   whole path exists to prevent. That is why it derives the box itself and asks core for
   `fit: 'cover'` — core's `contain` letterboxes to the requested box, this API fits inside it.
 - Bun's S3 flag is `virtualHostedStyle`; our `forcePathStyle` is its inverse.
+- **No `region` signs for `auto`.** R2 wants that; AWS and a gateway that checks the scope answer
+  `AuthorizationHeaderMalformed … expecting "<region>"`. `put`/`copy`/`list`/`delete` ask
+  `regionMismatch()` BEFORE their own verdict, so the code is `X_CONFIG_INVALID` and the fix is the
+  region — never `X_STORAGE_LIST_FAILED` with a fix about `s3:ListBucket`. The captured region is
+  held to `[A-Za-z0-9-]`: a provider's sentence may put nothing else into a `fix:`. A HEAD has no
+  body, so `exists()`/`stat()` never see it. `driver-s3.live.test.ts` runs with no region on purpose.
 - The signature check runs BEFORE the expiry check. Do not reorder.
 - `timingSafeEqual` is `@ultimat3/core`'s (`signed-url.ts` imports and re-exports it) — the same
   implementation `@ultimat3/auth` uses, not a second copy. Add new secret comparisons through it.

package/README.md

@@ -16,14 +16,44 @@ defineStorage({
 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.
+Swapping `local` for `s3` in `app.config.ts` changes no call site. `x dev` needs no S3 server.
 
 ## 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 |
+| `s3Driver` | `Bun.s3` | prod: any S3-compatible endpoint — AWS, R2, a self-hosted gateway | provider presign |
+| `memoryDriver` | a `Map` in this process | a TEST's disk — never a deployment's: a restart is every object gone | HMAC, the local disk's own |
+
+`memoryDriver()` is what a suite holds instead of a temp directory or a hand-written fake: it
+answers every method `localDriver` does, refuses what it refuses (an unsafe key, a wrong checksum,
+a body past `maxPutBytes`, `serverSideEncryption`), and signs under the same rule — the published
+development key in `development` and `test` only. `objects()` hands back a COPY of every stored
+object's bytes by key, for the assertion a test makes about the bucket itself.
+
+```ts
+import { afterEach, beforeEach } from 'bun:test';
+import { defineStorage, disk, memoryDriver, resetStorage } from '@ultimat3/storage';
+
+// A fresh driver per test: `resetStorage()` forgets the REGISTRY, never a driver's objects, so a
+// driver held across tests carries every earlier test's writes.
+let sessions = memoryDriver();
+beforeEach(() => {
+  sessions = memoryDriver();
+  defineStorage({ disks: { sessions } });
+});
+afterEach(() => resetStorage());
+
+await disk('sessions').put('org/o1/session.json', new TextEncoder().encode('{"sealed":"x1.…"}'));
+const stored = [...sessions.objects().values()].map((bytes) => new TextDecoder().decode(bytes));
+```
+
+Server-side only, like both other drivers: nothing an island imports reaches it.
+
+`region` is what requests are signed for; unset, that is `auto`. An endpoint that expects another
+region refuses the first write, list or delete with `X_CONFIG_INVALID`, and the fix names the
+`S3_REGION` to set.
 
 `copy(from, to)` is on the contract so a promotion is not a download-and-reupload:
 `promoteAttachment` used to `get()` the whole object into the app and `put()` it back, a gigabyte

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "22.15.0",
+  "version": "23.0.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,6 +32,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0"
+    "@ultimat3/core": "23.0.0"
   }
 }

package/src/driver-local.ts

@@ -1,5 +1,5 @@
 // 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.
+// `Bun.write` rooted at one directory, so `x dev` needs no S3 server 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.
 
@@ -141,6 +141,37 @@ function parseSidecar(raw: unknown): Sidecar | undefined {
   };
 }
 
+/**
+ * The secret a disk that mints its OWN URLs signs with — `localDriver` and `memoryDriver` both.
+ *
+ * A dev disk must work with zero config. Outside development the fallback is refused rather than
+ * used: the literal is published, so signing with it hands every reader the power to mint a PUT
+ * for any key with any size and type limit — which `acceptSignedUpload` then trusts over the app's
+ * own `uploadPolicy`. Refused at construction, so the boot fails rather than the first upload.
+ *
+ * The published literal counts as no secret at all, whichever way it arrives: an env var or an
+ * `app.config.ts` that pasted it in signs exactly as weakly as the fallback does. One table for
+ * all three reads — the secret, the environment test and the environment the refusal names.
+ * Splitting them is how the guard and the disk came to answer about two different processes.
+ */
+export function resolveSigningSecret(
+  disk: string,
+  options: Pick<LocalDriverOptions, 'signingSecret' | 'env'>,
+): string {
+  const env = options.env ?? (process.env as Record<string, string | undefined>);
+  const supplied = options.signingSecret ?? env[STORAGE_SIGNING_SECRET_KEY];
+  const configured =
+    supplied === undefined || supplied === '' || supplied === DEV_SIGNING_SECRET
+      ? undefined
+      : supplied;
+  // FAILS CLOSED: a process that names no environment resolves as `production` here, the answer
+  // core's `assertNoDevSecretsOutsideLocal` gives. `isLocal`'s own fallback is `development`, so the
+  // process that forgot to say signed with the published key — exactly the one that must not.
+  if (configured === undefined && !isLocal({ env, fallback: 'production' }))
+    throw signingSecretMissing(resolveEnvironment({ env, fallback: 'production' }), disk);
+  return configured ?? DEV_SIGNING_SECRET;
+}
+
 /**
  * A POSIX file is not encrypted at rest by this driver, and recording the request in the sidecar
  * would answer a security review with a field the disk never honoured. Refused on the DEV disk
@@ -174,28 +205,7 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
   // 404 its own URLs. An explicit `baseUrl` outranks the registration: that is the operator
   // stating where the route is mounted, and inference must not overwrite a decision.
   let baseUrl = options.baseUrl ?? signedUrlBaseFor(DRIVER_NAME);
-  // A dev disk must work with zero config. Outside development the fallback is refused rather
-  // than used: the literal is published, so signing with it hands every reader the power to mint
-  // a PUT for any key with any size and type limit — which `acceptSignedUpload` then trusts over
-  // the app's own `uploadPolicy`. Refused HERE, at construction, so the boot fails rather than
-  // the first upload.
-  // The published literal counts as no secret at all, whichever way it arrives: an env var or an
-  // `app.config.ts` that pasted it in signs exactly as weakly as the fallback does.
-  // One table for all three reads — the secret, the environment test and the environment the
-  // refusal names. Splitting them is how the guard and the disk came to answer about two
-  // different processes.
-  const env = options.env ?? (process.env as Record<string, string | undefined>);
-  const supplied = options.signingSecret ?? env[STORAGE_SIGNING_SECRET_KEY];
-  const configured =
-    supplied === undefined || supplied === '' || supplied === DEV_SIGNING_SECRET
-      ? undefined
-      : supplied;
-  // FAILS CLOSED: a process that names no environment resolves as `production` here, the answer
-  // core's `assertNoDevSecretsOutsideLocal` gives. `isLocal`'s own fallback is `development`, so the
-  // process that forgot to say signed with the published key — exactly the one that must not.
-  if (configured === undefined && !isLocal({ env, fallback: 'production' }))
-    throw signingSecretMissing(resolveEnvironment({ env, fallback: 'production' }));
-  const secret = configured ?? DEV_SIGNING_SECRET;
+  const secret = resolveSigningSecret(DRIVER_NAME, options);
 
   const filePath = (key: string): string => `${root}/${key}`;
   const metaPath = (key: string): string => `${root}/${META_DIR}/${key}.json`;

package/src/driver-memory.ts

@@ -0,0 +1,195 @@
+// Single responsibility: the disk a TEST holds — a `StorageDriver` over one `Map`, answering every
+// question `localDriver` answers and refusing what it refuses, with nothing on a filesystem to
+// create or clean up. Not a deployment's disk: a restart is every object gone.
+//
+// It exists because the alternative was written by hand in every suite that needed a bucket: a
+// fake with three methods and five `unsupported()` stubs, each a slightly different contract.
+
+import { type Clock, finiteCount, systemClock } from '@ultimat3/core';
+import {
+  DEFAULT_CONTENT_TYPE,
+  etagOf,
+  type ListOptions,
+  type ListPage,
+  type PutOptions,
+  resolveListLimit,
+  type SignedUrlOptions,
+  type StorageBody,
+  type StorageDriver,
+  type StorageObject,
+  type StorageRead,
+  sha256Base64,
+  toBytes,
+} from './driver';
+import type { LocalDriverOptions } from './driver-local';
+import { resolveSigningSecret } from './driver-local';
+import { checksumMismatch, objectNotFound, storageNotImplemented } from './errors';
+import { assertSafeKey } from './path';
+import type { SignedUrlVerification } from './signed-url';
+import { buildSignedUrl, signedUrlBaseFor, verifySignedUrl } from './signed-url';
+import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
+
+const DRIVER_NAME = 'memory';
+
+/** `localDriver`'s options, minus the directory there is none of. */
+export type MemoryDriverOptions = Omit<LocalDriverOptions, 'root'>;
+
+export interface MemoryStorageDriver extends StorageDriver {
+  /**
+   * Every stored object's bytes by key, COPIED — what an operator holding the bucket could read.
+   * For the assertion a test makes about the store itself: "nothing in it is a cookie value".
+   */
+  objects(): ReadonlyMap<string, Uint8Array>;
+}
+
+interface Stored {
+  readonly bytes: Uint8Array;
+  readonly object: StorageObject;
+}
+
+/**
+ * An object no caller shares with the store. `metadata` and `lastModified` are mutable by anyone
+ * holding a reference, and the local disk's sidecar is a copy by construction — a test that
+ * mutated what `put()` was handed must not see a different object on the next `get()`.
+ */
+const snapshot = (object: StorageObject): StorageObject => ({
+  ...object,
+  lastModified: new Date(object.lastModified.getTime()),
+  ...(object.metadata === undefined ? {} : { metadata: { ...object.metadata } }),
+});
+
+export function memoryDriver(options: MemoryDriverOptions = {}): MemoryStorageDriver {
+  const maxPutBytes = finiteCount(
+    'the memory disk driver',
+    'maxPutBytes',
+    options.maxPutBytes === undefined ? DEFAULT_MAX_UPLOAD_BYTES : options.maxPutBytes,
+    1,
+  );
+  const clock = options.clock ?? systemClock;
+  let baseUrl = options.baseUrl ?? signedUrlBaseFor(DRIVER_NAME);
+  const secret = resolveSigningSecret(DRIVER_NAME, options);
+  const stored = new Map<string, Stored>();
+
+  const found = (key: string): Stored => {
+    const hit = stored.get(key);
+    if (hit === undefined) throw objectNotFound(DRIVER_NAME, key);
+    return hit;
+  };
+
+  return {
+    name: DRIVER_NAME,
+
+    get signedUrlBase(): string {
+      return baseUrl;
+    },
+
+    registerAs(diskName: string): void {
+      if (options.baseUrl === undefined) baseUrl = signedUrlBaseFor(diskName);
+    },
+
+    objects(): ReadonlyMap<string, Uint8Array> {
+      return new Map([...stored].map(([key, value]) => [key, value.bytes.slice()]));
+    },
+
+    async put(key: string, body: StorageBody, putOptions?: PutOptions): Promise<StorageObject> {
+      const safe = assertSafeKey(key);
+      // The same refusal both shipped disks make: a `put()` that succeeds in a test and throws in
+      // production is a gap an app meets on the worst day.
+      if (putOptions?.serverSideEncryption !== undefined) {
+        throw storageNotImplemented(
+          'server-side encryption on the memory driver (it holds bytes in a Map)',
+          'drop serverSideEncryption from put(), and encrypt the disk itself — an s3Driver over a bucket with a default KMS rule',
+        );
+      }
+      const bytes = await toBytes(body, { driver: DRIVER_NAME, key: safe, maxBytes: maxPutBytes });
+      const claimed = putOptions?.checksum;
+      if (claimed !== undefined) {
+        const actual = sha256Base64(bytes);
+        if (claimed !== actual) throw checksumMismatch(safe, claimed, actual);
+      }
+      const object: StorageObject = {
+        key: safe,
+        size: bytes.byteLength,
+        contentType: putOptions?.contentType ?? DEFAULT_CONTENT_TYPE,
+        etag: etagOf(bytes),
+        lastModified: clock.now(),
+        ...(putOptions?.cacheControl === undefined
+          ? {}
+          : { cacheControl: putOptions.cacheControl }),
+        ...(putOptions?.metadata === undefined ? {} : { metadata: putOptions.metadata }),
+      };
+      // A copy in, as a file write is: the caller's buffer and metadata are the caller's to reuse.
+      stored.set(safe, { bytes: bytes.slice(), object: snapshot(object) });
+      return snapshot(object);
+    },
+
+    async get(key: string): Promise<StorageRead> {
+      const hit = found(assertSafeKey(key));
+      return { object: snapshot(hit.object), bytes: hit.bytes.slice() };
+    },
+
+    async stream(key: string): Promise<ReadableStream<Uint8Array>> {
+      const hit = found(assertSafeKey(key));
+      return new Blob([hit.bytes.slice()]).stream();
+    },
+
+    async copy(from: string, to: string): Promise<StorageObject> {
+      const source = found(assertSafeKey(from));
+      const destination = assertSafeKey(to);
+      const object: StorageObject = {
+        ...source.object,
+        key: destination,
+        lastModified: clock.now(),
+      };
+      stored.set(destination, { bytes: source.bytes.slice(), object: snapshot(object) });
+      return snapshot(object);
+    },
+
+    async delete(key: string): Promise<void> {
+      stored.delete(assertSafeKey(key));
+    },
+
+    async exists(key: string): Promise<boolean> {
+      return stored.has(assertSafeKey(key));
+    },
+
+    async list(listOptions?: ListOptions): Promise<ListPage> {
+      const prefix = listOptions?.prefix ?? '';
+      const limit = resolveListLimit(listOptions?.limit);
+      const cursor = listOptions?.cursor;
+      // Code-unit order and "the cursor is the last key of the page before" — the local disk's own.
+      const keys = [...stored.keys()]
+        .filter((key) => key.startsWith(prefix) && (cursor === undefined || key > cursor))
+        .sort();
+      const page = keys.slice(0, limit);
+      const objects = page.flatMap((key) => {
+        const hit = stored.get(key);
+        return hit === undefined ? [] : [snapshot(hit.object)];
+      });
+      const last = page.at(-1);
+      return keys.length > page.length && last !== undefined
+        ? { objects, truncated: true, 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,
+      });
+    },
+
+    async verifySigned(input: {
+      readonly url: string;
+      readonly clock?: Clock | undefined;
+    }): Promise<SignedUrlVerification> {
+      return verifySignedUrl({ url: input.url, secret, baseUrl, clock: input.clock ?? clock });
+    },
+  };
+}

package/src/driver-s3-region.ts

@@ -0,0 +1,39 @@
+// Single responsibility: recognise the one provider refusal that names its own repair — a request
+// signed for the wrong region — and turn it into the disk-misconfigured error it is. Split from
+// driver-s3.ts because every call that sends a signed request asks this before its own verdict.
+
+import { ConfigInvalidError, stringField } from '@ultimat3/core';
+
+/** What S3 and every S3-compatible gateway answer a SigV4 scope with the wrong region in it. */
+const REGION_MISMATCH_CODE = 'AuthorizationHeaderMalformed';
+
+/**
+ * `the region "auto" is wrong; expecting "us-east-1"` — double quotes from a gateway, single from
+ * AWS. The captures are held to a region name's alphabet, so a sentence this process did not
+ * write can put nothing else into a `fix:` line.
+ */
+const REGION_SENTENCE =
+  /the region ['"]([A-Za-z0-9-]{1,64})['"] is wrong; expecting ['"]([A-Za-z0-9-]{1,64})['"]/;
+
+/**
+ * The refusal as `X_CONFIG_INVALID`, or `undefined` when `error` is anything else. A region
+ * mismatch is the DISK misconfigured, exactly as a missing bucket is, so it carries that code from
+ * every call rather than `X_STORAGE_LIST_FAILED` with a fix about `s3:ListBucket` from one and a
+ * bare `S3Error` from another: `Bun.S3Client` signs for `auto` when no region is set, and a
+ * provider that checks the scope refuses every request the app ever sends.
+ *
+ * A HEAD carries no body, so `exists()` and `stat()` never see this sentence — the first PUT,
+ * LIST or DELETE does.
+ */
+export function regionMismatch(bucket: string, error: unknown): ConfigInvalidError | undefined {
+  if (stringField(error, 'code') !== REGION_MISMATCH_CODE) return undefined;
+  const match = REGION_SENTENCE.exec(stringField(error, 'message') ?? '');
+  const sent = match?.[1];
+  const expected = match?.[2];
+  if (sent === undefined || expected === undefined) return undefined;
+  return new ConfigInvalidError({
+    cause: `the s3 disk for bucket "${bucket}" signed a request for region "${sent}" and its endpoint expects "${expected}"`,
+    fix: `set S3_REGION=${expected} in .env (or pass region: '${expected}' to s3Driver), then re-run`,
+    meta: { bucket, sent, expected },
+  });
+}

package/src/driver-s3.ts

@@ -1,5 +1,6 @@
-// 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.
+// Single responsibility: the production disk over Bun's native S3 client. One driver covers AWS,
+// Cloudflare R2 and any S3-compatible gateway — the difference is `endpoint`, `region` and
+// `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.
 
@@ -19,6 +20,7 @@ import {
   sha256Base64,
   toBytes,
 } from './driver';
+import { regionMismatch } from './driver-s3-region';
 import {
   checksumMismatch,
   deleteFailed,
@@ -75,10 +77,14 @@ export interface S3ClientLike {
 
 export interface S3DriverOptions {
   readonly bucket: string;
+  /**
+   * The region requests are signed for. Unset, `Bun.S3Client` signs for `auto` — which R2 wants,
+   * and which AWS and a gateway that checks the scope refuse (`X_CONFIG_INVALID`, naming theirs).
+   */
   readonly region?: string | undefined;
-  /** MinIO: `http://localhost:9000`. R2: `https://<account>.r2.cloudflarestorage.com`. */
+  /** A self-hosted gateway: `http://localhost:9000`. R2: `https://<account>.r2.cloudflarestorage.com`. */
   readonly endpoint?: string | undefined;
-  /** MinIO needs `true`; AWS and R2 do not. */
+  /** A gateway addressed by host and port 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;
@@ -138,7 +144,7 @@ function buildClient(options: S3DriverOptions): S3ClientLike {
   }
   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".
+  // Bun's flag is the inverse: path style means "not virtual hosted".
   const pathStyle = options.forcePathStyle;
   return new Client({
     bucket: options.bucket,
@@ -224,6 +230,21 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     return client;
   };
 
+  /**
+   * A refused request as the disk-misconfigured error, when the provider named its own repair (a
+   * wrong region). Asked before any call's own verdict, so the fix an operator reads is the one
+   * that works rather than one about a grant they already have. `misconfigured` is the same
+   * question for a call with no verdict of its own: it rethrows whatever arrived.
+   */
+  const throwIfMisconfigured = (error: unknown): void => {
+    const mismatch = regionMismatch(options.bucket, error);
+    if (mismatch !== undefined) throw mismatch;
+  };
+  const misconfigured = (error: unknown): never => {
+    throwIfMisconfigured(error);
+    throw error;
+  };
+
   const statObject = async (key: string): Promise<StorageObject> => {
     const stat = await conn().file(key).stat();
     return {
@@ -253,7 +274,8 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       }
       await conn()
         .file(safe)
-        .write(bytes, { type: putOptions?.contentType ?? DEFAULT_CONTENT_TYPE });
+        .write(bytes, { type: putOptions?.contentType ?? DEFAULT_CONTENT_TYPE })
+        .catch(misconfigured);
       return statObject(safe);
     },
 
@@ -287,7 +309,8 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       const stat = await file.stat();
       await conn()
         .file(destination)
-        .write(file, { type: stat.type ?? DEFAULT_CONTENT_TYPE });
+        .write(file, { type: stat.type ?? DEFAULT_CONTENT_TYPE })
+        .catch(misconfigured);
       return statObject(destination);
     },
 
@@ -299,6 +322,7 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
         // Idempotent means an ABSENT key, and nothing else. AWS answers DELETE on a missing key
         // with 204, so this branch is for the providers that do not.
         if (isAbsentObject(error)) return;
+        throwIfMisconfigured(error);
         throw deleteFailed(
           DRIVER_NAME,
           safe,
@@ -331,6 +355,7 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
         // A bare `S3Error` used to escape here, uncoded: no `X_*`, no `fix`, no `--json` shape, and
         // `@ultimat3/http`'s error map has nothing to turn it into but a 500. A denied
         // `s3:ListBucket` is the commonest one and reads to an operator as an app crash.
+        throwIfMisconfigured(error);
         throw listFailed(
           DRIVER_NAME,
           prefix,

package/src/errors.ts

@@ -155,7 +155,9 @@ export const putTooLarge = (
       `send it direct with grantUpload({ disk, orgId, request }) instead of put(), or raise the ceiling: ` +
       (disk === 's3'
         ? `s3Driver({ bucket, maxPutBytes: ${bytes} })`
-        : `localDriver({ root, maxPutBytes: ${bytes} })`),
+        : disk === 'memory'
+          ? `memoryDriver({ maxPutBytes: ${bytes} })`
+          : `localDriver({ root, maxPutBytes: ${bytes} })`),
     meta: { disk, key, bytes, maxBytes },
   });
 
@@ -352,12 +354,12 @@ export const signedUrlUnverifiable = (diskName: string): StorageError =>
     meta: { disk: diskName },
   });
 
-export const signingSecretMissing = (environment: string): StorageError =>
+export const signingSecretMissing = (environment: string, disk = 'local'): StorageError =>
   new StorageError({
     code: 'X_ENV_MISSING',
     // The environment names what `resolveEnvironment()` resolved, which may have come from
     // NODE_ENV — naming ULTIMATE_ENV here reported a variable the process never set.
-    cause: `the local disk has no usable signing secret (no signingSecret option, and STORAGE_SIGNING_SECRET is unset, empty or the published development key) and the resolved environment is "${environment}", so it would sign URLs with the shipped development key`,
+    cause: `the ${disk} disk has no usable signing secret (no signingSecret option, and STORAGE_SIGNING_SECRET is unset, empty or the published development key) and the resolved environment is "${environment}", so it would sign URLs with the shipped development key`,
     fix: 'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
     meta: { key: 'STORAGE_SIGNING_SECRET', environment },
   });

package/src/index.ts

@@ -59,6 +59,8 @@ export {
   STORAGE_SIGNING_SECRET_KEY,
   usesDevStorageSecret,
 } from './driver-local';
+export type { MemoryDriverOptions, MemoryStorageDriver } from './driver-memory';
+export { memoryDriver } from './driver-memory';
 export type {
   S3ClientLike,
   S3DriverOptions,

package/src/driver-s3-fixture.ts

@@ -1,164 +0,0 @@
-// The in-memory `Bun.S3Client` stand-in the s3 driver's tests drive, and the helpers that read
-// its answers. Shared rather than copied because `driver-s3.test.ts` (reads, copies, listings,
-// credentials) and `driver-s3-put.test.ts` (everything `put()` refuses) must exercise the SAME
-// fake — two fakes drifting apart would be two providers, agreeing only by construction.
-
-import type { S3ClientLike, S3FileLike, S3ListResultLike, S3StatLike } from './driver-s3';
-import { isStorageError, objectNotFound } from './errors';
-
-/** The driver's private `DRIVER_NAME`; the fake reports failures against the same disk. */
-export const FAKE_DISK = 's3';
-
-export interface FakeObject {
-  bytes: Uint8Array;
-  type?: string | undefined;
-  etag?: string | undefined;
-  lastModified?: string | Date | undefined;
-}
-
-export interface PresignCall {
-  key: string;
-  options: {
-    method?: string | undefined;
-    expiresIn?: number | undefined;
-    type?: string | undefined;
-  };
-}
-
-export interface ListCall {
-  prefix?: string | undefined;
-  maxKeys?: number | undefined;
-  continuationToken?: string | undefined;
-}
-
-/**
- * What Bun hands back when the SERVICE refuses: an ordinary `Error` named `S3Error`, carrying the
- * provider's own code and status. The driver must read those structurally, because nothing in the
- * type system says a caught value has them.
- */
-export function s3Error(code: string, statusCode: number, key: string): Error {
-  return Object.assign(new Error(`${code}: the fake provider refused ${key}`), {
-    name: 'S3Error',
-    code,
-    statusCode,
-    path: key,
-  });
-}
-
-/** In-memory stand-in for `Bun.S3Client`, driven through `S3ClientLike` — no socket, ever. */
-export class FakeS3Client implements S3ClientLike {
-  readonly store = new Map<string, FakeObject>();
-  readonly fileCalls: string[] = [];
-  readonly presignCalls: PresignCall[] = [];
-  readonly listCalls: ListCall[] = [];
-  listResult: S3ListResultLike = { contents: [] };
-  /** A provider REFUSAL (403/503/reset) — the failure `delete()` must surface, not swallow. */
-  failDeleteFor: string | undefined;
-  /** A provider "there is nothing there" — the one failure `delete()` may call success. */
-  absentDeleteFor: string | undefined;
-  /**
-   * A refused LISTING — a denied `s3:ListBucket`, a throttle, an expired credential. There is no
-   * "absent" counterpart: a prefix with no keys is an empty page, never a rejection, so every
-   * failure `list()` can meet is one it must surface.
-   */
-  failListWith: Error | undefined;
-
-  /** Which key each handed-out `S3FileLike` stands for, so `write(sourceFile)` can read it. */
-  private readonly fileKeys = new WeakMap<object, string>();
-
-  /** The bytes behind an `S3FileLike` passed as `write`'s data, or `undefined` for raw bytes. */
-  sourceOf(data: unknown): Uint8Array | undefined {
-    if (typeof data !== 'object' || data === null) return undefined;
-    const sourceKey = this.fileKeys.get(data);
-    return sourceKey === undefined ? undefined : this.store.get(sourceKey)?.bytes;
-  }
-
-  file(key: string): S3FileLike {
-    this.fileCalls.push(key);
-    const store = this.store;
-    const client = this;
-    const handle: S3FileLike = {
-      async write(data, options) {
-        // `copy()` hands the SOURCE S3File to write(), exactly as Bun's own union allows, so the
-        // fake has to read one back out of its store rather than assume bytes.
-        const source = client.sourceOf(data);
-        const bytes =
-          source !== undefined
-            ? source
-            : data instanceof Uint8Array
-              ? data
-              : new Uint8Array(await (data as Blob).arrayBuffer());
-        store.set(key, { bytes, type: options?.type });
-        return bytes.byteLength;
-      },
-      async arrayBuffer() {
-        const entry = store.get(key);
-        // Reads the way the provider does: a GET on a key that is not there is a 404, and the
-        // driver is expected to have gated it behind exists() before ever getting here.
-        if (entry === undefined) throw objectNotFound(FAKE_DISK, key);
-        return new Uint8Array(entry.bytes).buffer;
-      },
-      async exists() {
-        return store.has(key);
-      },
-      async delete() {
-        // Shaped like the real thing: an `S3Error` is a plain Error with `name: 'S3Error'`, a
-        // provider `code` and a status. Deliberately NOT a StorageError — the driver has to
-        // classify a rejection it never authored, which is the only kind a provider hands back.
-        if (client.absentDeleteFor === key) throw s3Error('NoSuchKey', 404, key);
-        if (client.failDeleteFor === key) throw s3Error('AccessDenied', 403, key);
-        store.delete(key);
-      },
-      stream() {
-        const entry = store.get(key);
-        const bytes = entry?.bytes ?? new Uint8Array();
-        return new ReadableStream<Uint8Array>({
-          start(controller) {
-            controller.enqueue(bytes);
-            controller.close();
-          },
-        });
-      },
-      async stat(): Promise<S3StatLike> {
-        const entry = store.get(key);
-        if (entry === undefined) throw objectNotFound(FAKE_DISK, key);
-        return {
-          size: entry.bytes.byteLength,
-          type: entry.type,
-          etag: entry.etag,
-          lastModified: entry.lastModified,
-        };
-      },
-      presign(options) {
-        client.presignCalls.push({ key, options });
-        return `https://fake.example/${key}?signed`;
-      },
-    };
-    this.fileKeys.set(handle, key);
-    return handle;
-  }
-
-  async list(input: ListCall): Promise<S3ListResultLike> {
-    this.listCalls.push(input);
-    if (this.failListWith !== undefined) throw this.failListWith;
-    return this.listResult;
-  }
-}
-
-export const bytesOf = (text: string): Uint8Array => new TextEncoder().encode(text);
-export const textOf = (bytes: Uint8Array): string => new TextDecoder().decode(bytes);
-
-/** The error code a call answered with, or how it failed to answer with one. */
-export function codeOf(caught: unknown): string {
-  return isStorageError(caught) ? caught.code : `not-a-storage-error: ${String(caught)}`;
-}
-
-/** The thrown value itself, where the assertion is about its `cause`/`fix` and not just its code. */
-export async function catchError(fn: () => Promise<unknown>): Promise<unknown> {
-  try {
-    await fn();
-    return undefined;
-  } catch (error) {
-    return error;
-  }
-}