pyric 0.0.1 → 0.1.0-alpha.7

package/dist/auth/sandbox-backend.d.ts

@@ -0,0 +1,769 @@
+/**
+ * Sandbox backend for `pyric/auth`.
+ *
+ * Owns four pieces of per-sandbox state:
+ *   1. In-memory user database — emails / passwords / customClaims
+ *      seeded via `sandbox.seedUsers(auth, …)` plus accounts created
+ *      through `createUserWithEmailAndPassword`.
+ *   2. Listener registries — one for `onAuthStateChanged`, one for
+ *      `onIdTokenChanged`. Both fire on user change; the
+ *      `onIdTokenChanged` registry ALSO fires on a forced ID-token
+ *      refresh (matches prod — see oracle observation
+ *      `auth-onidtokenchanged-force-refresh.json`).
+ *   3. Mock-result registry — pre-staged `UserCredential`s consumed by
+ *      `signInWithPopup` / `signInWithCredential`. Keyed by
+ *      `providerId`; one slot per provider.
+ *   4. Token cache — current ID token string + IdTokenResult per uid.
+ *      A fresh token is minted on each setCurrentUser transition into
+ *      a non-null user (new session = new token) and on each
+ *      `getIdToken(forceRefresh=true)`. Subsequent
+ *      `getIdToken(false)` reads return the cached token (matches
+ *      prod — see `auth-getidtoken-force-refresh.json`).
+ *
+ * The "current user" itself lives on `sandbox.currentUser`. We don't
+ * shadow it — the source of truth is the sandbox so future
+ * `getFirestore(sandbox)` overloads (deferred follow-up PR) can read
+ * the same value per-call.
+ *
+ * `signInAnonymously` / `signInWithEmailAndPassword` / `signOut` /
+ * `sandbox.setUser` all flow through {@link setCurrentUser}, which
+ * writes `sandbox.currentUser` and fans out to both listener
+ * registries. The sandbox's own `currentUser` setter is idempotent,
+ * so calling it with the same identity twice is a no-op.
+ */
+import { FirebaseError } from 'firebase/app';
+import type { AuthState, Sandbox } from 'pyric/sandbox';
+import { type AuthFlowResolver, type AuthObserver, type IdTokenResult, type Unsubscribe, type User, type UserCredential } from './types.js';
+/** Seed record for `sandbox.seedUsers`. */
+/** Stand-in password for exported provider-flow identities that never had
+ *  one — keeps `exportUsers` → `seedUsers` round-trips lossless without
+ *  widening the `SeedUser` shape. Not a secret: sandbox-only. */
+export declare const NO_PASSWORD_SENTINEL = "__pyric_no_password__";
+export interface SeedUser {
+    uid: string;
+    email: string;
+    password: string;
+    displayName?: string;
+    customClaims?: Record<string, unknown>;
+    /** Originating provider for this identity (e.g. `'google.com'`).
+     *  Defaults to `'password'` — the natural provider for a record
+     *  seeded with an email + password. A host seeding popup-flow
+     *  identities passes the real provider so `listIdentities` /
+     *  `IdTokenResult.signInProvider` label them correctly. */
+    providerId?: string;
+}
+/**
+ * Request for {@link SandboxBackend.mintDetachedSession} — one variant
+ * per client sign-in shape, plus `uid` for existing identities
+ * (session restore, provider-bridge accept).
+ */
+export type MintSessionRequest = {
+    kind: 'anonymous';
+} | {
+    kind: 'password';
+    email: string;
+    password: string;
+} | {
+    kind: 'createPassword';
+    email: string;
+    password: string;
+} | {
+    kind: 'uid';
+    uid: string;
+};
+/** A minted per-connection session: the `User` plus the {@link AuthState}
+ *  its data contexts should carry (`sandbox.withAuth(state)`). */
+export interface MintedSession {
+    user: User;
+    state: NonNullable<AuthState>;
+}
+/** One linked provider on a stored user. Emulator-shaped (the
+ *  Identity Toolkit `providerUserInfo` array) — an array rather than
+ *  a single string so account linking can extend it later. */
+export interface ProviderUserInfo {
+    providerId: string;
+}
+/** "Add account" field set for {@link SandboxBackend.createSignInCredential}
+ *  — mirrors the emulator's add-user form (`customAttributes` →
+ *  `customClaims`). */
+export interface SignInIdentitySpec {
+    /** Defaults to `'<providerId>:<email>'`. */
+    uid?: string;
+    email: string;
+    displayName?: string;
+    customClaims?: Record<string, unknown>;
+}
+/** Internal record in the in-memory user DB. `email`/`password` are
+ *  null for identities that never had them (anonymous users,
+ *  popup-only identities recorded at sign-in time). */
+interface StoredUser {
+    uid: string;
+    email: string | null;
+    password: string | null;
+    displayName: string | null;
+    phoneNumber: string | null;
+    photoUrl: string | null;
+    customClaims: Record<string, unknown>;
+    isAnonymous: boolean;
+    /** Linked providers. Empty for anonymous users (matches the
+     *  emulator: anonymous accounts carry no providerUserInfo; their
+     *  provider surfaces as `sign_in_provider: 'anonymous'` on the
+     *  token instead). */
+    providerUserInfo: ProviderUserInfo[];
+    /** Disabled accounts reject every sign-in attempt with
+     *  `auth/user-disabled` (faithful to prod). */
+    disabled: boolean;
+    emailVerified: boolean;
+    /** ISO timestamp — when the record entered the user DB. */
+    createdAt: string;
+    /** ISO timestamp of the most recent sign-in, or null if this
+     *  identity never signed in. */
+    lastLoginAt: string | null;
+}
+/**
+ * Public per-user record for the user-admin surface
+ * (`sandbox.listUsers` & co.) — emulator-REST-shaped (Identity
+ * Toolkit `accounts:lookup` field names, ISO timestamps).
+ */
+export interface AuthUserRecord {
+    uid: string;
+    email: string | null;
+    displayName: string | null;
+    phoneNumber: string | null;
+    photoUrl: string | null;
+    customClaims: Record<string, unknown>;
+    providerUserInfo: ProviderUserInfo[];
+    isAnonymous: boolean;
+    disabled: boolean;
+    emailVerified: boolean;
+    /** ISO timestamp. */
+    createdAt: string;
+    /** ISO timestamp, or null if the identity never signed in. */
+    lastLoginAt: string | null;
+}
+/** `sandbox.createUser` request. Everything optional except that a
+ *  `password` requires an `email` to be useful for sign-in. */
+export interface CreateUserRequest {
+    /** Defaults to a generated `user-<N>` uid. */
+    uid?: string;
+    email?: string;
+    password?: string;
+    displayName?: string;
+    phoneNumber?: string;
+    photoUrl?: string;
+    customClaims?: Record<string, unknown>;
+    disabled?: boolean;
+    emailVerified?: boolean;
+    /** Linked OAuth providers to create the user with (dedup by
+     *  providerId; multiple providers per user are supported). Same
+     *  rules as {@link UpdateUserRequest.providerUserInfo}: `password`
+     *  is credential-derived (send `password` to link it) and
+     *  `anonymous` is token-level — neither can be forged here. */
+    providerUserInfo?: ProviderUserInfo[];
+}
+/** `sandbox.updateUser` request — `undefined` fields are left
+ *  untouched; `displayName: null` clears it. `customClaims` replaces
+ *  the whole map (admin `setCustomUserClaims` semantics). */
+export interface UpdateUserRequest {
+    displayName?: string | null;
+    email?: string;
+    password?: string;
+    customClaims?: Record<string, unknown>;
+    disabled?: boolean;
+    emailVerified?: boolean;
+    /** REPLACES the user's linked OAuth providers (dedup by providerId;
+     *  multiple providers per user are supported — the record's
+     *  `providerUserInfo` is an array precisely for account linking).
+     *  The `password` entry is credential-derived and managed by the
+     *  backend: it survives the replacement while the user has a
+     *  password and cannot be linked through this field; `anonymous`
+     *  is a token-level provider, never a linked entry. */
+    providerUserInfo?: ProviderUserInfo[];
+}
+/**
+ * Per-sandbox backend state. One instance per `getAuth(sandbox)` —
+ * memoized so repeat calls return the same backing store (matches
+ * `firebase/auth`'s `getAuth(app)` idempotency).
+ */
+export declare class SandboxBackend {
+    /** Email → stored user. Lowercase keys so lookups are case-
+     *  insensitive (matches upstream). */
+    private readonly usersByEmail;
+    /** UID → stored user. Lets `setUser` resolve customClaims for an
+     *  arbitrary uid without scanning the email index. */
+    private readonly usersByUid;
+    /** onAuthStateChanged registrations. Array, NOT a Set, so duplicate
+     *  observer functions register independently — upstream backs each
+     *  registry with an array (`util/src/subscribe.ts:191` pushes; dups
+     *  allowed) and `unsubscribeOne(i)` removes by *index*, so the same
+     *  fn subscribed twice fires twice and one unsubscribe removes one
+     *  registration (AUTH-B4). Each record carries its own initial-fire
+     *  bookkeeping so a shared per-observer dedup can't suppress a
+     *  resubscribe or a second registration of the same fn (AUTH-B3). */
+    private readonly authStateSubs;
+    /** onIdTokenChanged registrations. Same array semantics. */
+    private readonly idTokenSubs;
+    /** `subscribeUsers` subscribers — coarse "user DB changed"
+     *  callbacks; listeners re-list via `listUsers`. */
+    private readonly userDbSubs;
+    /** Monotonic uid counter for `createUser` calls without a uid. */
+    private nextAdminUserId;
+    /** Pre-staged sign-in results, keyed by providerId. The one-shot tier
+     *  of the popup/redirect resolver precedence (see `index.ts`
+     *  `signInWithPopup`): consumed when no resolver is injected, so
+     *  headless conformance fixtures stay deterministic. */
+    private readonly mockResults;
+    /** Injected popup/redirect resolver — the analog of browser
+     *  `getAuth` wiring `browserPopupRedirectResolver`. Null until a host
+     *  (the playground) installs one via `sandbox.setAuthFlowResolver`. */
+    private resolver;
+    /** Pending `getRedirectResult` payload — set by `signInWithRedirect`,
+     *  returned-and-cleared by `getRedirectResult` (one-shot, matches prod). */
+    private redirectResult;
+    /** Monotonic uid counter for anonymous users. */
+    private nextAnonymousId;
+    /** Underlying sandbox — written to on every sign-in/out. */
+    private readonly sandbox;
+    /** Cached `User` for `auth.currentUser` snapshots. Recomputed when
+     *  the sandbox's currentUser changes; null on signed-out. */
+    private cachedUser;
+    /** The uid `onAuthStateChanged` was last notified with. Mirrors
+     *  upstream's `lastNotifiedUid` (`auth_impl.ts:720`): auth-state only
+     *  re-fires when this changes, so a same-uid profile-shape change or a
+     *  same-uid re-sign-in does NOT re-fire auth-state (AUTH-B7). */
+    private lastNotifiedUid;
+    /** True while {@link setCurrentUser} is driving a transition through
+     *  the sandbox setter. The synchronous `onCurrentUserChanged`
+     *  subscriber checks this so it doesn't double-notify — setCurrentUser
+     *  owns the fan-out decision (id-token always, auth-state on uid
+     *  change). The subscriber only notifies for EXTERNAL mutations
+     *  (direct sandbox writes, `reset()`, another handle). */
+    private applyingTransition;
+    /** Per-uid 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;
+    /** Monotonic counter used to disambiguate freshly-minted tokens
+     *  for the same uid + claims map. Without this, two refreshes that
+     *  happen within the same millisecond would hash to the same
+     *  string (claims map + iat tie-breaker not enough). */
+    private nextTokenSerial;
+    /**
+     * Current persistence mode — mirrors the real Firebase SDK's
+     * `setPersistence` semantics. Default is `'LOCAL'` (Firebase default:
+     * `browserLocalPersistence` keeps you signed in across reloads and
+     * browser restarts).
+     *
+     * Stored here on the backend so the persistence controller can read it
+     * without knowing about auth internals. The `auth/index.ts` top-level
+     * `setPersistence` function writes this via `setPersistenceMode`; the
+     * controller reads it via `getPersistenceMode` on every session save.
+     *
+     * Subscribers to persistence-mode changes (the set holding the
+     * controller's session-save callback) are notified by `setPersistenceMode`
+     * so a `setPersistence` call that changes the mode immediately migrates
+     * the session to the new store without waiting for the next sign-in.
+     */
+    private persistenceMode;
+    /** Per-uid provider of the *current/most-recent* sign-in session —
+     *  backs `IdTokenResult.signInProvider` and the synthesized
+     *  `firebase.sign_in_provider` token claim. Written by each
+     *  sign-in path via {@link setCurrentUser}'s `signInProvider`
+     *  argument; `null` for identities driven directly through the
+     *  test driver (`sandbox.setUser`), which has no prod analog. */
+    private readonly signInProviderByUid;
+    /**
+     * Sign-in provider enablement — mirrors a real Firebase project's
+     * Authentication → Sign-in method toggles. GATED at every provider
+     * entry point OF THE ENFORCING BACKEND (owner decision — full
+     * fidelity): `resolveFlow` (`signInWithPopup`/`signInWithRedirect`),
+     * `signInWithCredential`, `createUserWithEmailAndPassword`/
+     * `signInWithEmailAndPassword` (the `'password'` provider), and
+     * `signInAnonymously` (the `'anonymous'` provider). A disabled
+     * provider throws the same `auth/operation-not-allowed` prod throws
+     * — a code deliberately distinct from `auth/argument-error` (which
+     * keeps meaning "no resolver/mock wired" for an ENABLED-but-unmocked
+     * OAuth provider).
+     *
+     * DELEGATION ESCAPE HATCH ({@link providerEnforcementDelegated}): a
+     * backend that is merely a UI vehicle for a REMOTE authority — the
+     * served worker path's page-local sandbox, whose popup picker
+     * resolves identities that a SharedWorker then gates + signs in —
+     * can delegate enforcement to that authority. With delegation on,
+     * {@link assertProviderEnabled} is a no-op HERE and the authority's
+     * own (undelegated) backend gate is the one that decides.
+     *
+     * DEFAULTS DIVERGE FROM A FRESH REAL PROJECT (owner decision,
+     * documented): prod ships every provider OFF until an admin flips it
+     * on in the console. The sandbox ships `'password'` and `'anonymous'`
+     * ON — everything else (`google.com`, `github.com`, `apple.com`,
+     * `microsoft.com`, custom OAuth ids, …) OFF — so the enforcement is
+     * identical to prod but the DEFAULTS are friendlier: every existing
+     * sandbox flow that never called `sandbox.setAuthProviderConfig`
+     * keeps signing in via email/password and anonymous auth unchanged
+     * after this landed.
+     */
+    private readonly providerConfig;
+    /** Subscribers to provider-config changes — the config analog of
+     *  {@link userDbSubs}. Same coarse contract: no payload, re-read via
+     *  {@link listProviderConfig} on each callback. */
+    private readonly providerConfigSubs;
+    /** When true, THIS backend's provider gate is delegated to a remote
+     *  authority (see the {@link providerConfig} docstring's delegation
+     *  section) — {@link assertProviderEnabled} becomes a no-op. Not
+     *  persisted: a runtime wiring decision, not project config. */
+    private providerEnforcementDelegated;
+    constructor(sandbox: Sandbox);
+    /** Snapshot of the current user — backs `auth.currentUser`. */
+    getCurrentUser(): User | null;
+    /**
+     * Subscribe to user change. Fires *immediately* on subscribe with
+     * the current value (mirrors `firebase/auth`'s
+     * `onAuthStateChanged` semantics).
+     *
+     * `kind: 'auth-state'` and `kind: 'id-token'` share the identity-
+     * transition fan-out path; additionally, `getIdToken(true)` fans
+     * out to the `'id-token'` registry only (without re-firing
+     * `'auth-state'`). Matches prod: `onIdTokenChanged` sees both
+     * identity changes AND forced token refreshes.
+     */
+    subscribe(kind: 'auth-state' | 'id-token', observer: AuthObserver): Unsubscribe;
+    /**
+     * Notify the requested registries of the current user. Snapshots
+     * the registration list before iteration so unsubscribes during
+     * emission don't skip remaining subscribers (upstream semantics).
+     *
+     * `kind: 'both'` (default) fires both auth-state and id-token
+     * registries — used for identity transitions.
+     * `kind: 'id-token'` fires ONLY the id-token registry — used for
+     * forced token refreshes, where the user identity hasn't changed
+     * but the token has. Matches prod: `onIdTokenChanged` sees refresh
+     * events; `onAuthStateChanged` does not.
+     */
+    private fanOut;
+    /**
+     * Mirror of upstream `notifyAuthListeners` (`auth_impl.ts:714-723`):
+     *   - `onIdTokenChanged` fires on EVERY notify (every identity update,
+     *     including a same-uid re-sign-in that mints a fresh token —
+     *     AUTH-B8);
+     *   - `onAuthStateChanged` fires ONLY when the uid changed vs the last
+     *     notification (`lastNotifiedUid`) — a same-uid profile-shape
+     *     change does NOT re-fire auth-state (AUTH-B7).
+     * Call this after `cachedUser` is updated.
+     */
+    private notifyAuthListeners;
+    private deliverOne;
+    /** Build a fresh {@link StoredUser} with admin-field defaults. */
+    private makeStored;
+    /** Fan a coarse "user DB changed" notification out to
+     *  `subscribeUsers` listeners. Snapshotted iteration; throwing
+     *  listeners are isolated (same policy as the auth observers). */
+    private notifyUsersChanged;
+    /**
+     * Emit an auth {@link ServiceMutationEvent} onto the sandbox's unified
+     * `onEvent`/`history()` stream (Pyric Studio keystone). Best-effort and
+     * fully isolated — a throw from the emit path (or a sandbox that somehow
+     * isn't a real `SandboxImpl`) must NOT break the auth operation that
+     * triggered it, so we swallow. `auth` defaults to the current sandbox
+     * identity; admin ops (createUser/updateUser/deleteUser) pass `null`
+     * since they have no acting session. `actor` defaults to `{ kind: 'app' }`
+     * via `stampProvenance`.
+     */
+    private emitAuthEvent;
+    /** Subscribe to user-DB mutations (seed/create/update/delete/clear,
+     *  provider links, lastLoginAt bumps). Coarse: no payload, no
+     *  initial fire — re-list via `listUsers` on each callback. */
+    subscribeUsers(cb: () => void): Unsubscribe;
+    /** Whether `providerId` is currently enabled. Unknown providers
+     *  (never toggled) default to `false` — matches a fresh real project,
+     *  EXCEPT `'password'`/`'anonymous'`, which start `true` (see the
+     *  {@link providerConfig} docstring for the rationale). */
+    isProviderEnabled(providerId: string): boolean;
+    /** Every provider this backend has an explicit enablement for —
+     *  seeded defaults (`password`, `anonymous`) plus anything a host
+     *  toggled via {@link setProviderConfig}. */
+    listProviderConfig(): Array<{
+        providerId: string;
+        enabled: boolean;
+    }>;
+    /** Toggle a provider on/off. No-op (no notify) when the value is
+     *  already what was requested — mirrors {@link setPersistenceMode}'s
+     *  dedup so a redundant toggle doesn't churn subscribers / flushes. */
+    setProviderConfig(providerId: string, enabled: boolean): void;
+    private notifyProviderConfigChanged;
+    /** Subscribe to provider-config mutations. Coarse: no payload, no
+     *  initial fire — re-read via {@link listProviderConfig} on each
+     *  callback (same contract as {@link subscribeUsers}). */
+    subscribeProviderConfig(cb: () => void): Unsubscribe;
+    /**
+     * Mark this backend's provider gate as delegated to (or reclaimed
+     * from) a remote authority. See the {@link providerConfig} docstring:
+     * the served worker path sets this on the PAGE-LOCAL sandbox so the
+     * popup picker opens regardless of local toggles — the SharedWorker's
+     * `auth.acceptIdentity` gate (against the worker's own, undelegated
+     * backend) is the enforcement point.
+     */
+    setProviderEnforcementDelegated(delegated: boolean): void;
+    /**
+     * Gate a provider entry point. Throws real Firebase's
+     * `auth/operation-not-allowed` (exactly the code/shape prod throws
+     * for a disabled sign-in method) when `providerId` is off. Called by
+     * every provider-flow entry point in `index.ts` BEFORE any other
+     * work, so a disabled provider never touches the user DB / mock
+     * registry / resolver. A no-op when enforcement is delegated to a
+     * remote authority ({@link setProviderEnforcementDelegated}).
+     */
+    assertProviderEnabled(providerId: string): void;
+    /** Snapshot the full provider-config map for the persistable-service
+     *  `snapshot()` hook — plain JSON, ready to embed under the `auth`
+     *  service's `providers` key. */
+    exportProviderConfig(): Record<string, boolean>;
+    /**
+     * Restore provider config from a persisted blob — a REPLACE, not a
+     * merge (same policy as `seedUsers`'s persistence path: the map
+     * becomes EXACTLY what `data` holds). When `data` is missing/invalid
+     * — including every blob written BEFORE this feature landed, which
+     * has no `providers` key at all — falls back to the documented
+     * defaults (`password`/`anonymous` enabled) rather than leaving the
+     * map empty, so an old `--persist` file doesn't silently lock
+     * existing sandbox flows out of email/password + anonymous sign-in.
+     */
+    restoreProviderConfig(data: Record<string, boolean> | undefined): void;
+    /**
+     * Read the current persistence mode. Used by the session-persistence
+     * controller to decide which web-storage slot (local / session) to
+     * write the signed-in uid into.
+     *
+     * The default value is `'LOCAL'` — matches Firebase's default of
+     * `browserLocalPersistence` (you stay signed in across page reloads
+     * and browser restarts unless you explicitly call `setPersistence`).
+     */
+    getPersistenceMode(): 'LOCAL' | 'SESSION' | 'NONE';
+    /**
+     * Record the new persistence mode. Called by the auth `setPersistence`
+     * function when the sandbox target receives a mode change.
+     *
+     * Changing the mode notifies the session-change subscribers so the
+     * persistence controller can IMMEDIATELY migrate the stored uid to
+     * the new web-storage slot — matching the real SDK's behavior where
+     * `setPersistence` carries the active session across modes before
+     * returning.
+     *
+     * Why notify on mode change (not just on sign-in/out): the session
+     * controller subscribes to "something about this session changed"
+     * events and re-reads both `currentUid()` and `mode()` on each fire.
+     * Notifying here lets the controller react to a mode change with the
+     * same code path as a sign-in/out, rather than a separate migration
+     * hook.
+     */
+    setPersistenceMode(mode: 'LOCAL' | 'SESSION' | 'NONE'): void;
+    /**
+     * Subscribers that need to react to ANY session state change —
+     * sign-in, sign-out, or persistence-mode change. The controller
+     * installs one subscriber here to drive session saves.
+     *
+     * Separate from `currentUserSubs` (on the sandbox) because we need
+     * to fire on mode changes (which don't change the currentUser) and
+     * because the backend owns the mode — it's cleaner to keep both
+     * signals on the same object.
+     */
+    private readonly sessionChangeSubs;
+    /** Notify all session-change subscribers. Used by `setCurrentUser`
+     *  (sign-in / sign-out) and by `setPersistenceMode` (mode change). */
+    private notifySessionChanged;
+    /**
+     * Subscribe to session-level changes: sign-in, sign-out, and
+     * persistence-mode changes. The persistence controller installs one
+     * subscription here and re-saves the session on every fire.
+     *
+     * This is the mechanism the `PersistableService.session.subscribe`
+     * hook exposes — the controller doesn't need to know it's subscribing
+     * to two separate event sources (sign-in/out AND mode); they both
+     * flow through this one subscription.
+     */
+    subscribeSession(cb: () => void): Unsubscribe;
+    seedUsers(users: ReadonlyArray<SeedUser>): void;
+    /**
+     * 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.
+     */
+    exportUsers(): SeedUser[];
+    /**
+     * Re-establish a signed-in session for an EXISTING identity — the
+     * substrate behind web-storage session persistence (`setPersistence`
+     * parity at the serve layer). Fires the auth-state listeners exactly
+     * like a real restored session. Throws `auth/user-not-found` for
+     * unknown uids and `auth/user-disabled` for disabled accounts (a
+     * restore is a sign-in).
+     */
+    restoreSession(uid: string): User;
+    findByEmail(email: string): StoredUser | undefined;
+    createEmailPasswordUser(email: string, password: string): StoredUser;
+    /**
+     * Set the active user. Owns the fan-out decision directly (rather than
+     * leaning on the sandbox setter's structural-equality dedup), so it can
+     * mirror upstream `notifyAuthListeners`: `onIdTokenChanged` fires on
+     * every sign-in (incl. a same-uid re-sign-in that mints a fresh token —
+     * AUTH-B8), while `onAuthStateChanged` fires only on a uid change
+     * (AUTH-B7). The `applyingTransition` guard suppresses the synchronous
+     * `onCurrentUserChanged` subscriber so we don't double-notify.
+     *
+     * `signInProvider` (when passed) records the provider of THIS
+     * sign-in session — it feeds `IdTokenResult.signInProvider` and the
+     * synthesized `firebase.sign_in_provider` claim. Omitted by the
+     * test driver (`sandbox.setUser`), which leaves any previous value
+     * in place.
+     */
+    setCurrentUser(user: User | null, signInProvider?: string | null): void;
+    setMockResult(providerId: string, result: UserCredential): void;
+    consumeMockResult(providerId: string): UserCredential | undefined;
+    setResolver(resolver: AuthFlowResolver | null): void;
+    getResolver(): AuthFlowResolver | null;
+    /** Stash the credential a `signInWithRedirect` produced; `getRedirectResult`
+     *  returns-and-clears it. */
+    setRedirectResult(result: UserCredential): void;
+    takeRedirectResult(): UserCredential | null;
+    /**
+     * Record a provider-flow sign-in (popup / redirect / credential)
+     * against the user DB so the identity shows up in `listIdentities`
+     * 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.
+     */
+    recordProviderSignIn(user: User, providerId: string): void;
+    /**
+     * Mint a sign-in credential for a host-driven flow (the account
+     * picker behind `AuthFlowResolver`). Token + claims synthesis is
+     * backend-owned: the returned `User`'s `getIdToken` /
+     * `getIdTokenResult` route through this backend's token cache, so
+     * helper-driven sign-ins get real (cached, refreshable,
+     * provider-labeled) sandbox tokens instead of host-synthesized
+     * strings.
+     *
+     * Two request shapes:
+     *   - `{providerId, uid}` — credential for an EXISTING identity
+     *     (the picker's "pick" action). Throws `invalid-argument` for
+     *     unknown uids.
+     *   - `{providerId, spec}` — upsert a new identity (the picker's
+     *     "add account"). If `spec.email` already belongs to a stored
+     *     user, that identity is reused and the provider linked
+     *     (Google-style same-email account reuse); otherwise a fresh
+     *     record is created with uid `spec.uid ?? '<providerId>:<email>'`
+     *     and NO password (provider identities can't sign in via
+     *     `signInWithEmailAndPassword`).
+     *
+     * In both shapes the provider is linked into `providerUserInfo`.
+     * The credential does NOT sign the user in — hand it to the
+     * resolver's promise; `signInWithPopup`/`signInWithRedirect`
+     * complete the sign-in.
+     */
+    createSignInCredential(req: {
+        providerId: string;
+        uid: string;
+    } | {
+        providerId: string;
+        spec: SignInIdentitySpec;
+    }): UserCredential;
+    /** Snapshot of every known identity (seeded + created), for a host
+     *  account-picker UI. No `firebase/auth` equivalent — sandbox-only.
+     *
+     *  `providerId` is the primary provider label (first linked
+     *  provider, or `'anonymous'` for anonymous users);
+     *  `providerUserInfo` is the full emulator-shaped array. */
+    listIdentities(): Array<{
+        uid: string;
+        email: string | null;
+        displayName: string | null;
+        providerId: string;
+        providerUserInfo: ProviderUserInfo[];
+        isAnonymous: boolean;
+        customClaims: Record<string, unknown>;
+    }>;
+    /** Public snapshot of a stored user. Defensive copies — mutating a
+     *  returned record never touches the DB. */
+    private toRecord;
+    /** Every user in the DB (seeded, created, signed-in-via-provider,
+     *  anonymous), as admin records. */
+    listUsers(): AuthUserRecord[];
+    /** Sanitize an admin-supplied linked-provider list (create + update):
+     *  dedup by providerId, reject empty ids, and refuse the two ids that
+     *  are NOT linkable entries — `password` is credential-derived (a
+     *  password on the account links it; it leads the list when present)
+     *  and `anonymous` surfaces on the token, never on the record. */
+    private sanitizeLinkedProviders;
+    /** 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;
+    /** Admin user update. `undefined` fields untouched; `customClaims`
+     *  replaces the whole map (admin `setCustomUserClaims` semantics).
+     *  Claims changes reach an ACTIVE session only on the next token
+     *  refresh / sign-in — same propagation story as prod. */
+    updateUser(uid: string, update: UpdateUserRequest): AuthUserRecord;
+    /** Admin user deletion. The active session (if it's this user) is
+     *  NOT terminated — matches prod, where admin deletion doesn't kill
+     *  live client sessions until the token is revoked/refreshed. */
+    deleteUser(uid: string): void;
+    /** Drop every user record (the emulator's "delete all accounts").
+     *  Active sessions are untouched, like {@link deleteUser}. */
+    clearUsers(): void;
+    /** Throw `auth/user-disabled` if the uid resolves to a disabled
+     *  record. Called by every provider-flow sign-in path; the
+     *  email/password path runs the same check inside
+     *  {@link validatePassword}. */
+    assertSignInAllowed(uid: string): void;
+    /**
+     * Mint a `User` shell for the given stored record. Used by all
+     * email/password and popup sign-in paths.
+     */
+    buildUserFromStored(stored: StoredUser): User;
+    /** Mint a fresh anonymous user with an auto-generated uid. Records
+     *  the identity in the user DB (empty `providerUserInfo`, matching
+     *  the emulator) so `listIdentities` / future user-admin surfaces
+     *  see anonymous accounts too. */
+    mintAnonymousUser(): User;
+    /**
+     * Mint a session identity WITHOUT making it the global current user —
+     * the substrate for per-connection identity at the serve layer (one
+     * SharedWorker sandbox, N tab sessions; issue #754). Performs a real
+     * sign-in's bookkeeping — provider record, `lastLoginAt` bump, a fresh
+     * token (new session = new token), the `sign_in` activity event — but
+     * leaves `sandbox.currentUser`, the auth-state listeners, and the
+     * session-change subscribers untouched.
+     *
+     * Returns the `User` plus the {@link AuthState} a data context should
+     * carry (`sandbox.withAuth(state)`) so rules evaluate exactly as they
+     * would for a globally signed-in user (`request.auth.uid` + custom
+     * claims on `request.auth.token`).
+     *
+     * GATING: `'anonymous'` / `'password'` / `'createPassword'` run through
+     * {@link assertProviderEnabled} — this is the path the served worker's
+     * per-port sessions actually use (`sandbox.mintSession`, NOT the
+     * `index.ts` free functions), so without this the provider toggle would
+     * have zero effect in `pyric dev`/Studio's served mode, the primary
+     * product surface. `'uid'` (session RESTORE for an existing identity —
+     * a page reload re-establishing a previously-valid session) is
+     * deliberately NOT gated, matching {@link restoreSession}: disabling a
+     * provider after the fact doesn't retroactively invalidate an already-
+     * authenticated session, same as real Firebase.
+     */
+    mintDetachedSession(request: MintSessionRequest): MintedSession;
+    /** The shared sign-in bookkeeping behind {@link mintDetachedSession} —
+     *  everything {@link setCurrentUser} does for a real sign-in EXCEPT the
+     *  global-session parts. */
+    private establishDetachedSession;
+    /** Reconstruct a `User` object from an {@link AuthState}. Returns
+     *  `null` for `null` input. Used to mirror sandbox-level state
+     *  changes that didn't originate from this backend. */
+    private buildUserFromState;
+    /**
+     * Mint a fresh `{ token, result }` for the given uid + claims. Used
+     * both on initial `getIdToken` (cache miss) and on a forced
+     * refresh. Each call advances {@link nextTokenSerial} so two
+     * refreshes inside the same millisecond still produce distinct
+     * token strings.
+     */
+    private mintToken;
+    /**
+     * Get-or-mint the ID token entry for a uid. `forceRefresh: true`
+     * always mints a fresh token, overwrites the cache, and fires the
+     * `onIdTokenChanged` listeners (NOT `onAuthStateChanged` — the
+     * user identity didn't change). Matches prod oracle observations:
+     *
+     *   - `auth-getidtoken-force-refresh.json` — forceRefresh returns a
+     *     different string than the previous read; a subsequent
+     *     getIdToken(false) returns the new (cached) token.
+     *   - `auth-onidtokenchanged-force-refresh.json` — onIdTokenChanged
+     *     fires after a forced refresh.
+     */
+    getIdTokenFor(uid: string, claims: Record<string, unknown>, forceRefresh: boolean): string;
+    /** {@link getIdTokenFor} variant returning the full IdTokenResult.
+     *  Same cache + fan-out semantics. */
+    getIdTokenResultFor(uid: string, claims: Record<string, unknown>, forceRefresh: boolean): IdTokenResult;
+    /**
+     * Build a `User` shell whose `getIdToken` / `getIdTokenResult`
+     * route through the backend's token cache. The User object closes
+     * over its uid + claims; the cache is owned by the backend so all
+     * User instances for the same uid agree on the current token.
+     */
+    private makeUser;
+    /**
+     * Update a signed-in user's profile (`displayName` / `photoURL`) — the
+     * backend behind the top-level `updateProfile(user, profile)`.
+     *
+     * Updates the stored record, then mutates the passed `user` AND
+     * `this.cachedUser` IN PLACE when their uid matches (the `User` fields are
+     * TS-`readonly` but runtime-mutable, so held references — including
+     * `auth.currentUser` — reflect the change without a re-read). Only a field
+     * whose `profile.<field> !== undefined` is applied, so `null` clears and
+     * `undefined` leaves the field untouched.
+     *
+     * Fires the coarse user-DB change (`notifyUsersChanged`) + a `user_update`
+     * activity event, but does NOT fan out auth-state / id-token listeners:
+     * real `firebase/auth.updateProfile` does not fire `onAuthStateChanged` /
+     * `onIdTokenChanged`.
+     */
+    updateProfileFor(user: User, profile: {
+        displayName?: string | null;
+        photoURL?: string | null;
+    }): void;
+    /** Mutate a `User`'s `displayName` / `photoURL` (and the first
+     *  `providerData` entry's, when present) in place. `readonly` at the type
+     *  level, mutable at runtime — cast through a Mutable helper. Only applies a
+     *  field when it was explicitly provided (`!== undefined`). */
+    private applyProfileToUser;
+    /**
+     * Worker-path `updateProfile`: update the stored record for `uid`
+     * (+ mutate `this.cachedUser` in place if it matches), then return the
+     * refreshed {@link AuthUserRecord}. The worker holds the real per-port
+     * session `User` and mutates it separately (host-auth.ts). Throws
+     * `auth/user-not-found` for an unknown uid.
+     */
+    updateProfileByUid(uid: string, profile: {
+        displayName?: string | null;
+        photoURL?: string | null;
+    }): AuthUserRecord;
+    /** Live customClaims for a uid — the current value in the user DB,
+     *  falling back to `fallback` for uids the DB doesn't track (anonymous
+     *  / popup users). Used so a re-seed / `updateUser` is reflected in
+     *  held users' forced-refresh tokens (AUTH-B10). */
+    private liveClaims;
+    /** 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,
+     *  `auth/user-not-found` if the email isn't seeded.
+     *
+     *  Format validation fires BEFORE the user-DB lookup so callers
+     *  shipping malformed inputs see the same `auth/invalid-email`
+     *  prod returns — they wouldn't reach the missing-user path in
+     *  production either. Password-strength is NOT enforced on sign-in
+     *  (a previously-weak seeded password should still let the user
+     *  in); only `createUserWithEmailAndPassword` runs the strength
+     *  check, mirroring prod. */
+    validatePassword(email: string, password: string): StoredUser;
+}
+/**
+ * Build a real `FirebaseError` (the same class `firebase/auth` throws),
+ * with the prod message wrapper `Firebase: <message> (<code>).`
+ * (`clones/.../util/src/errors.ts:121` — `${serviceName}: ${message}
+ * (${fullCode}).`, serviceName `Firebase`). So consumer code that does
+ * `err instanceof FirebaseError` or matches on the wrapped message sees
+ * the same shape sandbox vs prod (AUTH-GAP). `.code` is preserved.
+ *
+ * Oracle-pinned shapes this reproduces:
+ *   - `Firebase: Error (auth/invalid-email).`
+ *   - `Firebase: Password should be at least 6 characters (auth/weak-password).`
+ */
+export declare function makeAuthError(code: string, message: string): FirebaseError;
+export {};
+//# sourceMappingURL=sandbox-backend.d.ts.map