@ultimat3/storage 23.0.0 → 24.0.0

package/src/iso-bmff.ts

@@ -0,0 +1,50 @@
+// Single responsibility: which media type an ISO base media file is. Every MP4, MOV, M4A, HEIC
+// and AVIF opens with the same `ftyp` box, so the box alone says "container" — the four-byte MAJOR
+// BRAND after it is what says which one, and reading only the box labelled all of them `video/mp4`.
+
+const ascii = (bytes: Uint8Array, offset: number): string =>
+  String.fromCharCode(...bytes.subarray(offset, offset + 4));
+
+/** The type a major brand cannot narrow: a container, as `application/zip` is one for OOXML. */
+export const ISO_BMFF_CONTAINER = 'video/mp4';
+
+/** HEIF's structural brands — a still HEIC and a still AVIF both ship under `mif1`. */
+export const HEIF_CONTAINER = 'image/heif';
+
+// A `Map`, never an object literal: the brand is four bytes off an upload, and `BRANDS['cons']`
+// is harmless only until a brand spells a prototype key.
+const BRANDS: ReadonlyMap<string, string> = new Map([
+  ['avif', 'image/avif'],
+  ['avis', 'image/avif'],
+  ['heic', 'image/heic'],
+  ['heix', 'image/heic'],
+  ['heim', 'image/heic'],
+  ['heis', 'image/heic'],
+  ['hevc', 'image/heic'],
+  ['hevx', 'image/heic'],
+  ['mif1', HEIF_CONTAINER],
+  ['msf1', HEIF_CONTAINER],
+  ['qt  ', 'video/quicktime'],
+  ['M4A ', 'audio/mp4'],
+  ['M4B ', 'audio/mp4'],
+  ['M4P ', 'audio/mp4'],
+  ['3gp4', 'video/3gpp'],
+  ['3gp5', 'video/3gpp'],
+  ['3gp6', 'video/3gpp'],
+  ['3g2a', 'video/3gpp2'],
+]);
+
+/** Every type `sniffIsoBmff` can answer — what `validateUpload` reads "could confirm" from. */
+export const ISO_BMFF_TYPES: readonly string[] = [
+  ...new Set([ISO_BMFF_CONTAINER, ...BRANDS.values()]),
+];
+
+/**
+ * `undefined` when the bytes do not open with a `ftyp` box carrying a brand. A brand this table
+ * does not list answers the container: it is an ISO base media file, which is all the box proves,
+ * and that is the answer every brand got before this file existed.
+ */
+export function sniffIsoBmff(bytes: Uint8Array): string | undefined {
+  if (bytes.byteLength < 12 || ascii(bytes, 4) !== 'ftyp') return undefined;
+  return BRANDS.get(ascii(bytes, 8)) ?? ISO_BMFF_CONTAINER;
+}

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

@@ -12,7 +12,8 @@ import { assertSafeKey, isSafeKey } from './path';
  * 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 +71,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 +112,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 +121,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 +177,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 +254,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,71 @@
+// 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.
+
+import { isLocal, 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 `memoryDriver` 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: 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' }))
+    throw signingSecretMissing(resolveEnvironment({ env, fallback: 'production' }), disk);
+  return configured ?? DEV_SIGNING_SECRET;
+}

package/src/upload.ts

@@ -16,6 +16,7 @@ import {
   contentTypeUnrecognised,
   tooLarge,
 } 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 +66,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 +117,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] }] },
 ];
@@ -154,7 +159,9 @@ 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 +171,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 +193,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,7 +222,10 @@ 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))
+  );
 }
 
 /**