Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
34.6 KB
Raw Blame
import AppleArchive
import ArchiveKit
import CryptoKit
import Foundation
import System
import Testing
@testable import VPhoneArchiveKit
import VPhoneCoreKit

/// Staging an Apple TV 4K's device tree and userland from its OTA with the
/// system AppleArchive framework. The OTAs here are synthetic but shaped like
/// Apple's: AEA around a segmented archive whose extract segments carry the
/// files, plus the manifest and fix-up segments staging ignores.
@Suite("OTA userland staging", .serialized)
struct OTAArchiveTests {
    // MARK: - Fixtures

    private let key = SymmetricKey(size: .bits256)
    private var keyText: String {
        key.withUnsafeBytes { Data($0) }.base64EncodedString()
    }

    private func makeRoot() throws -> URL {
        let root = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString)
        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
        return root
    }

    private enum Entry {
        case file(String, Data)
        case directory(String)
        case symlink(String, String)
        /// A top-level metadata entry: `yop` and an archive of `entries` in its blob.
        case segment(Character, [Entry])
    }

    private func field(_ key: String, _ value: UInt64) -> ArchiveHeader.Field {
        .uint(key: ArchiveHeader.FieldKey(key), value: value)
    }

    private func ascii(_ character: Character) -> UInt64 {
        UInt64(character.asciiValue!)
    }

    /// The Apple Archive encoding of `entries`.
    private func encode(_ entries: [Entry], in root: URL) throws -> Data {
        let file = root.appendingPathComponent("\(UUID().uuidString).aar")
        let stream = try #require(ArchiveByteStream.fileStream(
            path: FilePath(file.path),
            mode: .writeOnly,
            options: [.create, .truncate],
            permissions: FilePermissions(rawValue: 0o644),
        ))
        let encoder = try #require(ArchiveStream.encodeStream(writingTo: stream))
        for entry in entries {
            let header = ArchiveHeader()
            let blob: Data?
            switch entry {
            case let .file(path, data):
                header.append(field("TYP", ascii("F")))
                header.append(.string(key: ArchiveHeader.FieldKey("PAT"), value: path))
                blob = data
            case let .directory(path):
                header.append(field("TYP", ascii("D")))
                header.append(.string(key: ArchiveHeader.FieldKey("PAT"), value: path))
                blob = nil
            case let .symlink(path, target):
                header.append(field("TYP", ascii("L")))
                header.append(.string(key: ArchiveHeader.FieldKey("PAT"), value: path))
                header.append(.string(key: ArchiveHeader.FieldKey("LNK"), value: target))
                blob = nil
            case let .segment(yop, inner):
                header.append(field("TYP", ascii("M")))
                header.append(field("YOP", ascii(yop)))
                header.append(.string(key: ArchiveHeader.FieldKey("LBL"), value: "main"))
                blob = try encode(inner, in: root)
            }
            if let blob {
                header.append(.blob(key: ArchiveHeader.FieldKey("DAT"), size: UInt64(blob.count)))
            }
            try encoder.writeHeader(header)
            if let blob, !blob.isEmpty {
                try blob.withUnsafeBytes { try encoder.writeBlob(key: ArchiveHeader.FieldKey("DAT"), from: $0) }
            }
        }
        try encoder.close()
        try stream.close()
        defer { try? FileManager.default.removeItem(at: file) }
        return try Data(contentsOf: file)
    }

    /// `archive` encrypted as Apple encrypts an OTA.
    private func encrypt(_ archive: Data, to file: URL, with key: SymmetricKey) throws {
        let stream = try #require(ArchiveByteStream.fileStream(
            path: FilePath(file.path),
            mode: .writeOnly,
            options: [.create, .truncate],
            permissions: FilePermissions(rawValue: 0o644),
        ))
        let context = ArchiveEncryptionContext(profile: .hkdf_sha256_aesctr_hmac__symmetric__none, compressionAlgorithm: .lzfse)
        try context.setSymmetricKey(key)
        let encrypted = try #require(ArchiveByteStream.encryptionStream(writingTo: stream, encryptionContext: context))
        _ = try archive.withUnsafeBytes { try encrypted.write(from: $0) }
        try encrypted.close()
        try stream.close()
    }

    private func manifest(productTypes: [String] = ["AppleTV14,1"], build: String = "23L773", version: String = "26.6") throws -> Data {
        try PropertyListSerialization.data(fromPropertyList: [
            "ProductVersion": version,
            "ProductBuildVersion": build,
            "SupportedProductTypes": productTypes,
        ], format: .xml, options: 0)
    }

    private func chunk(_ index: Int) -> Data {
        Data("chunk \(index) ".utf8) + Data(repeating: UInt8(index), count: 1000 + index)
    }

    /// The members Apple's AppleTV14,1 26.6 OTA has, in its order: the
    /// manifest and device trees in one extract segment, the payload chunks
    /// split across two more, `.ecc` files staging skips, and fix-ups.
    private func otaEntries(
        manifest: Data,
        chunks: Int = 3,
        list: String? = nil,
        deviceTree: Bool = true,
    ) -> [Entry] {
        let listed = list ?? (0 ..< chunks).map { "\($0): \(1000 + $0)" }.joined(separator: "\n") + "\n"
        let payload = (0 ..< chunks).flatMap { index -> [Entry] in
            let name = String(format: "AssetData/payloadv2/payload.%03d", index)
            return [.file(name, chunk(index)), .file(name + ".ecc", Data("ecc".utf8))]
        }
        let split = payload.count / 2
        var firmware: [Entry] = [
            .file("AssetData/Info.plist", Data("info".utf8)),
            .file("AssetData/boot/BuildManifest.plist", manifest),
            .file("AssetData/boot/Firmware/all_flash/LLB.j255.RELEASE.im4p", Data("llb".utf8)),
        ]
        if deviceTree {
            firmware.append(.file("AssetData/boot/Firmware/all_flash/DeviceTree.j255ap.im4p", Data("tree j255ap".utf8)))
        }
        return [
            .segment("M", [.directory("")]),
            .segment("E", [.directory("AssetData"), .directory("AssetData/payloadv2")]),
            .segment("E", firmware),
            .segment("E", Array(payload[..<split]) + [.file("AssetData/payloadv2/fixup.manifest", Data("fixup".utf8))]),
            .segment("E", Array(payload[split...]) + [
                .file("AssetData/payloadv2/payload_chunks.txt", Data(listed.utf8)),
                .file("AssetData/payloadv2/prepare_payload", Data("pbzx".utf8)),
            ]),
            .segment("O", [.file("AssetData/payloadv2/payload.000", Data())]),
        ]
    }

    private func makeOTA(in root: URL, _ entries: [Entry], key: SymmetricKey? = nil) throws -> URL {
        let file = root.appendingPathComponent("AppleTV14,1_26.6_23L773_OTA.aea")
        try encrypt(encode(entries, in: root), to: file, with: key ?? self.key)
        return file
    }

    private func makeZIP(in root: URL, _ members: [(String, Data)]) throws -> URL {
        let file = root.appendingPathComponent("HomePod.zip")
        let writer = try #require(archive_write_new())
        defer { archive_write_free(writer) }
        try #require(archive_write_set_format_zip(writer) == ARCHIVE_OK)
        try #require(archive_write_open_filename(writer, file.path) == ARCHIVE_OK)
        for (path, data) in members {
            let entry = try #require(archive_entry_new())
            defer { archive_entry_free(entry) }
            archive_entry_set_pathname(entry, path)
            archive_entry_set_filetype(entry, UInt32(S_IFREG))
            archive_entry_set_perm(entry, 0o644)
            archive_entry_set_size(entry, Int64(data.count))
            try #require(archive_write_header(writer, entry) == ARCHIVE_OK)
            try data.withUnsafeBytes { bytes in
                try #require(archive_write_data(writer, bytes.baseAddress, bytes.count) == bytes.count)
            }
        }
        try #require(archive_write_close(writer) == ARCHIVE_OK)
        return file
    }

    private func stage(_ ota: URL, in root: URL, key: String?, build: String = "23L773") throws -> VPhoneOTAArchive.StagedUserland {
        let flash = root.appendingPathComponent("restore/Firmware/all_flash", isDirectory: true)
        try FileManager.default.createDirectory(at: flash, withIntermediateDirectories: true)
        try FileManager.default.createDirectory(at: root.appendingPathComponent("vm"), withIntermediateDirectories: true)
        return try VPhoneOTAArchive.stageUserland(
            from: ota,
            key: key,
            device: .appleTV14_1,
            build: build,
            deviceTreeDirectory: flash,
            userlandDirectory: root.appendingPathComponent("vm/OTAUserland", isDirectory: true),
        )
    }

    private func vmFolder(_ root: URL) throws -> [String] {
        let vm = root.appendingPathComponent("vm")
        try FileManager.default.createDirectory(at: vm, withIntermediateDirectories: true)
        return try FileManager.default.contentsOfDirectory(atPath: vm.path)
    }

    // MARK: - Staging

    @Test func `HomePod ZIP staging reads late metadata before payload and ignores unrelated paths`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let flash = root.appendingPathComponent("flash")
        try FileManager.default.createDirectory(at: flash, withIntermediateDirectories: true)
        let manifest = try PropertyListSerialization.data(fromPropertyList: [
            "ProductVersion": "27.2", "ProductBuildVersion": "24K120",
            "SupportedProductTypes": ["AudioAccessory5,1"],
        ], format: .xml, options: 0)
        let info = try PropertyListSerialization.data(fromPropertyList: ["OSVersion": "27.2"], format: .xml, options: 0)
        let payload = try encode([.directory("System"), .file("System/source", Data("native".utf8))], in: root)
        let ota = try makeZIP(in: root, [
            ("../outside", Data("unselected".utf8)),
            ("AssetData/payloadv2/payload.000", payload),
            ("AssetData/payloadv2/payload.000.ecc", Data("ecc".utf8)),
            ("AssetData/payloadv2/payload_chunks.txt", Data("0: 1000\n".utf8)),
            ("AssetData/payloadv2/links.txt", Data("=System/source\n+System/copy\n".utf8)),
            ("AssetData/boot/Firmware/all_flash/DeviceTree.b520ap.im4p", Data("b520".utf8)),
            ("AssetData/boot/BuildManifest.plist", manifest),
            ("AssetData/Info.plist", info),
        ])
        let identity = try VPhoneOTAArchive.checkIdentity(of: ota, key: nil, device: .audioAccessory5_1, build: "24K120")
        #expect(identity.version == "27.2")
        let userland = root.appendingPathComponent("OTAUserland")
        let result = try VPhoneOTAArchive.stageUserland(from: ota, key: nil, device: .audioAccessory5_1,
            build: "24K120", deviceTreeDirectory: flash, userlandDirectory: userland, requireFullUpdate: true)
        #expect(result.chunks == ["payload.000"])
        #expect(try Data(contentsOf: userland.appendingPathComponent("payload.000")) == payload)
        #expect(!FileManager.default.fileExists(atPath: root.appendingPathComponent("outside").path))
    }

    @Test func `an LZRAVEN payload is refused before macOS 27, by name`() throws {
        let chunk = URL(fileURLWithPath: "/tmp/payload.000")
        let lzraven = Data("pbzm".utf8) + Data(repeating: 0, count: 4)
        if ProcessInfo.processInfo.operatingSystemVersion.majorVersion < 27 {
            let error = try #require(throws: VPhoneOTAArchive.Error.self) {
                try VPhoneOTAArchive.checkCompression(lzraven, of: chunk)
            }
            guard case .needsNewerMacOS(chunk, minimum: 27) = error else {
                Issue.record("\(error)")
                return
            }
            #expect(error.localizedDescription.contains("LZRAVEN"))
            #expect(!error.localizedDescription.contains("Download the OTA again"))
        } else {
            try VPhoneOTAArchive.checkCompression(lzraven, of: chunk)
        }
        // Every other pbz compression is AppleArchive's on any supported host.
        try VPhoneOTAArchive.checkCompression(Data("pbzx".utf8), of: chunk)
    }

    @Test func `ZIP duplicate metadata is refused`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let ota = try makeZIP(in: root, [("AssetData/Info.plist", Data()), ("AssetData/Info.plist", Data())])
        #expect(throws: VPhoneOTAArchive.Error.self) {
            try VPhoneOTAArchive.readMembers(ota, key: nil, select: { _ in .skip }, received: { _, _ in })
        }
    }

    @Test func `ZIP metadata has the same bounded memory admission as Apple Archive`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let oversized = Data(repeating: 0, count: Int(VPhoneOTAArchive.memoryLimit) + 1)
        let ota = try makeZIP(in: root, [("AssetData/Info.plist", oversized)])
        #expect(throws: VPhoneOTAArchive.Error.self) {
            try VPhoneOTAArchive.readMembers(ota, key: nil, select: { _ in .memory }, received: { _, _ in Issue.record("oversized metadata delivered") })
        }
    }

    @Test func `hard-link lists preserve spaces and reject unsafe or ambiguous records`() throws {
        let links = try VPhoneOTAArchive.parseHardLinks(Data("=System/source file\n+System/copy file\n+System/another\n".utf8))
        #expect(links.count == 2)
        #expect(links[0].source == "System/source file")
        #expect(links[0].destination == "System/copy file")
        for bad in ["+orphan\n", "=/outside\n+target\n", "=source\n+../outside\n",
                    "=source\n+source\n", "=source\n+target\n+target\n", "?unsupported\n",
                    "=source\n+dir//file\n", "=source\n+dir/./file\n", "=source\n+dir/\u{0}file\n"] {
            #expect(throws: VPhoneOTAArchive.Error.self) {
                try VPhoneOTAArchive.parseHardLinks(Data(bad.utf8))
            }
        }
    }

    @Test func `payload validation checks external hard links against the whole filesystem`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let chunk = root.appendingPathComponent("payload.000")
        try encode([.directory("System"), .file("System/source", Data("resource".utf8)),
                    .symlink("escape", "/private/tmp")], in: root).write(to: chunk)
        try VPhoneOTAArchive.validatePayloadPaths([chunk], hardLinks: Data("=System/source\n+System/copy\n".utf8))
        for list in ["=missing\n+System/copy\n", "=escape\n+System/copy\n",
                     "=System/source\n+escape/outside\n", "=System/source\n+System/source/child\n",
                     "=System/source\n+System/copy\n+System/copy/child\n"] {
            #expect(throws: VPhoneOTAArchive.Error.self) {
                try VPhoneOTAArchive.validatePayloadPaths([chunk], hardLinks: Data(list.utf8))
            }
        }
    }

    @Test func `hard-link installation shares the source inode and refuses symlink parents`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let directory = try VPhoneConfinedDirectory(root: root.path)
        _ = try directory.directory("System", create: true)
        try directory.writeFile("System/source", contents: Data("resource".utf8), mode: 0o640)
        let list = Data("=System/source\n+System/copy\n".utf8)
        #expect(try VPhoneOTAArchive.installHardLinks(list, in: directory) == 1)
        let source = try directory.openRegularFile("System/source")
        #expect(try directory.refersTo("System/copy", file: source))
        #expect(try directory.readData("System/copy") == Data("resource".utf8))
        #expect(throws: VPhoneConfinedDirectoryError.self) {
            try VPhoneOTAArchive.installHardLinks(list, in: directory)
        }
        try directory.createSymlink(target: "System", at: "alias")
        for bad in ["=alias/source\n+System/other\n", "=System/source\n+alias/other\n"] {
            #expect(throws: VPhoneConfinedDirectoryError.self) {
                try VPhoneOTAArchive.installHardLinks(Data(bad.utf8), in: directory)
            }
        }
        #expect(try directory.exists("System/other") == false)
    }

    @Test func `staging retains the separate hard-link manifest`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let links = Data("=System/source\n+System/copy\n".utf8)
        let entries = try otaEntries(manifest: manifest()) + [
            .segment("E", [.file("AssetData/payloadv2/links.txt", links)]),
        ]
        let ota = try makeOTA(in: root, entries)
        _ = try stage(ota, in: root, key: keyText)
        #expect(try Data(contentsOf: root.appendingPathComponent("vm/OTAUserland/links.txt")) == links)
    }

    @Test func `full iPad staging requires and validates the separate hard-link phase`() throws {
        for includeLinks in [false, true] {
            let root = try makeRoot()
            defer { try? FileManager.default.removeItem(at: root) }
            let flash = root.appendingPathComponent("restore/Firmware/all_flash")
            try FileManager.default.createDirectory(at: flash, withIntermediateDirectories: true)
            _ = try vmFolder(root)
            let manifest = try PropertyListSerialization.data(fromPropertyList: [
                "ProductVersion": "27.0.1", "ProductBuildVersion": "24A446",
                "SupportedProductTypes": ["iPad16,1"],
            ], format: .xml, options: 0)
            let info = try PropertyListSerialization.data(fromPropertyList: ["OSVersion": "27.0.1"], format: .xml, options: 0)
            let payload = try encode([.directory("System"), .file("System/source", Data("resource".utf8))], in: root)
            var members: [Entry] = [
                .file("AssetData/Info.plist", info),
                .file("AssetData/boot/BuildManifest.plist", manifest),
                .file("AssetData/boot/Firmware/all_flash/DeviceTree.j410ap.im4p", Data("tree".utf8)),
                .file("AssetData/payloadv2/payload.000", payload),
                .file("AssetData/payloadv2/payload_chunks.txt", Data("0: 1000\n".utf8)),
            ]
            if includeLinks { members.append(.file("AssetData/payloadv2/links.txt", Data("=System/source\n+System/copy\n".utf8))) }
            let ota = try makeOTA(in: root, [.segment("E", members)])
            let device = try #require(VPhoneGuestDevice.named("iPad16,1"))
            let userland = root.appendingPathComponent("vm/OTAUserland")
            if includeLinks {
                let staged = try VPhoneOTAArchive.stageUserland(from: ota, key: keyText, device: device,
                    build: "24A446", deviceTreeDirectory: flash, userlandDirectory: userland, requireFullUpdate: true)
                #expect(staged.build == "24A446")
                #expect(FileManager.default.fileExists(atPath: userland.appendingPathComponent("links.txt").path))
            } else {
                #expect(throws: VPhoneOTAArchive.Error.self) {
                    try VPhoneOTAArchive.stageUserland(from: ota, key: keyText, device: device,
                        build: "24A446", deviceTreeDirectory: flash, userlandDirectory: userland, requireFullUpdate: true)
                }
                #expect(!FileManager.default.fileExists(atPath: userland.path))
            }
        }
    }

    @Test func `full updates reject prerequisite metadata before staging chunks`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        for value: Any in ["23G90", ["23G90"], 123] {
            let info = try PropertyListSerialization.data(fromPropertyList: ["PrerequisiteBuild": value], format: .xml, options: 0)
            #expect(throws: VPhoneOTAArchive.Error.self) {
                try VPhoneOTAArchive.checkFullUpdateInfo(info, of: root.appendingPathComponent("delta.aea"))
            }
        }
        let full = try PropertyListSerialization.data(fromPropertyList: ["OSVersion": "27.0.1"], format: .xml, options: 0)
        try VPhoneOTAArchive.checkFullUpdateInfo(full, of: root.appendingPathComponent("full.aea"))
        let nested = try PropertyListSerialization.data(fromPropertyList: ["MobileAssetProperties": ["PrerequisiteBuild": "23G90"]], format: .xml, options: 0)
        #expect(throws: VPhoneOTAArchive.Error.self) {
            try VPhoneOTAArchive.checkFullUpdateInfo(nested, of: root.appendingPathComponent("delta.aea"))
        }
    }

    @Test func `payload validation rejects traversal and cross-chunk symlink descendants`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let a = root.appendingPathComponent("payload.000")
        let b = root.appendingPathComponent("payload.001")
        for path in ["../outside", "/outside", "System/../outside", "System//outside"] {
            try encode([.file(path, Data())], in: root).write(to: a)
            #expect(throws: VPhoneOTAArchive.Error.self) {
                try VPhoneOTAArchive.validatePayloadPaths([a])
            }
        }
        try encode([.symlink("escape", "/private/tmp")], in: root).write(to: a)
        try encode([.file("escape/outside", Data())], in: root).write(to: b)
        #expect(throws: VPhoneOTAArchive.Error.self) {
            try VPhoneOTAArchive.validatePayloadPaths([a, b])
        }
        // A guest's absolute links are valid when extraction never follows them.
        try encode([.directory(""), .directory("System"), .file("System/test", Data()), .symlink("var", "/private/var")], in: root).write(to: a)
        try VPhoneOTAArchive.validatePayloadPaths([a])
    }

    @Test func `the fourth generation stages J265 from its encrypted 27 point 2 OTA`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        try FileManager.default.createDirectory(at: root.appendingPathComponent("flash"), withIntermediateDirectories: true)
        let data = try manifest(productTypes: ["AppleTV18,1"], build: "24K120", version: "27.2")
        let entries: [Entry] = [
            .segment("E", [
                .file("AssetData/boot/BuildManifest.plist", data),
                .file("AssetData/boot/Firmware/all_flash/DeviceTree.j265ap.im4p", Data("J265".utf8)),
                .file("AssetData/payloadv2/payload.000", chunk(0)),
                .file("AssetData/payloadv2/payload_chunks.txt", Data("0: 1000\n".utf8)),
            ]),
        ]
        let ota = try makeOTA(in: root, entries)
        let identity = try VPhoneOTAArchive.checkIdentity(of: ota, key: keyText, device: .appleTV18_1, build: "24K120")
        #expect(identity.version == "27.2" && identity.build == "24K120")
        let staged = try VPhoneOTAArchive.stageUserland(
            from: ota, key: keyText, device: .appleTV18_1, build: "24K120",
            deviceTreeDirectory: root.appendingPathComponent("flash"),
            userlandDirectory: root.appendingPathComponent("userland")
        )
        #expect(staged.chunks == ["payload.000"])
        #expect(staged.deviceTree.lastPathComponent == "DeviceTree.j265ap.im4p")
        #expect(try Data(contentsOf: staged.deviceTree) == Data("J265".utf8))
        #expect(throws: VPhoneOTAArchive.Error.self) {
            try VPhoneOTAArchive.checkIdentity(of: ota, key: keyText, device: .appleTV14_1)
        }
    }

    @Test(arguments: ["26.6", "27.0", "27.1", "27.2.1", "27.3", "28.2"])
    func `the fourth generation refuses other userland versions before staging`(version: String) throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let data = try manifest(productTypes: ["AppleTV18,1"], build: "24K120", version: version)
        let ota = try makeOTA(in: root, otaEntries(manifest: data))
        #expect {
            try VPhoneOTAArchive.checkIdentity(of: ota, key: keyText, device: .appleTV18_1)
        } throws: { error in
            guard case let .unsupportedVersion(_, productType, actual)? = error as? VPhoneOTAArchive.Error else { return false }
            return productType == "AppleTV18,1" && actual == version
        }
        let userland = root.appendingPathComponent("userland")
        #expect {
            try VPhoneOTAArchive.stageUserland(
                from: ota, key: keyText, device: .appleTV18_1, build: "24K120",
                deviceTreeDirectory: root.appendingPathComponent("flash"), userlandDirectory: userland
            )
        } throws: { error in
            guard case let .unsupportedVersion(_, productType, actual)? = error as? VPhoneOTAArchive.Error else { return false }
            return productType == "AppleTV18,1" && actual == version
        }
        #expect(!FileManager.default.fileExists(atPath: userland.path))
    }

    @Test func `an encrypted OTA stages its device tree, payload chunks and chunk list`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        _ = try vmFolder(root)
        let ota = try makeOTA(in: root, otaEntries(manifest: manifest()))

        let staged = try stage(ota, in: root, key: keyText)

        #expect(staged.version == "26.6" && staged.build == "23L773")
        #expect(staged.chunks == ["payload.000", "payload.001", "payload.002"])
        #expect(try Data(contentsOf: staged.deviceTree) == Data("tree j255ap".utf8))
        #expect(staged.deviceTree.path.hasSuffix("restore/Firmware/all_flash/DeviceTree.j255ap.im4p"))
        let userland = root.appendingPathComponent("vm/OTAUserland")
        let names = try FileManager.default.contentsOfDirectory(atPath: userland.path).sorted()
        #expect(names == ["payload.000", "payload.001", "payload.002", "payload_chunks.txt"])
        for index in 0 ..< 3 {
            #expect(try Data(contentsOf: userland.appendingPathComponent(String(format: "payload.%03d", index))) == chunk(index))
        }
        #expect(try String(contentsOf: userland.appendingPathComponent("payload_chunks.txt"), encoding: .utf8) == "0: 1000\n1: 1001\n2: 1002\n")
        // Nothing else from the OTA lands beside the device tree.
        let flash = try FileManager.default.contentsOfDirectory(atPath: staged.deviceTree.deletingLastPathComponent().path)
        #expect(flash == ["DeviceTree.j255ap.im4p"])
        #expect(try vmFolder(root) == ["OTAUserland"])
    }

    @Test func `a decrypted archive stages without a key`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        _ = try vmFolder(root)
        let ota = root.appendingPathComponent("decrypted.aar")
        try encode(otaEntries(manifest: manifest()), in: root).write(to: ota)

        let staged = try stage(ota, in: root, key: nil)
        #expect(staged.chunks.count == 3)
    }

    @Test func `an encrypted OTA needs its own key`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let ota = try makeOTA(in: root, otaEntries(manifest: manifest()))

        #expect {
            try stage(ota, in: root, key: nil)
        } throws: { error in
            if case .keyRequired(ota)? = error as? VPhoneOTAArchive.Error { true } else { false }
        }
        let other = SymmetricKey(size: .bits256).withUnsafeBytes { Data($0) }.base64EncodedString()
        #expect {
            try stage(ota, in: root, key: other)
        } throws: { error in
            if case .wrongKey? = error as? VPhoneOTAArchive.Error { true } else { false }
        }
        #expect(try vmFolder(root).isEmpty)
    }

    @Test func `another device's OTA stops before any chunk is written`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let ota = try makeOTA(in: root, otaEntries(manifest: manifest(productTypes: ["AppleTV11,1"])))

        #expect {
            try stage(ota, in: root, key: keyText)
        } throws: { error in
            guard case let .wrongDevice(_, types, expected)? = error as? VPhoneOTAArchive.Error else { return false }
            return types == ["AppleTV11,1"] && expected == "AppleTV14,1"
        }
        #expect(try vmFolder(root).isEmpty)
        let flash = root.appendingPathComponent("restore/Firmware/all_flash")
        #expect(try FileManager.default.contentsOfDirectory(atPath: flash.path).isEmpty)
    }

    @Test func `the OTA must be the IPSW's build`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let ota = try makeOTA(in: root, otaEntries(manifest: manifest(build: "23L760")))

        #expect {
            try stage(ota, in: root, key: keyText)
        } throws: { error in
            guard case let .wrongBuild(_, build, expected)? = error as? VPhoneOTAArchive.Error else { return false }
            return build == "23L760" && expected == "23L773"
        }
        #expect(try vmFolder(root).isEmpty)
    }

    @Test func `a chunk list that does not match the chunks leaves no userland`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let ota = try makeOTA(in: root, otaEntries(manifest: manifest(), list: "0: 1000\n1: 1001\n2: 1002\n3: 1003\n"))

        #expect {
            try stage(ota, in: root, key: keyText)
        } throws: { error in
            if case .inconsistentChunks? = error as? VPhoneOTAArchive.Error { true } else { false }
        }
        #expect(try vmFolder(root).isEmpty)
    }

    @Test func `an OTA without the device's tree is refused`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let ota = try makeOTA(in: root, otaEntries(manifest: manifest(), deviceTree: false))

        #expect {
            try stage(ota, in: root, key: keyText)
        } throws: { error in
            guard case let .missingMember(member, _)? = error as? VPhoneOTAArchive.Error else { return false }
            return member.hasSuffix("DeviceTree.j255ap.im4p")
        }
        #expect(try vmFolder(root).isEmpty)
    }

    @Test func `an existing userland folder is not replaced`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let userland = root.appendingPathComponent("vm/OTAUserland")
        try FileManager.default.createDirectory(at: userland, withIntermediateDirectories: true)
        let ota = try makeOTA(in: root, otaEntries(manifest: manifest()))

        #expect {
            try stage(ota, in: root, key: keyText)
        } throws: { error in
            if case .existingUserland? = error as? VPhoneOTAArchive.Error { true } else { false }
        }
    }

    @Test func `a truncated ZIP is refused before any OTA chunk is written`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let zip = root.appendingPathComponent("AppleTV5,3_26.6_23L773_Restore.ipsw")
        try Data("PK\u{3}\u{4}not an ota".utf8).write(to: zip)

        #expect {
            try stage(zip, in: root, key: keyText)
        } throws: { error in
            if case .unreadable? = error as? VPhoneOTAArchive.Error { true } else { false }
        }
    }

    // MARK: - Names and keys

    @Test func `only numbered payload chunks are staged`() {
        #expect(VPhoneOTAArchive.isChunkName("payload.000"))
        #expect(VPhoneOTAArchive.isChunkName("payload.036"))
        #expect(!VPhoneOTAArchive.isChunkName("payload.000.ecc"))
        #expect(!VPhoneOTAArchive.isChunkName("payload."))
        #expect(!VPhoneOTAArchive.isChunkName("payload_chunks.txt"))
        #expect(!VPhoneOTAArchive.isChunkName("payload.0/../x"))
        #expect(!VPhoneOTAArchive.isChunkName("../payload.000"))
    }

    @Test func `keys are 32 bytes of base64, with or without aea's prefix`() throws {
        let raw = keyText
        let plain = try VPhoneOTAArchive.symmetricKey(raw)
        let prefixed = try VPhoneOTAArchive.symmetricKey("base64:\(raw)\n")
        #expect(plain == key && prefixed == key)
        #expect(throws: VPhoneOTAArchive.Error.self) { try VPhoneOTAArchive.symmetricKey("not base64") }
        #expect(throws: VPhoneOTAArchive.Error.self) {
            try VPhoneOTAArchive.symmetricKey(Data(repeating: 1, count: 16).base64EncodedString())
        }
    }

    // MARK: - Source

    @Test func `a local OTA is read in place and a cached catalog OTA is reused`() async throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let local = root.appendingPathComponent("local.aea")
        try Data("AEA1local".utf8).write(to: local)
        #expect(try await VPhoneOTAArchive.resolve(local.path, release: nil, in: root) == local)

        let cached = Data("AEA1".utf8) + Data(repeating: 0, count: 60)
        let release = VPhoneOTARelease(
            productType: "AppleTV14,1",
            version: "26.6",
            build: "23L773",
            url: "https://example.invalid/ota.aea",
            size: Int64(cached.count),
            key: keyText,
        )
        let ota = root.appendingPathComponent("ota", isDirectory: true)
        try FileManager.default.createDirectory(at: ota, withIntermediateDirectories: true)
        let file = ota.appendingPathComponent(release.fileName)
        try cached.write(to: file)
        #expect(try await VPhoneOTAArchive.resolve(nil, release: release, in: root) == file)
        #expect(try await VPhoneOTAArchive.resolve(release.url, release: release, in: root) == file)
    }

    @Test func `a cached OTA of the wrong length is removed`() throws {
        let root = try makeRoot()
        defer { try? FileManager.default.removeItem(at: root) }
        let file = root.appendingPathComponent("AppleTV14,1_26.6_23L773_OTA.aea")
        try Data("AEA1short".utf8).write(to: file)

        #expect(try !VPhoneOTAArchive.reusable(file, size: 4_764_729_344))
        #expect(!FileManager.default.fileExists(atPath: file.path))
        try Data("AEA1".utf8).write(to: file)
        #expect(try VPhoneOTAArchive.reusable(file, size: 4))
        try Data("PK..".utf8).write(to: file)
        #expect(try !VPhoneOTAArchive.reusable(file, size: 4))
    }

    @Test func `a remote OTA outside the catalog gets a cache name of its own`() throws {
        let url = try #require(URL(string: "https://updates.cdn-apple.com/x/com_apple_MobileAsset_SoftwareUpdate/9daea812.aea"))
        let name = VPhoneOTAArchive.cacheName(for: url)
        #expect(name.hasPrefix("9daea812-") && name.hasSuffix(".aea"))
        #expect(name != VPhoneOTAArchive.cacheName(for: try #require(URL(string: "https://other.example/9daea812.aea"))))
    }
}