@ultimat3/storage 23.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/path.ts

@@ -42,6 +42,9 @@ function hasControlByte(key: string): boolean {
 }
 
 function unsafeReason(key: string): string | undefined {
+  // The type says string; a key off an untyped caller is whatever it is, and `.length` on
+  // `undefined` was a bare `TypeError` out of every driver method at once.
+  if (typeof key !== 'string') return 'is not a string';
   if (key.length === 0) return 'is empty';
   const bytes = utf8Bytes(key);
   if (bytes > MAX_KEY_LENGTH) {
@@ -110,9 +113,21 @@ export function scopedKey(orgId: string, ...parts: readonly string[]): string {
   return joinKey(ORG_PREFIX, assertOrgId(orgId), ...parts);
 }
 
-/** Guard for read paths: a key handed in by a client must still belong to the actor's org. */
+/**
+ * Guard for read paths: a key handed in by a client must still belong to the actor's org.
+ *
+ * A PREDICATE, so it answers and never throws. An org id that cannot be one — empty, or carrying
+ * a separator — has no keys inside it, and that is `false`: it used to raise
+ * `X_STORAGE_PATH_UNSAFE` through `orgPrefix`, blaming the KEY for an actor with no org, and every
+ * caller that knew wrote `orgId === '' ||` in front of it while the ones that did not threw.
+ */
 export function isWithinOrg(key: string, orgId: string): boolean {
-  return isSafeKey(key) && key.startsWith(orgPrefix(orgId));
+  // `typeof`, because the caller is a guard on a request: an actor whose org claim is `undefined`
+  // at runtime must read as "inside no org", not as a `TypeError` out of `.includes`.
+  if (typeof key !== 'string' || typeof orgId !== 'string') return false;
+  const prefix = `${ORG_PREFIX}/${orgId}`;
+  if (orgId.includes('/') || !isSafeKey(prefix)) return false;
+  return isSafeKey(key) && key.startsWith(`${prefix}/`);
 }
 
 /**

package/src/signed-url.ts

@@ -8,11 +8,8 @@ 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 };
-
-export const SIGNED_URL_VERSION = 'v1';
+/** `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;
 /** The dev server mounts the download/upload route here; S3 disks never use it. */
 export const DEFAULT_SIGNED_URL_BASE = '/_storage';
@@ -70,10 +67,34 @@ export type SignedUrlVerification =
   | { readonly ok: true; readonly constraints: SignedUrlConstraints }
   | { readonly ok: false; readonly reason: SignedUrlFailure; readonly detail: string };
 
-/** Newline-separated and order-fixed: an ambiguous canonical form is a forgeable one. */
-export function canonicalRequest(constraints: SignedUrlConstraints): string {
+const trimBase = (base: string): string => base.replace(/\/+$/, '');
+
+/**
+ * The PATH a base mounts at — what a route sees, and so the only part of a base both halves can
+ * agree on. An absolute `baseUrl` (`https://cdn.example.com/_storage/local`) names an origin too,
+ * and the verifier compared a request's pathname against the whole string: every URL minted under
+ * one was `malformed`. Never throws — a base `URL` cannot parse is compared as written.
+ */
+export function signedUrlBasePath(baseUrl: string): string {
+  try {
+    return trimBase(new URL(baseUrl, 'http://storage.invalid').pathname);
+  } catch {
+    return trimBase(baseUrl);
+  }
+}
+
+/**
+ * Newline-separated and order-fixed: an ambiguous canonical form is a forgeable one.
+ *
+ * `basePath` is the disk: `/_storage/<registered name>`. Every local disk signs with the one
+ * `STORAGE_SIGNING_SECRET`, so without it a URL for `uploads/<key>` verified on `private/<key>`
+ * with only the path segment edited — a grant for one disk was a grant for all of them. The
+ * origin is deliberately outside it: the verifying route is handed a path.
+ */
+export function canonicalRequest(constraints: SignedUrlConstraints, basePath: string): string {
   return [
     SIGNED_URL_VERSION,
+    basePath,
     constraints.method,
     constraints.key,
     String(constraints.expiresAt),
@@ -87,6 +108,7 @@ const encoder = new TextEncoder();
 export async function signConstraints(
   secret: string,
   constraints: SignedUrlConstraints,
+  basePath: string,
 ): Promise<string> {
   const key = await crypto.subtle.importKey(
     'raw',
@@ -95,11 +117,14 @@ export async function signConstraints(
     false,
     ['sign'],
   );
-  const mac = await crypto.subtle.sign('HMAC', key, encoder.encode(canonicalRequest(constraints)));
+  const mac = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    encoder.encode(canonicalRequest(constraints, basePath)),
+  );
   return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
 }
 
-const trimBase = (base: string): string => base.replace(/\/+$/, '');
 const encodeKey = (key: string): string => key.split('/').map(encodeURIComponent).join('/');
 
 /**
@@ -148,8 +173,11 @@ export async function buildSignedUrl(input: SignedUrlInput): Promise<string> {
   if (constraints.contentType !== undefined) {
     params.set(SIGNED_URL_PARAMS.contentType, constraints.contentType);
   }
-  params.set(SIGNED_URL_PARAMS.signature, await signConstraints(input.secret, constraints));
   const base = trimBase(input.baseUrl ?? DEFAULT_SIGNED_URL_BASE);
+  params.set(
+    SIGNED_URL_PARAMS.signature,
+    await signConstraints(input.secret, constraints, signedUrlBasePath(base)),
+  );
   return `${base}/${encodeKey(key)}?${params.toString()}`;
 }
 
@@ -222,10 +250,11 @@ export async function verifySignedUrl(input: VerifySignedUrlInput): Promise<Sign
   }
   const signature = url.searchParams.get(SIGNED_URL_PARAMS.signature);
   if (signature === null) return fail('malformed', `no ${SIGNED_URL_PARAMS.signature} parameter`);
-  const parsed = parseConstraints(url, trimBase(input.baseUrl ?? DEFAULT_SIGNED_URL_BASE));
+  const basePath = signedUrlBasePath(input.baseUrl ?? DEFAULT_SIGNED_URL_BASE);
+  const parsed = parseConstraints(url, basePath);
   if (typeof parsed === 'string') return fail(parsed, `${url.pathname} is not a signable request`);
 
-  const expected = await signConstraints(input.secret, parsed);
+  const expected = await signConstraints(input.secret, parsed, basePath);
   if (!timingSafeEqual(expected, signature)) {
     return fail('signature-mismatch', 'the constraints do not match the signature');
   }

package/src/signing-secret.ts

@@ -0,0 +1,76 @@
+// 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
+// `memoryStorageDriver` both) for refusing the fallback outside a development or test environment.
+
+import {
+  devSecretsRefused,
+  type ResolveEnvironmentOptions,
+  resolveEnvironment,
+} from '@ultimat3/core';
+import { signingSecretMissing } from './errors';
+
+/**
+ * The dev-only fallback signing key. A literal, not a per-process random one, so a restart does
+ * not invalidate every URL `x dev` handed out — and published in this repo, which is exactly why
+ * `localDriver` refuses to use it outside a development or test environment.
+ */
+export const DEV_SIGNING_SECRET = 'ultimate-dev-signing-secret';
+
+/** The env key production must set. Named once, read by the driver and by the predicate below. */
+export const STORAGE_SIGNING_SECRET_KEY = 'STORAGE_SIGNING_SECRET';
+
+/**
+ * True while a local disk built without an explicit `signingSecret` would sign with the shipped
+ * development key — `x doctor` reports it, exactly as it reports `usesDevCursorSecret()`.
+ *
+ * Reads the environment, not a driver instance: this is the same question `x doctor` asks about
+ * the cursor secret, and a disk handed an explicit `signingSecret` in `app.config.ts` never
+ * consults the variable at all.
+ *
+ * `env` is core's own slot, so this half of the guard reads the SAME table its other half does:
+ * `dev-runtime.ts` asks `!isLocal({ env }) && usesDevStorageSecret({ env })`, and an embedding
+ * caller (`serveApp({ env })`, a test fixture) whose `env` is not `process.env` used to get one
+ * answer about the boot and one about the process — for the decision of whether a disk may be
+ * signed with the published development key. Defaulted to `process.env`, so a bare call is
+ * unchanged.
+ */
+export function usesDevStorageSecret(options?: Pick<ResolveEnvironmentOptions, 'env'>): boolean {
+  const source = options?.env ?? (process.env as Record<string, string | undefined>);
+  const configured = source[STORAGE_SIGNING_SECRET_KEY];
+  return configured === undefined || configured === '' || configured === DEV_SIGNING_SECRET;
+}
+
+/** The two options the rule reads; `LocalDriverOptions` carries both. */
+export interface SigningSecretOptions {
+  readonly signingSecret?: string | undefined;
+  readonly env?: ResolveEnvironmentOptions['env'];
+}
+
+/**
+ * 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
+ * for any key with any size and type limit — which `acceptSignedUpload` then trusts over the app's
+ * own `uploadPolicy`. Refused at construction, so the boot fails rather than the first upload.
+ *
+ * The published literal counts as no secret at all, whichever way it arrives: an env var or an
+ * `app.config.ts` that pasted it in signs exactly as weakly as the fallback does. One table for
+ * all three reads — the secret, the environment test and the environment the refusal names.
+ * Splitting them is how the guard and the disk came to answer about two different processes.
+ */
+export function resolveSigningSecret(disk: string, options: SigningSecretOptions): string {
+  const env = options.env ?? (process.env as Record<string, string | undefined>);
+  const supplied = options.signingSecret ?? env[STORAGE_SIGNING_SECRET_KEY];
+  const configured =
+    supplied === undefined || supplied === '' || supplied === DEV_SIGNING_SECRET
+      ? undefined
+      : supplied;
+  // 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,7 +15,9 @@ import {
   contentTypeNotAllowed,
   contentTypeUnrecognised,
   tooLarge,
+  xmlBodyUnreadable,
 } from './errors';
+import { HEIF_CONTAINER, ISO_BMFF_CONTAINER, ISO_BMFF_TYPES, sniffIsoBmff } from './iso-bmff';
 import { assertSafeKey } from './path';
 
 export const DEFAULT_MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
@@ -65,7 +67,12 @@ export function uploadPolicy(init: UploadPolicyInit = {}): UploadPolicy {
       init.maxBytes === undefined ? DEFAULT_MAX_UPLOAD_BYTES : init.maxBytes,
       1,
     ),
-    allowedContentTypes: init.allowedContentTypes ?? IMAGE_CONTENT_TYPES,
+    // Normalised, because the declared type is: `validateUpload` and `grantUpload` compare the
+    // NORMALISED declaration against this list, so an allowlist spelling an alias (`image/jpg`,
+    // `audio/x-m4a`) named a type no upload could ever match.
+    allowedContentTypes: (init.allowedContentTypes ?? IMAGE_CONTENT_TYPES).map(
+      normalizeContentType,
+    ),
     requireChecksum: init.requireChecksum ?? false,
   };
 }
@@ -111,7 +118,6 @@ const MAGIC_RULES: readonly MagicRule[] = [
     ],
   },
   { type: 'application/pdf', parts: [{ offset: 0, pattern: ascii('%PDF-') }] },
-  { type: 'video/mp4', parts: [{ offset: 4, pattern: ascii('ftyp') }] },
   // Every OOXML document and epub is a zip; the container is as far as magic bytes go.
   { type: 'application/zip', parts: [{ offset: 0, pattern: [0x50, 0x4b, 0x03, 0x04] }] },
 ];
@@ -146,15 +152,57 @@ 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) {
     if (matches(bytes, rule)) return rule.type;
   }
-  return sniffText(bytes);
+  // Not a `MagicRule`: every ISO base media file opens with the same `ftyp` box, and the one rule
+  // that matched it labelled AVIF, HEIC, MOV and M4A all `video/mp4`. The major brand decides.
+  return sniffIsoBmff(bytes) ?? sniffText(bytes);
 }
 
 // A `Map`, not an object literal: `base` is the transport's own `Content-Type` header by the time
@@ -164,6 +212,10 @@ const ALIASES: ReadonlyMap<string, string> = new Map([
   ['image/jpg', 'image/jpeg'],
   ['image/x-png', 'image/png'],
   ['application/x-pdf', 'application/pdf'],
+  // What Chrome and Safari report for an `.m4a` / `.m4v` picked from disk.
+  ['audio/x-m4a', 'audio/mp4'],
+  ['audio/m4a', 'audio/mp4'],
+  ['video/x-m4v', 'video/mp4'],
 ]);
 
 /** Strip parameters and case: `IMAGE/PNG; charset=binary` and `image/png` are one type. */
@@ -182,11 +234,23 @@ const TEXT_FAMILY = new Set([
   'text/xml',
 ]);
 
-/** A generic sniff (zip container, plain text) may stand in for a specific declared type. */
+// A brand that names only the container: `isom` is on an audio-only MP4 as often as on a video,
+// and `mif1` on a still HEIC and a still AVIF alike. `image/heif` is also the general name of a
+// file whose brand says `heic`, so that pair matches in the other direction too.
+const MP4_CONTAINED = new Set(['audio/mp4']);
+const HEIF_CONTAINED = new Set(['image/heic', 'image/avif']);
+
+/**
+ * A generic sniff (zip container, ISO-BMFF container, plain text) may stand in for a specific
+ * declared type.
+ */
 export function contentTypeMatches(declared: string, sniffed: string): boolean {
   const type = normalizeContentType(declared);
   if (type === sniffed) return true;
   if (sniffed === 'application/zip') return ZIP_CONTAINERS.has(type);
+  if (sniffed === ISO_BMFF_CONTAINER) return MP4_CONTAINED.has(type);
+  if (sniffed === HEIF_CONTAINER) return HEIF_CONTAINED.has(type);
+  if (sniffed === 'image/heic') return type === HEIF_CONTAINER;
   if (sniffed === 'text/plain') return TEXT_FAMILY.has(type);
   return false;
 }
@@ -199,9 +263,16 @@ export function contentTypeMatches(declared: string, sniffed: string): boolean {
  * as provably wrong as one under `image/png`.
  */
 function hasSignature(declared: string): boolean {
-  return MAGIC_RULES.some((rule) => contentTypeMatches(declared, rule.type));
+  return (
+    MAGIC_RULES.some((rule) => contentTypeMatches(declared, rule.type)) ||
+    ISO_BMFF_TYPES.some((type) => contentTypeMatches(declared, type))
+  );
 }
 
+/** `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
@@ -225,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);
   }