Run a virtual iPhone on an Apple Silicon Mac.
Swift
Retire root Makefile and preserve guest API updates
Lakre092fa0e5af4
diff --git a/AGENTS.md b/AGENTS.mdindex 64ebc0bd..2bfad794 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -40,7 +40,7 @@ See `research/` for detailed firmware pipeline, component origins, patch breakdo## Architecture```-Makefile # Single entry point — run `make help`+Package.swift # SwiftPM targets and testssources/├── vphone.entitlements # Private API entitlements (7 keys) — signed ONTO vphone-vm ONLY@@ -181,7 +181,6 @@ sources/scripts/ # Build scripts and payloads only; no runtime shell├── build.sh [b] # Compile, sign and bundle├── dist_manifest.sh [b] # Payload allowlist staged by build.sh-├── guest_binaries.mk [b] # Cross-compiles vphoned (needs the iPhoneOS SDK)├── check_aux.sh [b] # The self-containment admission gates├── setup_tools.sh [b] # Builds insert_dylib, the Mach-O byte-parity test reference├── vphoned/ # Guest SwiftNIO/IcliKit package plus native installer/keychain/camera codediff --git a/Makefile b/Makefiledeleted file mode 100644index db0d2606..00000000--- a/Makefile+++ /dev/null@@ -1,415 +0,0 @@-# ═══════════════════════════════════════════════════════════════════-# vphone-cli — Virtual iPhone boot tool-# ═══════════════════════════════════════════════════════════════════--# ─── Configuration (override with make VAR=value) ─────────────────-VM_DIR ?= vm-# Absolute VM path: handles both relative (default `vm`) and absolute-# (e.g. external SSD) VM_DIR values. `abspath` leaves absolute paths intact-# and joins relative ones against CURDIR — use this for the VM directory arg.-VM_DIR_ABS := $(abspath $(VM_DIR))-SWIFT_JOBS ?= 4-# UDID and ECID for restore operations-RESTORE_UDID ?=-RESTORE_ECID ?=--# Truth test for the boolean flags above and on the command line. One place-# owns the accepted spellings; use as $(call truthy,$(FLAG)) — it expands to-# non-empty when the flag is on. NB: this is not an emptiness test, so it is-# not a substitute for $(if $(RESTORE_UDID),…) and friends.-truthy = $(filter 1 true yes YES TRUE,$(1))--# ─── Build info ──────────────────────────────────────────────────-GIT_HASH := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")-BUILD_INFO := sources/VPhoneCore/VPhoneBuildInfo.swift--# ─── Paths ────────────────────────────────────────────────────────-SCRIPTS := scripts-# Three host binaries, and only ONE of them is entitled. vphone-cli is the-# user-facing entry point and carries nothing, so it always launches; vphone-vm-# holds the private virtualization keys and is what amfid can refuse;-# vphone-archive unpacks and packs. See sources/vphone.entitlements.-#-# Getting vphone-vm past amfid is `make amfi_allow`, which runs-# vphone-amfi-allow for this build's cdhashes. It asks for root and it is a-# per-build step. `make amfi_off` puts the machine back.-BINARY := .build/release/vphone-cli-VM_BINARY := .build/release/vphone-vm-ARCHIVE_BINARY := .build/release/vphone-archive-ASKPASS_BINARY := .build/release/vphone-ask-for-permission-# Not a SwiftPM product: SwiftPM emits arm64 and this one must be arm64e to-# read amfid's ObjC runtime. Built by clang, below and in scripts/build.sh.-AMFI_BINARY := .build/release/vphone-amfi-allow-AMFI_SOURCE := sources/vphone-amfi-allow/vphone-amfi-allow.c-PATCHER_BINARY := .build/debug/vphone-cli-BUNDLE := .build/vphone-cli.app-BUNDLE_BIN := $(BUNDLE)/Contents/MacOS/vphone-cli-BUNDLE_VM := $(BUNDLE)/Contents/MacOS/vphone-vm-BUNDLE_ARCHIVE := $(BUNDLE)/Contents/MacOS/vphone-archive-BUNDLE_ASKPASS := $(BUNDLE)/Contents/MacOS/vphone-ask-for-permission-BUNDLE_AMFI := $(BUNDLE)/Contents/MacOS/vphone-amfi-allow-INFO_PLIST := sources/Info.plist-ENTITLEMENTS := sources/vphone.entitlements-# 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--SWIFT_SOURCES := $(shell find sources -name '*.swift')--# ─── Environment — prefer project-local binaries ────────────────-export PATH := $(CURDIR)/$(TOOLS_PREFIX)/bin:$(CURDIR)/.build/release:$(PATH)--# ─── Default ──────────────────────────────────────────────────────-.PHONY: help-help:- @echo "vphone-cli — Virtual iPhone boot tool"- @echo ""- @echo "Setup (one-time):"- @echo " make setup_tools Build insert_dylib (a test reference; optional)"- @echo ""- @echo "Build:"- @echo " make build Build + sign vphone-cli"- @echo " make vphoned Cross-compile + sign vphoned for iOS"- @echo " make siblings_package Archive four optional guest components + GPU provenance"- @echo " make clean Remove build/tooling artifacts only"- @echo " Options: CLEAN_VM=1 Also remove VM_DIR=$(VM_DIR) after confirmation"- @echo " CLEAN_IPSW=1 Also remove ipsws/ after confirmation"- @echo ""- @echo "VM management:"- @echo " vphone-cli vm new <name> Create a VM bundle"- @echo " vphone-cli vm list List VM bundles"- @echo " vphone-cli vm export <name> --out <archive> Back up a VM"- @echo " vphone-cli vm import <archive> --name <name> Restore into a new VM"- @echo " make check-aux Run the self-containment admission gates"- @echo " make amfi_allow Allow THIS build's vphone-vm past amfid (asks for root)"- @echo " Re-run after every build — it allowlists cdhashes"- @echo " make amfi_status Show the allowlist and whether this host can carry one"- @echo " make amfi_off Remove the allowlist and restart amfid clean"- @echo " make boot_host_preflight Diagnose whether host can launch signed PV=3 binary"- @echo " make boot Boot VM (reads from config.plist)"- @echo " make boot_dfu Boot VM in DFU mode (reads from config.plist)"- @echo ""- @echo "Firmware pipeline:"- @echo " vphone-cli fw prepare <name> --iphone-source IPSW --cloudos-source IPSW"- @echo " Prepare a VM's restore tree from two IPSWs"- @echo " make fw_patch Patch boot chain with the JB Swift pipeline"- @echo " Options: FORCE_EXC_GUARD=1 Force the EXC_GUARD Mach-port-guard disable patch even on bases"- @echo " that don't strictly need it to boot (e.g. a 3rd-party app's"- @echo " crash-reporting SDK trips a fatal GUARD_TYPE_MACH_PORT violation)"- @echo " FRIDA=1 Opt in to the Frida Stalker kernel relaxations"- @echo ""- @echo "Restore:"- @echo " make restore_get_shsh Dump SHSH response from Apple"- @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):"- @echo " make cfw_install Install JB CFW via host mount"- @echo ""- @echo "Variables: VM_DIR=$(VM_DIR) SWIFT_JOBS=$(SWIFT_JOBS)"--# ═══════════════════════════════════════════════════════════════════-# Setup-# ═══════════════════════════════════════════════════════════════════--.PHONY: setup_tools--setup_tools:- VARIANT=$(VARIANT) zsh $(SCRIPTS)/setup_tools.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 $(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."; \- [ "$(CLEAN_VM)" = "1" ] && echo " VM directory: $(VM_DIR)/"; \- [ "$(CLEAN_IPSW)" = "1" ] && echo " IPSW cache: ipsws/"; \- printf "Also permanently delete the data listed above? [y/N] "; \- read answer; \- case "$$answer" in y|Y|yes|YES) ;; *) \- echo "[-] Destructive clean cancelled; no files removed."; \- exit 0; \- esac; \- fi; \- 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--# ═══════════════════════════════════════════════════════════════════-# Build-# ═══════════════════════════════════════════════════════════════════--.PHONY: build patcher_build bundle sign--# `sign` is phony and runs every time, deliberately. It used to live inside the-# $(BINARY) recipe, which meant make skipped it whenever the binary was newer-# than its sources — and a bare `swift build -c release`, which anyone might run,-# leaves exactly that state: a rebuilt vphone-vm with its entitlements stripped-# and an mtime that makes `make build` say "Nothing to be done". The guard below-# was written to catch that case and could not, because it was in the recipe-# that got skipped. Ad-hoc signing is idempotent and takes under a second, so-# doing it unconditionally costs nothing and closes the hole.-build: $(BINARY) sign--patcher_build: $(PATCHER_BINARY)--# Stamp the current commit into $(BUILD_INFO). Both build recipes use this, so-# the generated file's shape has one owner.-define WRITE_BUILD_INFO- @echo '// Auto-generated — do not edit' > $(BUILD_INFO)- @echo 'enum VPhoneBuildInfo { static let commitHash = "$(GIT_HASH)" }' >> $(BUILD_INFO)-endef--$(PATCHER_BINARY): $(SWIFT_SOURCES) Package.swift- @echo "=== Building vphone-cli patcher ($(GIT_HASH)) ==="- $(WRITE_BUILD_INFO)- @set -o pipefail; swift build --jobs $(SWIFT_JOBS) 2>&1 | tail -5--# One recipe produces all three host binaries — `swift build` builds every-# target anyway. Grouped targets (`&:`) would say this more precisely but need-# GNU Make 4.3, and macOS still ships 3.81, so the other two just depend on-# this one.-#-# Only vphone-vm gets the entitlements. Signing vphone-cli with them too would-# put us straight back where we started: the entry point itself unable to-# launch without an AMFI bypass already in place.-$(BINARY): $(SWIFT_SOURCES) Package.swift $(ENTITLEMENTS)- @echo "=== Building vphone-cli ($(GIT_HASH)) ==="- $(WRITE_BUILD_INFO)- @set -o pipefail; swift build -c release --jobs $(SWIFT_JOBS) 2>&1 | tail -5--sign: $(BINARY)- @echo "=== Signing ==="- @codesign --force --sign - --entitlements $(ENTITLEMENTS) $(VM_BINARY)- @codesign --force --sign - $(BINARY)- @codesign --force --sign - $(ARCHIVE_BINARY)- @codesign --force --sign - $(ASKPASS_BINARY)- @echo " signed: vphone-vm (entitled), vphone-cli, vphone-archive, vphone-ask-for-permission"- @# An unentitled vphone-vm is worse than a broken one: it launches- @# perfectly, which convinces vphone-cli's AMFI probe that nothing is- @# wrong, and only fails later trying to create a PV=3 machine. A bare- @# `swift build` leaves exactly that state behind — and leaves an mtime- @# that used to make `make build` skip this whole block, guard included.- @codesign -d --entitlements - --xml $(VM_BINARY) 2>/dev/null \- | grep -q 'com.apple.private.virtualization' \- || (echo "Error: $(VM_BINARY) is not entitled after signing." >&2; exit 1)--$(VM_BINARY) $(ARCHIVE_BINARY) $(ASKPASS_BINARY): $(BINARY)--# arm64e, because it reads amfid's ObjC runtime and has to match amfid's slice.-# An arm64 build links and then fails at run time with nothing to say, so the-# slice is asserted rather than assumed.-$(AMFI_BINARY): $(AMFI_SOURCE)- @echo "=== Building vphone-amfi-allow (arm64e) ==="- @mkdir -p $(dir $(AMFI_BINARY))- @clang -arch arm64e -O2 -framework CoreFoundation -framework Security \- -o $(AMFI_BINARY) $(AMFI_SOURCE)- @file $(AMFI_BINARY) | grep -q arm64e \- || (echo "Error: $(AMFI_BINARY) is not arm64e." >&2; exit 1)- @codesign --force --sign - $(AMFI_BINARY)- @echo " signed: vphone-amfi-allow"--# One packaging implementation: direct builds and `make bundle` stage the same resources.-bundle:- @zsh $(SCRIPTS)/build.sh--# The required guest daemon is compiled on the build machine, so running a VM-# never requires Xcode. Optional sibling components have their own package.-include $(SCRIPTS)/guest_binaries.mk--# vphoned for a live guest. This target only prepares the build artifact;-# `boot` stages it into its VM after `bundle` has completed.-.PHONY: vphoned-vphoned: $(GUEST_DIR)/vphoned $(BINARY)- @cp -f $(GUEST_DIR)/vphoned .build/vphoned.signed- @$(BINARY) sign --entitlements $(SCRIPTS)/vphoned/entitlements.plist --merge \- .build/vphoned.signed- @echo " signed → .build/vphoned.signed"--.PHONY: siblings_package-siblings_package:- @$(MAKE) --no-print-directory -C siblings package--# ═══════════════════════════════════════════════════════════════════-# VM management-# ═══════════════════════════════════════════════════════════════════--.PHONY: amfi_allow amfi_status amfi_off boot_host_preflight boot boot_dfu boot_binary_check--# Self-containment checks over the complete application bundle.-# CHECK_AUX_FAST=1 skips smoke checks for local source checks only.-.PHONY: check-aux-check-aux: bundle- @zsh $(SCRIPTS)/check_aux.sh--# vphone-vm carries the private virtualization entitlements, so amfid is the one-# thing that can refuse it. `vphone-amfi-allow` is how this project gets past-# that, and this target runs it for the binaries THIS build produced.-#-# It needs root, and it asks — it does not assume a passwordless sudo and it-# does not hold a password. It needs `Debugging Restrictions: disabled` in-# `csrutil status` as well, for task_for_pid; without it the tool says so and-# changes nothing.-#-# It depends on `bundle` because `make boot` needs BOTH copies of vphone-vm let-# through: boot_binary_check runs .build/release/vphone-vm, and the boot itself-# runs the one inside the .app. Their cdhashes differ — different signing-# identifier (`vphone-vm-<hash>` vs `com.vphone.cli`), sealed bundle resources-# on one and none on the other, and they are not even the same length — so an-# allowlist given one cdhash covers exactly half the flow. Both are passed.-#-# The paths are resolved (`pwd -P`). .build/release is a symlink to-# .build/out/Products/Release, and the requirement is evaluated against the-# vnode path, not the symlink that was typed.-amfi_allow: bundle- @set -e; \- binaries=""; \- for b in "$(CURDIR)/$(VM_BINARY)" "$(CURDIR)/$(BUNDLE_VM)"; do \- [ -f "$$b" ] || continue; \- d="$$(cd "$$(dirname "$$b")" && pwd -P)"; \- binaries="$$binaries $$d/$$(basename "$$b")"; \- done; \- if [ -z "$$binaries" ]; then \- echo "Error: $(VM_BINARY) not built — run 'make build' first." >&2; \- exit 1; \- fi; \- echo "Allowing this build past amfid (needs root):"; \- for b in $$binaries; do echo " $$b"; done; \- echo ""; \- sudo "$(CURDIR)/$(AMFI_BINARY)" allow $$binaries--# What the allowlist looks like right now, and whether the host can carry one.-# Reads only; no root.-amfi_status: $(AMFI_BINARY)- @"$(CURDIR)/$(AMFI_BINARY)" status--# Put the machine back: drops the preference and restarts amfid clean.-amfi_off:- @sudo "$(CURDIR)/$(AMFI_BINARY)" off--boot_host_preflight: build- "$(CURDIR)/$(BINARY)" host preflight--# Checks the ENTITLED binary, because that is the one amfid can refuse.-# Running `vphone-cli --help` here would prove nothing: it carries no-# entitlements and launches on any host.-define BOOT_BINARY_CHECK- @"$(CURDIR)/$(BINARY)" host preflight --quiet- @tmp_log="$$(mktemp -t vphone-boot-preflight.XXXXXX)"; \- set +e; \- "$(CURDIR)/$(VM_BINARY)" --help >"$$tmp_log" 2>&1; \- rc=$$?; \- set -e; \- if [ $$rc -ne 0 ]; then \- echo "Error: signed vphone-vm failed to launch (exit $$rc)." >&2; \- echo "Check private virtualization entitlement support and ensure SIP/AMFI are disabled on the host." >&2; \- echo "If it was SIGKILLed, amfid refused the entitlements and this build has to be" >&2; \- echo "allowed past it first. That step needs root, so it is not run for you:" >&2; \- echo " make amfi_allow" >&2; \- if [ -s "$$tmp_log" ]; then \- echo "--- vphone-cli preflight log ---" >&2; \- tail -n 40 "$$tmp_log" >&2; \- fi; \- rm -f "$$tmp_log"; \- exit $$rc; \- fi; \- rm -f "$$tmp_log"-endef--boot_binary_check: $(BINARY)- $(call BOOT_BINARY_CHECK,--assert-bootable)--boot: bundle boot_binary_check- @cp -f "$(BUNDLE)/Contents/Resources/vphoned.signed" "$(VM_DIR_ABS)/.vphoned.signed"- cd "$(VM_DIR)" && "$(CURDIR)/$(BUNDLE_BIN)" \- --config ./config.plist--boot_dfu: build boot_binary_check- cd "$(VM_DIR)" && "$(CURDIR)/$(BINARY)" \- --config ./config.plist \- --dfu--# ═══════════════════════════════════════════════════════════════════-# Firmware pipeline-# ═══════════════════════════════════════════════════════════════════--.PHONY: fw_patch--fw_patch: patcher_build- "$(CURDIR)/$(PATCHER_BINARY)" patch-firmware --vm-directory "$(VM_DIR_ABS)" \- $(if $(call truthy,$(FORCE_EXC_GUARD)),--force-exc-guard,) \- $(if $(call truthy,$(FRIDA)),--frida,)--# ═══════════════════════════════════════════════════════════════════-# Restore-# ═══════════════════════════════════════════════════════════════════--.PHONY: restore_get_shsh restore restore_offline--# Resolve ECID from RESTORE_ECID or vm/udid-prediction.txt (written by boot_dfu).-define _resolve_ecid- if [ -n "$(RESTORE_ECID)" ]; then \- ECID="$(RESTORE_ECID)"; \- elif [ -f "$(VM_DIR_ABS)/udid-prediction.txt" ]; then \- ECID=$$(grep '^ECID=' "$(VM_DIR_ABS)/udid-prediction.txt" | head -1 | cut -d= -f2); \- fi; \- if [ -z "$$ECID" ]; then \- echo "[-] Cannot resolve ECID — set RESTORE_ECID or run 'make boot_dfu' first"; \- exit 1; \- fi-endef--# 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); \- "$(CURDIR)/$(BINARY)" restore $(RESTORE_VM_ARGS) --get-shsh \- $(if $(RESTORE_UDID),--udid $(RESTORE_UDID),) \- --ecid "$$ECID"--restore: build- @$(call _resolve_ecid); \- "$(CURDIR)/$(BINARY)" restore $(RESTORE_VM_ARGS) \- $(if $(RESTORE_UDID),--udid $(RESTORE_UDID),) \- --ecid "$$ECID"--# The native restore command validates the SHSH and decrypts AEA images itself.-restore_offline: build- @$(call _resolve_ecid); \- "$(CURDIR)/$(BINARY)" restore $(RESTORE_VM_ARGS) --offline \- $(if $(RESTORE_UDID),--udid $(RESTORE_UDID),) \- --ecid "$$ECID"--# ═══════════════════════════════════════════════════════════════════-# CFW-# ═══════════════════════════════════════════════════════════════════--.PHONY: cfw_install--cfw_install: build- "$(CURDIR)/$(BINARY)" cfw install $(RESTORE_VM_ARGS) --project-root "$(CURDIR)"diff --git a/Package.swift b/Package.swiftindex 997cb48a..858b6aa4 100644--- a/Package.swift+++ b/Package.swift@@ -53,7 +53,7 @@ let package = Package(.product(name: "MachOKit", package: "MachOKit"),// The cryptex patcher re-signs what it rewrites. That used to be// three `runProcess("/opt/homebrew/bin/ldid", …)` calls, which is- // the one thing in this package that made `make check-aux` fail.+ // the one thing in this package that made `scripts/check_aux.sh` fail."VPhoneSign",// And it unpacks three archives onto the volume it is building,// which were the last three `runProcess("/usr/bin/tar", …)` calls@@ -89,7 +89,7 @@ let package = Package(// Ad-hoc and PKCS#12 Mach-O code signing, byte for byte what ldid// writes. It replaces ldid, which is the only program this project// shipped that links Homebrew (libcrypto.3, libplist-2.0.4) and so- // the only one that failed `make check-aux`. Nothing here is outside+ // the only one that failed `scripts/check_aux.sh`. Nothing here is outside// the system frameworks: CryptoKit for the hashes, Security for the// PKCS#12 and the CMS..target(@@ -109,7 +109,7 @@ let package = Package(// 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 mean a Homebrew dylib in the link, and `make check-aux`+ // backend would mean a Homebrew dylib in the link, and `scripts/check_aux.sh`// exists to keep those out..target(name: "MobileRecoveryCore",@@ -150,7 +150,7 @@ let package = Package(// top: config.h, which is what ./configure would have written, and the// libzip stub. libzip is the one PKG_CHECK_MODULES dependency with no// counterpart here, and linking Homebrew's copy would put an absolute- // path in the closure that `make check-aux` gate 1 rejects. It is only+ // path in the closure that `scripts/check_aux.sh` gate 1 rejects. It is only// reachable when reading a .ipsw archive or re-signing a .bbfw, and// this project restores from an extracted directory onto a device with// no baseband — zip.h has the full argument.@@ -253,10 +253,10 @@ let package = Package(// 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.+ // VPhoneRestore is the line that ends the venv: `restore` and+ // `vm create` 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+ // and libz inside .build/vphone-cli.app, where `scripts/check_aux.sh` gate 1// can see them..executableTarget(name: "vphone-cli",diff --git a/README.md b/README.mdindex edb746a1..c123cb8a 100644--- a/README.md+++ b/README.md@@ -43,11 +43,11 @@ Building from source needs Xcode, including its iPhoneOS SDK for vphoned:```shgit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.gitcd vphone-cli-make build+zsh scripts/build.sh.build/release/vphone-cli --help```-`make build` signs and bundles the binaries. After every rebuild, a host using the AMFI allowlist must run `make amfi_allow` again because the signed cdhash changes. See [host setup](docs/guides/host-setup.md).+`scripts/build.sh` builds, signs, and bundles the binaries. Run `swift test` for the Swift tests and `zsh scripts/check_aux.sh` for the bundle checks. After every rebuild, a host using the AMFI allowlist must allow the new signed binaries because their cdhashes change. See [host setup](docs/guides/host-setup.md).## Everyday commandsdiff --git a/docs/README.md b/docs/README.mdindex c225d9c7..2209b11a 100644--- a/docs/README.md+++ b/docs/README.md@@ -21,5 +21,5 @@ These pages give a translated overview and quick start. The English guides above- [Research index](../research/README.md) groups the patch and implementation records by subject.- [Patch inventory](../research/0_binary_patch_comparison.md) is the canonical per-component comparison.-- `make help` and `vphone-cli <group> --help` show the current command surface.-- `make check-aux` checks the bundled application's runtime dependency closure.+- `zsh scripts/build.sh` builds and bundles the application; `swift test` and `zsh scripts/check_aux.sh` run the tests and bundle checks.+- `vphone-cli <group> --help` shows the CLI command surface.diff --git a/docs/README_ja.md b/docs/README_ja.mdindex 4b26b6cc..e6bf036b 100644--- a/docs/README_ja.md+++ b/docs/README_ja.md@@ -31,8 +31,8 @@ cloudOS 26.4(`23E5207q`)との組み合わせで、iPhone17,3 の iOS 26.6.2```shgit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.gitcd vphone-cli-make build+zsh scripts/build.sh.build/release/vphone-cli host preflight```-AMFI の許可リストを使う場合、ビルドのたびに `make amfi_allow` を再実行してください。[ドキュメント一覧](README.md)から現在の手順と研究資料に進めます。詳しいガイドは現在英語です。+AMFI の許可リストを使う場合、ビルドのたびに[ホストの設定手順](guides/host-setup.md)に従って署名済み VM バイナリを再登録してください。[ドキュメント一覧](README.md)から現在の手順と研究資料に進めます。詳しいガイドは現在英語です。diff --git a/docs/README_ko.md b/docs/README_ko.mdindex 52c33f86..1cbe34ce 100644--- a/docs/README_ko.md+++ b/docs/README_ko.md@@ -31,8 +31,8 @@ cloudOS 26.4(`23E5207q`)와 함께 iPhone17,3 iOS 26.6.2(`23G90`), 27.0(`24A435````shgit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.gitcd vphone-cli-make build+zsh scripts/build.sh.build/release/vphone-cli host preflight```-AMFI 허용 목록을 사용하는 호스트에서는 빌드할 때마다 `make amfi_allow`를 다시 실행하세요. 현재 가이드와 연구 자료는 [문서 목차](README.md)에 모았습니다. 상세 가이드는 현재 영어로 제공됩니다.+AMFI 허용 목록을 사용하는 호스트에서는 빌드할 때마다 [호스트 설정 가이드](guides/host-setup.md)에 따라 서명된 VM 바이너리를 다시 허용하세요. 현재 가이드와 연구 자료는 [문서 목차](README.md)에 모았습니다. 상세 가이드는 현재 영어로 제공됩니다.diff --git a/docs/README_pt.md b/docs/README_pt.mdindex d0835738..ac09aa30 100644--- a/docs/README_pt.md+++ b/docs/README_pt.md@@ -31,8 +31,8 @@ O `.app` distribuído roda sem Homebrew, Python, Xcode ou outro ambiente de exec```shgit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.gitcd vphone-cli-make build+zsh scripts/build.sh.build/release/vphone-cli host preflight```-Se o host usar a lista de permissões AMFI, execute `make amfi_allow` novamente após cada compilação. O [índice da documentação](README.md) reúne os guias atuais e as notas de pesquisa. Os guias detalhados estão em inglês no momento.+Se o host usar a lista de permissões AMFI, autorize novamente os binários de VM assinados após cada compilação conforme o [guia de configuração do host](guides/host-setup.md). O [índice da documentação](README.md) reúne os guias atuais e as notas de pesquisa. Os guias detalhados estão em inglês no momento.diff --git a/docs/README_ru.md b/docs/README_ru.mdindex 94815f41..399b6293 100644--- a/docs/README_ru.md+++ b/docs/README_ru.md@@ -31,8 +31,8 @@ vphone-cli vm launch myphone```shgit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.gitcd vphone-cli-make build+zsh scripts/build.sh.build/release/vphone-cli host preflight```-Если хост использует список разрешений AMFI, повторяйте `make amfi_allow` после каждой сборки. Актуальные руководства и исследовательские заметки собраны в [оглавлении](README.md). Подробные руководства пока доступны на английском.+Если хост использует список разрешений AMFI, после каждой сборки заново разрешайте подписанные бинарные файлы VM по [инструкции по настройке хоста](guides/host-setup.md). Актуальные руководства и исследовательские заметки собраны в [оглавлении](README.md). Подробные руководства пока доступны на английском.diff --git a/docs/README_zh.md b/docs/README_zh.mdindex a20e03ff..6a28676f 100644--- a/docs/README_zh.md+++ b/docs/README_zh.md@@ -31,11 +31,11 @@ vphone-cli vm launch myphone```shgit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.gitcd vphone-cli-make build+zsh scripts/build.sh.build/release/vphone-cli host preflight```-采用 AMFI 白名单的宿主机,每次重编译后都要重新运行 `make amfi_allow`。详细设置见[宿主机准备](guides/host-setup.md)。+采用 AMFI 白名单的宿主机,每次重编译后都要按[宿主机准备](guides/host-setup.md)中的步骤重新允许签名后的 VM 程序。## 常用命令diff --git a/docs/guides/host-setup.md b/docs/guides/host-setup.mdindex 4837fa01..f245aa6c 100644--- a/docs/guides/host-setup.md+++ b/docs/guides/host-setup.md@@ -9,11 +9,11 @@ The VM needs an Apple Silicon Mac running macOS 15 or newer. PV=3 research guestA distributed `.app` needs no Homebrew, Python or Xcode **at runtime**. A source build needs Xcode and its iPhoneOS SDK to compile vphoned. From a source checkout:```sh-make build+zsh scripts/build.sh.build/release/vphone-cli host preflight```-Use `make build` rather than bare `swift build`: the latter does not perform the required signing and bundling. `host preflight` checks the entitled companion before any VM is started. If AMFI refuses it, the error prints the exact command for the bundled allowlist helper.+Use `scripts/build.sh` rather than bare `swift build`: the latter does not perform the required signing and bundling. `host preflight` checks the entitled companion before any VM is started. If AMFI refuses it, the error prints the bundled allowlist helper command.## Permit the entitled VM binary@@ -48,12 +48,14 @@ csrutil allow-research-guests enableAfter rebooting, allowlist the **current signed build**. In a source checkout:```sh-make amfi_allow-make amfi_status+sudo .build/release/vphone-amfi-allow allow \+ .build/release/vphone-vm \+ .build/vphone-cli.app/Contents/MacOS/vphone-vm+.build/release/vphone-amfi-allow status.build/release/vphone-cli host preflight```-`make amfi_allow` asks for administrator authentication and includes both the standalone and bundled copies of `vphone-vm`. The helper records their cdhashes in the AMFI code-requirements preference and enables amfid to consult it by changing one byte in its heap. It is scoped to these signed binaries. **Run `make amfi_allow` again after every build**, including a rebuild that only changes the signature. `make amfi_off` removes the allowlist and restarts amfid.+The helper records both `vphone-vm` cdhashes in the AMFI code-requirements preference and enables amfid to consult it by changing one byte in its heap. It is scoped to these signed binaries. **Repeat the `allow` command after every build**, including a rebuild that only changes the signature. Run `sudo .build/release/vphone-amfi-allow off` to remove the allowlist and restart amfid.For a distributed app without a source checkout, run `vphone-cli host preflight` first. If AMFI refuses the guest, its error gives the full `sudo .../vphone-amfi-allow allow .../vphone-vm` command for that installed app.diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.mdindex 53256900..9ac8b4de 100644--- a/docs/guides/troubleshooting.md+++ b/docs/guides/troubleshooting.md@@ -4,7 +4,7 @@## `vphone-vm` is killed before the VM opens-Run `vphone-cli host preflight`. The CLI is unentitled and can explain an AMFI refusal of its signed `vphone-vm` companion. If you rebuilt, the cdhash changed: run `make amfi_allow` again in the source checkout, or use the bundled helper command printed by preflight. [Host setup](host-setup.md) covers the required Recovery settings.+Run `vphone-cli host preflight`. The CLI is unentitled and can explain an AMFI refusal of its signed `vphone-vm` companion. If you rebuilt, the cdhash changed: allow the new binaries with the bundled helper as described in [host setup](host-setup.md).## `Virtualization is not available on this hardware`diff --git a/scripts/build.sh b/scripts/build.shindex 8ec49c67..b81f3c26 100755--- a/scripts/build.sh+++ b/scripts/build.sh@@ -1,15 +1,15 @@#!/bin/zsh# vphone-tier: build-# build.sh — Build, sign, and bundle vphone-cli (+ cross-compile vphoned).+# build.sh — Build, sign, and bundle vphone-cli and its guest binaries.## This is the bootstrap step that a running binary cannot do for itself:# it compiles the vphone-cli binary, signs it with the PV=3 entitlements,# wraps it in the .app bundle used for GUI boot, and cross-compiles + signs-# the vphoned guest daemon. Everything else in the project is driven by the+# vphoned and icli. Everything else in the project is driven by the# resulting `vphone-cli` binary — this script is the only build entrypoint.## Usage:-# ./scripts/build.sh # build + sign + bundle + vphoned+# ./scripts/build.sh # build + sign + bundle + guest binariesset -euo pipefailSCRIPT_DIR="${0:A:h}"@@ -23,9 +23,8 @@ cd "$PROJECT_ROOT"# vphone-ask-for-permission is the SUDO_ASKPASS helper; vphone-amfi-allow is# what gets vphone-vm past amfid.#-# `make amfi_allow` runs that last one for the binaries built below. It is a-# per-build step, not a once-per-machine one, because it allowlists cdhashes and-# those change every time anything is signed.+# The host setup guide shows how to run the helper for both signed vphone-vm+# copies. It is a per-build step because their cdhashes change when signed.BINARY=".build/release/vphone-cli"VM_BINARY=".build/release/vphone-vm"ARCHIVE_BINARY=".build/release/vphone-archive"@@ -133,16 +132,39 @@ codesign --force --sign - "$BUNDLE_AMFI"codesign --force --sign - --entitlements "$ENTITLEMENTS" "$BUNDLE_VM"echo " bundled → ${BUNDLE}"-# --- Guest binaries (cross-compiled for iOS; see scripts/guest_binaries.mk) ----# The guest daemon, because compiling it at CFW-install time would make-# Xcode a requirement for running a VM. This is the build machine; it has Xcode.-make -f scripts/guest_binaries.mk guest_binaries GIT_HASH="$GIT_HASH"+# --- Guest binaries (cross-compiled for iOS) ---+# Build vphoned and its icli dependency here so a distributed app can install+# CFW without Xcode or an iPhoneOS SDK on the destination host.+IOS_SDK="$(xcrun --sdk iphoneos --show-sdk-path)" \+ || { echo "Error: iPhoneOS SDK is required on the build machine" >&2; exit 1; }+mkdir -p .build/guest+echo "=== Building vphoned (arm64, iphoneos) ==="+GIT_HASH="$GIT_HASH" swift build --package-path scripts/vphoned \+ --scratch-path .build/vphoned-swiftpm --triple arm64-apple-ios15.0 \+ --sdk "$IOS_SDK" -c release --product vphoned \+ --jobs "${SWIFT_JOBS:-4}"+GUEST_BIN_DIR="$(swift build --package-path scripts/vphoned \+ --scratch-path .build/vphoned-swiftpm --triple arm64-apple-ios15.0 \+ --sdk "$IOS_SDK" -c release --show-bin-path)"+cp -f "$GUEST_BIN_DIR/vphoned" .build/guest/vphoned++echo "=== Building icli (arm64, iphoneos) ==="+ICLI_PACKAGE=".build/vphoned-swiftpm/checkouts/icli"+swift build --package-path "$ICLI_PACKAGE" \+ --scratch-path .build/icli-guest-swiftpm --triple arm64-apple-ios15.0 \+ --sdk "$IOS_SDK" -c release --product icli \+ --jobs "${SWIFT_JOBS:-4}"+ICLI_BIN_DIR="$(swift build --package-path "$ICLI_PACKAGE" \+ --scratch-path .build/icli-guest-swiftpm --triple arm64-apple-ios15.0 \+ --sdk "$IOS_SDK" -c release --show-bin-path)"+cp -f "$ICLI_BIN_DIR/icli" .build/guest/icli# vphoned.signed is the copy the host pushes into a running guest over vsock.echo "=== Signing vphoned ==="-cp .build/guest/vphoned .build/vphoned.signed+cp .build/guest/vphoned .build/vphoned"$BINARY" sign \--entitlements scripts/vphoned/entitlements.plist --merge \- .build/vphoned.signed+ .build/vphoned+cp .build/vphoned .build/vphoned.signedecho " signed → .build/vphoned.signed"# --- Bundle the standalone runtime mini-repo into Contents/Resources ---@@ -208,5 +230,4 @@ echo " vphoned : .build/vphoned.signed"echo ""echo "Run: ${BINARY} --help"echo "If vphone-vm is killed the moment it launches, amfid refused its entitlements."-echo "'make amfi_allow' allows this build past it; re-run it after every build,"-echo "because it allowlists cdhashes and those change with every signature."+echo "Allow the new vphone-vm signatures after each build; see docs/guides/host-setup.md."diff --git a/scripts/check_aux.sh b/scripts/check_aux.shindex f4eaad0f..a9ea4883 100755--- a/scripts/check_aux.sh+++ b/scripts/check_aux.sh@@ -79,7 +79,7 @@ typeset -a DIST_REMAINING=(# build-tier script is inside the .app, and gate 2 checks that no dist-tier# script execs one.typeset -a BUILD_ALLOWED=(- brew xcrun xcodebuild clang swift git make rsync+ brew xcrun xcodebuild clang swift git rsyncldid gtar zstd ipsw aria2c wget sshpass trustcache insert_dylib)@@ -94,8 +94,8 @@ typeset -a BUILD_ALLOWED=(# that used to be written here: it is not an external program any more.# `vphone-amfi-allow` is built from this repository's own C, ships in the# bundle, and links CoreFoundation, Security and libSystem — so gate 1 weighs it-# like everything else. What must not appear is a LOOKUP: `make amfi_allow` runs-# it by absolute path.+# like everything else. What must not appear is a PATH lookup: the bundled+# helper is invoked by its explicit path.# Programs macOS ships that the dist tier may use. This is the honest boundary# of "zero dependencies" — widening it means editing this file, which is the@@ -231,7 +231,7 @@ check_closure() {# ---------------------------------------------------------------------------# The bundler used to work from a list of EXCLUSIONS, so anything new shipped by# default. That is how the .app came to carry build.sh, check_aux.sh and-# setup_tools.sh — which runs `brew install` — alongside the scripts it actually+# setup_tools.sh alongside the scripts it actually# needs. It is an allowlist now, and this gate is what keeps it honest: a# build-tier script inside the bundle is a hard failure, because everything in# that tier is allowed to assume a toolchain the dist tier does not have.@@ -254,7 +254,7 @@ check_bundle_contents() {# Nothing may appear under Resources/scripts that the manifest did not put# there — a stale file from an older bundle is exactly as dangerous as a- # wrongly-declared one, and `make bundle` builds over whatever is already on+ # wrongly-declared one, and `scripts/build.sh` builds over whatever is already on# disk.local -a manifest=()while IFS= read -r name; do manifest+=("$name"); done \@@ -281,8 +281,8 @@ check_bundle_contents() {# `command -v python3` fallback, and a `tar --zstd` that quietly spawns a# zstd(1) from PATH. Neither shows up in gate 1.#-# The tier decides the verdict, not the program. `xcrun` in guest_binaries.mk is-# correct — that file exists to use the iPhoneOS SDK. The same `xcrun` in+# The tier decides the verdict, not the program. `xcrun` in build.sh is+# correct — that file uses the iPhoneOS SDK. The same `xcrun` in# cfw_install_jb.sh was a bug, because that script ships, and it made a full# Xcode install a prerequisite for putting firmware on a VM.check_sources() {@@ -412,19 +412,18 @@ check_sources() {## check_aux.sh excludes itself, because a scanner that looks for a word# necessarily contains it.- hits=$( { grep -rnE 'python[0-9.]*' --include='*.sh' --include='*.mk' \- scripts/ tests/ 2>/dev/null- grep -HnE 'python[0-9.]*' Makefile 2>/dev/null } \+ hits=$(grep -rnE 'python[0-9.]*' --include='*.sh' \+ scripts/ tests/ 2>/dev/null \| grep -vE '^[^:]+:[0-9]+:[[:space:]]*#' \| grep -vE '^scripts/check_aux\.sh:' \- | grep -vE '(echo|print)[[:space:]]' )+ | grep -vE '(echo|print)[[:space:]]')if [[ -n "$hits" ]]; thenwhile IFS= read -r line; do[[ -z "$line" ]] && continuefail "gate 2: interpreter reference — $line"done <<< "$hits"else- green " ok gate 2: no python reachable from any script, Makefile or test"+ green " ok gate 2: no python reachable from any script or test"fi}@@ -533,7 +532,7 @@ check_smoke() {print -P "%Bvphone-cli admission gates%b"if [[ ! -d "$BUNDLE" ]]; then- red "no bundle at $BUNDLE — run 'make bundle' first"+ red "no bundle at $BUNDLE — run 'zsh scripts/build.sh' first"exit 2fidiff --git a/scripts/dist_manifest.sh b/scripts/dist_manifest.shindex 8de0b959..53879352 100755--- a/scripts/dist_manifest.sh+++ b/scripts/dist_manifest.sh@@ -17,8 +17,8 @@# This prints the dist payload — paths relative to scripts/, one per line, for# `rsync -a --files-from=-`. It is an ALLOWLIST derived from those declarations,# which is the point: the bundler used to work from a list of exclusions, so-# anything new shipped by default and `setup_tools.sh` (which runs `brew-# install`), `build.sh` and `check_aux.sh` all ended up inside the .app. An+# anything new shipped by default and the build-only `setup_tools.sh`,+# `build.sh` and `check_aux.sh` all ended up inside the .app. An# undeclared script now ships nowhere, and says so.## Usage: dist_manifest.sh # the payload, for rsync --files-from@@ -61,6 +61,6 @@ done# repos/ toolchain submodules — build tier, sources only# ../siblings/ guest sources and GPU provenance; not copied into the# shipped app (GPU extraction runs in native fw prepare)-# vphoned/*.m *.h vendor/ Makefile same, and it is the bulk of scripts/+# vphoned/*.m *.h vendor/ same, and it is the bulk of scripts/print -r -- "vphoned/vphoned.plist" # LaunchDaemon plist, injectLaunchDaemonsprint -r -- "vphoned/entitlements.plist" # guest_sign_ent for vphoneddiff --git a/scripts/guest_binaries.mk b/scripts/guest_binaries.mkdeleted file mode 100644index 551cd5d7..00000000--- a/scripts/guest_binaries.mk+++ /dev/null@@ -1,34 +0,0 @@-# vphone-tier: build-# Compile the only guest binary shipped by the JB runtime. This runs on the-# build machine, where Xcode and the iPhoneOS SDK are allowed.--GUEST_DIR ?= .build/guest-GIT_HASH ?= unknown--.PHONY: guest_binaries guest_binaries_clean--guest_binaries: $(GUEST_DIR)/vphoned $(GUEST_DIR)/icli- @echo " guest binaries → $(GUEST_DIR)/vphoned, $(GUEST_DIR)/icli"--$(GUEST_DIR):- @mkdir -p $(GUEST_DIR)--$(GUEST_DIR)/vphoned: $(wildcard scripts/vphoned/*.m) $(wildcard scripts/vphoned/*.h) $(wildcard scripts/vphoned/Swift/*.swift) scripts/vphoned/Package.swift scripts/vphoned/Package.resolved | $(GUEST_DIR)- @xcrun --sdk iphoneos --show-sdk-path >/dev/null || (echo "Error: iPhoneOS SDK is required on the build machine" >&2; exit 1)- @$(MAKE) --no-print-directory -C scripts/vphoned GIT_HASH=$(GIT_HASH)- @cp -f scripts/vphoned/vphoned $@--# The complete icli command surface is available to the guest API without-# reimplementing its command parser or accepting shell text.-$(GUEST_DIR)/icli: $(GUEST_DIR)/vphoned- @swift build --package-path .build/vphoned-swiftpm/checkouts/icli \- --scratch-path .build/icli-guest-swiftpm --triple arm64-apple-ios15.0 \- --sdk "$$(xcrun --sdk iphoneos --show-sdk-path)" -c release --product icli \- --jobs $(or $(SWIFT_JOBS),4)- @cp "$$(swift build --package-path .build/vphoned-swiftpm/checkouts/icli \- --scratch-path .build/icli-guest-swiftpm --triple arm64-apple-ios15.0 \- --sdk "$$(xcrun --sdk iphoneos --show-sdk-path)" -c release --show-bin-path)/icli" $@--guest_binaries_clean:- @rm -rf $(GUEST_DIR)- @$(MAKE) --no-print-directory -C scripts/vphoned cleandiff --git a/scripts/setup_tools.sh b/scripts/setup_tools.shindex 8eb7e933..658f9964 100755--- a/scripts/setup_tools.sh+++ b/scripts/setup_tools.sh@@ -17,9 +17,9 @@# /System/Library/SecurityResearch. It was also the last file# in the bundle linking /opt/homebrew's libcrypto.3.#-# So: no Homebrew, no interpreter, no environment. `make build` is the toolchain.+# So: no Homebrew, no interpreter, no environment. `scripts/build.sh` builds the app.#-# Run: make setup_tools+# Run: zsh scripts/setup_tools.sh before the optional byte-parity test.set -euo pipefaildiff --git a/scripts/vphoned/Makefile b/scripts/vphoned/Makefiledeleted file mode 100644index 67df8421..00000000--- a/scripts/vphoned/Makefile+++ /dev/null@@ -1,23 +0,0 @@-# vphoned — iOS guest daemon (SwiftNIO + IcliKit + native vphone operations)--SRCS := $(wildcard *.m) $(wildcard *.h) $(wildcard Swift/*.swift) Package.swift Package.resolved-OUT := vphoned-SDK := $(shell xcrun --sdk iphoneos --show-sdk-path)-SCRATCH := $(abspath ../../.build/vphoned-swiftpm)-SWIFT_BUILD := swift build --scratch-path $(SCRATCH) --triple arm64-apple-ios15.0 --sdk $(SDK) -c release --product vphoned --jobs $(or $(SWIFT_JOBS),4)--# Passed from parent Makefile-GIT_HASH ?= unknown--.PHONY: all clean--all: $(OUT)--$(OUT): $(SRCS)- @echo "=== Building vphoned (arm64, iphoneos) ==="- GIT_HASH=$(GIT_HASH) $(SWIFT_BUILD)- @cp "$$($(SWIFT_BUILD) --show-bin-path)/vphoned" $@- @echo " built OK"--clean:- rm -f $(OUT)diff --git a/scripts/vphoned/Swift/GuestAPI.swift b/scripts/vphoned/Swift/GuestAPI.swiftindex 0f227a60..7f36a2de 100644--- a/scripts/vphoned/Swift/GuestAPI.swift+++ b/scripts/vphoned/Swift/GuestAPI.swift@@ -169,11 +169,13 @@ enum GuestAPI {case "agent.apply_update":let expected = try string(params, "sha256")let cache = "/var/root/Library/Caches/vphoned"- let data = try Data(contentsOf: URL(fileURLWithPath: cache), options: .mappedIfSafe)+ let next = cache + ".next"+ let data = try Data(contentsOf: URL(fileURLWithPath: next), options: .mappedIfSafe)let actual = SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()guard actual == expected else { throw GuestAPIError.invalidRequest("Update hash mismatch") }- guard chmod(cache, 0o755) == 0 else { throw GuestAPIError.operationFailed("Could not make update executable") }- try Data(expected.utf8).write(to: URL(fileURLWithPath: "/var/root/Library/Caches/vphoned.api-v1"), options: .atomic)+ guard chmod(next, 0o755) == 0 else { throw GuestAPIError.operationFailed("Could not make update executable") }+ guard rename(next, cache) == 0 else { throw GuestAPIError.operationFailed("Could not install update") }+ try Data(expected.utf8).write(to: URL(fileURLWithPath: "/var/root/Library/Caches/vphoned.api-v2"), options: .atomic)DispatchQueue.global().asyncAfter(deadline: .now() + 0.5) { exit(0) }return ["restarting": true]default:diff --git a/scripts/vphoned/Swift/main.swift b/scripts/vphoned/Swift/main.swiftindex b9b0536c..5a51ebc6 100644--- a/scripts/vphoned/Swift/main.swift+++ b/scripts/vphoned/Swift/main.swift@@ -44,6 +44,7 @@ do {}.bind(to: VsockAddress(cid: .any, port: 1339)).wait()+ vp_native_confirm_cached_binary()NSLog("vphoned: HTTP/WebSocket API listening on vsock 1339")try server.closeFuture.wait()} catch {diff --git a/scripts/vphoned/include/VphonedNative.h b/scripts/vphoned/include/VphonedNative.hindex 69ebc303..f455524a 100644--- a/scripts/vphoned/include/VphonedNative.h+++ b/scripts/vphoned/include/VphonedNative.h@@ -4,4 +4,5 @@/// vphone-specific operations that IcliKit does not own.NSDictionary *vp_native_api_command(NSDictionary *message);void vp_native_bootstrap_cached_binary(void);+void vp_native_confirm_cached_binary(void);void vp_vcam_start(void);diff --git a/scripts/vphoned/vphoned_native.m b/scripts/vphoned/vphoned_native.mindex d7692042..8b9b2898 100644--- a/scripts/vphoned/vphoned_native.m+++ b/scripts/vphoned/vphoned_native.m@@ -15,9 +15,10 @@ NSDictionary *vp_native_api_command(NSDictionary *message) {void vp_native_bootstrap_cached_binary(void) {static const char *cache = "/var/root/Library/Caches/vphoned";- // Pre-HTTP daemon builds also used this cache path. Their binaries lack- // the marker, so a new firmware daemon must not exec an old protocol.- static const char *marker = "/var/root/Library/Caches/vphoned.api-v1";+ // v1 cached binaries could fail before binding and put launchd in a crash+ // loop. A v2 update gets one attempt; the bundled daemon is the fallback.+ static const char *marker = "/var/root/Library/Caches/vphoned.api-v2";+ static const char *pending = "/var/root/Library/Caches/vphoned.api-v2.pending";if (access(cache, X_OK) != 0 || access(marker, R_OK) != 0) return;NSData *binary = [NSData dataWithContentsOfFile:@(cache) options:NSDataReadingMappedIfSafe error:nil];NSString *expected = [NSString stringWithContentsOfFile:@(marker) encoding:NSUTF8StringEncoding error:nil];@@ -30,7 +31,19 @@ void vp_native_bootstrap_cached_binary(void) {char current[4096];uint32_t size = sizeof(current);if (_NSGetExecutablePath(current, &size) != 0 || strcmp(current, cache) == 0) return;+ if (rename(marker, pending) != 0) return;char *const arguments[] = {(char *)cache, NULL};execv(cache, arguments);NSLog(@"vphoned: cached binary launch failed: %s", strerror(errno));}++void vp_native_confirm_cached_binary(void) {+ static const char *cache = "/var/root/Library/Caches/vphoned";+ static const char *marker = "/var/root/Library/Caches/vphoned.api-v2";+ static const char *pending = "/var/root/Library/Caches/vphoned.api-v2.pending";+ char current[4096];+ uint32_t size = sizeof(current);+ if (_NSGetExecutablePath(current, &size) != 0 || strcmp(current, cache) != 0) return;+ if (rename(pending, marker) != 0)+ NSLog(@"vphoned: could not confirm cached binary: %s", strerror(errno));+}diff --git a/siblings/README.md b/siblings/README.mdindex 66c5d540..1f456daa 100644--- a/siblings/README.md+++ b/siblings/README.md@@ -1,6 +1,6 @@# Sibling guest components-`make siblings_package` (or `make -C siblings package`) cross-compiles four+`make -C siblings package` cross-compiles fouroptional guest components with Xcode's iPhoneOS SDK and writes`.build/siblings/siblings.tar`. The archive contains signed arm64e binaries,two tweak filter plists, and the GPU provenance note:diff --git a/sources/FirmwarePatcher/Binary/InPlaceRewrite.swift b/sources/FirmwarePatcher/Binary/InPlaceRewrite.swiftindex ffc93e7c..2244ab71 100644--- a/sources/FirmwarePatcher/Binary/InPlaceRewrite.swift+++ b/sources/FirmwarePatcher/Binary/InPlaceRewrite.swift@@ -19,7 +19,7 @@// So a buffer that will be mutated and written back over its own file is READ.// Nothing that comes through here is large: these are single Mach-Os out of a// guest filesystem — launchd is 639 KB, the biggest is mobileactivationd at-// 4.6 MB — so the copy costs nothing worth having, and `make check-aux` knows+// 4.6 MB — so the copy costs nothing worth having, and `scripts/check_aux.sh` knows// this spelling is the deliberate one.import Foundationdiff --git a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swiftindex 099973ed..c5aebd45 100644--- a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift+++ b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherGuestPayload.swift@@ -97,7 +97,7 @@ extension CryptexFilesystemPatcher {/// sources shipped inside the .app — which meant installing CFW onto a VM/// required Xcode and the iPhoneOS SDK on a machine whose only job is to run/// that VM. vphoned is cross-compiled at build time now- /// (`scripts/guest_binaries.mk`) and staged into the bundle.+ /// (`scripts/build.sh`) and staged into the bundle.func stageVphoned(to vphonedBin: URL) throws {let prebuilt = try VPhoneGuestBinaries.resolve("vphoned")try FileManager.default.copyItem(at: prebuilt, to: vphonedBin)diff --git a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherSealing.swift b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherSealing.swiftindex 071de3d2..6492259e 100644--- a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherSealing.swift+++ b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherSealing.swift@@ -55,7 +55,7 @@ extension CryptexFilesystemPatcher {let iosVersion = try getProductVersion()// VPHONE_SEAL_DIR (set by the CLI's `fw prepare`/`fw patch`) must agree with// wherever fw_prepare.sh's download_apfs_sealvolume() wrote the file; unset- // (dev Makefile flow) falls back to the historical repo-relative `.tools/`.+ // (manual development flow) falls back to the historical repo-relative `.tools/`.let sealDir = ProcessInfo.processInfo.environment["VPHONE_SEAL_DIR"].map { URL(fileURLWithPath: $0) }?? vphoneCliDirectory.appending(path: ".tools")let path = sealDir.appendingPathComponent("apfs_sealvolume_\(iosVersion)")diff --git a/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift b/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swiftindex f9e4c35d..b5577aa2 100644--- a/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift+++ b/sources/FirmwarePatcher/Pipeline/FirmwarePipeline.swift@@ -4,7 +4,7 @@//// Pipeline order: AVPBooter → iBSS → iBEC → LLB → TXM → Kernel → DeviceTree//-// Variant selection (mirrors Makefile targets):+// Internal variant selection:// .regular — base patchers only// .dev — TXMDevPatcher instead of TXMPatcher// .jb — TXMDevPatcher + IBootJBPatcher (iBSS) + KernelJBPatcherdiff --git a/sources/MobileRestoreCore/zip.h b/sources/MobileRestoreCore/zip.hindex 1d3fa25e..6111cc6a 100644--- a/sources/MobileRestoreCore/zip.h+++ b/sources/MobileRestoreCore/zip.h@@ -14,7 +14,7 @@* libimobiledevice, its glue, libusbmuxd and libtatsu come from the* AppleMobileDeviceLibrary xcframeworks, and zlib and libcurl are in* /usr/lib. Linking Homebrew's libzip would put an absolute /opt/homebrew- * path in the dependency closure, which is exactly what `make check-aux`+ * path in the dependency closure, which is exactly what `scripts/check_aux.sh`* gate 1 exists to reject.** WHAT IS LOSTdiff --git a/sources/VPhoneCore/VPhoneGuestBinaries.swift b/sources/VPhoneCore/VPhoneGuestBinaries.swiftindex fed2d05c..84c4c827 100644--- a/sources/VPhoneCore/VPhoneGuestBinaries.swift+++ b/sources/VPhoneCore/VPhoneGuestBinaries.swift@@ -13,7 +13,7 @@ public enum VPhoneGuestBinaries {switch self {case let .missing(name, searched):"""- no prebuilt guest binary '\(name)'. Run 'make build'.+ no prebuilt guest binary '\(name)'. Run 'zsh scripts/build.sh'.Looked in: \(searched.map(\.path).joined(separator: ", "))"""}diff --git a/sources/VPhoneCore/VPhoneGuestLauncher.swift b/sources/VPhoneCore/VPhoneGuestLauncher.swiftindex 93ee17eb..088acda8 100644--- a/sources/VPhoneCore/VPhoneGuestLauncher.swift+++ b/sources/VPhoneCore/VPhoneGuestLauncher.swift@@ -17,7 +17,7 @@ public enum VPhoneGuestLaunchError: Error, CustomStringConvertible {return """\(name) is missing — expected it next to this binary at:\(url.path)- The install looks incomplete. Rebuild with `make build`.+ The install looks incomplete. Rebuild with `zsh scripts/build.sh`."""case let .blockedByAMFI(guest, cdHash):@@ -40,7 +40,7 @@ public enum VPhoneGuestLaunchError: Error, CustomStringConvertible {case let .missingEntitlements(guest):return """vphone-vm is missing the private PV=3 entitlements: \(guest.path)- Run `make build` to sign this binary, then allow the new signature+ Run `zsh scripts/build.sh` to sign this binary, then allow the new signaturethrough the host's AMFI policy before launching a VM."""diff --git a/sources/VPhoneCore/VPhoneSudo.swift b/sources/VPhoneCore/VPhoneSudo.swiftindex 0e1f6795..aac44e4f 100644--- a/sources/VPhoneCore/VPhoneSudo.swift+++ b/sources/VPhoneCore/VPhoneSudo.swift@@ -120,7 +120,7 @@ public enum VPhoneSudoError: Error, CustomStringConvertible {case let .helperMissing(path):"""vphone-ask-for-permission is not next to this binary (looked at \(path)).- It is built by `make build`; without it there is no way to ask for a \+ It is built by `scripts/build.sh`; without it there is no way to ask for a \password from a window session with no terminal."""}diff --git a/sources/VPhoneRestore/VPhoneRestoreIdentity.swift b/sources/VPhoneRestore/VPhoneRestoreIdentity.swiftindex 09536903..c81202e5 100644--- a/sources/VPhoneRestore/VPhoneRestoreIdentity.swift+++ b/sources/VPhoneRestore/VPhoneRestoreIdentity.swift@@ -6,7 +6,7 @@ import Foundation////// Both functions reproduce `scripts/pymobiledevice3_bridge.py` exactly —/// `parse_ecid` and `normalize_udid` — because the same strings come out of a-/// bundle's `udid-prediction.txt`, out of `make restore*`, and off users'+/// bundle's `udid-prediction.txt`, out of restore commands, and off users'/// shell histories.public enum VPhoneRestoreIdentity {// MARK: ECIDdiff --git a/sources/VPhoneRestore/VPhoneRestoreLayout.swift b/sources/VPhoneRestore/VPhoneRestoreLayout.swiftindex 76c75405..c69cbae9 100644--- a/sources/VPhoneRestore/VPhoneRestoreLayout.swift+++ b/sources/VPhoneRestore/VPhoneRestoreLayout.swift@@ -5,7 +5,7 @@ import Foundation/// Where a restore's files sit inside a VM bundle.////// Both rules here come from `scripts/pymobiledevice3_bridge.py` and both are-/// load-bearing: `make restore_offline`, `vphone-cli restore --offline` and the+/// load-bearing: `vphone-cli restore --offline` and the/// `vm create` orchestrator all find the `.shsh` by the name this produces.public enum VPhoneRestoreLayout {// MARK: Restore directorydiff --git a/sources/VPhoneVMKit/Guest/VPhoneAPIProxy.swift b/sources/VPhoneVMKit/Guest/VPhoneAPIProxy.swiftindex d6e3c0b4..caa0fbf9 100644--- a/sources/VPhoneVMKit/Guest/VPhoneAPIProxy.swift+++ b/sources/VPhoneVMKit/Guest/VPhoneAPIProxy.swift@@ -83,6 +83,7 @@ private final class GuestSocketProvider: @unchecked Sendable {Task { @MainActor inswitch result {case .failure(let error):+ print("[api] guest connection failed: \(error)")promise.fail(error)case .success(let connection):let fd = dup(connection.fileDescriptor)@@ -105,6 +106,7 @@ private final class GuestSocketProvider: @unchecked Sendable {case .success:host.setOption(ChannelOptions.autoRead, value: true).cascade(to: promise)case .failure(let error):+ print("[api] guest relay failed: \(error)")promise.fail(error)}}diff --git a/sources/VPhoneVMKit/Guest/VPhoneControl.swift b/sources/VPhoneVMKit/Guest/VPhoneControl.swiftindex 40b04130..5696ba1c 100644--- a/sources/VPhoneVMKit/Guest/VPhoneControl.swift+++ b/sources/VPhoneVMKit/Guest/VPhoneControl.swift@@ -83,7 +83,7 @@ final class VPhoneControl {if hash != info["binary_hash"] as? String {print("[control] updating vphoned over HTTP...")try await createDirectory(path: "/var/root/Library/Caches")- try await uploadFile(path: "/var/root/Library/Caches/vphoned", data: data)+ try await uploadFile(path: "/var/root/Library/Caches/vphoned.next", data: data)_ = try await call("agent.apply_update", params: ["sha256": hash])setDisconnected()return@@ -98,6 +98,7 @@ final class VPhoneControl {onConnect?(guestCaps)}} catch {+ if !isConnected { print("[control] probe failed: \(error)") }setDisconnected()}}diff --git a/sources/vphone-amfi-allow/vphone-amfi-allow.c b/sources/vphone-amfi-allow/vphone-amfi-allow.cindex 8877e827..bae8664d 100644--- a/sources/vphone-amfi-allow/vphone-amfi-allow.c+++ b/sources/vphone-amfi-allow/vphone-amfi-allow.c@@ -8,8 +8,8 @@// only local changes are this header and the usage text.//// It exists because vphone-vm is the one binary here that holds-// com.apple.private.* entitlements, and amfid refuses it. `make amfi_allow`-// runs the allow step for the binaries the current build just produced. Their+// com.apple.private.* entitlements, and amfid refuses it. The bundled helper+// allows the binaries the current build just produced. Their// cdhashes change every time they are signed, so that is a per-build step, not// a once-per-machine one.//@@ -617,6 +617,6 @@ int main(int argc, char **argv) {" sudo vphone-amfi-allow allow [--hold N] <binary> [<binary>...]\n"" sudo vphone-amfi-allow off\n""\n"- "'make amfi_allow' runs the allow step for the current build.\n");+ "Allow both signed vphone-vm copies after each build.\n");return 2;}diff --git a/sources/vphone-cli/VPhoneCreateOrchestrator.swift b/sources/vphone-cli/VPhoneCreateOrchestrator.swiftindex 546979c9..ac4441fa 100644--- a/sources/vphone-cli/VPhoneCreateOrchestrator.swift+++ b/sources/vphone-cli/VPhoneCreateOrchestrator.swift@@ -98,7 +98,7 @@ public struct VPhoneCreateOrchestrator {let v = options.verbosity// Fail fast on a nested-VM host — PV=3 guest boot can't nest, and the whole// create pipeline (download + patch + restore) is wasted otherwise. Mirrors- // the boot_host_preflight gate that `make boot` applied.+ // the host preflight that precedes VM launch.if Self.isNestedVMHost() {throw VPhoneCreateError.nestedVirtualization}diff --git a/sources/vphone-cli/VPhoneFWAEACLI.swift b/sources/vphone-cli/VPhoneFWAEACLI.swiftindex 319cfadc..5d7794fa 100644--- a/sources/vphone-cli/VPhoneFWAEACLI.swift+++ b/sources/vphone-cli/VPhoneFWAEACLI.swift@@ -4,7 +4,7 @@// fw_prepare.sh, and they are the last of them. `ipsw` is a fine program —// statically linked Go, nothing but system libraries — but it is a program the// user has to install with Homebrew before a .app that is supposed to be-// self-contained can finish a job, which is the thing `make check-aux` exists+// self-contained can finish a job, which is the thing `scripts/check_aux.sh` exists// to stop.//// ipsw fw aea --key <f> -> vphone-cli fw aea-key <f>diff --git a/tests/VPhoneSignTests/VPhoneSignFixtures.swift b/tests/VPhoneSignTests/VPhoneSignFixtures.swiftindex f003f559..6b8d2579 100644--- a/tests/VPhoneSignTests/VPhoneSignFixtures.swift+++ b/tests/VPhoneSignTests/VPhoneSignFixtures.swift@@ -78,7 +78,7 @@//// Adding a live `ldid` call back — a `which`, a hardcoded Homebrew path, an// environment variable — is the same regression the "Python" section of-// AGENTS.md forbids for an interpreter: a dependency `make check-aux` cannot+// AGENTS.md forbids for an interpreter: a dependency `scripts/check_aux.sh` cannot// see, and a silent skip when it is missing.import CryptoKit