Run a virtual iPhone on an Apple Silicon Mac.
Swift
docs: name current research by subject
Lakrd318bfdff88f
diff --git a/AGENTS.md b/AGENTS.mdindex f9de2ee6..faa8a036 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -9,7 +9,7 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc- **Boot (GUI):** `vphone-cli vm launch <name>`- **Boot (DFU):** `vphone-cli vm launch <name> --dfu`- **AMFI refuses `vphone-vm`?** Use the bundled `vphone-amfi-allow` helper as shown in `Documents/Guides/host-setup.md`. Repeat after every build because it allowlists cdhashes. See Key Patterns.-- **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/Restore/p2_restore_off_python.md`.+- **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/Restore/native_restore_architecture.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 `Documents/Guides/host-setup.md`; neither is installed by this project.- **Language:** Swift 6.0 (SwiftPM), private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic). This package's own manifest is `swift-tools-version:6.0`, but the **toolchain floor is Swift 6.2**: `libcapstone-spm` declares 6.2 so that it can reach `CSetting.disableWarning` instead of `.unsafeFlags`, which is what lets it be depended on by version at all.- **Dependencies:** Host and guest SwiftPM packages resolve dependencies by URL and version; `Package.resolved` pins the full graphs. There are no git submodules. **No Python anywhere, and no Homebrew package at runtime** — see Tiers below.@@ -197,7 +197,7 @@ Research/ # Detailed firmware/patch documentation- **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 ours, and it writes heap, not code.** `vphone-amfi-allow` (`Sources/VPhoneAMFIAllow/`, this project's copy of [Lakr233/amfi-allow](https://github.com/Lakr233/amfi-allow)) puts the cdhashes of both `vphone-vm` copies into `/Library/Preferences/com.apple.security.coderequirements.plist` — a file AMFI already reads — and flips one byte of `_isRunningInternalBuild` in amfid's `AMFIRequirementsManager` singleton so it consults that file. It is an **allowlist**, scoped to the cdhashes you name; do not describe it as a global switch. The helper's `allow`, `status`, and `off` commands manage it; see `Documents/Guides/host-setup.md`. It is a **per-build** step, because a cdhash changes with every signature. It must be **arm64e** to match amfid's slice, and `Scripts/build.sh` builds it with clang. The heap write is the load-bearing detail: `vphone-letmein` and LLDB-based tools dirty an executable page, and on a host with `vm.cs_system_enforcement = 1` the kernel kills amfid for that and takes the guest with it.- **Guest launches go through `VPhoneGuestLaunchPlanner`** (`VPhoneCore`). It resolves `vphone-vm` as a sibling of the running image — never through `PATH` — checks its two PV=3 entitlements, then probes with `vphone-vm --help` 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/Restore/p2_restore_off_python.md` has the decision and the behaviour table.+- **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/Restore/native_restore_architecture.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:** `VPhoneVM/main.swift` → `VPhoneGuestApp.run()` → `NSApplication` + `VPhoneVirtualMachineAppDelegate`. Entry points hold no logic.- **Configuration:** `ArgumentParser` → `VPhoneBootCLI` (in `VPhoneCore`, parsed by both binaries) → `VPhoneVirtualMachine.Options` → `VZVirtualMachineConfiguration`.@@ -247,7 +247,7 @@ There is none, and adding any is a regression.returns nothing; that is the standing check.- There is no environment to activate and no dependency list to install. Therestore backend was the last holdout and is now `Sources/VPhoneRestore` over- two vendored C targets — see `Research/Restore/p2_restore_off_python.md`.+ two vendored C targets — see `Research/Restore/native_restore_architecture.md`.- A patch, a probe, a format reader or a device protocol belongs in Swift,where it is built, signed, gated by `Scripts/check_aux.sh` and tested witheverything else. Adding an interpreter back brings with it a provisioningdiff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.mdindex cc45e744..50761423 100644--- a/Research/0_binary_patch_comparison.md+++ b/Research/0_binary_patch_comparison.md@@ -430,7 +430,7 @@ list; P2 then deleted the list.** `requirements.txt`, `scripts/setup_venv.sh`,`scripts/pymobiledevice3_bridge.py` are all gone — the restore backend was thelast program holding any of them up, and it is `Sources/VPhoneRestore` overvendored libirecovery and idevicerestore now-(`research/restore/p2_restore_off_python.md`). No Python is tracked in this repository+(`Research/Restore/native_restore_architecture.md`). No Python is tracked in this repositoryand nothing resolves a `python3` at runtime.### Installed Componentsdiff --git a/Research/History/intg_update_status.md b/Research/History/intg_update_status.mdindex e16b3fa8..f8df69df 100644--- a/Research/History/intg_update_status.md+++ b/Research/History/intg_update_status.md@@ -20,7 +20,7 @@>> **Updated at `a908f81`**, after D2 and D3 landed. The D2/D3 rows below are> rewritten; the D4 row is not, and the detail is in-> [`d2_d3_self_containment.md`](../Host/d2_d3_self_containment.md), which is the+> [`runtime_dependency_tiers.md`](../Host/runtime_dependency_tiers.md), which is the> handover for that work — what the tiers are, what each removed program was> replaced by, what was verified against the real tool, and what is left open.@@ -52,15 +52,15 @@ is 2,396 lines against 2,410 at the branch base.| P0.5 | `VPhoneArchive` + `vphone-archive` | ✅ library, binary, tests, fingerprint tool || P0.5 | switch the archive call sites | ✅ **done at `356bec6`.** `$TAR` is gone from `cfw_install*.sh`; only `cfw-kit` still finds `gtar`, and it is build tier and does not ship || P0.5 | `VPhoneSign`, drop `ldid` | ✅ **done at `356bec6`.** The installers and the Makefile call `vphone-cli sign`; nothing looks `ldid` up any more except `cfw-kit` |-| P0.5 | admission gates | ✅ **`make check-aux`, six gates, all green, dist list empty** — see [`d2_d3_self_containment.md`](../Host/d2_d3_self_containment.md) |+| P0.5 | admission gates | ✅ **`make check-aux`, six gates, all green, dist list empty** — see [`runtime_dependency_tiers.md`](../Host/runtime_dependency_tiers.md) || **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/restore/p2_dfu_spike.md` |+| **P2.0** | can libirecovery see the virtual DFU endpoint? | ✅ **yes** — `Research/Restore/virtual_dfu_probe.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 |-`research/restore/p2_restore_off_python.md` records what P2 decided and why, including+`Research/Restore/native_restore_architecture.md` records what P2 decided and why, includingthe behaviour table row by row.That AMFI row went round in a circle in one day, so it is worth restating where@@ -112,7 +112,7 @@ Two corrections to the earlier ledger's arithmetic:>> **Now**: `zsh Scripts/check_aux.sh` reports gates 0, 1, 1b, 1c, 2 and 3 all> green, with the **dist tier's registered list empty**. See-> [`d2_d3_self_containment.md`](../Host/d2_d3_self_containment.md).+> [`runtime_dependency_tiers.md`](../Host/runtime_dependency_tiers.md).`zsh Scripts/check_aux.sh --fast`, as of the previous revision:@@ -185,7 +185,7 @@ 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/restore/p2_dfu_spike.md`.+ DFU endpoint — `Research/Restore/virtual_dfu_probe.md`.2. ~~**`vphone-letmein` end to end.**~~ **Answered, and the answer removed thetool.** With `vm.cs_system_enforcement` = 1 the patched `__TEXT` page getsamfid killed (`CODESIGNING`, "Invalid Page") and the guest dies with it.@@ -196,11 +196,11 @@ Nothing below can be done without root or a real guest.3. **The four unverified rows of the P2 behaviour table** — a real restore(online and `--offline`), `--no-erase` update-in-place, and the exit-codecontract on failure. Table and criteria in- `research/restore/p2_restore_off_python.md`. **Run these on a disposable VM**: a+ `Research/Restore/native_restore_architecture.md`. **Run these on a disposable VM**: afailed 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/restore/p2_dfu_spike.md` explicitly did not. It shows up only during+ it, so `Research/Restore/virtual_dfu_probe.md` explicitly did not. It shows up only duringan 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@@ -265,7 +265,7 @@ Recorded because they were measured, not reasoned about.`AppleMobileDeviceLibrary` ships all five of those libraries plus OpenSSL asprebuilt xcframeworks, so only libirecovery (4,629 lines) and idevicerestore(20,918, of which 1,399 are ours) are vendored. The argument is in- `research/restore/p2_restore_off_python.md`.+ `Research/Restore/native_restore_architecture.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 maindiff --git a/Research/Host/host_binary_split.md b/Research/Host/host_binary_split.mdindex 5a93f415..5a568672 100644--- a/Research/Host/host_binary_split.md+++ b/Research/Host/host_binary_split.md@@ -227,7 +227,7 @@ nothing in the tree now.**Not verified — needs root and a real guest:**1. **Whether `vphone-vm` can actually start a VM holding the entitlements- alone.** — **settled**, see `research/restore/p2_dfu_spike.md`: it booted a guest+ alone.** — **settled**, see `Research/Restore/virtual_dfu_probe.md`: it booted a guestand libirecovery saw its DFU endpoint. Everything here rested on this, andit is the one item the DFU spike closed on the way past.2. **That the instructions printed on a refusal are the ones that work**, on adiff --git a/Research/Host/d2_d3_self_containment.md b/Research/Host/runtime_dependency_tiers.mdsimilarity index 100%rename from Research/Host/d2_d3_self_containment.mdrename to Research/Host/runtime_dependency_tiers.mddiff --git a/Research/README.md b/Research/README.mdindex 821e4416..a63d63e9 100644--- a/Research/README.md+++ b/Research/README.md@@ -9,7 +9,7 @@ This directory keeps the evidence behind firmware patches, restore and the self-1. [Patch comparison](0_binary_patch_comparison.md) is the canonical per-component inventory. Its regular/dev/exp columns are historical.2. [Firmware manifest and origins](Firmware/firmware_manifest_and_origins.md) explains the hybrid firmware inputs.3. [JB kernel patch notes](Kernel/kernel_jb_patch_notes.md) and the [individual patch index](KernelJailbreakPatches/README.md) lead to the kernel evidence.-4. [Native restore design](Restore/p2_restore_off_python.md) and [self-contained runtime](Host/d2_d3_self_containment.md) explain the host migration.+4. [Native restore design](Restore/native_restore_architecture.md) and [self-contained runtime](Host/runtime_dependency_tiers.md) explain the host migration.## By subject@@ -18,8 +18,8 @@ This directory keeps the evidence behind firmware patches, restore and the self-| Firmware and boot chain | [Manifest and origins](Firmware/firmware_manifest_and_origins.md), [iBoot patches](Firmware/iboot_patches.md), [TXM full chain](Firmware/txm_fullchain_analysis.md), [TXM JB patches](Firmware/txm_jb_patches.md), [selector 24](Firmware/txm_selector24_analysis.md), [variant differences](Firmware/txm_variant_diff.md) || Kernel | [JB overview](Kernel/kernel_jb_patch_notes.md), [patcher verification](Kernel/kernel_patcher_verification.md), [FairPlay kexts](Kernel/kernel_fairplay_kexts.md), [base validation 1–5](Kernel/kernel_patch_base_first5_validation.md), [11–15](Kernel/kernel_patch_base_11_15_validation.md), [16–20](Kernel/kernel_patch_base_16_20_validation.md), [sandbox hooks](Kernel/kernel_patch_sandbox_hooks_17_26_validation.md), [individual patch notes](KernelJailbreakPatches/README.md) || Other patches and captures | [Launchd jetsam](Patches/cfw_patch_launchd_jetsam.md), [user-mode hypervisor references](Patches/hv_vmm_present_usermode_xrefs.md), [reference capture](Patches/patch_reference_capture.md) |-| Restore | [DFU probe](Restore/p2_dfu_spike.md), [in-process restore](Restore/p2_restore_off_python.md) |-| Host and archives | [Binary split](Host/host_binary_split.md), [runtime dependency tiers](Host/d2_d3_self_containment.md), [archive extraction contracts](Host/archive_extraction_contracts.md), [libarchive validation](Host/libarchive_xcframework_validation.md) |+| Restore | [DFU probe](Restore/virtual_dfu_probe.md), [in-process restore](Restore/native_restore_architecture.md) |+| Host and archives | [Binary split](Host/host_binary_split.md), [runtime dependency tiers](Host/runtime_dependency_tiers.md), [archive extraction contracts](Host/archive_extraction_contracts.md), [libarchive validation](Host/libarchive_xcframework_validation.md) || Guest interaction and VM identity | [DevMode XPC](Guest/devmode_xpc_protocol.md), [keyboard events](Guest/keyboard_event_pipeline.md), [machine identifier](Guest/machine_identifier_storage_analysis.md) || Historical project records | [Migration ledger](History/intg_update_status.md), [manifest refactoring summary](History/manifest_and_refactoring_summary.md) |diff --git a/Research/Restore/p2_restore_off_python.md b/Research/Restore/native_restore_architecture.mdsimilarity index 98%rename from Research/Restore/p2_restore_off_python.mdrename to Research/Restore/native_restore_architecture.mdindex 324b506c..98a9bf6e 100644--- a/Research/Restore/p2_restore_off_python.md+++ b/Research/Restore/native_restore_architecture.md@@ -59,7 +59,7 @@ autotools project, so the only file here that is not upstream's own bytes is`IOKit/usb/IOUSBLib.h`, upstream's `configure.ac` picks IOKit and never looksfor libusb; that is deliberate here too, because a libusb backend would put aHomebrew dylib in the link and gate 1 rejects it. It is also what-`research/restore/p2_dfu_spike.md` proved works — see below.+`Research/Restore/virtual_dfu_probe.md` proved works — see below.### `Sources/MobileRestoreCore` — idevicerestore@@ -229,7 +229,7 @@ The rows still open are **1** (only as a single invocation — see its cell),**4** (the flag is new), **6** and the tail of **7**. **Run them on a disposableVM** — a failed restore leaves the guest sitting in recovery.-### `research/restore/p2_dfu_spike.md` already settled the riskiest question+### `Research/Restore/virtual_dfu_probe.md` already settled the riskiest questionP2.0 asked whether libirecovery's IOKit path can see a Virtualization.frameworkvirtual DFU endpoint at all — pymobiledevice3 reached it through pyusb, so one@@ -267,7 +267,7 @@ comparison.## Still open**FDR equivalence.** The Python ran `Restore(..., ignore_fdr=False)`;-idevicerestore's FDR handling is internal. `research/restore/p2_dfu_spike.md` says+idevicerestore's FDR handling is internal. `Research/Restore/virtual_dfu_probe.md` saysexplicitly 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.diff --git a/Research/Restore/p2_dfu_spike.md b/Research/Restore/virtual_dfu_probe.mdsimilarity index 97%rename from Research/Restore/p2_dfu_spike.mdrename to Research/Restore/virtual_dfu_probe.mdindex c0fbfbff..4728bf99 100644--- a/Research/Restore/p2_dfu_spike.md+++ b/Research/Restore/virtual_dfu_probe.md@@ -9,7 +9,7 @@> 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/restore/p2_restore_off_python.md` has what P2 went on to do.+> `Research/Restore/native_restore_architecture.md` has what P2 went on to do.## Why it was a real question@@ -113,4 +113,4 @@ It was not, and cannot be from device enumeration alone: pymobiledevice3 ranWhether the two behave the same only shows up during an actual restore. That staysan open risk on P2.2 and must not be assumed away — it is called out here so thenext person does not read "P2.0 passed" as covering it. It is still open;-`research/restore/p2_restore_off_python.md` carries it forward.+`Research/Restore/native_restore_architecture.md` carries it forward.diff --git a/Sources/VPhoneCLI/VPhoneCLI.swift b/Sources/VPhoneCLI/VPhoneCLI.swiftindex 01ad9dfe..ec8468b8 100644--- a/Sources/VPhoneCLI/VPhoneCLI.swift+++ b/Sources/VPhoneCLI/VPhoneCLI.swift@@ -84,8 +84,8 @@ struct PatchComponentCLI: ParsableCommand {case kernelBase = "kernel-base"/// TESTING/DIAGNOSTICS ONLY — not part of any production flow./// Production JB patching runs through `patch-firmware`; this- /// standalone option exists so `tests/test_jb_kernel_patches.sh` can run the- /// JB kernel layer over a single kernelcache and dump records via --records-out.+ /// standalone option runs the JB kernel layer over a single kernelcache+ /// and dumps records via --records-out./// (txm / kernel-base, by contrast, are standalone single-component patchers.)case kernelJB = "kernel-jb"}