Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Revert "Add minimal vphone launchd hook and inert system hook"

Lakr924a9af55498
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index dbf1608e..6107315c 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -2,33 +2,12 @@
> **Current product scope (September 2026):** the tables below preserve the
> historical patch comparison. The public runtime now exposes only JB. Guest
-> package managers, Procursus, and first-boot package setup are outside this
-> repository. The native Swift JB install retains the base system patches,
+> package managers, Procursus, BaseBin hooks, 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, mandatory vphoned, and the small vphone launchd hook described
-> below. Old variant rows are research history,
+> edit, GPU driver, and mandatory vphoned. 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 fd8324b7..9fd86de5 100644
--- a/Research/Host/runtime_dependency_tiers.md
+++ b/Research/Host/runtime_dependency_tiers.md
@@ -63,10 +63,8 @@ that does not work on a clean Mac.
### The compile/install split
-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
+Five Mach-Os run inside the guest: `vphoned`, `TweakLoader.dylib`,
+`vpregister`, `libvcamcaptured.dylib`, `libcamfix.dylib`. Every one 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.
@@ -81,9 +79,10 @@ 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.
-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.
+`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`).
---
diff --git a/Scripts/check_aux.sh b/Scripts/check_aux.sh
index eda9dc19..995d6c0f 100755
--- a/Scripts/check_aux.sh
+++ b/Scripts/check_aux.sh
@@ -21,7 +21,7 @@ file_copy_spawns="$(/usr/bin/find "$root/VPhoneExecutable" "$root/VPhoneKit" \
for name in vphone-vm vphone-cli VPhoneEscalator vphoned vphoned.signed \
libswiftCompatibilitySpan.vphone.dylib libcamfix.dylib libvcamcaptured.dylib \
- launchdhook-vphone.dylib SystemHook-vphone.dylib \
+ TweakLoader.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 a44ecf2d..bba898aa 100644
--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneCustomFirmwareInstaller.swift
@@ -219,14 +219,12 @@ 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.") {
@@ -327,26 +325,6 @@ 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,
@@ -354,7 +332,6 @@ struct VPhoneCustomFirmwareInstaller {
verb: String,
identifier: String? = nil,
preserveEntitlements: Bool = false,
- injectedDylibPath: String? = nil,
) throws {
let target = system.appendingPathComponent(path)
let backup = target.appendingPathExtension("bak")
@@ -370,9 +347,6 @@ 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 354aca68..94663486 100755
--- a/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
+++ b/VPhoneExecutable/VPhoneVirtualization/Build/StageBundle.sh
@@ -58,8 +58,7 @@ 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/launchhook/launchdhook-vphone.dylib" "$macos/launchdhook-vphone.dylib"
-/bin/cp "$guest_products/systemhook/SystemHook-vphone.dylib" "$macos/SystemHook-vphone.dylib"
+/bin/cp "$guest_products/tweakloader/TweakLoader.dylib" "$macos/TweakLoader.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
deleted file mode 100644
index 901b9286..00000000
--- a/VPhoneGuestComponents/LaunchHook/launchdhook-vphone.c
+++ /dev/null
@@ -1,183 +0,0 @@
-#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 62c42d7d..549028f1 100644
--- a/VPhoneGuestComponents/Makefile
+++ b/VPhoneGuestComponents/Makefile
@@ -5,8 +5,7 @@ OUT := $(abspath ../.build/siblings)
STAGE := $(OUT)/stage
ARCHIVE := $(OUT)/siblings.tar
CLANG := xcrun --sdk iphoneos clang
-GUEST_C_FLAGS := -arch arm64e -miphoneos-version-min=26.0 -Os
-COMMON_FLAGS := $(GUEST_C_FLAGS) -fobjc-arc
+COMMON_FLAGS := -arch arm64e -miphoneos-version-min=26.0 -Os -fobjc-arc
CAMFIX := $(STAGE)/camfix/libcamfix.dylib
VCAMCAPTURED := $(STAGE)/vcamcaptured/libvcamcaptured.dylib
@@ -21,10 +20,9 @@ VCAMCAPTURED_SOURCES := VCamCaptured/libvcamcaptured.m \
VCamCaptured/VCamStillSink.inc \
VCamCaptured/VCamFrameReceiver.inc \
VCamCaptured/VCamFrameProtocol.h
-LAUNCHHOOK := $(STAGE)/launchhook/launchdhook-vphone.dylib
-SYSTEMHOOK := $(STAGE)/systemhook/SystemHook-vphone.dylib
+TWEAKLOADER := $(STAGE)/tweakloader/TweakLoader.dylib
GPU_PLUGIN := $(STAGE)/gpu/libAppleParavirtCompilerPluginIOGPUFamily.dylib
-ARTIFACTS := $(CAMFIX) $(VCAMCAPTURED) $(LAUNCHHOOK) $(SYSTEMHOOK) $(GPU_PLUGIN)
+ARTIFACTS := $(CAMFIX) $(VCAMCAPTURED) $(TWEAKLOADER) $(GPU_PLUGIN)
PLISTS := $(STAGE)/camfix/libcamfix.plist $(STAGE)/vcamcaptured/libvcamcaptured.plist
GPU_PROVENANCE := $(STAGE)/gpu/README.md
@@ -36,10 +34,10 @@ gpu: $(GPU_PLUGIN)
package: all
@rm -f $(ARCHIVE)
- @/usr/bin/tar -cf $(ARCHIVE) -C $(STAGE) camfix vcamcaptured launchhook systemhook gpu
+ @/usr/bin/tar -cf $(ARCHIVE) -C $(STAGE) camfix vcamcaptured tweakloader gpu
@echo "Packaged $(ARCHIVE)"
-$(STAGE)/camfix $(STAGE)/vcamcaptured $(STAGE)/launchhook $(STAGE)/systemhook $(STAGE)/gpu:
+$(STAGE)/camfix $(STAGE)/vcamcaptured $(STAGE)/tweakloader $(STAGE)/gpu:
@mkdir -p $@
$(CAMFIX): CamFix/libcamfix.m VCamCaptured/VCamFrameProtocol.h | $(STAGE)/camfix
@@ -58,16 +56,10 @@ $(VCAMCAPTURED): $(VCAMCAPTURED_SOURCES) | $(STAGE)/vcamcaptured
-framework Foundation -framework CoreMedia -framework CoreVideo
@codesign --force --sign - $@
-$(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 $@ $<
+$(TWEAKLOADER): TweakLoader/TweakLoader.m | $(STAGE)/tweakloader
+ $(CLANG) $(COMMON_FLAGS) -dynamiclib \
+ -install_name /var/jb/usr/lib/TweakLoader.dylib \
+ -o $@ $< -framework Foundation
@codesign --force --sign - $@
$(GPU_PLUGIN): GraphicLoader/main.mm | $(STAGE)/gpu
diff --git a/VPhoneGuestComponents/README.md b/VPhoneGuestComponents/README.md
index 975e6959..c63ee6da 100644
--- a/VPhoneGuestComponents/README.md
+++ b/VPhoneGuestComponents/README.md
@@ -1,21 +1,19 @@
# Sibling guest components
-`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:
+`make -C VPhoneGuestComponents 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:
| Component | Archive contents |
| --- | --- |
| Camera app hook | `camfix/libcamfix.dylib`, `camfix/libcamfix.plist` |
| Camera daemon hook | `vcamcaptured/libvcamcaptured.dylib`, `vcamcaptured/libvcamcaptured.plist` |
-| Launchd hook | `launchhook/launchdhook-vphone.dylib` |
-| Reserved process hook | `systemhook/SystemHook-vphone.dylib` |
+| Tweak loader | `tweakloader/TweakLoader.dylib` |
| 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 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
+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
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
deleted file mode 100644
index 967ae6f2..00000000
--- a/VPhoneGuestComponents/SystemHook/SystemHook-vphone.c
+++ /dev/null
@@ -1,3 +0,0 @@
-// 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
new file mode 100644
index 00000000..e5f4fe1a
--- /dev/null
+++ b/VPhoneGuestComponents/TweakLoader/README.md
@@ -0,0 +1,25 @@
+# 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
new file mode 100644
index 00000000..88ec62c7
--- /dev/null
+++ b/VPhoneGuestComponents/TweakLoader/TweakLoader.m
@@ -0,0 +1,291 @@
+#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();
+ });
+ }
+}