@expo/build-tools 24.3.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/utils/IosSimulatorUtils.d.ts

@@ -52,6 +52,29 @@ export declare namespace IosSimulatorUtils {
         deviceIdentifier: IosSimulatorUuid | IosSimulatorName;
         env: NodeJS.ProcessEnv;
     }): Promise<void>;
+    /**
+     * The UDID for a device name or UDID. A name picks the first available
+     * device with that name, as `simctl` itself does.
+     */
+    export function resolveUdidAsync({ deviceIdentifier, env, }: {
+        deviceIdentifier: IosSimulatorUuid | IosSimulatorName;
+        env: NodeJS.ProcessEnv;
+    }): Promise<IosSimulatorUuid>;
+    /**
+     * Start booting without waiting for boot to complete; follow with
+     * `startAsync` to wait for it. `launchdEnvironment` is handed to the
+     * simulator's launchd before it spawns anything: `simctl` forwards every
+     * `SIMCTL_CHILD_`-prefixed variable of its own environment to the process
+     * it starts, and for `boot` that process is launchd itself. This is the only
+     * way to give the first processes of a boot an environment; `launchctl
+     * setenv` after boot only reaches processes started later. A device that is
+     * already booted keeps its environment.
+     */
+    export function bootAsync({ deviceIdentifier, env, launchdEnvironment, }: {
+        deviceIdentifier: IosSimulatorUuid | IosSimulatorName;
+        env: NodeJS.ProcessEnv;
+        launchdEnvironment?: Record<string, string>;
+    }): Promise<void>;
     export function startAsync({ deviceIdentifier, env, }: {
         deviceIdentifier: IosSimulatorUuid | IosSimulatorName;
         env: NodeJS.ProcessEnv;
@@ -66,6 +89,17 @@ export declare namespace IosSimulatorUtils {
         udid: IosSimulatorUuid;
         env: NodeJS.ProcessEnv;
     }): Promise<void>;
+    /**
+     * Set environment variables in the Simulator's launchd. Every process that
+     * launchd spawns afterwards inherits them: apps launched by SpringBoard
+     * (deep links, taps, WebDriverAgent) as well as by `simctl launch`.
+     * Processes that are already running keep their environment.
+     */
+    export function setLaunchdEnvironmentAsync({ udid, env, variables, }: {
+        udid: IosSimulatorUuid;
+        env: NodeJS.ProcessEnv;
+        variables: Record<string, string>;
+    }): Promise<void>;
     export function collectLogsAsync({ deviceIdentifier, env, }: {
         deviceIdentifier: IosSimulatorName | IosSimulatorUuid;
         env: NodeJS.ProcessEnv;

package/dist/utils/IosSimulatorUtils.js

@@ -87,6 +87,50 @@ var IosSimulatorUtils;
         }
     }
     IosSimulatorUtils.enableAccessibilitySettingsAsync = enableAccessibilitySettingsAsync;
+    const UDID_PATTERN = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
+    /**
+     * The UDID for a device name or UDID. A name picks the first available
+     * device with that name, as `simctl` itself does.
+     */
+    async function resolveUdidAsync({ deviceIdentifier, env, }) {
+        if (UDID_PATTERN.test(deviceIdentifier)) {
+            return deviceIdentifier;
+        }
+        const devices = await getAvailableDevicesAsync({ env, filter: 'available' });
+        const device = devices.find(candidate => candidate.name === deviceIdentifier);
+        if (!device) {
+            throw new eas_build_job_1.UserError('EAS_IOS_SIMULATOR_NOT_FOUND', `No available iOS Simulator is named "${deviceIdentifier}". Run \`xcrun simctl list devices available\` on the device host to see the devices it offers.`);
+        }
+        return device.udid;
+    }
+    IosSimulatorUtils.resolveUdidAsync = resolveUdidAsync;
+    /**
+     * Start booting without waiting for boot to complete; follow with
+     * `startAsync` to wait for it. `launchdEnvironment` is handed to the
+     * simulator's launchd before it spawns anything: `simctl` forwards every
+     * `SIMCTL_CHILD_`-prefixed variable of its own environment to the process
+     * it starts, and for `boot` that process is launchd itself. This is the only
+     * way to give the first processes of a boot an environment; `launchctl
+     * setenv` after boot only reaches processes started later. A device that is
+     * already booted keeps its environment.
+     */
+    async function bootAsync({ deviceIdentifier, env, launchdEnvironment = {}, }) {
+        const bootEnv = { ...env };
+        for (const [name, value] of Object.entries(launchdEnvironment)) {
+            bootEnv[`SIMCTL_CHILD_${name}`] = value;
+        }
+        try {
+            await (0, turtle_spawn_1.default)('xcrun', ['simctl', 'boot', deviceIdentifier], { env: bootEnv, stdio: 'pipe' });
+        }
+        catch (err) {
+            const failed = err;
+            if (/current state: Booted/.test(failed.stderr ?? '')) {
+                return;
+            }
+            throw err;
+        }
+    }
+    IosSimulatorUtils.bootAsync = bootAsync;
     async function startAsync({ deviceIdentifier, env, }) {
         const bootstatusResult = await (0, turtle_spawn_1.default)('xcrun', ['simctl', 'bootstatus', deviceIdentifier, '-b'], {
             env,
@@ -154,6 +198,24 @@ var IosSimulatorUtils;
         throw lastError ?? new eas_build_job_1.SystemError('Unable to disable apsd in the Simulator.');
     }
     IosSimulatorUtils.disableApsdAsync = disableApsdAsync;
+    /**
+     * Set environment variables in the Simulator's launchd. Every process that
+     * launchd spawns afterwards inherits them: apps launched by SpringBoard
+     * (deep links, taps, WebDriverAgent) as well as by `simctl launch`.
+     * Processes that are already running keep their environment.
+     */
+    async function setLaunchdEnvironmentAsync({ udid, env, variables, }) {
+        // One invocation for every variable: each `simctl spawn` costs a few
+        // hundred milliseconds on a device host, and this runs in the window
+        // between `simctl boot` returning and launchd spawning the boot's
+        // processes, which must inherit these.
+        const pairs = Object.entries(variables).flat();
+        if (pairs.length === 0) {
+            return;
+        }
+        await (0, turtle_spawn_1.default)('xcrun', ['simctl', 'spawn', udid, 'launchctl', 'setenv', ...pairs], { env });
+    }
+    IosSimulatorUtils.setLaunchdEnvironmentAsync = setLaunchdEnvironmentAsync;
     async function collectLogsAsync({ deviceIdentifier, env, }) {
         const outputDir = await node_fs_1.default.promises.mkdtemp(node_path_1.default.join(node_os_1.default.tmpdir(), 'ios-simulator-logs-'));
         const outputPath = node_path_1.default.join(outputDir, `${deviceIdentifier}.logarchive`);