pyric 0.0.1 → 0.1.0-alpha.7

package/README.md

@@ -1,3 +1,54 @@
 # pyric
 
-Reserved.
+Firebase-shaped client SDK adapters with a swappable in-process sandbox
+backend, plus Pyric's rules tooling and sandbox runtime.
+
+> **Alpha.** This package is an early alpha. The Firebase-mirrored subpaths
+> (`pyric/app`, `pyric/firestore`, `pyric/auth`, `pyric/database`,
+> `pyric/storage`) are best-effort mirror contracts of the modular Web SDK —
+> not guaranteed parity. Non-mirrored exports (e.g. `pyric/sandbox/internal`,
+> the rules tooling subpaths) are experimental public-alpha surfaces that may
+> change without notice.
+
+`pyric` mirrors Firebase's modular Web SDK subpaths:
+
+| Subpath | Surface |
+|---|---|
+| `pyric/app` | `initializeApp`, `PyricApp`, sandbox/prod app tags |
+| `pyric/firestore` | Firestore modular SDK mirror plus data/inspect tool factories |
+| `pyric/auth` | Auth modular SDK mirror plus sandbox auth helpers |
+| `pyric/database` | Realtime Database modular SDK mirror plus admin tools |
+| `pyric/storage` | Storage modular SDK mirror plus storage admin tools |
+| `pyric/rules` | Firestore rules parser, linter, validator, simulator, stdlib tooling |
+| `pyric/rules/node` | Node-only rules module resolution helpers |
+| `pyric/rules/rtdb` | Realtime Database rules facade: mapper, parser/linter, simulator, deploy/read rule tool factory |
+| `pyric/rules/rtdb-constraints` | Realtime Database rules constraint helpers |
+| `pyric/sandbox` | In-process Firebase sandbox runtime |
+| `pyric/sandbox/internal` | Adapter-only internal protocol surface |
+| `pyric/sandbox/admin-compat` | Chainable admin-compat Firestore wrapper over the sandbox |
+
+## Example
+
+```ts
+import { initializeApp } from 'pyric/app';
+import { initializeSandbox } from 'pyric/sandbox';
+import { getFirestore, collection, getDocs } from 'pyric/firestore';
+
+const app = initializeApp({ sandbox: initializeSandbox() });
+const db = getFirestore(app);
+
+const snap = await getDocs(collection(db, 'posts'));
+```
+
+To target production Firebase instead, pass normal Firebase app options to
+`initializeApp`. Downstream Firestore/Auth/Database/Storage calls keep the same
+shape.
+
+## Docs
+
+- [Firestore](docs/firestore/)
+- [Auth](docs/auth/)
+- [Realtime Database](docs/database/)
+- [Storage](docs/storage/)
+- [Rules](docs/rules/)
+- [Sandbox](docs/sandbox/)

package/dist/app/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `pyric/app` — Phase 3 initializeApp surface (ADR-001 D5).
+ *
+ * Mirror shape: at cutover this becomes `pyric/app` and is the single
+ * entry point where the sandbox-vs-prod choice is made. Every other
+ * subpath (`getFirestore(app)`, `getAuth(app)`, `getDatabase(app)`,
+ * `getStorage(app)`) is backend-agnostic — they inspect the `PyricApp`
+ * handle for the brand and route accordingly.
+ *
+ * Current shadow scope:
+ *   - `initializeApp({ sandbox })` — sandbox-backed app handle (live).
+ *   - `initializeApp(firebaseConfig)` — prod-backed app handle (live).
+ *   - Adapter dispatch (the `getFirestore(app)` etc. wrappers) is
+ *     **deferred to cutover**: the adapter subpaths still re-export
+ *     from `pyric/firestore` / `pyric/auth` / etc., which take their
+ *     own per-backend handles. Implementing the wrap requires hiding
+ *     the existing `getFirestore` overloads behind the unified
+ *     handle, which lands cleanly when source folds into
+ *     `packages/pyric/src/*` and the existing entry points go away.
+ *
+ * The handle shape is finalized here so consumers can begin coding
+ * against it (and stubs throw on the deferred call).
+ */
+import type { Sandbox } from 'pyric/sandbox';
+import { type FirebaseApp, type FirebaseOptions } from 'firebase/app';
+/**
+ * Brand symbol on every PyricApp. Adapter dispatch reads this to
+ * route between sandbox and prod backends. Mirrors the
+ * `TARGET_SYMBOL` pattern that `pyric/firestore` uses internally.
+ */
+export declare const APP_TARGET: unique symbol;
+export type PyricAppTarget = 'sandbox' | 'prod';
+export interface SandboxApp {
+    readonly [APP_TARGET]: 'sandbox';
+    readonly sandbox: Sandbox;
+}
+export interface ProdApp {
+    readonly [APP_TARGET]: 'prod';
+    readonly firebaseApp: FirebaseApp;
+}
+/**
+ * The unified app handle. Carries the backend selection so every
+ * adapter can dispatch from a single argument.
+ */
+export type PyricApp = SandboxApp | ProdApp;
+/**
+ * The two accepted config shapes. The discriminator is the presence
+ * of a `sandbox` field — sandbox handles always carry one, Firebase
+ * options never do.
+ */
+export type InitializeAppConfig = {
+    sandbox: Sandbox;
+} | FirebaseOptions;
+/**
+ * Initialize a Pyric app.
+ *
+ * @example
+ * ```ts
+ * // Sandbox-backed (tests, agent loops, playground)
+ * import { initializeApp } from 'pyric/app';
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * const app = initializeApp({ sandbox: initializeSandbox() });
+ *
+ * // Prod-backed (drop-in for existing Firebase code)
+ * const app = initializeApp({
+ *   apiKey: '...', projectId: '...', // ...standard FirebaseOptions
+ * });
+ * ```
+ */
+export declare function initializeApp(config: InitializeAppConfig): PyricApp;
+/**
+ * Type guard for the sandbox app handle. Adapter dispatch sites use
+ * this to route to the sandbox-backed `@pyric/*` implementation.
+ */
+export declare function isSandboxApp(app: PyricApp): app is SandboxApp;
+/**
+ * Type guard for the prod app handle. Adapter dispatch sites use
+ * this to route to the `firebase/*` modular SDK.
+ */
+export declare function isProdApp(app: PyricApp): app is ProdApp;
+//# sourceMappingURL=index.d.ts.map

package/dist/app/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAA0C,KAAK,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9G;;;;GAIG;AACH,eAAO,MAAM,UAAU,eAAiC,CAAC;AAEzD,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;AAE5C;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,eAAe,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,QAAQ,CAanE;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,GAAG,IAAI,UAAU,CAE7D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,GAAG,IAAI,OAAO,CAEvD"}

package/dist/app/index.js

@@ -0,0 +1,78 @@
+/**
+ * `pyric/app` — Phase 3 initializeApp surface (ADR-001 D5).
+ *
+ * Mirror shape: at cutover this becomes `pyric/app` and is the single
+ * entry point where the sandbox-vs-prod choice is made. Every other
+ * subpath (`getFirestore(app)`, `getAuth(app)`, `getDatabase(app)`,
+ * `getStorage(app)`) is backend-agnostic — they inspect the `PyricApp`
+ * handle for the brand and route accordingly.
+ *
+ * Current shadow scope:
+ *   - `initializeApp({ sandbox })` — sandbox-backed app handle (live).
+ *   - `initializeApp(firebaseConfig)` — prod-backed app handle (live).
+ *   - Adapter dispatch (the `getFirestore(app)` etc. wrappers) is
+ *     **deferred to cutover**: the adapter subpaths still re-export
+ *     from `pyric/firestore` / `pyric/auth` / etc., which take their
+ *     own per-backend handles. Implementing the wrap requires hiding
+ *     the existing `getFirestore` overloads behind the unified
+ *     handle, which lands cleanly when source folds into
+ *     `packages/pyric/src/*` and the existing entry points go away.
+ *
+ * The handle shape is finalized here so consumers can begin coding
+ * against it (and stubs throw on the deferred call).
+ */
+import { initializeApp as initializeFirebaseApp } from 'firebase/app';
+/**
+ * Brand symbol on every PyricApp. Adapter dispatch reads this to
+ * route between sandbox and prod backends. Mirrors the
+ * `TARGET_SYMBOL` pattern that `pyric/firestore` uses internally.
+ */
+export const APP_TARGET = Symbol.for('pyric.app.target');
+/**
+ * Initialize a Pyric app.
+ *
+ * @example
+ * ```ts
+ * // Sandbox-backed (tests, agent loops, playground)
+ * import { initializeApp } from 'pyric/app';
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * const app = initializeApp({ sandbox: initializeSandbox() });
+ *
+ * // Prod-backed (drop-in for existing Firebase code)
+ * const app = initializeApp({
+ *   apiKey: '...', projectId: '...', // ...standard FirebaseOptions
+ * });
+ * ```
+ */
+export function initializeApp(config) {
+    if (isSandboxConfig(config)) {
+        return {
+            [APP_TARGET]: 'sandbox',
+            sandbox: config.sandbox,
+        };
+    }
+    // Prod path: delegate to firebase/app initializeApp.
+    const firebaseApp = initializeFirebaseApp(config);
+    return {
+        [APP_TARGET]: 'prod',
+        firebaseApp,
+    };
+}
+function isSandboxConfig(config) {
+    return typeof config === 'object' && config !== null && 'sandbox' in config;
+}
+/**
+ * Type guard for the sandbox app handle. Adapter dispatch sites use
+ * this to route to the sandbox-backed `@pyric/*` implementation.
+ */
+export function isSandboxApp(app) {
+    return app[APP_TARGET] === 'sandbox';
+}
+/**
+ * Type guard for the prod app handle. Adapter dispatch sites use
+ * this to route to the `firebase/*` modular SDK.
+ */
+export function isProdApp(app) {
+    return app[APP_TARGET] === 'prod';
+}
+//# sourceMappingURL=index.js.map

package/dist/app/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,aAAa,IAAI,qBAAqB,EAA0C,MAAM,cAAc,CAAC;AAE9G;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;AA2BzD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,MAA2B;IACvD,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,CAAC,UAAU,CAAC,EAAE,SAAS;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,CAAC;IACJ,CAAC;IACD,qDAAqD;IACrD,MAAM,WAAW,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO;QACL,CAAC,UAAU,CAAC,EAAE,MAAM;QACpB,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,MAA2B;IAClD,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,SAAS,IAAI,MAAM,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAa;IACxC,OAAO,GAAG,CAAC,UAAU,CAAC,KAAK,SAAS,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,GAAa;IACrC,OAAO,GAAG,CAAC,UAAU,CAAC,KAAK,MAAM,CAAC;AACpC,CAAC"}

package/dist/auth/index.d.ts

@@ -0,0 +1,346 @@
+/**
+ * `pyric/auth` — modular Web-SDK Auth adapter for the Pyric
+ * sandbox.
+ *
+ * Mirrors `firebase/auth`'s tree-shakable free-function surface
+ * (`getAuth`, `signInAnonymously`, `signInWithEmailAndPassword`,
+ * `onAuthStateChanged`, `signInWithPopup`, `GoogleAuthProvider`, …)
+ * with two backends picked at init:
+ *
+ *   - **Sandbox target** — in-memory user DB + listener registry,
+ *     drives `sandbox.currentUser` so service factories (a future
+ *     `getFirestore(sandbox)` overload, follow-up PR) see identity
+ *     changes without re-binding.
+ *   - **Prod target** — delegates straight to `firebase/auth`.
+ *
+ * Same call surface across both. Agent code that writes against the
+ * sandbox during iteration runs unmodified against prod at deploy.
+ *
+ * Dual-target dispatch follows the same pattern as `pyric/firestore`:
+ *   - {@link TARGET_SYMBOL} brands every {@link Auth} handle.
+ *   - {@link targetOf} (internal) reads it and switches on
+ *     `target.kind`.
+ *
+ * Sandbox-only test driver lives under {@link sandbox}, mirroring
+ * `pyric/firestore`'s `sandbox.setRules` etc. — each method throws
+ * `failed-precondition` if called against a prod-backed handle.
+ *
+ * v0 scope is deliberately minimal. The deny-list is documented in
+ * `docs/reference/feature-matrix.md`; agent `appSource` that imports
+ * any of those will fail to bundle once the playground's
+ * `firebase/auth` → `pyric/auth` alias swap lands.
+ */
+import { type Sandbox } from 'pyric/sandbox';
+import type { FirebaseApp } from 'firebase/app';
+import { type PyricApp } from 'pyric/app';
+import { type AuthUserRecord, type CreateUserRequest, type MintSessionRequest, type MintedSession, type SeedUser, type SignInIdentitySpec, type UpdateUserRequest } from './sandbox-backend.js';
+import { type Auth, type AuthFlowRequest, type AuthFlowResolver, type AuthObserver, type IdTokenResult, type Persistence, type Unsubscribe, type User, type UserCredential, type UserInfo, type AuthCredential } from './types.js';
+import type { AuthProvider } from './providers.js';
+export type { Auth, AuthCredential, AuthFlowRequest, AuthFlowResolver, AuthObserver, IdTokenResult, Persistence, Unsubscribe, User, UserCredential, UserInfo, };
+export type { AuthProvider } from './providers.js';
+export type { AuthUserRecord, CreateUserRequest, MintSessionRequest, MintedSession, ProviderUserInfo, SeedUser, SignInIdentitySpec, UpdateUserRequest, } from './sandbox-backend.js';
+export { TARGET_SYMBOL } from './types.js';
+export { EmailAuthProvider, FacebookAuthProvider, GithubAuthProvider, GoogleAuthProvider, OAuthProvider, FEDERATED_PROVIDER_IDS, type FederatedProviderId, } from './providers.js';
+export declare const inMemoryPersistence: Persistence;
+export declare const browserSessionPersistence: Persistence;
+export declare const browserLocalPersistence: Persistence;
+/**
+ * Construct an {@link Auth} handle. Two overloads:
+ *   - `getAuth(sandbox)` — sandbox-backed.
+ *   - `getAuth(app)` — prod-backed; delegates to
+ *     `firebase/auth.getAuth(app)`.
+ *
+ * Idempotent on both targets — calling twice for the same input
+ * returns the same handle.
+ *
+ * @example
+ * ```ts
+ * // Sandbox.
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * import { getAuth, signInAnonymously } from 'pyric/auth';
+ * const sandbox = initializeSandbox();
+ * const auth = getAuth(sandbox);
+ * await signInAnonymously(auth);
+ *
+ * // Prod.
+ * import { initializeApp } from 'firebase/app';
+ * import { getAuth } from 'pyric/auth';
+ * const app = initializeApp(userProjectConfig);
+ * const auth = getAuth(app);
+ * ```
+ */
+export declare function getAuth(sandbox: Sandbox): Auth;
+export declare function getAuth(app: FirebaseApp): Auth;
+export declare function getAuth(app: PyricApp): Auth;
+/**
+ * `connectAuthEmulator(auth, url, options?)` — on sandbox handles
+ * this is a no-op (the sandbox IS the emulator); on prod it
+ * delegates straight to `firebase/auth.connectAuthEmulator`.
+ *
+ * Same signature as upstream so consumer code that calls this at
+ * init time works against both backends unchanged.
+ */
+export declare function connectAuthEmulator(auth: Auth, url: string, options?: {
+    disableWarnings?: boolean;
+}): void;
+export declare function signInAnonymously(auth: Auth): Promise<UserCredential>;
+export declare function signInWithEmailAndPassword(auth: Auth, email: string, password: string): Promise<UserCredential>;
+export declare function createUserWithEmailAndPassword(auth: Auth, email: string, password: string): Promise<UserCredential>;
+export declare function signOut(auth: Auth): Promise<void>;
+export declare function setPersistence(auth: Auth, persistence: Persistence): Promise<void>;
+/**
+ * The `resolver` argument is sandbox-only: on a prod-backed handle the
+ * call delegates to `firebase/auth`, which uses its own platform default
+ * (browser) resolver, and this argument is ignored.
+ */
+export declare function signInWithPopup(auth: Auth, provider: AuthProvider, resolver?: AuthFlowResolver): Promise<UserCredential>;
+/**
+ * The `resolver` argument is sandbox-only — see {@link signInWithPopup}.
+ */
+export declare function signInWithRedirect(auth: Auth, provider: AuthProvider, resolver?: AuthFlowResolver): Promise<void>;
+export declare function getRedirectResult(auth: Auth, _resolver?: AuthFlowResolver): Promise<UserCredential | null>;
+export declare function signInWithCredential(auth: Auth, credential: AuthCredential): Promise<UserCredential>;
+export declare function onAuthStateChanged(auth: Auth, observer: AuthObserver): Unsubscribe;
+export declare function onIdTokenChanged(auth: Auth, observer: AuthObserver): Unsubscribe;
+/**
+ * Top-level mirror of `firebase/auth`'s `getIdToken(user)`. Delegates
+ * to the method on the user handle, so it works on both backends.
+ *
+ * Parity provenance: W1.5 grid (2026-06-10) — generated apps import
+ * the modular free function, and its absence failed every render of
+ * the claims-driven fixtures.
+ */
+export declare function getIdToken(user: User, forceRefresh?: boolean): Promise<string>;
+/** Top-level mirror of `firebase/auth`'s `getIdTokenResult(user)`. */
+export declare function getIdTokenResult(user: User, forceRefresh?: boolean): Promise<IdTokenResult>;
+/**
+ * Top-level mirror of `firebase/auth`'s `updateProfile(user, profile)`.
+ * Updates the signed-in user's `displayName` / `photoURL` — pass `null` to
+ * clear a field, omit it to leave it untouched. Mutates the user object in
+ * place (held references, including `auth.currentUser`, reflect the change).
+ *
+ * Dispatches through the hidden {@link USER_INTERNAL} hook the backend stamps
+ * on every `User`, so it routes correctly WITHOUT an `auth` handle — matching
+ * upstream's user-only signature. Works on both sandbox and prod targets.
+ *
+ * Per `firebase/auth`, this does NOT fire `onAuthStateChanged` /
+ * `onIdTokenChanged`.
+ */
+export declare function updateProfile(user: User, profile: {
+    displayName?: string | null;
+    photoURL?: string | null;
+}): Promise<void>;
+/**
+ * Sandbox-only lifecycle / test-driver surface. Throws
+ * `failed-precondition` on prod-backed handles — mirrors the
+ * `pyric/firestore` `sandbox.*` pattern.
+ *
+ * **Naming note:** the `sandbox` export name collides with the
+ * common `const sandbox = initializeSandbox()` local. Alias on
+ * import if both are in scope:
+ *
+ * ```ts
+ * import { sandbox as authSandbox } from 'pyric/auth';
+ * import { initializeSandbox } from 'pyric/sandbox';
+ * const sandbox = initializeSandbox();
+ * const auth = getAuth(sandbox);
+ * authSandbox.seedUsers(auth, […]);
+ * ```
+ */
+export declare const sandbox: {
+    /**
+     * Force the current user (and emit to listeners). Pass `null` to
+     * sign out. Bypasses the email/password lookup — useful for
+     * driving auth state directly in tests without seeding.
+     */
+    setUser(auth: Auth, user: User | null): void;
+    /**
+     * Install the popup/redirect resolver — the analog of browser
+     * `getAuth` wiring `browserPopupRedirectResolver`. The host
+     * (playground) sets this once; `signInWithPopup` / `signInWithRedirect`
+     * then delegate the experience to it. Pass `null` to clear.
+     *
+     * Precedence at sign-in time: a per-call resolver arg wins, then this
+     * injected one, then a one-shot `mockSignInResult`, else
+     * `auth/argument-error`.
+     */
+    setAuthFlowResolver(auth: Auth, resolver: AuthFlowResolver | null): void;
+    /**
+     * Snapshot every known identity (seeded + created), for a host
+     * account-picker UI. Sandbox-only — no `firebase/auth` equivalent.
+     */
+    listIdentities(auth: Auth): {
+        uid: string;
+        email: string | null;
+        displayName: string | null;
+        providerId: string;
+        providerUserInfo: import("./sandbox-backend.js").ProviderUserInfo[];
+        isAnonymous: boolean;
+        customClaims: Record<string, unknown>;
+    }[];
+    /**
+     * Mint a sign-in credential for a host-driven flow — the account
+     * picker's "pick existing" (`{providerId, uid}`) and "add account"
+     * (`{providerId, spec}`) actions. Token + claims synthesis is
+     * backend-owned (routed through the same token cache as every
+     * other sign-in), replacing host-synthesized token strings.
+     *
+     * The credential does NOT sign anyone in — resolve the pending
+     * `AuthFlowResolver` promise with it and the in-flight
+     * `signInWithPopup` / `signInWithRedirect` completes the sign-in.
+     */
+    createSignInCredential(auth: Auth, request: {
+        providerId: string;
+        uid: string;
+    } | {
+        providerId: string;
+        spec: SignInIdentitySpec;
+    }): UserCredential;
+    /**
+     * Pre-stage the result that the next `signInWithPopup` /
+     * `signInWithCredential` call for the matching `providerId`
+     * returns. The one-shot tier of the resolver precedence (used when no
+     * resolver is injected) — consumed by the next sign-in call; stage
+     * again for repeat tests.
+     */
+    mockSignInResult(auth: Auth, result: UserCredential): void;
+    /**
+     * Bulk-load test users for email/password lookup. Idempotent for
+     * a given uid+email — re-seeding the same uid overwrites.
+     */
+    seedUsers(auth: Auth, users: ReadonlyArray<SeedUser>): void;
+    /**
+     * Export the user DB in the exact shape {@link sandbox.seedUsers}
+     * accepts — `exportUsers` → `seedUsers` round-trips losslessly (the
+     * persistence substrate, the design rationale section 3c).
+     * Provider-flow identities without a password export with a documented
+     * sentinel; anonymous users are not exported (ephemeral by design).
+     */
+    exportUsers(auth: Auth): SeedUser[];
+    /**
+     * Re-establish a signed-in session for an EXISTING identity — the
+     * substrate behind web-storage session persistence at the host layer.
+     * Fires auth-state listeners like a real restored session. Throws
+     * `auth/user-not-found` for unknown uids, `auth/user-disabled` for
+     * disabled accounts (a restore is a sign-in).
+     */
+    restoreSession(auth: Auth, uid: string): User;
+    /**
+     * Mint a session identity WITHOUT signing it in globally — the
+     * substrate for **per-connection identity** at the serve layer
+     * (issue #754): one shared sandbox, N connections (tabs / clients),
+     * each with its own authenticated session. Performs a real sign-in's
+     * bookkeeping (provider record, `lastLoginAt`, a fresh token, the
+     * `sign_in` activity event) but leaves `auth.currentUser`, the
+     * auth-state listeners, and session persistence untouched.
+     *
+     * Returns the `User` plus the `AuthState` its data contexts should
+     * carry — `getFirestore(sandbox.withAuth(session.state))` evaluates
+     * rules exactly as a real sign-in would (`request.auth.uid` +
+     * custom claims on `request.auth.token`).
+     *
+     * This is an AUTHENTIC session (credentials are validated / an
+     * identity is really minted) — distinct from the rules-debugging
+     * impersonation lens, which asserts a uid without authenticating.
+     */
+    mintSession(auth: Auth, request: MintSessionRequest): MintedSession;
+    /**
+     * Every user in the sandbox user DB (seeded, created,
+     * signed-in-via-provider, anonymous) as {@link AuthUserRecord}s.
+     * Snapshot — subscribe to changes via {@link sandbox.subscribeUsers}.
+     */
+    listUsers(auth: Auth): AuthUserRecord[];
+    /**
+     * Create a user without signing them in (admin semantics — the
+     * client-mirror `createUserWithEmailAndPassword` is the
+     * signs-you-in variant). Throws `auth/uid-already-exists`,
+     * `auth/email-already-in-use`, `auth/invalid-email`,
+     * `auth/weak-password` on bad input.
+     */
+    createUser(auth: Auth, request: CreateUserRequest): AuthUserRecord;
+    /**
+     * Update a user. `undefined` fields untouched; `customClaims`
+     * replaces the whole map; setting `disabled: true` blocks future
+     * sign-ins with `auth/user-disabled` (active sessions continue —
+     * same as prod until token revocation).
+     */
+    updateUser(auth: Auth, uid: string, update: UpdateUserRequest): AuthUserRecord;
+    /**
+     * Update a user's PROFILE (`displayName` / `photoURL`) by uid — the
+     * backend behind the served worker path's `updateProfile`. `undefined`
+     * fields untouched; `null` clears. Returns the refreshed record; throws
+     * `auth/user-not-found` for an unknown uid. (The client-facing
+     * `updateProfile(user, …)` free function is the app-code surface; this is
+     * the by-uid op the SharedWorker host calls.)
+     */
+    updateProfile(auth: Auth, uid: string, profile: {
+        displayName?: string | null;
+        photoURL?: string | null;
+    }): AuthUserRecord;
+    /** Delete a user record. Throws `auth/user-not-found` for unknown
+     *  uids. Active sessions are not terminated (prod parity). */
+    deleteUser(auth: Auth, uid: string): void;
+    /** Drop every user record — the emulator's "delete all accounts". */
+    clearUsers(auth: Auth): void;
+    /**
+     * Subscribe to user-DB mutations (seed / create / update / delete /
+     * clear / provider links / lastLoginAt bumps). Coarse contract: no
+     * payload, no initial fire — re-list via {@link sandbox.listUsers}
+     * in the callback.
+     */
+    subscribeUsers(auth: Auth, callback: () => void): Unsubscribe;
+    /**
+     * Every provider this sandbox has an explicit enablement for —
+     * seeded defaults (`password`, `anonymous` — both `true`) plus
+     * anything toggled via {@link sandbox.setAuthProviderConfig}. Every
+     * OTHER providerId (`google.com`, a custom OAuth id, …) is disabled
+     * until explicitly enabled.
+     */
+    getAuthProviderConfig(auth: Auth): Array<{
+        providerId: string;
+        enabled: boolean;
+    }>;
+    /**
+     * Enable/disable a sign-in provider. Gated at every provider entry
+     * point of the ENFORCING backend (`signInWithPopup`/`signInWithRedirect`,
+     * `signInWithCredential`, `createUserWithEmailAndPassword`/
+     * `signInWithEmailAndPassword` for `'password'`, `signInAnonymously`
+     * for `'anonymous'`) — disabling a provider makes the matching sign-in
+     * call throw real Firebase's `auth/operation-not-allowed`, exactly
+     * like flipping the toggle off in the real console. Survives
+     * `enablePersistence` round-trips (rides the `auth` service's
+     * snapshot alongside the user DB). A backend whose enforcement is
+     * delegated ({@link sandbox.delegateProviderEnforcement}) does NOT
+     * gate locally — the remote authority it fronts does.
+     */
+    setAuthProviderConfig(auth: Auth, providerId: string, enabled: boolean): void;
+    /**
+     * Assert a provider is enabled — throws `auth/operation-not-allowed`
+     * (the exact gate every provider entry point uses) when it is off.
+     * For hosts that ARE the enforcement authority for identities
+     * resolved elsewhere: the served SharedWorker calls this before
+     * accepting a page-resolved popup/redirect identity
+     * (`auth.acceptIdentity`), so Studio's provider toggles gate served
+     * OAuth sign-in at the shared backend, not at each page's UI shim.
+     */
+    assertAuthProviderEnabled(auth: Auth, providerId: string): void;
+    /**
+     * Delegate (or reclaim) THIS handle's provider-enablement gate to a
+     * remote authority. Serve-layer wiring: in SharedWorker mode the
+     * page-local sandbox is only the UI vehicle for popup/redirect
+     * resolution — the worker's `auth.acceptIdentity` gate (against the
+     * worker's own, undelegated config) is the real toggle enforcement —
+     * so the served `firebase/auth` entry sets `true` on the in-page
+     * handle to let the picker open regardless of local defaults. Do NOT
+     * set this on a backend that is itself the authority.
+     */
+    delegateProviderEnforcement(auth: Auth, delegated: boolean): void;
+    /**
+     * Subscribe to provider-config mutations. Coarse contract: no
+     * payload, no initial fire — re-read via
+     * {@link sandbox.getAuthProviderConfig} in the callback (same shape
+     * as {@link sandbox.subscribeUsers}).
+     */
+    subscribeAuthProviderConfig(auth: Auth, callback: () => void): Unsubscribe;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"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"}