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

package/src/serve/namespace.ts

@@ -23,7 +23,7 @@ import { createReadStream, existsSync, statSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { ActivityIncident } from 'pyric/firestore/internal';
-import { collectBody } from '../bridge/server/peer.js';
+import { BODY_TOO_LARGE_CODE, collectBody } from '../bridge/server/peer.js';
 import { handleIndexConfig } from './index-config-route.js';
 import { StateFileError, type StateSection, type StateStore } from './state-store.js';
 import { createWriterLock, type WriterLock } from './writer-lock.js';
@@ -32,7 +32,9 @@ import { pipeFileToResponse, getHeader, isAllowedHost, isAllowedOrigin, isAllowe
 import type { InitPayload } from './init-payload.js';
 import { handleActivity } from './activity-route.js';
 import { handleAiProxy, AI_PROXY_ROUTE } from './ai-proxy.js';
+import { createGeminiProxy, isGeminiProxyPath, type GeminiProxyConfig } from './gemini-proxy.js';
 import { aiTerminalBlockFor, type AiDiagnosticPayload } from './ai-terminal-blocks.js';
+import { sanitizeForTerminal, stripTerminalControls } from './ai-terminal-text.js';
 import { createSiteTreeHandler } from './site-tree.js';
 import { handleAvatar } from './assets/avatar-route.js';
 import { ASSETS_ROUTE_PREFIX } from './assets/avatar-url.js';
@@ -147,6 +149,10 @@ export interface NamespaceOptions {
    *  (local Ollama). Always mounted — the route only touches the network
    *  when a request arrives. */
   aiProxyUpstream?: string;
+  /** The gemini engine `/__pyric/ai-proxy/gemini` sends for a browser engine
+   *  (#1584): the Vite plugin's `ai.engine` when it is gemini. Absent, it
+   *  sends to Google AI Studio with the key from this process's environment. */
+  aiGemini?: GeminiProxyConfig;
   /** Receives one handshake beacon per pyric-launched child (`POST
    *  /__pyric/beacon`, sent by `@pyric/cli/register` once its hooks and
    *  net-guard are installed). Absent means the route still 204s; the child
@@ -354,6 +360,11 @@ async function handleCapture(
 
 const DENIAL_THROTTLE_MS = 5_000;
 
+/** Largest relayed denial the route reads. A real one is a message, a path, a
+ *  uid and a short owner stack, a few KiB at most; the index route's 64 KiB
+ *  leaves room for a deep stack without letting a page grow the server. */
+export const DENIAL_BODY_LIMIT_BYTES = 64 * 1024;
+
 /** Loosely-typed mirror of the client's relay payload — JSON from the served
  *  page, read defensively since nothing here enforces the wire shape. */
 interface DenialRelayPayload {
@@ -397,27 +408,48 @@ export function createDenialThrottle(windowMs: number = DENIAL_THROTTLE_MS): {
 }
 export type DenialThrottle = ReturnType<typeof createDenialThrottle>;
 
+/** A page-supplied string as one terminal-safe line. Every field of a relayed
+ *  denial comes from the served page, which need not be the developer's own
+ *  code, so none of it reaches the terminal with control characters intact. */
+function pageText(value: string): string {
+  return sanitizeForTerminal(value);
+}
+
+/** A multi-line page-supplied string (a query-proof remediation) as indented
+ *  terminal lines. Each line keeps its spacing and its whole length, because a
+ *  reader pastes the `pyric rules test` command and the `Fixture case:` JSON
+ *  out of it; only control and bidi characters are replaced. The denial body
+ *  limit bounds the total, so no line or line count is cut here. */
+function pageLines(value: string): string[] {
+  const lines = value.split(/\r?\n/).map((line) => stripTerminalControls(line).trimEnd());
+  const first = lines.findIndex((line) => line.length > 0);
+  if (first === -1) return [];
+  let last = lines.length - 1;
+  while (lines[last]!.length === 0) last -= 1;
+  return lines.slice(first, last + 1).map((line) => (line.length > 0 ? `      ${line}` : ''));
+}
+
 /** Format a relayed denial into the compact terminal block: the message,
  *  then (when present) the request method/path, the auth uid, and any
  *  remediation guidance. A few lines, never a JSON dump. */
 export function formatDenialBlock(payload: DenialRelayPayload): string {
   const message = typeof payload.message === 'string' ? payload.message : 'permission denied';
-  const lines = [`  ⚠ [pyric] denied: ${message}`];
+  const lines = [`  ⚠ [pyric] denied: ${pageText(message)}`];
   const ctx = payload.denialContext;
   const request = ctx?.request;
   if (request?.method && request?.path) {
-    const instance = typeof payload.instance === 'string' ? ` (${payload.instance})` : '';
-    lines.push(`      ${request.method} ${request.path}${instance}`);
+    const instance = typeof payload.instance === 'string' ? ` (${pageText(payload.instance)})` : '';
+    lines.push(`      ${pageText(String(request.method))} ${pageText(String(request.path))}${instance}`);
   }
   const uid = ctx?.auth?.uid;
-  lines.push(`      auth: ${uid ?? 'anonymous'}`);
+  lines.push(`      auth: ${uid === undefined || uid === null ? 'anonymous' : pageText(String(uid))}`);
   // An RTDB message names no rule, so the block names the deciding one.
   if (ctx?.engine === 'rtdb' && typeof ctx.matchedRule === 'string') {
-    const node = typeof ctx.matchedPath === 'string' ? `${ctx.matchedPath} ` : '';
-    lines.push(`      rule: ${node}${ctx.matchedRule}`);
+    const node = typeof ctx.matchedPath === 'string' ? `${pageText(ctx.matchedPath)} ` : '';
+    lines.push(`      rule: ${node}${pageText(ctx.matchedRule)}`);
   }
   const remediation = typeof payload.remediation === 'string' ? payload.remediation : ctx?.remediation;
-  if (remediation) lines.push(`      ${remediation}`);
+  if (remediation) lines.push(...pageLines(String(remediation)));
   lines.push(...ownerLines(payload.owners));
   return lines.join('\n');
 }
@@ -437,7 +469,7 @@ function isRelayedFrame(value: unknown): value is RelayedFrame {
 /** A frame's file as a reader looks for it: a served URL loses its origin and query. */
 function frameLocation(frame: RelayedFrame): string {
   const path = frame.file.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/i, '').replace(/[?#].*$/, '');
-  return `${path}:${frame.line}`;
+  return pageText(`${path}:${frame.line}`);
 }
 
 /**
@@ -450,7 +482,7 @@ function ownerLines(owners: unknown): string[] {
   if (!Array.isArray(owners)) return [];
   const frame = owners.find((owner) => (owner as { kind?: unknown })?.kind === 'frame');
   if (!isRelayedFrame(frame)) return [];
-  const name = typeof frame.function === 'string' && frame.function.length > 0 ? `${frame.function} ` : '';
+  const name = typeof frame.function === 'string' && frame.function.length > 0 ? `${pageText(frame.function)} ` : '';
   const lines = [`      owner: ${name}${frameLocation(frame)}`];
   const stack = (frame as { stack?: unknown }).stack;
   const chain = Array.isArray(stack) ? stack.filter(isRelayedFrame) : [];
@@ -492,8 +524,12 @@ export function noteAiDiagnostic(
  *  (target, reason) per window is the right volume for every one of them. A
  *  rules denial's target also names its RTDB instance, so the same path
  *  denied on two instances prints once for each.
- *  Always 204s (best-effort diagnostics: a malformed body or a caller with no
- *  logger wired must never fail the page that reported the refusal). */
+ *  Answers 204 (best-effort diagnostics: a malformed body or a caller with no
+ *  logger wired must never fail the page that reported the refusal), except
+ *  413 for a body over {@link DENIAL_BODY_LIMIT_BYTES}. On the 0.1.0-alpha.30
+ *  line the namespace runs no loopback guard before this route, so a page on
+ *  any origin can reach here; the body limit and the terminal-text sanitizing
+ *  still apply. */
 async function handleDenials(
   throttle: DenialThrottle,
   logger: ServeLogger | undefined,
@@ -505,7 +541,7 @@ async function handleDenials(
     return;
   }
   try {
-    const payload = (await collectBody(req)) as DenialRelayPayload & AiDiagnosticPayload;
+    const payload = (await collectBody(req, DENIAL_BODY_LIMIT_BYTES)) as DenialRelayPayload & AiDiagnosticPayload;
     const isAiDiagnostic = aiTerminalBlockFor(payload.kind) !== null;
     if (isAiDiagnostic) {
       noteAiDiagnostic(throttle, logger, payload);
@@ -519,7 +555,12 @@ async function handleDenials(
         logger.note(formatDenialBlock(payload));
       }
     }
-  } catch {
+  } catch (error) {
+    const tooLarge = (error as { code?: unknown } | null)?.code === BODY_TOO_LARGE_CODE;
+    if (tooLarge) {
+      res.writeHead(413, { 'content-type': 'text/plain' }).end('Payload Too Large');
+      return;
+    }
     /* malformed body: drop it; this is a diagnostics side channel */
   }
   res.writeHead(204).end();
@@ -573,6 +614,7 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     ? createSiteTreeHandler(siteUiDir, opts.workerVersion, hostedStudioProject(opts))
     : null;
   const denialThrottle = createDenialThrottle();
+  const geminiProxy = createGeminiProxy(opts.aiGemini, denialThrottle, opts.logger);
   // Issued once per server boot. The outer static/Vite host guard protects
   // init.json before this capability is disclosed to the served runtime.
   const activity = opts.activity;
@@ -688,8 +730,18 @@ export function createPyricNamespace(opts: NamespaceOptions) {
       events.handle(req, res);
       return true;
     }
+    const isGeminiProxyRequest = isGeminiProxyPath(url.pathname);
+    if (isGeminiProxyRequest) {
+      // It spends the server's key, so only this app's pages may call it.
+      const hostRefused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+      if (hostRefused) return true;
+      return geminiProxy(req, res, url).then(() => true);
+    }
     const isAiProxyRequest = url.pathname === AI_PROXY_ROUTE || url.pathname.startsWith(`${AI_PROXY_ROUTE}/`);
     if (isAiProxyRequest) {
+      // The upstream may carry the developer's key, so only this server's pages may spend it.
+      const hostRefused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+      if (hostRefused) return true;
       return handleAiProxy(opts.aiProxyUpstream, denialThrottle, req, res, url, opts.logger).then(
         () => true,
       );
@@ -700,6 +752,9 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     }
     const isDenialRequest = url.pathname === '/__pyric/denials';
     if (isDenialRequest) {
+      // No origin guard on the 0.1.0-alpha.30 line: without the learned proxy
+      // ports from #1497, it would refuse the Next dev server's page under
+      // `pyric sandbox -- next dev`. The body limit still applies.
       return handleDenials(denialThrottle, opts.logger, req, res).then(() => true);
     }
     const isInitRequest = url.pathname === '/__pyric/init.json';

package/src/serve/sandbox-session.ts

@@ -44,6 +44,7 @@ import { restoredStateCounts, stateForSummary } from './state-summary.js';
 import { parseStateFile } from './state-file.js';
 import { inlineStorage } from './state-objects.js';
 import { createHostedPersistence, formatStorageRepairs, type HostedPersistence } from './hosted/persistence.js';
+import type { GeminiProxyConfig } from './gemini-proxy.js';
 import {
   runProjectFixturesOnRulesReload,
   type RulesFixtureCheckSummary,
@@ -69,6 +70,8 @@ export interface SandboxSessionOptions {
   deployHostedRules?: (service: 'firestore' | 'database' | 'storage', source: string | null, instance?: DatabaseRulesDestination) => Promise<void>;
   ai?: InitPayload['ai'];
   aiProxyUpstream?: string;
+  /** The gemini engine the dev server's gemini proxy sends for a browser engine. */
+  aiGemini?: GeminiProxyConfig;
   /** Resolved `avatars` option (already reduced by `avatars-config.ts` from
    *  whatever the caller — the Vite plugin or `pyric sandbox` — accepted).
    *  Absent behaves like `{ enabled: false }`: no avatar route is mounted. */
@@ -444,6 +447,7 @@ export async function createSandboxSession(
       workerVersion: options.sdk.workerVersion,
       avatars: avatarsResolver,
       aiProxyUpstream: options.aiProxyUpstream,
+      aiGemini: options.aiGemini,
       activity: options.activity,
       beacon: options.beacon,
       beaconToken: options.beaconToken,

package/src/serve/vite-sandbox-generation.ts

@@ -33,6 +33,7 @@ import { resolveAvatarsConfig, type PyricAvatarsOptions } from './avatars-config
 import { resolveViteRulesConfig } from './vite-rules-source.js';
 import type { ViteWorkerRuntime, ViteWorkerRuntimeStatus } from './vite-worker-runtime.js';
 import { viteWorkerEpochSalt } from './vite-ai-config.js';
+import { geminiProxyConfig } from './gemini-proxy.js';
 import {
   attachViteGenerationBridge,
   createViteGenerationBridge,
@@ -278,6 +279,7 @@ export async function createViteSandboxGeneration(
       ai: aiOptions,
       avatars: avatarsConfig,
       aiProxyUpstream: ai.proxyUpstream,
+      aiGemini: geminiProxyConfig(ai.engineWire),
       activity: (incident) => server.config.logger.warn(formatActivityWarning(incident)),
       logger: {
         info: (message) => server.config.logger.info(message),

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',

package/src/serve/worker/entry.ts

@@ -123,6 +123,8 @@ async function buildCtx(): Promise<HostCtx> {
         ? (url) => new EventSource(url) as unknown as EventSourceLike
         : null,
   });
+  // This worker runs in the browser: the gemini engine sends through the dev server.
+  ctx.aiRunsInBrowser = true;
   return ctx;
 }
 

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

@@ -10,7 +10,9 @@ import { packAiEvidence, setAiEvidence, type AiEvidence } from 'pyric/ai/interna
  *   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.
+ *      origin, so the plain path works from inside the SharedWorker. The
+ *      gemini engine sends through `/__pyric/ai-proxy/gemini`, where the
+ *      server attaches the key, so the key never enters the browser.
  *   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
@@ -31,9 +33,9 @@ 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';
+import { AI_PROXY_PATH, browserGeminiEngine } from './ai-proxy-paths.js';
 
-/** The serve proxy route the browser openai engine defaults to (#98.2). */
-export const AI_PROXY_PATH = '/__pyric/ai-proxy';
+export { AI_PROXY_PATH } from './ai-proxy-paths.js';
 
 /** Is this op an AI op (routed here instead of handleOp)? */
 export function isAiOp(method: OpMessage['method']): boolean {
@@ -50,7 +52,11 @@ type AiOpMessage = Extract<OpMessage, { method: 'ai.generateContent' | 'ai.count
  * plain authoring shapes; predicate matchers never made it across the port —
  * structured clone rejects functions loudly at send time).
  */
-function resolveEngineConfig(wire: AiEngineConfigWire, upstream: HostCtx['aiUpstream']): NonNullable<AIOptions['engine']> {
+function resolveEngineConfig(
+  wire: AiEngineConfigWire,
+  upstream: HostCtx['aiUpstream'],
+  runsInBrowser: boolean,
+): NonNullable<AIOptions['engine']> {
   if (wire.kind === 'openai') {
     const configuredUrl = wire.baseUrl ?? AI_PROXY_PATH;
     const usesProxy = configuredUrl.replace(/\/$/, '') === AI_PROXY_PATH;
@@ -65,18 +71,10 @@ function resolveEngineConfig(wire: AiEngineConfigWire, upstream: HostCtx['aiUpst
   }
   const isGeminiWire = wire.kind === 'gemini';
   if (isGeminiWire) {
-    const result: Record<string, unknown> = {
-      kind: 'gemini',
-    };
-    const hasBaseUrl = wire.baseUrl !== undefined;
-    if (hasBaseUrl) {
-      result.baseUrl = wire.baseUrl;
-    }
-    const hasApiKey = wire.apiKey !== undefined;
-    if (hasApiKey) {
-      result.apiKey = wire.apiKey;
-    }
-    return result as unknown as NonNullable<AIOptions['engine']>;
+    // Node reads the key from its own environment. A browser worker has
+    // none, so it sends through the dev server's gemini proxy.
+    const config = runsInBrowser ? browserGeminiEngine(wire) : wire;
+    return { ...config } as NonNullable<AIOptions['engine']>;
   }
   return {
     kind: 'scripted',
@@ -100,7 +98,7 @@ function resolveEngineConfig(wire: AiEngineConfigWire, upstream: HostCtx['aiUpst
 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, ctx.aiUpstream) } : undefined);
+  const ai = getAI(ctx.sandbox, wire ? { engine: resolveEngineConfig(wire, ctx.aiUpstream, ctx.aiRunsInBrowser === true) } : undefined);
   const target = (ai as unknown as {
     [TARGET_SYMBOL]?: { broker: AiBrokerLike };
   })[TARGET_SYMBOL];
@@ -123,14 +121,14 @@ export async function handleAiOp(ctx: HostCtx, port: PortLike, msg: OpMessage):
     observation.identity(identity);
     switch (aiMsg.method) {
       case 'ai.generateContent': {
-        const response = await broker.generateContent(aiMsg.request, aiMsg.model);
+        const response = await broker.generateContent(aiMsg.request, aiMsg.model, aiMsg.appCheck);
         observation.response(response);
         observation.finish('completed');
         ok(port, aiMsg.id, packAiEvidence(response));
         break;
       }
       case 'ai.countTokens': {
-        const response = await broker.countTokens(aiMsg.request, aiMsg.model);
+        const response = await broker.countTokens(aiMsg.request, aiMsg.model, aiMsg.appCheck);
         observation.response(response);
         observation.finish('completed');
         ok(port, aiMsg.id, packAiEvidence(response));
@@ -156,9 +154,9 @@ export async function handleAiOp(ctx: HostCtx, port: PortLike, msg: OpMessage):
  * (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.
+ * The App Check gate runs first, then 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);
@@ -182,7 +180,9 @@ export function handleAiSub(ctx: HostCtx, port: PortLike, msg: AiStreamSubMessag
       const broker = ensureAiBroker(ctx, msg.engine);
       identity = broker.observationIdentity?.(msg.model);
       observation.identity(identity);
-      for await (const chunk of broker.streamGenerateContent(msg.request, msg.model)) {
+      // The App Check gate answers before any chunk, as AI Logic answers 403 before a stream.
+      await broker.admitAppCheck(msg.model, msg.appCheck);
+      for await (const chunk of broker.streamGenerateContent(msg.request, msg.model, msg.appCheck)) {
         if (cancelled) return;
         observation.response(chunk, true);
         post(port, { t: 'snap', subId: msg.subId, value: { chunk: packAiEvidence(chunk) } });

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

@@ -24,6 +24,7 @@ import {
   type OutboundMessage,
   type AuthPersistenceMode,
   type AiEngineConfigWire,
+  type AiAppCheckWire,
   type AppConfigMessage,
 } from './protocol.js';
 
@@ -40,9 +41,11 @@ import {
  */
 export interface AiBrokerLike {
   observationIdentity?(model: string): import('pyric/ai/internal').AiEvidence;
-  generateContent(req: Record<string, unknown>, model: string): Promise<Record<string, unknown>>;
-  streamGenerateContent(req: Record<string, unknown>, model: string): AsyncIterable<Record<string, unknown>>;
-  countTokens(req: Record<string, unknown>, model: string): Promise<Record<string, unknown>>;
+  /** AI Logic's App Check gate; a request with no claim passes. */
+  admitAppCheck(model: string, appCheck: AiAppCheckWire | undefined): Promise<void>;
+  generateContent(req: Record<string, unknown>, model: string, appCheck?: AiAppCheckWire): Promise<Record<string, unknown>>;
+  streamGenerateContent(req: Record<string, unknown>, model: string, appCheck?: AiAppCheckWire): AsyncIterable<Record<string, unknown>>;
+  countTokens(req: Record<string, unknown>, model: string, appCheck?: AiAppCheckWire): Promise<Record<string, unknown>>;
 }
 
 // ─── Port interface ───────────────────────────────────────────────────────
@@ -278,6 +281,13 @@ export interface HostCtx {
   aiEngine?: AiEngineConfigWire;
   /** Server-only OpenAI transport. Browser workers retain the same-origin proxy. */
   aiUpstream?: { baseUrl: string; fetch: typeof fetch };
+  /**
+   * The broker's engines run in the browser SharedWorker, which has no server
+   * environment: the gemini engine sends through the dev server's gemini
+   * proxy, which attaches the key (#1584). Set by the worker entry only; a
+   * Node host and a Node repro replay leave it unset.
+   */
+  aiRunsInBrowser?: boolean;
   /**
    * Lazily-built agent tool dispatcher (the canonical sandbox tool set) bound to
    * THIS worker's sandbox. The bridge peer forwards `tool` messages here so the

package/src/serve/worker/inbound-validation/operation-arguments.ts

@@ -495,10 +495,21 @@ export function assertOperationArguments(message: Record<string, unknown>): void
 }
 
 
+/** An App Check claim is absent (a handle with no app) or a record whose token is a string or null. */
+function assertAiAppCheck(appCheck: unknown): void {
+  const hasNoClaim = appCheck === undefined;
+  if (hasNoClaim) return;
+  requireRecord(appCheck, 'appCheck');
+  const token = appCheck.token;
+  const hasTokenShape = token === null || typeof token === 'string';
+  requireShape(hasTokenShape, 'appCheck.token');
+}
+
 /** Unary and streaming AI requests share the same adapter-owned wire fields. */
 export function assertAiArguments(message: Record<string, unknown>): void {
   requireString(message.model, 'model');
   requireRecord(message.request, 'request');
+  assertAiAppCheck(message.appCheck);
   const engine = message.engine;
   const hasNoEngine = engine === undefined;
   if (hasNoEngine) return;

package/src/serve/worker/protocol.ts

@@ -59,6 +59,17 @@ export type AiEngineConfigWire =
     }
   | { kind: 'gemini'; baseUrl?: string; apiKey?: string };
 
+/**
+ * The App Check claim an AI request from an app-backed handle carries, as
+ * production reads `X-Firebase-AppCheck`: a token, or `null` when the handle
+ * has none. The worker broker refuses a request whose claim has no valid
+ * sandbox token. Requests from handles with no app send no claim and are not
+ * gated.
+ */
+export interface AiAppCheckWire {
+  token: string | null;
+}
+
 /**
  * Wire form of the Gemini error envelope an `AiBrokerError` carries.
  */
@@ -289,8 +300,8 @@ export type OpMessage = (
    */
   | ({ t: 'op'; id: string; method: 'storage.createUploadSession'; path: string; contentType?: string; metadata?: Record<string, unknown>; downloadTokens?: string; origin?: string } & StorageBucketWire)
   // AI ops
-  | { t: 'op'; id: string; method: 'ai.generateContent'; model: string; request: Record<string, unknown>; engine?: AiEngineConfigWire }
-  | { t: 'op'; id: string; method: 'ai.countTokens'; model: string; request: Record<string, unknown>; engine?: AiEngineConfigWire }
+  | { t: 'op'; id: string; method: 'ai.generateContent'; model: string; request: Record<string, unknown>; engine?: AiEngineConfigWire; appCheck?: AiAppCheckWire }
+  | { t: 'op'; id: string; method: 'ai.countTokens'; model: string; request: Record<string, unknown>; engine?: AiEngineConfigWire; appCheck?: AiAppCheckWire }
   | { t: 'op'; id: string; method: 'getRuntimeEpoch' }
   | { t: 'op'; id: string; method: 'retireRuntime'; targetEpoch: string }
   | { t: 'op'; id: string; method: 'getVersion' }
@@ -377,6 +388,7 @@ export interface AiStreamSubMessage {
   model: string;
   request: Record<string, unknown>;
   engine?: AiEngineConfigWire;
+  appCheck?: AiAppCheckWire;
 }
 
 export interface MessagingSubMessage {