@pyric/cli 0.1.0-alpha.19 → 0.1.0-alpha.21

package/dist/next/runtime-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-env.js","sourceRoot":"","sources":["../../src/next/runtime-env.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAEvE,MAAM,UAAU,iBAAiB,CAAC,MAAwB,EAAE,OAA0B;IACpF,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAC/D,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,aAAa,GAAqB,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAClE,MAAM,WAAW,GAAG,aAAa,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChG,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5D,WAAW,CAAC,kBAAkB,GAAG,SAAS,CAAC;IAC3C,aAAa,CAAC,GAAG,GAAG,WAAW,CAAC;IAChC,OAAO,aAAa,CAAC;AACvB,CAAC"}
+{"version":3,"file":"runtime-env.js","sourceRoot":"","sources":["../../src/next/runtime-env.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAEvE,MAAM,UAAU,iBAAiB,CAAC,MAAwB,EAAE,OAA0B;IACpF,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAC/D,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,aAAa,GAAqB,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAClE,MAAM,WAAW,GAAG,aAAa,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChG,MAAM,SAAS,GAAG,oBAAoB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5D,8EAA8E;IAC9E,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,WAAW,CAAC,8BAA8B,GAAG,SAAS,CAAC;IACvD,WAAW,CAAC,kBAAkB,GAAG,SAAS,CAAC;IAC3C,aAAa,CAAC,GAAG,GAAG,WAAW,CAAC;IAChC,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/next/with-pyric.d.ts

@@ -5,7 +5,7 @@ import type { NextConfig, PyricNextOptions } from './types.js';
 /**
  * Higher-order configuration wrapper for Next.js (`next.config.js` or `next.config.mjs`).
  *
- * During development mode (`pyric dev` or non-production NODE_ENV):
+ * During development mode (`pyric sandbox` or non-production NODE_ENV):
  *   - Applies Webpack and Turbopack alias mappings to swap `firebase/*` imports
  *     for Pyric local sandbox mirrors on client components.
  *   - Adds `firebase` and `firebase-admin` to `serverExternalPackages` to prevent

package/dist/next/with-pyric.js

@@ -18,7 +18,7 @@ function applyPyricEnhancements(config, options) {
 /**
  * Higher-order configuration wrapper for Next.js (`next.config.js` or `next.config.mjs`).
  *
- * During development mode (`pyric dev` or non-production NODE_ENV):
+ * During development mode (`pyric sandbox` or non-production NODE_ENV):
  *   - Applies Webpack and Turbopack alias mappings to swap `firebase/*` imports
  *     for Pyric local sandbox mirrors on client components.
  *   - Adds `firebase` and `firebase-admin` to `serverExternalPackages` to prevent

package/dist/register/beacon.d.ts

@@ -0,0 +1,69 @@
+import type { GuardMode } from './net-guard.js';
+/** The dev server route that receives beacons (`serve/beacon-route.ts`). */
+export declare const BEACON_PATH = "/__pyric/beacon";
+/** Header carrying the per-launch secret from `PYRIC_BEACON_TOKEN`. The route
+ *  rejects a beacon that does not present it. */
+export declare const BEACON_TOKEN_HEADER = "x-pyric-beacon-token";
+/** What one activated child asserts about itself. Wire shape of the POST body
+ *  and the fields of the stderr line, kept identical on purpose. */
+export interface BeaconReport {
+    /** The child's own pid, the only durable handle a parent has on it. */
+    readonly pid: number;
+    /** Net-guard mode actually in force in this process. */
+    readonly guard: GuardMode;
+    /** Whether module resolution hooks were installed. `false` means imports
+     *  are NOT being rewritten, which is the whole thing worth knowing. */
+    readonly hooks: boolean;
+    /** The activator verbatim, so the parent can attribute the beacon. */
+    readonly sandbox: string;
+}
+export interface BeaconHooks {
+    readonly write?: (line: string) => void;
+    /** Delivery seam for the machine channel. Defaults to
+     *  {@link sendBeaconRequest}. */
+    readonly send?: (endpoint: string, body: string, token: string) => void;
+    /** Environment read for the beacon secret and the stderr gate. Defaults to
+     *  `process.env`. */
+    readonly env?: Record<string, string | undefined>;
+}
+/**
+ * POST one beacon body, fire and forget, over an unref'd socket. See the
+ * module header for why this is `node:http` and not `fetch`.
+ *
+ * `token` is the per-launch secret from `PYRIC_BEACON_TOKEN`; the route
+ * rejects a beacon without it.
+ */
+export declare function sendBeaconRequest(endpoint: string, body: string, token: string): void;
+/**
+ * The beacon endpoint implied by an activator value, or `null` when none is.
+ * Accepts `remote:<url>` (what `buildChildEnv` writes) and a bare URL; any
+ * non-http(s) scheme, and anything unparseable, is `null`: an unfetchable
+ * guess is worse than an honest absence.
+ */
+export declare function beaconEndpoint(sandbox: string | undefined): string | null;
+/**
+ * One stderr line, structured the way net-guard's verdict lines are: fixed
+ * leading fields first so it is greppable (`beacon ACTIVE pid= guard= hooks=
+ * bridge=`), then the explanation.
+ */
+export declare function formatBeaconLine(report: BeaconReport, endpoint: string | null): string;
+/**
+ * Whether the stderr channel prints.
+ *
+ * Quiet by default: a healthy first run should not carry a line per launched
+ * process, and the POST already tells the dev server what happened. The line
+ * prints when the developer asked for detail (`PYRIC_GUARD` set explicitly,
+ * `PYRIC_DEBUG`, or `PYRIC_VERBOSE`), and always when the report itself is bad
+ * news, since a child whose hooks did not install may have no other way to say
+ * so.
+ */
+export declare function beaconLineIsPrinted(report: BeaconReport, env: Record<string, string | undefined>): boolean;
+/**
+ * Emit the beacon. Never throws, never returns a promise: the caller is the
+ * `--import` hot path of every pyric-launched process.
+ *
+ * The POST always goes out. The stderr line is conditional, see
+ * {@link beaconLineIsPrinted}.
+ */
+export declare function emitBeacon(report: BeaconReport, hooks?: BeaconHooks): void;
+//# sourceMappingURL=beacon.d.ts.map

package/dist/register/beacon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../../src/register/beacon.ts"],"names":[],"mappings":"AAuDA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,4EAA4E;AAC5E,eAAO,MAAM,WAAW,oBAAoB,CAAC;AAE7C;iDACiD;AACjD,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAI1D;oEACoE;AACpE,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B;2EACuE;IACvE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;qCACiC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxE;yBACqB;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACnD;AAWD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA0CrF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAczE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAYtF;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,OAAO,CAKT;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,GAAE,WAAgB,GAAG,IAAI,CAa9E"}

package/dist/register/beacon.js

@@ -0,0 +1,199 @@
+/**
+ * The handshake beacon: register's proof that interception is live in this
+ * process.
+ *
+ * `pyric sandbox` sets `PYRIC_SANDBOX` and appends `--import
+ * @pyric/cli/register` to the child's `NODE_OPTIONS`, and then assumes the
+ * rest. Every link in that chain is silently breakable by the user's own
+ * command: a `bun`/`deno` runner that never evaluates Node loader hooks, a
+ * script that overwrites `NODE_OPTIONS` wholesale, a `NODE_ENV=production`
+ * that trips the activation refusal, an intermediate process that strips the
+ * env. In every one of those cases the child comes up looking perfectly
+ * healthy while its `firebase-admin` and `firebase` imports resolve to the
+ * real SDKs and reach live Firebase.
+ *
+ * The beacon closes that gap the only honest way: the child says so itself,
+ * after the hooks and the net-guard are actually installed.
+ *
+ * Two channels, on purpose
+ * ------------------------
+ * 1. A fire-and-forget `POST <bridge>/__pyric/beacon`, whenever a bridge URL
+ *    is knowable from the child's own env. That is the machine channel: it
+ *    reaches the dev server across an arbitrary depth of intermediate
+ *    processes (npm, then next, then its worker), where stderr scraping stops
+ *    being attributable. It carries the per-launch secret from
+ *    `PYRIC_BEACON_TOKEN`, which is what the route authorizes on.
+ * 2. One structured stderr line, printed when the developer asked for detail
+ *    or when the report is bad news (see {@link beaconLineIsPrinted}). It is
+ *    the fallback for a process with no reachable server, no port, no network.
+ *
+ * Where the bridge URL comes from
+ * -------------------------------
+ * `cli/sandbox-runner.ts:buildChildEnv` sets
+ * `PYRIC_SANDBOX=remote:<serveUrl>`, so the activator is the address. Nothing
+ * else needs to be plumbed, and the beacon works for any descendant that
+ * inherited the env, not just the direct child. When the activator carries no
+ * URL (`PYRIC_SANDBOX=local`, or a hand-set value), there is no endpoint and
+ * the line says `bridge=none` rather than guessing.
+ *
+ * The POST must never be able to hurt the child
+ * ---------------------------------------------
+ * It is diagnostics. A refused connection, a 500, an unreachable host: every
+ * one of those is swallowed. `emitBeacon` is `void`, never awaited.
+ *
+ * It is sent over a raw `node:http` request, an unref'd socket under a hard
+ * one-second bound (see {@link BEACON_TIMEOUT_MS}), rather than `fetch`, whose
+ * pending promise has neither knob. A short `node seed.js` child must not sit
+ * around after finishing its work just to deliver a diagnostic. A child that
+ * exits before the beacon lands simply loses the machine channel, which is
+ * exactly why the watchdog on the other end is warn-only.
+ *
+ * The POST targets loopback, which is not in the shared Google endpoint
+ * catalog, so it passes the net-guard installed moments earlier without a
+ * verdict.
+ */
+import { createRequire } from 'node:module';
+/** The dev server route that receives beacons (`serve/beacon-route.ts`). */
+export const BEACON_PATH = '/__pyric/beacon';
+/** Header carrying the per-launch secret from `PYRIC_BEACON_TOKEN`. The route
+ *  rejects a beacon that does not present it. */
+export const BEACON_TOKEN_HEADER = 'x-pyric-beacon-token';
+const LOG_PREFIX = '@pyric/cli/register: beacon';
+/**
+ * The hard bound on how long a beacon may delay a child's exit.
+ *
+ * One second, because this is loopback: the bridge is the dev server that
+ * launched us. If it has not accepted a connection in a second it is not
+ * going to, and no diagnostic is worth more of the child's life than that.
+ */
+const BEACON_TIMEOUT_MS = 1_000;
+/**
+ * POST one beacon body, fire and forget, over an unref'd socket. See the
+ * module header for why this is `node:http` and not `fetch`.
+ *
+ * `token` is the per-launch secret from `PYRIC_BEACON_TOKEN`; the route
+ * rejects a beacon without it.
+ */
+export function sendBeaconRequest(endpoint, body, token) {
+    const require = createRequire(import.meta.url);
+    const secure = endpoint.startsWith('https:');
+    const http = require(secure ? 'node:https' : 'node:http');
+    const req = http.request(endpoint, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            'content-length': Buffer.byteLength(body),
+            [BEACON_TOKEN_HEADER]: token,
+        },
+    });
+    // The bound on how long this can delay the child's exit is the unref'd timer
+    // below, not the socket and not a request timeout. A pending connect holds
+    // the event loop open regardless of `socket.unref()`, and `req.setTimeout()`
+    // does not arm until the `connect` event, so against a blackholed loopback
+    // address a 300 ms request timeout was measured firing at 5006 ms, when the
+    // kernel reset the connection. The timer destroys the request instead: it
+    // cannot hold the loop by itself, and it always gets to run.
+    const abort = setTimeout(() => req.destroy(), BEACON_TIMEOUT_MS);
+    abort.unref?.();
+    const settle = () => clearTimeout(abort);
+    req.on('socket', (socket) => {
+        socket.unref?.();
+    });
+    // A refused/reset connection is an expected outcome, not an error the child
+    // should ever hear about.
+    req.on('error', settle);
+    req.on('close', settle);
+    req.on('response', (res) => {
+        res.resume?.();
+        settle();
+    });
+    req.end(body);
+}
+/**
+ * The beacon endpoint implied by an activator value, or `null` when none is.
+ * Accepts `remote:<url>` (what `buildChildEnv` writes) and a bare URL; any
+ * non-http(s) scheme, and anything unparseable, is `null`: an unfetchable
+ * guess is worse than an honest absence.
+ */
+export function beaconEndpoint(sandbox) {
+    if (sandbox === undefined)
+        return null;
+    const raw = sandbox.trim();
+    if (raw.length === 0)
+        return null;
+    const value = raw.startsWith('remote:') ? raw.slice('remote:'.length).trim() : raw;
+    if (value.length === 0)
+        return null;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null;
+    return `${url.origin}${BEACON_PATH}`;
+}
+/**
+ * One stderr line, structured the way net-guard's verdict lines are: fixed
+ * leading fields first so it is greppable (`beacon ACTIVE pid= guard= hooks=
+ * bridge=`), then the explanation.
+ */
+export function formatBeaconLine(report, endpoint) {
+    const head = `${LOG_PREFIX} ACTIVE pid=${report.pid} guard=${report.guard} ` +
+        `hooks=${report.hooks ? 1 : 0} bridge=${endpoint ?? 'none'}`;
+    let hooksNote;
+    if (report.hooks) {
+        hooksNote = 'firebase-admin/firebase imports in this process are rewritten to the pyric sandbox';
+    }
+    else {
+        hooksNote =
+            'module hooks did NOT install, so firebase-admin/firebase imports in this process are NOT rewritten';
+    }
+    return `${head}: ${hooksNote}, net-guard mode ${report.guard}.\n`;
+}
+/**
+ * Whether the stderr channel prints.
+ *
+ * Quiet by default: a healthy first run should not carry a line per launched
+ * process, and the POST already tells the dev server what happened. The line
+ * prints when the developer asked for detail (`PYRIC_GUARD` set explicitly,
+ * `PYRIC_DEBUG`, or `PYRIC_VERBOSE`), and always when the report itself is bad
+ * news, since a child whose hooks did not install may have no other way to say
+ * so.
+ */
+export function beaconLineIsPrinted(report, env) {
+    if (!report.hooks)
+        return true;
+    if ((env.PYRIC_GUARD ?? '').trim().length > 0)
+        return true;
+    if (env.PYRIC_DEBUG)
+        return true;
+    return Boolean(env.PYRIC_VERBOSE);
+}
+/**
+ * Emit the beacon. Never throws, never returns a promise: the caller is the
+ * `--import` hot path of every pyric-launched process.
+ *
+ * The POST always goes out. The stderr line is conditional, see
+ * {@link beaconLineIsPrinted}.
+ */
+export function emitBeacon(report, hooks = {}) {
+    const env = hooks.env ?? process.env;
+    const write = hooks.write ?? ((line) => void process.stderr.write(line));
+    const endpoint = beaconEndpoint(report.sandbox);
+    if (beaconLineIsPrinted(report, env))
+        write(formatBeaconLine(report, endpoint));
+    if (endpoint === null)
+        return;
+    const token = env.PYRIC_BEACON_TOKEN ?? '';
+    try {
+        (hooks.send ?? sendBeaconRequest)(endpoint, JSON.stringify(report), token);
+    }
+    catch {
+        // A runtime with no usable http module, or an endpoint that slipped the
+        // URL parse, loses the machine channel only.
+    }
+}
+//# sourceMappingURL=beacon.js.map

package/dist/register/beacon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.js","sourceRoot":"","sources":["../../src/register/beacon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE7C;iDACiD;AACjD,MAAM,CAAC,MAAM,mBAAmB,GAAG,sBAAsB,CAAC;AAE1D,MAAM,UAAU,GAAG,6BAA6B,CAAC;AA0BjD;;;;;;GAMG;AACH,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,IAAY,EAAE,KAAa;IAC7E,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAMvD,CAAC;IACF,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE;QACjC,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;YAClC,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;YACzC,CAAC,mBAAmB,CAAC,EAAE,KAAK;SAC7B;KACF,CAAC,CAAC;IAEH,6EAA6E;IAC7E,2EAA2E;IAC3E,6EAA6E;IAC7E,2EAA2E;IAC3E,4EAA4E;IAC5E,0EAA0E;IAC1E,6DAA6D;IAC7D,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,iBAAiB,CAAC,CAAC;IACjE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAChB,MAAM,MAAM,GAAG,GAAS,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IAE/C,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE;QACzB,MAAiC,CAAC,KAAK,EAAE,EAAE,CAAC;IAC/C,CAAC,CAAC,CAAC;IACH,4EAA4E;IAC5E,0BAA0B;IAC1B,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACxB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACxB,GAAG,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE;QACxB,GAA+B,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5C,MAAM,EAAE,CAAC;IACX,CAAC,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAA2B;IACxD,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACnF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACvE,OAAO,GAAG,GAAG,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAoB,EAAE,QAAuB;IAC5E,MAAM,IAAI,GACR,GAAG,UAAU,eAAe,MAAM,CAAC,GAAG,UAAU,MAAM,CAAC,KAAK,GAAG;QAC/D,SAAS,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,QAAQ,IAAI,MAAM,EAAE,CAAC;IAC/D,IAAI,SAAiB,CAAC;IACtB,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,SAAS,GAAG,oFAAoF,CAAC;IACnG,CAAC;SAAM,CAAC;QACN,SAAS;YACP,oGAAoG,CAAC;IACzG,CAAC;IACD,OAAO,GAAG,IAAI,KAAK,SAAS,oBAAoB,MAAM,CAAC,KAAK,KAAK,CAAC;AACpE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAoB,EACpB,GAAuC;IAEvC,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,IAAI,GAAG,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,MAAoB,EAAE,QAAqB,EAAE;IACtE,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACrC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACjF,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,mBAAmB,CAAC,MAAM,EAAE,GAAG,CAAC;QAAE,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChF,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO;IAC9B,MAAM,KAAK,GAAG,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAC;IAC3C,IAAI,CAAC;QACH,CAAC,KAAK,CAAC,IAAI,IAAI,iBAAiB,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,6CAA6C;IAC/C,CAAC;AACH,CAAC"}

package/dist/register/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/register/index.ts"],"names":[],"mappings":"AAoIA;;yEAEyE;AACzE,eAAO,IAAI,MAAM,SAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/register/index.ts"],"names":[],"mappings":"AAkMA;;yEAEyE;AACzE,eAAO,IAAI,MAAM,SAAQ,CAAC"}

package/dist/register/index.js

@@ -1,9 +1,9 @@
 /**
  * `@pyric/cli/register` — the Node substitution seam (adoption layer 2).
  *
- * Loaded via `node --import @pyric/cli/register` (which `pyric dev` injects
- * through NODE_OPTIONS), it makes the user's UNCHANGED `firebase-admin` /
- * `firebase` imports resolve to `pyric-admin` / `pyric`, every subpath 1:1,
+ * Loaded via `node --import @pyric/cli/register` (which `pyric sandbox`
+ * injects through NODE_OPTIONS), it makes the user's UNCHANGED `firebase-admin`
+ * and `firebase` imports resolve to `pyric-admin` and `pyric`, every subpath 1:1,
  * and installs the sandbox-factory global that `pyric-admin`'s ambient
  * `initializeApp()` consumes.
  *
@@ -17,6 +17,17 @@
  * `require()` and `import`. On older 22.x it falls back to
  * `module.register()` (ESM-only) with a warning that CJS require() is not
  * rewritten.
+ *
+ * On activation it also installs the NETWORK GUARD (`./net-guard.js`), which
+ * reports egress from this process to live Google/Firebase endpoints, or
+ * refuses it under `PYRIC_GUARD=block`. See that module for the policy and the
+ * `PYRIC_GUARD` and `PYRIC_GUARD_ALLOW` knobs.
+ *
+ * Finally it emits the HANDSHAKE BEACON (`./beacon.js`): a fire-and-forget
+ * `POST /__pyric/beacon` when the activator carries a bridge URL, plus a
+ * stderr line when the developer asked for detail. That is how `pyric sandbox`
+ * learns that interception actually reached this child rather than assuming
+ * it did.
  */
 import Module from 'node:module';
 import { readFileSync } from 'node:fs';
@@ -24,6 +35,8 @@ import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { mapFirebaseSpecifier } from './mapping.js';
 import { resolveEsmOnlySubpath } from './esm-exports.js';
+import { installNetGuard, parseGuardMode } from './net-guard.js';
+import { emitBeacon } from './beacon.js';
 import { remoteSandbox } from '../remote/index.js';
 /** The shared seam with pyric-admin's ambient init: a synchronous factory
  *  returning the lazy branded handle. `Symbol.for` so both packages agree
@@ -68,7 +81,28 @@ function resolveEsmOnlyForRequire(mapped) {
     }
 }
 function activate() {
+    // FIRST, before any hook or global: the network guard.
+    //
+    // Order matters in one direction only. Everything after this line makes the
+    // process load MORE code (the resolution hooks pull in the pyric mirrors,
+    // the factory global pulls in the remote sandbox) and any of it could open
+    // a socket. Installing the guard first leaves no window in which
+    // sandbox-substituted code runs unguarded. The reverse ordering buys
+    // nothing: the guard mutates globals only (`undici.globalDispatcher.1`,
+    // `net`/`tls` connect) and depends on nothing the hooks establish.
+    //
+    // It stays BELOW the NODE_ENV=production refusal, deliberately. A refused
+    // process is a real production run that we declined to touch, and warning
+    // about its perfectly legitimate Google traffic, let alone blocking it,
+    // would be actively harmful. `PYRIC_SANDBOX` plus no refusal is the only
+    // state in which "traffic to live Google is a bug" is a true statement.
+    const guard = installNetGuard();
+    // Whether module resolution is actually being intercepted. Both branches
+    // below install SOMETHING, but a runtime with neither API installs nothing,
+    // which is precisely the state the beacon exists to make visible.
+    let hooksInstalled = false;
     if (typeof moduleApi.registerHooks === 'function') {
+        hooksInstalled = true;
         moduleApi.registerHooks({
             resolve(specifier, context, nextResolve) {
                 const mapped = mapFirebaseSpecifier(specifier, context.parentURL);
@@ -94,16 +128,41 @@ function activate() {
         });
     }
     else {
-        process.stderr.write('@pyric/cli/register: this Node version lacks module.registerHooks (needs >= 22.15) — ' +
-            'falling back to module.register: ESM imports of firebase-admin/firebase are rewritten, ' +
+        process.stderr.write('@pyric/cli/register: this Node version lacks module.registerHooks (needs >= 22.15). ' +
+            'Falling back to module.register: ESM imports of firebase-admin/firebase are rewritten, ' +
             "but CJS require('firebase-admin') is NOT intercepted. Upgrade Node to >= 22.15 for full coverage.\n");
+        hooksInstalled = typeof moduleApi.register === 'function';
         moduleApi.register?.(new URL('./hooks.js', import.meta.url));
     }
     // The factory global — exact contract shared with pyric-admin's ambient
     // init: synchronous, returns the lazy branded handle.
     globalThis[SANDBOX_FACTORY] = (opts) => remoteSandbox(opts);
-    process.stderr.write(`@pyric/cli/register: active — firebase-admin/firebase imports now resolve to the ` +
+    process.stderr.write(`@pyric/cli/register: active. firebase-admin/firebase imports now resolve to the ` +
         `pyric sandbox (PYRIC_SANDBOX=${process.env.PYRIC_SANDBOX}).\n`);
+    // LAST: the handshake beacon, after the guard, the hooks and the factory
+    // global are all in place. Its whole claim is "interception is live in this
+    // process", so it must not be able to run before that is true. See
+    // `./beacon.js` for the two channels and why the POST is fire-and-forget.
+    emitBeacon({
+        pid: process.pid,
+        guard: installedGuardMode(guard),
+        hooks: hooksInstalled,
+        sandbox: process.env.PYRIC_SANDBOX ?? '',
+    });
+}
+/**
+ * The net-guard mode actually in force, for the beacon to report.
+ *
+ * Policy: the installed guard is the authority when there is one. There is no
+ * guard object in exactly one case, `PYRIC_GUARD=off` (the `PYRIC_SANDBOX`
+ * gate `installNetGuard` shares with this module has already passed by the
+ * time it runs), and re-parsing the env is how that case names itself rather
+ * than guessing a default.
+ */
+function installedGuardMode(guard) {
+    if (guard !== null)
+        return guard.mode;
+    return parseGuardMode(process.env.PYRIC_GUARD);
 }
 /** Whether this process's firebase-admin/firebase imports are being rewritten
  *  to the pyric sandbox — true only when `PYRIC_SANDBOX` was set (and not

package/dist/register/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/register/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/register/index.ts"],"names":[],"mappings":"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"}

package/dist/register/net-guard.d.ts

@@ -0,0 +1,110 @@
+/** Marks a rejection as the guard's, so callers can tell it from a DNS/TLS
+ *  failure. A blocked `fetch` only exposes it as `error.cause.code`. */
+export declare const GUARD_BLOCKED_CODE = "PYRIC_GUARD_BLOCKED";
+export type GuardMode = 'warn' | 'block' | 'off';
+/** What the guard decided about one outbound connection. */
+export interface EgressVerdict {
+    /** `warn` reported-and-permitted, `block` refused, `allow` allowlisted. */
+    readonly verdict: 'warn' | 'block' | 'allow';
+    /** Whether the connection may proceed. */
+    readonly permitted: boolean;
+    /**
+     * The hostname actually being contacted, which is what the developer needs
+     * in order to find the call. Not the catalog suffix: `cloudfunctions.net`
+     * does not tell you which region or project a callable went to.
+     */
+    readonly host: string;
+    /** The catalog suffix that matched (`host` when the match was exact). */
+    readonly endpoint: string;
+    /** Human service label, verbatim from the shared catalog. */
+    readonly service: string;
+    /** Present only for catalog entries that can never be a false positive. */
+    readonly alwaysBlock?: true;
+}
+/** `PYRIC_GUARD` → mode. Unset, empty or unrecognised all mean the safe
+ *  default: report, do not break the developer's app. */
+export declare function parseGuardMode(raw: string | undefined): GuardMode;
+/** `PYRIC_GUARD_ALLOW` → hostnames. Accepts bare hosts and full URLs, because
+ *  the values it carries are configured as URLs (AI engine baseUrls). */
+export declare function parseAllowHosts(raw: string | undefined): string[];
+/**
+ * The whole verdict, pure: catalog lookup, then `alwaysBlock`, then the
+ * allowlist, then the mode. `null` means nothing to say: either not a
+ * production endpoint, or the guard is off.
+ */
+export declare function evaluateEgress(hostname: string, policy: {
+    mode: GuardMode;
+    allow: readonly string[];
+}): EgressVerdict | null;
+/** One stderr line per verdict: structured (fixed leading fields, so it is
+ *  greppable) and attributable (service + transport + initiating command).
+ *  The request PATH is deliberately never logged: it carries ids and tokens. */
+export declare function formatGuardLine(verdict: EgressVerdict, transport: 'fetch' | 'socket', context: string | undefined): string;
+export interface ReporterOptions {
+    readonly mode: GuardMode;
+    readonly allow: readonly string[];
+    readonly write?: (line: string) => void;
+    /** Initiating command, for attribution. Usually `basename(argv[1])`. */
+    readonly context?: string;
+    /**
+     * The shared "already reported" ledger. `installNetGuard` hands the SAME set
+     * to the dispatcher wrapper and the socket backstop, because undici connects
+     * through `net.connect`: a warn-mode fetch trips both seams and would
+     * otherwise print the same host twice. It also survives a re-assert, so
+     * being re-wrapped does not restart the noise.
+     */
+    readonly reported?: Set<string>;
+}
+interface Dispatcher {
+    dispatch(opts: unknown, handler: unknown): unknown;
+}
+/**
+ * Wrap a dispatcher so `dispatch` is guarded and every other member still
+ * belongs to the real instance.
+ *
+ * A `Proxy` rather than a subclass or a copy: undici's Agent keeps state in
+ * private fields and internal symbols, and every forwarded call must run with
+ * `this` bound to the REAL instance (hence `Reflect.get(target, prop, target)`
+ * and the bind) or those fields are not there. `instanceof` keeps working.
+ */
+export declare function wrapDispatcher<T extends Dispatcher>(real: T, options: ReporterOptions): T;
+type ConnectFn = (...args: unknown[]) => unknown;
+/** A `createConnection`-bearing object: an `http.Agent`/`https.Agent`
+ *  prototype in production, a stand-in under test. */
+type AgentPrototype = {
+    createConnection?: unknown;
+};
+export interface NetGuardHooks {
+    /** Object carrying the undici dispatcher symbol. Defaults to `globalThis`. */
+    scope?: Record<symbol, unknown>;
+    env?: Record<string, string | undefined>;
+    argv?: readonly string[];
+    write?: (line: string) => void;
+    net?: {
+        connect: ConnectFn;
+        createConnection: ConnectFn;
+    };
+    tls?: {
+        connect: ConnectFn;
+    };
+    /** Prototypes whose `createConnection` is patched. Defaults to the
+     *  `http.Agent` and `https.Agent` prototypes. */
+    agentPrototypes?: readonly AgentPrototype[];
+}
+export interface NetGuard {
+    readonly mode: GuardMode;
+    readonly allow: readonly string[];
+    /** Re-wrap the global dispatcher if something replaced it (a future Next
+     *  calling `setGlobalDispatcher` would otherwise silently unhook us). */
+    reassert(): void;
+    /** Stop the periodic re-assert. Used by the CLI's own tests. */
+    stop(): void;
+}
+/**
+ * Install the guard. Gated on `PYRIC_SANDBOX` exactly like the rest of the
+ * register module: without the activator this is a no-op, so the module stays
+ * safe to import anywhere. Returns `null` when nothing was installed.
+ */
+export declare function installNetGuard(hooks?: NetGuardHooks): NetGuard | null;
+export {};
+//# sourceMappingURL=net-guard.d.ts.map

package/dist/register/net-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-guard.d.ts","sourceRoot":"","sources":["../../src/register/net-guard.ts"],"names":[],"mappings":"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"}