pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/src/storage/service.ts

@@ -27,10 +27,10 @@ import {
   resolveOperationContext,
 } from 'pyric/sandbox/internal';
 import { openStorageBackend, storageDbName, type StorageBackend } from './persistence.js';
-import { parseStorageRules, type StorageRules } from './sandbox/rules.js';
-import { resolveModulesBrowser } from '../rules/modules/resolver-browser.js';
+import { StorageService, type CrossServiceIam } from './sandbox/running-service.js';
+import type { StorageRules } from './sandbox/rules.js';
 import {
-  createStorageRulesResolution,
+  compileStorageRules,
   type StorageRulesResolution,
 } from './rules-resolution.js';
 
@@ -92,39 +92,13 @@ export interface FirebaseStorage {
 /** Storage handle returned by Firebase-shaped app overloads. */
 export type AppFirebaseStorage = FirebaseStorage & { readonly app: FirebaseApp };
 
-/**
- * Cross-service IAM posture for `firestore.get()/exists()` in Storage rules.
- *
- * Production Storage rules can read Firestore ONLY when the project's
- * Storage service agent holds `roles/firebaserules.firestoreServiceAgent`.
- * `'granted'` (the default, the common configured-project state) serves
- * lookups from the same-sandbox Firestore store; `'denied'` makes every
- * EXECUTED lookup fail exactly like production without the role (error →
- * rule denies), while short-circuited lookups are never executed and stay
- * unaffected. Captured boundary: conformance observation
- * `stdlib-realstorage-p3-lookup-budget` (registry row storage-rules#134).
- */
-export type CrossServiceIam = 'granted' | 'denied';
-
-/**
- * Internal sandbox service — owns the IDB connection + parsed rules.
- * Only constructed inside the sandbox `getStorageSandbox` path.
- */
-export class StorageService {
-  constructor(
-    readonly backend: StorageBackend,
-    readonly rules: StorageRules | null = null,
-    readonly crossServiceIam: CrossServiceIam = 'granted',
-  ) {}
-}
+export { StorageService, type CrossServiceIam } from './sandbox/running-service.js';
 
 /** Options for {@link getStorageSandbox}. */
 export interface StorageOptions {
   /**
-   * Bucket identifier recorded on uploaded metadata. v1 has a
-   * single implicit bucket and does not enforce cross-bucket
-   * isolation — passing different values per call is accepted and
-   * round-trips in metadata, but the data store is shared.
+   * Bucket identifier recorded on uploaded metadata and used to isolate
+   * storage persistence across multiple buckets.
    */
   bucket?: string;
   /**
@@ -179,19 +153,53 @@ interface OpenStorageService {
 
 /** One open storage service, with its opening configuration, per `Sandbox`. */
 const OPEN_SERVICES = new WeakMap<Sandbox, OpenStorageService>();
+const HOST_BACKENDS = new WeakMap<Sandbox, StorageBackend>();
+
+/** Hosts install their durable backend before any Storage service is created. */
+export function installStorageBackend(sandbox: Sandbox, backend: StorageBackend): void {
+  const alreadyOpened = OPEN_SERVICES.has(sandbox) || HOST_BACKENDS.has(sandbox);
+  if (alreadyOpened) throw new Error('Storage backend must be installed once, before Storage initializes.');
+  HOST_BACKENDS.set(sandbox, backend);
+}
 
-/** One sandbox `FirebaseStorage` handle per `SandboxContext`. */
-const SANDBOX_HANDLES = new WeakMap<SandboxContext, FirebaseStorage>();
+/** One scoped `StorageService` per (Sandbox, bucket). */
+const SCOPED_SERVICES = new WeakMap<Sandbox, Map<string, Promise<StorageService>>>();
+
+function getOrCreateScopedService(
+  sandbox: Sandbox,
+  bucket: string,
+  rootServicePromise: Promise<StorageService>,
+): Promise<StorageService> {
+  let bucketMap = SCOPED_SERVICES.get(sandbox);
+  if (!bucketMap) {
+    bucketMap = new Map();
+    SCOPED_SERVICES.set(sandbox, bucketMap);
+  }
+  let existing = bucketMap.get(bucket);
+  if (!existing) {
+    existing = rootServicePromise.then((rootService) => {
+      const backend = rootService.backend.scoped
+        ? rootService.backend.scoped(bucket)
+        : rootService.backend;
+      return new StorageService(backend, rootService.rules, rootService.crossServiceIam);
+    });
+    bucketMap.set(bucket, existing);
+  }
+  return existing;
+}
+
+/** Sandbox `FirebaseStorage` handles cached per `(SandboxContext, bucket)`. */
+const SANDBOX_HANDLES = new WeakMap<SandboxContext, Map<string, FirebaseStorage>>();
 
 /**
- * One anonymous handle per bare `Sandbox`. `Sandbox.withAuth(null)`
+ * Anonymous handles cached per `(Sandbox, bucket)`. `Sandbox.withAuth(null)`
  * mints a FRESH `SandboxContext` on every call, so the per-context
  * cache above would miss for the bare-`Sandbox` convenience path —
  * `getStorageSandbox(sandbox)` twice returned two different handles
  * (ST-B3). Caching on the `Sandbox` keeps that path identity-stable,
  * matching the documented "handle is identity-stable per Sandbox".
  */
-const BARE_SANDBOX_HANDLES = new WeakMap<Sandbox, FirebaseStorage>();
+const BARE_SANDBOX_HANDLES = new WeakMap<Sandbox, Map<string, FirebaseStorage>>();
 
 /**
  * Reject a late option that differs from the one the service is already
@@ -221,6 +229,91 @@ function rejectDifferingLateConfig(
   );
 }
 
+/**
+ * Install a new ruleset into a sandbox's storage service, replacing whatever
+ * it is enforcing.
+ *
+ * This is the deliberate counterpart to the late-config guard in
+ * {@link ensureService}. That guard exists because a `rules` option passed to
+ * a FACTORY after the service is open would be silently discarded, and a
+ * caller asking for a handle has not asked to change the ruleset. Here the
+ * caller has asked for exactly that and nothing is discarded: the source is
+ * compiled first, so a source that does not parse throws and leaves the
+ * ruleset in force untouched, and the factory guard is unchanged, so the
+ * served-app path still refuses a late differing option.
+ *
+ * The new ruleset reaches the root service and every per-bucket scoped
+ * service, because each holds its own reference to the parsed rules.
+ */
+export async function replaceStorageRules(sandbox: Sandbox, source: string): Promise<void> {
+  const compiled = compileStorageRules(source);
+  const open = OPEN_SERVICES.get(sandbox);
+  if (open === undefined) {
+    await ensureService(sandbox, { rules: source }, 'replaceStorageRules');
+    return;
+  }
+  OPEN_SERVICES.set(sandbox, {
+    service: open.service,
+    rulesSource: source,
+    rulesResolution: compiled.resolution,
+    crossServiceIam: open.crossServiceIam,
+  });
+  const root = await open.service;
+  root.rules = compiled.rules;
+  for (const scopedPromise of SCOPED_SERVICES.get(sandbox)?.values() ?? []) {
+    const scoped = await scopedPromise;
+    scoped.rules = compiled.rules;
+  }
+}
+
+/**
+ * The cross-service IAM posture a sandbox's storage service is running under.
+ *
+ * A sandbox whose storage service has never been opened reports the default a
+ * first open would take, so a reader gets the mode that is in force rather
+ * than an absence it has to interpret.
+ */
+export function getStorageCrossServiceIam(sandbox: Sandbox): CrossServiceIam {
+  return OPEN_SERVICES.get(sandbox)?.crossServiceIam ?? 'granted';
+}
+
+/**
+ * Move a sandbox's storage service between the granted and denied
+ * cross-service IAM states, replacing whatever it is enforcing.
+ *
+ * This is the deliberate counterpart to the late-config guard in
+ * {@link ensureService}, on the same argument that gives
+ * {@link replaceStorageRules} its exception: a `crossServiceIam` option passed
+ * to a FACTORY after the service is open would be silently discarded, and a
+ * caller asking for a handle has not asked to change the project's IAM
+ * posture. Here the caller has asked for exactly that.
+ *
+ * The new mode reaches the root service and every per-bucket scoped service,
+ * because each holds its own reference to it.
+ */
+export async function replaceCrossServiceIam(
+  sandbox: Sandbox,
+  mode: CrossServiceIam,
+): Promise<void> {
+  const open = OPEN_SERVICES.get(sandbox);
+  if (open === undefined) {
+    await ensureService(sandbox, { crossServiceIam: mode }, 'replaceCrossServiceIam');
+    return;
+  }
+  OPEN_SERVICES.set(sandbox, {
+    service: open.service,
+    rulesSource: open.rulesSource,
+    rulesResolution: open.rulesResolution,
+    crossServiceIam: mode,
+  });
+  const root = await open.service;
+  root.crossServiceIam = mode;
+  for (const scopedPromise of SCOPED_SERVICES.get(sandbox)?.values() ?? []) {
+    const scoped = await scopedPromise;
+    scoped.crossServiceIam = mode;
+  }
+}
+
 /**
  * Get (or open) the ONE per-sandbox `StorageService`. Loud on the
  * silent-rules-wipe hazard: when the service is already open and the
@@ -234,7 +327,8 @@ function ensureService(
   caller: string,
 ): Promise<StorageService> {
   const existing = OPEN_SERVICES.get(sandbox);
-  if (existing) {
+  const alreadyOpen = existing !== undefined;
+  if (alreadyOpen) {
     rejectDifferingLateConfig(
       'rules',
       'rules source',
@@ -253,39 +347,27 @@ function ensureService(
   }
   let rules: StorageRules | null = null;
   let resolution: StorageRulesResolution | null = null;
-  if (options.rules) {
-    let source = options.rules;
-    let modules: readonly string[] = [];
-    let bundledModules: readonly string[] = [];
-    let moduleEvidenceIds: readonly string[] = [];
-    rules = parseStorageRules(source);
-    if (rules._version === '2+modules') {
-      const resolved = resolveModulesBrowser(source);
-      if (!resolved.success) {
-        throw new SyntaxError(
-          `Storage rules module resolution failed (${resolved.error.code}): ${resolved.error.message}`,
-        );
-      }
-      source = resolved.data.resolved;
-      modules = resolved.data.modules;
-      bundledModules = resolved.data.bundledModules;
-      moduleEvidenceIds = resolved.data.evidenceIds;
-      rules = parseStorageRules(source);
-    }
-    resolution = createStorageRulesResolution(
-      source,
-      modules,
-      bundledModules,
-      moduleEvidenceIds,
-      rules,
-    );
+  const rulesSource = options.rules;
+  const hasRules = typeof rulesSource === 'string' && rulesSource.length > 0;
+  if (hasRules) {
+    const compiled = compileStorageRules(rulesSource);
+    rules = compiled.rules;
+    resolution = compiled.resolution;
   }
   // Explicit dbName wins; otherwise scope the default by project identity so
   // two projects on one origin never share a storage database (issue #359).
   const crossServiceIam = options.crossServiceIam ?? 'granted';
-  const servicePromise = openStorageBackend(
-    options.dbName ?? storageDbName(options.projectId),
-  ).then(
+  const injectedBackend = HOST_BACKENDS.get(sandbox);
+  let backendPromise: Promise<StorageBackend>;
+  const hasInjectedBackend = injectedBackend !== undefined;
+  if (hasInjectedBackend) backendPromise = Promise.resolve(injectedBackend);
+  else {
+    backendPromise = openStorageBackend(
+      options.dbName ?? storageDbName(options.projectId),
+      options.bucket ?? DEFAULT_BUCKET,
+    );
+  }
+  const servicePromise = backendPromise.then(
     (backend) => new StorageService(backend, rules, crossServiceIam),
   );
   OPEN_SERVICES.set(sandbox, {
@@ -336,24 +418,22 @@ export function getStorageSandbox(
   // Open (or fetch) the ONE per-sandbox service FIRST — before any handle
   // cache fast-path — so a late, differing `rules` option throws instead of
   // being silently discarded (see ensureService).
-  const servicePromise = ensureService(sandbox, options, 'getStorageSandbox');
+  const rootServicePromise = ensureService(sandbox, options, 'getStorageSandbox');
+  const bucket = options.bucket ?? DEFAULT_BUCKET;
 
   // Fast path: a repeat bare-`Sandbox` call returns the cached
-  // anonymous handle (the per-context cache below can't catch it
-  // because `withAuth(null)` mints a fresh context each time). Like
-  // the per-context path, bucket/dbName options are honored only on
-  // the FIRST call per Sandbox.
+  // anonymous handle for the requested bucket.
   if (fromBareSandbox) {
-    const cachedBare = BARE_SANDBOX_HANDLES.get(sandbox);
+    const cachedBare = BARE_SANDBOX_HANDLES.get(sandbox)?.get(bucket);
     if (cachedBare) return cachedBare;
   }
 
   const ctx = isContext(target) ? target : target.withAuth(null);
-  const bucket = options.bucket ?? DEFAULT_BUCKET;
-
-  const cached = SANDBOX_HANDLES.get(ctx);
+  const cached = SANDBOX_HANDLES.get(ctx)?.get(bucket);
   if (cached) return cached;
 
+  const servicePromise = getOrCreateScopedService(sandbox, bucket, rootServicePromise);
+
   const sandboxTarget: SandboxTarget = {
     kind: 'sandbox',
     sandbox,
@@ -363,15 +443,29 @@ export function getStorageSandbox(
     servicePromise,
   };
   const handle: FirebaseStorage = Object.freeze({ [TARGET_SYMBOL]: sandboxTarget });
-  SANDBOX_HANDLES.set(ctx, handle);
-  if (fromBareSandbox) BARE_SANDBOX_HANDLES.set(sandbox, handle);
+
+  let ctxMap = SANDBOX_HANDLES.get(ctx);
+  if (!ctxMap) {
+    ctxMap = new Map();
+    SANDBOX_HANDLES.set(ctx, ctxMap);
+  }
+  ctxMap.set(bucket, handle);
+
+  if (fromBareSandbox) {
+    let bareMap = BARE_SANDBOX_HANDLES.get(sandbox);
+    if (!bareMap) {
+      bareMap = new Map();
+      BARE_SANDBOX_HANDLES.set(sandbox, bareMap);
+    }
+    bareMap.set(bucket, handle);
+  }
   return handle;
 }
 
 /** Admin handles are cached by bound context so Studio, agent, and
  * unattributed callers can share storage state without sharing provenance. */
-const ADMIN_CONTEXT_HANDLES = new WeakMap<SandboxContext, FirebaseStorage>();
-const BARE_ADMIN_HANDLES = new WeakMap<Sandbox, FirebaseStorage>();
+const ADMIN_CONTEXT_HANDLES = new WeakMap<SandboxContext, Map<string, FirebaseStorage>>();
+const BARE_ADMIN_HANDLES = new WeakMap<Sandbox, Map<string, FirebaseStorage>>();
 
 /**
  * INTERNAL (exported via `pyric/storage/internal` only) — construct
@@ -395,10 +489,11 @@ export function getAdminStorageSandbox(
   const fromBareSandbox = !isContext(target);
   const sandbox = isContext(target) ? target.sandbox : target;
   // Service first (late differing `rules` must throw, even on a cache hit).
-  const servicePromise = ensureService(sandbox, options, 'getAdminStorageSandbox');
+  const rootServicePromise = ensureService(sandbox, options, 'getAdminStorageSandbox');
+  const bucket = options.bucket ?? DEFAULT_BUCKET;
 
   if (fromBareSandbox) {
-    const cachedBare = BARE_ADMIN_HANDLES.get(sandbox);
+    const cachedBare = BARE_ADMIN_HANDLES.get(sandbox)?.get(bucket);
     if (cachedBare) return cachedBare;
   }
 
@@ -412,20 +507,36 @@ export function getAdminStorageSandbox(
           ? {}
           : { planId: baseContext.operationContext.planId }),
       });
-  const cached = ADMIN_CONTEXT_HANDLES.get(baseContext);
+  const cached = ADMIN_CONTEXT_HANDLES.get(baseContext)?.get(bucket);
   if (cached) return cached;
 
+  const servicePromise = getOrCreateScopedService(sandbox, bucket, rootServicePromise);
+
   const sandboxTarget: SandboxTarget = {
     kind: 'sandbox',
     sandbox,
     context,
-    bucket: options.bucket ?? DEFAULT_BUCKET,
+    bucket,
     servicePromise,
     admin: true,
   };
   const handle: FirebaseStorage = Object.freeze({ [TARGET_SYMBOL]: sandboxTarget });
-  ADMIN_CONTEXT_HANDLES.set(baseContext, handle);
-  if (fromBareSandbox) BARE_ADMIN_HANDLES.set(sandbox, handle);
+
+  let ctxMap = ADMIN_CONTEXT_HANDLES.get(baseContext);
+  if (!ctxMap) {
+    ctxMap = new Map();
+    ADMIN_CONTEXT_HANDLES.set(baseContext, ctxMap);
+  }
+  ctxMap.set(bucket, handle);
+
+  if (fromBareSandbox) {
+    let bareMap = BARE_ADMIN_HANDLES.get(sandbox);
+    if (!bareMap) {
+      bareMap = new Map();
+      BARE_ADMIN_HANDLES.set(sandbox, bareMap);
+    }
+    bareMap.set(bucket, handle);
+  }
   return handle;
 }
 

package/src/storage/string-format.ts

@@ -0,0 +1,8 @@
+/** Encodings accepted by Firebase Storage string uploads. */
+export const StringFormat = {
+  RAW: "raw",
+  BASE64: "base64",
+  BASE64URL: "base64url",
+  DATA_URL: "data_url",
+} as const;
+export type StringFormat = (typeof StringFormat)[keyof typeof StringFormat];

package/src/storage/upload.ts

@@ -23,7 +23,7 @@
  *     payload's intrinsic type (`Blob.type`, data-url prefix) →
  *     `application/octet-stream`. Matches the JS SDK.
  */
-import { emitSandboxEvent, makeServiceMutationEvent } from 'pyric/sandbox/internal';
+import { emitSandboxEvent, getClock, makeServiceMutationEvent } from 'pyric/sandbox/internal';
 import type { EventProvenance } from 'pyric/sandbox';
 import { getStorageService, storageAuth, storageOperationProvenance, targetOf } from './service.js';
 import { enforceRules } from './enforce.js';
@@ -36,7 +36,8 @@ import type { StorageReference } from './reference.js';
 const OCTET = 'application/octet-stream';
 
 /** `uploadString` format selector. */
-export type StringFormat = 'raw' | 'base64' | 'data_url';
+import type { StringFormat } from './string-format.js';
+export type { StringFormat } from './string-format.js';
 
 /**
  * Upload bytes to the reference's `fullPath`. Replaces any existing
@@ -63,7 +64,10 @@ export async function uploadBytes(
   const target = targetOf(ref.storage);
   const operationProvenance = storageOperationProvenance(target, provenance);
   const blob = toBlob(data, metadata?.contentType);
-  const stored = buildStoredMetadata({ ref, blob, settable: metadata });
+  // Server-set object times come from the sandbox clock, so `timeCreated` and
+  // `updated` agree with the `request.time` the rules see for this same upload.
+  const uploadedAt = getClock(target.sandbox).date();
+  const stored = buildStoredMetadata({ ref, blob, settable: metadata, now: uploadedAt });
   const service = await getStorageService(ref.storage);
   const existing = await service.backend.getMetadata(ref.fullPath);
   enforceRules(service, {
@@ -89,6 +93,7 @@ export async function uploadBytes(
     emitSandboxEvent(
       target.sandbox,
       makeServiceMutationEvent({
+        at: getClock(target.sandbox).now(),
         service: 'storage',
         op: 'object_put',
         path: ref.fullPath,

package/src/storage/url.ts

@@ -0,0 +1,106 @@
+/**
+ * The strings `ref()` reads as URLs, and the object each one names.
+ *
+ * `ref(storage, url)` accepts the URL forms production's `firebase/storage`
+ * parses, with the same patterns:
+ *
+ * - `gs://<bucket>/<path>`, whose path is taken as written;
+ * - `http(s)://firebasestorage.googleapis.com/v<n>/b/<bucket>/o/<path>`, the
+ *   download URL form, whose path is percent-decoded and whose query is ignored;
+ * - `http(s)://storage.googleapis.com/<bucket>/<path>` and
+ *   `storage.cloud.google.com`, percent-decoded the same way.
+ *
+ * It also accepts the download URL the Node host issues,
+ * `<origin>/__pyric/storage/v0/b/<bucket>/o/<path>`, on any origin. Production
+ * never issues that form and throws `storage/invalid-url` for it.
+ *
+ * A `data:` URI is a download URL in process and on a SharedWorker host. It
+ * carries an object's bytes, not its location, so `ref()` throws
+ * `storage/invalid-url` for one. Production has no such URL and reads the
+ * string as an object path.
+ */
+import { StorageError } from './errors.js';
+
+/** The bucket and object path a Storage URL names. */
+export interface StorageLocation {
+  readonly bucket: string;
+  readonly path: string;
+}
+
+const BUCKET = '([A-Za-z0-9.\\-_]+)';
+
+/** A `ref()` string is a URL when it starts with a scheme and `://`, as production decides. */
+const SCHEME_URL = /^[A-Za-z]+:\/\//;
+
+/** `data:[<media type>][;base64],<data>` */
+const DATA_URI = /^data:[^,]*,/i;
+
+/** A URL form: its pattern captures the bucket, then the path. */
+interface UrlForm {
+  readonly pattern: RegExp;
+  /** Turns the captured path into the object path. */
+  readonly path: (captured: string) => string;
+}
+
+const asWritten = (value: string): string => value;
+
+const URL_FORMS: readonly UrlForm[] = [
+  { pattern: new RegExp(`^gs://${BUCKET}(?:/(.*))?$`, 'i'), path: asWritten },
+  {
+    pattern: new RegExp(`^https?://firebasestorage\\.googleapis\\.com/v[A-Za-z0-9_]+/b/${BUCKET}/o(?:/([^?#]*).*)?$`, 'i'),
+    path: decodeURIComponent,
+  },
+  {
+    pattern: new RegExp(`^https?://(?:storage\\.googleapis\\.com|storage\\.cloud\\.google\\.com)/${BUCKET}/([^?#]*)`, 'i'),
+    path: decodeURIComponent,
+  },
+  {
+    pattern: new RegExp(`^https?://[^/?#]+/__pyric/storage/v0/b/${BUCKET}/o/([^?#]+)`),
+    path: decodeURIComponent,
+  },
+];
+
+function invalidUrl(url: string, detail: string): StorageError {
+  return new StorageError('invalid-url', `Invalid URL '${url}'. ${detail}`);
+}
+
+/** Whether `ref()` reads `value` as a URL rather than as an object path. */
+export function isStorageUrl(value: string): boolean {
+  return SCHEME_URL.test(value) || DATA_URI.test(value);
+}
+
+/** The bucket and object path `url` names; throws `storage/invalid-url` when it names none. */
+export function parseStorageUrl(url: string): StorageLocation {
+  const isDataUri = DATA_URI.test(url);
+  if (isDataUri) {
+    throw invalidUrl(
+      url.length > 64 ? `${url.slice(0, 64)}...` : url,
+      'A data: URI carries an object\'s bytes, not its location. Reference the object by its path or its gs:// URL.',
+    );
+  }
+  for (const form of URL_FORMS) {
+    const captured = form.pattern.exec(url);
+    if (captured === null) continue;
+    return { bucket: captured[1]!, path: form.path(captured[2] ?? '') };
+  }
+  throw invalidUrl(url, 'Expected a gs:// URL or a Storage download URL.');
+}
+
+/**
+ * The object path a `ref()` string argument names, before normalization.
+ * `fromStorage` is whether `ref()` was given a Storage instance rather than a
+ * reference: only a Storage instance takes a URL, as in production. The sandbox
+ * serves one bucket, so a URL's bucket does not change which store the
+ * reference reads.
+ */
+export function refPathOf(value: string | undefined, fromStorage: boolean): string {
+  const given = value ?? '';
+  const isUrl = isStorageUrl(given);
+  if (!isUrl) return given;
+  const isDataUri = DATA_URI.test(given);
+  const urlOnReference = !fromStorage && !isDataUri;
+  if (urlOnReference) {
+    throw new StorageError('invalid-argument', 'To use ref(service, url), the first argument must be a Storage instance.');
+  }
+  return parseStorageUrl(given).path;
+}