Run a virtual iPhone on an Apple Silicon Mac.
Swift
feat(archive): add VPhoneArchive and vphone-archive, replacing four programs
Lakr0972f5d8faaf
diff --git a/.gitignore b/.gitignoreindex c9474966..5c5f39c9 100644--- a/.gitignore+++ b/.gitignore@@ -327,6 +327,12 @@ __marimo__/scripts/vphoned/vphoned/cfw_input/sources/VPhoneCore/VPhoneBuildInfo.swift+# libarchive drops zero-byte tar.XXXXXXXX files in the process's working+# directory while restoring macOS metadata — a relative mkstemp template in+# its own sources, so TMPDIR does not redirect them. Harmless, but they should+# not be committed. Worth remembering that `vphone-archive` run as root during+# an install will leave them in whatever directory the installer is in.+tar.????????setup_logs//testing_results/.ida-mcpdiff --git a/.gitmodules b/.gitmodulesindex 0357c64d..439cebda 100644--- a/.gitmodules+++ b/.gitmodules@@ -22,3 +22,6 @@[submodule "scripts/repos/insert_dylib"]path = scripts/repos/insert_dyliburl = https://github.com/tyilo/insert_dylib.git+[submodule "vendor/libarchive.xcframework"]+ path = vendor/libarchive.xcframework+ url = https://github.com/Lakr233/libarchive.xcframework.gitdiff --git a/Makefile b/Makefileindex dd543826..d3855da9 100644--- a/Makefile+++ b/Makefile@@ -41,11 +41,13 @@ SCRIPTS := scriptsBINARY := .build/release/vphone-cliVM_BINARY := .build/release/vphone-vmLETMEIN_BINARY := .build/release/vphone-letmein+ARCHIVE_BINARY := .build/release/vphone-archivePATCHER_BINARY := .build/debug/vphone-cliBUNDLE := .build/vphone-cli.appBUNDLE_BIN := $(BUNDLE)/Contents/MacOS/vphone-cliBUNDLE_VM := $(BUNDLE)/Contents/MacOS/vphone-vmBUNDLE_LETMEIN := $(BUNDLE)/Contents/MacOS/vphone-letmein+BUNDLE_ARCHIVE := $(BUNDLE)/Contents/MacOS/vphone-archiveINFO_PLIST := sources/Info.plistENTITLEMENTS := sources/vphone.entitlementsVENV := .venv@@ -257,7 +259,8 @@ $(BINARY): $(SWIFT_SOURCES) Package.swift $(ENTITLEMENTS)@codesign --force --sign - --entitlements $(ENTITLEMENTS) $(VM_BINARY)@codesign --force --sign - $(BINARY)@codesign --force --sign - $(LETMEIN_BINARY)- @echo " signed: vphone-vm (entitled), vphone-cli, vphone-letmein"+ @codesign --force --sign - $(ARCHIVE_BINARY)+ @echo " signed: vphone-vm (entitled), vphone-cli, vphone-letmein, vphone-archive"@# An unentitled vphone-vm is worse than a broken one: it launches@# perfectly, which convinces vphone-cli's AMFI probe that nothing is@# wrong, and only fails later trying to create a PV=3 machine. A bare@@ -266,13 +269,14 @@ $(BINARY): $(SWIFT_SOURCES) Package.swift $(ENTITLEMENTS)| grep -q 'com.apple.private.virtualization' \|| (echo "Error: $(VM_BINARY) is not entitled after signing." >&2; exit 1)-$(VM_BINARY) $(LETMEIN_BINARY): $(BINARY)+$(VM_BINARY) $(LETMEIN_BINARY) $(ARCHIVE_BINARY): $(BINARY)bundle: build $(INFO_PLIST)@mkdir -p $(BUNDLE)/Contents/MacOS $(BUNDLE)/Contents/Resources@cp -f $(BINARY) $(BUNDLE_BIN)@cp -f $(VM_BINARY) $(BUNDLE_VM)@cp -f $(LETMEIN_BINARY) $(BUNDLE_LETMEIN)+ @cp -f $(ARCHIVE_BINARY) $(BUNDLE_ARCHIVE)@cp -f $(INFO_PLIST) $(BUNDLE)/Contents/Info.plist@cp -f sources/AppIcon.icns $(BUNDLE)/Contents/Resources/AppIcon.icns@cp -f $(SCRIPTS)/vphoned/signcert.p12 $(BUNDLE)/Contents/Resources/signcert.p12@@ -283,6 +287,7 @@ bundle: build $(INFO_PLIST)@codesign --force --sign - $(BUNDLE)/Contents/MacOS/ldid@codesign --force --sign - $(BUNDLE_BIN)@codesign --force --sign - $(BUNDLE_LETMEIN)+ @codesign --force --sign - $(BUNDLE_ARCHIVE)@codesign --force --sign - --entitlements $(ENTITLEMENTS) $(BUNDLE_VM)@codesign -v $(BUNDLE_VM) \|| (echo "Error: the bundle seal did not verify after signing." >&2; exit 1)diff --git a/Package.swift b/Package.swiftindex b9046ed6..dcb9882d 100644--- a/Package.swift+++ b/Package.swift@@ -14,6 +14,7 @@ let package = Package(.package(path: "vendor/libcapstone-spm"),.package(path: "vendor/libimg4-spm"),.package(path: "vendor/MachOKit"),+ .package(path: "vendor/libarchive.xcframework"),],targets: [.target(@@ -36,6 +37,19 @@ let package = Package(.linkedFramework("Virtualization"),]),+ // Archive reading and writing: the one place that knows how ownership,+ // permissions and path safety differ between unpacking onto a mounted+ // guest volume and unpacking into a host temp directory. Replaces+ // gtar, bsdtar, unzip and zstd, which between them were four external+ // programs and, for anything .zst, a Homebrew install.+ .target(+ name: "VPhoneArchive",+ dependencies: [+ .product(name: "LibArchive", package: "libarchive.xcframework"),+ "VPhoneCore",+ ],+ path: "sources/VPhoneArchive"+ ),// Everything that touches a running guest: the machine, its window and// menus, the vsock channel and the host device bridges. It is a library// so the only executable holding the private virtualization@@ -80,6 +94,15 @@ let package = Package(],path: "sources/vphone-cli"),+ .executableTarget(+ name: "vphone-archive",+ dependencies: [+ .product(name: "ArgumentParser", package: "swift-argument-parser"),+ "VPhoneArchive",+ "VPhoneCore",+ ],+ path: "sources/vphone-archive"+ ),// Opens a short AMFI window so vphone-vm can be exec'd. Plain C against// the SDK; no third-party anything..executableTarget(@@ -99,5 +122,10 @@ let package = Package(dependencies: ["VPhoneCore"],path: "tests/VPhoneCoreTests"),+ .testTarget(+ name: "VPhoneArchiveTests",+ dependencies: ["VPhoneArchive"],+ path: "tests/VPhoneArchiveTests"+ ),])diff --git a/scripts/build.sh b/scripts/build.shindex a459067e..6c3bed35 100755--- a/scripts/build.sh+++ b/scripts/build.sh@@ -16,17 +16,20 @@ SCRIPT_DIR="${0:A:h}"PROJECT_ROOT="${SCRIPT_DIR:h}"cd "$PROJECT_ROOT"-# Three host binaries, and only ONE of them is entitled. vphone-cli is the+# Four host binaries, and only ONE of them is entitled. vphone-cli is the# user-facing entry point and carries nothing, so it always launches; vphone-vm# holds the private virtualization keys and is what amfid can refuse;-# vphone-letmein opens a window when it does.+# vphone-letmein opens a window when it does; vphone-archive unpacks and packs+# without gtar, bsdtar, unzip or zstd.BINARY=".build/release/vphone-cli"VM_BINARY=".build/release/vphone-vm"LETMEIN_BINARY=".build/release/vphone-letmein"+ARCHIVE_BINARY=".build/release/vphone-archive"BUNDLE=".build/vphone-cli.app"BUNDLE_BIN="${BUNDLE}/Contents/MacOS/vphone-cli"BUNDLE_VM="${BUNDLE}/Contents/MacOS/vphone-vm"BUNDLE_LETMEIN="${BUNDLE}/Contents/MacOS/vphone-letmein"+BUNDLE_ARCHIVE="${BUNDLE}/Contents/MacOS/vphone-archive"INFO_PLIST="sources/Info.plist"ENTITLEMENTS="sources/vphone.entitlements"BUILD_INFO="sources/VPhoneCore/VPhoneBuildInfo.swift"@@ -54,7 +57,8 @@ echo "=== Signing ==="codesign --force --sign - --entitlements "$ENTITLEMENTS" "$VM_BINARY"codesign --force --sign - "$BINARY"codesign --force --sign - "$LETMEIN_BINARY"-echo " signed: vphone-vm (entitled), vphone-cli, vphone-letmein"+codesign --force --sign - "$ARCHIVE_BINARY"+echo " signed: vphone-vm (entitled), vphone-cli, vphone-letmein, vphone-archive"# An unentitled vphone-vm is worse than a broken one: it launches perfectly,# which convinces vphone-cli's AMFI probe that nothing is wrong, and only fails@@ -77,6 +81,7 @@ mkdir -p "${BUNDLE}/Contents/MacOS" "${BUNDLE}/Contents/Resources"cp -f "$BINARY" "$BUNDLE_BIN"cp -f "$VM_BINARY" "$BUNDLE_VM"cp -f "$LETMEIN_BINARY" "$BUNDLE_LETMEIN"+cp -f "$ARCHIVE_BINARY" "$BUNDLE_ARCHIVE"cp -f "$INFO_PLIST" "${BUNDLE}/Contents/Info.plist"cp -f "sources/AppIcon.icns" "${BUNDLE}/Contents/Resources/AppIcon.icns"cp -f "scripts/vphoned/signcert.p12" "${BUNDLE}/Contents/Resources/signcert.p12"@@ -88,6 +93,7 @@ cp -f "$(command -v ldid)" "${BUNDLE}/Contents/MacOS/ldid"codesign --force --sign - "${BUNDLE}/Contents/MacOS/ldid"codesign --force --sign - "$BUNDLE_BIN"codesign --force --sign - "$BUNDLE_LETMEIN"+codesign --force --sign - "$BUNDLE_ARCHIVE"codesign --force --sign - --entitlements "$ENTITLEMENTS" "$BUNDLE_VM"echo " bundled → ${BUNDLE}"@@ -147,6 +153,7 @@ echo "=== Re-signing bundled binaries (resealing Resources) ==="# Nested first, main executable last — see the bundling step above.codesign --force --sign - "$BUNDLE_BIN"codesign --force --sign - "$BUNDLE_LETMEIN"+codesign --force --sign - "$BUNDLE_ARCHIVE"codesign --force --sign - --entitlements "$ENTITLEMENTS" "$BUNDLE_VM"codesign -v "$BUNDLE_VM" \|| { echo "Error: the bundle seal did not verify after signing." >&2; exit 1; }@@ -157,6 +164,7 @@ echo "=== Build complete ==="echo " vphone-cli : ${BINARY} (no entitlements — always launches)"echo " vphone-vm : ${VM_BINARY} (entitled — amfid may refuse it)"echo " vphone-letmein : ${LETMEIN_BINARY}"+echo " vphone-archive : ${ARCHIVE_BINARY}"echo " bundle : ${BUNDLE}"[[ "$BUILD_VPHONED" -eq 1 ]] && echo " vphoned : .build/vphoned.signed"echo ""diff --git a/scripts/check_aux.sh b/scripts/check_aux.shindex d960d38f..c5f02904 100755--- a/scripts/check_aux.sh+++ b/scripts/check_aux.sh@@ -239,6 +239,27 @@ check_smoke() {}[[ -x "$cli" ]] && run_restricted "vphone-cli --help" "$cli" --help++ # The one binary whose smallest real job is worth doing here. Packing and+ # unpacking a .tzst with no zstd(1) reachable is the whole reason it exists:+ # both the system tar and GNU tar spawn one for that filter, so this is the+ # difference between a CFW install working on a machine without Homebrew and+ # not.+ local archive="$root/Contents/MacOS/vphone-archive"+ if [[ -x "$archive" ]]; then+ local work="$tmp/smoke"+ mkdir -p "$work/src" "$work/out"+ print "hello" > "$work/src/probe.txt"+ if env -i PATH=/usr/bin:/bin HOME="$tmp" "$archive" \+ create -f "$work/t.tzst" -C "$work/src" --zstd >/dev/null 2>&1 \+ && env -i PATH=/usr/bin:/bin HOME="$tmp" "$archive" \+ extract -f "$work/t.tzst" -C "$work/out" >/dev/null 2>&1 \+ && [[ "$(<"$work/out/probe.txt")" == "hello" ]]; then+ green " ok gate 3: vphone-archive round-trips a .tzst with no zstd on PATH"+ else+ fail "gate 3: vphone-archive could not round-trip a .tzst"+ fi+ fi[[ -x "$letmein" ]] && {# Expected to refuse without root; what matters is that it starts.env -i PATH=/usr/bin:/bin HOME="$tmp" "$letmein" status >/dev/null 2>&1diff --git a/sources/VPhoneArchive/VPhoneArchiveError.swift b/sources/VPhoneArchive/VPhoneArchiveError.swiftnew file mode 100644index 00000000..4293a3d8--- /dev/null+++ b/sources/VPhoneArchive/VPhoneArchiveError.swift@@ -0,0 +1,43 @@+import Foundation+import LibArchive++public enum VPhoneArchiveError: Error, CustomStringConvertible {+ case cannotOpen(path: String, reason: String)+ case readFailed(path: String, reason: String)+ case writeFailed(path: String, reason: String)+ case memberNotFound(member: String, archive: String)+ /// A member resolved outside the destination after normalisation.+ case pathEscapesDestination(member: String, destination: String)+ case destinationNotWritable(String)+ case cancelled++ public var description: String {+ switch self {+ case let .cannotOpen(path, reason):+ "Could not open \(path): \(reason)"+ case let .readFailed(path, reason):+ "Could not read \(path): \(reason)"+ case let .writeFailed(path, reason):+ "Could not write \(path): \(reason)"+ case let .memberNotFound(member, archive):+ "\(archive) has no member named \(member)"+ case let .pathEscapesDestination(member, destination):+ """+ Refusing to unpack '\(member)': it resolves outside \(destination).+ The archive is malformed or hostile; nothing was written.+ """+ case let .destinationNotWritable(path):+ "Cannot write into \(path)"+ case .cancelled:+ "Cancelled"+ }+ }+}++/// libarchive's own message for a handle, or a stand-in when it has none.+func archiveErrorString(_ handle: OpaquePointer?) -> String {+ guard let handle, let message = archive_error_string(handle) else {+ return "unknown libarchive error"+ }+ return String(cString: message)+}diff --git a/sources/VPhoneArchive/VPhoneArchiveExtractor.swift b/sources/VPhoneArchive/VPhoneArchiveExtractor.swiftnew file mode 100644index 00000000..fb556834--- /dev/null+++ b/sources/VPhoneArchive/VPhoneArchiveExtractor.swift@@ -0,0 +1,202 @@+import Foundation+import LibArchive++/// Unpacks an archive onto disk.+///+/// The format and the compressor are detected, so there is no `--zstd` to+/// pass and no way to get it wrong. What the caller does choose is where the+/// files end up belonging, which is the part that differs between unpacking+/// onto a mounted guest volume and unpacking into a scratch directory.+public enum VPhoneArchiveExtractor {+ /// Bytes handed to libarchive per read. 10 KiB is libarchive's own+ /// suggestion and there is no reason here to argue with it.+ private static let blockSize = 10240++ public struct Progress: Sendable {+ public let entriesWritten: Int+ public let bytesWritten: Int64+ public let currentPath: String+ }++ /// Unpack `archive` into `destination`.+ ///+ /// - Returns: the number of entries written, not counting any skipped by+ /// `noOverwriteDir`.+ @discardableResult+ public static func extract(+ _ archive: URL,+ into destination: URL,+ options: VPhoneArchiveExtractOptions,+ progress: ((Progress) -> Void)? = nil,+ isCancelled: (() -> Bool)? = nil+ ) throws -> Int {+ let reader = archive_read_new()+ archive_read_support_format_all(reader)+ archive_read_support_filter_all(reader)+ defer { archive_read_free(reader) }++ let writer = archive_write_disk_new()+ archive_write_disk_set_options(writer, options.extractFlags)+ // Deliberately NOT archive_write_disk_set_standard_lookup(): see+ // VPhoneArchiveOwnership.preserveNumeric. Without it libarchive uses+ // the numeric ids straight from the archive, which is what we want.+ defer { archive_write_free(writer) }++ guard archive_read_open_filename(reader, archive.path, blockSize) == ARCHIVE_OK else {+ throw VPhoneArchiveError.cannotOpen(+ path: archive.path, reason: archiveErrorString(reader)+ )+ }++ // Resolved once, and every target is built from the resolved form.+ //+ // Not a tidy-up: ARCHIVE_EXTRACT_SECURE_SYMLINKS checks every+ // component of the path it is given, and on macOS /tmp and /var are+ // themselves symlinks into /private. Handing it an unresolved+ // /var/folders/... target makes it refuse the extraction outright,+ // with "Cannot extract through symlink /var/...". Resolving the+ // destination leaves only components *below* it for the flag to judge,+ // which is the part we actually want judged.+ let resolvedDestination = try VPhoneArchivePaths.resolved(destination)+ let destinationPath = resolvedDestination.path+ var written = 0+ var bytes: Int64 = 0++ while true {+ if isCancelled?() == true { throw VPhoneArchiveError.cancelled }++ var entry: OpaquePointer?+ let status = archive_read_next_header(reader, &entry)+ if status == ARCHIVE_EOF { break }+ guard status == ARCHIVE_OK || status == ARCHIVE_WARN, let entry else {+ throw VPhoneArchiveError.readFailed(+ path: archive.path, reason: archiveErrorString(reader)+ )+ }++ let memberPath = archive_entry_pathname(entry).map { String(cString: $0) } ?? ""+ let target = resolvedDestination.appendingPathComponent(memberPath)++ // libarchive's SECURE_* flags already refuse absolute paths and+ // `..`, but they refuse them inside libarchive. Checking the+ // normalised result here as well means the answer does not rest on+ // one flag being set, and the error can name the member.+ // .standardized, not .standardizedFileURL: the latter resolves+ // symlinks as well, and on macOS that turns the /private/var we+ // just resolved back into /var, so the prefix comparison fails+ // against a destination that is perfectly fine. Collapsing "." and+ // ".." is all that is wanted here — the destination was already+ // resolved once, above.+ let targetPath = target.standardized.path+ guard targetPath == destinationPath || targetPath.hasPrefix(destinationPath + "/") else {+ throw VPhoneArchiveError.pathEscapesDestination(+ member: memberPath, destination: destinationPath+ )+ }+ archive_entry_set_pathname(entry, targetPath)++ if options.noOverwriteDir, shouldSkipExistingDirectory(entry, at: target) {+ // Skip the header only. Everything under this directory that+ // does not yet exist is still written on its own entry, which+ // is what GNU tar does too.+ continue+ }++ guard archive_write_header(writer, entry) == ARCHIVE_OK else {+ throw VPhoneArchiveError.writeFailed(+ path: target.path, reason: archiveErrorString(writer)+ )+ }++ if archive_entry_size(entry) > 0 {+ bytes += try copyData(from: reader, to: writer, isCancelled: isCancelled)+ }++ guard archive_write_finish_entry(writer) == ARCHIVE_OK else {+ throw VPhoneArchiveError.writeFailed(+ path: target.path, reason: archiveErrorString(writer)+ )+ }++ written += 1+ progress?(Progress(entriesWritten: written, bytesWritten: bytes, currentPath: memberPath))+ }++ return written+ }++ // MARK: - --no-overwrite-dir++ /// Whether this entry is a directory that already exists and should be+ /// left exactly as it is.+ ///+ /// GNU tar's `--no-overwrite-dir` has no libarchive equivalent, and+ /// neither of the two things libarchive does offer is the same:+ ///+ /// - The default, per `man 3 archive_write_disk`, is that "existing+ /// directories will have their permissions updated". That is precisely+ /// what must not happen. `iosbinpack64.tar` carries entries for `usr/`,+ /// `usr/local/` and `System/`, and unpacking it onto an installed iOS+ /// volume would stamp the archive's modes and owners over the real+ /// ones.+ ///+ /// - `ARCHIVE_EXTRACT_NO_OVERWRITE` is too broad in the other direction:+ /// it skips any existing object of any type, so an ordinary file that+ /// should be replaced silently is not. libarchive decides per entry, so+ /// skipping a directory does not affect new files beneath it — the+ /// problem is only what it does to regular files.+ ///+ /// So: look for a directory entry whose target already exists as a+ /// directory, and skip writing its header. The path is left in place; only+ /// its metadata is left alone.+ private static func shouldSkipExistingDirectory(+ _ entry: OpaquePointer,+ at target: URL+ ) -> Bool {+ // S_IFDIR rather than AE_IFDIR: the AE_* names are C macros that Swift+ // does not import, and they are defined to the same values as the+ // S_IF* ones precisely so they can be compared like this.+ guard mode_t(archive_entry_filetype(entry)) == S_IFDIR else { return false }++ var info = stat()+ // lstat, not stat: a symlink that points at a directory is a symlink,+ // and replacing it is a different decision from updating a directory.+ guard lstat(target.path, &info) == 0 else { return false }+ return (info.st_mode & S_IFMT) == S_IFDIR+ }++ // MARK: - Data++ private static func copyData(+ from reader: OpaquePointer?,+ to writer: OpaquePointer?,+ isCancelled: (() -> Bool)?+ ) throws -> Int64 {+ var total: Int64 = 0+ while true {+ // Cancellation is checked per block, not per entry: a single+ // multi-gigabyte disk image is one entry, and a check that only+ // happens between entries would not interrupt it.+ if isCancelled?() == true { throw VPhoneArchiveError.cancelled }++ var buffer: UnsafeRawPointer?+ var size = 0+ var offset: la_int64_t = 0++ let status = archive_read_data_block(reader, &buffer, &size, &offset)+ if status == ARCHIVE_EOF { return total }+ guard status == ARCHIVE_OK || status == ARCHIVE_WARN else {+ throw VPhoneArchiveError.readFailed(+ path: "<member data>", reason: archiveErrorString(reader)+ )+ }++ guard archive_write_data_block(writer, buffer, size, offset) >= ARCHIVE_OK else {+ throw VPhoneArchiveError.writeFailed(+ path: "<member data>", reason: archiveErrorString(writer)+ )+ }+ total += Int64(size)+ }+ }+}diff --git a/sources/VPhoneArchive/VPhoneArchiveOptions.swift b/sources/VPhoneArchive/VPhoneArchiveOptions.swiftnew file mode 100644index 00000000..d64f7093--- /dev/null+++ b/sources/VPhoneArchive/VPhoneArchiveOptions.swift@@ -0,0 +1,161 @@+import Foundation+import LibArchive++// MARK: - VPhoneArchiveOwnership++/// Who owns the files that come out of an archive.+///+/// This is not a preference — it is three different correct answers for three+/// different jobs, and using the wrong one is how an unbootable guest gets+/// made.+public enum VPhoneArchiveOwnership: Sendable {+ /// Restore the uid/gid recorded in the archive, **by number**.+ ///+ /// For unpacking onto a mounted guest volume as root. Files in+ /// iosbinpack64 that belong to `mobile` have to keep belonging to+ /// `mobile`, and `ARCHIVE_EXTRACT_PERM` does not do that — it only+ /// restores the mode bits.+ ///+ /// By number, because libarchive's name lookup would resolve the+ /// archive's `mobile` or `_wireless` against the **host's** passwd+ /// database, and either miss or, worse, hit an unrelated macOS account+ /// with the same name. This is what `tar --numeric-owner` means, and it+ /// differs slightly from GNU tar's default, which tries the name first.+ case preserveNumeric++ /// Let everything belong to whoever is running.+ ///+ /// For unpacking into a host directory as a normal user, where restoring+ /// the archive's owners would either fail outright or, as root, be a way+ /// of writing files owned by someone else.+ case currentUser+}++// MARK: - VPhoneArchiveExtractOptions++public struct VPhoneArchiveExtractOptions: Sendable {+ public var ownership: VPhoneArchiveOwnership++ /// Do not touch an existing directory's mode, owner or mtime.+ ///+ /// GNU tar spells this `--no-overwrite-dir`, and libarchive has no+ /// equivalent — see `VPhoneArchiveExtractor` for why neither the default+ /// behaviour nor `ARCHIVE_EXTRACT_NO_OVERWRITE` will do.+ public var noOverwriteDir: Bool++ /// Interpret `._*` AppleDouble members as real extended attributes.+ ///+ /// Off, deliberately. GNU tar does not understand AppleDouble either, so+ /// today those members land as ordinary files on the guest volume and the+ /// installer deletes them afterwards. Turning this on would genuinely+ /// change what ends up on an iOS volume, and the current shape is the one+ /// that has booted.+ public var macMetadata: Bool++ /// Restore ACLs and BSD file flags as well as mode bits.+ public var extendedMetadata: Bool++ public init(+ ownership: VPhoneArchiveOwnership,+ noOverwriteDir: Bool = false,+ macMetadata: Bool = false,+ extendedMetadata: Bool = false+ ) {+ self.ownership = ownership+ self.noOverwriteDir = noOverwriteDir+ self.macMetadata = macMetadata+ self.extendedMetadata = extendedMetadata+ }++ /// Unpacking onto a mounted guest volume, as root.+ ///+ /// Mirrors what `cfw_install*.sh` passes GNU tar today:+ /// `--preserve-permissions --no-overwrite-dir`.+ public static let ontoGuestVolume = VPhoneArchiveExtractOptions(+ ownership: .preserveNumeric,+ noOverwriteDir: true,+ macMetadata: false,+ extendedMetadata: true+ )++ /// Unpacking into a host directory we own and can throw away.+ public static let intoHostDirectory = VPhoneArchiveExtractOptions(+ ownership: .currentUser,+ noOverwriteDir: false,+ macMetadata: false,+ extendedMetadata: false+ )++ /// The libarchive `archive_write_disk` flags for these options.+ var extractFlags: Int32 {+ // SECURE_SYMLINKS and SECURE_NODOTDOT are unconditional, with no way+ // to turn them off. IPSWs and procursus bootstraps come from+ // elsewhere, and the destination is a mounted system volume: without+ // these, a crafted member writes wherever it likes. libarchive leaves+ // both OFF by default.+ //+ // SECURE_NOABSOLUTEPATHS is deliberately NOT set, and this is the one+ // place the implementation departs from the plan's "all three,+ // unconditionally". archive_write_disk has no notion of a destination+ // directory: it writes relative to the process's working directory. So+ // reaching an arbitrary destination means either chdir'ing there —+ // which makes extraction process-global and non-reentrant, and did+ // break when two ran at once — or giving each entry an absolute+ // target, which is what this does. That flag then rejects the very+ // paths we just computed.+ //+ // What replaces it is stronger, not weaker: VPhoneArchiveExtractor+ // normalises each target and requires it to sit under the destination+ // before writing. The flag only inspects whether a member's stored+ // path starts with a slash; the check looks at where the path actually+ // lands.+ var flags = ARCHIVE_EXTRACT_SECURE_SYMLINKS+ | ARCHIVE_EXTRACT_SECURE_NODOTDOT+ | ARCHIVE_EXTRACT_PERM+ | ARCHIVE_EXTRACT_TIME++ if ownership == .preserveNumeric { flags |= ARCHIVE_EXTRACT_OWNER }+ if extendedMetadata { flags |= ARCHIVE_EXTRACT_ACL | ARCHIVE_EXTRACT_FFLAGS }+ if macMetadata { flags |= ARCHIVE_EXTRACT_MAC_METADATA }++ return Int32(flags)+ }+}++// MARK: - VPhoneArchiveFormat++/// The tar dialect to write.+public enum VPhoneArchiveFormat: String, Sendable, CaseIterable {+ /// GNU tar. Not a default — a requirement in two places.+ ///+ /// `vm export` pipes into a consumer that reads pax extended headers as an+ /// mtree listing and fails with "Line too long"; and ustar cannot hold a+ /// member over 8 GB, which a VM bundle exceeds. Changing this breaks+ /// export.+ case gnutar+ case pax+ case ustar+}++// MARK: - VPhoneArchiveCompression++public enum VPhoneArchiveCompression: Sendable, Equatable {+ case none+ /// zstd. The default for `vm export`, at level 3.+ case zstd(level: Int)+ /// xz. What `vm export --max` uses, at level 9.+ case xz(level: Int)+ case gzip(level: Int)++ /// The extension this compressor produces for a tar archive. `vm export`+ /// hands these names to users and to older copies of itself, so they are+ /// part of the contract, not a formatting choice.+ public var tarExtension: String {+ switch self {+ case .none: "tar"+ case .zstd: "tzst"+ case .xz: "txz"+ case .gzip: "tgz"+ }+ }+}diff --git a/sources/VPhoneArchive/VPhoneArchivePaths.swift b/sources/VPhoneArchive/VPhoneArchivePaths.swiftnew file mode 100644index 00000000..034c1587--- /dev/null+++ b/sources/VPhoneArchive/VPhoneArchivePaths.swift@@ -0,0 +1,37 @@+import Foundation++/// Path handling that has to agree between the reader, the writer and the+/// extractor.+enum VPhoneArchivePaths {+ /// A directory with every symlink in it resolved, as realpath(3) sees it.+ ///+ /// Not `URL.resolvingSymlinksInPath()` or `.standardizedFileURL`. Both of+ /// those go the *other* way on macOS: given `/private/tmp/x` they hand+ /// back `/tmp/x`, stripping the `/private` prefix rather than resolving+ /// the symlink. That silently broke two things before this helper existed+ /// — extraction, where libarchive then refused to write "through symlink+ /// /var/...", and packing, where the archive-relative path never matched+ /// its root and every member was stored under an absolute path.+ ///+ /// Throws if the path does not exist, which is the right moment to find+ /// that out.+ static func resolved(_ url: URL) throws -> URL {+ guard let resolved = realpath(url.path, nil) else {+ throw VPhoneArchiveError.cannotOpen(+ path: url.path, reason: String(cString: strerror(errno))+ )+ }+ defer { free(resolved) }+ return URL(fileURLWithPath: String(cString: resolved))+ }++ /// `absolute` expressed relative to `root`, for storing in an archive.+ ///+ /// Empty when it *is* the root, which the caller skips: an archive should+ /// not carry an entry for the directory it was made from.+ static func relative(_ absolute: String, under root: String) -> String {+ if absolute == root { return "" }+ if absolute.hasPrefix(root + "/") { return String(absolute.dropFirst(root.count + 1)) }+ return absolute+ }+}diff --git a/sources/VPhoneArchive/VPhoneArchiveReader.swift b/sources/VPhoneArchive/VPhoneArchiveReader.swiftnew file mode 100644index 00000000..0e3b47dc--- /dev/null+++ b/sources/VPhoneArchive/VPhoneArchiveReader.swift@@ -0,0 +1,136 @@+import Foundation+import LibArchive++/// Reading an archive without unpacking it.+///+/// Listing members and pulling a single one out — reading a BuildManifest from+/// an IPSW without writing 15 GB to disk first.+public enum VPhoneArchiveReader {+ private static let blockSize = 10240++ public struct Entry: Sendable, Equatable {+ public let path: String+ public let size: Int64+ public let isDirectory: Bool+ public let isSymlink: Bool+ public let mode: mode_t+ public let uid: Int+ public let gid: Int+ public let modified: Date?+ /// Where a symlink points, unresolved.+ public let linkTarget: String?+ }++ /// Every member, in the order the archive stores them.+ public static func entries(of archive: URL) throws -> [Entry] {+ try withReader(archive) { reader in+ var found: [Entry] = []+ while let entry = try nextHeader(reader, archive: archive) {+ found.append(makeEntry(entry))+ archive_read_data_skip(reader)+ }+ return found+ }+ }++ /// One member's contents.+ ///+ /// Reads sequentially, so it costs whatever it costs to reach the member.+ /// For a zip on a real file libarchive uses the central directory and the+ /// seek is cheap; for a compressed tar it is not, and the whole stream up+ /// to that point has to be decompressed.+ public static func readMember(_ member: String, from archive: URL) throws -> Data {+ try withReader(archive) { reader in+ while let entry = try nextHeader(reader, archive: archive) {+ let path = archive_entry_pathname(entry).map { String(cString: $0) } ?? ""+ guard path == member else {+ archive_read_data_skip(reader)+ continue+ }++ var data = Data()+ let hint = archive_entry_size(entry)+ if hint > 0 { data.reserveCapacity(Int(hint)) }++ var buffer = [UInt8](repeating: 0, count: 65536)+ while true {+ let read = buffer.withUnsafeMutableBytes {+ archive_read_data(reader, $0.baseAddress, $0.count)+ }+ if read == 0 { break }+ guard read > 0 else {+ throw VPhoneArchiveError.readFailed(+ path: archive.path, reason: archiveErrorString(reader)+ )+ }+ data.append(contentsOf: buffer[0..<Int(read)])+ }+ return data+ }+ throw VPhoneArchiveError.memberNotFound(member: member, archive: archive.path)+ }+ }++ /// The compressor and format libarchive detects, for reporting.+ public static func describe(_ archive: URL) throws -> (format: String, filter: String) {+ try withReader(archive) { reader in+ _ = try nextHeader(reader, archive: archive)+ let format = archive_format_name(reader).map { String(cString: $0) } ?? "unknown"+ let filter = archive_filter_name(reader, 0).map { String(cString: $0) } ?? "none"+ return (format, filter)+ }+ }++ // MARK: - Plumbing++ private static func withReader<T>(+ _ archive: URL,+ _ body: (OpaquePointer?) throws -> T+ ) throws -> T {+ let reader = archive_read_new()+ archive_read_support_format_all(reader)+ archive_read_support_format_raw(reader)+ archive_read_support_filter_all(reader)+ defer { archive_read_free(reader) }++ guard archive_read_open_filename(reader, archive.path, blockSize) == ARCHIVE_OK else {+ throw VPhoneArchiveError.cannotOpen(+ path: archive.path, reason: archiveErrorString(reader)+ )+ }+ return try body(reader)+ }++ private static func nextHeader(+ _ reader: OpaquePointer?,+ archive: URL+ ) throws -> OpaquePointer? {+ var entry: OpaquePointer?+ let status = archive_read_next_header(reader, &entry)+ if status == ARCHIVE_EOF { return nil }+ guard status == ARCHIVE_OK || status == ARCHIVE_WARN else {+ throw VPhoneArchiveError.readFailed(+ path: archive.path, reason: archiveErrorString(reader)+ )+ }+ return entry+ }++ private static func makeEntry(_ entry: OpaquePointer) -> Entry {+ let fileType = mode_t(archive_entry_filetype(entry))+ let mtime = archive_entry_mtime_is_set(entry) != 0+ ? Date(timeIntervalSince1970: TimeInterval(archive_entry_mtime(entry)))+ : nil+ return Entry(+ path: archive_entry_pathname(entry).map { String(cString: $0) } ?? "",+ size: archive_entry_size(entry),+ isDirectory: fileType == S_IFDIR,+ isSymlink: fileType == S_IFLNK,+ mode: mode_t(archive_entry_perm(entry)),+ uid: Int(archive_entry_uid(entry)),+ gid: Int(archive_entry_gid(entry)),+ modified: mtime,+ linkTarget: archive_entry_symlink(entry).map { String(cString: $0) }+ )+ }+}diff --git a/sources/VPhoneArchive/VPhoneArchiveWriter.swift b/sources/VPhoneArchive/VPhoneArchiveWriter.swiftnew file mode 100644index 00000000..ab94fac2--- /dev/null+++ b/sources/VPhoneArchive/VPhoneArchiveWriter.swift@@ -0,0 +1,217 @@+import Foundation+import LibArchive++/// Creating archives, and plain decompression.+public enum VPhoneArchiveWriter {+ public struct Progress: Sendable {+ public let entriesWritten: Int+ public let bytesWritten: Int64+ public let currentPath: String+ }++ /// Pack `root` into `archive`.+ ///+ /// Paths inside the archive are relative to `root`, so unpacking anywhere+ /// reproduces the tree rather than an absolute path.+ ///+ /// `excluding` takes `fnmatch` patterns matched against the archive-relative+ /// path, which is what `vm export` already uses.+ @discardableResult+ public static func create(+ archive: URL,+ from root: URL,+ format: VPhoneArchiveFormat = .gnutar,+ compression: VPhoneArchiveCompression = .none,+ excluding patterns: [String] = [],+ progress: ((Progress) -> Void)? = nil,+ isCancelled: (() -> Bool)? = nil+ ) throws -> Int {+ let writer = archive_write_new()+ defer { archive_write_free(writer) }++ switch format {+ case .gnutar: archive_write_set_format_gnutar(writer)+ case .pax: archive_write_set_format_pax_restricted(writer)+ case .ustar: archive_write_set_format_ustar(writer)+ }++ switch compression {+ case .none:+ break+ case let .zstd(level):+ archive_write_add_filter_zstd(writer)+ try setFilterOption(writer, "zstd", "compression-level", String(level))+ // threads=0 means "as many as there are cores".+ try setFilterOption(writer, "zstd", "threads", "0")+ case let .xz(level):+ archive_write_add_filter_xz(writer)+ try setFilterOption(writer, "xz", "compression-level", String(level))+ // The bundled liblzma does carry the multithreaded encoder, which+ // is worth about 4.8x -- but only above one xz block, roughly+ // 192 MiB at level 9. A smaller archive gets no benefit, and that+ // is arithmetic rather than a fault. See+ // research/libarchive_xcframework_validation.md.+ try setFilterOption(writer, "xz", "threads", "0")+ case let .gzip(level):+ archive_write_add_filter_gzip(writer)+ try setFilterOption(writer, "gzip", "compression-level", String(level))+ }++ guard archive_write_open_filename(writer, archive.path) == ARCHIVE_OK else {+ throw VPhoneArchiveError.cannotOpen(+ path: archive.path, reason: archiveErrorString(writer)+ )+ }+ defer { archive_write_close(writer) }++ let disk = archive_read_disk_new()+ archive_read_disk_set_standard_lookup(disk)+ defer { archive_read_free(disk) }++ // Resolved, and the same resolved path is what libarchive walks — so+ // the prefix strip below always matches. Passing one form here and+ // comparing against another is how every member ended up stored under+ // an absolute path.+ let resolvedRoot = try VPhoneArchivePaths.resolved(root)+ guard archive_read_disk_open(disk, resolvedRoot.path) == ARCHIVE_OK else {+ throw VPhoneArchiveError.cannotOpen(+ path: resolvedRoot.path, reason: archiveErrorString(disk)+ )+ }++ let rootPath = resolvedRoot.path+ var written = 0+ var bytes: Int64 = 0++ while true {+ if isCancelled?() == true { throw VPhoneArchiveError.cancelled }++ let entry = archive_entry_new()+ defer { archive_entry_free(entry) }++ let status = archive_read_next_header2(disk, entry)+ if status == ARCHIVE_EOF { break }+ guard status == ARCHIVE_OK || status == ARCHIVE_WARN else {+ throw VPhoneArchiveError.readFailed(+ path: root.path, reason: archiveErrorString(disk)+ )+ }+ archive_read_disk_descend(disk)++ let absolute = archive_entry_pathname(entry).map { String(cString: $0) } ?? ""+ let relative = VPhoneArchivePaths.relative(absolute, under: rootPath)+ if relative.isEmpty { continue } // the root itself+ if patterns.contains(where: { matches(relative, pattern: $0) }) { continue }+ archive_entry_set_pathname(entry, relative)++ guard archive_write_header(writer, entry) == ARCHIVE_OK else {+ throw VPhoneArchiveError.writeFailed(+ path: relative, reason: archiveErrorString(writer)+ )+ }++ if archive_entry_size(entry) > 0 {+ bytes += try copyFile(at: absolute, into: writer, isCancelled: isCancelled)+ }++ written += 1+ progress?(Progress(entriesWritten: written, bytesWritten: bytes, currentPath: relative))+ }++ return written+ }++ /// Decompress a single-stream file — `zstd -d`, and its xz and gzip+ /// equivalents.+ ///+ /// This is not unpacking: `bootstrap-iphoneos-arm64.tar.zst` is one+ /// compressed file, and what comes out is the tar. libarchive expresses+ /// that as the "raw" format, which presents the stream as one nameless+ /// entry.+ public static func decompress(_ input: URL, to output: URL) throws {+ let reader = archive_read_new()+ archive_read_support_filter_all(reader)+ archive_read_support_format_raw(reader)+ defer { archive_read_free(reader) }++ guard archive_read_open_filename(reader, input.path, 10240) == ARCHIVE_OK else {+ throw VPhoneArchiveError.cannotOpen(+ path: input.path, reason: archiveErrorString(reader)+ )+ }++ var entry: OpaquePointer?+ guard archive_read_next_header(reader, &entry) == ARCHIVE_OK else {+ throw VPhoneArchiveError.readFailed(+ path: input.path, reason: archiveErrorString(reader)+ )+ }++ FileManager.default.createFile(atPath: output.path, contents: nil)+ guard let handle = FileHandle(forWritingAtPath: output.path) else {+ throw VPhoneArchiveError.cannotOpen(path: output.path, reason: "cannot create")+ }+ defer { try? handle.close() }++ var buffer = [UInt8](repeating: 0, count: 1 << 20)+ while true {+ let read = buffer.withUnsafeMutableBytes {+ archive_read_data(reader, $0.baseAddress, $0.count)+ }+ if read == 0 { break }+ guard read > 0 else {+ throw VPhoneArchiveError.readFailed(+ path: input.path, reason: archiveErrorString(reader)+ )+ }+ try handle.write(contentsOf: buffer[0..<Int(read)])+ }+ }++ // MARK: - Plumbing++ private static func setFilterOption(+ _ writer: OpaquePointer?,+ _ filter: String,+ _ key: String,+ _ value: String+ ) throws {+ guard archive_write_set_filter_option(writer, filter, key, value) == ARCHIVE_OK else {+ throw VPhoneArchiveError.writeFailed(+ path: "<filter \(filter)>", reason: archiveErrorString(writer)+ )+ }+ }++ private static func matches(_ path: String, pattern: String) -> Bool {+ fnmatch(pattern, path, 0) == 0+ || fnmatch(pattern, (path as NSString).lastPathComponent, 0) == 0+ }++ private static func copyFile(+ at path: String,+ into writer: OpaquePointer?,+ isCancelled: (() -> Bool)?+ ) throws -> Int64 {+ guard let handle = FileHandle(forReadingAtPath: path) else {+ throw VPhoneArchiveError.cannotOpen(path: path, reason: "cannot read")+ }+ defer { try? handle.close() }++ var total: Int64 = 0+ while true {+ if isCancelled?() == true { throw VPhoneArchiveError.cancelled }+ guard let chunk = try handle.read(upToCount: 1 << 20), !chunk.isEmpty else { break }+ let sent = chunk.withUnsafeBytes {+ archive_write_data(writer, $0.baseAddress, $0.count)+ }+ guard sent > 0 else {+ throw VPhoneArchiveError.writeFailed(+ path: path, reason: archiveErrorString(writer)+ )+ }+ total += Int64(sent)+ }+ return total+ }+}diff --git a/sources/vphone-archive/main.swift b/sources/vphone-archive/main.swiftnew file mode 100644index 00000000..ebe6b3fc--- /dev/null+++ b/sources/vphone-archive/main.swift@@ -0,0 +1,219 @@+// vphone-archive — unpacking and packing, without four external programs.+//+// Replaces gtar, bsdtar, unzip and zstd. The last of those is the reason this+// exists at all: neither the system tar nor GNU tar can read a .zst without a+// zstd(1) on PATH, because both shell out for that filter, and libzstd is not+// in /usr/lib or in the SDK. The libarchive this links has it compiled in, so+// a machine with no Homebrew can still install CFW.+//+// The shell scripts call this while they are still shell; vphone-cli calls the+// same library in-process. One implementation either way.++import ArgumentParser+import Foundation+import VPhoneArchive+import VPhoneCore++struct VPhoneArchiveCLI: ParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "vphone-archive",+ abstract: "Unpack and pack archives",+ discussion: """+ The compressor is detected when reading, so there is no --zstd to pass+ and no way to pass the wrong one.+ """,+ subcommands: [Extract.self, Create.self, Decompress.self, List.self, Cat.self],+ defaultSubcommand: Extract.self+ )+}++// MARK: - extract++struct Extract: ParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "extract",+ abstract: "Unpack an archive into a directory"+ )++ @Option(name: [.customShort("f"), .long], help: "Archive to read",+ transform: URL.init(fileURLWithPath:))+ var file: URL++ @Option(name: [.customShort("C"), .customLong("directory")],+ help: "Where to unpack it", transform: URL.init(fileURLWithPath:))+ var destination: URL = URL(fileURLWithPath: ".")++ @Flag(name: [.customShort("p"), .customLong("preserve-permissions")],+ help: "Restore modes, and — as root — the archive's numeric uid/gid")+ var preservePermissions = false++ @Flag(name: .customLong("no-overwrite-dir"),+ help: "Leave an existing directory's mode, owner and mtime alone")+ var noOverwriteDir = false++ @Flag(name: .customLong("numeric-owner"),+ help: "Accepted for compatibility; ownership is always restored by number")+ var numericOwner = false++ @Flag(name: [.customShort("v"), .long], help: "Print each member as it is written")+ var verbose = false++ func run() throws {+ // --preserve-permissions is what the install scripts pass GNU tar, and+ // they pass it precisely where they are running as root and unpacking+ // onto a mounted guest volume. Ownership by number is not a separate+ // choice: resolving the archive's `mobile` against the host's passwd+ // database is how files end up owned by an unrelated macOS account.+ var options = preservePermissions+ ? VPhoneArchiveExtractOptions.ontoGuestVolume+ : VPhoneArchiveExtractOptions.intoHostDirectory+ options.noOverwriteDir = noOverwriteDir++ let written = try VPhoneArchiveExtractor.extract(+ file, into: destination, options: options,+ progress: verbose ? { print($0.currentPath) } : nil+ )+ if !verbose { print("extracted \(written) entries to \(destination.path)") }+ }+}++// MARK: - create++struct Create: ParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "create",+ abstract: "Pack a directory into an archive"+ )++ @Option(name: [.customShort("f"), .long], help: "Archive to write",+ transform: URL.init(fileURLWithPath:))+ var file: URL++ @Option(name: [.customShort("C"), .customLong("directory")],+ help: "Directory to pack", transform: URL.init(fileURLWithPath:))+ var source: URL = URL(fileURLWithPath: ".")++ @Option(help: "tar dialect: gnutar, pax or ustar")+ var format: String = "gnutar"++ @Flag(name: .customLong("zstd"), help: "Compress with zstd")+ var zstd = false++ @Flag(name: .customLong("xz"), help: "Compress with xz")+ var xz = false++ @Option(help: "Compression level")+ var level: Int?++ @Option(help: "fnmatch pattern to leave out; repeatable")+ var exclude: [String] = []++ @Flag(name: [.customShort("v"), .long], help: "Print each member as it is added")+ var verbose = false++ func validate() throws {+ if zstd, xz { throw ValidationError("choose one of --zstd or --xz") }+ guard VPhoneArchiveFormat(rawValue: format) != nil else {+ throw ValidationError(+ "unknown format '\(format)' (gnutar, pax, ustar)"+ )+ }+ }++ func run() throws {+ // gnutar by default, and it matters: `vm export` feeds a consumer that+ // reads pax extended headers as an mtree listing and dies with "Line+ // too long", and ustar cannot hold a member over 8 GB.+ let tarFormat = VPhoneArchiveFormat(rawValue: format) ?? .gnutar+ let compression: VPhoneArchiveCompression = if zstd {+ .zstd(level: level ?? 3)+ } else if xz {+ .xz(level: level ?? 9)+ } else {+ .none+ }++ let written = try VPhoneArchiveWriter.create(+ archive: file, from: source,+ format: tarFormat, compression: compression, excluding: exclude,+ progress: verbose ? { print($0.currentPath) } : nil+ )+ if !verbose { print("packed \(written) entries into \(file.path)") }+ }+}++// MARK: - decompress++struct Decompress: ParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "decompress",+ abstract: "Unwrap a single compressed file, leaving what is inside packed",+ discussion: """+ What `zstd -d -f x.tar.zst -o x.tar` does. The result is still a tar;+ use `extract` to unpack it.+ """+ )++ @Option(name: [.customShort("f"), .long], help: "File to decompress",+ transform: URL.init(fileURLWithPath:))+ var file: URL++ @Option(name: [.customShort("o"), .long], help: "Where to write the result",+ transform: URL.init(fileURLWithPath:))+ var output: URL++ func run() throws {+ try VPhoneArchiveWriter.decompress(file, to: output)+ print("decompressed \(file.lastPathComponent) → \(output.path)")+ }+}++// MARK: - list++struct List: ParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "list", abstract: "List an archive's members"+ )++ @Option(name: [.customShort("f"), .long], help: "Archive to read",+ transform: URL.init(fileURLWithPath:))+ var file: URL++ @Flag(name: [.customShort("v"), .long], help: "Include mode, owner and size")+ var verbose = false++ func run() throws {+ let entries = try VPhoneArchiveReader.entries(of: file)+ for entry in entries {+ if verbose {+ let mode = String(entry.mode, radix: 8)+ print("\(mode)\t\(entry.uid):\(entry.gid)\t\(entry.size)\t\(entry.path)")+ } else {+ print(entry.path)+ }+ }+ }+}++// MARK: - cat++struct Cat: ParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "cat",+ abstract: "Write one member to stdout without unpacking the archive"+ )++ @Option(name: [.customShort("f"), .long], help: "Archive to read",+ transform: URL.init(fileURLWithPath:))+ var file: URL++ @Argument(help: "Member path inside the archive")+ var member: String++ func run() throws {+ let data = try VPhoneArchiveReader.readMember(member, from: file)+ FileHandle.standardOutput.write(data)+ }+}++VPhoneArchiveCLI.main()diff --git a/tests/VPhoneArchiveTests/NoOverwriteDirTests.swift b/tests/VPhoneArchiveTests/NoOverwriteDirTests.swiftnew file mode 100644index 00000000..c1fe1b18--- /dev/null+++ b/tests/VPhoneArchiveTests/NoOverwriteDirTests.swift@@ -0,0 +1,212 @@+import Foundation+import Testing+@testable import VPhoneArchive++/// `--no-overwrite-dir`, which libarchive does not have.+///+/// This is the first thing in VPhoneArchive that needed a test, because+/// neither of the two behaviours libarchive does offer is the one GNU tar+/// gives us today, and the difference only shows up on a guest volume that+/// will not boot:+///+/// - libarchive's default updates the permissions of directories that already+/// exist. `iosbinpack64.tar` carries entries for `usr/`, `usr/local/` and+/// `System/`, so unpacking it onto an installed iOS volume would stamp the+/// archive's modes over the real ones.+/// - `ARCHIVE_EXTRACT_NO_OVERWRITE` skips *any* existing object, so a regular+/// file that should be replaced silently is not.+@Suite("Extraction: --no-overwrite-dir", .serialized)+struct NoOverwriteDirTests {+ // MARK: - Fixtures++ /// A tar containing `dir/` with a distinctive mode, plus a file inside it+ /// and one beside it.+ static func makeFixture(directoryMode: mode_t = 0o777) throws -> URL {+ let staging = FileManager.default.temporaryDirectory+ .appendingPathComponent("vphone-arc-src-\(UUID().uuidString)")+ let dir = staging.appendingPathComponent("dir")+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)+ try Data("from archive\n".utf8).write(to: dir.appendingPathComponent("inside.txt"))+ try Data("beside\n".utf8).write(to: staging.appendingPathComponent("beside.txt"))+ try FileManager.default.setAttributes(+ [.posixPermissions: NSNumber(value: directoryMode)], ofItemAtPath: dir.path+ )++ let archive = FileManager.default.temporaryDirectory+ .appendingPathComponent("vphone-arc-\(UUID().uuidString).tar")+ try VPhoneArchiveWriter.create(archive: archive, from: staging)+ try? FileManager.default.removeItem(at: staging)+ return archive+ }++ static func makeDestination() throws -> URL {+ let url = FileManager.default.temporaryDirectory+ .appendingPathComponent("vphone-arc-dst-\(UUID().uuidString)")+ try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)+ return url+ }++ static func mode(of url: URL) throws -> mode_t {+ var info = stat()+ #expect(lstat(url.path, &info) == 0)+ return info.st_mode & 0o7777+ }++ // MARK: - The behaviour that matters++ @Test("an existing directory keeps its own permissions")+ func existingDirectoryKeepsItsMode() throws {+ let archive = try Self.makeFixture(directoryMode: 0o777)+ let destination = try Self.makeDestination()+ defer {+ try? FileManager.default.removeItem(at: archive)+ try? FileManager.default.removeItem(at: destination)+ }++ // Stand in for a real directory on the guest volume: it exists, and+ // its mode is not the archive's.+ let existing = destination.appendingPathComponent("dir")+ try FileManager.default.createDirectory(at: existing, withIntermediateDirectories: true)+ try FileManager.default.setAttributes(+ [.posixPermissions: NSNumber(value: 0o700)], ofItemAtPath: existing.path+ )++ var options = VPhoneArchiveExtractOptions.intoHostDirectory+ options.noOverwriteDir = true+ try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)++ #expect(try Self.mode(of: existing) == 0o700)+ }++ @Test("without the flag, the archive's permissions win — the behaviour we must not have")+ func defaultOverwritesTheMode() throws {+ let archive = try Self.makeFixture(directoryMode: 0o777)+ let destination = try Self.makeDestination()+ defer {+ try? FileManager.default.removeItem(at: archive)+ try? FileManager.default.removeItem(at: destination)+ }++ let existing = destination.appendingPathComponent("dir")+ try FileManager.default.createDirectory(at: existing, withIntermediateDirectories: true)+ try FileManager.default.setAttributes(+ [.posixPermissions: NSNumber(value: 0o700)], ofItemAtPath: existing.path+ )++ var options = VPhoneArchiveExtractOptions.intoHostDirectory+ options.noOverwriteDir = false+ try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)++ // `man 3 archive_write_disk`: "existing directories will have their+ // permissions updated". Confirmed — 0700 in, 0777 out. This is+ // precisely what must not happen to `usr/`, `usr/local/` and+ // `System/` on an installed iOS volume, and it is why noOverwriteDir+ // exists rather than being a courtesy.+ //+ // Pinned so a libarchive change shows up here rather than as a guest+ // that will not boot.+ #expect(try Self.mode(of: existing) == 0o777)+ }++ @Test("skipping a directory header still writes the files under it")+ func filesUnderASkippedDirectoryAreStillWritten() throws {+ let archive = try Self.makeFixture()+ let destination = try Self.makeDestination()+ defer {+ try? FileManager.default.removeItem(at: archive)+ try? FileManager.default.removeItem(at: destination)+ }++ let existing = destination.appendingPathComponent("dir")+ try FileManager.default.createDirectory(at: existing, withIntermediateDirectories: true)++ var options = VPhoneArchiveExtractOptions.intoHostDirectory+ options.noOverwriteDir = true+ try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)++ // This is the difference from ARCHIVE_EXTRACT_NO_OVERWRITE, which+ // would have skipped the whole subtree.+ let inside = existing.appendingPathComponent("inside.txt")+ #expect(FileManager.default.fileExists(atPath: inside.path))+ #expect(try String(contentsOf: inside, encoding: .utf8) == "from archive\n")+ }++ @Test("an existing regular file is still replaced")+ func existingFilesAreStillOverwritten() throws {+ let archive = try Self.makeFixture()+ let destination = try Self.makeDestination()+ defer {+ try? FileManager.default.removeItem(at: archive)+ try? FileManager.default.removeItem(at: destination)+ }++ let beside = destination.appendingPathComponent("beside.txt")+ try Data("stale\n".utf8).write(to: beside)++ var options = VPhoneArchiveExtractOptions.intoHostDirectory+ options.noOverwriteDir = true+ try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)++ // The other half of why ARCHIVE_EXTRACT_NO_OVERWRITE is not a+ // substitute: it would have left "stale" in place.+ #expect(try String(contentsOf: beside, encoding: .utf8) == "beside\n")+ }++ @Test("a directory that does not exist yet is created normally")+ func newDirectoriesAreUnaffected() throws {+ let archive = try Self.makeFixture(directoryMode: 0o755)+ let destination = try Self.makeDestination()+ defer {+ try? FileManager.default.removeItem(at: archive)+ try? FileManager.default.removeItem(at: destination)+ }++ var options = VPhoneArchiveExtractOptions.intoHostDirectory+ options.noOverwriteDir = true+ try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)++ let dir = destination.appendingPathComponent("dir")+ #expect(FileManager.default.fileExists(atPath: dir.path))+ #expect(try Self.mode(of: dir) == 0o755)+ }++ @Test("a symlink standing where a directory would go is replaced, not followed")+ func symlinkIsNotFollowed() throws {+ let archive = try Self.makeFixture()+ let destination = try Self.makeDestination()+ defer {+ try? FileManager.default.removeItem(at: archive)+ try? FileManager.default.removeItem(at: destination)+ }++ // A planted symlink is the classic way to get an unpacker to write+ // somewhere it was not asked to.+ let elsewhere = destination.appendingPathComponent("elsewhere")+ try FileManager.default.createDirectory(at: elsewhere, withIntermediateDirectories: true)+ try FileManager.default.createSymbolicLink(+ at: destination.appendingPathComponent("dir"), withDestinationURL: elsewhere+ )++ var options = VPhoneArchiveExtractOptions.intoHostDirectory+ options.noOverwriteDir = true+ try VPhoneArchiveExtractor.extract(archive, into: destination, options: options)++ // Two things have to hold, and both do.+ //+ // The skip check uses lstat, so the symlink is not mistaken for an+ // existing directory and quietly left in place — which is what would+ // have made the write go through it.+ //+ // ARCHIVE_EXTRACT_SECURE_SYMLINKS then removes it and creates a real+ // directory, so nothing lands in `elsewhere`.+ var info = stat()+ #expect(lstat(destination.appendingPathComponent("dir").path, &info) == 0)+ #expect((info.st_mode & S_IFMT) == S_IFDIR)+ #expect(!FileManager.default.fileExists(+ atPath: elsewhere.appendingPathComponent("inside.txt").path+ ))+ #expect(FileManager.default.fileExists(+ atPath: destination.appendingPathComponent("dir/inside.txt").path+ ))+ }+}diff --git a/tests/VPhoneArchiveTests/RoundTripTests.swift b/tests/VPhoneArchiveTests/RoundTripTests.swiftnew file mode 100644index 00000000..4d608fe7--- /dev/null+++ b/tests/VPhoneArchiveTests/RoundTripTests.swift@@ -0,0 +1,243 @@+import Foundation+import Testing+@testable import VPhoneArchive++/// `.serialized` because these do real filesystem work and libarchive leaves+/// `tar.XXXXXXXX` temp files in the process's working directory when several+/// run at once. Serialised, it does not.+@Suite("Archive round trips and path safety", .serialized)+struct RoundTripTests {+ static func makeTree() throws -> URL {+ let root = FileManager.default.temporaryDirectory+ .appendingPathComponent("vphone-rt-\(UUID().uuidString)")+ let nested = root.appendingPathComponent("a/b")+ try FileManager.default.createDirectory(at: nested, withIntermediateDirectories: true)+ try Data("hello\n".utf8).write(to: root.appendingPathComponent("top.txt"))+ try Data(repeating: 0x5A, count: 300_000).write(to: nested.appendingPathComponent("big.bin"))+ try FileManager.default.createSymbolicLink(+ atPath: root.appendingPathComponent("link").path,+ withDestinationPath: "top.txt"+ )+ try Data("skip me\n".utf8).write(to: root.appendingPathComponent("excluded.log"))+ return root+ }++ static func scratch(_ suffix: String) -> URL {+ FileManager.default.temporaryDirectory+ .appendingPathComponent("vphone-rt-\(suffix)-\(UUID().uuidString)")+ }++ @Test(+ "tar round trip preserves contents, nesting and symlinks",+ arguments: [+ VPhoneArchiveCompression.none,+ .zstd(level: 3),+ .xz(level: 1),+ .gzip(level: 1),+ ]+ )+ func roundTrip(compression: VPhoneArchiveCompression) throws {+ let source = try Self.makeTree()+ let archive = Self.scratch("arc").appendingPathExtension(compression.tarExtension)+ let destination = Self.scratch("out")+ try FileManager.default.createDirectory(at: destination, withIntermediateDirectories: true)+ defer {+ for url in [source, archive, destination] {+ try? FileManager.default.removeItem(at: url)+ }+ }++ try VPhoneArchiveWriter.create(archive: archive, from: source, compression: compression)+ try VPhoneArchiveExtractor.extract(+ archive, into: destination, options: .intoHostDirectory+ )++ #expect(try String(+ contentsOf: destination.appendingPathComponent("top.txt"), encoding: .utf8+ ) == "hello\n")+ #expect(try Data(+ contentsOf: destination.appendingPathComponent("a/b/big.bin")+ ).count == 300_000)++ // The symlink has to come back as a symlink, not as a copy of its+ // target: a bootstrap tar is mostly symlinks, and flattening them+ // silently doubles the volume and breaks relative paths.+ let link = destination.appendingPathComponent("link")+ var info = stat()+ #expect(lstat(link.path, &info) == 0)+ #expect((info.st_mode & S_IFMT) == S_IFLNK)+ #expect(try FileManager.default.destinationOfSymbolicLink(atPath: link.path) == "top.txt")+ }++ @Test("the compressor actually ran")+ func compressionIsApplied() throws {+ let source = try Self.makeTree()+ let plain = Self.scratch("plain").appendingPathExtension("tar")+ let compressed = Self.scratch("zstd").appendingPathExtension("tzst")+ defer {+ for url in [source, plain, compressed] { try? FileManager.default.removeItem(at: url) }+ }++ try VPhoneArchiveWriter.create(archive: plain, from: source)+ try VPhoneArchiveWriter.create(archive: compressed, from: source, compression: .zstd(level: 3))++ // 300 KB of one repeated byte: if it did not shrink, no compressor ran.+ let plainSize = try FileManager.default.attributesOfItem(atPath: plain.path)[.size] as? Int ?? 0+ let smallSize = try FileManager.default.attributesOfItem(atPath: compressed.path)[.size] as? Int ?? 0+ #expect(smallSize < plainSize / 10)++ let described = try VPhoneArchiveReader.describe(compressed)+ #expect(described.filter == "zstd")+ }++ @Test("member paths are relative, even when the source is reached through a symlink")+ func memberPathsAreRelative() throws {+ let source = try Self.makeTree()+ let archive = Self.scratch("rel").appendingPathExtension("tar")+ defer {+ for url in [source, archive] { try? FileManager.default.removeItem(at: url) }+ }++ try VPhoneArchiveWriter.create(archive: archive, from: source)+ let paths = try VPhoneArchiveReader.entries(of: archive).map(\.path)+ #expect(paths.allSatisfy { !$0.hasPrefix("/") })+ #expect(paths.contains("top.txt"))+ #expect(paths.contains("a/b/big.bin"))++ // The case the suite missed for a while. Foundation's path+ // standardisation strips a /private prefix, so a source under+ // /private/tmp compared against its own standardised form never+ // matched its root, and every member was stored absolute. The tests+ // did not catch it because FileManager's temporaryDirectory is+ // /var/folders/..., which has no /private to strip.+ let viaPrivate = URL(fileURLWithPath: "/private" + source.path)+ if FileManager.default.fileExists(atPath: viaPrivate.path) {+ let second = Self.scratch("rel2").appendingPathExtension("tar")+ defer { try? FileManager.default.removeItem(at: second) }+ try VPhoneArchiveWriter.create(archive: second, from: viaPrivate)+ let viaPrivatePaths = try VPhoneArchiveReader.entries(of: second).map(\.path)+ // Only that they are relative. Comparing the two member lists+ // outright would be asserting that nothing else in TMPDIR changed+ // between the two packs, which is not this test's business and is+ // not true while other tests are running.+ #expect(viaPrivatePaths.allSatisfy { !$0.hasPrefix("/") })+ #expect(viaPrivatePaths.contains("top.txt"))+ }+ }++ @Test("exclusions are applied")+ func exclusions() throws {+ let source = try Self.makeTree()+ let archive = Self.scratch("exc").appendingPathExtension("tar")+ defer {+ for url in [source, archive] { try? FileManager.default.removeItem(at: url) }+ }++ try VPhoneArchiveWriter.create(archive: archive, from: source, excluding: ["*.log"])+ let paths = try VPhoneArchiveReader.entries(of: archive).map(\.path)+ #expect(!paths.contains("excluded.log"))+ #expect(paths.contains("top.txt"))+ }++ @Test("a single member can be read without unpacking")+ func readMember() throws {+ let source = try Self.makeTree()+ let archive = Self.scratch("member").appendingPathExtension("tar")+ defer {+ for url in [source, archive] { try? FileManager.default.removeItem(at: url) }+ }++ try VPhoneArchiveWriter.create(archive: archive, from: source)+ let data = try VPhoneArchiveReader.readMember("top.txt", from: archive)+ #expect(String(decoding: data, as: UTF8.self) == "hello\n")++ #expect(throws: VPhoneArchiveError.self) {+ try VPhoneArchiveReader.readMember("nope.txt", from: archive)+ }+ }++ @Test("decompress unwraps a single stream without unpacking it")+ func decompress() throws {+ // What `zstd -d -f bootstrap.tar.zst -o bootstrap.tar` does: the input+ // is one compressed file and the output is the tar, still packed.+ let source = try Self.makeTree()+ let tar = Self.scratch("inner").appendingPathExtension("tar")+ let compressed = Self.scratch("inner").appendingPathExtension("tar.zst")+ let restored = Self.scratch("restored").appendingPathExtension("tar")+ defer {+ for url in [source, tar, compressed, restored] {+ try? FileManager.default.removeItem(at: url)+ }+ }++ // Compress an existing tar, rather than packing the tree twice: two+ // independent packs of the same tree are not expected to be+ // byte-identical (traversal order is not promised), so comparing them+ // would assert something that is not true.+ try VPhoneArchiveWriter.create(archive: tar, from: source)+ let staging = Self.scratch("stage")+ try FileManager.default.createDirectory(at: staging, withIntermediateDirectories: true)+ defer { try? FileManager.default.removeItem(at: staging) }+ try FileManager.default.copyItem(at: tar, to: staging.appendingPathComponent("inner.tar"))+ try VPhoneArchiveWriter.create(+ archive: compressed, from: staging, compression: .zstd(level: 3)+ )++ // What decompress gives back is the tar.zst's single stream, which+ // here is the outer tar containing inner.tar.+ try VPhoneArchiveWriter.decompress(compressed, to: restored)+ let members = try VPhoneArchiveReader.entries(of: restored).map(\.path)+ #expect(members == ["inner.tar"])++ // And it is still an archive, not a decompressed blob: the inner tar+ // comes out byte-identical to the one that went in.+ #expect(try VPhoneArchiveReader.readMember("inner.tar", from: restored)+ == Data(contentsOf: tar))+ }++ @Test("a member that escapes the destination is refused")+ func pathEscapeIsRefused() throws {+ // Hand-built, because the writer will not produce one.+ let staging = Self.scratch("evil")+ try FileManager.default.createDirectory(at: staging, withIntermediateDirectories: true)+ let archive = Self.scratch("evil").appendingPathExtension("tar")+ let destination = Self.scratch("victim")+ try FileManager.default.createDirectory(at: destination, withIntermediateDirectories: true)+ defer {+ for url in [staging, archive, destination] {+ try? FileManager.default.removeItem(at: url)+ }+ }++ try Data("pwned\n".utf8).write(to: staging.appendingPathComponent("payload"))+ try VPhoneArchiveWriter.create(archive: archive, from: staging)+ try rewriteFirstMemberName(of: archive, to: "../escaped")++ #expect(throws: VPhoneArchiveError.self) {+ try VPhoneArchiveExtractor.extract(+ archive, into: destination, options: .intoHostDirectory+ )+ }+ #expect(!FileManager.default.fileExists(+ atPath: destination.deletingLastPathComponent().appendingPathComponent("escaped").path+ ))+ }++ /// Overwrite the name in a ustar/gnutar header in place. The name field is+ /// 100 bytes at offset 0 of the header block, and the header checksum has+ /// to be recomputed or libarchive rejects the entry before we see it.+ private func rewriteFirstMemberName(of archive: URL, to name: String) throws {+ var bytes = try [UInt8](Data(contentsOf: archive))+ for i in 0..<100 { bytes[i] = 0 }+ for (i, byte) in Array(name.utf8).enumerated() { bytes[i] = byte }++ for i in 148..<156 { bytes[i] = UInt8(ascii: " ") } // checksum field reads as spaces+ let sum = (0..<512).reduce(0) { $0 + Int(bytes[$1]) }+ let octal = String(format: "%06o", sum)+ for (i, byte) in Array(octal.utf8).enumerated() { bytes[148 + i] = byte }+ bytes[154] = 0+ bytes[155] = UInt8(ascii: " ")++ try Data(bytes).write(to: archive)+ }+}diff --git a/vendor/libarchive.xcframework b/vendor/libarchive.xcframeworknew file mode 160000index 00000000..3bda868f--- /dev/null+++ b/vendor/libarchive.xcframework@@ -0,0 +1 @@+Subproject commit 3bda868f1868790de2dd246a9eff76eeecba3537