pyric 0.0.1 → 0.1.0-alpha.7

package/dist/auth/index.js

@@ -0,0 +1,701 @@
+/**
+ * `pyric/auth` — modular Web-SDK Auth adapter for the Pyric
+ * sandbox.
+ *
+ * Mirrors `firebase/auth`'s tree-shakable free-function surface
+ * (`getAuth`, `signInAnonymously`, `signInWithEmailAndPassword`,
+ * `onAuthStateChanged`, `signInWithPopup`, `GoogleAuthProvider`, …)
+ * with two backends picked at init:
+ *
+ *   - **Sandbox target** — in-memory user DB + listener registry,
+ *     drives `sandbox.currentUser` so service factories (a future
+ *     `getFirestore(sandbox)` overload, follow-up PR) see identity
+ *     changes without re-binding.
+ *   - **Prod target** — delegates straight to `firebase/auth`.
+ *
+ * Same call surface across both. Agent code that writes against the
+ * sandbox during iteration runs unmodified against prod at deploy.
+ *
+ * Dual-target dispatch follows the same pattern as `pyric/firestore`:
+ *   - {@link TARGET_SYMBOL} brands every {@link Auth} handle.
+ *   - {@link targetOf} (internal) reads it and switches on
+ *     `target.kind`.
+ *
+ * Sandbox-only test driver lives under {@link sandbox}, mirroring
+ * `pyric/firestore`'s `sandbox.setRules` etc. — each method throws
+ * `failed-precondition` if called against a prod-backed handle.
+ *
+ * v0 scope is deliberately minimal. The deny-list is documented in
+ * `docs/reference/feature-matrix.md`; agent `appSource` that imports
+ * any of those will fail to bundle once the playground's
+ * `firebase/auth` → `pyric/auth` alias swap lands.
+ */
+import { SandboxError } from 'pyric/sandbox';
+import * as fb from 'firebase/auth';
+// Phase 3 unified app handle. Adapter dispatch reads `APP_TARGET` and
+// routes to the existing direct-handle path (sandbox vs prod).
+import { APP_TARGET } from 'pyric/app';
+import { SandboxBackend, makeAuthError, } from './sandbox-backend.js';
+import { targetOf } from './target.js';
+import { TARGET_SYMBOL, USER_INTERNAL, } from './types.js';
+import { prodCreateUserWithEmailAndPassword, prodCurrentUser, prodGetRedirectResult, prodOnAuthStateChanged, prodOnIdTokenChanged, prodSetPersistence, prodSignInAnonymously, prodSignInWithCredential, prodSignInWithEmailAndPassword, prodSignInWithPopup, prodSignInWithRedirect, prodSignOut, } from './prod-backend.js';
+export { TARGET_SYMBOL } from './types.js';
+// ─── Re-exports: provider classes ─────────────────────────────────────
+export { EmailAuthProvider, FacebookAuthProvider, GithubAuthProvider, GoogleAuthProvider, OAuthProvider, FEDERATED_PROVIDER_IDS, } from './providers.js';
+// ─── Persistence markers ──────────────────────────────────────────────
+//
+// Opaque markers — sandbox treats them as no-ops, prod backend maps
+// them to upstream's `inMemoryPersistence` / `browserSessionPersistence`
+// / `browserLocalPersistence` singletons via `setPersistence`.
+export const inMemoryPersistence = { type: 'NONE' };
+export const browserSessionPersistence = { type: 'SESSION' };
+export const browserLocalPersistence = { type: 'LOCAL' };
+// ─── Memoization: one backend per sandbox ─────────────────────────────
+//
+// `firebase/auth.getAuth(app)` is idempotent — repeat calls for the
+// same app return the same Auth instance. Mirror that on the sandbox
+// side so listeners registered against one handle see changes
+// driven through another handle for the same sandbox.
+const sandboxBackends = new WeakMap();
+const sandboxHandles = new WeakMap();
+// Prod handles are memoized per underlying `fb.Auth`. `fb.getAuth(app)`
+// is itself idempotent (same `fb.Auth` per app), but our *wrapper*
+// handle was minted fresh on every `getAuth(app)` call — so
+// `getAuth(app) !== getAuth(app)`, contradicting the docstring + COMPAT.
+// Keying on the resolved `fb.Auth` makes the wrapper idempotent too,
+// matching the sandbox side (AUTH-B6).
+const prodHandles = new WeakMap();
+function backendFor(sandbox) {
+    let backend = sandboxBackends.get(sandbox);
+    if (!backend) {
+        backend = new SandboxBackend(sandbox);
+        sandboxBackends.set(sandbox, backend);
+        // Register the auth user DB as a persistable service on the sandbox.
+        // This is the primary hook that makes `enablePersistence` include auth
+        // users in the serialized blob and restore them on reload.
+        //
+        // Registration is guarded by the backendFor memoization — we only
+        // reach this branch ONCE per sandbox, so double-registration is
+        // impossible in practice. `registerPersistableService` throws on
+        // duplicates anyway, which would surface as a bug if the invariant
+        // were ever broken.
+        //
+        // Capture `backend` in the closure via a local so the let-binding
+        // can be reassigned without breaking the hooks (TypeScript narrows it
+        // as non-null here, but the closures below need a stable reference).
+        const capturedBackend = backend;
+        sandbox.registerPersistableService('auth', {
+            snapshot: () => ({
+                users: capturedBackend.exportUsers(),
+                providers: capturedBackend.exportProviderConfig(),
+            }),
+            restore: (data) => {
+                const d = data;
+                // Restore is a REPLACE, not a merge: the user DB becomes EXACTLY what
+                // the snapshot holds. On boot / late-registration the backend is empty,
+                // so clearUsers() is a no-op; for a runtime `sandbox.loadSnapshot()`
+                // (transfer / branch switch) it drops users that diverged after the
+                // snapshot was taken, so the clobber is total.
+                capturedBackend.clearUsers();
+                if (Array.isArray(d?.users) && d.users.length > 0) {
+                    capturedBackend.seedUsers(d.users);
+                }
+                // Same REPLACE policy for provider config. `restoreProviderConfig`
+                // falls back to the documented defaults when `d?.providers` is
+                // missing (a blob written before this feature existed), so older
+                // `--persist` files don't silently disable password/anonymous.
+                capturedBackend.restoreProviderConfig(d?.providers);
+            },
+            subscribe: (onChange) => {
+                const unsubUsers = capturedBackend.subscribeUsers(onChange);
+                const unsubProviders = capturedBackend.subscribeProviderConfig(onChange);
+                return () => {
+                    unsubUsers();
+                    unsubProviders();
+                };
+            },
+            // Session hooks — the persistence controller uses these to save and
+            // restore the CURRENTLY SIGNED-IN USER (the session), separate from
+            // the user database (handled above by snapshot/restore). The controller
+            // only activates session persistence when `sessionStorage` is injected
+            // into `enablePersistence` options; when omitted the hooks exist but
+            // are never called (no fake durability in non-browser environments).
+            session: {
+                currentUid: () => sandbox.currentUser?.uid ?? null,
+                restore: (uid) => capturedBackend.restoreSession(uid),
+                mode: () => capturedBackend.getPersistenceMode(),
+                subscribe: (onChange) => capturedBackend.subscribeSession(onChange),
+            },
+        });
+    }
+    return backend;
+}
+export function getAuth(target) {
+    // PyricApp dispatch: inspect the brand and forward to the existing
+    // direct-handle path. Ordered ABOVE the structural `isSandbox`
+    // sniff so a PyricApp's outer object (which doesn't itself carry
+    // `withAuth`) doesn't accidentally match either branch — and so a
+    // sandbox-app routes into the cached sandbox handle.
+    if (isPyricApp(target)) {
+        return target[APP_TARGET] === 'sandbox'
+            ? getAuth(target.sandbox)
+            : getAuth(target.firebaseApp);
+    }
+    if (isSandbox(target)) {
+        let handle = sandboxHandles.get(target);
+        if (handle)
+            return handle;
+        const backend = backendFor(target);
+        const t = { kind: 'sandbox', sandbox: target, backend };
+        handle = makeAuthHandle(t);
+        sandboxHandles.set(target, handle);
+        return handle;
+    }
+    const fbAuth = fb.getAuth(target);
+    let handle = prodHandles.get(fbAuth);
+    if (handle)
+        return handle;
+    const t = { kind: 'prod', auth: fbAuth };
+    handle = makeAuthHandle(t);
+    prodHandles.set(fbAuth, handle);
+    return handle;
+}
+/**
+ * Brand-based test for the {@link PyricApp} overload. Reads the
+ * `APP_TARGET` symbol that `pyric/app`'s `initializeApp` stamps on
+ * every handle. Cheap + collision-free: a `Sandbox` / `FirebaseApp`
+ * will never carry this symbol.
+ */
+function isPyricApp(target) {
+    return (target !== null
+        && typeof target === 'object'
+        && APP_TARGET in target);
+}
+/**
+ * Brand-based discriminator for `getAuth`. A {@link Sandbox} carries
+ * the `onCurrentUserChanged` method (and `currentUser` accessor)
+ * which a `FirebaseApp` will never have; structural sniff is cheap
+ * and stable.
+ */
+function isSandbox(target) {
+    return (typeof target === 'object'
+        && target !== null
+        && typeof target.onCurrentUserChanged === 'function'
+        && typeof target.withAuth === 'function');
+}
+/**
+ * Build an Auth handle. `currentUser` is a getter so each access
+ * reads through to the live backend state — consumer code that holds
+ * an `auth` reference always sees the latest user (matches
+ * `firebase/auth`).
+ */
+function makeAuthHandle(target) {
+    const handle = {
+        [TARGET_SYMBOL]: target,
+        // Method form of `signOut(auth)` — `firebase/auth`'s `Auth` exposes
+        // both the free function and this method (AUTH-GAP). Delegates to the
+        // free function so the two share one code path.
+        signOut() {
+            return signOut(handle);
+        },
+    };
+    return Object.defineProperty(handle, 'currentUser', {
+        enumerable: true,
+        get() {
+            return target.kind === 'sandbox'
+                ? target.backend.getCurrentUser()
+                : prodCurrentUser(target.auth);
+        },
+    });
+}
+// ─── Emulator wiring ──────────────────────────────────────────────────
+/**
+ * `connectAuthEmulator(auth, url, options?)` — on sandbox handles
+ * this is a no-op (the sandbox IS the emulator); on prod it
+ * delegates straight to `firebase/auth.connectAuthEmulator`.
+ *
+ * Same signature as upstream so consumer code that calls this at
+ * init time works against both backends unchanged.
+ */
+export function connectAuthEmulator(auth, url, options) {
+    const target = targetOf(auth);
+    if (target.kind === 'sandbox')
+        return;
+    // Upstream types require `disableWarnings: boolean` (not optional);
+    // normalize to false when callers omit it.
+    fb.connectAuthEmulator(target.auth, url, {
+        disableWarnings: options?.disableWarnings ?? false,
+    });
+}
+// ─── Sign-in / out free functions ─────────────────────────────────────
+export async function signInAnonymously(auth) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod')
+        return prodSignInAnonymously(target.auth);
+    target.backend.assertProviderEnabled('anonymous');
+    // Match `firebase/auth` semantics: if there's already an anonymous
+    // user signed in, reuse them rather than minting a fresh uid.
+    // Production persists anonymous users across page loads via the
+    // configured Persistence; the sandbox has no equivalent, but within
+    // a single sandbox lifetime an already-signed-in anonymous user is
+    // the same identity from the consumer's perspective. Without this
+    // check, React StrictMode (or any double-mount pattern) leaks a
+    // new anonymous user per mount — `anonymous-1`, `anonymous-2`, …
+    // each with their own owner-only profile docs nobody can clean up.
+    const existing = target.backend.getCurrentUser();
+    if (existing && existing.isAnonymous) {
+        return { user: existing, providerId: null, operationType: 'signIn' };
+    }
+    const user = target.backend.mintAnonymousUser();
+    target.backend.setCurrentUser(user, 'anonymous');
+    return { user, providerId: null, operationType: 'signIn' };
+}
+export async function signInWithEmailAndPassword(auth, email, password) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod') {
+        return prodSignInWithEmailAndPassword(target.auth, email, password);
+    }
+    target.backend.assertProviderEnabled('password');
+    const stored = target.backend.validatePassword(email, password);
+    const user = target.backend.buildUserFromStored(stored);
+    // The backend records the originating provider ('password') on the
+    // identity for provider tracking, while the credential's providerId
+    // stays null for email/password — matches prod. Upstream
+    // `providerIdForResponse` returns null when the token response carries
+    // no providerId (email/password responses don't; only OAuth/phone do —
+    // `core/user/user_credential_impl.ts:84-96`). Oracle:
+    // scripts/oracle/observations/auth-createUser-operationType.json pins
+    // providerId: null against prod (AUTH-B2).
+    target.backend.setCurrentUser(user, 'password');
+    return { user, providerId: null, operationType: 'signIn' };
+}
+export async function createUserWithEmailAndPassword(auth, email, password) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod') {
+        return prodCreateUserWithEmailAndPassword(target.auth, email, password);
+    }
+    target.backend.assertProviderEnabled('password');
+    const stored = target.backend.createEmailPasswordUser(email, password);
+    const user = target.backend.buildUserFromStored(stored);
+    // providerId: null — same rationale as signInWithEmailAndPassword above
+    // (the exact field the oracle capture contradicted; audit H6 / AUTH-B2);
+    // 'password' still recorded on the identity for provider tracking.
+    target.backend.setCurrentUser(user, 'password');
+    return { user, providerId: null, operationType: 'signIn' };
+}
+export async function signOut(auth) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod')
+        return prodSignOut(target.auth);
+    target.backend.setCurrentUser(null);
+}
+export async function setPersistence(auth, persistence) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod')
+        return prodSetPersistence(target.auth, persistence);
+    // Sandbox: record the mode on the backend so the persistence controller
+    // can pick the right web-storage slot (local / session / none) for the
+    // current session. The backend's setPersistenceMode notifies session-
+    // change subscribers, causing the controller to immediately migrate any
+    // stored uid to the new store — matching the real SDK's setMode behavior
+    // where the active session follows the new persistence target.
+    //
+    // Mode mapping: our persistence markers carry `.type` strings that match
+    // the `'LOCAL' | 'SESSION' | 'NONE'` enum exactly.
+    //   inMemoryPersistence       → { type: 'NONE' }
+    //   browserSessionPersistence → { type: 'SESSION' }
+    //   browserLocalPersistence   → { type: 'LOCAL' }
+    const modeMap = {
+        LOCAL: 'LOCAL',
+        SESSION: 'SESSION',
+        NONE: 'NONE',
+    };
+    const mode = modeMap[persistence.type] ?? 'LOCAL';
+    target.backend.setPersistenceMode(mode);
+}
+/**
+ * Resolve a popup/redirect sign-in to a `UserCredential`, mirroring
+ * `firebase/auth`'s `_withDefaultResolver` precedence:
+ *   per-call resolver → injected resolver → one-shot mock → throw.
+ * With nothing configured it throws `auth/argument-error` (exactly what
+ * upstream throws with no resolver), naming the API that was actually
+ * called. The one-shot mock keeps headless conformance deterministic.
+ */
+async function resolveFlow(backend, provider, authType, perCall, kind) {
+    // Gate BEFORE touching the resolver/mock registry, so a disabled provider
+    // throws `auth/operation-not-allowed` — distinct from the `auth/argument-
+    // error` below, which keeps meaning "enabled, but no resolver/mock wired".
+    backend.assertProviderEnabled(provider.providerId);
+    const req = { providerId: provider.providerId, authType };
+    const resolver = perCall ?? backend.getResolver();
+    if (resolver)
+        return kind === 'popup' ? resolver.openPopup(req) : resolver.openRedirect(req);
+    const mock = backend.consumeMockResult(provider.providerId);
+    if (mock)
+        return mock;
+    const api = kind === 'popup' ? 'signInWithPopup' : 'signInWithRedirect';
+    throw makeAuthError('auth/argument-error', `${api}(provider: ${provider.providerId}): no AuthFlowResolver configured. Inject one with sandbox.setAuthFlowResolver(auth, resolver), pass one as the 3rd argument, or pre-stage a result with sandbox.mockSignInResult(auth, {user, providerId: '${provider.providerId}', …}).`);
+}
+/**
+ * The `resolver` argument is sandbox-only: on a prod-backed handle the
+ * call delegates to `firebase/auth`, which uses its own platform default
+ * (browser) resolver, and this argument is ignored.
+ */
+export async function signInWithPopup(auth, provider, resolver) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod')
+        return prodSignInWithPopup(target.auth, provider);
+    const cred = await resolveFlow(target.backend, provider, 'signIn', resolver, 'popup');
+    const providerId = cred.providerId ?? provider.providerId;
+    target.backend.assertSignInAllowed(cred.user.uid);
+    target.backend.recordProviderSignIn(cred.user, providerId);
+    target.backend.setCurrentUser(cred.user, providerId);
+    return cred;
+}
+/**
+ * The `resolver` argument is sandbox-only — see {@link signInWithPopup}.
+ */
+export async function signInWithRedirect(auth, provider, resolver) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod')
+        return prodSignInWithRedirect(target.auth, provider);
+    // Sandbox has no navigation, so the resolver resolves inline; stash the
+    // credential + sign in so getRedirectResult returns it once (matches the
+    // observable prod outcome: after the redirect completes the user is
+    // signed in and getRedirectResult yields the credential).
+    const cred = await resolveFlow(target.backend, provider, 'signIn', resolver, 'redirect');
+    const providerId = cred.providerId ?? provider.providerId;
+    target.backend.assertSignInAllowed(cred.user.uid);
+    target.backend.setRedirectResult(cred);
+    target.backend.recordProviderSignIn(cred.user, providerId);
+    target.backend.setCurrentUser(cred.user, providerId);
+}
+export async function getRedirectResult(auth, _resolver) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod')
+        return prodGetRedirectResult(target.auth);
+    return target.backend.takeRedirectResult();
+}
+export async function signInWithCredential(auth, credential) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod')
+        return prodSignInWithCredential(target.auth, credential);
+    const providerId = credential.providerId;
+    // Gate BEFORE consuming the mock — see the `resolveFlow` gating note above
+    // for why `operation-not-allowed` must fire ahead of the mock-registry check.
+    target.backend.assertProviderEnabled(providerId);
+    const mock = target.backend.consumeMockResult(providerId);
+    if (!mock) {
+        throw makeAuthError('auth/no-mock-configured', `signInWithCredential(providerId: ${providerId}): no mock configured. Pre-stage with sandbox.mockSignInResult(auth, {user, providerId: '${providerId}', …}).`);
+    }
+    const credProviderId = mock.providerId ?? providerId;
+    target.backend.assertSignInAllowed(mock.user.uid);
+    target.backend.recordProviderSignIn(mock.user, credProviderId);
+    target.backend.setCurrentUser(mock.user, credProviderId);
+    return mock;
+}
+// ─── Observers ────────────────────────────────────────────────────────
+export function onAuthStateChanged(auth, observer) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod')
+        return prodOnAuthStateChanged(target.auth, observer);
+    return target.backend.subscribe('auth-state', observer);
+}
+export function onIdTokenChanged(auth, observer) {
+    const target = targetOf(auth);
+    if (target.kind === 'prod')
+        return prodOnIdTokenChanged(target.auth, observer);
+    // Sandbox: fires on identity transitions AND on
+    // `getIdToken(true)` forced refreshes — matches prod.
+    // Oracle: scripts/oracle/observations/auth-onidtokenchanged-force-refresh.json.
+    return target.backend.subscribe('id-token', observer);
+}
+// ─── Token accessors ──────────────────────────────────────────────────
+/**
+ * Top-level mirror of `firebase/auth`'s `getIdToken(user)`. Delegates
+ * to the method on the user handle, so it works on both backends.
+ *
+ * Parity provenance: W1.5 grid (2026-06-10) — generated apps import
+ * the modular free function, and its absence failed every render of
+ * the claims-driven fixtures.
+ */
+export async function getIdToken(user, forceRefresh) {
+    return user.getIdToken(forceRefresh);
+}
+/** Top-level mirror of `firebase/auth`'s `getIdTokenResult(user)`. */
+export async function getIdTokenResult(user, forceRefresh) {
+    return user.getIdTokenResult(forceRefresh);
+}
+/**
+ * Top-level mirror of `firebase/auth`'s `updateProfile(user, profile)`.
+ * Updates the signed-in user's `displayName` / `photoURL` — pass `null` to
+ * clear a field, omit it to leave it untouched. Mutates the user object in
+ * place (held references, including `auth.currentUser`, reflect the change).
+ *
+ * Dispatches through the hidden {@link USER_INTERNAL} hook the backend stamps
+ * on every `User`, so it routes correctly WITHOUT an `auth` handle — matching
+ * upstream's user-only signature. Works on both sandbox and prod targets.
+ *
+ * Per `firebase/auth`, this does NOT fire `onAuthStateChanged` /
+ * `onIdTokenChanged`.
+ */
+export async function updateProfile(user, profile) {
+    const internal = user[USER_INTERNAL];
+    if (!internal) {
+        throw makeAuthError('auth/invalid-user-token', 'updateProfile: unrecognized user — was it produced by a pyric/auth sign-in?');
+    }
+    return internal.updateProfile(profile);
+}
+// ─── Sandbox-only test driver ─────────────────────────────────────────
+/**
+ * Sandbox-only lifecycle / test-driver surface. Throws
+ * `failed-precondition` on prod-backed handles — mirrors the
+ * `pyric/firestore` `sandbox.*` pattern.
+ *
+ * **Naming note:** the `sandbox` export name collides with the
+ * common `const sandbox = initializeSandbox()` local. Alias on
+ * import if both are in scope:
+ *
+ * ```ts
+ * import { sandbox as authSandbox } from 'pyric/auth';
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * const sandbox = initializeSandbox();
+ * const auth = getAuth(sandbox);
+ * authSandbox.seedUsers(auth, […]);
+ * ```
+ */
+export const sandbox = {
+    /**
+     * Force the current user (and emit to listeners). Pass `null` to
+     * sign out. Bypasses the email/password lookup — useful for
+     * driving auth state directly in tests without seeding.
+     */
+    setUser(auth, user) {
+        requireSandbox(auth, 'sandbox.setUser').backend.setCurrentUser(user);
+    },
+    /**
+     * Install the popup/redirect resolver — the analog of browser
+     * `getAuth` wiring `browserPopupRedirectResolver`. The host
+     * (playground) sets this once; `signInWithPopup` / `signInWithRedirect`
+     * then delegate the experience to it. Pass `null` to clear.
+     *
+     * Precedence at sign-in time: a per-call resolver arg wins, then this
+     * injected one, then a one-shot `mockSignInResult`, else
+     * `auth/argument-error`.
+     */
+    setAuthFlowResolver(auth, resolver) {
+        requireSandbox(auth, 'sandbox.setAuthFlowResolver').backend.setResolver(resolver);
+    },
+    /**
+     * Snapshot every known identity (seeded + created), for a host
+     * account-picker UI. Sandbox-only — no `firebase/auth` equivalent.
+     */
+    listIdentities(auth) {
+        return requireSandbox(auth, 'sandbox.listIdentities').backend.listIdentities();
+    },
+    /**
+     * Mint a sign-in credential for a host-driven flow — the account
+     * picker's "pick existing" (`{providerId, uid}`) and "add account"
+     * (`{providerId, spec}`) actions. Token + claims synthesis is
+     * backend-owned (routed through the same token cache as every
+     * other sign-in), replacing host-synthesized token strings.
+     *
+     * The credential does NOT sign anyone in — resolve the pending
+     * `AuthFlowResolver` promise with it and the in-flight
+     * `signInWithPopup` / `signInWithRedirect` completes the sign-in.
+     */
+    createSignInCredential(auth, request) {
+        return requireSandbox(auth, 'sandbox.createSignInCredential')
+            .backend.createSignInCredential(request);
+    },
+    /**
+     * Pre-stage the result that the next `signInWithPopup` /
+     * `signInWithCredential` call for the matching `providerId`
+     * returns. The one-shot tier of the resolver precedence (used when no
+     * resolver is injected) — consumed by the next sign-in call; stage
+     * again for repeat tests.
+     */
+    mockSignInResult(auth, result) {
+        const backend = requireSandbox(auth, 'sandbox.mockSignInResult').backend;
+        const providerId = result.providerId;
+        if (!providerId) {
+            throw new SandboxError('invalid-argument', 'sandbox.mockSignInResult: result.providerId is required so the next signInWithPopup / signInWithCredential call can match.');
+        }
+        backend.setMockResult(providerId, result);
+    },
+    /**
+     * Bulk-load test users for email/password lookup. Idempotent for
+     * a given uid+email — re-seeding the same uid overwrites.
+     */
+    seedUsers(auth, users) {
+        requireSandbox(auth, 'sandbox.seedUsers').backend.seedUsers(users);
+    },
+    /**
+     * Export the user DB in the exact shape {@link sandbox.seedUsers}
+     * accepts — `exportUsers` → `seedUsers` round-trips losslessly (the
+     * persistence substrate, the design rationale section 3c).
+     * Provider-flow identities without a password export with a documented
+     * sentinel; anonymous users are not exported (ephemeral by design).
+     */
+    exportUsers(auth) {
+        return requireSandbox(auth, 'sandbox.exportUsers').backend.exportUsers();
+    },
+    /**
+     * Re-establish a signed-in session for an EXISTING identity — the
+     * substrate behind web-storage session persistence at the host layer.
+     * Fires auth-state listeners like a real restored session. Throws
+     * `auth/user-not-found` for unknown uids, `auth/user-disabled` for
+     * disabled accounts (a restore is a sign-in).
+     */
+    restoreSession(auth, uid) {
+        return requireSandbox(auth, 'sandbox.restoreSession').backend.restoreSession(uid);
+    },
+    /**
+     * Mint a session identity WITHOUT signing it in globally — the
+     * substrate for **per-connection identity** at the serve layer
+     * (issue #754): one shared sandbox, N connections (tabs / clients),
+     * each with its own authenticated session. Performs a real sign-in's
+     * bookkeeping (provider record, `lastLoginAt`, a fresh token, the
+     * `sign_in` activity event) but leaves `auth.currentUser`, the
+     * auth-state listeners, and session persistence untouched.
+     *
+     * Returns the `User` plus the `AuthState` its data contexts should
+     * carry — `getFirestore(sandbox.withAuth(session.state))` evaluates
+     * rules exactly as a real sign-in would (`request.auth.uid` +
+     * custom claims on `request.auth.token`).
+     *
+     * This is an AUTHENTIC session (credentials are validated / an
+     * identity is really minted) — distinct from the rules-debugging
+     * impersonation lens, which asserts a uid without authenticating.
+     */
+    mintSession(auth, request) {
+        return requireSandbox(auth, 'sandbox.mintSession').backend.mintDetachedSession(request);
+    },
+    // ── User-admin surface (emulator-REST-shaped) ──────────────────────
+    /**
+     * Every user in the sandbox user DB (seeded, created,
+     * signed-in-via-provider, anonymous) as {@link AuthUserRecord}s.
+     * Snapshot — subscribe to changes via {@link sandbox.subscribeUsers}.
+     */
+    listUsers(auth) {
+        return requireSandbox(auth, 'sandbox.listUsers').backend.listUsers();
+    },
+    /**
+     * Create a user without signing them in (admin semantics — the
+     * client-mirror `createUserWithEmailAndPassword` is the
+     * signs-you-in variant). Throws `auth/uid-already-exists`,
+     * `auth/email-already-in-use`, `auth/invalid-email`,
+     * `auth/weak-password` on bad input.
+     */
+    createUser(auth, request) {
+        return requireSandbox(auth, 'sandbox.createUser').backend.createUser(request);
+    },
+    /**
+     * Update a user. `undefined` fields untouched; `customClaims`
+     * replaces the whole map; setting `disabled: true` blocks future
+     * sign-ins with `auth/user-disabled` (active sessions continue —
+     * same as prod until token revocation).
+     */
+    updateUser(auth, uid, update) {
+        return requireSandbox(auth, 'sandbox.updateUser').backend.updateUser(uid, update);
+    },
+    /**
+     * Update a user's PROFILE (`displayName` / `photoURL`) by uid — the
+     * backend behind the served worker path's `updateProfile`. `undefined`
+     * fields untouched; `null` clears. Returns the refreshed record; throws
+     * `auth/user-not-found` for an unknown uid. (The client-facing
+     * `updateProfile(user, …)` free function is the app-code surface; this is
+     * the by-uid op the SharedWorker host calls.)
+     */
+    updateProfile(auth, uid, profile) {
+        return requireSandbox(auth, 'sandbox.updateProfile').backend.updateProfileByUid(uid, profile);
+    },
+    /** Delete a user record. Throws `auth/user-not-found` for unknown
+     *  uids. Active sessions are not terminated (prod parity). */
+    deleteUser(auth, uid) {
+        requireSandbox(auth, 'sandbox.deleteUser').backend.deleteUser(uid);
+    },
+    /** Drop every user record — the emulator's "delete all accounts". */
+    clearUsers(auth) {
+        requireSandbox(auth, 'sandbox.clearUsers').backend.clearUsers();
+    },
+    /**
+     * Subscribe to user-DB mutations (seed / create / update / delete /
+     * clear / provider links / lastLoginAt bumps). Coarse contract: no
+     * payload, no initial fire — re-list via {@link sandbox.listUsers}
+     * in the callback.
+     */
+    subscribeUsers(auth, callback) {
+        return requireSandbox(auth, 'sandbox.subscribeUsers').backend.subscribeUsers(callback);
+    },
+    // ── Sign-in provider config (Authentication → Sign-in method toggles) ──
+    /**
+     * Every provider this sandbox has an explicit enablement for —
+     * seeded defaults (`password`, `anonymous` — both `true`) plus
+     * anything toggled via {@link sandbox.setAuthProviderConfig}. Every
+     * OTHER providerId (`google.com`, a custom OAuth id, …) is disabled
+     * until explicitly enabled.
+     */
+    getAuthProviderConfig(auth) {
+        return requireSandbox(auth, 'sandbox.getAuthProviderConfig').backend.listProviderConfig();
+    },
+    /**
+     * Enable/disable a sign-in provider. Gated at every provider entry
+     * point of the ENFORCING backend (`signInWithPopup`/`signInWithRedirect`,
+     * `signInWithCredential`, `createUserWithEmailAndPassword`/
+     * `signInWithEmailAndPassword` for `'password'`, `signInAnonymously`
+     * for `'anonymous'`) — disabling a provider makes the matching sign-in
+     * call throw real Firebase's `auth/operation-not-allowed`, exactly
+     * like flipping the toggle off in the real console. Survives
+     * `enablePersistence` round-trips (rides the `auth` service's
+     * snapshot alongside the user DB). A backend whose enforcement is
+     * delegated ({@link sandbox.delegateProviderEnforcement}) does NOT
+     * gate locally — the remote authority it fronts does.
+     */
+    setAuthProviderConfig(auth, providerId, enabled) {
+        requireSandbox(auth, 'sandbox.setAuthProviderConfig').backend.setProviderConfig(providerId, enabled);
+    },
+    /**
+     * Assert a provider is enabled — throws `auth/operation-not-allowed`
+     * (the exact gate every provider entry point uses) when it is off.
+     * For hosts that ARE the enforcement authority for identities
+     * resolved elsewhere: the served SharedWorker calls this before
+     * accepting a page-resolved popup/redirect identity
+     * (`auth.acceptIdentity`), so Studio's provider toggles gate served
+     * OAuth sign-in at the shared backend, not at each page's UI shim.
+     */
+    assertAuthProviderEnabled(auth, providerId) {
+        requireSandbox(auth, 'sandbox.assertAuthProviderEnabled').backend.assertProviderEnabled(providerId);
+    },
+    /**
+     * Delegate (or reclaim) THIS handle's provider-enablement gate to a
+     * remote authority. Serve-layer wiring: in SharedWorker mode the
+     * page-local sandbox is only the UI vehicle for popup/redirect
+     * resolution — the worker's `auth.acceptIdentity` gate (against the
+     * worker's own, undelegated config) is the real toggle enforcement —
+     * so the served `firebase/auth` entry sets `true` on the in-page
+     * handle to let the picker open regardless of local defaults. Do NOT
+     * set this on a backend that is itself the authority.
+     */
+    delegateProviderEnforcement(auth, delegated) {
+        requireSandbox(auth, 'sandbox.delegateProviderEnforcement')
+            .backend.setProviderEnforcementDelegated(delegated);
+    },
+    /**
+     * Subscribe to provider-config mutations. Coarse contract: no
+     * payload, no initial fire — re-read via
+     * {@link sandbox.getAuthProviderConfig} in the callback (same shape
+     * as {@link sandbox.subscribeUsers}).
+     */
+    subscribeAuthProviderConfig(auth, callback) {
+        return requireSandbox(auth, 'sandbox.subscribeAuthProviderConfig').backend.subscribeProviderConfig(callback);
+    },
+};
+function requireSandbox(auth, name) {
+    const target = targetOf(auth);
+    if (target.kind !== 'sandbox') {
+        throw new SandboxError('failed-precondition', `${name} is sandbox-only; this Auth handle is prod-backed.`);
+    }
+    return target;
+}
+//# sourceMappingURL=index.js.map