Run a virtual iPhone on an Apple Silicon Mac.
Swift
// VPhoneRemoteZip.swift — read one file out of a remote .zip without fetching it.
//
// An IPSW is a zip, and a macOS one is about 18 GB. Two files inside it are
// wanted — BuildManifest.plist and a restore ramdisk — and together they are a
// few megabytes. `ipsw download appledb --pattern` did this with HTTP range
// requests; this is the same trick, and removing it was the last thing keeping
// `ipsw` in `fw_prepare.sh`.
//
// The shape of a zip makes it possible: the directory of contents is at the
// END, so three requests find any member. Read the last 64 KiB and look for the
// end-of-central-directory record; follow it to the central directory and parse
// the entries; then range-fetch the one entry's local header and data.
//
// ZIP64 is not optional here. A zip crosses into it at 4 GiB, and every IPSW
// is well past that, so the 32-bit fields in the classic records are all
// 0xFFFFFFFF and the real values live in the ZIP64 records and in each entry's
// extra field.
import Compression
import Foundation
public struct VPhoneRemoteZip: Sendable {
private static let sharedSession = URLSession(configuration: .ephemeral)
public struct Entry: Sendable {
public let name: String
public let compressedSize: UInt64
public let uncompressedSize: UInt64
public let localHeaderOffset: UInt64
/// 0 = stored, 8 = deflate. IPSWs use both: big payloads are stored,
/// small text is deflated.
public let compressionMethod: UInt16
}
public enum Error: Swift.Error, LocalizedError {
case notSeekable(URL)
case noEndOfCentralDirectory(URL)
case malformed(String)
case notFound(String)
case unsupportedCompression(UInt16)
case http(Int, URL)
public var errorDescription: String? {
switch self {
case let .notSeekable(url):
"\(url.host() ?? "The server") does not support partial downloads, so the archive must be downloaded in full."
case let .noEndOfCentralDirectory(url):
"\(url.lastPathComponent) is not a valid ZIP archive. Download it again."
case .malformed:
"The ZIP archive is damaged. Download it again."
case let .notFound(name):
"The archive does not contain '\(name)'."
case .unsupportedCompression:
"The archive uses an unsupported compression method. Download the full IPSW instead."
case let .http(_, url):
"Unable to download from \(url.host() ?? url.absoluteString). Try again later."
}
}
}
public let url: URL
public let entries: [Entry]
let session: URLSession
// MARK: - Opening
public static func open(_ url: URL) async throws -> VPhoneRemoteZip {
try await open(url, session: sharedSession)
}
static func open(_ url: URL, session: URLSession) async throws -> VPhoneRemoteZip {
let size = try await contentLength(of: url, session: session)
// The EOCD is 22 bytes plus up to 64 KiB of comment, so the last 64 KiB
// and change always contains it.
let tailLength = min(size, 66000)
let tail = try await range(of: url, from: size - tailLength, count: tailLength, session: session)
guard let eocd = lastIndex(of: [0x50, 0x4B, 0x05, 0x06], in: tail) else {
throw Error.noEndOfCentralDirectory(url)
}
var directoryOffset = UInt64(u32(tail, eocd + 16))
var directorySize = UInt64(u32(tail, eocd + 12))
var entryCount = Int(u16(tail, eocd + 10))
// 0xFFFFFFFF in any of those means the real value is in the ZIP64
// end-of-central-directory, which the locator right before the EOCD
// points at. Every IPSW takes this path.
if directoryOffset == 0xFFFF_FFFF || directorySize == 0xFFFF_FFFF || entryCount == 0xFFFF {
guard let locator = lastIndex(of: [0x50, 0x4B, 0x06, 0x07], in: tail) else {
throw Error.malformed("ZIP64 fields present but no ZIP64 locator")
}
let zip64Offset = u64(tail, locator + 8)
let record = try await range(of: url, from: zip64Offset, count: 56, session: session)
guard record.count >= 56, record.prefix(4) == Data([0x50, 0x4B, 0x06, 0x06]) else {
throw Error.malformed("ZIP64 end-of-central-directory not where the locator says")
}
entryCount = Int(u64(record, 32))
directorySize = u64(record, 40)
directoryOffset = u64(record, 48)
}
let directory = try await range(of: url, from: directoryOffset, count: directorySize, session: session)
return try VPhoneRemoteZip(
url: url,
entries: parseCentralDirectory(directory, expected: entryCount),
session: session,
)
}
// MARK: - Reading a member
/// The entry named `suffix`, or — failing that — the shallowest one whose
/// path ends with it.
///
/// An exact match first, and shallowest after, because an IPSW carries
/// several files called BuildManifest.plist: one at the root, which
/// describes the restore, and others inside payloads. Taking whichever came
/// first in the central directory picked a nested one and then failed to
/// find a ramdisk in it.
public func entry(endingWith suffix: String) throws -> Entry {
if let exact = entries.first(where: { $0.name == suffix }) {
return exact
}
let matches = entries.filter { $0.name.hasSuffix("/" + suffix) || $0.name.hasSuffix(suffix) }
guard let shallowest = matches.min(by: {
($0.name.count(where: { $0 == "/" }), $0.name.count)
< ($1.name.count(where: { $0 == "/" }), $1.name.count)
}) else { throw Error.notFound(suffix) }
return shallowest
}
public func read(_ entry: Entry) async throws -> Data {
// The local header repeats the name and carries its own extra field,
// whose length usually differs from the central directory's — so the
// data offset has to be computed from the local header, not assumed.
let header = try await Self.range(of: url, from: entry.localHeaderOffset, count: 30, session: session)
guard header.count == 30, header.prefix(4) == Data([0x50, 0x4B, 0x03, 0x04]) else {
throw Error.malformed("no local file header at \(entry.localHeaderOffset)")
}
let nameLength = UInt64(Self.u16(header, 26))
let extraLength = UInt64(Self.u16(header, 28))
let dataOffset = entry.localHeaderOffset + 30 + nameLength + extraLength
let raw = try await Self.range(of: url, from: dataOffset, count: entry.compressedSize, session: session)
switch entry.compressionMethod {
case 0: return raw
case 8: return try Self.inflate(raw, expecting: Int(entry.uncompressedSize))
default: throw Error.unsupportedCompression(entry.compressionMethod)
}
}
/// Raw DEFLATE, which is what a zip member stores — no zlib header, no
/// checksum. `COMPRESSION_ZLIB` is libcompression's name for exactly that,
/// misleadingly; it is the right constant.
static func inflate(_ data: Data, expecting size: Int) throws -> Data {
guard size > 0 else { return Data() }
var output = Data(count: size)
let written = output.withUnsafeMutableBytes { destination -> Int in
data.withUnsafeBytes { source in
compression_decode_buffer(
destination.baseAddress!.assumingMemoryBound(to: UInt8.self), size,
source.baseAddress!.assumingMemoryBound(to: UInt8.self), data.count,
nil, COMPRESSION_ZLIB,
)
}
}
guard written == size else {
throw Error.malformed("deflate produced \(written) bytes, the directory said \(size)")
}
return output
}
// MARK: - HTTP
/// The archive's size, once the server is known to answer range requests.
///
/// `Accept-Ranges: bytes` on the HEAD answer settles it. Without the header
/// the server is asked for one byte: some CDN edges in front of
/// updates.cdn-apple.com leave the header out of every HEAD answer and still
/// serve ranges, as every cloudOS URL did from China in October 2026.
static func contentLength(of url: URL, session: URLSession) async throws -> UInt64 {
var request = URLRequest(url: url)
request.httpMethod = "HEAD"
let (_, response) = try await session.data(for: request)
guard let http = response as? HTTPURLResponse else { throw Error.notSeekable(url) }
guard http.statusCode == 200 else { throw Error.http(http.statusCode, url) }
guard http.expectedContentLength > 0 else { throw Error.notSeekable(url) }
if !(http.value(forHTTPHeaderField: "Accept-Ranges") ?? "").contains("bytes") {
try await probeRange(of: url, session: session)
}
return UInt64(http.expectedContentLength)
}
/// Ask for the first byte and accept only a 206. The body is never read: a
/// server that ignores `Range` answers 200 and starts sending the whole
/// archive, so the request is cancelled as soon as its headers arrive.
private static func probeRange(of url: URL, session: URLSession) async throws {
var request = URLRequest(url: url)
request.setValue("bytes=0-0", forHTTPHeaderField: "Range")
let (bytes, response) = try await session.bytes(for: request)
bytes.task.cancel()
guard (response as? HTTPURLResponse)?.statusCode == 206 else { throw Error.notSeekable(url) }
}
private static func range(of url: URL, from offset: UInt64, count: UInt64, session: URLSession) async throws -> Data {
guard count > 0 else { return Data() }
var request = URLRequest(url: url)
request.setValue("bytes=\(offset)-\(offset + count - 1)", forHTTPHeaderField: "Range")
let (data, response) = try await session.data(for: request)
guard let http = response as? HTTPURLResponse else { throw Error.notSeekable(url) }
// 206 is the only acceptable answer. A 200 means the server ignored the
// header and is sending the whole 18 GB, which is exactly the thing this
// type exists to avoid.
guard http.statusCode == 206 else { throw Error.notSeekable(url) }
return data
}
// MARK: - Parsing
private static func parseCentralDirectory(_ data: Data, expected: Int) throws -> [Entry] {
var entries: [Entry] = []
entries.reserveCapacity(expected)
var offset = 0
while offset + 46 <= data.count {
guard data[data.startIndex + offset ..< data.startIndex + offset + 4]
== Data([0x50, 0x4B, 0x01, 0x02])
else { break }
let method = u16(data, offset + 10)
var compressed = UInt64(u32(data, offset + 20))
var uncompressed = UInt64(u32(data, offset + 24))
let nameLength = Int(u16(data, offset + 28))
let extraLength = Int(u16(data, offset + 30))
let commentLength = Int(u16(data, offset + 32))
var localOffset = UInt64(u32(data, offset + 42))
let nameStart = data.startIndex + offset + 46
let name = String(decoding: data[nameStart ..< nameStart + nameLength], as: UTF8.self)
// The ZIP64 extra field (id 0x0001) carries whichever of the three
// 32-bit fields were written as 0xFFFFFFFF, in this fixed order and
// ONLY for those — so they have to be consumed conditionally.
if compressed == 0xFFFF_FFFF || uncompressed == 0xFFFF_FFFF || localOffset == 0xFFFF_FFFF {
var cursor = offset + 46 + nameLength
let extraEnd = cursor + extraLength
while cursor + 4 <= extraEnd {
let id = u16(data, cursor)
let length = Int(u16(data, cursor + 2))
if id == 0x0001 {
var field = cursor + 4
if uncompressed == 0xFFFF_FFFF, field + 8 <= cursor + 4 + length {
uncompressed = u64(data, field); field += 8
}
if compressed == 0xFFFF_FFFF, field + 8 <= cursor + 4 + length {
compressed = u64(data, field); field += 8
}
if localOffset == 0xFFFF_FFFF, field + 8 <= cursor + 4 + length {
localOffset = u64(data, field)
}
break
}
cursor += 4 + length
}
}
entries.append(Entry(
name: name,
compressedSize: compressed,
uncompressedSize: uncompressed,
localHeaderOffset: localOffset,
compressionMethod: method,
))
offset += 46 + nameLength + extraLength + commentLength
}
guard !entries.isEmpty else { throw Error.malformed("central directory held no entries") }
return entries
}
private static func lastIndex(of needle: [UInt8], in data: Data) -> Int? {
guard data.count >= needle.count else { return nil }
let bytes = [UInt8](data)
var i = bytes.count - needle.count
while i >= 0 {
if Array(bytes[i ..< i + needle.count]) == needle {
return i
}
i -= 1
}
return nil
}
private static func u16(_ d: Data, _ o: Int) -> UInt16 {
d.withUnsafeBytes { $0.loadUnaligned(fromByteOffset: o, as: UInt16.self).littleEndian }
}
private static func u32(_ d: Data, _ o: Int) -> UInt32 {
d.withUnsafeBytes { $0.loadUnaligned(fromByteOffset: o, as: UInt32.self).littleEndian }
}
private static func u64(_ d: Data, _ o: Int) -> UInt64 {
d.withUnsafeBytes { $0.loadUnaligned(fromByteOffset: o, as: UInt64.self).littleEndian }
}
}