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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.shnew file mode 100755index 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."+fidiff --git a/cfw-kit/jb/userland/README.md b/cfw-kit/jb/userland/README.mdnew file mode 100644index 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/.gitkeepnew file mode 100644index 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/.gitkeepnew file mode 100644index 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.shnew file mode 100755index 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.shnew file mode 100755index 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."