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

package/src/serve/entries/ai.ts

@@ -16,8 +16,11 @@
  * config with no `baseUrl` targets serve's same-origin `/__pyric/ai-proxy`
  * route (which forwards to the configured upstream, default
  * `http://localhost:11434/v1`) — so a localhost Ollama needs no CORS setup
- * on EITHER path. A custom AnswerEngine OBJECT can't cross the port and is
- * rejected in worker mode rather than creating a second page-local backend.
+ * on EITHER path. A gemini config without its own `apiKey` sends through
+ * `/__pyric/ai-proxy/gemini`, where the server attaches the key from its
+ * environment, so the key never reaches the page. A custom AnswerEngine
+ * OBJECT can't cross the port and is rejected in worker mode rather than
+ * creating a second page-local backend.
  * Direct/in-process `pyric/ai` sandboxes still accept custom engines.
  *
  * Engine config is per-sandbox (#98.4) and first-call-wins at the worker
@@ -27,12 +30,14 @@
  */
 import * as ipAi from 'pyric/ai';
 import { aiErrorFromEnvelope, unpackAiEvidence, getAiEvidence, setAiEvidence } from 'pyric/ai/internal';
+import type { AppCheckClaim } from 'pyric/ai/internal';
 import { getAI as pyricGetAI } from 'pyric/ai';
 import { createTransportAI } from 'pyric/ai/internal';
 import { FirebaseError, getApp, type FirebaseApp } from 'pyric/app';
 import { isSandboxAppDeleted } from 'pyric/app/internal';
 import type { AiEngineConfigWire } from '../worker/protocol.js';
 import { aiGenerateContent, aiCountTokens, aiStreamGenerateContent } from '../worker/client.js';
+import { AI_PROXY_PATH, browserGeminiEngine } from '../worker/ai-proxy-paths.js';
 import { useWorker } from './worker-runtime.js';
 import { workerClientForApp } from './app-client.js';
 
@@ -80,9 +85,6 @@ export {
 type EngineOption = NonNullable<ipAi.AIOptions['engine']>;
 type AnswerTransport = Parameters<typeof createTransportAI>[2];
 
-/** The serve proxy route the browser openai engine defaults to (#98.2). */
-const AI_PROXY_PATH = '/__pyric/ai-proxy';
-
 /** A custom AnswerEngine object (vs a plain, worker-cloneable EngineConfig). */
 function isAnswerEngine(engine: EngineOption): boolean {
   return typeof (engine as { generateContent?: unknown }).generateContent === 'function';
@@ -150,20 +152,7 @@ function wireToEngineOption(wire: AiEngineConfigWire): EngineOption {
     } as EngineOption;
   }
   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 EngineOption;
-  }
+  if (isGeminiWire) return browserGeminiEngine(wire) as EngineOption;
   return {
     kind: 'scripted',
     ...(wire.script !== undefined
@@ -172,7 +161,10 @@ function wireToEngineOption(wire: AiEngineConfigWire): EngineOption {
   } as EngineOption;
 }
 
-/** In-page path: default an openai config's absent baseUrl to the proxy. */
+/**
+ * In-page path: default an openai config's absent baseUrl to the proxy, and
+ * send a gemini config without its own key through the gemini proxy.
+ */
 function withProxyDefault(options?: ipAi.AIOptions): ipAi.AIOptions | undefined {
   const engine = options?.engine;
   if (!engine || isAnswerEngine(engine)) return options;
@@ -180,6 +172,10 @@ function withProxyDefault(options?: ipAi.AIOptions): ipAi.AIOptions | undefined
   if (config.kind === 'openai' && config.baseUrl === undefined) {
     return { ...options, engine: { ...config, baseUrl: AI_PROXY_PATH } as EngineOption };
   }
+  const isKeylessGemini = config.kind === 'gemini' && (engine as { apiKey?: string }).apiKey === undefined;
+  if (isKeylessGemini) {
+    return { ...options, engine: browserGeminiEngine({ kind: 'gemini' }) as EngineOption };
+  }
   return options;
 }
 
@@ -191,22 +187,27 @@ function aiErrorFromWire(err: unknown, modelResource: string, op: string): unkno
 
 // ── The port-forwarding AnswerEngine (worker path) ─────────────────────────
 
+/**
+ * The handle's App Check claim rides every request to the worker broker,
+ * which plays AI Logic's gate (`pyric/ai`'s `app-check-gate.ts`).
+ */
 function portEngine(db: ReturnType<typeof workerClientForApp>, engineWire: AiEngineConfigWire | undefined): AnswerTransport {
-  const params = (model: string, request: Record<string, unknown>) => ({
+  const params = (model: string, request: Record<string, unknown>, appCheck: AppCheckClaim | undefined) => ({
     model,
     request,
     ...(engineWire !== undefined ? { engine: engineWire } : {}),
+    ...(appCheck !== undefined ? { appCheck } : {}),
   });
   const engine = {
-    async generateContent(req: Record<string, unknown>, model: string): Promise<Record<string, unknown>> {
+    async generateContent(req: Record<string, unknown>, model: string, appCheck?: AppCheckClaim): Promise<Record<string, unknown>> {
       try {
-        return unpackAiEvidence(await aiGenerateContent(db, params(model, req)));
+        return unpackAiEvidence(await aiGenerateContent(db, params(model, req, appCheck)));
       } catch (err) {
         throw aiErrorFromWire(err, model, 'generateContent');
       }
     },
-    streamGenerateContent(req: Record<string, unknown>, model: string): AsyncIterable<Record<string, unknown>> {
-      const inner = aiStreamGenerateContent(db, params(model, req));
+    streamGenerateContent(req: Record<string, unknown>, model: string, appCheck?: AppCheckClaim): AsyncIterable<Record<string, unknown>> {
+      const inner = aiStreamGenerateContent(db, params(model, req, appCheck));
       return (async function* mapped(): AsyncGenerator<Record<string, unknown>> {
         try {
           for await (const chunk of inner) yield unpackAiEvidence(chunk);
@@ -215,9 +216,9 @@ function portEngine(db: ReturnType<typeof workerClientForApp>, engineWire: AiEng
         }
       })();
     },
-    async countTokens(req: Record<string, unknown>, model: string): Promise<Record<string, unknown>> {
+    async countTokens(req: Record<string, unknown>, model: string, appCheck?: AppCheckClaim): Promise<Record<string, unknown>> {
       try {
-        return unpackAiEvidence(await aiCountTokens(db, params(model, req)));
+        return unpackAiEvidence(await aiCountTokens(db, params(model, req, appCheck)));
       } catch (err) {
         throw aiErrorFromWire(err, model, 'countTokens');
       }

package/src/serve/entries/app-ai-passthrough.ts

@@ -2,68 +2,18 @@
 import { bindAppRegistrySandbox } from 'pyric/app/internal';
 import { sandbox } from './app-backend.js';
 import * as pyricApp from 'pyric/app';
-import * as realApp from 'firebase/app';
+import { shadowedAppRegistry } from '../../register/app-bridge-shadow.js';
 
 bindAppRegistrySandbox(sandbox);
 
-function decorateApp(
-  app: pyricApp.FirebaseApp,
-  options?: pyricApp.FirebaseOptions,
-  rawSettings?: string | pyricApp.FirebaseAppSettings,
-): pyricApp.FirebaseApp {
-  try {
-    let shadow: { container?: unknown };
-    try {
-      shadow = realApp.getApp(app.name) as { container?: unknown };
-    } catch {
-      const initOptions = (options ?? app.options) as realApp.FirebaseOptions;
-      const initSettings = rawSettings ?? app.name;
-      const isStringSettings = typeof initSettings === 'string';
-      if (isStringSettings) {
-        shadow = realApp.initializeApp(initOptions, initSettings) as { container?: unknown };
-      } else {
-        const objectSettings = initSettings as realApp.FirebaseAppSettings;
-        shadow = realApp.initializeApp(initOptions, objectSettings) as { container?: unknown };
-      }
-    }
-    const hasShadowContainer = shadow.container !== undefined && shadow.container !== null;
-    if (hasShadowContainer) {
-      Object.defineProperty(app, 'container', { value: shadow.container, configurable: true });
-    }
-  } catch {
-    // Observational/best-effort: do not break Pyric initialization if shadow initialization fails.
-  }
-  return app;
-}
+// One shadow implementation for every plane: the register adapters build
+// their exports from the same registry.
+const registry = shadowedAppRegistry(pyricApp);
 
-export function initializeApp(
-  options?: pyricApp.FirebaseOptions,
-  rawSettings?: string | pyricApp.FirebaseAppSettings,
-): pyricApp.FirebaseApp {
-  const app = pyricApp.initializeApp(options, rawSettings);
-  return decorateApp(app, options, rawSettings);
-}
-
-export function getApp(name?: string): pyricApp.FirebaseApp {
-  return decorateApp(pyricApp.getApp(name));
-}
-
-export function getApps(): pyricApp.FirebaseApp[] {
-  return pyricApp.getApps().map((app) => decorateApp(app));
-}
-
-export async function deleteApp(app: pyricApp.FirebaseApp): Promise<void> {
-  try {
-    const shadow = realApp.getApp(app.name);
-    const hasShadow = shadow !== undefined && shadow !== null;
-    if (hasShadow) {
-      await realApp.deleteApp(shadow);
-    }
-  } catch {
-    // Ignore if shadow app was not initialized or already deleted.
-  }
-  return pyricApp.deleteApp(app);
-}
+export const initializeApp = registry.initializeApp;
+export const getApp = registry.getApp;
+export const getApps = registry.getApps;
+export const deleteApp = registry.deleteApp;
 
 export {
   FirebaseError,

package/src/serve/firebase-module-swap.ts

@@ -8,7 +8,8 @@
  * container.
  *
  * Every plane that swaps Firebase modules reads {@link swappedFirebaseEntries}:
- * the `pyric sandbox` import map (`html-injection.ts`) and the Vite resolver
+ * the `pyric sandbox` import map (`html-injection.ts`, through
+ * {@link importMapFirebaseEntries}) and the Vite resolver
  * (`vite-module-swap.ts`). Every front door resolves the mode with
  * {@link resolveAiMode}. One table and one precedence rule, so the planes
  * cannot disagree about what production mode means. It imports only Node
@@ -78,6 +79,34 @@ export function swappedFirebaseEntries(mode: AiMode): ReadonlyMap<ServedFirebase
   return swapped;
 }
 
+/**
+ * The Firebase SDK modules `pyric sandbox` builds for the browser from the
+ * project's own `firebase` install in production AI mode, to the entry key of
+ * each (`/__pyric/sdk/<key>.js`). One build, so the three share one
+ * `@firebase/app` component registry. The Vite and register planes resolve
+ * the Firebase SDK themselves and never read this.
+ */
+export const REAL_SDK_ENTRIES: ReadonlyMap<ServedFirebaseSpecifier, string> = new Map([
+  ['firebase/app', 'firebase-sdk-app'],
+  ['firebase/ai', 'firebase-sdk-ai'],
+  ['firebase/app-check', 'firebase-sdk-app-check'],
+]);
+
+/**
+ * The import-map plane's specifier to entry key table: the swap, plus, in
+ * production AI mode, the unswapped `firebase/ai` sent to the Firebase SDK
+ * that `pyric sandbox` builds. A browser has no package resolution, so on
+ * this plane an unswapped specifier still needs a URL.
+ */
+export function importMapFirebaseEntries(mode: AiMode): ReadonlyMap<ServedFirebaseSpecifier, string> {
+  const entries = new Map(swappedFirebaseEntries(mode));
+  for (const [specifier, key] of REAL_SDK_ENTRIES) {
+    const isUnswapped = !entries.has(specifier);
+    if (isUnswapped) entries.set(specifier, key);
+  }
+  return entries;
+}
+
 /** This package's root (`src/serve/` and `dist/serve/` both sit two levels below it), as written and resolved. */
 const PACKAGE_ROOTS: readonly string[] = (() => {
   const root = fileURLToPath(new URL('../../', import.meta.url)).replaceAll('\\', '/');
@@ -110,10 +139,30 @@ export function isShadowAppImporter(importer: string | undefined): boolean {
   return PACKAGE_ROOTS.some((root) => file.startsWith(root) && SHADOW_MODULE.test(file.slice(root.length)));
 }
 
-/** The SDK modules a shadow-app wrapper imports for itself. */
-const BRIDGED_SPECIFIERS: ReadonlySet<string> = new Set(['firebase/app', 'firebase/app-check']);
+/**
+ * The SDK modules a shadow-app wrapper imports for itself. The firebase-admin
+ * pair is the register's App Check verifier for production AI mode
+ * (`register/app-bridge-admin-app-check.ts`); no browser plane serves them.
+ */
+const BRIDGED_SPECIFIERS: ReadonlySet<string> = new Set([
+  'firebase/app',
+  'firebase/app-check',
+  'firebase-admin/app',
+  'firebase-admin/app-check',
+]);
 
 /** Whether this import is a shadow-app wrapper reaching the Firebase SDK it wraps. */
 export function isBypassedBridgeImport(specifier: string, importer: string | undefined): boolean {
   return BRIDGED_SPECIFIERS.has(specifier) && isShadowAppImporter(importer);
 }
+
+/**
+ * Where a bypassed bridge import goes on the import-map plane: the entry key
+ * of the Firebase SDK module `pyric sandbox` builds. The bare specifier
+ * cannot stay, because the import map sends it back to the wrapper itself.
+ * Undefined for every import {@link isBypassedBridgeImport} does not name.
+ */
+export function bridgeImportEntryKey(specifier: string, importer: string | undefined): string | undefined {
+  if (!isBypassedBridgeImport(specifier, importer)) return undefined;
+  return REAL_SDK_ENTRIES.get(specifier as ServedFirebaseSpecifier);
+}

package/src/serve/gemini-error-redaction.ts

@@ -0,0 +1,60 @@
+/**
+ * Masking an upstream Gemini error before the gemini proxy relays it to the
+ * browser (#1584). An upstream or a gateway can quote the credential it was
+ * sent in any form: in the URL (`?key=`, `&key=`, JSON-escaped or
+ * percent-encoded), in plain text, or in an echoed header such as
+ * `x-goog-api-key` or `Authorization: Bearer`. So the proxy removes the exact
+ * credentials the request carried, raw and percent-encoded, then runs
+ * `redactUrl` as a second pass for any other credential parameter.
+ *
+ * A JSON body is masked value by value and serialized again, so the
+ * browser engine still reads Gemini's own status and message. Text
+ * redaction over the raw JSON could eat a closing quote and leave the
+ * envelope unparseable.
+ */
+import { redactUrl } from 'pyric/ai/internal';
+
+const MASK = '***';
+
+/** The forms a credential can appear in, longest first. */
+function quotedForms(credential: string): string[] {
+  const forms = new Set([encodeURIComponent(credential), credential]);
+  return [...forms].sort((a, b) => b.length - a.length);
+}
+
+function redactText(text: string, credentials: readonly string[]): string {
+  let masked = text;
+  for (const credential of credentials) {
+    for (const form of quotedForms(credential)) masked = masked.split(form).join(MASK);
+  }
+  return redactUrl(masked);
+}
+
+function redactValue(value: unknown, credentials: readonly string[]): unknown {
+  if (typeof value === 'string') return redactText(value, credentials);
+  if (Array.isArray(value)) return value.map((item) => redactValue(item, credentials));
+  const isObject = value !== null && typeof value === 'object';
+  if (!isObject) return value;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .map(([key, item]) => [redactText(key, credentials), redactValue(item, credentials)]);
+  return Object.fromEntries(entries);
+}
+
+/** The JSON value `text` holds, or undefined when it is not JSON. */
+function parseJson(text: string): { value: unknown } | undefined {
+  try {
+    return { value: JSON.parse(text) as unknown };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `text` with every credential in `credentials` removed, and every
+ * credential URL parameter masked. A JSON body stays JSON.
+ */
+export function redactUpstreamError(text: string, credentials: readonly string[]): string {
+  const json = parseJson(text);
+  if (json === undefined) return redactText(text, credentials);
+  return JSON.stringify(redactValue(json.value, credentials));
+}

package/src/serve/gemini-proxy.ts

@@ -0,0 +1,140 @@
+/**
+ * `/__pyric/ai-proxy/gemini`: where a browser gemini engine sends (#1584).
+ *
+ * A page or SharedWorker has no server environment, and the Gemini API key
+ * must never reach it. The browser engine sends each request here with no
+ * credentials. The dev server sends it on with the gemini engine's own
+ * request code (`GeminiUpstream` from `pyric/ai/internal`): the key from the
+ * server's environment or ADC, to the server's configured base URL. A
+ * successful answer streams back unchanged. An error comes back with its
+ * status and with any credential it quotes masked, so the browser engine
+ * reads Gemini's own error and never the key. The body is bounded as the
+ * openai route's is.
+ *
+ * The browser chooses only the model and the call. The target and the
+ * credentials are the server's, so no page can send the key anywhere else.
+ * The App Check gate runs before any of this, in the broker that owns the
+ * browser engine.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { GeminiUpstream, type GeminiUpstreamOptions } from 'pyric/ai/internal';
+import { redactUpstreamError } from './gemini-error-redaction.js';
+import type { ServeLogger } from './server.js';
+import { fetchAiUpstream, readAiProxyBody, relayAiUpstream, type AiDiagnosticThrottle } from './ai-proxy.js';
+import { GEMINI_PROXY_PATH } from './worker/ai-proxy-paths.js';
+import { serializeError, type AiEngineConfigWire } from './worker/protocol.js';
+
+export { GEMINI_PROXY_PATH } from './worker/ai-proxy-paths.js';
+
+/** The server's gemini engine config: the Vite plugin's `ai.engine`, when it is gemini. */
+export interface GeminiProxyConfig {
+  baseUrl?: string;
+  apiKey?: string;
+}
+
+/** The gemini proxy's config from a configured engine, when that engine is gemini. */
+export function geminiProxyConfig(engine: AiEngineConfigWire | undefined): GeminiProxyConfig | undefined {
+  const isGemini = engine?.kind === 'gemini';
+  if (!isGemini) return undefined;
+  return {
+    ...(engine.baseUrl !== undefined ? { baseUrl: engine.baseUrl } : {}),
+    ...(engine.apiKey !== undefined ? { apiKey: engine.apiKey } : {}),
+  };
+}
+
+/** `/v1beta/models/<model>:<call>`, for the three calls the browser engine makes. */
+const GEMINI_CALL_PATH = /^\/v1beta\/(models\/[A-Za-z0-9._-]+):(generateContent|streamGenerateContent|countTokens)$/;
+
+/** The query each call may carry: only the stream asks for server-sent events. */
+const CALL_QUERY: Record<string, string> = {
+  generateContent: '',
+  countTokens: '',
+  streamGenerateContent: '?alt=sse',
+};
+
+/** Is this request for the gemini proxy (and not the OpenAI-compatible one)? */
+export function isGeminiProxyPath(pathname: string): boolean {
+  return pathname.startsWith(`${GEMINI_PROXY_PATH}/`);
+}
+
+/** The resource and the action `GeminiUpstream.send` takes, or null for anything else. */
+function geminiCall(url: URL): { resource: string; action: string } | null {
+  const match = url.pathname.slice(GEMINI_PROXY_PATH.length).match(GEMINI_CALL_PATH);
+  if (match === null) return null;
+  const [, resource, call] = match as unknown as [string, string, string];
+  const isExpectedQuery = url.search === CALL_QUERY[call];
+  if (!isExpectedQuery) return null;
+  return { resource, action: `${call}${url.search}` };
+}
+
+/** Answer with a Gemini error envelope, as the upstream would. */
+function sendEnvelope(res: ServerResponse, code: number, message: string, status: string): void {
+  res.writeHead(code, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+  res.end(JSON.stringify({ error: { code, message, status } }));
+}
+
+/**
+ * Send a non-2xx upstream answer with the credentials the request carried
+ * removed, in whatever form the upstream quotes them, and a JSON envelope
+ * kept parseable (`gemini-error-redaction.ts`).
+ */
+async function relayRedactedError(upstream: Response, credentials: readonly string[], res: ServerResponse): Promise<void> {
+  const text = redactUpstreamError(await upstream.text().catch(() => ''), credentials);
+  const headers: Record<string, string> = { 'cache-control': 'no-store' };
+  const contentType = upstream.headers.get('content-type');
+  if (contentType) headers['content-type'] = contentType;
+  res.writeHead(upstream.status, headers);
+  res.end(text);
+}
+
+/**
+ * The gemini proxy handler. One `GeminiUpstream` serves every request, so an
+ * ADC token is looked up once and reused, as the engine itself does.
+ * `seams` replaces the ADC lookup in tests.
+ */
+export function createGeminiProxy(
+  config: GeminiProxyConfig | undefined,
+  throttle: AiDiagnosticThrottle,
+  logger?: ServeLogger,
+  seams: Pick<GeminiUpstreamOptions, 'printAdcToken'> = {},
+): (req: IncomingMessage, res: ServerResponse, url: URL) => Promise<void> {
+  const upstream = new GeminiUpstream({
+    ...seams,
+    ...(config?.baseUrl !== undefined ? { baseUrl: config.baseUrl } : {}),
+    ...(config?.apiKey !== undefined ? { apiKey: config.apiKey } : {}),
+    fetch: Object.assign(
+      (input: Parameters<typeof fetch>[0], init?: RequestInit) => fetchAiUpstream(input, init, throttle, logger),
+      { preconnect: fetch.preconnect },
+    ),
+  });
+  return async (req, res, url) => {
+    if (req.method !== 'POST') {
+      res.writeHead(405, { allow: 'POST' }).end('method not allowed');
+      return;
+    }
+    const call = geminiCall(url);
+    if (call === null) {
+      sendEnvelope(res, 404, `pyric dev ai-proxy: ${url.pathname} is not a Gemini call the proxy sends.`, 'NOT_FOUND');
+      return;
+    }
+    const body = await readAiProxyBody(req, res);
+    if (body === null) return;
+    let response: Response;
+    let credentials: string[];
+    try {
+      ({ response, credentials } = await upstream.sendWithCredentials(call.resource, call.action, body));
+    } catch (error) {
+      // Missing credentials (401) and an unreachable upstream (502) come as
+      // the engine's own envelopes, already redacted.
+      const envelope = serializeError(error).aiEnvelope;
+      if (envelope === undefined) throw error;
+      sendEnvelope(res, envelope.error.code, envelope.error.message, envelope.error.status);
+      return;
+    }
+    if (response.ok) {
+      await relayAiUpstream(response, res);
+      return;
+    }
+    await relayRedactedError(response, credentials, res);
+  };
+}

package/src/serve/html-injection.ts

@@ -2,15 +2,17 @@ import { stampHostedTarget } from './runtime/hosted-target.js';
 import type { OwnersConfig } from './owners-config.js';
 import { REACT_BOOTSTRAP } from './react-bootstrap.js';
 import { SANDBOX_BUILD_MARKER } from './sandbox-marker.js';
-import { swappedFirebaseEntries, type AiMode } from './firebase-module-swap.js';
+import { importMapFirebaseEntries, type AiMode } from './firebase-module-swap.js';
 
 /**
  * The import-map targets, specifier to served URL, for one AI mode. Derived
  * from the shared swap table, so the Vite resolver serves the same modules.
+ * In production AI mode `firebase/ai` goes to the Firebase SDK that
+ * `pyric sandbox` builds from the project's `firebase` install.
  */
 export function sdkImportMap(mode: AiMode = 'sandbox'): Record<string, string> {
   const imports: Record<string, string> = {};
-  for (const [specifier, entryKey] of swappedFirebaseEntries(mode)) {
+  for (const [specifier, entryKey] of importMapFirebaseEntries(mode)) {
     imports[specifier] = `/__pyric/sdk/${entryKey}.js`;
   }
   return imports;