Run a virtual iPhone on an Apple Silicon Mac.
Swift
Use native PCC restore as the GPU source
Lakrb06496efc0c5
diff --git a/docs/guides/create-and-run.md b/docs/guides/create-and-run.mdindex a805c977..c2d18fa1 100644--- a/docs/guides/create-and-run.md+++ b/docs/guides/create-and-run.md@@ -17,7 +17,7 @@ vphone-cli vm create myphone \Creation runs prepare → JB patch → online DFU restore → host-mounted CFW installation → first GUI boot. It needs network access for the restore ticket. CFW installation needs administrator authentication; on a host without an interactive terminal, `--root-popup` uses a macOS authentication dialog. The default virtual disk is 64 GB. `--keep-artifacts` retains the large prepared restore tree; omit it when disk space matters.-If Apple's WKMS server no longer serves the AEA key for the selected PCC image, `fw prepare` automatically creates a temporary vphone VM, starts it in DFU, and restores the selected cloudOS IPSW using this project's restore backend. It mounts the restored System volume read-only, extracts the GPU bundle, then removes the temporary VM. This first restore supplies the GPU driver for the second, hybrid iPhone restore. `vm create` and `fw prepare` also accept `--gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle` to reuse a previously extracted bundle. The CLI checks its iPhoneOS platform version against the selected cloudOS version. Each restore obtains its own ticket online.+`fw prepare` creates a temporary vphone VM, starts it in DFU, and restores the selected cloudOS IPSW using this project's restore backend. It mounts the restored System volume read-only, extracts the GPU bundle, then removes the temporary VM. This first restore supplies the GPU driver for the second, hybrid iPhone restore. `vm create` and `fw prepare` also accept `--gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle` to reuse a previously extracted bundle without the temporary restore. The CLI checks its iPhoneOS platform version against the selected cloudOS version. Each restore obtains its own ticket online.Success ends with `First boot: vphoned ping succeeded` and `JB VM created; vphoned connected`. **The verification VM is then stopped.** The ping proves the daemon answered over the host control socket during that boot; it does not leave a running VM behind.diff --git a/research/0_binary_patch_comparison.md b/research/0_binary_patch_comparison.mdindex b24bd4fb..0d3f7ecd 100644--- a/research/0_binary_patch_comparison.md+++ b/research/0_binary_patch_comparison.md@@ -1226,13 +1226,13 @@ passed (the filter is detected, and libzstd is static in the xcframework).## GPU bundle now comes from the selected PCC image (2026-09-24)The application no longer ships `AppleParavirtGPUMetalIOGPUFamily.tar`. During-`fw prepare`, the PCC `BuildManifest.plist` selects the vphone600 OS image. The-preparer decrypts and read-only mounts that image when Apple serves its AEA-key, copies its complete `AppleParavirtGPUMetalIOGPUFamily.bundle` into the VM-restore tree, then removes the temporary image. When WKMS returns 403,-`vphone-cli` creates a temporary PV=3 VM, boots it in DFU, and restores the-selected cloudOS IPSW through its own `VPhoneRestoreBridge`. The preparer-copies the bundle from its sealed System volume and removes the temporary VM.+`fw prepare`, `vphone-cli` creates a temporary PV=3 VM, boots it in DFU, and+restores the selected cloudOS IPSW through its own `VPhoneRestoreBridge`. The+preparer copies `AppleParavirtGPUMetalIOGPUFamily.bundle` from the sealed System+volume into the VM restore tree and removes the temporary VM. This is the+default path; `--gpu-driver-bundle` reuses a validated bundle instead. Both+cloudOS 26.1 and 26.4 PCC AEA key URLs returned HTTP 403 on 2026-09-24, so+the preparer no longer requests those keys before the temporary restore.Both the JB host-mount installer and the filesystem merge copy this stagedbundle into the iPhone guest. The 26.4 `23E5207q` restored bundle has`DTPlatformVersion=26.4`, `CFBundleVersion=64.4.4`, and binary SHA-256diff --git a/siblings/gpu/README.md b/siblings/gpu/README.mdindex f973f5ba..772b0528 100644--- a/siblings/gpu/README.md+++ b/siblings/gpu/README.md@@ -3,15 +3,13 @@`AppleParavirtGPUMetalIOGPUFamily.bundle` is Apple firmware content. There isno source here to compile and no binary to package in `vphone-cli.app`.-`vphone-cli fw prepare` reads the vphone600 OS path from the selected PCC-`BuildManifest.plist`, decrypts and mounts that image when Apple serves its AEA-key, and stages the complete bundle inside the VM restore tree. If that key is-unavailable, `vphone-cli` creates its own temporary PV=3 VM, boots it into DFU,-and restores the selected cloudOS IPSW with the project's in-process-idevicerestore backend. The CLI mounts its sealed System volume read-only,-copies the bundle, and removes the temporary VM. JB installation copies the-staged bundle into the iPhone guest. The driver therefore comes from the same-PCC release used for the VM's kernel.+`vphone-cli fw prepare` creates a temporary PV=3 VM, boots it into DFU, and+restores the selected cloudOS IPSW with the project's in-process idevicerestore+backend. The CLI mounts its sealed System volume read-only, stages the GPU+bundle inside the iPhone restore tree, and removes the temporary VM. An explicit+`--gpu-driver-bundle` reuses a validated bundle instead. JB installation copies+the staged bundle into the iPhone guest. The driver therefore comes from the+same PCC release used for the VM's kernel.The cloudOS 26.4 `23E5207q` bundle recovered from its restored System volumehas `DTPlatformVersion=26.4`, `CFBundleVersion=64.4.4`, and nodiff --git a/sources/VPhoneCore/VPhonePCCGPUDriver.swift b/sources/VPhoneCore/VPhonePCCGPUDriver.swiftindex 37c38218..8d9e65ea 100644--- a/sources/VPhoneCore/VPhonePCCGPUDriver.swift+++ b/sources/VPhoneCore/VPhonePCCGPUDriver.swift@@ -1,32 +1,20 @@import Foundation-/// Stages Apple's paravirtual GPU bundle from the selected PCC OS image.-/// The bundle belongs to that firmware build; it is never shipped in the app.+/// Stages Apple's paravirtual GPU bundle from a restored PCC System volume or+/// a user-supplied bundle. The bundle is never shipped in the app.public enum VPhonePCCGPUDriver {public static let name = "AppleParavirtGPUMetalIOGPUFamily.bundle"public enum Error: Swift.Error, LocalizedError {- case missingOSPath(URL)- case unsafeOSPath(String)- case missingBundle(URL)- case invalidCachedBundle(URL)+ case invalidBundle(URL)case wrongPlatformVersion(URL, expected: String, actual: String)- case toolFailed(String, String)public var errorDescription: String? {switch self {- case let .missingOSPath(manifest):- "No vphone600 OS image in PCC manifest: \(manifest.path)"- case let .unsafeOSPath(path):- "PCC manifest has an unsafe OS image path: \(path)"- case let .missingBundle(path):- "PCC OS image has no GPU driver bundle at \(path.path)"- case let .invalidCachedBundle(path):+ case let .invalidBundle(path):"GPU driver bundle is incomplete or has the wrong identifier: \(path.path)"case let .wrongPlatformVersion(path, expected, actual):"GPU driver at \(path.path) is for iPhoneOS \(actual), expected cloudOS \(expected)"- case let .toolFailed(tool, detail):- "\(tool) failed while extracting the PCC GPU driver: \(detail)"}}}@@ -35,74 +23,15 @@ public enum VPhonePCCGPUDriver {restoreDirectory.appending(path: ".pcc-gpu/\(name)")}- public static func osImage(in cloudOSDirectory: URL) throws -> URL {- let manifest = cloudOSDirectory.appendingPathComponent("BuildManifest.plist")- let data = try Data(contentsOf: manifest, options: .mappedIfSafe)- let root = try PropertyListSerialization.propertyList(from: data, format: nil) as? [String: Any]- let identities = root?["BuildIdentities"] as? [[String: Any]] ?? []- guard let path = identities.compactMap({ identity -> String? in- let info = identity["Info"] as? [String: Any]- guard info?["DeviceClass"] as? String == "vphone600ap" else { return nil }- let components = identity["Manifest"] as? [String: Any]- let os = components?["OS"] as? [String: Any]- let osInfo = os?["Info"] as? [String: Any]- return osInfo?["Path"] as? String- }).first else {- throw Error.missingOSPath(manifest)- }- let parts = path.split(separator: "/", omittingEmptySubsequences: false)- guard !path.hasPrefix("/"), !parts.contains(".."), !parts.contains("."),- !parts.contains("") else { throw Error.unsafeOSPath(path) }- return cloudOSDirectory.appendingPathComponent(path)- }-- /// Called during `fw prepare`, while the extracted PCC tree still exists.- /// Only the small bundle survives in the VM's restore tree; the decrypted- /// system image and mount are discarded before firmware preparation ends.+ /// Keep only the validated bundle in the VM's restore tree.public static func stage(- from cloudOSDirectory: URL,+ from bundle: URL,into restoreDirectory: URL,- cachedBundle: URL? = nil,- expectedPlatformVersion: String? = nil,+ expectedPlatformVersion: String,) throws {let fm = FileManager.defaultlet destination = stagedBundle(in: restoreDirectory)- if let cachedBundle {- let source = cachedBundle.standardizedFileURL.resolvingSymlinksInPath()- try validateBundle(at: source, expectedPlatformVersion: expectedPlatformVersion)- try fm.createDirectory(at: destination.deletingLastPathComponent(),- withIntermediateDirectories: true)- if fm.fileExists(atPath: destination.path) {- try fm.removeItem(at: destination)- }- try fm.copyItem(at: source, to: destination)- print("[+] GPU driver staged from local bundle: \(destination.path)")- return- }-- let encrypted = try osImage(in: cloudOSDirectory)- let scratch = restoreDirectory.appendingPathComponent(".pcc-gpu-extract-\(UUID().uuidString)")- let plain = scratch.appendingPathComponent("OS.dmg")- let mount = scratch.appendingPathComponent("mount")- try fm.createDirectory(at: mount, withIntermediateDirectories: true)- defer { try? fm.removeItem(at: scratch) }-- let key = try vphoneRunBlocking { try await VPhoneAEA.symmetricKey(of: encrypted) }- try run("/usr/bin/aea", [- "decrypt", "-t", "4", "-i", encrypted.path, "-o", plain.path, "-key-value", key,- ])- defer {- _ = try? VPhoneProcessRunner.runCapturing(- URL(fileURLWithPath: "/usr/bin/hdiutil"), ["detach", mount.path],- )- }- try run("/usr/bin/hdiutil", [- "attach", "-readonly", "-nobrowse", "-owners", "off",- "-mountpoint", mount.path, plain.path,- ])-- let source = mount.appending(path: "System/Library/Extensions/\(name)")- guard fm.fileExists(atPath: source.path) else { throw Error.missingBundle(source) }+ let source = bundle.standardizedFileURL.resolvingSymlinksInPath()try validateBundle(at: source, expectedPlatformVersion: expectedPlatformVersion)try fm.createDirectory(at: destination.deletingLastPathComponent(),withIntermediateDirectories: true)@@ -110,21 +39,21 @@ public enum VPhonePCCGPUDriver {try fm.removeItem(at: destination)}try fm.copyItem(at: source, to: destination)- print("[+] GPU driver staged from PCC OS: \(destination.path)")+ print("[+] GPU driver staged: \(destination.path)")}- static func validateBundle(at source: URL, expectedPlatformVersion: String?) throws {+ static func validateBundle(at source: URL, expectedPlatformVersion: String) throws {let fm = FileManager.defaultvar isDirectory: ObjCBool = falseguard fm.fileExists(atPath: source.path, isDirectory: &isDirectory), isDirectory.boolValue else {- throw Error.invalidCachedBundle(source)+ throw Error.invalidBundle(source)}for file in ["AppleParavirtGPUMetalIOGPUFamily","Info.plist","_CodeSignature/CodeResources"]{guard fm.fileExists(atPath: source.appendingPathComponent(file).path) else {- throw Error.invalidCachedBundle(source)+ throw Error.invalidBundle(source)}}let infoURL = source.appendingPathComponent("Info.plist")@@ -133,23 +62,12 @@ public enum VPhonePCCGPUDriver {guard let properties = plist as? [String: Any],properties["CFBundleIdentifier"] as? String =="com.apple.driver.AppleParavirtGPUMetalIOGPUFamily"- else { throw Error.invalidCachedBundle(source) }- if let expectedPlatformVersion {- let actual = properties["DTPlatformVersion"] as? String ?? "unknown"- guard actual == expectedPlatformVersion else {- throw Error.wrongPlatformVersion(- source, expected: expectedPlatformVersion, actual: actual,- )- }- }- }-- private static func run(_ tool: String, _ args: [String]) throws {- let result = try VPhoneProcessRunner.runCapturing(URL(fileURLWithPath: tool), args)- guard result.succeeded else {- let output = result.stderr.isEmpty ? result.stdout : result.stderr- throw Error.toolFailed(URL(fileURLWithPath: tool).lastPathComponent,- output.trimmingCharacters(in: .whitespacesAndNewlines))+ else { throw Error.invalidBundle(source) }+ let actual = properties["DTPlatformVersion"] as? String ?? "unknown"+ guard actual == expectedPlatformVersion else {+ throw Error.wrongPlatformVersion(+ source, expected: expectedPlatformVersion, actual: actual,+ )}}}diff --git a/sources/vphone-cli/VPhoneFirmwarePreparer.swift b/sources/vphone-cli/VPhoneFirmwarePreparer.swiftindex e0dba36e..e6ec65bd 100644--- a/sources/vphone-cli/VPhoneFirmwarePreparer.swift+++ b/sources/vphone-cli/VPhoneFirmwarePreparer.swift@@ -73,17 +73,14 @@ enum VPhoneFirmwarePreparer {let originalManifest = phoneTree.appendingPathComponent("BuildManifest.plist")try clone(originalManifest, to: phoneTree.appendingPathComponent("iPhone-BuildManifest.plist"))try FirmwareManifest.generate(iPhoneDir: phoneTree, cloudOSDir: cloudTree, verbose: true)- print(gpuDriverBundle == nil- ? "[*] Extracting GPU driver from cloudOS PCC image..."- : "[*] Staging GPU driver from local bundle...")- do {+ if let gpuDriverBundle {+ print("[*] Staging GPU driver from local bundle...")try VPhonePCCGPUDriver.stage(- from: cloudTree, into: phoneTree, cachedBundle: gpuDriverBundle,+ from: gpuDriverBundle, into: phoneTree,expectedPlatformVersion: cloud.version,)- } catch let failure as VPhoneAEA.Error {- guard case .keyFetchFailed = failure, gpuDriverBundle == nil else { throw failure }- print("[*] PCC AEA key unavailable; restoring cloudOS in a temporary vphone VM...")+ } else {+ print("[*] Restoring cloudOS in a temporary vphone VM to extract its GPU driver...")try VPhonePCCGPURecovery.stage(cloudOSDirectory: cloudTree, into: phoneTree,expectedPlatformVersion: cloud.version,diff --git a/sources/vphone-cli/VPhonePCCGPURecovery.swift b/sources/vphone-cli/VPhonePCCGPURecovery.swiftindex 5f5c534d..67f4e32e 100644--- a/sources/vphone-cli/VPhonePCCGPURecovery.swift+++ b/sources/vphone-cli/VPhonePCCGPURecovery.swift@@ -82,14 +82,13 @@ enum VPhonePCCGPURecovery {_ = dfu.waitUntilExit()try stageFromSystemDisk(- vm.url.appending(path: "Disk.img"), cloudOSDirectory: cloudOSDirectory,+ vm.url.appending(path: "Disk.img"),into: restoreDirectory, expectedPlatformVersion: expectedPlatformVersion,)}private static func stageFromSystemDisk(_ diskImage: URL,- cloudOSDirectory: URL,into restoreDirectory: URL,expectedPlatformVersion: String,) throws {@@ -123,7 +122,7 @@ enum VPhonePCCGPURecovery {path: "System/Library/Extensions/\(VPhonePCCGPUDriver.name)",)try VPhonePCCGPUDriver.stage(- from: cloudOSDirectory, into: restoreDirectory, cachedBundle: source,+ from: source, into: restoreDirectory,expectedPlatformVersion: expectedPlatformVersion,)print("[+] GPU driver staged from cloudOS restored by vphone-cli")diff --git a/tests/VPhoneCoreTests/PCCGPUDriverTests.swift b/tests/VPhoneCoreTests/PCCGPUDriverTests.swiftindex fc086e35..1cecb659 100644--- a/tests/VPhoneCoreTests/PCCGPUDriverTests.swift+++ b/tests/VPhoneCoreTests/PCCGPUDriverTests.swift@@ -3,44 +3,7 @@ import Testing@testable import VPhoneCorestruct PCCGPUDriverTests {- @Test func `selects vphone 600 OS image`() throws {- let directory = FileManager.default.temporaryDirectory- .appendingPathComponent("pcc-gpu-test-\(UUID().uuidString)")- try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)- defer { try? FileManager.default.removeItem(at: directory) }-- let identities: [[String: Any]] = [- identity(device: "vresearch101ap", os: "wrong.dmg.aea"),- identity(device: "vphone600ap", os: "PCC-OS.dmg.aea"),- ]- let manifest = try PropertyListSerialization.data(- fromPropertyList: ["BuildIdentities": identities], format: .binary, options: 0,- )- try manifest.write(to: directory.appendingPathComponent("BuildManifest.plist"))-- #expect(try VPhonePCCGPUDriver.osImage(in: directory)- == directory.appendingPathComponent("PCC-OS.dmg.aea"))- #expect(VPhonePCCGPUDriver.stagedBundle(in: directory)- == directory.appending(path: ".pcc-gpu/AppleParavirtGPUMetalIOGPUFamily.bundle"))- }-- @Test func `refuses path outside PCC directory`() throws {- let directory = FileManager.default.temporaryDirectory- .appendingPathComponent("pcc-gpu-test-\(UUID().uuidString)")- try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)- defer { try? FileManager.default.removeItem(at: directory) }- let manifest = try PropertyListSerialization.data(- fromPropertyList: ["BuildIdentities": [identity(device: "vphone600ap", os: "../outside.dmg")]],- format: .binary, options: 0,- )- try manifest.write(to: directory.appendingPathComponent("BuildManifest.plist"))-- #expect(throws: VPhonePCCGPUDriver.Error.self) {- try VPhonePCCGPUDriver.osImage(in: directory)- }- }-- @Test func `stages a validated local bundle without an AEA key request`() throws {+ @Test func `stages a validated GPU bundle`() throws {let root = FileManager.default.temporaryDirectory.appendingPathComponent("pcc-gpu-test-\(UUID().uuidString)")defer { try? FileManager.default.removeItem(at: root) }@@ -63,30 +26,27 @@ struct PCCGPUDriverTests {let restore = root.appendingPathComponent("restore")try VPhonePCCGPUDriver.stage(- from: root.appendingPathComponent("missing-cloudos"),+ from: source,into: restore,- cachedBundle: source,expectedPlatformVersion: "26.4",)let staged = VPhonePCCGPUDriver.stagedBundle(in: restore)+ #expect(staged == restore.appending(path: ".pcc-gpu/AppleParavirtGPUMetalIOGPUFamily.bundle"))#expect(try Data(contentsOf: staged.appendingPathComponent("AppleParavirtGPUMetalIOGPUFamily"))== Data("AppleParavirtGPUMetalIOGPUFamily".utf8))#expect(throws: VPhonePCCGPUDriver.Error.self) {try VPhonePCCGPUDriver.stage(- from: root, into: restore, cachedBundle: source,+ from: source, into: restore,expectedPlatformVersion: "26.1",)}try FileManager.default.removeItem(at: source.appendingPathComponent("_CodeSignature/CodeResources"))#expect(throws: VPhonePCCGPUDriver.Error.self) {- try VPhonePCCGPUDriver.stage(from: root, into: restore, cachedBundle: source)+ try VPhonePCCGPUDriver.stage(+ from: source, into: restore, expectedPlatformVersion: "26.4",+ )}}-- private func identity(device: String, os: String) -> [String: Any] {- ["Info": ["DeviceClass": device],- "Manifest": ["OS": ["Info": ["Path": os]]]]- }}