Run a virtual iPhone on an Apple Silicon Mac.
Swift
import Darwin
import Foundation
import VPhoneCoreKit
// MARK: - Errors
public enum VPhoneBundleTransferError: Error, Equatable, CustomStringConvertible, LocalizedError {
/// The archive is readable, but it is not a VM export.
case badArchive(String)
public var description: String {
switch self {
case let .badArchive(message): message
}
}
public var errorDescription: String? {
description
}
}
// MARK: - VPhoneBundleTransfer
/// `vm export` and `vm import`.
///
/// It lives here, and not in `VPhoneCoreKit`, because it needs libarchive. It
/// lives here, and not in the VM kit, because `vphone-cli` deliberately does
/// not import the kit — see the note on that target in `Package.swift` —
/// and `vphone-cli vm export` has to keep working. `VPhoneArchiveKit` sits above
/// `VPhoneCoreKit` and needs neither Virtualization nor AppKit, which is exactly
/// the altitude this wants.
///
/// The format contract is fixed and older archives are already out there:
/// gnutar, `.tzst` at zstd 3, `.txz` at xz 9, extension chosen from the
/// preset. `importArchive` detects the compressor, so it reads anything an
/// older copy of this program produced — and `/usr/bin/tar` reads what this
/// produces.
public enum VPhoneBundleTransfer {
/// Compression preset for `export`. Both import transparently —
/// `importArchive` auto-detects the compressor when it extracts.
public enum ExportCompression: String, CaseIterable, Sendable {
case fast, max
/// zstd 3 and xz 9. Not tuning knobs: archives with these settings
/// have been handed to users, and the levels are part of what `.tzst`
/// and `.txz` mean here.
var archiveCompression: VPhoneArchiveCompression {
switch self {
case .fast: .zstd(level: 3)
case .max: .xz(level: 9)
}
}
/// Extension for auto-named output when `export`'s destination is a
/// directory.
public var fileExtension: String {
archiveCompression.tarExtension
}
}
// MARK: - Export
/// When `to` is an existing directory, the archive is written inside it as
/// `<name>.<compression.fileExtension>`. Returns the resolved output URL.
///
/// `progress` is called with `(bytesDone, totalBytes)`, where `totalBytes`
/// is the bundle's on-disk logical size minus the excludes, and `bytesDone`
/// is the uncompressed payload packed so far. It ticks per megabyte rather
/// than per member: a bundle is one huge `Disk.img` and a few small files.
@discardableResult
public static func export(
bundleNamed name: String,
to outFile: URL,
includeIPSW: Bool,
compression: ExportCompression = .fast,
in library: VPhoneLibrary,
progress: ((Int64, Int64) -> Void)? = nil,
) throws -> URL {
_ = try library.bundle(named: name) // validate it exists
var isDir: ObjCBool = false
let outFile = FileManager.default.fileExists(atPath: outFile.path, isDirectory: &isDir)
&& isDir.boolValue
? outFile.appendingPathComponent("\(name).\(compression.fileExtension)")
: outFile
let bundleDir = library.url(forName: name)
var excludes = VPhoneBundleOperations.exportExcludePatterns
if !includeIPSW {
excludes.append("*_Restore*")
// The kept boot-chain originals go with the restore tree they came
// from. On their own they describe firmware the archive does not
// carry, and the importer would have to delete them before its first
// `fw prepare` could be trusted.
excludes.append(VPhoneBundleOperations.firmwareOriginalsDirectoryName)
}
let total = progress != nil
? archivedLogicalSize(bundleDir: bundleDir, includeIPSW: includeIPSW)
: 0
// gnutar, not the pax default: pax extended headers used to break the
// consumer of the old two-stage pipe, and — still true — ustar cannot
// carry a member over 8 GB, which Disk.img is.
//
// topLevel is the bundle's own name, so the archive holds exactly one
// top-level directory. importArchive checks for that, and so does
// every export already on disk.
try VPhoneArchiveWriter.create(
archive: outFile,
from: bundleDir,
topLevel: name,
format: .gnutar,
compression: compression.archiveCompression,
excluding: excludes,
bytesPacked: progress.map { report in { done in report(done, total) } },
)
return outFile
}
/// On-disk logical size of the members `export` will archive, mirroring the
/// exclude patterns so the progress total matches the streamed bytes.
///
/// A hardlinked file is counted once, no matter how many names it has under
/// the bundle. `VPhoneArchiveWriter` runs a link resolver: the first name is
/// stored with its contents and every later name becomes a size-0 hardlink
/// reference, so those later names contribute nothing to `bytesPacked`.
/// Adding each name's size here made the total larger than anything that
/// could ever be packed, and the bar could not reach 100%.
private static func archivedLogicalSize(bundleDir: URL, includeIPSW: Bool) -> Int64 {
let keys: [URLResourceKey] = [.isRegularFileKey, .fileSizeKey, .linkCountKey]
let fm = FileManager.default
guard let en = fm.enumerator(at: bundleDir, includingPropertiesForKeys: keys)
else { return 0 }
let prefix = bundleDir.path.count + 1 // members are relative to the bundle
var total: Int64 = 0
var countedInodes = Set<Inode>()
for case let url as URL in en {
guard url.path.count > prefix else { continue }
let rel = String(url.path.dropFirst(prefix))
let originals = VPhoneBundleOperations.firmwareOriginalsDirectoryName
if !includeIPSW, rel.contains("_Restore")
|| rel == originals || rel.hasPrefix(originals + "/")
{
en.skipDescendants(); continue
}
// The same match as VPhoneArchiveWriter's: the relative path or its
// last component, and an excluded directory takes its subtree.
let name = url.lastPathComponent
if VPhoneBundleOperations.exportExcludePatterns.contains(where: {
fnmatch($0, rel, 0) == 0 || fnmatch($0, name, 0) == 0
}) {
en.skipDescendants(); continue
}
guard let vals = try? url.resourceValues(forKeys: Set(keys)),
vals.isRegularFile == true else { continue }
// linkCount == 1 is every file in an ordinary bundle, and it costs
// no extra syscall — only a genuinely linked file is stat'd again
// to find out which inode it is a name for.
if (vals.linkCount ?? 1) > 1 {
guard let inode = Inode(path: url.path), countedInodes.insert(inode).inserted
else { continue }
}
total += Int64(vals.fileSize ?? 0)
}
return total
}
/// Identity of a file's contents: device plus inode, which is what makes
/// two names the same file rather than two files of equal size.
private struct Inode: Hashable {
let device: dev_t
let number: ino_t
init?(path: String) {
var info = stat()
guard lstat(path, &info) == 0 else { return nil }
device = info.st_dev
number = info.st_ino
}
}
// MARK: - Import
/// Extracts (auto-detecting gzip/zstd/xz) into a private staging dir, then
/// promotes the single top-level bundle to the library.
///
/// `progress` is called with `(bytesDone, totalBytes)` against the archive
/// file's size on disk — compressed bytes, which is what the user can see
/// in Finder.
public static func importArchive(
from inFile: URL,
name: String?,
in library: VPhoneLibrary,
progress: ((Int64, Int64) -> Void)? = nil,
isCancelled: (() -> Bool)? = nil,
) throws -> VPhoneBundle {
let fm = FileManager.default
// Fail fast when the destination name is already known (explicit rename).
if let name {
try VPhoneBundleOperations.requireValidName(name)
if fm.fileExists(atPath: library.url(forName: name).path) {
throw VPhoneLibraryError.alreadyExists(name: name)
}
}
// Extract into a private staging dir so the archive's OWN top-level name
// can never clobber/merge into an existing bundle of that name; only the
// validated destination name is ever placed into the library.
try fm.createDirectory(at: library.root, withIntermediateDirectories: true)
let staging = library.root.appendingPathComponent(".import-\(UUID().uuidString)")
try fm.createDirectory(at: staging, withIntermediateDirectories: true)
defer { try? fm.removeItem(at: staging) }
let total = progress != nil ? fileByteSize(inFile) : 0
// .intoHostDirectory, and specifically NOT the guest-volume preset: an
// import is an archive from another machine landing in the user's home
// directory, so the umask applies and setuid/setgid do not survive —
// what `/usr/bin/tar -xf` (no -p) gave when this shelled out. The
// modes a VM bundle actually needs are its own files' 0644/0755;
// nothing in it has any business being setuid.
try VPhoneArchiveExtractor.extract(
inFile,
into: staging,
options: .intoHostDirectory,
bytesRead: progress.map { report in { done in report(done, total) } },
isCancelled: isCancelled,
)
// A tar reader stops at the end-of-archive marker, which in a
// compressed file can sit short of the last byte, so the read position
// alone would leave the bar just under full on a finished import.
progress?(total, total)
let entries = try fm.contentsOfDirectory(atPath: staging.path)
guard entries.count == 1, let archived = entries.first else {
throw VPhoneBundleTransferError.badArchive(
"This archive is not a VM export. Choose an archive created by 'vphone-cli vm export'.",
)
}
let finalName = name ?? archived
try VPhoneBundleOperations.requireValidName(finalName)
let dst = library.url(forName: finalName)
if fm.fileExists(atPath: dst.path) {
throw VPhoneLibraryError.alreadyExists(name: finalName)
}
let extracted = staging.appendingPathComponent(archived)
// The extractor restores symbolic links as they were stored, so the
// single top-level entry could itself be a link to a directory
// anywhere on this Mac. lstat, not fileExists, which follows it.
guard fileType(at: extracted) == S_IFDIR else {
throw VPhoneBundleTransferError.badArchive(
"This archive does not contain a VM folder. Choose an archive created by 'vphone-cli vm export'.",
)
}
guard VPhoneVirtualMachineManifest.fileKind(at: extracted.appendingPathComponent("config.plist"))
== .regularFile
else {
throw VPhoneBundleTransferError.badArchive(
"This archive does not contain a valid VM. Choose an archive created by 'vphone-cli vm export'.",
)
}
try checkSymbolicLinks(in: extracted, depth: 0)
let bundle = try VPhoneBundle.load(at: extracted)
try checkBundleFiles(of: bundle)
try fm.moveItem(at: extracted, to: dst)
return VPhoneBundle(url: dst, manifest: bundle.manifest)
}
// MARK: - Import Checks
/// The `S_IFMT` bits `lstat` reports, or nil when there is no entry.
private static func fileType(at url: URL) -> mode_t? {
var info = stat()
guard lstat(url.path, &info) == 0 else { return nil }
return info.st_mode & S_IFMT
}
/// A VM export never needs a link that leaves the bundle, and vphone-vm
/// and vphone-cli open, overwrite and chmod the bundle's files, so an
/// absolute or escaping link would reach host files as the importing user.
/// Relative links that stay inside, such as those in an unpacked
/// `*_Restore` tree, are kept.
///
/// `depth` is how many directories below the bundle root `dir` is. Only
/// real directories are walked, never a linked one, so a target's leading
/// `..` components climb real directories and can be counted against
/// `depth`. A `..` after a named component is refused: that name could be
/// a link itself, and then the climb would not be where it looks.
private static func checkSymbolicLinks(in dir: URL, depth: Int) throws {
let fm = FileManager.default
let names: [String]
do {
names = try fm.contentsOfDirectory(atPath: dir.path)
} catch {
throw VPhoneBundleTransferError.badArchive(
"This archive contains a folder that cannot be read. Choose an archive created by 'vphone-cli vm export'.",
)
}
for name in names {
let url = dir.appendingPathComponent(name)
switch fileType(at: url) {
case S_IFDIR:
try checkSymbolicLinks(in: url, depth: depth + 1)
case S_IFLNK:
let target = try? fm.destinationOfSymbolicLink(atPath: url.path)
guard let target, linkTargetStaysInside(target, depth: depth) else {
throw VPhoneBundleTransferError.badArchive(
"This archive contains a symbolic link that points outside the VM folder. Choose an archive created by 'vphone-cli vm export'.",
)
}
default:
continue
}
}
}
private static func linkTargetStaysInside(_ target: String, depth: Int) -> Bool {
guard !target.isEmpty, !target.hasPrefix("/") else { return false }
var climbs = 0
var descended = false
for component in target.split(separator: "/", omittingEmptySubsequences: true) {
switch component {
case ".":
continue
case "..":
guard !descended else { return false }
climbs += 1
default:
descended = true
}
}
return climbs <= depth
}
/// config.plist, the files the manifest names and the files vphone writes
/// at the bundle root must be regular files when present. The symbolic
/// link walk already refused links that leave the bundle; this also
/// refuses in-bundle links and FIFOs or devices in these places.
private static func checkBundleFiles(of bundle: VPhoneBundle) throws {
let names = ["config.plist", "restore-info.json", "udid-prediction.txt"]
+ bundle.manifest.bundleFileNames.map(\.name)
for name in names
where VPhoneVirtualMachineManifest.fileKind(at: bundle.url.appendingPathComponent(name)) == .other
{
throw VPhoneBundleTransferError.badArchive(
"This archive's VM file \(name) is a symbolic link or not a regular file. Choose an archive created by 'vphone-cli vm export'.",
)
}
}
private static func fileByteSize(_ url: URL) -> Int64 {
let size = (try? url.resourceValues(forKeys: [.fileSizeKey]))?.fileSize
return Int64(size ?? 0)
}
}