Run a virtual iPhone on an Apple Silicon Mac.
Swift
// CustomFirmwarePlistPatchTests.swift — the three P1.4 CFW patchers, against the Python
// they replaced.
//
// Unit tests cover the behaviour each patcher is supposed to have. The
// equivalence tests are the ones that matter: `scripts/patchers/<name>.py` was
// run over the same real input the Swift gets, and what it produced is frozen
// in ``CustomFirmwarePlistPatchGolden`` below — semantically for the two plist patchers,
// byte for byte for the device tree.
//
// Real input, never a hand-made stand-in:
// - the host's own /System/Library/CoreServices/SystemVersion.plist
// - a real entitlements plist dumped from a signed system binary
// - DeviceTree.vphone600ap.im4p, pulled out of the cloudOS IPSW
//
// The first two are host-dependent: their bytes differ with every macOS build,
// so a frozen digest of the *output* would say nothing. For those the frozen
// value is the transform the Python applied, read off its output by diffing it
// against its own input. The device tree is fixed inside its IPSW, so that one
// is a digest, per IPSW.
//
// Every equivalence test is gated on its input, and skips rather than fails
// when it is absent — but a skip is not a pass, and the migration notes record
// which ones actually ran.
import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Img4tool
import Testing
import VPhonePatchKit
// MARK: - The frozen reference
/// What `scripts/patchers/` produced on these inputs, recorded before it was
/// deleted. Measured at repo commit `78cbeea` with `.venv/bin/python3`.
enum CustomFirmwarePlistPatchGolden {
/// `.venv/bin/python3 scripts/patchers/cfw_patch_build_version.py \
/// <copy of /System/Library/CoreServices/SystemVersion.plist> 23F77`
///
/// Run over both `plutil -convert xml1` and `-convert binary1` copies. On
/// this host it printed `ProductBuildVersion '26A428' -> '23F77'` and,
/// diffing its output against its input, the ONLY difference was that one
/// key's value; the serialized format stayed what it went in as (the XML
/// copy came back starting `<?xml ve`, the binary one `bplist00`).
///
/// The input is the host's own file, which differs with every macOS build,
/// so the frozen value is that transform, not a digest.
static let buildVersionTarget = "23F77"
/// `.venv/bin/python3 scripts/patchers/campo_mach_lookup_exceptions.py \
/// <entitlements dumped from a signed host binary>`
///
/// Diffing its output against its input: the only key it touched was
/// ``exceptionKey``, and its new value was the existing array followed by
/// every service from the module's own `SERVICES` list not already in it,
/// in `SERVICES` order. On Safari (3 unrelated entries already present) it
/// printed `count: 20 (+17 added)`; on loginwindow (key absent) `count: 17
/// (+17 added)`.
static let exceptionKey = "com.apple.security.exception.mach-lookup.global-name"
static func countLine(total: Int, added: Int) -> String {
"count: \(total) (+\(added) added)"
}
/// `.venv/bin/python3 scripts/patchers/cfw_patch_post_restore_dt.py \
/// <copy of Firmware/all_flash/DeviceTree.vphone600ap.im4p>`
///
/// Byte for byte, input digest to output digest. Two cloudOS IPSWs carry
/// this device tree and they are not the same file, so both pairs are here;
/// the test looks its input up by digest rather than assuming which IPSW
/// `contentsOfDirectory` hands back first. Both runs reported the same
/// three rewrites, and a second run printed
/// `DT already in target state — no change` and left the bytes alone.
static let deviceTree: [String: String] = [
// EmbeddedDeviceTrees-11156.42.1, 68380-byte DT blob
"df0e5ceb010ae028b6e9a3322a07379a30911ee48f385cfe23f6931896cd096a":
"24894ac42dc218844d1988b6fe76e45d3ef9b8506ae08f11ecd01e7a6819a38b",
// EmbeddedDeviceTrees-11156.100.653.0.1, 68480-byte DT blob
"987a9306d16a9047dc1b46fd1b3cec2aab7738aff6c5c86938ee3ada1a461e3c":
"ca7386a775e8e2e7b1e242ef965ffcd644c35e545aba49182e15932257b6ba91",
]
/// SHA-256 as `shasum -a 256` prints it.
static func digest(of url: URL) throws -> String {
try Data(SHA256.hash(data: Data(contentsOf: url))).hex
}
}
// MARK: - Fixtures
enum CustomFirmwarePatchFixtures {
/// VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/CustomFirmware/<this file> → repo root.
static let repoRoot = URL(filePath: #filePath)
.deletingLastPathComponent()
.deletingLastPathComponent()
.deletingLastPathComponent()
.deletingLastPathComponent()
.deletingLastPathComponent()
/// A real Apple SystemVersion.plist, in XML, with a real ProductBuildVersion.
static let systemVersionPlist = URL(filePath: "/System/Library/CoreServices/SystemVersion.plist")
/// Signed host binaries to take a real entitlements plist from. Safari
/// already carries a non-empty mach-lookup global-name exception array,
/// so it exercises the merge; loginwindow does not carry the key at all,
/// so it exercises the insert. Both paths matter — Campo can be either.
static let entitlementsDonors = [
URL(filePath: "/Applications/Safari.app"),
URL(filePath: "/System/Library/CoreServices/loginwindow.app/Contents/MacOS/loginwindow"),
]
static var availableEntitlementsDonors: [URL] {
entitlementsDonors.filter { FileManager.default.fileExists(atPath: $0.path) }
}
static var systemVersionAvailable: Bool {
FileManager.default.isReadableFile(atPath: systemVersionPlist.path)
}
static var entitlementsDonorAvailable: Bool {
!availableEntitlementsDonors.isEmpty
}
/// Any IPSW in `ipsws/` that carries the vphone600 device tree.
static let deviceTreeEntry = "Firmware/all_flash/DeviceTree.vphone600ap.im4p"
static func ipswWithDeviceTree() -> URL? {
let ipswDirectory = repoRoot.appending(path: "ipsws")
let candidates = (try? FileManager.default.contentsOfDirectory(
at: ipswDirectory,
includingPropertiesForKeys: nil,
)) ?? []
for candidate in candidates where candidate.pathExtension == "ipsw" {
let listing = (try? run("/usr/bin/unzip", ["-l", candidate.path, deviceTreeEntry]))?.output ?? ""
if listing.contains(deviceTreeEntry) {
return candidate
}
}
return nil
}
static var deviceTreeAvailable: Bool {
ipswWithDeviceTree() != nil
}
/// Extract the device tree IM4P into `directory` and return its path.
static func extractDeviceTree(into directory: URL) throws -> URL {
guard let ipsw = ipswWithDeviceTree() else {
throw CustomFirmwareTestError.missingFixture("no IPSW in ipsws/ contains \(deviceTreeEntry)")
}
let result = try run("/usr/bin/unzip", ["-o", "-j", ipsw.path, deviceTreeEntry, "-d", directory.path])
guard result.status == 0 else {
throw CustomFirmwareTestError.commandFailed("unzip exited \(result.status): \(result.output)")
}
return directory.appending(path: "DeviceTree.vphone600ap.im4p")
}
/// Dump a real entitlements plist the way `cfw_install_jb.sh` does with
/// `ldid -e` — `codesign` is the host-side equivalent and needs no
/// Homebrew.
static func dumpEntitlements(of binary: URL, to url: URL) throws {
let result = try run("/usr/bin/codesign", ["-d", "--entitlements", ":-", "--xml", binary.path])
guard result.status == 0, !result.outputData.isEmpty else {
throw CustomFirmwareTestError.commandFailed("codesign exited \(result.status): \(result.combined)")
}
try result.outputData.write(to: url)
}
// MARK: Process plumbing
/// stdout and stderr stay separate: `codesign -d --entitlements :-` puts
/// the plist on stdout and its banner on stderr, and merging the two
/// produces a file that is not a plist at all.
struct CommandResult {
let status: Int32
let outputData: Data
let errorData: Data
var output: String {
String(decoding: outputData, as: UTF8.self)
}
var combined: String {
output + String(decoding: errorData, as: UTF8.self)
}
}
@discardableResult
static func run(_ launchPath: String, _ arguments: [String]) throws -> CommandResult {
let process = Process()
process.executableURL = URL(filePath: launchPath)
process.arguments = arguments
let out = Pipe(), err = Pipe()
process.standardOutput = out
process.standardError = err
try process.run()
let outputData = out.fileHandleForReading.readDataToEndOfFile()
let errorData = err.fileHandleForReading.readDataToEndOfFile()
process.waitUntilExit()
return CommandResult(
status: process.terminationStatus,
outputData: outputData,
errorData: errorData,
)
}
/// Copy a fixture's *contents*, not its file: the system plists this
/// reads are mode 0444, and a `copyItem` carries that through and makes
/// the copy unpatchable.
static func copyContents(of source: URL, to destination: URL) throws {
try Data(contentsOf: source).write(to: destination)
}
static func makeTemporaryDirectory() throws -> URL {
let url = FileManager.default.temporaryDirectory
.appending(path: "cfw-patch-tests-\(UUID().uuidString)")
try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
return url
}
}
enum CustomFirmwareTestError: Error, CustomStringConvertible {
case missingFixture(String)
case commandFailed(String)
var description: String {
switch self {
case let .missingFixture(message): "missing fixture: \(message)"
case let .commandFailed(message): "command failed: \(message)"
}
}
}
// MARK: - Semantic plist comparison
//
// Migration plan §7.1: same key set, same array order, same value types,
// same Data bytes. Serialized key order and the XML-vs-binary encoding are
// deliberately not compared — neither is part of what a plist means.
enum PlistComparison {
static func tag(_ value: Any) -> String {
if CFGetTypeID(value as CFTypeRef) == CFBooleanGetTypeID() {
return "bool"
}
switch value {
case is [String: Any]: return "dict"
case is [Any]: return "array"
case is String: return "string"
case is Data: return "data"
case is Date: return "date"
case let number as NSNumber: return CFNumberIsFloatType(number) ? "real" : "integer"
default: return "unknown(\(type(of: value)))"
}
}
/// Returns nil when the two are equivalent, or the path where they differ.
static func difference(_ lhs: Any, _ rhs: Any, path: String = "<root>") -> String? {
guard tag(lhs) == tag(rhs) else {
return "\(path): type \(tag(lhs)) vs \(tag(rhs))"
}
switch tag(lhs) {
case "dict":
guard let left = lhs as? [String: Any], let right = rhs as? [String: Any] else {
return "\(path): not a dictionary"
}
let leftKeys = Set(left.keys), rightKeys = Set(right.keys)
guard leftKeys == rightKeys else {
return "\(path): key set differs, only-left=\(leftKeys.subtracting(rightKeys).sorted()) only-right=\(rightKeys.subtracting(leftKeys).sorted())"
}
for key in leftKeys.sorted() {
if let found = difference(left[key]!, right[key]!, path: "\(path).\(key)") {
return found
}
}
return nil
case "array":
guard let left = lhs as? [Any], let right = rhs as? [Any] else {
return "\(path): not an array"
}
guard left.count == right.count else {
return "\(path): count \(left.count) vs \(right.count)"
}
for index in left.indices {
if let found = difference(left[index], right[index], path: "\(path)[\(index)]") {
return found
}
}
return nil
case "data":
guard let left = lhs as? Data, let right = rhs as? Data, left == right else {
return "\(path): Data bytes differ"
}
return nil
case "string":
guard let left = lhs as? String, let right = rhs as? String, left == right else {
return "\(path): '\(lhs)' vs '\(rhs)'"
}
return nil
default:
guard let left = lhs as? NSObject, let right = rhs as? NSObject, left.isEqual(right) else {
return "\(path): \(lhs) vs \(rhs)"
}
return nil
}
}
static func load(_ url: URL) throws -> Any {
try PropertyListSerialization.propertyList(
from: Data(contentsOf: url),
options: [],
format: nil,
)
}
}
// MARK: - CustomFirmwareBuildVersion
struct CustomFirmwareBuildVersionTests {
@Test func `detects XML and binary formats`() {
#expect(CustomFirmwareBuildVersion.detectFormat(Data("<?xml version=\"1.0\"?>".utf8)) == .xml)
#expect(CustomFirmwareBuildVersion.detectFormat(Data("\n\t <plist>".utf8)) == .xml)
#expect(CustomFirmwareBuildVersion.detectFormat(Data("bplist00".utf8)) == .binary)
#expect(CustomFirmwareBuildVersion.detectFormat(Data()) == .binary)
}
@Test func `rewrites the key and leaves everything else alone`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "SystemVersion.plist")
let original: [String: Any] = [
"ProductBuildVersion": "23B85",
"ProductVersion": "26.1",
"ProductName": "iPhone OS",
]
try PropertyListSerialization
.data(fromPropertyList: original, format: .xml, options: 0)
.write(to: url)
let outcome = try CustomFirmwareBuildVersion.patch(at: url, to: "23F77", verbose: false)
#expect(outcome == .rewritten(from: "23B85", to: "23F77"))
let patched = try PlistComparison.load(url) as? [String: Any]
#expect(patched?["ProductBuildVersion"] as? String == "23F77")
#expect(patched?["ProductVersion"] as? String == "26.1")
#expect(patched?["ProductName"] as? String == "iPhone OS")
}
@Test func `is idempotent and honours dry run`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "SystemVersion.plist")
try PropertyListSerialization
.data(fromPropertyList: ["ProductBuildVersion": "23F77"], format: .binary, options: 0)
.write(to: url)
let before = try Data(contentsOf: url)
#expect(try CustomFirmwareBuildVersion.patch(at: url, to: "23F77", verbose: false) == .alreadyTarget("23F77"))
#expect(try Data(contentsOf: url) == before)
let dry = try CustomFirmwareBuildVersion.patch(at: url, to: "24A100", dryRun: true, verbose: false)
#expect(dry == .dryRun(from: "23F77", to: "24A100"))
#expect(try Data(contentsOf: url) == before)
}
@Test func `refuses A plist without the key`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "SystemVersion.plist")
try PropertyListSerialization
.data(fromPropertyList: ["ProductVersion": "26.1"], format: .xml, options: 0)
.write(to: url)
#expect(throws: PatcherError.self) {
try CustomFirmwareBuildVersion.patch(at: url, to: "23F77", verbose: false)
}
}
@Test func `refuses A non dictionary root`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "root-array.plist")
try PropertyListSerialization
.data(fromPropertyList: ["a", "b"], format: .xml, options: 0)
.write(to: url)
#expect(throws: PatcherError.self) {
try CustomFirmwareBuildVersion.patch(at: url, to: "23F77", verbose: false)
}
}
@Test(.enabled(if: CustomFirmwarePatchFixtures.systemVersionAvailable))
func `matches the frozen reference on A real system version plist`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let target = CustomFirmwarePlistPatchGolden.buildVersionTarget
// Both plist encodings of the same real file: the rootfs copy is XML,
// the Cryptex copy on a device can be binary.
for format in ["xml1", "binary1"] {
let swiftOutput = directory.appending(path: "swift-\(format).plist")
try CustomFirmwarePatchFixtures.copyContents(
of: CustomFirmwarePatchFixtures.systemVersionPlist,
to: swiftOutput,
)
try CustomFirmwarePatchFixtures.run("/usr/bin/plutil", ["-convert", format, swiftOutput.path])
let before = try #require(try PlistComparison.load(swiftOutput) as? [String: Any])
try CustomFirmwareBuildVersion.patch(at: swiftOutput, to: target, verbose: false)
let after = try #require(try PlistComparison.load(swiftOutput) as? [String: Any])
// The transform the reference applied: that one key's value, and
// nothing else in the file.
#expect(after["ProductBuildVersion"] as? String == target)
var expected = after
expected["ProductBuildVersion"] = before["ProductBuildVersion"]
let difference = PlistComparison.difference(before, expected)
#expect(difference == nil, "\(format): \(difference ?? "")")
// The format the file went in as is the format it comes back as.
let swiftBytes = try Data(contentsOf: swiftOutput)
#expect(CustomFirmwareBuildVersion.detectFormat(swiftBytes) == (format == "xml1" ? .xml : .binary))
}
}
}
// MARK: - CustomFirmwareMachLookupExceptions
struct CustomFirmwareMachLookupExceptionTests {
private func write(_ plist: [String: Any], to url: URL) throws {
try PropertyListSerialization
.data(fromPropertyList: plist, format: .xml, options: 0)
.write(to: url)
}
@Test func `HomeView adds compiler access without widening Campo or removing its sandbox`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "BreadBoard.entitlements")
let profile = "com.apple.private.sandbox.profile:embedded"
try write([profile: "temporary-sandbox",
CustomFirmwareMachLookupExceptions.exceptionKey: CustomFirmwareMachLookupExceptions.services], to: url)
let result = try CustomFirmwareMachLookupExceptions.merge(at: url, services: CustomFirmwareMachLookupExceptions.homeViewServices, verbose: false)
let patched = try #require(PlistComparison.load(url) as? [String: Any])
#expect(result.added == 1)
#expect(patched.count == 2)
#expect(patched[profile] as? String == "temporary-sandbox")
#expect(patched[CustomFirmwareMachLookupExceptions.exceptionKey] as? [String] == CustomFirmwareMachLookupExceptions.services + ["com.apple.MTLCompilerService"])
#expect(!CustomFirmwareMachLookupExceptions.services.contains("com.apple.MTLCompilerService"))
}
@Test func `TV setup adds only PineBoard lookup and preserves its sandbox`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "SetupBackground.entitlements")
try write([
"application-identifier": "com.apple.SetupBackground",
"platform-application": true,
"com.apple.private.security.container-required": true,
CustomFirmwareMachLookupExceptions.exceptionKey: ["com.apple.existing.service"],
], to: url)
try CustomFirmwareMachLookupExceptions.merge(at: url, services: ["com.apple.PineBoardServices"], verbose: false)
let patched = try #require(PlistComparison.load(url) as? [String: Any])
#expect(patched.count == 4)
#expect(patched["application-identifier"] as? String == "com.apple.SetupBackground")
#expect(patched["platform-application"] as? Bool == true)
#expect(patched["com.apple.private.security.container-required"] as? Bool == true)
#expect(patched[CustomFirmwareMachLookupExceptions.exceptionKey] as? [String] == ["com.apple.existing.service", "com.apple.PineBoardServices"])
let repeated = try CustomFirmwareMachLookupExceptions.merge(at: url, services: ["com.apple.PineBoardServices"], verbose: false)
#expect(repeated.added == 0 && repeated.total == 2)
}
@Test func `adds every service when the key is absent`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "Campo.entitlements")
try write(["platform-application": true], to: url)
let outcome = try CustomFirmwareMachLookupExceptions.merge(at: url, verbose: false)
#expect(outcome.added == CustomFirmwareMachLookupExceptions.services.count)
#expect(outcome.total == CustomFirmwareMachLookupExceptions.services.count)
let patched = try PlistComparison.load(url) as? [String: Any]
#expect(patched?[CustomFirmwareMachLookupExceptions.exceptionKey] as? [String]
== CustomFirmwareMachLookupExceptions.services)
#expect(patched?["platform-application"] as? Bool == true)
}
@Test func `keeps existing entries first and does not duplicate`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "Campo.entitlements")
let preexisting = ["com.apple.some.other.service", "com.apple.CARenderServer"]
try write([CustomFirmwareMachLookupExceptions.exceptionKey: preexisting], to: url)
let outcome = try CustomFirmwareMachLookupExceptions.merge(at: url, verbose: false)
#expect(outcome.added == CustomFirmwareMachLookupExceptions.services.count - 1)
let patched = try PlistComparison.load(url) as? [String: Any]
let merged = patched?[CustomFirmwareMachLookupExceptions.exceptionKey] as? [String] ?? []
#expect(Array(merged.prefix(2)) == preexisting)
#expect(merged.filter { $0 == "com.apple.CARenderServer" }.count == 1)
#expect(Set(merged).isSuperset(of: CustomFirmwareMachLookupExceptions.services))
}
@Test func `is idempotent`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "Campo.entitlements")
try write(["get-task-allow": true], to: url)
try CustomFirmwareMachLookupExceptions.merge(at: url, verbose: false)
let once = try Data(contentsOf: url)
let second = try CustomFirmwareMachLookupExceptions.merge(at: url, verbose: false)
#expect(second.added == 0)
#expect(try Data(contentsOf: url) == once)
}
@Test func `refuses an exception key that is not an array`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "Campo.entitlements")
try write([CustomFirmwareMachLookupExceptions.exceptionKey: "com.apple.CARenderServer"], to: url)
#expect(throws: PatcherError.self) {
try CustomFirmwareMachLookupExceptions.merge(at: url, verbose: false)
}
}
@Test(.enabled(if: CustomFirmwarePatchFixtures.entitlementsDonorAvailable))
func `matches the frozen reference on real entitlements`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let key = CustomFirmwarePlistPatchGolden.exceptionKey
#expect(CustomFirmwareMachLookupExceptions.exceptionKey == key)
for donor in CustomFirmwarePatchFixtures.availableEntitlementsDonors {
let name = donor.lastPathComponent
let swiftOutput = directory.appending(path: "swift-\(name).entitlements")
try CustomFirmwarePatchFixtures.dumpEntitlements(of: donor, to: swiftOutput)
let before = try #require(try PlistComparison.load(swiftOutput) as? [String: Any])
let existing = (before[key] as? [String]) ?? []
let outcome = try CustomFirmwareMachLookupExceptions.merge(at: swiftOutput, verbose: false)
let after = try #require(try PlistComparison.load(swiftOutput) as? [String: Any])
// The transform the reference applied: the existing array, then
// every service it did not already carry, in SERVICES order.
let expectedServices = existing
+ CustomFirmwareMachLookupExceptions.services.filter { !existing.contains($0) }
#expect(after[key] as? [String] == expectedServices, "\(name)")
// …and its own count line agreed with that arithmetic.
#expect(
CustomFirmwarePlistPatchGolden.countLine(total: outcome.total, added: outcome.added)
== CustomFirmwarePlistPatchGolden.countLine(
total: expectedServices.count,
added: expectedServices.count - existing.count,
),
"\(name)",
)
// Nothing but that key moved.
var expected = after
if let original = before[key] {
expected[key] = original
} else {
expected[key] = nil
}
let difference = PlistComparison.difference(before, expected)
#expect(difference == nil, "\(name): \(difference ?? "")")
}
}
}
// MARK: - Just enough DER to build and take apart a test IMG4
enum DERTestEncoder {
static func length(_ count: Int) -> Data {
if count < 0x80 {
return Data([UInt8(count)])
}
var bytes: [UInt8] = []
var remaining = count
while remaining > 0 {
bytes.append(UInt8(remaining & 0xFF))
remaining >>= 8
}
bytes.reverse()
return Data([0x80 | UInt8(bytes.count)] + bytes)
}
static func element(tag: UInt8, value: Data) -> Data {
var out = Data([tag])
out.append(length(value.count))
out.append(value)
return out
}
static func sequence(_ elements: [Data]) -> Data {
element(tag: 0x30, value: elements.reduce(into: Data()) { $0.append($1) })
}
static func ia5String(_ text: String) -> Data {
element(tag: 0x16, value: Data(text.utf8))
}
/// Split a top-level SEQUENCE into its children's raw bytes.
static func children(of data: Data) throws -> [Data] {
var offset = 0
func readHeader() throws -> (tag: UInt8, valueStart: Int, valueCount: Int) {
guard offset + 2 <= data.count else { throw CustomFirmwareTestError.commandFailed("short DER") }
let tag = data[offset]
let first = data[offset + 1]
var cursor = offset + 2
var count = Int(first)
if first & 0x80 != 0 {
let byteCount = Int(first & 0x7F)
count = 0
for index in 0 ..< byteCount {
count = (count << 8) | Int(data[cursor + index])
}
cursor += byteCount
}
return (tag, cursor, count)
}
let outer = try readHeader()
var result: [Data] = []
offset = outer.valueStart
let end = outer.valueStart + outer.valueCount
while offset < end {
let child = try readHeader()
result.append(data[offset ..< (child.valueStart + child.valueCount)])
offset = child.valueStart + child.valueCount
}
return result
}
}
// MARK: - CustomFirmwarePostRestoreDeviceTree
struct CustomFirmwarePostRestoreDeviceTreeTests {
@Test(.enabled(if: CustomFirmwarePatchFixtures.deviceTreeAvailable))
func `parse and serialize round trips A real device tree`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let im4p = try CustomFirmwarePatchFixtures.extractDeviceTree(into: directory)
let blob = try IM4P(Data(contentsOf: im4p)).payload()
// Patching to the values already there is a no-op, which is the only
// way to see the parse/serialize pair on its own.
let (patched, changes) = try CustomFirmwarePostRestoreDeviceTree.patchedDeviceTree(blob)
#expect(changes.count == 3)
#expect(patched.count == blob.count)
let (again, noChanges) = try CustomFirmwarePostRestoreDeviceTree.patchedDeviceTree(patched)
#expect(noChanges.isEmpty)
#expect(again == patched)
}
@Test(.enabled(if: CustomFirmwarePatchFixtures.deviceTreeAvailable))
func `rewrites exactly the three restore fatal properties`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let im4p = try CustomFirmwarePatchFixtures.extractDeviceTree(into: directory)
let blob = try IM4P(Data(contentsOf: im4p)).payload()
let (patched, changes) = try CustomFirmwarePostRestoreDeviceTree.patchedDeviceTree(blob)
#expect(changes.map(\.property) == ["model", "target-type", "compatible"])
#expect(changes[0].before == "iPhone99,11")
#expect(changes[0].after == "iPhone17,3")
#expect(changes[1].before == "VPHONE600")
#expect(changes[1].after == "D47")
#expect(changes[2].before == "[VPHONE600AP, iPhone99,11, AppleVirtualPlatformARM]")
// Slot lengths are preserved, so every difference is inside one of the
// three property values — 12 + 10 + 48 bytes at most.
let differing = zip(blob, patched).filter { $0 != $1 }.count
#expect(differing > 0 && differing <= 12 + 10 + 48)
#expect(patched.range(of: Data("D47AP\0VPHONE600AP\0AppleVirtualPlatformARM\0".utf8)) != nil)
#expect(patched.range(of: Data("iPhone17,3\0".utf8)) != nil)
}
@Test(.enabled(if: CustomFirmwarePatchFixtures.deviceTreeAvailable))
func `matches the frozen reference byte for byte on A real device tree`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let source = try CustomFirmwarePatchFixtures.extractDeviceTree(into: directory)
// Two cloudOS IPSWs carry this device tree and they are different
// files, so the golden is looked up by the input's own digest rather
// than by which IPSW the directory listing happened to hand back.
let input = try CustomFirmwarePlistPatchGolden.digest(of: source)
let expected = try #require(
CustomFirmwarePlistPatchGolden.deviceTree[input],
"""
no frozen reference output for a DeviceTree.vphone600ap.im4p with \
digest \(input) — re-derive CustomFirmwarePlistPatchGolden.deviceTree for this \
IPSW before reading a failure here as a patcher bug
""",
)
let swiftOutput = directory.appending(path: "swift.im4p")
try FileManager.default.copyItem(at: source, to: swiftOutput)
let outcome = try CustomFirmwarePostRestoreDeviceTree.patch(at: swiftOutput, verbose: false)
#expect(outcome.wrote)
#expect(outcome.changes.count == 3)
#expect(
try CustomFirmwarePlistPatchGolden.digest(of: swiftOutput) == expected,
"IM4P differs from the frozen reference output",
)
// And the re-run is a no-op, as the reference's was: it printed
// `DT already in target state — no change` and the digest held.
let swiftRerun = try CustomFirmwarePostRestoreDeviceTree.patch(at: swiftOutput, verbose: false)
#expect(!swiftRerun.wrote)
#expect(try CustomFirmwarePlistPatchGolden.digest(of: swiftOutput) == expected)
}
/// The IMG4 path, as far as it can be checked here.
///
/// The real target is `/usr/standalone/firmware/devicetree.img4` on a
/// restored rootfs, which is a signed IMG4 — and no signed IM4M is
/// obtainable offline, so there is no Python-vs-Swift byte comparison for
/// this shape. What is checkable without one is the part that is actually
/// new: the IM4P inside must come out identical to the bare-IM4P run, and
/// every element around it must come back byte for byte, because the
/// manifest and restore info are carried, never re-encoded.
@Test(.enabled(if: CustomFirmwarePatchFixtures.deviceTreeAvailable))
func `preserves everything around the IM 4 P in an IMG 4`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let source = try CustomFirmwarePatchFixtures.extractDeviceTree(into: directory)
let im4pBytes = try Data(contentsOf: source)
// Stand-ins for the manifest and restore info: this test never looks
// inside them, and neither does the patcher.
let manifest = Data((0 ..< 96).map { UInt8(truncatingIfNeeded: $0 * 7 + 3) })
let restoreInfo = Data((0 ..< 32).map { UInt8(truncatingIfNeeded: $0 * 11 + 5) })
let img4 = DERTestEncoder.sequence([
DERTestEncoder.ia5String("IMG4"),
im4pBytes,
DERTestEncoder.element(tag: 0xA0, value: manifest),
DERTestEncoder.element(tag: 0xA1, value: restoreInfo),
])
let img4URL = directory.appending(path: "devicetree.img4")
try img4.write(to: img4URL)
let outcome = try CustomFirmwarePostRestoreDeviceTree.patch(at: img4URL, verbose: false)
#expect(outcome.changes.count == 3)
#expect(outcome.wrote)
// The bare-IM4P run, for comparison.
let bareURL = directory.appending(path: "bare.im4p")
try im4pBytes.write(to: bareURL)
try CustomFirmwarePostRestoreDeviceTree.patch(at: bareURL, verbose: false)
let patchedIM4P = try Data(contentsOf: bareURL)
let children = try DERTestEncoder.children(of: Data(contentsOf: img4URL))
#expect(children.count == 4)
#expect(children[0] == DERTestEncoder.ia5String("IMG4"))
#expect(children[1] == patchedIM4P)
#expect(children[2] == DERTestEncoder.element(tag: 0xA0, value: manifest))
#expect(children[3] == DERTestEncoder.element(tag: 0xA1, value: restoreInfo))
}
@Test(.enabled(if: CustomFirmwarePatchFixtures.deviceTreeAvailable))
func `refuses A payload that is not A device tree`() throws {
let directory = try CustomFirmwarePatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
let url = directory.appending(path: "not-a-dt.im4p")
try IM4P(fourcc: "krnl", description: "test", payload: Data(repeating: 0, count: 64))
.data
.write(to: url)
#expect(throws: PatcherError.self) {
try CustomFirmwarePostRestoreDeviceTree.patch(at: url, verbose: false)
}
}
}