Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

p2: delete the last Python, and the way back to ldid

Lakra779f4e2b94e
diff --git a/.gitignore b/.gitignore
index 5c5f39c9..f83d3e12 100644
--- a/.gitignore
+++ b/.gitignore
@@ -248,11 +248,14 @@ activemq-data/
*.sage.py
# Environments
+#
+# `.venv` and `venv/` are deliberately NOT ignored any more. Nothing in this
+# repo creates a virtualenv — the restore backend is linked into vphone-cli —
+# so a `.venv` on disk is a leftover from before P2.4, and it should show up in
+# `git status` until `make clean` sweeps it rather than sit there invisibly.
.env
.envrc
-.venv
env/
-venv/
ENV/
env.bak/
venv.bak/
diff --git a/AGENTS.md b/AGENTS.md
index 29667bc3..104cf2d8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,10 +9,10 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc
- **Boot (DFU):** `make boot_dfu`
- **All targets:** `make help`
- **AMFI refuses `vphone-vm`?** `make amfi_command` prints the bypass line for this build. The bypass itself is the user's to install and run; see Key Patterns.
-- **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.
+- **Restore:** `vphone-cli restore`, in process. Vendored libirecovery + idevicerestore (`sources/MobileRecoveryCore`, `sources/MobileRestoreCore`) over the `AppleMobileDeviceLibrary` xcframeworks. No interpreter, no environment to provision, no setup step. See `research/p2_restore_off_python.md`.
- **Platform:** macOS 15+ (Sequoia). `vphone-vm` needs amfid to accept its private entitlements: either SIP off with `amfi_get_out_of_my_way=1`, or SIP on (`--without debug`) plus an allowlist bypass the user runs. Both are in README's "SIP/AMFI Relaxation"; neither is installed by this project.
- **Language:** Swift 6.0 (SwiftPM), private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic)
-- **Python deps:** `typer`, `pymobiledevice3`, `ipsw-parser` (see `requirements.txt`) — the restore bridge's, and nothing else's
+- **Dependencies:** seven SwiftPM packages, every one resolved by URL — there is no `vendor/` directory, and `Package.resolved` pins fourteen once transitives are counted. Three git submodules are left: `scripts/resources`, `scripts/repos/trustcache`, `scripts/repos/insert_dylib`. **No Python anywhere.**
## Workflow Rules
@@ -56,7 +56,11 @@ sources/
│ ├── VPhoneCLI.swift # Root command, patch-firmware/patch-component
│ ├── VPhoneFWCLI.swift # Firmware subcommands
│ ├── VPhoneSetupCLI.swift # Setup subcommands
-│ ├── VPhoneRestoreCLI.swift # Restore subcommands
+│ ├── VPhoneRestoreCLI.swift # `restore` + the `cfw` subcommand group
+│ ├── VPhoneCFWPatchCLI.swift # `cfw` verbs: cryptex-paths, inject-*, patch-*
+│ ├── VPhoneCFWMachOVerbsCLI.swift # The six Mach-O `cfw patch-*` verbs
+│ ├── VPhoneCFWDSCVerbsCLI.swift # The eight dyld-shared-cache `cfw patch-*` verbs
+│ ├── VPhoneSignCLI.swift # `sign` — VPhoneSign from the command line
│ ├── VPhoneVMCLI.swift # VM subcommand group
│ ├── VPhoneVMCreateCLI.swift # VM create
│ ├── VPhoneVMLaunchCLI.swift # VM launch
@@ -87,6 +91,32 @@ sources/
│ ├── VPhoneArchivePaths.swift # realpath(3) — NOT the Foundation equivalents
│ └── VPhoneTreeFingerprint.swift # Compare two extracted trees, field by field
│
+├── VPhoneSign/ # Mach-O code signing — replaces ldid, byte for byte
+│ ├── VPhoneSigner.swift # Ad-hoc and PKCS#12 signing
+│ ├── VPhoneCodeSignature.swift # SuperBlob / CodeDirectory construction
+│ ├── VPhoneSignEntitlements.swift # Entitlements plist blob (+ …Reader for reading one back)
+│ ├── VPhoneSignDER.swift # The DER entitlements blob
+│ └── VPhoneSignLdid.swift # The `--use-ldid` escape hatch; last ldid site in Swift
+│
+├── MobileRecoveryCore/ # libirecovery 1.3.1, vendored C. IOKit USB, not libusb
+│ ├── libirecovery.c # Upstream's bytes, unmodified
+│ ├── include/libirecovery.h # Upstream's public header
+│ └── config.h # Ours — what ./configure concludes on macOS
+│
+├── MobileRestoreCore/ # idevicerestore, vendored C, built IDEVICERESTORE_NOMAIN
+│ ├── restore.c asr.c fdr.c img4.c …# Upstream's bytes, unmodified (~19.5k lines)
+│ ├── vphone_restore_bridge.c # Ours — the library entry point upstream's main() was
+│ ├── vphone_zip_stub.c + zip.h # Ours — libzip has no counterpart here; see zip.h's header
+│ ├── config.h # Ours
+│ └── include/vphone_restore_bridge.h # The only header a dependent sees
+│
+├── VPhoneRestore/ # Swift over those two C targets — replaced the Python bridge
+│ ├── VPhoneRecoveryProbe.swift # irecv_open_with_ecid_and_attempts + timeout polling
+│ ├── VPhoneRestoreBridge.swift # The three ported commands: probe, get-shsh, restore
+│ ├── VPhoneRestoreTicket.swift # Undoes idevicerestore's -t: gzipped binary plist → plain
+│ ├── VPhoneRestoreRunner.swift # Drives vphone_restore_run
+│ └── … # options, identity, restore-tree layout, events, errors
+│
├── 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
@@ -145,11 +175,12 @@ sources/
├── VPhoneTouchIDMonitor.swift # BiometricKit delegate sink
└── VPhoneScreenRecorder.swift # VM screen recording to file
-scripts/ # Shell only — the CFW patchers are `vphone-cli cfw <verb>` now
+scripts/ # Shell only — the CFW patchers are `vphone-cli cfw <verb>` now,
+│ # and there is no Python here at all
├── vphoned/ # Guest daemon (ObjC, runs inside iOS VM over vsock)
-├── 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)
+├── check_aux.sh # The self-containment admission gates — `make check-aux`
├── fw_prepare.sh # Download IPSWs, merge cloudOS into iPhone
├── cfw_install.sh # Install CFW (regular)
├── cfw_install_dev.sh # Regular + rpcserver daemon
@@ -158,9 +189,7 @@ scripts/ # Shell only — the CFW patchers are `vphone-
├── cfw_install_host.sh # Host-mount CFW driver (attaches Disk.img, VM off; re-execs sudo)
├── vm_create.sh # Create VM directory
├── setup_machine.sh # Full automation (setup → first boot)
-├── setup_tools.sh # Install deps, build toolchain from submodules, create venv
-├── setup_venv.sh # Create Python venv
-├── setup_venv_linux.sh # Create Python venv (Linux)
+├── setup_tools.sh # Install brew deps, build trustcache + insert_dylib from submodules
└── tail_jb_patch_logs.sh # Tail JB patch log output
cfw-kit/ # Variant-layered CFW installer, vendored as-is
@@ -175,8 +204,9 @@ 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-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.
-- **The AMFI bypass is the user's, not ours.** This project does not ship, install, spawn or supervise one. Relaxing AMFI at boot is the plain route; where that is not wanted, `amfidont` (`xcrun python3 -m pip install --user amfidont`, needs Xcode) allows `vphone-vm` by path or CDHash through LLDB. It is an **allowlist**, scoped to the binaries you name — do not describe it as a global switch. `make amfi_command` prints the line for the current build and prints only; the CDHash changes with every build. No Python dependency enters this repo for it; `scripts/pymobiledevice3_bridge.py` stays the only Python program here.
+- **The AMFI bypass is the user's, not ours.** This project does not ship, install, spawn or supervise one. Relaxing AMFI at boot is the plain route; where that is not wanted, `amfidont` (`xcrun python3 -m pip install --user amfidont`, needs Xcode) allows `vphone-vm` by path or CDHash through LLDB. It is an **allowlist**, scoped to the binaries you name — do not describe it as a global switch. `make amfi_command` prints the line for the current build and prints only; the CDHash changes with every build. It is installed into the user's own Python, not this repository's: nothing here imports it, invokes it or looks for it on `PATH`, and the repository itself contains no Python at all.
- **Guest launches go through `VPhoneGuestLaunchPlanner`** (`VPhoneCore`). It resolves `vphone-vm` as a sibling of the running image — never through `PATH` — and probes once per command with `vphone-vm --help`, looking for SIGKILL. A refusal is reported with the exact command the user has to run; the planner never arranges a bypass itself. Never spawn the guest directly.
+- **Restore runs in `vphone-cli`'s own process.** `VPhoneRestore` calls `vphone_restore_run()` in `MobileRestoreCore`; there is no subprocess, no bridge script and no environment to resolve first. The three commands the old Python bridge exposed became `restore --get-shsh`, `restore` and `restore --offline`; its fourth, `usbmux-list`, had no call site and was not ported. `research/p2_restore_off_python.md` has the decision and the behaviour table.
- **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.
- **Configuration:** `ArgumentParser` → `VPhoneBootCLI` (in `VPhoneCore`, parsed by both binaries) → `VPhoneVirtualMachine.Options` → `VZVirtualMachineConfiguration`.
@@ -212,21 +242,35 @@ 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.
+- Disassembly is Capstone via `ARM64Disassembler` (the `libcapstone-spm` package). 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` (the `libimg4-spm` package), which replaces pyimg4. Both resolve by URL; there is no `vendor/` directory to check out first.
- 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.
+- No interpreter, no Python environment, no native-library repair: `make build` is the whole toolchain.
+
+### Python
+
+There is none, and adding any is a regression.
+
+- No `.py` file is tracked in this repository, no shell script embeds a Python
+ heredoc, and nothing resolves a `python3` at runtime. `git ls-files '*.py'`
+ returns nothing; that is the standing check.
+- There is no environment to activate and no dependency list to install. The
+ restore backend was the last holdout and is now `sources/VPhoneRestore` over
+ two vendored C targets — see `research/p2_restore_off_python.md`.
+- A patch, a probe, a format reader or a device protocol belongs in Swift,
+ where it is built, signed, gated by `make check-aux` and tested with
+ everything else. Adding an interpreter back brings with it a provisioning
+ step, a silent system-`python3` fallback, and a dependency closure
+ `make check-aux` cannot see.
+- `amfidont` is not a counter-example: it is a third-party tool the user
+ installs into their own Python and runs from their own shell. Nothing here
+ imports it, spawns it or looks for it.
### 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. `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.
+- 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, stand keystone up in a throwaway environment **outside this repository** (`brew install keystone`, plus `keystone-engine` in a scratch interpreter somewhere under `/tmp`) and run the one-liner in that test file's header against it. There is no dependency list here to add it to and no environment here to install it into; creating either is the regression the "Python" section above forbids. 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 `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.
diff --git a/Makefile b/Makefile
index be2fc35e..917a523c 100644
--- a/Makefile
+++ b/Makefile
@@ -51,19 +51,18 @@ BUNDLE_VM := $(BUNDLE)/Contents/MacOS/vphone-vm
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
+# There is no interpreter here any more, and no variable naming one. The
+# firmware and CFW patchers are Swift (FirmwarePatcher, reached through
+# `vphone-cli cfw <verb>` and `patch-firmware`), and the restore targets below
+# are `vphone-cli restore`, which carries libirecovery and idevicerestore in
+# the binary. Anything that reintroduces a `python3` on PATH here is a
+# regression — see the "Python" section in AGENTS.md.
TOOLS_PREFIX := .tools
-PMD3_BRIDGE := $(CURDIR)/$(SCRIPTS)/pymobiledevice3_bridge.py
-PYTHON := $(CURDIR)/$(VENV)/bin/python3
SWIFT_SOURCES := $(shell find sources -name '*.swift')
# ─── Environment — prefer project-local binaries ────────────────
-export PATH := $(CURDIR)/$(TOOLS_PREFIX)/bin:$(CURDIR)/$(VENV)/bin:$(CURDIR)/.build/release:$(PATH)
+export PATH := $(CURDIR)/$(TOOLS_PREFIX)/bin:$(CURDIR)/.build/release:$(PATH)
# ─── Default ──────────────────────────────────────────────────────
.PHONY: help
@@ -88,8 +87,7 @@ help:
@echo " Unset or empty keeps the build version that ships in the IPSW."
@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 " make setup_tools Install all tools (brew packages, trustcache, insert_dylib)"
@echo ""
@echo "Build:"
@echo " make build Build + sign vphone-cli"
@@ -152,7 +150,7 @@ help:
@echo ""
@echo "Restore:"
@echo " make restore_get_shsh Dump SHSH response from Apple"
- @echo " make restore Restore to device (pymobiledevice3 backend)"
+ @echo " make restore Restore to device (in-process libirecovery + idevicerestore)"
@echo " make restore_offline Restore offline from the cached .shsh file (decrypts AEA images in place)"
@echo ""
@echo "CFW (host-mount install; VM must be off, re-execs sudo):"
@@ -168,7 +166,7 @@ help:
# Setup
# ═══════════════════════════════════════════════════════════════════
-.PHONY: setup_machine setup_tools setup_venv
+.PHONY: setup_machine setup_tools
setup_machine:
@if count=0; \
@@ -195,22 +193,20 @@ setup_machine:
setup_tools:
VARIANT=$(VARIANT) zsh $(SCRIPTS)/setup_tools.sh
-# The venv alone, without the brew packages and the toolchain builds that
-# setup_tools also does. Documented in AGENTS.md and in setup_venv.sh's own
-# header, both of which named a target that did not exist.
-setup_venv:
- zsh $(SCRIPTS)/setup_venv.sh
-
# ═══════════════════════════════════════════════════════════════════
# Clean — remove generated build/tooling files by default.
# Destructive VM/IPSW cleanup is opt-in and requires confirmation.
+#
+# `.venv` is named literally, and only so an old checkout can be swept: nothing
+# creates one any more, and it is no longer in .gitignore, so a leftover shows
+# up in `git status` until this removes it.
# ═══════════════════════════════════════════════════════════════════
.PHONY: clean
clean:
@set -e; \
echo "=== Cleaning build/tooling artifacts ==="; \
- echo "Removing: .build .swiftpm $(VENV) $(TOOLS_PREFIX)"; \
+ echo "Removing: .build .swiftpm $(TOOLS_PREFIX) (and a leftover .venv, if one is still there)"; \
if [ "$(CLEAN_VM)" = "1" ] || [ "$(CLEAN_IPSW)" = "1" ]; then \
echo ""; \
echo "WARNING: destructive clean requested."; \
@@ -223,7 +219,7 @@ clean:
exit 0; \
esac; \
fi; \
- rm -rf .build .swiftpm "$(VENV)" "$(TOOLS_PREFIX)"; \
+ rm -rf .build .swiftpm "$(TOOLS_PREFIX)" .venv; \
if [ "$(CLEAN_VM)" = "1" ]; then rm -rf "$(VM_DIR)"; fi; \
if [ "$(CLEAN_IPSW)" = "1" ]; then rm -rf ipsws; fi
@@ -550,21 +546,34 @@ define _resolve_ecid
fi
endef
-restore_get_shsh:
+# The restore backend is vphone-cli itself now — libirecovery and
+# idevicerestore, linked in — so these targets need the binary built, the way
+# boot_dfu does. The venv and the Python bridge they used to run are gone from
+# this path entirely.
+#
+# `vphone-cli restore` names a VM the way the CLI does, as a library root plus
+# a bundle name, while make has always taken a directory (VM_DIR=vm, or an
+# absolute path on an external disk). Split VM_DIR_ABS rather than ask anyone
+# to learn a second spelling.
+RESTORE_VM_ARGS = --library-root "$(dir $(VM_DIR_ABS))" "$(notdir $(VM_DIR_ABS))"
+
+restore_get_shsh: build
@$(call _resolve_ecid); \
- cd "$(VM_DIR)" && "$(PYTHON)" "$(PMD3_BRIDGE)" restore-get-shsh \
- --vm-dir . \
+ "$(CURDIR)/$(BINARY)" restore $(RESTORE_VM_ARGS) --get-shsh \
$(if $(RESTORE_UDID),--udid $(RESTORE_UDID),) \
--ecid "$$ECID"
-restore:
+restore: build
@$(call _resolve_ecid); \
- cd "$(VM_DIR)" && "$(PYTHON)" "$(PMD3_BRIDGE)" restore-update \
- --vm-dir . \
+ "$(CURDIR)/$(BINARY)" restore $(RESTORE_VM_ARGS) \
$(if $(RESTORE_UDID),--udid $(RESTORE_UDID),) \
--ecid "$$ECID"
-restore_offline:
+# The `ipsw fw aea` loop below stays: decrypting the AEA images is not part of
+# what moved in-process. `vphone-cli restore --offline` then picks the same
+# first-sorted .shsh this recipe checks for, and its own AEA pass finds nothing
+# left to do after the loop has run.
+restore_offline: build
@$(call _resolve_ecid); \
SHSH=$$(ls "$(VM_DIR_ABS)/"*.shsh 2>/dev/null | head -1); \
if [ -z "$$SHSH" ]; then \
@@ -595,9 +604,7 @@ restore_offline:
fi; \
done; \
echo "[+] Restoring offline with SHSH: $$(basename $$SHSH)"; \
- cd "$(VM_DIR)" && "$(PYTHON)" "$(PMD3_BRIDGE)" restore-update \
- --vm-dir . \
- --tss "$$SHSH" \
+ "$(CURDIR)/$(BINARY)" restore $(RESTORE_VM_ARGS) --offline \
$(if $(RESTORE_UDID),--udid $(RESTORE_UDID),) \
--ecid "$$ECID"
diff --git a/Package.swift b/Package.swift
index b681ee70..252da8d7 100644
--- a/Package.swift
+++ b/Package.swift
@@ -233,6 +233,12 @@ let package = Package(
// undo the split, so don't. VPhoneArchive is fine and is why `vm export`
// still works here: it sits above VPhoneCore and pulls in neither
// Virtualization nor AppKit.
+ //
+ // VPhoneRestore is the line that ends the venv: `restore`, `vm create`
+ // and `make restore*` reach it directly instead of spawning a Python.
+ // It is also what finally puts libirecovery, idevicerestore, libcurl
+ // and libz inside .build/vphone-cli.app, where `make check-aux` gate 1
+ // can see them.
.executableTarget(
name: "vphone-cli",
dependencies: [
@@ -240,6 +246,7 @@ let package = Package(
"FirmwarePatcher",
"VPhoneArchive",
"VPhoneCore",
+ "VPhoneRestore",
],
path: "sources/vphone-cli"
),
diff --git a/README.md b/README.md
index e60d2a3c..f5125a73 100644
--- a/README.md
+++ b/README.md
@@ -18,9 +18,12 @@ 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 libusb ipsw zstd
+brew install aria2 wget gnu-tar openssl@3 ldid-procursus sshpass libusb ipsw zstd
```
+No interpreter and no package environment: everything vphone-cli itself runs is
+Swift or C, built by `make build`.
+
## Install
```bash
@@ -32,7 +35,7 @@ brew install zqxwce/tap/vphone-cli
```bash
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
-./scripts/setup_tools.sh # install deps, build toolchain submodules, create the Python venv
+./scripts/setup_tools.sh # install brew deps, build the toolchain submodules
./scripts/build.sh # build + sign vphone-cli, bundle the .app, cross-compile vphoned
cd .build/vphone-cli.app/Contents/MacOS/
@@ -85,6 +88,11 @@ vphone-cli vm launch myphone # 6. first boot
Update to a newer iOS by pointing `fw prepare` at an IPSW: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`.
+Steps 4 and 5 run in `vphone-cli`'s own process. `restore` drives vendored
+libirecovery and idevicerestore directly — no external restore tool, no setup
+step before the first one works. Add `--offline` to restore from a `.shsh`
+already saved beside the VM instead of asking Apple for a fresh one.
+
## Firmware Variants
Five patch variants with increasing security bypass — pass one to `--variant`:
@@ -116,9 +124,8 @@ Everything vphone-cli creates lives under `~/.vphone/` — kept outside the repo
| `~/.vphone/ipsws/`| Downloaded iPhone + cloudOS IPSWs, cached and reused across VMs. |
| `~/.vphone/tools/`| Cached APFS seal-volume artifacts (`apfs_sealvolume_<version>`) fetched during `fw prepare`. |
| `~/.vphone/debs/` | Cached `.deb` packages the `jb`/`exp` CFW install lays into the guest (Sileo, apt, …). |
-| `~/.vphone/venv/` | Auto-provisioned Python environment (see [Python runtime](#python-runtime); override with `$VPHONE_VENV_DIR`). |
-Precedence: the per-item overrides (`$VPHONE_LIBRARY_ROOT`, `$VPHONE_VENV_DIR`) win over `$VPHONE_ROOT`, which wins over the `~/.vphone` default. The `ipsws/`, `tools/`, and `debs/` caches always sit directly under whichever root is active.
+Precedence: the per-item override `$VPHONE_LIBRARY_ROOT` wins over `$VPHONE_ROOT`, which wins over the `~/.vphone` default. The `ipsws/`, `tools/`, and `debs/` caches always sit directly under whichever root is active.
## SIP/AMFI Relaxation
diff --git a/docs/README_ja.md b/docs/README_ja.md
index 3c649682..00a68384 100644
--- a/docs/README_ja.md
+++ b/docs/README_ja.md
@@ -18,9 +18,11 @@ PCC リサーチ VM インフラストラクチャを使用し、Apple の Virtu
**依存関係:**
```bash
-brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd
+brew install aria2 wget gnu-tar openssl@3 ldid-procursus sshpass libusb ipsw zstd
```
+インタープリタもパッケージ環境も不要です。vphone-cli が実行するものはすべて Swift か C で、`make build` がビルドします。
+
## インストール
```bash
@@ -32,7 +34,7 @@ brew install zqxwce/tap/vphone-cli
```bash
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
-./scripts/setup_tools.sh # 依存関係のインストール、ツールチェーンのサブモジュールのビルド、Python venv の作成
+./scripts/setup_tools.sh # brew 依存関係のインストール、ツールチェーンのサブモジュールのビルド
./scripts/build.sh # vphone-cli のビルド + 署名、.app のバンドル、vphoned のクロスコンパイル
cd .build/vphone-cli.app/Contents/MacOS/
@@ -85,6 +87,11 @@ vphone-cli vm launch myphone # 6. 初回起動
新しい iOS に更新するには、`fw prepare` を IPSW に向けます: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`。
+ステップ 4 と 5 は `vphone-cli` 自身のプロセス内で実行されます。`restore` は同梱の
+libirecovery と idevicerestore を直接駆動します — 外部の復元ツールも、最初の 1 回の前に
+必要なセットアップ手順もありません。`--offline` を付けると、Apple に新しい ticket を
+要求する代わりに、VM の横に保存済みの `.shsh` で復元します。
+
## ファームウェアバリアント
セキュリティバイパスの度合いが段階的に増す 5 つのパッチバリアント — いずれか 1 つを `--variant` に渡します:
@@ -116,9 +123,8 @@ vphone-cli が生成するものはすべて `~/.vphone/` 以下に置かれま
| `~/.vphone/ipsws/`| ダウンロードされた iPhone + cloudOS の IPSW。キャッシュされ、複数の VM で再利用されます。 |
| `~/.vphone/tools/`| `fw prepare` 中に取得された APFS seal-volume アーティファクト(`apfs_sealvolume_<version>`)のキャッシュ。 |
| `~/.vphone/debs/` | `jb`/`exp` の CFW インストールがゲストに配置する `.deb` パッケージのキャッシュ(Sileo、apt など)。 |
-| `~/.vphone/venv/` | 自動的にプロビジョニングされる Python 環境([Python ランタイム](#python-ランタイム) を参照。`$VPHONE_VENV_DIR` で上書き可能)。 |
-優先順位: 項目ごとの上書き(`$VPHONE_LIBRARY_ROOT`、`$VPHONE_VENV_DIR`)が `$VPHONE_ROOT` より優先され、`$VPHONE_ROOT` は `~/.vphone` のデフォルトより優先されます。`ipsws/`、`tools/`、`debs/` キャッシュは、常に現在有効なルートの直下に置かれます。
+優先順位: 項目ごとの上書き `$VPHONE_LIBRARY_ROOT` が `$VPHONE_ROOT` より優先され、`$VPHONE_ROOT` は `~/.vphone` のデフォルトより優先されます。`ipsws/`、`tools/`、`debs/` キャッシュは、常に現在有効なルートの直下に置かれます。
## SIP/AMFI の緩和
diff --git a/docs/README_ko.md b/docs/README_ko.md
index cb2d76c0..3cb91894 100644
--- a/docs/README_ko.md
+++ b/docs/README_ko.md
@@ -18,9 +18,11 @@ PCC 리서치 VM 인프라를 사용하여 Apple의 Virtualization.framework로
**의존성:**
```bash
-brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd
+brew install aria2 wget gnu-tar openssl@3 ldid-procursus sshpass libusb ipsw zstd
```
+인터프리터도, 패키지 환경도 필요하지 않습니다. vphone-cli가 실행하는 모든 것은 Swift 또는 C이며 `make build`가 빌드합니다.
+
## 설치
```bash
@@ -32,7 +34,7 @@ brew install zqxwce/tap/vphone-cli
```bash
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
-./scripts/setup_tools.sh # 의존성 설치, 툴체인 서브모듈 빌드, Python venv 생성
+./scripts/setup_tools.sh # brew 의존성 설치, 툴체인 서브모듈 빌드
./scripts/build.sh # vphone-cli 빌드 및 서명, .app 번들 생성, vphoned 크로스 컴파일
cd .build/vphone-cli.app/Contents/MacOS/
@@ -85,6 +87,11 @@ vphone-cli vm launch myphone # 6. 첫 부팅
최신 iOS로 업데이트하려면 `fw prepare`를 IPSW로 지정하세요: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`.
+4단계와 5단계는 `vphone-cli` 자체 프로세스에서 실행됩니다. `restore`는 내장된
+libirecovery와 idevicerestore를 직접 구동합니다 — 외부 복원 도구도, 첫 실행 전
+준비 단계도 없습니다. `--offline`을 붙이면 Apple에 새 ticket을 요청하는 대신 VM
+옆에 이미 저장된 `.shsh`로 복원합니다.
+
## 펌웨어 변형
보안 우회 수준이 점점 강해지는 5가지 패치 변형이 있습니다 — 하나를 `--variant`에 전달하세요:
@@ -116,9 +123,8 @@ vphone-cli가 생성하는 모든 것은 `~/.vphone/` 아래에 있습니다 —
| `~/.vphone/ipsws/`| 다운로드된 iPhone + cloudOS IPSW, 캐시되어 여러 VM에서 재사용됩니다. |
| `~/.vphone/tools/`| `fw prepare` 중에 가져온 APFS seal-volume 아티팩트(`apfs_sealvolume_<version>`) 캐시. |
| `~/.vphone/debs/` | `jb`/`exp` CFW 설치가 게스트에 넣는 `.deb` 패키지 캐시 (Sileo, apt 등). |
-| `~/.vphone/venv/` | 자동으로 프로비저닝되는 Python 환경 ([Python 런타임](#python-런타임) 참조; `$VPHONE_VENV_DIR`로 재정의). |
-우선순위: 항목별 재정의(`$VPHONE_LIBRARY_ROOT`, `$VPHONE_VENV_DIR`)가 `$VPHONE_ROOT`보다 우선하고, `$VPHONE_ROOT`는 `~/.vphone` 기본값보다 우선합니다. `ipsws/`, `tools/`, `debs/` 캐시는 항상 현재 활성 루트 바로 아래에 위치합니다.
+우선순위: 항목별 재정의 `$VPHONE_LIBRARY_ROOT`가 `$VPHONE_ROOT`보다 우선하고, `$VPHONE_ROOT`는 `~/.vphone` 기본값보다 우선합니다. `ipsws/`, `tools/`, `debs/` 캐시는 항상 현재 활성 루트 바로 아래에 위치합니다.
## SIP/AMFI 완화
diff --git a/docs/README_pt.md b/docs/README_pt.md
index 0cabd8e1..4f981eb1 100644
--- a/docs/README_pt.md
+++ b/docs/README_pt.md
@@ -18,9 +18,11 @@ Inicie um iPhone virtual usando o Virtualization.framework da Apple com a infrae
**Dependências:**
```bash
-brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd
+brew install aria2 wget gnu-tar openssl@3 ldid-procursus sshpass libusb ipsw zstd
```
+Sem interpretador e sem ambiente de pacotes: tudo o que o próprio vphone-cli executa é Swift ou C, compilado por `make build`.
+
## Instalação
```bash
@@ -32,7 +34,7 @@ brew install zqxwce/tap/vphone-cli
```bash
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
-./scripts/setup_tools.sh # instala dependências, compila submodules do toolchain, cria o venv Python
+./scripts/setup_tools.sh # instala dependências do brew, compila submodules do toolchain
./scripts/build.sh # compila + assina vphone-cli, empacota o .app, compila vphoned para iOS
cd .build/vphone-cli.app/Contents/MacOS/
@@ -85,6 +87,12 @@ vphone-cli vm launch meuiphone # 6. primeiro boot
Atualize para um iOS mais novo apontando `fw prepare` para um IPSW: `--iphone-source /caminho/para.ipsw --cloudos-source /caminho/para.ipsw`.
+Os passos 4 e 5 rodam no próprio processo do `vphone-cli`. O `restore` controla
+diretamente as cópias embutidas de libirecovery e idevicerestore — sem ferramenta
+externa de restauração e sem nenhum passo de preparação antes da primeira
+execução. Com `--offline`, a restauração usa um `.shsh` já salvo ao lado da VM em
+vez de pedir um novo à Apple.
+
## Variantes de Firmware
Cinco variantes de patch com bypass de segurança crescente — passe uma para `--variant`:
@@ -116,9 +124,8 @@ Tudo que o vphone-cli cria fica em `~/.vphone/` — fora do repo e do `.app` par
| `~/.vphone/ipsws/`| IPSWs de iPhone + cloudOS baixados, em cache e reutilizados entre VMs. |
| `~/.vphone/tools/`| Artefatos de seal-volume APFS em cache (`apfs_sealvolume_<versão>`) obtidos durante `fw prepare`. |
| `~/.vphone/debs/` | Pacotes `.deb` em cache que o CFW `jb`/`exp` instala no guest (Sileo, apt, …). |
-| `~/.vphone/venv/` | Ambiente Python provisionado automaticamente; substitua com `$VPHONE_VENV_DIR`. |
-Precedência: as substituições por item (`$VPHONE_LIBRARY_ROOT`, `$VPHONE_VENV_DIR`) têm prioridade sobre `$VPHONE_ROOT`, que tem prioridade sobre o padrão `~/.vphone`. Os caches `ipsws/`, `tools/` e `debs/` sempre ficam diretamente sob qualquer raiz ativa.
+Precedência: a substituição por item `$VPHONE_LIBRARY_ROOT` tem prioridade sobre `$VPHONE_ROOT`, que tem prioridade sobre o padrão `~/.vphone`. Os caches `ipsws/`, `tools/` e `debs/` sempre ficam diretamente sob qualquer raiz ativa.
## Relaxamento SIP/AMFI
diff --git a/docs/README_ru.md b/docs/README_ru.md
index 40d58f89..0be724d2 100644
--- a/docs/README_ru.md
+++ b/docs/README_ru.md
@@ -18,9 +18,11 @@
**Зависимости:**
```
-brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd
+brew install aria2 wget gnu-tar openssl@3 ldid-procursus sshpass libusb ipsw zstd
```
+Ни интерпретатора, ни окружения пакетного менеджера: всё, что запускает сам vphone-cli, написано на Swift или C и собирается через `make build`.
+
## Установка
```
@@ -32,7 +34,7 @@ brew install zqxwce/tap/vphone-cli
```
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
-./scripts/setup_tools.sh # установка зависимостей, сборка сабмодулей тулчейна, создание Python venv
+./scripts/setup_tools.sh # установка зависимостей brew, сборка сабмодулей тулчейна
./scripts/build.sh # сборка + подпись vphone-cli, сборка .app, кросс-компиляция vphoned
cd .build/vphone-cli.app/Contents/MacOS/
@@ -85,6 +87,11 @@ vphone-cli vm launch myphone # 6. первая заг
Обновление до более новой iOS: укажите `fw prepare` на IPSW: `--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`.
+Шаги 4 и 5 выполняются в собственном процессе `vphone-cli`. `restore` напрямую
+управляет встроенными libirecovery и idevicerestore — ни внешней утилиты
+восстановления, ни подготовительного шага перед первым запуском. Флаг `--offline`
+восстанавливает из уже сохранённого рядом с ВМ `.shsh` вместо запроса нового у Apple.
+
## Варианты прошивки
Пять вариантов патчей с нарастающим обходом безопасности — передайте один в `--variant`:
@@ -116,10 +123,8 @@ vphone-cli vm launch myphone # 6. первая заг
| −`~/.vphone/ipsws/` | Загруженные IPSW iPhone + cloudOS, кэшируются и переиспользуются между ВМ. |
| −`~/.vphone/tools/` | Кэшированные артефакты APFS seal-volume (`apfs_sealvolume_<version>`), получаемые при `fw prepare`. |
| −`~/.vphone/debs/` | Кэшированные `.deb`-пакеты, которые установка CFW `jb`/`exp` кладёт в гостя (Sileo, apt, …). |
-| −`~/.vphone/venv/` | Автоматически созданное окружение Python (см. Python runtime; переопределяется через `$VPHONE_VENV_DIR`). |
-⚙
-Приоритет: переопределения по элементам (`$VPHONE_LIBRARY_ROOT`, `$VPHONE_VENV_DIR`) имеют больший вес, чем `$VPHONE_ROOT`, который имеет больший вес, чем значение по умолчанию `~/.vphone`. Кэши `ipsws/`, `tools/` и `debs/` всегда располагаются непосредственно под активным корнем.
+Приоритет: переопределение по элементу `$VPHONE_LIBRARY_ROOT` имеет больший вес, чем `$VPHONE_ROOT`, который имеет больший вес, чем значение по умолчанию `~/.vphone`. Кэши `ipsws/`, `tools/` и `debs/` всегда располагаются непосредственно под активным корнем.
## Ослабление SIP/AMFI
diff --git a/docs/README_zh.md b/docs/README_zh.md
index b7e101ba..24b83ff5 100644
--- a/docs/README_zh.md
+++ b/docs/README_zh.md
@@ -18,9 +18,11 @@
**依赖:**
```bash
-brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd
+brew install aria2 wget gnu-tar openssl@3 ldid-procursus sshpass libusb ipsw zstd
```
+不需要解释器,也不需要任何包管理环境:vphone-cli 自身运行的一切都是 Swift 或 C,由 `make build` 构建。
+
## 安装
```bash
@@ -32,7 +34,7 @@ brew install zqxwce/tap/vphone-cli
```bash
git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
-./scripts/setup_tools.sh # 安装依赖、构建工具链子模块、创建 Python venv
+./scripts/setup_tools.sh # 安装 brew 依赖、构建工具链子模块
./scripts/build.sh # 构建并签名 vphone-cli、打包 .app、交叉编译 vphoned
cd .build/vphone-cli.app/Contents/MacOS/
@@ -85,6 +87,10 @@ vphone-cli vm launch myphone # 6. 首次启动
要升级到更新的 iOS,把 `fw prepare` 指向一个 IPSW:`--iphone-source /path/to.ipsw --cloudos-source /path/to.ipsw`。
+第 4、5 步都在 `vphone-cli` 自己的进程里完成。`restore` 直接驱动内置的 libirecovery
+和 idevicerestore——没有外部刷机工具,第一次运行之前也不需要任何准备步骤。加
+`--offline` 可以用虚拟机目录里已保存的 `.shsh` 刷机,而不再向 Apple 申请新的。
+
## 固件变体
五种补丁变体,安全绕过程度递增——将其中之一传给 `--variant`:
@@ -116,9 +122,8 @@ vphone-cli 创建的所有内容都位于 `~/.vphone/` 下——保存在仓库
| `~/.vphone/ipsws/`| 已下载的 iPhone + cloudOS IPSW,缓存后在多个虚拟机间复用。 |
| `~/.vphone/tools/`| `fw prepare` 期间获取的 APFS seal-volume 制品(`apfs_sealvolume_<version>`)缓存。 |
| `~/.vphone/debs/` | `jb`/`exp` CFW 安装写入客户机的 `.deb` 包缓存(Sileo、apt 等)。 |
-| `~/.vphone/venv/` | 自动配置的 Python 环境(见 [Python 运行时](#python-运行时);可用 `$VPHONE_VENV_DIR` 覆盖)。 |
-优先级:单项覆盖(`$VPHONE_LIBRARY_ROOT`、`$VPHONE_VENV_DIR`)优先于 `$VPHONE_ROOT`,`$VPHONE_ROOT` 优先于 `~/.vphone` 默认值。`ipsws/`、`tools/` 和 `debs/` 缓存始终位于当前生效的根目录之下。
+优先级:单项覆盖 `$VPHONE_LIBRARY_ROOT` 优先于 `$VPHONE_ROOT`,`$VPHONE_ROOT` 优先于 `~/.vphone` 默认值。`ipsws/`、`tools/` 和 `debs/` 缓存始终位于当前生效的根目录之下。
## 放宽 SIP/AMFI
diff --git a/requirements.txt b/requirements.txt
deleted file mode 100644
index a66d1cc0..00000000
--- a/requirements.txt
+++ /dev/null
@@ -1,4 +0,0 @@
-typer
-pymobiledevice3>=9.5.0
-ipsw-parser
-setuptools
diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.md
index a934dd76..1589abc1 100644
--- a/research/0_binary_patch_comparison.md
+++ b/research/0_binary_patch_comparison.md
@@ -260,7 +260,7 @@ addresses (49 gates each, zero verdict differences).
convention (`0`). A driver summing these for a preview gets a wrong total.
* `DSCLSDEmbeddedRegPatcher` — record text says `cbz w0, 0x186eea048` where the
captured Python reference says `cbz w0, #0x186eea048`. libcapstone-spm
- (Capstone 6) omits the `#` the venv's Capstone 5.0.7 emits. Bytes are
+ (Capstone 6) omits the `#` the Python patchers' Capstone 5.0.7 emitted. Bytes are
identical; a field-level diff against `reference_patches/` will flag it.
* `DSCHVVMMPatcher.findStringSites(inMachO:)` skips a string section whose
declared extent overruns EOF, where the Python truncates and scans what is
@@ -415,9 +415,14 @@ 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`.
+**P1 dropped `capstone`, `keystone-engine` and `pyimg4` from the dependency
+list; P2 then deleted the list.** `requirements.txt`, `scripts/setup_venv.sh`,
+`scripts/setup_venv_linux.sh`, the `make setup_venv` target and
+`scripts/pymobiledevice3_bridge.py` are all gone — the restore backend was the
+last program holding any of them up, and it is `sources/VPhoneRestore` over
+vendored libirecovery and idevicerestore now
+(`research/p2_restore_off_python.md`). No Python is tracked in this repository
+and nothing resolves a `python3` at runtime.
### Installed Components
diff --git a/research/intg_update_status.md b/research/intg_update_status.md
index 00959be4..b459c4e5 100644
--- a/research/intg_update_status.md
+++ b/research/intg_update_status.md
@@ -2,19 +2,30 @@
> 2026-09-23. Branch off `qof-update-26-fall` @ `6d5ce7d`.
>
-> 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.
+> Plan: `~/Desktop/vphone-cli-migration-plan.md`. Its phases are P0 → P4. This
+> file is the ledger, because `/TODO.md` is not part of this repo's workflow.
+>
+> **Recounted against the tree on 2026-09-23**, after P1 and P2 landed. The
+> previous revision of this file still said P1 was not started and D1 stood at
+> 7.5%; both were stale by several commits. Every number below was measured with
+> a command, and the commands are in "How these were counted" at the end so the
+> next person can disagree with the measurement rather than the prose.
## Where the four delivery lines stand
| line | plan's completion bar | now |
| --- | --- | --- |
-| **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 |
+| **D1** Python → zero | hard gate, 100%, achieved at **P2.4** | **6,070 / 6,070 lines — done.** No `.py` tracked, no heredoc, no runtime `python3` |
+| **D2** self-contained admission rule | `make check-aux` green | gates 1 and 1b **green**; gate 2 has **38 registered** items (**35** once P2's deletions land) and 0 unregistered; gate 4 does not exist |
+| **D3** drop third-party programs | gtar/bsdtar/unzip/zstd/ldid/… | replacements all exist and the `.app` ships **3 binaries and no tools**; the installer shell still resolves `gtar` / `zstd` / `ldid` itself |
+| **D4** shell → zero | P3 required, P4 in scope | **0%**, and it grew: **7,173 lines** in 27 files, from 5,895 in 22 (**7,072 in 25** once P2's deletions land) |
+
+D4 going up is not an accounting artifact. `cfw-kit/` (1,036 lines) and
+`scripts/check_aux.sh` (327) are both new on this branch; everything else nets
+to −85. The 5,098 lines of Python that left `scripts/patchers/` did not take any
+shell with them, because the installers called into that Python and now call
+into `vphone-cli cfw` instead — same scripts, different callee. `cfw_install*.sh`
+is 2,396 lines against 2,410 at the branch base.
## Phase by phase
@@ -24,125 +35,174 @@
| S2 | liblzma MT encoder? | ✅ **yes**, 4.84x at 1 GiB |
| — | entitlements off `vphone-cli` onto `vphone-vm` | ✅ verified 0 / 7 / 0 / 0 |
| — | AMFI bypass moved out of the project | ✅ docs in 6 languages |
-| **P0** | 455 lines of Python | ✅ **complete** — all three gone from the tree |
+| **P0** | 455 lines of Python | ✅ **complete** |
| 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 |
+| P0.5 | switch the archive call sites | ◐ **package side done, shell side not.** `FirmwarePatcher` has no `tar` calls left; `$TAR` in `cfw_install*.sh` and `cfw-kit/lib/common.sh` still finds `gtar` |
+| P0.5 | `VPhoneSign`, drop `ldid` | ◐ **bundle clean.** `--use-ldid` (`VPhoneSignLdid.swift:27`) and the shell's own `ldid` lookups remain |
+| P0.5 | admission gates 1–3 | ✅ `make check-aux`; gate 1 now passes |
+| **P1.0–1.5** | CFW patchers | ✅ **complete** — `scripts/patchers/` deleted at `d90371a`, 26 files / 6,539 lines into 24 `vphone-cli cfw` verbs |
+| **P2.0** | can libirecovery see the virtual DFU endpoint? | ✅ **yes** — `research/p2_dfu_spike.md` |
+| **P2.1–2.2** | vendor libirecovery + idevicerestore | ✅ `sources/MobileRecoveryCore`, `sources/MobileRestoreCore` |
+| **P2.3** | Swift wrapper + call-site replacement | ◐ **built and unit-tested; 4 of the 7 behaviour rows still need a device** |
+| **P2.4** | Python → zero | ✅ **complete** — see D1 above |
| P3, P4 | shell | ❌ not started |
-That AMFI row went round in a circle in one day, so it is worth stating where
+`research/p2_restore_off_python.md` records what P2 decided and why, including
+the behaviour table row by row.
+
+That AMFI row went round in a circle in one day, so it is worth restating where
it landed. The `amfidont` scripts came out and `vphone-letmein` went in; then
`vphone-letmein` was measured killing amfid outright on a host where
-`vm.cs_system_enforcement` reads 1, and came out again. The project now ships
-**no** bypass at all: `vphone-cli` probes with `vphone-vm --help`, and on a
-refusal prints what to run. `amfidont` is what it names, installed by the user
-with `xcrun python3 -m pip install --user amfidont`. This costs D1 nothing —
-it is not a dependency of this repo, nothing here imports or invokes it, and
-`scripts/pymobiledevice3_bridge.py` remains the only Python program in the
-tree. `research/host_binary_split.md` has the measurement and the reasoning.
-
-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.
+`vm.cs_system_enforcement` reads 1, and came out again. The project ships **no**
+bypass: `vphone-cli` probes with `vphone-vm --help`, and on a refusal prints what
+to run. `amfidont` is what it names, installed by the user into their own Python.
+This costs D1 nothing — it is not a dependency of this repo, and nothing here
+imports or invokes it. `research/host_binary_split.md` has the measurement.
-## What is left, counted
+## D1, counted
-**Python — 5,426 lines in 28 files, plus 189 embedded in shell**
+The plan's corrected inventory (§1.2.1 plus the file it missed) is **6,070
+lines**: 5,881 standalone across 31 `.py` files at the branch base, plus 189
+embedded in shell heredocs. All of it is gone.
-| what | lines | phase |
+| what | lines at `6d5ce7d` | where it went |
| --- | ---: | --- |
-| `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.
+| `scripts/patchers/` (26 files) | 5,098 | 24 `vphone-cli cfw` verbs (P1) |
+| `scripts/pymobiledevice3_bridge.py` | 268 | `sources/VPhoneRestore` + two C targets (P2) |
+| `scripts/fw_manifest.py` | 237 | no callers — deleted |
+| `scripts/vm_manifest.py` | 123 | `VPhoneVirtualMachineManifest.swift` |
+| `tools/apfs_snap_rename.py` | 95 | `vphone-cli cfw flip-snapshot` |
+| `tests/test_dropbear_plist.py` | 60 | died with `cfw_daemons.py` |
+| embedded in `fw_prepare.sh` (169) and `cfw_install_{jb,exp}.sh` (20) | 189 | Swift; `fw_prepare.sh` lost 117 lines doing it |
+
+Two corrections to the earlier ledger's arithmetic:
+
+- **`scripts/patchers/` was 5,098 lines at the branch base but 6,539 when it was
+ deleted**, still in 26 files. The set churned while the port ran —
+ `cfw_patch_hv_vmm_rootfs.py` left, `cfw_records.py` arrived, and
+ `cfw_patch_watchdogd.py` roughly doubled. The plan's 5,098 is the right
+ denominator for D1 because that is what D1 was scoped against; 6,539 is the
+ right number for "how much Python actually had to be ported".
+- **The anti-fallback trap is closed.** `_resolve_python3()` is gone from all six
+ scripts — the plan's §1.2.3 warning was that deleting the environment would
+ make every one of them silently fall back to the system `python3`, and that
+ cannot happen now because there is no call site left to fall back.
+
+## D2, counted
+
+`zsh scripts/check_aux.sh --fast`:
+
+- **Gate 1 (dependency closure)** and **gate 1b (relocation)** both report
+ nothing. This is the change since the last revision of this file, which
+ recorded four failures, all `ldid`: `VPhoneSign` replaced it and the bundle
+ stopped shipping it. The `.app` is now exactly `vphone-cli`, `vphone-vm`,
+ `vphone-archive`, `signcert.p12` and `AppIcon.icns` — no tools directory, no
+ scripts, no interpreter.
+- **Gate 2 (source scan)**: 38 registered items, 0 unregistered violations.
+ Three of the 38 are Python — the hardcoded `python3` in
+ `VPhoneResources.swift` and `setup_machine.sh`'s `python3` / `python3.13`
+ lookups — and go out with P2's deletions, leaving 35: 6 `ipsw` and 1 `ldid`
+ hardcoded in Swift, and 28 `PATH` lookups in shell (`ldid`, `gtar`, `zstd`,
+ `ipsw`, `aea`, `aria2c`, `xcrun`, `shasum`, `sha256sum`, `curl`, `wget`,
+ `lsof`).
+- **Gate 3** was skipped here (`--fast`). CI must not skip it.
+- **Gate 4 — a machine with no Homebrew — still does not exist**, and is still
+ the only thing that can support "it works elsewhere". The script says so
+ itself. Gates 1–3 are necessary and not sufficient.
+
+`ipsw` and `aea` are deliberately out of scope this round and are not counted
+against D3.
+
+## D4, counted
+
+**7,173 lines of tracked `.sh` in 27 files** across `scripts/` and `cfw-kit/`,
+against 5,895 in 22 files at `6d5ce7d`. The largest single files:
+
+| file | lines |
+| --- | ---: |
+| `scripts/cfw_install_exp.sh` | 821 |
+| `scripts/setup_machine.sh` | 805 |
+| `scripts/fw_prepare.sh` | 589 |
+| `scripts/cfw_install.sh` | 579 |
+| `scripts/cfw_install_dev.sh` | 512 |
+| `scripts/cfw_install_jb.sh` | 484 |
+| `scripts/check_aux.sh` | 327 |
+| `scripts/vphone_jb_setup.sh` | 312 |
+| `cfw-kit/` (5 files) | 1,036 |
+
+P2's deletions take `setup_venv.sh` (49) and `setup_venv_linux.sh` (52) plus the
+provisioning blocks inside `setup_tools.sh` and `setup_machine.sh`. Of what is
+left, `vphone_jb_setup.sh` (312) runs **inside the guest**, not on the host, so
+the host-side figure P3/P4 are actually aimed at is 6,760 — a little less once
+those provisioning blocks go.
+
+## Tests
+
+Five test targets, by declaration count: `FirmwarePatcherTests` 341,
+`VPhoneCoreTests` 168, `VPhoneRestoreTests` 67, `VPhoneArchiveTests` 39,
+`VPhoneSignTests` 32. These are `@Test` / `func test…` declarations, not expanded
+parameterized cases, and they are **not** a pass count — the suite was not run in
+this pass because another stage held the build directory.
+
+The 14 `FirmwarePatcherTests` failures previously recorded are pre-existing and
+unrelated: they need `ipsws/patch_refactor_input/`, which is not in the repo.
+
+`VPhoneRestoreTests` covers everything that runs without a device attached —
+argument parsing, the restore-tree rules, the `.shsh` naming, and the C struct
+the options turn into. What needs a phone in DFU is not covered, and the target's
+stanza in `Package.swift` says so rather than shipping a test that only looks
+like one.
## Needs you, and a machine
-Nothing below could be done without root or a real guest.
+Nothing below can be done without root or a real guest.
1. ~~**Can `vphone-vm` start a VM holding the entitlements alone?**~~
**Answered: yes.** A guest booted and libirecovery enumerated its virtual
- DFU endpoint — `research/p2_dfu_spike.md`. Everything rested on this.
+ DFU endpoint — `research/p2_dfu_spike.md`.
2. ~~**`vphone-letmein` end to end.**~~ **Answered, and the answer removed the
- tool.** It works only where the kernel does not enforce code signing; with
- `vm.cs_system_enforcement` = 1 the patched `__TEXT` page gets amfid killed
- (`CODESIGNING`, "Invalid Page") and the guest dies with it. Measured twice
- on macOS 27.0 (26A428) arm64e. What still needs a machine is the
- **replacement instruction path**: that the `amfidont` command `vphone-cli`
- prints on a refusal is correct as printed on a host with nothing installed
- yet.
-3. **Location and TouchID**, which depend on TCC attributing the usage strings
+ tool.** With `vm.cs_system_enforcement` = 1 the patched `__TEXT` page gets
+ amfid killed (`CODESIGNING`, "Invalid Page") and the guest dies with it.
+ Measured twice on macOS 27.0 (26A428) arm64e. What still needs a machine is
+ the **replacement instruction path**: that the `amfidont` command
+ `vphone-cli` prints on a refusal is correct as printed, on a host with
+ nothing installed yet.
+3. **The four unverified rows of the P2 behaviour table** — a real restore
+ (online and `--offline`), `--no-erase` update-in-place, and the exit-code
+ contract on failure. Table and criteria in
+ `research/p2_restore_off_python.md`. **Run these on a disposable VM**: a
+ failed restore leaves the guest in recovery.
+4. **FDR equivalence.** The old bridge ran `Restore(..., ignore_fdr=False)`;
+ idevicerestore's FDR handling is internal. Device enumeration cannot settle
+ it, so `research/p2_dfu_spike.md` explicitly did not. It shows up only during
+ an actual restore, and it must not be assumed away.
+5. **Ownership restoration in `VPhoneArchive`**, which only happens as root, so
+ `ARCHIVE_EXTRACT_OWNER` has never come into play. This is the blocker on
+ 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.
+6. **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
+7. **Bridged networking**, now validated at boot instead of at config time.
+8. **`cfw flip-snapshot` against a real `Disk.img`.** The byte comparison
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.
+1. **Run the four device rows of the P2 table.** Everything else in P2 is
+ built and unit-tested; these are what stands between "compiles" and
+ "restores". Row 3, `--offline`, is the one the plan's first draft missed
+ entirely and the one with four separate criteria.
+2. **Finish the archive switch-over.** The host-side temp extractions and the
+ IPSW unzip in `fw_prepare.sh` have no ownership problem and can go first.
+ The `$TAR` calls in `cfw_install*.sh` wait on item 5 above. Re-run
+ `vphone-archive fingerprint <gtar-output> <vphone-output>` after each.
- The comparison the plan asks for has been run on the real
+ The comparison the plan asks for has already 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.
-
- 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, checking compatibility both ways.
@@ -154,9 +214,12 @@ Nothing below could be done without root or a real guest.
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.
+4. **P3 — the four `cfw_install*.sh` into one `CFWInstaller`.** This is D4's
+ main battle and the only thing that moves that line off 0%. Note that the
+ `cfw-kit/` layer added on this branch is 1,036 lines that P3 also has to
+ account for; the plan's §P3 was written against a tree where it did not
+ exist.
+5. **Gate 4** — a machine with no Homebrew.
## Things the plan got wrong
@@ -171,10 +234,19 @@ Recorded because they were measured, not reasoned about.
- **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.
+- **P2 did not need the 73k-line vendoring the plan implies.** §P2.1 reads as
+ though the whole libimobiledevice stack had to be carried in tree.
+ `AppleMobileDeviceLibrary` ships all five of those libraries plus OpenSSL as
+ prebuilt xcframeworks, so only libirecovery (4,629 lines) and idevicerestore
+ (20,918, of which 1,399 are ours) are vendored. The argument is in
+ `research/p2_restore_off_python.md`.
- **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
executable is signed last now, and both build paths verify the seal.
+- **D4 was never going to fall out of D1.** The plan treats the Python removal
+ as the hard part and the shell as cleanup. Porting 6,539 lines of Python
+ changed the shell's line count by −14.
## And one I nearly got wrong
@@ -183,3 +255,26 @@ 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.
+
+## How these were counted
+
+Re-run these rather than trusting the tables:
+
+```zsh
+git ls-files '*.py' # D1: must print nothing
+grep -rn '_resolve_python3' scripts/ sources/ Makefile # must print nothing
+grep -rn '<<.*PY' scripts/ # heredocs: must print nothing
+grep -rn 'python' scripts/*.sh # comments only, no call sites
+
+zsh scripts/check_aux.sh --fast # D2: gates 1, 1b, 2
+find .build/vphone-cli.app -type f # D2: what the bundle ships
+
+git ls-files scripts cfw-kit | grep '\.sh$' | xargs wc -l # D4
+
+# The denominators, from the branch base:
+git ls-tree -r --name-only 6d5ce7d | grep '\.py$' \
+ | while read f; do git show "6d5ce7d:$f" | wc -l; done | awk '{s+=$1} END {print s, NR}'
+# The patchers as they stood when deleted:
+git ls-tree -r --name-only 'd90371a^' -- scripts/patchers | grep '\.py$' \
+ | while read f; do git show "d90371a^:$f" | wc -l; done | awk '{s+=$1} END {print s, NR}'
+```
diff --git a/research/kernel_jb_patch_notes.md b/research/kernel_jb_patch_notes.md
index 051f07bd..82da2f9c 100644
--- a/research/kernel_jb_patch_notes.md
+++ b/research/kernel_jb_patch_notes.md
@@ -2,6 +2,15 @@
Last updated: 2026-03-07
+> **Historical.** These notes describe `scripts/patchers/kernel_jb.py`, which was
+> deleted with the rest of `scripts/patchers/` at commit `d90371a`. The findings
+> — what each patch targets, why a matcher overfit, which sites are the
+> XNU-backed ones — carried into the Swift port and are why this file is kept;
+> the commands are not runnable as written. There is no Python in this
+> repository and no environment to install any into. The port lives in
+> `sources/FirmwarePatcher/Kernel/JBPatches/`; to run anything below, recover
+> the patchers from git history at `78cbeea`.
+
## Overview
`scripts/patchers/kernel_jb.py` has 24 patch methods in `find_all()`. Current status:
@@ -411,7 +420,10 @@ Should have moderate caller count (hundreds).
## Environment Notes
-### Running on macOS (current)
+> Both recipes below are records of how this was run on 2026-03-07, not
+> instructions. The Python environment they assume does not exist any more.
+
+### Running on macOS (as it was then)
```bash
cd /Users/qaq/Documents/GitHub/vphone-cli
diff --git a/research/kernel_patch_jb/patch_vm_map_protect.md b/research/kernel_patch_jb/patch_vm_map_protect.md
index c551f533..2733b41f 100644
--- a/research/kernel_patch_jb/patch_vm_map_protect.md
+++ b/research/kernel_patch_jb/patch_vm_map_protect.md
@@ -56,7 +56,7 @@
- Release kernel used: extracted raw Mach-O `/tmp/vphone-kcache-release-26.1.raw`.
- Release outcome: `hit` at `0x00B8424C`.
- Release emitted patch: `b #0x28 [_vm_map_protect]`.
-- Method: focused `KernelJBPatcher.patch_vm_map_protect()` dry-runs in the project `.venv`.
+- Method: focused `KernelJBPatcher.patch_vm_map_protect()` dry-runs, in the Python environment this repository had on that date. Both the Python patcher and that environment are gone; the port is `sources/FirmwarePatcher/Kernel/JBPatches/`.
- Result: the reworked matcher hits the same semantic gate on both PCC 26.1 research and PCC 26.1 release, and the research hit **matches upstream exactly**.
## Why This Should Generalize Beyond The Current Research Image
diff --git a/research/p2_dfu_spike.md b/research/p2_dfu_spike.md
index 46dd43be..aeb7867f 100644
--- a/research/p2_dfu_spike.md
+++ b/research/p2_dfu_spike.md
@@ -5,12 +5,19 @@
> Plan section P2.0 marks this the largest unknown in P2 and says to stop and
> re-evaluate if it fails, rather than vendoring idevicerestore on an assumption.
+> **Since answered and acted on.** The migration this spike unblocked is done:
+> the restore path is `sources/VPhoneRestore` over vendored libirecovery and
+> idevicerestore, and `scripts/pymobiledevice3_bridge.py` no longer exists.
+> Everything below is written as of the day of the spike, when it still did.
+> `research/p2_restore_off_python.md` has what P2 went on to do.
+
## Why it was a real question
-The restore path today goes through pymobiledevice3's `IRecv`, which is **pyusb**.
-libirecovery on macOS goes through **IOKit USB**. Different transport, so whether
-one works tells you nothing about the other, and the whole of P2.1/P2.2 is wasted
-work if the IOKit path cannot see a Virtualization.framework virtual endpoint.
+The restore path at the time went through pymobiledevice3's `IRecv`, which is
+**pyusb**. libirecovery on macOS goes through **IOKit USB**. Different transport,
+so whether one works tells you nothing about the other, and the whole of
+P2.1/P2.2 is wasted work if the IOKit path cannot see a Virtualization.framework
+virtual endpoint.
## Result
@@ -101,8 +108,9 @@ negative result is distinguishable from a broken harness.
## Still open, and deliberately not answered here
Plan section P2.2 asks that **FDR equivalence** be confirmed as part of this spike.
-It was not, and cannot be from device enumeration alone: pymobiledevice3 runs
+It was not, and cannot be from device enumeration alone: pymobiledevice3 ran
`Restore(..., ignore_fdr=False)`, and idevicerestore's FDR handling is internal.
Whether the two behave the same only shows up during an actual restore. That stays
an open risk on P2.2 and must not be assumed away — it is called out here so the
-next person does not read "P2.0 passed" as covering it.
+next person does not read "P2.0 passed" as covering it. It is still open;
+`research/p2_restore_off_python.md` carries it forward.
diff --git a/research/p2_restore_off_python.md b/research/p2_restore_off_python.md
new file mode 100644
index 00000000..4a8a62ee
--- /dev/null
+++ b/research/p2_restore_off_python.md
@@ -0,0 +1,234 @@
+# P2 — taking restore off Python
+
+> 2026-09-23, branch `vphone-intg-update`. Plan sections P2.0 → P2.4.
+>
+> `scripts/pymobiledevice3_bridge.py` was the last Python program in this
+> repository. It is gone, and with it `requirements.txt`, `scripts/setup_venv.sh`,
+> `scripts/setup_venv_linux.sh`, the `make setup_venv` target and the
+> provisioning blocks in `setup_tools.sh` and `setup_machine.sh`. D1 — zero
+> Python — is met.
+>
+> What replaced it: `sources/VPhoneRestore` (1,040 lines of Swift) over two
+> vendored C targets, `MobileRecoveryCore` (libirecovery) and
+> `MobileRestoreCore` (idevicerestore), with everything else arriving as
+> prebuilt xcframeworks.
+
+## The decision: a package, not a vendoring
+
+The plan's §P2.1 reads as though the whole libimobiledevice stack had to be
+carried in tree. Measured against the upstream tarballs, that is what it would
+have cost:
+
+| upstream | `.c` + `.h` lines |
+| --- | ---: |
+| libimobiledevice 1.4.0 | 48,484 |
+| libplist 2.7.0 | 13,390 |
+| libimobiledevice-glue 1.3.2 | 6,204 |
+| libusbmuxd 2.1.1 | 3,045 |
+| libtatsu 1.0.5 | 2,070 |
+| **total** | **73,193** |
+
+None of that is code this project would ever read or change. Carrying it would
+have meant five more hand-written `config.h` files standing in for
+`./configure`, OpenSSL on top, and every upstream security fix arriving as a
+manual merge into a tree nobody here is qualified to review. Linking Homebrew's
+copies instead was never available: `make check-aux` gate 1 fails on any
+absolute path in the dependency closure, and `/opt/homebrew/lib/libimobiledevice-1.0.dylib`
+is exactly that.
+
+`Lakr233/AppleMobileDeviceLibrary` already ships all five of those, plus
+OpenSSL, as prebuilt static xcframeworks, and it was already a dependency of
+this package. A plain SwiftPM C target depending on the `AppleMobileDeviceLibrary`
+product can `#include <plist/plist.h>`, `<libimobiledevice/libimobiledevice.h>`,
+`<libimobiledevice/restore.h>`, `<libimobiledevice-glue/collection.h>`,
+`<usbmuxd.h>`, `<libtatsu/tss.h>` and `<openssl/ssl.h>` and link them — so the
+73,193 lines are a `.package(url:)` line and nothing else in the tree.
+
+## What still had to be vendored, and why
+
+Two things are not in that package, and both are load-bearing.
+
+### `sources/MobileRecoveryCore` — libirecovery 1.3.1
+
+4,629 lines. It talks to iBoot and iBSS over USB, which is the half of a restore
+`idevicerestore` does not get from libimobiledevice. Upstream ships it as an
+autotools project, so the only file here that is not upstream's own bytes is
+`config.h`, which says what `./configure` concludes on macOS.
+
+**The backend is IOKit, not libusb.** On a host whose SDK has
+`IOKit/usb/IOUSBLib.h`, upstream's `configure.ac` picks IOKit and never looks
+for libusb; that is deliberate here too, because a libusb backend would put a
+Homebrew dylib in the link and gate 1 rejects it. It is also what
+`research/p2_dfu_spike.md` proved works — see below.
+
+### `sources/MobileRestoreCore` — idevicerestore
+
+20,918 lines, of which **1,399 are ours** and each of those files says so at the
+top:
+
+| file | lines | what it is |
+| --- | ---: | --- |
+| `vphone_restore_bridge.c` | 703 | the library entry point upstream's `main()` was |
+| `vphone_zip_stub.c` | 260 | libzip's twenty-two entry points, each failing loudly |
+| `include/vphone_restore_bridge.h` | 166 | the target's only public header |
+| `zip.h` | 143 | libzip's signatures, so upstream's `.c` compiles unchanged |
+| `config.h` | 127 | what `./configure` would have written |
+
+Upstream is a program, not a library. It is compiled here with
+`IDEVICERESTORE_NOMAIN`, so its `argv` parsing, usage text and signal handling
+are excluded, and `vphone_restore_run()` builds the same client object from a
+struct instead of from a command line. One restore per process:
+idevicerestore keeps its mode, log level and quit flag in process globals, so a
+second concurrent call is refused with `VPHONE_RESTORE_E_BUSY` rather than
+allowed to fight the first over them.
+
+**The libzip stub is the one real amputation.** libzip is the single
+`PKG_CHECK_MODULES` dependency in `configure.ac` with no counterpart here, and
+linking Homebrew's copy fails gate 1. Exactly two things are lost, and `zip.h`'s
+header carries the full argument:
+
+1. Reading an IPSW straight out of the `.ipsw` zip. `src/ipsw.c` chooses once in
+ `ipsw_open()` between a stdio path for a directory and a libzip path for a
+ file. This project always hands idevicerestore an already-extracted
+ `iPhone*_Restore` directory, and `vphone_restore_run()` refuses anything else
+ before idevicerestore sees it — so the zip arm is unreachable by
+ construction. `RestoreRunnerTests.aFileIsNotARestoreDirectory` pins that: a
+ `.ipsw` is rejected by name rather than failing four layers down.
+2. Baseband firmware signing. `restore_sign_bbfw()` stitches signature blobs
+ into a `.bbfw`'s members. A virtual iPhone has no baseband, so the restore
+ never reaches it. On real hardware with one it would, and it would fail
+ loudly instead of flashing something unsigned — which is the right failure.
+
+Both end at `zip_open()` returning NULL after logging what happened and why,
+which upstream already handles as an ordinary error. Nothing in the stub returns
+a plausible-looking success.
+
+### What the two targets link
+
+`IOKit` and `CoreFoundation` for libirecovery; `/usr/lib/libcurl.4.dylib` for
+the TSS request and the firmware download, and `/usr/lib/libz.1.dylib` for the
+gzipped `.shsh` and the compressed BuildManifest members. All four are on
+`check_aux.sh`'s system whitelist, which is why gate 1 stays green with the
+restore backend in the bundle.
+
+## The Swift layer
+
+`sources/VPhoneRestore` is what actually replaces the bridge script. The Python
+had four commands; three are ported with the same arguments, the same errors and
+the same two lines of output that scripts and people have been grepping for
+(`[+] SHSH saved: …`, `[+] Using cached SHSH: …`).
+
+| Python command | now | note |
+| --- | --- | --- |
+| `recovery-probe` | `VPhoneRecoveryProbe.probe` | `irecv_open_with_ecid_and_attempts` + timeout polling |
+| `restore-get-shsh` | `VPhoneRestoreBridge.fetchSHSH` | erase ticket, as Python's did |
+| `restore-update` | `VPhoneRestoreBridge.restore` | `erase` defaults true; `ticketPath` for `--offline` |
+| `usbmux-list` | **not ported** | no call site anywhere in this repository |
+
+Two things the Swift has to undo, because idevicerestore and the Python bridge
+did not agree on either:
+
+- **`-t/--shsh` writes a gzipped binary plist**; the `.shsh` this project has
+ always written beside a VM is a plain one. `VPhoneRestoreTicket` reads all
+ three shapes that now exist in the wild — idevicerestore's gzipped binary
+ plist, the plain XML the Python wrote, and a bare binary plist — and writes
+ the bytes out as-is rather than re-serializing, so an XML file stays XML.
+- **`-t/--shsh` names the file after the device's decimal ECID** and skips the
+ write entirely when a file of that name is already present
+ (`"SHSH '%s' already present."`). `fetchSHSH` therefore points it at a fresh
+ temporary cache directory per call, so "the `.shsh` idevicerestore just wrote"
+ is unambiguous and a stale blob from a previous firmware can never be the one
+ copied out.
+
+## The P2.3 behaviour table
+
+The plan's seven rows, each with what it is checked by today. **`unit`** means
+`tests/VPhoneRestoreTests` covers it with no device attached; **`device`** means
+it is not checked and needs a phone or VM in DFU.
+
+| # | scenario | before | after | criterion | state |
+| --: | --- | --- | --- | --- | --- |
+| 1 | `restore` (online, default) | `pmd3 restore-update` | `erase=true, ticket_path=NULL` | VM boots | **device** (options mapping is `unit`: `RestoreOptionsTests.defaultsAreAnOnlineEraseRestore`) |
+| 2 | `restore --get-shsh` | `pmd3 restore-get-shsh` | `shsh_only=true` | `.shsh` semantically equal to the Python's, same filename | **split.** Filename and plist handling are `unit` (`RestoreLayoutTests.shshIsNamedAfterTheECIDInSixteenHexDigits`, the whole of `RestoreTicketTests`); the TSS round trip is **device** |
+| 3 | `restore --offline` | AEA decrypt in place → `--tss <first .shsh>` | AEA decrypt in place → `ticket_path=<same file>` | ① `noSHSH` with no blob ② `noRestoreDir` with no tree ③ multiple `.shsh` → sorted first ④ VM boots | ①②③ **unit** (`RestoreLayoutTests`, `RestoreRunnerTests.fetchingASHSHStopsAtTheMissingRestoreTree`); ④ **device** |
+| 4 | `restore --no-erase` | `Behavior.Update` | `erase=false` | user data survives | **device** (mapping is `unit`: `RestoreOptionsTests.updateInPlaceClearsErase`) |
+| 5 | metadata on success | writes `restore-info.json` | same | contents identical | **device.** `VPhoneRestoreInfo.derive` is host-side and unchanged, but "only on success" needs a run |
+| 6 | failure | no `restore-info.json`, exit code passed through | same | exit codes match | **device.** The bridge's own rejections are `unit` (`RestoreRunnerTests`); a failure from inside idevicerestore is not |
+| 7 | verbosity | `-v` → one, `-vv`/`-vvv` → two `-v` | `debug_level` | logs comparably detailed | **device.** The level enum matches upstream's one for one and that is `unit` (`RestoreEventTests.levelsMatchIdevicerestoresEnum`) |
+
+Four rows need a device: 1, 4, 5, 6, and the tail halves of 2, 3 and 7.
+**Run them on a disposable VM** — a failed restore leaves the guest sitting in
+recovery.
+
+The unit suite was **not executed during this documentation pass** (another
+stage held the build directory). Whoever lands P2 should run
+`swift test --filter VPhoneRestoreTests` and record the result here rather than
+inheriting the claim.
+
+### `research/p2_dfu_spike.md` already settled the riskiest question
+
+P2.0 asked whether libirecovery's IOKit path can see a Virtualization.framework
+virtual DFU endpoint at all — pymobiledevice3 reached it through pyusb, so one
+working said nothing about the other, and the plan says to stop and re-evaluate
+rather than vendor idevicerestore on an assumption. The answer is yes:
+`irecv_open_with_ecid_and_attempts` succeeded against a VM booted `--dfu` from a
+bare bundle, `irecv_get_device_info` returned a fully populated struct, and the
+ECID matched what `vphone-vm` derived from `machineIdentifier` — two independent
+code paths agreeing on `206C763772858301`. AP and SEP nonces were present and
+correctly sized, so personalization has what it needs.
+
+## Deliberate divergences from the Python
+
+Recorded because a behaviour comparison that only lists matches is not a
+comparison.
+
+- **Two restore trees in one bundle is now an error.** Python's
+ `find_restore_dir` globbed `iPhone*_Restore` and took whichever sorted first;
+ `VPhoneRestoreLayout.findRestoreDirectory` throws
+ `multipleRestoreDirectories` naming both. Restoring from whichever build
+ happened to sort first flashes a build nobody chose. The single-tree and
+ no-tree cases are unchanged, including that a symlink to a directory still
+ counts (`fileExists(atPath:isDirectory:)`, matching Python's `p.is_dir()`;
+ `URLResourceValues.isDirectory` would answer for the link and was wrong).
+- **`ticket_path` is not upstream's `-T/--ticket`.** The plan's P2.2 says to map
+ it there. `-T` takes a bare `ApImg4Ticket`; this takes the **whole TSS
+ response**, which is what `shsh_only` writes and what pymobiledevice3's
+ `fetch_tss_record()` dumped. A full response carries a signature per
+ component and a bare ticket does not, so personalizing with a bare one
+ produces components the device rejects.
+- **A `.ipsw` handed to `restore_dir` is rejected by name.** Upstream would have
+ opened it through libzip; this build has no libzip, so the check moved to the
+ front where the error is legible.
+
+## Still open
+
+**FDR equivalence.** The Python ran `Restore(..., ignore_fdr=False)`;
+idevicerestore's FDR handling is internal. `research/p2_dfu_spike.md` says
+explicitly that this could not be settled from device enumeration and was not,
+and it stays an open risk on P2.2. It shows up only during an actual restore.
+Do not read "P2.0 passed" as covering it.
+
+## The dependency graph P2 left behind
+
+Moving the restore backend into the package is what finally emptied `vendor/`.
+
+- **`vendor/` is gone.** Every one of the seven dependencies resolves by URL;
+ `Package.resolved` pins fourteen once transitives are counted.
+- **Submodules went from 9 to 3**: `scripts/resources`,
+ `scripts/repos/trustcache`, `scripts/repos/insert_dylib`. The other six were
+ SwiftPM checkouts this repository pinned by commit, which meant a
+ `git submodule update` before any build and a tree that could sit at an
+ unreleased commit — MachOKit was four commits past 0.46.1, Dynamic two past
+ 1.2.0.
+- **MachOKit 0.46.1+4 → 0.52.2** and **swift-argument-parser 1.7.0+6 → 1.8.2**
+ came with that move, with **zero source changes needed**.
+- **`libcapstone-spm` is pinned `branch: "main"`, not `from:`** — a known wart.
+ Its `CoreCapstone` target carries `.unsafeFlags(["-Wno-shorten-64-to-32"])`,
+ and SwiftPM refuses unsafe flags in a dependency resolved by version while
+ allowing them in one resolved by branch. A branch pin means `swift build`
+ can pick up an upstream commit nobody here reviewed; `Package.resolved`
+ records what was actually built, which limits the damage but does not remove
+ it. **The fix is upstream**: drop the flag from `CoreCapstone` — the warning
+ it suppresses is Capstone's own and can be silenced in the source or simply
+ tolerated — cut a release, and change this line to `from:` like the other
+ six.
diff --git a/research/patch_reference_capture.md b/research/patch_reference_capture.md
index a415a459..969df785 100644
--- a/research/patch_reference_capture.md
+++ b/research/patch_reference_capture.md
@@ -5,7 +5,10 @@
> 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`.
+> To run any of it, recover `scripts/patchers/` from git history at `78cbeea`
+> **and stand up a Python environment outside this repository** — there is no
+> Python here any more and nothing left to activate, so the `.venv/bin/python3`
+> invocations below are transcripts, not instructions.
> The parity evidence itself is no longer re-derived at test time: it is frozen
> into the `FrozenReference` / `*Golden` enums in `tests/FirmwarePatcherTests/`.
diff --git a/scripts/build.sh b/scripts/build.sh
index 11fc0ed4..945dcd7e 100755
--- a/scripts/build.sh
+++ b/scripts/build.sh
@@ -122,10 +122,13 @@ 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"
+# The bundle is built over whatever is already there, so ${RES}/tools and
+# ${RES}/requirements.txt are still removed although nothing creates either any
+# more: bundles built before `cfw flip-snapshot` replaced the snapshot-rename
+# script carry an empty tools/, and bundles built before the restore backend
+# moved in-process carry a pip requirements list the app would never read.
+rm -rf "${RES}/scripts" "${RES}/tools" "${RES}/.tools" "${RES}/vphoned.signed" \
+ "${RES}/requirements.txt"
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
@@ -147,23 +150,19 @@ rsync -a \
# 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.
+# out to it was the CFW patcher script that has since been deleted.
+# 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 .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. 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/ (resources), .tools/bin/trustcache, vphoned.signed, requirements.txt, debs.list, README.md"
+echo " bundled: scripts/ (resources), .tools/bin/trustcache, vphoned.signed, 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/check_aux.sh b/scripts/check_aux.sh
index 925576eb..c8e759f9 100755
--- a/scripts/check_aux.sh
+++ b/scripts/check_aux.sh
@@ -53,7 +53,6 @@ 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 # -> 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)
@@ -64,6 +63,13 @@ typeset -a REGISTERED_REMAINING=(
sshpass # JB environment only, frozen
)
+# python3 was on that list until P2.4 and must never go back on it. The restore
+# backend was its last consumer and is now libirecovery + idevicerestore linked
+# into vphone-cli, so an interpreter lookup anywhere in this repo is not a debt
+# to pay down — it is a regression, and gate 2 below now FAILS on one instead of
+# reporting it. `is_registered` still folds python3.13 and friends onto
+# `python3`, so a versioned lookup fails under the name people will search for.
+#
# The AMFI bypass is deliberately NOT on that list and must never be added to
# it. Whatever program lets amfid accept vphone-vm's entitlements — amfidont or
# anything else — is the user's, run by hand from their own shell. Nothing here
@@ -85,7 +91,9 @@ typeset -a SYSTEM_WHITELIST=(
is_registered() {
local needle="$1"
- # python3.13, python3.14 and friends are all the same dependency.
+ # python3.13, python3.14 and friends are all the same dependency — and since
+ # P2.4 that dependency is registered nowhere, so this fold exists to make a
+ # versioned lookup fail as plain `python3`.
[[ "$needle" == python3* ]] && needle=python3
for r in $REGISTERED_REMAINING; do [[ "$r" == "$needle" ]] && return 0; done
return 1
@@ -170,9 +178,12 @@ check_closure() {
# ---------------------------------------------------------------------------
# Gate 2 — source scan
# ---------------------------------------------------------------------------
-# otool describes link time. These are the runtime lookups it cannot see: the
-# `command -v python3` fallbacks, and a `tar --zstd` that quietly spawns a
-# zstd(1) from PATH. Both are real in this repo and neither shows up in gate 1.
+# otool describes link time. These are the runtime lookups it cannot see: a
+# `command -v python3` fallback, and a `tar --zstd` that quietly spawns a
+# zstd(1) from PATH. The second is still real in this repo; the first is the
+# one that made D1 look finished when it was not — several helpers ended their
+# python resolution with `command -v python3`, so pulling the venv out left
+# them quietly running the system interpreter. Neither shows up in gate 1.
check_sources() {
local hits="" line="" prog=""
@@ -203,9 +214,13 @@ check_sources() {
# command position -- line start, or after | ; && || ( $( ! if -- and dropping
# comment lines is the difference between a gate people read and one they
# learn to ignore. `which is enough for...` in a comment is not a PATH lookup.
+ #
+ # tests/ is scanned too. It was not until P2.4, and that is exactly how a
+ # `python3 - <<'PY'` heredoc in tests/test_jb_kernel_patches.sh outlived the
+ # venv it was never part of: nothing looked there.
hits=$(grep -rnE '^[^#]*(^|[;&|(]|\$\(|`|! |if )[[:space:]]*(command -v|which)[[:space:]]+[A-Za-z0-9_.-]+' \
- --include='*.sh' scripts/ cfw-kit/ 2>/dev/null \
- | grep -vE '^scripts/(build|check_aux|setup_venv|setup_venv_linux|setup_tools)\.sh' \
+ --include='*.sh' scripts/ cfw-kit/ tests/ 2>/dev/null \
+ | grep -vE '^scripts/(build|check_aux|setup_tools)\.sh' \
| grep -v 'vphone_jb_setup.sh')
if [[ -n "$hits" ]]; then
while IFS= read -r line; do
@@ -218,6 +233,34 @@ check_sources() {
fi
done <<< "$hits"
fi
+
+ # No interpreter, anywhere. This is D1's completion gate, and it deliberately
+ # does not look for a pattern: it fails on the word `python` wherever this
+ # project's own shell can execute it. Looking for `command -v python3` is
+ # what would have missed the two `python3 - <<'PY'` heredocs that sat in
+ # tests/ long after the venv they were never part of.
+ #
+ # Two things are not interpreter use here. Comment lines: the repo explains
+ # what the Python used to do in a lot of places, and that history is worth
+ # keeping. And `echo`/`print` lines: `make amfi_command` prints the command
+ # that installs amfidont, which is the USER's tool, in the USER's own python,
+ # run from the USER's own shell — nothing here installs or spawns it.
+ #
+ # check_aux.sh excludes itself, because a scanner that looks for a word
+ # necessarily contains it.
+ hits=$( { grep -rnE 'python[0-9.]*' --include='*.sh' scripts/ cfw-kit/ tests/ 2>/dev/null
+ grep -HnE 'python[0-9.]*' Makefile 2>/dev/null } \
+ | grep -vE '^[^:]+:[0-9]+:[[:space:]]*#' \
+ | grep -vE '^scripts/check_aux\.sh:' \
+ | grep -vE '(echo|print)[[:space:]]' )
+ if [[ -n "$hits" ]]; then
+ while IFS= read -r line; do
+ [[ -z "$line" ]] && continue
+ fail "gate 2: interpreter reference — $line"
+ done <<< "$hits"
+ else
+ green " ok gate 2: no python reachable from any script, Makefile or test"
+ fi
}
# ---------------------------------------------------------------------------
diff --git a/scripts/pymobiledevice3_bridge.py b/scripts/pymobiledevice3_bridge.py
deleted file mode 100755
index 7a4b5a8b..00000000
--- a/scripts/pymobiledevice3_bridge.py
+++ /dev/null
@@ -1,268 +0,0 @@
-import asyncio
-import inspect
-import plistlib
-import sys
-import time
-from collections.abc import Awaitable
-from pathlib import Path
-from typing import Optional
-
-from ipsw_parser.ipsw import IPSW
-from pymobiledevice3 import usbmux
-from pymobiledevice3.exceptions import (
- ConnectionFailedError,
- ConnectionFailedToUsbmuxdError,
- IRecvNoDeviceConnectedError,
- IncorrectModeError,
- PairingError,
-)
-from pymobiledevice3.irecv import IRecv
-from pymobiledevice3.lockdown import create_using_usbmux
-from pymobiledevice3.restore.device import Device
-from pymobiledevice3.restore.recovery import Behavior, Recovery
-from pymobiledevice3.restore.restore import Restore
-import typer
-
-
-# pymobiledevice3's own CLI installs coloredlogs at INFO (see its __main__) and
-# silences these chatty third-party loggers. Mirror that here so the bridge's
-# restore output is the same colorized log stream when run with -v.
-_NOISY_LOGGERS = (
- "quic",
- "asyncio",
- "parso.cache",
- "parso.cache.pickle",
- "parso.python.diff",
- "humanfriendly.prompts",
- "blib2to3.pgen2.driver",
- "urllib3.connectionpool",
-)
-
-
-def install_logging(verbose: int) -> None:
- import logging
-
- level = [logging.WARNING, logging.INFO, logging.DEBUG][min(verbose, 2)]
- try:
- import coloredlogs
-
- coloredlogs.install(level=level)
- except ImportError:
- logging.basicConfig(level=level)
- for name in _NOISY_LOGGERS:
- logging.getLogger(name).disabled = True
-
-
-def parse_ecid(value: Optional[str]) -> Optional[int]:
- if not value:
- return None
- raw = value.strip().lower()
- if raw.startswith("0x"):
- raw = raw[2:]
- if not raw:
- raise ValueError("ECID is empty")
- if any(c not in "0123456789abcdef" for c in raw):
- raise ValueError(f"Invalid ECID: {value}")
- return int(raw, 16)
-
-
-def normalize_udid(value: Optional[str]) -> Optional[str]:
- return None if value is None else value.strip().upper()
-
-
-def find_restore_dir(vm_dir: Path) -> Path:
- candidates = sorted(p for p in vm_dir.glob("iPhone*_Restore") if p.is_dir())
- if not candidates:
- raise FileNotFoundError(f"No iPhone*_Restore directory found in {vm_dir}")
- if len(candidates) > 1:
- raise RuntimeError(
- "Multiple iPhone*_Restore directories found; keep only one active restore tree"
- )
- return candidates[0]
-
-
-async def resolve_device(ecid: Optional[int], udid: Optional[str]) -> Device:
- udid_normalized = normalize_udid(udid)
-
- try:
- devices = [d for d in await usbmux.list_devices() if d.connection_type == "USB"]
- except ConnectionFailedToUsbmuxdError:
- devices = []
-
- for usb_device in devices:
- serial = normalize_udid(getattr(usb_device, "serial", None))
- if udid_normalized and serial != udid_normalized:
- continue
-
- try:
- lockdown = await create_using_usbmux(serial=usb_device.serial, connection_type="USB")
- except (ConnectionFailedError, IncorrectModeError, PairingError):
- continue
-
- lockdown_ecid = int(str(lockdown.ecid), 0)
- if ecid is not None and lockdown_ecid != ecid:
- continue
-
- return Device(lockdown=lockdown)
-
- if ecid is None and udid_normalized is not None:
- raise RuntimeError(
- "The device with that UDID was not found, and no ECID is set; "
- "set RESTORE_ECID to target the device in DFU or Recovery mode"
- )
-
- return Device(irecv=IRecv(ecid=ecid))
-
-
-async def cmd_usbmux_list(usb_only: bool) -> None:
- devices = await usbmux.list_devices()
- for device in devices:
- if usb_only and getattr(device, "connection_type", None) != "USB":
- continue
- serial = getattr(device, "serial", None)
- if serial:
- print(serial)
-
-
-def wait_for_irecv(ecid: Optional[int], timeout: int, is_recovery: Optional[bool] = None) -> IRecv:
- deadline = time.monotonic() + timeout
- while time.monotonic() < deadline:
- try:
- return IRecv(ecid=ecid, timeout=2, is_recovery=is_recovery)
- except (IRecvNoDeviceConnectedError, ValueError):
- time.sleep(1)
- mode_label = "recovery" if is_recovery else "dfu/recovery"
- raise TimeoutError(f"Timed out waiting for {mode_label} endpoint")
-
-
-
-def derive_shsh_output(vm_dir: Path, ecid: Optional[int]) -> Path:
- tag = f"{ecid:016X}" if ecid is not None else "auto"
- return vm_dir / f"{tag}.shsh"
-
-
-async def cmd_restore_get_shsh(
- vm_dir: Path, ecid: Optional[int], udid: Optional[str], out: Optional[Path]
-) -> None:
- restore_dir = find_restore_dir(vm_dir)
- ipsw = IPSW.create_from_path(str(restore_dir))
- device = await resolve_device(ecid, udid)
- tss = await Recovery(ipsw, device, behavior=Behavior.Erase).fetch_tss_record()
-
- out_path = out or derive_shsh_output(vm_dir, device.get_ecid_value())
- with out_path.open("wb") as handle:
- plistlib.dump(tss, handle)
-
- print(f"[+] SHSH saved: {out_path}")
-
-
-async def cmd_restore_update(
- vm_dir: Path,
- ecid: Optional[int],
- udid: Optional[str],
- erase: bool,
- tss_path: Optional[Path] = None,
-) -> None:
- restore_dir = find_restore_dir(vm_dir)
- ipsw = IPSW.create_from_path(str(restore_dir))
- behavior = Behavior.Erase if erase else Behavior.Update
- device = await resolve_device(ecid, udid)
- tss = None
- if tss_path is not None:
- with tss_path.open("rb") as handle:
- tss = plistlib.load(handle)
- print(f"[+] Using cached SHSH: {tss_path}")
- await Restore(ipsw, device, tss=tss, behavior=behavior, ignore_fdr=False).update()
-
-
-def require_ecid(value: str) -> Optional[int]:
- try:
- return parse_ecid(value)
- except ValueError as exc:
- raise typer.BadParameter(str(exc)) from exc
-
-
-app = typer.Typer(help="pymobiledevice3 bridge for vphone", pretty_exceptions_enable=False)
-
-
[email protected]("usbmux-list", help="List usbmux UDIDs")
-def usbmux_list_command(
- usb_only: bool = typer.Option(
- True,
- "--usb-only/--no-usb-only",
- help="Include network devices with --no-usb-only.",
- ),
-) -> Awaitable[None]:
- return cmd_usbmux_list(usb_only=usb_only)
-
-
[email protected]("recovery-probe", help="Probe for DFU/recovery endpoint")
-def recovery_probe_command(
- ecid: Optional[str] = typer.Option(None, help="Hex ECID (with/without 0x)"),
- timeout: int = typer.Option(2, help="Probe timeout in seconds"),
-) -> None:
- parsed_ecid = require_ecid(ecid)
- wait_for_irecv(parsed_ecid, timeout=timeout)
-
-
[email protected]("restore-get-shsh", help="Fetch SHSH from prepared restore dir")
-def restore_get_shsh_command(
- vm_dir: Path = typer.Option(
- Path("."),
- help="VM directory",
- exists=False,
- file_okay=False,
- dir_okay=True,
- ),
- ecid: Optional[str] = typer.Option(None, help="Hex ECID (with/without 0x)"),
- udid: Optional[str] = typer.Option(None, help="Target USB UDID"),
- out: Optional[Path] = typer.Option(
- None,
- help="Output SHSH path",
- exists=False,
- file_okay=True,
- dir_okay=False,
- ),
- verbose: int = typer.Option(
- 0, "--verbose", "-v", count=True, help="Increase log verbosity (-v info, -vv debug)."
- ),
-) -> Awaitable[None]:
- install_logging(verbose)
- return cmd_restore_get_shsh(vm_dir, require_ecid(ecid), udid, out)
-
-
[email protected]("restore-update", help="Run erase/update restore from prepared dir")
-def restore_update_command(
- vm_dir: Path = typer.Option(
- Path("."),
- help="VM directory",
- exists=False,
- file_okay=False,
- dir_okay=True,
- ),
- ecid: Optional[str] = typer.Option(None, help="Hex ECID (with/without 0x)"),
- udid: Optional[str] = typer.Option(None, help="Target USB UDID"),
- erase: bool = typer.Option(True, "--erase/--no-erase", help="Run update-in-place with --no-erase."),
- tss: Optional[Path] = typer.Option(
- None,
- help="Cached SHSH plist for offline restore (skips Apple TSS request).",
- exists=False,
- file_okay=True,
- dir_okay=False,
- ),
- verbose: int = typer.Option(
- 0, "--verbose", "-v", count=True, help="Increase log verbosity (-v info, -vv debug)."
- ),
-) -> Awaitable[None]:
- install_logging(verbose)
- return cmd_restore_update(vm_dir, require_ecid(ecid), udid, erase=erase, tss_path=tss)
-
-
-async def main(argv: list[str]) -> None:
- result = app(args=argv, prog_name="pymobiledevice3_bridge.py", standalone_mode=False)
- if inspect.isawaitable(result):
- await result
-
-
-if __name__ == "__main__":
- asyncio.run(main(sys.argv[1:]))
diff --git a/scripts/setup_machine.sh b/scripts/setup_machine.sh
index 3929f00e..5952f410 100755
--- a/scripts/setup_machine.sh
+++ b/scripts/setup_machine.sh
@@ -38,7 +38,9 @@ BOOT_ANALYSIS_TIMEOUT="${BOOT_ANALYSIS_TIMEOUT:-300}"
BOOT_PROMPT_FALLBACK_TIMEOUT="${BOOT_PROMPT_FALLBACK_TIMEOUT:-60}"
BOOT_BASH_PROMPT_REGEX="${BOOT_BASH_PROMPT_REGEX:-bash-[0-9]+(\.[0-9]+)+#|:/[^ ]* root#}"
BOOT_PANIC_REGEX="${BOOT_PANIC_REGEX:-(^|[^p])(panic|kernel panic|panic\\.apple\\.com|stackshot succeeded)}"
-PMD3_BRIDGE="${PMD3_BRIDGE:-${PROJECT_ROOT}/scripts/pymobiledevice3_bridge.py}"
+# The restore backend, built by `make build` a few steps before it is needed.
+# It replaces the pymobiledevice3 bridge script and the interpreter that ran it.
+VPHONE_CLI="${VPHONE_CLI:-${PROJECT_ROOT}/.build/release/vphone-cli}"
NON_INTERACTIVE=1
JB_MODE=0
DEV_MODE=0
@@ -56,22 +58,6 @@ require_cmd() {
command -v "$cmd" >/dev/null 2>&1 || die "Missing required command: $cmd"
}
-find_python_for_pmd3() {
- local candidate
- for candidate in \
- "${PROJECT_ROOT}/.venv/bin/python3" \
- "$(command -v python3 2>/dev/null || true)"
- do
- [[ -n "$candidate" ]] || continue
- [[ -x "$candidate" ]] || continue
- if "$candidate" -c "import pymobiledevice3" >/dev/null 2>&1; then
- echo "$candidate"
- return 0
- fi
- done
- return 1
-}
-
normalize_ecid() {
local ecid="$1"
ecid="${ecid#0x}"
@@ -472,9 +458,11 @@ check_platform() {
install_brew_deps() {
require_cmd brew
+ # No python formula: the restore backend is linked into vphone-cli and the
+ # patchers are Swift, so this flow needs no interpreter at any point.
local deps=(
wget gnu-tar openssl@3 ldid-procursus sshpass git-lfs
- [email protected] libusb ipsw
+ libusb ipsw
)
echo "=== Installing Homebrew dependencies ==="
@@ -489,16 +477,6 @@ install_brew_deps() {
echo ""
}
-ensure_python_linked() {
- if ! command -v python3.13 >/dev/null 2>&1; then
- local pybin
- pybin="$(brew --prefix [email protected])/bin"
- export PATH="$pybin:$PATH"
- fi
-
- require_cmd python3.13
-}
-
run_make() {
local label="$1"
shift
@@ -588,15 +566,12 @@ wait_for_post_restore_reboot() {
}
wait_for_recovery() {
- local pmd3_python
- pmd3_python="$(find_python_for_pmd3 || true)"
- [[ -x "$pmd3_python" ]] || die "pymobiledevice3 python runtime not found (run: make setup_tools)"
- [[ -f "$PMD3_BRIDGE" ]] || die "Missing bridge script: $PMD3_BRIDGE"
+ [[ -x "$VPHONE_CLI" ]] || die "Missing vphone-cli: $VPHONE_CLI (run: make build)"
echo "[*] Waiting for recovery/DFU endpoint..."
local i
for i in {1..90}; do
- if "$pmd3_python" "$PMD3_BRIDGE" recovery-probe --ecid "0x${DEVICE_ECID}" --timeout 2 >/dev/null 2>&1; then
+ if "$VPHONE_CLI" recovery-probe --ecid "0x${DEVICE_ECID}" --timeout 2 >/dev/null 2>&1; then
echo "[+] Device endpoint is reachable"
return
fi
@@ -711,16 +686,11 @@ main() {
else
check_platform
install_brew_deps
- ensure_python_linked
run_make "Project setup" setup_tools
run_make "Project setup" build
fi
- # 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
if [[ "$LESS_MODE" -eq 0 ]]; then
run_make "Firmware prep" fw_prepare
diff --git a/scripts/setup_tools.sh b/scripts/setup_tools.sh
index 142d9c42..1e4ce6cc 100755
--- a/scripts/setup_tools.sh
+++ b/scripts/setup_tools.sh
@@ -1,9 +1,11 @@
#!/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 (a test reference — see step [3/4]), and creates the
-# Python venv for the pymobiledevice3 restore bridge.
+# Installs brew packages, builds trustcache from source, and builds insert_dylib
+# from submodule source (a test reference — see step [3/3]).
+#
+# There is no interpreter step: the restore backend is linked into vphone-cli
+# and the patchers are Swift, so nothing this script installs is an environment.
#
# Run: make setup_tools
@@ -25,13 +27,13 @@ ensure_repo_submodule() {
# ── Brew packages ──────────────────────────────────────────────
-echo "[1/4] Checking brew packages..."
+echo "[1/3] Checking brew packages..."
-# 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.
+# No python here, and cmake and keystone are deliberately absent too: all three
+# 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(), the libcapstone-spm package 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=()
@@ -50,7 +52,7 @@ fi
# ── Trustcache ─────────────────────────────────────────────────
-echo "[2/4] trustcache"
+echo "[2/3] trustcache"
TRUSTCACHE_BIN="$TOOLS_PREFIX/bin/trustcache"
if [[ -x "$TRUSTCACHE_BIN" ]]; then
@@ -86,7 +88,7 @@ fi
# 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)"
+echo "[3/3] insert_dylib (byte-parity reference for CFWMachOTests)"
INSERT_DYLIB_BIN="$TOOLS_PREFIX/bin/insert_dylib"
if [[ -x "$INSERT_DYLIB_BIN" ]]; then
@@ -100,10 +102,5 @@ else
echo " Installed: $INSERT_DYLIB_BIN"
fi
-# ── Python venv ────────────────────────────────────────────────
-
-echo "[4/4] Python venv"
-zsh "$SCRIPT_DIR/setup_venv.sh"
-
echo ""
echo "All tools installed."
diff --git a/scripts/setup_venv.sh b/scripts/setup_venv.sh
deleted file mode 100755
index a5b381f2..00000000
--- a/scripts/setup_venv.sh
+++ /dev/null
@@ -1,49 +0,0 @@
-#!/bin/zsh
-# setup_venv.sh — Create a self-contained Python venv at project root.
-#
-# Creates the venv for scripts/pymobiledevice3_bridge.py, the restore backend.
-# Requires: python3.
-#
-# Usage:
-# make setup_venv
-#
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-VENV_DIR="${PROJECT_ROOT}/.venv"
-REQUIREMENTS="${PROJECT_ROOT}/requirements.txt"
-
-# Use system Python3
-PYTHON="$(readlink -f "$(which python3)")"
-if [[ -z "${PYTHON}" ]]; then
- echo "Error: python3 not found in PATH"
- exit 1
-fi
-
-echo "=== Creating venv ==="
-echo " Python: ${PYTHON} ($(${PYTHON} --version 2>&1))"
-echo " venv: ${VENV_DIR}"
-echo " deps: ${REQUIREMENTS}"
-echo ""
-
-# Create venv from system Python
-"${PYTHON}" -m venv "${VENV_DIR}"
-
-# Activate and install pip packages
-source "${VENV_DIR}/bin/activate"
-pip install --upgrade pip >/dev/null
-pip install -r "${REQUIREMENTS}"
-
-# --- Verify ---
-echo ""
-echo "=== Verifying imports ==="
-python3 -c "
-import pymobiledevice3
-print(' pmd3 OK')
-"
-
-echo ""
-echo "=== venv ready ==="
-echo " Activate: source ${VENV_DIR}/bin/activate"
-echo " Deactivate: deactivate"
diff --git a/scripts/setup_venv_linux.sh b/scripts/setup_venv_linux.sh
deleted file mode 100644
index ec164bfe..00000000
--- a/scripts/setup_venv_linux.sh
+++ /dev/null
@@ -1,52 +0,0 @@
-#!/bin/bash
-# setup_venv_linux.sh — Create Python venv on Linux (Debian/Ubuntu).
-#
-# Usage:
-# bash scripts/setup_venv_linux.sh
-#
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-VENV_DIR="${PROJECT_ROOT}/.venv"
-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 gcc g++ pkg-config 2>/dev/null
-elif command -v dnf &>/dev/null; then
- dnf install -y python3 python3-pip gcc gcc-c++ 2>/dev/null
-fi
-
-PYTHON="$(command -v python3)"
-if [[ -z "${PYTHON}" ]]; then
- echo "Error: python3 not found in PATH"
- exit 1
-fi
-
-echo ""
-echo "=== Creating venv ==="
-echo " Python: ${PYTHON} ($(${PYTHON} --version 2>&1))"
-echo " venv: ${VENV_DIR}"
-echo " deps: ${REQUIREMENTS}"
-echo ""
-
-"${PYTHON}" -m venv "${VENV_DIR}"
-
-source "${VENV_DIR}/bin/activate"
-pip install --upgrade pip >/dev/null
-pip install -r "${REQUIREMENTS}"
-
-# --- Verify ---
-echo ""
-echo "=== Verifying imports ==="
-python3 -c "
-import pymobiledevice3
-print(' pmd3 OK')
-"
-
-echo ""
-echo "=== venv ready ==="
-echo " Activate: source ${VENV_DIR}/bin/activate"
-echo " Deactivate: deactivate"
diff --git a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
index 61b22a96..0cae322d 100644
--- a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
+++ b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift
@@ -16,28 +16,23 @@ extension CryptexFilesystemPatcher {
/// shell out for now asks VPhoneSign for.
///
/// The `.p12` is opened here because VPhoneSign signs with an already-read
- /// identity — but not on the `VPHONE_USE_LDID` path, where the external
- /// tool opens the container itself from `identityPath`. Skipping the parse
- /// there is what keeps the escape hatch a way *out* of a VPhoneSign
- /// regression rather than a second way into one.
+ /// identity. There is no longer a second path that opens it elsewhere: the
+ /// external-ldid escape hatch is gone, so this parse either succeeds or the
+ /// step fails, and a missing identity can no longer become a silent ad-hoc
+ /// downgrade.
func guestSigningOptions(
cfwInput: URL,
identifier: String? = nil,
entitlements: URL? = nil
) throws -> VPhoneSignOptions {
let signingCertificatePath = cfwInput.appending(path: "cfw_input/signcert.p12")
- var identity: (any VPhoneSigningIdentity)?
- if !VPhoneLdid.isPreferred {
- identity = try VPhoneSignIdentity(
- pkcs12: Data(contentsOf: signingCertificatePath), password: ""
- )
- }
return VPhoneSignOptions(
identifier: identifier,
entitlements: try entitlements.map { try Data(contentsOf: $0) },
mergesExisting: true,
- identity: identity,
- identityPath: signingCertificatePath.path
+ identity: try VPhoneSignIdentity(
+ pkcs12: Data(contentsOf: signingCertificatePath), password: ""
+ )
)
}
diff --git a/sources/VPhoneCore/VPhoneResources.swift b/sources/VPhoneCore/VPhoneResources.swift
index 2288a3b8..b2733357 100644
--- a/sources/VPhoneCore/VPhoneResources.swift
+++ b/sources/VPhoneCore/VPhoneResources.swift
@@ -1,12 +1,6 @@
import Darwin // _NSGetExecutablePath
import Foundation
-// MARK: - VPhoneResourcesError
-
-public enum VPhoneResourcesError: Error, Equatable {
- case venvBootstrapFailed(String)
-}
-
// MARK: - VPhoneResources
public struct VPhoneResources: Sendable {
@@ -102,7 +96,6 @@ public struct VPhoneResources: Sendable {
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 signcert: URL { scriptsDir.appendingPathComponent("vphoned/signcert.p12") }
public var vphoned: URL {
@@ -116,8 +109,8 @@ public struct VPhoneResources: Sendable {
// MARK: - Cache dirs
/// The per-user data root: `$VPHONE_ROOT` when set, else `~/.vphone`. Both
- /// `VPhoneResources` (ipsws/tools/debs/venv) and `VPhoneLibrary` (VMs)
- /// derive from this so one variable redirects everything vphone-cli creates.
+ /// `VPhoneResources` (ipsws/tools/debs) and `VPhoneLibrary` (VMs) derive
+ /// from this so one variable redirects everything vphone-cli creates.
public static func userDataRoot() -> URL {
if let root = ProcessInfo.processInfo.environment["VPHONE_ROOT"], !root.isEmpty {
return URL(fileURLWithPath: root, isDirectory: true)
@@ -129,153 +122,25 @@ public struct VPhoneResources: Sendable {
public var sealVolumeCacheDir: URL { Self.userDataRoot().appendingPathComponent("tools") }
public var debsCacheDir: URL { Self.userDataRoot().appendingPathComponent("debs") }
- // MARK: - Python
-
- /// 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", "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") }
-
- /// Per-user managed venv, created on demand. Deliberately OUTSIDE both the
- /// repo and the .app so the app is portable — a venv is never moved between
- /// machines (its links would break); it is built fresh on each host.
- public var managedVenvDir: URL {
- if let dir = ProcessInfo.processInfo.environment["VPHONE_VENV_DIR"], !dir.isEmpty {
- return URL(fileURLWithPath: dir)
- }
- return Self.userDataRoot().appendingPathComponent("venv")
- }
- private var managedVenvPython: URL { managedVenvDir.appendingPathComponent("bin/python3") }
-
- /// 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 pymobiledevice3; import sys; "
- + "sys.exit(0 if hasattr(IPSW, 'create_from_path') else 1)"
- return (try? VPhoneProcessRunner.runCapturing(python, ["-c", probe]))?.succeeded == 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 pythonIsUsable(devVenv) { return devVenv }
- if pythonIsUsable(managedVenvPython) { return managedVenvPython }
- return try bootstrapManagedVenv()
- }
-
- /// Provision `~/.vphone/venv`: try each candidate host python for real
- /// (build the venv, install deps, verify) and use the first that fully
- /// succeeds — a candidate that imports `venv` can still fail `-m venv`
- /// (e.g. a broken `ensurepip`), so we fall through instead of trusting it.
- /// One-time per machine.
- private func bootstrapManagedVenv() throws -> URL {
- func log(_ s: String) { FileHandle.standardError.write(Data((s + "\n").utf8)) }
- let candidates = candidateHostPythons()
- guard !candidates.isEmpty else {
- throw VPhoneResourcesError.venvBootstrapFailed(
- "No python3 found on this system. Install it with 'brew install [email protected]', or set VPHONE_PYTHON.")
- }
- log("[*] First run: setting up the Python environment at \(managedVenvDir.path)…")
- let py = managedVenvPython
- let install: [String] = FileManager.default.fileExists(atPath: requirementsFile.path)
- ? ["-m", "pip", "install", "-r", requirementsFile.path]
- : ["-m", "pip", "install"] + Self.fallbackRequirements
- var lastError = "No usable Python could be found on this system"
-
- for host in candidates {
- log(" → Trying \(host.path)…")
- try? FileManager.default.removeItem(at: managedVenvDir)
- try FileManager.default.createDirectory(
- at: Self.userDataRoot(),
- withIntermediateDirectories: true)
- guard (try? VPhoneProcessRunner.runStreaming(host, ["-m", "venv", managedVenvDir.path])) == 0 else {
- lastError = "Could not create a Python environment with \(host.path)"; continue
- }
- _ = try? VPhoneProcessRunner.runStreaming(py, ["-m", "pip", "install", "--upgrade", "-q", "pip"])
- guard (try? VPhoneProcessRunner.runStreaming(py, install)) == 0 else {
- lastError = "Could not install the required Python packages with \(host.path)"; continue
- }
- guard pythonIsUsable(py) else {
- lastError = "The Python environment built with \(host.path) is missing a required package"; continue
- }
- log("[+] Python environment ready: \(py.path)")
- return py
- }
- try? FileManager.default.removeItem(at: managedVenvDir)
- throw VPhoneResourcesError.venvBootstrapFailed(
- lastError + ". If the problem persists, install a modern python3 with "
- + "'brew install [email protected]', or set VPHONE_PYTHON.")
- }
-
- /// Ordered, existence-checked host python3 candidates to bootstrap from.
- /// Canonical Homebrew locations first, then versioned names on PATH, then
- /// generic `python3`, then system `/usr/bin/python3` (3.9) as a last resort
- /// (it resolves an old, broken pymobiledevice3 stack).
- private func candidateHostPythons() -> [URL] {
- var paths: [String] = []
- if let override = ProcessInfo.processInfo.environment["VPHONE_PYTHON"], !override.isEmpty {
- paths.append(override)
- }
- paths += ["/opt/homebrew/bin/python3", "/usr/local/bin/python3"]
- for name in ["python3.14", "python3.13", "python3.12", "python3.11", "python3.10"] {
- if let p = which(name) { paths.append(p) }
- }
- if let p = which("python3") { paths.append(p) }
- paths.append("/usr/bin/python3")
-
- var seen = Set<String>()
- return paths.filter { !$0.isEmpty && seen.insert($0).inserted }
- .filter { FileManager.default.isExecutableFile(atPath: $0) }
- .map { URL(fileURLWithPath: $0) }
- }
-
- /// First executable named `name` on `PATH`, or nil.
- ///
- /// This was `/usr/bin/env which <name>` — two processes, run six times per
- /// call to `candidateHostPythons()`, to read a variable this one already
- /// has. It is also the only PATH lookup the admission gates allow, and only
- /// because of what it is for: finding an *interpreter to offer the user*,
- /// not resolving one of this project's own programs. Those are resolved as
- /// siblings of the running image — see `siblingExecutable` — and a gate
- /// scan that sees `which` here should read this comment and move on.
- private func which(_ name: String) -> String? {
- guard let path = ProcessInfo.processInfo.environment["PATH"] else { return nil }
- for directory in path.split(separator: ":", omittingEmptySubsequences: true) {
- let candidate = "\(directory)/\(name)"
- if FileManager.default.isExecutableFile(atPath: candidate) { return candidate }
- }
- return nil
- }
+ // MARK: - No interpreter
+
+ // There is deliberately nothing here any more.
+ //
+ // This type used to resolve a python3 — an explicit `VPHONE_PYTHON`, the
+ // repo's `.venv`, a managed `~/.vphone/venv` it would provision on first
+ // run, and failing all of those a scan of `PATH` for python3.14 down to
+ // python3.10 and then `/usr/bin/python3`. The one program that needed it
+ // was the pymobiledevice3 restore bridge, and the restore backend is now
+ // libirecovery + idevicerestore linked into this binary (`VPhoneRestore`).
+ //
+ // The whole ladder is gone rather than left unused, because the last rung
+ // was the dangerous one: a `PATH` fallback makes a missing environment look
+ // like a working one, right up until a restore fails on a stranger's
+ // machine. Nothing in this package may resolve an interpreter again — see
+ // the "Python" section in AGENTS.md, and `scripts/check_aux.sh`, which now
+ // fails outright on a python3 lookup instead of registering it.
+
+ // With the interpreter went the last `PATH` lookup in this package. Every
+ // program vphone-cli runs is either a sibling of the running image
+ // (`siblingExecutable`) or a bundled script under `scriptsDir`.
}
diff --git a/sources/VPhoneRestore/VPhoneRestoreBridge.swift b/sources/VPhoneRestore/VPhoneRestoreBridge.swift
index 8cf357f8..7a28ce11 100644
--- a/sources/VPhoneRestore/VPhoneRestoreBridge.swift
+++ b/sources/VPhoneRestore/VPhoneRestoreBridge.swift
@@ -73,10 +73,8 @@ public enum VPhoneRestoreBridge {
)
let written = try locateWrittenSHSH(under: cacheDirectory, requestedECID: ecid)
- let contents = try VPhoneRestoreTicket.plistData(
- of: try Data(contentsOf: written),
- at: written
- )
+ let onDisk = try Data(contentsOf: written)
+ let contents = try VPhoneRestoreTicket.plistData(of: onDisk, at: written)
// Python named the file after the ECID the DEVICE reported, not the one
// that was asked for; idevicerestore puts that same value at the front
diff --git a/sources/VPhoneRestore/VPhoneRestoreEvent.swift b/sources/VPhoneRestore/VPhoneRestoreEvent.swift
index d536f28d..4839000a 100644
--- a/sources/VPhoneRestore/VPhoneRestoreEvent.swift
+++ b/sources/VPhoneRestore/VPhoneRestoreEvent.swift
@@ -93,6 +93,12 @@ public enum VPhoneRestoreConsole {
/// mutex, but the captured `printf` channel does not, and two threads
/// interleaving mid-line is the kind of log nobody can read. Each call
/// returns an independently locked sink, so use one per restore.
+ ///
+ /// The `print` below happens while the C bridge has the process's `stdout`
+ /// redirected into itself, which would be a loop — except that the bridge
+ /// marks the thread it is calling a callback on and passes that thread's
+ /// writes through to the real stdout. See `g_in_callback` in
+ /// `vphone_restore_bridge.c`; printing from here is the case it exists for.
public static func handler(
level: VPhoneRestoreLogLevel = .info,
showsProgress: Bool = false
diff --git a/sources/VPhoneRestore/VPhoneRestoreTicket.swift b/sources/VPhoneRestore/VPhoneRestoreTicket.swift
index a631b4a2..aa1bd424 100644
--- a/sources/VPhoneRestore/VPhoneRestoreTicket.swift
+++ b/sources/VPhoneRestore/VPhoneRestoreTicket.swift
@@ -102,10 +102,11 @@ public enum VPhoneRestoreTicket {
case Z_STREAM_END:
return true
case Z_OK, Z_BUF_ERROR:
- // Z_BUF_ERROR with nothing left to read is a truncated
- // stream; with input left it just means "call me again".
- if status == Z_BUF_ERROR, produced == 0, stream.avail_in == 0 { return false }
- if stream.avail_in == 0, produced == 0 { return false }
+ // No input left and no output produced means inflate can
+ // make no further progress and the stream ended without
+ // its trailer — a truncated file, not a finished one. Z_OK
+ // otherwise just means "call me again".
+ if produced == 0, stream.avail_in == 0 { return false }
default:
return false
}
diff --git a/sources/VPhoneSign/VPhoneSignError.swift b/sources/VPhoneSign/VPhoneSignError.swift
index e2b5c1c4..a205a1c2 100644
--- a/sources/VPhoneSign/VPhoneSignError.swift
+++ b/sources/VPhoneSign/VPhoneSignError.swift
@@ -28,8 +28,6 @@ public enum VPhoneSignError: Error, Equatable, CustomStringConvertible {
case identityUnreadable(String)
/// The CMS signature could not be produced.
case signingFailed(String)
- /// `--use-ldid` was asked for and the external tool is missing or failed.
- case ldidUnavailable(String)
public var description: String {
switch self {
@@ -40,7 +38,6 @@ public enum VPhoneSignError: Error, Equatable, CustomStringConvertible {
case let .unsupportedEntitlements(detail): "unsupported entitlements: \(detail)"
case let .identityUnreadable(detail): "cannot read the signing identity: \(detail)"
case let .signingFailed(detail): "signing failed: \(detail)"
- case let .ldidUnavailable(detail): "ldid: \(detail)"
}
}
}
diff --git a/sources/VPhoneSign/VPhoneSignLdid.swift b/sources/VPhoneSign/VPhoneSignLdid.swift
deleted file mode 100644
index 4e7f58a8..00000000
--- a/sources/VPhoneSign/VPhoneSignLdid.swift
+++ /dev/null
@@ -1,134 +0,0 @@
-import Foundation
-
-// MARK: - The way back to ldid
-
-/// Running the external `ldid` instead of signing here.
-///
-/// This exists so that a regression in `VPhoneSign` is recoverable without a
-/// rebuild: set `VPHONE_USE_LDID=1` and every call site goes back to the
-/// tool it used before. It is deliberately not something the shipped bundle
-/// can reach on its own — `ldid` is the Homebrew binary that fails the
-/// self-contained admission rule, which is why it was replaced — so it looks
-/// for it on `PATH` and in the two Homebrew prefixes and fails loudly when
-/// it is not there, rather than quietly doing something else.
-///
-/// The plan's §10.19 says this comes out once the byte-for-byte gates have
-/// been green through a real guest boot. Until then it is one environment
-/// variable away.
-public enum VPhoneLdid {
- /// Whether a call with no explicit preference should use ldid.
- public static var isPreferred: Bool {
- let value = ProcessInfo.processInfo.environment["VPHONE_USE_LDID"] ?? ""
- return !value.isEmpty && value != "0" && value.lowercased() != "false"
- }
-
- /// Where the tool is, if it is anywhere.
- public static func resolve() -> URL? {
- var candidates = ["/opt/homebrew/bin/ldid", "/usr/local/bin/ldid"]
- for directory in (ProcessInfo.processInfo.environment["PATH"] ?? "").split(separator: ":") {
- candidates.append("\(directory)/ldid")
- }
- return candidates.first { FileManager.default.isExecutableFile(atPath: $0) }
- .map { URL(fileURLWithPath: $0) }
- }
-
- /// The arguments that make `ldid` do what `options` asks. Kept apart from
- /// running it so the mapping between the two signers can be read, and
- /// tested, in one place.
- ///
- /// These five flags — `-S`, `-S<file>`, `-M`, `-K<p12>`, `-I<name>`, and
- /// `-e` on the reading side — are every flag the repository ever passes.
- /// That was worked out by reading the call sites. Do not quote a total
- /// from memory: the number drops every time an installer is ported, and
- /// two figures written here have already gone stale. Measure it:
- ///
- /// grep -rnE '(^|[^_[:alnum:]])ldid[[:space:]]+-' scripts/ cfw-kit/ --include='*.sh'
- /// grep -rnE '(^|[^_[:alnum:]])ldid_sign(_ent)?[[:space:]]' scripts/ cfw-kit/ --include='*.sh'
- ///
- /// (17 and 33 on 2026-09-23.) A count of 175 has been quoted for this;
- /// that is every textual mention of the word, a different and much larger
- /// number. The flag set above is what matters here, and it has not moved.
- ///
- /// `entitlementsPath` is where `options.entitlements` has been written;
- /// ldid takes a file, not bytes.
- public static func arguments(
- for options: VPhoneSignOptions, entitlementsPath: String?, identityPath: String?
- ) -> [String] {
- var arguments: [String] = []
- arguments.append(entitlementsPath.map { "-S\($0)" } ?? "-S")
- if options.mergesExisting {
- arguments.append("-M")
- }
- if let identityPath {
- arguments.append("-K\(identityPath)")
- }
- if let identifier = options.identifier {
- arguments.append("-I\(identifier)")
- }
- return arguments
- }
-
- /// Signs with the external tool. `identityPath` is the `.p12`, since
- /// ldid reads the container itself rather than taking an opened identity.
- public static func sign(fileAt url: URL, options: VPhoneSignOptions, identityPath: String?) throws {
- guard let tool = resolve() else {
- throw VPhoneSignError.ldidUnavailable(
- "VPHONE_USE_LDID is set but ldid is not installed (brew install ldid-procursus)"
- )
- }
- // ldid opens the container itself, so the escape hatch needs the
- // path and not the identity. Signing ad-hoc because the path was
- // left out would be a silent downgrade from a real signature.
- guard options.identity == nil || identityPath != nil else {
- throw VPhoneSignError.ldidUnavailable(
- "a signing identity was given but not the .p12 it came from, which is what ldid needs"
- )
- }
- var entitlementsPath: String?
- var temporary: URL?
- if let entitlements = options.entitlements {
- let file = FileManager.default.temporaryDirectory
- .appendingPathComponent("vphone-ldid-\(UUID().uuidString).plist")
- try entitlements.write(to: file)
- entitlementsPath = file.path
- temporary = file
- }
- defer { temporary.map { try? FileManager.default.removeItem(at: $0) } }
-
- let process = Process()
- process.executableURL = tool
- process.arguments = arguments(
- for: options, entitlementsPath: entitlementsPath, identityPath: identityPath
- ) + [url.path]
- let diagnostics = Pipe()
- process.standardError = diagnostics
- try process.run()
- let message = String(decoding: diagnostics.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
- process.waitUntilExit()
- guard process.terminationStatus == 0 else {
- throw VPhoneSignError.ldidUnavailable("ldid exited \(process.terminationStatus): \(message)")
- }
- }
-
- /// `ldid -e`, for the same reason: one switch puts both directions back.
- public static func entitlements(ofFileAt url: URL) throws -> Data {
- guard let tool = resolve() else {
- throw VPhoneSignError.ldidUnavailable(
- "VPHONE_USE_LDID is set but ldid is not installed (brew install ldid-procursus)"
- )
- }
- let process = Process()
- process.executableURL = tool
- process.arguments = ["-e", url.path]
- let out = Pipe()
- process.standardOutput = out
- process.standardError = FileHandle.nullDevice
- try process.run()
- let data = out.fileHandleForReading.readDataToEndOfFile()
- process.waitUntilExit()
- guard process.terminationStatus == 0 else {
- throw VPhoneSignError.ldidUnavailable("ldid -e exited \(process.terminationStatus)")
- }
- return data
- }
-}
diff --git a/sources/VPhoneSign/VPhoneSigner.swift b/sources/VPhoneSign/VPhoneSigner.swift
index 579f0f7a..7d708c3e 100644
--- a/sources/VPhoneSign/VPhoneSigner.swift
+++ b/sources/VPhoneSign/VPhoneSigner.swift
@@ -42,30 +42,19 @@ public struct VPhoneSignOptions {
public var style = Style.ldid
/// `-K`: sign for real rather than ad-hoc.
public var identity: (any VPhoneSigningIdentity)?
- /// Where `identity` was read from. Only the escape hatch needs it: the
- /// external ldid opens the container itself.
- public var identityPath: String?
- /// `--use-ldid`: hand the file to the external tool instead. nil asks
- /// the environment (`VPHONE_USE_LDID`), which is how a regression is
- /// recovered from without touching a call site.
- public var usesExternalLdid: Bool?
public init(
identifier: String? = nil,
entitlements: Data? = nil,
mergesExisting: Bool = false,
style: Style = .ldid,
- identity: (any VPhoneSigningIdentity)? = nil,
- identityPath: String? = nil,
- usesExternalLdid: Bool? = nil
+ identity: (any VPhoneSigningIdentity)? = nil
) {
self.identifier = identifier
self.entitlements = entitlements
self.mergesExisting = mergesExisting
self.style = style
self.identity = identity
- self.identityPath = identityPath
- self.usesExternalLdid = usesExternalLdid
}
}
@@ -88,10 +77,6 @@ public enum VPhoneSigner {
public static func sign(fileAt url: URL, options: VPhoneSignOptions = .init()) throws -> Data {
var options = options
options.identifier = options.identifier ?? url.lastPathComponent
- if options.usesExternalLdid ?? VPhoneLdid.isPreferred {
- try VPhoneLdid.sign(fileAt: url, options: options, identityPath: options.identityPath)
- return try Data(contentsOf: url)
- }
let data = try Data(contentsOf: url)
let signed = try sign(data, options: options)
// The same path ldid takes: a temporary beside the file, its mode
@@ -206,12 +191,8 @@ public enum VPhoneSigner {
/// any, in slice order, exactly as the signature stores them. A slice
/// with none contributes nothing, so a file with no entitlements at all
/// gives an empty array.
- public static func entitlements(ofFileAt url: URL, usesExternalLdid: Bool? = nil) throws -> [Data] {
- if usesExternalLdid ?? VPhoneLdid.isPreferred {
- let dumped = try VPhoneLdid.entitlements(ofFileAt: url)
- return dumped.isEmpty ? [] : [dumped]
- }
- return try entitlements(in: Data(contentsOf: url))
+ public static func entitlements(ofFileAt url: URL) throws -> [Data] {
+ try entitlements(in: Data(contentsOf: url))
}
public static func entitlements(in data: Data) throws -> [Data] {
diff --git a/sources/vphone-cli/VPhoneCLI.swift b/sources/vphone-cli/VPhoneCLI.swift
index b923d4fe..acfa7391 100644
--- a/sources/vphone-cli/VPhoneCLI.swift
+++ b/sources/vphone-cli/VPhoneCLI.swift
@@ -9,7 +9,8 @@ struct VPhoneCLI: ParsableCommand {
abstract: "Boot a virtual iPhone or patch firmware with the Swift pipeline",
subcommands: [
VPhoneBootCLI.self, PatchFirmwareCLI.self, PatchComponentCLI.self, VPhoneVMCommand.self,
- VPhoneFWCommand.self, VPhoneRestoreCommand.self, VPhoneCFWCommand.self, VPhoneSetupCommand.self,
+ VPhoneFWCommand.self, VPhoneRestoreCommand.self, VPhoneRecoveryProbeCommand.self,
+ VPhoneCFWCommand.self,
VPhoneSignCommand.self, VPhoneDumpEntitlementsCommand.self,
],
defaultSubcommand: VPhoneBootCLI.self
diff --git a/sources/vphone-cli/VPhoneCreateOrchestrator.swift b/sources/vphone-cli/VPhoneCreateOrchestrator.swift
index 84bf7eaa..893702e1 100644
--- a/sources/vphone-cli/VPhoneCreateOrchestrator.swift
+++ b/sources/vphone-cli/VPhoneCreateOrchestrator.swift
@@ -1,6 +1,7 @@
import FirmwarePatcher
import Foundation
import VPhoneCore
+import VPhoneRestore
// MARK: - VPhoneCreateError
@@ -17,8 +18,8 @@ private enum VPhoneCreateError: Error, CustomStringConvertible {
case invalidECID(String)
case udidECIDMismatch(udid: String, ecid: String)
case recoveryTimeout
- case restoreGetSHSHFailed(Int32)
- case restoreUpdateFailed(Int32)
+ case restoreGetSHSHFailed(String)
+ case restoreUpdateFailed(String)
case cfwInstallFailed(Int32)
case sudoPasswordRequired
case firstBootPanic
@@ -49,10 +50,12 @@ private enum VPhoneCreateError: Error, CustomStringConvertible {
+ "Run vm create again to regenerate it."
case .recoveryTimeout:
"Timed out waiting for the device to enter recovery mode."
- case let .restoreGetSHSHFailed(code):
- "Unable to fetch the signing ticket (exit code \(code))."
- case let .restoreUpdateFailed(code):
- "Device restore failed (exit code \(code))."
+ // No exit code any more: the restore backend is in this process, so
+ // what a failure carries is the reason it gave.
+ case let .restoreGetSHSHFailed(reason):
+ "Unable to fetch the signing ticket: \(reason)"
+ case let .restoreUpdateFailed(reason):
+ "Device restore failed: \(reason)"
case let .cfwInstallFailed(code):
"Custom firmware installation failed (exit code \(code))."
case .sudoPasswordRequired:
@@ -228,14 +231,6 @@ public struct VPhoneCreateOrchestrator {
print("[trace] \(msg)")
}
- /// `-v` repeated `min(v.rawValue, 2)` times, for the pmd3 bridge's own
- /// `--verbose`/`-v` count option (`.info`→1 INFO / pmd3's colorful default,
- /// `.debug`/`.trace`→2 DEBUG). `-v` on `vm create` thus surfaces the pmd3
- /// restore logs, which is the whole point of asking for verbosity.
- private func pmd3VerbosityArgs(_ v: VPhoneVerbosity) -> [String] {
- Array(repeating: "-v", count: min(v.rawValue, 2))
- }
-
// MARK: - nested-VM preflight
/// True when running inside an Apple VM (`kern.hv_vmm_present == 1`),
@@ -361,31 +356,46 @@ public struct VPhoneCreateOrchestrator {
let (udid, ecid) = try loadDeviceIdentity(bundleURL: bundleURL)
print("[+] Device identity loaded: UDID=\(udid) ECID=0x\(ecid)")
+ // `loadDeviceIdentity` has already held this to ^[0-9A-F]{16}$, so the
+ // parse cannot fail; it is here because the backend takes the number.
+ let ecidValue = try VPhoneRestoreIdentity.parseECID(ecid)
- try waitForRecovery(ecid: ecid, verbosity: v)
+ try waitForRecovery(ecid: ecidValue, verbosity: v)
- let python = try resources.pythonExecutable()
- let verbosityArgs = pmd3VerbosityArgs(v)
+ // Both steps run in this process now — no python, no argv, no exit
+ // code — and report through the same console sink the CLI's `restore`
+ // uses. `-v` still decides how much of the restore log is shown.
+ let onEvent = VPhoneRestoreConsole.handler(level: v.restoreLogLevel)
print("[*] Fetching SHSH blob...")
- let shshArgs =
- [resources.pmd3Bridge.path, "restore-get-shsh", "--vm-dir", ".", "--udid", udid, "--ecid", "0x\(ecid)"]
- + verbosityArgs
- trace("spawn \(python.path) \(shshArgs.joined(separator: " "))", v)
- let shshCode = try VPhoneProcessRunner.runStreaming(python, shshArgs, cwd: bundleURL, echo: v.showsToolDetail)
- guard shshCode == 0 else { throw VPhoneCreateError.restoreGetSHSHFailed(shshCode) }
+ trace("in-process VPhoneRestoreBridge.fetchSHSH udid=\(udid) ecid=0x\(ecid)", v)
+ do {
+ try VPhoneRestoreBridge.fetchSHSH(
+ vmDir: bundleURL,
+ ecid: ecidValue,
+ udid: udid,
+ out: nil,
+ debugLevel: v.restoreDebugLevel,
+ onEvent: onEvent
+ )
+ } catch {
+ throw VPhoneCreateError.restoreGetSHSHFailed("\(error)")
+ }
print("[*] Restoring...")
- let restoreArgs =
- [resources.pmd3Bridge.path, "restore-update", "--vm-dir", ".", "--udid", udid, "--ecid", "0x\(ecid)"]
- + verbosityArgs
- trace("spawn \(python.path) \(restoreArgs.joined(separator: " "))", v)
- let restoreCode = try VPhoneProcessRunner.runStreaming(
- python,
- restoreArgs,
- cwd: bundleURL,
- echo: v.showsToolDetail
- )
- guard restoreCode == 0 else { throw VPhoneCreateError.restoreUpdateFailed(restoreCode) }
+ trace("in-process VPhoneRestoreBridge.restore udid=\(udid) ecid=0x\(ecid) erase=true", v)
+ do {
+ try VPhoneRestoreBridge.restore(
+ vmDir: bundleURL,
+ ecid: ecidValue,
+ udid: udid,
+ erase: true,
+ ticketPath: nil,
+ debugLevel: v.restoreDebugLevel,
+ onEvent: onEvent
+ )
+ } catch {
+ throw VPhoneCreateError.restoreUpdateFailed("\(error)")
+ }
recordRestoreVersions(bundleURL: bundleURL)
@@ -461,16 +471,16 @@ public struct VPhoneCreateOrchestrator {
return (udid, ecid)
}
- private func waitForRecovery(ecid: String, verbosity v: VPhoneVerbosity) throws {
+ /// 90 attempts, each waiting up to 2 seconds for an endpoint and sleeping 2
+ /// between — the cadence `setup_machine.sh`'s `wait_for_recovery` set, kept
+ /// to the attempt. What is gone is the python process per attempt: the same
+ /// wait is now one `irecv_open_with_ecid_and_attempts` poll per round.
+ private func waitForRecovery(ecid: UInt64?, verbosity v: VPhoneVerbosity) throws {
print("[*] Waiting for recovery/DFU endpoint...")
- let python = try resources.pythonExecutable()
for _ in 1...90 {
- let result = try? VPhoneProcessRunner.runCapturing(
- python,
- [resources.pmd3Bridge.path, "recovery-probe", "--ecid", "0x\(ecid)", "--timeout", "2"]
- )
- if result?.succeeded == true {
+ if let device = try? VPhoneRestoreBridge.recoveryProbe(ecid: ecid, timeout: 2) {
print("[+] Device endpoint is reachable")
+ trace("recovery-probe: \(device.productType ?? "device") in \(device.mode)", v)
return
}
Thread.sleep(forTimeInterval: 2)
diff --git a/sources/vphone-cli/VPhoneRestoreCLI.swift b/sources/vphone-cli/VPhoneRestoreCLI.swift
index 7f366473..fe6d9216 100644
--- a/sources/vphone-cli/VPhoneRestoreCLI.swift
+++ b/sources/vphone-cli/VPhoneRestoreCLI.swift
@@ -1,6 +1,22 @@
import ArgumentParser
import Foundation
import VPhoneCore
+import VPhoneRestore
+
+// MARK: - Verbosity → restore logging
+
+extension VPhoneVerbosity {
+ /// What `-v` meant when the restore ran as a Python subprocess: one `-v`
+ /// for `.info` (pymobiledevice3's colorful INFO), two for `.debug` and
+ /// `.trace`. In process that single count becomes two knobs, and both are
+ /// needed — see `restoreDebugLevel`.
+ var restoreLogLevel: VPhoneRestoreLogLevel { self >= .debug ? .debug : .info }
+
+ /// idevicerestore's own level ceiling (`-d`). Raising the console sink
+ /// without raising this one prints nothing extra, because the messages it
+ /// would show are never emitted.
+ var restoreDebugLevel: Int32 { self >= .debug ? 1 : 0 }
+}
// MARK: - restore
@@ -18,38 +34,41 @@ struct VPhoneRestoreCommand: ParsableCommand {
@Option(name: .shortAndLong, help: "Device UDID (optional)") var udid: String?
@Option(name: .shortAndLong, help: "Device ECID (default: read from the bundle's udid-prediction.txt)")
var ecid: String?
- @Option(name: .shortAndLong, help: "Resource base override (default: inferred from the running binary path)")
- var projectRoot: String?
@Flag(name: .customShort("v"), help: "Increase verbosity: -v tool detail, -vv guest serial, -vvv internal trace")
var verboseCount: Int
+ /// The restore runs here now, in this process: `VPhoneRestore` over
+ /// libirecovery and idevicerestore, where a python spawned with an argv
+ /// used to be. A failure therefore throws instead of returning an exit
+ /// code — which keeps the two halves that mattered, the non-zero exit and
+ /// `restore-info.json` staying unwritten.
func run() throws {
let v = max(VPhoneVerbosity.info, VPhoneVerbosity(count: verboseCount))
let name = try VPhoneVMSelection.resolveExisting(name, in: lib.library)
let bundle = try lib.library.bundle(named: name)
- let resources = projectRoot.map { VPhoneResources(base: URL(fileURLWithPath: $0)) } ?? .resolve()
- guard let ecidValue = VPhoneRestoreOps.resolveECID(explicit: ecid, bundle: bundle) else {
+ guard let ecidText = VPhoneRestoreOps.resolveECID(explicit: ecid, bundle: bundle) else {
throw VPhoneRestoreError.ecidUnresolved
}
-
- func pmd3(_ subcommand: String, extra: [String]) throws -> Int32 {
- var args = [resources.pmd3Bridge.path, subcommand, "--vm-dir", "."]
- if let udid { args += ["--udid", udid] }
- args += ["--ecid", ecidValue] + extra
- // -v (.info) → pmd3 INFO (its colorful log level), -vv/-vvv → DEBUG.
- args += Array(repeating: "-v", count: min(v.rawValue, 2))
- let python = try resources.pythonExecutable()
- if v.tracesInternals {
- print("[trace] spawning: \(python.path) \(args.joined(separator: " "))")
- }
- return try VPhoneProcessRunner.runStreaming(python, args, cwd: bundle.url, echo: v.showsToolDetail)
+ let ecidValue = try VPhoneRestoreIdentity.parseECID(ecidText)
+ let onEvent = VPhoneRestoreConsole.handler(level: v.restoreLogLevel)
+ if v.tracesInternals {
+ let ecidLabel = ecidValue.map { "0x" + VPhoneRestoreIdentity.formatECID($0) } ?? "(any attached device)"
+ print("[trace] restore backend: in-process, ECID \(ecidLabel), debug level \(v.restoreDebugLevel)")
}
if getShsh {
- throw ExitCode(try pmd3("restore-get-shsh", extra: []))
+ try VPhoneRestoreBridge.fetchSHSH(
+ vmDir: bundle.url,
+ ecid: ecidValue,
+ udid: udid,
+ out: nil,
+ debugLevel: v.restoreDebugLevel,
+ onEvent: onEvent
+ )
+ return
}
- let code: Int32
+ var ticket: URL?
if offline {
let fm = FileManager.default
let shshes = ((try? fm.contentsOfDirectory(at: bundle.url, includingPropertiesForKeys: nil)) ?? [])
@@ -62,13 +81,19 @@ struct VPhoneRestoreCommand: ParsableCommand {
guard let restoreDir else { throw VPhoneRestoreError.noRestoreDir }
print("[restore] decrypting AEA images in \(restoreDir.lastPathComponent)...")
try VPhoneRestoreOps.decryptAEAImages(inRestoreDir: restoreDir)
- code = try pmd3("restore-update", extra: ["--tss", shsh.path])
- } else {
- code = try pmd3("restore-update", extra: [])
+ ticket = shsh
}
- if code == 0 { recordRestoreVersions(bundle: bundle) }
- throw ExitCode(code)
+ try VPhoneRestoreBridge.restore(
+ vmDir: bundle.url,
+ ecid: ecidValue,
+ udid: udid,
+ erase: true,
+ ticketPath: ticket,
+ debugLevel: v.restoreDebugLevel,
+ onEvent: onEvent
+ )
+ recordRestoreVersions(bundle: bundle)
}
/// Snapshot the just-restored iOS + cloudOS versions to `restore-info.json`,
@@ -91,6 +116,37 @@ struct VPhoneRestoreCommand: ParsableCommand {
}
}
+// MARK: - recovery-probe
+
+/// The Python bridge's `recovery-probe`, under the same name.
+///
+/// It exists for `scripts/setup_machine.sh`, which polls for a DFU endpoint
+/// from the shell and has nothing but an exit code to go on — `vm create` does
+/// the same waiting in process (`VPhoneCreateOrchestrator.waitForRecovery`) and
+/// does not go through here.
+struct VPhoneRecoveryProbeCommand: ParsableCommand {
+ static let configuration = CommandConfiguration(
+ commandName: "recovery-probe",
+ abstract: "Wait briefly for a DFU/recovery endpoint; exit 0 if one answered"
+ )
+
+ @Option(name: .shortAndLong, help: "Device ECID (hex, 0x optional; default: the only device attached)")
+ var ecid: String?
+ @Option(name: .shortAndLong, help: "Seconds to keep probing before giving up") var timeout: Int = 2
+
+ func run() throws {
+ let device = try VPhoneRestoreBridge.recoveryProbe(
+ ecid: try VPhoneRestoreIdentity.parseECID(ecid),
+ timeout: timeout
+ )
+ // The Python printed nothing at all and its one caller discarded both
+ // streams. One line costs that caller nothing and is the difference
+ // between "it worked" and knowing which device answered.
+ print("[+] \(device.productType ?? "device") in \(device.mode), "
+ + "ECID 0x\(VPhoneRestoreIdentity.formatECID(device.ecid))")
+ }
+}
+
// MARK: - cfw
struct VPhoneCFWCommand: ParsableCommand {
@@ -198,7 +254,9 @@ struct VPhoneCFWInstallCommand: ParsableCommand {
// The script re-execs under sudo, so it cannot work out where we
// live from its own path in the bundled case. Tell it.
"VPHONE_CLI_BIN": VPhoneResources.runningExecutable().path,
- "VPHONE_PYTHON": try resources.pythonExecutable().path,
+ // No VPHONE_PYTHON: the installers call `vphone-cli cfw <verb>` for
+ // every patch, and cfw_install_host.sh stopped reading it when the
+ // last Python patcher was deleted.
"IPSW_DIR": resources.ipswCacheDir.path,
"VPHONE_SEAL_DIR": resources.sealVolumeCacheDir.path,
"VPHONE_DEBS_DIR": resources.debsCacheDir.path,
@@ -222,7 +280,7 @@ struct VPhoneCFWInstallCommand: ParsableCommand {
var env = ProcessInfo.processInfo.environment
for (key, value) in scriptEnv { env[key] = value }
if v.tracesInternals {
- print("[trace] spawning: /bin/zsh \(args.joined(separator: " ")) (env keys: VPHONE_PYTHON, IPSW_DIR, VPHONE_SEAL_DIR)")
+ print("[trace] spawning: /bin/zsh \(args.joined(separator: " ")) (env keys: VPHONE_CLI_BIN, IPSW_DIR, VPHONE_SEAL_DIR)")
}
code = try VPhoneProcessRunner.runStreaming(
URL(fileURLWithPath: "/bin/zsh"),
diff --git a/sources/vphone-cli/VPhoneSetupCLI.swift b/sources/vphone-cli/VPhoneSetupCLI.swift
deleted file mode 100644
index 1ec80c06..00000000
--- a/sources/vphone-cli/VPhoneSetupCLI.swift
+++ /dev/null
@@ -1,30 +0,0 @@
-import ArgumentParser
-import Foundation
-import VPhoneCore
-
-// MARK: - setup
-
-/// Provision (or verify) the host Python environment the guest pipeline needs.
-/// Runs implicitly on first use, but this makes it an explicit, up-front step
-/// so a freshly-copied .app can be prepared before a long `vm create`.
-struct VPhoneSetupCommand: ParsableCommand {
- static let configuration = CommandConfiguration(
- commandName: "setup",
- abstract: "Provision/verify the host Python environment (~/.vphone/venv)")
-
- @Flag(name: .shortAndLong, help: "Recreate the managed venv even if one already works")
- var force = false
- @Option(name: .shortAndLong, help: "Resource base override (default: inferred from the running binary path)")
- var projectRoot: String?
-
- func run() throws {
- let resources = projectRoot.map { VPhoneResources(base: URL(fileURLWithPath: $0)) } ?? .resolve()
- if force { try? FileManager.default.removeItem(at: resources.managedVenvDir) }
- // pythonExecutable() provisions ~/.vphone/venv on demand if none is
- // usable — running any python-backed command does this automatically;
- // `setup` just makes it explicit. It prints its own progress on a first
- // provision, so here only report the resolved interpreter.
- let python = try resources.pythonExecutable()
- print("python: \(python.path)")
- }
-}
diff --git a/sources/vphone-cli/VPhoneSignCLI.swift b/sources/vphone-cli/VPhoneSignCLI.swift
index 12b389c7..19f02da0 100644
--- a/sources/vphone-cli/VPhoneSignCLI.swift
+++ b/sources/vphone-cli/VPhoneSignCLI.swift
@@ -9,8 +9,12 @@
// ldid -S"$ent" -M "-K$p12" -I"$id" <file> -> vphone-cli sign …
// ldid -e <file> -> vphone-cli dump-entitlements
//
-// Both keep the `--use-ldid` escape hatch (and the VPHONE_USE_LDID environment
-// variable behind it), so a regression is recoverable without a rebuild.
+// There is no way back to the external tool. `--use-ldid` and the VPHONE_USE_LDID
+// environment variable behind it are gone: an escape hatch that shells out to a
+// Homebrew binary is a dependency whether or not the default path takes it, and
+// this project is meant to be self-contained. What guarded the replacement stays
+// where it belongs — tests/VPhoneSignTests compares these bytes against the real
+// ldid when one is installed, and skips rather than passes when one is not.
import ArgumentParser
import Foundation
@@ -80,9 +84,6 @@ struct VPhoneSignCommand: ParsableCommand {
)
var appleAdHoc = false
- @Flag(name: .customLong("use-ldid"), help: "Hand the file to the external ldid instead of signing here")
- var useLdid = false
-
func run() throws {
var options = VPhoneSignOptions()
options.identifier = identifier
@@ -90,19 +91,8 @@ struct VPhoneSignCommand: ParsableCommand {
options.mergesExisting = merge
options.style = appleAdHoc ? .appleAdHoc : .ldid
if let pkcs12 {
- // Both halves, and for different readers: the built-in signer wants
- // the opened identity, and --use-ldid wants the container's path
- // because ldid opens it itself. Setting only one of them is how a
- // real signature used to become a silent ad-hoc downgrade; the
- // external path now throws instead, which only works if the path is
- // here to throw about.
options.identity = try VPhoneSignIdentity(pkcs12: Data(contentsOf: pkcs12), password: "")
- options.identityPath = pkcs12.path
}
- // nil, not false: nil lets VPHONE_USE_LDID decide, which is the whole
- // point of the environment variable. Passing false would override it.
- options.usesExternalLdid = useLdid ? true : nil
-
try VPhoneSigner.sign(fileAt: file, options: options)
}
}
diff --git a/tests/VPhoneCoreTests/ResourcesTests.swift b/tests/VPhoneCoreTests/ResourcesTests.swift
index 38c92968..5c100669 100644
--- a/tests/VPhoneCoreTests/ResourcesTests.swift
+++ b/tests/VPhoneCoreTests/ResourcesTests.swift
@@ -15,8 +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.pmd3Bridge.path
- == "/Applications/vphone-cli.app/Contents/Resources/scripts/pymobiledevice3_bridge.py")
+ #expect(r.cfwInstallHostScript.path
+ == "/Applications/vphone-cli.app/Contents/Resources/scripts/cfw_install_host.sh")
}
@Test func devLayoutWalksUpToProjectRoot() throws {
@@ -44,53 +44,7 @@ struct ResourcesTests {
#expect(VPhoneResources.userDataRoot().path.hasSuffix("/.vphone"))
}
- /// 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)
- }
-
- /// 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() {
- // The override env vars would change this; only assert the default.
- if ProcessInfo.processInfo.environment["VPHONE_VENV_DIR"] != nil { return }
- if ProcessInfo.processInfo.environment["VPHONE_ROOT"] != nil { return }
- let r = VPhoneResources(base: URL(fileURLWithPath: "/x"))
- #expect(r.managedVenvDir.path.hasSuffix("/.vphone/venv"))
- }
-
@Test func userDataRootHonorsVPHONERoot() {
- unsetenv("VPHONE_VENV_DIR")
setenv("VPHONE_ROOT", "/tmp/vphone-test-root", 1)
defer { unsetenv("VPHONE_ROOT") }
let r = VPhoneResources(base: URL(fileURLWithPath: "/x"))
@@ -98,29 +52,36 @@ struct ResourcesTests {
#expect(r.ipswCacheDir.path == "/tmp/vphone-test-root/ipsws")
#expect(r.sealVolumeCacheDir.path == "/tmp/vphone-test-root/tools")
#expect(r.debsCacheDir.path == "/tmp/vphone-test-root/debs")
- #expect(r.managedVenvDir.path == "/tmp/vphone-test-root/venv")
}
- @Test func managedVenvOverrideBeatsVPHONERoot() {
+ /// `VPhoneResources` resolves programs as siblings of the running image and
+ /// scripts under `scriptsDir`, and nothing else — no `PATH` walk, no
+ /// interpreter. That claim is what the deleted venv tests used to guard
+ /// from the other side, so assert it directly: every URL this type hands
+ /// out is rooted in `base` or in the user data root.
+ @Test func everyResourceIsRootedInTheBaseOrTheDataRoot() {
setenv("VPHONE_ROOT", "/tmp/vphone-test-root", 1)
- setenv("VPHONE_VENV_DIR", "/tmp/custom-venv", 1)
- defer {
- unsetenv("VPHONE_ROOT")
- unsetenv("VPHONE_VENV_DIR")
+ defer { unsetenv("VPHONE_ROOT") }
+ let base = URL(fileURLWithPath: "/x")
+ let r = VPhoneResources(base: base)
+ let rooted = [
+ r.scriptsDir, r.resourceArchivesDir, r.fwPrepareScript,
+ r.cfwInstallHostScript, r.preflightScript, r.signcert, r.vphoned,
+ ]
+ for url in rooted {
+ #expect(url.path.hasPrefix("/x/"), "\(url.path) escapes the resource base")
+ }
+ for url in [r.ipswCacheDir, r.sealVolumeCacheDir, r.debsCacheDir] {
+ #expect(url.path.hasPrefix("/tmp/vphone-test-root/"))
}
- let r = VPhoneResources(base: URL(fileURLWithPath: "/x"))
- #expect(r.managedVenvDir.path == "/tmp/custom-venv")
}
- @Test func pythonUsabilityProbeRejectsMissingAcceptsDevVenv() {
- let cwd = URL(fileURLWithPath: FileManager.default.currentDirectoryPath)
- let r = VPhoneResources(base: cwd)
- // A non-existent interpreter is never usable.
- #expect(r.pythonIsUsable(URL(fileURLWithPath: "/does/not/exist/python3")) == false)
- // The dev .venv (when present) carries a modern ipsw_parser and must pass.
- let devVenv = cwd.appendingPathComponent(".venv/bin/python3")
- if FileManager.default.isExecutableFile(atPath: devVenv.path) {
- #expect(r.pythonIsUsable(devVenv) == true)
- }
+ /// A companion binary is found beside the running image, never on `PATH` —
+ /// the property that made the interpreter ladder removable.
+ @Test func siblingExecutableSitsBesideTheRunningImage() {
+ let me = VPhoneResources.runningExecutable()
+ let sibling = VPhoneResources.siblingExecutable("vphone-vm")
+ #expect(sibling.deletingLastPathComponent().path == me.deletingLastPathComponent().path)
+ #expect(sibling.lastPathComponent == "vphone-vm")
}
}
diff --git a/tests/VPhoneRestoreTests/RestoreRunnerTests.swift b/tests/VPhoneRestoreTests/RestoreRunnerTests.swift
new file mode 100644
index 00000000..9807bd5d
--- /dev/null
+++ b/tests/VPhoneRestoreTests/RestoreRunnerTests.swift
@@ -0,0 +1,183 @@
+import Foundation
+import Testing
+@testable import VPhoneRestore
+
+/// The only tests here that really call `vphone_restore_run`.
+///
+/// Every case below is one the C bridge rejects in its own argument checks,
+/// BEFORE `vphone_drive_idevicerestore` — so no USB is opened, nothing is sent
+/// to Apple, and no device is needed. What they prove is the plumbing: that the
+/// C strings survive the call, that the log callback reaches a Swift closure
+/// through `void *context`, and that a result code becomes the right typed
+/// error. None of them says a real restore works; that needs a phone in DFU.
+///
+/// `.serialized` for two reasons. The bridge allows one restore per process and
+/// answers a second with `VPHONE_RESTORE_E_BUSY`, and it redirects the
+/// process's `stdout` into itself while it runs — so anything else printing
+/// during that window arrives at the log callback instead of on the terminal.
+/// The window is a few milliseconds per case; it is still why these are not
+/// spread through the other suites.
+@Suite(.serialized)
+struct RestoreRunnerTests {
+ // MARK: - Fixtures
+
+ /// Thread-safe, because the callbacks come off idevicerestore's worker
+ /// threads and `@Sendable` is not a suggestion.
+ private final class Collector: @unchecked Sendable {
+ private let lock = NSLock()
+ private var events: [VPhoneRestoreEvent] = []
+
+ func record(_ event: VPhoneRestoreEvent) {
+ lock.lock()
+ defer { lock.unlock() }
+ events.append(event)
+ }
+
+ var messages: [String] {
+ lock.lock()
+ defer { lock.unlock() }
+ return events.compactMap { event in
+ if case let .log(_, message) = event { return message }
+ return nil
+ }
+ }
+
+ var errorMessages: [String] {
+ lock.lock()
+ defer { lock.unlock() }
+ return events.compactMap { event in
+ if case let .log(level, message) = event, level == .error { return message }
+ return nil
+ }
+ }
+ }
+
+ private func withTemporaryDirectory<R>(_ body: (URL) throws -> R) throws -> R {
+ let root = FileManager.default.temporaryDirectory
+ .appendingPathComponent("vphone-runner-\(UUID().uuidString)", isDirectory: true)
+ try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+ defer { try? FileManager.default.removeItem(at: root) }
+ return try body(root)
+ }
+
+ // MARK: - Restore directory
+
+ @Test func anAbsentRestoreDirectoryIsRejectedAndReported() throws {
+ let absent = URL(fileURLWithPath: "/nonexistent/vphone/iPhone17,3_Restore")
+ let collector = Collector()
+
+ #expect(throws: VPhoneRestoreBackendError.restoreDirectoryUnusable(absent)) {
+ try VPhoneRestoreRunner.run(
+ VPhoneRestoreOptions(restoreDirectory: absent),
+ onEvent: { collector.record($0) }
+ )
+ }
+
+ // The log callback reached Swift, and the path it names is the one that
+ // was passed — which is the whole `void *context` + strdup round trip.
+ let errors = collector.errorMessages
+ #expect(!errors.isEmpty)
+ #expect(errors.contains { $0.contains("/nonexistent/vphone/iPhone17,3_Restore") })
+ }
+
+ @Test func aFileIsNotARestoreDirectory() throws {
+ try withTemporaryDirectory { root in
+ // This build has no libzip, so a .ipsw is refused here by name
+ // rather than failing four layers down in src/ipsw.c.
+ let archive = root.appendingPathComponent("iPhone17,3_Restore.ipsw")
+ try Data("PK\u{03}\u{04}not really".utf8).write(to: archive)
+ let collector = Collector()
+
+ #expect(throws: VPhoneRestoreBackendError.restoreDirectoryUnusable(archive)) {
+ try VPhoneRestoreRunner.run(
+ VPhoneRestoreOptions(restoreDirectory: archive),
+ onEvent: { collector.record($0) }
+ )
+ }
+ #expect(collector.errorMessages.contains { $0.contains("not a directory") })
+ }
+ }
+
+ // MARK: - Ticket
+
+ @Test func anOfflineTicketThatIsNotAPlistIsRejected() throws {
+ try withTemporaryDirectory { root in
+ // A real directory, so the run gets past the restore-dir checks and
+ // into the offline-ticket loader — still without a device, because
+ // the ticket is read before idevicerestore is started at all.
+ let restoreDirectory = root.appendingPathComponent("iPhone17,3_Restore", isDirectory: true)
+ try FileManager.default.createDirectory(at: restoreDirectory, withIntermediateDirectories: true)
+ let ticket = root.appendingPathComponent("000000011A2B3C4D.shsh")
+ try Data("this is not a property list".utf8).write(to: ticket)
+ let collector = Collector()
+
+ #expect(throws: VPhoneRestoreBackendError.ticketUnreadable(ticket)) {
+ try VPhoneRestoreRunner.run(
+ VPhoneRestoreOptions(restoreDirectory: restoreDirectory, ticketPath: ticket),
+ onEvent: { collector.record($0) }
+ )
+ }
+ #expect(collector.errorMessages.contains { $0.contains(ticket.path) })
+ }
+ }
+
+ @Test func aRunWithoutACallbackIsStillSafe() throws {
+ // The default handler discards, and the C side takes NULL for the
+ // context it never uses. Nothing here may dereference it anyway.
+ let absent = URL(fileURLWithPath: "/nonexistent/vphone/iPhone17,3_Restore")
+ #expect(throws: VPhoneRestoreBackendError.restoreDirectoryUnusable(absent)) {
+ try VPhoneRestoreRunner.run(VPhoneRestoreOptions(restoreDirectory: absent))
+ }
+ }
+
+ // MARK: - The facade
+
+ @Test func fetchingASHSHStopsAtTheMissingRestoreTree() throws {
+ // `VPhoneRestoreBridge` finds the restore tree BEFORE it starts a run,
+ // so an empty bundle never reaches idevicerestore at all.
+ try withTemporaryDirectory { root in
+ #expect(throws: VPhoneRestoreBackendError.noRestoreDirectory(root)) {
+ try VPhoneRestoreBridge.fetchSHSH(vmDir: root, ecid: nil, udid: nil, out: nil)
+ }
+ }
+ }
+
+ @Test func restoringStopsAtTheMissingRestoreTree() throws {
+ try withTemporaryDirectory { root in
+ #expect(throws: VPhoneRestoreBackendError.noRestoreDirectory(root)) {
+ try VPhoneRestoreBridge.restore(
+ vmDir: root,
+ ecid: nil,
+ udid: nil,
+ erase: true,
+ ticketPath: nil
+ )
+ }
+ }
+ }
+
+ @Test func theCachedSHSHNoticeIsPrintedBeforeTheRestoreStarts() throws {
+ try withTemporaryDirectory { root in
+ // Python printed "[+] Using cached SHSH: …" the moment it loaded
+ // the blob. Users grep for that line, so it has to survive — and it
+ // has to come out even when the restore then fails.
+ let restoreDirectory = root.appendingPathComponent("iPhone17,3_Restore", isDirectory: true)
+ try FileManager.default.createDirectory(at: restoreDirectory, withIntermediateDirectories: true)
+ let ticket = root.appendingPathComponent("000000011A2B3C4D.shsh")
+ try Data("not a plist".utf8).write(to: ticket)
+ let collector = Collector()
+
+ #expect(throws: VPhoneRestoreBackendError.ticketUnreadable(ticket)) {
+ try VPhoneRestoreBridge.restore(
+ vmDir: root,
+ ecid: 0x0000_0001_1A2B_3C4D,
+ udid: nil,
+ erase: true,
+ ticketPath: ticket,
+ onEvent: { collector.record($0) }
+ )
+ }
+ #expect(collector.messages.contains("[+] Using cached SHSH: \(ticket.path)"))
+ }
+ }
+}
diff --git a/tests/VPhoneSignTests/VPhoneSignEntitlementsTests.swift b/tests/VPhoneSignTests/VPhoneSignEntitlementsTests.swift
index 8e50be10..abfda0f3 100644
--- a/tests/VPhoneSignTests/VPhoneSignEntitlementsTests.swift
+++ b/tests/VPhoneSignTests/VPhoneSignEntitlementsTests.swift
@@ -24,7 +24,7 @@ struct VPhoneSignEntitlementsTests {
var withEntitlements = 0
for source in corpus {
let theirs = try VPhoneSignLdidHarness.run(ldid, ["-e", source.path]).out
- let ours = try VPhoneSigner.entitlements(ofFileAt: source, usesExternalLdid: false)
+ let ours = try VPhoneSigner.entitlements(ofFileAt: source)
.reduce(Data(), +)
#expect(theirs == ours, "\(source.lastPathComponent): \(theirs.count) vs \(ours.count) bytes")
if !theirs.isEmpty { withEntitlements += 1 }
@@ -41,7 +41,7 @@ struct VPhoneSignEntitlementsTests {
let plist = VPhoneSignParityTests.sampleEntitlements
try VPhoneSigner.sign(fileAt: file, options: .init(identifier: "binary", entitlements: plist))
- let read = try VPhoneSigner.entitlements(ofFileAt: file, usesExternalLdid: false)
+ let read = try VPhoneSigner.entitlements(ofFileAt: file)
let slices = try VPhoneSignBlobs(fileAt: file).slices.count
#expect(read.count == slices)
// libplist rewrites the document it was given; what must survive is
diff --git a/tests/VPhoneSignTests/VPhoneSignParityTests.swift b/tests/VPhoneSignTests/VPhoneSignParityTests.swift
index f3056334..9c9cf86c 100644
--- a/tests/VPhoneSignTests/VPhoneSignParityTests.swift
+++ b/tests/VPhoneSignTests/VPhoneSignParityTests.swift
@@ -140,7 +140,7 @@ struct VPhoneSignParityTests {
let left = try Data(contentsOf: theirs), right = try Data(contentsOf: ours)
#expect(left == right, "\(name): \(VPhoneSignLdidHarness.difference(left, right))")
- if try VPhoneSigner.entitlements(ofFileAt: source, usesExternalLdid: false).isEmpty == false {
+ if try VPhoneSigner.entitlements(ofFileAt: source).isEmpty == false {
merged += 1
}
}
diff --git a/tests/VPhoneSignTests/VPhoneSignStyleTests.swift b/tests/VPhoneSignTests/VPhoneSignStyleTests.swift
index 9964134d..577f469c 100644
--- a/tests/VPhoneSignTests/VPhoneSignStyleTests.swift
+++ b/tests/VPhoneSignTests/VPhoneSignStyleTests.swift
@@ -47,70 +47,6 @@ struct VPhoneSignStyleTests {
}
}
- // MARK: - The escape hatch
-
- /// The flags `--use-ldid` hands over have to be the same request, or the
- /// fallback quietly signs something else.
- @Test("the ldid arguments match the options")
- func ldidArguments() {
- #expect(VPhoneLdid.arguments(
- for: .init(identifier: nil), entitlementsPath: nil, identityPath: nil
- ) == ["-S"])
- #expect(VPhoneLdid.arguments(
- for: .init(identifier: "com.apple.seputil", mergesExisting: true),
- entitlementsPath: nil, identityPath: "/tmp/signcert.p12"
- ) == ["-S", "-M", "-K/tmp/signcert.p12", "-Icom.apple.seputil"])
- #expect(VPhoneLdid.arguments(
- for: .init(entitlements: Data([1]), mergesExisting: true),
- entitlementsPath: "/tmp/e.plist", identityPath: nil
- ) == ["-S/tmp/e.plist", "-M"])
- }
-
- /// Handing ldid an identity it cannot see would sign ad-hoc and say
- /// nothing, which is the one way a fallback is worse than no fallback.
- @Test("--use-ldid refuses an identity it was not given the .p12 for")
- func escapeHatchRefusesAnIdentityWithoutItsFile() throws {
- try #require(VPhoneSignLdidHarness.ldid != nil, "ldid is not installed")
- let identity = try VPhoneSignIdentity(
- pkcs12: Data(contentsOf: VPhoneSignIdentityTests.p12), password: ""
- )
- let source = try #require(VPhoneSignLdidHarness.corpus.first)
- let directory = try VPhoneSignLdidHarness.temporaryDirectory()
- defer { try? FileManager.default.removeItem(at: directory) }
- let file = try VPhoneSignLdidHarness.copy(source, into: directory, as: "binary")
- #expect(throws: VPhoneSignError.self) {
- try VPhoneSigner.sign(fileAt: file, options: .init(
- identifier: "binary", identity: identity, usesExternalLdid: true
- ))
- }
- }
-
- /// Going through the external tool must land on the same file, or the
- /// fallback is not a fallback.
- @Test("--use-ldid produces what signing here produces")
- func escapeHatchAgrees() throws {
- try #require(VPhoneSignLdidHarness.ldid != nil, "ldid is not installed")
- for source in VPhoneSignLdidHarness.corpus.prefix(4) {
- let directory = try VPhoneSignLdidHarness.temporaryDirectory()
- defer { try? FileManager.default.removeItem(at: directory) }
- let name = source.lastPathComponent
-
- let viaLdid = try VPhoneSignLdidHarness.copy(source, into: directory, as: name)
- try VPhoneSigner.sign(fileAt: viaLdid, options: .init(
- identifier: name, entitlements: VPhoneSignParityTests.sampleEntitlements,
- usesExternalLdid: true
- ))
- let here = try VPhoneSignLdidHarness.copy(source, into: directory, as: "here-\(name)")
- try VPhoneSigner.sign(fileAt: here, options: .init(
- identifier: name, entitlements: VPhoneSignParityTests.sampleEntitlements,
- usesExternalLdid: false
- ))
-
- let left = try Data(contentsOf: viaLdid), right = try Data(contentsOf: here)
- #expect(left == right, "\(name): \(VPhoneSignLdidHarness.difference(left, right))")
- }
- }
-
// MARK: - Refusing rather than corrupting
@Test("a file that is not a Mach-O is refused")
diff --git a/tests/test_jb_kernel_patches.sh b/tests/test_jb_kernel_patches.sh
index a1b89dcf..a6ee8705 100755
--- a/tests/test_jb_kernel_patches.sh
+++ b/tests/test_jb_kernel_patches.sh
@@ -76,21 +76,28 @@ elif [[ -n "${BUILDS:-}" ]]; then
else
# cloudOS column entries look like `26.4-23E5207q` (version-dash-build); the
# iPhone column uses `17,3_26.5_23F77` (commas/underscores), so filter those out.
- BUILD_LIST=($(python3 - "$README" <<'PY'
-import re, sys
-seen=[]
-insec=False
-for line in open(sys.argv[1], encoding="utf-8"):
- if line.startswith("## Tested Environments"): insec=True; continue
- if insec and line.startswith("## "): break
- if not insec: continue
- for tok in re.findall(r"`([^`]+)`", line):
- m=re.fullmatch(r"\d+\.\d[\d.]*-([0-9A-Za-z]+)", tok) # 26.4-23E5207q
- if m and m.group(1) not in seen:
- seen.append(m.group(1))
-print("\n".join(seen))
-PY
-))
+ #
+ # awk, not the `python3 - <<'PY'` heredoc this was until P2.4. A bare `python3`
+ # here resolved whatever interpreter happened to be on PATH, which is the exact
+ # silent fallback the repo spent D1 removing — and it survived the venv because
+ # nothing linked it to the venv in the first place. awk ships with macOS.
+ BUILD_LIST=($(awk '
+ /^## Tested Environments/ { insec = 1; next }
+ insec && /^## / { exit }
+ !insec { next }
+ {
+ rest = $0
+ while (match(rest, /`[^`]+`/)) {
+ tok = substr(rest, RSTART + 1, RLENGTH - 2)
+ rest = substr(rest, RSTART + RLENGTH)
+ if (tok ~ /^[0-9]+\.[0-9][0-9.]*-[0-9A-Za-z]+$/) {
+ sub(/^[0-9]+\.[0-9][0-9.]*-/, "", tok)
+ if (!(tok in seen)) { seen[tok] = 1; order[++n] = tok }
+ }
+ }
+ }
+ END { for (i = 1; i <= n; i++) print order[i] }
+ ' "$README"))
fi
[[ ${#BUILD_LIST} -gt 0 ]] || { echo "[-] no cloudOS builds resolved"; exit 2; }
echo "kernel builds to test: ${BUILD_LIST[*]}"
@@ -115,34 +122,51 @@ ensure_pcc_info() {
# Resolve one cloudOS build -> its PCC "OS" asset URL (only releases that still
# carry the vphone600 firmware). Empty output => not found.
+# Also awk rather than a python3 heredoc — see the note above BUILD_LIST. The
+# release index is a flat text dump, so this walks it as blocks: a numbered
+# digest line opens one, and everything up to the next digest line belongs to
+# it. A block qualifies only if it advertises vphone firmware, carries a PCC
+# asset URL, and mentions the build we were asked about; the first qualifying
+# block wins, exactly as the reading of the whole index into a list then
+# scanning it in order did.
resolve_url() {
local build="$1"
- PCC_INFO="$PCC_INFO" python3 - "$build" <<'PY'
-import os, re, sys
-build = sys.argv[1]
-raw = open(os.environ["PCC_INFO"], encoding="utf-8", errors="replace").read()
-clean = re.sub(r"\x1b\[[0-9;]*m", "", raw)
-
-blocks, cur = [], None
-for line in clean.splitlines():
- if re.match(r"^\d+\)\s+[0-9a-f]{16,}", line):
- cur = {"vphone": False, "url": None, "builds": set()}
- blocks.append(cur)
- continue
- if cur is None:
- continue
- if "\U0001F4F1 VPHONE" in line: # 📱 VPHONE = vphone firmware present
- cur["vphone"] = True
- u = re.search(r"(https://updates\.cdn-apple\.com/private-cloud-compute/[0-9a-f]+)", line)
- if u and cur["url"] is None:
- cur["url"] = u.group(1)
- cur["builds"].update(re.findall(r"\b(2[0-9][A-Z][0-9A-Za-z]+)\b", line))
-
-for b in blocks:
- if b["vphone"] and b["url"] and build in b["builds"]:
- print(b["url"])
- break
-PY
+ awk -v want="$build" '
+ function close_block() {
+ if (!found && open && vphone && url != "" && (want in builds)) {
+ found = 1
+ print url
+ }
+ open = 0; vphone = 0; url = ""; delete builds
+ }
+ BEGIN { esc = sprintf("%c", 27) }
+ {
+ line = $0
+ gsub(esc "\\[[0-9;]*m", "", line) # ipsw colourises its output
+ }
+ # A release block opens on `<n>) <hex digest>`.
+ match(line, /^[0-9]+\)[ \t]+[0-9a-f]+/) {
+ digest = substr(line, RSTART, RLENGTH)
+ sub(/^[0-9]+\)[ \t]+/, "", digest)
+ if (length(digest) >= 16) { close_block(); open = 1; next }
+ }
+ !open { next }
+ {
+ if (index(line, "📱 VPHONE") > 0) vphone = 1 # the vphone firmware marker
+ if (url == "" \
+ && match(line, /https:\/\/updates\.cdn-apple\.com\/private-cloud-compute\/[0-9a-f]+/)) {
+ url = substr(line, RSTART, RLENGTH)
+ }
+ # Build ids (23B85, 24A5380h) as whole words. Splitting on non-word
+ # characters is what keeps `17,3_26.5_23F77` out: an id glued to its
+ # neighbours by underscores is not a word on its own.
+ k = split(line, word, /[^A-Za-z0-9_]+/)
+ for (i = 1; i <= k; i++) {
+ if (word[i] ~ /^2[0-9][A-Z][0-9A-Za-z]+$/) builds[word[i]] = 1
+ }
+ }
+ END { close_block() }
+ ' "$PCC_INFO"
}
# --- 4. Obtain kernelcache.research.vphone600 for a build -------------------