Run a virtual iPhone on an Apple Silicon Mac.
Swift
@testable import FirmwarePatcher
import Foundation
import CryptoKit
import VPhoneCoreKit
import Testing
/// Identity selection for the hybrid manifest.
///
/// `FirmwareManifest.generate()` was translated from `scripts/fw_manifest.py`
/// some time ago and then never called, so its equivalence was unknown until
/// it was run. It has now been checked against the Python on a real pair —
/// cloudOS 26.4-23E5207q and iPhone 27.0-24A435 — and produced semantically
/// identical BuildManifest.plist and Restore.plist, down to the picked
/// identity indices.
///
/// That is one build pair. What breaks on a different one is the *selection*:
/// which identity counts as research, which as release, which as the erase
/// identity. Those are pure functions over a build identity, so they can be
/// pinned here without a firmware image, which is what these do.
@Suite("Hybrid manifest identity selection")
struct FirmwareManifestSelectionTests {
@Test
func `TV donor digests authenticate unchanged payloads using PCC SHA384`() throws {
let root = FileManager.default.temporaryDirectory.appending(path: UUID().uuidString)
try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
defer { try? FileManager.default.removeItem(at: root) }
let payload = Data("unchanged donor payload".utf8)
try payload.write(to: root.appending(path: "payload.im4p"))
let names = ["Ap,SystemVolumeCanonicalMetadata", "OS", "StaticTrustCache", "SystemVolume"]
let entry: PlistDict = ["Digest": Data(Insecure.SHA1.hash(data: payload)),
"Trusted": true, "Info": ["Path": "payload.im4p"]]
var components = PlistDict()
for name in names { components[name] = entry }
components["KernelCache"] = entry
let identity: PlistDict = ["Manifest": components]
let normalized = try FirmwareManifest.normalizeGuestComponentDigests(
identity, device: .appleTV5_3, restoreDir: root,
)
let result = try #require(normalized["Manifest"] as? PlistDict)
for name in names {
let component = try #require(result[name] as? PlistDict)
#expect(component["Digest"] as? Data == Data(SHA384.hash(data: payload)))
#expect(component["Trusted"] as? Bool == true)
}
#expect((result["KernelCache"] as? PlistDict)?["Digest"] as? Data == entry["Digest"] as? Data)
#expect(try Data(contentsOf: root.appending(path: "payload.im4p")) == payload)
}
@Test
func `phone and pad manifest digests remain unchanged without reading files`() throws {
let identity: PlistDict = ["Manifest": ["OS": ["Digest": Data([1, 2, 3])]]]
for device in [VPhoneGuestDevice.iPhone17_3, .iPad16_1] {
let result = try FirmwareManifest.normalizeGuestComponentDigests(
identity, device: device, restoreDir: URL(fileURLWithPath: "/missing"),
)
#expect(NSDictionary(dictionary: result).isEqual(to: identity))
}
}
@Test
func `TV digest normalization rejects paths outside the restore tree`() {
let identity: PlistDict = ["Manifest": ["Ap,SystemVolumeCanonicalMetadata": ["Info": ["Path": "../outside"]]]]
#expect(throws: (any Error).self) {
try FirmwareManifest.normalizeGuestComponentDigests(
identity, device: .appleTV5_3, restoreDir: URL(fileURLWithPath: "/missing"),
)
}
}
// MARK: - Fixtures
static func identity(
deviceClass: String,
variant: String = "Customer Erase Install (IPSW)",
llbPath: String? = nil,
) -> PlistDict {
var manifest = PlistDict()
if let llbPath {
manifest["LLB"] = ["Info": ["Path": llbPath] as PlistDict] as PlistDict
}
return [
"Info": [
"DeviceClass": deviceClass,
"Variant": variant,
] as PlistDict,
"Manifest": manifest,
]
}
// MARK: - isResearch
@Test
func `a four-part LLB filename with RESEARCH in field 3 marks a research identity`() {
// Firmware/all_flash/LLB.vresearch101.RESEARCH.im4p -> 4 dot-separated
// parts, and the third says RESEARCH.
let bi = Self.identity(
deviceClass: "vresearch101ap",
llbPath: "Firmware/all_flash/LLB.vresearch101.RESEARCH.im4p",
)
#expect(FirmwareManifest.isResearch(bi))
}
@Test
func `the same filename shape with RELEASE does not`() {
let bi = Self.identity(
deviceClass: "vresearch101ap",
llbPath: "Firmware/all_flash/LLB.vresearch101.RELEASE.im4p",
)
#expect(!FirmwareManifest.isResearch(bi))
}
@Test
func `with no usable path, the Variant string decides`() {
#expect(FirmwareManifest.isResearch(
Self.identity(deviceClass: "vresearch101ap", variant: "Research Erase Install (IPSW)"),
))
#expect(!FirmwareManifest.isResearch(
Self.identity(deviceClass: "vresearch101ap", variant: "Customer Erase Install (IPSW)"),
))
}
@Test
func `the Variant check is case-insensitive`() {
#expect(FirmwareManifest.isResearch(
Self.identity(deviceClass: "vresearch101ap", variant: "RESEARCH Erase Install"),
))
}
@Test
func `a filename that is not four parts falls through to the Variant`() {
// "LLB.vresearch101.im4p" is three parts: no RESEARCH field to read,
// so the decision has to come from Variant instead of defaulting.
let bi = Self.identity(
deviceClass: "vresearch101ap",
variant: "Research Erase Install (IPSW)",
llbPath: "Firmware/all_flash/LLB.vresearch101.im4p",
)
#expect(FirmwareManifest.isResearch(bi))
}
// MARK: - findCloudOS
@Test
func `picks the first release and the first research for a device class`() throws {
let identities = [
Self.identity(deviceClass: "j226cap"),
Self.identity(deviceClass: "vphone600ap"),
Self.identity(deviceClass: "vresearch101ap"),
Self.identity(deviceClass: "vresearch101ap", variant: "Research Erase Install"),
Self.identity(deviceClass: "vresearch101ap", variant: "Research Erase Install"),
]
let (release, research) = try FirmwareManifest.findCloudOS(
identities,
deviceClass: "vresearch101ap",
)
#expect(release == 2)
#expect(research == 3) // the first research one, not the last
}
@Test
func `a device class with no research identity is an error, not a silent fallback`() {
let identities = [Self.identity(deviceClass: "vresearch101ap")]
#expect(throws: (any Error).self) {
try FirmwareManifest.findCloudOS(identities, deviceClass: "vresearch101ap")
}
}
@Test
func `an unknown device class is an error`() {
let identities = [Self.identity(deviceClass: "j226cap")]
#expect(throws: (any Error).self) {
try FirmwareManifest.findCloudOS(identities, deviceClass: "vphone600ap")
}
}
// MARK: - findRuntime
@Test
func `the guest takes vphone600ap's identities where the cloudOS has them`() {
let identities = [
Self.identity(deviceClass: "vresearch101ap"),
Self.identity(deviceClass: "vresearch101ap", variant: "Research Erase Install"),
Self.identity(deviceClass: "vphone600ap"),
Self.identity(deviceClass: "vphone600ap", variant: "Research Erase Install"),
]
let (release, research) = FirmwareManifest.findRuntime(identities, researchBoard: (0, 1))
#expect(release == 2)
#expect(research == 3)
}
@Test
func `without vphone600ap the research board stands in`() {
let identities = [
Self.identity(deviceClass: "vresearch101ap"),
Self.identity(deviceClass: "vresearch101ap", variant: "Research Erase Install"),
]
let (release, research) = FirmwareManifest.findRuntime(identities, researchBoard: (0, 1))
#expect(release == 0)
#expect(research == 1)
}
/// An identity naming each of `components` at `<component>.<device class>`.
static func identity(deviceClass: String, variant: String, components: [String]) -> PlistDict {
var identity = identity(deviceClass: deviceClass, variant: variant)
var manifest = PlistDict()
for component in components {
manifest[component] = ["Info": ["Path": "\(component).\(deviceClass)"] as PlistDict] as PlistDict
}
identity["Manifest"] = manifest
return identity
}
@Test
func `the research board supplies the guest's components and may lack a RecoveryMode`() throws {
let cloud = [
"LLB", "iBSS", "iBEC", "iBoot", "Ap,RestoreSecurePageTableMonitor", "Ap,RestoreTrustedExecutionMonitor",
"Ap,SecurePageTableMonitor", "Ap,TrustedExecutionMonitor", "DeviceTree", "RestoreDeviceTree", "SEP",
"RestoreSEP", "KernelCache", "RestoreKernelCache", "RestoreRamDisk", "RestoreTrustCache",
]
let cloudIdentities = [
Self.identity(deviceClass: "vresearch101ap", variant: "Darwin Cloud Customer Erase Install (IPSW)", components: cloud),
Self.identity(deviceClass: "vresearch101ap", variant: "Research Darwin Cloud Customer Erase Install (IPSW)", components: cloud),
]
let iPhoneIdentities = [
Self.identity(deviceClass: "d47ap", variant: "Customer Erase Install (IPSW)", components: [
"Ap,SystemVolumeCanonicalMetadata", "OS", "StaticTrustCache", "SystemVolume",
]),
]
let (vp, vpr) = FirmwareManifest.findRuntime(cloudIdentities, researchBoard: (0, 1))
let identity = try FirmwareManifest.buildEraseIdentity(
cloudIdentities: cloudIdentities,
iPhoneIdentities: iPhoneIdentities,
prod: 0,
res: 1,
vp: vp,
vpr: vpr,
iErase: 0,
)
let manifest = try #require(identity["Manifest"] as? PlistDict)
func path(_ component: String) -> String? {
((manifest[component] as? PlistDict)?["Info"] as? PlistDict)?["Path"] as? String
}
#expect(path("RestoreDeviceTree") == "RestoreDeviceTree.vresearch101ap")
#expect(path("SEP") == "SEP.vresearch101ap")
#expect(manifest["RecoveryMode"] == nil)
}
// MARK: - findIPhoneErase
@Test
func `erase is the first identity that is not research, upgrade or recovery`() throws {
let identities = [
Self.identity(deviceClass: "d47ap", variant: "Customer Upgrade Install (IPSW)"),
Self.identity(deviceClass: "d47ap", variant: "Research Erase Install (IPSW)"),
Self.identity(deviceClass: "d47ap", variant: "Recovery Customer Install"),
Self.identity(deviceClass: "d47ap", variant: "Customer Erase Install (IPSW)"),
]
#expect(try FirmwareManifest.findIPhoneErase(identities) == 3)
}
@Test
func `the erase match is case-insensitive`() throws {
let identities = [
Self.identity(deviceClass: "d47ap", variant: "Customer UPGRADE Install"),
Self.identity(deviceClass: "d47ap", variant: "Customer Erase Install"),
]
#expect(try FirmwareManifest.findIPhoneErase(identities) == 1)
}
@Test
func `an iPhone manifest with no erase identity is an error`() {
let identities = [
Self.identity(deviceClass: "d47ap", variant: "Customer Upgrade Install (IPSW)"),
]
#expect(throws: (any Error).self) {
try FirmwareManifest.findIPhoneErase(identities)
}
}
@Test
func `a multi-board iPad manifest yields the guest board's erase identity`() throws {
let identities = [
Self.identity(deviceClass: "j411ap", variant: "Customer Erase Install (IPSW)"),
Self.identity(deviceClass: "j411ap", variant: "Customer Upgrade Install (IPSW)"),
Self.identity(deviceClass: "J410AP", variant: "Customer Erase Install (IPSW)"),
Self.identity(deviceClass: "j410ap", variant: "Customer Upgrade Install (IPSW)"),
]
#expect(try FirmwareManifest.findIPhoneErase(identities, deviceClass: "j410ap") == 2)
}
@Test
func `an unknown board falls back to the first erase identity`() throws {
let identities = [
Self.identity(deviceClass: "d47ap", variant: "Customer Upgrade Install (IPSW)"),
Self.identity(deviceClass: "d47ap", variant: "Customer Erase Install (IPSW)"),
]
#expect(try FirmwareManifest.findIPhoneErase(identities, deviceClass: "j410ap") == 1)
}
}