Run a virtual iPhone on an Apple Silicon Mac.
Swift
import CryptoKit
import Foundation
// MARK: - Slimming
/// What a template's guest was trimmed of before it was frozen. Part of the
/// key: a machine cloned from a trimmed template cannot get the files back,
/// and one cloned from an untrimmed template does not lose them.
///
/// Every field has a "nothing done" value. Offline file trimming records
/// `trimTier`; the setup boot records `setupBoot`, `serviceProfile`,
/// `serviceGroups` and `removedApps` (see `VPhoneTemplateSetupBoot`). What a
/// `vm create` asks for comes from its switches (`VPhoneTemplateSlimmingRequest`).
public struct VPhoneMachineTemplateSlimming: Codable, Equatable, Hashable, Sendable {
/// The file trim applied to the System volume, as
/// ``VPhoneSystemTrimSpec/keyValue`` writes it: `none`, `conservative/1`,
/// `standard/1/en,zh,zh-Hans` (tier, list version, kept languages).
public var trimTier: String
/// Whether the template was booted once to finish Setup and first-boot
/// work before it was frozen.
public var setupBoot: Bool
/// The vphoned service profile applied during the setup boot: `none` or
/// `trimmed`.
public var serviceProfile: String
/// Optional service groups applied on top of the profile's defaults
/// (`accounts` for `--accounts-off`), sorted. Empty with profile `none`.
public var serviceGroups: [String]
/// Bundle identifiers of the system apps removed during the setup boot,
/// sorted.
public var removedApps: [String]
public static let none = VPhoneMachineTemplateSlimming()
/// Why a template could not be built with this slimming, or nothing. A
/// trim needs the setup boot: only the guest can delete the `orig-fs`
/// snapshot that otherwise keeps every trimmed block (see
/// ``VPhoneMachineTemplateSteps/problems``).
public var problems: [String] {
trimTier != "none" && !setupBoot
? ["trim \(trimTier) needs the setup boot, which deletes the guest's orig-fs snapshot; without it the trim frees nothing"]
: []
}
public init(
trimTier: String = "none",
setupBoot: Bool = false,
serviceProfile: String = "none",
serviceGroups: [String] = [],
removedApps: [String] = [],
) {
self.trimTier = trimTier
self.setupBoot = setupBoot
self.serviceProfile = serviceProfile
self.serviceGroups = Array(Set(serviceGroups)).sorted()
self.removedApps = Array(Set(removedApps)).sorted()
}
private enum CodingKeys: String, CodingKey {
case trimTier = "TrimTier"
case setupBoot = "SetupBoot"
case serviceProfile = "ServiceProfile"
case serviceGroups = "ServiceGroups"
case removedApps = "RemovedApps"
}
/// This slimming for a guest of `iOSVersion`. `trimmed` is the service
/// list measured for the guest's iOS; vphoned has one only for
/// ``VPhoneTemplateSlimmingRequest/trimmedServiceProfileMajors`` and
/// refuses the profile elsewhere, after the restore and most of the setup
/// boot. So on another version (iOS 25 and earlier) the profile is `none`, in
/// the key as in the setup boot. Extra groups (`--accounts-off`) are
/// skipped too: they need the same version-specific list.
public func fitted(toIOSVersion iOSVersion: String) throws -> Self {
guard serviceProfile == "trimmed",
let major = iOSVersion.split(separator: ".").first.flatMap({ Int($0) }),
!VPhoneTemplateSlimmingRequest.trimmedServiceProfileMajors.contains(major)
else { return self }
var fitted = self
fitted.serviceProfile = "none"
fitted.serviceGroups = []
return fitted
}
/// One phrase for listings: `trim none, setup boot, services trimmed+accounts, 10 apps removed`.
public var summary: String {
var services = serviceProfile
if !serviceGroups.isEmpty {
services += "+" + serviceGroups.joined(separator: "+")
}
return "trim \(trimTier), \(setupBoot ? "setup boot" : "no setup boot"), services \(services), "
+ "\(removedApps.count) apps removed"
}
/// A key of format 1 has no `ServiceGroups`; it reads as none.
public init(from decoder: any Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
try self.init(
trimTier: container.decode(String.self, forKey: .trimTier),
setupBoot: container.decode(Bool.self, forKey: .setupBoot),
serviceProfile: container.decode(String.self, forKey: .serviceProfile),
serviceGroups: container.decodeIfPresent([String].self, forKey: .serviceGroups) ?? [],
removedApps: container.decode([String].self, forKey: .removedApps),
)
}
}
// MARK: - Key
/// Everything a new machine inherits from its template and could not change
/// afterwards without a restore. Two requests with the same key can share one
/// template; any difference needs another.
///
/// Not part of it: CPU, memory, screen, network and the other `config.plist`
/// settings (`vm config` changes them on the clone), and the guest patch
/// selection, which `cfw update-environment` applies both ways. The boot chain
/// is: `bootChainPlanDigest` covers the preset's boot-chain patches as the
/// plan resolved them, and the preset itself is a field because the presets
/// also differ in what a full `cfw install` writes into Preboot.
///
/// The key is pure data. The caller resolves each field: from the requested
/// options and IPSWs before a create, or from a machine's own records when it
/// is adopted. Both must arrive at the same values for the same machine.
public struct VPhoneMachineTemplateKey: Codable, Equatable, Hashable, Sendable {
/// Raised whenever a field is added or its meaning changes, so templates
/// keyed by an older rule are never matched by a newer one.
///
/// - 1: the first templates (nothing slimmed, never booted).
/// - 2: `slimming.serviceGroups`; a create now asks for a setup boot.
public static let currentFormatVersion = 2
public var formatVersion: Int
/// The guest device's product type, as `fw prepare` picked it.
public var device: String
public var iOSVersion: String
public var iOSBuild: String
public var cloudOSVersion: String
public var cloudOSBuild: String
public var patchPreset: String
/// ``planDigest(bootChainPatches:parameters:)`` of the resolved plan.
public var bootChainPlanDigest: String
/// The `VPhone.bundle` series (`2.8`) that built the boot chain.
public var bundleSeries: String
/// The disk image's size in decimal GB, which the restore fixed.
public var diskSizeGB: UInt64
public var slimming: VPhoneMachineTemplateSlimming
public init(
formatVersion: Int = Self.currentFormatVersion,
device: String,
iOSVersion: String,
iOSBuild: String,
cloudOSVersion: String,
cloudOSBuild: String,
patchPreset: String,
bootChainPlanDigest: String,
bundleSeries: String,
diskSizeGB: UInt64,
slimming: VPhoneMachineTemplateSlimming = .none,
) {
self.formatVersion = formatVersion
self.device = device
self.iOSVersion = iOSVersion
self.iOSBuild = iOSBuild
self.cloudOSVersion = cloudOSVersion
self.cloudOSBuild = cloudOSBuild
self.patchPreset = patchPreset
self.bootChainPlanDigest = bootChainPlanDigest
self.bundleSeries = bundleSeries
self.diskSizeGB = diskSizeGB
self.slimming = slimming
}
// MARK: Identifier
/// One `name=value` line per field, in a fixed order. Lists are joined
/// with commas after sorting, so the order a caller gathered them in does
/// not matter.
public var canonicalDescription: String {
[
"format=\(formatVersion)",
"device=\(device)",
"ios=\(iOSVersion)/\(iOSBuild)",
"cloudos=\(cloudOSVersion)/\(cloudOSBuild)",
"preset=\(patchPreset)",
"bootchain=\(bootChainPlanDigest)",
"series=\(bundleSeries)",
"disk=\(diskSizeGB)",
"trim=\(slimming.trimTier)",
"setup=\(slimming.setupBoot ? 1 : 0)",
"services=\(slimming.serviceProfile)",
"service-groups=\(slimming.serviceGroups.sorted().joined(separator: ","))",
"removed-apps=\(slimming.removedApps.sorted().joined(separator: ","))",
].joined(separator: "\n")
}
/// The template's folder name: the first 12 hex digits of the SHA-256 of
/// ``canonicalDescription``.
public var identifier: String {
Self.hex(SHA256.hash(data: Data(canonicalDescription.utf8))).prefix(Self.identifierLength).description
}
public static let identifierLength = 12
/// Whether `text` has the shape of an identifier. Only such a name is
/// ever looked up under `.templates`.
public static func isIdentifier(_ text: String) -> Bool {
text.utf8.count == identifierLength && text.utf8.allSatisfy { byte in
(byte >= 0x30 && byte <= 0x39) || (byte >= 0x61 && byte <= 0x66)
}
}
// MARK: Plan digest
/// SHA-256 over the sorted boot-chain patch identifiers and the preset's
/// parameters. The caller decides which patches count as boot chain, and
/// must decide the same way for a request and for a recorded plan.
public static func planDigest(bootChainPatches: some Sequence<String>, parameters: [String: String]) -> String {
let patches = Array(Set(bootChainPatches)).sorted()
let knobs = parameters.keys.sorted().map { "\($0)=\(parameters[$0] ?? "")" }
let text = (["patches"] + patches + ["parameters"] + knobs).joined(separator: "\n")
return hex(SHA256.hash(data: Data(text.utf8)))
}
// MARK: Bundle series
/// The first two numbers of a bundle version: `2.8.1` and
/// `2.8.0-local.ab12cd34` are both `2.8`. Nil for anything else.
public static func series(ofBundleVersion version: String) -> String? {
let numbers = version.split(separator: "-", maxSplits: 1).first.map(String.init) ?? ""
let parts = numbers.split(separator: ".", omittingEmptySubsequences: false)
guard parts.count >= 2, parts.prefix(2).allSatisfy({ !$0.isEmpty && Int($0) != nil }) else {
return nil
}
return "\(parts[0]).\(parts[1])"
}
// MARK: Comparison
/// The fields that differ from `other`, as `name: mine → theirs`, for
/// messages. Empty when the keys are equal.
public func differences(from other: VPhoneMachineTemplateKey) -> [String] {
var lines: [String] = []
func compare(_ name: String, _ mine: String, _ theirs: String) {
if mine != theirs {
lines.append("\(name): \(mine) → \(theirs)")
}
}
compare("key format", String(formatVersion), String(other.formatVersion))
compare("device", device, other.device)
compare("iOS", "\(iOSVersion) (\(iOSBuild))", "\(other.iOSVersion) (\(other.iOSBuild))")
compare("cloudOS", "\(cloudOSVersion) (\(cloudOSBuild))", "\(other.cloudOSVersion) (\(other.cloudOSBuild))")
compare("preset", patchPreset, other.patchPreset)
compare("boot-chain plan", String(bootChainPlanDigest.prefix(12)), String(other.bootChainPlanDigest.prefix(12)))
compare("bundle series", bundleSeries, other.bundleSeries)
compare("disk size", "\(diskSizeGB) GB", "\(other.diskSizeGB) GB")
compare("trim tier", slimming.trimTier, other.slimming.trimTier)
compare("setup boot", slimming.setupBoot ? "yes" : "no", other.slimming.setupBoot ? "yes" : "no")
compare("service profile", slimming.serviceProfile, other.slimming.serviceProfile)
compare(
"service groups",
slimming.serviceGroups.joined(separator: ",").ifEmpty("none"),
other.slimming.serviceGroups.joined(separator: ",").ifEmpty("none"),
)
compare(
"removed apps",
slimming.removedApps.joined(separator: ",").ifEmpty("none"),
other.slimming.removedApps.joined(separator: ",").ifEmpty("none"),
)
return lines
}
/// One line for listings.
public var summary: String {
"\(device) iOS \(iOSVersion) (\(iOSBuild)) / cloudOS \(cloudOSVersion) (\(cloudOSBuild)), "
+ "\(patchPreset), \(diskSizeGB) GB, bundle \(bundleSeries), \(slimming.summary)"
}
// MARK: Coding
private enum CodingKeys: String, CodingKey {
case formatVersion = "FormatVersion"
case device = "Device"
case iOSVersion = "IOSVersion"
case iOSBuild = "IOSBuild"
case cloudOSVersion = "CloudOSVersion"
case cloudOSBuild = "CloudOSBuild"
case patchPreset = "PatchPreset"
case bootChainPlanDigest = "BootChainPlanDigest"
case bundleSeries = "BundleSeries"
case diskSizeGB = "DiskSizeGB"
case slimming = "Slimming"
}
private static func hex(_ digest: SHA256.Digest) -> String {
digest.map { String(format: "%02x", $0) }.joined()
}
}
// MARK: - Request
/// The key fields a `vm create --template` names explicitly. A nil field was
/// not given and takes the template's value.
public struct VPhoneMachineTemplateRequest: Equatable, Sendable {
public var device: String?
public var patchPreset: String?
public var diskSizeGB: UInt64?
/// The slimming the switches ask for, when any slimming switch was given.
public var slimming: VPhoneMachineTemplateSlimming?
public init(
device: String? = nil,
patchPreset: String? = nil,
diskSizeGB: UInt64? = nil,
slimming: VPhoneMachineTemplateSlimming? = nil,
) {
self.device = device
self.patchPreset = patchPreset
self.diskSizeGB = diskSizeGB
self.slimming = slimming
}
/// Each option that asks for something the template does not have, as a
/// sentence. A clone cannot change any of them.
public func conflicts(with key: VPhoneMachineTemplateKey) -> [String] {
var lines: [String] = []
if let device, device != key.device {
lines.append("--device \(device): the template's guest is \(key.device)")
}
if let patchPreset, patchPreset != key.patchPreset {
lines.append("--preset \(patchPreset): the template was built with \(key.patchPreset)")
}
if let diskSizeGB, diskSizeGB != key.diskSizeGB {
lines.append("--disk-size \(diskSizeGB): the template's disk is \(key.diskSizeGB) GB, fixed by its restore")
}
if let slimming, slimming != key.slimming {
lines.append("the slimming switches ask for \(slimming.summary); the template has \(key.slimming.summary)")
}
return lines
}
}
// MARK: - Expected identifier
/// `vm template adopt --expect <id>` refused: the key a machine's records
/// give hashes to another identifier than the one the caller worked out for
/// its request (`vm template find`). Adopting it anyway would file the
/// template where no later request with the same options looks, and every
/// such request would build another one.
public struct VPhoneMachineTemplateKeyMismatch: Error, CustomStringConvertible, LocalizedError, Sendable {
public var expected: String
/// The key the machine's records give.
public var key: VPhoneMachineTemplateKey
/// The key that hashes to `expected`, when it could be recovered (see
/// ``VPhoneMachineTemplateKey/mismatch(expecting:known:)``).
public var expectedKey: VPhoneMachineTemplateKey?
/// Per field, the expected value and the machine's (`expected → machine`);
/// empty when the expected key is not known.
public var differences: [String]
public var identifier: String {
key.identifier
}
public var description: String {
let head = "The machine's records give template \(identifier), not the expected \(expected)"
guard expectedKey != nil else {
return head + ". The key behind \(expected) is not known here; compare this machine's key with the key "
+ "vm template find --json prints: " + key.canonicalDescription.split(separator: "\n").joined(separator: "; ") + "."
}
return head + ": " + differences.joined(separator: "; ") + "."
}
public var errorDescription: String? {
description
}
}
public extension VPhoneMachineTemplateKey {
/// Nil when this key hashes to `expected`. Otherwise why not: the key
/// behind `expected` is looked for among `known` (the library's
/// templates and builds), then among the keys that differ from this one
/// only in slimming (the trim tier, the setup boot, the service profile
/// and groups, and which of the default apps were removed), where a
/// setup boot that left an app behind lands. A hash cannot be undone, so
/// a key that differs elsewhere, and is not known, stays unknown.
func mismatch(expecting expected: String, known: [VPhoneMachineTemplateKey] = []) -> VPhoneMachineTemplateKeyMismatch? {
let expected = expected.lowercased()
guard identifier != expected else { return nil }
let found = known.first { $0.identifier == expected } ?? slimmingVariant(identifiedBy: expected)
return VPhoneMachineTemplateKeyMismatch(
expected: expected,
key: self,
expectedKey: found,
differences: found.map { $0.mismatchLines(against: self) } ?? [],
)
}
/// The key with this one's fields but another slimming whose identifier
/// is `identifier`, or nil. At most a few tens of thousands of hashes,
/// this key's own values tried first.
func slimmingVariant(identifiedBy identifier: String) -> VPhoneMachineTemplateKey? {
func unique<T: Hashable>(_ values: [T]) -> [T] {
var seen = Set<T>()
return values.filter { seen.insert($0).inserted }
}
let tiers = unique([
slimming.trimTier,
"none",
VPhoneTemplateSlimmingRequest.defaultTrimTier,
(try? VPhoneSystemTrimSpec(tier: .conservative).keyValue) ?? "none",
])
let setups = [slimming.setupBoot, !slimming.setupBoot]
let profiles = unique([slimming.serviceProfile] + VPhoneTemplateSlimmingRequest.serviceProfiles)
let groups = unique([slimming.serviceGroups, [], [VPhoneTemplateSlimmingRequest.accountsGroup]])
let apps = unique(slimming.removedApps + VPhoneTemplateSlimmingRequest.defaultRemovedApps)
// Every subset of the apps, this key's own first; a list too long to
// enumerate is tried as it is, as the default, and as none.
let appSets: [[String]] = apps.count <= 12
? [slimming.removedApps] + (0 ..< (1 << apps.count)).map { mask in
apps.indices.filter { mask & (1 << $0) != 0 }.map { apps[$0] }
}
: [slimming.removedApps, VPhoneTemplateSlimmingRequest.defaultRemovedApps, []]
var candidate = self
for setup in setups {
for tier in tiers {
for profile in profiles {
for group in groups {
for removed in appSets {
candidate.slimming = VPhoneMachineTemplateSlimming(
trimTier: tier,
setupBoot: setup,
serviceProfile: profile,
serviceGroups: group,
removedApps: removed,
)
if candidate.identifier == identifier {
return candidate
}
}
}
}
}
}
return nil
}
/// ``differences(from:)`` from this (expected) key to `other`, with the
/// removed apps as the apps one list has and the other lacks.
private func mismatchLines(against other: VPhoneMachineTemplateKey) -> [String] {
var lines = differences(from: other).filter { !$0.hasPrefix("removed apps:") }
let mine = Set(slimming.removedApps)
let theirs = Set(other.slimming.removedApps)
let notRemoved = mine.subtracting(theirs).sorted()
let extra = theirs.subtracting(mine).sorted()
if !notRemoved.isEmpty {
lines.append("removed apps: expected \(notRemoved.joined(separator: ", ")) removed too, the machine still has "
+ (notRemoved.count == 1 ? "it" : "them"))
}
if !extra.isEmpty {
lines.append("removed apps: the machine also lacks \(extra.joined(separator: ", ")), which was not expected")
}
return lines
}
}
// MARK: - Bundle version
public enum VPhoneBundleVersion {
/// `CFBundleShortVersionString` of the `VPhone.bundle` the running
/// executable is in, read from `Contents/Info.plist` beside
/// `Contents/MacOS`. Nil for an executable outside a bundle.
public static func current() -> String? {
let executable = VPhoneResources.runningExecutable().resolvingSymlinksInPath()
let info = executable
.deletingLastPathComponent() // Contents/MacOS
.deletingLastPathComponent() // Contents
.appendingPathComponent("Info.plist")
guard let data = try? Data(contentsOf: info),
let plist = (try? PropertyListSerialization.propertyList(from: data, format: nil)) as? [String: Any]
else { return nil }
return plist["CFBundleShortVersionString"] as? String
}
}
private extension String {
func ifEmpty(_ replacement: String) -> String {
isEmpty ? replacement : self
}
}