@ultimat3/storage 15.0.0 → 17.0.0

package/CLAUDE.md

@@ -14,6 +14,33 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
   fits the table is `@ultimat3/auth`'s: ship the server function (`grantUpload`), let the app
   wrap it in its own `action()` with its own policy. See `docs/architecture/17-uploads.md`.
 
+- **Every byte ceiling and every TTL is screened where it is DECLARED, through core's
+  `finiteCount` and nothing else, `As of 2026-08-26`** — `uploadPolicy({ maxBytes })`, both
+  drivers' `maxPutBytes`, `createUploadGrant({ expiresInMs })`, `buildSignedUrl`'s two and the s3
+  driver's presign TTL. There was briefly a private `assertFiniteSignedUrlBound` here saying the
+  same thing in its own words; a second finite-bound path is one that drifts from the shared
+  contract, which is exactly what `jobs`, `realtime` and `query` each proved with a copy of their
+  own. Both presigners now call the one function, which is what `driver-parity.test.ts` needs to
+  stay true.
+  Measured: `uploadPolicy({ maxBytes: Number.NaN })` accepted a 5,000,016-byte PNG through
+  `validateUpload`, because `size > NaN` is false — the one number deciding how much a caller may
+  store stopped deciding anything. Variant `quality` is core's `assertFiniteImageQuality` and NOT a
+  second screen: `variantKey` never reaches the encoder, so a copy that disagreed would mint
+  `q150` keys for bytes `transformImageBytes` then refuses.
+- **The default is taken on `undefined` and on nothing else, `As of 2026-08-26`** —
+  `options.x === undefined ? D : options.x`, never `options.x ?? D`. `??` coalesces on `null` too,
+  so an explicitly blanked key in a decoded JSON config took the default BEFORE the screen above
+  could refuse it: the mirror of the `NaN` half, where one value slips past the guard and the other
+  past the default, and both end in a bound nobody chose. Every site above, `quality` included.
+
+- **`MAX_KEY_LENGTH` is BYTES, and is measured in bytes, `As of 2026-08-26`.** S3's limit is "a
+  sequence of Unicode characters whose UTF-8 encoding is at most 1,024 bytes long", and `path.ts`
+  measured `key.length` — UTF-16 code units — while its message said "chars". A code-unit count is
+  never MORE than the UTF-8 byte count, so a non-ASCII key over the real limit passed this guard
+  and was refused by the store instead: 400 CJK characters is 400 units and 1,200 bytes. Keeping
+  local and remote disks interchangeable is the whole reason the ceiling exists, so it has to be
+  the store's ceiling. Same defect and same fix as `@ultimat3/cache`'s surrogate-key guard.
+
 | Rule | |
 |---|---|
 | Errors | `StorageError` + one factory per code in `errors.ts`; never `throw new Error` |
@@ -162,8 +189,11 @@ Gotchas:
   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.
+  process.env`, so a bare `localDriver({ root })` is unchanged and additive.
+  `driver-local-boot.test.ts` pins it by mutation — reverting any one read to `process.env` fails.
+  That file is the CONSTRUCTION half, split off `driver-local.test.ts` at the line ceiling along
+  the seam the guard already draws: nothing in it writes a byte, so it needs no temporary
+  directory, and `driver-local.test.ts` keeps everything the disk actually does with an object.
 - **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/package.json

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

package/src/driver-local.ts

@@ -5,6 +5,7 @@
 
 import {
   type Clock,
+  finiteCount,
   isLocal,
   type ResolveEnvironmentOptions,
   resolveEnvironment,
@@ -159,7 +160,14 @@ const isMissingFile = (error: unknown): boolean => stringField(error, 'code') ==
 
 export function localDriver(options: LocalDriverOptions): StorageDriver {
   const root = options.root.replace(/\/+$/, '');
-  const maxPutBytes = options.maxPutBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
+  // `=== undefined`, never `??`: `??` coalesces on `null` too, so an explicitly blanked key in a
+  // decoded JSON config took the default instead of the refusal `finiteCount` is here to raise.
+  const maxPutBytes = finiteCount(
+    'the local disk driver',
+    'maxPutBytes',
+    options.maxPutBytes === undefined ? DEFAULT_MAX_UPLOAD_BYTES : options.maxPutBytes,
+    1,
+  );
   const clock = options.clock ?? systemClock;
   // 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`

package/src/driver-s3.ts

@@ -3,7 +3,7 @@
 // The client is built lazily on first use so importing this module never opens a socket, and
 // credentials arrive as env var NAMES: a literal key in app.config.ts is a key in git.
 
-import { ConfigInvalidError, EnvMissingError, stringField } from '@ultimat3/core';
+import { ConfigInvalidError, EnvMissingError, finiteCount, stringField } from '@ultimat3/core';
 import {
   DEFAULT_CONTENT_TYPE,
   type ListOptions,
@@ -27,6 +27,7 @@ import {
   storageNotImplemented,
 } from './errors';
 import { assertSafeKey } from './path';
+import { DEFAULT_SIGNED_URL_TTL_MS } from './signed-url';
 import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
 
 const DRIVER_NAME = 's3';
@@ -209,7 +210,14 @@ function refuseUnsupportedPut(bucket: string, key: string, putOptions?: PutOptio
 }
 
 export function s3Driver(options: S3DriverOptions): StorageDriver {
-  const maxPutBytes = options.maxPutBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
+  // `=== undefined`, never `??`: `??` coalesces on `null` too, so an explicitly blanked key in a
+  // decoded JSON config took the default instead of the refusal `finiteCount` is here to raise.
+  const maxPutBytes = finiteCount(
+    'the s3 driver',
+    'maxPutBytes',
+    options.maxPutBytes === undefined ? DEFAULT_MAX_UPLOAD_BYTES : options.maxPutBytes,
+    1,
+  );
   let client: S3ClientLike | undefined;
   const conn = (): S3ClientLike => {
     client ??= buildClient(options);
@@ -356,7 +364,17 @@ export function s3Driver(options: S3DriverOptions): StorageDriver {
      * `maxBytes` — S3 has no header for it, so size stays a server-side policy check.
      */
     async signedUrl(key: string, urlOptions?: SignedUrlOptions): Promise<string> {
-      const expiresInMs = urlOptions?.expiresInMs ?? 900_000;
+      // Screened with the SAME function `buildSignedUrl` applies on the local disk — one
+      // finite-bound path for both presigners, never a private copy per package: `Math.ceil(NaN /
+      // 1000)` is `NaN`, so `X-Amz-Expires=NaN` went to AWS and the app got a 403 on a link it
+      // believed it had just minted. `=== undefined` rather than `??`, so an explicit `null` is
+      // refused instead of silently taking the default.
+      const expiresInMs = finiteCount(
+        'the s3 driver',
+        'expiresInMs',
+        urlOptions?.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : urlOptions.expiresInMs,
+        1,
+      );
       return conn()
         .file(assertSafeKey(key))
         .presign({

package/src/grant.ts

@@ -5,7 +5,7 @@
 // only client input that survives is the filename's extension, and only if it survives a regex.
 
 import type { Clock } from '@ultimat3/core';
-import { systemClock } from '@ultimat3/core';
+import { finiteCount, systemClock } from '@ultimat3/core';
 import type { AttachmentTarget } from './attachment';
 import { attachmentKey, pendingKey, quarantineKey, uploadName } from './attachment';
 import type { StorageDriver } from './driver';
@@ -82,7 +82,17 @@ export async function grantUpload(input: GrantUploadInput): Promise<UploadGrant>
     throw tooLarge(key, size, policy.maxBytes);
   }
 
-  const expiresInMs = input.expiresInMs ?? DEFAULT_SIGNED_URL_TTL_MS;
+  // 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
+  // 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',
+    'expiresInMs',
+    input.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : input.expiresInMs,
+    1,
+  );
   const url = await input.disk.signedUrl(key, {
     method: 'PUT',
     maxBytes: policy.maxBytes,

package/src/image.ts

@@ -4,6 +4,7 @@
 // bytes, `transformImage()` returns exactly the size `fitDimensions()` already promised.
 
 import {
+  assertFiniteImageQuality,
   blurDataUrl,
   type ImageFormat,
   imageUnsupported,
@@ -90,7 +91,14 @@ export function variantKey(sourceKey: string, transform: ImageTransform): string
   if (transform.width !== undefined) parts.push(`w${transform.width}`);
   if (transform.height !== undefined) parts.push(`h${transform.height}`);
   if (transform.fit !== undefined) parts.push(transform.fit);
-  const quality = transform.quality ?? DEFAULT_QUALITY;
+  // Core's screen, not a second one: this function never reaches the encoder, so without it a
+  // `q150` or a `qNaN` variant key is minted for bytes `transformImageBytes` then refuses — and
+  // an unbounded quality is an unbounded number of distinct keys in the bucket.
+  // `=== undefined`, never `??`: `??` coalesces on `null` too, so an explicit one was spelled
+  // into a key as the default rather than refused.
+  const quality = assertFiniteImageQuality(
+    transform.quality === undefined ? DEFAULT_QUALITY : transform.quality,
+  );
   if (quality !== DEFAULT_QUALITY) parts.push(`q${quality}`);
   if (parts.length === 0) parts.push('full');
   return assertSafeKey(`${stem}@${parts.join('-')}.${FORMAT_EXTENSIONS[format]}`);
@@ -173,7 +181,9 @@ export async function transformImage(
     // what stops a rounded edge leaving a transparent (in JPEG: black) sliver inside it.
     fit: 'cover',
     format: transform.format ?? 'webp',
-    quality: transform.quality ?? DEFAULT_QUALITY,
+    quality: assertFiniteImageQuality(
+      transform.quality === undefined ? DEFAULT_QUALITY : transform.quality,
+    ),
   });
 }
 

package/src/path.ts

@@ -5,8 +5,19 @@
 
 import { pathUnsafe } from './errors';
 
-/** S3's own limit; keeping local and remote disks interchangeable requires the same ceiling. */
+/**
+ * S3's own limit; keeping local and remote disks interchangeable requires the same ceiling.
+ *
+ * BYTES, and S3 says so — "a sequence of Unicode characters whose UTF-8 encoding is at most 1,024
+ * bytes long". It was measured with `String.length`, which is UTF-16 code units, and a code-unit
+ * count is never MORE than the UTF-8 byte count — so every non-ASCII key over the real limit
+ * passed this guard and was refused by the store instead, which is the one thing a shared ceiling
+ * exists to prevent. `MAX_KEY_LENGTH` keeps its name: it is exported, and the number is unchanged.
+ */
 export const MAX_KEY_LENGTH = 1024;
+
+/** What the wire counts. The key is at most ~1 KB, so this is cheaper than deciding not to. */
+const utf8Bytes = (value: string): number => new TextEncoder().encode(value).byteLength;
 export const ORG_PREFIX = 'org';
 
 /**
@@ -32,8 +43,9 @@ function hasControlByte(key: string): boolean {
 
 function unsafeReason(key: string): string | undefined {
   if (key.length === 0) return 'is empty';
-  if (key.length > MAX_KEY_LENGTH) {
-    return `is ${key.length} chars, over the ${MAX_KEY_LENGTH} limit`;
+  const bytes = utf8Bytes(key);
+  if (bytes > MAX_KEY_LENGTH) {
+    return `is ${bytes} bytes, over the ${MAX_KEY_LENGTH}-byte limit`;
   }
   if (hasControlByte(key)) return 'contains a NUL or control byte';
   if (key.includes('\\')) return 'contains a backslash';

package/src/signed-url.ts

@@ -4,7 +4,7 @@
 // a 2GB executable. Verification never throws and never short-circuits on expiry before the
 // signature, so a forged URL can never learn "the signature was fine, just late".
 
-import { type Clock, systemClock, timingSafeEqual } from '@ultimat3/core';
+import { type Clock, finiteCount, systemClock, timingSafeEqual } from '@ultimat3/core';
 import type { SignedUrlMethod } from './driver';
 import { assertSafeKey, isSafeKey } from './path';
 
@@ -102,13 +102,36 @@ export async function signConstraints(
 const trimBase = (base: string): string => base.replace(/\/+$/, '');
 const encodeKey = (key: string): string => key.split('/').map(encodeURIComponent).join('/');
 
+/**
+ * The mint's side of the screen `parseConstraints` already applies to the read. `finiteCount` from
+ * `@ultimat3/core` is that screen — a private copy of it lived here, and a second finite-bound path
+ * is one that drifts from the shared contract, which is what `jobs`, `realtime` and `query` each
+ * proved with a byte-identical copy of their own. The S3 driver calls the same function directly,
+ * because it presigns through the provider rather than through this one, and two presigners that
+ * refuse different inputs is the disagreement `driver-parity.test.ts` exists to catch.
+ *
+ * A URL is minted here and verified elsewhere, so a number this function writes and that one
+ * refuses is a link that is dead on arrival — the app's own call succeeded, and the only report is
+ * a 400 at a recipient who cannot fix it. `expiresInMs: NaN` is exactly that: `now + NaN` is
+ * `NaN`, `String` writes the literal `NaN` into `x-exp`, and `Number.isSafeInteger` on the other
+ * side says no.
+ */
 export async function buildSignedUrl(input: SignedUrlInput): Promise<string> {
   const key = assertSafeKey(input.key);
   const clock = input.clock ?? systemClock;
+  // `=== undefined`, never `??`: `??` coalesces on `null` too, so an explicit `null` would take
+  // the default instead of the refusal `finiteCount` is here to raise.
+  const expiresInMs = finiteCount(
+    'buildSignedUrl',
+    'expiresInMs',
+    input.expiresInMs === undefined ? DEFAULT_SIGNED_URL_TTL_MS : input.expiresInMs,
+    1,
+  );
+  if (input.maxBytes !== undefined) finiteCount('buildSignedUrl', 'maxBytes', input.maxBytes, 0);
   const constraints: SignedUrlConstraints = {
     key,
     method: input.method ?? 'GET',
-    expiresAt: clock.now().getTime() + (input.expiresInMs ?? DEFAULT_SIGNED_URL_TTL_MS),
+    expiresAt: clock.now().getTime() + expiresInMs,
     maxBytes: input.maxBytes,
     // An empty string is not a content type, and `canonicalRequest` renders it and `undefined`
     // identically — so minting one would produce a URL indistinguishable from an unconstrained

package/src/upload.ts

@@ -4,6 +4,7 @@
 // is a stored-XSS delivery vehicle the moment any surface serves it back with the declared
 // type, so the magic bytes decide and a contradiction is rejected outright.
 
+import { finiteCount } from '@ultimat3/core';
 import { sha256Base64 } from './driver';
 import { checksumMismatch, contentTypeMismatch, contentTypeNotAllowed, tooLarge } from './errors';
 import { assertSafeKey } from './path';
@@ -43,7 +44,18 @@ export interface UploadPolicyInit {
 
 export function uploadPolicy(init: UploadPolicyInit = {}): UploadPolicy {
   return {
-    maxBytes: init.maxBytes ?? DEFAULT_MAX_UPLOAD_BYTES,
+    // Screened where it is DECLARED, because every reader of it is a comparison: `size >
+    // policy.maxBytes` is false for a `NaN` ceiling, so the cap that decides how much a caller may
+    // store stops deciding anything. Measured: a 5,000,016-byte PNG passed `validateUpload` under
+    // `uploadPolicy({ maxBytes: Number.NaN })`.
+    // `=== undefined`, never `??`: `??` coalesces on `null` too, so an explicitly blanked key in
+    // a decoded JSON config took the default instead of the refusal beside it.
+    maxBytes: finiteCount(
+      'uploadPolicy',
+      'maxBytes',
+      init.maxBytes === undefined ? DEFAULT_MAX_UPLOAD_BYTES : init.maxBytes,
+      1,
+    ),
     allowedContentTypes: init.allowedContentTypes ?? IMAGE_CONTENT_TYPES,
     requireChecksum: init.requireChecksum ?? false,
   };