@expo/build-tools 23.2.0 → 24.1.0

package/dist/steps/utils/localEgress.js

@@ -0,0 +1,550 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHISEL_VERSION = exports.LOCAL_EGRESS_HANDOFF_PATH = exports.LOCAL_EGRESS_USERNAME = exports.LOCAL_EGRESS_PROXY_PORT = exports.LOCAL_EGRESS_PROXY_HOST = void 0;
+exports.getChiselAssetName = getChiselAssetName;
+exports.getChiselDownloadUrl = getChiselDownloadUrl;
+exports.downloadChiselAsync = downloadChiselAsync;
+exports.generateEgressCredentials = generateEgressCredentials;
+exports.createChiselAuthfileContents = createChiselAuthfileContents;
+exports.parseChiselFingerprint = parseChiselFingerprint;
+exports.startChiselServerAsync = startChiselServerAsync;
+exports.parseDefaultRouteInterface = parseDefaultRouteInterface;
+exports.parseNetworkServiceNameForDevice = parseNetworkServiceNameForDevice;
+exports.resolveActiveNetworkServiceNameAsync = resolveActiveNetworkServiceNameAsync;
+exports.buildNetworksetupProxyArgs = buildNetworksetupProxyArgs;
+exports.configureSystemProxyAsync = configureSystemProxyAsync;
+exports.writeLocalEgressHandoffAsync = writeLocalEgressHandoffAsync;
+exports.readLocalEgressHandoffAsync = readLocalEgressHandoffAsync;
+exports.buildEgressRemoteConfigFields = buildEgressRemoteConfigFields;
+exports.registerLocalEgressResources = registerLocalEgressResources;
+exports.stopLocalEgressResourcesAsync = stopLocalEgressResourcesAsync;
+exports.isPortListeningAsync = isPortListeningAsync;
+exports.parseExitIpResponse = parseExitIpResponse;
+exports.fetchExitIpThroughProxyAsync = fetchExitIpThroughProxyAsync;
+exports.collectSimulatorProcessIds = collectSimulatorProcessIds;
+exports.parseDirectSimulatorConnections = parseDirectSimulatorConnections;
+exports.monitorLocalEgressAsync = monitorLocalEgressAsync;
+const downloader_1 = __importDefault(require("@expo/downloader"));
+const eas_build_job_1 = require("@expo/eas-build-job");
+const turtle_spawn_1 = __importDefault(require("@expo/turtle-spawn"));
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_net_1 = __importDefault(require("node:net"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = require("node:stream/promises");
+const node_zlib_1 = __importDefault(require("node:zlib"));
+const retry_1 = require("../../utils/retry");
+const remoteDeviceRunSession_1 = require("./remoteDeviceRunSession");
+/**
+ * Local egress provides an HTTP(S) proxy through the machine running the EAS CLI.
+ * Requests that use this proxy exit through that machine's network.
+ *
+ * Worker side: a chisel server in reverse mode listens on loopback and is exposed
+ * through the session's ngrok domain. When the CLI's egress client connects, chisel
+ * opens LOCAL_EGRESS_PROXY_PORT on this host and forwards every connection to the
+ * HTTP proxy the CLI runs. The macOS system proxy points at that port. Until the
+ * client connects, nothing listens on the port and proxied requests fail.
+ *
+ * Contract: HTTP(S) and WebSocket requests that honor the system proxy (WebKit,
+ * URLSession and other CFNetwork clients) exit from the egress client's network
+ * and fail while the client is disconnected. Requests from libraries that bypass
+ * the system proxy are not covered and exit from this host. Nothing here enforces
+ * routing; the session monitor reports such direct connections instead.
+ */
+exports.LOCAL_EGRESS_PROXY_HOST = '127.0.0.1';
+exports.LOCAL_EGRESS_PROXY_PORT = 8899;
+exports.LOCAL_EGRESS_USERNAME = 'eas';
+exports.LOCAL_EGRESS_HANDOFF_PATH = node_path_1.default.join(node_os_1.default.tmpdir(), 'eas-simulator-local-egress.json');
+exports.CHISEL_VERSION = '1.12.0';
+// sha256 of the release .gz assets, cross-checked against chisel_1.12.0_checksums.txt.
+const CHISEL_SHA256_BY_ASSET = {
+    'chisel_1.12.0_darwin_arm64.gz': '707a4b932eea214765146504a0df246cefc415b4297af65a80dd67cf69ba85a9',
+    'chisel_1.12.0_darwin_amd64.gz': '4aeae36c867f11c8e8c3f2b913a0e063ea3c6d29e1c14a52ed2e6eef8cfc4395',
+    'chisel_1.12.0_linux_amd64.gz': 'f3f180f1d93aa72cce4e6386f98cc06569a0146fbd65eb4423cf83e6434bcfe6',
+    'chisel_1.12.0_linux_arm64.gz': '2ec6152cd2c74fe0146d4d79e4e7aa174521368c56e433d55e023a92ea404ec3',
+};
+const CHISEL_STARTUP_TIMEOUT_MS = 15_000;
+const EGRESS_MONITOR_INTERVAL_MS = 2_000;
+const EGRESS_ESCAPE_SCAN_INTERVAL_MS = 5_000;
+const EGRESS_ESCAPE_LOG_LIMIT = 50;
+function getChiselAssetName({ platform, arch, }) {
+    const os = platform === 'darwin' ? 'darwin' : platform === 'linux' ? 'linux' : null;
+    const cpu = arch === 'arm64' ? 'arm64' : arch === 'x64' ? 'amd64' : null;
+    if (!os || !cpu) {
+        throw new eas_build_job_1.SystemError(`Local egress is not supported on ${platform}/${arch}. The reverse tunnel binary is available for macOS and Linux on arm64 and x64.`);
+    }
+    return `chisel_${exports.CHISEL_VERSION}_${os}_${cpu}.gz`;
+}
+function getChiselDownloadUrl(assetName) {
+    return `https://github.com/jpillora/chisel/releases/download/v${exports.CHISEL_VERSION}/${assetName}`;
+}
+async function sha256FileAsync(filePath) {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    await (0, promises_1.pipeline)(node_fs_1.default.createReadStream(filePath), hash);
+    return hash.digest('hex');
+}
+async function downloadChiselAsync({ destinationDir, logger, platform = process.platform, arch = process.arch, }) {
+    const assetName = getChiselAssetName({ platform, arch });
+    const expectedSha256 = CHISEL_SHA256_BY_ASSET[assetName];
+    if (!expectedSha256) {
+        throw new eas_build_job_1.SystemError(`No pinned checksum for ${assetName}.`);
+    }
+    const url = getChiselDownloadUrl(assetName);
+    const archivePath = node_path_1.default.join(destinationDir, assetName);
+    logger.info(`Downloading ${url}.`);
+    await (0, downloader_1.default)(url, archivePath, { retry: 3, timeout: 60_000 });
+    const actualSha256 = await sha256FileAsync(archivePath);
+    if (actualSha256 !== expectedSha256) {
+        throw new eas_build_job_1.SystemError(`Checksum mismatch for ${assetName}: expected ${expectedSha256}, got ${actualSha256}. ` +
+            'The download may be corrupted or tampered with; the session was not started.');
+    }
+    const binaryPath = node_path_1.default.join(destinationDir, 'chisel');
+    await (0, promises_1.pipeline)(node_fs_1.default.createReadStream(archivePath), node_zlib_1.default.createGunzip(), node_fs_1.default.createWriteStream(binaryPath));
+    await node_fs_1.default.promises.chmod(binaryPath, 0o755);
+    return binaryPath;
+}
+function generateEgressCredentials() {
+    return { user: exports.LOCAL_EGRESS_USERNAME, password: (0, node_crypto_1.randomBytes)(24).toString('base64url') };
+}
+// Matches 1024-65535: every unprivileged TCP port.
+const UNPRIVILEGED_PORT_PATTERN = '(102[4-9]|10[3-9][0-9]|1[1-9][0-9]{2}|[2-9][0-9]{3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])';
+/**
+ * chisel authfile: one user, allowed to open reverse remotes on loopback only.
+ * The proxy port carries proxied requests. Any unprivileged loopback port may be
+ * forwarded too: the EAS CLI opens one per `--egress-allow localhost:<port>`
+ * entry so `127.0.0.1:<port>` inside the simulator reaches that port on the
+ * developer's machine, like `adb reverse`. iOS never sends loopback-literal
+ * requests to the system proxy, so the proxy alone cannot serve them.
+ * Reverse remotes are matched as `R:<interface>:<port>`.
+ */
+function createChiselAuthfileContents({ user, password, port, }) {
+    const escapedHost = exports.LOCAL_EGRESS_PROXY_HOST.replace(/\./g, '\\.');
+    return JSON.stringify({
+        [`${user}:${password}`]: [
+            `^R:${escapedHost}:${port}$`,
+            `^R:${escapedHost}:${UNPRIVILEGED_PORT_PATTERN}$`,
+        ],
+    });
+}
+function parseChiselFingerprint(output) {
+    const match = /Fingerprint\s+(\S+)/.exec(output);
+    return match?.[1] ?? null;
+}
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function startChiselServerAsync({ chiselPath, controlPort, authfilePath, env, signal, }) {
+    const server = (0, remoteDeviceRunSession_1.spawnDetached)({
+        command: chiselPath,
+        args: [
+            'server',
+            '--host',
+            exports.LOCAL_EGRESS_PROXY_HOST,
+            '--port',
+            String(controlPort),
+            '--reverse',
+            '--authfile',
+            authfilePath,
+        ],
+        // AUTH adds an unrestricted user even when --authfile is supplied.
+        env: { ...env, AUTH: '' },
+    });
+    try {
+        const deadline = Date.now() + CHISEL_STARTUP_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            signal?.throwIfAborted();
+            if (server.pid === undefined || !isProcessRunning(server.pid)) {
+                break;
+            }
+            const output = server.getOutput();
+            const fingerprint = parseChiselFingerprint(output);
+            // Chisel prints the fingerprint before binding. This line comes from the
+            // child only after its listener succeeds, unlike a probe of a reused port.
+            const listening = output
+                .split('\n')
+                .some(line => line
+                .trimEnd()
+                .endsWith(`server: Listening on http://${exports.LOCAL_EGRESS_PROXY_HOST}:${controlPort}`));
+            if (fingerprint && listening) {
+                return { process: server, fingerprint };
+            }
+            await (0, retry_1.sleepAsync)(250);
+        }
+        throw new eas_build_job_1.SystemError(`The reverse tunnel server did not start within ${CHISEL_STARTUP_TIMEOUT_MS / 1000}s. Output:\n${server.getOutput() || '<empty>'}`);
+    }
+    catch (error) {
+        await server.stopAsync();
+        throw error;
+    }
+}
+function parseDefaultRouteInterface(routeOutput) {
+    const match = /^\s*interface:\s*(\S+)/m.exec(routeOutput);
+    return match?.[1] ?? null;
+}
+/**
+ * `networksetup -listnetworkserviceorder` prints each service as two lines:
+ * "(1) Wi-Fi" followed by "(Hardware Port: Wi-Fi, Device: en0)". Return the
+ * service name whose device matches.
+ */
+function parseNetworkServiceNameForDevice(listOutput, device) {
+    const lines = listOutput.split('\n').map(line => line.trim());
+    for (let i = 0; i < lines.length; i++) {
+        const hardwarePortMatch = /^\(Hardware Port: (.+), Device: (\S+)\)$/.exec(lines[i]);
+        if (!hardwarePortMatch || hardwarePortMatch[2] !== device) {
+            continue;
+        }
+        const serviceLineMatch = /^\(\d+\) (.+)$/.exec(lines[i - 1] ?? '');
+        return serviceLineMatch?.[1] ?? hardwarePortMatch[1];
+    }
+    return null;
+}
+async function resolveActiveNetworkServiceNameAsync({ env, }) {
+    const routeResult = await (0, turtle_spawn_1.default)('route', ['-n', 'get', 'default'], { env, stdio: 'pipe' });
+    const device = parseDefaultRouteInterface(routeResult.stdout);
+    if (!device) {
+        throw new eas_build_job_1.SystemError('Could not determine the default network interface of the device host, so the system proxy ' +
+            'cannot be configured. Output of `route -n get default`:\n' +
+            (routeResult.stdout || '<empty>'));
+    }
+    const listResult = await (0, turtle_spawn_1.default)('networksetup', ['-listnetworkserviceorder'], {
+        env,
+        stdio: 'pipe',
+    });
+    const service = parseNetworkServiceNameForDevice(listResult.stdout, device);
+    if (!service) {
+        throw new eas_build_job_1.SystemError(`Could not find the network service for interface ${device}, so the system proxy cannot be ` +
+            'configured. Output of `networksetup -listnetworkserviceorder`:\n' +
+            (listResult.stdout || '<empty>'));
+    }
+    return service;
+}
+function buildNetworksetupProxyArgs({ service, host, port, }) {
+    return [
+        ['-setwebproxy', service, host, String(port)],
+        ['-setsecurewebproxy', service, host, String(port)],
+    ];
+}
+/**
+ * Point the macOS system HTTP and HTTPS proxy at the loopback egress port. The
+ * simulator reads these settings when it boots, so this must run before
+ * `start_ios_simulator`. Existing bypass and automatic proxy settings are left
+ * unchanged. Requests that bypass this proxy can leave from this host's address.
+ */
+async function configureSystemProxyAsync({ env, logger, port, signal, }) {
+    if (process.env.ENVIRONMENT === 'development') {
+        logger.info('Job running outside of EAS, not changing the system proxy.');
+        return { service: '<development>' };
+    }
+    const service = await resolveActiveNetworkServiceNameAsync({ env });
+    for (const args of buildNetworksetupProxyArgs({ service, host: exports.LOCAL_EGRESS_PROXY_HOST, port })) {
+        signal?.throwIfAborted();
+        await (0, turtle_spawn_1.default)('networksetup', args, { env, logger, signal });
+    }
+    logger.info(`System proxy for "${service}" set to ${exports.LOCAL_EGRESS_PROXY_HOST}:${port}.`);
+    return { service };
+}
+async function writeLocalEgressHandoffAsync(handoff, handoffPath = exports.LOCAL_EGRESS_HANDOFF_PATH) {
+    await node_fs_1.default.promises.writeFile(handoffPath, JSON.stringify(handoff), {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+async function readLocalEgressHandoffAsync(handoffPath = exports.LOCAL_EGRESS_HANDOFF_PATH) {
+    let raw;
+    try {
+        raw = await node_fs_1.default.promises.readFile(handoffPath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.url !== 'string' ||
+        typeof parsed.token !== 'string' ||
+        typeof parsed.fingerprint !== 'string' ||
+        typeof parsed.port !== 'number') {
+        throw new eas_build_job_1.SystemError(`Local egress handoff at ${handoffPath} is malformed.`);
+    }
+    return {
+        url: parsed.url,
+        token: parsed.token,
+        fingerprint: parsed.fingerprint,
+        port: parsed.port,
+    };
+}
+/** remoteConfig fields the CLI needs to start the egress client. */
+function buildEgressRemoteConfigFields(handoff) {
+    if (!handoff) {
+        return {};
+    }
+    return {
+        egressUrl: handoff.url,
+        egressToken: handoff.token,
+        egressFingerprint: handoff.fingerprint,
+        egressPort: handoff.port,
+    };
+}
+// The egress step returns before the session ends, so the resources it created
+// are held here and released by the session step or the job's finally block.
+let activeLocalEgressResources;
+function registerLocalEgressResources(stopAsync) {
+    if (activeLocalEgressResources) {
+        throw new eas_build_job_1.SystemError('Local egress resources are already registered for this job.');
+    }
+    const controller = new AbortController();
+    activeLocalEgressResources = { stopAsync, controller };
+    return controller.signal;
+}
+async function stopLocalEgressResourcesAsync(logger) {
+    const resources = activeLocalEgressResources;
+    if (!resources) {
+        return;
+    }
+    resources.controller.abort();
+    resources.stopping ??= Promise.resolve()
+        .then(resources.stopAsync)
+        .catch(err => logger.warn({ err }, 'Could not stop a local egress resource.'))
+        .finally(() => {
+        activeLocalEgressResources = undefined;
+    });
+    await resources.stopping;
+}
+async function isPortListeningAsync({ host, port, timeoutMs = 1_000, }) {
+    return await new Promise(resolve => {
+        const socket = node_net_1.default.connect({ host, port });
+        const finish = (listening) => {
+            socket.destroy();
+            resolve(listening);
+        };
+        socket.setTimeout(timeoutMs, () => finish(false));
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+    });
+}
+function parseExitIpResponse(body) {
+    const parsed = JSON.parse(body);
+    if (typeof parsed.ip !== 'string' || parsed.ip.length === 0) {
+        throw new eas_build_job_1.SystemError(`Unexpected exit IP response: ${body}`);
+    }
+    return parsed.ip;
+}
+async function fetchExitIpThroughProxyAsync({ port, env, }) {
+    const result = await (0, turtle_spawn_1.default)('curl', [
+        '-sS',
+        '--max-time',
+        '10',
+        '-x',
+        `http://${exports.LOCAL_EGRESS_PROXY_HOST}:${port}`,
+        'https://api.ipify.org?format=json',
+    ], { env, stdio: 'pipe' });
+    return parseExitIpResponse(result.stdout);
+}
+/**
+ * Processes inside the simulator run on the host as descendants of launchd_sim,
+ * so `ps -axo pid=,ppid=,comm=` ancestry identifies them. Returns every
+ * descendant pid; launchd_sim itself opens no network connections.
+ */
+function collectSimulatorProcessIds(psOutput) {
+    const childrenByParent = new Map();
+    const roots = [];
+    for (const line of psOutput.split('\n')) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(\S.*)$/.exec(line);
+        if (!match) {
+            continue;
+        }
+        const pid = Number(match[1]);
+        const parentPid = Number(match[2]);
+        const command = match[3].trim();
+        const siblings = childrenByParent.get(parentPid) ?? [];
+        siblings.push(pid);
+        childrenByParent.set(parentPid, siblings);
+        if (node_path_1.default.basename(command) === 'launchd_sim') {
+            roots.push(pid);
+        }
+    }
+    const descendants = [];
+    const seen = new Set(roots);
+    const queue = [...roots];
+    for (let i = 0; i < queue.length; i++) {
+        for (const child of childrenByParent.get(queue[i]) ?? []) {
+            if (seen.has(child)) {
+                continue;
+            }
+            seen.add(child);
+            descendants.push(child);
+            queue.push(child);
+        }
+    }
+    return descendants;
+}
+function remoteHostOf(remote) {
+    if (remote.startsWith('[')) {
+        const end = remote.indexOf(']');
+        return end === -1 ? remote : remote.slice(1, end);
+    }
+    const colon = remote.lastIndexOf(':');
+    return colon === -1 ? remote : remote.slice(0, colon);
+}
+function isLoopbackHost(host) {
+    return (host === 'localhost' || host.startsWith('127.') || host === '::1' || host === '::ffff:127.0.0.1');
+}
+/**
+ * Parse `lsof -nP -i -F pcPnT` output. Returns the TCP and UDP connections that
+ * simulator processes hold to peers outside loopback. Those did not go through
+ * the proxy on 127.0.0.1, so they exit from this host instead of the egress
+ * client. Listening sockets, unconnected UDP sockets and connections to
+ * loopback (the proxy itself) are ignored.
+ */
+function parseDirectSimulatorConnections(lsofOutput, simulatorPids) {
+    const connections = [];
+    let pid = null;
+    let command = '';
+    let protocol = null;
+    let name = null;
+    let tcpState = null;
+    const flush = () => {
+        if (pid !== null && simulatorPids.has(pid) && protocol && name) {
+            const arrow = name.indexOf('->');
+            const remote = arrow === -1 ? null : name.slice(arrow + 2);
+            const active = protocol !== 'TCP' ||
+                tcpState === null ||
+                tcpState === 'ESTABLISHED' ||
+                tcpState === 'SYN_SENT';
+            if (remote && active && !isLoopbackHost(remoteHostOf(remote))) {
+                connections.push({ pid, command, protocol, remote });
+            }
+        }
+        protocol = null;
+        name = null;
+        tcpState = null;
+    };
+    for (const line of lsofOutput.split('\n')) {
+        const field = line[0];
+        const value = line.slice(1);
+        switch (field) {
+            case 'p':
+                flush();
+                pid = Number(value);
+                command = '';
+                break;
+            case 'c':
+                command = value;
+                break;
+            case 'f':
+                flush();
+                break;
+            case 'P':
+                protocol = value;
+                break;
+            case 'n':
+                name = value;
+                break;
+            case 'T':
+                if (value.startsWith('ST=')) {
+                    tcpState = value.slice('ST='.length);
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    flush();
+    return connections;
+}
+async function findDirectSimulatorConnectionsAsync({ env, }) {
+    const ps = await (0, turtle_spawn_1.default)('ps', ['-axo', 'pid=,ppid=,comm='], { env, stdio: 'pipe' });
+    const pids = collectSimulatorProcessIds(ps.stdout);
+    if (pids.length === 0) {
+        return [];
+    }
+    let lsofOutput;
+    try {
+        const lsof = await (0, turtle_spawn_1.default)('lsof', ['-nP', '-i', '-F', 'pcPnT', '-a', '-p', pids.join(',')], {
+            env,
+            stdio: 'pipe',
+        });
+        lsofOutput = lsof.stdout;
+    }
+    catch (err) {
+        // lsof exits with 1 when none of the processes holds a matching socket, and
+        // when one of them exited between `ps` and `lsof`. Its stdout is still valid.
+        const result = err;
+        if (result.status !== 1) {
+            throw err;
+        }
+        lsofOutput = result.stdout ?? '';
+    }
+    return parseDirectSimulatorConnections(lsofOutput, new Set(pids));
+}
+/**
+ * Log proxy listener availability, the exit IP observed by a worker request
+ * through it, and simulator connections that bypassed the proxy. Neither check
+ * verifies that proxied simulator requests reach the egress client. Never
+ * rejects: it runs in the background for the whole session.
+ */
+async function monitorLocalEgressAsync({ port, env, logger, signal, }) {
+    let connected = false;
+    let lastEscapeScanAt = 0;
+    let escapeScanBroken = false;
+    const reportedEscapes = new Set();
+    const lifetimeSignal = activeLocalEgressResources?.controller.signal;
+    try {
+        while (!signal.aborted && !lifetimeSignal?.aborted) {
+            const listening = await isPortListeningAsync({ host: exports.LOCAL_EGRESS_PROXY_HOST, port });
+            if (listening && !connected) {
+                connected = true;
+                logger.info('Local egress proxy listener is available.');
+                try {
+                    const exitIp = await fetchExitIpThroughProxyAsync({ port, env });
+                    logger.info(`Worker proxy exit-IP check observed ${exitIp}. This does not verify simulator routing.`);
+                }
+                catch (err) {
+                    logger.warn({ err }, 'The local egress proxy listener is available, but the worker exit-IP check through it failed.');
+                }
+            }
+            else if (!listening && connected) {
+                connected = false;
+                logger.warn('Local egress proxy listener is unavailable. Proxied HTTP(S) requests fail until it returns.');
+            }
+            if (!escapeScanBroken && Date.now() - lastEscapeScanAt >= EGRESS_ESCAPE_SCAN_INTERVAL_MS) {
+                lastEscapeScanAt = Date.now();
+                try {
+                    for (const connection of await findDirectSimulatorConnectionsAsync({ env })) {
+                        const key = `${connection.pid}|${connection.protocol}|${connection.remote}`;
+                        if (reportedEscapes.has(key)) {
+                            continue;
+                        }
+                        reportedEscapes.add(key);
+                        if (reportedEscapes.size > EGRESS_ESCAPE_LOG_LIMIT) {
+                            if (reportedEscapes.size === EGRESS_ESCAPE_LOG_LIMIT + 1) {
+                                logger.warn(`Local egress: more than ${EGRESS_ESCAPE_LOG_LIMIT} direct connections were reported; further ones are not logged.`);
+                            }
+                            continue;
+                        }
+                        logger.warn(`Local egress: ${connection.command} (pid ${connection.pid}) opened a direct ${connection.protocol} connection to ${connection.remote}, bypassing the system proxy. That traffic exits from this worker, not from the egress client.`);
+                    }
+                }
+                catch (err) {
+                    escapeScanBroken = true;
+                    logger.warn({ err }, 'Local egress: could not inspect simulator connections. Direct connections that bypass the proxy will not be reported.');
+                }
+            }
+            await (0, retry_1.sleepAsync)(EGRESS_MONITOR_INTERVAL_MS);
+        }
+    }
+    catch (err) {
+        logger.warn({ err }, 'Local egress monitoring stopped unexpectedly.');
+    }
+}

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

@@ -0,0 +1,9 @@
+import { type BuildFunction, type BuildStepEnv } from '@expo/steps';
+import { uploadRemoteSessionConfigAsync } from './remoteDeviceRunSession';
+/** Release the pre-boot egress resources even if controller startup or teardown fails. */
+export declare function withLocalEgressSession(fn: NonNullable<BuildFunction['fn']>): NonNullable<BuildFunction['fn']>;
+/** All simulator controllers publish the same egress handoff and run the same monitor. */
+export declare function uploadRemoteSessionConfigWithLocalEgressAsync({ env, signal, ...options }: Parameters<typeof uploadRemoteSessionConfigAsync>[0] & {
+    env: BuildStepEnv;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/steps/utils/localEgressSession.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withLocalEgressSession = withLocalEgressSession;
+exports.uploadRemoteSessionConfigWithLocalEgressAsync = uploadRemoteSessionConfigWithLocalEgressAsync;
+const localEgress_1 = require("./localEgress");
+const remoteDeviceRunSession_1 = require("./remoteDeviceRunSession");
+/** Release the pre-boot egress resources even if controller startup or teardown fails. */
+function withLocalEgressSession(fn) {
+    return async (context, args) => {
+        try {
+            args.signal?.throwIfAborted();
+            await fn(context, args);
+        }
+        finally {
+            await (0, localEgress_1.stopLocalEgressResourcesAsync)(context.logger);
+        }
+    };
+}
+/** All simulator controllers publish the same egress handoff and run the same monitor. */
+async function uploadRemoteSessionConfigWithLocalEgressAsync({ env, signal, ...options }) {
+    // Written by start_local_egress before simulator boot; absent for ordinary sessions.
+    const localEgress = await (0, localEgress_1.readLocalEgressHandoffAsync)();
+    signal?.throwIfAborted();
+    await (0, remoteDeviceRunSession_1.uploadRemoteSessionConfigAsync)({
+        ...options,
+        remoteConfig: { ...options.remoteConfig, ...(0, localEgress_1.buildEgressRemoteConfigFields)(localEgress) },
+    });
+    if (localEgress && !signal?.aborted) {
+        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
+        // withLocalEgressSession aborts on success, failure, or cancellation.
+        void (0, localEgress_1.monitorLocalEgressAsync)({
+            port: localEgress.port,
+            env,
+            logger: options.logger,
+            signal: signal ?? new AbortController().signal,
+        });
+    }
+}

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

@@ -33,22 +33,7 @@ export declare function waitForDeviceRunSessionStoppedAsync({ ctx, deviceRunSess
     signal?: AbortSignal;
     idleTimeout?: DeviceRunSessionIdleTimeout;
 }): Promise<void>;
-/**
- * Install ffmpeg when the runtime does not already provide it, so argent's
- * `screen-recording-start` tool can encode a video. The worker images do not
- * ship ffmpeg yet, so without this the tool fails with "`ffmpeg` was not found
- * on PATH" — on macOS (iOS simulators) and Linux (Android emulators) alike.
- *
- * Best-effort by design: screen recording is one optional argent tool, so a
- * failure here is logged and the session continues without it.
- *
- * The whole body is wrapped because the caller runs this in the background with
- * `void`. There is no unhandledRejection handler in the worker, so a rejection
- * escaping here would crash the process and take the live session with it.
- * `spawn` is not an async function and can throw synchronously, which
- * `asyncResult` cannot catch — it only wraps an already-created promise.
- */
-export declare function ensureFfmpegInstalledAsync({ runtimePlatform, env, logger, }: {
+export declare function ensureFfmpegInstalledOnceAsync({ runtimePlatform, env, logger, }: {
     runtimePlatform: BuildRuntimePlatform;
     env: BuildStepEnv;
     logger: bunyan;
@@ -104,17 +89,21 @@ export declare function createExpoDeviceHubArgs({ port, turnArgs, packageVersion
     turnArgs?: string[];
     packageVersion?: string;
 }): string[];
+export declare function findAvailablePortAsync(): Promise<number>;
 export declare function waitForWebPreviewReadyAsync({ previewServer, serverName, port, timeoutMs, }: {
     previewServer: Pick<DetachedProcessHandle, 'pid' | 'getOutput'>;
     serverName: string;
     port: number;
     timeoutMs: number;
-}): Promise<void>;
+}): Promise<string>;
 export type DeviceWebPreviewHandle = {
     previewUrl: string;
+    /** Session token gating the preview. Only serve-sim mints one. */
+    previewToken?: string;
     stopAsync: () => Promise<void>;
 };
 export type ServeSimPreviewHandle = DeviceWebPreviewHandle;
+export declare function readServeSimPreviewTokenAsync(udid: string, stateDir?: string): Promise<string | undefined>;
 export declare function startServeSimWithTunnelAsync(ctx: CustomBuildContext, { baseDomain, env, logger, timeoutMs, packageVersion, }: {
     baseDomain: string;
     env: BuildStepEnv;
@@ -122,7 +111,8 @@ export declare function startServeSimWithTunnelAsync(ctx: CustomBuildContext, {
     timeoutMs: number;
     packageVersion?: string;
 }): Promise<ServeSimPreviewHandle>;
-export declare function startExpoDeviceHubWithTunnelAsync(ctx: CustomBuildContext, { baseDomain, env, logger, timeoutMs, packageVersion, }: {
+export declare function startExpoDeviceHubWithTunnelAsync(ctx: CustomBuildContext, { runtimePlatform, baseDomain, env, logger, timeoutMs, packageVersion, }: {
+    runtimePlatform: BuildRuntimePlatform;
     baseDomain: string;
     env: BuildStepEnv;
     logger: bunyan;