@ultimat3/storage 22.15.0 → 24.0.0

package/src/errors.ts

@@ -2,7 +2,12 @@
 // rejected upload must tell the caller which constraint fired and where that constraint is
 // configured, or the caller retries the same bytes forever.
 
-import { registerErrorCodes, renderThrowable, UltimateError } from '@ultimat3/core';
+import {
+  registerErrorCodes,
+  renderFixLiteral,
+  renderThrowable,
+  UltimateError,
+} from '@ultimat3/core';
 
 /** Codes this package declares and owns. */
 export const STORAGE_OWNED_ERROR_CODES = [
@@ -21,11 +26,14 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_LIST_FAILED',
   'X_STORAGE_QUARANTINED',
   'X_STORAGE_NOT_PENDING',
+  'X_STORAGE_KEY_CONFLICT',
+  'X_STORAGE_PUT_FAILED',
+  'X_STORAGE_READ_FAILED',
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. `storageNotImplemented()` throws it and this package
- * keeps no title for it — one code, one owner, one title, or the two copies drift apart in silence.
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. The drivers throw core's own `NotImplementedError`
+ * and this package keeps no title for it — one code, one owner, one title, or the two copies drift apart in silence.
  * `X_IMAGE_UNSUPPORTED` / `X_IMAGE_DECODE_FAILED` are core's too and surface unwrapped (`image.ts`).
  * `X_ENV_MISSING` is core's for the same reason: an unset `STORAGE_SIGNING_SECRET` outside
  * development is a missing environment variable, not a storage concept needing its own code.
@@ -57,6 +65,9 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_LIST_FAILED: 'the objects could not be listed',
   X_STORAGE_QUARANTINED: 'the object is still in quarantine',
   X_STORAGE_NOT_PENDING: 'the key is not a pending upload',
+  X_STORAGE_KEY_CONFLICT: 'the key collides with another key on the local disk',
+  X_STORAGE_PUT_FAILED: 'the object could not be written',
+  X_STORAGE_READ_FAILED: 'the object could not be read',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws
@@ -155,10 +166,55 @@ export const putTooLarge = (
       `send it direct with grantUpload({ disk, orgId, request }) instead of put(), or raise the ceiling: ` +
       (disk === 's3'
         ? `s3Driver({ bucket, maxPutBytes: ${bytes} })`
-        : `localDriver({ root, maxPutBytes: ${bytes} })`),
+        : disk === 'memory'
+          ? `memoryDriver({ maxPutBytes: ${bytes} })`
+          : `localDriver({ root, maxPutBytes: ${bytes} })`),
     meta: { disk, key, bytes, maxBytes },
   });
 
+/**
+ * The SERVER-side `get()` ceiling — `putTooLarge`'s twin. `get()` buffers the whole object, and an
+ * object's size is not this process's to choose: a presigned PUT lands in the bucket unmeasured,
+ * so a later `get()` of it was heap growth the uploader picked.
+ */
+export const getTooLarge = (
+  disk: string,
+  key: string,
+  bytes: number,
+  maxBytes: number,
+): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_TOO_LARGE',
+    cause: `"${key}" is ${bytes}B against the ${disk} disk's get ceiling of ${maxBytes}B, and get() buffers the whole object`,
+    fix:
+      `read it with disk.stream(key) instead of get(), or raise the ceiling: ` +
+      (disk === 's3'
+        ? `s3Driver({ bucket, maxGetBytes: ${bytes} })`
+        : disk === 'memory'
+          ? `memoryDriver({ maxGetBytes: ${bytes} })`
+          : `localDriver({ root, maxGetBytes: ${bytes} })`),
+    meta: { disk, key, bytes, maxBytes },
+  });
+
+/**
+ * The local disk stores an object as a FILE at its key, so a key cannot also be the directory of
+ * another: `put('a')` then `put('a/b')`, or the reverse, or the same pair one tree over in the
+ * sidecars (`a` and `a.json/b`). It surfaced as a bare `ENOTDIR` / `EISDIR`. S3 and the memory
+ * disk hold both — this is the local disk's own limit, refused by name rather than hidden.
+ *
+ * The `fix` lists what is in the way: the remedy is storing one of the two under another key, and
+ * which one is only decidable by a reader who can see both.
+ */
+export const keyConflict = (disk: string, key: string, blocking: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_KEY_CONFLICT',
+    cause: `the "${disk}" disk is a local one and cannot store "${key}": "${blocking}" is already on it, and a POSIX path is a file or a directory, never both — so one key cannot be a path prefix of another here. Store one of the two under a different key; an s3 disk holds both`,
+    // The REGISTERED name, never the driver kind: `disk('local')` on a disk registered as
+    // `uploads` lists another disk, or answers X_STORAGE_DISK_UNKNOWN.
+    fix: `disk(${renderFixLiteral(disk, "'local'")}).list({ prefix: ${renderFixLiteral(blocking, "'a/'")} })`,
+    meta: { disk, key, blocking },
+  });
+
 /** The declared type is not on the allowlist at all. */
 export const contentTypeNotAllowed = (
   key: string,
@@ -256,6 +312,43 @@ export const deleteFailed = (
   });
 };
 
+/**
+ * A write the disk REFUSED — `deleteFailed`'s twin for `put()` and `copy()`. The local disk's
+ * `EACCES` / `ENOSPC` / `EROFS` left as a bare filesystem `Error`, and a provider's refused PUT as
+ * a bare `S3Error`: no code, no fix, nothing for the http error map to render but an anonymous 500.
+ * The `fix` is the driver's, for `deleteFailed`'s reason.
+ */
+export const putFailed = (disk: string, key: string, error: unknown, fix: string): StorageError => {
+  const reason = renderThrowable(error);
+  return new StorageError({
+    code: 'X_STORAGE_PUT_FAILED',
+    cause: `disk "${disk}" refused to write "${key}": ${reason}`,
+    fix,
+    meta: { disk, key, reason },
+  });
+};
+
+/**
+ * A read the disk REFUSED — `putFailed`'s read-side twin, for `get`, `stat`, `exists`, `stream` and
+ * the read half of `copy`. A denied `s3:GetObject`, a throttle, `EACCES`, `EIO`. An object that is
+ * simply absent is `objectNotFound`, never this: "not there" and "could not look" need opposite
+ * answers from a caller. The `fix` is the driver's, for `deleteFailed`'s reason.
+ */
+export const readFailed = (
+  disk: string,
+  key: string,
+  error: unknown,
+  fix: string,
+): StorageError => {
+  const reason = renderThrowable(error);
+  return new StorageError({
+    code: 'X_STORAGE_READ_FAILED',
+    cause: `disk "${disk}" refused to read "${key}": ${reason}`,
+    fix,
+    meta: { disk, key, reason },
+  });
+};
+
 /**
  * A listing the disk REFUSED — a denied `s3:ListBucket`, a throttle, an expired credential, a root
  * this process cannot read. Exactly `deleteFailed`'s shape and for exactly its reason: an empty
@@ -352,21 +445,12 @@ export const signedUrlUnverifiable = (diskName: string): StorageError =>
     meta: { disk: diskName },
   });
 
-export const signingSecretMissing = (environment: string): StorageError =>
+export const signingSecretMissing = (environment: string, disk = 'local'): StorageError =>
   new StorageError({
     code: 'X_ENV_MISSING',
     // The environment names what `resolveEnvironment()` resolved, which may have come from
     // NODE_ENV — naming ULTIMATE_ENV here reported a variable the process never set.
-    cause: `the local disk has no usable signing secret (no signingSecret option, and STORAGE_SIGNING_SECRET is unset, empty or the published development key) and the resolved environment is "${environment}", so it would sign URLs with the shipped development key`,
+    cause: `the ${disk} disk has no usable signing secret (no signingSecret option, and STORAGE_SIGNING_SECRET is unset, empty or the published development key) and the resolved environment is "${environment}", so it would sign URLs with the shipped development key`,
     fix: 'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
     meta: { key: 'STORAGE_SIGNING_SECRET', environment },
   });
-
-/** An interface-complete driver whose remote half is not bound yet. Always carries a fix. */
-export const storageNotImplemented = (feature: string, fix: string): StorageError =>
-  new StorageError({
-    code: 'X_NOT_IMPLEMENTED',
-    cause: `${feature} is declared but not implemented in @ultimat3/storage`,
-    fix,
-    meta: { feature },
-  });

package/src/grant.ts

@@ -83,12 +83,12 @@ export async function grantUpload(input: GrantUploadInput): Promise<UploadGrant>
   }
 
   // Refused here as well as in the presigner one call down: `expiresAt: now + NaN` is `NaN` in the
-  // grant this function RETURNS, and the message a caller can act on names `createUploadGrant`'s
+  // grant this function RETURNS, and the message a caller can act on names `grantUpload`'s
   // own option rather than `buildSignedUrl`'s.
   // `=== undefined`, never `??`, for the reason `buildSignedUrl` states: `??` coalesces on `null`
   // too, so an explicit one took the default instead of this refusal.
   const expiresInMs = finiteCount(
-    'createUploadGrant',
+    'grantUpload',
     'expiresInMs',
     input.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : input.expiresInMs,
     1,

package/src/image.ts

@@ -6,12 +6,13 @@
 import {
   assertFiniteImageQuality,
   blurDataUrl,
+  finiteCount,
   type ImageFormat,
   imageUnsupported,
   probeImage,
   transformImageBytes,
 } from '@ultimat3/core';
-import { assertSafeKey, keyExtname } from './path';
+import { assertSafeKey } from './path';
 
 /**
  * The formats a stored VARIANT can be minted in — a strict subset of the ones `@ultimat3/core`
@@ -67,13 +68,28 @@ const FORMAT_EXTENSIONS: Readonly<Record<VariantFormat, string>> = {
   png: 'png',
 };
 
+/**
+ * One edge of a variant box: a whole number of pixels, at least one. Core's `finiteCount`, for the
+ * reason `quality` goes through core's screen below — `{ width: NaN }` minted `a@wNaN.webp`, a
+ * writable key for bytes no encoder can produce, and `w1.5` / `w-3` are an unbounded number of
+ * keys in a bucket. `!== undefined`, never a truthiness test: an explicit `null` is refused.
+ */
+function edge(subject: string, option: 'width' | 'height', value: number | undefined): void {
+  if (value !== undefined) finiteCount(subject, option, value, 1);
+}
+
 /**
  * Derived, not stored: the same source + transform always yields the same key, so a variant
  * is a cache lookup rather than a database row.
+ *
+ * The WHOLE source key is the stem, extension included. It used to be cut, so `p/hero.png` and
+ * `p/hero.jpg` minted one `p/hero@w100.webp` and whichever was requested first was served for
+ * both — two sources, one cache identity.
  */
 export function variantKey(sourceKey: string, transform: ImageTransform): string {
   const safe = assertSafeKey(sourceKey);
-  const stem = safe.slice(0, safe.length - keyExtname(safe).length);
+  edge('variantKey', 'width', transform.width);
+  edge('variantKey', 'height', transform.height);
   // `string`, not `VariantFormat`: a format off a query string or through an `as` reaches here as
   // any string core can probe, and indexing FORMAT_EXTENSIONS with `gif` minted
   // `photos/hero@full.undefined` — a well-formed, writable key naming a file nothing can serve.
@@ -101,7 +117,7 @@ export function variantKey(sourceKey: string, transform: ImageTransform): string
   );
   if (quality !== DEFAULT_QUALITY) parts.push(`q${quality}`);
   if (parts.length === 0) parts.push('full');
-  return assertSafeKey(`${stem}@${parts.join('-')}.${FORMAT_EXTENSIONS[format]}`);
+  return assertSafeKey(`${safe}@${parts.join('-')}.${FORMAT_EXTENSIONS[format]}`);
 }
 
 export interface SrcsetDescriptor {
@@ -139,23 +155,33 @@ export function srcsetDescriptors(
     }));
 }
 
-/** Aspect-ratio fitting. `cover` rounds up so the box is always fully covered. */
+/** A derived edge is never zero: 1000x1 at width 100 rounded to a height no encoder can fill. */
+const atLeastOne = (pixels: number): number => Math.max(1, Math.round(pixels));
+
+/**
+ * Aspect-ratio fitting. `cover` is the exact box asked for; everything else fits INSIDE the box
+ * and never above the source — upscaling is never useful, whichever edges were named.
+ */
 export function fitDimensions(source: ImageSize, transform: ImageTransform): ImageSize {
   const ratio = source.height / source.width;
   const { width, height } = transform;
+  edge('fitDimensions', 'width', width);
+  edge('fitDimensions', 'height', height);
   if (width === undefined && height === undefined) return source;
   if (height === undefined) {
     const target = Math.min(width ?? source.width, source.width);
-    return { width: target, height: Math.round(target * ratio) };
+    return { width: target, height: atLeastOne(target * ratio) };
   }
   if (width === undefined) {
     const target = Math.min(height, source.height);
-    return { width: Math.round(target / ratio), height: target };
+    return { width: atLeastOne(target / ratio), height: target };
   }
   // `cover` crops to the exact box; `contain` scales down until both sides fit.
   if (transform.fit === 'cover') return { width, height };
-  const scale = Math.min(width / source.width, height / source.height);
-  return { width: Math.round(source.width * scale), height: Math.round(source.height * scale) };
+  // Clamped at 1: a single named edge already stopped at the source, and two of them did not —
+  // a 40x20 source asked for 400x400 came back 400x200.
+  const scale = Math.min(1, width / source.width, height / source.height);
+  return { width: atLeastOne(source.width * scale), height: atLeastOne(source.height * scale) };
 }
 
 /**

package/src/index.ts

@@ -43,22 +43,20 @@ export type {
   StorageRead,
 } from './driver';
 export {
+  // Exported for the same reason `toBytes` is: a driver written outside this package has to
+  // refuse a `limit` the same way both shipped ones do, or it is a third answer to one question.
+  assertPutOptions,
   DEFAULT_CONTENT_TYPE,
   DEFAULT_LIST_LIMIT,
   etagOf,
-  // Exported for the same reason `toBytes` is: a driver written outside this package has to
-  // refuse a `limit` the same way both shipped ones do, or it is a third answer to one question.
   resolveListLimit,
   sha256Base64,
   toBytes,
 } from './driver';
 export type { LocalDriverOptions } from './driver-local';
-export {
-  DEV_SIGNING_SECRET,
-  localDriver,
-  STORAGE_SIGNING_SECRET_KEY,
-  usesDevStorageSecret,
-} from './driver-local';
+export { localDriver } from './driver-local';
+export type { MemoryDriverOptions, MemoryStorageDriver } from './driver-memory';
+export { memoryDriver } from './driver-memory';
 export type {
   S3ClientLike,
   S3DriverOptions,
@@ -76,13 +74,17 @@ export {
   contentTypeUnrecognised,
   deleteFailed,
   diskUnknown,
+  getTooLarge,
   isStorageError,
+  keyConflict,
   listFailed,
   objectNotFound,
   orgMismatch,
   pathUnsafe,
+  putFailed,
   putTooLarge,
   quarantined,
+  readFailed,
   STORAGE_ERROR_CODES,
   STORAGE_ERROR_TITLES,
   StorageError,
@@ -90,7 +92,6 @@ export {
   signedUrlRejected,
   signedUrlUnverifiable,
   signingSecretMissing,
-  storageNotImplemented,
   tooLarge,
   uploadFailed,
 } from './errors';
@@ -150,9 +151,15 @@ export {
   SIGNED_URL_VERSION,
   signConstraints,
   signedUrlBaseFor,
+  signedUrlBasePath,
   timingSafeEqual,
   verifySignedUrl,
 } from './signed-url';
+export {
+  DEV_SIGNING_SECRET,
+  STORAGE_SIGNING_SECRET_KEY,
+  usesDevStorageSecret,
+} from './signing-secret';
 export type { Storage, StorageConfig } from './storage';
 export { definedStorage, defineStorage, disk, resetStorage, storage } from './storage';
 export type { UploadCandidate, UploadPolicy, UploadPolicyInit, ValidatedUpload } from './upload';

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;
+}