@ultimat3/storage 24.0.0 → 25.0.0

package/src/object-lock.ts

@@ -0,0 +1,173 @@
+// Single responsibility: S3 Object Lock as this package's vocabulary — a per-object retention (a
+// mode and an instant) and a legal hold, the screen `put()` holds them to, the one "is it locked
+// now?" rule, and the refusals the disks that EMULATE a lock (local, memory) answer with.
+
+import {
+  assert,
+  type Clock,
+  describeValue,
+  renderFixLiteral,
+  renderFixShellArg,
+} from '@ultimat3/core';
+import { StorageError } from './errors';
+
+/** `GOVERNANCE` yields to `s3:BypassGovernanceRetention`; `COMPLIANCE` yields to nobody, root included. */
+export const RETENTION_MODES = ['GOVERNANCE', 'COMPLIANCE'] as const;
+export type RetentionMode = (typeof RETENTION_MODES)[number];
+
+export interface ObjectRetention {
+  readonly mode: RetentionMode;
+  /** The instant the lock lapses. UTC-backed; sent as an ISO-8601 instant. */
+  readonly retainUntil: Date;
+}
+
+/** What locks one object, as the disk reports it. Neither field set means nothing locks it. */
+export interface ObjectLock {
+  readonly retention?: ObjectRetention | undefined;
+  readonly legalHold: boolean;
+}
+
+/** The lock half of `PutOptions`, screened here so all three disks refuse one way. */
+export interface ObjectLockOptions {
+  readonly retention?: ObjectRetention | undefined;
+  readonly legalHold?: boolean | undefined;
+}
+
+export const isRetentionMode = (value: unknown): value is RetentionMode =>
+  (RETENTION_MODES as readonly unknown[]).includes(value);
+
+/**
+ * A retention whose mode is not one of the two, whose instant is not one, or whose instant has
+ * already passed — refused before a byte moves. S3 itself answers a past date with a 400; the
+ * local disk would store a lock that never held, which reads to a caller as "this is retained".
+ */
+export function assertObjectLockOptions(
+  driver: string,
+  options: ObjectLockOptions | undefined,
+  clock: Clock,
+): void {
+  const retention = options?.retention;
+  if (retention !== undefined) {
+    assert(
+      isRetentionMode(retention.mode),
+      `put() on the ${driver} disk was given a retention mode that is neither GOVERNANCE nor COMPLIANCE (${describeValue(retention.mode)})`,
+      "put(key, body, { retention: { mode: 'GOVERNANCE', retainUntil } })",
+    );
+    const until = retention.retainUntil;
+    assert(
+      until instanceof Date && Number.isFinite(until.getTime()),
+      `put() on the ${driver} disk was given a retainUntil that is not a valid Date (${describeValue(until)})`,
+      'put(key, body, { retention: { mode, retainUntil: new Date(clock.now().getTime() + days * 86_400_000) } })',
+    );
+    assert(
+      until.getTime() > clock.now().getTime(),
+      `put() on the ${driver} disk was given a retainUntil of ${until.toISOString()}, which is not in the future: a lock that has already lapsed retains nothing`,
+      'pass a retainUntil after now — new Date(clock.now().getTime() + days * 86_400_000)',
+    );
+  }
+  assert(
+    options?.legalHold === undefined || typeof options.legalHold === 'boolean',
+    `put() on the ${driver} disk was given a legalHold that is not a boolean (${describeValue(options?.legalHold)})`,
+    'put(key, body, { legalHold: true }) — or omit legalHold',
+  );
+}
+
+/** The lock `put()` was asked to set, in the shape a disk stores — `undefined` when none was. */
+export function requestedLock(options: ObjectLockOptions | undefined): ObjectLock | undefined {
+  if (options?.retention === undefined && options?.legalHold !== true) return undefined;
+  return {
+    ...(options.retention === undefined
+      ? {}
+      : {
+          retention: {
+            mode: options.retention.mode,
+            retainUntil: new Date(options.retention.retainUntil.getTime()),
+          },
+        }),
+    legalHold: options.legalHold === true,
+  };
+}
+
+/** Locked NOW: a legal hold, or a retention whose instant is still ahead. One rule, every disk. */
+export function isLocked(lock: ObjectLock | undefined, now: Date): boolean {
+  if (lock === undefined) return false;
+  if (lock.legalHold) return true;
+  return lock.retention !== undefined && lock.retention.retainUntil.getTime() > now.getTime();
+}
+
+function describeLock(lock: ObjectLock): string {
+  const parts: string[] = [];
+  if (lock.retention !== undefined) {
+    parts.push(
+      `${lock.retention.mode} retention until ${lock.retention.retainUntil.toISOString()}`,
+    );
+  }
+  if (lock.legalHold) parts.push('a legal hold');
+  return parts.join(' and ');
+}
+
+export type LockedAction = 'delete' | 'overwrite' | 'copy onto';
+
+/**
+ * The fix opens with the read that shows the lock, then where the bytes can go instead. An
+ * overwrite or a copy has another key to write to; a delete only has "later".
+ */
+function lockFix(
+  action: LockedAction,
+  disk: string,
+  key: string,
+  lock: ObjectLock,
+  sidecar: string | undefined,
+): string {
+  const show = `disk('${disk}').retentionOf(${renderFixLiteral(key, '"<key>"')}) # shows the lock`;
+  const elsewhere =
+    action === 'delete'
+      ? ''
+      : `; or write under a new key: disk('${disk}').put(${renderFixLiteral(`${key}.v2`, '"<a new key>"')}, body)`;
+  if (lock.legalHold) {
+    return sidecar === undefined
+      ? `${show}; a hold on the memory disk lasts as long as the process${elsewhere}`
+      : `${show}; release the hold by setting "legalHold": false in ${renderFixShellArg(sidecar, "'<the sidecar file>'")}${elsewhere}`;
+  }
+  const until = lock.retention?.retainUntil.toISOString() ?? 'the retention lapses';
+  return `${show}; retry after ${until}${elsewhere}`;
+}
+
+/**
+ * `X_STORAGE_OBJECT_LOCKED` — a delete, overwrite or copy onto a locked key, refused by a disk that
+ * EMULATES Object Lock (local, memory). Those disks keep ONE version per key, so refusing is the
+ * only way to keep the locked bytes; S3 keeps the locked VERSION and lets the call through (a
+ * delete marker, a newer version) — `driver-parity.test.ts` pins that divergence.
+ */
+export class ObjectLockedError extends StorageError {
+  readonly lock: ObjectLock;
+
+  constructor(input: {
+    readonly disk: string;
+    readonly key: string;
+    readonly action: LockedAction;
+    readonly lock: ObjectLock;
+    /** The local disk's sidecar path, where a legal hold is released; absent on memory. */
+    readonly sidecar?: string | undefined;
+  }) {
+    const { disk, key, action, lock, sidecar } = input;
+    super({
+      code: 'X_STORAGE_OBJECT_LOCKED',
+      cause: `disk "${disk}" refused to ${action} "${key}": it is under ${describeLock(lock)}; the stored bytes are unchanged`,
+      fix: lockFix(action, disk, key, lock, sidecar),
+      meta: {
+        disk,
+        key,
+        action,
+        legalHold: lock.legalHold,
+        ...(lock.retention === undefined
+          ? {}
+          : {
+              mode: lock.retention.mode,
+              retainUntil: lock.retention.retainUntil.toISOString(),
+            }),
+      },
+    });
+    this.lock = lock;
+  }
+}

package/src/signed-url.ts

@@ -8,10 +8,6 @@ import { type Clock, finiteCount, systemClock, timingSafeEqual } from '@ultimat3
 import type { SignedUrlMethod } from './driver';
 import { assertSafeKey, isSafeKey } from './path';
 
-/** Re-exported so every existing `from '@ultimat3/storage'` import keeps working — the
- * implementation now lives in `@ultimat3/core`, shared with `@ultimat3/auth`. */
-export { timingSafeEqual };
-
 /** `v2` since the canonical string carries the base path: a `v1` signature names no disk. */
 export const SIGNED_URL_VERSION = 'v2';
 export const DEFAULT_SIGNED_URL_TTL_MS = 900_000;

package/src/signing-secret.ts

@@ -1,8 +1,12 @@
 // Single responsibility: the secret a disk that mints its OWN URLs signs with — the published
 // development fallback, the env key production must set, and the one rule (`localDriver` and
-// `memoryDriver` both) for refusing the fallback outside a development or test environment.
+// `memoryStorageDriver` both) for refusing the fallback outside a development or test environment.
 
-import { isLocal, type ResolveEnvironmentOptions, resolveEnvironment } from '@ultimat3/core';
+import {
+  devSecretsRefused,
+  type ResolveEnvironmentOptions,
+  resolveEnvironment,
+} from '@ultimat3/core';
 import { signingSecretMissing } from './errors';
 
 /**
@@ -43,7 +47,7 @@ export interface SigningSecretOptions {
 }
 
 /**
- * The secret a disk that mints its OWN URLs signs with — `localDriver` and `memoryDriver` both.
+ * The secret a disk that mints its OWN URLs signs with — `localDriver` and `memoryStorageDriver` both.
  *
  * A dev disk must work with zero config. Outside development the fallback is refused rather than
  * used: the literal is published, so signing with it hands every reader the power to mint a PUT
@@ -62,10 +66,11 @@ export function resolveSigningSecret(disk: string, options: SigningSecretOptions
     supplied === undefined || supplied === '' || supplied === DEV_SIGNING_SECRET
       ? undefined
       : supplied;
-  // FAILS CLOSED: a process that names no environment resolves as `production` here, the answer
-  // core's `assertNoDevSecretsOutsideLocal` gives. `isLocal`'s own fallback is `development`, so the
-  // process that forgot to say signed with the published key — exactly the one that must not.
-  if (configured === undefined && !isLocal({ env, fallback: 'production' }))
+  // FAILS CLOSED, through core's one rule (`devSecretsRefused`): a process that names no
+  // environment resolves as `production` here, the answer `assertNoDevSecretsOutsideLocal` gives.
+  // `isLocal`'s own fallback is `development`, so the process that forgot to say signed with the
+  // published key — exactly the one that must not.
+  if (configured === undefined && devSecretsRefused({ env }))
     throw signingSecretMissing(resolveEnvironment({ env, fallback: 'production' }), disk);
   return configured ?? DEV_SIGNING_SECRET;
 }

package/src/upload.ts

@@ -15,6 +15,7 @@ import {
   contentTypeNotAllowed,
   contentTypeUnrecognised,
   tooLarge,
+  xmlBodyUnreadable,
 } from './errors';
 import { HEIF_CONTAINER, ISO_BMFF_CONTAINER, ISO_BMFF_TYPES, sniffIsoBmff } from './iso-bmff';
 import { assertSafeKey } from './path';
@@ -151,9 +152,49 @@ function sniffText(bytes: Uint8Array): string | undefined {
   if (head.startsWith('<svg') || (head.startsWith('<?xml') && head.includes('<svg'))) {
     return 'image/svg+xml';
   }
+  if (head.startsWith('<')) return activeMarkupType(text) ?? 'text/plain';
   return 'text/plain';
 }
 
+/**
+ * `&#58;` and `&#x3a;` are `:` to an XML parser, so they are `:` to the scan below too. The digit
+ * run is UNBOUNDED because XML puts no cap on leading zeros (`&#x000000003a;` is `:`); the range is
+ * checked on the value instead, and a reference past U+10FFFF stays as written, as it is not a
+ * character a parser would produce.
+ */
+const decodeCharacterReferences = (text: string): string =>
+  text.replace(/&#(x[0-9a-f]+|[0-9]+);/gi, (whole, ref: string) => {
+    const hex = ref[0] === 'x' || ref[0] === 'X';
+    const digits = (hex ? ref.slice(1) : ref).replace(/^0+(?=.)/, '');
+    if (digits.length > (hex ? 6 : 7)) return whole;
+    const code = Number.parseInt(digits, hex ? 16 : 10);
+    return code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+  });
+
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+/** XHTML elements and XSLT output are pages; a DTD's entities can assemble either out of parts. */
+const PAGE_MARKERS = [
+  'http://www.w3.org/1999/xhtml',
+  'http://www.w3.org/1999/xsl/transform',
+  '<?xml-stylesheet',
+  '<!entity',
+] as const;
+
+/**
+ * Whether markup that looked like plain text is a document a browser RUNS — asked of the WHOLE
+ * body, never its head, because XML puts no rule on where a namespace is declared. Under
+ * `application/xml` a browser executes an XHTML-namespaced `<script>` anywhere in the tree, an
+ * SVG-namespaced element likewise, and an `<?xml-stylesheet?>` makes the document whatever HTML
+ * its XSLT emits. An internal `<!ENTITY>` subset is refused with them: an entity expands inside
+ * an attribute value, so it can build a namespace out of two halves no substring scan can see.
+ * A data document — a namespace of its own, no DTD, no stylesheet — stays plain text.
+ */
+function activeMarkupType(text: string): 'text/html' | 'image/svg+xml' | undefined {
+  const scanned = decodeCharacterReferences(text).toLowerCase();
+  if (PAGE_MARKERS.some((marker) => scanned.includes(marker))) return 'text/html';
+  return scanned.includes(SVG_NAMESPACE) ? 'image/svg+xml' : undefined;
+}
+
 /** `undefined` means "no rule recognised it", never "it is fine". */
 export function sniffContentType(bytes: Uint8Array): string | undefined {
   for (const rule of MAGIC_RULES) {
@@ -228,6 +269,10 @@ function hasSignature(declared: string): boolean {
   );
 }
 
+/** `application/xml`, `text/xml` and every `+xml` suffix type (RFC 6839): what a browser parses as XML. */
+const isXmlType = (type: string): boolean =>
+  type === 'application/xml' || type === 'text/xml' || type.endsWith('+xml');
+
 /**
  * Throws the first violated constraint, in this order: key, size, type, checksum. The key comes
  * before the size because a key nothing may store makes the other three moot, and which
@@ -251,7 +296,13 @@ export function validateUpload(
     // says so and this branch read it the other way, so any body the sniffer bailed on (one
     // control byte, one non-UTF-8 sequence) skipped the guard entirely. Measured: an HTML
     // document with a trailing `0x01` was accepted as `image/png`.
+    //
+    // An XML type is refused the same way, though no signature names it: a browser decodes XML by
+    // its BOM or `encoding=` declaration (UTF-16, a legacy charset) and runs the XHTML or SVG it
+    // finds, so a body the sniffer could not read as UTF-8 text is one whose script it never saw.
+    // Plain text types (`text/csv`) stay accepted: a Latin-1 CSV is real, and nothing executes it.
     if (hasSignature(declared)) throw contentTypeUnrecognised(key, declared);
+    if (isXmlType(declared)) throw xmlBodyUnreadable(key, declared);
   } else if (!contentTypeMatches(declared, sniffed)) {
     throw contentTypeMismatch(key, declared, sniffed);
   }