Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

feat(cfw): port the six Mach-O patchers, and take fw_prepare.sh off Python

Lakr78cbeea4f7c2
diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.md
index 4fc496a2..75dbe2f5 100644
--- a/research/0_binary_patch_comparison.md
+++ b/research/0_binary_patch_comparison.md
@@ -262,6 +262,58 @@ addresses (49 gates each, zero verdict differences).
cache-shaped file in the chunks directory turns a working patch into a hard
abort. Fail-closed, and left alone deliberately.
+### Swift port status — the six independent Mach-O patchers (2026-09-23)
+
+Rows 1, 2, 3, 5 and 13 above, plus the EXP `watchdogd` patch, now have Swift
+implementations under `sources/FirmwarePatcher/CFW/Patches/`. The patches did not
+change. Each was run against its Python on two `cp -c` clones of the real 24A435
+binary in `ipsws/ref_extract/macho_pristine/`, both with re-attestation off (what
+the Python emits) and on (against `cfw_macho_codesign.reattest_modified_offsets`).
+
+| Python | Swift | Sites | Parity on the real binary |
+| --- | --- | --- | --- |
+| `cfw_patch_seputil.py` | `CFWSeputil` | 1 (+1 slot) | `%s`→`AA` at `0x1BDD2`; sha256 `75dc86f8…` both sides. Re-attested: slot 27 identical. Anchored on the whole `__cstring` literal plus the `adrp`+`add` that builds it, not the Python's file-wide `find`. |
+| `cfw_patch_cache_loader.py` | `CFWCacheLoaderPatcher` | 1 (+1 slot, opt-in) | `cbz x0 @0xC7C` → `nop`; sha256 `17c5b00c…` both sides, 4 bytes differ from pristine. |
+| `cfw_patch_mobileactivationd.py` | `CFWMobileactivationd` | 1 (+1 slot) | `-[DeviceType should_hactivate]` at `0x2EC368`; sha256 `9f26bf92…` both sides. Re-attested: slot 748 identical. The Python's symbol match is a substring search that sees four candidates on this image; the Swift matches the exact selector and cross-checks ObjC metadata. |
+| `cfw_patch_jetsam.py` | `CFWJetsamPatcher` | 1 | `cbz w0 @0xFA98` → `b` (`launchd`); sha256 `cae806f5…` both sides. |
+| `cfw_patch_watchdogd.py` | `CFWWatchdogd` | 2 × 2 insns + 2 slots | Sites at `0x100004754` and `0x10000AB30`, slots 4 and 10; sha256 `963cd445…` both sides, `codesign -v` passes. |
+| `cfw_patch_diskimagesiod.py` | `CFWDiskimagesiod` | 1 (+1 slot) | `isMountComplete…` IMP at `0x320C0`, found through the relative method list; sha256 `41daf01d…` both sides. Re-attested: slot 50 identical. |
+
+**Every port is idempotent, and three of the Pythons are not.** A second Python
+run over its own output walks past the first patch and changes something else:
+`cache_loader` NOPs the `cbnz x0 @0xC84` log-file guard, `jetsam` rewrites the
+`b.ne @0xFAB0` in the same return block, and `seputil` exits 1. The shell never
+hit this because it always copies from the `.bak` first. The Swift reports
+`already patched` and writes nothing, which is what the in-place call site in
+`CryptexFilesystemPatcherGuestPayload` needs.
+
+**Wired in.** `CryptexFilesystemPatcherGuestPayload` now calls
+`CFWCacheLoaderPatcher` and `CFWMobileactivationd` in process instead of
+spawning `cfw.py`. The shell call sites (`cfw_install*.sh`, `cfw-kit`,
+`patch_hv_vmm_userland.sh`) still run the Python until a `vphone-cli cfw` verb
+replaces them.
+
+**A defect that review found and this branch fixed:** `CFWCacheLoaderPatcher`
+trapped on every patch with logging on, which is the default. The before/after
+window starts two instructions ahead of the gate, and it converted that negative
+delta with `UInt64(Int)`, which traps even under `-O`. Every test passed
+`log: nil`, so none reached it. Now covered by `loggingPathDoesNotTrap`.
+
+**Known, not fixed** (all LOW, none changes a byte on these binaries):
+
+* A Mach-O truncated to about 64 bytes makes `diskimagesiod` and `watchdogd`
+ trap in the shared `MachOParser` (`BinaryBuffer.swift:9` precondition) instead
+ of throwing.
+* `CFWCacheLoaderPatcher.flagSetterOnResult` accepts a flag-setting instruction
+ with `x0`/`w0` in any operand, including as the destination.
+* `CFWMobileactivationd`'s ObjC cross-check is scoped to the selector, not the
+ class: it takes the first relative-method-list entry with that name.
+* `CFWJetsamPatcher`'s `.alreadyPatched` is silent. If a later firmware emits an
+ unconditional `b` into the return block ahead of the real gate, it would read
+ as already patched.
+* `CFWWatchdogdTests.swift` converts a VA to a file offset by subtracting the
+ arm64 image base as a constant, in a test only.
+
### Installed Components
| # | Component | Description | Regular | Dev | JB |
diff --git a/scripts/fw_prepare.sh b/scripts/fw_prepare.sh
index 9e8d527b..74877ca6 100755
--- a/scripts/fw_prepare.sh
+++ b/scripts/fw_prepare.sh
@@ -87,6 +87,9 @@ resolve_vphone_binary() {
return 1
}
+# Only ever used to name a cache file, so a short hash is enough. There used to
+# be a Python third branch here for hosts with neither tool; shasum ships with
+# macOS system Perl and this project is macOS-only, so it could not run.
source_hash_suffix() {
local src="$1"
if command -v shasum >/dev/null 2>&1; then
@@ -94,12 +97,7 @@ source_hash_suffix() {
elif command -v sha256sum >/dev/null 2>&1; then
printf '%s' "$src" | sha256sum | awk '{print substr($1, 1, 12)}'
else
- "$PYTHON3" - "$src" <<'PY'
-import hashlib
-import sys
-
-print(hashlib.sha256(sys.argv[1].encode("utf-8")).hexdigest()[:12])
-PY
+ die "neither 'shasum' nor 'sha256sum' found — cannot derive a cache name"
fi
}
@@ -159,182 +157,37 @@ style_status() {
esac
}
+# The firmware support matrix — the README's "Tested Environments" table joined
+# against what Apple still serves — lives in VPhoneCore/VPhoneFirmwareMatrix.swift
+# now. The shell keeps the half it is good at: running `ipsw` and handing the
+# output over in DOWNLOADABLE_IPSW_URLS, the same variable the Python read, so
+# the contract between the two halves did not change.
+#
+# Colour is decided per stream inside the callee, from NO_COLOR, CLICOLOR_FORCE
+# and isatty: `fw list` styles stdout, `fw resolve` styles stderr (its stdout is
+# the $( ) capture below). That only stays right because the binary inherits
+# this script's descriptors — do not add a pipe or a tee.
+firmware_matrix_cli() {
+ resolve_vphone_binary vphone-cli \
+ || die "cannot find vphone-cli for the firmware matrix — run 'make build'"
+}
+
list_firmwares() {
- local device="$1" readme_path="$2"
- local downloadable_urls
+ local device="$1" readme_path="$2" cli downloadable_urls
+ # Separate from `local`, which would swallow the substitution's status.
+ cli="$(firmware_matrix_cli)"
downloadable_urls="$(downloadable_ipsw_urls "$device")"
- DOWNLOADABLE_IPSW_URLS="$downloadable_urls" "$PYTHON3" - "$device" "$readme_path" <<'PY'
-import os
-import re
-import sys
-
-device = sys.argv[1]
-readme_path = sys.argv[2]
-
-def supports_color(stream):
- return not os.environ.get("NO_COLOR") and (stream.isatty() or os.environ.get("CLICOLOR_FORCE") == "1")
-
-def styled_status(status, stream):
- text = f"{status:<11}"
- if not supports_color(stream):
- return text
- colors = {
- "Supported": "\033[32m",
- "Not Tested": "\033[33m",
- "Unsupported": "\033[31m",
- }
- color = colors.get(status)
- return f"{color}{text}\033[0m" if color else text
-
-def load_supported_pairs(readme_path, device):
- supported = set()
- device_suffix = device.removeprefix("iPhone")
- in_section = False
- try:
- with open(readme_path, "r", encoding="utf-8") as handle:
- for line in handle:
- if line.startswith("## Tested Environments"):
- in_section = True
- continue
- if in_section and line.startswith("## "):
- break
- if not in_section:
- continue
- for match in re.finditer(r"`(?P<device>\d+,\d+)_(?P<version>[^_`]+)_(?P<build>[A-Za-z0-9]+)`", line):
- if match.group("device") == device_suffix:
- supported.add((match.group("version"), match.group("build")))
- except FileNotFoundError:
- return supported
- return supported
-
-supported_pairs = load_supported_pairs(readme_path, device)
-rows = []
-for line in os.environ.get("DOWNLOADABLE_IPSW_URLS", "").splitlines():
- match = re.search(
- rf"/({re.escape(device)}_(?P<version>[^_]+)_(?P<build>[A-Za-z0-9]+)_Restore\.ipsw)$",
- line.strip(),
- )
- if match:
- rows.append((match.group("version"), match.group("build"), line.strip()))
-
-if not rows:
- print(f"No downloadable IPSWs found for {device}", file=sys.stderr)
- sys.exit(1)
-
-def version_key(version):
- parts = []
- for item in version.split("."):
- try:
- parts.append(int(item))
- except ValueError:
- parts.append(item)
- return tuple(parts)
-
-rows = sorted(set(rows), key=lambda row: (version_key(row[0]), row[1]), reverse=True)
-print(f"Available downloadable IPSWs for {device}:")
-print("")
-print(
- "Status:",
- styled_status("Supported", sys.stdout),
- styled_status("Not Tested", sys.stdout),
- styled_status("Unsupported", sys.stdout),
-)
-print("")
-print(f"{'VERSION':<12} {'BUILD':<10} STATUS")
-for version, build, url in rows:
- status = "Supported" if (version, build) in supported_pairs else "Not Tested"
- print(f"{version:<12} {build:<10} {styled_status(status, sys.stdout)}")
-PY
+ DOWNLOADABLE_IPSW_URLS="$downloadable_urls" \
+ "$cli" fw list --device "$device" --readme "$readme_path"
}
resolve_selector_from_downloads() {
- local device="$1" version="$2" build="$3" readme_path="$4"
- local downloadable_urls
+ local device="$1" version="$2" build="$3" readme_path="$4" cli downloadable_urls
+ cli="$(firmware_matrix_cli)"
downloadable_urls="$(downloadable_ipsw_urls "$device")"
- DOWNLOADABLE_IPSW_URLS="$downloadable_urls" "$PYTHON3" - "$device" "$version" "$build" "$readme_path" <<'PY'
-import os
-import re
-import sys
-
-device, version, build, readme_path = sys.argv[1:5]
-
-def supports_color(stream):
- return not os.environ.get("NO_COLOR") and (stream.isatty() or os.environ.get("CLICOLOR_FORCE") == "1")
-
-def styled_status(status, stream):
- text = status
- if not supports_color(stream):
- return text
- colors = {
- "Supported": "\033[32m",
- "Not Tested": "\033[33m",
- "Unsupported": "\033[31m",
- }
- color = colors.get(status)
- return f"{color}{text}\033[0m" if color else text
-
-def load_supported_pairs(readme_path, device):
- supported = set()
- device_suffix = device.removeprefix("iPhone")
- in_section = False
- try:
- with open(readme_path, "r", encoding="utf-8") as handle:
- for line in handle:
- if line.startswith("## Tested Environments"):
- in_section = True
- continue
- if in_section and line.startswith("## "):
- break
- if not in_section:
- continue
- for match in re.finditer(r"`(?P<device>\d+,\d+)_(?P<version>[^_`]+)_(?P<build>[A-Za-z0-9]+)`", line):
- if match.group("device") == device_suffix:
- supported.add((match.group("version"), match.group("build")))
- except FileNotFoundError:
- return supported
- return supported
-
-supported_pairs = load_supported_pairs(readme_path, device)
-matches = []
-for line in os.environ.get("DOWNLOADABLE_IPSW_URLS", "").splitlines():
- match = re.search(
- rf"/({re.escape(device)}_(?P<version>[^_]+)_(?P<build>[A-Za-z0-9]+)_Restore\.ipsw)$",
- line.strip(),
- )
- if not match:
- continue
- entry_version = match.group("version")
- entry_build = match.group("build")
- if version and entry_version != version:
- continue
- if build and entry_build != build:
- continue
- matches.append((entry_version, entry_build, line.strip()))
-
-if not matches:
- prefix = styled_status("Unsupported", sys.stderr)
- if version and build:
- print(f"{prefix}: no downloadable IPSW matched device={device} version={version} build={build}", file=sys.stderr)
- elif build:
- print(f"{prefix}: no downloadable IPSW matched device={device} build={build}", file=sys.stderr)
- else:
- print(f"{prefix}: no downloadable IPSW matched device={device} version={version}", file=sys.stderr)
- sys.exit(1)
-
-if version and not build:
- builds = sorted({item[1] for item in matches})
- if len(builds) > 1:
- print(f"Version {version} is ambiguous for {device}; specify one of these builds:", file=sys.stderr)
- print(f"{'BUILD':<10} STATUS", file=sys.stderr)
- for item in sorted(set(matches), key=lambda row: row[1], reverse=True):
- status = "Supported" if (item[0], item[1]) in supported_pairs else "Not Tested"
- print(f"{item[1]:<10} {styled_status(status, sys.stderr)}", file=sys.stderr)
- sys.exit(2)
-
-selected = sorted(set(matches), key=lambda row: row[1], reverse=True)[0]
-status = "Supported" if (selected[0], selected[1]) in supported_pairs else "Not Tested"
-print("\t".join(selected + (status,)))
-PY
+ DOWNLOADABLE_IPSW_URLS="$downloadable_urls" \
+ "$cli" fw resolve --device "$device" --version "$version" \
+ --build "$build" --readme "$readme_path"
}
download_file() {
@@ -548,7 +401,6 @@ IPHONE_BUILD="${IPHONE_BUILD:-}"
IPHONE_SOURCE="${IPHONE_SOURCE:-}"
CLOUDOS_SOURCE="${CLOUDOS_SOURCE:-}"
IPSW_DIR="${IPSW_DIR:-${SCRIPT_DIR}/../ipsws}"
-PYTHON3="${VPHONE_PYTHON:-python3}"
POSITIONAL=()
while [[ $# -gt 0 ]]; do
diff --git a/sources/FirmwarePatcher/CFW/Patches/CFWCacheloader.swift b/sources/FirmwarePatcher/CFW/Patches/CFWCacheloader.swift
new file mode 100644
index 00000000..44814fa2
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/Patches/CFWCacheloader.swift
@@ -0,0 +1,741 @@
+// CFWCacheloader.swift — open launchd_cache_loader's unsecure-cache gate.
+//
+// Swift port of `scripts/patchers/cfw_patch_cache_loader.py`, driven today by
+// `cfw.py patch-launchd-cache-loader <binary>`.
+//
+// What the binary does. `/usr/libexec/launchd_cache_loader` builds the XPC
+// service cache launchd loads at boot. Before it will accept a cache that did
+// not come from the sealed system volume it looks for the boot-arg
+// `launchd_unsecure_cache=` in `kern.bootargs`:
+//
+// adrp x0, "kern.bootargs" ; add x0, x0, #… ; add x1, sp, #…
+// bl <sysctl-by-name helper>
+// cbz x0, no_bootargs
+// ldr x0, [sp, #…] ; cbz x0, no_bootargs
+// adrp x1, "launchd_unsecure_cache=" ; add x1, x1, #… <- the string xref
+// mov x2, #0
+// bl <boot-arg lookup> <- the call
+// cbz x0, skip_unsecure_cache <- THE GATE
+// … <- "Using unsecure cache: %s"
+//
+// On a VM there is no way to set that boot-arg, so the gate always takes the
+// skip and the loader refuses anything but the stock cache. NOP'ing the one
+// `cbz` makes the unsecure path unconditional, which is what lets a MODIFIED
+// `/System/Library/xpc/launchd.plist` be loaded — the only reason this patch
+// exists (`research/0_binary_patch_comparison.md`, "Allow modified
+// launchd.plist"). A flavour that does not rewrite `launchd.plist` does not
+// need it; see `cfw-kit/lib/base_stages.sh:stage_launchd_cache_loader`.
+//
+// Nothing is hardcoded. The boot-arg string is found by content in the Mach-O's
+// own string sections, its ADRP+ADD xref is recovered from Capstone-decoded
+// operands, the call after it is found by control flow, and the gate is the
+// conditional branch that consumes that call's return register. The replacement
+// is `ARM64.nop`, which ARM64Constants generated with keystone.
+//
+// Two deliberate divergences from the Python, both documented at the site:
+//
+// 1. IDEMPOTENCE. The Python is not idempotent. On a second run it walks past
+// the NOP it wrote and takes the *next* conditional branch — `cbnz x0,`
+// over the log-file `fopen` — so it silently re-opens and truncates the log
+// on every cache build. This port recognises its own output and stops.
+// `CryptexFilesystemPatcher.patchLaunchdCacheLoader` patches in place with
+// no `.bak` restore, so that second run is reachable today.
+// 2. REFUSAL OVER GUESSING. The Python takes the first conditional branch it
+// sees after the call, whatever it tests. This port checks that the branch
+// really consumes the call's result and jumps forward out of the unsecure
+// path, and throws when it does not, rather than NOP'ing an unrelated
+// branch on a firmware whose shape has moved.
+//
+// Re-signing is OFF by default, which is what keeps this byte-identical to the
+// Python: every shipped caller re-signs the whole binary afterwards (`ldid_sign`
+// in `cfw_install*.sh`, `VPhoneSigner.sign` in the Swift call site), so slot
+// hashes written here would be thrown away. A caller that does NOT re-sign must
+// pass `reattestsCodeSignature: true` or ship a binary TXM will SIGKILL on the
+// first page-in of the patched page.
+
+import Capstone
+import Foundation
+
+/// NOPs the `launchd_unsecure_cache=` gate in `/usr/libexec/launchd_cache_loader`.
+public enum CFWCacheLoaderPatcher {
+ // MARK: - Identity
+
+ /// Component name, matching the Python's `records.set_group`.
+ public static let component = "launchd_cache_loader"
+
+ /// Record identity, matching the Python's `records.site` label so a captured
+ /// reference and this port sort together.
+ public static let patchID = "launchd_cache_loader.unsecure_cache_gate"
+
+ /// Substrings that name the gate's boot-arg, most specific first. The same
+ /// list the Python carries: the later three are there for a firmware that
+ /// renames the boot-arg, and have never matched on a shipping build.
+ public static let anchorTokens = ["unsecure_cache", "unsecure", "cache_valid", "validation"]
+
+ // MARK: - Search windows
+
+ /// How far an ADD may sit from the ADRP it completes. Both are emitted by
+ /// the same relocation pair, so the compiler keeps them close; 8 is the
+ /// Python's window.
+ static let maxADRPToADDInstructions = 8
+
+ /// How far past the string xref to look for the call it is an argument to.
+ static let maxInstructionsToCall = 16
+
+ /// How far past that call the branch on its result may sit.
+ static let maxInstructionsAfterCall = 8
+
+ /// The no-call fallback window, used only when no call follows the xref.
+ static let maxFallbackInstructions = 32
+
+ // MARK: - Results
+
+ /// The boot-arg string the gate is built around, and the code that loads it.
+ public struct Anchor: Sendable, Equatable {
+ /// Which of ``anchorTokens`` matched.
+ public let token: String
+ /// The whole null-terminated string the token sits inside.
+ public let text: String
+ /// `"__TEXT,__cstring"` and the like — where the string was found.
+ public let sectionName: String
+ /// File offset of the string's FIRST byte, which is what code addresses.
+ public let stringFileOffset: Int
+ public let stringVMA: UInt64
+ /// Address of the matched substring, which differs from ``stringVMA``
+ /// whenever the token is not itself the start of the string.
+ public let matchVMA: UInt64
+ /// File offset of the ADRP that forms the string's address.
+ public let referenceFileOffset: Int
+ public let referenceVMA: UInt64
+ }
+
+ /// The conditional branch that skips the unsecure-cache path — or the NOP a
+ /// previous run already left in its place.
+ public struct Gate: Sendable, Equatable {
+ public let fileOffset: Int
+ public let vma: UInt64
+ /// Capstone's mnemonic: `cbz`/`cbnz`/`tbz`/`tbnz`/`b.<cond>`, or `nop`
+ /// when this binary has already been patched.
+ public let mnemonic: String
+ public let operandString: String
+ /// The call whose return value the gate tests, when one was found. The
+ /// fallback path leaves this `nil`.
+ public let callFileOffset: Int?
+ public let callVMA: UInt64?
+ /// Where the branch jumps when it is taken, i.e. past the unsecure path.
+ /// `nil` once the gate is a NOP and there is no target left to read.
+ public let targetVMA: UInt64?
+
+ /// True when the site already holds this patch's own output.
+ public var wasAlreadyNOP: Bool { mnemonic == "nop" }
+
+ /// How the gate reads in disassembly.
+ public var text: String {
+ operandString.isEmpty ? mnemonic : "\(mnemonic) \(operandString)"
+ }
+ }
+
+ /// What a run did.
+ public enum Outcome: String, Sendable, Equatable {
+ /// The gate already held a NOP. Nothing was written.
+ case alreadyPatched
+ /// `dryRun` was set, so the site was located and reported only.
+ case wouldPatch
+ /// The branch was replaced with a NOP.
+ case patched
+ }
+
+ /// The outcome of one run, and the site it acted on.
+ public struct Report: Sendable {
+ public let outcome: Outcome
+ public let anchor: Anchor
+ public let gate: Gate
+ /// The write, in the shape the Python's reference capture records it.
+ /// `nil` unless bytes actually changed.
+ public let record: PatchRecord?
+ /// Slot hashes recomputed, empty unless `reattestsCodeSignature` was set.
+ public let reattestedSlots: [CFWSlotRehash]
+
+ /// Sites whose bytes this run changed. The parity number: the Python
+ /// writes exactly one, and so must this.
+ public var sitesWritten: Int { record == nil ? 0 : 1 }
+ }
+
+ /// Where progress goes when the caller does not say. The Python prints to
+ /// stdout and `cfw_install*.sh` captures that, so this does too.
+ public static let stdoutLog: @Sendable (String) -> Void = { print($0) }
+
+ // MARK: - Patching
+
+ /// Open the gate in the `launchd_cache_loader` at `url`.
+ ///
+ /// Idempotent: a binary this has already patched is reported
+ /// `.alreadyPatched` and left untouched, byte for byte.
+ ///
+ /// - Parameter reattestsCodeSignature: recompute the code-directory slot
+ /// hash of the page the NOP lands in. Off by default because every
+ /// shipped caller re-signs the binary wholesale afterwards; a caller that
+ /// does not MUST set it, or TXM SIGKILLs the guest process.
+ /// - Throws: ``PatcherError/patchSiteNotFound(_:)`` when the boot-arg
+ /// string, its xref, or a branch with the gate's shape is missing — each
+ /// of which means the firmware moved and has to stop the install rather
+ /// than be guessed at.
+ @discardableResult
+ public static func patch(
+ fileAt url: URL,
+ dryRun: Bool = false,
+ reattestsCodeSignature: Bool = false,
+ log: ((String) -> Void)? = stdoutLog
+ ) throws -> Report {
+ guard FileManager.default.fileExists(atPath: url.path) else {
+ throw PatcherError.fileNotFound(url.path)
+ }
+ var data = try Data(contentsOf: url)
+ let report = try patch(
+ &data,
+ dryRun: dryRun,
+ reattestsCodeSignature: reattestsCodeSignature,
+ log: log
+ )
+ if !dryRun, report.sitesWritten > 0 || !report.reattestedSlots.isEmpty {
+ try data.write(to: url)
+ }
+ return report
+ }
+
+ /// In-memory form, for callers that already hold the binary.
+ ///
+ /// `data` is left untouched unless the run writes, so an `.alreadyPatched`
+ /// or `.wouldPatch` result cannot change a byte.
+ @discardableResult
+ public static func patch(
+ _ data: inout Data,
+ dryRun: Bool = false,
+ reattestsCodeSignature: Bool = false,
+ log: ((String) -> Void)? = stdoutLog
+ ) throws -> Report {
+ // Every offset below is an absolute file offset, so the buffer has to be
+ // zero-based — a slice handed in by a caller is not.
+ if data.startIndex != 0 { data = Data(data) }
+
+ let located = try locateGate(in: data)
+ let anchor = located.anchor
+ let gate = located.gate
+
+ if anchor.text == anchor.token {
+ log?(" Found anchor '\(anchor.token)' at va:0x\(hex(anchor.stringVMA))")
+ } else {
+ log?(" Found anchor '\(anchor.token)' inside \"\(anchor.text)\"")
+ log?(" String start: va:0x\(hex(anchor.stringVMA)) "
+ + "(match at va:0x\(hex(anchor.matchVMA)))")
+ }
+ log?(" Found string ref at 0x\(hex(UInt64(anchor.referenceFileOffset)))")
+ if let callVMA = gate.callVMA {
+ log?(" Call at va:0x\(hex(callVMA)); gate tests its result")
+ }
+
+ guard !gate.wasAlreadyNOP else {
+ // The Python has no such branch: it walks past its own NOP and takes
+ // the next conditional branch, which on this binary is the `cbnz`
+ // guarding the log-file `fopen`. Stopping here is the whole
+ // difference between running the installer twice and corrupting the
+ // binary on the second pass.
+ log?(" [=] already NOP at 0x\(hex(UInt64(gate.fileOffset))); nothing to do")
+ // Re-attestation still runs when asked for: a binary the Python
+ // patched carries a stale slot hash, and this is the one call that
+ // can repair it without rewriting an instruction. It returns nothing
+ // when the stored hashes already match, so the idempotent case stays
+ // byte-stable.
+ var slots: [CFWSlotRehash] = []
+ if reattestsCodeSignature, !dryRun {
+ slots = try CFWMachOCodeSignature.reattest(&data, modifiedOffsets: [gate.fileOffset])
+ for slot in slots { log?(" re-attested \(slot)") }
+ }
+ return Report(
+ outcome: .alreadyPatched,
+ anchor: anchor,
+ gate: gate,
+ record: nil,
+ reattestedSlots: slots
+ )
+ }
+
+ let nop = ARM64.nop
+ let original = Data(data[gate.fileOffset ..< gate.fileOffset + nop.count])
+
+ log?(" Before:")
+ log?(context(in: data, around: gate, marking: gate.fileOffset))
+
+ guard !dryRun else {
+ log?(" [.] dry-run: would NOP \(gate.text) at 0x\(hex(UInt64(gate.fileOffset)))")
+ return Report(
+ outcome: .wouldPatch,
+ anchor: anchor,
+ gate: gate,
+ record: nil,
+ reattestedSlots: []
+ )
+ }
+
+ data.replaceSubrange(gate.fileOffset ..< gate.fileOffset + nop.count, with: nop)
+
+ log?(" After:")
+ log?(context(in: data, around: gate, marking: gate.fileOffset))
+
+ let written = Data(data[gate.fileOffset ..< gate.fileOffset + nop.count])
+ guard written == nop else {
+ throw PatcherError.patchVerificationFailed(
+ "\(component): gate at 0x\(hex(UInt64(gate.fileOffset))) reads \(written.hex) after write"
+ )
+ }
+
+ var slots: [CFWSlotRehash] = []
+ if reattestsCodeSignature {
+ slots = try CFWMachOCodeSignature.reattest(&data, modifiedOffsets: [gate.fileOffset])
+ for slot in slots { log?(" re-attested \(slot)") }
+ }
+
+ log?(" [+] NOPped at 0x\(hex(UInt64(gate.fileOffset)))")
+
+ return Report(
+ outcome: .patched,
+ anchor: anchor,
+ gate: gate,
+ record: record(anchor: anchor, gate: gate, original: original, patched: nop),
+ reattestedSlots: slots
+ )
+ }
+
+ // MARK: - Locating the gate
+
+ /// Find the gate without touching the binary.
+ ///
+ /// The three failure modes are reported apart, because they mean different
+ /// things: no boot-arg string at all (not this binary), a string with no
+ /// xref (the check was compiled out), and an xref whose branch no longer has
+ /// the gate's shape (the function was rewritten).
+ public static func locateGate(in data: Data) throws -> (anchor: Anchor, gate: Gate) {
+ let data = data.startIndex == 0 ? data : Data(data)
+ let sections = MachOParser.parseSections(from: data)
+ guard !sections.isEmpty else {
+ throw PatcherError.invalidFormat("not a 64-bit Mach-O, or it carries no sections")
+ }
+ guard let text = sections["__TEXT,__text"] else {
+ throw PatcherError.invalidFormat("__TEXT,__text not found")
+ }
+
+ var firstFound: StringHit?
+ for hit in stringHits(in: data, sections: sections) {
+ if firstFound == nil { firstFound = hit }
+ // The code addresses the string's first byte, so that VA is tried
+ // first; the substring's own VA is the Python's fallback, for a
+ // compiler that split the literal.
+ let candidates = hit.stringVMA == hit.matchVMA
+ ? [hit.stringVMA]
+ : [hit.stringVMA, hit.matchVMA]
+ guard let reference = candidates.lazy.compactMap({ target in
+ findStringReference(in: data, text: text, targetVMA: target)
+ }).first else { continue }
+
+ let anchor = Anchor(
+ token: hit.token,
+ text: hit.text,
+ sectionName: hit.sectionName,
+ stringFileOffset: hit.stringFileOffset,
+ stringVMA: hit.stringVMA,
+ matchVMA: hit.matchVMA,
+ referenceFileOffset: reference.fileOffset,
+ referenceVMA: reference.vma
+ )
+ return (anchor, try findGate(in: data, text: text, anchor: anchor))
+ }
+
+ guard let found = firstFound else {
+ throw PatcherError.patchSiteNotFound(
+ "\(component): none of \(anchorTokens) appears in this binary's string sections"
+ )
+ }
+ throw PatcherError.patchSiteNotFound(
+ "\(component): \"\(found.text)\" is present but nothing in __TEXT,__text "
+ + "forms its address (ADRP+ADD) — the boot-arg check looks compiled out"
+ )
+ }
+
+ // MARK: - The boot-arg string
+
+ /// One `anchorTokens` match, resolved to the whole C string around it.
+ struct StringHit: Sendable, Equatable {
+ let token: String
+ let text: String
+ let sectionName: String
+ let stringFileOffset: Int
+ let stringVMA: UInt64
+ let matchVMA: UInt64
+ }
+
+ /// Every token match, most specific token first and, within a token,
+ /// `__TEXT,__cstring` before the rest.
+ ///
+ /// Searching sections rather than the raw file — which is what the Python
+ /// does — is what keeps a byte sequence inside the code signature or the
+ /// link-edit tables from being mistaken for a string literal.
+ static func stringHits(in data: Data, sections: [String: MachOSectionInfo]) -> [StringHit] {
+ // A zerofill section has no file bytes, and its `offset` field is 0;
+ // searching it would walk the Mach-O header instead.
+ let searchable = sections.values
+ .filter { $0.fileOffset > 0 && $0.size > 0 }
+ .filter { Int($0.fileOffset) + Int($0.size) <= data.count }
+ .sorted {
+ let cstring = "__cstring"
+ if ($0.sectionName == cstring) != ($1.sectionName == cstring) {
+ return $0.sectionName == cstring
+ }
+ return $0.fileOffset < $1.fileOffset
+ }
+
+ var hits: [StringHit] = []
+ for token in anchorTokens {
+ let needle = Array(token.utf8)
+ for section in searchable {
+ let start = Int(section.fileOffset)
+ let end = start + Int(section.size)
+ guard let match = firstOccurrence(of: needle, in: data, from: start, to: end) else {
+ continue
+ }
+ let stringStart = cStringStart(in: data, containing: match, notBefore: start)
+ let stringEnd = cStringEnd(in: data, from: stringStart, notAfter: end)
+ hits.append(StringHit(
+ token: token,
+ text: String(decoding: data[stringStart ..< stringEnd], as: UTF8.self),
+ sectionName: "\(section.segmentName),\(section.sectionName)",
+ stringFileOffset: stringStart,
+ stringVMA: section.address + UInt64(stringStart - start),
+ matchVMA: section.address + UInt64(match - start)
+ ))
+ break
+ }
+ }
+ return hits
+ }
+
+ static func firstOccurrence(of needle: [UInt8], in data: Data, from: Int, to: Int) -> Int? {
+ guard !needle.isEmpty, to - from >= needle.count else { return nil }
+ for offset in from ... (to - needle.count) {
+ var matched = true
+ for (index, byte) in needle.enumerated() where data[offset + index] != byte {
+ matched = false
+ break
+ }
+ if matched { return offset }
+ }
+ return nil
+ }
+
+ /// The first byte of the null-terminated string containing `offset`.
+ ///
+ /// Code forms the address of a literal's START, never of a substring inside
+ /// it, so a token that matched mid-string has to be walked back before its
+ /// address can be looked for.
+ static func cStringStart(in data: Data, containing offset: Int, notBefore floor: Int) -> Int {
+ var position = offset - 1
+ while position >= floor, data[position] != 0 { position -= 1 }
+ return position + 1
+ }
+
+ static func cStringEnd(in data: Data, from start: Int, notAfter ceiling: Int) -> Int {
+ var position = start
+ while position < ceiling, data[position] != 0 { position += 1 }
+ return position
+ }
+
+ // MARK: - The string xref
+
+ /// The ADRP of the first ADRP+ADD pair in `__TEXT,__text` that forms
+ /// `targetVMA`.
+ ///
+ /// The pair need not be adjacent — the compiler interleaves other setup
+ /// between them — so an ADRP is remembered per destination register and
+ /// matched against a later ADD that reads it. Everything is read from
+ /// Capstone's decoded operands: the ADRP's immediate is already the absolute
+ /// page, and the ADD's is the page offset.
+ static func findStringReference(
+ in data: Data,
+ text: MachOSectionInfo,
+ targetVMA: UInt64
+ ) -> (fileOffset: Int, vma: UInt64)? {
+ let targetPage = Int64(targetVMA & ~0xFFF)
+ let targetPageOffset = Int64(targetVMA & 0xFFF)
+ let disassembler = ARM64Disassembler()
+
+ /// ADRP destination register -> (instruction index, address, page).
+ var pendingADRP: [UInt32: (index: Int, fileOffset: Int, vma: UInt64, page: Int64)] = [:]
+
+ for (index, offset) in wordOffsets(of: text).enumerated() {
+ let vma = text.address + UInt64(offset - Int(text.fileOffset))
+ guard let instruction = disassembler.disassembleOne(in: data, at: offset, address: vma),
+ let operands = instruction.aarch64?.operands
+ else { continue }
+
+ switch instruction.mnemonic {
+ case "adrp":
+ guard operands.count >= 2,
+ operands[0].type == AARCH64_OP_REG,
+ operands[1].type == AARCH64_OP_IMM
+ else { continue }
+ pendingADRP[UInt32(operands[0].reg.rawValue)] = (index, offset, vma, operands[1].imm)
+
+ case "add":
+ guard operands.count >= 3,
+ operands[1].type == AARCH64_OP_REG,
+ operands[2].type == AARCH64_OP_IMM,
+ let adrp = pendingADRP[UInt32(operands[1].reg.rawValue)],
+ adrp.page == targetPage,
+ operands[2].imm == targetPageOffset,
+ index - adrp.index <= maxADRPToADDInstructions
+ else { continue }
+ return (adrp.fileOffset, adrp.vma)
+
+ default:
+ continue
+ }
+ }
+ return nil
+ }
+
+ // MARK: - The gate
+
+ /// The conditional branch that consumes the boot-arg lookup's result.
+ ///
+ /// Shape, in order: the first `bl` at or after the string xref, then the
+ /// first conditional branch after that call. A `nop` reached before that
+ /// branch is this patch's own output and ends the search — see the file
+ /// header for why that matters.
+ static func findGate(
+ in data: Data,
+ text: MachOSectionInfo,
+ anchor: Anchor
+ ) throws -> Gate {
+ let disassembler = ARM64Disassembler()
+ let textEnd = Int(text.fileOffset) + Int(text.size)
+ func decode(_ offset: Int) -> Instruction? {
+ guard offset >= Int(text.fileOffset), offset + 4 <= textEnd else { return nil }
+ return disassembler.disassembleOne(
+ in: data,
+ at: offset,
+ address: text.address + UInt64(offset - Int(text.fileOffset))
+ )
+ }
+
+ var call: Instruction?
+ for step in 0 ..< maxInstructionsToCall {
+ guard let instruction = decode(anchor.referenceFileOffset + step * 4) else { break }
+ // A direct `bl` only — the string is an argument to a call, and an
+ // indirect `blr`/`blraa` through a register is not one this pass can
+ // attribute a return value to.
+ if instruction.mnemonic == "bl", branchTarget(of: instruction) != nil {
+ call = instruction
+ break
+ }
+ }
+
+ let searchBase = call.map { Int($0.address - text.address) + Int(text.fileOffset) }
+ ?? anchor.referenceFileOffset
+ let window = call == nil ? maxFallbackInstructions : maxInstructionsAfterCall
+
+ for step in 1 ... window {
+ let offset = searchBase + step * 4
+ guard let instruction = decode(offset) else { break }
+
+ if instruction.mnemonic == "nop" {
+ return Gate(
+ fileOffset: offset,
+ vma: instruction.address,
+ mnemonic: instruction.mnemonic,
+ operandString: instruction.operandString,
+ callFileOffset: call.map { Int($0.address - text.address) + Int(text.fileOffset) },
+ callVMA: call?.address,
+ targetVMA: nil
+ )
+ }
+
+ guard isConditionalBranch(instruction) else { continue }
+ try validate(gate: instruction, in: data, text: text, after: call, disassembler)
+ return Gate(
+ fileOffset: offset,
+ vma: instruction.address,
+ mnemonic: instruction.mnemonic,
+ operandString: instruction.operandString,
+ callFileOffset: call.map { Int($0.address - text.address) + Int(text.fileOffset) },
+ callVMA: call?.address,
+ targetVMA: branchTarget(of: instruction)
+ )
+ }
+
+ throw PatcherError.patchSiteNotFound(
+ "\(component): no conditional branch within \(window) instructions of "
+ + (call.map { "the call at 0x\(hex($0.address))" }
+ ?? "the \"\(anchor.text)\" xref at 0x\(hex(anchor.referenceVMA))")
+ )
+ }
+
+ /// Conditional branches, decided on the mnemonic Capstone produced.
+ static func isConditionalBranch(_ instruction: Instruction) -> Bool {
+ switch instruction.mnemonic {
+ case "cbz", "cbnz", "tbz", "tbnz": true
+ default: instruction.mnemonic.hasPrefix("b.")
+ }
+ }
+
+ /// Reject a branch that is not the gate.
+ ///
+ /// Two properties have to hold, and the Python checks neither: the branch
+ /// tests the register the call returned in, and it jumps FORWARD, past the
+ /// unsecure-cache path it guards. A branch that fails either is some other
+ /// branch, and NOP'ing it would be a silent miscompile of a boot-critical
+ /// binary — so this throws instead.
+ static func validate(
+ gate: Instruction,
+ in data: Data,
+ text: MachOSectionInfo,
+ after call: Instruction?,
+ _ disassembler: ARM64Disassembler
+ ) throws {
+ if let target = branchTarget(of: gate) {
+ let textEnd = text.address + text.size
+ guard target > gate.address, target < textEnd else {
+ throw PatcherError.patchSiteNotFound(
+ "\(component): branch at 0x\(hex(gate.address)) jumps to 0x\(hex(target)), "
+ + "which is not forward inside __TEXT,__text — not the unsecure-cache gate"
+ )
+ }
+ }
+
+ guard call != nil else { return } // Fallback path: nothing to attribute.
+
+ switch gate.mnemonic {
+ case "cbz", "cbnz", "tbz", "tbnz":
+ let register = disassembler.firstRegisterName(gate)
+ guard register == "x0" || register == "w0" else {
+ throw PatcherError.patchSiteNotFound(
+ "\(component): branch at 0x\(hex(gate.address)) tests "
+ + "\(register ?? "an unknown register"), not the call's result in x0/w0"
+ )
+ }
+ default:
+ // `b.<cond>` reads the flags, so the call's result has to reach it
+ // through a flag-setting instruction on x0/w0 in between.
+ guard flagSetterOnResult(between: call!, and: gate, in: data, text: text, disassembler)
+ else {
+ throw PatcherError.patchSiteNotFound(
+ "\(component): \(gate.mnemonic) at 0x\(hex(gate.address)) is not preceded by a "
+ + "compare of the call's result — nothing ties it to the boot-arg lookup"
+ )
+ }
+ }
+ }
+
+ /// Whether some instruction between the call and the branch sets the flags
+ /// from x0/w0 — a `cmp`/`subs`/`ands`/`tst` reading register 0.
+ static func flagSetterOnResult(
+ between call: Instruction,
+ and gate: Instruction,
+ in data: Data,
+ text: MachOSectionInfo,
+ _ disassembler: ARM64Disassembler
+ ) -> Bool {
+ var address = call.address + 4
+ while address < gate.address {
+ defer { address += 4 }
+ let offset = Int(address - text.address) + Int(text.fileOffset)
+ guard let instruction = disassembler.disassembleOne(in: data, at: offset, address: address),
+ instruction.aarch64?.updatesFlags == true,
+ let operands = instruction.aarch64?.operands
+ else { continue }
+ for operand in operands where operand.type == AARCH64_OP_REG {
+ let name = disassembler.registerName(UInt32(operand.reg.rawValue))
+ if name == "x0" || name == "w0" { return true }
+ }
+ }
+ return false
+ }
+
+ /// The absolute address a branch jumps to, read from its last immediate
+ /// operand, or `nil` when the instruction carries none.
+ static func branchTarget(of instruction: Instruction) -> UInt64? {
+ guard let operands = instruction.aarch64?.operands,
+ let last = operands.last,
+ last.type == AARCH64_OP_IMM,
+ last.imm >= 0
+ else { return nil }
+ return UInt64(last.imm)
+ }
+
+ // MARK: - Recording
+
+ private static func record(
+ anchor: Anchor,
+ gate: Gate,
+ original: Data,
+ patched: Data
+ ) -> PatchRecord {
+ PatchRecord(
+ patchID: patchID,
+ component: component,
+ fileOffset: gate.fileOffset,
+ virtualAddress: gate.vma,
+ originalBytes: original,
+ patchedBytes: patched,
+ beforeDisasm: disassemblyText(of: original, at: gate.vma),
+ afterDisasm: disassemblyText(of: patched, at: gate.vma),
+ // Worded as the Python words it, so a captured reference compares.
+ description: "NOP the cache-validation branch gated on '\(anchor.token)'"
+ )
+ }
+
+ // MARK: - Logging
+
+ /// Five instructions around the gate, with the gate itself marked — the
+ /// Python's `_log_asm` before/after block.
+ private static func context(in data: Data, around gate: Gate, marking marker: Int) -> String {
+ let disassembler = ARM64Disassembler()
+ let start = max(gate.fileOffset - 8, 0)
+ return (0 ..< 5).compactMap { step -> String? in
+ let offset = start + step * 4
+ guard offset + 4 <= data.count else { return nil }
+ // The window starts two instructions BEFORE the gate, so the delta is
+ // negative for the first steps. `UInt64(Int)` traps on a negative
+ // value even under -O; wrap through the bit pattern instead.
+ let vma = gate.vma &+ UInt64(bitPattern: Int64(offset - gate.fileOffset))
+ guard let instruction = disassembler.disassembleOne(in: data, at: offset, address: vma)
+ else { return nil }
+ let tag = offset == marker ? " >>>" : " "
+ let mnemonic = instruction.mnemonic.count < 8
+ ? instruction.mnemonic.padding(toLength: 8, withPad: " ", startingAt: 0)
+ : instruction.mnemonic
+ // Laid out by hand rather than with `String(format:)`: `%X` consumes
+ // 32 bits, and every offset here is an `Int`.
+ return " \(tag) 0x\(hex(UInt64(offset), padTo: 8)): \(mnemonic) \(instruction.operandString)"
+ }.joined(separator: "\n")
+ }
+
+ private static func disassemblyText(of bytes: Data, at vma: UInt64) -> String {
+ ARM64Disassembler()
+ .disassemble(bytes, at: vma)
+ .map { $0.operandString.isEmpty ? $0.mnemonic : "\($0.mnemonic) \($0.operandString)" }
+ .joined(separator: "; ")
+ }
+
+ // MARK: - Helpers
+
+ /// Every 4-byte instruction offset in a section, in order.
+ static func wordOffsets(of section: MachOSectionInfo) -> StrideTo<Int> {
+ let start = Int(section.fileOffset)
+ return stride(from: start, to: start + (Int(section.size) & ~3), by: 4)
+ }
+
+ private static func hex(_ value: UInt64, padTo width: Int = 0) -> String {
+ let digits = String(value, radix: 16, uppercase: true)
+ guard digits.count < width else { return digits }
+ return String(repeating: "0", count: width - digits.count) + digits
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/Patches/CFWDiskimagesiod.swift b/sources/FirmwarePatcher/CFW/Patches/CFWDiskimagesiod.swift
new file mode 100644
index 00000000..56068922
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/Patches/CFWDiskimagesiod.swift
@@ -0,0 +1,723 @@
+// CFWDiskimagesiod.swift — force diskimagesiod's DDI mount-completion gate open.
+//
+// Swift port of `scripts/patchers/cfw_patch_diskimagesiod.py`, driven by
+// `cfw.py patch-diskimagesiod <binary>` and, in the shipped installers, by
+// `scripts/cfw_install.sh:415` / `cfw-kit/lib/base_stages.sh:188`.
+//
+// Why the patch exists
+// ────────────────────
+// `pymobiledevice3 mounter auto-mount` attaches the personalized DDI, then
+// MobileStorageMounter waits on diskimagesiod's
+// `-[DIDiskArb waitForDAMountWithExpectedCount:diskTracker:]` before it
+// performs the real (nobrowse) mount of the DDI volume at /System/Developer.
+// That wait spins until `isMountComplete` returns YES, which is
+// `callbackReached || (appearedDiskCount >= expectedCount &&
+// mountedDiskCount >= mountableDiskCount)`. On the iOS-27-userland /
+// 26.4-vphone600-kernel hybrid it never becomes true: only some of the DMG's
+// IOMedia ever "appear" to diskimagesiod's DiskArbitration session, and
+// diskarbitrationd never auto-mounts the volume, so the wait hangs forever and
+// pmd3 times out. diskimagesiod itself does NOT mount the DDI — its
+// `-[DIDiskArb mountWithDeviceName:…]` is dead code; it only gates
+// MobileStorageMounter. Forcing `isMountComplete` to YES lets the wait return
+// immediately so MobileStorageMounter proceeds and mounts the DDI.
+//
+// Pairs with the JB kernel patches that make the DDI attachable and mountable
+// (the DiskImages2 ABI pokes, and the Sandbox `mpo_proc_check_syscall_unix`
+// stub that lets MobileStorageMounter's `mount_apfs` issue `mount(2)`).
+// No-op-in-effect on version-matched userlands, where the wait completes on its
+// own and returning YES early changes nothing observable.
+//
+// How the site is found
+// ─────────────────────
+// Nothing here is a hardcoded offset. Two source-backed anchors, in order:
+//
+// 1. `LC_SYMTAB`: a symbol whose name contains `isMountCompleteWithExpectedCount`.
+// Shipped diskimagesiod is stripped, so this normally misses — it is kept
+// because it is the cheapest and most direct anchor when it does hit.
+// 2. ObjC runtime metadata, which survives stripping:
+// selector cstring in `__TEXT,__objc_methname`
+// → its `__objc_selrefs` entry (chained-fixup aware)
+// → the relative method-list entry naming it
+// → that entry's `imp` field, relative-addressed.
+// `__TEXT,__objc_methlist` is walked *structurally* first — a packed run
+// of `{entsizeAndFlags, count}` headers followed by `count` 12-byte
+// `{name, types, imp}` entries, each list 8-byte aligned. The structural
+// walk cannot land mid-entry and cannot mistake a `__const` word for a
+// method. The Python's 4-byte-strided scan is kept behind it, over the
+// same sections the Python tries plus `__objc_methlist` itself, so this
+// port is never less capable than the one it replaces. Either way the
+// result is required to be the *only* entry in the image naming that
+// selector.
+//
+// The resolved IMP is then checked to land inside `__TEXT,__text` and to decode
+// as real instructions before a single byte is written.
+//
+// What is written
+// ───────────────
+// `mov x0, #1 ; ret` over the method prologue. Safe: the function returns to the
+// caller's (unsigned) LR without ever having pushed a frame, so overwriting
+// `pacibsp; stp …` loses nothing that the new epilogue needs. Both words come
+// from the encoder — `ARM64Encoder.encodeMovzX` builds MOVZ from its ISA fields
+// and `ARM64.ret` is the keystone-derived constant; `CFWDiskimagesiodTests`
+// asserts the two agree with `ARM64.movX0_1`.
+//
+// Re-signing
+// ──────────
+// Off by default, matching the Python and the call site: `cfw_install.sh`
+// re-signs the patched binary with `ldid` under the extracted
+// `com.apple.diskimagesiod` entitlements, so a slot re-attest here would be
+// overwritten moments later. `reattest: true` recomputes the CodeDirectory slot
+// hashes through `CFWMachOCodeSignature` instead, which is what a caller that
+// drops the `ldid` step needs — and what makes `codesign -v` pass on the patched
+// file on its own.
+
+import Capstone
+import Foundation
+
+/// Forces `-[DIDiskArb isMountCompleteWithExpectedCount:diskTracker:]` to
+/// return YES so MobileStorageMounter stops waiting on a mount that will never
+/// be reported.
+public enum CFWDiskimagesiod {
+ // MARK: - Identity
+
+ /// The component name the Python records this write under.
+ public static let component = "diskimagesiod"
+
+ /// The selector whose implementation is stubbed.
+ public static let selector = "isMountCompleteWithExpectedCount:diskTracker:"
+
+ /// The `LC_SYMTAB` fragment strategy 1 looks for. Deliberately shorter than
+ /// the selector: a symbol name is `-[DIDiskArb isMountComplete…]`, and the
+ /// colon-bearing tail differs between symbol spellings.
+ public static let symbolFragment = "isMountCompleteWithExpectedCount"
+
+ /// The method, as it reads in a disassembler.
+ public static let method = "-[DIDiskArb \(selector)]"
+
+ /// Record identity, matching the Python's `records.site` label so a captured
+ /// reference and this port sort together.
+ public static let patchID = "diskimagesiod.is_mount_complete"
+
+ /// `mov x0, #1 ; ret`.
+ ///
+ /// MOVZ is built from its ISA fields by ``ARM64Encoder/encodeMovzX(rd:imm16:shift:)``;
+ /// the `?? ARM64.movX0_1` arm is unreachable (that encoder returns `nil`
+ /// only for a shift above 48) and exists so this stays a plain `let` with
+ /// no trap in it. `CFWDiskimagesiodTests` asserts the two spellings are the
+ /// same four bytes.
+ public static let replacement: Data =
+ (ARM64Encoder.encodeMovzX(rd: 0, imm16: 1) ?? ARM64.movX0_1) + ARM64.ret
+
+ // MARK: - Results
+
+ /// Which anchor found the implementation.
+ public enum Anchor: String, Sendable, Equatable {
+ /// `LC_SYMTAB` carried the symbol. Only on an unstripped build.
+ case symbolTable
+ /// Structural walk of `__TEXT,__objc_methlist`.
+ case relativeMethodList
+ /// The Python's strategy: a 4-byte-strided scan, over `__objc_methlist`
+ /// when the structural walk could not follow it, then over the
+ /// `__objc_const` sections of the pre-`__objc_methlist` layout.
+ case methodListScan
+ }
+
+ /// The implementation this patch overwrites.
+ public struct Site: Sendable, Equatable {
+ /// File offset of the method's first instruction.
+ public let fileOffset: Int
+ /// Its virtual address, when an anchor produced one.
+ public let virtualAddress: UInt64?
+ /// How it was found.
+ public let anchor: Anchor
+ /// The bytes the patch replaces, as found — ``replacement``-many.
+ public let original: Data
+
+ /// True when the site already holds this patch's own output.
+ public var isAlreadyPatched: Bool { original == CFWDiskimagesiod.replacement }
+ }
+
+ /// What a run did.
+ public enum Outcome: String, Sendable, Equatable {
+ /// The prologue already read `mov x0, #1 ; ret`; nothing was written
+ /// there. (A stale slot hash may still have been re-attested.)
+ case alreadyPatched
+ /// `dryRun` was set, so the site was located and reported only.
+ case wouldPatch
+ /// The prologue was replaced.
+ case patched
+ }
+
+ /// The outcome of one run, and the site it acted on.
+ public struct Report: Sendable {
+ public let outcome: Outcome
+ public let site: Site
+ /// The write, in the shape the Python's reference capture records it.
+ /// `nil` unless the prologue bytes actually changed.
+ public let record: PatchRecord?
+ /// CodeDirectory slots re-attested. Empty unless `reattest` was set,
+ /// and empty on a second run because the stored hashes already match.
+ public let rehashes: [CFWSlotRehash]
+
+ /// The parity number: the Python writes exactly one site, and so must this.
+ public var sitesWritten: Int { record == nil ? 0 : 1 }
+ }
+
+ /// Where progress goes when the caller does not say. The Python prints to
+ /// stdout and `cfw_install*.sh` captures that, so this does too.
+ public static let stdoutLog: @Sendable (String) -> Void = { print($0) }
+
+ // MARK: - Patching
+
+ /// Stub the mount-completion gate in `data`.
+ ///
+ /// Idempotent: a buffer that already reads `mov x0, #1 ; ret` at the site
+ /// reports ``Outcome/alreadyPatched`` and writes nothing, rather than
+ /// failing to recognise a prologue that is no longer there. Re-running is
+ /// the normal case — `cfw install` is re-run against an already-installed
+ /// volume all the time — and commit `8eb6c8b` exists because a sibling
+ /// patcher got this wrong.
+ ///
+ /// - Parameters:
+ /// - reattest: recompute the CodeDirectory slot hashes for the pages the
+ /// write touched. Off by default; see the file header for why.
+ /// - dryRun: locate and report without writing.
+ /// - Throws: ``PatcherError/invalidFormat(_:)`` when the buffer is not a
+ /// 64-bit Mach-O or its ObjC metadata is ambiguous, and
+ /// ``PatcherError/patchSiteNotFound(_:)`` when no anchor resolves — both
+ /// have to stop the install rather than be guessed at.
+ @discardableResult
+ public static func patch(
+ _ data: inout Data,
+ reattest: Bool = false,
+ dryRun: Bool = false,
+ log: ((String) -> Void)? = stdoutLog
+ ) throws -> Report {
+ if data.startIndex != 0 { data = Data(data) }
+
+ let site = try locate(in: data)
+ let patched = replacement
+ log?(" \(method) @ \(describe(site))")
+ log?(" Before: \(disassemblyText(of: site.original, at: site.virtualAddress))")
+
+ guard !dryRun else {
+ log?(" [.] dry-run: would write \(patched.hex) at 0x\(hex(UInt64(site.fileOffset)))")
+ return Report(outcome: .wouldPatch, site: site, record: nil, rehashes: [])
+ }
+
+ var record: PatchRecord?
+ if site.isAlreadyPatched {
+ log?(" [=] already `mov x0, #1 ; ret` at 0x\(hex(UInt64(site.fileOffset))); nothing to write")
+ } else {
+ data.replaceSubrange(site.fileOffset ..< site.fileOffset + patched.count, with: patched)
+ record = makeRecord(site: site, patched: patched)
+ log?(" After: \(disassemblyText(of: patched, at: site.virtualAddress))")
+ }
+
+ var rehashes: [CFWSlotRehash] = []
+ if reattest {
+ // First and last byte of the write: an 8-byte span sits inside one
+ // 4 KiB page here, but a page boundary between them would otherwise
+ // leave the second page's slot stale.
+ rehashes = try CFWMachOCodeSignature.reattest(
+ &data,
+ modifiedOffsets: [site.fileOffset, site.fileOffset + patched.count - 1]
+ )
+ for rehash in rehashes { log?(" [~] \(rehash)") }
+ if rehashes.isEmpty {
+ log?(" [=] code directory slots already current; no re-attest needed")
+ }
+ }
+
+ let written = data[site.fileOffset ..< site.fileOffset + patched.count]
+ guard written == patched else {
+ throw PatcherError.patchVerificationFailed(
+ "\(method): site at 0x\(hex(UInt64(site.fileOffset))) reads \(Data(written).hex) after write"
+ )
+ }
+
+ log?(" [+] \(method) forced to YES at 0x\(hex(UInt64(site.fileOffset)))")
+ return Report(
+ outcome: site.isAlreadyPatched ? .alreadyPatched : .patched,
+ site: site,
+ record: record,
+ rehashes: rehashes
+ )
+ }
+
+ /// File-backed form of ``patch(_:reattest:dryRun:log:)``.
+ ///
+ /// The file is rewritten only when its bytes actually changed, so a
+ /// re-run leaves even the modification time alone.
+ @discardableResult
+ public static func patch(
+ fileAt url: URL,
+ reattest: Bool = false,
+ dryRun: Bool = false,
+ log: ((String) -> Void)? = stdoutLog
+ ) throws -> Report {
+ guard FileManager.default.fileExists(atPath: url.path) else {
+ throw PatcherError.fileNotFound(url.path)
+ }
+ var data = try Data(contentsOf: url)
+ let report = try patch(&data, reattest: reattest, dryRun: dryRun, log: log)
+ if !dryRun, report.record != nil || !report.rehashes.isEmpty {
+ try data.write(to: url)
+ }
+ return report
+ }
+
+ // MARK: - Locating the implementation
+
+ /// Resolve the method's first instruction without touching the buffer.
+ ///
+ /// - Throws: ``PatcherError/patchSiteNotFound(_:)`` when every anchor is
+ /// exhausted, ``PatcherError/invalidFormat(_:)`` when the image is not a
+ /// 64-bit Mach-O or names the selector from more than one implementation.
+ public static func locate(in data: Data) throws -> Site {
+ let data = rebased(data)
+ guard data.count > 32, data.loadLE(UInt32.self, at: 0) == machMagic64 else {
+ throw PatcherError.invalidFormat("\(component): not a 64-bit Mach-O")
+ }
+ let segments = MachOParser.parseSegments(from: data)
+ let sections = MachOParser.parseSections(from: data)
+ let textRange = sections[textSectionKey].map {
+ Int($0.fileOffset) ..< Int($0.fileOffset) + Int($0.size)
+ }
+
+ // Strategy 1 — the symbol table, when the image kept one.
+ if let va = MachOParser.findSymbol(containing: symbolFragment, in: data),
+ let offset = MachOParser.vaToFileOffset(va, segments: segments),
+ let site = makeSite(
+ in: data,
+ fileOffset: offset,
+ virtualAddress: va,
+ anchor: .symbolTable,
+ textRange: textRange
+ )
+ {
+ return site
+ }
+
+ // Strategy 2 — ObjC metadata, which survives stripping.
+ let (impVA, anchor) = try resolveIMPViaObjCMetadata(in: data, sections: sections)
+ guard let offset = MachOParser.vaToFileOffset(impVA, segments: segments) else {
+ throw PatcherError.invalidFormat(
+ "\(method): IMP va 0x\(hex(impVA)) is in no mapped segment"
+ )
+ }
+ guard let site = makeSite(
+ in: data,
+ fileOffset: offset,
+ virtualAddress: impVA,
+ anchor: anchor,
+ textRange: textRange
+ ) else {
+ throw PatcherError.patchSiteNotFound(
+ "\(method): IMP at 0x\(hex(impVA)) (foff 0x\(hex(UInt64(offset)))) "
+ + "is outside __TEXT,__text or does not decode as instructions"
+ )
+ }
+ return site
+ }
+
+ /// Build a ``Site`` when the candidate offset survives validation, else nil.
+ ///
+ /// Two checks, both semantic rather than positional: the offset must lie in
+ /// the image's executable section, and the words there must decode — unless
+ /// they are already this patch's own output, which is the idempotent case.
+ static func makeSite(
+ in data: Data,
+ fileOffset: Int,
+ virtualAddress: UInt64?,
+ anchor: Anchor,
+ textRange: Range<Int>?
+ ) -> Site? {
+ let length = replacement.count
+ guard fileOffset >= 0, fileOffset + length <= data.count else { return nil }
+ if let textRange, !(textRange.contains(fileOffset) && textRange.contains(fileOffset + length - 1)) {
+ return nil
+ }
+
+ let original = Data(data[fileOffset ..< fileOffset + length])
+ let site = Site(
+ fileOffset: fileOffset,
+ virtualAddress: virtualAddress,
+ anchor: anchor,
+ original: original
+ )
+ if site.isAlreadyPatched { return site }
+
+ // `skipData` is on in the shared disassembler, so an undecodable word
+ // arrives as a data pseudo-instruction (id 0) instead of ending the
+ // stream — which is what makes this a usable "is this code?" test.
+ let decoded = ARM64Disassembler().disassemble(
+ original,
+ at: virtualAddress ?? UInt64(fileOffset)
+ )
+ guard decoded.count == length / 4, decoded.allSatisfy({ $0.id != 0 }) else { return nil }
+ return site
+ }
+
+ // MARK: - ObjC metadata
+
+ /// selector cstring → selref → method-list entry → IMP.
+ static func resolveIMPViaObjCMetadata(
+ in data: Data,
+ sections: [String: MachOSectionInfo]
+ ) throws -> (impVA: UInt64, anchor: Anchor) {
+ guard let selectorVA = selectorStringVA(in: data, sections: sections) else {
+ throw PatcherError.patchSiteNotFound(
+ "\(component): selector '\(selector)' not present in the image"
+ )
+ }
+
+ // A method-list `name` field points at the uniqued `SEL *` (the selref)
+ // on every toolchain that emits `__objc_selrefs`, and straight at the
+ // cstring in a "direct selector" list. Both are accepted, exactly as
+ // the Python does, so a missing selref is not fatal on its own.
+ var targets: Set<UInt64> = [selectorVA]
+ if let selrefsSection = section(sections, "__DATA_CONST,__objc_selrefs", "__DATA,__objc_selrefs", "__AUTH_CONST,__objc_selrefs"),
+ let selrefVA = selectorReferenceVA(
+ in: data,
+ selrefs: selrefsSection,
+ selectorVA: selectorVA,
+ imageBase: imageBase(sections)
+ )
+ {
+ targets.insert(selrefVA)
+ }
+
+ // Preferred: a structural walk of the packed relative method lists.
+ if let methlist = sections[methodListSectionKey] {
+ let imps = relativeMethodListIMPs(in: data, section: methlist, naming: targets)
+ if let impVA = try single(imps, strategy: methodListSectionKey) {
+ return (impVA, .relativeMethodList)
+ }
+ }
+
+ // Fallback: the Python's own strategy, a 4-byte-strided scan, over the
+ // same sections it tries. It covers two cases the structural walk does
+ // not — a `__TEXT,__objc_methlist` whose list chain this parser cannot
+ // follow to the end, and the older layout where method lists are
+ // embedded in `class_ro_t` records inside an `__objc_const` section and
+ // so are not packed back to back. Running it over the method-list
+ // section too is what keeps this port from ever being *less* capable
+ // than the Python it replaces. Every candidate still has to resolve to
+ // a single agreed-upon IMP, and that IMP still has to pass ``makeSite``.
+ for key in scannedSectionKeys {
+ guard let scanned = sections[key] else { continue }
+ let imps = scanRelativeMethodEntryIMPs(in: data, section: scanned, naming: targets)
+ if let impVA = try single(imps, strategy: key) {
+ return (impVA, .methodListScan)
+ }
+ }
+
+ throw PatcherError.patchSiteNotFound(
+ "\(method): no ObjC method-list entry names '\(selector)'"
+ )
+ }
+
+ /// The single distinct IMP in `candidates`, `nil` when there are none.
+ ///
+ /// More than one distinct IMP means the image names this selector from
+ /// several implementations and the patch has no unambiguous target — which
+ /// stops the install rather than picking one.
+ static func single(_ candidates: [UInt64], strategy: String) throws -> UInt64? {
+ let distinct = Set(candidates)
+ guard let first = distinct.first else { return nil }
+ guard distinct.count == 1 else {
+ let list = distinct.sorted().map { "0x\(hex($0))" }.joined(separator: ", ")
+ throw PatcherError.invalidFormat(
+ "\(method): \(strategy) names '\(selector)' from \(distinct.count) "
+ + "implementations (\(list)) — no unambiguous target"
+ )
+ }
+ return first
+ }
+
+ /// Virtual address of the selector cstring.
+ ///
+ /// Looked for in `__TEXT,__objc_methname` first — the section that exists
+ /// for exactly this — then `__TEXT,__cstring`, then anywhere in the file,
+ /// which is the Python's only search. A hit has to start a string (the
+ /// preceding byte is NUL, or it is the first byte of its section) so a
+ /// selector that is the tail of a longer one cannot match.
+ static func selectorStringVA(in data: Data, sections: [String: MachOSectionInfo]) -> UInt64? {
+ let needle = Data(selector.utf8) + [0]
+
+ for key in stringSectionKeys {
+ guard let section = sections[key] else { continue }
+ let start = Int(section.fileOffset)
+ let end = start + Int(section.size)
+ guard start >= 0, end <= data.count, start < end else { continue }
+ guard let found = firstStringStart(of: needle, in: data, range: start ..< end) else { continue }
+ return section.address + UInt64(found - start)
+ }
+
+ guard let found = firstStringStart(of: needle, in: data, range: 0 ..< data.count) else { return nil }
+ return virtualAddress(ofFileOffset: found, sections: sections)
+ }
+
+ /// First occurrence of `needle` in `range` that begins a C string.
+ static func firstStringStart(of needle: Data, in data: Data, range: Range<Int>) -> Int? {
+ var searchFrom = range.lowerBound
+ while searchFrom < range.upperBound,
+ let found = data.range(of: needle, in: searchFrom ..< range.upperBound)
+ {
+ if found.lowerBound == range.lowerBound || data[found.lowerBound - 1] == 0 {
+ return found.lowerBound
+ }
+ searchFrom = found.lowerBound + 1
+ }
+ return nil
+ }
+
+ /// The `__objc_selrefs` slot pointing at `selectorVA`.
+ ///
+ /// The slot holds a *chained fixup*, not a linked address, so the raw
+ /// quadword rarely equals the target. Four interpretations are tried in
+ /// decreasing strictness, and the first that matches anywhere in the
+ /// section wins:
+ ///
+ /// 1. the value itself — an already-linked or non-chained image;
+ /// 2. `DYLD_CHAINED_PTR_64` rebase: the low 36 bits are an offset from the
+ /// image's preferred base, the rest are `high8` / `next` / `bind`;
+ /// 3. the low 48 bits, for the older 8-byte fixup spellings;
+ /// 4. the low 32 bits, which is the Python's catch-all.
+ static func selectorReferenceVA(
+ in data: Data,
+ selrefs: MachOSectionInfo,
+ selectorVA: UInt64,
+ imageBase: UInt64
+ ) -> UInt64? {
+ let start = Int(selrefs.fileOffset)
+ let count = Int(selrefs.size)
+ guard start >= 0, start + count <= data.count else { return nil }
+
+ let matchers: [(UInt64) -> Bool] = [
+ { $0 == selectorVA },
+ { imageBase &+ ($0 & chainedRebaseTargetMask) == selectorVA },
+ { ($0 & 0x0000_FFFF_FFFF_FFFF) == selectorVA },
+ { ($0 & 0xFFFF_FFFF) == (selectorVA & 0xFFFF_FFFF) },
+ ]
+ for matches in matchers {
+ var offset = 0
+ while offset + 8 <= count {
+ if matches(data.loadLE(UInt64.self, at: start + offset)) {
+ return selrefs.address + UInt64(offset)
+ }
+ offset += 8
+ }
+ }
+ return nil
+ }
+
+ // MARK: - Method lists
+
+ /// Walk `__TEXT,__objc_methlist` as what it is: relative method lists laid
+ /// end to end, each one 8-byte aligned.
+ ///
+ /// A list is `{uint32 entsizeAndFlags, uint32 count}` followed by `count`
+ /// entries of `entsizeAndFlags & 0xFFFC` bytes. Bit 31 marks the relative
+ /// form, whose entry is three `int32` fields — `name`, `types`, `imp` —
+ /// each relative to *its own* address.
+ ///
+ /// Returns the IMP virtual address of every entry whose `name` field
+ /// resolves into `targets`.
+ static func relativeMethodListIMPs(
+ in data: Data,
+ section: MachOSectionInfo,
+ naming targets: Set<UInt64>
+ ) -> [UInt64] {
+ let base = Int(section.fileOffset)
+ let size = Int(section.size)
+ guard base >= 0, size > 0, base + size <= data.count else { return [] }
+
+ var found: [UInt64] = []
+ var offset = 0
+ while offset + methodListHeaderSize <= size {
+ let header = data.loadLE(UInt32.self, at: base + offset)
+ let count = Int(data.loadLE(UInt32.self, at: base + offset + 4))
+ let entrySize = Int(header & methodListEntrySizeMask)
+ guard header & relativeMethodListFlag != 0,
+ entrySize == relativeMethodEntrySize,
+ count > 0,
+ methodListHeaderSize + entrySize * count <= size - offset
+ else { break }
+
+ let entriesStart = offset + methodListHeaderSize
+ for index in 0 ..< count {
+ let entryOffset = entriesStart + index * entrySize
+ if let impVA = relativeMethodEntryIMP(
+ in: data,
+ fileOffset: base + entryOffset,
+ virtualAddress: section.address + UInt64(entryOffset),
+ naming: targets
+ ) {
+ found.append(impVA)
+ }
+ }
+
+ offset = alignUp(entriesStart + entrySize * count, to: methodListAlignment)
+ }
+ return found
+ }
+
+ /// The Python's strategy, kept for the layouts the structural walk cannot
+ /// parse: treat every 4-byte-aligned word in `section` as the `name` field
+ /// of a relative method entry and keep the ones that resolve into `targets`.
+ static func scanRelativeMethodEntryIMPs(
+ in data: Data,
+ section: MachOSectionInfo,
+ naming targets: Set<UInt64>
+ ) -> [UInt64] {
+ let base = Int(section.fileOffset)
+ let size = Int(section.size)
+ guard base >= 0, size >= relativeMethodEntrySize, base + size <= data.count else { return [] }
+
+ var found: [UInt64] = []
+ var offset = 0
+ while offset + relativeMethodEntrySize <= size {
+ if let impVA = relativeMethodEntryIMP(
+ in: data,
+ fileOffset: base + offset,
+ virtualAddress: section.address + UInt64(offset),
+ naming: targets
+ ) {
+ found.append(impVA)
+ }
+ offset += 4
+ }
+ return found
+ }
+
+ /// `imp` of the relative method entry at `fileOffset`, when its `name`
+ /// field resolves into `targets`.
+ static func relativeMethodEntryIMP(
+ in data: Data,
+ fileOffset: Int,
+ virtualAddress: UInt64,
+ naming targets: Set<UInt64>
+ ) -> UInt64? {
+ guard fileOffset >= 0, fileOffset + relativeMethodEntrySize <= data.count else { return nil }
+ let nameRelative = Int32(bitPattern: data.loadLE(UInt32.self, at: fileOffset))
+ let nameVA = UInt64(bitPattern: Int64(bitPattern: virtualAddress) &+ Int64(nameRelative))
+ guard targets.contains(nameVA) else { return nil }
+
+ let impFieldOffset = fileOffset + 8
+ let impFieldVA = virtualAddress &+ 8
+ let impRelative = Int32(bitPattern: data.loadLE(UInt32.self, at: impFieldOffset))
+ return UInt64(bitPattern: Int64(bitPattern: impFieldVA) &+ Int64(impRelative))
+ }
+
+ // MARK: - Recording
+
+ private static func makeRecord(site: Site, patched: Data) -> PatchRecord {
+ PatchRecord(
+ patchID: patchID,
+ component: component,
+ fileOffset: site.fileOffset,
+ virtualAddress: site.virtualAddress,
+ originalBytes: site.original,
+ patchedBytes: patched,
+ beforeDisasm: disassemblyText(of: site.original, at: site.virtualAddress),
+ afterDisasm: disassemblyText(of: patched, at: site.virtualAddress),
+ description: "\(method) -> mov x0, #1; ret"
+ )
+ }
+
+ // MARK: - Section helpers
+
+ static let machMagic64: UInt32 = 0xFEED_FACF
+
+ /// Executable section every anchor's answer has to land in.
+ static let textSectionKey = "__TEXT,__text"
+
+ /// Where modern toolchains put packed relative method lists.
+ static let methodListSectionKey = "__TEXT,__objc_methlist"
+
+ /// Sections the strided fallback scan walks, in order: the packed method
+ /// lists again, then the older layouts where method lists sit inside
+ /// `class_ro_t` records. The Python's list, plus `__objc_methlist`.
+ static let scannedSectionKeys = [
+ methodListSectionKey,
+ "__DATA_CONST,__objc_const",
+ "__DATA,__objc_const",
+ "__AUTH_CONST,__objc_const",
+ ]
+
+ /// Selector cstrings live in the first of these that the image has.
+ static let stringSectionKeys = ["__TEXT,__objc_methname", "__TEXT,__cstring"]
+
+ /// `{uint32 entsizeAndFlags, uint32 count}`.
+ static let methodListHeaderSize = 8
+ /// Lists are laid out back to back on an 8-byte boundary.
+ static let methodListAlignment = 8
+ /// `entsizeAndFlags` bit 31 — entries are relative, not pointers.
+ static let relativeMethodListFlag: UInt32 = 0x8000_0000
+ /// The entry-size field, with the flag bits masked off.
+ static let methodListEntrySizeMask: UInt32 = 0xFFFC
+ /// `{int32 name, int32 types, int32 imp}`.
+ static let relativeMethodEntrySize = 12
+ /// `DYLD_CHAINED_PTR_64` rebase: `target` is the low 36 bits.
+ static let chainedRebaseTargetMask: UInt64 = 0x0000_000F_FFFF_FFFF
+
+ static func section(_ sections: [String: MachOSectionInfo], _ keys: String...) -> MachOSectionInfo? {
+ for key in keys {
+ if let section = sections[key] { return section }
+ }
+ return nil
+ }
+
+ /// The image's preferred load address: the `__TEXT` segment's `vmaddr`,
+ /// read off the section table so no extra segment walk is needed.
+ static func imageBase(_ sections: [String: MachOSectionInfo]) -> UInt64 {
+ sections[textSectionKey].map { $0.address - UInt64($0.fileOffset) } ?? 0
+ }
+
+ /// Map a file offset back to a virtual address through the section table.
+ ///
+ /// Zero-fill sections (`__bss`, `__common`) carry a file offset of 0 and
+ /// would otherwise claim the Mach-O header, so they are skipped. The
+ /// candidates are walked in file order rather than in the dictionary's,
+ /// which has no defined order — two runs over the same bytes must resolve
+ /// the same address.
+ static func virtualAddress(ofFileOffset offset: Int, sections: [String: MachOSectionInfo]) -> UInt64? {
+ for section in sections.values.sorted(by: { $0.fileOffset < $1.fileOffset }) {
+ let start = Int(section.fileOffset)
+ guard start > 0 else { continue }
+ if offset >= start, offset < start + Int(section.size) {
+ return section.address + UInt64(offset - start)
+ }
+ }
+ return nil
+ }
+
+ // MARK: - Formatting
+
+ static func describe(_ site: Site) -> String {
+ let va = site.virtualAddress.map { " va 0x\(hex($0))" } ?? ""
+ return "foff 0x\(hex(UInt64(site.fileOffset)))\(va) [\(site.anchor.rawValue)]"
+ }
+
+ static func disassemblyText(of bytes: Data, at virtualAddress: UInt64?) -> String {
+ ARM64Disassembler()
+ .disassemble(bytes, at: virtualAddress ?? 0)
+ .map { $0.operandString.isEmpty ? $0.mnemonic : "\($0.mnemonic) \($0.operandString)" }
+ .joined(separator: "; ")
+ }
+
+ static func hex(_ value: UInt64) -> String {
+ String(value, radix: 16, uppercase: true)
+ }
+
+ static func alignUp(_ value: Int, to alignment: Int) -> Int {
+ (value + alignment - 1) & ~(alignment - 1)
+ }
+
+ /// Zero-base a `Data` so the integer subscripts used throughout are valid.
+ static func rebased(_ data: Data) -> Data {
+ data.startIndex == 0 ? data : Data(data)
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swift b/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swift
new file mode 100644
index 00000000..3144f0d5
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swift
@@ -0,0 +1,641 @@
+// CFWJetsam.swift — Defuse the launchd jetsam panic guard in /sbin/launchd.
+//
+// WHY
+// ---
+// `/sbin/launchd` is pid 1. Under the vphone kernel the jetsam property
+// category for a Daemon job is never initialized, so the guard that checks it
+// takes its failure path, logs "jetsam property category (%s) is not
+// initialized" and tears the process down. initproc dying is a panic, and the
+// panic is a loop: the guest never reaches userspace. Forcing the guard's
+// success return is what lets the boot continue.
+//
+// The blast radius here is the largest of the six standalone Mach-O patchers:
+// a wrong four bytes in pid 1 is a guest that never boots, with no shell to
+// debug it from. Everything below is therefore anchored on what the compiler
+// had to emit, never on where it happened to land.
+//
+// REVEAL PROCEDURE (no file offset, virtual address or instruction byte in
+// this file is written down — all four steps derive their address):
+//
+// 1. String anchor — find the jetsam-not-initialized format string in the
+// image, then walk back to the start of the enclosing NUL-terminated C
+// string, because code references a string's start, never a substring.
+// 2. Cross-reference — find the ADRP+ADD pair in `__TEXT,__text` that
+// computes that string's VA. That is the guard's failure path: the
+// instruction that loads the message it is about to log.
+// 3. Enclosing function — walk back from the xref to the function's
+// `PACIBSP` prologue. This is the one place this port deliberately
+// diverges from `scripts/patchers/cfw_patch_jetsam.py`, which instead
+// scans a blind 0x300-byte window that can start inside the *previous*
+// function. Both pick the same instruction on iOS 27.0 / 24A435 (proven
+// byte for byte in `CFWJetsamTests`); the function bound is what keeps
+// that true when the code around it moves. The blind window survives as
+// the fallback for a function with no PAC prologue.
+// 4. Gate — inside that function, take the earliest conditional branch whose
+// target is a *return block*: a basic block reaching `ret`/`retab`/`retaa`
+// without leaving through a branch first. Earliest, because that one skips
+// the most of the jetsam path. Rewrite it to an unconditional `b` to the
+// same target, so every path that reaches the gate returns through its
+// success path. Not every path reaches it: on 24A435 a `cbz x1` four
+// instructions earlier branches past the gate, as it did before the patch.
+//
+// The replacement comes from `ARM64Encoder.encodeB(from:to:)`, and the branch
+// classification from Capstone's typed operands — never from operand text.
+// Capstone 6 prints a branch target as `0x237ef22bc` where the Capstone 5 the
+// Python links prints `#0x237ef22bc`; that string reaches a log line and a
+// `PatchRecord` description, never a patched byte.
+//
+// IDEMPOTENCE
+// -----------
+// Running twice is a clean no-op. That is not free here, and getting it wrong
+// is a live bug in the reference: rewriting the gate drops it out of the
+// conditional-branch set, so the Python's backward scan walks past it and
+// patches the *next* branch into the same return block — a second, wrong site
+// on a binary that was already correct (`scripts/patchers/README_reference_capture.md`,
+// "The non-idempotency itself is a separate, pre-existing bug"). The fix has to
+// live inside the scan, because on a re-run neither implementation picks the
+// site it patched before. So the scan collects unconditional `b`s into a return
+// block as well, and an earlier one of those means a previous run already did
+// the work. See `Verdict.alreadyPatched`.
+//
+// SIGNING
+// -------
+// `reattest` defaults to false, matching the reference: every call site
+// (`scripts/cfw_install_{dev,jb,exp}.sh`, `cfw-kit/jb/install.sh`) runs `ldid`
+// over the result immediately afterwards, which rebuilds the signature whole.
+// Pass `reattest: true` when nothing downstream re-signs — it recomputes the
+// slot hash of the one page this patch dirties through
+// `CFWMachOCodeSignature`, short tail slot included, and the result passes
+// `codesign -v`.
+
+import Capstone
+import Foundation
+
+public enum CFWJetsamPatcher {
+ // MARK: - Anchors
+
+ /// The jetsam guard's failure message, most specific first, exactly as the
+ /// reference orders them. The first anchor that resolves all the way to a
+ /// patch site wins; one that resolves partway is abandoned for the next.
+ ///
+ /// The middle entry is the substring that actually matches on iOS 27.0 —
+ /// the full sentence is a format string (`(%s)`) in the image, not the
+ /// rendered text.
+ public static let panicStringAnchors = [
+ "jetsam property category (Daemon) is not initialized",
+ "jetsam property category",
+ "initproc exited -- exit reason namespace 7 subcode 0x1",
+ ]
+
+ /// Conditional branches that can gate the jetsam failure path. Matched
+ /// against Capstone's mnemonic, which is the instruction's identity; the
+ /// target comes from its typed immediate operand.
+ static let conditionalBranchMnemonics: Set<String> = [
+ "b.eq", "b.ne", "b.cs", "b.hs", "b.cc", "b.lo", "b.mi", "b.pl",
+ "b.vs", "b.vc", "b.hi", "b.ls", "b.ge", "b.lt", "b.gt", "b.le",
+ "cbz", "cbnz", "tbz", "tbnz",
+ ]
+
+ /// How far back to look for the enclosing function's `PACIBSP` prologue.
+ /// A quarter of a page of instructions is well past any launchd function
+ /// that references a log string.
+ static let maxFunctionPrologueScan = 0x400
+
+ /// The reference's blind backward window, kept as the fallback for a
+ /// function whose prologue does not sign the link register.
+ static let fallbackScanWindow = 0x300
+
+ /// Instructions to decode from a branch target while deciding whether it is
+ /// a return block.
+ static let returnBlockProbeInstructions = 8
+
+ /// `ARM64Disassembler` is stateless across calls and `Sendable`.
+ private static let disassembler = ARM64Disassembler()
+
+ // MARK: - Outcome
+
+ /// What one run did.
+ public struct Outcome: Sendable {
+ public enum Verdict: Sendable, Equatable, CustomStringConvertible {
+ /// The gate was live and has been rewritten.
+ case patched
+ /// An unconditional branch into the function's return block already
+ /// sits ahead of every conditional one. A previous run wrote it;
+ /// nothing was written and nothing needed re-attesting.
+ case alreadyPatched
+ /// A dry run that located a live gate and stopped short of writing.
+ case wouldPatch
+
+ public var description: String {
+ switch self {
+ case .patched: "patched"
+ case .alreadyPatched: "already patched"
+ case .wouldPatch: "would patch"
+ }
+ }
+ }
+
+ public let verdict: Verdict
+ /// Which of `panicStringAnchors` resolved.
+ public let anchor: String
+ /// File offset of the branch that was (or would be) rewritten.
+ public let gateOffset: Int
+ /// Virtual address of the same.
+ public let gateVMA: UInt64
+ /// File offset the gate branches to — the function's return block.
+ public let returnBlockOffset: Int
+ /// File offset of the enclosing function's first instruction.
+ public let functionOffset: Int
+ /// The record of the single write, on a run that wrote or would write.
+ public let record: PatchRecord?
+ /// Slot hashes re-attestation replaced, on a run that wrote with
+ /// `reattest: true`.
+ public let rehashes: [CFWSlotRehash]
+
+ public init(
+ verdict: Verdict,
+ anchor: String,
+ gateOffset: Int,
+ gateVMA: UInt64,
+ returnBlockOffset: Int,
+ functionOffset: Int,
+ record: PatchRecord? = nil,
+ rehashes: [CFWSlotRehash] = []
+ ) {
+ self.verdict = verdict
+ self.anchor = anchor
+ self.gateOffset = gateOffset
+ self.gateVMA = gateVMA
+ self.returnBlockOffset = returnBlockOffset
+ self.functionOffset = functionOffset
+ self.record = record
+ self.rehashes = rehashes
+ }
+
+ /// Sites this run put on disk — 1 on a live patch, 0 otherwise.
+ public var sitesWritten: Int { verdict == .patched ? 1 : 0 }
+ }
+
+ // MARK: - Entry points
+
+ /// Patch `/sbin/launchd` in place.
+ ///
+ /// `reattest: true` recomputes the slot hash of the page the patch dirties
+ /// so the binary still verifies on its own; leave it false when the caller
+ /// re-signs (every current one does).
+ @discardableResult
+ public static func patch(
+ fileAt url: URL,
+ dryRun: Bool = false,
+ reattest: Bool = false,
+ log: ((String) -> Void)? = { FileHandle.standardError.write(Data(($0 + "\n").utf8)) }
+ ) throws -> Outcome {
+ guard FileManager.default.fileExists(atPath: url.path) else {
+ throw PatcherError.fileNotFound(url.path)
+ }
+ var data = try Data(contentsOf: url)
+ let outcome = try patch(&data, dryRun: dryRun, reattest: reattest, log: log)
+ if !dryRun, outcome.verdict == .patched {
+ try data.write(to: url)
+ }
+ return outcome
+ }
+
+ /// Patch a `/sbin/launchd` image held in memory.
+ @discardableResult
+ public static func patch(
+ _ data: inout Data,
+ dryRun: Bool = false,
+ reattest: Bool = false,
+ log: ((String) -> Void)? = nil
+ ) throws -> Outcome {
+ if data.startIndex != 0 { data = Data(data) }
+
+ let image = try Image(data: data)
+ guard let site = try locate(in: image, log: log) else {
+ throw PatcherError.patchSiteNotFound(
+ "launchd jetsam: no anchor string resolved to a conditional branch "
+ + "into its function's return block"
+ )
+ }
+
+ let gateVMA = image.virtualAddress(ofTextOffset: site.gateOffset)
+ log?(" Found jetsam anchor '\(site.anchor)'")
+ log?(String(format: " string start: va:0x%llX", site.stringVMA))
+ log?(String(format: " xref at foff:0x%X", site.xrefOffset))
+ log?(String(format: " function at foff:0x%X", site.functionOffset))
+
+ if site.isAlreadyPatched {
+ log?(String(
+ format: " [=] already patched at 0x%X: b 0x%X (jetsam panic guard bypass)",
+ site.gateOffset,
+ site.returnBlockOffset
+ ))
+ return Outcome(
+ verdict: .alreadyPatched,
+ anchor: site.anchor,
+ gateOffset: site.gateOffset,
+ gateVMA: gateVMA,
+ returnBlockOffset: site.returnBlockOffset,
+ functionOffset: site.functionOffset
+ )
+ }
+
+ guard let branch = ARM64Encoder.encodeB(from: site.gateOffset, to: site.returnBlockOffset) else {
+ throw PatcherError.invalidFormat(
+ String(
+ format: "launchd jetsam: b 0x%X is out of range from 0x%X",
+ site.returnBlockOffset,
+ site.gateOffset
+ )
+ )
+ }
+
+ let original = Data(data[site.gateOffset ..< site.gateOffset + 4])
+ let record = PatchRecord(
+ patchID: "launchd_jetsam.panic_guard_bypass",
+ component: "launchd_jetsam",
+ fileOffset: site.gateOffset,
+ virtualAddress: gateVMA,
+ originalBytes: original,
+ patchedBytes: branch,
+ beforeDisasm: describe(original, at: site.gateOffset),
+ afterDisasm: describe(branch, at: site.gateOffset),
+ description: String(
+ format: "conditional branch -> unconditional b 0x%X (jetsam panic guard bypass)",
+ site.returnBlockOffset
+ )
+ )
+
+ log?(String(
+ format: " %@ at 0x%X: %@ -> %@",
+ dryRun ? "[.] would patch" : "[+] patching",
+ site.gateOffset,
+ record.beforeDisasm,
+ record.afterDisasm
+ ))
+
+ guard !dryRun else {
+ return Outcome(
+ verdict: .wouldPatch,
+ anchor: site.anchor,
+ gateOffset: site.gateOffset,
+ gateVMA: gateVMA,
+ returnBlockOffset: site.returnBlockOffset,
+ functionOffset: site.functionOffset,
+ record: record
+ )
+ }
+
+ data.replaceSubrange(site.gateOffset ..< site.gateOffset + 4, with: branch)
+ guard Data(data[site.gateOffset ..< site.gateOffset + 4]) == branch else {
+ throw PatcherError.patchVerificationFailed(
+ String(format: "launchd jetsam: post-write verify failed at 0x%X", site.gateOffset)
+ )
+ }
+
+ var rehashes: [CFWSlotRehash] = []
+ if reattest {
+ rehashes = try CFWMachOCodeSignature.reattest(&data, modifiedOffsets: [site.gateOffset])
+ for rehash in rehashes { log?(" [.] re-attest \(rehash)") }
+ }
+
+ log?(String(format: " [+] Patched at 0x%X: jetsam panic guard bypass", site.gateOffset))
+ return Outcome(
+ verdict: .patched,
+ anchor: site.anchor,
+ gateOffset: site.gateOffset,
+ gateVMA: gateVMA,
+ returnBlockOffset: site.returnBlockOffset,
+ functionOffset: site.functionOffset,
+ record: record,
+ rehashes: rehashes
+ )
+ }
+
+ // MARK: - Image
+
+ /// The parts of the Mach-O this patch reads: `__TEXT,__text`, and every
+ /// file-backed section, so a string hit can be turned into a VA.
+ struct Image {
+ let data: Data
+ let textOffset: Int
+ let textSize: Int
+ let textVMA: UInt64
+ /// File-backed sections, in file order. Zero-fill sections (`__bss`,
+ /// `__common`) are dropped: their `fileOffset` is 0, so leaving them in
+ /// lets one claim the range `[0, size)` and mislocate a hit in the
+ /// Mach-O header.
+ let sections: [MachOSectionInfo]
+
+ init(data rawData: Data) throws {
+ // Zero-base so the integer subscripts used throughout are valid.
+ let data = rawData.startIndex == 0 ? rawData : Data(rawData)
+ guard data.count > 32, data.loadLE(UInt32.self, at: 0) == 0xFEED_FACF else {
+ throw PatcherError.invalidFormat("launchd jetsam: not a 64-bit Mach-O")
+ }
+ let parsed = MachOParser.parseSections(from: data)
+ guard let text = parsed["__TEXT,__text"] else {
+ throw PatcherError.invalidFormat("launchd jetsam: __TEXT,__text not found")
+ }
+ guard Int(text.fileOffset) + Int(text.size) <= data.count else {
+ throw PatcherError.invalidFormat("launchd jetsam: __TEXT,__text runs past the file")
+ }
+ self.data = data
+ textOffset = Int(text.fileOffset)
+ textSize = Int(text.size)
+ textVMA = text.address
+ sections = parsed.values
+ .filter { $0.fileOffset != 0 && $0.size != 0 }
+ .sorted { $0.fileOffset < $1.fileOffset }
+ }
+
+ var textEnd: Int { textOffset + textSize }
+
+ func isInText(_ offset: Int) -> Bool { offset >= textOffset && offset < textEnd }
+
+ /// VA of a `__TEXT,__text` file offset. `__text` is one contiguous
+ /// mapping, so the two differ by a constant.
+ func virtualAddress(ofTextOffset offset: Int) -> UInt64 {
+ textVMA &+ UInt64(offset - textOffset)
+ }
+
+ /// The file-backed section containing `offset`, if any.
+ func section(containing offset: Int) -> MachOSectionInfo? {
+ sections.first {
+ offset >= Int($0.fileOffset) && offset < Int($0.fileOffset) + Int($0.size)
+ }
+ }
+ }
+
+ // MARK: - Reveal
+
+ /// Everything step 4 needs, plus what the log prints about how it got there.
+ struct Site {
+ let anchor: String
+ let stringVMA: UInt64
+ let xrefOffset: Int
+ let functionOffset: Int
+ let gateOffset: Int
+ let returnBlockOffset: Int
+ /// True when `gateOffset` already holds the unconditional branch.
+ let isAlreadyPatched: Bool
+ }
+
+ /// Walk the anchors in order, taking the first that resolves all the way to
+ /// a gate. An anchor that resolves partway — present but with no xref, or
+ /// an xref with no qualifying branch — is abandoned for the next one, which
+ /// is what the reference does.
+ static func locate(in image: Image, log: ((String) -> Void)? = nil) throws -> Site? {
+ for anchor in panicStringAnchors {
+ guard let hit = image.data.range(of: Data(anchor.utf8))?.lowerBound else { continue }
+ guard let section = image.section(containing: hit) else { continue }
+
+ let stringOffset = cStringStart(in: image.data, containing: hit, sectionStart: Int(section.fileOffset))
+ let stringVMA = section.address &+ UInt64(stringOffset - Int(section.fileOffset))
+
+ guard let xrefOffset = findADRPADDReference(to: stringVMA, in: image) else {
+ log?(" [.] anchor '\(anchor)' has no ADRP+ADD xref in __TEXT,__text")
+ continue
+ }
+
+ let functionOffset = functionStart(before: xrefOffset, in: image)
+ guard let gate = findReturnGate(from: functionOffset, to: xrefOffset, in: image) else {
+ log?(String(format: " [.] anchor '%@' has no return-block gate in [0x%X, 0x%X)",
+ anchor, functionOffset, xrefOffset))
+ continue
+ }
+
+ return Site(
+ anchor: anchor,
+ stringVMA: stringVMA,
+ xrefOffset: xrefOffset,
+ functionOffset: functionOffset,
+ gateOffset: gate.offset,
+ returnBlockOffset: gate.target,
+ isAlreadyPatched: gate.isUnconditional
+ )
+ }
+ return nil
+ }
+
+ /// Start of the NUL-terminated C string containing `offset`.
+ ///
+ /// Code references a string's first byte, so a substring anchor has to be
+ /// widened to the whole string before its address means anything.
+ static func cStringStart(in data: Data, containing offset: Int, sectionStart: Int) -> Int {
+ var position = offset - 1
+ while position >= sectionStart, data[position] != 0 {
+ position -= 1
+ }
+ return position + 1
+ }
+
+ /// File offset of the ADRP in the first `ADRP Rd, page` / `ADD Rd, Rd, #off`
+ /// pair in `__TEXT,__text` that computes `targetVMA`.
+ ///
+ /// The pair need not be adjacent — the compiler interleaves other setup
+ /// between them — so the most recent ADRP per destination register is kept
+ /// and matched against a later ADD that reads it, within eight instructions.
+ ///
+ /// Decoded from the instruction words rather than through Capstone: this is
+ /// the one scan that covers all of `__text` (93k instructions in launchd),
+ /// and the two opcode predicates below are exact. `ARM64Inst` documents the
+ /// same split — raw predicates for the hot loops, Capstone once a specific
+ /// instruction is in hand, which is what every semantic test in this file
+ /// uses.
+ static func findADRPADDReference(to targetVMA: UInt64, in image: Image) -> Int? {
+ let targetPage = targetVMA & ~0xFFF
+ let targetPageOffset = UInt32(targetVMA & 0xFFF)
+
+ // Rd -> (instruction index, page the ADRP produced)
+ var pending: [UInt32: (index: Int, page: UInt64)] = [:]
+
+ var offset = image.textOffset
+ var index = 0
+ while offset + 4 <= image.textEnd {
+ let word = image.data.loadLE(UInt32.self, at: offset)
+
+ if ARM64Inst.isADRP(word) {
+ pending[ARM64Inst.rd(word)] = (index, adrpPage(word, at: image.virtualAddress(ofTextOffset: offset)))
+ } else if isAddImm64(word) {
+ let rn = ARM64Inst.rn(word)
+ if let adrp = pending[rn],
+ adrp.page == targetPage,
+ ARM64Inst.addSubImm12(word) == targetPageOffset,
+ index - adrp.index <= 8
+ {
+ return image.textOffset + (adrp.index * 4)
+ }
+ }
+
+ offset += 4
+ index += 1
+ }
+ return nil
+ }
+
+ /// Page address an ADRP at `pc` produces.
+ static func adrpPage(_ word: UInt32, at pc: UInt64) -> UInt64 {
+ let immhi = (word >> 5) & 0x7FFFF
+ let immlo = (word >> 29) & 0x3
+ let imm21 = (immhi << 2) | immlo
+ // Sign-extend the 21-bit immediate, then scale by the 4 KiB page.
+ let signed = Int64(Int32(bitPattern: imm21 << 11) >> 11)
+ return (pc & ~0xFFF) &+ UInt64(bitPattern: signed << 12)
+ }
+
+ /// `ADD Xd, Xn, #imm12` with `LSL #0` — `[31:22] = 1001000100`.
+ ///
+ /// Requiring `sh == 0` is what keeps `add xd, xn, #imm, lsl #12` out; a
+ /// shifted-register `add` has a different `[28:24]` and never reaches here.
+ static func isAddImm64(_ word: UInt32) -> Bool { (word & 0xFFC0_0000) == 0x9100_0000 }
+
+ /// First instruction of the function containing `offset`.
+ ///
+ /// `PACIBSP` is the prologue of every non-leaf arm64e function, and it is
+ /// the only instruction that can only appear at a function's entry, which
+ /// makes it the one reliable boundary here. A `ret` is not: this function's
+ /// own success epilogue returns *before* the failure path the xref sits in,
+ /// so a backward scan for `ret` stops inside the function it is trying to
+ /// delimit.
+ ///
+ /// With no prologue in range this falls back to the reference's blind
+ /// window, so a function that does not sign its link register still gets
+ /// the reference's behaviour rather than none.
+ static func functionStart(before offset: Int, in image: Image) -> Int {
+ let floor = max(image.textOffset, offset - maxFunctionPrologueScan)
+ var scan = offset - 4
+ while scan >= floor {
+ if image.data.loadLE(UInt32.self, at: scan) == ARM64.pacibspU32 { return scan }
+ scan -= 4
+ }
+ return max(image.textOffset, offset - fallbackScanWindow)
+ }
+
+ /// The gate: the earliest branch in `[start, end)` whose target is a return
+ /// block of the same function.
+ ///
+ /// Unconditional `b`s are collected alongside the conditional ones so that
+ /// the shape this patch *writes* is recognised on a second run. An
+ /// unconditional one earlier than every conditional candidate is a previous
+ /// run's work — there is nothing left to do, and rewriting the next
+ /// conditional branch instead (which is what the reference does) would put
+ /// a second, unasked-for patch into pid 1.
+ ///
+ /// The limit of that signal, stated so nobody has to rediscover it: a
+ /// compiler-emitted `b` to the epilogue, earlier in this window than any
+ /// conditional gate, would read as already-patched on a *pristine* image and
+ /// the patch would never be applied. There is none on iOS 27.0 / 24A435 —
+ /// `gateIsTheEarliestQualifyingBranch` walks the window and proves it — and
+ /// `revealStepsAreSelfConsistent` asserts `!isAlreadyPatched` on the pristine
+ /// binary, so a firmware that grows one fails the suite rather than quietly
+ /// shipping an unpatched pid 1.
+ static func findReturnGate(
+ from start: Int,
+ to end: Int,
+ in image: Image
+ ) -> (offset: Int, target: Int, isUnconditional: Bool)? {
+ var liveGate: (offset: Int, target: Int)?
+ var patchedGate: (offset: Int, target: Int)?
+
+ var offset = start
+ while offset + 4 <= end {
+ defer { offset += 4 }
+ guard let insn = disassembler.disassembleOne(in: image.data, at: offset) else { continue }
+
+ let unconditional = insn.mnemonic == "b"
+ guard unconditional || conditionalBranchMnemonics.contains(insn.mnemonic) else { continue }
+ guard let target = branchTarget(insn), image.isInText(target) else { continue }
+ guard isReturnBlock(target, in: image) else { continue }
+
+ if unconditional {
+ if patchedGate == nil { patchedGate = (offset, target) }
+ } else if liveGate == nil {
+ liveGate = (offset, target)
+ }
+ if liveGate != nil, patchedGate != nil { break }
+ }
+
+ switch (liveGate, patchedGate) {
+ case let (live?, patched?):
+ return patched.offset < live.offset
+ ? (patched.offset, patched.target, true)
+ : (live.offset, live.target, false)
+ case let (live?, nil):
+ return (live.offset, live.target, false)
+ case let (nil, patched?):
+ return (patched.offset, patched.target, true)
+ case (nil, nil):
+ return nil
+ }
+ }
+
+ /// Branch destination as a file offset, from Capstone's typed operands.
+ ///
+ /// Every branch form here carries its destination as its last immediate:
+ /// `b`/`b.<cond>` have only one operand, `cbz`/`cbnz` a register then the
+ /// target, `tbz`/`tbnz` a register, a bit number, then the target. Reading
+ /// the last immediate covers all three without parsing operand text. The
+ /// instruction was decoded at its own file offset, so the immediate is a
+ /// file offset too.
+ static func branchTarget(_ insn: Instruction) -> Int? {
+ guard let detail = insn.aarch64 else { return nil }
+ for operand in detail.operands.reversed() where operand.type == AARCH64_OP_IMM {
+ return Int(operand.imm)
+ }
+ return nil
+ }
+
+ /// True when the instruction returns from the function — `ret`, `retaa`,
+ /// `retab`, by Capstone's own classification rather than a mnemonic prefix.
+ ///
+ /// The prefix test this replaces (`hasPrefix("ret")`) is close enough on
+ /// this image and wrong in principle; the group is what Capstone decoded
+ /// the instruction to mean.
+ static func isReturn(_ insn: Instruction) -> Bool {
+ insn.groups.contains(UInt8(CS_GRP_RET.rawValue))
+ }
+
+ /// True when control leaves the block here without falling through: an
+ /// unconditional jump (`b`, `br`, `braa`, …) or a call (`bl`, `blr`,
+ /// `blraa`, …).
+ ///
+ /// A conditional branch is deliberately not one of these. It falls through,
+ /// so the return can still be the instruction after it, which is what makes
+ /// a compare-and-return epilogue a return block.
+ ///
+ /// Groups again, not prefixes: `hasPrefix("br")` also swallows `brk`, which
+ /// is a breakpoint (`CS_GRP_INT`) and ends nothing, and `hasPrefix("bl")`
+ /// would only reach the authenticated calls by accident.
+ static func leavesBlock(_ insn: Instruction) -> Bool {
+ if insn.groups.contains(UInt8(CS_GRP_CALL.rawValue)) { return true }
+ return insn.groups.contains(UInt8(CS_GRP_JUMP.rawValue))
+ && !conditionalBranchMnemonics.contains(insn.mnemonic)
+ }
+
+ /// True when the block at `offset` returns from the function.
+ ///
+ /// Decodes forward until the block returns, until control leaves it some
+ /// other way (so it is not a return block), or until the end of `__text` or
+ /// the probe limit.
+ static func isReturnBlock(_ offset: Int, in image: Image) -> Bool {
+ for step in 0 ..< returnBlockProbeInstructions {
+ let probe = offset + step * 4
+ guard probe + 4 <= image.textEnd else { return false }
+ guard let insn = disassembler.disassembleOne(in: image.data, at: probe) else { continue }
+ if isReturn(insn) { return true }
+ if leavesBlock(insn) { return false }
+ }
+ return false
+ }
+
+ // MARK: - Logging
+
+ /// `mnemonic operands` for a single instruction, for the record's
+ /// before/after fields. Text only — nothing matches on it.
+ static func describe(_ bytes: Data, at offset: Int) -> String {
+ guard let insn = disassembler.disassembleOne(bytes, at: UInt64(offset)) else { return bytes.hex }
+ return insn.operandString.isEmpty ? insn.mnemonic : "\(insn.mnemonic) \(insn.operandString)"
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/Patches/CFWMobileactivationd.swift b/sources/FirmwarePatcher/CFW/Patches/CFWMobileactivationd.swift
new file mode 100644
index 00000000..9b6ede8d
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/Patches/CFWMobileactivationd.swift
@@ -0,0 +1,645 @@
+// CFWMobileactivationd.swift — force `-[DeviceType should_hactivate]` to YES.
+//
+// Swift port of `scripts/patchers/cfw_patch_mobileactivationd.py`, driven by
+// `cfw.py patch-mobileactivationd <binary>` from `cfw_install{,_dev}.sh` and
+// `cfw-kit/lib/base_stages.sh`'s `stage_mobileactivationd`.
+//
+// `mobileactivationd` asks `-[DeviceType should_hactivate]` whether the device
+// may activate itself without talking to albert.apple.com. On a real iPhone the
+// answer is NO and Setup.app sits on the activation screen forever, which is
+// where an unpatched guest ends up. The method is a synthesised `_BOOL` ivar
+// getter — two instructions, `ldrb w0, [x0, #<ivar>]` then `ret` — so forcing
+// YES is `mov x0, #1 ; ret` over the same eight bytes. No cave, no shifting.
+//
+// Anchoring, and why it is not the Python's
+// ----------------------------------------
+// The Python takes two shortcuts this does not copy.
+//
+// 1. It resolves the IMP with a *substring* search over LC_SYMTAB
+// (`find_symbol_va(data, "should_hactivate")`) and patches the first hit.
+// On the iOS 27.0 / 24A435 iPhone17,3 binary four symbols contain that
+// substring — the method, `_objc_msgSend$should_hactivate` (a selector
+// stub in `__TEXT,__objc_stubs`), `_OBJC_IVAR_$_DeviceType._should_hactivate`
+// (a *data* offset in `__DATA`) and a duplicate N_STAB debug entry. It
+// works today only because the method happens to sort first. Patching the
+// ivar-offset word instead would corrupt every access to the ivar.
+// Here the symbol is matched by its exact ObjC name, STAB debug entries
+// are skipped, and the symbol must be N_SECT-defined.
+//
+// 2. Its ObjC-metadata fallback is dead code on this binary, twice over: it
+// takes the first `memmem` hit for `should_hactivate\0`, which lands at
+// the tail of the property-attribute string `TB,R,N,V_should_hactivate`
+// — the `V` field naming the backing ivar — 0x2F4D bytes before the real
+// selector; and it looks for relative method lists in `__objc_const`,
+// where iOS 16+ no longer puts them (they live in
+// `__TEXT,__objc_methlist`). Called directly on the pristine binary it
+// prints "Selref not found (chained fixups may obscure pointers)" and
+// returns -1. The fallback here finds the NUL-preceded selector,
+// unpacks chained-fixup rebase targets, and walks real relative method
+// lists — so it resolves the same IMP the symbol table does, which is how
+// the anchor is cross-checked rather than trusted.
+//
+// Both routes run. When both resolve they must agree, or the binary is not the
+// shape we were told it was and the run stops. Nothing is a literal address.
+//
+// Re-attestation
+// --------------
+// `codeSigningMonitor == 2` on this stack, so TXM holds the original per-page
+// slot hashes and any byte changed inside an executable mapping is a SIGKILL on
+// first page-in. The touched page is re-hashed through `CFWMachOCodeSignature`.
+// The Python leaves that to the `ldid_sign` that follows it in the shell; doing
+// it here means the binary is runnable the moment it is written, and the later
+// `ldid_sign` stays a no-op-in-effect re-sign. Pass `resign: false` to get the
+// Python's exact bytes.
+
+import Capstone
+import Foundation
+
+/// Forces `-[DeviceType should_hactivate]` to return YES, so the guest
+/// self-activates instead of waiting on Apple's activation service.
+public enum CFWMobileactivationd {
+ // MARK: - Identity
+
+ /// The ObjC method whose result is forced.
+ public static let method = "-[DeviceType should_hactivate]"
+
+ /// The selector, as it appears in `__TEXT,__objc_methname`.
+ public static let selector = "should_hactivate"
+
+ /// Component name, matching `records.set_group("mobileactivationd")`.
+ public static let component = "mobileactivationd"
+
+ /// Record identity, matching the Python's `records.site` label so a captured
+ /// reference and this port sort together.
+ public static let patchID = "mobileactivationd.should_hactivate"
+
+ /// Where progress goes when the caller does not say. The Python prints to
+ /// stdout and `cfw_install*.sh` captures that, so this does too.
+ public static let stdoutLog: @Sendable (String) -> Void = { print($0) }
+
+ // MARK: - Results
+
+ /// Which anchor produced the IMP address.
+ public enum AnchorSource: String, Sendable, Equatable {
+ /// Both the symbol table and the ObjC metadata chain resolved, and agreed.
+ case symbolTableAndObjCMetadata
+ /// Only `LC_SYMTAB` carried the method — a binary whose ObjC metadata
+ /// this port cannot walk (a layout change), but whose symbol is exact.
+ case symbolTable
+ /// Only the ObjC metadata chain resolved — a stripped binary.
+ case objcMetadata
+ }
+
+ /// The located IMP.
+ public struct Anchor: Sendable, Equatable {
+ public let virtualAddress: UInt64
+ public let fileOffset: Int
+ public let source: AnchorSource
+ /// `segment,section` the IMP lands in. Always an executable one.
+ public let section: String
+ }
+
+ /// What a run did.
+ public enum Outcome: String, Sendable, Equatable {
+ /// The eight bytes already read `mov x0, #1 ; ret`. Nothing was written.
+ case alreadyPatched
+ /// `dryRun` was set, so the site was located and reported only.
+ case wouldPatch
+ /// The getter was rewritten and its page re-attested.
+ case patched
+ }
+
+ /// The outcome of one run, and the site it acted on.
+ public struct Report: Sendable {
+ public let outcome: Outcome
+ public let anchor: Anchor
+ /// The write, in the shape the Python's reference capture records it.
+ /// `nil` unless bytes actually changed.
+ public let record: PatchRecord?
+ /// Code-directory slots recomputed for the page the write landed in.
+ /// Empty on a dry run, and on a re-run whose slots already match.
+ public let slotRehashes: [CFWSlotRehash]
+
+ /// Sites whose bytes this run changed. The parity number: the Python
+ /// writes exactly one, and so must this.
+ public var sitesWritten: Int { record == nil ? 0 : 1 }
+ }
+
+ // MARK: - Patching
+
+ /// Patch the `mobileactivationd` at `url` in place.
+ ///
+ /// Idempotent: a second run finds `mov x0, #1 ; ret` already in place,
+ /// reports ``Outcome/alreadyPatched`` and leaves the file untouched, byte
+ /// for byte. It does not error and it does not write the getter twice.
+ ///
+ /// - Parameters:
+ /// - url: The `mobileactivationd` Mach-O to patch.
+ /// - resign: Recompute the code-directory slot hash of the touched page.
+ /// `false` reproduces the Python's output exactly, for byte comparison.
+ /// - dryRun: Locate and report, write nothing.
+ /// - Throws: ``PatcherError/patchSiteNotFound(_:)`` when neither anchor
+ /// resolves, ``PatcherError/invalidFormat(_:)`` when the two anchors
+ /// disagree or the site is not executable code.
+ @discardableResult
+ public static func patch(
+ fileAt url: URL,
+ resign: Bool = true,
+ dryRun: Bool = false,
+ log: ((String) -> Void)? = stdoutLog
+ ) throws -> Report {
+ guard FileManager.default.fileExists(atPath: url.path) else {
+ throw PatcherError.fileNotFound(url.path)
+ }
+ var data = try Data(contentsOf: url)
+ let before = data
+ let report = try patch(&data, resign: resign, dryRun: dryRun, log: log)
+
+ // Written only when something changed, so a no-op run does not even
+ // touch the file's mtime — and so `sha256` before and after a re-run
+ // is trivially the same number.
+ if data != before {
+ try data.write(to: url)
+ }
+ return report
+ }
+
+ /// In-memory form of ``patch(fileAt:resign:dryRun:log:)``.
+ @discardableResult
+ public static func patch(
+ _ data: inout Data,
+ resign: Bool = true,
+ dryRun: Bool = false,
+ log: ((String) -> Void)? = stdoutLog
+ ) throws -> Report {
+ if data.startIndex != 0 { data = Data(data) }
+
+ let anchor = try locateIMP(in: data)
+ log?(" [.] \(method) @ 0x\(hex(anchor.virtualAddress)) "
+ + "-> foff 0x\(hex(UInt64(anchor.fileOffset))) "
+ + "in \(anchor.section) (via \(anchor.source.rawValue))")
+
+ let patched = try replacementBytes()
+ guard data.count >= anchor.fileOffset + patched.count else {
+ throw PatcherError.invalidFormat(
+ "\(method): IMP at 0x\(hex(UInt64(anchor.fileOffset))) is past the end of the file"
+ )
+ }
+ let original = Data(data[anchor.fileOffset ..< anchor.fileOffset + patched.count])
+ let body = try decodeBody(original, at: anchor.virtualAddress)
+
+ log?(" [.] before: \(text(of: body))")
+
+ if original == patched {
+ // The already-patched shape, recognised rather than re-applied.
+ // `8eb6c8b` fixed this exact class of bug for the DSC gates.
+ log?(" [=] already `mov x0, #1 ; ret` at 0x\(hex(anchor.virtualAddress)); "
+ + "nothing to write")
+ let rehashes = dryRun || !resign
+ ? []
+ : try CFWMachOCodeSignature.reattest(&data, modifiedOffsets: touchedOffsets(anchor, patched))
+ if !rehashes.isEmpty {
+ log?(" [+] re-attested \(rehashes.count) stale slot(s): "
+ + rehashes.map(\.description).joined(separator: ", "))
+ }
+ return Report(
+ outcome: .alreadyPatched,
+ anchor: anchor,
+ record: nil,
+ slotRehashes: rehashes
+ )
+ }
+
+ guard isPlausibleGetterBody(body) else {
+ throw PatcherError.invalidFormat(
+ "\(method): body at 0x\(hex(anchor.virtualAddress)) reads `\(text(of: body))`, "
+ + "which is not a two-instruction body this patch can replace"
+ )
+ }
+
+ guard !dryRun else {
+ log?(" [.] dry-run: would write \(original.hex) -> \(patched.hex) "
+ + "at foff 0x\(hex(UInt64(anchor.fileOffset)))")
+ return Report(outcome: .wouldPatch, anchor: anchor, record: nil, slotRehashes: [])
+ }
+
+ data.replaceSubrange(anchor.fileOffset ..< anchor.fileOffset + patched.count, with: patched)
+ log?(" [+] after: \(text(of: try decodeBody(patched, at: anchor.virtualAddress)))")
+
+ let written = Data(data[anchor.fileOffset ..< anchor.fileOffset + patched.count])
+ guard written == patched else {
+ throw PatcherError.patchVerificationFailed(
+ "\(method): site at 0x\(hex(UInt64(anchor.fileOffset))) reads \(written.hex) after write"
+ )
+ }
+
+ var rehashes: [CFWSlotRehash] = []
+ if resign {
+ rehashes = try CFWMachOCodeSignature.reattest(
+ &data,
+ modifiedOffsets: touchedOffsets(anchor, patched)
+ )
+ log?(" [.] re-attested \(rehashes.count) slot(s): "
+ + rehashes.map(\.description).joined(separator: ", "))
+ let unsupported = CFWMachOCodeSignature.unsupportedCodeDirectories(in: data)
+ if !unsupported.isEmpty {
+ log?(" [-] \(unsupported.count) non-SHA256 CodeDirectory(ies) left alone")
+ }
+ }
+
+ log?(" [+] Patched at 0x\(hex(UInt64(anchor.fileOffset))): mov x0, #1; ret")
+ return Report(
+ outcome: .patched,
+ anchor: anchor,
+ record: PatchRecord(
+ patchID: patchID,
+ component: component,
+ fileOffset: anchor.fileOffset,
+ virtualAddress: anchor.virtualAddress,
+ originalBytes: original,
+ patchedBytes: patched,
+ beforeDisasm: text(of: body),
+ afterDisasm: text(of: try decodeBody(patched, at: anchor.virtualAddress)),
+ description: "\(method) -> mov x0, #1; ret"
+ ),
+ slotRehashes: rehashes
+ )
+ }
+
+ // MARK: - Replacement
+
+ /// `mov x0, #1 ; ret`, assembled rather than written down.
+ ///
+ /// The MOVZ comes out of ``ARM64Encoder``, whose every encoder is asserted
+ /// against keystone; `ret` has no operands to encode, so it is the shared
+ /// keystone-generated constant — the same split the Python makes between
+ /// `asm("mov x0, #1")` and its `RET`.
+ static func replacementBytes() throws -> Data {
+ guard let mov = ARM64Encoder.encodeMovzX(rd: 0, imm16: 1) else {
+ throw PatcherError.invalidFormat("could not encode `mov x0, #1`")
+ }
+ return mov + ARM64.ret
+ }
+
+ /// The file offsets whose pages need re-hashing. Both words are listed, not
+ /// just the first: a getter whose second instruction begins a new 4 KiB page
+ /// dirties two slots, and hashing only the first would leave the tail slot
+ /// stale — a SIGKILL the first time that page is demand-paged in.
+ static func touchedOffsets(_ anchor: Anchor, _ patched: Data) -> [Int] {
+ stride(from: anchor.fileOffset, to: anchor.fileOffset + patched.count, by: 4).map { $0 }
+ }
+
+ // MARK: - Anchoring
+
+ /// Resolve the IMP of ``method``, by symbol and by ObjC metadata.
+ ///
+ /// Both routes are independent: one reads `LC_SYMTAB`, the other walks
+ /// `__objc_methname` -> `__objc_selrefs` -> relative method list. When both
+ /// answer they must give the same address.
+ public static func locateIMP(in data: Data) throws -> Anchor {
+ let data = data.startIndex == 0 ? data : Data(data)
+ let segments = MachOParser.parseSegments(from: data)
+ guard !segments.isEmpty else {
+ throw PatcherError.invalidFormat("not a 64-bit Mach-O, or it carries no LC_SEGMENT_64")
+ }
+
+ let bySymbol = symbolVirtualAddress(in: data)
+ let byMetadata = objcMetadataVirtualAddress(in: data, segments: segments)
+
+ let source: AnchorSource
+ let virtualAddress: UInt64
+ switch (bySymbol, byMetadata) {
+ case let (symbol?, metadata?):
+ guard symbol == metadata else {
+ throw PatcherError.invalidFormat(
+ "\(method): symbol table says 0x\(hex(symbol)) but the ObjC method list "
+ + "says 0x\(hex(metadata)) — refusing to guess which is the IMP"
+ )
+ }
+ source = .symbolTableAndObjCMetadata
+ virtualAddress = symbol
+ case let (symbol?, nil):
+ source = .symbolTable
+ virtualAddress = symbol
+ case let (nil, metadata?):
+ source = .objcMetadata
+ virtualAddress = metadata
+ case (nil, nil):
+ throw PatcherError.patchSiteNotFound(
+ "\(method): neither LC_SYMTAB nor the ObjC method lists carry it"
+ )
+ }
+
+ guard let fileOffset = MachOParser.vaToFileOffset(virtualAddress, segments: segments) else {
+ throw PatcherError.invalidFormat(
+ "\(method): VA 0x\(hex(virtualAddress)) maps to no segment"
+ )
+ }
+ guard let section = executableSection(containing: virtualAddress, in: data) else {
+ throw PatcherError.invalidFormat(
+ "\(method): VA 0x\(hex(virtualAddress)) is not inside an executable section — "
+ + "the anchor resolved to data, not code"
+ )
+ }
+
+ return Anchor(
+ virtualAddress: virtualAddress,
+ fileOffset: fileOffset,
+ source: source,
+ section: section
+ )
+ }
+
+ /// The VA of the `LC_SYMTAB` entry whose name is exactly ``method``.
+ ///
+ /// Exact, not a substring: `_objc_msgSend$should_hactivate` and
+ /// `_OBJC_IVAR_$_DeviceType._should_hactivate` both contain the selector and
+ /// neither is the IMP. N_STAB debug entries are skipped — the same address
+ /// arrives twice on this binary, once as N_SECT and once as N_FUN — and the
+ /// symbol must be section-defined with a non-zero value.
+ static func symbolVirtualAddress(in data: Data) -> UInt64? {
+ guard let symtab = MachOParser.parseSymtab(from: data) else { return nil }
+ // <mach-o/nlist.h>: N_STAB masks off the debug entries, N_TYPE selects
+ // the kind, and N_SECT is the one kind that means "defined in a section".
+ let nStab: UInt8 = 0xE0
+ let nTypeMask: UInt8 = 0x0E
+ let nSect: UInt8 = 0x0E
+
+ for index in 0 ..< symtab.nsyms {
+ let entry = symtab.symoff + index * 16 // sizeof(nlist_64)
+ guard entry + 16 <= data.count else { break }
+
+ let typeByte = data[entry + 4]
+ guard typeByte & nStab == 0, typeByte & nTypeMask == nSect else { continue }
+
+ let strx = Int(data.loadLE(UInt32.self, at: entry))
+ let value = data.loadLE(UInt64.self, at: entry + 8)
+ guard value != 0, strx < symtab.strsize else { continue }
+
+ guard let name = cString(in: data, at: symtab.stroff + strx,
+ limit: symtab.stroff + symtab.strsize) else { continue }
+ if name == method { return value }
+ }
+ return nil
+ }
+
+ /// The VA of the IMP, walked out of the ObjC metadata:
+ /// `__objc_methname` selector -> `__objc_selrefs` entry -> the relative
+ /// method-list entry whose `name` field points at that selref -> its `imp`.
+ static func objcMetadataVirtualAddress(
+ in data: Data,
+ segments: [MachOSegmentInfo]
+ ) -> UInt64? {
+ let sections = MachOParser.parseSections(from: data)
+ guard let imageBase = segments.first(where: { $0.name == "__TEXT" })?.vmAddr else {
+ return nil
+ }
+ guard let selectorVA = selectorVirtualAddress(in: data, sections: sections) else {
+ return nil
+ }
+ guard let selrefVA = selectorReferenceVirtualAddress(
+ to: selectorVA, in: data, sections: sections, imageBase: imageBase
+ ) else { return nil }
+
+ return methodImplementation(
+ forSelectorReference: selrefVA, in: data, sections: sections
+ )
+ }
+
+ /// The selector string's VA — the whole string ``selector``, not a suffix of
+ /// a longer one.
+ ///
+ /// `DeviceType`'s property-attribute string `TB,R,N,V_should_hactivate`
+ /// names the backing ivar and sits earlier in the very same section, so a
+ /// plain `memmem` for `should_hactivate\0` — what the Python does — hits its
+ /// tail first. Requiring the preceding byte to be the previous string's NUL
+ /// is what separates a whole selector from a suffix of something longer.
+ static func selectorVirtualAddress(
+ in data: Data,
+ sections: [String: MachOSectionInfo]
+ ) -> UInt64? {
+ let candidates = ["__TEXT,__objc_methname", "__DATA,__objc_methname"]
+ guard let section = candidates.compactMap({ sections[$0] }).first else { return nil }
+
+ let start = Int(section.fileOffset)
+ let end = start + Int(section.size)
+ guard start >= 0, end <= data.count, start < end else { return nil }
+
+ let needle = Data(selector.utf8) + Data([0])
+ var cursor = start
+ while cursor + needle.count <= end {
+ guard let found = data[cursor ..< end].range(of: needle) else { return nil }
+ let offset = found.lowerBound
+ // The first string in the section needs no separator before it.
+ if offset == start || data[offset - 1] == 0 {
+ return section.address + UInt64(offset - start)
+ }
+ cursor = offset + 1
+ }
+ return nil
+ }
+
+ /// The `__objc_selrefs` slot that points at `selectorVA`.
+ ///
+ /// The slots are chained-fixup rebases on this stack, not plain pointers, so
+ /// the raw word is matched three ways: as-is (an already-bound pointer), as a
+ /// 36-bit rebase target relative to the image base, and as an absolute 36-bit
+ /// target. Whichever form the binary uses, the resolved address has to be the
+ /// selector's.
+ static func selectorReferenceVirtualAddress(
+ to selectorVA: UInt64,
+ in data: Data,
+ sections: [String: MachOSectionInfo],
+ imageBase: UInt64
+ ) -> UInt64? {
+ let candidates = [
+ "__DATA,__objc_selrefs",
+ "__DATA_CONST,__objc_selrefs",
+ "__AUTH_CONST,__objc_selrefs",
+ ]
+ guard let section = candidates.compactMap({ sections[$0] }).first else { return nil }
+
+ let start = Int(section.fileOffset)
+ let count = Int(section.size)
+ guard start >= 0, start + count <= data.count else { return nil }
+
+ // dyld_chained_ptr_64_rebase.target is 36 bits wide.
+ let targetMask: UInt64 = (1 << 36) - 1
+
+ for slot in stride(from: 0, to: count - 7, by: 8) {
+ let raw = data.loadLE(UInt64.self, at: start + slot)
+ let target = raw & targetMask
+ if raw == selectorVA || target == selectorVA || imageBase &+ target == selectorVA {
+ return section.address + UInt64(slot)
+ }
+ }
+ return nil
+ }
+
+ /// The IMP of the relative-method-list entry whose `name` field resolves to
+ /// `selrefVA`.
+ ///
+ /// iOS 16+ stores "small" method lists — three `int32`s per entry, each
+ /// relative to its own field's address — in `__TEXT,__objc_methlist`. The
+ /// Python looks in `__objc_const`, which is why its fallback never fires.
+ /// Both are searched here, so an older layout still resolves.
+ static func methodImplementation(
+ forSelectorReference selrefVA: UInt64,
+ in data: Data,
+ sections: [String: MachOSectionInfo]
+ ) -> UInt64? {
+ let candidates = [
+ "__TEXT,__objc_methlist",
+ "__DATA,__objc_const",
+ "__DATA_CONST,__objc_const",
+ "__AUTH_CONST,__objc_const",
+ ]
+ for name in candidates {
+ guard let section = sections[name] else { continue }
+ if let imp = methodImplementation(
+ forSelectorReference: selrefVA, in: data, section: section
+ ) { return imp }
+ }
+ return nil
+ }
+
+ /// Walk one section as a run of relative method lists.
+ ///
+ /// Each list is `{ uint32 entsizeAndFlags; uint32 count; }` followed by
+ /// `count` 12-byte entries, and the next list starts at the following 8-byte
+ /// boundary. A header that is not a 12-byte-entry small list ends the walk:
+ /// past it the bytes are no longer method lists, and matching an "entry" in
+ /// them would be matching noise.
+ static func methodImplementation(
+ forSelectorReference selrefVA: UInt64,
+ in data: Data,
+ section: MachOSectionInfo
+ ) -> UInt64? {
+ let smallMethodListFlag: UInt32 = 0x8000_0000
+ let entrySizeMask: UInt32 = 0x0000_FFFC
+ let entrySize = 12
+
+ let base = Int(section.fileOffset)
+ let size = Int(section.size)
+ guard base >= 0, base + size <= data.count else { return nil }
+
+ var cursor = 0
+ while cursor + 8 <= size {
+ let header = data.loadLE(UInt32.self, at: base + cursor)
+ let count = Int(data.loadLE(UInt32.self, at: base + cursor + 4))
+ guard header & smallMethodListFlag != 0,
+ Int(header & entrySizeMask) == entrySize,
+ count > 0,
+ cursor + 8 + count * entrySize <= size
+ else { return nil }
+
+ for index in 0 ..< count {
+ let entry = cursor + 8 + index * entrySize
+ let entryVA = section.address + UInt64(entry)
+ let nameDelta = Int(data.loadLE(Int32.self, at: base + entry))
+ guard UInt64(bitPattern: Int64(entryVA) + Int64(nameDelta)) == selrefVA else {
+ continue
+ }
+ // { name, types, imp } — the imp field is 8 bytes in, and its
+ // delta is relative to the imp field's own address.
+ let impField = entryVA + 8
+ let impDelta = Int(data.loadLE(Int32.self, at: base + entry + 8))
+ return UInt64(bitPattern: Int64(impField) + Int64(impDelta))
+ }
+ cursor += 8 + count * entrySize
+ cursor = (cursor + 7) & ~7
+ }
+ return nil
+ }
+
+ /// `segment,section` of the executable section containing `va`, or nil when
+ /// the address is not in one.
+ ///
+ /// Executability is read off the segment's `initprot`, not off the segment's
+ /// name, so this keeps working if the IMP ever lives somewhere other than
+ /// `__TEXT,__text`.
+ static func executableSection(containing va: UInt64, in data: Data) -> String? {
+ let vmProtExecute: UInt32 = 0x4
+ var executableSegments: Set<String> = []
+
+ let ncmds = data.loadLE(UInt32.self, at: 16)
+ var offset = 32 // sizeof(mach_header_64)
+ for _ in 0 ..< ncmds {
+ guard offset + 8 <= data.count else { break }
+ let cmd = data.loadLE(UInt32.self, at: offset)
+ let cmdsize = Int(data.loadLE(UInt32.self, at: offset + 4))
+ guard cmdsize > 0 else { break }
+ if cmd == 0x19, offset + 64 <= data.count { // LC_SEGMENT_64
+ let initprot = data.loadLE(UInt32.self, at: offset + 60)
+ if initprot & vmProtExecute != 0 {
+ let raw = data[offset + 8 ..< offset + 24]
+ executableSegments.insert(
+ String(decoding: raw.prefix { $0 != 0 }, as: UTF8.self)
+ )
+ }
+ }
+ offset += cmdsize
+ }
+
+ for (key, section) in MachOParser.parseSections(from: data)
+ where executableSegments.contains(section.segmentName)
+ && va >= section.address && va < section.address + section.size
+ {
+ return key
+ }
+ return nil
+ }
+
+ // MARK: - Body Shape
+
+ /// Decode the eight bytes the patch replaces.
+ static func decodeBody(_ bytes: Data, at va: UInt64) throws -> [Instruction] {
+ let decoded = ARM64Disassembler().disassemble(bytes, at: va, count: 2)
+ guard decoded.count == 2, decoded.allSatisfy({ $0.id != 0 }) else {
+ throw PatcherError.invalidFormat(
+ "\(method): the eight bytes at 0x\(hex(va)) (\(bytes.hex)) are not two "
+ + "decodable instructions"
+ )
+ }
+ return decoded
+ }
+
+ /// Whether the decoded body is something this patch may overwrite.
+ ///
+ /// The method is a synthesised BOOL getter, so the shape to expect is a
+ /// single-register load followed by `ret`. The check is deliberately on the
+ /// *return* — a two-word body ending in `ret`, or a first instruction that
+ /// is a plain function entry — rather than on `ldrb` specifically: a future
+ /// build may spell the getter differently, but overwriting eight bytes that
+ /// are *not* a function's first two words would land mid-function.
+ static func isPlausibleGetterBody(_ body: [Instruction]) -> Bool {
+ guard body.count == 2 else { return false }
+ // A getter: `ldr…/mov… ; ret`.
+ if body[1].mnemonic == "ret" || body[1].mnemonic.hasPrefix("reta") { return true }
+ // A real function: a recognisable prologue in the first word, so the
+ // eight bytes are the head of a function and an early return is safe.
+ let prologue: Set<String> = ["pacibsp", "paciasp", "stp", "sub"]
+ return prologue.contains(body[0].mnemonic)
+ }
+
+ // MARK: - Helpers
+
+ static func text(of instructions: [Instruction]) -> String {
+ instructions
+ .map { $0.operandString.isEmpty ? $0.mnemonic : "\($0.mnemonic) \($0.operandString)" }
+ .joined(separator: "; ")
+ }
+
+ /// Read a NUL-terminated ASCII string, refusing to run past `limit`.
+ static func cString(in data: Data, at offset: Int, limit: Int) -> String? {
+ guard offset >= 0, offset < min(limit, data.count) else { return nil }
+ var end = offset
+ let stop = min(limit, data.count)
+ while end < stop, data[end] != 0 { end += 1 }
+ return String(data: data[offset ..< end], encoding: .ascii)
+ }
+
+ static func hex(_ value: UInt64) -> String {
+ String(value, radix: 16, uppercase: true)
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/Patches/CFWSeputil.swift b/sources/FirmwarePatcher/CFW/Patches/CFWSeputil.swift
new file mode 100644
index 00000000..9a143b52
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/Patches/CFWSeputil.swift
@@ -0,0 +1,482 @@
+// CFWSeputil.swift — pin seputil's gigalocker file name to "AA".
+//
+// `seputil` keeps the SEP's "gigalocker" blob in a file named after the
+// device's own UUID, built with a two-field format string:
+//
+// snprintf(path, n, "%s/%s.gl", mountpoint, uuid); // -> /mnt7/<uuid>.gl
+//
+// A vphone guest does not carry the UUID the gigalocker on the restored
+// filesystem was written for, so seputil looks for a file that is not there.
+// Rewriting the *uuid* field of that one literal to the constant `AA` makes
+// every lookup resolve to `<mountpoint>/AA.gl`, which is the name the install
+// gives the blob it ships. The mountpoint field is deliberately left as `%s`:
+// it is chosen at runtime between `/mnt7` and `/private/xarts` and both must
+// keep working.
+//
+// This is a data patch, not a code patch — the two bytes rewritten are ASCII
+// inside `__TEXT,__cstring`, so no instruction is assembled here and the ARM64
+// encoder has nothing to contribute. Capstone is used for the *anchor*: the
+// literal has to be the one seputil actually formats with, which is proven by
+// finding the `adrp`/`add` pair in `__TEXT,__text` that materialises its
+// address.
+//
+// Anchoring, in order, none of it positional:
+//
+// 1. `__TEXT,__cstring` from the load commands — a literal anywhere else is
+// not a C string this binary formats with.
+// 2. The one whole NUL-terminated literal in that section shaped
+// `<dir>/<2-byte field>.gl`, where the field reads `%s` (pristine) or `AA`
+// (already patched). Whole-literal equality, so the tail of a longer
+// string cannot match.
+// 3. An `adrp`+`add` in `__TEXT,__text` computing that literal's VA, matched
+// on decoded operands.
+// 4. The field to rewrite is the one after the literal's own last `/`.
+//
+// Port of `scripts/patchers/cfw_patch_seputil.py`, which stays the independent
+// reference: `CFWSeputilTests` runs the Python on one clone of a real seputil
+// and this on another and compares the files byte for byte.
+//
+// Two deliberate differences from the reference, both of them narrowing:
+//
+// * The Python searches the whole file for the *substring* `"/%s.gl\0"` and
+// patches the two bytes after the `/`. On this binary that substring is the
+// tail of `"%s/%s.gl"` and the result is the same byte, but the search is
+// not bounded to `__cstring`, does not require the match to be a whole
+// literal, and takes the first hit without checking that anything refers to
+// it. All three are tightened here.
+// * The Python leaves the code signature stale, because `cfw_install*.sh`
+// runs `ldid_sign` over the binary immediately afterwards. This
+// re-attests the page it dirtied through `CFWMachOCodeSignature`, so the
+// binary that leaves this function verifies on its own. Pass
+// `reattest: false` to reproduce the reference's bytes exactly.
+
+import Capstone
+import Foundation
+
+public enum CFWSeputil {
+ // MARK: - Anchors
+
+ /// Where the format string lives. A literal outside this section is not one
+ /// the binary formats with, so the search never leaves it.
+ public static let cstringSection = (segment: "__TEXT", section: "__cstring")
+
+ /// Where a reference to the literal has to come from.
+ public static let textSection = (segment: "__TEXT", section: "__text")
+
+ /// The conversion the pristine literal uses for the gigalocker's name.
+ public static let uuidConversion = "%s"
+
+ /// What this patch pins that field to.
+ public static let uuidReplacement = "AA"
+
+ /// The suffix that makes a two-field format string a gigalocker path
+ /// rather than any other path-shaped literal in the binary.
+ public static let gigalockerSuffix = ".gl"
+
+ /// How far past an `adrp` its `add` may sit. Eight instructions — the same
+ /// window `KernelPatcherBase.findStringRefs` uses for the same job.
+ static let addSearchWindow = 8
+
+ /// One disassembler for the whole patcher; `ARM64Disassembler` is `Sendable`
+ /// and stateless across calls.
+ private static let disassembler = ARM64Disassembler()
+
+ /// Default sink for the progress lines, matching the other patchers.
+ public static let stderrLog: @Sendable (String) -> Void = { line in
+ FileHandle.standardError.write(Data((line + "\n").utf8))
+ }
+
+ // MARK: - Site
+
+ /// The literal this patch rewrites, and the field inside it.
+ public struct Site: Sendable, Equatable {
+ /// File offset of the literal's first byte.
+ public let literalOffset: Int
+ /// The literal's virtual address.
+ public let literalVMA: UInt64
+ /// The literal as it currently reads.
+ public let literal: String
+ /// File offset of the two-byte field after the literal's last `/`.
+ public let fieldOffset: Int
+ /// That field's virtual address.
+ public let fieldVMA: UInt64
+ /// True while the field still holds `%s`; false once it holds `AA`.
+ public let isPristine: Bool
+
+ /// The offsets the write dirties. Two, not one: a literal can straddle
+ /// a page boundary, and then two slots need re-attesting.
+ public var modifiedOffsets: [Int] {
+ Array(fieldOffset ..< fieldOffset + CFWSeputil.uuidReplacement.utf8.count)
+ }
+ }
+
+ // MARK: - Outcome
+
+ /// What one run did.
+ public struct Outcome: Sendable {
+ public enum Verdict: Sendable, Equatable, CustomStringConvertible {
+ /// The field already reads `AA`. Nothing was written, nothing was
+ /// re-attested — a second run over an installed binary lands here.
+ case alreadyPatched
+ /// A dry run that found a pristine field and stopped before writing.
+ case wouldPatch
+ /// The field was rewritten, and the page it sits in re-attested
+ /// unless the caller asked otherwise.
+ case patched
+
+ public var description: String {
+ switch self {
+ case .alreadyPatched: "already patched"
+ case .wouldPatch: "would patch"
+ case .patched: "patched"
+ }
+ }
+ }
+
+ public let verdict: Verdict
+ public let site: Site
+ /// Addresses of the `add` instructions that materialise the literal.
+ public let references: [UInt64]
+ /// The record of the single write, on a run that wrote or would write.
+ public let record: PatchRecord?
+ /// Slot hashes re-attestation replaced. Empty when `reattest` was off.
+ public let rehashes: [CFWSlotRehash]
+
+ public init(
+ verdict: Verdict,
+ site: Site,
+ references: [UInt64],
+ record: PatchRecord? = nil,
+ rehashes: [CFWSlotRehash] = []
+ ) {
+ self.verdict = verdict
+ self.site = site
+ self.references = references
+ self.record = record
+ self.rehashes = rehashes
+ }
+
+ /// Sites this run put on disk — 1 on a live patch, 0 otherwise. Mirrors
+ /// what `patch_seputil()` reports.
+ public var sitesWritten: Int { verdict == .patched ? 1 : 0 }
+ }
+
+ // MARK: - Entry points
+
+ /// Patch the seputil binary at `url`.
+ ///
+ /// - Parameters:
+ /// - dryRun: locate and report, write nothing.
+ /// - reattest: recompute the slot hash of the page the write dirties.
+ /// On by default, so the binary verifies without an external re-sign.
+ /// Off reproduces `cfw_patch_seputil.py`'s bytes exactly.
+ @discardableResult
+ public static func patch(
+ fileAt url: URL,
+ dryRun: Bool = false,
+ reattest: Bool = true,
+ log: ((String) -> Void)? = stderrLog
+ ) throws -> Outcome {
+ guard FileManager.default.fileExists(atPath: url.path) else {
+ throw PatcherError.fileNotFound(url.path)
+ }
+ log?(" [.] \(url.path)")
+ var data = try Data(contentsOf: url)
+ let outcome = try patch(&data, dryRun: dryRun, reattest: reattest, log: log)
+ if outcome.verdict == .patched {
+ try data.write(to: url)
+ }
+ return outcome
+ }
+
+ /// Patch an in-memory seputil image.
+ @discardableResult
+ public static func patch(
+ _ data: inout Data,
+ dryRun: Bool = false,
+ reattest: Bool = true,
+ log: ((String) -> Void)? = stderrLog
+ ) throws -> Outcome {
+ if data.startIndex != 0 { data = Data(data) }
+
+ let (cstring, text) = try sections(in: data)
+ let site = try findSite(in: data, cstring: cstring)
+ log?(
+ " [.] literal \"\(site.literal)\" @ 0x\(hex(site.literalVMA)) "
+ + "(file 0x\(hex(site.literalOffset)))"
+ )
+
+ // The literal has to be one the code actually formats with. Without
+ // this, a build that moved the gigalocker path into a different string
+ // would still offer some `<dir>/%s.gl` to rewrite and the patch would
+ // report success while changing nothing that runs.
+ let references = references(to: site.literalVMA, in: data, text: text)
+ guard !references.isEmpty else {
+ throw PatcherError.patchSiteNotFound(
+ "seputil: \"\(site.literal)\" @ 0x\(hex(site.literalVMA)) has no adrp+add "
+ + "reference in \(textSection.segment),\(textSection.section); "
+ + "it is not the literal the gigalocker path is built from"
+ )
+ }
+ log?(" [.] referenced from \(references.map { "0x" + hex($0) }.joined(separator: ", "))")
+
+ guard site.isPristine else {
+ log?(
+ " [=] field at 0x\(hex(site.fieldOffset)) already reads "
+ + "\"\(uuidReplacement)\"; nothing to patch/re-attest"
+ )
+ return Outcome(verdict: .alreadyPatched, site: site, references: references)
+ }
+
+ let replacement = Data(uuidReplacement.utf8)
+ let range = site.fieldOffset ..< site.fieldOffset + replacement.count
+ let original = Data(data[range])
+ let record = record(for: site, original: original, replacement: replacement)
+
+ guard !dryRun else {
+ log?(" [+] would write \"\(uuidReplacement)\" at 0x\(hex(site.fieldOffset))")
+ return Outcome(
+ verdict: .wouldPatch,
+ site: site,
+ references: references,
+ record: record
+ )
+ }
+
+ data.replaceSubrange(range, with: replacement)
+ log?(
+ " [+] 0x\(hex(site.fieldOffset)): \(original.hex) -> \(replacement.hex) "
+ + "(\"\(site.literal)\" -> \"\(patchedLiteral(of: site))\")"
+ )
+
+ var rehashes: [CFWSlotRehash] = []
+ if reattest {
+ for directory in CFWMachOCodeSignature.unsupportedCodeDirectories(in: data) {
+ log?(
+ " [-] CodeDirectory @ 0x\(hex(directory.offset)) is hashType "
+ + "\(directory.hashType), not SHA-256 — left untouched"
+ )
+ }
+ rehashes = try CFWMachOCodeSignature.reattest(&data, modifiedOffsets: site.modifiedOffsets)
+ for rehash in rehashes { log?(" [+] \(rehash)") }
+ }
+
+ // Re-read the site the same way it was found, rather than trusting the
+ // write: anything that moved underneath it shows up here.
+ let after = try findSite(in: data, cstring: cstring)
+ guard after.fieldOffset == site.fieldOffset, !after.isPristine else {
+ throw PatcherError.patchVerificationFailed(
+ "seputil: post-write read back \"\(after.literal)\" at 0x\(hex(after.fieldOffset))"
+ )
+ }
+ log?(" [+] seputil gigalocker name pinned to \"\(uuidReplacement)\(gigalockerSuffix)\"")
+
+ return Outcome(
+ verdict: .patched,
+ site: site,
+ references: references,
+ record: record,
+ rehashes: rehashes
+ )
+ }
+
+ // MARK: - Reveal
+
+ /// The two sections this patcher reads, from the load commands.
+ static func sections(in data: Data) throws -> (cstring: MachOSectionInfo, text: MachOSectionInfo) {
+ let all = MachOParser.parseSections(from: data)
+ guard let cstring = all["\(cstringSection.segment),\(cstringSection.section)"] else {
+ throw PatcherError.invalidFormat(
+ "seputil: no \(cstringSection.segment),\(cstringSection.section) section "
+ + "(not a 64-bit Mach-O, or not the binary we were handed)"
+ )
+ }
+ guard let text = all["\(textSection.segment),\(textSection.section)"] else {
+ throw PatcherError.invalidFormat(
+ "seputil: no \(textSection.segment),\(textSection.section) section"
+ )
+ }
+ return (cstring, text)
+ }
+
+ /// The single gigalocker path literal in `__TEXT,__cstring`.
+ ///
+ /// Matching is on whole NUL-terminated literals, so `"%s.gl"` — the very
+ /// next literal after the one we want on the reference binary — cannot be
+ /// mistaken for it, and neither can the tail of any longer string.
+ ///
+ /// Throws when there is no candidate or more than one: with two, there is
+ /// no evidence which one seputil formats with, and picking either is a
+ /// coin flip that boots or does not.
+ static func findSite(in data: Data, cstring: MachOSectionInfo) throws -> Site {
+ let start = Int(cstring.fileOffset)
+ let end = start + Int(cstring.size)
+ guard start >= 0, end <= data.count, start <= end else {
+ throw PatcherError.invalidFormat(
+ "seputil: \(cstringSection.section) runs to 0x\(hex(end)), past the end of a "
+ + "0x\(hex(data.count))-byte file"
+ )
+ }
+
+ var sites: [Site] = []
+ var cursor = start
+ while cursor < end {
+ var terminator = cursor
+ while terminator < end, data[terminator] != 0 { terminator += 1 }
+ guard terminator < end else { break } // unterminated tail, not a literal
+ let literal = Array(data[cursor ..< terminator])
+ if let field = fileField(of: literal), let pristine = pristineness(of: literal[field]) {
+ sites.append(Site(
+ literalOffset: cursor,
+ literalVMA: cstring.address + UInt64(cursor - start),
+ literal: String(decoding: literal, as: UTF8.self),
+ fieldOffset: cursor + field.lowerBound,
+ fieldVMA: cstring.address + UInt64(cursor - start + field.lowerBound),
+ isPristine: pristine
+ ))
+ }
+ cursor = terminator + 1
+ }
+
+ guard let site = sites.first else {
+ throw PatcherError.patchSiteNotFound(
+ "seputil: no \"<dir>/\(uuidConversion)\(gigalockerSuffix)\" literal in "
+ + "\(cstringSection.segment),\(cstringSection.section)"
+ )
+ }
+ guard sites.count == 1 else {
+ throw PatcherError.patchSiteNotFound(
+ "seputil: \(sites.count) gigalocker path literals "
+ + "(\(sites.map { "\"\($0.literal)\" @ 0x" + hex($0.literalOffset) }.joined(separator: ", "))); "
+ + "refusing to guess which one builds the path"
+ )
+ }
+ return site
+ }
+
+ /// The range, within `literal`, of the field after its last `/`.
+ ///
+ /// `"%s/%s.gl"` names a directory and a file. The field this patch pins is
+ /// the file's, so it is read off the literal's own last separator instead
+ /// of being counted in from either end.
+ static func fileField(of literal: [UInt8]) -> Range<Int>? {
+ let suffix = Array(gigalockerSuffix.utf8)
+ let width = uuidReplacement.utf8.count
+ guard literal.count > suffix.count,
+ literal.suffix(suffix.count).elementsEqual(suffix),
+ let slash = literal.lastIndex(of: UInt8(ascii: "/"))
+ else { return nil }
+ let fieldStart = slash + 1
+ let fieldEnd = literal.count - suffix.count
+ guard fieldEnd - fieldStart == width else { return nil }
+ return fieldStart ..< fieldEnd
+ }
+
+ /// `true` for a field that still reads `%s`, `false` for one already
+ /// reading `AA`, `nil` for anything else — which is not this patch's site.
+ static func pristineness(of field: ArraySlice<UInt8>) -> Bool? {
+ if field.elementsEqual(uuidConversion.utf8) { return true }
+ if field.elementsEqual(uuidReplacement.utf8) { return false }
+ return nil
+ }
+
+ /// Addresses of the `add` instructions that, with their `adrp`, materialise
+ /// `vma` somewhere in `__TEXT,__text`.
+ ///
+ /// Pairing is the same shape `KernelPatcherBase.findStringRefs` uses, but
+ /// read off Capstone's decoded operands rather than raw encodings: an
+ /// `adrp` whose immediate is the literal's page, then an `add` within the
+ /// window whose source register is that `adrp`'s destination and whose
+ /// immediate is the literal's page offset.
+ static func references(to vma: UInt64, in data: Data, text: MachOSectionInfo) -> [UInt64] {
+ let start = Int(text.fileOffset)
+ let size = Int(text.size)
+ guard start >= 0, size > 0, start + size <= data.count else { return [] }
+ let instructions = disassembler.disassemble(Data(data[start ..< start + size]), at: text.address)
+
+ let page = vma & ~0xFFF
+ let pageOffset = Int64(vma & 0xFFF)
+
+ var sites: [UInt64] = []
+ for (index, insn) in instructions.enumerated() {
+ guard insn.mnemonic == "adrp",
+ let operands = insn.aarch64?.operands,
+ operands.count == 2,
+ operands[0].type == AARCH64_OP_REG,
+ operands[1].type == AARCH64_OP_IMM,
+ UInt64(bitPattern: operands[1].imm) == page
+ else { continue }
+
+ let base = operands[0].reg.rawValue
+ let limit = Swift.min(index + addSearchWindow, instructions.count - 1)
+ var cursor = index + 1
+ while cursor <= limit {
+ let candidate = instructions[cursor]
+ cursor += 1
+ guard candidate.mnemonic == "add",
+ let addOperands = candidate.aarch64?.operands,
+ addOperands.count == 3,
+ addOperands[0].type == AARCH64_OP_REG,
+ addOperands[1].type == AARCH64_OP_REG,
+ addOperands[1].reg.rawValue == base,
+ addOperands[2].type == AARCH64_OP_IMM,
+ addOperands[2].imm == pageOffset,
+ !isShiftedAddImmediate(candidate)
+ else { continue }
+ sites.append(candidate.address)
+ break
+ }
+ }
+ return sites
+ }
+
+ /// True when an `add` immediate carries `lsl #12`.
+ ///
+ /// The Swift Capstone wrapper does not surface an operand's shift, so the
+ /// `sh` field is read off the instruction's own 32-bit encoding — still a
+ /// property of the decode, never of the printed operand text. Without it an
+ /// `add xD, xN, #imm, lsl #12` could be paired as if it computed
+ /// `page + imm`, which is a different address than it really forms.
+ static func isShiftedAddImmediate(_ insn: Instruction) -> Bool {
+ guard insn.bytes.count == 4 else { return false }
+ let word = UInt32(insn.bytes[0])
+ | UInt32(insn.bytes[1]) << 8
+ | UInt32(insn.bytes[2]) << 16
+ | UInt32(insn.bytes[3]) << 24
+ return (word >> 22) & 1 == 1
+ }
+
+ // MARK: - Reporting
+
+ /// How the literal reads once the field is rewritten.
+ static func patchedLiteral(of site: Site) -> String {
+ var literal = Array(site.literal.utf8)
+ guard let field = fileField(of: literal) else { return site.literal }
+ literal.replaceSubrange(field, with: Array(uuidReplacement.utf8))
+ return String(decoding: literal, as: UTF8.self)
+ }
+
+ /// The record for the one write, with the reference's own `patchID`,
+ /// `component` and wording so a captured reference compares field for
+ /// field.
+ private static func record(for site: Site, original: Data, replacement: Data) -> PatchRecord {
+ PatchRecord(
+ patchID: "seputil.gigalocker_uuid",
+ component: "seputil",
+ fileOffset: site.fieldOffset,
+ virtualAddress: site.fieldVMA,
+ originalBytes: original,
+ patchedBytes: replacement,
+ description: "gigalocker path format '/\(uuidConversion)\(gigalockerSuffix)' "
+ + "-> '/\(uuidReplacement)\(gigalockerSuffix)'"
+ )
+ }
+
+ private static func hex(_ value: UInt64) -> String {
+ String(value, radix: 16, uppercase: true)
+ }
+
+ private static func hex(_ value: Int) -> String {
+ String(value, radix: 16, uppercase: true)
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/Patches/CFWWatchdogd.swift b/sources/FirmwarePatcher/CFW/Patches/CFWWatchdogd.swift
new file mode 100644
index 00000000..8831fcb7
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/Patches/CFWWatchdogd.swift
@@ -0,0 +1,869 @@
+// CFWWatchdogd.swift — force watchdogd's cached "am I a VM?" byte to 1.
+//
+// Port of `scripts/patchers/cfw_patch_watchdogd.py` (453 lines). EXP only.
+//
+// Why the patch exists
+// --------------------
+// The EXP variant renames the kernel's `kern.hv_vmm_present` sysctl OID
+// (`KernelEXPPatchHvVmmRename`), so every userland caller that still asks for
+// that name gets ENOENT. `/usr/libexec/watchdogd` caches the answer at startup:
+//
+// adrp x0, <page>
+// add x0, x0, #<off> ; "kern.hv_vmm_present"
+// sub x1, x29, #4 ; &oldval
+// mov x2, sp ; &oldlen
+// mov x3, #0
+// mov x4, #0
+// bl _sysctlbyname ; via __auth_stubs
+// cbnz w0, <skip> ; ENOENT -> skip the store
+// ldur w8, [x29, #-4]
+// cmp w8, #0
+// cset w8, ne ; w8 = (oldval != 0)
+// adrp x9, <page>
+// strb w8, [x9, #<off>] ; the cached byte, a __DATA zero-fill global
+//
+// With the OID renamed the `cbnz` is taken, the store never runs, the cached
+// byte keeps its BSS zero, and a downstream `cbz` on that byte falls into an
+// `_os_crash` wrapper that executes `brk #1`. launchd's `_PanicOnCrash` turns
+// the resulting SIGTRAP into a kernel panic, so this is a boot blocker rather
+// than a cosmetic detection problem.
+//
+// What is changed
+// ---------------
+// Two instructions per site, and nothing else:
+//
+// cbnz w0, <skip> -> nop (never skip the store)
+// cset wN, ne -> mov wN, #1 (store 1, not the sysctl's answer)
+//
+// The cstring is deliberately NOT touched: the EXP design keeps every
+// `kern.hv_vmm_present` consumer on the now-ENOENT name and opts individual
+// consumers out by rewriting their logic, which is what this does. watchdogd
+// then takes its clean-exit branch ("detected virtual machine environment and
+// no watchdog KEXT found, exiting...") instead of the trap.
+//
+// How the site is anchored — no offsets, no byte patterns
+// ------------------------------------------------------
+// Five layers, each read off a Capstone decode or the Mach-O's own tables:
+//
+// 1. The `"kern.hv_vmm_present\0"` literal is found in a cstring section at a
+// NUL boundary, giving its VA.
+// 2. In `__TEXT,__text`, an ADRP+ADD pair whose resolved address is that VA,
+// and whose result reaches x0 before the call — directly, or through a
+// `mov x0, xN`. That is the literal being passed as `sysctlbyname`'s
+// `name` argument rather than merely mentioned.
+// 3. The following `bl`'s target is resolved through the indirect symbol
+// table to the imported function `_sysctlbyname`. This is an in-image
+// symbol lookup, which the Python does not do: it accepts any `bl`.
+// 4. The instruction right after the call gates the store on the call's
+// return value (`cbnz w0`), and the value stored is `cset wN, ne` — the
+// truthiness of the sysctl's out-parameter. The condition is read from
+// Capstone's decoded condition code, not from operand text.
+// 5. The `strb` stores that same wN into an ADRP-relative address inside a
+// `__DATA*` segment — a cached global, not a stack or heap field.
+//
+// Layers 2, 3 and 5 are additions over the Python, which stops at "some `bl`
+// with a `cbnz w0` behind it". On `iPhone17,3` / iOS 27.0 (24A435) both
+// implementations select exactly the same two sites; the extra layers are what
+// keeps that true when the next firmware moves the code.
+//
+// Idempotence
+// -----------
+// A second run must be a no-op, not an error and not a double-apply (commit
+// 8eb6c8b fixed exactly that class of bug elsewhere in this tree). The site
+// matcher therefore recognises both shapes: the pristine one above and the one
+// this patch leaves behind (`nop` … `mov wN, #1` … `strb wN`). A binary whose
+// sites are all in the patched shape is reported as `.alreadyPatched`, nothing
+// is written, and — importantly — re-attestation is skipped too, so the file
+// on disk is byte-for-byte unchanged.
+//
+// Code signing
+// ------------
+// Editing bytes inside `__TEXT,__text` invalidates the SHA-256 slot hash of
+// each containing 4 KiB page. On `codeSigningMonitor == 2` hardware TXM holds
+// those hashes and kills the process on the first demand page-in, so every
+// written offset is handed to `CFWMachOCodeSignature` to re-hash its page.
+//
+// The binary is NOT re-signed with an identity. Re-signing would reset the
+// code-signing identifier to the local filename, which trips launchd's
+// boot-task identity check — the failure mode observed on mobile_obliterator
+// before an earlier attempt was reverted. Mutating the CD does change the
+// binary's cdHash; the JB kernel patch `patch_amfi_cdhash_in_trustcache`
+// short-circuits AMFI's trust-cache check, and that precondition still holds.
+
+import Capstone
+import Foundation
+
+public enum CFWWatchdogd {
+ // MARK: - Anchors
+
+ /// Component name carried by every ``PatchRecord`` this patcher emits.
+ public static let component = "watchdogd"
+
+ /// The sysctl whose cached answer this patch overrides.
+ public static let sysctlName = "kern.hv_vmm_present"
+
+ /// The imported function the call site must resolve to. Layer 3 of the
+ /// anchor: a `bl` that goes anywhere else is not this call.
+ public static let sysctlFunction = "_sysctlbyname"
+
+ /// `"kern.hv_vmm_present\0"` — the terminator is part of the match, so a
+ /// longer name that merely starts with this one cannot pass.
+ static let needle = Data((sysctlName + "\0").utf8)
+
+ /// Sections a C string literal can land in. `__cstring` is where the linker
+ /// puts them; the ObjC name pools could hold the same bytes, and the
+ /// reference scans those too.
+ static let literalSectionNames: Set<String> = [
+ "__cstring", "__objc_methname", "__objc_classname",
+ ]
+
+ static let textSectionKey = "__TEXT,__text"
+
+ /// Segment prefix a cached global must live under. `__bss` and `__common`
+ /// are both `__DATA` sections; the prefix also covers `__DATA_DIRTY`.
+ static let globalSegmentPrefix = "__DATA"
+
+ /// Where the AArch64 C ABI puts `sysctlbyname`'s first argument.
+ static let argumentRegister = "x0"
+
+ // MARK: - Scan windows
+ //
+ // Instruction counts, not byte counts. Same values as the Python, which
+ // measured them against the shipped binary.
+
+ /// ADRP and the ADD that completes it may be separated by argument setup.
+ static let pageToOffsetWindow = 8
+ /// From the ADD that forms the string pointer forward to the call.
+ static let argumentSetupWindow = 20
+ /// From the gate forward to the instruction that produces the stored value.
+ static let gateToValueWindow = 12
+ /// From that instruction forward to the store.
+ static let valueToStoreWindow = 8
+
+ // MARK: - Sites
+
+ /// One "cache the VM-presence answer" site, pristine or already patched.
+ public struct Site: Sendable, Equatable {
+ /// Which shape the site is in.
+ public enum State: String, Sendable {
+ /// The stock shape: `cbnz w0` gating a `cset wN, ne`.
+ case pristine
+ /// This patch's own output: `nop` and `mov wN, #1`.
+ case patched
+ }
+
+ public let state: State
+ /// VA of the `"kern.hv_vmm_present\0"` literal this site loads.
+ public let literalVMA: UInt64
+ /// VA of the ADD that completes the literal's address in x0.
+ public let addVMA: UInt64
+ /// VA of the `bl _sysctlbyname`.
+ public let callVMA: UInt64
+ /// VA of the gate — `cbnz w0` when pristine, `nop` when patched.
+ public let gateVMA: UInt64
+ public let gateFileOffset: Int
+ /// VA of the instruction producing the cached value — `cset wN, ne`
+ /// when pristine, `mov wN, #1` when patched.
+ public let valueVMA: UInt64
+ public let valueFileOffset: Int
+ /// The `w` register carrying the cached value, e.g. `"w8"`.
+ public let valueRegister: String
+ /// That register's number, for re-encoding it as `mov wN, #1`.
+ public let valueRegisterNumber: UInt32
+ /// VA of the `strb` that writes the cached byte.
+ public let storeVMA: UInt64
+ /// VA of the cached byte itself — the `__DATA` global.
+ public let cachedByteVMA: UInt64
+ }
+
+ // MARK: - Report
+
+ /// What a run did, as a whole.
+ public enum Outcome: String, Sendable, Equatable {
+ /// Every site was already in the patched shape; nothing was written.
+ case alreadyPatched
+ /// `dryRun` was set: sites were located and reported only.
+ case wouldPatch
+ /// Bytes were written and the affected pages re-attested.
+ case patched
+ }
+
+ /// The outcome of one run, and what it acted on.
+ public struct Report: Sendable {
+ public let outcome: Outcome
+ /// Every site the matcher recognised, in address order.
+ public let sites: [Site]
+ /// One record per instruction actually rewritten — two per patched
+ /// site. Empty for `.alreadyPatched`.
+ public let records: [PatchRecord]
+ /// Code-directory slots re-hashed as a result.
+ public let rehashedSlots: [CFWSlotRehash]
+
+ /// Sites whose bytes this run changed. The parity number against the
+ /// Python, whose `patch_watchdogd()` returns exactly this.
+ public var sitesWritten: Int { records.count / 2 }
+ }
+
+ /// Where progress goes when the caller does not say. The Python prints to
+ /// stdout and `cfw_install_exp.sh` captures that, so this does too.
+ public static let stdoutLog: @Sendable (String) -> Void = { print($0) }
+
+ // MARK: - Patching
+
+ /// Patch the watchdogd Mach-O at `url` in place.
+ ///
+ /// - Returns: a ``Report``. `.alreadyPatched` leaves the file untouched,
+ /// which is what makes a second install run a clean no-op.
+ /// - Throws: ``PatcherError/invalidFormat(_:)`` when the file is not the
+ /// kind of Mach-O this patch understands, and
+ /// ``PatcherError/patchSiteNotFound(_:)`` when it is but holds no site in
+ /// either shape — a watchdogd that no longer caches the sysctl, which has
+ /// to stop the install rather than be silently skipped.
+ @discardableResult
+ public static func patch(
+ at url: URL,
+ dryRun: Bool = false,
+ log: ((String) -> Void)? = stdoutLog
+ ) throws -> Report {
+ guard FileManager.default.fileExists(atPath: url.path) else {
+ throw PatcherError.fileNotFound(url.path)
+ }
+ var data = try Data(contentsOf: url)
+ let report = try patch(&data, dryRun: dryRun, log: log)
+ if !dryRun, report.outcome == .patched {
+ try data.write(to: url)
+ log?(" [+] \(url.path): wrote \(report.sitesWritten) site(s)")
+ }
+ return report
+ }
+
+ /// In-memory form of ``patch(at:dryRun:log:)``.
+ @discardableResult
+ public static func patch(
+ _ data: inout Data,
+ dryRun: Bool = false,
+ log: ((String) -> Void)? = stdoutLog
+ ) throws -> Report {
+ if data.startIndex != 0 { data = Data(data) }
+
+ let sites = try locateSites(in: data, log: log)
+ let pending = sites.filter { $0.state == .pristine }
+
+ guard !pending.isEmpty else {
+ log?(" [.] all \(sites.count) matching site(s) already patched — nothing to do")
+ return Report(outcome: .alreadyPatched, sites: sites, records: [], rehashedSlots: [])
+ }
+ log?(" [+] found \(sites.count) '\(sysctlName)' cache site(s), \(pending.count) to patch")
+
+ let disassembler = ARM64Disassembler()
+ var records: [PatchRecord] = []
+ var modifiedOffsets: [Int] = []
+
+ for site in pending {
+ guard let value = ARM64Encoder.encodeMovzW(rd: site.valueRegisterNumber, imm16: 1) else {
+ throw PatcherError.patchVerificationFailed(
+ "could not encode `mov \(site.valueRegister), #1`"
+ )
+ }
+ let gate = ARM64.nop
+
+ log?(" site @ add 0x\(hex(site.addVMA)) (bl 0x\(hex(site.callVMA)), "
+ + "gate 0x\(hex(site.gateVMA)), value \(site.valueRegister) 0x\(hex(site.valueVMA)), "
+ + "strb 0x\(hex(site.storeVMA)) -> cached byte 0x\(hex(site.cachedByteVMA)))")
+
+ records.append(record(
+ in: data,
+ at: site.gateFileOffset,
+ virtualAddress: site.gateVMA,
+ patched: gate,
+ id: "\(component).hv_vmm_cache.cbnz@0x\(hex(site.gateVMA))",
+ description: "NOP the cbnz w0 that skips the cached hv_vmm_present store",
+ disassembler: disassembler
+ ))
+ records.append(record(
+ in: data,
+ at: site.valueFileOffset,
+ virtualAddress: site.valueVMA,
+ patched: value,
+ id: "\(component).hv_vmm_cache.cset@0x\(hex(site.valueVMA))",
+ description: "cset \(site.valueRegister) -> mov \(site.valueRegister), #1 "
+ + "(cached 'am I a VM?' byte forced to 1)",
+ disassembler: disassembler
+ ))
+
+ if !dryRun {
+ data.replaceSubrange(site.gateFileOffset ..< site.gateFileOffset + 4, with: gate)
+ data.replaceSubrange(site.valueFileOffset ..< site.valueFileOffset + 4, with: value)
+ }
+ modifiedOffsets.append(site.gateFileOffset)
+ modifiedOffsets.append(site.valueFileOffset)
+ }
+
+ for record in records {
+ log?(" [+] 0x\(hex(UInt64(record.fileOffset))): \(record.beforeDisasm) -> \(record.afterDisasm)")
+ }
+
+ guard !dryRun else {
+ log?(" [.] dry-run — nothing written, no page re-attested")
+ return Report(outcome: .wouldPatch, sites: sites, records: records, rehashedSlots: [])
+ }
+
+ for directory in CFWMachOCodeSignature.unsupportedCodeDirectories(in: data) {
+ log?(" [!] CodeDirectory @0x\(hex(UInt64(directory.offset))) uses hashType "
+ + "\(directory.hashType); its slots are left stale")
+ }
+
+ let rehashed = try CFWMachOCodeSignature.reattest(&data, modifiedOffsets: modifiedOffsets)
+ for slot in rehashed { log?(" [+] re-attest: \(slot)") }
+ log?(" [+] re-attest updated \(rehashed.count) slot(s)")
+
+ try verify(sites: pending, in: data)
+ return Report(outcome: .patched, sites: sites, records: records, rehashedSlots: rehashed)
+ }
+
+ // MARK: - Site discovery
+
+ /// Every VM-presence cache site in `data`, pristine or already patched, in
+ /// address order.
+ ///
+ /// Throws rather than returning an empty array when nothing matches: an
+ /// empty result would be indistinguishable from "this binary does not need
+ /// the patch", and for watchdogd it always does.
+ public static func locateSites(in data: Data, log: ((String) -> Void)? = nil) throws -> [Site] {
+ let data = data.startIndex == 0 ? data : Data(data)
+ let sections = MachOParser.parseSections(from: data)
+ guard let text = sections[textSectionKey] else {
+ throw PatcherError.invalidFormat("no \(textSectionKey) section")
+ }
+ guard let literal = findLiteral(in: data, sections: sections) else {
+ throw PatcherError.patchSiteNotFound("'\(sysctlName)' cstring not present")
+ }
+ log?(" [.] cstring at va:0x\(hex(literal.address)) "
+ + "(foff:0x\(hex(UInt64(literal.fileOffset))), sect=\(literal.section))")
+
+ guard let symbols = CFWWatchdogdSymbolTargets(data: data) else {
+ throw PatcherError.invalidFormat(
+ "no LC_SYMTAB/LC_DYSYMTAB — \(sysctlFunction) cannot be resolved"
+ )
+ }
+
+ let start = Int(text.fileOffset)
+ let end = start + Int(text.size)
+ guard start >= 0, end <= data.count else {
+ throw PatcherError.invalidFormat("\(textSectionKey) falls outside the file")
+ }
+ let instructions = ARM64Disassembler().disassemble(data.subdata(in: start ..< end), at: text.address)
+
+ let segments = MachOParser.parseSegments(from: data)
+ var pages: [UInt32: (page: UInt64, index: Int)] = [:]
+ var sites: [Site] = []
+
+ for (index, instruction) in instructions.enumerated() {
+ // Capstone runs with `skipData` on, so a word it cannot decode
+ // arrives as a data pseudo-instruction rather than ending the
+ // stream. Register state across such a word means nothing.
+ guard instruction.id != 0 else {
+ pages.removeAll()
+ continue
+ }
+
+ if instruction.mnemonic == "adrp" {
+ if let destination = registerNumber(instruction, 0),
+ let page = immediate(instruction, 1)
+ {
+ pages[destination] = (UInt64(bitPattern: page), index)
+ }
+ continue
+ }
+
+ // Layer 2: an ADRP+ADD pair that resolves to the literal. The 64-bit
+ // form only — a `w` destination is arithmetic, not an address.
+ guard instruction.mnemonic == "add",
+ let pointer = registerName(instruction, 0), pointer.hasPrefix("x"),
+ let base = registerNumber(instruction, 1),
+ let offset = immediate(instruction, 2),
+ let page = pages[base],
+ index - page.index <= pageToOffsetWindow,
+ page.page &+ UInt64(bitPattern: offset) == literal.address
+ else { continue }
+
+ guard let site = matchSite(
+ instructions: instructions,
+ addIndex: index,
+ pointerRegister: pointer,
+ literalVMA: literal.address,
+ text: text,
+ segments: segments,
+ symbols: symbols
+ ) else { continue }
+
+ if !sites.contains(where: { $0.gateVMA == site.gateVMA }) { sites.append(site) }
+ }
+
+ guard !sites.isEmpty else {
+ throw PatcherError.patchSiteNotFound(
+ "no '\(sysctlName)' cache site: expected an adrp+add for the cstring reaching "
+ + "\(argumentRegister), a bl \(sysctlFunction), a cbnz w0 gate, a cset wN, ne "
+ + "and a strb into a \(globalSegmentPrefix) global"
+ )
+ }
+ return sites.sorted { $0.gateVMA < $1.gateVMA }
+ }
+
+ /// Match the canonical shape forward from the ADD that formed the string
+ /// pointer. Returns `nil` when any layer of the anchor fails, which is how
+ /// the three unrelated `sysctlbyname` calls in watchdogd are rejected.
+ static func matchSite(
+ instructions: [Instruction],
+ addIndex: Int,
+ pointerRegister: String,
+ literalVMA: UInt64,
+ text: MachOSectionInfo,
+ segments: [MachOSegmentInfo],
+ symbols: CFWWatchdogdSymbolTargets
+ ) -> Site? {
+ // Layer 3: the call, and the import it resolves to.
+ guard let callIndex = firstIndex(
+ in: instructions, from: addIndex + 1, within: argumentSetupWindow,
+ where: { $0.mnemonic == "bl" }
+ ) else { return nil }
+ let call = instructions[callIndex]
+ guard let target = ARM64Encoder.decodeBranchTarget(
+ insn: word(of: call), pc: call.address
+ ), symbols.name(forBranchTarget: target) == sysctlFunction else { return nil }
+
+ // Layer 2, concluded: the literal has to be the call's `name` argument,
+ // not just something this stretch of code also mentions.
+ guard passesLiteral(
+ inRegister: pointerRegister, from: addIndex, toCallAt: callIndex, in: instructions
+ ) else { return nil }
+
+ // Layer 4a: the gate, which must be the very next instruction — the
+ // defensive check on the call's return value.
+ let gateIndex = callIndex + 1
+ guard gateIndex < instructions.count else { return nil }
+ let gate = instructions[gateIndex]
+ let state: Site.State
+ if gate.mnemonic == "cbnz", registerName(gate, 0) == "w0" {
+ state = .pristine
+ } else if gate.mnemonic == "nop" {
+ state = .patched
+ } else {
+ return nil
+ }
+
+ // Layer 4b: the value the store writes. `cset wN, ne` is the stock
+ // truthiness of the sysctl's out-parameter; `mov wN, #1` is what this
+ // patch leaves in its place.
+ guard let valueIndex = firstIndex(
+ in: instructions, from: gateIndex + 1, within: gateToValueWindow,
+ where: { instruction in
+ switch state {
+ case .pristine:
+ instruction.mnemonic == "cset" && instruction.aarch64?.conditionCode == AArch64CC_NE
+ case .patched:
+ isMoveOfOne(instruction)
+ }
+ }
+ ) else { return nil }
+ let value = instructions[valueIndex]
+ guard let valueRegister = registerName(value, 0),
+ let valueNumber = wRegisterNumber(valueRegister) else { return nil }
+
+ // Layer 5: the store of that same register into an ADRP-relative
+ // __DATA address — the cached global.
+ guard let storeIndex = firstIndex(
+ in: instructions, from: valueIndex + 1, within: valueToStoreWindow,
+ where: { $0.mnemonic == "strb" && registerName($0, 0) == valueRegister }
+ ) else { return nil }
+ let store = instructions[storeIndex]
+ guard let memory = memoryOperand(store) else { return nil }
+ guard let basePage = pageAddress(
+ ofRegister: UInt32(memory.base.rawValue),
+ before: storeIndex, notBefore: addIndex, in: instructions
+ ) else { return nil }
+ let cachedByte = basePage &+ UInt64(bitPattern: Int64(memory.disp))
+ guard let segment = segments.first(where: {
+ cachedByte >= $0.vmAddr && cachedByte < $0.vmAddr &+ $0.vmSize
+ }), segment.name.hasPrefix(globalSegmentPrefix) else { return nil }
+
+ return Site(
+ state: state,
+ literalVMA: literalVMA,
+ addVMA: instructions[addIndex].address,
+ callVMA: call.address,
+ gateVMA: gate.address,
+ gateFileOffset: fileOffset(of: gate.address, in: text),
+ valueVMA: value.address,
+ valueFileOffset: fileOffset(of: value.address, in: text),
+ valueRegister: valueRegister,
+ valueRegisterNumber: valueNumber,
+ storeVMA: store.address,
+ cachedByteVMA: cachedByte
+ )
+ }
+
+ /// True when the literal the ADD at `addIndex` formed is in `x0` by the time
+ /// the call at `callIndex` runs.
+ ///
+ /// Two ways that happens, and both occur in Apple's own codegen: the ADD
+ /// writes `x0` outright, or it writes a scratch register that a later
+ /// `mov x0, xN` moves into place. Accepting only the first would make the
+ /// patch miss the site on a build that schedules the argument differently —
+ /// loudly, but still wrongly.
+ static func passesLiteral(
+ inRegister pointer: String,
+ from addIndex: Int,
+ toCallAt callIndex: Int,
+ in instructions: [Instruction]
+ ) -> Bool {
+ if pointer == argumentRegister { return true }
+ for index in (addIndex + 1) ..< callIndex {
+ let instruction = instructions[index]
+ if instruction.mnemonic == "mov",
+ registerName(instruction, 0) == argumentRegister,
+ registerName(instruction, 1) == pointer
+ {
+ return true
+ }
+ }
+ return false
+ }
+
+ /// The literal's VA, file offset and section, matched only at a string
+ /// boundary so a suffix of a longer literal cannot pass.
+ static func findLiteral(
+ in data: Data,
+ sections: [String: MachOSectionInfo]
+ ) -> (address: UInt64, fileOffset: Int, section: String)? {
+ for (key, section) in sections.sorted(by: { $0.key < $1.key })
+ where literalSectionNames.contains(section.sectionName)
+ {
+ let start = Int(section.fileOffset)
+ let end = start + Int(section.size)
+ guard start >= 0, end <= data.count, start < end else { continue }
+ let body = data.subdata(in: start ..< end)
+
+ var searchFrom = body.startIndex
+ while let found = body.range(of: needle, in: searchFrom ..< body.endIndex) {
+ let index = found.lowerBound
+ if index == body.startIndex || body[index - 1] == 0 {
+ return (section.address &+ UInt64(index), start + index, key)
+ }
+ searchFrom = index + 1
+ }
+ }
+ return nil
+ }
+
+ // MARK: - Verification
+
+ /// Read the patched words back out and confirm they are what was written.
+ static func verify(sites: [Site], in data: Data) throws {
+ for site in sites {
+ let gate = data.subdata(in: site.gateFileOffset ..< site.gateFileOffset + 4)
+ guard gate == ARM64.nop else {
+ throw PatcherError.patchVerificationFailed(
+ "gate at 0x\(hex(site.gateVMA)) reads \(gate.hex) after write"
+ )
+ }
+ let value = data.subdata(in: site.valueFileOffset ..< site.valueFileOffset + 4)
+ guard value == ARM64Encoder.encodeMovzW(rd: site.valueRegisterNumber, imm16: 1) else {
+ throw PatcherError.patchVerificationFailed(
+ "value at 0x\(hex(site.valueVMA)) reads \(value.hex) after write"
+ )
+ }
+ }
+ }
+
+ // MARK: - Records
+
+ static func record(
+ in data: Data,
+ at fileOffset: Int,
+ virtualAddress: UInt64,
+ patched: Data,
+ id: String,
+ description: String,
+ disassembler: ARM64Disassembler
+ ) -> PatchRecord {
+ let original = data.subdata(in: fileOffset ..< fileOffset + patched.count)
+ return PatchRecord(
+ patchID: id,
+ component: component,
+ fileOffset: fileOffset,
+ virtualAddress: virtualAddress,
+ originalBytes: original,
+ patchedBytes: patched,
+ beforeDisasm: text(of: original, at: virtualAddress, disassembler),
+ afterDisasm: text(of: patched, at: virtualAddress, disassembler),
+ description: description
+ )
+ }
+
+ static func text(of word: Data, at address: UInt64, _ disassembler: ARM64Disassembler) -> String {
+ guard let instruction = disassembler.disassembleOne(word, at: address) else { return "???" }
+ return instruction.operandString.isEmpty
+ ? instruction.mnemonic
+ : "\(instruction.mnemonic) \(instruction.operandString)"
+ }
+
+ // MARK: - Instruction helpers
+
+ /// Index of the first instruction at or after `from` that satisfies
+ /// `predicate`, within `within` instructions. A word Capstone could not
+ /// decode ends the window: past it the stream is no longer this function's
+ /// instructions.
+ static func firstIndex(
+ in instructions: [Instruction],
+ from: Int,
+ within: Int,
+ where predicate: (Instruction) -> Bool
+ ) -> Int? {
+ guard from >= 0 else { return nil }
+ let end = min(instructions.count, from + within)
+ var index = from
+ while index < end {
+ guard instructions[index].id != 0 else { return nil }
+ if predicate(instructions[index]) { return index }
+ index += 1
+ }
+ return nil
+ }
+
+ /// Page address an ADRP put in `register`, searching back from `before`
+ /// (exclusive) no further than `notBefore`.
+ static func pageAddress(
+ ofRegister register: UInt32,
+ before: Int,
+ notBefore: Int,
+ in instructions: [Instruction]
+ ) -> UInt64? {
+ var index = before - 1
+ while index >= notBefore {
+ let instruction = instructions[index]
+ if instruction.mnemonic == "adrp", registerNumber(instruction, 0) == register,
+ let page = immediate(instruction, 1)
+ {
+ return UInt64(bitPattern: page)
+ }
+ index -= 1
+ }
+ return nil
+ }
+
+ /// True for `mov wN, #1` in any encoding Capstone aliases to it (MOVZ, and
+ /// the ORR-immediate form) — the shape this patch writes.
+ static func isMoveOfOne(_ instruction: Instruction) -> Bool {
+ guard instruction.mnemonic == "mov",
+ let register = registerName(instruction, 0), register.hasPrefix("w"),
+ let value = immediate(instruction, 1)
+ else { return false }
+ return value == 1
+ }
+
+ /// The instruction's raw little-endian word, for the branch decoder.
+ static func word(of instruction: Instruction) -> UInt32 {
+ var value: UInt32 = 0
+ for byte in instruction.bytes.prefix(4).reversed() { value = (value << 8) | UInt32(byte) }
+ return value
+ }
+
+ static func registerName(_ instruction: Instruction, _ index: Int) -> String? {
+ guard let operands = instruction.aarch64?.operands, index < operands.count,
+ operands[index].type == AARCH64_OP_REG
+ else { return nil }
+ return sharedDisassembler.registerName(UInt32(operands[index].reg.rawValue))
+ }
+
+ static func registerNumber(_ instruction: Instruction, _ index: Int) -> UInt32? {
+ guard let operands = instruction.aarch64?.operands, index < operands.count,
+ operands[index].type == AARCH64_OP_REG
+ else { return nil }
+ return UInt32(operands[index].reg.rawValue)
+ }
+
+ static func immediate(_ instruction: Instruction, _ index: Int) -> Int64? {
+ guard let operands = instruction.aarch64?.operands, index < operands.count,
+ operands[index].type == AARCH64_OP_IMM
+ else { return nil }
+ return operands[index].imm
+ }
+
+ static func memoryOperand(_ instruction: Instruction) -> aarch64_op_mem? {
+ guard let operands = instruction.aarch64?.operands,
+ let operand = operands.first(where: { $0.type == AARCH64_OP_MEM })
+ else { return nil }
+ return operand.mem
+ }
+
+ /// `"w8"` -> 8. `wzr` is rejected: the patch re-encodes this register as
+ /// the destination of a `mov #1`, which is meaningless for the zero
+ /// register and would mean the shape was misread.
+ static func wRegisterNumber(_ name: String) -> UInt32? {
+ guard name.hasPrefix("w"), let number = UInt32(name.dropFirst()), number <= 30 else { return nil }
+ return number
+ }
+
+ /// Capstone handle used only for register-name lookups, which need no
+ /// per-call state.
+ static let sharedDisassembler = ARM64Disassembler()
+
+ // MARK: - Addresses
+
+ static func fileOffset(of address: UInt64, in text: MachOSectionInfo) -> Int {
+ Int(text.fileOffset) + Int(address &- text.address)
+ }
+
+ static func hex(_ value: UInt64) -> String {
+ String(value, radix: 16, uppercase: true)
+ }
+}
+
+// MARK: - Symbol targets
+
+/// Resolves a branch target to the name of the function it calls.
+///
+/// Two paths, because a call can reach a function either way:
+///
+/// * through a stub section (`S_SYMBOL_STUBS`, which is what `__auth_stubs`
+/// is), whose entries map one-to-one onto a window of the indirect symbol
+/// table — the classic Mach-O import lookup, and the one watchdogd's
+/// `bl _sysctlbyname` takes;
+/// * directly to a defined symbol, for a statically linked build.
+///
+/// This is deliberately not in `MachOParser`: it needs each section's `flags`,
+/// `reserved1` and `reserved2` and the `LC_DYSYMTAB` indirect table, none of
+/// which that shared parser exposes. It carries this patcher's name because
+/// this patcher is its only caller — the first time a second one needs the same
+/// lookup, move it to `Binary/` under a neutral name rather than growing a copy.
+struct CFWWatchdogdSymbolTargets {
+ /// A section of branch-island stubs, one per imported symbol.
+ struct StubSection {
+ let address: UInt64
+ let size: UInt64
+ /// `reserved2` — bytes per stub.
+ let entrySize: UInt64
+ /// `reserved1` — index of this section's first indirect symbol.
+ let firstIndirectIndex: Int
+ }
+
+ let data: Data
+ let symbolOffset: Int
+ let symbolCount: Int
+ let stringOffset: Int
+ let stringSize: Int
+ let indirectOffset: Int
+ let indirectCount: Int
+ let stubSections: [StubSection]
+
+ static let machMagic64: UInt32 = 0xFEED_FACF
+ static let lcSegment64: UInt32 = 0x19
+ static let lcDysymtab: UInt32 = 0x0B
+ /// `SECTION_TYPE` of a stub section.
+ static let sectionTypeSymbolStubs: UInt32 = 0x08
+ /// Indirect entries that name no import.
+ static let indirectSymbolLocal: UInt32 = 0x8000_0000
+ static let indirectSymbolAbs: UInt32 = 0x4000_0000
+ /// `N_STAB` — a debug entry, never a call target name.
+ static let symbolIsDebug: UInt8 = 0xE0
+
+ init?(data: Data) {
+ let data = data.startIndex == 0 ? data : Data(data)
+ guard data.count > 32, data.loadLE(UInt32.self, at: 0) == Self.machMagic64 else { return nil }
+ guard let symtab = MachOParser.parseSymtab(from: data) else { return nil }
+
+ var indirectOffset = 0
+ var indirectCount = 0
+ var stubs: [StubSection] = []
+
+ let commandCount = data.loadLE(UInt32.self, at: 16)
+ var offset = 32
+ for _ in 0 ..< commandCount {
+ guard offset + 8 <= data.count else { return nil }
+ let command = data.loadLE(UInt32.self, at: offset)
+ let commandSize = Int(data.loadLE(UInt32.self, at: offset + 4))
+ guard commandSize > 0 else { return nil }
+
+ if command == Self.lcDysymtab, offset + 64 <= data.count {
+ indirectOffset = Int(data.loadLE(UInt32.self, at: offset + 56))
+ indirectCount = Int(data.loadLE(UInt32.self, at: offset + 60))
+ } else if command == Self.lcSegment64, offset + 72 <= data.count {
+ let sectionCount = data.loadLE(UInt32.self, at: offset + 64)
+ var section = offset + 72
+ for _ in 0 ..< sectionCount {
+ guard section + 80 <= data.count else { break }
+ let flags = data.loadLE(UInt32.self, at: section + 64)
+ let entrySize = UInt64(data.loadLE(UInt32.self, at: section + 72)) // reserved2
+ if flags & 0xFF == Self.sectionTypeSymbolStubs, entrySize > 0 {
+ stubs.append(StubSection(
+ address: data.loadLE(UInt64.self, at: section + 32),
+ size: data.loadLE(UInt64.self, at: section + 40),
+ entrySize: entrySize,
+ firstIndirectIndex: Int(data.loadLE(UInt32.self, at: section + 68)) // reserved1
+ ))
+ }
+ section += 80
+ }
+ }
+ offset += commandSize
+ }
+
+ self.data = data
+ symbolOffset = symtab.symoff
+ symbolCount = symtab.nsyms
+ stringOffset = symtab.stroff
+ stringSize = symtab.strsize
+ self.indirectOffset = indirectOffset
+ self.indirectCount = indirectCount
+ stubSections = stubs
+ }
+
+ /// Name of the function a `bl`/`b` to `address` ends up in, or `nil`.
+ func name(forBranchTarget address: UInt64) -> String? {
+ importName(atStub: address) ?? definedName(at: address)
+ }
+
+ /// The imported symbol a stub at `address` stands for.
+ func importName(atStub address: UInt64) -> String? {
+ guard indirectCount > 0 else { return nil }
+ for section in stubSections {
+ guard address >= section.address, address < section.address &+ section.size else { continue }
+ let index = section.firstIndirectIndex + Int((address - section.address) / section.entrySize)
+ guard index >= 0, index < indirectCount else { return nil }
+ let entryOffset = indirectOffset + index * 4
+ guard entryOffset + 4 <= data.count else { return nil }
+ let entry = data.loadLE(UInt32.self, at: entryOffset)
+ guard entry & (Self.indirectSymbolLocal | Self.indirectSymbolAbs) == 0 else { return nil }
+ return symbolName(at: Int(entry))
+ }
+ return nil
+ }
+
+ /// A defined symbol whose value is exactly `address`.
+ func definedName(at address: UInt64) -> String? {
+ guard address != 0 else { return nil }
+ for index in 0 ..< symbolCount {
+ let entry = symbolOffset + index * 16
+ guard entry + 16 <= data.count else { return nil }
+ guard data[entry + 4] & Self.symbolIsDebug == 0 else { continue }
+ guard data.loadLE(UInt64.self, at: entry + 8) == address else { continue }
+ return symbolName(at: index)
+ }
+ return nil
+ }
+
+ func symbolName(at index: Int) -> String? {
+ guard index >= 0, index < symbolCount else { return nil }
+ let entry = symbolOffset + index * 16
+ guard entry + 4 <= data.count else { return nil }
+ let stringIndex = Int(data.loadLE(UInt32.self, at: entry))
+ guard stringIndex < stringSize else { return nil }
+ let start = stringOffset + stringIndex
+ guard start < data.count else { return nil }
+ var end = start
+ let limit = min(data.count, stringOffset + stringSize)
+ while end < limit, data[end] != 0 { end += 1 }
+ return String(data: data.subdata(in: start ..< end), encoding: .utf8)
+ }
+}
diff --git a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
index f3086d2b..825de4e1 100644
--- a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
+++ b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
@@ -43,12 +43,10 @@ extension CryptexFilesystemPatcher {
func patchLaunchdCacheLoader(targetMount: String, cfwInput: URL) throws {
let target = URL.init(filePath: targetMount)
let launchdCacheLoaderPath = target.appending(path: "/usr/libexec/launchd_cache_loader")
- let pythonPath = try resources.pythonExecutable()
- let patcherPath = resources.cfwPy
- _ = try runProcess(pythonPath.path, [
- patcherPath.path, "patch-launchd-cache-loader",
- launchdCacheLoaderPath.path
- ])
+ // Patched in place with no `.bak` to restore from, so this is the call
+ // site that needs the port's idempotence. No re-attestation: the sign
+ // below replaces the whole signature anyway.
+ try CFWCacheLoaderPatcher.patch(fileAt: launchdCacheLoaderPath)
_ = try runProcess("/bin/chmod", ["0755", launchdCacheLoaderPath.path])
try VPhoneSigner.sign(
@@ -207,11 +205,9 @@ extension CryptexFilesystemPatcher {
func patchMobileActivation(targetMount: String, cfwInput: URL) throws {
let target = URL.init(filePath: targetMount)
let mobileActivationdPath = target.appending(path: "/usr/libexec/mobileactivationd")
- let pythonPath = try resources.pythonExecutable()
- _ = try runProcess(pythonPath.path, [
- resources.cfwPy.path, "patch-mobileactivationd",
- mobileActivationdPath.path
- ])
+ // `resign: false` because the sign below replaces the signature, and
+ // re-attesting would refuse an unsigned input the Python accepted.
+ try CFWMobileactivationd.patch(fileAt: mobileActivationdPath, resign: false)
_ = try runProcess("/bin/chmod", ["0755", mobileActivationdPath.path])
try VPhoneSigner.sign(
diff --git a/sources/VPhoneCore/VPhoneFirmwareMatrix.swift b/sources/VPhoneCore/VPhoneFirmwareMatrix.swift
new file mode 100644
index 00000000..0dd6ca92
--- /dev/null
+++ b/sources/VPhoneCore/VPhoneFirmwareMatrix.swift
@@ -0,0 +1,477 @@
+import Foundation
+
+// MARK: - VPhoneFirmwareSupport
+
+/// How much confidence this project has in one downloadable iPhone firmware.
+///
+/// `supported` means the README's "Tested Environments" table records a boot on
+/// that exact version/build; `notTested` means Apple still serves it but nobody
+/// wrote a row for it. `unsupported` is never a table verdict — it is the
+/// prefix the selector puts on "nothing matched", and it exists here only
+/// because it shares the colour table with the other two.
+public enum VPhoneFirmwareSupport: String, Sendable, CaseIterable {
+ case supported = "Supported"
+ case notTested = "Not Tested"
+ case unsupported = "Unsupported"
+
+ /// SGR introducer for this verdict. Green/amber/red, matching the palette
+ /// the rest of the tool uses for status.
+ var ansiColor: String {
+ switch self {
+ case .supported: "\u{1B}[32m"
+ case .notTested: "\u{1B}[33m"
+ case .unsupported: "\u{1B}[31m"
+ }
+ }
+}
+
+// MARK: - VPhoneStatusStyle
+
+/// Whether ANSI colour may be written to one particular stream.
+///
+/// Three checks that have to stay together, and the order matters:
+///
+/// 1. `NO_COLOR` set to a non-empty value wins over everything.
+/// 2. Otherwise colour follows `isatty` **of this stream**, not of the process.
+/// 3. `CLICOLOR_FORCE=1` turns colour on even when the stream is a pipe.
+///
+/// The per-stream part is not a detail: the firmware listing styles stdout, the
+/// selector's failure paths style stderr, and a run that pipes one and not the
+/// other has to get a different answer for each. Getting this wrong means
+/// escape codes land in a pipe, or colour disappears in a terminal.
+public struct VPhoneStatusStyle: Sendable, Equatable {
+ public let isColored: Bool
+
+ public init(isColored: Bool) {
+ self.isColored = isColored
+ }
+
+ /// The policy above, resolved for one file descriptor.
+ public static func forStream(
+ _ fileDescriptor: Int32,
+ environment: [String: String] = ProcessInfo.processInfo.environment
+ ) -> VPhoneStatusStyle {
+ if let noColor = environment["NO_COLOR"], !noColor.isEmpty {
+ return VPhoneStatusStyle(isColored: false)
+ }
+ if isatty(fileDescriptor) != 0 {
+ return VPhoneStatusStyle(isColored: true)
+ }
+ return VPhoneStatusStyle(isColored: environment["CLICOLOR_FORCE"] == "1")
+ }
+
+ /// `status`, left-justified to `width` and only then wrapped in colour.
+ ///
+ /// The padding goes *inside* the escape sequence. That is deliberate: it is
+ /// where the shell's Python put it, and it keeps the plain and coloured
+ /// renderings the same width on screen, so the STATUS column lines up in
+ /// both. Moving the padding outside would change every byte of the output.
+ public func render(_ status: VPhoneFirmwareSupport, width: Int = 0) -> String {
+ let text = VPhoneFirmwareMatrix.leftJustified(status.rawValue, width)
+ guard isColored else { return text }
+ return "\(status.ansiColor)\(text)\u{1B}[0m"
+ }
+}
+
+// MARK: - VPhoneFirmwareRelease
+
+/// One downloadable restore image, as named by its own URL.
+public struct VPhoneFirmwareRelease: Sendable, Hashable {
+ public let version: String
+ public let build: String
+ public let url: String
+
+ public init(version: String, build: String, url: String) {
+ self.version = version
+ self.build = build
+ self.url = url
+ }
+}
+
+// MARK: - VPhoneFirmwareBuildID
+
+/// The (version, build) pair the README table and the URL list are joined on.
+public struct VPhoneFirmwareBuildID: Sendable, Hashable {
+ public let version: String
+ public let build: String
+
+ public init(version: String, build: String) {
+ self.version = version
+ self.build = build
+ }
+}
+
+// MARK: - VPhoneFirmwareListing
+
+/// Result of the `--list` path.
+public enum VPhoneFirmwareListing: Sendable, Equatable {
+ /// The rendered matrix. Goes to stdout; exit 0.
+ case matrix(String)
+ /// Nothing downloadable for the device. Goes to stderr; exit 1.
+ case nothingDownloadable(String)
+}
+
+// MARK: - VPhoneFirmwareSelection
+
+/// Result of resolving a version/build selector against the download list.
+public enum VPhoneFirmwareSelection: Sendable, Equatable {
+ /// One firmware and its verdict. Goes to stdout as `resolvedLine`; exit 0.
+ case selected(release: VPhoneFirmwareRelease, support: VPhoneFirmwareSupport)
+ /// A bare version that maps to several builds. Goes to stderr; exit 2 —
+ /// `fw_prepare.sh` forwards that 2 so a caller can tell "ambiguous" from
+ /// "no such firmware".
+ case ambiguous(String)
+ /// Nothing matched. Goes to stderr; exit 1.
+ case unmatched(String)
+
+ /// `version\tbuild\turl\tstatus`, which `fw_prepare.sh` reads back with
+ /// `IFS=$'\t' read -r`.
+ ///
+ /// Plain even when the rest of the run is coloured. The shell echoes field
+ /// 4 through its own `style_status`, so an escape sequence here would be
+ /// wrapped in a second one.
+ public var resolvedLine: String? {
+ guard case let .selected(release, support) = self else { return nil }
+ return "\(release.version)\t\(release.build)\t\(release.url)\t\(support.rawValue)\n"
+ }
+}
+
+// MARK: - VPhoneFirmwareMatrix
+
+/// The firmware support matrix: the README's "Tested Environments" table joined
+/// against the restore images Apple still serves.
+///
+/// This replaces the two Python heredocs that used to live inside
+/// `scripts/fw_prepare.sh` (`list_firmwares` and `resolve_selector_from_downloads`).
+/// They were 166 lines that duplicated the same three parsers — the README
+/// section scan, the URL scan, and the version sort — once each, so this is one
+/// parser with two renderers on top of it.
+public enum VPhoneFirmwareMatrix {
+ // MARK: Parsing
+
+ /// Every `(version, build)` the README's "Tested Environments" section
+ /// records for `device`.
+ ///
+ /// The section runs from the `## Tested Environments` heading to the next
+ /// `## ` heading. Inside it, any backticked `17,3_26.1_23B85` cell whose
+ /// device part equals `device` minus its `iPhone` prefix counts as tested;
+ /// the cloudOS column uses `26.1-23B85`, which cannot match. A missing
+ /// README is not an error — it just means nothing is known to be tested.
+ public static func testedBuilds(readme: String?, device: String) -> Set<VPhoneFirmwareBuildID> {
+ guard let readme else { return [] }
+ let deviceSuffix = device.hasPrefix("iPhone")
+ ? String(device.dropFirst("iPhone".count))
+ : device
+ guard let cell = try? NSRegularExpression(
+ pattern: "`(\\d+,\\d+)_([^_`]+)_([A-Za-z0-9]+)`"
+ ) else { return [] }
+
+ var tested: Set<VPhoneFirmwareBuildID> = []
+ var inSection = false
+ for line in normalizedLines(of: readme) {
+ if line.hasPrefix("## Tested Environments") {
+ inSection = true
+ continue
+ }
+ if inSection, line.hasPrefix("## ") { break }
+ guard inSection else { continue }
+
+ for match in cell.matches(in: line, range: NSRange(line.startIndex..., in: line)) {
+ guard let device = group(1, of: match, in: line),
+ let version = group(2, of: match, in: line),
+ let build = group(3, of: match, in: line),
+ device == deviceSuffix
+ else { continue }
+ tested.insert(VPhoneFirmwareBuildID(version: version, build: build))
+ }
+ }
+ return tested
+ }
+
+ /// Every restore image for `device` named by the `ipsw download … --urls`
+ /// output, in the order the lines arrive and with duplicates dropped.
+ ///
+ /// A line counts when it *ends* with `/<device>_<version>_<build>_Restore.ipsw`,
+ /// so the surrounding CDN path — which differs per release and is sometimes
+ /// a bare UUID — is ignored.
+ public static func releases(downloadURLs: String, device: String) -> [VPhoneFirmwareRelease] {
+ let pattern = "/(" + NSRegularExpression.escapedPattern(for: device)
+ + "_([^_]+)_([A-Za-z0-9]+)_Restore\\.ipsw)$"
+ guard let name = try? NSRegularExpression(pattern: pattern) else { return [] }
+
+ var seen: Set<VPhoneFirmwareRelease> = []
+ var found: [VPhoneFirmwareRelease] = []
+ for rawLine in normalizedLines(of: downloadURLs) {
+ let line = rawLine.trimmingCharacters(in: .whitespacesAndNewlines)
+ guard let match = name.firstMatch(in: line, range: NSRange(line.startIndex..., in: line)),
+ let version = group(2, of: match, in: line),
+ let build = group(3, of: match, in: line)
+ else { continue }
+ let release = VPhoneFirmwareRelease(version: version, build: build, url: line)
+ if seen.insert(release).inserted { found.append(release) }
+ }
+ return found
+ }
+
+ /// The verdict for one release, given what the README records.
+ public static func support(
+ of release: VPhoneFirmwareRelease,
+ tested: Set<VPhoneFirmwareBuildID>
+ ) -> VPhoneFirmwareSupport {
+ tested.contains(VPhoneFirmwareBuildID(version: release.version, build: release.build))
+ ? .supported
+ : .notTested
+ }
+
+ // MARK: Rendering — the listing
+
+ /// The full `--list` report, rendered for a stream with `style`'s colour policy.
+ public static func listing(
+ device: String,
+ readme: String?,
+ downloadURLs: String,
+ style: VPhoneStatusStyle
+ ) -> VPhoneFirmwareListing {
+ let releases = releases(downloadURLs: downloadURLs, device: device)
+ guard !releases.isEmpty else {
+ return .nothingDownloadable("No downloadable IPSWs found for \(device)\n")
+ }
+ let tested = testedBuilds(readme: readme, device: device)
+ let rows = releases.sorted { isNewer($0, than: $1) }
+
+ var out = "Available downloadable IPSWs for \(device):\n"
+ out += "\n"
+ out += "Status: \(style.render(.supported, width: statusWidth))"
+ + " \(style.render(.notTested, width: statusWidth))"
+ + " \(style.render(.unsupported, width: statusWidth))\n"
+ out += "\n"
+ out += "\(leftJustified("VERSION", versionWidth)) \(leftJustified("BUILD", buildWidth)) STATUS\n"
+ for row in rows {
+ let status = support(of: row, tested: tested)
+ out += "\(leftJustified(row.version, versionWidth))"
+ + " \(leftJustified(row.build, buildWidth))"
+ + " \(style.render(status, width: statusWidth))\n"
+ }
+ return .matrix(out)
+ }
+
+ // MARK: Rendering — the selector
+
+ /// Resolve a version and/or build selector against the download list.
+ ///
+ /// Empty strings mean "unconstrained", which is how the shell passes an
+ /// unset `IPHONE_VERSION`/`IPHONE_BUILD`. A bare version that matches more
+ /// than one build is reported as ambiguous rather than guessed at; anything
+ /// else resolves to the highest build that matched.
+ public static func selection(
+ device: String,
+ version: String,
+ build: String,
+ readme: String?,
+ downloadURLs: String,
+ style: VPhoneStatusStyle
+ ) -> VPhoneFirmwareSelection {
+ let matches = releases(downloadURLs: downloadURLs, device: device).filter {
+ (version.isEmpty || $0.version == version) && (build.isEmpty || $0.build == build)
+ }
+ guard !matches.isEmpty else {
+ let prefix = style.render(.unsupported)
+ let selector = if !version.isEmpty, !build.isEmpty {
+ "device=\(device) version=\(version) build=\(build)"
+ } else if !build.isEmpty {
+ "device=\(device) build=\(build)"
+ } else {
+ "device=\(device) version=\(version)"
+ }
+ return .unmatched("\(prefix): no downloadable IPSW matched \(selector)\n")
+ }
+
+ let tested = testedBuilds(readme: readme, device: device)
+ let byBuild = matches.sorted { hasHigherBuild($0, than: $1) }
+
+ if !version.isEmpty, build.isEmpty, Set(matches.map(\.build)).count > 1 {
+ var out = "Version \(version) is ambiguous for \(device); specify one of these builds:\n"
+ out += "\(leftJustified("BUILD", buildWidth)) STATUS\n"
+ for match in byBuild {
+ out += "\(leftJustified(match.build, buildWidth)) \(style.render(support(of: match, tested: tested)))\n"
+ }
+ return .ambiguous(out)
+ }
+
+ let selected = byBuild[0]
+ return .selected(release: selected, support: support(of: selected, tested: tested))
+ }
+
+ // MARK: Ordering
+
+ /// One dot-separated component of a version, compared the way the shell's
+ /// Python compared it: numerically where it parses as a number, textually
+ /// otherwise.
+ ///
+ /// The Python built a tuple and let Python compare it, which *raises* on a
+ /// number-against-text comparison (`26.1` vs `26.beta`). Nothing Apple
+ /// serves produces that, and raising is not a behaviour worth porting, so
+ /// numbers sort before text here.
+ enum VersionPart: Comparable {
+ case number(Int)
+ case text(String)
+
+ static func < (lhs: VersionPart, rhs: VersionPart) -> Bool {
+ switch (lhs, rhs) {
+ case let (.number(l), .number(r)): l < r
+ case let (.text(l), .text(r)): codePointsAscending(l, r)
+ case (.number, .text): true
+ case (.text, .number): false
+ }
+ }
+ }
+
+ /// `"26.4.1"` → `[26, 4, 1]`. Shorter sorts before longer on a common
+ /// prefix, so `26.4` < `26.4.1`.
+ static func versionKey(_ version: String) -> [VersionPart] {
+ version.components(separatedBy: ".").map { part in
+ if let number = Int(part) { .number(number) } else { .text(part) }
+ }
+ }
+
+ /// Newest first: version descending, then build descending.
+ ///
+ /// URL breaks the remaining ties. The Python had nothing there — it sorted
+ /// a `set`, so two rows sharing a version *and* a build came out in hash
+ /// order, which is to say a different order per run. That is not a
+ /// behaviour to reproduce, so the order here is total and reproducible.
+ static func isNewer(_ lhs: VPhoneFirmwareRelease, than rhs: VPhoneFirmwareRelease) -> Bool {
+ let (l, r) = (versionKey(lhs.version), versionKey(rhs.version))
+ for (lp, rp) in zip(l, r) where lp != rp { return rp < lp }
+ if l.count != r.count { return r.count < l.count }
+ return hasHigherBuild(lhs, than: rhs)
+ }
+
+ /// Build descending, URL descending as the tie-break.
+ static func hasHigherBuild(_ lhs: VPhoneFirmwareRelease, than rhs: VPhoneFirmwareRelease) -> Bool {
+ if lhs.build != rhs.build { return codePointsAscending(rhs.build, lhs.build) }
+ return codePointsAscending(rhs.url, lhs.url)
+ }
+
+ // MARK: Text helpers
+
+ static let versionWidth = 12
+ static let buildWidth = 10
+ static let statusWidth = 11
+
+ /// `String.padding(toLength:)` truncates; this does not, which is what the
+ /// `f"{value:<12}"` it replaces did. Width is counted in code points, again
+ /// to match.
+ static func leftJustified(_ text: String, _ width: Int) -> String {
+ let count = text.unicodeScalars.count
+ guard count < width else { return text }
+ return text + String(repeating: " ", count: width - count)
+ }
+
+ /// Code-point order, not Swift's canonical `String` ordering, because the
+ /// comparison it stands in for was Python's.
+ static func codePointsAscending(_ lhs: String, _ rhs: String) -> Bool {
+ var left = lhs.unicodeScalars.makeIterator()
+ var right = rhs.unicodeScalars.makeIterator()
+ while true {
+ switch (left.next(), right.next()) {
+ case (nil, nil): return false
+ case (nil, .some): return true
+ case (.some, nil): return false
+ case let (.some(l), .some(r)):
+ if l.value != r.value { return l.value < r.value }
+ }
+ }
+ }
+
+ /// Text-mode line splitting: CRLF and CR collapse to LF, and a trailing
+ /// newline does not produce a final empty line.
+ static func normalizedLines(of text: String) -> [String] {
+ var normalized = text.replacingOccurrences(of: "\r\n", with: "\n")
+ normalized = normalized.replacingOccurrences(of: "\r", with: "\n")
+ if normalized.hasSuffix("\n") { normalized.removeLast() }
+ if normalized.isEmpty { return [] }
+ return normalized.components(separatedBy: "\n")
+ }
+
+ private static func group(_ index: Int, of match: NSTextCheckingResult, in text: String) -> String? {
+ guard let range = Range(match.range(at: index), in: text) else { return nil }
+ return String(text[range])
+ }
+}
+
+// MARK: - VPhoneFirmwareMatrixCommandLine
+
+/// The two entry points `scripts/fw_prepare.sh` calls, including which stream
+/// each half writes to and what it exits with.
+///
+/// Stream choice is load-bearing twice over. The listing styles **stdout**, so
+/// `--list | less` gets plain text; every selector failure styles **stderr**,
+/// so an error stays coloured even when the resolved URL is being captured in a
+/// `$( … )`. Both are resolved independently, per stream.
+public enum VPhoneFirmwareMatrixCommandLine {
+ /// Print the support matrix. 0 on success, 1 when the device has nothing
+ /// downloadable.
+ public static func list(
+ device: String,
+ readmePath: String,
+ downloadURLs: String,
+ environment: [String: String] = ProcessInfo.processInfo.environment,
+ stdout: FileHandle = .standardOutput,
+ stderr: FileHandle = .standardError
+ ) -> Int32 {
+ let readme = try? String(contentsOfFile: readmePath, encoding: .utf8)
+ switch VPhoneFirmwareMatrix.listing(
+ device: device,
+ readme: readme,
+ downloadURLs: downloadURLs,
+ style: .forStream(stdout.fileDescriptor, environment: environment)
+ ) {
+ case let .matrix(text):
+ write(text, to: stdout)
+ return 0
+ case let .nothingDownloadable(text):
+ write(text, to: stderr)
+ return 1
+ }
+ }
+
+ /// Resolve a selector to `version\tbuild\turl\tstatus` on stdout. 0 on a
+ /// hit, 2 when a bare version is ambiguous, 1 when nothing matched.
+ public static func resolve(
+ device: String,
+ version: String,
+ build: String,
+ readmePath: String,
+ downloadURLs: String,
+ environment: [String: String] = ProcessInfo.processInfo.environment,
+ stdout: FileHandle = .standardOutput,
+ stderr: FileHandle = .standardError
+ ) -> Int32 {
+ let readme = try? String(contentsOfFile: readmePath, encoding: .utf8)
+ let selection = VPhoneFirmwareMatrix.selection(
+ device: device,
+ version: version,
+ build: build,
+ readme: readme,
+ downloadURLs: downloadURLs,
+ style: .forStream(stderr.fileDescriptor, environment: environment)
+ )
+ switch selection {
+ case .selected:
+ write(selection.resolvedLine ?? "", to: stdout)
+ return 0
+ case let .ambiguous(text):
+ write(text, to: stderr)
+ return 2
+ case let .unmatched(text):
+ write(text, to: stderr)
+ return 1
+ }
+ }
+
+ private static func write(_ text: String, to handle: FileHandle) {
+ guard !text.isEmpty else { return }
+ handle.write(Data(text.utf8))
+ }
+}
diff --git a/sources/vphone-cli/VPhoneCreateOrchestrator.swift b/sources/vphone-cli/VPhoneCreateOrchestrator.swift
index fc00d09c..87fd7213 100644
--- a/sources/vphone-cli/VPhoneCreateOrchestrator.swift
+++ b/sources/vphone-cli/VPhoneCreateOrchestrator.swift
@@ -285,14 +285,14 @@ public struct VPhoneCreateOrchestrator {
var env = ProcessInfo.processInfo.environment
if let iphoneSource = options.iphoneSource { env["IPHONE_SOURCE"] = iphoneSource }
if let cloudosSource = options.cloudosSource { env["CLOUDOS_SOURCE"] = cloudosSource }
- env["VPHONE_PYTHON"] = try resources.pythonExecutable().path
+ // No VPHONE_PYTHON: fw_prepare.sh no longer runs any Python.
env["IPSW_DIR"] = resources.ipswCacheDir.path
env["VPHONE_SEAL_DIR"] = resources.sealVolumeCacheDir.path
if isLess { env["VARIANT"] = "less" }
if options.keepArtifacts { env["VPHONE_KEEP_ARTIFACTS"] = "1" }
trace(
- "spawn /bin/bash \(resources.fwPrepareScript.path) (env keys: VPHONE_PYTHON, IPSW_DIR, VPHONE_SEAL_DIR)",
+ "spawn /bin/bash \(resources.fwPrepareScript.path) (env keys: IPSW_DIR, VPHONE_SEAL_DIR)",
v
)
// Always streamed — silence during a multi-GB download reads as a hang.
diff --git a/sources/vphone-cli/VPhoneFWCLI.swift b/sources/vphone-cli/VPhoneFWCLI.swift
index 9f9c1294..66e51253 100644
--- a/sources/vphone-cli/VPhoneFWCLI.swift
+++ b/sources/vphone-cli/VPhoneFWCLI.swift
@@ -12,9 +12,69 @@ struct VPhoneFWCommand: ParsableCommand {
VPhoneFWPrepareCommand.self,
VPhoneFWPatchCommand.self,
VPhoneFWManifestCommand.self,
+ VPhoneFWListCommand.self,
+ VPhoneFWResolveCommand.self,
])
}
+// MARK: - firmware support matrix
+
+/// Replaces the two Python heredocs that used to live inside
+/// `scripts/fw_prepare.sh`. Both read the `DOWNLOADABLE_IPSW_URLS` the shell
+/// already sets, so only the language changed; the shell still runs `ipsw`.
+///
+/// Neither writes through `print`: `list` styles stdout and `resolve` styles
+/// stderr, and colour is only right if each descriptor is asked separately.
+struct VPhoneFWListCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "list",
+ abstract: "Print the downloadable-firmware support matrix for a device"
+ )
+
+ @Option(help: "Device identifier, e.g. iPhone17,3") var device: String
+ @Option(help: "README.md holding the 'Tested Environments' table") var readme: String
+
+ func run() throws {
+ let code = VPhoneFirmwareMatrixCommandLine.list(
+ device: device,
+ readmePath: readme,
+ downloadURLs: ProcessInfo.processInfo.environment["DOWNLOADABLE_IPSW_URLS"] ?? ""
+ )
+ if code != 0 { throw ExitCode(code) }
+ }
+}
+
+struct VPhoneFWResolveCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "resolve",
+ abstract: "Resolve a version/build selector to a downloadable IPSW URL",
+ discussion: """
+ Prints version<TAB>build<TAB>url<TAB>status on stdout, which fw_prepare.sh
+ reads back with `IFS=$'\\t' read -r`.
+
+ Exits 2 — not 1 — when a bare version matches more than one build, so a
+ caller can tell "pick a build" from "there is no such firmware". An empty
+ --version or --build means unconstrained.
+ """
+ )
+
+ @Option(help: "Device identifier, e.g. iPhone17,3") var device: String
+ @Option(help: "iOS version to match; empty matches any") var version: String = ""
+ @Option(help: "Build to match; empty matches any") var build: String = ""
+ @Option(help: "README.md holding the 'Tested Environments' table") var readme: String
+
+ func run() throws {
+ let code = VPhoneFirmwareMatrixCommandLine.resolve(
+ device: device,
+ version: version,
+ build: build,
+ readmePath: readme,
+ downloadURLs: ProcessInfo.processInfo.environment["DOWNLOADABLE_IPSW_URLS"] ?? ""
+ )
+ if code != 0 { throw ExitCode(code) }
+ }
+}
+
// MARK: - manifest
/// Replaces `scripts/fw_manifest.py`, called from `fw_prepare.sh` once both
@@ -117,16 +177,16 @@ struct VPhoneFWPrepareCommand: ParsableCommand {
if let iphoneBuild { env["IPHONE_BUILD"] = iphoneBuild }
if list { env["LIST_FIRMWARES"] = "1" }
- // Redirect the three things a read-only bundle can't provide (python,
- // IPSW cache, extracted apfs_sealvolume) to the writable user cache.
+ // Redirect the two things a read-only bundle can't provide (IPSW cache,
+ // extracted apfs_sealvolume) to the writable user cache. No Python:
+ // fw_prepare.sh's last heredocs moved into `fw list` / `fw resolve`.
try FileManager.default.createDirectory(at: resources.ipswCacheDir, withIntermediateDirectories: true)
try FileManager.default.createDirectory(at: resources.sealVolumeCacheDir, withIntermediateDirectories: true)
- env["VPHONE_PYTHON"] = try resources.pythonExecutable().path
env["IPSW_DIR"] = resources.ipswCacheDir.path
env["VPHONE_SEAL_DIR"] = resources.sealVolumeCacheDir.path
if v.tracesInternals {
- print("[trace] spawning: /bin/bash \(resources.fwPrepareScript.path) (env keys: VPHONE_PYTHON, IPSW_DIR, VPHONE_SEAL_DIR)")
+ print("[trace] spawning: /bin/bash \(resources.fwPrepareScript.path) (env keys: IPSW_DIR, VPHONE_SEAL_DIR)")
}
let code = try VPhoneProcessRunner.runStreaming(
URL(fileURLWithPath: "/bin/bash"),
diff --git a/tests/FirmwarePatcherTests/CFWCacheloaderTests.swift b/tests/FirmwarePatcherTests/CFWCacheloaderTests.swift
new file mode 100644
index 00000000..3e394b22
--- /dev/null
+++ b/tests/FirmwarePatcherTests/CFWCacheloaderTests.swift
@@ -0,0 +1,586 @@
+// CFWCacheloaderTests.swift — parity for the launchd_cache_loader unsecure-cache gate.
+//
+// The patch is one instruction in a boot-critical binary, and a wrong one is a
+// guest that will not start rather than a failing assertion, so the reference
+// these tests grade against is the Python that has already shipped: `cfw.py
+// patch-launchd-cache-loader`. The centre of the suite runs both
+// implementations over two clones of the *real* iOS 27.0 / 24A435 binary and
+// compares every byte.
+//
+// The binary is required. Point `VPHONE_MACHO_PRISTINE` at a directory of
+// unpatched Mach-Os, or leave the default `ipsws/ref_extract/macho_pristine` in
+// place. Without it these tests FAIL — the suite never opens with a bare
+// `return`, which Swift Testing reports as a pass, so a green run cannot mean
+// the fixture was absent. A machine that genuinely cannot carry it sets
+// `VPHONE_MACHO_FIXTURE_OPTIONAL=1`, which turns the failure into a skip.
+//
+// Nothing here writes to the pristine tree. Clones are made with `clonefile`
+// (instant and near-free on APFS) under the system temporary directory, or
+// under `VPHONE_CACHELOADER_SCRATCH` when the caller names one;
+// `VPHONE_CACHELOADER_KEEP=1` leaves them behind for inspection.
+
+@testable import FirmwarePatcher
+import Foundation
+import Testing
+
+// MARK: - Fixture discovery
+
+private enum CacheLoaderFixture {
+ static let repoRoot = URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+
+ /// The read-only reference binary.
+ static var pristine: URL? {
+ let directory = ProcessInfo.processInfo.environment["VPHONE_MACHO_PRISTINE"]
+ .map { URL(fileURLWithPath: $0) }
+ ?? repoRoot.appendingPathComponent("ipsws/ref_extract/macho_pristine")
+ let binary = directory.appendingPathComponent("launchd_cache_loader")
+ return FileManager.default.fileExists(atPath: binary.path) ? binary : nil
+ }
+
+ /// Opt-out for a machine that cannot carry the extracted IPSW.
+ static var isOptional: Bool {
+ ProcessInfo.processInfo.environment["VPHONE_MACHO_FIXTURE_OPTIONAL"] == "1"
+ }
+
+ /// The suite runs unless the binary is absent *and* the caller opted out.
+ static var runs: Bool { pristine != nil || !isOptional }
+
+ static let missing: Comment = """
+ the real 24A435 launchd_cache_loader is required — put it at \
+ ipsws/ref_extract/macho_pristine/, point VPHONE_MACHO_PRISTINE at that \
+ directory, or set VPHONE_MACHO_FIXTURE_OPTIONAL=1 to skip these tests \
+ instead of failing
+ """
+
+ /// Where clones go. Deliberately *not* inside `ipsws/ref_extract`: that tree
+ /// is the pristine reference every parity test compares against, and it came
+ /// out of a 12 GB IPSW nobody wants to re-extract.
+ static var scratchRoot: URL {
+ ProcessInfo.processInfo.environment["VPHONE_CACHELOADER_SCRATCH"]
+ .map { URL(fileURLWithPath: $0) }
+ ?? URL(fileURLWithPath: NSTemporaryDirectory())
+ .appendingPathComponent("vphone-cacheloader")
+ }
+
+ /// Leave clones on disk after the run, for hand inspection.
+ static var keepsArtifacts: Bool {
+ ProcessInfo.processInfo.environment["VPHONE_CACHELOADER_KEEP"] == "1"
+ }
+
+ /// The project venv, which is where the reference Python lives.
+ static var python: URL? {
+ let url = repoRoot.appendingPathComponent(".venv/bin/python3")
+ return FileManager.default.fileExists(atPath: url.path) ? url : nil
+ }
+
+ static var patchersDirectory: URL { repoRoot.appendingPathComponent("scripts/patchers") }
+ static var cfwPy: URL { patchersDirectory.appendingPathComponent("cfw.py") }
+
+ /// Clone the pristine binary into a file the caller may write to.
+ ///
+ /// `cp -c` asks for a `clonefile`, which costs no space and no time when the
+ /// scratch root shares the fixture's APFS volume. When it does not — a
+ /// caller who pointed `VPHONE_CACHELOADER_SCRATCH` at another disk — the
+ /// clone is refused, and the fallback is an ordinary copy rather than a
+ /// failed test.
+ static func clone(named name: String) throws -> URL {
+ let pristine = try #require(self.pristine, missing)
+ try FileManager.default.createDirectory(
+ at: scratchRoot,
+ withIntermediateDirectories: true
+ )
+ let destination = scratchRoot.appendingPathComponent(name)
+ try? FileManager.default.removeItem(at: destination)
+
+ for flags in [["-c"], []] {
+ let result = try Shell.run(
+ executable: URL(fileURLWithPath: "/bin/cp"),
+ arguments: flags + [pristine.path, destination.path]
+ )
+ if result.status == 0 { return destination }
+ }
+ Issue.record("could not clone \(pristine.path) to \(destination.path)")
+ throw CocoaError(.fileWriteUnknown)
+ }
+
+ /// Discard clones, and the scratch root with them once the last one is gone,
+ /// so a test run leaves the filesystem as it found it.
+ static func discard(_ clones: URL...) {
+ guard !keepsArtifacts else { return }
+ for clone in clones {
+ try? FileManager.default.removeItem(at: clone)
+ }
+ let remaining = (try? FileManager.default
+ .contentsOfDirectory(atPath: scratchRoot.path)) ?? []
+ if remaining.isEmpty {
+ try? FileManager.default.removeItem(at: scratchRoot)
+ }
+ }
+
+ /// Run the shipped Python patcher over `binary`.
+ @discardableResult
+ static func runPython(on binary: URL) throws -> Shell.Result {
+ let python = try #require(
+ self.python,
+ "the reference Python is required — run `make setup_venv`"
+ )
+ return try Shell.run(
+ executable: python,
+ arguments: [cfwPy.path, "patch-launchd-cache-loader", binary.path],
+ currentDirectory: repoRoot
+ )
+ }
+
+ /// Recompute `binary`'s slot hashes with the Python's own re-signer — the
+ /// independent reference for the half of this port `codesign -v` grades.
+ @discardableResult
+ static func runPythonReattest(on binary: URL, offsets: [Int]) throws -> Shell.Result {
+ let python = try #require(
+ self.python,
+ "the reference Python is required — run `make setup_venv`"
+ )
+ let offsetList = offsets.map(String.init).joined(separator: ",")
+ return try Shell.run(
+ executable: python,
+ arguments: [
+ "-c",
+ """
+ import sys
+ sys.path.insert(0, sys.argv[1])
+ import cfw_macho_codesign as codesign
+ codesign.reattest_modified_offsets(
+ sys.argv[2], [int(x) for x in sys.argv[3].split(",")], verbose=False
+ )
+ """,
+ patchersDirectory.path,
+ binary.path,
+ offsetList,
+ ],
+ currentDirectory: repoRoot
+ )
+ }
+
+ /// `codesign -v`, the second independent reference: it knows nothing about
+ /// either implementation and recomputes the page hashes itself.
+ static func codesignVerify(_ binary: URL) throws -> Shell.Result {
+ try Shell.run(
+ executable: URL(fileURLWithPath: "/usr/bin/codesign"),
+ arguments: ["-v", "--verbose=2", binary.path]
+ )
+ }
+
+ static func bytes(of url: URL) throws -> Data { try Data(contentsOf: url) }
+}
+
+// MARK: - Subprocess helper
+
+private enum Shell {
+ struct Result {
+ let status: Int32
+ let stdout: String
+ let stderr: String
+ var output: String { stdout + stderr }
+ }
+
+ @discardableResult
+ static func run(
+ executable: URL,
+ arguments: [String],
+ currentDirectory: URL? = nil
+ ) throws -> Result {
+ let process = Process()
+ process.executableURL = executable
+ process.arguments = arguments
+ if let currentDirectory { process.currentDirectoryURL = currentDirectory }
+ let out = Pipe()
+ let err = Pipe()
+ process.standardOutput = out
+ process.standardError = err
+ try process.run()
+ let outData = out.fileHandleForReading.readDataToEndOfFile()
+ let errData = err.fileHandleForReading.readDataToEndOfFile()
+ process.waitUntilExit()
+ return Result(
+ status: process.terminationStatus,
+ stdout: String(decoding: outData, as: UTF8.self),
+ stderr: String(decoding: errData, as: UTF8.self)
+ )
+ }
+}
+
+// MARK: - Byte comparison
+
+private enum ByteComparison {
+ /// Every offset at which two equal-length buffers differ.
+ static func differingOffsets(_ lhs: Data, _ rhs: Data) -> [Int] {
+ guard lhs.count == rhs.count else { return [] }
+ return (0 ..< lhs.count).filter { lhs[$0] != rhs[$0] }
+ }
+}
+
+// MARK: - Gate discovery
+
+@Suite(
+ "launchd_cache_loader gate discovery",
+ .enabled(if: CacheLoaderFixture.runs, CacheLoaderFixture.missing)
+)
+struct CFWCacheLoaderGateTests {
+ @Test("the anchor is the whole launchd_unsecure_cache= literal, found in __cstring")
+ func anchorIsTheBootArgLiteral() throws {
+ let data = try CacheLoaderFixture.bytes(
+ of: try #require(CacheLoaderFixture.pristine, CacheLoaderFixture.missing)
+ )
+ let located = try CFWCacheLoaderPatcher.locateGate(in: data)
+ let anchor = located.anchor
+
+ #expect(anchor.token == "unsecure_cache")
+ #expect(anchor.text == "launchd_unsecure_cache=")
+ #expect(anchor.sectionName == "__TEXT,__cstring")
+ // The token sits inside the literal, so the address code forms is the
+ // literal's first byte — earlier than where the token matched.
+ #expect(anchor.stringVMA < anchor.matchVMA)
+ #expect(anchor.matchVMA - anchor.stringVMA == UInt64("launchd_".utf8.count))
+ // …and that first byte really is where the literal starts on disk.
+ let literal = data[anchor.stringFileOffset ..< anchor.stringFileOffset + anchor.text.utf8.count]
+ #expect(String(decoding: literal, as: UTF8.self) == anchor.text)
+ #expect(data[anchor.stringFileOffset - 1] == 0)
+ }
+
+ @Test("the xref is an ADRP+ADD that really computes the literal's address")
+ func referenceComputesTheString() throws {
+ let data = try CacheLoaderFixture.bytes(
+ of: try #require(CacheLoaderFixture.pristine, CacheLoaderFixture.missing)
+ )
+ let anchor = try CFWCacheLoaderPatcher.locateGate(in: data).anchor
+ let sections = MachOParser.parseSections(from: data)
+ let text = try #require(sections["__TEXT,__text"])
+ let disassembler = ARM64Disassembler()
+
+ // Recomputed here from the two instructions, independently of how the
+ // patcher found them: page(ADRP) + imm(ADD) has to be the literal.
+ let adrp = try #require(disassembler.disassembleOne(
+ in: data, at: anchor.referenceFileOffset, address: anchor.referenceVMA
+ ))
+ let add = try #require(disassembler.disassembleOne(
+ in: data, at: anchor.referenceFileOffset + 4, address: anchor.referenceVMA + 4
+ ))
+ #expect(adrp.mnemonic == "adrp")
+ #expect(add.mnemonic == "add")
+
+ let page = try #require(adrp.aarch64?.operands.last?.imm)
+ let pageOffset = try #require(add.aarch64?.operands.last?.imm)
+ #expect(UInt64(page + pageOffset) == anchor.stringVMA)
+
+ // And the xref is inside __TEXT,__text, which is the only place a gate
+ // could be.
+ #expect(anchor.referenceVMA >= text.address)
+ #expect(anchor.referenceVMA < text.address + text.size)
+ }
+
+ @Test("the gate is a forward cbz on the boot-arg lookup's result")
+ func gateShape() throws {
+ let data = try CacheLoaderFixture.bytes(
+ of: try #require(CacheLoaderFixture.pristine, CacheLoaderFixture.missing)
+ )
+ let located = try CFWCacheLoaderPatcher.locateGate(in: data)
+ let gate = located.gate
+
+ #expect(gate.mnemonic == "cbz")
+ #expect(!gate.wasAlreadyNOP)
+ #expect(gate.operandString.hasPrefix("x0,"))
+ // It is the instruction immediately after the call it grades…
+ let callVMA = try #require(gate.callVMA)
+ #expect(gate.vma == callVMA + 4)
+ #expect(callVMA > located.anchor.referenceVMA)
+ // …and it jumps forward, over the unsecure-cache path it guards.
+ let target = try #require(gate.targetVMA)
+ #expect(target > gate.vma)
+ }
+
+ @Test("the fixture's code directory is the SHA-256, short-tail shape this port assumes")
+ func fixtureSignatureShape() throws {
+ let data = try CacheLoaderFixture.bytes(
+ of: try #require(CacheLoaderFixture.pristine, CacheLoaderFixture.missing)
+ )
+ let directories = try #require(CFWMachOCodeSignature.codeDirectories(in: data))
+ let directory = try #require(directories.first)
+
+ #expect(directories.count == 1)
+ #expect(directory.hashType == CFWMachOCodeSignature.hashTypeSHA256)
+ #expect(directory.pageSize == 4096)
+ // codeLimit is NOT page aligned here, so the last slot is short — the
+ // case that regressed independent Mach-O re-signing once already.
+ #expect(directory.codeLimit % directory.pageSize != 0)
+ let tail = try #require(directory.slotRange(directory.codeSlotCount - 1))
+ #expect(tail.count < directory.pageSize)
+
+ // The gate lands in slot 0, well inside the covered region.
+ let gate = try CFWCacheLoaderPatcher.locateGate(in: data).gate
+ let bounds = try #require(CFWMachOCodeSignature.pageBounds(
+ fileOffset: gate.fileOffset,
+ pageSize: directory.pageSize,
+ codeLimit: directory.codeLimit
+ ))
+ #expect(bounds.index == 0)
+ }
+}
+
+// MARK: - Parity against the Python
+
+@Suite(
+ "launchd_cache_loader parity",
+ .enabled(if: CacheLoaderFixture.runs, CacheLoaderFixture.missing),
+ .serialized
+)
+struct CFWCacheLoaderParityTests {
+ @Test("Swift and Python produce byte-identical binaries")
+ func byteForByteParity() throws {
+ let swiftClone = try CacheLoaderFixture.clone(named: "swift")
+ let pythonClone = try CacheLoaderFixture.clone(named: "python")
+ defer { CacheLoaderFixture.discard(swiftClone, pythonClone) }
+
+ let report = try CFWCacheLoaderPatcher.patch(fileAt: swiftClone, log: nil)
+ #expect(report.outcome == .patched)
+ #expect(report.sitesWritten == 1)
+ // Off by default, because every shipped caller re-signs afterwards.
+ #expect(report.reattestedSlots.isEmpty)
+
+ let python = try CacheLoaderFixture.runPython(on: pythonClone)
+ #expect(python.status == 0, "python failed: \(python.output)")
+ #expect(python.stdout.contains("[+] NOPped at"))
+
+ let swiftBytes = try CacheLoaderFixture.bytes(of: swiftClone)
+ let pythonBytes = try CacheLoaderFixture.bytes(of: pythonClone)
+ #expect(swiftBytes == pythonBytes, "Swift and Python disagree")
+ }
+
+ @Test("exactly one instruction changes, and it is the gate")
+ func onlyTheGateChanges() throws {
+ let clone = try CacheLoaderFixture.clone(named: "single-site")
+ defer { CacheLoaderFixture.discard(clone) }
+
+ let pristine = try CacheLoaderFixture.bytes(
+ of: try #require(CacheLoaderFixture.pristine, CacheLoaderFixture.missing)
+ )
+ let report = try CFWCacheLoaderPatcher.patch(fileAt: clone, log: nil)
+ let patched = try CacheLoaderFixture.bytes(of: clone)
+
+ let differing = ByteComparison.differingOffsets(pristine, patched)
+ #expect(differing == Array(report.gate.fileOffset ..< report.gate.fileOffset + 4))
+ #expect(patched[report.gate.fileOffset ..< report.gate.fileOffset + 4] == ARM64.nop)
+ }
+
+ @Test("the record names the byte that changed, its address and the anchor")
+ func recordDescribesTheSite() throws {
+ let clone = try CacheLoaderFixture.clone(named: "record")
+ defer { CacheLoaderFixture.discard(clone) }
+
+ let report = try CFWCacheLoaderPatcher.patch(fileAt: clone, log: nil)
+ let record = try #require(report.record)
+
+ #expect(record.patchID == "launchd_cache_loader.unsecure_cache_gate")
+ #expect(record.component == "launchd_cache_loader")
+ #expect(record.fileOffset == report.gate.fileOffset)
+ #expect(record.virtualAddress == report.gate.vma)
+ #expect(record.patchedBytes == ARM64.nop)
+ #expect(record.originalBytes != ARM64.nop)
+ #expect(record.afterDisasm == "nop")
+ #expect(record.beforeDisasm.hasPrefix("cbz"))
+ // Worded exactly as the Python words it, so a captured reference sorts
+ // against this port.
+ #expect(record.patchDescription
+ == "NOP the cache-validation branch gated on 'unsecure_cache'")
+
+ let onDisk = try CacheLoaderFixture.bytes(of: clone)
+ #expect(onDisk[record.fileOffset ..< record.fileOffset + 4] == ARM64.nop)
+ }
+
+ /// Every other test here passes `log: nil`, and production does not. The
+ /// before/after window starts two instructions ahead of the gate, and it
+ /// once converted that negative delta with `UInt64(Int)` — a trap on every
+ /// real patch that no `log: nil` test could see.
+ @Test("patching with logging on succeeds and prints the marked window")
+ func loggingPathDoesNotTrap() throws {
+ let clone = try CacheLoaderFixture.clone(named: "logged")
+ defer { CacheLoaderFixture.discard(clone) }
+
+ final class Lines: @unchecked Sendable { var all: [String] = [] }
+ let lines = Lines()
+ let report = try CFWCacheLoaderPatcher.patch(fileAt: clone, log: { lines.all.append($0) })
+
+ let text = lines.all.joined(separator: "\n")
+ #expect(text.contains("Before:"))
+ #expect(text.contains(">>>"))
+ let onDisk = try CacheLoaderFixture.bytes(of: clone)
+ #expect(onDisk[report.gate.fileOffset ..< report.gate.fileOffset + 4] == ARM64.nop)
+ }
+}
+
+// MARK: - Re-runs and dry runs
+
+@Suite(
+ "launchd_cache_loader re-runs",
+ .enabled(if: CacheLoaderFixture.runs, CacheLoaderFixture.missing),
+ .serialized
+)
+struct CFWCacheLoaderRerunTests {
+ @Test("a second run is a byte-for-byte no-op")
+ func secondRunChangesNothing() throws {
+ let clone = try CacheLoaderFixture.clone(named: "twice")
+ defer { CacheLoaderFixture.discard(clone) }
+
+ let first = try CFWCacheLoaderPatcher.patch(fileAt: clone, log: nil)
+ let afterFirst = try CacheLoaderFixture.bytes(of: clone)
+
+ let second = try CFWCacheLoaderPatcher.patch(fileAt: clone, log: nil)
+ let afterSecond = try CacheLoaderFixture.bytes(of: clone)
+
+ #expect(second.outcome == .alreadyPatched)
+ #expect(second.sitesWritten == 0)
+ #expect(second.record == nil)
+ #expect(afterFirst == afterSecond)
+ // The second run has to recognise the SAME site, not merely find some
+ // other instruction it is willing to leave alone.
+ #expect(second.gate.fileOffset == first.gate.fileOffset)
+ #expect(second.gate.vma == first.gate.vma)
+ #expect(second.gate.wasAlreadyNOP)
+ #expect(second.anchor == first.anchor)
+
+ // A third run, for the same reason the second exists.
+ let third = try CFWCacheLoaderPatcher.patch(fileAt: clone, log: nil)
+ #expect(third.outcome == .alreadyPatched)
+ #expect(try CacheLoaderFixture.bytes(of: clone) == afterFirst)
+ }
+
+ @Test("the Python double-applies where this port stops — the reason they diverge")
+ func pythonIsNotIdempotent() throws {
+ let pythonClone = try CacheLoaderFixture.clone(named: "python-twice")
+ let swiftClone = try CacheLoaderFixture.clone(named: "swift-twice")
+ defer { CacheLoaderFixture.discard(pythonClone, swiftClone) }
+
+ try CacheLoaderFixture.runPython(on: pythonClone)
+ let afterFirst = try CacheLoaderFixture.bytes(of: pythonClone)
+ let secondRun = try CacheLoaderFixture.runPython(on: pythonClone)
+ let afterSecond = try CacheLoaderFixture.bytes(of: pythonClone)
+
+ // Not an assertion about what the Python *should* do — a pin on what it
+ // does, so this divergence is deliberate and stays visible. The Python
+ // walks past its own NOP and takes the next conditional branch.
+ #expect(secondRun.status == 0)
+ #expect(afterFirst != afterSecond, "the Python became idempotent; revisit this port")
+ let extra = ByteComparison.differingOffsets(afterFirst, afterSecond)
+ #expect(extra.count == 4)
+
+ try CFWCacheLoaderPatcher.patch(fileAt: swiftClone, log: nil)
+ try CFWCacheLoaderPatcher.patch(fileAt: swiftClone, log: nil)
+ let swiftTwice = try CacheLoaderFixture.bytes(of: swiftClone)
+ #expect(swiftTwice == afterFirst, "one Swift run twice must equal one Python run once")
+ #expect(swiftTwice != afterSecond)
+ }
+
+ @Test("a dry run locates the site and writes nothing")
+ func dryRunChangesNothing() throws {
+ let clone = try CacheLoaderFixture.clone(named: "dry-run")
+ defer { CacheLoaderFixture.discard(clone) }
+
+ let pristine = try CacheLoaderFixture.bytes(
+ of: try #require(CacheLoaderFixture.pristine, CacheLoaderFixture.missing)
+ )
+ let report = try CFWCacheLoaderPatcher.patch(fileAt: clone, dryRun: true, log: nil)
+
+ #expect(report.outcome == .wouldPatch)
+ #expect(report.sitesWritten == 0)
+ #expect(report.gate.mnemonic == "cbz")
+ #expect(try CacheLoaderFixture.bytes(of: clone) == pristine)
+ }
+}
+
+// MARK: - Code signature
+
+@Suite(
+ "launchd_cache_loader re-signing",
+ .enabled(if: CacheLoaderFixture.runs, CacheLoaderFixture.missing),
+ .serialized
+)
+struct CFWCacheLoaderSignatureTests {
+ @Test("the default output fails codesign, exactly as the Python's does")
+ func defaultOutputIsUnattested() throws {
+ let swiftClone = try CacheLoaderFixture.clone(named: "unattested-swift")
+ let pythonClone = try CacheLoaderFixture.clone(named: "unattested-python")
+ defer { CacheLoaderFixture.discard(swiftClone, pythonClone) }
+
+ try CFWCacheLoaderPatcher.patch(fileAt: swiftClone, log: nil)
+ try CacheLoaderFixture.runPython(on: pythonClone)
+
+ // Both leave a stale slot hash, because both rely on the caller
+ // re-signing the binary wholesale afterwards (`ldid_sign` in
+ // `cfw_install*.sh`, `VPhoneSigner.sign` in the Swift call site). This
+ // test exists so that shared assumption is written down where it fails
+ // loudly if a caller ever stops honouring it.
+ #expect(try CacheLoaderFixture.codesignVerify(swiftClone).status != 0)
+ #expect(try CacheLoaderFixture.codesignVerify(pythonClone).status != 0)
+ }
+
+ @Test("re-attested output passes codesign and matches the Python's slot hashes")
+ func reattestedOutputVerifies() throws {
+ let swiftClone = try CacheLoaderFixture.clone(named: "attested-swift")
+ let pythonClone = try CacheLoaderFixture.clone(named: "attested-python")
+ defer { CacheLoaderFixture.discard(swiftClone, pythonClone) }
+
+ let report = try CFWCacheLoaderPatcher.patch(
+ fileAt: swiftClone,
+ reattestsCodeSignature: true,
+ log: nil
+ )
+ #expect(report.outcome == .patched)
+ let slot = try #require(report.reattestedSlots.first)
+ #expect(report.reattestedSlots.count == 1)
+ #expect(slot.pageIndex == 0)
+ #expect(slot.before != slot.after)
+
+ // codesign knows nothing about either implementation — it recomputes the
+ // page hashes from the file itself.
+ let verified = try CacheLoaderFixture.codesignVerify(swiftClone)
+ #expect(verified.status == 0, "codesign -v failed: \(verified.output)")
+
+ // …and the Python, patching and re-signing with its own code, lands on
+ // the same bytes.
+ try CacheLoaderFixture.runPython(on: pythonClone)
+ let reattest = try CacheLoaderFixture.runPythonReattest(
+ on: pythonClone,
+ offsets: [report.gate.fileOffset]
+ )
+ #expect(reattest.status == 0, "python re-attest failed: \(reattest.output)")
+ #expect(try CacheLoaderFixture.bytes(of: swiftClone)
+ == (try CacheLoaderFixture.bytes(of: pythonClone)))
+ }
+
+ @Test("re-attesting an already-patched binary repairs it without moving an instruction")
+ func reattestRepairsPythonOutput() throws {
+ let clone = try CacheLoaderFixture.clone(named: "repair")
+ defer { CacheLoaderFixture.discard(clone) }
+
+ // The Python's output: patched, and carrying a stale slot hash.
+ try CacheLoaderFixture.runPython(on: clone)
+ let beforeRepair = try CacheLoaderFixture.bytes(of: clone)
+
+ let report = try CFWCacheLoaderPatcher.patch(
+ fileAt: clone,
+ reattestsCodeSignature: true,
+ log: nil
+ )
+ #expect(report.outcome == .alreadyPatched)
+ #expect(report.sitesWritten == 0)
+ #expect(report.reattestedSlots.count == 1)
+ #expect(try CacheLoaderFixture.codesignVerify(clone).status == 0)
+
+ // Only the slot hash moved; no instruction was rewritten.
+ let afterRepair = try CacheLoaderFixture.bytes(of: clone)
+ let differing = ByteComparison.differingOffsets(beforeRepair, afterRepair)
+ let slot = try #require(report.reattestedSlots.first)
+ #expect(differing == Array(slot.hashFileOffset ..< slot.hashFileOffset + slot.after.count))
+ }
+}
diff --git a/tests/FirmwarePatcherTests/CFWDiskimagesiodTests.swift b/tests/FirmwarePatcherTests/CFWDiskimagesiodTests.swift
new file mode 100644
index 00000000..9221b227
--- /dev/null
+++ b/tests/FirmwarePatcherTests/CFWDiskimagesiodTests.swift
@@ -0,0 +1,656 @@
+// CFWDiskimagesiodTests.swift — parity for the diskimagesiod DDI mount gate.
+//
+// The patch is eight bytes over an ObjC method prologue, and a wrong eight
+// bytes is a daemon that crashes on first call rather than a failing
+// assertion — so the reference these tests grade against is not this port's
+// own opinion. It is, in order of authority:
+//
+// 1. `cfw.py patch-diskimagesiod`, the Python that has already shipped, run
+// under the project venv over a clone of the same pristine binary;
+// 2. `cfw_macho_codesign.reattest_modified_offsets`, the Python's own
+// independent re-signing implementation, for the `reattest: true` path;
+// 3. `/usr/bin/codesign -v`, which is neither implementation.
+//
+// The fixture is the real `usr/libexec/diskimagesiod` from iOS 27.0 / 24A435 /
+// iPhone17,3: 2.8 MB, arm64e, ad-hoc signed, CodeDirectory v=20400, 710+7
+// hashes, and a codeLimit of 0x2C5840 that is NOT page-aligned — the short tail
+// slot that the last independent-Mach-O re-signing regression came from.
+//
+// Point `VPHONE_MACHO_PRISTINE` at a directory of those binaries, or leave the
+// default `ipsws/ref_extract/macho_pristine` in place. Without it these tests
+// FAIL — the suite never opens with a bare `return`, which Swift Testing
+// reports as a pass, so a green run cannot mean the fixture was absent. A
+// machine that genuinely cannot carry it sets `VPHONE_MACHO_FIXTURE_OPTIONAL=1`,
+// which turns the failure into a visible skip.
+//
+// Nothing here writes into the pristine tree. Clones are made with `cp -c`
+// (`clonefile`: instant, and free on APFS) under the system temporary
+// directory, or under `VPHONE_MACHO_SCRATCH` when the caller names one.
+
+@testable import FirmwarePatcher
+import Foundation
+import Testing
+
+// MARK: - Fixture discovery
+
+private enum DiskImagesFixture {
+ static let repoRoot = URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+
+ /// The read-only reference tree of standalone Mach-O binaries.
+ static var pristineDirectory: URL? {
+ let url = ProcessInfo.processInfo.environment["VPHONE_MACHO_PRISTINE"]
+ .map { URL(fileURLWithPath: $0) }
+ ?? repoRoot.appendingPathComponent("ipsws/ref_extract/macho_pristine")
+ let main = url.appendingPathComponent("diskimagesiod")
+ return FileManager.default.fileExists(atPath: main.path) ? url : nil
+ }
+
+ static var pristine: URL? { pristineDirectory?.appendingPathComponent("diskimagesiod") }
+
+ /// A second real binary from the same firmware, used as the negative case:
+ /// it has no `DIDiskArb`, so locating must fail rather than find something.
+ static var unrelated: URL? { pristineDirectory?.appendingPathComponent("watchdogd") }
+
+ /// Opt-out for a machine that cannot carry the fixture.
+ static var isOptional: Bool {
+ ProcessInfo.processInfo.environment["VPHONE_MACHO_FIXTURE_OPTIONAL"] == "1"
+ }
+
+ /// The suite runs unless the fixture is absent *and* the caller opted out.
+ static var runs: Bool { pristine != nil || !isOptional }
+
+ static let missing: Comment = """
+ the real 24A435 arm64e diskimagesiod is required — put it at \
+ ipsws/ref_extract/macho_pristine/diskimagesiod, point VPHONE_MACHO_PRISTINE \
+ at its directory, or set VPHONE_MACHO_FIXTURE_OPTIONAL=1 to skip these \
+ tests instead of failing
+ """
+
+ /// Where clones go. Deliberately *not* inside `ipsws/ref_extract`: that tree
+ /// is the pristine reference every parity test compares against, and a
+ /// scratch directory next to it is one `rm -rf` typo away from destroying an
+ /// extraction that costs a 12 GB IPSW to regenerate.
+ static var scratchRoot: URL {
+ ProcessInfo.processInfo.environment["VPHONE_MACHO_SCRATCH"]
+ .map { URL(fileURLWithPath: $0) }
+ ?? URL(fileURLWithPath: NSTemporaryDirectory())
+ .appendingPathComponent("vphone-macho-diskimagesiod")
+ }
+
+ /// The project venv, which is where the reference Python lives.
+ static var python: URL? {
+ let url = repoRoot.appendingPathComponent(".venv/bin/python3")
+ return FileManager.default.fileExists(atPath: url.path) ? url : nil
+ }
+
+ static var cfwPy: URL { repoRoot.appendingPathComponent("scripts/patchers/cfw.py") }
+
+ /// Clone the pristine binary into a fresh file the caller may write to.
+ ///
+ /// `cp -c` asks for a `clonefile`, which costs no space and no time when the
+ /// scratch root shares the fixture's APFS volume. When it does not — a
+ /// caller who pointed `VPHONE_MACHO_SCRATCH` at another disk — the clone is
+ /// refused and the fallback is an ordinary copy rather than a failed test.
+ static func clone(named name: String) throws -> URL {
+ let pristine = try #require(self.pristine, missing)
+ try FileManager.default.createDirectory(
+ at: scratchRoot,
+ withIntermediateDirectories: true
+ )
+ let destination = scratchRoot.appendingPathComponent(name)
+ try? FileManager.default.removeItem(at: destination)
+
+ for flags in [["-c"], []] {
+ let result = try DiskImagesShell.run(
+ executable: URL(fileURLWithPath: "/bin/cp"),
+ arguments: flags + [pristine.path, destination.path]
+ )
+ if result.status == 0 { return destination }
+ }
+ Issue.record("could not clone \(pristine.path) to \(destination.path)")
+ throw CocoaError(.fileWriteUnknown)
+ }
+
+ /// Discard clones.
+ ///
+ /// The scratch *root* is deliberately left behind. Suites run in parallel
+ /// even when each one is `.serialized`, so a suite that removed the shared
+ /// root on its way out would be deleting a directory another suite is
+ /// mid-clone into. The root is an empty directory under the system
+ /// temporary directory, which the OS reaps on its own schedule.
+ static func discard(_ clones: URL...) {
+ for clone in clones {
+ try? FileManager.default.removeItem(at: clone)
+ }
+ }
+
+ /// Run the shipped Python patcher over `binary`.
+ @discardableResult
+ static func runPython(on binary: URL) throws -> DiskImagesShell.Result {
+ let python = try #require(
+ self.python,
+ "the reference Python is required — run `make setup_venv`"
+ )
+ let result = try DiskImagesShell.run(
+ executable: python,
+ arguments: [cfwPy.path, "patch-diskimagesiod", binary.path],
+ currentDirectory: repoRoot.appendingPathComponent("scripts")
+ )
+ #expect(result.status == 0, "cfw.py patch-diskimagesiod failed: \(result.stderr)")
+ return result
+ }
+
+ /// Re-attest `offsets` in `binary` using the Python's own independent
+ /// implementation, `cfw_macho_codesign.reattest_modified_offsets`.
+ @discardableResult
+ static func runPythonReattest(on binary: URL, offsets: [Int]) throws -> DiskImagesShell.Result {
+ let python = try #require(
+ self.python,
+ "the reference Python is required — run `make setup_venv`"
+ )
+ let list = offsets.map(String.init).joined(separator: ",")
+ let program = """
+ import sys
+ sys.path.insert(0, "scripts")
+ from patchers.cfw_macho_codesign import reattest_modified_offsets
+ reattest_modified_offsets(sys.argv[1], [\(list)], verbose=False)
+ """
+ let result = try DiskImagesShell.run(
+ executable: python,
+ arguments: ["-c", program, binary.path],
+ currentDirectory: repoRoot
+ )
+ #expect(result.status == 0, "python reattest failed: \(result.stderr)")
+ return result
+ }
+
+ /// `codesign -v` on a file, which is a reference neither implementation wrote.
+ static func codesignVerify(_ binary: URL) throws -> DiskImagesShell.Result {
+ try DiskImagesShell.run(
+ executable: URL(fileURLWithPath: "/usr/bin/codesign"),
+ arguments: ["-v", "--verbose=2", binary.path]
+ )
+ }
+}
+
+// MARK: - Subprocess helper
+
+private enum DiskImagesShell {
+ struct Result {
+ let status: Int32
+ let stdout: String
+ let stderr: String
+ }
+
+ /// Run `executable` to completion and collect both streams.
+ ///
+ /// The two pipes are drained on separate queues rather than one after the
+ /// other. A pipe holds about 64 KiB; draining stdout to EOF first would
+ /// wedge any child that fills stderr in the meantime, and the child here is
+ /// a Python patcher that logs freely to both.
+ @discardableResult
+ static func run(
+ executable: URL,
+ arguments: [String],
+ currentDirectory: URL? = nil
+ ) throws -> Result {
+ let process = Process()
+ process.executableURL = executable
+ process.arguments = arguments
+ if let currentDirectory { process.currentDirectoryURL = currentDirectory }
+ let out = Pipe()
+ let err = Pipe()
+ process.standardOutput = out
+ process.standardError = err
+ try process.run()
+
+ let collected = Drain()
+ let group = DispatchGroup()
+ for (handle, isStandardOutput) in [
+ (out.fileHandleForReading, true),
+ (err.fileHandleForReading, false),
+ ] {
+ DispatchQueue.global().async(group: group) {
+ let data = handle.readDataToEndOfFile()
+ collected.store(data, isStandardOutput: isStandardOutput)
+ }
+ }
+ group.wait()
+ process.waitUntilExit()
+
+ return Result(
+ status: process.terminationStatus,
+ stdout: String(decoding: collected.standardOutput, as: UTF8.self),
+ stderr: String(decoding: collected.standardError, as: UTF8.self)
+ )
+ }
+
+ /// Somewhere for the two reader queues to put what they read.
+ private final class Drain: @unchecked Sendable {
+ private let lock = NSLock()
+ private var out = Data()
+ private var err = Data()
+
+ func store(_ data: Data, isStandardOutput: Bool) {
+ lock.lock()
+ defer { lock.unlock() }
+ if isStandardOutput { out = data } else { err = data }
+ }
+
+ var standardOutput: Data { lock.withLock { out } }
+ var standardError: Data { lock.withLock { err } }
+ }
+}
+
+// MARK: - Byte comparison
+
+private enum DiskImagesComparison {
+ /// Every offset at which two files differ, capped so a wholly wrong result
+ /// reports a count instead of megabytes of noise.
+ static func differences(between lhs: URL, and rhs: URL, limit: Int = 16) throws -> [Int] {
+ let left = try Data(contentsOf: lhs)
+ let right = try Data(contentsOf: rhs)
+ guard left.count == right.count else { return [-1] }
+ var offsets: [Int] = []
+ for index in 0 ..< left.count where left[index] != right[index] {
+ offsets.append(index)
+ if offsets.count >= limit { break }
+ }
+ return offsets
+ }
+
+ static func identical(_ lhs: URL, _ rhs: URL) throws -> Bool {
+ try differences(between: lhs, and: rhs, limit: 1).isEmpty
+ }
+}
+
+// MARK: - The replacement bytes
+
+@Suite("diskimagesiod replacement encoding")
+struct CFWDiskimagesiodEncodingTests {
+ @Test("`mov x0, #1` built from ISA fields is the keystone-verified constant")
+ func movzAgreesWithKeystone() throws {
+ let encoded = try #require(ARM64Encoder.encodeMovzX(rd: 0, imm16: 1))
+ #expect(encoded == ARM64.movX0_1)
+ // 0xD2800020, little-endian on disk.
+ #expect(encoded.hex == "200080d2")
+ }
+
+ @Test("the patch writes exactly `mov x0, #1 ; ret`")
+ func replacementDisassembles() {
+ #expect(CFWDiskimagesiod.replacement.count == 8)
+ #expect(CFWDiskimagesiod.replacement == ARM64.movX0_1 + ARM64.ret)
+ #expect(
+ CFWDiskimagesiod.disassemblyText(of: CFWDiskimagesiod.replacement, at: nil)
+ == "mov x0, #1; ret"
+ )
+ }
+}
+
+// MARK: - Anchoring
+
+@Suite(
+ "diskimagesiod anchoring",
+ .enabled(if: DiskImagesFixture.runs, DiskImagesFixture.missing),
+ .serialized
+)
+struct CFWDiskimagesiodAnchorTests {
+ @Test("the IMP resolves through the relative method list, into __TEXT,__text")
+ func locatesImplementation() throws {
+ let pristine = try #require(DiskImagesFixture.pristine, DiskImagesFixture.missing)
+ let data = try Data(contentsOf: pristine)
+ let site = try CFWDiskimagesiod.locate(in: data)
+
+ // Shipped diskimagesiod is stripped, so the symbol-table anchor misses
+ // and the ObjC metadata walk is what answers.
+ #expect(site.anchor == .relativeMethodList)
+ #expect(MachOParser.findSymbol(containing: CFWDiskimagesiod.symbolFragment, in: data) == nil)
+
+ let sections = MachOParser.parseSections(from: data)
+ let text = try #require(sections["__TEXT,__text"])
+ #expect(site.fileOffset >= Int(text.fileOffset))
+ #expect(site.fileOffset + 8 <= Int(text.fileOffset) + Int(text.size))
+
+ // The VA and the file offset have to agree through the segment table.
+ let va = try #require(site.virtualAddress)
+ let segments = MachOParser.parseSegments(from: data)
+ #expect(MachOParser.vaToFileOffset(va, segments: segments) == site.fileOffset)
+
+ // A real ObjC method prologue, not yet patched.
+ #expect(!site.isAlreadyPatched)
+ #expect(CFWDiskimagesiod.disassemblyText(of: site.original, at: va)
+ .hasPrefix("pacibsp; stp"))
+ }
+
+ @Test("the Python's own anchor walk agrees on the same offset")
+ func agreesWithPythonAnchor() throws {
+ let pristine = try #require(DiskImagesFixture.pristine, DiskImagesFixture.missing)
+ let site = try CFWDiskimagesiod.locate(in: try Data(contentsOf: pristine))
+
+ // The Python prints the offset it resolved; both walks must land on it.
+ let clone = try DiskImagesFixture.clone(named: "anchor")
+ defer { DiskImagesFixture.discard(clone) }
+ let output = try DiskImagesFixture.runPython(on: clone).stdout
+ let expected = "IMP va:0x\(String(site.virtualAddress ?? 0, radix: 16, uppercase: true)) "
+ + "foff:0x\(String(site.fileOffset, radix: 16, uppercase: true))"
+ #expect(output.contains(expected), "python said:\n\(output)")
+ }
+
+ @Test("the selector names exactly one implementation in the image")
+ func selectorIsUnique() throws {
+ let pristine = try #require(DiskImagesFixture.pristine, DiskImagesFixture.missing)
+ let data = try Data(contentsOf: pristine)
+ let sections = MachOParser.parseSections(from: data)
+
+ let selectorVA = try #require(
+ CFWDiskimagesiod.selectorStringVA(in: data, sections: sections)
+ )
+ let selrefs = try #require(sections["__DATA,__objc_selrefs"])
+ let selrefVA = try #require(CFWDiskimagesiod.selectorReferenceVA(
+ in: data,
+ selrefs: selrefs,
+ selectorVA: selectorVA,
+ imageBase: CFWDiskimagesiod.imageBase(sections)
+ ))
+
+ let methlist = try #require(sections["__TEXT,__objc_methlist"])
+ let imps = CFWDiskimagesiod.relativeMethodListIMPs(
+ in: data,
+ section: methlist,
+ naming: [selectorVA, selrefVA]
+ )
+ #expect(imps.count == 1)
+ #expect(imps.first == (try CFWDiskimagesiod.locate(in: data)).virtualAddress)
+ }
+
+ @Test("the strided fallback scan lands on the same IMP as the structural walk")
+ func scanFallbackAgreesWithStructuralWalk() throws {
+ let pristine = try #require(DiskImagesFixture.pristine, DiskImagesFixture.missing)
+ let data = try Data(contentsOf: pristine)
+ let sections = MachOParser.parseSections(from: data)
+
+ let selectorVA = try #require(
+ CFWDiskimagesiod.selectorStringVA(in: data, sections: sections)
+ )
+ let selrefs = try #require(sections["__DATA,__objc_selrefs"])
+ let selrefVA = try #require(CFWDiskimagesiod.selectorReferenceVA(
+ in: data,
+ selrefs: selrefs,
+ selectorVA: selectorVA,
+ imageBase: CFWDiskimagesiod.imageBase(sections)
+ ))
+ let methlist = try #require(sections["__TEXT,__objc_methlist"])
+ let targets: Set<UInt64> = [selectorVA, selrefVA]
+
+ // The Python only ever does the strided scan. Both walks over the same
+ // section have to name the same single implementation, or the two
+ // implementations would diverge on some other firmware even though they
+ // agree on this one.
+ let structural = CFWDiskimagesiod.relativeMethodListIMPs(
+ in: data,
+ section: methlist,
+ naming: targets
+ )
+ let strided = CFWDiskimagesiod.scanRelativeMethodEntryIMPs(
+ in: data,
+ section: methlist,
+ naming: targets
+ )
+ #expect(structural == strided)
+ #expect(strided.count == 1)
+ }
+
+ @Test("a binary without DIDiskArb is refused, not guessed at")
+ func unrelatedBinaryIsRefused() throws {
+ let unrelated = try #require(DiskImagesFixture.unrelated, DiskImagesFixture.missing)
+ let data = try Data(contentsOf: unrelated)
+ #expect(throws: PatcherError.self) {
+ try CFWDiskimagesiod.locate(in: data)
+ }
+ }
+}
+
+// MARK: - Parity against the Python
+
+@Suite(
+ "diskimagesiod parity",
+ .enabled(if: DiskImagesFixture.runs, DiskImagesFixture.missing),
+ .serialized
+)
+struct CFWDiskimagesiodParityTests {
+ @Test("Swift and Python produce byte-identical binaries, one site each")
+ func byteForByteParity() throws {
+ let swiftClone = try DiskImagesFixture.clone(named: "swift")
+ let pythonClone = try DiskImagesFixture.clone(named: "python")
+ defer { DiskImagesFixture.discard(swiftClone, pythonClone) }
+
+ let report = try CFWDiskimagesiod.patch(fileAt: swiftClone, log: nil)
+ #expect(report.outcome == .patched)
+ #expect(report.sitesWritten == 1)
+ // Off by default: `cfw_install.sh` re-signs with ldid straight after,
+ // and the Python does not re-attest either.
+ #expect(report.rehashes.isEmpty)
+
+ try DiskImagesFixture.runPython(on: pythonClone)
+
+ let differences = try DiskImagesComparison.differences(between: swiftClone, and: pythonClone)
+ #expect(differences.isEmpty, "first differing offsets: \(differences.map { String($0, radix: 16) })")
+ }
+
+ @Test("the recorded write names the site, the bytes and both disassemblies")
+ func recordDescribesTheSite() throws {
+ let clone = try DiskImagesFixture.clone(named: "record")
+ defer { DiskImagesFixture.discard(clone) }
+
+ let report = try CFWDiskimagesiod.patch(fileAt: clone, log: nil)
+ let record = try #require(report.record)
+
+ #expect(record.patchID == "diskimagesiod.is_mount_complete")
+ #expect(record.component == "diskimagesiod")
+ #expect(record.fileOffset == report.site.fileOffset)
+ #expect(record.virtualAddress == report.site.virtualAddress)
+ #expect(record.originalBytes == report.site.original)
+ #expect(record.patchedBytes == CFWDiskimagesiod.replacement)
+ #expect(record.afterDisasm == "mov x0, #1; ret")
+ #expect(record.beforeDisasm.hasPrefix("pacibsp"))
+ #expect(record.patchDescription.contains("isMountCompleteWithExpectedCount:diskTracker:"))
+
+ // What landed on disk is what the record claims.
+ let patched = try Data(contentsOf: clone)
+ let range = record.fileOffset ..< record.fileOffset + record.patchedBytes.count
+ #expect(patched[range] == record.patchedBytes)
+ }
+
+ @Test("only the eight patched bytes differ from the pristine binary")
+ func onlyTheSiteChanges() throws {
+ let clone = try DiskImagesFixture.clone(named: "minimal")
+ defer { DiskImagesFixture.discard(clone) }
+ let pristine = try #require(DiskImagesFixture.pristine, DiskImagesFixture.missing)
+
+ let report = try CFWDiskimagesiod.patch(fileAt: clone, log: nil)
+ let differences = try DiskImagesComparison.differences(
+ between: pristine,
+ and: clone,
+ limit: 64
+ )
+ #expect(differences.allSatisfy {
+ (report.site.fileOffset ..< report.site.fileOffset + 8).contains($0)
+ })
+ #expect(!differences.isEmpty)
+ }
+}
+
+// MARK: - Re-signing
+
+@Suite(
+ "diskimagesiod re-attestation",
+ .enabled(if: DiskImagesFixture.runs, DiskImagesFixture.missing),
+ .serialized
+)
+struct CFWDiskimagesiodReattestTests {
+ @Test("the fixture really does have the short tail slot this path regressed on")
+ func fixtureHasShortTail() throws {
+ let pristine = try #require(DiskImagesFixture.pristine, DiskImagesFixture.missing)
+ let data = try Data(contentsOf: pristine)
+ let directories = try #require(CFWMachOCodeSignature.codeDirectories(in: data))
+ let directory = try #require(directories.first)
+
+ #expect(directory.hashType == CFWMachOCodeSignature.hashTypeSHA256)
+ #expect(directory.pageSize == 4096)
+ #expect(directory.codeLimit % directory.pageSize != 0, "expected a non-page-aligned codeLimit")
+
+ let tail = try #require(directory.slotRange(directory.codeSlotCount - 1))
+ #expect(tail.count < directory.pageSize)
+ #expect(tail.upperBound == directory.codeLimit)
+ }
+
+ @Test("`codesign -v` rejects the un-attested patch and accepts the attested one")
+ func codesignAgrees() throws {
+ let bare = try DiskImagesFixture.clone(named: "bare")
+ let attested = try DiskImagesFixture.clone(named: "attested")
+ defer { DiskImagesFixture.discard(bare, attested) }
+
+ try CFWDiskimagesiod.patch(fileAt: bare, log: nil)
+ #expect(try DiskImagesFixture.codesignVerify(bare).status != 0)
+
+ let report = try CFWDiskimagesiod.patch(fileAt: attested, reattest: true, log: nil)
+ #expect(report.outcome == .patched)
+ #expect(report.rehashes.count == 1)
+
+ let slot = try #require(report.rehashes.first)
+ #expect(slot.pageIndex == report.site.fileOffset / slot.pageSize)
+ #expect(!slot.isTailSlot)
+ #expect(slot.before != slot.after)
+
+ let verification = try DiskImagesFixture.codesignVerify(attested)
+ #expect(verification.status == 0, "codesign said: \(verification.stderr)")
+ }
+
+ @Test("the re-attested bytes are the Python re-attest's bytes")
+ func reattestMatchesPython() throws {
+ let swiftClone = try DiskImagesFixture.clone(named: "swift-attested")
+ let pythonClone = try DiskImagesFixture.clone(named: "python-attested")
+ defer { DiskImagesFixture.discard(swiftClone, pythonClone) }
+
+ let report = try CFWDiskimagesiod.patch(fileAt: swiftClone, reattest: true, log: nil)
+
+ try DiskImagesFixture.runPython(on: pythonClone)
+ try DiskImagesFixture.runPythonReattest(
+ on: pythonClone,
+ offsets: [report.site.fileOffset, report.site.fileOffset + 7]
+ )
+
+ let differences = try DiskImagesComparison.differences(between: swiftClone, and: pythonClone)
+ #expect(differences.isEmpty, "first differing offsets: \(differences.map { String($0, radix: 16) })")
+ }
+
+ @Test("a short-tail slot is hashed to codeLimit, not to the end of its page")
+ func tailSlotStopsAtCodeLimit() throws {
+ let swiftClone = try DiskImagesFixture.clone(named: "swift-tail")
+ let pythonClone = try DiskImagesFixture.clone(named: "python-tail")
+ defer { DiskImagesFixture.discard(swiftClone, pythonClone) }
+
+ // Land a byte inside the last, short slot. This is synthetic — the real
+ // patch site is nowhere near — and it is the only way to make both
+ // implementations recompute the slot whose length is not a page.
+ var data = try Data(contentsOf: swiftClone)
+ let directory = try #require(CFWMachOCodeSignature.codeDirectories(in: data)?.first)
+ let tail = try #require(directory.slotRange(directory.codeSlotCount - 1))
+ let victim = tail.lowerBound + tail.count / 2
+ data[victim] = data[victim] ^ 0xFF
+ try data.write(to: swiftClone)
+ try data.write(to: pythonClone)
+
+ let rehashes = try CFWMachOCodeSignature.reattest(fileAt: swiftClone, modifiedOffsets: [victim])
+ let slot = try #require(rehashes.first)
+ #expect(slot.isTailSlot)
+ #expect(slot.hashedLength == tail.count)
+ #expect(slot.pageEnd == directory.codeLimit)
+
+ try DiskImagesFixture.runPythonReattest(on: pythonClone, offsets: [victim])
+ let differences = try DiskImagesComparison.differences(between: swiftClone, and: pythonClone)
+ #expect(differences.isEmpty, "first differing offsets: \(differences.map { String($0, radix: 16) })")
+ }
+}
+
+// MARK: - Idempotence
+
+@Suite(
+ "diskimagesiod idempotence",
+ .enabled(if: DiskImagesFixture.runs, DiskImagesFixture.missing),
+ .serialized
+)
+struct CFWDiskimagesiodIdempotenceTests {
+ @Test("a second Swift run recognises its own output and writes nothing")
+ func secondRunIsANoOp() throws {
+ let clone = try DiskImagesFixture.clone(named: "twice")
+ defer { DiskImagesFixture.discard(clone) }
+
+ try CFWDiskimagesiod.patch(fileAt: clone, log: nil)
+ let afterFirst = try Data(contentsOf: clone)
+ let attributes = try FileManager.default.attributesOfItem(atPath: clone.path)
+
+ let second = try CFWDiskimagesiod.patch(fileAt: clone, log: nil)
+ #expect(second.outcome == .alreadyPatched)
+ #expect(second.sitesWritten == 0)
+ #expect(second.record == nil)
+ #expect(second.site.isAlreadyPatched)
+ #expect(try Data(contentsOf: clone) == afterFirst)
+
+ // Nothing was written at all, so even the modification time stands.
+ let after = try FileManager.default.attributesOfItem(atPath: clone.path)
+ #expect(after[.modificationDate] as? Date == attributes[.modificationDate] as? Date)
+ }
+
+ @Test("a second run with re-attestation leaves the slot hashes alone")
+ func secondAttestedRunIsANoOp() throws {
+ let clone = try DiskImagesFixture.clone(named: "twice-attested")
+ defer { DiskImagesFixture.discard(clone) }
+
+ try CFWDiskimagesiod.patch(fileAt: clone, reattest: true, log: nil)
+ let afterFirst = try Data(contentsOf: clone)
+
+ let second = try CFWDiskimagesiod.patch(fileAt: clone, reattest: true, log: nil)
+ #expect(second.outcome == .alreadyPatched)
+ #expect(second.sitesWritten == 0)
+ #expect(second.rehashes.isEmpty, "the stored slot hashes were already current")
+ #expect(try Data(contentsOf: clone) == afterFirst)
+ #expect(try DiskImagesFixture.codesignVerify(clone).status == 0)
+ }
+
+ @Test("Python over a Swift-patched binary is a no-op, and the reverse too")
+ func crossImplementationRerunsAgree() throws {
+ let swiftFirst = try DiskImagesFixture.clone(named: "swift-then-python")
+ let pythonFirst = try DiskImagesFixture.clone(named: "python-then-swift")
+ defer { DiskImagesFixture.discard(swiftFirst, pythonFirst) }
+
+ try CFWDiskimagesiod.patch(fileAt: swiftFirst, log: nil)
+ let afterSwift = try Data(contentsOf: swiftFirst)
+ try DiskImagesFixture.runPython(on: swiftFirst)
+ #expect(try Data(contentsOf: swiftFirst) == afterSwift)
+
+ try DiskImagesFixture.runPython(on: pythonFirst)
+ let afterPython = try Data(contentsOf: pythonFirst)
+ let report = try CFWDiskimagesiod.patch(fileAt: pythonFirst, log: nil)
+ #expect(report.outcome == .alreadyPatched)
+ #expect(try Data(contentsOf: pythonFirst) == afterPython)
+ #expect(try DiskImagesComparison.identical(swiftFirst, pythonFirst))
+ }
+
+ @Test("a dry run locates the site and writes nothing")
+ func dryRunWritesNothing() throws {
+ let clone = try DiskImagesFixture.clone(named: "dry")
+ defer { DiskImagesFixture.discard(clone) }
+ let pristine = try #require(DiskImagesFixture.pristine, DiskImagesFixture.missing)
+
+ let report = try CFWDiskimagesiod.patch(fileAt: clone, reattest: true, dryRun: true, log: nil)
+ #expect(report.outcome == .wouldPatch)
+ #expect(report.sitesWritten == 0)
+ #expect(report.rehashes.isEmpty)
+ #expect(report.site.fileOffset > 0)
+ #expect(try DiskImagesComparison.identical(pristine, clone))
+ }
+}
diff --git a/tests/FirmwarePatcherTests/CFWJetsamTests.swift b/tests/FirmwarePatcherTests/CFWJetsamTests.swift
new file mode 100644
index 00000000..f1607b87
--- /dev/null
+++ b/tests/FirmwarePatcherTests/CFWJetsamTests.swift
@@ -0,0 +1,570 @@
+// CFWJetsamTests.swift — `CFWJetsamPatcher` against the reference it replaces.
+//
+// The bar for this port is not "the test passes". It is that the Swift patcher
+// and `scripts/patchers/cfw_patch_jetsam.py` produce the same bytes from the
+// same input, on the real `/sbin/launchd` out of iOS 27.0 / 24A435 — so the
+// comparison tests below run BOTH implementations, each over its own clone of
+// `ipsws/ref_extract/macho_pristine/launchd`, and diff the results.
+//
+// `codesign -v` is the second, fully independent reference: the patcher's
+// `reattest: true` mode has to leave a binary that verifies, and the slot hash
+// it writes has to equal the one the Python's own `cfw_macho_codesign.py`
+// computes over the same patched bytes.
+//
+// The reference is on its way out — plan P1.5 deletes `scripts/patchers/`, and
+// `ipsws/` is not in the repo — so every test that needs one is gated on it
+// still being there and skips rather than fails when it is not. The pure
+// decode/encode tests below have no such dependency and always run.
+//
+// Set `VPHONE_JETSAM_ARTIFACTS=<dir>` to keep each run's inputs and outputs for
+// inspection from a shell; without it they land in a temporary directory.
+
+import Capstone
+@testable import FirmwarePatcher
+import Foundation
+import Testing
+
+// MARK: - Fixtures
+
+enum JetsamFixture {
+ /// 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 real, ad-hoc signed, thin arm64e `/sbin/launchd`.
+ static let pristineLaunchd = repositoryRoot
+ .appending(path: "ipsws/ref_extract/macho_pristine/launchd")
+ static let python = repositoryRoot.appending(path: ".venv/bin/python3")
+ static let pythonCFW = repositoryRoot.appending(path: "scripts/patchers/cfw.py")
+ static let pythonCodeSign = repositoryRoot.appending(path: "scripts/patchers/cfw_macho_codesign.py")
+ static let scriptsDirectory = repositoryRoot.appending(path: "scripts")
+ static let codesign = URL(filePath: "/usr/bin/codesign")
+
+ static func exists(_ url: URL) -> Bool { FileManager.default.fileExists(atPath: url.path) }
+
+ static var hasLaunchd: Bool { exists(pristineLaunchd) }
+ static var hasPythonReference: Bool { exists(python) && exists(pythonCFW) }
+ static var hasLaunchdAndPython: Bool { hasLaunchd && hasPythonReference }
+ static var hasLaunchdAndCodesign: Bool { hasLaunchd && exists(codesign) }
+
+ /// A directory for one test's artifacts. `VPHONE_JETSAM_ARTIFACTS` pins it
+ /// so a shell can look at what a run produced.
+ static func workDirectory(_ name: String) throws -> URL {
+ let base = ProcessInfo.processInfo.environment["VPHONE_JETSAM_ARTIFACTS"]
+ .map { URL(filePath: $0) } ?? URL(filePath: NSTemporaryDirectory())
+ let directory = base.appending(path: "CFWJetsamTests-\(name)")
+ try? FileManager.default.removeItem(at: directory)
+ try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+ return directory
+ }
+
+ /// A private, writable clone of the pristine `launchd`.
+ static func launchdCopy(named name: String, in directory: URL) throws -> URL {
+ let destination = directory.appending(path: name)
+ try FileManager.default.copyItem(at: pristineLaunchd, to: destination)
+ return destination
+ }
+
+ @discardableResult
+ static func run(
+ _ tool: URL,
+ _ arguments: [String],
+ workingDirectory: URL? = nil
+ ) throws -> (status: Int32, output: String) {
+ let process = Process()
+ process.executableURL = tool
+ process.arguments = arguments
+ process.currentDirectoryURL = workingDirectory
+ 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))
+ }
+
+ /// `cfw.py patch-launchd-jetsam <file>` — the reference implementation.
+ @discardableResult
+ static func runPythonJetsam(on file: URL) throws -> (status: Int32, output: String) {
+ try run(
+ python,
+ ["patchers/cfw.py", "patch-launchd-jetsam", file.path],
+ workingDirectory: scriptsDirectory
+ )
+ }
+
+ /// The hex number the reference prints straight after `marker`, so the
+ /// expected values come out of the reference's own stdout instead of being
+ /// written down here and going stale with the next firmware.
+ static func hexAfter(_ marker: String, in output: String) -> Int? {
+ guard let range = output.range(of: marker) else { return nil }
+ return Int(String(output[range.upperBound...].prefix { $0.isHexDigit }), radix: 16)
+ }
+
+ /// The first byte offset at which two files differ, or nil when equal.
+ static func firstDifference(_ lhs: Data, _ rhs: Data) -> Int? {
+ if lhs.count != rhs.count { return min(lhs.count, rhs.count) }
+ for index in 0 ..< lhs.count where lhs[index] != rhs[index] { return index }
+ return nil
+ }
+}
+
+// MARK: - Against the Python reference
+
+@Suite("launchd jetsam guard — against the Python reference")
+struct CFWJetsamReferenceTests {
+ /// The whole point of the port: same input, same bytes out.
+ @Test(.enabled(if: JetsamFixture.hasLaunchdAndPython))
+ func matchesPythonByteForByte() throws {
+ let work = try JetsamFixture.workDirectory("byte-equivalence")
+ let swiftTarget = try JetsamFixture.launchdCopy(named: "launchd.swift", in: work)
+ let pythonTarget = try JetsamFixture.launchdCopy(named: "launchd.python", in: work)
+
+ let outcome = try CFWJetsamPatcher.patch(fileAt: swiftTarget, log: nil)
+ #expect(outcome.verdict == .patched)
+
+ let reference = try JetsamFixture.runPythonJetsam(on: pythonTarget)
+ #expect(reference.status == 0, "reference patcher failed:\n\(reference.output)")
+
+ let swiftBytes = try Data(contentsOf: swiftTarget)
+ let pythonBytes = try Data(contentsOf: pythonTarget)
+ let difference = JetsamFixture.firstDifference(swiftBytes, pythonBytes)
+ #expect(
+ difference == nil,
+ "Swift and Python diverge at offset \(difference.map { "0x" + String($0, radix: 16) } ?? "-")"
+ )
+
+ // And the only thing that moved is inside the instruction the record
+ // names. Not every one of the four bytes has to differ: on this image
+ // `cbz w0, #0xfaec` is A0 02 00 34 and `b #0xfaec` is 15 00 00 14, so
+ // byte 2 is 0x00 either way. Containment is the real claim — the whole
+ // instruction was rewritten and nothing outside it was.
+ let pristine = try Data(contentsOf: JetsamFixture.pristineLaunchd)
+ let site = outcome.gateOffset ..< outcome.gateOffset + 4
+ let changed = (0 ..< pristine.count).filter { pristine[$0] != swiftBytes[$0] }
+ #expect(!changed.isEmpty)
+ #expect(changed.allSatisfy(site.contains), "bytes changed outside the gate: \(changed)")
+ #expect(Data(swiftBytes[site]) == outcome.record?.patchedBytes)
+ #expect(Data(pristine[site]) == outcome.record?.originalBytes)
+ }
+
+ /// The gate the reference reports is the gate this finds. Checked against
+ /// its stdout rather than a hard-coded offset, so the day the firmware
+ /// moves, this moves with it.
+ @Test(.enabled(if: JetsamFixture.hasLaunchdAndPython))
+ func agreesWithPythonOnTheSite() throws {
+ let work = try JetsamFixture.workDirectory("site-agreement")
+ let pythonTarget = try JetsamFixture.launchdCopy(named: "launchd.python", in: work)
+ let reference = try JetsamFixture.runPythonJetsam(on: pythonTarget)
+ #expect(reference.status == 0)
+
+ // Both intermediate anchors the reference prints, not just its answer,
+ // so a port that agreed on the gate by luck would still be caught:
+ // " xref at foff:0xFB0C"
+ // " [+] Patched at 0xFA98: jetsam panic guard bypass"
+ let referenceXref = try #require(JetsamFixture.hexAfter("xref at foff:0x", in: reference.output))
+ let referenceGate = try #require(JetsamFixture.hexAfter("[+] Patched at 0x", in: reference.output))
+
+ let data = try Data(contentsOf: JetsamFixture.pristineLaunchd)
+ let image = try CFWJetsamPatcher.Image(data: data)
+ let site = try #require(try CFWJetsamPatcher.locate(in: image))
+ #expect(site.xrefOffset == referenceXref)
+ #expect(site.gateOffset == referenceGate)
+
+ var patchable = data
+ let outcome = try CFWJetsamPatcher.patch(&patchable, dryRun: true, log: nil)
+ #expect(outcome.gateOffset == referenceGate)
+ #expect(outcome.verdict == .wouldPatch)
+ }
+}
+
+// MARK: - Idempotence
+
+@Suite("launchd jetsam guard — idempotence")
+struct CFWJetsamIdempotenceTests {
+ /// The bug this patcher must not have. The reference re-patches a second,
+ /// different branch on an already-patched binary; this one recognises its
+ /// own work and stops.
+ @Test(.enabled(if: JetsamFixture.hasLaunchd))
+ func secondRunChangesNothing() throws {
+ let work = try JetsamFixture.workDirectory("idempotence")
+ let target = try JetsamFixture.launchdCopy(named: "launchd", in: work)
+
+ let first = try CFWJetsamPatcher.patch(fileAt: target, log: nil)
+ #expect(first.verdict == .patched)
+ let afterFirst = try Data(contentsOf: target)
+
+ let second = try CFWJetsamPatcher.patch(fileAt: target, log: nil)
+ #expect(second.verdict == .alreadyPatched)
+ #expect(second.gateOffset == first.gateOffset)
+ #expect(second.returnBlockOffset == first.returnBlockOffset)
+ #expect(second.record == nil)
+
+ let afterSecond = try Data(contentsOf: target)
+ #expect(JetsamFixture.firstDifference(afterFirst, afterSecond) == nil)
+
+ // A third pass must not drift either.
+ let third = try CFWJetsamPatcher.patch(fileAt: target, log: nil)
+ #expect(third.verdict == .alreadyPatched)
+ let afterThird = try Data(contentsOf: target)
+ #expect(JetsamFixture.firstDifference(afterFirst, afterThird) == nil)
+ }
+
+ /// Where the reference goes wrong, and proof that it does: run the Python
+ /// twice and it lands a *second* site the pristine image never had patched.
+ /// Recorded here so the divergence is a measurement, not a claim.
+ @Test(.enabled(if: JetsamFixture.hasLaunchdAndPython))
+ func referenceIsNotIdempotentAndThisIs() throws {
+ let work = try JetsamFixture.workDirectory("reference-double-apply")
+ let pythonTarget = try JetsamFixture.launchdCopy(named: "launchd.python", in: work)
+ let swiftTarget = try JetsamFixture.launchdCopy(named: "launchd.swift", in: work)
+
+ try JetsamFixture.runPythonJetsam(on: pythonTarget)
+ let pythonOnce = try Data(contentsOf: pythonTarget)
+ try JetsamFixture.runPythonJetsam(on: pythonTarget)
+ let pythonTwice = try Data(contentsOf: pythonTarget)
+
+ try CFWJetsamPatcher.patch(fileAt: swiftTarget, log: nil)
+ let swiftOnce = try Data(contentsOf: swiftTarget)
+ try CFWJetsamPatcher.patch(fileAt: swiftTarget, log: nil)
+ let swiftTwice = try Data(contentsOf: swiftTarget)
+
+ #expect(JetsamFixture.firstDifference(pythonOnce, swiftOnce) == nil)
+ #expect(
+ JetsamFixture.firstDifference(pythonOnce, pythonTwice) != nil,
+ "the reference became idempotent — re-check what this port has to preserve"
+ )
+ #expect(JetsamFixture.firstDifference(swiftOnce, swiftTwice) == nil)
+ }
+}
+
+// MARK: - Re-attestation
+
+@Suite("launchd jetsam guard — signature re-attestation")
+struct CFWJetsamSignatureTests {
+ /// Default is the reference's behaviour: the four bytes and nothing else,
+ /// because every call site re-signs with `ldid` straight afterwards.
+ @Test(.enabled(if: JetsamFixture.hasLaunchdAndCodesign))
+ func defaultLeavesTheSignatureStale() throws {
+ let work = try JetsamFixture.workDirectory("stale-signature")
+ let target = try JetsamFixture.launchdCopy(named: "launchd", in: work)
+
+ let outcome = try CFWJetsamPatcher.patch(fileAt: target, log: nil)
+ #expect(outcome.rehashes.isEmpty)
+
+ let verify = try JetsamFixture.run(JetsamFixture.codesign, ["-v", target.path])
+ #expect(verify.status != 0, "a patch with no re-attestation must not still verify")
+ }
+
+ /// `reattest: true` has to leave a binary `codesign` accepts — one page's
+ /// slot hash, recomputed, tail slot included.
+ @Test(.enabled(if: JetsamFixture.hasLaunchdAndCodesign))
+ func reattestedBinaryVerifies() throws {
+ let work = try JetsamFixture.workDirectory("reattested")
+ let target = try JetsamFixture.launchdCopy(named: "launchd", in: work)
+
+ let outcome = try CFWJetsamPatcher.patch(fileAt: target, reattest: true, log: nil)
+ #expect(outcome.verdict == .patched)
+ #expect(outcome.rehashes.count == 1)
+
+ let rehash = try #require(outcome.rehashes.first)
+ let patched = try Data(contentsOf: target)
+ let directory = try #require(
+ CFWMachOCodeSignature.codeDirectories(in: patched)?
+ .first { $0.hashType == CFWMachOCodeSignature.hashTypeSHA256 }
+ )
+ #expect(rehash.pageIndex == outcome.gateOffset / directory.pageSize)
+
+ let verify = try JetsamFixture.run(JetsamFixture.codesign, ["-v", target.path])
+ #expect(verify.status == 0, "codesign -v rejected the re-attested binary:\n\(verify.output)")
+ }
+
+ /// The slot hash itself, against the Python's independent re-signer run
+ /// over the Python's own patched bytes. Two implementations, one number.
+ @Test(.enabled(if: JetsamFixture.hasLaunchdAndPython))
+ func slotHashMatchesThePythonResigner() throws {
+ guard JetsamFixture.exists(JetsamFixture.pythonCodeSign) else { return }
+ let work = try JetsamFixture.workDirectory("slot-hash")
+ let swiftTarget = try JetsamFixture.launchdCopy(named: "launchd.swift", in: work)
+ let pythonTarget = try JetsamFixture.launchdCopy(named: "launchd.python", in: work)
+
+ let outcome = try CFWJetsamPatcher.patch(fileAt: swiftTarget, reattest: true, log: nil)
+ #expect(outcome.verdict == .patched)
+
+ try JetsamFixture.runPythonJetsam(on: pythonTarget)
+ let resign = try JetsamFixture.run(JetsamFixture.python, [
+ "-c",
+ """
+ import sys
+ sys.path.insert(0, \(quoted(JetsamFixture.scriptsDirectory.path)))
+ from patchers.cfw_macho_codesign import reattest_modified_offsets
+ reattest_modified_offsets(
+ \(quoted(pythonTarget.path)), [\(outcome.gateOffset)], verbose=False
+ )
+ """,
+ ])
+ #expect(resign.status == 0, "reference re-signer failed:\n\(resign.output)")
+
+ let swiftBytes = try Data(contentsOf: swiftTarget)
+ let pythonBytes = try Data(contentsOf: pythonTarget)
+ #expect(JetsamFixture.firstDifference(swiftBytes, pythonBytes) == nil)
+ }
+
+ private func quoted(_ path: String) -> String {
+ "\"" + path.replacingOccurrences(of: "\\", with: "\\\\")
+ .replacingOccurrences(of: "\"", with: "\\\"") + "\""
+ }
+}
+
+// MARK: - Anchoring, without a reference
+
+@Suite("launchd jetsam guard — anchoring")
+struct CFWJetsamAnchoringTests {
+ /// Every step of the reveal lands where the disassembly says it should:
+ /// the xref is inside the function, the gate is inside the function and
+ /// before the xref, and the gate's target really does return.
+ @Test(.enabled(if: JetsamFixture.hasLaunchd))
+ func revealStepsAreSelfConsistent() throws {
+ let data = try Data(contentsOf: JetsamFixture.pristineLaunchd)
+ let image = try CFWJetsamPatcher.Image(data: data)
+ let site = try #require(try CFWJetsamPatcher.locate(in: image))
+
+ #expect(CFWJetsamPatcher.panicStringAnchors.contains(site.anchor))
+ #expect(!site.isAlreadyPatched)
+ #expect(site.functionOffset <= site.gateOffset)
+ #expect(site.gateOffset < site.xrefOffset)
+ #expect(image.isInText(site.xrefOffset))
+ #expect(image.isInText(site.returnBlockOffset))
+ #expect(CFWJetsamPatcher.isReturnBlock(site.returnBlockOffset, in: image))
+
+ // The function bound is a real prologue, not the blind fallback.
+ #expect(data.loadLE(UInt32.self, at: site.functionOffset) == ARM64.pacibspU32)
+
+ // The anchor string starts where the xref computes it to start.
+ let page = CFWJetsamPatcher.adrpPage(
+ data.loadLE(UInt32.self, at: site.xrefOffset),
+ at: image.virtualAddress(ofTextOffset: site.xrefOffset)
+ )
+ #expect(site.stringVMA & ~0xFFF == page)
+
+ // The gate is a conditional branch, and it branches to the return block.
+ let disassembler = ARM64Disassembler()
+ let gate = try #require(disassembler.disassembleOne(in: data, at: site.gateOffset))
+ #expect(CFWJetsamPatcher.conditionalBranchMnemonics.contains(gate.mnemonic))
+ #expect(CFWJetsamPatcher.branchTarget(gate) == site.returnBlockOffset)
+ }
+
+ /// The gate is the *earliest* qualifying branch in the function — any later
+ /// one leaves more of the jetsam path running.
+ @Test(.enabled(if: JetsamFixture.hasLaunchd))
+ func gateIsTheEarliestQualifyingBranch() throws {
+ let data = try Data(contentsOf: JetsamFixture.pristineLaunchd)
+ let image = try CFWJetsamPatcher.Image(data: data)
+ let site = try #require(try CFWJetsamPatcher.locate(in: image))
+
+ let disassembler = ARM64Disassembler()
+ for offset in stride(from: site.functionOffset, to: site.gateOffset, by: 4) {
+ guard let insn = disassembler.disassembleOne(in: data, at: offset),
+ CFWJetsamPatcher.conditionalBranchMnemonics.contains(insn.mnemonic)
+ || insn.mnemonic == "b",
+ let target = CFWJetsamPatcher.branchTarget(insn),
+ image.isInText(target)
+ else { continue }
+ #expect(
+ !CFWJetsamPatcher.isReturnBlock(target, in: image),
+ "0x\(String(offset, radix: 16)) qualifies and is earlier than the chosen gate"
+ )
+ }
+ }
+
+ /// Rewriting the gate is what makes the second pass a no-op, and the scan
+ /// has to see that on its own — the site it would pick on a re-run is a
+ /// different, later branch, so checking the picked site afterwards would
+ /// not catch it.
+ @Test(.enabled(if: JetsamFixture.hasLaunchd))
+ func patchedShapeIsRecognisedInPlace() throws {
+ var data = try Data(contentsOf: JetsamFixture.pristineLaunchd)
+ let outcome = try CFWJetsamPatcher.patch(&data, log: nil)
+ #expect(outcome.verdict == .patched)
+
+ let image = try CFWJetsamPatcher.Image(data: data)
+ let site = try #require(try CFWJetsamPatcher.locate(in: image))
+ #expect(site.isAlreadyPatched)
+ #expect(site.gateOffset == outcome.gateOffset)
+ #expect(site.returnBlockOffset == outcome.returnBlockOffset)
+
+ // And the later branch the reference would fall back to really is
+ // there, live, into the same return block — which is why the check has
+ // to live inside the scan.
+ let gate = try #require(CFWJetsamPatcher.findReturnGate(
+ from: site.gateOffset + 4,
+ to: site.xrefOffset,
+ in: image
+ ))
+ #expect(!gate.isUnconditional)
+ #expect(gate.offset > outcome.gateOffset)
+ #expect(gate.target == outcome.returnBlockOffset)
+ }
+}
+
+// MARK: - Decoders and encoders
+
+@Suite("launchd jetsam guard — instruction decoding")
+struct CFWJetsamDecodeTests {
+ /// `ADD Xd, Xn, #imm12, LSL #0` only — an `LSL #12` form or a
+ /// shifted-register add would make the xref land on the wrong string.
+ @Test
+ func addImmediatePredicateRejectsTheNeighbours() throws {
+ let disassembler = ARM64Disassembler()
+ // The real thing: the ADD half of the string xref, straight out of the
+ // project encoder rather than typed in.
+ let addImm = try #require(ARM64Encoder.encodeAddImm12(rd: 0, rn: 0, imm12: 0xA09))
+ let decoded = try #require(disassembler.disassembleOne(addImm, at: 0))
+ #expect(decoded.mnemonic == "add")
+ #expect(CFWJetsamPatcher.isAddImm64(addImm.loadLE(UInt32.self, at: 0)))
+
+ // And the neighbours it must not accept.
+ #expect(!CFWJetsamPatcher.isAddImm64(0x9140_0000)) // add x0, x0, #0, lsl #12
+ #expect(!CFWJetsamPatcher.isAddImm64(0x1100_0000)) // add w0, w0, #0 (32-bit)
+ #expect(!CFWJetsamPatcher.isAddImm64(0x8B08_1534)) // add x20, x9, x8, lsl #5
+ #expect(!CFWJetsamPatcher.isAddImm64(0xD100_0000)) // sub x0, x0, #0
+ }
+
+ /// `adrpPage` against Capstone, which resolves the page for us. The inputs
+ /// come from `ARM64Encoder.encodeADRP`, so nothing here is a typed-in word.
+ @Test
+ func adrpPageAgreesWithCapstone() throws {
+ let disassembler = ARM64Disassembler()
+ for (pc, target) in [
+ (UInt64(0x1_0000_FB0C), UInt64(0x1_0006_5A09)), // forward
+ (UInt64(0x1_0000_0000), UInt64(0x1_0000_0FFF)), // same page
+ (UInt64(0x1_0005_0000), UInt64(0x1_0000_1234)), // backward
+ ] {
+ let encoded = try #require(ARM64Encoder.encodeADRP(rd: 0, pc: pc, target: target))
+ let insn = try #require(disassembler.disassembleOne(encoded, at: pc))
+ let operands = try #require(insn.aarch64?.operands)
+ #expect(insn.mnemonic == "adrp")
+ #expect(operands.count >= 2 && operands[1].type == AARCH64_OP_IMM)
+ let word = encoded.loadLE(UInt32.self, at: 0)
+ #expect(CFWJetsamPatcher.adrpPage(word, at: pc) == UInt64(operands[1].imm))
+ #expect(CFWJetsamPatcher.adrpPage(word, at: pc) == target & ~0xFFF)
+ }
+ }
+
+ /// The replacement is `ARM64Encoder`'s, and it decodes back to a `b` at the
+ /// intended target — never a hand-written instruction word.
+ @Test
+ func replacementBranchRoundTrips() throws {
+ let disassembler = ARM64Disassembler()
+ for (site, target) in [(0xFA98, 0xFAEC), (0x1000, 0x800), (0x40, 0x40)] {
+ let encoded = try #require(ARM64Encoder.encodeB(from: site, to: target))
+ let insn = try #require(disassembler.disassembleOne(encoded, at: UInt64(site)))
+ #expect(insn.mnemonic == "b")
+ #expect(CFWJetsamPatcher.branchTarget(insn) == target)
+ }
+ }
+
+ /// The return-block probe rests entirely on two questions — "does this
+ /// return?" and "does control leave here?" — and both are answered from
+ /// Capstone's instruction groups. Pinned against real decodes, because a
+ /// mnemonic prefix gets each of the last three rows below wrong: `brk` is
+ /// not a branch, and a conditional branch falls through.
+ @Test
+ func blockBoundariesComeFromCapstoneGroups() throws {
+ let disassembler = ARM64Disassembler()
+ func decode(_ bytes: Data) throws -> Instruction {
+ try #require(disassembler.disassembleOne(bytes, at: 0))
+ }
+
+ // Returns, from the project's own pre-encoded constants.
+ for bytes in [ARM64.ret, ARM64.retaa, ARM64.retab] {
+ let insn = try decode(bytes)
+ #expect(CFWJetsamPatcher.isReturn(insn))
+ }
+
+ // Control leaves: an unconditional relative jump and a relative call,
+ // both straight out of `ARM64Encoder`.
+ for bytes in [
+ try #require(ARM64Encoder.encodeB(from: 0, to: 8)),
+ try #require(ARM64Encoder.encodeBL(from: 0, to: 8)),
+ ] {
+ let insn = try decode(bytes)
+ #expect(CFWJetsamPatcher.leavesBlock(insn))
+ #expect(!CFWJetsamPatcher.isReturn(insn))
+ }
+
+ // The register-indirect forms, and the breakpoint that a `hasPrefix("br")`
+ // test would have mistaken for one. No encoder writes these — no patch
+ // emits them — so the words come from the ISA field layout and every
+ // claim about them is checked against Capstone's decode.
+ let indirect: [(UInt32, String, Bool)] = [
+ (0xD61F_0000, "br", true), // br x0
+ (0xD63F_0000, "blr", true), // blr x0
+ (0xD420_0000, "brk", false), // brk #0 — an exception, not a branch
+ ]
+ for (word, mnemonic, ends) in indirect {
+ let insn = try decode(ARM64.encodeU32(word))
+ #expect(insn.mnemonic == mnemonic)
+ #expect(CFWJetsamPatcher.leavesBlock(insn) == ends)
+ #expect(!CFWJetsamPatcher.isReturn(insn))
+ }
+
+ // Conditional branches fall through, so they end nothing — this is what
+ // lets a `b.cond` sit inside the return block being probed.
+ let conditional: [UInt32] = [
+ 0x5400_0000 | (2 << 5), // b.eq #8
+ 0x3400_0000 | (2 << 5), // cbz w0, #8
+ 0x3600_0000 | (2 << 5), // tbz w0, #0, #8
+ ]
+ for word in conditional {
+ let insn = try decode(ARM64.encodeU32(word))
+ #expect(CFWJetsamPatcher.conditionalBranchMnemonics.contains(insn.mnemonic))
+ #expect(!CFWJetsamPatcher.leavesBlock(insn))
+ #expect(!CFWJetsamPatcher.isReturn(insn))
+ }
+ }
+
+ /// `cbz`/`tbz` put the target last; reading the last immediate is what
+ /// keeps one code path covering all of them.
+ @Test
+ func branchTargetReadsTheLastImmediate() throws {
+ let disassembler = ARM64Disassembler()
+
+ // tbz w8, #1, #8 — three operands, target last, from the encoder.
+ let tbz = try #require(ARM64Encoder.encodeTestBitBranch(
+ nonzero: false, register: 8, bit: 1, from: 0, to: 8
+ ))
+ let tbzInsn = try #require(disassembler.disassembleOne(tbz, at: 0))
+ #expect(tbzInsn.mnemonic == "tbz")
+ #expect(CFWJetsamPatcher.branchTarget(tbzInsn) == 8)
+
+ // cbz w0, #8 and b.eq #8 — two and one operand. Neither has an encoder
+ // in `ARM64Encoder` (no patch writes one), so the words are built here
+ // from the ISA field layout and checked against Capstone's decode.
+ let cbz: UInt32 = 0x3400_0000 | (2 << 5) // imm19 = 8 / 4
+ let beq: UInt32 = 0x5400_0000 | (2 << 5) // imm19 = 8 / 4, cond = EQ
+ for word in [cbz, beq] {
+ let insn = try #require(disassembler.disassembleOne(ARM64.encodeU32(word), at: 0))
+ #expect(CFWJetsamPatcher.conditionalBranchMnemonics.contains(insn.mnemonic))
+ #expect(CFWJetsamPatcher.branchTarget(insn) == 8)
+ }
+ }
+
+ /// A substring anchor has to widen to the whole C string, because that is
+ /// what an ADRP+ADD points at.
+ @Test
+ func cStringStartWidensToTheWholeString() throws {
+ var bytes = Data("first\u{0}jetsam property category (%s) is not initialized\u{0}".utf8)
+ var hit = try #require(bytes.range(of: Data("property".utf8))?.lowerBound)
+ #expect(CFWJetsamPatcher.cStringStart(in: bytes, containing: hit, sectionStart: 0) == 6)
+
+ // A string that starts at the section's first byte has no NUL in front.
+ bytes = Data("jetsam property category\u{0}".utf8)
+ hit = try #require(bytes.range(of: Data("property".utf8))?.lowerBound)
+ #expect(CFWJetsamPatcher.cStringStart(in: bytes, containing: hit, sectionStart: 0) == 0)
+ }
+}
diff --git a/tests/FirmwarePatcherTests/CFWMobileactivationdTests.swift b/tests/FirmwarePatcherTests/CFWMobileactivationdTests.swift
new file mode 100644
index 00000000..66aa4da7
--- /dev/null
+++ b/tests/FirmwarePatcherTests/CFWMobileactivationdTests.swift
@@ -0,0 +1,393 @@
+// CFWMobileactivationdTests.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. Every comparison is gated on the reference still being present, so the
+// suite skips rather than fails once P1.5 deletes the Python.
+//
+// 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 Capstone
+@testable import FirmwarePatcher
+import Foundation
+import Testing
+
+// 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 python = repositoryRoot.appending(path: ".venv/bin/python3")
+ static let cfwPy = repositoryRoot.appending(path: "scripts/patchers/cfw.py")
+ 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: "CFWMobileactivationdTests")
+ }
+ return FileManager.default.temporaryDirectory.appending(path: "CFWMobileactivationdTests")
+ }()
+
+ 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 hasPythonReference: Bool { hasPristine && exists(python) && exists(cfwPy) }
+ static var hasCodesign: Bool { hasPristine && exists(codesign) }
+
+ /// 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))
+ }
+
+ /// Run the Python patcher over `file`, in place.
+ @discardableResult
+ static func runPythonPatcher(on file: URL) throws -> String {
+ let result = try run(python, [cfwPy.path, "patch-mobileactivationd", file.path])
+ #expect(result.status == 0, "cfw.py patch-mobileactivationd failed: \(result.output)")
+ return result.output
+ }
+
+ /// Re-attest `offsets` in `file` with the Python code-signature module —
+ /// the step `cfw_patch_mobileactivationd.py` leaves to the `ldid_sign` that
+ /// follows it in `cfw_install.sh`.
+ @discardableResult
+ static func runPythonReattest(on file: URL, offsets: [Int]) throws -> String {
+ let script = """
+ import sys
+ sys.path.insert(0, "scripts")
+ from patchers.cfw_macho_codesign import reattest_modified_offsets
+ reattest_modified_offsets(sys.argv[1], [int(a, 0) for a in sys.argv[2:]])
+ """
+ let result = try run(python, ["-c", script, file.path] + offsets.map { "0x" + String($0, radix: 16) })
+ #expect(result.status == 0, "cfw_macho_codesign failed: \(result.output)")
+ return result.output
+ }
+}
+
+// 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 the Python, and the run-it-twice check, can be driven
+/// from a shell over files a human picked — 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 the
+/// Python's bytes exactly.
+@Suite("mobileactivationd should_hactivate — shell runner")
+struct CFWMobileactivationdRunnerTests {
+ @Test(.enabled(if: ProcessInfo.processInfo.environment["VPHONE_PATCH_FILE"] != nil))
+ func runPatcherFromEnvironment() throws {
+ let environment = ProcessInfo.processInfo.environment
+ let path = try #require(environment["VPHONE_PATCH_FILE"])
+ let resign = environment["VPHONE_PATCH_RESIGN"] != "0"
+
+ let report = try CFWMobileactivationd.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 CFWMobileactivationdAnchorTests {
+ /// 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 bothAnchorsResolveAndAgree() throws {
+ let data = try Data(contentsOf: MobileactivationdFixture.pristine)
+ let segments = MachOParser.parseSegments(from: data)
+
+ let bySymbol = try #require(
+ CFWMobileactivationd.symbolVirtualAddress(in: data),
+ "LC_SYMTAB should carry -[DeviceType should_hactivate]"
+ )
+ let byMetadata = try #require(
+ CFWMobileactivationd.objcMetadataVirtualAddress(in: data, segments: segments),
+ "the ObjC method lists should carry the same IMP"
+ )
+ #expect(bySymbol == byMetadata)
+
+ let anchor = try CFWMobileactivationd.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 the Python does — lands inside the ivar's
+ /// name, finds no selref for it, and gives up. The NUL-preceded match finds
+ /// the real selector instead.
+ @Test(.enabled(if: MobileactivationdFixture.hasPristine))
+ func selectorLookupSkipsTheIvarName() throws {
+ let data = try Data(contentsOf: MobileactivationdFixture.pristine)
+ let sections = MachOParser.parseSections(from: data)
+ let selectorVA = try #require(
+ CFWMobileactivationd.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")
+
+ // The naive search the Python performs finds an earlier, wrong offset on
+ // this binary — so this is not an assertion that passes either way.
+ let needle = Data(CFWMobileactivationd.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 missingMethodThrows() throws {
+ let data = try Data(contentsOf: MobileactivationdFixture.launchd)
+ #expect(throws: PatcherError.self) {
+ try CFWMobileactivationd.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 replacementIsMovX0OneThenRet() throws {
+ let bytes = try CFWMobileactivationd.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].aarch64?.operands)
+ #expect(operands.count == 2)
+ #expect(operands[1].type == AARCH64_OP_IMM)
+ #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 touchedOffsetsCoverBothWords() throws {
+ let anchor = CFWMobileactivationd.Anchor(
+ virtualAddress: 0x1_0000_0FFC,
+ fileOffset: 0xFFC,
+ source: .symbolTable,
+ section: "__TEXT,__text"
+ )
+ let bytes = try CFWMobileactivationd.replacementBytes()
+ let offsets = CFWMobileactivationd.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 Python
+
+@Suite("mobileactivationd should_hactivate — parity and idempotence")
+struct CFWMobileactivationdParityTests {
+ /// Bar 1: identical bytes out of identical bytes in, against the
+ /// implementation being replaced.
+ ///
+ /// `resign: false` because the Python patcher does not re-sign — the
+ /// `ldid_sign` in `cfw_install.sh` does — so this compares like with like.
+ @Test(.enabled(if: MobileactivationdFixture.hasPythonReference))
+ func matchesThePythonByteForByte() throws {
+ let swiftFile = try MobileactivationdFixture.copyOfPristine(named: "swift.bin")
+ let pythonFile = try MobileactivationdFixture.copyOfPristine(named: "python.bin")
+
+ let report = try CFWMobileactivationd.patch(fileAt: swiftFile, resign: false, log: nil)
+ try MobileactivationdFixture.runPythonPatcher(on: pythonFile)
+
+ #expect(report.outcome == .patched)
+ #expect(report.sitesWritten == 1)
+ #expect(report.slotRehashes.isEmpty, "resign: false must not touch the signature")
+
+ let swiftBytes = try Data(contentsOf: swiftFile)
+ let pythonBytes = try Data(contentsOf: pythonFile)
+ #expect(swiftBytes == pythonBytes, "Swift and Python output must be byte-identical")
+
+ // And the one site they both changed is the one this patch claims.
+ let record = try #require(report.record)
+ let pristine = try Data(contentsOf: MobileactivationdFixture.pristine)
+ let differing = (0 ..< pristine.count).filter { pythonBytes[$0] != pristine[$0] }
+ #expect(differing.allSatisfy { record.fileOffset ..< record.fileOffset + 8 ~= $0 })
+ #expect(record.patchID == "mobileactivationd.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 Python'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.hasPythonReference && MobileactivationdFixture.hasCodesign))
+ func reattestedOutputMatchesThePythonAndVerifies() throws {
+ let swiftFile = try MobileactivationdFixture.copyOfPristine(named: "swift-resigned.bin")
+ let pythonFile = try MobileactivationdFixture.copyOfPristine(named: "python-resigned.bin")
+
+ let report = try CFWMobileactivationd.patch(fileAt: swiftFile, resign: true, log: nil)
+ let rehash = try #require(report.slotRehashes.first)
+ #expect(report.slotRehashes.count == 1)
+
+ try MobileactivationdFixture.runPythonPatcher(on: pythonFile)
+ try MobileactivationdFixture.runPythonReattest(
+ on: pythonFile,
+ offsets: CFWMobileactivationd.touchedOffsets(report.anchor, ARM64.movX0_1 + ARM64.ret)
+ )
+
+ let swiftBytes = try Data(contentsOf: swiftFile)
+ let pythonBytes = try Data(contentsOf: pythonFile)
+ #expect(swiftBytes == pythonBytes, "re-attested output must match the Python's")
+
+ // The slot hash itself, not just the file: read it back out of both.
+ let slot = rehash.hashFileOffset ..< rehash.hashFileOffset + rehash.after.count
+ #expect(swiftBytes[slot] == rehash.after)
+ #expect(pythonBytes[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 CFWMobileactivationd.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 secondRunChangesNothing() throws {
+ let file = try MobileactivationdFixture.copyOfPristine(named: "swift-idempotent.bin")
+
+ let first = try CFWMobileactivationd.patch(fileAt: file, log: nil)
+ #expect(first.outcome == .patched)
+ let afterFirst = try Data(contentsOf: file)
+
+ let second = try CFWMobileactivationd.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 CFWMobileactivationd.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 leaves behind —
+ /// 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 rerunRepairsAStaleSlot() throws {
+ let file = try MobileactivationdFixture.copyOfPristine(named: "swift-stale-slot.bin")
+ try CFWMobileactivationd.patch(fileAt: file, resign: false, log: nil)
+
+ let repaired = try CFWMobileactivationd.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 dryRunWritesNothing() throws {
+ let file = try MobileactivationdFixture.copyOfPristine(named: "swift-dry-run.bin")
+ let before = try Data(contentsOf: file)
+
+ let report = try CFWMobileactivationd.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)
+ }
+}
diff --git a/tests/FirmwarePatcherTests/CFWSeputilTests.swift b/tests/FirmwarePatcherTests/CFWSeputilTests.swift
new file mode 100644
index 00000000..48af6c23
--- /dev/null
+++ b/tests/FirmwarePatcherTests/CFWSeputilTests.swift
@@ -0,0 +1,601 @@
+// CFWSeputilTests.swift — Parity cross-checks for `CFWSeputil`.
+//
+// Two independent references, and every claim below is measured against one of
+// them rather than against a number written down by hand:
+//
+// * `scripts/patchers/cfw_patch_seputil.py`, driven through the exact CLI
+// `scripts/cfw_install.sh` calls — `cfw.py patch-seputil <binary>`. The
+// Swift patcher run with `reattest: false` must produce that file byte for
+// byte, and run with re-attestation on it must equal the Python's output
+// put through the Python's own re-attester
+// (`cfw_macho_codesign.reattest_modified_offsets`). The second comparison
+// is what proves the slot hashes agree: they are compared as bytes in the
+// file, not as values this module reported about itself.
+// * `/usr/bin/codesign -v`, which for a standalone Mach-O is a real second
+// opinion on whether the signature still covers the file. The test asserts
+// both directions — the re-attested binary verifies and the one that
+// matches the Python does not — so a `codesign` that passed everything
+// would fail this suite instead of quietly blessing it.
+//
+// The fixture is the real 24A435 / iPhone17,3 `seputil`. Point
+// `VPHONE_MACHO_PRISTINE` at a directory of pristine Mach-O binaries or leave
+// the default `ipsws/ref_extract/macho_pristine` in place.
+//
+// Without it these FAIL, following `DSCFoundationTests`: a `guard … else
+// { return }` is reported by Swift Testing as a pass, so a green run on a
+// machine with no fixture would be indistinguishable from a green run that
+// proved something. Set `VPHONE_MACHO_FIXTURE_OPTIONAL=1` to turn that failure
+// into a visible skip.
+//
+// Nothing here writes anywhere under `ipsws/ref_extract/`: that tree is the
+// pristine reference the whole suite compares against. Clones land in
+// `ipsws/scratch_cfwseputil/`, on the same filesystem, so `cp -c` is a
+// `clonefile(2)`.
+
+import CryptoKit
+@testable import FirmwarePatcher
+import Foundation
+import Testing
+
+// MARK: - Fixture discovery
+
+private enum SeputilFixture {
+ static let repoRoot = URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+
+ static let binaryName = "seputil"
+
+ /// The read-only reference binary.
+ static var pristine: URL? {
+ let directory = ProcessInfo.processInfo.environment["VPHONE_MACHO_PRISTINE"]
+ .map { URL(fileURLWithPath: $0) }
+ ?? repoRoot.appendingPathComponent("ipsws/ref_extract/macho_pristine")
+ let binary = directory.appendingPathComponent(binaryName)
+ return FileManager.default.fileExists(atPath: binary.path) ? binary : nil
+ }
+
+ /// Opt-out for a machine that does not carry the extracted IPSW.
+ static var isOptional: Bool {
+ ProcessInfo.processInfo.environment["VPHONE_MACHO_FIXTURE_OPTIONAL"] == "1"
+ }
+
+ /// The suite runs unless the binary is absent *and* the caller opted out.
+ static var runs: Bool { pristine != nil || !isOptional }
+
+ static let missing: Comment = """
+ the real 24A435 iPhone17,3 seputil is required — put it at \
+ ipsws/ref_extract/macho_pristine/seputil, point VPHONE_MACHO_PRISTINE at \
+ the directory holding it, or set VPHONE_MACHO_FIXTURE_OPTIONAL=1 to skip \
+ these tests instead of failing
+ """
+
+ static let skipReason: Comment =
+ "VPHONE_MACHO_FIXTURE_OPTIONAL=1 and no macho_pristine/seputil fixture present"
+
+ static let venvMissing: Comment = """
+ the project venv is required: these tests are a comparison against \
+ scripts/patchers/cfw_patch_seputil.py, and without it there is nothing to \
+ compare against — run `make setup_venv`
+ """
+
+ /// Where clones are made. Same filesystem as the repo, and deliberately
+ /// *not* under `ipsws/ref_extract/`.
+ static var scratchRoot: URL {
+ repoRoot.appendingPathComponent("ipsws/scratch_cfwseputil")
+ }
+
+ static var python: URL? {
+ let url = repoRoot.appendingPathComponent(".venv/bin/python3")
+ return FileManager.default.fileExists(atPath: url.path) ? url : nil
+ }
+
+ static var codesign: URL? {
+ let url = URL(fileURLWithPath: "/usr/bin/codesign")
+ return FileManager.default.fileExists(atPath: url.path) ? url : nil
+ }
+
+ /// A private clone of the pristine binary the caller may write to.
+ static func clone(named name: String) throws -> URL {
+ guard let pristine else { throw CocoaError(.fileNoSuchFile) }
+ try FileManager.default.createDirectory(
+ at: scratchRoot,
+ withIntermediateDirectories: true
+ )
+ let destination = scratchRoot.appendingPathComponent(name)
+ try? FileManager.default.removeItem(at: destination)
+
+ var result = try Subprocess.run(
+ executable: URL(fileURLWithPath: "/bin/cp"),
+ arguments: ["-c", pristine.path, destination.path]
+ )
+ if result.status != 0 {
+ // A fixture on another volume cannot be cloned. Copying is slower
+ // but correct, and a refusal here would look like a patch bug.
+ result = try Subprocess.run(
+ executable: URL(fileURLWithPath: "/bin/cp"),
+ arguments: [pristine.path, destination.path]
+ )
+ }
+ guard result.status == 0 else { throw CocoaError(.fileWriteUnknown) }
+ return destination
+ }
+
+ /// Discard clones, and the scratch root with them once the last one is
+ /// gone, so a test run leaves the working tree as it found it.
+ static func discard(_ clones: URL...) {
+ for clone in clones { try? FileManager.default.removeItem(at: clone) }
+ let remaining = (try? FileManager.default
+ .contentsOfDirectory(atPath: scratchRoot.path)) ?? []
+ if remaining.isEmpty {
+ try? FileManager.default.removeItem(at: scratchRoot)
+ }
+ }
+}
+
+// MARK: - Subprocess helper
+
+private enum Subprocess {
+ struct Result {
+ let status: Int32
+ let stdout: String
+ let stderr: String
+ }
+
+ @discardableResult
+ static func run(executable: URL, arguments: [String]) throws -> Result {
+ let process = Process()
+ process.executableURL = executable
+ process.arguments = arguments
+ let out = Pipe()
+ let err = Pipe()
+ process.standardOutput = out
+ process.standardError = err
+ try process.run()
+ // Drain before waiting, or a full pipe buffer deadlocks the child.
+ let outData = out.fileHandleForReading.readDataToEndOfFile()
+ let errData = err.fileHandleForReading.readDataToEndOfFile()
+ process.waitUntilExit()
+ return Result(
+ status: process.terminationStatus,
+ stdout: String(decoding: outData, as: UTF8.self),
+ stderr: String(decoding: errData, as: UTF8.self)
+ )
+ }
+}
+
+// MARK: - The reference Python, driven through its real CLI
+
+private enum PythonReference {
+ /// `cfw.py patch-seputil <binary>` — what `cfw_install.sh` runs.
+ @discardableResult
+ static func patch(_ binary: URL) throws -> String {
+ let python = try #require(SeputilFixture.python, SeputilFixture.venvMissing)
+ let result = try Subprocess.run(executable: python, arguments: [
+ SeputilFixture.repoRoot.appendingPathComponent("scripts/patchers/cfw.py").path,
+ "patch-seputil",
+ binary.path,
+ ])
+ guard result.status == 0 else {
+ Issue.record("cfw.py patch-seputil failed: \(result.stdout)\(result.stderr)")
+ throw CocoaError(.fileWriteUnknown)
+ }
+ return result.stdout
+ }
+
+ /// `cfw_macho_codesign.reattest_modified_offsets` — the independent
+ /// re-attester, so the slot hashes this suite compares against are the
+ /// Python's own and not a second copy of the Swift maths.
+ static func reattest(_ binary: URL, offsets: [Int]) throws {
+ let python = try #require(SeputilFixture.python, SeputilFixture.venvMissing)
+ let script = """
+ import sys
+ sys.path.insert(0, "scripts/patchers")
+ import cfw_macho_codesign as ref
+ ref.reattest_modified_offsets(sys.argv[1], [int(a) for a in sys.argv[2:]], verbose=False)
+ """
+ let process = Process()
+ process.executableURL = python
+ process.arguments = ["-c", script, binary.path] + offsets.map(String.init)
+ process.currentDirectoryURL = SeputilFixture.repoRoot
+ let pipe = Pipe()
+ process.standardOutput = pipe
+ process.standardError = pipe
+ try process.run()
+ let output = pipe.fileHandleForReading.readDataToEndOfFile()
+ process.waitUntilExit()
+ try #require(
+ process.terminationStatus == 0,
+ "reference re-attester failed: \(String(decoding: output, as: UTF8.self))"
+ )
+ }
+}
+
+// MARK: - Parity against the reference implementations
+
+@Suite("seputil gigalocker name", .enabled(if: SeputilFixture.runs, SeputilFixture.skipReason))
+struct CFWSeputilParityTests {
+ /// The plan's P1.2 gate: same input, same bytes out.
+ ///
+ /// Run with `reattest: false`, which is the reference's own behaviour —
+ /// `cfw_install.sh` re-signs with `ldid` right after, so the Python leaves
+ /// the signature stale.
+ @Test func matchesTheReferencePatcherByteForByte() throws {
+ let pristine = try #require(SeputilFixture.pristine, SeputilFixture.missing)
+ let swiftFile = try SeputilFixture.clone(named: "swift-plain")
+ let pythonFile = try SeputilFixture.clone(named: "python-plain")
+ defer { SeputilFixture.discard(swiftFile, pythonFile) }
+
+ let outcome = try CFWSeputil.patch(fileAt: swiftFile, reattest: false, log: nil)
+ try PythonReference.patch(pythonFile)
+
+ #expect(outcome.verdict == .patched)
+ #expect(
+ try Data(contentsOf: swiftFile) == (try Data(contentsOf: pythonFile)),
+ "Swift and Python must produce the same seputil, byte for byte"
+ )
+
+ // And the comparison is not two copies of the input: both moved.
+ #expect(try Data(contentsOf: swiftFile) != (try Data(contentsOf: pristine)))
+ }
+
+ /// The same for the whole pipeline, re-attestation included. The Python
+ /// has no re-attesting seputil patcher, so the reference side is composed
+ /// from the two Python modules the install script composes at runtime.
+ ///
+ /// This is the slot-hash comparison: the hashes are compared where they
+ /// live, in the file, against hashes the reference implementation computed.
+ @Test func matchesTheReferencePlusItsOwnReattester() throws {
+ let swiftFile = try SeputilFixture.clone(named: "swift-full")
+ let pythonFile = try SeputilFixture.clone(named: "python-full")
+ defer { SeputilFixture.discard(swiftFile, pythonFile) }
+
+ let outcome = try CFWSeputil.patch(fileAt: swiftFile, log: nil)
+ try PythonReference.patch(pythonFile)
+ try PythonReference.reattest(pythonFile, offsets: outcome.site.modifiedOffsets)
+
+ #expect(outcome.rehashes.count == 1, "one page was dirtied, so one slot is rewritten")
+ #expect(
+ try Data(contentsOf: swiftFile) == (try Data(contentsOf: pythonFile)),
+ "the re-attested slot hash must be the one the reference computes"
+ )
+ }
+
+ /// `codesign -v`, in both directions. The re-attested binary verifies; the
+ /// one that reproduces the Python's bytes does not, which is why
+ /// `cfw_install.sh` has to run `ldid_sign` after the Python.
+ @Test func reattestationIsWhatMakesTheBinaryVerify() throws {
+ let codesign = try #require(SeputilFixture.codesign)
+ let pristine = try #require(SeputilFixture.pristine, SeputilFixture.missing)
+ let reattested = try SeputilFixture.clone(named: "swift-verify")
+ let stale = try SeputilFixture.clone(named: "swift-stale")
+ defer { SeputilFixture.discard(reattested, stale) }
+
+ // The fixture itself has to verify, or the check below measures nothing.
+ let before = try Subprocess.run(executable: codesign, arguments: ["-v", pristine.path])
+ try #require(before.status == 0, "the pristine fixture must verify: \(before.stderr)")
+
+ try CFWSeputil.patch(fileAt: reattested, log: nil)
+ try CFWSeputil.patch(fileAt: stale, reattest: false, log: nil)
+
+ let good = try Subprocess.run(executable: codesign, arguments: ["-v", reattested.path])
+ let bad = try Subprocess.run(executable: codesign, arguments: ["-v", stale.path])
+ #expect(good.status == 0, "re-attested binary must verify: \(good.stderr)")
+ #expect(bad.status != 0, "a stale slot hash must be caught, or codesign proves nothing")
+ }
+
+ // MARK: Idempotence
+
+ /// Running twice is a clean no-op — not an error, not a second rewrite.
+ ///
+ /// The shape the second run has to recognise is the one the first run
+ /// wrote: the literal no longer reads `%s/%s.gl`, so a patcher that only
+ /// knows the pristine spelling fails here instead of reporting "already
+ /// patched". That is the bug `8eb6c8b` fixed for two DSC gates.
+ @Test func aSecondRunChangesNothing() throws {
+ let file = try SeputilFixture.clone(named: "twice")
+ defer { SeputilFixture.discard(file) }
+
+ let first = try CFWSeputil.patch(fileAt: file, log: nil)
+ let afterFirst = try Data(contentsOf: file)
+
+ let second = try CFWSeputil.patch(fileAt: file, log: nil)
+ let afterSecond = try Data(contentsOf: file)
+
+ #expect(first.verdict == .patched)
+ #expect(second.verdict == .alreadyPatched)
+ #expect(second.record == nil)
+ #expect(second.rehashes.isEmpty)
+ #expect(second.sitesWritten == 0)
+ #expect(afterSecond == afterFirst, "the second run must not touch a byte")
+
+ // The second run still found the same site, by its patched spelling.
+ #expect(second.site.fieldOffset == first.site.fieldOffset)
+ #expect(second.site.isPristine == false)
+ #expect(second.references == first.references)
+ }
+
+ /// A dry run reports the site and leaves the file alone.
+ @Test func aDryRunWritesNothing() throws {
+ let file = try SeputilFixture.clone(named: "dry")
+ defer { SeputilFixture.discard(file) }
+ let before = try Data(contentsOf: file)
+
+ let outcome = try CFWSeputil.patch(fileAt: file, dryRun: true, log: nil)
+ #expect(outcome.verdict == .wouldPatch)
+ #expect(outcome.record != nil)
+ #expect(outcome.rehashes.isEmpty)
+ #expect(try Data(contentsOf: file) == before)
+ }
+
+ // MARK: The anchor
+
+ /// What the patcher anchored on, stated in full: the literal, the field
+ /// inside it, and the instruction that materialises its address.
+ @Test func anchorsOnTheReferencedGigalockerLiteral() throws {
+ let file = try SeputilFixture.clone(named: "anchor")
+ defer { SeputilFixture.discard(file) }
+ let data = try Data(contentsOf: file)
+
+ let (cstring, text) = try CFWSeputil.sections(in: data)
+ let site = try CFWSeputil.findSite(in: data, cstring: cstring)
+
+ #expect(site.literal == "%s/%s.gl")
+ #expect(site.isPristine)
+ // The field is the one after the literal's last separator, so it lands
+ // on the *uuid*, not the mountpoint: patching the mountpoint would send
+ // every gigalocker lookup to a path that does not exist.
+ #expect(site.fieldOffset == site.literalOffset + 3)
+ #expect(data[site.fieldOffset ..< site.fieldOffset + 2] == Data("%s".utf8))
+
+ // VA and file offset describe the same byte.
+ let segments = MachOParser.parseSegments(from: data)
+ #expect(MachOParser.vaToFileOffset(site.fieldVMA, segments: segments) == site.fieldOffset)
+ #expect(site.literalVMA == cstring.address + UInt64(site.literalOffset - Int(cstring.fileOffset)))
+
+ // And something in __text actually forms that address.
+ let references = CFWSeputil.references(to: site.literalVMA, in: data, text: text)
+ #expect(!references.isEmpty)
+ for reference in references {
+ #expect(reference >= text.address && reference < text.address + text.size)
+ }
+ }
+
+ /// The record carries the reference's own `patchID`, `component` and
+ /// wording, so a captured reference JSON compares field for field.
+ @Test func recordsTheSiteTheWayTheReferenceDoes() throws {
+ let file = try SeputilFixture.clone(named: "record")
+ defer { SeputilFixture.discard(file) }
+
+ let outcome = try CFWSeputil.patch(fileAt: file, dryRun: true, log: nil)
+ let record = try #require(outcome.record)
+ #expect(record.patchID == "seputil.gigalocker_uuid")
+ #expect(record.component == "seputil")
+ #expect(record.fileOffset == outcome.site.fieldOffset)
+ #expect(record.virtualAddress == outcome.site.fieldVMA)
+ #expect(record.originalBytes == Data("%s".utf8))
+ #expect(record.patchedBytes == Data("AA".utf8))
+ #expect(record.patchedBytes.count == 2)
+ #expect(record.patchDescription == "gigalocker path format '/%s.gl' -> '/AA.gl'")
+ }
+
+ // MARK: Re-attestation reach
+
+ /// Exactly the dirtied page is re-hashed, and the short tail slot — which
+ /// this fixture has, and which is the known regression in independent
+ /// Mach-O re-signing — is left alone because nothing was written in it.
+ @Test func reattestationTouchesOnlyTheDirtiedPage() throws {
+ let file = try SeputilFixture.clone(named: "pages")
+ defer { SeputilFixture.discard(file) }
+ let before = try Data(contentsOf: file)
+
+ let directory = try #require(CFWMachOCodeSignature.codeDirectories(in: before)?.first)
+ try #require(
+ directory.codeLimit % directory.pageSize != 0,
+ "this fixture is supposed to have a short tail slot"
+ )
+
+ let outcome = try CFWSeputil.patch(fileAt: file, log: nil)
+ let rehash = try #require(outcome.rehashes.first)
+ #expect(outcome.rehashes.count == 1)
+ #expect(rehash.pageIndex == outcome.site.fieldOffset / directory.pageSize)
+ #expect(!rehash.isTailSlot)
+ #expect(rehash.hashedLength == directory.pageSize)
+
+ // The slot on disk holds the SHA-256 of the page as it now reads —
+ // computed here from the file, not taken from what the patcher said.
+ let after = try Data(contentsOf: file)
+ let range = try #require(directory.slotRange(rehash.pageIndex))
+ let expected = Data(SHA256.hash(data: after[range]))
+ #expect(after[rehash.hashFileOffset ..< rehash.hashFileOffset + directory.hashSize] == expected)
+
+ // Every other slot is byte-identical to the pristine binary.
+ let table = directory.offset + directory.hashOffset
+ let tableEnd = table + directory.codeSlotCount * directory.hashSize
+ let slot = rehash.hashFileOffset ..< rehash.hashFileOffset + directory.hashSize
+ #expect(after[table ..< slot.lowerBound] == before[table ..< slot.lowerBound])
+ #expect(after[slot.upperBound ..< tableEnd] == before[slot.upperBound ..< tableEnd])
+ }
+
+ // MARK: Refusals
+
+ /// A literal nothing refers to is not the gigalocker path.
+ ///
+ /// The reference takes the first `"/%s.gl"` it finds anywhere in the file
+ /// and patches it. Here the `adrp`/`add` that materialises the literal is
+ /// erased first, and the patcher has to stop rather than rewrite bytes no
+ /// code reads.
+ @Test func refusesALiteralNothingReferences() throws {
+ let file = try SeputilFixture.clone(named: "unreferenced")
+ defer { SeputilFixture.discard(file) }
+ var data = try Data(contentsOf: file)
+
+ let (cstring, text) = try CFWSeputil.sections(in: data)
+ let site = try CFWSeputil.findSite(in: data, cstring: cstring)
+ let references = CFWSeputil.references(to: site.literalVMA, in: data, text: text)
+ try #require(!references.isEmpty)
+
+ let segments = MachOParser.parseSegments(from: data)
+ for reference in references {
+ let offset = try #require(MachOParser.vaToFileOffset(reference, segments: segments))
+ data.replaceSubrange(offset ..< offset + ARM64.nop.count, with: ARM64.nop)
+ }
+ #expect(CFWSeputil.references(to: site.literalVMA, in: data, text: text).isEmpty)
+
+ #expect(throws: PatcherError.self) {
+ try CFWSeputil.patch(&data, log: nil)
+ }
+ }
+}
+
+// MARK: - Shape rules, with no fixture
+
+@Suite("seputil anchor shape")
+struct CFWSeputilShapeTests {
+ /// A synthetic `__cstring` is enough to pin the field rule, and it is the
+ /// only way to present cases the real binary does not contain.
+ private func section(at offset: UInt32, size: Int, address: UInt64) -> MachOSectionInfo {
+ MachOSectionInfo(
+ segmentName: "__TEXT",
+ sectionName: "__cstring",
+ address: address,
+ size: UInt64(size),
+ fileOffset: offset
+ )
+ }
+
+ private func cstrings(_ literals: [String], padding: Int = 16) -> Data {
+ var data = Data(repeating: 0, count: padding)
+ for literal in literals {
+ data.append(Data(literal.utf8))
+ data.append(0)
+ }
+ data.append(Data(repeating: 0, count: padding))
+ return data
+ }
+
+ @Test func readsTheFieldAfterTheLastSeparator() {
+ // The mountpoint field is left alone; the one after the last "/" moves.
+ let field = try? #require(CFWSeputil.fileField(of: Array("%s/%s.gl".utf8)))
+ #expect(field == 3 ..< 5)
+ #expect(CFWSeputil.fileField(of: Array("/mnt7/%s.gl".utf8)) == 6 ..< 8)
+ // No separator, wrong suffix, or a field that is not two bytes wide:
+ // none of these is the site this patch knows how to rewrite.
+ #expect(CFWSeputil.fileField(of: Array("%s.gl".utf8)) == nil)
+ #expect(CFWSeputil.fileField(of: Array("%s/%s.plist".utf8)) == nil)
+ #expect(CFWSeputil.fileField(of: Array("%s/%llu.gl".utf8)) == nil)
+ #expect(CFWSeputil.fileField(of: Array(".gl".utf8)) == nil)
+ }
+
+ @Test func classifiesOnlyTheTwoSpellingsItWrites() {
+ #expect(CFWSeputil.pristineness(of: ArraySlice("%s".utf8)) == true)
+ #expect(CFWSeputil.pristineness(of: ArraySlice("AA".utf8)) == false)
+ #expect(CFWSeputil.pristineness(of: ArraySlice("BB".utf8)) == nil)
+ }
+
+ @Test func matchesWholeLiteralsOnly() throws {
+ // "%s.gl" is the next literal after "%s/%s.gl" on the real binary, and
+ // also its tail; a substring search sees both, a literal search one.
+ let data = cstrings(["%s/%s.gl", "%s.gl", "/mnt7"])
+ let site = try CFWSeputil.findSite(
+ in: data,
+ cstring: section(at: 0, size: data.count, address: 0x1_0000_0000)
+ )
+ #expect(site.literalOffset == 16)
+ #expect(site.literal == "%s/%s.gl")
+ #expect(site.fieldOffset == 19)
+ #expect(site.fieldVMA == 0x1_0000_0013)
+ }
+
+ @Test func findsTheAlreadyPatchedSpelling() throws {
+ let data = cstrings(["%s/AA.gl"])
+ let site = try CFWSeputil.findSite(
+ in: data,
+ cstring: section(at: 0, size: data.count, address: 0x1_0000_0000)
+ )
+ #expect(site.isPristine == false)
+ #expect(site.fieldOffset == 19)
+ }
+
+ @Test func refusesWhenThereIsNoCandidate() {
+ let data = cstrings(["%s.gl", "/mnt7", "/private/xarts"])
+ #expect(throws: PatcherError.self) {
+ try CFWSeputil.findSite(
+ in: data,
+ cstring: section(at: 0, size: data.count, address: 0x1_0000_0000)
+ )
+ }
+ }
+
+ /// Two candidates is not a coin flip to be taken; it is a binary this
+ /// patcher does not recognise.
+ @Test func refusesWhenThereAreTwoCandidates() {
+ let data = cstrings(["%s/%s.gl", "/mnt7", "%s/%s.gl"])
+ #expect(throws: PatcherError.self) {
+ try CFWSeputil.findSite(
+ in: data,
+ cstring: section(at: 0, size: data.count, address: 0x1_0000_0000)
+ )
+ }
+ }
+
+ // MARK: adrp/add pairing
+
+ private func text(size: Int, address: UInt64) -> MachOSectionInfo {
+ MachOSectionInfo(
+ segmentName: "__TEXT",
+ sectionName: "__text",
+ address: address,
+ size: UInt64(size),
+ fileOffset: 0
+ )
+ }
+
+ @Test func pairsAnAdrpWithItsAdd() throws {
+ let pc: UInt64 = 0x1_0000_0000
+ let target: UInt64 = 0x1_0001_BDCF
+ var code = try #require(ARM64Encoder.encodeADRP(rd: 2, pc: pc, target: target))
+ code.append(try #require(ARM64Encoder.encodeAddImm12(rd: 2, rn: 2, imm12: 0xDCF)))
+
+ #expect(CFWSeputil.references(to: target, in: code, text: text(size: 8, address: pc)) == [pc + 4])
+ // A different literal on the same page is a different address.
+ #expect(CFWSeputil.references(to: target + 1, in: code, text: text(size: 8, address: pc)).isEmpty)
+ }
+
+ @Test func rejectsAnAddIntoAnotherRegister() throws {
+ let pc: UInt64 = 0x1_0000_0000
+ let target: UInt64 = 0x1_0001_BDCF
+ var code = try #require(ARM64Encoder.encodeADRP(rd: 2, pc: pc, target: target))
+ code.append(try #require(ARM64Encoder.encodeAddImm12(rd: 3, rn: 3, imm12: 0xDCF)))
+ #expect(CFWSeputil.references(to: target, in: code, text: text(size: 8, address: pc)).isEmpty)
+ }
+
+ /// `add xD, xN, #imm, lsl #12` forms `page + (imm << 12)`, not `page + imm`.
+ /// Treating it as the latter would pair it with an `adrp` it has nothing to
+ /// do with, so the `sh` bit is read off the encoding — the Swift Capstone
+ /// wrapper does not expose an operand's shift.
+ @Test func rejectsAShiftedAddImmediate() throws {
+ let pc: UInt64 = 0x1_0000_0000
+ let target: UInt64 = 0x1_0001_BDCF
+ let adrp = try #require(ARM64Encoder.encodeADRP(rd: 2, pc: pc, target: target))
+ let add = try #require(ARM64Encoder.encodeAddImm12(rd: 2, rn: 2, imm12: 0xDCF))
+
+ // Set bit 22 (`sh`) on the encoder's unshifted ADD — there is no
+ // shifted encoder, and hand-writing the whole word would be a second
+ // encoder to get wrong.
+ var shifted = add
+ shifted[shifted.startIndex + 2] |= 0x40
+
+ let disassembler = ARM64Disassembler()
+ let plain = try #require(disassembler.disassembleOne(add))
+ let lsl = try #require(disassembler.disassembleOne(shifted))
+ #expect(plain.mnemonic == "add")
+ #expect(lsl.mnemonic == "add")
+ #expect(CFWSeputil.isShiftedAddImmediate(plain) == false)
+ #expect(CFWSeputil.isShiftedAddImmediate(lsl) == true)
+
+ #expect(CFWSeputil.references(to: target, in: adrp + shifted, text: text(size: 8, address: pc)).isEmpty)
+ #expect(CFWSeputil.references(to: target, in: adrp + add, text: text(size: 8, address: pc)) == [pc + 4])
+ }
+}
diff --git a/tests/FirmwarePatcherTests/CFWWatchdogdTests.swift b/tests/FirmwarePatcherTests/CFWWatchdogdTests.swift
new file mode 100644
index 00000000..d376769a
--- /dev/null
+++ b/tests/FirmwarePatcherTests/CFWWatchdogdTests.swift
@@ -0,0 +1,462 @@
+// CFWWatchdogdTests.swift — parity, anchoring and idempotence for the
+// watchdogd hv_vmm_present cache patch.
+//
+// Two independent references are available for this patch and both are used:
+//
+// * `scripts/patchers/cfw_patch_watchdogd.py`, driven exactly as
+// `cfw_install_exp.sh` drives it (`cfw.py patch-watchdogd <binary>`). The
+// central test runs it and `CFWWatchdogd` over two clones of the same
+// pristine binary and compares the results byte for byte — patched
+// instructions and re-attested code slots alike.
+// * `/usr/bin/codesign`, which recomputes the slot hashes itself. It has no
+// part in this code, so a binary that verifies under it is evidence the
+// re-attestation is right rather than self-consistent.
+//
+// The fixture is the real `/usr/libexec/watchdogd` from iOS 27.0 (24A435,
+// iPhone17,3), at `ipsws/ref_extract/macho_pristine/watchdogd`. That tree is
+// read-only reference data: every test here clones what it needs into the
+// system temp directory and never writes inside it.
+
+import Capstone
+import CryptoKit
+@testable import FirmwarePatcher
+import Foundation
+import Testing
+
+// MARK: - Fixtures
+
+enum WatchdogdFixture {
+ /// 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>
+
+ static let pristineDirectory = repositoryRoot.appending(path: "ipsws/ref_extract/macho_pristine")
+ static let watchdogd = pristineDirectory.appending(path: "watchdogd")
+ /// A Mach-O from the same firmware that does not cache the sysctl — the
+ /// negative case.
+ static let seputil = pristineDirectory.appending(path: "seputil")
+
+ static let python = repositoryRoot.appending(path: ".venv/bin/python3")
+ static let cfwCLI = repositoryRoot.appending(path: "scripts/patchers/cfw.py")
+ static let codesign = URL(filePath: "/usr/bin/codesign")
+
+ static func exists(_ url: URL) -> Bool { FileManager.default.fileExists(atPath: url.path) }
+
+ /// SHA-256 as `shasum -a 256` prints it, so a digest in this run's output
+ /// can be compared against one taken from a shell.
+ static func digest(_ data: Data) -> String { Data(SHA256.hash(data: data)).hex }
+
+ static var hasWatchdogd: Bool { exists(watchdogd) }
+ static var hasSeputil: Bool { exists(seputil) }
+ static var hasPythonReference: Bool { hasWatchdogd && exists(python) && exists(cfwCLI) }
+ static var hasCodesign: Bool { hasWatchdogd && exists(codesign) }
+
+ /// A private copy of `source` the caller may modify freely. Deliberately
+ /// outside the working tree.
+ static func scratchCopy(of source: URL, named name: String) throws -> URL {
+ let directory = URL(filePath: NSTemporaryDirectory())
+ .appending(path: "CFWWatchdogdTests-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+ let destination = directory.appending(path: name)
+ try FileManager.default.copyItem(at: source, 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
+ 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))
+ }
+
+ /// The `__TEXT,__text` section, or a thrown error — never a silent empty
+ /// result, which a test would read as "nothing to check".
+ static func text(in data: Data) throws -> MachOSectionInfo {
+ guard let text = MachOParser.parseSections(from: data)["__TEXT,__text"] else {
+ throw PatcherError.invalidFormat("fixture has no __TEXT,__text")
+ }
+ return text
+ }
+
+ /// Every `bl` in `__TEXT,__text` whose target resolves to `_sysctlbyname`.
+ /// Computed here, not by the patcher, so "the anchor rejects the other
+ /// calls" is measured against an independent count.
+ static func sysctlCallSites(in data: Data) throws -> [UInt64] {
+ let text = try text(in: data)
+ guard let symbols = CFWWatchdogdSymbolTargets(data: data) else {
+ throw PatcherError.invalidFormat("fixture has no symbol table")
+ }
+ let start = Int(text.fileOffset)
+ let body = data.subdata(in: start ..< start + Int(text.size))
+
+ var found: [UInt64] = []
+ for instruction in ARM64Disassembler().disassemble(body, at: text.address)
+ where instruction.mnemonic == "bl"
+ {
+ guard let target = ARM64Encoder.decodeBranchTarget(
+ insn: CFWWatchdogd.word(of: instruction), pc: instruction.address
+ ) else { continue }
+ if symbols.name(forBranchTarget: target) == "_sysctlbyname" { found.append(instruction.address) }
+ }
+ return found
+ }
+}
+
+// MARK: - Anchoring
+
+@Suite("watchdogd hv_vmm_present cache — anchoring")
+struct CFWWatchdogdAnchorTests {
+ /// The shape the patch is written against, read off the real binary.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func locatesBothCacheSites() throws {
+ let data = try Data(contentsOf: WatchdogdFixture.watchdogd)
+ let sites = try CFWWatchdogd.locateSites(in: data)
+
+ #expect(sites.count == 2, "24A435 watchdogd caches the answer in two functions")
+ for site in sites {
+ #expect(site.state == .pristine)
+ #expect(site.valueRegister == "w8")
+ // The gate really is the `cbnz w0` right after the call...
+ #expect(site.gateVMA == site.callVMA + 4)
+ let gate = try #require(ARM64Disassembler().disassembleOne(
+ data.subdata(in: site.gateFileOffset ..< site.gateFileOffset + 4), at: site.gateVMA
+ ))
+ #expect(gate.mnemonic == "cbnz")
+ // ...and the value really is a `cset`.
+ let value = try #require(ARM64Disassembler().disassembleOne(
+ data.subdata(in: site.valueFileOffset ..< site.valueFileOffset + 4), at: site.valueVMA
+ ))
+ #expect(value.mnemonic == "cset")
+ #expect(value.aarch64?.conditionCode == AArch64CC_NE)
+ }
+ }
+
+ /// The cached byte is a zero-filled global, which is why the skipped store
+ /// leaves it reading 0 and why forcing the stored value to 1 is the fix.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func cachedByteLivesInZeroFilledData() throws {
+ let data = try Data(contentsOf: WatchdogdFixture.watchdogd)
+ let sites = try CFWWatchdogd.locateSites(in: data)
+ let sections = MachOParser.parseSections(from: data)
+ let zeroFilled = ["__DATA,__bss", "__DATA,__common"].compactMap { sections[$0] }
+ #expect(!zeroFilled.isEmpty)
+
+ for site in sites {
+ let inZeroFill = zeroFilled.contains {
+ site.cachedByteVMA >= $0.address && site.cachedByteVMA < $0.address + $0.size
+ }
+ #expect(inZeroFill, "cached byte 0x\(String(site.cachedByteVMA, radix: 16)) must be BSS")
+ }
+ }
+
+ /// The discriminating test: watchdogd calls `sysctlbyname` five times and
+ /// only two of those calls cache the VM-presence answer. An anchor that
+ /// matched on "a call followed by cbnz w0" alone would have to be checked
+ /// by hand; this states the number.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func rejectsTheOtherSysctlCallSites() throws {
+ let data = try Data(contentsOf: WatchdogdFixture.watchdogd)
+ let calls = try WatchdogdFixture.sysctlCallSites(in: data)
+ let sites = try CFWWatchdogd.locateSites(in: data)
+
+ #expect(calls.count == 5, "24A435 watchdogd calls sysctlbyname five times")
+ #expect(sites.count == 2)
+ for site in sites { #expect(calls.contains(site.callVMA)) }
+ }
+
+ /// The in-image symbol lookup the anchor rests on, checked on its own: a
+ /// stub address in `__auth_stubs` resolves through the indirect symbol
+ /// table to the imported name.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func resolvesTheImportThroughTheIndirectSymbolTable() throws {
+ let data = try Data(contentsOf: WatchdogdFixture.watchdogd)
+ let symbols = try #require(CFWWatchdogdSymbolTargets(data: data))
+ let sites = try CFWWatchdogd.locateSites(in: data)
+ let call = try #require(sites.first)
+
+ let target = try #require(ARM64Encoder.decodeBranchTarget(
+ insn: {
+ let offset = Int(call.callVMA - 0x1_0000_0000)
+ return data.loadLE(UInt32.self, at: offset)
+ }(),
+ pc: call.callVMA
+ ))
+ #expect(symbols.importName(atStub: target) == "_sysctlbyname")
+ // An address that is not a stub resolves to nothing rather than to the
+ // nearest entry.
+ #expect(symbols.importName(atStub: call.callVMA) == nil)
+ }
+
+ /// The argument anchor on its own, over a synthesised stream, because the
+ /// shipped binary only exercises one of its two branches.
+ ///
+ /// 24A435 forms the pointer straight into x0, so the indirection path —
+ /// the literal built in a scratch register and moved into x0 before the
+ /// call — has no coverage from the fixture. It is the path that keeps the
+ /// patch working when a later build schedules the argument differently, so
+ /// it is checked here instead of assumed.
+ @Test
+ func acceptsTheLiteralReachingX0ThroughAMove() throws {
+ let base: UInt64 = 0x1_0000_0000
+
+ func stream(movingInto destination: UInt32?) throws -> [Instruction] {
+ var code = Data()
+ code += try #require(ARM64Encoder.encodeADRP(rd: 9, pc: base, target: base + 0x4000))
+ code += try #require(ARM64Encoder.encodeAddImm12(rd: 9, rn: 9, imm12: 0x453))
+ if let destination {
+ code += ARM64Encoder.encodeMovX(rd: destination, rm: 9)
+ } else {
+ code += ARM64.nop
+ }
+ code += try #require(ARM64Encoder.encodeBL(from: Int(base) + 12, to: Int(base) + 0x100))
+ return ARM64Disassembler().disassemble(code, at: base)
+ }
+
+ // add x9, … ; mov x0, x9 ; bl — the literal is the call's argument.
+ #expect(CFWWatchdogd.passesLiteral(
+ inRegister: "x9", from: 1, toCallAt: 3, in: try stream(movingInto: 0)
+ ))
+ // The same shape moving into x1 is some other call's argument.
+ #expect(!CFWWatchdogd.passesLiteral(
+ inRegister: "x9", from: 1, toCallAt: 3, in: try stream(movingInto: 1)
+ ))
+ // No move at all, and the pointer never reaches x0.
+ #expect(!CFWWatchdogd.passesLiteral(
+ inRegister: "x9", from: 1, toCallAt: 3, in: try stream(movingInto: nil)
+ ))
+ // The direct form the shipped binary uses needs no move.
+ #expect(CFWWatchdogd.passesLiteral(
+ inRegister: "x0", from: 1, toCallAt: 3, in: try stream(movingInto: nil)
+ ))
+ }
+
+ /// A Mach-O from the same firmware that never queries the sysctl is a hard
+ /// error, not a silent no-op: "no site" and "already patched" must not be
+ /// the same answer.
+ @Test(.enabled(if: WatchdogdFixture.hasSeputil))
+ func rejectsABinaryWithoutTheCacheSite() throws {
+ let data = try Data(contentsOf: WatchdogdFixture.seputil)
+ #expect(throws: PatcherError.self) {
+ try CFWWatchdogd.locateSites(in: data)
+ }
+ }
+}
+
+// MARK: - Patching
+
+@Suite("watchdogd hv_vmm_present cache — patching")
+struct CFWWatchdogdPatchTests {
+ /// Both instructions, and nothing else in `__TEXT`.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func rewritesTwoInstructionsPerSite() throws {
+ let original = try Data(contentsOf: WatchdogdFixture.watchdogd)
+ var data = original
+ let report = try CFWWatchdogd.patch(&data, log: nil)
+
+ #expect(report.outcome == .patched)
+ #expect(report.sitesWritten == 2)
+ #expect(report.records.count == 4)
+
+ let expectedValue = try #require(ARM64Encoder.encodeMovzW(rd: 8, imm16: 1))
+ for (index, record) in report.records.enumerated() {
+ #expect(record.component == "watchdogd")
+ #expect(record.originalBytes.count == 4)
+ #expect(record.patchedBytes == (index % 2 == 0 ? ARM64.nop : expectedValue))
+ #expect(data.subdata(in: record.fileOffset ..< record.fileOffset + 4) == record.patchedBytes)
+ }
+
+ // Outside the two instructions and the two code slots, the file is
+ // untouched: the patch is surgical by construction, not by inspection.
+ var differing: [Int] = []
+ for offset in 0 ..< original.count where original[offset] != data[offset] {
+ differing.append(offset)
+ }
+ let instructionBytes = Set(report.records.flatMap { $0.fileOffset ..< $0.fileOffset + 4 })
+ let slotBytes = Set(report.rehashedSlots.flatMap { $0.hashFileOffset ..< $0.hashFileOffset + 32 })
+ #expect(Set(differing).isSubset(of: instructionBytes.union(slotBytes)))
+ #expect(report.rehashedSlots.count == 2)
+ }
+
+ /// Every page that was written gets its slot re-hashed — checked against
+ /// the code directory's own slot arithmetic rather than the patcher's.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func reattestsThePageOfEveryWrittenInstruction() throws {
+ var data = try Data(contentsOf: WatchdogdFixture.watchdogd)
+ let report = try CFWWatchdogd.patch(&data, log: nil)
+ let directory = try #require(CFWMachOCodeSignature.codeDirectories(in: data)?.first)
+
+ let writtenPages = Set(report.records.map { $0.fileOffset / directory.pageSize })
+ #expect(Set(report.rehashedSlots.map(\.pageIndex)) == writtenPages)
+
+ for slot in report.rehashedSlots {
+ let range = try #require(directory.slotRange(slot.pageIndex))
+ let stored = data.subdata(
+ in: directory.slotHashOffset(slot.pageIndex)
+ ..< directory.slotHashOffset(slot.pageIndex) + directory.hashSize
+ )
+ #expect(stored == slot.after)
+ #expect(slot.pageStart ..< slot.pageEnd == range)
+ }
+ }
+
+ /// Idempotence. Commit 8eb6c8b fixed exactly this class of bug in this
+ /// tree: a shape the patcher had already produced was not recognised. A
+ /// second run must change nothing at all — not the instructions, not the
+ /// code directory, not one byte of the file.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func secondRunChangesNothing() throws {
+ var data = try Data(contentsOf: WatchdogdFixture.watchdogd)
+ let first = try CFWWatchdogd.patch(&data, log: nil)
+ #expect(first.outcome == .patched)
+
+ let afterFirst = data
+ let second = try CFWWatchdogd.patch(&data, log: nil)
+ #expect(second.outcome == .alreadyPatched)
+ #expect(second.sitesWritten == 0)
+ #expect(second.records.isEmpty)
+ #expect(second.rehashedSlots.isEmpty)
+ #expect(data == afterFirst, "a second run must be byte-for-byte a no-op")
+
+ // And the already-patched shape is recognised as such, site by site.
+ #expect(second.sites.count == 2)
+ #expect(second.sites.allSatisfy { $0.state == .patched })
+ #expect(second.sites.map(\.gateVMA) == first.sites.map(\.gateVMA))
+ #expect(second.sites.map(\.valueVMA) == first.sites.map(\.valueVMA))
+ }
+
+ /// A dry run reports the sites and writes nothing.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func dryRunWritesNothing() throws {
+ let original = try Data(contentsOf: WatchdogdFixture.watchdogd)
+ var data = original
+ let report = try CFWWatchdogd.patch(&data, dryRun: true, log: nil)
+ #expect(report.outcome == .wouldPatch)
+ #expect(report.records.count == 4)
+ #expect(data == original)
+ }
+
+ /// The file-backed entry point, which is what the install script calls.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func patchesInPlaceOnDisk() throws {
+ let file = try WatchdogdFixture.scratchCopy(of: WatchdogdFixture.watchdogd, named: "watchdogd")
+ defer { try? FileManager.default.removeItem(at: file.deletingLastPathComponent()) }
+
+ let attributes = FileManager.default.attributesOfItem(atPath:)
+ let modeBefore = try attributes(file.path)[.posixPermissions] as? NSNumber
+
+ let report = try CFWWatchdogd.patch(at: file, log: nil)
+ #expect(report.outcome == .patched)
+
+ var expected = try Data(contentsOf: WatchdogdFixture.watchdogd)
+ try CFWWatchdogd.patch(&expected, log: nil)
+ #expect(try Data(contentsOf: file) == expected)
+
+ // watchdogd is installed executable and stays that way: the patch
+ // rewrites the file in place rather than replacing it.
+ #expect(try attributes(file.path)[.posixPermissions] as? NSNumber == modeBefore)
+ #expect(FileManager.default.isExecutableFile(atPath: file.path))
+ }
+
+ /// A second run over a file on disk leaves its bytes, and its mtime,
+ /// untouched — `.alreadyPatched` must not write at all.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func secondRunOnDiskWritesNothing() throws {
+ let file = try WatchdogdFixture.scratchCopy(of: WatchdogdFixture.watchdogd, named: "watchdogd")
+ defer { try? FileManager.default.removeItem(at: file.deletingLastPathComponent()) }
+
+ try CFWWatchdogd.patch(at: file, log: nil)
+ let afterFirst = try Data(contentsOf: file)
+ let stampAfterFirst = try FileManager.default
+ .attributesOfItem(atPath: file.path)[.modificationDate] as? Date
+
+ let second = try CFWWatchdogd.patch(at: file, log: nil)
+ #expect(second.outcome == .alreadyPatched)
+ #expect(try Data(contentsOf: file) == afterFirst)
+ #expect(try FileManager.default
+ .attributesOfItem(atPath: file.path)[.modificationDate] as? Date == stampAfterFirst)
+ }
+}
+
+// MARK: - Independent references
+
+@Suite("watchdogd hv_vmm_present cache — independent references")
+struct CFWWatchdogdReferenceTests {
+ /// The migration plan's gate for P1.2: the Swift patcher and the Python it
+ /// replaces must produce the same bytes from the same input.
+ @Test(.enabled(if: WatchdogdFixture.hasPythonReference))
+ func matchesThePythonReferenceByteForByte() throws {
+ let reference = try WatchdogdFixture.scratchCopy(
+ of: WatchdogdFixture.watchdogd, named: "watchdogd-python"
+ )
+ defer { try? FileManager.default.removeItem(at: reference.deletingLastPathComponent()) }
+
+ let result = try WatchdogdFixture.run(WatchdogdFixture.python, [
+ WatchdogdFixture.cfwCLI.path, "patch-watchdogd", reference.path,
+ ])
+ #expect(result.status == 0, "reference patcher failed: \(result.output)")
+
+ var mine = try Data(contentsOf: WatchdogdFixture.watchdogd)
+ try CFWWatchdogd.patch(&mine, log: nil)
+
+ let theirs = try Data(contentsOf: reference)
+ // Printed so the parity claim is checkable from outside this process:
+ // `shasum -a 256` over either patcher's output has to read the same.
+ print("""
+ watchdogd parity: \
+ pristine=\(WatchdogdFixture.digest(try Data(contentsOf: WatchdogdFixture.watchdogd))) \
+ python=\(WatchdogdFixture.digest(theirs)) \
+ swift=\(WatchdogdFixture.digest(mine))
+ """)
+ #expect(mine.count == theirs.count)
+ #expect(mine == theirs, "Swift and Python output must be identical")
+ }
+
+ /// The Python's idempotent path, for the same reason: both implementations
+ /// must agree that a patched binary needs nothing done to it.
+ @Test(.enabled(if: WatchdogdFixture.hasPythonReference))
+ func agreesWithThePythonOnAnAlreadyPatchedBinary() throws {
+ let file = try WatchdogdFixture.scratchCopy(
+ of: WatchdogdFixture.watchdogd, named: "watchdogd-twice"
+ )
+ defer { try? FileManager.default.removeItem(at: file.deletingLastPathComponent()) }
+
+ try CFWWatchdogd.patch(at: file, log: nil)
+ let afterSwift = try Data(contentsOf: file)
+
+ let result = try WatchdogdFixture.run(WatchdogdFixture.python, [
+ WatchdogdFixture.cfwCLI.path, "patch-watchdogd", file.path,
+ ])
+ #expect(result.status == 0, "reference patcher failed: \(result.output)")
+ #expect(result.output.contains("already patched"))
+ #expect(try Data(contentsOf: file) == afterSwift)
+ }
+
+ /// `codesign` recomputes the page hashes independently of this code. If the
+ /// re-attestation were wrong — the short tail slot being the classic way —
+ /// this is where it shows.
+ @Test(.enabled(if: WatchdogdFixture.hasCodesign))
+ func patchedBinaryStillVerifiesUnderCodesign() throws {
+ let file = try WatchdogdFixture.scratchCopy(
+ of: WatchdogdFixture.watchdogd, named: "watchdogd-signed"
+ )
+ defer { try? FileManager.default.removeItem(at: file.deletingLastPathComponent()) }
+
+ let before = try WatchdogdFixture.run(WatchdogdFixture.codesign, ["-v", "-v", file.path])
+ #expect(before.status == 0, "fixture must verify before patching: \(before.output)")
+
+ try CFWWatchdogd.patch(at: file, log: nil)
+
+ let after = try WatchdogdFixture.run(WatchdogdFixture.codesign, ["-v", "-v", file.path])
+ #expect(after.status == 0, "patched binary must still verify: \(after.output)")
+ }
+}
diff --git a/tests/VPhoneCoreTests/FirmwareMatrixTests.swift b/tests/VPhoneCoreTests/FirmwareMatrixTests.swift
new file mode 100644
index 00000000..010087a9
--- /dev/null
+++ b/tests/VPhoneCoreTests/FirmwareMatrixTests.swift
@@ -0,0 +1,714 @@
+// Equivalence tests for the Swift port of the two Python heredocs that used to
+// live inside scripts/fw_prepare.sh (`list_firmwares`,
+// `resolve_selector_from_downloads`).
+//
+// The golden strings below are not hand-written. They are the bytes the Python
+// produced when the two heredocs were lifted out of fw_prepare.sh verbatim
+// (`diff <(sed -n '167,246p' scripts/fw_prepare.sh) ref_list_firmwares.py`
+// reports no difference) and run under .venv/bin/python3 over the same fixture
+// this file freezes:
+//
+// DOWNLOADABLE_IPSW_URLS="$(cat fixture_urls.txt)" \
+// .venv/bin/python3 ref_list_firmwares.py iPhone17,3 fixture_readme.md
+//
+// Colour was compared in three conditions, each running both implementations
+// through the identical wrapper: a pipe, a real pty via script(1), and NO_COLOR
+// set. Those runs also covered the repository's own README.md against a live
+// `ipsw download ipsw --device iPhone17,3 --urls` capture.
+//
+// Trailing spaces are written as `\u{20}` on purpose: the Python padded the
+// status column to 11 *inside* the colour escape, so those spaces are real
+// output bytes, and a literal trailing space is the first thing an editor or a
+// formatter silently eats.
+//
+// One deliberate divergence, and the only one found: `version_key` built a
+// tuple of mixed ints and strs, so a list holding both `27.0` and `27.beta`
+// made CPython raise
+// `TypeError: '<' not supported between instances of 'str' and 'int'`
+// and exit 1 mid-listing. Nothing Apple serves produces that. The port orders
+// numbers before text instead of crashing; `nonNumericComponentsStillOrder`
+// below pins that choice down.
+
+@testable import VPhoneCore
+import Foundation
+import Testing
+
+// MARK: - Frozen fixture
+
+private enum Fixture {
+ /// A verbatim slice of the real README's table, plus two decoys: a
+ /// `17,3_…` cell before the section and another after it, neither of which
+ /// may count, and a `16,1_…` row for a different device.
+ static let readme = """
+ ## Prerequisites
+
+ Some prose with a `17,3_99.9_99Z99` cell that must NOT count, because it is
+ outside the section.
+
+ ## Tested Environments
+
+ | Host | iPhone | CloudOS |
+ | --------------- | --------------------- | --------------- |
+ | Mac16,11 27.0b2 | `17,3_18.6.2_22G100` | `26.1-23B85` |
+ | Mac16,8 26.5.1 | `17,3_26.0_23A341` | `26.1-23B85` |
+ | Mac16,12 26.3 | `17,3_26.3_23D127` | `26.3-23D128` |
+ | Mac16,12 26.3 | `17,3_26.3.1_23D8133` | `26.3-23D128` |
+ | Mac16,11 26.2 | `17,3_26.4_23E246` | `26.4-23E5207q` |
+ | Mac16,6 26.4.1 | `17,3_27.0_24A5390f` | `26.4-23E5207q` |
+ | Mac16,6 26.6.1 | `17,3_27.0_24A435` | `26.4-23E5207q` |
+ | Mac16,3 26.0 | `16,1_26.1_23B85` | `26.1-23B85` |
+
+ ## FAQ
+
+ A later section with `17,3_88.8_88Z88`, which must NOT count either.
+ """
+
+ /// Real Apple restore URLs, plus one exact duplicate and four lines that
+ /// look close enough to matter: another device, an extra `_Custom`
+ /// segment, and a log line with no leading slash.
+ static let urls = """
+ https://updates.cdn-apple.com/2025SummerFCS/fullrestores/093-20738/98758B5A-311E-4538-B365-FEE3D8792CDF/iPhone17,3_18.6.2_22G100_Restore.ipsw
+ https://updates.cdn-apple.com/2025FallFCS/fullrestores/093-40775/B7282E74-76C1-4D0A-8FAE-CE97FC2330C2/iPhone17,3_26.0_23A341_Restore.ipsw
+ https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-39165/E8E603F3-A2E2-4638-8067-394754896386/iPhone17,3_26.3_23D127_Restore.ipsw
+ https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-90312/17B5C7BE-C560-43BD-BA9A-7DD1E5C2FC23/iPhone17,3_26.3.1_23D8133_Restore.ipsw
+ https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-06082/FE21226A-B87F-4FC7-9D4B-B97A9EAF5C20/iPhone17,3_26.4_23E246_Restore.ipsw
+ https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-28526/10E1E3EC-6A3E-4620-A569-8E0C4361AB77/iPhone17,3_26.4.1_23E254_Restore.ipsw
+ https://updates.cdn-apple.com/2026SpringSeed/fullrestores/140-57108/5E816D0E-89BB-4B95-8825-6A3EDF22E509/iPhone17,3_27.0_24A5390f_Restore.ipsw
+ https://updates.cdn-apple.com/2026SpringSeed/2d03d580-843b-4b2a-b09d-976b31c10744/iPhone17,3_27.0_24A5430a_Restore.ipsw
+ https://updates.cdn-apple.com/2026FallFCS/2d0cd01d-b4f9-4a20-a1e8-f3be54570da7/iPhone17,3_27.0_24A435_Restore.ipsw
+ https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-39165/E8E603F3-A2E2-4638-8067-394754896386/iPhone17,3_26.3_23D127_Restore.ipsw
+ https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-13864/668EFC0E-5911-454C-96C6-E1063CB80042/iPad16,3_26.1_23B85_Restore.ipsw
+ https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-13864/668EFC0E-5911-454C-96C6-E1063CB80042/iPhone17,3_26.1_23B85_Custom_Restore.ipsw
+ · Downloading iPhone17,3_26.1_23B85_Restore.ipsw
+ """
+
+ static let d = "iPhone17,3"
+ static let url263 = "https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-39165/E8E603F3-A2E2-4638-8067-394754896386/iPhone17,3_26.3_23D127_Restore.ipsw"
+
+ static func lines(_ lines: [String]) -> String {
+ lines.map { $0 + "\n" }.joined()
+ }
+
+ static let plain = VPhoneStatusStyle(isColored: false)
+ static let colored = VPhoneStatusStyle(isColored: true)
+
+ /// Writes `readme` to a scratch file, because the command-line half takes a
+ /// path (that is what the shell hands it).
+ static func withReadmeFile<T>(_ body: (String) throws -> T) rethrows -> T {
+ let url = URL(fileURLWithPath: NSTemporaryDirectory())
+ .appendingPathComponent("vphone-fwmatrix-\(UUID().uuidString).md")
+ try? readme.write(to: url, atomically: true, encoding: .utf8)
+ defer { try? FileManager.default.removeItem(at: url) }
+ return try body(url.path)
+ }
+}
+
+// MARK: - Goldens
+
+private enum Golden {
+ static let listPlain = Fixture.lines([
+ "Available downloadable IPSWs for iPhone17,3:",
+ "",
+ "Status: Supported Not Tested Unsupported",
+ "",
+ "VERSION BUILD STATUS",
+ "27.0 24A5430a Not Tested\u{20}",
+ "27.0 24A5390f Supported\u{20}\u{20}",
+ "27.0 24A435 Supported\u{20}\u{20}",
+ "26.4.1 23E254 Not Tested\u{20}",
+ "26.4 23E246 Supported\u{20}\u{20}",
+ "26.3.1 23D8133 Supported\u{20}\u{20}",
+ "26.3 23D127 Supported\u{20}\u{20}",
+ "26.0 23A341 Supported\u{20}\u{20}",
+ "18.6.2 22G100 Supported\u{20}\u{20}",
+ ])
+
+ static let listColored = Fixture.lines([
+ "Available downloadable IPSWs for iPhone17,3:",
+ "",
+ "Status: \u{1B}[32mSupported \u{1B}[0m \u{1B}[33mNot Tested \u{1B}[0m \u{1B}[31mUnsupported\u{1B}[0m",
+ "",
+ "VERSION BUILD STATUS",
+ "27.0 24A5430a \u{1B}[33mNot Tested \u{1B}[0m",
+ "27.0 24A5390f \u{1B}[32mSupported \u{1B}[0m",
+ "27.0 24A435 \u{1B}[32mSupported \u{1B}[0m",
+ "26.4.1 23E254 \u{1B}[33mNot Tested \u{1B}[0m",
+ "26.4 23E246 \u{1B}[32mSupported \u{1B}[0m",
+ "26.3.1 23D8133 \u{1B}[32mSupported \u{1B}[0m",
+ "26.3 23D127 \u{1B}[32mSupported \u{1B}[0m",
+ "26.0 23A341 \u{1B}[32mSupported \u{1B}[0m",
+ "18.6.2 22G100 \u{1B}[32mSupported \u{1B}[0m",
+ ])
+
+ /// The selector's status column is *not* padded — a real asymmetry between
+ /// the two heredocs that the port has to keep.
+ static let ambiguousColored = Fixture.lines([
+ "Version 27.0 is ambiguous for iPhone17,3; specify one of these builds:",
+ "BUILD STATUS",
+ "24A5430a \u{1B}[33mNot Tested\u{1B}[0m",
+ "24A5390f \u{1B}[32mSupported\u{1B}[0m",
+ "24A435 \u{1B}[32mSupported\u{1B}[0m",
+ ])
+
+ static let ambiguousPlain = Fixture.lines([
+ "Version 27.0 is ambiguous for iPhone17,3; specify one of these builds:",
+ "BUILD STATUS",
+ "24A5430a Not Tested",
+ "24A5390f Supported",
+ "24A435 Supported",
+ ])
+
+ static let hit = "26.3\t23D127\t\(Fixture.url263)\tSupported\n"
+}
+
+// MARK: - Byte-for-byte equivalence with the Python
+
+struct FirmwareMatrixGoldenTests {
+ @Test func listingMatchesPythonPlain() {
+ let out = VPhoneFirmwareMatrix.listing(
+ device: Fixture.d, readme: Fixture.readme,
+ downloadURLs: Fixture.urls, style: Fixture.plain
+ )
+ #expect(out == .matrix(Golden.listPlain))
+ }
+
+ @Test func listingMatchesPythonColored() {
+ let out = VPhoneFirmwareMatrix.listing(
+ device: Fixture.d, readme: Fixture.readme,
+ downloadURLs: Fixture.urls, style: Fixture.colored
+ )
+ #expect(out == .matrix(Golden.listColored))
+ }
+
+ @Test func ambiguousVersionMatchesPython() {
+ for (style, golden) in [
+ (Fixture.plain, Golden.ambiguousPlain),
+ (Fixture.colored, Golden.ambiguousColored),
+ ] {
+ let out = VPhoneFirmwareMatrix.selection(
+ device: Fixture.d, version: "27.0", build: "",
+ readme: Fixture.readme, downloadURLs: Fixture.urls, style: style
+ )
+ #expect(out == .ambiguous(golden))
+ }
+ }
+
+ @Test func resolvedSelectorMatchesPython() {
+ let out = VPhoneFirmwareMatrix.selection(
+ device: Fixture.d, version: "26.3", build: "",
+ readme: Fixture.readme, downloadURLs: Fixture.urls, style: Fixture.colored
+ )
+ guard case let .selected(release, support) = out else {
+ Issue.record("expected a selection, got \(out)")
+ return
+ }
+ // The resolved line is plain even under colour — the shell reads it
+ // back through `IFS=$'\t' read`, and an escape in field 4 would end up
+ // in the "Status:" line it echoes.
+ #expect(out.resolvedLine == Golden.hit)
+ #expect(release.build == "23D127")
+ #expect(support == .supported)
+ // Only a hit has a line; the failure cases have nothing to hand back.
+ #expect(VPhoneFirmwareMatrix.selection(
+ device: Fixture.d, version: "99.9", build: "",
+ readme: Fixture.readme, downloadURLs: Fixture.urls, style: Fixture.plain
+ ).resolvedLine == nil)
+ }
+
+ @Test(arguments: [
+ ("99.9", "", "Unsupported: no downloadable IPSW matched device=iPhone17,3 version=99.9\n"),
+ ("", "99Z99", "Unsupported: no downloadable IPSW matched device=iPhone17,3 build=99Z99\n"),
+ ("99.9", "99Z99", "Unsupported: no downloadable IPSW matched device=iPhone17,3 version=99.9 build=99Z99\n"),
+ ])
+ func missMatchesPython(version: String, build: String, expected: String) {
+ let out = VPhoneFirmwareMatrix.selection(
+ device: Fixture.d, version: version, build: build,
+ readme: Fixture.readme, downloadURLs: Fixture.urls, style: Fixture.plain
+ )
+ #expect(out == .unmatched(expected))
+ let colored = VPhoneFirmwareMatrix.selection(
+ device: Fixture.d, version: version, build: build,
+ readme: Fixture.readme, downloadURLs: Fixture.urls, style: Fixture.colored
+ )
+ #expect(colored == .unmatched("\u{1B}[31mUnsupported\u{1B}[0m" + expected.dropFirst("Unsupported".count)))
+ }
+
+ @Test func emptyDownloadListIsAnError() {
+ let out = VPhoneFirmwareMatrix.listing(
+ device: "iPhone99,9", readme: Fixture.readme,
+ downloadURLs: Fixture.urls, style: Fixture.colored
+ )
+ // Plain even in colour, exactly as the Python printed it.
+ #expect(out == .nothingDownloadable("No downloadable IPSWs found for iPhone99,9\n"))
+ }
+}
+
+// MARK: - Parsing
+
+struct FirmwareMatrixParsingTests {
+ @Test func readsOnlyTheTestedEnvironmentsSectionAndOnlyThisDevice() {
+ let tested = VPhoneFirmwareMatrix.testedBuilds(readme: Fixture.readme, device: Fixture.d)
+ #expect(tested.count == 7)
+ #expect(tested.contains(VPhoneFirmwareBuildID(version: "26.3.1", build: "23D8133")))
+ // Before the heading.
+ #expect(!tested.contains(VPhoneFirmwareBuildID(version: "99.9", build: "99Z99")))
+ // After the next `## ` heading.
+ #expect(!tested.contains(VPhoneFirmwareBuildID(version: "88.8", build: "88Z88")))
+ // A different device's row inside the section.
+ #expect(!tested.contains(VPhoneFirmwareBuildID(version: "26.1", build: "23B85")))
+ }
+
+ @Test func aMissingReadmeMeansNothingIsTested() {
+ #expect(VPhoneFirmwareMatrix.testedBuilds(readme: nil, device: Fixture.d).isEmpty)
+ let out = VPhoneFirmwareMatrix.listing(
+ device: Fixture.d, readme: nil,
+ downloadURLs: Fixture.urls, style: Fixture.plain
+ )
+ guard case let .matrix(text) = out else {
+ Issue.record("expected a matrix")
+ return
+ }
+ #expect(!text.contains("Supported\u{20}\u{20}\n"))
+ #expect(text.components(separatedBy: "Not Tested").count == 1 + 9 + 1)
+ }
+
+ @Test func rejectsLookalikeURLs() {
+ let found = VPhoneFirmwareMatrix.releases(downloadURLs: Fixture.urls, device: Fixture.d)
+ // 9 real lines, 1 exact duplicate dropped, 3 lookalikes rejected.
+ #expect(found.count == 9)
+ #expect(!found.contains { $0.url.contains("iPad16,3") })
+ #expect(!found.contains { $0.url.contains("_Custom_") })
+ #expect(!found.contains { $0.build == "23B85" })
+ }
+
+ @Test func toleratesSurroundingWhitespaceAndBlankLines() {
+ let urls = "\n \(Fixture.url263) \n\n"
+ let found = VPhoneFirmwareMatrix.releases(downloadURLs: urls, device: Fixture.d)
+ #expect(found.count == 1)
+ // The URL is stored stripped, so the shell gets something it can fetch.
+ #expect(found.first?.url == Fixture.url263)
+ }
+
+ @Test func parsesTheRepositoryReadme() throws {
+ let tested = VPhoneFirmwareMatrix.testedBuilds(
+ readme: try RealData.repositoryReadme(),
+ device: Fixture.d
+ )
+ // The live table is edited often, so this asserts the shape, not a count.
+ #expect(tested.count >= 15)
+ #expect(tested.contains(VPhoneFirmwareBuildID(version: "26.1", build: "23B85")))
+ #expect(tested.allSatisfy { !$0.version.isEmpty && !$0.build.isEmpty })
+ #expect(tested.allSatisfy { !$0.version.contains("`") && !$0.build.contains("`") })
+ }
+}
+
+// MARK: - Real data
+
+/// The repository's own README table joined against a real `ipsw download ipsw
+/// --device iPhone17,3 --urls` capture — the two inputs the shell actually fed
+/// the Python, rather than anything shaped to suit the parser.
+///
+/// The README is read live, so these assert invariants rather than a golden: a
+/// row added to the table must not turn the suite red for the agent who added
+/// it. The cross-check is against a second parser written here on purpose in a
+/// different style — column splitting instead of a regex — so a regex that
+/// drifts has something independent to disagree with.
+private enum RealData {
+ static func repositoryReadme() throws -> String {
+ let url = URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+ .appendingPathComponent("README.md")
+ return try String(contentsOf: url, encoding: .utf8)
+ }
+
+ /// Captured 2026-09-23. 31 restore images, one build per version — which is
+ /// why the selector's ambiguity branch cannot be reached from live data and
+ /// is exercised from `Fixture` instead.
+ static let liveURLs = """
+ https://updates.cdn-apple.com/2026FallFCS/5130b3f9-3b4e-469a-b60e-93f6b310cdd9/iPhone17,3_27.0_24A437_Restore.ipsw
+ https://updates.cdn-apple.com/2026SummerFCS/29d685ce-f70d-45a0-9823-b1cd115f3927/iPhone17,3_26.6.2_23G90_Restore.ipsw
+ https://updates.cdn-apple.com/2026SummerFCS/fullrestores/140-93817/B5362BAA-F3EE-49C8-BA43-309F0DAD1362/iPhone17,3_26.6.1_23G83_Restore.ipsw
+ https://updates.cdn-apple.com/2026SummerFCS/fullrestores/140-58193/1F477C3E-934B-43C0-B428-753B9E005EC0/iPhone17,3_26.6_23G71_Restore.ipsw
+ https://updates.cdn-apple.com/2026SpringFCS/fullrestores/140-25549/1AFB1F72-E48E-476A-9C21-42B27C846C01/iPhone17,3_26.5.2_23F84_Restore.ipsw
+ https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-63074/5E6B4A05-BDBC-45FE-9606-22B8F4315989/iPhone17,3_26.5_23F77_Restore.ipsw
+ https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-60828/A4082066-CCC4-4903-89E6-FF4801EA609C/iPhone17,3_26.4.2_23E261_Restore.ipsw
+ https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-28526/10E1E3EC-6A3E-4620-A569-8E0C4361AB77/iPhone17,3_26.4.1_23E254_Restore.ipsw
+ https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-06082/FE21226A-B87F-4FC7-9D4B-B97A9EAF5C20/iPhone17,3_26.4_23E246_Restore.ipsw
+ https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-90312/17B5C7BE-C560-43BD-BA9A-7DD1E5C2FC23/iPhone17,3_26.3.1_23D8133_Restore.ipsw
+ https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-39165/E8E603F3-A2E2-4638-8067-394754896386/iPhone17,3_26.3_23D127_Restore.ipsw
+ https://updates.cdn-apple.com/2025FallFCS/fullrestores/047-34150/D14FB1F1-B8C5-4A20-9250-8DD35EF19BF5/iPhone17,3_26.2.1_23C71_Restore.ipsw
+ https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-90760/1214478F-8ED8-4AE0-B693-2F63CE0259A9/iPhone17,3_26.2_23C55_Restore.ipsw
+ https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-13864/668EFC0E-5911-454C-96C6-E1063CB80042/iPhone17,3_26.1_23B85_Restore.ipsw
+ https://updates.cdn-apple.com/2025FallFCS/fullrestores/093-46329/C1717B2A-9E58-4131-A398-75D9B1D01A89/iPhone17,3_26.0.1_23A355_Restore.ipsw
+ https://updates.cdn-apple.com/2025FallFCS/fullrestores/093-40775/B7282E74-76C1-4D0A-8FAE-CE97FC2330C2/iPhone17,3_26.0_23A341_Restore.ipsw
+ https://updates.cdn-apple.com/2025SummerFCS/fullrestores/093-20738/98758B5A-311E-4538-B365-FEE3D8792CDF/iPhone17,3_18.6.2_22G100_Restore.ipsw
+ https://updates.cdn-apple.com/2025SummerFCS/fullrestores/093-07229/D567EFF0-6D62-461A-9F66-B2EAE22C2DD8/iPhone17,3_18.6.1_22G90_Restore.ipsw
+ https://updates.cdn-apple.com/2025SummerFCS/fullrestores/082-98952/853D36FA-A5F4-4B75-B5F3-8D38430F6132/iPhone17,3_18.6_22G86_Restore.ipsw
+ https://updates.cdn-apple.com/2025SpringFCS/fullrestores/082-46019/A46C805A-4915-4552-BFD4-EFD1C7BE665E/iPhone17,3_18.5_22F76_Restore.ipsw
+ https://updates.cdn-apple.com/2025SpringFCS/fullrestores/082-30380/AD76C77E-51AA-4D55-A074-9C0E7545D784/iPhone17,3_18.4.1_22E252_Restore.ipsw
+ https://updates.cdn-apple.com/2025SpringFCS/fullrestores/082-14688/8DC47FED-F5B6-4BE6-B75F-8E36BCC5A484/iPhone17,3_18.4_22E240_Restore.ipsw
+ https://updates.cdn-apple.com/2025WinterFCS/fullrestores/082-03679/DA16409C-A02F-46E9-ADE9-ED32BDD47539/iPhone17,3_18.3.2_22D82_Restore.ipsw
+ https://updates.cdn-apple.com/2025WinterFCS/fullrestores/072-85742/283FD833-D2EF-4A97-AE6F-406E1DD998DA/iPhone17,3_18.3.1_22D72_Restore.ipsw
+ https://updates.cdn-apple.com/2025WinterFCS/fullrestores/072-68251/8CC707F3-9926-4ECC-B7F6-3497FE282048/iPhone17,3_18.3_22D63_Restore.ipsw
+ https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-55500/A62CEE9F-875F-4E53-9C9D-D4172E30BE88/iPhone17,3_18.2.1_22C161_Restore.ipsw
+ https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-42011/88CB7A92-6959-4FB4-A87E-77CE7CB8BB82/iPhone17,3_18.2_22C152_Restore.ipsw
+ https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-31863/D2DE541A-DC63-4016-9B22-0EED8A753FB9/iPhone17,3_18.1.1_22B91_Restore.ipsw
+ https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-12560/4A88CBAB-2F24-4173-BCFD-210325515BCA/iPhone17,3_18.1_22B83_Restore.ipsw
+ https://updates.cdn-apple.com/2024FallFCS/fullrestores/072-02193/DD4AADB5-492C-442E-8E79-42D72EDAF958/iPhone17,3_18.0.1_22A3370_Restore.ipsw
+ https://updates.cdn-apple.com/2024FallFCS/fullrestores/062-77769/2A2DBD27-47A6-40DB-AEF5-E283454A67E8/iPhone17,3_18.0_22A3354_Restore.ipsw
+ """
+
+ /// The same table, read by splitting on `|` and `_` instead of by regex.
+ static func testedBuildsByColumnSplitting(
+ in readme: String,
+ deviceSuffix: String
+ ) -> Set<VPhoneFirmwareBuildID> {
+ // A different way to find the section too: cut the document at its `## `
+ // headings rather than scanning line by line for them.
+ let sections = readme.components(separatedBy: "\n## ")
+ guard let table = sections.first(where: { $0.hasPrefix("Tested Environments") })
+ else { return [] }
+
+ var tested: Set<VPhoneFirmwareBuildID> = []
+ for row in table.components(separatedBy: "\n") {
+ for cell in row.components(separatedBy: "|") {
+ let trimmed = cell.trimmingCharacters(in: .whitespaces)
+ guard trimmed.hasPrefix("`"), trimmed.hasSuffix("`"), trimmed.count > 2
+ else { continue }
+ let fields = trimmed.dropFirst().dropLast().components(separatedBy: "_")
+ guard fields.count == 3, fields[0] == deviceSuffix else { continue }
+ tested.insert(VPhoneFirmwareBuildID(version: fields[1], build: fields[2]))
+ }
+ }
+ return tested
+ }
+}
+
+struct FirmwareMatrixRealDataTests {
+ @Test func theReadmeParserAgreesWithAnIndependentColumnSplitter() throws {
+ let readme = try RealData.repositoryReadme()
+ let byRegex = VPhoneFirmwareMatrix.testedBuilds(readme: readme, device: Fixture.d)
+ let bySplitting = RealData.testedBuildsByColumnSplitting(in: readme, deviceSuffix: "17,3")
+ #expect(!bySplitting.isEmpty, "the README table moved — fix the test, not the parser")
+ #expect(byRegex == bySplitting)
+ }
+
+ @Test func aLiveDownloadCaptureParsesWholeAndJoinsAgainstTheReadme() throws {
+ let releases = VPhoneFirmwareMatrix.releases(
+ downloadURLs: RealData.liveURLs,
+ device: Fixture.d
+ )
+ // Every line of the capture is a restore image for this device, so the
+ // URL parser has to claim all 31 — a silent drop is the failure mode
+ // that would quietly hide a firmware from `--list`.
+ #expect(releases.count == RealData.liveURLs.components(separatedBy: "\n").count)
+ #expect(releases.count == 31)
+ #expect(Set(releases.map(\.build)).count == 31)
+
+ let tested = VPhoneFirmwareMatrix.testedBuilds(readme: try RealData.repositoryReadme(), device: Fixture.d)
+ var supported = 0, notTested = 0
+ for release in releases {
+ let id = VPhoneFirmwareBuildID(version: release.version, build: release.build)
+ switch VPhoneFirmwareMatrix.support(of: release, tested: tested) {
+ case .supported:
+ #expect(tested.contains(id))
+ supported += 1
+ case .notTested:
+ #expect(!tested.contains(id))
+ notTested += 1
+ case .unsupported:
+ Issue.record("a listing row must never be Unsupported")
+ }
+ }
+ // Neither count may be zero, or the loop above proved nothing.
+ #expect(supported > 0)
+ #expect(notTested > 0)
+ }
+
+ /// Apple serves one build per version, so `--list` over live data is fully
+ /// ordered by version alone. This is the property the shell's `sorted(…,
+ /// reverse=True)` was there to produce.
+ @Test func theLiveCaptureListsNewestFirst() {
+ let out = VPhoneFirmwareMatrix.listing(
+ device: Fixture.d, readme: nil,
+ downloadURLs: RealData.liveURLs, style: Fixture.plain
+ )
+ guard case let .matrix(text) = out else {
+ Issue.record("expected a matrix")
+ return
+ }
+ let versions = text.components(separatedBy: "\n")
+ .dropFirst(5)
+ .compactMap { $0.split(separator: " ").first.map(String.init) }
+ #expect(versions.first == "27.0")
+ #expect(versions.last == "18.0")
+ // 26.6.2 above 26.6, and 26.2.1 above 26.2: a plain string sort puts
+ // both the other way round.
+ let index = { (v: String) in versions.firstIndex(of: v) ?? -1 }
+ #expect(index("26.6.2") < index("26.6"))
+ #expect(index("26.2.1") < index("26.2"))
+ #expect(index("26.0.1") < index("26.0"))
+ #expect(index("26.0") < index("18.6.2"))
+ }
+}
+
+// MARK: - Ordering
+
+struct FirmwareMatrixOrderingTests {
+ private func release(_ version: String, _ build: String) -> VPhoneFirmwareRelease {
+ VPhoneFirmwareRelease(version: version, build: build, url: "/\(version)_\(build)")
+ }
+
+ @Test func sortsVersionsNewestFirstWithNumericComponents() {
+ // Lexically "18.6.2" > "26.0" and "26.4.1" > "26.4"; numerically neither.
+ let sorted = [
+ release("26.4", "a"), release("18.6.2", "a"), release("26.4.1", "a"),
+ release("27.0", "a"), release("26.0", "a"), release("26.10", "a"),
+ ].sorted { VPhoneFirmwareMatrix.isNewer($0, than: $1) }
+ #expect(sorted.map(\.version) == ["27.0", "26.10", "26.4.1", "26.4", "26.0", "18.6.2"])
+ }
+
+ @Test func sortsBuildsByCodePointDescending() {
+ // 24A435 vs 24A5430a is the case that separates a string sort from a
+ // "looks numeric" one: '4' < '5' at index 3, so 24A5430a wins.
+ let sorted = [
+ release("27.0", "24A435"), release("27.0", "24A5430a"), release("27.0", "24A5390f"),
+ ].sorted { VPhoneFirmwareMatrix.hasHigherBuild($0, than: $1) }
+ #expect(sorted.map(\.build) == ["24A5430a", "24A5390f", "24A435"])
+ }
+
+ @Test func aShorterVersionSortsBelowItsOwnPrefixExtension() {
+ #expect(VPhoneFirmwareMatrix.isNewer(release("26.4.1", "a"), than: release("26.4", "a")))
+ #expect(!VPhoneFirmwareMatrix.isNewer(release("26.4", "a"), than: release("26.4.1", "a")))
+ }
+
+ @Test func nonNumericComponentsStillOrder() {
+ #expect(VPhoneFirmwareMatrix.versionKey("26.beta") == [.number(26), .text("beta")])
+ #expect(VPhoneFirmwareMatrix.versionKey("") == [.text("")])
+ #expect(VPhoneFirmwareMatrix.VersionPart.number(9) < .text("0"))
+ }
+}
+
+// MARK: - Column padding
+
+struct FirmwareMatrixPaddingTests {
+ @Test func leftJustifyingNeverTruncates() {
+ // `String.padding(toLength:)` would cut this to 12 and lose the build.
+ #expect(VPhoneFirmwareMatrix.leftJustified("27.0.1.2.3.4.5", 12) == "27.0.1.2.3.4.5")
+ #expect(VPhoneFirmwareMatrix.leftJustified("26.3", 12) == "26.3 ")
+ #expect(VPhoneFirmwareMatrix.leftJustified("", 3) == " ")
+ }
+
+ @Test func paddingGoesInsideTheColourEscape() {
+ // Outside the escape the text would be the same width on screen but a
+ // different byte string, and every golden above would break.
+ #expect(Fixture.colored.render(.supported, width: 11) == "\u{1B}[32mSupported \u{1B}[0m")
+ #expect(Fixture.colored.render(.supported) == "\u{1B}[32mSupported\u{1B}[0m")
+ #expect(Fixture.plain.render(.supported, width: 11) == "Supported ")
+ }
+
+ @Test func anOverlongVersionStillLeavesOneSpaceBeforeTheNextColumn() {
+ let urls = "/iPhone17,3_26.4.10.20.30_23E246_Restore.ipsw"
+ let out = VPhoneFirmwareMatrix.listing(
+ device: Fixture.d, readme: nil, downloadURLs: urls, style: Fixture.plain
+ )
+ guard case let .matrix(text) = out else {
+ Issue.record("expected a matrix")
+ return
+ }
+ #expect(text.contains("26.4.10.20.30 23E246 Not Tested\u{20}\n"))
+ }
+}
+
+// MARK: - Colour policy
+
+struct FirmwareMatrixColorPolicyTests {
+ /// A pty master is a terminal; a pipe is not. Both are real file
+ /// descriptors, so `isatty` is answering for real here.
+ private func withTTY<T>(_ body: (Int32) throws -> T) rethrows -> T {
+ let fd = posix_openpt(O_RDWR | O_NOCTTY)
+ defer { if fd >= 0 { close(fd) } }
+ return try body(fd)
+ }
+
+ @Test func honoursNoColorClicolorForceAndIsattyPerStream() throws {
+ let pipe = Pipe()
+ let pipeFD = pipe.fileHandleForWriting.fileDescriptor
+ try withTTY { ttyFD in
+ try #require(isatty(ttyFD) != 0, "expected a pty master to be a terminal")
+ #expect(isatty(pipeFD) == 0)
+
+ func colored(_ fd: Int32, _ env: [String: String]) -> Bool {
+ VPhoneStatusStyle.forStream(fd, environment: env).isColored
+ }
+
+ // A terminal colours by default; a pipe does not.
+ #expect(colored(ttyFD, [:]))
+ #expect(!colored(pipeFD, [:]))
+
+ // CLICOLOR_FORCE=1 colours a pipe; any other value does not.
+ #expect(colored(pipeFD, ["CLICOLOR_FORCE": "1"]))
+ #expect(!colored(pipeFD, ["CLICOLOR_FORCE": "0"]))
+ #expect(!colored(pipeFD, ["CLICOLOR_FORCE": "true"]))
+ #expect(!colored(pipeFD, ["CLICOLOR_FORCE": ""]))
+
+ // NO_COLOR wins over both the terminal and CLICOLOR_FORCE …
+ #expect(!colored(ttyFD, ["NO_COLOR": "1"]))
+ #expect(!colored(pipeFD, ["NO_COLOR": "1", "CLICOLOR_FORCE": "1"]))
+ // … but only when it is set to something. Empty is "not set", which
+ // is how both the shell (`-z`) and the Python (falsy) read it.
+ #expect(colored(ttyFD, ["NO_COLOR": ""]))
+ #expect(!colored(pipeFD, ["NO_COLOR": ""]))
+ }
+ try pipe.fileHandleForWriting.close()
+ try pipe.fileHandleForReading.close()
+ }
+}
+
+// MARK: - Exit codes and stream routing
+
+struct FirmwareMatrixCommandLineTests {
+ private func capture(
+ _ body: (FileHandle, FileHandle) -> Int32
+ ) -> (code: Int32, out: String, err: String) {
+ let outPipe = Pipe(), errPipe = Pipe()
+ let code = body(outPipe.fileHandleForWriting, errPipe.fileHandleForWriting)
+ try? outPipe.fileHandleForWriting.close()
+ try? errPipe.fileHandleForWriting.close()
+ let out = String(decoding: outPipe.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
+ let err = String(decoding: errPipe.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
+ return (code, out, err)
+ }
+
+ @Test func listGoesToStdoutAndExitsZero() {
+ let r = Fixture.withReadmeFile { path in
+ capture { out, err in
+ VPhoneFirmwareMatrixCommandLine.list(
+ device: Fixture.d, readmePath: path, downloadURLs: Fixture.urls,
+ environment: [:], stdout: out, stderr: err
+ )
+ }
+ }
+ #expect(r.code == 0)
+ #expect(r.out == Golden.listPlain)
+ #expect(r.err.isEmpty)
+ }
+
+ @Test func anEmptyDeviceListGoesToStderrAndExitsOne() {
+ let r = Fixture.withReadmeFile { path in
+ capture { out, err in
+ VPhoneFirmwareMatrixCommandLine.list(
+ device: "iPhone99,9", readmePath: path, downloadURLs: Fixture.urls,
+ environment: [:], stdout: out, stderr: err
+ )
+ }
+ }
+ #expect(r.code == 1)
+ #expect(r.out.isEmpty)
+ #expect(r.err == "No downloadable IPSWs found for iPhone99,9\n")
+ }
+
+ @Test func aResolvedSelectorGoesToStdoutAndExitsZero() {
+ let r = Fixture.withReadmeFile { path in
+ capture { out, err in
+ VPhoneFirmwareMatrixCommandLine.resolve(
+ device: Fixture.d, version: "26.3", build: "", readmePath: path,
+ downloadURLs: Fixture.urls, environment: [:], stdout: out, stderr: err
+ )
+ }
+ }
+ #expect(r.code == 0)
+ #expect(r.out == Golden.hit)
+ #expect(r.err.isEmpty)
+ }
+
+ /// 2, not 1. `fw_prepare.sh` forwards this status verbatim so a caller can
+ /// tell "pick a build" from "there is no such firmware".
+ @Test func anAmbiguousVersionGoesToStderrAndExitsTwo() {
+ let r = Fixture.withReadmeFile { path in
+ capture { out, err in
+ VPhoneFirmwareMatrixCommandLine.resolve(
+ device: Fixture.d, version: "27.0", build: "", readmePath: path,
+ downloadURLs: Fixture.urls, environment: [:], stdout: out, stderr: err
+ )
+ }
+ }
+ #expect(r.code == 2)
+ #expect(r.out.isEmpty)
+ #expect(r.err == Golden.ambiguousPlain)
+ }
+
+ @Test func aMissGoesToStderrAndExitsOne() {
+ let r = Fixture.withReadmeFile { path in
+ capture { out, err in
+ VPhoneFirmwareMatrixCommandLine.resolve(
+ device: Fixture.d, version: "99.9", build: "", readmePath: path,
+ downloadURLs: Fixture.urls, environment: [:],
+ stdout: out, stderr: err
+ )
+ }
+ }
+ #expect(r.code == 1)
+ #expect(r.out.isEmpty)
+ #expect(r.err == "Unsupported: no downloadable IPSW matched device=iPhone17,3 version=99.9\n")
+ }
+
+ @Test func anUnreadableReadmePathIsNotAnError() {
+ let r = capture { out, err in
+ VPhoneFirmwareMatrixCommandLine.list(
+ device: Fixture.d, readmePath: "/nonexistent/README.md",
+ downloadURLs: Fixture.urls, environment: [:], stdout: out, stderr: err
+ )
+ }
+ #expect(r.code == 0)
+ #expect(r.out.contains("Not Tested"))
+ #expect(!r.out.contains("Supported\u{20}\u{20}\n"))
+ }
+
+ /// The half that is easy to get wrong: each command styles the stream it
+ /// writes to, not the process. `list` writes its table to stdout, so a
+ /// terminal on stderr must not colour it.
+ @Test func listStylesStdoutNotStderr() throws {
+ let fd = posix_openpt(O_RDWR | O_NOCTTY)
+ try #require(fd >= 0)
+ defer { close(fd) }
+ let tty = FileHandle(fileDescriptor: fd, closeOnDealloc: false)
+ let outPipe = Pipe()
+ let code = Fixture.withReadmeFile { path in
+ VPhoneFirmwareMatrixCommandLine.list(
+ device: Fixture.d, readmePath: path, downloadURLs: Fixture.urls,
+ environment: [:], stdout: outPipe.fileHandleForWriting, stderr: tty
+ )
+ }
+ try outPipe.fileHandleForWriting.close()
+ let out = String(decoding: outPipe.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
+ #expect(code == 0)
+ #expect(out == Golden.listPlain)
+ #expect(!out.contains("\u{1B}["))
+ }
+
+ /// And the mirror image: the selector's failures are stderr's, so a
+ /// terminal on stdout must not colour them. This is the case that keeps
+ /// escapes out of `selection="$(resolve_selector_from_downloads …)"`.
+ @Test func resolveStylesStderrNotStdout() throws {
+ let fd = posix_openpt(O_RDWR | O_NOCTTY)
+ try #require(fd >= 0)
+ defer { close(fd) }
+ let tty = FileHandle(fileDescriptor: fd, closeOnDealloc: false)
+ let errPipe = Pipe()
+ let code = Fixture.withReadmeFile { path in
+ VPhoneFirmwareMatrixCommandLine.resolve(
+ device: Fixture.d, version: "99.9", build: "", readmePath: path,
+ downloadURLs: Fixture.urls, environment: [:],
+ stdout: tty, stderr: errPipe.fileHandleForWriting
+ )
+ }
+ try errPipe.fileHandleForWriting.close()
+ let err = String(decoding: errPipe.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
+ #expect(code == 1)
+ #expect(err == "Unsupported: no downloadable IPSW matched device=iPhone17,3 version=99.9\n")
+ #expect(!err.contains("\u{1B}["))
+ }
+}