Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Bound socket operations and restore post-merge checks

Lakr8eecc0defe63
diff --git a/AGENTS.md b/AGENTS.md
index 2adfb096..64ebc0bd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,16 +4,16 @@ Virtual iPhone boot tool using Apple's Virtualization.framework with PCC researc
## Quick Reference
-- **Build:** `make build`
-- **Boot (GUI):** `make boot`
-- **Boot (DFU):** `make boot_dfu`
-- **All targets:** `make help`
-- **AMFI refuses `vphone-vm`?** `make amfi_allow` (asks for root). Re-run it after every build — it allowlists cdhashes. `make amfi_status` to look, `make amfi_off` to revert. See Key Patterns.
+- **Build:** `zsh scripts/build.sh` (builds, signs, and bundles the app)
+- **Test:** `swift test`; then `zsh scripts/check_aux.sh` for bundle admission gates
+- **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 `docs/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`.
- **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 `docs/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. The only git submodule is `scripts/repos/insert_dylib`, a build-time test reference. **No Python anywhere, and no Homebrew package at runtime** — see Tiers below.
-- **Tiers.** Three environments run code here and the rules differ. **build** (the machine that builds the `.app`) may use Xcode, `xcrun`, clang, swift, git and Homebrew. **dist** (the shipped `.app`, on a clean macOS) may use `/usr/lib`, `/System` and the bundle — nothing else, no `PATH` lookup. **guest** (inside the VM) is out of host self-containment scope. Every script declares its tier on **line 2** (`# vphone-tier: dist`); `scripts/dist_manifest.sh` reads those and is what `build.sh` and `make bundle` stage from, so a script that declares nothing ships nowhere. `make check-aux` gates all of it. The dist tier's registered-exception list is **empty** and a release requires it to stay that way.
+- **Tiers.** Three environments run code here and the rules differ. **build** (the machine that builds the `.app`) may use Xcode, `xcrun`, clang, swift, git and Homebrew. **dist** (the shipped `.app`, on a clean macOS) may use `/usr/lib`, `/System` and the bundle — nothing else, no `PATH` lookup. **guest** (inside the VM) is out of host self-containment scope. Every script declares its tier on **line 2** (`# vphone-tier: dist`); `scripts/dist_manifest.sh` reads those and is what `scripts/build.sh` stages from, so a script that declares nothing ships nowhere. `scripts/check_aux.sh` runs the admission gates. The dist tier's registered-exception list is **empty** and a release requires it to stay that way.
## Workflow Rules
@@ -182,7 +182,7 @@ scripts/ # Build scripts and payloads only; no runtime
├── 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 — `make check-aux`
+├── 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 code
└── repos/ # Toolchain source (git submodule: insert_dylib)
@@ -198,7 +198,7 @@ research/ # Detailed firmware/patch documentation
### Key Patterns
- **Three host binaries, one of them entitled.** `vphone-cli` carries no entitlements, so it launches on any host and is always there to explain what is wrong. `vphone-vm` holds all 7 private keys and is the only thing amfid can refuse. `vphone-archive` does the unpacking. **Do not sign `vphone-cli` with entitlements** — that is how it used to be, and it is why the entry point could not start without a bypass already running.
-- **The AMFI bypass is ours, and it writes heap, not code.** `vphone-amfi-allow` (`sources/vphone-amfi-allow/`, 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. `make amfi_allow` runs it, `amfi_status` shows it, `amfi_off` removes it. It is a **per-build** step, because a cdhash changes with every signature. It must be **arm64e** to match amfid's slice, which is why it is a clang rule and not a SwiftPM target. 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.
+- **The AMFI bypass is ours, and it writes heap, not code.** `vphone-amfi-allow` (`sources/vphone-amfi-allow/`, 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 `docs/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.
- **Private API access:** Via [Dynamic](https://github.com/mhdhejazi/Dynamic) library (runtime method dispatch from pure Swift). No ObjC bridge.
@@ -239,7 +239,7 @@ one verb per patch, driven by `scripts/cfw_install*.sh` only.
- Disassembly is Capstone via `ARM64Disassembler` (the `libcapstone-spm` package). Assembly is `ARM64Encoder` plus the pre-encoded constants in `ARM64` (`ARM64Constants.swift`) — together they replace keystone's `asm()` / `asm_at()`, and `ARM64.nop` / `ARM64.movW0_0` are the old `NOP` / `MOV_W0_0`. IM4P containers go through `IM4PHandler` (the `libimg4-spm` package), which replaces pyimg4. Both resolve by URL; there is no `vendor/` directory to check out first.
- Dynamic pattern finding (string anchors, ADRP+ADD xrefs, BL frequency) — no hardcoded offsets.
- Each patch logged with offset and before/after state.
-- No interpreter, no Python environment, no native-library repair: `make build` is the whole toolchain.
+- No interpreter, no Python environment, no native-library repair: `scripts/build.sh` builds the complete app.
### Python
@@ -252,10 +252,10 @@ There is none, and adding any is a regression.
restore backend was the last holdout and is now `sources/VPhoneRestore` over
two vendored C targets — see `research/restore/p2_restore_off_python.md`.
- A patch, a probe, a format reader or a device protocol belongs in Swift,
- where it is built, signed, gated by `make check-aux` and tested with
+ where it is built, signed, gated by `scripts/check_aux.sh` and tested with
everything else. Adding an interpreter back brings with it a provisioning
step, a silent system-`python3` fallback, and a dependency closure
- `make check-aux` cannot see.
+ `scripts/check_aux.sh` cannot see.
- There is no counter-example left. `amfidont` used to be cited as one — a
third-party tool the user installed into their own Python — and it is gone
too: the AMFI bypass is `sources/vphone-amfi-allow`, one C file built by
@@ -272,7 +272,7 @@ There is none, and adding any is a regression.
## Build & Sign
-The binary requires private entitlements for PV=3 virtualization. Always use `make build` — never `swift build` alone, as the unsigned binary will fail at runtime.
+The binary requires private entitlements for PV=3 virtualization. Always use `zsh scripts/build.sh` — never `swift build` alone, as the unsigned binary will fail at runtime.
## Design System
diff --git a/research/vphoned_http_api.md b/research/vphoned_http_api.md
index 8fe95761..6dd150f3 100644
--- a/research/vphoned_http_api.md
+++ b/research/vphoned_http_api.md
@@ -74,7 +74,8 @@ exits. Host socket writes use `F_SETNOSIGPIPE`, so a guest disconnect becomes
an ordinary error instead of terminating `vphone-vm`. The host HTTP client
also times out stalled reads and writes. Camera frames use a duplicated
descriptor for each in-flight send; the original descriptor remains owned by
-`VZVirtioSocketConnection` and is never manually closed. The optional TCP
+`VZVirtioSocketConnection` and is never manually closed. Camera sends and
+local control socket operations have bounded timeouts. The optional TCP
proxy uses NIO channels and closes the paired channel when either side ends.
## Usage
diff --git a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherManifest.swift b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherManifest.swift
index 62d13bc6..42cfb206 100644
--- a/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherManifest.swift
+++ b/sources/FirmwarePatcher/Filesystem/CryptexFilesystemPatcherManifest.swift
@@ -121,7 +121,7 @@ extension CryptexFilesystemPatcher {
}
func getBuildIdentityManifest(path: URL) throws -> PlistDict {
- let data = try Data(contentsOf: path)
+ let data = try Data(contentsOf: path, options: .mappedIfSafe)
return try getBuildIdentityManifest(data: data)
}
diff --git a/sources/VPhoneVMKit/Devices/VPhoneCameraServer.swift b/sources/VPhoneVMKit/Devices/VPhoneCameraServer.swift
index ee540971..dd5f8390 100644
--- a/sources/VPhoneVMKit/Devices/VPhoneCameraServer.swift
+++ b/sources/VPhoneVMKit/Devices/VPhoneCameraServer.swift
@@ -134,7 +134,10 @@ final class VPhoneCameraServer {
let sourceFD = self.connectionFD
let fd = dup(sourceFD)
guard fd >= 0 else { self.handleDisconnect(); return }
- guard fcntl(fd, F_SETNOSIGPIPE, 1) != -1 else {
+ var timeout = timeval(tv_sec: 5, tv_usec: 0)
+ guard fcntl(fd, F_SETNOSIGPIPE, 1) != -1,
+ setsockopt(fd, SOL_SOCKET, SO_SNDTIMEO, &timeout,
+ socklen_t(MemoryLayout<timeval>.size)) == 0 else {
close(fd)
self.handleDisconnect()
return
diff --git a/sources/VPhoneVMKit/VPhoneHostControl.swift b/sources/VPhoneVMKit/VPhoneHostControl.swift
index 8d739e6d..beaafca9 100644
--- a/sources/VPhoneVMKit/VPhoneHostControl.swift
+++ b/sources/VPhoneVMKit/VPhoneHostControl.swift
@@ -181,6 +181,14 @@ class VPhoneHostControl {
close(clientFD)
continue
}
+ var timeout = timeval(tv_sec: 15, tv_usec: 0)
+ guard setsockopt(clientFD, SOL_SOCKET, SO_RCVTIMEO, &timeout,
+ socklen_t(MemoryLayout<timeval>.size)) == 0,
+ setsockopt(clientFD, SOL_SOCKET, SO_SNDTIMEO, &timeout,
+ socklen_t(MemoryLayout<timeval>.size)) == 0 else {
+ close(clientFD)
+ continue
+ }
handleClient(clientFD, controller: controller)
}
}
diff --git a/tests/FirmwarePatcherTests/DSCCameraPatcherTests.swift b/tests/FirmwarePatcherTests/DSCCameraPatcherTests.swift
index ebd2db33..9389f8ca 100644
--- a/tests/FirmwarePatcherTests/DSCCameraPatcherTests.swift
+++ b/tests/FirmwarePatcherTests/DSCCameraPatcherTests.swift
@@ -452,10 +452,8 @@ struct DSCCameraPatcherBehaviourTests {
let second = try DSCCameraPatcher.applyAll(chunksDirectory: clone, log: nil)
#expect(second.siteCount == 6)
- #expect(
- second.sites.allSatisfy(\.wasAlreadyPatched),
- "a re-run did not recognise its own output",
- )
+ let allAlreadyPatched = second.sites.allSatisfy { $0.wasAlreadyPatched }
+ #expect(allAlreadyPatched, "a re-run did not recognise its own output")
#expect(second.reattestation?.updated.isEmpty == true, "a re-run rewrote slot hashes")
#expect(second.isComplete)