@ultimat3/storage 24.0.0 → 25.0.0

package/src/driver-s3.ts

@@ -5,19 +5,21 @@
 // credentials arrive as env var NAMES: a literal key in app.config.ts is a key in git.
 
 import {
-  ConfigInvalidError,
-  EnvMissingError,
+  type Clock,
   finiteCount,
+  isUltimateError,
   NotImplementedError,
+  type Page,
+  pageOf,
+  renderFixLiteral,
   renderFixShellArg,
-  stringField,
+  systemClock,
 } from '@ultimat3/core';
 import {
   assertListOptions,
   assertPutOptions,
   DEFAULT_CONTENT_TYPE,
   type ListOptions,
-  type ListPage,
   type PutOptions,
   resolveListLimit,
   type SignedUrlOptions,
@@ -29,7 +31,11 @@ import {
   sha256Base64,
   toBytes,
 } from './driver';
+import { isAbsentObject } from './driver-s3-absent';
+import { buildClient, type S3ClientLike, type S3ListResultLike } from './driver-s3-client';
+import { needsSignedPut, readObjectLock, signedPut } from './driver-s3-lock';
 import { regionMismatch } from './driver-s3-region';
+import type { S3FetchLike } from './driver-s3-signed';
 import {
   checksumMismatch,
   deleteFailed,
@@ -40,53 +46,13 @@ import {
   putFailed,
   readFailed,
 } from './errors';
+import { assertObjectLockOptions, type ObjectLock } from './object-lock';
 import { assertSafeKey } from './path';
 import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
 import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
 
 const DRIVER_NAME = 's3';
 
-/** Structural view of `Bun.S3Client` — typing it here keeps `bun-types` out of the contract. */
-export interface S3FileLike {
-  /** `S3FileLike` is in the union because Bun's own `write` takes an `S3File` — that is `copy`. */
-  write(data: Uint8Array | Blob | S3FileLike, options?: { type?: string }): Promise<number>;
-  arrayBuffer(): Promise<ArrayBuffer>;
-  exists(): Promise<boolean>;
-  delete(): Promise<void>;
-  stream(): ReadableStream<Uint8Array>;
-  stat(): Promise<S3StatLike>;
-  presign(options: { method?: string; expiresIn?: number; type?: string }): string;
-}
-
-export interface S3StatLike {
-  readonly size: number;
-  readonly type?: string | undefined;
-  readonly etag?: string | undefined;
-  readonly lastModified?: string | Date | undefined;
-}
-
-export interface S3ListEntryLike {
-  readonly key?: string | undefined;
-  readonly size?: number | undefined;
-  readonly eTag?: string | undefined;
-  readonly lastModified?: string | Date | undefined;
-}
-
-export interface S3ListResultLike {
-  readonly contents?: readonly S3ListEntryLike[] | undefined;
-  readonly isTruncated?: boolean | undefined;
-  readonly nextContinuationToken?: string | undefined;
-}
-
-export interface S3ClientLike {
-  file(key: string): S3FileLike;
-  list(input: {
-    prefix?: string;
-    maxKeys?: number;
-    continuationToken?: string;
-  }): Promise<S3ListResultLike>;
-}
-
 export interface S3DriverOptions {
   readonly bucket: string;
   /**
@@ -107,6 +73,15 @@ export interface S3DriverOptions {
   readonly env?: Readonly<Record<string, string | undefined>> | undefined;
   /** Injected in tests; production constructs `Bun.S3Client`. */
   readonly client?: S3ClientLike | undefined;
+  /**
+   * Injected in tests; production uses the global `fetch`. Carries the SIGNED requests the Bun
+   * client has no option for — a `put()` with `metadata`, `cacheControl`, `retention` or
+   * `legalHold`, and `retentionOf()` — signed by core's `signAwsRequest` against the same
+   * endpoint, region and credentials.
+   */
+  readonly fetch?: S3FetchLike | undefined;
+  /** Signs the signed requests and screens a `retainUntil`. Default `systemClock`. */
+  readonly clock?: Clock | undefined;
   /**
    * Ceiling on ONE server-side `put()`, because `put()` buffers the whole body. Defaults to the
    * upload policy's ceiling — the same number for the same fact. Raise it for a disk that really
@@ -122,59 +97,6 @@ export interface S3DriverOptions {
   readonly maxGetBytes?: number | undefined;
 }
 
-interface S3ClientConstructor {
-  new (options: Record<string, unknown>): S3ClientLike;
-}
-
-function requireEnv(
-  env: Readonly<Record<string, string | undefined>>,
-  name: string,
-  partner: string,
-): string {
-  const value = env[name];
-  if (value === undefined || value === '') {
-    throw new EnvMissingError({
-      cause: `${name} is not set, so the s3 disk cannot authenticate`,
-      fix: `set ${name} and ${partner} in .env (or the container's secret store), then re-run`,
-      meta: { missing: name },
-    });
-  }
-  return value;
-}
-
-function buildClient(options: S3DriverOptions): S3ClientLike {
-  if (options.client !== undefined) return options.client;
-  if (options.bucket === '') {
-    throw new ConfigInvalidError({
-      cause: 's3 disk was defined without a bucket',
-      fix: 'set storage.disks.<name>.bucket in app.config.ts',
-    });
-  }
-  const env = options.env ?? process.env;
-  const idVar = options.accessKeyIdEnv ?? 'S3_ACCESS_KEY_ID';
-  const secretVar = options.secretAccessKeyEnv ?? 'S3_SECRET_ACCESS_KEY';
-  const Client = (Bun as unknown as { S3Client?: S3ClientConstructor }).S3Client;
-  if (Client === undefined) {
-    throw new ConfigInvalidError({
-      cause: 'Bun.S3Client is unavailable in this runtime',
-      fix: 'upgrade the runtime: bun upgrade   # the s3 disk needs bun >= 1.3',
-    });
-  }
-  const tokenVar = options.sessionTokenEnv;
-  const sessionToken = tokenVar === undefined ? undefined : env[tokenVar];
-  // Bun's flag is the inverse: path style means "not virtual hosted".
-  const pathStyle = options.forcePathStyle;
-  return new Client({
-    bucket: options.bucket,
-    accessKeyId: requireEnv(env, idVar, secretVar),
-    secretAccessKey: requireEnv(env, secretVar, idVar),
-    ...(options.region === undefined ? {} : { region: options.region }),
-    ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
-    ...(pathStyle === undefined ? {} : { virtualHostedStyle: !pathStyle }),
-    ...(sessionToken === undefined ? {} : { sessionToken }),
-  });
-}
-
 /**
  * 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.
@@ -182,59 +104,27 @@ function buildClient(options: S3DriverOptions): S3ClientLike {
 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 {
-  if (typeof value !== 'object' || value === null) return undefined;
-  try {
-    const held = (value as Record<string, unknown>)[key];
-    return typeof held === 'number' ? held : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/** The provider codes that mean "there is nothing at that key", and nothing wider. */
-const ABSENT_OBJECT_CODES: ReadonlySet<string> = new Set(['NoSuchKey', 'NotFound', 'ENOENT']);
-
-/**
- * The ONE delete failure the contract calls success. `AccessDenied`, `SlowDown`, an expired
- * credential and a reset connection are none of them, and the previous `.catch(() => undefined)`
- * reported all four as deleted — which is how an erasure sweep certifies data it never removed.
- *
- * Read structurally: an `S3Error` is `name: 'S3Error'` with a `code` the service returned, and
- * every field of a value this process did not build is a getter that can throw.
- */
-function isAbsentObject(error: unknown): boolean {
-  const code = stringField(error, 'code');
-  if (code !== undefined && ABSENT_OBJECT_CODES.has(code)) return true;
-  return numberField(error, 'statusCode') === 404 || numberField(error, 'status') === 404;
-}
-
 /**
  * Everything `put()` may be handed that this driver cannot honour, refused before a byte moves.
  * A typed refusal at the call site is the whole point: `serverSideEncryption` exists on
  * `PutOptions` so that "this disk cannot prove per-object encryption" is something an engineer
  * meets while writing the call, not while answering a security review.
  */
-function refuseUnsupportedPut(bucket: string, key: string, putOptions?: PutOptions): void {
-  if (putOptions?.metadata !== undefined || putOptions?.cacheControl !== undefined) {
-    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`,
-    });
-  }
+function refuseUnsupportedPut(bucket: string, putOptions?: PutOptions): void {
   const sse = putOptions?.serverSideEncryption;
   if (sse === undefined) return;
-  const rule =
-    sse.algorithm === 'aws:kms'
-      ? `{"SSEAlgorithm":"aws:kms","KMSMasterKeyID":"${sse.kmsKeyId ?? '<key-arn>'}"}`
-      : '{"SSEAlgorithm":"AES256"}';
+  // The key id is the caller's own option, spliced into single-quoted JSON: `renderFixLiteral`
+  // escapes the `"` and `\` JSON needs, and a `'` — the one byte live inside single quotes — makes
+  // it the placeholder rather than ending the argument (plan 101 row S12).
+  const keyId = sse.kmsKeyId?.includes("'") === false ? sse.kmsKeyId : undefined;
+  const bucketArg = renderFixShellArg(bucket, "'<bucket>'");
   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}]}'`,
+    fix:
+      sse.algorithm === 'aws:kms'
+        ? `aws s3api put-bucket-encryption --bucket ${bucketArg} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms","KMSMasterKeyID":${renderFixLiteral(keyId, '"<key-arn>"')}},"BucketKeyEnabled":true}]}'`
+        : `aws s3api put-bucket-encryption --bucket ${bucketArg} --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"AES256"},"BucketKeyEnabled":true}]}'`,
   });
 }
 
@@ -253,6 +143,10 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     options.maxGetBytes === undefined ? maxPutBytes : options.maxGetBytes,
     1,
   );
+  // The key `defineStorage` registered this disk under: a not-found `fix:` is `disk('<it>')…`,
+  // and the driver kind there is `X_STORAGE_DISK_UNKNOWN` on any app that named its disk.
+  let diskName = DRIVER_NAME;
+  const clock = options.clock ?? systemClock;
   let client: S3ClientLike | undefined;
   const conn = (): S3ClientLike => {
     client ??= buildClient(options);
@@ -277,12 +171,15 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
   const refusedWrite =
     (key: string) =>
     (error: unknown): never => {
+      // A refusal this process already coded — a screened header, a missing credential — is its
+      // own answer, never re-read as the provider refusing the write.
+      if (isUltimateError(error)) throw error;
       throwIfMisconfigured(error);
       throw putFailed(
         DRIVER_NAME,
         key,
         error,
-        `aws s3api get-bucket-policy --bucket ${renderFixShellArg(options.bucket, '<bucket>')}`,
+        `aws s3api get-bucket-policy --bucket ${renderFixShellArg(options.bucket, "'<bucket>'")}`,
       );
     };
 
@@ -294,13 +191,13 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     (key: string) =>
     (error: unknown): never => {
       if (isStorageError(error)) throw error;
-      if (isAbsentObject(error)) throw objectNotFound(DRIVER_NAME, key);
+      if (isAbsentObject(error)) throw objectNotFound(diskName, key);
       throwIfMisconfigured(error);
       throw readFailed(
         DRIVER_NAME,
         key,
         error,
-        `aws s3api head-object --bucket ${renderFixShellArg(options.bucket, '<bucket>')} --key ${renderFixShellArg(key, '<key>')}`,
+        `aws s3api head-object --bucket ${renderFixShellArg(options.bucket, "'<bucket>'")} --key ${renderFixShellArg(key, "'<key>'")}`,
       );
     };
   const present = (key: string): Promise<boolean> =>
@@ -319,11 +216,15 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
 
   return {
     name: DRIVER_NAME,
+    registerAs(name: string): void {
+      diskName = name;
+    },
 
     async put(key: string, body: StorageBody, putOptions?: PutOptions): Promise<StorageObject> {
       const safe = assertSafeKey(key);
-      refuseUnsupportedPut(options.bucket, safe, putOptions);
+      refuseUnsupportedPut(options.bucket, putOptions);
       assertPutOptions(DRIVER_NAME, putOptions);
+      assertObjectLockOptions(DRIVER_NAME, putOptions, clock);
       // 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
@@ -334,6 +235,20 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
         const actual = sha256Base64(bytes);
         if (claimed !== actual) throw checksumMismatch(safe, claimed, actual);
       }
+      if (putOptions !== undefined && needsSignedPut(putOptions)) {
+        // Off the Bun client only for what it cannot send: `S3File.write` takes a type, an ACL and
+        // a storage class and no header. One request either way — never a PUT then a second call.
+        const refusal = await signedPut(options, safe, bytes, putOptions).catch(refusedWrite(safe));
+        if (refusal !== undefined) refusedWrite(safe)(refusal);
+        // Stored — the PUT succeeded with them — so reported, as the local disk reports its own.
+        return {
+          ...(await statObject(safe)),
+          ...(putOptions.cacheControl === undefined
+            ? {}
+            : { cacheControl: putOptions.cacheControl }),
+          ...(putOptions.metadata === undefined ? {} : { metadata: { ...putOptions.metadata } }),
+        };
+      }
       await conn()
         .file(safe)
         .write(bytes, { type: putOptions?.contentType ?? DEFAULT_CONTENT_TYPE })
@@ -349,7 +264,7 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     async get(key: string): Promise<StorageRead> {
       const safe = assertSafeKey(key);
       const file = conn().file(safe);
-      if (!(await present(safe))) throw objectNotFound(DRIVER_NAME, safe);
+      if (!(await present(safe))) throw objectNotFound(diskName, 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.
@@ -362,7 +277,7 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
     async stream(key: string): Promise<ReadableStream<Uint8Array>> {
       const safe = assertSafeKey(key);
       const file = conn().file(safe);
-      if (!(await present(safe))) throw objectNotFound(DRIVER_NAME, safe);
+      if (!(await present(safe))) throw objectNotFound(diskName, safe);
       return file.stream();
     },
 
@@ -377,7 +292,7 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       const source = assertSafeKey(from);
       const destination = assertSafeKey(to);
       const file = conn().file(source);
-      if (!(await present(source))) throw objectNotFound(DRIVER_NAME, source);
+      if (!(await present(source))) throw objectNotFound(diskName, source);
       const stat = await file.stat().catch(refusedRead(source));
       await conn()
         .file(destination)
@@ -399,7 +314,8 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
           DRIVER_NAME,
           safe,
           error,
-          `grant s3:DeleteObject on this prefix to the app's role, then reproduce with the provider's own words: aws s3api delete-object --bucket ${options.bucket} --key ${safe}`,
+          // `isSafeKey` admits `$(…)`, a backtick and `;` — legal key bytes, live shell syntax.
+          `grant s3:DeleteObject on this prefix to the app's role, then reproduce with the provider's own words: aws s3api delete-object --bucket ${renderFixShellArg(options.bucket, "'<bucket>'")} --key ${renderFixShellArg(safe, "'<key>'")}`,
         );
       }
     },
@@ -408,7 +324,22 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
       return present(assertSafeKey(key));
     },
 
-    async list(listOptions?: ListOptions): Promise<ListPage> {
+    /** Signed `GET ?retention` and `?legal-hold`, in parallel. A bucket with no lock reports none. */
+    async retentionOf(key: string): Promise<ObjectLock> {
+      const safe = assertSafeKey(key);
+      const read = await readObjectLock(options, safe).catch(refusedRead(safe));
+      if (read.kind === 'lock') return read.lock;
+      if (isAbsentObject(read.refusal)) throw objectNotFound(diskName, safe);
+      throwIfMisconfigured(read.refusal);
+      throw readFailed(
+        DRIVER_NAME,
+        safe,
+        read.refusal,
+        `aws s3api get-object-retention --bucket ${renderFixShellArg(options.bucket, "'<bucket>'")} --key ${renderFixShellArg(safe, "'<key>'")}   # reproduces the refusal; grant s3:GetObjectRetention and s3:GetObjectLegalHold to the app's role`,
+      );
+    },
+
+    async list(listOptions?: ListOptions): Promise<Page<StorageListEntry>> {
       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.
@@ -422,7 +353,9 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
         result = await client.list({
           maxKeys,
           ...(listOptions?.prefix === undefined ? {} : { prefix: listOptions.prefix }),
-          ...(listOptions?.cursor === undefined ? {} : { continuationToken: listOptions.cursor }),
+          ...(typeof listOptions?.cursor === 'string'
+            ? { continuationToken: listOptions.cursor }
+            : {}),
         });
       } catch (error) {
         // A bare `S3Error` used to escape here, uncoded: no `X_*`, no `fix`, no `--json` shape, and
@@ -433,7 +366,11 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
           DRIVER_NAME,
           prefix,
           error,
-          `grant s3:ListBucket on this bucket to the app's role, then reproduce with the provider's own words: aws s3api list-objects-v2 --bucket ${options.bucket}${prefix === '' ? '' : ` --prefix ${prefix}`}`,
+          // Two whole lines rather than a ternary INSIDE one: each substitution is then a screen
+          // the fix-shell-arg guard can read as one.
+          prefix === ''
+            ? `grant s3:ListBucket on this bucket to the app's role, then reproduce with the provider's own words: aws s3api list-objects-v2 --bucket ${renderFixShellArg(options.bucket, "'<bucket>'")}`
+            : `grant s3:ListBucket on this bucket to the app's role, then reproduce with the provider's own words: aws s3api list-objects-v2 --bucket ${renderFixShellArg(options.bucket, "'<bucket>'")} --prefix ${renderFixShellArg(prefix, "'<prefix>'")}`,
         );
       }
       const objects: StorageListEntry[] = [];
@@ -451,10 +388,13 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
           ...dated(entry.lastModified),
         });
       }
-      const cursor = result.nextContinuationToken;
-      return result.isTruncated === true && cursor !== undefined
-        ? { objects, truncated: true, cursor }
-        : { objects, truncated: false };
+      // `IsTruncated` decides and `NextContinuationToken` is the cursor: a token beside
+      // `IsTruncated: false` is not a next page, and a truncated answer with no token has none to
+      // offer — both are the last page, never a cursor that fetches an empty one.
+      return pageOf(
+        objects,
+        result.isTruncated === true ? (result.nextContinuationToken ?? null) : null,
+      );
     },
 
     /**

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;
@@ -53,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;
@@ -65,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;
@@ -112,11 +115,13 @@ 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>;
@@ -147,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.
    *
@@ -180,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
@@ -229,7 +246,7 @@ 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',
+      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}`,
     );

package/src/errors.ts

@@ -29,6 +29,7 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_KEY_CONFLICT',
   'X_STORAGE_PUT_FAILED',
   'X_STORAGE_READ_FAILED',
+  'X_STORAGE_OBJECT_LOCKED',
 ] as const;
 
 /**
@@ -65,9 +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 the local disk',
+  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
@@ -167,7 +169,7 @@ 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 },
   });
@@ -191,7 +193,7 @@ export const getTooLarge = (
       (disk === 's3'
         ? `s3Driver({ bucket, maxGetBytes: ${bytes} })`
         : disk === 'memory'
-          ? `memoryDriver({ maxGetBytes: ${bytes} })`
+          ? `memoryStorageDriver({ maxGetBytes: ${bytes} })`
           : `localDriver({ root, maxGetBytes: ${bytes} })`),
     meta: { disk, key, bytes, maxBytes },
   });
@@ -199,8 +201,9 @@ export const getTooLarge = (
 /**
  * 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 and the memory
- * disk hold both — this is the local disk's own limit, refused by name rather than hidden.
+ * 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.
@@ -208,7 +211,7 @@ export const getTooLarge = (
 export const keyConflict = (disk: string, key: string, blocking: string): StorageError =>
   new StorageError({
     code: 'X_STORAGE_KEY_CONFLICT',
-    cause: `the "${disk}" disk is a local 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`,
+    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/'")} })`,
@@ -258,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',

package/src/index.ts

@@ -31,7 +31,6 @@ export {
 export type {
   ByteLimit,
   ListOptions,
-  ListPage,
   PutOptions,
   ServerSideEncryption,
   SignedUrlMethod,
@@ -55,17 +54,18 @@ export {
 } from './driver';
 export type { LocalDriverOptions } from './driver-local';
 export { localDriver } from './driver-local';
-export type { MemoryDriverOptions, MemoryStorageDriver } from './driver-memory';
-export { memoryDriver } from './driver-memory';
+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,
@@ -94,6 +94,7 @@ export {
   signingSecretMissing,
   tooLarge,
   uploadFailed,
+  xmlBodyUnreadable,
 } from './errors';
 export type { GrantUploadInput, UploadGrant, UploadRequest } from './grant';
 export { grantUpload } from './grant';
@@ -119,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,7 +161,6 @@ export {
   signConstraints,
   signedUrlBaseFor,
   signedUrlBasePath,
-  timingSafeEqual,
   verifySignedUrl,
 } from './signed-url';
 export {