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

package/src/serve/worker/activity-bootstrap.ts

@@ -0,0 +1,24 @@
+import type { ActivityMonitor } from 'pyric/firestore/internal';
+import { setupFirebaseActivityGuard as setupActivityGuardForFeed } from '../activity-guard.js';
+import type { HostCtx } from './host.js';
+
+export interface WorkerActivityEnv {
+  fetch: typeof fetch;
+}
+
+/** Own the worker-lifetime warning guard after capture history has hydrated. */
+export function setupFirebaseActivityGuard(
+  ctx: HostCtx,
+  env: WorkerActivityEnv,
+  activityToken: string | undefined,
+): ActivityMonitor | null {
+  if (!activityToken) return null;
+  return setupActivityGuardForFeed(
+    {
+      history: () => ctx.sandbox.history(),
+      subscribe: (listener) => ctx.sandbox.onEvent(listener),
+    },
+    env.fetch,
+    activityToken,
+  );
+}

package/src/serve/worker/client/admin-firestore.ts

@@ -0,0 +1,38 @@
+/**
+ * Admin-lens Firestore document ops over the worker port (Pyric Studio data
+ * browse) — rule-bypassing reads/writes the host resolves under the admin lens.
+ */
+
+import { nextId, rpc } from './core.js';
+import type { ClientDb } from './handles.js';
+
+export async function adminGetDocument(db: ClientDb, path: string): Promise<Record<string, unknown> | null> {
+  return (await rpc(db.port, { t: 'op', id: nextId(), method: 'admin.getDocument', path })) as Record<string, unknown> | null;
+}
+
+export async function adminListDocuments(
+  db: ClientDb,
+  path: string,
+): Promise<Array<{ path: string; data: unknown; phantom?: boolean }>> {
+  return (await rpc(db.port, { t: 'op', id: nextId(), method: 'admin.listDocuments', path })) as Array<{ path: string; data: unknown; phantom?: boolean }>;
+}
+
+export async function adminSetDocument(db: ClientDb, path: string, data: unknown): Promise<void> {
+  await rpc(db.port, { t: 'op', id: nextId(), method: 'admin.setDocument', path, data });
+}
+
+export async function adminDeleteDocument(db: ClientDb, path: string): Promise<boolean> {
+  return (await rpc(db.port, { t: 'op', id: nextId(), method: 'admin.deleteDocument', path })) as boolean;
+}
+
+export async function adminReadState(
+  db: ClientDb,
+  opts: { path?: string; maxDepth?: number } = {},
+): Promise<Record<string, unknown>> {
+  return (await rpc(db.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'admin.readState',
+    ...opts,
+  })) as Record<string, unknown>;
+}

package/src/serve/worker/client/ai.ts

@@ -0,0 +1,124 @@
+/**
+ * AI ops over the worker port — the served firebase/ai entry plugs these in
+ * as the mirror AnswerEngine on the worker path (see entries/ai.ts).
+ */
+
+import type { AiEngineConfigWire, InboundMessage } from '../protocol.js';
+import { closeSubscription, nextId, nextSubId, openSnapshotSubscription, rpc } from './core.js';
+import type { ClientDb } from './handles.js';
+
+// ─── AI ops (pyric/ai over the worker — cdd-deltas #98.3) ──────────────────
+//
+// The served `firebase/ai` entry (entries/ai.ts) plugs these three functions
+// in as the mirror's AnswerEngine on the worker path, so the page keeps the
+// full `pyric/ai` surface (GenerativeModel / ChatSession / Schema) while
+// ANSWERING happens in the worker host's broker — in-process with the ONE
+// shared sandbox (#98.1), whose unified event stream Studio consumes.
+// Requests/responses are the plain Gemini-wire JSON the broker speaks; no
+// codec round-trip. `engine` rides each message but is honored only on the
+// worker's FIRST ai op (broker creation — see AiEngineConfigWire).
+
+/** Parameters shared by the three AI ops. */
+export interface AiOpParams {
+  /** Model resource the mirror resolved (e.g. `models/gemini-flash-lite-latest`). */
+  model: string;
+  /** Plain Gemini-wire request JSON. */
+  request: Record<string, unknown>;
+  /** First-op engine config — see {@link AiEngineConfigWire}. */
+  engine?: AiEngineConfigWire;
+}
+
+/** Unary `generateContent` against the worker's broker. Resolves with the
+ *  complete WireResponse envelope; rejects with an Error carrying `.code`
+ *  (and `.aiEnvelope` when the broker answered a wire error envelope). */
+export async function aiGenerateContent(
+  db: ClientDb,
+  params: AiOpParams,
+): Promise<Record<string, unknown>> {
+  return (await rpc(db.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'ai.generateContent',
+    model: params.model,
+    request: params.request,
+    ...(params.engine !== undefined ? { engine: params.engine } : {}),
+  })) as Record<string, unknown>;
+}
+
+/** Unary `countTokens` against the worker's broker (deterministic). */
+export async function aiCountTokens(
+  db: ClientDb,
+  params: AiOpParams,
+): Promise<Record<string, unknown>> {
+  return (await rpc(db.port, {
+    t: 'op',
+    id: nextId(),
+    method: 'ai.countTokens',
+    model: params.model,
+    request: params.request,
+    ...(params.engine !== undefined ? { engine: params.engine } : {}),
+  })) as Record<string, unknown>;
+}
+
+/**
+ * Streamed `generateContent` over an AI stream SUBSCRIPTION: chunks arrive
+ * as `{ chunk }` snaps in order, the terminal `{ done: true }` snap ends the
+ * iteration, and a snap `__error` throws (with `.code` / `.aiEnvelope`).
+ * The host auto-unsubs on done; the generator additionally sends `unsub` on
+ * teardown so early consumer abandonment cancels the worker-side pump (the
+ * done/unsub race is a benign no-op on the host).
+ */
+export async function* aiStreamGenerateContent(
+  db: ClientDb,
+  params: AiOpParams,
+): AsyncGenerator<Record<string, unknown>> {
+  const subId = nextSubId();
+  type QueueItem =
+    | { kind: 'chunk'; chunk: Record<string, unknown> }
+    | { kind: 'done' }
+    | { kind: 'error'; error: unknown };
+  const queue: QueueItem[] = [];
+  let notify: (() => void) | null = null;
+  const push = (item: QueueItem): void => {
+    queue.push(item);
+    notify?.();
+    notify = null;
+  };
+
+  const opened = openSnapshotSubscription(db.port, subId, {
+    port: db.port,
+    next: (raw) => {
+      const v = (raw ?? {}) as { chunk?: Record<string, unknown>; done?: boolean };
+      if (v.done) push({ kind: 'done' });
+      else push({ kind: 'chunk', chunk: v.chunk ?? {} });
+    },
+    error: (err) => push({ kind: 'error', error: err }),
+  }, {
+    t: 'sub',
+    subId,
+    target: { service: 'ai', op: 'streamGenerateContent' },
+    model: params.model,
+    request: params.request,
+    ...(params.engine !== undefined ? { engine: params.engine } : {}),
+  } satisfies InboundMessage);
+  if (!opened) push({
+    kind: 'error',
+    error: Object.assign(new Error('Firebase App was deleted'), { code: 'app/app-deleted' }),
+  });
+
+  try {
+    for (;;) {
+      while (queue.length === 0) {
+        await new Promise<void>((resolve) => {
+          notify = resolve;
+        });
+      }
+      const item = queue.shift()!;
+      if (item.kind === 'error') throw item.error;
+      if (item.kind === 'done') return;
+      yield item.chunk;
+    }
+  } finally {
+    closeSubscription(db.port, subId);
+  }
+}

package/src/serve/worker/client/auth.ts

@@ -0,0 +1,489 @@
+/**
+ * Worker-client Auth surface — mirrors `pyric/auth` / `firebase/auth` over the
+ * port. Per-port sessions (#754): each port owns its own session; the client
+ * keeps a local `currentUser` mirror updated from the authState stream while the
+ * worker owns the real `User` and token minting.
+ */
+
+import type {
+  InboundMessage,
+  SerializedUser,
+  SerializedUserCredential,
+  SerializedIdTokenResult,
+  AuthPersistenceMode,
+  ResolvedIdentity,
+} from '../protocol.js';
+import type { AuthUserRecord, CreateUserRequest, UpdateUserRequest } from 'pyric/auth';
+import { closeSubscription, isDisconnectedPort, nextId, nextSubId, openSnapshotSubscription, rpc, wirePort } from './core.js';
+import type { ClientDb, ClientPort, Unsubscribe } from './handles.js';
+
+// ════════════════════════════════════════════════════════════════════════
+//  AUTH SURFACE (mirrors `pyric/auth` / `firebase/auth`)
+// ════════════════════════════════════════════════════════════════════════
+//
+// PER-PORT SESSIONS (#754)
+// ------------------------
+// The worker hosts ONE sandbox (one user pool, one data store, one ruleset)
+// but each port (tab / client) owns its OWN session: sign-ins bind to THIS
+// port, `onAuthStateChanged` fires for THIS port's transitions only, and
+// data ops from this port evaluate rules under its session. Two tabs can be
+// two different users on the same live backend — the multi-user testing
+// surface a single-identity sandbox can't provide. Session persistence
+// across reloads is client-side (SessionStore + `restorePortSession`).
+//
+// CLIENT-SIDE currentUser MIRROR
+// ------------------------------
+// The worker holds the one real `User`. The client keeps a local
+// `ClientUser` mirror updated from the authState stream, so `auth.currentUser`
+// is synchronously readable (matching firebase/auth). Token accessors RPC to
+// the worker (the worker owns token minting).
+
+/**
+ * Client-side User — a snapshot of the worker's `User` with token accessors
+ * that RPC back to the worker. Mirrors `firebase/auth`'s `User` shape.
+ */
+export interface ClientUser {
+  readonly uid: string;
+  readonly email: string | null;
+  readonly emailVerified: boolean;
+  readonly displayName: string | null;
+  readonly photoURL: string | null;
+  readonly phoneNumber: string | null;
+  readonly isAnonymous: boolean;
+  readonly providerId: string | null;
+  readonly providerData: SerializedUser['providerData'];
+  getIdToken(forceRefresh?: boolean): Promise<string>;
+  getIdTokenResult(forceRefresh?: boolean): Promise<SerializedIdTokenResult>;
+}
+
+/** Client-side UserCredential — mirrors `firebase/auth`. */
+export interface ClientUserCredential {
+  user: ClientUser;
+  providerId: string | null;
+  operationType: 'signIn' | 'reauthenticate' | 'link';
+}
+
+/**
+ * Client-side Auth handle. Holds the port + a local `currentUser` mirror.
+ * Returned by `getAuth(db | workerUrl)`. Mirrors `firebase/auth`'s `Auth`.
+ */
+export interface ClientAuth {
+  readonly __kind: 'client-auth';
+  readonly port: ClientPort;
+  /** Local mirror of the worker's currentUser, updated from the stream. */
+  currentUser: ClientUser | null;
+}
+
+/** Hidden per-`ClientUser` port handle so the top-level `updateProfile(user, …)`
+ *  free function can RPC without an `auth` handle in scope (mirrors
+ *  `firebase/auth`'s user-only signature). Non-enumerable — never serialized. */
+const CLIENT_USER_PORT: unique symbol = Symbol('pyric.clientUser.port');
+
+/** Build a token-capable ClientUser from a wire SerializedUser. */
+function makeClientUser(port: ClientPort, raw: SerializedUser): ClientUser {
+  const user: ClientUser = {
+    uid: raw.uid,
+    email: raw.email,
+    emailVerified: raw.emailVerified,
+    displayName: raw.displayName,
+    photoURL: raw.photoURL,
+    phoneNumber: raw.phoneNumber,
+    isAnonymous: raw.isAnonymous,
+    providerId: raw.providerId,
+    providerData: raw.providerData,
+    async getIdToken(forceRefresh?: boolean) {
+      return (await rpc(port, {
+        t: 'op', id: nextId(), method: 'auth.getIdToken', forceRefresh,
+      })) as string;
+    },
+    async getIdTokenResult(forceRefresh?: boolean) {
+      return (await rpc(port, {
+        t: 'op', id: nextId(), method: 'auth.getIdTokenResult', forceRefresh,
+      })) as SerializedIdTokenResult;
+    },
+  };
+  Object.defineProperty(user, CLIENT_USER_PORT, { value: port, enumerable: false });
+  return user;
+}
+
+/** Convert a wire SerializedUser|null to a ClientUser|null. */
+function toClientUser(port: ClientPort, raw: SerializedUser | null): ClientUser | null {
+  return raw ? makeClientUser(port, raw) : null;
+}
+
+/**
+ * Get the worker-backed Auth handle.
+ *
+ * Mirrors `pyric/auth`'s `getAuth(sandbox)` / `firebase/auth`'s
+ * `getAuth(app)` — but the input is either an existing `ClientDb` (reusing
+ * its port, the common case in serve where Firestore + auth share one
+ * worker) or a worker URL (standalone).
+ *
+ * The returned handle seeds its `currentUser` mirror by opening an internal
+ * authState subscription that keeps it live across tabs.
+ */
+export function getAuth(source: ClientDb | string | URL, name?: string): ClientAuth {
+  let port: ClientPort;
+  if (typeof source === 'object' && '__kind' in source && source.__kind === 'client-db') {
+    port = source.port;
+  } else {
+    if (typeof SharedWorker === 'undefined') {
+      throw new Error(
+        'SharedWorker is not available. ' +
+        'Open this page over http:// (not file://) and use a supported browser ' +
+        '(Chrome 4+, Firefox 29+, Safari 16.4+).',
+      );
+    }
+    const worker = new SharedWorker(source as string | URL, {
+      type: 'classic',
+      name: name ?? 'pyric-shared-worker',
+    });
+    port = worker.port;
+    port.start();
+    wirePort(port);
+  }
+
+  const auth: ClientAuth = { __kind: 'client-auth', port, currentUser: null };
+
+  // Internal authState subscription keeps `auth.currentUser` live. Per-port
+  // sessions (#754): only THIS port's sign-ins/outs (and its session restore)
+  // fire here — another tab's sign-in is another user, not an update to us.
+  const subId = nextSubId();
+  openSnapshotSubscription(port, subId, {
+    port,
+    next: (raw) => {
+      auth.currentUser = toClientUser(port, raw as SerializedUser | null);
+    },
+  }, { t: 'sub', subId, target: 'authState' } satisfies InboundMessage);
+
+  return auth;
+}
+
+/**
+ * Connect to the auth emulator. No-op shim over the worker: the worker's
+ * sandbox IS the emulator-equivalent backend, so there's nothing to point at.
+ * Present for surface parity so app code that calls it doesn't break.
+ */
+export function connectAuthEmulator(
+  _auth: ClientAuth,
+  _url: string,
+  _options?: { disableWarnings?: boolean },
+): void {
+  // Intentional no-op — the worker's sandbox is the local auth backend.
+}
+
+// ─── Sign-in / out / create (RPC) ─────────────────────────────────────────
+
+export async function createUserWithEmailAndPassword(
+  auth: ClientAuth,
+  email: string,
+  password: string,
+): Promise<ClientUserCredential> {
+  const raw = (await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.createUser', email, password,
+  })) as SerializedUserCredential;
+  return hydrateCred(auth, raw);
+}
+
+// ─── Admin user-DB ops (Pyric Studio data browse) ─────────────────────────
+// Mirror `pyric/auth`'s `sandbox.{listUsers,createUser,updateUser,deleteUser,
+// clearUsers}` over the port. No lens (admin control surface), so bare `rpc`.
+
+export async function listUsers(auth: ClientAuth): Promise<AuthUserRecord[]> {
+  return (await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.listUsers',
+  })) as AuthUserRecord[];
+}
+
+export async function adminCreateUser(
+  auth: ClientAuth,
+  request: CreateUserRequest,
+): Promise<AuthUserRecord> {
+  return (await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.adminCreateUser',
+    request: request as unknown as Record<string, unknown>,
+  })) as AuthUserRecord;
+}
+
+export async function adminUpdateUser(
+  auth: ClientAuth,
+  uid: string,
+  request: UpdateUserRequest,
+): Promise<AuthUserRecord> {
+  return (await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.adminUpdateUser', uid,
+    request: request as unknown as Record<string, unknown>,
+  })) as AuthUserRecord;
+}
+
+export async function adminDeleteUser(auth: ClientAuth, uid: string): Promise<void> {
+  await rpc(auth.port, { t: 'op', id: nextId(), method: 'auth.adminDeleteUser', uid });
+}
+
+export async function adminClearUsers(auth: ClientAuth): Promise<void> {
+  await rpc(auth.port, { t: 'op', id: nextId(), method: 'auth.adminClearUsers' });
+}
+
+// ─── Sign-in provider config (Pyric Studio S-AUTH) ────────────────────────
+// Mirror `pyric/auth`'s `sandbox.{getAuthProviderConfig,setAuthProviderConfig}`
+// over the port. No dedicated subscription: `setProviderConfig` fires a
+// `provider_config_update` sandbox event, so a caller re-reads via
+// `getProviderConfig` on the SAME event feed `listUsers` callers already
+// subscribe to (see `worker-live.ts`'s `subscribeUsers`).
+
+export async function getProviderConfig(
+  auth: ClientAuth,
+): Promise<Array<{ providerId: string; enabled: boolean }>> {
+  return (await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.getProviderConfig',
+  })) as Array<{ providerId: string; enabled: boolean }>;
+}
+
+export async function setProviderConfig(
+  auth: ClientAuth,
+  providerId: string,
+  enabled: boolean,
+): Promise<void> {
+  await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.setProviderConfig', providerId, enabled,
+  });
+}
+
+export async function signInWithEmailAndPassword(
+  auth: ClientAuth,
+  email: string,
+  password: string,
+): Promise<ClientUserCredential> {
+  const raw = (await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.signInEmail', email, password,
+  })) as SerializedUserCredential;
+  return hydrateCred(auth, raw);
+}
+
+export async function signInAnonymously(auth: ClientAuth): Promise<ClientUserCredential> {
+  const raw = (await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.signInAnonymously',
+  })) as SerializedUserCredential;
+  return hydrateCred(auth, raw);
+}
+
+export async function signOut(auth: ClientAuth): Promise<void> {
+  if (isDisconnectedPort(auth.port)) {
+    auth.currentUser = null;
+    return;
+  }
+  await rpc(auth.port, { t: 'op', id: nextId(), method: 'auth.signOut' });
+  // The authState stream will also clear the mirror; set eagerly so a
+  // synchronous read right after `await signOut()` reflects the change.
+  auth.currentUser = null;
+}
+
+/**
+ * Bridge a provider identity resolved IN-PAGE to the worker (the provider
+ * sign-in seam). The entry adapter's worker-path `signInWithPopup`/
+ * `signInWithRedirect` runs the in-page `AuthFlowResolver` (which can't cross
+ * the worker port), then calls this with the picked identity; the worker seeds
+ * it + signs it in, returning a worker-backed credential. The mirror updates
+ * eagerly (like the email/anon paths) so a synchronous `auth.currentUser`
+ * read right after the await reflects the new user.
+ */
+export async function acceptProviderCredential(
+  auth: ClientAuth,
+  identity: ResolvedIdentity,
+): Promise<ClientUserCredential> {
+  const raw = (await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.acceptIdentity', identity,
+  })) as SerializedUserCredential;
+  return hydrateCred(auth, raw);
+}
+
+/**
+ * Re-establish THIS PORT's session for an existing identity (#754) — the
+ * per-tab reload restore. The page persists its uid in web storage
+ * (SessionStore); runtime.ts calls this at boot BEFORE app code runs. Soft:
+ * returns null (and leaves the port signed out) when the uid no longer
+ * resolves, so a stale record never throws.
+ */
+export async function restorePortSession(
+  auth: ClientAuth,
+  uid: string,
+): Promise<ClientUser | null> {
+  const raw = (await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.restorePortSession', uid,
+  })) as SerializedUser | null;
+  const user = toClientUser(auth.port, raw);
+  if (user) auth.currentUser = user;
+  return user;
+}
+
+function hydrateCred(auth: ClientAuth, raw: SerializedUserCredential): ClientUserCredential {
+  const user = makeClientUser(auth.port, raw.user);
+  // Eagerly update the mirror so `auth.currentUser` is correct immediately
+  // after the await, before the broadcast stream lands.
+  auth.currentUser = user;
+  return { user, providerId: raw.providerId, operationType: raw.operationType };
+}
+
+// ─── Persistence ──────────────────────────────────────────────────────────
+
+/** Persistence markers — mirror `firebase/auth` / `pyric/auth`. */
+export const inMemoryPersistence = { type: 'NONE' } as const;
+
+export const browserSessionPersistence = { type: 'SESSION' } as const;
+
+export const browserLocalPersistence = { type: 'LOCAL' } as const;
+
+export type ClientPersistence = { readonly type: AuthPersistenceMode };
+
+/**
+ * Record the session-persistence mode on the worker (surface parity). The
+ * effective persistence is CLIENT-side (#754): the entry adapter mirrors the
+ * mode into the page's SessionStore, which decides where — or whether — this
+ * tab's session uid is stored for reload restore.
+ */
+export async function setPersistence(
+  auth: ClientAuth,
+  persistence: ClientPersistence,
+): Promise<void> {
+  await rpc(auth.port, {
+    t: 'op', id: nextId(), method: 'auth.setPersistence', mode: persistence.type,
+  });
+}
+
+// ─── Observers (streaming subs) ────────────────────────────────────────────
+
+/**
+ * Subscribe to auth-state changes. Mirrors `firebase/auth`'s
+ * `onAuthStateChanged`. Fires immediately with THIS PORT's current session,
+ * then on every change to it (#754: sessions are per-port — another tab's
+ * sign-in is a different user, not an update to this one). Updates the
+ * handle's `currentUser` mirror before invoking the callback.
+ */
+export function onAuthStateChanged(
+  auth: ClientAuth,
+  callback: (user: ClientUser | null) => void,
+): Unsubscribe {
+  return openAuthSub(auth, 'authState', callback);
+}
+
+/**
+ * Subscribe to ID-token changes. Mirrors `firebase/auth`'s
+ * `onIdTokenChanged` — fires on THIS PORT's identity transitions (per-port
+ * sessions, #754).
+ */
+export function onIdTokenChanged(
+  auth: ClientAuth,
+  callback: (user: ClientUser | null) => void,
+): Unsubscribe {
+  return openAuthSub(auth, 'idToken', callback);
+}
+
+function openAuthSub(
+  auth: ClientAuth,
+  target: 'authState' | 'idToken',
+  callback: (user: ClientUser | null) => void,
+): Unsubscribe {
+  const subId = nextSubId();
+  const port = auth.port;
+
+  openSnapshotSubscription(port, subId, {
+    port,
+    next: (raw) => {
+      const user = toClientUser(port, raw as SerializedUser | null);
+      auth.currentUser = user;
+      callback(user);
+    },
+  }, { t: 'sub', subId, target } satisfies InboundMessage);
+
+  return () => {
+    closeSubscription(port, subId);
+  };
+}
+
+// ─── Token accessors (top-level mirrors) ──────────────────────────────────
+
+/** Top-level mirror of `firebase/auth`'s `getIdToken(user)`. */
+export async function getIdToken(user: ClientUser, forceRefresh?: boolean): Promise<string> {
+  return user.getIdToken(forceRefresh);
+}
+
+/** Top-level mirror of `firebase/auth`'s `getIdTokenResult(user)`. */
+export async function getIdTokenResult(
+  user: ClientUser,
+  forceRefresh?: boolean,
+): Promise<SerializedIdTokenResult> {
+  return user.getIdTokenResult(forceRefresh);
+}
+
+/**
+ * Top-level mirror of `firebase/auth`'s `updateProfile(user, profile)` over
+ * the worker. RPCs `auth.updateProfile` for THIS PORT's session (the worker
+ * owns the real `User`), then mutates the passed `user` mirror in place with
+ * the returned fields so a synchronous read right after the await is
+ * consistent. `null` clears a field; an absent field is left untouched.
+ *
+ * The port is recovered from the hidden {@link CLIENT_USER_PORT} handle stamped
+ * on every `ClientUser`, so this works without an `auth` handle in scope.
+ */
+export async function updateProfile(
+  user: ClientUser,
+  profile: { displayName?: string | null; photoURL?: string | null },
+): Promise<void> {
+  const port = (user as { [CLIENT_USER_PORT]?: ClientPort })[CLIENT_USER_PORT];
+  if (!port) {
+    const err = new Error(
+      'updateProfile: unrecognized user — was it produced by a worker-path sign-in?',
+    ) as Error & { code: string };
+    err.code = 'auth/invalid-user-token';
+    throw err;
+  }
+  const raw = (await rpc(port, {
+    t: 'op', id: nextId(), method: 'auth.updateProfile',
+    displayName: profile.displayName, photoURL: profile.photoURL,
+  })) as SerializedUser;
+  // Mutate the passed mirror in place (readonly at the type level, plain data
+  // at runtime) so held references reflect the change immediately.
+  const mutable = user as { -readonly [K in keyof ClientUser]: ClientUser[K] };
+  mutable.displayName = raw.displayName;
+  mutable.photoURL = raw.photoURL;
+  mutable.providerData = raw.providerData;
+}
+
+// ─── Provider flows — NOT supported over the worker yet ───────────────────
+
+/**
+ * Provider sign-in (`signInWithCredential`, `signInWithPopup`,
+ * `signInWithRedirect`) needs the AuthFlowResolver, which lives in-page and
+ * can't cross the worker port. NOT SUPPORTED over the SharedWorker in v1 —
+ * a clear error rather than silent breakage. Tracked as a Phase 2 follow-up:
+ * thread the resolver through, or run provider flows in-page and hand the
+ * resulting credential to the worker.
+ */
+export function signInWithCredential(): Promise<never> {
+  return Promise.reject(makeUnsupported('signInWithCredential'));
+}
+
+/**
+ * `beforeAuthStateChanged` gates a LOCAL identity transition — the
+ * worker owns the shared user pool + fires the real transition on its
+ * own side of the port, so a page-local gate registered here would
+ * either never run (silently useless) or run too late to actually
+ * block anything. Rather than accept a callback that quietly does
+ * nothing, fail loudly at registration time — same defensive pattern
+ * as {@link signInWithCredential}. Follow-up: thread registration
+ * through the worker RPC protocol so the gate can run host-side before
+ * the worker commits a transition.
+ */
+export function beforeAuthStateChanged(): never {
+  throw makeUnsupported('beforeAuthStateChanged');
+}
+
+function makeUnsupported(api: string): Error & { code: string } {
+  const err = new Error(
+    `${api} is not supported over the SharedWorker yet (provider flows need ` +
+    'the in-page AuthFlowResolver). Follow-up: thread the resolver through or ' +
+    'run the flow in-page and hand the credential to the worker.',
+  ) as Error & { code: string };
+  err.code = 'auth/operation-not-supported-in-this-environment';
+  return err;
+}