@ultimat3/storage 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -157,6 +157,23 @@ 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
+  `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.**
+  `isWithinOrg` alone refused every un-scoped key, so an app's own `brand/logo.png` was unreachable
+  through a URL it had just signed. `isTenantScoped` is case-INSENSITIVE and `isWithinOrg` is not:
+  `Org/o2/x` and `org/o2/x` are one file on APFS/NTFS, so the fold has to count as tenant-scoped
+  and then fail the exact-case membership test. Do not "simplify" either half.
+- **`AcceptSignedUploadInput.checksum` is what makes `uploadPolicy({ requireChecksum: true })`
+  reachable.** Without it that option could only ever fail, because nothing on the accept path
+  could declare a hash. It travels like `declaredContentType`: the route reads a header and hands
+  it over, and `validateUpload` hashes the bytes itself. The browser half does NOT send one — a
+  custom header on an S3 presigned PUT is a signature question this package cannot answer.
 - `orgId` is required on both halves of `accept.ts` and is the ACTOR's, never a request field. A
   signed URL is a capability; a leaked capability must still not cross a tenant.
 - `X_STORAGE_ORG_MISMATCH` maps to **404**, not 403 (`@ultimat3/http`'s `error-map.ts`). 403 would

package/README.md

@@ -89,7 +89,9 @@ fixing was built wrong.
 `scopedKey('org-1', 'avatars', 'a.png')` is `org/org-1/avatars/a.png`; guard every
 client-supplied key with `isWithinOrg(key, ctx.actor.orgId)`. A surface that serves objects pairs
 it with `isTenantScoped(key)`: only a key already inside `org/` is another tenant's to refuse, so
-`disk().put('brand/logo.png', …)` stays reachable while `org/org-2/…` never is.
+`disk().put('brand/logo.png', …)` stays reachable while `org/org-2/…` never is. `accept.ts` asks
+the pair too. `isTenantScoped` folds case (`Org/`, `ORG/`) and `isWithinOrg` does not, so a
+case-variant prefix — one directory, not two, on APFS or NTFS — is refused rather than matched.
 
 ## Signed URLs
 
@@ -144,8 +146,10 @@ 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, secret, baseUrl: '/_storage/local',
-  disk: disk('uploads'), orgId: ctx.actor.orgId,
+  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>.
+  orgId: ctx.actor.orgId,
   bytes, declaredContentType: request.headers.get('content-type') ?? undefined,
   policy: uploadPolicy({ maxBytes: 5e6 }),
 });
@@ -154,7 +158,12 @@ const object = await acceptSignedUpload({
 `acceptSignedUpload` refuses on any of: a signature that does not verify, an expired grant, a
 `PUT` grant replayed as a `GET`, a key outside the actor's org, more bytes than the signature
 granted, a `Content-Type` the signature does not cover, or magic bytes that contradict it.
-`readSignedObject` is the GET half and applies the same verification and the same org check.
+`readSignedObject` is the GET half and applies the same verification and the same org check —
+which is the `isTenantScoped`/`isWithinOrg` pair, so an app's own un-scoped `brand/logo.png` is
+readable through a URL it signed and `org/org-2/…` still is not.
+`uploadPolicy({ requireChecksum: true })` needs the request's declared hash, which travels as
+`checksum` exactly as the content type travels as `declaredContentType`: a header the route reads
+and hands over, hashed again here and refused on any disagreement.
 Neither owns a `Request`, a `Response` or a status number — mounting is the host's job, and
 `@ultimat3/http` is the only layer that turns an `X_*` code into a status.
 

package/package.json

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

package/src/accept.ts

@@ -9,9 +9,9 @@
 import type { Clock } from '@ultimat3/core';
 import type { SignedUrlMethod, StorageDriver, StorageObject, StorageRead } from './driver';
 import { orgMismatch, signedUrlExpired, signedUrlRejected, tooLarge } from './errors';
-import { isWithinOrg } from './path';
+import { isTenantScoped, isWithinOrg } from './path';
 import type { SignedUrlConstraints } from './signed-url';
-import { verifySignedUrl } from './signed-url';
+import { signedUrlBaseFor, verifySignedUrl } from './signed-url';
 import type { UploadPolicy } from './upload';
 import { normalizeContentType, uploadPolicy, validateUpload } from './upload';
 
@@ -19,6 +19,11 @@ 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.
+   */
   readonly baseUrl?: string | undefined;
   readonly disk: StorageDriver;
   /**
@@ -33,6 +38,13 @@ export interface AcceptSignedUploadInput extends SignedRequestInput {
   readonly bytes: Uint8Array;
   /** The transport's `Content-Type`. Refused unless it equals the type the grant signed. */
   readonly declaredContentType?: string | undefined;
+  /**
+   * The transport's declared base64 SHA-256, travelling exactly as `declaredContentType` does: a
+   * header the route reads and hands over, trusted for nothing — the bytes are hashed here and a
+   * disagreement is refused. Without this field `uploadPolicy({ requireChecksum: true })` could
+   * only ever fail, since nothing on this path could ever declare one.
+   */
+  readonly checksum?: string | undefined;
   readonly policy?: UploadPolicy | undefined;
 }
 
@@ -48,7 +60,7 @@ async function constraintsFor(
   const result = await verifySignedUrl({
     url: input.url,
     secret: input.secret,
-    ...(input.baseUrl === undefined ? {} : { baseUrl: input.baseUrl }),
+    baseUrl: input.baseUrl ?? signedUrlBaseFor(input.disk.name),
     ...(input.clock === undefined ? {} : { clock: input.clock }),
   });
   if (!result.ok) {
@@ -63,8 +75,15 @@ async function constraintsFor(
       `the URL is signed for ${constraints.method}, and this is a ${method}`,
     );
   }
-  if (!isWithinOrg(constraints.key, input.orgId)) {
-    throw orgMismatch(constraints.key, input.orgId);
+  // The PAIR is the question "does this key belong to somebody else?". `isWithinOrg` alone
+  // answered `false` for every un-scoped key, so an app's own `brand/logo.png` was unreachable
+  // through a URL it had just signed — `path.ts` says so and `dev-storage.ts` already asks it this
+  // way. An actor with no org is inside no org, so every tenant-scoped key is somebody else's;
+  // checked here because `isWithinOrg` reads an empty org as a malformed key and would blame the
+  // URL for the actor's missing claim.
+  const orgId = input.orgId;
+  if (isTenantScoped(constraints.key) && (orgId === '' || !isWithinOrg(constraints.key, orgId))) {
+    throw orgMismatch(constraints.key, orgId);
   }
   return constraints;
 }
@@ -106,7 +125,12 @@ export async function acceptSignedUpload(input: AcceptSignedUploadInput): Promis
 
   const policy = input.policy ?? uploadPolicy();
   const validated = validateUpload(
-    { key, declaredContentType: signed, bytes: input.bytes },
+    {
+      key,
+      declaredContentType: signed,
+      bytes: input.bytes,
+      ...(input.checksum === undefined ? {} : { checksum: input.checksum }),
+    },
     policy,
   );
   return input.disk.put(validated.key, validated.bytes, {

package/src/driver-local.ts

@@ -29,7 +29,7 @@ import {
   storageNotImplemented,
 } from './errors';
 import { assertSafeKey, META_DIR } from './path';
-import { buildSignedUrl } from './signed-url';
+import { buildSignedUrl, signedUrlBaseFor } from './signed-url';
 import { DEFAULT_MAX_UPLOAD_BYTES } from './upload';
 
 const DRIVER_NAME = 'local';
@@ -130,7 +130,7 @@ 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 ?? `/_storage/${DRIVER_NAME}`;
+  const 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

package/src/index.ts

@@ -141,6 +141,7 @@ export {
   SIGNED_URL_PARAMS,
   SIGNED_URL_VERSION,
   signConstraints,
+  signedUrlBaseFor,
   timingSafeEqual,
   verifySignedUrl,
 } from './signed-url';

package/src/path.ts

@@ -102,9 +102,15 @@ export function isWithinOrg(key: string, orgId: string): boolean {
  * two apart: `isWithinOrg` alone would answer `false` for every un-scoped key and make an app's
  * own shared assets unreachable, and dropping the check would make one tenant's prefix readable
  * by another. The pair is the question "does this key belong to somebody else?".
+ *
+ * Case-INSENSITIVE, and that is the load-bearing half: `Org/o2/a.png` and `org/o2/a.png` are one
+ * file on a case-insensitive filesystem (APFS, NTFS), so an exact-case test would answer "not a
+ * tenant's" for a key that reads another tenant's bytes on every macOS dev disk. `isWithinOrg` is
+ * exact-case and stays so, so a folded prefix is refused outright rather than matched — `org/` is
+ * the only spelling `scopedKey` mints, so nothing legitimate arrives in any other.
  */
 export function isTenantScoped(key: string): boolean {
-  return key.startsWith(`${ORG_PREFIX}/`);
+  return key.slice(0, ORG_PREFIX.length + 1).toLowerCase() === `${ORG_PREFIX}/`;
 }
 
 /** `org/o1/a/b.png` -> `org/o1/a`. Empty for a top-level key. */

package/src/signed-url.ts

@@ -17,6 +17,17 @@ 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';
 
+/**
+ * The base ONE disk's own URLs hang off: the mount prefix plus the driver's name, because the
+ * mounted route is `${DEFAULT_SIGNED_URL_BASE}/:disk/*key` and the disk segment is inside the
+ * path the HMAC is recovered from. Declared once and called by both halves — the driver that
+ * mints and `accept.ts` that verifies — because a base stated twice is a base that drifts, and a
+ * drifted base makes every genuine URL a `signature-mismatch`: the key parses as `local/<key>`.
+ */
+export function signedUrlBaseFor(driverName: string): string {
+  return `${DEFAULT_SIGNED_URL_BASE}/${driverName}`;
+}
+
 export const SIGNED_URL_PARAMS = {
   method: 'x-method',
   expires: 'x-exp',