Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

feat(cfw): finish the CFW verbs and delete scripts/patchers

Lakrd90371a3d392
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index cce6feb2..8b4f508f 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -2,7 +2,7 @@ name: release
# Build the portable, signed vphone-cli.app and attach it to a published
# GitHub Release. Uses ./scripts/build.sh (the canonical build) so the .app
-# ships self-contained — bundled scripts/patchers/resources/requirements.txt/
+# ships self-contained — bundled scripts/resources/requirements.txt/
# vphoned/.tools — not the lean `make bundle` output. Signing is ad-hoc
# (codesign --sign -) with sources/vphone.entitlements; no secrets required.
@@ -23,8 +23,10 @@ jobs:
- name: Init submodules
# vendor/* (--recursive: libcapstone-spm builds capstone from its own
# nested submodule) for the Swift build; scripts/resources is the CFW
- # asset storage that build.sh bundles into the .app; scripts/repos/*
- # provide the trustcache/insert_dylib tool sources.
+ # asset storage that build.sh bundles into the .app; scripts/repos/trustcache
+ # provides the trustcache tool source. scripts/repos/insert_dylib is
+ # deliberately NOT initialised: nothing in the product runs it, it is only
+ # the local parity reference for CFWMachOTests.matchesInsertDylib.
run: |
git submodule update --init --recursive --depth 1 \
vendor/swift-argument-parser \
@@ -33,8 +35,7 @@ jobs:
vendor/libimg4-spm \
vendor/MachOKit \
scripts/resources \
- scripts/repos/trustcache \
- scripts/repos/insert_dylib
+ scripts/repos/trustcache
- name: Toolchain versions
run: |
@@ -44,10 +45,13 @@ jobs:
- name: Install build deps
run: brew install ldid-procursus openssl@3
- - name: Build .tools/bin/{trustcache,insert_dylib}
- # build.sh bundles these runtime tools into the .app and errors if
- # absent. Mirrors scripts/setup_tools.sh steps [2/4] and [3/4]; its
- # venv ([4/4]) and sshpass ([1/4]) steps aren't needed to build.
+ - name: Build .tools/bin/trustcache
+ # The one runtime tool build.sh still bundles into the .app; it errors
+ # if absent. Mirrors scripts/setup_tools.sh step [2/4]; its venv ([4/4])
+ # and sshpass ([1/4]) steps aren't needed to build.
+ # insert_dylib ([3/4]) is deliberately not built here: `cfw inject-dylib`
+ # writes the load command in process, so the binary is only the parity
+ # reference CFWMachOTests compares against — a test this job never runs.
run: |
set -euo pipefail
mkdir -p .tools/bin
@@ -58,8 +62,6 @@ jobs:
LDFLAGS="-L${openssl_prefix}/lib" \
-j"$(sysctl -n hw.logicalcpu)"
cp scripts/repos/trustcache/trustcache .tools/bin/trustcache
- clang -o .tools/bin/insert_dylib \
- scripts/repos/insert_dylib/insert_dylib/main.c -framework Security -O2
- name: Build and bundle (portable .app)
run: ./scripts/build.sh
@@ -68,8 +70,8 @@ jobs:
run: |
set -euo pipefail
res=.build/vphone-cli.app/Contents/Resources
- for p in scripts/fw_prepare.sh scripts/patchers/cfw.py scripts/resources \
- requirements.txt vphoned.signed .tools/bin/trustcache .tools/bin/insert_dylib; do
+ for p in scripts/fw_prepare.sh scripts/cfw_install.sh scripts/resources \
+ requirements.txt vphoned.signed .tools/bin/trustcache; do
[ -e "$res/$p" ] || { echo "::error::bundle is missing $p — not portable"; exit 1; }
done
bin=.build/vphone-cli.app/Contents/MacOS/vphone-cli
diff --git a/AGENTS.md b/AGENTS.md
index 23cffb22..c9679b37 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,10 +8,10 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc
- **Boot (GUI):** `make boot`
- **Boot (DFU):** `make boot_dfu`
- **All targets:** `make help`
-- **Python venv:** `make setup_venv` (installs to `.venv/`, activate with `source .venv/bin/activate`)
+- **Python venv:** `make setup_venv` (installs to `.venv/`, activate with `source .venv/bin/activate`). Needed only for `make restore*` — `scripts/pymobiledevice3_bridge.py` is the one Python program left. The patch pipeline never touches it.
- **Platform:** macOS 15+ (Sequoia), SIP/AMFI disabled
- **Language:** Swift 6.0 (SwiftPM), private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic)
-- **Python deps:** `capstone`, `keystone-engine`, `pyimg4` (see `requirements.txt`)
+- **Python deps:** `typer`, `pymobiledevice3`, `ipsw-parser` (see `requirements.txt`) — the restore bridge's, and nothing else's
## Workflow Rules
@@ -147,10 +147,9 @@ sources/
├── VPhoneTouchIDMonitor.swift # BiometricKit delegate sink
└── VPhoneScreenRecorder.swift # VM screen recording to file
-scripts/
+scripts/ # Shell only — the CFW patchers are `vphone-cli cfw <verb>` now
├── vphoned/ # Guest daemon (ObjC, runs inside iOS VM over vsock)
-├── patchers/ # Python CFW patcher modules
-│ └── cfw.py # CFW binary patcher entrypoint
+├── pymobiledevice3_bridge.py # The ONE remaining Python program (restore); needs .venv
├── resources/ # Resource archives (git submodule)
├── repos/ # Toolchain source repos (git submodules: trustcache, insert_dylib)
├── fw_prepare.sh # Download IPSWs, merge cloudOS into iPhone
@@ -168,7 +167,7 @@ scripts/
cfw-kit/ # Variant-layered CFW installer, vendored as-is
├── run.sh # Entry point
-├── lib/ # common.sh (cfw_py / ldid_sign / $TAR seams), base_stages.sh
+├── lib/ # common.sh (cfw_cli / ldid_sign / $TAR seams), base_stages.sh
├── vanilla/ jb/ # Per-flavour install.sh; jb/userland/* are empty slots
└── docs/phase-matrix.md
@@ -208,21 +207,30 @@ research/ # Detailed firmware/patch documentation
- Use `zsh` with `set -euo pipefail`.
- Scripts resolve their own directory via `${0:a:h}` or `$(cd "$(dirname "$0")" && pwd)`.
+### Patchers
+
+Every patcher is Swift, in `sources/FirmwarePatcher`. The boot chain and kernel
+run through `patch-firmware`; the CFW/DSC patchers are `vphone-cli cfw <verb>`,
+one verb per patch, driven by `scripts/cfw_install*.sh` and `cfw-kit/`.
+
+- Disassembly is Capstone via `ARM64Disassembler` (`vendor/libcapstone-spm`). Assembly is `ARM64Encoder` plus the pre-encoded constants in `ARM64` (`ARM64Constants.swift`) — together they replace keystone's `asm()` / `asm_at()`, and `ARM64.nop` / `ARM64.movW0_0` are the old `NOP` / `MOV_W0_0`. IM4P containers go through `IM4PHandler` (`vendor/libimg4-spm`), which replaces pyimg4.
+- Dynamic pattern finding (string anchors, ADRP+ADD xrefs, BL frequency) — no hardcoded offsets.
+- Each patch logged with offset and before/after state.
+- No interpreter, no venv, no native-library repair: `make build` is the whole toolchain.
+
### Python Scripts
+- One program is left: `scripts/pymobiledevice3_bridge.py`, the restore backend. Use the project venv (`source .venv/bin/activate`); create it with `make setup_venv`.
+- Do not add a second one. A patch, a probe or a format reader belongs in Swift, where it is built, signed and tested with everything else.
+
### Kernel patcher guardrails
- For kernel patchers, never hardcode file offsets, virtual addresses, or preassembled instruction bytes inside patch logic.
-- All instruction matching must be derived from Capstone decode results (mnemonic / operands / control-flow), not exact operand-string text when a semantic operand check is possible.
-- All replacement instruction bytes must come from Keystone-backed helpers already used by the project (for example `asm(...)`, `NOP`, `MOV_W0_0`, etc.).
+- All instruction matching must be derived from Capstone decode results (mnemonic / operands / control-flow), not exact operand-string text when a semantic operand check is possible. `ARM64Disassembler` is the only decoder — match on the decoded mnemonic and operand detail, never on a formatted operand string.
+- All replacement instruction bytes must come from Keystone-backed helpers already used by the project: `ARM64Encoder.encode*` and the `ARM64` constants, which were generated by keystone-engine, verified by Capstone round-trip, and are asserted word for word against keystone in `tests/FirmwarePatcherTests/ARM64EncoderTests.swift`. Never write a literal instruction word at a patch site. A new instruction means a new encoder plus its keystone-checked test case, not a raw `Data`. Keystone is deliberately **not** a project dependency any more — nothing at runtime or in the test suite calls it, and the expected words are frozen constants. To derive a new one, build it a throwaway environment: `brew install keystone && python3 -m venv /tmp/ks && /tmp/ks/bin/pip install keystone-engine`, then the one-liner in that test file's header. Do not add it back to `requirements.txt` or the venv, and do not invent an expected word without checking it.
- Prefer source-backed semantic anchors: in-image symbol lookup, string xrefs, local call-flow, and XNU correlation. Do not depend on repo-exported per-kernel symbol dumps at runtime.
- When retargeting a patch, write the reveal procedure and validation steps into the relevant research doc or commit notes before handing off for testing. Do not create `TODO.md`.
-- For `patch_bsd_init_auth` specifically, the allowed reveal flow is: recover `bsd_init` -> locate rootvp panic block -> find the unique in-function `call` -> `cbnz w0/x0, panic` -> `bl imageboot_needed` site -> patch the branch gate only.
-
-- Patchers use `capstone` (disassembly), `keystone-engine` (assembly), `pyimg4` (IM4P handling).
-- Dynamic pattern finding (string anchors, ADRP+ADD xrefs, BL frequency) — no hardcoded offsets.
-- Each patch logged with offset and before/after state.
-- Use project venv (`source .venv/bin/activate`). Create with `make setup_venv`.
+- For `patchBsdInitAuth` (`Kernel/JBPatches/Storage/KernelJBPatchBsdInitAuth.swift`, named `patch_bsd_init_auth` in the research docs) specifically, the allowed reveal flow is: recover `bsd_init` -> locate rootvp panic block -> find the unique in-function `call` -> `cbnz w0/x0, panic` -> `bl imageboot_needed` site -> patch the branch gate only.
## Build & Sign
diff --git a/Makefile b/Makefile
index 0d9baeef..41f31499 100644
--- a/Makefile
+++ b/Makefile
@@ -50,6 +50,10 @@ BUNDLE_LETMEIN := $(BUNDLE)/Contents/MacOS/vphone-letmein
BUNDLE_ARCHIVE := $(BUNDLE)/Contents/MacOS/vphone-archive
INFO_PLIST := sources/Info.plist
ENTITLEMENTS := sources/vphone.entitlements
+# The venv exists for exactly one program now — the pymobiledevice3 restore
+# bridge below. The firmware and CFW patchers it used to serve are Swift
+# (FirmwarePatcher, reached through `vphone-cli cfw <verb>` and `patch-firmware`),
+# so nothing in the patch pipeline touches $(PYTHON) any more.
VENV := .venv
TOOLS_PREFIX := .tools
PMD3_BRIDGE := $(CURDIR)/$(SCRIPTS)/pymobiledevice3_bridge.py
@@ -84,6 +88,7 @@ help:
@echo ""
@echo "Setup (one-time):"
@echo " make setup_tools Install all tools (brew, trustcache, insert_dylib, venv+pymobiledevice3)"
+ @echo " make setup_venv The venv alone — needed only for 'make restore*' (pymobiledevice3)"
@echo ""
@echo "Build:"
@echo " make build Build + sign vphone-cli"
diff --git a/README.md b/README.md
index 1c09736b..85cf97c6 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ Boot a virtual iPhone via Apple's Virtualization.framework using PCC research VM
**Dependencies:**
```bash
-brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd
+brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass libusb ipsw zstd
```
## Install
diff --git a/cfw-kit/README.md b/cfw-kit/README.md
index a6c58893..90a3ba69 100644
--- a/cfw-kit/README.md
+++ b/cfw-kit/README.md
@@ -12,8 +12,8 @@ base install path.
| `launchd.plist` | untouched | untouched |
| userland | yours to design | slot: `rootless` / `roothide`, both empty |
-The kit does **not** fork the Python patchers. It calls the repo's
-`scripts/patchers/cfw.py`, so patch behaviour cannot drift from upstream.
+The kit does **not** fork the patchers. It calls the repo's built
+`vphone-cli cfw <verb>`, so patch behaviour cannot drift from upstream.
It does not modify the vphone-cli repo at all.
## Use
@@ -29,7 +29,8 @@ cd ~/Documents/GitHub/Lakr233/vphone-cli && make fw_patch # or fw_patch_jb
`run.sh` re-execs itself under `sudo` (owners-honoured mounts need root),
attaches `Disk.img`, runs the variant installer against the mounted volumes,
-then flips the boot snapshot offline via the repo's `tools/apfs_snap_rename.py`.
+then flips the boot snapshot offline via the repo's `vphone-cli cfw
+flip-snapshot`.
Check what would happen without touching anything — **no root, no attach, no
writes**:
@@ -46,7 +47,7 @@ KIT_CHECK_ONLY=1 ./run.sh --variant jb
| `VANILLA_LSD_EMBEDDED_REG` | `0` | vanilla, 27 bases: open lsd's JB app-registration path |
| `FORCE_DSC_MAXSLIDE` | `0` | zero maxSlide on non-27 bases (normally self-gated to a no-op) |
| `KIT_CHECK_ONLY` | `0` | preflight and stop |
-| `VPHONE_REPO` / `--repo` | auto | vphone-cli checkout to take `cfw.py` and resources from |
+| `VPHONE_REPO` / `--repo` | auto | vphone-cli checkout to take the built `vphone-cli` and the resources from |
| `VPHONE_DROP_ARTIFACTS` | `0` | delete the extracted `cfw_input/` afterwards |
## Layout
@@ -68,9 +69,11 @@ the two binaries in the GPU bundle come from; this kit only installs them.
**Preflight is the only safety net.** The installer streams onto a mounted
volume with no snapshot to roll back to, so everything that can fail is checked
-before the first write: tools, Python deps, and every `cfw.py` subcommand this
-variant *and its userland slot* will call. A userland flavour is sourced before
-preflight precisely so its requirements get checked too.
+before the first write: tools, the built binary, and every `cfw` subcommand this
+variant *and its userland slot* will call — each one asked of the binary itself
+(`vphone-cli cfw <sub> --help`), not pattern-matched out of a source file. A
+userland flavour is sourced before preflight precisely so its requirements get
+checked too.
**`umount` is never forced.** If something still holds a file on the volume the
kit wants to hear about it, not paper over it with `umount -f`
@@ -89,12 +92,8 @@ Full reasoning in `docs/phase-matrix.md`.
Done, and repeatable:
- `zsh -n` on all five scripts
-- `KIT_CHECK_ONLY=1` preflight actually executed for both variants, and for
- vanilla with the lsd flag on — all pass on this host
-- all 12 `cfw.py` subcommands the kit can call confirmed present
- payload paths confirmed present: `cfw_input/signcert.p12`,
- `cfw_input/custom/AppleParavirtGPUMetalIOGPUFamily.tar`,
- `campo_mach_lookup_exceptions.py`, `tools/apfs_snap_rename.py`
+ `cfw_input/custom/AppleParavirtGPUMetalIOGPUFamily.tar`
- slot contract exercised with a throwaway flavour: `REQUIRED_CFW_SUBCOMMANDS`
appends reach preflight, `USERLAND_MODIFIES_LAUNCHD_PLIST=1` pulls in
`patch-launchd-cache-loader`, and a flavour demanding a nonexistent
@@ -102,6 +101,12 @@ Done, and repeatable:
- `run.sh` error paths: missing `--variant`, unknown variant, unknown
`JB_USERLAND`, empty slot
+**Not re-run since the patchers moved into `vphone-cli`:**
+
+- the `KIT_CHECK_ONLY=1` preflight. It no longer greps a Python file for verb
+ names; it asks the binary (`vphone-cli cfw <sub> --help`). Run it for both
+ variants, and for vanilla with the lsd flag on, before trusting the kit again.
+
**Not done — no VM was available on the authoring host:**
- no real install has ever run
diff --git a/cfw-kit/docs/phase-matrix.md b/cfw-kit/docs/phase-matrix.md
index cd6fe49b..eb3439fa 100644
--- a/cfw-kit/docs/phase-matrix.md
+++ b/cfw-kit/docs/phase-matrix.md
@@ -78,10 +78,11 @@ Legend: ✅ installed · ❌ not installed · ⬜ left to the userland slot or a
(`SystemVersion.plist` does not exist before that).
4. **Preflight before any write.** Upstream discovers a missing `zstd` or a
- stale `cfw.py` partway through a streaming install onto a volume with no
- snapshot to roll back to. `preflight()` checks tools, Python deps and every
- `cfw.py` subcommand the selected variant *and its userland slot* will call,
- then refuses with nothing written.
+ stale `vphone-cli` partway through a streaming install onto a volume with no
+ snapshot to roll back to. `preflight()` checks tools, the built binary and
+ every `cfw` subcommand the selected variant *and its userland slot* will
+ call — each asked of the binary itself with `--help`, which exits 0 only for
+ a verb it really has — then refuses with nothing written.
5. **`run.sh` requires `--variant`.** Upstream `cfw_install_host.sh` defaults to
`exp`. Defaulting to either variant here would hand someone a firmware they
diff --git a/cfw-kit/jb/install.sh b/cfw-kit/jb/install.sh
index 60d48c3e..39d79475 100755
--- a/cfw-kit/jb/install.sh
+++ b/cfw-kit/jb/install.sh
@@ -49,10 +49,13 @@ REQUIRED_CFW_SUBCOMMANDS=(
patch-lsd-embedded-reg
patch-diskimagesiod
patch-launchd-jetsam
+ # J3's Campo fix. It was a standalone Python script outside the preflight's
+ # reach; as a cfw verb it is checked with the rest.
+ patch-campo-entitlements
)
REPO_DIR="$(resolve_repo)"
-PYTHON3="$(resolve_python3)"
+VPHONE_CLI="$(resolve_vphone_cli)"
init_paths
cleanup_on_exit() {
@@ -107,7 +110,7 @@ mkdir -p "$TEMP_DIR"
echo ""
echo "[*] Parsing iPhone BuildManifest for Cryptex paths..."
-CRYPTEX_PATHS=$(cfw_py cryptex-paths "$RESTORE_DIR/iPhone-BuildManifest.plist")
+CRYPTEX_PATHS=$(cfw_cli cryptex-paths "$RESTORE_DIR/iPhone-BuildManifest.plist")
CRYPTEX_SYSOS=$(echo "$CRYPTEX_PATHS" | head -1)
CRYPTEX_APPOS=$(echo "$CRYPTEX_PATHS" | tail -1)
echo " SystemOS: $CRYPTEX_SYSOS"
@@ -163,7 +166,7 @@ else
echo " [*] No userland launchd hook — pid 1 gets no injected dylib"
fi
-cfw_py patch-launchd-jetsam "$TEMP_DIR/launchd"
+cfw_cli patch-launchd-jetsam "$TEMP_DIR/launchd"
if [[ -s "$TEMP_DIR/launchd.entitlements" ]]; then
ldid -S"$TEMP_DIR/launchd.entitlements" -M "-K$VM_DIR/$CFW_INPUT/signcert.p12" "$TEMP_DIR/launchd"
@@ -204,7 +207,7 @@ case "$IOS_VERSION" 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" "$REPO_DIR/scripts/patchers/campo_mach_lookup_exceptions.py" "$TEMP_DIR/Campo.entitlements"
+ cfw_cli 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"
diff --git a/cfw-kit/lib/base_stages.sh b/cfw-kit/lib/base_stages.sh
index fd1a162c..0d84acfd 100644
--- a/cfw-kit/lib/base_stages.sh
+++ b/cfw-kit/lib/base_stages.sh
@@ -121,12 +121,12 @@ stage_display_and_boot_fixes() {
26.0*|18.*)
echo " [*] Patching IOMobileFramebuffer SwapEnd payload size (-> 0x560)..."
[[ -d "$DSC_DIR" ]] || die "dyld cache dir missing: $DSC_DIR"
- cfw_py patch-iomfb-swapend "$DSC_DIR" --target-size 0x560
+ cfw_cli patch-iomfb-swapend "$DSC_DIR" --target-size 0x560
;;
27.*)
echo " [*] Forcing IOMobileFramebuffer present onto the kern (method-5) path..."
[[ -d "$DSC_DIR" ]] || die "dyld cache dir missing: $DSC_DIR"
- cfw_py patch-iomfb-force-kern "$DSC_DIR"
+ cfw_cli patch-iomfb-force-kern "$DSC_DIR"
;;
esac
@@ -136,18 +136,18 @@ stage_display_and_boot_fixes() {
# 27's cache + 512 MiB maxSlide overflows the 6 GiB shared region
# -> dyld cannot map libSystem -> launchd (pid 1) panics.
echo " [*] Checking dyld cache maxSlide vs kernel shared region..."
- cfw_py patch-dsc-maxslide "$DSC_DIR"
+ cfw_cli patch-dsc-maxslide "$DSC_DIR"
# libxpc LWCR self-check crash-loops every daemon that pins an
# entitlement peer-requirement under our code-signing setup.
echo " [*] Patching libxpc LWCR self-check..."
- cfw_py patch-xpc-lwcr "$DSC_DIR"
+ cfw_cli patch-xpc-lwcr "$DSC_DIR"
# missing MAC sysctl -> launchd abort.
echo " [*] Patching os_lockdown_mode_enabled..."
- cfw_py patch-lockdown-mode "$DSC_DIR"
+ cfw_cli patch-lockdown-mode "$DSC_DIR"
if [[ "$want_lsd_reg" == "1" ]]; then
echo " [*] Patching lsd embedded-registration gate..."
- cfw_py patch-lsd-embedded-reg "$DSC_DIR"
+ cfw_cli patch-lsd-embedded-reg "$DSC_DIR"
else
echo " [*] skip lsd embedded-registration gate (no JB registration tool)"
fi
@@ -156,7 +156,7 @@ stage_display_and_boot_fixes() {
*)
if [[ "${FORCE_DSC_MAXSLIDE:-0}" == "1" && -d "$DSC_DIR" ]]; then
echo " [*] Forcing dyld cache maxSlide=0 (opt-in FORCE_DSC_MAXSLIDE=1)..."
- cfw_py patch-dsc-maxslide "$DSC_DIR" --force
+ cfw_cli patch-dsc-maxslide "$DSC_DIR" --force
fi
;;
esac
@@ -185,7 +185,7 @@ stage_seputil() {
fi
ldid -e "$MNT1/usr/libexec/diskimagesiod.bak" > "$TEMP_DIR/diskimagesiod.ent.plist"
cp "$MNT1/usr/libexec/diskimagesiod.bak" "$TEMP_DIR/diskimagesiod"
- cfw_py patch-diskimagesiod "$TEMP_DIR/diskimagesiod"
+ cfw_cli patch-diskimagesiod "$TEMP_DIR/diskimagesiod"
ldid_sign_ent "$TEMP_DIR/diskimagesiod" "$TEMP_DIR/diskimagesiod.ent.plist" "com.apple.diskimagesiod"
cp -R "$TEMP_DIR/diskimagesiod" "$MNT1/usr/libexec/diskimagesiod"
/bin/chmod 0755 "$MNT1/usr/libexec/diskimagesiod"
diff --git a/cfw-kit/lib/common.sh b/cfw-kit/lib/common.sh
index 3ab74cac..8ca0dcc8 100644
--- a/cfw-kit/lib/common.sh
+++ b/cfw-kit/lib/common.sh
@@ -9,7 +9,8 @@
# - running as root, VM powered off
# - CFW_HOST_CONTAINER set to the attached APFS container (e.g. disk4)
# - cwd = the VM directory, $1 = the VM directory
-# - VPHONE_REPO points at a vphone-cli checkout (for patchers/ and resources/)
+# - VPHONE_REPO points at a vphone-cli checkout (for the built binary and
+# the resources/ archives)
# ── Restore caller's PATH — Nix /etc/zshenv resets PATH on zsh startup ─
[[ -n "${_VPHONE_PATH:-}" ]] && export PATH="$_VPHONE_PATH"
@@ -22,7 +23,11 @@ die() {
warn() { echo "[!] $*" >&2; }
# ── Repo location ───────────────────────────────────────────────
-# The kit does not fork the Python patchers; it calls the repo's cfw.py.
+# The kit does not fork the patchers; it calls the repo's `vphone-cli cfw`.
+# The checkout marker is scripts/cfw_install.sh — the upstream installer this
+# kit is derived from, and the one file whose absence really does mean "not a
+# vphone-cli checkout". It is deliberately not the built binary: a fresh clone
+# has no .build yet, and "run make build" is a better error than "wrong path".
resolve_repo() {
local candidate="${VPHONE_REPO:-}"
if [[ -z "$candidate" ]]; then
@@ -30,30 +35,34 @@ resolve_repo() {
# the answer in the normal case. The other two are kept for running it
# from outside a checkout, which is how it was developed.
for c in "${KIT_DIR:h}" "$HOME/Documents/GitHub/Lakr233/vphone-cli" "${KIT_DIR:h}/vphone-cli"; do
- [[ -f "$c/scripts/patchers/cfw.py" ]] && candidate="$c" && break
+ [[ -f "$c/scripts/cfw_install.sh" ]] && candidate="$c" && break
done
fi
[[ -n "$candidate" ]] || die "VPHONE_REPO unset and no vphone-cli checkout found. Pass --repo <path>."
- [[ -f "$candidate/scripts/patchers/cfw.py" ]] \
- || die "Not a vphone-cli checkout (no scripts/patchers/cfw.py): $candidate"
+ [[ -f "$candidate/scripts/cfw_install.sh" ]] \
+ || die "Not a vphone-cli checkout (no scripts/cfw_install.sh): $candidate"
echo "${candidate:a}"
}
-# ── Python resolver — prefer project venv over whatever is in PATH ─
-resolve_python3() {
- if [[ -n "${VPHONE_PYTHON:-}" ]]; then
- echo "$VPHONE_PYTHON"
+# ── vphone-cli resolver — every CFW patcher lives in the binary ─
+# Same order as scripts/cfw_install_host.sh and run.sh: VPHONE_CLI_BIN when a
+# vphone-cli subcommand invoked us, otherwise the repo's dev build or the .app,
+# where the kit sits beside Contents/Resources and the binaries are one level
+# up in MacOS. Never `command -v` — it has to be the binary built from this
+# checkout, not whatever else is on PATH.
+resolve_vphone_cli() {
+ if [[ -n "${VPHONE_CLI_BIN:-}" ]]; then
+ echo "$VPHONE_CLI_BIN"
return
fi
- local venv_py="$REPO_DIR/.venv/bin/python3"
- if [[ -x "$venv_py" ]]; then
- echo "$venv_py"
- else
- command -v python3 || true
- fi
+ local c
+ for c in "$REPO_DIR/.build/release/vphone-cli" "${REPO_DIR:h}/MacOS/vphone-cli"; do
+ [[ -x "$c" ]] && { echo "$c"; return }
+ done
+ echo "$REPO_DIR/.build/release/vphone-cli" # report the expected path
}
-cfw_py() { "$PYTHON3" "$REPO_DIR/scripts/patchers/cfw.py" "$@"; }
+cfw_cli() { "$VPHONE_CLI" cfw "$@"; }
# ── Signing ─────────────────────────────────────────────────────
require_signing_tools() {
@@ -161,23 +170,33 @@ preflight() {
fatal=1
fi
- [[ -x "$PYTHON3" ]] || { warn "python3 not found (tried: $PYTHON3)"; fatal=1; }
- if [[ -x "$PYTHON3" ]]; then
- local py_err
- py_err="$("$PYTHON3" -c "import capstone, keystone" 2>&1)" || {
- warn "Missing Python deps (using $PYTHON3): ${py_err}"
- warn " Fix: source $REPO_DIR/.venv/bin/activate && pip install capstone keystone-engine"
+ if [[ ! -x "$VPHONE_CLI" ]]; then
+ warn "vphone-cli not found (tried: $VPHONE_CLI) — build it with 'make build' in $REPO_DIR"
+ fatal=1
+ else
+ # Every cfw subcommand this variant will call must exist up front. Ask
+ # the binary, not a source file, by reading the verb list out of its own
+ # help. Probing `cfw <sub> --help` looks tidier and is WRONG: swift
+ # argument-parser intercepts --help anywhere in argv and prints the group
+ # help with exit 0, so every name on earth "passes". And `cfw <sub>` with
+ # no arguments cannot be used either — it exits 64 for a real verb
+ # (missing argument) and 64 for a typo, and would actually RUN any verb
+ # that happens to need no arguments.
+ local -a have
+ have=("${(@f)$("$VPHONE_CLI" cfw --help 2>&1 |
+ awk '/^SUBCOMMANDS:/ {f = 1; next} f && /^ [a-z]/ {print $1}')}")
+ if (( ${#have} == 0 )); then
+ warn "could not read the subcommand list from '$VPHONE_CLI cfw --help'"
fatal=1
- }
+ else
+ local sub
+ for sub in "${REQUIRED_CFW_SUBCOMMANDS[@]}"; do
+ (( ${have[(I)$sub]} )) \
+ || { warn "vphone-cli has no 'cfw $sub' subcommand — binary too old or too new for this kit"; fatal=1; }
+ done
+ fi
fi
- # Every cfw.py subcommand this variant will call must exist up front.
- local sub
- for sub in "${REQUIRED_CFW_SUBCOMMANDS[@]}"; do
- grep -q "\"$sub\"" "$REPO_DIR/scripts/patchers/cfw.py" \
- || { warn "cfw.py has no '$sub' subcommand — repo too old or too new for this kit"; fatal=1; }
- done
-
(( fatal == 0 )) || die "Preflight failed — nothing was written."
echo "[+] preflight OK"
}
@@ -201,7 +220,7 @@ read_ios_version() {
# Patch a rootfs binary from its pristine .bak, sign it, put it back.
# Upstream does this inline in four places; same semantics, one helper.
-patch_rootfs_binary() { # <relpath> <cfw.py subcommand> [bundle_id]
+patch_rootfs_binary() { # <relpath> <cfw subcommand> [bundle_id]
local rel="$1" sub="$2" bundle_id="${3:-}"
local live="$MNT1/$rel" bak="$MNT1/$rel.bak" work="$TEMP_DIR/${rel:t}"
@@ -211,7 +230,7 @@ patch_rootfs_binary() { # <relpath> <cfw.py subcommand> [bundle_id]
/bin/cp "$live" "$bak"
fi
/bin/cp "$bak" "$work"
- cfw_py "$sub" "$work"
+ cfw_cli "$sub" "$work"
ldid_sign "$work" "$bundle_id"
/bin/cp -R "$work" "$live"
/bin/chmod 0755 "$live"
diff --git a/cfw-kit/run.sh b/cfw-kit/run.sh
index 66ef3200..b426b236 100755
--- a/cfw-kit/run.sh
+++ b/cfw-kit/run.sh
@@ -16,7 +16,8 @@
#
# Prereqs: VM restored and POWERED OFF; for the jb variant the boot chain must
# already carry the 127 JB patches (`make fw_patch_jb`). Host needs gnu-tar,
-# zstd, ipsw, aea, ldid and the project venv (`make setup_tools`).
+# zstd, ipsw, aea, ldid (`make setup_tools`) and a built vphone-cli
+# (`make build`) — every CFW patcher the kit calls lives in that binary.
#
# Usage:
# ./run.sh --variant vanilla|jb [--repo <vphone-cli>] [vm_dir]
@@ -77,12 +78,10 @@ PROJ="$REPO_DIR"
[[ -n "$VM_DIR" ]] || VM_DIR="$PROJ/vm"
VM_DIR="${VM_DIR:a}"
-# Host-side install toolchain (gnu-tar/ipsw/aea/ldid/zstd + venv python).
-if [[ -n "${VPHONE_PYTHON:-}" ]]; then
- P="$PROJ/.tools/bin:$(dirname "$VPHONE_PYTHON"):/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
-else
- P="$PROJ/.tools/bin:$PROJ/.venv/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
-fi
+# Host-side install toolchain (gnu-tar/ipsw/aea/ldid/zstd). No python entry:
+# the installers call `vphone-cli cfw <verb>` for every patch, and nothing they
+# run comes out of the venv.
+P="$PROJ/.tools/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
export PATH="$P"
# Variables the installers read, forwarded explicitly. An expansion-produced
@@ -91,7 +90,7 @@ kit_env=(
CFW_HOST_CONTAINER="__unset__"
_VPHONE_PATH="$P"
VPHONE_REPO="$PROJ"
- ${VPHONE_PYTHON:+VPHONE_PYTHON="$VPHONE_PYTHON"}
+ ${VPHONE_CLI_BIN:+VPHONE_CLI_BIN="$VPHONE_CLI_BIN"}
${JB_USERLAND:+JB_USERLAND="$JB_USERLAND"}
${VANILLA_LSD_EMBEDDED_REG:+VANILLA_LSD_EMBEDDED_REG="$VANILLA_LSD_EMBEDDED_REG"}
${FORCE_DSC_MAXSLIDE:+FORCE_DSC_MAXSLIDE="$FORCE_DSC_MAXSLIDE"}
@@ -151,16 +150,9 @@ cleanup
trap - EXIT
echo "[*] flipping boot snapshot offline (com.apple.os.update -> live volume)..."
-# Was `python3 tools/apfs_snap_rename.py`. Same resolution order as
-# scripts/cfw_install_host.sh: the env var when the CLI invoked us, otherwise a
-# dev tree or the .app, where scripts/ sits in Contents/Resources and the
-# binaries are one level up in MacOS.
-VPHONE_CLI="${VPHONE_CLI_BIN:-}"
-if [[ -z "$VPHONE_CLI" ]]; then
- for candidate in "$PROJ/.build/release/vphone-cli" "${PROJ:h}/MacOS/vphone-cli"; do
- [[ -x "$candidate" ]] && { VPHONE_CLI="$candidate"; break }
- done
-fi
+# Was `python3 tools/apfs_snap_rename.py`. Same resolver the installers use for
+# the CFW patchers (lib/common.sh), so there is one search order in the kit.
+VPHONE_CLI="$(resolve_vphone_cli)"
[[ -x "$VPHONE_CLI" ]] || { echo "[-] cannot find vphone-cli — snapshot NOT flipped; the VM will boot the stock snapshot." >&2; exit 1; }
"$VPHONE_CLI" cfw flip-snapshot "$IMG"
diff --git a/cfw-kit/vanilla/install.sh b/cfw-kit/vanilla/install.sh
index ef0f2ad0..b3894533 100755
--- a/cfw-kit/vanilla/install.sh
+++ b/cfw-kit/vanilla/install.sh
@@ -62,7 +62,7 @@ REQUIRED_CFW_SUBCOMMANDS=(
[[ "$VANILLA_LSD_EMBEDDED_REG" == "1" ]] && REQUIRED_CFW_SUBCOMMANDS+=(patch-lsd-embedded-reg)
REPO_DIR="$(resolve_repo)"
-PYTHON3="$(resolve_python3)"
+VPHONE_CLI="$(resolve_vphone_cli)"
init_paths
cleanup_on_exit() {
@@ -90,7 +90,7 @@ mkdir -p "$TEMP_DIR"
echo ""
echo "[*] Parsing iPhone BuildManifest for Cryptex paths..."
-CRYPTEX_PATHS=$(cfw_py cryptex-paths "$RESTORE_DIR/iPhone-BuildManifest.plist")
+CRYPTEX_PATHS=$(cfw_cli cryptex-paths "$RESTORE_DIR/iPhone-BuildManifest.plist")
CRYPTEX_SYSOS=$(echo "$CRYPTEX_PATHS" | head -1)
CRYPTEX_APPOS=$(echo "$CRYPTEX_PATHS" | tail -1)
echo " SystemOS: $CRYPTEX_SYSOS"
diff --git a/requirements.txt b/requirements.txt
index b51a8b8f..a66d1cc0 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,7 +1,4 @@
typer
-capstone
-keystone-engine
-pyimg4
pymobiledevice3>=9.5.0
ipsw-parser
setuptools
diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.md
index 75dbe2f5..c56fa689 100644
--- a/research/0_binary_patch_comparison.md
+++ b/research/0_binary_patch_comparison.md
@@ -1,5 +1,13 @@
# Patch Comparison: Regular / Development / Jailbreak / Experimental
+> **`scripts/patchers/*.py` no longer exists.** The tables below cite those
+> filenames throughout, because that is where each patch was first written and
+> where its on-device validation notes were recorded. Every one is now a Swift
+> patcher reached through `vphone-cli cfw <verb>` — read a citation as "the
+> patch this became", and recover the Python itself from git history at
+> `78cbeea` if you need to run it. The port is documented in the three
+> "Swift port status" sections further down.
+
> **EXP is a JB superset.** Everything in the baseline tables below that is `Y`
> for JB is also `Y` for EXP. The columns are kept at three variants to avoid
> noise — the only place EXP and JB diverge is the **Experimental additions**
@@ -203,8 +211,8 @@ each now has an in-process Swift implementation on the validated DSC foundation
(`DSCChunkSet`, `DSCCodeSignature`, `DSCLocalSymbolTable`, `DSCSymbolResolver`).
Every one was proven on the real 24A435 arm64e cache — `ipsws/ref_extract/dsc_pristine`,
79 chunks + `.symbols` = 80 files, 6.7 GB — by running the Python on one `cp -c`
-clone and the Swift on another and comparing all 80 files. The Python stays in
-place until a `vphone-cli` verb replaces each `cfw.py` call site.
+clone and the Swift on another and comparing all 80 files. Every `cfw.py` call
+site is now a `vphone-cli cfw` verb — see "the CFW verbs" below.
| Python | Swift | Sites | Parity on the real cache |
| --- | --- | --- | --- |
@@ -287,11 +295,10 @@ hit this because it always copies from the `.bak` first. The Swift reports
`already patched` and writes nothing, which is what the in-place call site in
`CryptexFilesystemPatcherGuestPayload` needs.
-**Wired in.** `CryptexFilesystemPatcherGuestPayload` now calls
-`CFWCacheLoaderPatcher` and `CFWMobileactivationd` in process instead of
-spawning `cfw.py`. The shell call sites (`cfw_install*.sh`, `cfw-kit`,
-`patch_hv_vmm_userland.sh`) still run the Python until a `vphone-cli cfw` verb
-replaces them.
+**Wired in.** `CryptexFilesystemPatcherGuestPayload` calls
+`CFWCacheLoaderPatcher` and `CFWMobileactivationd` in process. Every shell call
+site (`cfw_install*.sh`, `cfw-kit`, `patch_{camera,hv_vmm}_userland.sh`) now runs
+`vphone-cli cfw <verb>` — see the next section.
**A defect that review found and this branch fixed:** `CFWCacheLoaderPatcher`
trapped on every patch with logging on, which is the default. The before/after
@@ -299,11 +306,18 @@ window starts two instructions ahead of the gate, and it converted that negative
delta with `UInt64(Int)`, which traps even under `-O`. Every test passed
`log: nil`, so none reached it. Now covered by `loggingPathDoesNotTrap`.
+**A second defect, found when the CLI verbs landed and fixed here:** a Mach-O
+whose load-command table runs past EOF — a 64-byte truncation is enough — made
+*all six* patchers die with SIGTRAP (`BinaryBuffer.swift:9` precondition, exit
+133), not a catchable error. `MachOParser` walked the table checking only that
+each command's 8-byte header fit, then read fields up to `+0x38` inside it.
+`MachOParser.forEachLoadCommand` now bounds every command by `cmdsize` and by
+the file, and each branch checks its own minimum command size; a truncated file
+yields no segments and the patcher throws `invalidFormat` like any other bad
+input.
+
**Known, not fixed** (all LOW, none changes a byte on these binaries):
-* A Mach-O truncated to about 64 bytes makes `diskimagesiod` and `watchdogd`
- trap in the shared `MachOParser` (`BinaryBuffer.swift:9` precondition) instead
- of throwing.
* `CFWCacheLoaderPatcher.flagSetterOnResult` accepts a flag-setting instruction
with `x0`/`w0` in any operand, including as the destination.
* `CFWMobileactivationd`'s ObjC cross-check is scoped to the selector, not the
@@ -314,6 +328,70 @@ delta with `UInt64(Int)`, which traps even under `-O`. Every test passed
* `CFWWatchdogdTests.swift` converts a VA to a file offset by subtracting the
arm64 image base as a constant, in a test only.
+### The CFW verbs, and the end of `scripts/patchers` (2026-09-23)
+
+The fourteen ports above had no caller outside the two in-process call sites, so
+the installers still ran `cfw.py`. They no longer do. Every patch is a
+`vphone-cli cfw <verb>` with the Python's exact verb name, positional arguments
+and flags, so the shell diff is a prefix swap:
+
+```
+- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-seputil "$bin"
++ "$VPHONE_CLI" cfw patch-seputil "$bin"
+```
+
+26 call sites across `cfw_install{,_dev,_jb,_exp,_host}.sh`,
+`patch_{camera,hv_vmm}_userland.sh` and `cfw-kit`, whose `cfw_py` seam became
+`cfw_cli`. Each verb was proven through the built binary against its Python on
+`cp -c` clones of the real 24A435 references: the six Mach-O verbs byte-identical
+(`cmp` + matching sha256, both exit 0), the eight DSC verbs `diff -rq` clean over
+all 80 cache files on first run, second run and dry run.
+
+**Parity evidence is now frozen, not re-measured.** The CFW test suites used to
+spawn `.venv/bin/python3 scripts/patchers/…` and compare live. They now compare
+against constants recorded from that same Python at commit `78cbeea`, each with a
+provenance comment naming the command and the input digest, and each suite checks
+the fixture is the one the goldens were taken over — so a different firmware fails
+on that line instead of looking like a patcher bug. Two structural fixes were
+needed for the freeze to mean anything: the re-attester parity test was reading
+`.build/release/vphone-letmein`, a build product whose bytes change every build
+(retargeted to `macho_pristine/seputil`), and the device-tree golden is a digest
+map keyed by input digest, because that input exists in two cloudOS IPSWs.
+
+Re-deriving any of these constants means re-extracting the reference Python from
+git history — `scripts/patchers/` is gone from the working tree.
+
+**One Python bug the port deliberately does not reproduce.** A write that
+straddles a code-signature page boundary — eight bytes at `0x280FFFC..0x2810004`,
+which is what `cfw_patch_camera_dsc.py` emits when its six entry points land on
+both sides of the 2563/2564 line — re-attested only the page containing the
+address. Page 2564 kept its original slot hash (`7ccd65fa…`) while its bytes
+hashed to `dfe38096…`, and the guest dies on the first demand-page-in of it.
+`DSCCodeSignature.reattestRecordedWrites` covers every dirtied page;
+`DSCFoundationTests.pageStraddlingWriteAttestsEveryDirtiedPage` pins both the fix
+and the reference's value, so the divergence stays on the record.
+
+**Two behavioural differences kept on purpose**, both on the already-patched path
+and neither changing a byte:
+
+* `patch-camera-dsc` over an already-patched cache exits 0 where the Python
+ raised and exited 1. `cfw_install_exp.sh:126` tests that exit status and its
+ failure branch prints "likely build-version mismatch" — a *wrong* diagnosis for
+ a re-install. Exit 0 with "chunks patched" is the true one.
+* The three idempotence divergences in the section above stand: the Swift
+ recognises its own output where the Python double-applies or exits 1.
+
+**Not removed:** `scripts/repos/insert_dylib`. Nothing in the product runs it —
+`CFWInjectDylib` does the injection in process — but
+`CFWMachOTests.matchesInsertDylib` still runs the real binary as an independent
+byte-parity reference, gated on its presence. Deleting the submodule would turn
+that check into a silent skip rather than a failure. CI no longer initialises it;
+`setup_tools.sh` still builds it, relabelled as a test reference.
+
+`requirements.txt` drops `capstone`, `keystone-engine` and `pyimg4`; the venv,
+`setup_venv*.sh` and the Homebrew list exist for exactly one program now,
+`scripts/pymobiledevice3_bridge.py`.
+
### Installed Components
| # | Component | Description | Regular | Dev | JB |
diff --git a/scripts/patchers/README_reference_capture.md b/research/patch_reference_capture.md
similarity index 96%
rename from scripts/patchers/README_reference_capture.md
rename to research/patch_reference_capture.md
index dac89506..a415a459 100644
--- a/scripts/patchers/README_reference_capture.md
+++ b/research/patch_reference_capture.md
@@ -1,5 +1,14 @@
# Capturing the patcher reference snapshot
+> **Historical.** Everything below describes a facility that lived in the Python
+> patchers — `--emit-records`, `VPHONE_PATCH_RECORDS`, `cfw_records.py` — and
+> left with them when `scripts/patchers/` was removed. It is kept because the
+> port was built against the records it describes, and because shipping code
+> still cites its findings (`CFWJetsam.swift` quotes the non-idempotency note).
+> To run any of it, recover `scripts/patchers/` from git history at `78cbeea`.
+> The parity evidence itself is no longer re-derived at test time: it is frozen
+> into the `FrozenReference` / `*Golden` enums in `tests/FirmwarePatcherTests/`.
+
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.
diff --git a/scripts/build.sh b/scripts/build.sh
index 12ba3f39..32f0b755 100755
--- a/scripts/build.sh
+++ b/scripts/build.sh
@@ -127,8 +127,14 @@ echo "=== Bundling runtime assets → ${RES} ==="
rm -rf "${RES}/scripts" "${RES}/tools" "${RES}/.tools" "${RES}/vphoned.signed"
mkdir -p "${RES}/scripts" "${RES}/.tools/bin"
# Mirror scripts/ EXCEPT the make-coupled orchestrator, toolchain source, caches.
+# `patchers` is excluded rather than simply absent: the CFW patchers are Swift
+# now (`cfw <verb>` in vphone-cli, FirmwarePatcher behind it) and scripts/patchers
+# is gone from the repo, but a checkout that predates its removal still has the
+# directory on disk, and an .app carrying a dead Python tree is exactly the kind
+# of thing that gets run by accident years later.
rsync -a \
--exclude 'setup_machine.sh' \
+ --exclude 'patchers' \
--exclude 'repos' \
--exclude '__pycache__' \
--exclude '.git' \
@@ -136,19 +142,27 @@ rsync -a \
scripts/ "${RES}/scripts/"
# Custom-built tools (bundled; not brew/pip). apfs_sealvolume is NOT bundled
# (it is extracted from the target IPSW at `fw prepare` time — Task 5).
-for t in trustcache insert_dylib; do
+#
+# insert_dylib is NOT bundled any more: `CFWInjectDylib` does the injection
+# in-process, byte for byte (tests/FirmwarePatcherTests/CFWMachOTests.swift
+# asserts that against the real binary), and the only caller that ever shelled
+# out to it was scripts/patchers/cfw.py. setup_tools.sh still builds it, because
+# that parity test needs a reference to compare against — it is a development
+# tool now, not something the shipped .app runs.
+for t in trustcache; do
if [[ -x ".tools/bin/$t" ]]; then cp -f ".tools/bin/$t" "${RES}/.tools/bin/$t"
else echo "Error: .tools/bin/$t missing — run ./scripts/setup_tools.sh first" >&2; exit 1; fi
done
[[ -f .build/vphoned.signed ]] && cp -f .build/vphoned.signed "${RES}/vphoned.signed" || true
# requirements.txt lets the app provision its own ~/.vphone/venv on first run
-# (see VPhoneResources.pythonExecutable) — the app carries no venv itself.
+# (see VPhoneResources.pythonExecutable) — the app carries no venv itself. The
+# venv is down to one job: scripts/pymobiledevice3_bridge.py, the restore path.
cp -f requirements.txt "${RES}/requirements.txt"
# debs.list = extra-deb manifest (fetch_debs.sh reads $base/debs.list); README.md
# = the Tested-Environments table fw_prepare.sh reads to label Supported firmwares.
cp -f debs.list "${RES}/debs.list"
cp -f README.md "${RES}/README.md"
-echo " bundled: scripts/ (patchers+resources), .tools/bin/{trustcache,insert_dylib}, vphoned.signed, requirements.txt, debs.list, README.md"
+echo " bundled: scripts/ (resources), .tools/bin/trustcache, vphoned.signed, requirements.txt, debs.list, README.md"
# Re-sign: codesign seals Contents/Resources at sign time, so the earlier
# bundle-step signature (made before these assets existed) is now stale —
diff --git a/scripts/cfw_install.sh b/scripts/cfw_install.sh
index aecae494..8c392365 100755
--- a/scripts/cfw_install.sh
+++ b/scripts/cfw_install.sh
@@ -14,7 +14,7 @@
# - VM restored (make restore) and powered off
# - `ipsw` tool installed (brew install blacktop/tap/ipsw)
# - `aea` tool available (macOS 12+)
-# - Python: make setup_tools && source .venv/bin/activate
+# - vphone-cli built (make build) — every CFW patcher lives in it
# - cfw_input/ or resources/cfw_input.tar.zst present
#
# Usage: make cfw_install
@@ -29,25 +29,24 @@ SCRIPT_DIR="${0:a:h}"
# Resolve absolute paths
VM_DIR="$(cd "$VM_DIR" && pwd)"
-# ── Python resolver — prefer project venv over whatever is in PATH ─
-# Resolves to .venv/bin/python3 relative to the project root (parent of
-# scripts/), falling back to the system python3 when the venv is absent.
-# Every python3 invocation in this script uses $PYTHON3 so that running
-# `make cfw_install` standalone (without setup_machine.sh exporting PATH)
-# still uses the correctly set-up venv interpreter.
-_resolve_python3() {
- if [[ -n "${VPHONE_PYTHON:-}" ]]; then
- echo "$VPHONE_PYTHON"
- return
- fi
- local venv_py="${SCRIPT_DIR:h}/.venv/bin/python3"
- if [[ -x "$venv_py" ]]; then
- echo "$venv_py"
- else
- command -v python3 || true
- fi
+# ── vphone-cli resolver — every CFW patcher this script calls lives in it ─
+# 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 CFW patchers live in it) — run 'make build'" >&2
+ exit 1
}
-PYTHON3="$(_resolve_python3)"
# ── Configuration ───────────────────────────────────────────────
CFW_INPUT="cfw_input"
@@ -149,12 +148,7 @@ setup_cfw_input() {
require_firmware_tools() {
command -v ipsw >/dev/null 2>&1 || die "'ipsw' not found. Install: brew install blacktop/tap/ipsw"
command -v aea >/dev/null 2>&1 || die "'aea' not found (requires macOS 12+)"
- [[ -x "$PYTHON3" ]] || die "python3 not found (tried: $PYTHON3). Run: make setup_tools"
- echo "[*] Python: $PYTHON3 ($("$PYTHON3" --version 2>&1))"
- local py_err
- py_err="$("$PYTHON3" -c "import capstone, keystone" 2>&1)" || {
- die "Missing Python dependencies (using $PYTHON3).\n Error: ${py_err}\n Fix: source ${SCRIPT_DIR:h}/.venv/bin/activate && pip install capstone keystone-engine\n Or: make setup_tools"
- }
+ echo "[*] Patchers: $VPHONE_CLI cfw"
}
# ── Cleanup trap (unmount DMGs on error) ───────────────────────
@@ -203,7 +197,7 @@ mkdir -p "$TEMP_DIR"
# ── Parse Cryptex paths from BuildManifest ─────────────────────
echo ""
echo "[*] Parsing iPhone BuildManifest for Cryptex paths..."
-CRYPTEX_PATHS=$("$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" cryptex-paths "$RESTORE_DIR/iPhone-BuildManifest.plist")
+CRYPTEX_PATHS=$("$VPHONE_CLI" cfw cryptex-paths "$RESTORE_DIR/iPhone-BuildManifest.plist")
CRYPTEX_SYSOS=$(echo "$CRYPTEX_PATHS" | head -1)
CRYPTEX_APPOS=$(echo "$CRYPTEX_PATHS" | tail -1)
echo " SystemOS: $CRYPTEX_SYSOS"
@@ -328,12 +322,12 @@ case "$IOS_VERSION" in
26.0*|18.*)
echo " [*] Patching IOMobileFramebuffer SwapEnd payload size (iOS $IOS_VERSION -> 0x560)..."
[[ -d "$DSC_DIR" ]] || die "dyld cache dir missing: $DSC_DIR"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-iomfb-swapend "$DSC_DIR" --target-size 0x560
+ "$VPHONE_CLI" cfw patch-iomfb-swapend "$DSC_DIR" --target-size 0x560
;;
27.*)
echo " [*] Forcing IOMobileFramebuffer present onto the kern (method-5) path (iOS $IOS_VERSION)..."
[[ -d "$DSC_DIR" ]] || die "dyld cache dir missing: $DSC_DIR"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-iomfb-force-kern "$DSC_DIR"
+ "$VPHONE_CLI" cfw patch-iomfb-force-kern "$DSC_DIR"
;;
esac
@@ -361,19 +355,19 @@ case "$IOS_VERSION" in
27.*)
if [[ -d "$DSC_DIR" ]]; then
echo " [*] Checking dyld cache maxSlide vs kernel shared region..."
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-dsc-maxslide "$DSC_DIR"
+ "$VPHONE_CLI" cfw patch-dsc-maxslide "$DSC_DIR"
echo " [*] Patching lsd embedded-registration gate (iOS 27 app registration)..."
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-lsd-embedded-reg "$DSC_DIR"
+ "$VPHONE_CLI" cfw patch-lsd-embedded-reg "$DSC_DIR"
echo " [*] Patching libxpc LWCR self-check (iOS 27 daemon crash-loop)..."
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-xpc-lwcr "$DSC_DIR"
+ "$VPHONE_CLI" cfw patch-xpc-lwcr "$DSC_DIR"
echo " [*] Patching os_lockdown_mode_enabled (missing MAC sysctl -> launchd abort)..."
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-lockdown-mode "$DSC_DIR"
+ "$VPHONE_CLI" cfw patch-lockdown-mode "$DSC_DIR"
fi
;;
*)
if [[ "$FORCE_DSC_MAXSLIDE" == "1" && -d "$DSC_DIR" ]]; then
echo " [*] Forcing dyld cache maxSlide=0 (opt-in FORCE_DSC_MAXSLIDE=1; base iOS ${IOS_VERSION:-unknown})..."
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-dsc-maxslide "$DSC_DIR" --force
+ "$VPHONE_CLI" cfw patch-dsc-maxslide "$DSC_DIR" --force
fi
;;
esac
@@ -389,7 +383,7 @@ if ! [[ -e "$MNT1/usr/libexec/seputil.bak" ]]; then
fi
cp "$MNT1/usr/libexec/seputil.bak" "$TEMP_DIR/seputil"
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-seputil "$TEMP_DIR/seputil"
+"$VPHONE_CLI" cfw patch-seputil "$TEMP_DIR/seputil"
ldid_sign "$TEMP_DIR/seputil" "com.apple.seputil"
cp -R "$TEMP_DIR/seputil" "$MNT1/usr/libexec/seputil"
/bin/chmod 0755 $MNT1/usr/libexec/seputil
@@ -412,7 +406,7 @@ case "$IOS_VERSION" in
fi
ldid -e "$MNT1/usr/libexec/diskimagesiod.bak" > "$TEMP_DIR/diskimagesiod.ent.plist"
cp "$MNT1/usr/libexec/diskimagesiod.bak" "$TEMP_DIR/diskimagesiod"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-diskimagesiod "$TEMP_DIR/diskimagesiod"
+ "$VPHONE_CLI" cfw patch-diskimagesiod "$TEMP_DIR/diskimagesiod"
ldid_sign_ent "$TEMP_DIR/diskimagesiod" "$TEMP_DIR/diskimagesiod.ent.plist" "com.apple.diskimagesiod"
cp -R "$TEMP_DIR/diskimagesiod" "$MNT1/usr/libexec/diskimagesiod"
/bin/chmod 0755 "$MNT1/usr/libexec/diskimagesiod"
@@ -474,7 +468,7 @@ if ! [[ -e "$MNT1/usr/libexec/launchd_cache_loader.bak" ]]; then
fi
cp "$MNT1/usr/libexec/launchd_cache_loader.bak" "$TEMP_DIR/launchd_cache_loader"
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-launchd-cache-loader "$TEMP_DIR/launchd_cache_loader"
+"$VPHONE_CLI" cfw patch-launchd-cache-loader "$TEMP_DIR/launchd_cache_loader"
ldid_sign "$TEMP_DIR/launchd_cache_loader" "com.apple.launchd_cache_loader"
cp -R "$TEMP_DIR/launchd_cache_loader" "$MNT1/usr/libexec/launchd_cache_loader"
/bin/chmod 0755 $MNT1/usr/libexec/launchd_cache_loader
@@ -492,7 +486,7 @@ if ! [[ -e "$MNT1/usr/libexec/mobileactivationd.bak" ]]; then
fi
cp "$MNT1/usr/libexec/mobileactivationd.bak" "$TEMP_DIR/mobileactivationd"
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-mobileactivationd "$TEMP_DIR/mobileactivationd"
+"$VPHONE_CLI" cfw patch-mobileactivationd "$TEMP_DIR/mobileactivationd"
ldid_sign "$TEMP_DIR/mobileactivationd"
cp -R "$TEMP_DIR/mobileactivationd" "$MNT1/usr/libexec/mobileactivationd"
/bin/chmod 0755 $MNT1/usr/libexec/mobileactivationd
@@ -547,7 +541,7 @@ for plist in bash.plist dropbear.plist trollvnc.plist rpcserver_ios.plist; do
if [[ "$plist" == "dropbear.plist" ]]; then
plist_src="$TEMP_DIR/dropbear.plist"
cp "$INPUT_DIR/jb/LaunchDaemons/dropbear.plist" "$plist_src"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-dropbear-plist "$plist_src"
+ "$VPHONE_CLI" cfw patch-dropbear-plist "$plist_src"
fi
cp -R "$plist_src" "$MNT1/System/Library/LaunchDaemons/"
/bin/chmod 0644 $MNT1/System/Library/LaunchDaemons/$plist
@@ -564,7 +558,7 @@ fi
cp "$MNT1/System/Library/xpc/launchd.plist.bak" "$TEMP_DIR/launchd.plist"
cp "$VPHONED_SRC/vphoned.plist" "$INPUT_DIR/jb/LaunchDaemons/"
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" inject-daemons "$TEMP_DIR/launchd.plist" "$INPUT_DIR/jb/LaunchDaemons"
+"$VPHONE_CLI" cfw inject-daemons "$TEMP_DIR/launchd.plist" "$INPUT_DIR/jb/LaunchDaemons"
cp -R "$TEMP_DIR/launchd.plist" "$MNT1/System/Library/xpc/launchd.plist"
/bin/chmod 0644 $MNT1/System/Library/xpc/launchd.plist
diff --git a/scripts/cfw_install_dev.sh b/scripts/cfw_install_dev.sh
index 14e00761..0906f1c0 100755
--- a/scripts/cfw_install_dev.sh
+++ b/scripts/cfw_install_dev.sh
@@ -14,7 +14,7 @@
# - VM restored (make restore) and powered off
# - `ipsw` tool installed (brew install blacktop/tap/ipsw)
# - `aea` tool available (macOS 12+)
-# - Python: make setup_tools && source .venv/bin/activate
+# - vphone-cli built (make build) — every CFW patcher lives in it
# - cfw_input/ or resources/cfw_input.tar.zst + resources/cfw_dev/rpcserver_ios present
#
# Usage: make cfw_install_dev
@@ -29,20 +29,22 @@ SCRIPT_DIR="${0:a:h}"
# Resolve absolute paths
VM_DIR="$(cd "$VM_DIR" && pwd)"
-# ── Python resolver — prefer project venv over whatever is in PATH ─
-_resolve_python3() {
- if [[ -n "${VPHONE_PYTHON:-}" ]]; then
- echo "$VPHONE_PYTHON"
- return
- fi
- local venv_py="${SCRIPT_DIR:h}/.venv/bin/python3"
- if [[ -x "$venv_py" ]]; then
- echo "$venv_py"
- else
- command -v python3 || true
- fi
+# ── vphone-cli resolver — every CFW patcher this script calls lives in it ─
+# 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.
+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 CFW patchers live in it) — run 'make build'" >&2
+ exit 1
}
-PYTHON3="$(_resolve_python3)"
# ── Configuration ───────────────────────────────────────────────
CFW_INPUT="cfw_input"
@@ -144,12 +146,7 @@ apply_dev_overlay() {
require_firmware_tools() {
command -v ipsw >/dev/null 2>&1 || die "'ipsw' not found. Install: brew install blacktop/tap/ipsw"
command -v aea >/dev/null 2>&1 || die "'aea' not found (requires macOS 12+)"
- [[ -x "$PYTHON3" ]] || die "python3 not found (tried: $PYTHON3). Run: make setup_tools"
- echo "[*] Python: $PYTHON3 ($("$PYTHON3" --version 2>&1))"
- local py_err
- py_err="$("$PYTHON3" -c "import capstone, keystone" 2>&1)" || {
- die "Missing Python dependencies (using $PYTHON3).\n Error: ${py_err}\n Fix: source ${SCRIPT_DIR:h}/.venv/bin/activate && pip install capstone keystone-engine\n Or: make setup_tools"
- }
+ echo "[*] Patchers: $VPHONE_CLI cfw"
}
# ── Cleanup trap (unmount DMGs on error) ───────────────────────
@@ -199,7 +196,7 @@ mkdir -p "$TEMP_DIR"
# ── Parse Cryptex paths from BuildManifest ─────────────────────
echo ""
echo "[*] Parsing iPhone BuildManifest for Cryptex paths..."
-CRYPTEX_PATHS=$("$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" cryptex-paths "$RESTORE_DIR/iPhone-BuildManifest.plist")
+CRYPTEX_PATHS=$("$VPHONE_CLI" cfw cryptex-paths "$RESTORE_DIR/iPhone-BuildManifest.plist")
CRYPTEX_SYSOS=$(echo "$CRYPTEX_PATHS" | head -1)
CRYPTEX_APPOS=$(echo "$CRYPTEX_PATHS" | tail -1)
echo " SystemOS: $CRYPTEX_SYSOS"
@@ -259,7 +256,7 @@ fi
cp "$MNT1/sbin/launchd.bak" "$TEMP_DIR/launchd"
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-launchd-jetsam "$TEMP_DIR/launchd"
+"$VPHONE_CLI" cfw patch-launchd-jetsam "$TEMP_DIR/launchd"
ldid_sign "$TEMP_DIR/launchd"
cp -R "$TEMP_DIR/launchd" "$MNT1/sbin/launchd"
/bin/chmod 0755 $MNT1/sbin/launchd
@@ -332,7 +329,7 @@ case "$IOS_VERSION" in
echo " [*] Patching IOMobileFramebuffer SwapEnd payload size (iOS $IOS_VERSION -> 0x560)..."
DSC_DIR="$MNT1/System/Cryptexes/OS/System/Library/Caches/com.apple.dyld"
[[ -d "$DSC_DIR" ]] || die "dyld cache dir missing: $DSC_DIR"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-iomfb-swapend "$DSC_DIR" --target-size 0x560
+ "$VPHONE_CLI" cfw patch-iomfb-swapend "$DSC_DIR" --target-size 0x560
;;
esac
@@ -347,7 +344,7 @@ if ! [[ -e "$MNT1/usr/libexec/seputil.bak" ]]; then
fi
cp "$MNT1/usr/libexec/seputil.bak" "$TEMP_DIR/seputil"
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-seputil "$TEMP_DIR/seputil"
+"$VPHONE_CLI" cfw patch-seputil "$TEMP_DIR/seputil"
ldid_sign "$TEMP_DIR/seputil" "com.apple.seputil"
cp -R "$TEMP_DIR/seputil" "$MNT1/usr/libexec/seputil"
/bin/chmod 0755 $MNT1/usr/libexec/seputil
@@ -407,7 +404,7 @@ if ! [[ -e "$MNT1/usr/libexec/launchd_cache_loader.bak" ]]; then
fi
cp "$MNT1/usr/libexec/launchd_cache_loader.bak" "$TEMP_DIR/launchd_cache_loader"
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-launchd-cache-loader "$TEMP_DIR/launchd_cache_loader"
+"$VPHONE_CLI" cfw patch-launchd-cache-loader "$TEMP_DIR/launchd_cache_loader"
ldid_sign "$TEMP_DIR/launchd_cache_loader" "com.apple.launchd_cache_loader"
cp -R "$TEMP_DIR/launchd_cache_loader" "$MNT1/usr/libexec/launchd_cache_loader"
/bin/chmod 0755 $MNT1/usr/libexec/launchd_cache_loader
@@ -425,7 +422,7 @@ if ! [[ -e "$MNT1/usr/libexec/mobileactivationd.bak" ]]; then
fi
cp "$MNT1/usr/libexec/mobileactivationd.bak" "$TEMP_DIR/mobileactivationd"
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-mobileactivationd "$TEMP_DIR/mobileactivationd"
+"$VPHONE_CLI" cfw patch-mobileactivationd "$TEMP_DIR/mobileactivationd"
ldid_sign "$TEMP_DIR/mobileactivationd"
cp -R "$TEMP_DIR/mobileactivationd" "$MNT1/usr/libexec/mobileactivationd"
/bin/chmod 0755 $MNT1/usr/libexec/mobileactivationd
@@ -477,7 +474,7 @@ for plist in bash.plist dropbear.plist trollvnc.plist rpcserver_ios.plist; do
if [[ "$plist" == "dropbear.plist" ]]; then
plist_src="$TEMP_DIR/dropbear.plist"
cp "$INPUT_DIR/jb/LaunchDaemons/dropbear.plist" "$plist_src"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-dropbear-plist "$plist_src"
+ "$VPHONE_CLI" cfw patch-dropbear-plist "$plist_src"
fi
cp -R "$plist_src" "$MNT1/System/Library/LaunchDaemons/"
/bin/chmod 0644 $MNT1/System/Library/LaunchDaemons/$plist
@@ -494,7 +491,7 @@ fi
cp "$MNT1/System/Library/xpc/launchd.plist.bak" "$TEMP_DIR/launchd.plist"
cp "$VPHONED_SRC/vphoned.plist" "$INPUT_DIR/jb/LaunchDaemons/"
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" inject-daemons "$TEMP_DIR/launchd.plist" "$INPUT_DIR/jb/LaunchDaemons"
+"$VPHONE_CLI" cfw inject-daemons "$TEMP_DIR/launchd.plist" "$INPUT_DIR/jb/LaunchDaemons"
cp -R "$TEMP_DIR/launchd.plist" "$MNT1/System/Library/xpc/launchd.plist"
/bin/chmod 0644 $MNT1/System/Library/xpc/launchd.plist
diff --git a/scripts/cfw_install_exp.sh b/scripts/cfw_install_exp.sh
index e8e307b7..4411f327 100755
--- a/scripts/cfw_install_exp.sh
+++ b/scripts/cfw_install_exp.sh
@@ -34,23 +34,6 @@ set -euo pipefail
VM_DIR="$(cd "${1:-.}" && pwd)"
SCRIPT_DIR="${0:a:h}"
-# ── Python resolver — prefer project venv over whatever is in PATH ─
-# Resolves to .venv/bin/python3 relative to the project root (parent of
-# scripts/), falling back to the system python3 when the venv is absent.
-_resolve_python3() {
- if [[ -n "${VPHONE_PYTHON:-}" ]]; then
- echo "$VPHONE_PYTHON"
- return
- fi
- local venv_py="${SCRIPT_DIR:h}/.venv/bin/python3"
- if [[ -x "$venv_py" ]]; then
- echo "$venv_py"
- else
- command -v python3 || true
- fi
-}
-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,
@@ -429,7 +412,7 @@ else
echo " [!] BaseBin is missing; skipping launchdhook injection"
fi
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-launchd-jetsam "$TEMP_DIR/launchd"
+"$VPHONE_CLI" cfw patch-launchd-jetsam "$TEMP_DIR/launchd"
# Re-sign with original entitlements to avoid "operation not permitted" on spawn
if [[ -s "$TEMP_DIR/launchd.entitlements" ]]; then
diff --git a/scripts/cfw_install_host.sh b/scripts/cfw_install_host.sh
index 86bcd2cd..0884efc0 100755
--- a/scripts/cfw_install_host.sh
+++ b/scripts/cfw_install_host.sh
@@ -7,8 +7,9 @@
# (`vphone-cli cfw flip-snapshot`) so the VM boots the live volume.
#
# Prereqs: VM restored (make restore) and powered off; host has gnu-tar, ipsw,
-# aea, ldid, zstd, project venv (make setup_tools). SIP disabled (project
-# baseline); NO authenticated-root/ARV change needed.
+# aea, ldid, zstd (make setup_tools) and a built vphone-cli (make build), which
+# is where every CFW patcher lives. SIP disabled (project baseline); NO
+# authenticated-root/ARV change needed.
#
# Usage: cfw_install_host.sh [--variant regular|dev|jb|exp] [vm_dir]
# Runs as root (mount_apfs/chown/cp to owners-honored mounts); re-execs under
@@ -44,16 +45,12 @@ VM_DIR="${VM_DIR:a}"
IMG="$VM_DIR/Disk.img"
[[ -f "$IMG" ]] || { echo "[-] no Disk.img at $IMG" >&2; exit 1; }
-# Host-side install toolchain (gnu-tar/ipsw/aea/ldid/zstd + venv python).
-# VPHONE_PYTHON overrides the venv python (e.g. a bundled .app has no .venv);
-# unset falls back to the repo venv, unchanged from before.
-if [[ -n "${VPHONE_PYTHON:-}" ]]; then
- P="$PROJ/.tools/bin:$(dirname "$VPHONE_PYTHON"):/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
-else
- P="$PROJ/.tools/bin:$PROJ/.venv/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
-fi
+# Host-side install toolchain (gnu-tar/ipsw/aea/ldid/zstd).
+# No python entry: the installers call `vphone-cli cfw <verb>` for every patch,
+# and nothing they run comes out of the venv. VPHONE_PYTHON used to be prepended
+# here for the Python patchers and is no longer read by anything downstream.
+P="$PROJ/.tools/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
export PATH="$P"
-PY="${VPHONE_PYTHON:-$PROJ/.venv/bin/python3}"
if lsof "$IMG" >/dev/null 2>&1; then
echo "[-] $IMG is in use — stop the VM first." >&2; exit 1
diff --git a/scripts/cfw_install_jb.sh b/scripts/cfw_install_jb.sh
index 6fbd91b5..bb7b047c 100755
--- a/scripts/cfw_install_jb.sh
+++ b/scripts/cfw_install_jb.sh
@@ -18,23 +18,6 @@ set -euo pipefail
VM_DIR="${1:-.}"
SCRIPT_DIR="${0:a:h}"
-# ── Python resolver — prefer project venv over whatever is in PATH ─
-# Resolves to .venv/bin/python3 relative to the project root (parent of
-# scripts/), falling back to the system python3 when the venv is absent.
-_resolve_python3() {
- if [[ -n "${VPHONE_PYTHON:-}" ]]; then
- echo "$VPHONE_PYTHON"
- return
- fi
- local venv_py="${SCRIPT_DIR:h}/.venv/bin/python3"
- if [[ -x "$venv_py" ]]; then
- echo "$venv_py"
- else
- command -v python3 || true
- fi
-}
-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,
@@ -263,7 +246,7 @@ else
echo " [!] BaseBin is missing; skipping launchdhook injection"
fi
-"$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-launchd-jetsam "$TEMP_DIR/launchd"
+"$VPHONE_CLI" cfw patch-launchd-jetsam "$TEMP_DIR/launchd"
# Re-sign with original entitlements to avoid "operation not permitted" on spawn
if [[ -s "$TEMP_DIR/launchd.entitlements" ]]; then
diff --git a/scripts/check_aux.sh b/scripts/check_aux.sh
index c5f02904..389eee06 100755
--- a/scripts/check_aux.sh
+++ b/scripts/check_aux.sh
@@ -53,7 +53,7 @@ section() { print ""; print -P "%B== $* ==%b" }
# Anything not on this list and not in the system whitelist fails.
typeset -a REGISTERED_REMAINING=(
ldid # -> VPhoneSign (P0.5). Bundled today and NOT self-contained.
- python3 # -> gone at P2.4
+ python3 # -> restore backend only (scripts/pymobiledevice3_bridge.py); gone at P2.4
gtar # -> vphone-archive (P0.5)
zstd # -> vphone-archive (P0.5)
unzip # -> vphone-archive (P0.5)
@@ -62,7 +62,6 @@ typeset -a REGISTERED_REMAINING=(
aria2c # -> deleted, curl fallback already exists (P0.5)
ipsw # allowed to stay: Go, statically linked, passes the rule
sshpass # JB environment only, frozen
- keystone # Python assembler dependency -> gone at P1.5/P2.4
)
# Programs macOS ships that we depend on and intend to keep. This is the
diff --git a/scripts/patch_camera_userland.sh b/scripts/patch_camera_userland.sh
index 1a9b5027..39db3389 100755
--- a/scripts/patch_camera_userland.sh
+++ b/scripts/patch_camera_userland.sh
@@ -3,8 +3,8 @@
#
# Mirrors patch_hv_vmm_userland.sh's shape so the EXP install pipeline can
# call into both via a single entry-point style. The actual work happens
-# in scripts/patchers/cfw_patch_camera_dsc.py::apply_all_camera_patches,
-# invoked through cfw.py's `patch-camera-dsc` subcommand.
+# in FirmwarePatcher's DSCCameraPatcher, invoked through vphone-cli's
+# `cfw patch-camera-dsc` subcommand.
#
# Usage:
# patch_camera_userland.sh dsc <chunks_dir> <dsc_header>
@@ -22,19 +22,20 @@ SCRIPT_DIR="${0:a:h}"
[[ -n "${_VPHONE_PATH:-}" ]] && export PATH="$_VPHONE_PATH"
-_resolve_python3() {
- if [[ -n "${VPHONE_PYTHON:-}" ]]; then
- echo "$VPHONE_PYTHON"
- return
- fi
- local venv_py="${SCRIPT_DIR:h}/.venv/bin/python3"
- if [[ -x "$venv_py" ]]; then
- echo "$venv_py"
- else
- command -v python3 || true
- fi
+# ── vphone-cli resolver — the patcher lives in it ─
+# Same order as scripts/cfw_install_host.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.
+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 camera DSC patcher lives in it) — run 'make build'" >&2
+ exit 1
}
-PYTHON3="$(_resolve_python3)"
usage() {
cat <<EOF >&2
@@ -52,7 +53,7 @@ case "$op" in
(( $# >= 2 )) || usage
echo "[*] Patching camera consumers in DSC chunks under: $1"
echo "[*] (symbol resolution against: $2)"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-camera-dsc "$1" "$2"
+ "$VPHONE_CLI" cfw patch-camera-dsc "$1" "$2"
;;
*)
usage
diff --git a/scripts/patch_hv_vmm_userland.sh b/scripts/patch_hv_vmm_userland.sh
index 052613f1..77bff62a 100755
--- a/scripts/patch_hv_vmm_userland.sh
+++ b/scripts/patch_hv_vmm_userland.sh
@@ -20,9 +20,9 @@
# code-signing identifier intact, which launchd boot-task identity
# checks require.
#
-# This script is a thin wrapper around `scripts/patchers/cfw.py`. It
-# exists so cfw_install_dev.sh and cfw_install_jb.sh can call a single
-# entry point without duplicating Python venv/python3 resolution logic.
+# This script is a thin wrapper around `vphone-cli cfw`. It exists so
+# cfw_install_dev.sh and cfw_install_jb.sh can call a single entry point
+# without duplicating the binary-resolution logic.
#
# Used by: cfw_install_dev.sh, cfw_install_jb.sh
@@ -32,19 +32,20 @@ SCRIPT_DIR="${0:a:h}"
[[ -n "${_VPHONE_PATH:-}" ]] && export PATH="$_VPHONE_PATH"
-_resolve_python3() {
- if [[ -n "${VPHONE_PYTHON:-}" ]]; then
- echo "$VPHONE_PYTHON"
- return
- fi
- local venv_py="${SCRIPT_DIR:h}/.venv/bin/python3"
- if [[ -x "$venv_py" ]]; then
- echo "$venv_py"
- else
- command -v python3 || true
- fi
+# ── vphone-cli resolver — both patchers live in it ─
+# Same order as scripts/cfw_install_host.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.
+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 hv_vmm patchers live in it) — run 'make build'" >&2
+ exit 1
}
-PYTHON3="$(_resolve_python3)"
usage() {
cat <<EOF >&2
@@ -62,12 +63,12 @@ case "$op" in
dsc)
(( $# >= 1 )) || usage
echo "[*] Patching hv_vmm_present consumers in DSC chunks under: $1"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-hv-vmm-dsc "$1"
+ "$VPHONE_CLI" cfw patch-hv-vmm-dsc "$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
+ # `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 the 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
@@ -77,7 +78,7 @@ case "$op" in
watchdogd)
(( $# >= 1 )) || usage
echo "[*] Patching watchdogd hv_vmm_present cache in: $1"
- "$PYTHON3" "$SCRIPT_DIR/patchers/cfw.py" patch-watchdogd "$1"
+ "$VPHONE_CLI" cfw patch-watchdogd "$1"
;;
*)
usage
diff --git a/scripts/patchers/__init__.py b/scripts/patchers/__init__.py
deleted file mode 100644
index 4c7ca9bf..00000000
--- a/scripts/patchers/__init__.py
+++ /dev/null
@@ -1,7 +0,0 @@
-"""patchers package.
-
-Only CFW-related helpers remain in Python. Firmware patching now lives in the
-Swift `FirmwarePatcher` module and is invoked through `vphone-cli`.
-"""
-
-__all__ = []
diff --git a/scripts/patchers/campo_mach_lookup_exceptions.py b/scripts/patchers/campo_mach_lookup_exceptions.py
deleted file mode 100644
index 5e6f0016..00000000
--- a/scripts/patchers/campo_mach_lookup_exceptions.py
+++ /dev/null
@@ -1,74 +0,0 @@
-#!/usr/bin/env python3
-"""Merge Campo's needed backboard/frontboard launch mach-services into an
-entitlements plist's mach-lookup exception array, in place. See
-0_binary_patch_comparison.md #14.
-
-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 = [
- "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",
-]
-
-
-def merge(path):
- records.set_group("campo_mach_lookup")
- before = records.snapshot_file(path)
-
- with open(path, "rb") as f:
- entitlements = plistlib.load(f)
-
- existing = list(entitlements.get(EXCEPTION_KEY, []))
- added = [s for s in SERVICES if s not in existing]
- entitlements[EXCEPTION_KEY] = existing + added
-
- 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 [--emit-records <dir>] "
- "<entitlements.plist>", file=sys.stderr)
- return 2
- merge(argv[1])
- return 0
-
-
-if __name__ == "__main__":
- sys.exit(main(sys.argv))
diff --git a/scripts/patchers/cfw.py b/scripts/patchers/cfw.py
deleted file mode 100755
index 4803e9e1..00000000
--- a/scripts/patchers/cfw.py
+++ /dev/null
@@ -1,518 +0,0 @@
-#!/usr/bin/env python3
-"""
-cfw.py — Dynamic binary patching for CFW installation on vphone600.
-
-Uses capstone for disassembly-based anchoring and keystone for instruction
-assembly, producing reliable, upgrade-proof patches.
-
-Called by cfw_install.sh during CFW installation.
-
-Commands:
- cryptex-paths <BuildManifest.plist>
- Print SystemOS and AppOS DMG paths from BuildManifest.
-
- patch-seputil <binary>
- Patch seputil gigalocker UUID to "AA".
-
- patch-launchd-cache-loader <binary>
- NOP the cache validation check in launchd_cache_loader.
-
- patch-mobileactivationd <binary>
- Patch -[DeviceType should_hactivate] to always return true.
-
- patch-launchd-jetsam <binary>
- Patch launchd jetsam panic guard to avoid initproc crash loop.
-
- patch-hv-vmm-dsc <chunks_dir> [--dry-run]
- Same patch, applied in place to the DSC chunks under
- <chunks_dir> (e.g. /System/Library/Caches/com.apple.dyld inside
- the mounted SystemOS Cryptex). Targets a fixed list of identity,
- store, and consumer-service dylibs; skips compute/accel libs.
-
- patch-iomfb-swapend <chunks_dir> [--dry-run]
- Patch iOS 26.0 and 26.0.1 IOMobileFramebuffer's _kern_SwapEnd external-method
- payload size from 0x548 to 0x560 for the PCC vphone600 userclient,
- then re-attest the modified DSC page hash.
-
- patch-iomfb-force-kern <chunks_dir> [--dry-run]
- iOS 27 VZ-view fix: retarget IOMobileFramebuffer's public
- _IOMobileFramebufferSwap* dispatch trampolines to their _kern_Swap*
- siblings, forcing present onto the userclient method-5 path the 26.4
- paravirt GPU scans out to the host (27 defaults to the _virt_* callback
- path the paravirt GPU never receives). Re-attests modified DSC pages.
- Pairs with the KernelJBPatchIomfbSwap kernel patches (accept 27's 0x6e0
- SwapEnd struct).
-
- patch-dsc-maxslide <chunks_dir> [--dry-run] [--force]
- Zero the dyld_cache_header maxSlide when the userland cache would overflow
- the vphone600 26.x kernel's 6 GiB shared region (cache span + maxSlide >
- 0x180000000, e.g. iOS 27.0). Lets the cache map at slide 0 so launchd's dyld
- can map libSystem. Self-gating (no-op if it already fits); no re-attest needed
- (header field, not a cs_validate'd code page). --force zeroes maxSlide even
- when the cache fits (non-27 opt-in).
-
- patch-lsd-embedded-reg <chunks_dir> [--dry-run]
- Force lsd's -[_LSDModifyClient clientIsEntitledForEmbeddedRegistrationOperations]
- to always succeed (NOP its entitlement gate + re-attest the page), so app
- (re)registration works on iOS 27 without the three privileged entitlements it
- otherwise demands from the XPC peer. Unblocks vphoned/TrollStore/uicache app
- installs. Self-gating (no-op on pre-iOS-27 userlands where the method is absent).
-
- patch-xpc-lwcr <chunks_dir> [--dry-run]
- Stop libxpc's Lightweight Code Requirement self-check (_xpc_token_satisfies_lwcr)
- from brk-aborting on our JB. iOS 27's LWCR matcher returns the contradictory
- (matched=0, error_code=MATCH) pair under our code-signing environment; the
- assertion crash-loops every daemon that pins an entitlement peer-requirement
- (intelligencetasksd/searchpartyd/transparencyd/bluetoothd/...). Derives `matched`
- from error_code + drops the abort (cset w0,eq; nop; nop) and re-attests the page.
- Self-gating (no-op on pre-iOS-27 userlands where the symbol is absent).
-
- patch-lockdown-mode <chunks_dir> [--dry-run]
- Stop libSystem's os_lockdown_mode_enabled() from aborting when the
- Lockdown Mode sysctl is missing. iOS 27 crashes on a -1 return from
- security.mac.lockdown_mode_state_public, which the vphone600 26.x kernel
- does not implement, so launchd is the first caller to abort and the
- kernel panics at boot. NOPs the error branch so the query reads 0 and
- boot continues, then re-attests the page. Self-gating (no-op on
- pre-iOS-27 userlands where the symbol is absent).
-
- patch-camera-dsc <chunks_dir> <dsc_header> [--dry-run] [--force]
- Apply the 10-patch set to the DSC chunks that makes Camera.app
- launch-survivable on a vphone VM: synthesises a single
- `vphone-cam` AVCaptureDevice through `cameracaptured`'s
- device-list / discovery-session / serializer paths and stubs out
- the AVFoundation init-time validation that would otherwise crash
- on the synthetic device. <dsc_header> is the
- dyld_shared_cache_arm64e file (not a chunk) used for
- `ipsw dyld symaddr` symbol resolution.
-
- patch-watchdogd <binary> [--dry-run]
- Surgical 2-instruction patch of /usr/libexec/watchdogd's
- sysctlbyname("kern.hv_vmm_present", ...) caching block so the
- cached "am I a VM?" byte is forced to 1 regardless of the
- sysctl result. Necessary because the kernel-side OID rename
- makes that sysctl return ENOENT, which would otherwise drive
- watchdogd into a trap path that launchd's _PanicOnCrash
- escalates to a kernel panic. Also recomputes the affected
- CodeDirectory slot hash via cfw_macho_codesign.
-
- patch-diskimagesiod <binary>
- Force -[DIDiskArb isMountCompleteWithExpectedCount:diskTracker:] to return
- YES so MobileStorageMounter proceeds to mount the iOS-27 personalized DDI at
- /System/Developer (its waitForDAMount otherwise hangs forever on the 26.4
- vphone600 hybrid). Pairs with the DiskImages2 ABI + sandbox
- mac_policy_ops[124] JB kernel patches. No-op-in-effect on matched userlands.
-
- inject-daemons <launchd.plist> <daemon_dir>
- Inject bash/dropbear/trollvnc into launchd.plist.
-
- patch-dropbear-plist <dropbear.plist>
- Rewrite dropbear ProgramArguments to use /var/dropbear host keys.
-
- inject-dylib <binary> <dylib_path>
- 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
-
-# When run as `python3 scripts/patchers/cfw.py`, __name__ is "__main__" and
-# relative imports fail. Add the parent directory to sys.path so we can import
-# from the patchers package using absolute imports.
-if __name__ == "__main__":
- sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
- from patchers.cfw_patch_seputil import patch_seputil
- from patchers.cfw_patch_cache_loader import patch_launchd_cache_loader
- from patchers.cfw_patch_mobileactivationd import patch_mobileactivationd
- from patchers.cfw_patch_jetsam import patch_launchd_jetsam
- from patchers.cfw_patch_hv_vmm_dsc import patch_hv_vmm_in_dsc
- from patchers.cfw_patch_iomfb_swapend import patch_iomfb_swapend
- from patchers.cfw_patch_iomfb_force_kern import patch_iomfb_force_kern
- from patchers.cfw_patch_dsc_maxslide import patch_dsc_maxslide
- from patchers.cfw_patch_lsd_embedded_reg import patch_lsd_embedded_reg
- from patchers.cfw_patch_xpc_lwcr import patch_xpc_lwcr
- from patchers.cfw_patch_lockdown_mode import patch_lockdown_mode
- from patchers.cfw_patch_camera_dsc import apply_all_camera_patches
- 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
- from .cfw_patch_mobileactivationd import patch_mobileactivationd
- from .cfw_patch_jetsam import patch_launchd_jetsam
- from .cfw_patch_hv_vmm_dsc import patch_hv_vmm_in_dsc
- from .cfw_patch_iomfb_swapend import patch_iomfb_swapend
- from .cfw_patch_iomfb_force_kern import patch_iomfb_force_kern
- from .cfw_patch_dsc_maxslide import patch_dsc_maxslide
- from .cfw_patch_lsd_embedded_reg import patch_lsd_embedded_reg
- from .cfw_patch_xpc_lwcr import patch_xpc_lwcr
- from .cfw_patch_lockdown_mode import patch_lockdown_mode
- from .cfw_patch_camera_dsc import apply_all_camera_patches
- 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>")
- sys.exit(1)
- sysos, appos = parse_cryptex_paths(sys.argv[2])
- print(sysos)
- print(appos)
-
- elif cmd == "patch-seputil":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-seputil <binary>")
- sys.exit(1)
- if not patch_seputil(sys.argv[2]):
- sys.exit(1)
-
- elif cmd == "patch-launchd-cache-loader":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-launchd-cache-loader <binary>")
- sys.exit(1)
- if not patch_launchd_cache_loader(sys.argv[2]):
- sys.exit(1)
-
- elif cmd == "patch-mobileactivationd":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-mobileactivationd <binary>")
- sys.exit(1)
- if not patch_mobileactivationd(sys.argv[2]):
- sys.exit(1)
-
- elif cmd == "patch-launchd-jetsam":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-launchd-jetsam <binary>")
- sys.exit(1)
- if not patch_launchd_jetsam(sys.argv[2]):
- sys.exit(1)
-
- elif cmd == "patch-hv-vmm-dsc":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-hv-vmm-dsc <chunks_dir> [--dry-run]")
- sys.exit(1)
- dry_run = "--dry-run" in sys.argv[3:]
- patch_hv_vmm_in_dsc(sys.argv[2], dry_run=dry_run)
- sys.exit(0)
-
- elif cmd == "patch-iomfb-swapend":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-iomfb-swapend <chunks_dir> "
- "[--target-size <hex|int>] [--dry-run]")
- sys.exit(1)
- dry_run = "--dry-run" in sys.argv[3:]
- kwargs = {}
- if "--target-size" in sys.argv:
- i = sys.argv.index("--target-size")
- kwargs["target_size"] = int(sys.argv[i + 1], 0)
- try:
- patch_iomfb_swapend(sys.argv[2], dry_run=dry_run, **kwargs)
- except ValueError as e:
- print(f"[-] {e}")
- sys.exit(1)
- sys.exit(0)
-
- elif cmd == "patch-iomfb-force-kern":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-iomfb-force-kern <chunks_dir> [--dry-run]")
- sys.exit(1)
- dry_run = "--dry-run" in sys.argv[3:]
- try:
- patch_iomfb_force_kern(sys.argv[2], dry_run=dry_run)
- except ValueError as e:
- print(f"[-] {e}")
- sys.exit(1)
- sys.exit(0)
-
- elif cmd == "patch-dsc-maxslide":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-dsc-maxslide <chunks_dir> [--dry-run] [--force]")
- sys.exit(1)
- dry_run = "--dry-run" in sys.argv[3:]
- force = "--force" in sys.argv[3:]
- patch_dsc_maxslide(sys.argv[2], dry_run=dry_run, force=force)
- sys.exit(0)
-
- elif cmd == "patch-lsd-embedded-reg":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-lsd-embedded-reg <chunks_dir> [--dry-run]")
- sys.exit(1)
- dry_run = "--dry-run" in sys.argv[3:]
- patch_lsd_embedded_reg(sys.argv[2], dry_run=dry_run)
- sys.exit(0)
-
- elif cmd == "patch-xpc-lwcr":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-xpc-lwcr <chunks_dir> [--dry-run]")
- sys.exit(1)
- dry_run = "--dry-run" in sys.argv[3:]
- patch_xpc_lwcr(sys.argv[2], dry_run=dry_run)
-
- elif cmd == "patch-lockdown-mode":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-lockdown-mode <chunks_dir> [--dry-run]")
- sys.exit(1)
- dry_run = "--dry-run" in sys.argv[3:]
- patch_lockdown_mode(sys.argv[2], dry_run=dry_run)
- sys.exit(0)
-
- elif cmd == "patch-camera-dsc":
- if len(sys.argv) < 4:
- print("Usage: cfw.py patch-camera-dsc <chunks_dir> <dsc_header> [--dry-run] [--force]")
- sys.exit(1)
- dry_run = "--dry-run" in sys.argv[4:]
- force = "--force" in sys.argv[4:]
- apply_all_camera_patches(sys.argv[2], sys.argv[3], dry_run=dry_run, force=force)
- sys.exit(0)
-
- elif cmd == "patch-watchdogd":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-watchdogd <binary> [--dry-run]")
- sys.exit(1)
- dry_run = "--dry-run" in sys.argv[3:]
- try:
- patch_watchdogd(sys.argv[2], dry_run=dry_run)
- except ValueError as e:
- print(f"[-] {e}")
- sys.exit(1)
- # Exit 0 on both "patched N>0" and "already patched (N==0)".
- # The install script treats both as success; only a raised
- # exception (unparseable binary / no anchor) is fatal.
- sys.exit(0)
-
- elif cmd == "patch-diskimagesiod":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-diskimagesiod <binary>")
- sys.exit(1)
- if not patch_diskimagesiod(sys.argv[2]):
- sys.exit(1)
-
- elif cmd == "inject-daemons":
- if len(sys.argv) < 4:
- print("Usage: cfw.py inject-daemons <launchd.plist> <daemon_dir>")
- sys.exit(1)
- inject_daemons(sys.argv[2], sys.argv[3])
-
- elif cmd == "patch-dropbear-plist":
- if len(sys.argv) < 3:
- print("Usage: cfw.py patch-dropbear-plist <dropbear.plist>")
- sys.exit(1)
- patch_dropbear_plist(sys.argv[2])
-
- elif cmd == "inject-dylib":
- if len(sys.argv) < 4:
- print("Usage: cfw.py inject-dylib <binary> <dylib_path>")
- sys.exit(1)
- import subprocess, shutil
- insert_dylib_bin = shutil.which("insert_dylib")
- if not insert_dylib_bin:
- # Check .tools/bin/ relative to project root
- project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
- candidate = os.path.join(project_root, ".tools", "bin", "insert_dylib")
- if os.path.isfile(candidate) and os.access(candidate, os.X_OK):
- insert_dylib_bin = candidate
- 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:")
- for name in COMMANDS:
- print(f" {name}")
- sys.exit(1)
-
-
-if __name__ == "__main__":
- main()
diff --git a/scripts/patchers/cfw_asm.py b/scripts/patchers/cfw_asm.py
deleted file mode 100644
index 068df1e3..00000000
--- a/scripts/patchers/cfw_asm.py
+++ /dev/null
@@ -1,172 +0,0 @@
-"""Shared helpers for CFW patch modules."""
-
-import struct
-
-from capstone import Cs, CS_ARCH_ARM64, CS_MODE_LITTLE_ENDIAN
-from capstone.arm64_const import ARM64_OP_REG, ARM64_OP_IMM
-from keystone import Ks, KS_ARCH_ARM64, KS_MODE_LITTLE_ENDIAN as KS_MODE_LE
-
-# ══════════════════════════════════════════════════════════════════
-# ARM64 assembler / disassembler
-# ══════════════════════════════════════════════════════════════════
-
-_cs = Cs(CS_ARCH_ARM64, CS_MODE_LITTLE_ENDIAN)
-_cs.detail = True
-_ks = Ks(KS_ARCH_ARM64, KS_MODE_LE)
-
-
-def asm(s):
- enc, _ = _ks.asm(s)
- if not enc:
- raise RuntimeError(f"asm failed: {s}")
- return bytes(enc)
-
-
-def asm_at(s, addr):
- enc, _ = _ks.asm(s, addr=addr)
- if not enc:
- raise RuntimeError(f"asm failed at 0x{addr:X}: {s}")
- return bytes(enc)
-
-
-NOP = asm("nop")
-MOV_X0_1 = asm("mov x0, #1")
-RET = asm("ret")
-
-
-def rd32(data, off):
- return struct.unpack_from("<I", data, off)[0]
-
-
-def wr32(data, off, val):
- struct.pack_into("<I", data, off, val)
-
-
-def disasm_at(data, off, n=8):
- """Disassemble n instructions at file offset."""
- return list(_cs.disasm(bytes(data[off : off + n * 4]), off))
-
-
-def _log_asm(data, offset, count=5, marker_off=-1):
- """Log disassembly of `count` instructions at file offset for before/after comparison."""
- insns = disasm_at(data, offset, count)
- for insn in insns:
- tag = " >>>" if insn.address == marker_off else " "
- print(f" {tag} 0x{insn.address:08X}: {insn.mnemonic:8s} {insn.op_str}")
-
-
-def _mov_reg_imm(insn):
- """If `insn` is `mov <reg>, #<imm>`, return (reg_name, imm); else None."""
- if insn.mnemonic != "mov":
- return None
- ops = insn.operands
- if len(ops) != 2 or ops[0].type != ARM64_OP_REG or ops[1].type != ARM64_OP_IMM:
- return None
- return insn.reg_name(ops[0].reg), ops[1].imm
-
-
-# ══════════════════════════════════════════════════════════════════
-# Mach-O helpers
-# ══════════════════════════════════════════════════════════════════
-
-
-def parse_macho_sections(data):
- """Parse Mach-O 64-bit to extract section info.
-
- Returns dict: "segment,section" -> (vm_addr, size, file_offset)
- """
- magic = struct.unpack_from("<I", data, 0)[0]
- if magic != 0xFEEDFACF:
- raise ValueError(f"Not a 64-bit Mach-O (magic=0x{magic:X})")
-
- ncmds = struct.unpack_from("<I", data, 16)[0]
- sections = {}
- offset = 32 # sizeof(mach_header_64)
-
- for _ in range(ncmds):
- cmd, cmdsize = struct.unpack_from("<II", data, offset)
- if cmd == 0x19: # LC_SEGMENT_64
- segname = data[offset + 8 : offset + 24].split(b"\x00")[0].decode()
- nsects = struct.unpack_from("<I", data, offset + 64)[0]
- sect_off = offset + 72
- for _ in range(nsects):
- sectname = data[sect_off : sect_off + 16].split(b"\x00")[0].decode()
- addr = struct.unpack_from("<Q", data, sect_off + 32)[0]
- size = struct.unpack_from("<Q", data, sect_off + 40)[0]
- file_off = struct.unpack_from("<I", data, sect_off + 48)[0]
- sections[f"{segname},{sectname}"] = (addr, size, file_off)
- sect_off += 80
- offset += cmdsize
- return sections
-
-
-def va_to_foff(data, va):
- """Convert virtual address to file offset using LC_SEGMENT_64 commands."""
- ncmds = struct.unpack_from("<I", data, 16)[0]
- offset = 32
-
- for _ in range(ncmds):
- cmd, cmdsize = struct.unpack_from("<II", data, offset)
- if cmd == 0x19: # LC_SEGMENT_64
- vmaddr = struct.unpack_from("<Q", data, offset + 24)[0]
- vmsize = struct.unpack_from("<Q", data, offset + 32)[0]
- fileoff = struct.unpack_from("<Q", data, offset + 40)[0]
- if vmaddr <= va < vmaddr + vmsize:
- return fileoff + (va - vmaddr)
- offset += cmdsize
- return -1
-
-
-def find_section(sections, *candidates):
- """Find the first matching section from candidates."""
- for name in candidates:
- if name in sections:
- return sections[name]
- return None
-
-
-def find_symtab(data):
- """Parse LC_SYMTAB from Mach-O header.
-
- Returns (symoff, nsyms, stroff, strsize) or None.
- """
- ncmds = struct.unpack_from("<I", data, 16)[0]
- offset = 32
- for _ in range(ncmds):
- cmd, cmdsize = struct.unpack_from("<II", data, offset)
- if cmd == 0x02: # LC_SYMTAB
- symoff = struct.unpack_from("<I", data, offset + 8)[0]
- nsyms = struct.unpack_from("<I", data, offset + 12)[0]
- stroff = struct.unpack_from("<I", data, offset + 16)[0]
- strsize = struct.unpack_from("<I", data, offset + 20)[0]
- return symoff, nsyms, stroff, strsize
- offset += cmdsize
- return None
-
-
-def find_symbol_va(data, name_fragment):
- """Search Mach-O symbol table for a symbol containing name_fragment.
-
- Returns the symbol's VA, or -1 if not found.
- """
- st = find_symtab(data)
- if not st:
- return -1
- symoff, nsyms, stroff, strsize = st
-
- for i in range(nsyms):
- entry_off = symoff + i * 16 # sizeof(nlist_64)
- n_strx = struct.unpack_from("<I", data, entry_off)[0]
- n_value = struct.unpack_from("<Q", data, entry_off + 8)[0]
-
- if n_strx >= strsize or n_value == 0:
- continue
-
- # Read null-terminated symbol name
- end = data.index(0, stroff + n_strx)
- sym_name = data[stroff + n_strx : end].decode("ascii", errors="replace")
-
- if name_fragment in sym_name:
- return n_value
-
- return -1
diff --git a/scripts/patchers/cfw_daemons.py b/scripts/patchers/cfw_daemons.py
deleted file mode 100644
index e2d5081e..00000000
--- a/scripts/patchers/cfw_daemons.py
+++ /dev/null
@@ -1,128 +0,0 @@
-"""Daemon injection and cryptex path helpers."""
-
-import os
-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",
- "/var/dropbear/dropbear_rsa_host_key",
- "-r",
- "/var/dropbear/dropbear_ecdsa_host_key",
-]
-
-def parse_cryptex_paths(manifest_path):
- """Extract Cryptex DMG paths from BuildManifest.plist.
-
- Searches ALL BuildIdentities for:
- - Cryptex1,SystemOS -> Info -> Path
- - Cryptex1,AppOS -> Info -> Path
-
- vResearch IPSWs may have Cryptex entries in a non-first identity.
- """
- with open(manifest_path, "rb") as f:
- manifest = plistlib.load(f)
-
- # Search all BuildIdentities for Cryptex paths
- for bi in manifest.get("BuildIdentities", []):
- m = bi.get("Manifest", {})
- sysos = m.get("Cryptex1,SystemOS", {}).get("Info", {}).get("Path", "")
- appos = m.get("Cryptex1,AppOS", {}).get("Info", {}).get("Path", "")
- if sysos and appos:
- return sysos, appos
-
- print(
- "[-] Cryptex1,SystemOS/AppOS paths not found in any BuildIdentity",
- file=sys.stderr,
- )
- sys.exit(1)
-
-
-# ══════════════════════════════════════════════════════════════════
-# LaunchDaemon injection
-# ══════════════════════════════════════════════════════════════════
-
-
-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)
-
- with open(plist_path, "rb") as f:
- target = plistlib.load(f)
-
- for name in ("bash", "dropbear", "trollvnc", "vphoned", "rpcserver_ios"):
- src = os.path.join(daemon_dir, f"{name}.plist")
- if not os.path.exists(src):
- print(f" [!] Missing {src}, skipping")
- continue
-
- with open(src, "rb") as f:
- daemon = plistlib.load(f)
-
- if name == "dropbear":
- patch_dropbear_daemon(daemon)
-
- key = f"/System/Library/LaunchDaemons/{name}.plist"
- target.setdefault("LaunchDaemons", {})[key] = daemon
- print(f" [+] Injected {name}")
-
- 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."""
- args = list(daemon.get("ProgramArguments", []))
- if not args:
- return
-
- # -R generates default keys under /etc/dropbear, which is read-only during
- # normal VM boot. Use explicit /var/dropbear keys seeded by cfw_install.
- cleaned = []
- idx = 0
- while idx < len(args):
- arg = args[idx]
- if arg == "-R":
- idx += 1
- continue
- if arg == "-r":
- idx += 2
- continue
- cleaned.append(arg)
- idx += 1
- args = cleaned + DROPBEAR_KEY_ARGS
- daemon["ProgramArguments"] = args
-
-
-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
deleted file mode 100644
index 88a76c7e..00000000
--- a/scripts/patchers/cfw_dsc_chunks.py
+++ /dev/null
@@ -1,394 +0,0 @@
-"""dyld shared cache (split / chunked) byte-level helper.
-
-The iOS 26 SystemOS Cryptex ships the DSC as multiple files:
-
- /System/Library/Caches/com.apple.dyld/dyld_shared_cache_arm64e
- /System/Library/Caches/com.apple.dyld/dyld_shared_cache_arm64e.01
- /System/Library/Caches/com.apple.dyld/dyld_shared_cache_arm64e.02
- ...
-
-The first file (no suffix) holds the cache header; suffixed files
-(`.NN`) hold subcache regions. Together they map a contiguous virtual
-address space.
-
-This module gives us:
-
- chunks = DSCChunks(chunks_dir)
- chunks.bytes_at_vma(vma, length) -> bytes
- chunks.find_chunk_for_vma(vma) -> (chunk_path, file_offset)
- chunks.write_at_vma(vma, data) -> None # persists to chunk on disk
-
-It does *not* extract dylibs. It treats the DSC as a flat virtual
-address space and gives byte-level access. That's the minimum we need
-to apply 4-byte instruction patches at known vmaddrs.
-
-The dyld_cache_header layout we use is intentionally minimal:
- char magic[16];
- uint32_t mappingOffset;
- uint32_t mappingCount;
- ...
- uint64_t sharedRegionStart; (offset 0x60 in modern caches)
- uint64_t sharedRegionSize;
- ...
-
-The dyld_cache_mapping_info entries (mappingCount of them) each look:
- uint64_t address;
- uint64_t size;
- uint64_t fileOffset;
- uint32_t maxProt;
- uint32_t initProt;
-
-For chunked caches (.NN files), each chunk has its own header with its
-own mappings; the mappings address ranges are non-overlapping across
-chunks.
-
-Reference: dyld project, dyld_cache_format.h.
-"""
-
-import os
-import struct
-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):
- """Return list of chunk file paths in numeric order; the unsuffixed file
- first, then .01, .02, ... `.symbols` is excluded (it doesn't map code).
- """
- names = []
- for name in os.listdir(chunks_dir):
- if not name.startswith("dyld_shared_cache_arm64e"):
- continue
- if name.endswith(".symbols") or name.endswith(".map"):
- continue
- names.append(name)
-
- def sort_key(n):
- # base file (no suffix) first, then .01, .02, ...
- m = re.match(r"^dyld_shared_cache_arm64e(?:\.(\d+))?$", n)
- if m:
- return (0, int(m.group(1)) if m.group(1) else -1)
- return (1, n)
-
- names.sort(key=sort_key)
- return [os.path.join(chunks_dir, n) for n in names]
-
-
-def _parse_chunk_mappings(path):
- """Return list of dicts {addr, size, file_off, max_prot, init_prot}
- for one chunk file.
-
- Only the standard dyld_cache_mapping_info entries are used. Slide-info
- mappings (`mappingWithSlideOffset`) are ignored — for our purposes we
- only care about which virtual address comes from which file offset,
- and the standard mappings cover that.
-
- `init_prot` is the VM_PROT mask: VM_PROT_READ=1, VM_PROT_WRITE=2,
- VM_PROT_EXECUTE=4.
- """
- with open(path, "rb") as f:
- head = f.read(0x100)
- magic = head[:16].rstrip(b"\x00")
- # Modern arm64e caches start with "dyld_v1 arm64e"
- if not magic.startswith(b"dyld"):
- return []
-
- mapping_off = struct.unpack_from("<I", head, 16)[0]
- mapping_cnt = struct.unpack_from("<I", head, 20)[0]
- if mapping_cnt > 64 or mapping_off > 0x10000:
- # sanity bounds
- return []
-
- with open(path, "rb") as f:
- f.seek(mapping_off)
- raw = f.read(mapping_cnt * 32)
-
- out = []
- for i in range(mapping_cnt):
- off = i * 32
- addr, size, file_off, max_prot, init_prot = \
- struct.unpack_from("<QQQII", raw, off)
- out.append({
- "addr": addr, "size": size, "file_off": file_off,
- "max_prot": max_prot, "init_prot": init_prot,
- })
- return out
-
-
-def resolve_local_symbol(chunks_dir, name):
- """Resolve a symbol (including an ObjC method symbol) to its vmaddr via the
- DSC's own `.symbols` local-symbol table (in-image; no repo-exported dumps).
- ipsw `symaddr -a` times out on this cache, so parse the table directly."""
- sym = os.path.join(chunks_dir, "dyld_shared_cache_arm64e.symbols")
- with open(sym, "rb") as f:
- hdr = f.read(0x100)
- if hdr[:15] != b"dyld_v1 arm64e":
- raise RuntimeError(f"unexpected .symbols magic in {sym}")
- local_off = struct.unpack_from("<Q", hdr, 72)[0]
- f.seek(local_off)
- nlist_off, nlist_cnt, str_off, str_sz, _eo, _ec = struct.unpack("<IIIIII", f.read(24))
- f.seek(local_off + str_off)
- strings = f.read(str_sz)
- f.seek(local_off + nlist_off)
- nl = f.read(nlist_cnt * 16)
- want = name.encode()
- for i in range(nlist_cnt):
- n_strx, _t, _s, _d, n_value = struct.unpack_from("<IBBHQ", nl, i * 16)
- if n_strx >= len(strings):
- continue
- end = strings.find(b"\x00", n_strx)
- if strings[n_strx:end] == want:
- return n_value
- raise RuntimeError(f"could not resolve {name!r} in .symbols")
-
-
-def _disasm_function(chunks, vma, max_insns):
- """Disassemble from `vma` up to the first ret/retab (function end) or
- `max_insns`, whichever comes first. `chunks` is a DSCChunks."""
- buf = chunks.bytes_at_vma(vma, max_insns * 4)
- insns = []
- for insn in _cs.disasm(buf, vma):
- insns.append(insn)
- if insn.mnemonic in ("ret", "retab"):
- break
- return insns
-
-
-class DSCChunks:
- """Lazy random-access byte view over a chunked dyld shared cache."""
-
- def __init__(self, chunks_dir):
- self.chunks_dir = chunks_dir
- self._chunk_paths = _enumerate_chunks(chunks_dir)
- if not self._chunk_paths:
- raise FileNotFoundError(
- f"No dyld_shared_cache_arm64e* chunks found under {chunks_dir!r}"
- )
-
- # Build (addr_start, addr_end, file_off, init_prot, chunk_path) ranges.
- ranges = []
- for cp in self._chunk_paths:
- for m in _parse_chunk_mappings(cp):
- if m["size"] == 0:
- continue
- ranges.append(
- (
- m["addr"],
- m["addr"] + m["size"],
- m["file_off"],
- m["init_prot"],
- cp,
- )
- )
- if not ranges:
- raise RuntimeError(
- f"No DSC mappings parsed under {chunks_dir!r} — "
- f"chunks present but headers unrecognised"
- )
-
- # Sort by addr_start for binary-search later.
- ranges.sort(key=lambda r: r[0])
- self._ranges = ranges
-
- def __repr__(self):
- return (
- f"DSCChunks({self.chunks_dir!r}, "
- f"{len(self._chunk_paths)} chunk(s), "
- f"{len(self._ranges)} mapping(s), "
- f"vm 0x{self._ranges[0][0]:X}..0x{self._ranges[-1][1]:X})"
- )
-
- def find_chunk_for_vma(self, vma):
- """Return (chunk_path, file_offset) for `vma`, or None if unmapped."""
- # Linear scan is fine; mapping count is < ~80.
- for addr_start, addr_end, file_off, _init_prot, cp in self._ranges:
- if addr_start <= vma < addr_end:
- return (cp, file_off + (vma - addr_start))
- return None
-
- def bytes_at_vma(self, vma, length):
- """Read `length` bytes starting at `vma`. Must be contained in one
- mapping (we don't stitch across mappings)."""
- loc = self.find_chunk_for_vma(vma)
- if loc is None:
- raise KeyError(f"vma 0x{vma:X} is not mapped by any chunk")
- cp, foff = loc
- with open(cp, "rb") as f:
- f.seek(foff)
- data = f.read(length)
- if len(data) != length:
- raise IOError(
- f"short read at vma 0x{vma:X} ({len(data)} of {length})"
- )
- return data
-
- def write_at_vma(self, vma, data):
- """Persist `data` bytes at `vma` to the right chunk file. The
- target span must lie within a single mapping."""
- loc = self.find_chunk_for_vma(vma)
- if loc is None:
- raise KeyError(f"vma 0x{vma:X} is not mapped by any chunk")
- # Verify the entire span is in this mapping.
- end_loc = self.find_chunk_for_vma(vma + len(data) - 1)
- if end_loc is None or end_loc[0] != loc[0]:
- raise ValueError(
- f"write at vma 0x{vma:X} length {len(data)} "
- 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 ----
-
- VM_PROT_EXECUTE = 4
-
- def mappings(self):
- """Return [(vmaddr_start, vmaddr_end, file_offset, init_prot, chunk_path)]."""
- return list(self._ranges)
-
- def find_string_vmas(self, needle):
- """Return all vmaddrs where `needle` (bytes) appears within a single
- mapping, anchored either at the mapping start or after a NUL byte.
-
- Restricted to executable (RX) mappings — `__TEXT` segments where
- `__TEXT,__cstring` lives. This skips the giant LINKEDIT and
- __DATA/__DATA_CONST mappings entirely.
- """
- out = []
- for addr_start, addr_end, file_off, init_prot, cp in self._ranges:
- if not (init_prot & self.VM_PROT_EXECUTE):
- continue
- size = addr_end - addr_start
- with open(cp, "rb") as f:
- f.seek(file_off)
- buf = f.read(size)
- i = 0
- while True:
- p = buf.find(needle, i)
- if p < 0:
- break
- if p == 0 or buf[p - 1] == 0:
- out.append(addr_start + p)
- i = p + 1
- return out
-
- def read_at_vma(self, vma, length, *, allow_short=False):
- """Read `length` bytes starting at `vma`, contained in a single
- mapping. With `allow_short=True`, returns whatever is available
- within the containing mapping instead of raising."""
- for addr_start, addr_end, file_off, _init_prot, cp in self._ranges:
- if addr_start <= vma < addr_end:
- avail = addr_end - vma
- want = length if avail >= length else (avail if allow_short else 0)
- if want == 0:
- raise IOError(
- f"read at vma 0x{vma:X} len {length} would cross "
- f"a chunk boundary"
- )
- with open(cp, "rb") as f:
- f.seek(file_off + (vma - addr_start))
- data = f.read(want)
- return data
- raise KeyError(f"vma 0x{vma:X} is not mapped by any chunk")
-
- _MH_MAGIC_64_LE = b"\xcf\xfa\xed\xfe"
-
- def find_macho_header_before(self, vma, *, max_walk=64 * 1024 * 1024):
- """Walk backwards from `vma` looking for a Mach-O 64 header
- (magic 0xfeedfacf) at a page boundary. Returns the magic's
- vmaddr, or None if not found within `max_walk` bytes inside the
- same mapping.
-
- Mach-O headers in the DSC are placed at page-aligned vmaddrs at
- the start of each dylib's __TEXT segment, and an arm64e iOS
- dylib's header is in the same mapping as its __text section, so
- we only have to search within the containing mapping.
-
- Implementation: read the relevant bytes from disk once and use
- `bytes.rfind` to locate the magic, then accept only page-aligned
- hits. Searching ~36 MiB takes <50 ms in pure Python.
- """
- for addr_start, addr_end, file_off, _init_prot, cp in self._ranges:
- if not (addr_start <= vma < addr_end):
- continue
- local_off = vma - addr_start
- scan_len = min(local_off, max_walk)
- scan_start = local_off - scan_len
- with open(cp, "rb") as f:
- f.seek(file_off + scan_start)
- buf = f.read(scan_len + 4) # +4 so a hit at end is captured
- i = len(buf)
- while True:
- found = buf.rfind(self._MH_MAGIC_64_LE, 0, i)
- if found < 0:
- return None
- candidate_vma = addr_start + scan_start + found
- if (candidate_vma & 0xFFF) == 0:
- return candidate_vma
- # Keep searching backwards.
- i = found
- # unreachable
- return None
-
- def read_install_name_at(self, header_vma):
- """Given the vmaddr of a Mach-O 64 header in the DSC, return the
- dylib's install name (LC_ID_DYLIB), or None if the file isn't a
- dylib or the LC isn't present.
- """
- # Read the first 64KB of LCs (more than enough).
- try:
- head = self.read_at_vma(header_vma, 64 * 1024, allow_short=True)
- except (KeyError, IOError):
- return None
- if struct.unpack_from("<I", head, 0)[0] != 0xFEEDFACF:
- return None
- ncmds = struct.unpack_from("<I", head, 16)[0]
- sizeofcmds = struct.unpack_from("<I", head, 20)[0]
- # Sanity-bound the LC walk.
- if ncmds > 4096 or sizeofcmds > 64 * 1024:
- return None
- o = 32
- for _ in range(ncmds):
- if o + 8 > len(head):
- return None
- cmd, cmdsize = struct.unpack_from("<II", head, o)
- if cmdsize < 8 or cmdsize > 64 * 1024:
- return None
- if cmd == 0xD: # LC_ID_DYLIB
- # struct dylib_command { cmd, cmdsize, dylib { name(uint32 offset),
- # timestamp, current_version, compatibility_version } }
- name_off_in_cmd = struct.unpack_from("<I", head, o + 8)[0]
- name_pos = o + name_off_in_cmd
- if name_pos >= len(head) or name_pos >= o + cmdsize:
- return None
- end = head.find(b"\x00", name_pos, o + cmdsize)
- if end < 0:
- return None
- try:
- return head[name_pos:end].decode("utf-8")
- except UnicodeDecodeError:
- return head[name_pos:end].decode("latin-1")
- o += cmdsize
- if o > sizeofcmds + 32:
- return None
- return None
diff --git a/scripts/patchers/cfw_dsc_codesign.py b/scripts/patchers/cfw_dsc_codesign.py
deleted file mode 100644
index 5134625f..00000000
--- a/scripts/patchers/cfw_dsc_codesign.py
+++ /dev/null
@@ -1,316 +0,0 @@
-"""DSC code-signature page-hash re-attestation.
-
-Background
-----------
-On iPhone17,3 / iOS 26.1 with TXM (`codeSigningMonitor == 2`) enabled,
-the kernel defers per-page hash validation to TXM (see source comments
-in `research/reference/xnu/osfmk/vm/vm_fault.c:2763-2780`). TXM has
-the original slot hashes baked in via the registered DSC signature, so
-any byte-mangle inside an executable mapping causes
-`KERN_PROTECTION_FAILURE` / `CODESIGNING / Invalid Page` SIGKILL on
-the first demand-page-in of the affected 16 KiB page. (An earlier
-XNU-side `_cs_validate_page` short-circuit kernel patch was attempted
-and shipped, then removed — it never fires on this hardware because
-the CSM-defer gate in `vm_fault_cs_check_violation` runs first.)
-
-To make a byte-mangled DSC dylib executable again, we recompute the
-SHA-256 slot hash for the 16 KiB page that contains the modification
-and overwrite the matching entry in the chunk's `CS_CodeDirectory`.
-
-DSC code-signature layout (verified empirically on
-`iPhone17,3_26.1_23B85` chunked DSC):
-
- Each chunk file has a `dyld_cache_header`:
- u64 codeSignatureOffset @ 0x28 (chunk-file relative)
- u64 codeSignatureSize @ 0x30
-
- At `codeSignatureOffset` there's a `CS_SuperBlob` (big-endian):
- u32 magic = 0xFADE0CC0
- u32 length
- u32 count
- CS_BlobIndex blobs[count]:
- u32 type
- u32 offset (within SuperBlob)
-
- The CSSLOT_CODEDIRECTORY entry (type==0) points at a
- `CS_CodeDirectory` blob (also big-endian):
- u32 magic = 0xFADE0C02
- u32 length
- u32 version
- u32 flags
- u32 hashOffset (within blob — to slot[0])
- u32 identOffset
- u32 nSpecialSlots
- u32 nCodeSlots
- u32 codeLimit (chunk-file byte range covered)
- u8 hashSize (32 for SHA-256)
- u8 hashType (2 for SHA-256)
- u8 platform
- u8 pageSize (log2 — 14 == 16 KiB)
- u32 spare2
- ... (more in later versions)
-
- Slot N stores SHA-256 of chunk bytes [N*pageSize, (N+1)*pageSize)
- and lives at chunk-file offset:
- codeSignatureOffset + cd_offset_in_superblob
- + hashOffset + N * hashSize
-
-DSC dylibs do NOT carry their own LC_CODE_SIGNATURE — only the
-chunk-level signature applies. Page indexing is against the chunk
-file offset, not the dylib's __TEXT offset.
-
-CDHash side effect (empirically benign)
----------------------------------------
-Modifying slot hashes changes the CodeDirectory's contents, which
-changes its CDHash (SHA-256 of the CD blob). The existing JB kernel
-patch `patch_amfi_cdhash_in_trustcache` bypasses AMFI's per-image
-CDHash trust-cache lookup, and TXM accepts the modified-CDHash DSC
-at cache-load time on iPhone17,3 / iOS 26.1 (verified: device boots
-with re-attested chunks). If a future build introduces a stricter
-CDHash check at DSC mount, the next step would be a TXM-side bypass
-at cache load — at the time this module was written that wasn't
-needed.
-
-"""
-
-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
-CSMAGIC_CODEDIRECTORY = 0xFADE0C02
-CSSLOT_CODEDIRECTORY = 0
-
-CS_HASHTYPE_SHA256 = 2
-
-
-def _read_chunk_cd_blob(chunk_path):
- """Locate the chunk's CS_CodeDirectory.
-
- Returns a dict with the fields we need to write back slot hashes:
- cd_file_off (chunk-file offset of the CD blob)
- cd_length (total length of the CD blob in bytes)
- hash_offset (offset within the CD blob to slot[0])
- hash_size (bytes per slot — 32 for SHA-256)
- n_code_slots (number of slots)
- code_limit (chunk byte range covered)
- page_size (1 << pageSize_log2 — typically 16384)
-
- Returns None if the chunk file isn't recognised (header magic
- mismatch, no CodeDirectory in SuperBlob, etc.).
- """
- with open(chunk_path, "rb") as f:
- head = f.read(0x100)
- if not head.startswith(b"dyld_"):
- return None
-
- # codeSignatureOffset at 0x28, codeSignatureSize at 0x30 (both u64 LE).
- cs_off, cs_size = struct.unpack_from("<QQ", head, 0x28)
- if cs_off == 0 or cs_size == 0:
- return None
-
- # SuperBlob (big-endian).
- with open(chunk_path, "rb") as f:
- f.seek(cs_off)
- sb_head = f.read(12)
- if len(sb_head) != 12:
- return None
- sb_magic, sb_length, sb_count = struct.unpack(">III", sb_head)
- if sb_magic != CSMAGIC_EMBEDDED_SIGNATURE:
- return None
- if sb_length > cs_size or sb_count > 256:
- return None
-
- # Read the BlobIndex array.
- with open(chunk_path, "rb") as f:
- f.seek(cs_off + 12)
- idx_bytes = f.read(sb_count * 8)
- if len(idx_bytes) != sb_count * 8:
- return None
-
- cd_off_in_sb = None
- for i in range(sb_count):
- slot_type, slot_off = struct.unpack_from(">II", idx_bytes, i * 8)
- if slot_type == CSSLOT_CODEDIRECTORY:
- cd_off_in_sb = slot_off
- break
- if cd_off_in_sb is None:
- return None
-
- cd_file_off = cs_off + cd_off_in_sb
-
- # CD blob header (big-endian).
- with open(chunk_path, "rb") as f:
- f.seek(cd_file_off)
- cd_head = f.read(44)
- if len(cd_head) != 44:
- return None
- cd_magic, cd_length, _version, _flags = struct.unpack_from(">IIII", cd_head, 0)
- if cd_magic != CSMAGIC_CODEDIRECTORY:
- return None
- hash_offset, _ident_offset, _n_special, n_code_slots, code_limit = \
- struct.unpack_from(">IIIII", cd_head, 16)
- hash_size = cd_head[36]
- hash_type = cd_head[37]
- page_size_log2 = cd_head[39]
- if hash_type != CS_HASHTYPE_SHA256 or hash_size != 32:
- # We only know how to recompute SHA-256 slots. Other hash types
- # (SHA-1, SHA-256-truncated) would need additional code paths.
- return None
- page_size = 1 << page_size_log2
- if page_size == 0 or page_size > (1 << 20):
- return None
-
- return {
- "cd_file_off": cd_file_off,
- "cd_length": cd_length,
- "hash_offset": hash_offset,
- "hash_size": hash_size,
- "n_code_slots": n_code_slots,
- "code_limit": code_limit,
- "page_size": page_size,
- }
-
-
-def reattest_modified_pages(chunks, modified_vmas, *, dry_run=False, verbose=True):
- """Recompute and write SHA-256 slot hashes for every 16 KiB page
- that contains a `modified_vmas` entry.
-
- `chunks` a DSCChunks instance.
- `modified_vmas` iterable of vmaddrs we wrote to. Each is reduced
- to its containing chunk + page; duplicate pages
- are coalesced.
- `dry_run` if True, log only, do not write.
-
- Returns a list of dicts (one per page recomputed) for diagnostics:
- {chunk_path, page_index, chunk_off, sha256_before, sha256_after}
- """
- # Group vmas by chunk → set of page indices to recompute.
- chunks_pages = {} # chunk_path → set(page_index)
- chunk_meta = {} # chunk_path → cd metadata (lazy-loaded)
-
- for vma in modified_vmas:
- loc = chunks.find_chunk_for_vma(vma)
- if loc is None:
- if verbose:
- print(f" [-] re-attest: vma 0x{vma:X} not mapped in any chunk")
- continue
- cp, foff = loc
- meta = chunk_meta.get(cp)
- if meta is None:
- meta = _read_chunk_cd_blob(cp)
- if meta is None:
- if verbose:
- print(f" [-] re-attest: chunk {os.path.basename(cp)!r} "
- f"has no recognised CS_SuperBlob/CD — skipping")
- # Cache the None so we don't re-probe.
- chunk_meta[cp] = False
- continue
- chunk_meta[cp] = meta
- elif meta is False:
- continue
- page_size = meta["page_size"]
- page_index = foff // page_size
- if page_index >= meta["n_code_slots"]:
- if verbose:
- print(f" [-] re-attest: vma 0x{vma:X} -> page {page_index} "
- f"is past nCodeSlots ({meta['n_code_slots']}) in "
- f"{os.path.basename(cp)} — skipping")
- continue
- if (page_index + 1) * page_size > meta["code_limit"]:
- if verbose:
- print(f" [-] re-attest: vma 0x{vma:X} -> page {page_index} "
- f"overruns codeLimit (0x{meta['code_limit']:X}) in "
- f"{os.path.basename(cp)} — skipping")
- continue
- chunks_pages.setdefault(cp, set()).add(page_index)
-
- if not chunks_pages:
- if verbose:
- print(f" [.] re-attest: no eligible pages")
- return []
-
- diagnostics = []
- total = 0
- for cp, pages in chunks_pages.items():
- meta = chunk_meta[cp]
- cd_file_off = meta["cd_file_off"]
- hash_offset = meta["hash_offset"]
- hash_size = meta["hash_size"]
- page_size = meta["page_size"]
-
- # Open once per chunk for read/write.
- mode = "rb" if dry_run else "r+b"
- with open(cp, mode) as f:
- for page_index in sorted(pages):
- page_off = page_index * page_size
- slot_off = cd_file_off + hash_offset + page_index * hash_size
-
- f.seek(page_off)
- page_data = f.read(page_size)
- if len(page_data) != page_size:
- if verbose:
- print(f" [-] re-attest: short read at "
- f"page {page_index} of {os.path.basename(cp)} "
- f"(got {len(page_data)} of {page_size})")
- continue
- new_hash = hashlib.sha256(page_data).digest()
-
- f.seek(slot_off)
- old_hash = f.read(hash_size)
-
- if old_hash == new_hash:
- if verbose:
- print(f" [.] re-attest: page {page_index} of "
- f"{os.path.basename(cp)} slot already matches "
- f"(no-op)")
- continue
-
- if not dry_run:
- f.seek(slot_off)
- f.write(new_hash)
-
- if verbose:
- action = "would write" if dry_run else "wrote"
- print(f" [+] re-attest: {action} slot {page_index} of "
- f"{os.path.basename(cp)} "
- f"({old_hash.hex()[:8]}.. -> {new_hash.hex()[:8]}..)")
- diagnostics.append({
- "chunk_path": cp,
- "page_index": page_index,
- "chunk_off": page_off,
- "slot_off": slot_off,
- "sha256_before": old_hash.hex(),
- "sha256_after": new_hash.hex(),
- })
- total += 1
-
- if verbose:
- 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
deleted file mode 100644
index 1ef6fdec..00000000
--- a/scripts/patchers/cfw_macho_codesign.py
+++ /dev/null
@@ -1,366 +0,0 @@
-"""Standalone Mach-O code-signature page-hash re-attestation.
-
-Parallel to `cfw_dsc_codesign.py` but for standalone Mach-Os instead of
-DSC chunks. The technique is the same — recompute the SHA-256 of each
-modified page and overwrite the matching slot in `CS_CodeDirectory` —
-but the parse path and tail-slot handling differ.
-
-Layout (single-arch arm64e Mach-O, verified on
-`iPhone17,3_26.1_23B85_Restore_extracted/usr/libexec/watchdogd`):
-
- LC_CODE_SIGNATURE (cmd=0x1d) in the Mach-O's own load commands:
- u32 dataoff — file offset of the embedded CS_SuperBlob
- u32 datasize — total bytes of the signature
-
- At `dataoff` there is a CS_SuperBlob (big-endian):
- u32 magic = 0xFADE0CC0
- u32 length
- u32 count
- CS_BlobIndex blobs[count]:
- u32 type
- u32 offset (within SuperBlob)
-
- Every blob whose magic is 0xFADE0C02 is a CodeDirectory. There can
- be more than one (alt-CD with a different hashType for legacy SHA-1
- consumers). We update every CD whose hashType is SHA-256 — anything
- else is left alone and reported, so the caller can decide whether to
- fail.
-
- A CD covers `[0, codeLimit)` of the Mach-O file. Slot N's hash
- covers bytes `[N * pageSize, min((N+1) * pageSize, codeLimit))`. The
- tail slot is typically short: `codeLimit - last_slot_start` bytes,
- not a full page. That is the single most likely source of the
- previous standalone-reattest regression — DSC chunks are aligned so
- the tail-slot quirk doesn't surface there.
-
-Page size is read from `pageSizeLog2` in the CD header. On the binaries
-we care about it is 12 (4 KiB), not 14 (16 KiB as in DSC chunks).
-
-CDHash side effect (same as DSC case)
--------------------------------------
-Rewriting slot hashes mutates the CD blob, which mutates the CD's
-SHA-256 (the cdHash). The existing JB kernel patch
-`patch_amfi_cdhash_in_trustcache` short-circuits AMFI's trust-cache
-lookup so a mutated cdHash isn't rejected at execve. On iPhone17,3 /
-iOS 26.1 with `codeSigningMonitor == 2`, TXM accepts the modified-CD
-binary on demand-page-in as long as the per-page slot hashes match,
-which is exactly what this module guarantees.
-
-Public entrypoint:
- reattest_modified_offsets(filepath, file_offsets, *, dry_run, verbose)
- -> list of diagnostic dicts (one per slot updated)
-
-The caller passes the file offsets of bytes it modified; this module
-takes care of mapping each offset to its containing page, deduping,
-recomputing the SHA-256 of the page's actual on-disk bytes, and writing
-the new hash back into every CD's slot table.
-
-Hash types we know how to recompute:
- SHA-256 (CS_HASHTYPE_SHA256 = 2)
-
-Other types (SHA-1 = 1, SHA-256-truncated = 4, SHA-384 = 3) are
-reported but not updated. If a binary needs those it will need
-additional code paths.
-"""
-
-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
-CSMAGIC_CODEDIRECTORY = 0xFADE0C02
-
-CS_HASHTYPE_SHA1 = 1
-CS_HASHTYPE_SHA256 = 2
-CS_HASHTYPE_SHA384 = 3
-CS_HASHTYPE_SHA256_TRUNCATED = 4
-
-LC_CODE_SIGNATURE = 0x1D
-
-MH_MAGIC_64 = 0xFEEDFACF
-
-
-def _find_lc_code_signature(data):
- """Return (dataoff, datasize) for the binary's LC_CODE_SIGNATURE, or None."""
- magic = struct.unpack_from("<I", data, 0)[0]
- if magic != MH_MAGIC_64:
- return None
- ncmds = struct.unpack_from("<I", data, 16)[0]
- off = 32 # sizeof(mach_header_64)
- for _ in range(ncmds):
- cmd, cmdsize = struct.unpack_from("<II", data, off)
- if cmd == LC_CODE_SIGNATURE:
- dataoff, datasize = struct.unpack_from("<II", data, off + 8)
- return dataoff, datasize
- off += cmdsize
- return None
-
-
-def _parse_superblob(data, sb_off):
- """Return list of (slot_type, blob_abs_off, blob_magic). None on error."""
- if sb_off + 12 > len(data):
- return None
- sb_magic, sb_length, sb_count = struct.unpack_from(">III", data, sb_off)
- if sb_magic != CSMAGIC_EMBEDDED_SIGNATURE:
- return None
- if sb_count > 256 or sb_off + sb_length > len(data):
- return None
- out = []
- for i in range(sb_count):
- st, bo = struct.unpack_from(">II", data, sb_off + 12 + i * 8)
- blob_abs = sb_off + bo
- if blob_abs + 4 > len(data):
- return None
- bm = struct.unpack_from(">I", data, blob_abs)[0]
- out.append((st, blob_abs, bm))
- return out
-
-
-def _parse_code_directory(data, cd_off):
- """Parse a CodeDirectory blob. Returns a dict of fields, or None.
-
- Fields:
- slot_type — left blank here, filled in by caller from the BlobIndex
- cd_off — absolute file offset of the CD blob
- cd_length — length of the CD blob
- hash_offset — offset within the CD blob to slot[0] (code slot 0)
- hash_size — bytes per slot
- hash_type — CS_HASHTYPE_*
- page_size — 1 << pageSizeLog2
- n_code_slots
- code_limit — covered byte range of the file
- """
- if cd_off + 44 > len(data):
- return None
- fields = struct.unpack_from(">IIIIIIIII", data, cd_off)
- cd_magic, cd_length, _version, _flags = fields[0], fields[1], fields[2], fields[3]
- if cd_magic != CSMAGIC_CODEDIRECTORY:
- return None
- hash_offset = fields[4]
- _ident_offset = fields[5]
- _n_special = fields[6]
- n_code_slots = fields[7]
- code_limit = fields[8]
- hash_size = data[cd_off + 36]
- hash_type = data[cd_off + 37]
- page_size_log2 = data[cd_off + 39]
- page_size = 1 << page_size_log2 if 0 < page_size_log2 < 24 else 0
- if page_size == 0:
- return None
- if cd_off + cd_length > len(data):
- return None
- if cd_off + hash_offset + n_code_slots * hash_size > len(data):
- return None
- return {
- "cd_off": cd_off,
- "cd_length": cd_length,
- "hash_offset": hash_offset,
- "hash_size": hash_size,
- "hash_type": hash_type,
- "page_size": page_size,
- "page_size_log2": page_size_log2,
- "n_code_slots": n_code_slots,
- "code_limit": code_limit,
- }
-
-
-def _find_code_directories(data):
- """Find every CS_CodeDirectory in the binary's LC_CODE_SIGNATURE blob.
-
- Returns a list of dicts (one per CD), each with the fields from
- `_parse_code_directory` plus `slot_type` from the SuperBlob's
- BlobIndex.
- """
- cs = _find_lc_code_signature(data)
- if cs is None:
- return None
- cs_off, _cs_size = cs
- sb = _parse_superblob(data, cs_off)
- if sb is None:
- return None
- cds = []
- for slot_type, blob_abs, blob_magic in sb:
- if blob_magic != CSMAGIC_CODEDIRECTORY:
- continue
- cd = _parse_code_directory(data, blob_abs)
- if cd is None:
- continue
- cd["slot_type"] = slot_type
- cds.append(cd)
- return cds
-
-
-def _page_bounds(file_off, page_size, code_limit):
- """Return (page_index, page_start, page_end_exclusive) for the page
- that contains file_off. page_end_exclusive is clamped to code_limit
- so the tail slot covers the actual signed byte range, not a full
- page beyond the end of the CD-covered region.
-
- Returns None if file_off is past code_limit (not covered by CD).
- """
- if file_off >= code_limit:
- return None
- page_index = file_off // page_size
- page_start = page_index * page_size
- page_end = min(page_start + page_size, code_limit)
- return page_index, page_start, page_end
-
-
-def reattest_modified_offsets(
- filepath, file_offsets, *, dry_run=False, verbose=True
-):
- """Recompute slot hashes for every page touched by `file_offsets`.
-
- `file_offsets` iterable of byte offsets within the Mach-O file
- that the caller has just modified. They get
- deduplicated to a set of (cd, page_index) pairs.
- `dry_run` if True, log only, do not write.
- `verbose` if True, print per-slot progress.
-
- Returns a list of diagnostic dicts:
- {cd_off, slot_type, page_index, page_start, page_end,
- hash_offset_in_file, before, after}
-
- Raises ValueError on a malformed signature blob — that's a hard
- error for any caller (the binary was not what we expected).
- """
- if not file_offsets:
- if verbose:
- print(f" [.] re-attest: no offsets given for {filepath}")
- return []
-
- with open(filepath, "rb") as f:
- data = f.read()
-
- cds = _find_code_directories(data)
- if cds is None:
- raise ValueError(
- f"{filepath}: no LC_CODE_SIGNATURE / CS_CodeDirectory found"
- )
- if not cds:
- raise ValueError(
- f"{filepath}: LC_CODE_SIGNATURE present but no CodeDirectory blobs"
- )
-
- if verbose:
- kinds = []
- for cd in cds:
- kinds.append(
- f"slot_type=0x{cd['slot_type']:x} hashType={cd['hash_type']} "
- f"pageSize={cd['page_size']} nSlots={cd['n_code_slots']} "
- f"codeLimit=0x{cd['code_limit']:x}"
- )
- print(f" [.] re-attest {filepath}: {len(cds)} CD(s): " + "; ".join(kinds))
-
- # Build (cd_index, page_index) -> (page_start, page_end) set.
- # Different CDs may have different page sizes in theory; we keep
- # them separate.
- work = {} # (cd_index, page_index) -> (page_start, page_end)
- skipped_non_sha256 = 0
- for cd_i, cd in enumerate(cds):
- if cd["hash_type"] != CS_HASHTYPE_SHA256:
- skipped_non_sha256 += 1
- continue
- for foff in file_offsets:
- pb = _page_bounds(foff, cd["page_size"], cd["code_limit"])
- if pb is None:
- if verbose:
- print(
- f" [-] re-attest: file off 0x{foff:X} past codeLimit "
- f"0x{cd['code_limit']:X} (cd_index={cd_i}) — skipping"
- )
- continue
- page_index, page_start, page_end = pb
- if page_index >= cd["n_code_slots"]:
- if verbose:
- print(
- f" [-] re-attest: page {page_index} >= "
- f"nCodeSlots {cd['n_code_slots']} (cd_index={cd_i}) — skipping"
- )
- continue
- work[(cd_i, page_index)] = (page_start, page_end)
-
- if skipped_non_sha256 and verbose:
- print(
- f" [-] re-attest: skipped {skipped_non_sha256} non-SHA256 "
- f"CD(s) (hashType != 2). If a legacy SHA-1 alt-CD exists for "
- f"this binary it is NOT being recomputed."
- )
-
- if not work:
- if verbose:
- print(f" [.] re-attest: no eligible slots for {filepath}")
- return []
-
- diagnostics = []
- mode = "rb" if dry_run else "r+b"
- with open(filepath, mode) as f:
- for (cd_i, page_index), (page_start, page_end) in sorted(work.items()):
- cd = cds[cd_i]
- slot_off = (
- cd["cd_off"] + cd["hash_offset"] + page_index * cd["hash_size"]
- )
- page_bytes = data[page_start:page_end]
- new_hash = hashlib.sha256(page_bytes).digest()
- old_hash = data[slot_off : slot_off + cd["hash_size"]]
-
- if old_hash == new_hash:
- if verbose:
- print(
- f" [.] re-attest: cd_index={cd_i} slot {page_index} "
- f"already matches ({page_end - page_start} bytes) — no-op"
- )
- continue
-
- if not dry_run:
- f.seek(slot_off)
- f.write(new_hash)
-
- if verbose:
- action = "would write" if dry_run else "wrote"
- tail_note = ""
- if page_end - page_start != cd["page_size"]:
- tail_note = f" [tail, {page_end - page_start}B]"
- print(
- f" [+] re-attest: {action} cd_index={cd_i} "
- f"slot {page_index}{tail_note} "
- f"({old_hash.hex()[:8]}.. -> {new_hash.hex()[:8]}..)"
- )
- diagnostics.append(
- {
- "cd_off": cd["cd_off"],
- "slot_type": cd["slot_type"],
- "page_index": page_index,
- "page_start": page_start,
- "page_end": page_end,
- "hash_offset_in_file": slot_off,
- "before": old_hash.hex(),
- "after": new_hash.hex(),
- }
- )
-
- 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
deleted file mode 100644
index 98b6727c..00000000
--- a/scripts/patchers/cfw_patch_build_version.py
+++ /dev/null
@@ -1,114 +0,0 @@
-#!/usr/bin/env python3
-"""cfw_patch_build_version.py — rewrite ProductBuildVersion in SystemVersion.plist.
-
-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,
-etc.) read it from `/System/Library/CoreServices/SystemVersion.plist` —
-the `ProductBuildVersion` key. A copy of the same plist also lives at
-`/private/preboot/Cryptexes/OS/System/Library/CoreServices/SystemVersion.plist`
-for Cryptex-side OS-version queries.
-
-This patcher takes a plist path and rewrites `ProductBuildVersion` to a
-target value (e.g. "23F77"). It auto-detects XML vs binary plist format
-and writes back in the same format.
-
-The change DOES NOT affect:
- - `sysctl kern.osversion` — populated at boot from a kernel global
- initialized from boot args; the kernel image itself doesn't carry
- "23B85" as a const cstring. (The kernel for vphone600 was built
- against "23B78", visible in kext Info.plist embedded blobs.)
- - `ProductVersion` (e.g. "26.1") — left at the iOS marketing version.
- - DSC dylib internal constants — `23B85` doesn't appear in any DSC
- chunk as a build identifier; the one apparent hit is a Swift
- mangled-name UUID-uniquing substring.
-
-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"
-
-
-def patch_plist(path: str, target: str, *, dry_run: bool = False) -> bool:
- """Rewrite the ProductBuildVersion key. Returns True if the file was
- rewritten, False if it was already in the target state.
- """
- with open(path, "rb") as f:
- data = f.read()
-
- # Detect format: XML plists start with '<?xml' or '<plist', binary
- # plists start with the magic 'bplist00' (or similar).
- is_xml = data.lstrip().startswith(b"<")
- fmt = plistlib.FMT_XML if is_xml else plistlib.FMT_BINARY
-
- try:
- plist = plistlib.loads(data)
- except Exception as e:
- raise ValueError(f"cannot parse as plist: {e}")
-
- if not isinstance(plist, dict):
- raise ValueError(
- f"top-level plist is {type(plist).__name__}, expected dict"
- )
-
- current = plist.get(KEY)
- if current is None:
- raise ValueError(f"no {KEY!r} key present")
- if not isinstance(current, str):
- raise ValueError(
- f"{KEY!r} is {type(current).__name__}, expected str"
- )
-
- if current == target:
- print(f" [.] {path}: {KEY} already = {target!r}")
- return False
-
- print(f" [+] {path}: {KEY} {current!r} -> {target!r}")
- plist[KEY] = target
-
- if dry_run:
- print(f" [.] dry-run — not writing back")
- 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 [--emit-records <dir>] "
- "<plist> <new_build_version> [--dry-run]",
- file=sys.stderr,
- )
- return 2
- path, target = argv[1], argv[2]
- dry_run = "--dry-run" in argv[3:]
- try:
- patch_plist(path, target, dry_run=dry_run)
- except Exception as e:
- print(f"[-] {type(e).__name__}: Unable to patch {path}: {e}", file=sys.stderr)
- return 1
- return 0
-
-
-if __name__ == "__main__":
- sys.exit(_main(sys.argv))
diff --git a/scripts/patchers/cfw_patch_cache_loader.py b/scripts/patchers/cfw_patch_cache_loader.py
deleted file mode 100644
index fa5aeb7a..00000000
--- a/scripts/patchers/cfw_patch_cache_loader.py
+++ /dev/null
@@ -1,218 +0,0 @@
-"""launchd cache loader patch module."""
-
-from .cfw_asm import *
-from .cfw_asm import _log_asm, _cs
-from . import cfw_records as records
-
-
-def patch_launchd_cache_loader(filepath):
- """NOP the cache validation check in launchd_cache_loader.
-
- Anchor strategy:
- Search for "unsecure_cache" substring, resolve to full null-terminated
- string start, find ADRP+ADD xref to it, NOP the nearby cbz/cbnz branch.
-
- The binary checks boot-arg "launchd_unsecure_cache=" — if not found,
- it skips the unsecure path via a conditional branch. NOPping that branch
- allows modified launchd.plist to be loaded.
- """
- data = bytearray(open(filepath, "rb").read())
- sections = parse_macho_sections(data)
-
- text_sec = find_section(sections, "__TEXT,__text")
- if not text_sec:
- print(" [-] __TEXT,__text not found")
- return False
-
- text_va, text_size, text_foff = text_sec
-
- # Strategy 1: Search for anchor strings in __cstring
- # Code always references the START of a C string, so after finding a
- # substring match, back-scan to the enclosing string's first byte.
- anchor_strings = [
- b"unsecure_cache",
- b"unsecure",
- b"cache_valid",
- b"validation",
- ]
-
- for anchor_str in anchor_strings:
- anchor_off = data.find(anchor_str)
- if anchor_off < 0:
- continue
-
- # Find which section this belongs to and compute VA
- anchor_sec_foff = -1
- anchor_sec_va = -1
- for sec_name, (sva, ssz, sfoff) in sections.items():
- if sfoff <= anchor_off < sfoff + ssz:
- anchor_sec_foff = sfoff
- anchor_sec_va = sva
- break
-
- if anchor_sec_foff < 0:
- continue
-
- # Back-scan to the start of the enclosing null-terminated C string.
- # Code loads strings from their beginning, not from a substring.
- str_start_off = _find_cstring_start(data, anchor_off, anchor_sec_foff)
- str_start_va = anchor_sec_va + (str_start_off - anchor_sec_foff)
- substr_va = anchor_sec_va + (anchor_off - anchor_sec_foff)
-
- if str_start_off != anchor_off:
- end = data.index(0, str_start_off)
- full_str = data[str_start_off:end].decode("ascii", errors="replace")
- print(f" Found anchor '{anchor_str.decode()}' inside \"{full_str}\"")
- print(
- f" String start: va:0x{str_start_va:X} (match at va:0x{substr_va:X})"
- )
- else:
- print(f" Found anchor '{anchor_str.decode()}' at va:0x{str_start_va:X}")
-
- # Search __TEXT for ADRP+ADD that resolves to the string START VA
- code = bytes(data[text_foff : text_foff + text_size])
- ref_off = _find_adrp_add_ref(code, text_va, str_start_va)
-
- if ref_off < 0:
- # Also try the exact substring VA as fallback
- ref_off = _find_adrp_add_ref(code, text_va, substr_va)
-
- if ref_off < 0:
- continue
-
- ref_foff = text_foff + (ref_off - text_va)
- print(f" Found string ref at 0x{ref_foff:X}")
-
- # Find conditional branch AFTER the string ref (within +32 instructions).
- # The pattern is: ADRP+ADD (load string) -> BL (call check) -> CBZ/CBNZ (branch on result)
- # So only search forward from the ref, not backwards.
- branch_foff = _find_nearby_branch(data, ref_foff, text_foff, text_size)
- if branch_foff >= 0:
- ctx_start = max(text_foff, branch_foff - 8)
- print(f" Before:")
- _log_asm(data, ctx_start, 5, branch_foff)
-
- data[branch_foff : branch_foff + 4] = NOP
-
- 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
-
- print(" [-] Dynamic anchor not found — all strategies exhausted")
- return False
-
-
-def _find_cstring_start(data, match_off, section_foff):
- """Find the start of the null-terminated C string containing match_off.
-
- Scans backwards from match_off to find the previous null byte (or section
- start). Returns the file offset of the first byte of the enclosing string.
- This is needed because code always references the start of a string, not
- a substring within it.
- """
- pos = match_off - 1
- while pos >= section_foff and data[pos] != 0:
- pos -= 1
- return pos + 1
-
-
-def _find_adrp_add_ref(code, base_va, target_va):
- """Find ADRP+ADD pair that computes target_va in code.
-
- Handles non-adjacent pairs: tracks recent ADRP results per register
- and matches them with ADD instructions up to 8 instructions later.
- """
- target_page = target_va & ~0xFFF
- target_pageoff = target_va & 0xFFF
-
- # Track recent ADRP instructions: reg -> (insn_va, page_value, instruction_index)
- adrp_cache = {}
-
- for off in range(0, len(code) - 4, 4):
- insns = list(_cs.disasm(code[off : off + 4], base_va + off))
- if not insns:
- continue
- insn = insns[0]
- idx = off // 4
-
- if insn.mnemonic == "adrp" and len(insn.operands) >= 2:
- reg = insn.operands[0].reg
- page = insn.operands[1].imm
- adrp_cache[reg] = (insn.address, page, idx)
-
- elif insn.mnemonic == "add" and len(insn.operands) >= 3:
- src_reg = insn.operands[1].reg
- imm = insn.operands[2].imm
- if src_reg in adrp_cache:
- adrp_va, page, adrp_idx = adrp_cache[src_reg]
- # Only match if ADRP was within 8 instructions
- if (
- page == target_page
- and imm == target_pageoff
- and idx - adrp_idx <= 8
- ):
- return adrp_va
-
- return -1
-
-
-def _find_nearby_branch(data, ref_foff, text_foff, text_size):
- """Find a conditional branch after a BL (function call) near ref_foff.
-
- The typical pattern is:
- ADRP+ADD (load string argument) ← ref_foff points here
- ... (setup other args)
- BL (call check function)
- CBZ/CBNZ (branch on return value)
-
- Searches forward from ref_foff for a BL, then finds the first
- conditional branch after it (within 8 instructions of the BL).
- Falls back to first conditional branch within +32 instructions.
- """
- branch_mnemonics = {"cbz", "cbnz", "tbz", "tbnz"}
-
- # Strategy A: find BL → then first conditional branch after it
- for delta in range(0, 16):
- check_foff = ref_foff + delta * 4
- if check_foff >= text_foff + text_size:
- break
- insns = disasm_at(data, check_foff, 1)
- if not insns:
- continue
- if insns[0].mnemonic == "bl":
- # Found a function call; scan the next 8 instructions for a branch
- for d2 in range(1, 9):
- br_foff = check_foff + d2 * 4
- if br_foff >= text_foff + text_size:
- break
- br_insns = disasm_at(data, br_foff, 1)
- if not br_insns:
- continue
- mn = br_insns[0].mnemonic
- if mn in branch_mnemonics or mn.startswith("b."):
- return br_foff
- break # Found BL but no branch after it
-
- # Strategy B: fallback — first conditional branch forward within 32 insns
- for delta in range(1, 33):
- check_foff = ref_foff + delta * 4
- if check_foff >= text_foff + text_size:
- break
- insns = disasm_at(data, check_foff, 1)
- if not insns:
- continue
- mn = insns[0].mnemonic
- if mn in branch_mnemonics or mn.startswith("b."):
- return check_foff
-
- return -1
diff --git a/scripts/patchers/cfw_patch_camera_dsc.py b/scripts/patchers/cfw_patch_camera_dsc.py
deleted file mode 100644
index ce728e9c..00000000
--- a/scripts/patchers/cfw_patch_camera_dsc.py
+++ /dev/null
@@ -1,232 +0,0 @@
-"""Camera-related DSC patches for the vphone EXP firmware.
-
-Two patch families:
-
-1. NeutrinoCore short-circuit — replace the five
- `+[_NUStyleTransfer*Processor processWithInputs:arguments:output:error:]`
- class methods with `mov w0, #0; ret`. Together with the DT `/product/camera`
- node (added by `DeviceTreePatcher.swift`), this lets Camera.app launch and
- reach the viewfinder UI on this VM build without crashing in NeutrinoCore.
-
-2. AVCaptureDevice authorization gate — replace
- `+[AVCaptureDevice authorizationStatusForMediaType:]` in `AVFCapture` with
- `mov w0, #3; ret` (AVAuthorizationStatusAuthorized = 3). Any process that
- probes camera (or any other media type) authorization gets "Authorized"
- without going through TCC. Stage 0 of the vcam stack — makes apps stop
- bailing on the auth check; downstream pipeline still needs Stages 1+2 to
- actually deliver frames.
-"""
-
-import os
-import re
-import shutil
-import subprocess
-
-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 = [
- "+[_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:]",
-]
-
-AVF_AUTH_STATUS_SYMBOL = (
- "+[AVCaptureDevice authorizationStatusForMediaType:]"
-)
-
-
-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.
- """
- ipsw_bin = shutil.which("ipsw")
- if not ipsw_bin:
- raise RuntimeError("`ipsw` not in PATH")
- cmd = [
- ipsw_bin, "dyld", "symaddr", dsc_path,
- "--image", image_path,
- ]
- out = subprocess.run(cmd, capture_output=True, text=True, check=True).stdout
- wanted = set(wanted_symbols)
- results = {}
- for line in out.splitlines():
- line = re.sub(r"\x1b\[[0-9;]*m", "", line).rstrip()
- m = re.match(r"\s*(0x[0-9A-Fa-f]+):\s*\([^)]+\)\s*(.+)$", line)
- if not m:
- continue
- addr, rest = m.group(1), m.group(2)
- sym = rest.rsplit("\t", 1)[0].strip() if "\t" in rest else rest.strip()
- if sym in wanted:
- results[sym] = int(addr, 16)
- missing = [s for s in wanted_symbols if s not in results]
- if missing:
- raise RuntimeError(
- f"could not resolve symbols in {image_path}: {missing}"
- )
- return results
-
-
-def resolve_nu_symbols(dsc_path):
- """Resolve the five NeutrinoCore symbols."""
- return _resolve_symbols_in_image(
- dsc_path,
- "/System/Library/PrivateFrameworks/NeutrinoCore.framework/NeutrinoCore",
- NU_STYLE_TRANSFER_SYMBOLS,
- )
-
-
-def resolve_avf_auth_symbol(dsc_path):
- """Resolve +[AVCaptureDevice authorizationStatusForMediaType:] in AVFCapture."""
- return _resolve_symbols_in_image(
- dsc_path,
- "/System/Library/PrivateFrameworks/AVFCapture.framework/AVFCapture",
- [AVF_AUTH_STATUS_SYMBOL],
- )
-
-
-def patch_nu_styletransfer_short_circuit(chunks, vmas, *, dry_run=False, force=False):
- """Replace each `+[_NUStyleTransfer*Processor processWithInputs:...]` with
- `mov w0, #0; ret`. Camera's style-thumbnail pipeline then short-circuits
- before reaching `_NUStyleEngineMemoryResource init:`, which would otherwise
- assert on a nil descriptor and SIGABRT on first viewfinder render.
- """
- new_bytes = asm("mov w0, #0\nret")
- if len(new_bytes) != 8:
- raise RuntimeError(f"expected 8 bytes, got {len(new_bytes)}")
-
- patched = []
- for sym, vma in sorted(vmas.items()):
- orig = chunks.bytes_at_vma(vma, 8)
- print(f" {sym} @ 0x{vma:X}")
- print(f" {orig.hex()} → {new_bytes.hex()}")
- if orig[:4] != b"\x7f\x23\x03\xd5" and not force:
- raise RuntimeError(
- 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)
-
- if dry_run:
- print(" [DRY RUN]")
- return
-
- diags = reattest_modified_pages(chunks, patched, verbose=True)
- print(f" re-attested {len(diags)} page(s)")
- for vma in patched:
- if chunks.bytes_at_vma(vma, 8) != new_bytes:
- raise RuntimeError(f"post-write verify failed at 0x{vma:X}")
-
-
-def patch_avf_authorization_always_authorized(
- chunks, vmas, *, dry_run=False, force=False
-):
- """Replace `+[AVCaptureDevice authorizationStatusForMediaType:]` with
- `mov w0, #3; ret`. Authorized = 3 across every media type — broader than
- just video, but the VM doesn't service audio capture either, so any app
- probing audio auth would have failed downstream regardless.
- """
- new_bytes = asm("mov w0, #3\nret")
- if len(new_bytes) != 8:
- raise RuntimeError(f"expected 8 bytes, got {len(new_bytes)}")
-
- patched = []
- for sym, vma in sorted(vmas.items()):
- orig = chunks.bytes_at_vma(vma, 8)
- print(f" {sym} @ 0x{vma:X}")
- print(f" {orig.hex()} → {new_bytes.hex()}")
- if orig[:4] != b"\x7f\x23\x03\xd5" and not force:
- raise RuntimeError(
- 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)
-
- if dry_run:
- print(" [DRY RUN]")
- return
-
- diags = reattest_modified_pages(chunks, patched, verbose=True)
- print(f" re-attested {len(diags)} page(s)")
- for vma in patched:
- if chunks.bytes_at_vma(vma, 8) != new_bytes:
- raise RuntimeError(f"post-write verify failed at 0x{vma:X}")
-
-
-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}")
-
- print(f" [.] resolving NeutrinoCore symbols against {dsc_path}...")
- nu_vmas = resolve_nu_symbols(dsc_path)
- print(f" [.] resolving AVFCapture authorization symbol against {dsc_path}...")
- avf_vmas = resolve_avf_auth_symbol(dsc_path)
-
- print(f"\n [1/2] +[_NUStyleTransfer*Processor processWithInputs:...] → return NO")
- patch_nu_styletransfer_short_circuit(chunks, nu_vmas, dry_run=dry_run, force=force)
-
- print(f"\n [2/2] +[AVCaptureDevice authorizationStatusForMediaType:] → return Authorized")
- patch_avf_authorization_always_authorized(chunks, avf_vmas, dry_run=dry_run, force=force)
-
- print(f"\n [+] camera DSC patches applied: 2/2")
- return 2
-
-
-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}...")
- avf_vmas = resolve_avf_auth_symbol(dsc_path)
- print(f"\n [1/1] +[AVCaptureDevice authorizationStatusForMediaType:] → return Authorized")
- patch_avf_authorization_always_authorized(chunks, avf_vmas, dry_run=dry_run, force=force)
- print(f"\n [+] AVF-only camera DSC patch applied: 1/1")
- return 1
-
-
-if __name__ == "__main__":
- import argparse
- ap = argparse.ArgumentParser(description="Camera DSC patcher")
- ap.add_argument("chunks_dir", help="Directory containing dyld_shared_cache_arm64e.* files")
- ap.add_argument("dsc_header", help="Path to the dyld_shared_cache_arm64e header (no suffix)")
- ap.add_argument("--dry-run", action="store_true")
- ap.add_argument("--force", action="store_true")
- ap.add_argument("--avf-only", action="store_true",
- help="Apply only the AVFCapture authorization gate patch (composition mode)")
- args = ap.parse_args()
- if args.avf_only:
- apply_avf_auth_only(args.chunks_dir, args.dsc_header,
- dry_run=args.dry_run, force=args.force)
- else:
- apply_all_camera_patches(args.chunks_dir, args.dsc_header,
- dry_run=args.dry_run, force=args.force)
diff --git a/scripts/patchers/cfw_patch_diskimagesiod.py b/scripts/patchers/cfw_patch_diskimagesiod.py
deleted file mode 100644
index d5cab665..00000000
--- a/scripts/patchers/cfw_patch_diskimagesiod.py
+++ /dev/null
@@ -1,162 +0,0 @@
-"""diskimagesiod patch module — iOS 27 DDI (/System/Developer) auto-mount fix.
-
-Forces -[DIDiskArb isMountCompleteWithExpectedCount:diskTracker:] to return YES.
-
-Why: `pymobiledevice3 mounter auto-mount` attaches the personalized DDI, then
-MobileStorageMounter waits on diskimagesiod's -[DIDiskArb
-waitForDAMountWithExpectedCount:diskTracker:] before it performs the real
-(nobrowse) mount of the DDI volume at /System/Developer. That wait loops until
-`isMountComplete` returns YES, which is
-`callbackReached || (appearedDiskCount >= expectedCount && mountedDiskCount >= mountableDiskCount)`.
-On the iOS-27-userland / 26.4-vphone600-kernel hybrid this never becomes true:
-only some of the DMG's IOMedia ever "appear" to diskimagesiod's DiskArbitration
-session (appearedDiskCount < expectedCount), and diskarbitrationd never
-auto-mounts the volume (mountedDiskCount stays 0), so the wait hangs forever and
-pmd3 times out. diskimagesiod itself does NOT mount the DDI (its
--[DIDiskArb mountWithDeviceName:...] is dead code); it only gates
-MobileStorageMounter. Forcing isMountComplete to YES lets the wait return
-immediately so MobileStorageMounter proceeds and mounts the DDI.
-
-Pairs with the JB kernel patches that make the DDI attachable + mountable:
- - DiskImages2 ABI pokes (KernelJBPatchDiskImages2*) — the v9-kernel accepts the
- v11 userland attach.
- - Sandbox mac_policy_ops[124] (mpo_proc_check_syscall_unix) → allow stub
- (KernelJBPatchSandboxExtended) — lets MobileStorageMounter's mount_apfs make
- the mount(2) syscall (unix 167), otherwise the kernel Sandbox denies it
- ("Protobox: mount_apfs deny(1) syscall-unix 167").
-
-No-op-in-effect on version-matched userlands (there the wait completes on its
-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:"
-
-
-def _find_imp_via_objc_metadata(data):
- """Resolve the method IMP through ObjC runtime metadata (relative method lists).
-
- selector cstring -> __objc_selrefs entry -> relative method-list entry -> IMP.
- """
- sections = parse_macho_sections(data)
-
- sel_foff = data.find(_SELECTOR.encode() + b"\x00")
- if sel_foff < 0:
- print(f" [-] Selector '{_SELECTOR}' not found in binary")
- return -1
-
- sel_va = -1
- for _sec_name, (sva, ssz, sfoff) in sections.items():
- if sfoff <= sel_foff < sfoff + ssz:
- sel_va = sva + (sel_foff - sfoff)
- break
- if sel_va < 0:
- print(f" [-] Could not compute VA for selector at foff:0x{sel_foff:X}")
- return -1
- print(f" Selector at foff:0x{sel_foff:X} va:0x{sel_va:X}")
-
- selrefs = find_section(
- sections,
- "__DATA_CONST,__objc_selrefs",
- "__DATA,__objc_selrefs",
- "__AUTH_CONST,__objc_selrefs",
- )
- selref_va = -1
- if selrefs:
- sr_va, sr_size, sr_foff = selrefs
- for i in range(0, sr_size, 8):
- ptr = struct.unpack_from("<Q", data, sr_foff + i)[0]
- # Handle chained fixups: exact, 48-bit-masked, or low-32-bit match.
- if (ptr == sel_va
- or (ptr & 0x0000FFFFFFFFFFFF) == sel_va
- or (ptr & 0xFFFFFFFF) == (sel_va & 0xFFFFFFFF)):
- selref_va = sr_va + i
- break
- if selref_va < 0:
- print(" [-] Selref not found (chained fixups may obscure pointers)")
- return -1
- print(f" Selref va:0x{selref_va:X}")
-
- # Relative method lists live in __TEXT,__objc_methlist on modern toolchains
- # (older layouts keep them in __objc_const — try both).
- objc_const = find_section(
- sections,
- "__TEXT,__objc_methlist",
- "__DATA_CONST,__objc_const",
- "__DATA,__objc_const",
- "__AUTH_CONST,__objc_const",
- )
- if objc_const:
- oc_va, oc_size, oc_foff = objc_const
- # Relative method entry: { int32 name_rel, int32 types_rel, int32 imp_rel }.
- # name_rel may resolve to the selref (uniqued SEL*) or, in "direct
- # selector" method lists, straight to the selector cstring — accept both.
- for i in range(0, oc_size - 12, 4):
- entry_foff = oc_foff + i
- entry_va = oc_va + i
- rel_name = struct.unpack_from("<i", data, entry_foff)[0]
- if entry_va + rel_name in (selref_va, sel_va):
- imp_field_foff = entry_foff + 8
- imp_field_va = entry_va + 8
- rel_imp = struct.unpack_from("<i", data, imp_field_foff)[0]
- imp_va = imp_field_va + rel_imp
- imp_foff = va_to_foff(bytes(data), imp_va)
- if imp_foff >= 0:
- print(f" Found via relative method list: IMP va:0x{imp_va:X} foff:0x{imp_foff:X}")
- return imp_foff
- print(f" [!] IMP va:0x{imp_va:X} could not be mapped to file offset")
- return -1
-
-
-def patch_diskimagesiod(filepath):
- """Force -[DIDiskArb isMountCompleteWithExpectedCount:diskTracker:] → YES.
-
- Anchor strategies (in order):
- 1. LC_SYMTAB symbol containing "isMountCompleteWithExpectedCount".
- 2. ObjC metadata: selector -> selref -> relative method list -> IMP.
- Then overwrite the method prologue with `mov x0,#1 ; ret`.
- """
- data = bytearray(open(filepath, "rb").read())
-
- imp_foff = -1
- imp_va = find_symbol_va(bytes(data), "isMountCompleteWithExpectedCount")
- if imp_va > 0:
- imp_foff = va_to_foff(bytes(data), imp_va)
- if imp_foff >= 0:
- print(f" Found via symtab: va:0x{imp_va:X} -> foff:0x{imp_foff:X}")
-
- if imp_foff < 0:
- imp_foff = _find_imp_via_objc_metadata(data)
-
- if imp_foff < 0:
- print(" [-] Dynamic anchor not found — all strategies exhausted")
- return False
-
- if imp_foff + 8 > len(data):
- print(f" [-] IMP offset 0x{imp_foff:X} out of bounds")
- return False
-
- print(" Before:")
- _log_asm(data, imp_foff, 4, imp_foff)
-
- # Return YES immediately. Overwriting the prologue (pacibsp; stp...) is safe:
- # the function returns to the caller's (unsigned) LR without ever pushing a
- # frame. Mirrors patch_mobileactivationd.
- data[imp_foff:imp_foff + 4] = MOV_X0_1
- data[imp_foff + 4:imp_foff + 8] = RET
-
- 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
deleted file mode 100644
index 8a20acc3..00000000
--- a/scripts/patchers/cfw_patch_dsc_maxslide.py
+++ /dev/null
@@ -1,143 +0,0 @@
-"""Clamp the dyld shared cache maxSlide so a large userland cache fits the
-PCC vphone600 26.x kernel's fixed 6 GiB shared region.
-
-The vphone600 26.x kernel reserves SHARED_REGION_SIZE_ARM64 = 0x180000000 (6 GiB)
-at SHARED_REGION_BASE_ARM64 = 0x180000000 (verified by disassembling the arm64 case
-of the kernel's shared_region_create). At map time the kernel needs room for the
-cache's mapped span PLUS the cache-header maxSlide (the ASLR range). A newer userland
-whose cache nearly fills the region overflows it:
-
- iOS 27.0 (24A5380h): span 0x17c830000 (~5.95 GiB) + maxSlide 0x20000000 (512 MiB)
- = 0x19c830000 (~6.46 GiB) > 0x180000000 (6 GiB)
-
--> _shared_region_map_and_slide returns ENOMEM -> dyld cannot map libSystem ->
-launchd (pid 1) panics ("initproc failed to start -- Library not loaded:
-/usr/lib/libSystem.B.dylib"). Older userlands (e.g. 26.x/18.x) fit with full slide
-and are unaffected.
-
-Fix: zero maxSlide in the cache header so the cache maps at slide 0 and fits (iOS 27.0
-leaves ~58 MiB spare). Only the main chunk `dyld_shared_cache_arm64e` carries the
-dyld_cache_header. maxSlide is a plain metadata field the kernel reads during map
-setup, NOT a cs_validate'd dylib code page — so, unlike cfw_patch_iomfb_swapend, NO
-page re-attestation is required (confirmed empirically: a live-poked cache with
-maxSlide=0 booted with "dyld cache mapped system-wide", 0 panics).
-
-Self-gating: no-op unless span + maxSlide overflows the region. force=True
-(CLI --force) zeroes maxSlide unconditionally, for non-27 bases that opt in.
-
-dyld_cache_header offsets (little-endian u64, stable across recent iOS):
- sharedRegionStart @0xE0, sharedRegionSize @0xE8, maxSlide @0xF0
-"""
-
-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
-OFF_SHARED_REGION_SIZE = 0xE8
-OFF_MAX_SLIDE = 0xF0
-
-# SHARED_REGION_SIZE_ARM64 baked into the PCC vphone600 26.x kernel. The cache's
-# span + maxSlide must fit within this or the shared_region map ENOMEMs.
-KERNEL_SHARED_REGION_SIZE = 0x180000000
-
-
-def patch_dsc_maxslide(chunks_dir, *, kernel_region_size=KERNEL_SHARED_REGION_SIZE, dry_run=False, force=False):
- main = os.path.join(chunks_dir, MAIN_CHUNK)
- if not os.path.isfile(main):
- raise FileNotFoundError(f"main DSC chunk not found: {main}")
-
- with open(main, "r+b") as f:
- hdr = f.read(0x100)
- if hdr[:7] != b"dyld_v1":
- raise RuntimeError(f"{main}: not a dyld shared cache (magic={hdr[:16]!r})")
- srstart = struct.unpack_from("<Q", hdr, OFF_SHARED_REGION_START)[0]
- srsize = struct.unpack_from("<Q", hdr, OFF_SHARED_REGION_SIZE)[0]
- maxslide = struct.unpack_from("<Q", hdr, OFF_MAX_SLIDE)[0]
- print(f" [.] {MAIN_CHUNK}: start=0x{srstart:X} size=0x{srsize:X} maxSlide=0x{maxslide:X}")
-
- fits = srsize + maxslide <= kernel_region_size
- if fits and not force:
- print(f" [=] fits: span+maxSlide 0x{srsize + maxslide:X} <= "
- f"region 0x{kernel_region_size:X}; no change")
- return 0
- if maxslide == 0:
- print(" [=] maxSlide already 0; no change")
- return 0
-
- # Set maxSlide to 0 so the cache maps at slide 0 within the region.
- new_maxslide = 0
- reason = (f"forced: span+maxSlide 0x{srsize + maxslide:X} fits region "
- f"0x{kernel_region_size:X} but --force set" if fits
- else f"overflow: span+maxSlide 0x{srsize + maxslide:X} > "
- f"region 0x{kernel_region_size:X}")
- 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()
- os.fsync(f.fileno())
- f.seek(OFF_MAX_SLIDE)
- back = struct.unpack("<Q", f.read(8))[0]
- if back != new_maxslide:
- raise RuntimeError(f"maxSlide write verify failed: 0x{back:X}")
-
- print(" [+] DSC maxSlide patch complete")
- return 1
-
-
-def _self_test():
- """Gate logic: a cache that overflows gets clamped; one that fits is untouched."""
- import tempfile
-
- def mkcache(size, maxslide, path):
- hdr = bytearray(0x100)
- hdr[0:16] = b"dyld_v1 arm64e\x00"
- struct.pack_into("<Q", hdr, OFF_SHARED_REGION_START, 0x180000000)
- struct.pack_into("<Q", hdr, OFF_SHARED_REGION_SIZE, size)
- struct.pack_into("<Q", hdr, OFF_MAX_SLIDE, maxslide)
- open(path, "wb").write(hdr)
-
- with tempfile.TemporaryDirectory() as d:
- c = os.path.join(d, MAIN_CHUNK)
- # overflow (iOS 27.0-like): 0x17c830000 + 0x20000000 > 0x180000000 -> clamp
- mkcache(0x17C830000, 0x20000000, c)
- assert patch_dsc_maxslide(d) == 1
- with open(c, "rb") as f:
- f.seek(OFF_MAX_SLIDE)
- assert struct.unpack("<Q", f.read(8))[0] == 0
- # fits (26.4-like): 0x140904000 + 0x20000000 <= 0x180000000 -> untouched
- mkcache(0x140904000, 0x20000000, c)
- assert patch_dsc_maxslide(d) == 0
- with open(c, "rb") as f:
- f.seek(OFF_MAX_SLIDE)
- assert struct.unpack("<Q", f.read(8))[0] == 0x20000000
- # fits + force: opt-in zeroes maxSlide even though it fits
- assert patch_dsc_maxslide(d, force=True) == 1
- with open(c, "rb") as f:
- f.seek(OFF_MAX_SLIDE)
- assert struct.unpack("<Q", f.read(8))[0] == 0
- # force + already 0: idempotent no-op
- assert patch_dsc_maxslide(d, force=True) == 0
- print("self-test OK")
-
-
-if __name__ == "__main__":
- _self_test()
diff --git a/scripts/patchers/cfw_patch_hv_vmm.py b/scripts/patchers/cfw_patch_hv_vmm.py
deleted file mode 100644
index 9a4e881e..00000000
--- a/scripts/patchers/cfw_patch_hv_vmm.py
+++ /dev/null
@@ -1,142 +0,0 @@
-"""hv_vmm_present user-mode patch module — cstring-mangle approach.
-
-Mangles the cstring "kern.hv_vmm_present\\0" in targeted user-mode
-binaries so they query a kernel sysctl with a different name. On a
-kernel patched by `KernelJBPatchHvVmmRename` (which renames the OID
-from `hv_vmm_present` to `Xv_vmm_present`), the new design is:
-
- - Caller queries `kern.hv_vmm_present` (UNPATCHED binary):
- kernel returns ENOENT. The canonical defensive post-call check
- (`cbnz w0, skip` / `cmp w0,#0 ; b.ne skip`) takes the skip
- path; the cached `is_vmm` byte stays at BSS-zero (0). The
- binary thinks it is NOT running in a VM.
-
- - Caller queries `kern.Xv_vmm_present` (PATCHED binary):
- kernel returns 1 (the real value of the OID's int variable).
- The defensive check passes; the cache stores 1. The binary
- thinks it IS running in a VM — same as a stock device.
-
-Patch shape (per cstring occurrence): byte 5 of the cstring
-`'h'` (0x68) → `'X'` (0x58). The mangled cstring is
-`"kern.Xv_vmm_present\\0"`. Byte 5 is chosen so the `kern.` top-level
-sysctl namespace is preserved — without that, the kernel's
-name-to-MIB resolver wouldn't route the call to any OID.
-
-Public entrypoints:
- patch_hv_vmm(filepath, *, dry_run=False) -> int
- Patch a standalone Mach-O. Returns the number of cstring sites
- mangled.
-
- find_string_sites(data: bytes) -> list[dict]
- Find every cstring occurrence in an in-memory Mach-O.
-"""
-
-import struct
-
-from .cfw_asm import parse_macho_sections, _log_asm
-
-
-NEEDLE = b"kern.hv_vmm_present\x00"
-# Mangle byte offset (0-based within NEEDLE). Position 5 is the 'h' of
-# "hv_vmm_present" — the first byte after the "kern." namespace prefix.
-# Keeping the "kern." prefix intact ensures the kernel's sysctl name-to-MIB
-# resolver routes the call to a real OID (registered as `Xv_vmm_present`
-# under `kern` by the companion kernel patch). Byte 0 would have produced
-# `Xern.hv_vmm_present`, which can never resolve because `Xern` isn't a
-# registered top-level sysctl namespace.
-MANGLE_OFFSET = 5
-ORIGINAL_BYTE = b"h" # 0x68
-MANGLED_BYTE = b"X" # 0x58
-MANGLED_NEEDLE = NEEDLE[:MANGLE_OFFSET] + MANGLED_BYTE + NEEDLE[MANGLE_OFFSET + 1:]
-
-
-def find_string_sites(data):
- """Return all unmangled "kern.hv_vmm_present\\0" cstring occurrences.
-
- Each entry: {string_vma, file_offset, section}.
-
- Hits are anchored at a cstring boundary (preceded by a NUL byte or
- at the start of the section) so partial-match substrings inside
- longer cstrings won't be returned.
- """
- sections = parse_macho_sections(data)
- out = []
- for sec_name, (vma, size, foff) in sections.items():
- _, _, sect = sec_name.partition(",")
- # __cstring is where the linker puts unique C-string literals.
- # Some method-name / class-name pools could in principle hold
- # the same bytes too; we include them for safety.
- if sect not in ("__cstring", "__objc_methname", "__objc_classname"):
- continue
- buf = bytes(data[foff:foff + size])
- i = 0
- while True:
- p = buf.find(NEEDLE, i)
- if p < 0:
- break
- if p == 0 or buf[p - 1] == 0:
- out.append(
- {
- "string_vma": vma + p,
- "file_offset": foff + p,
- "section": sec_name,
- }
- )
- i = p + 1
- return out
-
-
-def is_already_mangled(data):
- """Detect whether the binary already contains the mangled form.
-
- Used purely for friendlier logging — `find_string_sites` already
- returns empty on a mangled binary, so the patch flow is idempotent
- regardless.
- """
- return bytes(data).find(MANGLED_NEEDLE) >= 0
-
-
-def patch_hv_vmm(filepath, *, dry_run=False):
- """Mangle the kern.hv_vmm_present cstring in a standalone Mach-O.
-
- Returns the count of mangled cstring sites. Idempotent.
- """
- data = bytearray(open(filepath, "rb").read())
- sites = find_string_sites(bytes(data))
- if not sites:
- if is_already_mangled(bytes(data)):
- print(f" [.] {filepath}: already mangled (no original "
- f"'kern.hv_vmm_present' cstring present)")
- else:
- print(f" [.] {filepath}: 'kern.hv_vmm_present' cstring not "
- f"present — nothing to do")
- return 0
-
- print(f" [+] {len(sites)} cstring occurrence(s) in {filepath}")
- n = 0
- for s in sites:
- foff = s["file_offset"]
- original = bytes(data[foff:foff + len(NEEDLE)])
- # Idempotence: if byte at MANGLE_OFFSET is already mangled, skip.
- if original[MANGLE_OFFSET:MANGLE_OFFSET + 1] == MANGLED_BYTE:
- print(f" [.] string@0x{s['string_vma']:X} already mangled "
- f"(byte {MANGLE_OFFSET} is already {MANGLED_BYTE.decode()!r})")
- continue
- if original != NEEDLE:
- print(f" [-] string@0x{s['string_vma']:X} bytes look unexpected "
- f"({original!r}); skipping")
- continue
- print(f" patching string@0x{s['string_vma']:X} (sect={s['section']}): "
- f"byte {MANGLE_OFFSET} {ORIGINAL_BYTE.decode()!r} -> "
- f"{MANGLED_BYTE.decode()!r} "
- f"('kern.hv_vmm_present' -> 'kern.Xv_vmm_present')")
- data[foff + MANGLE_OFFSET:foff + MANGLE_OFFSET + 1] = MANGLED_BYTE
- n += 1
-
- if dry_run:
- print(f" [.] dry-run — not writing back")
- return n
- if n > 0:
- open(filepath, "wb").write(data)
- print(f" [+] {filepath}: mangled {n} cstring occurrence(s)")
- return n
diff --git a/scripts/patchers/cfw_patch_hv_vmm_dsc.py b/scripts/patchers/cfw_patch_hv_vmm_dsc.py
deleted file mode 100644
index 3f9646da..00000000
--- a/scripts/patchers/cfw_patch_hv_vmm_dsc.py
+++ /dev/null
@@ -1,273 +0,0 @@
-"""DSC-side orchestrator for the hv_vmm_present user-mode patch
-(blacklist-flip design).
-
-Design summary
---------------
-This module works in tandem with `KernelJBPatchHvVmmRename` (Swift
-kernel patcher) which renames the kernel's sysctl OID from
-`hv_vmm_present` to `Xv_vmm_present`. After the kernel patch:
-
- - `sysctlbyname("kern.hv_vmm_present", ...)` returns ENOENT.
- - `sysctlbyname("kern.Xv_vmm_present", ...)` returns 1 (the OID's
- real int value, since this device is in fact a VM).
-
-This module's job is to selectively rewrite cstrings inside DSC
-dylibs so each dylib queries either the original (now ENOENT-returning)
-name or the new (truthful-1-returning) name. Byte 5 of the
-`"kern.hv_vmm_present\\0"` cstring is flipped from `'h'` (0x68) to
-`'X'` (0x58), producing `"kern.Xv_vmm_present\\0"` — the same name the
-kernel OID now answers to. The `kern.` namespace prefix is preserved
-(byte-0 mangle would have produced `Xern.hv_vmm_present` which can
-never resolve because `Xern` isn't a registered top-level).
-
-Blacklist semantics
--------------------
-The `DONT_PATCH_INSTALL_NAMES` list names dylibs whose cstring stays
-ORIGINAL — they query `kern.hv_vmm_present`, get ENOENT, and the
-caller's defensive post-call check leaves the cached `is_vmm` byte
-at BSS-zero (0). Those libs end up thinking "not in a VM" — which is
-what we want for sign-in / device-likeness consumers.
-
-Every OTHER dylib that contains the cstring gets the byte-5 mangle —
-they query `kern.Xv_vmm_present`, get 1, cache 1, and think "in a VM"
-— exactly the value they would have seen on a stock device. This
-keeps the graphics path (libMobileGestalt, PhotoFoundation,
-AirPlaySupport, VisionKitCore, CoreVideo) and compute/accel fast
-paths (CoreML, Espresso, AppleNeuralEngine, …) intact, because they
-keep getting their original answer.
-
-"""
-
-import os
-import struct
-import sys
-
-from .cfw_patch_hv_vmm import (
- NEEDLE,
- MANGLED_NEEDLE,
- MANGLE_OFFSET,
- ORIGINAL_BYTE,
- MANGLED_BYTE,
-)
-from .cfw_dsc_chunks import DSCChunks
-from .cfw_dsc_codesign import reattest_modified_pages
-from . import cfw_records as records
-
-
-# ─────────────────────────────────────────────────────────────────────
-# Blacklist of DSC dylibs to LEAVE UNPATCHED.
-#
-# A dylib in this list keeps its cstring as `"kern.hv_vmm_present\0"`.
-# With the kernel-rename patch in place, that name resolves to ENOENT,
-# the dylib's defensive `cbnz w0, skip` takes the skip path, and the
-# cached `is_vmm` byte stays at BSS-zero (0). The dylib thinks the
-# device is not a VM.
-#
-# A dylib NOT in this list has its cstring rewritten to
-# `"kern.Xv_vmm_present\0"` (byte 5 mangle, 'h' → 'X'). That name
-# resolves to the renamed OID on the kernel side and returns 1. The
-# dylib thinks the device IS a VM — same as stock.
-#
-# Comment a single line out (re-enabling the patch for that dylib —
-# i.e., MOVING IT OUT of the blacklist) to bisect which consumer
-# regressed an observable.
-#
-# Order is grouped by why each entry needs to lie about VM presence;
-# the order itself doesn't affect patching.
-# ─────────────────────────────────────────────────────────────────────
-DONT_PATCH_INSTALL_NAMES = (
- # ── Identity / activation / anti-abuse.
- "/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",
-
- # ── Store / IAP.
- "/System/Library/PrivateFrameworks/AppStoreUtilities.framework/AppStoreUtilities",
-
- # ── Consumer services.
- "/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",
-)
-_DONT_PATCH_SET: frozenset[str] = frozenset(DONT_PATCH_INSTALL_NAMES)
-
-
-def _classify(chunks, string_vma):
- """Walk back from `string_vma` to find the containing Mach-O header
- and return its install name (LC_ID_DYLIB), or None if not found.
- """
- header_vma = chunks.find_macho_header_before(string_vma)
- if header_vma is None:
- return None
- return chunks.read_install_name_at(header_vma)
-
-
-def patch_hv_vmm_in_dsc(chunks_dir, *, dry_run=False):
- """Apply the blacklist-flip mangle inside the DSC chunks at
- `chunks_dir`.
-
- For every occurrence of `"kern.hv_vmm_present\\0"` in any
- executable DSC mapping, resolve the containing dylib's install
- name; if the install name is NOT in `DONT_PATCH_INSTALL_NAMES`,
- rewrite byte 5 of the cstring from 'h' to 'X'.
-
- Returns {install_name: count_of_cstring_sites_mangled}.
- """
- records.set_group("hv_vmm_dsc")
- chunks = DSCChunks(chunks_dir)
- print(f" [.] {chunks!r}")
-
- print(f" [.] locating cstring \"kern.hv_vmm_present\\0\"...")
- string_vmas = chunks.find_string_vmas(NEEDLE)
- # Also pick up cstrings already mangled by a prior run — we still
- # need their 16 KiB pages added to the re-attestation set so a
- # re-run on a previously-patched DSC keeps slot hashes in sync.
- already_mangled_vmas = chunks.find_string_vmas(MANGLED_NEEDLE)
- if not string_vmas and not already_mangled_vmas:
- print(f" [-] cstring not present in any executable mapping; "
- f"nothing to do (either patched already or absent)")
- return {}
- print(f" [.] {len(string_vmas)} pristine + {len(already_mangled_vmas)} "
- f"already-mangled cstring occurrence(s) found")
-
- print(f" [.] resolving containing dylib for each occurrence "
- f"(blacklist has {len(_DONT_PATCH_SET)} entries — these stay "
- f"unpatched)...")
- results = {}
- patched_total = 0
- skipped_in_blacklist = 0
- skipped_unclassified = 0
- refused = 0
- # Track every vmaddr we actually mangled so the re-attestation pass
- # at the end recomputes exactly the affected 16 KiB pages.
- modified_vmas: list[int] = []
-
- for vma in sorted(string_vmas):
- try:
- install_name = _classify(chunks, vma)
- except Exception as e:
- print(f" [-] could not classify string@0x{vma:X}: "
- f"{type(e).__name__}: {e}")
- install_name = None
- label = install_name or "<unknown dylib>"
-
- if install_name is None:
- # Unknown dylibs are NOT in the blacklist → would normally
- # be patched. Refuse here because we can't audit them.
- print(f" [.] SKIP (no install name resolvable) "
- f"string@0x{vma:X}")
- skipped_unclassified += 1
- results[label] = results.get(label, 0)
- continue
-
- if install_name in _DONT_PATCH_SET:
- print(f" [.] SKIP (blacklisted — stays unpatched, "
- f"will hit ENOENT): {install_name} string@0x{vma:X}")
- skipped_in_blacklist += 1
- results[label] = results.get(label, 0)
- continue
-
- # Sanity: the byte at vma must currently look like the pristine cstring.
- try:
- current = chunks.read_at_vma(vma, len(NEEDLE))
- except (KeyError, IOError) as e:
- print(f" [-] read failed at 0x{vma:X}: {e}")
- refused += 1
- continue
- if current[MANGLE_OFFSET:MANGLE_OFFSET + 1] == MANGLED_BYTE:
- # Already mangled by a prior run; nothing to write, but
- # the re-attest pass below picks it up via already_mangled_vmas.
- print(f" [.] already mangled at byte {MANGLE_OFFSET}: "
- f"{label} string@0x{vma:X}")
- results[label] = results.get(label, 0)
- continue
- if current != NEEDLE:
- print(f" [-] unexpected bytes at 0x{vma:X} "
- f"({current!r}); refusing ({label})")
- refused += 1
- continue
-
- 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} "
- f"({ORIGINAL_BYTE.decode()} -> {MANGLED_BYTE.decode()}) "
- f"now queries kern.Xv_vmm_present, will see 1 (in a VM)")
- results[label] = results.get(label, 0) + 1
- patched_total += 1
- modified_vmas.append(vma)
-
- # Second pass: previously-mangled cstrings. Add their pages to the
- # re-attestation set so a re-run brings slot hashes into sync.
- # IMPORTANT: we INTENTIONALLY do not refuse a mangled cstring whose
- # install_name is in the blacklist — that's an out-of-band action
- # (someone re-enabled patching for that dylib in a prior run and
- # then commented it back into the blacklist). We log it loudly.
- reattest_only_count = 0
- blacklist_drift_count = 0
- for vma in sorted(already_mangled_vmas):
- try:
- install_name = _classify(chunks, vma)
- except Exception:
- install_name = None
- if install_name is None:
- continue
- if install_name in _DONT_PATCH_SET:
- # This dylib is supposed to be unpatched but appears mangled.
- # Most likely the operator mangled and then re-added it to
- # the blacklist; we surface this and still re-attest the
- # page so the slot hash matches the current bytes.
- print(f" [!] drift: {install_name} is in the blacklist "
- f"but already mangled at string@0x{vma:X} — slot will "
- f"be re-attested to current bytes; consider whether "
- f"you actually want this dylib re-patched")
- modified_vmas.append(vma)
- blacklist_drift_count += 1
- continue
- modified_vmas.append(vma)
- reattest_only_count += 1
- if reattest_only_count:
- print(f" [.] also queueing {reattest_only_count} already-mangled "
- f"cstring page(s) for re-attestation")
- if blacklist_drift_count:
- print(f" [.] {blacklist_drift_count} blacklisted dylib(s) found "
- f"mangled on disk — see drift warnings above")
-
- # Page-hash re-attestation. On hardware with TXM enforcement
- # (`codeSigningMonitor == 2` — iPhone17,3 / iOS 26.1), the kernel
- # defers per-page validation to TXM (vm_fault.c:2763-2780). TXM has
- # the original SHA-256 slot hashes baked in via the DSC's chunk-
- # level CS_CodeDirectory, so a byte-mangle alone causes
- # `KERN_PROTECTION_FAILURE` / `CODESIGNING / Invalid Page` SIGKILL
- # of any process that demand-pages the patched page. Recomputing
- # the slot hash makes the modified (content, hash) pair consistent.
- # The CDHash of the CD blob changes as a side-effect but TXM
- # accepts it at DSC mount time on this build (verified empirically).
- if modified_vmas and not dry_run:
- print(f" [.] re-attesting {len(modified_vmas)} modified page(s)...")
- reattest_modified_pages(chunks, modified_vmas, dry_run=False)
- elif modified_vmas and dry_run:
- print(f" [.] dry-run: would re-attest {len(modified_vmas)} "
- f"modified page(s)")
- reattest_modified_pages(chunks, modified_vmas, dry_run=True)
-
- print(f" [+] DSC patch complete: {patched_total} cstring(s) mangled, "
- f"{skipped_in_blacklist} in-blacklist (left unpatched), "
- f"{skipped_unclassified} unclassified, "
- f"{refused} refused/error")
- return results
diff --git a/scripts/patchers/cfw_patch_iomfb_force_kern.py b/scripts/patchers/cfw_patch_iomfb_force_kern.py
deleted file mode 100644
index 85e7fe42..00000000
--- a/scripts/patchers/cfw_patch_iomfb_force_kern.py
+++ /dev/null
@@ -1,177 +0,0 @@
-"""Force IOMobileFramebuffer to present through the kern (userclient method-5)
-path instead of the virt (in-process callback) path.
-
-Why: on the vphone600 26.x kernel the host VZ display is fed by the guest
-AppleParavirtGPU scanout, which is driven ONLY by the IOMFB userclient swap
-methods — the `_kern_Swap*` family (`_kern_SwapEnd` == external method 5).
-26.x userlands presented via `_kern_*` (which is why the SwapEnd size patch,
-cfw_patch_iomfb_swapend, fixed the VZ view on 26.0/18.x). iOS 27 routes the
-paravirt display's present through the PARALLEL `_virt_Swap*` family instead —
-`_virt_SwapEnd` performs no userclient call; it invokes an in-process callback
-and hands the composited IOSurface to a virtual-display consumer. Those frames
-never enter the kernel userclient, so the paravirt GPU never scans out and the
-host VZ window stays black (the guest still composites — the GUI is visible
-over the in-guest TrollVNC capturer, and AppleParavirtGPU's scheduler sits idle).
-
-The public `_IOMobileFramebufferSwap*` entrypoints are thin dispatch
-trampolines that tail-call a per-connection function pointer:
-
- cbz x0, <fail>
- ldr xN, [x0, #<slot>] ; the connection's swap fp (kern or virt impl)
- cbz xN, <fail>
- braaz xN ; tail-call, all argument registers intact
-
-This patcher rewrites the FIRST instruction of each such trampoline to an
-unconditional `b _kern_Swap<Name>`. Because the trampoline tail-calls with the
-argument registers untouched, `b _kern_Swap<Name>` is behaviourally identical
-to the connection having selected the kern fp — every present call now routes
-through the kern/method-5 implementation regardless of how iOS 27 classified
-the display.
-
-Companion kernel patch (KernelJBPatchIomfbSwap): make the 26.4 userclient
-accept iOS 27's native 0x6e0 SwapEnd struct (26.x sent 0x588). Both are
-required together — forcing kern without the kernel size-accept makes method 5
-return kIOReturnBadArgument.
-
-Nothing is hardcoded: the public entrypoints and their `_kern_` counterparts
-are resolved by NAME via `ipsw dyld symaddr`, the trampoline shape is verified
-by Capstone decode, and the replacement branch bytes come from the
-Keystone-backed `asm_at()` helper. The modified DSC code page(s) are re-attested.
-"""
-
-import os
-import re
-import shutil
-import subprocess
-
-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"
-
-# The present transaction the render server drives; each public entrypoint is
-# retargeted to its `_kern_` sibling if (and only if) it is a thin dispatch
-# trampoline. The set is discovered at runtime — this is the minimum that MUST
-# be present for the patch to be meaningful (else we raise, rather than ship a
-# half-forced, incoherent swap path).
-REQUIRED = ("SwapBegin", "SwapEnd", "SwapSetLayer")
-
-
-def _all_symbols(dsc_path, image):
- """Return {symbol_name: vmaddr} for every symbol `ipsw` reports in `image`."""
- ipsw_bin = shutil.which("ipsw")
- if not ipsw_bin:
- raise RuntimeError("`ipsw` not in PATH")
- out = subprocess.run(
- [ipsw_bin, "dyld", "symaddr", dsc_path, "--image", image],
- capture_output=True, text=True, check=True,
- ).stdout
- syms = {}
- for line in out.splitlines():
- line = re.sub(r"\x1b\[[0-9;]*m", "", line)
- m = re.match(r"\s*(0x[0-9A-Fa-f]+):\s+\([^)]*\)\s+(\S+)", line)
- if m:
- syms.setdefault(m.group(2), int(m.group(1), 16))
- return syms
-
-
-def _is_dispatch_trampoline(chunks, va):
- """True iff the 4 insns at `va` are `cbz x0,.. ; ldr xN,[x0,#imm] ; cbz xN,.. ; braaz xN`."""
- insns = list(_cs.disasm(chunks.bytes_at_vma(va, 4 * 4), va))
- if len(insns) < 4:
- return False
- i0, i1, i2, i3 = insns[:4]
- if i0.mnemonic != "cbz" or not i0.op_str.startswith("x0,"):
- return False
- if i1.mnemonic != "ldr" or "[x0, #" not in i1.op_str:
- return False
- reg = i1.op_str.split(",")[0].strip() # scratch reg the fp is loaded into
- if i2.mnemonic != "cbz" or not i2.op_str.startswith(reg + ","):
- return False
- if i3.mnemonic not in ("braaz", "braa", "br") or not i3.op_str.startswith(reg):
- return False
- return True
-
-
-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}")
-
- if dsc_path is None:
- dsc_path = os.path.join(chunks_dir, "dyld_shared_cache_arm64e")
-
- syms = _all_symbols(dsc_path, IOMFB)
-
- # Every public swap entrypoint with a `_kern_` sibling.
- pub_prefix = "_IOMobileFramebufferSwap"
- candidates = []
- for name, va in syms.items():
- if not name.startswith(pub_prefix):
- continue
- suffix = "Swap" + name[len(pub_prefix):] # e.g. "SwapEnd"
- kern = "_kern_" + suffix
- if kern in syms:
- candidates.append((suffix, name, va, kern, syms[kern]))
- candidates.sort()
-
- modified = []
- forced = set()
- already = set()
- for suffix, pub_name, pub_va, kern_name, kern_va in candidates:
- first = next(_cs.disasm(chunks.bytes_at_vma(pub_va, 4), pub_va), None)
- # Idempotent: a prior run already rewrote this entrypoint to `b _kern_*`.
- if first is not None and first.mnemonic == "b":
- m = re.match(r"#(0x[0-9a-fA-F]+)$", first.op_str.strip())
- if m and int(m.group(1), 16) == kern_va:
- print(f" [=] {pub_name} already -> b {kern_name} (idempotent)")
- already.add(suffix)
- continue
- if not _is_dispatch_trampoline(chunks, pub_va):
- print(f" [=] {pub_name} not a thin trampoline; leaving on virt path")
- continue
- b_bytes = asm_at(f"b #{kern_va}", pub_va)
- if len(b_bytes) != 4:
- raise RuntimeError(f"expected 4 bytes for b, got {len(b_bytes)}")
- 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)
-
- covered = forced | already
- missing = [s for s in REQUIRED if s not in covered]
- if missing:
- raise ValueError(
- f"force-kern did not cover required entrypoints {missing} "
- f"(newly forced: {sorted(forced)}; already forced: {sorted(already)})"
- )
-
- if dry_run:
- print(f" [.] dry-run: would re-attest {len(set(modified))} page(s)")
- elif modified:
- print(f" [.] re-attesting {len(set(modified))} modified page(s)...")
- reattest_modified_pages(chunks, modified, dry_run=False)
- for va in modified:
- ins = next(_cs.disasm(chunks.bytes_at_vma(va, 4), va))
- if ins.mnemonic != "b":
- raise RuntimeError(f"post-write verify failed at 0x{va:X} ({ins.mnemonic})")
- else:
- print(f" [=] all {len(already)} entrypoint(s) already forced; nothing to patch/re-attest")
-
- print(f" [+] IOMFB force-kern complete: {len(forced)} newly forced, {len(already)} already -> _kern_*")
- return len(modified)
diff --git a/scripts/patchers/cfw_patch_iomfb_swapend.py b/scripts/patchers/cfw_patch_iomfb_swapend.py
deleted file mode 100644
index b17ff3e9..00000000
--- a/scripts/patchers/cfw_patch_iomfb_swapend.py
+++ /dev/null
@@ -1,188 +0,0 @@
-"""Patch IOMobileFramebuffer SwapEnd payload size to match the base kernel.
-
-The SwapEnd input-state size is enforced kernel-side: the PCC vphone600
-kernel's IOMobileFramebufferUserClient external method 5 (SwapEnd /
-swap_submit) does an exact `checkStructureInputSize` check. A userland whose
-`_kern_SwapEnd` sends a different size gets kIOReturnBadArgument, so no frame
-is presented and the host VZ display stays black (the guest still renders —
-the Apple logo is visible over VNC, just not in the vphone-cli view).
-
-The accepted size is a property of the BASE KERNEL, not the userland:
- - 26.1 base (older): userclient expects 0x560.
- - 26.4 base (xnu-12377, current): userclient expects 0x588. Confirmed two
- ways: the sole dispatch-shaped entry in kernelcache.*.vphone600 with
- checkStructureInputSize==0x588 (scalarIn=0, scalarOut=0, structOut=0,
- preceded by a ptrauth code ptr), and empirically — native 26.5 userland
- sends 0x588 and displays correctly on this stack.
-
-Known userland-sent sizes: 18.6.2 -> 0x514, 26.0/26.0.1 -> 0x548,
-26.5 -> 0x588 (native match on 26.4), 27.0 (24A5380h) -> 0x6e0.
-
-`_kern_SwapEnd` sets up an external-method-5 call:
-
- ldr w0, [x0,#0x14]
- add x2, x19,#0x18
- mov w1,#5 <- external method selector 5
- mov w3,#<size> <- input-state size (source; version-specific)
- mov x4,#0
- mov x5,#0
- bl _io_connect_method
-
-The `mov w3,#<size>` immediate is what this patcher rewrites to the target
-size (default 0x588 for the 26.4 base; override via `target_size`). The site
-is located dynamically: resolve `_kern_SwapEnd`, disassemble it with Capstone,
-and anchor on the semantic call-setup shape (selector `mov w1,#5` then
-`mov w3,#imm` then the zeroed `mov x4,#0`/`mov x5,#0` and the `bl`). Nothing
-about the source size is hardcoded — it is discovered, never matched — so this
-fires on any userland; the replacement immediate comes from the
-Keystone-backed `asm()` helper.
-"""
-
-import os
-import re
-import shutil
-import subprocess
-
-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"
-SWAPEND_SYMBOL = "_kern_SwapEnd"
-
-# External-method selector for SwapEnd, and the input-state size the 26.4
-# vphone600 userclient accepts (checkStructureInputSize). TARGET_SIZE is the
-# semantic goal, not an anchor — the source immediate (e.g. 0x6e0 on 27.0) is
-# discovered, never matched. Override via patch_iomfb_swapend(target_size=...)
-# when building against a different base kernel (26.1 base wants 0x560).
-SWAPEND_SELECTOR = 5
-TARGET_SIZE = 0x588
-
-
-def _resolve_symbol(dsc_path, image, symbol):
- """Resolve a single symbol's vmaddr in `image` via `ipsw dyld symaddr`.
- Returns the vmaddr, or raises if unresolved. Mirrors the resolution
- idiom in cfw_patch_camera_dsc."""
- ipsw_bin = shutil.which("ipsw")
- if not ipsw_bin:
- raise RuntimeError("`ipsw` not in PATH")
- cmd = [ipsw_bin, "dyld", "symaddr", dsc_path, "--image", image, symbol]
- out = subprocess.run(cmd, capture_output=True, text=True, check=True).stdout
- for line in out.splitlines():
- line = re.sub(r"\x1b\[[0-9;]*m", "", line).rstrip()
- m = re.match(r"\s*(0x[0-9A-Fa-f]+):.*\b" + re.escape(symbol) + r"\b", line)
- if m:
- return int(m.group(1), 16)
- raise RuntimeError(f"could not resolve {symbol} in {image}")
-
-
-def _find_swap_size_insn(insns):
- """Locate the `mov w3,#imm` that sets the SwapEnd input-state size.
-
- Anchored on the external-method call setup: `mov w1,#5` (selector),
- immediately followed by `mov w3,#imm`, then `mov x4,#0`, `mov x5,#0`,
- and a `bl`. Returns that insn, or None if the shape isn't found.
- """
- for i in range(len(insns) - 4):
- sel = _mov_reg_imm(insns[i])
- if sel != ("w1", SWAPEND_SELECTOR):
- continue
- size = _mov_reg_imm(insns[i + 1])
- if size is None or size[0] != "w3":
- continue
- if _mov_reg_imm(insns[i + 2]) != ("x4", 0):
- continue
- if _mov_reg_imm(insns[i + 3]) != ("x5", 0):
- continue
- if insns[i + 4].mnemonic != "bl":
- continue
- return insns[i + 1]
- return None
-
-
-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}")
-
- if dsc_path is None:
- dsc_path = os.path.join(chunks_dir, "dyld_shared_cache_arm64e")
-
- fn_vma = _resolve_symbol(dsc_path, IOMFB, SWAPEND_SYMBOL)
- print(f" [.] {SWAPEND_SYMBOL} @ 0x{fn_vma:X}")
-
- insns = _disasm_function(chunks, fn_vma, 64)
- target = _find_swap_size_insn(insns)
- if target is None:
- raise ValueError(
- f"{SWAPEND_SYMBOL} SwapEnd size site (mov w1,#{SWAPEND_SELECTOR} "
- f"-> mov w3,#imm -> ... -> bl) not found"
- )
-
- _reg, cur_size = _mov_reg_imm(target)
- insn_vma = target.address
- new_bytes = asm(f"mov w3, #{target_size}")
- if len(new_bytes) != 4:
- raise RuntimeError(f"expected 4 bytes, got {len(new_bytes)}")
-
- if cur_size == target_size:
- print(f" [=] already 0x{target_size:X} at 0x{insn_vma:X}; "
- f"re-attesting page only")
- else:
- action = "would patch" if dry_run else "patched"
- 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:
- print(f" [.] re-attesting modified page...")
- reattest_modified_pages(chunks, [insn_vma], dry_run=False)
- if chunks.bytes_at_vma(insn_vma, 4) != new_bytes:
- raise RuntimeError(f"post-write verify failed at 0x{insn_vma:X}")
- else:
- print(f" [.] dry-run: would re-attest page for 0x{insn_vma:X}")
-
- print(f" [+] IOMFB SwapEnd patch complete")
- return 1
-
-
-def _self_test():
- """Validate the finder against a synthetic call-setup sequence built
- from the assembler, with a source size (0x548) unlike the target."""
- seq = (
- asm("ldr w0, [x0, #0x14]")
- + asm("add x2, x19, #0x18")
- + asm("mov w1, #5")
- + asm("mov w3, #0x548")
- + asm("mov x4, #0")
- + asm("mov x5, #0")
- + asm("bl #0x40")
- )
- insns = list(_cs.disasm(seq, 0x1000))
- target = _find_swap_size_insn(insns)
- assert target is not None, "finder failed to locate size insn"
- reg, imm = _mov_reg_imm(target)
- assert (reg, imm) == ("w3", 0x548), (reg, hex(imm))
- assert target.address == 0x1000 + 12, hex(target.address)
- assert TARGET_SIZE == 0x588, hex(TARGET_SIZE)
- assert asm(f"mov w3, #{TARGET_SIZE}") == bytes.fromhex("03b18052")
- print("self-test OK")
-
-
-if __name__ == "__main__":
- _self_test()
diff --git a/scripts/patchers/cfw_patch_jetsam.py b/scripts/patchers/cfw_patch_jetsam.py
deleted file mode 100644
index 1cac37f3..00000000
--- a/scripts/patchers/cfw_patch_jetsam.py
+++ /dev/null
@@ -1,163 +0,0 @@
-"""launchd jetsam patch module."""
-
-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):
- if op.type == ARM64_OP_IMM:
- return op.imm
- return -1
-
-
-def _is_return_block(data, foff, text_foff, text_size):
- """Check if foff points to a function return sequence (ret/retab within 8 insns)."""
- for i in range(8):
- check = foff + i * 4
- if check >= text_foff + text_size:
- break
- insns = disasm_at(data, check, 1)
- if not insns:
- continue
- if insns[0].mnemonic in ("ret", "retab"):
- return True
- # Stop at unconditional branches (different block)
- if insns[0].mnemonic in ("b", "bl", "br", "blr"):
- break
- return False
-
-
-def patch_launchd_jetsam(filepath):
- """Bypass launchd jetsam panic path via dynamic string-xref branch rewrite.
-
- Anchor strategy:
- 1. Find jetsam panic string in cstring-like data.
- 2. Find ADRP+ADD xref to the string start in __TEXT,__text.
- 3. Search backward for a conditional branch whose target is the function's
- return/success path (basic block containing ret/retab).
- 4. Rewrite that conditional branch to unconditional `b <same_target>`,
- so the function always returns success and never reaches the panic.
- """
- data = bytearray(open(filepath, "rb").read())
- sections = parse_macho_sections(data)
-
- text_sec = find_section(sections, "__TEXT,__text")
- if not text_sec:
- print(" [-] __TEXT,__text not found")
- return False
-
- text_va, text_size, text_foff = text_sec
- code = bytes(data[text_foff : text_foff + text_size])
-
- cond_mnemonics = {
- "b.eq",
- "b.ne",
- "b.cs",
- "b.hs",
- "b.cc",
- "b.lo",
- "b.mi",
- "b.pl",
- "b.vs",
- "b.vc",
- "b.hi",
- "b.ls",
- "b.ge",
- "b.lt",
- "b.gt",
- "b.le",
- "cbz",
- "cbnz",
- "tbz",
- "tbnz",
- }
-
- anchors = [
- b"jetsam property category (Daemon) is not initialized",
- b"jetsam property category",
- b"initproc exited -- exit reason namespace 7 subcode 0x1",
- ]
-
- for anchor in anchors:
- hit_off = data.find(anchor)
- if hit_off < 0:
- continue
-
- sec_foff = -1
- sec_va = -1
- for _, (sva, ssz, sfoff) in sections.items():
- if sfoff <= hit_off < sfoff + ssz:
- sec_foff = sfoff
- sec_va = sva
- break
- if sec_foff < 0:
- continue
-
- str_start_off = _find_cstring_start(data, hit_off, sec_foff)
- str_start_va = sec_va + (str_start_off - sec_foff)
-
- ref_va = _find_adrp_add_ref(code, text_va, str_start_va)
- if ref_va < 0:
- continue
- ref_foff = text_foff + (ref_va - text_va)
-
- print(f" Found jetsam anchor '{anchor.decode(errors='ignore')}'")
- print(f" string start: va:0x{str_start_va:X}")
- print(f" xref at foff:0x{ref_foff:X}")
-
- # Search backward from xref for conditional branches targeting
- # the function's return path (block containing ret/retab).
- # Pick the earliest (farthest back) one — it skips the most
- # jetsam-related code and matches the upstream patch strategy.
- scan_lo = max(text_foff, ref_foff - 0x300)
- patch_off = -1
- patch_target = -1
-
- for back in range(ref_foff - 4, scan_lo - 1, -4):
- insns = disasm_at(data, back, 1)
- if not insns:
- continue
- insn = insns[0]
- if insn.mnemonic not in cond_mnemonics:
- continue
-
- tgt = _extract_branch_target_off(insn)
- if tgt < 0:
- continue
- # Target must be a valid file offset within __text
- if tgt < text_foff or tgt >= text_foff + text_size:
- continue
- # Target must be a return block (contains ret/retab)
- if _is_return_block(data, tgt, text_foff, text_size):
- patch_off = back
- patch_target = tgt
- # Don't break — keep scanning for an earlier match
-
- if patch_off < 0:
- continue
-
- ctx_start = max(text_foff, patch_off - 8)
- print(f" Before:")
- _log_asm(data, ctx_start, 5, patch_off)
-
- data[patch_off : patch_off + 4] = asm_at(f"b #0x{patch_target:X}", patch_off)
-
- 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
-
- print(" [-] Dynamic jetsam anchor/xref not found")
- return False
-
diff --git a/scripts/patchers/cfw_patch_lockdown_mode.py b/scripts/patchers/cfw_patch_lockdown_mode.py
deleted file mode 100644
index 71e748d6..00000000
--- a/scripts/patchers/cfw_patch_lockdown_mode.py
+++ /dev/null
@@ -1,124 +0,0 @@
-"""Stop libSystem's `os_lockdown_mode_enabled` from crashing on the vphone kernel.
-
-iOS 27's `os_lockdown_mode_enabled()` resolves Lockdown Mode once via
-`sysctlbyname("security.mac.lockdown_mode_state_public", ...)` and, if the
-sysctl call returns -1, calls `os_crash` (lockdown_mode.c). The vphone base
-kernel (cloudOS 26.x) does not implement that MAC sysctl, so the call fails
-with ENOENT and every process that queries Lockdown Mode aborts — including
-launchd (pid 1), which panics the system right after "Continuing system boot".
-
-The block pre-zeroes its output buffer (`stp x8, xzr, [sp]`), so dropping the
-error branch makes the failure path fall through to the normal path, read 0,
-and record "Lockdown Mode disabled". On a kernel that does implement the sysctl
-the branch is never taken, so the patch is behavior-neutral there.
-
-Shape (in `___os_lockdown_mode_enabled_block_invoke`):
-
- bl <sysctlbyname>
- cmn w0, #1 ; w0 == -1 ?
- b.eq <os_crash> ; -> NOP
-
-Anchored on the in-image local symbol; the sysctl-error idiom is located by
-control-flow shape via Capstone; the NOP comes from Keystone; the modified page
-is re-attested (`cfw_dsc_codesign.py`).
-"""
-
-from capstone.arm64_const import ARM64_OP_IMM
-
-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",
- "__os_lockdown_mode_enabled_block_invoke",
-)
-
-
-def _imm(insn, idx):
- ops = insn.operands
- return ops[idx].imm if idx < len(ops) and ops[idx].type == ARM64_OP_IMM else None
-
-
-def _find_error_gate(insns):
- """The `cmn wR, #1; b.eq` sysctl-error idiom, preceded by a bl.
-
- The branch slot is also matched once it holds the NOP this patch writes.
- Without that, a second pass over an already-installed cache never reaches
- the byte comparison below — the idiom it searches for is the one the patch
- has already replaced — and the patcher fails instead of reporting a no-op.
- The `bl` + `cmn wR, #1` anchor is unchanged, so widening the slot does not
- weaken where the match can land; re-writing a NOP over a NOP is inert.
- """
- saw_bl = False
- for i in range(len(insns) - 1):
- if insns[i].mnemonic == "bl":
- saw_bl = True
- if not saw_bl:
- continue
- if insns[i].mnemonic == "cmn" and _imm(insns[i], 1) == 1:
- gate = insns[i + 1]
- if gate.mnemonic in ("b.eq", "nop"):
- return gate
- return None
-
-
-def patch_lockdown_mode(chunks_dir, *, dry_run=False):
- records.set_group("lockdown_mode")
- chunks = DSCChunks(chunks_dir)
- print(f" [.] {chunks!r}")
-
- fn_vma = None
- for name in SYMBOL_CANDIDATES:
- try:
- fn_vma = resolve_local_symbol(chunks_dir, name)
- break
- except RuntimeError:
- continue
- if fn_vma is None:
- print(" [=] os_lockdown_mode_enabled not present (pre-iOS-27 userland); nothing to patch")
- return 0
- print(f" [.] {name} @ 0x{fn_vma:X}")
-
- gate = _find_error_gate(_disasm_function(chunks, fn_vma, 60))
- if gate is None:
- raise ValueError(
- "lockdown_mode: `cmn wR,#1; b.eq <crash>` sysctl-error gate not found "
- "(nor an already-NOPed one)"
- )
- print(f" [.] gate @ 0x{gate.address:X}: {gate.mnemonic} {gate.op_str}")
-
- nop = asm("nop")
- cur = chunks.bytes_at_vma(gate.address, 4)
- if cur == nop:
- print(f" [=] already patched at 0x{gate.address:X}; nothing to patch/re-attest")
- return 1
- 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:
- raise RuntimeError(f"post-write verify failed at 0x{gate.address:X}")
- print(" [+] lockdown-mode crash patch complete")
- return 1
-
-
-if __name__ == "__main__":
- import sys
- dry = "--apply" not in sys.argv
- args = [a for a in sys.argv[1:] if not a.startswith("--")]
- d = args[0] if args else "/private/tmp/cryptex27/System/Library/Caches/com.apple.dyld"
- patch_lockdown_mode(d, dry_run=dry)
diff --git a/scripts/patchers/cfw_patch_lsd_embedded_reg.py b/scripts/patchers/cfw_patch_lsd_embedded_reg.py
deleted file mode 100644
index 9bb231ae..00000000
--- a/scripts/patchers/cfw_patch_lsd_embedded_reg.py
+++ /dev/null
@@ -1,146 +0,0 @@
-"""Patch LaunchServices so lsd allows app (re)registration from any client.
-
-iOS 27's lsd gates `-[_LSDModifyClient performPostInstallationRegistration:...]`
-(and the sibling containerized/rebuild registration paths) behind
-`-[_LSDModifyClient clientIsEntitledForEmbeddedRegistrationOperations]`, which
-does `xpc_connection_copy_entitlement_value` on the XPC PEER for any of three
-privileged entitlements (com.apple.private.coreservices.lsaw /
-com.apple.private.installcoordinationd.daemon /
-com.apple.private.coreservices.can-register-install-results). A client without
-one gets NSError NSOSStatusErrorDomain -54 (permErr) from LSDModifyService.mm,
-so `registerApplicationDictionary:` returns NO. This blocks JB app registration
-(uicache/Sileo), vphoned's IPA installer, and TrollStore alike.
-
-The entitlement route is a dead end on this stack: even a launchd-spawned
-platform daemon (vphoned) with all three entitlements in its VALIDATED csblob
-(csops CS_OPS_ENTITLEMENTS_BLOB confirms) is still rejected, because the XPC
-peer lsd inspects is not the registering process (LS registration is proxied).
-
-So force the check to always succeed. `clientIsEntitledForEmbeddedRegistration
-Operations` ORs three entitlement checks:
-
- bl <check ent1> ; cbnz w0, entitled
- bl <check ent2> ; cbnz w0, entitled
- bl <check ent3> ; cbz w0, not_entitled <- gate: NOP this
- entitled:
- mov w20, #1 <- YES result (returned)
- ... ; mov x0, x20 ; retab
- not_entitled:
- mov w20, #0 -> returns 0
-
-NOP'ing the final `cbz w0, <not_entitled>` (the one whose fall-through is the
-`mov w<result>, #1`) makes every path reach the YES result. One instruction.
-
-Nothing is hardcoded: the method is resolved from the DSC's own local-symbol
-table (in-image), disassembled with Capstone, and the gate located by
-control-flow shape (the conditional branch immediately preceding the `mov
-w<reg>,#1` that becomes the return value). The replacement is Keystone `nop`.
-Modifying a DSC page invalidates its 16 KiB slot hash, so the page is
-re-attested (TXM enforces per-page); the resulting CDHash change is accepted by
-the JB's always-true AMFI cdhash-trust patch.
-"""
-
-from capstone.arm64_const import ARM64_OP_REG
-
-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"
-METHOD = "-[_LSDModifyClient clientIsEntitledForEmbeddedRegistrationOperations]"
-
-
-def _find_gate(insns):
- """Locate the conditional branch that gates the entitled result: the
- `cbz`/`cbnz` on w0 whose fall-through instruction is `mov w<reg>,#1`
- (the YES value later moved to x0). Returns (insn, result_reg) or None.
-
- Also matches an already-patched site: a bare `nop` (this patch's own
- output) immediately before the same `mov w<reg>,#1`, so a re-run against
- an already-patched cache is recognized as idempotent instead of failing
- to find the (now gone) conditional branch."""
- for i in range(len(insns) - 1):
- ins = insns[i]
- is_branch = ins.mnemonic in ("cbz", "cbnz")
- if is_branch:
- ops = ins.operands
- if not ops or ops[0].type != ARM64_OP_REG or ins.reg_name(ops[0].reg) != "w0":
- continue
- elif ins.mnemonic != "nop":
- continue
- nxt = _mov_reg_imm(insns[i + 1])
- if nxt is not None and nxt[1] == 1 and nxt[0].startswith("w"):
- return ins, nxt[0]
- return None
-
-
-def patch_lsd_embedded_reg(chunks_dir, *, dry_run=False):
- records.set_group("lsd_embedded_reg")
- chunks = DSCChunks(chunks_dir)
- print(f" [.] {chunks!r}")
-
- # Self-gating: the gate method only exists on iOS 27+ LaunchServices. On
- # older userlands (26.x/18.x) it is absent, so this is a no-op there.
- try:
- fn_vma = resolve_local_symbol(chunks_dir, METHOD)
- except RuntimeError:
- print(f" [=] {METHOD} not present (pre-iOS-27 userland); nothing to patch")
- return 0
- print(f" [.] {METHOD} @ 0x{fn_vma:X}")
-
- insns = _disasm_function(chunks, fn_vma, 96)
- found = _find_gate(insns)
- if found is None:
- raise ValueError(
- f"{METHOD}: entitled-result gate (cbz/cbnz w0 -> mov w<reg>,#1) not found"
- )
- gate, result_reg = found
- insn_vma = gate.address
- print(f" [.] gate: {gate.mnemonic} {gate.op_str} @ 0x{insn_vma:X} "
- f"(fall-through sets {result_reg}=1)")
-
- nop = asm("nop")
- if len(nop) != 4:
- raise RuntimeError(f"expected 4 nop bytes, got {len(nop)}")
-
- cur = chunks.bytes_at_vma(insn_vma, 4)
- if cur == nop:
- print(f" [=] already NOP at 0x{insn_vma:X}; re-attesting page only")
- else:
- action = "would NOP" if dry_run else "NOP'd"
- 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:
- print(f" [.] re-attesting modified page...")
- reattest_modified_pages(chunks, [insn_vma], dry_run=False)
- if chunks.bytes_at_vma(insn_vma, 4) != nop:
- raise RuntimeError(f"post-write verify failed at 0x{insn_vma:X}")
- else:
- print(f" [.] dry-run: would re-attest page for 0x{insn_vma:X}")
-
- print(f" [+] lsd embedded-registration gate patch complete")
- return 1
-
-
-if __name__ == "__main__":
- import sys
- dry = "--apply" not in sys.argv
- args = [a for a in sys.argv[1:] if not a.startswith("--")]
- d = args[0] if args else "/private/tmp/cryptex27/System/Library/Caches/com.apple.dyld"
- patch_lsd_embedded_reg(d, dry_run=dry)
diff --git a/scripts/patchers/cfw_patch_mobileactivationd.py b/scripts/patchers/cfw_patch_mobileactivationd.py
deleted file mode 100644
index f95fbee2..00000000
--- a/scripts/patchers/cfw_patch_mobileactivationd.py
+++ /dev/null
@@ -1,158 +0,0 @@
-"""mobileactivationd patch module."""
-
-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."""
- sections = parse_macho_sections(data)
-
- # Find "should_hactivate\0" string
- selector = b"should_hactivate\x00"
- sel_foff = data.find(selector)
- if sel_foff < 0:
- print(" [-] Selector 'should_hactivate' not found in binary")
- return -1
-
- # Compute selector VA
- sel_va = -1
- for sec_name, (sva, ssz, sfoff) in sections.items():
- if sfoff <= sel_foff < sfoff + ssz:
- sel_va = sva + (sel_foff - sfoff)
- break
-
- if sel_va < 0:
- print(f" [-] Could not compute VA for selector at foff:0x{sel_foff:X}")
- return -1
-
- print(f" Selector at foff:0x{sel_foff:X} va:0x{sel_va:X}")
-
- # Find selref that points to this selector
- selrefs = find_section(
- sections,
- "__DATA_CONST,__objc_selrefs",
- "__DATA,__objc_selrefs",
- "__AUTH_CONST,__objc_selrefs",
- )
-
- selref_foff = -1
- selref_va = -1
-
- if selrefs:
- sr_va, sr_size, sr_foff = selrefs
- for i in range(0, sr_size, 8):
- ptr = struct.unpack_from("<Q", data, sr_foff + i)[0]
- # Handle chained fixups: try exact and masked match
- if ptr == sel_va or (ptr & 0x0000FFFFFFFFFFFF) == sel_va:
- selref_foff = sr_foff + i
- selref_va = sr_va + i
- break
-
- # Also try: lower 32 bits might encode the target in chained fixups
- if (ptr & 0xFFFFFFFF) == (sel_va & 0xFFFFFFFF):
- selref_foff = sr_foff + i
- selref_va = sr_va + i
- break
-
- if selref_foff < 0:
- print(" [-] Selref not found (chained fixups may obscure pointers)")
- return -1
-
- print(f" Selref at foff:0x{selref_foff:X} va:0x{selref_va:X}")
-
- # Search for relative method list entry pointing to this selref
- # Relative method entries: { int32 name_rel, int32 types_rel, int32 imp_rel }
- # name_field_va + name_rel = selref_va
-
- objc_const = find_section(
- sections,
- "__DATA_CONST,__objc_const",
- "__DATA,__objc_const",
- "__AUTH_CONST,__objc_const",
- )
-
- if objc_const:
- oc_va, oc_size, oc_foff = objc_const
-
- for i in range(0, oc_size - 12, 4):
- entry_foff = oc_foff + i
- entry_va = oc_va + i
- rel_name = struct.unpack_from("<i", data, entry_foff)[0]
- target_va = entry_va + rel_name
-
- if target_va == selref_va:
- # Found the method entry! Read IMP relative offset
- imp_field_foff = entry_foff + 8
- imp_field_va = entry_va + 8
- rel_imp = struct.unpack_from("<i", data, imp_field_foff)[0]
- imp_va = imp_field_va + rel_imp
- imp_foff = va_to_foff(bytes(data), imp_va)
-
- if imp_foff >= 0:
- print(
- f" Found via relative method list: IMP va:0x{imp_va:X} foff:0x{imp_foff:X}"
- )
- return imp_foff
- else:
- print(
- f" [!] IMP va:0x{imp_va:X} could not be mapped to file offset"
- )
-
- return -1
-
-
-def patch_mobileactivationd(filepath):
- """Dynamically find -[DeviceType should_hactivate] and patch to return YES.
-
- Anchor strategies (in order):
- 1. Search LC_SYMTAB for symbol containing "should_hactivate"
- 2. Parse ObjC metadata: methnames -> selrefs -> method_list -> IMP
-
- The method determines if the device should self-activate (hackivation).
- Patching it to always return YES bypasses activation lock.
- """
- data = bytearray(open(filepath, "rb").read())
-
- imp_foff = -1
-
- # Strategy 1: Symbol table lookup (most reliable)
- imp_va = find_symbol_va(bytes(data), "should_hactivate")
- if imp_va > 0:
- imp_foff = va_to_foff(bytes(data), imp_va)
- if imp_foff >= 0:
- print(f" Found via symtab: va:0x{imp_va:X} -> foff:0x{imp_foff:X}")
-
- # Strategy 2: ObjC metadata chain
- if imp_foff < 0:
- imp_foff = _find_via_objc_metadata(data)
-
- # All dynamic strategies exhausted
- if imp_foff < 0:
- print(" [-] Dynamic anchor not found — all strategies exhausted")
- return False
-
- # Verify the target looks like code
- if imp_foff + 8 > len(data):
- print(f" [-] IMP offset 0x{imp_foff:X} out of bounds")
- return False
-
- print(f" Before:")
- _log_asm(data, imp_foff, 4, imp_foff)
-
- # Patch to: mov x0, #1; ret
- data[imp_foff : imp_foff + 4] = MOV_X0_1
- data[imp_foff + 4 : imp_foff + 8] = RET
-
- 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
deleted file mode 100644
index 51bb3e2d..00000000
--- a/scripts/patchers/cfw_patch_post_restore_dt.py
+++ /dev/null
@@ -1,347 +0,0 @@
-#!/usr/bin/env python3
-"""cfw_patch_post_restore_dt.py — post-restore DT identity rewrite.
-
-Applies the three restore-unsafe DT property edits that broke earlier
-attempts when applied at fw_patch time:
-
- root/model "iPhone99,11" -> "iPhone17,3"
- root/target-type "VPHONE600" -> "D47"
- root/compatible ["VPHONE600AP", "*", "AppleVirtualPlatformARM"]
- -> ["D47AP", "VPHONE600AP",
- "AppleVirtualPlatformARM"]
-
-These edits are restore-time-fatal — `restored_external` / iBoot's restore
-mode cross-checks DT root `model` / `target-type` against the
-BuildManifest's signed identity and rejects the device on mismatch — but
-they are NOT boot-time-fatal. After restore completes, the existing iBSS /
-iBEC / LLB image4_validate_property_callback bypass patches accept any
-IM4P contents, so re-patching the DT offline (on the host-mounted restored
-filesystem) before the device boots into the rootfs is safe.
-
-The `compatible` rewrite is a reorder, not a replacement: VPHONE600AP
-stays in the list (now as the second entry) so IOKit's platform-expert
-binding to AppleVMApple1IO still works. The first entry, which userland
-queries for `hw.model`, becomes D47AP — flipping the visible board
-identifier without breaking kernel kext binding.
-
-Layout summary:
-
- before: "VPHONE600AP\\0iPhone99,11\\0AppleVirtualPlatformARM\\0" (48B)
- OR "VPHONE600AP\\0iPhone17,3\\0AppleVirtualPlatformARM\\0\\0" (48B, post-Tier1b)
- after: "D47AP\\0VPHONE600AP\\0AppleVirtualPlatformARM\\0" + 6 NUL pad (48B)
-
-This script runs on the host. The install pipeline copies the
-devicetree.img4 out of the host-mounted `/mnt5/<boot-hash>/usr/standalone/firmware/`,
-this script edits it in place, and the pipeline copies it back to the same
-path. The boot-manifest-hash directory is the same one discovered by
-`get_boot_manifest_hash` in `cfw_install_jb.sh`.
-
-Dependencies:
- pip install pyimg4
- (already in the project's requirements.txt; uses pyimg4's LZFSE
- round-trip + IMG4/IM4P/IM4M repack.)
-
-Idempotent: a re-run on an already-patched img4 detects "no change" and
-exits without rewriting.
-"""
-
-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
-# DeviceTreePatcher.swift's behavior in Swift).
-#
-# Per-node layout:
-# u32 nProps
-# u32 nChildren
-# for each property:
-# char[32] name (NUL-padded)
-# u16 length (high bit = "placeholder" flag, mask 0x7FFF)
-# u16 flags
-# u8[len] value
-# padding to 4-byte boundary
-# for each child:
-# (recursive node)
-# ──────────────────────────────────────────────────────────────────────
-
-
-def _align4(n: int) -> int:
- return (n + 3) & ~3
-
-
-class DTProperty:
- __slots__ = ("name", "length", "flags", "value", "value_offset")
-
- def __init__(self, name, length, flags, value, value_offset):
- self.name = name
- self.length = length
- self.flags = flags
- self.value = value
- self.value_offset = value_offset
-
-
-class DTNode:
- __slots__ = ("properties", "children")
-
- def __init__(self):
- self.properties = []
- self.children = []
-
-
-def _parse_node(blob: bytes, offset: int):
- if offset + 8 > len(blob):
- raise ValueError(f"DT truncated at offset 0x{offset:X}")
- n_props = int.from_bytes(blob[offset : offset + 4], "little")
- n_children = int.from_bytes(blob[offset + 4 : offset + 8], "little")
- pos = offset + 8
- node = DTNode()
- for _ in range(n_props):
- if pos + 36 > len(blob):
- raise ValueError(f"DT property header truncated at 0x{pos:X}")
- name = blob[pos : pos + 32].split(b"\x00", 1)[0].decode("utf-8", errors="replace")
- # Length field's top bit is the "placeholder" / out-of-line flag in some
- # XNU branches; mask it for the actual size.
- raw_len = int.from_bytes(blob[pos + 32 : pos + 34], "little")
- masked_len = raw_len & 0x7FFF
- flags = int.from_bytes(blob[pos + 34 : pos + 36], "little")
- value_off = pos + 36
- value = blob[value_off : value_off + masked_len]
- node.properties.append(DTProperty(name, masked_len, flags, value, value_off))
- pos = value_off + _align4(masked_len)
- for _ in range(n_children):
- child, pos = _parse_node(blob, pos)
- node.children.append(child)
- return node, pos
-
-
-def _serialize_node(node: DTNode) -> bytes:
- out = bytearray()
- out += len(node.properties).to_bytes(4, "little")
- out += len(node.children).to_bytes(4, "little")
- for prop in node.properties:
- name = prop.name.encode("utf-8")
- if len(name) >= 32:
- name = name[:31]
- out += name + b"\x00" * (32 - len(name))
- out += prop.length.to_bytes(2, "little")
- out += prop.flags.to_bytes(2, "little")
- out += prop.value
- pad = _align4(prop.length) - prop.length
- if pad:
- out += b"\x00" * pad
- for child in node.children:
- out += _serialize_node(child)
- return bytes(out)
-
-
-def _get_node_name(node: DTNode) -> str:
- for p in node.properties:
- if p.name == "name":
- return p.value.split(b"\x00", 1)[0].decode("utf-8", errors="replace")
- return ""
-
-
-def _find_property(node: DTNode, name: str) -> DTProperty:
- for p in node.properties:
- if p.name == name:
- return p
- raise KeyError(f"property {name!r} not found in node {_get_node_name(node)!r}")
-
-
-def _encode_fixed_string(s: str, length: int) -> bytes:
- raw = s.encode("utf-8") + b"\x00"
- if len(raw) > length:
- return raw[:length]
- return raw + b"\x00" * (length - len(raw))
-
-
-# ──────────────────────────────────────────────────────────────────────
-# The three patches
-# ──────────────────────────────────────────────────────────────────────
-
-
-def _patch_dt_blob(dt_blob: bytes) -> bytes:
- """Apply the post-restore DT identity rewrites. Returns the new blob.
-
- Raises if the DT structure doesn't match what we expect.
- """
- root, end = _parse_node(dt_blob, 0)
- if end != len(dt_blob):
- raise ValueError(
- f"DT parse length mismatch: ended at {end}, blob is {len(dt_blob)}"
- )
- root_name = _get_node_name(root)
- if root_name != "device-tree":
- raise ValueError(f"expected root node 'device-tree', got {root_name!r}")
-
- changed = []
-
- # 1. root/model → iPhone17,3
- p = _find_property(root, "model")
- new_val = _encode_fixed_string("iPhone17,3", p.length)
- if p.value != new_val:
- before = p.value.split(b"\x00", 1)[0].decode("utf-8", errors="replace")
- p.value = new_val
- changed.append(f"model: '{before}' -> 'iPhone17,3'")
-
- # 2. root/target-type → D47
- p = _find_property(root, "target-type")
- new_val = _encode_fixed_string("D47", p.length)
- if p.value != new_val:
- before = p.value.split(b"\x00", 1)[0].decode("utf-8", errors="replace")
- p.value = new_val
- changed.append(f"target-type: '{before}' -> 'D47'")
-
- # 3. root/compatible reorder
- p = _find_property(root, "compatible")
- new_compat_body = (
- b"D47AP\x00"
- + b"VPHONE600AP\x00"
- + b"AppleVirtualPlatformARM\x00"
- )
- if len(new_compat_body) > p.length:
- raise ValueError(
- f"compatible body {len(new_compat_body)}B > slot {p.length}B"
- )
- new_compat = new_compat_body + b"\x00" * (p.length - len(new_compat_body))
- if p.value != new_compat:
- before_parts = [
- x.decode("utf-8", errors="replace")
- for x in p.value.split(b"\x00")
- if x
- ]
- p.value = new_compat
- changed.append(
- f"compatible: {before_parts} -> ['D47AP', 'VPHONE600AP', "
- f"'AppleVirtualPlatformARM']"
- )
-
- if not changed:
- return dt_blob
-
- for c in changed:
- print(f" [+] {c}")
- return _serialize_node(root)
-
-
-# ──────────────────────────────────────────────────────────────────────
-# img4 / IM4P round-trip
-# ──────────────────────────────────────────────────────────────────────
-
-
-def patch_devicetree_file(path: str, *, dry_run: bool = False) -> int:
- """Patch a devicetree.img4 (preferred) or devicetree.im4p file in
- place. Returns the number of property changes applied (0 if the file
- was already in the target state).
- """
- with open(path, "rb") as f:
- data = f.read()
-
- # Auto-detect IMG4 vs bare IM4P.
- try:
- img4 = pyimg4.IMG4(data)
- is_img4 = True
- im4p = img4.im4p
- except Exception:
- img4 = None
- is_img4 = False
- im4p = pyimg4.IM4P(data)
-
- if im4p.fourcc != "dtre":
- raise ValueError(
- f"expected DT payload (fourcc='dtre'), got fourcc={im4p.fourcc!r}"
- )
- print(
- f" [.] {path}: {'IMG4' if is_img4 else 'IM4P'} "
- f"desc={im4p.description!r} payload_compression={im4p.payload.compression}"
- )
-
- # Decompress
- original_compression = im4p.payload.compression
- if original_compression != pyimg4.Compression.NONE:
- im4p.payload.decompress()
- dt_blob = bytes(im4p.payload.output().data)
- print(f" [.] DT blob: {len(dt_blob)} bytes")
-
- # Apply patches
- new_dt = _patch_dt_blob(dt_blob)
- if new_dt == dt_blob:
- print(f" [.] {path}: DT already in target state — no change")
- return 0
- if len(new_dt) != len(dt_blob):
- # Should be impossible because we preserve every property's slot length,
- # but bail loudly if invariants drift.
- raise RuntimeError(
- f"DT size changed: {len(dt_blob)} -> {len(new_dt)} bytes "
- f"(would break IM4P offsets)"
- )
-
- # Build new IM4P with patched payload, preserving compression mode.
- new_payload = pyimg4.IM4PData(data=new_dt)
- if original_compression != pyimg4.Compression.NONE:
- new_payload.compress(original_compression)
- new_im4p = pyimg4.IM4P(
- fourcc=im4p.fourcc,
- description=im4p.description,
- payload=new_payload,
- )
-
- if is_img4:
- new_img4 = pyimg4.IMG4(im4p=new_im4p, im4m=img4.im4m, im4r=img4.im4r)
- out_bytes = new_img4.output()
- else:
- out_bytes = new_im4p.output()
-
- print(f" [.] output size: {len(out_bytes)} bytes (was {len(data)})")
- if dry_run:
- 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}")
- return 1
-
-
-def _main(argv):
- argv, _ = records.take_cli_flag(argv)
- if len(argv) < 2:
- print(
- "Usage: cfw_patch_post_restore_dt.py [--emit-records <dir>] "
- "<devicetree.img4|im4p> [--dry-run]",
- file=sys.stderr,
- )
- return 2
- path = argv[1]
- dry_run = "--dry-run" in argv[2:]
- try:
- patch_devicetree_file(path, dry_run=dry_run)
- except Exception as e:
- print(f"[-] {type(e).__name__}: Unable to patch {path}: {e}", file=sys.stderr)
- return 1
- return 0
-
-
-if __name__ == "__main__":
- sys.exit(_main(sys.argv))
diff --git a/scripts/patchers/cfw_patch_seputil.py b/scripts/patchers/cfw_patch_seputil.py
deleted file mode 100644
index 7a319c79..00000000
--- a/scripts/patchers/cfw_patch_seputil.py
+++ /dev/null
@@ -1,51 +0,0 @@
-"""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.
-
- Anchor: The format string "/%s.gl" used by seputil to construct the
- gigalocker file path as "{mountpoint}/{uuid}.gl".
-
- Patching "%s" to "AA" in "/%s.gl" makes it "/AA.gl", so the
- full path becomes /mnt7/AA.gl regardless of the device's UUID.
- The actual .gl file on disk is also renamed to AA.gl.
- """
- data = bytearray(open(filepath, "rb").read())
-
- # Search for the format string "/%s.gl\0" — this is the gigalocker
- # filename pattern where %s gets replaced with the device UUID.
- anchor = b"/%s.gl\x00"
- offset = data.find(anchor)
-
- if offset < 0:
- print(" [-] Format string '/%s.gl' not found in seputil")
- return False
-
- # The %s is at offset+1 (2 bytes: 0x25 0x73)
- pct_s_off = offset + 1
- original = bytes(data[offset : offset + len(anchor)])
- print(f" Found format string at 0x{offset:X}: {original!r}")
-
- print(f" Before: {bytes(data[offset : offset + 7]).hex(' ')}")
-
- # Replace %s (2 bytes) with AA — turns "/%s.gl" into "/AA.gl"
- data[pct_s_off] = ord("A")
- data[pct_s_off + 1] = ord("A")
-
- 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")
- return True
diff --git a/scripts/patchers/cfw_patch_watchdogd.py b/scripts/patchers/cfw_patch_watchdogd.py
deleted file mode 100644
index b79ceb76..00000000
--- a/scripts/patchers/cfw_patch_watchdogd.py
+++ /dev/null
@@ -1,467 +0,0 @@
-"""watchdogd surgical patch — force the cached "am I a VM?" byte to 1.
-
-Background
-----------
-After the kernel-side rename of the `kern.hv_vmm_present` sysctl OID
-(see `KernelJBPatchHvVmmRename.swift`), every userland caller that
-queries `kern.hv_vmm_present` now receives `ENOENT`. `/usr/libexec/
-watchdogd` initialises a private "am I a VM?" cache from that sysctl
-during startup:
-
- adrp x0, <page>
- add x0, x0, #<off> ; "kern.hv_vmm_present"
- sub x1, x29, #4 ; &oldval
- mov x2, sp ; &oldlen
- mov x3, #0
- mov x4, #0
- bl _sysctlbyname ; auth stub
- cbnz w0, <skip> ; on ENOENT: w0 != 0 -> jump past the store
- ldur w8, [x29, #-4]
- cmp w8, #0
- cset w8, ne ; w8 = (oldval != 0) ? 1 : 0
- adrp x9, <page>
- strb w8, [x9, #<off>] ; cached byte
-
-A downstream accessor returns that cached byte; a `cbz w0, ...` at
-`+0x58e0` reads it; on `cbz`-taken it falls into a call to a
-`_os_crash` wrapper that does `brk #1`. Because the cstring rename
-makes the sysctl return `ENOENT`, the `cbnz w0, <skip>` path is taken,
-the store is skipped, the cached byte stays at its BSS-zero default
-(0), the downstream `cbz` takes the trap branch, and launchd's
-`_PanicOnCrash` knob escalates the resulting SIGTRAP to a kernel
-panic.
-
-Patch
------
-Two-instruction surgical edit at the originating site. We do NOT touch
-the cstring (the kernel rename approach deliberately keeps every
-`kern.hv_vmm_present` consumer queriying the now-ENOENT name, except
-where we specifically opt them out). What we change instead is the
-caching logic so that, regardless of the sysctl result, the cached
-byte ends up at 1:
-
- cbnz w0, <skip> -> nop (don't skip the store)
- cset wN, ne -> mov wN, #1 (store 1, not oldval-truthiness)
-
-Net effect: the strb writes 1 into the cached "am I a VM?" byte every
-time, the downstream accessor returns 1, the `cbz w0, ...` at +0x58e0
-falls through to the clean-exit branch that logs "detected virtual
-machine environment and no watchdog KEXT found, exiting...". No trap,
-no panic.
-
-Anchoring
----------
-We anchor on the canonical shape rather than file offsets. For each
-`adrp/add` xref in `__TEXT,__text` that resolves to the file VA of
-the `"kern.hv_vmm_present\0"` cstring, we require:
-
- 1. A `bl <stub>` within the next 20 instructions of the `add`.
- 2. The instruction immediately after that `bl` is `cbnz w0, <imm>`.
- 3. Within 8 instructions after the `cbnz` there is a `cset wN, <cond>`
- (capstone alias for `csinc wN, wzr, wzr, !cond`).
- 4. Within 8 instructions after the `cset` there is a `strb wM,
- [xR, #imm]` (the store into the cached-byte global).
-
-Watchdogd contains two functions that match this shape (verified
-empirically on `iPhone17,3_26.1_23B85`). Both are "cache the VM
-presence" routines; one feeds the accessor at `+0x8cdc` (the path
-that leads to the trap), the other feeds a separate consumer at a
-different global. Both want the same answer (cached byte = 1), so we
-patch every match the anchor finds. Idempotent: after patching, the
-matcher no longer finds a `cbnz w0` at the expected slot, so a
-re-run reports "already patched" and exits cleanly.
-
-Code signing
-------------
-A byte edit inside `__TEXT,__text` invalidates the SHA-256 slot hash
-of the containing 4 KiB page in the binary's own `CS_CodeDirectory`.
-On `codeSigningMonitor == 2` hardware (iPhone17,3 / iOS 26.1), TXM
-rejects the page on demand-page-in unless the slot hash matches the
-on-disk page bytes. After the in-place byte patch we recompute and
-write the slot hash via `cfw_macho_codesign.reattest_modified_offsets`.
-
-The resulting CD mutation also changes the binary's cdHash, which
-would normally cause AMFI to reject the image at execve. The existing
-JB kernel patch `patch_amfi_cdhash_in_trustcache` short-circuits that
-trust-cache check unconditionally — same property the DSC reattest
-already relies on.
-
-We do NOT re-sign with `ldid`. Re-signing would default the code-signing
-identifier to the local filename, which trips launchd's boot-task
-identity check (the same failure mode we observed on mobile_obliterator
-before the previous attempt was reverted).
-"""
-
-import struct
-import sys
-
-from .cfw_asm import (
- NOP,
- _cs,
- _log_asm,
- asm,
- find_section,
- 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
-
-
-NEEDLE = b"kern.hv_vmm_present\x00"
-PATTERN_NAME = "watchdogd hv_vmm_present sysctl cache"
-
-# Scan windows (in instructions, not bytes).
-SCAN_ADRP_TO_ADD = 8 # ADRP and its paired ADD may be up to 8 insns apart
-SCAN_ADD_TO_BL = 20 # from the cstring-loading ADD forward to the bl _sysctlbyname
-SCAN_BL_TO_CSET = 12 # from cbnz forward to the cset
-SCAN_CSET_TO_STRB = 8 # from cset forward to the strb
-
-
-def _find_cstring_va(data, sections):
- """Locate "kern.hv_vmm_present\0" in any cstring-like section.
-
- Returns (va, file_offset, section_name) or None.
- """
- for sec_name, (vma, size, foff) in sections.items():
- _, _, sect = sec_name.partition(",")
- if sect not in ("__cstring", "__objc_methname", "__objc_classname"):
- continue
- buf = bytes(data[foff : foff + size])
- i = 0
- while True:
- p = buf.find(NEEDLE, i)
- if p < 0:
- break
- # Must be at a cstring boundary (preceded by NUL or start of section).
- if p == 0 or buf[p - 1] == 0:
- return (vma + p, foff + p, sec_name)
- i = p + 1
- return None
-
-
-def _find_adrp_add_xrefs(code, base_va, target_va):
- """Yield the (adrp_va, add_va) of every ADRP+ADD pair that resolves to
- target_va.
-
- Tracks recent ADRP results per destination register; pairs them with
- a subsequent ADD where the ADD's first source reg matches the ADRP's
- destination and the ADRP and ADD are within `SCAN_ADRP_TO_ADD`
- instructions of each other.
- """
- target_page = target_va & ~0xFFF
- target_pageoff = target_va & 0xFFF
-
- adrp_cache = {} # dst_reg -> (adrp_va, page_value, idx)
-
- insns = list(_cs.disasm(code, base_va))
-
- for idx, ins in enumerate(insns):
- if ins.mnemonic == "adrp" and len(ins.operands) >= 2:
- dst = ins.operands[0].reg
- page = ins.operands[1].imm
- adrp_cache[dst] = (ins.address, page, idx)
-
- elif ins.mnemonic == "add" and len(ins.operands) >= 3:
- src = ins.operands[1].reg
- imm_op = ins.operands[2]
- if imm_op.type != ARM64_OP_IMM:
- continue
- if src not in adrp_cache:
- continue
- adrp_va, page, adrp_idx = adrp_cache[src]
- if idx - adrp_idx > SCAN_ADRP_TO_ADD:
- continue
- if page == target_page and imm_op.imm == target_pageoff:
- yield (adrp_va, ins.address)
-
-
-def _next_branch(insns, start_idx, mnemonics, max_scan):
- """Return (idx, insn) of the first insn at or after start_idx whose
- mnemonic is in `mnemonics`, within `max_scan` instructions. None if
- not found.
- """
- end = min(len(insns), start_idx + max_scan)
- for i in range(start_idx, end):
- if insns[i].mnemonic in mnemonics:
- return i, insns[i]
- return None
-
-
-def _operand_reg_name(insn, op_index):
- """Return the lowercase register name of the op_index-th operand of
- insn (e.g. 'w8', 'x9'), or None.
- """
- if len(insn.operands) <= op_index:
- return None
- op = insn.operands[op_index]
- name = insn.reg_name(op.reg)
- return name.lower() if name else None
-
-
-def _scan_pattern_from_add(insns, add_idx):
- """From the ADD that completes a cstring xref, scan forward for the
- canonical shape:
-
- add x0, ... ; insns[add_idx]
- ... (arg setup, up to SCAN_ADD_TO_BL insns) ...
- bl <stub>
- cbnz w0, <skip> ; MUST be at bl_idx+1
- ... (up to SCAN_BL_TO_CSET) ...
- cset wN, <cond>
- ... (up to SCAN_CSET_TO_STRB) ...
- strb wM, [xR, #imm]
-
- Returns a dict with the file-relative VAs and the cset destination
- register name on success, or None on miss.
- """
- bl = _next_branch(insns, add_idx + 1, ("bl",), SCAN_ADD_TO_BL)
- if bl is None:
- return None
- bl_idx, bl_insn = bl
-
- if bl_idx + 1 >= len(insns):
- return None
- cbnz_insn = insns[bl_idx + 1]
- if cbnz_insn.mnemonic != "cbnz":
- return None
- # First operand of cbnz must be w0 — sysctlbyname's return value.
- if _operand_reg_name(cbnz_insn, 0) != "w0":
- return None
-
- cset = _next_branch(insns, bl_idx + 2, ("cset",), SCAN_BL_TO_CSET)
- if cset is None:
- return None
- cset_idx, cset_insn = cset
- cset_reg = _operand_reg_name(cset_insn, 0)
- if cset_reg is None or not cset_reg.startswith("w"):
- return None
-
- strb = _next_branch(insns, cset_idx + 1, ("strb",), SCAN_CSET_TO_STRB)
- if strb is None:
- return None
- _strb_idx, strb_insn = strb
-
- return {
- "bl_va": bl_insn.address,
- "cbnz_va": cbnz_insn.address,
- "cset_va": cset_insn.address,
- "cset_reg": cset_reg,
- "strb_va": strb_insn.address,
- }
-
-
-def _va_to_foff(text_va, text_foff, va):
- return text_foff + (va - text_va)
-
-
-def _already_patched_at(data, cbnz_foff, cset_foff):
- """Return True iff the cbnz slot is already a NOP and the cset slot
- is already a `mov wN, #1` (any wN). Used for idempotence.
- """
- cbnz_word = struct.unpack_from("<I", data, cbnz_foff)[0]
- if cbnz_word != struct.unpack("<I", NOP)[0]:
- return False
-
- cset_word = struct.unpack_from("<I", data, cset_foff)[0]
- # arm64 `mov wN, #1` encodes as MOVZ wN, #1, lsl #0
- # 31:23 = 0b010100101 (MOVZ-W, hw=0)
- # 22:21 = 00
- # 20:5 = imm16 (=1)
- # 4:0 = Rd
- # → top 16 bits = 0x5280, imm = 0x0001, low 5 = N
- high = cset_word >> 16
- mid = (cset_word >> 5) & 0xFFFF
- if high == 0x5280 and mid == 0x0001:
- return True
- return False
-
-
-def patch_watchdogd(filepath, *, dry_run=False):
- """Apply the surgical patch to a watchdogd Mach-O.
-
- Returns the number of sites patched (>=1 on success, 0 if the
- binary was already patched). Raises on a malformed binary or on
- failure to find any matching site (the binary isn't what we
- expect).
- """
- with open(filepath, "rb") as f:
- data = bytearray(f.read())
-
- sections = parse_macho_sections(data)
- text_sec = find_section(sections, "__TEXT,__text")
- if text_sec is None:
- raise ValueError(f"{filepath}: no __TEXT,__text section")
- text_va, text_size, text_foff = text_sec
-
- cstring_hit = _find_cstring_va(data, sections)
- if cstring_hit is None:
- raise ValueError(
- f"{filepath}: '{NEEDLE.rstrip(chr(0).encode()).decode()}' cstring "
- f"not present"
- )
- cstring_va, cstring_foff, cstring_sec = cstring_hit
- print(
- f" cstring at va:0x{cstring_va:X} (foff:0x{cstring_foff:X}, "
- f"sect={cstring_sec})"
- )
-
- code = bytes(data[text_foff : text_foff + text_size])
- insns = list(_cs.disasm(code, text_va))
- add_va_to_idx = {ins.address: i for i, ins in enumerate(insns) if ins.mnemonic == "add"}
-
- matches = []
- already_patched = []
- for adrp_va, add_va in _find_adrp_add_xrefs(code, text_va, cstring_va):
- add_idx = add_va_to_idx.get(add_va)
- if add_idx is None:
- continue
- m = _scan_pattern_from_add(insns, add_idx)
- if m is None:
- # Check whether this xref looks like an already-patched site.
- # Heuristic: look for the strb forward; if found, check the
- # canonical-slot offsets relative to the bl for the patched
- # form.
- continue
- m["adrp_va"] = adrp_va
- m["add_va"] = add_va
- m["cbnz_foff"] = _va_to_foff(text_va, text_foff, m["cbnz_va"])
- m["cset_foff"] = _va_to_foff(text_va, text_foff, m["cset_va"])
- matches.append(m)
-
- # Also detect an already-patched form by walking xrefs that DID find
- # the bl + strb but where the cbnz slot is now a NOP.
- # We do this as a second pass over the xrefs.
- for adrp_va, add_va in _find_adrp_add_xrefs(code, text_va, cstring_va):
- add_idx = add_va_to_idx.get(add_va)
- if add_idx is None:
- continue
- bl = _next_branch(insns, add_idx + 1, ("bl",), SCAN_ADD_TO_BL)
- if bl is None:
- continue
- bl_idx, bl_insn = bl
- if bl_idx + 1 >= len(insns):
- continue
- slot_after_bl = insns[bl_idx + 1]
- if slot_after_bl.mnemonic != "nop":
- continue
- # Try to find a strb after the bl so we know this is the same
- # function shape.
- strb = _next_branch(insns, bl_idx + 1, ("strb",), SCAN_BL_TO_CSET + SCAN_CSET_TO_STRB)
- if strb is None:
- continue
- # Find a candidate mov wN, #1 between the nop and the strb.
- mov_idx = None
- for j in range(bl_idx + 2, strb[0]):
- if insns[j].mnemonic == "mov" and _operand_reg_name(insns[j], 0) is not None:
- # Check it's a mov wN, #1.
- imm = insns[j].operands[1].imm if len(insns[j].operands) > 1 else -1
- if imm == 1:
- mov_idx = j
- break
- if mov_idx is None:
- continue
- already_patched.append({
- "add_va": add_va,
- "cbnz_va": slot_after_bl.address,
- "cset_va": insns[mov_idx].address,
- })
-
- if not matches and already_patched:
- print(
- f" [.] {filepath}: all {len(already_patched)} matching site(s) "
- f"already patched — nothing to do"
- )
- return 0
-
- if not matches:
- raise ValueError(
- f"{filepath}: no '{PATTERN_NAME}' site found. Expected an "
- f"adrp+add xref to the cstring followed by bl/cbnz w0/cset/strb."
- )
-
- 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"]
- cset_foff = m["cset_foff"]
-
- if _already_patched_at(data, cbnz_foff, cset_foff):
- print(
- f" [.] site @ add 0x{m['add_va']:X}: already in patched "
- f"form (cbnz=nop, cset=mov #1) — skipping"
- )
- continue
-
- new_cset = asm(f"mov {m['cset_reg']}, #1")
- if len(new_cset) != 4:
- raise RuntimeError(
- f"asm('mov {m['cset_reg']}, #1') returned {len(new_cset)} bytes"
- )
-
- ctx_start = max(text_foff, cbnz_foff - 8)
- print(
- f" site @ add 0x{m['add_va']:X} "
- f"(bl 0x{m['bl_va']:X}, cbnz 0x{m['cbnz_va']:X}, "
- f"cset {m['cset_reg']} 0x{m['cset_va']:X}, strb 0x{m['strb_va']:X})"
- )
- print(f" Before:")
- _log_asm(data, ctx_start, 8, cbnz_foff)
-
- old_cbnz = bytes(data[cbnz_foff : cbnz_foff + 4])
- old_cset = bytes(data[cset_foff : cset_foff + 4])
-
- data[cbnz_foff : cbnz_foff + 4] = NOP
- data[cset_foff : cset_foff + 4] = new_cset
-
- print(
- f" Patched: cbnz->{NOP.hex()} (was {old_cbnz.hex()}), "
- f"cset->{new_cset.hex()} (was {old_cset.hex()})"
- )
- print(f" After:")
- _log_asm(data, ctx_start, 8, cbnz_foff)
-
- 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:
- print(f" [.] {filepath}: nothing applied")
- return 0
-
- # Write the patched bytes to disk BEFORE re-attest, because the
- # re-attest helper opens the file from disk to compute SHA-256 of
- # the modified page.
- 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)")
-
- # Re-attest the modified page(s).
- diagnostics = reattest_modified_offsets(
- filepath, touched_offsets, dry_run=dry_run, verbose=True
- )
- print(
- f" [+] {filepath}: re-attest updated {len(diagnostics)} slot(s) "
- f"across {len(set((d['cd_off'], d['page_index']) for d in diagnostics))} "
- f"unique (CD, page) pair(s)"
- )
-
- return n_applied
diff --git a/scripts/patchers/cfw_patch_xpc_lwcr.py b/scripts/patchers/cfw_patch_xpc_lwcr.py
deleted file mode 100644
index d417d959..00000000
--- a/scripts/patchers/cfw_patch_xpc_lwcr.py
+++ /dev/null
@@ -1,229 +0,0 @@
-"""Patch libxpc so the Lightweight Code Requirement (LWCR) self-check can't
-abort on our JB.
-
-iOS 27 introduced XPC "lightweight code requirements": a server pins a code
-requirement on its listener (via `xpc_connection_set_peer_lightweight_code_
-requirement`, or the Swift `XPCPeerRequirement.hasEntitlement(_:)` wrapper),
-and libxpc evaluates whether a token satisfies it in `_xpc_token_satisfies_
-lwcr`. That function calls an internal matcher which returns two things — a
-`matched` bool and a `match_result.error_code` — and then hard-asserts they
-agree:
-
- bl <matcher> ; w0 = matched
- ldr wC, [xR] ; wC = match_result.error_code
- cmp wC, #0 ; AICMR_MATCH == 0
- cset wC, ne ; wC = (error_code != 0)
- eor wE, w0, wC ; wE = matched ^ (error_code != 0)
- tbz wE, #0, <abort> ; abort (brk #1) when they disagree
-
-On stock iOS the two always agree. On our JB the matcher's code-signing query
-writes error_code = MATCH(0) but then returns a failure status, yielding the
-forbidden combination (matched=0, error_code=0). libxpc `brk #1`-aborts, so
-every daemon that pins an entitlement peer-requirement at startup
-(intelligencetasksd, searchpartyd, transparencyd, bluetoothd, ...) crash-loops
-— which in turn churns the SpringBoard/backboardd group into resprings.
-
-Fix: make `matched` consistent with `error_code` by construction and drop the
-abort. Derive the return from error_code (the matcher's own verdict) and NOP
-the xor + the conditional branch:
-
- cset wC, ne -> cset w0, eq ; w0 = matched = (error_code == 0)
- eor wE,... -> nop
- tbz wE,#0,.. -> nop ; falls through to the normal return
-
-Real allow/deny is preserved (error_code drives it, exactly as stock does when
-the two agree); only the internally-contradictory case is resolved — toward
-"satisfied" when error_code says MATCH — instead of aborting.
-
-Nothing is hardcoded: `_xpc_token_satisfies_lwcr` is resolved from the DSC's
-own local-symbol table, disassembled with Capstone, and the check located by
-control-flow shape (the `cset wC,ne; eor wE,w0,wC; tbz wE,#0` idiom).
-Replacements come from Keystone. The modified 16 KiB page is re-attested (TXM
-enforces per-page); the CDHash change is accepted by the JB's always-true AMFI
-cdhash-trust patch.
-"""
-
-from capstone.arm64_const import ARM64_OP_REG, ARM64_OP_IMM
-
-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"
-# Mach-O mangles the leading-underscore source name to a double underscore.
-SYMBOL_CANDIDATES = ("__xpc_token_satisfies_lwcr", SYMBOL)
-
-
-def _rn(insn, idx):
- ops = insn.operands
- if idx >= len(ops) or ops[idx].type != ARM64_OP_REG:
- return None
- return insn.reg_name(ops[idx].reg)
-
-
-def _find_consistency_check(insns):
- """Locate the LWCR self-consistency idiom and return the (cset, eor, tbz)
- instructions.
-
- Shape:
- cset wC, ne
- eor wE, w0, wC
- tbz wE, #0, <abort>
- """
- for i in range(len(insns) - 1):
- eor = insns[i]
- if eor.mnemonic != "eor":
- continue
- wE, w0, wC = _rn(eor, 0), _rn(eor, 1), _rn(eor, 2)
- if w0 != "w0" or wE is None or wC is None:
- continue
- tbz = insns[i + 1]
- if tbz.mnemonic != "tbz":
- continue
- if _rn(tbz, 0) != wE:
- continue
- tops = tbz.operands
- if len(tops) < 2 or tops[1].type != ARM64_OP_IMM or tops[1].imm != 0:
- continue
- # Walk back for `cset wC, ne` feeding the eor.
- cset = None
- for j in range(i - 1, max(-1, i - 6), -1):
- cand = insns[j]
- if cand.mnemonic == "cset" and _rn(cand, 0) == wC:
- # capstone renders the condition as an operand imm code;
- # use op_str to confirm it is `ne`.
- if cand.op_str.strip().endswith("ne"):
- cset = cand
- break
- if cset is None:
- continue
- return cset, eor, tbz
- return None
-
-
-def _find_patched_shape(insns):
- """Locate the shape this patch itself leaves behind, so a re-run reports a
- no-op instead of failing.
-
- The per-edit `already patched` check below cannot cover this: it compares
- bytes at addresses that `_find_consistency_check` has to supply first, and
- that search looks for the `eor`/`tbz` the patch has already replaced. On a
- second pass over an installed cache the idiom is gone by construction.
-
- Shape:
- cmp wX, #0 ; error_code == AICMR_MATCH
- cset w0, eq ; the replacement for `cset wC, ne`
- nop ; was eor wE, w0, wC
- nop ; was tbz wE, #0, <abort>
- """
- for i in range(len(insns) - 2):
- cset = insns[i]
- if cset.mnemonic != "cset" or _rn(cset, 0) != "w0":
- continue
- if not cset.op_str.strip().endswith("eq"):
- continue
- if insns[i + 1].mnemonic != "nop" or insns[i + 2].mnemonic != "nop":
- continue
- # The `cmp wX, #0` feeding it keeps this from matching an unrelated
- # `cset w0, eq` that happens to precede padding.
- for j in range(i - 1, max(-1, i - 5), -1):
- cand = insns[j]
- if cand.mnemonic != "cmp":
- continue
- ops = cand.operands
- if len(ops) == 2 and ops[1].type == ARM64_OP_IMM and ops[1].imm == 0:
- return cset
- break
- return None
-
-
-def patch_xpc_lwcr(chunks_dir, *, dry_run=False):
- records.set_group("xpc_lwcr")
- chunks = DSCChunks(chunks_dir)
- print(f" [.] {chunks!r}")
-
- # Self-gating: the LWCR path only exists on iOS 27+ libxpc. On older
- # userlands the symbol is absent, so this is a no-op there.
- fn_vma = None
- resolved_name = None
- for candidate in SYMBOL_CANDIDATES:
- try:
- fn_vma = resolve_local_symbol(chunks_dir, candidate)
- resolved_name = candidate
- break
- except RuntimeError:
- continue
- if fn_vma is None:
- print(f" [=] {SYMBOL} not present (pre-iOS-27 userland); nothing to patch")
- return 0
- print(f" [.] {resolved_name} @ 0x{fn_vma:X}")
-
- insns = _disasm_function(chunks, fn_vma, 160)
- found = _find_consistency_check(insns)
- if found is None:
- already = _find_patched_shape(insns)
- if already is not None:
- print(f" [=] already patched at 0x{already.address:X} "
- f"(cset w0,eq; nop; nop); nothing to patch/re-attest")
- print(f" [+] libxpc LWCR self-check patch complete")
- return 0
- raise ValueError(
- f"{SYMBOL}: LWCR consistency idiom (cset wC,ne; eor wE,w0,wC; "
- f"tbz wE,#0) not found"
- )
- cset, eor, tbz = found
- print(f" [.] cset @ 0x{cset.address:X}: {cset.mnemonic} {cset.op_str}")
- print(f" [.] eor @ 0x{eor.address:X}: {eor.mnemonic} {eor.op_str}")
- print(f" [.] tbz @ 0x{tbz.address:X}: {tbz.mnemonic} {tbz.op_str}")
-
- nop = asm("nop")
- cset_new = asm("cset w0, eq") # w0 = matched = (error_code == 0)
- edits = [
- (cset.address, cset_new, "cset w0, eq"),
- (eor.address, nop, "nop"),
- (tbz.address, nop, "nop"),
- ]
-
- modified = []
- for vma, new_bytes, label in edits:
- cur = chunks.bytes_at_vma(vma, 4)
- if cur == new_bytes:
- print(f" [=] already patched at 0x{vma:X} ({label})")
- continue
- 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)
-
- if not dry_run and modified:
- print(f" [.] re-attesting modified page(s)...")
- reattest_modified_pages(chunks, modified, dry_run=False)
- for vma, new_bytes, _ in edits:
- if chunks.bytes_at_vma(vma, 4) != new_bytes:
- raise RuntimeError(f"post-write verify failed at 0x{vma:X}")
- elif dry_run:
- print(f" [.] dry-run: would re-attest page for {[hex(v) for v in modified]}")
-
- print(f" [+] libxpc LWCR self-check patch complete")
- return 1
-
-
-if __name__ == "__main__":
- import sys
- dry = "--apply" not in sys.argv
- args = [a for a in sys.argv[1:] if not a.startswith("--")]
- d = args[0] if args else "/private/tmp/cryptex27/System/Library/Caches/com.apple.dyld"
- patch_xpc_lwcr(d, dry_run=dry)
diff --git a/scripts/patchers/cfw_records.py b/scripts/patchers/cfw_records.py
deleted file mode 100644
index 2a9bbcf6..00000000
--- a/scripts/patchers/cfw_records.py
+++ /dev/null
@@ -1,1230 +0,0 @@
-"""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/scripts/setup_machine.sh b/scripts/setup_machine.sh
index 6f8d2080..3929f00e 100755
--- a/scripts/setup_machine.sh
+++ b/scripts/setup_machine.sh
@@ -473,7 +473,7 @@ install_brew_deps() {
require_cmd brew
local deps=(
- wget gnu-tar openssl@3 ldid-procursus sshpass keystone git-lfs
+ wget gnu-tar openssl@3 ldid-procursus sshpass git-lfs
[email protected] libusb ipsw
)
@@ -717,8 +717,8 @@ main() {
run_make "Project setup" build
fi
- # Activate venv so all child scripts (cfw_install, patchers, etc.) use the
- # project Python with capstone/keystone/pyimg4 installed, not the bare system python3.
+ # The venv serves exactly one program now: scripts/pymobiledevice3_bridge.py,
+ # the restore backend. The patch pipeline is Swift and never reads it.
export PATH="$PROJECT_ROOT/.venv/bin:$PATH"
run_make "Firmware prep" vm_new
diff --git a/scripts/setup_tools.sh b/scripts/setup_tools.sh
index 4b657c59..142d9c42 100755
--- a/scripts/setup_tools.sh
+++ b/scripts/setup_tools.sh
@@ -1,9 +1,9 @@
#!/bin/zsh
# setup_tools.sh — Install all required host tools for vphone-cli
#
-# Installs brew packages, builds trustcache from source,
-# builds insert_dylib from submodule source, and creates Python venv
-# (including pymobiledevice3 restore/usbmux tooling).
+# Installs brew packages, builds trustcache from source, builds insert_dylib
+# from submodule source (a test reference — see step [3/4]), and creates the
+# Python venv for the pymobiledevice3 restore bridge.
#
# Run: make setup_tools
@@ -27,7 +27,12 @@ ensure_repo_submodule() {
echo "[1/4] Checking brew packages..."
-BREW_PACKAGES=(aria2 gnu-tar openssl@3 ldid-procursus sshpass zstd cmake)
+# cmake and keystone are deliberately absent: both existed only so pip could
+# build keystone-engine's native library for the Python firmware patchers, and
+# those are Swift now (FirmwarePatcher's ARM64Encoder replaces keystone's asm(),
+# vendor/libcapstone-spm replaces the capstone wheel). openssl@3 stays — the
+# trustcache build below links it.
+BREW_PACKAGES=(aria2 gnu-tar openssl@3 ldid-procursus sshpass zstd)
BREW_MISSING=()
for pkg in "${BREW_PACKAGES[@]}"; do
@@ -72,9 +77,16 @@ else
echo " Installed: $TRUSTCACHE_BIN"
fi
-# ── insert_dylib ───────────────────────────────────────────────
-
-echo "[3/4] insert_dylib"
+# ── insert_dylib (test reference only) ─────────────────────────
+#
+# Nothing in the product runs this any more: `CFWInjectDylib` injects the weak
+# load command in-process, and the last caller that shelled out was
+# scripts/patchers/cfw.py. It is still built because it is the independent
+# reference CFWMachOTests.matchesInsertDylib compares the Swift injector
+# against, byte for byte — that test skips silently when it is missing, which
+# is the worst possible way to lose the check.
+
+echo "[3/4] insert_dylib (byte-parity reference for CFWMachOTests)"
INSERT_DYLIB_BIN="$TOOLS_PREFIX/bin/insert_dylib"
if [[ -x "$INSERT_DYLIB_BIN" ]]; then
diff --git a/scripts/setup_venv.sh b/scripts/setup_venv.sh
index 96fcf569..a5b381f2 100755
--- a/scripts/setup_venv.sh
+++ b/scripts/setup_venv.sh
@@ -1,8 +1,8 @@
#!/bin/zsh
# setup_venv.sh — Create a self-contained Python venv at project root.
#
-# Installs all dependencies including the keystone native library.
-# Requires: python3, clang, Homebrew keystone (brew install keystone)
+# Creates the venv for scripts/pymobiledevice3_bridge.py, the restore backend.
+# Requires: python3.
#
# Usage:
# make setup_venv
@@ -35,48 +35,11 @@ source "${VENV_DIR}/bin/activate"
pip install --upgrade pip >/dev/null
pip install -r "${REQUIREMENTS}"
-# --- Build keystone native library ---
-# The keystone-engine pip package is Python bindings only.
-# It needs libkeystone.dylib at runtime. Homebrew ships only the static .a,
-# so we build a dylib from it and place it inside the venv.
-echo ""
-echo "=== Building keystone dylib ==="
-KEYSTONE_DIR="/opt/homebrew/Cellar/keystone"
-if [[ ! -d "${KEYSTONE_DIR}" ]]; then
- echo "Error: keystone not found. Install with: brew install keystone"
- exit 1
-fi
-KEYSTONE_STATIC="$(find "${KEYSTONE_DIR}" -name 'libkeystone.a' -type f 2>/dev/null | head -1)"
-if [[ -z "${KEYSTONE_STATIC}" ]]; then
- echo "Error: libkeystone.a not found. Install with: brew install keystone"
- exit 1
-fi
-
-PYVER="$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
-KS_PKG_DIR="${VENV_DIR}/lib/python${PYVER}/site-packages/keystone"
-KS_DYLIB="${KS_PKG_DIR}/libkeystone.dylib"
-
-echo " static lib: ${KEYSTONE_STATIC}"
-echo " dylib dest: ${KS_DYLIB}"
-
-clang -shared -o "${KS_DYLIB}" \
- -Wl,-all_load "${KEYSTONE_STATIC}" \
- -lc++ \
- -install_name @rpath/libkeystone.dylib
-
-echo " dylib built OK"
-
# --- Verify ---
echo ""
echo "=== Verifying imports ==="
python3 -c "
-from capstone import Cs, CS_ARCH_ARM64, CS_MODE_LITTLE_ENDIAN
-from keystone import Ks, KS_ARCH_ARM64, KS_MODE_LITTLE_ENDIAN
-from pyimg4 import IM4P
import pymobiledevice3
-print(' capstone OK')
-print(' keystone OK')
-print(' pyimg4 OK')
print(' pmd3 OK')
"
diff --git a/scripts/setup_venv_linux.sh b/scripts/setup_venv_linux.sh
index 7129dd5c..ec164bfe 100644
--- a/scripts/setup_venv_linux.sh
+++ b/scripts/setup_venv_linux.sh
@@ -1,8 +1,6 @@
#!/bin/bash
# setup_venv_linux.sh — Create Python venv on Linux (Debian/Ubuntu).
#
-# On Linux, keystone-engine pip package ships prebuilt .so — no manual build needed.
-#
# Usage:
# bash scripts/setup_venv_linux.sh
#
@@ -16,9 +14,9 @@ REQUIREMENTS="${PROJECT_ROOT}/requirements.txt"
echo "=== Installing system deps ==="
if command -v apt-get &>/dev/null; then
apt-get update -qq
- apt-get install -y -qq python3 python3-venv python3-pip cmake gcc g++ pkg-config 2>/dev/null
+ apt-get install -y -qq python3 python3-venv python3-pip gcc g++ pkg-config 2>/dev/null
elif command -v dnf &>/dev/null; then
- dnf install -y python3 python3-pip cmake gcc gcc-c++ 2>/dev/null
+ dnf install -y python3 python3-pip gcc gcc-c++ 2>/dev/null
fi
PYTHON="$(command -v python3)"
@@ -44,12 +42,8 @@ pip install -r "${REQUIREMENTS}"
echo ""
echo "=== Verifying imports ==="
python3 -c "
-from capstone import Cs, CS_ARCH_ARM64, CS_MODE_LITTLE_ENDIAN
-from keystone import Ks, KS_ARCH_ARM64, KS_MODE_LITTLE_ENDIAN
-from pyimg4 import IM4P
-print(' capstone OK')
-print(' keystone OK')
-print(' pyimg4 OK')
+import pymobiledevice3
+print(' pmd3 OK')
"
echo ""
diff --git a/sources/FirmwarePatcher/Binary/MachOParser.swift b/sources/FirmwarePatcher/Binary/MachOParser.swift
index 6de21e4c..13b01c70 100644
--- a/sources/FirmwarePatcher/Binary/MachOParser.swift
+++ b/sources/FirmwarePatcher/Binary/MachOParser.swift
@@ -26,6 +26,42 @@ public struct MachOSectionInfo: Sendable {
/// Mach-O parsing utilities for kernel/firmware binary analysis.
public enum MachOParser {
+ /// `sizeof(segment_command_64)` — the fixed part, before the section table.
+ static let segmentCommand64Size = 72
+ /// `sizeof(section_64)`.
+ static let section64Size = 80
+ /// `sizeof(symtab_command)`.
+ static let symtabCommandSize = 24
+
+ /// Walk the load-command table, handing `body` only those commands whose
+ /// whole body lies inside the buffer.
+ ///
+ /// The bound matters: `Data.loadLE` is a `precondition`, so a read past the
+ /// end kills the process with SIGTRAP rather than raising anything a caller
+ /// could catch. A header claiming more (or larger) commands than the file
+ /// holds — a truncated download, a half-written patch — used to walk right
+ /// off the end. Now the walk stops at the first command that does not fit,
+ /// and the caller sees an empty/partial result it can reject normally.
+ static func forEachLoadCommand(
+ in data: Data,
+ _ body: (_ cmd: UInt32, _ offset: Int, _ cmdsize: Int) -> Void
+ ) {
+ guard data.count > 32 else { return }
+ let ncmds = data.loadLE(UInt32.self, at: 16)
+ var offset = 32 // sizeof(mach_header_64)
+
+ for _ in 0 ..< ncmds {
+ guard offset + 8 <= data.count else { return }
+ let cmd = data.loadLE(UInt32.self, at: offset)
+ let cmdsize = Int(data.loadLE(UInt32.self, at: offset + 4))
+ // A command smaller than its own header, or one running past EOF,
+ // means the table cannot be trusted — stop rather than guess.
+ guard cmdsize >= 8, offset + cmdsize <= data.count else { return }
+ body(cmd, offset, cmdsize)
+ offset += cmdsize
+ }
+ }
+
/// Parse all segments from a Mach-O binary in a Data buffer.
public static func parseSegments(from data: Data) -> [MachOSegmentInfo] {
var segments: [MachOSegmentInfo] = []
@@ -34,32 +70,23 @@ public enum MachOParser {
let magic = data.loadLE(UInt32.self, at: 0)
guard magic == 0xFEED_FACF else { return segments } // MH_MAGIC_64
- let ncmds = data.loadLE(UInt32.self, at: 16)
- var offset = 32 // sizeof(mach_header_64)
-
- for _ in 0 ..< ncmds {
- guard offset + 8 <= data.count else { break }
- let cmd = data.loadLE(UInt32.self, at: offset)
- let cmdsize = data.loadLE(UInt32.self, at: offset + 4)
-
- if cmd == 0x19 { // LC_SEGMENT_64
- let nameData = data[offset + 8 ..< offset + 24]
- let name = String(data: nameData, encoding: .utf8)?
- .trimmingCharacters(in: CharacterSet(charactersIn: "\0")) ?? ""
- let vmAddr = data.loadLE(UInt64.self, at: offset + 24)
- let vmSize = data.loadLE(UInt64.self, at: offset + 32)
- let fileOff = data.loadLE(UInt64.self, at: offset + 40)
- let fileSize = data.loadLE(UInt64.self, at: offset + 48)
-
- segments.append(MachOSegmentInfo(
- name: name,
- vmAddr: vmAddr,
- vmSize: vmSize,
- fileOffset: fileOff,
- fileSize: fileSize
- ))
- }
- offset += Int(cmdsize)
+ forEachLoadCommand(in: data) { cmd, offset, cmdsize in
+ guard cmd == 0x19, cmdsize >= segmentCommand64Size else { return } // LC_SEGMENT_64
+ let nameData = data[offset + 8 ..< offset + 24]
+ let name = String(data: nameData, encoding: .utf8)?
+ .trimmingCharacters(in: CharacterSet(charactersIn: "\0")) ?? ""
+ let vmAddr = data.loadLE(UInt64.self, at: offset + 24)
+ let vmSize = data.loadLE(UInt64.self, at: offset + 32)
+ let fileOff = data.loadLE(UInt64.self, at: offset + 40)
+ let fileSize = data.loadLE(UInt64.self, at: offset + 48)
+
+ segments.append(MachOSegmentInfo(
+ name: name,
+ vmAddr: vmAddr,
+ vmSize: vmSize,
+ fileOffset: fileOff,
+ fileSize: fileSize
+ ))
}
return segments
}
@@ -73,42 +100,35 @@ public enum MachOParser {
let magic = data.loadLE(UInt32.self, at: 0)
guard magic == 0xFEED_FACF else { return sections }
- let ncmds = data.loadLE(UInt32.self, at: 16)
- var offset = 32
-
- for _ in 0 ..< ncmds {
- guard offset + 8 <= data.count else { break }
- let cmd = data.loadLE(UInt32.self, at: offset)
- let cmdsize = data.loadLE(UInt32.self, at: offset + 4)
-
- if cmd == 0x19 { // LC_SEGMENT_64
- let segNameData = data[offset + 8 ..< offset + 24]
- let segName = String(data: segNameData, encoding: .utf8)?
+ forEachLoadCommand(in: data) { cmd, offset, cmdsize in
+ guard cmd == 0x19, cmdsize >= segmentCommand64Size else { return } // LC_SEGMENT_64
+ let segNameData = data[offset + 8 ..< offset + 24]
+ let segName = String(data: segNameData, encoding: .utf8)?
+ .trimmingCharacters(in: CharacterSet(charactersIn: "\0")) ?? ""
+ let nsects = data.loadLE(UInt32.self, at: offset + 64)
+
+ var sectOff = offset + segmentCommand64Size
+ for _ in 0 ..< nsects {
+ // The section table lives inside this command, so bound it by
+ // the command as well as by the file.
+ guard sectOff + section64Size <= offset + cmdsize else { break }
+ let sectNameData = data[sectOff ..< sectOff + 16]
+ let sectName = String(data: sectNameData, encoding: .utf8)?
.trimmingCharacters(in: CharacterSet(charactersIn: "\0")) ?? ""
- let nsects = data.loadLE(UInt32.self, at: offset + 64)
-
- var sectOff = offset + 72 // sizeof(segment_command_64) header
- for _ in 0 ..< nsects {
- guard sectOff + 80 <= data.count else { break }
- let sectNameData = data[sectOff ..< sectOff + 16]
- let sectName = String(data: sectNameData, encoding: .utf8)?
- .trimmingCharacters(in: CharacterSet(charactersIn: "\0")) ?? ""
- let addr = data.loadLE(UInt64.self, at: sectOff + 32)
- let size = data.loadLE(UInt64.self, at: sectOff + 40)
- let fileOff = data.loadLE(UInt32.self, at: sectOff + 48)
-
- let key = "\(segName),\(sectName)"
- sections[key] = MachOSectionInfo(
- segmentName: segName,
- sectionName: sectName,
- address: addr,
- size: size,
- fileOffset: fileOff
- )
- sectOff += 80
- }
+ let addr = data.loadLE(UInt64.self, at: sectOff + 32)
+ let size = data.loadLE(UInt64.self, at: sectOff + 40)
+ let fileOff = data.loadLE(UInt32.self, at: sectOff + 48)
+
+ let key = "\(segName),\(sectName)"
+ sections[key] = MachOSectionInfo(
+ segmentName: segName,
+ sectionName: sectName,
+ address: addr,
+ size: size,
+ fileOffset: fileOff
+ )
+ sectOff += section64Size
}
- offset += Int(cmdsize)
}
return sections
}
@@ -128,24 +148,17 @@ public enum MachOParser {
public static func parseSymtab(from data: Data) -> (symoff: Int, nsyms: Int, stroff: Int, strsize: Int)? {
guard data.count > 32 else { return nil }
- let ncmds = data.loadLE(UInt32.self, at: 16)
- var offset = 32
-
- for _ in 0 ..< ncmds {
- guard offset + 8 <= data.count else { break }
- let cmd = data.loadLE(UInt32.self, at: offset)
- let cmdsize = data.loadLE(UInt32.self, at: offset + 4)
-
- if cmd == 0x02 { // LC_SYMTAB
- let symoff = data.loadLE(UInt32.self, at: offset + 8)
- let nsyms = data.loadLE(UInt32.self, at: offset + 12)
- let stroff = data.loadLE(UInt32.self, at: offset + 16)
- let strsize = data.loadLE(UInt32.self, at: offset + 20)
- return (Int(symoff), Int(nsyms), Int(stroff), Int(strsize))
- }
- offset += Int(cmdsize)
+ var result: (symoff: Int, nsyms: Int, stroff: Int, strsize: Int)?
+ forEachLoadCommand(in: data) { cmd, offset, cmdsize in
+ guard result == nil else { return } // first LC_SYMTAB wins, as before
+ guard cmd == 0x02, cmdsize >= symtabCommandSize else { return } // LC_SYMTAB
+ let symoff = data.loadLE(UInt32.self, at: offset + 8)
+ let nsyms = data.loadLE(UInt32.self, at: offset + 12)
+ let stroff = data.loadLE(UInt32.self, at: offset + 16)
+ let strsize = data.loadLE(UInt32.self, at: offset + 20)
+ result = (Int(symoff), Int(nsyms), Int(stroff), Int(strsize))
}
- return nil
+ return result
}
/// Find a symbol containing the given name fragment. Returns its virtual address.
diff --git a/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swift b/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swift
index 3144f0d5..eac50ba0 100644
--- a/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swift
+++ b/sources/FirmwarePatcher/CFW/Patches/CFWJetsam.swift
@@ -51,7 +51,7 @@
// is a live bug in the reference: rewriting the gate drops it out of the
// conditional-branch set, so the Python's backward scan walks past it and
// patches the *next* branch into the same return block — a second, wrong site
-// on a binary that was already correct (`scripts/patchers/README_reference_capture.md`,
+// on a binary that was already correct (`research/patch_reference_capture.md`,
// "The non-idempotency itself is a separate, pre-existing bug"). The fix has to
// live inside the scan, because on a re-run neither implementation picks the
// site it patched before. So the scan collects unconditional `b`s into a return
diff --git a/sources/VPhoneCore/VPhoneResources.swift b/sources/VPhoneCore/VPhoneResources.swift
index 57dfa991..cd217110 100644
--- a/sources/VPhoneCore/VPhoneResources.swift
+++ b/sources/VPhoneCore/VPhoneResources.swift
@@ -80,13 +80,11 @@ public struct VPhoneResources: Sendable {
// MARK: - Assets
public var scriptsDir: URL { base.appendingPathComponent("scripts") }
- public var patchersDir: URL { scriptsDir.appendingPathComponent("patchers") }
public var resourceArchivesDir: URL { scriptsDir.appendingPathComponent("resources") }
public var fwPrepareScript: URL { scriptsDir.appendingPathComponent("fw_prepare.sh") }
public var cfwInstallHostScript: URL { scriptsDir.appendingPathComponent("cfw_install_host.sh") }
public var preflightScript: URL { scriptsDir.appendingPathComponent("boot_host_preflight.sh") }
public var pmd3Bridge: URL { scriptsDir.appendingPathComponent("pymobiledevice3_bridge.py") }
- public var cfwPy: URL { patchersDir.appendingPathComponent("cfw.py") }
public var signcert: URL { scriptsDir.appendingPathComponent("vphoned/signcert.p12") }
public var vphoned: URL {
@@ -117,8 +115,14 @@ public struct VPhoneResources: Sendable {
/// Runtime pip deps, mirrored from requirements.txt (fallback when the
/// bundled requirements.txt is somehow absent).
+ ///
+ /// One consumer is left: `scripts/pymobiledevice3_bridge.py`, the restore
+ /// path. The firmware patchers that needed capstone, keystone-engine and
+ /// pyimg4 are Swift now (`FirmwarePatcher`), so those three are gone. pyimg4
+ /// still ends up installed — `pymobiledevice3` and `ipsw-parser` both
+ /// require it — but nothing here asks for it directly any more.
static let fallbackRequirements =
- ["typer", "capstone", "keystone-engine", "pyimg4", "pymobiledevice3>=9.5.0", "ipsw-parser"]
+ ["typer", "pymobiledevice3>=9.5.0", "ipsw-parser", "setuptools"]
/// Bundled/dev requirements list the managed venv is provisioned from.
public var requirementsFile: URL { base.appendingPathComponent("requirements.txt") }
@@ -134,97 +138,42 @@ public struct VPhoneResources: Sendable {
}
private var managedVenvPython: URL { managedVenvDir.appendingPathComponent("bin/python3") }
- /// A python is usable only if it carries an `ipsw_parser` new enough for the
- /// bridge — the exact gap behind `IPSW has no attribute 'create_from_path'`
- /// when an old system-python build gets picked up.
+ /// A python is usable only if it can actually run the restore bridge.
+ ///
+ /// Two halves, and both are needed. `ipsw_parser` must be new enough —
+ /// that is the gap behind `IPSW has no attribute 'create_from_path'` when
+ /// an old system-python build gets picked up. And `pymobiledevice3` must be
+ /// importable, which `ipsw_parser` does **not** imply: `pip show
+ /// ipsw-parser` lists coloredlogs, construct, plumbum, pyimg4, remotezip2,
+ /// requests and typer, and no pymobiledevice3. A venv holding only
+ /// `ipsw-parser` passes an `ipsw_parser`-only probe and then dies on
+ /// `ModuleNotFoundError: No module named 'pymobiledevice3'` at the bridge's
+ /// line 11 — an import traceback instead of "this environment is wrong".
func pythonIsUsable(_ python: URL) -> Bool {
guard FileManager.default.isExecutableFile(atPath: python.path) else { return false }
- let probe = "from ipsw_parser.ipsw import IPSW; import sys; "
+ let probe = "from ipsw_parser.ipsw import IPSW; import pymobiledevice3; import sys; "
+ "sys.exit(0 if hasattr(IPSW, 'create_from_path') else 1)"
return (try? VPhoneProcessRunner.runCapturing(python, ["-c", probe]))?.succeeded == true
}
- /// Must assemble, not just import — a bindings-only install imports fine
- /// and then fails inside `fw patch`.
- func keystoneIsUsable(_ python: URL) -> Bool {
- let probe = "from keystone import Ks, KS_ARCH_ARM64, KS_MODE_LITTLE_ENDIAN; import sys; "
- + "sys.exit(0 if bytes(Ks(KS_ARCH_ARM64, KS_MODE_LITTLE_ENDIAN).asm('nop')[0]) else 1)"
- return (try? VPhoneProcessRunner.runCapturing(python, ["-c", probe]))?.succeeded == true
- }
-
- func venvIsUsable(_ python: URL) -> Bool {
- pythonIsUsable(python) && keystoneIsUsable(python)
- }
-
- // MARK: - keystone native library
-
- /// Older bottles ship only the static archive.
- private func homebrewKeystoneLibs() -> (dylib: URL?, archive: URL?) {
- for prefix in ["/opt/homebrew/opt/keystone/lib", "/usr/local/opt/keystone/lib"] {
- let dir = URL(fileURLWithPath: prefix)
- guard let names = try? FileManager.default.contentsOfDirectory(atPath: dir.path) else { continue }
- let dylib = names.first { $0.hasPrefix("libkeystone") && $0.hasSuffix(".dylib") }
- let archive = names.first { $0 == "libkeystone.a" }
- if dylib != nil || archive != nil {
- return (dylib.map(dir.appendingPathComponent), archive.map(dir.appendingPathComponent))
- }
- }
- return (nil, nil)
- }
-
- /// Asked of the interpreter: `import keystone` is what's broken here.
- private func keystonePackageDir(_ python: URL) -> URL? {
- let probe = "import sysconfig; print(sysconfig.get_paths()['purelib'])"
- guard let r = try? VPhoneProcessRunner.runCapturing(python, ["-c", probe]), r.succeeded else { return nil }
- let purelib = r.stdout.trimmingCharacters(in: .whitespacesAndNewlines)
- guard !purelib.isEmpty else { return nil }
- return URL(fileURLWithPath: purelib).appendingPathComponent("keystone")
- }
-
- /// PyPI has no arm64 macOS wheel and the sdist ignores its build's exit
- /// status, so a failed native build still installs bindings alone and pip
- /// reports success. Same recovery as scripts/setup_venv.sh.
- func repairKeystone(_ python: URL) -> Bool {
- guard let pkgDir = keystonePackageDir(python),
- FileManager.default.fileExists(atPath: pkgDir.path) else { return false }
- let dest = pkgDir.appendingPathComponent("libkeystone.dylib")
- let libs = homebrewKeystoneLibs()
-
- if let dylib = libs.dylib {
- try? FileManager.default.removeItem(at: dest)
- guard (try? FileManager.default.copyItem(at: dylib, to: dest)) != nil else { return false }
- try? FileManager.default.setAttributes([.posixPermissions: 0o755], ofItemAtPath: dest.path)
- } else if let archive = libs.archive {
- let r = try? VPhoneProcessRunner.runCapturing(
- URL(fileURLWithPath: "/usr/bin/clang"),
- ["-shared", "-o", dest.path, "-Wl,-all_load", archive.path,
- "-lc++", "-install_name", "@rpath/libkeystone.dylib"])
- guard r?.succeeded == true else { return false }
- } else {
- return false
- }
-
- guard keystoneIsUsable(python) else { return false }
- FileHandle.standardError.write(Data("[+] Repaired keystone native library: \(dest.path)\n".utf8))
- return true
- }
-
/// Resolve a python with working deps: an explicit `VPHONE_PYTHON`, the dev
/// repo `.venv`, the managed per-user venv, else provision the managed venv
/// on this machine. Never silently falls back to a stale system python.
+ ///
+ /// `pythonIsUsable` is the whole health check now. It used to be paired
+ /// with a keystone probe and an in-place repair of keystone's native
+ /// library, because a `fw patch` ran Python patchers; those are Swift
+ /// (`FirmwarePatcher`), and the only thing left needing an interpreter is
+ /// the pymobiledevice3 restore bridge — which is exactly what the probe
+ /// covers.
public func pythonExecutable() throws -> URL {
if let override = ProcessInfo.processInfo.environment["VPHONE_PYTHON"], !override.isEmpty {
let u = URL(fileURLWithPath: override)
if pythonIsUsable(u) { return u }
}
let devVenv = base.appendingPathComponent(".venv/bin/python3")
- if venvIsUsable(devVenv) { return devVenv }
- // Repair in place before rebuilding — a missing dylib is not worth a
- // full re-install.
- if pythonIsUsable(managedVenvPython),
- keystoneIsUsable(managedVenvPython) || repairKeystone(managedVenvPython) {
- return managedVenvPython
- }
+ if pythonIsUsable(devVenv) { return devVenv }
+ if pythonIsUsable(managedVenvPython) { return managedVenvPython }
return try bootstrapManagedVenv()
}
@@ -263,11 +212,6 @@ public struct VPhoneResources: Sendable {
guard pythonIsUsable(py) else {
lastError = "The Python environment built with \(host.path) is missing a required package"; continue
}
- guard keystoneIsUsable(py) || repairKeystone(py) else {
- lastError = "Could not set up keystone in the Python environment built with \(host.path). "
- + "Install it with 'brew install keystone', or install cmake so it can be built"
- continue
- }
log("[+] Python environment ready: \(py.path)")
return py
}
diff --git a/sources/vphone-cli/VPhoneCFWDSCVerbsCLI.swift b/sources/vphone-cli/VPhoneCFWDSCVerbsCLI.swift
new file mode 100644
index 00000000..491e3aed
--- /dev/null
+++ b/sources/vphone-cli/VPhoneCFWDSCVerbsCLI.swift
@@ -0,0 +1,437 @@
+// VPhoneCFWDSCVerbsCLI.swift — `cfw` verbs for the dyld-shared-cache patchers.
+//
+// Each command here is a thin face over a type in `FirmwarePatcher/DSC/Patchers/`,
+// and each one answers to the same verb name, the same positional arguments and
+// the same flags as the `scripts/patchers/cfw.py` subcommand it replaces
+// (`cfw.py:356-432`). That is not a stylistic choice: `scripts/cfw_install*.sh`,
+// `cfw-kit/lib/base_stages.sh` and `scripts/patch_{camera,hv_vmm}_userland.sh`
+// invoke these by hand-written argv, so the argv is the contract.
+//
+// Nothing here parses the patchers' output, so the bar for stdout is that an
+// install log still reads like the Python's — which is why every command passes
+// `log: stdout` rather than letting the library default to stderr, and prints
+// nothing of its own on top. The library already emits the Python's lines,
+// including the trailing "… complete".
+//
+// Exit codes follow the Python exactly: every one of these verbs exits 0 on a
+// no-op as well as on a patch (a self-gating patcher that finds a pre-iOS-27
+// userland has done its job), and non-zero only when the patcher throws.
+
+import ArgumentParser
+import FirmwarePatcher
+import Foundation
+
+enum VPhoneCFWDSCVerbs {
+ /// Registered into `vphone-cli cfw` by `VPhoneCFWCommand`.
+ static let all: [ParsableCommand.Type] = [
+ VPhoneCFWPatchHVVMMDSCCommand.self,
+ VPhoneCFWPatchIOMFBSwapEndCommand.self,
+ VPhoneCFWPatchIOMFBForceKernCommand.self,
+ VPhoneCFWPatchDSCMaxSlideCommand.self,
+ VPhoneCFWPatchLSDEmbeddedRegCommand.self,
+ VPhoneCFWPatchXPCLWCRCommand.self,
+ VPhoneCFWPatchLockdownModeCommand.self,
+ VPhoneCFWPatchCameraDSCCommand.self,
+ ]
+
+ /// Where the patchers' progress lines go.
+ ///
+ /// The DSC library defaults some patchers to stderr and some to stdout; the
+ /// Python put all of it on stdout, and an install log is read as one stream,
+ /// so all eight verbs are pinned here.
+ static let stdout: @Sendable (String) -> Void = { print($0) }
+
+ /// `int(value, 0)`, which is how `cfw.py` reads `--target-size 0x560`.
+ ///
+ /// Base is taken from the prefix, so `0x560`, `0o2540`, `0b10101100000` and
+ /// `1376` are the same number and a bare `0560` is decimal — Python's rule,
+ /// not C's. Underscores are accepted as digit separators, as Python accepts
+ /// them.
+ static func parseCInteger(_ value: String) throws -> UInt32 {
+ let cleaned = value.replacingOccurrences(of: "_", with: "")
+ let (radix, digits): (Int, Substring) = switch cleaned.prefix(2).lowercased() {
+ case "0x": (16, cleaned.dropFirst(2))
+ case "0o": (8, cleaned.dropFirst(2))
+ case "0b": (2, cleaned.dropFirst(2))
+ default: (10, cleaned[...])
+ }
+ guard !digits.isEmpty, let parsed = UInt32(digits, radix: radix) else {
+ throw ValidationError("not an integer: '\(value)'")
+ }
+ return parsed
+ }
+}
+
+// MARK: - patch-hv-vmm-dsc
+
+struct VPhoneCFWPatchHVVMMDSCCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-hv-vmm-dsc",
+ abstract: "Mangle the \"kern.hv_vmm_present\" sysctl name in the userland dyld cache",
+ discussion: """
+ The EXP variant's userland half of the hv_vmm rename: every cstring
+ occurrence of the sysctl name inside an executable mapping is rewritten,
+ so the identity, store and consumer-service dylibs that ask "am I in a
+ VM?" get ENOENT and read as a real device.
+
+ It is a blacklist, not a list: a site is patched unless the dylib that
+ contains it is one of the paravirt consumers that must keep seeing the
+ truth — the graphics passthrough and compute/accel fast paths, which
+ break if they think they are on bare metal. A site whose containing
+ dylib cannot be named is left alone rather than guessed at.
+
+ Every page written is re-attested against the cache's code-signature
+ slots, and so is every page found already mangled: a cache whose bytes
+ and slot hashes disagree is one the guest page-faults on. A re-run is
+ therefore a no-op that still repairs attestation.
+
+ Runs while the SystemOS cryptex is mounted on the host, wrapped by
+ `scripts/patch_hv_vmm_userland.sh dsc`.
+ """
+ )
+
+ @Argument(
+ help: "The guest's /System/Library/Caches/com.apple.dyld directory",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var chunksDirectory: URL
+
+ @Flag(name: .customLong("dry-run"), help: "Report every site and write nothing")
+ var dryRun = false
+
+ func run() throws {
+ try DSCHVVMMPatcher.patch(
+ chunksDirectory: chunksDirectory,
+ dryRun: dryRun,
+ log: VPhoneCFWDSCVerbs.stdout
+ )
+ }
+}
+
+// MARK: - patch-iomfb-swapend
+
+struct VPhoneCFWPatchIOMFBSwapEndCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-iomfb-swapend",
+ abstract: "Shrink IOMobileFramebuffer's _kern_SwapEnd payload to what the base userclient accepts",
+ discussion: """
+ iOS 26.0/26.0.1 and 18.x ship a `_kern_SwapEnd` that hands the
+ userclient a larger input-state struct than the vphone600 base kernel's
+ `checkStructureInputSize` will take, so every present is refused and the
+ VZ view stays black. This rewrites the size register in the
+ `io_connect_method` set-up — one `mov w3, #imm` — and re-attests the page.
+
+ The site is found by shape, not offset: the selector move, then the size
+ move, then the two zeroed argument registers, then the call. A userland
+ whose SwapEnd no longer has that shape is an error, not a silent skip.
+
+ --target-size takes the size the base kernel accepts, in any base
+ `int(x, 0)` reads (the installers pass 0x560). Default is 0x588, the
+ 26.4 base's. iOS 27 is not patched this way at all — see
+ `patch-iomfb-force-kern`.
+
+ Already-correct is a no-op that still re-attests, so re-running over a
+ patched cache is safe.
+ """
+ )
+
+ @Argument(
+ help: "The guest's /System/Library/Caches/com.apple.dyld directory",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var chunksDirectory: URL
+
+ @Option(
+ name: .customLong("target-size"),
+ help: "Payload size the base kernel's userclient accepts (hex or decimal)",
+ transform: VPhoneCFWDSCVerbs.parseCInteger
+ )
+ var targetSize: UInt32 = DSCIOMFBSwapEndPatcher.defaultTargetSize
+
+ @Flag(name: .customLong("dry-run"), help: "Report the site and the rewrite, and write nothing")
+ var dryRun = false
+
+ func run() throws {
+ try DSCIOMFBSwapEndPatcher.patch(
+ chunksDirectory: chunksDirectory,
+ targetSize: targetSize,
+ dryRun: dryRun,
+ log: VPhoneCFWDSCVerbs.stdout
+ )
+ }
+}
+
+// MARK: - patch-iomfb-force-kern
+
+struct VPhoneCFWPatchIOMFBForceKernCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-iomfb-force-kern",
+ abstract: "Retarget IOMobileFramebuffer's public Swap* trampolines onto their _kern_Swap* siblings",
+ discussion: """
+ iOS 27's IOMobileFramebuffer defaults present onto the `_virt_*`
+ callback path, which the 26.4 paravirt GPU never receives — so the host
+ scans out nothing and the VZ view stays black. Each public
+ `_IOMobileFramebufferSwap*` entry point is a thin dispatch trampoline;
+ this retargets its branch at the `_kern_Swap*` sibling, which is the
+ userclient method-5 path the paravirt GPU does scan out.
+
+ Only a function that still looks like a thin trampoline is retargeted.
+ One that does not is left on the virt path and reported, and a cache
+ missing a required entry point is refused before anything is written —
+ so a half-forced IOMFB is not a state this can leave behind.
+
+ `_kern_Swap*` are stripped local symbols, so the cache's `.symbols`
+ side file has to be present; without it there would be zero pairs to
+ find, which would read as "this userland has none".
+
+ Pairs with the KernelJBPatchIomfbSwap kernel patches, which make the
+ userclient accept 27's native 0x6e0 SwapEnd struct. Modified pages are
+ re-attested; an already-forced cache is a no-op.
+ """
+ )
+
+ @Argument(
+ help: "The guest's /System/Library/Caches/com.apple.dyld directory",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var chunksDirectory: URL
+
+ @Flag(name: .customLong("dry-run"), help: "Report every entry point and write nothing")
+ var dryRun = false
+
+ func run() throws {
+ try DSCIOMFBForceKernPatcher.patch(
+ chunksDirectory: chunksDirectory,
+ dryRun: dryRun,
+ log: VPhoneCFWDSCVerbs.stdout
+ )
+ }
+}
+
+// MARK: - patch-dsc-maxslide
+
+struct VPhoneCFWPatchDSCMaxSlideCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-dsc-maxslide",
+ abstract: "Zero dyld_cache_header.maxSlide when the cache would overflow the kernel's shared region",
+ discussion: """
+ The vphone600 26.x kernel reserves a fixed 6 GiB shared region and
+ charges it the cache's mapped span plus the header's maxSlide. iOS 27's
+ userland cache (~5.95 GiB) plus 512 MiB of slide does not fit, so
+ `_shared_region_map_and_slide` returns ENOMEM, dyld cannot map libSystem
+ and launchd — pid 1 — takes the kernel down with it. Zeroing maxSlide
+ lets the cache map at slide 0, which fits.
+
+ Self-gating on the cache's real span, so a 26.x or 18.x base that fits
+ with full slide is left alone and a cache already at maxSlide 0 is left
+ alone either way. Both are reported and exit 0.
+
+ --force zeroes maxSlide even when the cache fits — the opt-in behind
+ FORCE_DSC_MAXSLIDE=1 for a non-27 base.
+
+ No re-attestation: maxSlide lives in the cache header, which is not one
+ of the cs_validate'd code pages.
+ """
+ )
+
+ @Argument(
+ help: "The guest's /System/Library/Caches/com.apple.dyld directory",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var chunksDirectory: URL
+
+ @Flag(name: .customLong("dry-run"), help: "Decide and report, and write nothing")
+ var dryRun = false
+
+ @Flag(name: .customLong("force"), help: "Zero maxSlide even when the cache already fits")
+ var force = false
+
+ func run() throws {
+ try DSCMaxSlidePatcher.patch(
+ chunksDirectory: chunksDirectory,
+ dryRun: dryRun,
+ force: force
+ )
+ }
+}
+
+// MARK: - patch-lsd-embedded-reg
+
+struct VPhoneCFWPatchLSDEmbeddedRegCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-lsd-embedded-reg",
+ abstract: "Open lsd's embedded-registration path so JB app installs can register",
+ discussion: """
+ On iOS 27, `-[_LSDModifyClient
+ clientIsEntitledForEmbeddedRegistrationOperations]` demands three
+ privileged entitlements from its XPC peer, which nothing we install has,
+ and uicache's own registration call is a stub. That leaves an app
+ installed and unregistered — no icon, no launch. NOPing the gate makes
+ the method fall through to success, which is what unblocks
+ vphoned/TrollStore/uicache installs.
+
+ One instruction, found by the method's control-flow shape rather than by
+ offset, and the page is re-attested afterwards.
+
+ Self-gating: a pre-iOS-27 userland has no such method, which is reported
+ and exits 0. A userland that has the method but not the shape is an
+ error — a LaunchServices rewrite has to stop the install rather than be
+ guessed at, because the silent alternative boots a guest in which no app
+ can register.
+ """
+ )
+
+ @Argument(
+ help: "The guest's /System/Library/Caches/com.apple.dyld directory",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var chunksDirectory: URL
+
+ @Flag(name: .customLong("dry-run"), help: "Report the gate and write nothing")
+ var dryRun = false
+
+ func run() throws {
+ try DSCLSDEmbeddedRegPatcher.patch(
+ chunksDirectory: chunksDirectory,
+ dryRun: dryRun,
+ log: VPhoneCFWDSCVerbs.stdout
+ )
+ }
+}
+
+// MARK: - patch-xpc-lwcr
+
+struct VPhoneCFWPatchXPCLWCRCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-xpc-lwcr",
+ abstract: "Stop libxpc's Lightweight Code Requirement self-check from brk-aborting",
+ discussion: """
+ Under our code-signing environment, iOS 27's LWCR matcher hands
+ `_xpc_token_satisfies_lwcr` the contradictory pair (matched = 0,
+ error_code = MATCH). The consistency assertion takes that as
+ memory corruption and traps, which crash-loops every daemon that pins an
+ entitlement peer-requirement on its peer — intelligencetasksd,
+ searchpartyd, transparencyd, bluetoothd and the rest.
+
+ Three words: `matched` is derived from `error_code` instead of being
+ cross-checked against it, and the abort is dropped. The pages are
+ re-attested.
+
+ Self-gating: the symbol is absent on pre-iOS-27 libxpc, which is
+ reported and exits 0, and a cache already carrying the patched shape is
+ a no-op. A cache with the symbol but neither shape is an error.
+ """
+ )
+
+ @Argument(
+ help: "The guest's /System/Library/Caches/com.apple.dyld directory",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var chunksDirectory: URL
+
+ @Flag(name: .customLong("dry-run"), help: "Report the three sites and write nothing")
+ var dryRun = false
+
+ func run() throws {
+ try DSCXPCLWCRPatcher.apply(
+ directory: chunksDirectory,
+ dryRun: dryRun,
+ log: VPhoneCFWDSCVerbs.stdout
+ )
+ }
+}
+
+// MARK: - patch-lockdown-mode
+
+struct VPhoneCFWPatchLockdownModeCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-lockdown-mode",
+ abstract: "Stop os_lockdown_mode_enabled() aborting when the Lockdown Mode sysctl is missing",
+ discussion: """
+ iOS 27's libSystem treats a failed read of
+ `security.mac.lockdown_mode_state_public` as unrecoverable and aborts.
+ The vphone600 26.x kernel does not implement that MAC sysctl, launchd is
+ the first caller, and pid 1 aborting is a kernel panic before the guest
+ ever reaches a login screen.
+
+ NOPing the error branch lets the query fall through with 0 — Lockdown
+ Mode off, which is the truth here — and boot continues. The page is
+ re-attested.
+
+ Self-gating: pre-iOS-27 userlands have no such symbol, which is reported
+ and exits 0, and a cache already patched is a no-op.
+ """
+ )
+
+ @Argument(
+ help: "The guest's /System/Library/Caches/com.apple.dyld directory",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var chunksDirectory: URL
+
+ @Flag(name: .customLong("dry-run"), help: "Report the gate and write nothing")
+ var dryRun = false
+
+ func run() throws {
+ try DSCLockdownModePatcher.patch(
+ chunksDirectory: chunksDirectory,
+ dryRun: dryRun,
+ log: VPhoneCFWDSCVerbs.stdout
+ )
+ }
+}
+
+// MARK: - patch-camera-dsc
+
+struct VPhoneCFWPatchCameraDSCCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-camera-dsc",
+ abstract: "Stub the AVFoundation init-time validation that crashes Camera.app on a VM",
+ discussion: """
+ The host-side virtual camera synthesises a single `vphone-cam`
+ AVCaptureDevice through cameracaptured's device-list, discovery-session
+ and serializer paths. AVFoundation's init-time validation does not
+ survive a device assembled that way, so Camera.app dies on launch. This
+ short-circuits the entry points that do that validation to a constant
+ return, which is what makes the app launch-survivable.
+
+ <dsc_header> is the unsuffixed `dyld_shared_cache_arm64e` file — the one
+ the symbols resolve against, not a chunk. The Python takes it as a
+ separate argument because `ipsw dyld symaddr` wants a file; it is passed
+ through for the same reason.
+
+ --force accepts an entry point whose prologue is neither the expected
+ `pacibsp` nor the replacement already in place, which is otherwise
+ refused rather than overwritten blind. Modified pages are re-attested;
+ an already-patched cache is a no-op.
+ """
+ )
+
+ @Argument(
+ help: "The guest's /System/Library/Caches/com.apple.dyld directory",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var chunksDirectory: URL
+
+ @Argument(
+ help: "The dyld_shared_cache_arm64e file symbols resolve against (not a chunk)",
+ transform: URL.init(fileURLWithPath:)
+ )
+ var dscHeader: URL
+
+ @Flag(name: .customLong("dry-run"), help: "Report every site and write nothing")
+ var dryRun = false
+
+ @Flag(name: .customLong("force"), help: "Patch an entry point whose prologue is not the expected one")
+ var force = false
+
+ func run() throws {
+ try DSCCameraPatcher.applyAll(
+ chunksDirectory: chunksDirectory,
+ symbolCacheURL: dscHeader,
+ dryRun: dryRun,
+ force: force,
+ log: VPhoneCFWDSCVerbs.stdout
+ )
+ }
+}
diff --git a/sources/vphone-cli/VPhoneCFWMachOVerbsCLI.swift b/sources/vphone-cli/VPhoneCFWMachOVerbsCLI.swift
new file mode 100644
index 00000000..4d611d57
--- /dev/null
+++ b/sources/vphone-cli/VPhoneCFWMachOVerbsCLI.swift
@@ -0,0 +1,313 @@
+// VPhoneCFWMachOVerbsCLI.swift — `cfw` verbs for the standalone Mach-O patchers.
+//
+// Six faces over `FirmwarePatcher/CFW/Patches/`, replacing
+// `"$PYTHON3" scripts/patchers/cfw.py <verb> <binary>` in `cfw_install*.sh`,
+// `cfw-kit/` and `scripts/patch_hv_vmm_userland.sh`. The verb names, their
+// positional arguments and their flags are exactly the Python's — `cfw.py`
+// gives only `patch-watchdogd` a `--dry-run`, so only that one has one here.
+//
+// RE-ATTESTATION. Each library type decides for itself whether to recompute the
+// CodeDirectory slot hash of the page it dirties, and the settings below are
+// chosen so the bytes these verbs write equal the bytes the Python writes:
+//
+// * seputil and mobileactivationd re-attest by default, which the Python does
+// not do — `reattest: false` / `resign: false` restores parity.
+// * launchd_cache_loader, launchd (jetsam) and diskimagesiod default to off,
+// matching their Python. Passed explicitly anyway, so the choice is visible
+// at the call site rather than inherited from a default that could move.
+// * watchdogd has no switch, and needs none: `cfw_patch_watchdogd.py` calls
+// `cfw_macho_codesign.reattest_modified_offsets` itself, so both sides
+// re-attest and both write the same file.
+//
+// Nothing is lost by turning it off: every shipped caller runs `ldid_sign` over
+// the binary on the next line, which rebuilds the signature whole.
+//
+// STDOUT. Each library type already prints its own progress, so — as with
+// `patch-build-version` and friends in VPhoneCFWPatchCLI.swift — these commands
+// print nothing of their own. The Python writes every line to stdout, so the
+// log closure is `print` even for the two types whose default is stderr.
+//
+// IDEMPOTENCE. The Swift recognises its own output and reports "already
+// patched" without writing; several of the Pythons do not (seputil's anchor
+// string is gone after the first run, the cache-loader gate is no longer a
+// conditional branch) and exit 1 on a second run. That difference is
+// deliberate and documented in each library type's header — a re-run over an
+// already-installed volume is a normal thing for `cfw install` to do.
+
+import ArgumentParser
+import FirmwarePatcher
+import Foundation
+
+/// Where these verbs send patcher progress: stdout, like the Python.
+private let machOVerbLog: @Sendable (String) -> Void = { print($0) }
+
+// MARK: - Truncation guard
+
+/// Refuse a file whose Mach-O header promises more than the file holds.
+///
+/// This used to be load-bearing: `MachOParser` walked the load-command table
+/// checking only that each command's 8-byte header fit, and `Data.loadLE` is a
+/// `precondition`, so a header claiming a 2312-byte table in a 64-byte file
+/// killed the process with SIGTRAP and exit 133 rather than raising. The parser
+/// bounds every command now (`MachOParser.forEachLoadCommand`), so the trap is
+/// gone either way and this is kept for the message: "truncated Mach-O — the
+/// header claims 23 load command(s) in 2312 bytes, and the file is 64 bytes"
+/// names the problem, where the library can only say it found no segments.
+///
+/// Deliberately narrow: it only looks at a native 64-bit Mach-O header and only
+/// asks whether the load commands fit. Anything else — text, a fat header, a
+/// 32-bit image — passes straight through, and the library's own
+/// "not a 64-bit Mach-O" message is what the caller sees. Nothing the library
+/// accepts today is rejected here.
+private func requireUntruncatedMachO(at url: URL) throws {
+ guard let handle = try? FileHandle(forReadingFrom: url) else { return }
+ defer { try? handle.close() }
+ guard let header = try? handle.read(upToCount: 32), header.count == 32 else { return }
+
+ let magic = header.withUnsafeBytes { $0.loadUnaligned(fromByteOffset: 0, as: UInt32.self) }
+ guard UInt32(littleEndian: magic) == 0xFEED_FACF else { return }
+
+ let size = (try? FileManager.default.attributesOfItem(atPath: url.path)[.size] as? Int) ?? nil
+ guard let fileSize = size else { return }
+
+ let numberOfCommands = Int(UInt32(littleEndian: header.withUnsafeBytes {
+ $0.loadUnaligned(fromByteOffset: 16, as: UInt32.self)
+ }))
+ let sizeOfCommands = Int(UInt32(littleEndian: header.withUnsafeBytes {
+ $0.loadUnaligned(fromByteOffset: 20, as: UInt32.self)
+ }))
+
+ // A load command is 8 bytes at its smallest (cmd + cmdsize), so a header
+ // claiming more commands than that much room is lying about one of the two.
+ guard 32 + sizeOfCommands <= fileSize, numberOfCommands * 8 <= sizeOfCommands else {
+ throw PatcherError.invalidFormat(
+ "\(url.lastPathComponent): truncated Mach-O — the header claims "
+ + "\(numberOfCommands) load command(s) in \(sizeOfCommands) bytes, "
+ + "and the file is \(fileSize) bytes"
+ )
+ }
+}
+
+// MARK: - patch-seputil
+
+struct VPhoneCFWPatchSeputilCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-seputil",
+ abstract: "Pin seputil's gigalocker path to /AA.gl instead of the device UUID",
+ discussion: """
+ seputil builds the gigalocker filename from the format string
+ "/%s.gl", filling %s with the device's UUID. Rewriting those two bytes
+ to "AA" makes the path /mnt7/AA.gl on every guest, which is what lets
+ the install ship one pre-made .gl file instead of one per device.
+
+ The literal is found in __TEXT,__cstring and confirmed by an adrp+add
+ pair in __TEXT,__text that computes its address — the Python takes the
+ first substring hit anywhere in the file. Both land on the same byte in
+ this firmware; this one cannot land on a coincidence in the next.
+
+ Idempotent: a binary already reading "/AA.gl" is reported and left
+ alone. The Python exits 1 there, because the string it searches for is
+ no longer in the file.
+ """
+ )
+
+ @Argument(help: "Path to the seputil Mach-O, patched in place", transform: URL.init(fileURLWithPath:))
+ var binary: URL
+
+ func run() throws {
+ try requireUntruncatedMachO(at: binary)
+ // reattest: false — the Python leaves the signature stale and
+ // `cfw_install*.sh` re-signs on the next line. Parity in bytes.
+ try CFWSeputil.patch(fileAt: binary, reattest: false, log: machOVerbLog)
+ }
+}
+
+// MARK: - patch-launchd-cache-loader
+
+struct VPhoneCFWPatchLaunchdCacheLoaderCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-launchd-cache-loader",
+ abstract: "Open the launchd_unsecure_cache gate so a modified launchd.plist loads",
+ discussion: """
+ /usr/libexec/launchd_cache_loader refuses a launch-daemon cache it did
+ not validate unless the boot arg `launchd_unsecure_cache=` is set.
+ NOPping the branch that reads that boot arg takes the guest down the
+ unsecure path unconditionally, which is how the injected daemons get
+ loaded without a boot-args change.
+
+ The branch is reached from the boot-arg string's adrp+add xref, and it
+ is checked to actually consume the call's result and jump forward out
+ of the unsecure path before anything is written. The Python NOPs the
+ first conditional branch after the call, whatever it tests.
+
+ Idempotent: a gate already holding a NOP is reported and left alone.
+ The Python exits 1 there — a NOP is not one of the branches it looks
+ for.
+ """
+ )
+
+ @Argument(help: "Path to the launchd_cache_loader Mach-O, patched in place", transform: URL.init(fileURLWithPath:))
+ var binary: URL
+
+ func run() throws {
+ try requireUntruncatedMachO(at: binary)
+ // Off by default in the library and off in the Python: the caller
+ // re-signs. Spelled out so the parity choice is readable here.
+ try CFWCacheLoaderPatcher.patch(
+ fileAt: binary,
+ reattestsCodeSignature: false,
+ log: machOVerbLog
+ )
+ }
+}
+
+// MARK: - patch-mobileactivationd
+
+struct VPhoneCFWPatchMobileactivationdCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-mobileactivationd",
+ abstract: "Force -[DeviceType should_hactivate] to return YES",
+ discussion: """
+ The guest has no path to Apple's activation service, so activation has
+ to be answered locally. Overwriting the getter's prologue with
+ `mov x0, #1 ; ret` is safe: it returns to the caller's unsigned LR
+ without ever pushing a frame.
+
+ The implementation is resolved twice — through LC_SYMTAB and through
+ the ObjC metadata chain (selector -> selref -> method list -> IMP) —
+ and when both resolve they must agree. The Python takes whichever
+ answers first.
+
+ Idempotent: a getter already reading `mov x0, #1 ; ret` is reported and
+ the file is not rewritten, so even its mtime survives.
+ """
+ )
+
+ @Argument(help: "Path to the mobileactivationd Mach-O, patched in place", transform: URL.init(fileURLWithPath:))
+ var binary: URL
+
+ func run() throws {
+ try requireUntruncatedMachO(at: binary)
+ // resign: false — the Python's bytes, for the `ldid_sign` that follows.
+ try CFWMobileactivationd.patch(fileAt: binary, resign: false, log: machOVerbLog)
+ }
+}
+
+// MARK: - patch-launchd-jetsam
+
+struct VPhoneCFWPatchLaunchdJetsamCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-launchd-jetsam",
+ abstract: "Bypass the jetsam panic guard in /sbin/launchd",
+ discussion: """
+ launchd panics when its jetsam configuration does not add up, which a
+ JB guest's rearranged daemon set reliably triggers. The conditional
+ branch that guards the panic is rewritten to an unconditional `b` to
+ the same target, so the function always takes its return path.
+
+ The site is reached from the panic string's adrp+add xref, walking back
+ to the conditional branch whose target is the enclosing function's
+ return block.
+
+ Idempotent: an unconditional branch into the return block already
+ sitting ahead of every conditional one means a previous run did the
+ work, and nothing is written. Neither implementation would otherwise
+ pick the same site twice.
+ """
+ )
+
+ @Argument(help: "Path to the /sbin/launchd Mach-O, patched in place", transform: URL.init(fileURLWithPath:))
+ var binary: URL
+
+ func run() throws {
+ try requireUntruncatedMachO(at: binary)
+ // Off in the library and off in the Python: cfw_install_{dev,jb,exp}.sh
+ // and cfw-kit/jb/install.sh all run ldid over the result.
+ try CFWJetsamPatcher.patch(fileAt: binary, reattest: false, log: machOVerbLog)
+ }
+}
+
+// MARK: - patch-watchdogd
+
+struct VPhoneCFWPatchWatchdogdCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-watchdogd",
+ abstract: "Stop watchdogd caching kern.hv_vmm_present as true",
+ discussion: """
+ watchdogd reads `kern.hv_vmm_present` through sysctlbyname and caches
+ the answer in a __DATA global. On the EXP variant the kernel already
+ lies about that sysctl, but watchdogd's cached copy is written from the
+ call's success path, so the NOP here plus a forced `mov wN, #1` leaves
+ the cache reading "not a VM" whatever the call returns.
+
+ Each site is confirmed five ways — the literal, its adrp+add, the
+ `bl _sysctlbyname`, Capstone's decoded condition code on the gate, and
+ a `strb` into a __DATA-segment global — before a byte moves.
+
+ Exits 0 whether it patched or found every site already patched, which
+ is what `scripts/patch_hv_vmm_userland.sh` expects; only an
+ unparseable binary or a missing anchor is fatal. Unlike the other five
+ verbs this one re-attests the pages it dirties, because its Python does
+ too.
+ """
+ )
+
+ @Argument(help: "Path to the watchdogd Mach-O, patched in place", transform: URL.init(fileURLWithPath:))
+ var binary: URL
+
+ @Flag(name: .customLong("dry-run"), help: "Report the sites found and exit without writing")
+ var dryRun = false
+
+ func run() throws {
+ try requireUntruncatedMachO(at: binary)
+ try CFWWatchdogd.patch(at: binary, dryRun: dryRun, log: machOVerbLog)
+ }
+}
+
+// MARK: - patch-diskimagesiod
+
+struct VPhoneCFWPatchDiskimagesiodCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "patch-diskimagesiod",
+ abstract: "Force -[DIDiskArb isMountCompleteWithExpectedCount:diskTracker:] to return YES",
+ discussion: """
+ MobileStorageMounter waits for a disk-arbitration mount count the guest
+ never reaches, and blocks boot until it times out. Returning YES from
+ the completion check lets the mount finish.
+
+ The same two-anchor resolution as patch-mobileactivationd: LC_SYMTAB
+ first, then the ObjC metadata chain, with the prologue overwritten by
+ `mov x0, #1 ; ret`.
+
+ Idempotent: a prologue already reading `mov x0, #1 ; ret` is reported
+ and the file is left byte-for-byte alone.
+ """
+ )
+
+ @Argument(help: "Path to the diskimagesiod Mach-O, patched in place", transform: URL.init(fileURLWithPath:))
+ var binary: URL
+
+ func run() throws {
+ try requireUntruncatedMachO(at: binary)
+ // Off in the library and off in the Python: cfw_install.sh re-signs
+ // with the extracted com.apple.diskimagesiod entitlements right after.
+ try CFWDiskimagesiod.patch(fileAt: binary, reattest: false, log: machOVerbLog)
+ }
+}
+
+// MARK: - Registration
+
+enum VPhoneCFWMachOVerbs {
+ /// Registered into `vphone-cli cfw` by `VPhoneCFWCommand`.
+ ///
+ /// Ordered as `cfw.py`'s dispatch table lists them, so `--help` and the
+ /// Python's usage block read in the same order.
+ static let all: [ParsableCommand.Type] = [
+ VPhoneCFWPatchSeputilCommand.self,
+ VPhoneCFWPatchLaunchdCacheLoaderCommand.self,
+ VPhoneCFWPatchMobileactivationdCommand.self,
+ VPhoneCFWPatchLaunchdJetsamCommand.self,
+ VPhoneCFWPatchWatchdogdCommand.self,
+ VPhoneCFWPatchDiskimagesiodCommand.self,
+ ]
+}
diff --git a/sources/vphone-cli/VPhoneCFWPatchCLI.swift b/sources/vphone-cli/VPhoneCFWPatchCLI.swift
index de6af92f..8399b9a6 100644
--- a/sources/vphone-cli/VPhoneCFWPatchCLI.swift
+++ b/sources/vphone-cli/VPhoneCFWPatchCLI.swift
@@ -1,9 +1,10 @@
// 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
+// replace (`scripts/patchers/cfw.py` and friends) was removed once the
+// installers switched to these verbs — `git show 78cbeea:scripts/patchers` to
+// read it. The bar every command here had 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
diff --git a/sources/vphone-cli/VPhoneCreateOrchestrator.swift b/sources/vphone-cli/VPhoneCreateOrchestrator.swift
index 87fd7213..8ae68866 100644
--- a/sources/vphone-cli/VPhoneCreateOrchestrator.swift
+++ b/sources/vphone-cli/VPhoneCreateOrchestrator.swift
@@ -480,8 +480,10 @@ public struct VPhoneCreateOrchestrator {
try FileManager.default.createDirectory(at: resources.ipswCacheDir, withIntermediateDirectories: true)
try FileManager.default.createDirectory(at: resources.sealVolumeCacheDir, withIntermediateDirectories: true)
try FileManager.default.createDirectory(at: resources.debsCacheDir, withIntermediateDirectories: true)
+ // No VPHONE_PYTHON: the CFW installers and cfw-kit run `vphone-cli cfw
+ // <verb>` now, so nothing under this script reads a python. Asking for
+ // one here would only force a venv bootstrap nobody uses.
var scriptEnv: [String: String] = [
- "VPHONE_PYTHON": try resources.pythonExecutable().path,
"IPSW_DIR": resources.ipswCacheDir.path,
"VPHONE_SEAL_DIR": resources.sealVolumeCacheDir.path,
"VPHONE_DEBS_DIR": resources.debsCacheDir.path,
@@ -509,7 +511,7 @@ public struct VPhoneCreateOrchestrator {
var env = ProcessInfo.processInfo.environment
for (key, value) in scriptEnv { env[key] = value }
for (key, value) in sudoEnvExtras { env[key] = value }
- let envKeys = (["VPHONE_PYTHON", "IPSW_DIR", "VPHONE_SEAL_DIR"] + sudoEnvExtras.keys.sorted())
+ let envKeys = (["IPSW_DIR", "VPHONE_SEAL_DIR"] + sudoEnvExtras.keys.sorted())
.joined(separator: ", ")
trace("spawn /bin/zsh \(args.joined(separator: " ")) (env keys: \(envKeys))", v)
// With an askpass credential sudo is non-interactive → honor verbosity.
diff --git a/sources/vphone-cli/VPhoneRestoreCLI.swift b/sources/vphone-cli/VPhoneRestoreCLI.swift
index eb26582e..7f366473 100644
--- a/sources/vphone-cli/VPhoneRestoreCLI.swift
+++ b/sources/vphone-cli/VPhoneRestoreCLI.swift
@@ -110,7 +110,7 @@ struct VPhoneCFWCommand: ParsableCommand {
VPhoneCFWPatchBuildVersionCommand.self,
VPhoneCFWPatchCampoEntitlementsCommand.self,
VPhoneCFWPatchPostRestoreDTCommand.self,
- ])
+ ] + VPhoneCFWMachOVerbs.all + VPhoneCFWDSCVerbs.all)
}
/// Replaces `tools/apfs_snap_rename.py`, called from `cfw_install_host.sh`
diff --git a/tests/FirmwarePatcherTests/ARM64EncoderTests.swift b/tests/FirmwarePatcherTests/ARM64EncoderTests.swift
index 3494765a..03aa1df2 100644
--- a/tests/FirmwarePatcherTests/ARM64EncoderTests.swift
+++ b/tests/FirmwarePatcherTests/ARM64EncoderTests.swift
@@ -1,16 +1,19 @@
// ARM64EncoderTests.swift — every ARM64Encoder output asserted against keystone.
//
-// The expected words are keystone-engine's, taken from the repo venv:
+// The expected words below are keystone-engine's. They are frozen constants,
+// not a live call: they were taken at repo commit `78cbeea` from the repo venv,
+// one instruction at a time —
//
// .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.
+// keystone is what the Python patchers called, so agreement with it is the
+// migration's correctness bar: a disagreement is a bug in ARM64Encoder. Nothing
+// in this file runs Python, so the bar survived `scripts/patchers/` leaving.
//
// `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.
+// instructions the 19 patchers in scripts/patchers/ assembled at 78cbeea, 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.
@@ -23,7 +26,7 @@ import Testing
/// One encoder output paired with the keystone encoding of the same instruction.
struct ARM64EncodingCase: Sendable, CustomStringConvertible {
- /// The assembly the Python patcher passes to keystone.
+ /// The assembly the Python patcher passed to keystone.
let source: String
/// keystone-engine's encoding of `source` (at `address`, where it matters).
let keystone: UInt32
@@ -48,13 +51,14 @@ private func word(_ data: Data) -> UInt32 {
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.
+ /// Every distinct `asm(...)` / `asm_at(...)` instruction that was in
+ /// scripts/patchers/ at 78cbeea, the last commit that carried it. 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/`.
+ /// `origin` names the patcher and the Python expression, not a line number.
+ /// The set was derived with `grep -rnE '\basm(_at)?\(' scripts/patchers/`;
+ /// that tree is gone, so re-derive from `git show 78cbeea:scripts/patchers`.
static let asmCallSiteCases: [ARM64EncodingCase] = [
// asm("mov w0, #0\nret") — force the camera check to return 0
ARM64EncodingCase(
@@ -366,8 +370,8 @@ struct ARM64EncoderKeystoneParityTests {
)
}
- /// Every `asm(...)` site in the patchers is represented, and each one
- /// disassembles back to the mnemonic the Python source names.
+ /// Every `asm(...)` site the patchers had is represented, and each one
+ /// disassembles back to the mnemonic the Python source named.
@Test(arguments: ARM64EncoderKeystoneParityTests.allCases)
func roundTripsThroughCapstone(_ testCase: ARM64EncodingCase) throws {
let data = try #require(testCase.encoded)
@@ -511,7 +515,8 @@ struct ARM64EncoderRangeTests {
// 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.
+ /// 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),
diff --git a/tests/FirmwarePatcherTests/CFWCacheloaderTests.swift b/tests/FirmwarePatcherTests/CFWCacheloaderTests.swift
index 3e394b22..e62c0a02 100644
--- a/tests/FirmwarePatcherTests/CFWCacheloaderTests.swift
+++ b/tests/FirmwarePatcherTests/CFWCacheloaderTests.swift
@@ -2,10 +2,11 @@
//
// The patch is one instruction in a boot-critical binary, and a wrong one is a
// guest that will not start rather than a failing assertion, so the reference
-// these tests grade against is the Python that has already shipped: `cfw.py
-// patch-launchd-cache-loader`. The centre of the suite runs both
-// implementations over two clones of the *real* iOS 27.0 / 24A435 binary and
-// compares every byte.
+// these tests grade against is the Python that shipped before this port: `cfw.py
+// patch-launchd-cache-loader`. That Python is gone; what it wrote over the
+// *real* iOS 27.0 / 24A435 binary is frozen in ``CacheLoaderGolden`` below, and
+// the centre of the suite is still that comparison — the Swift patcher's output
+// has to hash to what the Python's did.
//
// The binary is required. Point `VPHONE_MACHO_PRISTINE` at a directory of
// unpatched Mach-Os, or leave the default `ipsws/ref_extract/macho_pristine` in
@@ -19,6 +20,7 @@
// under `VPHONE_CACHELOADER_SCRATCH` when the caller names one;
// `VPHONE_CACHELOADER_KEEP=1` leaves them behind for inspection.
+import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
@@ -70,15 +72,12 @@ private enum CacheLoaderFixture {
ProcessInfo.processInfo.environment["VPHONE_CACHELOADER_KEEP"] == "1"
}
- /// The project venv, which is where the reference Python lives.
- static var python: URL? {
- let url = repoRoot.appendingPathComponent(".venv/bin/python3")
- return FileManager.default.fileExists(atPath: url.path) ? url : nil
+ /// SHA-256 as `shasum -a 256` prints it, so a digest asserted here can be
+ /// taken again from a shell over the same file.
+ static func digest(of url: URL) throws -> String {
+ Data(SHA256.hash(data: try Data(contentsOf: url))).hex
}
- static var patchersDirectory: URL { repoRoot.appendingPathComponent("scripts/patchers") }
- static var cfwPy: URL { patchersDirectory.appendingPathComponent("cfw.py") }
-
/// Clone the pristine binary into a file the caller may write to.
///
/// `cp -c` asks for a `clonefile`, which costs no space and no time when the
@@ -120,49 +119,6 @@ private enum CacheLoaderFixture {
}
}
- /// Run the shipped Python patcher over `binary`.
- @discardableResult
- static func runPython(on binary: URL) throws -> Shell.Result {
- let python = try #require(
- self.python,
- "the reference Python is required — run `make setup_venv`"
- )
- return try Shell.run(
- executable: python,
- arguments: [cfwPy.path, "patch-launchd-cache-loader", binary.path],
- currentDirectory: repoRoot
- )
- }
-
- /// Recompute `binary`'s slot hashes with the Python's own re-signer — the
- /// independent reference for the half of this port `codesign -v` grades.
- @discardableResult
- static func runPythonReattest(on binary: URL, offsets: [Int]) throws -> Shell.Result {
- let python = try #require(
- self.python,
- "the reference Python is required — run `make setup_venv`"
- )
- let offsetList = offsets.map(String.init).joined(separator: ",")
- return try Shell.run(
- executable: python,
- arguments: [
- "-c",
- """
- import sys
- sys.path.insert(0, sys.argv[1])
- import cfw_macho_codesign as codesign
- codesign.reattest_modified_offsets(
- sys.argv[2], [int(x) for x in sys.argv[3].split(",")], verbose=False
- )
- """,
- patchersDirectory.path,
- binary.path,
- offsetList,
- ],
- currentDirectory: repoRoot
- )
- }
-
/// `codesign -v`, the second independent reference: it knows nothing about
/// either implementation and recomputes the page hashes itself.
static func codesignVerify(_ binary: URL) throws -> Shell.Result {
@@ -211,6 +167,47 @@ private enum Shell {
}
}
+// MARK: - The frozen reference
+
+/// What `scripts/patchers/` produced on this fixture, recorded before it was
+/// deleted.
+///
+/// Every value below was taken at repo commit `78cbeea`, with
+/// `.venv/bin/python3` driving `scripts/patchers/`, over the real iOS 27.0 /
+/// 24A435 / iPhone17,3 `launchd_cache_loader` whose own digest is ``pristine``.
+private enum CacheLoaderGolden {
+ /// `shasum -a 256 ipsws/ref_extract/macho_pristine/launchd_cache_loader`
+ static let pristine = "ad268f24802e37a60dcbe12e796685dc0124e308487ebbcbb4d46e47176a486d"
+
+ /// `.venv/bin/python3 scripts/patchers/cfw.py patch-launchd-cache-loader <clone>`
+ /// — one `cbz x0, #0xd20` at 0xC7C turned into a `nop`, signature left
+ /// stale. Its stdout ended `[+] NOPped at 0xC7C`.
+ static let patched = "17c5b00c82311dbfc466400ca225d92c1651f4d6697ba79cd8d59ea9309b30c7"
+
+ /// The gate the Python NOPped, from that same stdout line.
+ static let gateFileOffset = 0xC7C
+
+ /// ``patched``, then
+ /// `.venv/bin/python3 -c 'import sys; sys.path.insert(0, "scripts/patchers");
+ /// import cfw_macho_codesign as r;
+ /// r.reattest_modified_offsets(sys.argv[1], [3196], verbose=True)'`
+ /// — which reported `wrote cd_index=0 slot 0 (e4de608f.. -> 86da8821..)`.
+ static let patchedAndReattested =
+ "564e65d4251c83ede94371afbcbe60cb851ec2ce0be99959259cab415a27e5a9"
+
+ /// `cfw.py patch-launchd-cache-loader` run a SECOND time over ``patched``.
+ ///
+ /// Not what the Python should have done — what it did. It walked past its
+ /// own NOP and took the next conditional branch, printing
+ /// `[+] NOPped at 0xC84`, so the file moved again. This port stops instead,
+ /// and that divergence is deliberate; the digest keeps it visible.
+ static let patchedTwice = "e86fa5261259a9e0023539bac676b7027c4756ff2f9a74aa34c749999609868e"
+
+ /// The four bytes the Python's second run changed, from a byte diff of
+ /// ``patchedTwice`` against ``patched``.
+ static let secondRunOffsets = [0xC84, 0xC85, 0xC86, 0xC87]
+}
+
// MARK: - Byte comparison
private enum ByteComparison {
@@ -328,7 +325,7 @@ struct CFWCacheLoaderGateTests {
}
}
-// MARK: - Parity against the Python
+// MARK: - Parity against the frozen reference
@Suite(
"launchd_cache_loader parity",
@@ -336,25 +333,39 @@ struct CFWCacheLoaderGateTests {
.serialized
)
struct CFWCacheLoaderParityTests {
- @Test("Swift and Python produce byte-identical binaries")
+ /// The fixture the frozen digests were taken over. Without this a digest
+ /// mismatch below would read as a patcher bug when the real cause is a
+ /// different firmware's `launchd_cache_loader`.
+ @Test("the fixture is the one the goldens were recorded from")
+ func fixtureMatchesTheGoldens() throws {
+ let pristine = try #require(CacheLoaderFixture.pristine, CacheLoaderFixture.missing)
+ #expect(
+ try CacheLoaderFixture.digest(of: pristine) == CacheLoaderGolden.pristine,
+ """
+ this is not the 24A435 launchd_cache_loader CacheLoaderGolden was \
+ recorded from — re-derive the goldens before reading a failure \
+ below as a patcher bug
+ """
+ )
+ }
+
+ @Test("Swift reproduces the reference's bytes")
func byteForByteParity() throws {
let swiftClone = try CacheLoaderFixture.clone(named: "swift")
- let pythonClone = try CacheLoaderFixture.clone(named: "python")
- defer { CacheLoaderFixture.discard(swiftClone, pythonClone) }
+ defer { CacheLoaderFixture.discard(swiftClone) }
let report = try CFWCacheLoaderPatcher.patch(fileAt: swiftClone, log: nil)
#expect(report.outcome == .patched)
#expect(report.sitesWritten == 1)
// Off by default, because every shipped caller re-signs afterwards.
#expect(report.reattestedSlots.isEmpty)
+ // The site the reference's `[+] NOPped at 0xC7C` named.
+ #expect(report.gate.fileOffset == CacheLoaderGolden.gateFileOffset)
- let python = try CacheLoaderFixture.runPython(on: pythonClone)
- #expect(python.status == 0, "python failed: \(python.output)")
- #expect(python.stdout.contains("[+] NOPped at"))
-
- let swiftBytes = try CacheLoaderFixture.bytes(of: swiftClone)
- let pythonBytes = try CacheLoaderFixture.bytes(of: pythonClone)
- #expect(swiftBytes == pythonBytes, "Swift and Python disagree")
+ #expect(
+ try CacheLoaderFixture.digest(of: swiftClone) == CacheLoaderGolden.patched,
+ "Swift and the frozen reference disagree"
+ )
}
@Test("exactly one instruction changes, and it is the gate")
@@ -389,8 +400,9 @@ struct CFWCacheLoaderParityTests {
#expect(record.originalBytes != ARM64.nop)
#expect(record.afterDisasm == "nop")
#expect(record.beforeDisasm.hasPrefix("cbz"))
- // Worded exactly as the Python words it, so a captured reference sorts
- // against this port.
+ // Worded exactly as the Python worded it
+ // (scripts/patchers/cfw_patch_cache_loader.py:103 at 78cbeea), so a
+ // captured reference JSON still sorts against this port.
#expect(record.patchDescription
== "NOP the cache-validation branch gated on 'unsecure_cache'")
@@ -455,30 +467,39 @@ struct CFWCacheLoaderRerunTests {
#expect(try CacheLoaderFixture.bytes(of: clone) == afterFirst)
}
- @Test("the Python double-applies where this port stops — the reason they diverge")
- func pythonIsNotIdempotent() throws {
- let pythonClone = try CacheLoaderFixture.clone(named: "python-twice")
+ @Test("the reference double-applied where this port stops — the reason they diverge")
+ func referenceWasNotIdempotent() throws {
let swiftClone = try CacheLoaderFixture.clone(named: "swift-twice")
- defer { CacheLoaderFixture.discard(pythonClone, swiftClone) }
-
- try CacheLoaderFixture.runPython(on: pythonClone)
- let afterFirst = try CacheLoaderFixture.bytes(of: pythonClone)
- let secondRun = try CacheLoaderFixture.runPython(on: pythonClone)
- let afterSecond = try CacheLoaderFixture.bytes(of: pythonClone)
-
- // Not an assertion about what the Python *should* do — a pin on what it
- // does, so this divergence is deliberate and stays visible. The Python
- // walks past its own NOP and takes the next conditional branch.
- #expect(secondRun.status == 0)
- #expect(afterFirst != afterSecond, "the Python became idempotent; revisit this port")
- let extra = ByteComparison.differingOffsets(afterFirst, afterSecond)
- #expect(extra.count == 4)
+ defer { CacheLoaderFixture.discard(swiftClone) }
+
+ // The frozen half: the reference's second run moved the file again,
+ // rewriting four bytes at 0xC84 — it walked past its own NOP and took
+ // the next conditional branch. Not an assertion about what it *should*
+ // have done; a pin on what it did, so this divergence stays deliberate.
+ #expect(CacheLoaderGolden.patchedTwice != CacheLoaderGolden.patched)
+ #expect(CacheLoaderGolden.secondRunOffsets.count == 4)
+ #expect(
+ CacheLoaderGolden.secondRunOffsets
+ .allSatisfy { !(CacheLoaderGolden.gateFileOffset ..< CacheLoaderGolden.gateFileOffset + 4).contains($0) },
+ "the reference's second write was a different instruction, not the gate again"
+ )
+ // The Swift half, measured: two runs land exactly on one reference run.
try CFWCacheLoaderPatcher.patch(fileAt: swiftClone, log: nil)
try CFWCacheLoaderPatcher.patch(fileAt: swiftClone, log: nil)
- let swiftTwice = try CacheLoaderFixture.bytes(of: swiftClone)
- #expect(swiftTwice == afterFirst, "one Swift run twice must equal one Python run once")
- #expect(swiftTwice != afterSecond)
+ let swiftTwice = try CacheLoaderFixture.digest(of: swiftClone)
+ #expect(swiftTwice == CacheLoaderGolden.patched, "one Swift run twice must equal one reference run once")
+ #expect(swiftTwice != CacheLoaderGolden.patchedTwice)
+
+ // And the bytes the reference's second run would have touched are still
+ // the instruction the pristine binary carries there.
+ let pristine = try CacheLoaderFixture.bytes(
+ of: try #require(CacheLoaderFixture.pristine, CacheLoaderFixture.missing)
+ )
+ let patched = try CacheLoaderFixture.bytes(of: swiftClone)
+ let second = CacheLoaderGolden.secondRunOffsets
+ #expect(ByteComparison.differingOffsets(pristine, patched)
+ .allSatisfy { !second.contains($0) })
}
@Test("a dry run locates the site and writes nothing")
@@ -506,29 +527,30 @@ struct CFWCacheLoaderRerunTests {
.serialized
)
struct CFWCacheLoaderSignatureTests {
- @Test("the default output fails codesign, exactly as the Python's does")
+ @Test("the default output fails codesign, exactly as the reference's did")
func defaultOutputIsUnattested() throws {
let swiftClone = try CacheLoaderFixture.clone(named: "unattested-swift")
- let pythonClone = try CacheLoaderFixture.clone(named: "unattested-python")
- defer { CacheLoaderFixture.discard(swiftClone, pythonClone) }
+ defer { CacheLoaderFixture.discard(swiftClone) }
try CFWCacheLoaderPatcher.patch(fileAt: swiftClone, log: nil)
- try CacheLoaderFixture.runPython(on: pythonClone)
// Both leave a stale slot hash, because both rely on the caller
// re-signing the binary wholesale afterwards (`ldid_sign` in
// `cfw_install*.sh`, `VPhoneSigner.sign` in the Swift call site). This
// test exists so that shared assumption is written down where it fails
- // loudly if a caller ever stops honouring it.
+ // loudly if a caller ever stops honouring it. That the reference's own
+ // output failed the same way is frozen: `CacheLoaderGolden.patched` is
+ // the digest of a file with the gate NOPped and slot 0 untouched, which
+ // is what `CacheLoaderGolden.patchedAndReattested` then repairs.
+ #expect(CacheLoaderGolden.patched != CacheLoaderGolden.patchedAndReattested)
#expect(try CacheLoaderFixture.codesignVerify(swiftClone).status != 0)
- #expect(try CacheLoaderFixture.codesignVerify(pythonClone).status != 0)
+ #expect(try CacheLoaderFixture.digest(of: swiftClone) == CacheLoaderGolden.patched)
}
- @Test("re-attested output passes codesign and matches the Python's slot hashes")
+ @Test("re-attested output passes codesign and matches the reference's slot hashes")
func reattestedOutputVerifies() throws {
let swiftClone = try CacheLoaderFixture.clone(named: "attested-swift")
- let pythonClone = try CacheLoaderFixture.clone(named: "attested-python")
- defer { CacheLoaderFixture.discard(swiftClone, pythonClone) }
+ defer { CacheLoaderFixture.discard(swiftClone) }
let report = try CFWCacheLoaderPatcher.patch(
fileAt: swiftClone,
@@ -546,25 +568,23 @@ struct CFWCacheLoaderSignatureTests {
let verified = try CacheLoaderFixture.codesignVerify(swiftClone)
#expect(verified.status == 0, "codesign -v failed: \(verified.output)")
- // …and the Python, patching and re-signing with its own code, lands on
- // the same bytes.
- try CacheLoaderFixture.runPython(on: pythonClone)
- let reattest = try CacheLoaderFixture.runPythonReattest(
- on: pythonClone,
- offsets: [report.gate.fileOffset]
+ // …and the reference, patching and re-signing with its own code, landed
+ // on the same bytes.
+ #expect(
+ try CacheLoaderFixture.digest(of: swiftClone)
+ == CacheLoaderGolden.patchedAndReattested,
+ "the re-attested slot hash must be the one the reference computed"
)
- #expect(reattest.status == 0, "python re-attest failed: \(reattest.output)")
- #expect(try CacheLoaderFixture.bytes(of: swiftClone)
- == (try CacheLoaderFixture.bytes(of: pythonClone)))
}
@Test("re-attesting an already-patched binary repairs it without moving an instruction")
- func reattestRepairsPythonOutput() throws {
+ func reattestRepairsAStaleSlot() throws {
let clone = try CacheLoaderFixture.clone(named: "repair")
defer { CacheLoaderFixture.discard(clone) }
- // The Python's output: patched, and carrying a stale slot hash.
- try CacheLoaderFixture.runPython(on: clone)
+ // The shape the reference left behind: patched, stale slot hash.
+ try CFWCacheLoaderPatcher.patch(fileAt: clone, log: nil)
+ try #require(try CacheLoaderFixture.digest(of: clone) == CacheLoaderGolden.patched)
let beforeRepair = try CacheLoaderFixture.bytes(of: clone)
let report = try CFWCacheLoaderPatcher.patch(
diff --git a/tests/FirmwarePatcherTests/CFWDaemonsTests.swift b/tests/FirmwarePatcherTests/CFWDaemonsTests.swift
index a1f68f97..84d7cca0 100644
--- a/tests/FirmwarePatcherTests/CFWDaemonsTests.swift
+++ b/tests/FirmwarePatcherTests/CFWDaemonsTests.swift
@@ -1,3 +1,4 @@
+import CryptoKit
import Foundation
import Testing
@testable import FirmwarePatcher
@@ -88,8 +89,6 @@ enum CFWDaemonsFixtures {
.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")
@@ -100,10 +99,10 @@ enum CFWDaemonsFixtures {
/// 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]
+ /// Whether the real inputs the frozen reference was recorded over are here.
+ /// `BuildManifest.plist` comes out of an IPSW and is never in the repo.
+ static var referenceInputsAvailable: Bool {
+ [buildManifest, cfwInputArchive, hostLaunchdPlist]
.allSatisfy { FileManager.default.fileExists(atPath: $0.path) }
}
@@ -384,126 +383,222 @@ struct CFWDaemonsTests {
}
}
-// MARK: - Equivalence against the Python
+// MARK: - The frozen reference
+
+/// What `scripts/patchers/` produced on these inputs, recorded before it was
+/// deleted.
+///
+/// Measured at repo commit `78cbeea` with `.venv/bin/python3`. Two of the three
+/// rewrites take an input that is not fixed — the host's own
+/// `/System/Library/xpc/launchd.plist` is 2.6 MB and differs with every macOS
+/// build — so for those the frozen value is the *transform*, read off the
+/// Python's output by diffing it against its own input. Each constant says
+/// which command it came from, and the transform assertions below are exactly
+/// the ones that diff reported.
+enum CFWDaemonsGolden {
+ /// `.venv/bin/python3 scripts/patchers/cfw.py cryptex-paths \
+ /// ipsws/ref_extract/iphone/BuildManifest.plist`
+ /// printed these two lines, in this order.
+ static let cryptexSystemOS = "043-70113-702.dmg.aea"
+ static let cryptexAppOS = "043-69297-784.dmg"
+
+ /// `.venv/bin/python3 scripts/patchers/cfw.py patch-dropbear-plist <copy of
+ /// cfw_input/jb/LaunchDaemons/dropbear.plist>` — over the file whose digest
+ /// is ``dropbearSource`` — left exactly this `ProgramArguments` array and
+ /// changed no other key. `-R` dropped, the two `-r` key paths appended.
+ static let dropbearSource =
+ "2f6b05e7eeeb98559a3eb389a9c8fcb6083c2ccb9f2c105d6b132c76eece78a5"
+ static let dropbearProgramArguments = [
+ "/iosbinpack64/usr/local/bin/dropbear",
+ "--shell",
+ "/iosbinpack64/bin/bash",
+ "-E",
+ "-F",
+ "-p",
+ "22222",
+ "-a",
+ "-r",
+ "/var/dropbear/dropbear_rsa_host_key",
+ "-r",
+ "/var/dropbear/dropbear_ecdsa_host_key",
+ ]
+
+ /// `.venv/bin/python3 scripts/patchers/cfw.py inject-daemons <copy of
+ /// /System/Library/xpc/launchd.plist> <cfw_input/jb/LaunchDaemons>`.
+ ///
+ /// Diffing its output against its input: the top-level key set was
+ /// unchanged, every key but `LaunchDaemons` was untouched, no existing
+ /// `LaunchDaemons` entry moved, and exactly these four keys were added —
+ /// each one carrying the staged plist verbatim, dropbear with the rewrite
+ /// above already applied. It also printed
+ /// `[!] Missing …/vphoned.plist, skipping`.
+ static let injectedDaemonNames = ["bash", "dropbear", "trollvnc", "rpcserver_ios"]
+ static let missingDaemonCount = 1
+
+ /// The inline `plistlib` snippet at `cfw_install_jb.sh:460-469` and
+ /// `cfw_install_exp.sh:702-711`, run verbatim over the same input.
+ ///
+ /// The same diff: one key added, carrying `scripts/vphone_jb_setup.plist`
+ /// verbatim (digest ``jbSetupSource``), nothing else changed.
+ static let jbSetupKey = "/System/Library/LaunchDaemons/com.vphone.jb-setup.plist"
+ static let jbSetupSource =
+ "80ff5a830b81012c1ecfdc596bfb05557ace23ae747002233b2b88b464de9efc"
+
+ static func launchdKey(_ name: String) -> String {
+ "/System/Library/LaunchDaemons/\(name).plist"
+ }
+
+ /// SHA-256 as `shasum -a 256` prints it.
+ static func digest(of url: URL) throws -> String {
+ Data(SHA256.hash(data: try Data(contentsOf: url))).hex
+ }
+}
+
+// MARK: - Equivalence against the frozen reference
/// 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.
+/// These run only while the real inputs are here — `BuildManifest.plist` comes
+/// out of an IPSW, and `ipsws/` is not in the repo.
@Suite(
- "CFW daemon rewrites match the Python they replace",
- .enabled(if: CFWDaemonsFixtures.pythonReferenceAvailable)
+ "CFW daemon rewrites match the Python they replaced",
+ .enabled(if: CFWDaemonsFixtures.referenceInputsAvailable)
)
-struct CFWDaemonsPythonEquivalenceTests {
+struct CFWDaemonsReferenceEquivalenceTests {
@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)
-
+ func cryptexPathsMatchTheReference() throws {
let swift = try CFWDaemons.cryptexPaths(buildManifest: CFWDaemonsFixtures.buildManifest)
- #expect(swift.systemOS == lines[0])
- #expect(swift.appOS == lines[1])
+ #expect(swift.systemOS == CFWDaemonsGolden.cryptexSystemOS)
+ #expect(swift.appOS == CFWDaemonsGolden.cryptexAppOS)
}
@Test("patch-dropbear-plist on the installer's real dropbear.plist")
- func dropbearPlistMatchesPython() throws {
+ func dropbearPlistMatchesTheReference() 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")
+ try #require(
+ try CFWDaemonsGolden.digest(of: source) == CFWDaemonsGolden.dropbearSource,
+ "the archive's dropbear.plist is not the one the golden was recorded over"
+ )
+ let before = try CFWDaemonsFixtures.loadPlist(source)
- 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 after = try CFWDaemonsFixtures.loadPlist(swiftCopy)
- let differences = try PlistSemantics.differences(
- CFWDaemonsFixtures.loadPlist(pythonCopy),
- CFWDaemonsFixtures.loadPlist(swiftCopy)
+ #expect(
+ (after["ProgramArguments"] as? [Any])?.compactMap { $0 as? String }
+ == CFWDaemonsGolden.dropbearProgramArguments
)
+ // …and nothing but that key moved, which is the other half of what the
+ // Python's own output diff said.
+ var expected = after
+ expected["ProgramArguments"] = before["ProgramArguments"]
+ let differences = PlistSemantics.differences(before, expected)
#expect(differences.isEmpty, "\(differences)")
}
@Test("inject-daemons on a real launchd.plist and the real staging directory")
- func injectDaemonsMatchesPython() throws {
+ func injectDaemonsMatchesTheReference() 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"
)
+ let before = try CFWDaemonsFixtures.loadPlist(swiftCopy)
- 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"])
+ #expect(staged.injectedNames == CFWDaemonsGolden.injectedDaemonNames)
// 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)
+ #expect(staged.missingSources.count == CFWDaemonsGolden.missingDaemonCount)
- let differences = try PlistSemantics.differences(
- CFWDaemonsFixtures.loadPlist(pythonCopy),
- CFWDaemonsFixtures.loadPlist(swiftCopy)
+ let after = try CFWDaemonsFixtures.loadPlist(swiftCopy)
+ try assertOnlyAdded(
+ CFWDaemonsGolden.injectedDaemonNames.map(CFWDaemonsGolden.launchdKey),
+ to: before, in: after
)
- #expect(differences.isEmpty, "\(differences.prefix(10))")
+
+ // Each added value is the staged plist verbatim — dropbear with the
+ // rewrite applied — which is what the reference's output diff showed.
+ let daemons = try #require(after["LaunchDaemons"] as? [String: Any])
+ for name in CFWDaemonsGolden.injectedDaemonNames {
+ var source = try CFWDaemonsFixtures.loadPlist(staging.appending(path: "\(name).plist"))
+ if name == "dropbear" {
+ var patched: PlistDict = source
+ CFWDaemons.patchDropbearDaemon(&patched)
+ source = patched
+ }
+ let injected = try #require(daemons[CFWDaemonsGolden.launchdKey(name)])
+ let differences = PlistSemantics.differences(source, injected)
+ #expect(differences.isEmpty, "\(name): \(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
+ /// `cfw_install_exp.sh:702-711`, measured 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.
+ /// sites" has to mean: the inline snippet was 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"
+ try #require(
+ try CFWDaemonsGolden.digest(of: CFWDaemonsFixtures.jbSetupPlist)
+ == CFWDaemonsGolden.jbSetupSource,
+ "vphone_jb_setup.plist is not the one the golden was recorded over"
)
+
let swiftCopy = try CFWDaemonsFixtures.writableCopy(
of: CFWDaemonsFixtures.hostLaunchdPlist, in: directory, named: "swift-launchd.plist"
)
+ let before = try CFWDaemonsFixtures.loadPlist(swiftCopy)
- 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)
- )
+ let after = try CFWDaemonsFixtures.loadPlist(swiftCopy)
+ try assertOnlyAdded([CFWDaemonsGolden.jbSetupKey], to: before, in: after)
+
+ let daemons = try #require(after["LaunchDaemons"] as? [String: Any])
+ let injected = try #require(daemons[CFWDaemonsGolden.jbSetupKey])
+ let source = try CFWDaemonsFixtures.loadPlist(CFWDaemonsFixtures.jbSetupPlist)
+ let differences = PlistSemantics.differences(source, injected)
#expect(differences.isEmpty, "\(differences.prefix(10))")
}
+
+ /// The shape the reference's output diff reported, for both merges: the
+ /// top-level key set unchanged, every key but `LaunchDaemons` untouched, no
+ /// existing `LaunchDaemons` entry moved or removed, and exactly `keys`
+ /// added.
+ private func assertOnlyAdded(
+ _ keys: [String],
+ to before: [String: Any],
+ in after: [String: Any]
+ ) throws {
+ #expect(Set(before.keys).union(["LaunchDaemons"]) == Set(after.keys))
+ for key in before.keys where key != "LaunchDaemons" {
+ let differences = PlistSemantics.differences(before[key]!, after[key]!, at: key)
+ #expect(differences.isEmpty, "\(differences)")
+ }
+
+ let old = (before["LaunchDaemons"] as? [String: Any]) ?? [:]
+ let new = try #require(after["LaunchDaemons"] as? [String: Any])
+ #expect(Set(new.keys).subtracting(old.keys) == Set(keys))
+ #expect(Set(old.keys).subtracting(new.keys).isEmpty)
+ for key in old.keys where !keys.contains(key) {
+ let differences = PlistSemantics.differences(old[key]!, new[key]!, at: key)
+ #expect(differences.isEmpty, "\(differences)")
+ }
+ }
}
diff --git a/tests/FirmwarePatcherTests/CFWDiskimagesiodTests.swift b/tests/FirmwarePatcherTests/CFWDiskimagesiodTests.swift
index 9221b227..e75486e0 100644
--- a/tests/FirmwarePatcherTests/CFWDiskimagesiodTests.swift
+++ b/tests/FirmwarePatcherTests/CFWDiskimagesiodTests.swift
@@ -5,12 +5,15 @@
// assertion — so the reference these tests grade against is not this port's
// own opinion. It is, in order of authority:
//
-// 1. `cfw.py patch-diskimagesiod`, the Python that has already shipped, run
-// under the project venv over a clone of the same pristine binary;
+// 1. `cfw.py patch-diskimagesiod`, the Python that shipped before this port,
+// run under the project venv over a clone of the same pristine binary;
// 2. `cfw_macho_codesign.reattest_modified_offsets`, the Python's own
// independent re-signing implementation, for the `reattest: true` path;
// 3. `/usr/bin/codesign -v`, which is neither implementation.
//
+// The Python is gone. What it and its re-signer wrote is frozen digest by
+// digest in ``DiskImagesGolden`` below, with the command that produced each.
+//
// The fixture is the real `usr/libexec/diskimagesiod` from iOS 27.0 / 24A435 /
// iPhone17,3: 2.8 MB, arm64e, ad-hoc signed, CodeDirectory v=20400, 710+7
// hashes, and a codeLimit of 0x2C5840 that is NOT page-aligned — the short tail
@@ -27,6 +30,7 @@
// (`clonefile`: instant, and free on APFS) under the system temporary
// directory, or under `VPHONE_MACHO_SCRATCH` when the caller names one.
+import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
@@ -80,14 +84,12 @@ private enum DiskImagesFixture {
.appendingPathComponent("vphone-macho-diskimagesiod")
}
- /// The project venv, which is where the reference Python lives.
- static var python: URL? {
- let url = repoRoot.appendingPathComponent(".venv/bin/python3")
- return FileManager.default.fileExists(atPath: url.path) ? url : nil
+ /// SHA-256 as `shasum -a 256` prints it, so a digest asserted here can be
+ /// taken again from a shell over the same file.
+ static func digest(of url: URL) throws -> String {
+ Data(SHA256.hash(data: try Data(contentsOf: url))).hex
}
- static var cfwPy: URL { repoRoot.appendingPathComponent("scripts/patchers/cfw.py") }
-
/// Clone the pristine binary into a fresh file the caller may write to.
///
/// `cp -c` asks for a `clonefile`, which costs no space and no time when the
@@ -127,46 +129,6 @@ private enum DiskImagesFixture {
}
}
- /// Run the shipped Python patcher over `binary`.
- @discardableResult
- static func runPython(on binary: URL) throws -> DiskImagesShell.Result {
- let python = try #require(
- self.python,
- "the reference Python is required — run `make setup_venv`"
- )
- let result = try DiskImagesShell.run(
- executable: python,
- arguments: [cfwPy.path, "patch-diskimagesiod", binary.path],
- currentDirectory: repoRoot.appendingPathComponent("scripts")
- )
- #expect(result.status == 0, "cfw.py patch-diskimagesiod failed: \(result.stderr)")
- return result
- }
-
- /// Re-attest `offsets` in `binary` using the Python's own independent
- /// implementation, `cfw_macho_codesign.reattest_modified_offsets`.
- @discardableResult
- static func runPythonReattest(on binary: URL, offsets: [Int]) throws -> DiskImagesShell.Result {
- let python = try #require(
- self.python,
- "the reference Python is required — run `make setup_venv`"
- )
- let list = offsets.map(String.init).joined(separator: ",")
- let program = """
- import sys
- sys.path.insert(0, "scripts")
- from patchers.cfw_macho_codesign import reattest_modified_offsets
- reattest_modified_offsets(sys.argv[1], [\(list)], verbose=False)
- """
- let result = try DiskImagesShell.run(
- executable: python,
- arguments: ["-c", program, binary.path],
- currentDirectory: repoRoot
- )
- #expect(result.status == 0, "python reattest failed: \(result.stderr)")
- return result
- }
-
/// `codesign -v` on a file, which is a reference neither implementation wrote.
static func codesignVerify(_ binary: URL) throws -> DiskImagesShell.Result {
try DiskImagesShell.run(
@@ -189,8 +151,7 @@ private enum DiskImagesShell {
///
/// The two pipes are drained on separate queues rather than one after the
/// other. A pipe holds about 64 KiB; draining stdout to EOF first would
- /// wedge any child that fills stderr in the meantime, and the child here is
- /// a Python patcher that logs freely to both.
+ /// wedge any child that fills stderr in the meantime.
@discardableResult
static func run(
executable: URL,
@@ -245,6 +206,56 @@ private enum DiskImagesShell {
}
}
+// MARK: - The frozen reference
+
+/// What `scripts/patchers/` produced on this fixture, recorded before it was
+/// deleted.
+///
+/// Every value below was taken at repo commit `78cbeea`, with
+/// `.venv/bin/python3` driving `scripts/patchers/`, over the real iOS 27.0 /
+/// 24A435 / iPhone17,3 `usr/libexec/diskimagesiod` whose own digest is
+/// ``pristine``.
+private enum DiskImagesGolden {
+ /// `shasum -a 256 ipsws/ref_extract/macho_pristine/diskimagesiod`
+ static let pristine = "77e472b74d518beedb2533c409fd66ec964c90264ad35d8fa9f10f82a448af15"
+
+ /// `.venv/bin/python3 scripts/patchers/cfw.py patch-diskimagesiod <clone>`
+ /// — the ObjC prologue at 0x320C0 replaced with `mov x0, #1 ; ret`,
+ /// signature left stale. Its stdout reported
+ /// `Found via relative method list: IMP va:0x1000320C0 foff:0x320C0`.
+ static let patched = "41daf01d25fc98317516c1aa4c3a095a0e449715907e9e71f1cff6310bcd9cbd"
+
+ /// The IMP that run resolved, from that stdout line.
+ static let impFileOffset = 0x3_20C0
+ static let impVirtualAddress: UInt64 = 0x1_0003_20C0
+
+ /// ``patched``, then
+ /// `.venv/bin/python3 -c 'import sys; sys.path.insert(0, "scripts/patchers");
+ /// import cfw_macho_codesign as r;
+ /// r.reattest_modified_offsets(sys.argv[1], [204992, 204999], verbose=True)'`
+ /// — which reported `wrote cd_index=0 slot 50 (6e2cd215.. -> b7814241..)`.
+ static let patchedAndReattested =
+ "eea1a205c3b3d14ab41acf262b67f34fcdbb14ec96e7deb5a86adb5e807cec44"
+
+ /// The one code slot that re-attestation rewrote.
+ static let reattestedSlot = 50
+
+ /// The short-tail case, which the real patch site is nowhere near. On a
+ /// *pristine* clone, byte 2905120 (0x2C5420, the middle of the last slot)
+ /// XORed with 0xFF, then the same re-attester over `[2905120]` — which
+ /// reported `wrote cd_index=0 slot 709 [tail, 2112B] (2197132a.. -> 8106b4a9..)`.
+ static let tailVictimOffset = 2_905_120
+ static let tailFlippedAndReattested =
+ "bc979503698fcb92e3db6ae46650ea3cad6c66fd119765370c1f0cd5eb7281e9"
+ static let tailSlot = 709
+ static let tailSlotLength = 2112
+
+ /// `cfw.py patch-diskimagesiod` run a SECOND time over ``patched``: it
+ /// rewrote the same eight bytes and the file did not move, so the digest is
+ /// ``patched`` again.
+ static let patchedTwice = patched
+}
+
// MARK: - Byte comparison
private enum DiskImagesComparison {
@@ -325,18 +336,27 @@ struct CFWDiskimagesiodAnchorTests {
.hasPrefix("pacibsp; stp"))
}
- @Test("the Python's own anchor walk agrees on the same offset")
- func agreesWithPythonAnchor() throws {
+ @Test("the fixture is the one the goldens were recorded from")
+ func fixtureMatchesTheGoldens() throws {
+ let pristine = try #require(DiskImagesFixture.pristine, DiskImagesFixture.missing)
+ #expect(
+ try DiskImagesFixture.digest(of: pristine) == DiskImagesGolden.pristine,
+ """
+ this is not the 24A435 diskimagesiod DiskImagesGolden was recorded \
+ from — re-derive the goldens before reading a failure elsewhere in \
+ this file as a patcher bug
+ """
+ )
+ }
+
+ @Test("the reference's own anchor walk agreed on the same offset")
+ func agreesWithTheFrozenAnchor() throws {
let pristine = try #require(DiskImagesFixture.pristine, DiskImagesFixture.missing)
let site = try CFWDiskimagesiod.locate(in: try Data(contentsOf: pristine))
- // The Python prints the offset it resolved; both walks must land on it.
- let clone = try DiskImagesFixture.clone(named: "anchor")
- defer { DiskImagesFixture.discard(clone) }
- let output = try DiskImagesFixture.runPython(on: clone).stdout
- let expected = "IMP va:0x\(String(site.virtualAddress ?? 0, radix: 16, uppercase: true)) "
- + "foff:0x\(String(site.fileOffset, radix: 16, uppercase: true))"
- #expect(output.contains(expected), "python said:\n\(output)")
+ // The offset the Python printed; both walks must land on it.
+ #expect(site.fileOffset == DiskImagesGolden.impFileOffset)
+ #expect(site.virtualAddress == DiskImagesGolden.impVirtualAddress)
}
@Test("the selector names exactly one implementation in the image")
@@ -385,10 +405,10 @@ struct CFWDiskimagesiodAnchorTests {
let methlist = try #require(sections["__TEXT,__objc_methlist"])
let targets: Set<UInt64> = [selectorVA, selrefVA]
- // The Python only ever does the strided scan. Both walks over the same
+ // The Python only ever did the strided scan. Both walks over the same
// section have to name the same single implementation, or the two
- // implementations would diverge on some other firmware even though they
- // agree on this one.
+ // implementations would have diverged on some other firmware even
+ // though they agreed on this one.
let structural = CFWDiskimagesiod.relativeMethodListIMPs(
in: data,
section: methlist,
@@ -413,7 +433,7 @@ struct CFWDiskimagesiodAnchorTests {
}
}
-// MARK: - Parity against the Python
+// MARK: - Parity against the frozen reference
@Suite(
"diskimagesiod parity",
@@ -421,23 +441,23 @@ struct CFWDiskimagesiodAnchorTests {
.serialized
)
struct CFWDiskimagesiodParityTests {
- @Test("Swift and Python produce byte-identical binaries, one site each")
+ @Test("Swift reproduces the reference's bytes, one site each")
func byteForByteParity() throws {
let swiftClone = try DiskImagesFixture.clone(named: "swift")
- let pythonClone = try DiskImagesFixture.clone(named: "python")
- defer { DiskImagesFixture.discard(swiftClone, pythonClone) }
+ defer { DiskImagesFixture.discard(swiftClone) }
let report = try CFWDiskimagesiod.patch(fileAt: swiftClone, log: nil)
#expect(report.outcome == .patched)
#expect(report.sitesWritten == 1)
// Off by default: `cfw_install.sh` re-signs with ldid straight after,
- // and the Python does not re-attest either.
+ // and the Python did not re-attest either.
#expect(report.rehashes.isEmpty)
+ #expect(report.site.fileOffset == DiskImagesGolden.impFileOffset)
- try DiskImagesFixture.runPython(on: pythonClone)
-
- let differences = try DiskImagesComparison.differences(between: swiftClone, and: pythonClone)
- #expect(differences.isEmpty, "first differing offsets: \(differences.map { String($0, radix: 16) })")
+ #expect(
+ try DiskImagesFixture.digest(of: swiftClone) == DiskImagesGolden.patched,
+ "Swift and the frozen reference disagree"
+ )
}
@Test("the recorded write names the site, the bytes and both disassemblies")
@@ -529,40 +549,38 @@ struct CFWDiskimagesiodReattestTests {
#expect(verification.status == 0, "codesign said: \(verification.stderr)")
}
- @Test("the re-attested bytes are the Python re-attest's bytes")
- func reattestMatchesPython() throws {
+ @Test("the re-attested bytes are the reference re-attest's bytes")
+ func reattestMatchesTheFrozenReference() throws {
let swiftClone = try DiskImagesFixture.clone(named: "swift-attested")
- let pythonClone = try DiskImagesFixture.clone(named: "python-attested")
- defer { DiskImagesFixture.discard(swiftClone, pythonClone) }
+ defer { DiskImagesFixture.discard(swiftClone) }
let report = try CFWDiskimagesiod.patch(fileAt: swiftClone, reattest: true, log: nil)
-
- try DiskImagesFixture.runPython(on: pythonClone)
- try DiskImagesFixture.runPythonReattest(
- on: pythonClone,
- offsets: [report.site.fileOffset, report.site.fileOffset + 7]
+ #expect(report.rehashes.first?.pageIndex == DiskImagesGolden.reattestedSlot)
+ #expect(
+ try DiskImagesFixture.digest(of: swiftClone) == DiskImagesGolden.patchedAndReattested,
+ "the re-attested slot hash must be the one the reference computed"
)
-
- let differences = try DiskImagesComparison.differences(between: swiftClone, and: pythonClone)
- #expect(differences.isEmpty, "first differing offsets: \(differences.map { String($0, radix: 16) })")
}
@Test("a short-tail slot is hashed to codeLimit, not to the end of its page")
func tailSlotStopsAtCodeLimit() throws {
let swiftClone = try DiskImagesFixture.clone(named: "swift-tail")
- let pythonClone = try DiskImagesFixture.clone(named: "python-tail")
- defer { DiskImagesFixture.discard(swiftClone, pythonClone) }
+ defer { DiskImagesFixture.discard(swiftClone) }
// Land a byte inside the last, short slot. This is synthetic — the real
- // patch site is nowhere near — and it is the only way to make both
- // implementations recompute the slot whose length is not a page.
+ // patch site is nowhere near — and it is the only way to make the
+ // re-attester recompute the slot whose length is not a page. The victim
+ // is derived, not typed in, and then checked against the offset the
+ // frozen run used so both sides really are the same experiment.
var data = try Data(contentsOf: swiftClone)
let directory = try #require(CFWMachOCodeSignature.codeDirectories(in: data)?.first)
let tail = try #require(directory.slotRange(directory.codeSlotCount - 1))
let victim = tail.lowerBound + tail.count / 2
+ #expect(victim == DiskImagesGolden.tailVictimOffset)
+ #expect(tail.count == DiskImagesGolden.tailSlotLength)
+ #expect(directory.codeSlotCount - 1 == DiskImagesGolden.tailSlot)
data[victim] = data[victim] ^ 0xFF
try data.write(to: swiftClone)
- try data.write(to: pythonClone)
let rehashes = try CFWMachOCodeSignature.reattest(fileAt: swiftClone, modifiedOffsets: [victim])
let slot = try #require(rehashes.first)
@@ -570,9 +588,11 @@ struct CFWDiskimagesiodReattestTests {
#expect(slot.hashedLength == tail.count)
#expect(slot.pageEnd == directory.codeLimit)
- try DiskImagesFixture.runPythonReattest(on: pythonClone, offsets: [victim])
- let differences = try DiskImagesComparison.differences(between: swiftClone, and: pythonClone)
- #expect(differences.isEmpty, "first differing offsets: \(differences.map { String($0, radix: 16) })")
+ #expect(
+ try DiskImagesFixture.digest(of: swiftClone)
+ == DiskImagesGolden.tailFlippedAndReattested,
+ "the tail slot hash must be the one the reference re-attester computed"
+ )
}
}
@@ -621,23 +641,30 @@ struct CFWDiskimagesiodIdempotenceTests {
#expect(try DiskImagesFixture.codesignVerify(clone).status == 0)
}
- @Test("Python over a Swift-patched binary is a no-op, and the reverse too")
+ /// Running the two implementations in either order lands on one file.
+ ///
+ /// The reference half is frozen: `cfw.py patch-diskimagesiod` over its own
+ /// output rewrote the same eight bytes and the digest did not move
+ /// (``DiskImagesGolden/patchedTwice`` is ``DiskImagesGolden/patched``). So
+ /// "the reference over a Swift-patched binary" is the same experiment as
+ /// "the reference over its own output" — the two files are byte-identical
+ /// by `byteForByteParity` — and what is left to measure is this side:
+ /// Swift over the bytes the reference left behind must change nothing.
+ @Test("the reference's output is what this port reports as already patched")
func crossImplementationRerunsAgree() throws {
- let swiftFirst = try DiskImagesFixture.clone(named: "swift-then-python")
- let pythonFirst = try DiskImagesFixture.clone(named: "python-then-swift")
- defer { DiskImagesFixture.discard(swiftFirst, pythonFirst) }
-
- try CFWDiskimagesiod.patch(fileAt: swiftFirst, log: nil)
- let afterSwift = try Data(contentsOf: swiftFirst)
- try DiskImagesFixture.runPython(on: swiftFirst)
- #expect(try Data(contentsOf: swiftFirst) == afterSwift)
-
- try DiskImagesFixture.runPython(on: pythonFirst)
- let afterPython = try Data(contentsOf: pythonFirst)
- let report = try CFWDiskimagesiod.patch(fileAt: pythonFirst, log: nil)
+ let referenceOutput = try DiskImagesFixture.clone(named: "reference-then-swift")
+ defer { DiskImagesFixture.discard(referenceOutput) }
+
+ // Reproduce the reference's output, and prove it is that, by digest.
+ try CFWDiskimagesiod.patch(fileAt: referenceOutput, log: nil)
+ try #require(
+ try DiskImagesFixture.digest(of: referenceOutput) == DiskImagesGolden.patched
+ )
+ #expect(DiskImagesGolden.patchedTwice == DiskImagesGolden.patched)
+
+ let report = try CFWDiskimagesiod.patch(fileAt: referenceOutput, log: nil)
#expect(report.outcome == .alreadyPatched)
- #expect(try Data(contentsOf: pythonFirst) == afterPython)
- #expect(try DiskImagesComparison.identical(swiftFirst, pythonFirst))
+ #expect(try DiskImagesFixture.digest(of: referenceOutput) == DiskImagesGolden.patched)
}
@Test("a dry run locates the site and writes nothing")
diff --git a/tests/FirmwarePatcherTests/CFWJetsamTests.swift b/tests/FirmwarePatcherTests/CFWJetsamTests.swift
index f1607b87..b5566fe7 100644
--- a/tests/FirmwarePatcherTests/CFWJetsamTests.swift
+++ b/tests/FirmwarePatcherTests/CFWJetsamTests.swift
@@ -2,24 +2,25 @@
//
// The bar for this port is not "the test passes". It is that the Swift patcher
// and `scripts/patchers/cfw_patch_jetsam.py` produce the same bytes from the
-// same input, on the real `/sbin/launchd` out of iOS 27.0 / 24A435 — so the
-// comparison tests below run BOTH implementations, each over its own clone of
-// `ipsws/ref_extract/macho_pristine/launchd`, and diff the results.
+// same input, on the real `/sbin/launchd` out of iOS 27.0 / 24A435. That Python
+// is gone: what it wrote, and the two anchors it printed on its way there, are
+// frozen in ``JetsamGolden`` below, and the comparison tests grade the Swift
+// against those.
//
// `codesign -v` is the second, fully independent reference: the patcher's
// `reattest: true` mode has to leave a binary that verifies, and the slot hash
// it writes has to equal the one the Python's own `cfw_macho_codesign.py`
-// computes over the same patched bytes.
+// computed over the same patched bytes — also frozen.
//
-// The reference is on its way out — plan P1.5 deletes `scripts/patchers/`, and
-// `ipsws/` is not in the repo — so every test that needs one is gated on it
-// still being there and skips rather than fails when it is not. The pure
-// decode/encode tests below have no such dependency and always run.
+// `ipsws/` is not in the repo, so every test that needs the pristine `launchd`
+// is gated on it being there and skips rather than fails when it is not. The
+// pure decode/encode tests below have no such dependency and always run.
//
// Set `VPHONE_JETSAM_ARTIFACTS=<dir>` to keep each run's inputs and outputs for
// inspection from a shell; without it they land in a temporary directory.
import Capstone
+import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
@@ -37,19 +38,19 @@ enum JetsamFixture {
/// The real, ad-hoc signed, thin arm64e `/sbin/launchd`.
static let pristineLaunchd = repositoryRoot
.appending(path: "ipsws/ref_extract/macho_pristine/launchd")
- static let python = repositoryRoot.appending(path: ".venv/bin/python3")
- static let pythonCFW = repositoryRoot.appending(path: "scripts/patchers/cfw.py")
- static let pythonCodeSign = repositoryRoot.appending(path: "scripts/patchers/cfw_macho_codesign.py")
- static let scriptsDirectory = repositoryRoot.appending(path: "scripts")
static let codesign = URL(filePath: "/usr/bin/codesign")
static func exists(_ url: URL) -> Bool { FileManager.default.fileExists(atPath: url.path) }
static var hasLaunchd: Bool { exists(pristineLaunchd) }
- static var hasPythonReference: Bool { exists(python) && exists(pythonCFW) }
- static var hasLaunchdAndPython: Bool { hasLaunchd && hasPythonReference }
static var hasLaunchdAndCodesign: Bool { hasLaunchd && exists(codesign) }
+ /// SHA-256 as `shasum -a 256` prints it, so a digest asserted here can be
+ /// taken again from a shell over the same file.
+ static func digest(of url: URL) throws -> String {
+ Data(SHA256.hash(data: try Data(contentsOf: url))).hex
+ }
+
/// A directory for one test's artifacts. `VPHONE_JETSAM_ARTIFACTS` pins it
/// so a shell can look at what a run produced.
static func workDirectory(_ name: String) throws -> URL {
@@ -87,24 +88,6 @@ enum JetsamFixture {
return (process.terminationStatus, String(decoding: output, as: UTF8.self))
}
- /// `cfw.py patch-launchd-jetsam <file>` — the reference implementation.
- @discardableResult
- static func runPythonJetsam(on file: URL) throws -> (status: Int32, output: String) {
- try run(
- python,
- ["patchers/cfw.py", "patch-launchd-jetsam", file.path],
- workingDirectory: scriptsDirectory
- )
- }
-
- /// The hex number the reference prints straight after `marker`, so the
- /// expected values come out of the reference's own stdout instead of being
- /// written down here and going stale with the next firmware.
- static func hexAfter(_ marker: String, in output: String) -> Int? {
- guard let range = output.range(of: marker) else { return nil }
- return Int(String(output[range.upperBound...].prefix { $0.isHexDigit }), radix: 16)
- }
-
/// The first byte offset at which two files differ, or nil when equal.
static func firstDifference(_ lhs: Data, _ rhs: Data) -> Int? {
if lhs.count != rhs.count { return min(lhs.count, rhs.count) }
@@ -113,29 +96,82 @@ enum JetsamFixture {
}
}
-// MARK: - Against the Python reference
+// MARK: - The frozen reference
+
+/// What `scripts/patchers/` produced on this fixture, recorded before it was
+/// deleted.
+///
+/// Every value below was taken at repo commit `78cbeea`, with
+/// `.venv/bin/python3` driving `scripts/patchers/`, over the real iOS 27.0 /
+/// 24A435 / iPhone17,3 `/sbin/launchd` whose own digest is ``pristine``.
+enum JetsamGolden {
+ /// `shasum -a 256 ipsws/ref_extract/macho_pristine/launchd`
+ static let pristine = "c640246d38aaeb2d2372aff1e5aa0de59dec267f53c0dfc155f7837e717af68b"
+
+ /// `.venv/bin/python3 scripts/patchers/cfw.py patch-launchd-jetsam <clone>`
+ /// — `cbz w0, #0xfaec` at 0xFA98 rewritten to `b #0xfaec`, signature left
+ /// stale.
+ static let patched = "cae806f55aadc0109c6b8e737b0ee4e648ce7ec1fbcce0ac9215f45b736d0fcb"
+
+ /// The two anchors that run printed on its way to the gate, not just its
+ /// answer — so a port that agreed on the gate by luck is still caught:
+ /// " xref at foff:0xFB0C"
+ /// " [+] Patched at 0xFA98: jetsam panic guard bypass"
+ static let xrefOffset = 0xFB0C
+ static let gateOffset = 0xFA98
+
+ /// ``patched``, then
+ /// `.venv/bin/python3 -c 'import sys; sys.path.insert(0, "scripts/patchers");
+ /// import cfw_macho_codesign as r;
+ /// r.reattest_modified_offsets(sys.argv[1], [64152], verbose=True)'`
+ /// — which reported `wrote cd_index=0 slot 15 (ff0c126a.. -> 361aa09d..)`.
+ static let patchedAndReattested =
+ "689236aad3bb8fe360412195ff626269ee7403be322628a5bb66517a65ad2ea2"
+
+ /// The one code slot that re-attestation rewrote.
+ static let reattestedSlot = 15
+
+ /// `cfw.py patch-launchd-jetsam` run a SECOND time over ``patched``.
+ ///
+ /// Not what the reference should have done — what it did. It landed a
+ /// second site the pristine image never had patched, printing
+ /// `[+] Patched at 0xFAB0`, so the file moved again. This port recognises
+ /// its own work and stops; the digest keeps that divergence visible.
+ static let patchedTwice = "2c979d9dbeb0de9cd4877c843f1910ccff43a5ebfdf50c1e0f6bdc5d53370979"
+
+ /// The second gate the reference took, from that stdout line.
+ static let secondRunGateOffset = 0xFAB0
+}
-@Suite("launchd jetsam guard — against the Python reference")
+// MARK: - Against the frozen reference
+
+@Suite("launchd jetsam guard — against the frozen reference")
struct CFWJetsamReferenceTests {
+ /// The fixture the frozen digests were taken over. Without this a digest
+ /// mismatch below would read as a patcher bug when the real cause is a
+ /// different firmware's `launchd`.
+ @Test(.enabled(if: JetsamFixture.hasLaunchd))
+ func fixtureMatchesTheGoldens() throws {
+ #expect(
+ try JetsamFixture.digest(of: JetsamFixture.pristineLaunchd) == JetsamGolden.pristine,
+ """
+ this is not the 24A435 launchd JetsamGolden was recorded from — \
+ re-derive the goldens before reading a failure below as a patcher bug
+ """
+ )
+ }
+
/// The whole point of the port: same input, same bytes out.
- @Test(.enabled(if: JetsamFixture.hasLaunchdAndPython))
- func matchesPythonByteForByte() throws {
+ @Test(.enabled(if: JetsamFixture.hasLaunchd))
+ func matchesTheFrozenReferenceByteForByte() throws {
let work = try JetsamFixture.workDirectory("byte-equivalence")
let swiftTarget = try JetsamFixture.launchdCopy(named: "launchd.swift", in: work)
- let pythonTarget = try JetsamFixture.launchdCopy(named: "launchd.python", in: work)
let outcome = try CFWJetsamPatcher.patch(fileAt: swiftTarget, log: nil)
#expect(outcome.verdict == .patched)
-
- let reference = try JetsamFixture.runPythonJetsam(on: pythonTarget)
- #expect(reference.status == 0, "reference patcher failed:\n\(reference.output)")
-
- let swiftBytes = try Data(contentsOf: swiftTarget)
- let pythonBytes = try Data(contentsOf: pythonTarget)
- let difference = JetsamFixture.firstDifference(swiftBytes, pythonBytes)
#expect(
- difference == nil,
- "Swift and Python diverge at offset \(difference.map { "0x" + String($0, radix: 16) } ?? "-")"
+ try JetsamFixture.digest(of: swiftTarget) == JetsamGolden.patched,
+ "Swift and the frozen reference diverge"
)
// And the only thing that moved is inside the instruction the record
@@ -143,6 +179,7 @@ struct CFWJetsamReferenceTests {
// `cbz w0, #0xfaec` is A0 02 00 34 and `b #0xfaec` is 15 00 00 14, so
// byte 2 is 0x00 either way. Containment is the real claim — the whole
// instruction was rewritten and nothing outside it was.
+ let swiftBytes = try Data(contentsOf: swiftTarget)
let pristine = try Data(contentsOf: JetsamFixture.pristineLaunchd)
let site = outcome.gateOffset ..< outcome.gateOffset + 4
let changed = (0 ..< pristine.count).filter { pristine[$0] != swiftBytes[$0] }
@@ -152,32 +189,20 @@ struct CFWJetsamReferenceTests {
#expect(Data(pristine[site]) == outcome.record?.originalBytes)
}
- /// The gate the reference reports is the gate this finds. Checked against
- /// its stdout rather than a hard-coded offset, so the day the firmware
- /// moves, this moves with it.
- @Test(.enabled(if: JetsamFixture.hasLaunchdAndPython))
- func agreesWithPythonOnTheSite() throws {
- let work = try JetsamFixture.workDirectory("site-agreement")
- let pythonTarget = try JetsamFixture.launchdCopy(named: "launchd.python", in: work)
- let reference = try JetsamFixture.runPythonJetsam(on: pythonTarget)
- #expect(reference.status == 0)
-
- // Both intermediate anchors the reference prints, not just its answer,
- // so a port that agreed on the gate by luck would still be caught:
- // " xref at foff:0xFB0C"
- // " [+] Patched at 0xFA98: jetsam panic guard bypass"
- let referenceXref = try #require(JetsamFixture.hexAfter("xref at foff:0x", in: reference.output))
- let referenceGate = try #require(JetsamFixture.hexAfter("[+] Patched at 0x", in: reference.output))
-
+ /// The gate the reference reported is the gate this finds — and the xref it
+ /// reached it through too, so a port that agreed on the gate by luck is
+ /// still caught.
+ @Test(.enabled(if: JetsamFixture.hasLaunchd))
+ func agreesWithTheFrozenReferenceOnTheSite() throws {
let data = try Data(contentsOf: JetsamFixture.pristineLaunchd)
let image = try CFWJetsamPatcher.Image(data: data)
let site = try #require(try CFWJetsamPatcher.locate(in: image))
- #expect(site.xrefOffset == referenceXref)
- #expect(site.gateOffset == referenceGate)
+ #expect(site.xrefOffset == JetsamGolden.xrefOffset)
+ #expect(site.gateOffset == JetsamGolden.gateOffset)
var patchable = data
let outcome = try CFWJetsamPatcher.patch(&patchable, dryRun: true, log: nil)
- #expect(outcome.gateOffset == referenceGate)
+ #expect(outcome.gateOffset == JetsamGolden.gateOffset)
#expect(outcome.verdict == .wouldPatch)
}
}
@@ -214,31 +239,38 @@ struct CFWJetsamIdempotenceTests {
#expect(JetsamFixture.firstDifference(afterFirst, afterThird) == nil)
}
- /// Where the reference goes wrong, and proof that it does: run the Python
- /// twice and it lands a *second* site the pristine image never had patched.
- /// Recorded here so the divergence is a measurement, not a claim.
- @Test(.enabled(if: JetsamFixture.hasLaunchdAndPython))
- func referenceIsNotIdempotentAndThisIs() throws {
+ /// Where the reference went wrong, and the measurement that showed it: run
+ /// twice, and it landed a *second* site the pristine image never had
+ /// patched. Frozen, so the divergence stays a measurement, not a claim.
+ @Test(.enabled(if: JetsamFixture.hasLaunchd))
+ func referenceWasNotIdempotentAndThisIs() throws {
let work = try JetsamFixture.workDirectory("reference-double-apply")
- let pythonTarget = try JetsamFixture.launchdCopy(named: "launchd.python", in: work)
let swiftTarget = try JetsamFixture.launchdCopy(named: "launchd.swift", in: work)
- try JetsamFixture.runPythonJetsam(on: pythonTarget)
- let pythonOnce = try Data(contentsOf: pythonTarget)
- try JetsamFixture.runPythonJetsam(on: pythonTarget)
- let pythonTwice = try Data(contentsOf: pythonTarget)
+ // The frozen half: the reference's second run moved the file, and to a
+ // different instruction than the gate it had already rewritten.
+ #expect(
+ JetsamGolden.patchedTwice != JetsamGolden.patched,
+ "the reference was recorded as non-idempotent — re-check what this port has to preserve"
+ )
+ #expect(JetsamGolden.secondRunGateOffset != JetsamGolden.gateOffset)
+ // The Swift half, measured: run once, land on the reference's one-run
+ // bytes; run again, and nothing moves.
try CFWJetsamPatcher.patch(fileAt: swiftTarget, log: nil)
let swiftOnce = try Data(contentsOf: swiftTarget)
+ #expect(Data(SHA256.hash(data: swiftOnce)).hex == JetsamGolden.patched)
+
try CFWJetsamPatcher.patch(fileAt: swiftTarget, log: nil)
let swiftTwice = try Data(contentsOf: swiftTarget)
-
- #expect(JetsamFixture.firstDifference(pythonOnce, swiftOnce) == nil)
- #expect(
- JetsamFixture.firstDifference(pythonOnce, pythonTwice) != nil,
- "the reference became idempotent — re-check what this port has to preserve"
- )
#expect(JetsamFixture.firstDifference(swiftOnce, swiftTwice) == nil)
+ #expect(Data(SHA256.hash(data: swiftTwice)).hex != JetsamGolden.patchedTwice)
+
+ // And the instruction the reference's second run would have taken is
+ // still the one the pristine image carries there.
+ let pristine = try Data(contentsOf: JetsamFixture.pristineLaunchd)
+ let second = JetsamGolden.secondRunGateOffset ..< JetsamGolden.secondRunGateOffset + 4
+ #expect(Data(swiftTwice[second]) == Data(pristine[second]))
}
}
@@ -283,40 +315,22 @@ struct CFWJetsamSignatureTests {
#expect(verify.status == 0, "codesign -v rejected the re-attested binary:\n\(verify.output)")
}
- /// The slot hash itself, against the Python's independent re-signer run
- /// over the Python's own patched bytes. Two implementations, one number.
- @Test(.enabled(if: JetsamFixture.hasLaunchdAndPython))
- func slotHashMatchesThePythonResigner() throws {
- guard JetsamFixture.exists(JetsamFixture.pythonCodeSign) else { return }
+ /// The slot hash itself, against the frozen output of the Python's
+ /// independent re-signer run over the Python's own patched bytes. Two
+ /// implementations, one number.
+ @Test(.enabled(if: JetsamFixture.hasLaunchd))
+ func slotHashMatchesTheFrozenResigner() throws {
let work = try JetsamFixture.workDirectory("slot-hash")
let swiftTarget = try JetsamFixture.launchdCopy(named: "launchd.swift", in: work)
- let pythonTarget = try JetsamFixture.launchdCopy(named: "launchd.python", in: work)
let outcome = try CFWJetsamPatcher.patch(fileAt: swiftTarget, reattest: true, log: nil)
#expect(outcome.verdict == .patched)
-
- try JetsamFixture.runPythonJetsam(on: pythonTarget)
- let resign = try JetsamFixture.run(JetsamFixture.python, [
- "-c",
- """
- import sys
- sys.path.insert(0, \(quoted(JetsamFixture.scriptsDirectory.path)))
- from patchers.cfw_macho_codesign import reattest_modified_offsets
- reattest_modified_offsets(
- \(quoted(pythonTarget.path)), [\(outcome.gateOffset)], verbose=False
- )
- """,
- ])
- #expect(resign.status == 0, "reference re-signer failed:\n\(resign.output)")
-
- let swiftBytes = try Data(contentsOf: swiftTarget)
- let pythonBytes = try Data(contentsOf: pythonTarget)
- #expect(JetsamFixture.firstDifference(swiftBytes, pythonBytes) == nil)
- }
-
- private func quoted(_ path: String) -> String {
- "\"" + path.replacingOccurrences(of: "\\", with: "\\\\")
- .replacingOccurrences(of: "\"", with: "\\\"") + "\""
+ #expect(outcome.gateOffset == JetsamGolden.gateOffset)
+ #expect(outcome.rehashes.first?.pageIndex == JetsamGolden.reattestedSlot)
+ #expect(
+ try JetsamFixture.digest(of: swiftTarget) == JetsamGolden.patchedAndReattested,
+ "the re-attested slot hash must be the one the reference computed"
+ )
}
}
diff --git a/tests/FirmwarePatcherTests/CFWMachOTests.swift b/tests/FirmwarePatcherTests/CFWMachOTests.swift
index ffcc270c..33631d0f 100644
--- a/tests/FirmwarePatcherTests/CFWMachOTests.swift
+++ b/tests/FirmwarePatcherTests/CFWMachOTests.swift
@@ -1,18 +1,20 @@
// 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:
+// Both modules replace something outside this code, so both are tested against
+// it rather than against expectations written down by hand:
//
-// * `CFWInjectDylib` against `.tools/bin/insert_dylib`, byte for byte.
+// * `CFWInjectDylib` against `.tools/bin/insert_dylib`, byte for byte, while
+// that submodule build is still in the tree.
// * `CFWMachOCodeSignature` against `scripts/patchers/cfw_macho_codesign.py`,
-// byte for byte.
+// byte for byte. That Python is gone, so what it wrote is frozen in
+// ``MachOCodeSignGolden`` below — over the real 24A435 `seputil` rather
+// than a local build product, because a golden is only worth what its
+// input is reproducible.
//
-// 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.
+// Those two comparisons are the migration plan's stated gate (P1.1). 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
@@ -33,23 +35,38 @@ enum MachOFixture {
/// 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")
+
+ /// The real 24A435 `seputil`: ad-hoc signed, arm64e, SHA-256 CD, and a
+ /// codeLimit that is not page aligned. Unlike ``signedBinary`` it does not
+ /// change between builds, which is what makes a frozen digest mean
+ /// anything. Not in the repo — `ipsws/` never is.
+ static let pristineSeputil = repositoryRoot
+ .appending(path: "ipsws/ref_extract/macho_pristine/seputil")
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 hasPristineSeputil: Bool { exists(pristineSeputil) }
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 {
+ /// SHA-256 as `shasum -a 256` prints it.
+ static func digest(of url: URL) throws -> String {
+ Data(SHA256.hash(data: try Data(contentsOf: url))).hex
+ }
+
+ /// A private copy of `source` that the caller may modify freely.
+ static func scratchCopy(_ name: String, of source: URL? = nil) 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)
+ try FileManager.default.copyItem(at: source ?? signedBinary, to: destination)
+ // Both sources are 0755 already; this is only so a reference tree
+ // someone made read-only does not turn into a failing patch test.
+ try FileManager.default.setAttributes(
+ [.posixPermissions: 0o755], ofItemAtPath: destination.path
+ )
return destination
}
@@ -242,13 +259,27 @@ struct CFWMachOCodeSignatureTests {
#expect(after[legacyRange] == before[legacyRange], "the SHA-1 CD must be untouched")
}
- // MARK: Cross-check against the Python
+ // MARK: Cross-check against the frozen 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)
+ ///
+ /// The whole experiment is derived from the code directory, not typed in,
+ /// and then each derived value is checked against what the frozen run used
+ /// — so a fixture that drifted fails on the offsets rather than silently
+ /// comparing a different experiment's digest.
+ @Test(.enabled(if: MachOFixture.hasPristineSeputil))
+ func matchesTheFrozenPythonReattester() throws {
+ try #require(
+ try MachOFixture.digest(of: MachOFixture.pristineSeputil)
+ == MachOCodeSignGolden.pristine,
+ """
+ this is not the 24A435 seputil MachOCodeSignGolden was recorded \
+ from — re-derive the golden before reading a failure here as a bug
+ """
+ )
+
+ let data = try Data(contentsOf: MachOFixture.pristineSeputil)
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.
@@ -258,50 +289,69 @@ struct CFWMachOCodeSignatureTests {
directory.codeLimit - 1,
directory.codeLimit + 8,
]
+ #expect(offsets == MachOCodeSignGolden.offsets)
+ #expect(directory.codeLimit == MachOCodeSignGolden.codeLimit)
- let swiftFile = try MachOFixture.scratchCopy("swift")
- let pythonFile = swiftFile.deletingLastPathComponent().appending(path: "python")
- try FileManager.default.copyItem(at: swiftFile, to: pythonFile)
+ let swiftFile = try MachOFixture.scratchCopy("swift", of: MachOFixture.pristineSeputil)
+ defer { try? FileManager.default.removeItem(at: swiftFile.deletingLastPathComponent()) }
// 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(records.map(\.pageIndex).sorted() == MachOCodeSignGolden.rewrittenSlots)
#expect(
- try Data(contentsOf: swiftFile) == (try Data(contentsOf: pythonFile)),
- "Swift and Python re-attestation must agree byte for byte"
+ try MachOFixture.digest(of: swiftFile) == MachOCodeSignGolden.reattested,
+ "Swift and the frozen Python re-attestation must agree byte for byte"
)
}
}
+// MARK: - The frozen re-attestation reference
+
+/// What `scripts/patchers/cfw_macho_codesign.py` produced, recorded before it
+/// was deleted.
+///
+/// Taken at repo commit `78cbeea` with `.venv/bin/python3`, over the real iOS
+/// 27.0 / 24A435 / iPhone17,3 `seputil` whose digest is ``pristine``:
+///
+/// ```
+/// .venv/bin/python3 - <<'PY'
+/// import sys; sys.path.insert(0, "scripts/patchers")
+/// import cfw_macho_codesign as r
+/// p = "<clone of ipsws/ref_extract/macho_pristine/seputil>"
+/// offsets = [16, 90119, 183887, 183896] # codeLimit is 183888
+/// d = bytearray(open(p, "rb").read())
+/// for o in offsets:
+/// if o < 183888: d[o] ^= 0xFF
+/// open(p, "wb").write(bytes(d))
+/// r.reattest_modified_offsets(p, offsets, verbose=True)
+/// PY
+/// ```
+///
+/// which printed `file off 0x2CE58 past codeLimit 0x2CE50 — skipping` and then
+/// `wrote cd_index=0 slot 0`, `slot 22`, `slot 44 [tail, 3664B]`.
+private enum MachOCodeSignGolden {
+ /// `shasum -a 256 ipsws/ref_extract/macho_pristine/seputil`
+ static let pristine = "13e40e74d92928cf9e36fae75970dfcf4c0a4c1040eeac39d1c335407e841474"
+
+ /// The four offsets above, and the codeLimit the last two straddle.
+ static let offsets = [16, 90_119, 183_887, 183_896]
+ static let codeLimit = 183_888
+
+ /// The three slots the reference rewrote; the fourth offset was skipped.
+ static let rewrittenSlots = [0, 22, 44]
+
+ /// `shasum -a 256` of the file that run left behind.
+ static let reattested = "554de26a946547253a04c844e28acdc271b92c701322187e51d0b1d900fa4b1b"
+}
+
// MARK: - Dylib Injection
@Suite("LC_LOAD_DYLIB injection")
diff --git a/tests/FirmwarePatcherTests/CFWMobileactivationdTests.swift b/tests/FirmwarePatcherTests/CFWMobileactivationdTests.swift
index 66aa4da7..2741596b 100644
--- a/tests/FirmwarePatcherTests/CFWMobileactivationdTests.swift
+++ b/tests/FirmwarePatcherTests/CFWMobileactivationdTests.swift
@@ -5,8 +5,9 @@
// from the same input, on the real iOS 27.0 / 24A435 iPhone17,3
// `/usr/libexec/mobileactivationd` in `ipsws/ref_extract/macho_pristine/`, and
// that the result passes `codesign -v` — two references, neither of them this
-// code. Every comparison is gated on the reference still being present, so the
-// suite skips rather than fails once P1.5 deletes the Python.
+// code. The Python is gone; what it wrote is frozen digest by digest in
+// ``MobileactivationdGolden``, so the comparison outlived it. The comparisons
+// are still gated on the pristine binary, which is not in the repo.
//
// Outputs are kept on disk, not in a scratch directory that vanishes, so the
// same comparison can be re-run by hand with `cmp`, `shasum` and `codesign`.
@@ -15,6 +16,7 @@
// `ipsws/ref_extract/`, which is the read-only reference tree.
import Capstone
+import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
@@ -38,8 +40,6 @@ enum MobileactivationdFixture {
static let launchd = repositoryRoot
.appending(path: "ipsws/ref_extract/macho_pristine/launchd")
- static let python = repositoryRoot.appending(path: ".venv/bin/python3")
- static let cfwPy = repositoryRoot.appending(path: "scripts/patchers/cfw.py")
static let codesign = URL(filePath: "/usr/bin/codesign")
/// Where comparison artifacts land, so a failure can be picked apart after
@@ -61,9 +61,14 @@ enum MobileactivationdFixture {
static var hasPristine: Bool { exists(pristine) }
static var hasLaunchd: Bool { exists(launchd) }
- static var hasPythonReference: Bool { hasPristine && exists(python) && exists(cfwPy) }
static var hasCodesign: Bool { hasPristine && exists(codesign) }
+ /// SHA-256 as `shasum -a 256` prints it, so a digest asserted here can be
+ /// taken again from a shell over the same file.
+ static func digest(of url: URL) throws -> String {
+ Data(SHA256.hash(data: try Data(contentsOf: url))).hex
+ }
+
/// A named, writable copy of the pristine binary under ``artifacts``.
static func copyOfPristine(named name: String) throws -> URL {
try FileManager.default.createDirectory(at: artifacts, withIntermediateDirectories: true)
@@ -88,29 +93,40 @@ enum MobileactivationdFixture {
return (process.terminationStatus, String(decoding: output, as: UTF8.self))
}
- /// Run the Python patcher over `file`, in place.
- @discardableResult
- static func runPythonPatcher(on file: URL) throws -> String {
- let result = try run(python, [cfwPy.path, "patch-mobileactivationd", file.path])
- #expect(result.status == 0, "cfw.py patch-mobileactivationd failed: \(result.output)")
- return result.output
- }
+}
- /// Re-attest `offsets` in `file` with the Python code-signature module —
- /// the step `cfw_patch_mobileactivationd.py` leaves to the `ldid_sign` that
- /// follows it in `cfw_install.sh`.
- @discardableResult
- static func runPythonReattest(on file: URL, offsets: [Int]) throws -> String {
- let script = """
- import sys
- sys.path.insert(0, "scripts")
- from patchers.cfw_macho_codesign import reattest_modified_offsets
- reattest_modified_offsets(sys.argv[1], [int(a, 0) for a in sys.argv[2:]])
- """
- let result = try run(python, ["-c", script, file.path] + offsets.map { "0x" + String($0, radix: 16) })
- #expect(result.status == 0, "cfw_macho_codesign failed: \(result.output)")
- return result.output
- }
+// MARK: - The frozen reference
+
+/// What `scripts/patchers/` produced on this fixture, recorded before it was
+/// deleted.
+///
+/// Every value below was taken at repo commit `78cbeea`, with
+/// `.venv/bin/python3` driving `scripts/patchers/`, over the real iOS 27.0 /
+/// 24A435 / iPhone17,3 `mobileactivationd` whose own digest is ``pristine``.
+enum MobileactivationdGolden {
+ /// `shasum -a 256 ipsws/ref_extract/macho_pristine/mobileactivationd`
+ static let pristine = "89233513ce696cd01285f3432f3bcadd065cee07ac73bc5714836d13f24702d8"
+
+ /// `.venv/bin/python3 scripts/patchers/cfw.py patch-mobileactivationd <clone>`
+ /// — `ldrb w0, [x0, #0x14] ; ret` at 0x2EC368 replaced with
+ /// `mov x0, #1 ; ret`, signature left stale, exactly as `cfw_install.sh`
+ /// ran it before `ldid_sign`. Its stdout reported
+ /// `Found via symtab: va:0x1002EC368 -> foff:0x2EC368`.
+ static let patched = "9f26bf92a2a80133e763c6426949e262ad26d51485b5184548744bd37e1f4095"
+
+ /// The IMP the Python's symbol-table anchor resolved to, from that stdout.
+ static let impFileOffset = 0x2E_C368
+
+ /// ``patched``, then
+ /// `.venv/bin/python3 -c 'import sys; sys.path.insert(0, "scripts");
+ /// from patchers.cfw_macho_codesign import reattest_modified_offsets;
+ /// reattest_modified_offsets(sys.argv[1], [0x2ec368, 0x2ec36c])'`
+ /// — which reported `wrote cd_index=0 slot 748 (907503ed.. -> 2ea7d714..)`.
+ static let patchedAndReattested =
+ "df16f1ab4f5e7a3ad7a3a8774d54c0330a1b38d9568ad233e20936e48674973f"
+
+ /// The one code slot that re-attestation rewrote.
+ static let reattestedSlot = 748
}
// MARK: - Shell Runner
@@ -123,12 +139,13 @@ enum MobileactivationdFixture {
/// ```
///
/// patches that one file in place and prints where it landed. It exists so the
-/// comparison against the Python, and the run-it-twice check, can be driven
-/// from a shell over files a human picked — rather than living only inside
+/// comparison against ``MobileactivationdGolden``, and the run-it-twice check,
+/// can be driven from a shell over files a human picked — `shasum -a 256` on
+/// the result reads the same digests — rather than living only inside
/// assertions this same process wrote. Without the variable it does not run.
///
-/// `VPHONE_PATCH_RESIGN=0` skips re-attestation, which is what reproduces the
-/// Python's bytes exactly.
+/// `VPHONE_PATCH_RESIGN=0` skips re-attestation, which is what reproduces
+/// ``MobileactivationdGolden/patched`` exactly.
@Suite("mobileactivationd should_hactivate — shell runner")
struct CFWMobileactivationdRunnerTests {
@Test(.enabled(if: ProcessInfo.processInfo.environment["VPHONE_PATCH_FILE"] != nil))
@@ -191,9 +208,11 @@ struct CFWMobileactivationdAnchorTests {
/// The selector search must not settle for a suffix of a longer string.
///
/// `DeviceType`'s ivar is `_should_hactivate`, so a plain search for
- /// `should_hactivate\0` — what the Python does — lands inside the ivar's
- /// name, finds no selref for it, and gives up. The NUL-preceded match finds
- /// the real selector instead.
+ /// `should_hactivate\0` — what `scripts/patchers/cfw_patch_mobileactivationd.py`
+ /// did at 78cbeea — lands inside the ivar's name, finds no selref for it,
+ /// and gives up. The NUL-preceded match finds the real selector instead.
+ /// The naive search is reproduced below rather than described, so the
+ /// contrast is measured here and does not depend on that Python existing.
@Test(.enabled(if: MobileactivationdFixture.hasPristine))
func selectorLookupSkipsTheIvarName() throws {
let data = try Data(contentsOf: MobileactivationdFixture.pristine)
@@ -207,8 +226,8 @@ struct CFWMobileactivationdAnchorTests {
let offset = start + Int(selectorVA - methname.address)
#expect(data[offset - 1] == 0, "the selector must start a string, not end one")
- // The naive search the Python performs finds an earlier, wrong offset on
- // this binary — so this is not an assertion that passes either way.
+ // That naive search finds an earlier, wrong offset on this binary — so
+ // this is not an assertion that passes either way.
let needle = Data(CFWMobileactivationd.selector.utf8) + Data([0])
let naive = try #require(data.range(of: needle)?.lowerBound)
#expect(naive < offset)
@@ -261,70 +280,83 @@ struct CFWMobileactivationdAnchorTests {
}
}
-// MARK: - Byte parity with the Python
+// MARK: - Byte parity with the frozen reference
@Suite("mobileactivationd should_hactivate — parity and idempotence")
struct CFWMobileactivationdParityTests {
+ /// The fixture the frozen digests were taken over. Without this a digest
+ /// mismatch below would read as a patcher bug when the real cause is a
+ /// different firmware's `mobileactivationd`.
+ @Test(.enabled(if: MobileactivationdFixture.hasPristine))
+ func fixtureMatchesTheGoldens() throws {
+ #expect(
+ try MobileactivationdFixture.digest(of: MobileactivationdFixture.pristine)
+ == MobileactivationdGolden.pristine,
+ """
+ this is not the 24A435 mobileactivationd MobileactivationdGolden \
+ was recorded from — re-derive the goldens before reading a failure \
+ below as a patcher bug
+ """
+ )
+ }
+
/// Bar 1: identical bytes out of identical bytes in, against the
- /// implementation being replaced.
+ /// implementation that was replaced.
///
- /// `resign: false` because the Python patcher does not re-sign — the
+ /// `resign: false` because the Python patcher did not re-sign — the
/// `ldid_sign` in `cfw_install.sh` does — so this compares like with like.
- @Test(.enabled(if: MobileactivationdFixture.hasPythonReference))
- func matchesThePythonByteForByte() throws {
+ @Test(.enabled(if: MobileactivationdFixture.hasPristine))
+ func matchesTheFrozenReferenceBytes() throws {
let swiftFile = try MobileactivationdFixture.copyOfPristine(named: "swift.bin")
- let pythonFile = try MobileactivationdFixture.copyOfPristine(named: "python.bin")
let report = try CFWMobileactivationd.patch(fileAt: swiftFile, resign: false, log: nil)
- try MobileactivationdFixture.runPythonPatcher(on: pythonFile)
#expect(report.outcome == .patched)
#expect(report.sitesWritten == 1)
#expect(report.slotRehashes.isEmpty, "resign: false must not touch the signature")
+ #expect(
+ try MobileactivationdFixture.digest(of: swiftFile) == MobileactivationdGolden.patched,
+ "Swift output must be byte-identical to the reference's"
+ )
- let swiftBytes = try Data(contentsOf: swiftFile)
- let pythonBytes = try Data(contentsOf: pythonFile)
- #expect(swiftBytes == pythonBytes, "Swift and Python output must be byte-identical")
-
- // And the one site they both changed is the one this patch claims.
+ // And the one site it changed is the one the reference's symtab anchor
+ // named, and the one this patch claims.
let record = try #require(report.record)
let pristine = try Data(contentsOf: MobileactivationdFixture.pristine)
- let differing = (0 ..< pristine.count).filter { pythonBytes[$0] != pristine[$0] }
+ let patched = try Data(contentsOf: swiftFile)
+ let differing = (0 ..< pristine.count).filter { patched[$0] != pristine[$0] }
+ #expect(!differing.isEmpty)
#expect(differing.allSatisfy { record.fileOffset ..< record.fileOffset + 8 ~= $0 })
+ #expect(record.fileOffset == MobileactivationdGolden.impFileOffset)
#expect(record.patchID == "mobileactivationd.should_hactivate")
#expect(record.component == "mobileactivationd")
#expect(record.patchedBytes == ARM64.movX0_1 + ARM64.ret)
#expect(record.beforeDisasm.hasSuffix("ret"))
}
- /// Bar 2: the re-attested output matches the Python's own re-attestation,
- /// slot hash for slot hash, and `codesign -v` accepts it.
+ /// Bar 2: the re-attested output matches the reference's own
+ /// re-attestation, slot hash for slot hash, and `codesign -v` accepts it.
///
/// The raw patch does not: `codesign` rejects it, which is what makes this
/// step load-bearing rather than decorative.
- @Test(.enabled(if: MobileactivationdFixture.hasPythonReference && MobileactivationdFixture.hasCodesign))
- func reattestedOutputMatchesThePythonAndVerifies() throws {
+ @Test(.enabled(if: MobileactivationdFixture.hasCodesign))
+ func reattestedOutputMatchesTheFrozenReferenceAndVerifies() throws {
let swiftFile = try MobileactivationdFixture.copyOfPristine(named: "swift-resigned.bin")
- let pythonFile = try MobileactivationdFixture.copyOfPristine(named: "python-resigned.bin")
let report = try CFWMobileactivationd.patch(fileAt: swiftFile, resign: true, log: nil)
let rehash = try #require(report.slotRehashes.first)
#expect(report.slotRehashes.count == 1)
-
- try MobileactivationdFixture.runPythonPatcher(on: pythonFile)
- try MobileactivationdFixture.runPythonReattest(
- on: pythonFile,
- offsets: CFWMobileactivationd.touchedOffsets(report.anchor, ARM64.movX0_1 + ARM64.ret)
- )
+ #expect(rehash.pageIndex == MobileactivationdGolden.reattestedSlot)
let swiftBytes = try Data(contentsOf: swiftFile)
- let pythonBytes = try Data(contentsOf: pythonFile)
- #expect(swiftBytes == pythonBytes, "re-attested output must match the Python's")
+ #expect(
+ Data(SHA256.hash(data: swiftBytes)).hex == MobileactivationdGolden.patchedAndReattested,
+ "re-attested output must match the reference's"
+ )
- // The slot hash itself, not just the file: read it back out of both.
+ // The slot hash itself, not just the file: read it back out.
let slot = rehash.hashFileOffset ..< rehash.hashFileOffset + rehash.after.count
#expect(swiftBytes[slot] == rehash.after)
- #expect(pythonBytes[slot] == rehash.after)
let verified = try MobileactivationdFixture.run(
MobileactivationdFixture.codesign, ["-v", swiftFile.path]
@@ -364,9 +396,10 @@ struct CFWMobileactivationdParityTests {
#expect(try Data(contentsOf: file) == afterFirst)
}
- /// A patched-but-not-re-attested binary — what the Python leaves behind —
- /// is repaired on the next run rather than reported as already done and
- /// left to be SIGKILLed on first page-in.
+ /// A patched-but-not-re-attested binary — what the Python left behind, and
+ /// what ``MobileactivationdGolden/patched`` is the digest of — is repaired
+ /// on the next run rather than reported as already done and left to be
+ /// SIGKILLed on first page-in.
@Test(.enabled(if: MobileactivationdFixture.hasPristine))
func rerunRepairsAStaleSlot() throws {
let file = try MobileactivationdFixture.copyOfPristine(named: "swift-stale-slot.bin")
diff --git a/tests/FirmwarePatcherTests/CFWPlistPatchTests.swift b/tests/FirmwarePatcherTests/CFWPlistPatchTests.swift
index 6bb4620e..3a246a97 100644
--- a/tests/FirmwarePatcherTests/CFWPlistPatchTests.swift
+++ b/tests/FirmwarePatcherTests/CFWPlistPatchTests.swift
@@ -1,27 +1,90 @@
// CFWPlistPatchTests.swift — the three P1.4 CFW patchers, against the Python
-// they replace.
+// they replaced.
//
// 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.
+// equivalence tests are the ones that matter: `scripts/patchers/<name>.py` was
+// run over the same real input the Swift gets, and what it produced is frozen
+// in ``CFWPlistPatchGolden`` below — semantically for the two plist patchers,
+// byte for byte for the device tree.
//
// Real input, never a hand-made stand-in:
// - the host's own /System/Library/CoreServices/SystemVersion.plist
// - a real entitlements plist dumped from a signed system binary
// - DeviceTree.vphone600ap.im4p, pulled out of the cloudOS IPSW
//
-// 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.
+// The first two are host-dependent: their bytes differ with every macOS build,
+// so a frozen digest of the *output* would say nothing. For those the frozen
+// value is the transform the Python applied, read off its output by diffing it
+// against its own input. The device tree is fixed inside its IPSW, so that one
+// is a digest, per IPSW.
+//
+// Every equivalence test is gated on its input, and skips rather than fails
+// when it is absent — but a skip is not a pass, and the migration notes record
+// which ones actually ran.
+import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Img4tool
import Testing
-// MARK: - Fixtures and the Python reference
+// MARK: - The frozen reference
+
+/// What `scripts/patchers/` produced on these inputs, recorded before it was
+/// deleted. Measured at repo commit `78cbeea` with `.venv/bin/python3`.
+enum CFWPlistPatchGolden {
+ /// `.venv/bin/python3 scripts/patchers/cfw_patch_build_version.py \
+ /// <copy of /System/Library/CoreServices/SystemVersion.plist> 23F77`
+ ///
+ /// Run over both `plutil -convert xml1` and `-convert binary1` copies. On
+ /// this host it printed `ProductBuildVersion '26A428' -> '23F77'` and,
+ /// diffing its output against its input, the ONLY difference was that one
+ /// key's value; the serialized format stayed what it went in as (the XML
+ /// copy came back starting `<?xml ve`, the binary one `bplist00`).
+ ///
+ /// The input is the host's own file, which differs with every macOS build,
+ /// so the frozen value is that transform, not a digest.
+ static let buildVersionTarget = "23F77"
+
+ /// `.venv/bin/python3 scripts/patchers/campo_mach_lookup_exceptions.py \
+ /// <entitlements dumped from a signed host binary>`
+ ///
+ /// Diffing its output against its input: the only key it touched was
+ /// ``exceptionKey``, and its new value was the existing array followed by
+ /// every service from the module's own `SERVICES` list not already in it,
+ /// in `SERVICES` order. On Safari (3 unrelated entries already present) it
+ /// printed `count: 20 (+17 added)`; on loginwindow (key absent) `count: 17
+ /// (+17 added)`.
+ static let exceptionKey = "com.apple.security.exception.mach-lookup.global-name"
+ static func countLine(total: Int, added: Int) -> String {
+ "count: \(total) (+\(added) added)"
+ }
+
+ /// `.venv/bin/python3 scripts/patchers/cfw_patch_post_restore_dt.py \
+ /// <copy of Firmware/all_flash/DeviceTree.vphone600ap.im4p>`
+ ///
+ /// Byte for byte, input digest to output digest. Two cloudOS IPSWs carry
+ /// this device tree and they are not the same file, so both pairs are here;
+ /// the test looks its input up by digest rather than assuming which IPSW
+ /// `contentsOfDirectory` hands back first. Both runs reported the same
+ /// three rewrites, and a second run printed
+ /// `DT already in target state — no change` and left the bytes alone.
+ static let deviceTree: [String: String] = [
+ // EmbeddedDeviceTrees-11156.42.1, 68380-byte DT blob
+ "df0e5ceb010ae028b6e9a3322a07379a30911ee48f385cfe23f6931896cd096a":
+ "24894ac42dc218844d1988b6fe76e45d3ef9b8506ae08f11ecd01e7a6819a38b",
+ // EmbeddedDeviceTrees-11156.100.653.0.1, 68480-byte DT blob
+ "987a9306d16a9047dc1b46fd1b3cec2aab7738aff6c5c86938ee3ada1a461e3c":
+ "ca7386a775e8e2e7b1e242ef965ffcd644c35e545aba49182e15932257b6ba91",
+ ]
+
+ /// SHA-256 as `shasum -a 256` prints it.
+ static func digest(of url: URL) throws -> String {
+ Data(SHA256.hash(data: try Data(contentsOf: url))).hex
+ }
+}
+
+// MARK: - Fixtures
enum CFWPatchFixtures {
/// tests/FirmwarePatcherTests/<this file> → repo root.
@@ -30,9 +93,6 @@ enum CFWPatchFixtures {
.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")
@@ -49,18 +109,6 @@ enum CFWPatchFixtures {
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)
}
@@ -149,11 +197,6 @@ enum CFWPatchFixtures {
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)")
@@ -327,33 +370,29 @@ struct CFWBuildVersionTests {
}
}
- @Test(.enabled(if: CFWPatchFixtures.canRun("cfw_patch_build_version.py")
- && CFWPatchFixtures.systemVersionAvailable))
- func matchesPythonOnARealSystemVersionPlist() throws {
+ @Test(.enabled(if: CFWPatchFixtures.systemVersionAvailable))
+ func matchesTheFrozenReferenceOnARealSystemVersionPlist() throws {
let directory = try CFWPatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
+ let target = CFWPlistPatchGolden.buildVersionTarget
// Both plist encodings of the same real file: the rootfs copy is XML,
// the Cryptex copy on a device can be binary.
for format in ["xml1", "binary1"] {
- let 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)
- )
+ try CFWPatchFixtures.copyContents(of: CFWPatchFixtures.systemVersionPlist, to: swiftOutput)
+ try CFWPatchFixtures.run("/usr/bin/plutil", ["-convert", format, swiftOutput.path])
+
+ let before = try #require(try PlistComparison.load(swiftOutput) as? [String: Any])
+ try CFWBuildVersion.patch(at: swiftOutput, to: target, verbose: false)
+ let after = try #require(try PlistComparison.load(swiftOutput) as? [String: Any])
+
+ // The transform the reference applied: that one key's value, and
+ // nothing else in the file.
+ #expect(after["ProductBuildVersion"] as? String == target)
+ var expected = after
+ expected["ProductBuildVersion"] = before["ProductBuildVersion"]
+ let difference = PlistComparison.difference(before, expected)
#expect(difference == nil, "\(format): \(difference ?? "")")
// The format the file went in as is the format it comes back as.
@@ -428,31 +467,42 @@ struct CFWMachLookupExceptionTests {
}
}
- @Test(.enabled(if: CFWPatchFixtures.canRun("campo_mach_lookup_exceptions.py")
- && CFWPatchFixtures.entitlementsDonorAvailable))
- func matchesPythonOnRealEntitlements() throws {
+ @Test(.enabled(if: CFWPatchFixtures.entitlementsDonorAvailable))
+ func matchesTheFrozenReferenceOnRealEntitlements() throws {
let directory = try CFWPatchFixtures.makeTemporaryDirectory()
defer { try? FileManager.default.removeItem(at: directory) }
+ let key = CFWPlistPatchGolden.exceptionKey
+ #expect(CFWMachLookupExceptions.exceptionKey == key)
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)
+ try CFWPatchFixtures.dumpEntitlements(of: donor, to: swiftOutput)
- let python = try CFWPatchFixtures.runPython(
- "campo_mach_lookup_exceptions.py",
- [pythonOutput.path]
- )
- #expect(python.status == 0, "python: \(python.combined)")
+ let before = try #require(try PlistComparison.load(swiftOutput) as? [String: Any])
+ let existing = (before[key] as? [String]) ?? []
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)
+ let after = try #require(try PlistComparison.load(swiftOutput) as? [String: Any])
+
+ // The transform the reference applied: the existing array, then
+ // every service it did not already carry, in SERVICES order.
+ let expectedServices = existing
+ + CFWMachLookupExceptions.services.filter { !existing.contains($0) }
+ #expect(after[key] as? [String] == expectedServices, "\(name)")
+ // …and its own count line agreed with that arithmetic.
+ #expect(
+ CFWPlistPatchGolden.countLine(total: outcome.total, added: outcome.added)
+ == CFWPlistPatchGolden.countLine(
+ total: expectedServices.count,
+ added: expectedServices.count - existing.count
+ ),
+ "\(name)"
)
+
+ // Nothing but that key moved.
+ var expected = after
+ if let original = before[key] { expected[key] = original } else { expected[key] = nil }
+ let difference = PlistComparison.difference(before, expected)
#expect(difference == nil, "\(name): \(difference ?? "")")
}
}
@@ -563,34 +613,41 @@ struct CFWPostRestoreDeviceTreeTests {
#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 {
+ @Test(.enabled(if: CFWPatchFixtures.deviceTreeAvailable))
+ func matchesTheFrozenReferenceByteForByteOnARealDeviceTree() 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")
+ // Two cloudOS IPSWs carry this device tree and they are different
+ // files, so the golden is looked up by the input's own digest rather
+ // than by which IPSW the directory listing happened to hand back.
+ let input = try CFWPlistPatchGolden.digest(of: source)
+ let expected = try #require(
+ CFWPlistPatchGolden.deviceTree[input],
+ """
+ no frozen reference output for a DeviceTree.vphone600ap.im4p with \
+ digest \(input) — re-derive CFWPlistPatchGolden.deviceTree for this \
+ IPSW before reading a failure here as a patcher bug
+ """
+ )
+
let swiftOutput = directory.appending(path: "swift.im4p")
- try FileManager.default.copyItem(at: source, to: 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)
+ #expect(
+ try CFWPlistPatchGolden.digest(of: swiftOutput) == expected,
+ "IM4P differs from the frozen reference output"
+ )
- 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"))
+ // And the re-run is a no-op, as the reference's was: it printed
+ // `DT already in target state — no change` and the digest held.
let swiftRerun = try CFWPostRestoreDeviceTree.patch(at: swiftOutput, verbose: false)
#expect(!swiftRerun.wrote)
- #expect(try Data(contentsOf: swiftOutput) == swiftBytes)
+ #expect(try CFWPlistPatchGolden.digest(of: swiftOutput) == expected)
}
/// The IMG4 path, as far as it can be checked here.
diff --git a/tests/FirmwarePatcherTests/CFWSeputilTests.swift b/tests/FirmwarePatcherTests/CFWSeputilTests.swift
index 48af6c23..8c0f4f59 100644
--- a/tests/FirmwarePatcherTests/CFWSeputilTests.swift
+++ b/tests/FirmwarePatcherTests/CFWSeputilTests.swift
@@ -4,18 +4,20 @@
// them rather than against a number written down by hand:
//
// * `scripts/patchers/cfw_patch_seputil.py`, driven through the exact CLI
-// `scripts/cfw_install.sh` calls — `cfw.py patch-seputil <binary>`. The
-// Swift patcher run with `reattest: false` must produce that file byte for
-// byte, and run with re-attestation on it must equal the Python's output
-// put through the Python's own re-attester
-// (`cfw_macho_codesign.reattest_modified_offsets`). The second comparison
-// is what proves the slot hashes agree: they are compared as bytes in the
-// file, not as values this module reported about itself.
+// `scripts/cfw_install.sh` called — `cfw.py patch-seputil <binary>`. That
+// Python is gone; what it produced on this fixture is frozen in
+// ``SeputilGolden`` below, digest by digest, so the comparison survives it.
+// The Swift patcher run with `reattest: false` must reproduce the digest of
+// the file the Python wrote, and run with re-attestation on it must
+// reproduce the digest of that same file put through the Python's own
+// re-attester (`cfw_macho_codesign.reattest_modified_offsets`). The second
+// digest is what proves the slot hashes agree: it covers the hashes where
+// they live, in the file, not values this module reported about itself.
// * `/usr/bin/codesign -v`, which for a standalone Mach-O is a real second
// opinion on whether the signature still covers the file. The test asserts
// both directions — the re-attested binary verifies and the one that
-// matches the Python does not — so a `codesign` that passed everything
-// would fail this suite instead of quietly blessing it.
+// matches the frozen Python digest does not — so a `codesign` that passed
+// everything would fail this suite instead of quietly blessing it.
//
// The fixture is the real 24A435 / iPhone17,3 `seputil`. Point
// `VPHONE_MACHO_PRISTINE` at a directory of pristine Mach-O binaries or leave
@@ -74,21 +76,16 @@ private enum SeputilFixture {
static let skipReason: Comment =
"VPHONE_MACHO_FIXTURE_OPTIONAL=1 and no macho_pristine/seputil fixture present"
- static let venvMissing: Comment = """
- the project venv is required: these tests are a comparison against \
- scripts/patchers/cfw_patch_seputil.py, and without it there is nothing to \
- compare against — run `make setup_venv`
- """
-
/// Where clones are made. Same filesystem as the repo, and deliberately
/// *not* under `ipsws/ref_extract/`.
static var scratchRoot: URL {
repoRoot.appendingPathComponent("ipsws/scratch_cfwseputil")
}
- static var python: URL? {
- let url = repoRoot.appendingPathComponent(".venv/bin/python3")
- return FileManager.default.fileExists(atPath: url.path) ? url : nil
+ /// SHA-256 as `shasum -a 256` prints it, so a digest asserted here can be
+ /// taken again from a shell over the same file.
+ static func digest(of url: URL) throws -> String {
+ Data(SHA256.hash(data: try Data(contentsOf: url))).hex
}
static var codesign: URL? {
@@ -165,106 +162,108 @@ private enum Subprocess {
}
}
-// MARK: - The reference Python, driven through its real CLI
-
-private enum PythonReference {
- /// `cfw.py patch-seputil <binary>` — what `cfw_install.sh` runs.
- @discardableResult
- static func patch(_ binary: URL) throws -> String {
- let python = try #require(SeputilFixture.python, SeputilFixture.venvMissing)
- let result = try Subprocess.run(executable: python, arguments: [
- SeputilFixture.repoRoot.appendingPathComponent("scripts/patchers/cfw.py").path,
- "patch-seputil",
- binary.path,
- ])
- guard result.status == 0 else {
- Issue.record("cfw.py patch-seputil failed: \(result.stdout)\(result.stderr)")
- throw CocoaError(.fileWriteUnknown)
- }
- return result.stdout
- }
-
- /// `cfw_macho_codesign.reattest_modified_offsets` — the independent
- /// re-attester, so the slot hashes this suite compares against are the
- /// Python's own and not a second copy of the Swift maths.
- static func reattest(_ binary: URL, offsets: [Int]) throws {
- let python = try #require(SeputilFixture.python, SeputilFixture.venvMissing)
- let script = """
- import sys
- sys.path.insert(0, "scripts/patchers")
- import cfw_macho_codesign as ref
- ref.reattest_modified_offsets(sys.argv[1], [int(a) for a in sys.argv[2:]], verbose=False)
- """
- let process = Process()
- process.executableURL = python
- process.arguments = ["-c", script, binary.path] + offsets.map(String.init)
- process.currentDirectoryURL = SeputilFixture.repoRoot
- let pipe = Pipe()
- process.standardOutput = pipe
- process.standardError = pipe
- try process.run()
- let output = pipe.fileHandleForReading.readDataToEndOfFile()
- process.waitUntilExit()
- try #require(
- process.terminationStatus == 0,
- "reference re-attester failed: \(String(decoding: output, as: UTF8.self))"
- )
- }
+// MARK: - The frozen reference
+
+/// What `scripts/patchers/` produced on this fixture, recorded before it was
+/// deleted.
+///
+/// Every digest below was taken at repo commit `78cbeea`, with
+/// `.venv/bin/python3` driving `scripts/patchers/`, over the real iOS 27.0 /
+/// 24A435 / iPhone17,3 `seputil` whose own digest is ``pristine``. The exact
+/// command that produced each one is on the constant.
+private enum SeputilGolden {
+ /// `shasum -a 256 ipsws/ref_extract/macho_pristine/seputil`
+ static let pristine = "13e40e74d92928cf9e36fae75970dfcf4c0a4c1040eeac39d1c335407e841474"
+
+ /// `.venv/bin/python3 scripts/patchers/cfw.py patch-seputil <clone of seputil>`
+ /// — the patch alone, signature left stale, which is what `cfw_install.sh`
+ /// ran before handing the file to `ldid_sign`.
+ static let patched = "75dc86f8d0668e5d06ce90111f416c058a0e57f21fa55e5f6330f67ec8d0e8b2"
+
+ /// The bytes the Python changed, from a byte diff of ``patched`` against
+ /// ``pristine``: `%s` -> `AA` at 0x1BDD2, and nothing else in the file.
+ static let modifiedOffsets = [0x1_BDD2, 0x1_BDD3]
+
+ /// ``patched``, then
+ /// `.venv/bin/python3 -c 'import sys; sys.path.insert(0, "scripts/patchers");
+ /// import cfw_macho_codesign as r;
+ /// r.reattest_modified_offsets(sys.argv[1], [114130, 114131], verbose=True)'`
+ /// — which reported `wrote cd_index=0 slot 27 (345f649b.. -> a6df3073..)`.
+ static let patchedAndReattested =
+ "01b4dd86b44c867dc9d94339eea34dcf64de37e7dbd85997f040831dca6afd0b"
+
+ /// The one code slot that re-attestation rewrote.
+ static let reattestedSlot = 27
}
// MARK: - Parity against the reference implementations
@Suite("seputil gigalocker name", .enabled(if: SeputilFixture.runs, SeputilFixture.skipReason))
struct CFWSeputilParityTests {
+ /// The fixture the frozen digests were taken over. Without this the two
+ /// tests below would report a digest mismatch when the real cause is a
+ /// different firmware's `seputil`.
+ @Test func fixtureIsTheOneTheGoldensWereTakenFrom() throws {
+ let pristine = try #require(SeputilFixture.pristine, SeputilFixture.missing)
+ #expect(
+ try SeputilFixture.digest(of: pristine) == SeputilGolden.pristine,
+ """
+ this is not the 24A435 iPhone17,3 seputil the goldens in \
+ SeputilGolden were recorded from — re-derive them before reading a \
+ failure below as a patcher bug
+ """
+ )
+ }
+
/// The plan's P1.2 gate: same input, same bytes out.
///
- /// Run with `reattest: false`, which is the reference's own behaviour —
- /// `cfw_install.sh` re-signs with `ldid` right after, so the Python leaves
+ /// Run with `reattest: false`, which was the reference's own behaviour —
+ /// `cfw_install.sh` re-signs with `ldid` right after, so the Python left
/// the signature stale.
- @Test func matchesTheReferencePatcherByteForByte() throws {
+ @Test func matchesTheFrozenReferencePatch() throws {
let pristine = try #require(SeputilFixture.pristine, SeputilFixture.missing)
let swiftFile = try SeputilFixture.clone(named: "swift-plain")
- let pythonFile = try SeputilFixture.clone(named: "python-plain")
- defer { SeputilFixture.discard(swiftFile, pythonFile) }
+ defer { SeputilFixture.discard(swiftFile) }
let outcome = try CFWSeputil.patch(fileAt: swiftFile, reattest: false, log: nil)
- try PythonReference.patch(pythonFile)
#expect(outcome.verdict == .patched)
#expect(
- try Data(contentsOf: swiftFile) == (try Data(contentsOf: pythonFile)),
- "Swift and Python must produce the same seputil, byte for byte"
+ try SeputilFixture.digest(of: swiftFile) == SeputilGolden.patched,
+ "Swift must reproduce the seputil the reference wrote, byte for byte"
)
+ // The same two bytes, at the same two offsets, that the reference moved.
+ #expect(outcome.site.modifiedOffsets == SeputilGolden.modifiedOffsets)
- // And the comparison is not two copies of the input: both moved.
+ // And the comparison is not two copies of the input: the file moved.
+ #expect(try SeputilFixture.digest(of: swiftFile) != SeputilGolden.pristine)
#expect(try Data(contentsOf: swiftFile) != (try Data(contentsOf: pristine)))
}
/// The same for the whole pipeline, re-attestation included. The Python
- /// has no re-attesting seputil patcher, so the reference side is composed
- /// from the two Python modules the install script composes at runtime.
+ /// had no re-attesting seputil patcher, so the frozen digest is of the two
+ /// Python modules composed the way the install script composed them.
///
- /// This is the slot-hash comparison: the hashes are compared where they
- /// live, in the file, against hashes the reference implementation computed.
- @Test func matchesTheReferencePlusItsOwnReattester() throws {
+ /// This is the slot-hash comparison: the hashes are covered where they
+ /// live, in the file, by a digest of what the reference implementation
+ /// computed.
+ @Test func matchesTheFrozenReferencePlusItsOwnReattester() throws {
let swiftFile = try SeputilFixture.clone(named: "swift-full")
- let pythonFile = try SeputilFixture.clone(named: "python-full")
- defer { SeputilFixture.discard(swiftFile, pythonFile) }
+ defer { SeputilFixture.discard(swiftFile) }
let outcome = try CFWSeputil.patch(fileAt: swiftFile, log: nil)
- try PythonReference.patch(pythonFile)
- try PythonReference.reattest(pythonFile, offsets: outcome.site.modifiedOffsets)
#expect(outcome.rehashes.count == 1, "one page was dirtied, so one slot is rewritten")
+ #expect(outcome.rehashes.first?.pageIndex == SeputilGolden.reattestedSlot)
#expect(
- try Data(contentsOf: swiftFile) == (try Data(contentsOf: pythonFile)),
- "the re-attested slot hash must be the one the reference computes"
+ try SeputilFixture.digest(of: swiftFile) == SeputilGolden.patchedAndReattested,
+ "the re-attested slot hash must be the one the reference computed"
)
}
/// `codesign -v`, in both directions. The re-attested binary verifies; the
- /// one that reproduces the Python's bytes does not, which is why
- /// `cfw_install.sh` has to run `ldid_sign` after the Python.
+ /// one that reproduces the frozen Python bytes does not, which is why
+ /// `cfw_install.sh` had to run `ldid_sign` after the Python.
@Test func reattestationIsWhatMakesTheBinaryVerify() throws {
let codesign = try #require(SeputilFixture.codesign)
let pristine = try #require(SeputilFixture.pristine, SeputilFixture.missing)
diff --git a/tests/FirmwarePatcherTests/CFWWatchdogdTests.swift b/tests/FirmwarePatcherTests/CFWWatchdogdTests.swift
index d376769a..bf4b9980 100644
--- a/tests/FirmwarePatcherTests/CFWWatchdogdTests.swift
+++ b/tests/FirmwarePatcherTests/CFWWatchdogdTests.swift
@@ -1,13 +1,14 @@
// CFWWatchdogdTests.swift — parity, anchoring and idempotence for the
// watchdogd hv_vmm_present cache patch.
//
-// Two independent references are available for this patch and both are used:
+// Two independent references were available for this patch and both are used:
//
// * `scripts/patchers/cfw_patch_watchdogd.py`, driven exactly as
-// `cfw_install_exp.sh` drives it (`cfw.py patch-watchdogd <binary>`). The
-// central test runs it and `CFWWatchdogd` over two clones of the same
-// pristine binary and compares the results byte for byte — patched
-// instructions and re-attested code slots alike.
+// `cfw_install_exp.sh` drove it (`cfw.py patch-watchdogd <binary>`). That
+// Python is gone; what it wrote over the pristine binary is frozen in
+// ``WatchdogdGolden`` below, and the central test grades `CFWWatchdogd`
+// against it byte for byte — patched instructions and re-attested code
+// slots alike, because that verb re-attested on its own.
// * `/usr/bin/codesign`, which recomputes the slot hashes itself. It has no
// part in this code, so a binary that verifies under it is evidence the
// re-attestation is right rather than self-consistent.
@@ -39,8 +40,6 @@ enum WatchdogdFixture {
/// negative case.
static let seputil = pristineDirectory.appending(path: "seputil")
- static let python = repositoryRoot.appending(path: ".venv/bin/python3")
- static let cfwCLI = repositoryRoot.appending(path: "scripts/patchers/cfw.py")
static let codesign = URL(filePath: "/usr/bin/codesign")
static func exists(_ url: URL) -> Bool { FileManager.default.fileExists(atPath: url.path) }
@@ -51,7 +50,6 @@ enum WatchdogdFixture {
static var hasWatchdogd: Bool { exists(watchdogd) }
static var hasSeputil: Bool { exists(seputil) }
- static var hasPythonReference: Bool { hasWatchdogd && exists(python) && exists(cfwCLI) }
static var hasCodesign: Bool { hasWatchdogd && exists(codesign) }
/// A private copy of `source` the caller may modify freely. Deliberately
@@ -112,6 +110,38 @@ enum WatchdogdFixture {
}
}
+// MARK: - The frozen reference
+
+/// What `scripts/patchers/` produced on this fixture, recorded before it was
+/// deleted.
+///
+/// Every value below was taken at repo commit `78cbeea`, with
+/// `.venv/bin/python3` driving `scripts/patchers/`, over the real iOS 27.0 /
+/// 24A435 / iPhone17,3 `/usr/libexec/watchdogd` whose own digest is
+/// ``pristine``.
+enum WatchdogdGolden {
+ /// `shasum -a 256 ipsws/ref_extract/macho_pristine/watchdogd`
+ static let pristine = "0309b868a214f9841279db3e2ef901f26e8c05b2dc616eeb551f2b2f0e06207f"
+
+ /// `.venv/bin/python3 scripts/patchers/cfw.py patch-watchdogd <clone>`
+ ///
+ /// Unlike the other CFW Mach-O verbs, this one re-attested on its own:
+ /// stdout ended `wrote 2 site(s)` and then
+ /// `re-attest updated 2 slot(s) across 2 unique (CD, page) pair(s)`,
+ /// rewriting slots 4 and 10 (`4f3c398a.. -> f287fa91..` and
+ /// `75fa0b5a.. -> ff44ac69..`). So this digest covers both halves.
+ static let patched = "963cd44591763ac928f7fb9fab0e50e573bc456e5efe9c17e96fe8d220494b13"
+
+ /// The two code slots that run re-attested.
+ static let reattestedSlots = [4, 10]
+
+ /// `cfw.py patch-watchdogd` run a SECOND time over ``patched``: it printed
+ /// `all 2 matching site(s) already patched — nothing to do` and left the
+ /// file byte for byte alone, so the digest is ``patched`` again. Both
+ /// implementations agree that a patched binary needs nothing done to it.
+ static let patchedTwice = patched
+}
+
// MARK: - Anchoring
@Suite("watchdogd hv_vmm_present cache — anchoring")
@@ -391,54 +421,64 @@ struct CFWWatchdogdPatchTests {
@Suite("watchdogd hv_vmm_present cache — independent references")
struct CFWWatchdogdReferenceTests {
- /// The migration plan's gate for P1.2: the Swift patcher and the Python it
- /// replaces must produce the same bytes from the same input.
- @Test(.enabled(if: WatchdogdFixture.hasPythonReference))
- func matchesThePythonReferenceByteForByte() throws {
- let reference = try WatchdogdFixture.scratchCopy(
- of: WatchdogdFixture.watchdogd, named: "watchdogd-python"
+ /// The fixture the frozen digests were taken over. Without this a digest
+ /// mismatch below would read as a patcher bug when the real cause is a
+ /// different firmware's `watchdogd`.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func fixtureMatchesTheGoldens() throws {
+ #expect(
+ WatchdogdFixture.digest(try Data(contentsOf: WatchdogdFixture.watchdogd))
+ == WatchdogdGolden.pristine,
+ """
+ this is not the 24A435 watchdogd WatchdogdGolden was recorded from \
+ — re-derive the goldens before reading a failure below as a \
+ patcher bug
+ """
)
- defer { try? FileManager.default.removeItem(at: reference.deletingLastPathComponent()) }
-
- let result = try WatchdogdFixture.run(WatchdogdFixture.python, [
- WatchdogdFixture.cfwCLI.path, "patch-watchdogd", reference.path,
- ])
- #expect(result.status == 0, "reference patcher failed: \(result.output)")
+ }
+ /// The migration plan's gate for P1.2: the Swift patcher and the Python it
+ /// replaced must produce the same bytes from the same input.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func matchesTheFrozenReferenceByteForByte() throws {
var mine = try Data(contentsOf: WatchdogdFixture.watchdogd)
- try CFWWatchdogd.patch(&mine, log: nil)
+ let report = try CFWWatchdogd.patch(&mine, log: nil)
- let theirs = try Data(contentsOf: reference)
// Printed so the parity claim is checkable from outside this process:
- // `shasum -a 256` over either patcher's output has to read the same.
+ // `shasum -a 256` over this patcher's output has to read the same.
print("""
watchdogd parity: \
pristine=\(WatchdogdFixture.digest(try Data(contentsOf: WatchdogdFixture.watchdogd))) \
- python=\(WatchdogdFixture.digest(theirs)) \
+ golden=\(WatchdogdGolden.patched) \
swift=\(WatchdogdFixture.digest(mine))
""")
- #expect(mine.count == theirs.count)
- #expect(mine == theirs, "Swift and Python output must be identical")
+ #expect(report.sitesWritten == 2)
+ #expect(report.rehashedSlots.map(\.pageIndex).sorted() == WatchdogdGolden.reattestedSlots)
+ #expect(
+ WatchdogdFixture.digest(mine) == WatchdogdGolden.patched,
+ "Swift output must be identical to the frozen reference's"
+ )
}
- /// The Python's idempotent path, for the same reason: both implementations
- /// must agree that a patched binary needs nothing done to it.
- @Test(.enabled(if: WatchdogdFixture.hasPythonReference))
- func agreesWithThePythonOnAnAlreadyPatchedBinary() throws {
+ /// The reference's idempotent path, for the same reason: both
+ /// implementations agree that a patched binary needs nothing done to it.
+ @Test(.enabled(if: WatchdogdFixture.hasWatchdogd))
+ func agreesWithTheFrozenReferenceOnAnAlreadyPatchedBinary() throws {
let file = try WatchdogdFixture.scratchCopy(
of: WatchdogdFixture.watchdogd, named: "watchdogd-twice"
)
defer { try? FileManager.default.removeItem(at: file.deletingLastPathComponent()) }
try CFWWatchdogd.patch(at: file, log: nil)
- let afterSwift = try Data(contentsOf: file)
-
- let result = try WatchdogdFixture.run(WatchdogdFixture.python, [
- WatchdogdFixture.cfwCLI.path, "patch-watchdogd", file.path,
- ])
- #expect(result.status == 0, "reference patcher failed: \(result.output)")
- #expect(result.output.contains("already patched"))
- #expect(try Data(contentsOf: file) == afterSwift)
+ let afterFirst = try Data(contentsOf: file)
+ #expect(WatchdogdFixture.digest(afterFirst) == WatchdogdGolden.patched)
+
+ // The frozen half: the reference, handed this exact file, reported
+ // `all 2 matching site(s) already patched — nothing to do` and wrote
+ // nothing. This port lands on the same bytes when it re-runs.
+ let second = try CFWWatchdogd.patch(at: file, log: nil)
+ #expect(second.outcome == .alreadyPatched)
+ #expect(WatchdogdFixture.digest(try Data(contentsOf: file)) == WatchdogdGolden.patchedTwice)
}
/// `codesign` recomputes the page hashes independently of this code. If the
diff --git a/tests/FirmwarePatcherTests/DSCCameraPatcherTests.swift b/tests/FirmwarePatcherTests/DSCCameraPatcherTests.swift
index 8ee1a19f..d213bf26 100644
--- a/tests/FirmwarePatcherTests/DSCCameraPatcherTests.swift
+++ b/tests/FirmwarePatcherTests/DSCCameraPatcherTests.swift
@@ -1,12 +1,16 @@
// DSCCameraPatcherTests.swift — Parity gate for the camera DSC patcher.
//
// The claim these tests exist to defend is narrow and checkable: running
-// `scripts/patchers/cfw_patch_camera_dsc.py` on one clone of the real shared
-// cache and `DSCCameraPatcher` on another leaves the two clones byte for byte
-// identical, across all 79 chunk files — patched instructions, rewritten code
-// slots and everything neither touched. Nothing here asserts against a number
-// this repo wrote down once; the Python is run for real and its output is the
-// reference.
+// `DSCCameraPatcher` over a clone of the real shared cache leaves exactly the
+// bytes `scripts/patchers/cfw_patch_camera_dsc.py` left — patched instructions,
+// rewritten code slots and everything neither touched.
+//
+// That Python has been removed, so the numbers it produced are frozen in
+// `FrozenReference` below: the six sites with the address, the prologue and the
+// replacement for each, the code slots it re-attested, the SHA-256 of the two
+// chunks it changed, the patch ids its `_sym_slug` derived, and the bytes
+// keystone assembled for both replacements. Each carries the run that produced
+// it.
//
// The tests need the real cache. `VPHONE_DSC_PRISTINE` points at a directory of
// `dyld_shared_cache_arm64e*` chunks, defaulting to
@@ -28,6 +32,92 @@ import CryptoKit
import Foundation
import Testing
+// MARK: - The frozen reference
+
+/// What the reference Python did on the real 24A435 arm64e shared cache.
+///
+/// Recorded from a live run at commit 78cbeea:
+///
+/// PATH=/opt/homebrew/bin:… .venv/bin/python3 \
+/// scripts/patchers/cfw_patch_camera_dsc.py <clone> <clone>/dyld_shared_cache_arm64e
+///
+/// (`/opt/homebrew/bin` because the reference shelled out to `ipsw` for symbol
+/// resolution; the Swift port resolves from the cache's own tables.)
+private enum FrozenReference {
+ /// One entry point, as the reference printed it:
+ ///
+ /// +[_NUStyleTransferApplyProcessor processWithInputs:…] @ 0x1BF430C04
+ /// 7f2303d5ef3bb66d → 00008052c0035fd6
+ struct Site {
+ let symbol: String
+ let vma: UInt64
+ /// The eight prologue bytes it read, as it printed them.
+ let before: String
+ /// The eight it wrote in their place.
+ let after: String
+ }
+
+ /// `[1/2] +[_NUStyleTransfer*Processor processWithInputs:…] → return NO`,
+ /// then `[2/2] +[AVCaptureDevice authorizationStatusForMediaType:] →
+ /// return Authorized`. Six sites, in the order the reference listed them.
+ static let sites: [Site] = [
+ Site(symbol: "+[_NUStyleTransferApplyProcessor processWithInputs:arguments:output:error:]",
+ vma: 0x1_BF43_0C04, before: "7f2303d5ef3bb66d", after: "00008052c0035fd6"),
+ Site(symbol: "+[_NUStyleTransferInterpolateProcessor processWithInputs:arguments:output:error:]",
+ vma: 0x1_BF43_A3A8, before: "7f2303d5ff0303d1", after: "00008052c0035fd6"),
+ Site(symbol: "+[_NUStyleTransferLearnProcessor processWithInputs:arguments:output:error:]",
+ vma: 0x1_BF42_EC54, before: "7f2303d5ff0304d1", after: "00008052c0035fd6"),
+ Site(symbol: "+[_NUStyleTransferProcessor processWithInputs:arguments:output:error:]",
+ vma: 0x1_BF43_3BD0, before: "7f2303d5ffc306d1", after: "00008052c0035fd6"),
+ Site(symbol: "+[_NUStyleTransferThumbnailProcessor processWithInputs:arguments:output:error:]",
+ vma: 0x1_BF43_5DB4, before: "7f2303d5ff8303d1", after: "00008052c0035fd6"),
+ Site(symbol: "+[AVCaptureDevice authorizationStatusForMediaType:]",
+ vma: 0x1_AD8A_12D8, before: "7f2303d5ffc301d1", after: "60008052c0035fd6"),
+ ]
+
+ static var sitesBySymbol: [String: Site] {
+ Dictionary(uniqueKeysWithValues: sites.map { ($0.symbol, $0) })
+ }
+
+ /// The `re-attest: wrote slot N of <chunk>` lines, as `<chunk>:<slot>`:
+ /// four pages for the NeutrinoCore family, one for AVFCapture.
+ static let reattestedPages: Set<String> = [
+ "dyld_shared_cache_arm64e.15:7179",
+ "dyld_shared_cache_arm64e.15:7180",
+ "dyld_shared_cache_arm64e.15:7181",
+ "dyld_shared_cache_arm64e.15:7182",
+ "dyld_shared_cache_arm64e.11:5416",
+ ]
+
+ /// `cmp -s` against the pristine tree afterwards: two chunks moved, one per
+ /// family, with these digests (`shasum -a 256`). They cover the six writes
+ /// and the five re-attested slots together.
+ static let changedChunks: [String: String] = [
+ "dyld_shared_cache_arm64e.11":
+ "3a2cfbecd7eb029d74d930d9c8fc6d6d6066019691cf9f267a2089ac73685575",
+ "dyld_shared_cache_arm64e.15":
+ "4d7e5737d3d66725c59e0321410d05d501449301b269d7a6e25447c68ebc8cb0",
+ ]
+
+ /// `_sym_slug` from `cfw_patch_camera_dsc`, for the five style-transfer
+ /// symbols and the AVF one, in `DSCCameraPatcher`'s declaration order.
+ /// These key `cfw_records`, so a port that renames them writes records that
+ /// line up with nothing.
+ static let symbolSlugs: [String] = [
+ "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",
+ "AVCaptureDevice_authorizationStatusForMediaType",
+ ]
+
+ /// `cfw_asm.asm("mov w0, #0\nret").hex()` and the `#3` spelling, through
+ /// the keystone the patchers assembled with.
+ static let keystoneReturningZero = "00008052c0035fd6"
+ static let keystoneReturningThree = "60008052c0035fd6"
+}
+
// MARK: - Fixture discovery
private enum CameraFixture {
@@ -73,23 +163,6 @@ private enum CameraFixture {
.appendingPathComponent("vphone-dsc-camera")
}
- /// 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
- }
-
- /// `ipsw`, which the reference Python shells out to for symbol resolution.
- /// The Swift port does not need it; running the reference does.
- static var ipswDirectory: String? {
- for candidate in ["/opt/homebrew/bin", "/usr/local/bin"]
- where FileManager.default.isExecutableFile(atPath: candidate + "/ipsw")
- {
- return candidate
- }
- return nil
- }
-
/// Clone the pristine cache into a fresh directory the caller may write to.
static func cloneCache(named name: String) throws -> URL {
let pristine = try #require(pristine, missing)
@@ -185,129 +258,19 @@ private enum CameraSubprocess {
}
}
-// MARK: - The reference Python, run for real
-
-private enum CameraReference {
- /// Run `cfw_patch_camera_dsc.py` over `cache`, exactly as
- /// `patch_camera_userland.sh dsc` does.
- @discardableResult
- static func run(on cache: URL, extraArguments: [String] = []) throws -> CameraSubprocess.Result {
- let python = try #require(CameraFixture.python, "project venv is required for the cross-check")
- let ipswDirectory = try #require(
- CameraFixture.ipswDirectory,
- "`ipsw` is required to run the reference Python (the Swift port does not use it)"
- )
- var environment = ProcessInfo.processInfo.environment
- environment["PATH"] = ipswDirectory + ":/usr/bin:/bin:/usr/sbin:/sbin"
- let result = try CameraSubprocess.run(
- executable: python,
- arguments: [
- CameraFixture.repoRoot
- .appendingPathComponent("scripts/patchers/cfw_patch_camera_dsc.py").path,
- cache.path,
- cache.appendingPathComponent("dyld_shared_cache_arm64e").path,
- ] + extraArguments,
- environment: environment
- )
- #expect(result.status == 0, "reference Python failed: \(result.stderr)")
- return result
- }
-
- /// The sites the reference reported, as `symbol -> "before → after"`.
- ///
- /// Parsed off the two lines it prints per site rather than off a count, so
- /// a run that silently patched five of six cannot pass as six.
- static func sites(in output: String) -> [String: (before: String, after: String)] {
- var sites: [String: (String, String)] = [:]
- var pendingSymbol: String?
- for rawLine in output.split(separator: "\n", omittingEmptySubsequences: false) {
- let line = String(rawLine)
- let trimmed = line.trimmingCharacters(in: .whitespaces)
- if trimmed.hasPrefix("+["), let at = trimmed.range(of: " @ 0x") {
- pendingSymbol = String(trimmed[trimmed.startIndex ..< at.lowerBound])
- continue
- }
- if let symbol = pendingSymbol, trimmed.contains("→") {
- let halves = trimmed.components(separatedBy: "→")
- if halves.count == 2 {
- sites[symbol] = (
- halves[0].trimmingCharacters(in: .whitespaces),
- halves[1].trimmingCharacters(in: .whitespaces)
- )
- }
- pendingSymbol = nil
- }
- }
- return sites
- }
-
- /// `_sym_slug` from the reference module, for the six real symbols.
- static func symbolSlugs(for symbols: [String]) throws -> [String] {
- let python = try #require(CameraFixture.python)
- let result = try CameraSubprocess.run(
- executable: python,
- arguments: [
- "-c",
- """
- import json, sys
- sys.path.insert(0, sys.argv[1])
- from cfw_patch_camera_dsc import _sym_slug
- print(json.dumps([_sym_slug(s) for s in json.loads(sys.argv[2])]))
- """,
- CameraFixture.repoRoot.appendingPathComponent("scripts/patchers").path,
- String(decoding: try JSONSerialization.data(withJSONObject: symbols), as: UTF8.self),
- ]
- )
- #expect(result.status == 0, "python _sym_slug failed: \(result.stderr)")
- return try JSONDecoder().decode([String].self, from: Data(result.stdout.utf8))
- }
-
- /// What keystone assembles for a source string, through the module the
- /// patchers use.
- static func assemble(_ source: String) throws -> String {
- let python = try #require(CameraFixture.python)
- let result = try CameraSubprocess.run(
- executable: python,
- arguments: [
- "-c",
- """
- import sys
- sys.path.insert(0, sys.argv[1])
- from cfw_asm import asm
- print(asm(sys.argv[2]).hex())
- """,
- CameraFixture.repoRoot.appendingPathComponent("scripts/patchers").path,
- source,
- ]
- )
- #expect(result.status == 0, "keystone failed: \(result.stderr)")
- return result.stdout.trimmingCharacters(in: .whitespacesAndNewlines)
- }
-}
-
// MARK: - The parity gate
@Suite(.serialized, .enabled(if: CameraFixture.runs, CameraFixture.skipReason))
struct DSCCameraPatcherParityTests {
- /// The gate. Two clones, two implementations, one byte-for-byte comparison
- /// across every chunk file in the cache.
- @Test("Swift and Python leave the real cache byte-identical")
- func swiftAndPythonAgreeByteForByte() throws {
- _ = try #require(CameraFixture.pristine, CameraFixture.missing)
+ /// The gate. One clone, one run, one byte-for-byte comparison against the
+ /// digests the reference left on every chunk file in the cache.
+ @Test("Swift leaves the real cache in the reference's bytes")
+ func matchesTheReferenceByteForByte() throws {
+ let pristine = try #require(CameraFixture.pristine, CameraFixture.missing)
let swiftSide = try CameraFixture.cloneCache(named: "camera_swift")
- let pythonSide = try CameraFixture.cloneCache(named: "camera_python")
- defer { CameraFixture.discard(swiftSide, pythonSide) }
+ defer { CameraFixture.discard(swiftSide) }
- // The reference, run for real.
- let referenceOutput = try CameraReference.run(on: pythonSide).stdout
- let referenceSites = CameraReference.sites(in: referenceOutput)
- #expect(
- referenceSites.count == 6,
- "the reference reported \(referenceSites.count) sites, not 6"
- )
-
- // The port.
var log: [String] = []
let result = try DSCCameraPatcher.applyAll(
chunksDirectory: swiftSide,
@@ -319,73 +282,46 @@ struct DSCCameraPatcherParityTests {
// Same addresses, same bytes before, same bytes after — checked against
// what the reference printed, not against what the port believes.
+ let reference = FrozenReference.sitesBySymbol
+ #expect(Set(result.sites.map(\.symbol)) == Set(reference.keys))
for site in result.sites {
let theirs = try #require(
- referenceSites[site.symbol],
+ reference[site.symbol],
"the reference did not report \(site.symbol)"
)
+ #expect(site.vma == theirs.vma, "\(site.symbol) address")
#expect(site.originalBytes.hex == theirs.before, "\(site.symbol) original bytes")
#expect(site.patchedBytes.hex == theirs.after, "\(site.symbol) patched bytes")
- #expect(
- referenceOutput.contains("@ 0x\(String(site.vma, radix: 16, uppercase: true))"),
- "the reference did not report \(site.symbol) at the port's address"
- )
}
- // And the caches themselves, whole.
+ // And the caches themselves, whole: exactly the two chunks the
+ // reference moved, each to the bytes it left there.
let mine = try CameraFixture.digests(of: swiftSide)
- let theirs = try CameraFixture.digests(of: pythonSide)
- #expect(mine.keys.sorted() == theirs.keys.sorted())
- var differing: [String] = []
- for (name, digest) in mine.sorted(by: { $0.key < $1.key })
- where theirs[name] != digest
- {
- differing.append(name)
- }
- #expect(differing.isEmpty, "chunks differ after patching: \(differing)")
#expect(mine.count >= 79, "only \(mine.count) chunk files were compared")
-
- // The comparison is only worth anything if the two caches moved at all.
- let pristineDigests = try CameraFixture.digests(
- of: try #require(CameraFixture.pristine)
- )
+ let pristineDigests = try CameraFixture.digests(of: pristine)
let changed = mine.filter { pristineDigests[$0.key] != $0.value }.keys.sorted()
- #expect(
- changed.count == 2,
- "expected both families to land in their own chunk; changed: \(changed)"
- )
+ #expect(changed == FrozenReference.changedChunks.keys.sorted())
+ for name in changed {
+ let frozen = FrozenReference.changedChunks[name] ?? "(not a chunk the Python moved)"
+ #expect(mine[name] == frozen, "\(name): Swift \(mine[name] ?? "—"), reference \(frozen)")
+ }
print("[camera parity] \(result.siteCount) sites, "
+ "\(result.reattestation?.updated.count ?? 0) slots rewritten, "
- + "\(mine.count) chunk files identical to the Python's")
- print("[camera parity] chunks that changed: \(changed.joined(separator: ", "))")
+ + "\(mine.count) chunk files, \(changed.count) with the reference's digests")
for line in log where line.contains("re-attest: wrote") { print(line) }
}
- /// The reference re-attests per family off bare addresses; this re-attests
+ /// The reference re-attested per family off bare addresses; this re-attests
/// once at the end off recorded spans. Same pages on this cache — which is
/// worth checking rather than assuming, because it is the only reason the
/// two runs can come out identical.
- @Test("The port re-attests exactly the pages the reference does")
+ @Test("The port re-attests exactly the pages the reference did")
func reattestedPagesMatchTheReference() throws {
_ = try #require(CameraFixture.pristine, CameraFixture.missing)
let swiftSide = try CameraFixture.cloneCache(named: "camera_pages_swift")
- let pythonSide = try CameraFixture.cloneCache(named: "camera_pages_python")
- defer { CameraFixture.discard(swiftSide, pythonSide) }
-
- let referenceOutput = try CameraReference.run(on: pythonSide).stdout
- var referencePages: Set<String> = []
- for rawLine in referenceOutput.split(separator: "\n") {
- let line = String(rawLine)
- guard line.contains("re-attest: wrote slot ") else { continue }
- let parts = line.components(separatedBy: "re-attest: wrote slot ")
- guard parts.count == 2 else { continue }
- let fields = parts[1].split(separator: " ")
- guard fields.count >= 3 else { continue }
- referencePages.insert("\(fields[2]):\(fields[0])")
- }
- #expect(!referencePages.isEmpty, "the reference re-attested nothing")
+ defer { CameraFixture.discard(swiftSide) }
let result = try DSCCameraPatcher.applyAll(chunksDirectory: swiftSide, log: nil)
let minePages = Set(
@@ -393,7 +329,10 @@ struct DSCCameraPatcherParityTests {
"\($0.chunkURL.lastPathComponent):\($0.pageIndex)"
}
)
- #expect(minePages == referencePages, "swift \(minePages.sorted()) vs python \(referencePages.sorted())")
+ #expect(
+ minePages == FrozenReference.reattestedPages,
+ "swift \(minePages.sorted()) vs reference \(FrozenReference.reattestedPages.sorted())"
+ )
print("[camera pages] \(minePages.sorted().joined(separator: ", "))")
}
@@ -401,35 +340,25 @@ struct DSCCameraPatcherParityTests {
/// keyed on. A port that renames them writes records nothing lines up with.
@Test("Patch ids match the reference's _sym_slug")
func patchIDsMatchTheReference() throws {
- _ = try #require(CameraFixture.pristine, CameraFixture.missing)
-
let symbols = DSCCameraPatcher.styleTransferSymbols
+ [DSCCameraPatcher.authorizationStatusSymbol]
- let theirs = try CameraReference.symbolSlugs(for: symbols)
let mine = symbols.map(DSCCameraPatcher.symbolSlug)
- #expect(mine == theirs)
- #expect(
- mine.first == "NUStyleTransferProcessor_processWithInputs_arguments_output_error"
- )
+ #expect(mine == FrozenReference.symbolSlugs)
print("[camera slugs] \(mine.count) ids agreed, e.g. camera_dsc.nu_styletransfer.\(mine[0])")
}
/// Both replacements come out of the Keystone-checked encoders, and both
- /// have to be what keystone itself assembles.
- @Test("Both replacements are the bytes keystone assembles")
+ /// have to be what keystone itself assembled.
+ @Test("Both replacements are the bytes keystone assembled")
func replacementsMatchKeystone() throws {
- _ = try #require(CameraFixture.python, "project venv is required for the cross-check")
-
let styleTransfer = try DSCCameraPatcher.replacement(
returning: DSCCameraPatcher.Family.neutrinoStyleTransfer.returnValue
)
let authorization = try DSCCameraPatcher.replacement(
returning: DSCCameraPatcher.Family.avfAuthorization.returnValue
)
- let keystoneStyleTransfer = try CameraReference.assemble("mov w0, #0\nret")
- let keystoneAuthorization = try CameraReference.assemble("mov w0, #3\nret")
- #expect(styleTransfer.hex == keystoneStyleTransfer)
- #expect(authorization.hex == keystoneAuthorization)
+ #expect(styleTransfer.hex == FrozenReference.keystoneReturningZero)
+ #expect(authorization.hex == FrozenReference.keystoneReturningThree)
#expect(styleTransfer.count == 8)
#expect(authorization.count == 8)
print("[camera bytes] mov w0,#0;ret = \(styleTransfer.hex), mov w0,#3;ret = \(authorization.hex)")
@@ -524,6 +453,10 @@ struct DSCCameraPatcherBehaviourTests {
let afterSecond = try CameraFixture.digests(of: clone)
#expect(afterSecond == afterFirst, "a re-run changed the cache")
+ // …and what it left standing is still the reference's bytes.
+ for (name, digest) in FrozenReference.changedChunks {
+ #expect(afterSecond[name] == digest, "\(name) drifted across the re-run")
+ }
print("[camera idempotence] second run: 6 sites recognised as already patched, 0 slots rewritten")
}
diff --git a/tests/FirmwarePatcherTests/DSCFoundationTests.swift b/tests/FirmwarePatcherTests/DSCFoundationTests.swift
index 24b48fbd..42cb869b 100644
--- a/tests/FirmwarePatcherTests/DSCFoundationTests.swift
+++ b/tests/FirmwarePatcherTests/DSCFoundationTests.swift
@@ -1,9 +1,16 @@
// 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.
+// independent reference for any of this was the Python in `scripts/patchers/`
+// — `cfw_dsc_chunks` and `cfw_dsc_codesign`. That Python has been removed, so
+// what it produced on the real cache is frozen in `FrozenReference` below.
+//
+// The small answers — a symbol address, a slot hash, an install name — are
+// frozen literally. The big tables (103 mappings, 416 probe reads, 78 code
+// directories, 44 string hits) are frozen as the SHA-256 of a canonical text
+// form, which `Canonical` below rebuilds from the Swift side. A digest is not
+// a number this repo invented: it is the reference's whole answer, and any
+// single field that moves changes it.
//
// The tests need the real cache. Point `VPHONE_DSC_PRISTINE` at a directory of
// `dyld_shared_cache_arm64e*` chunks, or leave the default
@@ -21,9 +28,218 @@
// — `clonefile`, so instant and free on APFS — and work in the copy.
@testable import FirmwarePatcher
+import CryptoKit
import Foundation
import Testing
+// MARK: - The frozen reference
+
+/// What `cfw_dsc_chunks` and `cfw_dsc_codesign` answered on the real 24A435
+/// arm64e cache.
+///
+/// Recorded at commit 78cbeea by importing those modules from
+/// `.venv/bin/python3` and driving them over `ipsws/ref_extract/dsc_pristine`
+/// (and, for the writes, over clones of it). Each constant names the call.
+private enum FrozenReference {
+ // MARK: Layout
+
+ /// `len(_enumerate_chunks(dir))` and `len(DSCChunks(dir).mappings())`.
+ static let chunkCount = 79
+ static let mappingCount = 103
+
+ /// The first and last rows of `Canonical.mappings`, spelled out so a
+ /// digest mismatch has something human to sit next to.
+ static let firstMappingRow = "180000000 1800bc000 0 5 dyld_shared_cache_arm64e"
+ static let lastMappingRow =
+ "2d4fa8000 2fd500000 4000 1 dyld_shared_cache_arm64e.77.dyldlinkedit"
+
+ /// SHA-256 of `Canonical.mappings` — all 103 rows of
+ /// `(address, end, file_offset, init_prot, chunk)`.
+ static let mappingsSHA256 =
+ "8edc4100e0df480815d9cd3fff5855211a91b772996d771fd619713c818ee9dd"
+
+ // MARK: Reads
+
+ /// How many probe reads `Canonical.probes` covers: four per mapping
+ /// (start, last eight bytes, last byte, midpoint) plus four real code
+ /// sites.
+ static let probeCount = 416
+
+ /// SHA-256 of `Canonical.probes` — every probe's
+ /// `(vma, length, chunk, file_offset, bytes)`, so the address-to-file
+ /// translation and the bytes are frozen together.
+ static let probesSHA256 =
+ "1ab5b5a7d5bea1a4560d9b5b51415a92bbebaff4d6e0f6e8535bf70ff93174eb"
+
+ /// 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.
+ static let overrunVMA: UInt64 = 0x1_800B_BFFC
+
+ /// `DSCChunks.bytes_at_vma(0x1800BBFFC, 64).hex()`. The reference
+ /// bounds-checked only the first byte, so it returned all 64 without
+ /// complaint — bytes 4.. are the chunk's own `CS_SuperBlob` (`fade0cc0`),
+ /// presented as if they lived at those addresses. The Swift refuses the
+ /// read instead; this is the one deliberate divergence in the layer.
+ static let overrunBytes = """
+ 00000000fade0cc0000006d600000003000000000000002400000002000006c2\
+ 00010000000006cefade0c020000069e0002040000000002000000be00000058
+ """
+
+ // MARK: Symbols, strings and images
+
+ /// `resolve_local_symbol(dir, "_kern_SwapEnd")`.
+ static let kernSwapEndVMA: UInt64 = 0x2_2AC0_C334
+
+ /// `DSCChunks.find_string_vmas(b"kern.hv_vmm_present")`: 44 hits across the
+ /// executable mappings, first and last as spelled here, all of them frozen
+ /// together as the SHA-256 of `Canonical.addresses`.
+ static let hvVMMStringCount = 44
+ static let hvVMMStringFirst: UInt64 = 0x1_8C2D_B790
+ static let hvVMMStringLast: UInt64 = 0x2_C08F_0F67
+ static let hvVMMStringsSHA256 =
+ "746e7059ae67f7b5ac1e083efebf1647d2090db28ffccddabf93dd873323902a"
+
+ /// `find_macho_header_before(site)` and `read_install_name_at(header)` for
+ /// three real code sites — one per image the DSC patchers touch.
+ static let images: [(site: UInt64, header: UInt64, installName: String)] = [
+ (0x2_2AC0_C334, 0x2_2AC0_B000,
+ "/System/Library/PrivateFrameworks/IOMobileFramebuffer.framework/IOMobileFramebuffer"),
+ (0x1BF4_33BD0, 0x1BF1_43000,
+ "/System/Library/PrivateFrameworks/NeutrinoCore.framework/NeutrinoCore"),
+ (0x1AD8_A12D8, 0x1AD8_4B000,
+ "/System/Library/PrivateFrameworks/AVFCapture.framework/AVFCapture"),
+ ]
+
+ // MARK: Code directories
+
+ /// How many of the 79 chunks `_read_chunk_cd_blob` found a code directory
+ /// in. The one without is the `.atlas` side file.
+ static let codeDirectoryCount = 78
+
+ /// SHA-256 of `Canonical.codeDirectories` — every chunk's
+ /// `(blobOffset, blobLength, hashOffset, hashSize, codeSlotCount,
+ /// codeLimit, pageSize)`, or `none`.
+ static let codeDirectoriesSHA256 =
+ "cba2286b4310e7b4cc45b8655e020df6c95042075f6d2a95647d5c0b92d4cca1"
+
+ /// The main chunk's row, spelled out for the same reason as the mapping
+ /// rows above.
+ static let mainChunkDirectoryRow =
+ "dyld_shared_cache_arm64e 770084 1694 190 32 47 770048 16384"
+
+ // MARK: Re-signing
+
+ /// The site the re-signing tests patch: inside `IOMobileFramebuffer`'s
+ /// `__text`, a real executable page whose slot a real patch has to re-sign.
+ static let patchSite: UInt64 = 0x2_2AC0_C334
+
+ /// `bytes_at_vma(0x22AC0C334, 4).hex()` before anything is written —
+ /// `pacibsp`.
+ static let patchSiteOriginalBytes = "7f2303d5"
+
+ /// The one diagnostic `reattest_modified_pages` returned after writing
+ /// `mov w3, #0x588` (`03b18052`) at that site.
+ static let resignChunk = "dyld_shared_cache_arm64e.38"
+ static let resignPageIndex = 2563
+ static let resignChunkOffset = 41_992_192
+ static let resignSlotOffset = 130_892_098
+ static let resignHashBefore =
+ "5351489bc2d838a51a66a62e42ff7743457107335a35ddc82d3de4620e0c3e05"
+ static let resignHashAfter =
+ "f901fd7dd3ca8226722ebce5653d066a134c83c9925812957fc01d7b086dd31e"
+
+ // MARK: The page-straddling write
+
+ /// 0x22AC0FFFC is file offset 0x280FFFC of chunk .38 — the last four bytes
+ /// of page 2563. The eight-byte stub `mov w0, #0; ret` (what
+ /// `cfw_patch_camera_dsc` writes at a function entry) ends four bytes into
+ /// page 2564.
+ static let straddleVMA: UInt64 = 0x2_2AC0_FFFC
+ static let straddleFirstPage = 2563
+ static let straddleSecondPage = 2564
+
+ /// Told that address, the reference re-attested page 2563 and stopped: its
+ /// diagnostics named `[2563]`, page 2563 came out attested, and page 2564
+ /// was left with its original slot while its bytes had moved —
+ /// `computed dfe38096…` against `stored 7ccd65fa…`. The guest dies on the
+ /// first demand-page-in of such a page, which is why the Swift covers both.
+ static let straddleReferencePages = [2563]
+ static let straddlePage2563Hash =
+ "977f5abb356687af28158070c182b3017cfd5e90ccc82ef2eba8941d43d8020c"
+ static let straddlePage2564Computed =
+ "dfe38096f5ee7aaabeab6897f37e431eeacc0e9df589243abbb577877a1061c2"
+ static let straddlePage2564Stored =
+ "7ccd65fad32f1ee09d49a463dccc1226459a3b3bc2e6a45175b9a04c0e1e5423"
+
+ // MARK: The mapping seam
+
+ /// 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. `write_at_vma` accepted it and the four bytes landed at
+ /// file offset 0x3FFE.
+ static let seamVMA: UInt64 = 0x1_E00D_FFFE
+ static let seamChunk = "dyld_shared_cache_arm64e.25.dylddata"
+ static let seamFileOffset: UInt64 = 0x3FFE
+ static let seamBytes = "11223344"
+}
+
+// MARK: - Canonical forms
+
+/// The text forms the frozen digests were taken over.
+///
+/// Each row is exactly what the reference printed: lowercase hex without
+/// padding for addresses and file offsets, decimal for everything else, single
+/// spaces between fields, one trailing newline at the end of the table.
+private enum Canonical {
+ static func hex(_ value: UInt64) -> String { String(value, radix: 16) }
+
+ static func sha256(of text: String) -> String {
+ SHA256.hash(data: Data(text.utf8)).map { String(format: "%02x", $0) }.joined()
+ }
+
+ /// `address end file_offset init_prot chunk`, in mapping-table order.
+ static func mappings(_ chunks: DSCChunkSet) -> String {
+ chunks.mappings.map {
+ "\(hex($0.address)) \(hex($0.endAddress)) \(hex($0.fileOffset)) "
+ + "\($0.initProt) \($0.chunkURL.lastPathComponent)"
+ }.joined(separator: "\n") + "\n"
+ }
+
+ /// `vma length chunk file_offset bytes`, in request order.
+ static func probes(
+ _ chunks: DSCChunkSet,
+ _ requests: [(UInt64, Int)]
+ ) throws -> String {
+ try requests.map { vma, length in
+ let located = try #require(chunks.findChunk(forVMA: vma))
+ let bytes = try chunks.bytesAtVMA(vma, length: length)
+ return "\(hex(vma)) \(length) \(located.chunkURL.lastPathComponent) "
+ + "\(hex(UInt64(located.fileOffset))) \(bytes.hex)"
+ }.joined(separator: "\n") + "\n"
+ }
+
+ /// One address per row, sorted ascending.
+ static func addresses(_ values: [UInt64]) -> String {
+ values.sorted().map(hex).joined(separator: "\n") + "\n"
+ }
+
+ /// `chunk blobOffset blobLength hashOffset hashSize codeSlotCount
+ /// codeLimit pageSize`, or `chunk none`, in chunk order.
+ static func codeDirectories(_ chunks: DSCChunkSet) throws -> [String] {
+ try chunks.chunkURLs.map { url in
+ let name = url.lastPathComponent
+ guard let directory = try DSCCodeSignature.readCodeDirectory(ofChunk: url) else {
+ return "\(name) none"
+ }
+ return "\(name) \(directory.blobOffset) \(directory.blobLength) "
+ + "\(directory.hashOffset) \(directory.hashSize) "
+ + "\(directory.codeSlotCount) \(directory.codeLimit) \(directory.pageSize)"
+ }
+ }
+}
+
// MARK: - Fixture discovery
private enum DSCFixture {
@@ -73,12 +289,6 @@ private enum DSCFixture {
repoRoot.appendingPathComponent("ipsws/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
@@ -158,242 +368,52 @@ private enum Subprocess {
}
}
-// 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
+// MARK: - Slot state, read the way the reference read it
- var isAttested: Bool { computed == stored }
- }
-
- static func slotState(
+/// What one 16 KiB page hashes to now, and what its code slot claims it hashes
+/// to — the two numbers `cfw_dsc_codesign` compared, read straight out of the
+/// chunk's own code directory rather than from a patcher's bookkeeping.
+private enum SlotState {
+ static func read(
directory: URL,
chunk: String,
page: Int
- ) throws -> SlotState {
- try JSONDecoder().decode(
- SlotState.self,
- from: run("slot_state", directory: directory, extra: [chunk, String(page)])
+ ) throws -> (computed: String, stored: String, isAttested: Bool) {
+ let url = directory.appendingPathComponent(chunk)
+ let cd = try #require(
+ try DSCCodeSignature.readCodeDirectory(ofChunk: url),
+ "\(chunk) carries no code directory"
+ )
+ let (computed, stored) = try DSCCodeSignature.pageHashes(
+ chunkURL: url,
+ pageIndex: page,
+ directory: cd
)
+ return (computed.hex, stored.hex, computed == stored)
}
}
+
// 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 {
+ @Test("Chunk enumeration and mapping table match the reference")
+ func layoutMatchesTheReference() 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)
+ #expect(chunks.chunkURLs.count == FrozenReference.chunkCount)
+ #expect(chunks.mappings.count == FrozenReference.mappingCount)
- 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)
- }
+ let rows = Canonical.mappings(chunks).split(separator: "\n").map(String.init)
+ #expect(rows.first == FrozenReference.firstMappingRow)
+ #expect(rows.last == FrozenReference.lastMappingRow)
+ #expect(
+ Canonical.sha256(of: Canonical.mappings(chunks))
+ == FrozenReference.mappingsSHA256,
+ "the mapping table no longer matches the reference's"
+ )
print(
"[layout] \(chunks.chunkURLs.count) chunks, \(chunks.mappings.count) mappings, "
+ "vm 0x\(String(chunks.addressRange.lowerBound, radix: 16, uppercase: true))"
@@ -422,42 +442,31 @@ struct DSCFlatAddressingTests {
return requests
}
- @Test("bytesAtVMA matches cfw_dsc_chunks.py across every mapping and boundary")
- func bytesMatchPython() throws {
+ @Test("bytesAtVMA matches the reference across every mapping and boundary")
+ func bytesMatchTheReference() 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)
+ #expect(requests.count == FrozenReference.probeCount)
- 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])
+ // Every probe's chunk, file offset and bytes, in one digest — the whole
+ // of what the reference answered for these 416 reads.
+ #expect(
+ try Canonical.sha256(of: Canonical.probes(chunks, requests))
+ == FrozenReference.probesSHA256,
+ "a read, or its address-to-file translation, no longer matches the reference"
)
- #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
+ for (vma, length) in requests {
+ if let mapping = chunks.mapping(forVMA: vma),
+ vma + UInt64(length) == mapping.endAddress
{
boundaryChecks += 1
}
}
- print("[bytes] \(reference.count) reads agreed, \(boundaryChecks) of them ending exactly on a mapping boundary")
+ print("[bytes] \(requests.count) reads agreed, \(boundaryChecks) of them ending exactly on a mapping boundary")
#expect(boundaryChecks >= 2)
}
@@ -490,22 +499,18 @@ struct DSCFlatAddressingTests {
#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 {
+ /// The reference bounds-checked only the first byte of a read, then read
+ /// `length` raw bytes from the file. So a read that starts near the end of
+ /// a mapping came 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 reference
+ /// returned, and that the Swift refuses it.
+ @Test("An over-running read returned the chunk's signature; here it throws")
+ func overrunningReadIsRefusedUnlikeTheReference() 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 overrun = FrozenReference.overrunVMA
let mapping = try #require(chunks.mapping(forVMA: overrun))
#expect(mapping.endAddress == overrun + 4)
@@ -513,43 +518,27 @@ struct DSCFlatAddressingTests {
_ = 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")
+ let referenceBytes = FrozenReference.overrunBytes
+ #expect(referenceBytes.count == 128, "the reference returned all 64 bytes")
// Bytes 4.. are the chunk's own CS_SuperBlob, not code.
- #expect(pythonBytes.contains("fade0cc0"))
+ #expect(referenceBytes.contains("fade0cc0"))
- // The four bytes that really are at that address still read fine.
+ // The four bytes that really are at that address still read fine, and
+ // they are the four the reference's answer opens with.
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))…")
+ #expect(referenceBytes.hasPrefix(inBounds.hex))
print("[overrun] swift threw; its in-bounds 4 bytes are \(inBounds.hex)")
}
- @Test("resolveLocalSymbol matches the Python and ipsw")
+ @Test("resolveLocalSymbol matches the reference 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)))")
+ #expect(mine == FrozenReference.kernSwapEndVMA)
+ print("[local symbol] \(name) = 0x\(String(mine, 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
@@ -558,7 +547,7 @@ struct DSCFlatAddressingTests {
}
/// 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
+ /// symbol does not exist" the same way, as `nil`. The reference raised
/// `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 {
@@ -597,41 +586,31 @@ struct DSCFlatAddressingTests {
/// 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 {
+ @Test("String search and image lookup match the reference")
+ func searchHelpersMatchTheReference() 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])
+ let mine = try chunks.findStringVMAs(Data(needle.utf8)).sorted()
+ #expect(mine.count == FrozenReference.hvVMMStringCount)
+ #expect(mine.first == FrozenReference.hvVMMStringFirst)
+ #expect(mine.last == FrozenReference.hvVMMStringLast)
+ #expect(
+ Canonical.sha256(of: Canonical.addresses(mine))
+ == FrozenReference.hvVMMStringsSHA256,
+ "the string sweep no longer finds the reference's hits"
)
- #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))
+ for expected in FrozenReference.images {
+ let header = try #require(try chunks.findMachOHeaderBefore(expected.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>")")
+ #expect(header == expected.header)
+ #expect(name == expected.installName)
+ print("[image] 0x\(String(expected.site, radix: 16)) -> "
+ + "0x\(String(header, radix: 16)) \(name ?? "<none>")")
}
}
}
@@ -640,65 +619,25 @@ struct DSCFlatAddressingTests {
@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
+ private let patchSite = FrozenReference.patchSite
- @Test("Chunk code directories match cfw_dsc_codesign.py")
- func codeDirectoriesMatchPython() throws {
+ @Test("Chunk code directories match the reference")
+ func codeDirectoriesMatchTheReference() 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)
+ let rows = try Canonical.codeDirectories(chunks)
+ let found = rows.filter { !$0.hasSuffix(" none") }.count
+ #expect(found == FrozenReference.codeDirectoryCount)
+ #expect(rows.first == FrozenReference.mainChunkDirectoryRow)
+ #expect(
+ Canonical.sha256(of: rows.joined(separator: "\n") + "\n")
+ == FrozenReference.codeDirectoriesSHA256,
+ "a chunk's code directory no longer parses the way the reference parsed it"
)
-
- 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)
+ print("[code directories] \(found) chunk signatures agreed with the reference")
}
/// The DSC path's stated invariants: 16 KiB pages, a single SHA-256 code
@@ -727,40 +666,25 @@ struct DSCCodeSignatureTests {
#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 {
+ /// The gate from the plan: patch one byte, re-sign, and require the page
+ /// and its slot to come out as the reference's did.
+ @Test("Re-signing produces the reference's slot hashes")
+ func reSigningMatchesTheReference() 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) }
+ defer { DSCFixture.discard(swiftSide) }
// 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.
+ // 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)
+ #expect(originalBytes.hex == FrozenReference.patchSiteOriginalBytes)
let span = try chunks.write(at: patchSite, replacement)
#expect(span == DSCWriteSpan(vma: patchSite, length: 4))
#expect(chunks.recordedWrites == [span])
@@ -774,82 +698,55 @@ struct DSCCodeSignatureTests {
#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.
+ // The hashes themselves — the reference's single diagnostic, field for
+ // field.
+ #expect(mine.chunkURL.lastPathComponent == FrozenReference.resignChunk)
+ #expect(mine.pageIndex == FrozenReference.resignPageIndex)
+ #expect(mine.chunkOffset == FrozenReference.resignChunkOffset)
+ #expect(mine.slotOffset == FrozenReference.resignSlotOffset)
+ #expect(mine.hashBefore.hex == FrozenReference.resignHashBefore)
+ #expect(mine.hashAfter.hex == FrozenReference.resignHashAfter)
+
+ // And the bytes on disk, which is the claim that actually matters: the
+ // stored slot has to be the digest of the page as it now stands.
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)
+ #expect(stored.hex == FrozenReference.resignHashAfter)
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)")
+ print("[re-sign] swift \(mine.hashAfter.hex)")
+ print("[re-sign] reference \(FrozenReference.resignHashAfter)")
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
+ /// wrote 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;
+ /// dies on the first demand-page-in of it. The reference did 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")
+ @Test("A write across a page boundary re-attests both pages, where the reference attested 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) }
+ defer { DSCFixture.discard(swiftSide) }
- // 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 straddle = FrozenReference.straddleVMA
let stub = Data([0x00, 0x00, 0x80, 0x52, 0xC0, 0x03, 0x5F, 0xD6])
- let chunkName = "dyld_shared_cache_arm64e.38"
- let firstPage = 2563
- let secondPage = 2564
+ let chunkName = FrozenReference.resignChunk
+ let firstPage = FrozenReference.straddleFirstPage
+ let secondPage = FrozenReference.straddleSecondPage
// Swift: write, then re-attest from what the write recorded.
let chunks = try DSCChunkSet(directory: swiftSide)
@@ -867,83 +764,62 @@ struct DSCCodeSignatureTests {
#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.
+ // Both pages, read back out of the chunk's own code directory rather
+ // than from the patcher's bookkeeping.
for page in [firstPage, secondPage] {
- let state = try PythonOracle.slotState(
- directory: swiftSide,
- chunk: chunkName,
- page: page
- )
+ let state = try SlotState.read(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)
+ // Page 2563 comes out with the hash the reference also computed for it
+ // — the reference covered that one page and stopped.
+ #expect(FrozenReference.straddleReferencePages == [firstPage])
+ let first = try SlotState.read(directory: swiftSide, chunk: chunkName, page: firstPage)
+ #expect(first.computed == FrozenReference.straddlePage2563Hash)
+
+ // Page 2564 is the divergence, on the record: the reference left it
+ // holding `7ccd65fa…` while its bytes hashed to `dfe38096…`. The Swift
+ // rewrote it, so the two now agree — and the value it agrees on is the
+ // one the reference computed but did not store.
+ let second = try SlotState.read(directory: swiftSide, chunk: chunkName, page: secondPage)
+ #expect(second.computed == FrozenReference.straddlePage2564Computed)
+ #expect(second.stored == FrozenReference.straddlePage2564Computed)
#expect(
- !pythonSecond.isAttested,
- "the Python reference unexpectedly covered the second page too"
+ FrozenReference.straddlePage2564Stored != FrozenReference.straddlePage2564Computed,
+ "the reference's own second page was stale, which is why this test exists"
)
- print("[straddle python] page \(firstPage) attested, page \(secondPage) stored "
- + "\(pythonSecond.stored.prefix(16))… vs computed \(pythonSecond.computed.prefix(16))… — STALE")
+ print("[straddle reference] page \(secondPage) was left stored "
+ + "\(FrozenReference.straddlePage2564Stored.prefix(16))… vs computed "
+ + "\(FrozenReference.straddlePage2564Computed.prefix(16))… — STALE")
- // The bytes themselves still agree; only the attested page set differs.
+ // The bytes themselves are the stub, at the file offset the reference
+ // wrote them to.
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")
+ /// mapping start addresses and refused all of them, where the reference
+ /// wrote them happily. This one is accepted, and lands where the reference
+ /// landed; the case where the file offsets break is still refused.
+ @Test("A write across contiguous mappings of one chunk lands where the reference put it")
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
+ defer { DSCFixture.discard(swiftSide) }
+
+ let seam = FrozenReference.seamVMA
let value = Data([0x11, 0x22, 0x33, 0x44])
- let chunkName = "dyld_shared_cache_arm64e.25.dylddata"
+ let chunkName = FrozenReference.seamChunk
let chunks = try DSCChunkSet(directory: swiftSide)
let mapping = try #require(chunks.mapping(forVMA: seam))
@@ -958,33 +834,19 @@ struct DSCCodeSignatureTests {
// 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"]
- )
- )
+ // The reference's `write_at_vma` put these four bytes at file offset
+ // 0x3FFE of this chunk. So must this one.
let mine = try DSCChunkSet.read(
url: swiftSide.appendingPathComponent(chunkName),
- offset: 0x3FFE,
+ offset: FrozenReference.seamFileOffset,
length: 4
)
- #expect(mine.hex == theirs.bytes)
+ #expect(mine.hex == FrozenReference.seamBytes)
#expect(mine == value)
- print("[seam] 0x\(String(seam, radix: 16)) -> \(chunkName)@0x3ffe: swift \(mine.hex), python \(theirs.bytes)")
+ print("[seam] 0x\(String(seam, radix: 16)) -> \(chunkName)@0x3ffe: \(mine.hex)")
for page in [0, 1] {
- let state = try PythonOracle.slotState(
- directory: swiftSide, chunk: chunkName, page: page
- )
+ let state = try SlotState.read(directory: swiftSide, chunk: chunkName, page: page)
#expect(state.isAttested, "page \(page) left stale")
}
@@ -1079,8 +941,8 @@ struct DSCCodeSignatureTests {
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.
+ // And the default log says all of it out loud, as the reference's
+ // verbose=True did.
var spoken: [String] = []
_ = try DSCCodeSignature.reattest(
in: chunks,
diff --git a/tests/FirmwarePatcherTests/DSCHVVMMPatcherTests.swift b/tests/FirmwarePatcherTests/DSCHVVMMPatcherTests.swift
index fb9d187f..9e220efb 100644
--- a/tests/FirmwarePatcherTests/DSCHVVMMPatcherTests.swift
+++ b/tests/FirmwarePatcherTests/DSCHVVMMPatcherTests.swift
@@ -1,14 +1,18 @@
-// DSCHVVMMPatcherTests.swift — Python-vs-Swift parity for the hv_vmm_present
-// user-mode cstring mangle.
+// DSCHVVMMPatcherTests.swift — parity for the hv_vmm_present user-mode cstring
+// mangle.
//
// There is no external oracle for this patch. `codesign -v` does not apply to a
-// dyld shared cache chunk, and the only statement of what the patch should do is
-// `scripts/patchers/cfw_patch_hv_vmm_dsc.py` plus the module it imports its
-// constants from, `cfw_patch_hv_vmm.py`. So the test is not "does the Swift
-// write 29 sites" — that number is this repo's own claim. It is: run the
-// reference on one clone of the real cache, the Swift on another, and require
-// the two 6.7 GB trees to come out byte for byte identical, chunk files and
-// re-attested code directories alike.
+// dyld shared cache chunk, and the only statement of what the patch should do
+// was `scripts/patchers/cfw_patch_hv_vmm_dsc.py` plus the module it imported
+// its constants from, `cfw_patch_hv_vmm.py`. Those have been removed, so what
+// they produced on the real 24A435 arm64e cache is frozen in `FrozenReference`
+// below: the constants, the blacklist, the per-dylib verdict for all 44 dylibs
+// that carry the cstring, the SHA-256 of each of the 17 chunks that moved, the
+// drift scenario's own digests, and the two standalone Mach-O runs.
+//
+// So the test is still not "does the Swift write 29 sites" as a number this
+// repo invented — it is "does the Swift leave the bytes the reference left",
+// chunk files and re-attested code directories alike.
//
// The fixture is the real 24A435 arm64e cache. Point `VPHONE_DSC_PRISTINE` at a
// directory of `dyld_shared_cache_arm64e*` chunks, or leave the default
@@ -26,9 +30,225 @@
// disk.
@testable import FirmwarePatcher
+import CryptoKit
import Foundation
import Testing
+// MARK: - The frozen reference
+
+/// What the reference modules held, and what they did to the real cache.
+///
+/// Recorded at commit 78cbeea by driving `cfw_patch_hv_vmm` and
+/// `cfw_patch_hv_vmm_dsc` from `.venv/bin/python3` over a clone of
+/// `ipsws/ref_extract/dsc_pristine` and over the pristine binaries in
+/// `ipsws/ref_extract/macho_pristine`. Each constant names the call behind it.
+private enum FrozenReference {
+ // MARK: Constants, straight out of cfw_patch_hv_vmm
+
+ /// `NEEDLE.hex()` — `"kern.hv_vmm_present\0"`.
+ static let needleHex = "6b65726e2e68765f766d6d5f70726573656e7400"
+
+ /// `MANGLED_NEEDLE.hex()` — `"kern.Xv_vmm_present\0"`.
+ static let mangledNeedleHex = "6b65726e2e58765f766d6d5f70726573656e7400"
+
+ /// `MANGLE_OFFSET`, `ORIGINAL_BYTE.hex()`, `MANGLED_BYTE.hex()`.
+ static let mangleOffset = 5
+ static let originalByteHex = "68"
+ static let mangledByteHex = "58"
+
+ /// `list(DONT_PATCH_INSTALL_NAMES)` from `cfw_patch_hv_vmm_dsc`, in
+ /// declaration order — identity and activation first, then store, then the
+ /// consumer services.
+ static let blacklist: [String] = [
+ "/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",
+ ]
+
+ // MARK: The real cache
+
+ /// The dictionary `patch_hv_vmm_in_dsc(<clone>)` returned: every dylib that
+ /// carries the cstring, mapped to how many of its sites were mangled. The
+ /// zeros are the blacklist — seen, classified, and deliberately left with
+ /// the pristine name so they get ENOENT and conclude "not a VM".
+ static let mangledCountByInstallName: [String: Int] = [
+ "/System/Library/Frameworks/CoreML.framework/CoreML": 1,
+ "/System/Library/Frameworks/CoreVideo.framework/CoreVideo": 1,
+ "/System/Library/Frameworks/MediaToolbox.framework/MediaToolbox": 1,
+ "/System/Library/Frameworks/MetalPerformanceShadersGraph.framework/MetalPerformanceShadersGraph": 1,
+ "/System/Library/Frameworks/SoundAnalysis.framework/SoundAnalysis": 1,
+ "/System/Library/PrivateFrameworks/AAAFoundation.framework/AAAFoundation": 0,
+ "/System/Library/PrivateFrameworks/AirPlaySupport.framework/AirPlaySupport": 1,
+ "/System/Library/PrivateFrameworks/AppStoreUtilities.framework/AppStoreUtilities": 0,
+ "/System/Library/PrivateFrameworks/AppleNeuralEngine.framework/AppleNeuralEngine": 1,
+ "/System/Library/PrivateFrameworks/ApplePushService.framework/ApplePushService": 0,
+ "/System/Library/PrivateFrameworks/AuthKit.framework/AuthKit": 0,
+ "/System/Library/PrivateFrameworks/CMCapture.framework/CMCapture": 1,
+ "/System/Library/PrivateFrameworks/CloudSubscriptionFeatures.framework/CloudSubscriptionFeatures": 1,
+ "/System/Library/PrivateFrameworks/CoreCDP.framework/CoreCDP": 0,
+ "/System/Library/PrivateFrameworks/CorePrescription.framework/CorePrescription": 0,
+ "/System/Library/PrivateFrameworks/CoreRE.framework/CoreRE": 1,
+ "/System/Library/PrivateFrameworks/DVTInstrumentsUtilities.framework/DVTInstrumentsUtilities": 0,
+ "/System/Library/PrivateFrameworks/DesignLibrary.framework/DesignLibrary": 1,
+ "/System/Library/PrivateFrameworks/DeviceCheckInternal.framework/DeviceCheckInternal": 0,
+ "/System/Library/PrivateFrameworks/DeviceIdentity.framework/DeviceIdentity": 0,
+ "/System/Library/PrivateFrameworks/EmailFoundation.framework/EmailFoundation": 0,
+ "/System/Library/PrivateFrameworks/Espresso.framework/Espresso": 1,
+ "/System/Library/PrivateFrameworks/FindMyBase.framework/FindMyBase": 0,
+ "/System/Library/PrivateFrameworks/HomeAI.framework/HomeAI": 1,
+ "/System/Library/PrivateFrameworks/IDSFoundation.framework/IDSFoundation": 0,
+ "/System/Library/PrivateFrameworks/IOSurfaceAccelerator.framework/IOSurfaceAccelerator": 1,
+ "/System/Library/PrivateFrameworks/IntelligenceFlowShared.framework/IntelligenceFlowShared": 1,
+ "/System/Library/PrivateFrameworks/MagnifierSupport.framework/MagnifierSupport": 1,
+ "/System/Library/PrivateFrameworks/MobileActivation.framework/MobileActivation": 0,
+ "/System/Library/PrivateFrameworks/MobileAssetDaemon.framework/MobileAssetDaemon": 1,
+ "/System/Library/PrivateFrameworks/NeuralNetworks.framework/NeuralNetworks": 1,
+ "/System/Library/PrivateFrameworks/PhotoFoundation.framework/PhotoFoundation": 1,
+ "/System/Library/PrivateFrameworks/Recon3D.framework/Recon3D": 1,
+ "/System/Library/PrivateFrameworks/RenderBox.framework/RenderBox": 1,
+ "/System/Library/PrivateFrameworks/TrialServer.framework/TrialServer": 0,
+ "/System/Library/PrivateFrameworks/VFX.framework/VFX": 1,
+ "/System/Library/PrivateFrameworks/VisionKitCore.framework/VisionKitCore": 1,
+ "/System/Library/PrivateFrameworks/WatchdogServiceManagement.framework/WatchdogServiceManagement": 0,
+ "/System/Library/PrivateFrameworks/WebGPU.framework/WebGPU": 1,
+ "/System/Library/PrivateFrameworks/caulk.framework/caulk": 1,
+ "/System/Library/SubFrameworks/CoreAIRuntime.framework/CoreAIRuntime": 1,
+ "/System/Library/SubFrameworks/RealityCoreRenderer.framework/RealityCoreRenderer": 1,
+ "/usr/lib/libMobileGestalt.dylib": 1,
+ "/usr/lib/libafc.dylib": 1,
+ ]
+
+ /// 29 sites across 29 dylibs; the other 15 entries above are the blacklist.
+ static var totalMangled: Int { mangledCountByInstallName.values.reduce(0, +) }
+
+ /// `cmp -s` against the pristine tree after the run: 17 chunks moved, with
+ /// these digests (`shasum -a 256`). The Python logged 29 `re-attest: wrote
+ /// slot …` lines and then `re-attest: updated 29 slot hash(es) across 17
+ /// chunk(s)`, so these digests cover the mangles and the slot hashes alike.
+ ///
+ /// Re-running it over its own output wrote nothing and left them standing;
+ /// a dry run on a fresh clone changed no byte at all.
+ static let changedChunks: [String: String] = [
+ "dyld_shared_cache_arm64e.03":
+ "fa2647de6433a45269aeb7988338ba615c280e742fb7319f887df402fdd4526e",
+ "dyld_shared_cache_arm64e.05":
+ "fa58f42ad70af3c20e081c1f19c36121e27d3150a81856f7ef9a3264e1ef0d81",
+ "dyld_shared_cache_arm64e.11":
+ "f5614f3fb7147a0ee251becd1d6dc8a815849b879376c74d25dde04a982414b3",
+ "dyld_shared_cache_arm64e.13":
+ "5be2f71398d2c0e905d361e3b6619b338cdb7ccdb5f140f747a8fe50a0abbc64",
+ "dyld_shared_cache_arm64e.15":
+ "bbbd7d80035ee4b5496860eee91ce53762ee3c3fb7b6cd69a372763e12ee8269",
+ "dyld_shared_cache_arm64e.19":
+ "30a0167148dbe1884a6afc3332656501f5931967a0a0f881f2bd98b7ef0132b7",
+ "dyld_shared_cache_arm64e.30":
+ "383bad0df1c10be753d98263bed3913e0ec247fc1152b4b3b9122c089692c902",
+ "dyld_shared_cache_arm64e.36":
+ "00ffb7b9dd847203358afb1aafad0e8b6fb219c04bde44b632267fdabcb0fc27",
+ "dyld_shared_cache_arm64e.38":
+ "607dd2ffa643e7efcb0f8fd048a4f2b6d0834658fb1f252dc0c936416a368048",
+ "dyld_shared_cache_arm64e.40":
+ "294c4445e0c99955390374a60ac9c7aa2feab8d79fe9b7df96dc016888df3944",
+ "dyld_shared_cache_arm64e.42":
+ "d82b6cf13553ced34061ed555edb646d0f197f4fe4ee41a0a5c04ee221159a5b",
+ "dyld_shared_cache_arm64e.46":
+ "d44fc4f5d4caf1f85fac3c8f60cc8b53d3ceddd92abe47eeb468323b8afb467d",
+ "dyld_shared_cache_arm64e.57":
+ "f133e1624116214f3d794da136081478de3b6e3fb1485128c44ccb3e64b81c1d",
+ "dyld_shared_cache_arm64e.59":
+ "8133b4a774accd23e4682cdf3803479527d2a5025d47a675ca3a2eac844cc08d",
+ "dyld_shared_cache_arm64e.63":
+ "4ff96a186146fa1ef029d40c55de44bcd066c38b8040b5b726b5a12ea800c4e6",
+ "dyld_shared_cache_arm64e.71":
+ "701cf056e817fb25da8b1f74f9a2d92728941012e51fd4a5f9fa69c765d66251",
+ "dyld_shared_cache_arm64e.73":
+ "a56c1e720372456224a01ab06ab593c41966b50f1c24c6168cf2ab76788b5627",
+ ]
+
+ // MARK: The drift scenario
+
+ /// The lowest-addressed pristine site inside a blacklisted dylib, which is
+ /// what the drift test mangles by hand before running the patch. Found by
+ /// walking `chunks.find_string_vmas(NEEDLE)` in order and classifying each.
+ static let driftVMA: UInt64 = 0x1_97CF_0A98
+ static let driftedInstallName =
+ "/System/Library/PrivateFrameworks/IDSFoundation.framework/IDSFoundation"
+
+ /// With that one byte pre-mangled, the reference printed `[!] drift:
+ /// …IDSFoundation is in the blacklist but already mangled at
+ /// string@0x197CF0A98 — slot will be re-attested to current bytes`, then
+ /// `1 blacklisted dylib(s) found mangled on disk` and `re-attest: updated
+ /// 30 slot hash(es) across 17 chunk(s)`.
+ ///
+ /// It did not revert the byte: the same 17 chunks moved, and only
+ /// `…arm64e.05` — the chunk IDSFoundation's cstring lives in — came out
+ /// different from the ordinary run above.
+ static let driftChangedChunks: [String: String] = changedChunks.merging([
+ "dyld_shared_cache_arm64e.05":
+ "b5483cb22495048a99437a944f761c3bc36fa4c564789d9bd345f2a5dd2b59aa",
+ ]) { _, new in new }
+
+ // MARK: Standalone Mach-O
+
+ /// One `find_string_sites` result.
+ struct MachOSite {
+ let stringVMA: UInt64
+ let fileOffset: Int
+ let section: String
+ }
+
+ /// What `patch_hv_vmm` did to one pristine binary.
+ struct MachORun {
+ /// `find_string_sites(open(<pristine>,"rb").read())`.
+ let sites: [MachOSite]
+ /// `shasum -a 256 <pristine>`, so a test that fed it something else
+ /// fails on the input rather than comparing nothing.
+ let pristineSHA256: String
+ /// `shasum -a 256` of the copy afterwards. A second `patch_hv_vmm` over
+ /// that copy returned 0 and left this digest unchanged.
+ let patchedSHA256: String
+ }
+
+ /// The two binaries `ipsws/ref_extract/macho_pristine` keeps. Each carries
+ /// exactly one occurrence of the cstring on this build.
+ static let machO: [String: MachORun] = [
+ "watchdogd": MachORun(
+ sites: [MachOSite(
+ stringVMA: 0x1_0001_1453,
+ fileOffset: 70739,
+ section: "__TEXT,__cstring"
+ )],
+ pristineSHA256:
+ "0309b868a214f9841279db3e2ef901f26e8c05b2dc616eeb551f2b2f0e06207f",
+ patchedSHA256:
+ "95c9c25c89d20ee1d46b20ee8fd7a7b90c674ef57247a666e6cb19db123220e4"
+ ),
+ "mobileactivationd": MachORun(
+ sites: [MachOSite(
+ stringVMA: 0x1_003B_BE2A,
+ fileOffset: 3_915_306,
+ section: "__TEXT,__cstring"
+ )],
+ pristineSHA256:
+ "89233513ce696cd01285f3432f3bcadd065cee07ac73bc5714836d13f24702d8",
+ patchedSHA256:
+ "29814c1318b40cd1afc8ea021604f1b165c6ce3775e3a4f02106891b84ff4129"
+ ),
+ ]
+}
+
// MARK: - Fixture discovery
private enum HVVMMFixture {
@@ -98,17 +318,6 @@ private enum HVVMMFixture {
.appendingPathComponent("vphone-hvvmm-parity")
}
- /// 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 let pythonMissing: Comment = """
- the project venv is required — the reference implementation is the only \
- oracle this patch has. Create it with `make setup_venv`.
- """
-
/// 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) }
@@ -185,8 +394,8 @@ private enum Subprocess {
process.standardOutput = out
process.standardError = err
try process.run()
- // Drain before waiting: the reference prints a line per site, and a full
- // pipe buffer would deadlock the run.
+ // Drain before waiting: `cp` of a 6.7 GB tree can fill a pipe buffer,
+ // and a full buffer would deadlock the run.
let outData = out.fileHandleForReading.readDataToEndOfFile()
let errData = err.fileHandleForReading.readDataToEndOfFile()
process.waitUntilExit()
@@ -201,186 +410,76 @@ private enum Subprocess {
// MARK: - Byte-for-byte tree comparison
private enum TreeComparison {
- /// Files present in one tree but not the other, and files whose bytes differ.
- struct Difference: CustomStringConvertible {
- var onlyInLeft: [String] = []
- var onlyInRight: [String] = []
- var differingBytes: [String] = []
-
- var isEmpty: Bool {
- onlyInLeft.isEmpty && onlyInRight.isEmpty && differingBytes.isEmpty
- }
-
- var description: String {
- var parts: [String] = []
- if !onlyInLeft.isEmpty { parts.append("only in left: \(onlyInLeft)") }
- if !onlyInRight.isEmpty { parts.append("only in right: \(onlyInRight)") }
- if !differingBytes.isEmpty { parts.append("bytes differ: \(differingBytes)") }
- return parts.isEmpty ? "identical" : parts.joined(separator: "; ")
- }
- }
-
- /// Compare two directories file by file, byte by byte.
+ /// Every file in `directory` whose bytes differ from its twin in
+ /// `reference`, plus any file present in one and not the other.
///
/// `cmp` rather than a digest: it stops at the first differing byte, so a
- /// tree that really does differ is reported in milliseconds instead of after
- /// hashing 6.7 GB twice.
- static func compare(_ left: URL, _ right: URL) throws -> Difference {
- let leftNames = Set(try FileManager.default.contentsOfDirectory(atPath: left.path))
- let rightNames = Set(try FileManager.default.contentsOfDirectory(atPath: right.path))
-
- var difference = Difference()
- difference.onlyInLeft = leftNames.subtracting(rightNames).sorted()
- difference.onlyInRight = rightNames.subtracting(leftNames).sorted()
-
- for name in leftNames.intersection(rightNames).sorted() {
+ /// tree that really does differ is reported in milliseconds instead of
+ /// after hashing 6.7 GB twice.
+ static func changedNames(in directory: URL, against reference: URL) throws -> [String] {
+ let manager = FileManager.default
+ let left = Set(try manager.contentsOfDirectory(atPath: reference.path))
+ let right = Set(try manager.contentsOfDirectory(atPath: directory.path))
+ var differing = Array(left.symmetricDifference(right))
+
+ for name in left.intersection(right) {
let result = try Subprocess.run(
executable: URL(fileURLWithPath: "/usr/bin/cmp"),
arguments: [
"-s",
- left.appendingPathComponent(name).path,
- right.appendingPathComponent(name).path,
+ reference.appendingPathComponent(name).path,
+ directory.appendingPathComponent(name).path,
]
)
- if result.status != 0 { difference.differingBytes.append(name) }
+ if result.status != 0 { differing.append(name) }
}
- return difference
+ return differing.sorted()
}
}
-// MARK: - The reference Python, driven as an oracle
-
-/// A driver around `cfw_patch_hv_vmm_dsc` / `cfw_patch_hv_vmm`, written to a
-/// temp file at test time.
-///
-/// It adds no logic of its own: it calls the reference entry points and prints
-/// what they return. That is the point — the comparison has to be against that
-/// code running, not against a transcription of it.
-private enum PythonOracle {
- static let source = #"""
-import contextlib
-import json
-import os
-import sys
-
-sys.path.insert(0, os.path.join(sys.argv[1], "scripts"))
-
-from patchers.cfw_patch_hv_vmm import (
- NEEDLE, MANGLED_NEEDLE, MANGLE_OFFSET, ORIGINAL_BYTE, MANGLED_BYTE,
- find_string_sites, patch_hv_vmm,
-)
-from patchers.cfw_patch_hv_vmm_dsc import (
- DONT_PATCH_INSTALL_NAMES, patch_hv_vmm_in_dsc,
-)
-
-command = sys.argv[2]
-
-if command == "constants":
- print(json.dumps({
- "needle": NEEDLE.hex(),
- "mangled_needle": MANGLED_NEEDLE.hex(),
- "mangle_offset": MANGLE_OFFSET,
- "original_byte": ORIGINAL_BYTE.hex(),
- "mangled_byte": MANGLED_BYTE.hex(),
- "blacklist": list(DONT_PATCH_INSTALL_NAMES),
- }))
-
-elif command == "patch_dsc":
- # argv[3] = chunks dir, argv[4] = "1" for a dry run.
- dry_run = len(sys.argv) > 4 and sys.argv[4] == "1"
- # The patcher narrates to stdout; keep that on stderr so stdout is JSON.
- with contextlib.redirect_stdout(sys.stderr):
- results = patch_hv_vmm_in_dsc(sys.argv[3], dry_run=dry_run)
- print(json.dumps({"results": results}))
-
-elif command == "macho_sites":
- with open(sys.argv[3], "rb") as f:
- data = f.read()
- print(json.dumps({"sites": find_string_sites(data)}))
-
-elif command == "patch_macho":
- with contextlib.redirect_stdout(sys.stderr):
- count = patch_hv_vmm(sys.argv[3], dry_run=False)
- print(json.dumps({"count": count}))
-
-else:
- raise SystemExit(f"unknown command {command}")
-"""#
-
- static func scriptURL() throws -> URL {
- let url = FileManager.default.temporaryDirectory
- .appendingPathComponent(
- "hv_vmm_oracle_\(ProcessInfo.processInfo.processIdentifier).py"
- )
- if !FileManager.default.fileExists(atPath: url.path) {
- try source.write(to: url, atomically: true, encoding: .utf8)
- }
- return url
- }
-
- static func run(_ command: String, _ extra: [String] = []) throws -> Data {
- guard let python = HVVMMFixture.python else { throw CocoaError(.fileNoSuchFile) }
- let script = try scriptURL()
- let result = try Subprocess.run(
- executable: python,
- arguments: [script.path, HVVMMFixture.repoRoot.path, command] + extra
- )
- guard result.status == 0 else {
- Issue.record("python oracle \(command) failed: \(result.stderr)")
- throw CocoaError(.fileReadUnknown)
+// MARK: - Digests
+
+/// SHA-256 of a file, streamed so a 131 MB chunk never lands in memory whole.
+/// The hex spelling matches `shasum -a 256`, which produced the frozen digests.
+private enum Digest {
+ static func sha256(of url: URL) throws -> String {
+ let handle = try FileHandle(forReadingFrom: url)
+ defer { try? handle.close() }
+ var hasher = SHA256()
+ while let block = try handle.read(upToCount: 4 << 20), !block.isEmpty {
+ hasher.update(data: block)
}
- return Data(result.stdout.utf8)
- }
-
- struct Constants: Decodable {
- let needle: String
- let mangled_needle: String
- let mangle_offset: Int
- let original_byte: String
- let mangled_byte: String
- let blacklist: [String]
- }
-
- struct DSCRun: Decodable {
- let results: [String: Int]
+ return hasher.finalize().map { String(format: "%02x", $0) }.joined()
}
- struct MachOSites: Decodable {
- struct Site: Decodable {
- let string_vma: UInt64
- let file_offset: Int
- let section: String
+ /// Assert that `directory` holds exactly the chunks the reference changed,
+ /// with exactly the reference's bytes.
+ static func expectMatches(_ directory: URL, _ frozen: [String: String]) throws {
+ let pristine = try #require(HVVMMFixture.pristine, HVVMMFixture.missing)
+ let changed = try TreeComparison.changedNames(in: directory, against: pristine)
+ #expect(changed == frozen.keys.sorted())
+ for name in changed {
+ let digest = try sha256(of: directory.appendingPathComponent(name))
+ let expected = frozen[name] ?? "(not a chunk the Python moved)"
+ #expect(digest == expected, "\(name): Swift \(digest), reference \(expected)")
}
-
- let sites: [Site]
- }
-
- struct MachORun: Decodable {
- let count: Int
}
}
// MARK: - Constants
-/// No cache fixture here, so no fixture gate: the only thing this suite needs is
-/// the venv that holds the reference modules, and a missing venv has to fail
-/// rather than skip — without it there is no oracle and nothing was checked.
+/// No fixture needed: these are the reference modules' own constants, which the
+/// port has to carry verbatim for anything else here to mean anything.
@Suite(.serialized)
struct DSCHVVMMConstantsTests {
@Test("The cstring, its mangle and the blacklist match the reference modules")
- func constantsMatchPython() throws {
- try #require(HVVMMFixture.python != nil, HVVMMFixture.pythonMissing)
- let reference = try JSONDecoder().decode(
- PythonOracle.Constants.self,
- from: PythonOracle.run("constants")
- )
-
- #expect(DSCHVVMMPatcher.needle.hex == reference.needle)
- #expect(DSCHVVMMPatcher.mangledNeedle.hex == reference.mangled_needle)
- #expect(DSCHVVMMPatcher.mangleOffset == reference.mangle_offset)
- #expect(Data([DSCHVVMMPatcher.originalByte]).hex == reference.original_byte)
- #expect(Data([DSCHVVMMPatcher.mangledByte]).hex == reference.mangled_byte)
- #expect(DSCHVVMMPatcher.dontPatchInstallNames == reference.blacklist)
+ func constantsMatchTheReference() throws {
+ #expect(DSCHVVMMPatcher.needle.hex == FrozenReference.needleHex)
+ #expect(DSCHVVMMPatcher.mangledNeedle.hex == FrozenReference.mangledNeedleHex)
+ #expect(DSCHVVMMPatcher.mangleOffset == FrozenReference.mangleOffset)
+ #expect(Data([DSCHVVMMPatcher.originalByte]).hex == FrozenReference.originalByteHex)
+ #expect(Data([DSCHVVMMPatcher.mangledByte]).hex == FrozenReference.mangledByteHex)
+ #expect(DSCHVVMMPatcher.dontPatchInstallNames == FrozenReference.blacklist)
// The mangle has to preserve the namespace prefix, or the name cannot
// resolve to any OID — see the patcher's file comment. This is the one
@@ -403,36 +502,29 @@ struct DSCHVVMMConstantsTests {
struct DSCHVVMMCacheParityTests {
/// The parity gate.
///
- /// Reference on one clone, Swift on another, then require the two trees to
- /// be byte identical — every chunk file, including the code directories the
- /// re-attestation pass rewrote. A port that writes a different number of
- /// sites, or the same number in different places, or the right bytes with
- /// the wrong page re-hashed, fails here.
+ /// One clone, one run, then require the tree to hold exactly the chunks the
+ /// reference moved with exactly the bytes it left — code directories and
+ /// all. A port that writes a different number of sites, or the same number
+ /// in different places, or the right bytes with the wrong page re-hashed,
+ /// fails here.
///
- /// The idempotence and blacklist checks ride on the same clones rather than
+ /// The idempotence and blacklist checks ride on the same clone rather than
/// cloning 6.7 GB again for each: they are assertions about the state this
/// test has already produced.
- @Test("The Swift patch and the Python reference produce identical caches")
- func swiftMatchesPythonOnTheRealCache() throws {
+ @Test("The Swift patch reproduces the reference's cache")
+ func swiftMatchesTheReferenceOnTheRealCache() throws {
_ = try #require(HVVMMFixture.pristine, HVVMMFixture.missing)
- try #require(HVVMMFixture.python != nil, HVVMMFixture.pythonMissing)
- let pythonClone = try HVVMMFixture.cloneCache(named: "python")
let swiftClone = try HVVMMFixture.cloneCache(named: "swift")
- defer { HVVMMFixture.discard(pythonClone, swiftClone) }
+ defer { HVVMMFixture.discard(swiftClone) }
- let reference = try JSONDecoder().decode(
- PythonOracle.DSCRun.self,
- from: PythonOracle.run("patch_dsc", [pythonClone.path])
- )
let result = try DSCHVVMMPatcher.patch(chunksDirectory: swiftClone, log: nil)
// Same verdict per dylib, including the zero-count entries that record
// "seen and deliberately left alone".
- #expect(result.mangledCountByInstallName == reference.results)
+ #expect(result.mangledCountByInstallName == FrozenReference.mangledCountByInstallName)
- let referenceTotal = reference.results.values.reduce(0, +)
- #expect(result.mangled == referenceTotal)
+ #expect(result.mangled == FrozenReference.totalMangled)
#expect(result.mangled > 0, "the reference patched nothing — wrong fixture?")
#expect(result.skippedInBlacklist == DSCHVVMMPatcher.dontPatchInstallNames.count)
#expect(result.skippedUnclassified == 0)
@@ -440,22 +532,22 @@ struct DSCHVVMMCacheParityTests {
#expect(result.isFullyAttested)
// One slot per dirtied page, and no site left unattested. Sites can in
// principle share a page, so this is a bound rather than an equality —
- // the tree comparison below is what actually pins the code directories.
+ // the digests below are what actually pin the code directories.
let slotsRewritten = result.reattestation?.updated.count ?? 0
#expect(slotsRewritten > 0)
#expect(slotsRewritten <= result.mangled)
print(
- "[hv_vmm] python \(referenceTotal) site(s), swift \(result.mangled) site(s), "
+ "[hv_vmm] \(result.mangled) site(s), "
+ "\(result.skippedInBlacklist) blacklisted, "
+ "\(slotsRewritten) slot(s) re-attested"
)
- let difference = try TreeComparison.compare(pythonClone, swiftClone)
- #expect(difference.isEmpty, "patched caches differ: \(difference)")
+ try Digest.expectMatches(swiftClone, FrozenReference.changedChunks)
// Idempotence, on the cache the Swift run just produced. A second pass
// finds no pristine cstring left, queues the mangled ones so their slots
- // stay in sync, and must not move a byte.
+ // stay in sync, and must not move a byte. The reference behaved the same
+ // way, so the frozen digests have to survive it.
let second = try DSCHVVMMPatcher.patch(chunksDirectory: swiftClone, log: nil)
#expect(second.mangled == 0)
#expect(second.pristineSiteCount == result.skippedInBlacklist)
@@ -463,8 +555,7 @@ struct DSCHVVMMCacheParityTests {
#expect(second.reattestOnly == result.mangled)
#expect(second.blacklistDrift == 0)
#expect(second.reattestation?.updated.isEmpty == true)
- let afterRerun = try TreeComparison.compare(pythonClone, swiftClone)
- #expect(afterRerun.isEmpty, "a second run moved bytes: \(afterRerun)")
+ try Digest.expectMatches(swiftClone, FrozenReference.changedChunks)
// The blacklist is the whole point of the design, so check it against
// the bytes rather than against the run's own bookkeeping: every
@@ -496,7 +587,6 @@ struct DSCHVVMMCacheParityTests {
@Test("A dry run reports the same sites and leaves every byte alone")
func dryRunTouchesNothing() throws {
let pristine = try #require(HVVMMFixture.pristine, HVVMMFixture.missing)
- try #require(HVVMMFixture.python != nil, HVVMMFixture.pythonMissing)
let clone = try HVVMMFixture.cloneCache(named: "dryrun")
defer { HVVMMFixture.discard(clone) }
@@ -506,7 +596,7 @@ struct DSCHVVMMCacheParityTests {
dryRun: true,
log: nil
)
- #expect(result.mangled > 0)
+ #expect(result.mangled == FrozenReference.totalMangled)
// A dry run writes nothing, so every page still hashes to exactly what
// its slot says and no slot would be rewritten. What has to be true is
// that the pass REACHED every page the patch would dirty — otherwise a
@@ -517,22 +607,17 @@ struct DSCHVVMMCacheParityTests {
#expect(pagesReached <= result.mangled)
#expect(result.isFullyAttested)
- let difference = try TreeComparison.compare(pristine, clone)
- #expect(difference.isEmpty, "a dry run wrote to the cache: \(difference)")
-
- // And the same for the reference, so "dry run changes nothing" is a
- // property of both implementations and not just of this one.
- _ = try PythonOracle.run("patch_dsc", [clone.path, "1"])
- let afterPython = try TreeComparison.compare(pristine, clone)
- #expect(afterPython.isEmpty, "the reference dry run wrote too: \(afterPython)")
+ // The reference's dry run wrote nothing either.
+ let changed = try TreeComparison.changedNames(in: clone, against: pristine)
+ #expect(changed.isEmpty, "a dry run wrote to the cache: \(changed)")
}
/// The drift branch, which is the one deliberate behaviour in this patch that
/// a port could plausibly get backwards.
///
/// A blacklisted dylib found already mangled means somebody took it out of
- /// the blacklist, ran the patch, and put it back. The reference does NOT
- /// revert the byte and does NOT refuse: it says so loudly and re-attests the
+ /// the blacklist, ran the patch, and put it back. The reference did NOT
+ /// revert the byte and did NOT refuse: it said so loudly and re-attested the
/// page to the bytes that are actually there, because reverting would leave
/// the page hash right and the operator's intent wrong. A port that "fixed"
/// this by reverting, or by treating it as an error, would pass every other
@@ -540,14 +625,12 @@ struct DSCHVVMMCacheParityTests {
@Test("A blacklisted dylib found mangled is reported as drift, not reverted")
func blacklistDriftIsReportedNotReverted() throws {
_ = try #require(HVVMMFixture.pristine, HVVMMFixture.missing)
- try #require(HVVMMFixture.python != nil, HVVMMFixture.pythonMissing)
- let pythonClone = try HVVMMFixture.cloneCache(named: "drift-python")
let swiftClone = try HVVMMFixture.cloneCache(named: "drift-swift")
- defer { HVVMMFixture.discard(pythonClone, swiftClone) }
+ defer { HVVMMFixture.discard(swiftClone) }
// The lowest-addressed site inside a blacklisted dylib, so the choice is
- // the same on every run.
+ // the same on every run — and the same one the reference was given.
let probe = try DSCChunkSet(directory: swiftClone)
let driftVMA = try #require(
try probe.findStringVMAs(DSCHVVMMPatcher.needle).sorted().first {
@@ -557,18 +640,17 @@ struct DSCHVVMMCacheParityTests {
"no blacklisted dylib carries the cstring in this cache"
)
let driftedDylib = try #require(DSCHVVMMPatcher.classify(driftVMA, in: probe))
+ #expect(driftVMA == FrozenReference.driftVMA)
+ #expect(driftedDylib == FrozenReference.driftedInstallName)
- // Mangle it by hand in both clones, without re-attesting — exactly the
- // state a prior out-of-band run would have left behind.
- for clone in [pythonClone, swiftClone] {
- let chunks = try DSCChunkSet(directory: clone)
- try chunks.write(
- at: driftVMA &+ UInt64(DSCHVVMMPatcher.mangleOffset),
- Data([DSCHVVMMPatcher.mangledByte])
- )
- }
+ // Mangle it by hand, without re-attesting — exactly the state a prior
+ // out-of-band run would have left behind, and what the reference saw.
+ let chunks = try DSCChunkSet(directory: swiftClone)
+ try chunks.write(
+ at: driftVMA &+ UInt64(DSCHVVMMPatcher.mangleOffset),
+ Data([DSCHVVMMPatcher.mangledByte])
+ )
- _ = try PythonOracle.run("patch_dsc", [pythonClone.path])
let result = try DSCHVVMMPatcher.patch(chunksDirectory: swiftClone, log: nil)
#expect(result.blacklistDrift == 1)
@@ -587,8 +669,9 @@ struct DSCHVVMMCacheParityTests {
.bytesAtVMA(driftVMA, length: DSCHVVMMPatcher.needle.count)
#expect(after == DSCHVVMMPatcher.mangledNeedle)
- let difference = try TreeComparison.compare(pythonClone, swiftClone)
- #expect(difference.isEmpty, "drift handling differs from the reference: \(difference)")
+ // The same 17 chunks as the ordinary run, differing only in the one the
+ // drifted dylib lives in — which is what the reference left behind.
+ try Digest.expectMatches(swiftClone, FrozenReference.driftChangedChunks)
print("[hv_vmm] drift on \(driftedDylib) at 0x\(String(driftVMA, radix: 16, uppercase: true))")
}
}
@@ -598,63 +681,52 @@ struct DSCHVVMMCacheParityTests {
@Suite(.serialized, .enabled(if: HVVMMFixture.machORuns, HVVMMFixture.machOSkipReason))
struct DSCHVVMMStandaloneTests {
/// The other half of `cfw_patch_hv_vmm.py`, against the binaries the repo
- /// keeps pristine copies of.
- ///
- /// `watchdogd` carries one occurrence of the cstring and `mobileactivationd`
- /// two, so between them they cover the single-site and multi-site paths.
+ /// keeps pristine copies of. Each carries one occurrence of the cstring on
+ /// this build.
@Test(
"Standalone Mach-O mangling matches the reference",
arguments: ["watchdogd", "mobileactivationd"]
)
- func standaloneMatchesPython(name: String) throws {
+ func standaloneMatchesTheReference(name: String) throws {
let pristine = try #require(
HVVMMFixture.machO(name),
"""
ipsws/ref_extract/macho_pristine/\(name) is required — it is the \
- only standalone Mach-O oracle this half of the port has
+ only standalone Mach-O fixture this half of the port has
"""
)
- try #require(HVVMMFixture.python != nil, HVVMMFixture.pythonMissing)
+ let reference = try #require(
+ FrozenReference.machO[name],
+ "no frozen reference run for this binary"
+ )
+ // The reference saw this exact file; if it has been replaced, nothing
+ // below is a comparison.
+ #expect(try Digest.sha256(of: pristine) == reference.pristineSHA256)
- let pythonCopy = try HVVMMFixture.copyFile(pristine, named: "\(name).python")
let swiftCopy = try HVVMMFixture.copyFile(pristine, named: "\(name).swift")
- defer { HVVMMFixture.discard(pythonCopy, swiftCopy) }
+ defer { HVVMMFixture.discard(swiftCopy) }
// Same sites, in the same order, before anything is written.
- let referenceSites = try JSONDecoder().decode(
- PythonOracle.MachOSites.self,
- from: PythonOracle.run("macho_sites", [pristine.path])
- ).sites
let sites = try DSCHVVMMPatcher.findStringSites(
inMachO: Data(contentsOf: pristine)
)
- #expect(sites.count == referenceSites.count)
+ #expect(sites.count == reference.sites.count)
#expect(!sites.isEmpty, "\(name) holds no kern.hv_vmm_present cstring")
- for (mine, theirs) in zip(sites, referenceSites) {
- #expect(mine.stringVMA == theirs.string_vma)
- #expect(mine.fileOffset == theirs.file_offset)
+ for (mine, theirs) in zip(sites, reference.sites) {
+ #expect(mine.stringVMA == theirs.stringVMA)
+ #expect(mine.fileOffset == theirs.fileOffset)
#expect(mine.section == theirs.section)
}
- let referenceCount = try JSONDecoder().decode(
- PythonOracle.MachORun.self,
- from: PythonOracle.run("patch_macho", [pythonCopy.path])
- ).count
let count = try DSCHVVMMPatcher.patchStandaloneMachO(at: swiftCopy, log: nil)
- #expect(count == referenceCount)
#expect(count == sites.count)
-
- let pristineBytes = try Data(contentsOf: pristine)
- let patchedByPython = try Data(contentsOf: pythonCopy)
- let patchedBySwift = try Data(contentsOf: swiftCopy)
- #expect(patchedByPython == patchedBySwift, "\(name): patched bytes differ")
- #expect(patchedBySwift != pristineBytes, "\(name): nothing was written")
+ #expect(try Digest.sha256(of: swiftCopy) == reference.patchedSHA256)
// Idempotent: the pristine literal is gone, so a second pass is a no-op.
+ // The reference's own second pass returned 0 and left its digest alone.
let rerun = try DSCHVVMMPatcher.patchStandaloneMachO(at: swiftCopy, log: nil)
- let afterRerun = try Data(contentsOf: swiftCopy)
#expect(rerun == 0)
- #expect(afterRerun == patchedBySwift)
+ #expect(try Digest.sha256(of: swiftCopy) == reference.patchedSHA256)
print("[hv_vmm] \(name): \(count) standalone cstring site(s), bytes match")
}
}
diff --git a/tests/FirmwarePatcherTests/DSCIOMFBForceKernTests.swift b/tests/FirmwarePatcherTests/DSCIOMFBForceKernTests.swift
index 6106272a..20712bdb 100644
--- a/tests/FirmwarePatcherTests/DSCIOMFBForceKernTests.swift
+++ b/tests/FirmwarePatcherTests/DSCIOMFBForceKernTests.swift
@@ -2,12 +2,14 @@
//
// There is no independent oracle for a patched dyld shared cache: `codesign -v`
// does not apply to a cache chunk, and nothing but the guest kernel reads the
-// slot hashes. The only reference is `scripts/patchers/cfw_patch_iomfb_force_kern.py`,
-// so the central test here runs THAT on one clone of the real cache, runs the
-// Swift on a second clone, and compares the two byte for byte — every chunk,
-// every code-directory slot, the `.symbols` side file, all of it. A port that
-// writes a different number of sites, or the same number in different places,
-// or re-attests a different set of pages, fails.
+// slot hashes. The only reference was
+// `scripts/patchers/cfw_patch_iomfb_force_kern.py`, and that Python has been
+// removed — so what it did on the real cache is frozen in `FrozenReference`
+// below: the 35 entry points it discovered, the address it resolved for each,
+// which four it refused to touch, and the SHA-256 of the one chunk it changed.
+// The Swift runs on a clone and is graded against those. A port that writes a
+// different number of sites, or the same number in different places, or
+// re-attests a different set of pages, lands on a different digest.
//
// The tests need the real cache. Point `VPHONE_DSC_PRISTINE` at a directory of
// `dyld_shared_cache_arm64e*` chunks, or leave the default
@@ -24,9 +26,173 @@
// `ipsws/scratch_dsc_forcekern`, and removed again at the end.
@testable import FirmwarePatcher
+import CryptoKit
import Foundation
import Testing
+// MARK: - The frozen reference
+
+/// What the reference Python found and wrote on the real 24A435 arm64e shared
+/// cache.
+///
+/// Recorded from two live runs at commit 78cbeea:
+///
+/// .venv/bin/python3 scripts/patchers/cfw.py \
+/// patch-iomfb-force-kern <clone of ipsws/ref_extract/dsc_pristine> [--dry-run]
+private enum FrozenReference {
+ /// One entry point, as the dry run named it:
+ ///
+ /// [+] _IOMobileFramebufferSwapBegin @ 0x22AC0C1B0: \
+ /// 'cbz x0, #0x22ac0c1c0' -> 'b _kern_SwapBegin' (0x22AC0C1CC)
+ struct Pair {
+ let publicName: String
+ let publicAddress: UInt64
+ let kernName: String
+ let kernAddress: UInt64
+ }
+
+ /// The 31 `[+]` lines of the dry run, in the order it printed them, each
+ /// giving the public entry point, its address, the kern sibling it would
+ /// branch to and that sibling's address.
+ static let forcedPairs: [Pair] = [
+ Pair(publicName: "_IOMobileFramebufferSwapBegin",
+ publicAddress: 0x2_2AC0_C1B0,
+ kernName: "_kern_SwapBegin", kernAddress: 0x2_2AC0_C1CC),
+ Pair(publicName: "_IOMobileFramebufferSwapCancel",
+ publicAddress: 0x2_2AC1_23C8,
+ kernName: "_kern_SwapCancel", kernAddress: 0x2_2AC3_D4AC),
+ Pair(publicName: "_IOMobileFramebufferSwapCancelAll",
+ publicAddress: 0x2_2AC1_24F4,
+ kernName: "_kern_SwapCancelAll", kernAddress: 0x2_2AC1_2510),
+ Pair(publicName: "_IOMobileFramebufferSwapCancelAllGetCurrent",
+ publicAddress: 0x2_2AC1_2468,
+ kernName: "_kern_SwapCancelAllGetCurrent", kernAddress: 0x2_2AC1_2484),
+ Pair(publicName: "_IOMobileFramebufferSwapDebugInfo",
+ publicAddress: 0x2_2AC0_C734,
+ kernName: "_kern_SwapDebugInfo", kernAddress: 0x2_2AC0_C328),
+ Pair(publicName: "_IOMobileFramebufferSwapEnd",
+ publicAddress: 0x2_2AC0_C750,
+ kernName: "_kern_SwapEnd", kernAddress: 0x2_2AC0_C334),
+ Pair(publicName: "_IOMobileFramebufferSwapGetCurrent",
+ publicAddress: 0x2_2AC3_A85C,
+ kernName: "_kern_SwapGetCurrent", kernAddress: 0x2_2AC3_D518),
+ Pair(publicName: "_IOMobileFramebufferSwapSecureLayer",
+ publicAddress: 0x2_2AC3_A528,
+ kernName: "_kern_SwapSecureLayer", kernAddress: 0x2_2AC3_CB9C),
+ Pair(publicName: "_IOMobileFramebufferSwapSetAmbientLux",
+ publicAddress: 0x2_2AC0_D0F4,
+ kernName: "_kern_SwapSetAmbientLux", kernAddress: 0x2_2AC0_D110),
+ Pair(publicName: "_IOMobileFramebufferSwapSetBrightness",
+ publicAddress: 0x2_2AC0_D214,
+ kernName: "_kern_SwapSetBrightness", kernAddress: 0x2_2AC0_D230),
+ Pair(publicName: "_IOMobileFramebufferSwapSetBrightnessLimit",
+ publicAddress: 0x2_2AC1_25B0,
+ kernName: "_kern_SwapSetBrightnessLimit", kernAddress: 0x2_2AC1_25CC),
+ Pair(publicName: "_IOMobileFramebufferSwapSetColorMatrix",
+ publicAddress: 0x2_2AC3_A800,
+ kernName: "_kern_SwapSetColorMatrix", kernAddress: 0x2_2AC3_D2E0),
+ Pair(publicName: "_IOMobileFramebufferSwapSetDisplayEdr",
+ publicAddress: 0x2_2AC1_2634,
+ kernName: "_kern_SwapSetDisplayEdr", kernAddress: 0x2_2AC1_2650),
+ Pair(publicName: "_IOMobileFramebufferSwapSetDisplayEdrHeadroom",
+ publicAddress: 0x2_2AC1_278C,
+ kernName: "_kern_SwapSetDisplayEdrHeadroom", kernAddress: 0x2_2AC1_2724),
+ Pair(publicName: "_IOMobileFramebufferSwapSetEventSignal",
+ publicAddress: 0x2_2AC0_BE50,
+ kernName: "_kern_SwapSetEventSignal", kernAddress: 0x2_2AC0_CEBC),
+ Pair(publicName: "_IOMobileFramebufferSwapSetEventSignalOnGlass",
+ publicAddress: 0x2_2AC3_A560,
+ kernName: "_kern_SwapSetEventSignalOnGlass", kernAddress: 0x2_2AC3_CDB0),
+ Pair(publicName: "_IOMobileFramebufferSwapSetEventWait",
+ publicAddress: 0x2_2AC0_BE6C,
+ kernName: "_kern_SwapSetEventWait", kernAddress: 0x2_2AC0_BF58),
+ Pair(publicName: "_IOMobileFramebufferSwapSetIndicatorBrightnessLimit",
+ publicAddress: 0x2_2AC1_2594,
+ kernName: "_kern_SwapSetIndicatorBrightnessLimit", kernAddress: 0x2_2AC1_26B8),
+ Pair(publicName: "_IOMobileFramebufferSwapSetLFCTimestamps",
+ publicAddress: 0x2_2AC3_A7AC,
+ kernName: "_kern_SwapSetLFCTimestamps", kernAddress: 0x2_2AC3_DA6C),
+ Pair(publicName: "_IOMobileFramebufferSwapSetLayer",
+ publicAddress: 0x2_2AC0_CEA0,
+ kernName: "_kern_SwapSetLayer", kernAddress: 0x2_2AC0_C8F4),
+ Pair(publicName: "_IOMobileFramebufferSwapSetLayerEDRCompensation",
+ publicAddress: 0x2_2AC0_C194,
+ kernName: "_kern_SwapSetLayerEDRCompensation", kernAddress: 0x2_2AC0_BE88),
+ Pair(publicName: "_IOMobileFramebufferSwapSetPostBlendLayer",
+ publicAddress: 0x2_2AC3_A544,
+ kernName: "_kern_SwapSetPostBlendLayer", kernAddress: 0x2_2AC3_CC3C),
+ Pair(publicName: "_IOMobileFramebufferSwapSetPostBlendLayerEventSignal",
+ publicAddress: 0x2_2AC3_A5B4,
+ kernName: "_kern_SwapSetPostBlendLayerEventSignal", kernAddress: 0x2_2AC3_CE98),
+ Pair(publicName: "_IOMobileFramebufferSwapSetPostBlendLayerEventSignalOnGlass",
+ publicAddress: 0x2_2AC3_A598,
+ kernName: "_kern_SwapSetPostBlendLayerEventSignalOnGlass",
+ kernAddress: 0x2_2AC3_CE58),
+ Pair(publicName: "_IOMobileFramebufferSwapSetPostBlendLayerEventWait",
+ publicAddress: 0x2_2AC3_A57C,
+ kernName: "_kern_SwapSetPostBlendLayerEventWait", kernAddress: 0x2_2AC3_CDE8),
+ Pair(publicName: "_IOMobileFramebufferSwapSetPulseWidthMaximization",
+ publicAddress: 0x2_2AC4_1AC0,
+ kernName: "_kern_SwapSetPulseWidthMaximization", kernAddress: 0x2_2AC3_D1F4),
+ Pair(publicName: "_IOMobileFramebufferSwapSetResTransitionStrength",
+ publicAddress: 0x2_2AC4_1ADC,
+ kernName: "_kern_SwapSetResTransitionStrength", kernAddress: 0x2_2AC3_D238),
+ Pair(publicName: "_IOMobileFramebufferSwapSetSecureAnimation",
+ publicAddress: 0x2_2AC0_F354,
+ kernName: "_kern_SwapSetSecureAnimation", kernAddress: 0x2_2AC0_F370),
+ Pair(publicName: "_IOMobileFramebufferSwapSubtitleRegion",
+ publicAddress: 0x2_2AC3_A720,
+ kernName: "_kern_SwapSubtitleRegion", kernAddress: 0x2_2AC3_CF08),
+ Pair(publicName: "_IOMobileFramebufferSwapWait",
+ publicAddress: 0x2_2AC0_C298,
+ kernName: "_kern_SwapWait", kernAddress: 0x2_2AC0_C2B4),
+ Pair(publicName: "_IOMobileFramebufferSwapWaitWithTimeout",
+ publicAddress: 0x2_2AC3_A840,
+ kernName: "_kern_SwapWaitWithTimeout", kernAddress: 0x2_2AC3_D420),
+ ]
+
+ /// The four `[=] … not a thin trampoline; leaving on virt path` lines. The
+ /// reference discovered these and deliberately declined to rewrite them, so
+ /// a shape check that accepted everything would disagree here.
+ static let leftOnVirtPath: [String] = [
+ "_IOMobileFramebufferSwapSetBlit",
+ "_IOMobileFramebufferSwapSetIndicatorBrightness",
+ "_IOMobileFramebufferSwapSetParams",
+ "_IOMobileFramebufferSwapSignal",
+ ]
+
+ /// Python: `IOMFB force-kern complete: 31 newly forced, 0 already -> _kern_*`.
+ static let newlyForced = 31
+
+ /// Every entry point the reference considered — the 31 it forced plus the
+ /// four it left alone.
+ static var discoveredNames: Set<String> {
+ Set(forcedPairs.map(\.publicName)).union(leftOnVirtPath)
+ }
+
+ static var publicAddressesByName: [String: UInt64] {
+ Dictionary(uniqueKeysWithValues: forcedPairs.map { ($0.publicName, $0.publicAddress) })
+ }
+
+ /// `cmp -s` against the pristine tree after the wet run: exactly one chunk
+ /// moved, to this digest, from `shasum -a 256 <output>/…arm64e.38`.
+ ///
+ /// The digest covers the re-attestation as well as the 31 branches — the
+ /// Python logged `re-attesting 31 modified page(s)…` and then `re-attest:
+ /// updated 5 slot hash(es) across 1 chunk(s)` (slots 2562, 2563, 2564,
+ /// 2574 and 2576 of `dyld_shared_cache_arm64e.38`).
+ ///
+ /// Two further runs pinned the edges. Re-run over its own output: `all 31
+ /// entrypoint(s) already forced; nothing to patch/re-attest`, `0 newly
+ /// forced, 31 already`, and this digest unchanged. `--dry-run` on a fresh
+ /// clone: the 31 `[+]` lines above, `would re-attest 31 page(s)`, and no
+ /// chunk changed at all.
+ static let changedChunks: [String: String] = [
+ "dyld_shared_cache_arm64e.38":
+ "7cb82d8c33f1949197cf95aaf2286c76c4ecb85826d40f66437d33e707e3f879",
+ ]
+}
+
// MARK: - Fixture discovery
private enum ForceKernFixture {
@@ -74,16 +240,6 @@ private enum ForceKernFixture {
?? repoRoot.appendingPathComponent("ipsws/scratch_dsc_forcekern")
}
- /// 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 cfwDriver: URL {
- repoRoot.appendingPathComponent("scripts/patchers/cfw.py")
- }
-
static func cloneCache(named name: String) throws -> URL {
guard let pristine else { throw CocoaError(.fileNoSuchFile) }
let destination = scratchRoot.appendingPathComponent(name)
@@ -151,28 +307,6 @@ private enum ForceKernShell {
)
}
- /// Run the reference patcher through the CLI the install scripts use.
- static func runReference(on chunks: URL, dryRun: Bool) throws -> Result {
- guard let python = ForceKernFixture.python else { throw CocoaError(.fileNoSuchFile) }
- return try run(
- executable: python,
- arguments: [
- ForceKernFixture.cfwDriver.path,
- "patch-iomfb-force-kern",
- chunks.path,
- ] + (dryRun ? ["--dry-run"] : [])
- )
- }
-
- /// `N` out of the reference's `complete: N newly forced, M already -> _kern_*`.
- static func newlyForced(in output: String) -> Int? {
- guard let line = output.split(separator: "\n").last(where: {
- $0.contains("IOMFB force-kern complete:")
- }) else { return nil }
- let after = line.split(separator: ":").last ?? ""
- return Int(after.trimmingCharacters(in: .whitespaces).split(separator: " ").first ?? "")
- }
-
/// Byte-compare two cache directories, file by file. Returns the paths that
/// differ, plus the count compared.
static func diffTrees(_ left: URL, _ right: URL) throws -> (differing: [String], compared: Int) {
@@ -198,146 +332,140 @@ private enum ForceKernShell {
}
}
-// MARK: - Parity against the reference Python
+// MARK: - Digests
+
+/// SHA-256 of a cache chunk, streamed so a 131 MB file never lands in memory
+/// whole. The hex spelling matches `shasum -a 256`, which produced the frozen
+/// digests.
+private enum Digest {
+ static func sha256(of url: URL) throws -> String {
+ let handle = try FileHandle(forReadingFrom: url)
+ defer { try? handle.close() }
+ var hasher = SHA256()
+ while let block = try handle.read(upToCount: 4 << 20), !block.isEmpty {
+ hasher.update(data: block)
+ }
+ return hasher.finalize().map { String(format: "%02x", $0) }.joined()
+ }
+
+ /// SHA-256 of every chunk file, so "nothing changed" is checkable without
+ /// keeping a second copy around.
+ static func chunkDigests(of directory: URL) throws -> [String: String] {
+ var digests: [String: String] = [:]
+ for name in try FileManager.default.contentsOfDirectory(atPath: directory.path).sorted() {
+ digests[name] = try sha256(of: directory.appendingPathComponent(name))
+ }
+ return digests
+ }
+
+ /// Assert that `directory` holds exactly the chunks the reference changed,
+ /// with exactly the reference's bytes.
+ static func expectMatchesReference(_ directory: URL) throws {
+ let pristine = try #require(ForceKernFixture.pristine, ForceKernFixture.missing)
+ let pristineDigests = try chunkDigests(of: pristine)
+ let mine = try chunkDigests(of: directory)
+ let changed = mine.filter { pristineDigests[$0.key] != $0.value }.keys.sorted()
+ #expect(changed == FrozenReference.changedChunks.keys.sorted())
+ for name in changed {
+ let frozen = FrozenReference.changedChunks[name] ?? "(not a chunk the Python moved)"
+ #expect(mine[name] == frozen, "\(name): Swift \(mine[name] ?? "—"), reference \(frozen)")
+ }
+ }
+}
+
+// MARK: - Parity against the frozen reference
@Suite(.serialized, .enabled(if: ForceKernFixture.runs, ForceKernFixture.skipReason))
struct DSCIOMFBForceKernParityTests {
/// The one test that decides whether this port is done.
- @Test("Python and Swift force-kern produce byte-identical caches")
+ @Test("Swift force-kern reproduces the reference cache byte for byte")
func matchesReferenceByteForByte() throws {
_ = try #require(ForceKernFixture.pristine, ForceKernFixture.missing)
- try #require(
- ForceKernFixture.python != nil,
- "project venv is required to run the reference patcher"
- )
- let pythonClone = try ForceKernFixture.cloneCache(named: "python")
let swiftClone = try ForceKernFixture.cloneCache(named: "swift")
- defer { ForceKernFixture.discard(pythonClone, swiftClone) }
-
- // Both clones start identical — otherwise the comparison below proves
- // nothing at all.
- let before = try ForceKernShell.diffTrees(pythonClone, swiftClone)
- #expect(before.differing.isEmpty, "clones differed before patching: \(before.differing)")
- #expect(before.compared > 1)
-
- let reference = try ForceKernShell.runReference(on: pythonClone, dryRun: false)
- #expect(reference.status == 0, "reference patcher failed:\n\(reference.stderr)")
- let referenceSites = try #require(
- ForceKernShell.newlyForced(in: reference.stdout),
- "could not read the reference's site count from:\n\(reference.stdout)"
- )
+ defer { ForceKernFixture.discard(swiftClone) }
let outcome = try DSCIOMFBForceKernPatcher.patch(
chunksDirectory: swiftClone,
log: nil
)
- print("[force-kern] python wrote \(referenceSites) site(s), swift wrote \(outcome.writtenSiteCount)")
- #expect(
- outcome.writtenSiteCount == referenceSites,
- "swift wrote \(outcome.writtenSiteCount) sites, python wrote \(referenceSites)"
- )
- #expect(referenceSites > 0, "the reference patched nothing — the fixture is not force-kernable")
-
- let after = try ForceKernShell.diffTrees(pythonClone, swiftClone)
#expect(
- after.differing.isEmpty,
- "patched clones differ in: \(after.differing)"
+ outcome.writtenSiteCount == FrozenReference.newlyForced,
+ "swift wrote \(outcome.writtenSiteCount) sites, reference \(FrozenReference.newlyForced)"
)
- #expect(after.compared == before.compared)
- print("[force-kern] \(after.compared) file(s) compared byte for byte, all identical")
-
- // And the other direction: the reference must recognise the Swift's
- // output as already forced. That is a sharper check than the byte
- // comparison — it says the branch this port encodes is the one the
- // reference's own idempotence test decodes and accepts, rather than
- // some other encoding that happens to hash the same.
- let reRun = try ForceKernShell.runReference(on: swiftClone, dryRun: false)
- #expect(reRun.status == 0, "reference re-run failed:\n\(reRun.stderr)")
+ // The same entry points, not merely the same count.
#expect(
- ForceKernShell.newlyForced(in: reRun.stdout) == 0,
- "the reference re-forced sites the Swift had already written:\n\(reRun.stdout)"
+ Set(outcome.forced.map(\.entry.publicName))
+ == Set(FrozenReference.forcedPairs.map(\.publicName))
)
- let afterReRun = try ForceKernShell.diffTrees(pythonClone, swiftClone)
- #expect(afterReRun.differing.isEmpty, "the reference's re-run changed bytes")
+ #expect(Set(outcome.notTrampolines.map(\.entry.publicName))
+ == Set(FrozenReference.leftOnVirtPath))
+
+ try Digest.expectMatchesReference(swiftClone)
}
- /// The reference's own idempotence claim, applied across implementations:
- /// the Swift run over a cache the Python already patched must write nothing
- /// and leave every byte alone.
- @Test("Swift is a no-op on a cache the Python already forced")
- func swiftIsIdempotentOverPythonOutput() throws {
+ /// The reference's own idempotence claim: a second pass over a cache this
+ /// patch already forced must write nothing and leave every byte alone. The
+ /// Python printed `all 31 entrypoint(s) already forced; nothing to
+ /// patch/re-attest` here, with its digest unchanged.
+ @Test("A second run is a no-op on an already-forced cache")
+ func secondRunIsANoOp() throws {
_ = try #require(ForceKernFixture.pristine, ForceKernFixture.missing)
- try #require(ForceKernFixture.python != nil, "project venv is required")
let clone = try ForceKernFixture.cloneCache(named: "idempotence")
defer { ForceKernFixture.discard(clone) }
- let reference = try ForceKernShell.runReference(on: clone, dryRun: false)
- #expect(reference.status == 0, "reference patcher failed:\n\(reference.stderr)")
+ let first = try DSCIOMFBForceKernPatcher.patch(chunksDirectory: clone, log: nil)
+ #expect(first.writtenSiteCount == FrozenReference.newlyForced)
- let hashesBefore = try Self.chunkDigests(of: clone)
+ let hashesBefore = try Digest.chunkDigests(of: clone)
let second = try DSCIOMFBForceKernPatcher.patch(chunksDirectory: clone, log: nil)
#expect(second.writtenSiteCount == 0, "a second pass rewrote \(second.writtenSiteCount) site(s)")
#expect(second.reattestation == nil, "a second pass re-attested pages it did not dirty")
- #expect(!second.alreadyForced.isEmpty)
- let hashesAfter = try Self.chunkDigests(of: clone)
+ #expect(second.alreadyForced.count == FrozenReference.newlyForced)
+ let hashesAfter = try Digest.chunkDigests(of: clone)
#expect(hashesAfter == hashesBefore, "a no-op run changed bytes")
+
+ try Digest.expectMatchesReference(clone)
}
/// A dry run must classify everything and touch nothing.
- @Test("A dry run reports the same sites and writes no bytes")
+ @Test("A dry run reports the reference's sites and writes no bytes")
func dryRunWritesNothing() throws {
_ = try #require(ForceKernFixture.pristine, ForceKernFixture.missing)
let clone = try ForceKernFixture.cloneCache(named: "dryrun")
defer { ForceKernFixture.discard(clone) }
- let hashesBefore = try Self.chunkDigests(of: clone)
+ let hashesBefore = try Digest.chunkDigests(of: clone)
let dry = try DSCIOMFBForceKernPatcher.patch(
chunksDirectory: clone,
dryRun: true,
log: nil
)
- #expect(dry.writtenSiteCount > 0, "the dry run classified no forcible site")
+ #expect(dry.writtenSiteCount == FrozenReference.newlyForced)
#expect(dry.records.isEmpty)
#expect(dry.reattestation == nil)
- let hashesAfter = try Self.chunkDigests(of: clone)
+ let hashesAfter = try Digest.chunkDigests(of: clone)
#expect(hashesAfter == hashesBefore, "a dry run wrote to the cache")
let wet = try DSCIOMFBForceKernPatcher.patch(chunksDirectory: clone, log: nil)
#expect(wet.writtenSiteCount == dry.writtenSiteCount)
}
-
- /// SHA-256 of every chunk file, so "nothing changed" is checkable without
- /// keeping a second copy around.
- private static func chunkDigests(of directory: URL) throws -> [String: String] {
- var digests: [String: String] = [:]
- for name in try FileManager.default.contentsOfDirectory(atPath: directory.path).sorted() {
- let result = try ForceKernShell.run(
- executable: URL(fileURLWithPath: "/usr/bin/shasum"),
- arguments: ["-a", "256", directory.appendingPathComponent(name).path]
- )
- guard result.status == 0 else { throw CocoaError(.fileReadUnknown) }
- digests[name] = String(result.stdout.prefix(64))
- }
- return digests
- }
}
// MARK: - Discovery and classification
@Suite(.serialized, .enabled(if: ForceKernFixture.runs, ForceKernFixture.skipReason))
struct DSCIOMFBForceKernDiscoveryTests {
- /// Discovery has to agree with the reference's, which reads the same image
+ /// Discovery has to agree with the reference's, which read the same image
/// through `ipsw dyld symaddr`. Compared here without `ipsw`: the pairs the
- /// resolver finds are the pairs the reference logs.
+ /// resolver finds are the pairs the reference logged.
@Test("Every discovered pair matches the reference's, name and address")
func discoveryMatchesReference() throws {
let pristine = try #require(ForceKernFixture.pristine, ForceKernFixture.missing)
- try #require(ForceKernFixture.python != nil, "project venv is required")
let resolver = try DSCSymbolResolver(
mainCacheURL: pristine.appendingPathComponent("dyld_shared_cache_arm64e")
@@ -345,38 +473,26 @@ struct DSCIOMFBForceKernDiscoveryTests {
let entries = try DSCIOMFBForceKernPatcher.discoverEntryPoints(resolver: resolver)
#expect(entries.count >= DSCIOMFBForceKernPatcher.requiredSuffixes.count)
- // The reference names every pair it considers in its dry-run log, as
- // either a `[+] <public> @ 0xVA: … -> 'b <kern>' (0xVA)` or a
- // `[=] <public> not a thin trampoline` line.
- let clone = try ForceKernFixture.cloneCache(named: "discovery")
- defer { ForceKernFixture.discard(clone) }
- let reference = try ForceKernShell.runReference(on: clone, dryRun: true)
- #expect(reference.status == 0, "reference dry run failed:\n\(reference.stderr)")
-
- var referencePairs: [String: UInt64] = [:]
- var referenceNames: Set<String> = []
- for line in reference.stdout.split(separator: "\n") {
- guard let name = line.split(separator: " ").first(where: {
- $0.hasPrefix(DSCIOMFBForceKernPatcher.publicPrefix)
- }) else { continue }
- referenceNames.insert(String(name))
- // "… @ 0x22AC0C1B0: …" — the public address it decided to rewrite.
- guard let at = line.range(of: " @ 0x") else { continue }
- let rest = line[at.upperBound...].prefix { $0.isHexDigit }
- if let address = UInt64(rest, radix: 16) { referencePairs[String(name)] = address }
- }
-
let discovered = Set(entries.map(\.publicName))
- let disagreement = discovered.symmetricDifference(referenceNames).sorted()
- #expect(discovered == referenceNames, "discovery differs from the reference: \(disagreement)")
- for entry in entries {
- guard let referenceAddress = referencePairs[entry.publicName] else { continue }
- let mine = String(entry.publicAddress, radix: 16)
- let theirs = String(referenceAddress, radix: 16)
+ let expected = FrozenReference.discoveredNames
+ let disagreement = discovered.symmetricDifference(expected).sorted()
+ #expect(discovered == expected, "discovery differs from the reference: \(disagreement)")
+
+ // The 31 the reference resolved an address for — it printed no address
+ // for the four it left on the virt path.
+ let byName = Dictionary(uniqueKeysWithValues: entries.map { ($0.publicName, $0) })
+ for pair in FrozenReference.forcedPairs {
+ let entry = try #require(byName[pair.publicName], "\(pair.publicName) was not discovered")
+ let mine = String(entry.publicAddress, radix: 16, uppercase: true)
+ let theirs = String(pair.publicAddress, radix: 16, uppercase: true)
#expect(
- referenceAddress == entry.publicAddress,
- "\(entry.publicName): swift 0x\(mine) vs reference 0x\(theirs)"
+ entry.publicAddress == pair.publicAddress,
+ "\(pair.publicName): swift 0x\(mine) vs reference 0x\(theirs)"
)
+ // …and the sibling it would branch to, which is the half of the
+ // pair a name-only comparison would miss.
+ #expect(entry.kernName == pair.kernName)
+ #expect(entry.kernAddress == pair.kernAddress)
}
}
@@ -407,9 +523,9 @@ struct DSCIOMFBForceKernDiscoveryTests {
}
/// The shape check has to be discriminating, not a rubber stamp: the
- /// reference leaves several entry points on the virt path on this cache, and
- /// so must this. A matcher that accepted everything would still pass the
- /// byte comparison only if it happened to agree — it does not, so pin it.
+ /// reference left four entry points on the virt path on this cache, and so
+ /// must this. A matcher that accepted everything would still pass the byte
+ /// comparison only if it happened to agree — it does not, so pin it.
@Test("Non-trampoline entry points are recognised and left alone")
func nonTrampolinesAreLeftAlone() throws {
let pristine = try #require(ForceKernFixture.pristine, ForceKernFixture.missing)
@@ -422,7 +538,10 @@ struct DSCIOMFBForceKernDiscoveryTests {
log: nil
)
- #expect(!dry.notTrampolines.isEmpty, "every discovered entry point matched the shape")
+ #expect(
+ dry.notTrampolines.map(\.entry.publicName).sorted()
+ == FrozenReference.leftOnVirtPath.sorted()
+ )
#expect(dry.forced.count + dry.notTrampolines.count + dry.alreadyForced.count == dry.sites.count)
// And each rejection is a real one: its first instruction is not the
@@ -453,6 +572,9 @@ struct DSCIOMFBForceKernDiscoveryTests {
let outcome = try DSCIOMFBForceKernPatcher.patch(chunksDirectory: clone, log: nil)
#expect(outcome.records.count == outcome.writtenSiteCount)
+ let kernAddresses = Dictionary(
+ uniqueKeysWithValues: FrozenReference.forcedPairs.map { ($0.publicAddress, $0.kernAddress) }
+ )
let chunks = try DSCChunkSet(directory: clone)
let disassembler = ARM64Disassembler()
for record in outcome.records {
@@ -468,6 +590,15 @@ struct DSCIOMFBForceKernDiscoveryTests {
)
)
#expect(instruction.mnemonic == "b")
+ // …and it lands on the kern sibling the reference named for this
+ // entry point, rather than merely on some branch.
+ let target = try #require(kernAddresses[address], "0x\(String(address, radix: 16)) is not a reference site")
+ let expected = "0x\(String(target, radix: 16))"
+ let site = "0x\(String(address, radix: 16))"
+ #expect(
+ instruction.operandString == expected,
+ "\(site) branches to \(instruction.operandString), reference paired it with \(expected)"
+ )
}
}
}
diff --git a/tests/FirmwarePatcherTests/DSCIOMFBSwapEndTests.swift b/tests/FirmwarePatcherTests/DSCIOMFBSwapEndTests.swift
index 3939d5c4..a610c08d 100644
--- a/tests/FirmwarePatcherTests/DSCIOMFBSwapEndTests.swift
+++ b/tests/FirmwarePatcherTests/DSCIOMFBSwapEndTests.swift
@@ -2,13 +2,14 @@
//
// There is no independent checker for a patched dyld shared cache: `codesign -v`
// does not apply to a cache chunk, and the only other implementation of this
-// patch is `scripts/patchers/cfw_patch_iomfb_swapend.py`. So the parity test is
-// literal. Two clones of the real 24A435 arm64e cache; the Python patches one
-// through its own CLI (`cfw.py patch-iomfb-swapend`, exactly as
-// `cfw_install*.sh` and `cfw-kit` invoke it), `DSCIOMFBSwapEndPatcher` patches
-// the other, and then all 79 chunk files are compared byte for byte. Anything
-// short of byte-identical is a failing port, including a patch that lands in the
-// right place but re-attests a different page.
+// patch was `scripts/patchers/cfw_patch_iomfb_swapend.py`, driven through
+// `cfw.py patch-iomfb-swapend` exactly as `cfw_install*.sh` and `cfw-kit`
+// invoked it. That Python has been removed, so what it produced on the real
+// 24A435 arm64e cache — at each of the three target sizes — is frozen in
+// `FrozenReference` below: the site it landed on, the size it found there, and
+// the SHA-256 of the one chunk it changed. `DSCIOMFBSwapEndPatcher` runs on a
+// clone and is graded against those. A patch that lands in the right place but
+// re-attests a different page lands on a different digest.
//
// The cache is required. `VPHONE_DSC_PRISTINE` points at it, defaulting to
// `ipsws/ref_extract/dsc_pristine`, and its absence FAILS rather than passing
@@ -28,10 +29,78 @@
// are pinned on every machine, fixture or no fixture.
import Capstone
+import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
+// MARK: - The frozen reference
+
+/// What the reference Python did on the real 24A435 arm64e shared cache.
+///
+/// Recorded from live runs at commit 78cbeea, one per target size:
+///
+/// .venv/bin/python3 scripts/patchers/cfw.py patch-iomfb-swapend \
+/// <clone of ipsws/ref_extract/dsc_pristine> --target-size <size>
+private enum FrozenReference {
+ /// Python: `[.] _kern_SwapEnd @ 0x22AC0C334`.
+ static let functionVMA: UInt64 = 0x2_2AC0_C334
+
+ /// Python: the `at 0x22AC0C358` on every `patched`/`already` line — the
+ /// `mov w3, #imm` of the external-method call set-up.
+ static let siteVMA: UInt64 = 0x2_2AC0_C358
+
+ /// Python: the left half of `size 0x6E0 -> …`, i.e. what this cache's own
+ /// userland sends today.
+ static let originalSize: UInt32 = 0x6E0
+
+ /// What one target size produced.
+ struct SizeRun {
+ /// Sites the Python's `[+] patched … size … at …` lines counted.
+ let sitesWritten: Int
+ /// Whether it reported `[=] already 0x… at 0x22AC0C358` instead.
+ let wasAlreadyCorrect: Bool
+ /// The chunks `cmp -s` found moved against the pristine tree, with the
+ /// SHA-256 `shasum -a 256` read off each afterwards.
+ let changedChunks: [String: String]
+ }
+
+ /// `--target-size 0x588` (the 26.4 base). Python: `patched … _kern_SwapEnd
+ /// size 0x6E0 -> 0x588 at 0x22AC0C358`, then `re-attest: wrote slot 2563 of
+ /// dyld_shared_cache_arm64e.38` and `updated 1 slot hash(es) across 1
+ /// chunk(s)`.
+ ///
+ /// `--target-size 0x560` (the 26.1 base) is the same story with a different
+ /// immediate, and so a different digest for the same chunk.
+ ///
+ /// `--target-size 0x6E0` is the size the cache already sends: Python
+ /// printed `already 0x6E0 at 0x22AC0C358; re-attesting page only`, the
+ /// re-attestation was a no-op (`slot already matches`), and no chunk moved
+ /// at all.
+ ///
+ /// Re-running any of the three over its own output printed `already 0x… at
+ /// 0x22AC0C358`, wrote no site, and left the digest below standing.
+ static let bySize: [UInt32: SizeRun] = [
+ 0x588: SizeRun(
+ sitesWritten: 1,
+ wasAlreadyCorrect: false,
+ changedChunks: [
+ "dyld_shared_cache_arm64e.38":
+ "b49bbe7872273242c73973a451d9dac1a7ec803da8efeb5dcd1e04c7b5292f1d",
+ ]
+ ),
+ 0x560: SizeRun(
+ sitesWritten: 1,
+ wasAlreadyCorrect: false,
+ changedChunks: [
+ "dyld_shared_cache_arm64e.38":
+ "72f07ea587a523ed602d30f8f9a3508d291451a75ab90a0c578313d208b8a0e4",
+ ]
+ ),
+ 0x6E0: SizeRun(sitesWritten: 0, wasAlreadyCorrect: true, changedChunks: [:]),
+ ]
+}
+
// MARK: - Fixture discovery
private enum SwapEndFixture {
@@ -67,11 +136,6 @@ private enum SwapEndFixture {
static let skipReason: Comment =
"VPHONE_DSC_FIXTURE_OPTIONAL=1 and no dyld_shared_cache_arm64e fixture present"
- static let venvMissing: Comment = """
- the project venv is required for the cross-check against \
- scripts/patchers/cfw_patch_iomfb_swapend.py — run `make setup_venv`
- """
-
/// Where clones go. Deliberately *not* under `ipsws/ref_extract`: that tree
/// is the pristine reference the rest of the suite compares against, and
/// nothing here may leave anything in it.
@@ -81,17 +145,6 @@ private enum SwapEndFixture {
?? repoRoot.appendingPathComponent("ipsws/scratch_dsciomfbswapend")
}
- /// 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
- }
-
- /// The CLI the install scripts call, which is the contract being preserved.
- static var patcherCLI: URL {
- repoRoot.appendingPathComponent("scripts/patchers/cfw.py")
- }
-
/// 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) }
@@ -158,43 +211,20 @@ private enum SwapEndSubprocess {
}
}
-// MARK: - What the reference Python did, read back off its own output
-
-/// The Python prints one line per site it writes. Parsing that is how the test
-/// learns the *number of sites* and the address the reference chose, without
-/// this file writing either of them down.
-private struct PythonSwapEndRun {
- /// Addresses the Python said it wrote.
- let siteVMAs: [UInt64]
- /// The address it reported when it found the size already correct.
- let alreadyCorrectVMA: UInt64?
- let output: String
-
- var sitesWritten: Int { siteVMAs.count }
- var alreadyCorrect: Bool { alreadyCorrectVMA != nil }
- /// The site the Python landed on, whether or not it wrote to it.
- var siteVMA: UInt64? { siteVMAs.first ?? alreadyCorrectVMA }
-
- init(output: String) {
- self.output = output
- var written: [UInt64] = []
- var already: UInt64?
- for line in output.split(separator: "\n") {
- if line.contains("[+] patched"), line.contains("_kern_SwapEnd size"),
- let match = line.firstMatch(of: /\bat 0x([0-9A-Fa-f]+)\b/),
- let vma = UInt64(match.1, radix: 16)
- {
- written.append(vma)
- }
- if line.contains("[=] already"),
- let match = line.firstMatch(of: /\bat 0x([0-9A-Fa-f]+)\b/),
- let vma = UInt64(match.1, radix: 16)
- {
- already = vma
- }
+// MARK: - Digests
+
+/// SHA-256 of a cache chunk, streamed so a 131 MB file never lands in memory
+/// whole. The hex spelling matches `shasum -a 256`, which produced the frozen
+/// digests.
+private enum Digest {
+ static func sha256(of url: URL) throws -> String {
+ let handle = try FileHandle(forReadingFrom: url)
+ defer { try? handle.close() }
+ var hasher = SHA256()
+ while let block = try handle.read(upToCount: 4 << 20), !block.isEmpty {
+ hasher.update(data: block)
}
- siteVMAs = written
- alreadyCorrectVMA = already
+ return hasher.finalize().map { String(format: "%02x", $0) }.joined()
}
}
@@ -371,27 +401,10 @@ struct DSCIOMFBSwapEndShapeTests {
}
}
-// MARK: - 2 · Parity against the Python, on the real cache
+// MARK: - 2 · Parity against the frozen reference, on the real cache
@Suite(.serialized, .enabled(if: SwapEndFixture.runs, SwapEndFixture.skipReason))
struct DSCIOMFBSwapEndParityTests {
- /// Run the reference Python through the CLI the install scripts use.
- private func runPython(on directory: URL, targetSize: UInt32) throws -> PythonSwapEndRun {
- let python = try #require(SwapEndFixture.python, SwapEndFixture.venvMissing)
- let result = try SwapEndSubprocess.run(
- executable: python,
- arguments: [
- SwapEndFixture.patcherCLI.path,
- "patch-iomfb-swapend",
- directory.path,
- "--target-size",
- "0x" + String(targetSize, radix: 16),
- ]
- )
- #expect(result.status == 0, "python patcher failed: \(result.stdout)\(result.stderr)")
- return PythonSwapEndRun(output: result.stdout)
- }
-
/// The three sizes that matter: the 26.4 base's, the 26.1 base's, and the
/// size this cache's own userland already sends — which is the case where
/// the right answer is to write nothing at all.
@@ -402,18 +415,20 @@ struct DSCIOMFBSwapEndParityTests {
static let targetSizes: [UInt32] = [0x588, 0x560, 0x6E0]
@Test(
- "Swift and Python patch the real cache to the same bytes",
+ "Swift patches the real cache to the reference's bytes",
arguments: targetSizes
)
- func matchesPythonByteForByte(targetSize: UInt32) throws {
+ func matchesTheReferenceByteForByte(targetSize: UInt32) throws {
let pristine = try #require(SwapEndFixture.pristine, SwapEndFixture.missing)
let suffix = String(targetSize, radix: 16)
+ let reference = try #require(
+ FrozenReference.bySize[targetSize],
+ "no frozen reference run for this target size"
+ )
- let pythonClone = try SwapEndFixture.cloneCache(named: "python_\(suffix)")
let swiftClone = try SwapEndFixture.cloneCache(named: "swift_\(suffix)")
- defer { SwapEndFixture.discard(pythonClone, swiftClone) }
+ defer { SwapEndFixture.discard(swiftClone) }
- let reference = try runPython(on: pythonClone, targetSize: targetSize)
let mine = try DSCIOMFBSwapEndPatcher.patch(
chunksDirectory: swiftClone,
targetSize: targetSize,
@@ -423,42 +438,35 @@ struct DSCIOMFBSwapEndParityTests {
// Same number of sites, at the same address, from the same source size.
#expect(
mine.sitesWritten == reference.sitesWritten,
- "swift wrote \(mine.sitesWritten) site(s), python wrote \(reference.sitesWritten)"
+ "swift wrote \(mine.sitesWritten) site(s), reference \(reference.sitesWritten)"
)
- #expect(mine.wasAlreadyCorrect == reference.alreadyCorrect)
- let referenceVMA = try #require(
- reference.siteVMA,
- "the Python reported no SwapEnd site at all: \(reference.output)"
- )
- #expect(mine.siteVMA == referenceVMA)
+ #expect(mine.wasAlreadyCorrect == reference.wasAlreadyCorrect)
+ #expect(mine.siteVMA == FrozenReference.siteVMA)
+ #expect(mine.originalSize == FrozenReference.originalSize)
#expect(mine.targetSize == targetSize)
- // And, the part that actually matters: identical caches.
- let differing = try CacheComparison.differingFiles(pythonClone, swiftClone)
- #expect(differing.isEmpty, "chunks differ between Swift and Python: \(differing)")
-
- // A patch that changed nothing would also pass the comparison above, so
- // pin what changed relative to the untouched cache.
+ // And, the part that actually matters: the reference's chunks, with the
+ // reference's bytes.
let touched = try CacheComparison.differingFiles(pristine, swiftClone)
- if mine.sitesWritten == 0 {
- #expect(touched.isEmpty, "nothing should have been written, but \(touched) changed")
- } else {
- #expect(
- touched.count == 1,
- "expected exactly one chunk to change, got \(touched)"
- )
+ #expect(touched.sorted() == reference.changedChunks.keys.sorted())
+ for name in touched {
+ let digest = try Digest.sha256(of: swiftClone.appendingPathComponent(name))
+ let frozen = reference.changedChunks[name] ?? "(not a chunk the Python moved)"
+ #expect(digest == frozen, "\(name): Swift \(digest), reference \(frozen)")
+ }
+
+ if mine.sitesWritten > 0 {
let reattested = try #require(mine.reattestation)
#expect(reattested.updated.count == 1)
#expect(reattested.isFullyAttested)
}
print(
- "[parity 0x\(suffix)] python \(reference.sitesWritten) site(s), "
- + "swift \(mine.sitesWritten) site(s) "
+ "[parity 0x\(suffix)] \(mine.sitesWritten) site(s) "
+ "(0x\(String(mine.originalSize, radix: 16, uppercase: true)) -> "
+ "0x\(String(mine.targetSize, radix: 16, uppercase: true)) at "
+ "0x\(String(mine.siteVMA, radix: 16, uppercase: true))); "
- + "chunks changed: \(touched); swift vs python: identical"
+ + "chunks changed: \(touched) — digests match the reference"
)
}
@@ -476,8 +484,8 @@ struct DSCIOMFBSwapEndParityTests {
)
#expect(mine.sitesWritten == 0)
#expect(mine.reattestation == nil)
- #expect(mine.siteVMA != 0)
- #expect(mine.originalSize != 0)
+ #expect(mine.siteVMA == FrozenReference.siteVMA)
+ #expect(mine.originalSize == FrozenReference.originalSize)
let touched = try CacheComparison.differingFiles(pristine, clone)
#expect(touched.isEmpty, "a dry run wrote to \(touched)")
@@ -523,6 +531,13 @@ struct DSCIOMFBSwapEndParityTests {
let differing = try CacheComparison.differingFiles(afterFirst, clone)
#expect(differing.isEmpty, "a second run rewrote \(differing)")
+
+ // The reference was a no-op on its own output too, so the bytes here
+ // must still be the ones it left behind for 0x588.
+ let frozen = try #require(FrozenReference.bySize[0x588])
+ for (name, digest) in frozen.changedChunks {
+ #expect(try Digest.sha256(of: clone.appendingPathComponent(name)) == digest)
+ }
print("[idempotent] second run wrote 0 sites and changed 0 chunks")
}
@@ -537,7 +552,7 @@ struct DSCIOMFBSwapEndParityTests {
of: DSCIOMFBSwapEndPatcher.symbolName,
inImage: DSCIOMFBSwapEndPatcher.imagePath
)
- #expect(functionVMA != 0)
+ #expect(functionVMA == FrozenReference.functionVMA)
let disassembler = ARM64Disassembler()
let instructions = try DSCIOMFBSwapEndPatcher.disassembleFunction(
@@ -572,6 +587,9 @@ struct DSCIOMFBSwapEndParityTests {
disassembler: disassembler
)
)
+ // The reference resolved the same function and landed on the same move.
+ #expect(site.instruction.address == FrozenReference.siteVMA)
+ #expect(size.immediate == Int64(FrozenReference.originalSize))
print(
"[resolve] \(DSCIOMFBSwapEndPatcher.symbolName) @ "
+ "0x\(String(functionVMA, radix: 16, uppercase: true)), size move "
diff --git a/tests/FirmwarePatcherTests/DSCLSDEmbeddedRegTests.swift b/tests/FirmwarePatcherTests/DSCLSDEmbeddedRegTests.swift
index 9360433e..d3711686 100644
--- a/tests/FirmwarePatcherTests/DSCLSDEmbeddedRegTests.swift
+++ b/tests/FirmwarePatcherTests/DSCLSDEmbeddedRegTests.swift
@@ -2,10 +2,12 @@
//
// The patch is one instruction in a 6.7 GB cache, and a wrong one is a boot
// panic rather than a failing assertion, so the reference these tests grade
-// against is the Python that has already shipped: `cfw.py
-// patch-lsd-embedded-reg`. The centre of the suite runs both implementations
-// over two clones of the *real* cache and compares every byte of all 79 chunks
-// plus the `.symbols` side file.
+// against is the Python that shipped before this port: `cfw.py
+// patch-lsd-embedded-reg`. That Python has since been deleted, so its result
+// is frozen here instead of re-run: `FrozenReference` below records the site
+// it found, the bytes it wrote and the SHA-256 of every chunk it changed, and
+// the Swift patcher is graded against those numbers. Each constant names the
+// command that produced it.
//
// The cache is required. Point `VPHONE_DSC_PRISTINE` at a directory of
// `dyld_shared_cache_arm64e*` chunks, or leave the default
@@ -20,9 +22,64 @@
// under `VPHONE_DSC_SCRATCH` when the caller names one.
@testable import FirmwarePatcher
+import CryptoKit
import Foundation
import Testing
+// MARK: - The frozen reference
+
+/// What the reference Python wrote on the real 24A435 arm64e shared cache.
+///
+/// Every value below was read off one live run, recorded at commit 78cbeea:
+///
+/// .venv/bin/python3 scripts/patchers/cfw.py \
+/// patch-lsd-embedded-reg <clone of ipsws/ref_extract/dsc_pristine>
+///
+/// The Swift patcher has to land on the same site, write the same bytes and
+/// leave the same chunk files with the same digests.
+private enum FrozenReference {
+ /// Python: `[.] -[_LSDModifyClient clientIsEntitled…] @ 0x186EE9FAC`.
+ static let methodVMA: UInt64 = 0x1_86EE_9FAC
+
+ /// Python: `[.] gate: cbz w0, #0x186eea048 @ 0x186EEA024`.
+ static let gateVMA: UInt64 = 0x1_86EE_A024
+
+ /// Python: the gate it decoded at `0x186EEA024` was a `cbz`.
+ static let gateMnemonic = "cbz"
+
+ /// Python: `(fall-through sets w20=1)` — the register carrying the YES.
+ static let gateResultRegister = "w20"
+
+ /// Python: `NOP'd gate cbz -> nop … (bytes 20010034 -> 1f2003d5)`.
+ static let originalBytes = Data([0x20, 0x01, 0x00, 0x34])
+
+ /// Python: the same line's replacement half, `1f2003d5`, i.e. `ARM64.nop`.
+ static let patchedBytes = Data([0x1F, 0x20, 0x03, 0xD5])
+
+ /// Python: one `NOP'd gate` line, so one site written.
+ static let sitesWritten = 1
+
+ /// `cmp -s` of the Python's output against the pristine tree, chunk by
+ /// chunk: exactly one file moved, with this SHA-256 afterwards, from
+ /// `shasum -a 256 <python output>/dyld_shared_cache_arm64e.01`.
+ ///
+ /// The digest covers the re-attestation as well as the NOP — the Python
+ /// logged `re-attest: wrote slot 6842 of dyld_shared_cache_arm64e.01`
+ /// (`ee91dcbd.. -> 4ba06a66..`), `updated 1 slot hash(es) across 1
+ /// chunk(s)`, and a Swift run that skipped or mis-computed that slot hash
+ /// would land on a different digest here.
+ ///
+ /// Two further runs of the same Python pinned the edges: re-run over its
+ /// own output printed `already NOP at 0x186EEA024`, no `NOP'd gate` line,
+ /// `updated 0 slot hash(es)`, and left this digest standing; `--dry-run`
+ /// on a fresh clone printed `would NOP gate cbz -> nop at 0x186EEA024` and
+ /// changed no byte of any chunk.
+ static let changedChunks: [String: String] = [
+ "dyld_shared_cache_arm64e.01":
+ "e0c33aa967c0de2d2f46ee6becf40eab5acf20c12a8e1d99bf5b14da6da12a7c",
+ ]
+}
+
// MARK: - Fixture discovery
private enum LSDRegFixture {
@@ -65,14 +122,6 @@ private enum LSDRegFixture {
.appendingPathComponent("vphone-dsc-lsd-embedded-reg")
}
- /// The project venv, which is where the reference Python lives.
- static var python: URL? {
- let url = repoRoot.appendingPathComponent(".venv/bin/python3")
- return FileManager.default.fileExists(atPath: url.path) ? url : nil
- }
-
- static var cfwPy: URL { repoRoot.appendingPathComponent("scripts/patchers/cfw.py") }
-
/// Clone the pristine cache into a fresh directory the caller may write to.
///
/// `cp -c` asks for a `clonefile`, which costs no space and no time when
@@ -116,20 +165,6 @@ private enum LSDRegFixture {
try? FileManager.default.removeItem(at: scratchRoot)
}
}
-
- /// Run the shipped Python patcher over `directory`.
- static func runPython(on directory: URL, dryRun: Bool = false) throws -> Shell.Result {
- let python = try #require(
- self.python,
- "the reference Python is required — run `make setup_venv`"
- )
- return try Shell.run(
- executable: python,
- arguments: [cfwPy.path, "patch-lsd-embedded-reg", directory.path]
- + (dryRun ? ["--dry-run"] : []),
- currentDirectory: repoRoot
- )
- }
}
// MARK: - Subprocess helper
@@ -167,6 +202,23 @@ private enum Shell {
}
}
+// MARK: - Digests
+
+/// SHA-256 of a cache chunk, streamed so a 131 MB file never lands in memory
+/// whole. The hex spelling matches `shasum -a 256`, which is what produced the
+/// frozen digests.
+private enum Digest {
+ static func sha256(of url: URL) throws -> String {
+ let handle = try FileHandle(forReadingFrom: url)
+ defer { try? handle.close() }
+ var hasher = SHA256()
+ while let block = try handle.read(upToCount: 4 << 20), !block.isEmpty {
+ hasher.update(data: block)
+ }
+ return hasher.finalize().map { String(format: "%02x", $0) }.joined()
+ }
+}
+
// MARK: - Byte-for-byte cache comparison
private enum CacheComparison {
@@ -227,6 +279,12 @@ struct DSCLSDEmbeddedRegGateTests {
located.gate.vma
< located.functionVMA + UInt64(DSCLSDEmbeddedRegPatcher.maxInstructions * 4)
)
+
+ // …and it is the exact site the reference Python reported.
+ #expect(located.functionVMA == FrozenReference.methodVMA)
+ #expect(located.gate.vma == FrozenReference.gateVMA)
+ #expect(located.gate.mnemonic == FrozenReference.gateMnemonic)
+ #expect(located.gate.resultRegister == FrozenReference.gateResultRegister)
}
@Test("the symbol resolves through the cache's own local symbol table")
@@ -237,13 +295,14 @@ struct DSCLSDEmbeddedRegGateTests {
try chunks.resolveLocalSymbol(DSCLSDEmbeddedRegPatcher.method),
"\(DSCLSDEmbeddedRegPatcher.method) must be in the .symbols table"
)
+ #expect(address == FrozenReference.methodVMA)
// It has to live in an executable mapping, or it is not the method.
let mapping = try #require(chunks.mapping(forVMA: address))
#expect(mapping.isExecutable)
}
}
-// MARK: - Parity against the Python
+// MARK: - Parity against the frozen reference
@Suite(
"DSC lsd embedded-registration parity",
@@ -251,35 +310,28 @@ struct DSCLSDEmbeddedRegGateTests {
.serialized
)
struct DSCLSDEmbeddedRegParityTests {
- @Test("Swift and Python produce byte-identical caches, one site each")
+ @Test("Swift reproduces the reference cache byte for byte, one site")
func byteForByteParity() throws {
let swiftClone = try LSDRegFixture.cloneCache(named: "swift")
- let pythonClone = try LSDRegFixture.cloneCache(named: "python")
- defer { LSDRegFixture.discard(swiftClone, pythonClone) }
+ defer { LSDRegFixture.discard(swiftClone) }
let report = try DSCLSDEmbeddedRegPatcher.patch(
chunksDirectory: swiftClone,
log: nil
)
#expect(report.outcome == .patched)
- #expect(report.sitesWritten == 1)
+ #expect(report.sitesWritten == FrozenReference.sitesWritten)
#expect(report.methodIsPresent)
+ #expect(report.gate?.vma == FrozenReference.gateVMA)
- let python = try LSDRegFixture.runPython(on: pythonClone)
- #expect(python.status == 0, "python failed: \(python.stdout)\(python.stderr)")
- // The Python names each site it writes; one NOP is the whole patch.
- let pythonSites = python.stdout
- .split(separator: "\n")
- .filter { $0.contains("NOP'd gate") }
- #expect(pythonSites.count == 1, "python wrote \(pythonSites.count) sites")
-
- let differences = try CacheComparison.differences(between: swiftClone, and: pythonClone)
- #expect(differences.isEmpty, "chunks differ between Swift and Python: \(differences)")
-
- // …and both changed exactly the one chunk holding the gate's page.
+ // Exactly the chunk the Python moved, and to exactly the same bytes.
let changed = try CacheComparison.changedFiles(in: swiftClone)
- #expect(changed.count == 1, "Swift touched \(changed.count) chunk(s): \(changed)")
- #expect(changed == (try CacheComparison.changedFiles(in: pythonClone)))
+ #expect(changed == FrozenReference.changedChunks.keys.sorted())
+ for name in changed {
+ let digest = try Digest.sha256(of: swiftClone.appendingPathComponent(name))
+ let frozen = FrozenReference.changedChunks[name] ?? "(not a chunk the Python moved)"
+ #expect(digest == frozen, "\(name): Swift \(digest), reference \(frozen)")
+ }
}
@Test("the recorded write names the chunk, its offset and the gate address")
@@ -300,6 +352,11 @@ struct DSCLSDEmbeddedRegParityTests {
#expect(record.afterDisasm == "nop")
#expect(record.beforeDisasm.hasPrefix(gate.mnemonic))
+ // The bytes on both sides are the pair the Python printed.
+ #expect(record.originalBytes == FrozenReference.originalBytes)
+ #expect(record.patchedBytes == FrozenReference.patchedBytes)
+ #expect(record.virtualAddress == FrozenReference.gateVMA)
+
// The offset has to name the byte that changed, in the file it names.
let handle = try FileHandle(
forReadingFrom: clone.appendingPathComponent(record.component)
@@ -334,30 +391,14 @@ struct DSCLSDEmbeddedRegRerunTests {
#expect(second.gate?.vma == first.gate?.vma)
#expect(try CacheComparison.changedFiles(in: clone) == afterFirst)
- }
-
- @Test("Python over a Swift-patched cache is a no-op, and the reverse too")
- func crossImplementationRerunsAgree() throws {
- let clone = try LSDRegFixture.cloneCache(named: "cross")
- defer { LSDRegFixture.discard(clone) }
-
- try DSCLSDEmbeddedRegPatcher.patch(chunksDirectory: clone, log: nil)
- let afterSwift = try Data(
- contentsOf: clone.appendingPathComponent("dyld_shared_cache_arm64e")
- ).count
-
- let python = try LSDRegFixture.runPython(on: clone)
- #expect(python.status == 0, "python failed: \(python.stdout)\(python.stderr)")
- #expect(python.stdout.contains("already NOP"))
- #expect(!python.stdout.contains("NOP'd gate"))
-
- // The Python re-run must not have moved anything.
- #expect(
- try Data(contentsOf: clone.appendingPathComponent("dyld_shared_cache_arm64e"))
- .count == afterSwift
- )
- let report = try DSCLSDEmbeddedRegPatcher.patch(chunksDirectory: clone, log: nil)
- #expect(report.outcome == .alreadyPatched)
+ // The reference was idempotent across runs too, so a second Swift pass
+ // has to leave the frozen digests standing.
+ for name in afterFirst {
+ #expect(
+ try Digest.sha256(of: clone.appendingPathComponent(name))
+ == FrozenReference.changedChunks[name]
+ )
+ }
}
@Test("a dry run locates the gate and writes nothing")
@@ -372,7 +413,8 @@ struct DSCLSDEmbeddedRegRerunTests {
)
#expect(report.outcome == .wouldPatch)
#expect(report.sitesWritten == 0)
- #expect(report.gate != nil)
+ #expect(report.gate?.vma == FrozenReference.gateVMA)
+ // The reference dry run wrote nothing either.
#expect(try CacheComparison.changedFiles(in: clone).isEmpty)
}
}
diff --git a/tests/FirmwarePatcherTests/DSCLockdownModePatcherTests.swift b/tests/FirmwarePatcherTests/DSCLockdownModePatcherTests.swift
index e0028a52..425acdc1 100644
--- a/tests/FirmwarePatcherTests/DSCLockdownModePatcherTests.swift
+++ b/tests/FirmwarePatcherTests/DSCLockdownModePatcherTests.swift
@@ -1,11 +1,13 @@
// DSCLockdownModePatcherTests.swift — Parity for the lockdown-mode DSC patch.
//
-// The only independent reference for this patch is
+// The only independent reference for this patch was
// `scripts/patchers/cfw_patch_lockdown_mode.py`, driven exactly as
-// `cfw_install.sh` drives it: `cfw.py patch-lockdown-mode <chunks_dir>`. So the
-// central test here clones the real cache twice, runs the Python on one clone
-// and `DSCLockdownModePatcher` on the other, and compares the two patched
-// directories byte for byte — chunk bytes and re-attested code slots alike.
+// `cfw_install.sh` drove it: `cfw.py patch-lockdown-mode <chunks_dir>`. That
+// Python has been removed, so what it produced on the real cache is frozen in
+// `FrozenReference` below — the block and gate addresses, the instruction word
+// on each side of the write, and the SHA-256 of the one chunk it changed. The
+// central test clones the cache, runs `DSCLockdownModePatcher` on the clone and
+// grades it against those, chunk bytes and re-attested code slot alike.
//
// The tests need the real cache. Point `VPHONE_DSC_PRISTINE` at a directory of
// `dyld_shared_cache_arm64e*` chunks, or leave the default
@@ -22,10 +24,55 @@
// directory — instant and near-free on APFS — and removed again.
import Capstone
+import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
+// MARK: - The frozen reference
+
+/// What the reference Python wrote on the real 24A435 arm64e shared cache.
+///
+/// Recorded from live runs at commit 78cbeea, each constant quoting the log
+/// line it came from:
+///
+/// .venv/bin/python3 scripts/patchers/cfw.py \
+/// patch-lockdown-mode <clone of ipsws/ref_extract/dsc_pristine>
+private enum FrozenReference {
+ /// Python: `[.] ___os_lockdown_mode_enabled_block_invoke @ 0x237EF2260`.
+ static let functionVMA: UInt64 = 0x2_37EF_2260
+
+ /// Python: `[.] gate @ 0x237EF2298: b.eq #0x237ef22bc`.
+ static let gateVMA: UInt64 = 0x2_37EF_2298
+
+ /// The same line's disassembly, which is what the gate search must find.
+ static let gateMnemonic = "b.eq"
+
+ /// Python: `[+] wrote nop at 0x237EF2298 (20010054 -> 1f2003d5)`.
+ static let originalWord = Data([0x20, 0x01, 0x00, 0x54])
+ static let patchedWord = Data([0x1F, 0x20, 0x03, 0xD5])
+
+ /// Python: one `wrote nop` line, so one site written.
+ static let sitesWritten = 1
+
+ /// `cmp -s` against the pristine tree afterwards: exactly one chunk moved,
+ /// to this digest, from `shasum -a 256 <output>/…arm64e.40`.
+ ///
+ /// The digest covers the re-attestation as well as the NOP — the Python
+ /// logged `re-attest: wrote slot 7868 of dyld_shared_cache_arm64e.40`
+ /// (`c33cc701.. -> 43ba8896..`), `updated 1 slot hash(es) across 1
+ /// chunk(s)`.
+ ///
+ /// Two further runs pinned the edges. Re-run over its own output: `[.] gate
+ /// @ 0x237EF2298: nop`, `already patched at 0x237EF2298; nothing to
+ /// patch/re-attest`, digest unchanged. `--dry-run` on a fresh clone: `would
+ /// write nop at 0x237EF2298 (20010054 -> 1f2003d5)` and no chunk changed.
+ static let changedChunks: [String: String] = [
+ "dyld_shared_cache_arm64e.40":
+ "7f8ba74581e37fbd433d42851578d4faa7e30ab2959b1d466f0ff3b9a39f6e56",
+ ]
+}
+
// MARK: - Fixture discovery
private enum LockdownFixture {
@@ -62,15 +109,6 @@ private enum LockdownFixture {
static let skipReason: Comment =
"VPHONE_DSC_FIXTURE_OPTIONAL=1 and no dyld_shared_cache_arm64e fixture present"
- /// 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
- }
-
- /// `scripts/patchers/cfw.py`, the entry point `cfw_install.sh` calls.
- static var cfwCLI: URL { repoRoot.appendingPathComponent("scripts/patchers/cfw.py") }
-
/// Where clones go. Deliberately outside the working tree: the reference
/// cache's directory is what the whole DSC suite compares against, and a
/// scratch clone has no business living inside it.
@@ -150,58 +188,33 @@ private enum Subprocess {
}
}
-// MARK: - The reference Python, driven the way the installer drives it
-
-private enum PythonReference {
- struct Run {
- let stdout: String
- /// Sites the Python says it wrote, counted off its own log lines.
- let sitesWritten: Int
- /// Sites it reached at all — written, already patched, or (on a dry
- /// run) would-be-written.
- let sitesFound: Int
- /// The gate address it reported, if any.
- let gateVMA: UInt64?
- /// The block address it resolved, if any.
- let functionVMA: UInt64?
- }
-
- /// `cfw.py patch-lockdown-mode <chunks_dir> [--dry-run]`, which is the
- /// exact contract `cfw_install.sh` and `cfw-kit/lib/base_stages.sh` use.
- static func patchLockdownMode(directory: URL, dryRun: Bool) throws -> Run {
- let python = try #require(LockdownFixture.python, "project venv is required")
- let result = try Subprocess.run(
- executable: python,
- arguments: [LockdownFixture.cfwCLI.path, "patch-lockdown-mode", directory.path]
- + (dryRun ? ["--dry-run"] : [])
- )
- guard result.status == 0 else {
- Issue.record("cfw.py patch-lockdown-mode failed: \(result.stdout)\n\(result.stderr)")
- throw CocoaError(.fileReadUnknown)
+// MARK: - Digests
+
+/// SHA-256 of a cache chunk, streamed so a 131 MB file never lands in memory
+/// whole. The hex spelling matches `shasum -a 256`, which produced the frozen
+/// digests.
+private enum Digest {
+ static func sha256(of url: URL) throws -> String {
+ let handle = try FileHandle(forReadingFrom: url)
+ defer { try? handle.close() }
+ var hasher = SHA256()
+ while let block = try handle.read(upToCount: 4 << 20), !block.isEmpty {
+ hasher.update(data: block)
}
- let lines = result.stdout.split(separator: "\n").map(String.init)
- return Run(
- stdout: result.stdout,
- sitesWritten: lines.filter { $0.contains("wrote nop at 0x") }.count,
- sitesFound: lines.filter {
- $0.contains("wrote nop at 0x")
- || $0.contains("would write nop at 0x")
- || $0.contains("already patched at 0x")
- }.count,
- gateVMA: lines.compactMap { line in
- line.contains("gate @ 0x") ? hexAddress(after: "gate @ 0x", in: line) : nil
- }.first,
- functionVMA: lines.compactMap { line in
- line.contains("_block_invoke @ 0x")
- ? hexAddress(after: "_block_invoke @ 0x", in: line) : nil
- }.first
- )
+ return hasher.finalize().map { String(format: "%02x", $0) }.joined()
}
- private static func hexAddress(after marker: String, in line: String) -> UInt64? {
- guard let range = line.range(of: marker) else { return nil }
- let digits = line[range.upperBound...].prefix { $0.isHexDigit }
- return UInt64(digits, radix: 16)
+ /// Assert that `directory` holds exactly the chunks the reference changed,
+ /// with exactly the reference's bytes.
+ static func expectMatchesReference(_ directory: URL) throws {
+ let pristine = try #require(LockdownFixture.pristine, LockdownFixture.missing)
+ let changed = try DirectoryComparison.changedNames(in: directory, against: pristine)
+ #expect(changed == FrozenReference.changedChunks.keys.sorted())
+ for name in changed {
+ let digest = try sha256(of: directory.appendingPathComponent(name))
+ let frozen = FrozenReference.changedChunks[name] ?? "(not a chunk the Python moved)"
+ #expect(digest == frozen, "\(name): Swift \(digest), reference \(frozen)")
+ }
}
}
@@ -238,6 +251,26 @@ private enum DirectoryComparison {
return differing
}
+ /// The names of the files in `directory` that differ from `reference`.
+ static func changedNames(in directory: URL, against reference: URL) throws -> [String] {
+ let manager = FileManager.default
+ let left = Set(try manager.contentsOfDirectory(atPath: reference.path))
+ let right = Set(try manager.contentsOfDirectory(atPath: directory.path))
+ var differing = Array(left.symmetricDifference(right))
+ for name in left.intersection(right) {
+ let result = try Subprocess.run(
+ executable: URL(fileURLWithPath: "/usr/bin/cmp"),
+ arguments: [
+ "-s",
+ reference.appendingPathComponent(name).path,
+ directory.appendingPathComponent(name).path,
+ ]
+ )
+ if result.status != 0 { differing.append(name) }
+ }
+ return differing.sorted()
+ }
+
/// A digest of every file in a cache directory, for before/after checks
/// that only need to know whether anything moved.
static func fingerprint(of directory: URL) throws -> [String: String] {
@@ -254,43 +287,30 @@ private enum DirectoryComparison {
}
}
-// MARK: - Parity against the Python
+// MARK: - Parity against the frozen reference
@Suite(.serialized, .enabled(if: LockdownFixture.runs, LockdownFixture.skipReason))
struct DSCLockdownModeParityTests {
- /// The one that matters: same cache, both patchers, identical bytes out.
- @Test("Swift and Python produce byte-identical patched caches")
- func patchedCachesAreIdentical() throws {
+ /// The one that matters: the real cache in, the reference's bytes out.
+ @Test("Swift reproduces the reference's patched cache byte for byte")
+ func patchedCacheMatchesTheReference() throws {
_ = try #require(LockdownFixture.pristine, LockdownFixture.missing)
- _ = try #require(LockdownFixture.python, "project venv is required for the cross-check")
- let pythonClone = try LockdownFixture.cloneCache(named: "python")
let swiftClone = try LockdownFixture.cloneCache(named: "swift")
- defer { LockdownFixture.discard(pythonClone, swiftClone) }
+ defer { LockdownFixture.discard(swiftClone) }
- let reference = try PythonReference.patchLockdownMode(directory: pythonClone, dryRun: false)
let outcome = try DSCLockdownModePatcher.patch(chunksDirectory: swiftClone, log: nil)
#expect(outcome.verdict == .patched)
- #expect(outcome.sitesWritten == 1)
- #expect(reference.sitesWritten == 1)
- #expect(
- outcome.sitesWritten == reference.sitesWritten,
- "site counts must match: Swift \(outcome.sitesWritten), Python \(reference.sitesWritten)"
- )
- #expect(outcome.gateVMA == reference.gateVMA)
- #expect(outcome.functionVMA == reference.functionVMA)
-
- let differences = try DirectoryComparison.differences(between: pythonClone, and: swiftClone)
- #expect(differences.isEmpty, "patched caches differ: \(differences.joined(separator: "; "))")
-
- let fileCount = try FileManager.default
- .contentsOfDirectory(atPath: swiftClone.path).count
- print(
- "[lockdown] 1 site @ 0x"
- + String(outcome.gateVMA ?? 0, radix: 16, uppercase: true)
- + " — \(fileCount) files byte-identical to the Python's output"
- )
+ #expect(outcome.sitesWritten == FrozenReference.sitesWritten)
+ #expect(outcome.gateVMA == FrozenReference.gateVMA)
+ #expect(outcome.functionVMA == FrozenReference.functionVMA)
+
+ let record = try #require(outcome.record)
+ #expect(record.originalBytes == FrozenReference.originalWord)
+ #expect(record.patchedBytes == FrozenReference.patchedWord)
+
+ try Digest.expectMatchesReference(swiftClone)
}
/// The write has to be covered by exactly one re-attested page, or the
@@ -333,18 +353,39 @@ struct DSCLockdownModeParityTests {
let afterSecond = try DirectoryComparison.fingerprint(of: clone)
#expect(afterFirst == afterSecond, "a no-op run still rewrote something")
+ // The reference was a no-op on its own output too, so the bytes here
+ // must still be the ones it left behind.
+ try Digest.expectMatchesReference(clone)
}
- /// The Python's dry run is the cheapest oracle for the reveal, and it runs
- /// against the pristine cache without touching it.
- @Test("Symbol and gate resolve to the same addresses as the Python")
- func revealMatchesTheReference() throws {
+ /// The reference's `--dry-run` named the gate and changed no chunk. So
+ /// must this one — an install script that asks what would happen must not
+ /// be the thing that makes it happen.
+ @Test("A dry run names the reference's gate and writes nothing")
+ func dryRunWritesNothing() throws {
let pristine = try #require(LockdownFixture.pristine, LockdownFixture.missing)
- _ = try #require(LockdownFixture.python, "project venv is required for the cross-check")
- let reference = try PythonReference.patchLockdownMode(directory: pristine, dryRun: true)
- #expect(reference.sitesWritten == 0, "a dry run must not write")
- #expect(reference.sitesFound == 1)
+ let clone = try LockdownFixture.cloneCache(named: "dryrun")
+ defer { LockdownFixture.discard(clone) }
+
+ let outcome = try DSCLockdownModePatcher.patch(
+ chunksDirectory: clone,
+ dryRun: true,
+ log: nil
+ )
+ #expect(outcome.sitesWritten == 0)
+ #expect(outcome.sitesFound == 1)
+ #expect(outcome.gateVMA == FrozenReference.gateVMA)
+
+ let changed = try DirectoryComparison.changedNames(in: clone, against: pristine)
+ #expect(changed.isEmpty, "a dry run modified \(changed)")
+ }
+
+ /// The reveal — symbol, then gate — read off the pristine cache without
+ /// touching it, and checked against the addresses the reference printed.
+ @Test("Symbol and gate resolve to the reference's addresses")
+ func revealMatchesTheReference() throws {
+ let pristine = try #require(LockdownFixture.pristine, LockdownFixture.missing)
let chunks = try DSCChunkSet(directory: pristine)
let resolved = try DSCLockdownModePatcher.resolveBlockInvoke(in: chunks)
@@ -352,13 +393,13 @@ struct DSCLockdownModeParityTests {
resolved,
"the cache must carry an os_lockdown_mode_enabled block to compare against"
)
- #expect(block.vma == reference.functionVMA)
+ #expect(block.vma == FrozenReference.functionVMA)
#expect(block.name == DSCLockdownModePatcher.symbolCandidates.first)
let instructions = try DSCLockdownModePatcher.disassembleBlock(in: chunks, at: block.vma)
let gate = try #require(DSCLockdownModePatcher.findErrorGate(instructions))
- #expect(gate.address == reference.gateVMA)
- #expect(gate.mnemonic == "b.eq")
+ #expect(gate.address == FrozenReference.gateVMA)
+ #expect(gate.mnemonic == FrozenReference.gateMnemonic)
// The decode stops at the block's own return, not at the ceiling.
#expect(instructions.count < DSCLockdownModePatcher.maxInstructions)
diff --git a/tests/FirmwarePatcherTests/DSCMaxSlidePatcherTests.swift b/tests/FirmwarePatcherTests/DSCMaxSlidePatcherTests.swift
index 4da069bf..ed09ed74 100644
--- a/tests/FirmwarePatcherTests/DSCMaxSlidePatcherTests.swift
+++ b/tests/FirmwarePatcherTests/DSCMaxSlidePatcherTests.swift
@@ -1,11 +1,14 @@
// DSCMaxSlidePatcherTests.swift — Parity cross-checks for `DSCMaxSlidePatcher`.
//
// There is no `codesign -v` for a dyld shared cache chunk and no second
-// implementation of this patch anywhere, so the only independent reference is
-// `scripts/patchers/cfw_patch_dsc_maxslide.py` — driven here through the exact
-// CLI the install scripts use, `cfw.py patch-dsc-maxslide <dir> [--dry-run]
-// [--force]`. Every claim below is "the Python did X on one clone, the Swift
-// did X on another, and the two clones are the same bytes".
+// implementation of this patch anywhere. The only independent reference was
+// `scripts/patchers/cfw_patch_dsc_maxslide.py`, driven through the CLI the
+// install scripts use: `cfw.py patch-dsc-maxslide <dir> [--dry-run] [--force]`.
+// That Python has been removed, so what it produced is frozen in
+// `FrozenReference` below — for the real cache, and for each of the five
+// synthetic gate cases, the digest of the input it saw and the digest of the
+// file it left behind. Every claim here is "the Swift, given the bytes the
+// reference was given, produces the bytes the reference produced".
//
// The tests need the real cache. Point `VPHONE_DSC_PRISTINE` at a directory of
// `dyld_shared_cache_arm64e*` chunks, or leave the default
@@ -23,9 +26,116 @@
// `clonefile` rather than 10 GB of copying.
@testable import FirmwarePatcher
+import CryptoKit
import Foundation
import Testing
+// MARK: - The frozen reference
+
+/// What the reference Python produced, recorded from live runs at commit
+/// 78cbeea:
+///
+/// .venv/bin/python3 scripts/patchers/cfw.py \
+/// patch-dsc-maxslide <input> [--dry-run] [--force]
+///
+/// The real-cache input was a clone of `ipsws/ref_extract/dsc_pristine`. The
+/// synthetic inputs were rebuilt byte for byte from
+/// `DSCMaxSlideGateTests.writeCache`, which is why each case carries the digest
+/// of its input as well as of its output: a test that fed the Swift something
+/// else would fail on the input digest rather than quietly compare nothing.
+private enum FrozenReference {
+ // MARK: The real 24A435 arm64e cache
+
+ /// Python: `dyld_shared_cache_arm64e: start=0x180000000 size=0x17D504000
+ /// maxSlide=0x20000000`.
+ static let realStart: UInt64 = 0x1_8000_0000
+ static let realSize: UInt64 = 0x1_7D50_4000
+ static let realMaxSlide: UInt64 = 0x2000_0000
+
+ /// Python: `overflow: span+maxSlide 0x19D504000 > region 0x180000000; set
+ /// maxSlide 0x20000000 -> 0x0`, then `DSC maxSlide patch complete`.
+ ///
+ /// `cmp -s` against the pristine tree afterwards: exactly one file moved,
+ /// the main chunk, to this digest (`shasum -a 256 <output>/…arm64e`). The
+ /// other 79 files were untouched — this patch deliberately does not
+ /// re-attest, so no code-directory slot moves.
+ static let realChangedChunks: [String: String] = [
+ "dyld_shared_cache_arm64e":
+ "3d7197cc0714e95c0e49434ab8bbb6311952a96d5b0425b10f87d2cc060c0110",
+ ]
+
+ /// Re-running the Python over its own output printed `fits: span+maxSlide
+ /// 0x17D504000 <= region 0x180000000; no change` — the *fits* gate, not the
+ /// already-zero one — and left the digest above standing. A third run with
+ /// `--force` skipped that gate and printed `maxSlide already 0; no change`,
+ /// also writing nothing. A `--dry-run` on a fresh clone printed `would set
+ /// maxSlide 0x20000000 -> 0x0` and changed no byte.
+
+ // MARK: The synthetic gate cases
+
+ /// One synthetic case: the digest of the cache handed to the patcher, and
+ /// the digest of what it held afterwards.
+ struct GateCase {
+ let inputSHA256: String
+ let outputSHA256: String
+ /// The branch word the Python printed: `overflow`, `fits`, `forced` or
+ /// `maxSlide already 0`.
+ let branch: String
+ }
+
+ /// `writeCache(regionSize: 0x17C830000, maxSlide: 0x20000000)`, no flags.
+ /// Python: `overflow: span+maxSlide 0x19C830000 > region 0x180000000; set
+ /// maxSlide 0x20000000 -> 0x0`.
+ static let overflow = GateCase(
+ inputSHA256: "0eeb86dc953aa43a29df533a0c151cb1d8ce7f322f8fa77232d5c97733984ab3",
+ outputSHA256: "93e9ee632ab259a245f37e224e52e7f5671c8b323d04ba541483335c0d94bc6c",
+ branch: "overflow"
+ )
+
+ /// `writeCache(regionSize: 0x140904000, maxSlide: 0x20000000)`, no flags.
+ /// Python: `fits: span+maxSlide 0x160904000 <= region 0x180000000; no
+ /// change` — input and output digests are the same file.
+ static let fits = GateCase(
+ inputSHA256: "88c50a6f8304c87bca21e6c01da193d8022673c12d03d4d0dfd52340b3fca718",
+ outputSHA256: "88c50a6f8304c87bca21e6c01da193d8022673c12d03d4d0dfd52340b3fca718",
+ branch: "fits"
+ )
+
+ /// The same input as `fits`, with `--force`. Python: `forced: span+maxSlide
+ /// 0x160904000 fits region 0x180000000 but --force set; set maxSlide
+ /// 0x20000000 -> 0x0`.
+ static let forced = GateCase(
+ inputSHA256: "88c50a6f8304c87bca21e6c01da193d8022673c12d03d4d0dfd52340b3fca718",
+ outputSHA256: "73e12cacf1350c07ad38991f4e845e51f64199815061e0ea1889d19f53f4beda",
+ branch: "forced"
+ )
+
+ /// `writeCache(regionSize: 0x140904000, maxSlide: 0)` with `--force`.
+ /// Python: `maxSlide already 0; no change`.
+ static let forcedZero = GateCase(
+ inputSHA256: "73e12cacf1350c07ad38991f4e845e51f64199815061e0ea1889d19f53f4beda",
+ outputSHA256: "73e12cacf1350c07ad38991f4e845e51f64199815061e0ea1889d19f53f4beda",
+ branch: "maxSlide already 0"
+ )
+
+ /// `writeCache(regionSize: 0x190000000, maxSlide: 0)`, no flags — a span
+ /// that overruns the region with no slide left to give back. Python:
+ /// `maxSlide already 0; no change`.
+ static let overflowWithZeroSlide = GateCase(
+ inputSHA256: "f2543eb53f0f69a25c72045311292c9c428798a53683aeebd5b051509126d4b9",
+ outputSHA256: "f2543eb53f0f69a25c72045311292c9c428798a53683aeebd5b051509126d4b9",
+ branch: "maxSlide already 0"
+ )
+
+ /// The Python's own self-test fixture — a bare 0x100-byte header with no
+ /// mapping table — is the one input where the two implementations
+ /// deliberately disagree, so it has no `GateCase` above. The reference
+ /// patched it (`overflow: … set maxSlide 0x20000000 -> 0x0`, the field
+ /// reading back as 0 afterwards); the Swift refuses it, because every write
+ /// here goes through `DSCChunkSet`, which has nothing to address such a
+ /// file with. See `noMappingTableIsRefused`.
+}
+
// MARK: - Fixture discovery
private enum MaxSlideFixture {
@@ -62,12 +172,6 @@ private enum MaxSlideFixture {
static let skipReason: Comment =
"VPHONE_DSC_FIXTURE_OPTIONAL=1 and no dyld_shared_cache_arm64e fixture present"
- static let venvMissing: Comment = """
- the project venv is required: these tests are a comparison against \
- scripts/patchers/cfw_patch_dsc_maxslide.py, and without it there is nothing \
- to compare against — run `make setup_venv`
- """
-
/// Where clones are made. Same filesystem as the repo, and deliberately
/// *not* under `ipsws/ref_extract/`, which is the pristine reference the
/// whole suite compares against.
@@ -75,12 +179,6 @@ private enum MaxSlideFixture {
repoRoot.appendingPathComponent("ipsws/scratch_dscmaxslide")
}
- /// 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
- }
-
/// Clone the whole pristine cache into a fresh directory the caller may
/// write to. `cp -c` is `clonefile(2)`: instant, and near-zero disk until
/// something is written.
@@ -175,42 +273,19 @@ private enum Subprocess {
}
}
-// MARK: - The reference Python, driven through its real CLI
-
-/// `cfw.py patch-dsc-maxslide <chunks_dir> [--dry-run] [--force]` — the exact
-/// contract `scripts/cfw_install.sh` and `cfw-kit/lib/base_stages.sh` call.
-private enum PythonReference {
- struct Run {
- let stdout: String
-
- /// The Python's return value, recovered from the lines it prints: it
- /// returns 1 once it has decided the cache needs the clamp (including
- /// on a dry run), and 0 from either "no change" branch.
- var siteCount: Int { stdout.contains("[+] DSC maxSlide patch complete") ? 1 : 0 }
- var saidNoChange: Bool { stdout.contains("no change") }
- var saidWouldSet: Bool { stdout.contains("would set maxSlide") }
- }
-
- static func patch(
- directory: URL,
- dryRun: Bool = false,
- force: Bool = false
- ) throws -> Run {
- let python = try #require(MaxSlideFixture.python, MaxSlideFixture.venvMissing)
- var arguments = [
- MaxSlideFixture.repoRoot.appendingPathComponent("scripts/patchers/cfw.py").path,
- "patch-dsc-maxslide",
- directory.path,
- ]
- if dryRun { arguments.append("--dry-run") }
- if force { arguments.append("--force") }
-
- let result = try Subprocess.run(executable: python, arguments: arguments)
- guard result.status == 0 else {
- Issue.record("cfw.py patch-dsc-maxslide failed: \(result.stderr)")
- throw CocoaError(.fileReadUnknown)
+// MARK: - Digests
+
+/// SHA-256 of a file, streamed so a 131 MB chunk never lands in memory whole.
+/// The hex spelling matches `shasum -a 256`, which produced the frozen digests.
+private enum Digest {
+ static func sha256(of url: URL) throws -> String {
+ let handle = try FileHandle(forReadingFrom: url)
+ defer { try? handle.close() }
+ var hasher = SHA256()
+ while let block = try handle.read(upToCount: 4 << 20), !block.isEmpty {
+ hasher.update(data: block)
}
- return Run(stdout: result.stdout)
+ return hasher.finalize().map { String(format: "%02x", $0) }.joined()
}
}
@@ -285,6 +360,10 @@ struct DSCMaxSlideRealCacheTests {
header.sharedRegionSize + header.maxSlide > DSCMaxSlidePatcher.kernelSharedRegionSize,
"this fixture does not exercise the patch: it fits the region as it stands"
)
+ // The three numbers the reference read out of this same header.
+ #expect(header.sharedRegionStart == FrozenReference.realStart)
+ #expect(header.sharedRegionSize == FrozenReference.realSize)
+ #expect(header.maxSlide == FrozenReference.realMaxSlide)
print(
"[pristine] start=0x\(String(header.sharedRegionStart, radix: 16, uppercase: true)) "
+ "size=0x\(String(header.sharedRegionSize, radix: 16, uppercase: true)) "
@@ -292,22 +371,16 @@ struct DSCMaxSlideRealCacheTests {
)
}
- /// The gate from the task: run each implementation on its own clone of the
- /// real cache and require the two clones to come out byte-identical, over
- /// every one of the 79 chunks and the symbol side file — not just over the
- /// eight bytes the patch is about.
- @Test("Swift and the Python patch the real cache into byte-identical clones")
- func realCacheParityWithPython() throws {
+ /// The gate from the task: run the patcher on a clone of the real cache and
+ /// require the result to be the bytes the reference left behind, over every
+ /// one of the 79 chunks and the symbol side file — not just over the eight
+ /// bytes the patch is about.
+ @Test("Swift patches the real cache into the reference's bytes")
+ func realCacheMatchesTheReference() throws {
let pristine = try #require(MaxSlideFixture.pristine, MaxSlideFixture.missing)
- _ = try #require(MaxSlideFixture.python, MaxSlideFixture.venvMissing)
- let pythonSide = try MaxSlideFixture.cloneCache(named: "parity_python")
let swiftSide = try MaxSlideFixture.cloneCache(named: "parity_swift")
- defer { MaxSlideFixture.discard(pythonSide, swiftSide) }
-
- let theirs = try PythonReference.patch(directory: pythonSide)
- #expect(theirs.siteCount == 1, "the Python did not patch the real cache")
- #expect(!theirs.saidNoChange)
+ defer { MaxSlideFixture.discard(swiftSide) }
let mine = try DSCMaxSlidePatcher.patch(chunksDirectory: swiftSide)
#expect(mine.siteCount == 1, "the Swift did not patch the real cache")
@@ -318,37 +391,27 @@ struct DSCMaxSlideRealCacheTests {
))
#expect(mine.writtenSpan?.length == 8, "one site, one u64")
- let (matched, differing) = try Bytes.compareTrees(pythonSide, swiftSide)
- #expect(differing.isEmpty, "clones differ in: \(differing.joined(separator: ", "))")
- #expect(matched >= 79, "only \(matched) files compared")
- print("[parity] \(matched) files byte-identical between the two patched clones")
+ // Exactly the file the reference moved, with exactly its bytes.
+ let (unchanged, changed) = try Bytes.compareTrees(pristine, swiftSide)
+ #expect(changed == FrozenReference.realChangedChunks.keys.sorted())
+ #expect(unchanged >= 79, "only \(unchanged) files were left alone")
+ for name in changed {
+ let digest = try Digest.sha256(of: swiftSide.appendingPathComponent(name))
+ let frozen = FrozenReference.realChangedChunks[name] ?? "(not a file the Python moved)"
+ #expect(digest == frozen, "\(name): Swift \(digest), reference \(frozen)")
+ }
- // And both differ from pristine in exactly one file, by exactly the
- // eight bytes of the field.
+ // …and the change is the eight bytes of the field and nothing else.
let pristineMain = pristine.appendingPathComponent(MaxSlideFixture.mainChunkName)
let head = DSCMaxSlidePatcher.HeaderField.maxSlide
let tailOffset = UInt64(head + 8)
let tailLength = 0x100 - head - 8
- let pristineHead = try Bytes.read(pristineMain, offset: 0, length: head)
- let pristineTail = try Bytes.read(pristineMain, offset: tailOffset, length: tailLength)
- for side in [pythonSide, swiftSide] {
- let main = side.appendingPathComponent(MaxSlideFixture.mainChunkName)
- let differsFromPristine = try !Bytes.identical(main, pristineMain)
- #expect(differsFromPristine)
- let slide = try Bytes.maxSlide(of: main)
- #expect(slide == 0)
-
- // Everything either side of the field is untouched.
- let patchedHead = try Bytes.read(main, offset: 0, length: head)
- let patchedTail = try Bytes.read(main, offset: tailOffset, length: tailLength)
- #expect(patchedHead == pristineHead)
- #expect(patchedTail == pristineTail)
- }
-
- let (unchanged, changed) = try Bytes.compareTrees(pristine, swiftSide)
- #expect(changed == [MaxSlideFixture.mainChunkName])
- print("[parity] \(unchanged) files unchanged from pristine; only \(changed) differs")
- print("[parity] python: \(theirs.siteCount) site, swift: \(mine.siteCount) site")
+ let main = swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName)
+ #expect(try Bytes.maxSlide(of: main) == 0)
+ #expect(try Bytes.read(main, offset: 0, length: head)
+ == Bytes.read(pristineMain, offset: 0, length: head))
+ #expect(try Bytes.read(main, offset: tailOffset, length: tailLength)
+ == Bytes.read(pristineMain, offset: tailOffset, length: tailLength))
}
/// The deliberate divergence from every other DSC patcher, pinned so nobody
@@ -405,35 +468,28 @@ struct DSCMaxSlideRealCacheTests {
+ "computed \(after.computed.hex.prefix(16))… — stale on purpose")
}
- @Test("A dry run reports the site the Python reports, and writes nothing")
- func dryRunMatchesPythonAndWritesNothing() throws {
+ /// The reference's `--dry-run` printed `would set maxSlide 0x20000000 ->
+ /// 0x0` — one site reported, no byte written. So must this one.
+ @Test("A dry run reports the reference's site, and writes nothing")
+ func dryRunReportsTheSiteAndWritesNothing() throws {
let pristine = try #require(MaxSlideFixture.pristine, MaxSlideFixture.missing)
- _ = try #require(MaxSlideFixture.python, MaxSlideFixture.venvMissing)
- let pythonSide = try MaxSlideFixture.cloneMainChunk(named: "dryrun_python")
let swiftSide = try MaxSlideFixture.cloneMainChunk(named: "dryrun_swift")
- defer { MaxSlideFixture.discard(pythonSide, swiftSide) }
-
- let theirs = try PythonReference.patch(directory: pythonSide, dryRun: true)
- #expect(theirs.siteCount == 1)
- #expect(theirs.saidWouldSet)
+ defer { MaxSlideFixture.discard(swiftSide) }
let mine = try DSCMaxSlidePatcher.patch(chunksDirectory: swiftSide, dryRun: true)
- #expect(mine.siteCount == 1, "a dry run still reports the site, as the Python does")
+ #expect(mine.siteCount == 1, "a dry run still reports the site, as the reference did")
#expect(!mine.didWrite)
#expect(mine.record?.patchID == DSCMaxSlidePatcher.patchID)
#expect(mine.record?.patchedBytes == Data(count: 8))
#expect(mine.record?.originalBytes.loadLE(UInt64.self, at: 0) == mine.maxSlide)
+ #expect(mine.maxSlide == FrozenReference.realMaxSlide)
- let pristineMain = pristine.appendingPathComponent(MaxSlideFixture.mainChunkName)
- for side in [pythonSide, swiftSide] {
- let untouched = try Bytes.identical(
- side.appendingPathComponent(MaxSlideFixture.mainChunkName),
- pristineMain
- )
- #expect(untouched, "a dry run wrote to the chunk")
- }
- print("[dry run] python and swift both report 1 site and leave the chunk pristine")
+ let untouched = try Bytes.identical(
+ swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName),
+ pristine.appendingPathComponent(MaxSlideFixture.mainChunkName)
+ )
+ #expect(untouched, "a dry run wrote to the chunk")
}
/// `8eb6c8b`'s lesson again: a patcher has to recognise its own output. A
@@ -442,18 +498,15 @@ struct DSCMaxSlideRealCacheTests {
@Test("A second pass over an already-clamped cache is a no-op")
func secondPassIsANoOp() throws {
_ = try #require(MaxSlideFixture.pristine, MaxSlideFixture.missing)
- _ = try #require(MaxSlideFixture.python, MaxSlideFixture.venvMissing)
- let pythonSide = try MaxSlideFixture.cloneMainChunk(named: "idem_python")
let swiftSide = try MaxSlideFixture.cloneMainChunk(named: "idem_swift")
- defer { MaxSlideFixture.discard(pythonSide, swiftSide) }
-
- _ = try PythonReference.patch(directory: pythonSide)
- let theirsAgain = try PythonReference.patch(directory: pythonSide)
- #expect(theirsAgain.siteCount == 0)
- #expect(theirsAgain.saidNoChange)
+ defer { MaxSlideFixture.discard(swiftSide) }
let first = try DSCMaxSlidePatcher.patch(chunksDirectory: swiftSide)
+ let afterFirst = try Digest.sha256(
+ of: swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName)
+ )
+
let mineAgain = try DSCMaxSlidePatcher.patch(chunksDirectory: swiftSide)
#expect(mineAgain.siteCount == 0)
#expect(!mineAgain.didWrite)
@@ -461,31 +514,34 @@ struct DSCMaxSlideRealCacheTests {
// the slide is gone this cache's span fits the region on its own
// (0x17D504000 <= 0x180000000) — that is the whole point of the patch —
// so the *fits* gate is what returns, and the already-zero gate behind
- // it is never reached. The Python says the same thing in words: its
- // second run prints "fits: … no change", not "maxSlide already 0".
+ // it is never reached. The reference said the same thing in words: its
+ // second run printed "fits: … no change", not "maxSlide already 0".
#expect(mineAgain.outcome == .fits(
combined: first.sharedRegionSize,
region: DSCMaxSlidePatcher.kernelSharedRegionSize
))
// `--force` skips the fits gate, so it is the one path that does reach
- // the already-zero check — and it still writes nothing.
- let theirsForced = try PythonReference.patch(directory: pythonSide, force: true)
- #expect(theirsForced.siteCount == 0)
+ // the already-zero check — and it still writes nothing. The reference's
+ // third run printed "maxSlide already 0; no change" and left its file
+ // alone, which is what the unchanged digest below has to show.
let mineForced = try DSCMaxSlidePatcher.patch(chunksDirectory: swiftSide, force: true)
#expect(mineForced.siteCount == 0)
#expect(mineForced.outcome == .alreadyZero)
- let (_, differing) = try Bytes.compareTrees(pythonSide, swiftSide)
- #expect(differing.isEmpty)
- print("[idempotence] both implementations report 0 sites on the second and third pass")
+ let afterThird = try Digest.sha256(
+ of: swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName)
+ )
+ #expect(afterThird == afterFirst, "a no-op pass rewrote the chunk")
+ #expect(afterThird == FrozenReference.realChangedChunks[MaxSlideFixture.mainChunkName])
}
}
// MARK: - The gate, on synthetic caches
-/// The four branches `cfw_patch_dsc_maxslide._self_test` covers, run against
-/// both implementations on identical synthetic caches.
+/// The four branches `cfw_patch_dsc_maxslide._self_test` covered, replayed on
+/// the same synthetic caches the reference was given — see `FrozenReference`
+/// for the digests of each one, before and after.
///
/// Synthetic rather than real because the real cache can only exercise one of
/// the four: it overflows. A cache that *fits* — an 18.x or 26.x base, the case
@@ -544,52 +600,55 @@ struct DSCMaxSlideGateTests {
/// SHARED_REGION_BASE_ARM64, which is also where the real cache starts.
static let mappingAddress: UInt64 = 0x1_8000_0000
- /// Build the same synthetic cache twice, hand one to each implementation,
- /// and require the two files to come out identical.
+ /// Build the synthetic cache the reference was given, hand it to the Swift,
+ /// and require the file to come out with the reference's digest.
+ ///
+ /// The input digest is checked first. Without it a change to `writeCache`
+ /// would silently move the comparison onto some other cache, and the output
+ /// digest would then be measuring the wrong thing.
private func compare(
named name: String,
regionSize: UInt64,
maxSlide: UInt64,
force: Bool = false,
+ reference: FrozenReference.GateCase,
expectedSites: Int,
expectedOutcome: DSCMaxSlidePatcher.Outcome,
expectedMaxSlideAfter: UInt64
) throws {
- _ = try #require(MaxSlideFixture.python, MaxSlideFixture.venvMissing)
-
- let pythonSide = MaxSlideFixture.scratchRoot.appendingPathComponent("\(name)_python")
let swiftSide = MaxSlideFixture.scratchRoot.appendingPathComponent("\(name)_swift")
- defer { MaxSlideFixture.discard(pythonSide, swiftSide) }
- for side in [pythonSide, swiftSide] {
- try Self.writeCache(into: side, regionSize: regionSize, maxSlide: maxSlide)
- }
+ defer { MaxSlideFixture.discard(swiftSide) }
+ try Self.writeCache(into: swiftSide, regionSize: regionSize, maxSlide: maxSlide)
- let theirs = try PythonReference.patch(directory: pythonSide, force: force)
- let mine = try DSCMaxSlidePatcher.patch(chunksDirectory: swiftSide, force: force)
+ let swiftMain = swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName)
+ let inputDigest = try Digest.sha256(of: swiftMain)
+ #expect(
+ inputDigest == reference.inputSHA256,
+ "\(name): this is not the cache the reference saw — \(inputDigest)"
+ )
- #expect(theirs.siteCount == expectedSites, "python: \(theirs.stdout)")
+ let mine = try DSCMaxSlidePatcher.patch(chunksDirectory: swiftSide, force: force)
#expect(mine.siteCount == expectedSites)
#expect(mine.outcome == expectedOutcome)
- let pythonMain = pythonSide.appendingPathComponent(MaxSlideFixture.mainChunkName)
- let swiftMain = swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName)
- let same = try Bytes.identical(pythonMain, swiftMain)
- #expect(same, "\(name): the two caches differ")
- let swiftSlide = try Bytes.maxSlide(of: swiftMain)
- let pythonSlide = try Bytes.maxSlide(of: pythonMain)
- #expect(swiftSlide == expectedMaxSlideAfter)
- #expect(pythonSlide == expectedMaxSlideAfter)
- print("[gate \(name)] both wrote \(expectedSites) site(s); maxSlide now "
- + "0x\(String(expectedMaxSlideAfter, radix: 16, uppercase: true))")
+ let outputDigest = try Digest.sha256(of: swiftMain)
+ #expect(
+ outputDigest == reference.outputSHA256,
+ "\(name): Swift \(outputDigest), reference \(reference.outputSHA256)"
+ )
+ #expect(try Bytes.maxSlide(of: swiftMain) == expectedMaxSlideAfter)
+ print("[gate \(name)] \(expectedSites) site(s) on the reference's \(reference.branch) "
+ + "branch; maxSlide now 0x\(String(expectedMaxSlideAfter, radix: 16, uppercase: true))")
}
- @Test("An overflowing cache is clamped by both implementations")
+ @Test("An overflowing cache is clamped, as the reference clamped it")
func overflowIsClamped() throws {
// iOS 27.0-like: 0x17C830000 + 0x20000000 > 0x180000000.
try compare(
named: "overflow",
regionSize: 0x1_7C83_0000,
maxSlide: 0x2000_0000,
+ reference: FrozenReference.overflow,
expectedSites: 1,
expectedOutcome: .overflow(
combined: 0x1_9C83_0000,
@@ -599,13 +658,14 @@ struct DSCMaxSlideGateTests {
)
}
- @Test("A cache that fits is left alone by both implementations")
+ @Test("A cache that fits is left alone, as the reference left it")
func fittingCacheIsUntouched() throws {
// 26.4-like: 0x140904000 + 0x20000000 <= 0x180000000.
try compare(
named: "fits",
regionSize: 0x1_4090_4000,
maxSlide: 0x2000_0000,
+ reference: FrozenReference.fits,
expectedSites: 0,
expectedOutcome: .fits(
combined: 0x1_6090_4000,
@@ -615,13 +675,14 @@ struct DSCMaxSlideGateTests {
)
}
- @Test("--force clamps a cache that fits, on both implementations")
+ @Test("--force clamps a cache that fits, to the reference's bytes")
func forceClampsAFittingCache() throws {
try compare(
named: "forced",
regionSize: 0x1_4090_4000,
maxSlide: 0x2000_0000,
force: true,
+ reference: FrozenReference.forced,
expectedSites: 1,
expectedOutcome: .forced(
combined: 0x1_6090_4000,
@@ -631,13 +692,14 @@ struct DSCMaxSlideGateTests {
)
}
- @Test("--force over an already-zero cache is a no-op on both implementations")
+ @Test("--force over an already-zero cache is a no-op, as it was for the reference")
func forceOverZeroIsANoOp() throws {
try compare(
named: "forced_zero",
regionSize: 0x1_4090_4000,
maxSlide: 0,
force: true,
+ reference: FrozenReference.forcedZero,
expectedSites: 0,
expectedOutcome: .alreadyZero,
expectedMaxSlideAfter: 0
@@ -658,6 +720,7 @@ struct DSCMaxSlideGateTests {
named: "overflow_zero",
regionSize: 0x1_9000_0000,
maxSlide: 0,
+ reference: FrozenReference.overflowWithZeroSlide,
expectedSites: 0,
expectedOutcome: .alreadyZero,
expectedMaxSlideAfter: 0
@@ -698,10 +761,10 @@ struct DSCMaxSlideGateTests {
/// dyld's own field-presence rule: the header struct ends where the mapping
/// table begins, so a `mappingOffset` that does not reach past `maxSlide`
- /// means this cache version has no such field. The Python has no equivalent
- /// gate and would write eight zero bytes into whatever is at 0xF0 — here
- /// that is a `dyld_cache_mapping_info.fileOffset`.
- @Test("A header too short to hold maxSlide is refused, where the Python would write")
+ /// means this cache version has no such field. The reference had no
+ /// equivalent gate and would write eight zero bytes into whatever is at
+ /// 0xF0 — here that is a `dyld_cache_mapping_info.fileOffset`.
+ @Test("A header too short to hold maxSlide is refused, where the reference would write")
func truncatedHeaderIsRefused() throws {
let directory = MaxSlideFixture.scratchRoot.appendingPathComponent("shortheader")
defer { MaxSlideFixture.discard(directory) }
@@ -747,37 +810,30 @@ struct DSCMaxSlideGateTests {
}
/// The Python's own self-test fixture: a bare 0x100-byte header with no
- /// mapping table. The Python patches it; this refuses it, because every
- /// write here goes through `DSCChunkSet`, which has nothing to address it
- /// with. A documented divergence, and a strictly safer one — the input is
- /// not a shared cache.
- @Test("A header with no mapping table is refused, where the Python patches it")
+ /// mapping table. The reference patched it — it printed `overflow: … set
+ /// maxSlide 0x20000000 -> 0x0` and the field read back as 0. This refuses
+ /// it, because every write here goes through `DSCChunkSet`, which has
+ /// nothing to address such a file with. A documented divergence, and a
+ /// strictly safer one — the input is not a shared cache.
+ @Test("A header with no mapping table is refused, where the reference patched it")
func noMappingTableIsRefused() throws {
- _ = try #require(MaxSlideFixture.python, MaxSlideFixture.venvMissing)
-
- let pythonSide = MaxSlideFixture.scratchRoot.appendingPathComponent("headeronly_python")
let swiftSide = MaxSlideFixture.scratchRoot.appendingPathComponent("headeronly_swift")
- defer { MaxSlideFixture.discard(pythonSide, swiftSide) }
-
- for side in [pythonSide, swiftSide] {
- try FileManager.default.createDirectory(at: side, withIntermediateDirectories: true)
- var bytes = [UInt8](repeating: 0, count: 0x100)
- for (index, byte) in Array("dyld_v1 arm64e".utf8).enumerated() { bytes[index] = byte }
- func put(_ value: UInt64, at offset: Int) {
- withUnsafeBytes(of: value.littleEndian) { source in
- for (index, byte) in source.enumerated() { bytes[offset + index] = byte }
- }
+ defer { MaxSlideFixture.discard(swiftSide) }
+
+ try FileManager.default.createDirectory(at: swiftSide, withIntermediateDirectories: true)
+ var bytes = [UInt8](repeating: 0, count: 0x100)
+ for (index, byte) in Array("dyld_v1 arm64e".utf8).enumerated() { bytes[index] = byte }
+ func put(_ value: UInt64, at offset: Int) {
+ withUnsafeBytes(of: value.littleEndian) { source in
+ for (index, byte) in source.enumerated() { bytes[offset + index] = byte }
}
- put(Self.mappingAddress, at: 0xE0)
- put(0x1_7C83_0000, at: 0xE8)
- put(0x2000_0000, at: 0xF0)
- try Data(bytes).write(
- to: side.appendingPathComponent(MaxSlideFixture.mainChunkName)
- )
}
-
- let theirs = try PythonReference.patch(directory: pythonSide)
- #expect(theirs.siteCount == 1, "the Python patches a mapping-less header")
+ put(Self.mappingAddress, at: 0xE0)
+ put(0x1_7C83_0000, at: 0xE8)
+ put(0x2000_0000, at: 0xF0)
+ try Data(bytes).write(
+ to: swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName)
+ )
#expect(throws: DSCError.self) {
_ = try DSCMaxSlidePatcher.patch(chunksDirectory: swiftSide, verbose: false)
@@ -786,6 +842,5 @@ struct DSCMaxSlideGateTests {
of: swiftSide.appendingPathComponent(MaxSlideFixture.mainChunkName)
)
#expect(untouchedSlide == 0x2000_0000, "the refusal still wrote")
- print("[no mappings] python clamped it; swift refused and left it alone")
}
}
diff --git a/tests/FirmwarePatcherTests/DSCXPCLWCRPatcherTests.swift b/tests/FirmwarePatcherTests/DSCXPCLWCRPatcherTests.swift
index f1ac6d4e..090ac6f7 100644
--- a/tests/FirmwarePatcherTests/DSCXPCLWCRPatcherTests.swift
+++ b/tests/FirmwarePatcherTests/DSCXPCLWCRPatcherTests.swift
@@ -1,11 +1,13 @@
// DSCXPCLWCRPatcherTests.swift — Parity for the libxpc LWCR patch.
//
-// The only independent reference for this patch is
-// `scripts/patchers/cfw_patch_xpc_lwcr.py`, so every test here runs that
-// Python on one clone of the real shared cache, runs `DSCXPCLWCRPatcher` on a
-// second clone, and compares the two byte for byte. A port that writes the
-// right instruction at the wrong address, or re-attests a different page,
-// fails on the bytes rather than on a number this file wrote down.
+// The only independent reference for this patch was
+// `scripts/patchers/cfw_patch_xpc_lwcr.py`, driven through `cfw.py
+// patch-xpc-lwcr`. That Python is gone, so what it produced on the real cache
+// is frozen in `FrozenReference` below — the three sites, the six instruction
+// words, and the SHA-256 of the one chunk it changed. `DSCXPCLWCRPatcher` runs
+// on a clone and is graded against those. A port that writes the right
+// instruction at the wrong address, or re-attests a different page, lands on a
+// different digest.
//
// Fixture: `VPHONE_DSC_PRISTINE`, or `ipsws/ref_extract/dsc_pristine` by
// default. Without it these FAIL. A bare `guard let … else { return }` is
@@ -20,9 +22,64 @@
@testable import FirmwarePatcher
import Capstone
+import CryptoKit
import Foundation
import Testing
+// MARK: - The frozen reference
+
+/// What the reference Python wrote on the real 24A435 arm64e shared cache.
+///
+/// Recorded from live runs at commit 78cbeea, each line below quoting the log
+/// the run printed:
+///
+/// .venv/bin/python3 scripts/patchers/cfw.py \
+/// patch-xpc-lwcr <clone of ipsws/ref_extract/dsc_pristine>
+private enum FrozenReference {
+ /// Python: `[.] __xpc_token_satisfies_lwcr @ 0x1805DD5BC`.
+ static let functionVMA: UInt64 = 0x1_805D_D5BC
+
+ /// Python: the three `[+] wrote …` lines, in the order it printed them —
+ /// `cset w0, eq at 0x1805DD644`, `nop at 0x1805DD648`, `nop at 0x1805DD64C`.
+ static let writtenVMAs: [UInt64] = [0x1_805D_D644, 0x1_805D_D648, 0x1_805D_D64C]
+
+ /// Python: the left half of each `(… -> …)` on those same lines.
+ static let originalWords: [Data] = [
+ Data([0xE8, 0x07, 0x9F, 0x1A]),
+ Data([0x08, 0x00, 0x08, 0x4A]),
+ Data([0x88, 0x01, 0x00, 0x36]),
+ ]
+
+ /// Python: the right half — `cset w0, eq`, then two `nop`s.
+ static let patchedWords: [Data] = [
+ Data([0xE0, 0x17, 0x9F, 0x1A]),
+ Data([0x1F, 0x20, 0x03, 0xD5]),
+ Data([0x1F, 0x20, 0x03, 0xD5]),
+ ]
+
+ /// Python: the instruction text on the three `[.]` lines that precede the
+ /// writes — `cset w8, ne`, `eor w8, w0, w8`, `tbz w8, #0, #0x1805dd67c`.
+ static let idiomMnemonics = ["cset", "eor", "tbz"]
+
+ /// `cmp -s` against the pristine tree after the run: exactly one chunk
+ /// moved, to this digest, from `shasum -a 256 <output>/…arm64e.01`.
+ ///
+ /// The digest covers the re-attestation as well as the three words — the
+ /// Python logged `re-attest: wrote slot 119 of dyld_shared_cache_arm64e.01`
+ /// (`e19e728a.. -> 7a87ce53..`), `updated 1 slot hash(es) across 1
+ /// chunk(s)`.
+ ///
+ /// Two further runs pinned the edges. Re-run over its own output: `already
+ /// patched at 0x1805DD644 (cset w0,eq; nop; nop); nothing to
+ /// patch/re-attest`, no `wrote` line, digest unchanged. `--dry-run` on a
+ /// fresh clone: three `would write` lines at the same three addresses, and
+ /// no chunk changed at all.
+ static let changedChunks: [String: String] = [
+ "dyld_shared_cache_arm64e.01":
+ "94ab6599c12bb8f12ef7f19dc8fde081b55a91cf40992a23444741b3e9d43309",
+ ]
+}
+
// MARK: - Fixture
private enum LWCRFixture {
@@ -68,12 +125,6 @@ private enum LWCRFixture {
.appendingPathComponent("vphone_dsc_xpclwcr")
}
- /// 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
- }
-
/// 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) }
@@ -132,6 +183,41 @@ private enum LWCRFixture {
}
return differing.sorted()
}
+
+ /// Which chunk files a run moved away from the pristine tree.
+ static func changedFiles(in directory: URL) throws -> [String] {
+ let pristine = try #require(self.pristine, missing)
+ return try differences(between: pristine, and: directory)
+ }
+}
+
+// MARK: - Digests
+
+/// SHA-256 of a cache chunk, streamed so a 131 MB file never lands in memory
+/// whole. The hex spelling matches `shasum -a 256`, which produced the frozen
+/// digests.
+private enum Digest {
+ static func sha256(of url: URL) throws -> String {
+ let handle = try FileHandle(forReadingFrom: url)
+ defer { try? handle.close() }
+ var hasher = SHA256()
+ while let block = try handle.read(upToCount: 4 << 20), !block.isEmpty {
+ hasher.update(data: block)
+ }
+ return hasher.finalize().map { String(format: "%02x", $0) }.joined()
+ }
+
+ /// Assert that `directory` holds exactly the chunks the reference changed,
+ /// with exactly the reference's bytes.
+ static func expectMatchesReference(_ directory: URL) throws {
+ let changed = try LWCRFixture.changedFiles(in: directory)
+ #expect(changed == FrozenReference.changedChunks.keys.sorted())
+ for name in changed {
+ let digest = try sha256(of: directory.appendingPathComponent(name))
+ let frozen = FrozenReference.changedChunks[name] ?? "(not a chunk the Python moved)"
+ #expect(digest == frozen, "\(name): Swift \(digest), reference \(frozen)")
+ }
+ }
}
// MARK: - Subprocess helper
@@ -165,84 +251,25 @@ private enum Shell {
}
}
-// MARK: - The reference Python, driven through its own CLI
-
-private enum ReferencePython {
- /// Addresses the reference reports writing, parsed off its own log lines:
- ///
- /// [+] wrote cset w0, eq at 0x1805DD644 (e8079f1a -> e0179f1a)
- struct Run {
- let status: Int32
- let stdout: String
- let writtenVMAs: [UInt64]
- let alreadyPatched: Bool
- }
-
- /// Run `cfw.py patch-xpc-lwcr <directory>`, exactly as the install scripts do.
- static func patch(directory: URL, dryRun: Bool = false) throws -> Run {
- guard let python = LWCRFixture.python else { throw CocoaError(.fileNoSuchFile) }
- let script = LWCRFixture.repoRoot.appendingPathComponent("scripts/patchers/cfw.py")
- let result = try Shell.run(
- executable: python,
- arguments: [script.path, "patch-xpc-lwcr", directory.path]
- + (dryRun ? ["--dry-run"] : [])
- )
- var addresses: [UInt64] = []
- for line in result.stdout.split(separator: "\n") {
- guard line.contains("[+]"), line.contains(dryRun ? "would write" : "wrote") else {
- continue
- }
- // "… at 0x1805DD644 (…)" — the address is the token after " at ".
- guard let atRange = line.range(of: " at 0x") else { continue }
- let rest = line[atRange.upperBound...]
- let digits = rest.prefix { $0.isHexDigit }
- if let value = UInt64(digits, radix: 16) { addresses.append(value) }
- }
- return Run(
- status: result.status,
- stdout: result.stdout + result.stderr,
- writtenVMAs: addresses,
- alreadyPatched: result.stdout.contains("already patched")
- )
- }
-}
-
-// MARK: - Parity against the Python, on the real cache
+// MARK: - Parity against the frozen reference, on the real cache
@Suite(.serialized, .enabled(if: LWCRFixture.runs, LWCRFixture.skipReason))
struct DSCXPCLWCRParityTests {
- @Test("Swift and the Python patch the same three sites, byte for byte")
- func patchedClonesAreIdentical() throws {
+ @Test("Swift patches the reference's three sites, to the reference's bytes")
+ func patchedCloneMatchesTheReference() throws {
_ = try #require(LWCRFixture.pristine, LWCRFixture.missing)
- try #require(
- LWCRFixture.python != nil,
- "the project venv is required for the cross-check — run `make setup_venv`"
- )
- let pythonClone = try LWCRFixture.cloneCache(named: "python")
let swiftClone = try LWCRFixture.cloneCache(named: "swift")
- defer { LWCRFixture.discard(pythonClone, swiftClone) }
-
- // The two trees start out identical, or the comparison below proves
- // nothing about the patch.
- #expect(try LWCRFixture.differences(between: pythonClone, and: swiftClone).isEmpty)
-
- let reference = try ReferencePython.patch(directory: pythonClone)
- #expect(reference.status == 0, "python failed: \(reference.stdout)")
- #expect(reference.writtenVMAs.count == 3, "python wrote \(reference.writtenVMAs.count) sites")
+ defer { LWCRFixture.discard(swiftClone) }
let outcome = try DSCXPCLWCRPatcher.apply(directory: swiftClone, log: nil)
#expect(outcome.status == .patched)
#expect(outcome.siteCount == 3, "swift wrote \(outcome.siteCount) sites")
- #expect(outcome.records.compactMap(\.virtualAddress) == reference.writtenVMAs)
-
- let differences = try LWCRFixture.differences(between: pythonClone, and: swiftClone)
- #expect(differences.isEmpty, "chunks differ after patching: \(differences)")
+ #expect(outcome.records.compactMap(\.virtualAddress) == FrozenReference.writtenVMAs)
+ #expect(outcome.records.map(\.originalBytes) == FrozenReference.originalWords)
+ #expect(outcome.records.map(\.patchedBytes) == FrozenReference.patchedWords)
- print("[xpc_lwcr] python \(reference.writtenVMAs.count) sites, "
- + "swift \(outcome.siteCount) sites, "
- + "\(outcome.records.map { "0x" + String($0.virtualAddress ?? 0, radix: 16, uppercase: true) })"
- + " — clones byte-identical")
+ try Digest.expectMatchesReference(swiftClone)
}
@Test("The replacement words are exactly cset w0,eq / nop / nop")
@@ -259,6 +286,10 @@ struct DSCXPCLWCRParityTests {
#expect(outcome.records[1].patchedBytes == ARM64.nop)
#expect(outcome.records[2].patchedBytes == ARM64.nop)
+ // …and the encoders agree with the words the reference actually wrote.
+ #expect(expectedCset == FrozenReference.patchedWords[0])
+ #expect(ARM64.nop == FrozenReference.patchedWords[1])
+
// The three sites are consecutive words of one function.
let addresses = outcome.records.compactMap(\.virtualAddress)
#expect(addresses.count == 3)
@@ -269,47 +300,37 @@ struct DSCXPCLWCRParityTests {
@Test("A dry run reports the same three sites and writes nothing")
func dryRunWritesNothing() throws {
_ = try #require(LWCRFixture.pristine, LWCRFixture.missing)
- try #require(LWCRFixture.python != nil)
- let untouched = try LWCRFixture.cloneCache(named: "dry_reference")
let clone = try LWCRFixture.cloneCache(named: "dry")
- defer { LWCRFixture.discard(untouched, clone) }
+ defer { LWCRFixture.discard(clone) }
let outcome = try DSCXPCLWCRPatcher.apply(directory: clone, dryRun: true, log: nil)
#expect(outcome.status == .patched)
#expect(outcome.siteCount == 3)
+ // The reference's own dry run named these three and changed no chunk.
+ #expect(outcome.records.compactMap(\.virtualAddress) == FrozenReference.writtenVMAs)
- let differences = try LWCRFixture.differences(between: untouched, and: clone)
- #expect(differences.isEmpty, "a dry run modified \(differences)")
-
- let reference = try ReferencePython.patch(directory: untouched, dryRun: true)
- #expect(reference.writtenVMAs == outcome.records.compactMap(\.virtualAddress))
+ let changed = try LWCRFixture.changedFiles(in: clone)
+ #expect(changed.isEmpty, "a dry run modified \(changed)")
}
- @Test("Re-running over a patched cache is a no-op, in both implementations")
+ @Test("Re-running over a patched cache is a no-op")
func secondRunIsANoOp() throws {
_ = try #require(LWCRFixture.pristine, LWCRFixture.missing)
- try #require(LWCRFixture.python != nil)
- let pythonClone = try LWCRFixture.cloneCache(named: "python_twice")
let swiftClone = try LWCRFixture.cloneCache(named: "swift_twice")
- defer { LWCRFixture.discard(pythonClone, swiftClone) }
+ defer { LWCRFixture.discard(swiftClone) }
- _ = try ReferencePython.patch(directory: pythonClone)
_ = try DSCXPCLWCRPatcher.apply(directory: swiftClone, log: nil)
- // Second pass. Neither may raise, and neither may write.
- let second = try ReferencePython.patch(directory: pythonClone)
- #expect(second.status == 0, "python raised on a second pass: \(second.stdout)")
- #expect(second.alreadyPatched)
- #expect(second.writtenVMAs.isEmpty)
-
+ // Second pass. It may not raise, and it may not write — the reference
+ // printed `already patched … nothing to patch/re-attest` here and left
+ // its own digest standing, so the bytes must still be the frozen ones.
let outcome = try DSCXPCLWCRPatcher.apply(directory: swiftClone, log: nil)
#expect(outcome.status == .alreadyPatched)
#expect(outcome.siteCount == 0)
- let differences = try LWCRFixture.differences(between: pythonClone, and: swiftClone)
- #expect(differences.isEmpty, "chunks differ after a second pass: \(differences)")
+ try Digest.expectMatchesReference(swiftClone)
}
@Test("Every page the writes dirtied is re-attested")
@@ -377,6 +398,8 @@ struct DSCXPCLWCRShapeTests {
mangledAddress,
"the double-underscore spelling is the one Mach-O stores"
)
+ // The reference resolved the same symbol to the same address.
+ #expect(mangled == FrozenReference.functionVMA)
// The single-underscore source spelling is a miss, which is why the
// patcher tries both rather than only the obvious one.
let sourceSpelling = try chunks.resolveLocalSymbol(DSCXPCLWCRPatcher.symbol)
@@ -407,6 +430,12 @@ struct DSCXPCLWCRShapeTests {
#expect(site.tbz.mnemonic == "tbz")
#expect(site.eor.address == site.cset.address + 4)
#expect(site.tbz.address == site.eor.address + 4)
+ // The same three instructions, at the same three addresses, the
+ // reference printed before it wrote.
+ #expect([site.cset.mnemonic, site.eor.mnemonic, site.tbz.mnemonic]
+ == FrozenReference.idiomMnemonics)
+ #expect([site.cset.address, site.eor.address, site.tbz.address]
+ == FrozenReference.writtenVMAs)
// The xor's left operand is the matcher's return register, and its
// right operand is what the cset wrote — the dataflow that makes the
// match unambiguous.
diff --git a/tests/FirmwarePatcherTests/MachOParserBoundsTests.swift b/tests/FirmwarePatcherTests/MachOParserBoundsTests.swift
new file mode 100644
index 00000000..ac1ce53a
--- /dev/null
+++ b/tests/FirmwarePatcherTests/MachOParserBoundsTests.swift
@@ -0,0 +1,164 @@
+// MachOParserBoundsTests.swift — The load-command walk must not read past EOF.
+//
+// `Data.loadLE` is a `precondition`, so an out-of-range read does not throw: it
+// kills the process with SIGTRAP (exit 133). Before `forEachLoadCommand` bounded
+// each command by its own `cmdsize` and by the file, the walk checked only that
+// a command's 8-byte header fit and then read fields up to `+0x38` inside it —
+// so every CFW Mach-O patcher died on `head -c 64 <any binary>` instead of
+// reporting a bad file. These tests pass by *completing*: a regression here
+// crashes the test runner rather than failing an expectation.
+
+@testable import FirmwarePatcher
+import Foundation
+import Testing
+
+@Suite("MachOParser bounds")
+struct MachOParserBoundsTests {
+ // MARK: - Builders
+
+ /// A `mach_header_64` that claims `ncmds` commands totalling `sizeofcmds`.
+ static func header(ncmds: UInt32, sizeofcmds: UInt32) -> Data {
+ var data = Data()
+ func append(_ value: UInt32) {
+ withUnsafeBytes(of: value.littleEndian) { data.append(contentsOf: $0) }
+ }
+ append(0xFEED_FACF) // magic: MH_MAGIC_64
+ append(0x0100_000C) // cputype: CPU_TYPE_ARM64
+ append(2) // cpusubtype: arm64e
+ append(2) // filetype: MH_EXECUTE
+ append(ncmds)
+ append(sizeofcmds)
+ append(0) // flags
+ append(0) // reserved
+ return data
+ }
+
+ /// An `LC_SEGMENT_64` whose declared `cmdsize` is free to lie about `nsects`.
+ static func segment(
+ name: String,
+ vmAddr: UInt64,
+ vmSize: UInt64,
+ nsects: UInt32,
+ cmdsize: UInt32
+ ) -> Data {
+ var data = Data()
+ func append32(_ value: UInt32) {
+ withUnsafeBytes(of: value.littleEndian) { data.append(contentsOf: $0) }
+ }
+ func append64(_ value: UInt64) {
+ withUnsafeBytes(of: value.littleEndian) { data.append(contentsOf: $0) }
+ }
+ append32(0x19) // LC_SEGMENT_64
+ append32(cmdsize)
+ var segname = Data(name.utf8).prefix(16)
+ segname.append(contentsOf: [UInt8](repeating: 0, count: 16 - segname.count))
+ data.append(segname)
+ append64(vmAddr)
+ append64(vmSize)
+ append64(0) // fileoff
+ append64(vmSize) // filesize
+ append32(5) // maxprot: r-x
+ append32(5) // initprot: r-x
+ append32(nsects)
+ append32(0) // flags
+ return data
+ }
+
+ // MARK: - Positive control
+
+ // Without this, "returns nothing" would be indistinguishable from a guard
+ // that rejects everything.
+ @Test func aWellFormedSegmentStillParses() {
+ var image = Self.header(ncmds: 1, sizeofcmds: 72)
+ image.append(Self.segment(
+ name: "__TEXT",
+ vmAddr: 0x1_0000_0000,
+ vmSize: 0x4000,
+ nsects: 0,
+ cmdsize: 72
+ ))
+
+ let segments = MachOParser.parseSegments(from: image)
+ #expect(segments.count == 1)
+ #expect(segments.first?.name == "__TEXT")
+ #expect(segments.first?.vmAddr == 0x1_0000_0000)
+ #expect(MachOParser.vaToFileOffset(0x1_0000_0010, segments: segments) == 0x10)
+ }
+
+ // MARK: - Truncation
+
+ // The original repro: `head -c 64 ipsws/ref_extract/macho_pristine/seputil`.
+ // Header says 23 commands in 2312 bytes; the file holds 64.
+ @Test func aTruncatedLoadCommandTableYieldsNothingInsteadOfTrapping() {
+ var image = Self.header(ncmds: 23, sizeofcmds: 2312)
+ image.append(Data(repeating: 0, count: 32)) // half of one LC_SEGMENT_64
+ #expect(image.count == 64)
+
+ #expect(MachOParser.parseSegments(from: image).isEmpty)
+ #expect(MachOParser.parseSections(from: image).isEmpty)
+ #expect(MachOParser.parseSymtab(from: image) == nil)
+ #expect(MachOParser.findSymbol(containing: "anything", in: image) == nil)
+ }
+
+ // A command whose body is one byte short of fitting is still a command the
+ // walk must not enter — the last field read lives at the very end of it.
+ @Test func aSegmentOneByteShortOfFittingIsNotParsed() {
+ var image = Self.header(ncmds: 1, sizeofcmds: 72)
+ image.append(Self.segment(
+ name: "__TEXT",
+ vmAddr: 0x1_0000_0000,
+ vmSize: 0x4000,
+ nsects: 0,
+ cmdsize: 72
+ ))
+ image.removeLast()
+
+ #expect(MachOParser.parseSegments(from: image).isEmpty)
+ }
+
+ // MARK: - Malformed sizes
+
+ // `cmdsize == 0` used to advance the cursor by zero, re-reading the same
+ // command `ncmds` times. Bounded, but it is not a table worth trusting.
+ @Test func aZeroSizedCommandStopsTheWalk() {
+ var image = Self.header(ncmds: 4, sizeofcmds: 32)
+ var zero = Data()
+ withUnsafeBytes(of: UInt32(0x19).littleEndian) { zero.append(contentsOf: $0) }
+ withUnsafeBytes(of: UInt32(0).littleEndian) { zero.append(contentsOf: $0) }
+ image.append(zero)
+ image.append(Data(repeating: 0, count: 24))
+
+ #expect(MachOParser.parseSegments(from: image).isEmpty)
+ }
+
+ // `nsects` is inside the command but the section table it describes is not:
+ // the command declares one section and then stops at the fixed 72 bytes.
+ @Test func aSectionTableOutsideItsCommandIsNotRead() {
+ var image = Self.header(ncmds: 1, sizeofcmds: 72)
+ image.append(Self.segment(
+ name: "__TEXT",
+ vmAddr: 0x1_0000_0000,
+ vmSize: 0x4000,
+ nsects: 1, // claims a section_64 that cmdsize leaves no room for
+ cmdsize: 72
+ ))
+ image.append(Data(repeating: 0xFF, count: 80)) // trailing bytes, not ours to read
+
+ // The segment itself is well formed, so it still parses…
+ #expect(MachOParser.parseSegments(from: image).count == 1)
+ // …but the section it lies about does not.
+ #expect(MachOParser.parseSections(from: image).isEmpty)
+ }
+
+ // MARK: - Not a Mach-O at all
+
+ @Test func nonMachOInputIsRejectedWithoutReading() {
+ let text = Data("this is not a mach-o, not even a little bit of one".utf8)
+ #expect(MachOParser.parseSegments(from: text).isEmpty)
+ #expect(MachOParser.parseSections(from: text).isEmpty)
+ #expect(MachOParser.parseSymtab(from: text) == nil)
+
+ #expect(MachOParser.parseSegments(from: Data()).isEmpty)
+ #expect(MachOParser.parseSymtab(from: Data()) == nil)
+ }
+}
diff --git a/tests/VPhoneCoreTests/ResourcesTests.swift b/tests/VPhoneCoreTests/ResourcesTests.swift
index bcf6f1b0..38c92968 100644
--- a/tests/VPhoneCoreTests/ResourcesTests.swift
+++ b/tests/VPhoneCoreTests/ResourcesTests.swift
@@ -15,7 +15,8 @@ struct ResourcesTests {
let r = VPhoneResources.resolve(executablePath: exe)
#expect(r.base.path == "/Applications/vphone-cli.app/Contents/Resources")
#expect(r.fwPrepareScript.path == "/Applications/vphone-cli.app/Contents/Resources/scripts/fw_prepare.sh")
- #expect(r.cfwPy.path == "/Applications/vphone-cli.app/Contents/Resources/scripts/patchers/cfw.py")
+ #expect(r.pmd3Bridge.path
+ == "/Applications/vphone-cli.app/Contents/Resources/scripts/pymobiledevice3_bridge.py")
}
@Test func devLayoutWalksUpToProjectRoot() throws {
@@ -43,14 +44,41 @@ struct ResourcesTests {
#expect(VPhoneResources.userDataRoot().path.hasSuffix("/.vphone"))
}
- /// These all shell out; a missing interpreter must return false, not throw.
- @Test func venvProbesAreTotalForAMissingInterpreter() {
+ /// The probe shells out; a missing interpreter must return false, not throw.
+ @Test func venvProbeIsTotalForAMissingInterpreter() {
let r = VPhoneResources(base: URL(fileURLWithPath: "/x"))
let missing = URL(fileURLWithPath: "/nonexistent/bin/python3")
#expect(r.pythonIsUsable(missing) == false)
- #expect(r.keystoneIsUsable(missing) == false)
- #expect(r.venvIsUsable(missing) == false)
- #expect(r.repairKeystone(missing) == false)
+ }
+
+ /// The venv exists for `scripts/pymobiledevice3_bridge.py` and nothing else
+ /// now that the firmware patchers are Swift, so the requirements must not
+ /// name a patcher-only package. capstone, keystone-engine and pyimg4 were
+ /// the three; pyimg4 still arrives transitively via pymobiledevice3.
+ @Test func fallbackRequirementsCarryNoPatcherOnlyPackages() {
+ let names = VPhoneResources.fallbackRequirements
+ for dead in ["capstone", "keystone-engine", "pyimg4"] {
+ #expect(names.contains { $0.hasPrefix(dead) } == false, "\(dead) is patcher-only")
+ }
+ #expect(names.contains { $0.hasPrefix("pymobiledevice3") })
+ #expect(names.contains("ipsw-parser"))
+ }
+
+ /// `fallbackRequirements` claims to mirror requirements.txt, so check the
+ /// real file rather than trusting the comment. Derived from `#filePath`:
+ /// `swift test` makes no promise about the working directory.
+ @Test func requirementsFileMatchesTheFallbackList() throws {
+ let repoRoot = URL(filePath: #filePath)
+ .deletingLastPathComponent() // VPhoneCoreTests
+ .deletingLastPathComponent() // tests
+ .deletingLastPathComponent() // <root>
+ let file = repoRoot.appending(path: "requirements.txt")
+ try #require(FileManager.default.fileExists(atPath: file.path))
+ let listed = try String(contentsOf: file, encoding: .utf8)
+ .split(whereSeparator: \.isNewline)
+ .map { $0.trimmingCharacters(in: .whitespaces) }
+ .filter { !$0.isEmpty && !$0.hasPrefix("#") }
+ #expect(listed == VPhoneResources.fallbackRequirements)
}
@Test func managedVenvDefaultsUnderDotVphone() {