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

package/src/serve/namespace.ts

@@ -23,16 +23,19 @@ 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, closingHeaders, 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';
 import { createStudioRoutes, type StudioRouteOptions } from './studio/index.js';
 import { pipeFileToResponse, getHeader, isAllowedHost, isAllowedOrigin, isAllowedSessionToken, type ServeLogger } from './server.js';
 import type { InitPayload } from './init-payload.js';
+import type { AppPorts } from './app-ports.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';
@@ -141,12 +144,22 @@ export interface NamespaceOptions {
   boundHost?: string;
   /** Extra allowed hostnames. */
   allowedHosts?: string[];
+  /** Under `pyric sandbox`, the app's ports, including the port of a dev
+   *  server that proxies `/__pyric/*` here (`withPyric` under `next dev`).
+   *  The guarded routes accept a page's Origin on any of them. Absent, only
+   *  the connection's own port is accepted, as under the Vite plugin. The
+   *  caller that creates it teaches it from each request. */
+  appPorts?: AppPorts;
   /** The OpenAI-compatible upstream `/__pyric/ai-proxy` forwards to
    *  (pyric/ai — cdd-deltas #98.2). Falls back to the
    *  `PYRIC_AI_PROXY_UPSTREAM` env var, then `http://localhost:11434/v1`
    *  (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 +367,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 +415,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 +476,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 +489,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 +531,10 @@ 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}. The namespace runs
+ *  the loopback guard first, so only this server's own pages reach here. */
 async function handleDenials(
   throttle: DenialThrottle,
   logger: ServeLogger | undefined,
@@ -505,7 +546,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,26 +560,38 @@ 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, closingHeaders({ 'content-type': 'text/plain' })).end('Payload Too Large');
+      return;
+    }
     /* malformed body: drop it; this is a diagnostics side channel */
   }
   res.writeHead(204).end();
 }
 
-function guardLoopback(
-  req: IncomingMessage,
-  res: ServerResponse,
-  boundHost: string,
-  allowedHosts?: string[],
-): boolean {
+/**
+ * A /__pyric request comes from a page of this app, so the Origin names one of
+ * its ports: this server's own, or under `pyric sandbox` the port of a dev
+ * server that proxies to it (see app-ports.ts).
+ */
+function isAppOrigin(req: IncomingMessage, originHeader: string, opts: GuardOptions): boolean {
+  const boundHost = opts.boundHost ?? 'localhost';
+  const ports = opts.appPorts?.forRequest(req) ?? [req.socket.localPort];
+  return ports.some((port) => isAllowedOrigin(originHeader, boundHost, opts.allowedHosts, port));
+}
+
+type GuardOptions = Pick<NamespaceOptions, 'boundHost' | 'allowedHosts' | 'appPorts'>;
+
+function guardLoopback(req: IncomingMessage, res: ServerResponse, opts: GuardOptions): boolean {
   const hostHeader = getHeader(req, 'host');
   const originHeader = getHeader(req, 'origin');
-  if (!isAllowedHost(hostHeader, boundHost, allowedHosts)) {
+  if (!isAllowedHost(hostHeader, opts.boundHost ?? 'localhost', opts.allowedHosts)) {
     res.writeHead(403, { 'content-type': 'text/plain' }).end('Forbidden: host not allowed');
     return false;
   }
-  // A /__pyric request comes from a page on this same server, so the Origin names this port.
-  if (originHeader && !isAllowedOrigin(originHeader, boundHost, allowedHosts, req.socket.localPort)) {
+  if (originHeader && !isAppOrigin(req, originHeader, opts)) {
     res.writeHead(403, { 'content-type': 'text/plain' }).end('Forbidden: origin mismatch');
     return false;
   }
@@ -573,6 +626,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;
@@ -583,14 +637,14 @@ export function createPyricNamespace(opts: NamespaceOptions) {
   return (req: IncomingMessage, res: ServerResponse, url: URL): boolean | Promise<boolean> => {
     const isDiagnostics = url.pathname === DIAGNOSTICS_PATH;
     if (isDiagnostics) {
-      const refused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+      const refused = !guardLoopback(req, res, opts);
       if (refused) return true;
       return diagnostics(req, res).then(() => true);
     }
     const thresholds = opts.thresholds;
     const isThresholdRequest = thresholds !== undefined && url.pathname === '/__pyric/thresholds';
     if (isThresholdRequest) {
-      const hostRefused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+      const hostRefused = !guardLoopback(req, res, opts);
       if (hostRefused) return true;
       const sessionRefused = !isAllowedSessionToken(req, url, sessionToken);
       if (sessionRefused) {
@@ -602,7 +656,7 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     const indexes = opts.indexes;
     const isIndexRequest = indexes !== undefined && url.pathname === '/__pyric/indexes';
     if (isIndexRequest) {
-      const hostRefused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+      const hostRefused = !guardLoopback(req, res, opts);
       if (hostRefused) return true;
       const sessionRefused = !isAllowedSessionToken(req, url, sessionToken);
       if (sessionRefused) {
@@ -616,7 +670,7 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     if (hasStudioRoutes) {
       const isStudioRequest = url.pathname.startsWith('/__pyric/workspace') || url.pathname.startsWith('/__pyric/projects');
       if (isStudioRequest) {
-        const hostRefused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+        const hostRefused = !guardLoopback(req, res, opts);
         if (hostRefused) return true;
         return routes(req, res, url);
       }
@@ -624,7 +678,7 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     const state = opts.state;
     const isObjectRequest = state !== undefined && url.pathname.startsWith(STATE_OBJECTS_PREFIX);
     if (isObjectRequest) {
-      const hostRefused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+      const hostRefused = !guardLoopback(req, res, opts);
       if (hostRefused) return true;
       const sessionRefused = !isAllowedSessionToken(req, url, sessionToken);
       if (sessionRefused) {
@@ -636,7 +690,7 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     }
     const isStateRequest = state !== undefined && url.pathname === '/__pyric/state';
     if (isStateRequest) {
-      const hostRefused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+      const hostRefused = !guardLoopback(req, res, opts);
       if (hostRefused) return true;
       const sessionRefused = !isAllowedSessionToken(req, url, sessionToken);
       if (sessionRefused) {
@@ -656,7 +710,7 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     const rateCaptures = opts.rateCaptures;
     const isRateCaptureRequest = rateCaptures !== undefined && url.pathname === '/__pyric/rate-captures';
     if (isRateCaptureRequest) {
-      const hostRefused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+      const hostRefused = !guardLoopback(req, res, opts);
       if (hostRefused) return true;
       const sessionRefused = !isAllowedSessionToken(req, url, sessionToken);
       if (sessionRefused) {
@@ -667,7 +721,7 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     const capture = opts.capture;
     const isCaptureRequest = capture !== undefined && url.pathname === '/__pyric/capture';
     if (isCaptureRequest) {
-      const hostRefused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+      const hostRefused = !guardLoopback(req, res, opts);
       if (hostRefused) return true;
       const sessionRefused = !isAllowedSessionToken(req, url, sessionToken);
       if (sessionRefused) {
@@ -683,13 +737,23 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     const events = opts.events;
     const isEventsRequest = events !== undefined && url.pathname === '/__pyric/events';
     if (isEventsRequest) {
-      const hostRefused = !guardLoopback(req, res, opts.boundHost ?? 'localhost', opts.allowedHosts);
+      const hostRefused = !guardLoopback(req, res, opts);
       if (hostRefused) return true;
       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);
+      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);
+      if (hostRefused) return true;
       return handleAiProxy(opts.aiProxyUpstream, denialThrottle, req, res, url, opts.logger).then(
         () => true,
       );
@@ -700,6 +764,9 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     }
     const isDenialRequest = url.pathname === '/__pyric/denials';
     if (isDenialRequest) {
+      // A page on another origin must not be able to write to the developer's terminal.
+      const hostRefused = !guardLoopback(req, res, opts);
+      if (hostRefused) return true;
       return handleDenials(denialThrottle, opts.logger, req, res).then(() => true);
     }
     const isInitRequest = url.pathname === '/__pyric/init.json';

package/src/serve/repro/compare.ts

@@ -11,7 +11,8 @@
  *   replayed values back before comparing. A recorded id bound to two replayed
  *   ids is a divergence.
  * - Times compare equal to times: epoch milliseconds, `{ seconds, nanoseconds }`
- *   timestamps, ISO and HTTP dates, and the `iat`, `exp` and `auth_time` claims.
+ *   timestamps, ISO and HTTP dates, and the `iat`, `exp` and `auth_time` claims,
+ *   also inside a sandbox ID token string, which carries its claims as JSON.
  *
  * Everything else must be equal.
  */
@@ -21,6 +22,8 @@ const TOKEN_SPLIT = /([^A-Za-z0-9_-]+)/;
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
 const HTTP_DATE = /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
 const TIME_CLAIMS = new Set(['iat', 'exp', 'auth_time']);
+/** A sandbox ID token: `sandbox-id-token-<uid>-<serial>:` and its claims as JSON. */
+const SANDBOX_ID_TOKEN = /^(sandbox-id-token-[^:]*):(\{.*\})$/s;
 export const TIME = '<time>';
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -45,6 +48,11 @@ export function normalize(value: unknown): unknown {
   if (typeof value === 'string') {
     const isTime = ISO_DATE.test(value) || HTTP_DATE.test(value) || (/^\d{13}$/.test(value));
     if (isTime) return TIME;
+    const sandboxIdToken = SANDBOX_ID_TOKEN.exec(value);
+    if (sandboxIdToken !== null) {
+      const claims = normalize(sandboxIdToken[2]);
+      return { sandboxIdToken: sandboxIdToken[1], claims };
+    }
     const mayBeJson = value.startsWith('{') || value.startsWith('[');
     if (mayBeJson) {
       try {

package/src/serve/rules-fixture-check.ts

@@ -3,6 +3,7 @@ import { basename, join } from 'node:path';
 import {
   SimulateFirestoreRulesHandler,
   TestCaseSchema,
+  caseShapeRefusal,
   type TestCase,
 } from 'pyric/rules/internal';
 import {
@@ -74,7 +75,18 @@ function discoverProjectFixtureFiles(projectDir: string): DiscoveredFixtureFile[
   return found;
 }
 
-function extractFirestoreTestCases(raw: unknown): TestCase[] | null {
+/**
+ * What a fixture file holds: no Firestore cases, Firestore cases, or cases
+ * one of which the case check refuses. A refused fixture is reported, not
+ * skipped silently, so a case written with a misspelled field or a create
+ * that names a resource is not quietly left out of the check.
+ */
+type ExtractedCases =
+  | { kind: 'none' }
+  | { kind: 'refused'; reason: string }
+  | { kind: 'cases'; cases: TestCase[] };
+
+function extractFirestoreTestCases(raw: unknown): ExtractedCases {
   let candidateList: unknown[] | null = null;
   if (Array.isArray(raw)) {
     candidateList = raw;
@@ -88,15 +100,21 @@ function extractFirestoreTestCases(raw: unknown): TestCase[] | null {
       candidateList = [record];
     }
   }
-  if (!candidateList || candidateList.length === 0) return null;
+  if (!candidateList || candidateList.length === 0) return { kind: 'none' };
+  // A list with no `method` anywhere is some other service's cases, such as
+  // Realtime Database cases, which name an `operation`.
+  const isFirestoreCaseList = candidateList.some(
+    (item) => typeof item === 'object' && item !== null && 'method' in item,
+  );
+  if (!isFirestoreCaseList) return { kind: 'none' };
 
   const parsedCases: TestCase[] = [];
-  for (const item of candidateList) {
-    const parsed = TestCaseSchema.safeParse(item);
-    if (!parsed.success) return null;
-    parsedCases.push(parsed.data);
+  for (const [i, item] of candidateList.entries()) {
+    const refusal = caseShapeRefusal(item);
+    if (refusal) return { kind: 'refused', reason: `case ${i}: ${refusal}` };
+    parsedCases.push(TestCaseSchema.parse(item));
   }
-  return parsedCases;
+  return { kind: 'cases', cases: parsedCases };
 }
 
 function formatDivergenceReason(div: VerifyDivergence): string {
@@ -127,6 +145,7 @@ export async function runProjectFixturesOnRulesReload(
   let failed = 0;
   let checks = 0;
   const failureLines: string[] = [];
+  const warningLines: string[] = [];
 
   for (const file of files) {
     let raw: unknown;
@@ -189,8 +208,13 @@ export async function runProjectFixturesOnRulesReload(
     }
 
     if (input.service === 'firestore' && input.firestoreRules) {
-      const testCases = extractFirestoreTestCases(raw);
-      if (!testCases) continue;
+      const extracted = extractFirestoreTestCases(raw);
+      if (extracted.kind === 'refused') {
+        warningLines.push(`  ⚠ [pyric] fixtures: [${file.name}] not checked, ${extracted.reason}`);
+        continue;
+      }
+      if (extracted.kind === 'none') continue;
+      const testCases = extracted.cases;
 
       const sim = new SimulateFirestoreRulesHandler().simulate(input.firestoreRules, testCases);
       if (!sim.success) continue;
@@ -234,6 +258,7 @@ export async function runProjectFixturesOnRulesReload(
       lines.push(...failureLines);
     }
   }
+  lines.push(...warningLines);
 
   return { ran, passed, failed, checks, ok, lines };
 }

package/src/serve/rules.ts

@@ -12,7 +12,7 @@
 import { createHash } from 'node:crypto';
 import { readFileSync, watch, type FSWatcher } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join } from 'node:path';
+import { dirname, isAbsolute, join, relative } from 'node:path';
 import {
   describeCompileLimitViolations,
   lintFirestoreRules,
@@ -21,8 +21,17 @@ import {
   sourceCompileLimitViolations,
   type ResolveResult,
 } from 'pyric/rules/internal';
-import { asSentence, databaseRulesConfig, type DatabaseRulesConfig } from 'pyric/sandbox/internal';
+import {
+  asSentence,
+  databaseRulesConfig,
+  defaultFirestoreDatabase,
+  firestoreRulesConfig,
+  unservedFirestoreDatabaseWarnings,
+  type DatabaseRulesConfig,
+  type FirestoreRulesConfig,
+} from 'pyric/sandbox/internal';
 import { parseStorageRules } from 'pyric/storage';
+import { compileStorageRules } from 'pyric/storage/internal';
 import { readFirebaseRcSync, type FirebaseJson, type FirebaseRc } from '../cli/firebase-json.js';
 import {
   describeFirebaseProject,
@@ -44,6 +53,8 @@ export interface LoadedRules {
   /** Rules files of the project's own that the source imports, directly or
    *  through other modules. Watched alongside `sourcePath`. */
   moduleFiles: string[];
+  /** One line per `firebase.json` Firestore entry pyric does not serve yet. */
+  warnings: string[];
 }
 
 export interface LoadedStorageRules {
@@ -139,9 +150,16 @@ export function prepareProjectRules(raw: string, sourcePath: string): PreparedRu
     source = resolved.data.resolved;
   }
   // Production rejects a ruleset that does not parse, or is past its compile
-  // limits, before it evaluates any request, so the sandbox does not serve
-  // one either: the check every rules load path runs.
+  // limits, or names a service other than cloud.firestore, before it
+  // evaluates any request, so the sandbox does not serve one either: the
+  // check every rules load path runs, with the reason every plane gives.
   const rejection = rulesSourceRejection(source);
+  if (rejection?.kind === 'parse' && rejection.otherService !== undefined) {
+    throw new RulesPrepareError(
+      `pyric sandbox: ${sourcePath}: Firestore ${rejection.message} Fix the rules before serving.`,
+      moduleFiles,
+    );
+  }
   if (rejection?.kind === 'parse') {
     throw new RulesPrepareError(
       `pyric sandbox: ${sourcePath} failed to parse (line ${rejection.line}, col ${rejection.column}). Fix the rules before serving.`,
@@ -167,47 +185,107 @@ export function prepareProjectRules(raw: string, sourcePath: string): PreparedRu
 }
 
 /**
- * The Firestore rules file the project deploys: `firebase.json`'s
- * `firestore.rules`, else `firestore.rules` in `cwd`. The file may not exist.
+ * Where a project's Firestore deploy targets resolve from: the project id
+ * and `.firebaserc`. Without a project id, target entries stay unresolved.
  */
-export function firestoreRulesPath(cwd: string, config: FirebaseJson | null): string {
-  const rel = config?.firestore?.rules ?? 'firestore.rules';
-  return isAbsolute(rel) ? rel : join(cwd, rel);
+export interface FirestoreRulesProject {
+  projectId?: string;
+  /** Reads `.firebaserc`. Defaults to reading it from the project directory. */
+  readRc?: () => FirebaseRc | null;
 }
 
 /**
- * Load the project rules per `firebase.json` (`firestore.rules` path,
- * defaulting to `firestore.rules` in cwd when the key is absent but the file
- * exists). Missing file with no explicit config → `{ rules: null }` (serving
- * without rules is fine; the runtime logs it). Missing file that IS
- * explicitly configured → throw (the project says it should exist).
+ * The Firestore databases `firebase.json` deploys to, resolved by
+ * {@link firestoreRulesConfig} as `firebase deploy` resolves them, with files
+ * as absolute paths.
+ */
+export function firestoreDatabases(
+  cwd: string,
+  config: FirebaseJson | null,
+  project: FirestoreRulesProject = {},
+): FirestoreRulesConfig {
+  const { projectId } = project;
+  const readRc = project.readRc ?? (() => readFirebaseRcSync(cwd));
+  try {
+    return firestoreRulesConfig(config?.firestore, {
+      targetDatabases: (target) => projectId === undefined ? [] : readRc()?.targets?.[projectId]?.firestore?.[target] ?? [],
+      resolveFile: (file) => isAbsolute(file) ? file : join(cwd, file),
+    });
+  } catch (error) {
+    throw new Error(`pyric sandbox: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * The rules file `firebase.json` deploys to the `(default)` Firestore
+ * database, else `firestore.rules` in `cwd` when `firebase.json` names none.
+ * Null when an array form deploys no rules to `(default)`. The file may not
+ * exist.
+ */
+export function firestoreRulesPath(
+  cwd: string,
+  config: FirebaseJson | null,
+  project: FirestoreRulesProject = {},
+): string | null {
+  return defaultFirestoreDatabase(firestoreDatabases(cwd, config, project))?.rulesFile ?? null;
+}
+
+/**
+ * Load the `(default)` database's rules per `firebase.json`, resolved by
+ * {@link firestoreDatabases}. Missing file with no explicit config, or no
+ * rules for `(default)` → `{ rules: null }` (serving without rules is fine;
+ * the runtime logs it). Missing file that IS explicitly configured → throw
+ * (the project says it should exist). `warnings` names each named database
+ * and unresolved target pyric does not serve yet.
  */
 export async function loadProjectRules(
   cwd: string,
   config: FirebaseJson | null,
+  project: FirestoreRulesProject = {},
 ): Promise<LoadedRules> {
-  const configured = config?.firestore?.rules;
-  const path = firestoreRulesPath(cwd, config);
+  const databases = firestoreDatabases(cwd, config, project);
+  const warnings = firestoreDatabaseWarnings(cwd, databases);
+  const entry = defaultFirestoreDatabase(databases);
+  const path = entry?.rulesFile;
+  const none: LoadedRules = { rules: null, rulesHash: null, sourcePath: null, moduleFiles: [], warnings };
+  if (entry === undefined || path === undefined) return none;
   let raw: string;
   try {
     raw = await readFile(path, 'utf8');
   } catch (e) {
     if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
-      if (configured) {
-        throw new Error(`pyric sandbox: firebase.json points firestore.rules at ${path}, but it does not exist.`);
+      if (entry.configured) {
+        throw new Error(`pyric sandbox: ${entry.label} points Firestore rules at ${path}, but it does not exist.`);
       }
-      return { rules: null, rulesHash: null, sourcePath: null, moduleFiles: [] };
+      return none;
     }
     throw e;
   }
   const { rules, moduleFiles } = prepareProjectRules(raw, path);
-  return { rules, rulesHash: rulesHashOf(rules), sourcePath: path, moduleFiles };
+  return { rules, rulesHash: rulesHashOf(rules), sourcePath: path, moduleFiles, warnings };
 }
 
+/** One warning per Firestore database `firebase.json` declares that pyric does not serve yet, files named relative to `cwd`. */
+export function firestoreDatabaseWarnings(cwd: string, databases: FirestoreRulesConfig): string[] {
+  return unservedFirestoreDatabaseWarnings(databases, (file) => relativeToProject(cwd, file));
+}
+
+function relativeToProject(cwd: string, file: string): string {
+  const rel = relative(cwd, file);
+  const isInsideProject = rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+  return isInsideProject ? rel : file;
+}
+
+/** `compileStorageRules` opens some of its reasons with this; the message here says it already. */
+const STORAGE_COMPILE_PREFIX = /^Storage rules do not compile: /;
+
 /**
  * Resolve and validate a raw Storage rules source. Modular sources are
  * authored in storage.modules.rules and resolved in memory before the
  * sandbox sees them; firebase.json can continue to point at storage.rules.
+ * The source is checked by the sandbox's own install gate,
+ * `compileStorageRules`, so every source this accepts installs on every
+ * plane, and a reload this refuses is reported as refused.
  */
 export function prepareStorageRulesSource(raw: string, sourcePath: string): string {
   let source = raw;
@@ -233,6 +311,12 @@ export function prepareStorageRulesSource(raw: string, sourcePath: string): stri
       `${asSentence(`pyric sandbox: ${sourcePath} failed to parse: ${e instanceof Error ? e.message : String(e)}`)} Fix the rules before serving.`,
     );
   }
+  try {
+    compileStorageRules(source);
+  } catch (e) {
+    const reason = (e instanceof Error ? e.message : String(e)).replace(STORAGE_COMPILE_PREFIX, '');
+    throw new Error(`${asSentence(`pyric sandbox: ${sourcePath} does not compile: ${reason}`)} Fix the rules before serving.`);
+  }
   return source;
 }