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

package/src/auth/sandbox-backend.ts

@@ -48,9 +48,11 @@ import {
   createAuthProjectStore,
   type AuthProjectStore,
 } from './sandbox/project-store.js';
+import { defaultAvatarMint, type AvatarMint } from './sandbox/default-avatar.js';
 
-import type { AuthState, Sandbox } from 'pyric/sandbox';
-import { emitSandboxEvent, makeServiceMutationEvent } from 'pyric/sandbox/internal';
+import { normalizeAuthState, type AuthState, type Sandbox } from 'pyric/sandbox';
+import { emitSandboxEvent, getClock, makeServiceMutationEvent } from 'pyric/sandbox/internal';
+import type { AuthEventOperation } from './events.js';
 
 import {
   USER_INTERNAL,
@@ -98,6 +100,17 @@ export type {
  * sibling app backends share account/provider maps but not currentUser,
  * listeners, tokens, flow staging, or persistence mode.
  */
+
+/**
+ * The claims rules see on `auth.token` for a signed-in data context: the
+ * custom claims, plus the `firebase` namespace the minted ID token carries
+ * (`sign_in_provider`, and `tenant` for a tenant sign-in), as production's
+ * decoded ID token does.
+ */
+function rulesTokenClaims(claims: Record<string, unknown>, minted: IdTokenResult): Record<string, unknown> {
+  return { ...claims, firebase: minted.claims.firebase };
+}
+
 export class SandboxBackend {
   /** Email → stored user. Lowercase keys so lookups are case-
    *  insensitive (matches upstream). */
@@ -131,7 +144,6 @@ export class SandboxBackend {
   /** Monotonic uid counter for `createUser` calls without a uid. */
   private readonly sharedCounters: {
     nextAdminUserId: number;
-    nextAnonymousId: number;
   };
 
   /** Popup / redirect / credential flow-staging machinery — the
@@ -165,12 +177,12 @@ export class SandboxBackend {
    *  (direct sandbox writes, `reset()`, another handle). */
   private applyingTransition = false;
 
-  /** Per-uid current ID token + result. Refreshed on each
+  /** Per-uid and signed-in tenant current ID token + result. Refreshed on each
    *  `getIdToken(forceRefresh=true)` and on each new sign-in
    *  transition (so a sign-out / sign-in round-trip mints a fresh
    *  token, matching prod's "new session = new token" semantics).
    *  Subsequent `getIdToken(false)` reads return the cached value. */
-  private readonly tokenCache = new Map<string, { token: string; result: IdTokenResult }>();
+  private readonly tokenCache = new Map<string, Map<string | null, { token: string; result: IdTokenResult }>>();
 
   /** Monotonic counter used to disambiguate freshly-minted tokens
    *  for the same uid + claims map. Without this, two refreshes that
@@ -248,6 +260,42 @@ export class SandboxBackend {
    *  persisted: a runtime wiring decision, not project config. */
   private providerEnforcementDelegated = false;
 
+  /**
+   * The hook that assigns a default `photoURL` to a federated-provider record
+   * at creation (see {@link makeStored}). The built-in mint returns a
+   * deterministic SVG data URI, which resolves with no server at all — so an
+   * in-page sandbox and any host that configures nothing behave identically.
+   *
+   * A HOST OVERRIDES IT ({@link setAvatarMint}): the served dev server swaps in
+   * a mint that returns its `/__pyric/assets/avatar/<uid>` route, and a server
+   * with avatars disabled swaps in one that returns `null`, which restores
+   * Firebase's own no-photo behaviour. Not persisted: a runtime wiring
+   * decision, not project config — but the URL it returns IS persisted, so a
+   * host must install its mint before any user record is created.
+   */
+  private avatarMint: AvatarMint = defaultAvatarMint;
+
+  /**
+   * Tenant the NEXT sign-in through this handle authenticates against, or
+   * `null` for the project-level pool. Backs `Auth.tenantId`: the handle is a
+   * thin accessor over this field, so the value an app assigns before calling
+   * a sign-in function is the value {@link applyTenantScope} stamps onto the
+   * user and its stored record.
+   */
+  private tenantId: string | null = null;
+
+  /** Read `Auth.tenantId`. */
+  getTenantId(): string | null {
+    return this.tenantId;
+  }
+
+  /** Write `Auth.tenantId`. Takes effect on the next sign-in; the current
+   *  session keeps the tenant it authenticated with, matching prod, where the
+   *  tenant is fixed at the moment credentials are exchanged. */
+  setTenantId(tenantId: string | null): void {
+    this.tenantId = tenantId;
+  }
+
   constructor(
     sandbox: Sandbox,
     session: Pick<Sandbox, 'currentUser' | 'onCurrentUserChanged'> = sandbox,
@@ -311,6 +359,20 @@ export class SandboxBackend {
     return this.cachedUser;
   }
 
+  /**
+   * The provider the current session signed in through. This is the same
+   * value {@link mintToken} puts on `IdTokenResult.signInProvider` and on the
+   * `firebase.sign_in_provider` claim, read without minting a token.
+   *
+   * `null` while the app is signed out, and `null` for an identity driven
+   * straight through the test driver, which records no provider.
+   */
+  getCurrentSignInProvider(): string | null {
+    const user = this.cachedUser;
+    if (user === null) return null;
+    return this.signInProviderByUid.get(user.uid) ?? null;
+  }
+
   // ─── Listener registries ────────────────────────────────────────────
 
   /**
@@ -412,11 +474,26 @@ export class SandboxBackend {
 
   // ─── User DB ────────────────────────────────────────────────────────
 
-  /** Build a fresh {@link StoredUser} with admin-field defaults. */
+  /**
+   * Build a fresh {@link StoredUser} with admin-field defaults.
+   *
+   * THE ONE PLACE A DEFAULT PHOTO IS ASSIGNED. A federated-provider record
+   * that arrives without a photo gets one from {@link avatarMint} here, so
+   * `photoURL` is populated the instant the user object exists — never null
+   * for a moment and then patched. Every other path is untouched: an update,
+   * `updateProfile`, or `linkProvider` on an existing record never mints, and
+   * a caller-supplied photo always wins (see {@link mintsDefaultPhoto}).
+   *
+   * `signInProviderId` is the provider a flow is creating this record under,
+   * for the two paths that link the provider AFTER the record exists
+   * (`recordProviderSignIn`, `createSignInCredential`). Every other path
+   * carries its providers in `init.providerUserInfo`.
+   */
   private makeStored(
     init: Partial<StoredUser> & { uid: string },
+    signInProviderId: string | null = null,
   ): StoredUser {
-    return {
+    const record: StoredUser = {
       email: null,
       password: null,
       displayName: null,
@@ -427,10 +504,21 @@ export class SandboxBackend {
       providerUserInfo: [],
       disabled: false,
       emailVerified: false,
-      createdAt: new Date().toISOString(),
+      createdAt: this.now().toISOString(),
       lastLoginAt: null,
+      tenantId: null,
       ...init,
     };
+    const providerId = creationProviderId(record, signInProviderId);
+    if (mintsDefaultPhoto(record, providerId)) {
+      record.photoUrl = this.avatarMint({
+        uid: record.uid,
+        displayName: record.displayName,
+        email: record.email,
+        providerId,
+      });
+    }
+    return record;
   }
 
   /** Fan a coarse "user DB changed" notification out to
@@ -446,6 +534,17 @@ export class SandboxBackend {
     }
   }
 
+  /**
+   * The sandbox's current time. Every time this backend records reads it: an
+   * account's `createdAt` and `lastLoginAt`, and a minted token's `iat`,
+   * `auth_time`, and `exp`. So a token minted while the sandbox clock is
+   * pinned to a date carries that date, and a rule reading
+   * `request.auth.token.iat` sees the same instant the write pipeline stamps.
+   */
+  private now(): Date {
+    return getClock(this.sandbox).date();
+  }
+
   /**
    * Emit an auth {@link ServiceMutationEvent} onto the sandbox's unified
    * `onEvent`/`history()` stream (Pyric Studio keystone). Best-effort and
@@ -457,13 +556,14 @@ export class SandboxBackend {
    * via `stampProvenance`.
    */
   private emitAuthEvent(
-    op: string,
+    op: AuthEventOperation,
     fields: { path?: string; auth?: AuthState; before?: unknown; after?: unknown; detail?: Record<string, unknown> } = {},
   ): void {
     try {
       emitSandboxEvent(
         this.sandbox,
         makeServiceMutationEvent({
+          at: this.now().getTime(),
           service: 'auth',
           op,
           path: fields.path,
@@ -556,6 +656,17 @@ export class SandboxBackend {
     this.providerEnforcementDelegated = delegated;
   }
 
+  /**
+   * Install the {@link AvatarMint} this backend assigns default photos with,
+   * replacing the built-in data-URI mint. A host installs its mint during
+   * boot, before it seeds or signs anyone in: the minted URL is written into
+   * the stored record, so records created earlier keep the mint that was
+   * installed when they were created.
+   */
+  setAvatarMint(mint: AvatarMint): void {
+    this.avatarMint = mint;
+  }
+
   /**
    * Gate a provider entry point. Throws real Firebase's
    * `auth/operation-not-allowed` (exactly the code/shape prod throws
@@ -694,46 +805,94 @@ export class SandboxBackend {
       // in (AUTH-B9) — otherwise both emails would resolve, the old one
       // to a now-orphaned record.
       const prior = this.usersByUid.get(u.uid);
-      if (prior?.email && prior.email.toLowerCase() !== u.email.toLowerCase()) {
-        this.usersByEmail.delete(prior.email.toLowerCase());
+      const priorEmail = prior?.email;
+      const hasPriorEmail = typeof priorEmail === 'string' && priorEmail.length > 0;
+      const changesEmail = hasPriorEmail && priorEmail.toLowerCase() !== u.email?.toLowerCase();
+      if (changesEmail) {
+        this.usersByEmail.delete(priorEmail.toLowerCase());
       }
+      const isAnonymousSeed = u.providerId === 'anonymous';
+      const linkedProviders = u.providerUserInfo ?? [{ providerId: u.providerId ?? 'password' }];
+      const providerUserInfo = isAnonymousSeed ? [] : linkedProviders.map(provider => ({ ...provider }));
+      const hasPasswordProvider = providerUserInfo.some(provider => provider.providerId === 'password');
+      const hasLegacyPlaceholder = u.password === NO_PASSWORD_SENTINEL || u.password === '__pyric_popup_no_password__';
+      const isLegacyPasswordlessAccount = hasLegacyPlaceholder && !hasPasswordProvider;
+      const hasNoPassword = isAnonymousSeed || isLegacyPasswordlessAccount;
       const record = this.makeStored({
         uid: u.uid,
-        email: u.email,
-        password: u.password,
+        email: isAnonymousSeed ? null : (u.email ?? null),
+        password: hasNoPassword ? null : (u.password ?? null),
         displayName: u.displayName ?? null,
+        phoneNumber: u.phoneNumber ?? null,
+        photoUrl: u.photoUrl ?? null,
         customClaims: u.customClaims ?? {},
-        providerUserInfo: [{ providerId: u.providerId ?? 'password' }],
+        emailVerified: u.emailVerified ?? false,
+        disabled: u.disabled ?? false,
+        isAnonymous: isAnonymousSeed,
+        providerUserInfo,
+        tenantId: u.tenantId ?? null,
       });
-      this.usersByEmail.set(u.email.toLowerCase(), record);
+      const { createdAt, lastLoginAt, email } = u;
+      const hasCreatedAt = createdAt !== undefined;
+      if (hasCreatedAt) record.createdAt = createdAt;
+      const hasLastLoginAt = lastLoginAt !== undefined;
+      if (hasLastLoginAt) record.lastLoginAt = lastLoginAt;
+      const indexesEmail = !isAnonymousSeed && email !== undefined;
+      if (indexesEmail) this.usersByEmail.set(email.toLowerCase(), record);
       this.usersByUid.set(u.uid, record);
     }
-    if (users.length > 0) this.notifyUsersChanged();
+    const hasSeedUsers = users.length > 0;
+    if (hasSeedUsers) this.notifyUsersChanged();
   }
 
   /**
    * Export the user DB as `SeedUser`s — the exact shape `seedUsers`
-   * accepts, so export → seed round-trips (the persistence substrate,
-   * the design rationale section 3c). Identities with an email but no
-   * password (provider-flow users created via `createSignInCredential`)
-   * export with {@link NO_PASSWORD_SENTINEL} so they survive the
-   * round-trip (same trick hosts already use when seeding popup
-   * identities). Anonymous users (no email) are NOT exported — they are
-   * ephemeral by design; documented divergence from prod's persisted
-   * anonymous sessions.
+   * accepts, including every linked provider. Passwordless accounts omit
+   * the password; legacy placeholder values are decoded only on import.
+   * Anonymous users (no email) export with
+   * `providerId: 'anonymous'` and no email or password, so a checkpoint,
+   * a branch, and a restart keep them, matching real Firebase, which
+   * keeps anonymous accounts in its user pool rather than discarding them.
    */
   exportUsers(): SeedUser[] {
     const out: SeedUser[] = [];
     for (const u of this.usersByUid.values()) {
-      if (u.email === null) continue; // anonymous — not round-trippable
+      const { email, displayName, photoUrl, tenantId, phoneNumber, isAnonymous, disabled, emailVerified } = u;
+      const hasDisplayName = displayName !== null;
+      const hasPhotoUrl = photoUrl !== null;
+      const hasCustomClaims = Object.keys(u.customClaims).length > 0;
+      const hasTenant = tenantId !== null;
+      if (isAnonymous) {
+        const seed: SeedUser = { uid: u.uid, providerId: 'anonymous', createdAt: u.createdAt, lastLoginAt: u.lastLoginAt };
+        if (hasDisplayName) seed.displayName = displayName;
+        if (hasPhotoUrl) seed.photoUrl = photoUrl;
+        if (hasCustomClaims) seed.customClaims = u.customClaims;
+        if (disabled) seed.disabled = true;
+        if (hasTenant) seed.tenantId = tenantId;
+        out.push(seed);
+        continue;
+      }
+      const hasNoEmail = email === null;
+      if (hasNoEmail) continue; // credential-less, non-anonymous: not round-trippable
       const seed: SeedUser = {
         uid: u.uid,
-        email: u.email,
-        password: u.password ?? NO_PASSWORD_SENTINEL,
+        createdAt: u.createdAt,
+        lastLoginAt: u.lastLoginAt,
+        email,
         providerId: u.providerUserInfo[0]?.providerId ?? 'password',
+        providerUserInfo: u.providerUserInfo.map(provider => ({ ...provider })),
       };
-      if (u.displayName !== null) seed.displayName = u.displayName;
-      if (Object.keys(u.customClaims).length > 0) seed.customClaims = u.customClaims;
+      const { password } = u;
+      const hasPassword = password !== null;
+      if (hasPassword) seed.password = password;
+      if (hasDisplayName) seed.displayName = displayName;
+      if (hasPhotoUrl) seed.photoUrl = photoUrl;
+      const hasPhoneNumber = phoneNumber !== null;
+      if (hasPhoneNumber) seed.phoneNumber = phoneNumber;
+      if (hasCustomClaims) seed.customClaims = u.customClaims;
+      if (emailVerified) seed.emailVerified = true;
+      if (disabled) seed.disabled = true;
+      if (hasTenant) seed.tenantId = tenantId;
       out.push(seed);
     }
     return out;
@@ -892,8 +1051,10 @@ export class SandboxBackend {
     validateEmailFormat(email);
     const key = email.toLowerCase();
     const existing = this.usersByEmail.get(key);
-    if (existing) {
-      if (!existing.providerUserInfo.some((p) => p.providerId === 'password')) {
+    const hasAccount = existing !== undefined;
+    if (hasAccount) {
+      const needsPasswordProvider = !existing.providerUserInfo.some((p) => p.providerId === 'password');
+      if (needsPasswordProvider) {
         existing.providerUserInfo.push({ providerId: 'password' });
       }
       // Redeeming a link mailed to this address proves control of it.
@@ -901,7 +1062,8 @@ export class SandboxBackend {
       this.notifyUsersChanged();
       return { stored: existing, isNewUser: false };
     }
-    const uid = `email-${key}-${this.usersByEmail.size + 1}`;
+    // Email punctuation is invalid in common UID-keyed RTDB paths.
+    const uid = `email-${globalThis.crypto.randomUUID()}`;
     const record = this.makeStored({
       uid,
       email,
@@ -1042,13 +1204,15 @@ export class SandboxBackend {
     validateEmailFormat(email);
     validatePasswordStrength(password);
     const key = email.toLowerCase();
-    if (this.usersByEmail.has(key)) {
+    const emailInUse = this.usersByEmail.has(key);
+    if (emailInUse) {
       throw makeAuthError(
         'auth/email-already-in-use',
         `An account already exists for ${email}.`,
       );
     }
-    const uid = `email-${key}-${this.usersByEmail.size + 1}`;
+    // Email punctuation is invalid in common UID-keyed RTDB paths.
+    const uid = `email-${globalThis.crypto.randomUUID()}`;
     const record = this.makeStored({
       uid,
       email,
@@ -1160,6 +1324,13 @@ export class SandboxBackend {
    * pre-resolved promise on the fast path instead of ever suspending.
    */
   transitionCurrentUser(user: User | null, signInProvider?: string | null): Promise<void> {
+    // A `signInProvider` argument marks a REAL sign-in, which is the moment
+    // the tenant is fixed (the test driver omits it and leaves the tenant
+    // alone). Applied before the gate runs so a `beforeAuthStateChanged`
+    // callback inspecting the user sees the tenant it will sign in under.
+    if (user !== null && signInProvider !== undefined) {
+      this.scopeSignInToTenant(user);
+    }
     const hasActiveGate = this.beforeStateSubs.some((reg) => reg.active);
     if (!hasActiveGate || user === this.cachedUser) {
       this.setCurrentUser(user, signInProvider);
@@ -1187,8 +1358,24 @@ export class SandboxBackend {
    * test driver (`sandbox.setUser`), which leaves any previous value
    * in place.
    */
+  /**
+   * Fix a signing-in user to the handle's current {@link tenantId}. This is
+   * the sandbox's stand-in for Identity Platform resolving credentials against
+   * one tenant's user pool. The value lands in two places: on the `User` (so
+   * `user.tenantId` reads back, matching `firebase/auth`) and on the stored
+   * record (so a session restored after a reload, which rebuilds the user from
+   * that record, keeps the tenant it authenticated with).
+   */
+  private scopeSignInToTenant(user: User): void {
+    const tenantId = this.tenantId;
+    (user as Mutable<User>).tenantId = tenantId;
+    const stored = this.usersByUid.get(user.uid);
+    if (stored) stored.tenantId = tenantId;
+  }
+
   setCurrentUser(user: User | null, signInProvider?: string | null): void {
-    if (user === null) {
+    const signsOut = user === null;
+    if (signsOut) {
       // Sign-out. Drop the cached token so a later re-sign-in for the
       // same uid mints a fresh one ("new session = new token"). Fire
       // listeners only if we were actually signed in (signing out an
@@ -1201,7 +1388,8 @@ export class SandboxBackend {
       } finally {
         this.applyingTransition = false;
       }
-      if (previousUser) {
+      const hadUser = previousUser !== null;
+      if (hadUser) {
         this.tokenCache.delete(previousUser.uid);
         this.notifyAuthListeners();
         this.notifySessionChanged();
@@ -1216,9 +1404,10 @@ export class SandboxBackend {
       return;
     }
 
+    const isSignIn = signInProvider !== undefined;
     // Record this session's provider BEFORE any token mint below so
     // the freshly-minted token carries the right sign_in_provider.
-    if (signInProvider !== undefined) {
+    if (isSignIn) {
       this.signInProviderByUid.set(user.uid, signInProvider);
     }
 
@@ -1230,8 +1419,9 @@ export class SandboxBackend {
 
     // A `signInProvider` argument marks an actual sign-in (the test
     // driver omits it) — bump the record's lastLoginAt.
-    if (signInProvider !== undefined && stored) {
-      stored.lastLoginAt = new Date().toISOString();
+    const recordsSignIn = isSignIn && stored !== undefined;
+    if (recordsSignIn) {
+      stored.lastLoginAt = this.now().toISOString();
       this.notifyUsersChanged();
     }
 
@@ -1242,12 +1432,15 @@ export class SandboxBackend {
     // is unchanged (AUTH-B8: a same-uid re-sign-in still rotates the
     // token, which `onIdTokenChanged` then observes). Matches prod's
     // "new session = new token".
-    this.tokenCache.set(user.uid, this.mintToken(user.uid, claims));
+    const minted = this.mintToken(user.uid, claims, user.tenantId ?? null);
 
     // Push to the sandbox under the guard so the synchronous subscriber
     // doesn't notify — we drive the fan-out below with the correct
     // id-token / auth-state split.
-    const nextState: AuthState = { uid: user.uid, token: claims };
+    const signedInState: NonNullable<AuthState> = { uid: user.uid, token: rulesTokenClaims(claims, minted.result) };
+    const hasTenant = typeof user.tenantId === 'string';
+    if (hasTenant) signedInState.tenant = user.tenantId;
+    const nextState: AuthState = signedInState;
     this.applyingTransition = true;
     try {
       this.session.currentUser = nextState;
@@ -1265,7 +1458,7 @@ export class SandboxBackend {
     // the test driver (`sandbox.setUser`) omits it and is not a sign-in
     // worth surfacing on the activity stream. The acting identity IS the
     // user that just signed in.
-    if (signInProvider !== undefined) {
+    if (isSignIn) {
       this.emitAuthEvent('sign_in', {
         path: user.uid,
         auth: nextState,
@@ -1310,21 +1503,27 @@ export class SandboxBackend {
    * with its real provider. Upserts: unknown uids get a fresh record
    * (no password — these identities can't sign in via
    * `signInWithEmailAndPassword`); known uids get the provider
-   * appended to `providerUserInfo` if it isn't already linked.
+   * appended to `providerUserInfo` if it isn't already linked, and their
+   * stored photo refreshed when the identity carries one (see
+   * {@link refreshStoredPhoto}).
    */
   recordProviderSignIn(user: User, providerId: string): void {
     let changed = false;
+    const identityPhotoUrl = user.photoURL ?? null;
     let stored = this.usersByUid.get(user.uid);
     if (!stored) {
       stored = this.makeStored({
         uid: user.uid,
         email: user.email,
         displayName: user.displayName,
+        photoUrl: identityPhotoUrl,
         isAnonymous: user.isAnonymous,
-      });
+      }, providerId);
       this.usersByUid.set(user.uid, stored);
       if (user.email) this.usersByEmail.set(user.email.toLowerCase(), stored);
       changed = true;
+    } else if (refreshStoredPhoto(stored, identityPhotoUrl)) {
+      changed = true;
     }
     if (!stored.providerUserInfo.some((p) => p.providerId === providerId)) {
       stored.providerUserInfo.push({ providerId });
@@ -1354,7 +1553,10 @@ export class SandboxBackend {
    *     and NO password (provider identities can't sign in via
    *     `signInWithEmailAndPassword`).
    *
-   * In both shapes the provider is linked into `providerUserInfo`.
+   * In both shapes the provider is linked into `providerUserInfo`. A
+   * `spec.photoUrl` is stored on a fresh record and refreshes a reused
+   * same-email one; a spec without a photo never clears a stored one (see
+   * {@link refreshStoredPhoto}).
    * The credential does NOT sign the user in — hand it to the
    * resolver's promise; `signInWithPopup`/`signInWithRedirect`
    * complete the sign-in.
@@ -1374,19 +1576,24 @@ export class SandboxBackend {
           `createSignInCredential: no identity with uid ${req.uid}. Use the {spec} shape to create one.`,
         );
       }
+      this.assertUserEnabled(found);
       stored = found;
     } else {
       const { spec } = req;
+      const specPhotoUrl = spec.photoUrl ?? null;
       const byEmail = this.usersByEmail.get(spec.email.toLowerCase());
       if (byEmail) {
+        this.assertUserEnabled(byEmail);
         stored = byEmail;
+        if (refreshStoredPhoto(stored, specPhotoUrl)) this.notifyUsersChanged();
       } else {
         stored = this.makeStored({
           uid: spec.uid ?? mintProviderUid(),
           email: spec.email,
           displayName: spec.displayName ?? null,
+          photoUrl: specPhotoUrl,
           customClaims: spec.customClaims ?? {},
-        });
+        }, providerId);
         this.usersByUid.set(stored.uid, stored);
         this.usersByEmail.set(spec.email.toLowerCase(), stored);
         this.notifyUsersChanged();
@@ -1447,6 +1654,7 @@ export class SandboxBackend {
       isAnonymous: u.isAnonymous,
       disabled: u.disabled,
       emailVerified: u.emailVerified,
+      tenantId: u.tenantId,
       createdAt: u.createdAt,
       lastLoginAt: u.lastLoginAt,
     };
@@ -1487,11 +1695,20 @@ export class SandboxBackend {
     return next;
   }
 
+  /** Restored or explicitly seeded users may already occupy generated IDs. */
+  private nextAvailableAdminUid(): string {
+    for (;;) {
+      const uid = `user-${this.sharedCounters.nextAdminUserId++}`;
+      const isAvailable = !this.usersByUid.has(uid);
+      if (isAvailable) return uid;
+    }
+  }
+
   /** Admin user creation. Does NOT sign the user in (unlike
    *  `createUserWithEmailAndPassword`) — matches the emulator's
    *  add-user flow / admin SDK semantics. */
   createUser(req: CreateUserRequest): AuthUserRecord {
-    const uid = req.uid ?? `user-${this.sharedCounters.nextAdminUserId++}`;
+    const uid = req.uid ?? this.nextAvailableAdminUid();
     if (this.usersByUid.has(uid)) {
       throw makeAuthError(
         'auth/uid-already-exists',
@@ -1656,6 +1873,7 @@ export class SandboxBackend {
       emailVerified: stored.emailVerified,
       phoneNumber: stored.phoneNumber,
       providers: stored.providerUserInfo,
+      tenantId: stored.tenantId,
     });
   }
 
@@ -1664,7 +1882,7 @@ export class SandboxBackend {
    *  the emulator) so `listIdentities` / future user-admin surfaces
    *  see anonymous accounts too. */
   mintAnonymousUser(): User {
-    const uid = `anonymous-${this.sharedCounters.nextAnonymousId++}`;
+    const uid = `anonymous-${globalThis.crypto.randomUUID()}`;
     const record = this.makeStored({ uid, isAnonymous: true });
     this.usersByUid.set(uid, record);
     this.notifyUsersChanged();
@@ -1706,36 +1924,44 @@ export class SandboxBackend {
    * authenticated session, same as real Firebase.
    */
   mintDetachedSession(request: MintSessionRequest): MintedSession {
+    const tenantId = request.tenantId ?? null;
     switch (request.kind) {
       case 'anonymous':
         this.assertProviderEnabled('anonymous');
-        return this.establishDetachedSession(this.mintAnonymousUser(), 'anonymous');
+        return this.establishDetachedSession(this.mintAnonymousUser(), 'anonymous', tenantId);
       case 'password':
         this.assertProviderEnabled('password');
         return this.establishDetachedSession(
           this.buildUserFromStored(this.validatePassword(request.email, request.password)),
           'password',
+          tenantId,
         );
       case 'createPassword':
         this.assertProviderEnabled('password');
         return this.establishDetachedSession(
           this.buildUserFromStored(this.createEmailPasswordUser(request.email, request.password)),
           'password',
+          tenantId,
         );
+      case 'provider':
+      case 'custom':
       case 'uid': {
+        const isProviderSignIn = request.kind === 'provider';
+        if (isProviderSignIn) this.assertProviderEnabled(request.providerId);
         // restoreSession semantics minus the global set: an EXISTING
         // identity (per-tab session restore / provider-bridge accept).
         const stored = this.usersByUid.get(request.uid);
-        if (!stored) {
+        const missingUser = stored === undefined;
+        if (missingUser) {
           throw makeAuthError('auth/user-not-found', `mintSession: no identity with uid ${request.uid}.`);
         }
-        if (stored.disabled) {
-          throw makeAuthError('auth/user-disabled', `mintSession: user ${request.uid} is disabled.`);
-        }
-        const providerId = stored.isAnonymous
-          ? 'anonymous'
-          : (stored.providerUserInfo[0]?.providerId ?? 'password');
-        return this.establishDetachedSession(this.buildUserFromStored(stored), providerId);
+        this.assertUserEnabled(stored);
+        const isAnonymous = stored.isAnonymous;
+        const restoredProvider = isAnonymous ? 'anonymous' : (stored.providerUserInfo[0]?.providerId ?? 'password');
+        let providerId = isProviderSignIn ? request.providerId : restoredProvider;
+        const isCustomSignIn = request.kind === 'custom';
+        if (isCustomSignIn) providerId = 'custom';
+        return this.establishDetachedSession(this.buildUserFromStored(stored), providerId, tenantId);
       }
     }
   }
@@ -1743,16 +1969,27 @@ export class SandboxBackend {
   /** The shared sign-in bookkeeping behind {@link mintDetachedSession} —
    *  everything {@link setCurrentUser} does for a real sign-in EXCEPT the
    *  global-session parts. */
-  private establishDetachedSession(user: User, signInProvider: string): MintedSession {
+  private establishDetachedSession(
+    user: User,
+    signInProvider: string,
+    tenantId: string | null,
+  ): MintedSession {
     this.signInProviderByUid.set(user.uid, signInProvider);
     const stored = this.usersByUid.get(user.uid);
     const claims = stored?.customClaims ?? {};
-    if (stored) {
-      stored.lastLoginAt = new Date().toISOString();
+    const hasStoredUser = stored !== undefined;
+    if (hasStoredUser) {
+      stored.lastLoginAt = this.now().toISOString();
       this.notifyUsersChanged();
     }
-    this.tokenCache.set(user.uid, this.mintToken(user.uid, claims));
-    const state = { uid: user.uid, token: claims };
+    // The tenant rides on the session, not on the shared record: ports are
+    // independent sessions over one user pool, so two ports can hold the same
+    // identity under different tenants and neither may overwrite the other.
+    (user as Mutable<User>).tenantId = tenantId;
+    const minted = this.mintToken(user.uid, claims, tenantId);
+    const state: NonNullable<AuthState> = { uid: user.uid, token: rulesTokenClaims(claims, minted.result) };
+    const hasTenant = tenantId !== null;
+    if (hasTenant) state.tenant = tenantId;
     this.emitAuthEvent('sign_in', {
       path: user.uid,
       auth: state,
@@ -1776,6 +2013,7 @@ export class SandboxBackend {
       return this.buildUserFromStored({
         ...stored,
         customClaims: state.token ?? stored.customClaims,
+        tenantId: state.tenant ?? stored.tenantId,
       });
     }
     return this.makeUser({
@@ -1784,6 +2022,7 @@ export class SandboxBackend {
       displayName: null,
       isAnonymous: state.uid.startsWith('anonymous-'),
       claims: state.token ?? {},
+      tenantId: state.tenant ?? null,
     });
   }
 
@@ -1799,12 +2038,12 @@ export class SandboxBackend {
   private mintToken(
     uid: string,
     claims: Record<string, unknown>,
+    tenantId: string | null,
   ): { token: string; result: IdTokenResult } {
-    const issuedAt = new Date();
+    const issuedAt = this.now();
     // 100 years out — sandbox tokens never expire.
     const expires = new Date(issuedAt.getTime() + 100 * 365 * 24 * 60 * 60 * 1000);
     const serial = this.nextTokenSerial++;
-    const token = sandboxTokenFor(uid, claims, serial);
     // The provider of the current sign-in session for this uid —
     // recorded by setCurrentUser at sign-in time. Null for identities
     // driven via the test driver (no prod analog for that path).
@@ -1823,15 +2062,23 @@ export class SandboxBackend {
       // `firebase.sign_in_provider`.
       firebase: { sign_in_provider: signInProvider },
     };
+    const identity = normalizeAuthState({ uid, tenant: tenantId ?? undefined, token: fullClaims });
+    const tokenClaims = identity?.token ?? fullClaims;
+    const sessionClaims = { ...claims, firebase: tokenClaims.firebase };
+    const token = sandboxTokenFor(uid, sessionClaims, serial);
     const result: IdTokenResult = {
       token,
-      claims: fullClaims,
+      claims: tokenClaims,
       expirationTime: expires.toISOString(),
       issuedAtTime: issuedAt.toISOString(),
       authTime: issuedAt.toISOString(),
       signInProvider,
     };
-    return { token, result };
+    const entry = { token, result };
+    const tokens = this.tokenCache.get(uid) ?? new Map<string | null, typeof entry>();
+    tokens.set(tenantId, entry);
+    this.tokenCache.set(uid, tokens);
+    return entry;
   }
 
   /**
@@ -1850,20 +2097,9 @@ export class SandboxBackend {
     uid: string,
     claims: Record<string, unknown>,
     forceRefresh: boolean,
+    tenantId: string | null = null,
   ): string {
-    if (forceRefresh) {
-      const fresh = this.mintToken(uid, claims);
-      this.tokenCache.set(uid, fresh);
-      // Fan out to onIdTokenChanged listeners only — identity is
-      // unchanged, so onAuthStateChanged stays silent.
-      this.fanOut('id-token');
-      return fresh.token;
-    }
-    const cached = this.tokenCache.get(uid);
-    if (cached) return cached.token;
-    const fresh = this.mintToken(uid, claims);
-    this.tokenCache.set(uid, fresh);
-    return fresh.token;
+    return this.getIdTokenResultFor(uid, claims, forceRefresh, tenantId).token;
   }
 
   /** {@link getIdTokenFor} variant returning the full IdTokenResult.
@@ -1872,17 +2108,28 @@ export class SandboxBackend {
     uid: string,
     claims: Record<string, unknown>,
     forceRefresh: boolean,
+    tenantId: string | null = null,
   ): IdTokenResult {
     if (forceRefresh) {
-      const fresh = this.mintToken(uid, claims);
-      this.tokenCache.set(uid, fresh);
+      const fresh = this.mintToken(uid, claims, tenantId);
+      const current = this.session.currentUser;
+      const refreshesCurrentUser = current !== null && current.uid === uid && (current.tenant ?? null) === tenantId;
+      if (refreshesCurrentUser) {
+        // Rules follow refreshed claims without turning a token refresh into a sign-in.
+        this.applyingTransition = true;
+        try {
+          this.session.currentUser = { ...current, token: rulesTokenClaims(claims, fresh.result) };
+        } finally {
+          this.applyingTransition = false;
+        }
+      }
       this.fanOut('id-token');
       return fresh.result;
     }
-    const cached = this.tokenCache.get(uid);
-    if (cached) return cached.result;
-    const fresh = this.mintToken(uid, claims);
-    this.tokenCache.set(uid, fresh);
+    const cached = this.tokenCache.get(uid)?.get(tenantId);
+    const hasCachedToken = cached !== undefined;
+    if (hasCachedToken) return cached.result;
+    const fresh = this.mintToken(uid, claims, tenantId);
     return fresh.result;
   }
 
@@ -1903,6 +2150,8 @@ export class SandboxBackend {
     phoneNumber?: string | null;
     /** The identity's LINKED providers, from its stored record. */
     providers?: ProviderUserInfo[];
+    /** Tenant this identity authenticated under. Absent means untenanted. */
+    tenantId?: string | null;
   }): User {
     const photoURL = args.photoURL ?? null;
     const phoneNumber = args.phoneNumber ?? null;
@@ -1927,7 +2176,8 @@ export class SandboxBackend {
     // `unlink` of the last provider produces. Falling back on `[]` would
     // resurrect the very provider the user just removed.
     const linked: ProviderUserInfo[] = args.providers ?? [{ providerId: 'password' }];
-    const providerData: UserInfo[] = args.isAnonymous
+    const isAnonymous = args.isAnonymous === true;
+    const providerData: UserInfo[] = isAnonymous
       ? []
       : linked.map((p) => ({
         uid: args.uid,
@@ -1945,6 +2195,7 @@ export class SandboxBackend {
       photoURL,
       phoneNumber,
       isAnonymous: args.isAnonymous,
+      tenantId: args.tenantId ?? null,
       providerId,
       providerData,
       // Read LIVE claims by uid on each token call (not the claims frozen
@@ -1954,9 +2205,9 @@ export class SandboxBackend {
       // Falls back to the closed-over claims for users not in the DB
       // (anonymous / popup), matching how they were minted.
       getIdToken: async (forceRefresh?: boolean) =>
-        this.getIdTokenFor(args.uid, this.liveClaims(args.uid, args.claims), forceRefresh === true),
+        this.getIdTokenFor(args.uid, this.liveClaims(args.uid, args.claims), forceRefresh === true, user.tenantId),
       getIdTokenResult: async (forceRefresh?: boolean) =>
-        this.getIdTokenResultFor(args.uid, this.liveClaims(args.uid, args.claims), forceRefresh === true),
+        this.getIdTokenResultFor(args.uid, this.liveClaims(args.uid, args.claims), forceRefresh === true, user.tenantId),
     };
     // Stamp the backend-dispatch hook non-enumerably so the top-level
     // `updateProfile(user, …)` free function can update THIS user (and the
@@ -2200,6 +2451,12 @@ export class SandboxBackend {
     return this.usersByUid.get(uid)?.customClaims ?? fallback;
   }
 
+  private assertUserEnabled(user: StoredUser): void {
+    if (user.disabled) {
+      throw makeAuthError('auth/user-disabled', 'The user account has been disabled by an administrator.');
+    }
+  }
+
   /** Internal validator for email/password — checks the password
    *  matches the stored record. Throws `auth/invalid-email` on a
    *  malformed email, `auth/wrong-password` on mismatch,
@@ -2238,12 +2495,7 @@ export class SandboxBackend {
     // exact prod ordering (disabled-vs-wrong-password) is flagged for
     // an oracle capture; the code (`auth/user-disabled`) and message
     // match prod's documented shape.
-    if (stored.disabled) {
-      throw makeAuthError(
-        'auth/user-disabled',
-        'The user account has been disabled by an administrator.',
-      );
-    }
+    this.assertUserEnabled(stored);
     if (stored.password !== password) {
       throw makeAuthError(
         'auth/wrong-password',
@@ -2254,6 +2506,60 @@ export class SandboxBackend {
   }
 }
 
+/**
+ * Apply a provider sign-in's photo to an already-stored identity, reporting
+ * whether the record changed.
+ *
+ * A provider sign-in refreshes the provider profile data it actually carries.
+ * An identity that carries no photo leaves the stored one alone rather than
+ * blanking it, mirroring Firebase: a provider refresh updates the fields the
+ * provider supplied and never clears one it omitted.
+ */
+/**
+ * The provider a record is being created under: the provider a sign-in flow
+ * names explicitly, otherwise the first provider already on the record. Null
+ * when neither exists — an anonymous or provider-less record.
+ */
+function creationProviderId(
+  record: StoredUser,
+  signInProviderId: string | null,
+): string | null {
+  if (signInProviderId !== null) return signInProviderId;
+  const firstLinked = record.providerUserInfo[0];
+  if (firstLinked === undefined) return null;
+  return firstLinked.providerId;
+}
+
+/**
+ * Whether a freshly built record gets a default photo.
+ *
+ * Firebase populates `photoURL` only for federated identities: a real Google
+ * or GitHub sign-in always returns one, while `password`, `phone`, email-link,
+ * and anonymous users return null in production. Federated provider ids are
+ * exactly the dotted ones (`google.com`, `github.com`, `oidc.acme`,
+ * `saml.corp`); the first-party ids never contain a dot. Defaulting everyone
+ * would trade this divergence for a new one.
+ *
+ * A photo the caller supplied always wins — the mint only fills a record that
+ * would otherwise be photo-less.
+ */
+function mintsDefaultPhoto(
+  record: StoredUser,
+  providerId: string | null,
+): providerId is string {
+  if (record.photoUrl !== null) return false;
+  if (record.isAnonymous) return false;
+  if (providerId === null) return false;
+  return providerId.includes('.');
+}
+
+function refreshStoredPhoto(stored: StoredUser, photoUrl: string | null): boolean {
+  if (photoUrl === null) return false;
+  if (stored.photoUrl === photoUrl) return false;
+  stored.photoUrl = photoUrl;
+  return true;
+}
+
 /** Provider UIDs are opaque Firebase identifiers, not encoded credentials. */
 function mintProviderUid(): string {
   return `provider-${globalThis.crypto.randomUUID()}`;