@pyric/cli 0.1.0-alpha.30.1 → 0.1.0-alpha.31

package/src/serve/worker/__tests__/auth-credential-sign-in.test.ts

@@ -0,0 +1,343 @@
+/**
+ * Served `signInWithCredential` with an email credential (#1448).
+ *
+ * The served client must carry the credential's secret (the password, or the
+ * link for `credentialWithLink`) to the host, and the host must check it with
+ * the engine, as `signInWithEmailAndPassword` and `signInWithEmailLink` do.
+ * A wrong, empty or missing secret is refused with the in-page codes and binds
+ * no session to the port.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { EmailAuthProvider, GoogleAuthProvider, getAuth, sandbox as authSandbox } from 'pyric/auth';
+import { initializeSandbox } from 'pyric/sandbox';
+import { getFirestore } from 'pyric/firestore';
+import { handleMessage, type HostCtx, type PortLike } from '../host.js';
+import { portSession } from '../host-auth.js';
+import { signInWithCredentialPayload, type CredentialPayload } from '../host/auth-credential-sign-in.js';
+import type { InboundMessage, OutboundMessage, ResMessage, ResolvedIdentity } from '../protocol.js';
+import { wirePort } from '../client/core.js';
+import type { ClientPort } from '../client/handles.js';
+import {
+  createUserWithEmailAndPassword,
+  getAuth as getClientAuth,
+  sendSignInLinkToEmail,
+  signInWithCredential,
+  signOut,
+  stageSignInResult,
+  type ClientDb,
+} from '../client.js';
+
+const OWNER = 'owner@example.com';
+const PASSWORD = 'right-password';
+
+function harness() {
+  const sandbox = initializeSandbox();
+  const ctx: HostCtx = { sandbox, db: getFirestore(sandbox), subs: new Map(), sessionMode: 'LOCAL' };
+  let clientPort!: ClientPort;
+  const hostPort: PortLike = {
+    postMessage(message: OutboundMessage) {
+      clientPort.onmessage?.({ data: message } as MessageEvent<OutboundMessage>);
+    },
+  };
+  clientPort = {
+    onmessage: null,
+    postMessage(message: InboundMessage) { void handleMessage(ctx, hostPort, message); },
+    start() {},
+  };
+  wirePort(clientPort);
+  const clientDb: ClientDb = { __kind: 'client-db', port: clientPort };
+  const clientAuth = getClientAuth(clientDb);
+
+  const rawMessages: OutboundMessage[] = [];
+  const rawPort: PortLike = { postMessage: (message) => rawMessages.push(message) };
+  async function sendRaw(fields: Record<string, unknown>): Promise<ResMessage> {
+    const id = crypto.randomUUID();
+    await handleMessage(ctx, rawPort, { ...fields, t: 'op', id, method: 'auth.signInWithCredential' } as InboundMessage);
+    const response = rawMessages.find((entry): entry is ResMessage => entry.t === 'res' && entry.id === id);
+    if (response === undefined) throw new Error('No response from host');
+    return response;
+  }
+
+  async function createOwner(): Promise<string> {
+    const created = await createUserWithEmailAndPassword(clientAuth, OWNER, PASSWORD);
+    await signOut(clientAuth);
+    return created.user.uid;
+  }
+
+  function userCount(): number {
+    return authSandbox.listUsers(getAuth(sandbox)).length;
+  }
+
+  return { ctx, sandbox, hostPort, clientAuth, rawPort, sendRaw, createOwner, userCount };
+}
+
+const nothingStaged = (): null => null;
+
+async function refusal(promise: Promise<unknown>): Promise<string> {
+  try {
+    await promise;
+  } catch (error) {
+    return (error as { code?: string }).code ?? String(error);
+  }
+  return 'signed-in';
+}
+
+describe('served signInWithCredential with an email credential', () => {
+  it('refuses a wrong password, an empty password and an unknown email with the in-page codes', async () => {
+    const h = harness();
+    await h.createOwner();
+    const before = h.userCount();
+
+    const wrong = EmailAuthProvider.credential(OWNER, 'wrong-password');
+    expect(await refusal(signInWithCredential(h.clientAuth, wrong))).toBe('auth/wrong-password');
+    const empty = EmailAuthProvider.credential(OWNER, '');
+    expect(await refusal(signInWithCredential(h.clientAuth, empty))).toBe('auth/missing-password');
+    const unknown = EmailAuthProvider.credential('nobody@example.com', PASSWORD);
+    expect(await refusal(signInWithCredential(h.clientAuth, unknown))).toBe('auth/user-not-found');
+
+    expect(portSession(h.ctx, h.hostPort)).toBeNull();
+    expect(h.clientAuth.currentUser).toBeNull();
+    expect(h.userCount()).toBe(before);
+  });
+
+  it('signs in with the right password and reports a null providerId', async () => {
+    const h = harness();
+    const uid = await h.createOwner();
+
+    const result = await signInWithCredential(h.clientAuth, EmailAuthProvider.credential(OWNER, PASSWORD));
+
+    expect(result.user.uid).toBe(uid);
+    expect(result.providerId).toBeNull();
+    expect(result._additionalUserInfo?.isNewUser).toBe(false);
+    expect(portSession(h.ctx, h.hostPort)?.user.uid).toBe(uid);
+  });
+
+  it('refuses an email link the engine did not issue and accepts one it mailed', async () => {
+    const h = harness();
+    const madeUp = 'https://example.com/__/auth/action?mode=signIn&oobCode=made-up&apiKey=fake';
+    const forged = EmailAuthProvider.credentialWithLink(OWNER, madeUp);
+    expect(await refusal(signInWithCredential(h.clientAuth, forged))).toBe('auth/invalid-action-code');
+    expect(portSession(h.ctx, h.hostPort)).toBeNull();
+
+    await sendSignInLinkToEmail(h.clientAuth, OWNER, { url: 'https://example.com/finish', handleCodeInApp: true });
+    const mail = authSandbox.takeAuthMail(getAuth(h.sandbox), OWNER);
+    if (mail === null) throw new Error('No sign-in link was mailed');
+    const result = await signInWithCredential(h.clientAuth, EmailAuthProvider.credentialWithLink(OWNER, mail.link));
+
+    expect(result.user.email).toBe(OWNER);
+    expect(result.providerId).toBeNull();
+    expect(portSession(h.ctx, h.hostPort)?.user.uid).toBe(result.user.uid);
+  });
+
+  it('refuses a password credential that carries no secret, nested or flat', async () => {
+    const h = harness();
+    await h.createOwner();
+
+    const nested = await h.sendRaw({ credential: { providerId: 'password', email: OWNER } });
+    expect(nested).toMatchObject({ ok: false, error: { code: 'auth/invalid-credential' } });
+    const flat = await h.sendRaw({ providerId: 'password', email: OWNER });
+    expect(flat).toMatchObject({ ok: false, error: { code: 'auth/invalid-credential' } });
+    const noPassword = await h.sendRaw({ credential: { providerId: 'password', signInMethod: 'password', email: OWNER } });
+    expect(noPassword).toMatchObject({ ok: false, error: { code: 'auth/missing-password' } });
+
+    expect(portSession(h.ctx, h.rawPort)).toBeNull();
+  });
+});
+
+describe('served signInWithCredential with a provider id that is not federated (#1466)', () => {
+  function ownerProviderIds(h: ReturnType<typeof harness>, uid: string): string[] {
+    const owner = authSandbox.listUsers(getAuth(h.sandbox)).find((user) => user.uid === uid);
+    return owner?.providerUserInfo.map((entry) => entry.providerId) ?? [];
+  }
+
+  function refusedPayloads(uid: string): Record<string, CredentialPayload> {
+    return {
+      capitalPassword: { providerId: 'Password', signInMethod: 'password', email: OWNER, password: 'wrong' },
+      trailingSpacePassword: { providerId: 'password ', signInMethod: 'password', email: OWNER, password: 'wrong' },
+      emailLink: { providerId: 'emailLink', email: OWNER },
+      phone: { providerId: 'phone', uid },
+      anonymous: { providerId: 'anonymous', uid },
+      firebase: { providerId: 'firebase', uid },
+      madeUp: { providerId: 'acme', email: OWNER },
+      emptyOidc: { providerId: 'oidc.', email: OWNER },
+      googleWithPasswordMethod: { providerId: 'google.com', signInMethod: 'password', email: OWNER, password: 'wrong' },
+    };
+  }
+
+  function thrownCode(run: () => unknown): string {
+    try {
+      run();
+    } catch (error) {
+      return (error as { code?: string }).code ?? String(error);
+    }
+    return 'signed-in';
+  }
+
+  it('refuses each look-alike and unknown id with auth/no-mock-configured and leaves the owner untouched', async () => {
+    const h = harness();
+    const uid = await h.createOwner();
+    const before = h.userCount();
+    const auth = getAuth(h.sandbox);
+
+    for (const [name, payload] of Object.entries(refusedPayloads(uid))) {
+      const code = thrownCode(() => signInWithCredentialPayload(auth, payload, { tenantId: null }, nothingStaged));
+      expect({ name, code }).toEqual({ name, code: 'auth/no-mock-configured' });
+    }
+
+    expect(ownerProviderIds(h, uid)).toEqual(['password']);
+    expect(h.userCount()).toBe(before);
+  });
+
+  it('checks a disabled provider first, as in-page does, and refuses it with auth/operation-not-allowed', async () => {
+    const h = harness();
+    const uid = await h.createOwner();
+    const auth = getAuth(h.sandbox);
+    authSandbox.setAuthProviderConfig(auth, 'anonymous', false);
+    authSandbox.setAuthProviderConfig(auth, 'phone', false);
+
+    for (const providerId of ['anonymous', 'phone']) {
+      const code = thrownCode(() => signInWithCredentialPayload(auth, { providerId, uid }, { tenantId: null }, nothingStaged));
+      expect({ providerId, code }).toEqual({ providerId, code: 'auth/operation-not-allowed' });
+    }
+
+    expect(ownerProviderIds(h, uid)).toEqual(['password']);
+  });
+
+  it('refuses a look-alike over the wire, nested or flat, and binds no session', async () => {
+    const h = harness();
+    const uid = await h.createOwner();
+
+    const nested = await h.sendRaw({ credential: { providerId: 'Password', email: OWNER } });
+    expect(nested).toMatchObject({ ok: false, error: { code: 'auth/no-mock-configured' } });
+    const flat = await h.sendRaw({ providerId: 'phone', uid });
+    expect(flat).toMatchObject({ ok: false, error: { code: 'auth/no-mock-configured' } });
+
+    expect(portSession(h.ctx, h.rawPort)).toBeNull();
+    expect(ownerProviderIds(h, uid)).toEqual(['password']);
+  });
+
+});
+
+describe('served signInWithCredential with a federated credential needs a staged result (#1466)', () => {
+  function stagedIdentity(uid: string, providerId = 'google.com'): ResolvedIdentity {
+    return { uid, providerId, email: 'staged@example.com', displayName: null, photoURL: null, customClaims: {} };
+  }
+
+  function thrownCode(run: () => unknown): string {
+    try {
+      run();
+    } catch (error) {
+      return (error as { code?: string }).code ?? String(error);
+    }
+    return 'signed-in';
+  }
+
+  it('refuses a google.com and an oidc.acme credential with nothing staged, and creates no user', async () => {
+    const h = harness();
+    await h.createOwner();
+    const before = h.userCount();
+    const auth = getAuth(h.sandbox);
+
+    for (const payload of [
+      { providerId: 'google.com', idToken: 'token-1' },
+      { providerId: 'google.com', email: OWNER },
+      { providerId: 'oidc.acme', email: 'o@example.com' },
+    ]) {
+      const code = thrownCode(() => signInWithCredentialPayload(auth, payload, { tenantId: null }, nothingStaged));
+      expect({ payload, code }).toEqual({ payload, code: 'auth/no-mock-configured' });
+    }
+    expect(h.userCount()).toBe(before);
+  });
+
+  it('signs in as the staged identity, not the uid or email the payload asserts', async () => {
+    const h = harness();
+    const ownerUid = await h.createOwner();
+    const auth = getAuth(h.sandbox);
+
+    const result = signInWithCredentialPayload(
+      auth,
+      { providerId: 'google.com', uid: ownerUid, email: OWNER },
+      { tenantId: null },
+      (providerId) => (providerId === 'google.com' ? stagedIdentity('staged-uid') : null),
+    );
+
+    expect(result.providerId).toBe('google.com');
+    expect(result.session.user.uid).toBe('staged-uid');
+    expect(result.session.user.email).toBe('staged@example.com');
+  });
+
+  it('refuses a staged result with an empty uid instead of falling back to its email', async () => {
+    const h = harness();
+    await h.createOwner();
+    const auth = getAuth(h.sandbox);
+    const emptyUid = { ...stagedIdentity(''), email: OWNER };
+
+    const code = thrownCode(() => signInWithCredentialPayload(auth, { providerId: 'google.com' }, { tenantId: null }, () => emptyUid));
+
+    expect(code).toBe('auth/no-mock-configured');
+  });
+
+  it('over the wire, a result the client staged signs in once, on the port that staged it', async () => {
+    const h = harness();
+    await h.createOwner();
+    const google = GoogleAuthProvider.credential('any-token');
+
+    stageSignInResult(h.clientAuth, { user: { uid: 'staged-uid', email: 'staged@example.com' }, providerId: 'google.com' });
+    const signedIn = await signInWithCredential(h.clientAuth, google);
+    expect(signedIn.user.uid).toBe('staged-uid');
+    expect(signedIn.providerId).toBe('google.com');
+    await signOut(h.clientAuth);
+
+    expect(await refusal(signInWithCredential(h.clientAuth, google))).toBe('auth/no-mock-configured');
+  });
+
+  it('refuses a profile field the host would refuse at the call, not as an unhandled rejection', async () => {
+    const h = harness();
+    const unhandled: unknown[] = [];
+    const record = (reason: unknown) => unhandled.push(reason);
+    process.on('unhandledRejection', record);
+    try {
+      for (const user of [{ uid: 'u1', email: 42 }, { uid: 'u1', displayName: {} }, { uid: 'u1', photoURL: 7 }]) {
+        const result = { user, providerId: 'google.com' } as unknown as Parameters<typeof stageSignInResult>[1];
+        expect(() => stageSignInResult(h.clientAuth, result)).toThrow('strings or null');
+      }
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    } finally {
+      process.off('unhandledRejection', record);
+    }
+    expect(unhandled).toEqual([]);
+  });
+
+  it('drops an error reply to a staged result instead of leaving an unhandled rejection', async () => {
+    const unhandled: unknown[] = [];
+    const record = (reason: unknown) => unhandled.push(reason);
+    let port!: ClientPort;
+    port = {
+      onmessage: null,
+      postMessage(message: InboundMessage) {
+        const isOp = message.t === 'op';
+        if (!isOp) return;
+        const refusal = { t: 'res', id: message.id, ok: false, error: { code: 'invalid-argument', message: 'refused' } };
+        queueMicrotask(() => port.onmessage?.({ data: refusal } as MessageEvent<OutboundMessage>));
+      },
+      start() {},
+    };
+    wirePort(port);
+    const refusingAuth = getClientAuth({ __kind: 'client-db', port } as ClientDb);
+    process.on('unhandledRejection', record);
+    try {
+      stageSignInResult(refusingAuth, { user: { uid: 'u1' }, providerId: 'google.com' });
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    } finally {
+      process.off('unhandledRejection', record);
+    }
+    expect(unhandled).toEqual([]);
+  });
+
+  it('refuses to stage a result with an empty uid or provider at the call', () => {
+    const h = harness();
+    expect(() => stageSignInResult(h.clientAuth, { user: { uid: '' }, providerId: 'google.com' })).toThrow('non-empty');
+    expect(() => stageSignInResult(h.clientAuth, { user: { uid: 'u' }, providerId: null })).toThrow('non-empty');
+  });
+});

package/src/serve/worker/__tests__/auth-m2-parity.test.ts

@@ -39,6 +39,7 @@ import {
   updateProfile,
   updateCurrentUser,
   signInWithCredential,
+  stageSignInResult,
   onAuthStateChanged,
   onIdTokenChanged,
   listUsers,
@@ -61,6 +62,22 @@ import { getDatabase } from 'pyric/database';
 import { getAuth, sandbox as authSandboxOps } from 'pyric/auth';
 import type { ClientPort } from '../client/handles.js';
 
+/** Stage the identity the port's next federated signInWithCredential signs in as (#1466). */
+async function stageOnPort(
+  ctx: HostCtx,
+  port: PortLike,
+  identity: { uid: string; email: string; displayName?: string | null; providerId?: string },
+): Promise<void> {
+  await handleMessage(ctx, port, {
+    t: 'op',
+    id: `stage-${identity.uid}`,
+    method: 'auth.mockSignInResult',
+    identity: {
+      providerId: 'google.com', displayName: null, photoURL: null, customClaims: {}, ...identity,
+    },
+  } as InboundMessage);
+}
+
 function tick(ms = 15): Promise<void> {
   return new Promise((r) => setTimeout(r, ms));
 }
@@ -263,6 +280,15 @@ describe('Web SharedWorker Auth Parity & Bridge RPCs (M2)', () => {
   it('4. signInWithCredential seeds providerData and authenticates over the SharedWorker', async () => {
     const { clientAuth } = await createTestHarness();
 
+    stageSignInResult(clientAuth, {
+      user: {
+        uid: 'google-user-999',
+        email: 'googleuser@example.com',
+        displayName: 'Google OAuth User',
+        photoURL: 'https://example.com/avatar.png',
+      },
+      providerId: 'google.com',
+    });
     const cred = await signInWithCredential(clientAuth, {
       providerId: 'google.com',
       idToken: 'mock-google-id-token-999',
@@ -459,6 +485,7 @@ describe('Web SharedWorker Auth Parity & Bridge RPCs (M2)', () => {
       },
     };
 
+    await stageOnPort(ctx, testPort, { uid: 'oauth-tenant-user', email: 'oauth-tenant@example.com' });
     await handleMessage(ctx, testPort, {
       t: 'op',
       id: 'oauth-tenant-op',
@@ -571,7 +598,22 @@ describe('Web SharedWorker Auth Parity & Bridge RPCs (M2)', () => {
       },
     };
 
-    // Swift and Flutter send providerId, idToken, accessToken, rawNonce directly on the op message
+    // Swift and Flutter send providerId, idToken, accessToken, rawNonce directly on the op message.
+    // With nothing staged the host refuses it, as in-page does (#1466).
+    const flatPayload = {
+      method: 'auth.signInWithCredential',
+      providerId: 'google.com',
+      idToken: 'token-oauth-flat',
+      email: 'flat-mobile@example.com',
+      displayName: 'Flat Mobile User',
+      tenantId: 'tenant-mobile',
+    };
+    await handleMessage(ctx, testPort, { ...flatPayload, t: 'op', id: 'flat-unstaged-op' } as unknown as InboundMessage);
+    const unstaged = sentMessages.find((m) => m.t === 'res' && m.id === 'flat-unstaged-op');
+    expect(unstaged).toMatchObject({ ok: false, error: { code: 'auth/no-mock-configured' } });
+    expect(portSession(ctx, testPort)).toBeNull();
+
+    await stageOnPort(ctx, testPort, { uid: 'flat-mobile-user', email: 'flat-mobile@example.com', displayName: 'Flat Mobile User' });
     await handleMessage(ctx, testPort, {
       t: 'op',
       id: 'flat-oauth-op',
@@ -641,6 +683,7 @@ describe('Web SharedWorker Auth Parity & Bridge RPCs (M2)', () => {
     expect(signInRes.value.additionalUserInfo.isNewUser).toBe(false);
 
     // 3. auth.signInWithCredential on new user should return isNewUser = true
+    await stageOnPort(ctx, testPort, { uid: 'oauth-fresh-user', email: 'oauth-fresh@example.com' });
     await handleMessage(ctx, testPort, {
       t: 'op',
       id: 'oauth-new-op',
@@ -657,6 +700,7 @@ describe('Web SharedWorker Auth Parity & Bridge RPCs (M2)', () => {
     expect(oauthNewRes.value.additionalUserInfo.isNewUser).toBe(true);
 
     // 4. auth.signInWithCredential on existing user should return isNewUser = false
+    await stageOnPort(ctx, testPort, { uid: 'oauth-fresh-user', email: 'oauth-fresh@example.com' });
     await handleMessage(ctx, testPort, {
       t: 'op',
       id: 'oauth-existing-op',

package/src/serve/worker/__tests__/staged-sign-in-results.test.ts

@@ -0,0 +1,139 @@
+/**
+ * The host keeps sign-in results a served test staged (`auth.mockSignInResult`)
+ * per port, one slot per provider id (#1466 part 2).
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { initializeSandbox } from 'pyric/sandbox';
+import { getFirestore } from 'pyric/firestore';
+import { cleanupPort, handleMessage, type HostCtx, type PortLike } from '../host.js';
+import { stagedSignInResultsFor } from '../host-auth.js';
+import { createStagedSignInResults } from '../host/staged-sign-in-results.js';
+import type { InboundMessage, OutboundMessage, ResMessage, ResolvedIdentity } from '../protocol.js';
+
+function identity(uid: string, providerId = 'google.com'): ResolvedIdentity {
+  return { uid, providerId, email: `${uid}@example.com`, displayName: null, photoURL: null, customClaims: {} };
+}
+
+function recordingPort(): PortLike & { messages: OutboundMessage[] } {
+  const messages: OutboundMessage[] = [];
+  return { messages, postMessage: (message) => messages.push(message) };
+}
+
+function hostCtx(): HostCtx {
+  const sandbox = initializeSandbox();
+  return { sandbox, db: getFirestore(sandbox), subs: new Map(), sessionMode: 'LOCAL' };
+}
+
+async function stageOverPort(
+  ctx: HostCtx,
+  port: PortLike & { messages: OutboundMessage[] },
+  staged: unknown,
+): Promise<ResMessage> {
+  const id = crypto.randomUUID();
+  await handleMessage(ctx, port, { t: 'op', id, method: 'auth.mockSignInResult', identity: staged } as InboundMessage);
+  const reply = port.messages.find((message): message is ResMessage => message.t === 'res' && message.id === id);
+  if (reply === undefined) throw new Error('No response from host');
+  return reply;
+}
+
+describe('createStagedSignInResults', () => {
+  it('hands a staged result to one take, then has none', () => {
+    const staged = createStagedSignInResults();
+    const port = recordingPort();
+    staged.stage(port, identity('alice'));
+
+    expect(staged.take(port, 'google.com')?.uid).toBe('alice');
+    expect(staged.take(port, 'google.com')).toBeNull();
+  });
+
+  it('keeps the last result staged for a provider', () => {
+    const staged = createStagedSignInResults();
+    const port = recordingPort();
+    staged.stage(port, identity('first'));
+    staged.stage(port, identity('second'));
+
+    expect(staged.take(port, 'google.com')?.uid).toBe('second');
+    expect(staged.take(port, 'google.com')).toBeNull();
+  });
+
+  it('matches by provider id', () => {
+    const staged = createStagedSignInResults();
+    const port = recordingPort();
+    staged.stage(port, identity('gh', 'github.com'));
+
+    expect(staged.take(port, 'google.com')).toBeNull();
+    expect(staged.take(port, 'github.com')?.uid).toBe('gh');
+  });
+
+  it('keeps a result staged on one port from being taken on another', () => {
+    const staged = createStagedSignInResults();
+    const stagingPort = recordingPort();
+    const otherPort = recordingPort();
+    staged.stage(stagingPort, identity('alice'));
+
+    expect(staged.take(otherPort, 'google.com')).toBeNull();
+    expect(staged.take(stagingPort, 'google.com')?.uid).toBe('alice');
+  });
+});
+
+describe('createStagedSignInResults clear', () => {
+  it('drops every provider the port staged and leaves other ports alone', () => {
+    const staged = createStagedSignInResults();
+    const port = recordingPort();
+    const otherPort = recordingPort();
+    staged.stage(port, identity('alice'));
+    staged.stage(port, identity('gh', 'github.com'));
+    staged.stage(otherPort, identity('bob'));
+
+    staged.clear(port);
+
+    expect(staged.take(port, 'google.com')).toBeNull();
+    expect(staged.take(port, 'github.com')).toBeNull();
+    expect(staged.take(otherPort, 'google.com')?.uid).toBe('bob');
+  });
+});
+
+describe('auth.mockSignInResult on the host', () => {
+  it('stages the identity for the calling port and replies null', async () => {
+    const ctx = hostCtx();
+    const port = recordingPort();
+    const otherPort = recordingPort();
+
+    const reply = await stageOverPort(ctx, port, identity('alice'));
+
+    expect(reply).toMatchObject({ ok: true, value: null });
+    expect(stagedSignInResultsFor(ctx).take(otherPort, 'google.com')).toBeNull();
+    expect(stagedSignInResultsFor(ctx).take(port, 'google.com')).toEqual(identity('alice'));
+  });
+
+  it('drops what a port staged when the host tears the port down', async () => {
+    const ctx = hostCtx();
+    const port = recordingPort();
+    await stageOverPort(ctx, port, identity('alice'));
+
+    cleanupPort(ctx, port);
+
+    expect(stagedSignInResultsFor(ctx).take(port, 'google.com')).toBeNull();
+  });
+
+  it('refuses a result without a uid and stages nothing', async () => {
+    const ctx = hostCtx();
+    const port = recordingPort();
+    const { uid: _uid, ...withoutUid } = identity('alice');
+
+    const reply = await stageOverPort(ctx, port, withoutUid);
+
+    expect(reply).toMatchObject({ ok: false, error: { code: 'invalid-argument' } });
+    expect(stagedSignInResultsFor(ctx).take(port, 'google.com')).toBeNull();
+  });
+
+  it('refuses a result whose providerId is not a string', async () => {
+    const ctx = hostCtx();
+    const port = recordingPort();
+
+    const reply = await stageOverPort(ctx, port, { ...identity('alice'), providerId: 7 });
+
+    expect(reply).toMatchObject({ ok: false, error: { code: 'invalid-argument' } });
+  });
+});

package/src/serve/worker/ai-proxy-paths.ts

@@ -0,0 +1,35 @@
+/**
+ * The dev server's AI proxy routes, as the browser engines name them, and
+ * the gemini engine a browser page or SharedWorker runs.
+ *
+ * Browser-safe: the worker host and the served `firebase/ai` entry import
+ * this, so it imports nothing from node.
+ */
+import type { AiEngineConfigWire } from './protocol.js';
+
+/** The serve proxy route the browser openai engine defaults to (#98.2). */
+export const AI_PROXY_PATH = '/__pyric/ai-proxy';
+
+/** The serve route a browser gemini engine sends through. The server sends
+ *  each request on to Gemini with the key from its own environment (#1584). */
+export const GEMINI_PROXY_PATH = `${AI_PROXY_PATH}/gemini`;
+
+type GeminiWire = Extract<AiEngineConfigWire, { kind: 'gemini' }>;
+
+/** A browser gemini engine config: the wire shape, plus the flag that tells
+ *  the engine the dev server attaches the credentials. */
+export type BrowserGeminiEngine = GeminiWire & { serverAttachesAuth?: true };
+
+/**
+ * The gemini engine config for a browser. The browser has no server
+ * environment, so a config without its own `apiKey` sends through the dev
+ * server's {@link GEMINI_PROXY_PATH}, which attaches the key and sends to
+ * the server's configured base URL: the key never reaches the browser. A
+ * config with an `apiKey` already holds its key in the browser, so it keeps
+ * its own target.
+ */
+export function browserGeminiEngine(wire: GeminiWire): BrowserGeminiEngine {
+  const holdsItsOwnKey = wire.apiKey !== undefined;
+  if (holdsItsOwnKey) return { ...wire };
+  return { kind: 'gemini', baseUrl: GEMINI_PROXY_PATH, serverAttachesAuth: true };
+}

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

@@ -3,7 +3,7 @@
  * as the mirror AnswerEngine on the worker path (see entries/ai.ts).
  */
 
-import type { AiEngineConfigWire, InboundMessage } from '../protocol.js';
+import type { AiAppCheckWire, AiEngineConfigWire, InboundMessage } from '../protocol.js';
 import { closeSubscription, nextId, nextSubId, openSnapshotSubscription, rpc } from './core.js';
 import type { ClientDb } from './handles.js';
 
@@ -26,6 +26,8 @@ export interface AiOpParams {
   request: Record<string, unknown>;
   /** First-op engine config — see {@link AiEngineConfigWire}. */
   engine?: AiEngineConfigWire;
+  /** The App Check claim an app-backed handle attaches — see {@link AiAppCheckWire}. */
+  appCheck?: AiAppCheckWire;
 }
 
 /** Unary `generateContent` against the worker's broker. Resolves with the
@@ -42,6 +44,7 @@ export async function aiGenerateContent(
     model: params.model,
     request: params.request,
     ...(params.engine !== undefined ? { engine: params.engine } : {}),
+    ...(params.appCheck !== undefined ? { appCheck: params.appCheck } : {}),
   })) as Record<string, unknown>;
 }
 
@@ -57,6 +60,7 @@ export async function aiCountTokens(
     model: params.model,
     request: params.request,
     ...(params.engine !== undefined ? { engine: params.engine } : {}),
+    ...(params.appCheck !== undefined ? { appCheck: params.appCheck } : {}),
   })) as Record<string, unknown>;
 }
 
@@ -100,6 +104,7 @@ export async function* aiStreamGenerateContent(
     model: params.model,
     request: params.request,
     ...(params.engine !== undefined ? { engine: params.engine } : {}),
+    ...(params.appCheck !== undefined ? { appCheck: params.appCheck } : {}),
   } satisfies InboundMessage);
   if (!opened) push({
     kind: 'error',