Run a virtual iPhone on an Apple Silicon Mac.
Swift
Run bundle validation as part of VPhone build
Lakre5460ff087d3
diff --git a/AGENTS.md b/AGENTS.mdindex 53b342db..8f82fec9 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -5,7 +5,7 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc## Quick Reference- **Build:** `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone -configuration Debug -destination 'platform=macOS,arch=arm64' -derivedDataPath .build/XcodeBundle build`-- **Test:** Run the Xcode test schemes in their owning projects; then `zsh Scripts/check_aux.sh`+- **Test:** Run the Xcode test schemes in their owning projects. The `VPhone` build validates the finished bundle.- **Boot (GUI):** `vphone-cli vm launch <name>`- **Boot (DFU):** `vphone-cli vm launch <name> --dfu`- **AMFI refuses `vphone-vm`?** Use the bundled `VPhoneEscalator` allowlist tool as shown in `Documents/Guides/host-setup.md`. Repeat after the VM cdhash changes.@@ -13,7 +13,7 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc- **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 in handwritten Xcode projects, private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic).- **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.-- **Tiers.** The build machine may use Xcode and build tools. The shipped `VPhone.bundle` must use only system libraries and its own contents at runtime. Guest components run inside the VM. `Scripts/check_aux.sh` checks bundle admission.+- **Tiers.** The build machine may use Xcode and build tools. The shipped `VPhone.bundle` must use only system libraries and its own contents at runtime. Guest components run inside the VM. `Build/ValidateBundle.sh` checks bundle admission as part of the `VPhone` build.## Workflow Rules@@ -101,10 +101,10 @@ There is none, and adding any is a regression.restore backend was the last holdout and is now `VPhoneExecutable/VPhoneCommand/VPhoneRestore` overtwo 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 with+ where it is built, signed, gated by `Build/ValidateBundle.sh` and tested witheverything else. Adding an interpreter back brings with it a provisioningstep, a silent system-`python3` fallback, and a dependency closure- `Scripts/check_aux.sh` cannot see.+ `Build/ValidateBundle.sh` cannot see.- There is no counter-example left. `amfidont` used to be cited as one — athird-party tool the user installed into their own Python — and it is gonetoo: the AMFI allowlist tool is `VPhoneExecutable/VPhoneEscalator`, one Cdiff --git a/Documents/Guides/bundle-integration.md b/Documents/Guides/bundle-integration.mdindex f1b86bf1..1a899750 100644--- a/Documents/Guides/bundle-integration.md+++ b/Documents/Guides/bundle-integration.md@@ -30,11 +30,10 @@ launching it. The VM library and caches stay outside `VPhone.bundle`, underworkstation process can access them, including after a root-run create.Guest filesystem permissions inside `Disk.img` retain their own semantics.-Build and inspect:+Build and validate:```shxcodebuild -workspace VPhone.xcworkspace -scheme VPhone \-configuration Debug -destination 'platform=macOS,arch=arm64' \-derivedDataPath .build/XcodeBundle build-zsh Scripts/check_aux.sh .build/XcodeBundle/Build/Products/Debug/VPhone.bundle```diff --git a/Documents/README.md b/Documents/README.mdindex 630a7167..3a33daae 100644--- a/Documents/README.md+++ b/Documents/README.md@@ -21,5 +21,5 @@ These pages give a translated overview and quick start. The guides above hold th- [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.-- `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build` produces `VPhone.bundle`; run each project's test scheme and `zsh Scripts/check_aux.sh` for bundle checks.+- `xcodebuild -workspace VPhone.xcworkspace -scheme VPhone build` produces and validates `VPhone.bundle`; run each project's test scheme separately.- `vphone-cli <group> --help` shows the CLI command surface.diff --git a/Documents/README_ja.md b/Documents/README_ja.mdindex ac01eb6e..ffcd99a6 100644--- a/Documents/README_ja.md+++ b/Documents/README_ja.md@@ -42,7 +42,8 @@ cd vphone-clixcodebuild -workspace VPhone.xcworkspace -scheme VPhone \-configuration Debug -destination 'platform=macOS,arch=arm64' \-derivedDataPath .build/XcodeBundle build-zsh Scripts/check_aux.sh```+ビルド中に生成された `VPhone.bundle` が自動で検証されます。+AMFI の許可リストを使う場合、ビルドのたびに[ホストの設定手順](Guides/host-setup.md)に従って署名済み VM バイナリを再登録してください。[ドキュメント一覧](README.md)から現在の手順と研究資料に進めます。詳しいガイドは現在英語です。diff --git a/Documents/README_ko.md b/Documents/README_ko.mdindex c72f710b..68f9bcc7 100644--- a/Documents/README_ko.md+++ b/Documents/README_ko.md@@ -42,7 +42,8 @@ cd vphone-clixcodebuild -workspace VPhone.xcworkspace -scheme VPhone \-configuration Debug -destination 'platform=macOS,arch=arm64' \-derivedDataPath .build/XcodeBundle build-zsh Scripts/check_aux.sh```+빌드 과정에서 생성된 `VPhone.bundle`을 자동으로 검증합니다.+AMFI 허용 목록을 사용하는 호스트에서는 빌드할 때마다 [호스트 설정 가이드](Guides/host-setup.md)에 따라 서명된 VM 바이너리를 다시 허용하세요. 현재 가이드와 연구 자료는 [문서 목차](README.md)에 모았습니다. 상세 가이드는 현재 영어로 제공됩니다.diff --git a/Documents/README_zh.md b/Documents/README_zh.mdindex af151693..209613a7 100644--- a/Documents/README_zh.md+++ b/Documents/README_zh.md@@ -42,9 +42,10 @@ cd vphone-clixcodebuild -workspace VPhone.xcworkspace -scheme VPhone \-configuration Debug -destination 'platform=macOS,arch=arm64' \-derivedDataPath .build/XcodeBundle build-zsh Scripts/check_aux.sh```+构建会自动验收生成的 `VPhone.bundle`。+采用 AMFI 白名单的宿主机,每次重编译后都要按[宿主机准备](Guides/host-setup.md)中的步骤重新允许签名后的 VM 程序。## 常用命令diff --git a/README.md b/README.mdindex 18b1ea09..91a31fc8 100644--- a/README.md+++ b/README.md@@ -59,10 +59,10 @@ xcodebuild -workspace VPhone.xcworkspace -scheme VPhone \The `VPhone` scheme builds the host tools, guest daemon, and guest components;every shipped binary is under `Contents/MacOS`. They use ad hoc code signatures,-with private virtualization entitlements only on `vphone-vm`. Run the test-schemes in their respective projects and `zsh Scripts/check_aux.sh` to inspect-the bundle. An AMFI allowlist must be updated whenever the VM binary's cdhash-changes. See [host setup](Documents/Guides/host-setup.md) and the+with private virtualization entitlements only on `vphone-vm`. The build validates+the finished bundle; run the test schemes in their respective projects. An AMFI+allowlist must be updated whenever the VM binary's cdhash changes. See+[host setup](Documents/Guides/host-setup.md) and the[bundle integration contract](Documents/Guides/bundle-integration.md).## Everyday commandsdiff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/InPlaceRewrite.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/InPlaceRewrite.swiftindex fc820da4..16284b0e 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/InPlaceRewrite.swift+++ b/VPhoneExecutable/VPhoneCommand/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 `Scripts/check_aux.sh` knows+// 4.6 MB — so the copy costs nothing worth having, and `Build/ValidateBundle.sh` knows// this spelling is the deliberate one.import Foundationdiff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareAEACommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareAEACommand.swiftindex 0821f0c2..966d9ce0 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareAEACommand.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwareAEACommand.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 `Scripts/check_aux.sh` exists+// self-contained can finish a job, which is the thing `Build/ValidateBundle.sh` exists// to stop.//// ipsw fw aea --key <f> -> vphone-cli fw aea-key <f>diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneRestore/MobileRestoreCore/Bridge/zip.h b/VPhoneExecutable/VPhoneCommand/VPhoneRestore/MobileRestoreCore/Bridge/zip.hindex 7c812d5a..ad58b539 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneRestore/MobileRestoreCore/Bridge/zip.h+++ b/VPhoneExecutable/VPhoneCommand/VPhoneRestore/MobileRestoreCore/Bridge/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 `Scripts/check_aux.sh`+ * path in the dependency closure, which is exactly what `Build/ValidateBundle.sh`* gate 1 exists to reject.** WHAT IS LOSTdiff --git a/VPhoneExecutable/VPhoneCommand/VPhoneSignTests/VPhoneSignFixtures.swift b/VPhoneExecutable/VPhoneCommand/VPhoneSignTests/VPhoneSignFixtures.swiftindex 6fe05567..c6a02fb6 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneSignTests/VPhoneSignFixtures.swift+++ b/VPhoneExecutable/VPhoneCommand/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 `Scripts/check_aux.sh` cannot+// AGENTS.md forbids for an interpreter: a dependency `Build/ValidateBundle.sh` cannot// see, and a silent skip when it is missing.import CryptoKitdiff --git a/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh b/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.shindex 94663486..9dbae2a8 100755--- a/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh+++ b/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh@@ -82,3 +82,5 @@ compatibility_library="$(/usr/bin/xcrun swift-stdlib-tool --print \/usr/bin/codesign --force --sign - "$macos/libswiftCompatibilitySpan.vphone.dylib"/usr/bin/codesign --force --sign - --entitlements "$root/VPhoneExecutable/VPhoneVirtualization/Resources/VPhoneVirtualization.entitlements" "$macos/vphone-vm"/usr/bin/codesign --force --sign - "$bundle"++"${0:a:h}/ValidateBundle.sh" "$bundle"diff --git a/Scripts/check_aux.sh b/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.shsimilarity index 99%rename from Scripts/check_aux.shrename to VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.shindex 995d6c0f..7c475a44 100755--- a/Scripts/check_aux.sh+++ b/VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh@@ -2,7 +2,7 @@# vphone-tier: buildset -euo pipefail-root="${0:a:h:h}"+root="$(cd "${0:a:h}/../../.." && pwd)"bundle="${1:-$root/.build/XcodeBundle/Build/Products/Debug/VPhone.bundle}"macos="$bundle/Contents/MacOS"resources="$bundle/Contents/Resources"diff --git a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swift b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swiftindex 84d1b95a..d8004a94 100644--- a/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swift+++ b/VPhoneKit/VPhoneCoreKit/Firmware/VPhoneResources.swift@@ -138,7 +138,7 @@ public struct VPhoneResources: Sendable {// was the dangerous one: a `PATH` fallback makes a missing environment look// like a working one, right up until a restore fails on a stranger's// machine. Nothing in this package may resolve an interpreter again — see- // the "Python" section in AGENTS.md, and `Scripts/check_aux.sh`, which now+ // the "Python" section in AGENTS.md, and `Build/ValidateBundle.sh`, which now// fails outright on a python3 lookup instead of registering it.// With the interpreter went the last `PATH` lookup in this package. Every