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

package/src/register/swap-or-stop.ts

@@ -0,0 +1,194 @@
+/**
+ * Swap or stop (ADR 0022): under the register, `firebase` and `firebase-admin`
+ * imports resolve to the sandbox. When a resolve lands in the real SDK anyway,
+ * through an absolute path, an npm alias, a link under another name, or a
+ * direct `@firebase/*` import, the import stops before the file loads. The
+ * real SDK never runs, so it never reaches production with this machine's
+ * credentials.
+ *
+ * The package is named by the resolved file's own `package.json`
+ * (`package-identity.ts`), never by its folder. Only files under a
+ * `node_modules` directory are checked: every installed SDK lives under one,
+ * including the pnpm and bun stores, and the check stays off the resolve path
+ * for everything else.
+ *
+ * The real SDK is allowed only where the swap table chooses it
+ * (`choosesRealFirebase` in `mapping.ts`), or when an SDK file this hook
+ * already allowed imports what its entry needs: a firebase-admin file
+ * reaches only the verifier bridge pair's files, and a client SDK file only
+ * the `@firebase/*` packages the production AI entries import. The importer's
+ * URL alone is no proof, since `createRequire` can name any file, so each
+ * hook keeps the URLs it allowed. In sandbox AI mode that set stays empty.
+ * `firebase-admin` is never chosen, with one exception: the App Check verifier
+ * bridge that production AI mode loads on pyric's behalf (#1552), whose
+ * firebase-admin app holds no credentials. An app's own import of the real
+ * package still stops. `PYRIC_GUARD` does not change any of this: the stop
+ * belongs to the swap, not to the network guard.
+ *
+ * Loaded by both resolve hooks, including the loader-thread one, so it imports
+ * node built-ins and side-effect-free modules only.
+ */
+import { fileURLToPath } from 'node:url';
+import { packageNameOf, pathInPackageOf } from './package-identity.js';
+import { choosesRealFirebase } from './mapping.js';
+import {
+  SDK_MODULES,
+  isAdminBridgeFile,
+  isBypassedBridgeImport,
+  isProductionAiSdkPackage,
+  resolveAiMode,
+  type AiMode,
+} from '../serve/firebase-module-swap.js';
+
+/** The code on the error a stopped import throws. */
+export const REAL_SDK_STOPPED_CODE = 'PYRIC_REAL_SDK_STOPPED';
+
+const LOG_PREFIX = '@pyric/cli/register';
+const REPORT_URL = 'https://github.com/davideast/pyric/issues/new';
+
+/** One resolve the register finished: what was asked, by whom, and where it landed. */
+export interface ResolvedLoad {
+  readonly specifier: string;
+  /** The canonical name of a Turbopack-renamed specifier, when it is one. */
+  readonly canonical?: string | null;
+  readonly importer: string | undefined;
+  readonly url: string;
+  /** Defaults to the mode `PYRIC_AI_MODE` and `PYRIC_AI_PASSTHROUGH` select. */
+  readonly aiMode?: AiMode;
+  /** Defaults to the manifest lookup in `package-identity.ts`. */
+  readonly nameOf?: (url: string) => string | null;
+  /** Defaults to `pathInPackageOf` in `package-identity.ts`. */
+  readonly pathInPackage?: (url: string, packageName: string) => string | null;
+}
+
+type SdkFamily = 'admin' | 'client';
+
+/** `firebase-admin` is the admin SDK; `firebase` and every `@firebase/*` package are the client SDK. */
+function sdkFamilyOf(name: string | null): SdkFamily | null {
+  if (name === 'firebase-admin') return 'admin';
+  const isClientPackage = name === 'firebase' || (name?.startsWith('@firebase/') ?? false);
+  return isClientPackage ? 'client' : null;
+}
+
+function isInstalledFile(url: string): boolean {
+  return url.startsWith('file:') && url.includes('/node_modules/');
+}
+
+/**
+ * Whether this load is an SDK file the hook already allowed, importing what
+ * that SDK entry needs: a firebase-admin file reaches only the files of the
+ * verifier bridge's `firebase-admin/app` and `firebase-admin/app-check`, and a
+ * client SDK file only the `@firebase/*` packages that `firebase/ai`,
+ * `firebase/app` and `firebase/app-check` import. So a `createRequire` forge
+ * from an allowed file gets no further than the entry it came from.
+ */
+function isFromAllowedSdkFile(load: ResolvedLoad, packageName: string, allowedUrls: ReadonlySet<string>): boolean {
+  const importer = load.importer;
+  const isAllowedImporter = importer !== undefined && allowedUrls.has(importer);
+  if (!isAllowedImporter) return false;
+  const importerFamily = sdkFamilyOf((load.nameOf ?? packageNameOf)(importer));
+  if (importerFamily === 'client') return isProductionAiSdkPackage(packageName);
+  const isAdminTarget = importerFamily === 'admin' && packageName === 'firebase-admin';
+  if (!isAdminTarget) return false;
+  const pathOf = load.pathInPackage ?? pathInPackageOf;
+  return isAdminBridgeFile(pathOf(load.url, packageName));
+}
+
+/** Whether this load may reach the real SDK. */
+function isAllowedRealLoad(load: ResolvedLoad, packageName: string, family: SdkFamily, allowedUrls: ReadonlySet<string>): boolean {
+  if (isFromAllowedSdkFile(load, packageName, allowedUrls)) return true;
+  const specifier = load.canonical ?? load.specifier;
+  const aiMode = load.aiMode ?? resolveAiMode(undefined, process.env);
+  if (family === 'admin') return isBypassedBridgeImport(specifier, load.importer, aiMode);
+  const pathOf = load.pathInPackage ?? pathInPackageOf;
+  return choosesRealFirebase({
+    specifier,
+    importer: load.importer,
+    packageName,
+    pathInPackage: () => pathOf(load.url, packageName),
+    aiMode,
+  });
+}
+
+/** The served `firebase/*` import that stands for a `@firebase/*` package, when pyric serves one. */
+function servedImportFor(packageName: string): string | null {
+  const candidate = `firebase/${packageName.slice('@firebase/'.length)}`;
+  const isServed = (SDK_MODULES as readonly string[]).includes(candidate);
+  return isServed ? candidate : null;
+}
+
+/** The import an app writes in place of the one that stopped. */
+function fixFor(family: SdkFamily, packageName: string): string {
+  if (family === 'admin') {
+    return "import firebase-admin by its package name (for example 'firebase-admin/app'), so the register routes it to the sandbox";
+  }
+  if (packageName === 'firebase') {
+    return "import firebase by its package name (for example 'firebase/firestore'), so the register routes it to the sandbox";
+  }
+  const served = servedImportFor(packageName);
+  if (served === null) {
+    return `pyric serves no firebase/* import for '${packageName}', so import a served one (for example 'firebase/firestore'), or move this code out of the sandboxed process`;
+  }
+  return `import '${served}' instead of '${packageName}', so the register routes it to the sandbox`;
+}
+
+function stopMessage(load: ResolvedLoad, family: SdkFamily, packageName: string): string {
+  const consequence = family === 'admin'
+    ? "so it would have run with this machine's Google credentials"
+    : "so it would have reached production with the app's API key";
+  return [
+    `${LOG_PREFIX}: stopped loading the real ${packageName}`,
+    `  import '${load.specifier}'`,
+    `  from   ${load.importer ?? 'the entry point'}`,
+    `  found  ${load.url}`,
+    `Under pyric, ${packageName} resolves to the sandbox. This import didn't, ${consequence}.`,
+    `Fix: ${fixFor(family, packageName)}. To run the real SDK, start this process without @pyric/cli/register.`,
+    `If pyric should have routed this import, report it: ${REPORT_URL}`,
+    `code: ${REAL_SDK_STOPPED_CODE}`,
+  ].join('\n');
+}
+
+/**
+ * Whether this load is Node 22 resolving again a CommonJS file this hook
+ * already allowed. Node 22 resolves a CommonJS file imported from ESM a second
+ * time, by its own path and with no importer; Node 24 does not. That second
+ * pass loads nothing new, so it goes ahead. An app's import of the same file
+ * names its importer, so it still stops.
+ */
+function isCjsReloadOfAllowedFile(load: ResolvedLoad, allowedUrls: ReadonlySet<string>): boolean {
+  const hasNoImporter = load.importer === undefined;
+  const wasAllowed = allowedUrls.has(load.url);
+  if (!hasNoImporter || !wasAllowed) return false;
+  return load.specifier === fileURLToPath(load.url);
+}
+
+/**
+ * The error that stops this load, or `null` when the load may go ahead: it is
+ * not the real SDK, or the swap table chose the real SDK here. `allowedUrls`
+ * is the calling hook's record of the real SDK files it allowed; an allowed
+ * load joins it.
+ */
+export function stopFor(load: ResolvedLoad, allowedUrls: Set<string>): Error | null {
+  if (!isInstalledFile(load.url)) return null;
+  const packageName = (load.nameOf ?? packageNameOf)(load.url);
+  const family = sdkFamilyOf(packageName);
+  if (family === null || packageName === null) return null;
+  if (isCjsReloadOfAllowedFile(load, allowedUrls)) return null;
+  if (isAllowedRealLoad(load, packageName, family, allowedUrls)) {
+    allowedUrls.add(load.url);
+    return null;
+  }
+  const error = new Error(stopMessage(load, family, packageName));
+  return Object.assign(error, { code: REAL_SDK_STOPPED_CODE, url: load.url, specifier: load.specifier });
+}
+
+/** Writes each stop to stderr once per file, so a caught import still shows in the log. */
+export function createStopReporter(write: (line: string) => void): (error: Error) => void {
+  const reported = new Set<string>();
+  return (error) => {
+    const url = (error as { url?: string }).url ?? error.message;
+    if (reported.has(url)) return;
+    reported.add(url);
+    write(`${error.message}\n`);
+  };
+}

package/src/register/worker-guard.ts

@@ -0,0 +1,90 @@
+/**
+ * The register in worker threads.
+ *
+ * Built-in modules and resolve hooks are per thread, so the swap, the stop
+ * and the network guard have to be installed inside each worker as well. The
+ * register installs this wrapper whatever `PYRIC_GUARD` says. Node runs `--import` preloads (from the command
+ * line or `NODE_OPTIONS`) in a worker built from a file, a `data:` URL or ESM
+ * source, and the register then activates there as it does on the main
+ * thread. Two kinds of worker skip it:
+ *
+ *  - a worker built from CommonJS source with `eval: true`, which never runs
+ *    preloads;
+ *  - a worker given its own `execArgv`, when the register came from the
+ *    command line rather than `NODE_OPTIONS`.
+ *
+ * Wrapping `worker_threads.Worker` closes both. The worker still activates
+ * the register only under its own `PYRIC_SANDBOX`, exactly as the main thread
+ * does, so a worker the caller started outside the sandbox stays outside it.
+ */
+import Module, { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+/** The `Worker` options this module reads. */
+interface WorkerOptionsLike {
+  eval?: unknown;
+  execArgv?: unknown;
+}
+
+type WorkerConstructor = new (source: unknown, options?: unknown) => object;
+
+/** Marks a `Worker` this module already wrapped. */
+const GUARDED_WORKER = Symbol.for('pyric.guardedWorker');
+
+/** A `'use strict'` directive, which must stay the first statement. */
+const USE_STRICT = /^(\s*(['"])use strict\2;?[ \t]*\n?)/;
+
+/**
+ * The arguments to build the worker with, so that it loads the register at
+ * `registerUrl`. Returns new values and never changes the caller's.
+ */
+export function guardWorkerArguments(
+  source: unknown,
+  options: WorkerOptionsLike | undefined,
+  registerUrl: string,
+): [unknown, WorkerOptionsLike | undefined] {
+  let guardedSource = source;
+  let guardedOptions = options;
+  if (options?.eval === true && typeof source === 'string') {
+    guardedSource = withRegisterPrefix(source, registerUrl);
+  }
+  if (Array.isArray(options?.execArgv) && !options.execArgv.includes(registerUrl)) {
+    guardedOptions = { ...options, execArgv: [...options.execArgv, '--import', registerUrl] };
+  }
+  return [guardedSource, guardedOptions];
+}
+
+/**
+ * Eval source that first loads the register. `require` exists only when Node
+ * runs the source as CommonJS; ESM source already ran the preload, and the
+ * prefix does nothing there.
+ */
+function withRegisterPrefix(source: string, registerUrl: string): string {
+  const prefix = `typeof require === 'function' && require(${JSON.stringify(fileURLToPath(registerUrl))});\n`;
+  const directive = USE_STRICT.exec(source)?.[1];
+  if (directive === undefined) return `${prefix}${source}`;
+  const separator = directive.endsWith('\n') ? '' : '\n';
+  return `${directive}${separator}${prefix}${source.slice(directive.length)}`;
+}
+
+/**
+ * Replace `workerThreads.Worker` with a subclass that builds every worker with
+ * {@link guardWorkerArguments}. A subclass keeps `instanceof Worker` true.
+ * `workerThreads` defaults to `node:worker_threads`; tests pass a stand-in.
+ */
+export function installWorkerGuard(registerUrl: string, workerThreads?: { Worker: unknown }): void {
+  const target = workerThreads ?? (createRequire(import.meta.url)('node:worker_threads') as { Worker: unknown });
+  const Original = target.Worker as (WorkerConstructor & { [GUARDED_WORKER]?: true }) | undefined;
+  if (typeof Original !== 'function' || Original[GUARDED_WORKER] === true) return;
+  class GuardedWorker extends Original {
+    static readonly [GUARDED_WORKER] = true;
+    constructor(source: unknown, options?: WorkerOptionsLike) {
+      super(...guardWorkerArguments(source, options, registerUrl));
+    }
+  }
+  Object.defineProperty(GuardedWorker, 'name', { value: Original.name });
+  target.Worker = GuardedWorker;
+  // ESM `import { Worker } from 'node:worker_threads'` reads the export as
+  // synced, so publish the replacement there too.
+  if (workerThreads === undefined) Module.syncBuiltinESMExports();
+}

package/src/remote/resolve-host.ts

@@ -6,6 +6,13 @@
  * Shared by the Node remote client (`connectRemoteSandbox`, which
  * `pyric-admin` uses) and the client SDK bootstrap that `@pyric/cli/register`
  * installs (#1082), so both pick the same host for the same process.
+ *
+ * Discovery reads the project's `.pyric/serve.json` and probes the port it
+ * names, without the port scan `discoverServe` falls back to: a host found
+ * only by the scan is never attached to (`selectProjectHost`), and on a
+ * machine where closed ports never answer the scan takes seconds. A process
+ * resolves again at each reconnect, so a scan there would spend the window
+ * its held calls wait in (#1219).
  */
 import {
   discoverServe,
@@ -54,12 +61,17 @@ function warnOncePerUrl(url: string, message: string, warn?: (message: string) =
   else process.stderr.write(`${message}\n`);
 }
 
+/** The project's host as its `.pyric/serve.json` names it; no port scan. */
+export function discoverProjectPointer(cwd: string): Promise<Discovered | null> {
+  return discoverServe(cwd, () => {}, []);
+}
+
 async function resolveConfiguredHost(configuredUrl: string, options: ResolveRemoteHostOptions): Promise<ResolvedRemoteHost> {
   const choice = await selectExplicitHost({
     url: configuredUrl,
     cwd: options.cwd,
     launcherInstanceId: options.instanceId,
-    discover: options.discover,
+    discover: options.discover ?? discoverProjectPointer,
     probe: options.probe,
   });
   if (choice.kind === 'stale') throw hostError('not-found', choice.message);
@@ -73,7 +85,7 @@ async function resolveConfiguredHost(configuredUrl: string, options: ResolveRemo
 
 async function discoverProjectHost(options: ResolveRemoteHostOptions): Promise<ResolvedRemoteHost> {
   const refused: string[] = [];
-  const found = selectProjectHost(await (options.discover ?? discoverServe)(options.cwd), (m) => refused.push(m));
+  const found = selectProjectHost(await (options.discover ?? discoverProjectPointer)(options.cwd), (m) => refused.push(m));
   const hasNoDiscovery = found === null;
   if (hasNoDiscovery) {
     throw hostError(

package/src/serve/ai-proxy.ts

@@ -10,14 +10,14 @@
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { ServeLogger } from './server.js';
-import { redactUrl } from 'pyric/ai/internal';
+import { redactUpstreamText, redactUrl } from 'pyric/ai/internal';
 import { sanitizeForTerminal } from './ai-terminal-text.js';
 import type { AiEngineConfigWire } from './worker/protocol.js';
 import { permitGuardHost } from '../register/net-guard.js';
 import { FIREBASE_AI_LOGIC_HOST } from '../google-endpoints.js';
 import type { AiMode } from './firebase-module-swap.js';
 import { HOSTED_METHOD_BODY_LIMIT } from './hosted/method-protocol.js';
-import { BODY_TOO_LARGE_CODE, collectRawBody } from '../bridge/server/peer.js';
+import { BODY_TOO_LARGE_CODE, closingHeaders, collectRawBody } from '../bridge/server/peer.js';
 
 /** The dev server's diagnostics throttle, as this module needs it: the
  *  denials route owns the instance, and the proxy shares it so a failing
@@ -70,6 +70,8 @@ type AiProxyFailure =
       status: number;
       /** The upstream's raw `Retry-After` header, when it sent one. */
       retryAfter?: string;
+      /** The credentials the request carried, masked from `retryAfter`. */
+      credentials?: readonly string[];
     }
   | { kind: 'stream-abort'; target: string; latencyMs: number; cause: string };
 
@@ -82,13 +84,17 @@ const AI_PROXY_RETRY_AFTER_MAX = 64;
  * nothing worth printing.
  *
  * The header is remote-authored, so it is sanitized and length-capped like
- * every other upstream string that reaches the terminal. Delta-seconds (the
+ * every other upstream string that reaches the terminal. It is masked of the
+ * request's credentials first, with the masking the gemini engine and proxy
+ * use (`redactUpstreamText`), so the cap cannot leave a prefix of a key
+ * behind. Delta-seconds (the
  * common form) get an `s` suffix so the wait reads as a duration; the
  * HTTP-date form is echoed verbatim, since `Wed, 21 Oct 2026 07:28:00 GMTs`
  * would be nonsense.
  */
-function formatRetryAfter(raw: string): string | null {
-  const clean = sanitizeForTerminal(raw).slice(0, AI_PROXY_RETRY_AFTER_MAX).trim();
+function formatRetryAfter(raw: string, credentials: readonly string[]): string | null {
+  const masked = redactUpstreamText(raw, credentials);
+  const clean = sanitizeForTerminal(masked).slice(0, AI_PROXY_RETRY_AFTER_MAX).trim();
   if (clean === '') return null;
   if (/^\d+$/.test(clean)) return `${clean}s`;
   return clean;
@@ -161,7 +167,7 @@ export function formatAiProxyWarning(failure: AiProxyFailure, source = 'ai-proxy
     );
   }
   if (failure.kind === 'status' && failure.retryAfter !== undefined) {
-    const wait = formatRetryAfter(failure.retryAfter);
+    const wait = formatRetryAfter(failure.retryAfter, failure.credentials ?? []);
     if (wait !== null) {
       lines.push(`      Retry-After: ${wait}, no automatic retry; the status went to the caller`);
     }
@@ -229,6 +235,28 @@ export function permitAiUpstreams(ai: {
   for (const destination of destinations) permitGuardHost(destination);
 }
 
+/** The `key` parameter of `target`, or null when it has none or is not a URL. */
+function urlKeyParam(target: string): string | null {
+  try {
+    return new URL(target).searchParams.get('key');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The credentials an upstream request carries: the `key` URL parameter, the
+ * `x-goog-api-key` header, and the `Authorization` value without its scheme.
+ */
+function requestCredentials(input: Parameters<typeof fetch>[0], init: RequestInit | undefined): string[] {
+  const isRequest = input instanceof Request;
+  const headers = new Headers(isRequest ? input.headers : init?.headers);
+  const urlKey = urlKeyParam(isRequest ? input.url : String(input));
+  const authorization = headers.get('authorization')?.replace(/^\S+\s+/, '') ?? null;
+  const found = [urlKey, headers.get('x-goog-api-key'), authorization];
+  return found.filter((value): value is string => value !== null && value !== '');
+}
+
 /** Shared upstream I/O for the browser proxy and the direct Node engine.
  * Responses remain incremental; cancellation stops reading without a warning.
  */
@@ -255,7 +283,7 @@ export async function fetchAiUpstream(
   if (failed) {
     const retryAfter = upstream.headers.get('retry-after');
     note({ kind: 'status', target, latencyMs: Date.now() - startedAt, status: upstream.status,
-      ...(retryAfter !== null ? { retryAfter } : {}) });
+      ...(retryAfter !== null ? { retryAfter, credentials: requestCredentials(input, init) } : {}) });
   }
   const body = upstream.body;
   const hasNoBody = body === null;
@@ -300,7 +328,7 @@ export async function readAiProxyBody(
   } catch (error) {
     const tooLarge = (error as { code?: unknown }).code === BODY_TOO_LARGE_CODE;
     const status = tooLarge ? 413 : 400;
-    res.writeHead(status, { 'content-type': 'text/plain' }).end(tooLarge ? 'Payload Too Large' : 'Bad Request');
+    res.writeHead(status, closingHeaders({ 'content-type': 'text/plain' })).end(tooLarge ? 'Payload Too Large' : 'Bad Request');
     return null;
   }
 }

package/src/serve/app-ports.ts

@@ -0,0 +1,119 @@
+/**
+ * The ports a page of this app may name in its `Origin` when it opens the
+ * bridge socket or calls a control route.
+ *
+ * A page this server serves names the server's own port. Under a dev server
+ * that proxies `/__pyric/*` to this one, such as `withPyric`'s rewrite under
+ * `pyric sandbox -- next dev`, the page loads from the dev server, so its
+ * Origin names the dev server's port instead. The proxy says which port that
+ * is: it forwards each request with `x-forwarded-host` set to the host the
+ * browser asked it for. A socket the proxy forwards (the Node host's page)
+ * carries that header itself. A socket that comes straight to this server
+ * (the SharedWorker sandbox) does not, but the page's `/__pyric/init.json`
+ * went through the proxy before the page learned the bridge URL, so the
+ * port was learned from that request.
+ *
+ * Only a same-origin request teaches a port: one whose `sec-fetch-site` is
+ * `same-origin`, which the browser sets and a page cannot change. The page
+ * Next serves fetches `/__pyric/*` from Next's own origin, and the proxy
+ * passes the header through. A page on another port that sends the request
+ * itself, even with an `x-forwarded-host` it chose, is `same-site` at most,
+ * so it teaches nothing. A proxy names its own host, never the page's, so a
+ * page on another port that goes through the proxy is still refused. Only
+ * loopback names and the bound host are learned; a name allowed through
+ * `--allowed-host` (a tunnel) is never port-checked in the first place.
+ *
+ * Only the standalone server learns (`learnsProxyPorts`). A mount inside a
+ * dev server, such as the Vite plugin's, serves the page on the connection's
+ * own port, and that dev server may answer cross-origin preflights for
+ * `/__pyric/*` paths it does not handle.
+ */
+import type { IncomingMessage } from 'node:http';
+import { getHeader, isAllowedHost } from './server.js';
+
+/** A dev server proxies from one port; a handful covers restarts on new ports. */
+const MAX_LEARNED_PORTS = 8;
+
+export interface AppPorts {
+  /** Records the proxy port a same-origin forwarded request names. */
+  learn(req: IncomingMessage): void;
+  /** The ports a page's Origin may name on this request's connection. */
+  forRequest(req: IncomingMessage): number[];
+  /**
+   * The same, plus the proxy's port when a proxy forwarded this WebSocket
+   * upgrade from the page it serves: the Origin names the host the proxy
+   * names in `x-forwarded-host`. A browser cannot put a header on a
+   * WebSocket handshake, so only a proxy can name that host, and it names
+   * its own. The page may open its socket before any same-origin request
+   * has gone through the proxy, as the Node host's page under Next does.
+   */
+  forUpgrade(req: IncomingMessage): number[];
+}
+
+export function createAppPorts(boundHost: string): AppPorts {
+  const learned = new Set<number>();
+  const forRequest = (req: IncomingMessage): number[] => {
+    const ports = [...learned];
+    const localPort = req.socket?.localPort;
+    const hasLocalPort = typeof localPort === 'number';
+    if (hasLocalPort) ports.unshift(localPort);
+    return ports;
+  };
+  return {
+    learn(req) {
+      const isSameOrigin = getHeader(req, 'sec-fetch-site') === 'same-origin';
+      if (!isSameOrigin) return;
+      const port = forwardedLoopbackPort(getHeader(req, 'x-forwarded-host'), boundHost);
+      const namesNoPort = port === undefined;
+      if (namesNoPort) return;
+      learned.delete(port);
+      learned.add(port);
+      const isOverCapacity = learned.size > MAX_LEARNED_PORTS;
+      if (isOverCapacity) learned.delete(learned.values().next().value as number);
+    },
+    forRequest,
+    forUpgrade(req) {
+      const ports = forRequest(req);
+      const proxyPort = proxiedPagePort(req, boundHost);
+      const isProxiedFromItsPage = proxyPort !== undefined;
+      if (isProxiedFromItsPage) ports.push(proxyPort);
+      return ports;
+    },
+  };
+}
+
+/** The proxy's port when the Origin names the host `x-forwarded-host` names, else `undefined`. */
+function proxiedPagePort(req: IncomingMessage, boundHost: string): number | undefined {
+  const forwardedHost = getHeader(req, 'x-forwarded-host');
+  const originHeader = getHeader(req, 'origin');
+  const lacksEither = forwardedHost === undefined || originHeader === undefined;
+  if (lacksEither) return undefined;
+  let origin: URL;
+  try {
+    origin = new URL(originHeader);
+  } catch {
+    return undefined;
+  }
+  const namesTheProxy = origin.host.toLowerCase() === forwardedHost.trim().toLowerCase();
+  if (!namesTheProxy) return undefined;
+  return forwardedLoopbackPort(forwardedHost, boundHost);
+}
+
+/** The port in a single loopback `x-forwarded-host`, else `undefined`. */
+function forwardedLoopbackPort(forwardedHost: string | undefined, boundHost: string): number | undefined {
+  const hasNoForwardedHost = forwardedHost === undefined || forwardedHost.trim() === '';
+  if (hasNoForwardedHost) return undefined;
+  const namesSeveralHosts = forwardedHost.includes(',');
+  if (namesSeveralHosts) return undefined;
+  let forwarded: URL;
+  try {
+    forwarded = new URL(`http://${forwardedHost.trim()}`);
+  } catch {
+    return undefined;
+  }
+  const isLoopback = isAllowedHost(forwarded.hostname, boundHost);
+  if (!isLoopback) return undefined;
+  const namesNoPort = forwarded.port === '';
+  if (namesNoPort) return 80;
+  return Number(forwarded.port);
+}

package/src/serve/bridge-mount.ts

@@ -29,8 +29,10 @@ import { getBridgeToolSurface } from '../bridge/server/mcp-contract.js';
 import { createAuditWriter } from '../bridge/server/audit.js';
 import { attachPeer, collectBody, BODY_TOO_LARGE_CODE } from '../bridge/server/peer.js';
 import { pointerHeldByAnotherHost } from './discovery.js';
+import { boundedFetch } from '../bounded-request.js';
 import { pyricVersion } from './standalone-assets.js';
 import { getHeader, isAllowedHost, isAllowedLoopbackRequest, isAllowedOrigin, isAllowedUpgrade } from './server.js';
+import { createAppPorts, type AppPorts } from './app-ports.js';
 import { MAX_BRIDGE_FRAME_BYTES, MAX_MOUNTED_MCP_SESSIONS, STORAGE_BYTE_ROUTE_CAPABILITY, WORKER_PORT_CAPABILITY, WORKER_RELAY_CAPABILITY } from '../bridge/protocol.js';
 import { STORAGE_ROUTE_PREFIX } from './worker/protocol/storage.js';
 import type { DatabaseRulesDestination, InitPayload } from './init-payload.js';
@@ -40,9 +42,15 @@ import { MCP_PROJECT_HEADER, MCP_INSTANCE_HEADER, mcpProjectError } from './mcp-
 
 const WS_PATH = '/__pyric/sandbox';
 const MCP_PATH = '/__pyric/mcp';
-const HEALTH_PATH = '/__pyric/health';
+export const HEALTH_PATH = '/__pyric/health';
 const BRIDGE_VERSION = pyricVersion();
 
+/** The 503 a closed mount answers its routes with, so a client knows the host is going away. */
+export function answerMountClosed(res: ServerResponse): void {
+  res.writeHead(503, { 'content-type': 'application/json' });
+  res.end(JSON.stringify({ error: 'pyric bridge: mount is closed' }));
+}
+
 /**
  * Test-only: `PYRIC_TEST_PEER_LIVENESS_MS` shortens the host's peer liveness
  * window so app scenarios (`test/apps/host-closes-silent-page`) need not wait
@@ -68,6 +76,15 @@ export interface BridgeMountOptions {
    *  `allowedHosts: true` = the caller (vite `server.allowedHosts: true`) opted
    *  into all hosts. Omit ⇒ loopback-only. */
   upgradeGuard?: { boundHost: string; allowedHosts?: string[] | true };
+  /** Accept a page on the port of a dev server that proxies `/__pyric/*` to
+   *  this one (`pyric sandbox -- next dev`). Only the standalone server sets
+   *  it. A mount inside a dev server, such as the Vite plugin's, serves the
+   *  page on its own port, which the connection's port already covers. */
+  learnsProxyPorts?: boolean;
+  /** The app's ports, shared with the namespace's guarded routes. The caller
+   *  that passes them teaches them from each request, so the mount does not.
+   *  Absent, the mount keeps its own and learns when `learnsProxyPorts`. */
+  appPorts?: AppPorts;
 }
 
 export interface BridgeMount {
@@ -131,6 +148,10 @@ export interface BridgeHostAttachment {
 
 export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
   const peerOptions = { livenessTimeoutMs: testPeerLivenessMs() };
+  // The ports a page of this app may name in its Origin (see app-ports.ts).
+  const sharesPorts = opts.appPorts !== undefined;
+  const appPorts = opts.appPorts ?? createAppPorts(opts.upgradeGuard?.boundHost ?? 'localhost');
+  const learnsHere = opts.learnsProxyPorts === true && !sharesPorts;
   let hostedRuntime: Awaited<ReturnType<typeof createHostedRuntime>> | undefined;
   let hostedStartup: Promise<void> | undefined;
   let disconnectHosted: (() => void) | undefined;
@@ -313,6 +334,7 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
     instanceId: bridge.instanceId,
 
     async handler(req, res, url) {
+      if (learnsHere) appPorts.learn(req);
       const isHealthRequest = url.pathname === HEALTH_PATH;
       const isMcpRequest = url.pathname === MCP_PATH;
       const isHostedRepro = url.pathname === HOSTED_REPRO_PATH;
@@ -321,8 +343,7 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
       const isStorageBytes = url.pathname.startsWith(STORAGE_ROUTE_PREFIX);
       const rejectsClosedRequest = closed && (isHealthRequest || isMcpRequest || isHostedMethod || isStorageBytes);
       if (rejectsClosedRequest) {
-        res.writeHead(503, { 'content-type': 'application/json' });
-        res.end(JSON.stringify({ error: 'pyric bridge: mount is closed' }));
+        answerMountClosed(res);
         return true;
       }
       if (isHealthRequest) {
@@ -338,7 +359,7 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
           const allowedHosts = guard?.allowedHosts;
           const hasNamedHosts = Array.isArray(allowedHosts);
           const extra = hasNamedHosts ? allowedHosts : [];
-          const isForbidden = !isAllowedLoopbackRequest(req, boundHost, extra);
+          const isForbidden = !isAllowedLoopbackRequest(req, boundHost, extra, appPorts.forRequest(req));
           if (isForbidden) {
             res.writeHead(403, { 'content-type': 'application/json' });
             res.end(JSON.stringify({ error: 'Forbidden: invalid host or origin' }));
@@ -534,7 +555,9 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
           const allowedHosts = guard.allowedHosts;
           const hasNamedHosts = Array.isArray(allowedHosts);
           const extra = hasNamedHosts ? allowedHosts : [];
-          const isForbidden = !isAllowedUpgrade(req.headers, boundHost, extra);
+          const acceptsProxiedPage = opts.learnsProxyPorts === true;
+          const ports = acceptsProxiedPage ? appPorts.forUpgrade(req) : appPorts.forRequest(req);
+          const isForbidden = !isAllowedUpgrade(req.headers, boundHost, extra, ports);
           if (isForbidden) {
             socket.destroy();
             return;
@@ -583,11 +606,16 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
         if (hasNoCollisionProbe) return;
         const cannotProbe = !currentOrigin?.port || attachmentClosed;
         if (cannotProbe) return;
+        // By default a bounded request, connect included, so a family whose
+        // connect never completes leaves no socket pending past 1 s (#1167).
+        const probeHealth = (url: string): Promise<Response> => {
+          const injected = collision.fetchImpl;
+          if (injected) return injected(url, { signal: AbortSignal.any([collisionAbort.signal, AbortSignal.timeout(1000)]) });
+          return boundedFetch(url, { deadlineMs: 1000, signal: collisionAbort.signal });
+        };
         for (const probe of [`http://127.0.0.1:${currentOrigin.port}`, `http://[::1]:${currentOrigin.port}`]) {
           try {
-            const response = await (collision.fetchImpl ?? fetch)(`${probe}${HEALTH_PATH}`, {
-              signal: AbortSignal.any([collisionAbort.signal, AbortSignal.timeout(1000)]),
-            });
+            const response = await probeHealth(`${probe}${HEALTH_PATH}`);
             if (attachmentClosed) return;
             const isUnavailable = response.status !== 200;
             if (isUnavailable) continue;