Skip to content

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.md
index 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 question
diff --git a/sources/VPhoneCore/VPhoneRestoreOps.swift b/sources/VPhoneCore/VPhoneRestoreOps.swift
index 1a827862..5165cbff 100644
--- a/sources/VPhoneCore/VPhoneRestoreOps.swift
+++ b/sources/VPhoneCore/VPhoneRestoreOps.swift
@@ -3,11 +3,33 @@ import Foundation
public enum VPhoneRestoreError: Error, Equatable {
case ecidUnresolved
case noSHSH
- case noRestoreDir
case 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: - ECID
diff --git a/sources/vphone-cli/VPhoneRestoreCLI.swift b/sources/vphone-cli/VPhoneRestoreCLI.swift
index 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: onEvent
diff --git a/tests/VPhoneArchiveTests/BundleTransferTests.swift b/tests/VPhoneArchiveTests/BundleTransferTests.swift
index 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 same
diff --git a/tests/VPhoneCoreTests/LibraryTests.swift b/tests/VPhoneCoreTests/LibraryTests.swift
index 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.swift
new file mode 100644
index 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.swift
index 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/"))
+ }
}
}