@expo/build-tools 24.2.0 → 24.4.0

package/dist/steps/utils/localEgressGuard.js

@@ -0,0 +1,537 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardLogTailer = exports.GuardEventRelay = exports.LOCAL_EGRESS_GUARD_LOG_PATH = exports.EGRESS_GUARD_MODE_ENV = exports.EGRESS_GUARD_LOG_ENV = exports.EGRESS_GUARD_CHECK_FILE = exports.EGRESS_GUARD_LIBRARY_FILE = void 0;
+exports.buildGuardLaunchdEnvironment = buildGuardLaunchdEnvironment;
+exports.parseGuardLogLine = parseGuardLogLine;
+exports.resolveEgressGuardLibraryAsync = resolveEgressGuardLibraryAsync;
+exports.resolveEgressGuardCheckAsync = resolveEgressGuardCheckAsync;
+exports.resolveLocalEgressBootEnvironmentAsync = resolveLocalEgressBootEnvironmentAsync;
+exports.installLocalEgressGuardAsync = installLocalEgressGuardAsync;
+exports.parseGuardCoverage = parseGuardCoverage;
+exports.mergeGuardCoverageSamples = mergeGuardCoverageSamples;
+exports.reportLocalEgressGuardCoverageAsync = reportLocalEgressGuardCoverageAsync;
+exports.verifyLocalEgressGuardAsync = verifyLocalEgressGuardAsync;
+exports.rebindLocalEgressGuardRelays = rebindLocalEgressGuardRelays;
+exports.stopLocalEgressGuardRelaysAsync = stopLocalEgressGuardRelaysAsync;
+const eas_build_job_1 = require("@expo/eas-build-job");
+const turtle_spawn_1 = __importDefault(require("@expo/turtle-spawn"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const IosSimulatorUtils_1 = require("../../utils/IosSimulatorUtils");
+const localEgress_1 = require("./localEgress");
+/**
+ * Worker side of the local egress guard: a dylib injected into every process
+ * the simulator launches, which refuses connections that do not go to
+ * loopback (where the proxy and the `--egress-allow` forwards live) and
+ * records one event per destination per process. This module installs it
+ * through the simulator's launchd environment and relays its events into the
+ * session log. See resources/egress-guard/README.md.
+ */
+exports.EGRESS_GUARD_LIBRARY_FILE = 'egress-guard.dylib';
+exports.EGRESS_GUARD_CHECK_FILE = 'egress-guard-check';
+exports.EGRESS_GUARD_LOG_ENV = 'EAS_EGRESS_GUARD_LOG';
+exports.EGRESS_GUARD_MODE_ENV = 'EAS_EGRESS_GUARD_MODE';
+exports.LOCAL_EGRESS_GUARD_LOG_PATH = node_path_1.default.join(node_os_1.default.tmpdir(), 'eas-local-egress-guard.log');
+const GUARD_EVENT_PREFIX = 'eas-egress-guard';
+/** Written once by a process whose per-process table of destinations is full; see policy.h. */
+const GUARD_OVERFLOW_FUNCTION = 'overflow';
+const GUARD_RELAY_LOG_LIMIT = 200;
+const GUARD_TAIL_INTERVAL_MS = 1_000;
+function buildGuardLaunchdEnvironment({ libraryPath, logPath, mode, }) {
+    return {
+        DYLD_INSERT_LIBRARIES: libraryPath,
+        [exports.EGRESS_GUARD_LOG_ENV]: logPath,
+        [exports.EGRESS_GUARD_MODE_ENV]: mode,
+    };
+}
+/** One tab-separated line written by the guard; see policy.h for the format. */
+function parseGuardLogLine(line) {
+    const fields = line.split('\t');
+    if (fields.length < 7 || fields[0] !== GUARD_EVENT_PREFIX) {
+        return null;
+    }
+    const [, process, pidText, fn, action, peer, callerText] = fields;
+    const pid = Number(pidText);
+    if (!Number.isInteger(pid) || (action !== 'blocked' && action !== 'logged') || !fn || !peer) {
+        return null;
+    }
+    return {
+        process,
+        pid,
+        function: fn,
+        action,
+        peer,
+        callers: callerText ? callerText.split(',').filter(Boolean) : [],
+    };
+}
+const PACKAGED_BIN_DIR = node_path_1.default.join(__dirname, '..', '..', '..', 'bin');
+async function resolvePackagedFileAsync(binDir, file) {
+    const filePath = node_path_1.default.join(binDir, file);
+    try {
+        await node_fs_1.default.promises.access(filePath);
+        return filePath;
+    }
+    catch {
+        return null;
+    }
+}
+/** The packaged library, next to the compiled package like record-sim. */
+async function resolveEgressGuardLibraryAsync(binDir = PACKAGED_BIN_DIR) {
+    return await resolvePackagedFileAsync(binDir, exports.EGRESS_GUARD_LIBRARY_FILE);
+}
+/** The packaged self-check binary, built alongside the library. */
+async function resolveEgressGuardCheckAsync(binDir = PACKAGED_BIN_DIR) {
+    return await resolvePackagedFileAsync(binDir, exports.EGRESS_GUARD_CHECK_FILE);
+}
+/**
+ * Turns guard events into session log lines: one line the first time a
+ * process reaches a destination through a given call, counts after that, and
+ * a summary at the end.
+ */
+class GuardEventRelay {
+    limit;
+    seen = new Set();
+    peers = new Set();
+    processes = new Set();
+    blocked = 0;
+    logged = 0;
+    suppressed = 0;
+    logger;
+    constructor(logger, limit = GUARD_RELAY_LOG_LIMIT) {
+        this.limit = limit;
+        this.logger = logger;
+    }
+    /**
+     * Log through a different step's logger from now on. Refusals happen for
+     * the life of the session, so they belong to the step that runs the
+     * session, not the one that booted the simulator minutes earlier.
+     */
+    setLogger(logger) {
+        this.logger = logger;
+    }
+    handle(event) {
+        if (event.process === exports.EGRESS_GUARD_CHECK_FILE) {
+            // The self-check deliberately trips the guard once; not a bypass.
+            return;
+        }
+        if (event.function === GUARD_OVERFLOW_FUNCTION) {
+            const verb = event.action === 'blocked' ? 'refused' : 'observed';
+            this.logger.info(`Local egress guard: ${event.process} (pid ${event.pid}) reached the limit of ${event.peer} listed per process; further distinct destinations from it are ${verb} but not listed.`);
+            return;
+        }
+        if (event.action === 'blocked') {
+            this.blocked++;
+        }
+        else {
+            this.logged++;
+        }
+        this.peers.add(event.peer);
+        this.processes.add(event.process);
+        const key = `${event.process}|${event.function}|${event.peer}`;
+        if (this.seen.has(key)) {
+            return;
+        }
+        this.seen.add(key);
+        if (this.seen.size > this.limit) {
+            this.suppressed++;
+            return;
+        }
+        const verb = event.action === 'blocked' ? 'refused' : 'observed';
+        const callers = event.callers.length ? `; callers: ${event.callers.join(', ')}` : '';
+        this.logger.info(`Local egress guard: ${verb} ${event.function} from ${event.process} (pid ${event.pid}) to ${event.peer}${callers}`);
+    }
+    summary() {
+        return {
+            blocked: this.blocked,
+            logged: this.logged,
+            distinct: this.peers.size,
+            suppressed: this.suppressed,
+        };
+    }
+    logSummary() {
+        const { blocked, logged, distinct, suppressed } = this.summary();
+        const observed = logged ? ` and observed ${logged} more without refusing` : '';
+        const dropped = suppressed
+            ? ` ${suppressed} further distinct destination(s) were not logged individually.`
+            : '';
+        this.logger.info(`Local egress guard: refused ${blocked} connection attempt(s) to ${distinct} distinct destination(s) from ${this.processes.size} process(es)${observed}.${dropped}`);
+    }
+}
+exports.GuardEventRelay = GuardEventRelay;
+/**
+ * Polls a file the simulator processes append to and delivers whole lines.
+ * Tolerates the file not existing yet, partial trailing lines, and truncation.
+ */
+class GuardLogTailer {
+    path;
+    onLine;
+    intervalMs;
+    offset = 0;
+    partial = '';
+    timer;
+    reading = Promise.resolve();
+    constructor({ path: filePath, onLine, intervalMs = GUARD_TAIL_INTERVAL_MS, }) {
+        this.path = filePath;
+        this.onLine = onLine;
+        this.intervalMs = intervalMs;
+    }
+    start() {
+        this.timer = setInterval(() => {
+            this.reading = this.reading.then(() => this.readAsync()).catch(() => { });
+        }, this.intervalMs);
+        this.timer.unref();
+    }
+    async stopAsync() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        await this.reading.catch(() => { });
+        await this.readAsync().catch(() => { });
+    }
+    async readAsync() {
+        let handle;
+        try {
+            handle = await node_fs_1.default.promises.open(this.path, 'r');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return;
+            }
+            throw err;
+        }
+        try {
+            const { size } = await handle.stat();
+            if (size < this.offset) {
+                // Truncated or replaced; start over.
+                this.offset = 0;
+                this.partial = '';
+            }
+            if (size === this.offset) {
+                return;
+            }
+            const buffer = new Uint8Array(size - this.offset);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, this.offset);
+            this.offset += bytesRead;
+            const text = this.partial + Buffer.from(buffer.buffer, 0, bytesRead).toString('utf8');
+            const lines = text.split('\n');
+            this.partial = lines.pop() ?? '';
+            for (const line of lines) {
+                if (line.length > 0) {
+                    this.onLine(line);
+                }
+            }
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+exports.GuardLogTailer = GuardLogTailer;
+/**
+ * The environment the simulator's launchd must have from its first process:
+ * the guard and the proxy variables. Pass it to `IosSimulatorUtils.bootAsync`,
+ * which hands it to launchd before anything is spawned; `launchctl setenv`
+ * after boot only reaches later processes. Returns null when no local egress
+ * session is active. Throws when the guard library is not packaged, since a
+ * local egress session without it would silently leak.
+ */
+async function resolveLocalEgressBootEnvironmentAsync({ handoffPath = localEgress_1.LOCAL_EGRESS_HANDOFF_PATH, libraryPath, logPath = exports.LOCAL_EGRESS_GUARD_LOG_PATH, mode = 'block', } = {}) {
+    const handoff = await (0, localEgress_1.readLocalEgressHandoffAsync)(handoffPath);
+    if (!handoff) {
+        return null;
+    }
+    const resolvedLibrary = libraryPath === undefined ? await resolveEgressGuardLibraryAsync() : libraryPath;
+    if (!resolvedLibrary) {
+        throw new eas_build_job_1.SystemError('The local egress guard library is not available on this device host, so this local egress session ' +
+            'cannot guarantee that connections bypassing the system proxy are refused. The device host image is ' +
+            'missing bin/egress-guard.dylib; this is a service problem, please contact support.');
+    }
+    return {
+        ...buildGuardLaunchdEnvironment({ libraryPath: resolvedLibrary, logPath, mode }),
+        ...(0, localEgress_1.buildLocalEgressSimulatorEnvironment)(handoff.port),
+    };
+}
+const activeRelays = new Map();
+/**
+ * Install the guard into a simulator when a local egress session is active,
+ * and start relaying its events into the session log. Returns false when
+ * there is no local egress session. Throws when the library is not packaged
+ * or launchd could not be configured: a local egress session without the
+ * guard would silently leak, so it must not start. Only an unwritable event
+ * log is a warning, since refusals still happen and only reporting is lost.
+ *
+ * Call this as soon as `simctl boot` returns: launchd is up and nothing else
+ * has started, so every process the boot spawns inherits the guard. Verify
+ * with `verifyLocalEgressGuardAsync` once boot completes.
+ */
+async function installLocalEgressGuardAsync({ udid, env, logger, handoffPath = localEgress_1.LOCAL_EGRESS_HANDOFF_PATH, libraryPath, logPath = exports.LOCAL_EGRESS_GUARD_LOG_PATH, mode = 'block', tailIntervalMs, }) {
+    let handoff;
+    try {
+        handoff = await (0, localEgress_1.readLocalEgressHandoffAsync)(handoffPath);
+    }
+    catch (err) {
+        logger.warn({ err }, 'Local egress guard: could not read the local egress handoff, so the guard was not installed. ' +
+            'Connections that bypass the proxy will exit from this worker.');
+        return false;
+    }
+    if (!handoff) {
+        return false;
+    }
+    const resolvedLibrary = libraryPath === undefined ? await resolveEgressGuardLibraryAsync() : libraryPath;
+    if (!resolvedLibrary) {
+        throw new eas_build_job_1.SystemError('The local egress guard library is not available on this device host, so this local egress session ' +
+            'cannot guarantee that connections bypassing the system proxy are refused. The device host image is ' +
+            'missing bin/egress-guard.dylib; this is a service problem, please contact support.');
+    }
+    await logAlreadyRunningProcessesAsync({ env, logger });
+    let logWritable = true;
+    try {
+        await node_fs_1.default.promises.mkdir(node_path_1.default.dirname(logPath), { recursive: true });
+        await node_fs_1.default.promises.appendFile(logPath, '');
+    }
+    catch (err) {
+        logWritable = false;
+        logger.warn({ err }, `Local egress guard: could not create ${logPath}, so refused connections will not be reported in this log. They are still refused.`);
+    }
+    try {
+        await IosSimulatorUtils_1.IosSimulatorUtils.setLaunchdEnvironmentAsync({
+            udid,
+            env,
+            variables: buildGuardLaunchdEnvironment({ libraryPath: resolvedLibrary, logPath, mode }),
+        });
+    }
+    catch (err) {
+        throw new eas_build_job_1.SystemError('Could not install the local egress guard in the Simulator (launchctl setenv failed), so this local ' +
+            'egress session cannot guarantee that connections bypassing the system proxy are refused. Retry the ' +
+            'session; if it keeps failing, please contact support.', { cause: err });
+    }
+    if (logWritable && !activeRelays.has(logPath)) {
+        const relay = new GuardEventRelay(logger);
+        const tailer = new GuardLogTailer({
+            path: logPath,
+            intervalMs: tailIntervalMs,
+            onLine: line => {
+                const event = parseGuardLogLine(line);
+                if (event) {
+                    relay.handle(event);
+                }
+            },
+        });
+        tailer.start();
+        activeRelays.set(logPath, { tailer, relay });
+    }
+    logger.info(`Local egress guard installed in the Simulator (mode ${mode}): connections that bypass the system proxy are ${mode === 'block' ? 'refused' : 'observed'} in the process that makes them and reported here as they happen.`);
+    return true;
+}
+/**
+ * Processes the simulator already runs when the guard is installed never get
+ * it. Right after `simctl boot` that is nothing; later it is SpringBoard and
+ * the early daemons, which follow the system proxy anyway. Log them so the
+ * uncovered set is visible rather than assumed.
+ */
+async function logAlreadyRunningProcessesAsync({ env, logger, }) {
+    let psOutput = '';
+    try {
+        psOutput = (await (0, turtle_spawn_1.default)('ps', ['-axo', 'pid=,ppid=,comm='], { env, stdio: 'pipe' })).stdout;
+    }
+    catch {
+        return;
+    }
+    const pids = new Set((0, localEgress_1.collectSimulatorProcessIds)(psOutput));
+    const names = new Set();
+    for (const line of psOutput.split('\n')) {
+        const match = /^\s*(\d+)\s+\d+\s+(\S.*)$/.exec(line);
+        if (match && pids.has(Number(match[1]))) {
+            names.add(node_path_1.default.basename(match[2].trim()));
+        }
+    }
+    if (names.size === 0) {
+        logger.info('Local egress guard: no simulator process was running before the guard was installed.');
+        return;
+    }
+    const listed = [...names].sort();
+    const shown = listed.slice(0, 20).join(', ') + (listed.length > 20 ? `, and ${listed.length - 20} more` : '');
+    logger.info(`Local egress guard: ${names.size} simulator process(es) were already running before the guard was installed and are not covered by it: ${shown}.`);
+}
+/**
+ * launchd's trampoline exists for milliseconds between fork and exec of the
+ * real service, with nothing mapped yet; it never makes a connection itself.
+ */
+const COVERAGE_IGNORED_PROCESSES = new Set(['xpcproxy_sim']);
+/**
+ * Which simulator processes have the guard library mapped, from
+ * `ps -axo pid=,ppid=,comm=` and `lsof -nP -a -p <pids> -d txt -F pn` output.
+ * A process is covered when any of its mapped images is the guard library.
+ */
+function parseGuardCoverage(psOutput, lsofOutput) {
+    const simulatorPids = new Set((0, localEgress_1.collectSimulatorProcessIds)(psOutput));
+    const commandsByPid = new Map();
+    for (const line of psOutput.split('\n')) {
+        const match = /^\s*(\d+)\s+\d+\s+(\S.*)$/.exec(line);
+        if (match) {
+            commandsByPid.set(Number(match[1]), node_path_1.default.basename(match[2].trim()));
+        }
+    }
+    const loaded = new Set();
+    let pid = null;
+    for (const line of lsofOutput.split('\n')) {
+        if (line[0] === 'p') {
+            pid = Number(line.slice(1));
+        }
+        else if (line[0] === 'n' && pid !== null && line.endsWith(exports.EGRESS_GUARD_LIBRARY_FILE)) {
+            loaded.add(pid);
+        }
+    }
+    const covered = [];
+    const uncovered = [];
+    const uncoveredPids = [];
+    for (const simulatorPid of simulatorPids) {
+        const name = commandsByPid.get(simulatorPid) ?? String(simulatorPid);
+        if (COVERAGE_IGNORED_PROCESSES.has(name)) {
+            continue;
+        }
+        if (loaded.has(simulatorPid)) {
+            covered.push(name);
+        }
+        else {
+            uncovered.push(name);
+            uncoveredPids.push(simulatorPid);
+        }
+    }
+    covered.sort();
+    uncovered.sort();
+    return { covered, uncovered, uncoveredPids };
+}
+/**
+ * A process caught between fork and exec has nothing mapped yet and looks
+ * uncovered for an instant. Two samples a moment apart separate those from
+ * processes that really run without the guard: only pids uncovered in both
+ * count, reported with the later sample's names.
+ */
+function mergeGuardCoverageSamples(first, second) {
+    const persistent = new Set(first.uncoveredPids.filter(pid => second.uncoveredPids.includes(pid)));
+    const uncovered = [];
+    const uncoveredPids = [];
+    second.uncoveredPids.forEach((pid, index) => {
+        if (persistent.has(pid)) {
+            uncovered.push(second.uncovered[index]);
+            uncoveredPids.push(pid);
+        }
+    });
+    return { covered: second.covered, uncovered, uncoveredPids };
+}
+/**
+ * Measure and log guard coverage across the simulator's processes. Observation
+ * only: the uncovered set is whatever started before the guard was installed,
+ * which is nothing when installation runs right after `simctl boot`.
+ */
+async function reportLocalEgressGuardCoverageAsync({ env, logger, sampleIntervalMs = 1_000, }) {
+    const first = await sampleGuardCoverageAsync({ env });
+    if (!first) {
+        return null;
+    }
+    await new Promise(resolve => setTimeout(resolve, sampleIntervalMs));
+    const second = await sampleGuardCoverageAsync({ env });
+    const coverage = second ? mergeGuardCoverageSamples(first, second) : first;
+    const total = coverage.covered.length + coverage.uncovered.length;
+    if (coverage.uncovered.length === 0) {
+        logger.info(`Local egress guard coverage: all ${total} simulator process(es) have the guard loaded.`);
+    }
+    else {
+        const shown = coverage.uncovered.slice(0, 20).join(', ') +
+            (coverage.uncovered.length > 20 ? `, and ${coverage.uncovered.length - 20} more` : '');
+        logger.info(`Local egress guard coverage: ${coverage.covered.length} of ${total} simulator process(es) have the guard loaded. Not covered, started before the guard was installed: ${shown}.`);
+    }
+    return coverage;
+}
+async function sampleGuardCoverageAsync({ env, }) {
+    let psOutput;
+    try {
+        psOutput = (await (0, turtle_spawn_1.default)('ps', ['-axo', 'pid=,ppid=,comm='], { env, stdio: 'pipe' })).stdout;
+    }
+    catch {
+        return null;
+    }
+    const pids = (0, localEgress_1.collectSimulatorProcessIds)(psOutput);
+    if (pids.length === 0) {
+        return null;
+    }
+    let lsofOutput;
+    try {
+        lsofOutput = (await (0, turtle_spawn_1.default)('lsof', ['-nP', '-a', '-p', pids.join(','), '-d', 'txt', '-F', 'pn'], {
+            env,
+            stdio: 'pipe',
+        })).stdout;
+    }
+    catch (err) {
+        // lsof exits 1 when some listed pid has already exited; stdout is still valid.
+        const result = err;
+        if (result.status !== 1) {
+            return null;
+        }
+        lsofOutput = result.stdout ?? '';
+    }
+    return parseGuardCoverage(psOutput, lsofOutput);
+}
+/**
+ * Run the packaged self-check inside the simulator: it must find the guard
+ * loaded in a fresh process and see it behave as `mode` says. Throws when the
+ * check binary is missing or the check fails, which fails the session.
+ */
+async function verifyLocalEgressGuardAsync({ udid, env, logger, mode = 'block', checkPath, }) {
+    const resolvedCheck = checkPath === undefined ? await resolveEgressGuardCheckAsync() : checkPath;
+    if (!resolvedCheck) {
+        throw new eas_build_job_1.SystemError('The local egress guard self-check is not available on this device host, so this session cannot ' +
+            'verify that the guard is in effect. The device host image is missing bin/egress-guard-check; ' +
+            'this is a service problem, please contact support.');
+    }
+    let output;
+    try {
+        const result = await (0, turtle_spawn_1.default)('xcrun', ['simctl', 'spawn', udid, resolvedCheck, '--mode', mode], {
+            env,
+            stdio: 'pipe',
+        });
+        output = result.stdout.trim();
+    }
+    catch (err) {
+        const failed = err;
+        const detail = [failed.stdout, failed.stderr].filter(Boolean).join('\n').trim();
+        throw new eas_build_job_1.SystemError('The local egress guard is not in effect in the Simulator: the self-check run right after boot ' +
+            `failed${failed.status != null ? ` (exit ${failed.status})` : ''}. Connections that bypass the ` +
+            'system proxy would leave from the device host, so the session was stopped. Retry the session; if it ' +
+            `keeps failing, please contact support.${detail ? ` Self-check output: ${detail}` : ''}`, { cause: err });
+    }
+    logger.info(`Local egress guard verified in the Simulator: ${output || 'self-check passed'}.`);
+    await reportLocalEgressGuardCoverageAsync({ env, logger });
+}
+/**
+ * Attribute guard events to the step that runs the session from now on. The
+ * relay starts under the simulator boot step's logger; once the session step
+ * takes over, its lines should appear under that step in the job log, next
+ * to the rest of the session's output, rather than under a step that already
+ * finished.
+ */
+function rebindLocalEgressGuardRelays(logger) {
+    for (const { relay } of activeRelays.values()) {
+        relay.setLogger(logger);
+    }
+}
+/** Stop relaying and write each relay's summary; called from the session cleanup. */
+async function stopLocalEgressGuardRelaysAsync(logger) {
+    const relays = [...activeRelays.values()];
+    activeRelays.clear();
+    for (const { tailer, relay } of relays) {
+        try {
+            await tailer.stopAsync();
+        }
+        catch (err) {
+            logger.warn({ err }, 'Local egress guard: could not read the last events from the guard log.');
+        }
+        relay.logSummary();
+    }
+}

package/dist/steps/utils/localEgressSession.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.withLocalEgressSession = withLocalEgressSession;
 exports.uploadRemoteSessionConfigWithLocalEgressAsync = uploadRemoteSessionConfigWithLocalEgressAsync;
 const localEgress_1 = require("./localEgress");
+const localEgressGuard_1 = require("./localEgressGuard");
 const remoteDeviceRunSession_1 = require("./remoteDeviceRunSession");
 /** Release the pre-boot egress resources even if controller startup or teardown fails. */
 function withLocalEgressSession(fn) {
@@ -26,6 +27,9 @@ async function uploadRemoteSessionConfigWithLocalEgressAsync({ env, signal, ...o
         remoteConfig: { ...options.remoteConfig, ...(0, localEgress_1.buildEgressRemoteConfigFields)(localEgress) },
     });
     if (localEgress && !signal?.aborted) {
+        // Guard refusals from here on show up under this step in the job log,
+        // alongside the monitor's reports, instead of under the boot step.
+        (0, localEgressGuard_1.rebindLocalEgressGuardRelays)(options.logger);
         options.logger.info('Local egress: waiting for the EAS CLI egress client to connect. Proxied HTTP(S) ' +
             'requests are unavailable until it does.');
         // The monitor also observes the registered resources' lifetime signal, which

package/dist/steps/utils/sandboxDaemon.d.ts

@@ -0,0 +1,13 @@
+import { type bunyan } from '@expo/logger';
+export interface SandboxDaemonOptions {
+    credential: string;
+    serverUrl: string;
+    reconnectDelayMs: number;
+    logger: bunyan;
+    signal?: AbortSignal;
+}
+export interface SandboxDaemon {
+    ready: Promise<void>;
+    stopAsync(): Promise<void>;
+}
+export declare function startSandboxDaemonAsync(options: SandboxDaemonOptions): Promise<SandboxDaemon>;

package/dist/steps/utils/sandboxDaemon.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startSandboxDaemonAsync = startSandboxDaemonAsync;
+const eas_build_job_1 = require("@expo/eas-build-job");
+const promises_1 = require("node:timers/promises");
+const ws_1 = __importDefault(require("ws"));
+async function startSandboxDaemonAsync(options) {
+    options.signal?.throwIfAborted();
+    let socket;
+    const abortController = new AbortController();
+    let hasConnected = false;
+    let resolveConnected;
+    let rejectConnected;
+    const connected = new Promise((resolve, reject) => {
+        resolveConnected = resolve;
+        rejectConnected = reject;
+    });
+    const stop = () => {
+        abortController.abort();
+        socket?.close(1000, 'sandbox stopped');
+    };
+    options.signal?.addEventListener('abort', stop, { once: true });
+    const connectionLoop = (async () => {
+        while (!abortController.signal.aborted) {
+            try {
+                socket = new ws_1.default(new URL('/sandbox/connect', options.serverUrl), {
+                    handshakeTimeout: 10_000,
+                    headers: { Authorization: `Bearer ${options.credential}` },
+                });
+                await waitForOpen(socket);
+                options.logger.info('Sandbox MCP server connected.');
+                hasConnected = true;
+                resolveConnected();
+                await waitForClose(socket);
+            }
+            catch (error) {
+                if (!hasConnected) {
+                    const message = `Sandbox MCP server connection failed: ${error?.message ?? 'unknown error'}`;
+                    if (!abortController.signal.aborted) {
+                        options.logger.error({ err: error }, message);
+                    }
+                    rejectConnected(new eas_build_job_1.SystemError(message, { cause: error }));
+                    return;
+                }
+                if (!abortController.signal.aborted) {
+                    options.logger.warn({ err: error }, `Sandbox MCP server connection failed: ${error?.message ?? 'unknown error'}`);
+                }
+            }
+            if (!abortController.signal.aborted) {
+                try {
+                    await (0, promises_1.setTimeout)(options.reconnectDelayMs, undefined, {
+                        signal: abortController.signal,
+                    });
+                }
+                catch (error) {
+                    if (!abortController.signal.aborted) {
+                        throw error;
+                    }
+                }
+            }
+        }
+    })();
+    return {
+        ready: connected,
+        async stopAsync() {
+            options.signal?.removeEventListener('abort', stop);
+            stop();
+            await connectionLoop;
+        },
+    };
+}
+function waitForOpen(socket) {
+    return new Promise((resolve, reject) => {
+        socket.once('open', resolve);
+        socket.once('error', reject);
+        socket.once('close', () => reject(new Error('Sandbox MCP server closed before it connected.')));
+    });
+}
+function waitForClose(socket) {
+    if (socket.readyState === ws_1.default.CLOSING || socket.readyState === ws_1.default.CLOSED) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        socket.once('close', resolve);
+        socket.once('error', reject);
+    });
+}