@ultimat3/storage 24.0.0 → 25.0.0

package/src/driver-s3-lock.ts

@@ -0,0 +1,131 @@
+// Single responsibility: the two s3 calls `Bun.S3Client` cannot make — a PUT carrying user
+// metadata, `Cache-Control` and Object Lock headers, and the `?retention` / `?legal-hold` reads
+// behind `retentionOf` — over the signed wire in `driver-s3-signed.ts`, answered in this package's
+// vocabulary. A plain `put()` never comes here: it stays on the Bun client.
+
+import { assert, describeValue } from '@ultimat3/core';
+import { DEFAULT_CONTENT_TYPE, type PutOptions } from './driver';
+import { type S3Refusal, type S3WireOptions, sendSigned, xmlField } from './driver-s3-signed';
+import { isRetentionMode, type ObjectLock } from './object-lock';
+
+/** RFC 9110 `token` — the only bytes an `x-amz-meta-<name>` header name may carry. */
+const HEADER_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** Printable ASCII: S3 stores a metadata value as a header, and a CR or a non-ASCII byte is not one. */
+const HEADER_VALUE = /^[\x20-\x7e]*$/;
+
+/** The options only the signed PUT can carry. Any one of them routes the put off the Bun client. */
+export function needsSignedPut(options: PutOptions | undefined): boolean {
+  return (
+    options?.metadata !== undefined ||
+    options?.cacheControl !== undefined ||
+    options?.retention !== undefined ||
+    options?.legalHold !== undefined
+  );
+}
+
+/** Every header the signed PUT sends beyond the signer's own, screened before a byte moves. */
+export function putHeaders(bytes: Uint8Array, options: PutOptions): Record<string, string> {
+  const headers: Record<string, string> = {
+    'content-type': options.contentType ?? DEFAULT_CONTENT_TYPE,
+    // Required by S3 on any PUT that sets a retention, and an integrity check on every other one:
+    // a body that changed in flight is `BadDigest`, never a stored object.
+    'content-md5': new Bun.CryptoHasher('md5').update(bytes).digest('base64'),
+  };
+  if (options.cacheControl !== undefined) {
+    assert(
+      HEADER_VALUE.test(options.cacheControl),
+      `put() on the s3 disk was given a cacheControl that cannot travel as a header (${describeValue(options.cacheControl)})`,
+      "put(key, body, { cacheControl: 'public, max-age=3600' }) — printable ASCII, no line breaks",
+    );
+    headers['cache-control'] = options.cacheControl;
+  }
+  for (const [name, value] of Object.entries(options.metadata ?? {})) {
+    assert(
+      HEADER_TOKEN.test(name) && HEADER_VALUE.test(value),
+      `put() on the s3 disk was given metadata that cannot travel as an x-amz-meta-* header (name ${describeValue(name)}, value ${describeValue(value)})`,
+      'name each field with letters, digits and hyphens, and keep values printable ASCII — encodeURIComponent(value) anything else',
+    );
+    headers[`x-amz-meta-${name.toLowerCase()}`] = value;
+  }
+  if (options.retention !== undefined) {
+    headers['x-amz-object-lock-mode'] = options.retention.mode;
+    headers['x-amz-object-lock-retain-until-date'] = options.retention.retainUntil.toISOString();
+  }
+  if (options.legalHold !== undefined) {
+    headers['x-amz-object-lock-legal-hold'] = options.legalHold ? 'ON' : 'OFF';
+  }
+  return headers;
+}
+
+/** The signed PUT. `undefined` on success; the provider's refusal otherwise, for the driver to code. */
+export async function signedPut(
+  wire: S3WireOptions,
+  key: string,
+  bytes: Uint8Array,
+  options: PutOptions,
+): Promise<S3Refusal | undefined> {
+  const headers = putHeaders(bytes, options);
+  const result = await sendSigned(wire, { method: 'PUT', key, headers, body: bytes });
+  return result.ok ? undefined : result.refusal;
+}
+
+/**
+ * "Nothing locks this", as the provider says it: no configuration on the object, or a bucket made
+ * without Object Lock at all. Asked BEFORE the absent-object test, because the first answers 404.
+ */
+function isUnlockedAnswer(refusal: S3Refusal): boolean {
+  if (refusal.code === 'NoSuchObjectLockConfiguration') return true;
+  if (refusal.code === 'ObjectLockConfigurationNotFoundError') return true;
+  return refusal.code === 'InvalidRequest' && /object lock/i.test(refusal.message);
+}
+
+export type LockRead =
+  | { readonly kind: 'lock'; readonly lock: ObjectLock }
+  | { readonly kind: 'refused'; readonly refusal: S3Refusal };
+
+async function readSubresource(
+  wire: S3WireOptions,
+  key: string,
+  subresource: 'retention' | 'legal-hold',
+): Promise<{ readonly xml: string } | { readonly unlocked: true } | S3Refusal> {
+  const result = await sendSigned(wire, { method: 'GET', key, subresource });
+  if (result.ok) return { xml: await result.response.text() };
+  return isUnlockedAnswer(result.refusal) ? { unlocked: true } : result.refusal;
+}
+
+const unreadable = (key: string, what: string): S3Refusal => ({
+  name: 'S3Error',
+  code: 'UnreadableAnswer',
+  message: `the provider's ${what} for "${key}" did not parse`,
+  statusCode: 200,
+});
+
+/**
+ * Both halves of the lock, read in parallel. A refusal of either is the answer — a caller that
+ * asked "may I delete this?" must not hear "nothing locks it" because one read was denied.
+ */
+export async function readObjectLock(wire: S3WireOptions, key: string): Promise<LockRead> {
+  const [retention, hold] = await Promise.all([
+    readSubresource(wire, key, 'retention'),
+    readSubresource(wire, key, 'legal-hold'),
+  ]);
+  if ('code' in retention) return { kind: 'refused', refusal: retention };
+  if ('code' in hold) return { kind: 'refused', refusal: hold };
+  let lock: ObjectLock = { legalHold: false };
+  if ('xml' in retention) {
+    const mode = xmlField(retention.xml, 'Mode');
+    const until = new Date(xmlField(retention.xml, 'RetainUntilDate') ?? '');
+    if (!isRetentionMode(mode) || !Number.isFinite(until.getTime())) {
+      return { kind: 'refused', refusal: unreadable(key, 'retention') };
+    }
+    lock = { retention: { mode, retainUntil: until }, legalHold: false };
+  }
+  if ('xml' in hold) {
+    const status = xmlField(hold.xml, 'Status');
+    if (status !== 'ON' && status !== 'OFF') {
+      return { kind: 'refused', refusal: unreadable(key, 'legal hold') };
+    }
+    lock = { ...lock, legalHold: status === 'ON' };
+  }
+  return { kind: 'lock', lock };
+}

package/src/driver-s3-signed.ts

@@ -0,0 +1,220 @@
+// Single responsibility: the s3 disk's SIGNED requests — the ones `Bun.S3Client` has no option for
+// (`x-amz-meta-*`, `Cache-Control`, `x-amz-object-lock-*`, `?retention`, `?legal-hold`) — built,
+// signed through core's one SigV4 signer and sent with `fetch`. The endpoint, the addressing style,
+// the region and the credentials are read from the SAME `S3DriverOptions` the Bun client is built
+// from, so the two transports of one disk cannot point at two buckets.
+
+import {
+  type AwsCredentials,
+  type Clock,
+  ConfigInvalidError,
+  EnvMissingError,
+  signAwsRequest,
+  systemClock,
+} from '@ultimat3/core';
+
+/** The slice of `fetch` this file uses; injected in tests so no socket is ever opened. */
+export type S3FetchLike = (
+  url: string,
+  init: {
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: Uint8Array<ArrayBuffer> | undefined;
+  },
+) => Promise<Response>;
+
+/** Structurally `S3DriverOptions`, so the driver passes its own options through unchanged. */
+export interface S3WireOptions {
+  readonly bucket: string;
+  readonly region?: string | undefined;
+  readonly endpoint?: string | undefined;
+  readonly forcePathStyle?: boolean | undefined;
+  readonly accessKeyIdEnv?: string | undefined;
+  readonly secretAccessKeyEnv?: string | undefined;
+  readonly sessionTokenEnv?: string | undefined;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly fetch?: S3FetchLike | undefined;
+  readonly clock?: Clock | undefined;
+}
+
+/**
+ * What a provider's refusal is read as — the `code`/`message`/`statusCode` triple `Bun.S3Client`'s
+ * `S3Error` carries, so `regionMismatch` and `isAbsentObject` classify a signed request's failure
+ * exactly as they classify the Bun client's. A plain object: it is never thrown bare, only handed
+ * to a coded factory.
+ */
+export interface S3Refusal {
+  readonly name: 'S3Error';
+  readonly code: string;
+  readonly message: string;
+  readonly statusCode: number;
+}
+
+export interface S3SignedRequest {
+  readonly method: 'GET' | 'PUT';
+  readonly key: string;
+  /** A sub-resource such as `retention` — sent and signed as `?retention=`. */
+  readonly subresource?: string | undefined;
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  readonly body?: Uint8Array | undefined;
+}
+
+export type S3SignedResult =
+  | { readonly ok: true; readonly response: Response }
+  | { readonly ok: false; readonly refusal: S3Refusal };
+
+/** One credential reader for both transports: an unset or empty variable is `X_ENV_MISSING`. */
+export 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;
+}
+
+/** Where a disk's requests go, and as whom beyond the key pair — resolved ONCE for both transports. */
+export interface S3Target {
+  readonly endpoint?: string | undefined;
+  readonly region?: string | undefined;
+  readonly sessionToken?: string | undefined;
+}
+
+/** The first of `names` set to something other than `''` — Bun's reading of an unset variable. */
+const firstSet = (
+  env: Readonly<Record<string, string | undefined>>,
+  names: readonly string[],
+): string | undefined => {
+  for (const name of names) {
+    const value = env[name];
+    if (value !== undefined && value !== '') return value;
+  }
+  return undefined;
+};
+
+/**
+ * Bun's own defaults, restated so the signed path cannot target another place: an option wins,
+ * then `S3_*`, then `AWS_*` — `S3_ENDPOINT`/`AWS_ENDPOINT`, `S3_REGION`/`AWS_REGION`,
+ * `S3_SESSION_TOKEN`/`AWS_SESSION_TOKEN` (measured on Bun 1.4.2, and its `S3Options` docs). Read
+ * from `options.env ?? process.env`, and `buildClient` hands the result to Bun explicitly, so an
+ * injected table governs both transports. A `sessionTokenEnv` names the one variable to read.
+ */
+export function resolveS3Target(options: S3WireOptions): S3Target {
+  const env = options.env ?? process.env;
+  const tokenVar = options.sessionTokenEnv;
+  const endpoint = options.endpoint ?? firstSet(env, ['S3_ENDPOINT', 'AWS_ENDPOINT']);
+  const region = options.region ?? firstSet(env, ['S3_REGION', 'AWS_REGION']);
+  const sessionToken =
+    tokenVar === undefined
+      ? firstSet(env, ['S3_SESSION_TOKEN', 'AWS_SESSION_TOKEN'])
+      : firstSet(env, [tokenVar]);
+  return {
+    ...(endpoint === undefined ? {} : { endpoint }),
+    ...(region === undefined ? {} : { region }),
+    ...(sessionToken === undefined ? {} : { sessionToken }),
+  };
+}
+
+/** 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;
+  const idVar = options.accessKeyIdEnv ?? 'S3_ACCESS_KEY_ID';
+  const secretVar = options.secretAccessKeyEnv ?? 'S3_SECRET_ACCESS_KEY';
+  const { sessionToken } = resolveS3Target(options);
+  return {
+    accessKeyId: requireEnv(env, idVar, secretVar),
+    secretAccessKey: requireEnv(env, secretVar, idVar),
+    ...(sessionToken === undefined || sessionToken === '' ? {} : { sessionToken }),
+  };
+}
+
+/**
+ * Bun's addressing, restated: path style unless `forcePathStyle` is EXPLICITLY false (Bun's own
+ * `virtualHostedStyle` defaults to false), and AWS's regional endpoint when none is configured.
+ */
+export function s3ObjectUrl(options: S3WireOptions, key: string): URL {
+  const target = resolveS3Target(options);
+  const endpoint = target.endpoint ?? `https://s3.${target.region ?? 'us-east-1'}.amazonaws.com`;
+  const base = new URL(endpoint);
+  const path = key.split('/').map(encodeURIComponent).join('/');
+  if (options.forcePathStyle === false) {
+    return new URL(`${base.protocol}//${options.bucket}.${base.host}/${path}`);
+  }
+  const prefix = base.pathname.replace(/\/+$/, '');
+  return new URL(
+    `${base.protocol}//${base.host}${prefix}/${encodeURIComponent(options.bucket)}/${path}`,
+  );
+}
+
+const XML_FIELD = (name: string): RegExp => new RegExp(`<${name}>([^<]{0,512})</${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 {
+  return XML_FIELD(name).exec(xml)?.[1]?.trim();
+}
+
+/** A non-2xx answer as the refusal it is. A HEAD-style empty body still has its status. */
+async function refusalOf(response: Response): Promise<S3Refusal> {
+  const body = await response.text().catch(() => '');
+  return {
+    name: 'S3Error',
+    code: xmlField(body, 'Code') ?? `HTTP${response.status}`,
+    message: xmlField(body, 'Message') ?? response.statusText,
+    statusCode: response.status,
+  };
+}
+
+/**
+ * Sign and send one request. Resolves with the response or the provider's refusal — never throws
+ * for an answer the provider gave, so each caller decides what a refusal means for ITS call. A
+ * request with no answer at all (DNS, reset) rejects with whatever `fetch` raised.
+ */
+export async function sendSigned(
+  options: S3WireOptions,
+  request: S3SignedRequest,
+): Promise<S3SignedResult> {
+  // The Bun client's own refusal, for the transport beside it: one disk, one rule.
+  if (options.bucket === '') {
+    throw new ConfigInvalidError({
+      cause: 's3 disk was defined without a bucket',
+      fix: "s3Driver({ bucket: 'my-bucket' })   # storage.disks.<name> in app.config.ts",
+    });
+  }
+  const url = s3ObjectUrl(options, request.key);
+  if (request.subresource !== undefined) url.search = `${request.subresource}=`;
+  const signed = await signAwsRequest({
+    method: request.method,
+    url,
+    headers: request.headers ?? {},
+    // The body is in memory and bounded by `maxPutBytes`, so it is hashed and the provider can
+    // 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',
+    service: 's3',
+    clock: options.clock ?? systemClock,
+  });
+  const send = options.fetch ?? fetch;
+  const body = request.body;
+  const response = await send(signed.url, {
+    method: signed.method,
+    headers: signed.headers,
+    // `fetch` takes an ArrayBuffer-backed view; only a view over shared memory is copied.
+    ...(body === undefined
+      ? {}
+      : {
+          body:
+            body.buffer instanceof ArrayBuffer
+              ? new Uint8Array(body.buffer, body.byteOffset, body.byteLength)
+              : new Uint8Array(body),
+        }),
+  });
+  return response.ok ? { ok: true, response } : { ok: false, refusal: await refusalOf(response) };
+}