@ultimat3/storage 8.0.0 → 10.0.0

package/CLAUDE.md

@@ -32,6 +32,7 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
 | `signed-url.ts` | HMAC over the constraint tuple, constant-time verify |
 | `upload.ts` | magic-byte sniff + size/allowlist/checksum policy |
 | `image.ts` | deterministic variant keys; byte path over core's pipeline (png/jpeg encode only) |
+| | `VARIANT_FORMATS` — what a variant KEY can carry — and NOT `IMAGE_FORMATS`, which is core's and means what core can PROBE. See below |
 | | `variantKey` is the cache identity `@ultimat3/cli`'s `/media/*` route looks a variant up by — derived, never stored, so a request that misses transforms once and every later one is a disk read |
 | `storage.ts` | `defineStorage` + module-level `storage()` / `disk()` |
 | `grant.ts` | `grantUpload` — the ONE way a presigned PUT is minted; the client never names a key |
@@ -153,6 +154,16 @@ Gotchas:
   may be `NODE_ENV`'s, never a variable the process did not set. `usesDevStorageSecret()` is the
   `x doctor` predicate, mirroring core's `usesDevCursorSecret()`; it reads the env var, so a disk
   handed an explicit `signingSecret` is outside its question.
+- **`localDriver({ env })` and `usesDevStorageSecret({ env })` are ONE question about ONE table**
+  (`As of 2026-08-23`). The predicate learned core's `env` slot first, so `dev-runtime.ts`'s guard
+  — `!isLocal({ env }) && usesDevStorageSecret({ env })` — asked about the BOOT while the
+  constructor it guards still read `process.env` for the secret, for `isLocal()` and for the
+  environment its refusal names. An embedding caller whose env is not the process's (`serveApp({ env })`,
+  a test fixture) got the verdict from one table and the behaviour from another, in the dangerous
+  direction: a production boot with no secret, launched from a development shell that has one,
+  signing every grant with the published literal. All three reads now come off `options.env ??
+  process.env`, so a bare `localDriver({ root })` is unchanged and additive. `driver-local.test.ts`
+  pins it by mutation — reverting any one read to `process.env` fails.
 - **The mounted read half is `@ultimat3/cli`'s `dev-storage.ts`, not this package.** `GET
   /_storage/:disk/*key` gates on `@ultimat3/policy`'s `evaluate()` (`storage:read`), which is tier
   2 and unreachable from here — so a "serve this object" helper in this package could only ever be
@@ -169,7 +180,21 @@ Gotchas:
   in `beforeEach`.
 - `image.ts` owns no pixels: core's `transformImageBytes`/`blurDataUrl` are the only scaler.
   Its image failures (`X_IMAGE_UNSUPPORTED`, `X_IMAGE_DECODE_FAILED`) surface unwrapped —
-  wrapping them in a `StorageError` would give one failure two codes.
+  wrapping them in a `StorageError` would give one failure two codes. `variantKey` now RAISES
+  core's `imageUnsupported()` as well as passing them through, for that same reason.
+- **`VARIANT_FORMATS` is this package's format vocabulary, and `IMAGE_FORMATS` is core's.** Until
+  9.0.0 both packages exported `IMAGE_FORMATS` **and** `ImageFormat` from their own barrels over
+  different sets (core: `png|jpeg|webp|avif|gif|svg`, what it can PROBE; storage: `avif|webp|jpeg|png`),
+  so a caller narrowing on storage's held a type saying `gif` and `svg` could not occur and a
+  `probeImage()` value that was one — and `variantKey('photos/hero.gif', { format })` minted
+  `photos/hero@full.undefined`, a well-formed writable key naming a file nothing can serve. The set
+  is now a strict subset **by the compiler**: `as const satisfies readonly ImageFormat[]`, so a
+  member core cannot name is a build error here. `isVariantFormat` takes `string` on purpose, so
+  `probeImage(bytes).format` narrows through it with no cast. `avif` is in the set and `gif`/`svg`
+  are not because the question is what a variant KEY can carry, never what core can transform —
+  core decodes `gif` perfectly well, and naming this set `TRANSFORMABLE_FORMATS` would have been
+  the same lie one rename later. `scripts/render-modes.ts` holds the `IMAGE_FORMATS` row (`by:
+  'name'`) and `image.test.ts` fails the day either core name reappears in `src/index.ts`.
 - `transformImage()` must encode at exactly `fitDimensions()`'s size, and passes `format`
   explicitly (`?? 'webp'`, which then rejects): bytes that disagree with the `variantKey`
   extension, or with the `width`/`height` `@ultimat3/seo` inlined, are the layout shift the

package/README.md

@@ -113,6 +113,12 @@ any key with a `maxBytes` and `contentType` of their choosing, which `acceptSign
 trusts over the app's own `uploadPolicy`. Setting `STORAGE_SIGNING_SECRET=$DEV_SIGNING_SECRET`, or
 pasting the literal into `signingSecret`, is refused exactly as an unset variable is. `usesDevStorageSecret()` is the
 `x doctor` probe for it, the twin of core's `usesDevCursorSecret()`.
+
+Both read **one table**, and `env` is how a caller says which. `localDriver({ root, env })` reads
+the secret, the environment test and the environment the refusal names off that table;
+`usesDevStorageSecret({ env })` reads it off the same one. Both default to `process.env`, so a bare
+call is unchanged — pass `env` wherever the boot's environment is not the process's (`serveApp({ env })`,
+a test fixture), or the guard answers about one process and the disk signs according to another.
 Verification is constant-time, checks the signature *before* the expiry (a forged URL never
 learns it was merely late), takes a `Clock` so tests freeze time, and returns
 `{ ok: false, reason }` rather than throwing — `malformed | unsafe-key | signature-mismatch |
@@ -235,7 +241,7 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 | `X_STORAGE_QUARANTINED` | `promoteAttachment` on a key nothing has released from `pending/quarantine/` |
 | `X_NOT_IMPLEMENTED` | S3 user metadata / cache-control; `serverSideEncryption` on either driver |
 | `X_ENV_MISSING` | core's: S3 credential env vars, or a `localDriver` built outside development where neither `signingSecret` nor `STORAGE_SIGNING_SECRET` holds a secret other than the published `DEV_SIGNING_SECRET` |
-| `X_IMAGE_UNSUPPORTED` | core's: an `avif` encode, or a source no built-in decoder reads |
+| `X_IMAGE_UNSUPPORTED` | core's: an `avif` encode, a source no built-in decoder reads, or a `variantKey` format no variant can carry |
 | `X_IMAGE_DECODE_FAILED` | core's: truncated or corrupt image bytes |
 
 ## Images
@@ -243,6 +249,15 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 `variantKey()`, `srcsetDescriptors()`, `fitDimensions()` are pure — `@ultimat3/seo` builds
 `srcset` from them without decoding a byte.
 
+**`VARIANT_FORMATS` / `VariantFormat` are what a variant KEY can carry, `As of 2026-08`** —
+`avif`, `webp`, `jpeg`, `png` — and this package exports no `IMAGE_FORMATS` and no `ImageFormat`. Those two names are
+`@ultimat3/core`'s, over the six formats it can PROBE (`png`, `jpeg`, `webp`, `avif`, `gif`,
+`svg`). Until 9.0.0 both packages exported both names over different sets, so a caller narrowing on
+storage's held a type saying `gif` and `svg` could not occur and a `probeImage()` value that was
+one. `isVariantFormat(format)` takes a `string`, so a probed format narrows through it with no
+cast, and `variantKey()` refuses anything else with core's `X_IMAGE_UNSUPPORTED` instead of minting
+`photos/hero@full.undefined`.
+
 `transformImage()` and `blurPlaceholder()` are real, over `@ultimat3/core`'s pipeline, which is
 `Bun.Image` — no `sharp`, no dependency. **It encodes `png`, `jpeg` and `webp`** — so the default
 format and the default `.webp` key extension finally agree, and a `srcset` entry can be served

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "8.0.0",
+  "version": "10.0.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "8.0.0"
+    "@ultimat3/core": "10.0.0"
   }
 }

package/src/driver-local.ts

@@ -3,7 +3,14 @@
 // Content type, etag and user metadata live in a sidecar under `.meta/`: a POSIX file has
 // nowhere to keep them, and `get` must round-trip exactly what `put` was handed.
 
-import { type Clock, isLocal, resolveEnvironment, stringField, systemClock } from '@ultimat3/core';
+import {
+  type Clock,
+  isLocal,
+  type ResolveEnvironmentOptions,
+  resolveEnvironment,
+  stringField,
+  systemClock,
+} from '@ultimat3/core';
 import {
   DEFAULT_CONTENT_TYPE,
   etagOf,
@@ -52,9 +59,17 @@ export const STORAGE_SIGNING_SECRET_KEY = 'STORAGE_SIGNING_SECRET';
  * 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(): boolean {
-  const configured = process.env[STORAGE_SIGNING_SECRET_KEY];
+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;
 }
 
@@ -66,6 +81,21 @@ export interface LocalDriverOptions {
   /** Route prefix the dev server serves signed URLs from. */
   readonly baseUrl?: string | undefined;
   readonly clock?: Clock | undefined;
+  /**
+   * The environment table this DISK belongs to — the boot's, which is not always the process's.
+   * Core's own slot (`ResolveEnvironmentOptions['env']`), narrowed to that one field because the
+   * `fallback` beside it is a question this constructor never asks.
+   *
+   * It exists because the guard and the thing it guards have to read one table. `x doctor` and
+   * `dev-runtime.ts` ask `!isLocal({ env }) && usesDevStorageSecret({ env })` about the boot; the
+   * constructor below is what actually decides whether this disk signs with the published
+   * development key, and while it read `process.env` an embedding caller (`serveApp({ env })`, a
+   * test fixture) got the verdict from one table and the behaviour from another — in the
+   * dangerous direction, a production boot signing with a key published in this repo.
+   *
+   * Defaults to `process.env`, so a bare `localDriver({ root })` is unchanged.
+   */
+  readonly env?: ResolveEnvironmentOptions['env'];
   /**
    * Ceiling on ONE server-side `put()`, because `put()` buffers the whole body. Defaults to the
    * upload policy's ceiling — the same number for the same fact. The dev disk enforces it for
@@ -143,12 +173,17 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
   // 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.
-  const supplied = options.signingSecret ?? process.env[STORAGE_SIGNING_SECRET_KEY];
+  // 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.
+  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;
-  if (configured === undefined && !isLocal()) throw signingSecretMissing(resolveEnvironment());
+  if (configured === undefined && !isLocal({ env }))
+    throw signingSecretMissing(resolveEnvironment({ env }));
   const secret = configured ?? DEV_SIGNING_SECRET;
 
   const filePath = (key: string): string => `${root}/${key}`;

package/src/errors.ts

@@ -2,7 +2,7 @@
 // rejected upload must tell the caller which constraint fired and where that constraint is
 // configured, or the caller retries the same bytes forever.
 
-import { errorDocsUrl, registerErrorCodes, renderThrowable, UltimateError } from '@ultimat3/core';
+import { registerErrorCodes, renderThrowable, UltimateError } from '@ultimat3/core';
 
 /** Codes this package declares and owns. */
 export const STORAGE_OWNED_ERROR_CODES = [
@@ -80,7 +80,6 @@ export class StorageError extends UltimateError {
       code: init.code,
       cause: init.cause,
       fix: init.fix,
-      docs: errorDocsUrl(init.code),
       meta: init.meta,
     });
   }

package/src/image.ts

@@ -3,11 +3,41 @@
 // `<img srcset>` from `srcsetDescriptors()` without decoding a byte, and when it does need the
 // bytes, `transformImage()` returns exactly the size `fitDimensions()` already promised.
 
-import { blurDataUrl, probeImage, transformImageBytes } from '@ultimat3/core';
+import {
+  blurDataUrl,
+  type ImageFormat,
+  imageUnsupported,
+  probeImage,
+  transformImageBytes,
+} from '@ultimat3/core';
 import { assertSafeKey, keyExtname } from './path';
 
-export const IMAGE_FORMATS = ['avif', 'webp', 'jpeg', 'png'] as const;
-export type ImageFormat = (typeof IMAGE_FORMATS)[number];
+/**
+ * The formats a stored VARIANT can be minted in — a strict subset of the ones `@ultimat3/core`
+ * can PROBE, and a different question from them. `satisfies readonly ImageFormat[]` is the whole
+ * derivation: a member core cannot name is a compile error here, so this can never become a
+ * second vocabulary the way it was one until 9.0.0 (both packages exported `IMAGE_FORMATS` and
+ * `ImageFormat`, over different sets, from their own barrels — so a caller narrowing on storage's
+ * held a type saying `gif` and `svg` could not occur and a `probeImage()` value that was one).
+ *
+ * NOT "the formats storage can transform": core decodes `gif` perfectly well. This set is what a
+ * variant KEY can carry, which is why `avif` is in it (key and `srcset` math only — asking for
+ * its bytes rejects with core's `X_IMAGE_UNSUPPORTED`) and `gif` and `svg` are not.
+ */
+export const VARIANT_FORMATS = [
+  'avif',
+  'webp',
+  'jpeg',
+  'png',
+] as const satisfies readonly ImageFormat[];
+export type VariantFormat = (typeof VARIANT_FORMATS)[number];
+
+/**
+ * Takes `string`, so `probeImage(bytes).format` narrows through it without a cast. That is the
+ * whole point: the answer for `gif` is `false`, and it used to be unaskable.
+ */
+export const isVariantFormat = (format: string): format is VariantFormat =>
+  (VARIANT_FORMATS as readonly string[]).includes(format);
 
 /** `cover` fills the box and crops the overflow; `contain` fits inside it, no crop. */
 export type ImageFit = 'cover' | 'contain';
@@ -15,7 +45,7 @@ export type ImageFit = 'cover' | 'contain';
 export interface ImageTransform {
   readonly width?: number | undefined;
   readonly height?: number | undefined;
-  readonly format?: ImageFormat | undefined;
+  readonly format?: VariantFormat | undefined;
   /** 1-100. Omitted means the format default (`DEFAULT_QUALITY`). */
   readonly quality?: number | undefined;
   readonly fit?: ImageFit | undefined;
@@ -29,7 +59,7 @@ export interface ImageSize {
 export const DEFAULT_QUALITY = 80;
 export const DEFAULT_SRCSET_WIDTHS = [320, 640, 960, 1280, 1920] as const;
 
-const FORMAT_EXTENSIONS: Readonly<Record<ImageFormat, string>> = {
+const FORMAT_EXTENSIONS: Readonly<Record<VariantFormat, string>> = {
   avif: 'avif',
   webp: 'webp',
   jpeg: 'jpg',
@@ -43,7 +73,19 @@ const FORMAT_EXTENSIONS: Readonly<Record<ImageFormat, string>> = {
 export function variantKey(sourceKey: string, transform: ImageTransform): string {
   const safe = assertSafeKey(sourceKey);
   const stem = safe.slice(0, safe.length - keyExtname(safe).length);
-  const format = transform.format ?? 'webp';
+  // `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.
+  // Core's code, not a storage one: one bad format is one failure, and seo and the dev asset
+  // route already report it as X_IMAGE_UNSUPPORTED.
+  const format: string = transform.format ?? 'webp';
+  if (!isVariantFormat(format)) {
+    throw imageUnsupported(
+      `"${format}" is not a format a stored variant can be minted in`,
+      `variantKey('${safe}', { format: 'webp' }) — one of ${VARIANT_FORMATS.join(', ')}; a ${format} source is served as-is, it has no variant`,
+      { format, key: safe },
+    );
+  }
   const parts: string[] = [];
   if (transform.width !== undefined) parts.push(`w${transform.width}`);
   if (transform.height !== undefined) parts.push(`h${transform.height}`);
@@ -63,7 +105,7 @@ export interface SrcsetDescriptor {
 
 export interface SrcsetOptions {
   readonly widths?: readonly number[] | undefined;
-  readonly format?: ImageFormat | undefined;
+  readonly format?: VariantFormat | undefined;
   readonly quality?: number | undefined;
   /** Intrinsic size of the source. Widths above it are dropped — upscaling is never useful. */
   readonly intrinsic?: ImageSize | undefined;

package/src/index.ts

@@ -97,20 +97,24 @@ export type { GrantUploadInput, UploadGrant, UploadRequest } from './grant';
 export { grantUpload } from './grant';
 export type {
   ImageFit,
-  ImageFormat,
   ImageSize,
   ImageTransform,
   SrcsetDescriptor,
   SrcsetOptions,
+  VariantFormat,
 } from './image';
+// No `ImageFormat` and no `IMAGE_FORMATS` here, deliberately: `@ultimat3/core` owns that name and
+// that set (what it can PROBE), this package owns `VARIANT_FORMATS` (what a variant can be minted
+// in), and `image.test.ts` fails the day either core name reappears in this file.
 export {
   blurPlaceholder,
   DEFAULT_QUALITY,
   DEFAULT_SRCSET_WIDTHS,
   fitDimensions,
-  IMAGE_FORMATS,
+  isVariantFormat,
   srcsetDescriptors,
   transformImage,
+  VARIANT_FORMATS,
   variantKey,
 } from './image';