@pyric/cli 0.1.0-alpha.30.2 → 0.1.0-alpha.31

package/src/serve/worker/client/rtdb-writes.ts

@@ -12,6 +12,7 @@ import { validateUpdatePaths, validateWritablePath } from 'pyric/database/intern
 import { beginWorkerDatabaseActivity } from './sdk-activity.js';
 import { sandboxNow } from './clock.js';
 import { nextId } from './core.js';
+import { validateRtdbPriority, validateRtdbUpdateValues, validateRtdbValue } from './rtdb-value-validation.js';
 import type { RtdbRefHandle } from './handles.js';
 import { makeRtdbRef, rtdbRpc } from './rtdb-references.js';
 
@@ -45,6 +46,7 @@ function generateRtdbPushId(now: number): string {
 
 export function rtdbSet(ref: RtdbRefHandle, value: unknown): Promise<void> {
   validateWritablePath('set', ref.path);
+  validateRtdbValue('set', value, ref.path);
   return runSdkWrite(beginWorkerDatabaseActivity(ref, 'set', 'operation'), async () => {
     await rtdbRpc(ref, { t: 'op', id: nextId(), method: 'rtdb.set', path: ref.path, value });
   });
@@ -52,6 +54,7 @@ export function rtdbSet(ref: RtdbRefHandle, value: unknown): Promise<void> {
 
 export function rtdbSetPriority(ref: RtdbRefHandle, priority: string | number | null): Promise<void> {
   validateWritablePath('setPriority', ref.path);
+  validateRtdbPriority('setPriority', priority);
   return runSdkWrite(beginWorkerDatabaseActivity(ref, 'setPriority', 'operation'), async () => {
     await rtdbRpc(ref, { t: 'op', id: nextId(), method: 'rtdb.setPriority', path: ref.path, priority });
   });
@@ -63,6 +66,8 @@ export function rtdbSetWithPriority(
   priority: string | number | null,
 ): Promise<void> {
   validateWritablePath('setWithPriority', ref.path);
+  validateRtdbValue('setWithPriority', value, ref.path);
+  validateRtdbPriority('setWithPriority', priority);
   return runSdkWrite(beginWorkerDatabaseActivity(ref, 'setWithPriority', 'operation'), async () => {
     await rtdbRpc(ref, {
       t: 'op', id: nextId(), method: 'rtdb.setWithPriority', path: ref.path, value, priority,
@@ -71,6 +76,7 @@ export function rtdbSetWithPriority(
 }
 
 export function rtdbUpdate(ref: RtdbRefHandle, values: Record<string, unknown>): Promise<void> {
+  validateRtdbUpdateValues('update', values, ref.path);
   validateUpdatePaths(values);
   return runSdkWrite(beginWorkerDatabaseActivity(ref, 'update', 'operation'), async () => {
     await rtdbRpc(ref, { t: 'op', id: nextId(), method: 'rtdb.update', path: ref.path, values });
@@ -89,6 +95,7 @@ export function rtdbPush(
   value?: unknown,
 ): RtdbRefHandle & PromiseLike<RtdbRefHandle> {
   validateWritablePath('push', ref.path);
+  validateRtdbValue('push', value, ref.path, true);
   const key = generateRtdbPushId(sandboxNow());
   const pushed = makeRtdbRef(ref.port, `${ref.path}/${key}`, ref.instance);
   const settledRef = makeRtdbRef(ref.port, pushed.path, ref.instance);

package/src/serve/worker/client/snapshots.ts

@@ -34,6 +34,8 @@ export interface RawDocResult {
   path?: string;
   exists: boolean;
   data?: SerializedDocData;
+  /** Query listener frames only: this document's own `metadata.hasPendingWrites`. */
+  hasPendingWrites?: boolean;
 }
 
 const SETTLED_METADATA: SnapshotMetadata = Object.freeze({ fromCache: false, hasPendingWrites: false });
@@ -67,14 +69,19 @@ export function makeDocSnapshot<T = DocumentData>(
 ): ClientDocSnapshot<T> {
   const isMalformed = !isDocumentResult(raw);
   if (isMalformed) throw new FirebaseError('invalid-argument', 'The sandbox sent a malformed document result.');
-  let data: Record<string, unknown> | undefined;
   const serialized = raw.data;
-  const hasData = raw.exists && serialized !== undefined;
-  if (hasData) data = rehydrateDocData(serialized, port);
+  // Production builds a new object on every read, so a caller that mutates
+  // one result never changes the next (FP-13). The copy kept here is for
+  // cursor bounds only and is never handed out.
+  const freshData = (): Record<string, unknown> | undefined => {
+    const hasData = raw.exists && serialized !== undefined;
+    return hasData ? rehydrateDocData(serialized, port) : undefined;
+  };
+  const data = freshData();
   const path = raw.path ?? raw.id;
   const ref = reference ?? createDocumentReference<T>(port, path);
   const read = (): T | undefined => {
-    const document = data;
+    const document = freshData();
     const isMissing = document === undefined;
     if (isMissing) return undefined;
     const converter = ref.converter;
@@ -101,7 +108,7 @@ export function makeDocSnapshot<T = DocumentData>(
     metadata,
     data: read,
     // Production reads the stored field without the converter, as the in-page snapshot does.
-    get: (fieldPath) => readField(data, fieldPath),
+    get: (fieldPath) => readField(freshData(), fieldPath),
   };
   rawCursorSnapshots.set(docSnapshot, { id: raw.id, path, exists: raw.exists, data });
   return docSnapshot;
@@ -229,11 +236,13 @@ export function makeQuerySnapshot(
   const isMalformed = !isQueryResult(raw);
   if (isMalformed) throw new FirebaseError('invalid-argument', 'The sandbox sent a malformed query result.');
   const metadata = frameMetadata(raw);
+  // Each document carries its own pending state: production marks only the
+  // documents with a pending write, not every document in the snapshot (FP-5).
   const snapshotOf = (doc: RawDocResult) => makeDocSnapshot(
     doc,
     port,
     createDocumentReference(port, doc.path ?? doc.id, converter),
-    metadata,
+    frameMetadata(doc),
   );
   const docs = raw.docs.map(snapshotOf);
   const rows = raw.docs.map((doc) => ({ path: doc.path ?? doc.id, doc }));

package/src/serve/worker/client/websocket-connection.ts

@@ -65,10 +65,18 @@ export function getHostedFirestore(target: {
    * passes nothing and presents the boot it was served by (#1153).
    */
   currentHostInstanceId?: () => Promise<string | undefined>;
+  /**
+   * Resolves the socket url again before a reattach. A Node process passes it:
+   * a host that stopped may come back on another port, which its
+   * `.pyric/serve.json` names. A page passes nothing and redials its own origin.
+   */
+  currentUrl?: () => Promise<string>;
 }, existingPort?: ClientPort): ClientDb {
   const connectionId = `socket-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+  /** The url the next socket dials; a reattach may resolve it again. */
+  let socketUrl = target.url;
   const report = (phase: DiagnosticEvent['phase'], code?: number) => {
-    recordDiagnostic({ phase, connectionId, endpoint: target.url, code });
+    recordDiagnostic({ phase, connectionId, endpoint: socketUrl, code });
   };
   const connectionListeners = new Set<(connected: boolean) => void>();
   let state: HostedConnectionState = 'connecting';
@@ -242,12 +250,25 @@ export function getHostedFirestore(target: {
     failInFlightStreams(port, lost, subId => held.holdsSubscription({ t: 'unsub', subId }));
     noteTraffic({});
     connection.close();
+    scheduleReconnect();
+  }
+
+  function scheduleReconnect(): void {
     const delay = Math.min(5_000, 250 * 2 ** reconnectAttempt);
     reconnectAttempt += 1;
     const jitter = Math.random() * Math.min(250, delay / 10);
     reconnectTimer = armed(setTimeout(connect, Math.min(5_000, delay + jitter)));
   }
 
+  /** A reattach whose url could not be resolved (no host answers yet) tries again on the same backoff. */
+  function retryResolution(): void {
+    const isClosed = state === 'closed';
+    if (isClosed) return;
+    state = 'interrupted';
+    notifyConnectionChange();
+    scheduleReconnect();
+  }
+
   function scheduleHeartbeat(connection: WebSocket): void {
     const remainingLiveness = HOSTED_CLIENT_LIVENESS_TIMEOUT_MS - (performance.now() - lastReceivedAt);
     const delay = Math.max(0, Math.min(HOSTED_HEARTBEAT_INTERVAL_MS, remainingLiveness));
@@ -337,8 +358,23 @@ export function getHostedFirestore(target: {
     const retentionExpired = interruptedAt !== undefined && performance.now() - interruptedAt >= WORKER_SESSION_RETENTION_MS;
     if (retentionExpired) resumeToken = undefined;
     const requestsFreshSession = resumeToken === undefined;
+    const resolveUrl = target.currentUrl;
+    const resolvesAgain = hasEverAttached && resolveUrl !== undefined;
+    if (!resolvesAgain) {
+      openSocket(requestsFreshSession);
+      return;
+    }
+    void resolveUrl().then(url => {
+      const isClosedMeanwhile = state === 'closed';
+      if (isClosedMeanwhile) return;
+      socketUrl = url;
+      openSocket(requestsFreshSession);
+    }, retryResolution);
+  }
+
+  function openSocket(requestsFreshSession: boolean): void {
     let connection: WebSocket;
-    try { connection = realm ? realm.createSocket(target.url) : new WebSocket(target.url); }
+    try { connection = realm ? realm.createSocket(socketUrl) : new WebSocket(socketUrl); }
     catch (error) { report('socket-error'); throw error; }
     socket = connection;
     attachDeadline = armed(setTimeout(() => {
@@ -412,7 +448,7 @@ export function getHostedFirestore(target: {
           const offersByteRoute = capabilities.includes(STORAGE_BYTE_ROUTE_CAPABILITY);
           const sessionToken = target.sessionToken;
           const usesByteRoute = offersByteRoute && sessionToken !== undefined;
-          if (usesByteRoute) port.byteRoute = { baseUrl: httpOriginOf(target.url), sessionToken };
+          if (usesByteRoute) port.byteRoute = { baseUrl: httpOriginOf(socketUrl), sessionToken };
           else delete port.byteRoute;
           settleByteRoute();
           realm?.attached?.(message);

package/src/serve/worker/host/auth-credential-sign-in.ts

@@ -0,0 +1,97 @@
+import { FirebaseError } from 'pyric/app';
+import { AuthCredential, EmailAuthCredential, sandbox, type Auth, type MintedSession } from 'pyric/auth';
+import { isFederatedProviderId, noMockConfiguredError, resolveEmailLinkIdentity } from 'pyric/auth/internal';
+import { resolveOAuthCredentialUser, type OAuthCredentialPayload } from './auth-session-seeder.js';
+import type { ResolvedIdentity } from '../protocol.js';
+
+/** The tenant and page origin a served sign-in mints its session under. */
+export interface CredentialSignInScope {
+  readonly tenantId: string | null;
+  readonly origin?: string;
+}
+
+/** Use up the calling port's staged result for a provider, or `null` when none was staged. */
+export type TakeStagedSignInResult = (providerId: string) => ResolvedIdentity | null;
+
+/** A credential as it arrives on the wire: nested, or flat on a native client's op message. */
+export type CredentialPayload = OAuthCredentialPayload & Record<string, unknown>;
+
+export interface CredentialSignIn {
+  readonly session: MintedSession;
+  readonly providerId: string | null;
+  readonly isNewUser: boolean;
+}
+
+const EMAIL_PROVIDER_ID = 'password';
+
+/**
+ * Sign a port in with a credential.
+ *
+ * An email credential carries its own secret, so the engine checks it here
+ * exactly as `signInWithEmailAndPassword` and `signInWithEmailLink` do. A
+ * provider id that is not federated (a look-alike of `password`, `emailLink`,
+ * `phone`, or an id pyric doesn't know), or a payload whose `signInMethod`
+ * differs from its provider, is refused with in-page's
+ * `auth/no-mock-configured` before the resolver can find or touch an account
+ * (#1466). A federated credential signs in only as a result the port staged
+ * for its provider, as in-page: the sandbox has no identity provider to
+ * redeem a token against, so nothing the payload asserts (`uid`, `email`)
+ * picks the account. With nothing staged it is refused the same way.
+ */
+export function signInWithCredentialPayload(
+  auth: Auth,
+  payload: CredentialPayload,
+  scope: CredentialSignInScope,
+  takeStaged: TakeStagedSignInResult,
+): CredentialSignIn {
+  const isEmailCredential = payload.providerId === EMAIL_PROVIDER_ID;
+  if (isEmailCredential) return signInWithEmailCredential(auth, payload, scope);
+  // In-page checks enablement before anything else, so a disabled provider is operation-not-allowed.
+  sandbox.assertAuthProviderEnabled(auth, payload.providerId);
+  const isFederated = isFederatedProviderId(payload.providerId);
+  const signInMethod = payload.signInMethod;
+  const hasOtherSignInMethod = signInMethod !== undefined && signInMethod !== payload.providerId;
+  if (!isFederated || hasOtherSignInMethod) throw noMockConfiguredError(payload.providerId);
+  const staged = takeStaged(payload.providerId);
+  const hasStagedUser = staged !== null && staged.uid !== '';
+  if (!hasStagedUser) throw noMockConfiguredError(payload.providerId);
+  return signInAsStaged(auth, staged, scope);
+}
+
+/** Sign in as the staged identity: find or create its uid and link the provider, as `auth.acceptIdentity` does. */
+function signInAsStaged(auth: Auth, staged: ResolvedIdentity, scope: CredentialSignInScope): CredentialSignIn {
+  const { photoURL, ...identity } = staged;
+  const { uid, isNewUser } = resolveOAuthCredentialUser(auth, { ...identity, photoURL: photoURL ?? undefined });
+  const session = sandbox.mintSession(auth, { kind: 'provider', uid, providerId: staged.providerId, ...scope });
+  return { session, providerId: staged.providerId, isNewUser };
+}
+
+/** Rebuild the email credential and let the engine verify its password or link. A missing secret fails closed. */
+function signInWithEmailCredential(
+  auth: Auth,
+  payload: CredentialPayload,
+  scope: CredentialSignInScope,
+): CredentialSignIn {
+  const credential = AuthCredential.fromJSON(payload);
+  const isEmail = credential instanceof EmailAuthCredential;
+  if (!isEmail) throw invalidCredential();
+  const usesPassword = credential.password !== null;
+  if (usesPassword) {
+    const session = sandbox.mintSession(auth, {
+      kind: 'password', email: credential.email, password: credential.password, ...scope,
+    });
+    return { session, providerId: null, isNewUser: false };
+  }
+  const link = credential.emailLink;
+  const usesLink = link !== null;
+  if (!usesLink) throw invalidCredential();
+  const { user, isNewUser } = resolveEmailLinkIdentity(auth, credential.email, link);
+  const session = sandbox.mintSession(auth, {
+    kind: 'provider', uid: user.uid, providerId: EMAIL_PROVIDER_ID, ...scope,
+  });
+  return { session, providerId: null, isNewUser };
+}
+
+function invalidCredential(): FirebaseError {
+  return new FirebaseError('auth/invalid-credential', 'signInWithCredential: the email credential is invalid.');
+}

package/src/serve/worker/host/auth-reauthentication.ts

@@ -1,7 +1,7 @@
 import { FirebaseError } from 'pyric/app';
 import { AuthCredential, OAuthProvider, reauthenticateWithCredential, reauthenticateWithPopup,
   type MintedSession, type UserCredential } from 'pyric/auth';
-import { withoutJwtClaims } from 'pyric/sandbox/internal';
+import { rulesTokenFromIdToken } from 'pyric/sandbox/internal';
 import type { OpMessage } from '../protocol.js';
 import { requireMatchingPortSession } from './auth-session-seeder.js';
 
@@ -33,7 +33,7 @@ export async function reauthenticateSession(current: MintedSession | null, messa
   }
   const user = Object.assign(result.user, { tenantId: original.user.tenantId });
   const token = await user.getIdTokenResult();
-  // Rules read the token claim set without the JWT registered claims, as a fresh session does.
-  const session: MintedSession = { user, state: { ...original.state, token: withoutJwtClaims(token.claims) } };
+  // Rules read the full token claim set, JWT registered claims included, as a fresh session does.
+  const session: MintedSession = { user, state: { ...original.state, token: rulesTokenFromIdToken(token.claims) } };
   return { session, providerId: result.providerId };
 }

package/src/serve/worker/host/rules.ts

@@ -17,9 +17,9 @@ import { LOCKED_DATABASE_RULES, withDatabaseRulesPreservedOnReset } from 'pyric/
 import { setRules } from 'pyric/sandbox/firestore';
 import {
   lintFirestoreRules,
-  parseToASTOrError,
   rulesSourceRejection,
   type CompileLimitViolation,
+  type RulesSourceRejection,
 } from 'pyric/rules/internal';
 import { rtdbRulesSourceRejection } from 'pyric/rules/internal/rtdb';
 import { sandbox as rtdbSandbox } from 'pyric/database';
@@ -182,7 +182,46 @@ function compileLimitMessages(violations: readonly CompileLimitViolation[]) {
   }));
 }
 
-/** Deploy Firestore rules to the sandbox and update `ctx.activeRules.firestore`, refusing non-`cloud.firestore` services. */
+/** Production's refusal of a Firestore source, as error messages at the line and column it reports. */
+function rejectionMessages(rejection: RulesSourceRejection): ActiveRulesState['messages'] {
+  return rejection.kind === 'parse'
+    ? [{ severity: 'error', text: `Firestore ${rejection.message}`, line: rejection.line, column: rejection.column }]
+    : compileLimitMessages(rejection.violations);
+}
+
+/**
+ * The status of `source`, the Firestore rules the sandbox now enforces, for a
+ * path that installed them without {@link deployFirestoreRulesToHost} (a
+ * tool's seed, a promoted branch, a restored checkpoint). A source production
+ * would not load is `error` with production's reason, never `active`: the
+ * sandbox evaluates no request against it. `previous` is the status it
+ * replaces, whose rules stay the last known good ones.
+ */
+export function enforcedFirestoreRulesState(
+  source: string,
+  previous: ActiveRulesState | undefined,
+  activeMessages: ActiveRulesState['messages'] = [],
+): ActiveRulesState {
+  const rejection = rulesSourceRejection(source);
+  if (rejection === null) {
+    return { status: 'active', source, lastKnownGood: source, updatedAt: Date.now(), messages: activeMessages };
+  }
+  const lastKnownGood = previous?.status === 'active' ? previous.source : previous?.lastKnownGood;
+  return {
+    status: 'error',
+    source,
+    updatedAt: Date.now(),
+    messages: rejectionMessages(rejection),
+    ...(lastKnownGood === undefined ? {} : { lastKnownGood }),
+  };
+}
+
+/**
+ * Deploy Firestore rules to the sandbox and update `ctx.activeRules.firestore`.
+ * A source production's load check refuses (it does not parse, names a
+ * service other than `cloud.firestore`, or is past a compile limit) is not
+ * installed, and is reported with the reason every plane gives.
+ */
 export function deployFirestoreRulesToHost(ctx: HostCtx, source: string): {
   ok: boolean;
   warnings: ReturnType<typeof lintFirestoreRules>['warnings'];
@@ -190,27 +229,13 @@ export function deployFirestoreRulesToHost(ctx: HostCtx, source: string): {
   rejectionMessage: string | null;
 } {
   const rejection = rulesSourceRejection(source);
-  const parsed = rejection === null ? parseToASTOrError(source) : null;
-  const wrongService = parsed !== null && parsed.ok && parsed.ast.service && parsed.ast.service.name !== 'cloud.firestore'
-    ? parsed.ast.service
-    : null;
-  const refused = rejection !== null || wrongService !== null;
+  const refused = rejection !== null;
   const result = refused ? lintFirestoreRules(source) : setRules(ctx.sandbox, source);
-  const wrongServiceText = wrongService !== null
-    ? `Expected 'service cloud.firestore', got 'service ${wrongService.name}'.`
-    : null;
-  const messages = wrongService !== null
-    ? [{
-        severity: 'error' as const,
-        text: wrongServiceText!,
-        ...(wrongService.loc ? { line: wrongService.loc.line } : {}),
-      }]
-    : rejection === null
-      ? firestoreRuleMessages(result)
-      : rejection.kind === 'parse'
-        ? [{ severity: 'error' as const, text: `Firestore ${rejection.message}`, line: rejection.line, column: rejection.column }]
-        : compileLimitMessages(rejection.violations);
-  const okDeploy = !messages.some((m) => m.severity === 'error');
+  const messages = rejection === null ? firestoreRuleMessages(result) : rejectionMessages(rejection);
+  // `ok` reports whether the rules took effect. An installed ruleset with an
+  // error-severity lint finding (an always-true `match /{document=**}`) is
+  // in force, as production deploys it; its findings stay in `messages`.
+  const okDeploy = !refused;
   ctx.activeRules ??= {};
   const previous = ctx.activeRules.firestore?.status === 'active'
     ? ctx.activeRules.firestore.source
@@ -224,11 +249,7 @@ export function deployFirestoreRulesToHost(ctx: HostCtx, source: string): {
     messages,
     ...(previous ? { lastKnownGood: previous } : {}),
   };
-  const rejectionMessage = wrongServiceText !== null
-    ? `Firestore rules did not compile: ${wrongServiceText}`
-    : rejection !== null
-      ? `Firestore ${rejection.message}`
-      : null;
+  const rejectionMessage = rejection !== null ? `Firestore ${rejection.message}` : null;
   return { ok: okDeploy, warnings: result.warnings, messages, rejectionMessage };
 }
 
@@ -236,13 +257,11 @@ export function deployFirestoreRulesToHost(ctx: HostCtx, source: string): {
 export function syncHostRulesAfterCheckpointRestore(ctx: HostCtx, rules: SandboxRuleSources): void {
   if (rules.firestore.length > 0) {
     ctx.activeRules ??= {};
-    ctx.activeRules.firestore = {
-      source: rules.firestore,
-      lastKnownGood: rules.firestore,
-      updatedAt: Date.now(),
-      status: 'active',
-      messages: firestoreRuleMessages(lintFirestoreRules(rules.firestore)),
-    };
+    ctx.activeRules.firestore = enforcedFirestoreRulesState(
+      rules.firestore,
+      ctx.activeRules.firestore,
+      firestoreRuleMessages(lintFirestoreRules(rules.firestore)),
+    );
   } else if (ctx.activeRules) {
     delete ctx.activeRules.firestore;
   }

package/src/serve/worker/host/staged-sign-in-results.ts

@@ -0,0 +1,53 @@
+/**
+ * Sign-in results a served test staged with `sandbox.mockSignInResult`
+ * (`auth.mockSignInResult`), kept per port (#1466).
+ *
+ * Each port has one slot per provider id: the last result staged wins, and a
+ * sign-in uses it up. That is in-page's rule (`AuthFlowRegistry.setMockResult`
+ * and `consumeMockResult`). Keying by port means one tab, or one register
+ * process, can't stage a sign-in for another, as in-page where each tab has
+ * its own Auth. The host clears a port's slots when it tears the port down,
+ * since a torn-down port can be reused (a Node host session resume, an
+ * app-config eviction). They are never persisted.
+ */
+
+import type { PortLike } from '../host-context.js';
+import type { ResolvedIdentity } from '../protocol.js';
+
+export interface StagedSignInResults {
+  /** Stage `identity` for the port's next sign-in with `identity.providerId`. */
+  stage(port: PortLike, identity: ResolvedIdentity): void;
+  /** Use up the port's staged result for `providerId`, or `null` when none. */
+  take(port: PortLike, providerId: string): ResolvedIdentity | null;
+  /** Drop everything the port staged, when the host tears the port down. */
+  clear(port: PortLike): void;
+}
+
+export function createStagedSignInResults(): StagedSignInResults {
+  const slotsByPort = new WeakMap<PortLike, Map<string, ResolvedIdentity>>();
+
+  function slotsFor(port: PortLike): Map<string, ResolvedIdentity> {
+    let slots = slotsByPort.get(port);
+    if (slots === undefined) {
+      slots = new Map();
+      slotsByPort.set(port, slots);
+    }
+    return slots;
+  }
+
+  return {
+    stage(port, identity) {
+      slotsFor(port).set(identity.providerId, identity);
+    },
+    take(port, providerId) {
+      const slots = slotsByPort.get(port);
+      const staged = slots?.get(providerId);
+      if (staged === undefined) return null;
+      slots?.delete(providerId);
+      return staged;
+    },
+    clear(port) {
+      slotsByPort.delete(port);
+    },
+  };
+}

package/src/serve/worker/host/storage.ts

@@ -35,6 +35,7 @@ import {
   copyObject,
   getAdminStorageSandbox,
   getStorageService,
+  nameStorageBucket,
   patchObjectMetadata,
   storageAuth,
   storageOperationProvenance,
@@ -333,6 +334,20 @@ function lensStorage(ctx: HostCtx, actAs: AuthLens | undefined, port: PortLike,
   return handle;
 }
 
+/**
+ * The handle one op runs on: its lens, on the bucket it stores in, under the
+ * name the caller knows that bucket by. Rules see that name (ST-H2-4); the
+ * store keeps its own key.
+ */
+function opStorage(
+  ctx: HostCtx,
+  msg: StorageBucketWire & { actAs?: AuthLens },
+  port: PortLike,
+  bucket: string = bucketOfOp(ctx, msg),
+): FirebaseStorage {
+  return nameStorageBucket(lensStorage(ctx, msg.actAs, port, bucket), bucketNameOf(ctx, msg, bucket));
+}
+
 /**
  * {@link lensStorage} for a bucket other than the default one: the same
  * lenses, on a handle scoped to `bucket`. Each bucket's objects are its own;
@@ -472,7 +487,7 @@ export async function handleStorageOp(
       // under the op's lens (admin lens bypasses — see lensStorage).
       try {
         const storage = bindStorageOperationContext(
-          lensStorage(ctx, msg.actAs, port, bucketOfOp(ctx, msg)),
+          opStorage(ctx, msg, port),
           opProvenance(msg),
         );
         const result = await storageListAll(storageRef(storage, msg.path));
@@ -487,7 +502,7 @@ export async function handleStorageOp(
     case 'storage.getMetadata': {
       try {
         const storage = bindStorageOperationContext(
-          lensStorage(ctx, msg.actAs, port, bucketOfOp(ctx, msg)),
+          opStorage(ctx, msg, port),
           opProvenance(msg),
         );
         // FullMetadata is plain JSON (bucket/fullPath/name/size/contentType/...).
@@ -505,7 +520,7 @@ export async function handleStorageOp(
       // object's metadata, as production keeps it, and is minted on first use.
       try {
         const storage = bindStorageOperationContext(
-          lensStorage(ctx, msg.actAs, port, bucketOfOp(ctx, msg)),
+          opStorage(ctx, msg, port),
           opProvenance(msg),
         );
         const r = storageRef(storage, msg.path);
@@ -539,7 +554,7 @@ export async function handleStorageOp(
         if (!adminPlane) {
           throw new FirebaseError('storage/unauthorized', 'storage.setMetadata is the admin plane (firebase-admin File.setMetadata) and runs only on the admin lens.');
         }
-        const storage = bindStorageOperationContext(lensStorage(ctx, msg.actAs, port, bucketOfOp(ctx, msg)), opProvenance(msg));
+        const storage = bindStorageOperationContext(opStorage(ctx, msg, port), opProvenance(msg));
         const result = await patchObjectMetadata(storageRef(storage, msg.path), msg.patch);
         await bestEffortFlush(ctx, msg.method);
         ok(port, msg.id, namedMetadata(ctx, msg, result));
@@ -554,7 +569,7 @@ export async function handleStorageOp(
       // callers use `storage.getBytes` (base64) instead.
       try {
         const storage = bindStorageOperationContext(
-          lensStorage(ctx, msg.actAs, port, bucketOfOp(ctx, msg)),
+          opStorage(ctx, msg, port),
           opProvenance(msg),
         );
         ok(
@@ -589,7 +604,7 @@ export async function handleStorageOp(
         }
         const bucket = bucketOfOp(ctx, msg);
         const storage = bindStorageOperationContext(
-          lensStorage(ctx, msg.actAs, port, bucket),
+          opStorage(ctx, msg, port, bucket),
           opProvenance(msg),
         );
         const target = storageRef(storage, msg.path);
@@ -621,7 +636,7 @@ export async function handleStorageOp(
         }
         const downloadTokens = uploadDownloadTokens(msg);
         const storage = bindStorageOperationContext(
-          lensStorage(ctx, msg.actAs, port, bucketOfOp(ctx, msg)),
+          opStorage(ctx, msg, port),
           opProvenance(msg),
         );
         const r = storageRef(storage, msg.path);
@@ -706,7 +721,7 @@ export async function handleStorageOp(
           throw new FirebaseError('storage/object-not-found', `Upload '${msg.uploadId}' not found or already completed.`);
         }
         const storage = bindStorageOperationContext(
-          lensStorage(ctx, msg.actAs, port, pending!.bucket),
+          nameStorageBucket(lensStorage(ctx, msg.actAs, port, pending!.bucket), pending!.bucketName),
           opProvenance(msg),
         );
         const service = await getStorageService(storage);
@@ -752,7 +767,7 @@ export async function handleStorageOp(
       // superseding `not-found`, matching pyric/storage).
       try {
         const storage = bindStorageOperationContext(
-          lensStorage(ctx, msg.actAs, port, bucketOfOp(ctx, msg)),
+          opStorage(ctx, msg, port),
           opProvenance(msg),
         );
         const r = storageRef(storage, msg.path);
@@ -815,7 +830,7 @@ export async function handleStorageOp(
       // explicitly (issue #84 item 3).
       try {
         const storage = bindStorageOperationContext(
-          lensStorage(ctx, msg.actAs, port, bucketOfOp(ctx, msg)),
+          opStorage(ctx, msg, port),
           opProvenance(msg),
         );
         await storageDeleteObject(storageRef(storage, msg.path));
@@ -854,7 +869,7 @@ export async function handleStorageOp(
           throw new FirebaseError('storage/unauthorized', 'storage.copyObject is the admin plane (firebase-admin File.copy) and runs only on the admin lens.');
         }
         const provenance = opProvenance(msg);
-        const source = bindStorageOperationContext(lensStorage(ctx, msg.actAs, port, bucketOfOp(ctx, msg)), provenance);
+        const source = bindStorageOperationContext(opStorage(ctx, msg, port), provenance);
         const destinationBucket = storeBucketOf(ctx, msg.destinationBucket);
         const destination = bindStorageOperationContext(lensStorage(ctx, msg.actAs, port, destinationBucket), provenance);
         const result = await copyObject(storageRef(source, msg.path), storageRef(destination, msg.destinationPath), msg.patch ?? {}, provenance);

package/src/serve/worker/host/subscriptions.ts

@@ -261,6 +261,7 @@ function registerListener(
           path?: string;
           exists: boolean | (() => boolean);
           data(): Record<string, unknown>;
+          metadata?: { hasPendingWrites?: boolean };
         }>;
       };
 
@@ -268,10 +269,12 @@ function registerListener(
       // offline cache, so `fromCache` is always false and is not sent.
       const hasPendingWrites = snapAny.metadata?.hasPendingWrites === true;
       if (Array.isArray(snapAny.docs)) {
-        // Query snapshot
-        const docs = snapAny.docs.map((d) =>
-          serializeDocSnap(d as Parameters<typeof serializeDocSnap>[0]),
-        );
+        // Query snapshot. Each document sends its own pending state, which
+        // production reports per document (FP-5, #1358).
+        const docs = snapAny.docs.map((d) => ({
+          ...serializeDocSnap(d as Parameters<typeof serializeDocSnap>[0]),
+          hasPendingWrites: d.metadata?.hasPendingWrites === true,
+        }));
         post(port, { t: 'snap', subId: msg.subId, value: { docs, hasPendingWrites, usage } });
       } else if (snapAny.id !== undefined) {
         // Doc snapshot