@ultimat3/storage 26.1.1 → 27.1.0

package/README.md

@@ -11,6 +11,7 @@ defineStorage({
     media: s3Driver({ bucket: 'media', endpoint: process.env.S3_ENDPOINT, forcePathStyle: true }),
   },
   default: 'uploads', // omit and the first disk wins
+  shared: { media: ['brand/'] }, // the only un-scoped keys /_storage and /media serve (27.0.0)
 });
 
 await disk('media').put(scopedKey(orgId, 'avatars', 'a.png'), bytes, { contentType: 'image/png' });
@@ -18,6 +19,10 @@ await disk('media').put(scopedKey(orgId, 'avatars', 'a.png'), bytes, { contentTy
 
 Swapping `local` for `s3` in `app.config.ts` changes no call site. `x dev` needs no S3 server.
 
+`shared` is per disk, whole segments ending in `/`, never inside `org/` (`X_CONFIG_INVALID` at
+boot). A key outside every `org/<id>/` prefix and every shared prefix is refused by the served
+read routes with `X_STORAGE_KEY_UNSHARED` (404); `storage.isShared(disk, key)` is the question.
+
 ## Drivers
 
 | Driver | Backing | For | Signed URLs |

package/package.json

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

package/src/errors.ts

@@ -30,6 +30,7 @@ export const STORAGE_OWNED_ERROR_CODES = [
   'X_STORAGE_PUT_FAILED',
   'X_STORAGE_READ_FAILED',
   'X_STORAGE_OBJECT_LOCKED',
+  'X_STORAGE_KEY_UNSHARED',
 ] as const;
 
 /**
@@ -70,6 +71,7 @@ export const STORAGE_ERROR_TITLES: Readonly<Record<StorageOwnedErrorCode, string
   X_STORAGE_PUT_FAILED: 'the object could not be written',
   X_STORAGE_READ_FAILED: 'the object could not be read',
   X_STORAGE_OBJECT_LOCKED: 'the object is under retention or a legal hold',
+  X_STORAGE_KEY_UNSHARED: 'object key is outside every tenant and every shared prefix',
 };
 
 // One unconditional call, so a second package claiming one of storage's codes throws
@@ -429,6 +431,21 @@ export const orgMismatch = (key: string, orgId: string): StorageError =>
     meta: { key, orgId },
   });
 
+/**
+ * A served read of a key no tenant owns and no `defineStorage({ shared })` prefix covers. 404 for
+ * the reason `orgMismatch` is: the refusal is decided from the key alone, before any disk is read,
+ * so it says nothing about whether an object is there.
+ */
+export const keyUnshared = (disk: string, key: string): StorageError =>
+  new StorageError({
+    code: 'X_STORAGE_KEY_UNSHARED',
+    cause: `key "${key}" on disk "${disk}" is outside every org/<id>/ prefix and every prefix defineStorage({ shared }) lists for "${disk}"`,
+    // Never derived from the refused key: its own top segment is often the very data the refusal
+    // protects (`db-export/`), and a fix line is pasted as written.
+    fix: `scopedKey(orgId, ...parts)   # a tenant's object; for one EVERY reader may have, list a prefix you choose: defineStorage({ disks, shared: { ${disk}: ['brand/'] } })`,
+    meta: { disk, key },
+  });
+
 /** The client half: the disk answered the presigned PUT with something other than 2xx. */
 export const uploadFailed = (path: string, status: number, detail: string): StorageError =>
   new StorageError({

package/src/index.ts

@@ -77,6 +77,7 @@ export {
   getTooLarge,
   isStorageError,
   keyConflict,
+  keyUnshared,
   listFailed,
   objectNotFound,
   orgMismatch,

package/src/storage.ts

@@ -7,17 +7,66 @@
 import { ConfigInvalidError } from '@ultimat3/core';
 import type { StorageDriver } from './driver';
 import { diskUnknown } from './errors';
+import { isSafeKey, isTenantScoped } from './path';
 
 export interface StorageConfig {
   readonly disks: Readonly<Record<string, StorageDriver>>;
   /** Disk used when `disk()` is called with no name. Defaults to the first declared disk. */
   readonly default?: string | undefined;
+  /**
+   * Key prefixes, per disk, that hold objects NO tenant owns and every reader may have — a brand
+   * logo, a shared asset. The only way a key outside `org/<id>/` is served by `/_storage` and
+   * `/media` (still to a signed-in actor holding `storage:read`); everything else outside a
+   * tenant prefix — exports, raw payloads, DSR archives — is refused `X_STORAGE_KEY_UNSHARED`.
+   * Each prefix ends in `/` and names a whole segment: `{ uploads: ['brand/'] }`.
+   */
+  readonly shared?: Readonly<Record<string, readonly string[]>> | undefined;
 }
 
 export interface Storage {
   readonly defaultDisk: string;
   readonly diskNames: readonly string[];
   disk(name?: string): StorageDriver;
+  /**
+   * Whether `key` on `disk` lies under a prefix `StorageConfig.shared` declared for that disk. A
+   * tenant-scoped key is never shared, and an unknown disk shares nothing.
+   */
+  isShared(disk: string, key: string): boolean;
+}
+
+/**
+ * The declared prefixes, refused at boot when one could never mean what it says: a disk that is
+ * not declared, a prefix that is not a whole segment, one that would share the whole disk, or one
+ * inside the tenant namespace — sharing `org/` would undo the boundary the prefix exists beside.
+ */
+function sharedPrefixes(
+  shared: StorageConfig['shared'],
+  names: readonly string[],
+): ReadonlyMap<string, readonly string[]> {
+  const out = new Map<string, readonly string[]>();
+  for (const [diskName, prefixes] of Object.entries(shared ?? {})) {
+    if (!names.includes(diskName)) {
+      throw new ConfigInvalidError({
+        cause: `storage.shared names disk "${diskName}" but the configured disks are: ${names.join(', ')}`,
+        fix: `defineStorage({ disks, shared: { ${names[0] ?? '<disk>'}: ['<prefix>/'] } })   # key it by one of: ${names.join(', ')}`,
+      });
+    }
+    for (const prefix of prefixes) {
+      const shareable =
+        typeof prefix === 'string' &&
+        prefix.endsWith('/') &&
+        isSafeKey(prefix.slice(0, -1)) &&
+        !isTenantScoped(prefix);
+      if (!shareable) {
+        throw new ConfigInvalidError({
+          cause: `storage.shared.${diskName} lists ${JSON.stringify(prefix)}, which is not a shareable prefix: it must be a relative key ending in "/" and outside "org/"`,
+          fix: `defineStorage({ disks, shared: { ${diskName}: ['brand/'] } })   # whole segments ending in "/", outside org/ — a tenant's object is read by its own org, never shared`,
+        });
+      }
+    }
+    out.set(diskName, Object.freeze([...prefixes]));
+  }
+  return out;
 }
 
 let current: Storage | undefined;
@@ -63,6 +112,7 @@ export function defineStorage(config: StorageConfig): Storage {
     registered.set(driver, diskName);
     driver.registerAs?.(diskName);
   }
+  const shared = sharedPrefixes(config.shared, names);
   const storageInstance: Storage = {
     defaultDisk,
     diskNames: Object.freeze([...names]),
@@ -72,6 +122,10 @@ export function defineStorage(config: StorageConfig): Storage {
       if (driver === undefined) throw diskUnknown(wanted, names);
       return driver;
     },
+    isShared(diskName: string, key: string): boolean {
+      if (!isSafeKey(key) || isTenantScoped(key)) return false;
+      return (shared.get(diskName) ?? []).some((prefix) => key.startsWith(prefix));
+    },
   };
   current = storageInstance;
   return storageInstance;