Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Install the RootHide bootstrap on Apple TV, with its environment hooks

gitefcce966f2ff
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 4b08b276..9a37c0f5 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -1,5 +1,24 @@
# Patch Comparison: Regular / Development / Jailbreak / Experimental
+> **Apple TV RootHide bootstrap and environment hooks (2026-10-26).** No new
+> declaration or instruction patch. An arm64e Apple TV now admits
+> `system-launchdaemons-boot-environment` and
+> `system-launchd-boot-jetsam_panic_guard_bypass`
+> (`FirmwareGuestPatchResolution.tvArm64eGuestPatches`); both stay blocked in
+> `tvos` and `tvos-4k` and on the plain-arm64 HD. On TV the environment is
+> `launchdhook-vphone.dylib` and `SystemHook-vphone.dylib` alone, their
+> `LC_BUILD_VERSION` rewritten to tvOS (`MachOBuildPlatform`) and re-signed at
+> install, with `/vh`; turning it off removes them. The launchd patch is
+> unchanged: on `tv4k`'s tvOS 26.6 arm64e launchd it rewrote `tbnz w0, #0,
+> 0xdac4` at `0xDA68` to `b 0xdac4` (anchor `jetsam property category`) and
+> `/vh` went in as `LC_LOAD_WEAK_DYLIB`. With both on, `tv4k` booted to the
+> home screen with SystemHook in every process and the vphoned RootHide root
+> as `VPHONE_JB_ROOT`; with both off again launchd came back from its backup
+> and the libraries and `/vh` were removed. vphoned installs Irisin's
+> `appletvos-arm64e` package as the RootHide bootstrap on any tvOS guest and
+> refuses rootless there; both were validated live on `tv4k`. See
+> [tvOS support](Firmware/tvos_support.md#roothide-bootstrap).
+
> **The iPhone17,3 presents its board (2026-10-25).**
> `VPhoneGuestDevice.presentsBoard` no longer excludes the iPhone17,3; only the
> XS Max keeps the shared tree. An iPhone17,3 guest now gets the separate
diff --git a/Research/Firmware/tvos_support.md b/Research/Firmware/tvos_support.md
index ae9cb439..f3668caf 100644
--- a/Research/Firmware/tvos_support.md
+++ b/Research/Firmware/tvos_support.md
@@ -405,8 +405,9 @@ Its launchd job goes into `/System/Library/xpc/launchd.plist` as on iOS. The
plain-arm64 loader (`0xB00` in 23L5208m), and the console then shows `Using
unsecure cache: /System/Library/xpc/launchd.plist`. Both are now admitted for
TV (`FirmwareGuestPatchResolution.tvSupportedGuestPatches`). The environment
-hooks (`system-launchdaemons-boot-environment`) stay blocked; they have no TV
-port.
+hooks (`system-launchdaemons-boot-environment`) stay blocked on the plain-arm64
+HD; an arm64e TV admits a two-library port of them, see "RootHide bootstrap"
+below.
Verified on 23L5208m and 23L773: `vm wait` returns, `device.info` reports
`own_name` "Apple TV", screenshots and `apps.launch` work, and consumer-page
@@ -427,6 +428,94 @@ that way on TV guests all along. Compiling the daemon against the tvOS SDK
would fail on them; do not try to, and do not guard the session's code for
tvOS availability.
+## RootHide bootstrap
+
+Irisin 5.0.1 ships a third package, `appletvos-arm64e`, beside iOS's two:
+`irisind`, `irisin-install` and the daemon's plist, tvOS 17 binaries (plain
+arm64, platform TVOS), and no app. Irisin serves an Apple TV only as RootHide
+and refuses any other root (its `Documentation/AppleTV.md`). OwnGoal's
+repository carries no tvOS bootstrap package yet, so on TV the bootstrap is
+the RootHide root, vphoned's base in it, and Irisin's privileged layer.
+
+`bootstrap.install` decides the package by the platform dyld runs vphoned as
+(`GuestBootstrapPlatform`: the main image's `LC_BUILD_VERSION`, TVOS for
+`vphoned-tvos`), not by product type, so the HD and the 4K take the same
+package. On tvOS `rootless` is refused before a root is created. The
+package's missing app is allowed only for `appletvos-*`; vphoned then creates
+no data directory, registers nothing and loads the daemon, which is what the
+package's own postinst does. Every root also gets an empty `Applications`,
+which icli's refresh needs to exist. The Apps menu offers only roothide on
+an Apple TV.
+
+Validation, 2026-10-26, `tv4k` on jp-01 (AppleTV14,1, tvOS 26.6 arm64e OTA
+userland: `/sbin/launchd` cpusubtype `0x80000002`, `dyld_shared_cache_arm64e`),
+the new `vphoned-tvos` delivered by the host's update path:
+
+- `{"layout":"rootless"}` answers `Irisin serves only a roothide bootstrap on
+ tvOS`; no `/var/jb` appears.
+- `{"layout":"roothide"}` downloads `wiki.qaq.irisin_5.0.1_appletvos-arm64e.deb`
+ (digest checked) and returns `architecture` `appletvos-arm64e`,
+ `registration` null, `firmware_version` 26.6.0, `irisind` loaded, started and
+ running. The base created `/tmp`, `/var`, `/var/root`, `/etc`, `/var/tmp`,
+ `/dev`, `/rootfs` and the three account files from tvOS's own; `pwd.db`
+ waits for a `pwd_mkdb` no tvOS package provides yet. The `.jbroot` loader
+ links are in the root, `usr/lib` and `usr/libexec`.
+- Irisin's tvOS test client (`irisin-external-probe`, root-owned in the
+ root's `usr/libexec`, from Irisin's Apple TV test kit) gets `serviceInfo`
+ with `installRoot` the vphoned root, installs and removes an `all` package
+ (dpkg status lists it beside `firmware`, then only `firmware`), and is
+ refused an `iphoneos-arm64e` package.
+- After `system.reboot`, `bootstrap.inspect` reports the roothide root,
+ vphoned's startup reloads `wiki.qaq.irisind`, and the daemon starts on demand
+ for the client.
+
+### Environment hooks
+
+The iOS environment inserts SystemHook into every process and five more
+libraries into named iOS processes (SpringBoard, Settings, installd,
+lockdownd, cryptexd, configd). An Apple TV takes
+`VPhoneGuestEnvironment.tvLibraries` alone, `launchdhook-vphone.dylib` and
+`SystemHook-vphone.dylib`: the RootHide loader links and `VPHONE_JB_ROOT` at
+each spawn, jetsam limits for bootstrap programs, and ElleKit's TweakLoader
+when a bootstrap provides one. The spawn hooks insert a library only when it
+is installed, so the others are simply absent. Both libraries are built for
+iOS; `cfw install` and `cfw update-environment` mark them tvOS with
+`MachOBuildPlatform` and sign them again, as the HomePod virtio sound driver
+is. They are always written with `/vh` on TV, and removed with `/vh` when the
+patch is off. The hook is loaded by `/vh`, the load command
+`system-launchd-boot-jetsam_panic_guard_bypass` adds to launchd, so both
+patches are admitted together, for an arm64e TV only: both libraries are
+arm64e. Neither is on in `tvos-4k`; turn them on with `fw set-patches <vm>
+--allow system-launchdaemons-boot-environment --allow
+system-launchd-boot-jetsam_panic_guard_bypass`, then `cfw update-environment`.
+
+Offline, on a copy of `tv4k`'s `/sbin/launchd` (586496 bytes): the jetsam
+patcher found `jetsam property category`, function at `0xDA34`, and rewrote
+`tbnz w0, #0, 0xdac4` at `0xDA68` to `b 0xdac4`; `inject-dylib` added
+`LC_LOAD_WEAK_DYLIB /vh`.
+
+Live, the same day on `tv4k`, with the RootHide bootstrap above installed:
+`fw set-patches tv4k --allow …` for both, then `cfw update-environment`
+logged `Environment hooks retargeted to tvOS`, the jetsam patch at `0xDA68`
+and `/vh`. The guest booted to vphoned in 20 seconds and to the home screen.
+The launchd hook inserted SystemHook into xpcproxy (203 spawns by then),
+PineBoard, PosterBoard and the TV apps; SystemHook's log names
+`root=/private/var/containers/Bundle/Application/.jbroot-000114514191980C` in
+every process, so the hook found the vphoned root. The test client's request
+started `irisind` through xpcproxy (`label=wiki.qaq.irisind`); the hook
+checked its loader link (`loader_link_errno=0`) and, its plist setting
+`DISABLE_TWEAKS`, logged `inserted-tweaks-disabled`. `serviceInfo` answered as
+before; PineBoard kept its boot pid; the only reports were `bug_type` 313
+SiriSearchFeedback entries, which the guest also wrote before the hooks.
+There is no `bootstrap-root` line in the hook's log: its first spawns come
+before the data volume where the log lives is mounted.
+
+Turning both off (`fw set-patches tv4k`, `cfw update-environment`) logged
+`removed the TV environment hooks` and `restored sbin/launchd from backup`;
+the guest booted in 20 seconds with neither library nor `/vh`, the bootstrap
+still installed. Turning them on again restored the hooked boot. Snapshots
+`before-tvroothide` (no bootstrap) and `bootstrap-no-hooks` are on the VM.
+
## TV button, Home and Control Center
A USB keyboard cannot press the TV button: no keyboard-page key maps to it.
diff --git a/Research/Guest/roothide_bootstrap_base.md b/Research/Guest/roothide_bootstrap_base.md
index 15ca5c63..6fde5965 100644
--- a/Research/Guest/roothide_bootstrap_base.md
+++ b/Research/Guest/roothide_bootstrap_base.md
@@ -92,6 +92,10 @@ Rules:
link and root SSH worked with public-key and password authentication. A
fresh restore with the package's unmodified `sshd_config` has not been
checked yet. vphoned never edits `sshd_config`, the package's conffile.
+- **Apple TV.** The base is the same on tvOS, seeded from tvOS's own account
+ files, but no tvOS package provides `pwd_mkdb` or `ssh-keygen` yet, so the
+ databases and host keys stay deferred and vphoned logs that at every start.
+ See `Research/Firmware/tvos_support.md` ("RootHide bootstrap").
- **Alternatives links** such as `/usr/bin/pager` only exist when maintainer
scripts ran. Check whether Irisin's Bootstrap Install creates them on a fresh
vphone; if it does not, that is an Irisin bug.
diff --git a/Research/vphoned_http_api.md b/Research/vphoned_http_api.md
index bb6e7554..193c7092 100644
--- a/Research/vphoned_http_api.md
+++ b/Research/vphoned_http_api.md
@@ -125,7 +125,16 @@ menu item retains the verified latest-release download.
Rootless uses `/var/jb`. RootHide reuses the sole valid `.jbroot-<16 hex>` under
`/var/containers/Bundle/Application`, or creates
`.jbroot-000114514191980C` when none exists. The selected stem is zero padded
-and its final byte carries RootHide's XOR checksum. Missing bootstrap directories are created.
+and its final byte carries RootHide's XOR checksum. Missing bootstrap directories are created,
+an empty `Applications` among them, which the package watcher's app refresh reads.
+A guest whose vphoned dyld runs as tvOS (`vphoned-tvos`: every Apple TV and
+HomePod guest) has one layout, `roothide`, and one package, Irisin's
+`appletvos-arm64e`; `rootless` is refused before anything is created
+(`GuestBootstrapPlatform`). That package carries no app, so vphoned checks its
+daemon, helper and plist, makes no data directory, registers nothing
+(`registration` and `app_path` are null) and loads the daemon as on iOS. The
+Apple TV HD's plain-arm64 userland takes the same package: Irisin's tvOS
+binaries are arm64.
It selects the matching architecture, verifies the release
asset's GitHub SHA-256 digest and Debian control fields, then uses IcliKit to
extract the `.deb` into a temporary directory. It copies the full payload
diff --git a/VPhoneDaemon/Daemon/Bootstrap/GuestBootstrapPlatform.swift b/VPhoneDaemon/Daemon/Bootstrap/GuestBootstrapPlatform.swift
new file mode 100644
index 00000000..e018bdaa
--- /dev/null
+++ b/VPhoneDaemon/Daemon/Bootstrap/GuestBootstrapPlatform.swift
@@ -0,0 +1,55 @@
+import Darwin
+import MachO
+
+// MARK: - Bootstrap platform
+
+/// Which Irisin package a guest takes.
+///
+/// Irisin publishes three: RootHide and rootless for iOS, and RootHide alone
+/// for Apple TV, whose daemon and helper are tvOS binaries that refuse any
+/// other bootstrap (Irisin's Documentation/AppleTV.md). A TV guest runs
+/// `vphoned-tvos`, the iOS build marked tvOS so that dyld loads the system's
+/// libraries into it. The same mark decides whether Irisin's tvOS binaries
+/// load, so it is what this reads rather than the product type: the Apple TV
+/// HD and the 4K take the same package.
+enum GuestBootstrapPlatform {
+ /// The package for a layout, or nil when this system has none for it.
+ static func packageArchitecture(layout: String, tvOS: Bool) -> String? {
+ switch (layout, tvOS) {
+ case ("roothide", false): "iphoneos-arm64e"
+ case ("rootless", false): "iphoneos-arm64"
+ case ("roothide", true): "appletvos-arm64e"
+ default: nil
+ }
+ }
+
+ /// The iOS packages carry the Irisin app. The Apple TV package has none
+ /// yet: its postinst loads the daemon and registers nothing. An app a
+ /// later one carries is checked and registered as iOS's is.
+ static func packageRequiresApp(architecture: String) -> Bool {
+ !architecture.hasPrefix("appletvos-")
+ }
+
+ /// Whether dyld runs this process as tvOS.
+ static let isTVOS = mainExecutablePlatform() == UInt32(PLATFORM_TVOS)
+
+ /// The platform the main executable's `LC_BUILD_VERSION` names.
+ static func mainExecutablePlatform() -> UInt32? {
+ guard let header = _dyld_get_image_header(0) else { return nil }
+ return buildPlatform(UnsafeRawPointer(header))
+ }
+
+ static func buildPlatform(_ image: UnsafeRawPointer) -> UInt32? {
+ let header = image.load(as: mach_header_64.self)
+ guard header.magic == UInt32(MH_MAGIC_64) else { return nil }
+ var command = image + MemoryLayout<mach_header_64>.size
+ for _ in 0 ..< header.ncmds {
+ let load = command.load(as: load_command.self)
+ if load.cmd == UInt32(LC_BUILD_VERSION) {
+ return command.load(as: build_version_command.self).platform
+ }
+ command += Int(load.cmdsize)
+ }
+ return nil
+ }
+}
diff --git a/VPhoneDaemon/Daemon/Bootstrap/GuestIrisinInstaller+Payload.swift b/VPhoneDaemon/Daemon/Bootstrap/GuestIrisinInstaller+Payload.swift
index 070d3f63..96f7b8b2 100644
--- a/VPhoneDaemon/Daemon/Bootstrap/GuestIrisinInstaller+Payload.swift
+++ b/VPhoneDaemon/Daemon/Bootstrap/GuestIrisinInstaller+Payload.swift
@@ -4,16 +4,21 @@ import Foundation
// MARK: - Payload
extension GuestIrisinInstaller {
+ /// `app` is nil for a package without one, which only the Apple TV
+ /// package may be (`GuestBootstrapPlatform.packageRequiresApp`).
static func validatePayload(
- app: URL, daemon: URL, helper: URL, plist: URL,
+ app: URL?, daemon: URL, helper: URL, plist: URL,
version: String, architecture: String, layout: String,
) throws {
- let info = NSDictionary(contentsOf: app.appendingPathComponent("Info.plist"))
- guard info?["CFBundleIdentifier"] as? String == "wiki.qaq.irisin",
- info?["CFBundleShortVersionString"] as? String == version,
- info?["IrisinCurrentArchitecture"] as? String == architecture,
- FileManager.default.isExecutableFile(atPath: app.appendingPathComponent("irisin").path),
- FileManager.default.isExecutableFile(atPath: daemon.path),
+ if let app {
+ let info = NSDictionary(contentsOf: app.appendingPathComponent("Info.plist"))
+ guard info?["CFBundleIdentifier"] as? String == "wiki.qaq.irisin",
+ info?["CFBundleShortVersionString"] as? String == version,
+ info?["IrisinCurrentArchitecture"] as? String == architecture,
+ FileManager.default.isExecutableFile(atPath: app.appendingPathComponent("irisin").path)
+ else { throw GuestAPIError.operationFailed("Irisin release payload is incomplete or has the wrong layout") }
+ }
+ guard FileManager.default.isExecutableFile(atPath: daemon.path),
FileManager.default.isExecutableFile(atPath: helper.path),
let properties = NSDictionary(contentsOf: plist) as? [String: Any],
properties["Label"] as? String == serviceLabel,
diff --git a/VPhoneDaemon/Daemon/Bootstrap/GuestIrisinInstaller.swift b/VPhoneDaemon/Daemon/Bootstrap/GuestIrisinInstaller.swift
index d21a582c..79ff238f 100644
--- a/VPhoneDaemon/Daemon/Bootstrap/GuestIrisinInstaller.swift
+++ b/VPhoneDaemon/Daemon/Bootstrap/GuestIrisinInstaller.swift
@@ -255,16 +255,23 @@ enum GuestIrisinInstaller {
if let detectedLayout, layout != detectedLayout {
throw GuestAPIError.invalidRequest("Requested layout does not match the guest bootstrap")
}
+ // Before anything is created, so a refused layout leaves no root behind.
+ guard let architecture = GuestBootstrapPlatform.packageArchitecture(
+ layout: layout, tvOS: GuestBootstrapPlatform.isTVOS,
+ ) else {
+ throw GuestAPIError.invalidRequest("Irisin serves only a roothide bootstrap on tvOS")
+ }
let root = try bootstrapRoot(layout: layout, detected: jailbreak["jbroot"] as? String)
- try FileManager.default.createDirectory(atPath: root, withIntermediateDirectories: true,
- attributes: [.posixPermissions: 0o755])
- try FileManager.default.createDirectory(atPath: root + "/usr/lib", withIntermediateDirectories: true,
- attributes: [.posixPermissions: 0o755])
+ // icli refuses to refresh an Applications directory that is not there,
+ // and the Apple TV package carries no app to create it.
+ for directory in [root, root + "/usr/lib", root + "/Applications"] {
+ try FileManager.default.createDirectory(atPath: directory, withIntermediateDirectories: true,
+ attributes: [.posixPermissions: 0o755])
+ }
guard isDirectory(root) else {
throw GuestAPIError.operationFailed("Jailbreak root is not a directory: \(root)")
}
- let architecture = layout == "roothide" ? "iphoneos-arm64e" : "iphoneos-arm64"
let work = FileManager.default.temporaryDirectory
.appendingPathComponent("vphoned-irisin-\(UUID().uuidString)", isDirectory: true)
try FileManager.default.createDirectory(at: work, withIntermediateDirectories: true)
@@ -310,13 +317,19 @@ enum GuestIrisinInstaller {
let daemon = payload.appendingPathComponent("usr/libexec/irisind")
let helper = payload.appendingPathComponent("usr/libexec/irisin-install")
let plist = payload.appendingPathComponent("Library/LaunchDaemons/\(serviceLabel).plist")
- try validatePayload(app: app, daemon: daemon, helper: helper, plist: plist,
+ let carriesApp = itemExists(app)
+ guard carriesApp || !GuestBootstrapPlatform.packageRequiresApp(architecture: architecture) else {
+ throw GuestAPIError.operationFailed("Irisin release payload is incomplete or has the wrong layout")
+ }
+ try validatePayload(app: carriesApp ? app : nil, daemon: daemon, helper: helper, plist: plist,
version: version, architecture: architecture, layout: layout)
if layout == "roothide" {
_ = try patchRootHideDaemon(at: plist.path, root: root)
}
- try prepareAppData(home: appHome(layout: layout, root: root))
+ if carriesApp {
+ try prepareAppData(home: appHome(layout: layout, root: root))
+ }
let rootURL = URL(fileURLWithPath: root, isDirectory: true)
let installedApp = rootURL.appendingPathComponent("Applications/irisin.app", isDirectory: true)
@@ -338,7 +351,7 @@ enum GuestIrisinInstaller {
if layout == "roothide" {
base = try repairRootHide(root: root)
}
- let registration = try registerApp(installedApp.path)
+ let registration: Any = carriesApp ? try registerApp(installedApp.path) : NSNull()
let loaded = try loadServices([installedPlist.path], load: true, override: false)
var started: [String: Any]?
var startWarning: String?
@@ -370,7 +383,7 @@ enum GuestIrisinInstaller {
"architecture": architecture,
"layout": layout,
"jbroot": root,
- "app_path": installedApp.path,
+ "app_path": carriesApp ? installedApp.path : NSNull(),
"registration": registration,
"service_load": loaded,
"service_status": status,
diff --git a/VPhoneDaemon/Tests/LogicTests.swift b/VPhoneDaemon/Tests/LogicTests.swift
index 5877f3cb..3ed916e5 100644
--- a/VPhoneDaemon/Tests/LogicTests.swift
+++ b/VPhoneDaemon/Tests/LogicTests.swift
@@ -1,12 +1,13 @@
import Foundation
+import MachO
// MARK: - Harness
/// Checks the guest-independent parts of vphoned on the Mac: the service
/// profile lists and bookkeeping, the first-boot settle verdict (data
-/// migration included), the device name rule and the pointer scroll
-/// parameters. `run-logic-tests.sh` builds
-/// this file with those sources.
+/// migration included), the device name rule, the pointer scroll
+/// parameters and the Irisin package a guest takes. `run-logic-tests.sh`
+/// builds this file with those sources.
nonisolated(unsafe) var failures = 0
nonisolated(unsafe) var checks = 0
@@ -36,6 +37,7 @@ enum LogicTests {
dataMigrationRecord()
deviceNameRule()
pointerScroll()
+ bootstrapPlatform()
print("\(checks) checks, \(failures) failures")
exit(failures == 0 ? 0 : 1)
}
@@ -397,4 +399,20 @@ enum LogicTests {
expect((try? GuestPointerScroll.buttons(["buttons": bad])) == nil, "buttons \(bad) is refused")
}
}
+
+ // MARK: - Bootstrap Platform
+
+ static func bootstrapPlatform() {
+ let architecture = GuestBootstrapPlatform.packageArchitecture
+ expectEqual(architecture("roothide", false), "iphoneos-arm64e")
+ expectEqual(architecture("rootless", false), "iphoneos-arm64")
+ expectEqual(architecture("roothide", true), "appletvos-arm64e", "an Apple TV takes Irisin's Apple TV package")
+ expectEqual(architecture("rootless", true), nil, "Irisin serves no rootless Apple TV")
+ expectEqual(architecture("rootful", false), nil)
+ expect(GuestBootstrapPlatform.packageRequiresApp(architecture: "iphoneos-arm64e"), "the iOS packages carry the app")
+ expect(GuestBootstrapPlatform.packageRequiresApp(architecture: "iphoneos-arm64"), "the iOS packages carry the app")
+ expect(!GuestBootstrapPlatform.packageRequiresApp(architecture: "appletvos-arm64e"), "the Apple TV package has none")
+ expectEqual(GuestBootstrapPlatform.mainExecutablePlatform(), UInt32(PLATFORM_MACOS), "this test runs as macOS")
+ expect(!GuestBootstrapPlatform.isTVOS, "the Mac is not tvOS")
+ }
}
diff --git a/VPhoneDaemon/Tests/run-logic-tests.sh b/VPhoneDaemon/Tests/run-logic-tests.sh
index 597bba25..028d7983 100755
--- a/VPhoneDaemon/Tests/run-logic-tests.sh
+++ b/VPhoneDaemon/Tests/run-logic-tests.sh
@@ -3,8 +3,8 @@ set -euo pipefail
# Builds the guest-independent vphoned sources with LogicTests.swift for the
# Mac and runs them: service profile lists and bookkeeping, the first-boot
-# settle verdict, the device name rule, the pointer scroll parameters. No
-# guest is needed.
+# settle verdict, the device name rule, the pointer scroll parameters, the
+# Irisin package a guest takes. No guest is needed.
daemon="${0:a:h:h}"
temporary="$(/usr/bin/mktemp -d "${TMPDIR:-/tmp}/vphone-logic-tests.XXXXXX")"
@@ -16,6 +16,7 @@ trap '/bin/rm -rf "$temporary"' EXIT
"$daemon/Daemon/GuestFirstBootSettle.swift" \
"$daemon/Daemon/GuestDeviceNameRule.swift" \
"$daemon/Daemon/GuestPointerScroll.swift" \
+ "$daemon/Daemon/Bootstrap/GuestBootstrapPlatform.swift" \
"$daemon/Tests/LogicTests.swift" \
-o "$temporary/logic-tests"
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift
index c78431f0..46de17c3 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/PatchSets/FirmwareGuestPatchResolution.swift
@@ -37,11 +37,16 @@ public enum FirmwareGuestPatchResolution {
/// An arm64e Apple TV (the 4K, from its OTA) also admits the paravirtual
/// GPU driver, which a plain-arm64 userland cannot load, the OTA userland
/// swap itself, and the iOS 27 shared-cache patches its tvOS 27 OTA meets.
+ /// It admits the environment's launchd hook and SystemHook too, marked
+ /// tvOS at install, with the launchd patch that loads the hook: both are
+ /// arm64e, so a plain-arm64 launchd could not load them.
public static let tvArm64eGuestPatches: Set<String> = Set([
"system-extensions-boot-gpu_bundle",
FirmwareGuestSystemPatchSet.tvOTAUserland,
FirmwareGuestSystemPatchSet.tvSetupDisplayLookup,
FirmwareGuestSystemPatchSet.tvLegacySetup,
+ "system-launchdaemons-boot-environment",
+ "system-launchd-boot-jetsam_panic_guard_bypass",
]).union(FirmwarePatchSetCatalog.tvOS27UserlandPatches)
public static func unvalidatedTVGuestPatches(enabled: Set<String>, arm64eUserland: Bool = false) -> [String] {
diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
index 6aa75303..410b8153 100644
--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcherTests/PatchSets/FirmwareGuestPatchResolutionTests.swift
@@ -269,6 +269,19 @@ struct FirmwareGuestPatchResolutionTests {
#expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: ["dyld-cfw-camera"], arm64eUserland: true) == ["dyld-cfw-camera"])
}
+ @Test
+ func `only an arm64e TV admits the environment hooks and the launchd patch that loads them`() {
+ let hooks: Set = ["system-launchdaemons-boot-environment", "system-launchd-boot-jetsam_panic_guard_bypass"]
+ #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: hooks, arm64eUserland: true).isEmpty)
+ // Both libraries are arm64e: a plain-arm64 launchd cannot load them.
+ #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: hooks) == hooks.sorted())
+ // The X1 launchd bootstrap shares the load command but stays out.
+ let x1 = FirmwareGuestSystemPatchSet.arm64eX1LaunchdBootstrap
+ #expect(FirmwareGuestPatchResolution.unvalidatedTVGuestPatches(enabled: [x1], arm64eUserland: true) == [x1])
+ // HomePod keeps its own launchd library and no environment.
+ #expect(FirmwareGuestPatchResolution.unvalidatedHomePodGuestPatches(enabled: hooks) == hooks.sorted())
+ }
+
@Test(arguments: ["27.0", "27.2"])
func `the Apple TV 4K preset swaps in the OTA userland with the GPU driver and no TPRO patches`(version: String) throws {
let gpu = "system-extensions-boot-gpu_bundle"
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index 693e13e6..1ea206e5 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -1477,8 +1477,12 @@ struct VPhoneCustomFirmwareInstaller {
}
isolate(["system-launchdaemons-boot-environment"]) {
if on("system-launchdaemons-boot-environment") {
- try installEnvironment(system: system, environmentOnly: environmentOnly)
+ try installEnvironment(system: system, work: work, guestDevice: guestDevice,
+ environmentOnly: environmentOnly)
live.insert("system-launchdaemons-boot-environment")
+ } else if guestDevice.family == .appleTV {
+ // Optional on TV, unlike on iOS: take it out again.
+ try removeTVEnvironment(system: system)
}
}
// HomePod deliberately excludes the iPhone environment. Inject only the
@@ -2902,25 +2906,75 @@ struct VPhoneCustomFirmwareInstaller {
/// selected it), and the `/vh` alias is not created — an installed VM
/// already has it, and an environment update does not add load-command
/// infrastructure. A full install writes every library and creates `/vh`.
- private func installEnvironment(system: VPhoneConfinedDirectory, environmentOnly: Bool = false) throws {
- for name in VPhoneGuestEnvironment.libraries {
+ ///
+ /// An Apple TV takes `VPhoneGuestEnvironment.tvLibraries` alone, marked
+ /// tvOS. No TV guest had an environment before, so the narrow rule does
+ /// not apply there: both libraries and `/vh` are always written.
+ private func installEnvironment(
+ system: VPhoneConfinedDirectory,
+ work: WorkDirectory,
+ guestDevice: VPhoneGuestDevice,
+ environmentOnly: Bool = false,
+ ) throws {
+ let tvOS = guestDevice.family == .appleTV
+ let narrow = environmentOnly && !tvOS
+ for name in tvOS ? VPhoneGuestEnvironment.tvLibraries : VPhoneGuestEnvironment.libraries {
if VPhoneGuestEnvironment.selectedLibraries.contains(name) {
continue
}
let path = "usr/lib/\(name)"
- if environmentOnly, try !system.exists(path) {
+ if narrow, try !system.exists(path) {
print(" [·] \(path): not on this VM, left out")
continue
}
- let source = try VPhoneGuestBinaries.resolve(name)
+ let shipped = try VPhoneGuestBinaries.resolve(name)
+ let source = tvOS ? try tvOSCopy(of: shipped, work: work) : shipped
try system.replaceFile(path, fromFileAt: source, mode: 0o755, owner: Self.guestOwner)
}
- if !environmentOnly {
+ if !narrow {
// launchd has little free header space for another load command.
// /vh fits the same 32-byte command as the old /b without reusing it.
try installLibraryAlias(system: system, alias: "vh", target: "/usr/lib/launchdhook-vphone.dylib")
}
- try installMISFixDefaults(system: system)
+ if tvOS {
+ print(" [+] Environment hooks retargeted to tvOS: \(VPhoneGuestEnvironment.tvLibraries.joined(separator: ", "))")
+ } else {
+ try installMISFixDefaults(system: system)
+ }
+ }
+
+ /// A bundle-shipped iOS library, marked tvOS and signed again in the work
+ /// directory. dyld refuses to load a library of another platform, and an
+ /// Apple TV guest's processes, launchd among them, are tvOS.
+ private func tvOSCopy(of source: URL, work: WorkDirectory) throws -> URL {
+ let name = "tvos-\(source.lastPathComponent)"
+ try work.directory.removeItem(name)
+ let staged = work.file(name)
+ var data = try Data(contentsOf: source)
+ try MachOBuildPlatform.set(MachOBuildPlatform.tvOS, in: &data)
+ try data.write(to: staged)
+ try VPhoneSigner.sign(
+ fileAt: staged,
+ options: .init(identifier: nil, entitlements: nil, mergesExisting: true, style: .appleAdHoc),
+ )
+ return staged
+ }
+
+ /// The TV environment's libraries and `/vh`, when the environment is off.
+ /// A launchd still patched to load `/vh` loads nothing: the command is weak.
+ private func removeTVEnvironment(system: VPhoneConfinedDirectory) throws {
+ var removed = false
+ for name in VPhoneGuestEnvironment.tvLibraries where try system.exists("usr/lib/\(name)") {
+ try system.removeItem("usr/lib/\(name)")
+ removed = true
+ }
+ if try system.isSymlink("vh"), try system.readLink("vh") == "/usr/lib/launchdhook-vphone.dylib" {
+ try system.removeItem("vh")
+ removed = true
+ }
+ if removed {
+ print(" [+] system-launchdaemons-boot-environment: removed the TV environment hooks")
+ }
}
/// The CoreAudio HAL plugin for the VM's virtio sound device. iOS ships
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuBootstrap.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuBootstrap.swift
index 3f91c270..9fce7ca8 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuBootstrap.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuBootstrap.swift
@@ -129,16 +129,18 @@ extension VPhoneMenuController {
} else {
VPhoneLocalization.text("Choose the bootstrap layout. This installs the latest Irisin release once in the guest.")
}
+ // Irisin serves an Apple TV only as RootHide; vphoned refuses rootless there.
+ let offersRootless = !showsTVControls
VPhoneAlert.present(
title: "Install Bootstrap",
message: message,
style: .informational,
- buttons: ["roothide", "rootless (deprecated)", "Cancel"],
+ buttons: offersRootless ? ["roothide", "rootless (deprecated)", "Cancel"] : ["roothide", "Cancel"],
) { [weak self] response in
let layout: String
switch response {
case .alertFirstButtonReturn: layout = "roothide"
- case .alertSecondButtonReturn: layout = "rootless"
+ case .alertSecondButtonReturn where offersRootless: layout = "rootless"
default: return
}
self?.performBootstrapInstallation(layout: layout, localURL: localURL)
diff --git a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestEnvironment.swift b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestEnvironment.swift
index a1607638..bb811f06 100644
--- a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestEnvironment.swift
+++ b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneGuestEnvironment.swift
@@ -23,6 +23,13 @@ public enum VPhoneGuestEnvironment {
"libvphoneattitude.dylib",
]
+ /// What an Apple TV takes: the launchd hook and SystemHook, which give
+ /// every spawn the RootHide loader links, the bootstrap root and the tweak
+ /// loader. The others serve iOS processes (SpringBoard, Settings, the
+ /// camera) or are not validated in tvOS ones, and the spawn hooks insert a
+ /// library only when it is installed.
+ public static let tvLibraries = ["launchdhook-vphone.dylib", "SystemHook-vphone.dylib"]
+
/// Selection installs/removes these. A live hash sync may replace an
/// installed copy, but must never reinstall a patch the user turned off.
public static let selectedLibraries: Set<String> = [