@ultimat3/storage 22.15.0 → 24.0.0

package/src/driver-memory.ts

@@ -0,0 +1,220 @@
+// 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, NotImplementedError, systemClock } from '@ultimat3/core';
+import {
+  assertListOptions,
+  assertPutOptions,
+  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 { checksumMismatch, getTooLarge, objectNotFound } from './errors';
+import { assertSafeKey } from './path';
+import type { SignedUrlVerification } from './signed-url';
+import { buildSignedUrl, signedUrlBaseFor, verifySignedUrl } from './signed-url';
+import { resolveSigningSecret } from './signing-secret';
+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,
+  ...(object.lastModified === undefined
+    ? {}
+    : { 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 maxGetBytes = finiteCount(
+    'the memory disk driver',
+    'maxGetBytes',
+    options.maxGetBytes === undefined ? maxPutBytes : options.maxGetBytes,
+    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 new NotImplementedError({
+          cause:
+            'server-side encryption on the memory driver (it holds bytes in a Map) is not implemented by this driver — drop serverSideEncryption from put() and encrypt the disk itself: an s3Driver over a bucket with a default KMS rule',
+          fix: 'put(key, body)',
+        });
+      }
+      assertPutOptions(DRIVER_NAME, putOptions);
+      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 stat(key: string): Promise<StorageObject | undefined> {
+      const hit = stored.get(assertSafeKey(key));
+      return hit && snapshot(hit.object);
+    },
+
+    async get(key: string): Promise<StorageRead> {
+      const safe = assertSafeKey(key);
+      const hit = found(safe);
+      // The local disk's refusal, so a suite on this disk meets the ceiling production has.
+      if (hit.bytes.byteLength > maxGetBytes) {
+        throw getTooLarge(DRIVER_NAME, safe, hit.bytes.byteLength, maxGetBytes);
+      }
+      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> {
+      // Both keys before either lookup, as the other two disks do: an unsafe destination is the
+      // refusal whether or not the source exists.
+      const [from_, destination] = [assertSafeKey(from), assertSafeKey(to)];
+      const source = found(from_);
+      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 ?? '';
+      assertListOptions(listOptions);
+      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,10 +1,20 @@
-// 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.
 
-import { ConfigInvalidError, EnvMissingError, finiteCount, stringField } from '@ultimat3/core';
 import {
+  ConfigInvalidError,
+  EnvMissingError,
+  finiteCount,
+  NotImplementedError,
+  renderFixShellArg,
+  stringField,
+} from '@ultimat3/core';
+import {
+  assertListOptions,
+  assertPutOptions,
   DEFAULT_CONTENT_TYPE,
   type ListOptions,
   type ListPage,
@@ -19,12 +29,16 @@ import {
   sha256Base64,
   toBytes,
 } from './driver';
+import { regionMismatch } from './driver-s3-region';
 import {
   checksumMismatch,
   deleteFailed,
+  getTooLarge,
+  isStorageError,
   listFailed,
   objectNotFound,
-  storageNotImplemented,
+  putFailed,
+  readFailed,
 } from './errors';
 import { assertSafeKey } from './path';
 import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
@@ -75,10 +89,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;
@@ -96,6 +114,12 @@ export interface S3DriverOptions {
    * and S3's single-PUT limit is 5GB regardless of what this says.
    */
   readonly maxPutBytes?: number | undefined;
+  /**
+   * Ceiling on ONE `get()`, because `get()` buffers the whole object — and on this disk nothing
+   * bounds what a presigned PUT stored (`SignedUrlOptions.maxBytes`). Defaults to `maxPutBytes`;
+   * an object past it is read with `stream()`.
+   */
+  readonly maxGetBytes?: number | undefined;
 }
 
 interface S3ClientConstructor {
@@ -138,7 +162,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,
@@ -151,8 +175,12 @@ function buildClient(options: S3DriverOptions): S3ClientLike {
   });
 }
 
-const toDate = (value: string | Date | undefined): Date =>
-  value === undefined ? new Date(0) : value instanceof Date ? value : new Date(value);
+/**
+ * A missing `LastModified` is ABSENT, never `new Date(0)`: epoch 0 is older than every window, so
+ * `sweepOrphans` deleted an upload on the strength of a field the provider never sent.
+ */
+const dated = (value: string | Date | undefined): { readonly lastModified?: Date } =>
+  value === undefined ? {} : { lastModified: value instanceof Date ? value : new Date(value) };
 
 /** One numeric field off a value that may fight being read — `stringField`'s missing twin. */
 function numberField(value: unknown, key: string): number | undefined {
@@ -190,12 +218,12 @@ function isAbsentObject(error: unknown): boolean {
  */
 function refuseUnsupportedPut(bucket: string, key: string, putOptions?: PutOptions): void {
   if (putOptions?.metadata !== undefined || putOptions?.cacheControl !== undefined) {
-    const uri = `s3://${bucket}/${key}`;
-    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`,
-    );
+    const uri = renderFixShellArg(`s3://${bucket}/${key}`, '<s3-uri>');
+    throw new NotImplementedError({
+      cause:
+        'user metadata and cache-control on the s3 driver (Bun exposes no header hook yet) is not implemented by this driver — drop metadata/cacheControl from put(), or set them out of band with the command in fix',
+      fix: `aws s3 cp ${uri} ${uri} --metadata-directive REPLACE`,
+    });
   }
   const sse = putOptions?.serverSideEncryption;
   if (sse === undefined) return;
@@ -203,10 +231,11 @@ function refuseUnsupportedPut(bucket: string, key: string, putOptions?: PutOptio
     sse.algorithm === 'aws:kms'
       ? `{"SSEAlgorithm":"aws:kms","KMSMasterKeyID":"${sse.kmsKeyId ?? '<key-arn>'}"}`
       : '{"SSEAlgorithm":"AES256"}';
-  throw storageNotImplemented(
-    'per-object server-side encryption on the s3 driver (Bun.S3Client exposes acl, storageClass and type, and nothing for x-amz-server-side-encryption)',
-    `set it bucket-wide, then drop serverSideEncryption from put(): aws s3api put-bucket-encryption --bucket ${bucket} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":${rule},"BucketKeyEnabled":true}]}'`,
-  );
+  throw new NotImplementedError({
+    cause:
+      'per-object server-side encryption on the s3 driver (Bun.S3Client exposes acl, storageClass and type, and nothing for x-amz-server-side-encryption) is not implemented by this driver — set it bucket-wide with the command in fix, then drop serverSideEncryption from put()',
+    fix: `aws s3api put-bucket-encryption --bucket ${renderFixShellArg(bucket, '<bucket>')} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":${rule},"BucketKeyEnabled":true}]}'`,
+  });
 }
 
 export function s3Driver(options: S3DriverOptions): StorageDriver {
@@ -218,20 +247,73 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     options.maxPutBytes === undefined ? DEFAULT_MAX_UPLOAD_BYTES : options.maxPutBytes,
     1,
   );
+  const maxGetBytes = finiteCount(
+    'the s3 driver',
+    'maxGetBytes',
+    options.maxGetBytes === undefined ? maxPutBytes : options.maxGetBytes,
+    1,
+  );
   let client: S3ClientLike | undefined;
   const conn = (): S3ClientLike => {
     client ??= buildClient(options);
     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;
+  };
+  /**
+   * A write the provider refused, coded: a denied `s3:PutObject`, a throttle, an expired
+   * credential. The bare `S3Error` used to escape `put()` and `copy()` exactly as it once escaped
+   * `list()` — no code, no fix, an anonymous 500.
+   */
+  const refusedWrite =
+    (key: string) =>
+    (error: unknown): never => {
+      throwIfMisconfigured(error);
+      throw putFailed(
+        DRIVER_NAME,
+        key,
+        error,
+        `aws s3api get-bucket-policy --bucket ${renderFixShellArg(options.bucket, '<bucket>')}`,
+      );
+    };
+
+  /**
+   * A read the provider refused, coded — `refusedWrite`'s twin. A 404 is "not found" wherever it
+   * arrives: an object deleted between `exists()` and the read is absent, not unreadable.
+   */
+  const refusedRead =
+    (key: string) =>
+    (error: unknown): never => {
+      if (isStorageError(error)) throw error;
+      if (isAbsentObject(error)) throw objectNotFound(DRIVER_NAME, key);
+      throwIfMisconfigured(error);
+      throw readFailed(
+        DRIVER_NAME,
+        key,
+        error,
+        `aws s3api head-object --bucket ${renderFixShellArg(options.bucket, '<bucket>')} --key ${renderFixShellArg(key, '<key>')}`,
+      );
+    };
+  const present = (key: string): Promise<boolean> =>
+    conn().file(key).exists().catch(refusedRead(key));
+
   const statObject = async (key: string): Promise<StorageObject> => {
-    const stat = await conn().file(key).stat();
+    const stat = await conn().file(key).stat().catch(refusedRead(key));
     return {
       key,
       size: stat.size,
       contentType: stat.type ?? DEFAULT_CONTENT_TYPE,
       etag: stat.etag ?? '',
-      lastModified: toDate(stat.lastModified),
+      ...dated(stat.lastModified),
     };
   };
 
@@ -241,6 +323,7 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     async put(key: string, body: StorageBody, putOptions?: PutOptions): Promise<StorageObject> {
       const safe = assertSafeKey(key);
       refuseUnsupportedPut(options.bucket, safe, putOptions);
+      assertPutOptions(DRIVER_NAME, putOptions);
       // Buffered on purpose: size and checksum must be known before the object exists — so this
       // path is for objects that FIT IN MEMORY, and `maxPutBytes` is what makes that a contract
       // rather than a hope. User uploads never come through here: they go direct to the bucket
@@ -253,22 +336,33 @@ 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(refusedWrite(safe));
       return statObject(safe);
     },
 
+    async stat(key: string): Promise<StorageObject | undefined> {
+      const safe = assertSafeKey(key);
+      return (await present(safe)) ? statObject(safe) : undefined;
+    },
+
     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 };
+      if (!(await present(safe))) throw objectNotFound(DRIVER_NAME, safe);
+      // The HEAD comes FIRST, and it is the whole point: a client PUT straight into the bucket is
+      // bounded by nothing on this disk, so `arrayBuffer()` on whatever is there was heap growth
+      // the uploader chose. Refused on the provider's own size before a byte is read.
+      const object = await statObject(safe);
+      if (object.size > maxGetBytes) throw getTooLarge(DRIVER_NAME, safe, object.size, maxGetBytes);
+      const bytes = new Uint8Array(await file.arrayBuffer().catch(refusedRead(safe)));
+      return { object, 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);
+      if (!(await present(safe))) throw objectNotFound(DRIVER_NAME, safe);
       return file.stream();
     },
 
@@ -283,11 +377,12 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       const source = assertSafeKey(from);
       const destination = assertSafeKey(to);
       const file = conn().file(source);
-      if (!(await file.exists())) throw objectNotFound(DRIVER_NAME, source);
-      const stat = await file.stat();
+      if (!(await present(source))) throw objectNotFound(DRIVER_NAME, source);
+      const stat = await file.stat().catch(refusedRead(source));
       await conn()
         .file(destination)
-        .write(file, { type: stat.type ?? DEFAULT_CONTENT_TYPE });
+        .write(file, { type: stat.type ?? DEFAULT_CONTENT_TYPE })
+        .catch(refusedWrite(destination));
       return statObject(destination);
     },
 
@@ -299,6 +394,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,
@@ -309,13 +405,14 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     },
 
     async exists(key: string): Promise<boolean> {
-      return conn().file(assertSafeKey(key)).exists();
+      return present(assertSafeKey(key));
     },
 
     async list(listOptions?: ListOptions): Promise<ListPage> {
       const prefix = listOptions?.prefix ?? '';
       // Refused at the seam both drivers share, before the provider is asked: `maxKeys: 0` used to
       // go straight through, while the local disk answered a complete-looking empty page.
+      assertListOptions(listOptions);
       const maxKeys = resolveListLimit(listOptions?.limit);
       // `conn()` OUTSIDE the try: a missing credential or an absent `Bun.S3Client` is this disk
       // misconfigured, and it already answers with its own code and its own fix.
@@ -331,6 +428,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,
@@ -350,7 +448,7 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
           key: entry.key,
           size: entry.size ?? 0,
           etag: entry.eTag ?? '',
-          lastModified: toDate(entry.lastModified),
+          ...dated(entry.lastModified),
         });
       }
       const cursor = result.nextContinuationToken;

package/src/driver.ts

@@ -23,7 +23,12 @@ export interface StorageListEntry {
   /** Absent means the driver's listing does not carry it. Never a fabricated default. */
   readonly contentType?: string | undefined;
   readonly etag: string;
-  readonly lastModified: Date;
+  /**
+   * ABSENT when the provider did not say — never epoch 0, which every age test reads as "older
+   * than any window", and never an invalid `Date`, which is a value a reader has to remember to
+   * test. A reader that needs an age handles `undefined`; `sweepOrphans` spares it.
+   */
+  readonly lastModified?: Date | undefined;
   /** Present only when the driver actually stored what `put()` was handed — never invented. */
   readonly cacheControl?: string | undefined;
   readonly metadata?: Readonly<Record<string, string>> | undefined;
@@ -115,6 +120,17 @@ export interface StorageDriver {
    */
   registerAs?(diskName: string): void;
   put(key: string, body: StorageBody, options?: PutOptions): Promise<StorageObject>;
+  /**
+   * What a read would say about the object, WITHOUT its bytes — `undefined` when nothing is there.
+   * `promoteAttachment` decides on `stat().size`, because a presigned PUT lands on the disk
+   * unmeasured and `get()` is the one call that must not be how its size is learned. Required: a
+   * driver that cannot measure cannot be promoted from, and that is a compile error, not a refusal.
+   */
+  stat(key: string): Promise<StorageObject | undefined>;
+  /**
+   * The whole object, BUFFERED — so bounded: an object over the driver's `maxGetBytes` is
+   * `X_STORAGE_TOO_LARGE`, exactly as `put()` refuses a body over `maxPutBytes`. Past it, `stream()`.
+   */
   get(key: string): Promise<StorageRead>;
   /** Bytes without buffering — the only safe path for anything over a few MB. */
   stream(key: string): Promise<ReadableStream<Uint8Array>>;
@@ -181,6 +197,45 @@ export function resolveListLimit(limit: number | undefined): number {
   return limit;
 }
 
+const isStringRecord = (value: unknown): boolean =>
+  typeof value === 'object' &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.values(value).every((entry) => typeof entry === 'string');
+
+/**
+ * What `put()` was told ABOUT the bytes, held to its type before a byte moves. An untyped caller's
+ * `metadata: { n: 1n }` reached `JSON.stringify` on the local disk as a bare `TypeError`, and the
+ * memory disk stored it — against the `Record<string, string>` every reader is typed on.
+ */
+export function assertPutOptions(driver: string, options: PutOptions | undefined): void {
+  if (options === undefined) return;
+  for (const name of ['contentType', 'cacheControl'] as const) {
+    assert(
+      options[name] === undefined || typeof options[name] === 'string',
+      `put() on the ${driver} disk was given a ${name} that is not a string`,
+      `put(key, body, { ${name}: 'a string' }) — or omit ${name}`,
+    );
+  }
+  assert(
+    options.metadata === undefined || isStringRecord(options.metadata),
+    `put() on the ${driver} disk was given metadata that is not a plain object of string values`,
+    "put(key, body, { metadata: { name: 'value' } }) — every value a string: String(n) a number, JSON.stringify anything nested",
+  );
+}
+
+/** A `prefix` or a `cursor` that is not a string reached `startsWith` and `<=` as whatever it was. */
+export function assertListOptions(options: ListOptions | undefined): void {
+  for (const name of ['prefix', 'cursor'] as const) {
+    const value = options?.[name];
+    assert(
+      value === undefined || typeof value === 'string',
+      `list() was given a ${name} that is not a string`,
+      `disk.list({ ${name}: 'a string' }) — or omit ${name}`,
+    );
+  }
+}
+
 /** What `toBytes` needs to refuse a body: the ceiling, and the key to name in the refusal. */
 export interface ByteLimit {
   readonly driver: string;
@@ -212,6 +267,13 @@ export async function toBytes(body: StorageBody, limit: ByteLimit): Promise<Uint
     }
     return new Uint8Array(await body.arrayBuffer());
   }
+  // The type says so; an untyped caller's `put(key, 'a string')` reached `getReader` as a
+  // bare `TypeError`.
+  assert(
+    body instanceof ReadableStream,
+    `put() on the ${limit.driver} disk was given a body that is not a Uint8Array, a Blob or a ReadableStream`,
+    "put(key, new TextEncoder().encode(text)) — bytes, never a string: encode it, or pass the request's own body stream",
+  );
   return readBounded(body, limit);
 }