Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

feat: replace ldid, tar and the first CFW patchers with in-process Swift

Lakr0df7a69f279c
diff --git a/AGENTS.md b/AGENTS.md
index 2d93c822..23cffb22 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -152,8 +152,7 @@ scripts/
├── patchers/ # Python CFW patcher modules
│ └── cfw.py # CFW binary patcher entrypoint
├── resources/ # Resource archives (git submodule)
-├── repos/ # Toolchain source repos (git submodules: trustcache, insert_dylib, libimobiledevice stack)
-├── patches/ # Build-time patches (libirecovery)
+├── repos/ # Toolchain source repos (git submodules: trustcache, insert_dylib)
├── fw_prepare.sh # Download IPSWs, merge cloudOS into iPhone
├── cfw_install.sh # Install CFW (regular)
├── cfw_install_dev.sh # Regular + rpcserver daemon
@@ -165,7 +164,6 @@ scripts/
├── setup_tools.sh # Install deps, build toolchain from submodules, create venv
├── setup_venv.sh # Create Python venv
├── setup_venv_linux.sh # Create Python venv (Linux)
-├── setup_libimobiledevice.sh # Build libimobiledevice stack from scripts/repos submodules
└── tail_jb_patch_logs.sh # Tail JB patch log output
cfw-kit/ # Variant-layered CFW installer, vendored as-is
diff --git a/Makefile b/Makefile
index d3855da9..0d9baeef 100644
--- a/Makefile
+++ b/Makefile
@@ -280,11 +280,16 @@ bundle: build $(INFO_PLIST)
@cp -f $(INFO_PLIST) $(BUNDLE)/Contents/Info.plist
@cp -f sources/AppIcon.icns $(BUNDLE)/Contents/Resources/AppIcon.icns
@cp -f $(SCRIPTS)/vphoned/signcert.p12 $(BUNDLE)/Contents/Resources/signcert.p12
- @cp -f $$(command -v ldid) $(BUNDLE)/Contents/MacOS/ldid
+ @# The bundle is built over whatever is already there, so Contents/MacOS/ldid
+ @# is removed although nothing copies it any more: bundles built before
+ @# VPhoneSign replaced ldid carry the Homebrew one, which is the only thing in
+ @# here linking libcrypto.3 and libplist-2.0.4 and so the only thing failing
+ @# gate 1. It has to go before the seal below, not after — removing nested
+ @# code from a sealed bundle is what makes `codesign -v` report it modified.
+ @rm -f $(BUNDLE)/Contents/MacOS/ldid
@# Order matters: vphone-vm is CFBundleExecutable, so signing it seals the
@# whole bundle and everything beside it counts as nested code. Sign the
@# nested binaries FIRST, or `codesign -v` reports "nested code is modified".
- @codesign --force --sign - $(BUNDLE)/Contents/MacOS/ldid
@codesign --force --sign - $(BUNDLE_BIN)
@codesign --force --sign - $(BUNDLE_LETMEIN)
@codesign --force --sign - $(BUNDLE_ARCHIVE)
diff --git a/Package.swift b/Package.swift
index dcb9882d..69d4e512 100644
--- a/Package.swift
+++ b/Package.swift
@@ -23,6 +23,10 @@ let package = Package(
.product(name: "Capstone", package: "libcapstone-spm"),
.product(name: "Img4tool", package: "libimg4-spm"),
.product(name: "MachOKit", package: "MachOKit"),
+ // The cryptex patcher re-signs what it rewrites. That used to be
+ // three `runProcess("/opt/homebrew/bin/ldid", …)` calls, which is
+ // the one thing in this package that made `make check-aux` fail.
+ "VPhoneSign",
"VPhoneCore",
],
path: "sources/FirmwarePatcher"
@@ -50,6 +54,19 @@ let package = Package(
],
path: "sources/VPhoneArchive"
),
+ // Ad-hoc and PKCS#12 Mach-O code signing, byte for byte what ldid
+ // writes. It replaces ldid, which is the only program this project
+ // shipped that links Homebrew (libcrypto.3, libplist-2.0.4) and so
+ // the only one that failed `make check-aux`. Nothing here is outside
+ // the system frameworks: CryptoKit for the hashes, Security for the
+ // PKCS#12 and the CMS.
+ .target(
+ name: "VPhoneSign",
+ path: "sources/VPhoneSign",
+ linkerSettings: [
+ .linkedFramework("Security"),
+ ]
+ ),
// Everything that touches a running guest: the machine, its window and
// menus, the vsock channel and the host device bridges. It is a library
// so the only executable holding the private virtualization
@@ -84,12 +101,15 @@ let package = Package(
// The user-facing entry point. Note it depends on neither VPhoneVMKit
// nor any of the five frameworks above: it never builds a machine, it
// starts vphone-vm. Adding a dependency on the kit here would quietly
- // undo the split, so don't.
+ // undo the split, so don't. VPhoneArchive is fine and is why `vm export`
+ // still works here: it sits above VPhoneCore and pulls in neither
+ // Virtualization nor AppKit.
.executableTarget(
name: "vphone-cli",
dependencies: [
.product(name: "ArgumentParser", package: "swift-argument-parser"),
"FirmwarePatcher",
+ "VPhoneArchive",
"VPhoneCore",
],
path: "sources/vphone-cli"
@@ -127,5 +147,10 @@ let package = Package(
dependencies: ["VPhoneArchive"],
path: "tests/VPhoneArchiveTests"
),
+ .testTarget(
+ name: "VPhoneSignTests",
+ dependencies: ["VPhoneSign"],
+ path: "tests/VPhoneSignTests"
+ ),
]
)
diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.md
index b94cebd8..b01ffd8a 100644
--- a/research/0_binary_patch_comparison.md
+++ b/research/0_binary_patch_comparison.md
@@ -327,8 +327,12 @@ System/Library/ExtensionKit/Extensions/HostInferenceProviderService.appex/HostIn
the first byte of the cstring through `DSCChunks.write_at_vma`.
Pure Python. Whitelist-based by design so an operator can comment
out individual entries to bisect.
-* `scripts/patchers/cfw.py patch-hv-vmm <binary>` —
- standalone-Mach-O subcommand (used for the 6 on-device files).
+* ~~`scripts/patchers/cfw.py patch-hv-vmm <binary>`~~ — **gone.** The
+ standalone-Mach-O subcommand and its backing patcher
+ (`cfw_patch_hv_vmm_rootfs.py`) were removed with item 8 in the
+ blacklist-flip redesign; the 6 on-device files no longer need an
+ SSH-time patch. `scripts/patch_hv_vmm_userland.sh:65-73` documents
+ why the wrapper's standalone branch has no honest substitute.
* `scripts/patchers/cfw.py patch-hv-vmm-dsc <chunks_dir>` —
DSC subcommand (used while the SystemOS Cryptex DMG is still
mounted on the host, before the device copy).
diff --git a/research/hv_vmm_present_usermode_xrefs.md b/research/hv_vmm_present_usermode_xrefs.md
index 8ff68121..ae837d75 100644
--- a/research/hv_vmm_present_usermode_xrefs.md
+++ b/research/hv_vmm_present_usermode_xrefs.md
@@ -411,8 +411,12 @@ name-to-MIB translation.
a modified byte; the CDHash side-effect (CD blob hash changes
when slots change) is accepted by TXM at DSC mount time
(empirically verified — device boots with re-attested DSC).
-* `scripts/patchers/cfw.py` — adds `patch-hv-vmm <binary>` and
- `patch-hv-vmm-dsc <chunks_dir>` subcommands.
+* `scripts/patchers/cfw.py` — adds the `patch-hv-vmm-dsc <chunks_dir>`
+ subcommand. (A `patch-hv-vmm <binary>` subcommand existed when this
+ was written and no longer does: it and `cfw_patch_hv_vmm_rootfs.py`
+ were removed in the blacklist-flip redesign, which made the
+ standalone rootfs mangle unnecessary. See item 8 in
+ `research/0_binary_patch_comparison.md`.)
* `scripts/patch_hv_vmm_userland.sh` — thin wrapper used by the
install scripts.
* `scripts/cfw_install_dev.sh` — DSC patch is applied while the
diff --git a/research/p2_dfu_spike.md b/research/p2_dfu_spike.md
new file mode 100644
index 00000000..d59e7517
--- /dev/null
+++ b/research/p2_dfu_spike.md
@@ -0,0 +1,90 @@
+# P2.0 — can libirecovery see the VM's virtual DFU endpoint?
+
+> 2026-09-23, branch `vphone-intg-update`. **Answer: yes.**
+>
+> Plan section P2.0 marks this the largest unknown in P2 and says to stop and
+> re-evaluate if it fails, rather than vendoring idevicerestore on an assumption.
+
+## Why it was a real question
+
+The restore path today goes through pymobiledevice3's `IRecv`, which is **pyusb**.
+libirecovery on macOS goes through **IOKit USB**. Different transport, so whether
+one works tells you nothing about the other, and the whole of P2.1/P2.2 is wasted
+work if the IOKit path cannot see a Virtualization.framework virtual endpoint.
+
+## Result
+
+VM booted with `--dfu` from a bare bundle — `vphone-cli vm new` output only, no
+restore, no firmware, no CFW:
+
+```
+libirecovery DFU probe
+ target ecid : 206C763772858301
+ attempts : 10
+ RESULT : FOUND
+ ecid : 206C763772858301
+ cpid : 0xfe01
+ bdid : 0x90
+ cprv/cpfm : 0x0 / 0x3
+ srtg : mBoot-20457.1.29
+ serial : SDOM:01 CPID:FE01 CPRV:00 CPFM:03 SCEP:01 BDID:90
+ ECID:206C763772858301 IBFL:3C SRTG:[mBoot-20457.1.29]
+ ap nonce : 32 bytes
+ sep nonce : 20 bytes
+```
+
+`irecv_open_with_ecid_and_attempts` succeeds and `irecv_get_device_info` returns a
+fully populated struct. **The ECID matches exactly** what `vphone-vm` derived from
+`machineIdentifier` (`VPhoneVirtualMachine.swift:296-309`), which also confirms that
+derivation independently — two different code paths agreeing on
+`206C763772858301`.
+
+AP and SEP nonces are present and correctly sized, so personalisation has what it
+needs.
+
+## What this also established
+
+Getting here required the entitlement split to work end to end under a hostile
+amfid, so it settled three queue items at once:
+
+- `vphone-vm` **can start a VM holding the private entitlements alone**. This was
+ the item everything in step 1 rested on, and it was unproven until now.
+- `vphone-letmein exec --hold 10` is enough to cover the launch: the VM was running
+ and healthy after `amfid restored`.
+- `--detach` works — the patch is removed after the hold and the guest keeps
+ running (`detached; pid 33232 keeps running`).
+
+Also proven in passing: with amfid refusing, `vphone-cli --help` still runs and
+`VPHONE_LETMEIN=never` produces the full explanatory error rather than a `Killed: 9`.
+That is the entire point of moving the entitlements off the entry point.
+
+## Reproducing it
+
+The spike is ~60 lines of Swift against the system libirecovery. Note the link name
+is **`-lirecovery-1.0`**, not `-lirecovery` — Homebrew ships
+`libirecovery-1.0.dylib` with no unversioned symlink. That detail carries into P2.1.
+
+```
+swiftc -O -import-objc-header bridge.h main.swift \
+ -Xcc -I/opt/homebrew/include -L/opt/homebrew/lib -lirecovery-1.0 -o dfu_spike
+./dfu_spike <ecid-hex> <attempts>
+```
+
+Boot the VM first, leaving it running:
+
+```
+sudo .../vphone-letmein exec --hold 10 --detach -- \
+ .../vphone-vm --config ~/.vphone/VMs/<name>/config.plist --dfu
+```
+
+With no VM up, the probe exits 1 with `Unable to connect to device (-3)` — so a
+negative result is distinguishable from a broken harness.
+
+## Still open, and deliberately not answered here
+
+Plan section P2.2 asks that **FDR equivalence** be confirmed as part of this spike.
+It was not, and cannot be from device enumeration alone: pymobiledevice3 runs
+`Restore(..., ignore_fdr=False)`, and idevicerestore's FDR handling is internal.
+Whether the two behave the same only shows up during an actual restore. That stays
+an open risk on P2.2 and must not be assumed away — it is called out here so the
+next person does not read "P2.0 passed" as covering it.
diff --git a/scripts/build.sh b/scripts/build.sh
index dd68d03e..12ba3f39 100755
--- a/scripts/build.sh
+++ b/scripts/build.sh
@@ -85,12 +85,17 @@ cp -f "$ARCHIVE_BINARY" "$BUNDLE_ARCHIVE"
cp -f "$INFO_PLIST" "${BUNDLE}/Contents/Info.plist"
cp -f "sources/AppIcon.icns" "${BUNDLE}/Contents/Resources/AppIcon.icns"
cp -f "scripts/vphoned/signcert.p12" "${BUNDLE}/Contents/Resources/signcert.p12"
-cp -f "$(command -v ldid)" "${BUNDLE}/Contents/MacOS/ldid"
+# The bundle is built over whatever is already there, so Contents/MacOS/ldid is
+# removed although nothing copies it any more: bundles built before VPhoneSign
+# replaced ldid carry the Homebrew one, which is the only thing in here linking
+# libcrypto.3 and libplist-2.0.4 and so the only thing failing gate 1. It has to
+# go before the seal below, not after — removing nested code from a sealed
+# bundle is what makes `codesign -v` report it as modified.
+rm -f "${BUNDLE}/Contents/MacOS/ldid"
# Order matters: vphone-vm is CFBundleExecutable, so signing it seals the whole
# bundle, and everything beside it in Contents/MacOS counts as nested code.
# Sign the nested binaries FIRST or the seal captures them in an earlier state
# and `codesign -v` on the bundle reports "nested code is modified or invalid".
-codesign --force --sign - "${BUNDLE}/Contents/MacOS/ldid"
codesign --force --sign - "$BUNDLE_BIN"
codesign --force --sign - "$BUNDLE_LETMEIN"
codesign --force --sign - "$BUNDLE_ARCHIVE"
diff --git a/scripts/cfw_install_exp.sh b/scripts/cfw_install_exp.sh
index 9544e0a7..e8e307b7 100755
--- a/scripts/cfw_install_exp.sh
+++ b/scripts/cfw_install_exp.sh
@@ -51,6 +51,25 @@ _resolve_python3() {
}
PYTHON3="$(_resolve_python3)"
+# ── vphone-cli resolver — the Swift CFW patchers the phases below call ─
+# Same order as scripts/cfw_install_host.sh and cfw-kit/run.sh: VPHONE_CLI_BIN
+# when a vphone-cli subcommand invoked us, otherwise a dev tree or the .app,
+# where scripts/ sits in Contents/Resources and the binaries are one level up
+# in MacOS. Never `command -v` — the binary has to be the one we built beside
+# these scripts, not whatever else is on PATH.
+# Resolved up front, before anything is mounted or written: a missing binary
+# should stop the run here, not halfway through with volumes attached.
+VPHONE_CLI="${VPHONE_CLI_BIN:-}"
+if [[ -z "$VPHONE_CLI" ]]; then
+ for candidate in "${SCRIPT_DIR:h}/.build/release/vphone-cli" "${SCRIPT_DIR:h:h}/MacOS/vphone-cli"; do
+ [[ -x "$candidate" ]] && { VPHONE_CLI="$candidate"; break }
+ done
+fi
+[[ -x "$VPHONE_CLI" ]] || {
+ echo "[-] cannot find vphone-cli (the JB/EXP phases need it) — run 'make build'" >&2
+ exit 1
+}
+
# ════════════════════════════════════════════════════════════════
# Step 1: Run base CFW install (skip halt — we continue with JB phases)
# ════════════════════════════════════════════════════════════════
@@ -85,7 +104,8 @@ if [[ -z "$JB_RESTORE_DIR" ]]; then
elif [[ ! -f "$JB_SYSOS_DMG" ]]; then
# Not yet decrypted — decrypt to the cache location cfw_install.sh expects.
echo "[*] hv_vmm DSC patch: decrypting SystemOS into cache..."
- JB_CRYPTEX_SYSOS=$("$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" cryptex-paths "$JB_RESTORE_DIR/iPhone-BuildManifest.plist" | head -1)
+ # Two lines out, SystemOS first then AppOS; head -1 takes SystemOS.
+ JB_CRYPTEX_SYSOS=$("$VPHONE_CLI" cfw cryptex-paths "$JB_RESTORE_DIR/iPhone-BuildManifest.plist" | head -1)
JB_AEA_KEY=$(ipsw fw aea --key "$JB_RESTORE_DIR/$JB_CRYPTEX_SYSOS")
aea decrypt -i "$JB_RESTORE_DIR/$JB_CRYPTEX_SYSOS" -o "$JB_SYSOS_DMG" -key-value "$JB_AEA_KEY"
fi
@@ -401,7 +421,10 @@ if [[ "$DISABLE_LAUNCHD_HOOK" == "1" ]]; then
echo " [*] Skipping launchdhook dylib injection (DISABLE_LAUNCHD_HOOK=1)"
elif [[ -d "$JB_INPUT_DIR/basebin" ]]; then
echo " Injecting weak dylib load for /b (short launchdhook alias)..."
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" inject-dylib "$TEMP_DIR/launchd" "/b"
+ # Stays exactly here: the injector leaves launchd unsigned, so it has to
+ # run after the `ldid -e` entitlement capture above and before the
+ # patch-launchd-jetsam + ldid re-sign below.
+ "$VPHONE_CLI" cfw inject-dylib "$TEMP_DIR/launchd" "/b"
else
echo " [!] BaseBin is missing; skipping launchdhook injection"
fi
@@ -459,7 +482,7 @@ case "$BASE_IOS" in
cp "$CAMPO_BIN" "$TEMP_DIR/Campo"
ldid -e "$TEMP_DIR/Campo" > "$TEMP_DIR/Campo.entitlements" 2>/dev/null || true
if [[ -s "$TEMP_DIR/Campo.entitlements" ]]; then
- "$PYTHON3" "$SCRIPT_DIR/patchers/campo_mach_lookup_exceptions.py" "$TEMP_DIR/Campo.entitlements"
+ "$VPHONE_CLI" cfw patch-campo-entitlements "$TEMP_DIR/Campo.entitlements"
ldid_sign_ent "$TEMP_DIR/Campo" "$TEMP_DIR/Campo.entitlements"
cp -R "$TEMP_DIR/Campo" "$CAMPO_BIN"
/bin/chmod 0755 "$CAMPO_BIN"
@@ -699,16 +722,7 @@ if [[ -f "$SETUP_PLIST" ]]; then
# Inject into launchd.plist so launchd starts it at boot
echo " Injecting com.vphone.jb-setup into launchd.plist..."
cp "$MNT1/System/Library/xpc/launchd.plist" "$TEMP_DIR/launchd.plist"
- "$PYTHON3" -c "
-import plistlib, sys
-with open(sys.argv[1], 'rb') as f:
- target = plistlib.load(f)
-with open(sys.argv[2], 'rb') as f:
- daemon = plistlib.load(f)
-target.setdefault('LaunchDaemons', {})['/System/Library/LaunchDaemons/com.vphone.jb-setup.plist'] = daemon
-with open(sys.argv[1], 'wb') as f:
- plistlib.dump(target, f, sort_keys=False)
-" "$TEMP_DIR/launchd.plist" "$SETUP_PLIST"
+ "$VPHONE_CLI" cfw inject-daemon "$TEMP_DIR/launchd.plist" "$SETUP_PLIST" --name com.vphone.jb-setup
cp -R "$TEMP_DIR/launchd.plist" "$MNT1/System/Library/xpc/launchd.plist"
/bin/chmod 0644 $MNT1/System/Library/xpc/launchd.plist
echo " [+] com.vphone.jb-setup.plist injected into launchd.plist"
@@ -747,7 +761,7 @@ else
JB6_DT_LOCAL="$TEMP_DIR/devicetree.img4"
if [[ -e "$JB6_DT_REMOTE" ]]; then
cp "$JB6_DT_REMOTE" "$JB6_DT_LOCAL"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw_patch_post_restore_dt.py" "$JB6_DT_LOCAL"
+ "$VPHONE_CLI" cfw patch-post-restore-dt "$JB6_DT_LOCAL"
cp -R "$JB6_DT_LOCAL" "$JB6_DT_REMOTE"
/usr/sbin/chown 0:0 $JB6_DT_REMOTE
/bin/chmod 0644 $JB6_DT_REMOTE
@@ -794,8 +808,10 @@ if [[ -n "${SPOOF_BUILD:-}" ]]; then
if [[ -e "$jb7_remote" ]]; then
jb7_local="$TEMP_DIR/$(echo "$jb7_remote" | tr '/' '_').plist"
cp "$jb7_remote" "$jb7_local"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw_patch_build_version.py" \
- "$jb7_local" "$SPOOF_BUILD"
+ # The SPOOF_BUILD gate stays in the shell above: the Swift
+ # subcommand has no gate of its own, exactly as the Python had
+ # none, and always rewrites the build it is handed.
+ "$VPHONE_CLI" cfw patch-build-version "$jb7_local" "$SPOOF_BUILD"
cp -R "$jb7_local" "$jb7_remote"
else
echo " [-] $jb7_remote not found, skipping"
diff --git a/scripts/cfw_install_jb.sh b/scripts/cfw_install_jb.sh
index 672a9b18..6fbd91b5 100755
--- a/scripts/cfw_install_jb.sh
+++ b/scripts/cfw_install_jb.sh
@@ -35,6 +35,25 @@ _resolve_python3() {
}
PYTHON3="$(_resolve_python3)"
+# ── vphone-cli resolver — the Swift CFW patchers the JB phases call ─
+# Same order as scripts/cfw_install_host.sh and cfw-kit/run.sh: VPHONE_CLI_BIN
+# when a vphone-cli subcommand invoked us, otherwise a dev tree or the .app,
+# where scripts/ sits in Contents/Resources and the binaries are one level up
+# in MacOS. Never `command -v` — the binary has to be the one we built beside
+# these scripts, not whatever else is on PATH.
+# Resolved up front, before anything is mounted or written: a missing binary
+# should stop the run here, not halfway through JB-1 with volumes attached.
+VPHONE_CLI="${VPHONE_CLI_BIN:-}"
+if [[ -z "$VPHONE_CLI" ]]; then
+ for candidate in "${SCRIPT_DIR:h}/.build/release/vphone-cli" "${SCRIPT_DIR:h:h}/MacOS/vphone-cli"; do
+ [[ -x "$candidate" ]] && { VPHONE_CLI="$candidate"; break }
+ done
+fi
+[[ -x "$VPHONE_CLI" ]] || {
+ echo "[-] cannot find vphone-cli (the JB phases need it) — run 'make build'" >&2
+ exit 1
+}
+
# ════════════════════════════════════════════════════════════════
# Step 1: Run base CFW install, then continue with JB phases
# ════════════════════════════════════════════════════════════════
@@ -236,7 +255,10 @@ if [[ "$DISABLE_LAUNCHD_HOOK" == "1" ]]; then
echo " [*] Skipping launchdhook dylib injection (DISABLE_LAUNCHD_HOOK=1)"
elif [[ -d "$JB_INPUT_DIR/basebin" ]]; then
echo " Injecting weak dylib load for /b (short launchdhook alias)..."
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" inject-dylib "$TEMP_DIR/launchd" "/b"
+ # Stays exactly here: the injector leaves launchd unsigned, so it has to
+ # run after the `ldid -e` entitlement capture above and before the
+ # patch-launchd-jetsam + ldid re-sign below.
+ "$VPHONE_CLI" cfw inject-dylib "$TEMP_DIR/launchd" "/b"
else
echo " [!] BaseBin is missing; skipping launchdhook injection"
fi
@@ -294,7 +316,7 @@ case "$BASE_IOS" in
cp "$CAMPO_BIN" "$TEMP_DIR/Campo"
ldid -e "$TEMP_DIR/Campo" > "$TEMP_DIR/Campo.entitlements" 2>/dev/null || true
if [[ -s "$TEMP_DIR/Campo.entitlements" ]]; then
- "$PYTHON3" "$SCRIPT_DIR/patchers/campo_mach_lookup_exceptions.py" "$TEMP_DIR/Campo.entitlements"
+ "$VPHONE_CLI" cfw patch-campo-entitlements "$TEMP_DIR/Campo.entitlements"
ldid_sign_ent "$TEMP_DIR/Campo" "$TEMP_DIR/Campo.entitlements"
cp -R "$TEMP_DIR/Campo" "$CAMPO_BIN"
/bin/chmod 0755 "$CAMPO_BIN"
@@ -457,16 +479,7 @@ if [[ -f "$SETUP_PLIST" ]]; then
# Inject into launchd.plist so launchd starts it at boot
echo " Injecting com.vphone.jb-setup into launchd.plist..."
cp "$MNT1/System/Library/xpc/launchd.plist" "$TEMP_DIR/launchd.plist"
- "$PYTHON3" -c "
-import plistlib, sys
-with open(sys.argv[1], 'rb') as f:
- target = plistlib.load(f)
-with open(sys.argv[2], 'rb') as f:
- daemon = plistlib.load(f)
-target.setdefault('LaunchDaemons', {})['/System/Library/LaunchDaemons/com.vphone.jb-setup.plist'] = daemon
-with open(sys.argv[1], 'wb') as f:
- plistlib.dump(target, f, sort_keys=False)
-" "$TEMP_DIR/launchd.plist" "$SETUP_PLIST"
+ "$VPHONE_CLI" cfw inject-daemon "$TEMP_DIR/launchd.plist" "$SETUP_PLIST" --name com.vphone.jb-setup
cp -R "$TEMP_DIR/launchd.plist" "$MNT1/System/Library/xpc/launchd.plist"
/bin/chmod 0644 $MNT1/System/Library/xpc/launchd.plist
echo " [+] com.vphone.jb-setup.plist injected into launchd.plist"
diff --git a/scripts/fw_prepare.sh b/scripts/fw_prepare.sh
index a8076400..9e8d527b 100755
--- a/scripts/fw_prepare.sh
+++ b/scripts/fw_prepare.sh
@@ -66,6 +66,27 @@ require_command() {
command -v "$1" >/dev/null 2>&1 || die "'$1' not found"
}
+# Locate one of this project's own binaries (vphone-cli, vphone-archive).
+# Same resolution order as scripts/cfw_install_host.sh and cfw-kit/run.sh:
+# VPHONE_CLI_BIN when a vphone-cli subcommand invoked us — the wanted binary is
+# its sibling — otherwise a dev tree or the .app, where scripts/ sits in
+# Contents/Resources and the binaries are one level up in MacOS. Deliberately
+# not `command -v`: these have to be the binaries we built, not another copy
+# that happens to be on PATH. Prints the path; returns non-zero when it finds
+# nothing, so the caller can `die` with something a user can act on.
+resolve_vphone_binary() {
+ local name="$1" proj_root candidate
+ proj_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+ if [[ -n "${VPHONE_CLI_BIN:-}" ]]; then
+ candidate="$(dirname "$VPHONE_CLI_BIN")/$name"
+ [[ -x "$candidate" ]] && { printf '%s\n' "$candidate"; return 0; }
+ fi
+ for candidate in "$proj_root/.build/release/$name" "$(dirname "$proj_root")/MacOS/$name"; do
+ [[ -x "$candidate" ]] && { printf '%s\n' "$candidate"; return 0; }
+ done
+ return 1
+}
+
source_hash_suffix() {
local src="$1"
if command -v shasum >/dev/null 2>&1; then
@@ -396,14 +417,22 @@ fetch() {
}
extract() {
- local zip="$1" cache="$2" out="$3"
+ local zip="$1" cache="$2" out="$3" archive_bin
if [[ -d "$cache" && -n "$(ls -A "$cache" 2>/dev/null)" ]]; then
echo "==> Cached: ${cache##*/}"
else
rm -rf "$cache"
echo "==> Extracting ${zip##*/} ..."
mkdir -p "$cache"
- unzip -oq "$zip" -d "$cache"
+ # vphone-archive instead of unzip: libarchive in-process, measured at
+ # 0.75s against unzip's 4.97s on a real 1.2 GB IPSW, with identical
+ # output — 88 files, 10 dirs, every content digest and mode matching.
+ # The extractor's host preset applies the umask and never restores
+ # setuid, which is what `unzip` did here, and the cache directory is
+ # freshly removed above so there is nothing to overwrite (`unzip -o`).
+ archive_bin="$(resolve_vphone_binary vphone-archive)" \
+ || die "vphone-archive not found — run 'make build'"
+ "$archive_bin" extract -f "$zip" -C "$cache"
chmod -R u+w "$cache"
fi
rm -rf "$out"
@@ -689,17 +718,8 @@ cp -n "${CLOUDOS_DIR}"/Firmware/*.dmg.trustcache "$IPHONE_DIR/Firmware"/ 2>/dev/
cp "$IPHONE_DIR/BuildManifest.plist" "$IPHONE_DIR/iPhone-BuildManifest.plist"
echo "==> Generating hybrid plists ..."
-# VPHONE_CLI_BIN is set when a vphone-cli subcommand invokes this script; the
-# fallbacks cover being run by hand from a dev tree or from inside the .app,
-# where scripts/ sits in Contents/Resources and the binaries are in MacOS.
-PROJ_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-VPHONE_CLI="${VPHONE_CLI_BIN:-}"
-if [[ -z "$VPHONE_CLI" ]]; then
- for candidate in "$PROJ_ROOT/.build/release/vphone-cli" "$(dirname "$PROJ_ROOT")/MacOS/vphone-cli"; do
- [[ -x "$candidate" ]] && { VPHONE_CLI="$candidate"; break; }
- done
-fi
-[[ -x "$VPHONE_CLI" ]] || { echo "ERROR: cannot find vphone-cli to generate the hybrid plists" >&2; exit 1; }
+VPHONE_CLI="$(resolve_vphone_binary vphone-cli)" \
+ || die "cannot find vphone-cli to generate the hybrid plists — run 'make build'"
"$VPHONE_CLI" fw manifest "$IPHONE_DIR" "$CLOUDOS_DIR"
echo "==> Cleaning up ..."
diff --git a/scripts/patch_hv_vmm_userland.sh b/scripts/patch_hv_vmm_userland.sh
index a6fb49b9..052613f1 100755
--- a/scripts/patch_hv_vmm_userland.sh
+++ b/scripts/patch_hv_vmm_userland.sh
@@ -1,7 +1,7 @@
#!/bin/zsh
# patch_hv_vmm_userland.sh — Apply the user-mode hv_vmm_present patch.
#
-# Three operations, chosen by the first arg:
+# Two operations, chosen by the first arg:
#
# dsc <chunks_dir>
# Patch the canonical sysctlbyname("kern.hv_vmm_present", ...) sites
@@ -11,10 +11,6 @@
# Skips the compute/accel dylibs (CoreML, Espresso, ANE, CoreRE,
# RenderBox, WebGPU, caulk, IOSurfaceAccelerator).
#
-# standalone <binary>
-# Patch a single standalone Mach-O file in place. Idempotent.
-# Caller is responsible for re-signing (ldid).
-#
# watchdogd <binary>
# Surgical 2-instruction patch of /usr/libexec/watchdogd that
# forces its cached "am I a VM?" byte to 1 regardless of the
@@ -54,7 +50,6 @@ usage() {
cat <<EOF >&2
Usage:
$0 dsc <chunks_dir>
- $0 standalone <binary>
$0 watchdogd <binary>
EOF
exit 2
@@ -69,11 +64,16 @@ case "$op" in
echo "[*] Patching hv_vmm_present consumers in DSC chunks under: $1"
"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-hv-vmm-dsc "$1"
;;
- standalone)
- (( $# >= 1 )) || usage
- echo "[*] Patching hv_vmm_present consumers in: $1"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-hv-vmm "$1"
- ;;
+ # `standalone <binary>` used to live here and called
+ # `cfw.py patch-hv-vmm`, which no longer exists: that subcommand and its
+ # backing patcher (cfw_patch_hv_vmm_rootfs.py) were removed, so the op had
+ # been falling through cfw.py's unknown-command branch and exiting 1. It is
+ # deleted rather than retargeted because nothing in the repo invokes it and
+ # there is no honest substitute — `patch-hv-vmm-dsc` takes a directory of
+ # DSC chunks, not a Mach-O, and `patch-watchdogd` is specific to
+ # watchdogd's cached byte. EXP now covers user-mode hv_vmm_present with
+ # `dsc` (every consumer inside the shared cache) plus `watchdogd` (the one
+ # standalone binary still holding its own copy).
watchdogd)
(( $# >= 1 )) || usage
echo "[*] Patching watchdogd hv_vmm_present cache in: $1"
diff --git a/scripts/patchers/README_reference_capture.md b/scripts/patchers/README_reference_capture.md
new file mode 100644
index 00000000..dac89506
--- /dev/null
+++ b/scripts/patchers/README_reference_capture.md
@@ -0,0 +1,313 @@
+# Capturing the patcher reference snapshot
+
+Migration plan **P1.0**, the step marked 不可跳过. These patches rewrite pages
+TXM hashes, so a wrong byte in the Swift port is a boot panic, not a failing
+test. Capture the reference off a real install first; port against it second.
+
+Capture is a pure observer — a patch run with it on produces a byte-identical
+output file to one with it off. Turning it on during a real install is safe.
+
+The one thing it will do to a run is **stop it**. If the input it is asked to
+describe cannot yield an honest record, the patcher raises `CaptureError` before
+its write rather than storing a false one. That never fires on the capture this
+page describes — one clean pass over pristine inputs — and what it catches is
+[re-running a capture into a root that already holds one](#re-running-a-capture).
+
+---
+
+## The whole capture, in one environment variable
+
+```zsh
+cd <repo>
+VPHONE_PATCH_RECORDS="$PWD/ipsws/patch_refactor_input" make cfw_install_exp SPOOF_BUILD=23B85
+```
+
+That is it. The variable survives the installer's `sudo -E` re-exec and its
+inner `env` call, and every patcher — invoked through `cfw.py`, run as its own
+script, or called from Swift — picks it up on its own. No shell edit, no flag
+per call site.
+
+**The install runs as root, so the capture lands root-owned.** Afterwards:
+
+```zsh
+sudo chown -R "$(id -un)" ipsws/patch_refactor_input
+```
+
+For a single patcher outside an install, the flag does the same thing:
+
+```zsh
+.venv/bin/python3 scripts/patchers/cfw.py patch-watchdogd <binary> \
+ --emit-records ipsws/patch_refactor_input
+```
+
+`--emit-records` is accepted by every `cfw.py` subcommand and by
+`cfw_patch_build_version.py`, `cfw_patch_post_restore_dt.py` and
+`campo_mach_lookup_exceptions.py`. The root defaults to
+`ipsws/patch_refactor_input` if you leave it off.
+
+Because the value is optional, a `<root>` written separately from the flag has
+to look like a path — a `/` in it, a leading `~`, or a directory that already
+exists — and may not be a subcommand name. So
+`cfw.py --emit-records patch-seputil <bin>` reads as the bare flag plus a
+subcommand, not as a request to capture into `./patch-seputil/`. For a root that
+is a bare new name, use `--emit-records=<root>`.
+
+---
+
+## Two runs cover the matrix
+
+`cfw_install.sh` reads `ProductVersion` off the mounted SystemOS and branches on
+it, so no single install touches all 19 patchers. **`VARIANT=exp` on an iOS 26
+base and on an iOS 27 base is the whole matrix** — exp chains `cfw_install.sh`,
+so it is a superset of regular, and `dev` adds nothing exp does not already have.
+
+| capture run | picks up |
+| --- | --- |
+| `cfw_install_exp` on **any** base | `seputil`, `launchd_cache_loader`, `mobileactivationd`, `inject_daemons`, `dropbear_plist`, `launchd_jetsam`, `inject_dylib`, `watchdogd`, `hv_vmm_dsc`, `camera_dsc`, `post_restore_dt`, `build_version` (needs `SPOOF_BUILD`), `campo_mach_lookup` |
+| … on an **iOS 26 / 18** base | + `iomfb_swapend` |
+| … on an **iOS 27** base | + `dsc_maxslide`, `lsd_embedded_reg`, `xpc_lwcr`, `lockdown_mode`, `iomfb_force_kern`, `diskimagesiod` |
+
+`dsc_maxslide` self-gates to a no-op on a base whose cache already fits. To
+capture it on a non-27 base anyway, add `FORCE_DSC_MAXSLIDE=1`.
+
+Capture the same variant on more iOS builds than these two — the reference is
+per build, and a patcher that silently finds nothing on a new build is exactly
+what plan risk R7 is about. **Give each build its own root.** A root holds one
+copy of each input under `raw_payloads/`, and `PatchComparisonTests.swift`
+replays the port against that one copy and asserts the record count matches, so
+a root can only describe one build.
+
+---
+
+## Re-running a capture
+
+Records from several runs merge into one `<group>.json`, because one install
+legitimately runs a patcher over several files — the SystemOS and AppOS
+cryptexes both have a `launchd.plist`. Records for the same *site* collapse; the
+site is `(patchID, component, fileOffset, source path)`, not the bytes.
+
+> The site key used to end in the source **basename**, with this same paragraph
+> given as the reason — which is self-refuting: if both cryptexes hold a file
+> called `launchd.plist`, the basename is exactly what fails to tell them apart.
+> It silently dropped the second cryptex's record, so a correct port would then
+> fail `comparePatchRecords()` on count (2 vs 1). Use the full path. The keying
+> is deliberately on the site rather than the bytes because two of these
+> patchers are not idempotent and a re-run lands a genuinely new record at a
+> *different* offset — see the re-capture guards below.
+
+What does **not** work is running a capture twice over the same tree, and the
+capture now refuses it instead of quietly producing a wrong reference:
+
+```
+CaptureError: re-capture refused: <path> ... The file has been patched since —
+recording it as an original would describe the wrong bytes. Restore the pristine
+input, or capture into a fresh root: one root per (variant x iOS build).
+```
+
+The reason it cannot be allowed to proceed is that the capture reads
+`originalBytes` off the file on disk. On a second pass the patcher reads its own
+output back and calls it the original, and two patchers are not idempotent —
+`patch_launchd_cache_loader` and `patch_launchd_jetsam` each find a *second*,
+different site on an already-patched binary. Those land as brand-new records at
+offsets the pristine image never had patched, and `comparePatchRecords()`
+asserts on the record count, so a **correct** Swift port then fails against the
+reference. A record where `originalBytes == patchedBytes` is refused outright
+for the same reason: it asserts something false about the pristine bytes, and a
+port that writes nothing satisfies it.
+
+To redo a capture, delete the root (or capture into a new one) and re-extract
+the inputs.
+
+The non-idempotency itself is a separate, pre-existing bug in
+`cfw_patch_cache_loader.py` and `cfw_patch_jetsam.py` — it reproduces with
+capture off. Neither patcher checks whether the site it found is already
+patched, so on a second pass the first candidate no longer matches the shape
+they search for and the scan walks on to the next one:
+
+* `patch_launchd_cache_loader` NOPs `0xC7C`, then on a re-run `_find_nearby_branch`
+ skips the `nop` it wrote and returns the *next* conditional branch after the
+ same `bl` (`0xC84`).
+* `patch_launchd_jetsam` rewrites the conditional at `0xFA98` to `b`, which drops
+ out of `cond_mnemonics`. `cfw_patch_jetsam.py:117-136` scans *backward* keeping
+ the farthest-back match, so losing `0xFA98` makes it fall back to a **later**
+ candidate, nearer the xref (`0xFAB0` > `0xFA98`) — not an earlier one.
+
+The fix in both is the same shape and does not need new anchors, but it has to
+live **inside the scan**, not after it. Checking the picked site is useless here:
+on a re-run neither patcher picks the previously patched site. Decoded from the
+real twice-patched binaries, run 2 picks `0xC84` holding a live `cbnz x0, #0xca4`
+(the `nop` is back at `0xC7C`), and `0xFAB0` holding a live `b.ne #0xfaec` (the
+`b` is back at `0xFA98`). So: `_find_nearby_branch` must treat a `nop` at a
+candidate position as already-patched, and `cfw_patch_jetsam.py`'s backward loop
+must treat an unconditional `b` into a return block as already-patched — both
+`0xFA98` and `0xFAB0` branch to the same `0xfaec`, so the target test still
+applies. Both would then report no-op on a re-run, the way `patch_watchdogd` and
+the DSC patchers already do.
+
+---
+
+## Where it lands
+
+```
+ipsws/patch_refactor_input/
+├── reference_patches/
+│ ├── <patcher>.json one JSON array per patcher
+│ ├── _capture_log.jsonl one line per run: group, counts, root, argv, time
+│ └── _capture_warnings.jsonl anything the capture could store but you should
+│ not trust; absent on a clean capture
+└── raw_payloads/
+ ├── <binary> the pre-patch input, to replay the port against
+ ├── <binary>.<sha12> a *different* input with the same basename — the
+ │ second patcher in a chain sees the first one's
+ │ output, and each record names the one it used
+ ├── <binary>[.<sha12>].patched
+ │ only when the patch changed the file's length
+ └── dsc_pages/ 16 KiB before/after pairs around each DSC patch
+```
+
+`_capture_log.jsonl` carries `capture_root` and `env_var_set` because `argv`
+alone does not answer how capture was turned on: `cfw.py` strips
+`--emit-records` out of `sys.argv[:]` before dispatch, so its subcommands log an
+argv with no flag in it, while `cfw_patch_build_version.py`,
+`cfw_patch_post_restore_dt.py` and `campo_mach_lookup_exceptions.py` strip a
+*local* argv and do log the flag. `VPHONE_PATCH_RECORDS` shows in neither.
+
+The directory names are the convention
+`tests/FirmwarePatcherTests/PatchComparisonTests.swift` already reads from.
+`ipsws/` is gitignored, so none of this is committed.
+
+The DSC is ~7 GiB and is **not** copied. What `raw_payloads/dsc_pages/` holds is
+the 16 KiB code-signature page around each patch, before and after — enough for
+P1.1's slot-hash cross-check, not enough to re-run a DSC patcher's *finder*.
+That one needs the real cache on the machine.
+
+---
+
+## Is the capture complete?
+
+```zsh
+.venv/bin/python3 scripts/patchers/cfw.py records-status
+```
+
+It lists all 19 required patchers, prints the record count for each, names the
+ones still missing, and exits non-zero until every one is captured — or until
+every captured record can actually fail a wrong port. Pass a root as an argument
+if it is not `ipsws/patch_refactor_input`.
+
+A patcher showing `MISSING` after an install means one of three things: that
+iOS base gated it off (the table above), its input was absent, or it found
+nothing — and the third is the one to chase, in `_capture_log.jsonl` and the
+install log.
+
+---
+
+## The record format
+
+Each object in `<patcher>.json` decodes, with no translation layer, as **both**:
+
+* `FirmwarePatcher.PatchRecord` — `patchID`, `component`, `fileOffset`,
+ `virtualAddress`, `originalBytes`, `patchedBytes`, `beforeDisasm`,
+ `afterDisasm`, `patchDescription`; `Data` as base64, exactly as `Codable`
+ encodes it. `JSONDecoder().decode([PatchRecord].self, from:)` works as-is.
+* the `ReferencePatch` struct in `PatchComparisonTests.swift` — `file_offset`,
+ `patch_bytes` (hex), `patch_size`, `description`, `component`. Same values,
+ its spelling.
+
+Plus provenance both decoders ignore: `orig_bytes`, `orig_size`, `patched_size`,
+`va`, `file`, `orig_sha256`, `patch_sha256`, `inline_bytes`, `comparable`,
+`file_sha256_before`, `file_sha256_after`, `payload_before`, `payload_after`.
+The two `file_sha256_*` are whole-file hashes: they say which `raw_payloads/`
+entry a record belongs to, and they are what the re-capture guard matches a
+later run's input against.
+
+One record per sub-patch: each of the camera patcher's short-circuited symbols,
+each `hv_vmm_dsc` cstring site, each `iomfb_force_kern` trampoline, and each
+code-signature slot the re-attestation rewrites, all named individually.
+
+### Records that change a file's length
+
+A patch that resizes the file has no common offset space to diff, so it needs a
+recorder that knows the format. `inject-dylib` has one. `insert_dylib` strips
+launchd's code signature and reflows `__LINKEDIT` — the file comes out 27 KiB
+*shorter* — but the edit a Swift port has to reproduce is small, bounded, and
+sits at offsets that do not move, so that is what gets recorded:
+
+| record | what it pins |
+| --- | --- |
+| `inject_dylib.lc_load_dylib.mach_header` | the 32 header bytes carrying `ncmds` / `sizeofcmds` |
+| `inject_dylib.lc_load_dylib` | the inserted `LC_LOAD_WEAK_DYLIB`, at its offset |
+| `inject_dylib.lc_load_dylib.lc.0x<off>` | every other byte the command region moved (`__LINKEDIT` extent, `LC_SYMTAB` sizes) |
+
+Five records with real bytes at real offsets, where there used to be one with
+empty bytes at offset 0 that a port writing *nothing at all* still matched. What
+is deliberately not graded is the `__LINKEDIT` reflow past the command region:
+that is the signature strip, not the load-command write, and the payload pair is
+there to replay it.
+
+### Records that cannot fail
+
+`"comparable": false` (and a `patchID` ending `.opaque`) means the change was
+too big to inline, over 256 KiB — `patch_bytes` is empty and `patch_size` is 0,
+so the Swift comparison cannot fail against it. It is a pointer at the
+`payload_before` / `payload_after` pair, not a check. `records-status` marks the
+group `[!]` and exits non-zero, because a group like that looks captured while
+grading nothing; the fix is a structural recorder for that format, the way
+`record_macho_lc_edit` is the one for Mach-O.
+
+### Records the patcher did not declare
+
+A record whose `patchID` ends in `.undeclared.0x<offset>` is a byte the patcher
+changed without declaring it. That is not an error in the capture; it is the
+capture telling you the patcher's own account of itself has drifted from what it
+writes. Read it before porting that patcher.
+
+---
+
+## Known defects in this capture, as of 2026-09-23
+
+An independent verifier reproduced each of these with a harness. The doc errors
+above are already corrected; these are the ones still in the code. Read them
+before you trust a reference this produces.
+
+1. **`_dedupe_key()` drops a legitimate record** (`cfw_records.py:1146`). It
+ keys on the source *basename*, so one install patching both the SystemOS and
+ AppOS `launchd.plist` produces two records with the identical site key
+ `('inject_daemons.launch_daemons', 'launchd.plist', 0, 'launchd.plist')`;
+ `flush()` keeps the first and warns away the second. Expected 2, got 1. A
+ *correct* Swift port then fails `comparePatchRecords()` on count. Use the
+ full `file` path. This was introduced by the fix for the bytes-keyed version
+ of the same bug, from the other side.
+
+2. **`_assert_pristine_input` is caller-dependent, not structural**
+ (`cfw_records.py`). Net (i) keys on the source path, and holds today only
+ because `TEMP_DIR` is the fixed `$VM_DIR/.cfw_temp` (`cfw_install.sh:55`,
+ `cfw_install_exp.sh:171`). Randomise that temp dir and every legitimate
+ re-install becomes an "unfamiliar input" warning, while a chained
+ already-patched input becomes an accepted one. It is also **not on the DSC
+ path at all**: `cfw_dsc_chunks.py:258`, `cfw_dsc_codesign.py:304` and
+ `cfw_patch_dsc_maxslide.py:87` reach `record`/`record_span`, which never
+ call it.
+
+3. **The degenerate-record guard has a hole** (`cfw_records.py:490`).
+ `_assert_not_degenerate` runs only `if inline and original == patched`, so a
+ >256 KiB whole-file rewrite to identical content still stores a record whose
+ `originalBytes` equal its `patchedBytes`, as a `.opaque` record. Contained
+ (`comparable: false`, warning, `records-status` exits 1), but the rule stated
+ above — a degenerate record is an error, not a stored fact — is not what the
+ code enforces.
+
+4. **`take_cli_flag`'s `reserved` fix covers `cfw.py` only.**
+ `cfw_patch_build_version.py:95`, `cfw_patch_post_restore_dt.py:328` and
+ `campo_mach_lookup_exceptions.py:64` call it without `reserved`, and their
+ positional *is* a path, so `_looks_like_root` always swallows it:
+ `cfw_patch_build_version.py --emit-records <plist> 23B85` sets
+ `root=<plist>`, prints usage and exits 2. `reserved` cannot fix that — a path
+ cannot be excluded by name — so the containment is to make the separated
+ value illegal, i.e. accept `--emit-records=<root>` only.
+
+5. **Nothing in the repo exercises `cfw_records.py`.** `find tests -name '*.py'`
+ is empty, the Makefile has no pytest target, and `tests/test_dropbear_plist.py`
+ was deleted on this branch. Every guard described in this document — the
+ dedupe key, both `_assert_pristine_input` nets, `_assert_not_degenerate`,
+ `record_macho_lc_edit` — can be deleted and nothing goes red. Whatever
+ replaces this file in Swift must land with tests that do go red.
diff --git a/scripts/patchers/campo_mach_lookup_exceptions.py b/scripts/patchers/campo_mach_lookup_exceptions.py
index d44ef6a3..5e6f0016 100644
--- a/scripts/patchers/campo_mach_lookup_exceptions.py
+++ b/scripts/patchers/campo_mach_lookup_exceptions.py
@@ -8,6 +8,11 @@ Usage: campo_mach_lookup_exceptions.py <entitlements.plist>
import plistlib
import sys
+try:
+ from . import cfw_records as records
+except ImportError: # run directly: the script's own directory is on sys.path
+ import cfw_records as records
+
EXCEPTION_KEY = "com.apple.security.exception.mach-lookup.global-name"
SERVICES = [
@@ -32,6 +37,9 @@ SERVICES = [
def merge(path):
+ records.set_group("campo_mach_lookup")
+ before = records.snapshot_file(path)
+
with open(path, "rb") as f:
entitlements = plistlib.load(f)
@@ -42,14 +50,21 @@ def merge(path):
with open(path, "wb") as f:
plistlib.dump(entitlements, f)
+ records.record_after_write(
+ path, before, component="Campo.entitlements",
+ patch_id="campo_mach_lookup.global_name",
+ description=f"{len(added)} backboard/frontboard mach-lookup exception(s) merged",
+ )
+
print(" [+] Campo mach-lookup exception count: %d (+%d added)"
% (len(entitlements[EXCEPTION_KEY]), len(added)))
def main(argv):
+ argv, _ = records.take_cli_flag(argv)
if len(argv) != 2:
- print("Usage: campo_mach_lookup_exceptions.py <entitlements.plist>",
- file=sys.stderr)
+ print("Usage: campo_mach_lookup_exceptions.py [--emit-records <dir>] "
+ "<entitlements.plist>", file=sys.stderr)
return 2
merge(argv[1])
return 0
diff --git a/scripts/patchers/cfw.py b/scripts/patchers/cfw.py
index 2a4c147b..4803e9e1 100755
--- a/scripts/patchers/cfw.py
+++ b/scripts/patchers/cfw.py
@@ -113,12 +113,35 @@ Commands:
Inject LC_LOAD_DYLIB into Mach-O binary (thin or universal).
Equivalent to: optool install -c load -p <dylib_path> -t <binary>
+ records-status [<root>]
+ Report reference-snapshot coverage: which of the 19 patchers have a
+ captured `reference_patches/<group>.json` and which are still missing.
+
+Global flag (accepted by every subcommand above):
+
+ --emit-records [<root>]
+ Capture each applied patch as a PatchRecord-shaped JSON record under
+ <root>/reference_patches/, with the pre-patch inputs under
+ <root>/raw_payloads/. <root> defaults to ipsws/patch_refactor_input.
+ Equivalent to setting VPHONE_PATCH_RECORDS=<root>, which is the way to
+ capture a whole `cfw_install*.sh` run without editing the shell.
+ Capture is a pure observer — patch output is byte-identical either way —
+ except that it refuses, loudly, to record a run whose input is already
+ this root's own patched output. One root per (variant x iOS build).
+
+ Separated from its value, <root> has to look like a path (a separator,
+ a `~`, or a directory that exists) and may not be a subcommand name, so
+ that `--emit-records patch-seputil <bin>` reads as the bare flag plus a
+ subcommand. Spell an unusual root `--emit-records=<root>`.
+ See scripts/patchers/README_reference_capture.md.
+
Dependencies:
pip install capstone keystone-engine
ipsw CLI in $PATH (required for patch-camera-dsc, patch-iomfb-swapend and
patch-iomfb-force-kern)
"""
+import json
import os
import sys
@@ -142,6 +165,7 @@ if __name__ == "__main__":
from patchers.cfw_patch_watchdogd import patch_watchdogd
from patchers.cfw_patch_diskimagesiod import patch_diskimagesiod
from patchers.cfw_daemons import parse_cryptex_paths, inject_daemons, patch_dropbear_plist
+ from patchers import cfw_records as records
else:
from .cfw_patch_seputil import patch_seputil
from .cfw_patch_cache_loader import patch_launchd_cache_loader
@@ -158,15 +182,141 @@ else:
from .cfw_patch_watchdogd import patch_watchdogd
from .cfw_patch_diskimagesiod import patch_diskimagesiod
from .cfw_daemons import parse_cryptex_paths, inject_daemons, patch_dropbear_plist
+ from . import cfw_records as records
+
+
+# MARK: - Reference-snapshot coverage
+
+# The patchers plan P1.0 wants a reference snapshot for, by the group name each
+# one writes under. Kept here rather than in cfw_records so the list lives next
+# to the dispatch table it mirrors.
+EXPECTED_RECORD_GROUPS = (
+ # Standalone Mach-O (plan P1.2)
+ "seputil",
+ "launchd_cache_loader",
+ "mobileactivationd",
+ "launchd_jetsam",
+ "watchdogd",
+ "diskimagesiod",
+ # DSC (plan P1.3)
+ "dsc_maxslide",
+ "lockdown_mode",
+ "xpc_lwcr",
+ "lsd_embedded_reg",
+ "hv_vmm_dsc",
+ "iomfb_swapend",
+ "iomfb_force_kern",
+ "camera_dsc",
+ # Non-disassembly (plan P1.4)
+ "inject_daemons",
+ "dropbear_plist",
+ "inject_dylib",
+ "build_version",
+ "post_restore_dt",
+)
+
+# Runs only on the JB/EXP Campo path, so its absence is not a gap in the matrix.
+OPTIONAL_RECORD_GROUPS = ("campo_mach_lookup",)
+
+
+# MARK: - Dispatch table
+
+# Every verb `main()` answers to. Two jobs: the usage line printed on an unknown
+# command, and the reserved list handed to `records.take_cli_flag`, so a bare
+# `--emit-records` can never swallow a subcommand as its optional <root>.
+#
+# cfw-kit/lib/common.sh greps this file for each name in its
+# REQUIRED_CFW_SUBCOMMANDS and dies when one is missing, so nothing here is
+# removed while the Python remains the escape hatch.
+COMMANDS = (
+ "cryptex-paths",
+ "patch-seputil",
+ "patch-launchd-cache-loader",
+ "patch-mobileactivationd",
+ "patch-launchd-jetsam",
+ "patch-hv-vmm-dsc",
+ "patch-iomfb-swapend",
+ "patch-iomfb-force-kern",
+ "patch-dsc-maxslide",
+ "patch-lsd-embedded-reg",
+ "patch-xpc-lwcr",
+ "patch-lockdown-mode",
+ "patch-camera-dsc",
+ "patch-watchdogd",
+ "patch-diskimagesiod",
+ "inject-daemons",
+ "patch-dropbear-plist",
+ "inject-dylib",
+ "records-status",
+)
+
+
+def records_status(root):
+ """Print which patchers have been captured and which are missing."""
+ reference_dir, payload_dir = records.resolve_dirs(root)
+ print(f"reference_patches: {reference_dir}")
+ print(f"raw_payloads: {payload_dir}")
+ print("")
+
+ missing = []
+ opaque = []
+ for group in EXPECTED_RECORD_GROUPS + OPTIONAL_RECORD_GROUPS:
+ path = os.path.join(reference_dir, f"{group}.json")
+ optional = group in OPTIONAL_RECORD_GROUPS
+ try:
+ with open(path) as f:
+ recs = json.load(f)
+ except (OSError, ValueError):
+ print(f" [{'.' if optional else '-'}] {group:<22} "
+ f"{'missing (optional)' if optional else 'MISSING'}")
+ if not optional:
+ missing.append(group)
+ continue
+ # A record with no inline bytes carries an empty `patch_bytes`, so the
+ # Swift comparison cannot fail against it. Counting it as coverage is
+ # how a group looks captured while grading nothing.
+ blind = sum(1 for r in recs
+ if isinstance(r, dict) and not r.get("patch_bytes"))
+ note = f" — {blind} not comparable (no inline bytes)" if blind else ""
+ print(f" [{'!' if blind else '+'}] {group:<22} {len(recs):>5} record(s){note}")
+ if blind and not optional:
+ opaque.append(group)
+
+ covered = len(EXPECTED_RECORD_GROUPS) - len(missing)
+ print("")
+ print(f" {covered}/{len(EXPECTED_RECORD_GROUPS)} required patchers captured")
+ if missing:
+ print(f" still needed: {', '.join(missing)}")
+ return 1
+ if opaque:
+ print(f" records that cannot fail a wrong port: {', '.join(opaque)}")
+ print(" each needs a structural recorder before it grades anything")
+ return 1
+ warnings = os.path.join(reference_dir, "_capture_warnings.jsonl")
+ if os.path.exists(warnings):
+ print(f" read {warnings} — this capture warned about something")
+ print(" capture complete for this variant x iOS build")
+ return 0
def main():
+ # Strip the capture flag before dispatch: every branch below indexes argv
+ # positionally, so this is what makes the flag uniform across all of them.
+ # `reserved` keeps a bare `--emit-records` from eating the subcommand as its
+ # optional <root>, which is what turned `--emit-records patch-seputil <bin>`
+ # into "Unknown command: <bin>" plus a stray ./patch-seputil/ capture tree.
+ sys.argv[:], _ = records.take_cli_flag(sys.argv, reserved=COMMANDS)
+
if len(sys.argv) < 2:
print(__doc__)
sys.exit(1)
cmd = sys.argv[1]
+ if cmd == "records-status":
+ root = sys.argv[2] if len(sys.argv) > 2 else records.default_root()
+ sys.exit(records_status(root))
+
if cmd == "cryptex-paths":
if len(sys.argv) < 3:
print("Usage: cfw.py cryptex-paths <BuildManifest.plist>")
@@ -330,18 +480,37 @@ def main():
if not insert_dylib_bin:
print("[-] insert_dylib not found. Run: make setup_tools")
sys.exit(1)
+ # Recorded around the subprocess: the Swift port writes the LC itself,
+ # and the only honest reference for "what insert_dylib did" is the file
+ # either side of it.
+ #
+ # `structure="macho"` is what makes that reference mean something.
+ # insert_dylib strips the code signature and reflows __LINKEDIT, so the
+ # file length changes and the generic recorder collapsed the whole edit
+ # into one record with empty bytes at offset 0 — which a Swift port that
+ # wrote nothing at all still matched. The Mach-O recorder describes the
+ # mach_header counters and the inserted load command instead: small,
+ # bounded, at real offsets, and impossible to satisfy without writing
+ # them. This is pid 1's dylib; the reference has to be able to fail.
+ records.set_group("inject_dylib")
+ before = records.snapshot_file(sys.argv[2])
rc = subprocess.run(
[insert_dylib_bin, "--weak", "--inplace", "--all-yes", sys.argv[3], sys.argv[2]],
).returncode
if rc != 0:
sys.exit(rc)
+ records.record_after_write(
+ sys.argv[2], before, component=os.path.basename(sys.argv[2]),
+ patch_id="inject_dylib.lc_load_dylib",
+ description=f"LC_LOAD_WEAK_DYLIB for {sys.argv[3]} inserted",
+ structure="macho",
+ )
else:
print(f"Unknown command: {cmd}")
- print("Commands: cryptex-paths, patch-seputil, patch-launchd-cache-loader, patch-camera-dsc,")
- print(" patch-mobileactivationd, patch-launchd-jetsam,")
- print(" patch-hv-vmm-dsc, patch-iomfb-swapend, patch-iomfb-force-kern, patch-dsc-maxslide, patch-lsd-embedded-reg, patch-xpc-lwcr, patch-lockdown-mode, patch-watchdogd,")
- print(" patch-diskimagesiod, inject-daemons, patch-dropbear-plist, inject-dylib")
+ print("Commands:")
+ for name in COMMANDS:
+ print(f" {name}")
sys.exit(1)
diff --git a/scripts/patchers/cfw_daemons.py b/scripts/patchers/cfw_daemons.py
index 8dbc2ccf..e2d5081e 100644
--- a/scripts/patchers/cfw_daemons.py
+++ b/scripts/patchers/cfw_daemons.py
@@ -5,6 +5,11 @@ import plistlib
import subprocess
import sys
+try:
+ from . import cfw_records as records
+except ImportError: # direct self-test / standalone execution
+ import cfw_records as records
+
DROPBEAR_KEY_ARGS = [
"-r",
@@ -47,6 +52,11 @@ def parse_cryptex_paths(manifest_path):
def inject_daemons(plist_path, daemon_dir):
"""Inject bash/dropbear/trollvnc entries into launchd.plist."""
+ # Snapshot before the plutil conversion: the Swift port replaces that step
+ # too, so the reference input is the pristine binary plist.
+ records.set_group("inject_daemons")
+ before = records.snapshot_file(plist_path)
+
# Convert to XML first (macOS binary plist -> XML)
subprocess.run(["plutil", "-convert", "xml1", plist_path], capture_output=True)
@@ -72,6 +82,12 @@ def inject_daemons(plist_path, daemon_dir):
with open(plist_path, "wb") as f:
plistlib.dump(target, f, sort_keys=False)
+ records.record_after_write(
+ plist_path, before, component="launchd.plist",
+ patch_id="inject_daemons.launch_daemons",
+ description="LaunchDaemons entries injected for bash/dropbear/trollvnc/vphoned/rpcserver_ios",
+ )
+
def patch_dropbear_daemon(daemon):
"""Make dropbear use host keys on writable Data instead of read-only /etc."""
@@ -98,8 +114,15 @@ def patch_dropbear_daemon(daemon):
def patch_dropbear_plist(plist_path):
+ records.set_group("dropbear_plist")
+ before = records.snapshot_file(plist_path)
with open(plist_path, "rb") as f:
daemon = plistlib.load(f)
patch_dropbear_daemon(daemon)
with open(plist_path, "wb") as f:
plistlib.dump(daemon, f, sort_keys=False)
+ records.record_after_write(
+ plist_path, before, component="dropbear.plist",
+ patch_id="dropbear_plist.host_keys",
+ description="ProgramArguments rewritten to use /var/dropbear host keys",
+ )
diff --git a/scripts/patchers/cfw_dsc_chunks.py b/scripts/patchers/cfw_dsc_chunks.py
index d015bd33..88a76c7e 100644
--- a/scripts/patchers/cfw_dsc_chunks.py
+++ b/scripts/patchers/cfw_dsc_chunks.py
@@ -51,8 +51,10 @@ import re
try:
from .cfw_asm import _cs
+ from . import cfw_records as records
except ImportError: # direct self-test / standalone execution
from cfw_asm import _cs
+ import cfw_records as records
def _enumerate_chunks(chunks_dir):
@@ -240,9 +242,21 @@ class DSCChunks:
f"crosses a chunk boundary — refusing"
)
cp, foff = loc
+ # Every DSC patcher funnels through here, so this is the one place the
+ # reference capture has to read the original bytes — and it has to read
+ # them before the write, not reconstruct them after.
+ original = None
+ if records.enabled():
+ records.note_dsc_page(cp, foff)
+ with open(cp, "rb") as f:
+ f.seek(foff)
+ original = f.read(len(data))
with open(cp, "r+b") as f:
f.seek(foff)
f.write(data)
+ if original is not None:
+ records.record_span(os.path.basename(cp), foff, original, data,
+ virtual_address=vma, source_file=cp)
# ---- additional helpers used by the DSC-native canonical-site finder ----
diff --git a/scripts/patchers/cfw_dsc_codesign.py b/scripts/patchers/cfw_dsc_codesign.py
index 4390781b..5134625f 100644
--- a/scripts/patchers/cfw_dsc_codesign.py
+++ b/scripts/patchers/cfw_dsc_codesign.py
@@ -77,6 +77,11 @@ import hashlib
import os
import struct
+try:
+ from . import cfw_records as records
+except ImportError: # direct self-test / standalone execution
+ import cfw_records as records
+
# CS constants.
CSMAGIC_EMBEDDED_SIGNATURE = 0xFADE0CC0
@@ -291,4 +296,21 @@ def reattest_modified_pages(chunks, modified_vmas, *, dry_run=False, verbose=Tru
action = "would update" if dry_run else "updated"
print(f" [+] re-attest: {action} {total} slot hash(es) across "
f"{len(chunks_pages)} chunk(s)")
+ if not dry_run and records.enabled():
+ # P1.1's gate is that the Swift slot hashes come out byte-identical to
+ # these, so the re-attestation belongs in the snapshot as much as the
+ # instruction patches do.
+ for d in diagnostics:
+ records.record(
+ f"codesign.dsc.slot{d['page_index']}",
+ os.path.basename(d["chunk_path"]),
+ d["slot_off"],
+ bytes.fromhex(d["sha256_before"]),
+ bytes.fromhex(d["sha256_after"]),
+ description=(
+ f"DSC CodeDirectory slot {d['page_index']} "
+ f"(page at 0x{d['chunk_off']:X}) re-attested"
+ ),
+ source_file=d["chunk_path"],
+ )
return diagnostics
diff --git a/scripts/patchers/cfw_macho_codesign.py b/scripts/patchers/cfw_macho_codesign.py
index 96fee3e0..1ef6fdec 100644
--- a/scripts/patchers/cfw_macho_codesign.py
+++ b/scripts/patchers/cfw_macho_codesign.py
@@ -67,6 +67,11 @@ import hashlib
import os
import struct
+try:
+ from . import cfw_records as records
+except ImportError: # direct self-test / standalone execution
+ import cfw_records as records
+
# CS constants.
CSMAGIC_EMBEDDED_SIGNATURE = 0xFADE0CC0
@@ -341,4 +346,21 @@ def reattest_modified_offsets(
}
)
+ if not dry_run and records.enabled():
+ # Same reason as the DSC side: the Swift port has to reproduce these
+ # slot hashes exactly, so they are part of the reference snapshot.
+ for d in diagnostics:
+ records.record(
+ f"codesign.macho.cd{d['slot_type']:#x}.slot{d['page_index']}",
+ os.path.basename(filepath),
+ d["hash_offset_in_file"],
+ bytes.fromhex(d["before"]),
+ bytes.fromhex(d["after"]),
+ description=(
+ f"Mach-O CodeDirectory slot {d['page_index']} "
+ f"(page 0x{d['page_start']:X}..0x{d['page_end']:X}) re-attested"
+ ),
+ source_file=filepath,
+ )
+
return diagnostics
diff --git a/scripts/patchers/cfw_patch_build_version.py b/scripts/patchers/cfw_patch_build_version.py
index d831fdb1..98b6727c 100644
--- a/scripts/patchers/cfw_patch_build_version.py
+++ b/scripts/patchers/cfw_patch_build_version.py
@@ -29,6 +29,11 @@ Idempotent: a re-run on an already-patched plist exits without rewriting.
import plistlib
import sys
+try:
+ from . import cfw_records as records
+except ImportError: # run directly: the script's own directory is on sys.path
+ import cfw_records as records
+
KEY = "ProductBuildVersion"
@@ -75,15 +80,23 @@ def patch_plist(path: str, target: str, *, dry_run: bool = False) -> bool:
return False
new_data = plistlib.dumps(plist, fmt=fmt, sort_keys=False)
+ records.set_group("build_version")
+ records.record_file_write(
+ path, new_data, component="SystemVersion.plist",
+ patch_id="build_version.product_build_version",
+ description=f"{KEY} {current!r} -> {target!r}",
+ )
with open(path, "wb") as f:
f.write(new_data)
return True
def _main(argv):
+ argv, _ = records.take_cli_flag(argv)
if len(argv) < 3:
print(
- "Usage: cfw_patch_build_version.py <plist> <new_build_version> [--dry-run]",
+ "Usage: cfw_patch_build_version.py [--emit-records <dir>] "
+ "<plist> <new_build_version> [--dry-run]",
file=sys.stderr,
)
return 2
diff --git a/scripts/patchers/cfw_patch_cache_loader.py b/scripts/patchers/cfw_patch_cache_loader.py
index eaeca782..fa5aeb7a 100644
--- a/scripts/patchers/cfw_patch_cache_loader.py
+++ b/scripts/patchers/cfw_patch_cache_loader.py
@@ -2,6 +2,7 @@
from .cfw_asm import *
from .cfw_asm import _log_asm, _cs
+from . import cfw_records as records
def patch_launchd_cache_loader(filepath):
@@ -96,6 +97,13 @@ def patch_launchd_cache_loader(filepath):
print(f" After:")
_log_asm(data, ctx_start, 5, branch_foff)
+ records.set_group("launchd_cache_loader")
+ records.record_file_write(filepath, data, component="launchd_cache_loader", sites=[
+ records.site(branch_foff, 4, "launchd_cache_loader.unsecure_cache_gate",
+ f"NOP the cache-validation branch gated on "
+ f"'{anchor_str.decode()}'",
+ virtual_address=text_va + (branch_foff - text_foff)),
+ ])
open(filepath, "wb").write(data)
print(f" [+] NOPped at 0x{branch_foff:X}")
return True
diff --git a/scripts/patchers/cfw_patch_camera_dsc.py b/scripts/patchers/cfw_patch_camera_dsc.py
index 8e710641..ce728e9c 100644
--- a/scripts/patchers/cfw_patch_camera_dsc.py
+++ b/scripts/patchers/cfw_patch_camera_dsc.py
@@ -26,10 +26,12 @@ try:
from .cfw_asm import asm
from .cfw_dsc_chunks import DSCChunks
from .cfw_dsc_codesign import reattest_modified_pages
+ from . import cfw_records as records
except ImportError:
from cfw_asm import asm
from cfw_dsc_chunks import DSCChunks
from cfw_dsc_codesign import reattest_modified_pages
+ import cfw_records as records
NU_STYLE_TRANSFER_SYMBOLS = [
@@ -45,6 +47,11 @@ AVF_AUTH_STATUS_SYMBOL = (
)
+def _sym_slug(sym):
+ """A stable, filename-safe patch-id tail for an ObjC method symbol."""
+ return re.sub(r"[^A-Za-z0-9]+", "_", sym).strip("_")
+
+
def _resolve_symbols_in_image(dsc_path, image_path, wanted_symbols):
"""Resolve a set of ObjC method symbols in `image_path` against `dsc_path`
via `ipsw dyld symaddr`. Returns {symbol: vmaddr}. Raises if any are missing.
@@ -114,6 +121,10 @@ def patch_nu_styletransfer_short_circuit(chunks, vmas, *, dry_run=False, force=F
f"{sym}: prologue not pacibsp (got {orig[:4].hex()}); use --force to override"
)
if not dry_run:
+ # One record per symbol, so each of the five short-circuits is
+ # identified on its own rather than as "the camera patch".
+ records.next_site(f"camera_dsc.nu_styletransfer.{_sym_slug(sym)}",
+ f"{sym} -> mov w0, #0; ret")
chunks.write_at_vma(vma, new_bytes)
patched.append(vma)
@@ -150,6 +161,8 @@ def patch_avf_authorization_always_authorized(
f"{sym}: prologue not pacibsp (got {orig[:4].hex()}); use --force to override"
)
if not dry_run:
+ records.next_site(f"camera_dsc.avf_authorization.{_sym_slug(sym)}",
+ f"{sym} -> mov w0, #3 (AVAuthorizationStatusAuthorized); ret")
chunks.write_at_vma(vma, new_bytes)
patched.append(vma)
@@ -167,6 +180,7 @@ def patch_avf_authorization_always_authorized(
def apply_all_camera_patches(chunks_dir, dsc_path, *, dry_run=False, force=False):
"""Apply every camera DSC patch against `chunks_dir`, resolving symbols
against `dsc_path`."""
+ records.set_group("camera_dsc")
chunks = DSCChunks(chunks_dir)
print(f" [.] DSC: {chunks!r}")
@@ -189,6 +203,7 @@ def apply_avf_auth_only(chunks_dir, dsc_path, *, dry_run=False, force=False):
"""Apply only the AVFCapture authorization gate patch. Useful when running
on a chunk pulled from a device that already has the NU patches applied
(composition mode in `vphone-dsc-chunk-ramdisk-deploy`)."""
+ records.set_group("camera_dsc")
chunks = DSCChunks(chunks_dir)
print(f" [.] DSC: {chunks!r}")
print(f" [.] resolving AVFCapture authorization symbol against {dsc_path}...")
diff --git a/scripts/patchers/cfw_patch_diskimagesiod.py b/scripts/patchers/cfw_patch_diskimagesiod.py
index 19844094..d5cab665 100644
--- a/scripts/patchers/cfw_patch_diskimagesiod.py
+++ b/scripts/patchers/cfw_patch_diskimagesiod.py
@@ -31,6 +31,7 @@ own, so returning YES early changes nothing observable).
from .cfw_asm import *
from .cfw_asm import _log_asm
+from . import cfw_records as records
_SELECTOR = "isMountCompleteWithExpectedCount:diskTracker:"
@@ -150,6 +151,12 @@ def patch_diskimagesiod(filepath):
print(" After:")
_log_asm(data, imp_foff, 4, imp_foff)
+ records.set_group("diskimagesiod")
+ records.record_file_write(filepath, data, component="diskimagesiod", sites=[
+ records.site(imp_foff, 8, "diskimagesiod.is_mount_complete",
+ f"-[DIDiskArb {_SELECTOR}] -> mov x0, #1; ret",
+ virtual_address=imp_va if imp_va > 0 else None),
+ ])
open(filepath, "wb").write(data)
print(f" [+] Patched isMountComplete at 0x{imp_foff:X}: mov x0, #1; ret")
return True
diff --git a/scripts/patchers/cfw_patch_dsc_maxslide.py b/scripts/patchers/cfw_patch_dsc_maxslide.py
index a06f3750..8a20acc3 100644
--- a/scripts/patchers/cfw_patch_dsc_maxslide.py
+++ b/scripts/patchers/cfw_patch_dsc_maxslide.py
@@ -32,6 +32,11 @@ dyld_cache_header offsets (little-endian u64, stable across recent iOS):
import os
import struct
+try:
+ from . import cfw_records as records
+except ImportError: # direct self-test / standalone execution
+ import cfw_records as records
+
MAIN_CHUNK = "dyld_shared_cache_arm64e"
OFF_SHARED_REGION_START = 0xE0
@@ -75,6 +80,16 @@ def patch_dsc_maxslide(chunks_dir, *, kernel_region_size=KERNEL_SHARED_REGION_SI
action = "would set" if dry_run else "set"
print(f" [+] {reason}; {action} maxSlide 0x{maxslide:X} -> 0x{new_maxslide:X}")
if not dry_run:
+ # Header field, not a cs_validate'd code page — this is the one DSC
+ # patch that never goes through DSCChunks.write_at_vma, so it has to
+ # record itself.
+ records.set_group("dsc_maxslide")
+ records.record(
+ "dsc_maxslide.zero", MAIN_CHUNK, OFF_MAX_SLIDE,
+ struct.pack("<Q", maxslide), struct.pack("<Q", new_maxslide),
+ description=f"dyld_cache_header maxSlide 0x{maxslide:X} -> 0 ({reason})",
+ source_file=main,
+ )
f.seek(OFF_MAX_SLIDE)
f.write(struct.pack("<Q", new_maxslide))
f.flush()
diff --git a/scripts/patchers/cfw_patch_hv_vmm_dsc.py b/scripts/patchers/cfw_patch_hv_vmm_dsc.py
index 415f177c..3f9646da 100644
--- a/scripts/patchers/cfw_patch_hv_vmm_dsc.py
+++ b/scripts/patchers/cfw_patch_hv_vmm_dsc.py
@@ -51,6 +51,7 @@ from .cfw_patch_hv_vmm import (
)
from .cfw_dsc_chunks import DSCChunks
from .cfw_dsc_codesign import reattest_modified_pages
+from . import cfw_records as records
# ─────────────────────────────────────────────────────────────────────
@@ -120,6 +121,7 @@ def patch_hv_vmm_in_dsc(chunks_dir, *, dry_run=False):
Returns {install_name: count_of_cstring_sites_mangled}.
"""
+ records.set_group("hv_vmm_dsc")
chunks = DSCChunks(chunks_dir)
print(f" [.] {chunks!r}")
@@ -196,6 +198,11 @@ def patch_hv_vmm_in_dsc(chunks_dir, *, dry_run=False):
action = "would mangle" if dry_run else "mangled"
if not dry_run:
# Write the single byte at vma + MANGLE_OFFSET.
+ records.next_site(
+ f"hv_vmm_dsc.mangle@0x{vma:X}",
+ f"'kern.hv_vmm_present' byte {MANGLE_OFFSET} "
+ f"{ORIGINAL_BYTE.decode()} -> {MANGLED_BYTE.decode()} in {install_name}",
+ )
chunks.write_at_vma(vma + MANGLE_OFFSET, MANGLED_BYTE)
print(f" [+] {action} {label} string@0x{vma:X} "
f"byte {MANGLE_OFFSET} "
diff --git a/scripts/patchers/cfw_patch_hv_vmm_rootfs.py b/scripts/patchers/cfw_patch_hv_vmm_rootfs.py
deleted file mode 100644
index d23c6cb6..00000000
--- a/scripts/patchers/cfw_patch_hv_vmm_rootfs.py
+++ /dev/null
@@ -1,216 +0,0 @@
-"""Rootfs-side orchestrator for the hv_vmm_present user-mode patch
-(blacklist-flip design, standalone-binary side).
-
-Companion to:
- - The kernel-side `KernelJBPatchHvVmmRename` (renames the OID name
- cstring from `hv_vmm_present` to `Xv_vmm_present` AND mangles
- every kernel-internal `\\0kern.hv_vmm_present\\0` cstring inside
- kexts so they query the new name and keep seeing 1).
- - The DSC-side `cfw_patch_hv_vmm_dsc.py` (same blacklist-flip,
- mangles every DSC dylib's cstring EXCEPT those in
- `DONT_PATCH_INSTALL_NAMES`).
-
-This module covers the third domain: standalone Mach-O binaries on
-the device's rootfs that hard-code `"kern.hv_vmm_present\\0"` in their
-own `__TEXT,__cstring`. Under the new design every such binary needs
-to either:
-
- - Be MANGLED (byte 5 of the cstring: 'h' -> 'X') so it queries
- `kern.Xv_vmm_present`, gets the truthful `1` back from the
- renamed OID, and behaves as it would on a real device. Default
- behaviour: most platform daemons (watchdogd, mobile_obliterator,
- DumpPanic, …) need this — without it they hit the renamed OID's
- ENOENT, interpret as "not in a VM", and take real-hardware code
- paths that don't exist on the VM (concrete repro: watchdogd
- SIGTRAP → kernel panic with `watchdogd[N] exited`).
-
- - Be LEFT ALONE (`DONT_PATCH_ROOTFS_PATHS` blacklist) so its
- cstring still says `kern.hv_vmm_present`, that query returns
- ENOENT after the kernel rename, the binary's defensive
- post-call check leaves the cached `is_vmm` byte at BSS-zero (0),
- and the binary thinks "not in a VM". Use this for the sign-in
- / activation / Apple-ID stack — the same role intent we apply
- to the DSC frameworks they link.
-
-Data sources for ALL_KNOWN_ROOTFS_PATHS
----------------------------------------
-The list below is taken verbatim from a `grep -rla 'kern\\.hv_vmm_present'
-ipsws/iPhone17,3_26.1_23B85_Restore_extracted/ --exclude-dir='Cryptexes'`
-on the extracted rootfs of iPhone17,3 26.1 23B85, minus
-`/System/Library/Caches/com.apple.kernelcaches/kernelcache.release.iphone17`
-which is the kernel itself and is patched by the firmware patcher
-not this module. If future iOS builds add new daemons that reference
-the cstring, re-run that grep and add the new paths here.
-"""
-
-import sys
-
-
-# ─────────────────────────────────────────────────────────────────────
-# Complete list of rootfs Mach-Os that contain the cstring
-# `kern.hv_vmm_present\0` somewhere in their __TEXT,__cstring.
-#
-# Established once by scanning the extracted rootfs of iPhone17,3 /
-# iOS 26.1 / 23B85. Re-derive when porting to a new iOS build by:
-# grep -rla 'kern\.hv_vmm_present' \
-# ipsws/<new>_Restore_extracted/ \
-# --exclude-dir='Cryptexes' 2>/dev/null
-# ─────────────────────────────────────────────────────────────────────
-ALL_KNOWN_ROOTFS_PATHS: tuple[str, ...] = (
- # /usr/libexec daemons
- "/usr/libexec/adid",
- "/usr/libexec/DumpPanic",
- "/usr/libexec/fairplaydeviceidentityd",
- "/usr/libexec/mmaintenanced",
- "/usr/libexec/modelmanagerd",
- "/usr/libexec/mobile_obliterator",
- "/usr/libexec/mobileactivationd",
- "/usr/libexec/networkserviceproxy",
- "/usr/libexec/promotedcontentd",
- "/usr/libexec/storagekitd",
- "/usr/libexec/terminusd",
- "/usr/libexec/transparencyd",
- "/usr/libexec/trustd",
- "/usr/libexec/watchdogd",
-
- # /usr/sbin
- "/usr/sbin/absd",
- "/usr/sbin/bluetoothd",
- "/usr/sbin/fairplayd.H2",
-
- # /usr/lib
- "/usr/lib/libMobileGestalt.dylib",
-
- # /System/Library/CoreServices
- "/System/Library/CoreServices/ClarityBoard.app/ClarityBoard",
-
- # /System/Library/DataClassMigrators
- "/System/Library/DataClassMigrators/MobileActivationMigrator.migrator/MobileActivationMigrator",
-
- # /System/Library/ExtensionKit
- "/System/Library/ExtensionKit/Extensions/HostInferenceProviderService.appex/HostInferenceProviderService",
-
- # /System/Library/Frameworks
- "/System/Library/Frameworks/CoreML.framework/CoreML",
- "/System/Library/Frameworks/CoreVideo.framework/CoreVideo",
- "/System/Library/Frameworks/ManagedAppDistribution.framework/Support/managedappdistributiond",
- "/System/Library/Frameworks/MediaToolbox.framework/MediaToolbox",
- "/System/Library/Frameworks/SoundAnalysis.framework/SoundAnalysis",
- "/System/Library/Frameworks/StoreKit.framework/Support/storekitd",
-
- # /System/Library/PrivateFrameworks
- "/System/Library/PrivateFrameworks/AAAFoundation.framework/AAAFoundation",
- "/System/Library/PrivateFrameworks/AirPlaySupport.framework/AirPlaySupport",
- "/System/Library/PrivateFrameworks/AppStoreDaemon.framework/Support/appstored",
- "/System/Library/PrivateFrameworks/AppStoreUtilities.framework/AppStoreUtilities",
- "/System/Library/PrivateFrameworks/AppleNeuralEngine.framework/AppleNeuralEngine",
- "/System/Library/PrivateFrameworks/ApplePushService.framework/ApplePushService",
- "/System/Library/PrivateFrameworks/ApplePushService.framework/apsd",
- "/System/Library/PrivateFrameworks/AuthKit.framework/AuthKit",
- "/System/Library/PrivateFrameworks/CMCapture.framework/CMCapture",
- "/System/Library/PrivateFrameworks/CoreALD.framework/CoreALD",
- "/System/Library/PrivateFrameworks/CoreCDP.framework/CoreCDP",
- "/System/Library/PrivateFrameworks/CorePrescription.framework/CorePrescription",
- "/System/Library/PrivateFrameworks/CorePrescription.framework/XPCServices/CorePrescriptionService.xpc/CorePrescriptionService",
- "/System/Library/PrivateFrameworks/CoreRE.framework/CoreRE",
- "/System/Library/PrivateFrameworks/DVTInstrumentsUtilities.framework/DVTInstrumentsUtilities",
- "/System/Library/PrivateFrameworks/DataDetectorsUI.framework/PlugIns/com.apple.DataDetectorsUI.ActionsExtension.appex/com.apple.DataDetectorsUI.ActionsExtension",
- "/System/Library/PrivateFrameworks/DeviceCheckInternal.framework/DeviceCheckInternal",
- "/System/Library/PrivateFrameworks/DeviceIdentity.framework/DeviceIdentity",
- "/System/Library/PrivateFrameworks/EmailFoundation.framework/EmailFoundation",
- "/System/Library/PrivateFrameworks/Espresso.framework/Espresso",
- "/System/Library/PrivateFrameworks/FindMyBase.framework/FindMyBase",
- "/System/Library/PrivateFrameworks/IDS.framework/identityservicesd.app/identityservicesd",
- "/System/Library/PrivateFrameworks/IDSFoundation.framework/IDSFoundation",
- "/System/Library/PrivateFrameworks/IOSurfaceAccelerator.framework/IOSurfaceAccelerator",
- "/System/Library/PrivateFrameworks/MagnifierSupport.framework/MagnifierSupport",
- "/System/Library/PrivateFrameworks/MobileActivation.framework/MobileActivation",
- "/System/Library/PrivateFrameworks/NeuralNetworks.framework/NeuralNetworks",
- "/System/Library/PrivateFrameworks/PhotoFoundation.framework/PhotoFoundation",
- "/System/Library/PrivateFrameworks/Recon3D.framework/Recon3D",
- "/System/Library/PrivateFrameworks/RenderBox.framework/RenderBox",
- "/System/Library/PrivateFrameworks/SonicKit.framework/SonicKit",
- "/System/Library/PrivateFrameworks/TrialServer.framework/TrialServer",
- "/System/Library/PrivateFrameworks/VFX.framework/VFX",
- "/System/Library/PrivateFrameworks/VideosUI.framework/VideosUI",
- "/System/Library/PrivateFrameworks/VisionKitCore.framework/VisionKitCore",
- "/System/Library/PrivateFrameworks/WatchdogServiceManagement.framework/WatchdogServiceManagement",
- "/System/Library/PrivateFrameworks/caulk.framework/caulk",
-
- # /Applications
- "/Applications/CheckerBoard.app/CheckerBoard",
- "/Applications/Family.app/Family",
- "/Applications/PeopleMessageService.app/PeopleMessageService",
- "/Applications/PeopleViewService.app/PeopleViewService",
- "/Applications/StoreKitUISceneService.app/StoreKitUISceneService",
-)
-
-
-# ─────────────────────────────────────────────────────────────────────
-# Rootfs binaries to LEAVE UNPATCHED.
-#
-# A path in this set keeps its `kern.hv_vmm_present\0` cstring as-is.
-# After the kernel rename that sysctl name returns ENOENT, the caller's
-# defensive post-call check leaves the cached `is_vmm` byte at BSS-zero
-# (0), and the binary thinks "not in a VM". Use this for sign-in /
-# Apple-ID / activation / Store consumers — mirrors the DSC blacklist.
-#
-# Starting set is intentionally conservative: only daemons we have a
-# clear "is sign-in adjacent" reason to leave alone. Tighten / loosen
-# by editing this list and re-running `make cfw_install_jb`.
-# ─────────────────────────────────────────────────────────────────────
-DONT_PATCH_ROOTFS_PATHS: frozenset[str] = frozenset((
- # Apple ID / activation / device-identity daemons
- "/usr/libexec/adid",
- "/usr/libexec/mobileactivationd",
- "/usr/libexec/fairplaydeviceidentityd",
- "/System/Library/DataClassMigrators/MobileActivationMigrator.migrator/MobileActivationMigrator",
- # APNS / iMessage daemons
- "/System/Library/PrivateFrameworks/ApplePushService.framework/apsd",
- "/System/Library/PrivateFrameworks/IDS.framework/identityservicesd.app/identityservicesd",
- # Store / IAP daemons + UI
- "/System/Library/Frameworks/StoreKit.framework/Support/storekitd",
- "/System/Library/PrivateFrameworks/AppStoreDaemon.framework/Support/appstored",
- "/Applications/StoreKitUISceneService.app/StoreKitUISceneService",
- "/Applications/CheckerBoard.app/CheckerBoard",
- # Health Rx
- "/System/Library/PrivateFrameworks/CorePrescription.framework/XPCServices/CorePrescriptionService.xpc/CorePrescriptionService",
- # Standalone copies of DSC-blacklisted frameworks. The rootfs files
- # may be stubs that redirect into the DSC at load time, in which
- # case mangling them has no effect — but blacklisting is defensive
- # and matches role intent.
- "/System/Library/PrivateFrameworks/AAAFoundation.framework/AAAFoundation",
- "/System/Library/PrivateFrameworks/AuthKit.framework/AuthKit",
- "/System/Library/PrivateFrameworks/IDSFoundation.framework/IDSFoundation",
- "/System/Library/PrivateFrameworks/DeviceIdentity.framework/DeviceIdentity",
- "/System/Library/PrivateFrameworks/DeviceCheckInternal.framework/DeviceCheckInternal",
- "/System/Library/PrivateFrameworks/MobileActivation.framework/MobileActivation",
- "/System/Library/PrivateFrameworks/ApplePushService.framework/ApplePushService",
- "/System/Library/PrivateFrameworks/AppStoreUtilities.framework/AppStoreUtilities",
- "/System/Library/PrivateFrameworks/CorePrescription.framework/CorePrescription",
- "/System/Library/PrivateFrameworks/CoreCDP.framework/CoreCDP",
- "/System/Library/PrivateFrameworks/EmailFoundation.framework/EmailFoundation",
- "/System/Library/PrivateFrameworks/FindMyBase.framework/FindMyBase",
- "/System/Library/PrivateFrameworks/TrialServer.framework/TrialServer",
- "/System/Library/PrivateFrameworks/DVTInstrumentsUtilities.framework/DVTInstrumentsUtilities",
- "/System/Library/PrivateFrameworks/WatchdogServiceManagement.framework/WatchdogServiceManagement",
-))
-
-
-def get_patch_paths() -> list[str]:
- """Return the list of rootfs binary paths that should be byte-5
- mangled at install time. This is `ALL_KNOWN_ROOTFS_PATHS` minus
- `DONT_PATCH_ROOTFS_PATHS`, in stable sorted order.
- """
- return sorted(p for p in ALL_KNOWN_ROOTFS_PATHS if p not in DONT_PATCH_ROOTFS_PATHS)
-
-
-def main(argv: list[str]) -> int:
- """Print the patch paths, one per line, for shell consumption."""
- for p in get_patch_paths():
- print(p)
- return 0
-
-
-if __name__ == "__main__":
- raise SystemExit(main(sys.argv))
diff --git a/scripts/patchers/cfw_patch_iomfb_force_kern.py b/scripts/patchers/cfw_patch_iomfb_force_kern.py
index bea81568..85e7fe42 100644
--- a/scripts/patchers/cfw_patch_iomfb_force_kern.py
+++ b/scripts/patchers/cfw_patch_iomfb_force_kern.py
@@ -48,10 +48,12 @@ try:
from .cfw_asm import asm_at, _cs
from .cfw_dsc_chunks import DSCChunks
from .cfw_dsc_codesign import reattest_modified_pages
+ from . import cfw_records as records
except ImportError: # direct execution
from cfw_asm import asm_at, _cs
from cfw_dsc_chunks import DSCChunks
from cfw_dsc_codesign import reattest_modified_pages
+ import cfw_records as records
IOMFB = "/System/Library/PrivateFrameworks/IOMobileFramebuffer.framework/IOMobileFramebuffer"
@@ -101,6 +103,7 @@ def _is_dispatch_trampoline(chunks, va):
def patch_iomfb_force_kern(chunks_dir, *, dsc_path=None, dry_run=False):
+ records.set_group("iomfb_force_kern")
chunks = DSCChunks(chunks_dir)
print(f" [.] {chunks!r}")
@@ -142,6 +145,10 @@ def patch_iomfb_force_kern(chunks_dir, *, dsc_path=None, dry_run=False):
print(f" [+] {pub_name} @ 0x{pub_va:X}: "
f"'{first.mnemonic} {first.op_str}' -> 'b {kern_name}' (0x{kern_va:X})")
if not dry_run:
+ records.next_site(
+ f"iomfb_force_kern.{suffix}",
+ f"{pub_name} trampoline -> b {kern_name} (0x{kern_va:X})",
+ )
chunks.write_at_vma(pub_va, b_bytes)
modified.append(pub_va)
forced.add(suffix)
diff --git a/scripts/patchers/cfw_patch_iomfb_swapend.py b/scripts/patchers/cfw_patch_iomfb_swapend.py
index bf9025c9..b17ff3e9 100644
--- a/scripts/patchers/cfw_patch_iomfb_swapend.py
+++ b/scripts/patchers/cfw_patch_iomfb_swapend.py
@@ -47,10 +47,12 @@ try:
from .cfw_asm import asm, _cs, _mov_reg_imm
from .cfw_dsc_chunks import DSCChunks, _disasm_function
from .cfw_dsc_codesign import reattest_modified_pages
+ from . import cfw_records as records
except ImportError: # direct self-test execution
from cfw_asm import asm, _cs, _mov_reg_imm
from cfw_dsc_chunks import DSCChunks, _disasm_function
from cfw_dsc_codesign import reattest_modified_pages
+ import cfw_records as records
IOMFB = "/System/Library/PrivateFrameworks/IOMobileFramebuffer.framework/IOMobileFramebuffer"
@@ -108,6 +110,7 @@ def _find_swap_size_insn(insns):
def patch_iomfb_swapend(chunks_dir, *, dsc_path=None, target_size=TARGET_SIZE,
dry_run=False):
+ records.set_group("iomfb_swapend")
chunks = DSCChunks(chunks_dir)
print(f" [.] {chunks!r}")
@@ -139,6 +142,11 @@ def patch_iomfb_swapend(chunks_dir, *, dsc_path=None, target_size=TARGET_SIZE,
print(f" [+] {action} {IOMFB} {SWAPEND_SYMBOL} size "
f"0x{cur_size:X} -> 0x{target_size:X} at 0x{insn_vma:X}")
if not dry_run:
+ records.next_site(
+ "iomfb_swapend.payload_size",
+ f"{IOMFB} {SWAPEND_SYMBOL} external-method payload size "
+ f"0x{cur_size:X} -> 0x{target_size:X}",
+ )
chunks.write_at_vma(insn_vma, new_bytes)
if not dry_run:
diff --git a/scripts/patchers/cfw_patch_jetsam.py b/scripts/patchers/cfw_patch_jetsam.py
index f670a515..1cac37f3 100644
--- a/scripts/patchers/cfw_patch_jetsam.py
+++ b/scripts/patchers/cfw_patch_jetsam.py
@@ -3,6 +3,7 @@
from .cfw_asm import *
from .cfw_asm import _log_asm
from .cfw_patch_cache_loader import _find_adrp_add_ref, _find_cstring_start
+from . import cfw_records as records
def _extract_branch_target_off(insn):
for op in reversed(insn.operands):
@@ -146,6 +147,13 @@ def patch_launchd_jetsam(filepath):
print(f" After:")
_log_asm(data, ctx_start, 5, patch_off)
+ records.set_group("launchd_jetsam")
+ records.record_file_write(filepath, data, component="launchd_jetsam", sites=[
+ records.site(patch_off, 4, "launchd_jetsam.panic_guard_bypass",
+ f"conditional branch -> unconditional b 0x{patch_target:X} "
+ f"(jetsam panic guard bypass)",
+ virtual_address=text_va + (patch_off - text_foff)),
+ ])
open(filepath, "wb").write(data)
print(f" [+] Patched at 0x{patch_off:X}: jetsam panic guard bypass")
return True
diff --git a/scripts/patchers/cfw_patch_lockdown_mode.py b/scripts/patchers/cfw_patch_lockdown_mode.py
index 44f263de..71e748d6 100644
--- a/scripts/patchers/cfw_patch_lockdown_mode.py
+++ b/scripts/patchers/cfw_patch_lockdown_mode.py
@@ -29,10 +29,12 @@ try:
from .cfw_asm import asm
from .cfw_dsc_chunks import DSCChunks, resolve_local_symbol, _disasm_function
from .cfw_dsc_codesign import reattest_modified_pages
+ from . import cfw_records as records
except ImportError:
from cfw_asm import asm
from cfw_dsc_chunks import DSCChunks, resolve_local_symbol, _disasm_function
from cfw_dsc_codesign import reattest_modified_pages
+ import cfw_records as records
SYMBOL_CANDIDATES = (
"___os_lockdown_mode_enabled_block_invoke",
@@ -69,6 +71,7 @@ def _find_error_gate(insns):
def patch_lockdown_mode(chunks_dir, *, dry_run=False):
+ records.set_group("lockdown_mode")
chunks = DSCChunks(chunks_dir)
print(f" [.] {chunks!r}")
@@ -100,6 +103,11 @@ def patch_lockdown_mode(chunks_dir, *, dry_run=False):
action = "would write" if dry_run else "wrote"
print(f" [+] {action} nop at 0x{gate.address:X} ({cur.hex()} -> {nop.hex()})")
if not dry_run:
+ records.next_site(
+ "lockdown_mode.sysctl_error_gate",
+ f"NOP `{gate.mnemonic} {gate.op_str}` so a missing "
+ f"security.mac.lockdown_mode_state_public sysctl reads 0 instead of aborting",
+ )
chunks.write_at_vma(gate.address, nop)
reattest_modified_pages(chunks, [gate.address], dry_run=False)
if chunks.bytes_at_vma(gate.address, 4) != nop:
diff --git a/scripts/patchers/cfw_patch_lsd_embedded_reg.py b/scripts/patchers/cfw_patch_lsd_embedded_reg.py
index cd3bd6a9..9bb231ae 100644
--- a/scripts/patchers/cfw_patch_lsd_embedded_reg.py
+++ b/scripts/patchers/cfw_patch_lsd_embedded_reg.py
@@ -46,10 +46,12 @@ try:
from .cfw_asm import asm, _mov_reg_imm
from .cfw_dsc_chunks import DSCChunks, resolve_local_symbol, _disasm_function
from .cfw_dsc_codesign import reattest_modified_pages
+ from . import cfw_records as records
except ImportError: # direct self-test / standalone execution
from cfw_asm import asm, _mov_reg_imm
from cfw_dsc_chunks import DSCChunks, resolve_local_symbol, _disasm_function
from cfw_dsc_codesign import reattest_modified_pages
+ import cfw_records as records
LAUNCHSERVICES = "/System/Library/Frameworks/CoreServices.framework/CoreServices"
@@ -81,6 +83,7 @@ def _find_gate(insns):
def patch_lsd_embedded_reg(chunks_dir, *, dry_run=False):
+ records.set_group("lsd_embedded_reg")
chunks = DSCChunks(chunks_dir)
print(f" [.] {chunks!r}")
@@ -116,6 +119,11 @@ def patch_lsd_embedded_reg(chunks_dir, *, dry_run=False):
print(f" [+] {action} gate {gate.mnemonic} -> nop at 0x{insn_vma:X} "
f"(bytes {cur.hex()} -> {nop.hex()})")
if not dry_run:
+ records.next_site(
+ "lsd_embedded_reg.entitlement_gate",
+ f"NOP `{gate.mnemonic} {gate.op_str}` in {METHOD} so the "
+ f"fall-through sets {result_reg}=1 (entitled)",
+ )
chunks.write_at_vma(insn_vma, nop)
if not dry_run:
diff --git a/scripts/patchers/cfw_patch_mobileactivationd.py b/scripts/patchers/cfw_patch_mobileactivationd.py
index ac876cf7..f95fbee2 100644
--- a/scripts/patchers/cfw_patch_mobileactivationd.py
+++ b/scripts/patchers/cfw_patch_mobileactivationd.py
@@ -2,6 +2,7 @@
from .cfw_asm import *
from .cfw_asm import _log_asm
+from . import cfw_records as records
def _find_via_objc_metadata(data):
"""Find method IMP through ObjC runtime metadata."""
@@ -146,6 +147,12 @@ def patch_mobileactivationd(filepath):
print(f" After:")
_log_asm(data, imp_foff, 4, imp_foff)
+ records.set_group("mobileactivationd")
+ records.record_file_write(filepath, data, component="mobileactivationd", sites=[
+ records.site(imp_foff, 8, "mobileactivationd.should_hactivate",
+ "-[DeviceType should_hactivate] -> mov x0, #1; ret",
+ virtual_address=imp_va if imp_va > 0 else None),
+ ])
open(filepath, "wb").write(data)
print(f" [+] Patched at 0x{imp_foff:X}: mov x0, #1; ret")
return True
diff --git a/scripts/patchers/cfw_patch_post_restore_dt.py b/scripts/patchers/cfw_patch_post_restore_dt.py
index 1778bff3..51bb3e2d 100644
--- a/scripts/patchers/cfw_patch_post_restore_dt.py
+++ b/scripts/patchers/cfw_patch_post_restore_dt.py
@@ -49,6 +49,11 @@ import sys
import pyimg4
+try:
+ from . import cfw_records as records
+except ImportError: # run directly: the script's own directory is on sys.path
+ import cfw_records as records
+
# ──────────────────────────────────────────────────────────────────────
# Device Tree binary format parser/serializer (mirrors
@@ -300,6 +305,19 @@ def patch_devicetree_file(path: str, *, dry_run: bool = False) -> int:
print(f" [.] dry-run — not writing back")
return 0
+ records.set_group("post_restore_dt")
+ # Two levels, because the Swift port has to get both right: the property
+ # edits inside the decompressed DT blob, and the re-wrapped container.
+ records.record_blob_diff(
+ "devicetree.dtre", dt_blob, new_dt,
+ patch_id_prefix="post_restore_dt.property",
+ description="restore-fatal DT identity property rewritten (blob-relative offset)",
+ source_file=path,
+ )
+ records.record_file_write(path, out_bytes, component="devicetree.img4",
+ patch_id="post_restore_dt.container",
+ description="IM4P re-wrapped around the patched DT blob")
+
with open(path, "wb") as f:
f.write(out_bytes)
print(f" [+] wrote {path}")
@@ -307,9 +325,11 @@ def patch_devicetree_file(path: str, *, dry_run: bool = False) -> int:
def _main(argv):
+ argv, _ = records.take_cli_flag(argv)
if len(argv) < 2:
print(
- "Usage: cfw_patch_post_restore_dt.py <devicetree.img4|im4p> [--dry-run]",
+ "Usage: cfw_patch_post_restore_dt.py [--emit-records <dir>] "
+ "<devicetree.img4|im4p> [--dry-run]",
file=sys.stderr,
)
return 2
diff --git a/scripts/patchers/cfw_patch_seputil.py b/scripts/patchers/cfw_patch_seputil.py
index 246993f8..7a319c79 100644
--- a/scripts/patchers/cfw_patch_seputil.py
+++ b/scripts/patchers/cfw_patch_seputil.py
@@ -1,5 +1,10 @@
"""seputil patch module."""
+try:
+ from . import cfw_records as records
+except ImportError: # direct self-test / standalone execution
+ import cfw_records as records
+
def patch_seputil(filepath):
"""Dynamically find and patch the gigalocker path format string in seputil.
@@ -35,6 +40,11 @@ def patch_seputil(filepath):
print(f" After: {bytes(data[offset : offset + 7]).hex(' ')}")
+ records.set_group("seputil")
+ records.record_file_write(filepath, data, component="seputil", sites=[
+ records.site(pct_s_off, 2, "seputil.gigalocker_uuid",
+ "gigalocker path format '/%s.gl' -> '/AA.gl'"),
+ ])
open(filepath, "wb").write(data)
print(f" [+] Patched at 0x{pct_s_off:X}: %s -> AA")
print(f" /{anchor[1:-1].decode()} -> /AA.gl")
diff --git a/scripts/patchers/cfw_patch_watchdogd.py b/scripts/patchers/cfw_patch_watchdogd.py
index 9e71cf81..b79ceb76 100644
--- a/scripts/patchers/cfw_patch_watchdogd.py
+++ b/scripts/patchers/cfw_patch_watchdogd.py
@@ -104,6 +104,7 @@ from .cfw_asm import (
parse_macho_sections,
)
from .cfw_macho_codesign import reattest_modified_offsets
+from . import cfw_records as records
from capstone.arm64_const import ARM64_OP_IMM
@@ -382,6 +383,7 @@ def patch_watchdogd(filepath, *, dry_run=False):
print(f" [+] found {len(matches)} '{PATTERN_NAME}' site(s)")
touched_offsets = []
+ record_sites = []
n_applied = 0
for m in matches:
cbnz_foff = m["cbnz_foff"]
@@ -424,6 +426,15 @@ def patch_watchdogd(filepath, *, dry_run=False):
touched_offsets.append(cbnz_foff)
touched_offsets.append(cset_foff)
+ record_sites.append(records.site(
+ cbnz_foff, 4, f"watchdogd.hv_vmm_cache.cbnz@0x{m['cbnz_va']:X}",
+ "NOP the cbnz w0 that skips the cached hv_vmm_present store",
+ virtual_address=m["cbnz_va"]))
+ record_sites.append(records.site(
+ cset_foff, 4, f"watchdogd.hv_vmm_cache.cset@0x{m['cset_va']:X}",
+ f"cset {m['cset_reg']} -> mov {m['cset_reg']}, #1 "
+ f"(cached 'am I a VM?' byte forced to 1)",
+ virtual_address=m["cset_va"]))
n_applied += 1
if n_applied == 0:
@@ -436,6 +447,9 @@ def patch_watchdogd(filepath, *, dry_run=False):
if dry_run:
print(f" [.] dry-run — not writing patched bytes")
else:
+ records.set_group("watchdogd")
+ records.record_file_write(filepath, data, component="watchdogd",
+ sites=record_sites)
with open(filepath, "wb") as f:
f.write(data)
print(f" [+] {filepath}: wrote {n_applied} site(s)")
diff --git a/scripts/patchers/cfw_patch_xpc_lwcr.py b/scripts/patchers/cfw_patch_xpc_lwcr.py
index a4d4c3ac..d417d959 100644
--- a/scripts/patchers/cfw_patch_xpc_lwcr.py
+++ b/scripts/patchers/cfw_patch_xpc_lwcr.py
@@ -49,10 +49,12 @@ try:
from .cfw_asm import asm
from .cfw_dsc_chunks import DSCChunks, resolve_local_symbol, _disasm_function
from .cfw_dsc_codesign import reattest_modified_pages
+ from . import cfw_records as records
except ImportError: # direct self-test / standalone execution
from cfw_asm import asm
from cfw_dsc_chunks import DSCChunks, resolve_local_symbol, _disasm_function
from cfw_dsc_codesign import reattest_modified_pages
+ import cfw_records as records
SYMBOL = "_xpc_token_satisfies_lwcr"
@@ -144,6 +146,7 @@ def _find_patched_shape(insns):
def patch_xpc_lwcr(chunks_dir, *, dry_run=False):
+ records.set_group("xpc_lwcr")
chunks = DSCChunks(chunks_dir)
print(f" [.] {chunks!r}")
@@ -198,6 +201,10 @@ def patch_xpc_lwcr(chunks_dir, *, dry_run=False):
action = "would write" if dry_run else "wrote"
print(f" [+] {action} {label} at 0x{vma:X} ({cur.hex()} -> {new_bytes.hex()})")
if not dry_run:
+ records.next_site(
+ f"xpc_lwcr.{label.split()[0]}@0x{vma:X}",
+ f"{SYMBOL}: `{label}` — derive matched from error_code and drop the abort",
+ )
chunks.write_at_vma(vma, new_bytes)
modified.append(vma)
diff --git a/scripts/patchers/cfw_records.py b/scripts/patchers/cfw_records.py
new file mode 100644
index 00000000..2a9bbcf6
--- /dev/null
+++ b/scripts/patchers/cfw_records.py
@@ -0,0 +1,1230 @@
+"""Reference-snapshot capture for the Swift patcher migration (plan P1.0).
+
+Why this exists
+---------------
+The CFW patches rewrite executable pages that TXM hashes. A wrong byte is not a
+failing test, it is a boot panic — so before any of `scripts/patchers/` is
+reimplemented in Swift, every patch site has to be captured off a *real* install
+as `file offset + original bytes + patched bytes`. The Swift port is then diffed
+against that instead of eyeballed. `README_reference_capture.md` has the capture
+procedure.
+
+Contract: recording is a pure observer, or it stops
+---------------------------------------------------
+Every entry point below returns immediately when capture is off, and on the
+happy path nothing here mutates a buffer, a file, or a patcher's control flow.
+A patch run with capture on therefore produces a byte-identical output file to
+one with it off; the README documents how that is proven.
+
+The one way capture changes a run is by *refusing* it: when the input it is
+asked to describe cannot yield an honest record, it raises `CaptureError`
+instead of storing a false one. That aborts the patcher before its write, which
+is the point — a reference nobody can trust is worse than no reference, because
+the Swift port is graded against it and a boot panic is the failing grade. The
+two refusals are documented at `_assert_not_degenerate` and
+`_assert_pristine_input`; both are unreachable on a clean capture over pristine
+inputs, which is the only capture the README asks for.
+
+One capture root per (variant x iOS build)
+------------------------------------------
+A root holds exactly one copy of each input under `raw_payloads/`, and
+`PatchComparisonTests.swift` replays the Swift port against that one copy and
+asserts the record count matches. So a root describes one build, and capturing a
+second build into it would silently mix two references. `_assert_pristine_input`
+catches the common way that happens — re-running an install over a tree the last
+capture already patched — and `flush()` warns when a site's bytes disagree with
+what the root already holds.
+
+Output layout — the existing `ipsws/patch_refactor_input/` convention
+---------------------------------------------------------------------
+ <root>/reference_patches/<group>.json one JSON array per patcher
+ <root>/raw_payloads/<name> the pre-patch input, for replaying
+ <root>/reference_patches/_capture_log.jsonl
+ <root>/reference_patches/_capture_warnings.jsonl
+
+Each JSON object carries two key sets naming the same values:
+
+ * `patchID` / `component` / `fileOffset` / `virtualAddress` / `originalBytes` /
+ `patchedBytes` / `beforeDisasm` / `afterDisasm` / `patchDescription` —
+ `FirmwarePatcher.PatchRecord`'s own `Codable` keys, `Data` as base64, so
+ `JSONDecoder().decode([PatchRecord].self, from:)` works directly.
+ * `file_offset` / `patch_bytes` / `patch_size` / `description` / `component` —
+ the `ReferencePatch` struct `tests/FirmwarePatcherTests/PatchComparisonTests.swift`
+ already decodes, bytes as lowercase hex.
+
+Neither decoder minds the other's keys, so the capture needs no translation
+layer on either side.
+"""
+
+import atexit
+import base64
+import hashlib
+import json
+import os
+import struct
+import sys
+import time
+
+
+class CaptureError(Exception):
+ """The capture cannot describe this write honestly, so it stops the run.
+
+ Raised only from the two guards named in the module docstring. It is not a
+ patcher failure: it means the *input* was wrong for a capture (already
+ patched, or a site that did not change), and continuing would write a
+ reference that lies about the pristine bytes.
+ """
+
+# Environment override, so a whole `cfw_install*.sh` run captures without any
+# shell edit: `VPHONE_PATCH_RECORDS=<root> make cfw_install_exp`.
+ENV_VAR = "VPHONE_PATCH_RECORDS"
+
+# DSC code-signature page granularity on these caches. Used only to decide how
+# much context to stash alongside a DSC patch, never to locate one.
+DSC_PAGE_SIZE = 0x4000
+
+# A raw payload above this is not worth copying — the DSC chunks are ~8 GiB and
+# are captured page-wise instead.
+MAX_PAYLOAD_BYTES = 512 * 1024 * 1024
+
+# Whole-file before/after is inlined into the JSON below this; past it only the
+# SHA-256 goes in, and the two payload copies carry the bytes. Each record
+# spells its bytes twice (base64 for PatchRecord, hex for ReferencePatch), so a
+# generous limit here costs four times the file size in JSON.
+MAX_INLINE_REWRITE_BYTES = 256 * 1024
+
+# A patched region that spans more than this many disjoint runs is a structural
+# rewrite wearing a diff's clothes; record it as one span instead.
+MAX_DIFF_RUNS = 512
+
+
+# MARK: - Capture state
+
+
+class _Capture:
+ def __init__(self, root):
+ self.root = root
+ self.reference_dir, self.payload_dir = _resolve_dirs(root)
+ # Directories are created on first write, not here. Creating them in the
+ # constructor is how a mis-parsed `--emit-records <subcommand>` used to
+ # leave a junk `./<subcommand>/reference_patches/` tree in the cwd of a
+ # run that then exited 1 without capturing anything.
+ self.dirs_ready = False
+ self.group = "unclassified"
+ self.records = []
+ self.pending = None
+ self.dsc_pages = {} # (chunk_path, page_index) -> bytes before the write
+ self.payloads = {} # raw_payloads name -> sha256 of what is stored there
+ self.group_index = {} # group -> {"inputs": {...}, "outputs": {...}}
+ self.warnings = []
+ self.started = time.time()
+
+
+def _ensure_dirs():
+ if not _capture.dirs_ready:
+ os.makedirs(_capture.reference_dir, exist_ok=True)
+ os.makedirs(_capture.payload_dir, exist_ok=True)
+ _capture.dirs_ready = True
+
+
+def _warn(kind, **fields):
+ """Note something the capture could still store but nobody should trust.
+
+ Louder than a comment, quieter than `CaptureError`: it goes to stderr now
+ and to `_capture_warnings.jsonl` at flush, so a capture that needs a second
+ look says so without aborting an install that is otherwise fine.
+ """
+ entry = dict(kind=kind, group=_capture.group if _capture else None, **fields)
+ if _capture is not None:
+ _capture.warnings.append(entry)
+ sys.stderr.write(f"[capture] WARNING {kind}: "
+ + ", ".join(f"{k}={v}" for k, v in fields.items() if v is not None)
+ + "\n")
+
+
+_capture = None
+_env_checked = False
+
+
+def _resolve_dirs(root):
+ """`<root>` is `ipsws/patch_refactor_input/` (or its `reference_patches/`
+ subdirectory — both spellings land in the same place)."""
+ root = os.path.abspath(os.path.expanduser(root))
+ base = os.path.dirname(root) if os.path.basename(root) == "reference_patches" else root
+ return os.path.join(base, "reference_patches"), os.path.join(base, "raw_payloads")
+
+
+def resolve_dirs(root):
+ """Where a given capture root puts its two directories."""
+ return _resolve_dirs(root)
+
+
+def enable(root, *, group=None):
+ """Turn capture on, writing under `root`. Idempotent per process."""
+ global _capture
+ if _capture is None:
+ _capture = _Capture(root)
+ atexit.register(flush)
+ if group:
+ set_group(group)
+ return _capture.reference_dir
+
+
+def enabled():
+ """True when capture is on. Picks up `VPHONE_PATCH_RECORDS` on first ask, so
+ a patcher imported and called directly records without any argv plumbing."""
+ global _env_checked
+ if _capture is None and not _env_checked:
+ _env_checked = True
+ root = os.environ.get(ENV_VAR)
+ if root:
+ enable(root)
+ return _capture is not None
+
+
+def set_group(name):
+ """Name the output file. Records already held under a different group are
+ flushed first so one process can drive several patchers."""
+ if not enabled():
+ return
+ if name == _capture.group:
+ return
+ if _capture.records:
+ flush()
+ _capture.group = name
+
+
+def next_site(patch_id, description, *, component=None, virtual_address=None):
+ """Label the next recorded write. One-shot: consumed by whichever write
+ lands next, so a loop over N symbols labels each of the N records."""
+ if not enabled():
+ return
+ _capture.pending = {
+ "patch_id": patch_id,
+ "description": description,
+ "component": component,
+ "virtual_address": virtual_address,
+ }
+
+
+def default_root():
+ """`<repo>/ipsws/patch_refactor_input` — the convention the Swift
+ comparison harness already reads from."""
+ here = os.path.dirname(os.path.abspath(__file__))
+ repo = os.path.dirname(os.path.dirname(here))
+ return os.path.join(repo, "ipsws", "patch_refactor_input")
+
+
+def _looks_like_root(token, reserved):
+ """Is `token` the `<root>` of a bare `--emit-records <root>`, or the next
+ real argument?
+
+ `--emit-records` takes an optional value, so the separated spelling is
+ ambiguous by construction. Consuming any non-dash token, which is what this
+ used to do, ate the subcommand out of
+ `cfw.py --emit-records patch-seputil <bin>`: the run then died with
+ "Unknown command: <bin>" and left a `./patch-seputil/` capture tree behind.
+
+ A root is a filesystem path, so that is what is required of it: a separator,
+ a `~`, `.`/`..`, or a directory that already exists. A caller that knows its
+ own verbs (`cfw.py` passes its dispatch table) also gets them excluded by
+ name. Anything else means the flag was written bare — use the default root.
+ A root with no separator that does not exist yet has to be spelled
+ `--emit-records=<root>`.
+ """
+ if not token or token.startswith("-") or token in reserved:
+ return False
+ if token.startswith("~") or os.sep in token or token in (".", ".."):
+ return True
+ if os.altsep and os.altsep in token:
+ return True
+ return os.path.isdir(token)
+
+
+def take_cli_flag(argv, *, reserved=()):
+ """Strip `--emit-records [<root>]` / `--emit-records=<root>` out of `argv`
+ and turn capture on. Returns `(argv_without_flag, root_or_None)`.
+
+ Stripping rather than parsing in place is deliberate: every `cfw.py`
+ subcommand indexes `sys.argv` positionally, so the flag has to be gone
+ before dispatch for all of them to accept it without touching their
+ argument handling.
+
+ `reserved` is the caller's own argument vocabulary — subcommand names it
+ must never lose to the flag's optional value.
+ """
+ reserved = frozenset(reserved)
+ out = []
+ root = None
+ found = False
+ i = 0
+ while i < len(argv):
+ arg = argv[i]
+ if arg == "--emit-records":
+ found = True
+ if i + 1 < len(argv) and _looks_like_root(argv[i + 1], reserved):
+ root = argv[i + 1]
+ i += 2
+ else:
+ i += 1
+ continue
+ if arg.startswith("--emit-records="):
+ found = True
+ root = arg.split("=", 1)[1]
+ i += 1
+ continue
+ out.append(arg)
+ i += 1
+ if found:
+ enable(root or os.environ.get(ENV_VAR) or default_root())
+ return out, root
+
+
+def site(file_offset, length, patch_id, description, *, virtual_address=None):
+ """Declare a patch span for `record_file_write`. Plain data, no side effect —
+ safe to build even when capture is off (the caller's list is just ignored)."""
+ return {
+ "file_offset": file_offset,
+ "length": length,
+ "patch_id": patch_id,
+ "description": description,
+ "virtual_address": virtual_address,
+ }
+
+
+# MARK: - What this root already holds
+
+
+def _group_index(group):
+ """What files this group has already described, read once per process.
+
+ Two views, both keyed off the whole-file hashes every file-level record
+ carries:
+
+ * `inputs` — source path -> {sha256 of the file this group has already
+ called the *original* at that path};
+ * `outputs` — basename -> {sha256 of the file *after* a recorded patch},
+ so the capture recognises its own output handed back to it even when
+ the install ran under a different temporary path.
+
+ `flush()` does its own dedupe straight off the file, so nothing about record
+ identity is cached here — only what the guard needs.
+ """
+ cached = _capture.group_index.get(group)
+ if cached is not None:
+ return cached
+ index = {"inputs": {}, "outputs": {}}
+ path = os.path.join(_capture.reference_dir, f"{group}.json")
+ try:
+ with open(path, "r") as f:
+ existing = json.load(f)
+ except (OSError, ValueError):
+ existing = []
+ if isinstance(existing, list):
+ for rec in existing:
+ if not isinstance(rec, dict) or "patchID" not in rec:
+ continue
+ source = rec.get("file") or ""
+ if rec.get("file_sha256_before"):
+ index["inputs"].setdefault(source, set()).add(
+ rec["file_sha256_before"])
+ if rec.get("file_sha256_after"):
+ index["outputs"].setdefault(os.path.basename(source), set()).add(
+ rec["file_sha256_after"])
+ _capture.group_index[group] = index
+ return index
+
+
+def _note_input(group, path, file_before_sha):
+ """Remember what this process just called an original, so a second run
+ inside one process is caught without waiting for a flush."""
+ if file_before_sha:
+ _group_index(group)["inputs"].setdefault(path, set()).add(file_before_sha)
+
+
+def _note_output(group, path, file_after_sha):
+ """Remember a file hash this process just produced, same reason."""
+ if file_after_sha:
+ _group_index(group)["outputs"].setdefault(
+ os.path.basename(path), set()).add(file_after_sha)
+
+
+def _assert_pristine_input(path, before):
+ """Refuse to describe an input this root has already recorded patching.
+
+ The capture reads `originalBytes` off the file on disk. Run it twice over
+ the same tree and the second run reads run 1's *output* and calls it the
+ original — every record it writes then misdescribes the pristine image.
+ Dedupe cannot save that: the bytes differ from run 1's, so a bytes-keyed key
+ could never collide, and a patcher that is not idempotent (launchd's cache
+ loader and jetsam guard each find a *second* site on an already-patched
+ binary) lands a genuinely new, genuinely wrong record at an offset run 1
+ never touched. So the guard is at the front door instead.
+
+ Two nets, because a capture can arrive here two ways:
+
+ * the same source path, different bytes — this group already recorded an
+ original at this path and it is not this one. That covers the chained
+ case the "is it my own output?" test misses: `cfw_install_exp.sh` runs
+ `inject-dylib` and then `patch-launchd-jetsam` over one `launchd`, so on
+ a re-capture jetsam's input is neither pristine nor jetsam's own output.
+ * these exact bytes, recorded as an *output* — the tree is this root's own
+ result, reached under some other temporary path.
+
+ Anything else that merely looks unfamiliar is warned about, not refused: a
+ patcher legitimately runs over several files that share a basename (SystemOS
+ and AppOS cryptexes), and those are different sites, not a re-capture.
+
+ Returns the input's sha256, which the caller threads into its records.
+ """
+ sha = hashlib.sha256(before).hexdigest()
+ index = _group_index(_capture.group)
+
+ known_here = index["inputs"].get(path)
+ if known_here and sha not in known_here:
+ raise CaptureError(
+ f"re-capture refused: {_capture.root} already holds records taken "
+ f"from {path} with a different original (sha256 "
+ f"{sorted(known_here)[0][:16]}..., now {sha[:16]}...), group "
+ f"'{_capture.group}'. The file has been patched since — recording "
+ f"it as an original would describe the wrong bytes. Restore the "
+ f"pristine input, or capture into a fresh root: one root per "
+ f"(variant x iOS build)."
+ )
+
+ produced = index["outputs"].get(os.path.basename(path))
+ if produced and sha in produced:
+ raise CaptureError(
+ f"re-capture refused: {path} is already the *patched* output of an "
+ f"earlier capture into {_capture.root} (sha256 {sha[:16]}..., "
+ f"group '{_capture.group}'). Restore the pristine input, or capture "
+ f"into a fresh root — one root per (variant x iOS build)."
+ )
+
+ if not known_here and index["inputs"]:
+ stem = os.path.basename(path)
+ siblings = {os.path.basename(p) for p in index["inputs"]}
+ if stem in siblings:
+ _warn("unfamiliar input for a known basename", file=path,
+ sha256=sha[:16],
+ note="this group already recorded a different file called "
+ f"'{stem}'; fine for SystemOS vs AppOS, a re-capture "
+ "under a new temp path otherwise")
+
+ _note_input(_capture.group, path, sha)
+ return sha
+
+
+# MARK: - Record construction
+
+
+def _cs_engine():
+ try:
+ try:
+ from .cfw_asm import _cs
+ except ImportError:
+ from cfw_asm import _cs
+ return _cs
+ except Exception:
+ return None
+
+
+def _disasm(blob, address):
+ """Best-effort ARM64 text for `blob`. Returns "" unless the whole span
+ decodes cleanly — a half-decoded string would be worse than none.
+
+ A record without a virtual address is not mapped code (a header field, a
+ code-signature slot, a plist), so it is never disassembled: "udf #0" as the
+ reading of a zeroed `maxSlide` would be actively misleading.
+ """
+ if address is None or not blob or len(blob) % 4 or len(blob) > 64:
+ return ""
+ cs = _cs_engine()
+ if cs is None:
+ return ""
+ parts, covered = [], 0
+ try:
+ for insn in cs.disasm(bytes(blob), address or 0):
+ parts.append(f"{insn.mnemonic} {insn.op_str}".strip())
+ covered += insn.size
+ except Exception:
+ return ""
+ if covered != len(blob) or not parts:
+ return ""
+ return "; ".join(parts)
+
+
+def _assert_not_degenerate(patch_id, component, file_offset, original, patched,
+ source_file):
+ """A record whose `originalBytes` equal its `patchedBytes` is not a patch.
+
+ Stored, it asserts a false thing about the pristine image: "at this offset
+ the untouched file held exactly what the patched file holds". Every way of
+ producing one is a bug worth stopping for —
+
+ * re-capturing over a tree a previous capture already patched, so the
+ patcher reads its own output back as the original (this is how
+ diskimagesiod and mobileactivationd grew a second, degenerate record);
+ * a `site()` declaring a span the patcher did not actually change.
+
+ Both mean the capture is describing something other than the patch, so it
+ refuses rather than writing a record the Swift comparison would happily and
+ wrongly satisfy with a port that writes nothing.
+ """
+ raise CaptureError(
+ f"degenerate record refused: {patch_id} @ 0x{file_offset:X} in "
+ f"{component} claims a patch but original == patched "
+ f"({original.hex()[:32] or '<empty>'}). "
+ f"Source: {source_file or '<none>'}. "
+ f"The usual cause is a re-capture over an already-patched input — "
+ f"restore the pristine file, or capture into a fresh root."
+ )
+
+
+def _make_record(patch_id, component, file_offset, original, patched,
+ *, virtual_address, description, source_file, inline,
+ file_before_sha=None, file_after_sha=None,
+ payload_before=None, payload_after=None):
+ original = bytes(original or b"")
+ patched = bytes(patched or b"")
+ if inline and original == patched:
+ _assert_not_degenerate(patch_id, component, file_offset,
+ original, patched, source_file)
+ if not inline:
+ # The bytes did not fit, so `patch_bytes` is empty and the Swift
+ # comparison cannot check this record — it can only be a pointer at the
+ # payload pair. Name it so nobody mistakes it for a check, and warn.
+ patch_id = f"{patch_id}.opaque"
+ _warn("opaque record", patch_id=patch_id, component=component,
+ file=source_file, orig_size=len(original),
+ patched_size=len(patched),
+ note="too large to inline; not comparable — needs a structural "
+ "recorder before this group can grade a Swift port")
+ before = _disasm(original, virtual_address) if inline else ""
+ after = _disasm(patched, virtual_address) if inline else ""
+ rec = {
+ # FirmwarePatcher.PatchRecord — decodes straight into [PatchRecord].
+ "patchID": patch_id,
+ "component": component,
+ "fileOffset": file_offset,
+ "virtualAddress": virtual_address,
+ "originalBytes": base64.b64encode(original).decode() if inline else "",
+ "patchedBytes": base64.b64encode(patched).decode() if inline else "",
+ "beforeDisasm": before,
+ "afterDisasm": after,
+ "patchDescription": description,
+ # PatchComparisonTests.ReferencePatch — same values, its spelling.
+ # `patch_size` describes `patch_bytes`, so it is 0 when the bytes were
+ # too big to inline; the true lengths are in the provenance fields and
+ # the bytes themselves are the `raw_payloads/` pair.
+ "file_offset": file_offset,
+ "patch_bytes": patched.hex() if inline else "",
+ "patch_size": len(patched) if inline else 0,
+ "description": description,
+ # Capture provenance. Both decoders ignore these.
+ "orig_bytes": original.hex() if inline else "",
+ "orig_size": len(original),
+ "patched_size": len(patched),
+ "va": f"0x{virtual_address:X}" if virtual_address is not None else None,
+ "file": source_file,
+ "orig_sha256": hashlib.sha256(original).hexdigest(),
+ "patch_sha256": hashlib.sha256(patched).hexdigest(),
+ "inline_bytes": bool(inline),
+ "comparable": bool(inline),
+ # Whole-file hashes, when the recorder read whole files. These are what
+ # `_assert_pristine_input` matches a later run's input against, and what
+ # tells a replay harness which `raw_payloads/` entry a record belongs to.
+ "file_sha256_before": file_before_sha,
+ "file_sha256_after": file_after_sha,
+ "payload_before": payload_before,
+ "payload_after": payload_after,
+ }
+ return rec
+
+
+def record(patch_id, component, file_offset, original_bytes, patched_bytes,
+ *, virtual_address=None, description="", source_file=None, inline=True,
+ file_before_sha=None, file_after_sha=None,
+ payload_before=None, payload_after=None):
+ """Append one patch record. The lowest level; everything else funnels here."""
+ if not enabled():
+ return
+ _capture.records.append(_make_record(
+ patch_id, component, file_offset, original_bytes, patched_bytes,
+ virtual_address=virtual_address, description=description,
+ source_file=source_file, inline=inline,
+ file_before_sha=file_before_sha, file_after_sha=file_after_sha,
+ payload_before=payload_before, payload_after=payload_after,
+ ))
+
+
+def record_span(component, file_offset, original_bytes, patched_bytes,
+ *, virtual_address=None, source_file=None):
+ """Record a write whose label came from `next_site`."""
+ if not enabled():
+ return
+ pending = _capture.pending
+ _capture.pending = None
+ if pending:
+ patch_id = pending["patch_id"]
+ description = pending["description"]
+ component = pending["component"] or component
+ if virtual_address is None:
+ virtual_address = pending["virtual_address"]
+ else:
+ patch_id = f"{_capture.group}.site{len(_capture.records)}"
+ description = f"undeclared write in {_capture.group}"
+ record(patch_id, component, file_offset, original_bytes, patched_bytes,
+ virtual_address=virtual_address, description=description,
+ source_file=source_file)
+
+
+# MARK: - File-level capture
+
+
+def _diff_runs(before, after):
+ """Contiguous byte runs where `before` and `after` differ. Equal lengths
+ only — a length change is a rewrite, not a patch."""
+ runs = []
+ n = len(before)
+ i = 0
+ while i < n:
+ if before[i] == after[i]:
+ i += 1
+ continue
+ start = i
+ while i < n and before[i] != after[i]:
+ i += 1
+ runs.append((start, i))
+ if len(runs) > MAX_DIFF_RUNS:
+ return None
+ return runs
+
+
+def _stored_payload_sha(name):
+ """sha256 of what `raw_payloads/<name>` already holds, or None."""
+ known = _capture.payloads.get(name)
+ if known is not None:
+ return known
+ dest = os.path.join(_capture.payload_dir, name)
+ try:
+ if os.path.getsize(dest) > MAX_PAYLOAD_BYTES:
+ return None
+ with open(dest, "rb") as f:
+ sha = hashlib.sha256(f.read()).hexdigest()
+ except OSError:
+ return None
+ _capture.payloads[name] = sha
+ return sha
+
+
+def write_payload(name, blob, sha=None):
+ """Store `blob` in `raw_payloads/` and return the name it landed under.
+
+ Writes the buffer the caller already has rather than re-reading the file,
+ which is the only correct thing to do on the `record_file_write` path: there
+ the file on disk is still the *original* when the record is made, so
+ re-reading it to save "<name>.patched" would have saved the original bytes
+ under the patched name.
+
+ First distinct content wins the plain name, so `raw_payloads/<binary>` stays
+ the pristine input the Swift harness loads. A later, different input for the
+ same basename — a second patcher in a chain, which sees its predecessor's
+ output — gets a hash-qualified name instead of silently sharing or
+ overwriting the first one.
+ """
+ if not enabled():
+ return None
+ blob = bytes(blob)
+ if len(blob) > MAX_PAYLOAD_BYTES:
+ return None
+ sha = sha or hashlib.sha256(blob).hexdigest()
+ stored = _stored_payload_sha(name)
+ if stored == sha:
+ return name
+ if stored is not None:
+ name = f"{name}.{sha[:12]}"
+ if _stored_payload_sha(name) == sha:
+ return name
+ try:
+ _ensure_dirs()
+ with open(os.path.join(_capture.payload_dir, name), "wb") as out:
+ out.write(blob)
+ except OSError:
+ return None
+ _capture.payloads[name] = sha
+ return name
+
+
+def capture_payload(path, *, name=None):
+ """Copy the file as it stands right now into `raw_payloads/`, so a harness
+ has the pre-patch input to replay. Returns the stored name."""
+ if not enabled():
+ return None
+ try:
+ if os.path.getsize(path) > MAX_PAYLOAD_BYTES:
+ return None
+ with open(path, "rb") as f:
+ blob = f.read()
+ except OSError:
+ return None
+ return write_payload(name or os.path.basename(path), blob)
+
+
+def record_file_write(path, new_data, *, component=None, sites=None,
+ patch_id=None, description="", capture_input=True):
+ """Record what writing `new_data` over `path` changes.
+
+ Called immediately *before* the write, while the file on disk is still the
+ original — so the diff is ground truth, not a transcription of what the
+ patcher believes it did.
+
+ `sites` (from `site()`) names the spans the patcher meant to change; each
+ becomes its own record. Anything else that differs is still recorded, under
+ an `.undeclared` id, which is the point: a declaration that drifts from the
+ bytes shows up in the capture instead of hiding in it.
+ """
+ if not enabled():
+ return
+ component = component or _capture.group
+ try:
+ with open(path, "rb") as f:
+ before = f.read()
+ except OSError:
+ return
+ after = bytes(new_data)
+ before_sha = _assert_pristine_input(path, before)
+ after_sha = hashlib.sha256(after).hexdigest()
+ payload_before = capture_payload(path) if capture_input else None
+
+ if len(before) != len(after):
+ _record_rewrite(path, before, after, component,
+ patch_id or f"{component}.rewrite", description,
+ before_sha=before_sha, after_sha=after_sha,
+ payload_before=payload_before)
+ _note_output(_capture.group, path, after_sha)
+ return
+
+ claimed = []
+ for s in (sites or []):
+ off, ln = s["file_offset"], s["length"]
+ if off < 0 or ln <= 0 or off + ln > len(after):
+ continue
+ claimed.append((off, off + ln))
+ record(s["patch_id"], component, off,
+ before[off:off + ln], after[off:off + ln],
+ virtual_address=s["virtual_address"],
+ description=s["description"], source_file=path,
+ file_before_sha=before_sha, file_after_sha=after_sha,
+ payload_before=payload_before)
+
+ runs = _diff_runs(before, after)
+ if runs is None:
+ _record_rewrite(path, before, after, component,
+ patch_id or f"{component}.rewrite", description,
+ before_sha=before_sha, after_sha=after_sha,
+ payload_before=payload_before)
+ _note_output(_capture.group, path, after_sha)
+ return
+ for start, end in runs:
+ if any(c_start <= start and end <= c_end for c_start, c_end in claimed):
+ continue
+ record(f"{patch_id or component}.undeclared.0x{start:X}", component, start,
+ before[start:end], after[start:end],
+ description=description or f"undeclared change in {component}",
+ source_file=path,
+ file_before_sha=before_sha, file_after_sha=after_sha,
+ payload_before=payload_before)
+ _note_output(_capture.group, path, after_sha)
+
+
+def _record_rewrite(path, before, after, component, patch_id, description,
+ *, before_sha=None, after_sha=None, payload_before=None):
+ """Last resort: one record for the whole file, before and after.
+
+ Only reached when nothing structural is known about the format, so prefer a
+ structural recorder (`record_macho_lc_edit`) wherever one exists — past
+ `MAX_INLINE_REWRITE_BYTES` this emits an `.opaque` record that the Swift
+ comparison cannot check at all.
+ """
+ before_sha = before_sha or hashlib.sha256(before).hexdigest()
+ after_sha = after_sha or hashlib.sha256(after).hexdigest()
+ inline = max(len(before), len(after)) <= MAX_INLINE_REWRITE_BYTES
+ payload_before = payload_before or write_payload(
+ os.path.basename(path), before, before_sha)
+ payload_after = None
+ if not inline:
+ # From the `after` buffer, never by re-reading `path`: on the
+ # `record_file_write` path the write has not happened yet.
+ payload_after = write_payload(
+ f"{payload_before or os.path.basename(path)}.patched", after, after_sha)
+ record(patch_id, component, 0, before, after,
+ description=description or f"whole-file rewrite of {component}",
+ source_file=path, inline=inline,
+ file_before_sha=before_sha, file_after_sha=after_sha,
+ payload_before=payload_before, payload_after=payload_after)
+
+
+def record_file_rewrite(path, new_data, *, component, patch_id, description=""):
+ """Whole-file structural rewrite (plists, device trees) where a byte diff
+ would be noise. One record, before and after, from the file on disk."""
+ if not enabled():
+ return
+ try:
+ with open(path, "rb") as f:
+ before = f.read()
+ except OSError:
+ return
+ after = bytes(new_data)
+ before_sha = _assert_pristine_input(path, before)
+ after_sha = hashlib.sha256(after).hexdigest()
+ _record_rewrite(path, before, after, component, patch_id, description,
+ before_sha=before_sha, after_sha=after_sha)
+ _note_output(_capture.group, path, after_sha)
+
+
+def record_blob_diff(component, before, after, *, patch_id_prefix,
+ description="", source_file=None, base_offset=0):
+ """Record a diff of a decoded payload rather than a file — the device-tree
+ blob inside an IM4P, say, where the file offsets mean nothing until the
+ container is unwrapped. Offsets are payload-relative; `component` says so."""
+ if not enabled():
+ return
+ before, after = bytes(before), bytes(after)
+ if len(before) != len(after):
+ record(f"{patch_id_prefix}.payload", component, base_offset, before, after,
+ description=description or f"{component} payload replaced",
+ source_file=source_file,
+ inline=max(len(before), len(after)) <= MAX_INLINE_REWRITE_BYTES)
+ return
+ runs = _diff_runs(before, after)
+ if runs is None:
+ record(f"{patch_id_prefix}.payload", component, base_offset, before, after,
+ description=description or f"{component} payload replaced",
+ source_file=source_file,
+ inline=len(before) <= MAX_INLINE_REWRITE_BYTES)
+ return
+ for start, end in runs:
+ record(f"{patch_id_prefix}.0x{start:X}", component, base_offset + start,
+ before[start:end], after[start:end],
+ description=description, source_file=source_file)
+
+
+def snapshot_file(path):
+ """Read `path` as it stands, for patchers that write through a serializer
+ (`plistlib.dump`) or an external program and so have no buffer to diff.
+ Returns None when capture is off, which `record_after_write` treats as
+ "nothing to do" — so the pair costs one branch in the normal path."""
+ if not enabled():
+ return None
+ try:
+ with open(path, "rb") as f:
+ before = f.read()
+ except OSError:
+ return None
+ _assert_pristine_input(path, before)
+ capture_payload(path)
+ return before
+
+
+def record_after_write(path, before, *, component, patch_id, description="",
+ structure=None):
+ """Close the pair opened by `snapshot_file`, reading the file back."""
+ if before is None or not enabled():
+ return
+ try:
+ with open(path, "rb") as f:
+ after = f.read()
+ except OSError:
+ return
+ record_external_edit(path, before, after, component=component,
+ patch_id=patch_id, description=description,
+ structure=structure)
+
+
+def record_external_edit(path, before, after, *, component, patch_id,
+ description="", structure=None):
+ """An edit made by a program we shell out to (`insert_dylib`). Caller reads
+ the file either side of the call; we only classify the difference.
+
+ `structure="macho"` says the file is a Mach-O whose *load commands* are the
+ edit, so a length change is described by `record_macho_lc_edit` — the
+ header and the inserted command — rather than collapsing into one opaque
+ whole-file record.
+ """
+ if not enabled():
+ return
+ before, after = bytes(before), bytes(after)
+ before_sha = hashlib.sha256(before).hexdigest()
+ after_sha = hashlib.sha256(after).hexdigest()
+ if before == after:
+ return
+ if len(before) == len(after):
+ runs = _diff_runs(before, after)
+ if runs is not None:
+ for start, end in runs:
+ record(f"{patch_id}.0x{start:X}", component, start,
+ before[start:end], after[start:end],
+ description=description, source_file=path,
+ file_before_sha=before_sha, file_after_sha=after_sha)
+ _note_output(_capture.group, path, after_sha)
+ return
+ if structure == "macho" and record_macho_lc_edit(
+ path, before, after, component=component, patch_id=patch_id,
+ description=description,
+ before_sha=before_sha, after_sha=after_sha):
+ _note_output(_capture.group, path, after_sha)
+ return
+ _record_rewrite(path, before, after, component, patch_id, description,
+ before_sha=before_sha, after_sha=after_sha)
+ _note_output(_capture.group, path, after_sha)
+
+
+# MARK: - Mach-O load-command edits
+
+
+LC_REQ_DYLD = 0x80000000
+MH_MAGIC_64 = 0xFEEDFACF # 64-bit Mach-O, little-endian on disk here
+FAT_CIGAM = 0xBEBAFECA # FAT_MAGIC (0xCAFEBABE) read little-endian
+FAT_CIGAM_64 = 0xBFBAFECA
+_DYLIB_LOAD_COMMANDS = (
+ 0x0C, # LC_LOAD_DYLIB
+ 0x0D, # LC_ID_DYLIB
+ 0x20, # LC_LAZY_LOAD_DYLIB
+ 0x18 | LC_REQ_DYLD, # LC_LOAD_WEAK_DYLIB — what `insert_dylib --weak`
+ 0x1F | LC_REQ_DYLD, # LC_REEXPORT_DYLIB writes
+)
+_MACH_HEADER_64_SIZE = 32
+
+
+def _macho_slices(buf):
+ """File offsets of the 64-bit Mach-O images in `buf`, in file order.
+
+ One entry for a thin binary, one per arch for a universal one. Returns []
+ for anything this does not recognise, which sends the caller back to the
+ whole-file path rather than guessing.
+ """
+ if len(buf) < 8:
+ return []
+ magic = struct.unpack_from("<I", buf, 0)[0]
+ if magic == MH_MAGIC_64:
+ return [0]
+ if magic not in (FAT_CIGAM, FAT_CIGAM_64):
+ return []
+ is64 = magic == FAT_CIGAM_64
+ nfat = struct.unpack_from(">I", buf, 4)[0]
+ entry = 32 if is64 else 20
+ offs = []
+ for i in range(nfat):
+ base = 8 + i * entry
+ if base + entry > len(buf):
+ return []
+ if is64:
+ off = struct.unpack_from(">Q", buf, base + 8)[0]
+ else:
+ off = struct.unpack_from(">I", buf, base + 8)[0]
+ if off + _MACH_HEADER_64_SIZE > len(buf):
+ return []
+ if struct.unpack_from("<I", buf, off)[0] != MH_MAGIC_64:
+ return []
+ offs.append(off)
+ return offs
+
+
+def _macho_load_commands(buf, slice_off):
+ """`(ncmds, sizeofcmds, [(offset, cmd, size)])` for one 64-bit image."""
+ if slice_off + _MACH_HEADER_64_SIZE > len(buf):
+ return None
+ _, _, _, _, ncmds, sizeofcmds, _, _ = struct.unpack_from("<8I", buf, slice_off)
+ pos = slice_off + _MACH_HEADER_64_SIZE
+ end = pos + sizeofcmds
+ if end > len(buf) or ncmds > 4096:
+ return None
+ cmds = []
+ for _ in range(ncmds):
+ if pos + 8 > end:
+ return None
+ cmd, size = struct.unpack_from("<2I", buf, pos)
+ if size < 8 or pos + size > end:
+ return None
+ cmds.append((pos, cmd, size))
+ pos += size
+ return ncmds, sizeofcmds, cmds
+
+
+def record_macho_lc_edit(path, before, after, *, component, patch_id,
+ description="", before_sha=None, after_sha=None):
+ """Describe a Mach-O load-command edit by what a port must reproduce.
+
+ `insert_dylib` rewrites a file end to end — it strips the code signature and
+ reflows `__LINKEDIT`, so `launchd` came out 27 KiB *shorter* than it went
+ in. Recorded as a whole-file rewrite that was one `.opaque` record: empty
+ `patchedBytes`, `patch_size` 0, offset 0. A Swift port that emitted one
+ record with empty bytes at offset 0 and the same description matched it
+ exactly while writing nothing at all — for the LC_LOAD_WEAK_DYLIB that pid 1
+ boots through.
+
+ The edit itself is small and bounded however big the file is, and it lands
+ in a region whose offsets are the same either side of the edit: the
+ `mach_header` counters and the load commands. So that is what gets recorded,
+ run by run:
+
+ * `<patch_id>.mach_header` — the 32 bytes carrying `ncmds`/`sizeofcmds`
+ * `<patch_id>` — the inserted dylib load command, at its
+ offset, against whatever stood there before
+ * `<patch_id>.lc.0x<off>` — every other byte the command region moved
+ (`__LINKEDIT` extent, `LC_SYMTAB` sizes)
+
+ Each carries real bytes at a real offset, so a port that skips any of them
+ fails on count or on bytes. What is deliberately *not* graded here is the
+ `__LINKEDIT` reflow past the command region: that is the signature strip,
+ not the load-command write, and the payload pair is there to replay it.
+
+ Returns True when it recorded, False when the file is not a shape it can
+ describe — the caller then falls back to the whole-file record.
+ """
+ if not enabled():
+ return False
+ before, after = bytes(before), bytes(after)
+ before_sha = before_sha or hashlib.sha256(before).hexdigest()
+ after_sha = after_sha or hashlib.sha256(after).hexdigest()
+
+ slices_before = _macho_slices(before)
+ slices_after = _macho_slices(after)
+ if not slices_after or slices_before != slices_after:
+ # A moved slice means offsets are not comparable image to image; a
+ # missing header means this is not a Mach-O at all.
+ return False
+
+ payload_before = write_payload(os.path.basename(path), before, before_sha)
+ payload_after = write_payload(
+ f"{payload_before or os.path.basename(path)}.patched", after, after_sha)
+ common = dict(source_file=path, file_before_sha=before_sha,
+ file_after_sha=after_sha, payload_before=payload_before,
+ payload_after=payload_after)
+
+ staged = []
+ for slice_off in slices_after:
+ parsed_before = _macho_load_commands(before, slice_off)
+ parsed_after = _macho_load_commands(after, slice_off)
+ if parsed_before is None or parsed_after is None:
+ return False
+ _, size_before, cmds_before = parsed_before
+ _, size_after, cmds_after = parsed_after
+
+ suffix = f".slice0x{slice_off:X}" if len(slices_after) > 1 else ""
+ hdr_end = slice_off + _MACH_HEADER_64_SIZE
+ if before[slice_off:hdr_end] != after[slice_off:hdr_end]:
+ staged.append((f"{patch_id}.mach_header{suffix}", slice_off,
+ before[slice_off:hdr_end], after[slice_off:hdr_end],
+ f"mach_header ncmds/sizeofcmds updated for "
+ f"{description or 'the inserted load command'}"))
+
+ # The command region is comparable only where both images have bytes.
+ region_end = min(len(before), len(after),
+ hdr_end + max(size_before, size_after))
+ if region_end <= hdr_end:
+ continue
+
+ # The inserted dylib command: present in `after`, absent from `before`.
+ old_blobs = {before[p:p + s] for p, _, s in cmds_before}
+ claimed = []
+ for pos, cmd, size in cmds_after:
+ blob = after[pos:pos + size]
+ if cmd not in _DYLIB_LOAD_COMMANDS or blob in old_blobs:
+ continue
+ if pos + size > region_end:
+ continue
+ if before[pos:pos + size] == blob:
+ # Already there, byte for byte, at the same offset — nothing was
+ # inserted here. Leave it to the region diff, which will agree.
+ continue
+ staged.append((f"{patch_id}{suffix}", pos,
+ before[pos:pos + size], blob,
+ description or "dylib load command inserted"))
+ claimed.append((pos, pos + size))
+
+ runs = _diff_runs(before[hdr_end:region_end], after[hdr_end:region_end])
+ if runs is None:
+ return False
+ for start, end in runs:
+ off = hdr_end + start
+ stop = hdr_end + end
+ if any(lo <= off and stop <= hi for lo, hi in claimed):
+ continue
+ staged.append((f"{patch_id}.lc.0x{off:X}{suffix}", off,
+ before[off:stop], after[off:stop],
+ f"load-command region follow-on for "
+ f"{description or 'the inserted load command'}"))
+
+ if not staged:
+ # Nothing inside the header or the command region changed, so this
+ # recorder has nothing true to say about the edit.
+ return False
+ for rec_id, off, orig, patched, desc in staged:
+ record(rec_id, component, off, orig, patched, description=desc, **common)
+ return True
+
+
+# MARK: - DSC page context
+
+
+def note_dsc_page(chunk_path, file_offset):
+ """Stash the 16 KiB code-signature page around a DSC write, before it lands.
+ Copying the whole cache is out of the question, and the page is what P1.1's
+ slot-hash cross-check needs anyway."""
+ if not enabled():
+ return
+ page_index = file_offset // DSC_PAGE_SIZE
+ key = (chunk_path, page_index)
+ if key in _capture.dsc_pages:
+ return
+ try:
+ with open(chunk_path, "rb") as f:
+ f.seek(page_index * DSC_PAGE_SIZE)
+ _capture.dsc_pages[key] = f.read(DSC_PAGE_SIZE)
+ except OSError:
+ pass
+
+
+def _flush_dsc_pages():
+ """Write each stashed page's before/after pair. "After" is read at flush,
+ not at write time, so it includes the code-signature re-attestation."""
+ pages_dir = os.path.join(_capture.payload_dir, "dsc_pages")
+ for (chunk_path, page_index), before in _capture.dsc_pages.items():
+ stem = f"{os.path.basename(chunk_path)}.page{page_index:06d}"
+ try:
+ os.makedirs(pages_dir, exist_ok=True)
+ with open(os.path.join(pages_dir, stem + ".before.bin"), "wb") as f:
+ f.write(before)
+ with open(chunk_path, "rb") as src:
+ src.seek(page_index * DSC_PAGE_SIZE)
+ after = src.read(DSC_PAGE_SIZE)
+ with open(os.path.join(pages_dir, stem + ".after.bin"), "wb") as f:
+ f.write(after)
+ except OSError:
+ continue
+ _capture.dsc_pages = {}
+
+
+# MARK: - Flush
+
+
+def _flush_warnings():
+ """Persist anything `_warn` collected, so a capture that needs a second look
+ still says so in the root itself after the terminal has scrolled away."""
+ if not _capture.warnings:
+ return
+ try:
+ _ensure_dirs()
+ with open(os.path.join(_capture.reference_dir,
+ "_capture_warnings.jsonl"), "a") as f:
+ for entry in _capture.warnings:
+ entry.setdefault("utc", time.strftime("%Y-%m-%dT%H:%M:%SZ",
+ time.gmtime()))
+ f.write(json.dumps(entry) + "\n")
+ except OSError:
+ return
+ _capture.warnings = []
+
+
+def _dedupe_key(rec):
+ """What makes two records the same record: the *site*, not the bytes.
+
+ This used to include `orig_sha256` and `patch_sha256`, which made the key
+ unable to do its job. The capture reads `originalBytes` off disk, so a
+ second capture over an already-patched tree reads different original bytes
+ and produced a key that could never collide with run 1's — the very case
+ dedupe existed for. Keying on the site collapses it instead, and when the
+ bytes disagree that is reported as a conflict rather than quietly stored as
+ a second truth about one offset.
+
+ The source file's basename is in the key because one install legitimately
+ runs a patcher over several files (SystemOS and AppOS cryptexes), and those
+ are different sites that can share an offset and a patch id.
+ """
+ return (rec["patchID"], rec["component"], rec["fileOffset"],
+ os.path.basename(rec.get("file") or ""))
+
+
+def flush():
+ """Merge this run's records into `<group>.json` and clear them.
+
+ Merging rather than overwriting: one install runs a patcher several times
+ (SystemOS and AppOS cryptexes, repeated variants), and the capture wants all
+ of it. A site already in the file keeps the record it has; if this run's
+ bytes for that site disagree, the disagreement is warned about, because it
+ means two different inputs are being captured into one root and the root can
+ only describe one.
+ """
+ if _capture is None:
+ return
+ if not _capture.records:
+ _flush_warnings()
+ return
+ _ensure_dirs()
+ path = os.path.join(_capture.reference_dir, f"{_capture.group}.json")
+ merged = []
+ seen = {}
+ try:
+ with open(path, "r") as f:
+ existing = json.load(f)
+ if isinstance(existing, list):
+ for rec in existing:
+ if isinstance(rec, dict) and "patchID" in rec:
+ merged.append(rec)
+ seen[_dedupe_key(rec)] = rec
+ except (OSError, ValueError, KeyError):
+ merged, seen = [], {}
+
+ added = 0
+ for rec in _capture.records:
+ key = _dedupe_key(rec)
+ prior = seen.get(key)
+ if prior is not None:
+ if (prior.get("orig_sha256") != rec["orig_sha256"]
+ or prior.get("patch_sha256") != rec["patch_sha256"]):
+ _warn("conflicting record for one site",
+ patch_id=rec["patchID"], component=rec["component"],
+ file_offset=f"0x{rec['fileOffset']:X}",
+ kept=prior.get("patch_sha256", "")[:16],
+ discarded=rec["patch_sha256"][:16],
+ note="one capture root describes one (variant x iOS "
+ "build); capture the other build into its own root")
+ continue
+ seen[key] = rec
+ merged.append(rec)
+ added += 1
+
+ merged.sort(key=lambda r: (r["component"], r["fileOffset"], r["patchID"]))
+ tmp = path + ".tmp"
+ with open(tmp, "w") as f:
+ json.dump(merged, f, indent=2)
+ f.write("\n")
+ os.replace(tmp, path)
+ # The on-disk view just changed, so the cached index for this group is stale.
+ _capture.group_index.pop(_capture.group, None)
+
+ with open(os.path.join(_capture.reference_dir, "_capture_log.jsonl"), "a") as f:
+ f.write(json.dumps({
+ "group": _capture.group,
+ "recorded": len(_capture.records),
+ "added": added,
+ "total": len(merged),
+ # `capture_root` rather than trusting `argv` to show how capture was
+ # turned on: `cfw.py` strips `--emit-records` out of `sys.argv[:]`
+ # before dispatch, so its subcommands log an argv with no flag in it,
+ # while `cfw_patch_build_version.py`, `cfw_patch_post_restore_dt.py`
+ # and `campo_mach_lookup_exceptions.py` strip a *local* argv and log
+ # the flag. The env var shows in neither. This field always answers it.
+ "capture_root": _capture.root,
+ "env_var_set": bool(os.environ.get(ENV_VAR)),
+ "argv": sys.argv,
+ "cwd": os.getcwd(),
+ "utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+ }) + "\n")
+
+ _flush_warnings()
+
+ _capture.records = []
+ _flush_dsc_pages()
diff --git a/sources/FirmwarePatcher/ARM64/ARM64Encoder.swift b/sources/FirmwarePatcher/ARM64/ARM64Encoder.swift
index ef1e68d3..f296934c 100644
--- a/sources/FirmwarePatcher/ARM64/ARM64Encoder.swift
+++ b/sources/FirmwarePatcher/ARM64/ARM64Encoder.swift
@@ -1,10 +1,51 @@
-// ARM64Encoder.swift — PC-relative instruction encoding for ARM64.
+// ARM64Encoder.swift — instruction encoding for ARM64.
+//
+// Replaces keystone-engine's `asm()` / `asm_at()` for the CFW patchers. The set
+// of encoders here is closed deliberately: it is exactly the instruction set the
+// 19 Python patchers assemble, recovered by grepping every `asm(...)` call site.
+// This is not a general assembler and must not grow into one — add an encoder
+// when a patcher needs the instruction, not before.
+//
+// Every field layout below is written out from the ARM64 ISA encoding rather
+// than copied from a keystone dump, and every one is asserted against keystone
+// in ARM64EncoderTests.swift.
//
-// Replaces keystone-engine _asm_at() for branch/ADRP/ADD encoding.
// Each encoder produces a 4-byte little-endian Data value.
import Foundation
+// MARK: - Condition Codes
+
+/// ARM64 condition codes, `cond` in bits [15:12] of the conditional-select family.
+///
+/// Only the 14 invertible conditions exist here. `AL` (0b1110) and `NV` (0b1111)
+/// are each other's inverse and are rejected by CSET, which is the only consumer.
+public enum ARM64Condition: UInt32, Sendable, CaseIterable {
+ case eq = 0b0000 // equal — Z == 1
+ case ne = 0b0001 // not equal
+ case hs = 0b0010 // unsigned >= — C == 1
+ case lo = 0b0011 // unsigned <
+ case mi = 0b0100 // negative — N == 1
+ case pl = 0b0101 // positive or zero
+ case vs = 0b0110 // overflow — V == 1
+ case vc = 0b0111 // no overflow
+ case hi = 0b1000 // unsigned >
+ case ls = 0b1001 // unsigned <=
+ case ge = 0b1010 // signed >=
+ case lt = 0b1011 // signed <
+ case gt = 0b1100 // signed >
+ case le = 0b1101 // signed <=
+
+ /// The condition true exactly when this one is false.
+ ///
+ /// AArch64 orders the condition codes in complementary pairs, so inverting
+ /// bit 0 inverts the test. This is why CSET can be a CSINC alias at all.
+ public var inverted: ARM64Condition {
+ // Safe: flipping bit 0 stays inside 0b0000...0b1101 for every case here.
+ ARM64Condition(rawValue: rawValue ^ 1)!
+ }
+}
+
public enum ARM64Encoder {
// MARK: - Branch Encoding
@@ -119,6 +160,54 @@ public enum ARM64Encoder {
return ARM64.encodeU32(insn)
}
+ // MARK: - Conditional Set
+
+ /// Encode `CSET Wd, <cond>` — set Wd to 1 when `condition` holds, else 0.
+ ///
+ /// CSET is an alias of `CSINC Wd, WZR, WZR, invert(cond)`: the increment path
+ /// (WZR + 1 = 1) runs when the *encoded* condition is false, so the encoded
+ /// condition is the inverse of the one written in the assembly.
+ ///
+ /// CSINC format: `[31] = 0 (sf, 32-bit)`, `[30] = 0 (op)`, `[29] = 0 (S)`,
+ /// `[28:21] = 11010100`, `[20:16] = Rm`, `[15:12] = cond`,
+ /// `[11:10] = 01 (o2:o1, selects CSINC)`, `[9:5] = Rn`, `[4:0] = Rd`
+ public static func encodeCsetW(rd: UInt32, condition: ARM64Condition) -> Data? {
+ guard rd < 32 else { return nil }
+ var insn: UInt32 = 0b0_0_0_1101_0100 << 21
+ insn |= 31 << 16 // Rm = WZR
+ insn |= condition.inverted.rawValue << 12
+ insn |= 0b01 << 10 // CSINC
+ insn |= 31 << 5 // Rn = WZR
+ insn |= rd
+ return ARM64.encodeU32(insn)
+ }
+
+ // MARK: - Loads
+
+ /// Encode `LDR Wt, [Xn, #offset]` — 32-bit load, unsigned scaled offset.
+ ///
+ /// Format: `[31:30] = 10 (size = 32-bit)`, `[29:27] = 111`, `[26] = 0 (V, non-SIMD)`,
+ /// `[25:24] = 01 (unsigned offset)`, `[23:22] = 01 (opc = load)`,
+ /// `[21:10] = imm12`, `[9:5] = Rn`, `[4:0] = Rt`
+ ///
+ /// `imm12` is scaled by the access size, so `offset` must be a multiple of 4
+ /// in `0...16380`. `rn == 31` means SP, which is what the base encoding says.
+ public static func encodeLdrWUnsignedOffset(rt: UInt32, rn: UInt32, offset: UInt32) -> Data? {
+ guard rt < 32, rn < 32 else { return nil }
+ guard offset % 4 == 0 else { return nil }
+ let imm12 = offset / 4
+ guard imm12 < 4096 else { return nil }
+
+ var insn: UInt32 = 0b10 << 30 // size
+ insn |= 0b111 << 27
+ insn |= 0b01 << 24
+ insn |= 0b01 << 22 // opc = LDR
+ insn |= imm12 << 10
+ insn |= rn << 5
+ insn |= rt
+ return ARM64.encodeU32(insn)
+ }
+
// MARK: - Decode Helpers
/// Decode a B or BL target address from an instruction at `pc`.
diff --git a/sources/FirmwarePatcher/CFW/CFWBuildVersion.swift b/sources/FirmwarePatcher/CFW/CFWBuildVersion.swift
new file mode 100644
index 00000000..66de6807
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/CFWBuildVersion.swift
@@ -0,0 +1,132 @@
+// CFWBuildVersion.swift — rewrite ProductBuildVersion in SystemVersion.plist.
+//
+// Swift port of scripts/patchers/cfw_patch_build_version.py (EXP-JB-7).
+//
+// iOS displays the build identifier (e.g. "23B85") in Settings → General →
+// About → "Build Version", and most userland frameworks (libMobileGestalt,
+// CoreFoundation's `_CFCopyServerVersionDictionary`, App Store telemetry)
+// read it from `/System/Library/CoreServices/SystemVersion.plist` — the
+// `ProductBuildVersion` key. A copy of the same plist lives at
+// `/private/preboot/Cryptexes/OS/System/Library/CoreServices/SystemVersion.plist`
+// for Cryptex-side OS-version queries, and the install step rewrites both.
+//
+// The change does NOT affect `sysctl kern.osversion` (a kernel global
+// populated at boot from boot args), `ProductVersion` (the marketing
+// version, deliberately left alone), or any DSC constant.
+//
+// The step is opt-in: `cfw_install_exp.sh` runs it only when SPOOF_BUILD is
+// set and non-empty. That gate lives at the call site, not here — this type
+// is told the target build and rewrites it.
+
+import Foundation
+
+/// Rewrites `ProductBuildVersion` in a `SystemVersion.plist`, preserving the
+/// file's original plist format (XML in, XML out; binary in, binary out).
+public enum CFWBuildVersion {
+ /// The single key this patcher touches.
+ public static let key = "ProductBuildVersion"
+
+ /// What a patch attempt did.
+ public enum Outcome: Sendable, Equatable {
+ /// The plist already held the target build identifier.
+ case alreadyTarget(String)
+ /// The value would change but `dryRun` suppressed the write.
+ case dryRun(from: String, to: String)
+ /// The file was rewritten.
+ case rewritten(from: String, to: String)
+
+ /// True only when bytes landed on disk — mirrors the Python's
+ /// `patch_plist()` return value.
+ public var didWrite: Bool {
+ if case .rewritten = self { return true }
+ return false
+ }
+ }
+
+ // MARK: - Patching
+
+ /// Rewrite `ProductBuildVersion` at `url` to `target`.
+ ///
+ /// - Throws: ``PatcherError/invalidFormat(_:)`` when the file is not a
+ /// plist, its root is not a dictionary, or the key is missing or not a
+ /// string. Every one of those is a reason to stop the install rather
+ /// than write a half-understood file back to a mounted guest volume.
+ @discardableResult
+ public static func patch(
+ at url: URL,
+ to target: String,
+ dryRun: Bool = false,
+ verbose: Bool = true
+ ) throws -> Outcome {
+ let data = try readFile(at: url)
+ let format = detectFormat(data)
+
+ guard let parsed = try? PropertyListSerialization.propertyList(
+ from: data,
+ options: [],
+ format: nil
+ ) else {
+ throw PatcherError.invalidFormat("cannot parse as plist: \(url.path)")
+ }
+
+ guard var plist = parsed as? [String: Any] else {
+ throw PatcherError.invalidFormat(
+ "top-level plist is \(type(of: parsed)), expected dict: \(url.path)"
+ )
+ }
+
+ guard let current = plist[key] else {
+ throw PatcherError.invalidFormat("no '\(key)' key present: \(url.path)")
+ }
+ guard let currentString = current as? String else {
+ throw PatcherError.invalidFormat(
+ "'\(key)' is \(type(of: current)), expected str: \(url.path)"
+ )
+ }
+
+ if currentString == target {
+ if verbose { print(" [.] \(url.path): \(key) already = '\(target)'") }
+ return .alreadyTarget(target)
+ }
+
+ if verbose { print(" [+] \(url.path): \(key) '\(currentString)' -> '\(target)'") }
+ plist[key] = target
+
+ if dryRun {
+ if verbose { print(" [.] dry-run — not writing back") }
+ return .dryRun(from: currentString, to: target)
+ }
+
+ let output = try PropertyListSerialization.data(
+ fromPropertyList: plist,
+ format: format,
+ options: 0
+ )
+ try output.write(to: url)
+ return .rewritten(from: currentString, to: target)
+ }
+
+ // MARK: - Format detection
+
+ /// XML plists start with `<?xml` or `<plist`; binary plists start with
+ /// `bplist00`. Sniffing the first non-whitespace byte is what the Python
+ /// does, and it is enough: `PropertyListSerialization` will not tell us
+ /// the input format without also handing back a parsed object, and an
+ /// open-coded check keeps the two implementations provably identical.
+ static func detectFormat(_ data: Data) -> PropertyListSerialization.PropertyListFormat {
+ // bytes.lstrip() with no argument strips exactly these.
+ let asciiWhitespace: Set<UInt8> = [0x20, 0x09, 0x0A, 0x0D, 0x0B, 0x0C]
+ guard let first = data.first(where: { !asciiWhitespace.contains($0) }) else {
+ return .binary
+ }
+ return first == UInt8(ascii: "<") ? .xml : .binary
+ }
+
+ private static func readFile(at url: URL) throws -> Data {
+ do {
+ return try Data(contentsOf: url)
+ } catch {
+ throw PatcherError.fileNotFound(url.path)
+ }
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/CFWDaemons.swift b/sources/FirmwarePatcher/CFW/CFWDaemons.swift
new file mode 100644
index 00000000..0aba0cf3
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/CFWDaemons.swift
@@ -0,0 +1,112 @@
+// CFWDaemons.swift — Cryptex path lookup and the plist I/O the CFW daemon rewrites share.
+//
+// Translated from: scripts/patchers/cfw_daemons.py (cryptex-paths, inject-daemons,
+// patch-dropbear-plist). None of these three touch code or signatures — they are
+// plist reads and rewrites, which is why they come over ahead of the disassembly
+// patchers.
+
+import Foundation
+
+// MARK: - CFWDaemons
+
+/// The three non-disassembly CFW commands: Cryptex path lookup, LaunchDaemon
+/// injection into `launchd.plist`, and the dropbear `ProgramArguments` rewrite.
+public enum CFWDaemons {
+ // MARK: - Errors
+
+ public enum DaemonError: Error, CustomStringConvertible {
+ case fileNotFound(String)
+ case invalidPlist(String)
+ case cryptexPathsNotFound(String)
+
+ public var description: String {
+ switch self {
+ case let .fileNotFound(path):
+ "File not found: \(path)"
+ case let .invalidPlist(path):
+ "Invalid plist: \(path)"
+ case let .cryptexPathsNotFound(path):
+ "Cryptex1,SystemOS/AppOS paths not found in any BuildIdentity: \(path)"
+ }
+ }
+ }
+
+ // MARK: - Cryptex paths
+
+ /// The two Cryptex DMG paths a BuildManifest names, relative to the IPSW root.
+ public struct CryptexPaths: Sendable, Equatable {
+ public let systemOS: String
+ public let appOS: String
+
+ public init(systemOS: String, appOS: String) {
+ self.systemOS = systemOS
+ self.appOS = appOS
+ }
+ }
+
+ /// Extract the Cryptex DMG paths from a BuildManifest.
+ ///
+ /// Every BuildIdentity is searched, not just the first: vResearch IPSWs carry
+ /// their Cryptex entries in a later identity, and the last identity in a real
+ /// manifest has none at all. The first identity carrying *both* wins.
+ public static func cryptexPaths(buildManifest url: URL) throws -> CryptexPaths {
+ let manifest = try loadPlist(url)
+ let identities = manifest["BuildIdentities"] as? [Any] ?? []
+
+ for identity in identities {
+ let manifestSection = (identity as? PlistDict)?["Manifest"] as? PlistDict ?? [:]
+ let systemOS = componentPath(manifestSection, "Cryptex1,SystemOS")
+ let appOS = componentPath(manifestSection, "Cryptex1,AppOS")
+ if !systemOS.isEmpty, !appOS.isEmpty {
+ return CryptexPaths(systemOS: systemOS, appOS: appOS)
+ }
+ }
+
+ throw DaemonError.cryptexPathsNotFound(url.path)
+ }
+
+ /// `Manifest -> <component> -> Info -> Path`, or "" when any link is missing.
+ private static func componentPath(_ manifest: PlistDict, _ component: String) -> String {
+ let info = (manifest[component] as? PlistDict)?["Info"] as? PlistDict
+ return info?["Path"] as? String ?? ""
+ }
+
+ // MARK: - Plist I/O
+
+ /// Read a plist of any format.
+ ///
+ /// The Python ran `plutil -convert xml1` first, which was only ever needed
+ /// because `plistlib` cannot read old-style ASCII plists. CoreFoundation
+ /// reads all three formats, so the conversion step drops out.
+ static func loadPlist(_ url: URL) throws -> PlistDict {
+ guard FileManager.default.fileExists(atPath: url.path) else {
+ throw DaemonError.fileNotFound(url.path)
+ }
+ let data = try Data(contentsOf: url)
+ guard let dict = try PropertyListSerialization.propertyList(
+ from: data,
+ options: [],
+ format: nil
+ ) as? PlistDict else {
+ throw DaemonError.invalidPlist(url.path)
+ }
+ return dict
+ }
+
+ /// Write a plist as XML, matching what `plistlib.dump` produced.
+ ///
+ /// XML rather than binary because that is what the Python wrote, and the
+ /// installer's `/System/Library/xpc/launchd.plist` has been an XML file ever
+ /// since. Note that CoreFoundation orders dictionary keys alphabetically
+ /// while `plistlib.dump(sort_keys=False)` kept the order it read; a plist
+ /// dictionary is unordered to every consumer of these files, and the
+ /// migration plan's equivalence bar for plists is the key *set*.
+ static func savePlist(_ plist: PlistDict, to url: URL) throws {
+ let data = try PropertyListSerialization.data(
+ fromPropertyList: plist,
+ format: .xml,
+ options: 0
+ )
+ try data.write(to: url)
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/CFWDaemonsDropbear.swift b/sources/FirmwarePatcher/CFW/CFWDaemonsDropbear.swift
new file mode 100644
index 00000000..56c48c15
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/CFWDaemonsDropbear.swift
@@ -0,0 +1,69 @@
+// CFWDaemonsDropbear.swift — dropbear's ProgramArguments rewrite.
+//
+// Translated from: scripts/patchers/cfw_daemons.py (patch_dropbear_daemon,
+// patch_dropbear_plist). Covered by tests/FirmwarePatcherTests/CFWDaemonsTests.swift,
+// which carries both cases of the retired tests/test_dropbear_plist.py.
+
+import Foundation
+
+extension CFWDaemons {
+ // MARK: - Host keys
+
+ /// The host keys dropbear is pointed at instead of generating its own.
+ ///
+ /// `/var` is on the writable Data volume; `/etc/dropbear`, where `-R` would
+ /// put them, is on a read-only root during a normal VM boot. `cfw_install`
+ /// seeds these two files.
+ public static let dropbearKeyArguments: [String] = [
+ "-r",
+ "/var/dropbear/dropbear_rsa_host_key",
+ "-r",
+ "/var/dropbear/dropbear_ecdsa_host_key",
+ ]
+
+ // MARK: - Rewrite
+
+ /// Strip dropbear's key-generation flags and append the seeded host keys.
+ ///
+ /// Drops `-R` (generate defaults under the read-only `/etc/dropbear`) and
+ /// every `-r <path>` pair, so a stale explicit key path cannot survive, then
+ /// appends `dropbearKeyArguments`. An empty or missing argument list is left
+ /// alone: there is nothing to point at a key.
+ ///
+ /// Elements are compared as strings but carried through as read, so a plist
+ /// holding a non-string in `ProgramArguments` round-trips unchanged rather
+ /// than failing.
+ public static func patchedDropbearArguments(_ arguments: [Any]) -> [Any] {
+ guard !arguments.isEmpty else { return arguments }
+
+ var cleaned: [Any] = []
+ var index = 0
+ while index < arguments.count {
+ switch arguments[index] as? String {
+ case "-R":
+ index += 1
+ case "-r":
+ index += 2
+ default:
+ cleaned.append(arguments[index])
+ index += 1
+ }
+ }
+ return cleaned + dropbearKeyArguments
+ }
+
+ /// Apply `patchedDropbearArguments` to a loaded daemon plist in place.
+ public static func patchDropbearDaemon(_ daemon: inout PlistDict) {
+ guard let arguments = daemon["ProgramArguments"] as? [Any], !arguments.isEmpty else {
+ return
+ }
+ daemon["ProgramArguments"] = patchedDropbearArguments(arguments)
+ }
+
+ /// Rewrite a dropbear daemon plist on disk. Implements `cfw.py patch-dropbear-plist`.
+ public static func patchDropbearPlist(at url: URL) throws {
+ var daemon = try loadPlist(url)
+ patchDropbearDaemon(&daemon)
+ try savePlist(daemon, to: url)
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/CFWDaemonsLaunchd.swift b/sources/FirmwarePatcher/CFW/CFWDaemonsLaunchd.swift
new file mode 100644
index 00000000..2156de91
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/CFWDaemonsLaunchd.swift
@@ -0,0 +1,150 @@
+// CFWDaemonsLaunchd.swift — LaunchDaemon injection into /System/Library/xpc/launchd.plist.
+//
+// Translated from: scripts/patchers/cfw_daemons.py (inject_daemons), and from the
+// inline plistlib snippets at cfw_install_jb.sh:460-469 and cfw_install_exp.sh:702-711.
+//
+// Those three were the same merge written twice, once as a command taking a
+// directory of daemon plists and once inline taking a single file. They converge
+// here: `inject` is the merge, and the two loaders below are the only difference
+// between the call sites.
+
+import Foundation
+
+extension CFWDaemons {
+ // MARK: - Daemon
+
+ /// One LaunchDaemon to merge, already loaded and already rewritten.
+ public struct Daemon {
+ /// Label as installed, without `.plist` — e.g. `dropbear`, `com.vphone.jb-setup`.
+ public let name: String
+ public let contents: PlistDict
+
+ public init(name: String, contents: PlistDict) {
+ self.name = name
+ self.contents = contents
+ }
+
+ /// The `LaunchDaemons` key launchd looks this daemon up under.
+ public var launchdKey: String {
+ "/System/Library/LaunchDaemons/\(name).plist"
+ }
+ }
+
+ /// The daemons `inject-daemons` looks for in a directory, in this order.
+ ///
+ /// A fixed list rather than a directory listing, so what gets injected does
+ /// not depend on what else a variant happens to leave in the staging
+ /// directory, and so the order stays the order the log lines come out in.
+ public static let defaultDaemonNames: [String] = [
+ "bash",
+ "dropbear",
+ "trollvnc",
+ "vphoned",
+ "rpcserver_ios",
+ ]
+
+ // MARK: - Loading
+
+ /// One entry of a staging-directory scan.
+ ///
+ /// A daemon that is not there is not an error — a variant that does not ship
+ /// `rpcserver_ios` still installs — so absence is a result, not a throw. The
+ /// scan is returned in order because the caller logs it line by line.
+ public enum StagedDaemon {
+ case present(Daemon)
+ case absent(source: String)
+ }
+
+ /// Load one daemon plist by the name it will be installed under.
+ ///
+ /// The dropbear rewrite lives here rather than in the directory loader so it
+ /// holds however the daemon reaches the merge.
+ public static func loadDaemon(name: String, from url: URL) throws -> Daemon {
+ var contents = try loadPlist(url)
+ if name == "dropbear" {
+ patchDropbearDaemon(&contents)
+ }
+ return Daemon(name: name, contents: contents)
+ }
+
+ /// Scan a staging directory for the named daemons, in the order given.
+ public static func loadDaemons(
+ inDirectory directory: URL,
+ names: [String] = defaultDaemonNames
+ ) throws -> [StagedDaemon] {
+ try names.map { name in
+ let source = directory.appendingPathComponent("\(name).plist")
+ guard FileManager.default.fileExists(atPath: source.path) else {
+ return .absent(source: source.path)
+ }
+ return .present(try loadDaemon(name: name, from: source))
+ }
+ }
+
+ // MARK: - Injection
+
+ /// Merge daemons into a `launchd.plist`'s `LaunchDaemons` dictionary, in place.
+ ///
+ /// This is the single merge behind `cfw inject-daemons`, the jb-setup
+ /// injection in `cfw_install_jb.sh` and the one in `cfw_install_exp.sh`.
+ /// An entry already present is replaced, which is what makes re-running an
+ /// install over an already-patched volume safe.
+ ///
+ /// - Returns: the names injected, in the order given.
+ @discardableResult
+ public static func inject(_ daemons: [Daemon], into launchdPlist: URL) throws -> [String] {
+ var target = try loadPlist(launchdPlist)
+ var launchDaemons = target["LaunchDaemons"] as? PlistDict ?? [:]
+
+ for daemon in daemons {
+ launchDaemons[daemon.launchdKey] = daemon.contents
+ }
+
+ target["LaunchDaemons"] = launchDaemons
+ try savePlist(target, to: launchdPlist)
+ return daemons.map(\.name)
+ }
+
+ /// `cfw.py inject-daemons <launchd.plist> <daemon_dir>`, whole.
+ ///
+ /// - Returns: the scan, in scan order, so the caller can log one line each.
+ @discardableResult
+ public static func injectDaemons(
+ into launchdPlist: URL,
+ fromDirectory directory: URL,
+ names: [String] = defaultDaemonNames
+ ) throws -> [StagedDaemon] {
+ let staged = try loadDaemons(inDirectory: directory, names: names)
+ try inject(staged.present, into: launchdPlist)
+ return staged
+ }
+
+ /// The single-file form the two installer scripts inline.
+ ///
+ /// `name` is the installed label, which is not the source filename: the jb
+ /// setup daemon ships as `vphone_jb_setup.plist` and installs as
+ /// `com.vphone.jb-setup.plist`.
+ public static func injectDaemon(
+ into launchdPlist: URL,
+ name: String,
+ from source: URL
+ ) throws {
+ try inject([loadDaemon(name: name, from: source)], into: launchdPlist)
+ }
+}
+
+// MARK: - Scan convenience
+
+public extension [CFWDaemons.StagedDaemon] {
+ var present: [CFWDaemons.Daemon] {
+ compactMap { if case let .present(daemon) = $0 { daemon } else { nil } }
+ }
+
+ var injectedNames: [String] {
+ present.map(\.name)
+ }
+
+ var missingSources: [String] {
+ compactMap { if case let .absent(source) = $0 { source } else { nil } }
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/CFWInjectDylib.swift b/sources/FirmwarePatcher/CFW/CFWInjectDylib.swift
new file mode 100644
index 00000000..9ba80c1d
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/CFWInjectDylib.swift
@@ -0,0 +1,524 @@
+// CFWInjectDylib.swift — LC_LOAD_DYLIB / LC_LOAD_WEAK_DYLIB insertion.
+//
+// Replaces the `insert_dylib` binary built from `scripts/repos/insert_dylib`,
+// whose only caller is the launchdhook injection in `cfw_install_jb.sh` and
+// `cfw_install_exp.sh`:
+//
+// cfw.py inject-dylib "$TEMP_DIR/launchd" "/b"
+// -> insert_dylib --weak --inplace --all-yes /b <launchd>
+//
+// This is a deliberate behaviour-for-behaviour port, because byte equality with
+// the C tool is the only independent check available for it. Two things differ
+// on purpose, both in the safe direction, both marked below:
+//
+// 1. `insert_dylib --all-yes` answers "y" to "It doesn't seem like there is
+// enough empty space. Continue anyway?" and then writes the load command
+// over whatever follows the load-command region — normally the first bytes
+// of __text. That silently corrupts the binary. We throw instead, unless
+// the caller opts in.
+// 2. `insert_dylib` supports big-endian and 32-bit Mach-Os. Nothing in this
+// pipeline is either, so they are rejected rather than half-supported.
+//
+// Inserting the command does not move anything: it is written into the zero
+// padding between the end of the load commands and the first section, and only
+// `ncmds` / `sizeofcmds` in the header change. What *does* move is the code
+// signature — `.strip` removes it and truncates the slice, which is why the
+// policy is part of this API rather than a separate pass.
+
+import Foundation
+
+// MARK: - Byte Access
+
+private extension Data {
+ func loadLEValue<T: FixedWidthInteger>(_: T.Type, at offset: Int) -> T {
+ var value: T = .zero
+ _ = Swift.withUnsafeMutableBytes(of: &value) { destination in
+ copyBytes(to: destination, from: offset ..< offset + MemoryLayout<T>.size)
+ }
+ return T(littleEndian: value)
+ }
+
+ func loadBEValue<T: FixedWidthInteger>(_: T.Type, at offset: Int) -> T {
+ var value: T = .zero
+ _ = Swift.withUnsafeMutableBytes(of: &value) { destination in
+ copyBytes(to: destination, from: offset ..< offset + MemoryLayout<T>.size)
+ }
+ return T(bigEndian: value)
+ }
+
+ mutating func storeLE(_ value: some FixedWidthInteger, at offset: Int) {
+ Swift.withUnsafeBytes(of: value.littleEndian) { source in
+ replaceSubrange(offset ..< offset + source.count, with: source)
+ }
+ }
+
+ mutating func storeBE(_ value: some FixedWidthInteger, at offset: Int) {
+ Swift.withUnsafeBytes(of: value.bigEndian) { source in
+ replaceSubrange(offset ..< offset + source.count, with: source)
+ }
+ }
+
+ mutating func zeroBytes(at offset: Int, count: Int) {
+ guard count > 0 else { return }
+ replaceSubrange(offset ..< offset + count, with: Data(repeating: 0, count: count))
+ }
+
+ func holds(_ offset: Int, _ length: Int) -> Bool {
+ offset >= 0 && length >= 0 && offset + length <= count
+ }
+}
+
+// MARK: - Result
+
+/// What one injected load command ended up as, per architecture slice.
+public struct CFWDylibInjection: Sendable {
+ /// Slice start in the file. 0 for a thin binary.
+ public let sliceOffset: Int
+ /// Slice size after injection (smaller than before when the signature was stripped).
+ public let sliceSize: Int
+ public let cpuType: Int32
+ public let cpuSubtype: Int32
+ /// Absolute file offset the new load command was written to.
+ public let loadCommandOffset: Int
+ public let loadCommandSize: Int
+ public let isWeak: Bool
+ /// True when LC_CODE_SIGNATURE and its blob were removed.
+ public let removedCodeSignature: Bool
+ /// Slots re-hashed under `.keepAndReattest`. Empty under `.strip`.
+ public let rehashedSlots: [CFWSlotRehash]
+}
+
+// MARK: - Injector
+
+public enum CFWInjectDylib {
+ /// What to do about an existing LC_CODE_SIGNATURE.
+ public enum CodeSignaturePolicy: Sendable {
+ /// Drop the load command, the signature blob and the bytes it occupied,
+ /// exactly as `insert_dylib` does by default. The CFW pipeline re-signs
+ /// with ldid on the next line, so the binary is never left unsigned.
+ case strip
+ /// Keep the signature and recompute the slot hashes of the pages the
+ /// injection touched, so the binary still verifies with no external
+ /// signer. Only valid when the signature covers the header — i.e. every
+ /// real Mach-O.
+ case keepAndReattest
+ }
+
+ // MARK: Constants
+
+ static let machMagic64: UInt32 = 0xFEED_FACF
+ static let machMagic32: UInt32 = 0xFEED_FACE
+ static let machCigam64: UInt32 = 0xCFFA_EDFE
+ static let fatMagic: UInt32 = 0xCAFE_BABE
+ static let fatMagic64: UInt32 = 0xCAFE_BABF
+
+ static let lcSegment64: UInt32 = 0x19
+ static let lcSymtab: UInt32 = 0x02
+ static let lcCodeSignature: UInt32 = 0x1D
+ static let lcLoadDylib: UInt32 = 0x0C
+ static let lcLoadWeakDylib: UInt32 = 0x8000_0018
+
+ /// sizeof(struct dylib_command).
+ static let dylibCommandSize = 24
+ /// A 4-byte pad is enough for the loader but codesign rejects it, which is
+ /// the comment `insert_dylib` carries over the same constant.
+ static let pathPadding = 8
+ static let machHeader64Size = 32
+
+ // MARK: Entry Points
+
+ /// Insert a dylib load command into every architecture slice of `url`, in place.
+ @discardableResult
+ public static func inject(
+ dylibPath: String,
+ into url: URL,
+ weak: Bool = true,
+ policy: CodeSignaturePolicy = .strip,
+ allowNonEmptyPadding: Bool = false
+ ) throws -> [CFWDylibInjection] {
+ guard FileManager.default.fileExists(atPath: url.path) else {
+ throw PatcherError.fileNotFound(url.path)
+ }
+ var data = try Data(contentsOf: url)
+ let injections = try inject(
+ dylibPath: dylibPath,
+ into: &data,
+ weak: weak,
+ policy: policy,
+ allowNonEmptyPadding: allowNonEmptyPadding
+ )
+ try data.write(to: url)
+ return injections
+ }
+
+ /// Buffer form of `inject(dylibPath:into:weak:policy:)`.
+ @discardableResult
+ public static func inject(
+ dylibPath: String,
+ into data: inout Data,
+ weak: Bool = true,
+ policy: CodeSignaturePolicy = .strip,
+ allowNonEmptyPadding: Bool = false
+ ) throws -> [CFWDylibInjection] {
+ if data.startIndex != 0 { data = Data(data) }
+ guard data.holds(0, 4) else { throw PatcherError.invalidFormat("file is too small to be a Mach-O") }
+
+ let options = Options(
+ dylibPath: dylibPath,
+ weak: weak,
+ policy: policy,
+ allowNonEmptyPadding: allowNonEmptyPadding
+ )
+ switch data.loadBEValue(UInt32.self, at: 0) {
+ case fatMagic:
+ return try injectFat(into: &data, options: options)
+ case fatMagic64:
+ // `insert_dylib` refuses these too; no arm64e IPSW ships one.
+ throw PatcherError.invalidFormat("64-bit fat binaries (FAT_MAGIC_64) are not supported")
+ default:
+ var sliceSize = data.count
+ let injection = try injectSlice(
+ into: &data,
+ headerOffset: 0,
+ sliceSize: &sliceSize,
+ options: options
+ )
+ if sliceSize < data.count { data = data.prefix(sliceSize) }
+ return [injection]
+ }
+ }
+
+ struct Options {
+ let dylibPath: String
+ let weak: Bool
+ let policy: CodeSignaturePolicy
+ let allowNonEmptyPadding: Bool
+ }
+
+ // MARK: Universal Binaries
+
+ /// Re-pack a fat binary the way `insert_dylib` does: walk the slices in
+ /// order, slide each one down to its alignment boundary behind the previous
+ /// slice, inject, and truncate. Slices move because `.strip` makes earlier
+ /// ones shorter.
+ static func injectFat(into data: inout Data, options: Options) throws -> [CFWDylibInjection] {
+ let archCount = Int(data.loadBEValue(UInt32.self, at: 4))
+ guard archCount > 0, data.holds(8, archCount * 20) else {
+ throw PatcherError.invalidFormat("fat header declares \(archCount) architectures it does not have")
+ }
+
+ var injections: [CFWDylibInjection] = []
+ var fileSize = data.count
+ var cursor = Int(data.loadBEValue(UInt32.self, at: 8 + 8))
+
+ for index in 0 ..< archCount {
+ let entry = 8 + index * 20
+ let originalOffset = Int(data.loadBEValue(UInt32.self, at: entry + 8))
+ let originalSize = Int(data.loadBEValue(UInt32.self, at: entry + 12))
+ let align = Int(data.loadBEValue(UInt32.self, at: entry + 16))
+ guard align < 32, data.holds(originalOffset, originalSize) else {
+ throw PatcherError.invalidFormat("fat slice \(index) is out of bounds")
+ }
+
+ cursor = roundUp(cursor, to: 1 << align)
+ if cursor != originalOffset {
+ guard data.holds(cursor, originalSize) else {
+ throw PatcherError.invalidFormat("fat slice \(index) would be relocated past the end of the file")
+ }
+ let slice = Data(data[originalOffset ..< originalOffset + originalSize])
+ data.replaceSubrange(cursor ..< cursor + originalSize, with: slice)
+ // Zero whatever the move left behind, so the gap is not stale code.
+ data.zeroBytes(
+ at: Swift.min(cursor, originalOffset) + originalSize,
+ count: abs(cursor - originalOffset)
+ )
+ data.storeBE(UInt32(cursor), at: entry + 8)
+ }
+
+ var sliceSize = originalSize
+ injections.append(try injectSlice(
+ into: &data,
+ headerOffset: cursor,
+ sliceSize: &sliceSize,
+ options: options
+ ))
+
+ if sliceSize < originalSize, index < archCount - 1 {
+ data.zeroBytes(at: cursor + sliceSize, count: originalSize - sliceSize)
+ }
+ fileSize = cursor + sliceSize
+ cursor += sliceSize
+ data.storeBE(UInt32(sliceSize), at: entry + 12)
+ }
+
+ if fileSize < data.count { data = data.prefix(fileSize) }
+ return injections
+ }
+
+ // MARK: One Slice
+
+ static func injectSlice(
+ into data: inout Data,
+ headerOffset: Int,
+ sliceSize: inout Int,
+ options: Options
+ ) throws -> CFWDylibInjection {
+ guard data.holds(headerOffset, machHeader64Size) else {
+ throw PatcherError.invalidFormat("Mach-O header at 0x\(String(headerOffset, radix: 16)) is truncated")
+ }
+ let magic = data.loadLEValue(UInt32.self, at: headerOffset)
+ guard magic == machMagic64 else {
+ let hint = magic == machMagic32
+ ? "32-bit Mach-O"
+ : (magic == machCigam64 ? "big-endian Mach-O" : "magic 0x\(String(magic, radix: 16))")
+ throw PatcherError.invalidFormat("unsupported slice: \(hint)")
+ }
+
+ let cpuType = Int32(bitPattern: data.loadLEValue(UInt32.self, at: headerOffset + 4))
+ let cpuSubtype = Int32(bitPattern: data.loadLEValue(UInt32.self, at: headerOffset + 8))
+ let commandsOffset = headerOffset + machHeader64Size
+ var ncmds = data.loadLEValue(UInt32.self, at: headerOffset + 16)
+ var sizeofcmds = Int(data.loadLEValue(UInt32.self, at: headerOffset + 20))
+
+ let layout = try scanLoadCommands(
+ in: data,
+ headerOffset: headerOffset,
+ commandsOffset: commandsOffset,
+ ncmds: Int(ncmds)
+ )
+
+ var removedCodeSignature = false
+ if case .strip = options.policy, let signature = layout.codeSignature, layout.codeSignatureIsLast {
+ try stripCodeSignature(
+ from: &data,
+ headerOffset: headerOffset,
+ sliceSize: &sliceSize,
+ signature: signature,
+ layout: layout
+ )
+ ncmds -= 1
+ sizeofcmds -= signature.commandSize
+ removedCodeSignature = true
+ }
+
+ // The command is `dylib_command` followed by the NUL-padded path. The
+ // padding formula always leaves at least one NUL, matching insert_dylib.
+ let pathBytes = Array(options.dylibPath.utf8)
+ let paddedPathSize = (pathBytes.count & ~(pathPadding - 1)) + pathPadding
+ let commandSize = dylibCommandSize + paddedPathSize
+ let commandOffset = commandsOffset + sizeofcmds
+
+ guard data.holds(commandOffset, commandSize), commandOffset + commandSize <= headerOffset + sliceSize else {
+ throw PatcherError.invalidFormat(
+ "no room for a \(commandSize)-byte load command at 0x\(String(commandOffset, radix: 16))"
+ )
+ }
+ if !options.allowNonEmptyPadding, data[commandOffset ..< commandOffset + commandSize].contains(where: { $0 != 0 }) {
+ // insert_dylib --all-yes overwrites here. Refusing is the whole
+ // reason this is a Swift port: the bytes past the load commands are
+ // the first section, and clobbering them is silent.
+ throw PatcherError.invalidFormat(
+ "load-command padding at 0x\(String(commandOffset, radix: 16)) is not empty; "
+ + "inserting would overwrite \(commandSize) bytes of the first section"
+ )
+ }
+
+ var command = Data(capacity: commandSize)
+ command.append(contentsOf: [0, 0, 0, 0, 0, 0, 0, 0])
+ command.storeLE(options.weak ? lcLoadWeakDylib : lcLoadDylib, at: 0)
+ command.storeLE(UInt32(commandSize), at: 4)
+ command.append(contentsOf: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])
+ command.storeLE(UInt32(dylibCommandSize), at: 8) // dylib.name offset
+ command.storeLE(UInt32(0), at: 12) // timestamp
+ command.storeLE(UInt32(0), at: 16) // current_version
+ command.storeLE(UInt32(0), at: 20) // compatibility_version
+ command.append(contentsOf: pathBytes)
+ command.append(Data(repeating: 0, count: paddedPathSize - pathBytes.count))
+ data.replaceSubrange(commandOffset ..< commandOffset + commandSize, with: command)
+
+ ncmds += 1
+ sizeofcmds += commandSize
+ data.storeLE(ncmds, at: headerOffset + 16)
+ data.storeLE(UInt32(sizeofcmds), at: headerOffset + 20)
+
+ var rehashed: [CFWSlotRehash] = []
+ if case .keepAndReattest = options.policy {
+ rehashed = try reattestSlice(
+ in: &data,
+ headerOffset: headerOffset,
+ sliceSize: sliceSize,
+ touched: [
+ (headerOffset + 16) ..< (headerOffset + 24),
+ commandOffset ..< commandOffset + commandSize,
+ ]
+ )
+ }
+
+ return CFWDylibInjection(
+ sliceOffset: headerOffset,
+ sliceSize: sliceSize,
+ cpuType: cpuType,
+ cpuSubtype: cpuSubtype,
+ loadCommandOffset: commandOffset,
+ loadCommandSize: commandSize,
+ isWeak: options.weak,
+ removedCodeSignature: removedCodeSignature,
+ rehashedSlots: rehashed
+ )
+ }
+
+ // MARK: Load Command Scan
+
+ struct CodeSignatureCommand {
+ let commandOffset: Int
+ let commandSize: Int
+ /// Slice-relative, as stored.
+ let dataOffset: Int
+ let dataSize: Int
+ }
+
+ struct SliceLayout {
+ var codeSignature: CodeSignatureCommand?
+ var codeSignatureIsLast = false
+ /// Offset of the __LINKEDIT LC_SEGMENT_64 command, and its slice-relative extent.
+ var linkEditCommandOffset: Int?
+ var linkEditFileOffset = 0
+ var linkEditFileSize = 0
+ var symtabCommandOffset: Int?
+ }
+
+ static func scanLoadCommands(
+ in data: Data,
+ headerOffset: Int,
+ commandsOffset: Int,
+ ncmds: Int
+ ) throws -> SliceLayout {
+ var layout = SliceLayout()
+ var offset = commandsOffset
+ for index in 0 ..< ncmds {
+ guard data.holds(offset, 8) else {
+ throw PatcherError.invalidFormat("load command \(index) runs past the end of the file")
+ }
+ let cmd = data.loadLEValue(UInt32.self, at: offset)
+ let cmdsize = Int(data.loadLEValue(UInt32.self, at: offset + 4))
+ guard cmdsize >= 8, data.holds(offset, cmdsize) else {
+ throw PatcherError.invalidFormat("load command \(index) declares an impossible size \(cmdsize)")
+ }
+
+ switch cmd {
+ case lcCodeSignature:
+ guard data.holds(offset, 16) else {
+ throw PatcherError.invalidFormat("LC_CODE_SIGNATURE is truncated")
+ }
+ layout.codeSignature = CodeSignatureCommand(
+ commandOffset: offset,
+ commandSize: cmdsize,
+ dataOffset: Int(data.loadLEValue(UInt32.self, at: offset + 8)),
+ dataSize: Int(data.loadLEValue(UInt32.self, at: offset + 12))
+ )
+ layout.codeSignatureIsLast = index == ncmds - 1
+ case lcSegment64:
+ guard data.holds(offset, 72) else {
+ throw PatcherError.invalidFormat("LC_SEGMENT_64 is truncated")
+ }
+ let name = segmentName(in: data, at: offset + 8)
+ if name == "__LINKEDIT" {
+ layout.linkEditCommandOffset = offset
+ layout.linkEditFileOffset = Int(data.loadLEValue(UInt64.self, at: offset + 40))
+ layout.linkEditFileSize = Int(data.loadLEValue(UInt64.self, at: offset + 48))
+ }
+ case lcSymtab:
+ guard data.holds(offset, 24) else {
+ throw PatcherError.invalidFormat("LC_SYMTAB is truncated")
+ }
+ layout.symtabCommandOffset = offset
+ default:
+ break
+ }
+ offset += cmdsize
+ }
+ return layout
+ }
+
+ static func segmentName(in data: Data, at offset: Int) -> String {
+ let bytes = data[offset ..< offset + 16].prefix { $0 != 0 }
+ return String(decoding: bytes, as: UTF8.self)
+ }
+
+ // MARK: Code Signature Removal
+
+ /// Remove the signature the way `insert_dylib` does.
+ ///
+ /// When the signature sits at the very end of __LINKEDIT and __LINKEDIT sits
+ /// at the very end of the slice — true for every linker output — the slice is
+ /// shortened instead of just blanked, __LINKEDIT shrinks with it, and the
+ /// string table is stretched over the gap left between it and the old
+ /// signature so the linkedit contents stay contiguous. Anything else falls
+ /// back to zeroing the blob in place.
+ static func stripCodeSignature(
+ from data: inout Data,
+ headerOffset: Int,
+ sliceSize: inout Int,
+ signature: CodeSignatureCommand,
+ layout: SliceLayout
+ ) throws {
+ data.zeroBytes(at: signature.commandOffset, count: signature.commandSize)
+
+ let canTruncate = layout.linkEditCommandOffset != nil
+ && layout.linkEditFileOffset + layout.linkEditFileSize == sliceSize
+ && signature.dataOffset + signature.dataSize == sliceSize
+ guard canTruncate, let linkEditOffset = layout.linkEditCommandOffset else {
+ guard data.holds(headerOffset + signature.dataOffset, signature.dataSize) else {
+ throw PatcherError.invalidFormat("LC_CODE_SIGNATURE points outside the file")
+ }
+ data.zeroBytes(at: headerOffset + signature.dataOffset, count: signature.dataSize)
+ return
+ }
+
+ sliceSize -= signature.dataSize
+
+ // The string table is the last thing in __LINKEDIT before the signature,
+ // and its recorded size can fall a few bytes short of where the signature
+ // began (alignment padding). Stretch it to the new slice end so nothing
+ // is left unaccounted for; leave it alone if the gap is implausible.
+ if let symtabOffset = layout.symtabCommandOffset {
+ let stringOffset = Int(data.loadLEValue(UInt32.self, at: symtabOffset + 16))
+ let stringSize = Int(data.loadLEValue(UInt32.self, at: symtabOffset + 20))
+ let difference = stringOffset + stringSize - sliceSize
+ if difference >= -0x10, difference <= 0 {
+ data.storeLE(UInt32(stringSize - difference), at: symtabOffset + 20)
+ }
+ }
+
+ let newLinkEditFileSize = layout.linkEditFileSize - signature.dataSize
+ data.storeLE(UInt64(newLinkEditFileSize), at: linkEditOffset + 48)
+ data.storeLE(UInt64(roundUp(newLinkEditFileSize, to: 0x1000)), at: linkEditOffset + 32)
+ }
+
+ // MARK: Re-attestation
+
+ /// Re-hash the touched pages of one slice.
+ ///
+ /// The CodeDirectory's offsets are slice-relative, so a fat slice has to be
+ /// re-attested on its own bytes and spliced back rather than re-attested in
+ /// place against whole-file offsets.
+ static func reattestSlice(
+ in data: inout Data,
+ headerOffset: Int,
+ sliceSize: Int,
+ touched: [Range<Int>]
+ ) throws -> [CFWSlotRehash] {
+ var slice = Data(data[headerOffset ..< headerOffset + sliceSize])
+ let offsets = touched.flatMap { range in range.map { $0 - headerOffset } }
+ let records = try CFWMachOCodeSignature.reattest(&slice, modifiedOffsets: offsets)
+ data.replaceSubrange(headerOffset ..< headerOffset + sliceSize, with: slice)
+ return records
+ }
+
+ // MARK: Helpers
+
+ static func roundUp(_ value: Int, to alignment: Int) -> Int {
+ guard alignment > 1 else { return value }
+ return (value + alignment - 1) & ~(alignment - 1)
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/CFWMachLookupExceptions.swift b/sources/FirmwarePatcher/CFW/CFWMachLookupExceptions.swift
new file mode 100644
index 00000000..6332bf0b
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/CFWMachLookupExceptions.swift
@@ -0,0 +1,128 @@
+// CFWMachLookupExceptions.swift — Campo backboard/frontboard mach-lookups.
+//
+// Swift port of scripts/patchers/campo_mach_lookup_exceptions.py (JB-3b).
+// See research/0_binary_patch_comparison.md #14.
+//
+// iOS 27's temporary sandbox denies Campo.app the backboard/frontboard
+// services it needs to put a window on screen. The install step dumps
+// Campo's entitlements with `ldid -e`, merges the missing global-name
+// lookups into the mach-lookup exception array, and re-signs with the
+// merged plist.
+//
+// The merge is append-only and order-preserving: entries already present
+// keep their position, and anything the binary carried that is not in this
+// list survives. That matters because the plist is fed straight back to
+// `ldid`, and dropping an entitlement Campo already had would be a silent
+// downgrade.
+
+import Foundation
+
+/// Merges the mach-lookup global-name exceptions Campo needs into an
+/// entitlements plist, in place.
+public enum CFWMachLookupExceptions {
+ /// The entitlement array this patcher merges into.
+ public static let exceptionKey = "com.apple.security.exception.mach-lookup.global-name"
+
+ /// The services Campo needs and iOS 27's temporary sandbox denies.
+ /// Order is load-bearing only in that it is the order new entries are
+ /// appended in — it has to match the Python for the comparison to hold.
+ public static let services: [String] = [
+ "com.apple.backboard.display.services",
+ "com.apple.iohideventsystem",
+ "com.apple.CARenderServer",
+ "com.apple.backboard.hid.services",
+ "com.apple.backboard.hid-services.xpc",
+ "com.apple.backboard.TouchDeliveryPolicyServer",
+ "com.apple.backboard.system-app-server",
+ "com.apple.backboard.watchdog",
+ "com.apple.backboard.oswatchdog",
+ "com.apple.backboard.altsysapp",
+ "com.apple.AttentionAwareness",
+ "PurpleSystemEventPort",
+ "PurpleWorkspacePort",
+ "com.apple.frontboard.systemappservices",
+ "com.apple.frontboard.workspace",
+ "com.apple.frontboardservices.systemappmanager",
+ "com.apple.frontboard.watchdog",
+ ]
+
+ /// What the merge did.
+ public struct Outcome: Sendable, Equatable {
+ /// Size of the exception array after the merge.
+ public let total: Int
+ /// How many entries this run appended.
+ public let added: Int
+ }
+
+ // MARK: - Merging
+
+ /// Merge ``services`` into the exception array at `url`, in place.
+ ///
+ /// The file is written back as an XML plist regardless of the input
+ /// format, which is what `plistlib.dump()` defaults to and what `ldid`
+ /// expects on the way back in.
+ @discardableResult
+ public static func merge(at url: URL, verbose: Bool = true) throws -> Outcome {
+ let data: Data
+ do {
+ data = try Data(contentsOf: url)
+ } catch {
+ throw PatcherError.fileNotFound(url.path)
+ }
+
+ guard let parsed = try? PropertyListSerialization.propertyList(
+ from: data,
+ options: [],
+ format: nil
+ ) else {
+ throw PatcherError.invalidFormat("cannot parse as plist: \(url.path)")
+ }
+ guard var entitlements = parsed as? [String: Any] else {
+ throw PatcherError.invalidFormat(
+ "top-level plist is \(type(of: parsed)), expected dict: \(url.path)"
+ )
+ }
+
+ let existing = try existingExceptions(entitlements[exceptionKey], path: url.path)
+ let added = services.filter { !existing.contains($0) }
+ let merged = existing + added
+ entitlements[exceptionKey] = merged
+
+ let output = try PropertyListSerialization.data(
+ fromPropertyList: entitlements,
+ format: .xml,
+ options: 0
+ )
+ try output.write(to: url)
+
+ if verbose {
+ print(" [+] Campo mach-lookup exception count: \(merged.count) (+\(added.count) added)")
+ }
+ return Outcome(total: merged.count, added: added.count)
+ }
+
+ /// Read the existing exception array.
+ ///
+ /// A missing key means an empty array, matching the Python's
+ /// `entitlements.get(KEY, [])`. A present-but-not-an-array value is an
+ /// error here, where the Python would run `list()` over it — turning a
+ /// string entitlement into one array entry per character and re-signing
+ /// Campo with the result. Refusing is the only sane reading of a file
+ /// that is about to be handed to `ldid`.
+ private static func existingExceptions(_ value: Any?, path: String) throws -> [String] {
+ guard let value else { return [] }
+ guard let array = value as? [Any] else {
+ throw PatcherError.invalidFormat(
+ "'\(exceptionKey)' is \(type(of: value)), expected array: \(path)"
+ )
+ }
+ return try array.map { element in
+ guard let string = element as? String else {
+ throw PatcherError.invalidFormat(
+ "'\(exceptionKey)' holds a non-string entry (\(type(of: element))): \(path)"
+ )
+ }
+ return string
+ }
+ }
+}
diff --git a/sources/FirmwarePatcher/CFW/CFWMachOCodeSignature.swift b/sources/FirmwarePatcher/CFW/CFWMachOCodeSignature.swift
new file mode 100644
index 00000000..2f57b632
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/CFWMachOCodeSignature.swift
@@ -0,0 +1,369 @@
+// CFWMachOCodeSignature.swift — Standalone Mach-O code-signature page-hash re-attestation.
+//
+// Port of `scripts/patchers/cfw_macho_codesign.py` (344 lines). The DSC-chunk
+// half of the same technique lives elsewhere and deliberately does NOT share
+// this code: the two differ in where the signature is found, in page size, in
+// how many code directories exist, and — the part that bit us before — in
+// whether the last slot covers a whole page.
+//
+// Why this exists at all: on iPhone17,3 / iOS 26.x `codeSigningMonitor == 2`,
+// so the kernel hands per-page hash validation to TXM. TXM holds the original
+// slot hashes, so any byte we change inside an executable mapping is a
+// KERN_PROTECTION_FAILURE / SIGKILL the first time that page is demand-paged
+// in. Recomputing the slot hash for every page we touched is what keeps a
+// patched binary runnable.
+//
+// Side effect, unchanged from the Python: rewriting slot hashes mutates the
+// CodeDirectory, and therefore the cdHash. The JB kernel patch
+// `patch_amfi_cdhash_in_trustcache` short-circuits AMFI's trust-cache lookup so
+// the mutated cdHash is not rejected at execve. That precondition still holds
+// for this implementation — do not drop it.
+
+import CryptoKit
+import Foundation
+
+// MARK: - Byte Reading
+
+// The Mach-O header and load commands are little-endian; everything inside the
+// CS_SuperBlob is big-endian. Data.loadLE covers the first half, so this file
+// only needs the second.
+private extension Data {
+ func loadBE<T: FixedWidthInteger>(_: T.Type, at offset: Int) -> T {
+ var value: T = .zero
+ _ = Swift.withUnsafeMutableBytes(of: &value) { destination in
+ copyBytes(to: destination, from: offset ..< offset + MemoryLayout<T>.size)
+ }
+ return T(bigEndian: value)
+ }
+
+ func fits(_ offset: Int, _ length: Int) -> Bool {
+ offset >= 0 && length >= 0 && offset + length <= count
+ }
+}
+
+// MARK: - Code Directory
+
+/// One `CS_CodeDirectory` blob inside a Mach-O's embedded signature.
+public struct CFWCodeDirectory: Sendable, Equatable {
+ /// `CS_BlobIndex.type` this CD was reached through (0 = primary, 0x1000+ = alt).
+ public let slotType: UInt32
+ /// Absolute file offset of the CD blob.
+ public let offset: Int
+ public let length: Int
+ /// Offset within the CD blob of code slot 0.
+ public let hashOffset: Int
+ public let hashSize: Int
+ public let hashType: UInt8
+ public let pageSize: Int
+ public let pageSizeLog2: UInt8
+ public let codeSlotCount: Int
+ /// The CD covers `[0, codeLimit)` of the file. Rarely page-aligned.
+ public let codeLimit: Int
+
+ /// File offset of slot `index`'s hash.
+ public func slotHashOffset(_ index: Int) -> Int {
+ offset + hashOffset + index * hashSize
+ }
+
+ /// The byte range slot `index` hashes.
+ ///
+ /// Clamped to `codeLimit`, which is what makes the last slot SHORT. Getting
+ /// this wrong is the known regression in independent Mach-O re-signing: the
+ /// tail slot hashes `codeLimit - slotStart` bytes, not a full page, and a
+ /// full-page hash there produces a binary that is SIGKILLed on first page-in.
+ public func slotRange(_ index: Int) -> Range<Int>? {
+ guard index >= 0, index < codeSlotCount else { return nil }
+ let start = index * pageSize
+ guard start < codeLimit else { return nil }
+ return start ..< Swift.min(start + pageSize, codeLimit)
+ }
+}
+
+// MARK: - Slot Rehash Record
+
+/// One slot hash that re-attestation replaced.
+public struct CFWSlotRehash: Sendable, Equatable {
+ public let codeDirectoryOffset: Int
+ public let slotType: UInt32
+ public let pageIndex: Int
+ public let pageStart: Int
+ public let pageEnd: Int
+ /// File offset the new hash was written to.
+ public let hashFileOffset: Int
+ public let before: Data
+ public let after: Data
+ /// Page size of the code directory this slot belongs to.
+ public let pageSize: Int
+
+ /// Bytes actually hashed. Less than `pageSize` for the tail slot.
+ public var hashedLength: Int { pageEnd - pageStart }
+ public var isTailSlot: Bool { hashedLength != pageSize }
+}
+
+extension CFWSlotRehash: CustomStringConvertible {
+ public var description: String {
+ let tail = isTailSlot ? " [tail, \(hashedLength)B]" : ""
+ return String(
+ format: "slot %d%@ @0x%X: %@.. -> %@..",
+ pageIndex,
+ tail,
+ hashFileOffset,
+ String(before.hex.prefix(8)),
+ String(after.hex.prefix(8))
+ )
+ }
+}
+
+// MARK: - Re-attestation
+
+public enum CFWMachOCodeSignature {
+ // MARK: Constants
+
+ static let superBlobMagic: UInt32 = 0xFADE_0CC0
+ static let codeDirectoryMagic: UInt32 = 0xFADE_0C02
+
+ public static let hashTypeSHA1: UInt8 = 1
+ public static let hashTypeSHA256: UInt8 = 2
+ public static let hashTypeSHA384: UInt8 = 3
+ public static let hashTypeSHA256Truncated: UInt8 = 4
+
+ static let lcCodeSignature: UInt32 = 0x1D
+ static let machMagic64: UInt32 = 0xFEED_FACF
+
+ /// A CD's own header is 44 bytes up to and including `codeLimit`.
+ static let codeDirectoryHeaderSize = 44
+ /// Guard against a runaway `count` in a corrupt SuperBlob. Matches the Python.
+ static let maxSuperBlobEntries = 256
+
+ // MARK: Parsing
+
+ /// `(dataoff, datasize)` of the binary's LC_CODE_SIGNATURE, or nil.
+ public static func codeSignatureCommand(in data: Data) -> (offset: Int, size: Int)? {
+ let data = rebased(data)
+ guard data.fits(0, 32), data.loadLE(UInt32.self, at: 0) == machMagic64 else { return nil }
+ let ncmds = data.loadLE(UInt32.self, at: 16)
+ var offset = 32 // sizeof(mach_header_64)
+ for _ in 0 ..< ncmds {
+ guard data.fits(offset, 8) else { return nil }
+ let cmd = data.loadLE(UInt32.self, at: offset)
+ let cmdsize = Int(data.loadLE(UInt32.self, at: offset + 4))
+ if cmd == lcCodeSignature {
+ guard data.fits(offset, 16) else { return nil }
+ return (
+ Int(data.loadLE(UInt32.self, at: offset + 8)),
+ Int(data.loadLE(UInt32.self, at: offset + 12))
+ )
+ }
+ guard cmdsize > 0 else { return nil }
+ offset += cmdsize
+ }
+ return nil
+ }
+
+ /// Every `CS_CodeDirectory` in the embedded signature, in SuperBlob order.
+ ///
+ /// Returns nil when there is no signature or it is unparsable — the caller
+ /// decides whether that is fatal. An empty array means a signature exists
+ /// but holds no CodeDirectory, which is malformed.
+ public static func codeDirectories(in data: Data) -> [CFWCodeDirectory]? {
+ let data = rebased(data)
+ guard let signature = codeSignatureCommand(in: data) else { return nil }
+ guard let blobs = superBlobEntries(in: data, at: signature.offset) else { return nil }
+ return blobs.compactMap { entry in
+ guard entry.magic == codeDirectoryMagic else { return nil }
+ return parseCodeDirectory(in: data, at: entry.offset, slotType: entry.slotType)
+ }
+ }
+
+ static func superBlobEntries(
+ in data: Data,
+ at superBlobOffset: Int
+ ) -> [(slotType: UInt32, offset: Int, magic: UInt32)]? {
+ guard data.fits(superBlobOffset, 12) else { return nil }
+ let magic = data.loadBE(UInt32.self, at: superBlobOffset)
+ let length = Int(data.loadBE(UInt32.self, at: superBlobOffset + 4))
+ let count = Int(data.loadBE(UInt32.self, at: superBlobOffset + 8))
+ guard magic == superBlobMagic else { return nil }
+ guard count <= maxSuperBlobEntries, data.fits(superBlobOffset, length) else { return nil }
+
+ var entries: [(slotType: UInt32, offset: Int, magic: UInt32)] = []
+ for index in 0 ..< count {
+ let entryOffset = superBlobOffset + 12 + index * 8
+ guard data.fits(entryOffset, 8) else { return nil }
+ let slotType = data.loadBE(UInt32.self, at: entryOffset)
+ let blobOffset = superBlobOffset + Int(data.loadBE(UInt32.self, at: entryOffset + 4))
+ guard data.fits(blobOffset, 4) else { return nil }
+ entries.append((slotType, blobOffset, data.loadBE(UInt32.self, at: blobOffset)))
+ }
+ return entries
+ }
+
+ static func parseCodeDirectory(in data: Data, at offset: Int, slotType: UInt32) -> CFWCodeDirectory? {
+ guard data.fits(offset, codeDirectoryHeaderSize) else { return nil }
+ guard data.loadBE(UInt32.self, at: offset) == codeDirectoryMagic else { return nil }
+
+ let length = Int(data.loadBE(UInt32.self, at: offset + 4))
+ let hashOffset = Int(data.loadBE(UInt32.self, at: offset + 16))
+ let codeSlotCount = Int(data.loadBE(UInt32.self, at: offset + 28))
+ // `codeLimit` is the 32-bit field. Binaries over 4 GiB carry the real
+ // value in `codeLimit64` (version >= 0x20400) — the Python ignores that
+ // too, and nothing in this pipeline is that large.
+ let codeLimit = Int(data.loadBE(UInt32.self, at: offset + 32))
+ let hashSize = Int(data[offset + 36])
+ let hashType = data[offset + 37]
+ let pageSizeLog2 = data[offset + 39]
+
+ guard pageSizeLog2 > 0, pageSizeLog2 < 24 else { return nil }
+ let pageSize = 1 << Int(pageSizeLog2)
+
+ guard data.fits(offset, length) else { return nil }
+ guard data.fits(offset + hashOffset, codeSlotCount * hashSize) else { return nil }
+
+ return CFWCodeDirectory(
+ slotType: slotType,
+ offset: offset,
+ length: length,
+ hashOffset: hashOffset,
+ hashSize: hashSize,
+ hashType: hashType,
+ pageSize: pageSize,
+ pageSizeLog2: pageSizeLog2,
+ codeSlotCount: codeSlotCount,
+ codeLimit: codeLimit
+ )
+ }
+
+ /// `(pageIndex, start, end)` of the slot covering `fileOffset`, or nil when
+ /// the offset is past `codeLimit` and therefore covered by no slot.
+ public static func pageBounds(
+ fileOffset: Int,
+ pageSize: Int,
+ codeLimit: Int
+ ) -> (index: Int, start: Int, end: Int)? {
+ guard fileOffset >= 0, fileOffset < codeLimit, pageSize > 0 else { return nil }
+ let index = fileOffset / pageSize
+ let start = index * pageSize
+ return (index, start, Swift.min(start + pageSize, codeLimit))
+ }
+
+ // MARK: Entry Points
+
+ /// Code directories this module refuses to recompute, for the caller to warn
+ /// about. A legacy SHA-1 alt-CD lands here: it is left byte-for-byte alone,
+ /// so a consumer that trusts it will reject the patched binary.
+ public static func unsupportedCodeDirectories(in data: Data) -> [CFWCodeDirectory] {
+ (codeDirectories(in: data) ?? []).filter { $0.hashType != hashTypeSHA256 }
+ }
+
+ /// Recompute the slot hash of every page touched by `modifiedOffsets`.
+ ///
+ /// Only code directories with `hashType == SHA-256` are updated — see
+ /// `unsupportedCodeDirectories(in:)` for what that leaves behind.
+ ///
+ /// Throws `PatcherError.invalidFormat` when the binary carries no usable
+ /// signature — for every caller that is a hard error, because the binary was
+ /// not the shape we were told it was.
+ @discardableResult
+ public static func reattest(
+ _ data: inout Data,
+ modifiedOffsets: some Sequence<Int>,
+ dryRun: Bool = false
+ ) throws -> [CFWSlotRehash] {
+ let offsets = Array(modifiedOffsets)
+ if offsets.isEmpty { return [] }
+
+ if data.startIndex != 0 { data = Data(data) }
+
+ guard let directories = codeDirectories(in: data) else {
+ throw PatcherError.invalidFormat("no LC_CODE_SIGNATURE / CS_CodeDirectory found")
+ }
+ guard !directories.isEmpty else {
+ throw PatcherError.invalidFormat("LC_CODE_SIGNATURE present but no CodeDirectory blobs")
+ }
+
+ // (cdIndex, pageIndex) -> byte range. Different CDs may in principle use
+ // different page sizes, so the work is kept per-CD rather than merged.
+ var work: [SlotKey: Range<Int>] = [:]
+ for (cdIndex, directory) in directories.enumerated() {
+ guard directory.hashType == hashTypeSHA256 else { continue }
+ guard directory.hashSize == SHA256.byteCount else {
+ throw PatcherError.invalidFormat(
+ "SHA-256 CodeDirectory at 0x\(String(directory.offset, radix: 16)) "
+ + "declares hashSize \(directory.hashSize), expected \(SHA256.byteCount)"
+ )
+ }
+ for fileOffset in offsets {
+ guard let bounds = pageBounds(
+ fileOffset: fileOffset,
+ pageSize: directory.pageSize,
+ codeLimit: directory.codeLimit
+ ) else { continue }
+ guard bounds.index < directory.codeSlotCount else { continue }
+ work[SlotKey(cdIndex: cdIndex, pageIndex: bounds.index)] = bounds.start ..< bounds.end
+ }
+ }
+
+ var records: [CFWSlotRehash] = []
+ for (key, range) in work.sorted(by: { $0.key < $1.key }) {
+ let directory = directories[key.cdIndex]
+ let slotOffset = directory.slotHashOffset(key.pageIndex)
+ guard data.fits(slotOffset, directory.hashSize), data.fits(range.lowerBound, range.count) else {
+ throw PatcherError.invalidFormat("code directory slot \(key.pageIndex) falls outside the file")
+ }
+
+ let newHash = Data(SHA256.hash(data: data[range]))
+ let oldHash = data[slotOffset ..< slotOffset + directory.hashSize]
+ if oldHash == newHash { continue }
+
+ if !dryRun {
+ data.replaceSubrange(slotOffset ..< slotOffset + directory.hashSize, with: newHash)
+ }
+ records.append(CFWSlotRehash(
+ codeDirectoryOffset: directory.offset,
+ slotType: directory.slotType,
+ pageIndex: key.pageIndex,
+ pageStart: range.lowerBound,
+ pageEnd: range.upperBound,
+ hashFileOffset: slotOffset,
+ before: Data(oldHash),
+ after: newHash,
+ pageSize: directory.pageSize
+ ))
+ }
+ return records
+ }
+
+ /// File-backed form of `reattest(_:modifiedOffsets:)`.
+ @discardableResult
+ public static func reattest(
+ fileAt url: URL,
+ modifiedOffsets: some Sequence<Int>,
+ dryRun: Bool = false
+ ) throws -> [CFWSlotRehash] {
+ guard FileManager.default.fileExists(atPath: url.path) else {
+ throw PatcherError.fileNotFound(url.path)
+ }
+ var data = try Data(contentsOf: url)
+ let records = try reattest(&data, modifiedOffsets: modifiedOffsets, dryRun: dryRun)
+ if !dryRun, !records.isEmpty {
+ try data.write(to: url)
+ }
+ return records
+ }
+
+ // MARK: Helpers
+
+ struct SlotKey: Hashable, Comparable {
+ let cdIndex: Int
+ let pageIndex: Int
+
+ static func < (lhs: Self, rhs: Self) -> Bool {
+ (lhs.cdIndex, lhs.pageIndex) < (rhs.cdIndex, rhs.pageIndex)
+ }
+ }
+
+ /// 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/CFWPostRestoreDeviceTree.swift b/sources/FirmwarePatcher/CFW/CFWPostRestoreDeviceTree.swift
new file mode 100644
index 00000000..3f764ff7
--- /dev/null
+++ b/sources/FirmwarePatcher/CFW/CFWPostRestoreDeviceTree.swift
@@ -0,0 +1,556 @@
+// CFWPostRestoreDeviceTree.swift — post-restore DT identity rewrite.
+//
+// Swift port of scripts/patchers/cfw_patch_post_restore_dt.py (EXP-JB-6).
+//
+// Three root properties of the restored device tree, and only three:
+//
+// root/model "iPhone99,11" -> "iPhone17,3"
+// root/target-type "VPHONE600" -> "D47"
+// root/compatible ["VPHONE600AP", "iPhone99,11", "AppleVirtualPlatformARM"]
+// -> ["D47AP", "VPHONE600AP", "AppleVirtualPlatformARM"]
+//
+// They are restore-time fatal, which is why they are not in
+// `DeviceTreePatcher.identityPropertyPatches` with the other eight:
+// `restored_external` and iBoot's restore mode cross-check DT root `model`
+// and `target-type` against the BuildManifest's signed identity and reject
+// the device on mismatch. Both were tried at fw_patch time, both broke
+// restore. They are not boot-time fatal — after restore, the iBSS / iBEC /
+// LLB `image4_validate_property_callback` bypass accepts any IM4P contents
+// — so the install pipeline re-patches the DT offline, on the host-mounted
+// restored filesystem, before the device boots into the rootfs.
+//
+// The `compatible` rewrite is a reorder, not a replacement: VPHONE600AP
+// stays in the list, now second, so IOKit's platform-expert binding to
+// AppleVMApple1IO still works. The first entry — the one userland reads for
+// `hw.model` — becomes D47AP.
+//
+// Every property keeps its original slot length, so the serialized tree is
+// the same size as the one parsed. That is asserted, not assumed.
+
+import Foundation
+import Img4tool
+
+/// Rewrites the three restore-fatal identity properties in a
+/// `devicetree.img4` (or bare `.im4p`), in place, preserving the container's
+/// compression, manifest and restore info.
+public enum CFWPostRestoreDeviceTree {
+ // MARK: - Targets
+
+ static let targetModel = "iPhone17,3"
+ static let targetTargetType = "D47"
+
+ /// The reordered `compatible` body, NUL-delimited, before slot padding.
+ static let targetCompatibleBody = Data(
+ "D47AP\0VPHONE600AP\0AppleVirtualPlatformARM\0".utf8
+ )
+
+ // MARK: - Results
+
+ /// One property rewrite, as the log line describes it.
+ public struct Change: Sendable, Equatable {
+ public let property: String
+ public let before: String
+ public let after: String
+ }
+
+ /// What a patch attempt did.
+ public struct Outcome: Sendable, Equatable {
+ public let changes: [Change]
+ /// Bytes landed on disk. False when the DT was already in the target
+ /// state, or when `dryRun` suppressed the write.
+ public let wrote: Bool
+ /// Size of the rebuilt container, or the original's when nothing changed.
+ public let outputSize: Int
+ }
+
+ // MARK: - File-level patching
+
+ /// Patch a `devicetree.img4` (preferred) or bare `devicetree.im4p` in place.
+ @discardableResult
+ public static func patch(
+ at url: URL,
+ dryRun: Bool = false,
+ verbose: Bool = true
+ ) throws -> Outcome {
+ let data: Data
+ do {
+ data = try Data(contentsOf: url)
+ } catch {
+ throw PatcherError.fileNotFound(url.path)
+ }
+
+ let container = try Container(data)
+ let im4p = try IM4P(container.im4pBytes)
+ guard im4p.fourcc == "dtre" else {
+ throw PatcherError.invalidFormat(
+ "expected DT payload (fourcc='dtre'), got fourcc='\(im4p.fourcc)'"
+ )
+ }
+ guard !im4p.isEncrypted else {
+ throw PatcherError.invalidFormat("DT payload is encrypted (KBAG present): \(url.path)")
+ }
+
+ let compression = try container.payloadCompression()
+ let kind = container.isIMG4 ? "IMG4" : "IM4P"
+ if verbose {
+ print(" [.] \(url.path): \(kind) desc='\(im4p.description)' "
+ + "payload_compression=\(compression.rawValue)")
+ }
+
+ let blob = try im4p.payload()
+ // Img4tool finds the uncompressed size in the IM4P's compression-info
+ // element rather than in the bvx2 stream, so a container that carries
+ // the magic but not the element comes back still compressed. Refuse
+ // it: the alternative is parsing compressed bytes as a device tree.
+ guard compression == .none || !compression.isStillCompressed(blob) else {
+ throw PatcherError.invalidFormat(
+ "IM4P payload is \(compression) but did not decompress — no compression-info element?"
+ )
+ }
+ if verbose { print(" [.] DT blob: \(blob.count) bytes") }
+
+ let (newBlob, changes) = try patchedDeviceTree(blob)
+ guard !changes.isEmpty else {
+ if verbose { print(" [.] \(url.path): DT already in target state — no change") }
+ return Outcome(changes: [], wrote: false, outputSize: data.count)
+ }
+ if verbose {
+ for change in changes {
+ print(" [+] \(change.property): '\(change.before)' -> '\(change.after)'")
+ }
+ }
+ // Every patch writes into the property's existing slot, so a size
+ // change means the parser and the serializer have drifted apart —
+ // and an IM4P whose payload no longer matches its recorded
+ // uncompressed size will not load.
+ guard newBlob.count == blob.count else {
+ throw PatcherError.patchVerificationFailed(
+ "DT size changed: \(blob.count) -> \(newBlob.count) bytes (would break IM4P offsets)"
+ )
+ }
+
+ let newIM4P = try IM4P(
+ fourcc: im4p.fourcc,
+ description: im4p.description,
+ payload: newBlob,
+ compression: compression.img4toolName
+ )
+ let output = try container.rebuilt(im4pBytes: newIM4P.data)
+
+ if verbose { print(" [.] output size: \(output.count) bytes (was \(data.count))") }
+ if dryRun {
+ if verbose { print(" [.] dry-run — not writing back") }
+ return Outcome(changes: changes, wrote: false, outputSize: output.count)
+ }
+
+ try output.write(to: url)
+ if verbose { print(" [+] wrote \(url.path)") }
+ return Outcome(changes: changes, wrote: true, outputSize: output.count)
+ }
+
+ // MARK: - Device tree patching
+
+ /// Apply the three identity rewrites to a flat device tree blob.
+ /// Returns the blob unchanged and no changes when it is already in the
+ /// target state.
+ public static func patchedDeviceTree(_ blob: Data) throws -> (Data, [Change]) {
+ let (root, end) = try parseNode(blob, at: 0)
+ guard end == blob.count else {
+ throw PatcherError.invalidFormat(
+ "DT parse length mismatch: ended at \(end), blob is \(blob.count)"
+ )
+ }
+ guard nodeName(root) == "device-tree" else {
+ throw PatcherError.invalidFormat(
+ "expected root node 'device-tree', got '\(nodeName(root))'"
+ )
+ }
+
+ var changes: [Change] = []
+
+ let model = try property(root, named: "model")
+ let newModel = encodeFixedString(targetModel, length: model.length)
+ if model.value != newModel {
+ changes.append(Change(
+ property: "model",
+ before: cString(model.value),
+ after: targetModel
+ ))
+ model.value = newModel
+ }
+
+ let targetType = try property(root, named: "target-type")
+ let newTargetType = encodeFixedString(targetTargetType, length: targetType.length)
+ if targetType.value != newTargetType {
+ changes.append(Change(
+ property: "target-type",
+ before: cString(targetType.value),
+ after: targetTargetType
+ ))
+ targetType.value = newTargetType
+ }
+
+ let compatible = try property(root, named: "compatible")
+ guard targetCompatibleBody.count <= compatible.length else {
+ throw PatcherError.invalidFormat(
+ "compatible body \(targetCompatibleBody.count)B > slot \(compatible.length)B"
+ )
+ }
+ var newCompatible = targetCompatibleBody
+ newCompatible.append(
+ contentsOf: [UInt8](repeating: 0, count: compatible.length - newCompatible.count)
+ )
+ if compatible.value != newCompatible {
+ changes.append(Change(
+ property: "compatible",
+ before: "[\(cStringList(compatible.value).joined(separator: ", "))]",
+ after: "[D47AP, VPHONE600AP, AppleVirtualPlatformARM]"
+ ))
+ compatible.value = newCompatible
+ }
+
+ guard !changes.isEmpty else { return (blob, []) }
+ return (serializeNode(root), changes)
+ }
+
+ // MARK: - Flat device tree format
+ //
+ // Per node: u32 nProps, u32 nChildren, then each property as
+ // char[32] name, u16 length, u16 flags, u8[length] value, padded to a
+ // 4-byte boundary; then each child node, recursively.
+ //
+ // The top bit of the length field is XNU's out-of-line "placeholder"
+ // flag and is masked off for the real size. `DeviceTreePatcher` parses
+ // the same layout at fw_patch time; this is a second reader only because
+ // its own parse/serialize pair is file-private. See `integrationNeeded`
+ // in the migration notes.
+
+ private static func align4(_ n: Int) -> Int { (n + 3) & ~3 }
+
+ private static func parseNode(
+ _ blob: Data,
+ at offset: Int
+ ) throws -> (DeviceTreePatcher.DTNode, Int) {
+ guard offset + 8 <= blob.count else {
+ throw PatcherError.invalidFormat("DT truncated at offset 0x\(String(offset, radix: 16))")
+ }
+ let propertyCount = Int(blob.loadLE(UInt32.self, at: offset))
+ let childCount = Int(blob.loadLE(UInt32.self, at: offset + 4))
+ var pos = offset + 8
+ let node = DeviceTreePatcher.DTNode()
+
+ for _ in 0 ..< propertyCount {
+ guard pos + 36 <= blob.count else {
+ throw PatcherError.invalidFormat(
+ "DT property header truncated at 0x\(String(pos, radix: 16))"
+ )
+ }
+ let name = cString(slice(blob, pos, 32))
+ let length = Int(blob.loadLE(UInt16.self, at: pos + 32) & 0x7FFF)
+ let flags = blob.loadLE(UInt16.self, at: pos + 34)
+ let valueOffset = pos + 36
+ guard valueOffset + length <= blob.count else {
+ throw PatcherError.invalidFormat(
+ "DT property value '\(name)' truncated at 0x\(String(valueOffset, radix: 16))"
+ )
+ }
+ node.properties.append(DeviceTreePatcher.DTProperty(
+ name: name,
+ length: length,
+ flags: flags,
+ value: slice(blob, valueOffset, length),
+ valueOffset: valueOffset
+ ))
+ pos = valueOffset + align4(length)
+ }
+
+ for _ in 0 ..< childCount {
+ let (child, next) = try parseNode(blob, at: pos)
+ node.children.append(child)
+ pos = next
+ }
+ return (node, pos)
+ }
+
+ private static func serializeNode(_ node: DeviceTreePatcher.DTNode) -> Data {
+ var out = Data()
+ out.append(littleEndian: UInt32(node.properties.count))
+ out.append(littleEndian: UInt32(node.children.count))
+ for property in node.properties {
+ var name = Data(property.name.utf8)
+ if name.count >= 32 { name = Data(name.prefix(31)) }
+ name.append(contentsOf: [UInt8](repeating: 0, count: 32 - name.count))
+ out.append(name)
+ out.append(littleEndian: UInt16(property.length))
+ out.append(littleEndian: property.flags)
+ out.append(property.value)
+ let pad = align4(property.length) - property.length
+ if pad > 0 { out.append(Data(repeating: 0, count: pad)) }
+ }
+ for child in node.children {
+ out.append(serializeNode(child))
+ }
+ return out
+ }
+
+ private static func nodeName(_ node: DeviceTreePatcher.DTNode) -> String {
+ for property in node.properties where property.name == "name" {
+ return cString(property.value)
+ }
+ return ""
+ }
+
+ private static func property(
+ _ node: DeviceTreePatcher.DTNode,
+ named name: String
+ ) throws -> DeviceTreePatcher.DTProperty {
+ for property in node.properties where property.name == name {
+ return property
+ }
+ throw PatcherError.patchSiteNotFound(
+ "property '\(name)' not found in node '\(nodeName(node))'"
+ )
+ }
+
+ // MARK: - Value helpers
+
+ /// A NUL-terminated string padded (or truncated) to a fixed slot.
+ private static func encodeFixedString(_ text: String, length: Int) -> Data {
+ var raw = Data(text.utf8)
+ raw.append(0)
+ if raw.count > length { return Data(raw.prefix(length)) }
+ raw.append(contentsOf: [UInt8](repeating: 0, count: length - raw.count))
+ return raw
+ }
+
+ private static func cString(_ data: Data) -> String {
+ let body = data.prefix(while: { $0 != 0 })
+ return String(decoding: body, as: UTF8.self)
+ }
+
+ /// Split a NUL-delimited multi-string property into its non-empty parts.
+ private static func cStringList(_ data: Data) -> [String] {
+ data.split(separator: 0, omittingEmptySubsequences: true)
+ .map { String(decoding: $0, as: UTF8.self) }
+ }
+
+ private static func slice(_ data: Data, _ offset: Int, _ count: Int) -> Data {
+ let start = data.startIndex.advanced(by: offset)
+ return Data(data[start ..< start.advanced(by: count)])
+ }
+}
+
+// MARK: - Image4 container
+
+extension CFWPostRestoreDeviceTree {
+ /// How the IM4P payload is stored. The raw values are pyimg4's
+ /// `Compression` enum, so the log line reads the same either side.
+ enum PayloadCompression: Int, Sendable {
+ case none = 0
+ case lzss = 1
+ case lzfse = 2
+
+ var img4toolName: String? {
+ switch self {
+ case .none: nil
+ case .lzss: "lzss"
+ case .lzfse: "lzfse"
+ }
+ }
+
+ var magic: Data? {
+ switch self {
+ case .none: nil
+ case .lzss: Data("complzss".utf8)
+ case .lzfse: Data("bvx2".utf8)
+ }
+ }
+
+ func isStillCompressed(_ payload: Data) -> Bool {
+ guard let magic else { return false }
+ return payload.starts(with: magic)
+ }
+ }
+
+ /// An IMG4 or bare IM4P, split so the IM4P can be replaced without
+ /// touching anything else.
+ ///
+ /// For an IMG4 the manifest ([0] IM4M) and restore info ([1] IM4R) are
+ /// carried over as their original bytes. pyimg4 re-encodes the IM4M from
+ /// its parsed fields instead; preserving the signed bytes verbatim is the
+ /// safer of the two, and the difference is invisible for any manifest
+ /// that was DER-canonical to begin with.
+ struct Container {
+ let isIMG4: Bool
+ /// Raw DER of the IM4P element.
+ let im4pBytes: Data
+ /// The IMG4 elements around the IM4P, in order, as raw DER.
+ private let leading: Data
+ private let trailing: [Data]
+
+ init(_ data: Data) throws {
+ let outer = try DER.parse(data, at: 0)
+ guard outer.tag == DER.sequence, outer.range.upperBound == data.count else {
+ throw PatcherError.invalidFormat("not an Image4 container: trailing or short DER")
+ }
+ let children = try DER.children(data, of: outer)
+ guard let first = children.first, first.tag == DER.ia5String else {
+ throw PatcherError.invalidFormat("Image4 container has no type tag")
+ }
+
+ switch DER.string(data, first) {
+ case "IMG4":
+ guard children.count >= 3, children[1].tag == DER.sequence else {
+ throw PatcherError.invalidFormat("IMG4 does not contain an IM4P")
+ }
+ guard children[2].tag == DER.contextConstructed(0) else {
+ throw PatcherError.invalidFormat("IMG4 does not contain an IM4M")
+ }
+ isIMG4 = true
+ leading = DER.raw(data, first)
+ im4pBytes = DER.raw(data, children[1])
+ trailing = children[2...].map { DER.raw(data, $0) }
+ case "IM4P":
+ isIMG4 = false
+ leading = Data()
+ im4pBytes = data
+ trailing = []
+ default:
+ throw PatcherError.invalidFormat("unrecognized Image4 container type")
+ }
+ }
+
+ /// Which compression the stored payload uses, sniffed from the
+ /// payload's own magic exactly as pyimg4 does.
+ func payloadCompression() throws -> PayloadCompression {
+ let element = try DER.parse(im4pBytes, at: 0)
+ let children = try DER.children(im4pBytes, of: element)
+ guard children.count >= 4 else {
+ throw PatcherError.invalidFormat("malformed IM4P structure")
+ }
+ let payload = DER.value(im4pBytes, children[3])
+ for candidate in [PayloadCompression.lzss, .lzfse]
+ where candidate.isStillCompressed(payload) { return candidate }
+ return .none
+ }
+
+ /// Reassemble the container around a replacement IM4P.
+ func rebuilt(im4pBytes newIM4P: Data) throws -> Data {
+ guard isIMG4 else { return newIM4P }
+ var body = leading
+ body.append(newIM4P)
+ for element in trailing { body.append(element) }
+ var out = DER.sequenceHeader(bodyCount: body.count)
+ out.append(body)
+ return out
+ }
+ }
+}
+
+// MARK: - Minimal DER reader
+//
+// Enough of DER to walk an Image4 container and splice one element: tags
+// are single-byte here, lengths are definite. Img4tool's own DER helpers are
+// internal to that module, so this stays private to this file.
+
+private enum DER {
+ static let sequence: UInt8 = 0x30
+ static let ia5String: UInt8 = 0x16
+
+ static func contextConstructed(_ number: UInt8) -> UInt8 { 0xA0 | number }
+
+ struct Element {
+ let tag: UInt8
+ let valueRange: Range<Int>
+ let range: Range<Int>
+ }
+
+ static func parse(_ data: Data, at offset: Int) throws -> Element {
+ guard offset + 2 <= data.count else {
+ throw PatcherError.invalidFormat("DER truncated at \(offset)")
+ }
+ let tag = data[data.startIndex + offset]
+ let lengthByte = data[data.startIndex + offset + 1]
+ var cursor = offset + 2
+ let length: Int
+
+ if lengthByte & 0x80 == 0 {
+ length = Int(lengthByte)
+ } else {
+ let byteCount = Int(lengthByte & 0x7F)
+ guard byteCount > 0, byteCount <= 8, cursor + byteCount <= data.count else {
+ throw PatcherError.invalidFormat("DER length field at \(offset) is not definite")
+ }
+ var accumulated = 0
+ for index in 0 ..< byteCount {
+ accumulated = (accumulated << 8) | Int(data[data.startIndex + cursor + index])
+ }
+ length = accumulated
+ cursor += byteCount
+ }
+
+ guard cursor + length <= data.count else {
+ throw PatcherError.invalidFormat("DER element at \(offset) runs past the buffer")
+ }
+ return Element(
+ tag: tag,
+ valueRange: cursor ..< (cursor + length),
+ range: offset ..< (cursor + length)
+ )
+ }
+
+ static func children(_ data: Data, of element: Element) throws -> [Element] {
+ var out: [Element] = []
+ var offset = element.valueRange.lowerBound
+ while offset < element.valueRange.upperBound {
+ let child = try parse(data, at: offset)
+ out.append(child)
+ offset = child.range.upperBound
+ }
+ return out
+ }
+
+ static func raw(_ data: Data, _ element: Element) -> Data {
+ subdata(data, element.range)
+ }
+
+ static func value(_ data: Data, _ element: Element) -> Data {
+ subdata(data, element.valueRange)
+ }
+
+ static func string(_ data: Data, _ element: Element) -> String {
+ String(decoding: value(data, element), as: UTF8.self)
+ }
+
+ /// A SEQUENCE tag plus a minimal definite-length header.
+ static func sequenceHeader(bodyCount: Int) -> Data {
+ var out = Data([sequence])
+ if bodyCount < 0x80 {
+ out.append(UInt8(bodyCount))
+ return out
+ }
+ var bytes: [UInt8] = []
+ var remaining = bodyCount
+ while remaining > 0 {
+ bytes.append(UInt8(remaining & 0xFF))
+ remaining >>= 8
+ }
+ bytes.reverse()
+ out.append(0x80 | UInt8(bytes.count))
+ out.append(contentsOf: bytes)
+ return out
+ }
+
+ private static func subdata(_ data: Data, _ range: Range<Int>) -> Data {
+ let start = data.startIndex.advanced(by: range.lowerBound)
+ return Data(data[start ..< start.advanced(by: range.count)])
+ }
+}
+
+// MARK: - Little-endian append
+
+private extension Data {
+ mutating func append<T: FixedWidthInteger>(littleEndian value: T) {
+ Swift.withUnsafeBytes(of: value.littleEndian) { append(contentsOf: $0) }
+ }
+}
diff --git a/sources/FirmwarePatcher/DSC/DSCChunkSet.swift b/sources/FirmwarePatcher/DSC/DSCChunkSet.swift
new file mode 100644
index 00000000..c80c4ffa
--- /dev/null
+++ b/sources/FirmwarePatcher/DSC/DSCChunkSet.swift
@@ -0,0 +1,523 @@
+// DSCChunkSet.swift — Flat virtual-address access over a chunked dyld shared cache.
+//
+// The iOS 26/27 SystemOS cryptex ships the shared cache as many files:
+//
+// dyld_shared_cache_arm64e
+// dyld_shared_cache_arm64e.01
+// dyld_shared_cache_arm64e.02
+// ...
+// dyld_shared_cache_arm64e.75.dylddata
+// dyld_shared_cache_arm64e.77.dyldlinkedit
+//
+// Every one of them carries its own `dyld_cache_header` and its own mapping
+// table. The address ranges are disjoint across chunks, so together they are
+// one contiguous virtual address space. This type is the translation from an
+// address in that space to (file, offset), and back.
+//
+// It deliberately does not extract dylibs. Patchers want to read four bytes at
+// a vmaddr, decide something, and write four bytes back; anything more is the
+// symbol resolver's job.
+//
+// Port of `scripts/patchers/cfw_dsc_chunks.py`. The Python remains the
+// independent reference for this layer — see `DSCFoundationTests`.
+//
+// Two places diverge from it on purpose, both pinned by tests:
+//
+// * `bytes_at_vma` bounds-checks only its first byte and then reads `length`
+// raw bytes from the file, so a read near the end of a mapping comes back
+// padded with whatever follows — at 0x1800BBFFC on this cache, with the
+// chunk's own code signature. Here the whole span has to be addressable.
+// * `write_at_vma` compares only the chunk path, so it will write across a
+// mapping seam whether or not the file offsets continue across it. Here a
+// span may cross a seam only when the bytes behind it really are one run of
+// one file, which on this cache accepts every seam the Python accepts.
+
+import Foundation
+
+/// A half-open span of virtual addresses that was written, or is about to be.
+///
+/// Re-attestation consumes these rather than bare addresses. An address alone
+/// cannot say how many 16 KiB pages a write dirtied, and a caller that writes
+/// eight bytes across a page boundary and then re-attests the one address it
+/// started at leaves the second page's code slot stale — a
+/// `KERN_PROTECTION_FAILURE` on the first demand-page-in, with nothing pointing
+/// back at the patch. Carrying the length is what makes that unexpressible.
+public struct DSCWriteSpan: Sendable, Hashable {
+ /// First address the span covers.
+ public let vma: UInt64
+ /// Byte length. Always at least 1.
+ public let length: Int
+
+ public init(vma: UInt64, length: Int) {
+ precondition(length > 0, "a write span covers at least one byte")
+ self.vma = vma
+ self.length = length
+ }
+
+ /// The single byte at `vma` — the only honest way to spell "just this
+ /// address", and it has to be spelled out.
+ public static func byte(at vma: UInt64) -> DSCWriteSpan {
+ DSCWriteSpan(vma: vma, length: 1)
+ }
+
+ /// Last address the span covers.
+ public var lastVMA: UInt64 { vma &+ UInt64(length - 1) }
+ /// One past the last address the span covers.
+ public var endVMA: UInt64 { vma &+ UInt64(length) }
+}
+
+/// Random-access byte view over a chunked dyld shared cache.
+public final class DSCChunkSet {
+ /// One `dyld_cache_mapping_info` entry, tagged with the chunk it came from.
+ public struct Mapping: Sendable {
+ /// First address the mapping covers.
+ public let address: UInt64
+ /// Byte length of the mapping.
+ public let size: UInt64
+ /// Offset of `address` within `chunkURL`.
+ public let fileOffset: UInt64
+ public let maxProt: UInt32
+ /// VM_PROT mask: read 1, write 2, execute 4.
+ public let initProt: UInt32
+ public let chunkURL: URL
+
+ /// One past the last address the mapping covers.
+ public var endAddress: UInt64 { address &+ size }
+
+ public var isExecutable: Bool { initProt & DSCChunkSet.vmProtExecute != 0 }
+ }
+
+ public static let vmProtExecute: UInt32 = 4
+
+ /// Directory holding the chunk files.
+ public let directory: URL
+ /// Chunk files, in the order they are enumerated (base file, then `.NN`).
+ public let chunkURLs: [URL]
+ /// Every mapping across every chunk, sorted by start address.
+ public let mappings: [Mapping]
+
+ private let architecture: String
+
+ /// Guards the two pieces of lazily built state below.
+ private let stateLock = NSLock()
+ private var writeLog: [DSCWriteSpan] = []
+ private var loadedLocalSymbols: DSCLocalSymbolTable?
+
+ // MARK: - Construction
+
+ /// Open the cache under `directory`.
+ ///
+ /// - Parameters:
+ /// - directory: the directory holding `dyld_shared_cache_<arch>*`.
+ /// - architecture: cache architecture suffix; `arm64e` for every device
+ /// this project targets.
+ public init(directory: URL, architecture: String = "arm64e") throws {
+ self.directory = directory
+ self.architecture = architecture
+ chunkURLs = try Self.enumerateChunks(in: directory, architecture: architecture)
+ guard !chunkURLs.isEmpty else {
+ throw DSCError.noChunksFound(directory: directory.path)
+ }
+
+ var collected: [Mapping] = []
+ for url in chunkURLs {
+ for mapping in Self.parseMappings(of: url) where mapping.size != 0 {
+ collected.append(mapping)
+ }
+ }
+ guard !collected.isEmpty else {
+ throw DSCError.noMappingsParsed(directory: directory.path)
+ }
+ collected.sort { $0.address < $1.address }
+ mappings = collected
+ }
+
+ /// The unsuffixed chunk, which carries the cache-wide header (image list,
+ /// sub-cache table, local-symbols pointer).
+ public var mainCacheURL: URL {
+ directory.appendingPathComponent("dyld_shared_cache_\(architecture)")
+ }
+
+ /// The `.symbols` side file holding the stripped local symbol table.
+ public var localSymbolsURL: URL {
+ directory.appendingPathComponent("dyld_shared_cache_\(architecture).symbols")
+ }
+
+ /// Lowest and highest address the cache covers.
+ public var addressRange: Range<UInt64> {
+ (mappings.first?.address ?? 0) ..< (mappings.map(\.endAddress).max() ?? 0)
+ }
+
+ // MARK: - Address translation
+
+ /// Locate `vma`'s byte in its chunk file.
+ ///
+ /// Returns `nil` when no mapping covers the address. Only the first byte is
+ /// checked — use `fileRange(of:)` when a whole span has to be addressable.
+ public func findChunk(forVMA vma: UInt64) -> (chunkURL: URL, fileOffset: Int)? {
+ guard let mapping = mapping(forVMA: vma) else { return nil }
+ return (mapping.chunkURL, Int(mapping.fileOffset &+ (vma &- mapping.address)))
+ }
+
+ /// The mapping covering `vma`, if any.
+ public func mapping(forVMA vma: UInt64) -> Mapping? {
+ mappingIndex(forVMA: vma).map { mappings[$0] }
+ }
+
+ private func mappingIndex(forVMA vma: UInt64) -> Int? {
+ // Mappings are disjoint and sorted, so the candidate is the last one
+ // that starts at or below `vma`.
+ var low = 0
+ var high = mappings.count
+ while low < high {
+ let mid = (low + high) / 2
+ if mappings[mid].address <= vma { low = mid + 1 } else { high = mid }
+ }
+ guard low > 0 else { return nil }
+ return vma < mappings[low - 1].endAddress ? low - 1 : nil
+ }
+
+ /// The unbroken run of chunk-file bytes that starts at `vma`.
+ ///
+ /// A span is addressable when the bytes behind it are one contiguous run of
+ /// one file. Usually that means one mapping, but neighbouring mappings of
+ /// the same chunk are often contiguous in address *and* in file offset — on
+ /// the 24A435 arm64e cache 19 of the 62 adjacent mapping pairs are, all of
+ /// them inside a single chunk — and a read or write that crosses such a
+ /// seam is still reading or writing exactly the right bytes. A seam where
+ /// either the file offsets or the chunk files break is a different story,
+ /// and stops the run.
+ ///
+ /// - Returns: the chunk file, the offset of `vma` in it, and how many bytes
+ /// follow before the run ends. `nil` when `vma` is not mapped at all.
+ func contiguousRun(from vma: UInt64) -> (chunkURL: URL, fileOffset: UInt64, available: UInt64)? {
+ guard var index = mappingIndex(forVMA: vma) else { return nil }
+ let first = mappings[index]
+ var available = first.endAddress &- vma
+ while index + 1 < mappings.count {
+ let current = mappings[index]
+ let next = mappings[index + 1]
+ guard next.chunkURL == current.chunkURL,
+ next.address == current.endAddress,
+ next.fileOffset == current.fileOffset &+ current.size
+ else { break }
+ available &+= next.size
+ index += 1
+ }
+ return (first.chunkURL, first.fileOffset &+ (vma &- first.address), available)
+ }
+
+ /// Where `span` lives in its chunk file.
+ ///
+ /// Throws when the first byte is unmapped, and when the span runs off the
+ /// end of its contiguous run — the case where the following bytes in the
+ /// file belong to some other virtual address, or to none at all.
+ public func fileRange(of span: DSCWriteSpan) throws -> (chunkURL: URL, range: Range<Int>) {
+ guard let run = contiguousRun(from: span.vma) else {
+ throw DSCError.addressNotMapped(span.vma)
+ }
+ guard UInt64(span.length) <= run.available else {
+ throw DSCError.addressSpanCrossesChunk(vma: span.vma, length: span.length)
+ }
+ let start = Int(run.fileOffset)
+ return (run.chunkURL, start ..< (start + span.length))
+ }
+
+ // MARK: - Reading
+
+ /// Read `length` bytes at `vma`. The whole span must be addressable.
+ ///
+ /// This is stricter than `cfw_dsc_chunks.bytes_at_vma`, deliberately. The
+ /// Python bounds-checks only the first byte and then reads `length` raw
+ /// bytes from the file, so a read that starts near the end of a mapping
+ /// comes back padded with whatever happens to follow — on this cache,
+ /// asking for 64 bytes at 0x1800BBFFC returns 60 bytes of the chunk's own
+ /// `CS_SuperBlob` dressed up as code. That is silent wrong data on a read
+ /// API, so here it throws.
+ public func bytesAtVMA(_ vma: UInt64, length: Int) throws -> Data {
+ guard length > 0 else { return Data() }
+ let (chunkURL, range) = try fileRange(of: DSCWriteSpan(vma: vma, length: length))
+ let data = try Self.read(url: chunkURL, offset: UInt64(range.lowerBound), length: length)
+ guard data.count == length else {
+ throw DSCError.shortRead(vma: vma, wanted: length, got: data.count)
+ }
+ return data
+ }
+
+ /// Read up to `length` bytes at `vma`.
+ ///
+ /// With `allowShort` set, a span that would run past the end of what is
+ /// addressable comes back truncated instead of throwing — what a
+ /// load-command walk wants when it asks for "the next 64 KiB, however much
+ /// of it exists".
+ public func readAtVMA(_ vma: UInt64, length: Int, allowShort: Bool = false) throws -> Data {
+ guard length > 0 else { return Data() }
+ guard let run = contiguousRun(from: vma) else {
+ throw DSCError.addressNotMapped(vma)
+ }
+ let wanted: Int
+ if run.available >= UInt64(length) {
+ wanted = length
+ } else if allowShort {
+ wanted = Int(run.available)
+ } else {
+ throw DSCError.addressSpanCrossesChunk(vma: vma, length: length)
+ }
+ return try Self.read(url: run.chunkURL, offset: run.fileOffset, length: wanted)
+ }
+
+ // MARK: - Writing
+
+ /// Write `data` at `vma`, straight through to the chunk that holds it, and
+ /// record the span so it can be re-attested.
+ ///
+ /// The whole span has to be addressable as one run of one chunk file. A
+ /// write that would straddle two chunks is refused rather than split: the
+ /// second chunk's bytes are a different file with a different code
+ /// directory, and silently writing half a patch is worse than not writing
+ /// it.
+ ///
+ /// - Returns: the span written, which is what
+ /// `DSCCodeSignature.reattest(in:modifiedSpans:)` consumes. The same span
+ /// is appended to `recordedWrites`, so a patcher that just writes and
+ /// then calls `reattestRecordedWrites(in:)` cannot under-attest. Empty
+ /// `data` writes nothing and records nothing; the span it hands back is
+ /// the single byte at `vma`, and re-attesting it is a no-op.
+ @discardableResult
+ public func write(at vma: UInt64, _ data: Data) throws -> DSCWriteSpan {
+ guard !data.isEmpty else { return DSCWriteSpan.byte(at: vma) }
+ let span = DSCWriteSpan(vma: vma, length: data.count)
+ let (chunkURL, range) = try fileRange(of: span)
+ let handle = try FileHandle(forUpdating: chunkURL)
+ defer { try? handle.close() }
+ try handle.seek(toOffset: UInt64(range.lowerBound))
+ try handle.write(contentsOf: data)
+ stateLock.withLock { writeLog.append(span) }
+ return span
+ }
+
+ /// Every span `write(at:_:)` has put on disk through this chunk set, oldest
+ /// first.
+ public var recordedWrites: [DSCWriteSpan] {
+ stateLock.withLock { writeLog }
+ }
+
+ /// Forget the recorded writes — for a caller that re-attests in batches and
+ /// does not want the next batch to redo the previous one's pages.
+ public func clearRecordedWrites() {
+ stateLock.withLock { writeLog.removeAll() }
+ }
+
+ // MARK: - Local symbols
+
+ /// The cache's `.symbols` local symbol table, parsed once and kept.
+ ///
+ /// Parsed directly rather than shelled out to `ipsw dyld symaddr`, which
+ /// times out on a cache this size. The table is big — 1.2 GB resident on
+ /// the 24A435 arm64e cache — so it is loaded at most once per chunk set and
+ /// can be dropped again with `unloadLocalSymbolTable()`.
+ ///
+ /// Throws when the side file is missing or unparseable. That is the whole
+ /// point of it throwing: "the symbol table is not there" and "that symbol
+ /// is not in it" are different answers, and the previous `try?` spelled
+ /// both of them `nil`.
+ public func localSymbolTable() throws -> DSCLocalSymbolTable {
+ try stateLock.withLock {
+ if let loadedLocalSymbols { return loadedLocalSymbols }
+ guard FileManager.default.fileExists(atPath: localSymbolsURL.path) else {
+ throw DSCError.localSymbolsMissing(path: localSymbolsURL.path)
+ }
+ let table = try DSCLocalSymbolTable(url: localSymbolsURL)
+ loadedLocalSymbols = table
+ return table
+ }
+ }
+
+ /// Drop the cached local symbol table and its ~1.2 GB of buffers.
+ public func unloadLocalSymbolTable() {
+ stateLock.withLock { loadedLocalSymbols = nil }
+ }
+
+ /// Resolve `name` to its address through the cache's own `.symbols` table.
+ ///
+ /// Returns the first match, matching the Python reference; local symbol
+ /// names are not guaranteed unique across images, so callers that care
+ /// which image a symbol came from should use `DSCSymbolResolver` instead.
+ ///
+ /// `nil` means "no symbol by that name". A missing or unreadable table
+ /// throws instead, so a force-kern discovery run cannot report "zero pairs"
+ /// when what actually happened is that the table was not there.
+ public func resolveLocalSymbol(_ name: String) throws -> UInt64? {
+ try localSymbolTable().firstAddress(of: name)
+ }
+
+ // MARK: - Search helpers
+
+ /// Every address at which `needle` appears in an executable mapping,
+ /// anchored at the mapping start or just after a NUL.
+ ///
+ /// Restricted to RX mappings, which is where `__TEXT,__cstring` lives. That
+ /// skips LINKEDIT and the `__DATA` mappings, which between them are most of
+ /// the cache's bytes and none of its C strings.
+ public func findStringVMAs(_ needle: Data) throws -> [UInt64] {
+ guard !needle.isEmpty else { return [] }
+ var results: [UInt64] = []
+ for mapping in mappings where mapping.isExecutable {
+ let buffer = try Self.read(
+ url: mapping.chunkURL,
+ offset: mapping.fileOffset,
+ length: Int(mapping.size)
+ )
+ var searchFrom = buffer.startIndex
+ while searchFrom < buffer.endIndex,
+ let found = buffer.range(of: needle, in: searchFrom ..< buffer.endIndex)
+ {
+ let position = found.lowerBound - buffer.startIndex
+ if position == 0 || buffer[buffer.startIndex + position - 1] == 0 {
+ results.append(mapping.address &+ UInt64(position))
+ }
+ searchFrom = found.lowerBound + 1
+ }
+ }
+ return results
+ }
+
+ private static let machOMagic64LE = Data([0xCF, 0xFA, 0xED, 0xFE])
+
+ /// Walk back from `vma` to the start of the Mach-O image that contains it.
+ ///
+ /// Images in the cache start on a page boundary at the head of their
+ /// `__TEXT`, and an arm64e dylib's header shares a mapping with its
+ /// `__text`, so the search never has to leave the containing mapping.
+ public func findMachOHeaderBefore(
+ _ vma: UInt64,
+ maxWalk: Int = 64 * 1024 * 1024
+ ) throws -> UInt64? {
+ guard let mapping = mapping(forVMA: vma) else { return nil }
+ let localOffset = Int(vma &- mapping.address)
+ let scanLength = min(localOffset, maxWalk)
+ let scanStart = localOffset - scanLength
+ // +4 so a header sitting right at the scan's end is still matched.
+ let buffer = try Self.read(
+ url: mapping.chunkURL,
+ offset: mapping.fileOffset &+ UInt64(scanStart),
+ length: scanLength + 4
+ )
+ var searchEnd = buffer.endIndex
+ while searchEnd > buffer.startIndex,
+ let found = buffer.range(
+ of: Self.machOMagic64LE,
+ options: .backwards,
+ in: buffer.startIndex ..< searchEnd
+ )
+ {
+ let position = found.lowerBound - buffer.startIndex
+ let candidate = mapping.address &+ UInt64(scanStart + position)
+ if candidate & 0xFFF == 0 { return candidate }
+ searchEnd = found.lowerBound
+ }
+ return nil
+ }
+
+ /// The `LC_ID_DYLIB` install name of the image whose header is at
+ /// `headerVMA`, or `nil` when that address is not a dylib header.
+ public func readInstallName(atHeaderVMA headerVMA: UInt64) -> String? {
+ guard let head = try? readAtVMA(headerVMA, length: 64 * 1024, allowShort: true),
+ head.count >= 32,
+ head.loadLE(UInt32.self, at: 0) == 0xFEED_FACF
+ else { return nil }
+
+ let commandCount = head.loadLE(UInt32.self, at: 16)
+ let commandsSize = head.loadLE(UInt32.self, at: 20)
+ guard commandCount <= 4096, commandsSize <= 64 * 1024 else { return nil }
+
+ var offset = 32
+ for _ in 0 ..< commandCount {
+ guard offset + 8 <= head.count else { return nil }
+ let command = head.loadLE(UInt32.self, at: offset)
+ let commandSize = Int(head.loadLE(UInt32.self, at: offset + 4))
+ guard commandSize >= 8, commandSize <= 64 * 1024 else { return nil }
+ if command == 0xD { // LC_ID_DYLIB
+ let nameOffset = Int(head.loadLE(UInt32.self, at: offset + 8))
+ let nameStart = offset + nameOffset
+ guard nameStart < head.count, nameStart < offset + commandSize else { return nil }
+ let limit = min(head.count, offset + commandSize)
+ var end = nameStart
+ while end < limit, head[head.startIndex + end] != 0 { end += 1 }
+ let bytes = head[(head.startIndex + nameStart) ..< (head.startIndex + end)]
+ return String(decoding: bytes, as: UTF8.self)
+ }
+ offset += commandSize
+ if offset > Int(commandsSize) + 32 { return nil }
+ }
+ return nil
+ }
+
+ // MARK: - Chunk enumeration and header parsing
+
+ static func enumerateChunks(in directory: URL, architecture: String) throws -> [URL] {
+ let prefix = "dyld_shared_cache_\(architecture)"
+ let names = try FileManager.default
+ .contentsOfDirectory(atPath: directory.path)
+ .filter { $0.hasPrefix(prefix) }
+ .filter { !$0.hasSuffix(".symbols") && !$0.hasSuffix(".map") }
+
+ // Base file first, then numerically by sub-cache index. Files whose
+ // suffix is not a bare number (`.75.dylddata`, `.atlas`) sort after,
+ // by name — they still carry mappings and must not be dropped.
+ func sortKey(_ name: String) -> (Int, Int, String) {
+ if name == prefix { return (0, -1, name) }
+ let suffix = name.dropFirst(prefix.count)
+ guard suffix.hasPrefix(".") else { return (1, 0, name) }
+ let rest = suffix.dropFirst()
+ if let index = Int(rest), !rest.isEmpty { return (0, index, name) }
+ return (1, 0, name)
+ }
+ return names
+ .sorted { sortKey($0) < sortKey($1) }
+ .map { directory.appendingPathComponent($0) }
+ }
+
+ /// Parse one chunk's `dyld_cache_mapping_info` table.
+ ///
+ /// Slide-info mappings (`mappingWithSlideOffset`) are left alone: which
+ /// address comes from which file offset is fully covered by the standard
+ /// mappings, and that is all this layer claims to know.
+ static func parseMappings(of url: URL) -> [Mapping] {
+ guard let head = try? read(url: url, offset: 0, length: 0x100), head.count >= 24 else {
+ return []
+ }
+ guard head.prefix(4) == Data("dyld".utf8) else { return [] }
+
+ let mappingOffset = head.loadLE(UInt32.self, at: 16)
+ let mappingCount = head.loadLE(UInt32.self, at: 20)
+ // Sanity bounds — a mis-parsed header must not turn into a huge read.
+ guard mappingCount <= 64, mappingOffset <= 0x10000 else { return [] }
+
+ guard let raw = try? read(
+ url: url,
+ offset: UInt64(mappingOffset),
+ length: Int(mappingCount) * 32
+ ), raw.count == Int(mappingCount) * 32 else { return [] }
+
+ return (0 ..< Int(mappingCount)).map { index in
+ let base = index * 32
+ return Mapping(
+ address: raw.loadLE(UInt64.self, at: base),
+ size: raw.loadLE(UInt64.self, at: base + 8),
+ fileOffset: raw.loadLE(UInt64.self, at: base + 16),
+ maxProt: raw.loadLE(UInt32.self, at: base + 24),
+ initProt: raw.loadLE(UInt32.self, at: base + 28),
+ chunkURL: url
+ )
+ }
+ }
+
+ static func read(url: URL, offset: UInt64, length: Int) throws -> Data {
+ guard length > 0 else { return Data() }
+ let handle = try FileHandle(forReadingFrom: url)
+ defer { try? handle.close() }
+ try handle.seek(toOffset: offset)
+ return try handle.read(upToCount: length) ?? Data()
+ }
+}
diff --git a/sources/FirmwarePatcher/DSC/DSCCodeSignature.swift b/sources/FirmwarePatcher/DSC/DSCCodeSignature.swift
new file mode 100644
index 00000000..c0728aa4
--- /dev/null
+++ b/sources/FirmwarePatcher/DSC/DSCCodeSignature.swift
@@ -0,0 +1,474 @@
+// DSCCodeSignature.swift — Page-hash re-signing for dyld shared cache chunks.
+//
+// Why this exists
+// ---------------
+// On iPhone17,3 / iOS 26+ the kernel runs with `codeSigningMonitor == 2`: it
+// hands per-page hash validation to TXM, and TXM holds the slot hashes the
+// cache was registered with. So a byte changed inside an executable mapping
+// does not fail at patch time, or at boot; it fails the first time that 16 KiB
+// page is demand-paged in, as a `KERN_PROTECTION_FAILURE` / SIGKILL on
+// whichever process touched it. Every DSC edit has to be followed by re-hashing
+// the affected page's slot, or the guest panics on a page fault nobody can
+// trace back to the patch.
+//
+// This is the DSC path and it is not the Mach-O path
+// --------------------------------------------------
+// The two must not share an implementation. Here:
+//
+// * the signature is found through the chunk header's
+// `codeSignatureOffset` @0x28 / `codeSignatureSize` @0x30 — a DSC image
+// carries no `LC_CODE_SIGNATURE` of its own, only the chunk-level one
+// * pages are 16 KiB (`pageSize` log2 == 14), not 4 KiB
+// * there is a single code directory, no alternate SHA-1 CD to skip past
+// * chunks are page-aligned, so `nCodeSlots * pageSize == codeLimit` and
+// there is no short tail slot. The independent Mach-O path does have one,
+// and getting it wrong is what regressed re-signing once already.
+//
+// Side effect, by design
+// ----------------------
+// Rewriting slot hashes changes the code directory's contents and therefore its
+// cdHash. That is only survivable because the JB kernel patch
+// `patch_amfi_cdhash_in_trustcache` — `KernelJBPatchAmfiTrustcache` in this
+// repo — short-circuits AMFI's per-image trust-cache lookup to return 1. This
+// file must not be used on a firmware that does not carry that patch.
+//
+// Port of `scripts/patchers/cfw_dsc_codesign.py`, which stays the independent
+// reference for the slot hashes computed here.
+//
+// It is not a port of how the reference chooses *which* pages to hash. The
+// Python takes bare addresses and hashes one page each, so a write that crosses
+// a 16 KiB boundary leaves the following page's slot stale and still reports
+// success — reproduced on the 24A435 cache with an 8-byte write at
+// 0x22AC0FFFC, which dirties pages 2563 and 2564 and gets 2563 re-signed. The
+// six sites `cfw_patch_camera_dsc.py` writes miss that by 1072 bytes, so the
+// reference is safe by margin rather than by construction. Here the page set is
+// derived from the spans that were actually written, and `DSCChunkSet` records
+// those itself.
+
+import CryptoKit
+import Foundation
+
+/// The `CS_CodeDirectory` of one chunk, reduced to what re-signing needs.
+public struct DSCChunkCodeDirectory: Sendable {
+ /// Offset of the CD blob within the chunk file.
+ public let blobOffset: Int
+ /// Byte length of the CD blob.
+ public let blobLength: Int
+ /// Offset of slot 0 within the CD blob.
+ public let hashOffset: Int
+ /// Bytes per slot — 32 for SHA-256.
+ public let hashSize: Int
+ /// Number of code slots.
+ public let codeSlotCount: Int
+ /// Chunk byte range the signature covers.
+ public let codeLimit: Int
+ /// Bytes per slot's page — 16384 on this cache.
+ public let pageSize: Int
+
+ /// Chunk-file offset of slot `index`'s hash.
+ public func slotOffset(forPage index: Int) -> Int {
+ blobOffset + hashOffset + index * hashSize
+ }
+}
+
+/// One slot rewritten, for logging and for cross-checking against the Python.
+public struct DSCSlotReattestation: Sendable {
+ public let chunkURL: URL
+ public let pageIndex: Int
+ /// Offset of the page's first byte in the chunk file.
+ public let chunkOffset: Int
+ /// Offset of the slot hash in the chunk file.
+ public let slotOffset: Int
+ public let hashBefore: Data
+ public let hashAfter: Data
+}
+
+/// One page of one chunk.
+public struct DSCPageReference: Sendable, Hashable {
+ public let chunkURL: URL
+ public let pageIndex: Int
+}
+
+/// A page that re-attestation could not cover, and why.
+///
+/// Every one of these used to be an early `continue` that produced no record
+/// and, under the default `log: nil`, no output either — so "I skipped it" came
+/// back looking exactly like "there was nothing to do". The Python reference
+/// prints each one, and so does this, but the caller also gets them as values
+/// rather than as text it would have to have been listening for.
+public struct DSCReattestationSkip: Sendable {
+ public enum Reason: Sendable, CustomStringConvertible {
+ case addressNotMapped(vma: UInt64)
+ case spanNotAddressable(vma: UInt64, length: Int)
+ case chunkHasNoCodeDirectory(chunk: String)
+ case pageBeyondCodeSlots(chunk: String, page: Int, codeSlotCount: Int)
+ case pageBeyondCodeLimit(chunk: String, page: Int, codeLimit: Int)
+ case shortPageRead(chunk: String, page: Int, got: Int, wanted: Int)
+
+ public var description: String {
+ switch self {
+ case let .addressNotMapped(vma):
+ "vma 0x\(String(vma, radix: 16, uppercase: true)) not mapped in any chunk"
+ case let .spanNotAddressable(vma, length):
+ "span at vma 0x\(String(vma, radix: 16, uppercase: true)) length \(length) "
+ + "runs past the end of its chunk"
+ case let .chunkHasNoCodeDirectory(chunk):
+ "chunk \(chunk) has no recognised CS_SuperBlob/CD"
+ case let .pageBeyondCodeSlots(chunk, page, codeSlotCount):
+ "page \(page) of \(chunk) is past nCodeSlots (\(codeSlotCount))"
+ case let .pageBeyondCodeLimit(chunk, page, codeLimit):
+ "page \(page) of \(chunk) overruns codeLimit "
+ + "(0x\(String(codeLimit, radix: 16, uppercase: true)))"
+ case let .shortPageRead(chunk, page, got, wanted):
+ "short read at page \(page) of \(chunk) (got \(got) of \(wanted))"
+ }
+ }
+ }
+
+ public let reason: Reason
+ public var description: String { reason.description }
+}
+
+/// What one re-attestation run did.
+///
+/// Three outcomes that used to share the empty array are separate here: no
+/// pages were eligible, every page already matched, and some pages were
+/// skipped. A caller that wants "the patch is fully covered" should check
+/// `isFullyAttested`.
+public struct DSCReattestation: Sendable {
+ /// Slots whose stored hash was changed (or, on a dry run, would have been).
+ public let updated: [DSCSlotReattestation]
+ /// Pages whose stored slot already matched what the page hashes to.
+ public let alreadyAttested: [DSCPageReference]
+ /// Pages that could not be covered at all.
+ public let skipped: [DSCReattestationSkip]
+
+ /// Pages the run actually reached — rewritten plus already-correct.
+ public var pagesAttested: Int { updated.count + alreadyAttested.count }
+
+ /// True when every page the caller's spans touched now carries a slot hash
+ /// that matches its contents. False the moment anything was skipped.
+ public var isFullyAttested: Bool { skipped.isEmpty }
+
+ public var summary: String {
+ "\(updated.count) slot(s) rewritten, \(alreadyAttested.count) already correct, "
+ + "\(skipped.count) skipped"
+ }
+}
+
+public enum DSCCodeSignature {
+ static let superBlobMagic: UInt32 = 0xFADE_0CC0
+ static let codeDirectoryMagic: UInt32 = 0xFADE_0C02
+ static let codeDirectorySlot: UInt32 = 0
+ static let hashTypeSHA256: UInt8 = 2
+
+ // MARK: - Reading the chunk's code directory
+
+ /// Locate a chunk's `CS_CodeDirectory`.
+ ///
+ /// Returns `nil` — rather than throwing — when the chunk simply has no
+ /// signature to update. Several chunks in a cache are like that, and a
+ /// patch that lands in one of them is not an error.
+ public static func readCodeDirectory(ofChunk url: URL) throws -> DSCChunkCodeDirectory? {
+ let head = try DSCChunkSet.read(url: url, offset: 0, length: 0x100)
+ guard head.count >= 0x38, head.prefix(5) == Data("dyld_".utf8) else { return nil }
+
+ let signatureOffset = head.loadLE(UInt64.self, at: 0x28)
+ let signatureSize = head.loadLE(UInt64.self, at: 0x30)
+ guard signatureOffset != 0, signatureSize != 0 else { return nil }
+
+ // CS_SuperBlob, big-endian.
+ let superHead = try DSCChunkSet.read(url: url, offset: signatureOffset, length: 12)
+ guard superHead.count == 12 else { return nil }
+ guard superHead.loadBE(UInt32.self, at: 0) == superBlobMagic else { return nil }
+ let superLength = superHead.loadBE(UInt32.self, at: 4)
+ let blobCount = superHead.loadBE(UInt32.self, at: 8)
+ guard UInt64(superLength) <= signatureSize, blobCount <= 256 else { return nil }
+
+ let indexData = try DSCChunkSet.read(
+ url: url,
+ offset: signatureOffset + 12,
+ length: Int(blobCount) * 8
+ )
+ guard indexData.count == Int(blobCount) * 8 else { return nil }
+
+ var directoryOffsetInSuperBlob: UInt32?
+ for index in 0 ..< Int(blobCount) {
+ let slotType = indexData.loadBE(UInt32.self, at: index * 8)
+ if slotType == codeDirectorySlot {
+ directoryOffsetInSuperBlob = indexData.loadBE(UInt32.self, at: index * 8 + 4)
+ break
+ }
+ }
+ guard let directoryOffsetInSuperBlob else { return nil }
+ let blobOffset = signatureOffset + UInt64(directoryOffsetInSuperBlob)
+
+ // CS_CodeDirectory, big-endian.
+ let directoryHead = try DSCChunkSet.read(url: url, offset: blobOffset, length: 44)
+ guard directoryHead.count == 44 else { return nil }
+ guard directoryHead.loadBE(UInt32.self, at: 0) == codeDirectoryMagic else { return nil }
+
+ let blobLength = Int(directoryHead.loadBE(UInt32.self, at: 4))
+ let hashOffset = Int(directoryHead.loadBE(UInt32.self, at: 16))
+ let codeSlotCount = Int(directoryHead.loadBE(UInt32.self, at: 28))
+ let codeLimit = Int(directoryHead.loadBE(UInt32.self, at: 32))
+ let hashSize = Int(directoryHead[directoryHead.startIndex + 36])
+ let hashType = directoryHead[directoryHead.startIndex + 37]
+ let pageSizeLog2 = directoryHead[directoryHead.startIndex + 39]
+
+ // Only SHA-256 slots are recomputable here. A cache signed with
+ // anything else needs its own code path, and guessing would write
+ // 32 bytes of the wrong digest into a 20-byte slot.
+ guard hashType == hashTypeSHA256, hashSize == 32 else { return nil }
+ let pageSize = 1 << Int(pageSizeLog2)
+ guard pageSize > 0, pageSize <= (1 << 20) else { return nil }
+
+ return DSCChunkCodeDirectory(
+ blobOffset: Int(blobOffset),
+ blobLength: blobLength,
+ hashOffset: hashOffset,
+ hashSize: hashSize,
+ codeSlotCount: codeSlotCount,
+ codeLimit: codeLimit,
+ pageSize: pageSize
+ )
+ }
+
+ // MARK: - Re-signing
+
+ /// Where diagnostics go when the caller does not say.
+ ///
+ /// `cfw_dsc_codesign.reattest_modified_pages` defaults to `verbose=True`
+ /// and prints every skip it makes. Defaulting this to `nil` was how the
+ /// port lost that: an unmapped address, an unsigned chunk and an empty
+ /// input all came back as an empty array with nothing written anywhere.
+ /// Callers that really want silence pass `log: nil` and read the returned
+ /// `DSCReattestation` instead.
+ public static let stderrLog: @Sendable (String) -> Void = { line in
+ FileHandle.standardError.write(Data((line + "\n").utf8))
+ }
+
+ /// Recompute and store the slot hash of every 16 KiB page any of
+ /// `modifiedSpans` touched.
+ ///
+ /// Spans, not addresses, on purpose. A span knows its length, so an 8-byte
+ /// write four bytes before a page boundary dirties two pages and both get
+ /// re-hashed. The address-only version of this could not know that and
+ /// silently left the second page stale — a `KERN_PROTECTION_FAILURE` the
+ /// first time the guest demand-paged it in.
+ ///
+ /// Pages are coalesced, so patching four sites in one page costs one hash.
+ /// A page whose stored slot already matches what the page hashes to is left
+ /// alone and reported in `alreadyAttested`, which is what makes a second
+ /// run over an already-patched cache a no-op rather than a rewrite.
+ @discardableResult
+ public static func reattest(
+ in chunks: DSCChunkSet,
+ modifiedSpans: some Sequence<DSCWriteSpan>,
+ dryRun: Bool = false,
+ log: ((String) -> Void)? = stderrLog
+ ) throws -> DSCReattestation {
+ var pagesByChunk: [URL: Set<Int>] = [:]
+ var directories: [URL: DSCChunkCodeDirectory?] = [:]
+ var skipped: [DSCReattestationSkip] = []
+
+ func skip(_ reason: DSCReattestationSkip.Reason) {
+ skipped.append(DSCReattestationSkip(reason: reason))
+ log?(" [-] re-attest: \(reason) — skipping")
+ }
+
+ for span in modifiedSpans {
+ let chunkURL: URL
+ let byteRange: Range<Int>
+ do {
+ (chunkURL, byteRange) = try chunks.fileRange(of: span)
+ } catch DSCError.addressNotMapped {
+ skip(.addressNotMapped(vma: span.vma))
+ continue
+ } catch DSCError.addressSpanCrossesChunk {
+ skip(.spanNotAddressable(vma: span.vma, length: span.length))
+ continue
+ }
+
+ let directory: DSCChunkCodeDirectory?
+ if let cached = directories[chunkURL] {
+ directory = cached
+ } else {
+ directory = try readCodeDirectory(ofChunk: chunkURL)
+ directories[chunkURL] = directory
+ if directory == nil {
+ skip(.chunkHasNoCodeDirectory(chunk: chunkURL.lastPathComponent))
+ }
+ }
+ guard let directory else { continue }
+
+ // Every page the span's bytes land in, not just the first.
+ let firstPage = byteRange.lowerBound / directory.pageSize
+ let lastPage = (byteRange.upperBound - 1) / directory.pageSize
+ for pageIndex in firstPage ... lastPage {
+ guard pageIndex < directory.codeSlotCount else {
+ skip(.pageBeyondCodeSlots(
+ chunk: chunkURL.lastPathComponent,
+ page: pageIndex,
+ codeSlotCount: directory.codeSlotCount
+ ))
+ continue
+ }
+ guard (pageIndex + 1) * directory.pageSize <= directory.codeLimit else {
+ skip(.pageBeyondCodeLimit(
+ chunk: chunkURL.lastPathComponent,
+ page: pageIndex,
+ codeLimit: directory.codeLimit
+ ))
+ continue
+ }
+ pagesByChunk[chunkURL, default: []].insert(pageIndex)
+ }
+ }
+
+ guard !pagesByChunk.isEmpty else {
+ log?(
+ " [.] re-attest: no eligible pages "
+ + "(\(skipped.count) skipped)"
+ )
+ return DSCReattestation(updated: [], alreadyAttested: [], skipped: skipped)
+ }
+
+ var records: [DSCSlotReattestation] = []
+ var alreadyAttested: [DSCPageReference] = []
+ for chunkURL in pagesByChunk.keys.sorted(by: { $0.path < $1.path }) {
+ guard let directory = directories[chunkURL] ?? nil else { continue }
+ let handle = dryRun
+ ? try FileHandle(forReadingFrom: chunkURL)
+ : try FileHandle(forUpdating: chunkURL)
+ defer { try? handle.close() }
+
+ for pageIndex in pagesByChunk[chunkURL, default: []].sorted() {
+ let pageOffset = pageIndex * directory.pageSize
+ let slotOffset = directory.slotOffset(forPage: pageIndex)
+
+ try handle.seek(toOffset: UInt64(pageOffset))
+ let pageData = try handle.read(upToCount: directory.pageSize) ?? Data()
+ guard pageData.count == directory.pageSize else {
+ skip(.shortPageRead(
+ chunk: chunkURL.lastPathComponent,
+ page: pageIndex,
+ got: pageData.count,
+ wanted: directory.pageSize
+ ))
+ continue
+ }
+ let newHash = Data(SHA256.hash(data: pageData))
+
+ try handle.seek(toOffset: UInt64(slotOffset))
+ let oldHash = try handle.read(upToCount: directory.hashSize) ?? Data()
+
+ guard oldHash != newHash else {
+ alreadyAttested.append(
+ DSCPageReference(chunkURL: chunkURL, pageIndex: pageIndex)
+ )
+ log?(
+ " [.] re-attest: page \(pageIndex) of "
+ + "\(chunkURL.lastPathComponent) slot already matches (no-op)"
+ )
+ continue
+ }
+
+ if !dryRun {
+ try handle.seek(toOffset: UInt64(slotOffset))
+ try handle.write(contentsOf: newHash)
+ }
+ log?(
+ " [+] re-attest: \(dryRun ? "would write" : "wrote") slot "
+ + "\(pageIndex) of \(chunkURL.lastPathComponent) "
+ + "(\(Data(oldHash.prefix(4)).hex).. -> \(Data(newHash.prefix(4)).hex)..)"
+ )
+ records.append(
+ DSCSlotReattestation(
+ chunkURL: chunkURL,
+ pageIndex: pageIndex,
+ chunkOffset: pageOffset,
+ slotOffset: slotOffset,
+ hashBefore: oldHash,
+ hashAfter: newHash
+ )
+ )
+ }
+ }
+
+ log?(
+ " [+] re-attest: \(dryRun ? "would update" : "updated") \(records.count) "
+ + "slot hash(es) across \(pagesByChunk.count) chunk(s), "
+ + "\(alreadyAttested.count) already correct, \(skipped.count) skipped"
+ )
+ return DSCReattestation(
+ updated: records,
+ alreadyAttested: alreadyAttested,
+ skipped: skipped
+ )
+ }
+
+ /// Re-attest every page that `chunks`'s own writes dirtied.
+ ///
+ /// The path a patcher should take: write through `DSCChunkSet.write(at:_:)`
+ /// as many times as it likes, then call this. Nothing has to be told which
+ /// addresses were touched, so nothing can get it wrong.
+ @discardableResult
+ public static func reattestRecordedWrites(
+ in chunks: DSCChunkSet,
+ dryRun: Bool = false,
+ log: ((String) -> Void)? = stderrLog
+ ) throws -> DSCReattestation {
+ try reattest(
+ in: chunks,
+ modifiedSpans: chunks.recordedWrites,
+ dryRun: dryRun,
+ log: log
+ )
+ }
+
+ // MARK: - Inspection
+
+ /// The SHA-256 a page currently hashes to, and the slot hash stored for it.
+ ///
+ /// Used by tests and by idempotence checks: when the two are equal the page
+ /// is already attested, whether this code wrote the slot or the Python did.
+ public static func pageHashes(
+ chunkURL: URL,
+ pageIndex: Int,
+ directory: DSCChunkCodeDirectory
+ ) throws -> (computed: Data, stored: Data) {
+ let page = try DSCChunkSet.read(
+ url: chunkURL,
+ offset: UInt64(pageIndex * directory.pageSize),
+ length: directory.pageSize
+ )
+ let stored = try DSCChunkSet.read(
+ url: chunkURL,
+ offset: UInt64(directory.slotOffset(forPage: pageIndex)),
+ length: directory.hashSize
+ )
+ return (Data(SHA256.hash(data: page)), stored)
+ }
+}
+
+// MARK: - Big-endian load
+
+// File-private: `CFWMachOCodeSignature` declares the same helper for the
+// independent Mach-O path. The two signature paths are deliberately separate
+// implementations, and keeping their helpers file-scoped is what stops them
+// drifting into a shared one.
+private extension Data {
+ /// Load a big-endian integer without assuming the buffer is aligned.
+ ///
+ /// Code-signing blobs are big-endian throughout, which is the one place in
+ /// a Mach-O or a dyld cache where that is true.
+ func loadBE<T: FixedWidthInteger>(_: T.Type, at offset: Int) -> T {
+ precondition(offset >= 0 && offset + MemoryLayout<T>.size <= count)
+ var value: T = .zero
+ _ = Swift.withUnsafeMutableBytes(of: &value) { destination in
+ copyBytes(to: destination, from: offset ..< offset + MemoryLayout<T>.size)
+ }
+ return T(bigEndian: value)
+ }
+}
diff --git a/sources/FirmwarePatcher/DSC/DSCError.swift b/sources/FirmwarePatcher/DSC/DSCError.swift
new file mode 100644
index 00000000..79dd3bec
--- /dev/null
+++ b/sources/FirmwarePatcher/DSC/DSCError.swift
@@ -0,0 +1,67 @@
+// DSCError.swift — Errors raised by the dyld shared cache foundation layer.
+
+import Foundation
+
+/// Failures specific to reading and writing a chunked dyld shared cache.
+///
+/// These are separate from `PatcherError` because every one of them is a
+/// statement about the cache on disk, not about a patch site: a caller that
+/// sees one of these has been handed a cache it cannot address, and no amount
+/// of retrying a different anchor will help.
+public enum DSCError: Error, CustomStringConvertible, Sendable {
+ /// No `dyld_shared_cache_<arch>` chunk files under the given directory.
+ case noChunksFound(directory: String)
+ /// Chunks were present but not one of them had a parseable header.
+ case noMappingsParsed(directory: String)
+ /// The address is outside every chunk's mapping table.
+ case addressNotMapped(UInt64)
+ /// The span would run past the end of the mapping that holds its first byte.
+ case addressSpanCrossesChunk(vma: UInt64, length: Int)
+ /// A read came up short — the chunk file is truncated relative to its mappings.
+ case shortRead(vma: UInt64, wanted: Int, got: Int)
+ /// The chunk has no `CS_SuperBlob` / `CS_CodeDirectory` we can re-sign.
+ case noCodeDirectory(chunk: String)
+ /// The code directory exists but is shaped in a way this code does not handle.
+ case unsupportedCodeDirectory(chunk: String, reason: String)
+ /// A file that should carry a `dyld_cache_header` does not.
+ case notADyldCache(String)
+ /// The `.symbols` side file that holds the stripped local symbols is not
+ /// beside the cache. Distinct from `symbolNotFound`: there is nothing to
+ /// look in, so "not found" would be a lie.
+ case localSymbolsMissing(path: String)
+ /// A symbol lookup came back empty.
+ case symbolNotFound(symbol: String, image: String?)
+ /// An image path is not in the cache's image list.
+ case imageNotFound(String)
+
+ public var description: String {
+ switch self {
+ case let .noChunksFound(directory):
+ "No dyld shared cache chunks found under \(directory)"
+ case let .noMappingsParsed(directory):
+ "Chunks present under \(directory) but no mapping table was recognised"
+ case let .addressNotMapped(vma):
+ "VMA 0x\(String(vma, radix: 16, uppercase: true)) is not mapped by any chunk"
+ case let .addressSpanCrossesChunk(vma, length):
+ "Span at VMA 0x\(String(vma, radix: 16, uppercase: true)) length \(length) crosses a chunk boundary"
+ case let .shortRead(vma, wanted, got):
+ "Short read at VMA 0x\(String(vma, radix: 16, uppercase: true)): got \(got) of \(wanted) bytes"
+ case let .noCodeDirectory(chunk):
+ "Chunk \(chunk) has no recognised CS_SuperBlob / CS_CodeDirectory"
+ case let .unsupportedCodeDirectory(chunk, reason):
+ "Chunk \(chunk) code directory unsupported: \(reason)"
+ case let .notADyldCache(path):
+ "\(path) does not start with a dyld cache header"
+ case let .localSymbolsMissing(path):
+ "The cache's local symbol table is missing: \(path)"
+ case let .symbolNotFound(symbol, image):
+ if let image {
+ "Symbol \(symbol) not found in \(image)"
+ } else {
+ "Symbol \(symbol) not found in the cache's local symbol table"
+ }
+ case let .imageNotFound(path):
+ "Image \(path) is not in the cache"
+ }
+ }
+}
diff --git a/sources/FirmwarePatcher/DSC/DSCLocalSymbolTable.swift b/sources/FirmwarePatcher/DSC/DSCLocalSymbolTable.swift
new file mode 100644
index 00000000..651add25
--- /dev/null
+++ b/sources/FirmwarePatcher/DSC/DSCLocalSymbolTable.swift
@@ -0,0 +1,170 @@
+// DSCLocalSymbolTable.swift — The cache's stripped local symbol table.
+//
+// dyld strips local symbols out of the images in the shared cache and parks
+// them in a side file, `dyld_shared_cache_<arch>.symbols`. That file is where
+// every ObjC method symbol lives — `+[AVCaptureDevice authorizationStatusFor…]`
+// is not exported, so the export trie will never have it — and where private C
+// functions such as `_kern_SwapEnd` live too.
+//
+// This is parsed directly rather than shelled out to `ipsw dyld symaddr`:
+// on this cache that tool takes long enough to time out, which is exactly why
+// the Python reference parses the table itself. Keeping the property matters
+// more than the line count.
+//
+// struct dyld_cache_local_symbols_info { // at header.localSymbolsOffset
+// uint32_t nlistOffset; // all offsets are relative to
+// uint32_t nlistCount; // localSymbolsOffset
+// uint32_t stringsOffset;
+// uint32_t stringsSize;
+// uint32_t entriesOffset;
+// uint32_t entriesCount;
+// };
+//
+// struct dyld_cache_local_symbols_entry_64 {
+// uint64_t dylibOffset; // image's __TEXT, as a cache
+// uint32_t nlistStartIndex; // VM offset from sharedRegionStart
+// uint32_t nlistCount;
+// };
+
+import Foundation
+
+/// Reader over `dyld_shared_cache_<arch>.symbols`.
+public struct DSCLocalSymbolTable: Sendable {
+ /// One image's slice of the nlist array.
+ public struct ImageEntry: Sendable {
+ /// The image's `__TEXT` address as an offset from the cache's
+ /// `sharedRegionStart`, which is how entries are keyed.
+ public let dylibOffset: UInt64
+ public let nlistStartIndex: Int
+ public let nlistCount: Int
+ }
+
+ public let url: URL
+ /// The whole nlist array, `nlistCount` × 16 bytes.
+ let nlistData: Data
+ /// The string table the nlist entries index into.
+ let stringData: Data
+ public let nlistCount: Int
+ public let entries: [ImageEntry]
+
+ // MARK: - Construction
+
+ public init(url: URL) throws {
+ self.url = url
+ let handle = try FileHandle(forReadingFrom: url)
+ defer { try? handle.close() }
+
+ guard let head = try handle.read(upToCount: 0x100), head.count >= 0x50,
+ head.prefix(7) == Data("dyld_v1".utf8)
+ else {
+ throw DSCError.notADyldCache(url.path)
+ }
+
+ let infoOffset = head.loadLE(UInt64.self, at: 0x48)
+ guard infoOffset > 0 else {
+ throw DSCError.symbolNotFound(symbol: "<local symbols table>", image: nil)
+ }
+
+ try handle.seek(toOffset: infoOffset)
+ guard let info = try handle.read(upToCount: 24), info.count == 24 else {
+ throw DSCError.symbolNotFound(symbol: "<local symbols table>", image: nil)
+ }
+ let nlistOffset = UInt64(info.loadLE(UInt32.self, at: 0))
+ let nlistCount = Int(info.loadLE(UInt32.self, at: 4))
+ let stringsOffset = UInt64(info.loadLE(UInt32.self, at: 8))
+ let stringsSize = Int(info.loadLE(UInt32.self, at: 12))
+ let entriesOffset = UInt64(info.loadLE(UInt32.self, at: 16))
+ let entriesCount = Int(info.loadLE(UInt32.self, at: 20))
+
+ try handle.seek(toOffset: infoOffset + stringsOffset)
+ stringData = try handle.read(upToCount: stringsSize) ?? Data()
+
+ try handle.seek(toOffset: infoOffset + nlistOffset)
+ nlistData = try handle.read(upToCount: nlistCount * 16) ?? Data()
+ self.nlistCount = min(nlistCount, nlistData.count / 16)
+
+ try handle.seek(toOffset: infoOffset + entriesOffset)
+ let entryData = try handle.read(upToCount: entriesCount * 16) ?? Data()
+ entries = (0 ..< min(entriesCount, entryData.count / 16)).map { index in
+ let base = index * 16
+ return ImageEntry(
+ dylibOffset: entryData.loadLE(UInt64.self, at: base),
+ nlistStartIndex: Int(entryData.loadLE(UInt32.self, at: base + 8)),
+ nlistCount: Int(entryData.loadLE(UInt32.self, at: base + 12))
+ )
+ }
+ }
+
+ // MARK: - Lookup
+
+ /// The name at `stringIndex`, or `nil` when the index is out of range.
+ func name(atStringIndex stringIndex: Int) -> String? {
+ guard stringIndex >= 0, stringIndex < stringData.count else { return nil }
+ var end = stringIndex
+ while end < stringData.count, stringData[stringData.startIndex + end] != 0 { end += 1 }
+ guard end > stringIndex else { return "" }
+ let bytes = stringData[(stringData.startIndex + stringIndex) ..< (stringData.startIndex + end)]
+ return String(decoding: bytes, as: UTF8.self)
+ }
+
+ /// `n_value` of the first entry named `name`, scanning the whole table.
+ ///
+ /// First match wins, which is what the Python reference does. Names repeat
+ /// across images — every ObjC class that answers `+alloc` contributes one —
+ /// so prefer `symbols(in:)` when the image is known.
+ public func firstAddress(of name: String) -> UInt64? {
+ let wanted = Array(name.utf8)
+ return nlistData.withUnsafeBytes { nlist -> UInt64? in
+ stringData.withUnsafeBytes { strings -> UInt64? in
+ for index in 0 ..< nlistCount {
+ let base = index * 16
+ let stringIndex = Int(
+ nlist.loadUnaligned(fromByteOffset: base, as: UInt32.self).littleEndian
+ )
+ guard Self.matches(wanted, in: strings, at: stringIndex) else { continue }
+ return nlist
+ .loadUnaligned(fromByteOffset: base + 8, as: UInt64.self)
+ .littleEndian
+ }
+ return nil
+ }
+ }
+ }
+
+ /// Every symbol in one image's slice of the table, as name → address.
+ ///
+ /// Later duplicates are kept out, so the first spelling of a name in the
+ /// image's own slice wins — same rule as `firstAddress(of:)`, applied to a
+ /// smaller range.
+ public func symbols(in entry: ImageEntry) -> [String: UInt64] {
+ var result: [String: UInt64] = [:]
+ let upperBound = min(entry.nlistStartIndex + entry.nlistCount, nlistCount)
+ guard entry.nlistStartIndex >= 0, entry.nlistStartIndex < upperBound else { return result }
+ for index in entry.nlistStartIndex ..< upperBound {
+ let base = index * 16
+ let stringIndex = Int(nlistData.loadLE(UInt32.self, at: base))
+ let value = nlistData.loadLE(UInt64.self, at: base + 8)
+ guard value != 0, let name = name(atStringIndex: stringIndex), !name.isEmpty
+ else { continue }
+ if result[name] == nil { result[name] = value }
+ }
+ return result
+ }
+
+ /// The entry whose image starts at `dylibOffset` (a cache VM offset).
+ public func entry(forDylibOffset dylibOffset: UInt64) -> ImageEntry? {
+ entries.first { $0.dylibOffset == dylibOffset }
+ }
+
+ private static func matches(
+ _ wanted: [UInt8],
+ in strings: UnsafeRawBufferPointer,
+ at stringIndex: Int
+ ) -> Bool {
+ guard stringIndex >= 0, stringIndex + wanted.count < strings.count else { return false }
+ for offset in 0 ..< wanted.count where strings[stringIndex + offset] != wanted[offset] {
+ return false
+ }
+ return strings[stringIndex + wanted.count] == 0
+ }
+}
diff --git a/sources/FirmwarePatcher/DSC/DSCSymbolResolver.swift b/sources/FirmwarePatcher/DSC/DSCSymbolResolver.swift
new file mode 100644
index 00000000..dfe116b4
--- /dev/null
+++ b/sources/FirmwarePatcher/DSC/DSCSymbolResolver.swift
@@ -0,0 +1,218 @@
+// DSCSymbolResolver.swift — Symbol addresses in the shared cache, without `ipsw`.
+//
+// Three CFW patchers used to shell out to `ipsw dyld symaddr`:
+// `cfw_patch_camera_dsc.py`, `cfw_patch_iomfb_swapend.py` and
+// `cfw_patch_iomfb_force_kern.py`. Between them they need two kinds of symbol,
+// and the cache stores them in two different places:
+//
+// * **Exported** symbols — `_IOMobileFramebufferSwapBegin` and its siblings —
+// live in each image's export trie, addressed as an offset from the image's
+// mach header.
+// * **Local** symbols — every `+[Class method]`, and private C functions such
+// as `_kern_SwapEnd` — are stripped out of the images at cache-build time
+// and parked in `dyld_shared_cache_<arch>.symbols`, sliced per image.
+//
+// Resolving both, per image, is what replaces the Go tool on the patch path.
+
+import Foundation
+import MachOKit
+
+/// Symbol lookup across the images of a chunked dyld shared cache.
+public final class DSCSymbolResolver {
+ /// Where a resolved address came from. Worth reporting: a symbol found only
+ /// in the local table is one `ipsw dyld symaddr` may also be slow to find,
+ /// and a symbol found in both should agree.
+ public enum Source: String, Sendable {
+ case exportTrie
+ case localSymbols
+ }
+
+ public struct Resolution: Sendable {
+ public let name: String
+ public let address: UInt64
+ public let source: Source
+ }
+
+ /// The cache and all its sub-caches as one view.
+ ///
+ /// This has to be the full cache, not the unsuffixed file: an image's
+ /// export trie lives in the `.dyldlinkedit` sub-cache, and the main
+ /// chunk's own mapping table covers only its first megabyte, so a
+ /// `DyldCache` opened on it alone reports no images past `.00` and no
+ /// exported symbols at all.
+ private let cache: FullDyldCache
+ private let localSymbols: DSCLocalSymbolTable?
+ private let localSymbolsURL: URL
+ private let sharedRegionStart: UInt64
+ /// image path → mach header address.
+ private let imageAddresses: [String: UInt64]
+ private var symbolCacheByImage: [String: [String: Resolution]] = [:]
+
+ // MARK: - Construction
+
+ /// Open the cache whose unsuffixed chunk is `mainCacheURL`.
+ ///
+ /// The `.symbols` side file is expected beside it. Its *absence* is not
+ /// fatal — exported symbols still resolve — but every ObjC method lookup
+ /// will then fail, so callers that need one should check `hasLocalSymbols`.
+ /// A file that is present but unparseable *is* fatal: that is a broken
+ /// cache, and reporting it as "no local symbols" would turn it into a pile
+ /// of `symbolNotFound`s pointing at the wrong thing.
+ public init(mainCacheURL: URL) throws {
+ cache = try FullDyldCache(url: mainCacheURL)
+ sharedRegionStart = cache.mainCacheHeader.sharedRegionStart
+
+ var addresses: [String: UInt64] = [:]
+ if let infos = cache.imageInfos {
+ for info in infos {
+ guard let path = info.path(in: cache) else { continue }
+ if addresses[path] == nil { addresses[path] = info.address }
+ }
+ }
+ imageAddresses = addresses
+
+ let symbolsURL = mainCacheURL.deletingLastPathComponent()
+ .appendingPathComponent(mainCacheURL.lastPathComponent + ".symbols")
+ localSymbols = FileManager.default.fileExists(atPath: symbolsURL.path)
+ ? try DSCLocalSymbolTable(url: symbolsURL)
+ : nil
+ localSymbolsURL = symbolsURL
+ }
+
+ /// Open the cache a `DSCChunkSet` already found.
+ public convenience init(chunks: DSCChunkSet) throws {
+ try self.init(mainCacheURL: chunks.mainCacheURL)
+ }
+
+ public var hasLocalSymbols: Bool { localSymbols != nil }
+
+ /// Fail now if the local symbol table is not there.
+ ///
+ /// For the discovery-shaped callers — `cfw_patch_iomfb_force_kern` looks
+ /// for `_kern_Swap*`, which exist only in the local table. Without this,
+ /// a missing `.symbols` file makes discovery return an empty set, which
+ /// reads as "this cache has no such functions" rather than "I had nowhere
+ /// to look".
+ public func requireLocalSymbols() throws {
+ guard localSymbols != nil else {
+ throw DSCError.localSymbolsMissing(path: localSymbolsURL.path)
+ }
+ }
+
+ /// Every image path in the cache, sorted.
+ public var imagePaths: [String] { imageAddresses.keys.sorted() }
+
+ /// The mach header address of `imagePath`.
+ public func headerAddress(ofImage imagePath: String) throws -> UInt64 {
+ guard let address = imageAddresses[imagePath] else {
+ throw DSCError.imageNotFound(imagePath)
+ }
+ return address
+ }
+
+ // MARK: - Lookup
+
+ /// Every symbol `imagePath` exposes, as name → resolution.
+ ///
+ /// Export-trie entries are taken first, so a name that appears in both
+ /// tables reports the exported address — the one a caller of the public
+ /// entry point would branch to.
+ public func symbols(inImage imagePath: String) throws -> [String: Resolution] {
+ if let cached = symbolCacheByImage[imagePath] { return cached }
+ let headerAddress = try headerAddress(ofImage: imagePath)
+
+ var result: [String: Resolution] = [:]
+
+ if let machO = machOFile(forImage: imagePath) {
+ for exported in machO.exportedSymbols {
+ guard let offset = exported.offset, offset != 0 else { continue }
+ let address = headerAddress &+ UInt64(offset)
+ if result[exported.name] == nil {
+ result[exported.name] = Resolution(
+ name: exported.name,
+ address: address,
+ source: .exportTrie
+ )
+ }
+ }
+ }
+
+ if let localSymbols {
+ let dylibOffset = headerAddress &- sharedRegionStart
+ if let entry = localSymbols.entry(forDylibOffset: dylibOffset) {
+ for (name, address) in localSymbols.symbols(in: entry) where result[name] == nil {
+ result[name] = Resolution(
+ name: name,
+ address: address,
+ source: .localSymbols
+ )
+ }
+ }
+ }
+
+ symbolCacheByImage[imagePath] = result
+ return result
+ }
+
+ /// The address of `symbol` in `imagePath`.
+ ///
+ /// A miss with no local symbol table loaded reports the missing table
+ /// rather than the missing symbol — most of what this resolves (every ObjC
+ /// method, every private C function) lives only in that table, so "not
+ /// found" would send the caller looking in the wrong place.
+ public func address(of symbol: String, inImage imagePath: String) throws -> UInt64 {
+ guard let resolution = try symbols(inImage: imagePath)[symbol] else {
+ try requireLocalSymbols()
+ throw DSCError.symbolNotFound(symbol: symbol, image: imagePath)
+ }
+ return resolution.address
+ }
+
+ /// Resolve several symbols at once, failing on the first one missing.
+ ///
+ /// Reports every missing name rather than only the first: a patcher that
+ /// has lost five ObjC methods to a rename wants to see all five.
+ public func addresses(
+ of symbols: [String],
+ inImage imagePath: String
+ ) throws -> [String: UInt64] {
+ let table = try self.symbols(inImage: imagePath)
+ var result: [String: UInt64] = [:]
+ var missing: [String] = []
+ for symbol in symbols {
+ if let resolution = table[symbol] {
+ result[symbol] = resolution.address
+ } else {
+ missing.append(symbol)
+ }
+ }
+ guard missing.isEmpty else {
+ try requireLocalSymbols()
+ throw DSCError.symbolNotFound(
+ symbol: missing.joined(separator: ", "),
+ image: imagePath
+ )
+ }
+ return result
+ }
+
+ /// Every symbol in `imagePath` whose name starts with `prefix`.
+ ///
+ /// `cfw_patch_iomfb_force_kern` works this way: it does not know the set of
+ /// `_IOMobileFramebufferSwap*` entry points ahead of time, it discovers
+ /// them and pairs each with its `_kern_` sibling.
+ public func symbols(
+ inImage imagePath: String,
+ withPrefix prefix: String
+ ) throws -> [String: UInt64] {
+ try symbols(inImage: imagePath)
+ .filter { $0.key.hasPrefix(prefix) }
+ .mapValues(\.address)
+ }
+
+ // MARK: - Image lookup
+
+ private func machOFile(forImage imagePath: String) -> MachOFile? {
+ cache.machOFiles().first { $0.imagePath == imagePath }
+ }
+}
diff --git a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
index 4e858a4d..f3086d2b 100644
--- a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
+++ b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
@@ -6,8 +6,40 @@
import Foundation
import VPhoneCore
+import VPhoneSign
extension CryptexFilesystemPatcher {
+ // MARK: - Signing
+
+ /// What the `ldid -S -M -K<cfw_input/signcert.p12>` these steps used to
+ /// shell out for now asks VPhoneSign for.
+ ///
+ /// The `.p12` is opened here because VPhoneSign signs with an already-read
+ /// identity — but not on the `VPHONE_USE_LDID` path, where the external
+ /// tool opens the container itself from `identityPath`. Skipping the parse
+ /// there is what keeps the escape hatch a way *out* of a VPhoneSign
+ /// regression rather than a second way into one.
+ func guestSigningOptions(
+ cfwInput: URL,
+ identifier: String? = nil,
+ entitlements: URL? = nil
+ ) throws -> VPhoneSignOptions {
+ let signingCertificatePath = cfwInput.appending(path: "cfw_input/signcert.p12")
+ var identity: (any VPhoneSigningIdentity)?
+ if !VPhoneLdid.isPreferred {
+ identity = try VPhoneSignIdentity(
+ pkcs12: Data(contentsOf: signingCertificatePath), password: ""
+ )
+ }
+ return VPhoneSignOptions(
+ identifier: identifier,
+ entitlements: try entitlements.map { try Data(contentsOf: $0) },
+ mergesExisting: true,
+ identity: identity,
+ identityPath: signingCertificatePath.path
+ )
+ }
+
func patchLaunchdCacheLoader(targetMount: String, cfwInput: URL) throws {
let target = URL.init(filePath: targetMount)
let launchdCacheLoaderPath = target.appending(path: "/usr/libexec/launchd_cache_loader")
@@ -19,12 +51,12 @@ extension CryptexFilesystemPatcher {
])
_ = try runProcess("/bin/chmod", ["0755", launchdCacheLoaderPath.path])
- let signingCertificatePath = cfwInput.appending(path: "cfw_input/signcert.p12")
- _ = try runProcess("/opt/homebrew/bin/ldid", [
- "-S", "-M", "-K\(signingCertificatePath.path)",
- "-Icom.apple.launchd_cache_loader",
- launchdCacheLoaderPath.path
- ])
+ try VPhoneSigner.sign(
+ fileAt: launchdCacheLoaderPath,
+ options: try guestSigningOptions(
+ cfwInput: cfwInput, identifier: "com.apple.launchd_cache_loader"
+ )
+ )
}
func injectLaunchDaemons(targetMount: String, cfwInput: URL, vphoned: Bool = true, cfw: Bool = true) throws {
@@ -62,11 +94,20 @@ extension CryptexFilesystemPatcher {
}
}
- let pythonPath = try resources.pythonExecutable()
- _ = try runProcess(pythonPath.path, [
- resources.cfwPy.path, "inject-daemons",
- launchdPath.path, launchDaemonsPath.path
- ])
+ // The Python printed one line per daemon as it scanned and the install
+ // log is read for those lines, so the scan comes back in scan order and
+ // is logged here in the same words.
+ let staged = try CFWDaemons.injectDaemons(
+ into: launchdPath, fromDirectory: launchDaemonsPath
+ )
+ for daemon in staged {
+ switch daemon {
+ case let .present(daemon):
+ print(" [+] Injected \(daemon.name)")
+ case let .absent(source):
+ print(" [!] Missing \(source), skipping")
+ }
+ }
try FileManager.default.moveItem(at: launchdPath, to: launchdOgPath)
_ = try runProcess("/bin/chmod", ["0644", launchdOgPath.path])
}
@@ -94,12 +135,13 @@ extension CryptexFilesystemPatcher {
// Sign
let targetBin = target.appending(path: "/usr/bin/vphoned")
try FileManager.default.copyItem(at: vphonedBin, to: targetBin)
- let signingCertificatePath = cfwInput.appending(path: "cfw_input/signcert.p12")
- _ = try runProcess("/opt/homebrew/bin/ldid", [
- "-S\(vphonedSrc.appendingPathComponent("entitlements.plist").path)",
- "-M", "-K\(signingCertificatePath.path)",
- targetBin.path
- ])
+ try VPhoneSigner.sign(
+ fileAt: targetBin,
+ options: try guestSigningOptions(
+ cfwInput: cfwInput,
+ entitlements: vphonedSrc.appendingPathComponent("entitlements.plist")
+ )
+ )
_ = try runProcess("/bin/chmod", ["0755", targetBin.path])
}
@@ -172,11 +214,10 @@ extension CryptexFilesystemPatcher {
])
_ = try runProcess("/bin/chmod", ["0755", mobileActivationdPath.path])
- let signingCertificatePath = cfwInput.appending(path: "cfw_input/signcert.p12")
- _ = try runProcess("/opt/homebrew/bin/ldid", [
- "-S", "-M", "-K\(signingCertificatePath.path)",
- mobileActivationdPath.path
- ])
+ try VPhoneSigner.sign(
+ fileAt: mobileActivationdPath,
+ options: try guestSigningOptions(cfwInput: cfwInput)
+ )
}
func addDyldSymlinks(targetMount: String) throws {
diff --git a/sources/VPhoneArchive/VPhoneArchiveExtractor.swift b/sources/VPhoneArchive/VPhoneArchiveExtractor.swift
index 7b4a375d..257641f0 100644
--- a/sources/VPhoneArchive/VPhoneArchiveExtractor.swift
+++ b/sources/VPhoneArchive/VPhoneArchiveExtractor.swift
@@ -20,6 +20,11 @@ public enum VPhoneArchiveExtractor {
/// Unpack `archive` into `destination`.
///
+ /// `bytesRead` reports how far into the archive *file* the read has got —
+ /// compressed bytes, so it can be shown against the file's size on disk.
+ /// It fires per data block, not per entry, because a VM bundle's `Disk.img`
+ /// is one entry of many gigabytes.
+ ///
/// - Returns: the number of entries written, not counting any skipped by
/// `noOverwriteDir`.
@discardableResult
@@ -28,6 +33,7 @@ public enum VPhoneArchiveExtractor {
into destination: URL,
options: VPhoneArchiveExtractOptions,
progress: ((Progress) -> Void)? = nil,
+ bytesRead: ((Int64) -> Void)? = nil,
isCancelled: (() -> Bool)? = nil
) throws -> Int {
let reader = archive_read_new()
@@ -130,7 +136,12 @@ public enum VPhoneArchiveExtractor {
}
if archive_entry_size(entry) > 0 {
- bytes += try copyData(from: reader, to: writer, isCancelled: isCancelled)
+ bytes += try copyData(
+ from: reader, to: writer, isCancelled: isCancelled,
+ onBlock: bytesRead.map { report in
+ { report(archive_filter_bytes(reader, -1)) }
+ }
+ )
}
guard archive_write_finish_entry(writer) == ARCHIVE_OK else {
@@ -141,6 +152,10 @@ public enum VPhoneArchiveExtractor {
written += 1
progress?(Progress(entriesWritten: written, bytesWritten: bytes, currentPath: memberPath))
+ // filter -1 is the bottom filter, the archive file itself, so this
+ // is the compressed position. Entries with no data never reach the
+ // per-block report above, and small ones are most of a bundle.
+ bytesRead?(archive_filter_bytes(reader, -1))
}
return written
@@ -191,7 +206,8 @@ public enum VPhoneArchiveExtractor {
private static func copyData(
from reader: OpaquePointer?,
to writer: OpaquePointer?,
- isCancelled: (() -> Bool)?
+ isCancelled: (() -> Bool)?,
+ onBlock: (() -> Void)? = nil
) throws -> Int64 {
var total: Int64 = 0
while true {
@@ -218,6 +234,7 @@ public enum VPhoneArchiveExtractor {
)
}
total += Int64(size)
+ onBlock?()
}
}
}
diff --git a/sources/VPhoneArchive/VPhoneArchiveOptions.swift b/sources/VPhoneArchive/VPhoneArchiveOptions.swift
index d64f7093..ffd173d4 100644
--- a/sources/VPhoneArchive/VPhoneArchiveOptions.swift
+++ b/sources/VPhoneArchive/VPhoneArchiveOptions.swift
@@ -52,16 +52,30 @@ public struct VPhoneArchiveExtractOptions: Sendable {
/// that has booted.
public var macMetadata: Bool
+ /// Restore the archive's mode bits **exactly**, setuid and setgid included,
+ /// ignoring the process umask. This is `tar -p`.
+ ///
+ /// Off by default, and that default is the safe one: without it libarchive
+ /// strips setuid, setgid and sticky and masks the rest through the umask,
+ /// which is what plain `tar -xf` does as a normal user.
+ ///
+ /// Only turn it on where the modes in the archive are the point — see
+ /// `ontoGuestVolume` — never for an archive that arrived from somewhere
+ /// else.
+ public var exactPermissions: Bool
+
/// Restore ACLs and BSD file flags as well as mode bits.
public var extendedMetadata: Bool
public init(
ownership: VPhoneArchiveOwnership,
+ exactPermissions: Bool = false,
noOverwriteDir: Bool = false,
macMetadata: Bool = false,
extendedMetadata: Bool = false
) {
self.ownership = ownership
+ self.exactPermissions = exactPermissions
self.noOverwriteDir = noOverwriteDir
self.macMetadata = macMetadata
self.extendedMetadata = extendedMetadata
@@ -71,16 +85,35 @@ public struct VPhoneArchiveExtractOptions: Sendable {
///
/// Mirrors what `cfw_install*.sh` passes GNU tar today:
/// `--preserve-permissions --no-overwrite-dir`.
+ ///
+ /// `exactPermissions` is not optional here. An iOS system volume is full
+ /// of setuid binaries and of modes that are not the host's umask to decide
+ /// — a `/usr/bin/su` that comes back 0755 instead of 4755 is a guest that
+ /// boots into something subtly broken. The archives are ones this project
+ /// builds, so restoring them verbatim is the whole job.
public static let ontoGuestVolume = VPhoneArchiveExtractOptions(
ownership: .preserveNumeric,
+ exactPermissions: true,
noOverwriteDir: true,
macMetadata: false,
extendedMetadata: true
)
/// Unpacking into a host directory we own and can throw away.
+ ///
+ /// The mirror image of `ontoGuestVolume`: the archive is whatever the user
+ /// handed us — a `vm export` that travelled here from another machine —
+ /// and nothing in it may decide the modes of files written into the host's
+ /// home directory. So `exactPermissions` stays off, the process umask
+ /// applies, and setuid/setgid/sticky are dropped.
+ ///
+ /// This is exactly what `/usr/bin/tar -xf` (no `-p`) gave, which is what
+ /// `vm import` used to shell out to. It is a deliberate contract, not a
+ /// default nobody looked at: `hostPresetNeverRestoresSetuid` fails if the
+ /// flag ever comes back.
public static let intoHostDirectory = VPhoneArchiveExtractOptions(
ownership: .currentUser,
+ exactPermissions: false,
noOverwriteDir: false,
macMetadata: false,
extendedMetadata: false
@@ -111,9 +144,16 @@ public struct VPhoneArchiveExtractOptions: Sendable {
// lands.
var flags = ARCHIVE_EXTRACT_SECURE_SYMLINKS
| ARCHIVE_EXTRACT_SECURE_NODOTDOT
- | ARCHIVE_EXTRACT_PERM
| ARCHIVE_EXTRACT_TIME
+ // ARCHIVE_EXTRACT_PERM is `tar -p`, and it is a decision, not a
+ // fidelity dial. With it, archive_write_disk restores the stored mode
+ // verbatim; without it, it clears S_ISUID/S_ISGID/S_ISVTX and masks
+ // the remainder through the umask it captured at
+ // archive_write_disk_new(). Setting it unconditionally is how `vm
+ // import` came to write a world-writable, setuid tree out of an
+ // archive from somewhere else. See the two presets above.
+ if exactPermissions { flags |= ARCHIVE_EXTRACT_PERM }
if ownership == .preserveNumeric { flags |= ARCHIVE_EXTRACT_OWNER }
if extendedMetadata { flags |= ARCHIVE_EXTRACT_ACL | ARCHIVE_EXTRACT_FFLAGS }
if macMetadata { flags |= ARCHIVE_EXTRACT_MAC_METADATA }
diff --git a/sources/VPhoneArchive/VPhoneArchiveWriter.swift b/sources/VPhoneArchive/VPhoneArchiveWriter.swift
index a9c95370..ce153f8f 100644
--- a/sources/VPhoneArchive/VPhoneArchiveWriter.swift
+++ b/sources/VPhoneArchive/VPhoneArchiveWriter.swift
@@ -14,16 +14,30 @@ public enum VPhoneArchiveWriter {
/// Paths inside the archive are relative to `root`, so unpacking anywhere
/// reproduces the tree rather than an absolute path.
///
- /// `excluding` takes `fnmatch` patterns matched against the archive-relative
- /// path, which is what `vm export` already uses.
+ /// `topLevel` puts every member under one directory of that name, and adds
+ /// an entry for the directory itself — what `tar -C <parent> <name>` does.
+ /// `vm export` needs it: an export holds exactly one top-level bundle
+ /// directory, and import checks for exactly that.
+ ///
+ /// `excluding` takes `fnmatch` patterns, matched against the path relative
+ /// to `root` — not against `topLevel/...`, so a VM whose name happens to
+ /// contain `cfw_input` does not exclude its own contents.
+ ///
+ /// `bytesPacked` reports the running total of file bytes copied, as they
+ /// are copied. `progress` fires once per entry, which is enough for a
+ /// listing but not for a progress bar: a VM bundle is one multi-gigabyte
+ /// `Disk.img` and a handful of small files, so a per-entry bar would sit
+ /// at zero for the whole export.
@discardableResult
public static func create(
archive: URL,
from root: URL,
+ topLevel: String? = nil,
format: VPhoneArchiveFormat = .gnutar,
compression: VPhoneArchiveCompression = .none,
excluding patterns: [String] = [],
progress: ((Progress) -> Void)? = nil,
+ bytesPacked: ((Int64) -> Void)? = nil,
isCancelled: (() -> Bool)? = nil
) throws -> Int {
let writer = archive_write_new()
@@ -66,6 +80,24 @@ public enum VPhoneArchiveWriter {
let disk = archive_read_disk_new()
archive_read_disk_set_standard_lookup(disk)
+ // Clears ARCHIVE_READDISK_MAC_COPYFILE, which archive_read_disk_new
+ // sets. Everything else stays at its default — xattrs, ACLs, file
+ // flags and sparse maps are still read.
+ //
+ // It is not a fidelity choice, it is a side effect: for every file,
+ // copyfile(3) packs the AppleDouble form into a temp file made with a
+ // *relative* mkstemp template, and libarchive's tree walker chdir's
+ // into each directory as it descends — so the temp file is created and
+ // removed inside the directory being read, and that directory's mtime
+ // becomes now. `vm export` would rewrite the mtime of every directory
+ // in the VM bundle it was asked only to read. Measured: 2023 in, the
+ // moment of the export out; `/usr/bin/tar -cf` leaves them alone.
+ //
+ // Nothing is lost that was being kept: no `._` member has ever been
+ // seen in an archive this writes, and both extract presets leave
+ // ARCHIVE_EXTRACT_MAC_METADATA off, so one would come back as a
+ // literal `._` file rather than as metadata.
+ archive_read_disk_set_behavior(disk, 0)
defer { archive_read_free(disk) }
// Resolved, and the same resolved path is what libarchive walks — so
@@ -111,13 +143,22 @@ public enum VPhoneArchiveWriter {
path: root.path, reason: archiveErrorString(disk)
)
}
- archive_read_disk_descend(disk)
let absolute = archive_entry_pathname(entry).map { String(cString: $0) } ?? ""
let relative = VPhoneArchivePaths.relative(absolute, under: rootPath)
- if relative.isEmpty { continue } // the root itself
- if patterns.contains(where: { matches(relative, pattern: $0) }) { continue }
- archive_entry_set_pathname(entry, relative)
+ // An excluded directory is not descended into, so the whole subtree
+ // goes in one decision rather than one fnmatch per file. GNU tar's
+ // --exclude prunes the same way, and `vm export`'s *_Restore*
+ // exclude covers an unpacked IPSW — tens of thousands of files.
+ if !relative.isEmpty, patterns.contains(where: { matches(relative, pattern: $0) }) {
+ continue
+ }
+ archive_read_disk_descend(disk)
+
+ // Without a top-level name the root entry itself is skipped: an
+ // archive of a directory's contents should not carry the directory.
+ guard let stored = storedPath(relative, under: topLevel) else { continue }
+ archive_entry_set_pathname(entry, stored)
// Turns the second and later names of a hardlinked file into
// references to the first. The archive-relative pathname has to be
@@ -130,18 +171,21 @@ public enum VPhoneArchiveWriter {
guard archive_write_header(writer, resolved) == ARCHIVE_OK else {
throw VPhoneArchiveError.writeFailed(
- path: relative, reason: archiveErrorString(writer)
+ path: stored, reason: archiveErrorString(writer)
)
}
// A hardlink reference comes back with size 0, so this also skips
// re-storing contents we have already written once.
if archive_entry_size(resolved) > 0 {
- bytes += try copyFile(at: absolute, into: writer, isCancelled: isCancelled)
+ try copyFile(at: absolute, into: writer, isCancelled: isCancelled) { chunk in
+ bytes += chunk
+ bytesPacked?(bytes)
+ }
}
written += 1
- progress?(Progress(entriesWritten: written, bytesWritten: bytes, currentPath: relative))
+ progress?(Progress(entriesWritten: written, bytesWritten: bytes, currentPath: stored))
}
return written
@@ -214,17 +258,23 @@ public enum VPhoneArchiveWriter {
|| fnmatch(pattern, (path as NSString).lastPathComponent, 0) == 0
}
+ /// What this member is called inside the archive, or nil to skip it.
+ private static func storedPath(_ relative: String, under topLevel: String?) -> String? {
+ guard let topLevel else { return relative.isEmpty ? nil : relative }
+ return relative.isEmpty ? topLevel : topLevel + "/" + relative
+ }
+
private static func copyFile(
at path: String,
into writer: OpaquePointer?,
- isCancelled: (() -> Bool)?
- ) throws -> Int64 {
+ isCancelled: (() -> Bool)?,
+ onBytes: (Int64) -> Void
+ ) throws {
guard let handle = FileHandle(forReadingAtPath: path) else {
throw VPhoneArchiveError.cannotOpen(path: path, reason: "cannot read")
}
defer { try? handle.close() }
- var total: Int64 = 0
while true {
if isCancelled?() == true { throw VPhoneArchiveError.cancelled }
guard let chunk = try handle.read(upToCount: 1 << 20), !chunk.isEmpty else { break }
@@ -236,8 +286,7 @@ public enum VPhoneArchiveWriter {
path: path, reason: archiveErrorString(writer)
)
}
- total += Int64(sent)
+ onBytes(Int64(sent))
}
- return total
}
}
diff --git a/sources/VPhoneArchive/VPhoneBundleTransfer.swift b/sources/VPhoneArchive/VPhoneBundleTransfer.swift
new file mode 100644
index 00000000..043a15ae
--- /dev/null
+++ b/sources/VPhoneArchive/VPhoneBundleTransfer.swift
@@ -0,0 +1,233 @@
+import Darwin
+import Foundation
+import VPhoneCore
+
+// MARK: - Errors
+
+public enum VPhoneBundleTransferError: Error, Equatable, CustomStringConvertible, LocalizedError {
+ /// The archive is readable, but it is not a VM export.
+ case badArchive(String)
+
+ public var description: String {
+ switch self {
+ case let .badArchive(message): message
+ }
+ }
+
+ public var errorDescription: String? { description }
+}
+
+// MARK: - VPhoneBundleTransfer
+
+/// `vm export` and `vm import`.
+///
+/// It lives here, and not in `VPhoneCore`, because it needs libarchive. It
+/// lives here, and not in the VM kit, because `vphone-cli` deliberately does
+/// not import the kit — see the note on that target in `Package.swift` —
+/// and `vphone-cli vm export` has to keep working. `VPhoneArchive` sits above
+/// `VPhoneCore` and needs neither Virtualization nor AppKit, which is exactly
+/// the altitude this wants.
+///
+/// The format contract is fixed and older archives are already out there:
+/// gnutar, `.tzst` at zstd 3, `.txz` at xz 9, extension chosen from the
+/// preset. `importArchive` detects the compressor, so it reads anything an
+/// older copy of this program produced — and `/usr/bin/tar` reads what this
+/// produces.
+public enum VPhoneBundleTransfer {
+ /// Compression preset for `export`. Both import transparently —
+ /// `importArchive` auto-detects the compressor when it extracts.
+ public enum ExportCompression: String, CaseIterable, Sendable {
+ case fast, max
+
+ /// zstd 3 and xz 9. Not tuning knobs: archives with these settings
+ /// have been handed to users, and the levels are part of what `.tzst`
+ /// and `.txz` mean here.
+ var archiveCompression: VPhoneArchiveCompression {
+ switch self {
+ case .fast: .zstd(level: 3)
+ case .max: .xz(level: 9)
+ }
+ }
+
+ /// Extension for auto-named output when `export`'s destination is a
+ /// directory.
+ public var fileExtension: String { archiveCompression.tarExtension }
+ }
+
+ // MARK: - Export
+
+ /// When `to` is an existing directory, the archive is written inside it as
+ /// `<name>.<compression.fileExtension>`. Returns the resolved output URL.
+ ///
+ /// `progress` is called with `(bytesDone, totalBytes)`, where `totalBytes`
+ /// is the bundle's on-disk logical size minus the excludes, and `bytesDone`
+ /// is the uncompressed payload packed so far. It ticks per megabyte rather
+ /// than per member: a bundle is one huge `Disk.img` and a few small files.
+ @discardableResult
+ public static func export(
+ bundleNamed name: String,
+ to outFile: URL,
+ includeIPSW: Bool,
+ compression: ExportCompression = .fast,
+ in library: VPhoneLibrary,
+ progress: ((Int64, Int64) -> Void)? = nil
+ ) throws -> URL {
+ _ = try library.bundle(named: name) // validate it exists
+ var isDir: ObjCBool = false
+ let outFile = FileManager.default.fileExists(atPath: outFile.path, isDirectory: &isDir)
+ && isDir.boolValue
+ ? outFile.appendingPathComponent("\(name).\(compression.fileExtension)")
+ : outFile
+
+ let bundleDir = library.url(forName: name)
+ var excludes = VPhoneBundleOps.exportExcludePatterns
+ if !includeIPSW { excludes.append("*_Restore*") }
+
+ let total = progress != nil
+ ? archivedLogicalSize(bundleDir: bundleDir, includeIPSW: includeIPSW)
+ : 0
+
+ // gnutar, not the pax default: pax extended headers used to break the
+ // consumer of the old two-stage pipe, and — still true — ustar cannot
+ // carry a member over 8 GB, which Disk.img is.
+ //
+ // topLevel is the bundle's own name, so the archive holds exactly one
+ // top-level directory. importArchive checks for that, and so does
+ // every export already on disk.
+ try VPhoneArchiveWriter.create(
+ archive: outFile,
+ from: bundleDir,
+ topLevel: name,
+ format: .gnutar,
+ compression: compression.archiveCompression,
+ excluding: excludes,
+ bytesPacked: progress.map { report in { done in report(done, total) } }
+ )
+ return outFile
+ }
+
+ /// On-disk logical size of the members `export` will archive, mirroring the
+ /// exclude patterns so the progress total matches the streamed bytes.
+ ///
+ /// A hardlinked file is counted once, no matter how many names it has under
+ /// the bundle. `VPhoneArchiveWriter` runs a link resolver: the first name is
+ /// stored with its contents and every later name becomes a size-0 hardlink
+ /// reference, so those later names contribute nothing to `bytesPacked`.
+ /// Adding each name's size here made the total larger than anything that
+ /// could ever be packed, and the bar could not reach 100%.
+ private static func archivedLogicalSize(bundleDir: URL, includeIPSW: Bool) -> Int64 {
+ let keys: [URLResourceKey] = [.isRegularFileKey, .fileSizeKey, .linkCountKey]
+ let fm = FileManager.default
+ guard let en = fm.enumerator(at: bundleDir, includingPropertiesForKeys: keys)
+ else { return 0 }
+ let prefix = bundleDir.path.count + 1 // members are relative to the bundle
+ var total: Int64 = 0
+ var countedInodes = Set<Inode>()
+ for case let url as URL in en {
+ guard url.path.count > prefix else { continue }
+ let rel = String(url.path.dropFirst(prefix))
+ if !includeIPSW, rel.contains("_Restore") { en.skipDescendants(); continue }
+ if VPhoneBundleOps.exportExcludePatterns.contains(where: { fnmatch($0, rel, 0) == 0 }) {
+ continue
+ }
+ guard let vals = try? url.resourceValues(forKeys: Set(keys)),
+ vals.isRegularFile == true else { continue }
+ // linkCount == 1 is every file in an ordinary bundle, and it costs
+ // no extra syscall — only a genuinely linked file is stat'd again
+ // to find out which inode it is a name for.
+ if (vals.linkCount ?? 1) > 1 {
+ guard let inode = Inode(path: url.path), countedInodes.insert(inode).inserted
+ else { continue }
+ }
+ total += Int64(vals.fileSize ?? 0)
+ }
+ return total
+ }
+
+ /// Identity of a file's contents: device plus inode, which is what makes
+ /// two names the same file rather than two files of equal size.
+ private struct Inode: Hashable {
+ let device: dev_t
+ let number: ino_t
+
+ init?(path: String) {
+ var info = stat()
+ guard lstat(path, &info) == 0 else { return nil }
+ device = info.st_dev
+ number = info.st_ino
+ }
+ }
+
+ // MARK: - Import
+
+ /// Extracts (auto-detecting gzip/zstd/xz) into a private staging dir, then
+ /// promotes the single top-level bundle to the library.
+ ///
+ /// `progress` is called with `(bytesDone, totalBytes)` against the archive
+ /// file's size on disk — compressed bytes, which is what the user can see
+ /// in Finder.
+ public static func importArchive(
+ from inFile: URL,
+ name: String?,
+ in library: VPhoneLibrary,
+ progress: ((Int64, Int64) -> Void)? = nil
+ ) throws -> VPhoneBundle {
+ let fm = FileManager.default
+ // Fail fast when the destination name is already known (explicit rename).
+ if let name {
+ try VPhoneBundleOps.requireValidName(name)
+ if fm.fileExists(atPath: library.url(forName: name).path) {
+ throw VPhoneLibraryError.alreadyExists(name: name)
+ }
+ }
+
+ // Extract into a private staging dir so the archive's OWN top-level name
+ // can never clobber/merge into an existing bundle of that name; only the
+ // validated destination name is ever placed into the library.
+ try fm.createDirectory(at: library.root, withIntermediateDirectories: true)
+ let staging = library.root.appendingPathComponent(".import-\(UUID().uuidString)")
+ try fm.createDirectory(at: staging, withIntermediateDirectories: true)
+ defer { try? fm.removeItem(at: staging) }
+
+ let total = progress != nil ? fileByteSize(inFile) : 0
+ // .intoHostDirectory, and specifically NOT the guest-volume preset: an
+ // import is an archive from another machine landing in the user's home
+ // directory, so the umask applies and setuid/setgid do not survive —
+ // what `/usr/bin/tar -xf` (no -p) gave when this shelled out. The
+ // modes a VM bundle actually needs are its own files' 0644/0755;
+ // nothing in it has any business being setuid.
+ try VPhoneArchiveExtractor.extract(
+ inFile,
+ into: staging,
+ options: .intoHostDirectory,
+ bytesRead: progress.map { report in { done in report(done, total) } }
+ )
+ // A tar reader stops at the end-of-archive marker, which in a
+ // compressed file can sit short of the last byte, so the read position
+ // alone would leave the bar just under full on a finished import.
+ progress?(total, total)
+
+ let entries = try fm.contentsOfDirectory(atPath: staging.path)
+ guard entries.count == 1, let archived = entries.first else {
+ throw VPhoneBundleTransferError.badArchive(
+ "This archive is not a VM export. Choose an archive created by 'vphone-cli vm export'.")
+ }
+ let finalName = name ?? archived
+ try VPhoneBundleOps.requireValidName(finalName)
+ let dst = library.url(forName: finalName)
+ if fm.fileExists(atPath: dst.path) { throw VPhoneLibraryError.alreadyExists(name: finalName) }
+ let extracted = staging.appendingPathComponent(archived)
+ guard fm.fileExists(atPath: extracted.appendingPathComponent("config.plist").path) else {
+ throw VPhoneBundleTransferError.badArchive(
+ "This archive does not contain a valid VM. Choose an archive created by 'vphone-cli vm export'.")
+ }
+ let bundle = try VPhoneBundle.load(at: extracted)
+ try fm.moveItem(at: extracted, to: dst)
+ return VPhoneBundle(url: dst, manifest: bundle.manifest)
+ }
+
+ private static func fileByteSize(_ url: URL) -> Int64 {
+ let size = (try? url.resourceValues(forKeys: [.fileSizeKey]))?.fileSize
+ return Int64(size ?? 0)
+ }
+}
diff --git a/sources/VPhoneCore/VPhoneBundleOps.swift b/sources/VPhoneCore/VPhoneBundleOps.swift
index f0ec312b..a09db6d8 100644
--- a/sources/VPhoneCore/VPhoneBundleOps.swift
+++ b/sources/VPhoneCore/VPhoneBundleOps.swift
@@ -1,11 +1,6 @@
import Darwin
import Foundation
-public enum VPhoneBundleOpsError: Error, Equatable {
- case tarFailed(String)
- case badArchive(String)
-}
-
public enum VPhoneBundleOps {
public struct NewBundleSpec: Sendable {
public let name: String
@@ -38,7 +33,9 @@ public enum VPhoneBundleOps {
frameworkResources.appendingPathComponent("AVPSEPBooter.vresearch1.bin")
}
- private static func requireValidName(_ name: String) throws {
+ /// Public because `vm import` validates the name it is about to place into
+ /// the library, and that lives in `VPhoneArchive` now.
+ public static func requireValidName(_ name: String) throws {
guard !name.isEmpty, !name.contains("/"), !name.hasPrefix(".") else {
throw VPhoneLibraryError.invalidName(name)
}
@@ -177,158 +174,16 @@ public enum VPhoneBundleOps {
try manifest.updating(machineIdentifier: Data()).write(to: configURL)
}
- // MARK: - Export / Import
-
- /// Compression preset for `export`. Both import transparently — `importArchive`
- /// auto-detects the compressor when it extracts. `threads=0` → all cores.
- public enum ExportCompression: String, CaseIterable, Sendable {
- case fast, max
-
- var tarArgs: [String] {
- switch self {
- case .fast: ["--zstd", "--options", "zstd:compression-level=3,zstd:threads=0"]
- case .max: ["-J", "--options", "xz:compression-level=9,xz:threads=0"]
- }
- }
-
- /// Extension for auto-named output when `export`'s destination is a directory.
- public var fileExtension: String {
- switch self {
- case .fast: "tzst"
- case .max: "txz"
- }
- }
- }
+ // MARK: - Export
/// Regenerable staging artifacts that never need to travel in an export:
/// `.vphoned.signed` is re-staged on the next launch, and the CFW install
/// inputs/temp are consumed at install time (the result already lives in
/// `Disk.img`). Always excluded.
- static let exportExcludePatterns = ["*.vphoned.signed", "*cfw_input*", "*cfw_jb_input*", "*.cfw_temp*"]
-
- /// When `to` is an existing directory, the archive is written inside it as
- /// `<name>.<compression.fileExtension>`. Returns the resolved output URL.
///
- /// Runs as a two-stage `tar` pipeline (uncompressed producer → compressing
- /// consumer via bsdtar's `@-`) so `progress` can be driven off the
- /// uncompressed byte stream: it is called with `(bytesDone, totalBytes)`,
- /// where `totalBytes` is the bundle's on-disk logical size (minus excludes).
- @discardableResult
- public static func export(
- bundleNamed name: String,
- to outFile: URL,
- includeIPSW: Bool,
- compression: ExportCompression = .fast,
- in library: VPhoneLibrary,
- progress: ((Int64, Int64) -> Void)? = nil
- ) throws -> URL {
- _ = try library.bundle(named: name) // validate it exists
- var isDir: ObjCBool = false
- let outFile = FileManager.default.fileExists(atPath: outFile.path, isDirectory: &isDir) && isDir.boolValue
- ? outFile.appendingPathComponent("\(name).\(compression.fileExtension)")
- : outFile
-
- // gnutar (not the bsdtar-default pax): pax extended headers make the
- // consumer's `@-` reader misbid the stream as mtree ("Line too long")
- // on large members; gnutar also carries files >8 GB (ustar cannot).
- var producer = ["--format", "gnutar", "-cf", "-"]
- if !includeIPSW { producer += ["--exclude", "*_Restore*"] }
- for pattern in exportExcludePatterns { producer += ["--exclude", pattern] }
- producer += ["-C", library.root.path, name]
- let consumer = ["-cf", outFile.path] + compression.tarArgs + ["@-"]
-
- let total = progress != nil
- ? archivedLogicalSize(
- bundleDir: library.url(forName: name),
- libraryRoot: library.root,
- includeIPSW: includeIPSW)
- : 0
- let err = try VPhoneProcessRunner.runCountingTarPipe(
- producerArgs: producer, sourceFile: nil, consumerArgs: consumer
- ) { done in progress?(done, total) }
- if let err { throw VPhoneBundleOpsError.tarFailed(err) }
- return outFile
- }
-
- /// On-disk logical size of the members `export` will archive, mirroring the
- /// tar `--exclude` patterns so the progress total matches the streamed bytes.
- private static func archivedLogicalSize(
- bundleDir: URL,
- libraryRoot: URL,
- includeIPSW: Bool
- ) -> Int64 {
- let fm = FileManager.default
- guard let en = fm.enumerator(
- at: bundleDir,
- includingPropertiesForKeys: [.isRegularFileKey, .fileSizeKey]) else { return 0 }
- let prefix = libraryRoot.path.count + 1 // members are "<name>/..."
- var total: Int64 = 0
- for case let url as URL in en {
- let rel = String(url.path.dropFirst(prefix))
- if !includeIPSW, rel.contains("_Restore") { en.skipDescendants(); continue }
- if exportExcludePatterns.contains(where: { fnmatch($0, rel, 0) == 0 }) { continue }
- guard let vals = try? url.resourceValues(forKeys: [.isRegularFileKey, .fileSizeKey]),
- vals.isRegularFile == true else { continue }
- total += Int64(vals.fileSize ?? 0)
- }
- return total
- }
-
- /// Extracts (auto-detecting gzip/zstd/xz) into a private staging dir, then
- /// promotes the single top-level bundle to the library. Extracting first
- /// means the archive is decompressed once; `progress` is called with
- /// `(bytesDone, totalBytes)` as the compressed file is fed into `tar -x`,
- /// where `totalBytes` is the archive's size on disk.
- public static func importArchive(
- from inFile: URL,
- name: String?,
- in library: VPhoneLibrary,
- progress: ((Int64, Int64) -> Void)? = nil
- ) throws -> VPhoneBundle {
- let fm = FileManager.default
- // Fail fast when the destination name is already known (explicit rename).
- if let name {
- try requireValidName(name)
- if fm.fileExists(atPath: library.url(forName: name).path) {
- throw VPhoneLibraryError.alreadyExists(name: name)
- }
- }
-
- // Extract into a private staging dir so the archive's OWN top-level name
- // can never clobber/merge into an existing bundle of that name; only the
- // validated destination name is ever placed into the library.
- try fm.createDirectory(at: library.root, withIntermediateDirectories: true)
- let staging = library.root.appendingPathComponent(".import-\(UUID().uuidString)")
- try fm.createDirectory(at: staging, withIntermediateDirectories: true)
- defer { try? fm.removeItem(at: staging) }
-
- let total = progress != nil ? fileByteSize(inFile) : 0
- let err = try VPhoneProcessRunner.runCountingTarPipe(
- producerArgs: nil, sourceFile: inFile, consumerArgs: ["-xf", "-", "-C", staging.path]
- ) { done in progress?(done, total) }
- if let err { throw VPhoneBundleOpsError.tarFailed(err) }
-
- let entries = try fm.contentsOfDirectory(atPath: staging.path)
- guard entries.count == 1, let archived = entries.first else {
- throw VPhoneBundleOpsError.badArchive(
- "This archive is not a VM export. Choose an archive created by 'vphone-cli vm export'.")
- }
- let finalName = name ?? archived
- try requireValidName(finalName)
- let dst = library.url(forName: finalName)
- if fm.fileExists(atPath: dst.path) { throw VPhoneLibraryError.alreadyExists(name: finalName) }
- let extracted = staging.appendingPathComponent(archived)
- guard fm.fileExists(atPath: extracted.appendingPathComponent("config.plist").path) else {
- throw VPhoneBundleOpsError.badArchive(
- "This archive does not contain a valid VM. Choose an archive created by 'vphone-cli vm export'.")
- }
- let bundle = try VPhoneBundle.load(at: extracted)
- try fm.moveItem(at: extracted, to: dst)
- return VPhoneBundle(url: dst, manifest: bundle.manifest)
- }
-
- private static func fileByteSize(_ url: URL) -> Int64 {
- let size = (try? url.resourceValues(forKeys: [.fileSizeKey]))?.fileSize
- return Int64(size ?? 0)
- }
+ /// Export itself is `VPhoneBundleTransfer` in `VPhoneArchive` — it needs
+ /// libarchive, and this does not. The list stays here because it describes
+ /// what a bundle is, and `VPhoneRestoreInfo` is checked against it.
+ public static let exportExcludePatterns =
+ ["*.vphoned.signed", "*cfw_input*", "*cfw_jb_input*", "*.cfw_temp*"]
}
diff --git a/sources/VPhoneCore/VPhoneProcessRunner.swift b/sources/VPhoneCore/VPhoneProcessRunner.swift
index 069eab5e..284a714c 100644
--- a/sources/VPhoneCore/VPhoneProcessRunner.swift
+++ b/sources/VPhoneCore/VPhoneProcessRunner.swift
@@ -79,96 +79,16 @@ public enum VPhoneProcessRunner {
stderr: String(decoding: errBox.take(), as: UTF8.self))
}
- /// Stream an archive through a `/usr/bin/tar` consumer that reads on stdin,
- /// invoking `onBytes` with the running byte total so a caller can drive a
- /// progress bar off the *uncompressed* (export) or *compressed* (import)
- /// stream. The byte source is exactly one of:
- /// - `producerArgs`: a `tar` producing an uncompressed archive to a pipe
- /// (export → count uncompressed input; the consumer compresses via `@-`).
- /// - `sourceFile`: the archive file read directly (import → count the file
- /// as it is fed into `tar -x`).
- /// Returns the stderr of whichever stage exited nonzero (consumer first), or
- /// `nil` on success. SIGPIPE is ignored for the duration so a consumer that
- /// dies early surfaces as its exit status rather than killing this process.
- public static func runCountingTarPipe(
- producerArgs: [String]?,
- sourceFile: URL?,
- consumerArgs: [String],
- onBytes: ((Int64) -> Void)? = nil
- ) throws -> String? {
- let tar = URL(fileURLWithPath: "/usr/bin/tar")
- let prevPIPE = signal(SIGPIPE, SIG_IGN)
- defer { signal(SIGPIPE, prevPIPE) }
-
- let group = DispatchGroup()
-
- let consumer = Process()
- consumer.executableURL = tar
- consumer.arguments = consumerArgs
- let cIn = Pipe()
- consumer.standardInput = cIn
- consumer.standardOutput = FileHandle.nullDevice
- let cErr = Pipe()
- consumer.standardError = cErr
- let cErrBox = DataBox()
- group.enter()
- cErr.fileHandleForReading.readabilityHandler = { handle in
- let chunk = handle.availableData
- if chunk.isEmpty { handle.readabilityHandler = nil; group.leave() }
- else { cErrBox.append(chunk) }
- }
-
- var producer: Process?
- let source: FileHandle
- let pErrBox = DataBox()
- if let producerArgs {
- let p = Process()
- p.executableURL = tar
- p.arguments = producerArgs
- let pOut = Pipe()
- p.standardOutput = pOut
- let pErr = Pipe()
- p.standardError = pErr
- group.enter()
- pErr.fileHandleForReading.readabilityHandler = { handle in
- let chunk = handle.availableData
- if chunk.isEmpty { handle.readabilityHandler = nil; group.leave() }
- else { pErrBox.append(chunk) }
- }
- producer = p
- source = pOut.fileHandleForReading
- } else if let sourceFile {
- source = try FileHandle(forReadingFrom: sourceFile)
- } else {
- preconditionFailure("runCountingTarPipe: producerArgs or sourceFile required")
- }
-
- try consumer.run()
- try producer?.run()
-
- let sink = cIn.fileHandleForWriting
- var total: Int64 = 0
- while true {
- guard let chunk = try? source.read(upToCount: 1 << 20), !chunk.isEmpty else { break }
- do { try sink.write(contentsOf: chunk) } catch { break } // consumer died; status below
- total += Int64(chunk.count)
- onBytes?(total)
- }
- try? sink.close()
- try? source.close()
-
- producer?.waitUntilExit()
- consumer.waitUntilExit()
- group.wait()
-
- if consumer.terminationStatus != 0 {
- return String(decoding: cErrBox.take(), as: UTF8.self)
- }
- if let producer, producer.terminationStatus != 0 {
- return String(decoding: pErrBox.take(), as: UTF8.self)
- }
- return nil
- }
+ // `runCountingTarPipe` lived here: a two-stage `/usr/bin/tar` pipe with a
+ // byte counter between the stages, used only by `vm export` and
+ // `vm import`. Both now pack and unpack in-process through
+ // `VPhoneArchive`, which counts its own bytes, so the helper had no
+ // callers left. It is gone rather than kept: a public convenience for
+ // spawning tar is an invitation to shell out again, and the point of the
+ // migration was that a machine with no `zstd(1)` on PATH can still import
+ // a `.tzst`. The `/usr/bin/tar` call sites left in FirmwarePatcher unpack
+ // onto a mounted guest volume with --preserve-permissions; none of them
+ // ever went through here.
/// Run `executable args`, inheriting the parent's stdout/stderr so output
/// streams live to the terminal (for long-running tools: downloads, restore,
diff --git a/sources/VPhoneSign/VPhoneCodeSignature.swift b/sources/VPhoneSign/VPhoneCodeSignature.swift
new file mode 100644
index 00000000..6f8791da
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneCodeSignature.swift
@@ -0,0 +1,279 @@
+import CryptoKit
+import Foundation
+
+// MARK: - The embedded signature
+
+/// The SuperBlob that goes in `__LINKEDIT`: one CodeDirectory per hash, the
+/// designated requirement, a program's entitlements as XML and as DER, and
+/// for a real signature the CMS blob.
+///
+/// Every field and every size here was read off `ldid.cpp` (Procursus 2.1.5)
+/// and then checked against its output, because the guest's AMFI accepts
+/// what ldid writes and the sizes end up inside the hashed load commands:
+/// reserving one byte more than ldid does changes the CDHash.
+struct VPhoneCodeSignature {
+ enum Digest: Equatable {
+ case sha1, sha256
+
+ var size: Int { self == .sha1 ? 20 : 32 }
+ /// `CS_HASHTYPE_SHA1` / `CS_HASHTYPE_SHA256`.
+ var type: UInt8 { self == .sha1 ? 1 : 2 }
+
+ func hash(_ data: Data) -> Data {
+ self == .sha1 ? Data(Insecure.SHA1.hash(data: data)) : Data(SHA256.hash(data: data))
+ }
+ }
+
+ /// What the signature is issued under: the file's name, unless `-I` said
+ /// otherwise.
+ var identifier: String
+ /// The leaf certificate's organizational unit, which is the team ID.
+ /// Empty for an ad-hoc signature, and then the field is left at 0.
+ var teamIdentifier = ""
+ /// The requirements blob, already compiled: ldid's designated
+ /// requirement (`requirements(identifier:commonName:)`), or the empty
+ /// one `codesign` writes.
+ var requirementsBlob = Data()
+ var entitlements: (xml: Data, der: Data)?
+ /// `__TEXT,__info_plist`, hashed into slot 1 of whatever carries one.
+ var infoPlist: Data?
+ var executableSegmentFlags: UInt64 = 0
+ /// `CodeDirectory.flags`. ldid leaves it at 0; an Apple ad-hoc signature
+ /// sets `kSecCodeSignatureAdhoc`.
+ var flags: UInt32 = 0
+ /// Which CodeDirectories to write, in order. The first is slot 0 and the
+ /// rest are `CSSLOT_ALTERNATE`.
+ var digests: [Digest] = [.sha1, .sha256]
+ /// How much room to leave for the CMS blob, or nil for no CMS slot at
+ /// all, which is what ldid writes without `-K`. ldid reserves a flat
+ /// 0x3000 and pads whatever is left over, because the signature's size
+ /// has to be in the load commands before a CMS over the CodeDirectory
+ /// can exist. Zero is the empty wrapper `codesign` writes for an ad-hoc
+ /// signature.
+ var cmsReservation: Int?
+
+ private static let pageShift = 12
+ private static let pageSize = 1 << pageShift
+ /// `sizeof(struct Blob)` + `sizeof(struct CodeDirectory)` at v20400.
+ private static let directoryHeader = 8 + 80
+
+ // MARK: Sizing
+
+ /// What ldid reserves for the whole signature, before alignment to 16.
+ ///
+ /// The shape is ldid's: a running total that is re-aligned to 16 once
+ /// per hash, which is why the slack is not a constant.
+ func allocation(codeLimit: Int) -> Int {
+ let pages = (codeLimit + Self.pageSize - 1) / Self.pageSize
+ let special = specialSlots
+
+ var total = 12 // sizeof(struct SuperBlob)
+ total += 8 + requirementsBlob.count // its BlobIndex, and the blob itself
+ if let entitlements {
+ total += 8 + 8 + entitlements.xml.count
+ total += 8 + 8 + entitlements.der.count
+ }
+ var directory = 8 + Self.directoryHeader + identifier.utf8.count + 1
+ if !teamIdentifier.isEmpty {
+ directory += teamIdentifier.utf8.count + 1
+ }
+ for digest in digests {
+ total = (total + directory + (special + pages) * digest.size).aligned(to: 16)
+ }
+ if let cmsReservation {
+ total += 8 + 8 + cmsReservation
+ }
+ return total
+ }
+
+ /// The highest slot anything is hashed into, which is how many special
+ /// slots each CodeDirectory carries.
+ private var specialSlots: Int {
+ entitlements == nil ? 2 : 7
+ }
+
+ // MARK: Writing
+
+ /// The SuperBlob over `code`, which is the slice up to `codeLimit` with
+ /// its load commands already final.
+ ///
+ /// `cms` is given the primary CodeDirectory and the cdhashes of them all
+ /// and returns the blob to put in the signature slot; it is nil for an
+ /// ad-hoc signature, and for an Apple-style one it returns no bytes at
+ /// all, which is the empty wrapper `codesign` writes.
+ func blob(
+ code: Data,
+ codeLimit: Int,
+ executable: (base: UInt64, limit: UInt64),
+ cms: ((_ primary: Data, _ cdHashes: [Data]) throws -> Data)? = nil
+ ) throws -> Data {
+ var blobs: [(slot: UInt32, bytes: Data)] = [(2, requirementsBlob)]
+ if let entitlements {
+ blobs.append((5, Self.wrapped(0xFADE_7171, entitlements.xml)))
+ blobs.append((7, Self.wrapped(0xFADE_7172, entitlements.der)))
+ }
+
+ var directories: [Data] = []
+ for (index, digest) in digests.enumerated() {
+ let directory = self.directory(
+ digest: digest, code: code, codeLimit: codeLimit, executable: executable, blobs: blobs
+ )
+ directories.append(directory)
+ blobs.append((index == 0 ? 0 : 0x1000 + UInt32(index) - 1, directory))
+ }
+
+ if let cms, let primary = directories.first {
+ // each CodeDirectory hashed with its own digest, at full length:
+ // the attribute that carries them truncates to 20 bytes itself
+ let cdHashes = zip(digests, directories).map { $0.hash($1) }
+ blobs.append((0x10000, Self.wrapped(0xFADE_0B01, try cms(primary, cdHashes))))
+ }
+
+ // ldid keeps the blobs in a map, so they come out in slot order
+ blobs.sort { $0.slot < $1.slot }
+ var superBlob = Data()
+ superBlob.appendBigEndian(0xFADE_0CC0 as UInt32)
+ superBlob.appendBigEndian(UInt32(12 + 8 * blobs.count + blobs.reduce(0) { $0 + $1.bytes.count }))
+ superBlob.appendBigEndian(UInt32(blobs.count))
+ var offset = 12 + 8 * blobs.count
+ for blob in blobs {
+ superBlob.appendBigEndian(blob.slot)
+ superBlob.appendBigEndian(UInt32(offset))
+ offset += blob.bytes.count
+ }
+ return blobs.reduce(superBlob) { $0 + $1.bytes }
+ }
+
+ private func directory(
+ digest: Digest,
+ code: Data,
+ codeLimit: Int,
+ executable: (base: UInt64, limit: UInt64),
+ blobs: [(slot: UInt32, bytes: Data)]
+ ) -> Data {
+ let identifierBytes = Data(identifier.utf8) + [0]
+ let teamBytes = teamIdentifier.isEmpty ? Data() : Data(teamIdentifier.utf8) + [0]
+ let special = specialSlots
+ let pages = (codeLimit + Self.pageSize - 1) / Self.pageSize
+ let size = Self.directoryHeader + identifierBytes.count + teamBytes.count
+ + (special + pages) * digest.size
+
+ var directory = Data()
+ directory.appendBigEndian(0xFADE_0C02 as UInt32)
+ directory.appendBigEndian(UInt32(size))
+ directory.appendBigEndian(0x0002_0400 as UInt32) // the version with an executable segment
+ directory.appendBigEndian(flags)
+ directory.appendBigEndian(UInt32(
+ Self.directoryHeader + identifierBytes.count + teamBytes.count + special * digest.size
+ )) // hashOffset
+ directory.appendBigEndian(UInt32(Self.directoryHeader)) // identOffset
+ directory.appendBigEndian(UInt32(special))
+ directory.appendBigEndian(UInt32(pages))
+ directory.appendBigEndian(UInt32(codeLimit))
+ directory.append(contentsOf: [UInt8(digest.size), digest.type, 0, UInt8(Self.pageShift)])
+ directory.appendBigEndian(0 as UInt32) // spare2
+ directory.appendBigEndian(0 as UInt32) // scatterOffset
+ directory.appendBigEndian(teamBytes.isEmpty
+ ? 0
+ : UInt32(Self.directoryHeader + identifierBytes.count)) // teamIDOffset
+ directory.appendBigEndian(0 as UInt32) // spare3
+ directory.appendBigEndian(0 as UInt64) // codeLimit64, zero below 4 GiB
+ directory.appendBigEndian(executable.base)
+ directory.appendBigEndian(executable.limit)
+ directory.appendBigEndian(executableSegmentFlags)
+ directory.append(identifierBytes)
+ directory.append(teamBytes)
+
+ // The special slots count down in front of the page hashes: slot 1
+ // nearest them, the highest slot first. Whatever is in no slot stays
+ // zero, which is how ldid leaves 3, 4 and 6.
+ for slot in (1 ... special).reversed() {
+ let hashed = slot == 1 ? infoPlist : blobs.first { $0.slot == UInt32(slot) }?.bytes
+ directory.append(hashed.map(digest.hash) ?? Data(count: digest.size))
+ }
+ for start in stride(from: 0, to: codeLimit, by: Self.pageSize) {
+ directory.append(digest.hash(code.subdata(in: start ..< min(start + Self.pageSize, codeLimit))))
+ }
+ return directory
+ }
+
+ private static func wrapped(_ magic: UInt32, _ content: Data) -> Data {
+ var blob = Data()
+ blob.appendBigEndian(magic)
+ blob.appendBigEndian(UInt32(8 + content.count))
+ return blob + content
+ }
+
+ /// `identifier "<identifier>" and anchor apple generic and certificate
+ /// leaf[subject.CN] = "<common name>" and certificate
+ /// 1[field.1.2.840.113635.100.6.2.1]`, compiled: what ldid writes for
+ /// every file it signs, with the identifier and — under `-K` — the
+ /// leaf's common name the only parts that vary.
+ static func requirements(identifier: String, commonName: String) -> Data {
+ func padded(_ bytes: some Sequence<UInt8>) -> Data {
+ let data = Data(bytes)
+ return data + Data(count: (4 - data.count % 4) % 4)
+ }
+ var expression = Data()
+ expression.appendBigEndian(6 as UInt32) // and
+ expression.appendBigEndian(2 as UInt32) // identifier
+ expression.appendBigEndian(UInt32(identifier.utf8.count))
+ expression.append(padded(identifier.utf8))
+ expression.appendBigEndian(6 as UInt32) // and
+ expression.appendBigEndian(15 as UInt32) // anchor apple generic
+ expression.appendBigEndian(6 as UInt32) // and
+ expression.appendBigEndian(11 as UInt32) // certificate field
+ expression.appendBigEndian(0 as UInt32) // of the leaf
+ expression.appendBigEndian(10 as UInt32)
+ expression.append(padded("subject.CN".utf8))
+ expression.appendBigEndian(1 as UInt32) // equal
+ expression.appendBigEndian(UInt32(commonName.utf8.count))
+ expression.append(padded(commonName.utf8))
+ expression.appendBigEndian(14 as UInt32) // certificate generic
+ expression.appendBigEndian(1 as UInt32) // the one above the leaf
+ expression.appendBigEndian(10 as UInt32)
+ expression.append(padded([0x2A, 0x86, 0x48, 0x86, 0xF7, 0x63, 0x64, 0x06, 0x02, 0x01]))
+ expression.appendBigEndian(0 as UInt32) // exists
+
+ var requirements = Data()
+ requirements.appendBigEndian(0xFADE_0C01 as UInt32)
+ requirements.appendBigEndian(UInt32(20 + 12 + expression.count))
+ requirements.appendBigEndian(1 as UInt32) // one requirement
+ requirements.appendBigEndian(3 as UInt32) // the designated one
+ requirements.appendBigEndian(20 as UInt32) // where it starts
+ requirements.appendBigEndian(0xFADE_0C00 as UInt32)
+ requirements.appendBigEndian(UInt32(12 + expression.count))
+ requirements.appendBigEndian(1 as UInt32) // an expression
+ return requirements + expression
+ }
+
+ /// An empty requirements blob, which is what `codesign` writes for an
+ /// ad-hoc signature: no designated requirement, so the implicit one (the
+ /// cdhash) applies and `codesign --verify` is satisfied.
+ static var emptyRequirements: Data {
+ var requirements = Data()
+ requirements.appendBigEndian(0xFADE_0C01 as UInt32)
+ requirements.appendBigEndian(12 as UInt32)
+ requirements.appendBigEndian(0 as UInt32)
+ return requirements
+ }
+
+ // MARK: Reading one back
+
+ /// The entitlements XML a signature carries, as ldid reads it: the last
+ /// blob in slot 5, and nothing where there is none.
+ static func entitlementsXML(in blob: Data) -> Data? {
+ guard blob.count >= 12 else { return nil }
+ let count = Int(blob.bigEndianValue(at: 8) as UInt32)
+ guard blob.holds(12, count * 8) else { return nil }
+ var found: Data?
+ for index in 0 ..< count where blob.bigEndianValue(at: 12 + index * 8) as UInt32 == 5 {
+ let offset = Int(blob.bigEndianValue(at: 16 + index * 8) as UInt32)
+ guard blob.holds(offset, 8) else { return nil }
+ let length = Int(blob.bigEndianValue(at: offset + 4) as UInt32)
+ guard length >= 8, blob.holds(offset, length) else { return nil }
+ found = blob.subdata(in: offset + 8 ..< offset + length)
+ }
+ return found
+ }
+}
diff --git a/sources/VPhoneSign/VPhoneMachOImage.swift b/sources/VPhoneSign/VPhoneMachOImage.swift
new file mode 100644
index 00000000..afb1863c
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneMachOImage.swift
@@ -0,0 +1,464 @@
+import Foundation
+import MachO
+
+// MARK: - One Mach-O slice
+
+/// A single architecture's image and the few facts a signer needs from it.
+///
+/// The parse is deliberately its own rather than a library's: everything
+/// below is read from offsets the file itself supplies, so each one is
+/// bounds-checked before it is used. A signer that trusts a malformed header
+/// writes a signature over the wrong bytes, which is worse than refusing.
+struct VPhoneMachOImage {
+ struct Segment {
+ /// Where the command sits among the load commands, counted from the
+ /// first byte after the header.
+ let commandOffset: Int
+ let name: String
+ let fileOffset: UInt64
+ let fileSize: UInt64
+ let initialProtection: Int32
+ /// File offsets and sizes of the segment's sections.
+ let sections: [(name: String, offset: UInt32, size: UInt64)]
+ }
+
+ /// Where this slice lives in the file it came from. A thin file is one
+ /// slice covering everything.
+ let range: Range<Int>
+ /// The slice's own bytes, header first.
+ let image: Data
+ let cpuType: cpu_type_t
+ let fileType: UInt32
+ let commandCount: UInt32
+ let commandsSize: Int
+ let segments: [Segment]
+ /// Every load command, in file order: the signature is written by laying
+ /// the command area out again, so each one's bytes have to be carried
+ /// over whether or not this signer understands it.
+ let commands: [(command: UInt32, offset: Int, size: Int)]
+ /// Where the existing signature starts and the command that points at
+ /// it, or nil for a file that was never signed.
+ let signature: (commandOffset: Int, dataOffset: Int, dataSize: Int)?
+ /// One past the end of the string table, which is where ldid ends the
+ /// code. nil when the slice has no symbol table, or an empty one.
+ let stringTableEnd: UInt64?
+ /// Which CodeDirectories ldid would write for this slice, from its
+ /// deployment target (see `digests(in:command:at:size:)`).
+ let digests: [VPhoneCodeSignature.Digest]
+
+ private static let headerSize = MemoryLayout<mach_header_64>.size
+ private static let linkedit = "__LINKEDIT"
+
+ // MARK: Parsing
+
+ /// Parses the slice at `range` of `file`.
+ init(file: Data, range: Range<Int>) throws {
+ guard file.holds(range.lowerBound, range.count), range.count >= Self.headerSize else {
+ throw VPhoneSignError.malformed("slice at \(range.lowerBound) runs past the end of the file")
+ }
+ let image = file.subdata(in: range)
+ let magic: UInt32 = image.littleEndianValue(at: 0)
+ guard magic == MH_MAGIC_64 else {
+ guard magic == MH_MAGIC || magic == MH_CIGAM || magic == MH_CIGAM_64 else {
+ throw VPhoneSignError.notMachO("slice at \(range.lowerBound) has magic 0x\(String(magic, radix: 16))")
+ }
+ throw VPhoneSignError.unsupportedSlice("slice at \(range.lowerBound) is not 64-bit little-endian")
+ }
+
+ self.range = range
+ self.image = image
+ cpuType = cpu_type_t(bitPattern: image.littleEndianValue(at: 4) as UInt32)
+ fileType = image.littleEndianValue(at: 12)
+ commandCount = image.littleEndianValue(at: 16)
+ commandsSize = Int(image.littleEndianValue(at: 20) as UInt32)
+ guard Self.headerSize + commandsSize <= image.count else {
+ throw VPhoneSignError.malformed("load commands run past the end of the slice")
+ }
+
+ var segments: [Segment] = []
+ var commands: [(command: UInt32, offset: Int, size: Int)] = []
+ var signature: (Int, Int, Int)?
+ var stringTableEnd: UInt64?
+ var digests: [VPhoneCodeSignature.Digest]?
+ var cursor = 0
+ for _ in 0 ..< commandCount {
+ guard cursor + 8 <= commandsSize else {
+ throw VPhoneSignError.malformed("a load command starts past the end of the command area")
+ }
+ let start = Self.headerSize + cursor
+ let command: UInt32 = image.littleEndianValue(at: start)
+ let size = Int(image.littleEndianValue(at: start + 4) as UInt32)
+ guard size >= 8, size % 8 == 0, cursor + size <= commandsSize else {
+ throw VPhoneSignError.malformed("load command 0x\(String(command, radix: 16)) has size \(size)")
+ }
+ commands.append((command, cursor, size))
+ if let choice = try Self.digests(in: image, command: command, at: start, size: size) {
+ // ldid lets the last one it reads decide
+ digests = choice
+ }
+ switch command {
+ case UInt32(LC_CODE_SIGNATURE):
+ guard size >= MemoryLayout<linkedit_data_command>.size else {
+ throw VPhoneSignError.malformed("LC_CODE_SIGNATURE is \(size) bytes")
+ }
+ signature = (
+ cursor,
+ Int(image.littleEndianValue(at: start + 8) as UInt32),
+ Int(image.littleEndianValue(at: start + 12) as UInt32)
+ )
+ case UInt32(LC_SYMTAB):
+ guard size >= MemoryLayout<symtab_command>.size else {
+ throw VPhoneSignError.malformed("LC_SYMTAB is \(size) bytes")
+ }
+ let offset: UInt32 = image.littleEndianValue(at: start + 16)
+ let length: UInt32 = image.littleEndianValue(at: start + 20)
+ // an all-zero symbol table is no symbol table, as ldid reads it
+ stringTableEnd = offset == 0 && length == 0 ? nil : UInt64(offset) + UInt64(length)
+ case UInt32(LC_SEGMENT_64):
+ segments.append(try Self.segment(in: image, at: start, commandOffset: cursor, size: size))
+ default:
+ break
+ }
+ cursor += size
+ }
+ self.segments = segments
+ self.commands = commands
+ self.signature = signature
+ self.stringTableEnd = stringTableEnd
+ self.digests = digests ?? [.sha1, .sha256]
+
+ if let signature {
+ guard image.holds(signature.1, signature.2) else {
+ throw VPhoneSignError.malformed("the existing signature runs past the end of the slice")
+ }
+ guard signature.1 + signature.2 == image.count else {
+ // ldid rewrites the file from the old signature's offset on,
+ // so anything after it would be dropped without notice
+ throw VPhoneSignError.malformed("the existing signature does not end the slice")
+ }
+ }
+ guard segments.contains(where: { $0.name == Self.linkedit }) else {
+ throw VPhoneSignError.malformed("no __LINKEDIT segment")
+ }
+ }
+
+ private static func segment(in image: Data, at start: Int, commandOffset: Int, size: Int) throws -> Segment {
+ guard size >= MemoryLayout<segment_command_64>.size else {
+ throw VPhoneSignError.malformed("LC_SEGMENT_64 is \(size) bytes")
+ }
+ let fileOffset: UInt64 = image.littleEndianValue(at: start + 40)
+ let fileSize: UInt64 = image.littleEndianValue(at: start + 48)
+ guard fileOffset <= UInt64(image.count), fileSize <= UInt64(image.count) - fileOffset else {
+ throw VPhoneSignError.malformed("a segment runs past the end of the slice")
+ }
+ let count = Int(image.littleEndianValue(at: start + 64) as UInt32)
+ let sectionSize = MemoryLayout<section_64>.size
+ guard MemoryLayout<segment_command_64>.size + count * sectionSize <= size else {
+ throw VPhoneSignError.malformed("a segment claims \(count) sections it has no room for")
+ }
+ var sections: [(String, UInt32, UInt64)] = []
+ for index in 0 ..< count {
+ let section = start + MemoryLayout<segment_command_64>.size + index * sectionSize
+ sections.append((
+ Self.name(in: image, at: section),
+ image.littleEndianValue(at: section + 48),
+ image.littleEndianValue(at: section + 40)
+ ))
+ }
+ return Segment(
+ commandOffset: commandOffset,
+ name: Self.name(in: image, at: start + 8),
+ fileOffset: fileOffset,
+ fileSize: fileSize,
+ initialProtection: Int32(bitPattern: image.littleEndianValue(at: start + 60) as UInt32),
+ sections: sections
+ )
+ }
+
+ /// Which CodeDirectories ldid writes, decided by a deployment-target
+ /// load command, or nil for a command that is not one.
+ ///
+ /// ldid drops SHA-1 for a target new enough to have stopped needing it,
+ /// and its test is `major >= 10 && minor >= 12` — written for macOS
+ /// 10.12 and never revisited, so a target of macOS 11 or later fails the
+ /// `minor` half and keeps SHA-1. That is not what the test means, but it
+ /// is what ldid does, and a signature that differs from ldid's in its
+ /// number of CodeDirectories has a different CDHash. So it is
+ /// reproduced, not corrected.
+ private static func digests(
+ in image: Data, command: UInt32, at start: Int, size: Int
+ ) throws -> [VPhoneCodeSignature.Digest]? {
+ /// A packed version: patch, minor, then major in the high 16 bits.
+ func version(_ value: UInt32) -> (major: UInt32, minor: UInt32) {
+ (value >> 16, (value >> 8) & 0xFF)
+ }
+ switch command {
+ case UInt32(LC_BUILD_VERSION):
+ guard size >= MemoryLayout<build_version_command>.size else {
+ throw VPhoneSignError.malformed("LC_BUILD_VERSION is \(size) bytes")
+ }
+ let platform: UInt32 = image.littleEndianValue(at: start + 8)
+ let (major, minor) = version(image.littleEndianValue(at: start + 12))
+ switch platform {
+ case UInt32(PLATFORM_MACOS) where major >= 10 && minor >= 12,
+ UInt32(PLATFORM_IOS) where major >= 11,
+ UInt32(PLATFORM_TVOS) where major >= 11:
+ return [.sha256]
+ default:
+ return [.sha1, .sha256]
+ }
+ case UInt32(LC_VERSION_MIN_MACOSX):
+ guard size >= MemoryLayout<version_min_command>.size else {
+ throw VPhoneSignError.malformed("LC_VERSION_MIN_MACOSX is \(size) bytes")
+ }
+ let (major, minor) = version(image.littleEndianValue(at: start + 8))
+ return major >= 10 && minor >= 12 ? [.sha256] : [.sha1, .sha256]
+ case UInt32(LC_VERSION_MIN_IPHONEOS), UInt32(LC_VERSION_MIN_TVOS):
+ guard size >= MemoryLayout<version_min_command>.size else {
+ throw VPhoneSignError.malformed("a version command is \(size) bytes")
+ }
+ return version(image.littleEndianValue(at: start + 8)).major >= 11 ? [.sha256] : [.sha1, .sha256]
+ default:
+ return nil
+ }
+ }
+
+ /// A 16-byte name field, which is NUL-padded and need not be terminated.
+ private static func name(in image: Data, at offset: Int) -> String {
+ String(decoding: image[offset ..< offset + 16].prefix { $0 != 0 }, as: UTF8.self)
+ }
+
+ // MARK: Facts the signer asks for
+
+ /// ldid's executable segment: from the first byte of any segment that
+ /// maps code to the last, in its own unsigned arithmetic.
+ var executableSegment: (base: UInt64, limit: UInt64) {
+ var base = UInt64.max
+ var end: UInt64 = 0
+ for segment in segments where segment.initialProtection & VM_PROT_EXECUTE != 0 {
+ base = min(base, segment.fileOffset)
+ end = max(end, segment.fileOffset &+ segment.fileSize)
+ }
+ return (base, end &- base)
+ }
+
+ /// `__TEXT,__info_plist`, which ldid hashes into the info slot of
+ /// whatever carries one. The last one wins, as it does there.
+ var infoPlist: Data? {
+ var found: (UInt64, UInt64)?
+ for segment in segments where segment.name == "__TEXT" {
+ for section in segment.sections where section.name == "__info_plist" {
+ found = (segment.fileOffset &+ UInt64(section.offset), section.size)
+ }
+ }
+ // ldid cuts the offset to 32 bits before it reads there
+ guard let found else { return nil }
+ let start = Int(UInt32(truncatingIfNeeded: found.0))
+ guard image.holds(start, Int(found.1)) else { return nil }
+ return image.subdata(in: start ..< start + Int(found.1))
+ }
+
+ /// The XML in the old signature's entitlements slot, read as ldid reads
+ /// it: the last blob in slot 5, nothing where there is none, and the
+ /// SuperBlob's own magic unchecked.
+ var embeddedEntitlements: Data? {
+ guard let signature, signature.dataSize >= 12 else { return nil }
+ let blob = image.subdata(in: signature.dataOffset ..< signature.dataOffset + signature.dataSize)
+ return VPhoneCodeSignature.entitlementsXML(in: blob)
+ }
+
+ /// How far ldid lets the code reach: the end of the string table, or the
+ /// start of the signature it is replacing.
+ func codeEnd() throws -> Int {
+ let signatureStart = signature.map(\.dataOffset) ?? image.count
+ guard let stringTableEnd else { return signatureStart }
+ // ldid adds the string table up in 32 bits and asserts it is not
+ // past the old signature
+ guard stringTableEnd <= UInt64(UInt32.max), stringTableEnd <= UInt64(signatureStart) else {
+ throw VPhoneSignError.malformed("the string table ends past the signature")
+ }
+ return Int(stringTableEnd)
+ }
+
+ /// The alignment ldid rounds `__LINKEDIT`'s vmsize to: the slice's own
+ /// in a fat file, and in a thin one what it takes the CPU's page to be.
+ var linkeditAlignment: Int {
+ switch cpuType {
+ case CPU_TYPE_ARM, CPU_TYPE_ARM64, CPU_TYPE_ARM64_32: 14
+ case CPU_TYPE_X86, CPU_TYPE_X86_64, CPU_TYPE_POWERPC, CPU_TYPE_POWERPC64: 12
+ default: 0
+ }
+ }
+
+ // MARK: Rewriting
+
+ /// The slice with `makeSignature` laid over it, `__LINKEDIT` grown to
+ /// hold it and the load command pointing at it.
+ ///
+ /// The signature's length has to be known before anything is hashed —
+ /// the load commands carry it and are themselves hashed — so the caller
+ /// supplies a size first and the bytes second.
+ func signed(
+ alignment: Int,
+ signatureSize: (_ codeLimit: Int) -> Int,
+ makeSignature: (_ code: Data, _ codeLimit: Int) throws -> Data
+ ) throws -> Data {
+ let codeEnd = try codeEnd()
+ let codeLimit = codeEnd.aligned(to: 16)
+ let size = signatureSize(codeLimit).aligned(to: 16)
+
+ // ldid drops the old LC_CODE_SIGNATURE and puts a fresh one after
+ // every other command, so the command area is laid out again rather
+ // than patched in place. For a linker-produced file the command was
+ // last anyway and nothing moves.
+ let carried = commands.filter { $0.command != UInt32(LC_CODE_SIGNATURE) }
+ let commandSize = MemoryLayout<linkedit_data_command>.size
+ let rebuilt = carried.reduce(0) { $0 + $1.size } + commandSize
+
+ // Whatever holds content has to start after the commands. The check
+ // comes before anything is written: a section over them is exactly
+ // what a command area that grew would overwrite.
+ let content = segments.flatMap { segment in
+ segment.sections.map { UInt64($0.offset) }
+ + (segment.sections.isEmpty && segment.fileSize > 0 ? [segment.fileOffset] : [])
+ }
+ let firstContent = content.filter { $0 > 0 }.min() ?? 0
+ guard UInt64(Self.headerSize + max(rebuilt, commandsSize)) <= firstContent, firstContent <= UInt64(codeEnd) else {
+ throw VPhoneSignError.noRoom("content starts at \(firstContent), \(Self.headerSize + rebuilt) bytes of commands")
+ }
+
+ var area = Data()
+ for command in carried {
+ var bytes = image.subdata(in: Self.headerSize + command.offset ..< Self.headerSize + command.offset + command.size)
+ // ldid sets the size of every __LINKEDIT there is
+ if command.command == UInt32(LC_SEGMENT_64), Self.name(in: bytes, at: 8) == Self.linkedit {
+ let start: UInt64 = bytes.littleEndianValue(at: 40)
+ let end = UInt64(codeLimit + size)
+ guard start < end else {
+ throw VPhoneSignError.malformed("__LINKEDIT starts past the end of the signature")
+ }
+ let grown = Int(end - start)
+ bytes.storeLittleEndian(UInt64(grown.aligned(to: 1 << alignment)), at: 32)
+ bytes.storeLittleEndian(UInt64(grown), at: 48)
+ }
+ area.append(bytes)
+ }
+ var signatureCommand = Data(count: commandSize)
+ signatureCommand.storeLittleEndian(UInt32(LC_CODE_SIGNATURE), at: 0)
+ signatureCommand.storeLittleEndian(UInt32(commandSize), at: 4)
+ signatureCommand.storeLittleEndian(UInt32(codeLimit), at: 8)
+ signatureCommand.storeLittleEndian(UInt32(size), at: 12)
+ area.append(signatureCommand)
+ // a command area that shrank is padded back out, as ldid pads it, so
+ // that what follows stays where the rest of the file expects it
+ area.append(Data(count: max(0, commandsSize - rebuilt)))
+
+ var code = image.prefix(codeEnd) + Data(count: codeLimit - codeEnd)
+ guard code.holds(Self.headerSize, area.count) else {
+ throw VPhoneSignError.noRoom("the slice ends inside the command area")
+ }
+ code.replaceSubrange(Self.headerSize ..< Self.headerSize + area.count, with: area)
+ code.storeLittleEndian(UInt32(carried.count + 1), at: 16)
+ code.storeLittleEndian(UInt32(rebuilt), at: 20)
+
+ let blob = try makeSignature(code, codeLimit)
+ guard blob.count <= size else {
+ throw VPhoneSignError.malformed("the signature grew between being measured and being written")
+ }
+ return code + blob + Data(count: size - blob.count)
+ }
+}
+
+// MARK: - A whole file
+
+/// A Mach-O file, thin or fat, and the slices to sign.
+struct VPhoneMachOFile {
+ /// A fat slice's architecture as the fat header spells it, which is what
+ /// the file is laid out again from.
+ struct Architecture {
+ let cpuType: UInt32
+ let cpuSubtype: UInt32
+ let alignment: UInt32
+ }
+
+ let slices: [VPhoneMachOImage]
+ /// nil for a thin file.
+ let architectures: [Architecture]?
+
+ init(data: Data) throws {
+ // Every offset below is counted from the start of the file, so a
+ // slice whose indices do not start at zero has to be copied first:
+ // Data keeps the parent's indices, and reading `data[0]` of one
+ // would either trap or read the wrong byte.
+ let data = data.startIndex == 0 ? data : Data(data)
+ guard data.count >= 8 else {
+ throw VPhoneSignError.notMachO("the file is \(data.count) bytes")
+ }
+ let magic: UInt32 = data.littleEndianValue(at: 0)
+ switch magic {
+ case FAT_CIGAM:
+ let count = Int(data.bigEndianValue(at: 4) as UInt32)
+ let size = MemoryLayout<fat_arch>.size
+ // A Java class file opens with the same four bytes, and its next
+ // two hold a version rather than a count. ldid's own bound is 20
+ // architectures; past that this is not a fat Mach-O.
+ guard (1 ..< 20).contains(count) else {
+ throw VPhoneSignError.notMachO("a fat header claiming \(count) architectures")
+ }
+ guard data.holds(8, count * size) else {
+ throw VPhoneSignError.malformed("a fat header of \(count) architectures does not fit")
+ }
+ var architectures: [Architecture] = []
+ var slices: [VPhoneMachOImage] = []
+ for index in 0 ..< count {
+ let entry = 8 + index * size
+ let offset = Int(data.bigEndianValue(at: entry + 8) as UInt32)
+ let length = Int(data.bigEndianValue(at: entry + 12) as UInt32)
+ let alignment: UInt32 = data.bigEndianValue(at: entry + 16)
+ guard data.holds(offset, length) else {
+ throw VPhoneSignError.malformed("architecture \(index) runs past the end of the file")
+ }
+ guard alignment <= 30 else {
+ throw VPhoneSignError.malformed("architecture \(index) is aligned to 2^\(alignment)")
+ }
+ architectures.append(Architecture(
+ cpuType: data.bigEndianValue(at: entry),
+ cpuSubtype: data.bigEndianValue(at: entry + 4),
+ alignment: alignment
+ ))
+ slices.append(try VPhoneMachOImage(file: data, range: offset ..< offset + length))
+ }
+ self.architectures = architectures
+ self.slices = slices
+ case FAT_MAGIC, FAT_CIGAM_64, FAT_MAGIC_64:
+ throw VPhoneSignError.unsupportedSlice("a fat file this signer does not read")
+ default:
+ architectures = nil
+ slices = [try VPhoneMachOImage(file: data, range: 0 ..< data.count)]
+ }
+ }
+
+ /// The file rebuilt from `images`, one per slice. ldid lays the slices
+ /// out again, each on its own alignment.
+ func assembled(_ images: [Data]) throws -> Data {
+ guard let architectures else { return images[0] }
+ var header = Data()
+ header.appendBigEndian(FAT_MAGIC)
+ header.appendBigEndian(UInt32(images.count))
+ var body = Data()
+ let bodyStart = 8 + images.count * MemoryLayout<fat_arch>.size
+ for (architecture, image) in zip(architectures, images) {
+ let offset = (bodyStart + body.count).aligned(to: 1 << Int(architecture.alignment))
+ body.append(Data(count: offset - bodyStart - body.count))
+ body.append(image)
+ // a fat header counts in 32 bits, so a file this size has none
+ guard let start = UInt32(exactly: offset), let size = UInt32(exactly: image.count) else {
+ throw VPhoneSignError.malformed("a slice does not fit a 32-bit fat header")
+ }
+ for field in [architecture.cpuType, architecture.cpuSubtype, start, size, architecture.alignment] {
+ header.appendBigEndian(field)
+ }
+ }
+ return header + body
+ }
+}
diff --git a/sources/VPhoneSign/VPhoneSignBytes.swift b/sources/VPhoneSign/VPhoneSignBytes.swift
new file mode 100644
index 00000000..72546d9a
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneSignBytes.swift
@@ -0,0 +1,47 @@
+import Foundation
+
+// MARK: - Byte access
+
+// Mach-O fields are little-endian in every slice this signs; code signing
+// structures are big-endian whatever the slice is. Keeping the two spellings
+// apart in the names is the only thing that stops them being mixed up.
+
+extension Data {
+ /// A Mach-O field.
+ func littleEndianValue<T: FixedWidthInteger>(at offset: Int) -> T {
+ precondition(offset >= 0 && offset + MemoryLayout<T>.size <= count)
+ return T(littleEndian: withUnsafeBytes {
+ $0.loadUnaligned(fromByteOffset: offset, as: T.self)
+ })
+ }
+
+ /// A code signing field.
+ func bigEndianValue<T: FixedWidthInteger>(at offset: Int) -> T {
+ precondition(offset >= 0 && offset + MemoryLayout<T>.size <= count)
+ return T(bigEndian: withUnsafeBytes {
+ $0.loadUnaligned(fromByteOffset: offset, as: T.self)
+ })
+ }
+
+ /// True when `offset ..< offset + length` is inside the data. Every read
+ /// of a value whose offset came out of the file goes through this first.
+ func holds(_ offset: Int, _ length: Int) -> Bool {
+ offset >= 0 && length >= 0 && offset <= count && length <= count - offset
+ }
+
+ mutating func storeLittleEndian(_ value: some FixedWidthInteger, at offset: Int) {
+ Swift.withUnsafeBytes(of: value.littleEndian) {
+ replaceSubrange(offset ..< offset + $0.count, with: $0)
+ }
+ }
+
+ mutating func appendBigEndian(_ value: some FixedWidthInteger) {
+ Swift.withUnsafeBytes(of: value.bigEndian) { append(contentsOf: $0) }
+ }
+}
+
+extension Int {
+ func aligned(to boundary: Int) -> Int {
+ (self + boundary - 1) / boundary * boundary
+ }
+}
diff --git a/sources/VPhoneSign/VPhoneSignDER.swift b/sources/VPhoneSign/VPhoneSignDER.swift
new file mode 100644
index 00000000..bc6138df
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneSignDER.swift
@@ -0,0 +1,212 @@
+import Foundation
+
+// MARK: - Just enough ASN.1
+
+/// A DER reader and writer sized to what code signing needs: walking a
+/// PKCS#12, pulling two names and a serial number out of a certificate, and
+/// writing a CMS SignedData.
+///
+/// It is here rather than a library because the whole point of `VPhoneSign`
+/// is that the signer links nothing outside the system frameworks, and
+/// because DER is small when you only need definite-length encodings.
+enum VPhoneDER {
+ /// One element: its tag, where its value is, and where the whole thing
+ /// ends in the buffer it was read from.
+ struct Element {
+ let tag: UInt8
+ /// The value, with the tag and length stripped.
+ let content: Data
+ /// The element including its tag and length, which is what has to be
+ /// carried over verbatim when one structure is embedded in another.
+ let encoded: Data
+ /// Where the next element starts.
+ let end: Int
+
+ var isConstructed: Bool { tag & 0x20 != 0 }
+ }
+
+ // MARK: Reading
+
+ /// The element starting at `index`. `data` must be 0-based.
+ static func element(in data: Data, at index: Int) throws -> Element {
+ guard data.holds(index, 2) else { throw VPhoneSignError.identityUnreadable("a DER element runs off the end") }
+ let tag = data[index]
+ var cursor = index + 1
+ let first = data[cursor]
+ cursor += 1
+ var length = Int(first)
+ if first & 0x80 != 0 {
+ let count = Int(first & 0x7F)
+ // an indefinite length is BER, not DER, and nothing here writes one
+ guard count > 0, count <= 4, data.holds(cursor, count) else {
+ throw VPhoneSignError.identityUnreadable("a DER length this reader does not accept")
+ }
+ length = 0
+ for _ in 0 ..< count {
+ length = length << 8 | Int(data[cursor])
+ cursor += 1
+ }
+ }
+ guard data.holds(cursor, length) else {
+ throw VPhoneSignError.identityUnreadable("a DER element claims \(length) bytes it does not have")
+ }
+ return Element(
+ tag: tag,
+ content: data.subdata(in: cursor ..< cursor + length),
+ encoded: data.subdata(in: index ..< cursor + length),
+ end: cursor + length
+ )
+ }
+
+ /// Every element of a constructed value's content.
+ static func children(of content: Data) throws -> [Element] {
+ var elements: [Element] = []
+ var cursor = 0
+ while cursor < content.count {
+ let element = try element(in: content, at: cursor)
+ elements.append(element)
+ cursor = element.end
+ }
+ return elements
+ }
+
+ /// The dotted form of an OBJECT IDENTIFIER's content, for comparing
+ /// against the constants below.
+ static func objectIdentifier(_ content: Data) -> String {
+ guard let first = content.first else { return "" }
+ var parts = ["\(first / 40)", "\(first % 40)"]
+ var value = 0
+ for byte in content.dropFirst() {
+ value = value << 7 | Int(byte & 0x7F)
+ if byte & 0x80 == 0 {
+ parts.append("\(value)")
+ value = 0
+ }
+ }
+ return parts.joined(separator: ".")
+ }
+
+ /// An INTEGER's value, for the small ones this reads (iteration counts,
+ /// key lengths, versions).
+ static func integer(_ content: Data) throws -> Int {
+ guard !content.isEmpty, content.count <= 8 else {
+ throw VPhoneSignError.identityUnreadable("an INTEGER of \(content.count) bytes")
+ }
+ return content.reduce(0) { $0 << 8 | Int($1) }
+ }
+
+ // MARK: Writing
+
+ static func encode(_ tag: UInt8, _ content: Data) -> Data {
+ var out = Data([tag])
+ if content.count < 0x80 {
+ out.append(UInt8(content.count))
+ } else {
+ var length = Data()
+ var value = content.count
+ while value > 0 {
+ length.insert(UInt8(value & 0xFF), at: 0)
+ value >>= 8
+ }
+ out.append(0x80 | UInt8(length.count))
+ out.append(length)
+ }
+ return out + content
+ }
+
+ static func sequence(_ elements: [Data]) -> Data {
+ encode(0x30, elements.reduce(Data(), +))
+ }
+
+ /// DER sorts a SET OF by the encoded bytes of its members, which is what
+ /// a verifier re-derives the digest over.
+ static func setOf(_ elements: [Data]) -> Data {
+ encode(0x31, elements.sorted { left, right in
+ left.lexicographicallyPrecedes(right)
+ }.reduce(Data(), +))
+ }
+
+ static func octetString(_ content: Data) -> Data { encode(0x04, content) }
+
+ static func integer(_ value: Int) -> Data {
+ var bytes: [UInt8] = []
+ var value = value
+ repeat {
+ bytes.insert(UInt8(value & 0xFF), at: 0)
+ value >>= 8
+ } while value > 0
+ // DER integers are signed, so a leading bit set needs a zero byte
+ if bytes[0] & 0x80 != 0 {
+ bytes.insert(0, at: 0)
+ }
+ return encode(0x02, Data(bytes))
+ }
+
+ static func objectIdentifier(dotted: String) -> Data {
+ let parts = dotted.split(separator: ".").compactMap { Int($0) }
+ var content = Data([UInt8(parts[0] * 40 + parts[1])])
+ for part in parts.dropFirst(2) {
+ var chunk: [UInt8] = [UInt8(part & 0x7F)]
+ var value = part >> 7
+ while value > 0 {
+ chunk.insert(UInt8(value & 0x7F) | 0x80, at: 0)
+ value >>= 7
+ }
+ content.append(contentsOf: chunk)
+ }
+ return encode(0x06, content)
+ }
+
+ /// An AlgorithmIdentifier with the explicit NULL parameters the RSA and
+ /// SHA OIDs carry in a CMS structure.
+ static func algorithm(_ oid: String, parameters: Data = Data([0x05, 0x00])) -> Data {
+ sequence([objectIdentifier(dotted: oid), parameters])
+ }
+
+ /// A UTCTime, which is what CMS uses for a signing time before 2050.
+ static func utcTime(_ date: Date) -> Data {
+ var calendar = Calendar(identifier: .gregorian)
+ calendar.timeZone = TimeZone(identifier: "UTC")!
+ let parts = calendar.dateComponents([.year, .month, .day, .hour, .minute, .second], from: date)
+ let text = String(
+ format: "%02d%02d%02d%02d%02d%02dZ",
+ parts.year! % 100, parts.month!, parts.day!, parts.hour!, parts.minute!, parts.second!
+ )
+ return encode(0x17, Data(text.utf8))
+ }
+
+ // MARK: The OIDs this deals in
+
+ enum OID {
+ static let data = "1.2.840.113549.1.7.1"
+ static let signedData = "1.2.840.113549.1.7.2"
+ static let encryptedData = "1.2.840.113549.1.7.6"
+ static let contentType = "1.2.840.113549.1.9.3"
+ static let messageDigest = "1.2.840.113549.1.9.4"
+ static let signingTime = "1.2.840.113549.1.9.5"
+ static let sha256 = "2.16.840.1.101.3.4.2.1"
+ static let sha1 = "1.3.14.3.2.26"
+ static let rsaEncryption = "1.2.840.113549.1.1.1"
+ static let sha256WithRSA = "1.2.840.113549.1.1.11"
+ static let pbes2 = "1.2.840.113549.1.5.13"
+ static let pbkdf2 = "1.2.840.113549.1.5.12"
+ static let hmacWithSHA1 = "1.2.840.113549.2.7"
+ static let hmacWithSHA224 = "1.2.840.113549.2.8"
+ static let hmacWithSHA256 = "1.2.840.113549.2.9"
+ static let hmacWithSHA384 = "1.2.840.113549.2.10"
+ static let hmacWithSHA512 = "1.2.840.113549.2.11"
+ static let aes128CBC = "2.16.840.1.101.3.4.1.2"
+ static let aes192CBC = "2.16.840.1.101.3.4.1.22"
+ static let aes256CBC = "2.16.840.1.101.3.4.1.42"
+ static let certBag = "1.2.840.113549.1.12.10.1.3"
+ static let keyBag = "1.2.840.113549.1.12.10.1.1"
+ static let shroudedKeyBag = "1.2.840.113549.1.12.10.1.2"
+ static let x509Certificate = "1.2.840.113549.1.9.22.1"
+ static let commonName = "2.5.4.3"
+ static let organizationalUnit = "2.5.4.11"
+ /// Apple's code signing hash agility attributes: the first carries a
+ /// plist of truncated cdhashes, the second one entry per digest.
+ static let hashAgility = "1.2.840.113635.100.9.1"
+ static let hashAgilityV2 = "1.2.840.113635.100.9.2"
+ }
+}
diff --git a/sources/VPhoneSign/VPhoneSignEntitlements.swift b/sources/VPhoneSign/VPhoneSignEntitlements.swift
new file mode 100644
index 00000000..88ba7c4c
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneSignEntitlements.swift
@@ -0,0 +1,262 @@
+import Foundation
+
+// MARK: - Entitlements
+
+/// A program's entitlements as `ldid -M -S<file>` treats them: read from the
+/// XML the old signature carries, merged with a file's, and written back as
+/// the XML and DER blobs of the new signature.
+///
+/// ldid reads and writes that XML with libplist, whose dictionary keeps its
+/// keys in the order they arrived and replaces a value where it stands, and
+/// whose reader keeps every byte of a string as it was. Foundation sorts the
+/// keys, and `XMLParser` folds line ends and reads entities its own way. So
+/// both directions are written here, the writer held to Foundation in
+/// everything but the order (`xml()`) and the DER ldid's own.
+///
+/// Ported from `Lakr233/Irisin`'s `LdidEntitlements`, which the fixtures
+/// there hold to `ldid` byte for byte.
+struct VPhoneSignEntitlements: Equatable {
+ enum Value: Equatable {
+ case boolean(Bool)
+ case integer(Integer)
+ case string(String)
+ case data(Data)
+ case array([Value])
+ case dictionary([Entry])
+ }
+
+ /// An `<integer>` held the way libplist holds one, because that is what
+ /// decides both of the things a signer has to reproduce.
+ ///
+ /// libplist keeps a single `uint64_t intval` and a `length` that is 8 or
+ /// 16. ldid asks for `intval` through `plist_get_uint_val` and encodes
+ /// that whole number, so the DER never sees a sign: `<integer>-1</integer>`
+ /// and `<integer>18446744073709551615</integer>` both come out
+ /// `0208ffffffffffffffff`. `plist_to_xml` is the half that remembers —
+ /// `%llu` when `length == 16`, `%lli` otherwise — so the same bits print
+ /// back as `-1` or as `18446744073709551615` depending on how they were
+ /// spelled. Both were checked against `ldid -S<file>` and the blob it
+ /// writes; see `Reader`'s `<integer>` case for the parse.
+ struct Integer: Equatable {
+ /// libplist's `intval`: a negative value in two's complement.
+ var raw: UInt64
+ /// libplist's `length == 16` — a value above `INT64_MAX` written
+ /// with no sign, which prints unsigned and nothing else does.
+ var isUnsigned: Bool
+
+ init(raw: UInt64, isUnsigned: Bool = false) {
+ self.raw = raw
+ self.isUnsigned = isUnsigned
+ }
+
+ /// What `plist_to_xml` prints.
+ var text: String {
+ isUnsigned ? "\(raw)" : "\(Int64(bitPattern: raw))"
+ }
+ }
+
+ struct Entry: Equatable {
+ var key: String
+ var value: Value
+ }
+
+ private(set) var entries: [Entry]
+
+ /// `xml` is what an entitlements file or a signature's slot 5 holds;
+ /// empty is no entitlements.
+ init(xml: Data) throws {
+ guard !xml.isEmpty else {
+ entries = []
+ return
+ }
+ var reader = Reader(xml)
+ entries = try reader.read()
+ }
+
+ var isEmpty: Bool { entries.isEmpty }
+
+ /// Merges `other` in as `-M` does: each of its keys set to its value
+ /// where the key already stands, appended where it does not.
+ mutating func merge(_ other: VPhoneSignEntitlements) {
+ for entry in other.entries {
+ if let index = entries.firstIndex(where: { $0.key.utf8.elementsEqual(entry.key.utf8) }) {
+ entries[index].value = entry.value
+ } else {
+ entries.append(entry)
+ }
+ }
+ }
+
+ /// The executable segment flags ldid derives: the main binary's for a
+ /// program's slice, and one for each entitlement that asks. ldid gives
+ /// can-execute-cdhash the bit of can-load-cdhash (0x100), and so does
+ /// this.
+ func executableSegmentFlags(mainBinary: Bool) -> UInt64 {
+ let flags: [(key: String, bit: UInt64)] = [
+ ("get-task-allow", 0x10), ("run-unsigned-code", 0x10), ("com.apple.private.cs.debugger", 0x20),
+ ("dynamic-codesigning", 0x40), ("com.apple.private.skip-library-validation", 0x80),
+ ("com.apple.private.amfi.can-load-cdhash", 0x100), ("com.apple.private.amfi.can-execute-cdhash", 0x100),
+ ]
+ return flags.reduce(mainBinary ? 1 : 0) { result, flag in
+ entries.first { $0.key.utf8.elementsEqual(flag.key.utf8) }?.value == .boolean(true) ? result | flag.bit : result
+ }
+ }
+
+ /// As libplist's `plist_to_xml` writes it, which is Foundation's XML to
+ /// the byte but in one thing: libplist keeps a dictionary's keys in the
+ /// order they arrived and Foundation sorts them, so Foundation cannot
+ /// write it. The writer here is held to Foundation on every call — the
+ /// same list with its keys in Foundation's order must come out as
+ /// `PropertyListSerialization` writes it — so every byte but the order
+ /// is Foundation's, and a list the two would write differently is
+ /// refused rather than signed.
+ func xml() throws -> Data {
+ let foundation = try? PropertyListSerialization.data(
+ fromPropertyList: Self.foundation(.dictionary(entries)), format: .xml, options: 0
+ )
+ guard Self.document(.dictionary(entries), sorted: true) == foundation else {
+ throw VPhoneSignError.unsupportedEntitlements("Foundation and libplist would write this list differently")
+ }
+ return Self.document(.dictionary(entries), sorted: false)
+ }
+
+ /// As ldid writes it: the dictionary a SET whose members are sorted as
+ /// encoded byte strings, not by key, and no wrapper around it.
+ var der: Data {
+ Data(Self.der(.dictionary(entries)))
+ }
+
+ // MARK: Writing
+
+ /// Tabs, only `<`, `>` and `&` escaped, an empty container closed on
+ /// itself; `sorted` puts keys in the UTF-16 order Foundation writes.
+ private static func document(_ value: Value, sorted: Bool) -> Data {
+ var out = Array("""
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+ <plist version="1.0">
+
+ """.utf8)
+ write(value, depth: 0, sorted: sorted, into: &out)
+ out += "</plist>\n".utf8
+ return Data(out)
+ }
+
+ /// The list as Foundation holds it. The keys stay `NSString`s, which
+ /// compare as UTF-16, so two spellings of one character stay two keys.
+ private static func foundation(_ value: Value) -> Any {
+ switch value {
+ case let .boolean(value): NSNumber(value: value)
+ // the same split libplist makes when it prints one, so Foundation
+ // spells 2^63 and above unsigned the way `plist_to_xml` does
+ case let .integer(value):
+ value.isUnsigned ? NSNumber(value: value.raw) : NSNumber(value: Int64(bitPattern: value.raw))
+ case let .string(value): NSString(string: value)
+ case let .data(value): NSData(data: value)
+ case let .array(values): NSArray(array: values.map(foundation))
+ case let .dictionary(entries):
+ NSDictionary(
+ objects: entries.map { foundation($0.value) },
+ forKeys: entries.map { NSString(string: $0.key) }
+ )
+ }
+ }
+
+ private static func write(_ value: Value, depth: Int, sorted: Bool, into out: inout [UInt8]) {
+ let indent = [UInt8](repeating: 0x09, count: depth)
+ out += indent
+ func text(_ tag: String, _ content: String) {
+ out += "<\(tag)>".utf8
+ for byte in content.utf8 {
+ switch byte {
+ case UInt8(ascii: "<"): out += "&lt;".utf8
+ case UInt8(ascii: ">"): out += "&gt;".utf8
+ case UInt8(ascii: "&"): out += "&amp;".utf8
+ default: out.append(byte)
+ }
+ }
+ out += "</\(tag)>\n".utf8
+ }
+ switch value {
+ case let .boolean(value):
+ out += (value ? "<true/>\n" : "<false/>\n").utf8
+ case let .integer(value):
+ out += "<integer>\(value.text)</integer>\n".utf8
+ case let .string(value):
+ text("string", value)
+ case let .data(value):
+ out += "<data>\n".utf8
+ // lines no wider than 76 columns counting a tab as 8, whole
+ // groups of three bytes each, at most eight tabs in
+ let lineIndent = [UInt8](repeating: 0x09, count: min(depth, 8))
+ let perLine = (76 - lineIndent.count * 8) / 4 * 3
+ for start in stride(from: 0, to: value.count, by: perLine) {
+ let line = value.dropFirst(start).prefix(perLine)
+ out += lineIndent + Data(line).base64EncodedString().utf8 + [0x0A]
+ }
+ out += indent + "</data>\n".utf8
+ case let .array(values):
+ guard !values.isEmpty else {
+ out += "<array/>\n".utf8
+ return
+ }
+ out += "<array>\n".utf8
+ for value in values {
+ write(value, depth: depth + 1, sorted: sorted, into: &out)
+ }
+ out += indent + "</array>\n".utf8
+ case let .dictionary(entries):
+ guard !entries.isEmpty else {
+ out += "<dict/>\n".utf8
+ return
+ }
+ out += "<dict>\n".utf8
+ for entry in sorted ? entries.sorted(by: { $0.key.utf16.lexicographicallyPrecedes($1.key.utf16) }) : entries {
+ out += indent + [0x09]
+ text("key", entry.key)
+ write(entry.value, depth: depth + 1, sorted: sorted, into: &out)
+ }
+ out += indent + "</dict>\n".utf8
+ }
+ }
+
+ private static func der(_ value: Value) -> [UInt8] {
+ switch value {
+ case let .boolean(value):
+ [0x01, 0x01, value ? 1 : 0]
+ case let .integer(value):
+ tagged(0x02, bigEndian(value.raw))
+ case let .string(value):
+ tagged(0x0C, Array(value.utf8))
+ case let .data(value):
+ tagged(0x04, Array(value))
+ case let .array(values):
+ tagged(0x30, values.flatMap(der))
+ case let .dictionary(entries):
+ tagged(
+ 0x31,
+ entries.map { tagged(0x30, tagged(0x0C, Array($0.key.utf8)) + der($0.value)) }
+ .sorted { $0.lexicographicallyPrecedes($1) }
+ .flatMap(\.self)
+ )
+ }
+ }
+
+ private static func tagged(_ tag: UInt8, _ content: [UInt8]) -> [UInt8] {
+ guard content.count >= 0x80 else { return [tag, UInt8(content.count)] + content }
+ let length = bigEndian(UInt64(content.count))
+ return [tag, 0x80 | UInt8(length.count)] + length + content
+ }
+
+ /// The fewest bytes that hold `value`, most significant first, and one
+ /// byte for zero. That last part is ldid's `bytes()`, which answers 1 for
+ /// 0 rather than 0, and is why `<integer>0</integer>` encodes as `020100`
+ /// and not as an INTEGER with no content. ldid writes no leading zero
+ /// pad either, so a value with its top bit set is not a DER-legal signed
+ /// INTEGER — 2^63 is `02088000000000000000`. Reproducing ldid means
+ /// reproducing that.
+ private static func bigEndian(_ value: UInt64) -> [UInt8] {
+ let bytes = Array(withUnsafeBytes(of: value.bigEndian, Array.init).drop { $0 == 0 })
+ return bytes.isEmpty ? [0] : bytes
+ }
+}
diff --git a/sources/VPhoneSign/VPhoneSignEntitlementsReader.swift b/sources/VPhoneSign/VPhoneSignEntitlementsReader.swift
new file mode 100644
index 00000000..3f8b2633
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneSignEntitlementsReader.swift
@@ -0,0 +1,383 @@
+import Foundation
+
+// MARK: - Reading entitlements the way libplist reads them
+
+extension VPhoneSignEntitlements {
+ /// The XML read as libplist's `plist_from_xml` reads it, for what an
+ /// entitlements file holds. What libplist reads its own way is refused
+ /// rather than guessed at: an entity it matches by the first letters,
+ /// text split by a comment or CDATA, a second key in a row, a key left
+ /// without a value, a byte that ends its C strings early, and elements
+ /// after an empty root, which it reads into that root. The rest it reads
+ /// as written here: every byte of a string kept (a CR too), the document
+ /// read up to the end of its root and no further, and an `<integer>` in
+ /// any base with any sign (`integer(_:)`).
+ ///
+ /// The refusals are deliberately stricter than ldid on one axis, measured
+ /// 2026-09-23: 28 `<integer>` spellings ldid takes are refused here — `08`,
+ /// `09`, `0x`, `42abc`, `1e3`, `0b101`, `0_1`, `12 34`, `&#52;2`, overflow
+ /// either way, and so on. Every one is a shape `plist_to_xml` and
+ /// CFPropertyList never emit, and no plist in this repo contains one, so
+ /// the `-M` path (which re-reads canonical decimal) and the `-e`-then-`-S`
+ /// installer flows are unaffected. The case it would bite is a
+ /// hand-written entitlements plist added later with, say, a leading zero:
+ /// that would abort a CFW build where ldid completed. If that happens the
+ /// answer is to fix the plist, not to loosen this.
+ ///
+ /// Ported from `Lakr233/Irisin`'s `LdidEntitlements.Reader`.
+ struct Reader {
+ /// A container being read.
+ private struct Frame {
+ let isDictionary: Bool
+ /// The key read for the next value of a dictionary.
+ var key: String?
+ var entries: [VPhoneSignEntitlements.Entry] = []
+ /// Where each key of `entries` stands, by its bytes.
+ var index: [[UInt8]: Int] = [:]
+ var values: [VPhoneSignEntitlements.Value] = []
+
+ /// As `plist_dict_set_item`: the value replaced where the key stands.
+ mutating func set(_ key: String, _ value: VPhoneSignEntitlements.Value) {
+ if let at = index[Array(key.utf8)] {
+ entries[at].value = value
+ } else {
+ index[Array(key.utf8)] = entries.count
+ entries.append(VPhoneSignEntitlements.Entry(key: key, value: value))
+ }
+ }
+ }
+
+ /// Deeper than any entitlements go, and shallow enough for the
+ /// writers' recursion on a small stack.
+ private static let depth = 64
+
+ private let bytes: [UInt8]
+ private var at = 0
+ private var stack: [Frame] = []
+ /// An empty root, which libplist reads past.
+ private var root: [VPhoneSignEntitlements.Entry]?
+
+ init(_ data: Data) {
+ bytes = Array(data)
+ }
+
+ private static func refuse(_ reason: String) -> VPhoneSignError {
+ .unsupportedEntitlements(reason)
+ }
+
+ /// The root dictionary's entries.
+ mutating func read() throws -> [VPhoneSignEntitlements.Entry] {
+ let entries = try document()
+ // libplist turns a lone CF$UID into a UID, which ldid refuses
+ if entries.count == 1, entries[0].key.utf8.elementsEqual("CF$UID".utf8), case .integer = entries[0].value {
+ throw Self.refuse("a lone CF$UID libplist would read as a UID")
+ }
+ return entries
+ }
+
+ private mutating func document() throws -> [VPhoneSignEntitlements.Entry] {
+ var inPlist = false
+ while true {
+ skipSpace()
+ guard at < bytes.count else { break }
+ try expect("<")
+ if try skipMarkup() {
+ continue
+ }
+ let (name, empty) = try tag()
+ switch name {
+ case "plist":
+ guard !empty, !inPlist, stack.isEmpty, root == nil else {
+ throw Self.refuse("a second <plist> element")
+ }
+ inPlist = true
+ case "/plist":
+ // reached only past an empty root: libplist stops at the
+ // end of any other
+ guard !empty, inPlist, root != nil else { throw Self.refuse("</plist> where no root was open") }
+ inPlist = false
+ case _ where root != nil:
+ throw Self.refuse("an element after an empty root, which libplist reads into that root")
+ case "dict", "array":
+ if empty {
+ try add(name == "dict" ? .dictionary([]) : .array([]))
+ } else {
+ try open(dictionary: name == "dict")
+ }
+ case "/dict", "/array":
+ guard !empty, let frame = stack.popLast(), frame.isDictionary == (name == "/dict"), frame.key == nil else {
+ throw Self.refuse("<\(name)> closes a container that is not open, or a key without a value")
+ }
+ guard !stack.isEmpty else {
+ // the root, a dictionary (`open`): libplist reads no further
+ return frame.entries
+ }
+ try add(frame.isDictionary ? .dictionary(frame.entries) : .array(frame.values))
+ case "key":
+ guard !empty, let top = stack.indices.last, stack[top].isDictionary, stack[top].key == nil else {
+ throw Self.refuse("a <key> outside a dictionary, or a second one in a row")
+ }
+ stack[top].key = try Self.string(text(closing: name, skippingSpace: false))
+ case "string":
+ let string = try empty ? "" : Self.string(text(closing: name, skippingSpace: false))
+ try add(.string(string))
+ case "integer":
+ guard !empty else { throw Self.refuse("an empty <integer/>") }
+ try add(.integer(Self.integer(text(closing: name, skippingSpace: true))))
+ case "data":
+ // libplist's decoder skips what it does not know; base64
+ // that reads back the same is what the two agree on
+ let encoded = try empty ? "" : String(
+ decoding: text(closing: name, skippingSpace: true).filter { !Self.isSpace($0) }, as: UTF8.self
+ )
+ guard let value = Data(base64Encoded: encoded), value.base64EncodedString() == encoded else {
+ throw Self.refuse("a <data> whose base64 does not read back the same")
+ }
+ try add(.data(value))
+ case "true", "false":
+ // libplist reads past any text in them; there is none here
+ guard try empty || text(closing: name, skippingSpace: true).isEmpty else {
+ throw Self.refuse("text inside <\(name)>")
+ }
+ try add(.boolean(name == "true"))
+ default:
+ // a real, a date and anything that is no plist element
+ throw Self.refuse("<\(name)>, which this signer does not carry into DER")
+ }
+ }
+ // the end of the document, fine only after an empty root
+ guard stack.isEmpty, !inPlist, let root else { throw Self.refuse("the document ends inside an element") }
+ return root
+ }
+
+ private mutating func open(dictionary: Bool) throws {
+ // a value in a dictionary needs its key, and the root is a dictionary
+ guard stack.count < Self.depth, stack.last.map({ !$0.isDictionary || $0.key != nil }) ?? dictionary else {
+ throw Self.refuse("a container too deep, or a dictionary value without a key")
+ }
+ stack.append(Frame(isDictionary: dictionary))
+ }
+
+ private mutating func add(_ value: VPhoneSignEntitlements.Value) throws {
+ guard let top = stack.indices.last else {
+ // a root that is not a container ends libplist's read, and
+ // one that is empty does not; only an empty dictionary is a
+ // dictionary
+ guard value == .dictionary([]) else { throw Self.refuse("a root that is not a dictionary") }
+ root = []
+ return
+ }
+ if stack[top].isDictionary {
+ guard let key = stack[top].key else { throw Self.refuse("a dictionary value without a key") }
+ stack[top].key = nil
+ stack[top].set(key, value)
+ } else {
+ stack[top].values.append(value)
+ }
+ }
+
+ /// A tag's name, read past its `<` as libplist reads it, and whether
+ /// it closes itself. Only `<plist>` may carry attributes, their
+ /// double-quoted values skipped whole as libplist skips them.
+ private mutating func tag() throws -> (name: String, empty: Bool) {
+ let start = at
+ while at < bytes.count, !" \t\r\n<>".utf8.contains(bytes[at]) {
+ at += 1
+ }
+ var name = bytes[start ..< at]
+ if at < bytes.count, bytes[at] != UInt8(ascii: ">") {
+ guard name.elementsEqual("plist".utf8) else { throw Self.refuse("attributes on <\(String(decoding: name, as: UTF8.self))>") }
+ while at < bytes.count, bytes[at] != UInt8(ascii: "<"), bytes[at] != UInt8(ascii: ">") {
+ if bytes[at] == UInt8(ascii: "\"") {
+ at = try closingQuote()
+ }
+ at += 1
+ }
+ }
+ try expect(">")
+ let empty = bytes[at - 2] == UInt8(ascii: "/")
+ if empty, name.last == UInt8(ascii: "/") {
+ name = name.dropLast()
+ }
+ return (String(decoding: name, as: UTF8.self), empty)
+ }
+
+ /// An element's text up to its closing tag, which must be what
+ /// follows it: libplist splits a text at a comment or CDATA and joins
+ /// the parts its own way.
+ private mutating func text(closing name: String, skippingSpace: Bool) throws -> ArraySlice<UInt8> {
+ if skippingSpace {
+ skipSpace()
+ }
+ guard let end = bytes[at...].firstIndex(of: UInt8(ascii: "<")) else { throw Self.refuse("<\(name)> is never closed") }
+ let text = bytes[at ..< end]
+ at = end + 1
+ try expect("/" + name)
+ skipSpace()
+ try expect(">")
+ return text
+ }
+
+ /// Skips what libplist skips between elements, past the `<`: `<?…?>`,
+ /// a comment, and a `<!DOCTYPE>` without an internal subset.
+ private mutating func skipMarkup() throws -> Bool {
+ if bytes[at...].starts(with: "?".utf8) {
+ try skip(past: "?>", quotes: true)
+ } else if bytes[at...].starts(with: "!--".utf8) {
+ at += 3
+ try skip(past: "-->", quotes: false)
+ } else if bytes[at...].starts(with: "!DOCTYPE".utf8) {
+ at += 8
+ while true {
+ guard at < bytes.count, bytes[at] != UInt8(ascii: "[") else {
+ throw Self.refuse("a DOCTYPE with an internal subset")
+ }
+ if bytes[at] == UInt8(ascii: "\"") {
+ at = try closingQuote()
+ } else if bytes[at] == UInt8(ascii: ">") {
+ at += 1
+ break
+ }
+ at += 1
+ }
+ } else if bytes[at...].starts(with: "!".utf8) {
+ throw Self.refuse("CDATA or another declaration libplist joins its own way")
+ } else {
+ return false
+ }
+ return true
+ }
+
+ private mutating func skip(past terminator: String, quotes: Bool) throws {
+ while at < bytes.count {
+ if bytes[at...].starts(with: terminator.utf8) {
+ at += terminator.utf8.count
+ return
+ }
+ if quotes, bytes[at] == UInt8(ascii: "\"") {
+ at = try closingQuote()
+ }
+ at += 1
+ }
+ throw Self.refuse("markup that is never closed")
+ }
+
+ /// Where the double quote opened at `at` closes.
+ private func closingQuote() throws -> Int {
+ guard let close = bytes[(at + 1)...].firstIndex(of: UInt8(ascii: "\"")) else {
+ throw Self.refuse("a quote that is never closed")
+ }
+ return close
+ }
+
+ private mutating func expect(_ literal: String) throws {
+ guard bytes[at...].starts(with: literal.utf8) else { throw Self.refuse("expected \(literal)") }
+ at += literal.utf8.count
+ }
+
+ private mutating func skipSpace() {
+ while at < bytes.count, Self.isSpace(bytes[at]) {
+ at += 1
+ }
+ }
+
+ /// What libplist skips as space: these four and nothing else.
+ private static func isSpace(_ byte: UInt8) -> Bool {
+ [0x20, 0x09, 0x0A, 0x0D].contains(byte)
+ }
+
+ /// An `<integer>`'s text, read as libplist reads it: an optional sign,
+ /// then `strtoull` in base 0, and the `uint64_t` that comes out is
+ /// what ldid hands to its DER writer.
+ ///
+ /// Every released libplist — 2.3 through the 2.7 every shipped `ldid`
+ /// links — is `strtoull(str, NULL, 0)` with nothing checked after it,
+ /// so it reads `42abc` as 42, `abc` and `<integer></integer>` as 0,
+ /// and an overflow as `ULLONG_MAX`. libplist's master branch added
+ /// the three checks that turn each of those into a parse error. The
+ /// spellings both read the same way are taken here and the rest are
+ /// refused, because signing one of the others would seal a number the
+ /// next ldid would have refused to write at all. A doubled sign
+ /// (`--1`) is refused with them: the two agree it is 1, and nothing
+ /// writes it.
+ ///
+ /// Everything a real entitlements list can hold is in the accepted
+ /// group. `0`, `-1`, `007`, `0x10`, `+42`, `-0x10`, `2^63` and
+ /// `2^64-1` all round-trip, each checked against the 0xfade7172 blob
+ /// `ldid -S<file>` writes for it.
+ private static func integer(_ text: ArraySlice<UInt8>) throws -> VPhoneSignEntitlements.Integer {
+ // the leading space went before the text was captured; the
+ // trailing space strtoull stops at goes here
+ var body = text.drop { isSpace($0) }
+ while let last = body.last, isSpace(last) {
+ body = body.dropLast()
+ }
+ var isNegative = false
+ if let sign = body.first, sign == UInt8(ascii: "-") || sign == UInt8(ascii: "+") {
+ isNegative = sign == UInt8(ascii: "-")
+ // strtoull skips its own leading space, so `<integer>- 1</integer>` is -1
+ body = body.dropFirst().drop { isSpace($0) }
+ }
+ // base 0: `0x` is hex, a leading `0` is octal, anything else decimal
+ var radix = 10
+ if body.count > 1, body.first == UInt8(ascii: "0") {
+ let isHex = body.dropFirst().first.map { $0 | 0x20 == UInt8(ascii: "x") } == true
+ radix = isHex ? 16 : 8
+ body = body.dropFirst(isHex ? 2 : 1)
+ }
+ let digits = String(decoding: body, as: UTF8.self)
+ guard !body.isEmpty, body.first != UInt8(ascii: "-"), body.first != UInt8(ascii: "+"),
+ let magnitude = UInt64(digits, radix: radix),
+ // strtoull would wrap this one and a newer libplist refuses it
+ !isNegative || magnitude <= UInt64(Int64.max) + 1
+ else {
+ throw refuse("<integer>\(String(decoding: text, as: UTF8.self))</integer>, which libplist would read its own way")
+ }
+ return VPhoneSignEntitlements.Integer(
+ raw: isNegative ? 0 &- magnitude : magnitude,
+ // libplist's `length == 16`: above INT64_MAX and unsigned,
+ // which is the only case `plist_to_xml` prints with %llu
+ isUnsigned: !isNegative && magnitude > UInt64(Int64.max)
+ )
+ }
+
+ /// A key's or a string's text: the five named entities and a numeric
+ /// reference of up to eight characters, as libplist takes them, and
+ /// UTF-8 with no NUL, which would end libplist's string.
+ private static func string(_ text: ArraySlice<UInt8>) throws -> String {
+ var bytes: [UInt8] = []
+ var at = text.startIndex
+ while at < text.endIndex {
+ guard text[at] == UInt8(ascii: "&") else {
+ bytes.append(text[at])
+ at += 1
+ continue
+ }
+ guard let end = text[at...].firstIndex(of: UInt8(ascii: ";")) else { throw refuse("an entity that is never closed") }
+ let name = text[(at + 1) ..< end]
+ switch String(decoding: name, as: UTF8.self) {
+ case "amp": bytes.append(UInt8(ascii: "&"))
+ case "lt": bytes.append(UInt8(ascii: "<"))
+ case "gt": bytes.append(UInt8(ascii: ">"))
+ case "quot": bytes.append(UInt8(ascii: "\""))
+ case "apos": bytes.append(UInt8(ascii: "'"))
+ default:
+ let hex = name.dropFirst().first.map { $0 | 0x20 == UInt8(ascii: "x") } == true
+ let digits = name.dropFirst(hex ? 2 : 1)
+ guard name.first == UInt8(ascii: "#"), name.count <= 8, !digits.isEmpty,
+ digits.allSatisfy({ (0x30 ... 0x39).contains($0) || hex && (0x61 ... 0x66).contains($0 | 0x20) }),
+ let value = UInt32(String(decoding: digits, as: UTF8.self), radix: hex ? 16 : 10), value != 0,
+ let scalar = Unicode.Scalar(value)
+ else { throw refuse("an entity libplist matches by its first letters") }
+ bytes += Array(String(scalar).utf8)
+ }
+ at = end + 1
+ }
+ let string = String(decoding: bytes, as: UTF8.self)
+ guard !bytes.contains(0), string.utf8.elementsEqual(bytes) else {
+ throw refuse("a string with a NUL or a byte that is not UTF-8")
+ }
+ return string
+ }
+ }
+}
diff --git a/sources/VPhoneSign/VPhoneSignError.swift b/sources/VPhoneSign/VPhoneSignError.swift
new file mode 100644
index 00000000..e2b5c1c4
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneSignError.swift
@@ -0,0 +1,46 @@
+import Foundation
+
+// MARK: - Failures
+
+/// Why a file could not be signed or read back. The cases are the ones a
+/// caller can act on: everything else is a programming error and traps.
+public enum VPhoneSignError: Error, Equatable, CustomStringConvertible {
+ /// The file is not a Mach-O at all. `ldid` says "not a Mach-O file".
+ case notMachO(String)
+ /// A header, an architecture, a load command or the old signature points
+ /// outside the file.
+ case malformed(String)
+ /// A slice that is not 64-bit little-endian. ldid signs 32-bit slices
+ /// too; nothing this project signs has one, so it is refused rather
+ /// than written wrong.
+ case unsupportedSlice(String)
+ /// The longer load commands do not fit in front of the first section,
+ /// which happens when a file that never had a signature has no room for
+ /// the `LC_CODE_SIGNATURE` one.
+ case noRoom(String)
+ /// Entitlements this signer will not carry over unchanged: a binary
+ /// plist, a date, a real, a negative or zero integer, or XML that
+ /// libplist and Foundation read differently. Signing them would silently
+ /// change what the guest is granted, so it refuses instead.
+ case unsupportedEntitlements(String)
+ /// The PKCS#12 could not be opened: wrong password, an algorithm this
+ /// reader does not implement, or a structure it does not recognise.
+ case identityUnreadable(String)
+ /// The CMS signature could not be produced.
+ case signingFailed(String)
+ /// `--use-ldid` was asked for and the external tool is missing or failed.
+ case ldidUnavailable(String)
+
+ public var description: String {
+ switch self {
+ case let .notMachO(detail): "not a Mach-O file: \(detail)"
+ case let .malformed(detail): "malformed Mach-O: \(detail)"
+ case let .unsupportedSlice(detail): "unsupported slice: \(detail)"
+ case let .noRoom(detail): "no room for the signature load command: \(detail)"
+ case let .unsupportedEntitlements(detail): "unsupported entitlements: \(detail)"
+ case let .identityUnreadable(detail): "cannot read the signing identity: \(detail)"
+ case let .signingFailed(detail): "signing failed: \(detail)"
+ case let .ldidUnavailable(detail): "ldid: \(detail)"
+ }
+ }
+}
diff --git a/sources/VPhoneSign/VPhoneSignIdentity.swift b/sources/VPhoneSign/VPhoneSignIdentity.swift
new file mode 100644
index 00000000..fe1c2187
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneSignIdentity.swift
@@ -0,0 +1,177 @@
+import CryptoKit
+import Foundation
+import Security
+
+// MARK: - Signing for real
+
+/// A signing identity read out of a `.p12`, and the detached CMS it makes.
+///
+/// The CMS is assembled here rather than with `CMSEncoder` for one reason:
+/// `CMSEncoder` wants a `SecIdentity`, and getting one means putting the
+/// private key in a keychain. Signing a firmware should not write to the
+/// user's keychain or raise a prompt for it. `SecKeyCreateSignature` needs
+/// no keychain, so the SignedData around it is written out by hand — which
+/// also makes the signed attributes exactly the set `ldid` produces, rather
+/// than whatever the encoder decides to add.
+public struct VPhoneSignIdentity: VPhoneSigningIdentity, @unchecked Sendable {
+ public let commonName: String
+ public let teamIdentifier: String
+ /// Leaf first, as the chain came out of the container.
+ private let certificates: [Data]
+ private let key: SecKey
+ /// The leaf's issuer and serial, which is how a SignerInfo names it.
+ private let issuer: Data
+ private let serialNumber: Data
+
+ /// `password` is the one the container was wrapped with; the `.p12` in
+ /// this repository has none, which is why it is read without
+ /// `SecPKCS12Import`.
+ public init(pkcs12 data: Data, password: String) throws {
+ let container = try VPhoneSignPKCS12(data: data, password: password)
+ // The leaf is the one the private key belongs to. localKeyID would
+ // say so, but the modulus does too and needs no bag attributes: it
+ // is the certificate whose public key the key reproduces.
+ guard let key = SecKeyCreateWithData(
+ container.privateKey as CFData,
+ [kSecAttrKeyType: kSecAttrKeyTypeRSA, kSecAttrKeyClass: kSecAttrKeyClassPrivate] as CFDictionary,
+ nil
+ ) else {
+ throw VPhoneSignError.identityUnreadable("the private key is not an RSA key Security will take")
+ }
+ guard let publicKey = SecKeyCopyPublicKey(key),
+ let ours = SecKeyCopyExternalRepresentation(publicKey, nil) as Data?
+ else {
+ throw VPhoneSignError.identityUnreadable("the private key has no public half")
+ }
+ guard let leafIndex = try container.certificates.firstIndex(where: {
+ try Self.publicKey(ofCertificate: $0) == ours
+ }) else {
+ throw VPhoneSignError.identityUnreadable("no certificate in the PKCS#12 matches the private key")
+ }
+
+ let leaf = container.certificates[leafIndex]
+ // leaf first, then the rest in the order they were stored, which is
+ // the order ldid hands OpenSSL
+ certificates = [leaf] + container.certificates.enumerated()
+ .filter { $0.offset != leafIndex }.map(\.element)
+ self.key = key
+ let fields = try Self.certificateFields(leaf)
+ issuer = fields.issuer
+ serialNumber = fields.serialNumber
+ commonName = try Self.name(fields.subject, oid: VPhoneDER.OID.commonName)
+ teamIdentifier = try Self.name(fields.subject, oid: VPhoneDER.OID.organizationalUnit)
+ }
+
+ // MARK: The CMS
+
+ /// A detached CMS SignedData over the CodeDirectory, with the signed
+ /// attributes ldid writes: the content type, Apple's two hash agility
+ /// attributes, the message digest and the signing time.
+ public func cms(codeDirectory: Data, cdHashes: [Data]) throws -> Data {
+ var attributes = [
+ attribute(VPhoneDER.OID.contentType, [VPhoneDER.objectIdentifier(dotted: VPhoneDER.OID.data)]),
+ attribute(VPhoneDER.OID.messageDigest, [VPhoneDER.octetString(Data(SHA256.hash(data: codeDirectory)))]),
+ attribute(VPhoneDER.OID.signingTime, [VPhoneDER.utcTime(Date())]),
+ ]
+ // 1.2.840.113635.100.9.1: a plist of every cdhash, truncated to 20
+ // bytes, which is the form the older attribute carries.
+ if let plist = try? PropertyListSerialization.data(
+ fromPropertyList: ["cdhashes": cdHashes.map { $0.prefix(20) }], format: .xml, options: 0
+ ) {
+ attributes.append(attribute(VPhoneDER.OID.hashAgility, [VPhoneDER.octetString(plist)]))
+ }
+ // 1.2.840.113635.100.9.2: one entry per CodeDirectory, at full
+ // length, each tagged with the digest that made it. The digest is a
+ // bare OID here, not an AlgorithmIdentifier — Apple's structure has
+ // no parameters field, and adding the customary NULL is enough for
+ // `codesign --verify` to answer "Unable to decode the provided
+ // data" while OpenSSL still verifies the signature happily.
+ attributes.append(attribute(VPhoneDER.OID.hashAgilityV2, cdHashes.map { hash in
+ VPhoneDER.sequence([
+ VPhoneDER.objectIdentifier(dotted: hash.count == 20 ? VPhoneDER.OID.sha1 : VPhoneDER.OID.sha256),
+ VPhoneDER.octetString(hash),
+ ])
+ }))
+
+ // The digest is over the attributes as a SET, not as the [0] IMPLICIT
+ // they are stored in: the tag is swapped for the signature and back
+ // for the encoding. Getting this backwards is the classic way to
+ // produce a CMS that every verifier rejects.
+ let signed = VPhoneDER.setOf(attributes)
+ let signature = try sign(signed)
+ var stored = signed
+ stored[stored.startIndex] = 0xA0
+
+ let signerInfo = VPhoneDER.sequence([
+ VPhoneDER.integer(1),
+ VPhoneDER.sequence([issuer, serialNumber]),
+ VPhoneDER.algorithm(VPhoneDER.OID.sha256),
+ stored,
+ VPhoneDER.algorithm(VPhoneDER.OID.rsaEncryption),
+ VPhoneDER.octetString(signature),
+ ])
+ let signedData = VPhoneDER.sequence([
+ VPhoneDER.integer(1),
+ VPhoneDER.setOf([VPhoneDER.algorithm(VPhoneDER.OID.sha256)]),
+ // detached: the content type and nothing else
+ VPhoneDER.sequence([VPhoneDER.objectIdentifier(dotted: VPhoneDER.OID.data)]),
+ VPhoneDER.encode(0xA0, certificates.reduce(Data(), +)),
+ VPhoneDER.setOf([signerInfo]),
+ ])
+ return VPhoneDER.sequence([
+ VPhoneDER.objectIdentifier(dotted: VPhoneDER.OID.signedData),
+ VPhoneDER.encode(0xA0, signedData),
+ ])
+ }
+
+ private func sign(_ content: Data) throws -> Data {
+ var error: Unmanaged<CFError>?
+ guard let signature = SecKeyCreateSignature(
+ key, .rsaSignatureMessagePKCS1v15SHA256, content as CFData, &error
+ ) as Data? else {
+ throw VPhoneSignError.signingFailed(
+ (error?.takeRetainedValue()).map { "\($0)" } ?? "SecKeyCreateSignature gave no signature"
+ )
+ }
+ return signature
+ }
+
+ private func attribute(_ oid: String, _ values: [Data]) -> Data {
+ VPhoneDER.sequence([VPhoneDER.objectIdentifier(dotted: oid), VPhoneDER.setOf(values)])
+ }
+
+ // MARK: Reading the certificate
+
+ private static func certificateFields(_ certificate: Data) throws -> (
+ issuer: Data, subject: Data, serialNumber: Data
+ ) {
+ let tbs = try VPhoneDER.children(of: try VPhoneDER.element(in: certificate, at: 0).content)
+ guard let first = tbs.first else { throw VPhoneSignError.identityUnreadable("an empty certificate") }
+ let fields = try VPhoneDER.children(of: first.content)
+ // [0] EXPLICIT version is optional; everything after it shifts by one
+ let offset = fields.first?.tag == 0xA0 ? 1 : 0
+ guard fields.count >= offset + 6 else {
+ throw VPhoneSignError.identityUnreadable("a certificate with \(fields.count) fields")
+ }
+ return (fields[offset + 2].encoded, fields[offset + 4].encoded, fields[offset].encoded)
+ }
+
+ private static func publicKey(ofCertificate certificate: Data) throws -> Data? {
+ guard let certificate = SecCertificateCreateWithData(nil, certificate as CFData),
+ let key = SecCertificateCopyKey(certificate)
+ else { return nil }
+ return SecKeyCopyExternalRepresentation(key, nil) as Data?
+ }
+
+ /// One attribute of a `Name`: a SEQUENCE of SETs of type-and-value.
+ private static func name(_ encoded: Data, oid: String) throws -> String {
+ for set in try VPhoneDER.children(of: try VPhoneDER.element(in: encoded, at: 0).content) {
+ for pair in try VPhoneDER.children(of: set.content) {
+ let fields = try VPhoneDER.children(of: pair.content)
+ guard fields.count >= 2, VPhoneDER.objectIdentifier(fields[0].content) == oid else { continue }
+ return String(decoding: fields[1].content, as: UTF8.self)
+ }
+ }
+ throw VPhoneSignError.identityUnreadable("the certificate's subject has no \(oid)")
+ }
+}
diff --git a/sources/VPhoneSign/VPhoneSignLdid.swift b/sources/VPhoneSign/VPhoneSignLdid.swift
new file mode 100644
index 00000000..4e7f58a8
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneSignLdid.swift
@@ -0,0 +1,134 @@
+import Foundation
+
+// MARK: - The way back to ldid
+
+/// Running the external `ldid` instead of signing here.
+///
+/// This exists so that a regression in `VPhoneSign` is recoverable without a
+/// rebuild: set `VPHONE_USE_LDID=1` and every call site goes back to the
+/// tool it used before. It is deliberately not something the shipped bundle
+/// can reach on its own — `ldid` is the Homebrew binary that fails the
+/// self-contained admission rule, which is why it was replaced — so it looks
+/// for it on `PATH` and in the two Homebrew prefixes and fails loudly when
+/// it is not there, rather than quietly doing something else.
+///
+/// The plan's §10.19 says this comes out once the byte-for-byte gates have
+/// been green through a real guest boot. Until then it is one environment
+/// variable away.
+public enum VPhoneLdid {
+ /// Whether a call with no explicit preference should use ldid.
+ public static var isPreferred: Bool {
+ let value = ProcessInfo.processInfo.environment["VPHONE_USE_LDID"] ?? ""
+ return !value.isEmpty && value != "0" && value.lowercased() != "false"
+ }
+
+ /// Where the tool is, if it is anywhere.
+ public static func resolve() -> URL? {
+ var candidates = ["/opt/homebrew/bin/ldid", "/usr/local/bin/ldid"]
+ for directory in (ProcessInfo.processInfo.environment["PATH"] ?? "").split(separator: ":") {
+ candidates.append("\(directory)/ldid")
+ }
+ return candidates.first { FileManager.default.isExecutableFile(atPath: $0) }
+ .map { URL(fileURLWithPath: $0) }
+ }
+
+ /// The arguments that make `ldid` do what `options` asks. Kept apart from
+ /// running it so the mapping between the two signers can be read, and
+ /// tested, in one place.
+ ///
+ /// These five flags — `-S`, `-S<file>`, `-M`, `-K<p12>`, `-I<name>`, and
+ /// `-e` on the reading side — are every flag the repository ever passes.
+ /// That was worked out by reading the call sites. Do not quote a total
+ /// from memory: the number drops every time an installer is ported, and
+ /// two figures written here have already gone stale. Measure it:
+ ///
+ /// grep -rnE '(^|[^_[:alnum:]])ldid[[:space:]]+-' scripts/ cfw-kit/ --include='*.sh'
+ /// grep -rnE '(^|[^_[:alnum:]])ldid_sign(_ent)?[[:space:]]' scripts/ cfw-kit/ --include='*.sh'
+ ///
+ /// (17 and 33 on 2026-09-23.) A count of 175 has been quoted for this;
+ /// that is every textual mention of the word, a different and much larger
+ /// number. The flag set above is what matters here, and it has not moved.
+ ///
+ /// `entitlementsPath` is where `options.entitlements` has been written;
+ /// ldid takes a file, not bytes.
+ public static func arguments(
+ for options: VPhoneSignOptions, entitlementsPath: String?, identityPath: String?
+ ) -> [String] {
+ var arguments: [String] = []
+ arguments.append(entitlementsPath.map { "-S\($0)" } ?? "-S")
+ if options.mergesExisting {
+ arguments.append("-M")
+ }
+ if let identityPath {
+ arguments.append("-K\(identityPath)")
+ }
+ if let identifier = options.identifier {
+ arguments.append("-I\(identifier)")
+ }
+ return arguments
+ }
+
+ /// Signs with the external tool. `identityPath` is the `.p12`, since
+ /// ldid reads the container itself rather than taking an opened identity.
+ public static func sign(fileAt url: URL, options: VPhoneSignOptions, identityPath: String?) throws {
+ guard let tool = resolve() else {
+ throw VPhoneSignError.ldidUnavailable(
+ "VPHONE_USE_LDID is set but ldid is not installed (brew install ldid-procursus)"
+ )
+ }
+ // ldid opens the container itself, so the escape hatch needs the
+ // path and not the identity. Signing ad-hoc because the path was
+ // left out would be a silent downgrade from a real signature.
+ guard options.identity == nil || identityPath != nil else {
+ throw VPhoneSignError.ldidUnavailable(
+ "a signing identity was given but not the .p12 it came from, which is what ldid needs"
+ )
+ }
+ var entitlementsPath: String?
+ var temporary: URL?
+ if let entitlements = options.entitlements {
+ let file = FileManager.default.temporaryDirectory
+ .appendingPathComponent("vphone-ldid-\(UUID().uuidString).plist")
+ try entitlements.write(to: file)
+ entitlementsPath = file.path
+ temporary = file
+ }
+ defer { temporary.map { try? FileManager.default.removeItem(at: $0) } }
+
+ let process = Process()
+ process.executableURL = tool
+ process.arguments = arguments(
+ for: options, entitlementsPath: entitlementsPath, identityPath: identityPath
+ ) + [url.path]
+ let diagnostics = Pipe()
+ process.standardError = diagnostics
+ try process.run()
+ let message = String(decoding: diagnostics.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
+ process.waitUntilExit()
+ guard process.terminationStatus == 0 else {
+ throw VPhoneSignError.ldidUnavailable("ldid exited \(process.terminationStatus): \(message)")
+ }
+ }
+
+ /// `ldid -e`, for the same reason: one switch puts both directions back.
+ public static func entitlements(ofFileAt url: URL) throws -> Data {
+ guard let tool = resolve() else {
+ throw VPhoneSignError.ldidUnavailable(
+ "VPHONE_USE_LDID is set but ldid is not installed (brew install ldid-procursus)"
+ )
+ }
+ let process = Process()
+ process.executableURL = tool
+ process.arguments = ["-e", url.path]
+ let out = Pipe()
+ process.standardOutput = out
+ process.standardError = FileHandle.nullDevice
+ try process.run()
+ let data = out.fileHandleForReading.readDataToEndOfFile()
+ process.waitUntilExit()
+ guard process.terminationStatus == 0 else {
+ throw VPhoneSignError.ldidUnavailable("ldid -e exited \(process.terminationStatus)")
+ }
+ return data
+ }
+}
diff --git a/sources/VPhoneSign/VPhoneSignPKCS12.swift b/sources/VPhoneSign/VPhoneSignPKCS12.swift
new file mode 100644
index 00000000..e5c3d4a6
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneSignPKCS12.swift
@@ -0,0 +1,206 @@
+import CommonCrypto
+import Foundation
+
+// MARK: - Opening a PKCS#12
+
+/// What a `.p12` holds, once it has been opened: the certificates and the
+/// private key's PKCS#1 bytes.
+///
+/// `SecPKCS12Import` would be the obvious way to do this and it cannot be:
+/// it refuses an empty password with `errSecAuthFailed`, and the
+/// `signcert.p12` in this repository has one, as do most of the ones people
+/// pass around. Re-wrapping it with a password would work but would change
+/// a checked-in file and break every other tool that reads it. So the
+/// container is opened here, which needs PBES2 and PBKDF2 from CommonCrypto
+/// and nothing else.
+struct VPhoneSignPKCS12 {
+ /// Every certificate in the file, in the order it appears.
+ let certificates: [Data]
+ /// The private key as PKCS#1 `RSAPrivateKey`, which is what
+ /// `SecKeyCreateWithData` takes.
+ let privateKey: Data
+
+ init(data: Data, password: String) throws {
+ // as in VPhoneMachOFile: the DER reader counts from zero
+ let data = data.startIndex == 0 ? data : Data(data)
+ let pfx = try VPhoneDER.children(of: try VPhoneDER.element(in: data, at: 0).content)
+ guard pfx.count >= 2 else { throw VPhoneSignError.identityUnreadable("a PFX with \(pfx.count) fields") }
+ let authenticated = try Self.contentInfo(pfx[1], password: password)
+
+ var certificates: [Data] = []
+ var privateKey: Data?
+ // Each payload is the DER of a SEQUENCE, not its contents, so it is
+ // unwrapped once more on the way in.
+ for content in try VPhoneDER.children(of: try VPhoneDER.element(in: authenticated, at: 0).content) {
+ let safeContents = try Self.contentInfo(content, password: password)
+ for bag in try VPhoneDER.children(of: try VPhoneDER.element(in: safeContents, at: 0).content) {
+ let fields = try VPhoneDER.children(of: bag.content)
+ guard fields.count >= 2 else { continue }
+ let value = try VPhoneDER.element(in: fields[1].content, at: 0)
+ switch VPhoneDER.objectIdentifier(fields[0].content) {
+ case VPhoneDER.OID.certBag:
+ let certificate = try VPhoneDER.children(of: value.content)
+ guard certificate.count >= 2,
+ VPhoneDER.objectIdentifier(certificate[0].content) == VPhoneDER.OID.x509Certificate
+ else { continue }
+ certificates.append(try VPhoneDER.element(in: certificate[1].content, at: 0).content)
+ case VPhoneDER.OID.shroudedKeyBag:
+ privateKey = try Self.privateKey(in: try Self.decryptPrivateKey(value.encoded, password: password))
+ case VPhoneDER.OID.keyBag:
+ privateKey = try Self.privateKey(in: value.encoded)
+ default:
+ continue
+ }
+ }
+ }
+
+ guard let privateKey else { throw VPhoneSignError.identityUnreadable("no private key in the PKCS#12") }
+ guard !certificates.isEmpty else { throw VPhoneSignError.identityUnreadable("no certificate in the PKCS#12") }
+ self.certificates = certificates
+ self.privateKey = privateKey
+ }
+
+ /// A ContentInfo's payload: plain for `data`, decrypted for
+ /// `encryptedData`.
+ private static func contentInfo(_ element: VPhoneDER.Element, password: String) throws -> Data {
+ let fields = try VPhoneDER.children(of: element.content)
+ guard fields.count >= 2 else { throw VPhoneSignError.identityUnreadable("a ContentInfo without content") }
+ switch VPhoneDER.objectIdentifier(fields[0].content) {
+ case VPhoneDER.OID.data:
+ // [0] EXPLICIT OCTET STRING, which may be split into chunks in
+ // BER; DER keeps it in one
+ return try VPhoneDER.element(in: fields[1].content, at: 0).content
+ case VPhoneDER.OID.encryptedData:
+ let encrypted = try VPhoneDER.children(of: try VPhoneDER.element(in: fields[1].content, at: 0).content)
+ guard encrypted.count >= 2 else { throw VPhoneSignError.identityUnreadable("an EncryptedData without content") }
+ let info = try VPhoneDER.children(of: encrypted[1].content)
+ guard info.count >= 3 else { throw VPhoneSignError.identityUnreadable("an EncryptedContentInfo without content") }
+ // [0] IMPLICIT OCTET STRING: the content is the value itself
+ return try decrypt(info[2].content, algorithm: info[1], password: password)
+ default:
+ throw VPhoneSignError.identityUnreadable(
+ "a PKCS#12 bag of type \(VPhoneDER.objectIdentifier(fields[0].content))"
+ )
+ }
+ }
+
+ /// An EncryptedPrivateKeyInfo.
+ private static func decryptPrivateKey(_ encoded: Data, password: String) throws -> Data {
+ let fields = try VPhoneDER.children(of: try VPhoneDER.element(in: encoded, at: 0).content)
+ guard fields.count >= 2 else { throw VPhoneSignError.identityUnreadable("an EncryptedPrivateKeyInfo without content") }
+ return try decrypt(fields[1].content, algorithm: fields[0], password: password)
+ }
+
+ /// The PKCS#1 `RSAPrivateKey` inside a PKCS#8 `PrivateKeyInfo`.
+ private static func privateKey(in pkcs8: Data) throws -> Data {
+ let fields = try VPhoneDER.children(of: try VPhoneDER.element(in: pkcs8, at: 0).content)
+ guard fields.count >= 3 else { throw VPhoneSignError.identityUnreadable("a PrivateKeyInfo without a key") }
+ let algorithm = try VPhoneDER.children(of: fields[1].content)
+ guard let first = algorithm.first,
+ VPhoneDER.objectIdentifier(first.content) == VPhoneDER.OID.rsaEncryption
+ else {
+ throw VPhoneSignError.identityUnreadable("a private key that is not RSA")
+ }
+ return fields[2].content
+ }
+
+ // MARK: PBES2
+
+ /// PBES2: PBKDF2 over the password, then AES-CBC. It is what every
+ /// PKCS#12 written this decade uses, including the one in this
+ /// repository. A file wrapped with the older PKCS#12 key derivation is
+ /// refused by name rather than guessed at.
+ private static func decrypt(_ ciphertext: Data, algorithm: VPhoneDER.Element, password: String) throws -> Data {
+ let fields = try VPhoneDER.children(of: algorithm.content)
+ guard let oid = fields.first.map({ VPhoneDER.objectIdentifier($0.content) }), fields.count >= 2 else {
+ throw VPhoneSignError.identityUnreadable("an encryption algorithm without parameters")
+ }
+ guard oid == VPhoneDER.OID.pbes2 else {
+ throw VPhoneSignError.identityUnreadable("""
+ the PKCS#12 is encrypted with \(oid), which this reader does not implement. \
+ Re-wrap it with PBES2: openssl pkcs12 -in old.p12 -nodes -out tmp.pem && \
+ openssl pkcs12 -export -in tmp.pem -out new.p12
+ """)
+ }
+ let parameters = try VPhoneDER.children(of: fields[1].content)
+ guard parameters.count >= 2 else { throw VPhoneSignError.identityUnreadable("PBES2 without both halves") }
+
+ let derivation = try VPhoneDER.children(of: parameters[0].content)
+ guard derivation.count >= 2,
+ VPhoneDER.objectIdentifier(derivation[0].content) == VPhoneDER.OID.pbkdf2
+ else {
+ throw VPhoneSignError.identityUnreadable("PBES2 with a key derivation that is not PBKDF2")
+ }
+ let pbkdf2 = try VPhoneDER.children(of: derivation[1].content)
+ guard pbkdf2.count >= 2 else { throw VPhoneSignError.identityUnreadable("PBKDF2 without a salt") }
+ let salt = pbkdf2[0].content
+ let iterations = try VPhoneDER.integer(pbkdf2[1].content)
+
+ var prf = CCPseudoRandomAlgorithm(kCCPRFHmacAlgSHA1)
+ for field in pbkdf2.dropFirst(2) where field.tag == 0x30 {
+ let algorithm = try VPhoneDER.children(of: field.content)
+ switch algorithm.first.map({ VPhoneDER.objectIdentifier($0.content) }) {
+ case VPhoneDER.OID.hmacWithSHA1: prf = CCPseudoRandomAlgorithm(kCCPRFHmacAlgSHA1)
+ case VPhoneDER.OID.hmacWithSHA224: prf = CCPseudoRandomAlgorithm(kCCPRFHmacAlgSHA224)
+ case VPhoneDER.OID.hmacWithSHA256: prf = CCPseudoRandomAlgorithm(kCCPRFHmacAlgSHA256)
+ case VPhoneDER.OID.hmacWithSHA384: prf = CCPseudoRandomAlgorithm(kCCPRFHmacAlgSHA384)
+ case VPhoneDER.OID.hmacWithSHA512: prf = CCPseudoRandomAlgorithm(kCCPRFHmacAlgSHA512)
+ case let other:
+ throw VPhoneSignError.identityUnreadable("PBKDF2 with the pseudorandom function \(other ?? "?")")
+ }
+ }
+
+ let scheme = try VPhoneDER.children(of: parameters[1].content)
+ guard scheme.count >= 2 else { throw VPhoneSignError.identityUnreadable("an encryption scheme without an IV") }
+ let keyLength: Int
+ switch VPhoneDER.objectIdentifier(scheme[0].content) {
+ case VPhoneDER.OID.aes128CBC: keyLength = 16
+ case VPhoneDER.OID.aes192CBC: keyLength = 24
+ case VPhoneDER.OID.aes256CBC: keyLength = 32
+ case let other:
+ throw VPhoneSignError.identityUnreadable("PBES2 with the cipher \(other)")
+ }
+ let iv = scheme[1].content
+
+ var key = [UInt8](repeating: 0, count: keyLength)
+ let derived = Array(password.utf8).withUnsafeBufferPointer { bytes in
+ [UInt8](salt).withUnsafeBufferPointer { salt in
+ CCKeyDerivationPBKDF(
+ CCPBKDFAlgorithm(kCCPBKDF2),
+ // an empty password is a real password here: the pointer
+ // may be null, which CCKeyDerivationPBKDF accepts with a
+ // length of zero
+ bytes.baseAddress.map { UnsafeRawPointer($0).assumingMemoryBound(to: CChar.self) }, bytes.count,
+ salt.baseAddress, salt.count,
+ prf, UInt32(iterations),
+ &key, key.count
+ )
+ }
+ }
+ guard derived == kCCSuccess else {
+ throw VPhoneSignError.identityUnreadable("PBKDF2 failed with \(derived)")
+ }
+
+ var plaintext = [UInt8](repeating: 0, count: ciphertext.count + kCCBlockSizeAES128)
+ var written = 0
+ let status = [UInt8](ciphertext).withUnsafeBufferPointer { input in
+ [UInt8](iv).withUnsafeBufferPointer { iv in
+ CCCrypt(
+ CCOperation(kCCDecrypt), CCAlgorithm(kCCAlgorithmAES), CCOptions(kCCOptionPKCS7Padding),
+ key, key.count, iv.baseAddress,
+ input.baseAddress, input.count,
+ &plaintext, plaintext.count, &written
+ )
+ }
+ }
+ guard status == kCCSuccess else {
+ // the one failure a caller can act on: the password is wrong
+ throw VPhoneSignError.identityUnreadable(
+ status == kCCDecodeError || status == kCCAlignmentError
+ ? "the PKCS#12 password is wrong"
+ : "decrypting the PKCS#12 failed with \(status)"
+ )
+ }
+ return Data(plaintext.prefix(written))
+ }
+}
diff --git a/sources/VPhoneSign/VPhoneSigner.swift b/sources/VPhoneSign/VPhoneSigner.swift
new file mode 100644
index 00000000..579f0f7a
--- /dev/null
+++ b/sources/VPhoneSign/VPhoneSigner.swift
@@ -0,0 +1,220 @@
+import Foundation
+import MachO
+
+// MARK: - What ldid was called for
+
+/// The identity `-K` signs with. The CMS half is behind a protocol so the
+/// ad-hoc path, which is nearly every call, needs nothing from Security.
+public protocol VPhoneSigningIdentity: Sendable {
+ /// The leaf certificate's common name, which goes in the designated
+ /// requirement.
+ var commonName: String { get }
+ /// The leaf certificate's organizational unit, which is the team ID and
+ /// goes in the CodeDirectory.
+ var teamIdentifier: String { get }
+ /// A detached CMS SignedData over `codeDirectory`, carrying the cdhashes
+ /// of every CodeDirectory in the signature.
+ func cms(codeDirectory: Data, cdHashes: [Data]) throws -> Data
+}
+
+/// How to sign.
+public struct VPhoneSignOptions {
+ /// What shape of signature to write.
+ public enum Style: Sendable {
+ /// Byte for byte what `ldid` writes, which is what the guest's AMFI
+ /// is known to accept and what every call site in this repository
+ /// has always produced. `codesign --verify` rejects it — it rejects
+ /// ldid's own output too, because there is no CMS blob and the
+ /// ad-hoc flag is not set.
+ case ldid
+ /// An ad-hoc signature in Apple's shape: the ad-hoc flag set, no
+ /// designated requirement, and the empty CMS wrapper. This is what
+ /// `codesign --sign -` writes and what `codesign --verify` accepts.
+ case appleAdHoc
+ }
+
+ /// `-I`. The file's name when nil, as ldid defaults it.
+ public var identifier: String?
+ /// `-S<file>`: the entitlements to embed, as the file holds them.
+ public var entitlements: Data?
+ /// `-M`: merge over whatever the file is already signed with.
+ public var mergesExisting = false
+ public var style = Style.ldid
+ /// `-K`: sign for real rather than ad-hoc.
+ public var identity: (any VPhoneSigningIdentity)?
+ /// Where `identity` was read from. Only the escape hatch needs it: the
+ /// external ldid opens the container itself.
+ public var identityPath: String?
+ /// `--use-ldid`: hand the file to the external tool instead. nil asks
+ /// the environment (`VPHONE_USE_LDID`), which is how a regression is
+ /// recovered from without touching a call site.
+ public var usesExternalLdid: Bool?
+
+ public init(
+ identifier: String? = nil,
+ entitlements: Data? = nil,
+ mergesExisting: Bool = false,
+ style: Style = .ldid,
+ identity: (any VPhoneSigningIdentity)? = nil,
+ identityPath: String? = nil,
+ usesExternalLdid: Bool? = nil
+ ) {
+ self.identifier = identifier
+ self.entitlements = entitlements
+ self.mergesExisting = mergesExisting
+ self.style = style
+ self.identity = identity
+ self.identityPath = identityPath
+ self.usesExternalLdid = usesExternalLdid
+ }
+}
+
+/// Signs Mach-O files the way `ldid` does, and reads entitlements back out
+/// the way `ldid -e` does.
+///
+/// This exists because `ldid` is the one program this project ships that
+/// links Homebrew — `libcrypto.3` and `libplist-2.0.4` — and so the one
+/// thing that fails the self-contained admission rule. Nothing here is
+/// outside the system frameworks.
+public enum VPhoneSigner {
+ /// ldid's `certificate`: "a sufficiently large number" of bytes kept for
+ /// the CMS blob, which has to be reserved before it can be made.
+ static let cmsReservation = 0x3000
+
+ // MARK: Signing
+
+ /// Signs the file in place, keeping its mode.
+ @discardableResult
+ public static func sign(fileAt url: URL, options: VPhoneSignOptions = .init()) throws -> Data {
+ var options = options
+ options.identifier = options.identifier ?? url.lastPathComponent
+ if options.usesExternalLdid ?? VPhoneLdid.isPreferred {
+ try VPhoneLdid.sign(fileAt: url, options: options, identityPath: options.identityPath)
+ return try Data(contentsOf: url)
+ }
+ let data = try Data(contentsOf: url)
+ let signed = try sign(data, options: options)
+ // The same path ldid takes: a temporary beside the file, its mode
+ // copied over, then rename(2). It has to be rename and not
+ // replaceItemAt because a great many of the files this signs are
+ // mode 444 — anything unpacked out of an IPSW is — and replacing
+ // one needs write permission on the file, where renaming over it
+ // needs it only on the directory. It is also why an interrupted run
+ // leaves the original untouched rather than half written.
+ let temporary = url.deletingLastPathComponent()
+ .appendingPathComponent(".\(url.lastPathComponent).vphonesign")
+ try? FileManager.default.removeItem(at: temporary)
+ try signed.write(to: temporary, options: .atomic)
+ if let mode = try? FileManager.default.attributesOfItem(atPath: url.path)[.posixPermissions] {
+ try? FileManager.default.setAttributes([.posixPermissions: mode], ofItemAtPath: temporary.path)
+ }
+ guard rename(temporary.path, url.path) == 0 else {
+ let reason = String(cString: strerror(errno))
+ try? FileManager.default.removeItem(at: temporary)
+ throw VPhoneSignError.signingFailed("cannot replace \(url.path): \(reason)")
+ }
+ return signed
+ }
+
+ /// Signs `data`. `options.identifier` must be set; the file-based entry
+ /// point fills it in from the name.
+ public static func sign(_ data: Data, options: VPhoneSignOptions) throws -> Data {
+ guard let identifier = options.identifier else {
+ throw VPhoneSignError.signingFailed("no identifier, and no file name to take one from")
+ }
+ let file = try VPhoneMachOFile(data: data)
+
+ // ldid works out the hashes once, from the first slice it reads, and
+ // keeps them for the rest of the run. Every other slice inherits
+ // that decision however new its own deployment target is.
+ let digests = options.style == .appleAdHoc ? [.sha256] : file.slices[0].digests
+
+ var images: [Data] = []
+ for (index, slice) in file.slices.enumerated() {
+ let alignment = file.architectures.map { Int($0[index].alignment) } ?? slice.linkeditAlignment
+ let signature = try self.signature(
+ for: slice, identifier: identifier, digests: digests, options: options
+ )
+ let executable = slice.executableSegment
+ images.append(try slice.signed(
+ alignment: alignment,
+ signatureSize: { signature.allocation(codeLimit: $0) },
+ makeSignature: { code, codeLimit in
+ try signature.blob(
+ code: code,
+ codeLimit: codeLimit,
+ executable: executable,
+ cms: cmsBuilder(options: options)
+ )
+ }
+ ))
+ }
+ return try file.assembled(images)
+ }
+
+ private static func cmsBuilder(
+ options: VPhoneSignOptions
+ ) -> ((Data, [Data]) throws -> Data)? {
+ if let identity = options.identity {
+ return { try identity.cms(codeDirectory: $0, cdHashes: $1) }
+ }
+ // codesign writes the wrapper with nothing in it, and its absence is
+ // one of the two reasons codesign --verify calls ldid's output
+ // unsigned
+ return options.style == .appleAdHoc ? { _, _ in Data() } : nil
+ }
+
+ private static func signature(
+ for slice: VPhoneMachOImage,
+ identifier: String,
+ digests: [VPhoneCodeSignature.Digest],
+ options: VPhoneSignOptions
+ ) throws -> VPhoneCodeSignature {
+ var signature = VPhoneCodeSignature(identifier: identifier)
+ signature.digests = digests
+ signature.infoPlist = slice.infoPlist
+
+ let mainBinary = slice.fileType == UInt32(MH_EXECUTE)
+ switch options.style {
+ case .ldid:
+ signature.teamIdentifier = options.identity?.teamIdentifier ?? ""
+ signature.requirementsBlob = VPhoneCodeSignature.requirements(
+ identifier: identifier, commonName: options.identity?.commonName ?? ""
+ )
+ signature.cmsReservation = options.identity == nil ? nil : cmsReservation
+ case .appleAdHoc:
+ signature.requirementsBlob = VPhoneCodeSignature.emptyRequirements
+ signature.flags = 0x2 // kSecCodeSignatureAdhoc
+ signature.cmsReservation = 0
+ }
+
+ let existing = options.mergesExisting ? slice.embeddedEntitlements : nil
+ if existing?.isEmpty == false || options.entitlements?.isEmpty == false {
+ var combined = try VPhoneSignEntitlements(xml: existing ?? Data())
+ combined.merge(try VPhoneSignEntitlements(xml: options.entitlements ?? Data()))
+ signature.entitlements = (try combined.xml(), combined.der)
+ signature.executableSegmentFlags = combined.executableSegmentFlags(mainBinary: mainBinary)
+ } else {
+ signature.executableSegmentFlags = mainBinary ? 1 : 0
+ }
+ return signature
+ }
+
+ // MARK: Reading entitlements back
+
+ /// What `ldid -e` prints: the entitlements of each slice that carries
+ /// any, in slice order, exactly as the signature stores them. A slice
+ /// with none contributes nothing, so a file with no entitlements at all
+ /// gives an empty array.
+ public static func entitlements(ofFileAt url: URL, usesExternalLdid: Bool? = nil) throws -> [Data] {
+ if usesExternalLdid ?? VPhoneLdid.isPreferred {
+ let dumped = try VPhoneLdid.entitlements(ofFileAt: url)
+ return dumped.isEmpty ? [] : [dumped]
+ }
+ return try entitlements(in: Data(contentsOf: url))
+ }
+
+ public static func entitlements(in data: Data) throws -> [Data] {
+ try VPhoneMachOFile(data: data).slices.compactMap(\.embeddedEntitlements)
+ }
+}
diff --git a/sources/vphone-cli/VPhoneCFWPatchCLI.swift b/sources/vphone-cli/VPhoneCFWPatchCLI.swift
new file mode 100644
index 00000000..de6af92f
--- /dev/null
+++ b/sources/vphone-cli/VPhoneCFWPatchCLI.swift
@@ -0,0 +1,274 @@
+// VPhoneCFWPatchCLI.swift — the `cfw` subcommands that replace the Python patchers.
+//
+// Each one is a thin face over a type in `FirmwarePatcher/CFW/`. The Python they
+// replace is still on disk (`scripts/patchers/cfw.py` and friends) and the
+// installers still call it, so the bar every command here has to clear is that
+// its stdout is the Python's stdout — `cfw_install.sh:207-208` reads
+// `cryptex-paths` with `head -1`/`tail -1`, and a human reads the rest out of an
+// install log. Where the library already prints (build-version, campo,
+// post-restore-dt), the command passes `verbose: true` and prints nothing of its
+// own rather than inventing a second voice.
+
+import ArgumentParser
+import FirmwarePatcher
+import Foundation
+
+// MARK: - cryptex-paths
+
+struct VPhoneCFWCryptexPathsCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "cryptex-paths",
+ abstract: "Print the SystemOS and AppOS Cryptex DMG paths from a BuildManifest",
+ discussion: """
+ Two lines, SystemOS first then AppOS, relative to the IPSW root. The
+ installer reads them with `head -1` and `tail -1`, so nothing else may
+ be printed on success.
+
+ Every BuildIdentity is searched, not just the first: a vResearch IPSW
+ carries its Cryptex entries in a later identity, and the last identity
+ in a real manifest has none at all. The first identity carrying both
+ wins. When no identity carries both, this exits non-zero rather than
+ printing a blank line the caller would read as a path.
+ """
+ )
+
+ @Argument(help: "Path to BuildManifest.plist", transform: URL.init(fileURLWithPath:))
+ var buildManifest: URL
+
+ func run() throws {
+ let paths = try CFWDaemons.cryptexPaths(buildManifest: buildManifest)
+ print(paths.systemOS)
+ print(paths.appOS)
+ }
+}
+
+// MARK: - inject-daemons
+
+struct VPhoneCFWInjectDaemonsCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "inject-daemons",
+ abstract: "Merge the staged LaunchDaemons into a launchd.plist",
+ discussion: """
+ Looks for bash, dropbear, trollvnc, vphoned and rpcserver_ios in the
+ staging directory — a fixed list, in that order, so what gets injected
+ does not depend on what else a variant leaves lying around — and writes
+ each one into the target's `LaunchDaemons` dictionary under
+ `/System/Library/LaunchDaemons/<name>.plist`.
+
+ A daemon that is not staged is skipped, not an error: a variant that
+ does not ship rpcserver_ios still installs. An entry already present is
+ replaced, which is what makes re-running an install over an
+ already-patched volume safe.
+
+ dropbear's ProgramArguments are rewritten on the way through to point at
+ the /var/dropbear host keys — see `patch-dropbear-plist`.
+ """
+ )
+
+ @Argument(help: "Path to the guest's /System/Library/xpc/launchd.plist", transform: URL.init(fileURLWithPath:))
+ var launchdPlist: URL
+
+ @Argument(help: "Directory holding the staged <name>.plist daemons", transform: URL.init(fileURLWithPath:))
+ var daemonDirectory: URL
+
+ func run() throws {
+ for entry in try CFWDaemons.injectDaemons(into: launchdPlist, fromDirectory: daemonDirectory) {
+ switch entry {
+ case let .present(daemon): print(" [+] Injected \(daemon.name)")
+ case let .absent(source): print(" [!] Missing \(source), skipping")
+ }
+ }
+ }
+}
+
+// MARK: - inject-daemon
+
+struct VPhoneCFWInjectDaemonCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "inject-daemon",
+ abstract: "Merge one LaunchDaemon plist into a launchd.plist under a given label",
+ discussion: """
+ The single-file form of `inject-daemons`, replacing the inline plistlib
+ snippet that `cfw_install_jb.sh` and `cfw_install_exp.sh` each carry a
+ copy of.
+
+ --name is the label the daemon installs under, which is not the source
+ file's name: the JB setup daemon ships as `vphone_jb_setup.plist` and
+ installs as `com.vphone.jb-setup.plist`. It is the key launchd looks the
+ daemon up by, so it has to match the file written into
+ /System/Library/LaunchDaemons.
+ """
+ )
+
+ @Argument(help: "Path to the guest's /System/Library/xpc/launchd.plist", transform: URL.init(fileURLWithPath:))
+ var launchdPlist: URL
+
+ @Argument(help: "The daemon plist to merge in", transform: URL.init(fileURLWithPath:))
+ var source: URL
+
+ @Option(name: .customLong("name"), help: "Label to install under, without .plist (e.g. com.vphone.jb-setup)")
+ var name: String
+
+ func run() throws {
+ try CFWDaemons.injectDaemon(into: launchdPlist, name: name, from: source)
+ }
+}
+
+// MARK: - patch-dropbear-plist
+
+struct VPhoneCFWPatchDropbearPlistCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-dropbear-plist",
+ abstract: "Point dropbear at the /var/dropbear host keys instead of generating its own",
+ discussion: """
+ Drops `-R` (generate defaults under /etc/dropbear, which is on the
+ read-only root during a normal VM boot) and every `-r <path>` pair, so a
+ stale explicit key path cannot survive, then appends the two keys
+ cfw_install seeds on the writable Data volume.
+
+ An empty or missing ProgramArguments list is left alone: there is
+ nothing there to point at a key.
+ """
+ )
+
+ @Argument(help: "Path to dropbear.plist", transform: URL.init(fileURLWithPath:))
+ var plist: URL
+
+ func run() throws {
+ try CFWDaemons.patchDropbearPlist(at: plist)
+ }
+}
+
+// MARK: - inject-dylib
+
+struct VPhoneCFWInjectDylibCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "inject-dylib",
+ abstract: "Insert a weak LC_LOAD_DYLIB into every slice of a Mach-O",
+ discussion: """
+ Replaces `insert_dylib --weak --inplace --all-yes`, which is how the JB
+ and EXP installers get launchd to load /b (the short launchdhook alias)
+ at boot.
+
+ The load is weak, so a guest that reaches launchd without the dylib in
+ place boots instead of panicking, and the existing LC_CODE_SIGNATURE and
+ its blob are removed — exactly what insert_dylib does by default. The
+ binary is not left unsigned: the install re-signs it on the next line.
+ """
+ )
+
+ @Argument(help: "The Mach-O to patch, in place", transform: URL.init(fileURLWithPath:))
+ var binary: URL
+
+ @Argument(help: "Path the guest will load the dylib from (e.g. /b)")
+ var dylibPath: String
+
+ func run() throws {
+ let injections = try CFWInjectDylib.inject(dylibPath: dylibPath, into: binary, weak: true, policy: .strip)
+ for injection in injections {
+ let stripped = injection.removedCodeSignature ? ", signature stripped" : ""
+ print(" [+] LC_LOAD_WEAK_DYLIB \(dylibPath) -> \(binary.lastPathComponent) "
+ + "(slice +0x\(String(injection.sliceOffset, radix: 16))\(stripped))")
+ }
+ }
+}
+
+// MARK: - patch-build-version
+
+struct VPhoneCFWPatchBuildVersionCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-build-version",
+ abstract: "Rewrite ProductBuildVersion in a SystemVersion.plist",
+ discussion: """
+ Settings → General → About shows this string as "Build Version", and
+ most of userland — libMobileGestalt, CoreFoundation's
+ _CFCopyServerVersionDictionary, App Store telemetry — reads it from
+ SystemVersion.plist rather than from the kernel. The EXP install
+ rewrites both copies: the one on the system volume and the one under
+ /private/preboot/Cryptexes/OS.
+
+ It does not touch `sysctl kern.osversion` (a kernel global set from boot
+ args), ProductVersion (the marketing version, deliberately left alone)
+ or any DSC constant. The file's format is preserved: XML in, XML out.
+
+ Idempotent — a re-run on an already-patched plist reports and exits
+ without rewriting.
+ """
+ )
+
+ @Argument(help: "Path to SystemVersion.plist", transform: URL.init(fileURLWithPath:))
+ var plist: URL
+
+ @Argument(help: "The build identifier to write (e.g. 23B85)")
+ var buildID: String
+
+ @Flag(name: .customLong("dry-run"), help: "Report what would change and exit")
+ var dryRun = false
+
+ func run() throws {
+ try CFWBuildVersion.patch(at: plist, to: buildID, dryRun: dryRun, verbose: true)
+ }
+}
+
+// MARK: - patch-campo-entitlements
+
+struct VPhoneCFWPatchCampoEntitlementsCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-campo-entitlements",
+ abstract: "Merge the backboard/frontboard mach-lookup exceptions Campo needs",
+ discussion: """
+ iOS 27's temporary sandbox denies Campo.app the services it needs to put
+ a window on screen. The install dumps Campo's entitlements, runs this to
+ merge the missing global-name lookups into the mach-lookup exception
+ array, and re-signs with the merged plist.
+
+ The merge is append-only and order-preserving: an entry already present
+ keeps its position, and anything the binary carried that is not in this
+ list survives. That matters because the result goes straight back to the
+ signer, and dropping an entitlement Campo already had would be a silent
+ downgrade.
+
+ The file is written back as XML, which is what the signer expects.
+ """
+ )
+
+ @Argument(help: "Path to the dumped entitlements plist", transform: URL.init(fileURLWithPath:))
+ var plist: URL
+
+ func run() throws {
+ try CFWMachLookupExceptions.merge(at: plist, verbose: true)
+ }
+}
+
+// MARK: - patch-post-restore-dt
+
+struct VPhoneCFWPatchPostRestoreDTCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-post-restore-dt",
+ abstract: "Rewrite the restore-fatal identity properties in a device tree",
+ discussion: """
+ Rewrites the three identity properties that make the guest look like a
+ real iPhone17,3 to the services that ask, in place, preserving the
+ container's compression, manifest and restore info.
+
+ Every rewrite lands in the property's existing slot, so the blob's size
+ cannot change; if it did, the parser and the serializer would have
+ drifted apart and the IM4P's recorded uncompressed size would no longer
+ match its payload. That is checked, and it refuses rather than writing a
+ device tree the guest will not load.
+
+ Takes a devicetree.img4 (preferred) or a bare .im4p. An encrypted
+ payload is refused, not guessed at.
+ """
+ )
+
+ @Argument(help: "Path to devicetree.img4 or devicetree.im4p", transform: URL.init(fileURLWithPath:))
+ var deviceTree: URL
+
+ @Flag(name: .customLong("dry-run"), help: "Report what would change and exit")
+ var dryRun = false
+
+ func run() throws {
+ try CFWPostRestoreDeviceTree.patch(at: deviceTree, dryRun: dryRun, verbose: true)
+ }
+}
diff --git a/sources/vphone-cli/VPhoneCLI.swift b/sources/vphone-cli/VPhoneCLI.swift
index 38190ed1..b923d4fe 100644
--- a/sources/vphone-cli/VPhoneCLI.swift
+++ b/sources/vphone-cli/VPhoneCLI.swift
@@ -10,6 +10,7 @@ struct VPhoneCLI: ParsableCommand {
subcommands: [
VPhoneBootCLI.self, PatchFirmwareCLI.self, PatchComponentCLI.self, VPhoneVMCommand.self,
VPhoneFWCommand.self, VPhoneRestoreCommand.self, VPhoneCFWCommand.self, VPhoneSetupCommand.self,
+ VPhoneSignCommand.self, VPhoneDumpEntitlementsCommand.self,
],
defaultSubcommand: VPhoneBootCLI.self
)
diff --git a/sources/vphone-cli/VPhoneRestoreCLI.swift b/sources/vphone-cli/VPhoneRestoreCLI.swift
index 6805e94b..eb26582e 100644
--- a/sources/vphone-cli/VPhoneRestoreCLI.swift
+++ b/sources/vphone-cli/VPhoneRestoreCLI.swift
@@ -97,7 +97,20 @@ struct VPhoneCFWCommand: ParsableCommand {
static let configuration = CommandConfiguration(
commandName: "cfw",
abstract: "Custom-firmware install (host-mount; VM must be off; re-execs sudo)",
- subcommands: [VPhoneCFWInstallCommand.self, VPhoneCFWFlipSnapshotCommand.self])
+ subcommands: [
+ VPhoneCFWInstallCommand.self,
+ VPhoneCFWFlipSnapshotCommand.self,
+ // The per-step patchers the installers used to reach through
+ // scripts/patchers/cfw.py for — see VPhoneCFWPatchCLI.swift.
+ VPhoneCFWCryptexPathsCommand.self,
+ VPhoneCFWInjectDaemonsCommand.self,
+ VPhoneCFWInjectDaemonCommand.self,
+ VPhoneCFWPatchDropbearPlistCommand.self,
+ VPhoneCFWInjectDylibCommand.self,
+ VPhoneCFWPatchBuildVersionCommand.self,
+ VPhoneCFWPatchCampoEntitlementsCommand.self,
+ VPhoneCFWPatchPostRestoreDTCommand.self,
+ ])
}
/// Replaces `tools/apfs_snap_rename.py`, called from `cfw_install_host.sh`
diff --git a/sources/vphone-cli/VPhoneSignCLI.swift b/sources/vphone-cli/VPhoneSignCLI.swift
new file mode 100644
index 00000000..12b389c7
--- /dev/null
+++ b/sources/vphone-cli/VPhoneSignCLI.swift
@@ -0,0 +1,139 @@
+// VPhoneSignCLI.swift — `sign` and `dump-entitlements`, which replace ldid.
+//
+// ldid is the one program this project shipped that links Homebrew
+// (libcrypto.3, libplist-2.0.4), and so the one thing that failed the
+// self-contained admission rule. `VPhoneSign` writes the same bytes out of the
+// system frameworks; these two commands are the shape the installers called the
+// tool in:
+//
+// ldid -S"$ent" -M "-K$p12" -I"$id" <file> -> vphone-cli sign …
+// ldid -e <file> -> vphone-cli dump-entitlements
+//
+// Both keep the `--use-ldid` escape hatch (and the VPHONE_USE_LDID environment
+// variable behind it), so a regression is recoverable without a rebuild.
+
+import ArgumentParser
+import Foundation
+import VPhoneSign
+
+// MARK: - sign
+
+struct VPhoneSignCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "sign",
+ abstract: "Sign a Mach-O the way ldid does (replaces `ldid -S -M -K -I`)",
+ discussion: """
+ Writes, by default, byte for byte what ldid writes: no CMS blob, no
+ ad-hoc flag, and the designated requirement ldid synthesises. That is
+ what the guest's AMFI is known to accept, and what every call site in
+ this repository has always produced. `codesign --verify` rejects it —
+ it rejects ldid's own output too, for the same two reasons. Pass
+ --apple-adhoc for a signature in Apple's shape instead, which is what
+ `codesign --sign -` writes and what codesign will verify.
+
+ The file is replaced by rename(2) over a temporary beside it, with the
+ original mode copied across. That is deliberate: most of what this signs
+ came out of an IPSW at mode 444, and renaming over such a file needs
+ write permission on the directory, not on the file. An interrupted run
+ leaves the original untouched rather than half written.
+
+ --merge is ldid's -M: the entitlements given are merged over whatever
+ the file already carries, rather than replacing them. Without it, a
+ re-sign silently drops the sandbox profile and private entitlements a
+ binary like diskimagesiod cannot run without.
+ """
+ )
+
+ @Argument(help: "The Mach-O to sign, in place", transform: URL.init(fileURLWithPath:))
+ var file: URL
+
+ // Long spellings only, deliberately. ldid's short flags take their value
+ // attached (-S"$ent", -K"$p12"), which ArgumentParser reads as an unknown
+ // option; offering -S and -K here would invite exactly that call and answer
+ // it with a parse error about something else.
+ @Option(
+ name: .customLong("entitlements"),
+ help: "Entitlements plist to embed, as the file holds it",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var entitlements: URL?
+
+ @Option(
+ name: .customLong("identifier"),
+ help: "Signing identifier. Defaults to the file's name, as ldid does."
+ )
+ var identifier: String?
+
+ @Flag(name: .customLong("merge"), help: "Merge over the file's existing entitlements")
+ var merge = false
+
+ @Option(
+ name: .customLong("pkcs12"),
+ help: "Sign for real with this .p12 (no password) instead of ad-hoc",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var pkcs12: URL?
+
+ @Flag(
+ name: .customLong("apple-adhoc"),
+ help: "Write an ad-hoc signature in Apple's shape (codesign --sign -) rather than ldid's"
+ )
+ var appleAdHoc = false
+
+ @Flag(name: .customLong("use-ldid"), help: "Hand the file to the external ldid instead of signing here")
+ var useLdid = false
+
+ func run() throws {
+ var options = VPhoneSignOptions()
+ options.identifier = identifier
+ options.entitlements = try entitlements.map { try Data(contentsOf: $0) }
+ options.mergesExisting = merge
+ options.style = appleAdHoc ? .appleAdHoc : .ldid
+ if let pkcs12 {
+ // Both halves, and for different readers: the built-in signer wants
+ // the opened identity, and --use-ldid wants the container's path
+ // because ldid opens it itself. Setting only one of them is how a
+ // real signature used to become a silent ad-hoc downgrade; the
+ // external path now throws instead, which only works if the path is
+ // here to throw about.
+ options.identity = try VPhoneSignIdentity(pkcs12: Data(contentsOf: pkcs12), password: "")
+ options.identityPath = pkcs12.path
+ }
+ // nil, not false: nil lets VPHONE_USE_LDID decide, which is the whole
+ // point of the environment variable. Passing false would override it.
+ options.usesExternalLdid = useLdid ? true : nil
+
+ try VPhoneSigner.sign(fileAt: file, options: options)
+ }
+}
+
+// MARK: - dump-entitlements
+
+struct VPhoneDumpEntitlementsCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "dump-entitlements",
+ abstract: "Print a Mach-O's embedded entitlements (replaces `ldid -e`)",
+ discussion: """
+ Writes the entitlements of every slice that carries any, in slice order,
+ exactly as the signature stores them and with nothing in between —
+ which is what `ldid -e` does, and what the installers depend on when
+ they redirect this into a plist and feed it back to `sign --merge`.
+
+ A slice with no entitlements contributes nothing, so a file with none at
+ all prints nothing and still exits zero.
+ """
+ )
+
+ @Argument(help: "The Mach-O to read", transform: URL.init(fileURLWithPath:))
+ var file: URL
+
+ func run() throws {
+ // Raw bytes, not print(): the blob is a plist as the signature stores
+ // it, and a trailing newline per slice would be a byte ldid did not
+ // write into a file that gets parsed.
+ let out = FileHandle.standardOutput
+ for blob in try VPhoneSigner.entitlements(ofFileAt: file) {
+ out.write(blob)
+ }
+ }
+}
diff --git a/sources/vphone-cli/VPhoneVMTransferCLI.swift b/sources/vphone-cli/VPhoneVMTransferCLI.swift
index 30686827..965ee168 100644
--- a/sources/vphone-cli/VPhoneVMTransferCLI.swift
+++ b/sources/vphone-cli/VPhoneVMTransferCLI.swift
@@ -1,5 +1,6 @@
import ArgumentParser
import Foundation
+import VPhoneArchive
import VPhoneCore
struct VPhoneVMCloneCommand: ParsableCommand {
@@ -36,9 +37,9 @@ struct VPhoneVMExportCommand: ParsableCommand {
func run() throws {
let name = try VPhoneVMSelection.resolveExisting(name, in: lib.library)
- let compression: VPhoneBundleOps.ExportCompression = max ? .max : .fast
+ let compression: VPhoneBundleTransfer.ExportCompression = max ? .max : .fast
let bar = VPhoneProgressBar(label: "exporting \(name)")
- let outURL = try VPhoneBundleOps.export(
+ let outURL = try VPhoneBundleTransfer.export(
bundleNamed: name,
to: URL(fileURLWithPath: out),
includeIPSW: includeIpsw,
@@ -63,7 +64,7 @@ struct VPhoneVMImportCommand: ParsableCommand {
func run() throws {
let bar = VPhoneProgressBar(label: "importing")
- let bundle = try VPhoneBundleOps.importArchive(
+ let bundle = try VPhoneBundleTransfer.importArchive(
from: URL(fileURLWithPath: input),
name: name,
in: lib.library,
diff --git a/tests/FirmwarePatcherTests/ARM64EncoderTests.swift b/tests/FirmwarePatcherTests/ARM64EncoderTests.swift
new file mode 100644
index 00000000..3494765a
--- /dev/null
+++ b/tests/FirmwarePatcherTests/ARM64EncoderTests.swift
@@ -0,0 +1,535 @@
+// ARM64EncoderTests.swift — every ARM64Encoder output asserted against keystone.
+//
+// The expected words are keystone-engine's, taken from the repo venv:
+//
+// .venv/bin/python3 -c "from keystone import *; \
+// ks = Ks(KS_ARCH_ARM64, KS_MODE_LITTLE_ENDIAN); print(ks.asm('cset w0, eq')[0])"
+//
+// keystone is what the Python patchers call today, so agreement with it is the
+// migration's correctness bar: a disagreement is a bug in ARM64Encoder.
+//
+// `asmCallSiteCases` is not an arbitrary sample — it is the closed set of
+// instructions the 19 patchers in scripts/patchers/ actually assemble, one entry
+// per `asm(...)` / `asm_at(...)` call site, each tagged with that site.
+// `operandCoverageCases` then exercises the rest of each encoder's operand range
+// (encoding-boundary immediates, backward branches, every shift amount), because
+// the call sites alone leave most fields pinned at one value.
+
+@testable import FirmwarePatcher
+import Foundation
+import Testing
+
+// MARK: - Case Model
+
+/// One encoder output paired with the keystone encoding of the same instruction.
+struct ARM64EncodingCase: Sendable, CustomStringConvertible {
+ /// The assembly the Python patcher passes to keystone.
+ let source: String
+ /// keystone-engine's encoding of `source` (at `address`, where it matters).
+ let keystone: UInt32
+ /// What `ARM64Encoder` produced; nil means the encoder refused.
+ let encoded: Data?
+ /// The patcher call site this instruction comes from, or the field being covered.
+ let origin: String
+
+ var description: String { "\(source) [\(origin)]" }
+}
+
+private func word(_ data: Data) -> UInt32 {
+ let bytes = [UInt8](data)
+ return UInt32(bytes[0])
+ | UInt32(bytes[1]) << 8
+ | UInt32(bytes[2]) << 16
+ | UInt32(bytes[3]) << 24
+}
+
+// MARK: - Parity Against Keystone
+
+struct ARM64EncoderKeystoneParityTests {
+ // MARK: The instructions the patchers assemble
+
+ /// Every distinct `asm(...)` / `asm_at(...)` instruction in scripts/patchers/.
+ /// The three fixed ones (`nop`, `ret`, `mov x0, #1`) live in ARM64Constants and
+ /// are checked in `constantsMatchKeystone` below.
+ ///
+ /// `origin` names the patcher and the Python expression, not a line number:
+ /// these files are being ported and the line numbers move. Re-derive the set with
+ /// `grep -rnE '\basm(_at)?\(' scripts/patchers/`.
+ static let asmCallSiteCases: [ARM64EncodingCase] = [
+ // asm("mov w0, #0\nret") — force the camera check to return 0
+ ARM64EncodingCase(
+ source: "mov w0, #0", keystone: 0x5280_0000,
+ encoded: ARM64Encoder.encodeMovzW(rd: 0, imm16: 0),
+ origin: #"camera_dsc asm("mov w0, #0\nret")"#
+ ),
+ // asm("mov w0, #3\nret")
+ ARM64EncodingCase(
+ source: "mov w0, #3", keystone: 0x5280_0060,
+ encoded: ARM64Encoder.encodeMovzW(rd: 0, imm16: 3),
+ origin: #"camera_dsc asm("mov w0, #3\nret")"#
+ ),
+ // asm_at(f"b #{kern_va}", pub_va) — redirect the public stub at its own address
+ ARM64EncodingCase(
+ source: "b #0x1010 @0x1000", keystone: 0x1400_0004,
+ encoded: ARM64Encoder.encodeB(from: 0x1000, to: 0x1010),
+ origin: #"iomfb_force_kern asm_at("b #{kern_va}", pub_va)"#
+ ),
+ // asm_at(f"b #0x{patch_target:X}", patch_off) — the same shape, backwards
+ ARM64EncodingCase(
+ source: "b #0x1000 @0x2000", keystone: 0x17FF_FC00,
+ encoded: ARM64Encoder.encodeB(from: 0x2000, to: 0x1000),
+ origin: #"jetsam asm_at("b #{patch_target}", patch_off)"#
+ ),
+ // asm(f"mov w3, #{target_size}"), where TARGET_SIZE == 0x588
+ ARM64EncodingCase(
+ source: "mov w3, #0x588", keystone: 0x5280_B103,
+ encoded: ARM64Encoder.encodeMovzW(rd: 3, imm16: 0x588),
+ origin: #"iomfb_swapend asm("mov w3, #{target_size}")"#
+ ),
+ // The next seven build the SwapEnd call-setup sequence in _self_test().
+ ARM64EncodingCase(
+ source: "ldr w0, [x0, #0x14]", keystone: 0xB940_1400,
+ encoded: ARM64Encoder.encodeLdrWUnsignedOffset(rt: 0, rn: 0, offset: 0x14),
+ origin: #"iomfb_swapend asm("ldr w0, [x0, #0x14]")"#
+ ),
+ ARM64EncodingCase(
+ source: "add x2, x19, #0x18", keystone: 0x9100_6262,
+ encoded: ARM64Encoder.encodeAddImm12(rd: 2, rn: 19, imm12: 0x18),
+ origin: #"iomfb_swapend asm("add x2, x19, #0x18")"#
+ ),
+ ARM64EncodingCase(
+ source: "mov w1, #5", keystone: 0x5280_00A1,
+ encoded: ARM64Encoder.encodeMovzW(rd: 1, imm16: 5),
+ origin: #"iomfb_swapend asm("mov w1, #5")"#
+ ),
+ ARM64EncodingCase(
+ source: "mov w3, #0x548", keystone: 0x5280_A903,
+ encoded: ARM64Encoder.encodeMovzW(rd: 3, imm16: 0x548),
+ origin: #"iomfb_swapend asm("mov w3, #0x548")"#
+ ),
+ ARM64EncodingCase(
+ source: "mov x4, #0", keystone: 0xD280_0004,
+ encoded: ARM64Encoder.encodeMovzX(rd: 4, imm16: 0),
+ origin: #"iomfb_swapend asm("mov x4, #0")"#
+ ),
+ ARM64EncodingCase(
+ source: "mov x5, #0", keystone: 0xD280_0005,
+ encoded: ARM64Encoder.encodeMovzX(rd: 5, imm16: 0),
+ origin: #"iomfb_swapend asm("mov x5, #0")"#
+ ),
+ // asm("bl #0x40") — plain asm(), so keystone assembles it at address 0.
+ ARM64EncodingCase(
+ source: "bl #0x40 @0x0", keystone: 0x9400_0010,
+ encoded: ARM64Encoder.encodeBL(from: 0, to: 0x40),
+ origin: #"iomfb_swapend asm("bl #0x40")"#
+ ),
+ // asm(f"mov {m['cset_reg']}, #1") — cset_reg is always a W register; the
+ // matcher rejects any destination that does not start with "w".
+ ARM64EncodingCase(
+ source: "mov w8, #1", keystone: 0x5280_0028,
+ encoded: ARM64Encoder.encodeMovzW(rd: 8, imm16: 1),
+ origin: #"watchdogd asm("mov {cset_reg}, #1")"#
+ ),
+ // asm("cset w0, eq") — the one instruction with no encoder before this change
+ ARM64EncodingCase(
+ source: "cset w0, eq", keystone: 0x1A9F_17E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .eq),
+ origin: #"xpc_lwcr asm("cset w0, eq")"#
+ ),
+ ]
+
+ // MARK: The rest of each encoder's operand range
+
+ static let operandCoverageCases: [ARM64EncodingCase] = [
+ // --- encodeB: both signs, and both ends of the imm26 range -------
+ ARM64EncodingCase(
+ source: "b #0x7FFFFFC @0x0", keystone: 0x15FF_FFFF,
+ encoded: ARM64Encoder.encodeB(from: 0, to: 0x7FF_FFFC),
+ origin: "B max forward"
+ ),
+ ARM64EncodingCase(
+ source: "b #0x0 @0x8000000", keystone: 0x1600_0000,
+ encoded: ARM64Encoder.encodeB(from: 0x800_0000, to: 0),
+ origin: "B max backward"
+ ),
+ // --- encodeBL ----------------------------------------------------
+ ARM64EncodingCase(
+ source: "bl #0x1100 @0x1000", keystone: 0x9400_0040,
+ encoded: ARM64Encoder.encodeBL(from: 0x1000, to: 0x1100),
+ origin: "BL forward"
+ ),
+ ARM64EncodingCase(
+ source: "bl #0x2000 @0x3000", keystone: 0x97FF_FC00,
+ encoded: ARM64Encoder.encodeBL(from: 0x3000, to: 0x2000),
+ origin: "BL backward"
+ ),
+ // --- encodeTestBitBranch: b5 both ways, TBZ and TBNZ, both signs --
+ ARM64EncodingCase(
+ source: "tbz w8, #0xb, #0x14", keystone: 0x3658_00A8,
+ encoded: ARM64Encoder.encodeTestBitBranch(
+ nonzero: false, register: 8, bit: 11, from: 0, to: 0x14
+ ),
+ origin: "TBZ W, bit<32"
+ ),
+ ARM64EncodingCase(
+ source: "tbz w8, #0xa, #0x14", keystone: 0x3650_00A8,
+ encoded: ARM64Encoder.encodeTestBitBranch(
+ nonzero: false, register: 8, bit: 10, from: 0, to: 0x14
+ ),
+ origin: "TBZ W, bit<32"
+ ),
+ ARM64EncodingCase(
+ source: "tbnz w0, #0, #0x8", keystone: 0x3700_0040,
+ encoded: ARM64Encoder.encodeTestBitBranch(
+ nonzero: true, register: 0, bit: 0, from: 0, to: 8
+ ),
+ origin: "TBNZ bit 0"
+ ),
+ ARM64EncodingCase(
+ source: "tbz x9, #32, #0x40", keystone: 0xB600_0209,
+ encoded: ARM64Encoder.encodeTestBitBranch(
+ nonzero: false, register: 9, bit: 32, from: 0, to: 0x40
+ ),
+ origin: "TBZ X, b5 set"
+ ),
+ ARM64EncodingCase(
+ source: "tbnz x3, #63, #0x0 @0x100", keystone: 0xB7FF_F803,
+ encoded: ARM64Encoder.encodeTestBitBranch(
+ nonzero: true, register: 3, bit: 63, from: 0x100, to: 0
+ ),
+ origin: "TBNZ bit 63, backward"
+ ),
+ // --- encodeADRP: forward, backward, and same page ----------------
+ ARM64EncodingCase(
+ source: "adrp x2, #0x5000 @0x1000", keystone: 0x9000_0022,
+ encoded: ARM64Encoder.encodeADRP(rd: 2, pc: 0x1000, target: 0x5000),
+ origin: "ADRP forward"
+ ),
+ ARM64EncodingCase(
+ source: "adrp x0, #0x1000 @0x9000", keystone: 0x90FF_FFC0,
+ encoded: ARM64Encoder.encodeADRP(rd: 0, pc: 0x9000, target: 0x1000),
+ origin: "ADRP backward"
+ ),
+ ARM64EncodingCase(
+ source: "adrp x17, #0x1000 @0x1FFF", keystone: 0x9000_0011,
+ encoded: ARM64Encoder.encodeADRP(rd: 17, pc: 0x1FFF, target: 0x1000),
+ origin: "ADRP same page, unaligned PC"
+ ),
+ // --- encodeAddImm12 ----------------------------------------------
+ ARM64EncodingCase(
+ source: "add x2, x2, #0xabc", keystone: 0x912A_F042,
+ encoded: ARM64Encoder.encodeAddImm12(rd: 2, rn: 2, imm12: 0xABC),
+ origin: "ADD imm12"
+ ),
+ ARM64EncodingCase(
+ source: "add x0, x0, #0", keystone: 0x9100_0000,
+ encoded: ARM64Encoder.encodeAddImm12(rd: 0, rn: 0, imm12: 0),
+ origin: "ADD imm12 = 0"
+ ),
+ // --- encodeMovzW / encodeMovzX: every legal hw --------------------
+ ARM64EncodingCase(
+ source: "movz w5, #0x1234, lsl #16", keystone: 0x52A2_4685,
+ encoded: ARM64Encoder.encodeMovzW(rd: 5, imm16: 0x1234, shift: 16),
+ origin: "MOVZ W hw=1"
+ ),
+ ARM64EncodingCase(
+ source: "movz x3, #0x4000", keystone: 0xD288_0003,
+ encoded: ARM64Encoder.encodeMovzX(rd: 3, imm16: 0x4000, shift: 0),
+ origin: "MOVZ X hw=0"
+ ),
+ ARM64EncodingCase(
+ source: "movz x9, #0xbeef, lsl #32", keystone: 0xD2D7_DDE9,
+ encoded: ARM64Encoder.encodeMovzX(rd: 9, imm16: 0xBEEF, shift: 32),
+ origin: "MOVZ X hw=2"
+ ),
+ ARM64EncodingCase(
+ source: "movz x1, #0xdead, lsl #48", keystone: 0xD2FB_D5A1,
+ encoded: ARM64Encoder.encodeMovzX(rd: 1, imm16: 0xDEAD, shift: 48),
+ origin: "MOVZ X hw=3"
+ ),
+ // --- encodeMovX ---------------------------------------------------
+ ARM64EncodingCase(
+ source: "mov x0, x20", keystone: 0xAA14_03E0,
+ encoded: ARM64Encoder.encodeMovX(rd: 0, rm: 20),
+ origin: "MOV X reg"
+ ),
+ ARM64EncodingCase(
+ source: "mov x9, xzr", keystone: 0xAA1F_03E9,
+ encoded: ARM64Encoder.encodeMovX(rd: 9, rm: 31),
+ origin: "MOV X from XZR"
+ ),
+ ARM64EncodingCase(
+ source: "mov x30, x1", keystone: 0xAA01_03FE,
+ encoded: ARM64Encoder.encodeMovX(rd: 30, rm: 1),
+ origin: "MOV X high Rd"
+ ),
+ // --- encodeCsetW: all 14 conditions, plus other destinations ------
+ ARM64EncodingCase(
+ source: "cset w0, ne", keystone: 0x1A9F_07E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .ne), origin: "CSET ne"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, hs", keystone: 0x1A9F_37E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .hs), origin: "CSET hs"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, lo", keystone: 0x1A9F_27E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .lo), origin: "CSET lo"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, mi", keystone: 0x1A9F_57E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .mi), origin: "CSET mi"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, pl", keystone: 0x1A9F_47E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .pl), origin: "CSET pl"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, vs", keystone: 0x1A9F_77E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .vs), origin: "CSET vs"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, vc", keystone: 0x1A9F_67E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .vc), origin: "CSET vc"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, hi", keystone: 0x1A9F_97E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .hi), origin: "CSET hi"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, ls", keystone: 0x1A9F_87E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .ls), origin: "CSET ls"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, ge", keystone: 0x1A9F_B7E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .ge), origin: "CSET ge"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, lt", keystone: 0x1A9F_A7E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .lt), origin: "CSET lt"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, gt", keystone: 0x1A9F_D7E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .gt), origin: "CSET gt"
+ ),
+ ARM64EncodingCase(
+ source: "cset w0, le", keystone: 0x1A9F_C7E0,
+ encoded: ARM64Encoder.encodeCsetW(rd: 0, condition: .le), origin: "CSET le"
+ ),
+ ARM64EncodingCase(
+ source: "cset w8, ne", keystone: 0x1A9F_07E8,
+ encoded: ARM64Encoder.encodeCsetW(rd: 8, condition: .ne), origin: "CSET Rd=8"
+ ),
+ ARM64EncodingCase(
+ source: "cset w19, eq", keystone: 0x1A9F_17F3,
+ encoded: ARM64Encoder.encodeCsetW(rd: 19, condition: .eq), origin: "CSET Rd=19"
+ ),
+ // --- encodeLdrWUnsignedOffset: zero, SP base, both imm12 ends -----
+ ARM64EncodingCase(
+ source: "ldr w7, [x19]", keystone: 0xB940_0267,
+ encoded: ARM64Encoder.encodeLdrWUnsignedOffset(rt: 7, rn: 19, offset: 0),
+ origin: "LDR W offset 0"
+ ),
+ ARM64EncodingCase(
+ source: "ldr w8, [sp, #0xcc]", keystone: 0xB940_CFE8,
+ encoded: ARM64Encoder.encodeLdrWUnsignedOffset(rt: 8, rn: 31, offset: 0xCC),
+ origin: "LDR W base = SP"
+ ),
+ ARM64EncodingCase(
+ source: "ldr w8, [x0, #0x454]", keystone: 0xB944_5408,
+ encoded: ARM64Encoder.encodeLdrWUnsignedOffset(rt: 8, rn: 0, offset: 0x454),
+ origin: "LDR W mid offset"
+ ),
+ ARM64EncodingCase(
+ source: "ldr w30, [x29, #0x3ffc]", keystone: 0xB97F_FFBE,
+ encoded: ARM64Encoder.encodeLdrWUnsignedOffset(rt: 30, rn: 29, offset: 0x3FFC),
+ origin: "LDR W max imm12"
+ ),
+ ]
+
+ static let allCases: [ARM64EncodingCase] = asmCallSiteCases + operandCoverageCases
+
+ // MARK: Parity
+
+ @Test(arguments: ARM64EncoderKeystoneParityTests.allCases)
+ func matchesKeystone(_ testCase: ARM64EncodingCase) throws {
+ let data = try #require(testCase.encoded, "encoder refused \(testCase.source)")
+ #expect(data.count == 4, "\(testCase.source): expected 4 bytes, got \(data.count)")
+ let produced = word(data)
+ #expect(
+ produced == testCase.keystone,
+ """
+ \(testCase.source) [\(testCase.origin)]
+ ARM64Encoder: 0x\(String(produced, radix: 16, uppercase: true))
+ keystone: 0x\(String(testCase.keystone, radix: 16, uppercase: true))
+ """
+ )
+ }
+
+ /// Every `asm(...)` site in the patchers is represented, and each one
+ /// disassembles back to the mnemonic the Python source names.
+ @Test(arguments: ARM64EncoderKeystoneParityTests.allCases)
+ func roundTripsThroughCapstone(_ testCase: ARM64EncodingCase) throws {
+ let data = try #require(testCase.encoded)
+ let disasm = ARM64Disassembler()
+ // Address 0 is fine: only the mnemonic is asserted, and the keystone parity
+ // test above already pins the PC-relative operand bits exactly.
+ let insn = try #require(
+ disasm.disassembleOne(data, at: 0),
+ "capstone could not decode \(testCase.source)"
+ )
+ let expectedMnemonic = String(testCase.source.prefix(while: { $0 != " " }))
+ // A MOVZ with any `hw` is expressible as MOV (wide immediate), and capstone
+ // always prints that alias — the keystone source spells it either way.
+ let accepted: Set<String> = expectedMnemonic == "movz"
+ ? ["movz", "mov"]
+ : [expectedMnemonic]
+ #expect(
+ accepted.contains(insn.mnemonic),
+ "\(testCase.source): capstone read it as '\(insn.mnemonic) \(insn.operandString)'"
+ )
+ }
+
+ // MARK: Fixed constants used at asm() sites
+
+ /// `nop`, `ret` and `mov x0, #1` are `asm()` results in cfw_asm.py (NOP / RET /
+ /// MOV_X0_1) and ship as constants rather than encoder calls. The rest of the
+ /// public table is checked alongside them, since keystone was available.
+ ///
+ /// `retaa`, `retab` and `pacibsp` are absent: this keystone build rejects those
+ /// mnemonics (KS_ERR_ASM_MNEMONICFAIL). `pacibsp` is checked through its `hint
+ /// #27` spelling, which keystone does accept; retaa/retab stay on the capstone
+ /// round-trip in ARM64ConstantTests.
+ @Test func constantsMatchKeystone() {
+ let expected: [(String, Data, UInt32)] = [
+ ("nop", ARM64.nop, 0xD503_201F),
+ ("ret", ARM64.ret, 0xD65F_03C0),
+ ("pacibsp (hint #27)", ARM64.pacibsp, 0xD503_237F),
+ ("movz x0, #0", ARM64.movX0_0, 0xD280_0000),
+ ("movz x0, #1", ARM64.movX0_1, 0xD280_0020),
+ ("movz w0, #0", ARM64.movW0_0, 0x5280_0000),
+ ("movz w0, #1", ARM64.movW0_1, 0x5280_0020),
+ ("mov x0, x20", ARM64.movX0X20, 0xAA14_03E0),
+ ("movz w0, #0xa1", ARM64.movW0_0xA1, 0x5280_1420),
+ ("cmp w0, w0", ARM64.cmpW0W0, 0x6B00_001F),
+ ("cmp x0, x0", ARM64.cmpX0X0, 0xEB00_001F),
+ ("strb w0, [x20, #0x30]", ARM64.strbW0X20_30, 0x3900_C280),
+ ("cbz x2, #8", ARM64.cbzX2_8, 0xB400_0042),
+ ("str x0, [x2]", ARM64.strX0X2, 0xF900_0040),
+ ("cmp xzr, xzr", ARM64.cmpXzrXzr, 0xEB1F_03FF),
+ ]
+ for (source, data, keystone) in expected {
+ let produced = String(word(data), radix: 16, uppercase: true)
+ let reference = String(keystone, radix: 16, uppercase: true)
+ #expect(word(data) == keystone, "\(source): constant 0x\(produced) != keystone 0x\(reference)")
+ }
+ }
+
+ /// The three constants that stand in for `asm()` results are byte-identical to
+ /// the encoder path, so a patcher may use either without a behaviour change.
+ @Test func constantsAgreeWithEncoders() {
+ #expect(ARM64.movX0_1 == ARM64Encoder.encodeMovzX(rd: 0, imm16: 1))
+ #expect(ARM64.movX0_0 == ARM64Encoder.encodeMovzX(rd: 0, imm16: 0))
+ #expect(ARM64.movW0_0 == ARM64Encoder.encodeMovzW(rd: 0, imm16: 0))
+ #expect(ARM64.movW0_1 == ARM64Encoder.encodeMovzW(rd: 0, imm16: 1))
+ #expect(ARM64.movX0X20 == ARM64Encoder.encodeMovX(rd: 0, rm: 20))
+ }
+}
+
+// MARK: - Range And Refusal
+
+struct ARM64EncoderRangeTests {
+ // MARK: Branches
+
+ @Test func branchRefusesUnalignedAndOutOfRange() {
+ #expect(ARM64Encoder.encodeB(from: 0, to: 2) == nil, "unaligned target")
+ #expect(ARM64Encoder.encodeB(from: 0, to: 0x800_0000) == nil, "one past +128 MB")
+ #expect(ARM64Encoder.encodeB(from: 0x800_0004, to: 0) == nil, "one past -128 MB")
+ #expect(ARM64Encoder.encodeBL(from: 0, to: 1) == nil, "unaligned target")
+ #expect(ARM64Encoder.encodeBL(from: 0, to: 0x800_0000) == nil, "one past +128 MB")
+ }
+
+ @Test func testBitBranchRefusesBadOperands() {
+ #expect(
+ ARM64Encoder.encodeTestBitBranch(nonzero: false, register: 32, bit: 0, from: 0, to: 4) == nil,
+ "register out of range"
+ )
+ #expect(
+ ARM64Encoder.encodeTestBitBranch(nonzero: false, register: 0, bit: 64, from: 0, to: 4) == nil,
+ "bit out of range"
+ )
+ #expect(
+ ARM64Encoder.encodeTestBitBranch(nonzero: false, register: 0, bit: 0, from: 0, to: 0x8000) == nil,
+ "one past +32 KB"
+ )
+ }
+
+ // MARK: ADRP / ADD / MOVZ
+
+ @Test func adrpAndAddRefuseOutOfRange() {
+ // ADRP reaches +/-4 GB; one page past that must be refused.
+ #expect(ARM64Encoder.encodeADRP(rd: 0, pc: 0, target: 1 << 32) == nil)
+ #expect(ARM64Encoder.encodeAddImm12(rd: 0, rn: 0, imm12: 4096) == nil)
+ }
+
+ @Test func movzRefusesUnrepresentableShift() {
+ #expect(ARM64Encoder.encodeMovzW(rd: 0, imm16: 1, shift: 32) == nil, "W has hw 0..1")
+ #expect(ARM64Encoder.encodeMovzX(rd: 0, imm16: 1, shift: 64) == nil, "X has hw 0..3")
+ }
+
+ // MARK: CSET
+
+ @Test func csetRefusesInvalidRegister() {
+ #expect(ARM64Encoder.encodeCsetW(rd: 32, condition: .eq) == nil)
+ }
+
+ /// CSET encodes the inverse of the written condition, so inverting twice has to
+ /// be the identity — otherwise the alias silently means the opposite thing.
+ @Test func conditionInversionIsAnInvolution() {
+ for condition in ARM64Condition.allCases {
+ #expect(condition.inverted.inverted == condition, "\(condition) inverted twice")
+ #expect(condition.inverted != condition, "\(condition) is its own inverse")
+ #expect(condition.inverted.rawValue == condition.rawValue ^ 1)
+ }
+ }
+
+ // MARK: LDR
+
+ @Test func ldrRefusesUnscalableOffsets() {
+ #expect(
+ ARM64Encoder.encodeLdrWUnsignedOffset(rt: 0, rn: 0, offset: 0x13) == nil,
+ "offset must be a multiple of 4"
+ )
+ #expect(
+ ARM64Encoder.encodeLdrWUnsignedOffset(rt: 0, rn: 0, offset: 0x4000) == nil,
+ "one past the scaled imm12 range"
+ )
+ #expect(ARM64Encoder.encodeLdrWUnsignedOffset(rt: 32, rn: 0, offset: 0) == nil)
+ #expect(ARM64Encoder.encodeLdrWUnsignedOffset(rt: 0, rn: 32, offset: 0) == nil)
+ }
+
+ // MARK: Decode
+
+ /// `decodeBranchTarget` is the inverse of `encodeB` / `encodeBL`; the two must
+ /// agree, because the patchers use the decoder to find the site they then re-encode.
+ @Test func decodeBranchTargetInvertsEncode() throws {
+ let sites: [(UInt64, UInt64)] = [
+ (0x1000, 0x1010), (0x2000, 0x1000), (0, 0x40), (0x800_0000, 0),
+ ]
+ for (pc, target) in sites {
+ let branch = try #require(ARM64Encoder.encodeB(from: Int(pc), to: Int(target)))
+ let link = try #require(ARM64Encoder.encodeBL(from: Int(pc), to: Int(target)))
+ for data in [branch, link] {
+ let bytes = [UInt8](data)
+ let insn = UInt32(bytes[0]) | UInt32(bytes[1]) << 8
+ | UInt32(bytes[2]) << 16 | UInt32(bytes[3]) << 24
+ #expect(ARM64Encoder.decodeBranchTarget(insn: insn, pc: pc) == target)
+ }
+ }
+ }
+
+ @Test func decodeBranchTargetRejectsNonBranches() {
+ #expect(ARM64Encoder.decodeBranchTarget(insn: ARM64.nopU32, pc: 0) == nil)
+ #expect(ARM64Encoder.decodeBranchTarget(insn: ARM64.retU32, pc: 0) == nil)
+ }
+}
diff --git a/tests/FirmwarePatcherTests/CFWDaemonsTests.swift b/tests/FirmwarePatcherTests/CFWDaemonsTests.swift
new file mode 100644
index 00000000..a1f68f97
--- /dev/null
+++ b/tests/FirmwarePatcherTests/CFWDaemonsTests.swift
@@ -0,0 +1,509 @@
+import Foundation
+import Testing
+@testable import FirmwarePatcher
+
+// MARK: - Plist semantics
+
+/// Recursive semantic comparison of two property lists.
+///
+/// Byte equality is the wrong bar here and would fail on correct output: two XML
+/// plist writers disagree on `<data>` line width, on `<real>` digits, and on
+/// dictionary key order, none of which any consumer of these files can observe.
+/// What *is* semantic — and what this checks — is the type of every value, the
+/// order of every array, the key set of every dictionary and the bytes of every
+/// `<data>`.
+enum PlistSemantics {
+ /// Every place the two differ, as readable key paths. Empty means equivalent.
+ static func differences(_ lhs: Any, _ rhs: Any, at path: String = "<root>") -> [String] {
+ // CFBoolean bridges to NSNumber, so `1` and `true` would compare equal
+ // if the number branch saw them first. Type is semantic; check it first.
+ if isBoolean(lhs) || isBoolean(rhs) {
+ guard let left = lhs as? Bool, let right = rhs as? Bool, isBoolean(lhs), isBoolean(rhs) else {
+ return ["\(path): boolean vs \(describe(isBoolean(lhs) ? rhs : lhs))"]
+ }
+ return left == right ? [] : ["\(path): \(left) != \(right)"]
+ }
+
+ switch (lhs, rhs) {
+ case let (left as [String: Any], right as [String: Any]):
+ var found: [String] = []
+ let leftKeys = Set(left.keys)
+ let rightKeys = Set(right.keys)
+ for key in leftKeys.subtracting(rightKeys).sorted() {
+ found.append("\(path).\(key): only on the left")
+ }
+ for key in rightKeys.subtracting(leftKeys).sorted() {
+ found.append("\(path).\(key): only on the right")
+ }
+ for key in leftKeys.intersection(rightKeys).sorted() {
+ found += differences(left[key]!, right[key]!, at: "\(path).\(key)")
+ }
+ return found
+
+ case let (left as [Any], right as [Any]):
+ guard left.count == right.count else {
+ return ["\(path): array of \(left.count) vs \(right.count)"]
+ }
+ return (0 ..< left.count).flatMap {
+ differences(left[$0], right[$0], at: "\(path)[\($0)]")
+ }
+
+ case let (left as String, right as String):
+ return left == right ? [] : ["\(path): \"\(left)\" != \"\(right)\""]
+
+ case let (left as Data, right as Data):
+ return left == right ? [] : ["\(path): \(left.count) bytes != \(right.count) bytes"]
+
+ case let (left as Date, right as Date):
+ return left == right ? [] : ["\(path): \(left) != \(right)"]
+
+ case let (left as NSNumber, right as NSNumber):
+ let leftIsFloat = CFNumberIsFloatType(left as CFNumber)
+ let rightIsFloat = CFNumberIsFloatType(right as CFNumber)
+ if leftIsFloat != rightIsFloat {
+ return ["\(path): \(leftIsFloat ? "real" : "integer") vs \(rightIsFloat ? "real" : "integer")"]
+ }
+ return left == right ? [] : ["\(path): \(left) != \(right)"]
+
+ default:
+ return ["\(path): \(describe(lhs)) vs \(describe(rhs))"]
+ }
+ }
+
+ private static func isBoolean(_ value: Any) -> Bool {
+ CFGetTypeID(value as CFTypeRef) == CFBooleanGetTypeID()
+ }
+
+ private static func describe(_ value: Any) -> String {
+ "\(type(of: value))(\(value))"
+ }
+}
+
+// MARK: - Fixtures
+
+enum CFWDaemonsFixtures {
+ /// The repository root, from this file's own path.
+ static let repositoryRoot = URL(filePath: #filePath)
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+
+ static let python = repositoryRoot.appending(path: ".venv/bin/python3")
+ static let cfwPy = repositoryRoot.appending(path: "scripts/patchers/cfw.py")
+ static let buildManifest = repositoryRoot.appending(path: "ipsws/ref_extract/iphone/BuildManifest.plist")
+ static let cfwInputArchive = repositoryRoot.appending(path: "scripts/resources/cfw_input.tar.zst")
+ static let jbSetupPlist = repositoryRoot.appending(path: "scripts/vphone_jb_setup.plist")
+
+ /// A real `launchd.plist` of the shape the installer rewrites.
+ ///
+ /// The guest's copy lives on a volume that needs root to mount; the host's is
+ /// the same file, produced by the same build system, and is world-readable.
+ static let hostLaunchdPlist = URL(filePath: "/System/Library/xpc/launchd.plist")
+
+ /// Whether the Python this ports is still in the tree to compare against.
+ /// It is deleted at the end of P1, and these comparisons go with it.
+ static var pythonReferenceAvailable: Bool {
+ [python, cfwPy, buildManifest, cfwInputArchive, hostLaunchdPlist]
+ .allSatisfy { FileManager.default.fileExists(atPath: $0.path) }
+ }
+
+ static func temporaryDirectory() throws -> URL {
+ let url = URL(filePath: NSTemporaryDirectory())
+ .appending(path: "CFWDaemonsTests-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+ return url
+ }
+
+ /// The installer's real LaunchDaemons staging directory, unpacked from the
+ /// resource archive the installer itself consumes.
+ static func unpackLaunchDaemons(into directory: URL) throws -> URL {
+ try run("/usr/bin/tar", [
+ "-xf", cfwInputArchive.path,
+ "-C", directory.path,
+ "cfw_input/jb/LaunchDaemons",
+ ])
+ return directory.appending(path: "cfw_input/jb/LaunchDaemons")
+ }
+
+ @discardableResult
+ static func run(_ executable: String, _ arguments: [String]) throws -> String {
+ let process = Process()
+ process.executableURL = URL(filePath: executable)
+ process.arguments = arguments
+ let pipe = Pipe()
+ process.standardOutput = pipe
+ process.standardError = Pipe()
+ try process.run()
+ let output = pipe.fileHandleForReading.readDataToEndOfFile()
+ process.waitUntilExit()
+ #expect(process.terminationStatus == 0, "\(executable) \(arguments.joined(separator: " "))")
+ return String(data: output, encoding: .utf8) ?? ""
+ }
+
+ static func loadPlist(_ url: URL) throws -> [String: Any] {
+ let data = try Data(contentsOf: url)
+ return try PropertyListSerialization.propertyList(from: data, options: [], format: nil)
+ as? [String: Any] ?? [:]
+ }
+
+ /// Copy a plist somewhere writable — the sources are all read-only originals.
+ static func writableCopy(of source: URL, in directory: URL, named name: String) throws -> URL {
+ let destination = directory.appending(path: name)
+ try FileManager.default.copyItem(at: source, to: destination)
+ try FileManager.default.setAttributes([.posixPermissions: 0o644], ofItemAtPath: destination.path)
+ return destination
+ }
+}
+
+// MARK: - Unit tests
+
+@Suite("CFW daemon plist rewrites")
+struct CFWDaemonsTests {
+ // MARK: - dropbear ProgramArguments
+ //
+ // Both cases below came over verbatim from tests/test_dropbear_plist.py,
+ // which covered this exact rewrite and which no runner ever invoked.
+
+ @Test("-R is dropped and the seeded host keys are appended")
+ func rewritesReadOnlyRootKeyGeneration() {
+ var daemon: PlistDict = [
+ "ProgramArguments": [
+ "/iosbinpack64/usr/local/bin/dropbear",
+ "--shell",
+ "/iosbinpack64/bin/bash",
+ "-R",
+ "-E",
+ "-F",
+ "-p",
+ "22222",
+ "-a",
+ ],
+ ]
+
+ CFWDaemons.patchDropbearDaemon(&daemon)
+
+ let arguments = daemon["ProgramArguments"] as? [Any] ?? []
+ let strings = arguments.compactMap { $0 as? String }
+ #expect(!strings.contains("-R"))
+ #expect(Array(strings.suffix(CFWDaemons.dropbearKeyArguments.count)) == CFWDaemons.dropbearKeyArguments)
+ }
+
+ @Test("stale explicit -r key paths are replaced, not kept")
+ func replacesStaleExplicitKeyPaths() {
+ var daemon: PlistDict = [
+ "ProgramArguments": [
+ "dropbear",
+ "-r",
+ "/etc/dropbear/dropbear_rsa_host_key",
+ "-E",
+ "-r",
+ "/tmp/old_ecdsa_key",
+ "-p",
+ "22222",
+ ],
+ ]
+
+ CFWDaemons.patchDropbearDaemon(&daemon)
+
+ let strings = (daemon["ProgramArguments"] as? [Any] ?? []).compactMap { $0 as? String }
+ #expect(!strings.contains("/etc/dropbear/dropbear_rsa_host_key"))
+ #expect(!strings.contains("/tmp/old_ecdsa_key"))
+ #expect(strings == ["dropbear", "-E", "-p", "22222"] + CFWDaemons.dropbearKeyArguments)
+ }
+
+ @Test("an empty argument list is left alone — there is nothing to point at a key")
+ func leavesEmptyArgumentsAlone() {
+ var daemon: PlistDict = ["ProgramArguments": [String]()]
+ CFWDaemons.patchDropbearDaemon(&daemon)
+ #expect((daemon["ProgramArguments"] as? [Any])?.isEmpty == true)
+ }
+
+ @Test("a trailing -r with no path does not read past the end")
+ func toleratesTrailingKeyFlag() {
+ #expect(
+ CFWDaemons.patchedDropbearArguments(["dropbear", "-r"]).compactMap { $0 as? String }
+ == ["dropbear"] + CFWDaemons.dropbearKeyArguments
+ )
+ }
+
+ // MARK: - Cryptex paths
+
+ @Test("Cryptex paths are found in a later identity, not just the first")
+ func cryptexPathsSearchesEveryIdentity() throws {
+ let directory = try CFWDaemonsFixtures.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ // vResearch IPSWs put the Cryptex entries somewhere other than identity 0,
+ // and a real manifest's last identity has neither.
+ let manifest: PlistDict = [
+ "BuildIdentities": [
+ ["Manifest": PlistDict()],
+ ["Manifest": [
+ "Cryptex1,SystemOS": ["Info": ["Path": "043-70113-702.dmg.aea"]],
+ "Cryptex1,AppOS": ["Info": ["Path": "043-69297-784.dmg"]],
+ ] as PlistDict],
+ ],
+ ]
+ let url = directory.appending(path: "BuildManifest.plist")
+ try CFWDaemons.savePlist(manifest, to: url)
+
+ let paths = try CFWDaemons.cryptexPaths(buildManifest: url)
+ #expect(paths.systemOS == "043-70113-702.dmg.aea")
+ #expect(paths.appOS == "043-69297-784.dmg")
+ }
+
+ @Test("an identity carrying only one of the two is not a match")
+ func cryptexPathsNeedsBoth() throws {
+ let directory = try CFWDaemonsFixtures.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ let manifest: PlistDict = [
+ "BuildIdentities": [
+ ["Manifest": ["Cryptex1,SystemOS": ["Info": ["Path": "sys.dmg"]]] as PlistDict],
+ ],
+ ]
+ let url = directory.appending(path: "BuildManifest.plist")
+ try CFWDaemons.savePlist(manifest, to: url)
+
+ #expect(throws: CFWDaemons.DaemonError.self) {
+ try CFWDaemons.cryptexPaths(buildManifest: url)
+ }
+ }
+
+ // MARK: - launchd.plist injection
+
+ @Test("injection creates LaunchDaemons when the target has none")
+ func injectionCreatesLaunchDaemonsDictionary() throws {
+ let directory = try CFWDaemonsFixtures.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ let launchd = directory.appending(path: "launchd.plist")
+ try CFWDaemons.savePlist(["VersionNumber": 1], to: launchd)
+
+ try CFWDaemons.inject(
+ [CFWDaemons.Daemon(name: "vphoned", contents: ["Label": "vphoned"])],
+ into: launchd
+ )
+
+ let result = try CFWDaemons.loadPlist(launchd)
+ let daemons = result["LaunchDaemons"] as? PlistDict
+ #expect(daemons?["/System/Library/LaunchDaemons/vphoned.plist"] != nil)
+ #expect(result["VersionNumber"] as? Int == 1)
+ }
+
+ @Test("injecting twice replaces rather than duplicates, so a re-run is safe")
+ func injectionIsIdempotent() throws {
+ let directory = try CFWDaemonsFixtures.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ let launchd = directory.appending(path: "launchd.plist")
+ try CFWDaemons.savePlist(["LaunchDaemons": PlistDict()], to: launchd)
+
+ let daemon = CFWDaemons.Daemon(name: "bash", contents: ["Label": "bash"])
+ try CFWDaemons.inject([daemon], into: launchd)
+ let first = try CFWDaemonsFixtures.loadPlist(launchd)
+ try CFWDaemons.inject([daemon], into: launchd)
+ let second = try CFWDaemonsFixtures.loadPlist(launchd)
+
+ #expect(PlistSemantics.differences(first, second).isEmpty)
+ #expect((second["LaunchDaemons"] as? PlistDict)?.count == 1)
+ }
+
+ @Test("a daemon absent from the staging directory is reported, not fatal")
+ func missingDaemonsAreReported() throws {
+ let directory = try CFWDaemonsFixtures.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ let staging = directory.appending(path: "LaunchDaemons")
+ try FileManager.default.createDirectory(at: staging, withIntermediateDirectories: true)
+ try CFWDaemons.savePlist(["Label": "bash"], to: staging.appending(path: "bash.plist"))
+
+ let launchd = directory.appending(path: "launchd.plist")
+ try CFWDaemons.savePlist(PlistDict(), to: launchd)
+
+ let staged = try CFWDaemons.injectDaemons(into: launchd, fromDirectory: staging)
+ #expect(staged.injectedNames == ["bash"])
+ #expect(staged.missingSources.count == CFWDaemons.defaultDaemonNames.count - 1)
+ // Scan order, not injected-then-missing: the caller logs one line each,
+ // and those lines have always come out in the order the names are tried.
+ #expect(staged.count == CFWDaemons.defaultDaemonNames.count)
+ if case .present = staged[0] {} else { Issue.record("bash should be first in scan order") }
+ }
+
+ @Test("the directory loader applies the dropbear rewrite on its way through")
+ func directoryLoaderPatchesDropbear() throws {
+ let directory = try CFWDaemonsFixtures.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ let staging = directory.appending(path: "LaunchDaemons")
+ try FileManager.default.createDirectory(at: staging, withIntermediateDirectories: true)
+ try CFWDaemons.savePlist(
+ ["ProgramArguments": ["dropbear", "-R"]],
+ to: staging.appending(path: "dropbear.plist")
+ )
+
+ let staged = try CFWDaemons.loadDaemons(inDirectory: staging, names: ["dropbear"])
+ let arguments = (staged.present[0].contents["ProgramArguments"] as? [Any] ?? [])
+ .compactMap { $0 as? String }
+ #expect(arguments == ["dropbear"] + CFWDaemons.dropbearKeyArguments)
+ }
+
+ @Test("the installed label, not the source filename, is what launchd keys on")
+ func launchdKeyComesFromTheInstalledLabel() {
+ let daemon = CFWDaemons.Daemon(name: "com.vphone.jb-setup", contents: [:])
+ #expect(daemon.launchdKey == "/System/Library/LaunchDaemons/com.vphone.jb-setup.plist")
+ }
+
+ // MARK: - The comparator itself
+ //
+ // The equivalence tests below are only worth their run time if the thing
+ // judging them can fail. These are what say it can.
+
+ @Test("the comparator catches a reordered array")
+ func comparatorCatchesArrayOrder() {
+ let differences = PlistSemantics.differences(
+ ["ProgramArguments": ["-r", "/a", "-r", "/b"]],
+ ["ProgramArguments": ["-r", "/b", "-r", "/a"]]
+ )
+ #expect(differences.count == 2)
+ }
+
+ @Test("the comparator catches true standing in for 1, and a missing key")
+ func comparatorCatchesTypeAndKeySet() {
+ #expect(!PlistSemantics.differences(["RunAtLoad": true], ["RunAtLoad": 1]).isEmpty)
+ #expect(!PlistSemantics.differences(["Umask": 0], ["Umask": 0, "Extra": 1]).isEmpty)
+ #expect(!PlistSemantics.differences(["Version": 1], ["Version": 1.0]).isEmpty)
+ }
+
+ @Test("the comparator catches differing Data bytes of equal length")
+ func comparatorCatchesDataBytes() {
+ #expect(!PlistSemantics.differences(
+ ["Blob": Data([0x01, 0x02])],
+ ["Blob": Data([0x01, 0x03])]
+ ).isEmpty)
+ }
+}
+
+// MARK: - Equivalence against the Python
+
+/// The verification bar for this port: same real input through the Python and
+/// through the Swift, compared semantically.
+///
+/// These run only while `scripts/patchers/` and the venv are still in the tree.
+/// When P1 finishes deleting them the suite disables itself and the unit tests
+/// above are what remains.
+@Suite(
+ "CFW daemon rewrites match the Python they replace",
+ .enabled(if: CFWDaemonsFixtures.pythonReferenceAvailable)
+)
+struct CFWDaemonsPythonEquivalenceTests {
+ @Test("cryptex-paths on a real BuildManifest")
+ func cryptexPathsMatchPython() throws {
+ let output = try CFWDaemonsFixtures.run(CFWDaemonsFixtures.python.path, [
+ CFWDaemonsFixtures.cfwPy.path,
+ "cryptex-paths",
+ CFWDaemonsFixtures.buildManifest.path,
+ ])
+ let lines = output.split(separator: "\n", omittingEmptySubsequences: true).map(String.init)
+ try #require(lines.count == 2)
+
+ let swift = try CFWDaemons.cryptexPaths(buildManifest: CFWDaemonsFixtures.buildManifest)
+ #expect(swift.systemOS == lines[0])
+ #expect(swift.appOS == lines[1])
+ }
+
+ @Test("patch-dropbear-plist on the installer's real dropbear.plist")
+ func dropbearPlistMatchesPython() throws {
+ let directory = try CFWDaemonsFixtures.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ let staging = try CFWDaemonsFixtures.unpackLaunchDaemons(into: directory)
+ let source = staging.appending(path: "dropbear.plist")
+
+ let pythonCopy = try CFWDaemonsFixtures.writableCopy(of: source, in: directory, named: "py.plist")
+ let swiftCopy = try CFWDaemonsFixtures.writableCopy(of: source, in: directory, named: "swift.plist")
+
+ try CFWDaemonsFixtures.run(CFWDaemonsFixtures.python.path, [
+ CFWDaemonsFixtures.cfwPy.path, "patch-dropbear-plist", pythonCopy.path,
+ ])
+ try CFWDaemons.patchDropbearPlist(at: swiftCopy)
+
+ let differences = try PlistSemantics.differences(
+ CFWDaemonsFixtures.loadPlist(pythonCopy),
+ CFWDaemonsFixtures.loadPlist(swiftCopy)
+ )
+ #expect(differences.isEmpty, "\(differences)")
+ }
+
+ @Test("inject-daemons on a real launchd.plist and the real staging directory")
+ func injectDaemonsMatchesPython() throws {
+ let directory = try CFWDaemonsFixtures.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ let staging = try CFWDaemonsFixtures.unpackLaunchDaemons(into: directory)
+ let pythonCopy = try CFWDaemonsFixtures.writableCopy(
+ of: CFWDaemonsFixtures.hostLaunchdPlist, in: directory, named: "py-launchd.plist"
+ )
+ let swiftCopy = try CFWDaemonsFixtures.writableCopy(
+ of: CFWDaemonsFixtures.hostLaunchdPlist, in: directory, named: "swift-launchd.plist"
+ )
+
+ try CFWDaemonsFixtures.run(CFWDaemonsFixtures.python.path, [
+ CFWDaemonsFixtures.cfwPy.path, "inject-daemons", pythonCopy.path, staging.path,
+ ])
+ let staged = try CFWDaemons.injectDaemons(into: swiftCopy, fromDirectory: staging)
+ #expect(staged.injectedNames == ["bash", "dropbear", "trollvnc", "rpcserver_ios"])
+ // vphoned is staged separately by the Swift installer, so the archive's
+ // directory really is missing it — the skip path is exercised for free.
+ #expect(staged.missingSources.count == 1)
+
+ let differences = try PlistSemantics.differences(
+ CFWDaemonsFixtures.loadPlist(pythonCopy),
+ CFWDaemonsFixtures.loadPlist(swiftCopy)
+ )
+ #expect(differences.isEmpty, "\(differences.prefix(10))")
+ }
+
+ /// The inline `plistlib` snippet at `cfw_install_jb.sh:460-469` and
+ /// `cfw_install_exp.sh:702-711`, run verbatim against the same input as the
+ /// Swift single-daemon form. This is what "one implementation, three call
+ /// sites" has to mean: the inline snippet is not a second behaviour.
+ @Test("the installers' inline jb-setup merge is the same merge")
+ func inlineInstallerSnippetMatchesSwift() throws {
+ let directory = try CFWDaemonsFixtures.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ let pythonCopy = try CFWDaemonsFixtures.writableCopy(
+ of: CFWDaemonsFixtures.hostLaunchdPlist, in: directory, named: "py-launchd.plist"
+ )
+ let swiftCopy = try CFWDaemonsFixtures.writableCopy(
+ of: CFWDaemonsFixtures.hostLaunchdPlist, in: directory, named: "swift-launchd.plist"
+ )
+
+ let inlineSnippet = """
+ import plistlib, sys
+ with open(sys.argv[1], 'rb') as f:
+ target = plistlib.load(f)
+ with open(sys.argv[2], 'rb') as f:
+ daemon = plistlib.load(f)
+ target.setdefault('LaunchDaemons', {})\
+ ['/System/Library/LaunchDaemons/com.vphone.jb-setup.plist'] = daemon
+ with open(sys.argv[1], 'wb') as f:
+ plistlib.dump(target, f, sort_keys=False)
+ """
+ try CFWDaemonsFixtures.run(CFWDaemonsFixtures.python.path, [
+ "-c", inlineSnippet, pythonCopy.path, CFWDaemonsFixtures.jbSetupPlist.path,
+ ])
+ try CFWDaemons.injectDaemon(
+ into: swiftCopy,
+ name: "com.vphone.jb-setup",
+ from: CFWDaemonsFixtures.jbSetupPlist
+ )
+
+ let differences = try PlistSemantics.differences(
+ CFWDaemonsFixtures.loadPlist(pythonCopy),
+ CFWDaemonsFixtures.loadPlist(swiftCopy)
+ )
+ #expect(differences.isEmpty, "\(differences.prefix(10))")
+ }
+}
diff --git a/tests/FirmwarePatcherTests/CFWMachOTests.swift b/tests/FirmwarePatcherTests/CFWMachOTests.swift
new file mode 100644
index 00000000..ffcc270c
--- /dev/null
+++ b/tests/FirmwarePatcherTests/CFWMachOTests.swift
@@ -0,0 +1,413 @@
+// CFWMachOTests.swift — Mach-O load-command insertion and code-signature re-attestation.
+//
+// Both modules replace something that still exists in the tree, so both are
+// tested against it rather than against expectations written down by hand:
+//
+// * `CFWInjectDylib` against `.tools/bin/insert_dylib`, byte for byte.
+// * `CFWMachOCodeSignature` against `scripts/patchers/cfw_macho_codesign.py`,
+// byte for byte.
+//
+// Those two comparisons are the migration plan's stated gate (P1.1), and they
+// stop being available when P1.5 deletes the Python and the submodule — the
+// tests that need them are gated on the reference still being present, so they
+// skip instead of failing once it is gone. Everything that can be asserted
+// without a reference is asserted unconditionally, first among them the short
+// tail slot, which is the known regression in independent re-signing.
+
+import CryptoKit
+@testable import FirmwarePatcher
+import Foundation
+import Testing
+
+// MARK: - Fixtures
+
+enum MachOFixture {
+ /// 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>
+
+ /// A real, adhoc-signed, thin arm64 Mach-O with a non-page-aligned
+ /// codeLimit — the shape that produces a short tail slot.
+ static let signedBinary = repositoryRoot.appending(path: ".build/release/vphone-letmein")
+ static let insertDylib = repositoryRoot.appending(path: ".tools/bin/insert_dylib")
+ static let python = repositoryRoot.appending(path: ".venv/bin/python3")
+ static let pythonCodeSign = repositoryRoot.appending(path: "scripts/patchers/cfw_macho_codesign.py")
+
+ static func exists(_ url: URL) -> Bool { FileManager.default.fileExists(atPath: url.path) }
+
+ static var hasSignedBinary: Bool { exists(signedBinary) }
+ static var hasInsertDylib: Bool { exists(insertDylib) }
+ static var hasPythonReference: Bool { exists(python) && exists(pythonCodeSign) }
+ static var hasCodesign: Bool { exists(URL(filePath: "/usr/bin/codesign")) }
+
+ /// A private copy of `signedBinary` that the caller may modify freely.
+ static func scratchCopy(_ name: String) throws -> URL {
+ let directory = URL(filePath: NSTemporaryDirectory())
+ .appending(path: "CFWMachOTests-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+ let destination = directory.appending(path: name)
+ try FileManager.default.copyItem(at: signedBinary, 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))
+ }
+
+ /// Flip one byte, the way a patcher would.
+ static func flipByte(at offset: Int, in url: URL) throws {
+ var data = try Data(contentsOf: url)
+ data[offset] ^= 0xFF
+ try data.write(to: url)
+ }
+
+ /// Independent load-command walk, so the tests do not check the injector
+ /// against the injector's own parser.
+ static func dylibLoadCommands(in data: Data) -> [(command: UInt32, path: String)] {
+ var results: [(UInt32, String)] = []
+ let ncmds = data.loadLE(UInt32.self, at: 16)
+ var offset = 32
+ for _ in 0 ..< ncmds {
+ let cmd = data.loadLE(UInt32.self, at: offset)
+ let cmdsize = Int(data.loadLE(UInt32.self, at: offset + 4))
+ if cmd == 0x0C || cmd == 0x8000_0018 { // LC_LOAD_DYLIB / LC_LOAD_WEAK_DYLIB
+ let nameOffset = offset + Int(data.loadLE(UInt32.self, at: offset + 8))
+ let bytes = data[nameOffset ..< offset + cmdsize].prefix { $0 != 0 }
+ results.append((cmd, String(decoding: bytes, as: UTF8.self)))
+ }
+ offset += cmdsize
+ }
+ return results
+ }
+}
+
+// MARK: - Code Signature
+
+@Suite("Standalone Mach-O code-signature re-attestation")
+struct CFWMachOCodeSignatureTests {
+ // MARK: Tail slot
+
+ /// The regression this module exists to not repeat.
+ ///
+ /// The last code slot covers `codeLimit - slotStart` bytes, not a whole
+ /// page. Hashing a full page there — or anything else — produces a binary
+ /// that TXM kills the first time that page is faulted in, and nothing about
+ /// the file looks wrong until then.
+ @Test(.enabled(if: MachOFixture.hasSignedBinary))
+ func tailSlotHashesOnlyUpToCodeLimit() throws {
+ let data = try Data(contentsOf: MachOFixture.signedBinary)
+ let directory = try #require(CFWMachOCodeSignature.codeDirectories(in: data)?.first)
+
+ let lastSlot = directory.codeSlotCount - 1
+ let range = try #require(directory.slotRange(lastSlot))
+ #expect(range.upperBound == directory.codeLimit)
+ #expect(range.count == directory.codeLimit - lastSlot * directory.pageSize)
+ #expect(range.count < directory.pageSize, "fixture must have a non-page-aligned codeLimit")
+
+ // Re-attest a change inside the tail page and check the hash that lands
+ // in the slot against one computed here from the short range.
+ let file = try MachOFixture.scratchCopy("tail")
+ try MachOFixture.flipByte(at: directory.codeLimit - 1, in: file)
+ let records = try CFWMachOCodeSignature.reattest(
+ fileAt: file,
+ modifiedOffsets: [directory.codeLimit - 1]
+ )
+ let record = try #require(records.first)
+ #expect(records.count == 1)
+ #expect(record.pageIndex == lastSlot)
+ #expect(record.isTailSlot)
+ #expect(record.hashedLength == range.count)
+
+ let patched = try Data(contentsOf: file)
+ let shortHash = Data(SHA256.hash(data: patched[range]))
+ #expect(record.after == shortHash)
+ #expect(
+ patched[record.hashFileOffset ..< record.hashFileOffset + directory.hashSize] == shortHash,
+ "the slot on disk must hold the hash of the short range"
+ )
+
+ // And state the failure mode directly: a full-page hash is a different
+ // value, so this is not an assertion that happens to pass either way.
+ let fullPage = record.pageStart ..< record.pageStart + directory.pageSize
+ if patched.count >= fullPage.upperBound {
+ #expect(Data(SHA256.hash(data: patched[fullPage])) != shortHash)
+ }
+ }
+
+ /// The contrast case: when `codeLimit` is page-aligned there is no short
+ /// tail, and the last slot must cover a whole page. No binary on a build
+ /// machine reliably has a page-aligned codeLimit, so the boundary maths is
+ /// pinned directly.
+ @Test func slotRangesFollowCodeLimitAlignment() {
+ let aligned = CFWCodeDirectory(
+ slotType: 0, offset: 0, length: 0, hashOffset: 0, hashSize: 32,
+ hashType: 2, pageSize: 4096, pageSizeLog2: 12,
+ codeSlotCount: 2, codeLimit: 8192
+ )
+ #expect(aligned.slotRange(0) == 0 ..< 4096)
+ #expect(aligned.slotRange(1) == 4096 ..< 8192)
+ #expect(aligned.slotRange(2) == nil)
+
+ let short = CFWCodeDirectory(
+ slotType: 0, offset: 0, length: 0, hashOffset: 0, hashSize: 32,
+ hashType: 2, pageSize: 4096, pageSizeLog2: 12,
+ codeSlotCount: 2, codeLimit: 5000
+ )
+ #expect(short.slotRange(0) == 0 ..< 4096)
+ #expect(short.slotRange(1) == 4096 ..< 5000)
+ }
+
+ @Test func offsetsPastCodeLimitBelongToNoSlot() {
+ #expect(CFWMachOCodeSignature.pageBounds(fileOffset: 4095, pageSize: 4096, codeLimit: 5000)?.index == 0)
+ #expect(CFWMachOCodeSignature.pageBounds(fileOffset: 4999, pageSize: 4096, codeLimit: 5000)?.end == 5000)
+ #expect(CFWMachOCodeSignature.pageBounds(fileOffset: 5000, pageSize: 4096, codeLimit: 5000) == nil)
+ }
+
+ // MARK: Page size
+
+ /// The page size comes from the CD, never from a constant. The plan records
+ /// 4 KiB for the iOS binaries this pipeline patches, but arm64e binaries on
+ /// the build host use 16 KiB, and a hard-coded 4096 silently hashes the
+ /// wrong ranges on those.
+ @Test(.enabled(if: MachOFixture.hasSignedBinary))
+ func pageSizeComesFromTheCodeDirectory() throws {
+ let data = try Data(contentsOf: MachOFixture.signedBinary)
+ let directory = try #require(CFWMachOCodeSignature.codeDirectories(in: data)?.first)
+ #expect(directory.pageSize == 1 << Int(directory.pageSizeLog2))
+ #expect(directory.hashType == CFWMachOCodeSignature.hashTypeSHA256)
+ #expect(directory.hashSize == SHA256.byteCount)
+ }
+
+ @Test func unsignedDataIsRejected() {
+ var data = Data(repeating: 0, count: 4096)
+ #expect(throws: PatcherError.self) {
+ try CFWMachOCodeSignature.reattest(&data, modifiedOffsets: [0])
+ }
+ }
+
+ @Test func noOffsetsIsANoOp() throws {
+ var data = Data(repeating: 0, count: 16)
+ #expect(try CFWMachOCodeSignature.reattest(&data, modifiedOffsets: []).isEmpty)
+ }
+
+ @Test(.enabled(if: MachOFixture.hasSignedBinary))
+ func unchangedPagesAreNotRewritten() throws {
+ let file = try MachOFixture.scratchCopy("untouched")
+ // Nothing was modified, so every slot already matches and no write happens.
+ let records = try CFWMachOCodeSignature.reattest(fileAt: file, modifiedOffsets: [0, 4096, 8192])
+ #expect(records.isEmpty)
+ #expect(try Data(contentsOf: file) == (try Data(contentsOf: MachOFixture.signedBinary)))
+ }
+
+ // MARK: Multiple code directories
+
+ /// A binary with a legacy SHA-1 alt-CD alongside the SHA-256 one. Only the
+ /// SHA-256 CD is recomputed; the SHA-1 CD is left byte-for-byte alone and
+ /// reported, which is what `unsupportedCodeDirectories(in:)` is for.
+ @Test(.enabled(if: MachOFixture.hasSignedBinary && MachOFixture.hasCodesign))
+ func onlySHA256CodeDirectoriesAreUpdated() throws {
+ let file = try MachOFixture.scratchCopy("dual")
+ let signing = try MachOFixture.run(
+ URL(filePath: "/usr/bin/codesign"),
+ ["-f", "-s", "-", "--digest-algorithm=sha1,sha256", file.path]
+ )
+ try #require(signing.status == 0, "could not build a dual-CD fixture: \(signing.output)")
+
+ let before = try Data(contentsOf: file)
+ let directories = try #require(CFWMachOCodeSignature.codeDirectories(in: before))
+ try #require(directories.count == 2)
+ let legacy = try #require(directories.first { $0.hashType == CFWMachOCodeSignature.hashTypeSHA1 })
+ let modern = try #require(directories.first { $0.hashType == CFWMachOCodeSignature.hashTypeSHA256 })
+ #expect(CFWMachOCodeSignature.unsupportedCodeDirectories(in: before).map(\.offset) == [legacy.offset])
+
+ try MachOFixture.flipByte(at: 16, in: file)
+ let records = try CFWMachOCodeSignature.reattest(fileAt: file, modifiedOffsets: [16])
+ #expect(records.allSatisfy { $0.codeDirectoryOffset == modern.offset })
+
+ let after = try Data(contentsOf: file)
+ let legacyRange = legacy.offset ..< legacy.offset + legacy.length
+ #expect(after[legacyRange] == before[legacyRange], "the SHA-1 CD must be untouched")
+ }
+
+ // MARK: Cross-check against the Python
+
+ /// The plan's P1.1 gate: the Swift and the Python must produce the same
+ /// file, byte for byte, from the same input and the same offsets.
+ @Test(.enabled(if: MachOFixture.hasSignedBinary && MachOFixture.hasPythonReference))
+ func matchesThePythonReattester() throws {
+ let data = try Data(contentsOf: MachOFixture.signedBinary)
+ let directory = try #require(CFWMachOCodeSignature.codeDirectories(in: data)?.first)
+ // First page, a middle page, the short tail page, and one offset past
+ // codeLimit that both implementations must ignore.
+ let offsets = [
+ 16,
+ (directory.codeSlotCount / 2) * directory.pageSize + 7,
+ directory.codeLimit - 1,
+ directory.codeLimit + 8,
+ ]
+
+ let swiftFile = try MachOFixture.scratchCopy("swift")
+ let pythonFile = swiftFile.deletingLastPathComponent().appending(path: "python")
+ try FileManager.default.copyItem(at: swiftFile, to: pythonFile)
+ // Only the covered offsets are actually modified — the one past
+ // codeLimit lands in the signature blob itself, and corrupting that
+ // would be testing the parser's behaviour on garbage rather than the
+ // agreement between the two implementations.
+ for offset in offsets where offset < directory.codeLimit {
+ try MachOFixture.flipByte(at: offset, in: swiftFile)
+ try MachOFixture.flipByte(at: offset, in: pythonFile)
+ }
+
+ let records = try CFWMachOCodeSignature.reattest(fileAt: swiftFile, modifiedOffsets: offsets)
+ #expect(records.contains { $0.isTailSlot }, "the offset set must exercise the tail slot")
+
+ 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 python = Process()
+ python.executableURL = MachOFixture.python
+ python.arguments = ["-c", script, pythonFile.path] + offsets.map(String.init)
+ python.currentDirectoryURL = MachOFixture.repositoryRoot
+ let pipe = Pipe()
+ python.standardOutput = pipe
+ python.standardError = pipe
+ try python.run()
+ let output = pipe.fileHandleForReading.readDataToEndOfFile()
+ python.waitUntilExit()
+ try #require(
+ python.terminationStatus == 0,
+ "reference implementation failed: \(String(decoding: output, as: UTF8.self))"
+ )
+
+ #expect(
+ try Data(contentsOf: swiftFile) == (try Data(contentsOf: pythonFile)),
+ "Swift and Python re-attestation must agree byte for byte"
+ )
+ }
+}
+
+// MARK: - Dylib Injection
+
+@Suite("LC_LOAD_DYLIB injection")
+struct CFWInjectDylibTests {
+ /// What `cfw_install_jb.sh` does to launchd, minus ldid: the weak load of
+ /// `/b` has to appear and the header has to grow to match.
+ @Test(.enabled(if: MachOFixture.hasSignedBinary))
+ func insertsAWeakLoadCommand() throws {
+ let file = try MachOFixture.scratchCopy("weak")
+ let before = try Data(contentsOf: file)
+ let injections = try CFWInjectDylib.inject(dylibPath: "/b", into: file)
+ let injection = try #require(injections.first)
+ #expect(injections.count == 1)
+ #expect(injection.isWeak)
+ #expect(injection.removedCodeSignature)
+ // "/b" is 2 bytes, padded to 8, after the 24-byte dylib_command.
+ #expect(injection.loadCommandSize == 32)
+
+ let after = try Data(contentsOf: file)
+ let loads = MachOFixture.dylibLoadCommands(in: after)
+ #expect(loads.contains { $0.path == "/b" && $0.command == 0x8000_0018 })
+ #expect(!MachOFixture.dylibLoadCommands(in: before).contains { $0.path == "/b" })
+
+ #expect(after.loadLE(UInt32.self, at: 16) == before.loadLE(UInt32.self, at: 16))
+ // One LC_CODE_SIGNATURE out, one LC_LOAD_WEAK_DYLIB in: ncmds is
+ // unchanged and sizeofcmds moves by the difference of the two sizes.
+ let sizeBefore = before.loadLE(UInt32.self, at: 20)
+ let sizeAfter = after.loadLE(UInt32.self, at: 20)
+ #expect(sizeAfter == sizeBefore + 32 - 16)
+ #expect(after.count < before.count, "stripping the signature must shorten the file")
+ }
+
+ /// The other policy: keep the signature and re-hash what the insertion
+ /// touched, so the binary stays verifiable with no external signer. This is
+ /// the one path that exercises both halves of this work together.
+ @Test(.enabled(if: MachOFixture.hasSignedBinary))
+ func keepingTheSignatureRehashesTheHeaderPage() throws {
+ let file = try MachOFixture.scratchCopy("keep")
+ let before = try Data(contentsOf: file)
+ let injection = try #require(try CFWInjectDylib.inject(
+ dylibPath: "/b",
+ into: file,
+ policy: .keepAndReattest
+ ).first)
+ #expect(!injection.removedCodeSignature)
+ #expect(injection.rehashedSlots.map(\.pageIndex) == [0])
+
+ let after = try Data(contentsOf: file)
+ #expect(after.count == before.count, "keeping the signature must not resize the file")
+ #expect(MachOFixture.dylibLoadCommands(in: after).contains { $0.path == "/b" })
+
+ let directory = try #require(CFWMachOCodeSignature.codeDirectories(in: after)?.first)
+ let range = try #require(directory.slotRange(0))
+ let slot = directory.slotHashOffset(0)
+ #expect(after[slot ..< slot + directory.hashSize] == Data(SHA256.hash(data: after[range])))
+ }
+
+ /// `insert_dylib --all-yes` answers "yes" to "there is not enough empty
+ /// space" and writes the command over the first section. Refusing is the
+ /// deliberate difference; this pins it.
+ @Test(.enabled(if: MachOFixture.hasSignedBinary))
+ func refusesToOverwriteOccupiedPadding() throws {
+ let file = try MachOFixture.scratchCopy("occupied")
+ var data = try Data(contentsOf: file)
+ let sizeofcmds = Int(data.loadLE(UInt32.self, at: 20))
+ data[32 + sizeofcmds] = 0xFF // first byte past the load commands
+ try data.write(to: file)
+
+ #expect(throws: PatcherError.self) {
+ try CFWInjectDylib.inject(dylibPath: "/b", into: file)
+ }
+ // …and the opt-out still works, for a caller that knows better.
+ #expect(throws: Never.self) {
+ try CFWInjectDylib.inject(dylibPath: "/b", into: file, allowNonEmptyPadding: true)
+ }
+ }
+
+ @Test func rejectsWhatItCannotHandle() {
+ var empty = Data([0xCA, 0xFE, 0xBA, 0xBF, 0, 0, 0, 1])
+ #expect(throws: PatcherError.self) {
+ try CFWInjectDylib.inject(dylibPath: "/b", into: &empty)
+ }
+ var garbage = Data(repeating: 0xAB, count: 512)
+ #expect(throws: PatcherError.self) {
+ try CFWInjectDylib.inject(dylibPath: "/b", into: &garbage)
+ }
+ }
+
+ /// The migration gate for this half: identical output to the C tool it
+ /// replaces, on the exact command line the CFW scripts use.
+ @Test(.enabled(if: MachOFixture.hasSignedBinary && MachOFixture.hasInsertDylib))
+ func matchesInsertDylib() throws {
+ let swiftFile = try MachOFixture.scratchCopy("swift")
+ let referenceFile = swiftFile.deletingLastPathComponent().appending(path: "reference")
+ try FileManager.default.copyItem(at: MachOFixture.signedBinary, to: referenceFile)
+
+ try CFWInjectDylib.inject(dylibPath: "/b", into: swiftFile)
+ let reference = try MachOFixture.run(
+ MachOFixture.insertDylib,
+ ["--weak", "--inplace", "--all-yes", "/b", referenceFile.path]
+ )
+ try #require(reference.status == 0, "insert_dylib failed: \(reference.output)")
+
+ #expect(
+ try Data(contentsOf: swiftFile) == (try Data(contentsOf: referenceFile)),
+ "Swift injection must match insert_dylib byte for byte"
+ )
+ }
+}
diff --git a/tests/FirmwarePatcherTests/CFWPlistPatchTests.swift b/tests/FirmwarePatcherTests/CFWPlistPatchTests.swift
new file mode 100644
index 00000000..6bb4620e
--- /dev/null
+++ b/tests/FirmwarePatcherTests/CFWPlistPatchTests.swift
@@ -0,0 +1,655 @@
+// CFWPlistPatchTests.swift — the three P1.4 CFW patchers, against the Python
+// they replace.
+//
+// Unit tests cover the behaviour each patcher is supposed to have. The
+// equivalence tests are the ones that matter: they run
+// `scripts/patchers/<name>.py` and the Swift over the same real input and
+// compare the outputs — semantically for the two plist patchers, byte for
+// byte for the device tree.
+//
+// Real input, never a hand-made stand-in:
+// - the host's own /System/Library/CoreServices/SystemVersion.plist
+// - a real entitlements plist dumped from a signed system binary
+// - DeviceTree.vphone600ap.im4p, pulled out of the cloudOS IPSW
+//
+// Every equivalence test is gated on its input and on the project venv
+// existing, and skips rather than fails when they do not — but a skip is not
+// a pass, and the migration notes record which ones actually ran.
+
+@testable import FirmwarePatcher
+import Foundation
+import Img4tool
+import Testing
+
+// MARK: - Fixtures and the Python reference
+
+enum CFWPatchFixtures {
+ /// tests/FirmwarePatcherTests/<this file> → repo root.
+ static let repoRoot = URL(filePath: #filePath)
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+
+ static let python = repoRoot.appending(path: ".venv/bin/python3")
+ static let patchers = repoRoot.appending(path: "scripts/patchers")
+
+ /// A real Apple SystemVersion.plist, in XML, with a real ProductBuildVersion.
+ static let systemVersionPlist = URL(filePath: "/System/Library/CoreServices/SystemVersion.plist")
+
+ /// Signed host binaries to take a real entitlements plist from. Safari
+ /// already carries a non-empty mach-lookup global-name exception array,
+ /// so it exercises the merge; loginwindow does not carry the key at all,
+ /// so it exercises the insert. Both paths matter — Campo can be either.
+ static let entitlementsDonors = [
+ URL(filePath: "/Applications/Safari.app"),
+ URL(filePath: "/System/Library/CoreServices/loginwindow.app/Contents/MacOS/loginwindow"),
+ ]
+
+ static var availableEntitlementsDonors: [URL] {
+ entitlementsDonors.filter { FileManager.default.fileExists(atPath: $0.path) }
+ }
+
+ static func pythonPatcherExists(_ name: String) -> Bool {
+ FileManager.default.fileExists(atPath: patchers.appending(path: name).path)
+ }
+
+ static var venvAvailable: Bool {
+ FileManager.default.isExecutableFile(atPath: python.path)
+ }
+
+ static func canRun(_ patcher: String) -> Bool {
+ venvAvailable && pythonPatcherExists(patcher)
+ }
+
+ static var systemVersionAvailable: Bool {
+ FileManager.default.isReadableFile(atPath: systemVersionPlist.path)
+ }
+
+ static var entitlementsDonorAvailable: Bool {
+ !availableEntitlementsDonors.isEmpty
+ }
+
+ /// Any IPSW in `ipsws/` that carries the vphone600 device tree.
+ static let deviceTreeEntry = "Firmware/all_flash/DeviceTree.vphone600ap.im4p"
+
+ static func ipswWithDeviceTree() -> URL? {
+ let ipswDirectory = repoRoot.appending(path: "ipsws")
+ let candidates = (try? FileManager.default.contentsOfDirectory(
+ at: ipswDirectory,
+ includingPropertiesForKeys: nil
+ )) ?? []
+ for candidate in candidates where candidate.pathExtension == "ipsw" {
+ let listing = (try? run("/usr/bin/unzip", ["-l", candidate.path, deviceTreeEntry]))?.output ?? ""
+ if listing.contains(deviceTreeEntry) { return candidate }
+ }
+ return nil
+ }
+
+ static var deviceTreeAvailable: Bool { ipswWithDeviceTree() != nil }
+
+ /// Extract the device tree IM4P into `directory` and return its path.
+ static func extractDeviceTree(into directory: URL) throws -> URL {
+ guard let ipsw = ipswWithDeviceTree() else {
+ throw CFWTestError.missingFixture("no IPSW in ipsws/ contains \(deviceTreeEntry)")
+ }
+ let result = try run("/usr/bin/unzip", ["-o", "-j", ipsw.path, deviceTreeEntry, "-d", directory.path])
+ guard result.status == 0 else {
+ throw CFWTestError.commandFailed("unzip exited \(result.status): \(result.output)")
+ }
+ return directory.appending(path: "DeviceTree.vphone600ap.im4p")
+ }
+
+ /// Dump a real entitlements plist the way `cfw_install_jb.sh` does with
+ /// `ldid -e` — `codesign` is the host-side equivalent and needs no
+ /// Homebrew.
+ static func dumpEntitlements(of binary: URL, to url: URL) throws {
+ let result = try run("/usr/bin/codesign", ["-d", "--entitlements", ":-", "--xml", binary.path])
+ guard result.status == 0, !result.outputData.isEmpty else {
+ throw CFWTestError.commandFailed("codesign exited \(result.status): \(result.combined)")
+ }
+ try result.outputData.write(to: url)
+ }
+
+ // MARK: Process plumbing
+
+ /// stdout and stderr stay separate: `codesign -d --entitlements :-` puts
+ /// the plist on stdout and its banner on stderr, and merging the two
+ /// produces a file that is not a plist at all.
+ struct CommandResult {
+ let status: Int32
+ let outputData: Data
+ let errorData: Data
+ var output: String { String(decoding: outputData, as: UTF8.self) }
+ var combined: String { output + String(decoding: errorData, as: UTF8.self) }
+ }
+
+ @discardableResult
+ static func run(_ launchPath: String, _ arguments: [String]) throws -> CommandResult {
+ let process = Process()
+ process.executableURL = URL(filePath: launchPath)
+ process.arguments = arguments
+ let out = Pipe(), err = Pipe()
+ process.standardOutput = out
+ process.standardError = err
+ try process.run()
+ let outputData = out.fileHandleForReading.readDataToEndOfFile()
+ let errorData = err.fileHandleForReading.readDataToEndOfFile()
+ process.waitUntilExit()
+ return CommandResult(
+ status: process.terminationStatus,
+ outputData: outputData,
+ errorData: errorData
+ )
+ }
+
+ /// Copy a fixture's *contents*, not its file: the system plists this
+ /// reads are mode 0444, and a `copyItem` carries that through and makes
+ /// the copy unpatchable.
+ static func copyContents(of source: URL, to destination: URL) throws {
+ try Data(contentsOf: source).write(to: destination)
+ }
+
+ @discardableResult
+ static func runPython(_ patcher: String, _ arguments: [String]) throws -> CommandResult {
+ try run(python.path, [patchers.appending(path: patcher).path] + arguments)
+ }
+
+ static func makeTemporaryDirectory() throws -> URL {
+ let url = FileManager.default.temporaryDirectory
+ .appending(path: "cfw-patch-tests-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+ return url
+ }
+}
+
+enum CFWTestError: Error, CustomStringConvertible {
+ case missingFixture(String)
+ case commandFailed(String)
+
+ var description: String {
+ switch self {
+ case let .missingFixture(message): "missing fixture: \(message)"
+ case let .commandFailed(message): "command failed: \(message)"
+ }
+ }
+}
+
+// MARK: - Semantic plist comparison
+//
+// Migration plan §7.1: same key set, same array order, same value types,
+// same Data bytes. Serialized key order and the XML-vs-binary encoding are
+// deliberately not compared — neither is part of what a plist means.
+
+enum PlistComparison {
+ static func tag(_ value: Any) -> String {
+ if CFGetTypeID(value as CFTypeRef) == CFBooleanGetTypeID() { return "bool" }
+ switch value {
+ case is [String: Any]: return "dict"
+ case is [Any]: return "array"
+ case is String: return "string"
+ case is Data: return "data"
+ case is Date: return "date"
+ case let number as NSNumber: return CFNumberIsFloatType(number) ? "real" : "integer"
+ default: return "unknown(\(type(of: value)))"
+ }
+ }
+
+ /// Returns nil when the two are equivalent, or the path where they differ.
+ static func difference(_ lhs: Any, _ rhs: Any, path: String = "<root>") -> String? {
+ guard tag(lhs) == tag(rhs) else {
+ return "\(path): type \(tag(lhs)) vs \(tag(rhs))"
+ }
+ switch tag(lhs) {
+ case "dict":
+ guard let left = lhs as? [String: Any], let right = rhs as? [String: Any] else {
+ return "\(path): not a dictionary"
+ }
+ let leftKeys = Set(left.keys), rightKeys = Set(right.keys)
+ guard leftKeys == rightKeys else {
+ return "\(path): key set differs, only-left=\(leftKeys.subtracting(rightKeys).sorted()) only-right=\(rightKeys.subtracting(leftKeys).sorted())"
+ }
+ for key in leftKeys.sorted() {
+ if let found = difference(left[key]!, right[key]!, path: "\(path).\(key)") {
+ return found
+ }
+ }
+ return nil
+ case "array":
+ guard let left = lhs as? [Any], let right = rhs as? [Any] else {
+ return "\(path): not an array"
+ }
+ guard left.count == right.count else {
+ return "\(path): count \(left.count) vs \(right.count)"
+ }
+ for index in left.indices {
+ if let found = difference(left[index], right[index], path: "\(path)[\(index)]") {
+ return found
+ }
+ }
+ return nil
+ case "data":
+ guard let left = lhs as? Data, let right = rhs as? Data, left == right else {
+ return "\(path): Data bytes differ"
+ }
+ return nil
+ case "string":
+ guard let left = lhs as? String, let right = rhs as? String, left == right else {
+ return "\(path): '\(lhs)' vs '\(rhs)'"
+ }
+ return nil
+ default:
+ guard let left = lhs as? NSObject, let right = rhs as? NSObject, left.isEqual(right) else {
+ return "\(path): \(lhs) vs \(rhs)"
+ }
+ return nil
+ }
+ }
+
+ static func load(_ url: URL) throws -> Any {
+ try PropertyListSerialization.propertyList(
+ from: Data(contentsOf: url),
+ options: [],
+ format: nil
+ )
+ }
+}
+
+// MARK: - CFWBuildVersion
+
+struct CFWBuildVersionTests {
+ @Test func detectsXMLAndBinaryFormats() {
+ #expect(CFWBuildVersion.detectFormat(Data("<?xml version=\"1.0\"?>".utf8)) == .xml)
+ #expect(CFWBuildVersion.detectFormat(Data("\n\t <plist>".utf8)) == .xml)
+ #expect(CFWBuildVersion.detectFormat(Data("bplist00".utf8)) == .binary)
+ #expect(CFWBuildVersion.detectFormat(Data()) == .binary)
+ }
+
+ @Test func rewritesTheKeyAndLeavesEverythingElseAlone() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let url = directory.appending(path: "SystemVersion.plist")
+ let original: [String: Any] = [
+ "ProductBuildVersion": "23B85",
+ "ProductVersion": "26.1",
+ "ProductName": "iPhone OS",
+ ]
+ try PropertyListSerialization
+ .data(fromPropertyList: original, format: .xml, options: 0)
+ .write(to: url)
+
+ let outcome = try CFWBuildVersion.patch(at: url, to: "23F77", verbose: false)
+ #expect(outcome == .rewritten(from: "23B85", to: "23F77"))
+
+ let patched = try PlistComparison.load(url) as? [String: Any]
+ #expect(patched?["ProductBuildVersion"] as? String == "23F77")
+ #expect(patched?["ProductVersion"] as? String == "26.1")
+ #expect(patched?["ProductName"] as? String == "iPhone OS")
+ }
+
+ @Test func isIdempotentAndHonoursDryRun() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let url = directory.appending(path: "SystemVersion.plist")
+ try PropertyListSerialization
+ .data(fromPropertyList: ["ProductBuildVersion": "23F77"], format: .binary, options: 0)
+ .write(to: url)
+
+ let before = try Data(contentsOf: url)
+ #expect(try CFWBuildVersion.patch(at: url, to: "23F77", verbose: false) == .alreadyTarget("23F77"))
+ #expect(try Data(contentsOf: url) == before)
+
+ let dry = try CFWBuildVersion.patch(at: url, to: "24A100", dryRun: true, verbose: false)
+ #expect(dry == .dryRun(from: "23F77", to: "24A100"))
+ #expect(try Data(contentsOf: url) == before)
+ }
+
+ @Test func refusesAPlistWithoutTheKey() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let url = directory.appending(path: "SystemVersion.plist")
+ try PropertyListSerialization
+ .data(fromPropertyList: ["ProductVersion": "26.1"], format: .xml, options: 0)
+ .write(to: url)
+ #expect(throws: PatcherError.self) {
+ try CFWBuildVersion.patch(at: url, to: "23F77", verbose: false)
+ }
+ }
+
+ @Test func refusesANonDictionaryRoot() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let url = directory.appending(path: "root-array.plist")
+ try PropertyListSerialization
+ .data(fromPropertyList: ["a", "b"], format: .xml, options: 0)
+ .write(to: url)
+ #expect(throws: PatcherError.self) {
+ try CFWBuildVersion.patch(at: url, to: "23F77", verbose: false)
+ }
+ }
+
+ @Test(.enabled(if: CFWPatchFixtures.canRun("cfw_patch_build_version.py")
+ && CFWPatchFixtures.systemVersionAvailable))
+ func matchesPythonOnARealSystemVersionPlist() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ // Both plist encodings of the same real file: the rootfs copy is XML,
+ // the Cryptex copy on a device can be binary.
+ for format in ["xml1", "binary1"] {
+ let pythonOutput = directory.appending(path: "python-\(format).plist")
+ let swiftOutput = directory.appending(path: "swift-\(format).plist")
+ for destination in [pythonOutput, swiftOutput] {
+ try CFWPatchFixtures.copyContents(of: CFWPatchFixtures.systemVersionPlist, to: destination)
+ try CFWPatchFixtures.run("/usr/bin/plutil", ["-convert", format, destination.path])
+ }
+
+ let python = try CFWPatchFixtures.runPython(
+ "cfw_patch_build_version.py",
+ [pythonOutput.path, "23F77"]
+ )
+ #expect(python.status == 0, "python: \(python.combined)")
+ try CFWBuildVersion.patch(at: swiftOutput, to: "23F77", verbose: false)
+
+ let difference = PlistComparison.difference(
+ try PlistComparison.load(pythonOutput),
+ try PlistComparison.load(swiftOutput)
+ )
+ #expect(difference == nil, "\(format): \(difference ?? "")")
+
+ // The format the file went in as is the format it comes back as.
+ let swiftBytes = try Data(contentsOf: swiftOutput)
+ #expect(CFWBuildVersion.detectFormat(swiftBytes) == (format == "xml1" ? .xml : .binary))
+ }
+ }
+}
+
+// MARK: - CFWMachLookupExceptions
+
+struct CFWMachLookupExceptionTests {
+ private func write(_ plist: [String: Any], to url: URL) throws {
+ try PropertyListSerialization
+ .data(fromPropertyList: plist, format: .xml, options: 0)
+ .write(to: url)
+ }
+
+ @Test func addsEveryServiceWhenTheKeyIsAbsent() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let url = directory.appending(path: "Campo.entitlements")
+ try write(["platform-application": true], to: url)
+
+ let outcome = try CFWMachLookupExceptions.merge(at: url, verbose: false)
+ #expect(outcome.added == CFWMachLookupExceptions.services.count)
+ #expect(outcome.total == CFWMachLookupExceptions.services.count)
+
+ let patched = try PlistComparison.load(url) as? [String: Any]
+ #expect(patched?[CFWMachLookupExceptions.exceptionKey] as? [String]
+ == CFWMachLookupExceptions.services)
+ #expect(patched?["platform-application"] as? Bool == true)
+ }
+
+ @Test func keepsExistingEntriesFirstAndDoesNotDuplicate() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let url = directory.appending(path: "Campo.entitlements")
+ let preexisting = ["com.apple.some.other.service", "com.apple.CARenderServer"]
+ try write([CFWMachLookupExceptions.exceptionKey: preexisting], to: url)
+
+ let outcome = try CFWMachLookupExceptions.merge(at: url, verbose: false)
+ #expect(outcome.added == CFWMachLookupExceptions.services.count - 1)
+
+ let patched = try PlistComparison.load(url) as? [String: Any]
+ let merged = patched?[CFWMachLookupExceptions.exceptionKey] as? [String] ?? []
+ #expect(Array(merged.prefix(2)) == preexisting)
+ #expect(merged.filter { $0 == "com.apple.CARenderServer" }.count == 1)
+ #expect(Set(merged).isSuperset(of: CFWMachLookupExceptions.services))
+ }
+
+ @Test func isIdempotent() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let url = directory.appending(path: "Campo.entitlements")
+ try write(["get-task-allow": true], to: url)
+
+ try CFWMachLookupExceptions.merge(at: url, verbose: false)
+ let once = try Data(contentsOf: url)
+ let second = try CFWMachLookupExceptions.merge(at: url, verbose: false)
+ #expect(second.added == 0)
+ #expect(try Data(contentsOf: url) == once)
+ }
+
+ @Test func refusesAnExceptionKeyThatIsNotAnArray() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let url = directory.appending(path: "Campo.entitlements")
+ try write([CFWMachLookupExceptions.exceptionKey: "com.apple.CARenderServer"], to: url)
+ #expect(throws: PatcherError.self) {
+ try CFWMachLookupExceptions.merge(at: url, verbose: false)
+ }
+ }
+
+ @Test(.enabled(if: CFWPatchFixtures.canRun("campo_mach_lookup_exceptions.py")
+ && CFWPatchFixtures.entitlementsDonorAvailable))
+ func matchesPythonOnRealEntitlements() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ for donor in CFWPatchFixtures.availableEntitlementsDonors {
+ let name = donor.lastPathComponent
+ let pythonOutput = directory.appending(path: "python-\(name).entitlements")
+ let swiftOutput = directory.appending(path: "swift-\(name).entitlements")
+ try CFWPatchFixtures.dumpEntitlements(of: donor, to: pythonOutput)
+ try CFWPatchFixtures.copyContents(of: pythonOutput, to: swiftOutput)
+
+ let python = try CFWPatchFixtures.runPython(
+ "campo_mach_lookup_exceptions.py",
+ [pythonOutput.path]
+ )
+ #expect(python.status == 0, "python: \(python.combined)")
+ let outcome = try CFWMachLookupExceptions.merge(at: swiftOutput, verbose: false)
+ #expect(python.output.contains("count: \(outcome.total) (+\(outcome.added) added)"))
+
+ let difference = PlistComparison.difference(
+ try PlistComparison.load(pythonOutput),
+ try PlistComparison.load(swiftOutput)
+ )
+ #expect(difference == nil, "\(name): \(difference ?? "")")
+ }
+ }
+}
+
+// MARK: - Just enough DER to build and take apart a test IMG4
+
+enum DERTestEncoder {
+ static func length(_ count: Int) -> Data {
+ if count < 0x80 { return Data([UInt8(count)]) }
+ var bytes: [UInt8] = []
+ var remaining = count
+ while remaining > 0 {
+ bytes.append(UInt8(remaining & 0xFF))
+ remaining >>= 8
+ }
+ bytes.reverse()
+ return Data([0x80 | UInt8(bytes.count)] + bytes)
+ }
+
+ static func element(tag: UInt8, value: Data) -> Data {
+ var out = Data([tag])
+ out.append(length(value.count))
+ out.append(value)
+ return out
+ }
+
+ static func sequence(_ elements: [Data]) -> Data {
+ element(tag: 0x30, value: elements.reduce(into: Data()) { $0.append($1) })
+ }
+
+ static func ia5String(_ text: String) -> Data {
+ element(tag: 0x16, value: Data(text.utf8))
+ }
+
+ /// Split a top-level SEQUENCE into its children's raw bytes.
+ static func children(of data: Data) throws -> [Data] {
+ var offset = 0
+ func readHeader() throws -> (tag: UInt8, valueStart: Int, valueCount: Int) {
+ guard offset + 2 <= data.count else { throw CFWTestError.commandFailed("short DER") }
+ let tag = data[offset]
+ let first = data[offset + 1]
+ var cursor = offset + 2
+ var count = Int(first)
+ if first & 0x80 != 0 {
+ let byteCount = Int(first & 0x7F)
+ count = 0
+ for index in 0 ..< byteCount { count = (count << 8) | Int(data[cursor + index]) }
+ cursor += byteCount
+ }
+ return (tag, cursor, count)
+ }
+ let outer = try readHeader()
+ var result: [Data] = []
+ offset = outer.valueStart
+ let end = outer.valueStart + outer.valueCount
+ while offset < end {
+ let child = try readHeader()
+ result.append(data[offset ..< (child.valueStart + child.valueCount)])
+ offset = child.valueStart + child.valueCount
+ }
+ return result
+ }
+}
+
+// MARK: - CFWPostRestoreDeviceTree
+
+struct CFWPostRestoreDeviceTreeTests {
+ @Test(.enabled(if: CFWPatchFixtures.deviceTreeAvailable))
+ func parseAndSerializeRoundTripsARealDeviceTree() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let im4p = try CFWPatchFixtures.extractDeviceTree(into: directory)
+ let blob = try IM4P(Data(contentsOf: im4p)).payload()
+
+ // Patching to the values already there is a no-op, which is the only
+ // way to see the parse/serialize pair on its own.
+ let (patched, changes) = try CFWPostRestoreDeviceTree.patchedDeviceTree(blob)
+ #expect(changes.count == 3)
+ #expect(patched.count == blob.count)
+
+ let (again, noChanges) = try CFWPostRestoreDeviceTree.patchedDeviceTree(patched)
+ #expect(noChanges.isEmpty)
+ #expect(again == patched)
+ }
+
+ @Test(.enabled(if: CFWPatchFixtures.deviceTreeAvailable))
+ func rewritesExactlyTheThreeRestoreFatalProperties() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let im4p = try CFWPatchFixtures.extractDeviceTree(into: directory)
+ let blob = try IM4P(Data(contentsOf: im4p)).payload()
+ let (patched, changes) = try CFWPostRestoreDeviceTree.patchedDeviceTree(blob)
+
+ #expect(changes.map(\.property) == ["model", "target-type", "compatible"])
+ #expect(changes[0].before == "iPhone99,11")
+ #expect(changes[0].after == "iPhone17,3")
+ #expect(changes[1].before == "VPHONE600")
+ #expect(changes[1].after == "D47")
+ #expect(changes[2].before == "[VPHONE600AP, iPhone99,11, AppleVirtualPlatformARM]")
+
+ // Slot lengths are preserved, so every difference is inside one of the
+ // three property values — 12 + 10 + 48 bytes at most.
+ let differing = zip(blob, patched).filter { $0 != $1 }.count
+ #expect(differing > 0 && differing <= 12 + 10 + 48)
+
+ #expect(patched.range(of: Data("D47AP\0VPHONE600AP\0AppleVirtualPlatformARM\0".utf8)) != nil)
+ #expect(patched.range(of: Data("iPhone17,3\0".utf8)) != nil)
+ }
+
+ @Test(.enabled(if: CFWPatchFixtures.canRun("cfw_patch_post_restore_dt.py")
+ && CFWPatchFixtures.deviceTreeAvailable))
+ func matchesPythonByteForByteOnARealDeviceTree() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let source = try CFWPatchFixtures.extractDeviceTree(into: directory)
+
+ let pythonOutput = directory.appending(path: "python.im4p")
+ let swiftOutput = directory.appending(path: "swift.im4p")
+ try FileManager.default.copyItem(at: source, to: pythonOutput)
+ try FileManager.default.copyItem(at: source, to: swiftOutput)
+
+ let python = try CFWPatchFixtures.runPython("cfw_patch_post_restore_dt.py", [pythonOutput.path])
+ #expect(python.status == 0, "python: \(python.combined)")
+ let outcome = try CFWPostRestoreDeviceTree.patch(at: swiftOutput, verbose: false)
+ #expect(outcome.wrote)
+ #expect(outcome.changes.count == 3)
+
+ let pythonBytes = try Data(contentsOf: pythonOutput)
+ let swiftBytes = try Data(contentsOf: swiftOutput)
+ #expect(pythonBytes == swiftBytes, "IM4P differs: \(pythonBytes.count)B vs \(swiftBytes.count)B")
+
+ // And the re-run is a no-op on both sides.
+ let pythonRerun = try CFWPatchFixtures.runPython("cfw_patch_post_restore_dt.py", [pythonOutput.path])
+ #expect(pythonRerun.output.contains("no change"))
+ let swiftRerun = try CFWPostRestoreDeviceTree.patch(at: swiftOutput, verbose: false)
+ #expect(!swiftRerun.wrote)
+ #expect(try Data(contentsOf: swiftOutput) == swiftBytes)
+ }
+
+ /// The IMG4 path, as far as it can be checked here.
+ ///
+ /// The real target is `/usr/standalone/firmware/devicetree.img4` on a
+ /// restored rootfs, which is a signed IMG4 — and no signed IM4M is
+ /// obtainable offline, so there is no Python-vs-Swift byte comparison for
+ /// this shape. What is checkable without one is the part that is actually
+ /// new: the IM4P inside must come out identical to the bare-IM4P run, and
+ /// every element around it must come back byte for byte, because the
+ /// manifest and restore info are carried, never re-encoded.
+ @Test(.enabled(if: CFWPatchFixtures.deviceTreeAvailable))
+ func preservesEverythingAroundTheIM4PInAnIMG4() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let source = try CFWPatchFixtures.extractDeviceTree(into: directory)
+ let im4pBytes = try Data(contentsOf: source)
+
+ // Stand-ins for the manifest and restore info: this test never looks
+ // inside them, and neither does the patcher.
+ let manifest = Data((0 ..< 96).map { UInt8(truncatingIfNeeded: $0 * 7 + 3) })
+ let restoreInfo = Data((0 ..< 32).map { UInt8(truncatingIfNeeded: $0 * 11 + 5) })
+ let img4 = DERTestEncoder.sequence([
+ DERTestEncoder.ia5String("IMG4"),
+ im4pBytes,
+ DERTestEncoder.element(tag: 0xA0, value: manifest),
+ DERTestEncoder.element(tag: 0xA1, value: restoreInfo),
+ ])
+ let img4URL = directory.appending(path: "devicetree.img4")
+ try img4.write(to: img4URL)
+
+ let outcome = try CFWPostRestoreDeviceTree.patch(at: img4URL, verbose: false)
+ #expect(outcome.changes.count == 3)
+ #expect(outcome.wrote)
+
+ // The bare-IM4P run, for comparison.
+ let bareURL = directory.appending(path: "bare.im4p")
+ try im4pBytes.write(to: bareURL)
+ try CFWPostRestoreDeviceTree.patch(at: bareURL, verbose: false)
+ let patchedIM4P = try Data(contentsOf: bareURL)
+
+ let children = try DERTestEncoder.children(of: Data(contentsOf: img4URL))
+ #expect(children.count == 4)
+ #expect(children[0] == DERTestEncoder.ia5String("IMG4"))
+ #expect(children[1] == patchedIM4P)
+ #expect(children[2] == DERTestEncoder.element(tag: 0xA0, value: manifest))
+ #expect(children[3] == DERTestEncoder.element(tag: 0xA1, value: restoreInfo))
+ }
+
+ @Test(.enabled(if: CFWPatchFixtures.deviceTreeAvailable))
+ func refusesAPayloadThatIsNotADeviceTree() throws {
+ let directory = try CFWPatchFixtures.makeTemporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let url = directory.appending(path: "not-a-dt.im4p")
+ try IM4P(fourcc: "krnl", description: "test", payload: Data(repeating: 0, count: 64))
+ .data
+ .write(to: url)
+ #expect(throws: PatcherError.self) {
+ try CFWPostRestoreDeviceTree.patch(at: url, verbose: false)
+ }
+ }
+}
diff --git a/tests/FirmwarePatcherTests/DSCFoundationTests.swift b/tests/FirmwarePatcherTests/DSCFoundationTests.swift
new file mode 100644
index 00000000..fbe75ac0
--- /dev/null
+++ b/tests/FirmwarePatcherTests/DSCFoundationTests.swift
@@ -0,0 +1,1284 @@
+// DSCFoundationTests.swift — Cross-checks for the DSC foundation layer.
+//
+// `codesign -v` does not apply to a dyld shared cache chunk, so the only
+// independent reference for any of this is the Python in `scripts/patchers/`.
+// Every test here therefore runs the Python on the same bytes and compares,
+// rather than asserting against a number this repo wrote down once.
+//
+// The tests need the real cache. Point `VPHONE_DSC_PRISTINE` at a directory of
+// `dyld_shared_cache_arm64e*` chunks, or leave the default
+// `ipsws/ref_extract/dsc_pristine` in place.
+//
+// Without it they FAIL. They used to open with `guard let pristine = … else
+// { return }`, and a bare `return` is reported by Swift Testing as a pass — so
+// "13 tests passed" was equally compatible with "13 tests did nothing", on any
+// machine that had not extracted the 5.3 GB cache. A machine that genuinely
+// cannot carry the fixture sets `VPHONE_DSC_FIXTURE_OPTIONAL=1`, which turns
+// the failure into a visible *skip*. There is no configuration in which a green
+// run means the cache was absent.
+//
+// Nothing here writes to the pristine directory. The re-signing tests clone it
+// — `clonefile`, so instant and free on APFS — and work in the copy.
+
+@testable import FirmwarePatcher
+import Foundation
+import Testing
+
+// MARK: - Fixture discovery
+
+private enum DSCFixture {
+ static let repoRoot = URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+ .deletingLastPathComponent()
+
+ /// The read-only reference cache.
+ static var pristine: URL? {
+ let url = ProcessInfo.processInfo.environment["VPHONE_DSC_PRISTINE"]
+ .map { URL(fileURLWithPath: $0) }
+ ?? repoRoot.appendingPathComponent("ipsws/ref_extract/dsc_pristine")
+ let main = url.appendingPathComponent("dyld_shared_cache_arm64e")
+ return FileManager.default.fileExists(atPath: main.path) ? url : nil
+ }
+
+ /// Opt-out for a machine that cannot carry the fixture. Set it and the
+ /// suites report as skipped; leave it unset and a missing cache is a
+ /// failure, which is the only reading of "green" this layer can afford.
+ static var isOptional: Bool {
+ ProcessInfo.processInfo.environment["VPHONE_DSC_FIXTURE_OPTIONAL"] == "1"
+ }
+
+ /// The suites run unless the cache is absent *and* the caller opted out.
+ static var runs: Bool { pristine != nil || !isOptional }
+
+ static let missing: Comment = """
+ the real 24A435 arm64e shared cache is required — put it at \
+ ipsws/ref_extract/dsc_pristine, point VPHONE_DSC_PRISTINE at it, or set \
+ VPHONE_DSC_FIXTURE_OPTIONAL=1 to skip these tests instead of failing
+ """
+
+ static let skipReason: Comment =
+ "VPHONE_DSC_FIXTURE_OPTIONAL=1 and no dyld_shared_cache_arm64e fixture present"
+
+ /// Where clones are made. Same filesystem as the pristine copy, so
+ /// `cp -c` is a clone rather than 6.7 GB of reads.
+ static var scratchRoot: URL {
+ repoRoot.appendingPathComponent("ipsws/ref_extract/scratch_dscfoundation")
+ }
+
+ /// 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 ipsw: URL? {
+ let url = URL(fileURLWithPath: "/opt/homebrew/bin/ipsw")
+ return FileManager.default.fileExists(atPath: url.path) ? url : nil
+ }
+
+ /// Clone the pristine cache into a fresh directory the caller may write to.
+ static func cloneCache(named name: String) throws -> URL {
+ guard let pristine else { throw CocoaError(.fileNoSuchFile) }
+ let destination = scratchRoot.appendingPathComponent(name)
+ try? FileManager.default.removeItem(at: destination)
+ try FileManager.default.createDirectory(
+ at: destination,
+ withIntermediateDirectories: true
+ )
+ let result = try Subprocess.run(
+ executable: URL(fileURLWithPath: "/bin/cp"),
+ arguments: ["-c", "-R"]
+ + (try FileManager.default.contentsOfDirectory(atPath: pristine.path))
+ .sorted()
+ .map { pristine.appendingPathComponent($0).path }
+ + [destination.path]
+ )
+ guard result.status == 0 else {
+ throw CocoaError(.fileWriteUnknown)
+ }
+ return destination
+ }
+
+ /// Discard a clone, and the scratch root with it once the last clone is
+ /// gone — the suite used to leave an empty `scratch_dscfoundation/` behind
+ /// on every run, so the working tree was not left as found.
+ 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],
+ 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()
+ // Drain before waiting: a full pipe buffer would deadlock a symbol dump.
+ 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 as an oracle
+
+/// A tiny driver around `cfw_dsc_chunks` / `cfw_dsc_codesign`, written to a
+/// temp file at test time. It adds no logic of its own — every number it
+/// prints comes out of the modules under `scripts/patchers/`, which is the
+/// point: the comparison has to be against that code, not a transcription.
+private enum PythonOracle {
+ static let source = #"""
+import hashlib
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(sys.argv[1], "scripts", "patchers"))
+
+from cfw_dsc_chunks import DSCChunks, _enumerate_chunks, _parse_chunk_mappings, resolve_local_symbol
+from cfw_dsc_codesign import _read_chunk_cd_blob, reattest_modified_pages
+
+command = sys.argv[2]
+chunks_dir = sys.argv[3]
+
+if command == "layout":
+ out = {"chunks": [], "mappings": []}
+ for path in _enumerate_chunks(chunks_dir):
+ out["chunks"].append(os.path.basename(path))
+ c = DSCChunks(chunks_dir)
+ for addr, end, foff, prot, cp in c.mappings():
+ out["mappings"].append({
+ "address": addr, "end": end, "file_offset": foff,
+ "init_prot": prot, "chunk": os.path.basename(cp),
+ })
+ print(json.dumps(out))
+
+elif command == "bytes":
+ # argv[4] = JSON file of [[vma, length], ...]
+ with open(sys.argv[4]) as f:
+ requests = json.load(f)
+ c = DSCChunks(chunks_dir)
+ out = []
+ for vma, length in requests:
+ cp, foff = c.find_chunk_for_vma(vma)
+ out.append({
+ "vma": vma,
+ "length": length,
+ "chunk": os.path.basename(cp),
+ "file_offset": foff,
+ "bytes": c.bytes_at_vma(vma, length).hex(),
+ })
+ print(json.dumps(out))
+
+elif command == "coderdirs":
+ out = {}
+ for path in _enumerate_chunks(chunks_dir):
+ out[os.path.basename(path)] = _read_chunk_cd_blob(path)
+ print(json.dumps(out))
+
+elif command == "patch_and_reattest":
+ # argv[4] = vma, argv[5] = replacement bytes as hex
+ vma = int(sys.argv[4], 0)
+ data = bytes.fromhex(sys.argv[5])
+ c = DSCChunks(chunks_dir)
+ before = c.bytes_at_vma(vma, len(data)).hex()
+ c.write_at_vma(vma, data)
+ diags = reattest_modified_pages(c, [vma], dry_run=False, verbose=False)
+ print(json.dumps({"before": before, "diagnostics": diags}))
+
+elif command == "write_at":
+ # argv[4] = vma, argv[5] = replacement bytes as hex. Write only, no re-sign.
+ vma = int(sys.argv[4], 0)
+ data = bytes.fromhex(sys.argv[5])
+ c = DSCChunks(chunks_dir)
+ c.write_at_vma(vma, data)
+ print(json.dumps({"ok": True}))
+
+elif command == "reattest_dry":
+ vma = int(sys.argv[4], 0)
+ c = DSCChunks(chunks_dir)
+ diags = reattest_modified_pages(c, [vma], dry_run=True, verbose=False)
+ print(json.dumps({"diagnostics": diags}))
+
+elif command == "local_symbol":
+ print(json.dumps({"address": resolve_local_symbol(chunks_dir, sys.argv[4])}))
+
+elif command == "string_vmas":
+ c = DSCChunks(chunks_dir)
+ print(json.dumps(c.find_string_vmas(sys.argv[4].encode())))
+
+elif command == "image_at":
+ # argv[4] = vma; walk back to the image header and read its install name
+ vma = int(sys.argv[4], 0)
+ c = DSCChunks(chunks_dir)
+ header = c.find_macho_header_before(vma)
+ print(json.dumps({
+ "header": header,
+ "install_name": c.read_install_name_at(header) if header else None,
+ }))
+
+elif command == "page_digest":
+ # argv[4] = chunk basename, argv[5] = page index, argv[6] = page size
+ path = os.path.join(chunks_dir, sys.argv[4])
+ page_size = int(sys.argv[6])
+ with open(path, "rb") as f:
+ f.seek(int(sys.argv[5]) * page_size)
+ page = f.read(page_size)
+ print(json.dumps({"sha256": hashlib.sha256(page).hexdigest()}))
+
+elif command == "slot_state":
+ # argv[4] = chunk basename, argv[5] = page index. What the page hashes to
+ # now, and what its code slot currently says it hashes to.
+ path = os.path.join(chunks_dir, sys.argv[4])
+ meta = _read_chunk_cd_blob(path)
+ page_index = int(sys.argv[5])
+ with open(path, "rb") as f:
+ f.seek(page_index * meta["page_size"])
+ page = f.read(meta["page_size"])
+ f.seek(meta["cd_file_off"] + meta["hash_offset"]
+ + page_index * meta["hash_size"])
+ stored = f.read(meta["hash_size"])
+ print(json.dumps({
+ "computed": hashlib.sha256(page).hexdigest(),
+ "stored": stored.hex(),
+ "page_size": meta["page_size"],
+ }))
+
+elif command == "file_bytes":
+ # argv[4] = chunk basename, argv[5] = file offset, argv[6] = length
+ path = os.path.join(chunks_dir, sys.argv[4])
+ with open(path, "rb") as f:
+ f.seek(int(sys.argv[5], 0))
+ print(json.dumps({"bytes": f.read(int(sys.argv[6])).hex()}))
+
+else:
+ raise SystemExit(f"unknown command {command}")
+"""#
+
+ static func scriptURL() throws -> URL {
+ let url = FileManager.default.temporaryDirectory
+ .appendingPathComponent("dsc_oracle_\(ProcessInfo.processInfo.processIdentifier).py")
+ if !FileManager.default.fileExists(atPath: url.path) {
+ try source.write(to: url, atomically: true, encoding: .utf8)
+ }
+ return url
+ }
+
+ @discardableResult
+ static func run(
+ _ command: String,
+ directory: URL,
+ extra: [String] = []
+ ) throws -> Data {
+ guard let python = DSCFixture.python else { throw CocoaError(.fileNoSuchFile) }
+ let script = try scriptURL()
+ let result = try Subprocess.run(
+ executable: python,
+ arguments: [
+ script.path,
+ DSCFixture.repoRoot.path,
+ command,
+ directory.path,
+ ] + extra
+ )
+ guard result.status == 0 else {
+ Issue.record("python oracle \(command) failed: \(result.stderr)")
+ throw CocoaError(.fileReadUnknown)
+ }
+ return Data(result.stdout.utf8)
+ }
+
+ /// What one page hashes to now, and what its slot claims, read straight
+ /// out of the code directory by the reference implementation.
+ struct SlotState: Decodable {
+ let computed: String
+ let stored: String
+ let page_size: Int
+
+ var isAttested: Bool { computed == stored }
+ }
+
+ static func slotState(
+ directory: URL,
+ chunk: String,
+ page: Int
+ ) throws -> SlotState {
+ try JSONDecoder().decode(
+ SlotState.self,
+ from: run("slot_state", directory: directory, extra: [chunk, String(page)])
+ )
+ }
+}
+
+// MARK: - 3.1 · Flat addressing
+
+@Suite(.serialized, .enabled(if: DSCFixture.runs, DSCFixture.skipReason))
+struct DSCFlatAddressingTests {
+ private struct PythonLayout: Decodable {
+ struct Mapping: Decodable {
+ let address: UInt64
+ let end: UInt64
+ let file_offset: UInt64
+ let init_prot: UInt32
+ let chunk: String
+ }
+
+ let chunks: [String]
+ let mappings: [Mapping]
+ }
+
+ private struct PythonBytes: Decodable {
+ let vma: UInt64
+ let length: Int
+ let chunk: String
+ let file_offset: Int
+ let bytes: String
+ }
+
+ @Test("Chunk enumeration and mapping table match cfw_dsc_chunks.py")
+ func layoutMatchesPython() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ try #require(DSCFixture.python != nil, "project venv is required for the cross-check")
+
+ let chunks = try DSCChunkSet(directory: pristine)
+ let reference = try JSONDecoder().decode(
+ PythonLayout.self,
+ from: PythonOracle.run("layout", directory: pristine)
+ )
+
+ #expect(chunks.chunkURLs.map(\.lastPathComponent).sorted() == reference.chunks.sorted())
+ #expect(chunks.mappings.count == reference.mappings.count)
+
+ for (mine, theirs) in zip(chunks.mappings, reference.mappings) {
+ #expect(mine.address == theirs.address)
+ #expect(mine.endAddress == theirs.end)
+ #expect(mine.fileOffset == theirs.file_offset)
+ #expect(mine.initProt == theirs.init_prot)
+ #expect(mine.chunkURL.lastPathComponent == theirs.chunk)
+ }
+ print(
+ "[layout] \(chunks.chunkURLs.count) chunks, \(chunks.mappings.count) mappings, "
+ + "vm 0x\(String(chunks.addressRange.lowerBound, radix: 16, uppercase: true))"
+ + "..0x\(String(chunks.addressRange.upperBound, radix: 16, uppercase: true))"
+ )
+ }
+
+ /// Reads spread across every mapping, including the first and last bytes of
+ /// each one — the spots where an off-by-one in the boundary test would
+ /// silently read out of the neighbouring chunk.
+ private func probeRequests(for chunks: DSCChunkSet) -> [(UInt64, Int)] {
+ var requests: [(UInt64, Int)] = []
+ for mapping in chunks.mappings {
+ requests.append((mapping.address, 16))
+ requests.append((mapping.endAddress - 8, 8))
+ requests.append((mapping.endAddress - 1, 1))
+ if mapping.size >= 256 {
+ let middle = (mapping.address + mapping.size / 2) & ~7
+ requests.append((middle, 64))
+ }
+ }
+ // Real code sites, not just mapping arithmetic.
+ for site: UInt64 in [0x2_2AC0_C334, 0x1BF4_33BD0, 0x1AD8_A12D8, 0x2_2AC0_C1B0] {
+ requests.append((site, 32))
+ }
+ return requests
+ }
+
+ @Test("bytesAtVMA matches cfw_dsc_chunks.py across every mapping and boundary")
+ func bytesMatchPython() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ try #require(DSCFixture.python != nil)
+
+ let chunks = try DSCChunkSet(directory: pristine)
+ let requests = probeRequests(for: chunks)
+
+ let requestFile = FileManager.default.temporaryDirectory
+ .appendingPathComponent("dsc_probe_requests.json")
+ try JSONSerialization
+ .data(withJSONObject: requests.map { [$0.0, UInt64($0.1)] })
+ .write(to: requestFile)
+
+ let reference = try JSONDecoder().decode(
+ [PythonBytes].self,
+ from: PythonOracle.run("bytes", directory: pristine, extra: [requestFile.path])
+ )
+ #expect(reference.count == requests.count)
+
+ var boundaryChecks = 0
+ for theirs in reference {
+ let mine = try chunks.bytesAtVMA(theirs.vma, length: theirs.length)
+ #expect(mine.hex == theirs.bytes, "bytes differ at 0x\(String(theirs.vma, radix: 16))")
+
+ let located = try #require(chunks.findChunk(forVMA: theirs.vma))
+ #expect(located.chunkURL.lastPathComponent == theirs.chunk)
+ #expect(located.fileOffset == theirs.file_offset)
+
+ if let mapping = chunks.mapping(forVMA: theirs.vma),
+ theirs.vma + UInt64(theirs.length) == mapping.endAddress
+ {
+ boundaryChecks += 1
+ }
+ }
+ print("[bytes] \(reference.count) reads agreed, \(boundaryChecks) of them ending exactly on a mapping boundary")
+ #expect(boundaryChecks >= 2)
+ }
+
+ @Test("A read or write that leaves its chunk is refused, not truncated")
+ func boundaryCrossingIsRefused() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ let chunks = try DSCChunkSet(directory: pristine)
+ let mapping = try #require(chunks.mappings.first { $0.size > 64 })
+ let lastFour = mapping.endAddress - 4
+
+ // Reading past the end of a mapping is not a short read, it is a
+ // different chunk's bytes. Every API has to say so.
+ #expect(throws: DSCError.self) {
+ _ = try chunks.readAtVMA(lastFour, length: 64)
+ }
+ let short = try chunks.readAtVMA(lastFour, length: 64, allowShort: true)
+ #expect(short.count == 4)
+
+ #expect(throws: DSCError.self) {
+ _ = try chunks.write(at: lastFour, Data(repeating: 0, count: 64))
+ }
+ #expect(throws: DSCError.self) {
+ _ = try chunks.bytesAtVMA(chunks.addressRange.upperBound + 0x1000, length: 4)
+ }
+ // And `bytesAtVMA` itself, at the same boundary — the case the suite
+ // used to name but never exercise.
+ #expect(throws: DSCError.self) {
+ _ = try chunks.bytesAtVMA(lastFour, length: 64)
+ }
+ #expect(try chunks.bytesAtVMA(lastFour, length: 4).count == 4)
+ }
+
+ /// The reference Python bounds-checks only the first byte of a read, then
+ /// reads `length` raw bytes from the file. So a read that starts near the
+ /// end of a mapping comes back padded with whatever follows in the file,
+ /// presented as the bytes at those virtual addresses. This is the one place
+ /// the Swift deliberately diverges, and the test pins both halves: what the
+ /// Python returns, and that the Swift refuses it.
+ @Test("An over-running read returns the chunk's signature in Python, and throws here")
+ func overrunningReadIsRefusedUnlikeThePython() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ try #require(DSCFixture.python != nil)
+
+ let chunks = try DSCChunkSet(directory: pristine)
+ // 0x1800BBFFC is four bytes before the end of the main chunk's first
+ // mapping. The next mapping starts at 0x180400000 — a 3.3 MB hole — so
+ // bytes 4..63 of a 64-byte read correspond to no virtual address.
+ let overrun: UInt64 = 0x1_800B_BFFC
+ let mapping = try #require(chunks.mapping(forVMA: overrun))
+ #expect(mapping.endAddress == overrun + 4)
+
+ #expect(throws: DSCError.self) {
+ _ = try chunks.bytesAtVMA(overrun, length: 64)
+ }
+
+ let requestFile = FileManager.default.temporaryDirectory
+ .appendingPathComponent("dsc_overrun_request.json")
+ try JSONSerialization
+ .data(withJSONObject: [[overrun, UInt64(64)]])
+ .write(to: requestFile)
+ let theirs = try JSONDecoder().decode(
+ [PythonBytes].self,
+ from: PythonOracle.run("bytes", directory: pristine, extra: [requestFile.path])
+ )
+ let pythonBytes = try #require(theirs.first).bytes
+ #expect(pythonBytes.count == 128, "the Python returns all 64 bytes without complaint")
+ // Bytes 4.. are the chunk's own CS_SuperBlob, not code.
+ #expect(pythonBytes.contains("fade0cc0"))
+
+ // The four bytes that really are at that address still read fine.
+ let inBounds = try chunks.bytesAtVMA(overrun, length: 4)
+ #expect(pythonBytes.hasPrefix(inBounds.hex))
+ print("[overrun] python returned 64 bytes at 0x\(String(overrun, radix: 16)): \(pythonBytes.prefix(48))…")
+ print("[overrun] swift threw; its in-bounds 4 bytes are \(inBounds.hex)")
+ }
+
+ @Test("resolveLocalSymbol matches the Python and ipsw")
+ func localSymbolMatchesReferences() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ try #require(DSCFixture.python != nil)
+
+ let chunks = try DSCChunkSet(directory: pristine)
+ let name = "_kern_SwapEnd"
+ let mine = try #require(try chunks.resolveLocalSymbol(name))
+
+ struct Answer: Decodable { let address: UInt64 }
+ let theirs = try JSONDecoder().decode(
+ Answer.self,
+ from: PythonOracle.run("local_symbol", directory: pristine, extra: [name])
+ )
+ #expect(mine == theirs.address)
+ print("[local symbol] \(name) = 0x\(String(mine, radix: 16)) (python: 0x\(String(theirs.address, radix: 16)))")
+
+ // A name that is not in the table is `nil`, and that is a different
+ // answer from the table not being there — see
+ // `missingLocalSymbolTableIsNotAMissingSymbol`.
+ #expect(try chunks.resolveLocalSymbol("_definitely_not_a_symbol_xyz") == nil)
+ }
+
+ /// The `try?` this replaced spelled "I could not open the table" and "that
+ /// symbol does not exist" the same way, as `nil`. The Python raises
+ /// `FileNotFoundError`; so does this, in its own vocabulary.
+ @Test("A missing local symbol table is not the same answer as a missing symbol")
+ func missingLocalSymbolTableIsNotAMissingSymbol() throws {
+ _ = try #require(DSCFixture.pristine, DSCFixture.missing)
+
+ let clone = try DSCFixture.cloneCache(named: "symbols_removed")
+ defer { DSCFixture.discard(clone) }
+ try FileManager.default.removeItem(
+ at: clone.appendingPathComponent("dyld_shared_cache_arm64e.symbols")
+ )
+
+ let chunks = try DSCChunkSet(directory: clone)
+ #expect(throws: DSCError.self) {
+ _ = try chunks.resolveLocalSymbol("_kern_SwapEnd")
+ }
+ #expect(throws: DSCError.self) {
+ _ = try chunks.resolveLocalSymbol("_definitely_not_a_symbol_xyz")
+ }
+
+ // And the resolver built on the same cache says so rather than
+ // reporting entry points with no siblings.
+ let resolver = try DSCSymbolResolver(
+ mainCacheURL: clone.appendingPathComponent("dyld_shared_cache_arm64e")
+ )
+ #expect(!resolver.hasLocalSymbols)
+ #expect(throws: DSCError.self) { try resolver.requireLocalSymbols() }
+ #expect(throws: DSCError.self) {
+ _ = try resolver.address(
+ of: "_kern_SwapEnd",
+ inImage: "/System/Library/PrivateFrameworks/IOMobileFramebuffer.framework/IOMobileFramebuffer"
+ )
+ }
+ print("[symbols missing] resolveLocalSymbol and the resolver both report the absent table")
+ }
+
+ /// The two helpers P1.3's `hv_vmm` and canonical-site finders are built on:
+ /// a C-string sweep of the executable mappings, and the walk back from an
+ /// address to the image that owns it.
+ @Test("String search and image lookup match cfw_dsc_chunks.py")
+ func searchHelpersMatchPython() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ try #require(DSCFixture.python != nil)
+
+ let chunks = try DSCChunkSet(directory: pristine)
+
+ let needle = "kern.hv_vmm_present"
+ let mine = try chunks.findStringVMAs(Data(needle.utf8))
+ let theirs = try JSONDecoder().decode(
+ [UInt64].self,
+ from: PythonOracle.run("string_vmas", directory: pristine, extra: [needle])
+ )
+ #expect(mine.sorted() == theirs.sorted())
+ #expect(!mine.isEmpty)
+ print("[strings] \"\(needle)\": \(mine.count) hits, first 0x\(String(mine[0], radix: 16))")
+
+ struct Image: Decodable {
+ let header: UInt64?
+ let install_name: String?
+ }
+ for site: UInt64 in [0x2_2AC0_C334, 0x1BF4_33BD0, 0x1AD8_A12D8] {
+ let header = try #require(try chunks.findMachOHeaderBefore(site))
+ let name = chunks.readInstallName(atHeaderVMA: header)
+ let reference = try JSONDecoder().decode(
+ Image.self,
+ from: PythonOracle.run(
+ "image_at",
+ directory: pristine,
+ extra: ["0x\(String(site, radix: 16))"]
+ )
+ )
+ #expect(header == reference.header)
+ #expect(name == reference.install_name)
+ print("[image] 0x\(String(site, radix: 16)) -> 0x\(String(header, radix: 16)) \(name ?? "<none>")")
+ }
+ }
+}
+
+// MARK: - 3.2 · Code-signature page-hash re-signing, DSC path
+
+@Suite(.serialized, .enabled(if: DSCFixture.runs, DSCFixture.skipReason))
+struct DSCCodeSignatureTests {
+ private struct PythonDirectory: Decodable {
+ let cd_file_off: Int
+ let cd_length: Int
+ let hash_offset: Int
+ let hash_size: Int
+ let n_code_slots: Int
+ let code_limit: Int
+ let page_size: Int
+ }
+
+ private struct PythonDiagnostic: Decodable {
+ let chunk_path: String
+ let page_index: Int
+ let chunk_off: Int
+ let slot_off: Int
+ let sha256_before: String
+ let sha256_after: String
+ }
+
+ private struct PythonPatchResult: Decodable {
+ let before: String
+ let diagnostics: [PythonDiagnostic]
+ }
+
+ /// A site inside `IOMobileFramebuffer`'s `__text` — a real executable page
+ /// whose slot a real patch would have to re-sign.
+ private let patchSite: UInt64 = 0x2_2AC0_C334
+
+ @Test("Chunk code directories match cfw_dsc_codesign.py")
+ func codeDirectoriesMatchPython() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ try #require(DSCFixture.python != nil)
+
+ let chunks = try DSCChunkSet(directory: pristine)
+ let reference = try JSONDecoder().decode(
+ [String: PythonDirectory?].self,
+ from: PythonOracle.run("coderdirs", directory: pristine)
+ )
+
+ var compared = 0
+ for url in chunks.chunkURLs {
+ let mine = try DSCCodeSignature.readCodeDirectory(ofChunk: url)
+ let theirs = reference[url.lastPathComponent] ?? nil
+ guard let theirs else {
+ #expect(mine == nil, "\(url.lastPathComponent): python found no CD, Swift did")
+ continue
+ }
+ let mine2 = try #require(mine, "\(url.lastPathComponent): python found a CD, Swift did not")
+ #expect(mine2.blobOffset == theirs.cd_file_off)
+ #expect(mine2.blobLength == theirs.cd_length)
+ #expect(mine2.hashOffset == theirs.hash_offset)
+ #expect(mine2.hashSize == theirs.hash_size)
+ #expect(mine2.codeSlotCount == theirs.n_code_slots)
+ #expect(mine2.codeLimit == theirs.code_limit)
+ #expect(mine2.pageSize == theirs.page_size)
+ compared += 1
+ }
+ print("[code directories] \(compared) chunk signatures agreed with the Python")
+ #expect(compared > 70)
+ }
+
+ /// The DSC path's stated invariants: 16 KiB pages, a single SHA-256 code
+ /// directory, and no short tail slot.
+ @Test("Every signed chunk is 16 KiB paged, SHA-256, and chunk-aligned")
+ func dscPathShapeHolds() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ let chunks = try DSCChunkSet(directory: pristine)
+ var checked = 0
+ for url in chunks.chunkURLs {
+ guard let directory = try DSCCodeSignature.readCodeDirectory(ofChunk: url) else {
+ continue
+ }
+ #expect(directory.pageSize == 16384, "\(url.lastPathComponent) page size")
+ #expect(directory.hashSize == 32, "\(url.lastPathComponent) hash size")
+ // Chunk-aligned: the last slot covers a whole page, so unlike the
+ // independent Mach-O path there is no short tail to special-case.
+ let covered = directory.codeSlotCount * directory.pageSize
+ #expect(
+ covered == directory.codeLimit,
+ "\(url.lastPathComponent) has a short tail slot: codeLimit \(directory.codeLimit), slots cover \(covered)"
+ )
+ checked += 1
+ }
+ print("[shape] \(checked) chunks: 16 KiB pages, SHA-256, no short tail slot")
+ #expect(checked > 70)
+ }
+
+ /// The gate from the plan: patch one byte, re-sign with each
+ /// implementation in its own clone, and require the two caches to come out
+ /// byte-identical over the page and over the whole code directory.
+ @Test("Swift and Python re-signing produce byte-identical slot hashes")
+ func reSigningMatchesPythonByteForByte() throws {
+ _ = try #require(DSCFixture.pristine, DSCFixture.missing)
+ try #require(DSCFixture.python != nil)
+
+ let swiftSide = try DSCFixture.cloneCache(named: "resign_swift")
+ let pythonSide = try DSCFixture.cloneCache(named: "resign_python")
+ defer { DSCFixture.discard(swiftSide, pythonSide) }
+
+ // The replacement is a real instruction shape — `mov w3, #0x588`, the
+ // immediate `cfw_patch_iomfb_swapend` writes — not a byte pattern
+ // chosen to be easy.
+ let replacement = Data([0x03, 0xB1, 0x80, 0x52])
+
+ // Python: write through its own writer, then re-sign.
+ let pythonResult = try JSONDecoder().decode(
+ PythonPatchResult.self,
+ from: PythonOracle.run(
+ "patch_and_reattest",
+ directory: pythonSide,
+ extra: ["0x\(String(patchSite, radix: 16))", replacement.hex]
+ )
+ )
+ #expect(pythonResult.diagnostics.count == 1)
+ let theirs = try #require(pythonResult.diagnostics.first)
+
+ // Swift: same write, same re-sign — and the re-sign is driven by what
+ // the write itself recorded, not by an address repeated by hand.
+ let chunks = try DSCChunkSet(directory: swiftSide)
+ let originalBytes = try chunks.bytesAtVMA(patchSite, length: replacement.count)
+ #expect(originalBytes.hex == pythonResult.before)
+ let span = try chunks.write(at: patchSite, replacement)
+ #expect(span == DSCWriteSpan(vma: patchSite, length: 4))
+ #expect(chunks.recordedWrites == [span])
+
+ var log: [String] = []
+ let result = try DSCCodeSignature.reattestRecordedWrites(
+ in: chunks,
+ log: { log.append($0) }
+ )
+ #expect(result.updated.count == 1)
+ #expect(result.isFullyAttested)
+ let mine = try #require(result.updated.first)
+
+ // The hashes themselves.
+ #expect(mine.pageIndex == theirs.page_index)
+ #expect(mine.chunkOffset == theirs.chunk_off)
+ #expect(mine.slotOffset == theirs.slot_off)
+ #expect(mine.hashBefore.hex == theirs.sha256_before)
+ #expect(mine.hashAfter.hex == theirs.sha256_after)
+ #expect(mine.chunkURL.lastPathComponent == URL(fileURLWithPath: theirs.chunk_path).lastPathComponent)
+
+ // And the bytes on disk, which is the claim that actually matters.
+ let chunkName = mine.chunkURL.lastPathComponent
+ let directory = try #require(
+ try DSCCodeSignature.readCodeDirectory(ofChunk: mine.chunkURL)
+ )
+ let swiftSlots = try DSCChunkSet.read(
+ url: swiftSide.appendingPathComponent(chunkName),
+ offset: UInt64(directory.blobOffset),
+ length: directory.blobLength
+ )
+ let pythonSlots = try DSCChunkSet.read(
+ url: pythonSide.appendingPathComponent(chunkName),
+ offset: UInt64(directory.blobOffset),
+ length: directory.blobLength
+ )
+ #expect(swiftSlots == pythonSlots, "the whole code directory blob must match")
+
+ let swiftPage = try DSCChunkSet.read(
+ url: swiftSide.appendingPathComponent(chunkName),
+ offset: UInt64(mine.chunkOffset),
+ length: directory.pageSize
+ )
+ let pythonPage = try DSCChunkSet.read(
+ url: pythonSide.appendingPathComponent(chunkName),
+ offset: UInt64(mine.chunkOffset),
+ length: directory.pageSize
+ )
+ #expect(swiftPage == pythonPage, "the patched page must match")
+
+ // The stored slot has to be the digest of the page as it now stands.
+ let (computed, stored) = try DSCCodeSignature.pageHashes(
+ chunkURL: mine.chunkURL,
+ pageIndex: mine.pageIndex,
+ directory: directory
+ )
+ #expect(computed == stored)
+ #expect(stored.hex == theirs.sha256_after)
+
+ print("[re-sign] chunk \(chunkName) page \(mine.pageIndex) slot @0x\(String(mine.slotOffset, radix: 16))")
+ print("[re-sign] swift \(mine.hashAfter.hex)")
+ print("[re-sign] python \(theirs.sha256_after)")
+ for line in log { print(line) }
+ }
+
+ /// The finding all three verifiers reached independently, pinned.
+ ///
+ /// Eight bytes — `mov w0, #0; ret`, exactly what `cfw_patch_camera_dsc.py`
+ /// writes at each of its six function entries — placed so four of them land
+ /// on page 2563 and four on page 2564. Re-attesting the address alone
+ /// covers one page; the other keeps its original slot hash, and the guest
+ /// dies on the first demand-page-in of it. The Python does exactly that;
+ /// this checks the Swift no longer can.
+ @Test("A write across a page boundary re-attests both pages, where the Python attests one")
+ func pageStraddlingWriteAttestsEveryDirtiedPage() throws {
+ _ = try #require(DSCFixture.pristine, DSCFixture.missing)
+ try #require(DSCFixture.python != nil)
+
+ let swiftSide = try DSCFixture.cloneCache(named: "straddle_swift")
+ let pythonSide = try DSCFixture.cloneCache(named: "straddle_python")
+ defer { DSCFixture.discard(swiftSide, pythonSide) }
+
+ // 0x22AC0FFFC is file offset 0x280FFFC of chunk .38 — the last four
+ // bytes of page 2563. Eight bytes from there end four bytes into 2564.
+ let straddle: UInt64 = 0x2_2AC0_FFFC
+ let stub = Data([0x00, 0x00, 0x80, 0x52, 0xC0, 0x03, 0x5F, 0xD6])
+ let chunkName = "dyld_shared_cache_arm64e.38"
+ let firstPage = 2563
+ let secondPage = 2564
+
+ // Swift: write, then re-attest from what the write recorded.
+ let chunks = try DSCChunkSet(directory: swiftSide)
+ let span = try chunks.write(at: straddle, stub)
+ #expect(span.length == 8)
+ let (writtenChunk, writtenRange) = try chunks.fileRange(of: span)
+ #expect(writtenChunk.lastPathComponent == chunkName)
+ #expect(writtenRange == 0x280_FFFC ..< 0x281_0004)
+
+ var log: [String] = []
+ let result = try DSCCodeSignature.reattestRecordedWrites(
+ in: chunks,
+ log: { log.append($0) }
+ )
+ #expect(result.updated.map(\.pageIndex) == [firstPage, secondPage])
+ #expect(result.isFullyAttested)
+
+ // Both pages, checked by the reference implementation reading the code
+ // directory itself — not by this code agreeing with itself.
+ for page in [firstPage, secondPage] {
+ let state = try PythonOracle.slotState(
+ directory: swiftSide,
+ chunk: chunkName,
+ page: page
+ )
+ #expect(state.isAttested, "swift left page \(page) stale: \(state.stored)")
+ print("[straddle swift] page \(page) stored \(state.stored.prefix(16))… == computed")
+ }
+
+ // The Python, told the same address, covers page 2563 and leaves 2564
+ // stale. This is the bug in the reference, reproduced, so the
+ // divergence is on the record rather than assumed.
+ let pythonResult = try JSONDecoder().decode(
+ PythonPatchResult.self,
+ from: PythonOracle.run(
+ "patch_and_reattest",
+ directory: pythonSide,
+ extra: ["0x\(String(straddle, radix: 16))", stub.hex]
+ )
+ )
+ #expect(pythonResult.diagnostics.map(\.page_index) == [firstPage])
+
+ let pythonFirst = try PythonOracle.slotState(
+ directory: pythonSide, chunk: chunkName, page: firstPage
+ )
+ let pythonSecond = try PythonOracle.slotState(
+ directory: pythonSide, chunk: chunkName, page: secondPage
+ )
+ #expect(pythonFirst.isAttested)
+ #expect(
+ !pythonSecond.isAttested,
+ "the Python reference unexpectedly covered the second page too"
+ )
+ print("[straddle python] page \(firstPage) attested, page \(secondPage) stored "
+ + "\(pythonSecond.stored.prefix(16))… vs computed \(pythonSecond.computed.prefix(16))… — STALE")
+
+ // The bytes themselves still agree; only the attested page set differs.
+ let swiftBytes = try DSCChunkSet.read(
+ url: swiftSide.appendingPathComponent(chunkName),
+ offset: 0x280_FFFC,
+ length: 8
+ )
+ let pythonBytes = try DSCChunkSet.read(
+ url: pythonSide.appendingPathComponent(chunkName),
+ offset: 0x280_FFFC,
+ length: 8
+ )
+ #expect(swiftBytes == stub)
+ #expect(swiftBytes == pythonBytes)
+ for line in log { print(line) }
+ }
+
+ /// A span may cross from one mapping into the next when the two are
+ /// contiguous in address *and* in file offset inside the same chunk — 19 of
+ /// the 62 adjacent mapping pairs on this cache are. The old guard compared
+ /// mapping start addresses and refused all of them, where the Python wrote
+ /// them happily. This one is accepted, and matches the Python byte for
+ /// byte; the case where the file offsets break is still refused.
+ @Test("A write across contiguous mappings of one chunk is written, and matches the Python")
+ func contiguousMappingSeamIsWritable() throws {
+ _ = try #require(DSCFixture.pristine, DSCFixture.missing)
+ try #require(DSCFixture.python != nil)
+
+ let swiftSide = try DSCFixture.cloneCache(named: "seam_swift")
+ let pythonSide = try DSCFixture.cloneCache(named: "seam_python")
+ defer { DSCFixture.discard(swiftSide, pythonSide) }
+
+ // 0x1E00DFFFE is two bytes before the end of the first mapping of
+ // .25.dylddata; the next mapping continues at file offset 0x4000 of the
+ // same file. Four bytes therefore cross both a mapping seam and a
+ // 16 KiB page boundary.
+ let seam: UInt64 = 0x1_E00D_FFFE
+ let value = Data([0x11, 0x22, 0x33, 0x44])
+ let chunkName = "dyld_shared_cache_arm64e.25.dylddata"
+
+ let chunks = try DSCChunkSet(directory: swiftSide)
+ let mapping = try #require(chunks.mapping(forVMA: seam))
+ let next = try #require(chunks.mapping(forVMA: mapping.endAddress))
+ #expect(next.chunkURL.lastPathComponent == chunkName)
+ #expect(next.fileOffset == mapping.fileOffset + mapping.size)
+
+ let span = try chunks.write(at: seam, value)
+ let result = try DSCCodeSignature.reattestRecordedWrites(in: chunks, log: nil)
+ #expect(span.length == 4)
+ #expect(result.isFullyAttested)
+ // 0x3FFE..0x4001 spans pages 0 and 1 of the chunk.
+ #expect(result.updated.map(\.pageIndex) + result.alreadyAttested.map(\.pageIndex) == [0, 1])
+
+ try PythonOracle.run(
+ "write_at",
+ directory: pythonSide,
+ extra: ["0x\(String(seam, radix: 16))", value.hex]
+ )
+ struct Bytes: Decodable { let bytes: String }
+ let theirs = try JSONDecoder().decode(
+ Bytes.self,
+ from: PythonOracle.run(
+ "file_bytes",
+ directory: pythonSide,
+ extra: [chunkName, "0x3ffe", "4"]
+ )
+ )
+ let mine = try DSCChunkSet.read(
+ url: swiftSide.appendingPathComponent(chunkName),
+ offset: 0x3FFE,
+ length: 4
+ )
+ #expect(mine.hex == theirs.bytes)
+ #expect(mine == value)
+ print("[seam] 0x\(String(seam, radix: 16)) -> \(chunkName)@0x3ffe: swift \(mine.hex), python \(theirs.bytes)")
+
+ for page in [0, 1] {
+ let state = try PythonOracle.slotState(
+ directory: swiftSide, chunk: chunkName, page: page
+ )
+ #expect(state.isAttested, "page \(page) left stale")
+ }
+
+ // A seam where the file offsets do not continue is still a refusal.
+ let crossChunk = try #require(
+ chunks.mappings.first { mapping in
+ guard let next = chunks.mapping(forVMA: mapping.endAddress) else { return false }
+ return next.chunkURL != mapping.chunkURL
+ }
+ )
+ #expect(throws: DSCError.self) {
+ _ = try chunks.write(at: crossChunk.endAddress - 2, Data([0, 0, 0, 0]))
+ }
+ }
+
+ /// `8eb6c8b` fixed a patcher that did not recognise its own output. The
+ /// same trap applies here: a second re-sign of an already-attested page has
+ /// to be a no-op, not a rewrite and not an error.
+ @Test("Re-signing twice is a no-op the second time")
+ func reSigningIsIdempotent() throws {
+ _ = try #require(DSCFixture.pristine, DSCFixture.missing)
+
+ let clone = try DSCFixture.cloneCache(named: "resign_idempotent")
+ defer { DSCFixture.discard(clone) }
+
+ let chunks = try DSCChunkSet(directory: clone)
+ let span = try chunks.write(at: patchSite, Data([0x03, 0xB1, 0x80, 0x52]))
+
+ let first = try DSCCodeSignature.reattest(in: chunks, modifiedSpans: [span], log: nil)
+ #expect(first.updated.count == 1)
+ #expect(first.alreadyAttested.isEmpty)
+
+ let second = try DSCCodeSignature.reattest(in: chunks, modifiedSpans: [span], log: nil)
+ #expect(second.updated.isEmpty, "a second re-sign rewrote a slot that already matched")
+ #expect(second.alreadyAttested.count == 1, "and it has to say so, not just return nothing")
+ #expect(second.isFullyAttested)
+
+ // Several addresses inside one page still cost exactly one slot.
+ let third = try DSCCodeSignature.reattest(
+ in: chunks,
+ modifiedSpans: [patchSite, patchSite + 4, patchSite + 8].map(DSCWriteSpan.byte(at:)),
+ log: nil
+ )
+ #expect(third.updated.isEmpty)
+ #expect(third.alreadyAttested.count == 1)
+ print("[idempotence] first run rewrote 1 slot; second and third rewrote 0 and reported 1 already correct")
+ }
+
+ /// Every early return used to yield `[]` under the default `log: nil`, so
+ /// "I skipped an address I could not map", "everything already matched" and
+ /// "you passed me nothing" were the same value. They are three different
+ /// values now, and the default log is no longer silent.
+ @Test("A skipped page is distinguishable from nothing to do")
+ func skipsAreReportedNotSwallowed() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ let chunks = try DSCChunkSet(directory: pristine)
+
+ let stray = try DSCCodeSignature.reattest(
+ in: chunks,
+ modifiedSpans: [DSCWriteSpan.byte(at: 0xDEAD_0000_0000)],
+ dryRun: true,
+ log: nil
+ )
+ #expect(stray.updated.isEmpty)
+ #expect(stray.skipped.count == 1)
+ #expect(!stray.isFullyAttested, "an unmapped address is not a clean run")
+ if case let .addressNotMapped(vma) = stray.skipped[0].reason {
+ #expect(vma == 0xDEAD_0000_0000)
+ } else {
+ Issue.record("wrong skip reason: \(stray.skipped[0].reason)")
+ }
+
+ let nothing = try DSCCodeSignature.reattest(
+ in: chunks,
+ modifiedSpans: [] as [DSCWriteSpan],
+ dryRun: true,
+ log: nil
+ )
+ #expect(nothing.skipped.isEmpty)
+ #expect(nothing.isFullyAttested, "nothing to do is a clean run")
+
+ // A span that runs off the end of its chunk is its own reason.
+ let mapping = try #require(chunks.mappings.first { $0.size > 64 })
+ let overrun = try DSCCodeSignature.reattest(
+ in: chunks,
+ modifiedSpans: [DSCWriteSpan(vma: mapping.endAddress - 2, length: 64)],
+ dryRun: true,
+ log: nil
+ )
+ #expect(overrun.skipped.count == 1)
+ if case .spanNotAddressable = overrun.skipped[0].reason {} else {
+ Issue.record("wrong skip reason: \(overrun.skipped[0].reason)")
+ }
+
+ // And the default log says all of it out loud, like the Python's
+ // verbose=True does.
+ var spoken: [String] = []
+ _ = try DSCCodeSignature.reattest(
+ in: chunks,
+ modifiedSpans: [DSCWriteSpan.byte(at: 0xDEAD_0000_0000)],
+ dryRun: true,
+ log: { spoken.append($0) }
+ )
+ #expect(spoken.contains { $0.contains("not mapped in any chunk") })
+ for line in spoken { print("[skip log] \(line)") }
+ }
+
+ @Test("A dry run computes the same hash it would have written, and writes nothing")
+ func dryRunWritesNothing() throws {
+ _ = try #require(DSCFixture.pristine, DSCFixture.missing)
+
+ let clone = try DSCFixture.cloneCache(named: "resign_dryrun")
+ defer { DSCFixture.discard(clone) }
+
+ let chunks = try DSCChunkSet(directory: clone)
+ try chunks.write(at: patchSite, Data([0x03, 0xB1, 0x80, 0x52]))
+
+ let dry = try DSCCodeSignature.reattestRecordedWrites(
+ in: chunks,
+ dryRun: true,
+ log: nil
+ )
+ #expect(dry.updated.count == 1)
+ let record = try #require(dry.updated.first)
+
+ let directory = try #require(
+ try DSCCodeSignature.readCodeDirectory(ofChunk: record.chunkURL)
+ )
+ let (_, storedAfterDryRun) = try DSCCodeSignature.pageHashes(
+ chunkURL: record.chunkURL,
+ pageIndex: record.pageIndex,
+ directory: directory
+ )
+ #expect(storedAfterDryRun == record.hashBefore, "a dry run must not touch the slot")
+
+ let wet = try DSCCodeSignature.reattestRecordedWrites(in: chunks, log: nil)
+ #expect(wet.updated.first?.hashAfter == record.hashAfter)
+ }
+}
+
+// MARK: - 3.3 · Symbol resolution
+
+@Suite(.serialized, .enabled(if: DSCFixture.runs, DSCFixture.skipReason))
+struct DSCSymbolResolverTests {
+ private static let neutrinoCore =
+ "/System/Library/PrivateFrameworks/NeutrinoCore.framework/NeutrinoCore"
+ private static let avfCapture =
+ "/System/Library/PrivateFrameworks/AVFCapture.framework/AVFCapture"
+ private static let ioMobileFramebuffer =
+ "/System/Library/PrivateFrameworks/IOMobileFramebuffer.framework/IOMobileFramebuffer"
+
+ /// The complete set the three patchers look up.
+ ///
+ /// `cfw_patch_camera_dsc.py` names six ObjC methods; `cfw_patch_iomfb_swapend.py`
+ /// names `_kern_SwapEnd`; `cfw_patch_iomfb_force_kern.py` does not name any,
+ /// it discovers every `_IOMobileFramebufferSwap*` with a `_kern_` sibling,
+ /// so the four pairs that discovery finds on this cache are listed here.
+ private static let required: [(image: String, symbols: [String])] = [
+ (neutrinoCore, [
+ "+[_NUStyleTransferProcessor processWithInputs:arguments:output:error:]",
+ "+[_NUStyleTransferThumbnailProcessor processWithInputs:arguments:output:error:]",
+ "+[_NUStyleTransferApplyProcessor processWithInputs:arguments:output:error:]",
+ "+[_NUStyleTransferLearnProcessor processWithInputs:arguments:output:error:]",
+ "+[_NUStyleTransferInterpolateProcessor processWithInputs:arguments:output:error:]",
+ ]),
+ (avfCapture, [
+ "+[AVCaptureDevice authorizationStatusForMediaType:]",
+ ]),
+ (ioMobileFramebuffer, [
+ "_kern_SwapEnd",
+ "_kern_SwapBegin",
+ "_kern_SwapSetLayer",
+ "_kern_SwapSetLayerEDRCompensation",
+ "_IOMobileFramebufferSwapBegin",
+ "_IOMobileFramebufferSwapEnd",
+ "_IOMobileFramebufferSwapSetLayer",
+ "_IOMobileFramebufferSwapSetLayerEDRCompensation",
+ ]),
+ ]
+
+ /// `ipsw dyld symaddr <cache> --image <image>` for one image, parsed into
+ /// name → address. The per-symbol form of that command is what times out on
+ /// this cache; the whole-image dump answers in under a second.
+ private func ipswSymbols(image: String, cache: URL) throws -> [String: UInt64] {
+ guard let ipsw = DSCFixture.ipsw else { return [:] }
+ let result = try Subprocess.run(
+ executable: ipsw,
+ arguments: [
+ "dyld", "symaddr",
+ cache.appendingPathComponent("dyld_shared_cache_arm64e").path,
+ "--image", image,
+ ]
+ )
+ guard result.status == 0 else { return [:] }
+
+ var symbols: [String: UInt64] = [:]
+ for rawLine in result.stdout.split(separator: "\n") {
+ // Strip SGR colour codes, then split "0xADDR:\t(kind)\tname\timage".
+ let line = rawLine.replacing(/\u{1B}\[[0-9;]*m/, with: "")
+ guard let colon = line.firstIndex(of: ":") else { continue }
+ let addressText = line[line.startIndex ..< colon].trimmingCharacters(in: .whitespaces)
+ guard addressText.hasPrefix("0x"),
+ let address = UInt64(addressText.dropFirst(2), radix: 16)
+ else { continue }
+ var rest = line[line.index(after: colon)...]
+ .trimmingCharacters(in: .whitespaces)
+ guard rest.hasPrefix("(") , let close = rest.firstIndex(of: ")") else { continue }
+ rest = String(rest[rest.index(after: close)...]).trimmingCharacters(in: .whitespaces)
+ // The name may be followed by a tab and the image name; ObjC method
+ // names contain spaces, so split on tabs only.
+ let name = rest.split(separator: "\t").first.map(String.init) ?? rest
+ if symbols[name] == nil { symbols[name] = address }
+ }
+ return symbols
+ }
+
+ @Test("Every symbol the three DSC patchers look up resolves, and agrees with ipsw")
+ func requiredSymbolsResolveAndAgree() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ let resolver = try DSCSymbolResolver(
+ mainCacheURL: pristine.appendingPathComponent("dyld_shared_cache_arm64e")
+ )
+ #expect(resolver.hasLocalSymbols)
+
+ var agreed = 0
+ var unconfirmed: [String] = []
+ for (image, wanted) in Self.required {
+ let resolved = try resolver.addresses(of: wanted, inImage: image)
+ #expect(resolved.count == wanted.count)
+
+ let reference = try ipswSymbols(image: image, cache: pristine)
+ for name in wanted {
+ let mine = try #require(resolved[name])
+ #expect(mine != 0)
+ if let theirs = reference[name] {
+ #expect(
+ mine == theirs,
+ "\(name): swift 0x\(String(mine, radix: 16)) vs ipsw 0x\(String(theirs, radix: 16))"
+ )
+ agreed += 1
+ print("[symbol] \(name) = 0x\(String(mine, radix: 16)) (ipsw agrees)")
+ } else {
+ unconfirmed.append(name)
+ print("[symbol] \(name) = 0x\(String(mine, radix: 16)) (ipsw did not report it)")
+ }
+ }
+ }
+ print("[symbols] \(agreed) confirmed against ipsw, \(unconfirmed.count) unconfirmed")
+ #expect(agreed >= 13, "ipsw confirmed only \(agreed) symbols")
+ }
+
+ @Test("The force-kern discovery shape is reproduced without ipsw")
+ func forceKernPairsAreDiscoverable() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ let resolver = try DSCSymbolResolver(
+ mainCacheURL: pristine.appendingPathComponent("dyld_shared_cache_arm64e")
+ )
+ try resolver.requireLocalSymbols()
+
+ let publicPrefix = "_IOMobileFramebufferSwap"
+ let all = try resolver.symbols(inImage: Self.ioMobileFramebuffer)
+ let entryPoints = try resolver.symbols(
+ inImage: Self.ioMobileFramebuffer,
+ withPrefix: publicPrefix
+ )
+
+ var pairs: [(String, UInt64, String, UInt64)] = []
+ for (name, address) in entryPoints.sorted(by: { $0.key < $1.key }) {
+ let sibling = "_kern_Swap" + name.dropFirst(publicPrefix.count)
+ guard let kern = all[sibling] else { continue }
+ pairs.append((name, address, sibling, kern.address))
+ }
+
+ // `cfw_patch_iomfb_force_kern.py` refuses to ship unless these three
+ // are covered, so the resolver has to find all three without ipsw.
+ for required in ["SwapBegin", "SwapEnd", "SwapSetLayer"] {
+ #expect(
+ pairs.contains { $0.0 == publicPrefix + required.dropFirst(4) },
+ "missing entry point for \(required)"
+ )
+ }
+ for pair in pairs {
+ print("[force-kern] \(pair.0) 0x\(String(pair.1, radix: 16)) -> \(pair.2) 0x\(String(pair.3, radix: 16))")
+ }
+ #expect(pairs.count >= 3)
+ }
+
+ @Test("A missing symbol and a missing image both fail loudly")
+ func missingLookupsThrow() throws {
+ let pristine = try #require(DSCFixture.pristine, DSCFixture.missing)
+ let resolver = try DSCSymbolResolver(
+ mainCacheURL: pristine.appendingPathComponent("dyld_shared_cache_arm64e")
+ )
+ #expect(throws: DSCError.self) {
+ _ = try resolver.address(
+ of: "_this_symbol_does_not_exist",
+ inImage: Self.ioMobileFramebuffer
+ )
+ }
+ #expect(throws: DSCError.self) {
+ _ = try resolver.symbols(inImage: "/System/Library/Nope.framework/Nope")
+ }
+ }
+}
diff --git a/tests/VPhoneArchiveTests/BundleTransferTests.swift b/tests/VPhoneArchiveTests/BundleTransferTests.swift
new file mode 100644
index 00000000..f3c09d79
--- /dev/null
+++ b/tests/VPhoneArchiveTests/BundleTransferTests.swift
@@ -0,0 +1,484 @@
+import Foundation
+import Testing
+@testable import VPhoneArchive
+import VPhoneCore
+
+/// `vm export` / `vm import`, moved here with the implementation when they came
+/// off the two-stage `tar` pipe. The format contract they pin — gnutar, one
+/// top-level directory, `.tzst` at zstd 3, `.txz` at xz 9, the extension chosen
+/// from the preset — is the reason these tests came along unchanged: archives
+/// in those shapes are already on people's disks.
+///
+/// `.serialized` for the same reason as `RoundTripTests`: libarchive leaves
+/// `tar.XXXXXXXX` temp files in the process's working directory when several
+/// extractions run at once.
+@Suite("VM bundle export and import", .serialized)
+struct BundleTransferTests {
+ // MARK: - Fixtures
+
+ private func makeRoot() throws -> URL {
+ let dir = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+ return dir
+ }
+
+ private func fakeROM() throws -> URL {
+ let f = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString + ".bin")
+ try Data([0xAA, 0xBB, 0xCC]).write(to: f)
+ return f
+ }
+
+ @discardableResult
+ private func makeBundle(
+ _ name: String,
+ cpuCount: UInt = 2,
+ in library: VPhoneLibrary
+ ) throws -> VPhoneBundle {
+ let rom = try fakeROM(); let seprom = try fakeROM()
+ defer {
+ try? FileManager.default.removeItem(at: rom)
+ try? FileManager.default.removeItem(at: seprom)
+ }
+ return try VPhoneBundleOps.create(
+ .init(
+ name: name,
+ cpuCount: cpuCount,
+ memoryMB: 2048,
+ diskSizeGB: 1,
+ romSource: rom,
+ sepromSource: seprom
+ ),
+ in: library
+ )
+ }
+
+ private func systemTar(_ args: [String]) throws -> VPhoneProcessResult {
+ try VPhoneProcessRunner.runCapturing(URL(fileURLWithPath: "/usr/bin/tar"), args)
+ }
+
+ // MARK: - Round trip
+
+ @Test func exportThenImportRoundTrips() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ try makeBundle("orig", cpuCount: 8, in: lib)
+
+ let archive = root.appendingPathComponent("orig.tgz")
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
+ #expect(FileManager.default.fileExists(atPath: archive.path))
+
+ // Import into a fresh library, renaming.
+ let root2 = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root2) }
+ let lib2 = VPhoneLibrary(root: root2)
+ let imported = try VPhoneBundleTransfer.importArchive(from: archive, name: "copy", in: lib2)
+ #expect(imported.name == "copy")
+ #expect(imported.manifest.cpuCount == 8)
+ #expect(imported.manifest.memorySize == 2048 * 1024 * 1024)
+ #expect(try lib2.bundle(named: "copy").manifest.cpuCount == 8)
+ }
+
+ @Test func importRejectsExistingName() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ try makeBundle("orig", in: lib)
+ let archive = root.appendingPathComponent("orig.tgz")
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
+ // Importing back under the same existing name must fail.
+ #expect(throws: VPhoneLibraryError.alreadyExists(name: "orig")) {
+ _ = try VPhoneBundleTransfer.importArchive(from: archive, name: nil, in: lib)
+ }
+ }
+
+ @Test func importWithRenameDoesNotClobberArchivedNameCollision() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ // Existing "orig" (cpu 16) that must NOT be touched by the import.
+ try makeBundle("orig", cpuCount: 16, in: lib)
+
+ // Archive of a DIFFERENT "orig" (cpu 4) from a separate library.
+ let root2 = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root2) }
+ let lib2 = VPhoneLibrary(root: root2)
+ try makeBundle("orig", cpuCount: 4, in: lib2)
+ let archive = root2.appendingPathComponent("orig.tgz")
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib2)
+
+ let imported = try VPhoneBundleTransfer.importArchive(from: archive, name: "renamed", in: lib)
+ #expect(imported.name == "renamed")
+ #expect(imported.manifest.cpuCount == 4)
+ #expect(try lib.bundle(named: "orig").manifest.cpuCount == 16) // untouched
+ }
+
+ // MARK: - Exclusions
+
+ @Test func exportExcludesRestoreDirByDefault() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ let b = try makeBundle("orig", in: lib)
+ let restoreDir = b.url.appendingPathComponent("iPhone_Restore")
+ try FileManager.default.createDirectory(at: restoreDir, withIntermediateDirectories: true)
+ try Data([0]).write(to: restoreDir.appendingPathComponent("marker"))
+
+ let archive = root.appendingPathComponent("orig.tgz")
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
+ let members = try VPhoneArchiveReader.entries(of: archive).map(\.path)
+ #expect(!members.contains { $0.contains("iPhone_Restore") })
+ }
+
+ @Test func exportIncludesRestoreDirWhenAsked() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ let b = try makeBundle("orig", in: lib)
+ let restoreDir = b.url.appendingPathComponent("iPhone_Restore")
+ try FileManager.default.createDirectory(at: restoreDir, withIntermediateDirectories: true)
+ try Data([0]).write(to: restoreDir.appendingPathComponent("marker"))
+
+ let archive = root.appendingPathComponent("orig.tgz")
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: true, in: lib)
+ let members = try VPhoneArchiveReader.entries(of: archive).map(\.path)
+ #expect(members.contains("orig/iPhone_Restore/marker"))
+ }
+
+ @Test func exportExcludesRegenerableStagingFiles() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ let b = try makeBundle("orig", in: lib)
+ let fm = FileManager.default
+ try Data([0]).write(to: b.url.appendingPathComponent(".vphoned.signed"))
+ try fm.createDirectory(at: b.url.appendingPathComponent("cfw_input/jb"), withIntermediateDirectories: true)
+ try Data([0]).write(to: b.url.appendingPathComponent("cfw_input/jb/f"))
+ try fm.createDirectory(at: b.url.appendingPathComponent("cfw_jb_input"), withIntermediateDirectories: true)
+ try Data([0]).write(to: b.url.appendingPathComponent("cfw_jb_input/f"))
+ try fm.createDirectory(at: b.url.appendingPathComponent(".cfw_temp"), withIntermediateDirectories: true)
+ try Data([0]).write(to: b.url.appendingPathComponent(".cfw_temp/f"))
+
+ let archive = root.appendingPathComponent("orig.tgz")
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
+ let members = try VPhoneArchiveReader.entries(of: archive).map(\.path)
+ #expect(!members.contains { $0.contains(".vphoned.signed") })
+ #expect(!members.contains { $0.contains("cfw_input") })
+ #expect(!members.contains { $0.contains("cfw_jb_input") })
+ #expect(!members.contains { $0.contains(".cfw_temp") })
+ // The real payload still travels.
+ #expect(members.contains("orig/Disk.img"))
+ #expect(members.contains("orig/config.plist"))
+ }
+
+ // MARK: - Malformed input
+
+ @Test func importRejectsMultiTopLevelArchive() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ // An archive with TWO top-level dirs is not a single bundle → badArchive.
+ let src = root.appendingPathComponent("src")
+ try FileManager.default.createDirectory(at: src.appendingPathComponent("a"), withIntermediateDirectories: true)
+ try FileManager.default.createDirectory(at: src.appendingPathComponent("b"), withIntermediateDirectories: true)
+ try Data([0]).write(to: src.appendingPathComponent("a/x"))
+ try Data([0]).write(to: src.appendingPathComponent("b/y"))
+ let archive = root.appendingPathComponent("multi.tgz")
+ try VPhoneArchiveWriter.create(archive: archive, from: src, compression: .gzip(level: 1))
+
+ #expect(throws: VPhoneBundleTransferError.self) {
+ _ = try VPhoneBundleTransfer.importArchive(
+ from: archive, name: nil, in: VPhoneLibrary(root: root.appendingPathComponent("library")))
+ }
+ }
+
+ @Test func importRejectsInvalidManifestWithoutReservingName() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let fm = FileManager.default
+ let bundleDir = root.appendingPathComponent("original")
+ try fm.createDirectory(at: bundleDir, withIntermediateDirectories: true)
+ let config = bundleDir.appendingPathComponent("config.plist")
+ try "not a plist".write(to: config, atomically: true, encoding: .utf8)
+ let archive = root.appendingPathComponent("vm.tgz")
+ let lib = VPhoneLibrary(root: root.appendingPathComponent("library"))
+
+ func pack() throws {
+ try? fm.removeItem(at: archive)
+ try VPhoneArchiveWriter.create(
+ archive: archive, from: bundleDir, topLevel: "original", compression: .gzip(level: 1))
+ }
+ try pack()
+ #expect(throws: VPhoneManifestError.self) {
+ _ = try VPhoneBundleTransfer.importArchive(from: archive, name: nil, in: lib)
+ }
+ // Neither a destination bundle nor a hidden staging directory may remain.
+ #expect(try fm.contentsOfDirectory(atPath: lib.root.path).isEmpty)
+
+ let manifest = VPhoneVirtualMachineManifest(
+ cpuCount: 2, memorySize: 2048 * 1024 * 1024, romImages: nil)
+ try manifest.write(to: config)
+ try pack()
+ let imported = try VPhoneBundleTransfer.importArchive(from: archive, name: nil, in: lib)
+ #expect(imported.url == lib.url(forName: "original"))
+ #expect(try lib.bundle(named: "original").manifest.cpuCount == 2)
+ }
+
+ // MARK: - Compression presets
+
+ private static let zstdMagic: [UInt8] = [0x28, 0xB5, 0x2F, 0xFD]
+ private static let xzMagic: [UInt8] = [0xFD, 0x37, 0x7A, 0x58, 0x5A, 0x00]
+
+ private func magic(_ url: URL, _ n: Int) throws -> [UInt8] {
+ Array(try Data(contentsOf: url).prefix(n))
+ }
+
+ private func exportAndImport(
+ _ compression: VPhoneBundleTransfer.ExportCompression?
+ ) throws -> (archive: URL, imported: VPhoneBundle) {
+ let root = try makeRoot()
+ let lib = VPhoneLibrary(root: root)
+ try makeBundle("orig", cpuCount: 6, in: lib)
+ let archive = root.appendingPathComponent("orig.archive")
+ if let compression {
+ try VPhoneBundleTransfer.export(
+ bundleNamed: "orig",
+ to: archive,
+ includeIPSW: false,
+ compression: compression,
+ in: lib
+ )
+ } else {
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
+ }
+ let dstRoot = try makeRoot()
+ let imported = try VPhoneBundleTransfer.importArchive(
+ from: archive, name: "copy", in: VPhoneLibrary(root: dstRoot))
+ return (archive, imported)
+ }
+
+ @Test func exportDefaultsToFastZstd() throws {
+ let (archive, imported) = try exportAndImport(nil)
+ #expect(try magic(archive, 4) == Self.zstdMagic)
+ #expect(imported.manifest.cpuCount == 6)
+ }
+
+ @Test func exportFastProducesZstdAndRoundTrips() throws {
+ let (archive, imported) = try exportAndImport(.fast)
+ #expect(try magic(archive, 4) == Self.zstdMagic)
+ #expect(imported.manifest.cpuCount == 6)
+ }
+
+ @Test func exportMaxProducesXzAndRoundTrips() throws {
+ let (archive, imported) = try exportAndImport(.max)
+ #expect(try magic(archive, 6) == Self.xzMagic)
+ #expect(imported.manifest.cpuCount == 6)
+ }
+
+ /// Replaces the old `compressionPresetTarArgs`, which pinned the same
+ /// contract as `tar` flag strings. The levels are not tuning: `.tzst` and
+ /// `.txz` files produced at these settings are already in circulation.
+ @Test func compressionPresetsPinLevelsAndExtensions() {
+ #expect(VPhoneBundleTransfer.ExportCompression.fast.archiveCompression == .zstd(level: 3))
+ #expect(VPhoneBundleTransfer.ExportCompression.max.archiveCompression == .xz(level: 9))
+ #expect(VPhoneBundleTransfer.ExportCompression.fast.fileExtension == "tzst")
+ #expect(VPhoneBundleTransfer.ExportCompression.max.fileExtension == "txz")
+ }
+
+ @Test func exportToDirectoryAutoNamesWithExtension() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ try makeBundle("orig", cpuCount: 6, in: lib)
+
+ let outDir = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: outDir) }
+ let zstdOut = try VPhoneBundleTransfer.export(
+ bundleNamed: "orig",
+ to: outDir,
+ includeIPSW: false,
+ in: lib
+ )
+ #expect(zstdOut == outDir.appendingPathComponent("orig.tzst"))
+ #expect(FileManager.default.fileExists(atPath: zstdOut.path))
+ let xzOut = try VPhoneBundleTransfer.export(
+ bundleNamed: "orig",
+ to: outDir,
+ includeIPSW: false,
+ compression: .max,
+ in: lib
+ )
+ #expect(xzOut == outDir.appendingPathComponent("orig.txz"))
+ #expect(FileManager.default.fileExists(atPath: xzOut.path))
+ }
+
+ // MARK: - Progress
+
+ @Test func exportAndImportReportProgress() throws {
+ final class Collector {
+ private(set) var dones: [Int64] = []
+ private(set) var total: Int64 = 0
+ func add(_ done: Int64, _ total: Int64) { dones.append(done); self.total = total }
+ }
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ try makeBundle("orig", cpuCount: 6, in: lib)
+
+ let exp = Collector()
+ let archive = root.appendingPathComponent("orig.tzst")
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib) {
+ exp.add($0, $1)
+ }
+ #expect(!exp.dones.isEmpty)
+ #expect(exp.total > 0) // bundle logical size
+ #expect(exp.dones.last! > 0)
+ #expect(exp.dones == exp.dones.sorted()) // monotonically non-decreasing
+ // A bar that only moved once per member would sit at zero for the whole
+ // export: Disk.img is one entry and everything else is tiny.
+ #expect(exp.dones.count > 1)
+
+ let imp = Collector()
+ let dstRoot = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: dstRoot) }
+ _ = try VPhoneBundleTransfer.importArchive(
+ from: archive, name: "copy", in: VPhoneLibrary(root: dstRoot)) {
+ imp.add($0, $1)
+ }
+ let archiveSize = try Data(contentsOf: archive).count
+ #expect(!imp.dones.isEmpty)
+ #expect(imp.total == Int64(archiveSize)) // total == compressed file size
+ #expect(imp.dones == imp.dones.sorted())
+ #expect(imp.dones.last! == Int64(archiveSize)) // whole archive accounted for
+
+ // That last one cannot fail on its own: `importArchive` reports
+ // `(total, total)` unconditionally once extraction returns, precisely
+ // so a tar end-of-archive marker short of the last byte does not leave
+ // the bar at 99%. So it would stay green with the per-block callback
+ // ripped out entirely. What proves the callback fires is the positions
+ // BEFORE that final report — a bar that only learned where it was at
+ // the end is not a progress bar.
+ let intermediate = Set(imp.dones.dropLast())
+ #expect(intermediate.count > 1, "import reported \(intermediate.count) position(s) before the final one")
+ #expect(intermediate.contains { $0 < Int64(archiveSize) })
+ }
+
+ /// The progress total has to be reachable. `archivedLogicalSize` counts the
+ /// bytes that will be packed, and a hardlinked file is packed once however
+ /// many names it has — the writer's link resolver turns the later names
+ /// into size-0 references. Counting each name's size instead put the total
+ /// permanently above the packed bytes, so the bar could not reach 100%.
+ @Test func exportProgressTotalCountsAHardlinkedFileOnce() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ let bundle = try makeBundle("orig", in: lib)
+
+ // One 100 KiB payload under three names, the shape a procursus
+ // bootstrap has all over it.
+ let payload = bundle.url.appendingPathComponent("linked.bin")
+ try Data(repeating: 0x7A, count: 100 * 1024).write(to: payload)
+ for alias in ["linked_b.bin", "linked_c.bin"] {
+ try FileManager.default.linkItem(
+ at: payload, to: bundle.url.appendingPathComponent(alias))
+ }
+
+ final class Collector {
+ private(set) var done: Int64 = 0
+ private(set) var total: Int64 = 0
+ func add(_ done: Int64, _ total: Int64) { self.done = done; self.total = total }
+ }
+ let progress = Collector()
+ let archive = root.appendingPathComponent("orig.tzst")
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib) {
+ progress.add($0, $1)
+ }
+
+ #expect(progress.total > 0)
+ #expect(progress.done == progress.total, "packed \(progress.done) of a claimed \(progress.total)")
+ // All three names travel; only the bytes do not travel three times.
+ let members = try VPhoneArchiveReader.entries(of: archive).map(\.path)
+ for alias in ["linked.bin", "linked_b.bin", "linked_c.bin"] {
+ #expect(members.contains("orig/\(alias)"))
+ }
+ }
+
+ // MARK: - Compatibility, both directions
+
+ /// An export holds exactly one top-level directory named after the VM, and
+ /// an entry for that directory itself — what `tar -C <library> <name>`
+ /// produced. `importArchive` requires it, and so does every archive already
+ /// written by an older copy of this program.
+ @Test func exportCarriesOneTopLevelBundleDirectory() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ try makeBundle("orig", in: lib)
+ let archive = root.appendingPathComponent("orig.tar")
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
+
+ // "orig/", with the slash a tar header gives a directory — the same
+ // spelling the old pipeline's `tar -C <library> orig` produced.
+ let members = try VPhoneArchiveReader.entries(of: archive).map(\.path)
+ #expect(members.first == "orig/")
+ #expect(members.allSatisfy { $0.hasPrefix("orig/") })
+ }
+
+ /// The old code path spawned `/usr/bin/tar --format gnutar -cf - -C <root>
+ /// <name>` into a compressing consumer. Reproducing that shape here checks
+ /// the direction that cannot be checked any other way once the pipe is
+ /// gone: an archive produced before this change still imports.
+ ///
+ /// gzip rather than zstd only so the check does not need a `zstd(1)` on
+ /// PATH — which is the whole point of the migration. The compressor is
+ /// detected either way; `research/archive_extraction_contracts.md` records
+ /// the .tzst and .txz runs.
+ @Test func importReadsArchiveWrittenByTheOldTarPipeline() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ try makeBundle("legacy", cpuCount: 6, in: lib)
+
+ let archive = root.appendingPathComponent("legacy.tgz")
+ let packed = try systemTar([
+ "--format", "gnutar", "-czf", archive.path,
+ "--exclude", "*_Restore*",
+ "-C", lib.root.path, "legacy",
+ ])
+ try #require(packed.succeeded, "system tar could not pack the legacy-shaped archive")
+
+ let dstRoot = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: dstRoot) }
+ let imported = try VPhoneBundleTransfer.importArchive(
+ from: archive, name: "fromlegacy", in: VPhoneLibrary(root: dstRoot))
+ #expect(imported.name == "fromlegacy")
+ #expect(imported.manifest.cpuCount == 6)
+ #expect(FileManager.default.fileExists(atPath: imported.url.appendingPathComponent("Disk.img").path))
+ }
+
+ /// And the other direction: what this writes is an ordinary tar. Checked
+ /// after `decompress`, so the check does not need a `zstd(1)` either; the
+ /// zstd stream itself is pinned by the magic-byte tests above.
+ @Test func systemTarReadsWhatExportWrites() throws {
+ let root = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: root) }
+ let lib = VPhoneLibrary(root: root)
+ try makeBundle("orig", cpuCount: 6, in: lib)
+
+ let archive = root.appendingPathComponent("orig.tzst")
+ try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
+ let plain = root.appendingPathComponent("orig.tar")
+ try VPhoneArchiveWriter.decompress(archive, to: plain)
+
+ let listed = try systemTar(["-tf", plain.path])
+ #expect(listed.succeeded)
+ #expect(listed.stdout.contains("orig/Disk.img"))
+ #expect(listed.stdout.contains("orig/config.plist"))
+
+ let out = try makeRoot()
+ defer { try? FileManager.default.removeItem(at: out) }
+ let extracted = try systemTar(["-xf", plain.path, "-C", out.path])
+ #expect(extracted.succeeded)
+ let config = out.appendingPathComponent("orig/config.plist")
+ #expect(try VPhoneVirtualMachineManifest.load(from: config).cpuCount == 6)
+ }
+}
diff --git a/tests/VPhoneArchiveTests/ExtractPermissionsTests.swift b/tests/VPhoneArchiveTests/ExtractPermissionsTests.swift
new file mode 100644
index 00000000..91746f63
--- /dev/null
+++ b/tests/VPhoneArchiveTests/ExtractPermissionsTests.swift
@@ -0,0 +1,199 @@
+import Foundation
+import LibArchive
+import Testing
+@testable import VPhoneArchive
+import VPhoneCore
+
+/// What an extraction is allowed to decide about the modes of the files it
+/// writes.
+///
+/// There are two answers and they are opposites, which is the whole reason
+/// these exist. `ontoGuestVolume` restores the archive's modes verbatim,
+/// setuid included, because an iOS system volume's modes are the payload.
+/// `intoHostDirectory` does not, because the archive came from somewhere else
+/// and the files land in the user's home directory.
+///
+/// `vm import` shelled out to `/usr/bin/tar -xf` — no `-p` — for its whole
+/// life, so it always had the second behaviour. When the shell-out became a
+/// libarchive call, `ARCHIVE_EXTRACT_PERM` was set unconditionally and the
+/// behaviour silently became the first. That is what these pin.
+///
+/// `.serialized` for the same reason as the other suites here: libarchive
+/// leaves `tar.XXXXXXXX` temp files in the working directory when several
+/// extractions run at once.
+@Suite("Extraction permissions", .serialized)
+struct ExtractPermissionsTests {
+ // MARK: - Fixture
+
+ /// The three shapes that tell the two presets apart: a setuid binary, a
+ /// world-writable directory and a world-writable file.
+ private struct Fixture {
+ let source: URL
+ let archive: URL
+
+ static let setuidFile = "setuid_file"
+ static let wideDirectory = "wide_dir"
+ static let worldWritableFile = "world_writable.txt"
+
+ /// What is stored in the archive, which is also what `-p` restores.
+ static let archivedModes: [String: mode_t] = [
+ setuidFile: 0o4755,
+ wideDirectory: 0o777,
+ worldWritableFile: 0o666,
+ ]
+
+ static func make() throws -> Fixture {
+ let fm = FileManager.default
+ let source = scratch("perm-src")
+ try fm.createDirectory(at: source, withIntermediateDirectories: true)
+ try Data("#!/bin/sh\n".utf8).write(to: source.appendingPathComponent(setuidFile))
+ try fm.createDirectory(
+ at: source.appendingPathComponent(wideDirectory), withIntermediateDirectories: true)
+ try Data("owo\n".utf8).write(to: source.appendingPathComponent(worldWritableFile))
+ // chmod after the writes: creating a file resets its mode.
+ for (name, mode) in archivedModes {
+ try fm.setAttributes(
+ [.posixPermissions: NSNumber(value: mode)],
+ ofItemAtPath: source.appendingPathComponent(name).path)
+ }
+ // A setuid bit that the filesystem refused would make every
+ // assertion below vacuously true.
+ try #require(
+ self.mode(of: source.appendingPathComponent(setuidFile)) == 0o4755,
+ "the test filesystem would not keep a setuid bit")
+
+ // Uncompressed, so /usr/bin/tar can read it without a filter
+ // helper on PATH.
+ let archive = scratch("perm-arc").appendingPathExtension("tar")
+ try VPhoneArchiveWriter.create(archive: archive, from: source)
+ return Fixture(source: source, archive: archive)
+ }
+
+ static func scratch(_ suffix: String) -> URL {
+ FileManager.default.temporaryDirectory
+ .appendingPathComponent("vphone-\(suffix)-\(UUID().uuidString)")
+ }
+
+ /// The permission bits, setuid/setgid/sticky included.
+ static func mode(of url: URL) -> mode_t? {
+ var info = stat()
+ guard lstat(url.path, &info) == 0 else { return nil }
+ return info.st_mode & 0o7777
+ }
+
+ func cleanUp() {
+ for url in [source, archive] { try? FileManager.default.removeItem(at: url) }
+ }
+ }
+
+ // MARK: - The flag itself
+
+ /// The regression test, at the level the regression happened: a flag.
+ ///
+ /// `ARCHIVE_EXTRACT_PERM` is `tar -p`. Without it, `archive_write_disk`
+ /// clears setuid, setgid and sticky and masks what is left through the
+ /// umask; with it, the archive's mode is written exactly. Anything that
+ /// sets it on the host preset — including "tidying up" the conditional —
+ /// fails here.
+ @Test func hostPresetNeverRestoresSetuid() {
+ let host = VPhoneArchiveExtractOptions.intoHostDirectory
+ #expect(!host.exactPermissions)
+ #expect(host.extractFlags & Int32(ARCHIVE_EXTRACT_PERM) == 0)
+
+ // And the other half of the contract: cfw_install genuinely needs the
+ // exact modes, so the guest preset must keep the flag.
+ let guest = VPhoneArchiveExtractOptions.ontoGuestVolume
+ #expect(guest.exactPermissions)
+ #expect(guest.extractFlags & Int32(ARCHIVE_EXTRACT_PERM) != 0)
+ }
+
+ /// The default is the safe one, so an option set built by hand — or a
+ /// preset someone copies — does not acquire `-p` by omission.
+ @Test func exactPermissionsIsOptIn() {
+ #expect(!VPhoneArchiveExtractOptions(ownership: .currentUser).exactPermissions)
+ #expect(!VPhoneArchiveExtractOptions(ownership: .preserveNumeric).exactPermissions)
+ }
+
+ // MARK: - What lands on disk
+
+ /// The observable half: unpack the same archive with the host preset and
+ /// with `/usr/bin/tar -xf`, and require the modes to agree.
+ ///
+ /// Comparing against `tar` rather than against literals keeps this true
+ /// whatever umask the test runs under — and `tar -xf` is precisely what
+ /// `vm import` used to run, so agreement with it *is* the contract.
+ @Test func hostExtractionMatchesPlainSystemTar() throws {
+ let fixture = try Fixture.make()
+ defer { fixture.cleanUp() }
+ let fm = FileManager.default
+
+ let ours = Fixture.scratch("perm-ours")
+ let theirs = Fixture.scratch("perm-tar")
+ try fm.createDirectory(at: ours, withIntermediateDirectories: true)
+ try fm.createDirectory(at: theirs, withIntermediateDirectories: true)
+ defer { for url in [ours, theirs] { try? fm.removeItem(at: url) } }
+
+ try VPhoneArchiveExtractor.extract(
+ fixture.archive, into: ours, options: .intoHostDirectory)
+ let untarred = try VPhoneProcessRunner.runCapturing(
+ URL(fileURLWithPath: "/usr/bin/tar"),
+ ["-xf", fixture.archive.path, "-C", theirs.path])
+ try #require(untarred.succeeded, "system tar could not unpack the fixture: \(untarred.stderr)")
+
+ for name in Fixture.archivedModes.keys.sorted() {
+ let mine = Fixture.mode(of: ours.appendingPathComponent(name))
+ let tars = Fixture.mode(of: theirs.appendingPathComponent(name))
+ #expect(mine != nil, "\(name) was not extracted")
+ #expect(mine == tars, "\(name): extractor gave \(mine ?? 0), tar -xf gave \(tars ?? 0)")
+ }
+ }
+
+ /// And the part that holds under any umask: nothing arriving from an
+ /// archive may be setuid, setgid or sticky. Run as root — `vm import`
+ /// under sudo — restoring the archive's mode would give a setuid-root
+ /// binary out of an untrusted file.
+ @Test func hostExtractionStripsSetuidSetgidAndSticky() throws {
+ let fixture = try Fixture.make()
+ defer { fixture.cleanUp() }
+ let fm = FileManager.default
+ let destination = Fixture.scratch("perm-strip")
+ try fm.createDirectory(at: destination, withIntermediateDirectories: true)
+ defer { try? fm.removeItem(at: destination) }
+
+ try VPhoneArchiveExtractor.extract(
+ fixture.archive, into: destination, options: .intoHostDirectory)
+
+ for name in Fixture.archivedModes.keys.sorted() {
+ let mode = try #require(Fixture.mode(of: destination.appendingPathComponent(name)))
+ #expect(mode & mode_t(S_ISUID) == 0, "\(name) came back setuid")
+ #expect(mode & mode_t(S_ISGID) == 0, "\(name) came back setgid")
+ #expect(mode & mode_t(S_ISVTX) == 0, "\(name) came back sticky")
+ }
+ }
+
+ /// The opposite preset, on the one thing that can be checked without
+ /// being root: with `-p` the setuid bit survives. (Ownership cannot —
+ /// `ARCHIVE_EXTRACT_OWNER` needs root — but the mode does, because the
+ /// file already belongs to whoever is running.)
+ @Test func guestPresetKeepsExactModes() throws {
+ let fixture = try Fixture.make()
+ defer { fixture.cleanUp() }
+ let fm = FileManager.default
+ let destination = Fixture.scratch("perm-guest")
+ try fm.createDirectory(at: destination, withIntermediateDirectories: true)
+ defer { try? fm.removeItem(at: destination) }
+
+ var options = VPhoneArchiveExtractOptions.ontoGuestVolume
+ // The one thing dialled back for a non-root run: chown would fail and
+ // take the setuid bit down with it. Everything under test here is the
+ // mode.
+ options.ownership = .currentUser
+ try VPhoneArchiveExtractor.extract(fixture.archive, into: destination, options: options)
+
+ for (name, archived) in Fixture.archivedModes.sorted(by: { $0.key < $1.key }) {
+ #expect(
+ Fixture.mode(of: destination.appendingPathComponent(name)) == archived,
+ "\(name) did not come back with the mode the archive stores")
+ }
+ }
+}
diff --git a/tests/VPhoneArchiveTests/NoOverwriteDirTests.swift b/tests/VPhoneArchiveTests/NoOverwriteDirTests.swift
index c1fe1b18..1dfe7864 100644
--- a/tests/VPhoneArchiveTests/NoOverwriteDirTests.swift
+++ b/tests/VPhoneArchiveTests/NoOverwriteDirTests.swift
@@ -52,6 +52,26 @@ struct NoOverwriteDirTests {
return info.st_mode & 0o7777
}
+ /// The options `cfw_install` unpacks with, minus the one part that needs
+ /// root.
+ ///
+ /// `--no-overwrite-dir` exists for exactly one caller — unpacking onto a
+ /// mounted guest volume — so `ontoGuestVolume` is the preset these vary
+ /// `noOverwriteDir` against. It is also the preset that carries
+ /// `exactPermissions`, and the modes below are what that means: the host
+ /// preset masks them through the umask instead, which is its whole point
+ /// (see `ExtractPermissionsTests`) and would make "the archive's mode
+ /// won" unobservable here.
+ ///
+ /// `.currentUser` only because `ARCHIVE_EXTRACT_OWNER` would need root to
+ /// chown, and these run as whoever is testing.
+ static func installOptions(noOverwriteDir: Bool) -> VPhoneArchiveExtractOptions {
+ var options = VPhoneArchiveExtractOptions.ontoGuestVolume
+ options.ownership = .currentUser
+ options.noOverwriteDir = noOverwriteDir
+ return options
+ }
+
// MARK: - The behaviour that matters
@Test("an existing directory keeps its own permissions")
@@ -71,9 +91,8 @@ struct NoOverwriteDirTests {
[.posixPermissions: NSNumber(value: 0o700)], ofItemAtPath: existing.path
)
- var options = VPhoneArchiveExtractOptions.intoHostDirectory
- options.noOverwriteDir = true
- try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)
+ try VPhoneArchiveExtractor.extract(
+ archive, into: destination, options: Self.installOptions(noOverwriteDir: true))
#expect(try Self.mode(of: existing) == 0o700)
}
@@ -93,9 +112,8 @@ struct NoOverwriteDirTests {
[.posixPermissions: NSNumber(value: 0o700)], ofItemAtPath: existing.path
)
- var options = VPhoneArchiveExtractOptions.intoHostDirectory
- options.noOverwriteDir = false
- try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)
+ try VPhoneArchiveExtractor.extract(
+ archive, into: destination, options: Self.installOptions(noOverwriteDir: false))
// `man 3 archive_write_disk`: "existing directories will have their
// permissions updated". Confirmed — 0700 in, 0777 out. This is
@@ -120,9 +138,8 @@ struct NoOverwriteDirTests {
let existing = destination.appendingPathComponent("dir")
try FileManager.default.createDirectory(at: existing, withIntermediateDirectories: true)
- var options = VPhoneArchiveExtractOptions.intoHostDirectory
- options.noOverwriteDir = true
- try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)
+ try VPhoneArchiveExtractor.extract(
+ archive, into: destination, options: Self.installOptions(noOverwriteDir: true))
// This is the difference from ARCHIVE_EXTRACT_NO_OVERWRITE, which
// would have skipped the whole subtree.
@@ -143,9 +160,8 @@ struct NoOverwriteDirTests {
let beside = destination.appendingPathComponent("beside.txt")
try Data("stale\n".utf8).write(to: beside)
- var options = VPhoneArchiveExtractOptions.intoHostDirectory
- options.noOverwriteDir = true
- try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)
+ try VPhoneArchiveExtractor.extract(
+ archive, into: destination, options: Self.installOptions(noOverwriteDir: true))
// The other half of why ARCHIVE_EXTRACT_NO_OVERWRITE is not a
// substitute: it would have left "stale" in place.
@@ -161,9 +177,8 @@ struct NoOverwriteDirTests {
try? FileManager.default.removeItem(at: destination)
}
- var options = VPhoneArchiveExtractOptions.intoHostDirectory
- options.noOverwriteDir = true
- try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)
+ try VPhoneArchiveExtractor.extract(
+ archive, into: destination, options: Self.installOptions(noOverwriteDir: true))
let dir = destination.appendingPathComponent("dir")
#expect(FileManager.default.fileExists(atPath: dir.path))
@@ -187,9 +202,8 @@ struct NoOverwriteDirTests {
at: destination.appendingPathComponent("dir"), withDestinationURL: elsewhere
)
- var options = VPhoneArchiveExtractOptions.intoHostDirectory
- options.noOverwriteDir = true
- try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)
+ try VPhoneArchiveExtractor.extract(
+ archive, into: destination, options: Self.installOptions(noOverwriteDir: true))
// Two things have to hold, and both do.
//
diff --git a/tests/VPhoneArchiveTests/RoundTripTests.swift b/tests/VPhoneArchiveTests/RoundTripTests.swift
index f1514e4d..6d493a23 100644
--- a/tests/VPhoneArchiveTests/RoundTripTests.swift
+++ b/tests/VPhoneArchiveTests/RoundTripTests.swift
@@ -208,6 +208,37 @@ struct RoundTripTests {
#expect(paths.contains("top.txt"))
}
+ @Test("packing does not modify the tree it reads")
+ func packingLeavesTheSourceAlone() throws {
+ // libarchive's read_disk defaults to ARCHIVE_READDISK_MAC_COPYFILE,
+ // which packs each file's AppleDouble form through a temp file made
+ // from a *relative* mkstemp template — and the tree walker chdir's
+ // into each directory as it descends, so the temp file appears and
+ // vanishes inside the directory being read and leaves its mtime at
+ // now. `vm export` was rewriting the mtime of every directory in the
+ // VM bundle it had only been asked to read. `/usr/bin/tar -cf` does
+ // not do this, and neither should this.
+ let source = try Self.makeTree()
+ let archive = Self.scratch("untouched").appendingPathExtension("tar")
+ defer {
+ for url in [source, archive] { try? FileManager.default.removeItem(at: url) }
+ }
+
+ let when = Date(timeIntervalSince1970: 1_700_000_000)
+ let nested = source.appendingPathComponent("a/b")
+ for url in [source, source.appendingPathComponent("a"), nested] {
+ try FileManager.default.setAttributes([.modificationDate: when], ofItemAtPath: url.path)
+ }
+
+ try VPhoneArchiveWriter.create(archive: archive, from: source)
+
+ for url in [source, source.appendingPathComponent("a"), nested] {
+ var info = stat()
+ #expect(lstat(url.path, &info) == 0)
+ #expect(info.st_mtimespec.tv_sec == Int(when.timeIntervalSince1970))
+ }
+ }
+
@Test("a single member can be read without unpacking")
func readMember() throws {
let source = try Self.makeTree()
diff --git a/tests/VPhoneCoreTests/BundleOpsTests.swift b/tests/VPhoneCoreTests/BundleOpsTests.swift
index 36cfd445..7280cbd6 100644
--- a/tests/VPhoneCoreTests/BundleOpsTests.swift
+++ b/tests/VPhoneCoreTests/BundleOpsTests.swift
@@ -2,6 +2,9 @@
import Foundation
import Testing
+/// Creating, editing, renaming and cloning a bundle. Export and import moved to
+/// `VPhoneArchiveTests/BundleTransferTests` with the implementation, which needs
+/// libarchive; this half does not.
struct BundleOpsTests {
private func makeRoot() throws -> URL {
let dir = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
@@ -312,373 +315,4 @@ struct BundleOpsTests {
_ = try VPhoneBundleOps.clone(bundleNamed: "a", to: "b", in: lib)
}
}
-
- @Test func exportThenImportRoundTrips() throws {
- let root = try makeRoot()
- defer { try? FileManager.default.removeItem(at: root) }
- let rom = try fakeROM(); let seprom = try fakeROM()
- defer { try? FileManager.default.removeItem(at: rom); try? FileManager.default.removeItem(at: seprom) }
- let lib = VPhoneLibrary(root: root)
- _ = try VPhoneBundleOps.create(
- .init(
- name: "orig",
- cpuCount: 8,
- memoryMB: 4096,
- diskSizeGB: 1,
- romSource: rom,
- sepromSource: seprom
- ),
- in: lib
- )
-
- let archive = root.appendingPathComponent("orig.tgz")
- try VPhoneBundleOps.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
- #expect(FileManager.default.fileExists(atPath: archive.path))
-
- // Import into a fresh library, renaming.
- let root2 = try makeRoot()
- defer { try? FileManager.default.removeItem(at: root2) }
- let lib2 = VPhoneLibrary(root: root2)
- let imported = try VPhoneBundleOps.importArchive(from: archive, name: "copy", in: lib2)
- #expect(imported.name == "copy")
- #expect(imported.manifest.cpuCount == 8)
- #expect(imported.manifest.memorySize == 4096 * 1024 * 1024)
- #expect(try lib2.bundle(named: "copy").manifest.cpuCount == 8)
- }
-
- @Test func importRejectsExistingName() throws {
- let root = try makeRoot()
- defer { try? FileManager.default.removeItem(at: root) }
- let rom = try fakeROM(); let seprom = try fakeROM()
- defer { try? FileManager.default.removeItem(at: rom); try? FileManager.default.removeItem(at: seprom) }
- let lib = VPhoneLibrary(root: root)
- _ = try VPhoneBundleOps.create(
- .init(
- name: "orig",
- cpuCount: 2,
- memoryMB: 2048,
- diskSizeGB: 1,
- romSource: rom,
- sepromSource: seprom
- ),
- in: lib
- )
- let archive = root.appendingPathComponent("orig.tgz")
- try VPhoneBundleOps.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
- // Importing back under the same existing name must fail.
- #expect(throws: VPhoneLibraryError.alreadyExists(name: "orig")) {
- _ = try VPhoneBundleOps.importArchive(from: archive, name: nil, in: lib)
- }
- }
-
- @Test func importWithRenameDoesNotClobberArchivedNameCollision() throws {
- let root = try makeRoot()
- defer { try? FileManager.default.removeItem(at: root) }
- let rom = try fakeROM(); let seprom = try fakeROM()
- defer { try? FileManager.default.removeItem(at: rom); try? FileManager.default.removeItem(at: seprom) }
- let lib = VPhoneLibrary(root: root)
- // Existing "orig" (cpu 16) that must NOT be touched by the import.
- _ = try VPhoneBundleOps.create(
- .init(
- name: "orig",
- cpuCount: 16,
- memoryMB: 2048,
- diskSizeGB: 1,
- romSource: rom,
- sepromSource: seprom
- ),
- in: lib
- )
- // Archive of a DIFFERENT "orig" (cpu 4) from a separate library.
- let root2 = try makeRoot()
- defer { try? FileManager.default.removeItem(at: root2) }
- let lib2 = VPhoneLibrary(root: root2)
- _ = try VPhoneBundleOps.create(
- .init(
- name: "orig",
- cpuCount: 4,
- memoryMB: 2048,
- diskSizeGB: 1,
- romSource: rom,
- sepromSource: seprom
- ),
- in: lib2
- )
- let archive = root2.appendingPathComponent("orig.tgz")
- try VPhoneBundleOps.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib2)
-
- let imported = try VPhoneBundleOps.importArchive(from: archive, name: "renamed", in: lib)
- #expect(imported.name == "renamed")
- #expect(imported.manifest.cpuCount == 4)
- #expect(try lib.bundle(named: "orig").manifest.cpuCount == 16) // untouched
- }
-
- @Test func exportExcludesRestoreDirByDefault() throws {
- let root = try makeRoot()
- defer { try? FileManager.default.removeItem(at: root) }
- let rom = try fakeROM(); let seprom = try fakeROM()
- defer { try? FileManager.default.removeItem(at: rom); try? FileManager.default.removeItem(at: seprom) }
- let lib = VPhoneLibrary(root: root)
- let b = try VPhoneBundleOps.create(
- .init(
- name: "orig",
- cpuCount: 2,
- memoryMB: 2048,
- diskSizeGB: 1,
- romSource: rom,
- sepromSource: seprom
- ),
- in: lib
- )
- let restoreDir = b.url.appendingPathComponent("iPhone_Restore")
- try FileManager.default.createDirectory(at: restoreDir, withIntermediateDirectories: true)
- try Data([0]).write(to: restoreDir.appendingPathComponent("marker"))
-
- let archive = root.appendingPathComponent("orig.tgz")
- try VPhoneBundleOps.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
- let listing = try VPhoneProcessRunner.runCapturing(URL(fileURLWithPath: "/usr/bin/tar"), ["-tf", archive.path])
- #expect(listing.succeeded)
- #expect(!listing.stdout.contains("iPhone_Restore"))
- }
-
- @Test func exportExcludesRegenerableStagingFiles() throws {
- let root = try makeRoot()
- defer { try? FileManager.default.removeItem(at: root) }
- let rom = try fakeROM(); let seprom = try fakeROM()
- defer { try? FileManager.default.removeItem(at: rom); try? FileManager.default.removeItem(at: seprom) }
- let lib = VPhoneLibrary(root: root)
- let b = try VPhoneBundleOps.create(
- .init(
- name: "orig",
- cpuCount: 2,
- memoryMB: 2048,
- diskSizeGB: 1,
- romSource: rom,
- sepromSource: seprom
- ),
- in: lib
- )
- let fm = FileManager.default
- try Data([0]).write(to: b.url.appendingPathComponent(".vphoned.signed"))
- try fm.createDirectory(at: b.url.appendingPathComponent("cfw_input/jb"), withIntermediateDirectories: true)
- try Data([0]).write(to: b.url.appendingPathComponent("cfw_input/jb/f"))
- try fm.createDirectory(at: b.url.appendingPathComponent("cfw_jb_input"), withIntermediateDirectories: true)
- try Data([0]).write(to: b.url.appendingPathComponent("cfw_jb_input/f"))
- try fm.createDirectory(at: b.url.appendingPathComponent(".cfw_temp"), withIntermediateDirectories: true)
- try Data([0]).write(to: b.url.appendingPathComponent(".cfw_temp/f"))
-
- let archive = root.appendingPathComponent("orig.tgz")
- try VPhoneBundleOps.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
- let listing = try VPhoneProcessRunner.runCapturing(URL(fileURLWithPath: "/usr/bin/tar"), ["-tf", archive.path])
- #expect(listing.succeeded)
- #expect(!listing.stdout.contains(".vphoned.signed"))
- #expect(!listing.stdout.contains("cfw_input"))
- #expect(!listing.stdout.contains("cfw_jb_input"))
- #expect(!listing.stdout.contains(".cfw_temp"))
- // The real payload still travels.
- #expect(listing.stdout.contains("Disk.img"))
- #expect(listing.stdout.contains("config.plist"))
- }
-
- @Test func importRejectsMultiTopLevelArchive() throws {
- let root = try makeRoot()
- defer { try? FileManager.default.removeItem(at: root) }
- // An archive with TWO top-level dirs is not a single bundle → badArchive.
- let src = root.appendingPathComponent("src")
- try FileManager.default.createDirectory(at: src.appendingPathComponent("a"), withIntermediateDirectories: true)
- try FileManager.default.createDirectory(at: src.appendingPathComponent("b"), withIntermediateDirectories: true)
- try Data([0]).write(to: src.appendingPathComponent("a/x"))
- try Data([0]).write(to: src.appendingPathComponent("b/y"))
- let archive = root.appendingPathComponent("multi.tgz")
- let made = try VPhoneProcessRunner.runCapturing(
- URL(fileURLWithPath: "/usr/bin/tar"),
- ["-czf", archive.path, "-C", src.path, "a", "b"]
- )
- #expect(made.succeeded)
-
- #expect(throws: VPhoneBundleOpsError.self) {
- _ = try VPhoneBundleOps.importArchive(from: archive, name: nil, in: VPhoneLibrary(root: root))
- }
- }
-
- @Test func importRejectsInvalidManifestWithoutReservingName() throws {
- let root = try makeRoot()
- defer { try? FileManager.default.removeItem(at: root) }
- let fm = FileManager.default
- let bundleDir = root.appendingPathComponent("original")
- try fm.createDirectory(at: bundleDir, withIntermediateDirectories: true)
- let config = bundleDir.appendingPathComponent("config.plist")
- try "not a plist".write(to: config, atomically: true, encoding: .utf8)
- let archive = root.appendingPathComponent("vm.tgz")
- let lib = VPhoneLibrary(root: root.appendingPathComponent("library"))
-
- func pack() throws {
- let result = try VPhoneProcessRunner.runCapturing(
- URL(fileURLWithPath: "/usr/bin/tar"),
- ["-czf", archive.path, "-C", root.path, "original"])
- try #require(result.succeeded)
- }
- try pack()
- #expect(throws: VPhoneManifestError.self) {
- _ = try VPhoneBundleOps.importArchive(from: archive, name: nil, in: lib)
- }
- // Neither a destination bundle nor a hidden staging directory may remain.
- #expect(try fm.contentsOfDirectory(atPath: lib.root.path).isEmpty)
-
- let manifest = VPhoneVirtualMachineManifest(
- cpuCount: 2, memorySize: 2048 * 1024 * 1024, romImages: nil)
- try manifest.write(to: config)
- try pack()
- let imported = try VPhoneBundleOps.importArchive(from: archive, name: nil, in: lib)
- #expect(imported.url == lib.url(forName: "original"))
- #expect(try lib.bundle(named: "original").manifest.cpuCount == 2)
- }
-
- // MARK: - Compression presets
-
- private static let zstdMagic: [UInt8] = [0x28, 0xB5, 0x2F, 0xFD]
- private static let xzMagic: [UInt8] = [0xFD, 0x37, 0x7A, 0x58, 0x5A, 0x00]
-
- private func magic(_ url: URL, _ n: Int) throws -> [UInt8] {
- Array(try Data(contentsOf: url).prefix(n))
- }
-
- private func exportAndImport(
- _ compression: VPhoneBundleOps.ExportCompression?
- ) throws -> (archive: URL, imported: VPhoneBundle) {
- let root = try makeRoot()
- let rom = try fakeROM(); let seprom = try fakeROM()
- let lib = VPhoneLibrary(root: root)
- _ = try VPhoneBundleOps.create(
- .init(
- name: "orig",
- cpuCount: 6,
- memoryMB: 2048,
- diskSizeGB: 1,
- romSource: rom,
- sepromSource: seprom
- ),
- in: lib
- )
- let archive = root.appendingPathComponent("orig.archive")
- if let compression {
- try VPhoneBundleOps.export(
- bundleNamed: "orig",
- to: archive,
- includeIPSW: false,
- compression: compression,
- in: lib
- )
- } else {
- try VPhoneBundleOps.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)
- }
- let dstRoot = try makeRoot()
- let imported = try VPhoneBundleOps.importArchive(from: archive, name: "copy", in: VPhoneLibrary(root: dstRoot))
- return (archive, imported)
- }
-
- @Test func exportDefaultsToFastZstd() throws {
- let (archive, imported) = try exportAndImport(nil)
- #expect(try magic(archive, 4) == Self.zstdMagic)
- #expect(imported.manifest.cpuCount == 6)
- }
-
- @Test func exportFastProducesZstdAndRoundTrips() throws {
- let (archive, imported) = try exportAndImport(.fast)
- #expect(try magic(archive, 4) == Self.zstdMagic)
- #expect(imported.manifest.cpuCount == 6)
- }
-
- @Test func exportMaxProducesXzAndRoundTrips() throws {
- let (archive, imported) = try exportAndImport(.max)
- #expect(try magic(archive, 6) == Self.xzMagic)
- #expect(imported.manifest.cpuCount == 6)
- }
-
- @Test func exportToDirectoryAutoNamesWithExtension() throws {
- let root = try makeRoot()
- let rom = try fakeROM(); let seprom = try fakeROM()
- let lib = VPhoneLibrary(root: root)
- _ = try VPhoneBundleOps.create(
- .init(
- name: "orig",
- cpuCount: 6,
- memoryMB: 2048,
- diskSizeGB: 1,
- romSource: rom,
- sepromSource: seprom
- ),
- in: lib
- )
- let outDir = try makeRoot()
- let zstdOut = try VPhoneBundleOps.export(
- bundleNamed: "orig",
- to: outDir,
- includeIPSW: false,
- in: lib
- )
- #expect(zstdOut == outDir.appendingPathComponent("orig.tzst"))
- #expect(FileManager.default.fileExists(atPath: zstdOut.path))
- let xzOut = try VPhoneBundleOps.export(
- bundleNamed: "orig",
- to: outDir,
- includeIPSW: false,
- compression: .max,
- in: lib
- )
- #expect(xzOut == outDir.appendingPathComponent("orig.txz"))
- #expect(FileManager.default.fileExists(atPath: xzOut.path))
- }
-
- @Test func exportAndImportReportProgress() throws {
- final class Collector {
- private(set) var dones: [Int64] = []
- private(set) var total: Int64 = 0
- func add(_ done: Int64, _ total: Int64) { dones.append(done); self.total = total }
- }
- let root = try makeRoot()
- defer { try? FileManager.default.removeItem(at: root) }
- let rom = try fakeROM(); let seprom = try fakeROM()
- let lib = VPhoneLibrary(root: root)
- _ = try VPhoneBundleOps.create(
- .init(
- name: "orig",
- cpuCount: 6,
- memoryMB: 2048,
- diskSizeGB: 1,
- romSource: rom,
- sepromSource: seprom
- ),
- in: lib
- )
-
- let exp = Collector()
- let archive = root.appendingPathComponent("orig.tzst")
- try VPhoneBundleOps.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib) {
- exp.add($0, $1)
- }
- #expect(!exp.dones.isEmpty)
- #expect(exp.total > 0) // bundle logical size
- #expect(exp.dones.last! > 0)
- #expect(exp.dones == exp.dones.sorted()) // monotonically non-decreasing
-
- let imp = Collector()
- let dstRoot = try makeRoot()
- defer { try? FileManager.default.removeItem(at: dstRoot) }
- _ = try VPhoneBundleOps.importArchive(from: archive, name: "copy", in: VPhoneLibrary(root: dstRoot)) {
- imp.add($0, $1)
- }
- let archiveSize = try Data(contentsOf: archive).count
- #expect(!imp.dones.isEmpty)
- #expect(imp.total == Int64(archiveSize)) // total == compressed file size
- #expect(imp.dones.last! == Int64(archiveSize)) // whole archive fed
- #expect(imp.dones == imp.dones.sorted())
- }
-
- @Test func compressionPresetTarArgs() {
- #expect(VPhoneBundleOps.ExportCompression.fast.tarArgs
- == ["--zstd", "--options", "zstd:compression-level=3,zstd:threads=0"])
- #expect(VPhoneBundleOps.ExportCompression.max.tarArgs
- == ["-J", "--options", "xz:compression-level=9,xz:threads=0"])
- }
}
diff --git a/tests/VPhoneSignTests/VPhoneSignBlobs.swift b/tests/VPhoneSignTests/VPhoneSignBlobs.swift
new file mode 100644
index 00000000..41ce3737
--- /dev/null
+++ b/tests/VPhoneSignTests/VPhoneSignBlobs.swift
@@ -0,0 +1,75 @@
+import Foundation
+
+/// The blobs of a signed file's embedded signature, per slice, read back with
+/// a parser that is not the one being tested.
+///
+/// It is separate from `VPhoneSign`'s own reader on purpose: a test that
+/// reads the output with the writer's own code checks that the code agrees
+/// with itself. This one starts from the Mach-O header and knows nothing
+/// about how the signature was put together.
+struct VPhoneSignBlobs {
+ /// One dictionary per slice, from slot to the blob's bytes, header
+ /// included.
+ let slices: [[UInt32: Data]]
+
+ init(fileAt url: URL) throws {
+ try self.init(data: Data(contentsOf: url))
+ }
+
+ init(data: Data) throws {
+ var slices: [[UInt32: Data]] = []
+ for range in Self.sliceRanges(data) {
+ let image = data.subdata(in: range)
+ guard let signature = Self.signatureRange(image) else {
+ slices.append([:])
+ continue
+ }
+ let blob = image.subdata(in: signature)
+ var found: [UInt32: Data] = [:]
+ let count = Int(Self.be32(blob, 8))
+ for index in 0 ..< count {
+ let slot = Self.be32(blob, 12 + index * 8)
+ let offset = Int(Self.be32(blob, 16 + index * 8))
+ let length = Int(Self.be32(blob, offset + 4))
+ found[slot] = blob.subdata(in: offset ..< offset + length)
+ }
+ slices.append(found)
+ }
+ self.slices = slices
+ }
+
+ // MARK: Walking the file
+
+ private static func be32(_ data: Data, _ offset: Int) -> UInt32 {
+ UInt32(bigEndian: data.withUnsafeBytes { $0.loadUnaligned(fromByteOffset: offset, as: UInt32.self) })
+ }
+
+ private static func le32(_ data: Data, _ offset: Int) -> UInt32 {
+ UInt32(littleEndian: data.withUnsafeBytes { $0.loadUnaligned(fromByteOffset: offset, as: UInt32.self) })
+ }
+
+ private static func sliceRanges(_ data: Data) -> [Range<Int>] {
+ guard data.count >= 8, le32(data, 0) == 0xBEBA_FECA else { return [0 ..< data.count] }
+ let count = Int(be32(data, 4))
+ return (0 ..< count).map {
+ let entry = 8 + $0 * 20
+ let offset = Int(be32(data, entry + 8))
+ return offset ..< offset + Int(be32(data, entry + 12))
+ }
+ }
+
+ private static func signatureRange(_ image: Data) -> Range<Int>? {
+ guard image.count >= 32 else { return nil }
+ var cursor = 32
+ for _ in 0 ..< Int(le32(image, 16)) {
+ let command = le32(image, cursor)
+ let size = Int(le32(image, cursor + 4))
+ if command == 0x1D { // LC_CODE_SIGNATURE
+ let offset = Int(le32(image, cursor + 8))
+ return offset ..< offset + Int(le32(image, cursor + 12))
+ }
+ cursor += size
+ }
+ return nil
+ }
+}
diff --git a/tests/VPhoneSignTests/VPhoneSignEntitlementsTests.swift b/tests/VPhoneSignTests/VPhoneSignEntitlementsTests.swift
new file mode 100644
index 00000000..8e50be10
--- /dev/null
+++ b/tests/VPhoneSignTests/VPhoneSignEntitlementsTests.swift
@@ -0,0 +1,279 @@
+import Foundation
+import Testing
+@testable import VPhoneSign
+
+/// Reading entitlements back, and the two things a signer must not get wrong
+/// about them: what libplist would have written, and what it would have
+/// refused.
+@Suite("Entitlements")
+struct VPhoneSignEntitlementsTests {
+ // MARK: - Dumping
+
+ /// `ldid -e`, which the installers use a dozen times over to carry a
+ /// binary's entitlements across a re-sign. It prints each slice's blob
+ /// one after another, so a fat file prints several and a file with none
+ /// prints nothing.
+ @Test("dump matches ldid -e byte for byte")
+ func dumpMatchesLdid() throws {
+ let ldid = try #require(VPhoneSignLdidHarness.ldid, "ldid is not installed")
+ // the ones with entitlements carry the interesting cases: a long
+ // sandbox profile in a <data>, arrays, integers, and several slices
+ let corpus = VPhoneSignLdidHarness.carryingEntitlements
+ .filter { FileManager.default.fileExists(atPath: $0) }
+ .map { URL(fileURLWithPath: $0) } + VPhoneSignLdidHarness.corpus
+ var withEntitlements = 0
+ for source in corpus {
+ let theirs = try VPhoneSignLdidHarness.run(ldid, ["-e", source.path]).out
+ let ours = try VPhoneSigner.entitlements(ofFileAt: source, usesExternalLdid: false)
+ .reduce(Data(), +)
+ #expect(theirs == ours, "\(source.lastPathComponent): \(theirs.count) vs \(ours.count) bytes")
+ if !theirs.isEmpty { withEntitlements += 1 }
+ }
+ #expect(withEntitlements > 0, "nothing in the corpus had entitlements, so nothing was compared")
+ }
+
+ @Test("a file this signed reads back the entitlements it was given")
+ func roundTrip() throws {
+ let source = try #require(VPhoneSignLdidHarness.corpus.first)
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let file = try VPhoneSignLdidHarness.copy(source, into: directory, as: "binary")
+ let plist = VPhoneSignParityTests.sampleEntitlements
+ try VPhoneSigner.sign(fileAt: file, options: .init(identifier: "binary", entitlements: plist))
+
+ let read = try VPhoneSigner.entitlements(ofFileAt: file, usesExternalLdid: false)
+ let slices = try VPhoneSignBlobs(fileAt: file).slices.count
+ #expect(read.count == slices)
+ // libplist rewrites the document it was given; what must survive is
+ // the list, so it is compared after a parse rather than as bytes
+ for blob in read {
+ let ours = try PropertyListSerialization.propertyList(from: blob, format: nil) as? [String: Any]
+ let original = try PropertyListSerialization.propertyList(from: plist, format: nil) as? [String: Any]
+ #expect(NSDictionary(dictionary: ours ?? [:]) == NSDictionary(dictionary: original ?? [:]))
+ }
+ }
+
+ // MARK: - What the writer must agree with libplist about
+
+ @Test("the XML writer keeps the order libplist keeps, not Foundation's")
+ func keepsInsertionOrder() throws {
+ // "b" before "a": Foundation would sort them, libplist would not, and
+ // the bytes are hashed into the signature
+ let plist = Data("""
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+ <plist version="1.0">
+ <dict>
+ \t<key>zeta</key>
+ \t<true/>
+ \t<key>alpha</key>
+ \t<true/>
+ </dict>
+ </plist>
+
+ """.utf8)
+ let entitlements = try VPhoneSignEntitlements(xml: plist)
+ let written = String(decoding: try entitlements.xml(), as: UTF8.self)
+ let zeta = try #require(written.range(of: "zeta"))
+ let alpha = try #require(written.range(of: "alpha"))
+ #expect(zeta.lowerBound < alpha.lowerBound, "the keys were sorted")
+ }
+
+ @Test("a merge replaces a key where it stands and appends a new one")
+ func mergeKeepsPositions() throws {
+ var base = try VPhoneSignEntitlements(xml: Data("""
+ <?xml version="1.0" encoding="UTF-8"?>
+ <plist version="1.0"><dict>
+ \t<key>first</key><string>old</string>
+ \t<key>second</key><true/>
+ </dict></plist>
+ """.utf8))
+ base.merge(try VPhoneSignEntitlements(xml: Data("""
+ <?xml version="1.0" encoding="UTF-8"?>
+ <plist version="1.0"><dict>
+ \t<key>first</key><string>new</string>
+ \t<key>third</key><true/>
+ </dict></plist>
+ """.utf8)))
+ #expect(base.entries.map(\.key) == ["first", "second", "third"])
+ #expect(base.entries[0].value == .string("new"))
+ }
+
+ /// The executable segment flags ldid derives. Getting these wrong is
+ /// silent: the binary signs, and then the guest refuses to debug it or
+ /// lets it do something it should not.
+ @Test("executable segment flags follow the entitlements")
+ func executableSegmentFlags() throws {
+ let entitlements = try VPhoneSignEntitlements(xml: Data("""
+ <?xml version="1.0" encoding="UTF-8"?>
+ <plist version="1.0"><dict>
+ \t<key>get-task-allow</key><true/>
+ \t<key>dynamic-codesigning</key><true/>
+ \t<key>com.apple.private.amfi.can-execute-cdhash</key><true/>
+ </dict></plist>
+ """.utf8))
+ #expect(entitlements.executableSegmentFlags(mainBinary: true) == 0x1 | 0x10 | 0x40 | 0x100)
+ #expect(entitlements.executableSegmentFlags(mainBinary: false) == 0x10 | 0x40 | 0x100)
+ }
+
+ // MARK: - <integer>, which is where the reader was wrong
+
+ /// Every spelling of an `<integer>` that ldid takes, compared against the
+ /// blobs ldid writes for it rather than against what this signer thinks
+ /// it should write.
+ ///
+ /// This is the test that was missing. The reader used to accept only a
+ /// positive decimal, justified by a comment saying ldid's DER "cannot
+ /// spell zero or a negative one" — and the suite pinned that in place by
+ /// asserting `<integer>0</integer>` must be refused, without ever asking
+ /// ldid. ldid spells zero `020100` and minus one `0208ffffffffffffffff`,
+ /// and `/usr/sbin/spindump` ships a zero, so the production path failed
+ /// on real input while the tests stayed green.
+ @Test(
+ "every <integer> ldid takes is carried the way ldid carries it",
+ arguments: [
+ "0", // 020100 — the one that broke spindump
+ "-1", // 0208ffffffffffffffff, the same bits as 2^64-1
+ "007", // strtoull in base 0: octal, so 7
+ "0x10", // and hex, so 16
+ "0777", // 511
+ "0X1F", // 31
+ "+42",
+ "-0",
+ "-0x10",
+ "1",
+ "42",
+ "128", // one byte with the top bit set, and no DER sign pad
+ "256", // two bytes
+ "2033844765", // as /usr/libexec/lsd carries it
+ "4014732562", // above Int32.max, as promotedcontentd carries it
+ "9223372036854775807", // Int64.max
+ "-9223372036854775808", // Int64.min
+ "9223372036854775808", // above Int64.max: libplist prints it unsigned
+ "18446744073709551615", // UInt64.max
+ " 42 ", // libplist skips the space around it
+ ]
+ )
+ func integerSpellingsMatchLdid(_ spelling: String) throws {
+ let ldid = try #require(VPhoneSignLdidHarness.ldid, "ldid is not installed")
+ let source = try #require(VPhoneSignLdidHarness.corpus.first)
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+
+ let plist = Data("""
+ <?xml version="1.0" encoding="UTF-8"?>
+ <plist version="1.0"><dict><key>k</key><integer>\(spelling)</integer></dict></plist>
+ """.utf8)
+ let file = directory.appendingPathComponent("entitlements.plist")
+ try plist.write(to: file)
+
+ let theirs = try VPhoneSignLdidHarness.copy(source, into: directory, as: "binary")
+ let result = try VPhoneSignLdidHarness.run(ldid, ["-S\(file.path)", theirs.path])
+ #expect(result.status == 0, "ldid refused <integer>\(spelling)</integer>: \(result.error)")
+
+ let ours = try VPhoneSignLdidHarness.copy(source, into: directory, as: "ours-binary")
+ try VPhoneSigner.sign(fileAt: ours, options: .init(identifier: "binary", entitlements: plist))
+
+ // the whole file, since a difference in either blob moves every
+ // CDHash with it; the two blobs are then named individually, because
+ // the DER drops the sign and the XML keeps it, so a reader that got
+ // one right could still have the other wrong
+ let whole = try Data(contentsOf: theirs), oursWhole = try Data(contentsOf: ours)
+ #expect(
+ whole == oursWhole,
+ "<integer>\(spelling)</integer>: \(VPhoneSignLdidHarness.difference(whole, oursWhole))"
+ )
+ let left = try VPhoneSignBlobs(fileAt: theirs), right = try VPhoneSignBlobs(fileAt: ours)
+ #expect(left.slices.count == right.slices.count)
+ for (index, pair) in zip(left.slices, right.slices).enumerated() {
+ // slot 5 is the XML the next `-M` reads back, slot 7 the DER AMFI reads
+ for slot in [UInt32(5), 7] {
+ #expect(pair.0[slot] != nil, "ldid wrote no slot \(slot)")
+ #expect(
+ pair.0[slot] == pair.1[slot],
+ """
+ <integer>\(spelling)</integer> slice \(index) slot \(slot): \
+ \(VPhoneSignLdidHarness.difference(pair.0[slot] ?? Data(), pair.1[slot] ?? Data()))
+ """
+ )
+ }
+ }
+ }
+
+ /// A list this signer cannot write back the way libplist would is
+ /// refused, rather than signed into something that grants the guest
+ /// different things from what the file said.
+ ///
+ /// ldid refuses both of these itself — `der(plist_t)` answers "Invalid
+ /// plist entry type" and exits 1 for `PLIST_REAL` and `PLIST_DATE` — so
+ /// the claim is checked against ldid here rather than asserted.
+ @Test(
+ "what ldid's DER has no room for is refused, as ldid refuses it",
+ arguments: ["<date>2020-01-01T00:00:00Z</date>", "<real>1.5</real>"]
+ )
+ func refusesWhatItCannotCarry(_ value: String) throws {
+ let plist = Data("""
+ <?xml version="1.0" encoding="UTF-8"?>
+ <plist version="1.0"><dict><key>k</key>\(value)</dict></plist>
+ """.utf8)
+ #expect(throws: VPhoneSignError.self) {
+ _ = try VPhoneSignEntitlements(xml: plist)
+ }
+
+ let ldid = try #require(VPhoneSignLdidHarness.ldid, "ldid is not installed")
+ let source = try #require(VPhoneSignLdidHarness.corpus.first)
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let file = directory.appendingPathComponent("entitlements.plist")
+ try plist.write(to: file)
+ let binary = try VPhoneSignLdidHarness.copy(source, into: directory, as: "binary")
+ let result = try VPhoneSignLdidHarness.run(ldid, ["-S\(file.path)", binary.path])
+ #expect(result.status != 0, "ldid accepted \(value), so refusing it is wrong")
+ }
+
+ /// The spellings the two libplists read differently.
+ ///
+ /// Every released libplist — 2.3 through the 2.7 the shipped ldid links —
+ /// reads an `<integer>` with `strtoull(str, NULL, 0)` and checks nothing
+ /// after it, so it takes each of these and produces a number. libplist's
+ /// master branch added the checks that make all of them parse errors.
+ /// Refusing is the side that cannot seal a number the next ldid would
+ /// have refused to write, and none of these is a shape a real
+ /// entitlements list has. `--1` is the odd one out: both libplists read
+ /// it as 1, and it is refused anyway because nothing writes it.
+ ///
+ /// No claim about the installed ldid is made here: it accepts these
+ /// today. That is the point of refusing them.
+ @Test(
+ "an <integer> the two libplists disagree about is refused",
+ arguments: [
+ "42abc", // released reads 42; master stops on the trailing text
+ "abc", // released reads 0
+ "", // an empty tag: released reads 0, master refuses it
+ "08", // released reads 0 and stops on the 8, octal having no 8
+ "99999999999999999999999", // released clamps to ULLONG_MAX on ERANGE
+ "-18446744073709551615", // released wraps it; master calls it out of range
+ "0x", // a hex prefix with no digits: released reads the 0 and stops
+ "--1", // the one both agree on and this refuses anyway; see integer(_:)
+ ]
+ )
+ func refusesWhatTwoLibplistsReadDifferently(_ spelling: String) throws {
+ let plist = Data("""
+ <?xml version="1.0" encoding="UTF-8"?>
+ <plist version="1.0"><dict><key>k</key><integer>\(spelling)</integer></dict></plist>
+ """.utf8)
+ #expect(throws: VPhoneSignError.self) {
+ _ = try VPhoneSignEntitlements(xml: plist)
+ }
+ }
+
+ @Test("a binary plist is refused rather than read as XML")
+ func refusesABinaryPlist() throws {
+ let binary = try PropertyListSerialization.data(
+ fromPropertyList: ["k": true], format: .binary, options: 0
+ )
+ #expect(throws: VPhoneSignError.self) {
+ _ = try VPhoneSignEntitlements(xml: binary)
+ }
+ }
+}
diff --git a/tests/VPhoneSignTests/VPhoneSignIdentityTests.swift b/tests/VPhoneSignTests/VPhoneSignIdentityTests.swift
new file mode 100644
index 00000000..14b508ac
--- /dev/null
+++ b/tests/VPhoneSignTests/VPhoneSignIdentityTests.swift
@@ -0,0 +1,210 @@
+import Foundation
+import Testing
+@testable import VPhoneSign
+
+/// `-K`: signing with the repository's own `signcert.p12`.
+///
+/// The whole file cannot match ldid's, because a CMS carries a signing time.
+/// It is only the content that differs: the CMS blob comes out the same
+/// length as ldid's on every slice measured (4711 against 4711, 4792 against
+/// 4792), and the signed files are the same size to the byte, because both
+/// signers reserve `cmsReservation` and pad what is left. What must match is
+/// the CodeDirectory, and it is the only part that has to: everything AMFI
+/// seals is in there, and the CDHash is computed over it. The CMS is then
+/// held to a verifier nobody here wrote.
+@Suite("VPhoneSign signs with a PKCS#12")
+struct VPhoneSignIdentityTests {
+ /// The certificate this repository signs its guest daemon with. It is
+ /// checked in, wrapped with no password, and expired in 2018 — none of
+ /// which matters to a device whose AMFI this project patched, and all of
+ /// which matters to how it has to be read.
+ static var p12: URL {
+ URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+ .appendingPathComponent("scripts/vphoned/signcert.p12")
+ }
+
+ private func identity() throws -> VPhoneSignIdentity {
+ try #require(FileManager.default.fileExists(atPath: Self.p12.path), "signcert.p12 is not in the tree")
+ return try VPhoneSignIdentity(pkcs12: Data(contentsOf: Self.p12), password: "")
+ }
+
+ /// `SecPKCS12Import` cannot do this: it answers `errSecAuthFailed` for an
+ /// empty password. That is the entire reason the container is opened by
+ /// hand.
+ @Test("the repository's PKCS#12 opens with no password")
+ func opensWithoutAPassword() throws {
+ let identity = try identity()
+ #expect(identity.teamIdentifier == "DQF6PC5T2P")
+ #expect(identity.commonName == "iPhone Distribution: jiu de (DQF6PC5T2P)")
+ }
+
+ @Test("a wrong password is refused, not worked around")
+ func refusesAWrongPassword() throws {
+ try #require(FileManager.default.fileExists(atPath: Self.p12.path))
+ let data = try Data(contentsOf: Self.p12)
+ #expect(throws: VPhoneSignError.self) {
+ _ = try VPhoneSignIdentity(pkcs12: data, password: "not the password")
+ }
+ }
+
+ /// The hard gate for `-K`: the CodeDirectories are ldid's, byte for byte.
+ @Test("every CodeDirectory matches ldid -K")
+ func codeDirectoriesMatchLdid() throws {
+ let ldid = try #require(VPhoneSignLdidHarness.ldid, "ldid is not installed")
+ let identity = try identity()
+ for source in VPhoneSignLdidHarness.corpus {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+
+ let theirs = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ let result = try VPhoneSignLdidHarness.run(ldid, ["-S", "-M", "-K\(Self.p12.path)", theirs.path])
+ #expect(result.status == 0, "ldid -K \(name): \(result.error)")
+
+ let ours = try VPhoneSignLdidHarness.copy(source, into: directory, as: "ours-\(name)")
+ try VPhoneSigner.sign(fileAt: ours, options: .init(
+ identifier: name, mergesExisting: true, identity: identity
+ ))
+
+ let left = try VPhoneSignBlobs(fileAt: theirs), right = try VPhoneSignBlobs(fileAt: ours)
+ #expect(left.slices.count == right.slices.count, "\(name): different slice counts")
+ for (index, pair) in zip(left.slices, right.slices).enumerated() {
+ for slot in [UInt32(0), 0x1000] where pair.0[slot] != nil || pair.1[slot] != nil {
+ #expect(
+ pair.0[slot] == pair.1[slot],
+ "\(name) slice \(index) slot 0x\(String(slot, radix: 16)): CodeDirectory differs"
+ )
+ }
+ // the designated requirement carries the leaf's common name
+ // under -K, so it is part of the same claim
+ #expect(pair.0[2] == pair.1[2], "\(name) slice \(index): requirements differ")
+ }
+ }
+ }
+
+ /// The seal, checked by `codesign --verify`, which is an action and not
+ /// the verbosity flag that `-d -vvv` turns out to be.
+ ///
+ /// Both signers pass outright, entitlements or not: `codesign --verify`
+ /// exits 0 and prints "satisfies its Designated Requirement" for ldid's
+ /// output and for this one. An earlier note here said the DR clause fails
+ /// for both whenever entitlements are present, because ldid compiles a DR
+ /// naming a leaf that expired in 2018. That does not reproduce in any
+ /// configuration tried — `--verify` does not build a trust chain, so the
+ /// expiry never comes into it — so the run is asserted rather than only
+ /// compared against ldid's.
+ @Test("codesign --verify accepts the seal, with entitlements and without")
+ func codesignVerifiesTheSeal() throws {
+ let ldid = try #require(VPhoneSignLdidHarness.ldid, "ldid is not installed")
+ let identity = try identity()
+ let codesign = URL(fileURLWithPath: "/usr/bin/codesign")
+ // the corpus's first files carry no entitlements and
+ // `carryingEntitlements` is the half that does, which is the case the
+ // old note claimed was different
+ // Filter before the prefix, not after. The other order takes the first
+ // four names and *then* drops the missing ones, so a machine without
+ // one of lsd/sshd/trustd/pkd quietly shrinks the entitlement-carrying
+ // half — possibly to nothing — and the test still passes.
+ let entitled = VPhoneSignLdidHarness.carryingEntitlements
+ .filter { FileManager.default.fileExists(atPath: $0) }
+ .prefix(4)
+ .map { URL(fileURLWithPath: $0) }
+ #expect(entitled.count == 4, "expected four entitlement-carrying binaries, found \(entitled.count)")
+ let corpus = VPhoneSignLdidHarness.corpus.prefix(4) + entitled
+ for source in corpus {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+
+ let theirs = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ let seal = try VPhoneSignLdidHarness.run(ldid, ["-S", "-M", "-K\(Self.p12.path)", theirs.path])
+ #expect(seal.status == 0, "ldid -S -M -K \(name): \(seal.error)")
+ let ours = try VPhoneSignLdidHarness.copy(source, into: directory, as: "ours-\(name)")
+ try VPhoneSigner.sign(fileAt: ours, options: .init(
+ identifier: name, mergesExisting: true, identity: identity
+ ))
+
+ let mine = try VPhoneSignLdidHarness.run(codesign, ["--verify", "--no-strict", "-vvv", ours.path])
+ let theirsResult = try VPhoneSignLdidHarness.run(codesign, ["--verify", "--no-strict", "-vvv", theirs.path])
+ #expect(theirsResult.status == 0, "ldid's own output: \(theirsResult.error)")
+ #expect(mine.status == 0, "\(name): \(mine.error)")
+ #expect(mine.error.contains("valid on disk"), "\(name): \(mine.error)")
+ #expect(
+ mine.error.contains("satisfies its Designated Requirement"),
+ "\(name): ours [\(mine.error)] ldid [\(theirsResult.error)]"
+ )
+ }
+ }
+
+ /// The two files are the same size, and their CMS blobs are the same
+ /// length; only the bytes inside differ, where the signing time lives.
+ ///
+ /// This is here because the opposite was written down — that this
+ /// signer's CMS runs eight bytes longer than ldid's — and a CMS that
+ /// really was longer would be a real problem: the reservation is fixed,
+ /// so overflowing it would move the `__LINKEDIT` size in the load
+ /// commands and change every CDHash.
+ @Test("the CMS is the same length as ldid's, and so is the file")
+ func cmsIsTheSameLengthAsLdids() throws {
+ let ldid = try #require(VPhoneSignLdidHarness.ldid, "ldid is not installed")
+ let identity = try identity()
+ for source in VPhoneSignLdidHarness.corpus.prefix(8) {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+
+ let theirs = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ _ = try VPhoneSignLdidHarness.run(ldid, ["-S", "-M", "-K\(Self.p12.path)", theirs.path])
+ let ours = try VPhoneSignLdidHarness.copy(source, into: directory, as: "ours-\(name)")
+ try VPhoneSigner.sign(fileAt: ours, options: .init(
+ identifier: name, mergesExisting: true, identity: identity
+ ))
+
+ #expect(
+ try Data(contentsOf: theirs).count == Data(contentsOf: ours).count,
+ "\(name): the signed files are different sizes"
+ )
+ let left = try VPhoneSignBlobs(fileAt: theirs), right = try VPhoneSignBlobs(fileAt: ours)
+ for (index, pair) in zip(left.slices, right.slices).enumerated() {
+ let mine = try #require(pair.1[0x10000], "\(name) slice \(index) has no CMS")
+ let theirs = try #require(pair.0[0x10000], "\(name) slice \(index): ldid wrote no CMS")
+ #expect(mine.count == theirs.count, "\(name) slice \(index): \(mine.count) vs \(theirs.count)")
+ }
+ }
+ }
+
+ /// The gate that is real evidence rather than a display: a verifier from
+ /// outside this project, over the bytes this project signed. `-noverify`
+ /// skips building a trust chain, which would fail on an expired leaf and
+ /// says nothing about whether the signature is sound.
+ @Test("openssl cms -verify accepts the signature")
+ func opensslVerifiesTheCMS() throws {
+ let openssl = try #require(VPhoneSignLdidHarness.which("openssl"), "openssl is not installed")
+ let identity = try identity()
+ for source in VPhoneSignLdidHarness.corpus.prefix(6) {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+ let ours = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ try VPhoneSigner.sign(fileAt: ours, options: .init(identifier: name, identity: identity))
+
+ let blobs = try VPhoneSignBlobs(fileAt: ours)
+ for (index, slice) in blobs.slices.enumerated() {
+ let cms = try #require(slice[0x10000], "\(name) slice \(index) has no CMS blob")
+ let directoryBlob = try #require(slice[0], "\(name) slice \(index) has no CodeDirectory")
+ let cmsFile = directory.appendingPathComponent("cms-\(index).der")
+ let contentFile = directory.appendingPathComponent("cd-\(index).bin")
+ // the blob wrapper's own 8-byte header is not part of the CMS
+ try cms.dropFirst(8).write(to: cmsFile)
+ try directoryBlob.write(to: contentFile)
+
+ let result = try VPhoneSignLdidHarness.run(openssl, [
+ "cms", "-verify", "-inform", "DER", "-in", cmsFile.path,
+ "-content", contentFile.path, "-noverify", "-binary", "-out", "/dev/null",
+ ])
+ #expect(result.status == 0, "\(name) slice \(index): openssl said \(result.error)")
+ }
+ }
+ }
+}
diff --git a/tests/VPhoneSignTests/VPhoneSignLdidHarness.swift b/tests/VPhoneSignTests/VPhoneSignLdidHarness.swift
new file mode 100644
index 00000000..5792c7de
--- /dev/null
+++ b/tests/VPhoneSignTests/VPhoneSignLdidHarness.swift
@@ -0,0 +1,167 @@
+import Foundation
+import Testing
+
+/// Running the real `ldid` and holding this signer's output against it.
+///
+/// The bar for `VPhoneSign` is not "the signature verifies" — ldid's own
+/// ad-hoc output does not verify, because it sets no ad-hoc flag and writes
+/// no CMS blob, and the guest's AMFI takes it anyway. The bar is that the
+/// bytes are the same, which is the only claim that carries over to a
+/// patched AMFI nobody here can re-derive. So these tests need ldid, and
+/// skip rather than pretend when it is not installed.
+enum VPhoneSignLdidHarness {
+ /// Where Homebrew's ldid is, or nil. Its absence skips the comparisons;
+ /// it must never make them pass.
+ static let ldid: URL? = {
+ for candidate in ["/opt/homebrew/bin/ldid", "/usr/local/bin/ldid"] {
+ if FileManager.default.isExecutableFile(atPath: candidate) {
+ return URL(fileURLWithPath: candidate)
+ }
+ }
+ return which("ldid")
+ }()
+
+ static func which(_ name: String) -> URL? {
+ let process = Process()
+ process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
+ process.arguments = ["which", name]
+ let pipe = Pipe()
+ process.standardOutput = pipe
+ process.standardError = FileHandle.nullDevice
+ guard (try? process.run()) != nil else { return nil }
+ let data = pipe.fileHandleForReading.readDataToEndOfFile()
+ process.waitUntilExit()
+ let path = String(decoding: data, as: UTF8.self).trimmingCharacters(in: .whitespacesAndNewlines)
+ return process.terminationStatus == 0 && !path.isEmpty ? URL(fileURLWithPath: path) : nil
+ }
+
+ /// The Mach-O files to compare on. System binaries cover the shapes this
+ /// signer has to get right and nothing else on the machine does: fat
+ /// files, several architectures, a deployment target old enough that
+ /// ldid drops SHA-1, and one new enough that it does not. The built
+ /// products are the thin arm64 case.
+ static var corpus: [URL] {
+ let candidates = [
+ "/bin/ls", // fat, and minos 10.14 on x86_64: ldid writes SHA-256 only
+ "/bin/cat", // fat, minos 27.0: ldid writes both
+ "/bin/echo",
+ "/usr/bin/true",
+ "/usr/bin/grep",
+ "/usr/bin/head",
+ ] + carryingEntitlements + toolchainLibraries + built
+ return candidates
+ .filter { FileManager.default.fileExists(atPath: $0) }
+ .map { URL(fileURLWithPath: $0) }
+ }
+
+ /// Binaries that already carry entitlements, which is what `-M` has to
+ /// re-serialise. They are listed apart because a corpus of files with no
+ /// entitlements makes every merge test pass without merging anything.
+ ///
+ /// The `<integer>` spellings are the reason for most of this list: an
+ /// earlier reader here took only a positive decimal, so a merge over
+ /// `spindump` — whose
+ /// `com.apple.trial.status.deployment-environment.allow` is
+ /// `<array><integer>0</integer></array>` — failed where ldid completed.
+ /// `promotedcontentd` is above `Int32.max`, `runningboardd` carries two
+ /// different values, and `sysdiagnose_helper` carries six.
+ static var carryingEntitlements: [String] {
+ [
+ "/usr/libexec/lsd", // carries __TEXT,__info_plist and entitlements
+ "/usr/sbin/sshd",
+ "/usr/libexec/trustd",
+ "/usr/libexec/pkd",
+ "/usr/sbin/spindump", // <integer>0</integer>
+ "/usr/libexec/sysdiagnose_helper",
+ "/usr/libexec/runningboardd",
+ "/usr/libexec/promotedcontentd",
+ "/usr/libexec/seserviced",
+ "/usr/libexec/tailspind",
+ "/usr/bin/tailspin",
+ "/usr/sbin/cfprefsd",
+ "/usr/sbin/securityd",
+ "/usr/libexec/opendirectoryd",
+ "/usr/bin/shortcuts",
+ ]
+ }
+
+ /// Dylibs rather than programs, which differ in the executable segment
+ /// flags and in whether the main-binary bit is set. The system's own are
+ /// in the shared cache and not on disk; the toolchain's are real files.
+ static var toolchainLibraries: [String] {
+ let toolchain = "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib"
+ let names = ["libLTO.dylib", "libswiftDemangle.dylib", "libcodedirectory.dylib"]
+ guard let installed = try? FileManager.default.contentsOfDirectory(atPath: "/Applications") else {
+ return names.map { "\(toolchain)/\($0)" }
+ }
+ // whichever Xcode is installed, including a versioned one beside it
+ return installed.filter { $0.hasPrefix("Xcode") }.flatMap { application in
+ names.map {
+ "/Applications/\(application)/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/\($0)"
+ }
+ }
+ }
+
+ /// This project's own binaries, when they have been built. `vphoned` is
+ /// the one that matters most: it is iOS arm64, cross-compiled, and the
+ /// binary the guest actually loads.
+ static var built: [String] {
+ let root = URL(fileURLWithPath: #filePath)
+ .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+ return [root.appendingPathComponent("scripts/vphoned/vphoned").path]
+ + ["vphone-letmein", "vphone-archive", "vphone-vm", "vphone-cli"].flatMap { name in
+ ["release", "debug"].map { root.appendingPathComponent(".build/\($0)/\(name)").path }
+ }
+ }
+
+ // MARK: Running things
+
+ @discardableResult
+ static func run(_ tool: URL, _ arguments: [String]) throws -> (status: Int32, out: Data, error: String) {
+ let process = Process()
+ process.executableURL = tool
+ process.arguments = arguments
+ let out = Pipe(), error = Pipe()
+ process.standardOutput = out
+ process.standardError = error
+ try process.run()
+ // read before waiting: a pipe that fills would deadlock the child
+ let output = out.fileHandleForReading.readDataToEndOfFile()
+ let diagnostics = error.fileHandleForReading.readDataToEndOfFile()
+ process.waitUntilExit()
+ return (process.terminationStatus, output, String(decoding: diagnostics, as: UTF8.self))
+ }
+
+ /// A directory that goes away with the test.
+ static func temporaryDirectory() throws -> URL {
+ let url = FileManager.default.temporaryDirectory
+ .appendingPathComponent("vphone-sign-\(UUID().uuidString)")
+ try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+ return url
+ }
+
+ /// `source` copied in as `name`, since ldid signs under the file's name
+ /// and both sides have to be called the same thing.
+ static func copy(_ source: URL, into directory: URL, as name: String) throws -> URL {
+ let url = directory.appendingPathComponent(name)
+ try? FileManager.default.removeItem(at: url)
+ try FileManager.default.copyItem(at: source, to: url)
+ return url
+ }
+
+ /// Where two files first differ, for a failure message worth reading.
+ static func difference(_ left: Data, _ right: Data) -> String {
+ guard left != right else { return "identical" }
+ let shared = min(left.count, right.count)
+ for offset in 0 ..< shared where left[offset] != right[offset] {
+ let window = offset ..< min(offset + 16, shared)
+ return """
+ \(left.count) vs \(right.count) bytes, first difference at \(offset) \
+ (0x\(String(offset, radix: 16))): \
+ \(left[window].map { String(format: "%02x", $0) }.joined()) vs \
+ \(right[window].map { String(format: "%02x", $0) }.joined())
+ """
+ }
+ return "\(left.count) vs \(right.count) bytes, identical up to the shorter one"
+ }
+}
diff --git a/tests/VPhoneSignTests/VPhoneSignParityTests.swift b/tests/VPhoneSignTests/VPhoneSignParityTests.swift
new file mode 100644
index 00000000..f3056334
--- /dev/null
+++ b/tests/VPhoneSignTests/VPhoneSignParityTests.swift
@@ -0,0 +1,292 @@
+import Foundation
+import Testing
+@testable import VPhoneSign
+
+/// The hard gate: what this signer writes and what `ldid` writes are the
+/// same bytes.
+///
+/// Byte equality is the bar rather than "the signature verifies" because the
+/// signature's own size lands in the load commands, which are hashed — one
+/// byte of slack more than ldid reserves and every CDHash is different. It
+/// is also the only bar that carries: the device this signs for runs an AMFI
+/// this project patched, and what that accepts cannot be re-derived from
+/// first principles. It accepts ldid's bytes.
+@Suite("VPhoneSign is byte-identical to ldid")
+struct VPhoneSignParityTests {
+ private var ldid: URL {
+ get throws {
+ try #require(VPhoneSignLdidHarness.ldid, "ldid is not installed; install ldid-procursus to run the parity gate")
+ }
+ }
+
+ // MARK: - Ad-hoc, which is nearly every call
+
+ @Test("ldid -S")
+ func adHoc() throws {
+ let ldid = try ldid
+ let corpus = VPhoneSignLdidHarness.corpus
+ // a corpus that shrank to nothing would make every one of these pass
+ #expect(corpus.count >= 10, "only \(corpus.count) files: too few to say anything")
+ #expect(
+ corpus.contains { (try? Data(contentsOf: $0).prefix(4)) == Data([0xCA, 0xFE, 0xBA, 0xBE]) },
+ "no fat binary in the corpus"
+ )
+ for source in corpus {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+
+ let theirs = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ let result = try VPhoneSignLdidHarness.run(ldid, ["-S", theirs.path])
+ #expect(result.status == 0, "ldid -S \(name): \(result.error)")
+
+ let ours = try VPhoneSignLdidHarness.copy(source, into: directory, as: "ours-\(name)")
+ try VPhoneSigner.sign(fileAt: ours, options: .init(identifier: name))
+
+ let left = try Data(contentsOf: theirs), right = try Data(contentsOf: ours)
+ #expect(left == right, "\(name): \(VPhoneSignLdidHarness.difference(left, right))")
+ }
+ }
+
+ // MARK: - Entitlements
+
+ @Test("ldid -S<entitlements>")
+ func entitlements() throws {
+ let ldid = try ldid
+ for source in VPhoneSignLdidHarness.corpus {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+ let plist = directory.appendingPathComponent("entitlements.plist")
+ try Self.sampleEntitlements.write(to: plist)
+
+ let theirs = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ let result = try VPhoneSignLdidHarness.run(ldid, ["-S\(plist.path)", theirs.path])
+ #expect(result.status == 0, "ldid -S<ent> \(name): \(result.error)")
+
+ let ours = try VPhoneSignLdidHarness.copy(source, into: directory, as: "ours-\(name)")
+ try VPhoneSigner.sign(fileAt: ours, options: .init(
+ identifier: name, entitlements: Self.sampleEntitlements
+ ))
+
+ let left = try Data(contentsOf: theirs), right = try Data(contentsOf: ours)
+ #expect(left == right, "\(name): \(VPhoneSignLdidHarness.difference(left, right))")
+ }
+ }
+
+ /// `-M` over a list written for the occasion, so that the merge itself is
+ /// pinned: a key replaced where it stood and a key appended after it,
+ /// which a system binary's own entitlements cannot be relied on to
+ /// contain. The unseeded case — a binary's own list, which is what the
+ /// installers actually merge over — is `mergedWithoutAFile` and
+ /// `mergedOverOwnEntitlements`.
+ @Test("ldid -S<entitlements> -M over a seeded signature")
+ func merged() throws {
+ let ldid = try ldid
+ for source in VPhoneSignLdidHarness.corpus {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+
+ // give the file entitlements to merge over, with ldid, so the
+ // starting point is not this signer's own work
+ let seed = directory.appendingPathComponent("seed.plist")
+ try Self.seedEntitlements.write(to: seed)
+ let seeded = try VPhoneSignLdidHarness.copy(source, into: directory, as: "seeded-\(name)")
+ _ = try VPhoneSignLdidHarness.run(ldid, ["-S\(seed.path)", seeded.path])
+
+ let plist = directory.appendingPathComponent("entitlements.plist")
+ try Self.sampleEntitlements.write(to: plist)
+
+ let theirs = try VPhoneSignLdidHarness.copy(seeded, into: directory, as: name)
+ let result = try VPhoneSignLdidHarness.run(ldid, ["-S\(plist.path)", "-M", theirs.path])
+ #expect(result.status == 0, "ldid -S<ent> -M \(name): \(result.error)")
+
+ let ours = try VPhoneSignLdidHarness.copy(seeded, into: directory, as: "ours-\(name)")
+ try VPhoneSigner.sign(fileAt: ours, options: .init(
+ identifier: name, entitlements: Self.sampleEntitlements, mergesExisting: true
+ ))
+
+ let left = try Data(contentsOf: theirs), right = try Data(contentsOf: ours)
+ #expect(left == right, "\(name): \(VPhoneSignLdidHarness.difference(left, right))")
+ }
+ }
+
+ /// `ldid_sign` in `cfw_install*.sh` is `-S -M` with no entitlements file
+ /// at all: whatever the binary already had is re-serialised and kept.
+ ///
+ /// The file is signed as it came off disk, with no fixture written over
+ /// it first. That is the whole point. Seeding a binary with an
+ /// author-written plist makes the merge input a list this signer is
+ /// already known to read, which is how twenty-eight green tests once sat
+ /// beside a production path that aborted on `/usr/sbin/spindump` — its
+ /// `<integer>0</integer>` was a shape the fixtures never had. What the
+ /// firmware's own binaries carry is the only input this has to survive.
+ @Test("ldid -S -M over a binary's own entitlements, which is what cfw_install calls")
+ func mergedWithoutAFile() throws {
+ let ldid = try ldid
+ var merged = 0
+ for source in VPhoneSignLdidHarness.corpus {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+
+ let theirs = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ let result = try VPhoneSignLdidHarness.run(ldid, ["-S", "-M", theirs.path])
+ #expect(result.status == 0, "ldid -S -M \(name): \(result.error)")
+
+ let ours = try VPhoneSignLdidHarness.copy(source, into: directory, as: "ours-\(name)")
+ try VPhoneSigner.sign(fileAt: ours, options: .init(identifier: name, mergesExisting: true))
+
+ let left = try Data(contentsOf: theirs), right = try Data(contentsOf: ours)
+ #expect(left == right, "\(name): \(VPhoneSignLdidHarness.difference(left, right))")
+ if try VPhoneSigner.entitlements(ofFileAt: source, usesExternalLdid: false).isEmpty == false {
+ merged += 1
+ }
+ }
+ // a corpus of files with no entitlements merges nothing and passes
+ #expect(merged >= 8, "only \(merged) files carried entitlements to merge")
+ }
+
+ /// The same, with an entitlements file on top: `ldid -S<ent> -M <file>`
+ /// over what the binary already carried, which is what the installers
+ /// run when they add a key rather than only re-sign.
+ @Test("ldid -S<entitlements> -M over a binary's own entitlements")
+ func mergedOverOwnEntitlements() throws {
+ let ldid = try ldid
+ var merged = 0
+ for path in VPhoneSignLdidHarness.carryingEntitlements
+ where FileManager.default.fileExists(atPath: path)
+ {
+ merged += 1
+ let source = URL(fileURLWithPath: path)
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+ let plist = directory.appendingPathComponent("entitlements.plist")
+ try Self.sampleEntitlements.write(to: plist)
+
+ let theirs = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ let result = try VPhoneSignLdidHarness.run(ldid, ["-S\(plist.path)", "-M", theirs.path])
+ #expect(result.status == 0, "ldid -S<ent> -M \(name): \(result.error)")
+
+ let ours = try VPhoneSignLdidHarness.copy(source, into: directory, as: "ours-\(name)")
+ try VPhoneSigner.sign(fileAt: ours, options: .init(
+ identifier: name, entitlements: Self.sampleEntitlements, mergesExisting: true
+ ))
+
+ let left = try Data(contentsOf: theirs), right = try Data(contentsOf: ours)
+ #expect(left == right, "\(name): \(VPhoneSignLdidHarness.difference(left, right))")
+ }
+ // Without this the loop body can never run — every path missing on
+ // some future macOS — and the test passes having compared nothing.
+ // Its sibling `mergedWithoutAFile` carries the same guard.
+ #expect(merged >= 8, "only \(merged) of the entitlement-carrying binaries exist here")
+ }
+
+ /// `-I`, which a handful of call sites use to sign under an Apple
+ /// identifier (`com.apple.seputil` and friends) rather than the file's
+ /// name.
+ @Test("ldid -I<identifier>")
+ func explicitIdentifier() throws {
+ let ldid = try ldid
+ for source in VPhoneSignLdidHarness.corpus.prefix(4) {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+
+ let theirs = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ let result = try VPhoneSignLdidHarness.run(ldid, ["-S", "-Icom.apple.seputil", theirs.path])
+ #expect(result.status == 0, "ldid -I \(name): \(result.error)")
+
+ let ours = try VPhoneSignLdidHarness.copy(source, into: directory, as: "ours-\(name)")
+ try VPhoneSigner.sign(fileAt: ours, options: .init(identifier: "com.apple.seputil"))
+
+ let left = try Data(contentsOf: theirs), right = try Data(contentsOf: ours)
+ #expect(left == right, "\(name): \(VPhoneSignLdidHarness.difference(left, right))")
+ }
+ }
+
+ /// Signing twice must land on the same bytes, or a rebuild of the CFW
+ /// would produce a different image every time.
+ @Test("signing an already-signed file is idempotent")
+ func idempotent() throws {
+ for source in VPhoneSignLdidHarness.corpus {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+ let file = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ let once = try VPhoneSigner.sign(fileAt: file, options: .init(identifier: name))
+ let twice = try VPhoneSigner.sign(fileAt: file, options: .init(identifier: name))
+ #expect(once == twice, "\(name): \(VPhoneSignLdidHarness.difference(once, twice))")
+ }
+ }
+
+ // MARK: - Fixtures
+
+ /// Covers what the DER and XML writers have to agree with libplist on:
+ /// booleans, a nested array of strings, a `<data>` long enough to wrap,
+ /// and integers — including the four spellings that the DER and the XML
+ /// disagree about. `-1` and `18446744073709551615` are the same eight
+ /// bytes in the DER and two different strings in the XML; `0` is one zero
+ /// byte and not an empty INTEGER. A fixture whose only integer was `42`
+ /// is what let the reader ship taking positive decimals only.
+ static let sampleEntitlements = Data("""
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+ <plist version="1.0">
+ <dict>
+ \t<key>platform-application</key>
+ \t<true/>
+ \t<key>com.apple.private.security.no-sandbox</key>
+ \t<true/>
+ \t<key>get-task-allow</key>
+ \t<true/>
+ \t<key>com.apple.private.skip-library-validation</key>
+ \t<true/>
+ \t<key>com.apple.security.exception.files.absolute-path.read-only</key>
+ \t<array>
+ \t\t<string>/usr/lib/</string>
+ \t\t<string>/System/</string>
+ \t</array>
+ \t<key>seatbelt-profiles</key>
+ \t<data>
+ \tAQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyAhIiMkJSYnKCkqKywtLi8w
+ \tMTIzNDU2Nzg5Ojs8PT4/QEFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaW1xdXl9g
+ \t</data>
+ \t<key>an-integer</key>
+ \t<integer>42</integer>
+ \t<key>a-zero</key>
+ \t<integer>0</integer>
+ \t<key>a-negative</key>
+ \t<integer>-1</integer>
+ \t<key>above-int64-max</key>
+ \t<integer>18446744073709551615</integer>
+ \t<key>an-array-of-integers</key>
+ \t<array>
+ \t\t<integer>0</integer>
+ \t\t<integer>128</integer>
+ \t\t<integer>9223372036854775808</integer>
+ \t</array>
+ </dict>
+ </plist>
+
+ """.utf8)
+
+ /// A different set, so a merge that silently dropped one side would show.
+ static let seedEntitlements = Data("""
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+ <plist version="1.0">
+ <dict>
+ \t<key>com.apple.private.cs.debugger</key>
+ \t<true/>
+ \t<key>an-existing-key</key>
+ \t<string>kept</string>
+ \t<key>get-task-allow</key>
+ \t<false/>
+ </dict>
+ </plist>
+
+ """.utf8)
+}
diff --git a/tests/VPhoneSignTests/VPhoneSignStyleTests.swift b/tests/VPhoneSignTests/VPhoneSignStyleTests.swift
new file mode 100644
index 00000000..9964134d
--- /dev/null
+++ b/tests/VPhoneSignTests/VPhoneSignStyleTests.swift
@@ -0,0 +1,185 @@
+import Foundation
+import Testing
+@testable import VPhoneSign
+
+/// The Apple-shaped ad-hoc signature, the escape hatch, and what happens to a
+/// file that is not a Mach-O.
+@Suite("Signature styles and failure")
+struct VPhoneSignStyleTests {
+ /// `codesign --verify` rejects ldid's ad-hoc output — no ad-hoc flag, no
+ /// CMS blob — and rejects this signer's `.ldid` output for the same two
+ /// reasons, which is the point. `.appleAdHoc` is the shape it accepts,
+ /// kept for anything that has to satisfy the host rather than the guest.
+ @Test("the Apple ad-hoc style passes codesign --verify")
+ func appleAdHocVerifies() throws {
+ let codesign = URL(fileURLWithPath: "/usr/bin/codesign")
+ for source in VPhoneSignLdidHarness.corpus {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+ let file = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ try VPhoneSigner.sign(fileAt: file, options: .init(identifier: name, style: .appleAdHoc))
+
+ let result = try VPhoneSignLdidHarness.run(codesign, ["--verify", "-vvv", file.path])
+ #expect(result.status == 0, "\(name): \(result.error)")
+ #expect(result.error.contains("valid on disk"), "\(name): \(result.error)")
+ }
+ }
+
+ @Test("the Apple ad-hoc style sets the flag and writes the empty wrapper")
+ func appleAdHocShape() throws {
+ let source = try #require(VPhoneSignLdidHarness.corpus.first)
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let file = try VPhoneSignLdidHarness.copy(source, into: directory, as: "binary")
+ try VPhoneSigner.sign(fileAt: file, options: .init(identifier: "binary", style: .appleAdHoc))
+
+ for slice in try VPhoneSignBlobs(fileAt: file).slices {
+ let directoryBlob = try #require(slice[0])
+ // CodeDirectory.flags is the fourth big-endian word
+ let flags = UInt32(bigEndian: directoryBlob.withUnsafeBytes {
+ $0.loadUnaligned(fromByteOffset: 12, as: UInt32.self)
+ })
+ #expect(flags == 0x2, "the ad-hoc flag is not set")
+ #expect(slice[0x10000]?.count == 8, "the empty CMS wrapper is missing")
+ #expect(slice[2]?.count == 12, "the requirements blob is not empty")
+ #expect(slice[0x1000] == nil, "an Apple ad-hoc signature has one CodeDirectory")
+ }
+ }
+
+ // MARK: - The escape hatch
+
+ /// The flags `--use-ldid` hands over have to be the same request, or the
+ /// fallback quietly signs something else.
+ @Test("the ldid arguments match the options")
+ func ldidArguments() {
+ #expect(VPhoneLdid.arguments(
+ for: .init(identifier: nil), entitlementsPath: nil, identityPath: nil
+ ) == ["-S"])
+ #expect(VPhoneLdid.arguments(
+ for: .init(identifier: "com.apple.seputil", mergesExisting: true),
+ entitlementsPath: nil, identityPath: "/tmp/signcert.p12"
+ ) == ["-S", "-M", "-K/tmp/signcert.p12", "-Icom.apple.seputil"])
+ #expect(VPhoneLdid.arguments(
+ for: .init(entitlements: Data([1]), mergesExisting: true),
+ entitlementsPath: "/tmp/e.plist", identityPath: nil
+ ) == ["-S/tmp/e.plist", "-M"])
+ }
+
+ /// Handing ldid an identity it cannot see would sign ad-hoc and say
+ /// nothing, which is the one way a fallback is worse than no fallback.
+ @Test("--use-ldid refuses an identity it was not given the .p12 for")
+ func escapeHatchRefusesAnIdentityWithoutItsFile() throws {
+ try #require(VPhoneSignLdidHarness.ldid != nil, "ldid is not installed")
+ let identity = try VPhoneSignIdentity(
+ pkcs12: Data(contentsOf: VPhoneSignIdentityTests.p12), password: ""
+ )
+ let source = try #require(VPhoneSignLdidHarness.corpus.first)
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let file = try VPhoneSignLdidHarness.copy(source, into: directory, as: "binary")
+ #expect(throws: VPhoneSignError.self) {
+ try VPhoneSigner.sign(fileAt: file, options: .init(
+ identifier: "binary", identity: identity, usesExternalLdid: true
+ ))
+ }
+ }
+
+ /// Going through the external tool must land on the same file, or the
+ /// fallback is not a fallback.
+ @Test("--use-ldid produces what signing here produces")
+ func escapeHatchAgrees() throws {
+ try #require(VPhoneSignLdidHarness.ldid != nil, "ldid is not installed")
+ for source in VPhoneSignLdidHarness.corpus.prefix(4) {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let name = source.lastPathComponent
+
+ let viaLdid = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
+ try VPhoneSigner.sign(fileAt: viaLdid, options: .init(
+ identifier: name, entitlements: VPhoneSignParityTests.sampleEntitlements,
+ usesExternalLdid: true
+ ))
+ let here = try VPhoneSignLdidHarness.copy(source, into: directory, as: "here-\(name)")
+ try VPhoneSigner.sign(fileAt: here, options: .init(
+ identifier: name, entitlements: VPhoneSignParityTests.sampleEntitlements,
+ usesExternalLdid: false
+ ))
+
+ let left = try Data(contentsOf: viaLdid), right = try Data(contentsOf: here)
+ #expect(left == right, "\(name): \(VPhoneSignLdidHarness.difference(left, right))")
+ }
+ }
+
+ // MARK: - Refusing rather than corrupting
+
+ @Test("a file that is not a Mach-O is refused")
+ func refusesSomethingElse() throws {
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let file = directory.appendingPathComponent("script.sh")
+ try Data("#!/bin/sh\necho hello\n".utf8).write(to: file)
+ #expect(throws: VPhoneSignError.self) {
+ try VPhoneSigner.sign(fileAt: file, options: .init(identifier: "script.sh"))
+ }
+ // and it is still the file it was
+ #expect(try Data(contentsOf: file) == Data("#!/bin/sh\necho hello\n".utf8))
+ }
+
+ @Test("a truncated Mach-O is refused rather than signed over garbage")
+ func refusesATruncatedMachO() throws {
+ let source = try #require(VPhoneSignLdidHarness.corpus.first { $0.path.hasPrefix("/bin") })
+ let whole = try Data(contentsOf: source)
+ #expect(throws: VPhoneSignError.self) {
+ _ = try VPhoneSigner.sign(whole.prefix(whole.count / 3), options: .init(identifier: "x"))
+ }
+ }
+
+ /// A Java class file opens with the four bytes of a fat Mach-O. Reading
+ /// the next two as an architecture count is how a signer ends up writing
+ /// over something it does not understand.
+ @Test("something that only starts like a fat Mach-O is refused")
+ func refusesAJavaClass() throws {
+ var file = Data([0xCA, 0xFE, 0xBA, 0xBE, 0x00, 0x00, 0x00, 0x41])
+ file.append(Data(count: 512))
+ #expect(throws: VPhoneSignError.self) {
+ _ = try VPhoneSigner.sign(file, options: .init(identifier: "x"))
+ }
+ }
+
+ /// `sign(_:options:)` takes any `Data`, and a slice of one keeps its
+ /// parent's indices. Every offset in the signer counts from the start of
+ /// the file, so a slice that starts anywhere else has to be handled
+ /// before the first byte is read.
+ @Test("a Data slice that does not start at zero signs the same as a copy")
+ func signsANonZeroBasedSlice() throws {
+ let source = try #require(VPhoneSignLdidHarness.corpus.first)
+ let whole = try Data(contentsOf: source)
+ let padded = Data(count: 7) + whole
+ let slice = padded[7...]
+ #expect(slice.startIndex == 7, "the slice was rebased, so this proves nothing")
+ let fromSlice = try VPhoneSigner.sign(slice, options: .init(identifier: "x"))
+ let fromCopy = try VPhoneSigner.sign(whole, options: .init(identifier: "x"))
+ #expect(fromSlice == fromCopy)
+ }
+
+ /// Signing a read-only file is the normal case, not the exception:
+ /// everything unpacked out of an IPSW is mode 444, and the whole CFW
+ /// pipeline signs those in place.
+ @Test("a read-only file is signed and keeps its mode")
+ func signsAReadOnlyFile() throws {
+ let source = try #require(VPhoneSignLdidHarness.corpus.first)
+ let directory = try VPhoneSignLdidHarness.temporaryDirectory()
+ defer { try? FileManager.default.removeItem(at: directory) }
+ let file = try VPhoneSignLdidHarness.copy(source, into: directory, as: "binary")
+ try FileManager.default.setAttributes([.posixPermissions: 0o444], ofItemAtPath: file.path)
+
+ try VPhoneSigner.sign(fileAt: file, options: .init(identifier: "binary"))
+ let mode = try FileManager.default.attributesOfItem(atPath: file.path)[.posixPermissions] as? NSNumber
+ #expect(mode?.int16Value == 0o444)
+ #expect(try VPhoneSignBlobs(fileAt: file).slices.allSatisfy { $0[0] != nil })
+ // nothing left beside it
+ let left = try FileManager.default.contentsOfDirectory(atPath: directory.path)
+ #expect(left == ["binary"], "a temporary was left behind: \(left)")
+ }
+}
diff --git a/tests/test_dropbear_plist.py b/tests/test_dropbear_plist.py
deleted file mode 100644
index 4006cf39..00000000
--- a/tests/test_dropbear_plist.py
+++ /dev/null
@@ -1,60 +0,0 @@
-#!/usr/bin/env python3
-"""Unit tests for CFW LaunchDaemon plist rewrites."""
-
-import os
-import sys
-import unittest
-
-
-ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-sys.path.insert(0, os.path.join(ROOT, "scripts"))
-
-from patchers.cfw_daemons import DROPBEAR_KEY_ARGS, patch_dropbear_daemon # noqa: E402
-
-
-class DropbearPlistTests(unittest.TestCase):
- def test_rewrites_readonly_root_key_generation(self):
- daemon = {
- "ProgramArguments": [
- "/iosbinpack64/usr/local/bin/dropbear",
- "--shell",
- "/iosbinpack64/bin/bash",
- "-R",
- "-E",
- "-F",
- "-p",
- "22222",
- "-a",
- ]
- }
-
- patch_dropbear_daemon(daemon)
-
- args = daemon["ProgramArguments"]
- self.assertNotIn("-R", args)
- self.assertEqual(args[-len(DROPBEAR_KEY_ARGS):], DROPBEAR_KEY_ARGS)
-
- def test_replaces_stale_explicit_key_paths(self):
- daemon = {
- "ProgramArguments": [
- "dropbear",
- "-r",
- "/etc/dropbear/dropbear_rsa_host_key",
- "-E",
- "-r",
- "/tmp/old_ecdsa_key",
- "-p",
- "22222",
- ]
- }
-
- patch_dropbear_daemon(daemon)
-
- args = daemon["ProgramArguments"]
- self.assertNotIn("/etc/dropbear/dropbear_rsa_host_key", args)
- self.assertNotIn("/tmp/old_ecdsa_key", args)
- self.assertEqual(args, ["dropbear", "-E", "-p", "22222", *DROPBEAR_KEY_ARGS])
-
-
-if __name__ == "__main__":
- unittest.main()