@ultimat3/storage 23.0.0 → 25.0.0

package/src/driver.ts

@@ -3,9 +3,10 @@
 // strings — a base64 round trip through JSON is how a "small" upload becomes a 33%-larger OOM —
 // and never unbounded, which is the same failure with the sender choosing the size.
 
-import type { Clock } from '@ultimat3/core';
+import type { Clock, Page } from '@ultimat3/core';
 import { assert } from '@ultimat3/core';
 import { putTooLarge } from './errors';
+import type { ObjectLock, ObjectLockOptions } from './object-lock';
 import type { SignedUrlVerification } from './signed-url';
 
 export type StorageBody = Uint8Array | ReadableStream<Uint8Array> | Blob;
@@ -23,7 +24,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;
@@ -48,7 +54,12 @@ export interface ServerSideEncryption {
   readonly kmsKeyId?: string | undefined;
 }
 
-export interface PutOptions {
+/**
+ * `retention` and `legalHold` (from `ObjectLockOptions`) are S3 Object Lock, per object: sent as
+ * `x-amz-object-lock-*` on s3 — which needs a bucket created with Object Lock — and EMULATED by the
+ * local and memory disks, which refuse a delete or an overwrite of a locked object until it lapses.
+ */
+export interface PutOptions extends ObjectLockOptions {
   readonly contentType?: string | undefined;
   readonly cacheControl?: string | undefined;
   readonly metadata?: Readonly<Record<string, string>> | undefined;
@@ -60,18 +71,15 @@ export interface PutOptions {
 
 export interface ListOptions {
   readonly prefix?: string | undefined;
-  /** Opaque; pass back the `cursor` of the previous page. */
-  readonly cursor?: string | undefined;
+  /**
+   * Opaque; pass back the `nextCursor` of the previous page. `null` and absent both mean the
+   * first page, so `cursor: page.nextCursor` threads a loop with no conversion — the loop stops
+   * on `hasMore: false` before a `null` is ever handed back as "the page after the last".
+   */
+  readonly cursor?: string | null | undefined;
   readonly limit?: number | undefined;
 }
 
-export interface ListPage {
-  readonly objects: readonly StorageListEntry[];
-  readonly truncated: boolean;
-  /** Absent when `truncated` is false. */
-  readonly cursor?: string | undefined;
-}
-
 export interface StorageRead {
   readonly object: StorageObject;
   readonly bytes: Uint8Array;
@@ -107,14 +115,27 @@ export interface StorageDriver {
    */
   readonly signedUrlBase?: string | undefined;
   /**
-   * `defineStorage` tells the driver the key it was registered under, at boot, once. A driver that
-   * mints its own URLs hangs them off THAT, never off `name`: the mounted `/_storage/:disk/*key`
-   * route resolves the segment through the registry, so a disk registered as `uploads` whose URLs
-   * say `local` 404s every signature it just wrote. Optional — a driver with no URLs of its own
-   * (`s3`) needs none, and a third-party driver that ignores it keeps minting under `name`.
+   * `defineStorage` tells the driver the key it was registered under, at boot, once. Two readers:
+   * a driver that mints its own URLs hangs them off THAT, never off `name` — the mounted
+   * `/_storage/:disk/*key` route resolves the segment through the registry, so a disk registered
+   * as `uploads` whose URLs say `local` 404s every signature it just wrote — and every
+   * `X_STORAGE_NOT_FOUND`, whose `fix:` is `disk('<name>').list(…)`. `local`, `s3`
+   * and `memory` use it for both — their URLs and their not-found errors. Optional: a
+   * third-party driver that ignores it keeps minting and refusing under `name`.
    */
   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>>;
@@ -131,8 +152,20 @@ export interface StorageDriver {
    */
   delete(key: string): Promise<void>;
   exists(key: string): Promise<boolean>;
-  list(options?: ListOptions): Promise<ListPage>;
+  /**
+   * One page of core's ONE `Page` shape: `nextCursor` exists exactly when another object does,
+   * so a full last page answers `hasMore: false` rather than a cursor to an empty page.
+   */
+  list(options?: ListOptions): Promise<Page<StorageListEntry>>;
   signedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+  /**
+   * What locks one object — its Object Lock retention and legal hold — read back from the disk.
+   * `{ legalHold: false }` with no `retention` means nothing does, including on a bucket created
+   * without Object Lock. `X_STORAGE_NOT_FOUND` when no object is at the key. Optional, like
+   * `registerAs`: every shipped disk answers it, and a third-party driver that does not is a
+   * driver with no lock to report.
+   */
+  retentionOf?(key: string): Promise<ObjectLock>;
   /**
    * Verify a URL THIS disk minted — without surrendering the key it minted with.
    *
@@ -164,7 +197,7 @@ export const DEFAULT_LIST_LIMIT = 1000;
  * The page size a `list()` honours — refused rather than clamped when it cannot be one.
  *
  * At the `ListOptions` seam and not inside a driver, because the two answered a non-positive
- * limit differently: the local disk sliced `[0, 0)` and then dropped its own `truncated` flag, so
+ * limit differently: the local disk sliced `[0, 0)` and then dropped its own "more" flag, so
  * `list({ limit: 0 })` over a full disk reported a COMPLETE empty listing, while the s3 disk
  * handed `maxKeys: 0` straight to the provider. `sweepOrphans` pages through `list()`, so a page
  * that is empty and claims to be complete is a false erasure report — the same lie a swallowed
@@ -181,6 +214,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' || (name === 'cursor' && value === null),
+      `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 +284,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);
 }
 

package/src/errors.ts

@@ -2,7 +2,12 @@
 // rejected upload must tell the caller which constraint fired and where that constraint is
 // configured, or the caller retries the same bytes forever.
 
-import { registerErrorCodes, renderThrowable, UltimateError } from '@ultimat3/core';
+import {
+  registerErrorCodes,
+  renderFixLiteral,
+  renderThrowable,
+  UltimateError,
+} from '@ultimat3/core';
 
 /** Codes this package declares and owns. */
 export const STORAGE_OWNED_ERROR_CODES = [
@@ -21,11 +26,15 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_LIST_FAILED',
   'X_STORAGE_QUARANTINED',
   'X_STORAGE_NOT_PENDING',
+  'X_STORAGE_KEY_CONFLICT',
+  'X_STORAGE_PUT_FAILED',
+  'X_STORAGE_READ_FAILED',
+  'X_STORAGE_OBJECT_LOCKED',
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. `storageNotImplemented()` throws it and this package
- * keeps no title for it — one code, one owner, one title, or the two copies drift apart in silence.
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. The drivers throw core's own `NotImplementedError`
+ * and this package keeps no title for it — one code, one owner, one title, or the two copies drift apart in silence.
  * `X_IMAGE_UNSUPPORTED` / `X_IMAGE_DECODE_FAILED` are core's too and surface unwrapped (`image.ts`).
  * `X_ENV_MISSING` is core's for the same reason: an unset `STORAGE_SIGNING_SECRET` outside
  * development is a missing environment variable, not a storage concept needing its own code.
@@ -57,6 +66,10 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_LIST_FAILED: 'the objects could not be listed',
   X_STORAGE_QUARANTINED: 'the object is still in quarantine',
   X_STORAGE_NOT_PENDING: 'the key is not a pending upload',
+  X_STORAGE_KEY_CONFLICT: 'the key collides with another key on a local or memory disk',
+  X_STORAGE_PUT_FAILED: 'the object could not be written',
+  X_STORAGE_READ_FAILED: 'the object could not be read',
+  X_STORAGE_OBJECT_LOCKED: 'the object is under retention or a legal hold',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws
@@ -156,11 +169,55 @@ export const putTooLarge = (
       (disk === 's3'
         ? `s3Driver({ bucket, maxPutBytes: ${bytes} })`
         : disk === 'memory'
-          ? `memoryDriver({ maxPutBytes: ${bytes} })`
+          ? `memoryStorageDriver({ maxPutBytes: ${bytes} })`
           : `localDriver({ root, maxPutBytes: ${bytes} })`),
     meta: { disk, key, bytes, maxBytes },
   });
 
+/**
+ * The SERVER-side `get()` ceiling — `putTooLarge`'s twin. `get()` buffers the whole object, and an
+ * object's size is not this process's to choose: a presigned PUT lands in the bucket unmeasured,
+ * so a later `get()` of it was heap growth the uploader picked.
+ */
+export const getTooLarge = (
+  disk: string,
+  key: string,
+  bytes: number,
+  maxBytes: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TOO_LARGE',
+    cause: `"${key}" is ${bytes}B against the ${disk} disk's get ceiling of ${maxBytes}B, and get() buffers the whole object`,
+    fix:
+      `read it with disk.stream(key) instead of get(), or raise the ceiling: ` +
+      (disk === 's3'
+        ? `s3Driver({ bucket, maxGetBytes: ${bytes} })`
+        : disk === 'memory'
+          ? `memoryStorageDriver({ maxGetBytes: ${bytes} })`
+          : `localDriver({ root, maxGetBytes: ${bytes} })`),
+    meta: { disk, key, bytes, maxBytes },
+  });
+
+/**
+ * The local disk stores an object as a FILE at its key, so a key cannot also be the directory of
+ * another: `put('a')` then `put('a/b')`, or the reverse, or the same pair one tree over in the
+ * sidecars (`a` and `a.json/b`). It surfaced as a bare `ENOTDIR` / `EISDIR`. S3 holds both —
+ * this is the local disk's own limit, refused by name rather than hidden, and the memory disk
+ * emulates it (`driver-memory-conflict.ts`) because a test's disk stands in for the dev disk.
+ *
+ * The `fix` lists what is in the way: the remedy is storing one of the two under another key, and
+ * which one is only decidable by a reader who can see both.
+ */
+export const keyConflict = (disk: string, key: string, blocking: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_KEY_CONFLICT',
+    cause: `the "${disk}" disk stores keys as POSIX paths (a local disk, or the memory disk standing in for one) and cannot store "${key}": "${blocking}" is already on it, and a POSIX path is a file or a directory, never both — so one key cannot be a path prefix of another here. Store one of the two under a different key; an s3 disk holds both`,
+    // The REGISTERED name, never the driver kind: `disk('local')` on a disk registered as
+    // `uploads` lists another disk, or answers X_STORAGE_DISK_UNKNOWN.
+    fix: `disk(${renderFixLiteral(disk, "'local'")}).list({ prefix: ${renderFixLiteral(blocking, "'a/'")} })`,
+    meta: { disk, key, blocking },
+  });
+
 /** The declared type is not on the allowlist at all. */
 export const contentTypeNotAllowed = (
   key: string,
@@ -204,6 +261,20 @@ export const contentTypeUnrecognised = (key: string, declared: string): StorageE
     meta: { key, declared },
   });
 
+/**
+ * The XML twin of `contentTypeUnrecognised`: no signature names an XML type, so "matches no known
+ * signature" would be false here. The finding is that the bytes are not UTF-8 text — UTF-16, a
+ * legacy charset, a control byte — so the screen for script-carrying markup never saw what a
+ * browser would decode. Same shipped code: what a client retries on is unchanged.
+ */
+export const xmlBodyUnreadable = (key: string, declared: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TYPE_REJECTED',
+    cause: `"${key}" declares ${declared}, and its bytes are not readable UTF-8 text, so they cannot be screened for the script a browser would run from them`,
+    fix: `validateUpload({ key: ${renderFixLiteral(key, "'a/data.xml'")}, declaredContentType: ${renderFixLiteral(declared, "'application/xml'")}, bytes: new TextEncoder().encode(text) }, policy) — where text is the document decoded from its own charset (iconv -f UTF-16 -t UTF-8), with no byte-order mark and no control characters`,
+    meta: { key, declared },
+  });
+
 export const checksumMismatch = (key: string, declared: string, actual: string): StorageError =>
   new StorageError({
     code: 'X_STORAGE_CHECKSUM_MISMATCH',
@@ -258,6 +329,43 @@ export const deleteFailed = (
   });
 };
 
+/**
+ * A write the disk REFUSED — `deleteFailed`'s twin for `put()` and `copy()`. The local disk's
+ * `EACCES` / `ENOSPC` / `EROFS` left as a bare filesystem `Error`, and a provider's refused PUT as
+ * a bare `S3Error`: no code, no fix, nothing for the http error map to render but an anonymous 500.
+ * The `fix` is the driver's, for `deleteFailed`'s reason.
+ */
+export const putFailed = (disk: string, key: string, error: unknown, fix: string): StorageError => {
+  const reason = renderThrowable(error);
+  return new StorageError({
+    code: 'X_STORAGE_PUT_FAILED',
+    cause: `disk "${disk}" refused to write "${key}": ${reason}`,
+    fix,
+    meta: { disk, key, reason },
+  });
+};
+
+/**
+ * A read the disk REFUSED — `putFailed`'s read-side twin, for `get`, `stat`, `exists`, `stream` and
+ * the read half of `copy`. A denied `s3:GetObject`, a throttle, `EACCES`, `EIO`. An object that is
+ * simply absent is `objectNotFound`, never this: "not there" and "could not look" need opposite
+ * answers from a caller. The `fix` is the driver's, for `deleteFailed`'s reason.
+ */
+export const readFailed = (
+  disk: string,
+  key: string,
+  error: unknown,
+  fix: string,
+): StorageError => {
+  const reason = renderThrowable(error);
+  return new StorageError({
+    code: 'X_STORAGE_READ_FAILED',
+    cause: `disk "${disk}" refused to read "${key}": ${reason}`,
+    fix,
+    meta: { disk, key, reason },
+  });
+};
+
 /**
  * A listing the disk REFUSED — a denied `s3:ListBucket`, a throttle, an expired credential, a root
  * this process cannot read. Exactly `deleteFailed`'s shape and for exactly its reason: an empty
@@ -363,12 +471,3 @@ export const signingSecretMissing = (environment: string, disk = 'local'): Stora
     fix: 'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
     meta: { key: 'STORAGE_SIGNING_SECRET', environment },
   });
-
-/** An interface-complete driver whose remote half is not bound yet. Always carries a fix. */
-export const storageNotImplemented = (feature: string, fix: string): StorageError =>
-  new StorageError({
-    code: 'X_NOT_IMPLEMENTED',
-    cause: `${feature} is declared but not implemented in @ultimat3/storage`,
-    fix,
-    meta: { feature },
-  });

package/src/grant.ts

@@ -83,12 +83,12 @@ export async function grantUpload(input: GrantUploadInput): Promise<UploadGrant>
   }
 
   // Refused here as well as in the presigner one call down: `expiresAt: now + NaN` is `NaN` in the
-  // grant this function RETURNS, and the message a caller can act on names `createUploadGrant`'s
+  // grant this function RETURNS, and the message a caller can act on names `grantUpload`'s
   // own option rather than `buildSignedUrl`'s.
   // `=== undefined`, never `??`, for the reason `buildSignedUrl` states: `??` coalesces on `null`
   // too, so an explicit one took the default instead of this refusal.
   const expiresInMs = finiteCount(
-    'createUploadGrant',
+    'grantUpload',
     'expiresInMs',
     input.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : input.expiresInMs,
     1,

package/src/image.ts

@@ -6,12 +6,13 @@
 import {
   assertFiniteImageQuality,
   blurDataUrl,
+  finiteCount,
   type ImageFormat,
   imageUnsupported,
   probeImage,
   transformImageBytes,
 } from '@ultimat3/core';
-import { assertSafeKey, keyExtname } from './path';
+import { assertSafeKey } from './path';
 
 /**
  * The formats a stored VARIANT can be minted in — a strict subset of the ones `@ultimat3/core`
@@ -67,13 +68,28 @@ const FORMAT_EXTENSIONS: Readonly<Record<VariantFormat, string>> = {
   png: 'png',
 };
 
+/**
+ * One edge of a variant box: a whole number of pixels, at least one. Core's `finiteCount`, for the
+ * reason `quality` goes through core's screen below — `{ width: NaN }` minted `a@wNaN.webp`, a
+ * writable key for bytes no encoder can produce, and `w1.5` / `w-3` are an unbounded number of
+ * keys in a bucket. `!== undefined`, never a truthiness test: an explicit `null` is refused.
+ */
+function edge(subject: string, option: 'width' | 'height', value: number | undefined): void {
+  if (value !== undefined) finiteCount(subject, option, value, 1);
+}
+
 /**
  * Derived, not stored: the same source + transform always yields the same key, so a variant
  * is a cache lookup rather than a database row.
+ *
+ * The WHOLE source key is the stem, extension included. It used to be cut, so `p/hero.png` and
+ * `p/hero.jpg` minted one `p/hero@w100.webp` and whichever was requested first was served for
+ * both — two sources, one cache identity.
  */
 export function variantKey(sourceKey: string, transform: ImageTransform): string {
   const safe = assertSafeKey(sourceKey);
-  const stem = safe.slice(0, safe.length - keyExtname(safe).length);
+  edge('variantKey', 'width', transform.width);
+  edge('variantKey', 'height', transform.height);
   // `string`, not `VariantFormat`: a format off a query string or through an `as` reaches here as
   // any string core can probe, and indexing FORMAT_EXTENSIONS with `gif` minted
   // `photos/hero@full.undefined` — a well-formed, writable key naming a file nothing can serve.
@@ -101,7 +117,7 @@ export function variantKey(sourceKey: string, transform: ImageTransform): string
   );
   if (quality !== DEFAULT_QUALITY) parts.push(`q${quality}`);
   if (parts.length === 0) parts.push('full');
-  return assertSafeKey(`${stem}@${parts.join('-')}.${FORMAT_EXTENSIONS[format]}`);
+  return assertSafeKey(`${safe}@${parts.join('-')}.${FORMAT_EXTENSIONS[format]}`);
 }
 
 export interface SrcsetDescriptor {
@@ -139,23 +155,33 @@ export function srcsetDescriptors(
     }));
 }
 
-/** Aspect-ratio fitting. `cover` rounds up so the box is always fully covered. */
+/** A derived edge is never zero: 1000x1 at width 100 rounded to a height no encoder can fill. */
+const atLeastOne = (pixels: number): number => Math.max(1, Math.round(pixels));
+
+/**
+ * Aspect-ratio fitting. `cover` is the exact box asked for; everything else fits INSIDE the box
+ * and never above the source — upscaling is never useful, whichever edges were named.
+ */
 export function fitDimensions(source: ImageSize, transform: ImageTransform): ImageSize {
   const ratio = source.height / source.width;
   const { width, height } = transform;
+  edge('fitDimensions', 'width', width);
+  edge('fitDimensions', 'height', height);
   if (width === undefined && height === undefined) return source;
   if (height === undefined) {
     const target = Math.min(width ?? source.width, source.width);
-    return { width: target, height: Math.round(target * ratio) };
+    return { width: target, height: atLeastOne(target * ratio) };
   }
   if (width === undefined) {
     const target = Math.min(height, source.height);
-    return { width: Math.round(target / ratio), height: target };
+    return { width: atLeastOne(target / ratio), height: target };
   }
   // `cover` crops to the exact box; `contain` scales down until both sides fit.
   if (transform.fit === 'cover') return { width, height };
-  const scale = Math.min(width / source.width, height / source.height);
-  return { width: Math.round(source.width * scale), height: Math.round(source.height * scale) };
+  // Clamped at 1: a single named edge already stopped at the source, and two of them did not —
+  // a 40x20 source asked for 400x400 came back 400x200.
+  const scale = Math.min(1, width / source.width, height / source.height);
+  return { width: atLeastOne(source.width * scale), height: atLeastOne(source.height * scale) };
 }
 
 /**

package/src/index.ts

@@ -31,7 +31,6 @@ export {
 export type {
   ByteLimit,
   ListOptions,
-  ListPage,
   PutOptions,
   ServerSideEncryption,
   SignedUrlMethod,
@@ -43,33 +42,30 @@ export type {
   StorageRead,
 } from './driver';
 export {
+  // Exported for the same reason `toBytes` is: a driver written outside this package has to
+  // refuse a `limit` the same way both shipped ones do, or it is a third answer to one question.
+  assertPutOptions,
   DEFAULT_CONTENT_TYPE,
   DEFAULT_LIST_LIMIT,
   etagOf,
-  // Exported for the same reason `toBytes` is: a driver written outside this package has to
-  // refuse a `limit` the same way both shipped ones do, or it is a third answer to one question.
   resolveListLimit,
   sha256Base64,
   toBytes,
 } from './driver';
 export type { LocalDriverOptions } from './driver-local';
-export {
-  DEV_SIGNING_SECRET,
-  localDriver,
-  STORAGE_SIGNING_SECRET_KEY,
-  usesDevStorageSecret,
-} from './driver-local';
-export type { MemoryDriverOptions, MemoryStorageDriver } from './driver-memory';
-export { memoryDriver } from './driver-memory';
+export { localDriver } from './driver-local';
+export type { MemoryStorageDriver, MemoryStorageDriverOptions } from './driver-memory';
+export { memoryStorageDriver } from './driver-memory';
+export type { S3DriverOptions } from './driver-s3';
+export { s3Driver } from './driver-s3';
 export type {
   S3ClientLike,
-  S3DriverOptions,
   S3FileLike,
   S3ListEntryLike,
   S3ListResultLike,
   S3StatLike,
-} from './driver-s3';
-export { s3Driver } from './driver-s3';
+} from './driver-s3-client';
+export type { S3FetchLike } from './driver-s3-signed';
 export type { StorageErrorCode, StorageErrorInit } from './errors';
 export {
   checksumMismatch,
@@ -78,13 +74,17 @@ export {
   contentTypeUnrecognised,
   deleteFailed,
   diskUnknown,
+  getTooLarge,
   isStorageError,
+  keyConflict,
   listFailed,
   objectNotFound,
   orgMismatch,
   pathUnsafe,
+  putFailed,
   putTooLarge,
   quarantined,
+  readFailed,
   STORAGE_ERROR_CODES,
   STORAGE_ERROR_TITLES,
   StorageError,
@@ -92,9 +92,9 @@ export {
   signedUrlRejected,
   signedUrlUnverifiable,
   signingSecretMissing,
-  storageNotImplemented,
   tooLarge,
   uploadFailed,
+  xmlBodyUnreadable,
 } from './errors';
 export type { GrantUploadInput, UploadGrant, UploadRequest } from './grant';
 export { grantUpload } from './grant';
@@ -120,6 +120,14 @@ export {
   VARIANT_FORMATS,
   variantKey,
 } from './image';
+export type {
+  LockedAction,
+  ObjectLock,
+  ObjectLockOptions,
+  ObjectRetention,
+  RetentionMode,
+} from './object-lock';
+export { isLocked, ObjectLockedError, RETENTION_MODES } from './object-lock';
 
 export {
   assertSafeKey,
@@ -152,9 +160,14 @@ export {
   SIGNED_URL_VERSION,
   signConstraints,
   signedUrlBaseFor,
-  timingSafeEqual,
+  signedUrlBasePath,
   verifySignedUrl,
 } from './signed-url';
+export {
+  DEV_SIGNING_SECRET,
+  STORAGE_SIGNING_SECRET_KEY,
+  usesDevStorageSecret,
+} from './signing-secret';
 export type { Storage, StorageConfig } from './storage';
 export { definedStorage, defineStorage, disk, resetStorage, storage } from './storage';
 export type { UploadCandidate, UploadPolicy, UploadPolicyInit, ValidatedUpload } from './upload';

package/src/iso-bmff.ts

@@ -0,0 +1,50 @@
+// Single responsibility: which media type an ISO base media file is. Every MP4, MOV, M4A, HEIC
+// and AVIF opens with the same `ftyp` box, so the box alone says "container" — the four-byte MAJOR
+// BRAND after it is what says which one, and reading only the box labelled all of them `video/mp4`.
+
+const ascii = (bytes: Uint8Array, offset: number): string =>
+  String.fromCharCode(...bytes.subarray(offset, offset + 4));
+
+/** The type a major brand cannot narrow: a container, as `application/zip` is one for OOXML. */
+export const ISO_BMFF_CONTAINER = 'video/mp4';
+
+/** HEIF's structural brands — a still HEIC and a still AVIF both ship under `mif1`. */
+export const HEIF_CONTAINER = 'image/heif';
+
+// A `Map`, never an object literal: the brand is four bytes off an upload, and `BRANDS['cons']`
+// is harmless only until a brand spells a prototype key.
+const BRANDS: ReadonlyMap<string, string> = new Map([
+  ['avif', 'image/avif'],
+  ['avis', 'image/avif'],
+  ['heic', 'image/heic'],
+  ['heix', 'image/heic'],
+  ['heim', 'image/heic'],
+  ['heis', 'image/heic'],
+  ['hevc', 'image/heic'],
+  ['hevx', 'image/heic'],
+  ['mif1', HEIF_CONTAINER],
+  ['msf1', HEIF_CONTAINER],
+  ['qt  ', 'video/quicktime'],
+  ['M4A ', 'audio/mp4'],
+  ['M4B ', 'audio/mp4'],
+  ['M4P ', 'audio/mp4'],
+  ['3gp4', 'video/3gpp'],
+  ['3gp5', 'video/3gpp'],
+  ['3gp6', 'video/3gpp'],
+  ['3g2a', 'video/3gpp2'],
+]);
+
+/** Every type `sniffIsoBmff` can answer — what `validateUpload` reads "could confirm" from. */
+export const ISO_BMFF_TYPES: readonly string[] = [
+  ...new Set([ISO_BMFF_CONTAINER, ...BRANDS.values()]),
+];
+
+/**
+ * `undefined` when the bytes do not open with a `ftyp` box carrying a brand. A brand this table
+ * does not list answers the container: it is an ISO base media file, which is all the box proves,
+ * and that is the answer every brand got before this file existed.
+ */
+export function sniffIsoBmff(bytes: Uint8Array): string | undefined {
+  if (bytes.byteLength < 12 || ascii(bytes, 4) !== 'ftyp') return undefined;
+  return BRANDS.get(ascii(bytes, 8)) ?? ISO_BMFF_CONTAINER;
+}