Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
23.9 KB
Raw Blame
import Foundation

// MARK: - Errors

public enum VPhoneManifestError: Error {
    case loadFailed(path: String)
    case parseFailed(path: String)
    case unsupportedSchema(path: String, found: Int?)
    case unsupportedRuntimeVersion(String)
    case writeFailed(path: String)
    /// A file name in the manifest is not one plain name inside the VM folder.
    case invalidPath(path: String, field: String)
    /// A VM file exists but is a symbolic link or not a regular file.
    case notRegularFile(path: String)
}

extension VPhoneManifestError: CustomStringConvertible, LocalizedError {
    public var description: String {
        switch self {
        case let .loadFailed(path):
            "Unable to read the VM configuration at \(path). Check that the file exists and try again."
        case let .parseFailed(path):
            "The VM configuration at \(path) is not valid. Recreate the VM, or restore a backup of config.plist."
        case let .unsupportedSchema(path, found):
            "The VM configuration at \(path) has \(found.map { "schema version \($0)" } ?? "no valid schema version"). vphone 2.x requires schema version 2. Recreate this VM with `vphone-cli vm create`."
        case let .unsupportedRuntimeVersion(version):
            "This vphone build is version \(version). VMs with schema version 2 require vphone 2.x. Install vphone 2.x before launching this VM."
        case let .writeFailed(path):
            "Unable to save the VM configuration to \(path). Check that the file is writable and try again."
        case let .invalidPath(path, field):
            "The VM configuration at \(path) has an invalid \(field). It must be a single file name inside the VM folder. Recreate the VM, or restore a backup of config.plist."
        case let .notRegularFile(path):
            "\(path) is a symbolic link or not a regular file. VM files must be regular files inside the VM folder. Recreate the VM, or restore the file from a backup."
        }
    }

    public var errorDescription: String? {
        description
    }
}

enum VPhoneRuntimeVersion {
    /// A plain `swift build` executable has no app bundle Info.plist.
    private static let unbundledVersion = "2.2.0"

    static var current: String {
        let contents = VPhoneResources.runningExecutable().deletingLastPathComponent().deletingLastPathComponent()
        guard contents.lastPathComponent == "Contents",
              contents.deletingLastPathComponent().pathExtension == "app"
        else { return unbundledVersion }

        let infoURL = contents.appendingPathComponent("Info.plist")
        guard let data = try? Data(contentsOf: infoURL),
              let plist = (try? PropertyListSerialization.propertyList(from: data, format: nil)) as? [String: Any],
              let version = plist["CFBundleShortVersionString"] as? String
        else { return "unknown" }
        return version
    }

    static func requireVersion2() throws {
        let parts = current.split(separator: ".", omittingEmptySubsequences: false)
        guard parts.count >= 2, parts[0] == "2", parts.dropFirst().allSatisfy({ Int($0) != nil }) else {
            throw VPhoneManifestError.unsupportedRuntimeVersion(current)
        }
    }
}

/// VPhoneVirtualMachineManifest represents the on-disk VM configuration manifest.
/// Structure extends security-pcc's VMBundle.Config format with a vphone schema marker.
public struct VPhoneVirtualMachineManifest: Codable, Sendable {
    public static let currentSchemaVersion = 2

    /// The VM layout version. Old bundles without this marker cannot be booted.
    public let schemaVersion: Int

    // MARK: - Platform

    /// Platform type (fixed to vresearch101 for vphone)
    public let platformType: PlatformType

    /// Platform fusing mode (prod/dev) - determined by host OS capabilities
    public let platformFusing: PlatformFusing?

    /// Machine identifier (opaque ECID representation)
    public let machineIdentifier: Data

    // MARK: - Hardware

    /// CPU core count
    public let cpuCount: UInt

    /// Memory size in bytes
    public let memorySize: UInt64

    /// Missing in older manifests, which keep the original USB keyboard.
    public let hardwareKeyboardEnabled: Bool?

    public var usesHardwareKeyboard: Bool {
        hardwareKeyboardEnabled ?? true
    }

    // MARK: - Startup

    /// Whether vphone-vm wakes the guest and dismisses its Lock Screen each
    /// time it connects to a freshly started vphoned. Missing in older
    /// manifests, which leave the guest at the Lock Screen.
    public let unlocksAtStartup: Bool?

    public var unlocksScreenAtStartup: Bool {
        unlocksAtStartup ?? false
    }

    /// Whether vphone-vm forwards the Mac's location to the guest while it
    /// runs. Missing in older manifests, which keep the Mac's location to
    /// itself.
    public let syncsHostLocation: Bool?

    public var sharesHostLocation: Bool {
        syncsHostLocation ?? false
    }

    // MARK: - Display

    /// Screen configuration
    public let screenConfig: ScreenConfig

    // MARK: - Network

    /// Network configuration (NAT mode for vphone)
    public let networkConfig: NetworkConfig

    // MARK: - Storage

    /// Disk image filename
    public let diskImage: String

    /// NVRAM storage filename
    public let nvramStorage: String

    // MARK: - ROMs

    /// ROM image paths
    public let romImages: ROMImages?

    // MARK: - SEP

    /// SEP storage filename
    public let sepStorage: String

    // MARK: - Guest Device

    /// Product type of the device whose IPSW supplied the guest OS, as
    /// `fw prepare` found it. Absent for an iPhone17,3 guest and for every VM
    /// made before iPad guests existed.
    public let guestProductType: String?

    /// The guest device `fw patch` presents in the device tree.
    public var guestDevice: VPhoneGuestDevice {
        VPhoneGuestDevice.named(guestProductType) ?? .default
    }

    // MARK: - Nested Types

    public enum PlatformType: String, Codable, Sendable {
        case vresearch101
    }

    public enum PlatformFusing: String, Codable, Sendable {
        case prod
        case dev
    }

    public struct ScreenConfig: Codable, Equatable, Sendable {
        public let width: Int
        public let height: Int
        public let pixelsPerInch: Int
        public let scale: Double

        public static let `default` = ScreenConfig(
            width: 1290,
            height: 2796,
            pixelsPerInch: 460,
            scale: 3.0,
        )

        public init(width: Int, height: Int, pixelsPerInch: Int, scale: Double) {
            self.width = width
            self.height = height
            self.pixelsPerInch = pixelsPerInch
            self.scale = scale
        }
    }

    public struct NetworkConfig: Codable, Equatable, Sendable {
        public let mode: NetworkMode
        /// The guest NIC's MAC, `aa:bb:cc:dd:ee:ff`. Empty until first boot
        /// generates one and saves it here, so the guest keeps one identity
        /// (and one DHCP lease) across launches.
        public let macAddress: String
        /// Host interface identifier to bridge (bridged mode only); nil otherwise.
        public let bridgeInterface: String?
        /// A fixed guest address; nil leaves the address to DHCP. How each mode
        /// realizes it is in `VPhoneNetworking.plan`.
        public let ipv4: IPv4Config?
        /// Host ports carried into the guest. Nil and empty both forward nothing.
        public let portForwards: [PortForward]?
        /// The name the guest answers to as `<name>.local` over mDNS. Nil, the
        /// default, leaves the guest's own name alone.
        public let localHostName: String?
        /// Whether the guest resolves this Mac's `.local` name to the address it
        /// reaches the Mac at, through a record vphoned registers with the
        /// guest's mDNSResponder. Nil means yes; see `VPhoneNetworking.plan`.
        public let resolvesMacName: Bool?
        /// Whether, in `nat`, the guest reaches the other machines on the Mac's
        /// shared network and they reach it, as a watch and the phone it pairs
        /// with must. Nil means yes, except for a fixed address on the first
        /// shared network, set before this existed; false keeps vmnet's
        /// isolation, where each guest reaches only the Mac and beyond.
        public let reachesPeers: Bool?

        public enum NetworkMode: String, Codable, Sendable {
            case nat
            case bridged
            case hostOnly
            /// The guest's NIC is carried by this process. Egress leaves through
            /// ordinary host sockets, so it follows the host's routing table —
            /// and therefore a VPN — which vmnet's `nat` cannot do because its
            /// masquerade is pinned to a physical interface.
            case tunnel
            /// No network device. Named `off` (not `none`) so a `NetworkMode?`
            /// literal `.none` can't silently bind to `Optional.none`.
            case off = "none"
        }

        public static let `default` = NetworkConfig(mode: .nat, macAddress: "")

        public init(
            mode: NetworkMode,
            macAddress: String,
            bridgeInterface: String? = nil,
            ipv4: IPv4Config? = nil,
            portForwards: [PortForward]? = nil,
            localHostName: String? = nil,
            resolvesMacName: Bool? = nil,
            reachesPeers: Bool? = nil,
        ) {
            self.mode = mode
            self.macAddress = macAddress
            self.bridgeInterface = bridgeInterface
            self.ipv4 = ipv4
            self.portForwards = portForwards
            self.localHostName = localHostName
            self.resolvesMacName = resolvesMacName
            self.reachesPeers = reachesPeers
        }

        /// The same configuration with one field replaced.
        public func with(
            mode: NetworkMode? = nil,
            macAddress: String? = nil,
            bridgeInterface: String?? = nil,
            ipv4: IPv4Config?? = nil,
            portForwards: [PortForward]?? = nil,
            localHostName: String?? = nil,
            resolvesMacName: Bool?? = nil,
            reachesPeers: Bool?? = nil,
        ) -> NetworkConfig {
            NetworkConfig(
                mode: mode ?? self.mode,
                macAddress: macAddress ?? self.macAddress,
                bridgeInterface: bridgeInterface ?? self.bridgeInterface,
                ipv4: ipv4 ?? self.ipv4,
                portForwards: portForwards ?? self.portForwards,
                localHostName: localHostName ?? self.localHostName,
                resolvesMacName: resolvesMacName ?? self.resolvesMacName,
                reachesPeers: reachesPeers ?? self.reachesPeers,
            )
        }

        /// A fixed IPv4 configuration for the guest's NIC.
        ///
        /// Addresses are kept as dotted strings so `config.plist` stays readable
        /// and editable by hand. `VPhoneNetworking.validate` is what gives them
        /// meaning, and it runs both when the config is edited and at boot.
        public struct IPv4Config: Codable, Equatable, Sendable {
            public let address: String
            public let prefixLength: Int
            /// The default route. Nil means the first host of the subnet, which
            /// is where `nat` and `tunnel` put the host.
            public let router: String?
            /// Resolvers handed to the guest. Nil or empty means the router.
            public let dns: [String]?

            public init(address: String, prefixLength: Int, router: String? = nil, dns: [String]? = nil) {
                self.address = address
                self.prefixLength = prefixLength
                self.router = router
                self.dns = dns
            }
        }

        /// One host port carried to a guest port.
        public struct PortForward: Codable, Equatable, Hashable, Sendable, CustomStringConvertible {
            public enum TransportProtocol: String, Codable, Sendable, CaseIterable {
                case tcp
                case udp
            }

            public let transport: TransportProtocol
            /// The host address to listen on. Nil is loopback only, so a guest
            /// service is not on the LAN unless someone asks for that.
            public let hostAddress: String?
            public let hostPort: Int
            public let guestPort: Int

            private enum CodingKeys: String, CodingKey {
                case transport = "protocol"
                case hostAddress, hostPort, guestPort
            }

            public init(transport: TransportProtocol = .tcp, hostAddress: String? = nil, hostPort: Int, guestPort: Int) {
                self.transport = transport
                self.hostAddress = hostAddress
                self.hostPort = hostPort
                self.guestPort = guestPort
            }

            /// The address actually listened on.
            public var listenAddress: String {
                hostAddress ?? "127.0.0.1"
            }

            /// `tcp:127.0.0.1:8022:22`, the form `--forward` accepts.
            public var description: String {
                "\(transport.rawValue):\(listenAddress):\(hostPort):\(guestPort)"
            }
        }
    }

    public struct ROMImages: Codable, Sendable {
        public let avpBooter: String
        public let avpSEPBooter: String

        /// The names `vm create` copies the ROMs in as.
        public static let `default` = ROMImages(
            avpBooter: "AVPBooter.vresearch1.bin",
            avpSEPBooter: "AVPSEPBooter.vresearch1.bin",
        )

        public init(avpBooter: String, avpSEPBooter: String) {
            self.avpBooter = avpBooter
            self.avpSEPBooter = avpSEPBooter
        }
    }

    // MARK: - Init from VM creation parameters

    public init(
        platformType: PlatformType = .vresearch101,
        platformFusing: PlatformFusing? = nil,
        machineIdentifier: Data = Data(),
        cpuCount: UInt,
        memorySize: UInt64,
        screenConfig: ScreenConfig = .default,
        networkConfig: NetworkConfig = .default,
        diskImage: String = "Disk.img",
        nvramStorage: String = "nvram.bin",
        romImages: ROMImages?,
        sepStorage: String = "SEPStorage",
        guestProductType: String? = nil,
        hardwareKeyboardEnabled: Bool? = nil,
        unlocksAtStartup: Bool? = nil,
        syncsHostLocation: Bool? = nil,
    ) {
        schemaVersion = Self.currentSchemaVersion
        self.platformType = platformType
        self.platformFusing = platformFusing
        self.machineIdentifier = machineIdentifier
        self.cpuCount = cpuCount
        self.memorySize = memorySize
        self.screenConfig = screenConfig
        self.networkConfig = networkConfig
        self.diskImage = diskImage
        self.nvramStorage = nvramStorage
        self.romImages = romImages
        self.sepStorage = sepStorage
        self.guestProductType = guestProductType
        self.hardwareKeyboardEnabled = hardwareKeyboardEnabled
        self.unlocksAtStartup = unlocksAtStartup
        self.syncsHostLocation = syncsHostLocation
    }

    // MARK: - Creation

    /// The manifest a freshly created VM starts with.
    ///
    /// Replaces `scripts/vm_manifest.py`. Everything not named here is a
    /// default that the guest or the framework fills in later:
    /// `machineIdentifier` and `macAddress` are empty until first boot
    /// generates and persists them.
    ///
    /// `platformFusing` stays nil unless asked for, which leaves the key out
    /// of the plist entirely and lets the host OS decide.
    public static func newVM(
        cpuCount: UInt = 8,
        memoryMB: UInt64 = 8192,
        platformFusing: PlatformFusing? = nil,
    ) -> VPhoneVirtualMachineManifest {
        VPhoneVirtualMachineManifest(
            platformFusing: platformFusing,
            cpuCount: cpuCount,
            memorySize: memoryMB * 1024 * 1024,
            romImages: .default,
        )
    }

    // MARK: - Load/Save

    /// Load manifest from a plist file
    public static func load(from url: URL) throws -> VPhoneVirtualMachineManifest {
        let data: Data
        do {
            data = try Data(contentsOf: url, options: .mappedIfSafe)
        } catch {
            throw VPhoneManifestError.loadFailed(path: url.path)
        }

        let decoder = PropertyListDecoder()
        struct SchemaMarker: Decodable { let schemaVersion: Int? }
        let marker = try? decoder.decode(SchemaMarker.self, from: data)
        guard marker?.schemaVersion == Self.currentSchemaVersion else {
            throw VPhoneManifestError.unsupportedSchema(path: url.path, found: marker?.schemaVersion)
        }
        try VPhoneRuntimeVersion.requireVersion2()
        let manifest: VPhoneVirtualMachineManifest
        do {
            manifest = try decoder.decode(VPhoneVirtualMachineManifest.self, from: data)
        } catch {
            throw VPhoneManifestError.parseFailed(path: url.path)
        }
        try manifest.validateFileNames(configPath: url.path)
        return manifest
    }

    /// Save manifest to a plist file.
    ///
    /// Atomic, so a config.plist that is a symbolic link is replaced by a new
    /// file rather than written through to wherever it points.
    public func write(to url: URL) throws {
        let encoder = PropertyListEncoder()
        encoder.outputFormat = .xml

        do {
            let data = try encoder.encode(self)
            try data.write(to: url, options: .atomic)
        } catch {
            throw VPhoneManifestError.writeFailed(path: url.path)
        }
    }

    // MARK: - File Names

    /// Whether `name` is one plain entry in a directory: not empty, not `.` or
    /// `..`, no `/`, no NUL, and within NAME_MAX bytes.
    public static func isPlainFileName(_ name: String) -> Bool {
        !name.isEmpty
            && name != "."
            && name != ".."
            && !name.contains("/")
            && !name.contains("\0")
            && name.utf8.count <= 255
    }

    /// The bundle files this manifest names, keyed by their plist field.
    public var bundleFileNames: [(field: String, name: String)] {
        var names = [
            (field: "diskImage", name: diskImage),
            (field: "nvramStorage", name: nvramStorage),
            (field: "sepStorage", name: sepStorage),
        ]
        if let romImages {
            names.append((field: "romImages.avpBooter", name: romImages.avpBooter))
            names.append((field: "romImages.avpSEPBooter", name: romImages.avpSEPBooter))
        }
        return names
    }

    /// Every file the manifest names must sit directly in the VM folder. An
    /// imported config.plist is untrusted, and vphone-vm overwrites the NVRAM
    /// file and attaches the disk read-write, so a `../` name would reach any
    /// file the user can write.
    func validateFileNames(configPath: String) throws {
        for (field, name) in bundleFileNames where !Self.isPlainFileName(name) {
            throw VPhoneManifestError.invalidPath(path: configPath, field: field)
        }
    }

    // MARK: - Convenience

    /// Resolve a manifest file name to its URL directly inside the VM directory.
    ///
    /// `load(from:)` already rejects names that are not plain; this refuses
    /// them again so no caller can reach outside the bundle with a manifest
    /// built some other way.
    public func resolve(path: String, in vmDirectory: URL) throws -> URL {
        let configPath = vmDirectory.appendingPathComponent("config.plist").path
        guard Self.isPlainFileName(path) else {
            throw VPhoneManifestError.invalidPath(path: configPath, field: "file name \"\(path)\"")
        }
        let url = vmDirectory.appendingPathComponent(path, isDirectory: false)
        guard url.deletingLastPathComponent().standardizedFileURL.path
            == vmDirectory.standardizedFileURL.path
        else {
            throw VPhoneManifestError.invalidPath(path: configPath, field: "file name \"\(path)\"")
        }
        return url
    }

    // MARK: - Bundle Files

    /// What `lstat` finds at a VM file's path. A symbolic link is never
    /// followed, so it counts as `.other`.
    public enum FileKind: Sendable {
        case missing
        case regularFile
        case other
    }

    public static func fileKind(at url: URL) -> FileKind {
        var info = stat()
        guard lstat(url.path, &info) == 0 else {
            return errno == ENOENT ? .missing : .other
        }
        return info.st_mode & S_IFMT == S_IFREG ? .regularFile : .other
    }

    /// Throws unless the entry at `url` is missing or a regular file, and
    /// returns whether it exists. Checked before a VM file is handed to
    /// Virtualization, which opens, creates and overwrites through symbolic
    /// links.
    @discardableResult
    public static func requireRegularFileIfPresent(at url: URL) throws -> Bool {
        switch fileKind(at: url) {
        case .missing: false
        case .regularFile: true
        case .other: throw VPhoneManifestError.notRegularFile(path: url.path)
        }
    }

    // MARK: - Editing

    public func updating(
        cpuCount: UInt? = nil,
        memorySize: UInt64? = nil,
        machineIdentifier: Data? = nil,
        networkConfig: NetworkConfig? = nil,
        hardwareKeyboardEnabled: Bool? = nil,
        unlocksAtStartup: Bool? = nil,
        syncsHostLocation: Bool? = nil,
    ) -> VPhoneVirtualMachineManifest {
        VPhoneVirtualMachineManifest(
            platformType: platformType,
            platformFusing: platformFusing,
            machineIdentifier: machineIdentifier ?? self.machineIdentifier,
            cpuCount: cpuCount ?? self.cpuCount,
            memorySize: memorySize ?? self.memorySize,
            screenConfig: screenConfig,
            networkConfig: networkConfig ?? self.networkConfig,
            diskImage: diskImage,
            nvramStorage: nvramStorage,
            romImages: romImages,
            sepStorage: sepStorage,
            guestProductType: guestProductType,
            hardwareKeyboardEnabled: hardwareKeyboardEnabled ?? self.hardwareKeyboardEnabled,
            unlocksAtStartup: unlocksAtStartup ?? self.unlocksAtStartup,
            syncsHostLocation: syncsHostLocation ?? self.syncsHostLocation,
        )
    }

    /// This manifest with other ROM file names.
    public func updating(romImages: ROMImages) -> VPhoneVirtualMachineManifest {
        VPhoneVirtualMachineManifest(
            platformType: platformType,
            platformFusing: platformFusing,
            machineIdentifier: machineIdentifier,
            cpuCount: cpuCount,
            memorySize: memorySize,
            screenConfig: screenConfig,
            networkConfig: networkConfig,
            diskImage: diskImage,
            nvramStorage: nvramStorage,
            romImages: romImages,
            sepStorage: sepStorage,
            guestProductType: guestProductType,
            hardwareKeyboardEnabled: hardwareKeyboardEnabled,
            unlocksAtStartup: unlocksAtStartup,
            syncsHostLocation: syncsHostLocation,
        )
    }

    /// This manifest for a guest running `device`'s OS: its product type and
    /// its display. An iPhone17,3 guest records no product type, so its
    /// configuration stays readable by bundles that predate iPad guests.
    public func updating(guestDevice device: VPhoneGuestDevice) -> VPhoneVirtualMachineManifest {
        VPhoneVirtualMachineManifest(
            platformType: platformType,
            platformFusing: platformFusing,
            machineIdentifier: machineIdentifier,
            cpuCount: cpuCount,
            memorySize: memorySize,
            screenConfig: device.screen,
            networkConfig: networkConfig,
            diskImage: diskImage,
            nvramStorage: nvramStorage,
            romImages: romImages,
            sepStorage: sepStorage,
            guestProductType: device == .default ? nil : device.productType,
            hardwareKeyboardEnabled: hardwareKeyboardEnabled,
            unlocksAtStartup: unlocksAtStartup,
            syncsHostLocation: syncsHostLocation,
        )
    }
}