Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
30.8 KB
Raw Blame
import CoreLocation
import CryptoKit
import Darwin
import Foundation
import IcliKit
import IcliSystem
import UIKit
import VphonedNative

enum GuestAPIError: Error, CustomStringConvertible {
    case invalidRequest(String)
    case unsupportedMethod(String)
    case operationFailed(String)
    /// The request would repeat work the guest has already done. The code is
    /// sent as the error code so a client can tell it apart from a failure.
    case alreadyDone(code: String, message: String)
    /// The guest's Location Services switch is off, so locationd gives no
    /// client a location. vphoned leaves the switch to the guest's Settings.
    case locationServicesOff

    var description: String {
        switch self {
        case let .invalidRequest(message), let .operationFailed(message): message
        case let .unsupportedMethod(method): "Unknown method: \(method)"
        case let .alreadyDone(_, message): message
        case .locationServicesOff:
            "Location Services are turned off in the guest. Turn them on in Settings > Privacy & Security > Location Services."
        }
    }

    var code: String {
        if case let .alreadyDone(code, _) = self {
            return code
        }
        if case .locationServicesOff = self {
            return "location_services_off"
        }
        return "invalid_operation"
    }
}

/// The API boundary is deliberately small: named operations and JSON values.
/// IcliKit owns general device work, including app installation and Keychain
/// metadata. vphone signs app code before IcliKit installs it.
enum GuestAPI {
    /// Each request executes independently. A synchronous system service such
    /// as powerd may wait during boot; it must not hold up HID or file requests.
    static let queue = DispatchQueue(
        label: "vphoned.api.operations", qos: .userInitiated,
        attributes: .concurrent,
    )
    static let binaryHash: String = {
        guard let url = Bundle.main.executableURL,
              let data = try? Data(contentsOf: url, options: .mappedIfSafe)
        else { return "unknown" }
        return sha256Hex(data)
    }()

    /// New each time vphoned starts: after a guest boot, a userspace reboot, an
    /// update or a crash. A host tells a vphoned that just started from a
    /// connection it lost and found again by this, not by reconnecting.
    static let instance = UUID().uuidString

    static func sha256Hex(_ data: Data) -> String {
        SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
    }

    /// The address the host shows for the guest, from icli's
    /// `"<interface> <address>"` strings: the NIC's (`en0`) IPv4 address,
    /// which is where the host forwards ports to, then a 192.x IPv4 address
    /// (the NAT network), then any other routable IPv4, then a routable IPv6.
    /// Loopback and link-local addresses, which sort first, never qualify.
    static func preferredAddress(_ addresses: [String]) -> String? {
        func routableIPv4(_ host: String) -> Bool {
            !host.contains(":") && !host.hasPrefix("127.") && !host.hasPrefix("169.254.")
        }
        let entries = addresses.map { $0.split(separator: " ", maxSplits: 1).map(String.init) }
        let nic = entries.first { $0.count == 2 && $0[0] == "en0" && routableIPv4($0[1]) }?[1]
        let hosts = entries.compactMap(\.last)
        let ipv4 = hosts.filter(routableIPv4)
        let ipv6 = hosts.filter { $0.contains(":") && $0 != "::1" && !$0.contains("%") && !$0.hasPrefix("fe80:") }
        return nic ?? ipv4.first { $0.hasPrefix("192.") } ?? ipv4.first ?? ipv6.first
    }

    static func health() -> [String: Any] {
        let ip = preferredAddress(networkInfo()["addresses"] as? [String] ?? [])
        let version = ProcessInfo.processInfo.operatingSystemVersion
        return [
            "name": "vphoned",
            "api_version": 1,
            "status": "ok",
            "binary_hash": binaryHash,
            "instance": instance,
            "ios": "\(version.majorVersion).\(version.minorVersion).\(version.patchVersion)",
            "ip": ip ?? "",
            "setup_pending": setupAssistantPending(),
            "mobilegestalt_restart_pending": GuestMobileGestaltCache.restartPending(),
            "capabilities": [
                "touch",
                "touch2",
                "touch_edge",
                "hid",
                "apps",
                "ota_system_apps",
                "url",
                "files",
                "clipboard",
                "location",
                "keychain",
                "keychain_edit",
                "ipa_install",
                "bootstrap_install",
                "bootstrap_packages",
                "bootstrap_uninstall",
                "port_forward",
                "camera",
                "screenshot",
                "device_info",
                "display",
                "display_orientation",
                "display_auto_lock",
                "device_pose",
                "screen_unlock",
                "audio",
                "input_gestures",
                "ui_inspection",
                "processes",
                "services",
                "service_profile",
                "service_kickstart",
                "logs",
                "network_capture",
                "app_details",
                "system_app_removal",
                "system_control",
                "system_shutdown",
                "file_tools",
                "apfs_snapshots",
                "files_app_drop",
                "packages",
                "environment_update",
                "udid_override",
                "setup_skip",
                "setup_settle",
                "network_ipv4",
                "network_hostname",
                "device_name",
                "network_static_names",
                "network_resolve",
                "timezone",
                "clock",
                "audio_host_latency",
                "motion_gyroscope",
                "motion_gyroscope_toggle",
                "motion_attitude",
            ] + pointerCapabilities() + scriptCapabilities() + GuestHomePodDisplay.capabilities
                + GuestHomePodDebug.capabilities + GuestHomeViewDistance.capabilities,
        ]
    }

    /// iPadOS accepts a pointing device directly. iPhones normally need
    /// AssistiveTouch, but may explicitly opt in to host pointer forwarding.
    /// Advertising the transport does not promise that iOS consumes it.
    private static func pointerCapabilities() -> [String] {
        let machine = GuestVirtualAudioProduct.machine()
        if machine.hasPrefix("iPad") { return ["pointer_scroll", "pointer_buttons"] }
        guard machine.hasPrefix("iPhone"),
              let preference = try? readPreference(domain: "com.vphone.vphoned", key: "iPhonePointerEnabled"),
              preference["type"] as? String == "bool",
              preference["value"] as? Bool == true
        else { return [] }
        return ["pointer_scroll", "pointer_buttons"]
    }

    static func execute(method: String, params: [String: Any]) throws -> [String: Any] {
        switch method {
        case "device.snapshot":
            var snapshot = try collectDeviceSnapshot()
            snapshot["jailbreak"] = jailbreakInfo()
            return snapshot
        case "device.screen":
            return screenInfo()
        case "screen.screenshot":
            return try takeScreenshot(base64: true, nativeResolution: true)
        case "apps.list":
            let filter = params["filter"] as? String ?? "all"
            let apps = try listedApps()
            let running = try runningApps()["apps"] as? [[String: Any]] ?? []
            let pids = Dictionary(
                uniqueKeysWithValues: running.compactMap { app -> (String, Int)? in
                    guard let id = app["bundle_id"] as? String, let pid = app["pid"] as? Int else { return nil }
                    return (id, pid)
                },
            )
            return [
                "apps": apps.compactMap { app -> [String: Any]? in
                    var info = app
                    guard let id = app["bundle_id"] as? String, !id.isEmpty else { return nil }
                    let pid = pids[id] ?? 0
                    let path = app["bundle_path"] as? String ?? ""
                    let type: String =
                        if let registeredType = (app["type"] as? String)?.lowercased(),
                        registeredType == "system" || registeredType == "user" {
                            registeredType
                        } else {
                            path.hasPrefix("/System/") || id.hasPrefix("com.apple.") ? "system" : "user"
                        }
                    if filter == "running" && pid == 0 {
                        return nil
                    }
                    if filter == "user" && type != "user" {
                        return nil
                    }
                    if filter == "system" && type != "system" {
                        return nil
                    }
                    info["pid"] = pid
                    info["type"] = type
                    info["state"] = pid > 0 ? "running" : "not_running"
                    info["path"] = path
                    info["version"] = app["version"] ?? ""
                    return info
                },
            ]
        case "apps.search":
            return try searchApps(string(params, "query"))
        case "apps.refresh":
            return try refreshAppRegistrations(directory: params["directory"] as? String)
        case "apps.launch":
            let id = try string(params, "bundle_id")
            if let url = params["url"] as? String {
                _ = try openAppURL(url, bundleID: id)
            } else {
                let before = try runningApps()["apps"] as? [[String: Any]] ?? []
                let wasRunning = before.contains { $0["bundle_id"] as? String == id }
                do {
                    _ = try launchApp(id)
                } catch let IcliError.failed(message) where message == "app did not become frontmost: \(id)" {
                    let after = try runningApps()["apps"] as? [[String: Any]] ?? []
                    guard let pid = after.first(where: { $0["bundle_id"] as? String == id })?["pid"] as? Int
                    else { throw IcliError.failed(message) }
                    let front = frontmostApp()
                    if front["verified"] as? Bool == true,
                       front["bundle_id"] as? String == id
                    {
                        return ["pid": pid, "frontmost_verified": true]
                    }
                    guard !wasRunning else { throw IcliError.failed(message) }
                    return [
                        "pid": pid,
                        "frontmost_verified": false,
                        "warning": "App process started, but foreground state could not be confirmed",
                    ]
                }
            }
            let running = try? runningApps()["apps"] as? [[String: Any]]
            let front = frontmostApp()
            return [
                "pid": running?.first(where: { $0["bundle_id"] as? String == id })?["pid"] ?? 0,
                "frontmost_verified": params["url"] == nil
                    && front["verified"] as? Bool == true
                    && front["bundle_id"] as? String == id,
            ]
        case "apps.terminate":
            return try killApp(string(params, "bundle_id"), force: true)
        case "apps.uninstall":
            let id = try string(params, "bundle_id")
            try requireForce(params, "uninstall \(id)")
            return try uninstallApp(id, force: true)
        case "apps.foreground":
            let front = frontmostApp()
            let id = front["bundle_id"] as? String ?? ""
            let apps = try searchApps(id)["apps"] as? [[String: Any]] ?? []
            let running = try runningApps()["apps"] as? [[String: Any]] ?? []
            let name =
                id == "com.apple.springboard"
                    ? "Home Screen"
                    : (apps.first(where: { $0["bundle_id"] as? String == id })?["name"] as? String ?? "")
            return [
                "bundle_id": id,
                "name": name,
                "pid": running.first(where: { $0["bundle_id"] as? String == id })?["pid"] ?? 0,
                "verified": front["verified"] ?? false,
                "source": front["source"] ?? "",
            ]
        case "apps.open_url":
            return try openAppURL(string(params, "url"), bundleID: params["bundle_id"] as? String)
        case "apps.install":
            let path = try string(params, "path")
            let certificate = params["cert_path"] as? String ?? ""
            let registration: AppRegistrationType = params["registration"] as? String == "System" ? .system : .user
            defer {
                try? FileManager.default.removeItem(atPath: path)
                if !certificate.isEmpty {
                    try? FileManager.default.removeItem(atPath: certificate)
                }
            }
            var result = try installIPAInContainer(path, registration: registration) { app in
                try signAppForInstall(app, certificate: certificate)
            }
            let id = result["bundle_id"] as? String ?? "app"
            result["msg"] = "Installed \(id) as a \(registration.rawValue) app."
            return result
        case "bootstrap.install":
            let layout = try string(params, "layout")
            return try GuestIrisinInstaller.install(
                jailbreak: jailbreakInfo(),
                layout: layout,
                packagePath: params["package_path"] as? String,
            )
        case "bootstrap.packages":
            return try GuestIrisinInstaller.installPackages(GuestIrisinInstaller.initialPackages)
        case "bootstrap.status":
            return GuestIrisinInstaller.status()
        case "bootstrap.inspect":
            return try GuestIrisinInstaller.installedBootstrap()
        case "bootstrap.uninstall":
            try requireForce(params, "uninstall the bootstrap")
            let roots = try (params["roots"] as? [String]) ?? [string(params, "jbroot")]
            return try GuestIrisinInstaller.uninstall(
                expectedRoots: roots,
                reboot: params["reboot"] as? Bool ?? true,
            )
        case "bootstrap.firmware":
            return try GuestIrisinInstaller.repairFirmwareRecord()
        case "input.touch":
            guard let phase = (params["phase"] as? String).flatMap(TouchPhase.init(rawValue:)) else {
                throw GuestAPIError.invalidRequest("phase must be down, move or up")
            }
            // A touch that starts at a screen edge needs the digitizer edge
            // flags, which icli does not set; vphoned injects those itself.
            if let edge = params["edge"] as? Int, edge != 0 {
                guard params["normalized"] as? Bool ?? true else {
                    throw GuestAPIError.invalidRequest("edge touch coordinates are normalized 0..1 only")
                }
                vp_hid_touch_edge(touchPhaseCode(phase), number(params, "x"), number(params, "y"), Int32(edge))
                return ["phase": phase.rawValue, "edge": edge]
            }
            return try touch(
                phase, x: number(params, "x"), y: number(params, "y"),
                normalized: params["normalized"] as? Bool ?? true,
            )
        case "input.touch2":
            // Two fingers in one hand event. icli's `input.touch` carries a
            // single digitizer point, so a pinch has to go through vphoned's own
            // injection path (`vp_hid_touch2`) instead.
            guard let phase = (params["phase"] as? String).flatMap(TouchPhase.init(rawValue:)) else {
                throw GuestAPIError.invalidRequest("phase must be down, move or up")
            }
            // `vp_hid_touch2` takes normalized coordinates only. `input.touch`
            // also accepts screen points, so refuse the flag here rather than
            // read points as fractions and put both fingers in the corner.
            guard params["normalized"] as? Bool ?? true else {
                throw GuestAPIError.invalidRequest("touch2 coordinates are normalized 0..1 only")
            }
            vp_hid_touch2(
                touchPhaseCode(phase),
                number(params, "x1"), number(params, "y1"),
                number(params, "x2"), number(params, "y2"),
            )
            return ["phase": phase.rawValue, "fingers": 2]
        case "input.pointer":
            let point: GuestPointerScroll.Point
            let sequence: UInt64
            let buttons: Int32
            do {
                point = try GuestPointerScroll.point(params)
                sequence = try GuestPointerScroll.sequence(params)
                buttons = try GuestPointerScroll.buttons(params)
            } catch {
                throw GuestAPIError.invalidRequest(error.message)
            }
            try movePointer(point, sequence: sequence, buttons: buttons)
            return ["x": point.x, "y": point.y, "buttons": Int(buttons)]
        case "input.scroll":
            let scroll: GuestPointerScroll.Scroll
            do {
                scroll = try GuestPointerScroll.scroll(params)
            } catch {
                throw GuestAPIError.invalidRequest(error.message)
            }
            try scrollPointer(scroll)
            return ["phase": scroll.phase.rawValue]
        case "input.hid":
            let page = try integer(params, "page")
            let usage = try integer(params, "usage")
            if let value = params["long_press"] {
                guard let flag = value as? NSNumber, CFGetTypeID(flag) == CFBooleanGetTypeID() else {
                    throw GuestAPIError.invalidRequest("long_press must be a boolean")
                }
                if flag.boolValue {
                    guard (0...65535).contains(page), (0...65535).contains(usage),
                          let down = params["down"] as? NSNumber, CFGetTypeID(down) == CFBooleanGetTypeID()
                    else { throw GuestAPIError.invalidRequest("long_press requires a boolean down and 16-bit page and usage") }
                    guard vp_hid_keyboard_hold(UInt16(page), UInt16(usage), down.boolValue) else {
                        throw GuestAPIError.operationFailed("HID long-press injection is unavailable")
                    }
                    return ["page": page, "usage": usage, "action": down.boolValue ? "down" : "up", "long_press": true]
                }
            }
            if let down = params["down"] as? Bool {
                return try hidEvent(page: page, usage: usage, down: down)
            }
            return try hidPress(page: page, usage: usage)
        case "location.set":
            guard CLLocationManager.locationServicesEnabled() else { throw GuestAPIError.locationServicesOff }
            return try simulateLocation(
                latitude: number(params, "latitude"),
                longitude: number(params, "longitude"),
                altitude: number(params, "altitude", default: 0),
                horizontalAccuracy: number(params, "horizontal_accuracy", default: 5),
                verticalAccuracy: number(params, "vertical_accuracy", default: 5),
                speed: (params["speed"] as? NSNumber)?.doubleValue,
                course: (params["course"] as? NSNumber)?.doubleValue,
            )
        case "location.clear":
            return try clearSimulatedLocation()
        case "location.current":
            guard CLLocationManager.locationServicesEnabled() else { throw GuestAPIError.locationServicesOff }
            return try currentLocation(timeout: number(params, "timeout", default: 10))
        case "developer_mode.status":
            return try developerModeStatus()
        case "developer_mode.enable":
            return try enableDeveloperMode()
        case "power.low_power_mode":
            if let enabled = params["enabled"] as? Bool {
                return try setLowPowerMode(enabled)
            }
            return try lowPowerMode()
        case "clipboard.get":
            return try clipboardInfo()
        case "clipboard.set":
            return try setClipboard(string(params, "text"))
        case "clipboard.clear":
            #if os(tvOS)
            throw GuestAPIError.operationFailed("tvOS has no system clipboard")
            #else
            guard let pasteboard = UIPasteboard(name: .general, create: false) else {
                throw GuestAPIError.operationFailed("The system clipboard is unavailable")
            }
            pasteboard.items = []
            return try clipboardInfo()
            #endif
        case "files.list":
            return try fileList(string(params, "path"))
        case "files.mkdir":
            return try makeDirectory(string(params, "path"), mode: nil)
        case "files.remove":
            return try removePath(
                string(params, "path"), recursive: params["recursive"] as? Bool ?? false,
                force: true,
            )
        case "files.rename":
            return try movePath(string(params, "from"), to: string(params, "to"))
        case "settings.get":
            return try readPreference(domain: string(params, "domain"), key: params["key"] as? String)
        case "settings.set":
            let rawValue = params["value"] ?? NSNull()
            let type =
                params["type"] as? String
                    ?? (rawValue is Bool
                        ? "bool"
                        : rawValue is NSNumber
                        ? "float"
                        : rawValue is String ? "string" : "json")
            let text: String =
                if type == "json" {
                    try String(data: JSONSerialization.data(withJSONObject: rawValue), encoding: .utf8) ?? ""
                } else {
                    String(describing: rawValue)
                }
            return try writePreference(
                domain: string(params, "domain"),
                key: string(params, "key"),
                value: PreferenceValue(text: text, type: type),
            )
        case "settings.delete":
            return try deletePreference(domain: string(params, "domain"), key: string(params, "key"))
        case "keychain.list":
            return try GuestKeychain.list(className: params["class"] as? String)
        case "keychain.add":
            return try GuestKeychain.add(
                account: string(params, "account"),
                service: string(params, "service"),
                password: string(params, "password"),
            )
        case "keychain.get":
            return try GuestKeychain.get(GuestKeychain.Identity(params))
        case "keychain.update":
            return try GuestKeychain.update(GuestKeychain.Identity(params), value: string(params, "value"))
        case "keychain.delete":
            return try GuestKeychain.delete(GuestKeychain.Identity(params))
        case "agent.apply_update":
            let expected = try string(params, "sha256")
            let cache = "/var/root/Library/Caches/vphoned"
            let next = cache + ".next"
            let data = try Data(contentsOf: URL(fileURLWithPath: next), options: .mappedIfSafe)
            let actual = sha256Hex(data)
            guard actual == expected else { throw GuestAPIError.invalidRequest("The update is damaged. Try again.") }
            guard chmod(next, 0o755) == 0 else {
                throw GuestAPIError.operationFailed("Could not make update executable")
            }
            guard rename(next, cache) == 0 else { throw GuestAPIError.operationFailed("Could not install update") }
            try Data(expected.utf8).write(
                to: URL(fileURLWithPath: "/var/root/Library/Caches/vphoned.api-v2"),
                options: .atomic,
            )
            DispatchQueue.global().asyncAfter(deadline: .now() + 0.5) { exit(0) }
            return ["restarting": true]
        default:
            if let result = try executeExtended(method: method, params: params) {
                return result
            }
            throw GuestAPIError.unsupportedMethod(method)
        }
    }

    private static func signAppForInstall(_ app: String, certificate: String) throws {
        let usableCertificate = FileManager.default.fileExists(atPath: certificate) ? certificate : ""
        let error = app.withCString { appPath in
            if usableCertificate.isEmpty {
                return vp_sign_app_for_install(appPath, nil)
            }
            return usableCertificate.withCString { vp_sign_app_for_install(appPath, $0) }
        }
        if let error {
            defer { free(error) }
            throw GuestAPIError.operationFailed(String(cString: error))
        }
    }

    private static func fileList(_ path: String) throws -> [String: Any] {
        var result = try listDirectory(path)
        let entries = result["entries"] as? [[String: Any]] ?? []
        result["entries"] = entries.compactMap { entry -> [String: Any]? in
            guard let fullPath = entry["path"] as? String else { return nil }
            var metadata = stat()
            guard lstat(fullPath, &metadata) == 0 else { return nil }
            let kind = metadata.st_mode & mode_t(S_IFMT)
            let isLink = kind == mode_t(S_IFLNK)
            var target = stat()
            let targetsDirectory =
                isLink && stat(fullPath, &target) == 0
                    && target.st_mode & mode_t(S_IFMT) == mode_t(S_IFDIR)
            var enriched = entry
            enriched["type"] = isLink ? "link" : kind == mode_t(S_IFDIR) ? "dir" : "file"
            enriched["link_target_dir"] = targetsDirectory
            if kind == mode_t(S_IFDIR) || targetsDirectory,
               let canonicalPath = fullPath.withCString({ realpath($0, nil) })
            {
                enriched["resolved_path"] = String(cString: canonicalPath)
                free(canonicalPath)
            }
            enriched["size"] = metadata.st_size
            enriched["perm"] = String(metadata.st_mode & 0o777, radix: 8)
            enriched["mtime"] = Double(metadata.st_mtimespec.tv_sec)
            return enriched
        }
        return result
    }

    /// The LaunchServices records `apps.list` reports: those with a bundle
    /// identifier. `setup.settle` counts this list, not icli's `count`, which
    /// was one higher than `apps.list` on an iOS 27 guest.
    static func listedApps() throws -> [[String: Any]] {
        try (listApps()["apps"] as? [[String: Any]] ?? []).filter {
            !(($0["bundle_id"] as? String) ?? "").isEmpty
        }
    }

    static func jailbreakInfo() -> [String: Any] {
        func isDirectory(_ path: String) -> Bool {
            var directory: ObjCBool = false
            return FileManager.default.fileExists(atPath: path, isDirectory: &directory) && directory.boolValue
        }

        // The bootstrap vphoned installed itself, by its completion record.
        // The probes below look for a jailbreak's own traces, and a RootHide
        // root vphoned made has none: vphoned is on the system volume, away
        // from any .jbroot link or libroot library, and vphone's SystemHook
        // has no get_jbroot.
        if let installation = try? GuestIrisinInstaller.completedBootstrap(), isDirectory(installation.root) {
            return ["layout": installation.layout, "jbroot": installation.root, "source": "vphoned bootstrap"]
        }

        // A foreign RootHide can expose its root through its injected hook even
        // when vphoned has no adjacent .jbroot or libroot library.
        if let hook = dlopen("systemhook.dylib", RTLD_NOLOAD) {
            defer { dlclose(hook) }
            if let symbol = dlsym(hook, "get_jbroot") {
                typealias GetRoot = @convention(c) () -> UnsafePointer<CChar>?
                if let prefix = unsafeBitCast(symbol, to: GetRoot.self)() {
                    let path = String(cString: prefix)
                    if path.hasPrefix("/"), path != "/", isDirectory(path) {
                        return ["layout": "roothide", "jbroot": path, "source": "systemhook"]
                    }
                }
            }
        }

        let root = JailbreakRoot.current
        if let layout = root.layout, layout != .rootful, isDirectory(root.jbroot) {
            return ["layout": layout.rawValue, "jbroot": root.jbroot, "source": root.source]
        }
        if isDirectory("/var/jb") {
            return ["layout": "rootless", "jbroot": "/var/jb", "source": "filesystem /var/jb"]
        }
        var rootMount = statfs()
        if statfs("/", &rootMount) == 0, rootMount.f_flags & UInt32(MNT_RDONLY) == 0 {
            return ["layout": "rootful", "jbroot": "/", "source": "root mount"]
        }
        return ["layout": NSNull(), "jbroot": NSNull(), "source": "not detected"]
    }

    static func string(_ params: [String: Any], _ key: String) throws -> String {
        guard let value = params[key] as? String, !value.isEmpty else {
            throw GuestAPIError.invalidRequest("\(key) is required")
        }
        return value
    }

    static func integer(_ params: [String: Any], _ key: String) throws -> Int {
        guard let value = params[key] as? NSNumber else {
            throw GuestAPIError.invalidRequest("\(key) must be an integer")
        }
        return value.intValue
    }

    static func number(_ params: [String: Any], _ key: String, default fallback: Double = .nan) -> Double {
        if let value = params[key] as? NSNumber {
            return value.doubleValue
        }
        if let value = params[key] as? String, let number = Double(value) {
            return number
        }
        return fallback
    }

    static func optionalString(_ params: [String: Any], _ key: String) -> String? {
        guard let value = params[key] as? String, !value.isEmpty else { return nil }
        return value
    }

    static func bool(_ params: [String: Any], _ key: String, default fallback: Bool = false) -> Bool {
        (params[key] as? NSNumber)?.boolValue ?? fallback
    }

    static func requiredNumber(_ params: [String: Any], _ key: String) throws -> Double {
        let value = number(params, key)
        guard value.isFinite else { throw GuestAPIError.invalidRequest("\(key) must be a number") }
        return value
    }

    /// Operations that end a process, stop a service, remove an app or restart
    /// the guest run only when the caller says so, so a stray request cannot.
    static func requireForce(_ params: [String: Any], _ action: String) throws {
        guard bool(params, "force") else {
            throw GuestAPIError.invalidRequest("Pass force: true to \(action)")
        }
    }

    /// Digitizer phase codes for vphoned's own multi-finger injection path.
    /// icli keeps its equivalent mapping module-internal, and these are the
    /// values the private digitizer entry points take: 0 down, 1 move, 3 up.
    static func touchPhaseCode(_ phase: TouchPhase) -> Int32 {
        switch phase {
        case .down: 0
        case .move: 1
        case .up: 3
        }
    }
}