Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
6.7 KB
Raw Blame
import Foundation

// MARK: - Identity

/// Names both sides of the privileged helper agree on. The label is also the
/// helper's file name under /Library/PrivilegedHelperTools and the key of the
/// app's SMPrivilegedExecutables entry.
nonisolated enum VPhoneLaunchpadHelperIdentity {
    static let label = "com.vphone.launchpad.helper"
    static let machServiceName = label
    /// Authorization right every privileged verb requires. The helper
    /// writes its rule (an administrator, no shared credential) as root.
    static let privilegedRight = "com.vphone.launchpad.helper.privileged"
}

// MARK: - Helper interface

/// The whole root surface of vphone-launchpad. Every call is a fixed verb with
/// validated arguments; there is deliberately no "run this command" entry.
/// Every verb but `helperVersion` takes `authorization`, the caller's
/// AuthorizationExternalForm, and fails unless it holds
/// `VPhoneLaunchpadHelperIdentity.privilegedRight`.
@objc(VPhoneLaunchpadHelperProtocol)
nonisolated protocol VPhoneLaunchpadHelperProtocol {
    /// CFBundleVersion of the running helper, compared against the copy
    /// embedded in the app to decide whether to bless it again.
    func helperVersion(reply: @escaping @Sendable (String) -> Void)

    /// Copies the archive from `archive` into a root-owned staging directory,
    /// checks it against `sha256`, verifies the bundle's signature, and moves
    /// it into the root-owned bundle store. Replies with an error message, or
    /// nil on success.
    func installBundle(
        authorization: Data,
        version: String,
        archive: FileHandle,
        sha256: String,
        reply: @escaping @Sendable (String?) -> Void,
    )

    /// Removes one version from the bundle store.
    func removeBundle(authorization: Data, version: String, reply: @escaping @Sendable (String?) -> Void)

    /// Allows only the installed bundle's receipt-pinned vphone-vm through
    /// AMFI, using that bundle's vphone-escalator as root.
    func allowVirtualMachine(authorization: Data, bundleVersion: String, reply: @escaping @Sendable (String?) -> Void)

    /// Runs `vphone-cli cfw install` from a store bundle as root, on behalf of
    /// the calling user. Output lines arrive through
    /// `VPhoneLaunchpadHelperClientProtocol` on the connection that made the
    /// request, so the app opens one connection per operation. Replies with
    /// the exit status and an error message when the request was refused
    /// before running.
    ///
    /// One operation per machine at a time; different machines run side by
    /// side, provided each volume they write to keeps enough free space for
    /// every operation already running on it.
    func installCustomFirmware(
        authorization: Data,
        bundleVersion: String,
        machineName: String,
        libraryRoot: String,
        keepArtifacts: Bool,
        reply: @escaping @Sendable (Int32, String?) -> Void,
    )

    /// Runs `vphone-cli fw patch` from a store bundle as root, for a machine
    /// whose recorded preset customises the system before the restore (`minimal`):
    /// merging and resealing the system image needs root. Same output channel
    /// and reply as `installCustomFirmware`, and `cancelCustomFirmware` stops it.
    func patchRestoreImage(
        authorization: Data,
        bundleVersion: String,
        machineName: String,
        libraryRoot: String,
        reply: @escaping @Sendable (Int32, String?) -> Void,
    )

    /// Runs `vphone-cli fw kernelcache --link-only` from a store bundle as root:
    /// links the kernelcache mix the user staged for a machine on a cloudOS
    /// without vphone600 components. kmutil reads only kexts root owns; the
    /// child copies the stage into a directory of its own first and runs no
    /// ipsw. Same output channel and reply as `installCustomFirmware`.
    func linkKernelcache(
        authorization: Data,
        bundleVersion: String,
        machineName: String,
        libraryRoot: String,
        reply: @escaping @Sendable (Int32, String?) -> Void,
    )

    /// Runs `vphone-cli cfw update-environment` from a store bundle as root:
    /// redeploys the bundle's guest resources into a stopped machine and
    /// nothing else. Same output channel and reply as `installCustomFirmware`,
    /// and `cancelCustomFirmware` stops it.
    func updateGuestEnvironment(
        authorization: Data,
        bundleVersion: String,
        machineName: String,
        libraryRoot: String,
        reply: @escaping @Sendable (Int32, String?) -> Void,
    )

    /// Runs `vphone-cli cfw update-kernel` from a store bundle as root: swaps
    /// the Preboot kernelcache for the re-patched one and nothing else, keeping
    /// the guest's data. Same output channel and reply as `installCustomFirmware`,
    /// and `cancelCustomFirmware` stops it.
    func updateKernel(
        authorization: Data,
        bundleVersion: String,
        machineName: String,
        libraryRoot: String,
        reply: @escaping @Sendable (Int32, String?) -> Void,
    )

    /// Runs `vphone-cli vm leases --release-orphans --json` from a store
    /// bundle as root, against the machines of `libraryRoots`, each of which
    /// the caller must own. It removes the DHCP leases on the shared NAT
    /// network that iOS guests left behind with a MAC no machine has. Replies
    /// with the command's JSON output, or with an error message.
    func releaseOrphanedLeases(
        authorization: Data,
        bundleVersion: String,
        libraryRoots: [String],
        reply: @escaping @Sendable (String?, String?) -> Void,
    )

    /// Sends SIGINT to the CFW install, environment update or kernel update
    /// running on one machine, when the same user started it. It needs no
    /// authorization: it can only stop the caller's own operation.
    func cancelCustomFirmware(
        machineName: String,
        libraryRoot: String,
        reply: @escaping @Sendable () -> Void,
    )

    /// Removes the helper's launchd job and binary, then exits.
    func uninstallHelper(authorization: Data, reply: @escaping @Sendable (String?) -> Void)
}

// MARK: - Client interface

/// Exported by the app so the helper can stream command output back.
@objc(VPhoneLaunchpadHelperClientProtocol)
nonisolated protocol VPhoneLaunchpadHelperClientProtocol {
    func helperDidEmit(line: String)

    /// Replies once every line sent before it has been handled. The helper
    /// waits for this before it replies to the request that produced them:
    /// XPC orders the helper's own messages, but a request's reply can reach
    /// the app ahead of lines still queued, and the app stops listening for
    /// lines when the reply arrives.
    func helperDidFinishOutput(reply: @escaping @Sendable () -> Void)
}