Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

feat(cfw-kit): bring the variant-layered installer kit into the repo

Lakr1dac63eb591e
diff --git a/cfw-kit/README.md b/cfw-kit/README.md
new file mode 100644
index 00000000..a6c58893
--- /dev/null
+++ b/cfw-kit/README.md
@@ -0,0 +1,113 @@
+# custom-firmware-kit
+
+Two independently buildable CFW environments for vphone-cli guests, sharing one
+base install path.
+
+| | vanilla | jb |
+| --- | --- | --- |
+| goal | boots to SpringBoard, nothing else | jailbroken kernel, empty userland |
+| boot chain | `make fw_patch` (52 patches) | `make fw_patch_jb` (**127 patches**) |
+| SSH / VNC / RPC | none | none (slot's job) |
+| daemons added | none | none |
+| `launchd.plist` | untouched | untouched |
+| userland | yours to design | slot: `rootless` / `roothide`, both empty |
+
+The kit does **not** fork the Python patchers. It calls the repo's
+`scripts/patchers/cfw.py`, so patch behaviour cannot drift from upstream.
+It does not modify the vphone-cli repo at all.
+
+## Use
+
+```sh
+# boot chain first — the kit only does the filesystem layer
+cd ~/Documents/GitHub/Lakr233/vphone-cli && make fw_patch # or fw_patch_jb
+
+# then, with the VM restored and POWERED OFF
+~/Desktop/custom-firmware-kit/run.sh --variant vanilla /path/to/vm
+~/Desktop/custom-firmware-kit/run.sh --variant jb /path/to/vm
+```
+
+`run.sh` re-execs itself under `sudo` (owners-honoured mounts need root),
+attaches `Disk.img`, runs the variant installer against the mounted volumes,
+then flips the boot snapshot offline via the repo's `tools/apfs_snap_rename.py`.
+
+Check what would happen without touching anything — **no root, no attach, no
+writes**:
+
+```sh
+KIT_CHECK_ONLY=1 ./run.sh --variant jb
+```
+
+### Knobs
+
+| variable | default | effect |
+| --- | --- | --- |
+| `JB_USERLAND` | `none` | `rootless` \| `roothide`; jb only. Both slots are empty, so anything but `none` is currently a hard error *before* the image is attached |
+| `VANILLA_LSD_EMBEDDED_REG` | `0` | vanilla, 27 bases: open lsd's JB app-registration path |
+| `FORCE_DSC_MAXSLIDE` | `0` | zero maxSlide on non-27 bases (normally self-gated to a no-op) |
+| `KIT_CHECK_ONLY` | `0` | preflight and stop |
+| `VPHONE_REPO` / `--repo` | auto | vphone-cli checkout to take `cfw.py` and resources from |
+| `VPHONE_DROP_ARTIFACTS` | `0` | delete the extracted `cfw_input/` afterwards |
+
+## Layout
+
+```
+run.sh host driver: attach, dispatch, snapshot flip
+lib/common.sh helpers lifted from upstream cfw_install.sh + preflight
+lib/base_stages.sh the stages both variants need
+vanilla/install.sh minimal boot
+jb/install.sh + jetsam guard, debugserver, Campo, two slot hooks
+jb/userland/ empty slots (rootless, roothide) + how to fill them
+docs/phase-matrix.md every upstream phase → variant, with evidence
+```
+
+`../paravirt-gpu-provenance-kit/` is separate and unchanged. It documents where
+the two binaries in the GPU bundle come from; this kit only installs them.
+
+## Design notes
+
+**Preflight is the only safety net.** The installer streams onto a mounted
+volume with no snapshot to roll back to, so everything that can fail is checked
+before the first write: tools, Python deps, and every `cfw.py` subcommand this
+variant *and its userland slot* will call. A userland flavour is sourced before
+preflight precisely so its requirements get checked too.
+
+**`umount` is never forced.** If something still holds a file on the volume the
+kit wants to hear about it, not paper over it with `umount -f`
+(`lib/base_stages.sh`).
+
+**Why vanilla drops `launchd_cache_loader`.** That patch exists only to let
+launchd accept a modified `launchd.plist`, and upstream's phase 7/7
+(`inject-daemons`) is the only thing that modifies it. Vanilla installs no
+daemons, so the patch has nothing to enable and stock validation passes
+untouched. A userland flavour that *does* rewrite `launchd.plist` must declare
+`USERLAND_MODIFIES_LAUNCHD_PLIST=1`, which re-arms the patch automatically.
+Full reasoning in `docs/phase-matrix.md`.
+
+## Verification status — read this before trusting the kit
+
+Done, and repeatable:
+
+- `zsh -n` on all five scripts
+- `KIT_CHECK_ONLY=1` preflight actually executed for both variants, and for
+ vanilla with the lsd flag on — all pass on this host
+- all 12 `cfw.py` subcommands the kit can call confirmed present
+- payload paths confirmed present: `cfw_input/signcert.p12`,
+ `cfw_input/custom/AppleParavirtGPUMetalIOGPUFamily.tar`,
+ `campo_mach_lookup_exceptions.py`, `tools/apfs_snap_rename.py`
+- slot contract exercised with a throwaway flavour: `REQUIRED_CFW_SUBCOMMANDS`
+ appends reach preflight, `USERLAND_MODIFIES_LAUNCHD_PLIST=1` pulls in
+ `patch-launchd-cache-loader`, and a flavour demanding a nonexistent
+ subcommand is rejected with nothing written
+- `run.sh` error paths: missing `--variant`, unknown variant, unknown
+ `JB_USERLAND`, empty slot
+
+**Not done — no VM was available on the authoring host:**
+
+- no real install has ever run
+- **no guest has ever booted from either variant**
+- whether vanilla actually reaches SpringBoard is a static inference from
+ upstream's code and the research docs, not a measurement
+
+Treat the phase matrix as a reviewed argument, not a test result. The first real
+run should be vanilla on a 26.x base, where the fewest version gates fire.
diff --git a/cfw-kit/docs/phase-matrix.md b/cfw-kit/docs/phase-matrix.md
new file mode 100644
index 00000000..cd6fe49b
--- /dev/null
+++ b/cfw-kit/docs/phase-matrix.md
@@ -0,0 +1,100 @@
+# Phase matrix — what each variant installs, and why
+
+Every row of upstream's installers, mapped onto this kit's two variants with the
+evidence for the decision. This table is the only auditable form of the claim
+"vanilla still boots".
+
+Derived against:
+
+| file | sha256 |
+| --- | --- |
+| `scripts/cfw_install.sh` | `7d71137763c47e9ac19a1199a97132f0e8990d4c9e8ff0f82e9719cd10e0373b` |
+| `scripts/cfw_install_jb.sh` | `5c6c064b2aacce540a4dac15660cb3ec709e07f85d62a0ab49c331a91b062c74` |
+| `scripts/cfw_install_host.sh` | `6c84d50b65c37404ca6ab423b6d22b5a69aba27d063da37d7ae0fc682175aa78` |
+
+vphone-cli HEAD `6d5ce7d49b4574859c57c66dff26c5c02bcae6ba`, branch
+`qof-update-26-fall`, 2026-09-23. **If any hash has moved, re-diff before
+trusting this table.**
+
+Note `cfw_install_jb.sh:43` runs `cfw_install.sh` first, so upstream "jb" means
+regular + the JB phases. This kit does not chain; both variants call the same
+stage functions in `lib/base_stages.sh` directly.
+
+---
+
+## `cfw_install.sh` (regular, 7 phases)
+
+| upstream | vanilla | jb | why |
+| --- | :-: | :-: | --- |
+| Cryptex SystemOS + AppOS + dyld symlinks (`:214`) | ✅ | ✅ | the hybrid firmware has a boot chain and no userland without it |
+| IOMFB SwapEnd 0x560 — 26.0/18.x (`:331`) | ✅ | ✅ | version-gated; without it the VZ view is black |
+| IOMFB force-kern — 27.x (`:336`) | ✅ | ✅ | same, 27's path |
+| DSC maxSlide — 27.x (`:364`) | ✅ | ✅ | 27's cache + 512 MiB slide overflows the 6 GiB shared region → dyld cannot map libSystem → **pid 1 panics** |
+| lsd embedded-reg — 27.x (`:366`) | ⬜ opt-in | ✅ | upstream `:348-351`: exists so the **`vpregister` first-boot tool** can register JB apps, because 27's `registerApplicationDictionary` is a stub. Nothing walks that path without such a tool. `VANILLA_LSD_EMBEDDED_REG=1` to force. |
+| libxpc LWCR self-check — 27.x (`:368`) | ✅ | ✅ | 27's libxpc brk-aborts on the (matched=0, MATCH) pair our signing produces → every entitlement-pinning daemon crash-loops |
+| `os_lockdown_mode_enabled` — 27.x (`:370`) | ✅ | ✅ | missing MAC sysctl → launchd abort |
+| **2/7** seputil (`:383`) | ✅ | ✅ | SEP rejects the volume without the gigalocker UUID rename |
+| diskimagesiod DDI gate — 27.x (`:407`) | ✅ | ✅ | **applied by upstream's regular variant too**, not a JB extra: `waitForDAMount` otherwise hangs forever on the 26.4 hybrid. Version-gated exactly as upstream. |
+| gigalocker rename (`:423`) | ✅ | ✅ | part of the same SEP requirement |
+| **3/7** AppleParavirtGPU bundle (`:431`) | ✅ | ✅ | backboardd crash loop / black SpringBoard without it. Provenance: `../paravirt-gpu-provenance-kit` |
+| **4/7** iosbinpack64 (`:453`) | ❌ | ❌ | this is where bash/dropbear/SSH live. vanilla: explicitly excluded ("不给 ssh"). jb: belongs to the userland slot |
+| **5/7** launchd_cache_loader (`:468`) | ❌ | ⬜ slot | **proven dead, not merely unnecessary.** `research/0_binary_patch_comparison.md:183` states its purpose is "Allow modified `launchd.plist`", and `cfw_install.sh:567` (`inject-daemons`) is the **only** writer of that file in the whole installer. Drop 7/7 and the patch has nothing to enable. Re-armed automatically when a slot sets `USERLAND_MODIFIES_LAUNCHD_PLIST=1`. |
+| **6/7** mobileactivationd (`:486`) | ✅ | ✅ | otherwise the guest sits on the activation screen forever |
+| **7/7** vphoned + 4 daemon plists + `launchd.plist` injection (`:504-569`) | ❌ | ⬜ slot | vphoned is host↔guest control, not a boot requirement. The plists are bash/dropbear/trollvnc/rpcserver_ios — exactly the "什么都不给" list |
+
+## `cfw_install_jb.sh` (JB phases)
+
+| upstream | vanilla | jb | why |
+| --- | :-: | :-: | --- |
+| **JB-1** launchd jetsam guard (`:244`) | ❌ | ✅ | without it pid 1 panics on boot under the JB kernel patches. Flavour-independent |
+| **JB-1** launchdhook `/b` injection (`:237-242`) | ❌ | ⬜ slot | BaseBin-specific → `userland_launchd_hook` |
+| **JB-2** iosbinpack64 (`:259`) | ❌ | ❌ | same as 4/7 |
+| **JB-3** debugserver entitlements (`:271`) | ❌ | ✅ | flavour-independent, and a debugger is the point of a research JB |
+| **JB-3b** Campo mach-lookup, 27 only (`:293`) | ❌ | ✅ | flavour-independent sandbox fix |
+| **JB-4** procursus bootstrap (`:317`) | ❌ | ⬜ slot | rootless and roothide disagree on the prefix — this IS the divergence |
+| **JB-4** BaseBin → `/cores` (`:378`) | ❌ | ⬜ slot | flavour-specific dylibs |
+| **JB-4** TweakLoader (`:411`) | ❌ | ⬜ slot | flavour-specific |
+| **JB-5** first-boot setup + `launchd.plist` injection (`:423-471`) | ❌ | ⬜ slot | Sileo/apt/TrollStore finalization; also the thing that makes launchd_cache_loader necessary again |
+
+Legend: ✅ installed · ❌ not installed · ⬜ left to the userland slot or an opt-in flag
+
+---
+
+## Divergences from upstream worth knowing
+
+1. **No chaining.** Upstream jb re-runs the whole regular installer. Here both
+ variants call shared stage functions, so the base path cannot drift between
+ them — but it also means this kit's jb is *not* byte-identical to upstream's
+ jb even before the empty slot is accounted for.
+
+2. **`patch_rootfs_binary` helper.** Upstream open-codes the
+ backup → patch → sign → copy → chmod sequence in four places. Same
+ semantics, one helper (`lib/common.sh`). diskimagesiod and launchd still
+ open-code it because their entitlements must survive the re-sign.
+
+3. **`detect_ios_version` is explicit.** Upstream sets `IOS_VERSION` as a side
+ effect of the display-fix block, which makes the stage order silently
+ load-bearing. Here it is set once, on purpose, right after the Cryptex lands
+ (`SystemVersion.plist` does not exist before that).
+
+4. **Preflight before any write.** Upstream discovers a missing `zstd` or a
+ stale `cfw.py` partway through a streaming install onto a volume with no
+ snapshot to roll back to. `preflight()` checks tools, Python deps and every
+ `cfw.py` subcommand the selected variant *and its userland slot* will call,
+ then refuses with nothing written.
+
+5. **`run.sh` requires `--variant`.** Upstream `cfw_install_host.sh` defaults to
+ `exp`. Defaulting to either variant here would hand someone a firmware they
+ did not ask for.
+
+6. **`cfw_input/` is kept.** Upstream deletes it for `make` idempotence; opt in
+ with `VPHONE_DROP_ARTIFACTS=1`.
+
+## What this table does not tell you
+
+Nothing here was verified by booting a guest. Every ✅ and ❌ is read off
+upstream's code and comments plus the research docs. The two rows most likely to
+be wrong in practice are the two where this kit *removes* something upstream
+always installs — 4/7 and 7/7 — and their failure mode is a guest that boots to
+a black screen or a login-less shell you cannot reach, because vanilla
+deliberately ships no way in.
diff --git a/cfw-kit/jb/install.sh b/cfw-kit/jb/install.sh
new file mode 100755
index 00000000..60d48c3e
--- /dev/null
+++ b/cfw-kit/jb/install.sh
@@ -0,0 +1,243 @@
+#!/bin/zsh
+# jb/install.sh — fully patched firmware, empty userland.
+#
+# The firmware layer is jailbroken all the way: run `make fw_patch_jb` first and
+# all 127 JB boot-chain patches (iBoot / kernel / TXM / DSC) are already in the
+# images this installs onto. This script then applies the FILESYSTEM-layer JB
+# work that does not depend on which userland flavour you eventually pick.
+#
+# The userland is deliberately EMPTY. No BaseBin hooks, no procursus bootstrap,
+# no Sileo, no TweakLoader, no first-boot setup. Two flavours are planned —
+# rootless and roothide — and they disagree about where things live, so the kit
+# ships the interface and neither implementation. See userland/README.md.
+#
+# installed here left empty (slot)
+# ───────────────────────────────── ──────────────────────────────
+# everything vanilla installs BaseBin hooks -> /cores
+# launchd jetsam guard /b launchdhook alias + injection
+# debugserver entitlements procursus bootstrap
+# Campo mach-lookup fix (iOS 27) Sileo / apt / TrollStore
+# iOS-27 JB DSC + DDI patches TweakLoader
+# first-boot setup daemon
+#
+# Usage: ../run.sh --variant jb [vm_dir]
+# JB_USERLAND=rootless|roothide|none (default: none)
+# Contract: root, VM off, CFW_HOST_CONTAINER set, $1 = VM dir.
+set -euo pipefail
+
+KIT_DIR="${0:a:h:h}"
+source "$KIT_DIR/lib/common.sh"
+source "$KIT_DIR/lib/base_stages.sh"
+
+VM_DIR="$(cd "${1:-.}" && pwd)"
+CFW_INPUT="cfw_input"
+CFW_ARCHIVE="cfw_input.tar.zst"
+TEMP_DIR="$VM_DIR/.cfw_temp"
+
+JB_USERLAND="${JB_USERLAND:-none}"
+FORCE_DSC_MAXSLIDE="${FORCE_DSC_MAXSLIDE:-0}"
+
+REQUIRED_CFW_SUBCOMMANDS=(
+ cryptex-paths
+ patch-seputil
+ patch-mobileactivationd
+ patch-iomfb-swapend
+ patch-iomfb-force-kern
+ patch-dsc-maxslide
+ patch-xpc-lwcr
+ patch-lockdown-mode
+ patch-lsd-embedded-reg
+ patch-diskimagesiod
+ patch-launchd-jetsam
+)
+
+REPO_DIR="$(resolve_repo)"
+PYTHON3="$(resolve_python3)"
+init_paths
+
+cleanup_on_exit() {
+ safe_detach "$TEMP_DIR/mnt_sysos" 2>/dev/null || true
+ safe_detach "$TEMP_DIR/mnt_appos" 2>/dev/null || true
+}
+trap cleanup_on_exit EXIT
+
+echo "[*] custom-firmware-kit — variant: jb (all firmware patches, empty userland)"
+echo "[+] repo: $REPO_DIR"
+echo "[+] vm: $VM_DIR"
+
+# ── Userland slot ───────────────────────────────────────────────
+# Loaded BEFORE anything is written so a flavour can register hooks and so a
+# missing/broken slot fails before the volume is touched.
+USERLAND_DIR=""
+if [[ "$JB_USERLAND" != "none" ]]; then
+ USERLAND_DIR="$KIT_DIR/jb/userland/$JB_USERLAND"
+ [[ -d "$USERLAND_DIR" ]] || die "unknown JB_USERLAND '$JB_USERLAND' (expected a dir at $USERLAND_DIR)"
+ if [[ -f "$USERLAND_DIR/install.sh" ]]; then
+ echo "[+] userland flavour: $JB_USERLAND"
+ source "$USERLAND_DIR/install.sh"
+ else
+ die "JB_USERLAND=$JB_USERLAND but $USERLAND_DIR/install.sh does not exist yet.
+ The userland slots are intentionally empty in this kit — see jb/userland/README.md.
+ Use JB_USERLAND=none to install the firmware layer only."
+ fi
+else
+ echo "[+] userland flavour: none (slot left empty — firmware layer only)"
+fi
+
+# A flavour that rewrites launchd.plist needs the cache-validation NOP too;
+# fold it into the preflight list so a missing subcommand is caught before any
+# write rather than halfway through the install.
+if [[ "${USERLAND_MODIFIES_LAUNCHD_PLIST:-0}" == "1" ]]; then
+ echo "[+] slot declares it modifies launchd.plist — launchd_cache_loader patch enabled"
+ REQUIRED_CFW_SUBCOMMANDS+=(patch-launchd-cache-loader)
+fi
+
+preflight
+[[ "${KIT_CHECK_ONLY:-0}" == "1" ]] && { echo "[+] check-only: stopping before any write"; exit 0; }
+
+RESTORE_DIR=$(find_restore_dir)
+echo "[+] Restore directory: $RESTORE_DIR"
+
+setup_cfw_input
+INPUT_DIR="$VM_DIR/$CFW_INPUT"
+echo "[+] Input resources: $INPUT_DIR"
+require_signing_tools
+
+mkdir -p "$TEMP_DIR"
+
+echo ""
+echo "[*] Parsing iPhone BuildManifest for Cryptex paths..."
+CRYPTEX_PATHS=$(cfw_py cryptex-paths "$RESTORE_DIR/iPhone-BuildManifest.plist")
+CRYPTEX_SYSOS=$(echo "$CRYPTEX_PATHS" | head -1)
+CRYPTEX_APPOS=$(echo "$CRYPTEX_PATHS" | tail -1)
+echo " SystemOS: $CRYPTEX_SYSOS"
+echo " AppOS: $CRYPTEX_APPOS"
+
+# ── Base (same code path as vanilla) ────────────────────────────
+# The only difference from vanilla's base is the lsd embedded-registration
+# gate, on here because a JB userland is what needs it.
+stage_cryptex
+detect_ios_version
+stage_display_and_boot_fixes 1
+stage_seputil
+stage_gpu
+stage_mobileactivationd
+
+# Only needed if the userland slot rewrites launchd.plist. See the stage's
+# comment in lib/base_stages.sh for why this is not unconditional.
+if [[ "${USERLAND_MODIFIES_LAUNCHD_PLIST:-0}" == "1" ]]; then
+ stage_launchd_cache_loader
+else
+ echo ""
+ echo "[base] skip launchd_cache_loader (nothing modifies launchd.plist)"
+fi
+
+# ═══════════ J1 PATCH LAUNCHD (JETSAM GUARD) ══════════════════
+# The jetsam guard patch is flavour-independent: without it pid 1 panics on
+# boot under the JB kernel patches. The launchdhook dylib injection that
+# upstream also does here belongs to BaseBin, so it is exposed as a hook the
+# userland slot may implement instead of being done unconditionally.
+echo ""
+echo "[J1] Patching launchd (jetsam guard)..."
+
+if ! [[ -e "$MNT1/sbin/launchd.bak" ]]; then
+ echo " Creating backup..."
+ /bin/cp $MNT1/sbin/launchd $MNT1/sbin/launchd.bak
+fi
+cp "$MNT1/sbin/launchd.bak" "$TEMP_DIR/launchd"
+
+# Original entitlements must survive the re-sign or spawn breaks.
+echo " Extracting original entitlements..."
+ldid -e "$TEMP_DIR/launchd" > "$TEMP_DIR/launchd.entitlements" 2>/dev/null || true
+if [[ -s "$TEMP_DIR/launchd.entitlements" ]]; then
+ echo " [+] Preserved launchd entitlements"
+else
+ warn "No entitlements found on original launchd"
+fi
+
+# ── slot hook: dylib injection into pid 1 ──
+if typeset -f userland_launchd_hook >/dev/null; then
+ echo " Running userland launchd hook ($JB_USERLAND)..."
+ userland_launchd_hook "$TEMP_DIR/launchd"
+else
+ echo " [*] No userland launchd hook — pid 1 gets no injected dylib"
+fi
+
+cfw_py patch-launchd-jetsam "$TEMP_DIR/launchd"
+
+if [[ -s "$TEMP_DIR/launchd.entitlements" ]]; then
+ ldid -S"$TEMP_DIR/launchd.entitlements" -M "-K$VM_DIR/$CFW_INPUT/signcert.p12" "$TEMP_DIR/launchd"
+else
+ ldid_sign "$TEMP_DIR/launchd"
+fi
+cp -R "$TEMP_DIR/launchd" "$MNT1/sbin/launchd"
+/bin/chmod 0755 $MNT1/sbin/launchd
+
+echo " [+] launchd patched"
+
+# ═══════════ J2 DEBUGSERVER ENTITLEMENTS ══════════════════════
+echo ""
+echo "[J2] Patching debugserver entitlements..."
+
+if [[ -f "$MNT1/usr/libexec/debugserver" ]]; then
+ cp "$MNT1/usr/libexec/debugserver" "$TEMP_DIR/debugserver"
+ ldid -e "$TEMP_DIR/debugserver" > "$TEMP_DIR/debugserver-entitlements.plist"
+ plutil -remove seatbelt-profiles "$TEMP_DIR/debugserver-entitlements.plist" || true
+ plutil -insert task_for_pid-allow -bool YES "$TEMP_DIR/debugserver-entitlements.plist" || true
+ ldid_sign_ent "$TEMP_DIR/debugserver" "$TEMP_DIR/debugserver-entitlements.plist"
+ cp -R "$TEMP_DIR/debugserver" "$MNT1/usr/libexec/debugserver"
+ /bin/chmod 0755 $MNT1/usr/libexec/debugserver
+ echo " [+] debugserver entitlements patched"
+else
+ warn "debugserver not present in this OS image; skipping"
+fi
+
+# ═══════════ J3 CAMPO SANDBOX FIX (iOS 27 only) ═══════════════
+# Grants Campo the backboard/frontboard mach-lookups the 26.4 temporary sandbox
+# denies. 27-gated on the mounted rootfs SystemVersion.plist.
+CAMPO_BIN="$MNT1/Applications/Campo.app/Campo"
+case "$IOS_VERSION" in
+27.*)
+ if [[ -f "$CAMPO_BIN" ]]; then
+ echo ""
+ echo "[J3] Granting Campo backboard/frontboard mach-lookup exceptions (iOS $IOS_VERSION)..."
+ cp "$CAMPO_BIN" "$TEMP_DIR/Campo"
+ ldid -e "$TEMP_DIR/Campo" > "$TEMP_DIR/Campo.entitlements" 2>/dev/null || true
+ if [[ -s "$TEMP_DIR/Campo.entitlements" ]]; then
+ "$PYTHON3" "$REPO_DIR/scripts/patchers/campo_mach_lookup_exceptions.py" "$TEMP_DIR/Campo.entitlements"
+ ldid_sign_ent "$TEMP_DIR/Campo" "$TEMP_DIR/Campo.entitlements"
+ cp -R "$TEMP_DIR/Campo" "$CAMPO_BIN"
+ /bin/chmod 0755 "$CAMPO_BIN"
+ echo " [+] Campo re-signed"
+ else
+ warn "Could not read Campo entitlements; skipping Campo sandbox fix"
+ fi
+ else
+ echo "[J3] Campo.app not present in this OS image; skipping"
+ fi
+ ;;
+*)
+ echo "[J3] skip Campo sandbox fix (base iOS ${IOS_VERSION:-unknown} — 27-only)"
+ ;;
+esac
+
+# ═══════════ J4 USERLAND SLOT ═════════════════════════════════
+echo ""
+if typeset -f userland_install >/dev/null; then
+ echo "[J4] Installing userland flavour: $JB_USERLAND..."
+ userland_install
+ echo " [+] userland installed"
+else
+ echo "[J4] Userland slot is empty — nothing installed."
+ echo " No /cores hooks, no bootstrap, no package manager, no tweak loader."
+ echo " Fill jb/userland/{rootless,roothide}/install.sh to change that."
+fi
+
+stage_unmount
+
+echo ""
+echo "[+] jb CFW installation complete (firmware layer fully patched)."
+if ! typeset -f userland_install >/dev/null; then
+ echo " Userland slot empty: the guest boots a jailbroken KERNEL with a"
+ echo " stock userland. That is expected for JB_USERLAND=none."
+fi
diff --git a/cfw-kit/jb/userland/README.md b/cfw-kit/jb/userland/README.md
new file mode 100644
index 00000000..543a91c4
--- /dev/null
+++ b/cfw-kit/jb/userland/README.md
@@ -0,0 +1,63 @@
+# JB userland slot
+
+Both flavour directories here are **empty on purpose**. `jb/install.sh` installs
+the firmware and filesystem layers; everything above that — BaseBin hooks, the
+procursus bootstrap, a package manager, a tweak loader, a first-boot setup
+daemon — is left to a flavour, because rootless and roothide disagree about
+where any of it lives.
+
+With no flavour selected the guest boots a **jailbroken kernel under a stock
+userland**. That is a valid, deliberate end state, not a half-finished install.
+
+> The authoritative hook contract — exact call sites, variables in scope,
+> available helpers, and the two declarations a flavour must make — is
+> **§10 of `~/Desktop/vphone-cli-migration-plan.md`**. This page is only how to
+> drive it. If the two ever disagree, the plan wins.
+
+## Selecting a flavour
+
+```sh
+JB_USERLAND=rootless ../../run.sh --variant jb /path/to/vm
+```
+
+`JB_USERLAND` is `none` by default. Naming a flavour whose directory has no
+`install.sh` is a hard error raised **before the disk image is attached**, so a
+half-built flavour cannot leave a half-modified volume behind.
+
+## Adding one
+
+Drop an `install.sh` in `rootless/` or `roothide/`. It is **sourced**, not
+executed, so it must define functions rather than run work at the top level.
+Two optional hooks:
+
+| function | when it runs |
+| --- | --- |
+| `userland_launchd_hook <workfile>` | on the launchd work copy, after its entitlements are saved and before the jetsam patch and re-sign |
+| `userland_install` | after J3, with the volumes still mounted, just before unmount |
+
+Top-level statements run at source time — before `preflight`, before anything is
+written. That is where a flavour declares what it needs:
+
+```zsh
+# checked by preflight, before the first write
+REQUIRED_CFW_SUBCOMMANDS+=(inject-dylib)
+
+# if you rewrite /System/Library/xpc/launchd.plist you MUST set this, or
+# launchd will refuse the modified plist and the guest will not boot
+USERLAND_MODIFIES_LAUNCHD_PLIST=1
+```
+
+## Payloads already in the repo
+
+`scripts/resources/cfw_jb_input.tar.zst` carries a rootless-shaped set:
+
+- `basebin/launchdhook.dylib`, `basebin/libellekit.dylib`, `basebin/systemhook.dylib`
+- `jb/bootstrap-iphoneos-arm64.tar.zst`
+- `jb/org.coolstar.sileo_2.5.1_iphoneos-arm64.deb`
+
+None of these are Apple binaries — they are ElleKit/Dopamine-derived, so the
+provenance question that applies to the GPU bundle does not apply here.
+
+**roothide has no payload in this repo.** A roothide flavour has to bring its
+own BaseBin; the dylibs above are built for rootless path assumptions and
+will not work unmodified.
diff --git a/cfw-kit/jb/userland/roothide/.gitkeep b/cfw-kit/jb/userland/roothide/.gitkeep
new file mode 100644
index 00000000..e6b96d95
--- /dev/null
+++ b/cfw-kit/jb/userland/roothide/.gitkeep
@@ -0,0 +1,3 @@
+# Empty slot. Add install.sh here to implement the roothide flavour.
+# Hook contract: ../README.md, and §10 of vphone-cli-migration-plan.md.
+# Note: no roothide BaseBin ships in the repo; bring your own.
diff --git a/cfw-kit/jb/userland/rootless/.gitkeep b/cfw-kit/jb/userland/rootless/.gitkeep
new file mode 100644
index 00000000..2b635298
--- /dev/null
+++ b/cfw-kit/jb/userland/rootless/.gitkeep
@@ -0,0 +1,2 @@
+# Empty slot. Add install.sh here to implement the rootless flavour.
+# Hook contract: ../README.md, and §10 of vphone-cli-migration-plan.md.
diff --git a/cfw-kit/run.sh b/cfw-kit/run.sh
new file mode 100755
index 00000000..bc8b338d
--- /dev/null
+++ b/cfw-kit/run.sh
@@ -0,0 +1,172 @@
+#!/bin/zsh
+# run.sh — host driver for the custom-firmware-kit variant installers.
+#
+# Attaches the VM's Disk.img on the host, hands the APFS container to the
+# variant installer (vanilla/ or jb/), then flips the boot snapshot offline so
+# the VM boots the live volume.
+#
+# Derived from vphone-cli's scripts/cfw_install_host.sh. Everything to do with
+# root, attach and the snapshot flip is kept verbatim — those are the parts
+# that are easy to get subtly wrong and impossible to notice until a guest
+# fails to boot. Upstream at the time of derivation:
+# scripts/cfw_install_host.sh
+# sha256 6c84d50b65c37404ca6ab423b6d22b5a69aba27d063da37d7ae0fc682175aa78
+# vphone-cli HEAD 6d5ce7d49b4574859c57c66dff26c5c02bcae6ba (2026-09-23)
+# If upstream's hash has moved, diff it before trusting this script.
+#
+# Prereqs: VM restored and POWERED OFF; for the jb variant the boot chain must
+# already carry the 127 JB patches (`make fw_patch_jb`). Host needs gnu-tar,
+# zstd, ipsw, aea, ldid and the project venv (`make setup_tools`).
+#
+# Usage:
+# ./run.sh --variant vanilla|jb [--repo <vphone-cli>] [vm_dir]
+#
+# JB_USERLAND=rootless|roothide|none jb only; default none (empty slot)
+# VANILLA_LSD_EMBEDDED_REG=1 vanilla only; opens lsd's JB app
+# registration path on a 27 base
+# FORCE_DSC_MAXSLIDE=1 force maxSlide=0 on non-27 bases
+# KIT_CHECK_ONLY=1 preflight only; never attaches the image
+# VPHONE_KEEP_ARTIFACTS=1 keep the extracted cfw_input/ (default: kept)
+set -euo pipefail
+
+KIT_DIR="${0:a:h}"
+
+VARIANT=""
+VM_DIR=""
+REPO_ARG="${VPHONE_REPO:-}"
+
+usage() {
+ /bin/cat >&2 <<'USAGE'
+usage: run.sh --variant vanilla|jb [--repo <vphone-cli checkout>] [vm_dir]
+
+ vanilla minimal boot: Cryptex, dyld links, display/boot fixes, seputil,
+ GPU bundle, activation bypass. No daemons, no SSH, no jailbreak.
+ jb the above plus the filesystem-layer jailbreak work. Userland slot
+ is empty unless JB_USERLAND names a flavour.
+USAGE
+ exit 2
+}
+
+while (( $# )); do
+ case "$1" in
+ --variant) [[ $# -ge 2 ]] || usage; VARIANT="$2"; shift 2 ;;
+ --repo) [[ $# -ge 2 ]] || usage; REPO_ARG="$2"; shift 2 ;;
+ -h|--help) usage ;;
+ -*) echo "[-] unknown option: $1" >&2; usage ;;
+ *) VM_DIR="$1"; shift ;;
+ esac
+done
+
+# No default variant. Upstream defaults to `exp`; defaulting to either of ours
+# would silently give someone a firmware they did not ask for.
+[[ -n "$VARIANT" ]] || { echo "[-] --variant is required (vanilla|jb)" >&2; usage; }
+case "$VARIANT" in
+ vanilla|jb) ;;
+ *) echo "[-] unknown variant: $VARIANT (vanilla|jb)" >&2; exit 1 ;;
+esac
+
+INSTALLER="$KIT_DIR/$VARIANT/install.sh"
+[[ -f "$INSTALLER" ]] || { echo "[-] missing installer: $INSTALLER" >&2; exit 1; }
+
+# resolve_repo/die live in the shared lib; don't duplicate the search order.
+source "$KIT_DIR/lib/common.sh"
+export VPHONE_REPO="$REPO_ARG"
+REPO_DIR="$(resolve_repo)" # die() inside -> non-zero -> errexit aborts here
+PROJ="$REPO_DIR"
+
+[[ -n "$VM_DIR" ]] || VM_DIR="$PROJ/vm"
+VM_DIR="${VM_DIR:a}"
+
+# Host-side install toolchain (gnu-tar/ipsw/aea/ldid/zstd + venv python).
+if [[ -n "${VPHONE_PYTHON:-}" ]]; then
+ P="$PROJ/.tools/bin:$(dirname "$VPHONE_PYTHON"):/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+else
+ P="$PROJ/.tools/bin:$PROJ/.venv/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+fi
+export PATH="$P"
+PY="${VPHONE_PYTHON:-$PROJ/.venv/bin/python3}"
+
+# Variables the installers read, forwarded explicitly. An expansion-produced
+# ${VAR:+NAME=val} is not parsed as a shell assignment, hence `env`.
+kit_env=(
+ CFW_HOST_CONTAINER="__unset__"
+ _VPHONE_PATH="$P"
+ VPHONE_REPO="$PROJ"
+ ${VPHONE_PYTHON:+VPHONE_PYTHON="$VPHONE_PYTHON"}
+ ${JB_USERLAND:+JB_USERLAND="$JB_USERLAND"}
+ ${VANILLA_LSD_EMBEDDED_REG:+VANILLA_LSD_EMBEDDED_REG="$VANILLA_LSD_EMBEDDED_REG"}
+ ${FORCE_DSC_MAXSLIDE:+FORCE_DSC_MAXSLIDE="$FORCE_DSC_MAXSLIDE"}
+)
+
+# ── check-only: never touch the image, never ask for root ───────
+# Deliberately placed BEFORE the sudo re-exec. The installers stop right after
+# preflight — before find_restore_dir and before the first mount — so nothing
+# here needs privileges, and a preflight that prompts for a password is a
+# preflight nobody runs. The container sentinel only has to satisfy
+# init_paths' :? guard; nothing dereferences it on this path.
+if [[ "${KIT_CHECK_ONLY:-0}" == "1" ]]; then
+ echo "[*] check-only: $VARIANT preflight only — no root, no attach, no writes"
+ [[ -d "$VM_DIR" ]] || { echo "[!] $VM_DIR does not exist; using it as a label only" >&2; VM_DIR="$PWD"; }
+ ( cd "$VM_DIR" && env "${kit_env[@]}" KIT_CHECK_ONLY=1 zsh "$INSTALLER" . )
+ echo "[+] check-only passed for variant=$VARIANT"
+ exit 0
+fi
+
+# Re-exec as root; owners-honored mounts + chown/cp require it.
+if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
+ exec sudo ${SUDO_ASKPASS:+-A} -E /bin/zsh "$0" \
+ --variant "$VARIANT" --repo "$PROJ" "$VM_DIR"
+fi
+unset SUDO_ASKPASS # already root: host_hdiutil/pre-step use plain sudo/hdiutil
+
+IMG="$VM_DIR/Disk.img"
+[[ -f "$IMG" ]] || { echo "[-] no Disk.img at $IMG" >&2; exit 1; }
+
+if lsof "$IMG" >/dev/null 2>&1; then
+ echo "[-] $IMG is in use — stop the VM first." >&2; exit 1
+fi
+
+echo "[*] custom-firmware-kit: variant=$VARIANT vm=$VM_DIR"
+echo "[*] repo=$PROJ"
+AO=$(hdiutil attach -nomount -imagekey diskimage-class=CRawDiskImage "$IMG" 2>/dev/null)
+BASEDISK=$(awk 'NR == 1 { print $1; exit }' <<< "$AO")
+CONT=$(diskutil info -plist "${BASEDISK}s1" | /usr/bin/plutil -extract APFSContainerReference raw -o - - 2>/dev/null || true)
+SYS=$(diskutil apfs list "$CONT" 2>/dev/null | awk '/APFS Volume Disk \(Role\):/{for(i=1;i<=NF;i++) if($i ~ /^disk[0-9]+s[0-9]+$/) dev=$i} /Name:.*System \(Case-sensitive\)/{print dev; exit}')
+[[ -n "$CONT" && -n "$SYS" ]] || { echo "[-] System volume not found in $IMG" >&2; hdiutil detach "$BASEDISK" 2>/dev/null; exit 1; }
+echo "[*] attached: container=$CONT system=$SYS"
+
+cleanup() {
+ for m in /private/tmp/cfwhost/mnt1 /private/tmp/cfwhost/mnt3 /private/tmp/cfwhost/mnt5; do
+ umount "$m" 2>/dev/null || true
+ done
+ hdiutil detach "$BASEDISK" 2>/dev/null || diskutil eject "$BASEDISK" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+kit_env[1]="CFW_HOST_CONTAINER=$CONT"
+
+echo "[*] running $VARIANT/install.sh (files placed on host mounts)..."
+( cd "$VM_DIR" && env "${kit_env[@]}" zsh "$INSTALLER" . )
+
+cleanup
+trap - EXIT
+
+echo "[*] flipping boot snapshot offline (com.apple.os.update -> live volume)..."
+[[ -x "$PY" ]] || { echo "[-] python3 not found at $PY — snapshot NOT flipped; the VM will boot the stock snapshot." >&2; exit 1; }
+"$PY" "$PROJ/tools/apfs_snap_rename.py" "$IMG"
+
+# Upstream removes the extracted cfw_input/ here for `make` idempotence. The kit
+# keeps it: re-running a variant is the normal case while designing a userland,
+# and re-extracting 7 MB every time is pure waste. Opt in to the cleanup.
+if [[ "${VPHONE_DROP_ARTIFACTS:-0}" == "1" ]]; then
+ rm -rf "${VM_DIR:?}/cfw_input"
+fi
+
+# The whole install ran as root. Hand the host-side artifacts back to the
+# invoking user so subsequent user-run steps (make boot) don't hit EPERM.
+if [[ -n "${SUDO_USER:-}" ]]; then
+ chown -R "$SUDO_USER" "$VM_DIR" 2>/dev/null || true
+ echo "[*] restored ownership of host-side artifacts to $SUDO_USER"
+fi
+
+echo "[+] $VARIANT install complete. Boot with: make boot"
diff --git a/cfw-kit/vanilla/install.sh b/cfw-kit/vanilla/install.sh
new file mode 100755
index 00000000..ef0f2ad0
--- /dev/null
+++ b/cfw-kit/vanilla/install.sh
@@ -0,0 +1,109 @@
+#!/bin/zsh
+# vanilla/install.sh — the smallest CFW that boots.
+#
+# Installs nothing you did not ask for: no SSH, no VNC, no RPC server, no
+# iosbinpack64, no vphoned, no LaunchDaemon injection, no jailbreak. The guest
+# boots to SpringBoard with working graphics, and that is the whole contract.
+# Everything else is yours to design.
+#
+# Installed, and why none of it is optional:
+# Cryptex SystemOS + AppOS the hybrid firmware has no userland without it
+# dyld symlinks dyld cannot find the shared cache otherwise
+# version-gated display fixes black screen (IOMFB) / pid-1 panic (27.x) without
+# seputil gigalocker UUID SEP rejects the volume otherwise
+# diskimagesiod (27 only) MobileStorageMounter hangs forever otherwise
+# AppleParavirtGPU bundle backboardd crash loop / black SpringBoard without
+# mobileactivationd bypass stuck on the activation screen otherwise
+#
+# Deliberately NOT installed (upstream cfw_install.sh does all of these):
+# iosbinpack64 jailbreak tool pack — bash/dropbear/SSH live here
+# launchd_cache_loader patch its ONLY purpose is to allow a MODIFIED
+# launchd.plist. We never modify it, so stock cache
+# validation passes untouched and the patch is moot.
+# launchd.plist injection no daemons -> nothing to inject
+# vphoned host<->guest control daemon; not needed to boot
+# bash / dropbear / trollvnc / rpcserver_ios plists
+#
+# Usage: ../run.sh --variant vanilla [vm_dir]
+# Contract: root, VM off, CFW_HOST_CONTAINER set, $1 = VM dir.
+set -euo pipefail
+
+KIT_DIR="${0:a:h:h}"
+source "$KIT_DIR/lib/common.sh"
+source "$KIT_DIR/lib/base_stages.sh"
+
+VM_DIR="$(cd "${1:-.}" && pwd)"
+CFW_INPUT="cfw_input"
+CFW_ARCHIVE="cfw_input.tar.zst"
+TEMP_DIR="$VM_DIR/.cfw_temp"
+
+# The lsd embedded-registration gate is the one iOS-27 DSC patch upstream
+# applies that has no effect without a jailbreak tool to use it (see
+# lib/base_stages.sh). Off here. Turn it on only if you add your own app
+# registration tool to a 27 guest.
+#
+# Note this is NOT the diskimagesiod DDI patch — that one is applied
+# unconditionally on 27, because upstream's regular variant applies it too and
+# without it MobileStorageMounter hangs.
+VANILLA_LSD_EMBEDDED_REG="${VANILLA_LSD_EMBEDDED_REG:-0}"
+FORCE_DSC_MAXSLIDE="${FORCE_DSC_MAXSLIDE:-0}"
+
+REQUIRED_CFW_SUBCOMMANDS=(
+ cryptex-paths
+ patch-seputil
+ patch-mobileactivationd
+ patch-iomfb-swapend
+ patch-iomfb-force-kern
+ patch-dsc-maxslide
+ patch-xpc-lwcr
+ patch-lockdown-mode
+ patch-diskimagesiod
+)
+[[ "$VANILLA_LSD_EMBEDDED_REG" == "1" ]] && REQUIRED_CFW_SUBCOMMANDS+=(patch-lsd-embedded-reg)
+
+REPO_DIR="$(resolve_repo)"
+PYTHON3="$(resolve_python3)"
+init_paths
+
+cleanup_on_exit() {
+ safe_detach "$TEMP_DIR/mnt_sysos" 2>/dev/null || true
+ safe_detach "$TEMP_DIR/mnt_appos" 2>/dev/null || true
+}
+trap cleanup_on_exit EXIT
+
+echo "[*] custom-firmware-kit — variant: vanilla (minimal boot)"
+echo "[+] repo: $REPO_DIR"
+echo "[+] vm: $VM_DIR"
+
+preflight
+[[ "${KIT_CHECK_ONLY:-0}" == "1" ]] && { echo "[+] check-only: stopping before any write"; exit 0; }
+
+RESTORE_DIR=$(find_restore_dir)
+echo "[+] Restore directory: $RESTORE_DIR"
+
+setup_cfw_input
+INPUT_DIR="$VM_DIR/$CFW_INPUT"
+echo "[+] Input resources: $INPUT_DIR"
+require_signing_tools
+
+mkdir -p "$TEMP_DIR"
+
+echo ""
+echo "[*] Parsing iPhone BuildManifest for Cryptex paths..."
+CRYPTEX_PATHS=$(cfw_py cryptex-paths "$RESTORE_DIR/iPhone-BuildManifest.plist")
+CRYPTEX_SYSOS=$(echo "$CRYPTEX_PATHS" | head -1)
+CRYPTEX_APPOS=$(echo "$CRYPTEX_PATHS" | tail -1)
+echo " SystemOS: $CRYPTEX_SYSOS"
+echo " AppOS: $CRYPTEX_APPOS"
+
+stage_cryptex
+detect_ios_version
+stage_display_and_boot_fixes "$VANILLA_LSD_EMBEDDED_REG"
+stage_seputil
+stage_gpu
+stage_mobileactivationd
+stage_unmount
+
+echo ""
+echo "[+] vanilla CFW installation complete."
+echo " No daemons, no SSH, no jailbreak were installed — by design."