@autifyhq/aximo-cli 0.6.0 → 0.8.0

package/dist/mobile-control/ios-resign.js

@@ -0,0 +1,101 @@
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execBinary } from "./exec.js";
+import { parseProfileXml } from "./ios-profiles.js";
+const TOP_LEVEL_PLIST = /^Payload\/[^/]+\.app\/Info\.plist$/;
+/** Inspect an IPA's identity/signature surface without a full extraction. */
+export async function inspectIpa(ipaPath, exec = execBinary) {
+    const { stdout } = await exec("unzip", ["-Z1", ipaPath]);
+    const entries = stdout.toString("utf-8").split("\n");
+    const plistEntry = entries.find((e) => TOP_LEVEL_PLIST.test(e.trim()))?.trim();
+    if (!plistEntry) {
+        throw new Error(`Not a valid .ipa (no Payload/<app>.app/Info.plist): ${ipaPath}`);
+    }
+    const appDir = plistEntry.slice(0, -"/Info.plist".length);
+    const profileEntry = `${appDir}/embedded.mobileprovision`;
+    const hasProfile = entries.some((e) => e.trim() === profileEntry);
+    const scratch = mkdtempSync(join(tmpdir(), "aximo-ipa-inspect-"));
+    try {
+        const wanted = [plistEntry, ...(hasProfile ? [profileEntry] : [])];
+        await exec("unzip", ["-o", "-q", ipaPath, ...wanted, "-d", scratch]);
+        const plistPath = join(scratch, plistEntry);
+        const bundleId = (await exec("plutil", ["-extract", "CFBundleIdentifier", "raw", plistPath])).stdout
+            .toString("utf-8")
+            .trim();
+        if (!bundleId)
+            throw new Error(`Could not read CFBundleIdentifier from ${ipaPath}`);
+        let profile = null;
+        if (hasProfile) {
+            try {
+                const { stdout: xml } = await exec("security", [
+                    "cms",
+                    "-D",
+                    "-i",
+                    join(scratch, profileEntry),
+                ]);
+                profile = parseProfileXml(xml.toString("utf-8"), profileEntry);
+            }
+            catch {
+                profile = null; // undecodable profile → treated as not installable
+            }
+        }
+        const encrypted = await readEncryption(ipaPath, appDir, plistPath, scratch, exec);
+        return { bundleId, profile, encrypted };
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+/** FairPlay check: extract just the main binary and read LC_ENCRYPTION_INFO. */
+async function readEncryption(ipaPath, appDir, plistPath, scratch, exec) {
+    try {
+        const executable = (await exec("plutil", ["-extract", "CFBundleExecutable", "raw", plistPath])).stdout
+            .toString("utf-8")
+            .trim();
+        // Plain filename only — a crafted CFBundleExecutable must not become a zip
+        // pattern or filesystem path segment (traversal during extraction).
+        if (!executable || /[/\\]/.test(executable) || executable === "..")
+            return null;
+        const binEntry = `${appDir}/${executable}`;
+        await exec("unzip", ["-o", "-q", ipaPath, binEntry, "-d", scratch]);
+        const { stdout } = await exec("otool", ["-l", join(scratch, binEntry)]);
+        const cryptid = stdout.toString("utf-8").match(/cryptid\s+(\d+)/);
+        return cryptid?.[1] ? cryptid[1] !== "0" : null;
+    }
+    catch {
+        return null; // best-effort; a resign attempt will surface real problems
+    }
+}
+/** True when the IPA (per its embedded profile) can install on `udid` as-is. */
+export function isInstallableOn(info, udid, now = Date.now()) {
+    const profile = info.profile;
+    if (!profile)
+        return false;
+    if (profile.expirationDate.getTime() <= now)
+        return false;
+    return profile.provisionedDevices === null || profile.provisionedDevices.includes(udid);
+}
+function applesignBin() {
+    return createRequire(import.meta.url).resolve("applesign/bin/applesign.js");
+}
+/** Re-sign an IPA via the bundled applesign (never PATH-dependent). */
+export async function resignIpa(options) {
+    const exec = options.exec ?? execBinary;
+    const args = [
+        applesignBin(),
+        "-i",
+        options.identityHash,
+        "-m",
+        options.profilePath,
+        ...(options.bundleId ? ["-b", options.bundleId] : []),
+        "-o",
+        options.outPath,
+        options.ipaPath,
+    ];
+    await exec(process.execPath, args);
+    if (!existsSync(options.outPath)) {
+        throw new Error(`applesign reported success but ${options.outPath} was not created.`);
+    }
+}

package/dist/mobile-control/ios-resign.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mobile-control/ios-resign.test.js

@@ -0,0 +1,84 @@
+import { writeFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { isInstallableOn, resignIpa } from "./ios-resign.js";
+const NOW = new Date("2026-07-13T00:00:00Z").getTime();
+function profile(over) {
+    return {
+        path: "/p",
+        name: "p",
+        teamId: "TESTTEAM99",
+        bundleId: "com.example.app",
+        isWildcard: false,
+        expirationDate: new Date("2026-07-20T00:00:00Z"),
+        provisionedDevices: ["UDID-1"],
+        ...over,
+    };
+}
+describe("isInstallableOn", () => {
+    const info = (p) => ({
+        bundleId: "com.example.app",
+        profile: p,
+        encrypted: false,
+    });
+    it("requires an embedded profile", () => {
+        expect(isInstallableOn(info(null), "UDID-1", NOW)).toBe(false);
+    });
+    it("requires the profile to be unexpired and cover the udid", () => {
+        expect(isInstallableOn(info(profile({})), "UDID-1", NOW)).toBe(true);
+        expect(isInstallableOn(info(profile({})), "OTHER", NOW)).toBe(false);
+        const expired = profile({ expirationDate: new Date("2026-07-01T00:00:00Z") });
+        expect(isInstallableOn(info(expired), "UDID-1", NOW)).toBe(false);
+    });
+    it("treats a missing device list (enterprise) as covering any device", () => {
+        expect(isInstallableOn(info(profile({ provisionedDevices: null })), "ANY", NOW)).toBe(true);
+    });
+});
+describe("resignIpa", () => {
+    it("runs the bundled applesign with identity, profile, remap, and output", async () => {
+        let seen = [];
+        const exec = async (file, args) => {
+            seen = [file, ...args];
+            const out = args[args.indexOf("-o") + 1];
+            if (out)
+                writeFileSync(out, "ipa");
+            return { stdout: Buffer.from(""), stderr: "" };
+        };
+        const outPath = `${process.env["TMPDIR"] ?? "/tmp"}/aximo-test-resign-out.ipa`;
+        await resignIpa({
+            ipaPath: "/apps/in.ipa",
+            outPath,
+            identityHash: "A".repeat(40),
+            profilePath: "/profiles/p.mobileprovision",
+            bundleId: "com.remapped.id",
+            exec,
+        });
+        expect(seen[0]).toBe(process.execPath);
+        expect(seen[1]).toMatch(/applesign/);
+        expect(seen).toEqual(expect.arrayContaining([
+            "-i",
+            "A".repeat(40),
+            "-m",
+            "/profiles/p.mobileprovision",
+            "-b",
+            "com.remapped.id",
+            "-o",
+            outPath,
+            "/apps/in.ipa",
+        ]));
+    });
+    it("omits -b without a remap and fails when no output is produced", async () => {
+        let seen = [];
+        const exec = async (file, args) => {
+            seen = [file, ...args];
+            return { stdout: Buffer.from(""), stderr: "" };
+        };
+        await expect(resignIpa({
+            ipaPath: "/apps/in.ipa",
+            outPath: "/nonexistent-dir/never-created.ipa",
+            identityHash: "A".repeat(40),
+            profilePath: "/profiles/p.mobileprovision",
+            exec,
+        })).rejects.toThrow(/was not created/);
+        expect(seen).not.toContain("-b");
+    });
+});

package/dist/mobile-control/ios-session-error.d.ts

@@ -0,0 +1,10 @@
+import { readWdaFailureReason } from "./ios-wda-diagnostics.js";
+/**
+ * Turn a raw XCUITest session-start failure into a transparent, actionable error:
+ * the driver's message, the real reason pulled from the WDA `.xcresult` (e.g. an
+ * untrusted developer cert), and the matching fix hint. The reason is what lets
+ * the hint fire — the driver's own message is usually too generic to match.
+ */
+export declare function enrichIosSessionError(err: unknown, derivedDataPath?: string, deps?: {
+    readReason?: typeof readWdaFailureReason;
+}): Promise<Error>;

package/dist/mobile-control/ios-session-error.js

@@ -0,0 +1,34 @@
+import { mobileErrorHint } from "./mobile-errors.js";
+import { readWdaFailureReason } from "./ios-wda-diagnostics.js";
+/**
+ * Turn a raw XCUITest session-start failure into a transparent, actionable error:
+ * the driver's message, the real reason pulled from the WDA `.xcresult` (e.g. an
+ * untrusted developer cert), and the matching fix hint. The reason is what lets
+ * the hint fire — the driver's own message is usually too generic to match.
+ */
+export async function enrichIosSessionError(err, derivedDataPath, deps = {}) {
+    const base = err instanceof Error ? err.message : String(err);
+    let reason = null;
+    try {
+        const read = deps.readReason ?? readWdaFailureReason;
+        const options = {};
+        if (derivedDataPath !== undefined)
+            options.derivedDataPath = derivedDataPath;
+        reason = await read(options);
+    }
+    catch {
+        // Best-effort diagnostics: fall back to just the driver's message.
+    }
+    const hint = mobileErrorHint(reason ?? base, "ios");
+    const parts = ["Could not start the iOS session (WebDriverAgent failed to launch)."];
+    if (reason)
+        parts.push(`Reason: ${reason}`);
+    parts.push(`Details: ${base}`);
+    if (hint)
+        parts.push(`Fix: ${hint}`);
+    parts.push("More: run `aximo mobile doctor --platform ios`.");
+    const enriched = new Error(parts.join("\n"));
+    if (err instanceof Error && err.stack)
+        enriched.stack = err.stack;
+    return enriched;
+}

package/dist/mobile-control/ios-session-error.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mobile-control/ios-session-error.test.js

@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from "vitest";
+import { enrichIosSessionError } from "./ios-session-error.js";
+describe("enrichIosSessionError", () => {
+    it("surfaces the xcresult reason and the matching trust hint", async () => {
+        const readReason = vi.fn(async () => "The Developer App Certificate is not trusted.");
+        const enriched = await enrichIosSessionError(new Error("WebDriver POST /session failed: xcodebuild failed with code 65"), "/dd", { readReason });
+        expect(enriched.message).toContain("Reason: The Developer App Certificate is not trusted.");
+        expect(enriched.message).toContain("VPN & Device Management"); // the trust hint fired
+        expect(enriched.message).toContain("xcodebuild failed with code 65"); // original detail kept
+        expect(enriched.message).toContain("aximo mobile doctor");
+    });
+    it("falls back to the driver message when no xcresult reason is available", async () => {
+        const readReason = vi.fn(async () => null);
+        const enriched = await enrichIosSessionError(new Error("xcodebuild failed with code 65"), "/dd", {
+            readReason,
+        });
+        expect(enriched.message).not.toContain("Reason:");
+        expect(enriched.message).toContain("xcodebuild failed with code 65");
+        // Generic WDA hint still fires from the driver message.
+        expect(enriched.message).toContain("Fix:");
+    });
+    it("never throws even if reason extraction fails", async () => {
+        const readReason = vi.fn(async () => {
+            throw new Error("xcresulttool missing");
+        });
+        const enriched = await enrichIosSessionError(new Error("boom"), undefined, { readReason });
+        expect(enriched).toBeInstanceOf(Error);
+        expect(enriched.message).toContain("Details: boom");
+    });
+});

package/dist/mobile-control/ios-signing.d.ts

@@ -1,11 +1,15 @@
+import { type ExecFn } from "./exec.js";
+import { listSigningIdentities } from "./ios-identity.js";
+import { listProvisioningProfiles } from "./ios-profiles.js";
 /**
  * iOS WebDriverAgent signing configuration.
  *
- * Driving a physical iPhone goes through Appium's XCUITest driver, which builds
- * and code-signs a WebDriverAgent (WDA) runner onto the device. That build needs
- * an Apple Developer signing identity. These values are supplied via env vars and
- * forwarded as XCUITest capabilities. Simulators need no signing, so the caps are
- * only emitted when a team id is configured.
+ * Driving a physical iPhone goes through Appium's XCUITest driver, which needs a
+ * development-signed WebDriverAgent (WDA) runner on the device. Configuration is
+ * zero-config by default — `resolveIosSigningAuto` discovers the identity and
+ * Team ID from the keychain and derives/reuses a WDA bundle id from the installed
+ * profiles — with env vars as overrides. Simulators need no signing, so the caps
+ * are only emitted when a team id is available.
  *
  * The CLI-native `AXIMO_IOS_*` names take precedence; Autify's MobileLink
  * (mobile-web) names — `XCODE_TEAM_ID` / `XCODE_SIGN_ID` / `WDA_BUNDLE_ID` — are
@@ -20,9 +24,33 @@ export interface IosSigningConfig {
     wdaBundleId: string;
     /** Optional prebuilt-WDA DerivedData path to skip per-session WDA rebuilds. */
     derivedDataPath?: string;
+    /** Reuse the cached WDA build in `derivedDataPath` instead of rebuilding+signing. */
+    usePrebuiltWDA?: boolean;
+    /** Launch the already-installed WDA runner instead of building (iOS 17+). */
+    usePreinstalledWDA?: boolean;
+    /** Keychain identity hash (drives re-signing; discovered, never a capability). */
+    identityHash?: string;
 }
 type Env = Record<string, string | undefined>;
 export declare function resolveIosSigning(env?: Env): IosSigningConfig;
 /** Map signing config to XCUITest capabilities; empty unless a team id is set. */
 export declare function iosSigningCapabilities(config: IosSigningConfig): Record<string, unknown>;
+/** Aximo-owned WDA bundle id for teams with no prior WDA profile. */
+export declare function defaultWdaBundleId(teamId: string): string;
+export interface ResolveIosSigningAutoOptions {
+    env?: Env;
+    exec?: ExecFn;
+    /** Device UDID — profiles are matched against it when deriving the WDA id. */
+    udid?: string;
+    now?: number;
+    listIdentities?: typeof listSigningIdentities;
+    listProfiles?: typeof listProvisioningProfiles;
+}
+/**
+ * Zero-config signing resolution: start from the env config, then fill the gaps
+ * from the keychain (identity + Team ID) and installed profiles (WDA bundle id —
+ * reuse the id of a still-valid runner profile so no re-mint is needed; derive an
+ * Aximo-owned id otherwise). Explicit env values always win.
+ */
+export declare function resolveIosSigningAuto(options?: ResolveIosSigningAutoOptions): Promise<IosSigningConfig>;
 export {};

package/dist/mobile-control/ios-signing.js

@@ -1,3 +1,6 @@
+import { execBinary } from "./exec.js";
+import { listSigningIdentities, selectIdentity } from "./ios-identity.js";
+import { listProvisioningProfiles } from "./ios-profiles.js";
 const DEFAULT_SIGNING_ID = "Apple Development";
 const DEFAULT_WDA_BUNDLE_ID = "com.facebook.WebDriverAgentRunner";
 export function resolveIosSigning(env = process.env) {
@@ -24,6 +27,14 @@ export function resolveIosSigning(env = process.env) {
 }
 /** Map signing config to XCUITest capabilities; empty unless a team id is set. */
 export function iosSigningCapabilities(config) {
+    // Preinstalled runner: the driver launches it via devicectl — no build, so no
+    // signing caps; mixing in derivedDataPath/usePrebuiltWDA would fight it.
+    if (config.usePreinstalledWDA) {
+        return {
+            "appium:usePreinstalledWDA": true,
+            "appium:updatedWDABundleId": config.wdaBundleId,
+        };
+    }
     if (!config.teamId)
         return {};
     const caps = {
@@ -34,5 +45,50 @@ export function iosSigningCapabilities(config) {
     };
     if (config.derivedDataPath)
         caps["appium:derivedDataPath"] = config.derivedDataPath;
+    if (config.usePrebuiltWDA)
+        caps["appium:usePrebuiltWDA"] = true;
     return caps;
 }
+const WDA_RUNNER_SUFFIX = ".xctrunner";
+/** Aximo-owned WDA bundle id for teams with no prior WDA profile. */
+export function defaultWdaBundleId(teamId) {
+    return `com.aximo.wda.${teamId.toLowerCase()}`;
+}
+/**
+ * Zero-config signing resolution: start from the env config, then fill the gaps
+ * from the keychain (identity + Team ID) and installed profiles (WDA bundle id —
+ * reuse the id of a still-valid runner profile so no re-mint is needed; derive an
+ * Aximo-owned id otherwise). Explicit env values always win.
+ */
+export async function resolveIosSigningAuto(options = {}) {
+    const env = options.env ?? process.env;
+    const exec = options.exec ?? execBinary;
+    const config = resolveIosSigning(env);
+    const identity = selectIdentity(await (options.listIdentities ?? listSigningIdentities)(exec), config.teamId);
+    if (identity)
+        config.identityHash = identity.hash;
+    if (!config.teamId && identity?.teamId)
+        config.teamId = identity.teamId;
+    const wdaExplicit = Boolean(env["AXIMO_IOS_WDA_BUNDLE_ID"]?.trim() || env["WDA_BUNDLE_ID"]?.trim());
+    if (!wdaExplicit && config.teamId) {
+        const profiles = await (options.listProfiles ?? listProvisioningProfiles)({ exec });
+        const now = options.now ?? Date.now();
+        // Reuse a valid runner profile for this team/device: no re-mint, and existing
+        // setups (e.g. MobileLink-style com.<user>.WebDriverAgentRunner) keep working.
+        const runnerProfile = profiles.find((p) => p.teamId === config.teamId &&
+            p.bundleId.endsWith(WDA_RUNNER_SUFFIX) &&
+            isWdaRunnerId(p.bundleId.slice(0, -WDA_RUNNER_SUFFIX.length)) &&
+            p.expirationDate.getTime() > now &&
+            (!options.udid ||
+                p.provisionedDevices === null ||
+                p.provisionedDevices.includes(options.udid)));
+        config.wdaBundleId = runnerProfile
+            ? runnerProfile.bundleId.slice(0, -WDA_RUNNER_SUFFIX.length)
+            : defaultWdaBundleId(config.teamId);
+    }
+    return config;
+}
+/** Only reuse profiles that are unmistakably WDA runners, never app-resign ones. */
+function isWdaRunnerId(baseId) {
+    return baseId.endsWith("WebDriverAgentRunner") || baseId.startsWith("com.aximo.wda.");
+}

package/dist/mobile-control/ios-signing.test.js

@@ -71,3 +71,90 @@ describe("iosSigningCapabilities", () => {
         expect(caps["appium:derivedDataPath"]).toBe("/tmp/wda");
     });
 });
+describe("resolveIosSigningAuto", async () => {
+    const { resolveIosSigningAuto, defaultWdaBundleId } = await import("./ios-signing.js");
+    const identity = {
+        hash: "0B0DF9CFF90EC3358C9A2CB52F006EB83FD7748C",
+        name: "Apple Development: test@example.com (ABC123DEF4)",
+        teamId: "TESTTEAM99",
+    };
+    const runnerProfile = {
+        path: "/p/wda.mobileprovision",
+        name: "wda",
+        teamId: "TESTTEAM99",
+        bundleId: "com.someone.WebDriverAgentRunner.xctrunner",
+        isWildcard: false,
+        expirationDate: new Date("2999-01-01T00:00:00Z"),
+        provisionedDevices: ["UDID-1"],
+    };
+    it("discovers team + identity from the keychain when env is empty", async () => {
+        const config = await resolveIosSigningAuto({
+            env: {},
+            udid: "UDID-1",
+            listIdentities: async () => [identity],
+            listProfiles: async () => [],
+        });
+        expect(config.teamId).toBe("TESTTEAM99");
+        expect(config.identityHash).toBe(identity.hash);
+        expect(config.wdaBundleId).toBe(defaultWdaBundleId("TESTTEAM99"));
+    });
+    it("lets env overrides win over discovery", async () => {
+        const config = await resolveIosSigningAuto({
+            env: { AXIMO_IOS_TEAM_ID: "ENVTEAM000", AXIMO_IOS_WDA_BUNDLE_ID: "com.env.WDA" },
+            udid: "UDID-1",
+            listIdentities: async () => [identity],
+            listProfiles: async () => [runnerProfile],
+        });
+        expect(config.teamId).toBe("ENVTEAM000");
+        expect(config.wdaBundleId).toBe("com.env.WDA"); // explicit id blocks derivation
+        expect(config.identityHash).toBeUndefined(); // no identity matches ENVTEAM000
+    });
+    it("reuses a valid runner profile's base id for this team + device", async () => {
+        const config = await resolveIosSigningAuto({
+            env: {},
+            udid: "UDID-1",
+            listIdentities: async () => [identity],
+            listProfiles: async () => [runnerProfile],
+        });
+        expect(config.wdaBundleId).toBe("com.someone.WebDriverAgentRunner");
+    });
+    it("ignores expired, other-device, other-team, and non-WDA runner profiles", async () => {
+        const expired = { ...runnerProfile, expirationDate: new Date("2000-01-01T00:00:00Z") };
+        const otherDevice = { ...runnerProfile, provisionedDevices: ["OTHER"] };
+        const otherTeam = { ...runnerProfile, teamId: "OTHERTEAM0" };
+        const resignProfile = {
+            ...runnerProfile,
+            bundleId: "com.aximo.resign.testteam99.xctrunner",
+        };
+        const config = await resolveIosSigningAuto({
+            env: {},
+            udid: "UDID-1",
+            listIdentities: async () => [identity],
+            listProfiles: async () => [expired, otherDevice, otherTeam, resignProfile],
+        });
+        expect(config.wdaBundleId).toBe(defaultWdaBundleId("TESTTEAM99"));
+    });
+    it("accepts com.aximo.wda.* profiles as reusable runner ids", async () => {
+        const aximoWda = {
+            ...runnerProfile,
+            bundleId: "com.aximo.wda.testteam99.xctrunner",
+        };
+        const config = await resolveIosSigningAuto({
+            env: {},
+            udid: "UDID-1",
+            listIdentities: async () => [identity],
+            listProfiles: async () => [aximoWda],
+        });
+        expect(config.wdaBundleId).toBe("com.aximo.wda.testteam99");
+    });
+    it("returns an env-free config with defaults when nothing is discoverable", async () => {
+        const config = await resolveIosSigningAuto({
+            env: {},
+            listIdentities: async () => [],
+            listProfiles: async () => [],
+        });
+        expect(config.teamId).toBeUndefined();
+        expect(config.identityHash).toBeUndefined();
+        expect(config.wdaBundleId).toBe("com.facebook.WebDriverAgentRunner");
+    });
+});

package/dist/mobile-control/ios-tunnel.d.ts

@@ -0,0 +1,57 @@
+/**
+ * iOS 17+/18+ device automation goes through Appium's XCUITest driver, which can
+ * only reach WebDriverAgent on the device through a RemoteXPC/CoreDevice tunnel.
+ * The driver ships a `tunnel-creation` script that must run as root (it creates a
+ * `utun` interface) and exposes a tunnel registry server on a fixed local port.
+ * Older iOS and self-managed setups can opt out with AXIMO_IOS_SKIP_TUNNEL.
+ */
+export declare const DEFAULT_TUNNEL_REGISTRY_PORT = 42314;
+/** How to stop the elevated tunnel daemon — surfaced whenever we start or leave it running. */
+export declare const TUNNEL_STOP_COMMAND = "sudo pkill -f tunnel-creation";
+/**
+ * True when the tunnel registry server answers its HTTP API on `port`. A raw
+ * TCP connect is not enough — an unrelated listener on the port would be
+ * mistaken for the tunnel and surface much later as an opaque XCUITest error.
+ */
+export declare function isTunnelHealthy(port?: number, host?: string, timeoutMs?: number): Promise<boolean>;
+export interface TunnelScriptOptions {
+    appiumHome: string;
+    nodePath: string;
+    appiumBin: string;
+    logFile: string;
+}
+/**
+ * A self-contained shell script that launches the driver's `tunnel-creation` as a
+ * fully detached daemon (own session, via {@link DAEMONIZE_PERL}). Run as root via
+ * the macOS auth prompt; it returns immediately while the tunnel keeps running
+ * (health-checked via the registry port).
+ */
+export declare function buildTunnelScript(opts: TunnelScriptOptions): string;
+/** Prompt for admin rights (password/Touch ID) and run the tunnel script as root. */
+export type Elevator = (scriptPath: string) => Promise<void>;
+export interface EnsureIosTunnelOptions {
+    port?: number;
+    appiumHome?: string;
+    nodePath?: string;
+    appiumBin?: string;
+    /** Directory for the generated tunnel script + log (defaults to $AXIMO_HOME/ios-tunnel). */
+    dir?: string;
+    elevate?: Elevator;
+    isHealthy?: (port: number) => Promise<boolean>;
+    writeScript?: (path: string, content: string, dir: string) => void;
+    readyTimeoutMs?: number;
+    log?: (message: string) => void;
+    env?: NodeJS.ProcessEnv;
+}
+export interface EnsureIosTunnelResult {
+    reused: boolean;
+    started: boolean;
+    skipped: boolean;
+    port: number;
+}
+/**
+ * Ensure the RemoteXPC tunnel is running so XCUITest can reach WebDriverAgent.
+ * Reuses an already-running tunnel (no prompt); otherwise elevates once via the
+ * macOS auth dialog to start it. No-op when AXIMO_IOS_SKIP_TUNNEL is set.
+ */
+export declare function ensureIosTunnel(options?: EnsureIosTunnelOptions): Promise<EnsureIosTunnelResult>;