Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
9.9 KB
Raw Blame
// KernelCustomFirmwarePatcher.swift — CFW kernel patcher orchestrator.
//
// Historical note: derived from the legacy Python firmware patcher during the Swift migration.

import Foundation
import VPhonePatchKit

/// CFW kernel patcher across 3 groups. Variant- and feature-gated methods can
/// change the emitted record count; iOS-27-only patches are gated by `applyIOS27`
/// and Frida Stalker relaxations by `applyFrida`, which the pipeline sets from the
/// plan — the `com.vphone.patchset.kernel.frida` patches, off in `standard`.
///
/// Group A: Core gate-bypass methods
/// Group B: Pattern/string anchored methods
/// Group C: Shellcode/trampoline heavy methods
public final class KernelCustomFirmwarePatcher: KernelCustomFirmwarePatcherBase, BufferedPatcher {
    public let component = "kernelcache_cfw"

    /// Gates the iOS-27-only kernel patches. These target an iOS-27 userland running
    /// on the 26.4 kernel; on a 26.x base they are unnecessary and some are actively
    /// harmful (e.g. the IOMFB SwapEnd size gate would reject 26.x's native 0x588 swap
    /// struct → dead display, the 26.5 regression). The pipeline sets this from the
    /// iPhone base ProductVersion (false for 18.x/26.x → byte-identical to pre-branch);
    /// standalone patch-component defaults it true so the dev tool exercises the full
    /// set (override with --target-os).
    public var applyIOS27 = false

    /// The AppleSEPKeyStore keybag-unlock count-5 acceptance. iOS 26.6 is where
    /// Apple's external method began sending inputScalarCount == 5 (26.5 and
    /// earlier send 4), so a 26.6-or-newer userland needs it on the 26.4 kernel —
    /// not only a 27 base. The pipeline sets this from the iPhone base; the patch
    /// anchor self-guards on a kernel that already accepts 5, so it no-ops where
    /// unneeded. False here so a patcher built directly preserves the reference corpus.
    public var applyAksUnlockBag5 = false

    /// Opt-in Frida Stalker kernel relaxations. Set from the plan: `standard` blocks
    /// both, `experimental` and a per-VM checkmark turn them on, and their own
    /// cloudOS 26.4+ gate then decides whether they land. Baseline CFW/EXP firmware is
    /// byte-identical when false.
    public var applyFrida = false

    /// ProMotion, the 120 Hz display timing. Set from the plan, and `standard`
    /// turns it on; a VM that blocks it keeps the host's 60 Hz mode. False here so
    /// a patcher built directly writes what the reference records were taken from.
    public var applyProMotion = false

    /// Opt-in plain-arm64 tvOS shared-cache compatibility; off by default.
    public var applyTVTPROPagers = false

    /// On a base older than 27: a narrow allowlist at the same sandbox gate, so a
    /// process outside an app sandbox can open the paravirtual GPU, video decoder,
    /// Neural Engine and IOSurface scaler user clients and nothing else. Set from
    /// the plan, and `standard` turns it on. False here so a patcher built directly
    /// writes what the reference records were taken from.
    public var applyParavirtUserClients = false

    /// Paravirtual GPU binary version 252 (Task3). Set from the plan; `standard`
    /// enables it. False here so direct patchers preserve the reference corpus.
    public var applyParavirtTask3 = false

    /// The paravirtual GPU's OpenGL ES renderer. Set from the plan; `standard`
    /// enables it. False here so direct patchers preserve the reference corpus.
    public var applyParavirtGLES = false

    public func findAll() throws -> [PatchRecord] {
        parseMachO()
        buildADRPIndex()
        buildBLIndex()
        buildSymbolTable()
        findPanic()

        if applyTVTPROPagers {
            guard patchTVTPROPagers() else {
                throw NSError(domain: "FirmwarePatcher.TVTPROPagers", code: 1, userInfo: [NSLocalizedDescriptionKey: "Cannot validate sprr_tpro_pagers tunable; kernel unchanged by this operation"])
            }
        }

        // Group A
        patchAmfiCdhashInTrustcache()
        patchTaskConversionEvalInternal()
        patchSandboxHooksExtended()
        patchIoucFailedMacf()

        // iOS-27-only (gated — a 26.x base skips these entirely). Both target a 27
        // userland on the 26.4 kernel:
        //  - IOUC sandbox gate bypass: the IOKit user-client open path's Sandbox gate
        //    (separate from the MACF gate above) spuriously denies backboardd its
        //    IOMFB/IOSurface/HID user clients → no present + nil main display →
        //    SpringBoard crash-loop. Mirrors the MACF gate.
        //  - DiskImages2 DDI ABI (kernel driver v9 vs iOS-27 controller/daemon v11) +
        //    RegisterNotificationPort off-by-one, so the personalized DDI attaches
        //    (/System/Developer auto-mount). Pairs with the sandbox ops[124] allow
        //    and the diskimagesiod isMountComplete→YES userland patch (cfw_install).
        //  - Shared region size: the arm64 region widens from 6 GiB to 7 GiB so a
        //    27 cache (0x185804000 on 27.0.1 iPhone18,x) maps at all. A 26.x base's
        //    own cache fits the stock region, so the kernel is left stock there.
        if applyIOS27 {
            patchIoucFailedSandbox()
            patchDiskImages2ClientAbi()
            patchSharedRegionSize()
            if gate.isEnabled("kernel-boot-arm64e_x1"), !patchArm64eX1Admission() {
                throw PatcherError.invalidFormat("cannot validate required ARM64E_X1 kernel admission")
            }
            try patchCSSC()
        } else if applyParavirtUserClients {
            patchParavirtUserClientsNarrow()
        }

        // AppleSEPKeyStore keybag unlock: accept the 5 scalars an iOS 26.6-or-newer
        // userland sends (26.5 and earlier send 4). Gated on the base, not on
        // applyIOS27, so a 26.6/26.6.1 base on the 26.4 kernel gets it too; the
        // anchor self-guards on a kernel that already accepts 5.
        if applyAksUnlockBag5 {
            patchAksUnlockBagCount5()
        }

        // Group B
        patchPostValidationAdditional()
        patchProcSecurityPolicy()
        patchProcPidinfo()
        patchConvertPortToMap()
        patchBsdInitAuth()
        patchDounmount()
        patchIoSecureBsdRoot()
        patchLoadDylinker()
        patchMacMount()
        patchNvramVerifyPermission()
        patchSharedRegionMap()
        patchSpawnValidatePersona()
        patchTaskForPid()
        patchThidShouldCrash()
        patchVmFaultEnterPrepare()
        patchVmMapProtect()

        // Opt-in Frida support, from the kernel.frida patch set: existing-thread
        // follow (thread_set_state), repeated VM_PROT_COPY overwrite
        // (vm_map_delete), spawn (TPRO), syscall-filtered targets, and fork
        // after instrumentation (the child of an entitled parent keeps its
        // permission to run rewritten code). The gate writes each only when its
        // own identifier is selected.
        if applyFrida {
            patchThreadSetStateEntitlementFlag()
            patchVmMapDeleteImmutableCode()
            patchTproOff()
            patchSyscallFilterOff()
            patchForkInheritInvalidCode()
        }

        // The paravirtual display advertises 120 Hz instead of the host's
        // fixed 60 Hz mode, unless the VM blocked it.
        if applyProMotion {
            patchParavirtDisplayRefreshRate()
        }

        // Negotiate Task3 and identify the executable before registration.
        if applyParavirtTask3 {
            guard patchParavirtTask3Version() else {
                throw NSError(domain: "FirmwarePatcher.ParavirtTask3", code: 1, userInfo: [
                    NSLocalizedDescriptionKey: "Cannot resolve the complete Task3 shader-cache patch; kernel was not installed",
                ])
            }
        }

        // Name the GLES renderer in the paravirtual GPU's personality.
        if applyParavirtGLES {
            patchParavirtGLESRenderer()
        }

        // Group C
        patchCredLabelUpdateExecve()
        patchHookCredLabelUpdateExecve()
        patchKcall10()
        patchSyscallmaskApplyToProc()

        // iOS-27-only (gated — a 26.x base skips these entirely). All target a 27
        // userland on the 26.4 kernel and are unnecessary or actively harmful on 26.x:
        //  - exec ip_mac_return SECURITY_POLICY kill bypass: AMFI's exec hooks reject a
        //    userland newer than the kernel (27 binaries' validation category) →
        //    ip_mac_return != 0 → core daemons die at exec → boot deadlock. 26.x
        //    binaries pass (ip_mac_return == 0), so it is not needed there.
        //  - container-manager exec-upcall force-success: iOS 27 deleted the kernel-side
        //    containermanagerd upcall, so on the 26.4 kernel it fails for every 27 app →
        //    autoboxed into temporary-sandbox → Campo/intelligencetasksd/feedbackd
        //    crash-loop. On 26.x the upcall succeeds, so it is not needed.
        //  - IOMFB SwapEnd size gates: 27's force-kern present (cfw_patch_iomfb_force_kern)
        //    sends a 0x6e0 SwapEnd struct; the 26.4 userclient exact-checks 0x588 in two
        //    places, so both gates are relaxed to accept 0x6e0. HARMFUL on 26.x — it
        //    sends the native 0x588, which the retargeted handler gate would then reject
        //    → every framebuffer swap fails → dead display (the 26.5 regression).
        if applyIOS27 {
            patchExecSecurityPolicyKill()
            patchContainerManagerUpcall()
            patchIomfbSwapEndVariableSize() // dispatch checkStructureInputSize → variable
            patchIomfbSwapEndHandlerSize() // handler cmp w2,#0x588 → 0x6e0
            patchFpfsScopedVnodeOpen() // ops[267] → FileProvider-scoped trampoline (fpfs respring fix)
        }

        return patches
    }

    public func apply() throws -> Int {
        // `emit()` already wrote every record through to `buffer.data`.
        let records = try (patches.isEmpty ? findAll() : patches)
        return records.count
    }
}