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

package/src/bridge/frame-output.ts

@@ -93,8 +93,53 @@ export function failBridgeResponse(frame: BridgeMessage, error: FrameError): Bri
   }
 }
 
+const RTDB_WRITE_FIELDS = ['value', 'values', 'priority'] as const;
+
+function childPath(path: string, key: string): string {
+  return path.endsWith('/') ? `${path}${key}` : `${path}/${key}`;
+}
+
+/** Where `value` holds something JSON drops or turns into null, and what it is. */
+function findJsonLoss(value: unknown, path: string): { path: string; found: string } | undefined {
+  const isLost = value === undefined || (typeof value === 'number' && !Number.isFinite(value));
+  if (isLost) return { path, found: String(value) };
+  const isLeaf = typeof value !== 'object' || value === null;
+  if (isLeaf) return;
+  for (const [key, child] of Object.entries(value)) {
+    const loss = findJsonLoss(child, childPath(path, key));
+    if (loss !== undefined) return loss;
+  }
+}
+
+/**
+ * Refuse an RTDB write whose value JSON cannot carry. NaN and Infinity encode
+ * as null and an undefined member vanishes, so the host would store a delete
+ * (RP-1, #1362). The served client refuses these first with the SDK's text;
+ * this is the second line.
+ */
+function assertJsonSafeRtdbWrite(frame: BridgeMessage): void {
+  const isOtherFrame = frame.type !== 'worker-message';
+  if (isOtherFrame) return;
+  const message = frame.message;
+  const isRtdbOperation = message.t === 'op' && message.method.startsWith('rtdb.');
+  if (!isRtdbOperation) return;
+  const fields: Record<string, unknown> = { ...message };
+  const path = typeof fields.path === 'string' ? fields.path : '/';
+  for (const field of RTDB_WRITE_FIELDS) {
+    const isAbsent = !Object.hasOwn(fields, field);
+    if (isAbsent) continue;
+    const loss = findJsonLoss(fields[field], path);
+    const isJsonSafe = loss === undefined;
+    if (isJsonSafe) continue;
+    throw new Error(
+      `RTDB ${message.method} ${field} at ${loss.path} holds ${loss.found}, which a JSON frame cannot carry. The write was not sent.`,
+    );
+  }
+}
+
 /** Encode bounded output, retaining correlation when an oversized result can be refused. */
 export function encodeBridgeMessage(frame: BridgeMessage): string | undefined {
+  assertJsonSafeRtdbWrite(frame);
   const payload = JSON.stringify(frame);
   const fitsFrameLimit = utf8.encode(payload).byteLength <= MAX_BRIDGE_FRAME_BYTES;
   if (fitsFrameLimit) return payload;

package/src/bridge/protocol.ts

@@ -84,6 +84,19 @@ export const PEER_REPLACED_CLOSE_CODE = 4001;
 /** Human-readable reason sent with {@link PEER_REPLACED_CLOSE_CODE}. */
 export const PEER_REPLACED_CLOSE_REASON = 'replaced by a newer sandbox peer';
 
+/**
+ * WS close code the standalone `pyric bridge` sends a page that opens its
+ * `/sandbox` socket. That bridge has no browser peer (#1468): the page is
+ * closed before it can register, and `connectBridge` stops instead of
+ * reconnecting. A page that needs a browser bridge runs under
+ * `pyric sandbox --bridge`, which serves the page and guards its socket.
+ */
+export const NO_BROWSER_PEER_CLOSE_CODE = 4010;
+
+/** Reason sent with {@link NO_BROWSER_PEER_CLOSE_CODE}; a close frame carries at most 123 bytes. */
+export const NO_BROWSER_PEER_CLOSE_REASON =
+  'pyric bridge does not accept a browser sandbox. Run pyric sandbox --bridge, which serves the page and its bridge.';
+
 // ── Bridge ↔ browser WebSocket protocol ──────────────────────────────
 //
 // All messages are JSON. Each message has a `type` discriminator.

package/src/bridge/server/in-process.ts

@@ -53,6 +53,14 @@ import {
 import type { BridgeToolEvent } from './bridge.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { claimProjectState } from '../../serve/hosted/project-ownership.js';
+import {
+  firestoreDatabaseWarnings,
+  firestoreDatabases,
+  prepareStorageRulesSource,
+  storageRulesPath,
+} from '../../serve/rules.js';
+import { readFirebaseRcSync, type FirebaseJson } from '../../cli/firebase-json.js';
+import { defaultFirestoreDatabase } from 'pyric/sandbox/internal';
 import { TargetRouter } from './target-router.js';
 import type { discoverServe } from '../../serve/discovery.js';
 import type { callHostedMethod } from '../../cli/hosted-method.js';
@@ -156,17 +164,44 @@ export interface ProjectRulesLoad {
   refused: string | null;
 }
 
+function readProjectFirebaseJson(cwd: string): FirebaseJson | null {
+  const path = join(cwd, 'firebase.json');
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as FirebaseJson;
+  } catch (error) {
+    throw new Error(`pyric: failed to parse firebase.json: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 /**
- * Load `<cwd>/firestore.rules` into the sandbox when present. A file
- * production would not load (it does not parse, or it is past a compile
- * limit) is refused: the rules in force stay, and lint and simulate read the
- * file's source. Null when there is no rules file. Without rules,
- * rules-enforcing (`as:{uid}`) ops fall back to the sandbox's default; admin
- * ops are unaffected.
+ * Load the rules `<cwd>/firebase.json` deploys to the `(default)` Firestore
+ * database, resolved as the dev server resolves them, else
+ * `<cwd>/firestore.rules` when `firebase.json` names none. A file production
+ * would not load (it does not parse, or it is past a compile limit) is
+ * refused: the rules in force stay, and lint and simulate read the file's
+ * source. Null when there is no rules file. Without rules, rules-enforcing
+ * (`as:{uid}`) ops fall back to the sandbox's default; admin ops are
+ * unaffected. `onWarning` receives one line per named database or unresolved
+ * deploy target pyric does not serve yet, and one for a named file that is
+ * missing.
  */
-export function loadProjectRules(sandbox: LocalSandbox, cwd: string): ProjectRulesLoad | null {
-  const path = join(cwd, 'firestore.rules');
-  if (!existsSync(path)) return null;
+export function loadProjectRules(
+  sandbox: LocalSandbox,
+  cwd: string,
+  onWarning: (message: string) => void = () => {},
+): ProjectRulesLoad | null {
+  const config = readProjectFirebaseJson(cwd);
+  const projectId = readFirebaseRcSync(cwd)?.projects?.default;
+  const databases = firestoreDatabases(cwd, config, projectId === undefined ? {} : { projectId });
+  for (const warning of firestoreDatabaseWarnings(cwd, databases)) onWarning(warning);
+  const entry = defaultFirestoreDatabase(databases);
+  const path = entry?.rulesFile;
+  if (entry === undefined || path === undefined) return null;
+  if (!existsSync(path)) {
+    if (entry.configured) onWarning(`${entry.label} points Firestore rules at ${path}, but it does not exist.`);
+    return null;
+  }
   return { path, refused: loadFirestoreRules(sandbox, readFileSync(path, 'utf8')) };
 }
 
@@ -179,23 +214,28 @@ export function loadProjectRules(sandbox: LocalSandbox, cwd: string): ProjectRul
  * a restored session complete. Returns the storage handle, which the sidecar
  * codec reads and writes; storage keeps its own durability and is not in the
  * bundle at all.
+ *
+ * Storage enforces the rules file the project deploys, found and prepared as
+ * the dev server finds and prepares it: the first `firebase.json` `storage`
+ * entry with a `rules` path, else `storage.rules` in `cwd`, with `2+modules`
+ * imports resolved against the file's own directory.
  */
 export function openPersistedServices(sandbox: LocalSandbox, cwd: string): FirebaseStorage {
   getAuth(sandbox);
   getAdminDatabase(sandbox);
   // Storage rules are read only by the call that opens the service, so the
   // project's rules have to be in hand here or not at all.
-  const rulesPath = join(cwd, 'storage.rules');
+  const rulesPath = storageRulesPath(cwd, readProjectFirebaseJson(cwd));
   if (!existsSync(rulesPath)) return getAdminStorageSandbox(sandbox);
   const source = readFileSync(rulesPath, 'utf8');
   try {
-    return getAdminStorageSandbox(sandbox, { rules: source });
+    return getAdminStorageSandbox(sandbox, { rules: prepareStorageRulesSource(source, rulesPath) });
   } catch (error) {
-    // A rules file that does not parse cannot govern the service, but a lint
-    // call must still be able to say what is wrong with it. The service opens
-    // without rules and the source is kept for the lint operation.
+    // A rules file the sandbox cannot install cannot govern the service, but a
+    // lint call must still be able to say what is wrong with it. The service
+    // opens without rules and the source is kept for the lint operation.
     process.stderr.write(
-      `[pyric mcp in-process] storage.rules not loaded: ${error instanceof Error ? error.message : String(error)}\n`,
+      `[pyric mcp in-process] Storage rules not loaded: ${error instanceof Error ? error.message : String(error)}\n`,
     );
     rememberUnloadedStorageRules(sandbox, source);
     return getAdminStorageSandbox(sandbox);
@@ -389,13 +429,13 @@ async function runInProcessSession(
   }
   // After the snapshot: restoring it resets the ruleset to the sandbox default,
   // and the project's rules file is the authority for what the server enforces.
-  const projectRules = loadProjectRules(sandbox, projectDir);
+  const projectRules = loadProjectRules(sandbox, projectDir, log);
   if (projectRules !== null && projectRules.refused === null) {
     log(`rules loaded from ${projectRules.path}`);
   } else if (projectRules !== null) {
     log(`rules not loaded from ${projectRules.path}: ${projectRules.refused} The sandbox keeps the rules in force.`);
   } else {
-    log(`no firestore.rules found in ${projectDir}`);
+    log(`no Firestore rules for (default) found in ${projectDir}`);
   }
   const restoredObjects = await loadStorageSidecar(storage, projectDir);
   const restoredStorage = restoredObjects > 0;

package/src/bridge/server/peer.ts

@@ -449,6 +449,65 @@ export function createConsumerSession(
  *  code lets a route answer 413 instead of treating it as malformed JSON. */
 export const BODY_TOO_LARGE_CODE = 'PYRIC_BODY_TOO_LARGE';
 
+/**
+ * Headers for an answer sent before the request body was read to its end,
+ * as a 413 is. The server is still owed the rest of the upload, so a client
+ * that reuses the socket would have its next request read as that remainder
+ * and answered 400 (#1706). Closing the connection sends the next request on
+ * a fresh one (RFC 9112 §9.6).
+ */
+export function closingHeaders(headers: Record<string, string> = {}): Record<string, string> {
+  return { ...headers, connection: 'close' };
+}
+
+function bodyTooLarge(): Error {
+  return Object.assign(new Error('request body too large'), { code: BODY_TOO_LARGE_CODE });
+}
+
+/**
+ * Read a request body as bytes, for a route that forwards it verbatim.
+ *
+ * Unlike {@link collectBody} the limit is required: the bytes are held in
+ * memory once as received chunks and once as the joined copy, so an
+ * unbounded read would let one request grow the process twice over. Past the
+ * limit the rest of the upload is read and discarded, as `collectBody` does,
+ * so the caller's 413 reaches the client.
+ */
+export async function collectRawBody(
+  req: IncomingMessage,
+  limitBytes: number,
+): Promise<Uint8Array<ArrayBuffer>> {
+  return await new Promise<Uint8Array<ArrayBuffer>>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    let overLimit = false;
+    req.on('data', (chunk: Buffer) => {
+      if (overLimit) return;
+      total += chunk.byteLength;
+      const withinLimit = total <= limitBytes;
+      if (withinLimit) {
+        chunks.push(chunk);
+        return;
+      }
+      overLimit = true;
+      chunks.length = 0;
+      reject(bodyTooLarge());
+    });
+    req.on('end', () => {
+      if (overLimit) return;
+      // A plain-ArrayBuffer view: fetch's BodyInit typing rejects Buffer's ArrayBufferLike backing.
+      const body = new Uint8Array(total);
+      let offset = 0;
+      for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      resolve(body);
+    });
+    req.on('error', reject);
+  });
+}
+
 /**
  * Read a request body and parse it as JSON.
  *
@@ -474,7 +533,7 @@ export async function collectBody(
       if (limitBytes === undefined || Buffer.byteLength(raw) <= limitBytes) return;
       overLimit = true;
       raw = '';
-      reject(Object.assign(new Error('request body too large'), { code: BODY_TOO_LARGE_CODE }));
+      reject(bodyTooLarge());
     });
     req.on('end', () => {
       if (!raw) {

package/src/bridge/server/standalone.ts

@@ -1,10 +1,15 @@
 /**
  * Standalone bridge server. Spins up an HTTP server on a known
- * loopback port that handles three routes:
+ * loopback port that handles two routes:
  *
  *   GET  /health           — diagnostic
  *   POST /mcp              — MCP-over-HTTP (StreamableHTTPServerTransport)
- *   GET  /sandbox (Upgrade) — WebSocket the browser tab connects to
+ *
+ * It serves only the tools that run in the bridge process. It has no browser
+ * socket (#1468): a page that opens `/sandbox` is closed with
+ * NO_BROWSER_PEER_CLOSE_CODE and a reason naming `pyric sandbox --bridge`,
+ * before it can register as the sandbox peer. `connectBridge` stops on that
+ * close and reports the reason.
  *
  * Bound to 127.0.0.1 only. Refuses to start if the port is occupied.
  *
@@ -16,7 +21,7 @@
 
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
-import { WebSocketServer, WebSocket } from 'ws';
+import { WebSocketServer } from 'ws';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createBridge, type Bridge, type BridgeToolEvent } from './bridge.js';
 import { buildMcpServer } from './mcp.js';
@@ -29,16 +34,15 @@ import {
 } from './logger.js';
 import {
   DEFAULT_BRIDGE_PORT,
-  MAX_BRIDGE_FRAME_BYTES,
   DEFAULT_HEALTH_PATH,
   DEFAULT_MCP_PATH,
   DEFAULT_SANDBOX_PATH,
-  type BridgeMessage,
+  NO_BROWSER_PEER_CLOSE_CODE,
+  NO_BROWSER_PEER_CLOSE_REASON,
 } from '../protocol.js';
-import { parseBridgeMessage, requestEnvelopeError, requestProtocolError } from './request-envelope.js';
-import { sendBridgeMessage } from './socket-message.js';
 import { pyricVersion } from '../../serve/standalone-assets.js';
 import { isAllowedLoopbackRequest, isAllowedUpgrade } from '../../serve/server.js';
+import { createAppPorts } from '../../serve/app-ports.js';
 
 const BRIDGE_VERSION = pyricVersion();
 const DEFAULT_SESSION_IDLE_MS = 10 * 60 * 1000; // 10 minutes
@@ -112,7 +116,8 @@ export async function startServer(
     },
   });
 
-  const { forwarded, inProcess } = getBridgeToolSurface({
+  // No browser peer can attach here, so the tools a peer would run are not offered.
+  const { inProcess } = getBridgeToolSurface({
     projectDir: opts.projectDir ?? process.cwd(),
     consumers: bridge.consumers,
     callerIdentity: bridge.callerIdentity,
@@ -165,7 +170,7 @@ export async function startServer(
         logger.verbose(`session ${id.slice(0, 8)}… initialized`);
       },
     });
-    const server = buildMcpServer(bridge, { forwarded, inProcess });
+    const server = buildMcpServer(bridge, { forwarded: [], inProcess });
     const session: Session = {
       transport,
       idleTimer: null,
@@ -185,6 +190,8 @@ export async function startServer(
   }
 
   // ── HTTP server ─────────────────────────────────────────────────
+  // No proxy fronts this bridge, so it learns no port: an MCP request names this port or none.
+  const mcpPorts = createAppPorts('127.0.0.1');
   const http = createServer(async (req, res) => {
     const url = req.url ?? '/';
     const debugEnabled = Boolean(process.env.PYRIC_DEBUG);
@@ -201,7 +208,7 @@ export async function startServer(
     const supportsMcpMethod = req.method === 'POST' || req.method === 'GET' || req.method === 'DELETE';
     const requestsMcp = url === DEFAULT_MCP_PATH && supportsMcpMethod;
     if (requestsMcp) {
-      const refusesOrigin = !isAllowedLoopbackRequest(req, '127.0.0.1', opts.allowedHosts);
+      const refusesOrigin = !isAllowedLoopbackRequest(req, '127.0.0.1', opts.allowedHosts, mcpPorts.forRequest(req));
       if (refusesOrigin) {
         res.writeHead(403, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Forbidden: invalid host or origin' }));
@@ -259,17 +266,20 @@ export async function startServer(
     res.end(JSON.stringify({ error: 'not found', path: url }));
   });
 
-  // ── WebSocket server (mounted on /sandbox) ──────────────────────
-  const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_BRIDGE_FRAME_BYTES });
+  // ── /sandbox: refused with a reason ─────────────────────────────
+  // A browser cannot read an HTTP refusal of an upgrade, so the socket is
+  // accepted and closed at once with a reason `connectBridge` reports. No
+  // message from it is read, and it never registers as the sandbox peer.
+  const wss = new WebSocketServer({ noServer: true, maxPayload: 1024 });
   http.on('upgrade', (req, socket, head) => {
     const hasWrongPath = (req.url ?? '') !== DEFAULT_SANDBOX_PATH;
     if (hasWrongPath) {
       socket.destroy();
       return;
     }
-    // DNS-rebinding + cross-origin hijack guard (the request-time isAllowedHost
-    // runs on the `request` event only — `upgrade` bypasses it). The standalone
-    // bridge binds 127.0.0.1 only, so the allowlist is the loopback set.
+    // DNS-rebinding + cross-origin guard: only a loopback page is told why.
+    // The port is not compared here: the page that reaches this socket loads
+    // from the app's own dev server on another port.
     const refusesUpgrade = !isAllowedUpgrade(req.headers, '127.0.0.1', opts.allowedHosts);
     if (refusesUpgrade) {
       logger.error(
@@ -279,7 +289,8 @@ export async function startServer(
       return;
     }
     wss.handleUpgrade(req, socket, head, (ws) => {
-      attachPeer(bridge, ws, logger);
+      logger.info(`refused a browser sandbox on ${DEFAULT_SANDBOX_PATH}: run pyric sandbox --bridge instead`);
+      ws.close(NO_BROWSER_PEER_CLOSE_CODE, NO_BROWSER_PEER_CLOSE_REASON);
     });
   });
 
@@ -305,12 +316,9 @@ export async function startServer(
     url,
     auditLogPath: auditWriter?.path ?? null,
     async stop() {
-      // Stop accepting new WebSocket upgrades…
+      // Stop accepting new WebSocket upgrades, and terminate a refused
+      // socket whose close handshake is still in flight.
       wss.close();
-      // …and forcibly terminate any existing WS clients. Without this,
-      // http.close() below waits for clients to disconnect on their own
-      // (MCP keep-alives sit forever — a Ctrl-C with any open peer
-      // would hang the CLI shutdown indefinitely).
       for (const client of wss.clients) {
         try { client.terminate(); } catch { /* already closed */ }
       }
@@ -332,92 +340,6 @@ export async function startServer(
   };
 }
 
-function attachPeer(bridge: Bridge, ws: WebSocket, logger: BridgeLogger): void {
-  let disconnect: (() => void) | null = null;
-  let helloed = false;
-  let sandboxId: string | null = null;
-  let peerGeneration = 0;
-
-  ws.on('message', (raw) => {
-    const isClosingConnection = ws.readyState !== ws.OPEN;
-    if (isClosingConnection) return;
-    const parsed = parseBridgeMessage(raw.toString());
-    const isInvalidMessage = parsed.kind === 'invalid';
-    if (isInvalidMessage) {
-      ws.close(1002, parsed.reason);
-      return;
-    }
-    const msg = parsed.message;
-    const isHello = msg.type === 'hello';
-    if (isHello) {
-      const protocolError = requestProtocolError(msg);
-      const hasProtocolError = protocolError !== undefined;
-      if (hasProtocolError) {
-        ws.close(1008, protocolError);
-        return;
-      }
-      const envelopeError = requestEnvelopeError(msg);
-      const hasEnvelopeError = envelopeError !== undefined;
-      if (hasEnvelopeError) {
-        ws.close(1002, envelopeError);
-        return;
-      }
-      if (helloed) return; // ignore duplicate hellos
-      helloed = true;
-      sandboxId = msg.sandboxId;
-      logger.info(
-        `peer connected — sandboxId=${sandboxId.slice(0, 12)} tools=${msg.tools.length}`,
-      );
-      disconnect = bridge.registerSandboxPeer(
-        (out: BridgeMessage) => {
-          try {
-            sendBridgeMessage(ws, out, bridge.handleSandboxMessage);
-          } catch {
-            // socket likely closed; the close handler runs disconnect.
-          }
-        },
-        msg.tools,
-        msg.sandboxId,
-      );
-      peerGeneration = bridge.peerGeneration();
-      sendBridgeMessage(ws, {
-        type: 'hello-ack',
-        protocol: 1,
-        bridgeVersion: bridge.version,
-      });
-      return;
-    }
-
-    const isUnregistered = !helloed;
-    if (isUnregistered) return; // ignore messages before hello
-    const envelopeError = requestEnvelopeError(msg);
-    const hasEnvelopeError = envelopeError !== undefined;
-    if (hasEnvelopeError) {
-      ws.close(1002, envelopeError);
-      return;
-    }
-    bridge.handleSandboxMessage(msg, peerGeneration);
-  });
-
-  ws.on('close', () => {
-    const releasePeer = disconnect;
-    const hasPeer = releasePeer !== null;
-    if (hasPeer) {
-      releasePeer();
-      const id = sandboxId;
-      const hasId = id !== null && id.length > 0;
-      let label = 'unknown';
-      if (hasId) label = id.slice(0, 12);
-      logger.info(`peer disconnected — sandboxId=${label}`);
-    }
-    disconnect = null;
-  });
-
-  ws.on('error', () => {
-    // ws will follow up with a 'close' event; cleanup happens there.
-  });
-}
-
 /** Construct a default logger only when the caller did not supply one. */
 function defaultLogger(silent = false): BridgeLogger {
   if (silent) return createSilentLogger();

package/src/bridge/surface/arguments/sandbox.ts

@@ -2,11 +2,8 @@
  * The `sandbox` tool's argument vocabulary: the names, shapes, and reads of the
  * project directory that more than one of its methods needs.
  *
- * `seed` is the one method here with nested arguments, and its user entries are
- * where the Admin SDK naming gap reappears: `auth.createUser` already rejects
- * `claims` and `tenant` in favor of `customClaims` and `tenantId`, and a seed
- * that quietly dropped them would leave the tenant or the claim out of the
- * sandbox with nothing said.
+ * The seed entries live in `./seed.ts`, apart from these reads of the project
+ * directory, so the records that take them can run where the sandbox lives.
  *
  * The branch methods share more than a schema. Six of them name a branch, four
  * have to say the same thing when the project holds no branch by that name, and
@@ -22,70 +19,6 @@ import { CAPTURE_RELATIVE_PATH } from '../../../serve/capture-store.js';
 import { z } from 'zod';
 
 import type { Args, Fail, InvalidArguments } from '../method-types.js';
-import { closest, quoted } from '../closest-name.js';
-
-/** The fields a `seed` users entry accepts, after the Admin SDK rename. */
-const USER_FIELDS = ['uid', 'email', 'password', 'customClaims', 'tenantId'] as const;
-
-/** Client SDK spellings of the two user fields the Admin SDK names differently. */
-const USER_FIELD_RENAMES: Readonly<Record<string, string>> = {
-  claims: 'customClaims',
-  tenant: 'tenantId',
-};
-
-/**
- * One seeded user, under the Admin SDK field names. `auth.importUsers` takes
- * the same entry, so an import and a seed describe an identity one way.
- */
-export const userSeed = z.object({
-  uid: z.string().describe('The user id.'),
-  email: z.string().optional().describe('Email address. Generated when omitted.'),
-  password: z
-    .string()
-    .optional()
-    .describe('Password the identity can sign in with. Derived from the uid when omitted.'),
-  customClaims: z.record(z.unknown()).optional().describe('Custom claims on the record.'),
-  tenantId: z.string().optional().describe('Identity Platform tenant the record belongs to.'),
-});
-
-/** One seeded storage object. */
-export const storageObjectSeed = z.object({
-  path: z.string(),
-  contentBase64: z.string(),
-  contentType: z.string().optional(),
-  customMetadata: z.record(z.string()).optional(),
-});
-
-/**
- * Reject a `users` entry field the schema does not declare. The seed schema
- * strips unknown keys rather than failing on them, so this walks the raw
- * arguments a client sent, not the parsed result, the same way the shared
- * validator walks a method's top-level arguments.
- */
-export function checkUserFields(args: Args, fail: Fail): InvalidArguments | null {
-  const users = args.users;
-  if (!Array.isArray(users)) return null;
-  for (const user of users) {
-    if (user === null || typeof user !== 'object' || Array.isArray(user)) continue;
-    for (const name of Object.keys(user as Record<string, unknown>)) {
-      if ((USER_FIELDS as readonly string[]).includes(name)) continue;
-      const renamed = USER_FIELD_RENAMES[name] ?? closest(name, [...USER_FIELDS]);
-      if (renamed !== null && renamed !== undefined) {
-        return fail(
-          `users entry has unknown field ${quoted(name)}. seed names this field ${quoted(renamed)}.`,
-          `Pass '${renamed}' instead of '${name}' in the users entry.`,
-          `users.${name}`,
-        );
-      }
-      return fail(
-        `users entry has unknown field ${quoted(name)}. A users entry accepts ${USER_FIELDS.join(', ')}.`,
-        `Remove '${name}' from the users entry.`,
-        `users.${name}`,
-      );
-    }
-  }
-  return null;
-}
 
 /** The value of `against` that names the live sandbox rather than a checkpoint. */
 export const AGAINST_LIVE = 'live';

package/src/bridge/surface/arguments/seed.ts

@@ -0,0 +1,78 @@
+/**
+ * The seed entry vocabulary `sandbox.seed` and `auth.importUsers` share.
+ *
+ * A users entry is where the Admin SDK naming gap reappears: `auth.createUser`
+ * already rejects `claims` and `tenant` in favor of `customClaims` and
+ * `tenantId`, and a seed that quietly dropped them would leave the tenant or
+ * the claim out of the sandbox with nothing said.
+ *
+ * Nothing here reads the project directory, so both records can run where the
+ * sandbox lives.
+ */
+import { z } from 'zod';
+
+import type { Args, Fail, InvalidArguments } from '../method-types.js';
+import { closest, quoted } from '../closest-name.js';
+
+/** The fields a `seed` users entry accepts, after the Admin SDK rename. */
+const USER_FIELDS = ['uid', 'email', 'password', 'customClaims', 'tenantId'] as const;
+
+/** Client SDK spellings of the two user fields the Admin SDK names differently. */
+const USER_FIELD_RENAMES: Readonly<Record<string, string>> = {
+  claims: 'customClaims',
+  tenant: 'tenantId',
+};
+
+/**
+ * One seeded user, under the Admin SDK field names. `auth.importUsers` takes
+ * the same entry, so an import and a seed describe an identity one way.
+ */
+export const userSeed = z.object({
+  uid: z.string().describe('The user id.'),
+  email: z.string().optional().describe('Email address. Generated when omitted.'),
+  password: z
+    .string()
+    .optional()
+    .describe('Password the identity can sign in with. Derived from the uid when omitted.'),
+  customClaims: z.record(z.unknown()).optional().describe('Custom claims on the record.'),
+  tenantId: z.string().optional().describe('Identity Platform tenant the record belongs to.'),
+});
+
+/** One seeded storage object. */
+export const storageObjectSeed = z.object({
+  path: z.string(),
+  contentBase64: z.string(),
+  contentType: z.string().optional(),
+  customMetadata: z.record(z.string()).optional(),
+});
+
+/**
+ * Reject a `users` entry field the schema does not declare. The seed schema
+ * strips unknown keys rather than failing on them, so this walks the raw
+ * arguments a client sent, not the parsed result, the same way the shared
+ * validator walks a method's top-level arguments.
+ */
+export function checkUserFields(args: Args, fail: Fail): InvalidArguments | null {
+  const users = args.users;
+  if (!Array.isArray(users)) return null;
+  for (const user of users) {
+    if (user === null || typeof user !== 'object' || Array.isArray(user)) continue;
+    for (const name of Object.keys(user as Record<string, unknown>)) {
+      if ((USER_FIELDS as readonly string[]).includes(name)) continue;
+      const renamed = USER_FIELD_RENAMES[name] ?? closest(name, [...USER_FIELDS]);
+      if (renamed !== null && renamed !== undefined) {
+        return fail(
+          `users entry has unknown field ${quoted(name)}. seed names this field ${quoted(renamed)}.`,
+          `Pass '${renamed}' instead of '${name}' in the users entry.`,
+          `users.${name}`,
+        );
+      }
+      return fail(
+        `users entry has unknown field ${quoted(name)}. A users entry accepts ${USER_FIELDS.join(', ')}.`,
+        `Remove '${name}' from the users entry.`,
+        `users.${name}`,
+      );
+    }
+  }
+  return null;
+}