Run a virtual iPhone on an Apple Silicon Mac.
Swift
p2: three restore gaps the CLI had, and two leaks in the test suite
Lakr1ca414611f4e
diff --git a/research/p2_restore_off_python.md b/research/p2_restore_off_python.mdindex 4a8a62ee..65a35abc 100644--- a/research/p2_restore_off_python.md+++ b/research/p2_restore_off_python.md@@ -150,20 +150,48 @@ it is not checked and needs a phone or VM in DFU.| --: | --- | --- | --- | --- | --- || 1 | `restore` (online, default) | `pmd3 restore-update` | `erase=true, ticket_path=NULL` | VM boots | **device** (options mapping is `unit`: `RestoreOptionsTests.defaultsAreAnOnlineEraseRestore`) || 2 | `restore --get-shsh` | `pmd3 restore-get-shsh` | `shsh_only=true` | `.shsh` semantically equal to the Python's, same filename | **split.** Filename and plist handling are `unit` (`RestoreLayoutTests.shshIsNamedAfterTheECIDInSixteenHexDigits`, the whole of `RestoreTicketTests`); the TSS round trip is **device** |-| 3 | `restore --offline` | AEA decrypt in place → `--tss <first .shsh>` | AEA decrypt in place → `ticket_path=<same file>` | ① `noSHSH` with no blob ② `noRestoreDir` with no tree ③ multiple `.shsh` → sorted first ④ VM boots | ①②③ **unit** (`RestoreLayoutTests`, `RestoreRunnerTests.fetchingASHSHStopsAtTheMissingRestoreTree`); ④ **device** |+| 3 | `restore --offline` | AEA decrypt in place → `--tss <first .shsh>` | AEA decrypt in place → `ticket_path=<same file>` | ① `noSHSH` with no blob ② `noRestoreDir` with no tree ③ multiple `.shsh` → sorted first ④ VM boots | ①②③ **unit** (`RestoreLayoutTests`, `RestoreRunnerTests.fetchingASHSHStopsAtTheMissingRestoreTree`), and ①② also **run through the CLI** — see below; ④ **device** || 4 | `restore --no-erase` | `Behavior.Update` | `erase=false` | user data survives | **device** (mapping is `unit`: `RestoreOptionsTests.updateInPlaceClearsErase`) || 5 | metadata on success | writes `restore-info.json` | same | contents identical | **device.** `VPhoneRestoreInfo.derive` is host-side and unchanged, but "only on success" needs a run || 6 | failure | no `restore-info.json`, exit code passed through | same | exit codes match | **device.** The bridge's own rejections are `unit` (`RestoreRunnerTests`); a failure from inside idevicerestore is not || 7 | verbosity | `-v` → one, `-vv`/`-vvv` → two `-v` | `debug_level` | logs comparably detailed | **device.** The level enum matches upstream's one for one and that is `unit` (`RestoreEventTests.levelsMatchIdevicerestoresEnum`) |-Four rows need a device: 1, 4, 5, 6, and the tail halves of 2, 3 and 7.-**Run them on a disposable VM** — a failed restore leaves the guest sitting in-recovery.--The unit suite was **not executed during this documentation pass** (another-stage held the build directory). Whoever lands P2 should run-`swift test --filter VPhoneRestoreTests` and record the result here rather than-inheriting the claim.+### What the first pass over this table actually turned up++The unit suite had **not been executed during the documentation pass** that wrote+this file, and the note here asked whoever landed P2 to run it rather than+inherit the claim. Run on 2026-09-23:+`swift test --filter VPhoneRestoreTests` → **67 tests in 6 suites, all passing.**++Reading the table against the shipped CLI, rather than against the library,+found three things the unit tests could not have caught — every one of them a+gap between `VPhoneRestore` and `vphone-cli`, not inside either:++- **Row 4 was not "needs a device", it was unreachable.** The Python had+ `--erase/--no-erase`; the port kept `VPhoneRestoreOptions.erase` and+ `RestoreOptionsTests.updateInPlaceClearsErase`, but no flag was ever added to+ `VPhoneRestoreCommand`, which passed a literal `erase: true`. The flag exists+ now, so the row is a device check like the rest.+- **Row 3's `--offline` path bypassed its own guard, destructively.** The CLI+ globbed `iPhone*_Restore` itself, sorted, and took the first — Python's rule,+ the one "Deliberate divergences" below says was replaced — then decrypted that+ tree's AEA images **in place** before `VPhoneRestoreBridge` got a chance to+ refuse two trees. With two firmware trees in a bundle it irreversibly+ decrypted one nobody chose and *then* aborted. It now calls+ `VPhoneRestoreLayout.findRestoreDirectory` like every other caller, so the+ refusal comes first. Verified end to end: two trees → exit 1, zero bytes+ written into either.+- **`VPhoneRestoreError` printed case names.** A missing blob said+ `Error: noSHSH` beside sibling failures from `VPhoneRestoreBackendError` that+ have read as sentences all along. It conforms to `LocalizedError` now.+ `noRestoreDir` went with it: the `--offline` glob was its only thrower.++Criteria ① and ② of row 3 were then exercised through the built binary against a+synthetic bundle, not only through the library.++The rows that remain **device** are unchanged: 1, 4, 5, 6 and the tail halves of+2, 3 and 7. **Run them on a disposable VM** — a failed restore leaves the guest+sitting in recovery.### `research/p2_dfu_spike.md` already settled the riskiest questiondiff --git a/sources/VPhoneCore/VPhoneRestoreOps.swift b/sources/VPhoneCore/VPhoneRestoreOps.swiftindex 1a827862..5165cbff 100644--- a/sources/VPhoneCore/VPhoneRestoreOps.swift+++ b/sources/VPhoneCore/VPhoneRestoreOps.swift@@ -3,11 +3,33 @@ import Foundationpublic enum VPhoneRestoreError: Error, Equatable {case ecidUnresolvedcase noSHSH- case noRestoreDircase aeaDecryptFailed(String)case aeaStillEncrypted(String)}+/// Without this, ArgumentParser prints the case name — a restore run with no+/// cached blob said `Error: noSHSH`, beside sibling failures from+/// `VPhoneRestoreBackendError` that have read as sentences all along.+///+/// `noRestoreDir` used to sit in the enum above and is gone: its one thrower+/// was `--offline`'s local restore-tree glob, and that now goes through+/// `VPhoneRestoreLayout.findRestoreDirectory`, whose own+/// `noRestoreDirectory(_:)` names the bundle it looked in.+extension VPhoneRestoreError: LocalizedError {+ public var errorDescription: String? {+ switch self {+ case .ecidUnresolved:+ "No ECID: pass --ecid, or restore a bundle whose udid-prediction.txt carries one"+ case .noSHSH:+ "No cached .shsh in the bundle; run `restore --get-shsh` first, or drop the --offline flag"+ case let .aeaDecryptFailed(name):+ "Could not decrypt \(name)"+ case let .aeaStillEncrypted(name):+ "\(name) is still AEA-encrypted after decryption reported success"+ }+ }+}+public enum VPhoneRestoreOps {// MARK: - ECIDdiff --git a/sources/vphone-cli/VPhoneRestoreCLI.swift b/sources/vphone-cli/VPhoneRestoreCLI.swiftindex fe6d9216..7b27ff1b 100644--- a/sources/vphone-cli/VPhoneRestoreCLI.swift+++ b/sources/vphone-cli/VPhoneRestoreCLI.swift@@ -34,6 +34,12 @@ struct VPhoneRestoreCommand: ParsableCommand {@Option(name: .shortAndLong, help: "Device UDID (optional)") var udid: String?@Option(name: .shortAndLong, help: "Device ECID (default: read from the bundle's udid-prediction.txt)")var ecid: String?+ // The Python exposed this as `--erase/--no-erase`, defaulting to erase, and+ // `VPhoneRestoreOptions.erase` has carried it since the port. Only the flag+ // was missing, which left `Behavior.Update` reachable from the library and+ // its unit test but not from the command line.+ @Flag(name: .customLong("no-erase"), help: "Update in place instead of erasing (upstream's Behavior.Update)")+ var noErase = false@Flag(name: .customShort("v"), help: "Increase verbosity: -v tool detail, -vv guest serial, -vvv internal trace")var verboseCount: Int@@ -74,11 +80,14 @@ struct VPhoneRestoreCommand: ParsableCommand {let shshes = ((try? fm.contentsOfDirectory(at: bundle.url, includingPropertiesForKeys: nil)) ?? []).filter { $0.pathExtension == "shsh" }.sorted { $0.lastPathComponent < $1.lastPathComponent }guard let shsh = shshes.first else { throw VPhoneRestoreError.noSHSH }- let restoreDir = ((try? fm.contentsOfDirectory(at: bundle.url, includingPropertiesForKeys: nil)) ?? [])- .filter { $0.lastPathComponent.hasPrefix("iPhone") && $0.lastPathComponent.hasSuffix("_Restore") }- .sorted { $0.lastPathComponent < $1.lastPathComponent }- .first- guard let restoreDir else { throw VPhoneRestoreError.noRestoreDir }+ // `VPhoneRestoreLayout.findRestoreDirectory`, not a local glob that+ // sorts and takes the first. This path used to do the latter, which+ // is Python's rule and the one the port deliberately replaced —+ // and here it was worse than either: with two firmware trees side+ // by side it decrypted one of them IN PLACE, irreversibly, and only+ // then reached the bridge, which refuses two trees and aborted. The+ // refusal has to come before anything is written.+ let restoreDir = try VPhoneRestoreLayout.findRestoreDirectory(in: bundle.url)print("[restore] decrypting AEA images in \(restoreDir.lastPathComponent)...")try VPhoneRestoreOps.decryptAEAImages(inRestoreDir: restoreDir)ticket = shsh@@ -88,7 +97,7 @@ struct VPhoneRestoreCommand: ParsableCommand {vmDir: bundle.url,ecid: ecidValue,udid: udid,- erase: true,+ erase: !noErase,ticketPath: ticket,debugLevel: v.restoreDebugLevel,onEvent: onEventdiff --git a/tests/VPhoneArchiveTests/BundleTransferTests.swift b/tests/VPhoneArchiveTests/BundleTransferTests.swiftindex f3c09d79..8abd2cce 100644--- a/tests/VPhoneArchiveTests/BundleTransferTests.swift+++ b/tests/VPhoneArchiveTests/BundleTransferTests.swift@@ -232,10 +232,22 @@ struct BundleTransferTests {Array(try Data(contentsOf: url).prefix(n))}- private func exportAndImport(- _ compression: VPhoneBundleTransfer.ExportCompression?- ) throws -> (archive: URL, imported: VPhoneBundle) {+ /// Takes a body rather than returning the pair, because it makes two+ /// temporary libraries and has to outlive neither.+ ///+ /// It used to `return (archive, imported)`, which meant neither root could+ /// be removed here — and none of the three callers removed them either. Each+ /// holds a 1 GiB `Disk.img`, so every `swift test` left six of them in+ /// `FileManager.temporaryDirectory` for good: the directory had reached+ /// 383 GB and filled the volume. Every other test in this file and in+ /// `BundleOpsTests` already paired `makeRoot()` with a `defer`; this helper+ /// was the one place that could not.+ private func withExportAndImport(+ _ compression: VPhoneBundleTransfer.ExportCompression?,+ _ body: (_ archive: URL, _ imported: VPhoneBundle) throws -> Void+ ) throws {let root = try makeRoot()+ defer { try? FileManager.default.removeItem(at: root) }let lib = VPhoneLibrary(root: root)try makeBundle("orig", cpuCount: 6, in: lib)let archive = root.appendingPathComponent("orig.archive")@@ -251,27 +263,37 @@ struct BundleTransferTests {try VPhoneBundleTransfer.export(bundleNamed: "orig", to: archive, includeIPSW: false, in: lib)}let dstRoot = try makeRoot()+ defer { try? FileManager.default.removeItem(at: dstRoot) }let imported = try VPhoneBundleTransfer.importArchive(from: archive, name: "copy", in: VPhoneLibrary(root: dstRoot))- return (archive, imported)+ try body(archive, imported)}+ // The `try` is hoisted out of `#expect` in these three: inside a throwing+ // closure the macro's expansion does not carry the throw out, so+ // `#expect(try magic(...))` is "errors thrown from here are not handled".@Test func exportDefaultsToFastZstd() throws {- let (archive, imported) = try exportAndImport(nil)- #expect(try magic(archive, 4) == Self.zstdMagic)- #expect(imported.manifest.cpuCount == 6)+ try withExportAndImport(nil) { archive, imported in+ let magic = try magic(archive, 4)+ #expect(magic == Self.zstdMagic)+ #expect(imported.manifest.cpuCount == 6)+ }}@Test func exportFastProducesZstdAndRoundTrips() throws {- let (archive, imported) = try exportAndImport(.fast)- #expect(try magic(archive, 4) == Self.zstdMagic)- #expect(imported.manifest.cpuCount == 6)+ try withExportAndImport(.fast) { archive, imported in+ let magic = try magic(archive, 4)+ #expect(magic == Self.zstdMagic)+ #expect(imported.manifest.cpuCount == 6)+ }}@Test func exportMaxProducesXzAndRoundTrips() throws {- let (archive, imported) = try exportAndImport(.max)- #expect(try magic(archive, 6) == Self.xzMagic)- #expect(imported.manifest.cpuCount == 6)+ try withExportAndImport(.max) { archive, imported in+ let magic = try magic(archive, 6)+ #expect(magic == Self.xzMagic)+ #expect(imported.manifest.cpuCount == 6)+ }}/// Replaces the old `compressionPresetTarArgs`, which pinned the samediff --git a/tests/VPhoneCoreTests/LibraryTests.swift b/tests/VPhoneCoreTests/LibraryTests.swiftindex aa5c9a40..ac26ebb0 100644--- a/tests/VPhoneCoreTests/LibraryTests.swift+++ b/tests/VPhoneCoreTests/LibraryTests.swift@@ -47,25 +47,36 @@ struct LibraryTests {}}+ // These three go through `ProcessEnvironment` rather than calling `setenv`+ // and `unsetenv` directly. `.serialized` on this suite orders these tests+ // against each other, but `ResourcesTests` drives the same two variables+ // from its own serialized suite, and nothing ordered the two suites — so+ // the bare `unsetenv` that used to open `defaultRootIsShellSafe` could+ // clear `VPHONE_ROOT` in the middle of a ResourcesTests assertion.@Test func defaultRootHonorsEnvOverride() {- setenv("VPHONE_LIBRARY_ROOT", "/tmp/vphone-test-root", 1)- defer { unsetenv("VPHONE_LIBRARY_ROOT") }- #expect(VPhoneLibrary.defaultRoot().path == "/tmp/vphone-test-root")+ ProcessEnvironment.withOverrides(["VPHONE_LIBRARY_ROOT": "/tmp/vphone-test-root"]) {+ #expect(VPhoneLibrary.defaultRoot().path == "/tmp/vphone-test-root")+ }}@Test func defaultRootHonorsVPHONERoot() {- unsetenv("VPHONE_LIBRARY_ROOT")- setenv("VPHONE_ROOT", "/tmp/vphone-test-root", 1)- defer { unsetenv("VPHONE_ROOT") }- #expect(VPhoneLibrary.defaultRoot().path == "/tmp/vphone-test-root/VMs")+ ProcessEnvironment.withOverrides([+ "VPHONE_LIBRARY_ROOT": nil,+ "VPHONE_ROOT": "/tmp/vphone-test-root",+ ]) {+ #expect(VPhoneLibrary.defaultRoot().path == "/tmp/vphone-test-root/VMs")+ }}@Test func defaultRootIsShellSafe() {// The default root feeds the shell/make firmware pipeline; a space in it// (e.g. "Application Support") breaks unquoted expansion. Must stay space-free.- unsetenv("VPHONE_LIBRARY_ROOT")- unsetenv("VPHONE_ROOT")- #expect(!VPhoneLibrary.defaultRoot().path.contains(" "))+ ProcessEnvironment.withOverrides([+ "VPHONE_LIBRARY_ROOT": nil,+ "VPHONE_ROOT": nil,+ ]) {+ #expect(!VPhoneLibrary.defaultRoot().path.contains(" "))+ }}@Test func scanReportsCorruptBundlesInsteadOfDropping() throws {diff --git a/tests/VPhoneCoreTests/ProcessEnvironment.swift b/tests/VPhoneCoreTests/ProcessEnvironment.swiftnew file mode 100644index 00000000..ba54130e--- /dev/null+++ b/tests/VPhoneCoreTests/ProcessEnvironment.swift@@ -0,0 +1,53 @@+import Foundation++/// A lock around `VPHONE_ROOT` and `VPHONE_LIBRARY_ROOT`, because the+/// environment is process-global and `.serialized` is not.+///+/// `ResourcesTests` and `LibraryTests` both drive those two variables, and both+/// carry `.serialized` — which orders each suite's own tests and does nothing+/// about the two suites running against each other. So `LibraryTests`'+/// `unsetenv("VPHONE_ROOT")` would land in the middle of+/// `ResourcesTests.userDataRootHonorsVPHONERoot`, whose next three+/// `#expect`s then compared a `~/.vphone` path against `/tmp/vphone-test-root`.+/// That is the intermittent failure `ResourcesTests`' own header describes as+/// "roughly one run in ten" and believed `.serialized` had fixed; it survived,+/// because the other half of the race is in a different file.+///+/// Taking this lock for the whole of a test body — reads included, not just+/// writes — is what actually serialises them, and restoring the previous value+/// rather than unsetting means a test that runs under an inherited+/// `VPHONE_ROOT` leaves it as it found it.+enum ProcessEnvironment {+ private static let lock = NSLock()++ /// Run `body` with `overrides` applied, with nothing else touching these+ /// variables, and with whatever was there before put back afterwards. A+ /// `nil` value unsets.+ static func withOverrides(+ _ overrides: [String: String?],+ _ body: () throws -> Void+ ) rethrows {+ lock.lock()+ defer { lock.unlock() }++ let previous = overrides.keys.reduce(into: [String: String?]()) { saved, key in+ saved[key] = ProcessInfo.processInfo.environment[key]+ }+ defer { for (key, value) in previous { apply(key, value) } }++ for (key, value) in overrides { apply(key, value) }+ try body()+ }++ /// Hold the lock without changing anything — for a test that only reads the+ /// ambient environment and must not see another suite's override.+ static func withStableEnvironment(_ body: () throws -> Void) rethrows {+ lock.lock()+ defer { lock.unlock() }+ try body()+ }++ private static func apply(_ key: String, _ value: String?) {+ if let value { setenv(key, value, 1) } else { unsetenv(key) }+ }+}diff --git a/tests/VPhoneCoreTests/ResourcesTests.swift b/tests/VPhoneCoreTests/ResourcesTests.swiftindex 5c100669..d1ab144c 100644--- a/tests/VPhoneCoreTests/ResourcesTests.swift+++ b/tests/VPhoneCoreTests/ResourcesTests.swift@@ -5,9 +5,13 @@ import Testing/// `.serialized` because several of these set and unset `VPHONE_ROOT`, and the/// environment is process-global: run in parallel, one test's/// `defer { unsetenv(...) }` clears the variable another is still relying on.-/// That was a real intermittent failure — roughly one run in ten —-/// and the reason two tests below bail out early when `VPHONE_ROOT` is already-/// set, which was a way of tolerating the race rather than fixing it.+/// That was a real intermittent failure — roughly one run in ten.+///+/// `.serialized` alone did not fix it, and the "roughly one run in ten" stayed+/// true: it orders this suite's tests against each other and says nothing about+/// `LibraryTests`, which drives the same two variables from its own serialized+/// suite in a different file. Both sides now go through `ProcessEnvironment`,+/// which is the lock that actually spans them.@Suite(.serialized)struct ResourcesTests {@Test func bundledLayoutResolvesToContentsResources() {@@ -39,19 +43,23 @@ struct ResourcesTests {}@Test func cacheDirsAreHomeRelative() {- // The VPHONE_ROOT override would relocate the cache; only assert the default.- if ProcessInfo.processInfo.environment["VPHONE_ROOT"] != nil { return }- #expect(VPhoneResources.userDataRoot().path.hasSuffix("/.vphone"))+ // The VPHONE_ROOT override would relocate the cache; assert the default+ // with the variable held clear, rather than bailing out when some other+ // suite happens to have set it — that skip was the old way of living+ // with the race `ProcessEnvironment` now closes.+ ProcessEnvironment.withOverrides(["VPHONE_ROOT": nil]) {+ #expect(VPhoneResources.userDataRoot().path.hasSuffix("/.vphone"))+ }}@Test func userDataRootHonorsVPHONERoot() {- setenv("VPHONE_ROOT", "/tmp/vphone-test-root", 1)- defer { unsetenv("VPHONE_ROOT") }- let r = VPhoneResources(base: URL(fileURLWithPath: "/x"))- #expect(VPhoneResources.userDataRoot().path == "/tmp/vphone-test-root")- #expect(r.ipswCacheDir.path == "/tmp/vphone-test-root/ipsws")- #expect(r.sealVolumeCacheDir.path == "/tmp/vphone-test-root/tools")- #expect(r.debsCacheDir.path == "/tmp/vphone-test-root/debs")+ ProcessEnvironment.withOverrides(["VPHONE_ROOT": "/tmp/vphone-test-root"]) {+ let r = VPhoneResources(base: URL(fileURLWithPath: "/x"))+ #expect(VPhoneResources.userDataRoot().path == "/tmp/vphone-test-root")+ #expect(r.ipswCacheDir.path == "/tmp/vphone-test-root/ipsws")+ #expect(r.sealVolumeCacheDir.path == "/tmp/vphone-test-root/tools")+ #expect(r.debsCacheDir.path == "/tmp/vphone-test-root/debs")+ }}/// `VPhoneResources` resolves programs as siblings of the running image and@@ -60,19 +68,19 @@ struct ResourcesTests {/// from the other side, so assert it directly: every URL this type hands/// out is rooted in `base` or in the user data root.@Test func everyResourceIsRootedInTheBaseOrTheDataRoot() {- setenv("VPHONE_ROOT", "/tmp/vphone-test-root", 1)- defer { unsetenv("VPHONE_ROOT") }- let base = URL(fileURLWithPath: "/x")- let r = VPhoneResources(base: base)- let rooted = [- r.scriptsDir, r.resourceArchivesDir, r.fwPrepareScript,- r.cfwInstallHostScript, r.preflightScript, r.signcert, r.vphoned,- ]- for url in rooted {- #expect(url.path.hasPrefix("/x/"), "\(url.path) escapes the resource base")- }- for url in [r.ipswCacheDir, r.sealVolumeCacheDir, r.debsCacheDir] {- #expect(url.path.hasPrefix("/tmp/vphone-test-root/"))+ ProcessEnvironment.withOverrides(["VPHONE_ROOT": "/tmp/vphone-test-root"]) {+ let base = URL(fileURLWithPath: "/x")+ let r = VPhoneResources(base: base)+ let rooted = [+ r.scriptsDir, r.resourceArchivesDir, r.fwPrepareScript,+ r.cfwInstallHostScript, r.preflightScript, r.signcert, r.vphoned,+ ]+ for url in rooted {+ #expect(url.path.hasPrefix("/x/"), "\(url.path) escapes the resource base")+ }+ for url in [r.ipswCacheDir, r.sealVolumeCacheDir, r.debsCacheDir] {+ #expect(url.path.hasPrefix("/tmp/vphone-test-root/"))+ }}}