@ultimat3/storage 29.4.0 → 30.1.0

package/src/driver-s3-multipart.ts

@@ -0,0 +1,177 @@
+// Single responsibility: the S3 multipart calls (create, part, complete, abort, list parts, list uploads) over the disk's signed requests. Each answers
+// what its caller goes on with, or hands the provider's refusal to the disk's coded `refused`. The
+// order they run in, and what a failure aborts, is the caller's.
+
+import { escapeHtml } from '@ultimat3/core';
+import { type S3Refusal, type S3WireOptions, sendSigned, xmlField } from './driver-s3-signed';
+import type { MultipartSession, UploadedPart } from './multipart';
+
+export interface S3UploadTarget {
+  readonly wire: S3WireOptions;
+  readonly key: string;
+  /** The disk's coded write refusal. A refusal is never thrown bare. */
+  readonly refused: (refusal: S3Refusal) => never;
+}
+
+const unreadable = (what: string): S3Refusal => ({
+  name: 'S3Error',
+  code: 'UnreadableAnswer',
+  message: `the provider's answer to ${what} carried nothing to go on`,
+  statusCode: 200,
+});
+
+/** Every `<name>…</name>` block of an S3 listing, in order; the shapes read here are flat. */
+export const xmlBlocks = (xml: string, name: string): readonly string[] =>
+  [...xml.matchAll(new RegExp(`<${name}>([\\s\\S]*?)</${name}>`, 'g'))].map(
+    (match) => match[1] ?? '',
+  );
+
+/** XML's entities: S3 writes an etag as `&quot;…&quot;` and a key's `&` as `&amp;`. */
+export const xmlText = (text: string): string =>
+  text
+    // A numeric reference too: a gateway writes the etag's quotes as `&#34;`, S3 as `&quot;`.
+    .replace(/&#(x[0-9a-f]{1,6}|[0-9]{1,7});/gi, (_, code: string) =>
+      String.fromCodePoint(
+        Math.min(Number(code[0] === 'x' || code[0] === 'X' ? `0${code}` : code), 0x10ffff),
+      ),
+    )
+    .replaceAll('&quot;', '"')
+    .replaceAll('&apos;', "'")
+    .replaceAll('&lt;', '<')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&amp;', '&');
+
+// Core's table: `&#39;`/`&quot;` are numeric/XML references too, so its output is valid XML text.
+const completeXml = (parts: readonly { partNumber: number; etag: string }[]): Uint8Array =>
+  new TextEncoder().encode(
+    `<CompleteMultipartUpload>${parts
+      .map(
+        ({ partNumber, etag }) =>
+          `<Part><PartNumber>${partNumber}</PartNumber><ETag>${escapeHtml(etag)}</ETag></Part>`,
+      )
+      .join('')}</CompleteMultipartUpload>`,
+  );
+
+/** CreateMultipartUpload. The object's own headers travel here: a part has none. */
+export async function createS3Upload(
+  { wire, key, refused }: S3UploadTarget,
+  headers: Readonly<Record<string, string>>,
+): Promise<string> {
+  const result = await sendSigned(wire, { method: 'POST', key, headers, query: { uploads: '' } });
+  if (!result.ok) return refused(result.refusal);
+  const id = xmlField(await result.response.text(), 'UploadId');
+  return id === undefined ? refused(unreadable('CreateMultipartUpload')) : id;
+}
+
+/** UploadPart, answering the etag the Complete must name. */
+export async function uploadS3Part(
+  { wire, key, refused }: S3UploadTarget,
+  uploadId: string,
+  partNumber: number,
+  body: Uint8Array,
+): Promise<string> {
+  const result = await sendSigned(wire, {
+    method: 'PUT',
+    key,
+    query: { partNumber: String(partNumber), uploadId },
+    body,
+  });
+  if (!result.ok) return refused(result.refusal);
+  await result.response.body?.cancel().catch(() => undefined);
+  const etag = result.response.headers.get('etag');
+  return etag === null ? refused(unreadable('UploadPart')) : etag;
+}
+
+/** CompleteMultipartUpload, `parts` ascending. The object exists only once this returns. */
+export async function completeS3Upload(
+  { wire, key, refused }: S3UploadTarget,
+  uploadId: string,
+  parts: readonly { readonly partNumber: number; readonly etag: string }[],
+): Promise<void> {
+  const result = await sendSigned(wire, {
+    method: 'POST',
+    key,
+    query: { uploadId },
+    body: completeXml(parts),
+  });
+  if (!result.ok) return refused(result.refusal);
+  // S3 answers a failed Complete with 200 and an `<Error>` body, once it has started working.
+  const answer = await result.response.text();
+  if (answer.includes('<Error>')) {
+    refused({
+      name: 'S3Error',
+      code: xmlField(answer, 'Code') ?? 'CompleteFailed',
+      message: xmlField(answer, 'Message') ?? 'the provider refused the Complete',
+      statusCode: 200,
+    });
+  }
+}
+
+/** AbortMultipartUpload. `undefined` on success; the refusal otherwise, for the caller to weigh. */
+export async function abortS3Upload(
+  { wire, key }: S3UploadTarget,
+  uploadId: string,
+): Promise<S3Refusal | undefined> {
+  const result = await sendSigned(wire, { method: 'DELETE', key, query: { uploadId } });
+  return result.ok ? undefined : result.refusal;
+}
+
+/** ListParts, every page: what landed, which is the resume and the Complete's etags. */
+export async function listS3Parts(
+  { wire, key, refused }: S3UploadTarget,
+  uploadId: string,
+): Promise<readonly UploadedPart[]> {
+  const parts: UploadedPart[] = [];
+  let marker: string | undefined;
+  for (;;) {
+    const query = { uploadId, ...(marker === undefined ? {} : { 'part-number-marker': marker }) };
+    const result = await sendSigned(wire, { method: 'GET', key, query });
+    if (!result.ok) return refused(result.refusal);
+    const answer = await result.response.text();
+    for (const block of xmlBlocks(answer, 'Part')) {
+      const partNumber = Number(xmlField(block, 'PartNumber'));
+      const size = Number(xmlField(block, 'Size'));
+      const etag = xmlText(xmlField(block, 'ETag') ?? '');
+      if (Number.isSafeInteger(partNumber) && Number.isSafeInteger(size) && etag !== '') {
+        parts.push({ partNumber, etag, size });
+      }
+    }
+    marker = xmlField(answer, 'NextPartNumberMarker');
+    if (xmlField(answer, 'IsTruncated') !== 'true' || marker === undefined) break;
+  }
+  return parts.sort((a, b) => a.partNumber - b.partNumber);
+}
+
+/** ListMultipartUploads under a prefix, every page: the sessions nobody completed or aborted. */
+export async function listS3Uploads(
+  { wire, refused }: Omit<S3UploadTarget, 'key'>,
+  prefix: string | undefined,
+): Promise<readonly MultipartSession[]> {
+  const sessions: MultipartSession[] = [];
+  let markers: Readonly<Record<string, string>> = {};
+  for (;;) {
+    const query = { uploads: '', ...(prefix === undefined ? {} : { prefix }), ...markers };
+    const result = await sendSigned(wire, { method: 'GET', key: '', query });
+    if (!result.ok) return refused(result.refusal);
+    const answer = await result.response.text();
+    for (const block of xmlBlocks(answer, 'Upload')) {
+      const key = xmlText(xmlField(block, 'Key') ?? '');
+      const uploadId = xmlText(xmlField(block, 'UploadId') ?? '');
+      const initiated = new Date(xmlField(block, 'Initiated') ?? '');
+      if (key === '' || uploadId === '') continue;
+      sessions.push({
+        key,
+        uploadId,
+        ...(Number.isNaN(initiated.getTime()) ? {} : { initiated }),
+      });
+    }
+    const nextKey = xmlField(answer, 'NextKeyMarker');
+    const nextId = xmlField(answer, 'NextUploadIdMarker');
+    if (xmlField(answer, 'IsTruncated') !== 'true' || nextKey === undefined) break;
+    markers = {
+      'key-marker': xmlText(nextKey),
+      ...(nextId === undefined ? {} : { 'upload-id-marker': xmlText(nextId) }),
+    };
+  }
+  return sessions;
+}

package/src/driver-s3-presign.ts

@@ -0,0 +1,52 @@
+// Single responsibility: the s3 disk's `signedUrl`, both presigners under one rule. Bun's presign
+// binds method and expiry and signs `host` alone: `type` becomes `response-content-type`, which
+// governs a GET, so a PUT's `Content-Type` is unsigned and `promoteAttachment` sniffs the object. A
+// `contentLength` leaves Bun for core's signer, the one way a presign can hold a size.
+
+import { assert, finiteCount, MAX_AWS_PRESIGN_SECONDS } from '@ultimat3/core';
+import { type SignedUrlOptions, signedByteBound } from './driver';
+import type { S3FileLike } from './driver-s3-client';
+import { presignBoundPut, type S3WireOptions } from './driver-s3-signed';
+import { uploadSizeUndeclared } from './errors-stream';
+import { assertSafeKey } from './path';
+import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
+
+export async function s3SignedUrl(
+  wire: S3WireOptions,
+  fileOf: (key: string) => S3FileLike,
+  key: string,
+  urlOptions: SignedUrlOptions | undefined,
+): Promise<string> {
+  // Screened with the SAME function `buildSignedUrl` applies on the local disk: `Math.ceil(NaN /
+  // 1000)` is `NaN`, so `X-Amz-Expires=NaN` went to AWS and the app got a 403 on a link it believed
+  // it had just minted. `=== undefined` rather than `??`, so an explicit `null` is refused.
+  const expiresInMs = finiteCount(
+    'the s3 driver',
+    'expiresInMs',
+    urlOptions?.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : urlOptions.expiresInMs,
+    1,
+  );
+  const seconds = Math.ceil(expiresInMs / 1000);
+  // Before the branch, so Bun's presign cannot mint a URL past SigV4's limit the other refuses.
+  assert(
+    seconds <= MAX_AWS_PRESIGN_SECONDS,
+    `signedUrl() on the s3 disk was given expiresInMs ${expiresInMs}, past SigV4's seven days`,
+    `signedUrl(key, { expiresInMs: ${MAX_AWS_PRESIGN_SECONDS * 1000} })   # the longest a presign lives`,
+  );
+  const safe = assertSafeKey(key);
+  const contentLength = signedByteBound('s3', urlOptions);
+  if (urlOptions?.contentLength !== undefined && contentLength !== undefined) {
+    return presignBoundPut(wire, safe, contentLength, seconds, urlOptions?.part);
+  }
+  // A part names its exact size or nothing: Bun's presign below would drop it and sign a whole PUT.
+  if (urlOptions?.part !== undefined) throw uploadSizeUndeclared(safe, undefined);
+  // A ceiling bounds a PUT; a read has no body, and the local disks ignore it there too.
+  if (urlOptions?.method === 'PUT' && urlOptions.maxBytes !== undefined) {
+    throw uploadSizeUndeclared(safe, undefined);
+  }
+  return fileOf(safe).presign({
+    method: urlOptions?.method ?? 'GET',
+    expiresIn: seconds,
+    ...(urlOptions?.contentType === undefined ? {} : { type: urlOptions.contentType }),
+  });
+}

package/src/driver-s3-put-stream.ts

@@ -0,0 +1,97 @@
+// Single responsibility: `putStream` on the s3 wire — the pump that cuts a body into parts. Not
+// `S3File.writer()`, measured on Bun 1.4.4: `end(error)` COMPLETES the upload, so an overrun would
+// replace the object at the key, and the writer cannot send `x-amz-meta-*`. Here the object does not
+// exist until the Complete, and every other exit aborts.
+
+import { pumpBounded } from './byte-pump';
+import type { PutOptions } from './driver';
+import { objectHeaders, signedPut } from './driver-s3-lock';
+import {
+  abortS3Upload,
+  completeS3Upload,
+  createS3Upload,
+  type S3UploadTarget,
+  uploadS3Part,
+} from './driver-s3-multipart';
+import {
+  isAnswered,
+  multipartEtagOf,
+  type S3Stat,
+  sentObject,
+  settleComplete,
+  settleLostPut,
+} from './driver-s3-settle';
+import type { S3WireOptions } from './driver-s3-signed';
+import { partBytesFor } from './multipart';
+import type { PutStreamOptions } from './put-stream';
+import { streamLimit } from './put-stream';
+
+export interface S3PutStreamInput extends Pick<S3UploadTarget, 'key' | 'refused'> {
+  readonly body: ReadableStream<Uint8Array>;
+  readonly options: PutStreamOptions;
+  readonly maxBytes: number;
+  readonly driver: string;
+  /** The disk's HEAD, asked only when a last request's answer was lost. */
+  readonly stat: S3Stat;
+}
+
+/** The whole body, stored — or nothing stored and the key as it was. */
+export async function putS3Stream(wire: S3WireOptions, input: S3PutStreamInput): Promise<void> {
+  const { key, body, options, maxBytes, driver, refused, stat } = input;
+  const target: S3UploadTarget = { wire, key, refused };
+  const putOptions: PutOptions = options;
+  // Screened before a byte is read: a header that cannot travel fails here, not on the Create.
+  const headers = objectHeaders(putOptions);
+  const partBytes = partBytesFor(maxBytes);
+  let chunks: Uint8Array[] = [];
+  let held = 0;
+  let total = 0;
+  let uploadId: string | undefined;
+  const etags: string[] = [];
+
+  const sendPart = async (): Promise<void> => {
+    uploadId ??= await createS3Upload(target, headers);
+    const part = new Uint8Array(Bun.concatArrayBuffers(chunks));
+    chunks = [];
+    held = 0;
+    etags.push(await uploadS3Part(target, uploadId, etags.length + 1, part));
+  };
+
+  try {
+    await pumpBounded(body, streamLimit(driver, key, maxBytes), async (chunk) => {
+      chunks.push(chunk);
+      held += chunk.byteLength;
+      total += chunk.byteLength;
+      if (held >= partBytes) await sendPart();
+    });
+    if (uploadId === undefined) {
+      const whole = new Uint8Array(Bun.concatArrayBuffers(chunks));
+      const rethrow = (error: unknown): never => {
+        throw error;
+      };
+      const refusal = await signedPut(wire, key, whole, putOptions).catch(
+        settleLostPut(stat, { driver, key, bytes: whole, attributes: options }, rethrow),
+      );
+      if (refusal !== undefined) refused(refusal);
+      return;
+    }
+    if (held > 0) await sendPart();
+    const open = uploadId;
+    await completeS3Upload(
+      target,
+      open,
+      etags.map((etag, at) => ({ partNumber: at + 1, etag })),
+    ).catch(async (lost: unknown) => {
+      if (isAnswered(lost)) throw lost;
+      // Settled here, abort included, so the catch below must not abort a second time.
+      uploadId = undefined;
+      const sent = sentObject(total, multipartEtagOf(etags), options);
+      await settleComplete(stat, { ...target, driver }, open, sent, lost);
+    });
+  } catch (error) {
+    // Parts bill until they are aborted. The refusal the caller reads is the first one, so an abort
+    // that fails too is left to the bucket's lifecycle rule rather than replacing it.
+    if (uploadId !== undefined) await abortS3Upload(target, uploadId).catch(() => undefined);
+    throw error;
+  }
+}

package/src/driver-s3-settle.ts

@@ -0,0 +1,150 @@
+// Single responsibility: what a write whose answer was lost actually did. The last request went out
+// and the socket died, so the provider may have stored the object. Settled by a stat against what
+// was sent, and for a multipart upload by an abort, whose answer says whether it was still open.
+// What neither can settle is `X_STORAGE_WRITE_OUTCOME_UNKNOWN`, never a refusal the disk did not make.
+
+import { isUltimateError, stringField } from '@ultimat3/core';
+import { DEFAULT_CONTENT_TYPE, type PutOptions } from './driver';
+import { abortS3Upload, type S3UploadTarget } from './driver-s3-multipart';
+import { writeOutcomeUnknown } from './errors-stream';
+
+/** The disk's own HEAD: `undefined` for nothing there. A throw is a stat that could not answer. */
+export type S3Stat = (
+  key: string,
+) => Promise<
+  { readonly size: number; readonly etag: string; readonly contentType: string } | undefined
+>;
+
+export interface SentObject {
+  readonly size: number;
+  /** The etag the provider gives exactly these bytes, unquoted; `undefined` when it cannot be known. */
+  readonly etag: string | undefined;
+  readonly contentType: string;
+  /**
+   * The write set something a HEAD does not read back (metadata, cache-control, a lock). Then a
+   * match proves only the bytes, which an overwrite of the same bytes matches already: unknown.
+   */
+  readonly unverifiable: boolean;
+}
+
+/** What a write said about the object, beyond its bytes. */
+export interface SentAttributes
+  extends Pick<PutOptions, 'contentType' | 'cacheControl' | 'metadata'> {
+  readonly retention?: unknown;
+  readonly legalHold?: unknown;
+}
+
+/** `SentObject` for `size` bytes of `etag` under `attributes`. */
+export const sentObject = (
+  size: number,
+  etag: string | undefined,
+  attributes: SentAttributes | undefined,
+): SentObject => ({
+  size,
+  etag,
+  contentType: attributes?.contentType ?? DEFAULT_CONTENT_TYPE,
+  unverifiable:
+    attributes?.metadata !== undefined ||
+    attributes?.cacheControl !== undefined ||
+    attributes?.retention !== undefined ||
+    attributes?.legalHold !== undefined,
+});
+
+const unquoted = (etag: string): string => etag.replace(/^W\//, '').replaceAll('"', '');
+
+const md5Hex = (bytes: Uint8Array): string =>
+  new Bun.CryptoHasher('md5').update(bytes).digest('hex');
+
+/** A single PUT's etag: the body's MD5. A provider encrypting with KMS mints another, so no match. */
+export const putEtagOf = (bytes: Uint8Array): string => md5Hex(bytes);
+
+/**
+ * S3's multipart etag: the MD5 of the parts' binary MD5s, then `-<count>`. Measured equal on the test
+ * stack's gateway. A part etag that is not an MD5 (KMS) makes it unknowable, never a guess.
+ */
+export function multipartEtagOf(partEtags: readonly string[]): string | undefined {
+  const digests: Uint8Array[] = [];
+  for (const etag of partEtags) {
+    const hex = unquoted(etag);
+    if (!/^[0-9a-f]{32}$/i.test(hex)) return undefined;
+    digests.push(Uint8Array.fromHex(hex));
+  }
+  return `${md5Hex(new Uint8Array(Bun.concatArrayBuffers(digests)))}-${partEtags.length}`;
+}
+
+/** `true` when the key holds what was sent, `false` when it holds something else, `undefined` unknown. */
+async function holds(stat: S3Stat, key: string, sent: SentObject): Promise<boolean | undefined> {
+  let found: Awaited<ReturnType<S3Stat>>;
+  try {
+    found = await stat(key);
+  } catch {
+    return undefined;
+  }
+  if (found === undefined) return false;
+  if (sent.etag === undefined || sent.unverifiable) return undefined;
+  return (
+    found.size === sent.size &&
+    unquoted(found.etag) === sent.etag &&
+    found.contentType === sent.contentType
+  );
+}
+
+/**
+ * Whether a failed write is the provider ANSWERING (a refusal, already coded or Bun's `S3Error`) or
+ * the answer lost on the wire, after which the object may be stored.
+ */
+export const isAnswered = (error: unknown): boolean =>
+  isUltimateError(error) || stringField(error, 'name') === 'S3Error';
+
+/**
+ * The `.catch` for a single PUT: a provider answer goes to `refused`, a lost one is settled, so
+ * `put()` resolves when the object landed and is `X_STORAGE_WRITE_OUTCOME_UNKNOWN` when unproven.
+ */
+export const settleLostPut =
+  (
+    stat: S3Stat,
+    input: {
+      readonly driver: string;
+      readonly key: string;
+      readonly bytes: Uint8Array;
+      readonly attributes: SentAttributes | undefined;
+    },
+    refused: (error: unknown) => never,
+  ) =>
+  async (error: unknown): Promise<undefined> => {
+    if (isAnswered(error)) return refused(error);
+    const sent = sentObject(input.bytes.byteLength, putEtagOf(input.bytes), input.attributes);
+    await settlePut(stat, { driver: input.driver, key: input.key, lost: error }, sent);
+    return undefined;
+  };
+
+/** A lost single PUT. It cannot be aborted, so only a match settles it. */
+export async function settlePut(
+  stat: S3Stat,
+  input: { readonly driver: string; readonly key: string; readonly lost: unknown },
+  sent: SentObject,
+): Promise<void> {
+  if ((await holds(stat, input.key, sent)) === true) return;
+  throw writeOutcomeUnknown(input.driver, input.key, input.lost);
+}
+
+/**
+ * A lost Complete. Resolves when the object landed; rethrows `lost` when the abort proves the upload
+ * was still open, so nothing was stored and the caller's refusal is the truth.
+ */
+export async function settleComplete(
+  stat: S3Stat,
+  target: S3UploadTarget & { readonly driver: string },
+  uploadId: string,
+  sent: SentObject,
+  lost: unknown,
+): Promise<void> {
+  if ((await holds(stat, target.key, sent)) === true) return;
+  const refusal = await abortS3Upload(target, uploadId).catch(() => 'unanswered' as const);
+  if (refusal === undefined) throw lost;
+  // NoSuchUpload: nothing is open, so the Complete finished. Whether with these bytes, the key says.
+  if (refusal !== 'unanswered' && refusal.statusCode === 404) {
+    if ((await holds(stat, target.key, sent)) === true) return;
+  }
+  throw writeOutcomeUnknown(target.driver, target.key, lost);
+}

package/src/driver-s3-signed.ts

@@ -9,9 +9,11 @@ import {
   type Clock,
   ConfigInvalidError,
   EnvMissingError,
+  presignAwsUrl,
   signAwsRequest,
   systemClock,
 } from '@ultimat3/core';
+import type { SignedPart } from './signed-url';
 
 /** The slice of `fetch` this file uses; injected in tests so no socket is ever opened. */
 export type S3FetchLike = (
@@ -51,10 +53,12 @@ export interface S3Refusal {
 }
 
 export interface S3SignedRequest {
-  readonly method: 'GET' | 'PUT';
+  readonly method: 'GET' | 'PUT' | 'POST' | 'DELETE';
   readonly key: string;
   /** A sub-resource such as `retention` — sent and signed as `?retention=`. */
   readonly subresource?: string | undefined;
+  /** Query parameters of a multipart call, signed. An empty value is sent as `uploads=`. */
+  readonly query?: Readonly<Record<string, string>> | undefined;
   readonly headers?: Readonly<Record<string, string>> | undefined;
   readonly body?: Uint8Array | undefined;
 }
@@ -122,6 +126,61 @@ export function resolveS3Target(options: S3WireOptions): S3Target {
   };
 }
 
+/**
+ * A PUT URL that signs its `content-length`, which is what `Bun.S3Client.presign` has no option for.
+ * The provider recomputes the signature from the header the browser really sent, so the only body
+ * this URL lands is one of exactly `contentLength` bytes. A browser sets that header itself.
+ */
+export async function presignBoundPut(
+  options: S3WireOptions,
+  key: string,
+  contentLength: number,
+  expiresInSeconds: number,
+  part?: SignedPart | undefined,
+): Promise<string> {
+  const url = s3ObjectUrl(options, key);
+  // A part of an open upload: S3's own UploadPart, its two parameters inside the signature.
+  if (part !== undefined) {
+    url.searchParams.set('partNumber', String(part.partNumber));
+    url.searchParams.set('uploadId', part.uploadId);
+  }
+  const presigned = await presignAwsUrl({
+    method: 'PUT',
+    url,
+    expiresInSeconds,
+    headers: { 'content-length': String(contentLength) },
+    credentials: s3Credentials(options),
+    region: signingRegion(options),
+    service: 's3',
+    clock: options.clock ?? systemClock,
+  });
+  return presigned.url;
+}
+
+/** The labels between `s3.` and `.amazonaws.com` of an AWS host: its region, or none. */
+const AWS_HOST = /(?:^|\.)s3\.(?:(.+)\.)?amazonaws\.com$/i;
+const REGION = /^[a-z0-9-]{1,64}$/;
+
+/**
+ * The region a request is signed for, as `Bun.S3Client` derives it, measured on Bun 1.4.4 so the
+ * disk's two transports sign alike: a region set wins; no endpoint is AWS's `us-east-1`; an AWS host
+ * `s3.<region>.amazonaws.com` is that region, bare `s3.amazonaws.com` is `us-east-1`; any other host
+ * is `auto` (R2, a gateway). One deviation: Bun reads `s3.dualstack.<region>` as the whole
+ * `dualstack.<region>`, which is no region, and this reads the region.
+ */
+export function signingRegion(options: S3WireOptions): string {
+  const { region, endpoint } = resolveS3Target(options);
+  if (region !== undefined) return region;
+  if (endpoint === undefined) return 'us-east-1';
+  const host = URL.canParse(endpoint) ? new URL(endpoint).hostname : '';
+  const match = AWS_HOST.exec(host);
+  if (match === null) return 'auto';
+  const named = match[1];
+  if (named === undefined) return 'us-east-1';
+  const last = named.split('.').at(-1) ?? '';
+  return REGION.test(named) ? named : REGION.test(last) ? last : 'auto';
+}
+
 /** Read lazily, at the first signed request — importing or constructing the disk reads nothing. */
 export function s3Credentials(options: S3WireOptions): AwsCredentials {
   const env = options.env ?? process.env;
@@ -153,7 +212,10 @@ export function s3ObjectUrl(options: S3WireOptions, key: string): URL {
   );
 }
 
-const XML_FIELD = (name: string): RegExp => new RegExp(`<${name}>([^<]{0,512})</${name}>`);
+// Uncapped: a key is up to 1,024 bytes and S3 escapes it (`&` is `&amp;`), so a 512-character
+// cap dropped a long key's session from `listS3Uploads` and ended its paging at a long
+// `NextKeyMarker`. `[^<]*` stops at the next tag, so the match stays linear with no cap.
+const XML_FIELD = (name: string): RegExp => new RegExp(`<${name}>([^<]*)</${name}>`);
 
 /** The first `<name>…</name>` of an S3 XML answer — the shapes read here are flat and fixed. */
 export function xmlField(xml: string, name: string): string | undefined {
@@ -189,6 +251,9 @@ export async function sendSigned(
   }
   const url = s3ObjectUrl(options, request.key);
   if (request.subresource !== undefined) url.search = `${request.subresource}=`;
+  for (const [name, value] of Object.entries(request.query ?? {})) {
+    url.searchParams.set(name, value);
+  }
   const signed = await signAwsRequest({
     method: request.method,
     url,
@@ -197,7 +262,7 @@ export async function sendSigned(
     // refuse a body that changed in flight; a read has none.
     payload: { body: request.body ?? new Uint8Array() },
     credentials: s3Credentials(options),
-    region: resolveS3Target(options).region ?? 'auto',
+    region: signingRegion(options),
     service: 's3',
     clock: options.clock ?? systemClock,
   });

package/src/driver-s3-sse.ts

@@ -0,0 +1,29 @@
+// Single responsibility: the one `put()` option the s3 disk cannot honour, refused by name with the
+// bucket-wide command that does the job instead.
+
+import { NotImplementedError, renderFixLiteral, renderFixShellArg } from '@ultimat3/core';
+import type { PutOptions } from './driver';
+
+/**
+ * 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.
+ */
+export function refuseUnsupportedPut(bucket: string, putOptions?: PutOptions): void {
+  const sse = putOptions?.serverSideEncryption;
+  if (sse === undefined) return;
+  // 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:
+      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}]}'`,
+  });
+}