@pyric/cli 0.1.0-alpha.9

package/dist/serve/docs-ui/docs/pyric-auth-reference-feature-matrix.md

@@ -0,0 +1,198 @@
+# Feature matrix: `pyric/auth` coverage of `firebase/auth`
+
+Coverage of the modular Web SDK Auth surface when package resolution swaps canonical `firebase/auth` imports to the Pyric sandbox mirror. Production installs no swap and continues using Firebase.
+
+**Legend:**
+
+- ✅: exported by `pyric/auth` with the same name and compatible signature as upstream.
+- ⚠️: exported, but with a caveat: signature subset, sandbox-only no-op, runtime parity gap, or similar. Read the note.
+- ❌: not exported. Code that imports it will fail to resolve when the sandbox-preview build aliases `firebase/auth` → `pyric/auth`.
+
+The right column ("Use in agent-generated `appSource`?") is the deny-list / allow-list the agent's system prompt should encode once the playground alias swap lands.
+
+---
+
+## Initialization & lifecycle
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `getAuth(app)` | ✅ | Also accepts `Sandbox` overload (sandbox-only) | Yes |
+| `initializeAuth(app, deps?)` | ❌ | No custom dependency injection on sandbox backend | No |
+| `connectAuthEmulator(auth, url, options?)` | ✅ | Accepted no-op; the mirror is already a sandbox | Yes |
+| `setPersistence(auth, persistence)` | ✅ | Records the sandbox session storage mode; rejects unknown marker types | Yes |
+| `inMemoryPersistence` | ✅ | Marker `{type: 'NONE'}`; maps to upstream singleton | Yes |
+| `browserSessionPersistence` | ✅ | Marker `{type: 'SESSION'}` | Yes |
+| `browserLocalPersistence` | ✅ | Marker `{type: 'LOCAL'}` | Yes |
+| `indexedDBLocalPersistence` | ❌ | Browser-specific persistence not modelled in sandbox | No |
+| `useDeviceLanguage(auth)` | ❌ | Localization not modelled | No |
+| `auth.languageCode` | ❌ | As above | No |
+| `auth.tenantId` | ❌ | Multi-tenant not in v0 | No |
+
+## Sign-in / sign-out
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `signInAnonymously(auth)` | ✅ | Sandbox: auto-mints `anonymous-N` uid (recorded in the user DB; `sign_in_provider: 'anonymous'`) | Yes |
+| `signInWithEmailAndPassword(auth, email, pw)` | ✅ | Sandbox: lookup in in-memory DB. Disabled accounts (`sandbox.updateUser(…, {disabled: true})`) throw `auth/user-disabled` | Yes |
+| `createUserWithEmailAndPassword(auth, email, pw)` | ✅ | Sandbox: adds to in-memory DB with the `password` provider recorded | Yes |
+| `signInWithPopup(auth, provider, resolver?)` | ⚠️ | Delegates to a configured sandbox `AuthFlowResolver` (per-call arg → `sandbox.setAuthFlowResolver` → one-shot `mockSignInResult` → throws `auth/argument-error`, matching upstream's no-resolver default). The `resolver` arg is sandbox-only. Unswapped production imports remain on `firebase/auth` and its platform resolver. Sandbox sign-in records the provider on the identity (user DB upsert) and throws `auth/user-disabled` for disabled accounts | Yes |
+| `signInWithCredential(auth, credential)` | ⚠️ | Mock-or-throw, keyed on `credential.providerId` (not a popup/resolver flow, opens no UI); throws `auth/no-mock-configured` with none staged. Records the provider; disabled accounts throw `auth/user-disabled` | Yes |
+| `signInWithRedirect(auth, provider, resolver?)` | ⚠️ | Resolves inline via the sandbox `AuthFlowResolver` (no real navigation); signs in + stashes for `getRedirectResult`. Unswapped production imports remain on `firebase/auth` (real navigation) | Yes |
+| `getRedirectResult(auth)` | ⚠️ | Returns-and-clears the pending sandbox redirect credential (one-shot), or `null`. Unswapped production imports remain on `firebase/auth` | Yes |
+| `signInWithCustomToken(auth, token)` | ✅ | Accepts JSON `{uid, claims?}` (or base64url / JWT payload segment). Signature not verified (documented ⚠ accept-path). Mints identity if missing; `providerId: null` | Yes |
+| `signInWithPhoneNumber(auth, phone, verifier)` | ❌ | Phone auth out of scope v0 | No |
+| `signInWithEmailLink(auth, email, link)` | ⚠️ | Sandbox: consumes outbox / action-code path; see COMPAT email-link rows | Yes |
+| `isSignInWithEmailLink(auth, link)` | ✅ | Client-side predicate | Yes |
+| `sendSignInLinkToEmail(auth, email, settings)` | ⚠️ | Sandbox: records mail in auth outbox (`sandbox.takeAuthMail`) rather than SMTP | Yes |
+| `signOut(auth)` | ✅ | Sandbox: sets currentUser to null, emits | Yes |
+| `auth.signOut()` (method form) | ✅ | Same as the free function; `firebase/auth`'s `Auth` exposes both (AUTH-GAP) | Yes |
+
+## Observers
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `onAuthStateChanged(auth, observer)` | ✅ | Function + observer-object forms; immediate fire on subscribe | Yes |
+| `onIdTokenChanged(auth, observer)` | ✅ | Sandbox: fires on identity change AND on `getIdToken(true)` forced refresh, matching prod (oracle `auth-onidtokenchanged-force-refresh.json`). Does not fire *spontaneously* (sandbox tokens don't expire). | Yes |
+| `beforeAuthStateChanged(auth, callback, onAbort?)` | ✅ | Blocking gate: runs before a real sign-in/sign-out transition commits. A throwing callback aborts the transition (`auth/login-blocked`); `currentUser` unchanged, `onAuthStateChanged`/`onIdTokenChanged` don't fire. Covers every sign-in path `pyric/auth` has. Does NOT gate `sandbox.setUser` (test-only, no prod analog) — see COMPAT.md. | Yes |
+
+## Providers
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `GoogleAuthProvider` | ✅ | `PROVIDER_ID = 'google.com'`; `addScope` / `setCustomParameters` no-ops | Yes |
+| `EmailAuthProvider` | ✅ | `PROVIDER_ID = 'password'` | Yes |
+| `FacebookAuthProvider` | ✅ | `PROVIDER_ID = 'facebook.com'` | Yes |
+| `GithubAuthProvider` | ✅ | `PROVIDER_ID = 'github.com'` | Yes |
+| `OAuthProvider` | ✅ | Constructor takes `providerId: string` | Yes |
+| `TwitterAuthProvider` | ❌ | Use `new OAuthProvider('twitter.com')` instead | No |
+| `SAMLAuthProvider` | ❌ | Enterprise SSO out of scope v0 | No |
+| `PhoneAuthProvider` | ❌ | Phone auth out of scope v0 | No |
+| `RecaptchaVerifier` | ❌ | As above | No |
+
+## Multi-factor
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `multiFactor(user)` | ❌ | MFA out of scope v0 | No |
+| `MultiFactorSession` | ❌ | As above | No |
+| `getMultiFactorResolver(auth, error)` | ❌ | As above | No |
+| `PhoneMultiFactorGenerator` | ❌ | As above | No |
+| `TotpMultiFactorGenerator` | ❌ | As above | No |
+| `TotpSecret` | ❌ | As above | No |
+
+## Link / unlink / re-authenticate
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `linkWithCredential(user, credential)` | ❌ | Link flows out of scope v0 | No |
+| `linkWithPopup(user, provider)` | ❌ | As above | No |
+| `linkWithRedirect(user, provider)` | ❌ | As above | No |
+| `unlink(user, providerId)` | ❌ | As above | No |
+| `reauthenticateWithCredential(user, credential)` | ❌ | Re-auth out of scope v0 | No |
+| `reauthenticateWithPopup(user, provider)` | ❌ | As above | No |
+| `reauthenticateWithRedirect(user, provider)` | ❌ | As above | No |
+| `reauthenticateWithPhoneNumber(user, phone, verifier)` | ❌ | As above | No |
+
+## Profile mutation
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `updateProfile(user, { displayName, photoURL })` | ✅ | Mutates held user + stored record; null clears; no extra `onAuthStateChanged` | Yes |
+| `updateEmail(user, newEmail)` | ✅ | Updates store + held user; next sign-in uses the new email (no `requires-recent-login`) | Yes |
+| `updatePassword(user, newPassword)` | ✅ | Stored + verified; old password rejected after change (no `requires-recent-login`) | Yes |
+| `verifyBeforeUpdateEmail(user, newEmail, settings?)` | ✅ | Mails a code to the new address via auth outbox; email changes only on redemption (`emailVerified: true`) | Yes |
+| `deleteUser(user)` | ✅ | Removes store record and signs out if current; post-delete `reload(user)` → `auth/user-token-expired` | Yes |
+| `reload(user)` | ✅ | Re-reads store into held user; missing identity → `auth/user-token-expired` | Yes |
+
+## Password reset & email verification
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `sendPasswordResetEmail(auth, email, settings?)` | ❌ | Email flows out of scope v0 | No |
+| `confirmPasswordReset(auth, code, newPassword)` | ❌ | As above | No |
+| `sendEmailVerification(user, settings?)` | ❌ | As above | No |
+| `applyActionCode(auth, code)` | ❌ | As above | No |
+| `verifyPasswordResetCode(auth, code)` | ❌ | As above | No |
+| `checkActionCode(auth, code)` | ❌ | As above | No |
+| `revokeAccessToken(auth, token)` | ❌ | As above | No |
+| `validatePassword(auth, password)` | ❌ | Password-policy enforcement out of scope v0 | No |
+
+## User token / refresh
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `user.getIdToken(forceRefresh?)` | ⚠️ | Sandbox: returns stable opaque `sandbox-id-token-…` string | Yes |
+| `user.getIdTokenResult(forceRefresh?)` | ⚠️ | Sandbox: claims include `customClaims` + synthesized `sub`/`aud`/`iss` + reserved `firebase.sign_in_provider`; `signInProvider` reflects the session's provider (`'anonymous'`/`'password'`/`'google.com'`/…). Claims are read live from the user DB, so `sandbox.updateUser` claims changes land on the next forced refresh (prod parity) | Yes |
+| `user.{photoURL, emailVerified, phoneNumber, providerId, providerData}` | ✅ | Present on every `User`; sandbox synthesizes (photoURL/phoneNumber `null`, emailVerified `false`, one `providerData` entry for non-anon); prod passes the real values through (no longer stripped) (AUTH-GAP) | Yes |
+| `user.reload()` / `user.delete()` | ⚠️ | Prefer top-level `reload(user)` / `deleteUser(user)` (COMPAT ✓); instance methods are not the documented appSource path | No |
+| `user.{metadata, refreshToken, tenantId, toJSON()}` | ❌ | Not modeled by the sandbox; documented per AUTH-GAP | No |
+
+## Error code constants
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `AuthErrorCodes` module | ❌ | Use string literals (`'auth/user-not-found'` etc.) | No |
+| `FirebaseError` instanceof check | ✅ | Sandbox throws a real `FirebaseError` (from `firebase/app`) with the prod message wrapper `Firebase: <msg> (<auth/...>).`; `err instanceof FirebaseError` holds (AUTH-GAP) | Yes |
+
+## Result & wrapper types
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `Auth` | ✅ | Opaque handle with `currentUser` getter + `TARGET_SYMBOL` brand | Yes |
+| `User` | ✅ | Subset: uid, email, displayName, isAnonymous, getIdToken, getIdTokenResult | Yes |
+| `UserCredential` | ✅ | `{ user, providerId, operationType }` | Yes |
+| `AuthCredential` | ✅ | `{ providerId, signInMethod }` opaque marker | Yes |
+| `IdTokenResult` | ✅ | `{ token, claims, expirationTime, issuedAtTime, authTime, signInProvider? }`. `signInProvider` optional at the type level until all `User` minting is backend-owned (post-B1); the sandbox always populates it | Yes |
+| `Persistence` | ✅ | `{ type: 'NONE' \| 'SESSION' \| 'LOCAL' }` | Yes |
+| `AuthObserver` | ✅ | Function or `{ next, error, complete }` object | Yes |
+| `Unsubscribe` | ✅ | `() => void` | Yes |
+| `AuthProvider` | ✅ | Union of provider classes | Yes |
+| `ActionCodeSettings` | ❌ | Action-code flows out of scope v0 | No |
+| `ActionCodeInfo` | ❌ | As above | No |
+| `UserMetadata` | ❌ | Not exposed on the v0 User subset | No |
+| `UserInfo` | ❌ | As above | No |
+| `AdditionalUserInfo` | ❌ | As above | No |
+
+## Sandbox-only additions
+
+These have no `firebase/auth` equivalent. They live under the `sandbox.*` namespace and require an `Auth` handle produced by this mirror.
+
+| Symbol | Status | Note | Use in `appSource`? |
+|---|---|---|---|
+| `sandbox.setUser(auth, user)` | ✅ | Sandbox-only test driver. Bypasses the `disabled` check and does NOT bump `lastLoginAt` (not a real sign-in) | **No**, never appears in deployed app code |
+| `sandbox.mockSignInResult(auth, result)` | ✅ | Sandbox-only test driver (one-shot resolver tier) | **No**, same |
+| `sandbox.seedUsers(auth, users)` | ✅ | Sandbox-only test driver. Seed records accept optional `providerId` (default `'password'`) | **No**, same |
+| `sandbox.setAuthFlowResolver(auth, resolver)` | ✅ | Sandbox-only: installs the popup/redirect resolver (host serves the sign-in UI) | **No**, host wiring, never app code |
+| `sandbox.listIdentities(auth)` | ✅ | Sandbox-only: snapshot of seeded/created identities for an account-picker UI. Returns the REAL provider per identity (`providerId` primary label + emulator-shaped `providerUserInfo` array); anonymous users included | **No**, host wiring |
+| `sandbox.createSignInCredential(auth, {providerId, uid \| spec})` | ✅ | Sandbox-only: backend-owned credential minting for host-driven flows (account picker pick/add). Tokens route through the backend token cache | **No**, host wiring |
+| `sandbox.listUsers(auth)` | ✅ | Sandbox-only user admin: every DB record as an emulator-REST-shaped `AuthUserRecord` | **No**, host wiring |
+| `sandbox.createUser(auth, request)` | ✅ | Sandbox-only user admin: create WITHOUT signing in (admin semantics) | **No**, host wiring |
+| `sandbox.updateUser(auth, uid, update)` | ✅ | Sandbox-only user admin: displayName/email/password/customClaims/disabled/emailVerified | **No**, host wiring |
+| `sandbox.deleteUser(auth, uid)` | ✅ | Sandbox-only user admin. Active session not terminated (prod parity) | **No**, host wiring |
+| `sandbox.clearUsers(auth)` | ✅ | Sandbox-only user admin: the emulator's "delete all accounts" | **No**, host wiring |
+| `sandbox.subscribeUsers(auth, cb)` | ✅ | Sandbox-only: coarse user-DB-changed callback (no payload, no initial fire; re-list in the callback) | **No**, host wiring |
+| `TARGET_SYMBOL` | ✅ | Internal brand; agents should not read it | No |
+
+See [sandbox-test-driver.md](../pyric-auth-reference-sandbox-test-driver/) for the full driver API.
+
+---
+
+## Adjacent surfaces not in this matrix
+
+- `firebase/app`: `initializeApp`, `getApp`, `getApps`, `FirebaseApp`. Used by the playground template; no pyric shim because `getAuth(sandbox)` skips the app handle entirely.
+
+## How this matrix gets used
+
+- **The agent's system prompt** (once the alias swap lands) encodes the "No" column as an explicit deny-list. Agents generating `appSource` won't reach for symbols that break sandbox preview.
+- **The sandbox preview build** (deferred follow-up) aliases `firebase/auth` → `pyric/auth`. A ✅ row is guaranteed to work. A ⚠️ row works at the type level but has a sandbox-runtime caveat: acceptable for preview, fix-on-deploy.
+- **The deploy build** has no aliases. Whatever the agent imports resolves to real `firebase/auth` in node_modules. Any symbol the upstream SDK exports works; ❌ rows from this matrix only fail in sandbox preview, not in production. The deploy adapter's metafile gate rejects any prod bundle containing `@pyric/*`.
+
+---
+
+## Keeping this matrix honest
+
+Re-run this audit when:
+
+- `pyric/auth` adds or removes exports.
+- The upstream `firebase/auth` modular SDK adds a new symbol category (passkeys / WebAuthn extensions, OAuth2 client_credentials grants, etc.).
+- The sandbox backend closes a parity gap: flip the row from ⚠️ to ✅. (Done for `onIdTokenChanged` forced-refresh and the popup/redirect resolver flow.)

package/dist/serve/docs-ui/docs/pyric-auth-reference-sandbox-test-driver/index.html

@@ -0,0 +1,71 @@
+<!DOCTYPE html><html lang="en"> <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Sandbox test driver: pyric/auth/sandbox.* · Pyric Studio</title><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link rel="stylesheet" href="/__pyric/ui/_astro/_slug_.CQYSemvw.css"></head> <body>  <header class="studio__bar"> <div class="studio__bar-inner"> <a class="studio__brand" href="/__pyric/ui/" aria-label="Pyric Studio">Pyric</a> <nav class="studio__nav" aria-label="Studio tabs"> <a class="studio__nav-tab" href="/__pyric/ui/"> Home </a><a class="studio__nav-tab" href="/__pyric/ui/firestore"> Firestore </a><a class="studio__nav-tab" href="/__pyric/ui/auth"> Auth </a><a class="studio__nav-tab" href="/__pyric/ui/rtdb"> RTDB </a><a class="studio__nav-tab" href="/__pyric/ui/storage"> Storage </a><a class="studio__nav-tab" href="/__pyric/ui/traffic"> Traffic </a><a class="studio__nav-tab" href="/__pyric/ui/settings"> Settings </a><a class="studio__nav-tab" href="/__pyric/ui/docs" aria-current="page"> Docs </a> </nav> </div> </header> <div class="docs-shell">  <details class="docs-nav-drawer"> <summary>Navigate</summary> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div> <script type="module">let i=null;function d(t){return i||(i=fetch(t).then(e=>e.json())),i}function l(t,e){return t.title.toLowerCase().includes(e)||t.excerpt.toLowerCase().includes(e)?!0:t.headings.some(r=>r.text.toLowerCase().includes(e))}function u(t,e,r){if(e.innerHTML="",t.length===0){e.hidden=!1;{const n=document.createElement("li");n.className="docs-search-empty",n.textContent="No matches",e.appendChild(n)}return}e.hidden=!1;for(const n of t.slice(0,8)){const s=document.createElement("li"),c=document.createElement("a");c.href=n.path;const o=document.createElement("span");o.className="docs-search-result-title",o.textContent=n.title;const a=document.createElement("span");a.className="docs-search-result-meta",a.textContent=[n.group,n.section].filter(Boolean).join(" / "),c.append(o,a),s.appendChild(c),e.appendChild(s)}}document.querySelectorAll(".docs-search").forEach(t=>{const e=t.dataset.indexUrl,r=t.querySelector(".docs-search-input"),n=t.querySelector(".docs-search-results");r.addEventListener("input",async()=>{const s=r.value.trim().toLowerCase();if(!s){n.hidden=!0,n.innerHTML="";return}const{pages:c}=await d(e);r.value.trim().toLowerCase()===s&&u(c.filter(o=>l(o,s)),n)}),r.addEventListener("focus",()=>{d(e),n.childElementCount>0&&(n.hidden=!1)}),r.addEventListener("keydown",s=>{s.key==="Escape"&&(r.value="",n.hidden=!0,n.innerHTML="",r.blur())}),r.addEventListener("blur",()=>{window.setTimeout(()=>{n.hidden=!0},150)})});document.addEventListener("keydown",t=>{if(!(t.metaKey||t.ctrlKey)||t.key.toLowerCase()!=="k")return;const e=[...document.querySelectorAll(".docs-search-input")].find(r=>r.offsetParent!==null);e&&(t.preventDefault(),e.focus(),e.select())});</script> <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/"> Overview </a><details class="docs-nav-group"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/" aria-current="true"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> </details> <nav class="docs-nav" aria-label="Documentation"> <div class="docs-search" data-index-url="/__pyric/ui/docs/index.json"> <div class="docs-search-field"> <svg class="docs-search-icon" viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"> <path d="M11.5 11.5 15 15M13 7A6 6 0 1 1 1 7a6 6 0 0 1 12 0Z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"></path> </svg> <input type="text" class="docs-search-input" placeholder="Search docs" aria-label="Search docs" autocomplete="off" spellcheck="false"> <kbd class="docs-search-kbd">⌘K</kbd> </div> <ul class="docs-search-results" hidden></ul> </div>  <a class="docs-nav-toplink" href="/__pyric/ui/docs/overview/" id="nav-group-overview"> Overview </a><details class="docs-nav-group" id="nav-group-run-locally"> <summary>Run locally</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/start-building/"> Quickstart </a> </li><li> <a href="/__pyric/ui/docs/how-the-swap-works/"> How the swap works </a> </li><li> <a href="/__pyric/ui/docs/set-up-your-agent/"> Connect an agent </a> </li><li> <a href="/__pyric/ui/docs/test-in-node/"> Test in Node </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-develop-with-firebase-apis"> <summary>Develop with Firebase APIs</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/sign-in-and-manage-users/"> Sign in and manage users </a> </li><li> <a href="/__pyric/ui/docs/store-and-query-data/"> Store and query data </a> </li><li> <a href="/__pyric/ui/docs/sync-realtime-data/"> Sync realtime data </a> </li><li> <a href="/__pyric/ui/docs/store-files/"> Store files </a> </li><li> <a href="/__pyric/ui/docs/receive-messages/"> Receive messages </a> </li><li> <a href="/__pyric/ui/docs/run-ai-logic-locally/"> Run AI Logic locally </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-how-to-run-rtdb-onvaluecreated/"> Run an RTDB function locally </a> </li><li> <a href="/__pyric/ui/docs/which-data-service/"> Which data service? </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-inspect-and-correct"> <summary>Inspect and correct</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-inspect-the-sandbox"> Inspect the sandbox </h2> <ul> <li> <a href="/__pyric/ui/docs/see-whats-happening/"> Traffic &amp; rule verdicts </a> </li><li> <a href="/__pyric/ui/docs/read-a-denial/"> Read a denial and understand it </a> </li><li> <a href="/__pyric/ui/docs/shape-your-data/"> Seed, snapshot, replay </a> </li><li> <a href="/__pyric/ui/docs/watch-and-review/"> Review agent activity </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-correct-security-rules"> Correct Security Rules </h2> <ul> <li> <a href="/__pyric/ui/docs/secure-it-with-rules/"> Security Rules </a> </li><li> <a href="/__pyric/ui/docs/simulate-and-lint/"> Simulate and lint before you deploy </a> </li><li> <a href="/__pyric/ui/docs/rules-patterns/"> Rules patterns </a> </li><li> <a href="/__pyric/ui/docs/rules-standard-library/"> The rules standard library </a> </li><li> <a href="/__pyric/ui/docs/rtdb-rules-in-typescript/"> RTDB rules in TypeScript </a> </li><li> <a href="/__pyric/ui/docs/firestore-rules-limits/"> Rules limits </a> </li><li> <a href="/__pyric/ui/docs/whats-possible/"> Case studies </a> </li> </ul> </div><div class="docs-nav-section"> <h2 class="docs-nav-heading" id="nav-section-inspect-and-correct-work-with-an-agent"> Work with an agent </h2> <ul> <li> <a href="/__pyric/ui/docs/what-your-agent-can-do/"> Work through an agent </a> </li><li> <a href="/__pyric/ui/docs/skills/"> Agent skills </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-verify-the-boundary"> <summary>Verify the boundary</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/pyric-cli-how-to-verify-against-a-captured-session/"> Verify a captured session </a> </li><li> <a href="/__pyric/ui/docs/write-a-rules-test-suite/"> Write a rules test suite </a> </li><li> <a href="/__pyric/ui/docs/audit-your-rules/"> Audit rules and data </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-ship-unchanged"> <summary>Ship unchanged</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/ship-to-production/"> Ship to production </a> </li><li> <a href="/__pyric/ui/docs/set-up-the-project/"> Set up the Firebase project </a> </li> </ul> </div> </div> </details><details class="docs-nav-group" id="nav-group-conformance"> <summary>Conformance</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section">  <ul> <li> <a href="/__pyric/ui/docs/how-we-know-it-matches-firebase/"> Conformance </a> </li><li> <a href="/__pyric/ui/docs/whats-experimental/"> What&#39;s experimental </a> </li><li> <a href="/__pyric/ui/docs/pyric-conformance-scores/"> Conformance scores </a> </li><li> <a href="/__pyric/ui/docs/pyric-app-compat/"> App </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore-compat/"> Firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth-compat/"> Auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database-compat/"> Realtime Database </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage-compat/"> Storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules-compat/"> Rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-messaging-compat/"> Messaging </a> </li><li> <a href="/__pyric/ui/docs/pyric-ai-compat/"> AI Logic </a> </li><li> <a href="/__pyric/ui/docs/pyric-cli-functions-rtdb-compat/"> Functions · RTDB </a> </li> </ul> </div> </div> </details> <details class="docs-nav-group" id="nav-group-reference" open> <summary>Reference</summary> <div class="docs-nav-group-body"> <div class="docs-nav-section"> <ul> <li> <a href="/__pyric/ui/docs/pyric-cli/"> @pyric/cli </a> </li><li> <a href="/__pyric/ui/docs/pyric-explanation-versioning-and-compatibility/"> pyric </a> </li><li> <a href="/__pyric/ui/docs/pyric-firestore/"> pyric / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-rules/"> pyric / rules </a> </li><li> <a href="/__pyric/ui/docs/pyric-sandbox/"> pyric / sandbox </a> </li><li> <a href="/__pyric/ui/docs/pyric-storage/"> pyric / storage </a> </li><li> <a href="/__pyric/ui/docs/pyric-auth/" aria-current="true"> pyric / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-database/"> pyric / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-app/"> pyric-admin / app </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-firestore/"> pyric-admin / firestore </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-auth/"> pyric-admin / auth </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-database/"> pyric-admin / database </a> </li><li> <a href="/__pyric/ui/docs/pyric-admin-storage/"> pyric-admin / storage </a> </li><li> <a href="/__pyric/ui/docs/ui/"> @pyric/ui </a> </li><li> <a href="/__pyric/ui/docs/api-reference/"> API reference </a> </li> </ul> </div> </div> </details> </nav> <main class="doc-main"> <nav class="docs-breadcrumbs" aria-label="Breadcrumb"> <ol> <li>  <a href="/__pyric/ui/docs/pyric-auth/">pyric / auth</a> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span>Reference</span> </li><li> <span class="docs-breadcrumbs-sep" aria-hidden="true">/</span> <span aria-current="page">Sandbox test driver</span> </li> </ol> </nav>  <article class="prose">  <h1 id="sandbox-test-driver-pyricauthsandbox">Sandbox test driver: <code>pyric/auth/sandbox.*</code></h1>
+<p>The <code>sandbox</code> export is <code>pyric/auth</code>’s test-driver namespace. It mirrors <code>pyric/firestore</code>’s <code>sandbox.setRules</code> / <code>sandbox.seedDocuments</code> pattern: methods exist only for sandbox-backed <code>Auth</code> handles and throw <code>failed-precondition</code> against a prod handle.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">sandbox</span><span style="color:#C678DD"> as</span><span style="color:#E06C75"> authSandbox</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> 'pyric/auth'</span><span style="color:#ABB2BF">;</span></span></code></pre>
+<p>The import alias avoids the name collision with the local <code>const sandbox = initializeSandbox()</code> you’ll typically have in scope.</p>
+<hr>
+<h2 id="sandboxsetuserauth-user--null"><code>sandbox.setUser(auth, user | null)</code></h2>
+<p>Force the current user. Bypasses email/password lookup, mock-result registry, and seeded DB. Pass <code>null</code> to sign out.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#E5C07B">authSandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">setUser</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'forced-uid'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  email</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'forced@example.com'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  displayName</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'Forced User'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  isAnonymous</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">false</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#61AFEF">  getIdToken</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">async</span><span style="color:#ABB2BF"> () </span><span style="color:#C678DD">=></span><span style="color:#98C379"> 'fake-token'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#61AFEF">  getIdTokenResult</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">async</span><span style="color:#ABB2BF"> () </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> ({</span></span>
+<span class="line"><span style="color:#E06C75">    token</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'fake-token'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    claims</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">role</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'admin'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#E06C75">    expirationTime</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">new</span><span style="color:#61AFEF"> Date</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">Date</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">now</span><span style="color:#ABB2BF">() </span><span style="color:#56B6C2">+</span><span style="color:#D19A66"> 3600_000</span><span style="color:#ABB2BF">).</span><span style="color:#61AFEF">toISOString</span><span style="color:#ABB2BF">(),</span></span>
+<span class="line"><span style="color:#E06C75">    issuedAtTime</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">new</span><span style="color:#61AFEF"> Date</span><span style="color:#ABB2BF">().</span><span style="color:#61AFEF">toISOString</span><span style="color:#ABB2BF">(),</span></span>
+<span class="line"><span style="color:#E06C75">    authTime</span><span style="color:#ABB2BF">: </span><span style="color:#C678DD">new</span><span style="color:#61AFEF"> Date</span><span style="color:#ABB2BF">().</span><span style="color:#61AFEF">toISOString</span><span style="color:#ABB2BF">(),</span></span>
+<span class="line"><span style="color:#ABB2BF">  }),</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span></code></pre>
+<p>Emits to <code>onAuthStateChanged</code> / <code>onIdTokenChanged</code> subscribers and writes through to <code>sandbox.currentUser</code>.</p>
+<hr>
+<h2 id="sandboxmocksigninresultauth-result"><code>sandbox.mockSignInResult(auth, result)</code></h2>
+<p>Pre-stage the result that the next matching <code>signInWithPopup</code> / <code>signInWithCredential</code> call returns. The mock is <strong>one-shot</strong>, consumed by the next call with the matching <code>providerId</code>. Stage again for repeat tests.</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#E5C07B">authSandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">mockSignInResult</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">, {</span></span>
+<span class="line"><span style="color:#E06C75">  user</span><span style="color:#ABB2BF">: </span><span style="color:#61AFEF">makeGoogleUser</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'uid-1'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'a@example.com'</span><span style="color:#ABB2BF">),</span></span>
+<span class="line"><span style="color:#E06C75">  providerId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'google.com'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">  operationType</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'signIn'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#ABB2BF">});</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> signInWithPopup</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">, </span><span style="color:#C678DD">new</span><span style="color:#61AFEF"> GoogleAuthProvider</span><span style="color:#ABB2BF">());</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// → resolves to the mock, sets currentUser to mock.user</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> signInWithPopup</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">, </span><span style="color:#C678DD">new</span><span style="color:#61AFEF"> GoogleAuthProvider</span><span style="color:#ABB2BF">());</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// → throws auth/no-mock-configured</span></span></code></pre>
+<p>The provider passed to <code>signInWithPopup</code> must have a <code>providerId</code> that matches <code>result.providerId</code>.</p>
+<hr>
+<h2 id="sandboxseedusersauth-users"><code>sandbox.seedUsers(auth, users)</code></h2>
+<p>Bulk-load test users for email/password lookup. Each record:</p>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#C678DD">interface</span><span style="color:#E5C07B"> SeedUser</span><span style="color:#ABB2BF"> {</span></span>
+<span class="line"><span style="color:#E06C75">  uid</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  email</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  password</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  displayName</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">;</span></span>
+<span class="line"><span style="color:#E06C75">  customClaims</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Record</span><span style="color:#ABB2BF">&#x3C;</span><span style="color:#E5C07B">string</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">unknown</span><span style="color:#ABB2BF">>;</span></span>
+<span class="line"><span style="color:#ABB2BF">}</span></span></code></pre>
+<pre class="astro-code one-dark-pro" style="background-color:#282c34;color:#abb2bf; overflow-x: auto;" tabindex="0" data-language="ts"><code><span class="line"><span style="color:#E5C07B">authSandbox</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">seedUsers</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">, [</span></span>
+<span class="line"><span style="color:#ABB2BF">  { </span><span style="color:#E06C75">uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">email</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'alice@example.com'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">password</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'pw1'</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#ABB2BF">  {</span></span>
+<span class="line"><span style="color:#E06C75">    uid</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'admin'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    email</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'admin@example.com'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    password</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'pw2'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    displayName</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'Admin User'</span><span style="color:#ABB2BF">,</span></span>
+<span class="line"><span style="color:#E06C75">    customClaims</span><span style="color:#ABB2BF">: { </span><span style="color:#E06C75">role</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'admin'</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">tier</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">5</span><span style="color:#ABB2BF"> },</span></span>
+<span class="line"><span style="color:#ABB2BF">  },</span></span>
+<span class="line"><span style="color:#ABB2BF">]);</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#C678DD">await</span><span style="color:#61AFEF"> signInWithEmailAndPassword</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">auth</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'admin@example.com'</span><span style="color:#ABB2BF">, </span><span style="color:#98C379">'pw2'</span><span style="color:#ABB2BF">);</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// auth.currentUser.uid === 'admin'</span></span>
+<span class="line"><span style="color:#7F848E;font-style:italic">// (await auth.currentUser.getIdTokenResult()).claims.role === 'admin'</span></span></code></pre>
+<p><code>customClaims</code> flow through into <code>sandbox.currentUser.token</code>, which is what the Firestore rules engine reads as <code>request.auth.token.*</code>. This is the seam that makes rules tests with custom claims work end-to-end on sandbox.</p>
+<p>Email lookup is case-insensitive. Re-seeding the same uid overwrites.</p>
+<hr>
+<h2 id="errors">Errors</h2>
+<p>These helpers require an <code>Auth</code> handle produced by <code>pyric/auth</code>. Production
+code remains on <code>firebase/auth</code> and does not load the sandbox driver.</p>
+<p><code>sandbox.mockSignInResult</code> additionally throws <code>'invalid-argument'</code> if <code>result.providerId</code> is missing. The mock registry is keyed on <code>providerId</code>, so an unkeyed mock can’t be matched.</p>
+<hr>
+<h2 id="whats-not-a-test-driver">What’s NOT a test driver</h2>
+<p>The <code>firebase/auth</code> SDK has no equivalent of these methods, so they’re sandbox-only. The agent’s deployed <code>appSource</code> must never import the <code>sandbox</code> namespace. Keep it in the runner harness (the <code>code</code> artifact in playground), not in app code. The deploy adapter’s metafile gate rejects any prod bundle containing <code>@pyric/*</code>.</p>  </article> </main> <aside class="doc-toc" aria-label="On this page"> <h2 class="doc-toc-heading">On this page</h2> <ul> <li data-depth="2"> <a href="#sandboxsetuserauth-user--null">sandbox.setUser(auth, user | null)</a> </li><li data-depth="2"> <a href="#sandboxmocksigninresultauth-result">sandbox.mockSignInResult(auth, result)</a> </li><li data-depth="2"> <a href="#sandboxseedusersauth-users">sandbox.seedUsers(auth, users)</a> </li><li data-depth="2"> <a href="#errors">Errors</a> </li><li data-depth="2"> <a href="#whats-not-a-test-driver">What’s NOT a test driver</a> </li> </ul> </aside> </div> <script type="module">const a=document.querySelector("[data-api-symbol-filter]"),d=[...document.querySelectorAll("[data-api-symbol-group]")],n=document.querySelector("[data-api-symbol-empty]");a?.addEventListener("input",()=>{const t=a.value.trim().toLowerCase();let o=0;for(const i of d){let e=0;i.querySelectorAll("[data-api-symbol]").forEach(l=>{const r=!t||(l.dataset.apiSymbol??"").includes(t);l.hidden=!r,r&&e++}),i.hidden=e===0,o+=e}n&&(n.hidden=o>0)});</script> <script type="module">const s=new Map;document.querySelectorAll('.doc-toc a[href^="#"]').forEach(t=>s.set(decodeURIComponent(t.hash.slice(1)),t));if(s.size>0){const t=new Set,n=()=>{let o=null;for(const e of s.keys())if(t.has(e)){o=e;break}s.forEach((e,c)=>e.classList.toggle("active",c===o))},r=new IntersectionObserver(o=>{for(const e of o)e.isIntersecting?t.add(e.target.id):t.delete(e.target.id);n()},{rootMargin:"-72px 0px -60% 0px"});s.forEach((o,e)=>{const c=document.getElementById(e);c&&r.observe(c)})}</script> <script type="module">document.querySelector('.studio__nav [aria-current="page"]')?.scrollIntoView({block:"nearest",inline:"center"});</script> </body> </html>

package/dist/serve/docs-ui/docs/pyric-auth-reference-sandbox-test-driver.md

@@ -0,0 +1,108 @@
+# Sandbox test driver: `pyric/auth/sandbox.*`
+
+The `sandbox` export is `pyric/auth`'s test-driver namespace. It mirrors `pyric/firestore`'s `sandbox.setRules` / `sandbox.seedDocuments` pattern: methods exist only for sandbox-backed `Auth` handles and throw `failed-precondition` against a prod handle.
+
+```ts
+import { sandbox as authSandbox } from 'pyric/auth';
+```
+
+The import alias avoids the name collision with the local `const sandbox = initializeSandbox()` you'll typically have in scope.
+
+---
+
+## `sandbox.setUser(auth, user | null)`
+
+Force the current user. Bypasses email/password lookup, mock-result registry, and seeded DB. Pass `null` to sign out.
+
+```ts
+authSandbox.setUser(auth, {
+  uid: 'forced-uid',
+  email: 'forced@example.com',
+  displayName: 'Forced User',
+  isAnonymous: false,
+  getIdToken: async () => 'fake-token',
+  getIdTokenResult: async () => ({
+    token: 'fake-token',
+    claims: { role: 'admin' },
+    expirationTime: new Date(Date.now() + 3600_000).toISOString(),
+    issuedAtTime: new Date().toISOString(),
+    authTime: new Date().toISOString(),
+  }),
+});
+```
+
+Emits to `onAuthStateChanged` / `onIdTokenChanged` subscribers and writes through to `sandbox.currentUser`.
+
+---
+
+## `sandbox.mockSignInResult(auth, result)`
+
+Pre-stage the result that the next matching `signInWithPopup` / `signInWithCredential` call returns. The mock is **one-shot**, consumed by the next call with the matching `providerId`. Stage again for repeat tests.
+
+```ts
+authSandbox.mockSignInResult(auth, {
+  user: makeGoogleUser('uid-1', 'a@example.com'),
+  providerId: 'google.com',
+  operationType: 'signIn',
+});
+
+await signInWithPopup(auth, new GoogleAuthProvider());
+// → resolves to the mock, sets currentUser to mock.user
+
+await signInWithPopup(auth, new GoogleAuthProvider());
+// → throws auth/no-mock-configured
+```
+
+The provider passed to `signInWithPopup` must have a `providerId` that matches `result.providerId`.
+
+---
+
+## `sandbox.seedUsers(auth, users)`
+
+Bulk-load test users for email/password lookup. Each record:
+
+```ts
+interface SeedUser {
+  uid: string;
+  email: string;
+  password: string;
+  displayName?: string;
+  customClaims?: Record<string, unknown>;
+}
+```
+
+```ts
+authSandbox.seedUsers(auth, [
+  { uid: 'alice', email: 'alice@example.com', password: 'pw1' },
+  {
+    uid: 'admin',
+    email: 'admin@example.com',
+    password: 'pw2',
+    displayName: 'Admin User',
+    customClaims: { role: 'admin', tier: 5 },
+  },
+]);
+
+await signInWithEmailAndPassword(auth, 'admin@example.com', 'pw2');
+// auth.currentUser.uid === 'admin'
+// (await auth.currentUser.getIdTokenResult()).claims.role === 'admin'
+```
+
+`customClaims` flow through into `sandbox.currentUser.token`, which is what the Firestore rules engine reads as `request.auth.token.*`. This is the seam that makes rules tests with custom claims work end-to-end on sandbox.
+
+Email lookup is case-insensitive. Re-seeding the same uid overwrites.
+
+---
+
+## Errors
+
+These helpers require an `Auth` handle produced by `pyric/auth`. Production
+code remains on `firebase/auth` and does not load the sandbox driver.
+
+`sandbox.mockSignInResult` additionally throws `'invalid-argument'` if `result.providerId` is missing. The mock registry is keyed on `providerId`, so an unkeyed mock can't be matched.
+
+---
+
+## What's NOT a test driver
+
+The `firebase/auth` SDK has no equivalent of these methods, so they're sandbox-only. The agent's deployed `appSource` must never import the `sandbox` namespace. Keep it in the runner harness (the `code` artifact in playground), not in app code. The deploy adapter's metafile gate rejects any prod bundle containing `@pyric/*`.

package/dist/serve/docs-ui/docs/pyric-auth.md

@@ -0,0 +1,86 @@
+# `pyric/auth`
+
+Sandbox-only modular Web SDK Auth mirror. It implements `firebase/auth`'s tree-shakable shape (`getAuth`, `signInAnonymously`, `signInWithEmailAndPassword`, `onAuthStateChanged`, `signInWithPopup`, `GoogleAuthProvider`) in process, with no network.
+
+Application code keeps canonical `firebase/auth` imports. Pyric's Vite/import-map or Node register boundary swaps those imports to this mirror in sandbox mode; production installs no swap and continues loading Firebase itself. Direct `pyric/auth` imports always select sandbox behavior.
+
+## Install
+
+```bash
+bun add pyric firebase
+```
+
+`firebase` supplies the canonical production package. It is not a runtime dependency of the `pyric/auth` mirror.
+
+## A 30-second example
+
+Sandbox backend:
+
+```ts
+import { initializeSandbox } from 'pyric/sandbox';
+import { getAuth, signInWithEmailAndPassword, onAuthStateChanged, sandbox as authSandbox } from 'pyric/auth';
+
+const sandbox = initializeSandbox();
+const auth = getAuth(sandbox);
+
+authSandbox.seedUsers(auth, [
+  { uid: 'alice', email: 'alice@example.com', password: 'pw', customClaims: { role: 'admin' } },
+]);
+
+onAuthStateChanged(auth, (user) => {
+  console.log('current user:', user?.uid ?? '(signed out)');
+});
+
+await signInWithEmailAndPassword(auth, 'alice@example.com', 'pw');
+console.log(auth.currentUser?.uid); // 'alice'
+```
+
+Production uses the canonical package without a Pyric swap:
+
+```ts
+import { initializeApp } from 'firebase/app';
+import { getAuth, signInWithEmailAndPassword } from 'firebase/auth';
+
+const app = initializeApp({ /* your Firebase config */ });
+const auth = getAuth(app);
+
+await signInWithEmailAndPassword(auth, 'alice@example.com', 'pw');
+```
+
+## What's in v0
+
+The deliberately-minimal surface covers everything an `appSource` likely needs:
+
+- `getAuth(target)`: default `FirebaseApp`, explicit `FirebaseApp`, and direct `Sandbox` overloads
+- `connectAuthEmulator(auth, url, options?)`: accepted no-op because the mirror is already a sandbox
+- `signInAnonymously` / `signInWithEmailAndPassword` / `createUserWithEmailAndPassword` / `signOut`
+- `signInWithPopup(auth, provider)` / `signInWithCredential(auth, credential)`: sandbox returns pre-staged mock results
+- `setPersistence` + `inMemoryPersistence` / `browserSessionPersistence` / `browserLocalPersistence`
+- `onAuthStateChanged` / `onIdTokenChanged`
+- Provider classes: `GoogleAuthProvider`, `EmailAuthProvider`, `FacebookAuthProvider`, `GithubAuthProvider`, `OAuthProvider`
+- Sandbox-only test driver: `sandbox.setUser`, `sandbox.mockSignInResult`, `sandbox.seedUsers`
+
+See [`docs/reference/feature-matrix.md`](../pyric-auth-reference-feature-matrix/) for the full feature matrix and the explicit v0 deny-list.
+
+## What's out (v0)
+
+Unsupported symbols fail to resolve only in sandbox builds where package resolution selects this mirror. Production remains on the complete `firebase/auth` package. The current list is maintained in the feature matrix.
+
+## State model: sandbox-wide `currentUser`
+
+`pyric/auth`'s sandbox backend writes through to `sandbox.currentUser`. Every sandbox now carries that field plus an `onCurrentUserChanged` event. This is the integration seam: a future `getFirestore(sandbox)` overload reads `sandbox.currentUser` per-call so Firestore rules evaluate against the live auth state without re-binding handles.
+
+Today, `pyric/auth` writes to the field; reading from other service handles is the next follow-up.
+
+## What's next (deferred follow-ups)
+
+- **`getFirestore(sandbox)` per-call identity read.** Add a `(sandbox)` overload on `pyric/firestore`'s `getFirestore` that reads `sandbox.currentUser` for each op. Lets agent code call `getFirestore(sandbox)` once and have Firestore see auth changes from `pyric/auth`'s sign-in flows automatically.
+- **Agent system-prompt update.** Drop the "no `firebase/auth` in `appSource`" rule and document the v0 deny-list as the new boundary.
+
+## Position in the Pyric stack
+
+`pyric/auth` is the **modular-shape auth adapter**, sibling to `pyric/firestore`. Both run on top of `pyric/sandbox` and share the same `currentUser` bridge.
+
+## Licence
+
+Same as the parent workspace.