Run a virtual iPhone on an Apple Silicon Mac.
Swift
// CustomFirmwareMobileActivationTests.swift — `-[DeviceType should_hactivate]` -> YES.
//
// The bar here is not "the Swift patcher did something". It is that this port
// and `scripts/patchers/cfw_patch_mobileactivationd.py` produce the same bytes
// from the same input, on the real iOS 27.0 / 24A435 iPhone17,3
// `/usr/libexec/mobileactivationd` in `ipsws/ref_extract/macho_pristine/`, and
// that the result passes `codesign -v` — two references, neither of them this
// code. The Python is gone; what it wrote is frozen digest by digest in
// ``MobileactivationdGolden``, so the comparison outlived it. The comparisons
// are still gated on the pristine binary, which is not in the repo.
//
// Outputs are kept on disk, not in a scratch directory that vanishes, so the
// same comparison can be re-run by hand with `cmp`, `shasum` and `codesign`.
// They go wherever `VPHONE_TEST_ARTIFACTS` points, defaulting to a named
// directory under `TMPDIR` — never inside the repository, and never inside
// `ipsws/ref_extract/`, which is the read-only reference tree.
import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
import VPhonePatchKit
// MARK: - Fixtures
enum MobileactivationdFixture {
/// The package root, derived from this file rather than the working
/// directory, which `swift test` does not promise.
static let repositoryRoot = URL(filePath: #filePath)
.deletingLastPathComponent() // FirmwarePatcherTests
.deletingLastPathComponent() // tests
.deletingLastPathComponent() // <root>
/// The pristine reference binary. Read-only: every test works on a copy.
static let pristine = repositoryRoot
.appending(path: "ipsws/ref_extract/macho_pristine/mobileactivationd")
/// A second real binary that does not contain the method, for the
/// not-found path.
static let launchd = repositoryRoot
.appending(path: "ipsws/ref_extract/macho_pristine/launchd")
static let codesign = URL(filePath: "/usr/bin/codesign")
/// Where comparison artifacts land, so a failure can be picked apart after
/// the run instead of being re-created from scratch.
///
/// Outside the repository by default. `ipsws/ref_extract/` in particular is
/// the pristine reference the whole suite compares against; nothing here
/// ever writes inside it.
static let artifacts: URL = {
if let override = ProcessInfo.processInfo.environment["VPHONE_TEST_ARTIFACTS"],
!override.isEmpty
{
return URL(filePath: override).appending(path: "CustomFirmwareMobileactivationdTests")
}
return FileManager.default.temporaryDirectory.appending(path: "CustomFirmwareMobileactivationdTests")
}()
static func exists(_ url: URL) -> Bool {
FileManager.default.fileExists(atPath: url.path)
}
static var hasPristine: Bool {
exists(pristine)
}
static var hasLaunchd: Bool {
exists(launchd)
}
static var hasCodesign: Bool {
hasPristine && exists(codesign)
}
/// SHA-256 as `shasum -a 256` prints it, so a digest asserted here can be
/// taken again from a shell over the same file.
static func digest(of url: URL) throws -> String {
try Data(SHA256.hash(data: Data(contentsOf: url))).hex
}
/// A named, writable copy of the pristine binary under ``artifacts``.
static func copyOfPristine(named name: String) throws -> URL {
try FileManager.default.createDirectory(at: artifacts, withIntermediateDirectories: true)
let destination = artifacts.appending(path: name)
if exists(destination) {
try FileManager.default.removeItem(at: destination)
}
try FileManager.default.copyItem(at: pristine, to: destination)
return destination
}
@discardableResult
static func run(_ tool: URL, _ arguments: [String]) throws -> (status: Int32, output: String) {
let process = Process()
process.executableURL = tool
process.arguments = arguments
process.currentDirectoryURL = repositoryRoot
let pipe = Pipe()
process.standardOutput = pipe
process.standardError = pipe
try process.run()
let output = pipe.fileHandleForReading.readDataToEndOfFile()
process.waitUntilExit()
return (process.terminationStatus, String(decoding: output, as: UTF8.self))
}
}
// MARK: - The frozen reference
/// What `scripts/patchers/` produced on this fixture, recorded before it was
/// deleted.
///
/// Every value below was taken at repo commit `78cbeea`, with
/// `.venv/bin/python3` driving `scripts/patchers/`, over the real iOS 27.0 /
/// 24A435 / iPhone17,3 `mobileactivationd` whose own digest is ``pristine``.
enum MobileactivationdGolden {
/// `shasum -a 256 ipsws/ref_extract/macho_pristine/mobileactivationd`
static let pristine = "89233513ce696cd01285f3432f3bcadd065cee07ac73bc5714836d13f24702d8"
/// `.venv/bin/python3 scripts/patchers/cfw.py patch-mobileactivationd <clone>`
/// — `ldrb w0, [x0, #0x14] ; ret` at 0x2EC368 replaced with
/// `mov x0, #1 ; ret`, signature left stale, exactly as `cfw_install.sh`
/// ran it before `ldid_sign`. Its stdout reported
/// `Found via symtab: va:0x1002EC368 -> foff:0x2EC368`.
static let patched = "9f26bf92a2a80133e763c6426949e262ad26d51485b5184548744bd37e1f4095"
/// The IMP the Python's symbol-table anchor resolved to, from that stdout.
static let impFileOffset = 0x2EC368
/// ``patched``, then
/// `.venv/bin/python3 -c 'import sys; sys.path.insert(0, "scripts");
/// from patchers.cfw_macho_codesign import reattest_modified_offsets;
/// reattest_modified_offsets(sys.argv[1], [0x2ec368, 0x2ec36c])'`
/// — which reported `wrote cd_index=0 slot 748 (907503ed.. -> 2ea7d714..)`.
static let patchedAndReattested =
"df16f1ab4f5e7a3ad7a3a8774d54c0330a1b38d9568ad233e20936e48674973f"
/// The one code slot that re-attestation rewrote.
static let reattestedSlot = 748
}
// MARK: - Shell Runner
/// A shell entry point for the patcher, standing in for `vphone-patch` until
/// that binary exists (plan §3.9).
///
/// ```
/// VPHONE_PATCH_FILE=<binary> swift test --filter runPatcherFromEnvironment
/// ```
///
/// patches that one file in place and prints where it landed. It exists so the
/// comparison against ``MobileactivationdGolden``, and the run-it-twice check,
/// can be driven from a shell over files a human picked — `shasum -a 256` on
/// the result reads the same digests — rather than living only inside
/// assertions this same process wrote. Without the variable it does not run.
///
/// `VPHONE_PATCH_RESIGN=0` skips re-attestation, which is what reproduces
/// ``MobileactivationdGolden/patched`` exactly.
@Suite("mobileactivationd should_hactivate — shell runner")
struct CustomFirmwareMobileActivationRunnerTests {
@Test(.enabled(if: ProcessInfo.processInfo.environment["VPHONE_PATCH_FILE"] != nil))
func `run patcher from environment`() throws {
let environment = ProcessInfo.processInfo.environment
let path = try #require(environment["VPHONE_PATCH_FILE"])
let resign = environment["VPHONE_PATCH_RESIGN"] != "0"
let report = try CustomFirmwareMobileActivation.patch(fileAt: URL(filePath: path), resign: resign)
print(
"RUNNER outcome=\(report.outcome.rawValue)"
+ " sitesWritten=\(report.sitesWritten)"
+ " va=0x\(String(report.anchor.virtualAddress, radix: 16, uppercase: true))"
+ " foff=0x\(String(report.anchor.fileOffset, radix: 16, uppercase: true))"
+ " section=\(report.anchor.section)"
+ " anchor=\(report.anchor.source.rawValue)"
+ " rehashes=\(report.slotRehashes.count)",
)
for rehash in report.slotRehashes {
print("RUNNER \(rehash.description)")
print("RUNNER slot@0x\(String(rehash.hashFileOffset, radix: 16, uppercase: true))"
+ " = \(rehash.after.hex)")
}
}
}
// MARK: - Anchoring
@Suite("mobileactivationd should_hactivate — anchoring")
struct CustomFirmwareMobileActivationAnchorTests {
/// The two routes are independent — `LC_SYMTAB` on one side, the
/// `__objc_methname` -> `__objc_selrefs` -> relative method list walk on the
/// other — and they agree. That agreement is the evidence the anchor is the
/// method and not something that merely sorts first.
@Test(.enabled(if: MobileactivationdFixture.hasPristine))
func `both anchors resolve and agree`() throws {
let data = try Data(contentsOf: MobileactivationdFixture.pristine)
let segments = MachOParser.parseSegments(from: data)
let bySymbol = try #require(
CustomFirmwareMobileActivation.symbolVirtualAddress(in: data),
"LC_SYMTAB should carry -[DeviceType should_hactivate]",
)
let byMetadata = try #require(
CustomFirmwareMobileActivation.objcMetadataVirtualAddress(in: data, segments: segments),
"the ObjC method lists should carry the same IMP",
)
#expect(bySymbol == byMetadata)
let anchor = try CustomFirmwareMobileActivation.locateIMP(in: data)
#expect(anchor.source == .symbolTableAndObjCMetadata)
#expect(anchor.virtualAddress == bySymbol)
#expect(anchor.section == "__TEXT,__text", "the IMP must be code, not data")
#expect(
MachOParser.vaToFileOffset(anchor.virtualAddress, segments: segments) == anchor.fileOffset,
)
}
/// The selector search must not settle for a suffix of a longer string.
///
/// `DeviceType`'s ivar is `_should_hactivate`, so a plain search for
/// `should_hactivate\0` — what `scripts/patchers/cfw_patch_mobileactivationd.py`
/// did at 78cbeea — lands inside the ivar's name, finds no selref for it,
/// and gives up. The NUL-preceded match finds the real selector instead.
/// The naive search is reproduced below rather than described, so the
/// contrast is measured here and does not depend on that Python existing.
@Test(.enabled(if: MobileactivationdFixture.hasPristine))
func `selector lookup skips the ivar name`() throws {
let data = try Data(contentsOf: MobileactivationdFixture.pristine)
let sections = MachOParser.parseSections(from: data)
let selectorVA = try #require(
CustomFirmwareMobileActivation.selectorVirtualAddress(in: data, sections: sections),
)
let methname = try #require(sections["__TEXT,__objc_methname"])
let start = Int(methname.fileOffset)
let offset = start + Int(selectorVA - methname.address)
#expect(data[offset - 1] == 0, "the selector must start a string, not end one")
// That naive search finds an earlier, wrong offset on this binary — so
// this is not an assertion that passes either way.
let needle = Data(CustomFirmwareMobileActivation.selector.utf8) + Data([0])
let naive = try #require(data.range(of: needle)?.lowerBound)
#expect(naive < offset)
#expect(data[naive - 1] == UInt8(ascii: "_"))
}
/// A binary without the method is a hard stop, not a silent skip: every
/// caller of this patch needs it to have happened.
@Test(.enabled(if: MobileactivationdFixture.hasLaunchd))
func `missing method throws`() throws {
let data = try Data(contentsOf: MobileactivationdFixture.launchd)
#expect(throws: PatcherError.self) {
try CustomFirmwareMobileActivation.locateIMP(in: data)
}
}
/// The replacement is assembled, not transcribed. `ARM64Encoder`'s MOVZ is
/// asserted against keystone in `ARM64EncoderTests`; this pins that the
/// patch asks it for the right instruction, and that the pair reads back as
/// `mov x0, #1 ; ret`.
@Test func `replacement is mov X 0 one then ret`() throws {
let bytes = try CustomFirmwareMobileActivation.replacementBytes()
#expect(bytes.count == 8)
#expect(bytes == ARM64.movX0_1 + ARM64.ret)
let decoded = ARM64Disassembler().disassemble(bytes, at: 0, count: 2)
#expect(decoded.count == 2)
#expect(decoded[0].mnemonic == "mov")
#expect(decoded[1].mnemonic == "ret")
let operands = try #require(decoded[0].detail?.operands)
#expect(operands.count == 2)
#expect(operands[1].type == .immediate)
#expect(operands[1].imm == 1)
#expect(ARM64Disassembler().firstRegisterName(decoded[0]) == "x0")
}
/// Both words of the getter are re-hashed, so a getter that straddles a
/// page boundary does not leave the second page's slot stale.
@Test func `touched offsets cover both words`() throws {
let anchor = CustomFirmwareMobileActivation.Anchor(
virtualAddress: 0x1_0000_0FFC,
fileOffset: 0xFFC,
source: .symbolTable,
section: "__TEXT,__text",
)
let bytes = try CustomFirmwareMobileActivation.replacementBytes()
let offsets = CustomFirmwareMobileActivation.touchedOffsets(anchor, bytes)
#expect(offsets == [0xFFC, 0x1000])
#expect(Set(offsets.map { $0 / 4096 }).count == 2, "the two words are on different pages")
}
}
// MARK: - Byte parity with the frozen reference
@Suite("mobileactivationd should_hactivate — parity and idempotence")
struct CustomFirmwareMobileActivationParityTests {
/// The fixture the frozen digests were taken over. Without this a digest
/// mismatch below would read as a patcher bug when the real cause is a
/// different firmware's `mobileactivationd`.
@Test(.enabled(if: MobileactivationdFixture.hasPristine))
func `fixture matches the goldens`() throws {
#expect(
try MobileactivationdFixture.digest(of: MobileactivationdFixture.pristine)
== MobileactivationdGolden.pristine,
"""
this is not the 24A435 mobileactivationd MobileactivationdGolden \
was recorded from — re-derive the goldens before reading a failure \
below as a patcher bug
""",
)
}
/// Bar 1: identical bytes out of identical bytes in, against the
/// implementation that was replaced.
///
/// `resign: false` because the Python patcher did not re-sign — the
/// `ldid_sign` in `cfw_install.sh` does — so this compares like with like.
@Test(.enabled(if: MobileactivationdFixture.hasPristine))
func `matches the frozen reference bytes`() throws {
let swiftFile = try MobileactivationdFixture.copyOfPristine(named: "swift.bin")
let report = try CustomFirmwareMobileActivation.patch(fileAt: swiftFile, resign: false, log: nil)
#expect(report.outcome == .patched)
#expect(report.sitesWritten == 1)
#expect(report.slotRehashes.isEmpty, "resign: false must not touch the signature")
#expect(
try MobileactivationdFixture.digest(of: swiftFile) == MobileactivationdGolden.patched,
"Swift output must be byte-identical to the reference's",
)
// And the one site it changed is the one the reference's symtab anchor
// named, and the one this patch claims.
let record = try #require(report.record)
let pristine = try Data(contentsOf: MobileactivationdFixture.pristine)
let patched = try Data(contentsOf: swiftFile)
let differing = (0 ..< pristine.count).filter { patched[$0] != pristine[$0] }
#expect(!differing.isEmpty)
#expect(differing.allSatisfy { record.fileOffset ..< record.fileOffset + 8 ~= $0 })
#expect(record.fileOffset == MobileactivationdGolden.impFileOffset)
#expect(record.patchID == "system-mobileactivationd-boot-should_hactivate")
#expect(record.component == "mobileactivationd")
#expect(record.patchedBytes == ARM64.movX0_1 + ARM64.ret)
#expect(record.beforeDisasm.hasSuffix("ret"))
}
/// Bar 2: the re-attested output matches the reference's own
/// re-attestation, slot hash for slot hash, and `codesign -v` accepts it.
///
/// The raw patch does not: `codesign` rejects it, which is what makes this
/// step load-bearing rather than decorative.
@Test(.enabled(if: MobileactivationdFixture.hasCodesign))
func `reattested output matches the frozen reference and verifies`() throws {
let swiftFile = try MobileactivationdFixture.copyOfPristine(named: "swift-resigned.bin")
let report = try CustomFirmwareMobileActivation.patch(fileAt: swiftFile, resign: true, log: nil)
let rehash = try #require(report.slotRehashes.first)
#expect(report.slotRehashes.count == 1)
#expect(rehash.pageIndex == MobileactivationdGolden.reattestedSlot)
let swiftBytes = try Data(contentsOf: swiftFile)
#expect(
Data(SHA256.hash(data: swiftBytes)).hex == MobileactivationdGolden.patchedAndReattested,
"re-attested output must match the reference's",
)
// The slot hash itself, not just the file: read it back out.
let slot = rehash.hashFileOffset ..< rehash.hashFileOffset + rehash.after.count
#expect(swiftBytes[slot] == rehash.after)
let verified = try MobileactivationdFixture.run(
MobileactivationdFixture.codesign, ["-v", swiftFile.path],
)
#expect(verified.status == 0, "codesign -v rejected the patched binary: \(verified.output)")
// The contrast: without re-attestation it is rejected.
let unsigned = try MobileactivationdFixture.copyOfPristine(named: "swift-unsigned.bin")
try CustomFirmwareMobileActivation.patch(fileAt: unsigned, resign: false, log: nil)
let rejected = try MobileactivationdFixture.run(
MobileactivationdFixture.codesign, ["-v", unsigned.path],
)
#expect(rejected.status != 0, "an un-re-attested patch should not verify")
}
/// Bar 3. A second run recognises its own output and writes nothing —
/// neither an error nor a double-apply. `8eb6c8b` fixed exactly this class
/// of bug for the DSC gates; it does not get to come back here.
@Test(.enabled(if: MobileactivationdFixture.hasPristine))
func `second run changes nothing`() throws {
let file = try MobileactivationdFixture.copyOfPristine(named: "swift-idempotent.bin")
let first = try CustomFirmwareMobileActivation.patch(fileAt: file, log: nil)
#expect(first.outcome == .patched)
let afterFirst = try Data(contentsOf: file)
let second = try CustomFirmwareMobileActivation.patch(fileAt: file, log: nil)
#expect(second.outcome == .alreadyPatched)
#expect(second.sitesWritten == 0)
#expect(second.record == nil)
#expect(second.slotRehashes.isEmpty, "the slot was already correct")
#expect(second.anchor == first.anchor)
#expect(try Data(contentsOf: file) == afterFirst)
let third = try CustomFirmwareMobileActivation.patch(fileAt: file, log: nil)
#expect(third.outcome == .alreadyPatched)
#expect(try Data(contentsOf: file) == afterFirst)
}
/// A patched-but-not-re-attested binary — what the Python left behind, and
/// what ``MobileactivationdGolden/patched`` is the digest of — is repaired
/// on the next run rather than reported as already done and left to be
/// SIGKILLed on first page-in.
@Test(.enabled(if: MobileactivationdFixture.hasPristine))
func `rerun repairs A stale slot`() throws {
let file = try MobileactivationdFixture.copyOfPristine(named: "swift-stale-slot.bin")
try CustomFirmwareMobileActivation.patch(fileAt: file, resign: false, log: nil)
let repaired = try CustomFirmwareMobileActivation.patch(fileAt: file, resign: true, log: nil)
#expect(repaired.outcome == .alreadyPatched)
#expect(repaired.slotRehashes.count == 1, "the stale slot must be recomputed")
#expect(repaired.record == nil, "no code bytes changed the second time")
}
/// A dry run reports the site and leaves the file exactly as it found it.
@Test(.enabled(if: MobileactivationdFixture.hasPristine))
func `dry run writes nothing`() throws {
let file = try MobileactivationdFixture.copyOfPristine(named: "swift-dry-run.bin")
let before = try Data(contentsOf: file)
let report = try CustomFirmwareMobileActivation.patch(fileAt: file, dryRun: true, log: nil)
#expect(report.outcome == .wouldPatch)
#expect(report.sitesWritten == 0)
#expect(report.anchor.section == "__TEXT,__text")
#expect(try Data(contentsOf: file) == before)
}
}