pyric/auth compatibility matrix
64.4% of the public API supported
96 of 149 public API
Status legend
getAuth(target) — initializer
getAuth(target)Returns a stable Auth handle for repeated calls with the same input
unit:sandbox-anonymous.test.ts + canonical Node register child (register-child.test.ts)getAuth(target)getAuth(sandbox) dispatches to the sandbox backend
getAuth(target)Without sandbox package swapping, canonical firebase/auth imports remain Firebase and never enter this mirror
unit:package-resolution.test.ts; an unswapped production-resolution observation is still neededgetAuth(target)After package swapping, bare getAuth() resolves the registered default sandbox app; without swapping, Firebase retains its app/no-app behavior when no default app exists
register-child.test.ts) + oracle: packages/conformance/observations/auth/auth-bare-getauth-no-default-app.json (code: 'app/no-app' against digame-mas, fb-js-sdk 12.19.0 — confirms unswapped Firebase behavior)getAuth(target)auth.currentUser is a live getter, not a snapshot — reads through to the backend on every access
unit:sandbox-anonymous.test.tsMulti-app Auth session topology
getAuth(app)Equal-config Firebase apps have independent active Auth sessions; signing in or out on one app does not change another app's currentUser
app-production-multi-app-topology (firebase 12.19.0, real Chromium against production) + twin replay: packages/pyric/test/app/production-multi-app-oracle.test.tsbrowserLocalPersistence across same-named app instances in sibling tabsAfter the sibling receives the LOCAL persistence event, same-named Firebase app instances in sibling tabs keep independent active Auth sessions; an anonymous sign-in in one tab does not update the sibling tab's currentUser during the bounded post-signal observation window
app-production-cross-tab-auth-persistence (firebase 12.19.0, two real Chromium pages in one browser context) + served twin: packages/cli/test/e2e/app-multi-app.pw.tssignInAnonymously(auth) — anonymous
signInAnonymously(auth)Returns UserCredential with providerId: null, operationType: 'signIn', and a User with isAnonymous: true, email: null, displayName: null
unit:sandbox-anonymous.test.ts, playground:auth-anonymous (bundled) + playground:auth-row-6-anon-credential-shape (one-claim) + oracle: packages/conformance/observations/auth/auth-anonymous-credential-providerid.json (providerId: null against digame-mas, fb-js-sdk 12.19.0). Prior matrix language said providerId: 'anonymous'; corrected after empirical observation. Sandbox aligned to prod in the same commit.signInAnonymously(auth)Auto-generates a uid for fresh sign-ins (sandbox format: anonymous-{N})
unit:sandbox-anonymous.test.ts — prod uids are 28-char base64-ish; sandbox uses a readable counter for debuggabilitysignInAnonymously(auth)If an anonymous user is already signed in, returns the SAME user (no fresh uid mint)
unit:sandbox-anonymous.test.ts ("idempotent while signed in") — fix from #399signInAnonymously(auth)After signOut, a subsequent signInAnonymously mints a fresh uid
unit:sandbox-anonymous.test.ts, playground:auth-anonymous (bundled) + playground:auth-row-9-anon-fresh-uid-after-signout (one-claim)signInAnonymously(auth)Fires onAuthStateChanged exactly once per state transition (no same-value double-fire)
unit:sandbox-listeners.test.ts, playground:auth-anonymous (bundled) + playground:auth-row-10-onauthstatechanged-one-per-transition (one-claim) — fix from #399 + oracle: packages/conformance/observations/auth/auth-row-10-onauthstatechanged-one-per-transition.json (against digame-mas, fb-js-sdk 12.19.0: subscribe → 1 initial null fire → signInAnonymously → +1 → signOut → +1 → signInAnonymously → +1. eachTransitionFiredExactlyOnce: true — every transition produces exactly one fire)signInAnonymously(auth)Writes through to sandbox.currentUser so rules engines see request.auth.uid
unit:sandbox-anonymous.test.ts, playground:auth-anonymous (bundled) + playground:auth-row-11-anon-uid-visible-to-rules (one-claim)signInAnonymously(auth)Anonymous users persist across page reload via configured Persistence (prod only — sandbox has no persistence layer)
signInWithEmailAndPassword(auth, email, password) — password
signInWithEmailAndPassword(auth, email, password)Returns UserCredential with providerId: null (NOT 'password' — only OAuth/phone responses carry a providerId; upstream providerIdForResponse returns null for email/password), operationType: 'signIn', and a User with the stored uid + email
unit:sandbox-email-password.test.ts + oracle: packages/conformance/observations/auth/auth-createUser-operationType.json (providerId: null against digame-mas, fb-js-sdk 12.19.0). Prior matrix language said providerId: 'password'; corrected after the oracle contradicted it (AUTH-B2).signInWithEmailAndPassword(auth, email, password)Production answers auth/invalid-credential for an unknown email with Email Enumeration Protection on. pyric throws auth/user-not-found
auth-user-not-found-error-code records auth/invalid-credential. The oracle suite pins both sides. Pending fix, #1819. (Structured evidence: oracle-conformance.test.ts, sandbox-email-password.test.ts)signInWithEmailAndPassword(auth, email, password)Production answers auth/invalid-credential for a wrong password with Email Enumeration Protection on. pyric throws auth/wrong-password
auth-wrong-password-error-code records auth/invalid-credential. The oracle suite pins both sides. Pending fix, #1819. (Structured evidence: oracle-conformance.test.ts, sandbox-email-password.test.ts)signInWithEmailAndPassword(auth, email, password)An EMPTY password throws auth/missing-password (message "A non-empty password must be provided"), fired before the user-DB lookup so it can't be used to enumerate seeded emails. Upstream maps the MISSING_PASSWORD server error (core/errors.ts:92,282,563). ⚠ best-known semantics — message text not yet captured against a live project (STOP-flagged for an oracle pass; the .code is the load-bearing part).
unit:sandbox-cluster-b9-b12.test.ts (locks AUTH-B11)signInWithEmailAndPassword(auth, email, password)Re-signing in after signOut returns the same uid (passwords persist within the sandbox lifetime)
playground:auth-email-password (bundled) + playground:auth-row-16-resignin-same-uid (one-claim)signInWithEmailAndPassword(auth, email, password)Fires onAuthStateChanged with the new user once
unit:sandbox-listeners.test.ts + oracle: packages/conformance/observations/auth/auth-row-17-signin-email-password-fires-once.json (against digame-mas, fb-js-sdk 12.19.0: createUser → signOut → subscribe (1 initial null fire) → signInWithEmailAndPassword → firesForSignIn: 1 with the signed-in uid, lastFireUidMatches: true)signInWithEmailAndPassword(auth, email, password)Email validation (RFC 5322ish) — rejects empty, missing @, missing local-part, missing domain with auth/invalid-email. Runs on both signInWithEmailAndPassword and createUserWithEmailAndPassword before any user-DB lookup, so consumers shipping malformed input see the same error sandbox vs prod.
unit:sandbox-email-password.test.ts + oracle: packages/conformance/observations/auth/auth-row-18-invalid-email-error-code.json (code: 'auth/invalid-email', message Firebase: Error (auth/invalid-email). against digame-mas, fb-js-sdk 12.19.0)signInWithEmailAndPassword(auth, email, password)Password strength requirements — rejects passwords shorter than 6 chars with auth/weak-password on createUserWithEmailAndPassword. Strength is NOT enforced on signInWithEmailAndPassword so previously-seeded weak passwords still let the user in (matches prod's separation of registration vs sign-in).
unit:sandbox-email-password.test.ts + oracle: packages/conformance/observations/auth/auth-row-19-weak-password-error-code.json (code: 'auth/weak-password', message Firebase: Password should be at least 6 characters (auth/weak-password). against digame-mas, fb-js-sdk 12.19.0; matrix language "≥6 chars per prod default" empirically confirmed)signInWithEmailAndPassword(auth, email, password)Disabled accounts (sandbox.updateUser(…, {disabled: true})) reject sign-in with auth/user-disabled and prod's documented message (The user account has been disabled by an administrator.). Sandbox checks disabled BEFORE the password compare (anti-probing); the exact prod ordering of disabled-vs-wrong-password needs an oracle capture. Disabling leaves a held session signed in until its next token refresh, which rejects auth/user-disabled and signs the user out (@firebase/auth _logoutIfInvalidated), on the in-page and worker planes; a deleted account's refresh, or one authenticated before a password change, rejects auth/user-token-expired the same way (#1950). The revocation times and deletions hold across an in-page reload (#2018) and a checkpoint restore, branch fork or promote (#2021); a worker or hosted restore re-checks each held session and signs a refused one out at the restore, where production keeps it until its next refresh fails
unit:sandbox-user-admin.test.ts ("disabled users", "a refresh for a disabled or deleted account (#1950)"); worker port: unit:auth.test.ts ("a refused refresh signs the port out (#1950)"); the app scenario test/apps/id-token-bearer-header disables, deletes and changes the password of a signed-in account with pyric auth and checks the page's next refresh, and restores a checkpoint taken after a revocation. Reload and restore: unit:auth-session-persistence.test.ts ("a revoked session stays refused after a reload (#2018)"), unit:full-state.test.ts ("a captured state carries revocations and deletions (#2021)"), the worker's restore op in unit:auth.test.ts, and the app scenario test/apps/inpage-auth-revocation-reload. Upstream source: @firebase/auth 1.13.6 maps USER_DISABLED to auth/user-disabled and USER_NOT_FOUND and TOKEN_EXPIRED to auth/user-token-expired. A production observation of the refresh after disable is still neededcreateUserWithEmailAndPassword(auth, email, password) — register
createUserWithEmailAndPassword(auth, email, password)Creates a new user, signs them in automatically (currentUser becomes the new user)
playground:auth-email-password (bundled) + playground:auth-row-20-create-user-auto-signs-in (one-claim), unit:sandbox-email-password.test.tscreateUserWithEmailAndPassword(auth, email, password)Returns UserCredential with operationType: 'signIn' (NOT 'register' — matches prod)
unit:sandbox-email-password.test.ts + oracle: packages/conformance/observations/auth/auth-createUser-operationType.json (operationType: 'signIn' against digame-mas, fb-js-sdk 12.19.0; matches sandbox) (Structured evidence: oracle-conformance.test.ts)createUserWithEmailAndPassword(auth, email, password)Throws auth/email-already-in-use when the email is already registered
unit:sandbox-email-password.test.ts + oracle: packages/conformance/observations/auth/auth-email-already-in-use-error-code.json (code: 'auth/email-already-in-use' against digame-mas, fb-js-sdk 12.19.0; matches sandbox)createUserWithEmailAndPassword(auth, email, password)The created user has isAnonymous: false, email: <input>, displayName: null
unit:sandbox-email-password.test.ts + playground:auth-row-23-create-user-shape (one-claim)createUserWithEmailAndPassword(auth, email, password)Fires onAuthStateChanged with the new user once
unit:sandbox-listeners.test.ts + oracle: packages/conformance/observations/auth/auth-row-24-createuser-fires-once.json (against digame-mas, fb-js-sdk 12.19.0: subscribe (1 initial null fire) → createUserWithEmailAndPassword → firesForCreate: 1 with the newly-created uid, lastFireUidMatches: true)signOut(auth)
signOut(auth)Sets currentUser to null synchronously after resolution
playground:auth-anonymous (bundled) + playground:auth-row-25-signout-currentuser-null (one-claim), unit:sandbox-anonymous.test.ts + oracle: packages/conformance/observations/auth/auth-row-25-signout-currentuser-null-sync.json (currentUserIsNullSync: true against digame-mas, fb-js-sdk 12.19.0 — auth.currentUser read in the synchronous continuation immediately after await signOut(auth) is already null, with no microtask/macrotask required to settle)signOut(auth)Fires onAuthStateChanged with null exactly once
unit:sandbox-listeners.test.ts, playground:auth-anonymous (bundled) + playground:auth-row-26-signout-fires-null-once (one-claim) + oracle: packages/conformance/observations/auth/auth-row-26-signout-fires-null-once.json (against digame-mas, fb-js-sdk 12.19.0: subscribe (1 initial null fire) → signInAnonymously → signOut → firesForSignOut: 1 with lastFireUidWasNull: true)signOut(auth)Idempotent — signOut on already-signed-out user is a no-op (no listener fire)
playground:auth-signout-idempotent + oracle-confirmed: packages/conformance/observations/auth/auth-signout-idempotent.json (threw: false, redundantSignOutFiredListener: false against digame-mas)signOut(auth)Clears the active session's persistence in prod; sandbox has no persistence
onAuthStateChanged(auth, observer)
onAuthStateChanged(auth, observer)Fires immediately on subscribe with the current value (microtask-deferred)
unit:sandbox-listeners.test.ts + oracle: packages/conformance/observations/auth/auth-row-29-onauthstatechanged-initial-fire-timing.json (firedSynchronously: 0, firedAfterMicrotask: 1 against digame-mas, fb-js-sdk 12.19.0 — initial fire does NOT arrive in the synchronous tick of onAuthStateChanged(...); it lands after the first microtask flush)onAuthStateChanged(auth, observer)Fires on every subsequent identity change
unit:sandbox-listeners.test.ts, playground:auth-anonymous + oracle: packages/conformance/observations/auth/auth-row-30-onauthstatechanged-fires-on-every-transition.json (against digame-mas, fb-js-sdk 12.19.0: subscribe → signIn → signOut → signIn → signOut, each of the 4 transitions produced exactly 1 fire; eachTransitionFiredExactlyOnce: true)onAuthStateChanged(auth, observer)Dedups by uid: a same-uid update (profile-shape change, or a same-uid re-sign-in) does NOT re-fire onAuthStateChanged — only an actual uid change does. Mirrors upstream notifyAuthListeners's lastNotifiedUid gate (auth_impl.ts:718-723). (onIdTokenChanged still fires on those same-uid updates — see row 38a.)
unit:sandbox-uid-dedup.test.ts (locks AUTH-B7 / B8)onAuthStateChanged(auth, observer)No duplicate fire when subscribe is followed by a synchronous setCurrentUser — dedup ensures observer sees the new value once, not twice. Sandbox-only concern: prod has no synchronous state-change API, so the dedup window can't be exercised against the cloud SDK; subscribe-then-async-signIn naturally fires twice (initial + new value) because the microtask between them flushes the initial fire
unit:sandbox-listeners.test.ts (regression test from #399), playground:auth-anonymous + oracle baseline: packages/conformance/observations/auth/auth-row-31-onauthstatechanged-no-dup-on-sync-transition.json (against digame-mas, fb-js-sdk 12.19.0: subscribe + async signInAnonymously in the same tick produces totalFires: 2 — {uid: null, ts: 0} then {uid: <user>, ts: ~400ms}. Confirms prod cannot exhibit the same-tick race; the dedup behavior remains a sandbox-only property)onAuthStateChanged(auth, observer)Returned Unsubscribe removes the observer; subsequent state changes do NOT fire it
unit:sandbox-listeners.test.ts, playground:auth-listener-unsub (bundled) + playground:auth-row-32-unsubscribe-stops-fires (one-claim) + oracle: packages/conformance/observations/auth/auth-row-32-unsubscribe-stops-fires.json (against digame-mas, fb-js-sdk 12.19.0: subscribe → 1 fire on signInAnonymously → call unsub() → signOut + signInAnonymously + signOut produce zero further fires; postUnsubFires: 0, unsubscribeStoppedFires: true)onAuthStateChanged(auth, observer)Multiple subscribers all fire on each change
unit:sandbox-listeners.test.ts + oracle: packages/conformance/observations/auth/auth-row-33-multiple-subscribers-all-fire.json (against digame-mas, fb-js-sdk 12.19.0: two subscribers registered back-to-back each see 1 initial null fire, +1 on signInAnonymously, +1 on signOut; bothFiredOnSignIn: true, bothFiredOnSignOut: true)onAuthStateChanged(auth, observer)Registry is array-backed (matches upstream util/subscribe.ts): the SAME observer fn registered N times produces N independent registrations that each fire, and one Unsubscribe removes exactly one registration. A resubscribe of a previously-unsubscribed fn fires its initial value again. (Per-registration initial-fire bookkeeping, not a shared per-observer dedup.)
unit:sandbox-listener-registry.test.ts (locks AUTH-B3 + AUTH-B4)onAuthStateChanged(auth, observer)Unsubscribing during emission does not skip remaining subscribers (snapshotted iteration)
onAuthStateChanged(auth, observer)A throwing observer doesn't block other observers from firing
unit:sandbox-listeners.test.ts + oracle: packages/conformance/observations/auth/auth-row-35-throwing-observer-doesnt-block-others.json (secondObserverContinuedFiring: true against digame-mas, fb-js-sdk 12.19.0 — observer #1 throws on every call, observer #2 still counts the initial fire AND the post-sign-in fire)onAuthStateChanged(auth, observer)Observer object form ({next, error, complete}) works alongside the function form
unit:sandbox-listeners.test.ts + oracle: packages/conformance/observations/auth/auth-row-36-observer-object-form-works.json (against digame-mas, fb-js-sdk 12.19.0: one observer as NextFn, another as {next, error, complete}. Both forms see 1 initial null fire, +1 on signInAnonymously, +1 on signOut; bothFormsFiredOnSignIn: true, bothFormsFiredOnSignOut: true)onAuthStateChanged(auth, observer)Setting the same user twice does NOT double-fire (structural-equality no-op). Sandbox-internal setCurrentUser claim; the prod analog is signInAnonymously called twice in a row (per fix #399, the second call returns the same user).
unit:sandbox-listeners.test.ts + oracle: packages/conformance/observations/auth/auth-row-37-same-user-no-double-fire.json (against digame-mas, fb-js-sdk 12.19.0: first signInAnonymously fires the listener once; second call returns the same uid (sameUserAcrossCalls: true) and does NOT produce a fresh fire (secondSignInProducedFire: false). Prod also recognizes the same-user no-op)onIdTokenChanged(auth, observer)
onIdTokenChanged(auth, observer)Fires on user change (sandbox shares the auth-state path)
unit:sandbox-listeners.test.ts + oracle: packages/conformance/observations/auth/auth-row-38-onidtokenchanged-fires-on-user-change.json (against digame-mas, fb-js-sdk 12.19.0: subscribe → 1 initial fire (null) → signInAnonymously → +1 (user₁) → signOut → +1 (null) → signInAnonymously → +1 (user₂ with fresh uid). Every identity transition produces exactly one fire, matching onAuthStateChanged)onIdTokenChanged(auth, observer)Fires on EVERY sign-in, including a same-uid re-sign-in (no signOut first) — which mints a fresh token, so a subsequent getIdToken() returns a new string. Mirrors upstream notifyAuthListeners, which calls idTokenSubscription.next on every identity update (auth_impl.ts:716). onAuthStateChanged stays silent on the same-uid case (row 30a).
unit:sandbox-uid-dedup.test.ts (locks AUTH-B8)onIdTokenChanged(auth, observer)Fires on token refresh (getIdToken(true))
unit:sandbox-token-refresh.test.ts — was ⚠ (documented divergence); aligned to prod in commit — sandbox now mints a fresh token on forceRefresh and fires onIdTokenChanged (NOT onAuthStateChanged, since identity is unchanged). Oracle: packages/conformance/observations/auth/auth-onidtokenchanged-force-refresh.json defines the target shape (refreshFiredListener: true against digame-mas; subscribe → null fire → signInAnonymously → +1 → getIdToken(true) → +1 for a total of 3 fires).onIdTokenChanged(auth, observer)Initial-fire semantics match onAuthStateChanged
unit:sandbox-listeners.test.ts + oracle: packages/conformance/observations/auth/auth-row-40-onidtokenchanged-matches-onauthstatechanged-initial-fire.json (against digame-mas, fb-js-sdk 12.19.0: subscribing both listeners in the same tick yields sync: {auth: 0, idToken: 0} → microtask: {auth: 1, idToken: 1} → no further fires. Both listeners share the microtask-deferred initial-fire timing)setPersistence(auth, persistence)
setPersistence(auth, persistence)Accepts inMemoryPersistence / browserSessionPersistence / browserLocalPersistence markers without throwing
setPersistence(auth, persistence)Returns Promise<void>
setPersistence(auth, persistence)Actually changes where the auth state is persisted
setPersistence(auth, persistence)An unrecognized persistence marker is rejected with auth/argument-error rather than silently coerced to LOCAL
unit:sandbox-cluster-b9-b12.test.ts (locks AUTH-B12)signInWithPopup(auth, provider) / signInWithCredential(auth, credential)
signInWithPopup(auth, provider) / signInWithCredential(auth, credential)Returns the pre-staged UserCredential registered via sandbox.mockSignInResult(auth, …)
/ signInWithCredential(auth, credential)signInWithPopup(auth, provider) / signInWithCredential(auth, credential)Throws auth/no-mock-configured when no mock is pre-staged
/ signInWithCredential(auth, credential)signInWithPopup(auth, provider) / signInWithCredential(auth, credential)Mock is consumed after one read (subsequent call without a fresh stage throws again)
/ signInWithCredential(auth, credential)signInWithPopup(auth, provider) / signInWithCredential(auth, credential)After successful sign-in, currentUser becomes the mock's user, listeners fire
/ signInWithCredential(auth, credential)signInWithPopup(auth, provider) / signInWithCredential(auth, credential)The credential's rich User (email / displayName / isAnonymous) survives the transition — popup/redirect/credential/setUser do NOT clobber it down to the bare AuthState; cred.user === auth.currentUser (reference identity, matches upstream _updateCurrentUser(userCredential.user))
/ signInWithCredential(auth, credential)unit:sandbox-user-identity.test.ts (locks AUTH-B1)signInWithPopup(auth, provider) / signInWithCredential(auth, credential)Opens a popup window in prod
/ signInWithCredential(auth, credential)signInWithPopup(auth, provider) / signInWithCredential(auth, credential)Cancels with auth/popup-closed-by-user when the user dismisses the popup (prod)
/ signInWithCredential(auth, credential)signInWithPopup(auth, provider) / signInWithCredential(auth, credential)Provider-flow sign-ins (popup / redirect / credential) record the flow's providerId on the identity in the user DB (upsert for unknown uids; append-if-missing for known ones) and reject disabled accounts with auth/user-disabled before any state change
/ signInWithCredential(auth, credential)unit:sandbox-user-admin.test.ts ("provider tracking", "disabled users") — provider recording is sandbox bookkeeping for listIdentities/listUsers; prod's auto-link semantics are narrower (same-email Google auto-link only) and not modeledsignInWithRedirect / getRedirectResult / resolver seam
signInWithRedirect / getRedirectResult` / resolver seamsignInWithRedirect(auth, provider, resolver?) resolves the flow (per-call resolver → injected → one-shot mock → auth/argument-error), signs the user in, and stashes the credential for one getRedirectResult
/ getRedirectResult` / resolver seamsignInWithRedirect / getRedirectResult` / resolver seamgetRedirectResult(auth) returns the stashed credential once, then null (one-shot, matches prod)
/ getRedirectResult` / resolver seamsignInWithRedirect / getRedirectResult` / resolver seamsandbox.setAuthFlowResolver(auth, resolver | null) installs / clears the popup/redirect resolver (the analog of browser getAuth wiring browserPopupRedirectResolver)
/ getRedirectResult` / resolver seamsignInWithRedirect / getRedirectResult` / resolver seamsandbox.listIdentities(auth) snapshots every seeded/created identity for a host account-picker (sandbox-only — no firebase/auth equivalent)
/ getRedirectResult` / resolver seamAuth surface + error shape
Auth` surface + error shapeauth.signOut() method form works alongside the free signOut(auth) function (firebase/auth's Auth exposes both) (AUTH-GAP)
Auth` surface + error shapeSandbox auth errors are real FirebaseError instances (err instanceof FirebaseError) carrying the prod message wrapper Firebase: <message> (<auth/...>). — e.g. Firebase: Error (auth/invalid-email)., matching the oracle (AUTH-GAP)
Provider classes (GoogleAuthProvider, EmailAuthProvider, etc.)
Exports the same constructor signatures as firebase/auth for each provider
unit:types.test.tsProvider.credential(...) static factories produce AuthCredential-shaped objects
GoogleAuthProvider.providerId === 'google.com' (and per-provider analogs)
Custom scopes / params / language code
User methods
User` methodsgetIdToken() returns a three-segment base64url JWT (header alg RS256, typ JWT, a kid) whose payload decodes to getIdTokenResult().claims
oracle:auth-id-token-standard-claims decodes name and the standard claims from the token's payload, and _parseToken in @firebase/auth 1.13.6 splits the token on . and refuses one with fewer than three sections. Pyric: unit:sandbox-anonymous.test.ts decodes the minted token to its claims; unit:auth.test.ts (pyric-admin) sends the token of a user named Builder One or 李 as a Bearer header and verifies it; unit:auth-standard-claims.test.ts decodes the same claims on the in-page and worker planes. The third segment is a sandbox tag, not an RSA signature (#1836)User` methodsuser.getIdToken(true) (forceRefresh) returns a NEW token; subsequent getIdToken(false) returns the cached new token
unit:sandbox-token-refresh.test.ts — was ⚠ (documented divergence); aligned to prod in commit — sandbox now mints a fresh token on forceRefresh and fires onIdTokenChanged. Oracle: packages/conformance/observations/auth/auth-getidtoken-force-refresh.json defines the target shape (forceRefreshReturnedDifferentString: true, token1EqualsToken2: true against digame-mas — the refreshed token is cached, so a subsequent non-forced read returns it, not yet another fresh one). Sandbox tokens are JWTs, as production's are (row 54); the header's pyric_mint numbers each mint, so two refreshes in the same second still return two strings.User` methodsgetIdToken() after expiry returns a fresh token: a minted token lasts one hour (exp - iat is 3600), a non-forced read once the clock passes exp minus 30 seconds mints a new token, fires onIdTokenChanged but not onAuthStateChanged, and rules read the new token, on the in-page and worker planes
StsTokenManager.isExpired in @firebase/auth 1.13.6 (Date.now() > expirationTime - 30000, TOKEN_REFRESH_BUFFER_MS), and exp - iat of 3600 in oracle:auth-request-auth-per-sign-in (row 68c). Pyric: unit:sandbox-token-lifetime.test.ts (in-page) and unit:auth-token-lifetime.test.ts (worker port) move the sandbox clock past the refresh point; the app scenario test/apps/id-token-bearer-header moves it 61 minutes with pyric sandbox advanceClock and verifies the page's next token with firebase-admin. A production observation of a read after expiry is still neededUser` methodsuser.getIdTokenResult() returns claims
unit:sandbox-providers.test.ts (custom-claims path)User` methodsuser.uid, user.email, user.displayName, user.isAnonymous reflect the source
playground:auth-anonymous, playground:auth-email-passwordUser` methodsuser.emailVerified — present on every sandbox-minted User (default false; sandbox has no verification flow). Prod passes the real value through (no longer stripped). The admin record (sandbox.listUsers) carries it too
unit:auth-gap-surface.test.ts (locks AUTH-GAP)User` methodsuser.photoURL / user.phoneNumber — present (prod passes through, no longer stripped). A user created under a federated provider id (one containing a dot, such as google.com) with no photo of its own is assigned a generated photoURL at creation, matching prod, where a federated sign-in always returns one; password, phone, email-link, and anonymous users stay null. An identity-supplied photo always wins, and phoneNumber defaults to null. A served host stores the generated photo as a relative path and reads it back absolute, as prod's always is: user.photoURL on the page's origin, and the ID token picture claim and admin user records on the origin the client signed in from
unit:sandbox-provider-photo.test.ts (federated mint, identity photo wins, password / anonymous / email-link stay null); unit:auth-gap-surface.test.ts (phoneNumber presence)User` methodsuser.providerId (aggregate, 'firebase') + user.providerData: UserInfo[] — sandbox synthesizes one provider entry for non-anonymous users, empty for anonymous; prod passes the real array through (no longer stripped). The admin record carries the emulator-shaped providerUserInfo
User` methodsuser.metadata.creationTime / lastSignInTime
User.metadata not exposed (AUTH-GAP); the admin record carries createdAt/lastLoginAt (ISO)User` methodsIdTokenResult.signInProvider reflects the session's provider per flow ('anonymous' / 'password' / 'google.com' / …); claims include the reserved firebase.sign_in_provider (custom claims can't shadow it)
unit:sandbox-user-admin.test.ts ("IdTokenResult.signInProvider"), oracle:auth-signinprovider-per-flowUser` methodsID token claims project the account record: email with email_verified, name, picture and phone_number each only when the account has the field, user_id, provider_id: 'anonymous' for anonymous accounts, and firebase.identities keyed by identity type (email, phone, federated provider ID; {} when none). For a custom claim of the same name, the account value wins for user_id, email, email_verified, phone_number, and provider_id on an anonymous account; the custom value wins for name, picture, and provider_id on any other account. Custom claims with a reserved name (sub, iat, firebase, and the other JWT and OIDC names) are refused with auth/reserved-claim. A new Google identity gets a verified email, as Google's ID token asserts email_verified for the account's address: the user reports emailVerified: true and the token email_verified: true, also for an address typed into the sandbox sign-in dialog. An existing password or other-provider account keeps its own flag on a Google sign-in, a staged sign-in result that creates an account keeps the caller's flag, and other federated providers keep the account's flag. Rules read the same claims on auth.token / request.auth.token in Firestore, Realtime Database and Storage: in process, through the served worker (including after reauthentication), and under the MCP agent identity
oracle:auth-id-token-standard-claims replayed per sign-in flow; unit:standard-token-claims.test.ts (rules in all three services allow a verified password user and deny an unverified one); unit:auth-standard-claims.test.ts (worker port session, RTDB and Storage, reauthentication); unit:identity-standard-claims.test.ts (MCP agent identity); unit:auth.test.ts (Admin setCustomUserClaims reserved names). aud and iss name the sandbox issuer rather than a project. A federated identity lists the uid, since the sandbox records no provider-side account ID. The Google verified email follows Google's documented email_verified claim, not a capture: no production capture of a google.com sign-in exists yet. Firebase trusts Google for account linking only on @gmail.com, where it overwrites an unverified account and removes its password; the sandbox does not overwrite, so it leaves existing accounts unverified. unit:sandbox-provider-email-verified.test.ts (picker mint, popup sign-in, Firestore rule on email_verified, password and GitHub accounts stay unverified, staged result keeps its flag), unit:auth.test.ts (worker auth.acceptIdentity, new and returning identity, password and GitHub accounts stay unverified) unit:auth-m2-parity.test.ts (served staged result keeps its flag, and never marks an existing Google-only account) and unit:staged-sign-in-results.test.ts (a non-boolean emailVerified is refused); the app scenario test/apps/google-dialog-email-verified signs in through the dialog in Chromium on the SharedWorker page and the Node host (Structured evidence: oracle-conformance.test.ts)User` methodsRules see the session's minted ID token exactly: RTDB auth.token and Firestore and Storage request.auth.token carry every decoded claim with its value, sub, aud, iss, iat, exp and auth_time included (iss is https://securetoken.google.com/ plus aud, exp - iat is 3600, auth_time stays the sign-in time across refreshes), claims the token lacks read null, and RTDB auth.provider equals firebase.sign_in_provider; per sign-in kind (anonymous, password, verified profile, custom token for a new or existing account, custom claims after a forced refresh, reload, updateProfile, password reauthentication, email link). Custom-token claims merge over the account's stored claims for that session only
oracle:auth-request-auth-per-sign-in (real sign-ins, RTDB probes deployed per decoded token) and oracle:auth-request-auth-rules-test-api (Firestore and Storage evaluating the same claim sets). In-page replay with pins: unit:request-auth-per-sign-in.test.tsUser` methodsCustom-claims changes (sandbox.updateUser / re-seed) reach an active session on the next FORCED token refresh, not immediately — claims are read live from the user DB at mint time (prod's refresh-propagation story; AUTH-B10)
unit:sandbox-user-admin.test.ts, unit:sandbox-cluster-b9-b12.test.ts (Structured evidence: auth-claims-forced-refresh-propagation)User` methodsuser.reload() / user.delete() / user.toJSON() / user.refreshToken / user.tenantId
updateProfile(user, {displayName, photoURL})updateProfile(user, {displayName, photoURL}) mutates the held user + stored record in place (null clears a field; omitted fields untouched) without an extra onAuthStateChanged fire. Profile survives signOut → signInWithEmailAndPassword.
unit:sandbox-update-profile.test.ts (in-place mutation, listUsers persist, null clear, no extra listener); re-sign-in persistence: unit:upstream-auth-probes.test.tsbeforeAuthStateChanged(auth, callback, onAbort?)
beforeAuthStateChanged(auth, callback, onAbort?)Registers a BLOCKING gate that runs before a real sign-in/sign-out transition commits. Callbacks run in registration order; a callback that throws (or returns a rejected promise) aborts the transition entirely: the pending signInWith…/signOut call rejects with auth/login-blocked, currentUser is unchanged, and onAuthStateChanged/onIdTokenChanged do NOT fire. Covers every sign-in path that exists in pyric/auth: signInAnonymously, signInWithEmailAndPassword, createUserWithEmailAndPassword, signInWithPopup, signInWithRedirect, signInWithCredential, signInWithCustomToken, and signOut. Modeled after the real @firebase/auth AuthMiddlewareQueue.runMiddleware (auth_impl.ts), read directly from the installed SDK source, not just its .d.ts.
unit:sandbox-before-auth-state-changed.test.ts — implementation cross-checked against @firebase/auth's AuthMiddlewareQueue source (registration-order queue, per-callback try/await, auth/login-blocked wrap). Custom-token allow/block: unit:upstream-auth-probes.test.ts. No live-oracle capture (no observable client-visible signal to probe beyond the documented+sourced contract already read).beforeAuthStateChanged(auth, callback, onAbort?)onAbort semantics: when a callback throws, every onAbort registered by a callback that ALREADY SUCCEEDED in the same pass runs, in REVERSE registration order — matches upstream's rollback-stack (runMiddleware's onAbortStack). An onAbort that itself throws is swallowed so it can't mask the original block reason or skip the remaining rollbacks.
unit:sandbox-before-auth-state-changed.test.ts ("onAbort runs (in reverse order)…", "a callback whose own onAbort throws…")beforeAuthStateChanged(auth, callback, onAbort?)Fires on BOTH directions: a real sign-in (nextUser non-null) and a real sign-out (nextUser === null) — a throwing callback blocks signOut too, leaving the previous user signed in. Matches upstream, where the same middleware queue gates _updateCurrentUser and signOut.
unit:sandbox-before-auth-state-changed.test.ts ("fires on sign-out too…")beforeAuthStateChanged(auth, callback, onAbort?)sandbox.setUser (the sandbox-only test driver) BYPASSES the gate entirely — it is a raw identity force with no prod analog (same bypass it already has for provider enforcement / signInProvider tracking), so no registered beforeAuthStateChanged callback runs and none can block it.
unit:sandbox-before-auth-state-changed.test.ts ("sandbox.setUser test driver bypasses the gate")beforeAuthStateChanged(auth, callback, onAbort?)Served-worker path (SharedWorker-backed auth in @pyric/cli): the worker owns the shared user pool and commits transitions on its own side of the port, so a page-local beforeAuthStateChanged registration can't actually gate a worker-driven sign-in. Rather than silently accept a callback that could never run, registering THROWS immediately (auth/operation-not-supported-in-this-environment) — same defensive pattern as signInWithCredential over the worker.
packages/cli/src/serve/worker/client.ts (beforeAuthStateChanged throws makeUnsupported)User-management and session exports
initializeAuth(app, deps?)Aliases getAuth(app) and returns the same stable Auth handle — an app that calls initializeAuth instead of getAuth gets an equivalent, working instance. The optional Dependencies arg (persistence / popupRedirectResolver) is accepted for signature parity but not applied (persistence is already a documented sandbox no-op). Repeated calls return the cached handle rather than throwing auth/already-initialized
deleteUser(user)Deletes the account from the user store AND signs the user out if they are current (fires onAuthStateChanged(null)), matching prod where deleting the signed-in user clears auth.currentUser. Real behavior: a subsequent signInWithEmailAndPassword for that identity throws auth/user-not-found; reload(user) after delete rejects with auth/user-token-expired. A non-anonymous session older than five minutes is refused with auth/requires-recent-login (oracle capture auth-requires-recent-login)
unit:fruit-aliases.test.ts — user removed from the store, sign-out fired, re-sign-in throws auth/user-not-found; post-delete reload → auth/user-token-expired: unit:upstream-auth-probes.test.tsupdateEmail(user, newEmail)Changes the stored email (via the same path as sandbox.updateUser, rejecting auth/email-already-in-use / auth/invalid-email) and mutates the held user in place, so the next sign-in resolves against the new email. A session older than five minutes is refused with auth/requires-recent-login. Leniency vs prod: the sandbox is not routed through verifyBeforeUpdateEmail; with email-enumeration protection on, production refuses updateEmail with auth/operation-not-allowed (Please verify the new email before changing email.)
unit:fruit-aliases.test.ts: stored email changes; re-sign-in works with the new email, fails with the old. Recent-login gate: unit:requires-recent-login.test.ts. Oracle capture auth-requires-recent-login recorded auth/operation-not-allowed for updateEmail on the oracle project, which has email-enumeration protection on.updatePassword(user, newPassword)Sets the stored password (validated for strength). The sandbox DOES store and verify passwords, so this is a real mutation: a subsequent signInWithEmailAndPassword with the new password succeeds and the old one throws auth/wrong-password. A session older than five minutes is refused with auth/requires-recent-login until it signs in again or re-authenticates. The change revokes the account's other sessions, whose next refresh rejects auth/user-token-expired and signs out (other browsers and other worker ports included), while the session that changed it keeps refreshing, after a page reload too; an admin password change (sandbox.updateUser, pyric auth updateUser --password) revokes every session (#1950)
unit:fruit-aliases.test.ts: new password signs in, old password throws auth/wrong-password. Revocation: unit:sandbox-user-admin.test.ts ("an admin password change refuses the held session refresh and signs out", "the session that changes its own password keeps refreshing"). Recent-login gate: oracle capture auth-requires-recent-login (refused at 330 seconds, allowed right after sign-in and after reauthentication), replayed in unit:oracle-conformance.test.ts (Structured evidence: requires-recent-login.test.ts)reload(user)Re-reads the stored record into the user object in place, so a change made out of band (e.g. sandbox.updateUser) is reflected on the held reference — matching prod's server refresh. If the identity is absent from the store (including after deleteUser), rejects with auth/user-token-expired; a disabled account rejects with auth/user-disabled. Either rejection signs the user out, on the in-page and worker planes (#1950)
unit:fruit-aliases.test.ts — an out-of-band sandbox.updateUser displayName change is visible on the held user after reload; missing-store / post-delete: unit:upstream-auth-probes.test.ts; disabled and deleted with sign-out: unit:sandbox-user-admin.test.ts and, on the worker port, unit:auth.test.ts (#1950). What production's accounts:lookup answers for a disabled account with an unexpired token is not capturedupdateCurrentUser(auth, user)Sets the sandbox's current user (pass null to sign out), firing onAuthStateChanged — auth.currentUser reflects the passed user afterward
useDeviceLanguage(auth)Accepted no-op — the sandbox has no device locale to read, so there is no language to set; accepted so init code that calls it compiles + runs
unit:fruit-aliases.test.ts — resolves/returns without errorActionCodeURL / email-link / action-code — the out-of-band family
ActionCodeURL.parseLink(link) / parseActionCodeURL(link)Parses an out-of-band action link. The mode query param maps to a NORMALIZED operation (mode=resetPassword -> PASSWORD_RESET, mode=signIn -> EMAIL_SIGNIN), oobCode surfaces as code, lang as languageCode, and continueUrl comes out URL-DECODED. A link missing mode, missing oobCode, carrying an unknown mode, or that is not a URL at all parses to null — the parse NEVER throws. parseActionCodeURL and ActionCodeURL.parseLink agree.
auth-actioncodeurl-parse against firebase-js-sdk 12.19.0. Replayed in unit:oracle-conformance.test.ts. (Structured evidence: sandbox-email-link.test.ts)isSignInWithEmailLink(auth, link)Pure predicate over the link string — no network. true only for a link whose mode is signIn AND which carries an oobCode; false for a password-reset link, for mode=signIn with no code, for garbage, and for the empty string. Never throws.
auth-issigninwithemaillink-predicate captured all five cases against prod. Replayed in unit:oracle-conformance.test.ts. (Structured evidence: sandbox-email-link.test.ts)applyActionCode(auth, code)Redeems an out-of-band code and performs its state change (VERIFY_EMAIL sets emailVerified, VERIFY_AND_CHANGE_EMAIL moves the account to the new address). Throws auth/invalid-action-code for a code the project never issued, for the empty string, and for a code already redeemed (single-use). A PASSWORD_RESET code is refused — confirmPasswordReset owns that one.
auth-action-code-invalid, in the #1676 re-capture (firebase 12.19.0, digame-mas, Email/Password and Email Enumeration Protection on), confirmed prod emits auth/invalid-action-code for both a bogus code and the empty string. The APPLY path (a real code, redeemed) cannot be probed from a client — it needs a code from a real inbox — and is unit-backed end to end against the sandbox outbox in unit:sandbox-email-link.test.ts. (Structured evidence: oracle-conformance.test.ts)sendSignInLinkToEmail(auth, email, settings)ActionCodeSettings validation, enforced CLIENT-side before any request leaves the process: a missing or unparseable url throws auth/invalid-continue-uri (NOT auth/missing-continue-uri, despite the constant's name), and handleCodeInApp other than true throws auth/argument-error. On success the sandbox mints a single-use code and posts the message to the outbox.
auth-sendsigninlinktoemail-settings-validation captured missingUrl: auth/invalid-continue-uri and handleCodeInAppFalse: auth/argument-error, unchanged in the #1676 re-capture (firebase 12.19.0, digame-mas, Email/Password and Email Enumeration Protection on). The same capture recorded the server arms: invalidUrl: auth/invalid-continue-uri and unauthorizedDomain: auth/unauthorized-continue-uri (auth#163). Replayed in unit:oracle-conformance.test.ts; the send path is unit-backed in unit:sandbox-email-link.test.ts.signInWithEmailLink(auth, email, link)Redeems the code in a sign-in link. A link carrying no oobCode throws auth/argument-error CLIENT-side (the SDK never reaches the server to ask about a code it cannot find in the link). A first-time sign-in for an address CREATES the account, getAdditionalUserInfo(cred).isNewUser is true, and the account arrives emailVerified: true — redeeming a code mailed to that address is proof of control. The code is single-use.
auth-signinwithemaillink-invalid-link: noOobCode: auth/argument-error). The server arm for a code the project never issued answered auth/invalid-action-code in the #1676 re-capture (firebase 12.19.0, digame-mas, Email/Password and Email Enumeration Protection on), and is replayed in unit:oracle-conformance.test.ts. Redeeming a real code needs a real inbox; that half is unit-backed end to end against the sandbox outbox (unit:sandbox-email-link.test.ts drives send -> read the outbox -> sign in).sendPasswordResetEmail(auth, email)For an address NO account owns, prod RESOLVES silently — it does not throw auth/user-not-found. Email Enumeration Protection is on by default and refusing to leak account existence is the point. The sandbox matches: it resolves and mails nothing. A malformed address still throws auth/invalid-email. For a real account, the sandbox mails a reset code; confirmPasswordReset redeems it and the new password signs in while the old one throws auth/wrong-password.
auth-sendpasswordresetemail-unknown-user captured resolvedForUnknownUser: true, unknownUserCode: null, malformedEmailCode: auth/invalid-email. A shim that threw auth/user-not-found here would hand agent code an account oracle production deliberately removed. Reset round trip unit-backed in unit:sandbox-email-link.test.ts. (Structured evidence: oracle-conformance.test.ts)sendEmailVerification(user)Throws auth/missing-email for a user with no email on the account (an anonymous user). For a real account the mail goes out and NOTHING ELSE HAPPENS: user.emailVerified stays false. Verification happens when the code in the message is redeemed (applyActionCode), not when it is sent.
auth-sendemailverification-shape captured anonymousUserCode: auth/missing-email against prod. The send-does-not-verify property is the one the whole flow turns on and is unit-backed (unit:sandbox-email-link.test.ts asserts emailVerified is still false after the send and true only after the code is applied) — it cannot be oracle-confirmed end to end because confirming it would require reading a real inbox. (Structured evidence: oracle-conformance.test.ts)verifyBeforeUpdateEmail(user, newEmail)Mails a code to the NEW address and returns. The account's email does NOT change until that code is redeemed. A malformed new address is refused with auth/invalid-new-email. On redemption the account moves and the new address arrives emailVerified: true. checkActionCode on the code reports data.email = the new address and data.previousEmail = the old one. A session older than five minutes is refused with auth/requires-recent-login (oracle capture auth-requires-recent-login).
auth-verifybeforeupdateemail-shape: the email stays unchanged until redeemed. Redemption needs a real inbox and is unit-backed. Divergence (#1693): a malformed new address gives auth/invalid-new-email, the sandbox auth/invalid-email. The replay pins both. (Structured evidence: sandbox-email-link.test.ts, oracle-conformance.test.ts)sandbox.takeAuthMail(auth) / sandbox.setAuthMailResolver(auth, resolver)The sandbox IS the mail server. Every send posts a real message (operation, recipient, single-use code, and the full action link) to an outbox; sandbox.takeAuthMail reads it — the program's substitute for a human opening an inbox. The mailed link round-trips through the public isSignInWithEmailLink / parseActionCodeURL unchanged, and its code is the code the redeemer accepts, so the round trip production cannot complete without a human closes in-process. An installed AuthMailResolver is additionally notified per message; a resolver that THROWS does not fail the send that produced it.
unit:sandbox-email-link.test.ts — sandbox-only driver (no firebase/auth counterpart; this is the seam that makes the family testable at all).checkActionCode(auth, code) / verifyPasswordResetCode(auth, code) / confirmPasswordReset(auth, code, newPassword)checkActionCode and verifyPasswordResetCode INSPECT a code without burning it — a check must not destroy the code the subsequent apply needs. confirmPasswordReset redeems it and sets the password, running the same strength check createUserWithEmailAndPassword runs; a weak new password throws auth/weak-password and does NOT burn the code (a typo must not destroy the user's one reset link). A code staged as expired throws auth/expired-action-code.
auth-action-code-invalid, in the #1676 re-capture (firebase 12.19.0, digame-mas, Email/Password and Email Enumeration Protection on), captured auth/invalid-action-code from checkActionCode, verifyPasswordResetCode and confirmPasswordReset for a code the project never issued. Replayed in unit:oracle-conformance.test.ts. The earlier capture answered auth/operation-not-allowed because that project had the password provider disabled. The inspect-without-burning, weak-password and expired-code behavior needs a real issued code and is unit-backed in unit:sandbox-email-link.test.ts.sendSignInLinkToEmailauth/unauthorized-continue-uri (domain allowlist) · Prod rejects a continue URL whose domain is not on the project's authorized-domains list. The sandbox has NO domain allowlist and does not invent one: it accepts any parseable continue URL. A continue URL that would be rejected in production is accepted here.
auth-sendsigninlinktoemail-settings-validation, in the #1676 re-capture (firebase 12.19.0, digame-mas, Email/Password and Email Enumeration Protection on), captured unauthorizedDomain: auth/unauthorized-continue-uri for a continue domain off the allowlist. (Structured evidence: sandbox-email-link.test.ts)linkWithCredential / linkWithPopup / linkWithRedirect / unlink — account linking
linkWithCredential(user, credential)The ANONYMOUS UPGRADE. Linking an email credential onto an anonymous account upgrades it IN PLACE: the uid is PRESERVED, isAnonymous flips to false, the email is set, and providerData gains the provider. Returns a UserCredential with operationType: 'link' and providerId: null, and getAdditionalUserInfo() reports isNewUser: true and providerId: 'password' for this upgrade. The linked credential then works as a first-class signInWithEmailAndPassword.
auth-link-email-credential-to-anonymous. Divergence (#1698): the sandbox reports isNewUser: false and providerId: null for the link's additional user info. The replay pins both. (Structured evidence: oracle-conformance.test.ts, sandbox-linking-reauth.test.ts)linkWithCredentialconflict codes · auth/provider-already-linked when the account already carries the provider (one identity per provider). auth/email-already-in-use when the email credential belongs to a DIFFERENT account — an address can back only one identity, so the link cannot be granted without stealing it.
auth-link-conflicts, in the #1676 re-capture (firebase 12.19.0, digame-mas, Email/Password and Email Enumeration Protection on), captured auth/provider-already-linked for a second email credential on an account that already has one, and auth/email-already-in-use for an email credential another account owns. Replayed in unit:oracle-conformance.test.ts and proven in unit:sandbox-linking-reauth.test.ts. credential-already-in-use remains the OAuth-credential case.unlink(user, providerId)Detaches a provider and returns the updated user with a SHRUNKEN providerData. Unlinking a provider that was never linked throws auth/no-such-provider. Unlinking 'password' takes the password with it, so signInWithEmailAndPassword for that account stops working. Unlinking the LAST provider does NOT re-anonymize the account — isAnonymous describes how an identity was born, not what it currently carries.
auth-unlink-provider captured noSuchProviderCode: auth/no-such-provider against prod on an anonymous user. Replayed in unit:oracle-conformance.test.ts. The detach path is unit-backed (unit:sandbox-linking-reauth.test.ts).linkWithPopup(user, provider, resolver?) / linkWithRedirect(...)Route through the SAME AuthFlowResolver seam as signInWithPopup, with authType: 'link' on the request so a host UI can present 'link your Google account' rather than 'sign in'. The resolved credential names the provider to attach; the sandbox performs the attach and the uid is preserved. A disabled provider throws auth/operation-not-allowed AHEAD of the resolver check — a code deliberately distinct from auth/argument-error, which keeps meaning 'enabled, but no resolver/mock wired'.
unit:sandbox-linking-reauth.test.ts — asserts the resolver sees authType: 'link', the uid is preserved, and the two error codes stay distinct. The OAuth arm cannot be oracle-probed at all (it needs a real IdP popup and a human), which is precisely why it goes through the resolver seam.reauthenticateWithCredential / reauthenticateWithPopup / reauthenticateWithRedirect — re-authentication
reauthenticateWithCredential(user, credential)A wrong password throws auth/wrong-password, where production with Email Enumeration Protection on answers auth/invalid-credential (#1819). A credential for a DIFFERENT account throws auth/user-mismatch, checked before the password. On success a fresh ID token is minted, and the UserCredential carries operationType: 'reauthenticate'.
auth-reauthenticate-with-credential: the sandbox matches all but the wrong-password code. The oracle suite pins both sides. Pending fix, #1819. (Structured evidence: oracle-conformance.test.ts)reauthenticate* and the auth/requires-recent-login gateupdatePassword, updateEmail, verifyBeforeUpdateEmail and deleteUser refuse a non-anonymous session whose last authentication is more than five minutes old with auth/requires-recent-login (message Firebase: Error (auth/requires-recent-login).). The age is measured on the sandbox clock, so advancing the clock reaches the gate. A sign-in or a successful re-authentication restarts the window; a forced token refresh, a reload and a served-session restore do not, and a refreshed token keeps its auth_time. Not gated: updateProfile, getIdToken(true), unlink, and linkWithCredential and deleteUser on an anonymous account. Enforced in the in-page sandbox and in the served worker's port sessions.
auth/requires-recent-login gateauth-requires-recent-login: deleteUser allowed at ages 280 and 295 seconds and refused at 305 and 320; at 330 seconds updatePassword, verifyBeforeUpdateEmail and deleteUser refused, updateProfile, forced refresh, unlink, anonymous link and anonymous delete allowed; a refresh at 120 seconds left the gate in place at 330; reauthenticateWithCredential cleared it. Replayed against the sandbox in unit:oracle-conformance.test.ts; served-worker parity in unit:auth-requires-recent-login.test.ts. (Structured evidence: auth-requires-recent-login.test.ts)reauthenticateWithPopup(user, provider, resolver?) / reauthenticateWithRedirect(...)Route through the shared resolver seam with authType: 'reauth'. The identity the resolver produces MUST be the user being re-authenticated — a resolver that hands back a different uid throws auth/user-mismatch. That check is the entire security content of the flow; without it 're-authentication' would accept anyone.
unit:sandbox-linking-reauth.test.ts — asserts the resolver sees authType: 'reauth' and that an impostor identity is rejected with auth/user-mismatch.Constants, credentials, and inert config tokens
getAdditionalUserInfo(userCredential)Returns { isNewUser, profile, providerId }. For a fresh anonymous sign-in prod reports { isNewUser: true, providerId: null, profile: {} }. For createUserWithEmailAndPassword and a returning signInWithEmailAndPassword, getAdditionalUserInfo().providerId is 'password' (while UserCredential.providerId stays null, AUTH-B2). isNewUser is true for createUserWithEmailAndPassword, a first-time email-link sign-in, a custom-token sign-in that minted the account, and linking an email credential onto an anonymous user (auth#160); false for a returning signInWithEmailAndPassword and for reauthenticate.
auth-additional-user-info-shape. Divergence (#1699): the sandbox reports providerId: null for the email create and sign-in arms. The replay pins both. Other arms are unit-backed. (Structured evidence: oracle-conformance.test.ts, sandbox-email-link.test.ts, sandbox-linking-reauth.test.ts, upstream-auth-probes.test.ts)ProviderId / SignInMethod / OperationType / ActionCodeOperation / AuthErrorCodesThe constant maps, value for value. OperationType.SIGN_IN === 'signIn', SignInMethod.EMAIL_LINK === 'emailLink', ProviderId.GOOGLE === 'google.com', ActionCodeOperation.PASSWORD_RESET === 'PASSWORD_RESET', and the 106-entry AuthErrorCodes map (INVALID_OOB_CODE === 'auth/invalid-action-code', PROVIDER_ALREADY_LINKED === 'auth/provider-already-linked', NO_SUCH_PROVIDER === 'auth/no-such-provider', USER_MISMATCH === 'auth/user-mismatch', …).
auth-mechanical-surface-constants against firebase-js-sdk 12.19.0, replayed value-for-value in unit:oracle-conformance.test.ts. This matters more than it looks: consumer code COMPARES against these constants, so a mirror that got a string wrong would turn every such comparison into a silent false — a worse failure than the export simply being absent, because it typechecks and runs. NOTE: the capture's persistenceTypes block is deliberately NOT asserted — the harness runs under Node, where firebase/auth stubs the browser-only persistence tokens to type: 'NONE' (it reports 'NONE' even for browserLocalPersistence, which is unambiguously 'LOCAL'); asserting it would be asserting a harness artifact. See auth#178.signInWithCustomToken(auth, customToken)Throws auth/invalid-custom-token for a malformed token and for the empty string. createCustomToken in pyric-admin and the CLI mints a custom token in firebase-admin's shape (an RS256 JWT for the identity toolkit audience with uid and claims), signed with a sandbox key for the minting app's project, and this exchanges it (#1952): an edited signature or an exp on or before the sandbox clock's now throws auth/invalid-custom-token, and a token for another project throws auth/custom-token-mismatch. Every unsigned token throws auth/invalid-custom-token, as production answers a token it cannot verify (#2009): a JSON (optionally base64url) {uid, claims} payload, a three-part JWT for any other audience or none, and a custom-token-audience JWT the sandbox did not sign. The identity is created if it does not exist, and the credential carries providerId: null (custom-token sign-in is not a federated provider).
auth-signinwithcustomtoken-invalid captured auth/invalid-custom-token for both a malformed token and the empty string, replayed in unit:oracle-conformance.test.ts. The mismatch and expiry codes follow @firebase/auth's server error map (CREDENTIAL_MISMATCH to custom-token-mismatch, INVALID_CUSTOM_TOKEN to invalid-custom-token), not a capture. Diverged on the accept path, declared rather than hidden: prod verifies an RS256 signature against the project's service-account key, and the sandbox has none, so a token signed with a real key is refused. The mint, exchange and verify round trip runs in packages/pyric-admin/src/auth/custom-token-exchange.test.ts and the id-token-bearer-header app scenario, and each unsigned shape is refused in packages/pyric/test/auth/unsigned-custom-token.test.ts, packages/cli/test/serve/worker/unsigned-custom-token.test.ts and that scenario.validatePassword(auth, password)Returns a PasswordValidationStatus against the project's password policy, WITHOUT attempting a sign-up (so a UI can show live strength feedback). The sandbox's policy is minPasswordLength: 6, maxPasswordLength: 4096, enforcementState: 'ENFORCE', with every character-class requirement UNSET — so a password this function calls valid is exactly one createUserWithEmailAndPassword will accept. The character-class fields are undefined, not false: upstream distinguishes 'not required' from 'required and unmet', and reporting false would claim the password failed a rule the project never had.
auth-validatepassword-status-shape captured prod's live policy (minPasswordLength 6, maxPasswordLength 4096, ENFORCE, character classes unset) and the status shape for a weak and a strong password. Replayed in unit:oracle-conformance.test.ts. The 6-char minimum agrees with the separately oracle-pinned auth/weak-password threshold on the create path, so the two surfaces draw the same line here exactly as they do in prod.fetchSignInMethodsForEmail(auth, email)Not implemented; disposition auth.email-enumeration owns the reviewed availability and rationale.
auth-fetchsigninmethodsforemail-deprecated capture, in the #1676 re-capture (firebase 12.19.0, digame-mas, Email Enumeration Protection on), returned an empty list both for an account that has a password method and for an unknown address, so the method cannot tell them apart.inMemoryPersistence / browserSessionPersistence / browserLocalPersistence / indexedDBLocalPersistence / browserCookiePersistence / browserPopupRedirectResolver / debugErrorMap / prodErrorMapInert configuration tokens, accepted so the idiomatic initializeAuth(app, { persistence: indexedDBLocalPersistence }) and setPersistence(auth, browserCookiePersistence) compile, run, and behave identically. The .type discriminant matches upstream exactly (NONE / SESSION / LOCAL / LOCAL / COOKIE) because consumer code branches on it. browserPopupRedirectResolver is accepted and ignored — the sandbox has its own first-class pluggable equivalent (sandbox.setAuthFlowResolver). prodErrorMap is accepted and DELIBERATELY not honored: installing it upstream strips error messages, and doing that in a sandbox whose purpose is to tell a developer what went wrong would be actively hostile.
pyric/firestore uses for its cache-factory tokens. unit:types.test.ts + unit:sandbox-email-link.test.ts cover the exports. Oracle caveat recorded on auth#172: the persistenceTypes block of auth-mechanical-surface-constants reports NONE for every token including browserLocalPersistence — a Node-build stub artifact, not the browser contract, so the .type values here follow the documented Persistence.type union instead.revokeAccessToken(auth, token)Accepted no-op. In production this reaches OUTSIDE Firebase entirely — it tells the identity provider (in practice Apple) to revoke an OAuth access token, which is a call landing on Apple's servers. There is no external IdP behind a sandbox sign-in, so there is no token out there to revoke and nothing this call could truthfully do. It resolves (so the account-deletion flow Apple requires an app to ship runs end to end against the sandbox) and changes no sandbox state (because claiming otherwise would be a lie).
unit:types.test.ts — the export resolves. Deliberately not oracle-probed: a successful probe would revoke a real token at a real IdP, which is a side effect on someone else's system that a conformance run has no business causing.AuthCredential / EmailAuthCredential / OAuthCredentialReal classes, not markers. EmailAuthProvider.credential(email, password) returns an EmailAuthCredential that CARRIES THE SECRET — which is what makes linkWithCredential, reauthenticateWithCredential, and signInWithCredential decidable in the sandbox with no resolver and no mock (the backend already stores and verifies passwords). credentialWithLink carries the link instead, and signInMethod discriminates ('password' vs 'emailLink'). The backing secret is non-enumerable, so a spread or Object.keys walk does not pick it up; toJSON() DOES carry it, matching upstream (whose fromJSON needs it to round-trip). OAuthCredential carries the IdP tokens, which the sandbox cannot verify — those flows keep going through the resolver seam.
unit:sandbox-linking-reauth.test.ts — pins the secret-carrying behavior, the enumerable/toJSON split (so nobody 'hardens' it into a divergence later), and that a real email credential now signs in via signInWithCredential instead of throwing the sandbox-only auth/no-mock-configured it used to.TwitterAuthProvider / SAMLAuthProviderProvider marker classes. TwitterAuthProvider.credential(token, secret) takes a token AND a secret — Twitter is the one OAuth 1.0a provider in the set, where the OAuth 2.0 providers take a single access token. SAMLAuthProvider's constructor ENFORCES the saml. providerId prefix (throwing auth/argument-error otherwise), because that id is what routes an assertion to the right configured IdP and a typo there would silently target nothing. SAML has no client-constructible credential, so the class has no credential() factory.
unit:types.test.ts — construction, PROVIDER_ID values, and the SAML prefix guard.User.providerDataOne entry PER LINKED PROVIDER, read from the identity's stored record. Previously the sandbox synthesized a single {providerId: 'password'} entry for EVERY non-anonymous user, so a Google popup sign-in reported its provider as 'password' and a linked account could never show more than one. Consumer code branches on this array (that is what it is for — 'is this account linked to Google?'), so the synthesized version was actively misleading. Empty for anonymous users; after unlink of the last provider it is genuinely empty (it does not resurrect the removed provider).
unit:sandbox-linking-reauth.test.ts now pins that a Google link surfaces google.com in providerData, that unlink shrinks it, and that unlinking the last provider leaves it empty rather than falling back to a synthesized 'password' entry.Calls in flight when the hosted connection drops
The web hosted client talks to the Node host over one WebSocket. When that socket drops, a call the socket had already taken is in flight: the host may or may not have run it (ADR-0019 decision 7). Each row here states what becomes of such a call, against what the production Web SDK does when its own connection drops.
Operations in flight at a hosted connection drop (web hosted client)An Auth operation (a sign-in, a profile update, a token refresh) the web hosted client's socket had taken when it dropped fails once with unavailable and the message "The hosted sandbox connection was lost. Requests already sent may have completed; check state before retrying." It is not sent again. In production the Auth Web SDK fails a request whose network call fails with auth/network-request-failed and does not retry it.
@firebase/auth 1.13.1 dist/esm: a failed fetch is reported through _fail(auth, "network-request-failed"), and the request is not retried. packages/cli/test/serve/worker/hosted-reconnect-hold.test.ts drops a real loopback socket with auth.signInEmail in flight and asserts it fails once with that message and reaches the host once.unavailable where production fails with auth/network-request-failedClient SDKs in a registered server process
A server process started with node --import @pyric/cli/register and PYRIC_SANDBOX=remote, remote:<url>, 1 or true runs the client SDKs against the Node host (#1082): firebase/app, firebase/database, firebase/firestore, firebase/auth and firebase/storage resolve to @pyric/cli’s Node client, which reaches the host over its own hosted connection with the process’s own signed-in session, so the host’s rules apply as they do for any other client. Off the Node host every call fails instead of running against a private in-process sandbox, and the client services with no path to the host refuse. PYRIC_SANDBOX=local keeps the in-process sandbox. In production the client SDKs run in Node and reach the project.
getAuth(app) in a registered server processUnder a remote register activation on the Node host, firebase/auth in a server process signs in to the host: the session belongs to that process, the user is visible to firebase-admin, and its identity applies to the process's RTDB, Firestore and Storage calls. The session lasts as long as the process. When the host is not the Node host, every call fails with failed-precondition and a message naming the Node host (pyric sandbox --hosted or pyric({ hosted: true })); when no host is found, with the discovery error pyric-admin gets. No call falls back to an in-process sandbox.
test/apps/client-sdk-under-register runs the client SDKs under node --import @pyric/cli/register against a hosted Vite dev server, reads back with firebase-admin and a page, and asserts a user the process created that firebase-admin finds, and rules that allow that user's own path and deny another's. On main (942cb175) it failed: the calls ran against a private in-process sandbox, so an upload returned a data: URL and firebase-admin read nothing they wrote. packages/cli/test/register/node-origin.test.ts runs the served surfaces under a Node origin whose host is not the Node host, or cannot be found, and asserts every call fails, useWorker stays true, the served app entry's placeholder sandbox stays empty, and a pyric/* mirror resolved from the app refuses. mapping.test.ts pins the mapping per activation value.. (Structured evidence: register-child.test.ts)Server-rendered modules under vite dev
Modules Vite loads for server rendering under vite dev with pyric() (server.ssrLoadModule, a runnable environment, a framework’s SSR entry and loaders) get the modules a registered server process gets (#1123): the client SDKs reach the dev server’s own Node host as one signed-in SSR session per dev server process, and firebase-admin reaches it as admin. This holds with Vite’s default externalization and with ssr.noExternal. A SharedWorker dev server refuses them, naming pyric({ hosted: true }), and a server environment Vite does not run in its own process (workerd) gets a module that throws when it loads. In production these modules run the Firebase SDKs in the server’s runtime and reach the project.
getAuth(app) in a server-rendered module under vite devOn a hosted dev server, firebase/auth in a server-rendered module signs in to the host. The session belongs to the dev server process: every SSR request, both of Vite's SSR loaders and a module reloaded after an edit see the same currentUser, and its identity applies to the SSR RTDB, Firestore and Storage calls. Browser sessions are separate. On a SharedWorker dev server every call fails with failed-precondition and a message naming pyric({ hosted: true }). No call reaches production or an in-process sandbox.
test/apps/vite-ssr-client-sdk signs in through ssrLoadModule, then finds the same user through the environment runner, and checks that the rules allow that user's paths and deny another's. On main (ba2c0bf0a) the scenario failed: SSR sign-in rejected with auth/network-request-failed from the network guard, and the RTDB, Firestore and Storage writes did not settle, because the imports loaded the real SDK. vite-module-swap.test.ts pins the routing per specifier, AI mode and environment (Vite 5's ssr option, a runnable environment, a non-runnable one), vite-ssr-activation.test.ts the host, the restart hand-over and the SharedWorker refusal, and vite-plugin-firestore.test.ts runs Vite with firebase installed, so it takes the externalized path. (Structured evidence: scenario.ts)initializeServerApp) is unsupportedCurrent gaps
Documented divergences
Known differences between Pyric and production Firebase. Each remains tracked as a non-conforming row.
signInAnonymously(auth)Auto-generates a uid for fresh sign-ins (sandbox format: anonymous-{N})
unit:sandbox-anonymous.test.ts — prod uids are 28-char base64-ish; sandbox uses a readable counter for debuggabilitysignInAnonymously(auth)Anonymous users persist across page reload via configured Persistence (prod only — sandbox has no persistence layer)
signInWithEmailAndPassword(auth, email, password)Production answers auth/invalid-credential for an unknown email with Email Enumeration Protection on. pyric throws auth/user-not-found
auth-user-not-found-error-code records auth/invalid-credential. The oracle suite pins both sides. Pending fix, #1819. (Structured evidence: oracle-conformance.test.ts, sandbox-email-password.test.ts)signInWithEmailAndPassword(auth, email, password)Production answers auth/invalid-credential for a wrong password with Email Enumeration Protection on. pyric throws auth/wrong-password
auth-wrong-password-error-code records auth/invalid-credential. The oracle suite pins both sides. Pending fix, #1819. (Structured evidence: oracle-conformance.test.ts, sandbox-email-password.test.ts)signInWithEmailAndPassword(auth, email, password)An EMPTY password throws auth/missing-password (message "A non-empty password must be provided"), fired before the user-DB lookup so it can't be used to enumerate seeded emails. Upstream maps the MISSING_PASSWORD server error (core/errors.ts:92,282,563). ⚠ best-known semantics — message text not yet captured against a live project (STOP-flagged for an oracle pass; the .code is the load-bearing part).
unit:sandbox-cluster-b9-b12.test.ts (locks AUTH-B11)signOut(auth)Clears the active session's persistence in prod; sandbox has no persistence
setPersistence(auth, persistence)Actually changes where the auth state is persisted
signInWithPopup(auth, provider)` / `signInWithCredential(auth, credential)Opens a popup window in prod
beforeAuthStateChanged(auth, callback, onAbort?)sandbox.setUser (the sandbox-only test driver) BYPASSES the gate entirely — it is a raw identity force with no prod analog (same bypass it already has for provider enforcement / signInProvider tracking), so no registered beforeAuthStateChanged callback runs and none can block it.
unit:sandbox-before-auth-state-changed.test.ts ("sandbox.setUser test driver bypasses the gate")beforeAuthStateChanged(auth, callback, onAbort?)Served-worker path (SharedWorker-backed auth in @pyric/cli): the worker owns the shared user pool and commits transitions on its own side of the port, so a page-local beforeAuthStateChanged registration can't actually gate a worker-driven sign-in. Rather than silently accept a callback that could never run, registering THROWS immediately (auth/operation-not-supported-in-this-environment) — same defensive pattern as signInWithCredential over the worker.
packages/cli/src/serve/worker/client.ts (beforeAuthStateChanged throws makeUnsupported)updateEmail(user, newEmail)Changes the stored email (via the same path as sandbox.updateUser, rejecting auth/email-already-in-use / auth/invalid-email) and mutates the held user in place, so the next sign-in resolves against the new email. A session older than five minutes is refused with auth/requires-recent-login. Leniency vs prod: the sandbox is not routed through verifyBeforeUpdateEmail; with email-enumeration protection on, production refuses updateEmail with auth/operation-not-allowed (Please verify the new email before changing email.)
unit:fruit-aliases.test.ts: stored email changes; re-sign-in works with the new email, fails with the old. Recent-login gate: unit:requires-recent-login.test.ts. Oracle capture auth-requires-recent-login recorded auth/operation-not-allowed for updateEmail on the oracle project, which has email-enumeration protection on.useDeviceLanguage(auth)Accepted no-op — the sandbox has no device locale to read, so there is no language to set; accepted so init code that calls it compiles + runs
unit:fruit-aliases.test.ts — resolves/returns without errorverifyBeforeUpdateEmail(user, newEmail)Mails a code to the NEW address and returns. The account's email does NOT change until that code is redeemed. A malformed new address is refused with auth/invalid-new-email. On redemption the account moves and the new address arrives emailVerified: true. checkActionCode on the code reports data.email = the new address and data.previousEmail = the old one. A session older than five minutes is refused with auth/requires-recent-login (oracle capture auth-requires-recent-login).
auth-verifybeforeupdateemail-shape: the email stays unchanged until redeemed. Redemption needs a real inbox and is unit-backed. Divergence (#1693): a malformed new address gives auth/invalid-new-email, the sandbox auth/invalid-email. The replay pins both. (Structured evidence: sandbox-email-link.test.ts, oracle-conformance.test.ts)sendSignInLinkToEmailProd rejects a continue URL whose domain is not on the project's authorized-domains list. The sandbox has NO domain allowlist and does not invent one: it accepts any parseable continue URL. A continue URL that would be rejected in production is accepted here.
auth-sendsigninlinktoemail-settings-validation, in the #1676 re-capture (firebase 12.19.0, digame-mas, Email/Password and Email Enumeration Protection on), captured unauthorizedDomain: auth/unauthorized-continue-uri for a continue domain off the allowlist. (Structured evidence: sandbox-email-link.test.ts)linkWithCredential(user, credential)The ANONYMOUS UPGRADE. Linking an email credential onto an anonymous account upgrades it IN PLACE: the uid is PRESERVED, isAnonymous flips to false, the email is set, and providerData gains the provider. Returns a UserCredential with operationType: 'link' and providerId: null, and getAdditionalUserInfo() reports isNewUser: true and providerId: 'password' for this upgrade. The linked credential then works as a first-class signInWithEmailAndPassword.
auth-link-email-credential-to-anonymous. Divergence (#1698): the sandbox reports isNewUser: false and providerId: null for the link's additional user info. The replay pins both. (Structured evidence: oracle-conformance.test.ts, sandbox-linking-reauth.test.ts)reauthenticateWithCredential(user, credential)A wrong password throws auth/wrong-password, where production with Email Enumeration Protection on answers auth/invalid-credential (#1819). A credential for a DIFFERENT account throws auth/user-mismatch, checked before the password. On success a fresh ID token is minted, and the UserCredential carries operationType: 'reauthenticate'.
auth-reauthenticate-with-credential: the sandbox matches all but the wrong-password code. The oracle suite pins both sides. Pending fix, #1819. (Structured evidence: oracle-conformance.test.ts)getAdditionalUserInfo(userCredential)Returns { isNewUser, profile, providerId }. For a fresh anonymous sign-in prod reports { isNewUser: true, providerId: null, profile: {} }. For createUserWithEmailAndPassword and a returning signInWithEmailAndPassword, getAdditionalUserInfo().providerId is 'password' (while UserCredential.providerId stays null, AUTH-B2). isNewUser is true for createUserWithEmailAndPassword, a first-time email-link sign-in, a custom-token sign-in that minted the account, and linking an email credential onto an anonymous user (auth#160); false for a returning signInWithEmailAndPassword and for reauthenticate.
auth-additional-user-info-shape. Divergence (#1699): the sandbox reports providerId: null for the email create and sign-in arms. The replay pins both. Other arms are unit-backed. (Structured evidence: oracle-conformance.test.ts, sandbox-email-link.test.ts, sandbox-linking-reauth.test.ts, upstream-auth-probes.test.ts)signInWithCustomToken(auth, customToken)Throws auth/invalid-custom-token for a malformed token and for the empty string. createCustomToken in pyric-admin and the CLI mints a custom token in firebase-admin's shape (an RS256 JWT for the identity toolkit audience with uid and claims), signed with a sandbox key for the minting app's project, and this exchanges it (#1952): an edited signature or an exp on or before the sandbox clock's now throws auth/invalid-custom-token, and a token for another project throws auth/custom-token-mismatch. Every unsigned token throws auth/invalid-custom-token, as production answers a token it cannot verify (#2009): a JSON (optionally base64url) {uid, claims} payload, a three-part JWT for any other audience or none, and a custom-token-audience JWT the sandbox did not sign. The identity is created if it does not exist, and the credential carries providerId: null (custom-token sign-in is not a federated provider).
auth-signinwithcustomtoken-invalid captured auth/invalid-custom-token for both a malformed token and the empty string, replayed in unit:oracle-conformance.test.ts. The mismatch and expiry codes follow @firebase/auth's server error map (CREDENTIAL_MISMATCH to custom-token-mismatch, INVALID_CUSTOM_TOKEN to invalid-custom-token), not a capture. Diverged on the accept path, declared rather than hidden: prod verifies an RS256 signature against the project's service-account key, and the sandbox has none, so a token signed with a real key is refused. The mint, exchange and verify round trip runs in packages/pyric-admin/src/auth/custom-token-exchange.test.ts and the id-token-bearer-header app scenario, and each unsigned shape is refused in packages/pyric/test/auth/unsigned-custom-token.test.ts, packages/cli/test/serve/worker/unsigned-custom-token.test.ts and that scenario.inMemoryPersistence / browserSessionPersistence / browserLocalPersistence / indexedDBLocalPersistence / browserCookiePersistence / browserPopupRedirectResolver / debugErrorMap / prodErrorMapInert configuration tokens, accepted so the idiomatic initializeAuth(app, { persistence: indexedDBLocalPersistence }) and setPersistence(auth, browserCookiePersistence) compile, run, and behave identically. The .type discriminant matches upstream exactly (NONE / SESSION / LOCAL / LOCAL / COOKIE) because consumer code branches on it. browserPopupRedirectResolver is accepted and ignored — the sandbox has its own first-class pluggable equivalent (sandbox.setAuthFlowResolver). prodErrorMap is accepted and DELIBERATELY not honored: installing it upstream strips error messages, and doing that in a sandbox whose purpose is to tell a developer what went wrong would be actively hostile.
pyric/firestore uses for its cache-factory tokens. unit:types.test.ts + unit:sandbox-email-link.test.ts cover the exports. Oracle caveat recorded on auth#172: the persistenceTypes block of auth-mechanical-surface-constants reports NONE for every token including browserLocalPersistence — a Node-build stub artifact, not the browser contract, so the .type values here follow the documented Persistence.type union instead.revokeAccessToken(auth, token)Accepted no-op. In production this reaches OUTSIDE Firebase entirely — it tells the identity provider (in practice Apple) to revoke an OAuth access token, which is a call landing on Apple's servers. There is no external IdP behind a sandbox sign-in, so there is no token out there to revoke and nothing this call could truthfully do. It resolves (so the account-deletion flow Apple requires an app to ship runs end to end against the sandbox) and changes no sandbox state (because claiming otherwise would be a lie).
unit:types.test.ts — the export resolves. Deliberately not oracle-probed: a successful probe would revoke a real token at a real IdP, which is a side effect on someone else's system that a conformance run has no business causing.Operations in flight at a hosted connection drop (web hosted client)An Auth operation (a sign-in, a profile update, a token refresh) the web hosted client's socket had taken when it dropped fails once with unavailable and the message "The hosted sandbox connection was lost. Requests already sent may have completed; check state before retrying." It is not sent again. In production the Auth Web SDK fails a request whose network call fails with auth/network-request-failed and does not retry it.
@firebase/auth 1.13.1 dist/esm: a failed fetch is reported through _fail(auth, "network-request-failed"), and the request is not retried. packages/cli/test/serve/worker/hosted-reconnect-hold.test.ts drops a real loopback socket with auth.signInEmail in flight and asserts it fails once with that message and reaches the host once.getAuth(app) in a registered server processUnder a remote register activation on the Node host, firebase/auth in a server process signs in to the host: the session belongs to that process, the user is visible to firebase-admin, and its identity applies to the process's RTDB, Firestore and Storage calls. The session lasts as long as the process. When the host is not the Node host, every call fails with failed-precondition and a message naming the Node host (pyric sandbox --hosted or pyric({ hosted: true })); when no host is found, with the discovery error pyric-admin gets. No call falls back to an in-process sandbox.
test/apps/client-sdk-under-register runs the client SDKs under node --import @pyric/cli/register against a hosted Vite dev server, reads back with firebase-admin and a page, and asserts a user the process created that firebase-admin finds, and rules that allow that user's own path and deny another's. On main (942cb175) it failed: the calls ran against a private in-process sandbox, so an upload returned a data: URL and firebase-admin read nothing they wrote. packages/cli/test/register/node-origin.test.ts runs the served surfaces under a Node origin whose host is not the Node host, or cannot be found, and asserts every call fails, useWorker stays true, the served app entry's placeholder sandbox stays empty, and a pyric/* mirror resolved from the app refuses. mapping.test.ts pins the mapping per activation value.. (Structured evidence: register-child.test.ts)getAuth(app) in a server-rendered module under vite devOn a hosted dev server, firebase/auth in a server-rendered module signs in to the host. The session belongs to the dev server process: every SSR request, both of Vite's SSR loaders and a module reloaded after an edit see the same currentUser, and its identity applies to the SSR RTDB, Firestore and Storage calls. Browser sessions are separate. On a SharedWorker dev server every call fails with failed-precondition and a message naming pyric({ hosted: true }). No call reaches production or an in-process sandbox.
test/apps/vite-ssr-client-sdk signs in through ssrLoadModule, then finds the same user through the environment runner, and checks that the rules allow that user's paths and deny another's. On main (ba2c0bf0a) the scenario failed: SSR sign-in rejected with auth/network-request-failed from the network guard, and the RTDB, Firestore and Storage writes did not settle, because the imports loaded the real SDK. vite-module-swap.test.ts pins the routing per specifier, AI mode and environment (Vite 5's ssr option, a runnable environment, a non-runnable one), vite-ssr-activation.test.ts the host, the restart hand-over and the SharedWorker refusal, and vite-plugin-firestore.test.ts runs Vite with firebase installed, so it takes the externalized path. (Structured evidence: scenario.ts)Bugs
Behavior that should match production Firebase but currently does not.
User` methodsRules see the session's minted ID token exactly: RTDB auth.token and Firestore and Storage request.auth.token carry every decoded claim with its value, sub, aud, iss, iat, exp and auth_time included (iss is https://securetoken.google.com/ plus aud, exp - iat is 3600, auth_time stays the sign-in time across refreshes), claims the token lacks read null, and RTDB auth.provider equals firebase.sign_in_provider; per sign-in kind (anonymous, password, verified profile, custom token for a new or existing account, custom claims after a forced refresh, reload, updateProfile, password reauthentication, email link). Custom-token claims merge over the account's stored claims for that session only
oracle:auth-request-auth-per-sign-in (real sign-ins, RTDB probes deployed per decoded token) and oracle:auth-request-auth-rules-test-api (Firestore and Storage evaluating the same claim sets). In-page replay with pins: unit:request-auth-per-sign-in.test.tsNot implemented yet
Tracked behavior that is not implemented in the current contract.
signInWithPopup(auth, provider)` / `signInWithCredential(auth, credential)Cancels with auth/popup-closed-by-user when the user dismisses the popup (prod)
Custom scopes / params / language code
User` methodsuser.metadata.creationTime / lastSignInTime
User.metadata not exposed (AUTH-GAP); the admin record carries createdAt/lastLoginAt (ISO)User` methodsuser.reload() / user.delete() / user.toJSON() / user.refreshToken / user.tenantId
fetchSignInMethodsForEmail(auth, email)Not implemented; disposition auth.email-enumeration owns the reviewed availability and rationale.
auth-fetchsigninmethodsforemail-deprecated capture, in the #1676 re-capture (firebase 12.19.0, digame-mas, Email Enumeration Protection on), returned an empty list both for an account that has a password method and for an unknown address, so the method cannot tell them apart.Unverified
Tracked behavior whose available evidence does not yet establish the production result.
getAuth(target)Without sandbox package swapping, canonical firebase/auth imports remain Firebase and never enter this mirror
unit:package-resolution.test.ts; an unswapped production-resolution observation is still neededUser` methodsgetIdToken() after expiry returns a fresh token: a minted token lasts one hour (exp - iat is 3600), a non-forced read once the clock passes exp minus 30 seconds mints a new token, fires onIdTokenChanged but not onAuthStateChanged, and rules read the new token, on the in-page and worker planes
StsTokenManager.isExpired in @firebase/auth 1.13.6 (Date.now() > expirationTime - 30000, TOKEN_REFRESH_BUFFER_MS), and exp - iat of 3600 in oracle:auth-request-auth-per-sign-in (row 68c). Pyric: unit:sandbox-token-lifetime.test.ts (in-page) and unit:auth-token-lifetime.test.ts (worker port) move the sandbox clock past the refresh point; the app scenario test/apps/id-token-bearer-header moves it 61 minutes with pyric sandbox advanceClock and verifies the page's next token with firebase-admin. A production observation of a read after expiry is still neededReviewed public-runtime gaps
auth.mfa-phone-recaptchaMFA / phone / reCAPTCHA is deferred, not out of scope — reCAPTCHA/SMS are external infrastructure Pyric can mock with the OAuth resolver pattern, and TOTP is pure algorithm work.
PhoneAuthCredential PhoneAuthProvider PhoneMultiFactorGenerator RecaptchaVerifier TotpMultiFactorGenerator TotpSecret getMultiFactorResolver initializeRecaptchaConfig linkWithPhoneNumber multiFactor reauthenticateWithPhoneNumber signInWithPhoneNumberauth.email-enumerationDeprecated upstream as a security retraction, not a cosmetic one: the shipped @firebase/auth declaration states it "returns an empty list when Email Enumeration Protection is enabled, irrespective of the number of authentication methods available", and that "migrating off of this method is recommended as a security best-practice". Enumeration protection is on by default, so against a modern project the production function always returns []. A mirror that reproduced the pre-deprecation behavior would be MORE capable than prod and would silently mislead agent code that branches on the result; a mirror that reproduced the post-deprecation behavior would be a no-op. Same criterion applied to Imagen in firebase/ai — an API whose production counterpart is retiring is out of scope, because mirroring it freezes dead behavior.
fetchSignInMethodsForEmailauth.phone-mutationPhone number mutation is deferred alongside the rest of the phone-auth family — buildable via a mocked SMS/verification-code resolver, the same shape as the OAuth resolver.
updatePhoneNumber