pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/src/auth/seed-user.ts

@@ -0,0 +1,38 @@
+import type { ProviderUserInfo } from './sandbox-backend-types.js';
+
+/** Seed record shared by account import and persistence validation. */
+export interface SeedUser {
+  uid: string;
+  /** Account timestamps retained by export, checkpoints, and host restart. */
+  createdAt?: string;
+  lastLoginAt?: string | null;
+  /** Absent for an anonymous account (`providerId: 'anonymous'`), which has
+   *  no address to sign in with. Required for every other provider. */
+  email?: string;
+  /** Absent when the account has no password (anonymous or provider-only). */
+  password?: string;
+  displayName?: string;
+  customClaims?: Record<string, unknown>;
+  /** Profile photo URL, mirroring the stored record's `photoUrl`.
+   *  Omitted for records that carry none. */
+  photoUrl?: string;
+  /** Phone number on the record. Omitted for records that carry none. */
+  phoneNumber?: string;
+  /** Whether the address on the record is verified. Omitted when false
+   *  — the seeded default. */
+  emailVerified?: boolean;
+  /** Whether the account rejects every sign-in with
+   *  `auth/user-disabled`. Omitted when false — the seeded default. */
+  disabled?: boolean;
+  /** Identity Platform tenant the record belongs to. Omitted for
+   *  untenanted identities. Absent is the seeded default. */
+  tenantId?: string;
+  /** Originating provider for this identity (e.g. `'google.com'`).
+   *  Defaults to `'password'` — the natural provider for a record
+   *  seeded with an email + password. A host seeding popup-flow
+   *  identities passes the real provider so `listIdentities` /
+   *  `IdTokenResult.signInProvider` label them correctly. */
+  providerId?: string;
+  /** Complete linked-provider list. Older seeds use providerId alone. */
+  providerUserInfo?: ProviderUserInfo[];
+}

package/src/auth/tokens.ts

@@ -7,7 +7,7 @@
 import { makeAuthError } from './auth-errors.js';
 import { requireSandboxTarget } from './action-codes.js';
 import { targetOf } from './target.js';
-import type { Auth, UserCredential } from './types.js';
+import type { Auth, User, UserCredential } from './types.js';
 
 // ─── signInWithCustomToken ────────────────────────────────────────────
 
@@ -45,10 +45,18 @@ export async function signInWithCustomToken(
   auth: Auth,
   customToken: string,
 ): Promise<UserCredential> {
-  const t = targetOf(auth);
-  const target = t;
+  const { user, isNewUser } = resolveCustomTokenIdentity(auth, customToken);
+  await targetOf(auth).backend.transitionCurrentUser(user, 'custom');
+  return { user, providerId: null, operationType: 'signIn',
+    _additionalUserInfo: { isNewUser, profile: {}, providerId: null } };
+}
+
+/** Resolve a custom-token account without changing the backend's global session. */
+export function resolveCustomTokenIdentity(auth: Auth, customToken: string): { user: User; isNewUser: boolean } {
+  const target = targetOf(auth);
   const payload = decodeCustomToken(customToken);
-  if (!payload) {
+  const invalidToken = payload === null;
+  if (invalidToken) {
     throw makeAuthError(
       'auth/invalid-custom-token',
       'The custom token format is incorrect. Please check the documentation.',
@@ -57,32 +65,27 @@ export async function signInWithCustomToken(
 
   const existing = target.backend.findByUid(payload.uid);
   const isNewUser = existing === undefined;
-  if (existing) {
+  const hasExistingUser = !isNewUser;
+  const hasClaims = payload.claims !== undefined;
+  if (hasExistingUser) {
     // A custom token re-asserts claims on every exchange — prod merges the
     // token's claims into the session, so a claims change on the backend
     // takes effect at the next sign-in without touching the user record.
-    if (payload.claims) {
+    if (hasClaims) {
       target.backend.updateUser(payload.uid, { customClaims: payload.claims });
     }
   } else {
-    target.backend.createUser({
-      uid: payload.uid,
-      ...(payload.claims ? { customClaims: payload.claims } : {}),
-    });
+    const identity = hasClaims ? { uid: payload.uid, customClaims: payload.claims } : { uid: payload.uid };
+    target.backend.createUser(identity);
   }
   const stored = target.backend.findByUid(payload.uid);
-  if (!stored) {
+  const missingIdentity = stored === undefined;
+  if (missingIdentity) {
     throw makeAuthError('auth/invalid-custom-token', 'signInWithCustomToken: could not materialize the identity.');
   }
   target.backend.assertSignInAllowed(stored.uid);
   const user = target.backend.buildUserFromStored(stored);
-  await target.backend.transitionCurrentUser(user, 'custom');
-  return {
-    user,
-    providerId: null,
-    operationType: 'signIn',
-    _additionalUserInfo: { isNewUser, profile: {}, providerId: null },
-  };
+  return { user, isNewUser };
 }
 
 /** Read `{uid, claims}` out of a custom token, or `null` if it carries

package/src/auth/types.ts

@@ -80,7 +80,7 @@ export interface UserInfo {
  * containing the fields the sandbox can synthesize faithfully.
  *
  * The heavier `User` surface the sandbox does NOT model (`metadata`,
- * `refreshToken`, `tenantId`, `reload()`, `delete()`, `toJSON()`) is
+ * `refreshToken`, `reload()`, `delete()`, `toJSON()`) is
  * intentionally not synthesized; its absence remains visible in the public
  * type census rather than being hidden behind placeholder values.
  */
@@ -106,6 +106,12 @@ export interface User {
   readonly phoneNumber?: string | null;
   /** True iff this user signed in via `signInAnonymously`. */
   readonly isAnonymous: boolean;
+  /** Identity Platform tenant this user authenticated under, or `null` for
+   *  the project-level pool. Set from {@link Auth.tenantId} at sign-in;
+   *  rules see the same value as `request.auth.token.firebase.tenant`.
+   *  Optional on the type so host helpers that synthesize a partial `User`
+   *  aren't forced to specify it; the sandbox backend always populates it. */
+  readonly tenantId?: string | null;
   /** The aggregate provider id (`'firebase'` for a real `User`;
    *  per-provider ids live in {@link providerData}). Optional on the
    *  type; always populated by the sandbox backend. */
@@ -286,6 +292,12 @@ export interface Auth {
   /** Currently signed-in user, or `null`. Snapshot value — read
    *  through `onAuthStateChanged` for live updates. */
   readonly currentUser: User | null;
+  /** Identity Platform tenant that subsequent sign-ins authenticate
+   *  against, or `null` for the project-level pool. Assign before calling a
+   *  sign-in function: the resulting {@link User} carries the same value on
+   *  `tenantId`, and rules evaluate the session with
+   *  `request.auth.token.firebase.tenant` set to it. */
+  tenantId: string | null;
   /** Sign the current user out. Method form of the free `signOut(auth)`
    *  function — `firebase/auth`'s `Auth` exposes both, so consumer code
    *  written as `auth.signOut()` works unchanged (AUTH-GAP). */

package/src/database/activity-coverage.ts

@@ -0,0 +1,10 @@
+/** Public RTDB data operations observed by the modular adapters. */
+export const databaseActivityCoverage = {
+  service: 'rtdb',
+  read: ['get'],
+  write: ['set', 'update', 'remove', 'push', 'setPriority', 'setWithPriority', 'runTransaction'],
+  listener: ['onValue', 'onChildAdded', 'onChildChanged', 'onChildRemoved', 'onChildMoved'],
+  // Scheduling server work is a distinct surface; neither scheduling nor its
+  // later server execution may be silently reported as an observed client write.
+  untrackedMethods: ['onDisconnect'],
+} as const;

package/src/database/connection-lifecycle.ts

@@ -7,6 +7,7 @@ export class RtdbConnectionLifecycle {
   private readonly operations = new DisconnectOperationQueue();
   private draining: Promise<void> | null = null;
   private online = true;
+  private readonly connectionListeners = new Set<(online: boolean) => void>();
   private resetGeneration: number;
 
   constructor(
@@ -18,7 +19,8 @@ export class RtdbConnectionLifecycle {
   }
 
   private synchronizeReset(): void {
-    if (this.resetGeneration === this.backend.connectionResetGeneration) return;
+    const isCurrentGeneration = this.resetGeneration === this.backend.connectionResetGeneration;
+    if (isCurrentGeneration) return;
     this.operations.clear();
     this.online = true;
     this.resetGeneration = this.backend.connectionResetGeneration;
@@ -27,14 +29,17 @@ export class RtdbConnectionLifecycle {
   register(operation: DisconnectOperation): Promise<void> {
     this.synchronizeReset();
     try {
-      if (!this.admin) {
-        if (operation.kind === 'update') {
+      const requiresRules = !this.admin;
+      if (requiresRules) {
+        const isUpdate = operation.kind === 'update';
+        if (isUpdate) {
           this.backend.validateUpdate(this.auth(), operation.path, operation.values);
         } else {
+          const isRemove = operation.kind === 'remove';
           this.backend.validateSet(
             this.auth(),
             operation.path,
-            operation.kind === 'remove' ? null : operation.value,
+            isRemove ? null : operation.value,
           );
         }
       }
@@ -58,53 +63,75 @@ export class RtdbConnectionLifecycle {
 
   goOffline(): void {
     this.synchronizeReset();
-    if (!this.online) return;
-    this.online = false;
+    const isOffline = !this.online;
+    if (isOffline) return;
+    this.setOnline(false);
     void this.drain().catch(() => undefined);
   }
 
   goOnline(): void {
     this.synchronizeReset();
-    this.online = true;
+    this.setOnline(true);
+  }
+
+  observeConnection(next: (online: boolean) => void): () => void {
+    this.synchronizeReset();
+    this.connectionListeners.add(next);
+    next(this.online);
+    return () => { this.connectionListeners.delete(next); };
+  }
+
+  private setOnline(online: boolean): void {
+    const isUnchanged = this.online === online;
+    if (isUnchanged) return;
+    this.online = online;
+    for (const listener of [...this.connectionListeners]) listener(online);
   }
 
   drain(): Promise<void> {
     this.synchronizeReset();
-    if (this.draining) return this.draining;
+    const currentDrain = this.draining;
+    const isDraining = currentDrain !== null;
+    if (isDraining) return currentDrain;
     const queued = this.operations.takeAll();
     this.draining = (async () => {
       const failures: unknown[] = [];
       for (const operation of queued) {
         try {
-          if (operation.kind === 'update') {
-            if (this.admin) {
+          const isUpdate = operation.kind === 'update';
+          const isAdmin = this.admin;
+          if (isUpdate) {
+            if (isAdmin) {
               this.backend.adminUpdate(operation.path, operation.values as Record<string, JsonValue>);
             } else {
               this.backend.update(this.auth(), operation.path, operation.values as Record<string, JsonValue>);
             }
           } else {
-            const value = operation.kind === 'remove' ? null : operation.value;
-            if (
-              operation.kind === 'set' &&
-              operation.mergeAfterChildRegistration &&
-              value !== null && typeof value === 'object' && !Array.isArray(value)
-            ) {
-              if (this.admin) {
+            const isRemove = operation.kind === 'remove';
+            const value = isRemove ? null : operation.value;
+            const isSet = operation.kind === 'set';
+            const mergesAfterChildRegistration = isSet && operation.mergeAfterChildRegistration === true;
+            const hasObjectValue = value !== null && typeof value === 'object';
+            const mergesObjectChildren = mergesAfterChildRegistration && hasObjectValue && !Array.isArray(value);
+            if (mergesObjectChildren) {
+              if (isAdmin) {
                 this.backend.adminUpdate(operation.path, value as Record<string, JsonValue>);
               } else {
                 this.backend.update(this.auth(), operation.path, value as Record<string, JsonValue>);
               }
               continue;
             }
-            if (this.admin) {
-              if (operation.kind === 'set' && operation.priority !== undefined) {
-                this.backend.adminSetWithPriority(operation.path, value as JsonValue, operation.priority);
+            const priority = isSet ? operation.priority : undefined;
+            const hasPriority = priority !== undefined;
+            if (isAdmin) {
+              if (hasPriority) {
+                this.backend.adminSetWithPriority(operation.path, value as JsonValue, priority);
               } else {
                 this.backend.adminSet(operation.path, value as JsonValue);
               }
             } else {
-              if (operation.kind === 'set' && operation.priority !== undefined) {
-                this.backend.setWithPriority(this.auth(), operation.path, value as JsonValue, operation.priority);
+              if (hasPriority) {
+                this.backend.setWithPriority(this.auth(), operation.path, value as JsonValue, priority);
               } else {
                 this.backend.set(this.auth(), operation.path, value as JsonValue);
               }
@@ -114,8 +141,10 @@ export class RtdbConnectionLifecycle {
           failures.push(error);
         }
       }
-      if (failures.length === 1) throw failures[0];
-      if (failures.length > 1) throw new AggregateError(failures, 'Multiple onDisconnect operations failed');
+      const hasOneFailure = failures.length === 1;
+      if (hasOneFailure) throw failures[0];
+      const hasMultipleFailures = failures.length > 1;
+      if (hasMultipleFailures) throw new AggregateError(failures, 'Multiple onDisconnect operations failed');
     })().finally(() => {
       this.draining = null;
     });

package/src/database/events.ts

@@ -0,0 +1,20 @@
+/**
+ * What the Realtime Database surface puts on the sandbox event stream as a
+ * cross-service mutation. The surface's rich typed `operation`, `commit`, and
+ * `listener` events are declared on the event union itself; this record covers
+ * the generic mutation envelope only.
+ */
+import type { ServiceEventRecord } from '../sandbox/types/service-event-record.js';
+
+export const RTDB_EVENT_RECORD = {
+  service: 'rtdb',
+  operations: ['set', 'update', 'remove', 'transaction', 'setPriority'],
+  target: {
+    name: 'path',
+    description: 'The database path the call targeted, e.g. /rooms/r1/messages.',
+    always: true,
+  },
+} as const satisfies ServiceEventRecord;
+
+/** Every mutation operation the Realtime Database surface emits. */
+export type RtdbEventOperation = (typeof RTDB_EVENT_RECORD)['operations'][number];

package/src/database/instances.ts

@@ -2,7 +2,7 @@ import type { Sandbox, SandboxContext } from 'pyric/sandbox';
 import { SandboxContextImpl } from 'pyric/sandbox';
 import type { FirebaseApp } from '../app/types.js';
 import { defaultClientApp, resolveClientApp } from '../sandbox/internal/client-app.js';
-import { getOrCreateBackend } from './sandbox/backend-for.js';
+import { canonicalizeDatabaseUrl, getOrCreateBackend } from './sandbox/backend-for.js';
 import { RtdbConnectionLifecycle } from './connection-lifecycle.js';
 import { TARGET_SYMBOL, type SandboxLiveTarget, type SandboxTarget } from './routing.js';
 import { Database, type AppDatabase } from './types.js';
@@ -26,23 +26,43 @@ import { Database, type AppDatabase } from './types.js';
  * console.log(snap.val()); // { text: 'hi' }
  * ```
  */
-export function getDatabase(ctx: SandboxContext): Database;
-export function getDatabase(sandbox: Sandbox): Database;
-export function getDatabase(app: FirebaseApp): AppDatabase;
-export function getDatabase(): AppDatabase;
+export function getDatabase(ctx: SandboxContext, url?: string): Database;
+export function getDatabase(sandbox: Sandbox, url?: string): Database;
+export function getDatabase(app: FirebaseApp, url?: string): AppDatabase;
+export function getDatabase(url?: string): AppDatabase;
 export function getDatabase(
-  target?: SandboxContext | Sandbox | FirebaseApp,
+  targetOrUrl?: SandboxContext | Sandbox | FirebaseApp | string,
+  url?: string,
 ): Database {
-  if (target === undefined) return getDatabase(defaultClientApp() as FirebaseApp);
+  let target = targetOrUrl;
+  let effectiveUrl: string | undefined = url;
+
+  if (typeof targetOrUrl === 'string') {
+    target = defaultClientApp() as FirebaseApp;
+    effectiveUrl = targetOrUrl;
+  } else if (target === undefined) {
+    target = defaultClientApp() as FirebaseApp;
+  }
+
   // Package resolution already selected the sandbox mirror; the neutral app
   // adapter resolves an associated FirebaseApp to its app-owned runtime.
   const appRuntime = resolveClientApp(target);
   if (appRuntime) {
-    return appRuntime.service('database/default', () => {
+    const app = target as FirebaseApp;
+    let appDbUrl: string | undefined;
+    try {
+      appDbUrl = app.options?.databaseURL;
+    } catch {
+      // If app is already deleted, reading app.options throws app/app-deleted.
+    }
+    const finalUrl = effectiveUrl ?? appDbUrl;
+    const canonicalKey = canonicalizeDatabaseUrl(finalUrl);
+
+    return appRuntime.service(`database/${canonicalKey}`, () => {
       const { sandbox, session } = appRuntime;
       let deleted = false;
       appRuntime.onDelete(() => { deleted = true; });
-      const backend = getOrCreateBackend(sandbox);
+      const backend = getOrCreateBackend(sandbox, finalUrl);
       const connection = new RtdbConnectionLifecycle(
         backend,
         () => session.currentUser,
@@ -51,6 +71,8 @@ export function getDatabase(
       appRuntime.onDelete(() => connection.drain().catch(() => undefined));
       const t: SandboxLiveTarget = {
         kind: 'sandbox-live',
+        activityApp: app,
+        activityScope: canonicalKey,
         backend,
         connection,
         sandbox,
@@ -63,17 +85,19 @@ export function getDatabase(
           }
         },
       };
-      return new Database(t, target as FirebaseApp) as AppDatabase;
+      return new Database(t, app) as AppDatabase;
     });
   }
+
   if (isSandboxContext(target)) {
-    const backend = getOrCreateBackend(target.sandbox);
+    const backend = getOrCreateBackend(target.sandbox, effectiveUrl);
     const connection = new RtdbConnectionLifecycle(backend, () => target.auth, false);
-    const t: SandboxTarget = { kind: 'sandbox', backend, auth: target.auth, connection };
+    const t: SandboxTarget = { kind: 'sandbox', activityApp: target, activityScope: canonicalizeDatabaseUrl(effectiveUrl), backend, auth: target.auth, connection };
     return new Database(t);
   }
+
   if (isSandbox(target)) {
-    const backend = getOrCreateBackend(target);
+    const backend = getOrCreateBackend(target, effectiveUrl);
     const connection = new RtdbConnectionLifecycle(
       backend,
       () => target.currentUser,
@@ -81,6 +105,8 @@ export function getDatabase(
     );
     const t: SandboxLiveTarget = {
       kind: 'sandbox-live',
+      activityApp: target,
+      activityScope: canonicalizeDatabaseUrl(effectiveUrl),
       backend,
       connection,
       sandbox: target,
@@ -88,6 +114,7 @@ export function getDatabase(
     };
     return new Database(t);
   }
+
   throw packageResolutionError();
 }
 
@@ -96,14 +123,18 @@ export function getDatabase(
  * `getAdminFirestore(sandbox)` for Studio/Playground data browsers and
  * controlled admin tools.
  */
-export function getAdminDatabase(sandbox: Sandbox): Database;
-export function getAdminDatabase(ctx: SandboxContext): Database;
-export function getAdminDatabase(app: FirebaseApp): Database;
-export function getAdminDatabase(target: Sandbox | SandboxContext | FirebaseApp): Database {
+export function getAdminDatabase(sandbox: Sandbox, url?: string): Database;
+export function getAdminDatabase(ctx: SandboxContext, url?: string): Database;
+export function getAdminDatabase(app: FirebaseApp, url?: string): Database;
+export function getAdminDatabase(
+  target: Sandbox | SandboxContext | FirebaseApp,
+  url?: string,
+): Database {
   const appRuntime = resolveClientApp(target);
   if (appRuntime) {
     appRuntime.assertAlive();
-    return getAdminDatabase(appRuntime.sandbox);
+    const effectiveUrl = url ?? (target as FirebaseApp).options?.databaseURL;
+    return getAdminDatabase(appRuntime.sandbox, effectiveUrl);
   }
   const sandbox = isSandboxContext(target)
     ? target.sandbox
@@ -111,7 +142,7 @@ export function getAdminDatabase(target: Sandbox | SandboxContext | FirebaseApp)
       ? target
       : undefined;
   if (sandbox === undefined) throw packageResolutionError();
-  const backend = getOrCreateBackend(sandbox);
+  const backend = getOrCreateBackend(sandbox, url);
   const connection = new RtdbConnectionLifecycle(backend, () => null, true);
   const t: SandboxTarget = { kind: 'sandbox', backend, auth: null, admin: true, connection };
   return new Database(t);
@@ -124,13 +155,13 @@ function packageResolutionError(): TypeError {
 }
 
 function isSandboxContext(
-  target: SandboxContext | Sandbox | FirebaseApp,
+  target: unknown,
 ): target is SandboxContext {
   return target instanceof SandboxContextImpl;
 }
 
 function isSandbox(
-  target: SandboxContext | Sandbox | FirebaseApp,
+  target: unknown,
 ): target is Sandbox {
   if (target === null || typeof target !== 'object') return false;
   const o = target as unknown as Record<string, unknown>;