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

package/src/next/guard.ts

@@ -2,6 +2,7 @@
  * Execution policies and safety interlocks for Next.js configuration loading.
  */
 import type { PyricNextOptions } from './types.js';
+import { isRegisterActive } from '../register/activation.js';
 
 const FORCED_SANDBOX_FLAG = '1';
 
@@ -45,22 +46,43 @@ function hasActiveSandboxEnvironment(): boolean {
   return sandboxValue.length > 0;
 }
 
+const OPT_OUT = 'To disable this guard, pass { guard: false } to withPyric(config, options).';
+
+const NO_SANDBOX_MESSAGE =
+  '[Pyric] Next.js development server started without active Pyric sandbox environment variables.\n' +
+  'To prevent accidental connections to production Firebase databases, launch this server using:\n' +
+  '  pyric sandbox -- next dev\n' +
+  'or start the host alone with `pyric sandbox --no-run` and paste the printed export lines into the terminal that runs next dev.\n' +
+  OPT_OUT;
+
 /**
- * Verify whether the Next.js development server is booting under a secure,
- * activated sandbox environment. Throws a protective terminal error if un-sandboxed.
+ * `PYRIC_SANDBOX` is set but the register didn't load, so route handlers
+ * would import the real `firebase-admin` (#1625). The message names the three
+ * ways that happens and how to start the server instead.
+ */
+const NO_REGISTER_MESSAGE =
+  '[Pyric] PYRIC_SANDBOX is set, but @pyric/cli/register is not active in this process, ' +
+  'so firebase-admin and firebase imports in route handlers would load the real SDKs.\n' +
+  'Start the development server with:\n' +
+  '  pyric sandbox -- next dev\n' +
+  'The register is missing when PYRIC_SANDBOX comes only from a .env file, when NODE_ENV=production makes the register refuse, ' +
+  'or when a package script sets its own NODE_OPTIONS. A script that needs its own options appends them: ' +
+  'NODE_OPTIONS="$NODE_OPTIONS --max-old-space-size=4096" next dev\n' +
+  OPT_OUT;
+
+/**
+ * Verify that the Next.js development server is starting under an active
+ * sandbox: `PYRIC_SANDBOX` is set and `@pyric/cli/register` activated in this
+ * process. Throws a terminal error naming how to start it otherwise.
  */
 export function enforceSandboxGuard(options?: PyricNextOptions): void {
   if (isGuardExplicitlyDisabled(options)) {
     return;
   }
-  if (hasActiveSandboxEnvironment()) {
-    return;
+  if (!hasActiveSandboxEnvironment()) {
+    throw new Error(NO_SANDBOX_MESSAGE);
+  }
+  if (!isRegisterActive()) {
+    throw new Error(NO_REGISTER_MESSAGE);
   }
-  const errorMessage =
-    '[Pyric] Next.js development server started without active Pyric sandbox environment variables.\n' +
-    'To prevent accidental connections to production Firebase databases, launch this server using:\n' +
-    '  pyric sandbox -- next dev\n' +
-    'or start the host alone with `pyric sandbox --no-run` and paste the printed export lines into the terminal that runs next dev.\n' +
-    'To disable this guard, pass { guard: false } to withPyric(config, options).';
-  throw new Error(errorMessage);
 }

package/src/next/turbopack-config.ts

@@ -3,12 +3,38 @@
  */
 import type { NextConfigObject } from './types.js';
 import { getClientAliases } from './client-aliases.js';
+import { BRIDGE_IMPORT_LOADER, bridgeModuleFileNames, productionBridgeOptions, type BridgeImportOptions } from './bridge-imports.js';
+
+/** The Turbopack rule that runs the bridge import loader on one wrapper. */
+export interface TurbopackBridgeRule {
+  loaders: Array<{ loader: string; options: BridgeImportOptions }>;
+  as: '*.js';
+}
+
+/**
+ * In production AI mode, a rule per shadow-app wrapper that runs the bridge
+ * import loader, so the wrapper's Firebase SDK import escapes the alias that
+ * names the wrapper itself. Keyed by the wrapper's file name; the loader
+ * leaves any other file of that name unchanged.
+ */
+function assembleBridgeRules(existingRules: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  const options = productionBridgeOptions();
+  if (options === undefined) return existingRules;
+  const rules: Record<string, unknown> = Object.assign({}, existingRules);
+  for (const name of bridgeModuleFileNames()) {
+    const rule: TurbopackBridgeRule = { loaders: [{ loader: BRIDGE_IMPORT_LOADER, options }], as: '*.js' };
+    rules[name] = rule;
+  }
+  return rules;
+}
 
 function assembleTurbopackAliases(existingTurbo: Record<string, any> | undefined): Record<string, any> {
   const turboSection = existingTurbo !== undefined ? Object.assign({}, existingTurbo) : {};
   const currentAliases = turboSection.resolveAlias !== undefined ? Object.assign({}, turboSection.resolveAlias) : {};
   const pyricAliases = getClientAliases();
   turboSection.resolveAlias = Object.assign(currentAliases, pyricAliases);
+  const rules = assembleBridgeRules(turboSection.rules);
+  if (rules !== undefined) turboSection.rules = rules;
   return turboSection;
 }
 

package/src/next/webpack-config.ts

@@ -3,6 +3,7 @@
  */
 import type { NextConfigObject } from './types.js';
 import { getClientAliases, getNodeBuiltinFallbacks } from './client-aliases.js';
+import { BRIDGE_IMPORT_LOADER, productionBridgeOptions, type BridgeImportOptions } from './bridge-imports.js';
 
 interface WebpackOptions {
   isServer: boolean;
@@ -32,6 +33,30 @@ function assembleClientResolveSection(existingResolve: Record<string, any> | und
   return resolveSection;
 }
 
+/**
+ * In production AI mode, a rule that runs the bridge import loader on the
+ * shadow-app wrappers, so their Firebase SDK imports escape the aliases that
+ * name the wrappers themselves (see `bridge-imports.ts`).
+ */
+function assembleClientModuleSection(
+  existingModule: { rules?: unknown[]; [key: string]: unknown } | undefined,
+):{ rules?: unknown[]; [key: string]: unknown } | undefined {
+  const options = productionBridgeOptions();
+  if (options === undefined) return existingModule;
+  const moduleSection = Object.assign({}, existingModule);
+  const rules = Array.isArray(moduleSection.rules) ? [...moduleSection.rules] : [];
+  const rule: WebpackBridgeRule = { test: Object.keys(options.wrappers), use: [{ loader: BRIDGE_IMPORT_LOADER, options }] };
+  rules.push(rule);
+  moduleSection.rules = rules;
+  return moduleSection;
+}
+
+/** The webpack rule that runs the bridge import loader on the wrappers. */
+export interface WebpackBridgeRule {
+  test: string[];
+  use: Array<{ loader: string; options: BridgeImportOptions }>;
+}
+
 /** The module that installs React's commit hook; it must evaluate before React. */
 export const REACT_HOOK_ENTRY = '@pyric/cli/next/internal/react-hook';
 
@@ -98,6 +123,7 @@ export function augmentWebpackConfig(config: NextConfigObject): NextConfigObject
       return resolvedConfig;
     }
     resolvedConfig.resolve = assembleClientResolveSection(resolvedConfig.resolve);
+    resolvedConfig.module = assembleClientModuleSection(resolvedConfig.module);
     resolvedConfig.experiments = assembleClientExperimentsSection(resolvedConfig.experiments);
     resolvedConfig.output = assembleClientOutputSection(resolvedConfig.output);
     resolvedConfig.entry = assembleClientEntry(resolvedConfig.entry);

package/src/next/with-pyric.ts

@@ -9,6 +9,10 @@ import { augmentTurbopackConfig } from './turbopack-config.js';
 import { augmentDevRewrites } from './dev-rewrites.js';
 import { augmentRuntimeEnv } from './runtime-env.js';
 import { findEdgeRuntimeFiles, formatEdgeRuntimeWarning } from './edge-runtime.js';
+import { NET_GUARD_GLOBAL, type NetGuard } from '../register/net-guard.js';
+
+const DEV_SERVER_PHASE = 'phase-development-server';
+const DEV_GUARD_REASON = 'withPyric runs the Next dev server, which defaults to PYRIC_GUARD=block (#1443)';
 
 function isFunctionConfig(config: NextConfig): config is NextConfigFunction {
   return typeof config === 'function';
@@ -21,6 +25,26 @@ function warnAboutEdgeRuntime(): void {
   }
 }
 
+/**
+ * The Next dev server defaults the network guard to `block` (#1443), as the
+ * Vite dev server does (`serve/vite-net-guard.ts`): inside a framework dev
+ * server pyric's plugin wraps, nothing is meant to reach live Firebase except
+ * allowlisted hosts, and a missed import looks swapped to its author. It
+ * escalates the guard the register installed in this process, and sets
+ * `PYRIC_GUARD=block` for the processes Next starts afterward. An explicit
+ * `PYRIC_GUARD` (`warn`, `off`) still names the mode, and `PYRIC_GUARD_ALLOW`
+ * still permits its hosts.
+ */
+function blockByDefaultInDevServer(phase: string): void {
+  const isDevServer = phase === DEV_SERVER_PHASE;
+  const namesMode = (process.env.PYRIC_GUARD ?? '').trim().length > 0;
+  const takesDefault = isDevServer && !namesMode;
+  if (!takesDefault) return;
+  process.env.PYRIC_GUARD = 'block';
+  const guard = (globalThis as unknown as Record<symbol, Pick<NetGuard, 'escalate'> | undefined>)[NET_GUARD_GLOBAL];
+  guard?.escalate(DEV_GUARD_REASON);
+}
+
 function applyPyricEnhancements(config: NextConfigObject, options?: PyricNextOptions): NextConfigObject {
   let enhancedConfig = augmentServerExternalPackages(config);
   enhancedConfig = augmentWebpackConfig(enhancedConfig);
@@ -42,6 +66,7 @@ function applyPyricEnhancements(config: NextConfigObject, options?: PyricNextOpt
  *     to the local Pyric server without CORS errors.
  *   - Enforces a bundler safety interlock (guard) to prevent accidental connections to
  *     production databases when `PYRIC_SANDBOX` is inactive.
+ *   - Defaults the network guard to `block` unless `PYRIC_GUARD` names a mode.
  *
  * In the production build, export and production server phases (without
  * `PYRIC_SANDBOX_FORCE=1`):
@@ -57,6 +82,7 @@ export function withPyric(config: NextConfig = {}, options?: PyricNextOptions):
     }
 
     enforceSandboxGuard(options);
+    blockByDefaultInDevServer(phase);
     warnAboutEdgeRuntime();
 
     const resolvedConfig = isFunctionConfig(config) ? await config(phase, defaults) : config;

package/src/register/activation.ts

@@ -0,0 +1,26 @@
+/**
+ * Whether `@pyric/cli/register` is active in this thread.
+ *
+ * `PYRIC_SANDBOX` asks for the register, but the variable says nothing about
+ * whether it loaded: a `.env` file Next reads, a `NODE_ENV=production`
+ * refusal, or a package script that sets its own `NODE_OPTIONS` each leave the
+ * variable set and the register absent (#1625). Code that depends on the
+ * register reads this mark instead. It lives on `globalThis` under
+ * `Symbol.for`, so it holds across two installed copies of `@pyric/cli`, and
+ * importing this module never activates anything.
+ */
+
+/** Set by the register once its hooks, guard and factory global are in place. */
+const REGISTER_ACTIVE = Symbol.for('pyric.register.active');
+
+type MarkedGlobal = Record<symbol, unknown>;
+
+/** Called by the register at the end of activation. */
+export function markRegisterActive(): void {
+  (globalThis as unknown as MarkedGlobal)[REGISTER_ACTIVE] = true;
+}
+
+/** Whether the register activated in this thread. */
+export function isRegisterActive(): boolean {
+  return (globalThis as unknown as MarkedGlobal)[REGISTER_ACTIVE] === true;
+}

package/src/register/app-bridge-admin-app-check.ts

@@ -7,7 +7,9 @@
  * production AI mode only, and loads this module on the first token whose
  * `kid` is not the sandbox's, so a server that never sees one never loads
  * firebase-admin. `firebase-admin/app` and `firebase-admin/app-check` reach
- * the real package from here (`isBypassedBridgeImport`).
+ * the real package from this module only, and only in production AI mode
+ * (`isBypassedBridgeImport`); the stop in `swap-or-stop.ts` lets them and the
+ * firebase-admin files they import through.
  *
  * Each project gets one firebase-admin app whose credential refuses to mint an
  * access token, so the app cannot fall back to Application Default

package/src/register/child-process-guard.ts

@@ -0,0 +1,189 @@
+/**
+ * The register in child processes.
+ *
+ * A child process of a registered process is in the sandbox, whatever it is
+ * started with (#1618). Node passes a preload to a child only through
+ * `NODE_OPTIONS`, so a child loses the register when the parent got it on the
+ * command line (`node --import @pyric/cli/register`), or when the caller gives
+ * the child its own `NODE_OPTIONS` or `env`. Each of those children kept or
+ * dropped `PYRIC_SANDBOX` and loaded the real `firebase-admin`.
+ *
+ * This module rewrites the environment of every child the process starts:
+ * `NODE_OPTIONS` gets `--import <register>` when it lacks the register, and
+ * each `PYRIC_*` variable this process has and the child's environment lacks
+ * is copied in, `PYRIC_SANDBOX` first among them. A variable the caller set
+ * for the child keeps the caller's value. A shell the process starts passes
+ * the environment on, so a Node process the shell starts is registered too,
+ * unless the command line it runs sets `NODE_OPTIONS` itself
+ * (`NODE_OPTIONS=--max-old-space-size=4096 node server.js`), which no code in
+ * this process can see.
+ *
+ * Every asynchronous child (`spawn`, `exec`, `execFile`, `fork`, and their
+ * promisified forms) is built by `ChildProcess.prototype.spawn` from the env
+ * Node has already resolved, so one wrapper there covers them. The
+ * synchronous forms reach a native binding instead, so `spawnSync`,
+ * `execSync` and `execFileSync` are wrapped where they are exported.
+ */
+import Module, { createRequire } from 'node:module';
+
+type Env = Record<string, string | undefined>;
+
+/** The `child_process` exports this module replaces. */
+interface ChildProcessModule {
+  ChildProcess: { prototype: { spawn?: unknown } };
+  spawnSync: unknown;
+  execSync: unknown;
+  execFileSync: unknown;
+}
+
+/** Marks a function this module already wrapped. */
+const GUARDED = Symbol.for('pyric.guardedChildProcess');
+
+/** The variables that carry the sandbox to a child. */
+const SANDBOX_VARIABLE = /^PYRIC_/;
+
+/** The register, named by its package rather than its file. */
+const REGISTER_BY_NAME = /(^|\s)--import[= ]?["']?@pyric\/cli\/register(["'\s]|$)/;
+
+/** Whether `nodeOptions` already loads the register. */
+function loadsRegister(nodeOptions: string, registerUrl: string): boolean {
+  return nodeOptions.includes(registerUrl) || REGISTER_BY_NAME.test(nodeOptions);
+}
+
+/**
+ * The environment to start a child with, so that it loads the register at
+ * `registerUrl` in the sandbox `parentEnv` names. Returns a new object and
+ * never changes `childEnv`. `file:` URLs are percent-encoded, so the import
+ * needs no quoting in `NODE_OPTIONS`.
+ */
+export function guardChildEnv(childEnv: Env, parentEnv: Env, registerUrl: string): Env {
+  const guarded: Env = { ...childEnv };
+  for (const [name, value] of Object.entries(parentEnv)) {
+    const childLacksIt = guarded[name] === undefined || guarded[name] === '';
+    if (SANDBOX_VARIABLE.test(name) && value !== undefined && childLacksIt) guarded[name] = value;
+  }
+  const nodeOptions = guarded.NODE_OPTIONS ?? '';
+  if (!loadsRegister(nodeOptions, registerUrl)) {
+    const importFlag = `--import ${registerUrl}`;
+    guarded.NODE_OPTIONS = nodeOptions.trim() === '' ? importFlag : `${nodeOptions} ${importFlag}`;
+  }
+  return guarded;
+}
+
+/** `envPairs` (`NAME=value` strings, as `ChildProcess.prototype.spawn` takes them) with the guarded env. */
+export function guardEnvPairs(envPairs: readonly string[], parentEnv: Env, registerUrl: string): string[] {
+  const childEnv: Env = {};
+  for (const pair of envPairs) {
+    const split = pair.indexOf('=');
+    if (split === -1) childEnv[pair] = '';
+    else childEnv[pair.slice(0, split)] = pair.slice(split + 1);
+  }
+  const guarded = guardChildEnv(childEnv, parentEnv, registerUrl);
+  const pairs: string[] = [];
+  for (const [name, value] of Object.entries(guarded)) {
+    if (value !== undefined) pairs.push(`${name}=${value}`);
+  }
+  return pairs;
+}
+
+function isOptions(value: unknown): value is { env?: Env } {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Where a synchronous call's options go. `execSync(command, options)` takes
+ * them second. `spawnSync` and `execFileSync` take `(file, args, options)`,
+ * where `args` may be left out, or passed as `undefined` or `null`.
+ */
+function optionsIndex(takesArgs: boolean, args: readonly unknown[]): number {
+  if (!takesArgs) return 1;
+  const second = args[1];
+  if (isOptions(second)) return 1;
+  const hasArgsSlot = Array.isArray(second) || (second == null && args.length > 2);
+  return hasArgsSlot ? 2 : 1;
+}
+
+/**
+ * The arguments for a synchronous `child_process` call, with options whose
+ * `env` is guarded. A call that names no env gets one built from this
+ * process's env, as Node would build it. Returns new values and never changes
+ * the caller's.
+ */
+export function guardSyncArguments(
+  takesArgs: boolean,
+  args: readonly unknown[],
+  parentEnv: Env,
+  registerUrl: string,
+): unknown[] {
+  const guarded = [...args];
+  const index = optionsIndex(takesArgs, guarded);
+  const options = isOptions(guarded[index]) ? guarded[index] : {};
+  guarded[index] = { ...options, env: guardChildEnv(options.env ?? parentEnv, parentEnv, registerUrl) };
+  return guarded;
+}
+
+type AnyFunction = (this: unknown, ...args: unknown[]) => unknown;
+
+function isGuarded(value: unknown): boolean {
+  return typeof value === 'function' && (value as { [GUARDED]?: true })[GUARDED] === true;
+}
+
+function markGuarded<T extends AnyFunction>(wrapper: T, original: AnyFunction): T {
+  Object.defineProperty(wrapper, GUARDED, { value: true });
+  Object.defineProperty(wrapper, 'name', { value: original.name });
+  return wrapper;
+}
+
+/**
+ * The options `ChildProcess.prototype.spawn` receives, with the env guarded.
+ * Node resolves the child's env into `envPairs` before this call. Bun builds
+ * its children elsewhere and ignores the env here, so its asynchronous
+ * children are not covered; its synchronous ones are.
+ */
+export function guardSpawnOptions(options: unknown, registerUrl: string): unknown {
+  if (!isOptions(options)) return options;
+  const { envPairs } = options as { envPairs?: unknown };
+  if (!Array.isArray(envPairs)) return options;
+  return { ...options, envPairs: guardEnvPairs(envPairs as string[], process.env, registerUrl) };
+}
+
+function guardAsyncSpawn(target: ChildProcessModule, registerUrl: string): void {
+  const prototype = target.ChildProcess?.prototype;
+  const original = prototype?.spawn;
+  if (typeof original !== 'function' || isGuarded(original)) return;
+  const spawnOriginal = original as AnyFunction;
+  prototype.spawn = markGuarded(function (this: unknown, ...args: unknown[]) {
+    args[0] = guardSpawnOptions(args[0], registerUrl);
+    return spawnOriginal.apply(this, args);
+  }, spawnOriginal);
+}
+
+function guardSyncExport(
+  target: ChildProcessModule,
+  name: 'spawnSync' | 'execSync' | 'execFileSync',
+  registerUrl: string,
+): void {
+  const original = target[name];
+  if (typeof original !== 'function' || isGuarded(original)) return;
+  const takesArgs = name !== 'execSync';
+  const syncOriginal = original as AnyFunction;
+  target[name] = markGuarded(function (this: unknown, ...args: unknown[]) {
+    return syncOriginal.apply(this, guardSyncArguments(takesArgs, args, process.env, registerUrl));
+  }, syncOriginal);
+}
+
+/**
+ * Start every child process of this process with the register at
+ * `registerUrl` (see the module comment). `childProcess` defaults to
+ * `node:child_process`; tests pass a stand-in.
+ */
+export function installChildProcessGuard(registerUrl: string, childProcess?: ChildProcessModule): void {
+  const target = childProcess ?? (createRequire(import.meta.url)('node:child_process') as ChildProcessModule);
+  guardAsyncSpawn(target, registerUrl);
+  guardSyncExport(target, 'spawnSync', registerUrl);
+  guardSyncExport(target, 'execSync', registerUrl);
+  guardSyncExport(target, 'execFileSync', registerUrl);
+  // ESM `import { spawnSync } from 'node:child_process'` reads the export as
+  // synced, so publish the replacements there too.
+  if (childProcess === undefined) Module.syncBuiltinESMExports();
+}

package/src/register/client/bootstrap.ts

@@ -9,7 +9,7 @@
  *
  * - the host is resolved as `remoteSandbox()` resolves it for `pyric-admin`
  *   (`PYRIC_SANDBOX_INSTANCE`, the stale-url check, `.pyric/serve.json`), at
- *   the first call that needs it;
+ *   the first call that needs it, and again after the connection is lost;
  * - the served entries get a Node runtime origin: `init.json` and the socket
  *   on that host, the `ws` realm (`./node-realm.ts`), and the refusal every
  *   call gets when the host is not the Node host;
@@ -87,6 +87,11 @@ function hostOnce(): Promise<string> {
   return host;
 }
 
+/** A lost connection resolves the host again at the next call; a host that moved is found where it now runs. */
+function forgetHost(): void {
+  host = undefined;
+}
+
 const socketRealm = createNodeSocketRealm({ onAttached: ack => reportVersionSkew(ack.serveVersion) });
 // The in-process host ended for good (its dev server closed): let the process go.
 onProcessActivationEnd(() => socketRealm.releaseAll());
@@ -94,6 +99,7 @@ onProcessActivationEnd(() => socketRealm.releaseAll());
 installNodeRuntimeOrigin({
   realm: 'node',
   host: hostOnce,
+  forgetHost,
   socketRealm,
   offHostError: (detail) => inProcessActivation()?.offHostError(detail) ?? offHostRefusal(detail),
 });

package/src/register/connect-prototypes.ts

@@ -57,3 +57,15 @@ export function nodeSocketPrototypes(): object[] {
   return builtinPrototypes([['node:net', 'Socket']]);
 }
 
+/**
+ * The `http.ClientRequest` prototype. Every `http.request` and `https.request`
+ * reaches `ClientRequest.prototype.onSocket` once it has a socket, whether an
+ * Agent made it or the caller's `createConnection` did, and before the request
+ * line is written. It is the one place the request's own `method` and `path`
+ * are readable: an Agent's `createConnection` receives `path: null`. A
+ * `CONNECT` request names its real destination there.
+ */
+export function nodeClientRequestPrototypes(): object[] {
+  return builtinPrototypes([['node:http', 'ClientRequest']]);
+}
+

package/src/register/hooks.ts

@@ -8,7 +8,9 @@
  * a warning saying exactly that). Keep this module free of side effects and
  * heavy imports: the loader thread re-instantiates it in isolation.
  */
-import { mapFirebaseSpecifier } from './mapping.js';
+import { canonicalFirebaseSpecifier, mapFirebaseSpecifier } from './mapping.js';
+import { resolvesIntoPackage } from './package-identity.js';
+import { createStopReporter, stopFor } from './swap-or-stop.js';
 
 interface ResolveContext {
   parentURL?: string;
@@ -21,11 +23,62 @@ interface ResolveResult {
   shortCircuit?: boolean;
 }
 
-export function resolve(
+type NextResolve = (specifier: string, context?: ResolveContext) => Promise<ResolveResult>;
+
+/**
+ * A Turbopack-renamed import (`firebase-admin-<hash>/app`, #1443) resolves as
+ * given first, and maps by its canonical name only when that landed in the
+ * real package, so an unrelated package with such a name stays itself.
+ */
+async function resolveRenamed(
   specifier: string,
+  canonical: string,
   context: ResolveContext,
-  nextResolve: (specifier: string, context?: ResolveContext) => Promise<ResolveResult>,
+  nextResolve: NextResolve,
 ): Promise<ResolveResult> {
+  const renamed = await nextResolve(specifier, context);
+  const isRealFirebasePackage = resolvesIntoPackage(renamed.url, canonical);
+  if (!isRealFirebasePackage) return renamed;
+  const mappedSpecifier = mapFirebaseSpecifier(canonical, context.parentURL);
+  if (mappedSpecifier === null) return renamed;
+  return nextResolve(mappedSpecifier, context);
+}
+
+const reportStop = createStopReporter((line) => void process.stderr.write(line));
+/** The real SDK files this hook allowed (`stopFor`). */
+const allowedUrls = new Set<string>();
+
+/**
+ * Swap or stop (ADR 0022). A throw here rejects the import on the main
+ * thread, so this hook stops ESM imports of the real SDK without reaching the
+ * network guard. CommonJS `require` never reaches this hook.
+ */
+export async function resolve(
+  specifier: string,
+  context: ResolveContext,
+  nextResolve: NextResolve,
+): Promise<ResolveResult> {
+  const result = await resolveFirebase(specifier, context, nextResolve);
+  const stop = stopFor({
+    specifier,
+    canonical: canonicalFirebaseSpecifier(specifier),
+    importer: context.parentURL,
+    url: result.url,
+  }, allowedUrls);
+  if (stop === null) return result;
+  reportStop(stop);
+  throw stop;
+}
+
+function resolveFirebase(
+  specifier: string,
+  context: ResolveContext,
+  nextResolve: NextResolve,
+): Promise<ResolveResult> {
+  const canonical = canonicalFirebaseSpecifier(specifier);
+  if (canonical !== null) {
+    return resolveRenamed(specifier, canonical, context, nextResolve);
+  }
   const mappedSpecifier = mapFirebaseSpecifier(specifier, context.parentURL);
   const hasMappedSpecifier = mappedSpecifier !== null && mappedSpecifier !== undefined;
   if (hasMappedSpecifier) {