Run a virtual iPhone on an Apple Silicon Mac.
Swift
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)
}