@ultimat3/storage 3.0.0 → 4.1.0

package/CLAUDE.md

@@ -50,6 +50,33 @@ Gotchas:
   in a single `test()` per claim, so neither disk can move alone. Where the two genuinely cannot
   agree it pins the DIVERGENCE, with the reason — that is the honest form, and it still fails the
   day either half changes.
+- **The local `list()` globs with `dot: true`, and the `META_DIR` skip is the REAL filter**
+  (`As of 2026-08`). `Bun.Glob('**/*')` matches no dot-prefixed entry, so every object whose key
+  had one — `.hidden.txt`, `org/o1/pending/.x.png`, the `.metadata/a.json` `path.test.ts` pins as
+  legal — was missing from the listing while `put`/`get`/`exists` handled it normally and
+  `s3Driver.list()` returned it: the key space and the listing disagreed by construction.
+  `sweepOrphans` pages through `list()`, so those objects were reported as erased while still on
+  disk — a false erasure report by OMISSION, the same lie a swallowed listing error tells. The
+  `.meta/` skip one line below was unreachable until this landed and this file called it "a second
+  line of defence"; it is now the only thing keeping the sidecar tree out of the object namespace,
+  and it folds case for `isSafeKey`'s reason. Pinned in `driver-parity.test.ts`.
+- **A `list({ limit })` is a positive integer or a refusal** — `resolveListLimit` at the
+  `ListOptions` seam, so both disks answer one way. `limit: 0` used to slice `[0, 0)` on the local
+  disk and then drop its own `truncated` flag (`truncated && last !== undefined`, with an empty
+  page), so a paging caller read "complete, and there is nothing here" over a full disk, while the
+  s3 disk handed `maxKeys: 0` to the provider. Core's `assert` (`X_INVARIANT`), for the reason
+  `@ultimat3/seo`'s `chunk()` uses it: a bound with no code of its own is still a coded refusal.
+- **`META_DIR` is reserved case-INSENSITIVELY** (`As of 2026-08`), exactly as `isTenantScoped`
+  folds and for the same filesystem: `.META/a.txt.json` was a legal key that writes
+  `<root>/.META/a.txt.json`, which on APFS and NTFS IS `<root>/.meta/a.txt.json` — the sidecar for
+  object `a.txt` — so a caller able to name a key rewrote another object's recorded `contentType`.
+  The whole SEGMENT is compared, never a prefix: `.metadata/a.json` is an ordinary key and stays
+  one, and `path.test.ts` pins both halves.
+- **`disk(name)` resolves through a `Map`, never `config.disks[name]`.** The bracket read walked
+  the prototype chain, so `disk('constructor')` handed back the `Object` function and the next
+  `.put()` was a bare `TypeError` — `X_STORAGE_DISK_UNKNOWN` unreachable for `constructor`,
+  `toString`, `valueOf`, `hasOwnProperty` and `__proto__`, in a function whose own
+  `default:` check already read `Object.keys`.
 - **`list()` is idempotent for an EMPTY disk and for nothing else** (`As of 2026-08`) — exactly
   `delete()`'s rule, one call to the left, and both drivers broke it in opposite directions. The
   local one caught EVERYTHING and answered `{ objects: [], truncated: false }`, so `EACCES` on the
@@ -113,7 +140,8 @@ Gotchas:
   itself a legal key, so an uploader could rewrite another object's recorded `contentType` to
   `text/html` and have a route serve attacker HTML from the app's origin. Reserved in
   `assertSafeKey`, so it holds for S3 too — a key valid on one driver and refused on another is two
-  key rules. The `list()` skip stays as a second line of defence.
+  key rules, and the reservation folds case — see above. The `list()` skip is not a second line of
+  defence but the only one: the glob yields the sidecar tree.
 - **`localDriver` refuses to construct outside development without a usable signing secret**
   (`X_ENV_MISSING`, borrowed from core). Usable means neither the `signingSecret` option nor
   `STORAGE_SIGNING_SECRET` is missing, empty **or** the published `DEV_SIGNING_SECRET` — pasting
@@ -157,11 +185,19 @@ Gotchas:
 - `acceptSignedUpload` refuses a URL signed with **no** content type (`unconstrained`). `grantUpload`
   always sets one, so such a URL is hand-rolled, and trusting the uploader's header instead is the
   only other option.
-- **The signed base is declared ONCE, in `signedUrlBaseFor(driverName)`.** `localDriver` mints
-  under it and `accept.ts` defaults to `signedUrlBaseFor(disk.name)` — the same base, arrived at
-  from the disk the caller already passed. It was stated twice (`/_storage/local` in the driver,
-  `/_storage` in `verifySignedUrl`'s default), so with both defaults NO genuine URL verified: the
-  key parsed as `local/<key>` and every grant died as `signature-mismatch`. `@ultimat3/cli`'s
+- **The signed base is the disk's REGISTERED name, and it is stated once — on the driver.**
+  `defineStorage` tells each driver its registration key (`StorageDriver.registerAs`), the driver
+  rebases its URLs onto `signedUrlBaseFor(diskName)`, and `accept.ts` reads `disk.signedUrlBase`
+  rather than deriving a second one. Both halves used to derive it from `disk.name` — the DRIVER
+  kind — so they agreed with each other and disagreed with the mounted `/_storage/:disk/*key`
+  route, which resolves the segment through the registry: a disk registered as `uploads` minted
+  `/_storage/local/...` and 404'd its own signatures. Latent only because every disk in this repo
+  happens to be named `local`. An explicit `baseUrl` on `localDriver` outranks the registration
+  (the operator saying where the route is mounted); an unregistered driver still mints under
+  `local`. One driver instance under two disk names is refused at `defineStorage`
+  (`X_CONFIG_INVALID`) — it could only mint under one of them. Before that, the base was stated
+  twice (`/_storage/local` in the driver, `/_storage` in `verifySignedUrl`'s default) and NO
+  genuine URL verified at all: the key parsed as `local/<key>`. `@ultimat3/cli`'s
   `STORAGE_BASE_PATH` is a third statement of the mount prefix and should import
   `DEFAULT_SIGNED_URL_BASE` instead.
 - **`accept.ts` asks the `isTenantScoped`/`isWithinOrg` PAIR, exactly as `dev-storage.ts` does.**

package/README.md

@@ -50,6 +50,12 @@ The etag follows the same rule: a listed object with no sidecar reports `etag: '
 answering otherwise means reading and hashing the whole object — which is what the local `list()`
 used to do, once per sidecar-less row, sequentially. `get()` hashes out of bytes it already holds.
 
+**A listing returns every key the key rules allow**, dot-prefixed segments included
+(`.hidden.txt`, `org/o1/pending/.x.png`) — the local glob was blind to them until 2026-08, so a
+disk answered `exists()` true and `list()` nothing for the same object. **`limit` is a positive
+integer or a refusal** (`X_INVARIANT`, at the `ListOptions` seam): `limit: 0` used to read back as
+a complete, empty page on the local disk and as `maxKeys: 0` on s3.
+
 ## `put()` is for objects that fit in memory
 
 `put()` buffers the whole body — size and checksum have to be known before the object exists —
@@ -146,9 +152,9 @@ const { key } = await uploadFile({ file, grant: (request) => api.requestUpload(r
 
 // 3. server, in the route mounted at `/_storage`: take it back, or refuse
 const object = await acceptSignedUpload({
-  url: request.url,                  // baseUrl defaults to signedUrlBaseFor(disk.name) — the
-  secret,                            // same base the driver signed under. Pass one only for a
-  disk: disk('uploads'),             // route mounted somewhere other than /_storage/<driver>.
+  url: request.url,                  // baseUrl defaults to `disk.signedUrlBase` — the very base
+  secret,                            // the driver signed under, `/_storage/<disk name>`. Pass one
+  disk: disk('uploads'),             // only for a route mounted somewhere else.
   orgId: ctx.actor.orgId,
   bytes, declaredContentType: request.headers.get('content-type') ?? undefined,
   policy: uploadPolicy({ maxBytes: 5e6 }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "3.0.0",
+  "version": "4.1.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": "3.0.0"
+    "@ultimat3/core": "4.1.0"
   }
 }

package/src/accept.ts

@@ -8,9 +8,15 @@
 
 import type { Clock } from '@ultimat3/core';
 import type { SignedUrlMethod, StorageDriver, StorageObject, StorageRead } from './driver';
-import { orgMismatch, signedUrlExpired, signedUrlRejected, tooLarge } from './errors';
+import {
+  orgMismatch,
+  signedUrlExpired,
+  signedUrlRejected,
+  signedUrlUnverifiable,
+  tooLarge,
+} from './errors';
 import { isTenantScoped, isWithinOrg } from './path';
-import type { SignedUrlConstraints } from './signed-url';
+import type { SignedUrlConstraints, SignedUrlVerification } from './signed-url';
 import { signedUrlBaseFor, verifySignedUrl } from './signed-url';
 import type { UploadPolicy } from './upload';
 import { normalizeContentType, uploadPolicy, validateUpload } from './upload';
@@ -18,11 +24,23 @@ import { normalizeContentType, uploadPolicy, validateUpload } from './upload';
 export interface SignedRequestInput {
   /** Absolute or route-relative — `verifySignedUrl` parses both. */
   readonly url: string;
-  readonly secret: string;
   /**
-   * Defaults to the base THIS disk signs under (`signedUrlBaseFor(disk.name)`), never to the bare
-   * mount prefix: a second default here made every URL `localDriver` mints a signature-mismatch,
-   * because the key parsed as `local/<key>`. Pass one only for a route mounted somewhere else.
+   * OPTIONAL since the disk can verify its own. It was required, and that requirement is why the
+   * upload half of `/_storage` has never been mounted: `localDriver` closes over the secret it
+   * mints with and exposes it through no member, so a route holding a `Storage` registry had no
+   * value to put here. A disk implementing `verifySigned()` needs none.
+   *
+   * Still honoured, and it still wins, for a caller that verifies a URL some OTHER disk signed —
+   * a migration between disks, a test signing by hand.
+   */
+  readonly secret?: string | undefined;
+  /**
+   * Defaults to the base THIS disk signs under (`disk.signedUrlBase`), never to the bare mount
+   * prefix: a second default here made every URL `localDriver` mints a signature-mismatch,
+   * because the key parsed as `local/<key>`. Read off the driver rather than re-derived from
+   * `disk.name`, which is the driver KIND — the segment is the registered disk name, and deriving
+   * it twice is what let both halves agree with each other and disagree with the mounted route.
+   * Pass one only for a route mounted somewhere else.
    */
   readonly baseUrl?: string | undefined;
   readonly disk: StorageDriver;
@@ -53,16 +71,33 @@ export interface AcceptSignedUploadInput extends SignedRequestInput {
  * the reason it exists is that a forged URL must never learn "the signature was fine, just late".
  * The org check runs on the verified key, so an attacker cannot probe org names with a fake one.
  */
+async function verify(input: SignedRequestInput): Promise<SignedUrlVerification> {
+  // An explicit secret first, so every call that shipped behaves exactly as it did — including
+  // one verifying a URL a DIFFERENT disk signed, which the driver could not answer for.
+  if (input.secret !== undefined && input.secret !== '') {
+    return verifySignedUrl({
+      url: input.url,
+      secret: input.secret,
+      baseUrl: input.baseUrl ?? input.disk.signedUrlBase ?? signedUrlBaseFor(input.disk.name),
+      ...(input.clock === undefined ? {} : { clock: input.clock }),
+    });
+  }
+  // The disk that signed it verifies it, holding the key it never hands out. `baseUrl` is the
+  // driver's own here for the same reason the secret is: both are the minting half's, and stating
+  // either one a second time is what made every `localDriver` URL a signature mismatch once.
+  const own = input.disk.verifySigned;
+  if (own === undefined) throw signedUrlUnverifiable(input.disk.name);
+  return own.call(input.disk, {
+    url: input.url,
+    ...(input.clock === undefined ? {} : { clock: input.clock }),
+  });
+}
+
 async function constraintsFor(
   input: SignedRequestInput,
   method: SignedUrlMethod,
 ): Promise<SignedUrlConstraints> {
-  const result = await verifySignedUrl({
-    url: input.url,
-    secret: input.secret,
-    baseUrl: input.baseUrl ?? signedUrlBaseFor(input.disk.name),
-    ...(input.clock === undefined ? {} : { clock: input.clock }),
-  });
+  const result = await verify(input);
   if (!result.ok) {
     throw result.reason === 'expired'
       ? signedUrlExpired(input.url, result.detail)

package/src/driver-local.ts

@@ -6,11 +6,11 @@
 import { type Clock, isLocal, resolveEnvironment, stringField, systemClock } from '@ultimat3/core';
 import {
   DEFAULT_CONTENT_TYPE,
-  DEFAULT_LIST_LIMIT,
   etagOf,
   type ListOptions,
   type ListPage,
   type PutOptions,
+  resolveListLimit,
   type SignedUrlOptions,
   type StorageBody,
   type StorageDriver,
@@ -29,7 +29,8 @@ import {
   storageNotImplemented,
 } from './errors';
 import { assertSafeKey, META_DIR } from './path';
-import { buildSignedUrl, signedUrlBaseFor } from './signed-url';
+import type { SignedUrlVerification } from './signed-url';
+import { buildSignedUrl, signedUrlBaseFor, verifySignedUrl } from './signed-url';
 import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
 
 const DRIVER_NAME = 'local';
@@ -130,7 +131,11 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
   const root = options.root.replace(/\/+$/, '');
   const maxPutBytes = options.maxPutBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
   const clock = options.clock ?? systemClock;
-  const baseUrl = options.baseUrl ?? signedUrlBaseFor(DRIVER_NAME);
+  // The segment is the disk's REGISTERED name, learned from `defineStorage` at boot — the driver
+  // kind is not a mount point, and minting under it made every disk not literally named `local`
+  // 404 its own URLs. An explicit `baseUrl` outranks the registration: that is the operator
+  // stating where the route is mounted, and inference must not overwrite a decision.
+  let baseUrl = options.baseUrl ?? signedUrlBaseFor(DRIVER_NAME);
   // 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
@@ -205,6 +210,15 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
   return {
     name: DRIVER_NAME,
 
+    /** A getter, not a captured string: `registerAs` runs after the driver is constructed. */
+    get signedUrlBase(): string {
+      return baseUrl;
+    },
+
+    registerAs(diskName: string): void {
+      if (options.baseUrl === undefined) baseUrl = signedUrlBaseFor(diskName);
+    },
+
     async put(key: string, body: StorageBody, putOptions?: PutOptions): Promise<StorageObject> {
       const safe = assertSafeKey(key);
       refuseUnsupportedPut(putOptions);
@@ -297,13 +311,27 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
 
     async list(listOptions?: ListOptions): Promise<ListPage> {
       const prefix = listOptions?.prefix ?? '';
-      const limit = listOptions?.limit ?? DEFAULT_LIST_LIMIT;
+      const limit = resolveListLimit(listOptions?.limit);
       const cursor = listOptions?.cursor;
       const keys: string[] = [];
       try {
-        for await (const entry of new Bun.Glob('**/*').scan({ cwd: root, onlyFiles: true })) {
+        // `dot: true`, and it is load-bearing: without it a glob matches no dot-prefixed entry, so
+        // every object whose key has one — `.hidden.txt`, `org/o1/pending/.x.png`, the
+        // `.metadata/a.json` `path.test.ts` pins as legal — was absent from the listing while
+        // `put`/`get`/`exists` handled it normally and the s3 listing returned it. `sweepOrphans`
+        // pages through `list()`, so those objects were swept as if they did not exist: a false
+        // erasure report by omission, which is what the classification below exists to prevent.
+        for await (const entry of new Bun.Glob('**/*').scan({
+          cwd: root,
+          onlyFiles: true,
+          dot: true,
+        })) {
           const key = entry.replaceAll('\\', '/');
-          if (key.startsWith(`${META_DIR}/`)) continue;
+          // The real filter now, not a second line of defence: the glob above yields the sidecar
+          // tree, and this is the one thing keeping `.meta/<key>.json` out of the object
+          // namespace. Folded like `assertSafeKey`'s reservation — `.META/` and `.meta/` are one
+          // directory on APFS and NTFS, and listing a key `get()` would refuse is the worse half.
+          if (key.toLowerCase().startsWith(`${META_DIR}/`)) continue;
           if (!key.startsWith(prefix)) continue;
           // The cursor IS the last key of the previous page — lexicographic order keeps it stable.
           if (cursor !== undefined && key <= cursor) continue;
@@ -332,6 +360,9 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
         if (object !== undefined) objects.push(object);
       }
       const truncated = keys.length > page.length;
+      // `limit` is a positive integer, so a truncated page always HAS a last key: the guard is the
+      // type's and not a second condition. It used to be one, and `limit: 0` fell through it —
+      // an empty page reported as complete over a disk that was not.
       const last = page.at(-1);
       return truncated && last !== undefined
         ? { objects, truncated, cursor: last }
@@ -350,5 +381,27 @@ export function localDriver(options: LocalDriverOptions): StorageDriver {
         clock,
       });
     },
+
+    /**
+     * The mint above, run backwards, on the same three values from the same closure: `secret`,
+     * `baseUrl` and `clock`. That is the whole reason it belongs here rather than in a caller — a
+     * route holding this disk can now accept an upload without ever being handed the key, and
+     * before this member existed there was no way for one to verify at all, which is why the
+     * shipped `PUT` half of `/_storage` was never mounted.
+     *
+     * Never throws: `verifySignedUrl` returns a reason, and `accept.ts` owns which reason becomes
+     * which error. A driver that decided that here would be a second error taxonomy.
+     */
+    async verifySigned(input: {
+      readonly url: string;
+      readonly clock?: Clock | undefined;
+    }): Promise<SignedUrlVerification> {
+      return verifySignedUrl({
+        url: input.url,
+        secret,
+        baseUrl,
+        clock: input.clock ?? clock,
+      });
+    },
   };
 }

package/src/driver-s3.ts

@@ -6,10 +6,10 @@
 import { ConfigInvalidError, EnvMissingError, stringField } from '@ultimat3/core';
 import {
   DEFAULT_CONTENT_TYPE,
-  DEFAULT_LIST_LIMIT,
   type ListOptions,
   type ListPage,
   type PutOptions,
+  resolveListLimit,
   type SignedUrlOptions,
   type StorageBody,
   type StorageDriver,
@@ -306,13 +306,16 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
 
     async list(listOptions?: ListOptions): Promise<ListPage> {
       const prefix = listOptions?.prefix ?? '';
+      // Refused at the seam both drivers share, before the provider is asked: `maxKeys: 0` used to
+      // go straight through, while the local disk answered a complete-looking empty page.
+      const maxKeys = resolveListLimit(listOptions?.limit);
       // `conn()` OUTSIDE the try: a missing credential or an absent `Bun.S3Client` is this disk
       // misconfigured, and it already answers with its own code and its own fix.
       const client = conn();
       let result: S3ListResultLike;
       try {
         result = await client.list({
-          maxKeys: listOptions?.limit ?? DEFAULT_LIST_LIMIT,
+          maxKeys,
           ...(listOptions?.prefix === undefined ? {} : { prefix: listOptions.prefix }),
           ...(listOptions?.cursor === undefined ? {} : { continuationToken: listOptions.cursor }),
         });

package/src/driver.ts

@@ -3,7 +3,10 @@
 // strings — a base64 round trip through JSON is how a "small" upload becomes a 33%-larger OOM —
 // and never unbounded, which is the same failure with the sender choosing the size.
 
+import type { Clock } from '@ultimat3/core';
+import { assert } from '@ultimat3/core';
 import { putTooLarge } from './errors';
+import type { SignedUrlVerification } from './signed-url';
 
 export type StorageBody = Uint8Array | ReadableStream<Uint8Array> | Blob;
 
@@ -97,6 +100,20 @@ export interface SignedUrlOptions {
 export interface StorageDriver {
   /** Disk-independent driver name (`local`, `s3`) — appears in every error cause. */
   readonly name: string;
+  /**
+   * The path prefix THIS disk's own signed URLs hang off, read by `accept.ts` so the minting half
+   * and the verifying half cannot state it twice. Undefined on a driver whose URLs are the
+   * provider's (`s3`), which this package never verifies.
+   */
+  readonly signedUrlBase?: string | undefined;
+  /**
+   * `defineStorage` tells the driver the key it was registered under, at boot, once. A driver that
+   * mints its own URLs hangs them off THAT, never off `name`: the mounted `/_storage/:disk/*key`
+   * route resolves the segment through the registry, so a disk registered as `uploads` whose URLs
+   * say `local` 404s every signature it just wrote. Optional — a driver with no URLs of its own
+   * (`s3`) needs none, and a third-party driver that ignores it keeps minting under `name`.
+   */
+  registerAs?(diskName: string): void;
   put(key: string, body: StorageBody, options?: PutOptions): Promise<StorageObject>;
   get(key: string): Promise<StorageRead>;
   /** Bytes without buffering — the only safe path for anything over a few MB. */
@@ -116,11 +133,54 @@ export interface StorageDriver {
   exists(key: string): Promise<boolean>;
   list(options?: ListOptions): Promise<ListPage>;
   signedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+  /**
+   * Verify a URL THIS disk minted — without surrendering the key it minted with.
+   *
+   * The other half of `signedUrlBase`, and it was missing for the whole life of the package.
+   * `signedUrlBase` is on this interface so the minting half and the verifying half cannot state
+   * the base twice; the SECRET is the same pair and stayed closed over inside `localDriver`, so
+   * `acceptSignedUpload` — whose `secret:` was required — was reachable from no route that held
+   * only a `Storage` registry. That is why the shipped upload path has no mounted `PUT`.
+   *
+   * Verification and not the secret, deliberately. A member that handed the key back would let any
+   * holder of a driver MINT a URL for any key, and would put it in every `JSON.stringify(disk)` a
+   * log or an error payload performs. A driver can answer "did I sign this?" without that.
+   *
+   * Optional, like `registerAs`: a disk whose URLs are the provider's (`s3`) verifies at the
+   * provider and never reaches this path, and a third-party driver that implements neither is
+   * refused by name (`X_STORAGE_URL_UNVERIFIABLE`) rather than reported as a bad signature.
+   */
+  verifySigned?(input: {
+    readonly url: string;
+    /** Overrides the driver's own, so a test's frozen clock still governs expiry. */
+    readonly clock?: Clock | undefined;
+  }): Promise<SignedUrlVerification>;
 }
 
 export const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
 export const DEFAULT_LIST_LIMIT = 1000;
 
+/**
+ * The page size a `list()` honours — refused rather than clamped when it cannot be one.
+ *
+ * At the `ListOptions` seam and not inside a driver, because the two answered a non-positive
+ * limit differently: the local disk sliced `[0, 0)` and then dropped its own `truncated` flag, so
+ * `list({ limit: 0 })` over a full disk reported a COMPLETE empty listing, while the s3 disk
+ * handed `maxKeys: 0` straight to the provider. `sweepOrphans` pages through `list()`, so a page
+ * that is empty and claims to be complete is a false erasure report — the same lie a swallowed
+ * listing error tells, one call to the left. A fraction is refused for `chunk()`'s reason: a
+ * `slice` truncates it, so the pages silently stop being the size that was asked for.
+ */
+export function resolveListLimit(limit: number | undefined): number {
+  if (limit === undefined) return DEFAULT_LIST_LIMIT;
+  assert(
+    Number.isSafeInteger(limit) && limit > 0,
+    `a list limit must be a positive integer, got ${String(limit)}: a page of zero objects cannot be told apart from a disk that has none`,
+    `pass a positive limit — disk.list({ limit: ${DEFAULT_LIST_LIMIT} }), or omit it and take DEFAULT_LIST_LIMIT`,
+  );
+  return limit;
+}
+
 /** What `toBytes` needs to refuse a body: the ceiling, and the key to name in the refusal. */
 export interface ByteLimit {
   readonly driver: string;

package/src/errors.ts

@@ -14,6 +14,7 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_CHECKSUM_MISMATCH',
   'X_STORAGE_URL_INVALID',
   'X_STORAGE_URL_EXPIRED',
+  'X_STORAGE_URL_UNVERIFIABLE',
   'X_STORAGE_ORG_MISMATCH',
   'X_STORAGE_UPLOAD_FAILED',
   'X_STORAGE_DELETE_FAILED',
@@ -48,6 +49,7 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_CHECKSUM_MISMATCH: 'bytes do not match the declared checksum',
   X_STORAGE_URL_INVALID: 'signed URL does not match its signature',
   X_STORAGE_URL_EXPIRED: 'signed URL is past its expiry',
+  X_STORAGE_URL_UNVERIFIABLE: 'no way to verify a signed URL for this disk',
   X_STORAGE_ORG_MISMATCH: 'object key belongs to another org',
   X_STORAGE_UPLOAD_FAILED: 'the signed upload was refused',
   X_STORAGE_DELETE_FAILED: 'the object could not be deleted',
@@ -300,6 +302,21 @@ export const uploadFailed = (path: string, status: number, detail: string): Stor
  * avatar grant becomes an unlimited upload of any type. Refused at construction, not at the
  * first `signedUrl()`: a process that cannot sign safely must not finish booting.
  */
+/**
+ * Neither half of the verification seam was available: no `secret:` in the call, and a disk that
+ * cannot verify what it signed. Its own condition rather than a signature failure, because the two
+ * need opposite edits — a mismatch is a forged or stale URL and this is a route that was never
+ * handed a way to check one, and reporting it as `X_STORAGE_URL_INVALID` sent an operator looking
+ * for an attacker.
+ */
+export const signedUrlUnverifiable = (diskName: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_URL_UNVERIFIABLE',
+    cause: `the "${diskName}" disk was asked to verify a signed URL with no secret in the call, and its driver implements no verifySigned()`,
+    fix: 'pass secret: to the call, or use a driver that signs its own URLs (localDriver) — a provider-signed disk (s3) verifies at the provider and never reaches this path',
+    meta: { disk: diskName },
+  });
+
 export const signingSecretMissing = (environment: string): StorageError =>
   new StorageError({
     code: 'X_ENV_MISSING',

package/src/index.ts

@@ -46,6 +46,9 @@ export {
   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';
@@ -84,6 +87,7 @@ export {
   StorageError,
   signedUrlExpired,
   signedUrlRejected,
+  signedUrlUnverifiable,
   signingSecretMissing,
   storageNotImplemented,
   tooLarge,

package/src/path.ts

@@ -40,7 +40,14 @@ function unsafeReason(key: string): string | undefined {
   if (key.startsWith('/')) return 'is absolute (leading "/")';
   if (ENCODED_SEPARATOR.test(key)) return 'contains a percent-encoded separator (%2e/%2f/%5c)';
   const segments = key.split('/');
-  if (segments[0] === META_DIR) return `starts with the reserved "${META_DIR}" segment`;
+  // Case-FOLDED, exactly as `isTenantScoped` folds and for the same filesystem: `.META/a.txt.json`
+  // and `.meta/a.txt.json` are one file on APFS and NTFS, so an exact-case reservation accepted a
+  // key that writes another object's sidecar — the whole attack this reservation closes, spelled
+  // with a shift key. The whole SEGMENT is compared, never a prefix of one: `.metadata/a.json` is
+  // an ordinary key and stays one.
+  if (segments[0]?.toLowerCase() === META_DIR) {
+    return `starts with the reserved "${META_DIR}" segment`;
+  }
   for (const segment of segments) {
     if (segment.length === 0) return 'contains an empty segment ("//" or a trailing "/")';
     if (segment === '.' || segment === '..') return `contains a "${segment}" segment`;

package/src/storage.ts

@@ -1,6 +1,8 @@
 // Single responsibility: named disks (Laravel's model) and the one module-level accessor.
 // Call sites name a disk, never a driver — swapping `local` for `s3` in app.config.ts must
-// not touch a single `storage.disk('uploads').put(...)` call.
+// not touch a single `storage.disk('uploads').put(...)` call. This file is also where a driver
+// LEARNS its disk name (`registerAs`), because the registry is the only holder of that fact and
+// a signed URL's `:disk` segment has to be the name the mounted route resolves.
 
 import { ConfigInvalidError } from '@ultimat3/core';
 import type { StorageDriver } from './driver';
@@ -40,12 +42,33 @@ export function defineStorage(config: StorageConfig): Storage {
       fix: `set storage.default to one of: ${names.join(', ')} in app.config.ts`,
     });
   }
+  // A Map, and the SAME own-keys read `names` above is built from. `config.disks[wanted]` walked
+  // the prototype chain, so `disk('constructor')` answered with the `Object` function and the next
+  // `.put()` was a bare `TypeError` inside app code — `diskUnknown` unreachable for `constructor`,
+  // `toString`, `valueOf`, `hasOwnProperty` and `__proto__`. One function was already answering
+  // one question two ways: `default: 'constructor'` is refused above, off `Object.keys`.
+  const disks = new Map(Object.entries(config.disks));
+  // One driver instance, one disk name. A driver told two names keeps the last, and every URL it
+  // minted under the first then resolves to a disk it is not — refused here rather than 404ing
+  // one alias at a time. Two disks over one root are two `localDriver()` calls.
+  const registered = new Map<StorageDriver, string>();
+  for (const [diskName, driver] of disks) {
+    const already = registered.get(driver);
+    if (already !== undefined) {
+      throw new ConfigInvalidError({
+        cause: `storage disks "${already}" and "${diskName}" are the same driver instance, and a driver can only mint URLs under one name`,
+        fix: `give "${diskName}" its own driver in app.config.ts: disks: { ${already}: localDriver({ root: '.storage/${already}' }), ${diskName}: localDriver({ root: '.storage/${diskName}' }) }`,
+      });
+    }
+    registered.set(driver, diskName);
+    driver.registerAs?.(diskName);
+  }
   const storageInstance: Storage = {
     defaultDisk,
     diskNames: Object.freeze([...names]),
     disk(name?: string): StorageDriver {
       const wanted = name ?? defaultDisk;
-      const driver = config.disks[wanted];
+      const driver = disks.get(wanted);
       if (driver === undefined) throw diskUnknown(wanted, names);
       return driver;
     },

package/src/upload.ts

@@ -136,16 +136,19 @@ export function sniffContentType(bytes: Uint8Array): string | undefined {
   return sniffText(bytes);
 }
 
-const ALIASES: Readonly<Record<string, string>> = {
-  'image/jpg': 'image/jpeg',
-  'image/x-png': 'image/png',
-  'application/x-pdf': 'application/pdf',
-};
+// A `Map`, not an object literal: `base` is the transport's own `Content-Type` header by the time
+// `acceptSignedUpload` reaches here, and `ALIASES['constructor']` on an object answers the `Object`
+// FUNCTION through a `: string` signature — which the refusal below then rendered as its `cause`.
+const ALIASES: ReadonlyMap<string, string> = new Map([
+  ['image/jpg', 'image/jpeg'],
+  ['image/x-png', 'image/png'],
+  ['application/x-pdf', 'application/pdf'],
+]);
 
 /** Strip parameters and case: `IMAGE/PNG; charset=binary` and `image/png` are one type. */
 export function normalizeContentType(value: string): string {
   const base = (value.split(';')[0] ?? '').trim().toLowerCase();
-  return ALIASES[base] ?? base;
+  return ALIASES.get(base) ?? base;
 }
 
 const ZIP_CONTAINERS = new Set<string>([...DOCUMENT_CONTENT_TYPES, 'application/epub+zip']);
@@ -167,7 +170,11 @@ export function contentTypeMatches(declared: string, sniffed: string): boolean {
   return false;
 }
 
-/** Throws the first violated constraint. Order is cheapest-first: size, key, type, checksum. */
+/**
+ * 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
+ * constraint a rejected upload reports is what the client retries on — `upload.test.ts` pins it.
+ */
 export function validateUpload(
   candidate: UploadCandidate,
   policy: UploadPolicy = uploadPolicy(),