Run a virtual iPhone on an Apple Silicon Mac.
Swift
docs: describe the split, and stop promising an allowlist we cannot deliver
Lakr86d2b508bf82
diff --git a/AGENTS.md b/AGENTS.mdindex 66dd50f6..2d4fba28 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -47,27 +47,36 @@ See `research/` for detailed firmware pipeline, component origins, patch breakdoMakefile # Single entry point — run `make help`sources/-├── vphone.entitlements # Private API entitlements (5 keys)-└── vphone-cli/ # Swift 6.0 executable (pure Swift, no ObjC)- ├── main.swift # Entry point — NSApplication + AppDelegate+├── vphone.entitlements # Private API entitlements (7 keys) — signed ONTO vphone-vm ONLY+│+├── vphone-cli/ # Entry point. NO entitlements, so it always launches.+│ │ # Argument parsing + orchestration; spawns the others.+│ ├── main.swift # Parses, and forwards `boot` to vphone-vm+│ ├── VPhoneCLI.swift # Root command, patch-firmware/patch-component+│ ├── VPhoneFWCLI.swift # Firmware subcommands+│ ├── VPhoneSetupCLI.swift # Setup subcommands+│ ├── VPhoneRestoreCLI.swift # Restore subcommands+│ ├── VPhoneVMCLI.swift # VM subcommand group+│ ├── VPhoneVMCreateCLI.swift # VM create+│ ├── VPhoneVMLaunchCLI.swift # VM launch+│ ├── VPhoneVMTransferCLI.swift # VM transfer+│ ├── VPhoneCreateOptions.swift # Create-flow option set+│ ├── VPhoneCreateOrchestrator.swift # Native `vm create` pipeline driver+│ ├── VPhoneFirmwareSelection.swift # Interactive firmware picker+│ ├── VPhoneVMSelection.swift # Interactive VM picker+│ └── VPhoneProgressBar.swift # Terminal progress rendering+│+├── vphone-vm/ # The ONLY entitled binary — a parse and a run loop+│ └── main.swift # VPhoneBootCLI.parseOrExit() → VPhoneGuestApp.run()+│+├── vphone-letmein/ # Opens a short AMFI window so vphone-vm can exec+│ └── main.c # Plain C; Foundation + libobjc only+│+└── VPhoneVMKit/ # Everything that touches a running guest+ ├── VPhoneGuestApp.swift # NSApplication wiring (keeps the entry point logic-free)├── VPhoneAppDelegate.swift # App lifecycle, SIGINT, VM start/stop- ├── VPhoneBuildInfo.swift # Auto-generated build-time commit hash├── VPhoneHostControl.swift # Unix-socket automation server (one JSON line in/out)- │- ├── CLI/ # ArgumentParser command tree + interactive pickers- │ ├── VPhoneCLI.swift # Root command and global options- │ ├── VPhoneFWCLI.swift # Firmware subcommands- │ ├── VPhoneSetupCLI.swift # Setup subcommands- │ ├── VPhoneRestoreCLI.swift # Restore subcommands- │ ├── VPhoneVMCLI.swift # VM subcommand group- │ ├── VPhoneVMCreateCLI.swift # VM create- │ ├── VPhoneVMLaunchCLI.swift # VM launch- │ ├── VPhoneVMTransferCLI.swift # VM transfer- │ ├── VPhoneCreateOptions.swift # Create-flow option set- │ ├── VPhoneCreateOrchestrator.swift # Native `vm create` pipeline driver- │ ├── VPhoneFirmwareSelection.swift # Interactive firmware picker- │ ├── VPhoneVMSelection.swift # Interactive VM picker- │ └── VPhoneProgressBar.swift # Terminal progress rendering+ ├── VPhoneBootCLI+VirtualMachine.swift # resolveOptions() — the half that needs Virtualization│├── VM/ # VM core│ ├── VPhoneVirtualMachine.swift # @MainActor VM configuration and lifecycle@@ -79,8 +88,7 @@ sources/│ ├── VPhoneControl.swift # Host-side vsock client for vphoned (length-prefixed JSON)│ ├── VPhoneControlApps.swift # Installed apps — list and launch│ ├── VPhoneControlKeychain.swift # Keychain dump- │ ├── VPhoneControlSystem.swift # Device, battery, location, devmode- │ └── VPhoneInstallPackage.swift # Package installation over vsock+ │ └── VPhoneControlSystem.swift # Device, battery, location, devmode│├── Interface/ # Window & UI│ ├── VPhoneWindowController.swift # @MainActor VM window management + toolbar@@ -147,9 +155,11 @@ research/ # Detailed firmware/patch documentation### Key Patterns+- **Three host binaries, one of them entitled.** `vphone-cli` carries no entitlements, so it launches on any host and is always there to explain what is wrong. `vphone-vm` holds all 7 private keys and is the only thing amfid can refuse. `vphone-letmein` opens a window when it does. **Do not sign `vphone-cli` with entitlements** — that is how it used to be, and it is why the entry point could not start without a bypass already running.+- **Guest launches go through `VPhoneGuestLaunchPlanner`** (`VPhoneCore`). It resolves `vphone-vm` as a sibling of the running image — never through `PATH` — and decides once per command whether an AMFI window is needed, by running `vphone-vm --help` and looking for SIGKILL. Never spawn the guest directly.- **Private API access:** Via [Dynamic](https://github.com/mhdhejazi/Dynamic) library (runtime method dispatch from pure Swift). No ObjC bridge.-- **App lifecycle:** `main.swift` → `NSApplication` + `VPhoneAppDelegate`. CLI args parsed before run loop. AppDelegate drives VM start/window/shutdown.-- **Configuration:** `ArgumentParser` → `VPhoneVirtualMachine.Options` → `VZVirtualMachineConfiguration`.+- **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`.- **Guest daemon (vphoned):** ObjC daemon inside iOS VM, vsock port 1337, length-prefixed JSON protocol. Host side is `VPhoneControl` with auto-reconnect.- **Menu system:** `VPhoneMenuController` + per-menu extensions (Keys, Type, Location, Connect, Install, Record).- **File browser:** SwiftUI (`VPhoneFileBrowserView` + `VPhoneFileBrowserModel`) in `NSHostingController`. Search, sort, upload/download, drag-drop via `VPhoneControl`.diff --git a/README.md b/README.mdindex 22212fe8..1c09736b 100644--- a/README.md+++ b/README.md@@ -137,7 +137,7 @@ Then reboot into macOS and set the AMFI boot-arg (needs SIP fully off to take efsudo nvram boot-args="amfi_get_out_of_my_way=1 -v" # reboot after```-**Option B — keep SIP on (debug-only relaxed), then allowlist the binary with amfidont** (leaves AMFI enabled system-wide).+**Option B — keep SIP on (debug-only relaxed) and let `vphone-cli` open a window per launch** (leaves AMFI enabled the rest of the time).In Recovery:@@ -146,12 +146,30 @@ csrutil enable --without debugcsrutil allow-research-guests enable```-Then reboot into macOS and:+Then reboot into macOS. There is nothing else to set up: `vphone-cli` carries+no entitlements and always launches, so when it starts a guest it notices that+amfid will not accept `vphone-vm`, opens a window with `vphone-letmein` (one+sudo prompt), and closes it once the guest is running.++To do it by hand — worth it while working on `vphone-vm`, where one sudo beats+a prompt per run:```bash-vphone-amfidont # .build/vphone-cli.app/Contents/Resources/vphone-amfidont for local builds+make letmein # open (sudo)+make letmein_status # check+make letmein_off # close```+> **Be honest about what this does.** It is a global switch, not an allowlist:+> while the window is open, amfid reports *every* signature it checks as valid+> and Apple-signed. That cannot be narrowed to one path or one binary — a+> per-validation decision needs Apple-private debugger entitlements. What can+> be narrowed is time, which is why the automatic path holds the window only+> for the length of one launch. It is also memory-only: a reboot clears it.+>+> `vphone-letmein` replaces the old `amfidont` helper, which was a pip package+> and is no longer used.+## Tested Environments| Host | iPhone | CloudOS |@@ -179,7 +197,7 @@ vphone-amfidont # .build/vphone-cli.app/Contents/Resources/vphone-amfido## FAQ-**`zsh: killed ./vphone-cli`** — AMFI/debug restrictions aren't bypassed; see [Prerequisites](#prerequisites) (`amfi_get_out_of_my_way=1` or `amfidont`).+**`zsh: killed ./vphone-vm`** — AMFI/debug restrictions aren't bypassed; see [Prerequisites](#prerequisites) (`amfi_get_out_of_my_way=1`, or let `vphone-cli` open a window for you). Note this cannot happen to `vphone-cli` itself: it carries no entitlements, so if *it* is being killed, something else is wrong.**`Virtualization is not available on this hardware`** — your Mac is itself a VM; PV=3 guest boot can't nest. Use a non-nested macOS 15+ host.diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.mdindex c51be030..b94cebd8 100644--- a/research/0_binary_patch_comparison.md+++ b/research/0_binary_patch_comparison.md@@ -787,7 +787,8 @@ cache rebuild.- it can attach to `/usr/libexec/amfid`- the initial path allow rule failed because `AMFIPathValidator` reports URL-encoded paths (`/Volumes/My%20Shared%20Files/...`)- rerunning `amfidont` with the encoded project path and the release-binary CDHash allows the signed release `vphone-cli` to launch- - this workflow is now packaged as `make amfidont_allow_vphone` / `scripts/start_amfidont_for_vphone.sh`+ - this workflow was packaged as `make amfidont_allow_vphone` / `scripts/start_amfidont_for_vphone.sh`+ - **superseded 2026-09-23.** `amfidont` is gone, and so is the path/CDHash allowlist it provided — on macOS 26 amfid carries `com.apple.developer.hardened-process`, which gates the debugger operations a per-validation decision needs. `vphone-letmein` replaces it with a global switch held open only for the length of one launch, and `vphone-cli` (now unentitled, so it always starts) drives that itself. The URL-encoding detail above no longer applies: nothing matches on paths any more. See `sources/vphone-letmein/main.c`.- With launch policy bypassed, `make boot_dfu` advances into VM setup, emits `vm/udid-prediction.txt`, and then fails with `VZErrorDomain Code=2 "Virtualization is not available on this hardware."`- `VPhoneAppDelegate` startup failure handling was tightened so these fatal boot/DFU startup errors now exit non-zero; `make boot_dfu` now reports `make: *** [boot_dfu] Error 1` for the nested-virtualization failure instead of incorrectly returning success.- The host itself is a nested Apple VM (`Model Name: Apple Virtual Machine 1`, `kern.hv_vmm_present=1`), so the remaining blocker is lack of nested Virtualization.framework availability rather than firmware patching or AMFI bypass.diff --git a/research/host_binary_split.md b/research/host_binary_split.mdnew file mode 100644index 00000000..3d310934--- /dev/null+++ b/research/host_binary_split.md@@ -0,0 +1,144 @@+# The host binary split: vphone-cli / vphone-vm / vphone-letmein++> 2026-09-23, branch `vphone-intg-update`.+> Supersedes the single-executable layout and the `amfidont` helper.++## The problem it solves++All seven private entitlements used to be signed onto `vphone-cli` — the binary+a user types. amfid will not accept Apple-private entitlements on an ad-hoc+signature, so the kernel killed the entry point at exec. `vphone-cli --help`+printed nothing and exited 137.++That is a chicken-and-egg: the tool could not run in order to arrange the+conditions under which it could run. The only way out was to leave a bypass+daemon running all the time, so that every process on the machine was being+told that every signature was valid, for as long as the machine was up.++## The shape now++| binary | entitlements | what it is |+| --- | :---: | --- |+| `vphone-cli` | **none** | argument parsing and orchestration. Launches anywhere. |+| `vphone-vm` | **all 7** | a parse and an `NSApplication` run loop over `VPhoneVMKit`. |+| `vphone-letmein` | none (needs root) | opens an AMFI window. Plain C. |++`vphone-cli` is now always able to start, which is what lets it do something+about amfid instead of being the thing amfid stops. When it is asked for a+guest it hands the boot to `vphone-vm`, opening a window around the exec if it+has to and closing it immediately after.++The compensating control moved from **scope** to **time**. The old helper+claimed a path/CDHash allowlist; that is not reproducible on macOS 26, because+deciding per-validation means interrupting amfid, and amfid carries+`com.apple.developer.hardened-process`, which gates exactly those debugger+operations behind Apple-private entitlements. So the switch is global while it+is open — and the answer is to keep it open for one exec rather than all day.++**Do not describe `vphone-letmein` as scoped to a binary or a path.** It is not.++## Why the split was cheap++The CLI/VM boundary was already a process boundary. `vm launch` and four sites+in the create orchestrator all spawned the running executable through+`VPhoneResources.runningExecutable()`. The change is mostly *what* they spawn.++## Things that are easy to get wrong++### `Bundle.main.executableURL` cannot find this process any more++It reads `CFBundleExecutable`, which is now `vphone-vm`. Ask it while running+`vphone-cli` — in the same `Contents/MacOS` — and it answers `vphone-vm`.+`runningExecutable()` uses `_NSGetExecutablePath`, which is the path the kernel+exec'd and owes nothing to any plist.++### `CFBundleExecutable` is `vphone-vm`, deliberately++The `.app` is never opened through Launch Services; every caller runs a binary+inside it directly. It exists to give the process that becomes an+`NSApplication` a bundle — icon, `LSUIElement`, the `NSLocation*UsageDescription`+strings. That process is `vphone-vm`.++### An unentitled `vphone-vm` is worse than a broken one++It launches perfectly. The AMFI probe therefore concludes nothing is wrong, the+boot proceeds, and it fails much later trying to create a PV=3 machine — far+from the cause. A bare `swift build -c release` leaves exactly that state+behind, because only `make build` / `scripts/build.sh` sign. Both now verify+the entitlements actually landed and fail if they did not. This was found by+walking into it.++### Bridged networking nearly broke silently++`availableBridgeInterfaces()` returns an empty list without+`com.apple.vm.networking` — which `vphone-cli` no longer has. The old code read+that as "this host has no bridgeable interfaces" and rejected `--network+bridged` on a machine full of them. An empty list is now treated as *cannot+tell*: the requested name is recorded and `vphone-vm`, which is entitled,+validates it at boot where the error can name the real problem. With no name+given and nothing to enumerate, `bridgeInterfaceMustBeNamed` says so.++This is the general hazard of the split — **anything that read host state+through an entitled API from the CLI side is now reading it unprivileged.**+Nothing else in `VPhoneCore` does, but new code might.++## The probe++`vphone-vm --help`. amfid decides at exec, before any of the target's own code+runs, so a `--help` that never prints is the same refusal a real boot would+hit. It costs nothing and touches no VM state. A refusal is `SIGKILL`, which+Foundation reports as termination status 9. Any *other* non-zero exit is raised+rather than escalated into a sudo prompt — we only ask for root on the one+signature we recognise.++`VPHONE_LETMEIN=auto|always|never`, and `--let-me-in` on `vm launch`. `never`+still probes: it means "do not open a window", not "do not tell me why", and+skipping the probe would hand the user a bare exit 9 with no explanation, which+is the failure this path exists to remove.++## `--hold` changed meaning++Upstream `exec --hold N` restored the patch after N seconds and returned+immediately, leaving the child running. That loses the guest's exit status and+every signal path to it, so `vphone-cli` could not report or cancel a boot.++Now `--hold N` restores after N seconds and *keeps supervising*: the window is+still only one launch long, but the guest's exit status and signals still reach+the caller. The old behaviour is `--hold N --detach`. `SIGINT`/`SIGTERM`/`SIGHUP`+are also forwarded to the child before the supervisor leaves — without that, a+Ctrl-C took down the supervisor and left the guest parentless, which looks+exactly like a hang.++## Verified, and not++**Verified on 2026-09-23** (AMFI window closed, no sudo available):++| | |+| --- | --- |+| `vphone-cli` entitlements | 0 keys |+| `vphone-vm` entitlements | 7 keys |+| `vphone-cli --help` | exits 0 and prints |+| `vphone-vm --help` | exits 137 — amfid refuses it, as expected |+| probe + `VPHONE_LETMEIN=never` | reports the refusal in full, never touches sudo |+| probe + `auto` | builds `sudo …/vphone-letmein exec --hold 10 -- …/vphone-vm --config …`, confirmed in the process tree |+| sibling resolution | resolves through the `.build/release` symlink to the real `Products/Release` directory |+| entitlement guard | fails as required on an unentitled binary |+| `VPhoneCoreTests` | 130/130 |+| `vphone-letmein` | builds `-Wall -Wextra` clean; `otool -L` shows only Foundation, libSystem, libobjc |++**Not verified — needs root and a real guest:**++1. **Whether `vphone-vm` can actually start a VM holding the entitlements+ alone.** Everything here rests on it. Nothing about the split is proven+ until a guest boots.+2. **`--hold 10` — is 10 seconds right?** A guess. Too short and the exec is+ still being validated when the window shuts; too long and it is open for no+ reason. Measure it.+3. **The `auto` path end to end**, including the sudo prompt, `--hold`+ restoring while the guest keeps running, and Ctrl-C reaching the guest.+4. **Location and TouchID**, which depend on TCC attributing the usage strings+ to `vphone-vm`. It is `CFBundleExecutable`, so it should — but TCC's view of+ a binary inside someone else's bundle is worth confirming rather than+ assuming.+5. **Bridged networking**, now that the name is validated at boot instead of at+ config time.