{"owner":"Lakr233","repo":"vphone-cli","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# vphone-cli\n\nVirtual iPhone boot tool using Apple's Virtualization.framework with PCC research VMs.\n\n## Quick Reference\n\n- **Build:** `make build`\n- **Boot (GUI):** `make boot`\n- **Boot (DFU):** `make boot_dfu`\n- **All targets:** `make help`\n- **Python venv:** `make setup_venv` (installs to `.venv/`, activate with `source .venv/bin/activate`)\n- **Platform:** macOS 15+ (Sequoia), SIP/AMFI disabled\n- **Language:** Swift 6.0 (SwiftPM), private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic)\n- **Python deps:** `capstone`, `keystone-engine`, `pyimg4` (see `requirements.txt`)\n\n## Workflow Rules\n\n- Do not create, read, or update `/TODO.md`.\n- Ignore `/TODO.md` if it exists locally; it is intentionally not part of the repo workflow anymore.\n- Track plan, progress, assumptions, blockers, and next actions in commit history, code comments when warranted, and current research docs instead of a repo TODO file.\n\nFor any changes applying new patches, also update research/0_binary_patch_comparison.md. Dont forget this.\n\n## Local Skills\n\n- If working on kernel analysis, symbolication lookups, or kernel patch reasoning, read `skills/kernel-analysis-vphone600/SKILL.md` first.\n- Use this skill as the default procedure for `vphone600` kernel work.\n\n## Firmware Variants\n\n| Variant          | Boot Chain     |    CFW    | Make Targets                       |\n| ---------------- | :------------: | :-------: | ---------------------------------- |\n| **Regular**      | 52 patches     | 10 phases | `fw_patch` + `cfw_install`         |\n| **Development**  | 66 patches     | 12 phases | `fw_patch_dev` + `cfw_install_dev` |\n| **Jailbreak**    | 127 patches    | 14 phases | `fw_patch_jb` + `cfw_install_jb`   |\n| **Experimental** | 141 patches    | 18 phases | `fw_patch_exp` + `cfw_install_exp` |\n\n> JB finalization (symlinks, Sileo, apt, TrollStore) runs automatically on first boot via `/cores/vphone_jb_setup.sh` LaunchDaemon. Monitor progress: `/var/log/vphone_jb_setup.log`.\n\n> EXP is a JB superset that patches the kernel and DSC to make some Apple services think the device is not a VM, while keeping VM-specific services (graphics passthrough, compute/accel fast paths) working correctly. Other variants are deliberately NOT affected by these changes.\n\nSee `research/` for detailed firmware pipeline, component origins, patch breakdowns, and boot flow documentation.\n\n## Architecture\n\n```\nMakefile                          # Single entry point — run `make help`\n\nsources/\n├── vphone.entitlements               # Private API entitlements (5 keys)\n└── vphone-cli/                       # Swift 6.0 executable (pure Swift, no ObjC)\n    ├── main.swift                    # Entry point — NSApplication + AppDelegate\n    ├── VPhoneAppDelegate.swift       # App lifecycle, SIGINT, VM start/stop\n    ├── VPhoneCLI.swift               # ArgumentParser options (no execution logic)\n    ├── VPhoneBuildInfo.swift         # Auto-generated build-time commit hash\n    │\n    │   # VM core\n    ├── VPhoneVirtualMachine.swift    # @MainActor VM configuration and lifecycle\n    ├── VPhoneHardwareModel.swift     # PV=3 hardware model via Dynamic\n    ├── VPhoneVirtualMachineView.swift # Touch-enabled VZVirtualMachineView + helpers\n    ├── VPhoneError.swift             # Error types\n    │\n    │   # Guest daemon client (vsock)\n    ├── VPhoneControl.swift           # Host-side vsock client for vphoned (length-prefixed JSON)\n    │\n    │   # Window & UI\n    ├── VPhoneWindowController.swift  # @MainActor VM window management + toolbar\n    ├── VPhoneKeyHelper.swift         # Keyboard/hardware key event dispatch to VM\n    ├── VPhoneLocationProvider.swift  # CoreLocation → guest forwarding over vsock\n    ├── VPhoneScreenRecorder.swift    # VM screen recording to file\n    │\n    │   # Menu bar (extensions on VPhoneMenuController)\n    ├── VPhoneMenuController.swift    # Menu bar controller\n    ├── VPhoneMenuKeys.swift          # Keys menu — home, power, volume, spotlight\n    ├── VPhoneMenuType.swift          # Type menu — paste ASCII text to guest\n    ├── VPhoneMenuLocation.swift      # Location menu — host location sync toggle\n    ├── VPhoneMenuConnect.swift       # Connect menu — devmode, ping, version, file browser\n    ├── VPhoneMenuInstall.swift       # Install menu — IPA installation to guest\n    ├── VPhoneMenuRecord.swift        # Record menu — screen recording controls\n    ├── VPhoneMenuBattery.swift       # Battery menu — battery status display\n    │\n    │   # IPA installation\n    ├── VPhoneIPAInstaller.swift      # IPA extraction, signing, and installation\n    ├── VPhoneSigner.swift            # Mach-O binary signing utilities\n    │\n    │   # File browser (SwiftUI)\n    ├── VPhoneFileWindowController.swift # File browser window (NSHostingController)\n    ├── VPhoneFileBrowserView.swift   # SwiftUI file browser with search + drag-drop\n    ├── VPhoneFileBrowserModel.swift  # @Observable file browser state + transfers\n    └── VPhoneRemoteFile.swift        # Remote file data model\n\nscripts/\n├── vphoned/                      # Guest daemon (ObjC, runs inside iOS VM over vsock)\n├── patchers/                     # Python CFW patcher modules\n│   └── cfw.py                    #   CFW binary patcher entrypoint\n├── resources/                    # Resource archives (git submodule)\n├── repos/                        # Toolchain source repos (git submodules: trustcache, insert_dylib, libimobiledevice stack)\n├── patches/                      # Build-time patches (libirecovery)\n├── fw_prepare.sh                 # Download IPSWs, merge cloudOS into iPhone\n├── fw_manifest.py                # Generate hybrid BuildManifest/Restore plists\n├── cfw_install.sh                # Install CFW (regular)\n├── cfw_install_dev.sh            # Regular + rpcserver daemon\n├── cfw_install_jb.sh             # Regular + jetsam fix + procursus\n├── cfw_install_exp.sh            # JB + experimental research patches (hv_vmm rename, DT identity)\n├── cfw_install_host.sh           # Host-mount CFW driver (attaches Disk.img, VM off; re-execs sudo)\n├── vm_create.sh                  # Create VM directory\n├── setup_machine.sh              # Full automation (setup → first boot)\n├── setup_tools.sh                # Install deps, build toolchain from submodules, create venv\n├── setup_venv.sh                 # Create Python venv\n├── setup_venv_linux.sh           # Create Python venv (Linux)\n├── setup_libimobiledevice.sh     # Build libimobiledevice stack from scripts/repos submodules\n└── tail_jb_patch_logs.sh         # Tail JB patch log output\n\ntools/\n└── apfs_snap_rename.py           # Offline APFS boot-snapshot flip (used by cfw_install_host.sh)\n\nresearch/                         # Detailed firmware/patch documentation\n```\n\n### Key Patterns\n\n- **Private API access:** Via [Dynamic](https://github.com/mhdhejazi/Dynamic) library (runtime method dispatch from pure Swift). No ObjC bridge.\n- **App lifecycle:** `main.swift` → `NSApplication` + `VPhoneAppDelegate`. CLI args parsed before run loop. AppDelegate drives VM start/window/shutdown.\n- **Configuration:** `ArgumentParser` → `VPhoneVirtualMachine.Options` → `VZVirtualMachineConfiguration`.\n- **Guest daemon (vphoned):** ObjC daemon inside iOS VM, vsock port 1337, length-prefixed JSON protocol. Host side is `VPhoneControl` with auto-reconnect.\n- **Menu system:** `VPhoneMenuController` + per-menu extensions (Keys, Type, Location, Connect, Install, Record).\n- **File browser:** SwiftUI (`VPhoneFileBrowserView` + `VPhoneFileBrowserModel`) in `NSHostingController`. Search, sort, upload/download, drag-drop via `VPhoneControl`.\n- **IPA installation:** `VPhoneIPAInstaller` extracts + re-signs via `VPhoneSigner` + installs over vsock.\n- **Screen recording:** `VPhoneScreenRecorder` captures VM display. Controls via Record menu.\n\n---\n\n## Coding Conventions\n\n### Swift\n\n- **Language:** Swift 6.0 (strict concurrency).\n- **Style:** Pragmatic, minimal. No unnecessary abstractions.\n- **Sections:** Use `// MARK: -` to organize code within files.\n- **Access control:** Default (internal). Only mark `private` when needed for clarity.\n- **Concurrency:** `@MainActor` for VM and UI classes. `nonisolated` delegate methods use `MainActor.isolated {}` to hop back safely.\n- **Naming:** Types are `VPhone`-prefixed. Match Apple framework conventions.\n- **Private APIs:** Use `Dynamic()` for runtime method dispatch. Touch objects use `NSClassFromString` + KVC to avoid designated initializer crashes.\n- **NSWindow `isReleasedWhenClosed`:** Always set `window.isReleasedWhenClosed = false` for programmatically created windows managed by an `NSWindowController`. The default `true` causes `objc_release` crashes on dangling pointers during CA transaction commit.\n\n### Shell Scripts\n\n- Use `zsh` with `set -euo pipefail`.\n- Scripts resolve their own directory via `${0:a:h}` or `$(cd \"$(dirname \"$0\")\" && pwd)`.\n\n### Python Scripts\n\n### Kernel patcher guardrails\n\n- For kernel patchers, never hardcode file offsets, virtual addresses, or preassembled instruction bytes inside patch logic.\n- All instruction matching must be derived from Capstone decode results (mnemonic / operands / control-flow), not exact operand-string text when a semantic operand check is possible.\n- All replacement instruction bytes must come from Keystone-backed helpers already used by the project (for example `asm(...)`, `NOP`, `MOV_W0_0`, etc.).\n- Prefer source-backed semantic anchors: in-image symbol lookup, string xrefs, local call-flow, and XNU correlation. Do not depend on repo-exported per-kernel symbol dumps at runtime.\n- When retargeting a patch, write the reveal procedure and validation steps into the relevant research doc or commit notes before handing off for testing. Do not create `TODO.md`.\n- For `patch_bsd_init_auth` specifically, the allowed reveal flow is: recover `bsd_init` -> locate rootvp panic block -> find the unique in-function `call` -> `cbnz w0/x0, panic` -> `bl imageboot_needed` site -> patch the branch gate only.\n\n- Patchers use `capstone` (disassembly), `keystone-engine` (assembly), `pyimg4` (IM4P handling).\n- Dynamic pattern finding (string anchors, ADRP+ADD xrefs, BL frequency) — no hardcoded offsets.\n- Each patch logged with offset and before/after state.\n- Use project venv (`source .venv/bin/activate`). Create with `make setup_venv`.\n\n## Build & Sign\n\nThe binary requires private entitlements for PV=3 virtualization. Always use `make build` — never `swift build` alone, as the unsigned binary will fail at runtime.\n\n## Design System\n\n- **Audience:** Security researchers. Terminal-adjacent workflow.\n- **Feel:** Research instrument — precise, informative, no decoration.\n- **Palette:** Dark neutral (`#1a1a1a` bg), status green/amber/red/blue accents.\n- **Typography:** System monospace (SF Mono / Menlo) for UI and log output.\n- **Depth:** Flat with 1px borders (`#333333`). No shadows.\n- **Spacing:** 8px base unit, 12px component padding, 16px section gaps.\n"},"files":{"AGENTS.md":"# vphone-cli\n\nVirtual iPhone boot tool using Apple's Virtualization.framework with PCC research VMs.\n\n## Quick Reference\n\n- **Build:** `make build`\n- **Boot (GUI):** `make boot`\n- **Boot (DFU):** `make boot_dfu`\n- **All targets:** `make help`\n- **Python venv:** `make setup_venv` (installs to `.venv/`, activate with `source .venv/bin/activate`)\n- **Platform:** macOS 15+ (Sequoia), SIP/AMFI disabled\n- **Language:** Swift 6.0 (SwiftPM), private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic)\n- **Python deps:** `capstone`, `keystone-engine`, `pyimg4` (see `requirements.txt`)\n\n## Workflow Rules\n\n- Do not create, read, or update `/TODO.md`.\n- Ignore `/TODO.md` if it exists locally; it is intentionally not part of the repo workflow anymore.\n- Track plan, progress, assumptions, blockers, and next actions in commit history, code comments when warranted, and current research docs instead of a repo TODO file.\n\nFor any changes applying new patches, also update research/0_binary_patch_comparison.md. Dont forget this.\n\n## Local Skills\n\n- If working on kernel analysis, symbolication lookups, or kernel patch reasoning, read `skills/kernel-analysis-vphone600/SKILL.md` first.\n- Use this skill as the default procedure for `vphone600` kernel work.\n\n## Firmware Variants\n\n| Variant          | Boot Chain     |    CFW    | Make Targets                       |\n| ---------------- | :------------: | :-------: | ---------------------------------- |\n| **Regular**      | 52 patches     | 10 phases | `fw_patch` + `cfw_install`         |\n| **Development**  | 66 patches     | 12 phases | `fw_patch_dev` + `cfw_install_dev` |\n| **Jailbreak**    | 127 patches    | 14 phases | `fw_patch_jb` + `cfw_install_jb`   |\n| **Experimental** | 141 patches    | 18 phases | `fw_patch_exp` + `cfw_install_exp` |\n\n> JB finalization (symlinks, Sileo, apt, TrollStore) runs automatically on first boot via `/cores/vphone_jb_setup.sh` LaunchDaemon. Monitor progress: `/var/log/vphone_jb_setup.log`.\n\n> EXP is a JB superset that patches the kernel and DSC to make some Apple services think the device is not a VM, while keeping VM-specific services (graphics passthrough, compute/accel fast paths) working correctly. Other variants are deliberately NOT affected by these changes.\n\nSee `research/` for detailed firmware pipeline, component origins, patch breakdowns, and boot flow documentation.\n\n## Architecture\n\n```\nMakefile                          # Single entry point — run `make help`\n\nsources/\n├── vphone.entitlements               # Private API entitlements (5 keys)\n└── vphone-cli/                       # Swift 6.0 executable (pure Swift, no ObjC)\n    ├── main.swift                    # Entry point — NSApplication + AppDelegate\n    ├── VPhoneAppDelegate.swift       # App lifecycle, SIGINT, VM start/stop\n    ├── VPhoneCLI.swift               # ArgumentParser options (no execution logic)\n    ├── VPhoneBuildInfo.swift         # Auto-generated build-time commit hash\n    │\n    │   # VM core\n    ├── VPhoneVirtualMachine.swift    # @MainActor VM configuration and lifecycle\n    ├── VPhoneHardwareModel.swift     # PV=3 hardware model via Dynamic\n    ├── VPhoneVirtualMachineView.swift # Touch-enabled VZVirtualMachineView + helpers\n    ├── VPhoneError.swift             # Error types\n    │\n    │   # Guest daemon client (vsock)\n    ├── VPhoneControl.swift           # Host-side vsock client for vphoned (length-prefixed JSON)\n    │\n    │   # Window & UI\n    ├── VPhoneWindowController.swift  # @MainActor VM window management + toolbar\n    ├── VPhoneKeyHelper.swift         # Keyboard/hardware key event dispatch to VM\n    ├── VPhoneLocationProvider.swift  # CoreLocation → guest forwarding over vsock\n    ├── VPhoneScreenRecorder.swift    # VM screen recording to file\n    │\n    │   # Menu bar (extensions on VPhoneMenuController)\n    ├── VPhoneMenuController.swift    # Menu bar controller\n    ├── VPhoneMenuKeys.swift          # Keys menu — home, power, volume, spotlight\n    ├── VPhoneMenuType.swift          # Type menu — paste ASCII text to guest\n    ├── VPhoneMenuLocation.swift      # Location menu — host location sync toggle\n    ├── VPhoneMenuConnect.swift       # Connect menu — devmode, ping, version, file browser\n    ├── VPhoneMenuInstall.swift       # Install menu — IPA installation to guest\n    ├── VPhoneMenuRecord.swift        # Record menu — screen recording controls\n    ├── VPhoneMenuBattery.swift       # Battery menu — battery status display\n    │\n    │   # IPA installation\n    ├── VPhoneIPAInstaller.swift      # IPA extraction, signing, and installation\n    ├── VPhoneSigner.swift            # Mach-O binary signing utilities\n    │\n    │   # File browser (SwiftUI)\n    ├── VPhoneFileWindowController.swift # File browser window (NSHostingController)\n    ├── VPhoneFileBrowserView.swift   # SwiftUI file browser with search + drag-drop\n    ├── VPhoneFileBrowserModel.swift  # @Observable file browser state + transfers\n    └── VPhoneRemoteFile.swift        # Remote file data model\n\nscripts/\n├── vphoned/                      # Guest daemon (ObjC, runs inside iOS VM over vsock)\n├── patchers/                     # Python CFW patcher modules\n│   └── cfw.py                    #   CFW binary patcher entrypoint\n├── resources/                    # Resource archives (git submodule)\n├── repos/                        # Toolchain source repos (git submodules: trustcache, insert_dylib, libimobiledevice stack)\n├── patches/                      # Build-time patches (libirecovery)\n├── fw_prepare.sh                 # Download IPSWs, merge cloudOS into iPhone\n├── fw_manifest.py                # Generate hybrid BuildManifest/Restore plists\n├── cfw_install.sh                # Install CFW (regular)\n├── cfw_install_dev.sh            # Regular + rpcserver daemon\n├── cfw_install_jb.sh             # Regular + jetsam fix + procursus\n├── cfw_install_exp.sh            # JB + experimental research patches (hv_vmm rename, DT identity)\n├── cfw_install_host.sh           # Host-mount CFW driver (attaches Disk.img, VM off; re-execs sudo)\n├── vm_create.sh                  # Create VM directory\n├── setup_machine.sh              # Full automation (setup → first boot)\n├── setup_tools.sh                # Install deps, build toolchain from submodules, create venv\n├── setup_venv.sh                 # Create Python venv\n├── setup_venv_linux.sh           # Create Python venv (Linux)\n├── setup_libimobiledevice.sh     # Build libimobiledevice stack from scripts/repos submodules\n└── tail_jb_patch_logs.sh         # Tail JB patch log output\n\ntools/\n└── apfs_snap_rename.py           # Offline APFS boot-snapshot flip (used by cfw_install_host.sh)\n\nresearch/                         # Detailed firmware/patch documentation\n```\n\n### Key Patterns\n\n- **Private API access:** Via [Dynamic](https://github.com/mhdhejazi/Dynamic) library (runtime method dispatch from pure Swift). No ObjC bridge.\n- **App lifecycle:** `main.swift` → `NSApplication` + `VPhoneAppDelegate`. CLI args parsed before run loop. AppDelegate drives VM start/window/shutdown.\n- **Configuration:** `ArgumentParser` → `VPhoneVirtualMachine.Options` → `VZVirtualMachineConfiguration`.\n- **Guest daemon (vphoned):** ObjC daemon inside iOS VM, vsock port 1337, length-prefixed JSON protocol. Host side is `VPhoneControl` with auto-reconnect.\n- **Menu system:** `VPhoneMenuController` + per-menu extensions (Keys, Type, Location, Connect, Install, Record).\n- **File browser:** SwiftUI (`VPhoneFileBrowserView` + `VPhoneFileBrowserModel`) in `NSHostingController`. Search, sort, upload/download, drag-drop via `VPhoneControl`.\n- **IPA installation:** `VPhoneIPAInstaller` extracts + re-signs via `VPhoneSigner` + installs over vsock.\n- **Screen recording:** `VPhoneScreenRecorder` captures VM display. Controls via Record menu.\n\n---\n\n## Coding Conventions\n\n### Swift\n\n- **Language:** Swift 6.0 (strict concurrency).\n- **Style:** Pragmatic, minimal. No unnecessary abstractions.\n- **Sections:** Use `// MARK: -` to organize code within files.\n- **Access control:** Default (internal). Only mark `private` when needed for clarity.\n- **Concurrency:** `@MainActor` for VM and UI classes. `nonisolated` delegate methods use `MainActor.isolated {}` to hop back safely.\n- **Naming:** Types are `VPhone`-prefixed. Match Apple framework conventions.\n- **Private APIs:** Use `Dynamic()` for runtime method dispatch. Touch objects use `NSClassFromString` + KVC to avoid designated initializer crashes.\n- **NSWindow `isReleasedWhenClosed`:** Always set `window.isReleasedWhenClosed = false` for programmatically created windows managed by an `NSWindowController`. The default `true` causes `objc_release` crashes on dangling pointers during CA transaction commit.\n\n### Shell Scripts\n\n- Use `zsh` with `set -euo pipefail`.\n- Scripts resolve their own directory via `${0:a:h}` or `$(cd \"$(dirname \"$0\")\" && pwd)`.\n\n### Python Scripts\n\n### Kernel patcher guardrails\n\n- For kernel patchers, never hardcode file offsets, virtual addresses, or preassembled instruction bytes inside patch logic.\n- All instruction matching must be derived from Capstone decode results (mnemonic / operands / control-flow), not exact operand-string text when a semantic operand check is possible.\n- All replacement instruction bytes must come from Keystone-backed helpers already used by the project (for example `asm(...)`, `NOP`, `MOV_W0_0`, etc.).\n- Prefer source-backed semantic anchors: in-image symbol lookup, string xrefs, local call-flow, and XNU correlation. Do not depend on repo-exported per-kernel symbol dumps at runtime.\n- When retargeting a patch, write the reveal procedure and validation steps into the relevant research doc or commit notes before handing off for testing. Do not create `TODO.md`.\n- For `patch_bsd_init_auth` specifically, the allowed reveal flow is: recover `bsd_init` -> locate rootvp panic block -> find the unique in-function `call` -> `cbnz w0/x0, panic` -> `bl imageboot_needed` site -> patch the branch gate only.\n\n- Patchers use `capstone` (disassembly), `keystone-engine` (assembly), `pyimg4` (IM4P handling).\n- Dynamic pattern finding (string anchors, ADRP+ADD xrefs, BL frequency) — no hardcoded offsets.\n- Each patch logged with offset and before/after state.\n- Use project venv (`source .venv/bin/activate`). Create with `make setup_venv`.\n\n## Build & Sign\n\nThe binary requires private entitlements for PV=3 virtualization. Always use `make build` — never `swift build` alone, as the unsigned binary will fail at runtime.\n\n## Design System\n\n- **Audience:** Security researchers. Terminal-adjacent workflow.\n- **Feel:** Research instrument — precise, informative, no decoration.\n- **Palette:** Dark neutral (`#1a1a1a` bg), status green/amber/red/blue accents.\n- **Typography:** System monospace (SF Mono / Menlo) for UI and log output.\n- **Depth:** Flat with 1px borders (`#333333`). No shadows.\n- **Spacing:** 8px base unit, 12px component padding, 16px section gaps.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# vphone-cli\n\nVirtual iPhone boot tool using Apple's Virtualization.framework with PCC research VMs.\n\n## Quick Reference\n\n- **Build:** `make build`\n- **Boot (GUI):** `make boot`\n- **Boot (DFU):** `make boot_dfu`\n- **All targets:** `make help`\n- **Python venv:** `make setup_venv` (installs to `.venv/`, activate with `source .venv/bin/activate`)\n- **Platform:** macOS 15+ (Sequoia), SIP/AMFI disabled\n- **Language:** Swift 6.0 (SwiftPM), private APIs via [Dynamic](https://github.com/mhdhejazi/Dynamic)\n- **Python deps:** `capstone`, `keystone-engine`, `pyimg4` (see `requirements.txt`)\n\n## Workflow Rules\n\n- Do not create, read, or update `/TODO.md`.\n- Ignore `/TODO.md` if it exists locally; it is intentionally not part of the repo workflow anymore.\n- Track plan, progress, assumptions, blockers, and next actions in commit history, code comments when warranted, and current research docs instead of a repo TODO file.\n\nFor any changes applying new patches, also update research/0_binary_patch_comparison.md. Dont forget this.\n\n## Local Skills\n\n- If working on kernel analysis, symbolication lookups, or kernel patch reasoning, read `skills/kernel-analysis-vphone600/SKILL.md` first.\n- Use this skill as the default procedure for `vphone600` kernel work.\n\n## Firmware Variants\n\n| Variant          | Boot Chain     |    CFW    | Make Targets                       |\n| ---------------- | :------------: | :-------: | ---------------------------------- |\n| **Regular**      | 52 patches     | 10 phases | `fw_patch` + `cfw_install`         |\n| **Development**  | 66 patches     | 12 phases | `fw_patch_dev` + `cfw_install_dev` |\n| **Jailbreak**    | 127 patches    | 14 phases | `fw_patch_jb` + `cfw_install_jb`   |\n| **Experimental** | 141 patches    | 18 phases | `fw_patch_exp` + `cfw_install_exp` |\n\n> JB finalization (symlinks, Sileo, apt, TrollStore) runs automatically on first boot via `/cores/vphone_jb_setup.sh` LaunchDaemon. Monitor progress: `/var/log/vphone_jb_setup.log`.\n\n> EXP is a JB superset that patches the kernel and DSC to make some Apple services think the device is not a VM, while keeping VM-specific services (graphics passthrough, compute/accel fast paths) working correctly. Other variants are deliberately NOT affected by these changes.\n\nSee `research/` for detailed firmware pipeline, component origins, patch breakdowns, and boot flow documentation.\n\n## Architecture\n\n```\nMakefile                          # Single entry point — run `make help`\n\nsources/\n├── vphone.entitlements               # Private API entitlements (5 keys)\n└── vphone-cli/                       # Swift 6.0 executable (pure Swift, no ObjC)\n    ├── main.swift                    # Entry point — NSApplication + AppDelegate\n    ├── VPhoneAppDelegate.swift       # App lifecycle, SIGINT, VM start/stop\n    ├── VPhoneCLI.swift               # ArgumentParser options (no execution logic)\n    ├── VPhoneBuildInfo.swift         # Auto-generated build-time commit hash\n    │\n    │   # VM core\n    ├── VPhoneVirtualMachine.swift    # @MainActor VM configuration and lifecycle\n    ├── VPhoneHardwareModel.swift     # PV=3 hardware model via Dynamic\n    ├── VPhoneVirtualMachineView.swift # Touch-enabled VZVirtualMachineView + helpers\n    ├── VPhoneError.swift             # Error types\n    │\n    │   # Guest daemon client (vsock)\n    ├── VPhoneControl.swift           # Host-side vsock client for vphoned (length-prefixed JSON)\n    │\n    │   # Window & UI\n    ├── VPhoneWindowController.swift  # @MainActor VM window management + toolbar\n    ├── VPhoneKeyHelper.swift         # Keyboard/hardware key event dispatch to VM\n    ├── VPhoneLocationProvider.swift  # CoreLocation → guest forwarding over vsock\n    ├── VPhoneScreenRecorder.swift    # VM screen recording to file\n    │\n    │   # Menu bar (extensions on VPhoneMenuController)\n    ├── VPhoneMenuController.swift    # Menu bar controller\n    ├── VPhoneMenuKeys.swift          # Keys menu — home, power, volume, spotlight\n    ├── VPhoneMenuType.swift          # Type menu — paste ASCII text to guest\n    ├── VPhoneMenuLocation.swift      # Location menu — host location sync toggle\n    ├── VPhoneMenuConnect.swift       # Connect menu — devmode, ping, version, file browser\n    ├── VPhoneMenuInstall.swift       # Install menu — IPA installation to guest\n    ├── VPhoneMenuRecord.swift        # Record menu — screen recording controls\n    ├── VPhoneMenuBattery.swift       # Battery menu — battery status display\n    │\n    │   # IPA installation\n    ├── VPhoneIPAInstaller.swift      # IPA extraction, signing, and installation\n    ├── VPhoneSigner.swift            # Mach-O binary signing utilities\n    │\n    │   # File browser (SwiftUI)\n    ├── VPhoneFileWindowController.swift # File browser window (NSHostingController)\n    ├── VPhoneFileBrowserView.swift   # SwiftUI file browser with search + drag-drop\n    ├── VPhoneFileBrowserModel.swift  # @Observable file browser state + transfers\n    └── VPhoneRemoteFile.swift        # Remote file data model\n\nscripts/\n├── vphoned/                      # Guest daemon (ObjC, runs inside iOS VM over vsock)\n├── patchers/                     # Python CFW patcher modules\n│   └── cfw.py                    #   CFW binary patcher entrypoint\n├── resources/                    # Resource archives (git submodule)\n├── repos/                        # Toolchain source repos (git submodules: trustcache, insert_dylib, libimobiledevice stack)\n├── patches/                      # Build-time patches (libirecovery)\n├── fw_prepare.sh                 # Download IPSWs, merge cloudOS into iPhone\n├── fw_manifest.py                # Generate hybrid BuildManifest/Restore plists\n├── cfw_install.sh                # Install CFW (regular)\n├── cfw_install_dev.sh            # Regular + rpcserver daemon\n├── cfw_install_jb.sh             # Regular + jetsam fix + procursus\n├── cfw_install_exp.sh            # JB + experimental research patches (hv_vmm rename, DT identity)\n├── cfw_install_host.sh           # Host-mount CFW driver (attaches Disk.img, VM off; re-execs sudo)\n├── vm_create.sh                  # Create VM directory\n├── setup_machine.sh              # Full automation (setup → first boot)\n├── setup_tools.sh                # Install deps, build toolchain from submodules, create venv\n├── setup_venv.sh                 # Create Python venv\n├── setup_venv_linux.sh           # Create Python venv (Linux)\n├── setup_libimobiledevice.sh     # Build libimobiledevice stack from scripts/repos submodules\n└── tail_jb_patch_logs.sh         # Tail JB patch log output\n\ntools/\n└── apfs_snap_rename.py           # Offline APFS boot-snapshot flip (used by cfw_install_host.sh)\n\nresearch/                         # Detailed firmware/patch documentation\n```\n\n### Key Patterns\n\n- **Private API access:** Via [Dynamic](https://github.com/mhdhejazi/Dynamic) library (runtime method dispatch from pure Swift). No ObjC bridge.\n- **App lifecycle:** `main.swift` → `NSApplication` + `VPhoneAppDelegate`. CLI args parsed before run loop. AppDelegate drives VM start/window/shutdown.\n- **Configuration:** `ArgumentParser` → `VPhoneVirtualMachine.Options` → `VZVirtualMachineConfiguration`.\n- **Guest daemon (vphoned):** ObjC daemon inside iOS VM, vsock port 1337, length-prefixed JSON protocol. Host side is `VPhoneControl` with auto-reconnect.\n- **Menu system:** `VPhoneMenuController` + per-menu extensions (Keys, Type, Location, Connect, Install, Record).\n- **File browser:** SwiftUI (`VPhoneFileBrowserView` + `VPhoneFileBrowserModel`) in `NSHostingController`. Search, sort, upload/download, drag-drop via `VPhoneControl`.\n- **IPA installation:** `VPhoneIPAInstaller` extracts + re-signs via `VPhoneSigner` + installs over vsock.\n- **Screen recording:** `VPhoneScreenRecorder` captures VM display. Controls via Record menu.\n\n---\n\n## Coding Conventions\n\n### Swift\n\n- **Language:** Swift 6.0 (strict concurrency).\n- **Style:** Pragmatic, minimal. No unnecessary abstractions.\n- **Sections:** Use `// MARK: -` to organize code within files.\n- **Access control:** Default (internal). Only mark `private` when needed for clarity.\n- **Concurrency:** `@MainActor` for VM and UI classes. `nonisolated` delegate methods use `MainActor.isolated {}` to hop back safely.\n- **Naming:** Types are `VPhone`-prefixed. Match Apple framework conventions.\n- **Private APIs:** Use `Dynamic()` for runtime method dispatch. Touch objects use `NSClassFromString` + KVC to avoid designated initializer crashes.\n- **NSWindow `isReleasedWhenClosed`:** Always set `window.isReleasedWhenClosed = false` for programmatically created windows managed by an `NSWindowController`. The default `true` causes `objc_release` crashes on dangling pointers during CA transaction commit.\n\n### Shell Scripts\n\n- Use `zsh` with `set -euo pipefail`.\n- Scripts resolve their own directory via `${0:a:h}` or `$(cd \"$(dirname \"$0\")\" && pwd)`.\n\n### Python Scripts\n\n### Kernel patcher guardrails\n\n- For kernel patchers, never hardcode file offsets, virtual addresses, or preassembled instruction bytes inside patch logic.\n- All instruction matching must be derived from Capstone decode results (mnemonic / operands / control-flow), not exact operand-string text when a semantic operand check is possible.\n- All replacement instruction bytes must come from Keystone-backed helpers already used by the project (for example `asm(...)`, `NOP`, `MOV_W0_0`, etc.).\n- Prefer source-backed semantic anchors: in-image symbol lookup, string xrefs, local call-flow, and XNU correlation. Do not depend on repo-exported per-kernel symbol dumps at runtime.\n- When retargeting a patch, write the reveal procedure and validation steps into the relevant research doc or commit notes before handing off for testing. Do not create `TODO.md`.\n- For `patch_bsd_init_auth` specifically, the allowed reveal flow is: recover `bsd_init` -> locate rootvp panic block -> find the unique in-function `call` -> `cbnz w0/x0, panic` -> `bl imageboot_needed` site -> patch the branch gate only.\n\n- Patchers use `capstone` (disassembly), `keystone-engine` (assembly), `pyimg4` (IM4P handling).\n- Dynamic pattern finding (string anchors, ADRP+ADD xrefs, BL frequency) — no hardcoded offsets.\n- Each patch logged with offset and before/after state.\n- Use project venv (`source .venv/bin/activate`). Create with `make setup_venv`.\n\n## Build & Sign\n\nThe binary requires private entitlements for PV=3 virtualization. Always use `make build` — never `swift build` alone, as the unsigned binary will fail at runtime.\n\n## Design System\n\n- **Audience:** Security researchers. Terminal-adjacent workflow.\n- **Feel:** Research instrument — precise, informative, no decoration.\n- **Palette:** Dark neutral (`#1a1a1a` bg), status green/amber/red/blue accents.\n- **Typography:** System monospace (SF Mono / Menlo) for UI and log output.\n- **Depth:** Flat with 1px borders (`#333333`). No shadows.\n- **Spacing:** 8px base unit, 12px component padding, 16px section gaps.\n","category":"root","tokens":2736}]}