Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
9.9 KB
Raw Blame
// VPhoneFirmwareIndex.swift — where a restore image can be downloaded from.
//
// Two questions used to need two external programs:
//
//   iOS    "every IPSW Apple offers for iPhone17,3"
//          -> `ipsw download ipsw --device … --urls`
//   macOS  "the IPSW for macOS 26.1"
//          -> `ipsw download appledb --os macOS --version … --urls`
//
// Both are answered here, from one file: AppleDB's `main.json.xz`. It is 8 MB
// over the wire, 95 MB of JSON and 18,000 releases once unpacked, and it holds
// every OS, every build, the device each one applies to and the CDN links. One
// request answers both questions and every follow-up, which is why it is worth
// downloading whole rather than walking AppleDB's per-build files — that would
// be hundreds of requests to answer one.
//
// Apple's own iTunes version plist was the obvious alternative and is not
// enough: it lists only the CURRENT release per device. Every older build is a
// `SameAs` pointer at it, so a device like iPhone17,3 comes back with exactly
// one URL where the catalogue needs sixty-eight.
//
// The macOS side exists for one reason: `apfs_sealvolume` is not in an iPhone
// restore image, only in a macOS one. Since 2025 the two share a marketing
// version, so "the macOS that goes with iOS 26.1" is just "macOS 26.1".

import Compression
import Foundation

public enum VPhoneFirmwareIndex {
    public enum Error: Swift.Error, LocalizedError {
        case fetchFailed(URL, Int)
        case unexpectedShape(URL)
        case decompressionFailed
        case noRelease(String, String)

        public var errorDescription: String? {
            switch self {
            case let .fetchFailed(url, _):
                "Unable to download the firmware catalog from \(url.host() ?? url.absoluteString). Check your connection and try again."
            case let .unexpectedShape(url):
                "Unable to read the firmware catalog from \(url.host() ?? url.absoluteString). Try again later."
            case .decompressionFailed:
                "Unable to read the firmware catalog. Try again later."
            case let .noRelease(os, what):
                "No released \(os) \(what) found in the firmware catalog."
            }
        }
    }

    public struct Release: Sendable {
        public let os: String
        public let version: String
        public let build: String
        public let url: URL
    }

    static let catalogueURL = URL(string: "https://api.appledb.dev/main.json.xz")!

    // MARK: - Queries

    /// Every released iOS restore URL for one device identifier, newest first.
    /// AppleDB files an iPad's releases under iPadOS, a watch's under watchOS.
    public static func restoreURLs(forDevice device: String) async throws -> [String] {
        try await releases(os: device.hasPrefix("iPad") ? "iPadOS" : device.hasPrefix("Watch") ? "watchOS" : "iOS", device: device)
            .map(\.url.absoluteString)
    }

    /// The macOS whose `apfs_sealvolume` seals a system of iOS `version`.
    ///
    /// Before 2025 the two did not share a marketing version: iOS 18.x.y goes
    /// with macOS 15.x.y. Not every iOS release has a macOS twin (18.2.1 has
    /// only 15.2), and the catalogue misses some releases, so without an exact
    /// match the newest release of the same major below it is taken.
    public static func sealToolRelease(forOSVersion version: String) async throws -> Release {
        let macOS = try await releases(os: "macOS", device: nil)
        return try sealToolRelease(forOSVersion: version, in: macOS)
    }

    /// ``sealToolRelease(forOSVersion:)`` over a given list of macOS releases.
    static func sealToolRelease(forOSVersion version: String, in macOS: [Release]) throws -> Release {
        func numbers(_ version: String) -> [Int] {
            version.split(separator: ".").compactMap { Int($0) }
        }
        var target = numbers(version)
        if target.first == 18 {
            target[0] = 15
        }
        // The same major, and not newer than the target.
        let candidates = macOS.filter {
            let other = numbers($0.version)
            return other.first == target.first && !target.lexicographicallyPrecedes(other)
        }
        guard let release = candidates.max(by: { numbers($0.version).lexicographicallyPrecedes(numbers($1.version)) }) else {
            throw Error.noRelease("macOS", target.map(String.init).joined(separator: "."))
        }
        return release
    }

    /// Released `.ipsw` entries for an OS, optionally narrowed to one device,
    /// sorted newest version first.
    ///
    /// `beta` and `rc` are both excluded. A release-candidate build is signed
    /// and installable, but it is superseded within days and a catalogue that
    /// offered one as "the 26.1 image" would hand out a different file
    /// depending on the week.
    public static func releases(os: String, device: String?) async throws -> [Release] {
        let entries = try await catalogue()
        var out: [Release] = []
        for entry in entries {
            guard entry["osStr"] as? String == os,
                  entry["beta"] as? Bool != true,
                  entry["rc"] as? Bool != true,
                  let version = entry["version"] as? String,
                  let build = entry["build"] as? String ?? entry["uniqueBuild"] as? String,
                  let sources = entry["sources"] as? [[String: Any]]
            else { continue }
            if let device, !((entry["deviceMap"] as? [String])?.contains(device) ?? false) {
                continue
            }

            for source in sources where source["type"] as? String == "ipsw" {
                // A single release carries one source per hardware family, so
                // the device has to be matched on the SOURCE as well: the
                // Universal Mac image and an iPhone image sit side by side.
                if let device, let map = source["deviceMap"] as? [String], !map.contains(device) {
                    continue
                }
                guard let links = source["links"] as? [[String: Any]] else { continue }
                let active = links.filter { $0["active"] as? Bool != false }
                // `preferred` is the https CDN link; the rest are plain-http
                // mirrors of the same bytes.
                let chosen = active.first { $0["preferred"] as? Bool == true } ?? active.first
                if let string = chosen?["url"] as? String, let url = URL(string: string) {
                    out.append(Release(os: os, version: version, build: build, url: url))
                    break
                }
            }
        }
        return out.sorted { compareVersions($0.version, $1.version) == .orderedDescending }
    }

    /// Numeric, component by component: "26.10" is newer than "26.9", which
    /// string ordering gets backwards, and the firmware picker shows this list
    /// to a human.
    static func compareVersions(_ a: String, _ b: String) -> ComparisonResult {
        let lhs = a.split(separator: ".").map { Int($0) ?? 0 }
        let rhs = b.split(separator: ".").map { Int($0) ?? 0 }
        for i in 0 ..< max(lhs.count, rhs.count) {
            let l = i < lhs.count ? lhs[i] : 0
            let r = i < rhs.count ? rhs[i] : 0
            if l != r {
                return l < r ? .orderedAscending : .orderedDescending
            }
        }
        return .orderedSame
    }

    // MARK: - The catalogue

    static func catalogue() async throws -> [[String: Any]] {
        let data = try await catalogueData()
        guard let root = try JSONSerialization.jsonObject(with: data) as? [String: Any],
              let entries = root["ios"] as? [[String: Any]]
        else { throw Error.unexpectedShape(catalogueURL) }
        return entries
    }

    private static func catalogueData() async throws -> Data {
        let session = URLSession(configuration: .ephemeral)
        defer { session.invalidateAndCancel() }
        let (compressed, response) = try await session.data(from: catalogueURL)
        if let http = response as? HTTPURLResponse, http.statusCode != 200 {
            throw Error.fetchFailed(catalogueURL, http.statusCode)
        }
        return try decompressXZ(compressed)
    }

    /// `.xz`, through libcompression.
    ///
    /// `COMPRESSION_LZMA` reads the xz container, not bare LZMA, which is what
    /// the name suggests and not what it does. Streaming rather than
    /// `compression_decode_buffer` because the output size is not known in
    /// advance and is two orders of magnitude larger than the input.
    static func decompressXZ(_ input: Data) throws -> Data {
        var stream = compression_stream(
            dst_ptr: UnsafeMutablePointer<UInt8>(bitPattern: 1)!,
            dst_size: 0,
            src_ptr: UnsafePointer<UInt8>(bitPattern: 1)!,
            src_size: 0,
            state: nil,
        )
        guard compression_stream_init(&stream, COMPRESSION_STREAM_DECODE, COMPRESSION_LZMA)
            == COMPRESSION_STATUS_OK
        else { throw Error.decompressionFailed }
        defer { compression_stream_destroy(&stream) }

        let chunkSize = 1 << 20
        let chunk = UnsafeMutablePointer<UInt8>.allocate(capacity: chunkSize)
        defer { chunk.deallocate() }

        var output = Data()
        output.reserveCapacity(input.count * 12)
        var status = COMPRESSION_STATUS_OK
        input.withUnsafeBytes { raw in
            stream.src_ptr = raw.baseAddress!.assumingMemoryBound(to: UInt8.self)
            stream.src_size = raw.count
            repeat {
                stream.dst_ptr = chunk
                stream.dst_size = chunkSize
                status = compression_stream_process(
                    &stream, Int32(COMPRESSION_STREAM_FINALIZE.rawValue),
                )
                output.append(chunk, count: chunkSize - stream.dst_size)
            } while status == COMPRESSION_STATUS_OK
        }
        guard status == COMPRESSION_STATUS_END else { throw Error.decompressionFailed }
        return output
    }
}