@ultimat3/storage 9.0.0 → 11.0.0

package/CLAUDE.md

@@ -154,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

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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "9.0.0",
+  "version": "11.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": "9.0.0"
+    "@ultimat3/core": "11.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,
     });
   }