Skip to content

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.md
index 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.md
research/ # 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.sh
index bc8b338d..66ef3200 100755
--- a/cfw-kit/run.sh
+++ b/cfw-kit/run.sh
@@ -84,7 +84,6 @@ else
P="$PROJ/.tools/bin:$PROJ/.venv/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
fi
export 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 @@ cleanup
trap - EXIT
echo "[*] 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.md
index 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 machine
Nothing 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` restoring
while the guest keeps running, Ctrl-C reaching the guest. The window
defaults 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 order
1. **Switch the archive call sites.** `vphone-archive` is built, bundled and
tested, 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 tar
except **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 old
empty-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 can
support "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 wrong
Recorded 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 the
5 `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.sh
index 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.py
deleted file mode 100755
index 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.py
deleted file mode 100755
index 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()