Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Add minimal vphone launchd hook and inert system hook

Lakr9efcaa65171c
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 6107315c..dbf1608e 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -2,12 +2,33 @@
> **Current product scope (September 2026):** the tables below preserve the
> historical patch comparison. The public runtime now exposes only JB. Guest
-> package managers, Procursus, BaseBin hooks, and first-boot package setup are
-> outside this repository. The native Swift JB install retains the base system patches,
+> package managers, Procursus, and first-boot package setup are outside this
+> repository. The native Swift JB install retains the base system patches,
> launchd jetsam guard, debugserver entitlement edit, iOS 27 Campo entitlement
-> edit, GPU driver, and mandatory vphoned. Old variant rows are research history,
+> edit, GPU driver, mandatory vphoned, and the small vphone launchd hook described
+> below. Old variant rows are research history,
> not available install modes.
+> **Current launchd hook (2026-09-24; source/build verification only):**
+> `cfw install` now places `launchdhook-vphone.dylib` and an inert
+> `SystemHook-vphone.dylib` in `/usr/lib`, links `/vh` to the launchd hook,
+> inserts a weak `/vh` load command for the
+> launchd hook after `patch-launchd-jetsam`, and re-signs launchd. The hook
+> extends launchd's `Paths` and `LaunchDaemons` values with the selected
+> bootstrap's `Library/LaunchDaemons` (plus `basebin/LaunchDaemons` when present).
+> A single `.jbroot-<16 hex>` under the RootHide application container is
+> accepted; ambiguous roots are ignored. RootHide bootstrap-relative `Program`
+> and `ProgramArguments[0]` paths are translated to physical kernel paths in
+> the in-memory XPC plist. The hook also tries to remove PID 1's existing
+> jetsam limit and suppresses future fatal task-limit assignments for PID 1.
+> `SystemHook-vphone.dylib` is not injected into processes in this phase; ElleKit
+> chain loading, `DISABLE_TWEAKS`, and tweak filters remain a later step.
+> **Validation needed on a disposable VM before relying on this at boot:**
+> confirm launchd loads the weak dylib and dyld interposition fires; install
+> one RootHide and one rootless daemon on separate VM copies, reboot each, and
+> inspect their `launchctl print` executable paths; verify PID 1's effective
+> jetsam limit separately from the existing panic-guard patch.
+
> **`scripts/patchers/*.py` no longer exists.** The tables below cite those
> filenames throughout, because that is where each patch was first written and
> where its on-device validation notes were recorded. Every one is now a Swift
diff --git a/Research/Host/runtime_dependency_tiers.md b/Research/Host/runtime_dependency_tiers.md
index 9fd86de5..fd8324b7 100644
--- a/Research/Host/runtime_dependency_tiers.md
+++ b/Research/Host/runtime_dependency_tiers.md
@@ -63,8 +63,10 @@ that does not work on a clean Mac.
### The compile/install split
-Five Mach-Os run inside the guest: `vphoned`, `TweakLoader.dylib`,
-`vpregister`, `libvcamcaptured.dylib`, `libcamfix.dylib`. Every one used to be
+The guest bundle includes `vphoned`, `vpregister`, `libvcamcaptured.dylib`,
+`libcamfix.dylib`, `launchdhook-vphone.dylib`, and the currently inert
+`SystemHook-vphone.dylib`. ElleKit's `TweakLoader.dylib` is installed later by
+Irisin into the chosen bootstrap. The earlier guest binaries used to be
compiled at CFW-install time — three by the installers, and `vphoned` twice
more (again by `FirmwarePatcher.buildVphoned`). That made a full Xcode install
a prerequisite for putting firmware on a VM.
@@ -79,10 +81,9 @@ framework list included. That looks arbitrary and is load-bearing:
`-framework` order decides `LC_LOAD_DYLIB` order, which decides the indirect
symbol table's numbering. With it, `vpregister` and `libvcamcaptured.dylib`
come out **byte-identical** to what the installers used to produce.
-`TweakLoader.dylib` differs in exactly two fields per slice — `LC_UUID`
-(content-derived, differs between any two links) and `LC_ID_DYLIB` (it takes no
-`-install_name`, so this defaults to the output path; nothing reads it, the
-guest loads the file by absolute path from `/var/jb/usr/lib`).
+The vphone launchd hook is compiled as C and links only `libSystem`; it is
+loaded through a short `/vh` alias during boot. The process hook currently has
+no constructor, spawn interception, or ElleKit chain load.
---
diff --git a/Scripts/check_aux.sh b/Scripts/check_aux.sh
index 306e0455..6d4ad2ff 100755
--- a/Scripts/check_aux.sh
+++ b/Scripts/check_aux.sh
@@ -20,7 +20,8 @@ file_copy_spawns="$(/usr/bin/find "$root/VPhoneExecutable" "$root/VPhoneKit" \
[[ -d "$bundle" ]] || { print -u2 "Missing Xcode bundle: $bundle"; exit 1; }
for name in vphone-vm vphone-cli VPhoneEscalator vphoned vphoned.signed \
- vpregister libswiftCompatibilitySpan.vphone.dylib libcamfix.dylib libvcamcaptured.dylib TweakLoader.dylib \
+ vpregister libswiftCompatibilitySpan.vphone.dylib libcamfix.dylib libvcamcaptured.dylib \
+ launchdhook-vphone.dylib SystemHook-vphone.dylib \
libAppleParavirtCompilerPluginIOGPUFamily.dylib; do
[[ -f "$macos/$name" ]] || { print -u2 "Missing binary: Contents/MacOS/$name"; exit 1; }
/usr/bin/file "$macos/$name" | /usr/bin/grep -q 'Mach-O' || {
diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
index bba898aa..a44ecf2d 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -219,12 +219,14 @@ struct VPhoneCustomFirmwareInstaller {
verb: "patch-mobileactivationd",
)
try installVphoned(system: system, work: work)
+ try installLaunchHook(system: system)
try patchMachO(
system: system,
work: work,
path: "sbin/launchd",
verb: "patch-launchd-jetsam",
preserveEntitlements: true,
+ injectedDylibPath: "/vh",
)
try patchDebugserver(system: system, work: work)
if version.hasPrefix("27.") {
@@ -325,6 +327,26 @@ struct VPhoneCustomFirmwareInstaller {
try replace(temp, at: launchd, mode: 0o644)
}
+ private func installLaunchHook(system: URL) throws {
+ for name in ["launchdhook-vphone.dylib", "SystemHook-vphone.dylib"] {
+ let source = try VPhoneGuestBinaries.resolve(name)
+ try replace(source, at: system.appendingPathComponent("usr/lib/\(name)"), mode: 0o755)
+ }
+ // launchd has little free header space for another load command.
+ // /vh fits the same 32-byte command as the old /b without reusing it.
+ let alias = system.appendingPathComponent("vh")
+ let target = "/usr/lib/launchdhook-vphone.dylib"
+ if fm.fileExists(atPath: alias.path)
+ || (try? alias.resourceValues(forKeys: [.isSymbolicLinkKey]))?.isSymbolicLink == true
+ {
+ guard (try? fm.destinationOfSymbolicLink(atPath: alias.path)) == target else {
+ throw ValidationError("Root path /vh is already occupied")
+ }
+ } else {
+ try fm.createSymbolicLink(atPath: alias.path, withDestinationPath: target)
+ }
+ }
+
private func patchMachO(
system: URL,
work: URL,
@@ -332,6 +354,7 @@ struct VPhoneCustomFirmwareInstaller {
verb: String,
identifier: String? = nil,
preserveEntitlements: Bool = false,
+ injectedDylibPath: String? = nil,
) throws {
let target = system.appendingPathComponent(path)
let backup = target.appendingPathExtension("bak")
@@ -347,6 +370,9 @@ struct VPhoneCustomFirmwareInstaller {
? try VPhoneSigner.entitlements(ofFileAt: backup).first(where: { !$0.isEmpty })
: nil
try patch(verb, [staged.path])
+ if let injectedDylibPath {
+ try patch("inject-dylib", [staged.path, injectedDylibPath])
+ }
try VPhoneSigner.sign(fileAt: staged,
options: .init(identifier: identifier, entitlements: entitlements, mergesExisting: true))
try replace(staged, at: target, mode: 0o755)
diff --git a/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh b/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
index 1adedf52..085c9a33 100755
--- a/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
+++ b/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
@@ -64,7 +64,8 @@ fi
/bin/cp "$amfi_products/VPhoneEscalator" "$macos/VPhoneEscalator"
/bin/cp "$guest_products/camfix/libcamfix.dylib" "$macos/libcamfix.dylib"
/bin/cp "$guest_products/vcamcaptured/libvcamcaptured.dylib" "$macos/libvcamcaptured.dylib"
-/bin/cp "$guest_products/tweakloader/TweakLoader.dylib" "$macos/TweakLoader.dylib"
+/bin/cp "$guest_products/launchhook/launchdhook-vphone.dylib" "$macos/launchdhook-vphone.dylib"
+/bin/cp "$guest_products/systemhook/SystemHook-vphone.dylib" "$macos/SystemHook-vphone.dylib"
/bin/cp "$guest_products/gpu/libAppleParavirtCompilerPluginIOGPUFamily.dylib" "$macos/libAppleParavirtCompilerPluginIOGPUFamily.dylib"
/bin/cp "$root/VPhoneDaemon/Configuration/vphoned.plist" "$resources/scripts/vphoned/vphoned.plist"
/bin/cp "$root/VPhoneDaemon/Configuration/VPhoneDaemon.entitlements" "$resources/scripts/vphoned/VPhoneDaemon.entitlements"
diff --git a/VPhoneGuestComponents/LaunchHook/launchdhook-vphone.c b/VPhoneGuestComponents/LaunchHook/launchdhook-vphone.c
new file mode 100644
index 00000000..901b9286
--- /dev/null
+++ b/VPhoneGuestComponents/LaunchHook/launchdhook-vphone.c
@@ -0,0 +1,183 @@
+#include <dlfcn.h>
+#include <dirent.h>
+#include <ctype.h>
+#include <fcntl.h>
+#include <limits.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#include <xpc/xpc.h>
+
+// Neither bootstrap exists on the first boot. RootHide is chosen once and
+// keeps one randomized root across later boots; ambiguity disables discovery.
+static int vpFindJBRoot(char root[PATH_MAX]) {
+ struct stat info;
+ if (stat("/var/jb/usr/lib", &info) == 0 && S_ISDIR(info.st_mode)) {
+ return realpath("/var/jb", root) != NULL;
+ }
+ const char *parent = "/private/var/containers/Bundle/Application";
+ DIR *directory = opendir(parent);
+ if (!directory) return 0;
+ int matches = 0;
+ struct dirent *entry;
+ while ((entry = readdir(directory))) {
+ if (strncmp(entry->d_name, ".jbroot-", 8) != 0 || strlen(entry->d_name) != 24) continue;
+ int valid = 1;
+ for (unsigned index = 8; index < 24; index++) {
+ if (!isxdigit((unsigned char)entry->d_name[index])) valid = 0;
+ }
+ if (!valid) continue;
+ char candidate[PATH_MAX];
+ int length = snprintf(candidate, sizeof(candidate), "%s/%s", parent, entry->d_name);
+ if (length < 0 || (size_t)length >= sizeof(candidate)) continue;
+ char library[PATH_MAX];
+ length = snprintf(library, sizeof(library), "%s/usr/lib", candidate);
+ if (length < 0 || (size_t)length >= sizeof(library) ||
+ stat(library, &info) != 0 || !S_ISDIR(info.st_mode)) continue;
+ if (!realpath(candidate, root)) continue;
+ matches++;
+ }
+ closedir(directory);
+ if (matches != 1) root[0] = '\0';
+ return matches == 1;
+}
+
+// launchd itself uses kernel paths. Bootstrap tools may use vroot paths, but
+// plist discovery and ProgramArguments handed to launchd must be physical.
+typedef xpc_object_t (*VPGetValue)(xpc_object_t, const char *);
+typedef xpc_object_t (*VPPlistDecoder)(const void *, size_t);
+typedef int (*VPMemoryStatus)(uint32_t, int32_t, uint32_t, void *, size_t);
+extern int memorystatus_control(uint32_t, int32_t, uint32_t, void *, size_t);
+
+enum { VPSetJetsamHighWaterMark = 5, VPSetJetsamTaskLimit = 6 };
+
+static VPGetValue vpOriginalGetValue(void) {
+ return (VPGetValue)dlsym(RTLD_NEXT, "xpc_dictionary_get_value");
+}
+
+static VPMemoryStatus vpOriginalMemoryStatus(void) {
+ return (VPMemoryStatus)dlsym(RTLD_NEXT, "memorystatus_control");
+}
+
+static int vpPhysicalProgram(const char *program, const char *root, char physical[PATH_MAX]) {
+ if (!program || program[0] != '/') return 0;
+ size_t rootLength = strlen(root);
+ if (strncmp(program, root, rootLength) == 0 && program[rootLength] == '/') return 0;
+ char canonical[PATH_MAX];
+ if (realpath(program, canonical) &&
+ strncmp(canonical, root, rootLength) == 0 && canonical[rootLength] == '/') return 0;
+ int used = strncmp(program, "/rootfs/", 8) == 0
+ ? snprintf(physical, PATH_MAX, "%s", program + 7)
+ : snprintf(physical, PATH_MAX, "%s%s", root, program);
+ return used > 0 && used < PATH_MAX;
+}
+
+static void vpPatchProgram(xpc_object_t plist, const char *root) {
+ // RootHide's bootstrap paths are relative to jbroot. launchd is outside
+ // vroot, so its executable must be passed as a physical kernel path.
+ if (access("/var/jb", F_OK) == 0 || xpc_dictionary_get_bool(plist, "__Patched")) return;
+ xpc_object_t args = xpc_dictionary_get_value(plist, "ProgramArguments");
+ if (args && xpc_get_type(args) == XPC_TYPE_ARRAY && xpc_array_get_count(args) > 0) {
+ const char *program = xpc_array_get_string(args, 0);
+ char physical[PATH_MAX];
+ if (vpPhysicalProgram(program, root, physical)) xpc_array_set_string(args, 0, physical);
+ }
+ const char *program = xpc_dictionary_get_string(plist, "Program");
+ char physical[PATH_MAX];
+ if (vpPhysicalProgram(program, root, physical)) xpc_dictionary_set_string(plist, "Program", physical);
+}
+
+static void vpAddPlist(xpc_object_t dictionary, const char *path, const char *root) {
+ int fd = open(path, O_RDONLY | O_CLOEXEC | O_NOFOLLOW);
+ if (fd < 0) return;
+ struct stat info;
+ if (fstat(fd, &info) == 0 && S_ISREG(info.st_mode) && info.st_size > 0 &&
+ info.st_size < 1024 * 1024) {
+ void *bytes = mmap(NULL, (size_t)info.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+ if (bytes != MAP_FAILED) {
+ VPPlistDecoder decode = (VPPlistDecoder)dlsym(RTLD_DEFAULT, "xpc_create_from_plist");
+ if (decode) {
+ xpc_object_t plist = decode(bytes, (size_t)info.st_size);
+ if (plist && xpc_get_type(plist) == XPC_TYPE_DICTIONARY) {
+ vpPatchProgram(plist, root);
+ xpc_dictionary_set_value(dictionary, path, plist);
+ }
+ if (plist) xpc_release(plist);
+ }
+ munmap(bytes, (size_t)info.st_size);
+ }
+ }
+ close(fd);
+}
+
+static void vpAddDaemons(xpc_object_t dictionary, const char *directory, const char *root) {
+ DIR *stream = opendir(directory);
+ if (!stream) return;
+ struct dirent *entry;
+ while ((entry = readdir(stream))) {
+ size_t length = strlen(entry->d_name);
+ if (length < 6 || strcmp(entry->d_name + length - 6, ".plist") != 0) continue;
+ char path[PATH_MAX];
+ int used = snprintf(path, sizeof(path), "%s/%s", directory, entry->d_name);
+ if (used > 0 && (size_t)used < sizeof(path)) vpAddPlist(dictionary, path, root);
+ }
+ closedir(stream);
+}
+
+static xpc_object_t vpGetValue(xpc_object_t dictionary, const char *key) {
+ VPGetValue original = vpOriginalGetValue();
+ if (!original) return NULL;
+ xpc_object_t value = original(dictionary, key);
+ if (getpid() != 1 || !value || !key ||
+ (strcmp(key, "Paths") != 0 && strcmp(key, "LaunchDaemons") != 0)) {
+ return value;
+ }
+ char root[PATH_MAX];
+ if (!vpFindJBRoot(root)) return value;
+ char path[PATH_MAX];
+ int used = snprintf(path, sizeof(path), "%s/Library/LaunchDaemons", root);
+ if (used < 0 || (size_t)used >= sizeof(path)) return value;
+ if (strcmp(key, "Paths") == 0 && xpc_get_type(value) == XPC_TYPE_ARRAY) {
+ xpc_array_set_string(value, XPC_ARRAY_APPEND, path);
+ used = snprintf(path, sizeof(path), "%s/basebin/LaunchDaemons", root);
+ if (used > 0 && (size_t)used < sizeof(path) && access(path, F_OK) == 0) {
+ xpc_array_set_string(value, XPC_ARRAY_APPEND, path);
+ }
+ } else if (strcmp(key, "LaunchDaemons") == 0 &&
+ xpc_get_type(value) == XPC_TYPE_DICTIONARY) {
+ vpAddDaemons(value, path, root);
+ used = snprintf(path, sizeof(path), "%s/basebin/LaunchDaemons", root);
+ if (used > 0 && (size_t)used < sizeof(path)) vpAddDaemons(value, path, root);
+ }
+ return value;
+}
+
+static int vpMemoryStatus(uint32_t command, int32_t pid, uint32_t flags,
+ void *buffer, size_t size) {
+ if (getpid() == 1 && command == VPSetJetsamTaskLimit && (pid == 1 || pid == 0)) {
+ return 0;
+ }
+ VPMemoryStatus original = vpOriginalMemoryStatus();
+ return original ? original(command, pid, flags, buffer, size) : -1;
+}
+
+__attribute__((constructor))
+static void vpLaunchHookInit(void) {
+ if (getpid() != 1) return;
+ VPMemoryStatus original = vpOriginalMemoryStatus();
+ if (!original) return;
+ // The firmware panic-guard patch does not remove a limit already on PID 1.
+ original(VPSetJetsamTaskLimit, 1, (uint32_t)-1, NULL, 0);
+ original(VPSetJetsamHighWaterMark, 1, (uint32_t)-1, NULL, 0);
+}
+
+// This image is loaded by launchd's LC_LOAD_WEAK_DYLIB. Child injection is
+// deliberately deferred until SystemHook has its own process policy.
+__attribute__((used, section("__DATA,__interpose")))
+static const struct { const void *replacement; const void *replacee; } vpInterpose[] = {
+ {(const void *)vpGetValue, (const void *)xpc_dictionary_get_value},
+ {(const void *)vpMemoryStatus, (const void *)memorystatus_control},
+};
diff --git a/VPhoneGuestComponents/Makefile b/VPhoneGuestComponents/Makefile
index 4fad9b87..8043727c 100644
--- a/VPhoneGuestComponents/Makefile
+++ b/VPhoneGuestComponents/Makefile
@@ -5,13 +5,15 @@ OUT := $(abspath ../.build/siblings)
STAGE := $(OUT)/stage
ARCHIVE := $(OUT)/siblings.tar
CLANG := xcrun --sdk iphoneos clang
-COMMON_FLAGS := -arch arm64e -miphoneos-version-min=26.0 -Os -fobjc-arc
+GUEST_C_FLAGS := -arch arm64e -miphoneos-version-min=26.0 -Os
+COMMON_FLAGS := $(GUEST_C_FLAGS) -fobjc-arc
CAMFIX := $(STAGE)/camfix/libcamfix.dylib
VCAMCAPTURED := $(STAGE)/vcamcaptured/libvcamcaptured.dylib
-TWEAKLOADER := $(STAGE)/tweakloader/TweakLoader.dylib
+LAUNCHHOOK := $(STAGE)/launchhook/launchdhook-vphone.dylib
+SYSTEMHOOK := $(STAGE)/systemhook/SystemHook-vphone.dylib
GPU_PLUGIN := $(STAGE)/gpu/libAppleParavirtCompilerPluginIOGPUFamily.dylib
-ARTIFACTS := $(CAMFIX) $(VCAMCAPTURED) $(TWEAKLOADER) $(GPU_PLUGIN)
+ARTIFACTS := $(CAMFIX) $(VCAMCAPTURED) $(LAUNCHHOOK) $(SYSTEMHOOK) $(GPU_PLUGIN)
PLISTS := $(STAGE)/camfix/libcamfix.plist $(STAGE)/vcamcaptured/libvcamcaptured.plist
GPU_PROVENANCE := $(STAGE)/gpu/README.md
@@ -23,10 +25,10 @@ gpu: $(GPU_PLUGIN)
package: all
@rm -f $(ARCHIVE)
- @/usr/bin/tar -cf $(ARCHIVE) -C $(STAGE) camfix vcamcaptured tweakloader gpu
+ @/usr/bin/tar -cf $(ARCHIVE) -C $(STAGE) camfix vcamcaptured launchhook systemhook gpu
@echo "Packaged $(ARCHIVE)"
-$(STAGE)/camfix $(STAGE)/vcamcaptured $(STAGE)/tweakloader $(STAGE)/gpu:
+$(STAGE)/camfix $(STAGE)/vcamcaptured $(STAGE)/launchhook $(STAGE)/systemhook $(STAGE)/gpu:
@mkdir -p $@
$(CAMFIX): CamFix/libcamfix.m | $(STAGE)/camfix
@@ -45,10 +47,16 @@ $(VCAMCAPTURED): VCamCaptured/libvcamcaptured.m | $(STAGE)/vcamcaptured
-framework Foundation -framework CoreMedia -framework CoreVideo
@codesign --force --sign - $@
-$(TWEAKLOADER): TweakLoader/TweakLoader.m | $(STAGE)/tweakloader
- $(CLANG) $(COMMON_FLAGS) -dynamiclib \
- -install_name /var/jb/usr/lib/TweakLoader.dylib \
- -o $@ $< -framework Foundation
+$(LAUNCHHOOK): LaunchHook/launchdhook-vphone.c | $(STAGE)/launchhook
+ $(CLANG) $(GUEST_C_FLAGS) -dynamiclib \
+ -install_name /usr/lib/launchdhook-vphone.dylib \
+ -o $@ $< -Wl,-not_for_dyld_shared_cache
+ @codesign --force --sign - $@
+
+$(SYSTEMHOOK): SystemHook/SystemHook-vphone.c | $(STAGE)/systemhook
+ $(CLANG) $(GUEST_C_FLAGS) -dynamiclib \
+ -install_name /usr/lib/SystemHook-vphone.dylib \
+ -o $@ $<
@codesign --force --sign - $@
$(GPU_PLUGIN): GraphicLoader/main.mm | $(STAGE)/gpu
diff --git a/VPhoneGuestComponents/README.md b/VPhoneGuestComponents/README.md
index f8acdd04..8aef56be 100644
--- a/VPhoneGuestComponents/README.md
+++ b/VPhoneGuestComponents/README.md
@@ -1,20 +1,22 @@
# Sibling guest components
-`make -C Siblings package` cross-compiles four
-optional guest components with Xcode's iPhoneOS SDK and writes
-`.build/siblings/siblings.tar`. The archive contains signed arm64e binaries,
-two tweak filter plists, and the GPU provenance note:
+`make -C VPhoneGuestComponents package` cross-compiles guest components with
+Xcode's iPhoneOS SDK. The archive contains signed arm64e binaries, two camera
+tweak filter plists, and the GPU provenance note:
| Component | Archive contents |
| --- | --- |
| Camera app hook | `camfix/libcamfix.dylib`, `camfix/libcamfix.plist` |
| Camera daemon hook | `vcamcaptured/libvcamcaptured.dylib`, `vcamcaptured/libvcamcaptured.plist` |
-| Tweak loader | `tweakloader/TweakLoader.dylib` |
+| Launchd hook | `launchhook/launchdhook-vphone.dylib` |
+| Reserved process hook | `systemhook/SystemHook-vphone.dylib` |
| iOS 27 app registrar | `vpregister/vpregister` |
| PCC GPU driver | `gpu/README.md` (source and extraction flow; no Apple binary) |
-The archive is a local build artifact, not a VM bootstrap. The four optional
-components are not installed by the normal JB flow. The required GPU bundle is
+The archive is a local build artifact, not a VM bootstrap. The launchd hook is
+installed by `cfw install` to discover package daemons after reboot; the process
+hook is staged but has no injection or chain-load behavior yet. Irisin installs
+ElleKit's own `TweakLoader.dylib` in the selected bootstrap. The required GPU bundle is
instead extracted from the selected PCC firmware by `vphone-cli fw prepare`
and copied into the VM during JB installation. No Apple GPU binary is stored
in this directory, the archive, or the shipped app.
diff --git a/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c b/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c
new file mode 100644
index 00000000..967ae6f2
--- /dev/null
+++ b/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c
@@ -0,0 +1,3 @@
+// Reserved for a later, explicitly gated ElleKit chain load.
+// This first version does not inject SystemHook into any process.
+int vphone_systemhook_version(void) { return 1; }
diff --git a/VPhoneGuestComponents/TweakLoader/README.md b/VPhoneGuestComponents/TweakLoader/README.md
deleted file mode 100644
index e5f4fe1a..00000000
--- a/VPhoneGuestComponents/TweakLoader/README.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Lean TweakLoader
-
-Purpose
-
-- Provide the `/var/jb/usr/lib/TweakLoader.dylib` component expected by the
- vphone JB basebin runtime (`systemhook.dylib`).
-- Load user tweak dylibs from
- `/var/jb/Library/MobileSubstrate/DynamicLibraries` into matching processes.
-
-Current behavior
-
-- Enumerates substrate-style `.plist` files in the tweak directory.
-- Two engagement tiers:
- - `Filter.Frameworks` tweaks are scheduled in *every* process and
- `dlopen`ed asynchronously once a matching `*.framework/` image loads
- (`_dyld_register_func_for_add_image`); no `dlopen` happens in a process
- where the named framework never appears.
- - Tweaks filtered by `Filter.Bundles` / `Filter.Executables`, or with no
- filter, load only in `.app/` processes plus the daemon allowlist in
- `kVPhoneAllowedDaemonPaths`.
-- `dlopen`s the corresponding `.dylib` when the current process matches.
-
-Logging
-
-- Writes to `/var/jb/var/mobile/Library/TweakLoader/tweakloader.log`.
diff --git a/VPhoneGuestComponents/TweakLoader/TweakLoader.m b/VPhoneGuestComponents/TweakLoader/TweakLoader.m
deleted file mode 100644
index 88ec62c7..00000000
--- a/VPhoneGuestComponents/TweakLoader/TweakLoader.m
+++ /dev/null
@@ -1,291 +0,0 @@
-#import <Foundation/Foundation.h>
-#import <dlfcn.h>
-#import <fcntl.h>
-#import <mach-o/dyld.h>
-#import <mach-o/loader.h>
-#import <stdarg.h>
-#import <string.h>
-#import <unistd.h>
-
-static NSString *const kTweakDir = @"/var/jb/Library/MobileSubstrate/DynamicLibraries";
-static NSString *const kLogDir = @"/var/jb/var/mobile/Library/TweakLoader";
-static NSString *const kLogPath = @"/var/jb/var/mobile/Library/TweakLoader/tweakloader.log";
-
-static void TLLog(NSString *format, ...) {
- va_list args;
- va_start(args, format);
- NSString *message = [[NSString alloc] initWithFormat:format arguments:args];
- va_end(args);
-
- if (!message.length) return;
-
- [[NSFileManager defaultManager] createDirectoryAtPath:kLogDir
- withIntermediateDirectories:YES
- attributes:nil
- error:nil];
-
- NSString *line = [NSString stringWithFormat:@"%@ [TweakLoader] %@\n",
- [NSDate.date description],
- message];
- NSData *data = [line dataUsingEncoding:NSUTF8StringEncoding];
- if (!data.length) return;
-
- int fd = open(kLogPath.fileSystemRepresentation, O_WRONLY | O_CREAT | O_APPEND, 0644);
- if (fd < 0) return;
- (void)write(fd, data.bytes, data.length);
- close(fd);
-}
-
-static NSString *TLExecutableName(void) {
- NSString *argv0 = NSProcessInfo.processInfo.arguments.firstObject;
- if (argv0.length) return argv0.lastPathComponent;
- return NSProcessInfo.processInfo.processName ?: @"unknown";
-}
-
-static NSString *TLExecutablePath(void) {
- NSString *argv0 = NSProcessInfo.processInfo.arguments.firstObject;
- return argv0 ?: @"";
-}
-
-// Daemons the loader is explicitly allowed to load tweaks into, even though
-// they're not under a `.app/` path. Keep this list narrow — every daemon
-// added here is a process where a buggy tweak can crash a launchd-managed
-// service and destabilize boot.
-//
-// This list ONLY applies to tweaks WITHOUT Filter.Frameworks. Framework-
-// filtered tweaks engage in every process and self-limit based on which
-// frameworks are actually loaded — they don't need per-daemon entries here.
-static NSString *const kVPhoneAllowedDaemonPaths[] = {
- @"/usr/libexec/cameracaptured", // libvcamcaptured (Filter.Executables match)
-};
-
-static BOOL TLShouldRunInCurrentProcess(void) {
- NSString *execPath = TLExecutablePath();
- if (!execPath.length) return NO;
-
- // vphone's hook runtime injects broadly, including launch-critical daemons
- // like xpcproxy, logd, notifyd, sshd, shells, and helper tools. Restrict the
- // user tweak loader to app binaries only — plus an allowlist of daemons
- // that explicitly opt in (see `kVPhoneAllowedDaemonPaths`).
- if ([execPath containsString:@".app/"]) return YES;
-
- for (size_t i = 0;
- i < sizeof(kVPhoneAllowedDaemonPaths) /
- sizeof(kVPhoneAllowedDaemonPaths[0]);
- i++) {
- if ([execPath isEqualToString:kVPhoneAllowedDaemonPaths[i]]) return YES;
- }
-
- return NO;
-}
-
-static BOOL TLArrayContainsString(NSArray *array, NSString *value) {
- for (id item in array) {
- if ([item isKindOfClass:[NSString class]] &&
- [(NSString *)item isEqualToString:value]) {
- return YES;
- }
- }
- return NO;
-}
-
-static BOOL TLFilterMatches(NSDictionary *filter, NSString *bundleID, NSString *executableName) {
- if (![filter isKindOfClass:[NSDictionary class]]) {
- return YES;
- }
-
- id bundles = filter[@"Bundles"];
- if ([bundles isKindOfClass:[NSArray class]]) {
- if (!bundleID.length || !TLArrayContainsString(bundles, bundleID)) {
- return NO;
- }
- }
-
- id executables = filter[@"Executables"];
- if ([executables isKindOfClass:[NSArray class]]) {
- if (!executableName.length || !TLArrayContainsString(executables, executableName)) {
- return NO;
- }
- }
-
- return YES;
-}
-
-// Match a loaded dylib path against a "framework name" filter entry.
-// "AVFoundation" matches any path containing "/AVFoundation.framework/" —
-// catches both /System/Library/Frameworks/... and PrivateFrameworks/....
-static BOOL TLPathMatchesFramework(const char *path, NSString *frameworkName) {
- if (!path || !frameworkName.length) return NO;
- NSString *needle = [NSString stringWithFormat:@"/%@.framework/", frameworkName];
- return strstr(path, needle.UTF8String) != NULL;
-}
-
-// Pending framework-filtered tweaks: each entry is @{"dylib": path, "frameworks": @[name,...]}.
-static NSMutableArray<NSDictionary *> *gTLPendingFrameworkTweaks = nil;
-static NSLock *gTLPendingLock = nil;
-static dispatch_once_t gTLAddImageOnce;
-
-// dyld invokes add-image callbacks SYNCHRONOUSLY inside its loader lock.
-// Calling dlopen from here would recurse and can deadlock or crash early
-// daemons. Hand the actual dlopen off to a background queue so it runs
-// outside the loader lock — by the time it executes, the framework that
-// triggered it is fully loaded.
-static void TLOnImageAdded(const struct mach_header *mh, intptr_t slide) {
- (void)slide;
- Dl_info info; if (!dladdr((const void *)mh, &info)) return;
- const char *cpath = info.dli_fname; if (!cpath) return;
- NSString *imagePath = [NSString stringWithUTF8String:cpath];
- if (!imagePath.length) return;
-
- NSArray<NSDictionary *> *snapshot;
- [gTLPendingLock lock];
- snapshot = [gTLPendingFrameworkTweaks copy];
- [gTLPendingLock unlock];
- if (!snapshot.count) return;
-
- NSMutableArray<NSString *> *toLoad = [NSMutableArray array];
- for (NSDictionary *pending in snapshot) {
- NSArray *frameworks = pending[@"frameworks"];
- for (NSString *fw in frameworks) {
- if (TLPathMatchesFramework(cpath, fw)) {
- [toLoad addObject:pending[@"dylib"]];
- break;
- }
- }
- }
- if (!toLoad.count) return;
-
- dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
- for (NSString *dylibPath in toLoad) {
- void *h = dlopen(dylibPath.fileSystemRepresentation, RTLD_NOW | RTLD_GLOBAL);
- if (h) TLLog(@"framework-deferred-load %@ -> %p (triggered by %@)", dylibPath, h, imagePath);
- else TLLog(@"framework-deferred-load failed for %@: %s", dylibPath, dlerror() ?: "unknown");
- }
- });
-}
-
-// Schedule a tweak whose Filter.Frameworks needs at least one framework loaded.
-// If a matching framework is already in the process, dlopen via dispatch_async
-// (the constructor is still inside dyld's image loading sequence). Otherwise
-// queue it; the dyld add-image callback (also async-deferred) handles future.
-static void TLScheduleFrameworkTweak(NSString *dylibPath, NSArray *frameworks) {
- // Already-loaded fast path: schedule dlopen on a background queue so it
- // runs after the TweakLoader constructor returns and dyld is idle.
- uint32_t n = _dyld_image_count();
- for (uint32_t i = 0; i < n; i++) {
- const char *p = _dyld_get_image_name(i);
- for (NSString *fw in frameworks) {
- if (TLPathMatchesFramework(p, fw)) {
- TLLog(@"queueing %@ for async load (framework %@ already loaded as %s)", dylibPath, fw, p);
- dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
- void *h = dlopen(dylibPath.fileSystemRepresentation, RTLD_NOW | RTLD_GLOBAL);
- if (h) TLLog(@"framework-load %@ -> %p", dylibPath, h);
- else TLLog(@"framework-load failed for %@: %s", dylibPath, dlerror() ?: "unknown");
- });
- return;
- }
- }
- }
-
- // Queue for later; register the add-image callback once.
- [gTLPendingLock lock];
- if (!gTLPendingFrameworkTweaks) gTLPendingFrameworkTweaks = [NSMutableArray array];
- [gTLPendingFrameworkTweaks addObject:@{@"dylib": dylibPath, @"frameworks": frameworks}];
- [gTLPendingLock unlock];
-
- dispatch_once(&gTLAddImageOnce, ^{
- _dyld_register_func_for_add_image(TLOnImageAdded);
- });
-}
-
-static void TLLoadTweaks(void) {
- // Two engagement tiers:
- //
- // 1. Framework-filtered tweaks (Filter.Frameworks in plist): scanned
- // and scheduled in EVERY process. The schedule is a no-op unless
- // the named framework actually loads in this process — the dyld
- // add-image callback (dispatch_async'd dlopen) is what eventually
- // pulls the tweak in. Cost in non-AVF processes: one dir scan,
- // a few plist parses, one callback registration. Safe because
- // no dlopen happens until the framework appears.
- //
- // 2. Non-framework tweaks (Bundles/Executables filter or none):
- // only run in .app/ processes and the explicit daemon allowlist
- // (TLShouldRunInCurrentProcess). Keeping this gate avoids dropping
- // arbitrary tweaks into launch-critical daemons by accident.
- //
- // Everything below is wrapped in @try/@catch so a bad plist or
- // Foundation quirk in an early-boot daemon can't crash the whole
- // process and trigger a launchd respawn loop.
- NSFileManager *fm = nil;
- NSArray<NSString *> *files = nil;
- @try {
- fm = NSFileManager.defaultManager;
- files = [fm contentsOfDirectoryAtPath:kTweakDir error:nil];
- } @catch (NSException *e) {
- return;
- }
- if (!files.count) return;
-
- NSString *bundleID = NSBundle.mainBundle.bundleIdentifier ?: @"";
- NSString *executableName = TLExecutableName();
- BOOL processAllowed = TLShouldRunInCurrentProcess();
-
- gTLPendingLock = [[NSLock alloc] init];
-
- for (NSString *filename in files) {
- if (![filename.pathExtension isEqualToString:@"plist"]) continue;
-
- NSDictionary *plist = nil;
- NSString *dylibPath = nil;
- @try {
- NSString *plistPath = [kTweakDir stringByAppendingPathComponent:filename];
- plist = [NSDictionary dictionaryWithContentsOfFile:plistPath];
- if (![plist isKindOfClass:[NSDictionary class]]) continue;
-
- NSString *baseName = filename.stringByDeletingPathExtension;
- dylibPath = [[kTweakDir stringByAppendingPathComponent:baseName]
- stringByAppendingPathExtension:@"dylib"];
- if (![fm isExecutableFileAtPath:dylibPath]) continue;
- } @catch (NSException *e) {
- continue;
- }
-
- @try {
- NSDictionary *filter = plist[@"Filter"];
- id frameworksRaw = [filter isKindOfClass:[NSDictionary class]] ? filter[@"Frameworks"] : nil;
-
- if ([frameworksRaw isKindOfClass:[NSArray class]] &&
- [(NSArray *)frameworksRaw count] > 0) {
- // Universal: schedule in every process. No-op in processes
- // where the named framework never loads.
- TLScheduleFrameworkTweak(dylibPath, (NSArray *)frameworksRaw);
- continue;
- }
-
- // Non-framework-filtered: keep the .app/+allowlist gate.
- if (!processAllowed) continue;
- if (!TLFilterMatches(filter, bundleID, executableName)) continue;
-
- void *handle = dlopen(dylibPath.fileSystemRepresentation, RTLD_NOW | RTLD_GLOBAL);
- if (handle) {
- TLLog(@"Loaded %@ (exec=%@ bundle=%@)", dylibPath, executableName, bundleID);
- } else {
- const char *err = dlerror();
- TLLog(@"Failed to load %@: %s", dylibPath, err ?: "unknown error");
- }
- } @catch (NSException *e) {
- TLLog(@"Exception loading %@: %@", dylibPath, e);
- }
- }
-}
-
-__attribute__((constructor))
-static void TweakLoaderInit(void) {
- @autoreleasepool {
- static dispatch_once_t onceToken;
- dispatch_once(&onceToken, ^{
- TLLoadTweaks();
- });
- }
-}