Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Integrate former EXP patches into public JB firmware flow

Lakr228326de0424
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 7719134a..1ece40c3 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -6,9 +6,27 @@
> repository. The native Swift JB install retains the base system patches,
> launchd jetsam guard, debugserver entitlement edit, iOS 27 Campo entitlement
> edit, GPU driver, mandatory vphoned, and the small vphone launchd hook described
-> below. Old variant rows are research history,
+> below. The JB firmware pipeline now also runs the former EXP kernel OID and
+> DeviceTree identity/camera patches. The JB system installer runs the former
+> EXP DSC hypervisor and camera patches, watchdogd patch, and post-restore
+> Preboot DeviceTree rewrite. `SPOOF_BUILD` remains opt-in and updates the
+> rootfs and installed SystemOS SystemVersion.plist copies, plus the Preboot
+> Cryptex copy when present. These are install-time integrations;
+> successful patch dry-runs do not establish guest boot or Camera.app behavior.
+> Old variant rows are research history,
> not available install modes.
+> **Integration check (2026-09-25):** A clean `/tmp` restore tree assembled
+> from cloudOS 26.4 (23E5207q) and iPhone17,3 iOS 27.0 (24A435) completed
+> the public `fw patch` command with 191 records: 7 former EXP kernel records
+> and 23 DeviceTree records. The unchanged BuildManifest retained its input
+> SHA-256. Against the existing iOS 27 VM's read-only system image,
+> `patch-hv-vmm-dsc --dry-run` found 29 writable cstrings and 15 blacklist
+> entries; `patch-camera-dsc --dry-run` found six methods. A copy of that
+> VM's watchdogd was patched, passed `codesign -v`, and was unchanged on a
+> second run. The Preboot DT rewrite succeeded on a copy and was likewise
+> unchanged on a second run. The original VM disk was not modified or booted.
+
> **Current launchd hook (2026-09-25; isolated VM verification):**
> `cfw install` now places `launchdhook-vphone.dylib` and a diagnostic
> `SystemHook-vphone.dylib` in `/usr/lib`, links `/vh` to the launchd hook,
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/BinaryBuffer.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/BinaryBuffer.swift
index bb79236d..efea54c6 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/BinaryBuffer.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Binary/BinaryBuffer.swift
@@ -9,7 +9,10 @@ extension Data {
precondition(offset >= 0 && offset + MemoryLayout<T>.size <= count)
var value: T = .zero
_ = Swift.withUnsafeMutableBytes(of: &value) { dst in
- copyBytes(to: dst, from: offset ..< offset + MemoryLayout<T>.size)
+ copyBytes(
+ to: dst,
+ from: startIndex + offset ..< startIndex + offset + MemoryLayout<T>.size,
+ )
}
return T(littleEndian: value)
}
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift
index f58f42fe..28015b5b 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/DeviceTree/DeviceTreePatcher.swift
@@ -16,9 +16,8 @@ public final class DeviceTreePatcher: Patcher {
public let verbose: Bool
/// Whether to apply the 8 identity-rewrite property patches (Tier 1b + 1c)
- /// that flip device identity towards iPhone17,3 / D47AP. Enabled only for
- /// the `.exp` variant; all other variants run the base 4 patches only so
- /// they remain unaffected by the experimental identity rewrites.
+ /// that flip device identity towards iPhone17,3 / D47AP. Enabled for
+ /// public JB and the historical internal EXP variant.
let includeIdentityPatches: Bool
let buffer: BinaryBuffer
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/KernelExperimentalPatcher.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/KernelExperimentalPatcher.swift
index fb646201..829ad874 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/KernelExperimentalPatcher.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Kernel/KernelExperimentalPatcher.swift
@@ -1,7 +1,7 @@
// KernelExperimentalPatcher.swift — Experimental kernel patcher orchestrator.
//
-// Runs after KernelPatcher + KernelJailbreakPatcher for the `.exp` firmware variant
-// only. JB and other variants are NOT affected by patches owned here.
+// Runs after KernelPatcher + KernelJailbreakPatcher for public JB firmware.
+// The internal historical `.exp` variant uses the same patcher.
//
// Current contents:
// - patchHvVmmRename (Part A + Part B): rename the kern.hv_vmm_present
@@ -26,7 +26,7 @@ public final class KernelExperimentalPatcher: KernelJailbreakPatcherBase, Patche
buildSymbolTable()
findPanic()
- // Experimental patches (EXP variant only)
+ // Former EXP patch, now part of the public JB firmware pipeline.
patchHvVmmRename()
return patches
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipeline.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipeline.swift
index ef0af443..fc6ca70b 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipeline.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipeline.swift
@@ -8,9 +8,9 @@
// .regular — base patchers only
// .dev — TXMDevPatcher instead of TXMPatcher
// .jb — TXMDevPatcher + IBootJailbreakPatcher (iBSS) + KernelJailbreakPatcher
-// .exp — JB + experimental: KernelExperimentalPatcher (hv_vmm rename) +
-// DeviceTreePatcher identity properties (D47AP/iPhone17,3).
-// Other variants are NOT affected by experimental patches.
+// + former EXP kernel and DeviceTree patches.
+// .exp — historical internal variant, currently equivalent to JB for
+// the boot-chain patcher catalogue. Only JB is public.
//
// The component catalogue lives in FirmwarePipelineComponents.swift and the
// Restore-directory/firmware-file lookup in FirmwarePipelineDiscovery.swift.
@@ -150,6 +150,10 @@ public final class FirmwarePipeline {
var allRecords: [PatchRecord] = []
for component in components {
+ guard !component.patcherFactories.isEmpty else {
+ log(" [=] \(component.name): no patches for \(variant.rawValue)")
+ continue
+ }
let baseDir = component.inRestoreDir ? restoreDir : vmDirectory
let fileURL = try findFile(in: baseDir, patterns: component.searchPatterns, label: component.name)
@@ -174,7 +178,7 @@ public final class FirmwarePipeline {
}
log("\n\(String(repeating: "=", count: 60))")
- log(" All \(components.count) components patched successfully! (\(allRecords.count) total patches)")
+ log(" All \(components.count) components processed successfully! (\(allRecords.count) total patches)")
log(String(repeating: "=", count: 60))
return allRecords
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift
index 65850f29..18bc2b19 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipelineComponents.swift
@@ -147,8 +147,8 @@ extension FirmwarePipeline {
}(),
))
- // 6. Kernel — JB variant runs base kernel patches first, then JB extensions.
- // EXP variant runs base + JB + experimental extensions (hv_vmm rename).
+ // 6. Kernel — the public JB firmware includes the former EXP
+ // hv_vmm rename after the base and jailbreak patches.
components.append(ComponentDescriptor(
name: "kernelcache",
inRestoreDir: true,
@@ -176,6 +176,9 @@ extension FirmwarePipeline {
p.applyFrida = applyFrida
return p
},
+ { data, verbose in
+ KernelExperimentalPatcher(data: data, verbose: verbose)
+ },
]
case .exp:
[
@@ -196,10 +199,9 @@ extension FirmwarePipeline {
}(),
))
- // 7. DeviceTree — base property patches for every variant. EXP additionally
- // applies the 8 identity-rewrite properties (Tier 1b + 1c) that flip the
- // device's userland-visible identity toward D47AP / iPhone17,3.
- let dtIncludeIdentity = variant == .exp
+ // 7. DeviceTree — JB includes the former EXP identity and camera
+ // properties so the guest presents a consistent iPhone17,3 identity.
+ let dtIncludeIdentity = variant == .jb || variant == .exp
components.append(ComponentDescriptor(
name: "DeviceTree",
inRestoreDir: true,
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/FirmwarePatcherTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/FirmwarePatcherTests.swift
index c89a6b28..ddbb5b60 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/FirmwarePatcherTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/Core/FirmwarePatcherTests.swift
@@ -307,6 +307,13 @@ struct ARM64InstTests {
}
struct BinaryBufferTests {
+ @Test func `loads little endian values from sliced data`() {
+ let source = Data([0xFF, 0x78, 0x56, 0x34, 0x12, 0xEE])
+ let slice = source[1 ..< 5]
+ #expect(slice.startIndex == 1)
+ #expect(slice.loadLE(UInt32.self, at: 0) == 0x1234_5678)
+ }
+
@Test func `read write U 32`() {
let data = Data(repeating: 0, count: 16)
let buf = BinaryBuffer(data)
@@ -515,6 +522,26 @@ struct IM4PPayloadParityTests {
}
struct FirmwarePipelineTests {
+ @Test func `public JB includes former EXP kernel and device tree patchers`() throws {
+ let root = URL(fileURLWithPath: NSTemporaryDirectory())
+ let pipeline = FirmwarePipeline(vmDirectory: root, variant: .jb, verbose: false)
+ let components = pipeline.buildComponentList(
+ restoreDir: root,
+ iosBaseIs18: false,
+ iosBaseIs27: true,
+ cloudOSIsFridaCapable: true,
+ )
+ let kernel = try #require(components.first { $0.name == "kernelcache" })
+ #expect(kernel.patcherFactories.count == 3)
+ #expect(kernel.patcherFactories[2](Data(), false) is KernelExperimentalPatcher)
+
+ let deviceTree = try #require(components.first { $0.name == "DeviceTree" })
+ let patcher = try #require(deviceTree.patcherFactories.first?(Data(), false) as? DeviceTreePatcher)
+ #expect(patcher.includeIdentityPatches)
+ #expect(components.first { $0.name == "Filesystem" }?.patcherFactories.isEmpty == true)
+ #expect(components.first { $0.name == "Manifest" }?.patcherFactories.isEmpty == true)
+ }
+
@Test func `find file supports glob patterns`() throws {
let fm = FileManager.default
let tempDir = URL(fileURLWithPath: NSTemporaryDirectory())
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index db5b24ea..ba233bae 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -20,6 +20,13 @@ struct VPhoneCustomFirmwareInstaller {
.default
}
+ private var spoofBuild: String? {
+ guard let build = ProcessInfo.processInfo.environment["SPOOF_BUILD"], !build.isEmpty else {
+ return nil
+ }
+ return build
+ }
+
static func elevate(
bundle: URL,
resources: VPhoneResources,
@@ -137,6 +144,7 @@ struct VPhoneCustomFirmwareInstaller {
try tool("/sbin/mount_apfs", ["-o", "rw", "/dev/\(container)s3", data.path])
print("[*] JB system install: \(bundle.lastPathComponent)")
try installMounted(system: system, data: data, work: work)
+ try patchPreboot(container: container, work: work)
_ = try tool("/sbin/umount", [data.path])
dataMounted = false
_ = try tool("/sbin/umount", [system.path])
@@ -171,6 +179,18 @@ struct VPhoneCustomFirmwareInstaller {
} else if forceDyldSharedCacheMaxSlide {
try patch("patch-dsc-maxslide", [dsc.path, "--force"])
}
+ // These former EXP patches pair with the kernel OID rename and the
+ // camera DeviceTree additions in the public JB firmware pipeline.
+ try patch("patch-hv-vmm-dsc", [dsc.path])
+ try patch("patch-camera-dsc", [dsc.path, dsc.appendingPathComponent("dyld_shared_cache_arm64e").path])
+ if let build = spoofBuild {
+ for path in [
+ "System/Library/CoreServices/SystemVersion.plist",
+ "System/Cryptexes/OS/System/Library/CoreServices/SystemVersion.plist",
+ ] {
+ try patch("patch-build-version", [system.appendingPathComponent(path).path, build])
+ }
+ }
try patchMachO(
system: system,
work: work,
@@ -232,6 +252,7 @@ struct VPhoneCustomFirmwareInstaller {
path: "usr/libexec/mobileactivationd",
verb: "patch-mobileactivationd",
)
+ try patchWatchdog(system: system, work: work)
try installVphoned(system: system, work: work)
try installLaunchHook(system: system)
try patchMachO(
@@ -381,6 +402,59 @@ struct VPhoneCustomFirmwareInstaller {
}
}
+ private func patchWatchdog(system: URL, work: URL) throws {
+ let target = system.appendingPathComponent("usr/libexec/watchdogd")
+ let backup = target.appendingPathExtension("bak")
+ if !fm.fileExists(atPath: backup.path) {
+ try fm.copyItem(at: target, to: backup)
+ }
+ let staged = work.appendingPathComponent("watchdogd")
+ if fm.fileExists(atPath: staged.path) {
+ try fm.removeItem(at: staged)
+ }
+ try fm.copyItem(at: backup, to: staged)
+ // The patcher re-attests watchdogd's original CodeDirectory pages.
+ // Re-signing it would change Apple's identifier and break launchd's
+ // boot-task identity check.
+ try patch("patch-watchdogd", [staged.path])
+ try replace(staged, at: target, mode: 0o755)
+ }
+
+ private func patchPreboot(container: String, work: URL) throws {
+ let output = try tool("/usr/sbin/diskutil", ["apfs", "list", "-plist", container], quiet: true)
+ guard
+ let plist = try PropertyListSerialization.propertyList(from: Data(output.utf8), format: nil)
+ as? [String: Any],
+ let containers = plist["Containers"] as? [[String: Any]],
+ let volumes = containers.first(where: { $0["ContainerReference"] as? String == container })?["Volumes"]
+ as? [[String: Any]],
+ let preboot = volumes.first(where: { ($0["Roles"] as? [String])?.contains("Preboot") == true }),
+ let device = preboot["DeviceIdentifier"] as? String
+ else {
+ throw ValidationError("Could not locate the VM's Preboot APFS volume")
+ }
+ let mount = work.appendingPathComponent("preboot")
+ try fm.createDirectory(at: mount, withIntermediateDirectories: false)
+ try tool("/sbin/mount_apfs", ["-o", "rw", "/dev/\(device)", mount.path])
+ defer { try? tool("/sbin/umount", [mount.path], quiet: true) }
+ let roots = try fm.contentsOfDirectory(at: mount, includingPropertiesForKeys: [.isDirectoryKey])
+ let candidates = roots.map {
+ $0.appendingPathComponent("usr/standalone/firmware/devicetree.img4")
+ }.filter { fm.fileExists(atPath: $0.path) }
+ guard candidates.count == 1, let deviceTree = candidates.first else {
+ throw ValidationError("Expected one restored devicetree.img4 in Preboot, found \(candidates.count)")
+ }
+ try patch("patch-post-restore-dt", [deviceTree.path])
+ if let build = spoofBuild {
+ let version = mount.appendingPathComponent(
+ "Cryptexes/OS/System/Library/CoreServices/SystemVersion.plist",
+ )
+ if fm.fileExists(atPath: version.path) {
+ try patch("patch-build-version", [version.path, build])
+ }
+ }
+ }
+
private func patchMachO(
system: URL,
work: URL,