Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
42.1 KB
Raw Blame
// CustomFirmwarePostRestoreDeviceTree.swift — post-restore DT identity rewrite.
//
// Swift port of scripts/patchers/cfw_patch_post_restore_dt.py (EXP-JB-6).
//
// Three root properties of the restored device tree, and only three:
//
//     root/model        "iPhone99,11"  -> "iPhone17,3"
//     root/target-type  "VPHONE600"    -> "D47"
//     root/compatible   ["VPHONE600AP", "iPhone99,11", "AppleVirtualPlatformARM"]
//                       -> ["D47AP", "VPHONE600AP", "AppleVirtualPlatformARM"]
//
// They are restore-time fatal, which is why they are not in
// `DeviceTreePatcher.identityPropertyPatches` with the other eight:
// `restored_external` and iBoot's restore mode cross-check DT root `model`
// and `target-type` against the BuildManifest's signed identity and reject
// the device on mismatch. Both were tried at fw_patch time, both broke
// restore. They are not boot-time fatal — after restore, the iBSS / iBEC /
// LLB `image4_validate_property_callback` bypass accepts any IM4P contents
// — so the install pipeline re-patches the DT offline, on the host-mounted
// restored filesystem, before the device boots into the rootfs.
//
// The `compatible` rewrite is a reorder, not a replacement: VPHONE600AP
// stays in the list, now second, so IOKit's platform-expert binding to
// AppleVMApple1IO still works. The first entry — the one userland reads for
// `hw.model` — becomes D47AP.
//
// Every property keeps its original slot length, so the serialized tree is
// the same size as the one parsed. That is asserted, not assumed.

import Foundation
import Img4tool
import VPhonePatchKit

/// Rewrites the three restore-fatal identity properties in a
/// `devicetree.img4` (or bare `.im4p`), in place, preserving the container's
/// compression, manifest and restore info.
public enum CustomFirmwarePostRestoreDeviceTree {
    // MARK: - Targets

    static let targetModel = "iPhone17,3"
    static let targetTargetType = "D47"

    /// The reordered `compatible` body, NUL-delimited, before slot padding.
    static let targetCompatibleBody = Data(
        "D47AP\0VPHONE600AP\0AppleVirtualPlatformARM\0".utf8,
    )

    // MARK: - Results

    /// One property rewrite, as the log line describes it.
    public struct Change: Sendable, Equatable {
        public let property: String
        public let before: String
        public let after: String
    }

    /// What a patch attempt did.
    public struct Outcome: Sendable, Equatable {
        public let changes: [Change]
        /// Bytes landed on disk. False when the DT was already in the target
        /// state, or when `dryRun` suppressed the write.
        public let wrote: Bool
        /// Size of the rebuilt container, or the original's when nothing changed.
        public let outputSize: Int
    }

    // MARK: - File-level patching

    @discardableResult
    public static func presentIOS16EphemeralStorage(at url: URL, dryRun: Bool = false) throws -> Outcome {
        try rewrite(at: url, dryRun: dryRun, verbose: true) { blob in
            let (result, changes) = try withIOS16EphemeralStorage(blob)
            return (result, changes, blob.count)
        }
    }

    /// Native XNU hw.ephemeral_storage and the corresponding MobileGestalt
    /// product answer, for an explicitly selected fresh, keybag-less lab.
    /// Existing slots only: no topology, size, root identity or disk edit.
    public static func withIOS16EphemeralStorage(_ blob: Data) throws -> (Data, [Change]) {
        let root = try parseTree(blob, label: "DT")
        var changes: [Change] = []
        for (nodeName, propertyName) in [("chosen", "ephemeral-storage"), ("product", "ephemeral-data-mode")] {
            let nodes = root.children.filter { child in
                child.properties.contains { $0.name == "name" && String(decoding: $0.value.prefix(while: { $0 != 0 }), as: UTF8.self) == nodeName }
            }
            guard nodes.count == 1, let property = nodes.first?.properties.first(where: { $0.name == propertyName }),
                  (nodeName == "chosen" ? [4] : [4, 8]).contains(property.value.count),
                  property.value.dropFirst().allSatisfy({ $0 == 0 }), property.value.first.map({ $0 <= 1 }) == true
            else { throw PatcherError.patchVerificationFailed("iOS 16 ephemeral storage: unknown \(nodeName)/\(propertyName) slot") }
            if property.value.first == 0 {
                property.value[0] = 1
                changes.append(Change(property: "\(nodeName)/\(propertyName)", before: "0", after: "1"))
            }
        }
        return (changes.isEmpty ? blob : serializeNode(root), changes)
    }

    /// Patch a `devicetree.img4` (preferred) or bare `devicetree.im4p` in place.
    @discardableResult
    public static func patch(
        at url: URL,
        dryRun: Bool = false,
        verbose: Bool = true,
    ) throws -> Outcome {
        // Every identity rewrite lands in the property's existing slot.
        try rewrite(at: url, dryRun: dryRun, verbose: verbose) { blob in
            let (newBlob, changes) = try patchedDeviceTree(blob)
            return (newBlob, changes, blob.count)
        }
    }

    /// Give an iPad guest's `devicetree.img4` (or bare `.im4p`) the audio node
    /// of the iPad's own tree at `boardURL`, in place. See
    /// `DeviceTreePatcher.presentBoardAudio`.
    @discardableResult
    public static func presentBoardAudio(
        at url: URL,
        board boardURL: URL,
        dryRun: Bool = false,
        verbose: Bool = true,
    ) throws -> Outcome {
        let boardData: Data
        do {
            boardData = try Data(contentsOf: boardURL)
        } catch {
            throw PatcherError.fileNotFound(boardURL.path)
        }
        let board = try openDeviceTree(boardData, path: boardURL.path).blob
        return try rewrite(at: url, dryRun: dryRun, verbose: verbose) { blob in
            let (newBlob, changes, delta) = try withBoardAudio(blob, board: board)
            return (newBlob, changes, blob.count + delta)
        }
    }

    /// Give an iPhone guest's `devicetree.img4` (or bare `.im4p`) the product
    /// description of the iPhone's own tree at `boardURL`, in place. See
    /// `DeviceTreePatcher.presentPhoneProduct`.
    @discardableResult
    public static func presentPhoneProduct(
        at url: URL,
        board boardURL: URL,
        dryRun: Bool = false,
        verbose: Bool = true,
    ) throws -> Outcome {
        let boardData: Data
        do {
            boardData = try Data(contentsOf: boardURL)
        } catch {
            throw PatcherError.fileNotFound(boardURL.path)
        }
        let board = try openDeviceTree(boardData, path: boardURL.path).blob
        return try rewrite(at: url, dryRun: dryRun, verbose: verbose) { blob in
            let (newBlob, changes, delta) = try withPhoneProduct(blob, board: board)
            return (newBlob, changes, blob.count + delta)
        }
    }

    /// Restore only the HomePod mini donor's native MobileGestalt audio product
    /// token, keeping personalized IMG4 data and the payload compression.
    @discardableResult
    public static func presentHomePodAudioProduct(
        at url: URL,
        board boardURL: URL,
        dryRun: Bool = false,
        verbose: Bool = true,
    ) throws -> Outcome {
        let boardData: Data
        do {
            boardData = try Data(contentsOf: boardURL)
        } catch {
            throw PatcherError.fileNotFound(boardURL.path)
        }
        let board = try openDeviceTree(boardData, path: boardURL.path).blob
        return try rewrite(at: url, dryRun: dryRun, verbose: verbose) { blob in
            let (newBlob, changes, delta) = try withHomePodAudioProduct(blob, board: board)
            return (newBlob, changes, blob.count + delta)
        }
    }

    /// Remove `/product/haptics` from a guest's `devicetree.img4` (or bare
    /// `.im4p`), in place. See `DeviceTreePatcher.removeHaptics(from:)`.
    @discardableResult
    public static func removeHaptics(
        at url: URL,
        dryRun: Bool = false,
        verbose: Bool = true,
    ) throws -> Outcome {
        try rewrite(at: url, dryRun: dryRun, verbose: verbose) { blob in
            let (newBlob, changes, delta) = try withoutHaptics(blob)
            return (newBlob, changes, blob.count + delta)
        }
    }

    /// Remove the microphone array claims from `/product/audio` in a guest's
    /// `devicetree.img4` (or bare `.im4p`), in place. See
    /// `DeviceTreePatcher.removeMicrophoneArrayClaims(from:)`.
    @discardableResult
    public static func removeMicrophoneArrayClaims(
        at url: URL,
        dryRun: Bool = false,
        verbose: Bool = true,
    ) throws -> Outcome {
        try rewrite(at: url, dryRun: dryRun, verbose: verbose) { blob in
            let (newBlob, changes, delta) = try withoutMicrophoneArrayClaims(blob)
            return (newBlob, changes, blob.count + delta)
        }
    }

    /// The Preboot kernelcache IMG4 with its IM4P replaced by the patched
    /// kernelcache's IM4P, keeping the IM4M; nil when they already match.
    ///
    /// `prebootIMG4` must be an IMG4 (IM4P + signed IM4M). `patchedKernelcache`
    /// is the restore tree's `fw patch`ed kernelcache, a bare IM4P (an IMG4 is
    /// also accepted and its IM4P taken). Both must be `krnl`. The whole IM4P —
    /// its compression and any PAYP tail included — is carried over verbatim,
    /// so this assumes nothing about how the payload is stored.
    public static func kernelcacheReplacingPayload(
        prebootIMG4: Data,
        patchedKernelcache: Data,
    ) throws -> Data? {
        try firmwareReplacingPayload(prebootIMG4: prebootIMG4, patchedComponent: patchedKernelcache, expectedFourcc: "krnl")
    }

    /// A Preboot component keeps its personalized IM4M and restore information;
    /// only the matching, explicitly named payload type may be replaced.
    public static func firmwareReplacingPayload(
        prebootIMG4: Data,
        patchedComponent: Data,
        expectedFourcc: String
    ) throws -> Data? {
        let container = try Container(prebootIMG4)
        guard container.isIMG4 else {
            throw PatcherError.invalidFormat("the Preboot kernelcache is a bare IM4P; expected an IMG4 with a manifest")
        }
        let sourceIM4P = try Container(patchedComponent).im4pBytes
        let targetFourcc = try IM4P(container.im4pBytes).fourcc
        let sourceFourcc = try IM4P(sourceIM4P).fourcc
        guard targetFourcc == expectedFourcc, sourceFourcc == expectedFourcc else {
            throw PatcherError.invalidFormat(
                "firmware fourcc mismatch: Preboot '\(targetFourcc)', source '\(sourceFourcc)' — expected '\(expectedFourcc)'",
            )
        }
        guard container.im4pBytes != sourceIM4P else { return nil }
        return try container.rebuilt(im4pBytes: sourceIM4P)
    }

    /// The container, payload and flat tree of a device tree file. Refuses a
    /// payload that is not a device tree, is encrypted, or came back still
    /// compressed.
    private static func openDeviceTree(
        _ data: Data,
        path: String,
    ) throws -> (container: Container, im4p: IM4P, compression: PayloadCompression, blob: Data) {
        let container = try Container(data)
        let im4p = try IM4P(container.im4pBytes)
        guard im4p.fourcc == "dtre" else {
            throw PatcherError.invalidFormat(
                "expected DT payload (fourcc='dtre'), got fourcc='\(im4p.fourcc)'",
            )
        }
        guard !im4p.isEncrypted else {
            throw PatcherError.invalidFormat("DT payload is encrypted (KBAG present): \(path)")
        }
        let compression = try container.payloadCompression()
        let blob = try im4p.payload()
        // Img4tool finds the uncompressed size in the IM4P's compression-info
        // element rather than in the bvx2 stream, so a container that carries
        // the magic but not the element comes back still compressed. Refuse
        // it: the alternative is parsing compressed bytes as a device tree.
        guard compression == .none || !compression.isStillCompressed(blob) else {
            throw PatcherError.invalidFormat(
                "IM4P payload is \(compression) but did not decompress — no compression-info element?",
            )
        }
        return (container, im4p, compression, blob)
    }

    /// Open the container, apply `transform` to the flat device tree, and
    /// write the container back with its compression, manifest and restore
    /// info when anything changed. `transform` also returns the size its
    /// output must have, which is checked: a mismatch means the parser and the
    /// serializer have drifted apart.
    private static func rewrite(
        at url: URL,
        dryRun: Bool,
        verbose: Bool,
        transform: (Data) throws -> (Data, [Change], Int),
    ) throws -> Outcome {
        let data: Data
        do {
            data = try Data(contentsOfFileToRewrite: url)
        } catch {
            throw PatcherError.fileNotFound(url.path)
        }

        let (container, im4p, compression, blob) = try openDeviceTree(data, path: url.path)
        if verbose {
            print("  [.] \(url.path): \(container.isIMG4 ? "IMG4" : "IM4P")  desc='\(im4p.description)'  "
                + "payload_compression=\(compression.rawValue)")
            print("  [.] DT blob: \(blob.count) bytes")
        }

        let (newBlob, changes, expectedSize) = try transform(blob)
        guard !changes.isEmpty else {
            if verbose {
                print("  [.] \(url.path): DT already in target state — no change")
            }
            return Outcome(changes: [], wrote: false, outputSize: data.count)
        }
        if verbose {
            for change in changes {
                print("  [+] \(change.property): '\(change.before)' -> '\(change.after)'")
            }
        }
        guard newBlob.count == expectedSize else {
            throw PatcherError.patchVerificationFailed(
                "DT is \(newBlob.count) bytes, expected \(expectedSize) (was \(blob.count)): parser and serializer disagree",
            )
        }

        let newIM4P = try IM4P(
            fourcc: im4p.fourcc,
            description: im4p.description,
            payload: newBlob,
            compression: compression.img4toolName,
        )
        let output = try container.rebuilt(im4pBytes: newIM4P.data)

        if verbose {
            print("  [.] output size: \(output.count) bytes (was \(data.count))")
        }
        if dryRun {
            if verbose {
                print("  [.] dry-run — not writing back")
            }
            return Outcome(changes: changes, wrote: false, outputSize: output.count)
        }

        try output.write(to: url)
        if verbose {
            print("  [+] wrote \(url.path)")
        }
        return Outcome(changes: changes, wrote: true, outputSize: output.count)
    }

    // MARK: - Device tree patching

    /// Apply the three identity rewrites to a flat device tree blob.
    /// Returns the blob unchanged and no changes when it is already in the
    /// target state.
    public static func patchedDeviceTree(_ blob: Data) throws -> (Data, [Change]) {
        let root = try parseTree(blob, label: "DT")
        guard nodeName(root) == "device-tree" else {
            throw PatcherError.invalidFormat(
                "expected root node 'device-tree', got '\(nodeName(root))'",
            )
        }

        var changes: [Change] = []

        let model = try property(root, named: "model")
        let newModel = encodeFixedString(targetModel, length: model.length)
        if model.value != newModel {
            changes.append(Change(
                property: "model",
                before: cString(model.value),
                after: targetModel,
            ))
            model.value = newModel
        }

        let targetType = try property(root, named: "target-type")
        let newTargetType = encodeFixedString(targetTargetType, length: targetType.length)
        if targetType.value != newTargetType {
            changes.append(Change(
                property: "target-type",
                before: cString(targetType.value),
                after: targetTargetType,
            ))
            targetType.value = newTargetType
        }

        let compatible = try property(root, named: "compatible")
        guard targetCompatibleBody.count <= compatible.length else {
            throw PatcherError.invalidFormat(
                "compatible body \(targetCompatibleBody.count)B > slot \(compatible.length)B",
            )
        }
        var newCompatible = targetCompatibleBody
        newCompatible.append(
            contentsOf: [UInt8](repeating: 0, count: compatible.length - newCompatible.count),
        )
        if compatible.value != newCompatible {
            changes.append(Change(
                property: "compatible",
                before: "[\(cStringList(compatible.value).joined(separator: ", "))]",
                after: "[D47AP, VPHONE600AP, AppleVirtualPlatformARM]",
            ))
            compatible.value = newCompatible
        }

        guard !changes.isEmpty else { return (blob, []) }
        return (serializeNode(root), changes)
    }

    /// `blob` with `/product/audio` taken from the board's flat tree `board`,
    /// through `DeviceTreePatcher.presentBoardAudio`, which fw patch uses for
    /// a new iPad guest. Returns the size change with the changes, so the caller
    /// can check the serialized size: the node's old bytes out, its new bytes in.
    /// A tree that already matches, or a board with no audio node, comes back
    /// unchanged.
    public static func withBoardAudio(_ blob: Data, board: Data) throws -> (Data, [Change], Int) {
        func acousticID(_ node: Data) -> String {
            guard let (audio, _) = try? parseNode(node, at: 0),
                  let id = audio.properties.first(where: { $0.name == "acoustic-id" }),
                  id.length == 4
            else { return "none" }
            return String(id.value.loadLE(UInt32.self, at: 0))
        }
        let root = try parseTree(blob, label: "DT")
        let source = try parseTree(board, label: "board DT")
        guard let change = DeviceTreePatcher.presentBoardAudio(in: root, from: source) else {
            return (blob, [], 0)
        }
        let record = Change(
            property: "product/audio",
            before: "acoustic-id \(acousticID(change.before))",
            after: "acoustic-id \(acousticID(change.after)), \(change.after.count)B",
        )
        return (serializeNode(root), [record], change.after.count - change.before.count)
    }

    /// `blob` with the product description of the iPhone's own flat tree
    /// `board`, through `DeviceTreePatcher.presentPhoneProduct`. Returns the
    /// size change with the changes: a filled placeholder trades its value's
    /// padded length for the board's, an added property brings its 36-byte
    /// header too. A tree that already has them comes back unchanged.
    public static func withPhoneProduct(_ blob: Data, board: Data) throws -> (Data, [Change], Int) {
        func describe(_ value: Data) -> String {
            let text = value.prefix(while: { $0 != 0 })
            if !text.isEmpty, text.count == value.count - 1 || text.count == value.count,
               let string = String(data: text, encoding: .utf8), string.allSatisfy({ $0.isASCII && !$0.isNewline })
            {
                return string
            }
            return value.hex
        }
        let root = try parseTree(blob, label: "DT")
        let source = try parseTree(board, label: "board DT")
        let changes = DeviceTreePatcher.presentPhoneProduct(in: root, from: source)
        guard !changes.isEmpty else { return (blob, [], 0) }
        let records = changes.map {
            Change(property: $0.path, before: $0.before.map(describe) ?? "absent", after: describe($0.after))
        }
        let delta = changes.reduce(0) { sum, change in
            sum + align4(change.after.count) - (change.before.map { align4($0.count) } ?? -36)
        }
        return (serializeNode(root), records, delta)
    }

    public static func withHomePodAudioProduct(_ blob: Data, board: Data) throws -> (Data, [Change], Int) {
        let root = try parseTree(blob, label: "DT")
        let source = try parseTree(board, label: "HomePod board DT")
        guard let change = try DeviceTreePatcher.presentHomePodAudioProduct(in: root, from: source) else {
            return (blob, [], 0)
        }
        let record = Change(property: "product/product-id", before: change.before?.hex ?? "absent", after: change.after.hex)
        let delta = align4(change.after.count) - (change.before.map { align4($0.count) } ?? -36)
        return (serializeNode(root), [record], delta)
    }

    @discardableResult
    public static func presentHomePodCryptexClass(at url: URL, dryRun: Bool = false, verbose: Bool = true) throws -> Outcome {
        try rewrite(at: url, dryRun: dryRun, verbose: verbose) { blob in
            let (newBlob, changes, delta) = try withHomePodCryptexClass(blob)
            return (newBlob, changes, blob.count + delta)
        }
    }

    public static func withHomePodCryptexClass(_ blob: Data) throws -> (Data, [Change], Int) {
        let root = try parseTree(blob, label: "HomePod DT")
        guard let change = try DeviceTreePatcher.presentHomePodCryptexClass(in: root) else { return (blob, [], 0) }
        return (serializeNode(root), [Change(property: "product/cryptex1-product-class",
                                            before: change.before?.hex ?? "absent", after: change.after.hex)],
                change.before == nil ? 40 : 0)
    }

    /// `blob` without `/product/haptics`, through
    /// `DeviceTreePatcher.removeHaptics(from:)`, which fw patch uses for every
    /// new guest. Returns the size change with the changes, as `withBoardAudio`
    /// does: the node's bytes out. A tree with no haptics node comes back
    /// unchanged.
    public static func withoutHaptics(_ blob: Data) throws -> (Data, [Change], Int) {
        let root = try parseTree(blob, label: "DT")
        guard let removed = DeviceTreePatcher.removeHaptics(from: root) else {
            return (blob, [], 0)
        }
        let record = Change(property: "product/haptics", before: "present, \(removed.count)B", after: "absent")
        return (serializeNode(root), [record], -removed.count)
    }

    /// `blob` without the microphone array claims in `/product/audio`, through
    /// `DeviceTreePatcher.removeMicrophoneArrayClaims(from:)`, which fw patch
    /// uses for every new guest. Returns the size change with the changes: each
    /// property's entry out. A tree with none of them comes back unchanged.
    public static func withoutMicrophoneArrayClaims(_ blob: Data) throws -> (Data, [Change], Int) {
        let root = try parseTree(blob, label: "DT")
        let removed = DeviceTreePatcher.removeMicrophoneArrayClaims(from: root)
        guard !removed.isEmpty else {
            return (blob, [], 0)
        }
        let records = removed.map {
            Change(property: "product/audio/\($0.name)", before: $0.value.hex, after: "absent")
        }
        let delta = removed.reduce(0) { $0 - 36 - align4($1.value.count) }
        return (serializeNode(root), records, delta)
    }

    /// Apple's own VM sub-types for foldable boards, by the board's
    /// `target-sub-type`. SpringBoardFoundation's `SBFDevicePoseProvider`
    /// marks the device a VM when MobileGestalt's `TargetSubType` is the VM
    /// value, and `SBFDisplayContentModeResolver` then restores the fold pose
    /// ("Restore pose on VM") instead of waiting for hinge hardware.
    public static let foldableVMSubtypes = ["V68AP": "V68VM2025"]

    /// Every sub-type that marks a tree a foldable board's: the board's own
    /// values and their VM replacements.
    public static var foldableSubtypes: Set<String> {
        Set(foldableVMSubtypes.keys).union(foldableVMSubtypes.values)
    }

    /// `blob` with its root `target-sub-type` replaced by the board's VM
    /// sub-type. A tree whose sub-type has none, or already has it, comes back
    /// unchanged.
    public static func withFoldableVMSubtype(_ blob: Data) throws -> (Data, [Change], Int) {
        let root = try parseTree(blob, label: "DT")
        guard let property = root.properties.first(where: { $0.name == "target-sub-type" }) else {
            return (blob, [], 0)
        }
        let before = String(decoding: property.value.prefix { $0 != 0 }, as: UTF8.self)
        guard let vm = foldableVMSubtypes[before] else { return (blob, [], 0) }
        let value = Data(vm.utf8) + [0]
        let delta = align4(value.count) - align4(property.value.count)
        property.value = value
        property.flags = 0
        return (serializeNode(root), [Change(property: "target-sub-type", before: before, after: vm)], delta)
    }

    /// Give a foldable guest's `devicetree.img4` (or bare `.im4p`) the board's
    /// VM sub-type, in place. See `withFoldableVMSubtype`.
    @discardableResult
    public static func presentFoldableVMSubtype(
        at url: URL,
        dryRun: Bool = false,
        verbose: Bool = true,
    ) throws -> Outcome {
        try rewrite(at: url, dryRun: dryRun, verbose: verbose) { blob in
            let (newBlob, changes, delta) = try withFoldableVMSubtype(blob)
            return (newBlob, changes, blob.count + delta)
        }
    }

    /// `blob` with `/product/product-id` taken from the foldable board's own
    /// flat tree `board`, through `DeviceTreePatcher.presentFoldableProductID`.
    /// Returns the size change with the changes, as `withHomePodAudioProduct`
    /// does. A tree that is not a foldable guest, or already carries the
    /// board's token, comes back unchanged.
    public static func withFoldableProductId(_ blob: Data, board: Data) throws -> (Data, [Change], Int) {
        let root = try parseTree(blob, label: "DT")
        let source = try parseTree(board, label: "foldable board DT")
        guard let change = try DeviceTreePatcher.presentFoldableProductID(in: root, from: source) else {
            return (blob, [], 0)
        }
        let record = Change(property: "product/product-id", before: change.before?.hex ?? "absent", after: change.after.hex)
        let delta = align4(change.after.count) - (change.before.map { align4($0.count) } ?? -36)
        return (serializeNode(root), [record], delta)
    }

    /// Give a foldable guest's `devicetree.img4` (or bare `.im4p`) the board's
    /// own product token, in place. See `withFoldableProductId`.
    @discardableResult
    public static func presentFoldableProductId(
        at url: URL,
        board boardURL: URL,
        dryRun: Bool = false,
        verbose: Bool = true,
    ) throws -> Outcome {
        let boardData: Data
        do {
            boardData = try Data(contentsOf: boardURL)
        } catch {
            throw PatcherError.fileNotFound(boardURL.path)
        }
        let board = try openDeviceTree(boardData, path: boardURL.path).blob
        return try rewrite(at: url, dryRun: dryRun, verbose: verbose) { blob in
            let (newBlob, changes, delta) = try withFoldableProductId(blob, board: board)
            return (newBlob, changes, blob.count + delta)
        }
    }

    /// `blob` with the foldable board's panel nodes under `/product`, taken
    /// from its flat tree `board` through
    /// `DeviceTreePatcher.presentFoldableDisplays`. Returns the size change
    /// with the changes: each added node's serialized bytes. A tree that is
    /// not a foldable guest, or already has panel nodes, comes back unchanged.
    public static func withFoldableDisplays(_ blob: Data, board: Data) throws -> (Data, [Change], Int) {
        let root = try parseTree(blob, label: "DT")
        let source = try parseTree(board, label: "foldable board DT")
        let nodes = try DeviceTreePatcher.presentFoldableDisplays(in: root, from: source)
        guard !nodes.isEmpty else { return (blob, [], 0) }
        let records = nodes.map { node in
            var name = "?"
            if let (parsed, _) = try? parseNode(node, at: 0),
               let property = parsed.properties.first(where: { $0.name == "name" })
            {
                name = String(decoding: property.value.prefix { $0 != 0 }, as: UTF8.self)
            }
            return Change(property: "product/\(name)", before: "absent", after: "\(node.count)B")
        }
        return (serializeNode(root), records, nodes.reduce(0) { $0 + $1.count })
    }

    /// Give a foldable guest's `devicetree.img4` (or bare `.im4p`) the board's
    /// panel nodes, in place. See `withFoldableDisplays`.
    @discardableResult
    public static func presentFoldableDisplays(
        at url: URL,
        board boardURL: URL,
        dryRun: Bool = false,
        verbose: Bool = true,
    ) throws -> Outcome {
        let boardData: Data
        do {
            boardData = try Data(contentsOf: boardURL)
        } catch {
            throw PatcherError.fileNotFound(boardURL.path)
        }
        let board = try openDeviceTree(boardData, path: boardURL.path).blob
        return try rewrite(at: url, dryRun: dryRun, verbose: verbose) { blob in
            let (newBlob, changes, delta) = try withFoldableDisplays(blob, board: board)
            return (newBlob, changes, blob.count + delta)
        }
    }

    /// The root of a flat tree that must fill `blob` exactly.
    private static func parseTree(_ blob: Data, label: String) throws -> DeviceTreePatcher.DTNode {
        let (root, end) = try parseNode(blob, at: 0)
        guard end == blob.count else {
            throw PatcherError.invalidFormat(
                "\(label) parse length mismatch: ended at \(end), blob is \(blob.count)",
            )
        }
        return root
    }

    // MARK: - Flat device tree format

    //
    // Per node: u32 nProps, u32 nChildren, then each property as
    // char[32] name, u16 length, u16 flags, u8[length] value, padded to a
    // 4-byte boundary; then each child node, recursively.
    //
    // The top bit of the length field is XNU's out-of-line "placeholder"
    // flag and is masked off for the real size. `DeviceTreePatcher` parses
    // the same layout at fw_patch time; this is a second reader only because
    // its own parse/serialize pair is file-private. See `integrationNeeded`
    // in the migration notes.

    private static func align4(_ n: Int) -> Int {
        (n + 3) & ~3
    }

    private static func parseNode(
        _ blob: Data,
        at offset: Int,
    ) throws -> (DeviceTreePatcher.DTNode, Int) {
        guard offset + 8 <= blob.count else {
            throw PatcherError.invalidFormat("DT truncated at offset 0x\(String(offset, radix: 16))")
        }
        let propertyCount = Int(blob.loadLE(UInt32.self, at: offset))
        let childCount = Int(blob.loadLE(UInt32.self, at: offset + 4))
        var pos = offset + 8
        let node = DeviceTreePatcher.DTNode()

        for _ in 0 ..< propertyCount {
            guard pos + 36 <= blob.count else {
                throw PatcherError.invalidFormat(
                    "DT property header truncated at 0x\(String(pos, radix: 16))",
                )
            }
            let name = cString(slice(blob, pos, 32))
            let length = Int(blob.loadLE(UInt16.self, at: pos + 32) & 0x7FFF)
            let flags = blob.loadLE(UInt16.self, at: pos + 34)
            let valueOffset = pos + 36
            guard valueOffset + length <= blob.count else {
                throw PatcherError.invalidFormat(
                    "DT property value '\(name)' truncated at 0x\(String(valueOffset, radix: 16))",
                )
            }
            node.properties.append(DeviceTreePatcher.DTProperty(
                name: name,
                flags: flags,
                value: slice(blob, valueOffset, length),
                valueOffset: valueOffset,
            ))
            pos = valueOffset + align4(length)
        }

        for _ in 0 ..< childCount {
            let (child, next) = try parseNode(blob, at: pos)
            node.children.append(child)
            pos = next
        }
        return (node, pos)
    }

    private static func serializeNode(_ node: DeviceTreePatcher.DTNode) -> Data {
        var out = Data()
        out.append(littleEndian: UInt32(node.properties.count))
        out.append(littleEndian: UInt32(node.children.count))
        for property in node.properties {
            var name = Data(property.name.utf8)
            if name.count >= 32 {
                name = Data(name.prefix(31))
            }
            name.append(contentsOf: [UInt8](repeating: 0, count: 32 - name.count))
            out.append(name)
            out.append(littleEndian: UInt16(property.length))
            out.append(littleEndian: property.flags)
            out.append(property.value)
            let pad = align4(property.length) - property.length
            if pad > 0 {
                out.append(Data(repeating: 0, count: pad))
            }
        }
        for child in node.children {
            out.append(serializeNode(child))
        }
        return out
    }

    private static func nodeName(_ node: DeviceTreePatcher.DTNode) -> String {
        for property in node.properties where property.name == "name" {
            return cString(property.value)
        }
        return ""
    }

    private static func property(
        _ node: DeviceTreePatcher.DTNode,
        named name: String,
    ) throws -> DeviceTreePatcher.DTProperty {
        for property in node.properties where property.name == name {
            return property
        }
        throw PatcherError.patchSiteNotFound(
            "property '\(name)' not found in node '\(nodeName(node))'",
        )
    }

    // MARK: - Value helpers

    /// A NUL-terminated string padded (or truncated) to a fixed slot.
    private static func encodeFixedString(_ text: String, length: Int) -> Data {
        var raw = Data(text.utf8)
        raw.append(0)
        if raw.count > length {
            return Data(raw.prefix(length))
        }
        raw.append(contentsOf: [UInt8](repeating: 0, count: length - raw.count))
        return raw
    }

    private static func cString(_ data: Data) -> String {
        let body = data.prefix(while: { $0 != 0 })
        return String(decoding: body, as: UTF8.self)
    }

    /// Split a NUL-delimited multi-string property into its non-empty parts.
    private static func cStringList(_ data: Data) -> [String] {
        data.split(separator: 0, omittingEmptySubsequences: true)
            .map { String(decoding: $0, as: UTF8.self) }
    }

    private static func slice(_ data: Data, _ offset: Int, _ count: Int) -> Data {
        let start = data.startIndex.advanced(by: offset)
        return Data(data[start ..< start.advanced(by: count)])
    }
}

// MARK: - Image4 container

extension CustomFirmwarePostRestoreDeviceTree {
    /// How the IM4P payload is stored. The raw values are pyimg4's
    /// `Compression` enum, so the log line reads the same either side.
    enum PayloadCompression: Int, Sendable {
        case none = 0
        case lzss = 1
        case lzfse = 2

        var img4toolName: String? {
            switch self {
            case .none: nil
            case .lzss: "lzss"
            case .lzfse: "lzfse"
            }
        }

        var magic: Data? {
            switch self {
            case .none: nil
            case .lzss: Data("complzss".utf8)
            case .lzfse: Data("bvx2".utf8)
            }
        }

        func isStillCompressed(_ payload: Data) -> Bool {
            guard let magic else { return false }
            return payload.starts(with: magic)
        }
    }

    /// An IMG4 or bare IM4P, split so the IM4P can be replaced without
    /// touching anything else.
    ///
    /// For an IMG4 the manifest ([0] IM4M) and restore info ([1] IM4R) are
    /// carried over as their original bytes. pyimg4 re-encodes the IM4M from
    /// its parsed fields instead; preserving the signed bytes verbatim is the
    /// safer of the two, and the difference is invisible for any manifest
    /// that was DER-canonical to begin with.
    struct Container {
        let isIMG4: Bool
        /// Raw DER of the IM4P element.
        let im4pBytes: Data
        /// The IMG4 elements around the IM4P, in order, as raw DER.
        private let leading: Data
        private let trailing: [Data]

        init(_ data: Data) throws {
            let outer = try DER.parse(data, at: 0)
            guard outer.tag == DER.sequence, outer.range.upperBound == data.count else {
                throw PatcherError.invalidFormat("not an Image4 container: trailing or short DER")
            }
            let children = try DER.children(data, of: outer)
            guard let first = children.first, first.tag == DER.ia5String else {
                throw PatcherError.invalidFormat("Image4 container has no type tag")
            }

            switch DER.string(data, first) {
            case "IMG4":
                guard children.count >= 3, children[1].tag == DER.sequence else {
                    throw PatcherError.invalidFormat("IMG4 does not contain an IM4P")
                }
                guard children[2].tag == DER.contextConstructed(0) else {
                    throw PatcherError.invalidFormat("IMG4 does not contain an IM4M")
                }
                isIMG4 = true
                leading = DER.raw(data, first)
                im4pBytes = DER.raw(data, children[1])
                trailing = children[2...].map { DER.raw(data, $0) }
            case "IM4P":
                isIMG4 = false
                leading = Data()
                im4pBytes = data
                trailing = []
            default:
                throw PatcherError.invalidFormat("unrecognized Image4 container type")
            }
        }

        /// Which compression the stored payload uses, sniffed from the
        /// payload's own magic exactly as pyimg4 does.
        func payloadCompression() throws -> PayloadCompression {
            let element = try DER.parse(im4pBytes, at: 0)
            let children = try DER.children(im4pBytes, of: element)
            guard children.count >= 4 else {
                throw PatcherError.invalidFormat("malformed IM4P structure")
            }
            let payload = DER.value(im4pBytes, children[3])
            for candidate in [PayloadCompression.lzss, .lzfse]
                where candidate.isStillCompressed(payload)
            {
                return candidate
            }
            return .none
        }

        /// Reassemble the container around a replacement IM4P.
        func rebuilt(im4pBytes newIM4P: Data) throws -> Data {
            guard isIMG4 else { return newIM4P }
            var body = leading
            body.append(newIM4P)
            for element in trailing {
                body.append(element)
            }
            var out = DER.sequenceHeader(bodyCount: body.count)
            out.append(body)
            return out
        }
    }
}

// MARK: - Minimal DER reader

//
// Enough of DER to walk an Image4 container and splice one element: tags
// are single-byte here, lengths are definite. Img4tool's own DER helpers are
// internal to that module, so this stays private to this file.

private enum DER {
    static let sequence: UInt8 = 0x30
    static let ia5String: UInt8 = 0x16

    static func contextConstructed(_ number: UInt8) -> UInt8 {
        0xA0 | number
    }

    struct Element {
        let tag: UInt8
        let valueRange: Range<Int>
        let range: Range<Int>
    }

    static func parse(_ data: Data, at offset: Int) throws -> Element {
        guard offset + 2 <= data.count else {
            throw PatcherError.invalidFormat("DER truncated at \(offset)")
        }
        let tag = data[data.startIndex + offset]
        let lengthByte = data[data.startIndex + offset + 1]
        var cursor = offset + 2
        let length: Int

        if lengthByte & 0x80 == 0 {
            length = Int(lengthByte)
        } else {
            let byteCount = Int(lengthByte & 0x7F)
            guard byteCount > 0, byteCount <= 8, cursor + byteCount <= data.count else {
                throw PatcherError.invalidFormat("DER length field at \(offset) is not definite")
            }
            var accumulated = 0
            for index in 0 ..< byteCount {
                accumulated = (accumulated << 8) | Int(data[data.startIndex + cursor + index])
            }
            length = accumulated
            cursor += byteCount
        }

        guard cursor + length <= data.count else {
            throw PatcherError.invalidFormat("DER element at \(offset) runs past the buffer")
        }
        return Element(
            tag: tag,
            valueRange: cursor ..< (cursor + length),
            range: offset ..< (cursor + length),
        )
    }

    static func children(_ data: Data, of element: Element) throws -> [Element] {
        var out: [Element] = []
        var offset = element.valueRange.lowerBound
        while offset < element.valueRange.upperBound {
            let child = try parse(data, at: offset)
            out.append(child)
            offset = child.range.upperBound
        }
        return out
    }

    static func raw(_ data: Data, _ element: Element) -> Data {
        subdata(data, element.range)
    }

    static func value(_ data: Data, _ element: Element) -> Data {
        subdata(data, element.valueRange)
    }

    static func string(_ data: Data, _ element: Element) -> String {
        String(decoding: value(data, element), as: UTF8.self)
    }

    /// A SEQUENCE tag plus a minimal definite-length header.
    static func sequenceHeader(bodyCount: Int) -> Data {
        var out = Data([sequence])
        if bodyCount < 0x80 {
            out.append(UInt8(bodyCount))
            return out
        }
        var bytes: [UInt8] = []
        var remaining = bodyCount
        while remaining > 0 {
            bytes.append(UInt8(remaining & 0xFF))
            remaining >>= 8
        }
        bytes.reverse()
        out.append(0x80 | UInt8(bytes.count))
        out.append(contentsOf: bytes)
        return out
    }

    private static func subdata(_ data: Data, _ range: Range<Int>) -> Data {
        let start = data.startIndex.advanced(by: range.lowerBound)
        return Data(data[start ..< start.advanced(by: range.count)])
    }
}

// MARK: - Little-endian append

private extension Data {
    mutating func append(littleEndian value: some FixedWidthInteger) {
        Swift.withUnsafeBytes(of: value.littleEndian) { append(contentsOf: $0) }
    }
}