@pyric/cli 0.1.0-alpha.11 → 0.1.0-alpha.12

package/src/serve/worker/host-ai.ts

@@ -0,0 +1,165 @@
+/**
+ * SharedWorker host — AI op + stream-subscription handlers (pyric/ai).
+ *
+ * Implements cdd-deltas "Where the engines live under pyric dev (#98)":
+ *
+ *   1. The broker and engines run IN-PROCESS with the sandbox — here, in the
+ *      worker host. The scripted engine does no I/O anywhere.
+ *   2. The openai engine's default base URL in this (browser) context is the
+ *      same-origin `/__pyric/ai-proxy` route, so a localhost upstream (Ollama)
+ *      needs no CORS setup. Relative URLs resolve against the worker script's
+ *      origin, so the plain path works from inside the SharedWorker.
+ *   3. `ai.generateContent` / `ai.countTokens` are unary ops exactly like
+ *      `rtdb.*` / `auth.*`; `ai.streamGenerateContent` is a FINITE
+ *      subscription that delivers `{ chunk }` snaps in order, then a terminal
+ *      `{ done: true }` snap and auto-unsubscribes (see AiStreamSubMessage).
+ *   4. Engine choice + model mapping are per-sandbox config: the broker is
+ *      recovered from `getAI(ctx.sandbox, …)` (the mirror's OWN per-sandbox
+ *      broker — its events land on the shared sandbox's unified stream), and
+ *      is created ONCE — host config (`ctx.aiEngine`) wins over the first
+ *      op's `engine` field; later configs are ignored, mirroring `getAI`'s
+ *      first-call-wins idempotence.
+ *
+ * Decomposition mirrors host-auth.ts / host-events.ts: host.ts routes
+ * `ai.*` ops and `{ service: 'ai' }` subs here; this module never imports
+ * host.ts (no cycles — it leans only on the host-context foundation).
+ */
+
+import { getAI, TARGET_SYMBOL, type AIOptions } from 'pyric/ai';
+
+import { serializeError, type OpMessage, type AiStreamSubMessage, type AiEngineConfigWire } from './protocol.js';
+import { type HostCtx, type PortLike, type AiBrokerLike, post, ok, fail } from './host-context.js';
+
+/** The serve proxy route the browser openai engine defaults to (#98.2). */
+export const AI_PROXY_PATH = '/__pyric/ai-proxy';
+
+/** Is this op an AI op (routed here instead of handleOp)? */
+export function isAiOp(method: OpMessage['method']): boolean {
+  return method.startsWith('ai.');
+}
+
+/** The two unary AI op variants, extracted from the OpMessage union. */
+type AiOpMessage = Extract<OpMessage, { method: 'ai.generateContent' | 'ai.countTokens' }>;
+
+/**
+ * Wire config → the mirror's `EngineConfig`. The only transformation is the
+ * browser default: an openai config with no `baseUrl` targets the serve
+ * proxy path. Script entries pass through as-is (they are the broker's own
+ * plain authoring shapes; predicate matchers never made it across the port —
+ * structured clone rejects functions loudly at send time).
+ */
+function resolveEngineConfig(wire: AiEngineConfigWire): NonNullable<AIOptions['engine']> {
+  if (wire.kind === 'openai') {
+    return {
+      kind: 'openai',
+      baseUrl: wire.baseUrl ?? AI_PROXY_PATH,
+      ...(wire.model !== undefined ? { model: wire.model } : {}),
+      ...(wire.modelMap !== undefined ? { modelMap: wire.modelMap } : {}),
+    };
+  }
+  return {
+    kind: 'scripted',
+    ...(wire.script !== undefined
+      ? { script: wire.script as unknown as Extract<NonNullable<AIOptions['engine']>, { kind: 'scripted' }>['script'] }
+      : {}),
+  };
+}
+
+/**
+ * The sandbox's AiBroker, created once per worker lifetime. `getAI` is
+ * idempotent per sandbox+backend, so this IS the mirror's broker — a page
+ * embedding host and this handler resolve the same instance, and every
+ * broker op lands `service: 'ai'` events on the shared sandbox's unified
+ * event stream (what Studio consumes).
+ *
+ * `AiBroker` is not exported from `pyric/ai`'s public surface; the instance
+ * is recovered from the branded handle via the exported `TARGET_SYMBOL`
+ * (the mirror's own dispatch seam).
+ */
+export function ensureAiBroker(ctx: HostCtx, opEngine?: AiEngineConfigWire): AiBrokerLike {
+  if (ctx.aiBroker) return ctx.aiBroker;
+  const wire = ctx.aiEngine ?? opEngine;
+  const ai = getAI(ctx.sandbox, wire ? { engine: resolveEngineConfig(wire) } : undefined);
+  const target = (ai as unknown as {
+    [TARGET_SYMBOL]?: { broker: AiBrokerLike };
+  })[TARGET_SYMBOL];
+  if (!target?.broker) {
+    // Unreachable for a real Sandbox ctx; guards a mis-wired embedding host.
+    throw new Error('pyric worker: getAI(sandbox) did not produce a sandbox-target AI handle');
+  }
+  ctx.aiBroker = target.broker;
+  return target.broker;
+}
+
+/** Handle the unary AI ops. Requests/replies are plain Gemini-wire JSON. */
+export async function handleAiOp(ctx: HostCtx, port: PortLike, msg: OpMessage): Promise<void> {
+  const aiMsg = msg as AiOpMessage;
+  try {
+    const broker = ensureAiBroker(ctx, aiMsg.engine);
+    switch (aiMsg.method) {
+      case 'ai.generateContent': {
+        ok(port, aiMsg.id, await broker.generateContent(aiMsg.request, aiMsg.model));
+        break;
+      }
+      case 'ai.countTokens': {
+        ok(port, aiMsg.id, await broker.countTokens(aiMsg.request, aiMsg.model));
+        break;
+      }
+      default: {
+        fail(port, msg.id, new Error(`Unknown ai method: ${String((msg as { method: unknown }).method)}`));
+      }
+    }
+  } catch (e) {
+    // AiBrokerError envelopes ride the SerializedError whole (aiEnvelope) —
+    // serializeError detects them structurally.
+    fail(port, aiMsg.id, e);
+  }
+}
+
+/**
+ * Handle an AI stream subscription: pump the broker's chunk stream to the
+ * port as `{ chunk }` snaps IN ORDER, then post the terminal `{ done: true }`
+ * snap and drop the sub (finite — auto-unsub on done). The pump is detached
+ * (sub handling is synchronous, like the other sub handlers); a client
+ * `unsub` mid-stream flips the registered cancel and delivery stops.
+ *
+ * Broker validation runs eagerly inside `streamGenerateContent` (before
+ * iteration) — either way a throw lands as the shared `{ __error }` snap
+ * convention, terminal for this sub.
+ */
+export function handleAiSub(ctx: HostCtx, port: PortLike, msg: AiStreamSubMessage): void {
+  let portSubs = ctx.subs.get(port);
+  if (!portSubs) {
+    portSubs = new Map();
+    ctx.subs.set(port, portSubs);
+  }
+  if (portSubs.has(msg.subId)) return; // idempotent
+
+  let cancelled = false;
+  const cancel = (): void => {
+    cancelled = true;
+  };
+  portSubs.set(msg.subId, cancel);
+
+  void (async () => {
+    try {
+      const broker = ensureAiBroker(ctx, msg.engine);
+      for await (const chunk of broker.streamGenerateContent(msg.request, msg.model)) {
+        if (cancelled) return;
+        post(port, { t: 'snap', subId: msg.subId, value: { chunk } });
+      }
+      if (!cancelled) {
+        post(port, { t: 'snap', subId: msg.subId, value: { done: true } });
+      }
+    } catch (e) {
+      if (!cancelled) {
+        post(port, { t: 'snap', subId: msg.subId, value: { __error: serializeError(e) } });
+      }
+    } finally {
+      // Auto-unsub: drop OUR registration only (an early client unsub may
+      // have already removed it — handleUnsub ran the cancel and deleted it).
+      const subs = ctx.subs.get(port);
+      if (subs?.get(msg.subId) === cancel) subs.delete(msg.subId);
+    }
+  })();
+}

package/src/serve/worker/host-auth.ts

@@ -0,0 +1,469 @@
+/**
+ * SharedWorker host — auth subsystem: PER-PORT SESSIONS (#754).
+ *
+ * The worker hosts ONE sandbox (one user pool, one data store, one ruleset)
+ * but each connected port (tab / client) owns its OWN session: sign-ins mint
+ * an authentic identity via `sandbox.mintSession` (credentials validated /
+ * identity really created — NOT the impersonation lens) and bind it to the
+ * port. Auth-state fan-out is port-scoped: tab A signing in does not fire
+ * tab B's `onAuthStateChanged`. Data ops without an explicit Studio lens
+ * run under the port's session (see `sessionDb` in host.ts).
+ *
+ * Session persistence is CLIENT-side: the page records its uid in web
+ * storage (SessionStore, honoring setPersistence) and re-establishes it on
+ * reload via the `auth.restorePortSession` op. The worker holds no session
+ * record — the user POOL still rides the sandbox snapshot (#629).
+ *
+ * Imports only from `./host-context.js` + external packages (no circular
+ * imports).
+ */
+
+import { type HostCtx, type PortLike, post, ok, fail, bestEffortFlush } from './host-context.js';
+import {
+  getAuth,
+  sandbox as authSandboxOps,
+  type Auth,
+  type MintedSession,
+  type User,
+} from 'pyric/auth';
+import {
+  serializeUser,
+  type OpMessage,
+  type AuthSubMessage,
+} from './protocol.js';
+
+/**
+ * Synthetic password seeded for bridged provider identities (popup/redirect).
+ * Provider users never authenticate with a password — this just satisfies the
+ * SeedUser shape. Matches `ServeAuthHelper`'s in-page constant in spirit.
+ */
+const PROVIDER_SYNTHETIC_PASSWORD = '__pyric_popup_no_password__';
+
+// ─── Auth: per-port sessions + port-scoped fan-out ────────────────────────
+
+/**
+ * Per-port auth subscription registry. Map<port, Map<subId, target>>.
+ *
+ * SEPARATE FROM `ctx.subs` (Firestore listeners): auth subs are routing
+ * entries only. With per-port sessions there is no worker-wide auth
+ * listener at all — a port's session changes fan out to THAT port's subs
+ * (see {@link setPortSession}).
+ */
+const _authSubs = new WeakMap<HostCtx, Map<PortLike, Map<string, 'authState' | 'idToken'>>>();
+
+export function authSubsFor(ctx: HostCtx): Map<PortLike, Map<string, 'authState' | 'idToken'>> {
+  let m = _authSubs.get(ctx);
+  if (!m) {
+    m = new Map();
+    _authSubs.set(ctx, m);
+  }
+  return m;
+}
+
+/**
+ * Lazily create the ONE shared auth handle — the user pool + admin surface.
+ * Calling `getAuth(sandbox)` also (re)registers the auth service with the
+ * persistence registry, so the user DB rides the snapshot (#629). Its
+ * `currentUser` is never set in served mode; sessions live per-port.
+ *
+ * Idempotent: returns the cached `ctx.auth` on repeat calls.
+ */
+export function ensureAuth(ctx: HostCtx): Auth {
+  if (ctx.auth) return ctx.auth;
+  ctx.auth = getAuth(ctx.sandbox);
+  if (ctx.sessionMode === undefined) ctx.sessionMode = 'LOCAL';
+  return ctx.auth;
+}
+
+function portSessionsFor(ctx: HostCtx): Map<PortLike, MintedSession | null> {
+  return (ctx.portSessions ??= new Map());
+}
+
+/** The port's signed-in session, or null (absent from the map = signed out). */
+export function portSession(ctx: HostCtx, port: PortLike): MintedSession | null {
+  return portSessionsFor(ctx).get(port) ?? null;
+}
+
+/**
+ * Bind (or clear) a port's session and fan the change out to THAT PORT's
+ * authState/idToken subs — the per-port analog of the old cross-tab
+ * broadcast. Every sign-in mints a fresh token (mintSession did), so the
+ * idToken stream fires alongside authState, matching the real observers.
+ */
+function setPortSession(ctx: HostCtx, port: PortLike, session: MintedSession | null): void {
+  portSessionsFor(ctx).set(port, session);
+
+  // Prod parity on auth transitions: re-establish this port's session-bound
+  // Firestore listeners under the NEW identity, so a sign-out re-evaluates
+  // live streams (auth-gated data is revoked, not leaked) and a sign-in
+  // grants them. Studio-lens subs (explicit actAs) are untouched.
+  ctx.resubscribePortSubs?.(port);
+
+  const serialized = serializeUser(session?.user ?? null);
+  const bySubId = authSubsFor(ctx).get(port);
+  if (!bySubId) return;
+  for (const [subId] of bySubId) {
+    post(port, { t: 'snap', subId, value: serialized });
+  }
+}
+
+/** Apply a forced ID-token refresh to this port's data authorization state. */
+function refreshPortAuthorization(
+  ctx: HostCtx,
+  port: PortLike,
+  session: MintedSession,
+  claims: Record<string, unknown>,
+): void {
+  session.state.token = { ...claims };
+
+  // Frozen sandbox.withAuth handles capture the old token. Clear all
+  // session-handle caches so this port and any same-uid sibling rebuild from
+  // their own current session state on the next operation.
+  ctx.sessionDbs?.clear();
+  ctx.sessionRtdbs?.clear();
+  ctx.sessionStorages?.clear();
+
+  // Existing Firestore/RTDB streams must reauthorize under the refreshed
+  // claims. A token refresh is not an auth-state transition, so notify only
+  // onIdTokenChanged observers with the still-current user.
+  ctx.resubscribePortSubs?.(port);
+  const serialized = serializeUser(session.user);
+  for (const [subId, target] of authSubsFor(ctx).get(port) ?? []) {
+    if (target === 'idToken') post(port, { t: 'snap', subId, value: serialized });
+  }
+}
+
+/** Tear down a disconnected port's session (called from cleanupPort). */
+export function cleanupPortSession(ctx: HostCtx, port: PortLike): void {
+  ctx.portSessions?.delete(port);
+}
+
+// ─── Auth op handlers ─────────────────────────────────────────────────────
+
+/** Serialized UserCredential reply shape for a minted session. */
+function credReply(session: MintedSession, providerId: string | null) {
+  return {
+    user: serializeUser(session.user),
+    providerId,
+    operationType: 'signIn' as const,
+  };
+}
+
+export async function handleAuthOp(ctx: HostCtx, port: PortLike, msg: OpMessage): Promise<void> {
+  const auth = ensureAuth(ctx);
+
+  switch (msg.method) {
+    case 'auth.createUser': {
+      try {
+        const session = authSandboxOps.mintSession(auth, {
+          kind: 'createPassword', email: msg.email, password: msg.password,
+        });
+        setPortSession(ctx, port, session);
+        await bestEffortFlush(ctx); // new user record must be durable at ack
+        ok(port, msg.id, credReply(session, null));
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.signInEmail': {
+      try {
+        const session = authSandboxOps.mintSession(auth, {
+          kind: 'password', email: msg.email, password: msg.password,
+        });
+        setPortSession(ctx, port, session);
+        ok(port, msg.id, credReply(session, null));
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.signInAnonymously': {
+      try {
+        // Match `firebase/auth` semantics per session: if THIS PORT is
+        // already anonymous, reuse that identity (StrictMode double-mounts
+        // must not leak a fresh uid per mount). Other ports' anonymous
+        // sessions are other users — that's the multi-user point.
+        const existing = portSession(ctx, port);
+        if (existing && existing.user.isAnonymous) {
+          ok(port, msg.id, credReply(existing, null));
+          break;
+        }
+        const session = authSandboxOps.mintSession(auth, { kind: 'anonymous' });
+        setPortSession(ctx, port, session);
+        await bestEffortFlush(ctx); // anonymous sign-in creates a user record
+        ok(port, msg.id, credReply(session, null));
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.signOut': {
+      try {
+        setPortSession(ctx, port, null);
+        ok(port, msg.id, null);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.restorePortSession': {
+      // Per-tab reload restore (#754): soft — an unknown/disabled uid means
+      // signed out (null), never an error. The page clears its stale record.
+      try {
+        let session: MintedSession | null = null;
+        try {
+          session = authSandboxOps.mintSession(auth, { kind: 'uid', uid: msg.uid });
+        } catch {
+          session = null;
+        }
+        if (session) setPortSession(ctx, port, session);
+        ok(port, msg.id, session ? serializeUser(session.user) : null);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.getIdToken': {
+      try {
+        const session = requirePortSession(ctx, port, 'getIdToken');
+        const user = session.user;
+        const token = await user.getIdToken(msg.forceRefresh);
+        if (msg.forceRefresh) {
+          const result = await user.getIdTokenResult(false);
+          refreshPortAuthorization(ctx, port, session, result.claims);
+        }
+        ok(port, msg.id, token);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.getIdTokenResult': {
+      try {
+        const session = requirePortSession(ctx, port, 'getIdTokenResult');
+        const user = session.user;
+        const r = await user.getIdTokenResult(msg.forceRefresh);
+        if (msg.forceRefresh) refreshPortAuthorization(ctx, port, session, r.claims);
+        ok(port, msg.id, {
+          token: r.token,
+          claims: r.claims,
+          expirationTime: r.expirationTime,
+          issuedAtTime: r.issuedAtTime,
+          authTime: r.authTime,
+          signInProvider: r.signInProvider ?? null,
+        });
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.setPersistence': {
+      // Accepted for surface parity; the CLIENT's SessionStore owns where
+      // (or whether) the session uid is recorded. Nothing to do worker-side.
+      ctx.sessionMode = msg.mode;
+      ok(port, msg.id, null);
+      break;
+    }
+
+    case 'auth.getCurrentUser': {
+      try {
+        ok(port, msg.id, serializeUser(portSession(ctx, port)?.user ?? null));
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.updateProfile': {
+      // Update THIS PORT's signed-in user's profile (displayName / photoURL).
+      // Updates the stored record (by uid) via the sandbox op, then mutates the
+      // port session's `User` in place so a subsequent `auth.getCurrentUser`
+      // (and the client mirror hydrated from the reply) is consistent. Does NOT
+      // fire onAuthStateChanged/onIdTokenChanged — matching firebase/auth.
+      try {
+        const session = portSession(ctx, port);
+        if (!session) throw makeNoUserError('updateProfile');
+        const profile = { displayName: msg.displayName, photoURL: msg.photoURL };
+        authSandboxOps.updateProfile(auth, session.user.uid, profile);
+        applyProfileToUser(session.user, profile);
+        await bestEffortFlush(ctx);
+        ok(port, msg.id, serializeUser(session.user));
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.acceptIdentity': {
+      // Provider sign-in bridge: the page resolved a popup/redirect identity
+      // in-page (ServeAuthHelper) and hands it here. GATE FIRST: the page
+      // sandbox delegates provider enforcement to this worker (its picker
+      // opens unconditionally), so THIS is where Studio's provider toggles
+      // bite — a disabled provider throws `auth/operation-not-allowed`
+      // before any user-DB write. Then seed it into the user DB (so rules
+      // `request.auth.token.*` claims resolve AND it shows in the picker
+      // next time), and mint THIS PORT's session for it — provider users
+      // have no password. Mirrors ServeAuthHelper.add's seeding.
+      try {
+        const { uid, email, displayName, customClaims, providerId } = msg.identity;
+        authSandboxOps.assertAuthProviderEnabled(auth, providerId);
+        authSandboxOps.seedUsers(auth, [{
+          uid,
+          email: email ?? '',
+          password: PROVIDER_SYNTHETIC_PASSWORD,
+          displayName: displayName ?? undefined,
+          customClaims: customClaims ?? {},
+          providerId,
+        }]);
+        const session = authSandboxOps.mintSession(auth, { kind: 'uid', uid });
+        setPortSession(ctx, port, session);
+        await bestEffortFlush(ctx); // seeded provider identity must be durable
+        ok(port, msg.id, credReply(session, providerId));
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.listUsers': {
+      // Admin user-DB enumeration (Pyric Studio data browse).
+      try {
+        ok(port, msg.id, authSandboxOps.listUsers(auth));
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.adminCreateUser': {
+      try {
+        const created = authSandboxOps.createUser(
+          auth,
+          msg.request as Parameters<typeof authSandboxOps.createUser>[1],
+        );
+        await bestEffortFlush(ctx);
+        ok(port, msg.id, created);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.adminUpdateUser': {
+      try {
+        const updated = authSandboxOps.updateUser(
+          auth,
+          msg.uid,
+          msg.request as Parameters<typeof authSandboxOps.updateUser>[2],
+        );
+        await bestEffortFlush(ctx);
+        ok(port, msg.id, updated);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.adminDeleteUser': {
+      try {
+        authSandboxOps.deleteUser(auth, msg.uid);
+        await bestEffortFlush(ctx);
+        ok(port, msg.id, null);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.adminClearUsers': {
+      try {
+        authSandboxOps.clearUsers(auth);
+        await bestEffortFlush(ctx);
+        ok(port, msg.id, null);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.getProviderConfig': {
+      // Sign-in provider config (Pyric Studio S-AUTH "Sign-in providers"
+      // section). `setProviderConfig` emits a `provider_config_update`
+      // sandbox event, so a caller subscribed to the event stream (the
+      // worker's event feed, which `subscribeUsers` already rides) sees
+      // toggles live without a dedicated subscription message here.
+      try {
+        ok(port, msg.id, authSandboxOps.getAuthProviderConfig(auth));
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    case 'auth.setProviderConfig': {
+      try {
+        authSandboxOps.setAuthProviderConfig(auth, msg.providerId, msg.enabled);
+        ok(port, msg.id, null);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
+    default: {
+      fail(port, msg.id, new Error(`Unknown auth method: ${String((msg as { method: unknown }).method)}`));
+    }
+  }
+}
+
+/** The port session's User, or throw `auth/no-current-user`. */
+function requireSessionUser(ctx: HostCtx, port: PortLike, api: string): User {
+  return requirePortSession(ctx, port, api).user;
+}
+
+function requirePortSession(ctx: HostCtx, port: PortLike, api: string): MintedSession {
+  const session = portSession(ctx, port);
+  if (!session) throw makeNoUserError(api);
+  return session;
+}
+
+/**
+ * Mutate a port session's `User` `displayName` / `photoURL` (and the first
+ * `providerData` entry's) in place so a subsequent `auth.getCurrentUser`
+ * reflects an `auth.updateProfile`. Fields are `readonly` at the type level
+ * but plain data at runtime; only an explicitly-provided field is applied
+ * (`null` clears, `undefined` leaves untouched).
+ */
+function applyProfileToUser(
+  user: User,
+  profile: { displayName?: string | null; photoURL?: string | null },
+): void {
+  const mutable = user as { -readonly [K in keyof User]: User[K] };
+  if (profile.displayName !== undefined) mutable.displayName = profile.displayName;
+  if (profile.photoURL !== undefined) mutable.photoURL = profile.photoURL;
+  const provider0 = user.providerData?.[0] as
+    | { -readonly [K in keyof NonNullable<User['providerData']>[number]]: NonNullable<User['providerData']>[number][K] }
+    | undefined;
+  if (provider0) {
+    if (profile.displayName !== undefined) provider0.displayName = profile.displayName;
+    if (profile.photoURL !== undefined) provider0.photoURL = profile.photoURL;
+  }
+}
+
+/** Build an `auth/no-current-user`-style error for token ops with no user. */
+function makeNoUserError(api: string): Error & { code: string } {
+  const err = new Error(`${api}: no current user is signed in.`) as Error & { code: string };
+  err.code = 'auth/no-current-user';
+  return err;
+}
+
+export function isAuthOp(method: OpMessage['method']): boolean {
+  return method.startsWith('auth.');
+}
+
+// ─── Auth subscription handlers ───────────────────────────────────────────
+
+/**
+ * Register an auth subscription for a port. A routing entry only — the
+ * port's session changes (its own sign-ins/outs) fan out to it via
+ * {@link setPortSession}. Fires the PORT's current session immediately
+ * (initial-fire parity with onAuthStateChanged/onIdTokenChanged).
+ */
+export function handleAuthSub(ctx: HostCtx, port: PortLike, msg: AuthSubMessage): void {
+  ensureAuth(ctx);
+  const subs = authSubsFor(ctx);
+  let bySubId = subs.get(port);
+  if (!bySubId) {
+    bySubId = new Map();
+    subs.set(port, bySubId);
+  }
+  if (bySubId.has(msg.subId)) return; // idempotent
+  bySubId.set(msg.subId, msg.target);
+
+  // Initial fire — mirror the real observers, which invoke the callback once
+  // with the current state on registration. Per-port: THIS port's session.
+  post(port, { t: 'snap', subId: msg.subId, value: serializeUser(portSession(ctx, port)?.user ?? null) });
+}
+
+export function handleAuthUnsub(ctx: HostCtx, port: PortLike, subId: string): boolean {
+  const subs = authSubsFor(ctx);
+  const bySubId = subs.get(port);
+  if (!bySubId || !bySubId.has(subId)) return false;
+  bySubId.delete(subId);
+  if (bySubId.size === 0) subs.delete(port);
+  return true;
+}