Run a virtual iPhone on an Apple Silicon Mac.
Swift
chore: remove the last dead Python, and fix what removing it broke
Lakr9296442c2847
diff --git a/AGENTS.md b/AGENTS.mdindex 2d4fba28..2d93c822 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -72,6 +72,28 @@ sources/├── vphone-letmein/ # Opens a short AMFI window so vphone-vm can exec│ └── main.c # Plain C; Foundation + libobjc only│+├── vphone-archive/ # Thin shell over VPhoneArchive+│ └── main.swift # extract / create / decompress / list / cat / fingerprint+│+├── VPhoneCore/ # No UI, no guest — what both entry points share+│ ├── VPhoneBootCLI.swift # Boot flags, parsed by both binaries; renders argv+│ ├── VPhoneGuestLauncher.swift # Decides on the AMFI window, spawns vphone-vm+│ ├── VPhoneBundle*.swift # VM bundle layout, ops, reporting+│ ├── VPhoneVirtualMachineManifest.swift # config.plist (replaced scripts/vm_manifest.py)+│ ├── VPhoneAPFSSnapshot.swift # Offline APFS boot-snapshot flip+│ └── … # networking, resources, process running, pickers+│+├── VPhoneArchive/ # libarchive: replaces gtar, bsdtar, unzip and zstd+│ ├── VPhoneArchiveExtractor.swift # Unpack, incl. the hand-written --no-overwrite-dir+│ ├── VPhoneArchiveWriter.swift # Pack + single-stream decompress+│ ├── VPhoneArchivePaths.swift # realpath(3) — NOT the Foundation equivalents+│ └── VPhoneTreeFingerprint.swift # Compare two extracted trees, field by field+│+├── FirmwarePatcher/ # The Swift firmware pipeline (largest module)+│ ├── IBoot/ Kernel/ TXM/ # Boot-chain patches; Kernel/JBPatches/ is the JB set+│ ├── DeviceTree/ Filesystem/ # DT edits, cryptex/rootfs work+│ └── ARM64/ Binary/ Core/ Pipeline/ # Disassembly, Mach-O, driver+│└── VPhoneVMKit/ # Everything that touches a running guest├── VPhoneGuestApp.swift # NSApplication wiring (keeps the entry point logic-free)├── VPhoneAppDelegate.swift # App lifecycle, SIGINT, VM start/stop@@ -133,7 +155,6 @@ scripts/├── repos/ # Toolchain source repos (git submodules: trustcache, insert_dylib, libimobiledevice stack)├── patches/ # Build-time patches (libirecovery)├── fw_prepare.sh # Download IPSWs, merge cloudOS into iPhone-├── fw_manifest.py # Generate hybrid BuildManifest/Restore plists├── cfw_install.sh # Install CFW (regular)├── cfw_install_dev.sh # Regular + rpcserver daemon├── cfw_install_jb.sh # Regular + jetsam fix + procursus@@ -147,15 +168,18 @@ scripts/├── setup_libimobiledevice.sh # Build libimobiledevice stack from scripts/repos submodules└── tail_jb_patch_logs.sh # Tail JB patch log output-tools/-└── apfs_snap_rename.py # Offline APFS boot-snapshot flip (used by cfw_install_host.sh)+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+├── vanilla/ jb/ # Per-flavour install.sh; jb/userland/* are empty slots+└── docs/phase-matrix.mdresearch/ # Detailed firmware/patch documentation```### Key Patterns-- **Three host binaries, one of them entitled.** `vphone-cli` carries no entitlements, so it launches on any host and is always there to explain what is wrong. `vphone-vm` holds all 7 private keys and is the only thing amfid can refuse. `vphone-letmein` opens a window when it does. **Do not sign `vphone-cli` with entitlements** — that is how it used to be, and it is why the entry point could not start without a bypass already running.+- **Four host binaries, one of them entitled.** `vphone-cli` carries no entitlements, so it launches on any host and is always there to explain what is wrong. `vphone-vm` holds all 7 private keys and is the only thing amfid can refuse. `vphone-letmein` opens a window when it does, and `vphone-archive` does the unpacking. **Do not sign `vphone-cli` with entitlements** — that is how it used to be, and it is why the entry point could not start without a bypass already running.- **Guest launches go through `VPhoneGuestLaunchPlanner`** (`VPhoneCore`). It resolves `vphone-vm` as a sibling of the running image — never through `PATH` — and decides once per command whether an AMFI window is needed, by running `vphone-vm --help` and looking for SIGKILL. Never spawn the guest directly.- **Private API access:** Via [Dynamic](https://github.com/mhdhejazi/Dynamic) library (runtime method dispatch from pure Swift). No ObjC bridge.- **App lifecycle:** `vphone-vm/main.swift` → `VPhoneGuestApp.run()` → `NSApplication` + `VPhoneAppDelegate`. Entry points hold no logic.diff --git a/cfw-kit/run.sh b/cfw-kit/run.shindex bc8b338d..66ef3200 100755--- a/cfw-kit/run.sh+++ b/cfw-kit/run.sh@@ -84,7 +84,6 @@ elseP="$PROJ/.tools/bin:$PROJ/.venv/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"fiexport PATH="$P"-PY="${VPHONE_PYTHON:-$PROJ/.venv/bin/python3}"# Variables the installers read, forwarded explicitly. An expansion-produced# ${VAR:+NAME=val} is not parsed as a shell assignment, hence `env`.@@ -152,8 +151,18 @@ cleanuptrap - EXITecho "[*] flipping boot snapshot offline (com.apple.os.update -> live volume)..."-[[ -x "$PY" ]] || { echo "[-] python3 not found at $PY — snapshot NOT flipped; the VM will boot the stock snapshot." >&2; exit 1; }-"$PY" "$PROJ/tools/apfs_snap_rename.py" "$IMG"+# 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+[[ -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"# Upstream removes the extracted cfw_input/ here for `make` idempotence. The kit# keeps it: re-running a variant is the normal case while designing a userland,diff --git a/research/intg_update_status.md b/research/intg_update_status.mdindex f6ccca9a..f19a34a7 100644--- a/research/intg_update_status.md+++ b/research/intg_update_status.md@@ -1,91 +1,147 @@-# `vphone-intg-update` — where this got to+# `vphone-intg-update` — progress against the migration plan-> 2026-09-23. Branch off `qof-update-26-fall` @ `6d5ce7d`, pushed.+> 2026-09-23. Branch off `qof-update-26-fall` @ `6d5ce7d`.>-> Plan: `~/Desktop/vphone-cli-migration-plan.md`, and the approved execution-> order in `~/.claude/plans/mellow-weaving-gem.md`.+> Plan: `~/Desktop/vphone-cli-migration-plan.md`. Its phases are P0 → P4; the+> approved execution order for this branch (`~/.claude/plans/mellow-weaving-gem.md`)+> covered **P0 and part of P0.5 only**, and said so up front. This file is the+> ledger, because `/TODO.md` is not part of this repo's workflow.-## Done+## Where the four delivery lines stand-| step | what | state |+| line | plan's completion bar | now || --- | --- | --- |-| S0 | libzstd static in the xcframework? | **yes** — proven at runtime |-| S2 | liblzma MT encoder? | **yes** — 4.84x at 1 GiB |-| 1 | entitlements moved off `vphone-cli` onto `vphone-vm` | done, verified |-| 2 | `vphone-letmein` in, `amfidont` scripts out, docs in 6 languages | done |-| 3 | P0's three Python files | done; two deleted, one kept as reference |-| 4 | `custom-firmware-kit` → `cfw-kit/` | done, as-is |-| 5a | admission gates 1–3 (`make check-aux`) | done; fails on bundled ldid, as designed |-| 5b | `VPhoneArchive` + `vphone-archive` | library and binary done; **call sites not switched** |-| 5c | `vphone-archive fingerprint` (the plan's tree-fingerprint) | done; already found and drove a hardlink fix |--Tests: `VPhoneCoreTests` 152/152, `VPhoneArchiveTests` 13/13. The 14+| **D1** Python → zero | hard gate, 100%, achieved at **P2.4** | **455 / 6,070 lines (7.5%)** — P0 only |+| **D2** self-contained admission rule | `make check-aux` green | gates 1–3 exist and run; **4 failures**, all `ldid` |+| **D3** drop third-party programs | gtar/bsdtar/unzip/zstd/ldid/… | archive four **replaced but not switched over**; `ldid` still shipped |+| **D4** shell → zero | P3 required, P4 in scope | **0%** — 7,304 lines host-side |++## Phase by phase++| phase | scope | state |+| --- | --- | --- |+| S0 | libzstd static in the xcframework? | ✅ **yes**, proven at runtime |+| S2 | liblzma MT encoder? | ✅ **yes**, 4.84x at 1 GiB |+| — | entitlements off `vphone-cli` onto `vphone-vm` | ✅ verified 0 / 7 / 0 / 0 |+| — | `vphone-letmein` in, `amfidont` scripts out | ✅ docs in 6 languages |+| **P0** | 455 lines of Python | ✅ **complete** — all three gone from the tree |+| P0.5 | `VPhoneArchive` + `vphone-archive` | ✅ library, binary, tests, fingerprint tool |+| P0.5 | switch the archive call sites | ❌ **nothing calls it yet** |+| P0.5 | `VPhoneSign`, drop `ldid` | ❌ not started |+| P0.5 | admission gates 1–3 | ✅ `make check-aux`, fails on `ldid` by design |+| P1.0–1.5 | CFW patchers, **5,098 lines** | ❌ not started |+| P2.0–2.4 | restore, 268 lines + venv removal | ❌ not started |+| P3, P4 | shell | ❌ not started |++Tests: `VPhoneCoreTests` 152/152, `VPhoneArchiveTests` 15/15. The 14`FirmwarePatcherTests` failures are pre-existing — they need`ipsws/patch_refactor_input/`, which is not in the repo.+## What is left, counted++**Python — 5,426 lines in 28 files, plus 189 embedded in shell**++| what | lines | phase |+| --- | ---: | --- |+| `scripts/patchers/*.py` (26 files) | 5,098 | P1 |+| `scripts/pymobiledevice3_bridge.py` | 268 | P2 |+| `tests/test_dropbear_plist.py` | 60 | P1.5 |+| embedded in `fw_prepare.sh`, `cfw_install_{jb,exp}.sh` | 189 | P1.4 / P2.4 |++`tests/test_dropbear_plist.py` is worth knowing about separately: it passes, it+covers live code (`patchers/cfw_daemons.py`), and **no runner invokes it** — no+Makefile target, no CI. The other two files in `tests/` have Makefile targets.+It dies with P1.5 either way, so wiring it up is optional, but right now it is+coverage nobody is collecting.++**The `_resolve_python3()` fallback is untouched in all six scripts**+(`cfw_install{,_dev,_jb,_exp}.sh`, `patch_{camera,hv_vmm}_userland.sh`). Each+ends in `command -v python3`, so deleting the venv makes everything **silently+fall back to system Python**. Plan §1.2.3 calls this D1's main trap, and it is+why D1's acceptance has to run on a PATH with no `python3` at all.++**Shell — 7,304 lines host-side**, of which `cfw_install*.sh` is 2,410 and+`setup_machine.sh` + `fw_prepare.sh` another 1,522.++## Dead code removed (this pass)++- `scripts/fw_manifest.py` (251) and `tools/apfs_snap_rename.py` (108) —+ both had no callers left. `tools/` is gone with it. Recover either from git+ if a comparison is ever needed again: `git show f637f63:tools/apfs_snap_rename.py`.+- `scripts/build.sh` — stopped creating the now-empty `Resources/tools`, and+ the bundled-assets line no longer claims to ship it. The `rm -rf` stays, with+ a note: the bundle is built over whatever is already there, so an older one+ still has the empty directory to clear.+- `cfw-kit/run.sh` — **this one was a live break, not dead code.** Deleting+ `apfs_snap_rename.py` broke `run.sh:156`, which still called it by path. The+ first sweep missed it by only searching `scripts/`, `Makefile` and `sources/`.+ It is now `vphone-cli cfw flip-snapshot`, using the same resolution order as+ `scripts/cfw_install_host.sh`, and `$PY` is gone with its only use. **Any+ future file deletion has to be swept against `cfw-kit/` too.**+- `AGENTS.md` — the tree listed `tools/apfs_snap_rename.py` as "used by+ `cfw_install_host.sh`", which stopped being true before this pass. It also+ had no entry for `VPhoneCore`, `VPhoneArchive`, `FirmwarePatcher`,+ `vphone-archive` or `cfw-kit`, and still said "three host binaries".++Swept and found clean: no unreferenced Swift type in `VPhoneCore`,+`VPhoneArchive` or `vphone-cli`; every repo-relative path literal in shell,+Swift, C and the Makefile resolves; every `requirements.txt` entry is still+imported except `setuptools`, which is a build dependency of `keystone-engine`+and must stay.+## Needs you, and a machineNothing below could be done without root or a real guest.1. **Can `vphone-vm` start a VM holding the entitlements alone?** Everything- in step 1 rests on this, and none of it is proven until a guest boots.+ rests on this, and none of it is proven until a guest boots.2. **`vphone-letmein` end to end** — the sudo prompt, `--hold 10` restoringwhile the guest keeps running, Ctrl-C reaching the guest. The windowdefaults to 10 seconds, which is a guess; measure it.-3. **Location and TouchID**, which depend on TCC attributing the usage- strings to `vphone-vm`. It is `CFBundleExecutable`, so it should — worth- confirming rather than assuming.+3. **Location and TouchID**, which depend on TCC attributing the usage strings+ to `vphone-vm`. It is `CFBundleExecutable`, so it should — worth confirming.4. **Bridged networking**, now validated at boot instead of at config time.5. **`cfw flip-snapshot` against a real `Disk.img`.** The byte comparison- against the Python passed on a synthetic fixture; repeat it once on a real- image, then delete `tools/apfs_snap_rename.py`.+ against the Python passed on a synthetic fixture. This is now the only+ implementation — `cfw-kit/run.sh` and `cfw_install_host.sh` both call it.## Next, in order1. **Switch the archive call sites.** `vphone-archive` is built, bundled andtested, and nothing calls it yet.- The comparison the plan asks for has been run, on the real+ The comparison the plan asks for has been run on the real`cfw_input.tar.zst` and `cfw_jb_input.tar.zst`: everything matches GNU tarexcept **one directory mtime per archive**, where `vphone-archive` restores- the archive's recorded value and GNU tar leaves the extraction time. More- faithful, but still a behaviour change, and it has not been through a boot.-- What is still untested is **ownership restoration**, which only happens as- root — the comparison ran unprivileged, so `ARCHIVE_EXTRACT_OWNER` never- came into play. That is the gap to close before the `$TAR` calls in- `cfw_install*.sh` are switched, since those write to a mounted guest volume- as root and getting ownership wrong there produces a guest that does not- boot. The IPSW unzip in `fw_prepare.sh` and the host-side temp extractions- have neither problem and can go first.-- Re-run it yourself with:- `vphone-archive fingerprint <gtar-output> <vphone-output>`-2. **`VPhoneSign`**, which is what clears the last two admission-gate- failures. `ldid` is the only binary we ship that is already- non-self-contained. The plan's §3.11 has the measurements; the+ the archive's recorded value and GNU tar leaves the extraction time.++ Still untested is **ownership restoration**, which only happens as root, so+ `ARCHIVE_EXTRACT_OWNER` never came into play. Close that before switching+ the `$TAR` calls in `cfw_install*.sh`, which write to a mounted guest volume+ as root — getting ownership wrong there produces a guest that will not boot.+ The IPSW unzip in `fw_prepare.sh` and the host-side temp extractions have+ neither problem and can go first. Re-run with+ `vphone-archive fingerprint <gtar-output> <vphone-output>`.+2. **`VPhoneSign`** — the only thing that clears the four remaining admission+ gate failures, all of them `ldid`. Plan §3.11 has the measurements. The`signcert.p12` needs re-wrapping with a password first, and the oldempty-password copy has to stay for the `--use-ldid` escape hatch.-3. **`vm export` / `import`** onto `VPhoneArchive`, keeping gnutar, `.tzst`- at zstd 3 and `.txz` at xz 9, and checking compatibility both ways.-- This one needs a decision the plan gets wrong for this architecture. §3.9.0-0- says to move export/import from `VPhoneCore` to `VPhoneVM`, which assumed- `vphone-cli` imports the VM kit. It does not, deliberately — so moving them- there would break `vphone-cli vm export`. The right home here is- `VPhoneArchive`: it sits above `VPhoneCore`, and `vphone-cli` can depend on- it without pulling in Virtualization or AppKit.-- It is a real refactor rather than a switch of implementation: about twenty- call sites in `BundleOpsTests` move with the API. The upside is that those- tests already pin the format contract (R11) — round trip, `--max` producing- xz, auto-naming the extension — so whoever does it gets told immediately if- it is wrong. Worth doing in one go rather than in the tail of a session.+3. **`vm export` / `import`** onto `VPhoneArchive`, keeping gnutar, `.tzst` at+ zstd 3 and `.txz` at xz 9, checking compatibility both ways.++ Plan §3.9.0-0 says to move these to `VPhoneVM`, which assumed `vphone-cli`+ imports the VM kit. It does not, deliberately, so that move would break+ `vphone-cli vm export`. The right home is `VPhoneArchive`: above+ `VPhoneCore`, and reachable without Virtualization or AppKit.++ It is a real refactor, about twenty call sites in `BundleOpsTests`. Those+ tests already pin the format contract (R11), so whoever does it gets told+ immediately if it is wrong. Worth doing in one go.4. **Gate 4** — a machine with no Homebrew. Still the only thing that cansupport "it works elsewhere"; gates 1–3 are necessary and not sufficient,which the script says out loud.-## Three things the plan got wrong+## Things the plan got wrongRecorded because they were measured, not reasoned about.@@ -95,6 +151,9 @@ Recorded because they were measured, not reasoned about.- **`sources/vphone.entitlements` has 7 keys**, not the 4 the plan says or the5 `CLAUDE.md` said. Two of them — location and BiometricKit — belong to`Devices/`, which is why they all landed on `vphone-vm`.+- **The Python inventory in §1.2.1 misses a file.** It lists five blocks of+ standalone `.py`; `tests/test_dropbear_plist.py` (60 lines) is not among+ them. The total is 6,070, not 6,010.- **The admission rule caught a bug the plan did not predict**: signing`vphone-vm` first sealed the bundle over its siblings in an earlier state,and `codesign -v` reported "nested code is modified or invalid". The main@@ -102,8 +161,8 @@ Recorded because they were measured, not reasoned about.## And one I nearly got wrong-The first measurement of `--no-overwrite-dir` said libarchive already leaves-an existing directory's mode alone, which would have made the flag-decorative — and it was taken from an extraction that was failing partway and-applying nothing. A measurement from a failing code path measures the failure.-It is 0700 in, 0777 out when extraction actually works, and the flag matters.+The first measurement of `--no-overwrite-dir` said libarchive already leaves an+existing directory's mode alone, which would have made the flag decorative —+and it was taken from an extraction that was failing partway and applying+nothing. A measurement from a failing code path measures the failure. It is+0700 in, 0777 out when extraction actually works, and the flag matters.diff --git a/scripts/build.sh b/scripts/build.shindex 6c3bed35..dd68d03e 100755--- a/scripts/build.sh+++ b/scripts/build.sh@@ -116,8 +116,11 @@ fi# --- Bundle the standalone runtime mini-repo into Contents/Resources ---RES="${BUNDLE}/Contents/Resources"echo "=== Bundling runtime assets → ${RES} ==="+# The bundle is built over whatever is already there, so ${RES}/tools is still+# removed although nothing creates it any more: bundles built before+# `cfw flip-snapshot` replaced apfs_snap_rename.py carry an empty one.rm -rf "${RES}/scripts" "${RES}/tools" "${RES}/.tools" "${RES}/vphoned.signed"-mkdir -p "${RES}/scripts" "${RES}/tools" "${RES}/.tools/bin"+mkdir -p "${RES}/scripts" "${RES}/.tools/bin"# Mirror scripts/ EXCEPT the make-coupled orchestrator, toolchain source, caches.rsync -a \--exclude 'setup_machine.sh' \@@ -126,10 +129,6 @@ rsync -a \--exclude '.git' \--exclude '.build' \scripts/ "${RES}/scripts/"-# tools/ is created but currently empty: apfs_snap_rename.py is no longer-# bundled, because `vphone-cli cfw flip-snapshot` does that work now. The .py-# stays in the repo as a reference until the byte comparison has been repeated-# against a real Disk.img.# 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@@ -144,7 +143,7 @@ cp -f requirements.txt "${RES}/requirements.txt"# = 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/, .tools/bin/{trustcache,insert_dylib}, vphoned.signed, requirements.txt, debs.list, README.md"+echo " bundled: scripts/ (patchers+resources), .tools/bin/{trustcache,insert_dylib}, 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/fw_manifest.py b/scripts/fw_manifest.pydeleted file mode 100755index 3463a4ed..00000000--- a/scripts/fw_manifest.py+++ /dev/null@@ -1,251 +0,0 @@-#!/usr/bin/env python3-"""REFERENCE IMPLEMENTATION -- no longer called by anything.--Superseded 2026-09-23 by `vphone-cli fw manifest`-(sources/FirmwarePatcher/Manifest/FirmwareManifest.swift). Checked against-this file on cloudOS 26.4-23E5207q x iPhone 27.0-24A435: same identity-indices picked, and semantically identical BuildManifest.plist and-Restore.plist.--That is ONE build pair. What would break on another is the identity-*selection* -- which identity counts as research, which as release, which as-the erase identity -- and the only reason to keep this file is to re-run the-comparison when a new pair lands. Do that before deleting it. It is one of-the files D1 counts.--Generate hybrid BuildManifest.plist and Restore.plist for vresearch1 restore.--Merges cloudOS boot-chain (vresearch101ap) with vphone600 runtime components-(device tree, SEP, kernel) and iPhone OS images into a single DFU erase-install-Build Identity.--The VM hardware identifies as vresearch101ap (BDID 0x90) in DFU mode, so the-identity fields must match for TSS/SHSH signing. Runtime components use the-vphone600 variant because its device tree sets MKB dt=1 (keybag-less boot).--Usage:- python3 fw_manifest.py <iphone_dir> <cloudos_dir>-"""--import copy, os, plistlib, sys---# ----------------------------------------------------------------------------# Helpers-# ------------------------------------------------------------------------------def load(path):- with open(path, "rb") as f:- return plistlib.load(f)---def entry(identities, idx, key):- """Deep-copy a single Manifest entry from a build identity."""- return copy.deepcopy(identities[idx]["Manifest"][key])---# ----------------------------------------------------------------------------# Identity discovery-# ------------------------------------------------------------------------------def _is_research(bi):- """Determine whether a build identity is a research variant."""- for comp in ("LLB", "iBSS", "iBEC"):- path = bi.get("Manifest", {}).get(comp, {}).get("Info", {}).get("Path", "")- if not path:- continue- parts = os.path.basename(path).split(".")- if len(parts) == 4:- return "RESEARCH" in parts[2]- variant = bi.get("Info", {}).get("Variant", "")- return "research" in variant.lower()---def find_cloudos(identities, device_class):- """Find release and research identity indices for the given DeviceClass."""- release = research = None- for i, bi in enumerate(identities):- dc = bi.get("Info", {}).get("DeviceClass", "")- if dc != device_class:- continue- if _is_research(bi):- if research is None:- research = i- else:- if release is None:- release = i- if release is None:- raise KeyError(f"No release identity for DeviceClass={device_class}")- if research is None:- raise KeyError(f"No research identity for DeviceClass={device_class}")- return release, research---def find_iphone_erase(identities):- """Return the index of the first iPhone erase identity."""- for i, bi in enumerate(identities):- var = bi.get("Info", {}).get("Variant", "").lower()- if "research" not in var and "upgrade" not in var and "recovery" not in var:- return i- raise KeyError("No erase identity found in iPhone manifest")---# ----------------------------------------------------------------------------# Main-# ------------------------------------------------------------------------------def main():- if len(sys.argv) < 3:- print(f"Usage: {sys.argv[0]} <iphone_dir> <cloudos_dir>", file=sys.stderr)- sys.exit(1)-- iphone_dir, cloudos_dir = sys.argv[1], sys.argv[2]-- cloudos_bm = load(os.path.join(cloudos_dir, "BuildManifest.plist"))- iphone_bm = load(os.path.join(iphone_dir, "BuildManifest.plist"))- cloudos_rp = load(os.path.join(cloudos_dir, "Restore.plist"))- iphone_rp = load(os.path.join(iphone_dir, "Restore.plist"))-- C = cloudos_bm["BuildIdentities"]- I = iphone_bm["BuildIdentities"]-- # ── Discover source identities ───────────────────────────────────- # PROD / RES = vresearch101ap release / research (boot chain)- # VP / VPR = vphone600ap release / research (runtime)- PROD, RES = find_cloudos(C, "vresearch101ap")- VP, VPR = find_cloudos(C, "vphone600ap")- I_ERASE = find_iphone_erase(I)-- print(f" cloudOS vresearch101ap: release=#{PROD}, research=#{RES}")- print(f" cloudOS vphone600ap: release=#{VP}, research=#{VPR}")- print(f" iPhone erase: #{I_ERASE}")-- # ── Build the single DFU erase identity ──────────────────────────- # Identity base from vresearch101ap PROD — must match DFU hardware- # (BDID 0x90) for TSS/SHSH signing.- bi = copy.deepcopy(C[PROD])- bi["Manifest"] = {}- bi["Ap,ProductType"] = "ComputeModule14,2"- bi["Ap,Target"] = "VRESEARCH101AP"- bi["Ap,TargetType"] = "vresearch101"- bi["ApBoardID"] = "0x90"- bi["ApChipID"] = "0xFE01"- bi["ApSecurityDomain"] = "0x01"- for k in ("NeRDEpoch", "RestoreAttestationMode"):- bi.pop(k, None)- bi.get("Info", {}).pop(k, None)- bi["Info"]["FDRSupport"] = False- bi["Info"]["Variant"] = "Darwin Cloud Customer Erase Install (IPSW)"- bi["Info"]["VariantContents"] = {- "BasebandFirmware": "Release",- "DCP": "DarwinProduction",- "DFU": "DarwinProduction",- "Firmware": "DarwinProduction",- "InitiumBaseband": "Production",- "InstalledKernelCache": "Production",- "InstalledSPTM": "Production",- "OS": "Production",- "RestoreKernelCache": "Production",- "RestoreRamDisk": "Production",- "RestoreSEP": "DarwinProduction",- "RestoreSPTM": "Production",- "SEP": "DarwinProduction",- "VinylFirmware": "Release",- }-- m = bi["Manifest"]-- # ── Boot chain (vresearch101 — matches DFU hardware) ─────────────- m["LLB"] = entry(C, PROD, "LLB")- m["iBSS"] = entry(C, PROD, "iBSS")- m["iBEC"] = entry(C, PROD, "iBEC")- m["iBoot"] = entry(C, RES, "iBoot") # research iBoot-- # ── Security monitors (shared across board configs) ──────────────- m["Ap,RestoreSecurePageTableMonitor"] = entry(- C, PROD, "Ap,RestoreSecurePageTableMonitor"- )- m["Ap,RestoreTrustedExecutionMonitor"] = entry(- C, PROD, "Ap,RestoreTrustedExecutionMonitor"- )- m["Ap,SecurePageTableMonitor"] = entry(C, PROD, "Ap,SecurePageTableMonitor")- m["Ap,TrustedExecutionMonitor"] = entry(C, RES, "Ap,TrustedExecutionMonitor")-- # ── Device tree (vphone600ap — sets MKB dt=1 for keybag-less boot)- m["DeviceTree"] = entry(C, VP, "DeviceTree")- m["RestoreDeviceTree"] = entry(C, VP, "RestoreDeviceTree")-- # ── SEP (vphone600 — matches device tree) ────────────────────────- m["SEP"] = entry(C, VP, "SEP")- m["RestoreSEP"] = entry(C, VP, "RestoreSEP")-- # ── Kernel (vphone600, patched by the Swift firmware pipeline) ─────- m["KernelCache"] = entry(C, VPR, "KernelCache") # research- m["RestoreKernelCache"] = entry(C, VP, "RestoreKernelCache") # release-- # ── Recovery mode (vphone600ap carries this entry) ────────────────- m["RecoveryMode"] = entry(C, VP, "RecoveryMode")-- # ── CloudOS erase ramdisk ────────────────────────────────────────- m["RestoreRamDisk"] = entry(C, PROD, "RestoreRamDisk")- m["RestoreTrustCache"] = entry(C, PROD, "RestoreTrustCache")-- # ── iPhone OS image ──────────────────────────────────────────────- m["Ap,SystemVolumeCanonicalMetadata"] = entry(- I, I_ERASE, "Ap,SystemVolumeCanonicalMetadata"- )- m["OS"] = entry(I, I_ERASE, "OS")- m["StaticTrustCache"] = entry(I, I_ERASE, "StaticTrustCache")- m["SystemVolume"] = entry(I, I_ERASE, "SystemVolume")-- # ── Assemble BuildManifest ───────────────────────────────────────- build_manifest = {- "BuildIdentities": [bi],- "ManifestVersion": cloudos_bm["ManifestVersion"],- "ProductBuildVersion": cloudos_bm["ProductBuildVersion"],- "ProductVersion": cloudos_bm["ProductVersion"],- "SupportedProductTypes": ["iPhone99,11"],- }-- # ── Assemble Restore.plist ───────────────────────────────────────- restore = {- "ProductBuildVersion": cloudos_rp["ProductBuildVersion"],- "ProductVersion": cloudos_rp["ProductVersion"],- "DeviceMap": [iphone_rp["DeviceMap"][0]]- + [- d- for d in cloudos_rp["DeviceMap"]- if d["BoardConfig"] in ("vphone600ap", "vresearch101ap")- ],- "SupportedProductTypeIDs": {- cat: (- iphone_rp["SupportedProductTypeIDs"][cat]- + cloudos_rp["SupportedProductTypeIDs"][cat]- )- for cat in ("DFU", "Recovery")- },- "SupportedProductTypes": (- iphone_rp.get("SupportedProductTypes", [])- + cloudos_rp.get("SupportedProductTypes", [])- ),- "SystemRestoreImageFileSystems": copy.deepcopy(- iphone_rp["SystemRestoreImageFileSystems"]- ),- }-- # ── Write output ─────────────────────────────────────────────────- for name, data in [- ("BuildManifest.plist", build_manifest),- ("Restore.plist", restore),- ]:- path = os.path.join(iphone_dir, name)- with open(path, "wb") as f:- plistlib.dump(data, f, sort_keys=True)- print(f" wrote {name}")---if __name__ == "__main__":- main()diff --git a/tools/apfs_snap_rename.py b/tools/apfs_snap_rename.pydeleted file mode 100755index 7bad6390..00000000--- a/tools/apfs_snap_rename.py+++ /dev/null@@ -1,108 +0,0 @@-#!/usr/bin/env python3-# REFERENCE IMPLEMENTATION -- no longer called by anything.-#-# Superseded 2026-09-23 by `vphone-cli cfw flip-snapshot`-# (sources/VPhoneCore/VPhoneAPFSSnapshot.swift). The two were compared on a-# synthetic multi-block fixture and produced byte-identical images and-# character-identical output, including the decoy block that must NOT be-# rewritten.-#-# It is kept only until that comparison has been repeated once against a real-# Disk.img, because the blast radius of getting this wrong is a corrupt guest-# filesystem and having the reference to hand beats reading it out of git.-# Delete it then -- it is one of the files D1 counts.-#-# Offline APFS root-snapshot rename for vphone Disk.img (CFW boot-source flip).-#-# Renames the com.apple.os.update-<hash> system snapshot in place so the-# (seal-enforcement-patched) guest kernel can't find the named root snapshot-# and roots the live volume instead -- the same effect as snaputil in the VM,-# done offline on the host: no mount, no fs_snapshot syscall, no kernel CSR-# gate, no host security change. The name is stored in exactly two b-tree-# records (snap_metadata value + snap_name key), normally in one leaf node;-# a same-length rename keeps name_len and single-snapshot b-tree order intact,-# so only the touched block(s)' fletcher64 change.-#-# Usage: apfs_snap_rename.py <Disk.img> [--dry-run] [--new-prefix PREFIX]-# Auto-detects the com.apple.os.update-* snapshot; only edits records that-# live in a valid APFS object block (checksum verified), so identical-# strings baked into on-volume binaries are never touched.-import mmap-import struct-import sys--BS = 4096-OLD_PREFIX = b"com.apple.os.update-" # 20 bytes-HEXSET = set(b"0123456789abcdefABCDEF")--def cksum(block):- words = struct.unpack('<%dI' % ((BS - 8) // 4), block[8:BS])- s1 = s2 = 0- for w in words:- s1 = (s1 + w) % 0xFFFFFFFF- s2 = (s2 + s1) % 0xFFFFFFFF- c1 = 0xFFFFFFFF - ((s1 + s2) % 0xFFFFFFFF)- c2 = 0xFFFFFFFF - ((s1 + c1) % 0xFFFFFFFF)- return c1 | (c2 << 32)--def main():- args = sys.argv[1:]- dry = "--dry-run" in args- args = [a for a in args if a != "--dry-run"]- new_prefix = b"orig-fs.disabled.rn-"- if "--new-prefix" in args:- i = args.index("--new-prefix")- new_prefix = args[i+1].encode()- del args[i:i+2]- if not args:- sys.exit("usage: apfs_snap_rename.py <Disk.img> [--dry-run] [--new-prefix PREFIX]")- img = args[0]- if len(new_prefix) != len(OLD_PREFIX):- sys.exit("--new-prefix must be exactly %d bytes" % len(OLD_PREFIX))-- with open(img, 'r+b') as f, mmap.mmap(f.fileno(), 0) as mm:- # Auto-detect: every "com.apple.os.update-" followed by 64 hex chars, that- # sits inside a block whose APFS fletcher64 verifies (i.e. a real metadata- # object, not a string constant inside a Mach-O on the volume).- hits = {} # block_off -> list of within-block offsets- i = 0- name = None- while True:- j = mm.find(OLD_PREFIX, i)- if j < 0:- break- i = j + 1- hexpart = mm[j+len(OLD_PREFIX):j+len(OLD_PREFIX)+64]- if len(hexpart) < 64 or any(c not in HEXSET for c in hexpart):- continue # not a snapshot name- blk = (j // BS) * BS- block = bytes(mm[blk:blk+BS])- if cksum(block) != struct.unpack('<Q', block[0:8])[0]:- continue # not a valid APFS object block- if name is None:- name = mm[j:j+len(OLD_PREFIX)+64].decode(errors="replace")- hits.setdefault(blk, []).append(j - blk)-- if not hits:- print("No com.apple.os.update-* root snapshot found. The snapshot may already be renamed.")- return-- total = sum(len(v) for v in hits.values())- print("Detected snapshot: %s" % name)- print("Records: %d in %d block(s): %s" % (total, len(hits), [hex(b) for b in hits]))- if dry:- print("Dry run: the prefix would be renamed to %s." % new_prefix.decode())- return-- for blk, recs in sorted(hits.items()):- block = bytearray(mm[blk:blk+BS])- for within in recs:- assert bytes(block[within:within+len(OLD_PREFIX)]) == OLD_PREFIX- block[within:within+len(new_prefix)] = new_prefix- block[0:8] = struct.pack('<Q', cksum(bytes(block)))- mm[blk:blk+BS] = bytes(block)- print("Block 0x%x: renamed %d record(s) and fixed the checksum." % (blk, len(recs)))- mm.flush()- print("Done. Root snapshot renamed to %s*. The VM will boot the live volume." % new_prefix.decode())--main()