Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
6.7 KB
Raw Blame
// FirmwarePatchFeature.swift — Patches a machine turns on or off together.
//
// A feature is not a patch set and not a preset: it names patches that already
// belong to sets, and is only useful as a group. Turning it on is the same as
// `--allow` for each of its patches, so the selection on disk stays a list of
// patch identifiers and nothing new has to be resolved. `fw patches --json`
// reports the features, so Launchpad can offer one checkbox for the group
// without declaring any patch of its own.

import Foundation
import VPhonePatchKit

public struct FirmwarePatchFeature: Sendable, Hashable, Identifiable {
    public let identifier: String
    public let title: String
    public let summary: String
    /// What the feature turns on, one entry per part. Most parts are one patch;
    /// a part that presets deliver in different ways lists each patch that does
    /// it, and a preset takes the first one its sets declare.
    public let parts: [[String]]

    public var id: String {
        identifier
    }

    /// Every patch any preset could take for the feature.
    public var allPatches: Set<String> {
        Set(parts.flatMap(\.self))
    }

    /// The patches `preset` turns on for the feature, or nil when it cannot
    /// carry it: some part has no patch in a set the preset names, so `--allow`
    /// would not resolve, or `cfw install` would refuse one of them on the
    /// preset's tvOS-family guest (``FirmwareGuestPatchResolution``).
    public func patches(in preset: VPhonePatchPreset) -> Set<String>? {
        let named = Set(preset.patchSets.map(\.identifier))
        let declared = Set(FirmwarePatchSetCatalog.bundled.filter { named.contains($0.identifier) }
            .flatMap(\.patches).map(\.identifier))
        var result: Set<String> = []
        for part in parts {
            guard let patch = part.first(where: declared.contains) else { return nil }
            result.insert(patch)
        }
        let refused: [String] = switch preset.identifier {
        case VPhonePatchPreset.homePodMiniIdentifier:
            FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: result)
        case VPhonePatchPreset.homeViewIdentifier:
            FirmwareGuestPatchResolution.unvalidatedHomeViewGuestPatches(enabled: result)
        case VPhonePatchPreset.tvOSIdentifier:
            FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: result)
        case VPhonePatchPreset.tvOS4KIdentifier:
            FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: result, arm64eUserland: true)
        default:
            []
        }
        return refused.isEmpty ? result : nil
    }

    public func isAvailable(in preset: VPhonePatchPreset) -> Bool {
        patches(in: preset) != nil
    }
}

extension FirmwarePatchSetCatalog {
    /// Everything a debugger needs to attach to a process in a ``minimalPreset``
    /// guest and read its memory, and no more. `minimal` restores a resealed
    /// system onto a stock kernel and TXM; this adds:
    ///
    /// - A debugserver re-signed with `task_for_pid-allow` and no sandbox
    ///   profile: `filesystem-exp-debugserver` re-signs it before the reseal,
    ///   so its new hash lands in the regenerated trust cache; a preset that
    ///   installs the guest with `cfw install` takes
    ///   `system-debugserver-cfw-install` instead (HomePod and the Apple TV
    ///   presets leave it off).
    /// - launchd's jetsam panic guard, bypassed (`filesystem-exp-launchd_jetsam_panic_guard`
    ///   before the reseal, `system-launchd-boot-jetsam_panic_guard_bypass` with
    ///   `cfw install`). With developer mode on, MobileStorageMounter mounts the
    ///   Developer disk image, and launchd kills init over its daemons
    ///   ("jetsam property category (Daemon) is not initialized").
    /// - `kernel-cfw-task_for_pid` returns a task port for a process the caller
    ///   does not own, and `kernel-boot-task_conversion_eval` lets that port be
    ///   converted.
    /// - `kernel-cfw-debugger` reports the kernel debuggable, which
    ///   `task_for_pid` is gated on.
    /// - `kernel-boot-port_to_map` stops the panic when debugserver converts the
    ///   target's task port to a vm_map to read or write its memory.
    /// - `kernel-boot-proc_security_policy` lets the per-process policy check pass.
    /// - `kernel-boot-cred_label_update_execve` grants the platform label and
    ///   `kernel-boot-hook_cred_label` retargets the MACF hook to that handler;
    ///   the handler is dead code without the hook.
    /// - `txm-boot-developer_mode_bypass` reports developer mode on. On a TXM
    ///   device AMFI asks TXM, and kills the re-signed debugserver without it
    ///   ("Developer mode is disabled, task_for_pid-allow is disallowed");
    ///   enrolling from the guest does not survive a forced reboot.
    /// - `txm-cfw-debugger_entitlement` passes selector 42's (debug memory
    ///   mapping) debugger entitlement check, and `txm-boot-sel42_29` and
    ///   `txm-cfw-get_task_allow` set the target's get-task-allow byte where
    ///   selectors 42 and 41 read it, so a daemon without get-task-allow can be
    ///   debugged (Research/Firmware/txm_jb_patches.md).
    ///
    /// The rest of the kernel sets, and TXM's signature-admission patches, stay
    /// off: the resealed image's own trust cache admits everything it runs,
    /// the re-signed debugserver included, so AMFI's trust cache and execve
    /// patches are not needed (an iPhone17,3 26.5 guest attached without them).
    /// `standard` and its relatives turn every part on already, so the editor
    /// offers no box there.
    public static let userspaceDebugging = FirmwarePatchFeature(
        identifier: "userspace-debugging",
        title: "Userspace debugging",
        summary: "A re-signed debugserver, and the kernel and TXM patches it needs to attach to any process in the guest and read its memory. The kernel and TXM stay otherwise stock.",
        parts: [
            [FirmwareRestoreImagePatchSet.debugserver, "system-debugserver-cfw-install"],
            [FirmwareRestoreImagePatchSet.launchdJetsam, "system-launchd-boot-jetsam_panic_guard_bypass"],
            ["kernel-cfw-task_for_pid"],
            ["kernel-boot-task_conversion_eval"],
            ["kernel-cfw-debugger"],
            ["kernel-boot-port_to_map"],
            ["kernel-boot-proc_security_policy"],
            ["kernel-boot-cred_label_update_execve"],
            ["kernel-boot-hook_cred_label"],
            ["txm-boot-developer_mode_bypass"],
            ["txm-cfw-debugger_entitlement"],
            ["txm-boot-sel42_29"],
            ["txm-cfw-get_task_allow"],
        ],
    )

    /// The features the bundle offers.
    public static let features: [FirmwarePatchFeature] = [userspaceDebugging]
}