Run a virtual iPhone on an Apple Silicon Mac.
Swift
import Foundation
/// iOS-userland and cloudOS-kernel versions a bundle was restored with, recorded
/// host-side so they're readable without booting the VM. Persisted as
/// `restore-info.json` at the bundle root and rewritten on every restore.
public struct VPhoneRestoreInfo: Codable, Equatable, Sendable {
public struct OSVersion: Codable, Equatable, Sendable {
public let version: String
public let build: String
public init(version: String, build: String) {
self.version = version
self.build = build
}
}
public let ios: OSVersion
public let cloudOS: OSVersion
public let variant: String?
public let device: String?
public init(ios: OSVersion, cloudOS: OSVersion, variant: String? = nil, device: String? = nil) {
self.ios = ios
self.cloudOS = cloudOS
self.variant = variant
self.device = device
}
static let fileName = "restore-info.json"
private static let baseDevice = "iPhone99,11"
private static let experimentalDevice = "iPhone17,3"
/// Only `exp` rewrites the DeviceTree identity; others keep the base type.
public static func device(forVariant variant: String) -> String {
variant == "exp" ? experimentalDevice : baseDevice
}
public static func url(forBundle bundle: VPhoneBundle) -> URL {
bundle.url.appendingPathComponent(fileName)
}
/// The `restore-info.json` snapshot if present, else derived live from the
/// bundle's restore-directory plists — so bundles restored before this file
/// existed still report their versions. `nil` when neither is available.
/// A snapshot that is a symbolic link or not a regular file is ignored.
public static func load(fromBundle bundle: VPhoneBundle) -> VPhoneRestoreInfo? {
if let directory = readableDirectory(of: bundle),
let data = try? directory.readData(fileName),
let info = try? JSONDecoder().decode(VPhoneRestoreInfo.self, from: data)
{
return info
}
return derive(fromBundle: bundle)
}
/// Read both versions from the bundle's `iPhone*_Restore` plists:
/// `iPhone-BuildManifest.plist` (iOS userland) and the hybrid
/// `BuildManifest.plist` (cloudOS kernel). `nil` if the restore directory or
/// either version is missing.
public static func derive(fromBundle bundle: VPhoneBundle) -> VPhoneRestoreInfo? {
guard let directory = readableDirectory(of: bundle),
let name = findRestoreDirectory(in: directory),
let restore = try? directory.directory(name),
let ios = readVersion("iPhone-BuildManifest.plist", in: restore),
let cloudOS = readVersion("BuildManifest.plist", in: restore)
else { return nil }
return VPhoneRestoreInfo(ios: ios, cloudOS: cloudOS)
}
/// Root runs this in a folder the caller controls (`vm new` under sudo),
/// so the write is descriptor relative: a new file created exclusively
/// beside the old one, then renamed over it. A symbolic link planted at
/// `restore-info.json` is replaced, never written through, and the bundle
/// folder itself must not be a link.
public func write(toBundle bundle: VPhoneBundle) throws {
let encoder = JSONEncoder()
encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
let data = try encoder.encode(self)
let directory = try VPhoneConfinedDirectory(root: bundle.url.path)
try directory.writeFile(Self.fileName, contents: data, mode: 0o644)
}
/// Set `variant` (and its device) on the bundle's restore-info.json, keeping
/// the recorded versions unless the completed installer supplies an actual
/// mounted System identity. nil if no versions exist yet to preserve.
@discardableResult
public static func recordVariant(_ variant: String, toBundle bundle: VPhoneBundle,
installedUserland: OSVersion? = nil) throws
-> VPhoneRestoreInfo?
{
guard let base = load(fromBundle: bundle) else { return nil }
let merged = VPhoneRestoreInfo(
ios: installedUserland ?? base.ios,
cloudOS: base.cloudOS,
variant: variant,
device: bundle.manifest.guestDevice.family == .homePod
? bundle.manifest.guestProductType : device(forVariant: variant),
)
try merged.write(toBundle: bundle)
return merged
}
/// Whether `cfw install` finished on this bundle. `restore` writes
/// restore-info.json without a variant and only a completed install records
/// one, so a snapshot with no variant is a guest that cannot boot yet. `nil`
/// when there is no snapshot to tell: a bundle restored before it existed.
public static func customFirmwareInstalled(inBundle bundle: VPhoneBundle) -> Bool? {
guard let directory = readableDirectory(of: bundle),
let data = try? directory.readData(fileName),
let info = try? JSONDecoder().decode(VPhoneRestoreInfo.self, from: data)
else { return nil }
return info.variant != nil
}
/// Drop the recorded variant before an install that writes Disk.img in
/// place, so an install that stops halfway is not reported as complete.
public static func clearVariant(inBundle bundle: VPhoneBundle) throws {
guard let directory = readableDirectory(of: bundle),
let data = try? directory.readData(fileName),
let info = try? JSONDecoder().decode(VPhoneRestoreInfo.self, from: data),
info.variant != nil
else { return }
try VPhoneRestoreInfo(ios: info.ios, cloudOS: info.cloudOS).write(toBundle: bundle)
}
/// Remove the `iPhone*_Restore/` tree from the bundle; returns its name, or
/// nil if absent. Record versions (`derive`) first — it reads this directory.
/// Only a real folder is removed, without following any link inside it:
/// an `iPhone*_Restore` symbolic link is not a restore tree.
@discardableResult
public static func removeBuiltFirmware(fromBundle bundle: VPhoneBundle) throws -> String? {
let directory = try VPhoneConfinedDirectory(root: bundle.url.path)
guard let name = findRestoreDirectory(in: directory) else { return nil }
try directory.removeItem(name)
return name
}
// MARK: - Restore-directory reads
/// Reads may follow a bundle folder that is itself a link (a VM moved to
/// another disk); everything below it is still opened without following.
private static func readableDirectory(of bundle: VPhoneBundle) -> VPhoneConfinedDirectory? {
try? VPhoneConfinedDirectory(root: bundle.url.resolvingSymlinksInPath().path)
}
/// The newest `iPhone*_Restore` entry that `lstat` reports as a folder.
static func findRestoreDirectory(in directory: VPhoneConfinedDirectory) -> String? {
let entries = (try? directory.entries()) ?? []
return entries
.filter { $0.hasPrefix("iPhone") && $0.hasSuffix("_Restore") }
.filter { (try? directory.isDirectory($0)) == true }
.max()
}
private static func readVersion(_ name: String, in directory: VPhoneConfinedDirectory) -> OSVersion? {
guard let data = try? directory.readData(name),
let root = (try? PropertyListSerialization.propertyList(from: data, format: nil)) as? [String: Any],
let version = root["ProductVersion"] as? String, isVersionToken(version),
let build = root["ProductBuildVersion"] as? String, isVersionToken(build)
else { return nil }
return OSVersion(version: version, build: build)
}
/// Versions and builds come from plists in a caller-controlled folder and
/// end up in JSON, logs and UI: accept only `[0-9A-Za-z.]{1,32}`.
static func isVersionToken(_ text: String) -> Bool {
(1 ... 32).contains(text.utf8.count) && text.utf8.allSatisfy { byte in
(byte >= 0x30 && byte <= 0x39) || (byte >= 0x41 && byte <= 0x5A)
|| (byte >= 0x61 && byte <= 0x7A) || byte == 0x2E
}
}
}