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

package/dist/auth/sandbox-backend.js

@@ -38,7 +38,9 @@ import { AuthFlowRegistry, } from './sandbox-auth-flow.js';
 import { sandboxTokenFor } from './sandbox-token.js';
 import { validateEmailFormat, validatePasswordStrength } from './sandbox-credential-validators.js';
 import { createAuthProjectStore, } from './sandbox/project-store.js';
-import { emitSandboxEvent, makeServiceMutationEvent } from 'pyric/sandbox/internal';
+import { defaultAvatarMint } from './sandbox/default-avatar.js';
+import { normalizeAuthState } from 'pyric/sandbox';
+import { emitSandboxEvent, getClock, makeServiceMutationEvent } from 'pyric/sandbox/internal';
 import { USER_INTERNAL, } from './types.js';
 import { NO_PASSWORD_SENTINEL, } from './sandbox-backend-types.js';
 // Re-export the public backend types + the sentinel value from the
@@ -50,6 +52,15 @@ export { NO_PASSWORD_SENTINEL } from './sandbox-backend-types.js';
  * 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, minted) {
+    return { ...claims, firebase: minted.claims.firebase };
+}
 export class SandboxBackend {
     /** Email → stored user. Lowercase keys so lookups are case-
      *  insensitive (matches upstream). */
@@ -107,7 +118,7 @@ export class SandboxBackend {
      *  change). The subscriber only notifies for EXTERNAL mutations
      *  (direct sandbox writes, `reset()`, another handle). */
     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).
@@ -183,6 +194,38 @@ export class SandboxBackend {
      *  section) — {@link assertProviderEnabled} becomes a no-op. Not
      *  persisted: a runtime wiring decision, not project config. */
     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.
+     */
+    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.
+     */
+    tenantId = null;
+    /** Read `Auth.tenantId`. */
+    getTenantId() {
+        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) {
+        this.tenantId = tenantId;
+    }
     constructor(sandbox, session = sandbox, projectStore = createAuthProjectStore(), ownCleanup) {
         this.sandbox = sandbox;
         this.session = session;
@@ -240,6 +283,20 @@ export class SandboxBackend {
     getCurrentUser() {
         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() {
+        const user = this.cachedUser;
+        if (user === null)
+            return null;
+        return this.signInProviderByUid.get(user.uid) ?? null;
+    }
     // ─── Listener registries ────────────────────────────────────────────
     /**
      * Subscribe to user change. Fires *immediately* on subscribe with
@@ -342,9 +399,23 @@ export class SandboxBackend {
         }
     }
     // ─── User DB ────────────────────────────────────────────────────────
-    /** Build a fresh {@link StoredUser} with admin-field defaults. */
-    makeStored(init) {
-        return {
+    /**
+     * 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`.
+     */
+    makeStored(init, signInProviderId = null) {
+        const record = {
             email: null,
             password: null,
             displayName: null,
@@ -355,10 +426,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
      *  `subscribeUsers` listeners. Snapshotted iteration; throwing
@@ -373,6 +455,16 @@ 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.
+     */
+    now() {
+        return getClock(this.sandbox).date();
+    }
     /**
      * Emit an auth {@link ServiceMutationEvent} onto the sandbox's unified
      * `onEvent`/`history()` stream (Pyric Studio keystone). Best-effort and
@@ -386,6 +478,7 @@ export class SandboxBackend {
     emitAuthEvent(op, fields = {}) {
         try {
             emitSandboxEvent(this.sandbox, makeServiceMutationEvent({
+                at: this.now().getTime(),
                 service: 'auth',
                 op,
                 path: fields.path,
@@ -470,6 +563,16 @@ export class SandboxBackend {
     setProviderEnforcementDelegated(delegated) {
         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) {
+        this.avatarMint = mint;
+    }
     /**
      * Gate a provider entry point. Throws real Firebase's
      * `auth/operation-not-allowed` (exactly the code/shape prod throws
@@ -601,49 +704,111 @@ 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)
+        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() {
         const out = [];
         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 = { 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 = {
                 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)
+            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;
@@ -786,8 +951,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.
@@ -795,7 +962,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,
@@ -920,10 +1088,12 @@ 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,
@@ -1033,6 +1203,13 @@ export class SandboxBackend {
      * pre-resolved promise on the fast path instead of ever suspending.
      */
     transitionCurrentUser(user, signInProvider) {
+        // 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);
@@ -1058,8 +1235,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).
+     */
+    scopeSignInToTenant(user) {
+        const tenantId = this.tenantId;
+        user.tenantId = tenantId;
+        const stored = this.usersByUid.get(user.uid);
+        if (stored)
+            stored.tenantId = tenantId;
+    }
     setCurrentUser(user, signInProvider) {
-        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
@@ -1073,7 +1266,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();
@@ -1087,9 +1281,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);
         }
         // Look up custom claims for this uid (if we know them). Falls
@@ -1099,8 +1294,9 @@ export class SandboxBackend {
         const claims = stored?.customClaims ?? {};
         // 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();
         }
         // Stash the (possibly richer) User snapshot so listeners fire with
@@ -1110,11 +1306,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 = { uid: user.uid, token: claims };
+        const signedInState = { uid: user.uid, token: rulesTokenClaims(claims, minted.result) };
+        const hasTenant = typeof user.tenantId === 'string';
+        if (hasTenant)
+            signedInState.tenant = user.tenantId;
+        const nextState = signedInState;
         this.applyingTransition = true;
         try {
             this.session.currentUser = nextState;
@@ -1133,7 +1333,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,
@@ -1170,23 +1370,30 @@ 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, providerId) {
         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 });
             changed = true;
@@ -1215,7 +1422,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.
@@ -1228,21 +1438,27 @@ export class SandboxBackend {
             if (!found) {
                 throw makeAuthError('auth/user-not-found', `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();
@@ -1292,6 +1508,7 @@ export class SandboxBackend {
             isAnonymous: u.isAnonymous,
             disabled: u.disabled,
             emailVerified: u.emailVerified,
+            tenantId: u.tenantId,
             createdAt: u.createdAt,
             lastLoginAt: u.lastLoginAt,
         };
@@ -1325,11 +1542,20 @@ export class SandboxBackend {
             next.unshift({ providerId: 'password' });
         return next;
     }
+    /** Restored or explicitly seeded users may already occupy generated IDs. */
+    nextAvailableAdminUid() {
+        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) {
-        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', `createUser: a user with uid ${uid} already exists.`);
         }
@@ -1471,6 +1697,7 @@ export class SandboxBackend {
             emailVerified: stored.emailVerified,
             phoneNumber: stored.phoneNumber,
             providers: stored.providerUserInfo,
+            tenantId: stored.tenantId,
         });
     }
     /** Mint a fresh anonymous user with an auto-generated uid. Records
@@ -1478,7 +1705,7 @@ export class SandboxBackend {
      *  the emulator) so `listIdentities` / future user-admin surfaces
      *  see anonymous accounts too. */
     mintAnonymousUser() {
-        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();
@@ -1518,46 +1745,62 @@ export class SandboxBackend {
      * authenticated session, same as real Firebase.
      */
     mintDetachedSession(request) {
+        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');
+                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');
+                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);
             }
         }
     }
     /** The shared sign-in bookkeeping behind {@link mintDetachedSession} —
      *  everything {@link setCurrentUser} does for a real sign-in EXCEPT the
      *  global-session parts. */
-    establishDetachedSession(user, signInProvider) {
+    establishDetachedSession(user, signInProvider, tenantId) {
         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.tenantId = tenantId;
+        const minted = this.mintToken(user.uid, claims, tenantId);
+        const state = { 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,
@@ -1581,6 +1824,7 @@ export class SandboxBackend {
             return this.buildUserFromStored({
                 ...stored,
                 customClaims: state.token ?? stored.customClaims,
+                tenantId: state.tenant ?? stored.tenantId,
             });
         }
         return this.makeUser({
@@ -1589,6 +1833,7 @@ export class SandboxBackend {
             displayName: null,
             isAnonymous: state.uid.startsWith('anonymous-'),
             claims: state.token ?? {},
+            tenantId: state.tenant ?? null,
         });
     }
     // ─── Token cache / refresh ──────────────────────────────────────────
@@ -1599,12 +1844,11 @@ export class SandboxBackend {
      * refreshes inside the same millisecond still produce distinct
      * token strings.
      */
-    mintToken(uid, claims) {
-        const issuedAt = new Date();
+    mintToken(uid, claims, tenantId) {
+        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).
@@ -1623,15 +1867,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 = {
             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();
+        tokens.set(tenantId, entry);
+        this.tokenCache.set(uid, tokens);
+        return entry;
     }
     /**
      * Get-or-mint the ID token entry for a uid. `forceRefresh: true`
@@ -1645,36 +1897,34 @@ export class SandboxBackend {
      *   - `auth-onidtokenchanged-force-refresh.json` — onIdTokenChanged
      *     fires after a forced refresh.
      */
-    getIdTokenFor(uid, claims, forceRefresh) {
-        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;
+    getIdTokenFor(uid, claims, forceRefresh, tenantId = null) {
+        return this.getIdTokenResultFor(uid, claims, forceRefresh, tenantId).token;
     }
     /** {@link getIdTokenFor} variant returning the full IdTokenResult.
      *  Same cache + fan-out semantics. */
-    getIdTokenResultFor(uid, claims, forceRefresh) {
+    getIdTokenResultFor(uid, claims, forceRefresh, tenantId = null) {
         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)
+        const cached = this.tokenCache.get(uid)?.get(tenantId);
+        const hasCachedToken = cached !== undefined;
+        if (hasCachedToken)
             return cached.result;
-        const fresh = this.mintToken(uid, claims);
-        this.tokenCache.set(uid, fresh);
+        const fresh = this.mintToken(uid, claims, tenantId);
         return fresh.result;
     }
     /**
@@ -1707,7 +1957,8 @@ export class SandboxBackend {
         // `unlink` of the last provider produces. Falling back on `[]` would
         // resurrect the very provider the user just removed.
         const linked = args.providers ?? [{ providerId: 'password' }];
-        const providerData = args.isAnonymous
+        const isAnonymous = args.isAnonymous === true;
+        const providerData = isAnonymous
             ? []
             : linked.map((p) => ({
                 uid: args.uid,
@@ -1725,6 +1976,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
@@ -1733,8 +1985,8 @@ export class SandboxBackend {
             // `getIdToken(true)` (AUTH-B10) — same propagation story as prod.
             // Falls back to the closed-over claims for users not in the DB
             // (anonymous / popup), matching how they were minted.
-            getIdToken: async (forceRefresh) => this.getIdTokenFor(args.uid, this.liveClaims(args.uid, args.claims), forceRefresh === true),
-            getIdTokenResult: async (forceRefresh) => this.getIdTokenResultFor(args.uid, this.liveClaims(args.uid, args.claims), forceRefresh === true),
+            getIdToken: async (forceRefresh) => this.getIdTokenFor(args.uid, this.liveClaims(args.uid, args.claims), forceRefresh === true, user.tenantId),
+            getIdTokenResult: async (forceRefresh) => 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
@@ -1960,6 +2212,11 @@ export class SandboxBackend {
     liveClaims(uid, fallback) {
         return this.usersByUid.get(uid)?.customClaims ?? fallback;
     }
+    assertUserEnabled(user) {
+        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,
@@ -1992,15 +2249,65 @@ 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', 'Invalid password.');
         }
         return stored;
     }
 }
+/**
+ * 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, signInProviderId) {
+    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, providerId) {
+    if (record.photoUrl !== null)
+        return false;
+    if (record.isAnonymous)
+        return false;
+    if (providerId === null)
+        return false;
+    return providerId.includes('.');
+}
+function refreshStoredPhoto(stored, photoUrl) {
+    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() {
     return `provider-${globalThis.crypto.randomUUID()}`;