# 34306/filzajailedds architecture

> Architecture diagram of the GitHub repository 34306/filzajailedds, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/34306/filzajailedds
- Repository: https://github.com/34306/filzajailedds

## Overview

1. This repository is a packaged injected tweak for the Filza iPA, not a standalone app or service. The goal is to extend Filza’s file access capabilities on jailed iOS devices by combining userland hooks with low-level kernel primitives.

2. The top-level entrypoint is `Tweak.m`, with `FilzaApplySandboxExt.plist` acting as the injection/filter configuration. `Makefile` and `control` indicate it is built and distributed as a tweak/package rather than as a normal app binary.

3. The main user-facing logic lives in `sandbox_escape.m` and `apfs_own.m`. These appear to manage sandbox bypass behavior and file ownership changes so Filza can access paths it normally cannot. `utils/` provides supporting helpers for file, process, and hex-dump operations.

4. The kernel-access layer is isolated under `kexploit/`. This includes an exploit implementation (`kexploit_opa334.m`), kernel read/write primitives (`krw.*`), device/offset metadata (`machine_info.h`, `offsets.*`), vnode helpers (`vnode.*`), and PAC-related helpers (`xpaci.h`). This layer is responsible for turning an exploit into usable kernel memory access.

5. `kpf/patchfinder.*` is the offset/patch-finding layer. Its job is to locate kernel code/data patterns across OS versions so the exploit and patching logic can adapt without hardcoded addresses.

6. The `XPF/` subtree is the higher-level patching framework. It is split into shared logic (`common`, `decompress`, `xpf`) and execution paths for different environments (`ppl.*` and `non_ppl.*`), plus `bad_recovery.*` for cleanup/recovery. This strongly suggests the repo supports multiple low-level patching strategies depending on whether PPL-related constraints are present.

7. `XPF/external/ChOma` is a vendored dependency used for binary and cache inspection. It includes Mach-O, fat binary, dyld shared cache, code directory, entitlements, and patch-finding support. Architecturally, this lets the patching layer reason about system binaries and shared caches instead of relying only on raw kernel memory access.

8. The main data flow is: Filza launches → injected tweak initializes → sandbox/file-access logic runs → if needed, the kernel exploit provides `krw` → patchfinder/XPF locate the right targets → patches or ownership changes are applied → Filza gains the expanded access it needs.

9. The repo is highly version- and device-dependent. The README explicitly calls out iOS version support and exclusions, and the presence of `offsets.*`, patchfinder code, and PPL/non-PPL paths shows that behavior is tailored to specific OS internals rather than using a single universal technique.

10. There is no backend or network architecture here; the system is entirely local and privilege-oriented. The important architectural boundaries are between injected userland code, kernel exploit primitives, and version-specific patching/inspection logic.

Main entry points: [`XPF/src/xpf.c`](https://github.com/34306/filzajailedds/blob/main/XPF/src/xpf.c) (XPF core), [`kexploit/kexploit_opa334.m`](https://github.com/34306/filzajailedds/blob/main/kexploit/kexploit_opa334.m) (Kernel exploit), [`kexploit/krw.m`](https://github.com/34306/filzajailedds/blob/main/kexploit/krw.m) (KRW), [`sandbox_escape.m`](https://github.com/34306/filzajailedds/blob/main/sandbox_escape.m) (Sandbox escape)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_package["Package"]
  node_n1(("Tweak entry<br/>entrypoint<br/>[Tweak.m]"))
  node_n2["Filter plist<br/>injection config"]
  node_n3["Package spec<br/>dpkg metadata"]
  node_n4["Build file<br/>build script"]
end

subgraph group_userland["Userland access"]
  node_n5["Sandbox escape<br/>userland bypass<br/>[sandbox_escape.m]"]
  node_n6["APFS ownership<br/>file access<br/>[apfs_own.m]"]
end

subgraph group_kernel["Kernel access"]
  node_n10["Kernel exploit<br/>[kexploit_opa334.m]"]
  node_n11["KRW<br/>primitive<br/>[krw.m]"]
  node_n12["Offsets<br/>device map<br/>[offsets.m]"]
  node_n13["Vnode helpers<br/>kernel helper<br/>[vnode.m]"]
  node_n14["PAC helpers<br/>kernel helper<br/>[xpaci.h]"]
end

subgraph group_patching["Patching"]
  node_n15["Patchfinder<br/>offset discovery<br/>[patchfinder.m]"]
  node_n16["XPF core<br/>patch framework<br/>[xpf.c]"]
  node_n17["PPL path<br/>patch path<br/>[ppl.c]"]
  node_n18["Non-PPL path<br/>patch path<br/>[non_ppl.c]"]
  node_n19["Recovery<br/>cleanup<br/>[bad_recovery.c]"]
end

subgraph group_vendor["Vendor dep"]
  node_n20["ChOma<br/>binary inspection lib<br/>[MachO.c]"]
end

subgraph group_utils["Utils"]
  node_n7["File helpers<br/>[file.c]"]
  node_n8["Process helpers<br/>[process.c]"]
  node_n9["Hex dump<br/>[hexdump.c]"]
end

node_n2 -->|"injects"| node_n1
node_n1 -->|"starts"| node_n5
node_n1 -->|"starts"| node_n6
node_n5 -->|"uses"| node_n7
node_n5 -->|"uses"| node_n8
node_n6 -->|"uses"| node_n7
node_n5 -.->|"falls back to"| node_n10
node_n6 -.->|"falls back to"| node_n10
node_n10 -->|"enables"| node_n11
node_n10 -->|"adapts to"| node_n12
node_n11 -->|"supports"| node_n13
node_n11 -->|"supports"| node_n15
node_n14 -->|"supports"| node_n10
node_n15 -->|"feeds"| node_n16
node_n16 -->|"selects"| node_n17
node_n16 -->|"selects"| node_n18
node_n16 -->|"recovers"| node_n19
node_n16 -->|"uses"| node_n20
node_n20 -->|"assists"| node_n15
node_n17 -->|"uses"| node_n11
node_n18 -->|"uses"| node_n11

click node_n1 "https://github.com/34306/filzajailedds/blob/main/Tweak.m"
click node_n2 "https://github.com/34306/filzajailedds/blob/main/FilzaApplySandboxExt.plist"
click node_n3 "https://github.com/34306/filzajailedds/tree/main/control"
click node_n4 "https://github.com/34306/filzajailedds/tree/main/Makefile"
click node_n5 "https://github.com/34306/filzajailedds/blob/main/sandbox_escape.m"
click node_n6 "https://github.com/34306/filzajailedds/blob/main/apfs_own.m"
click node_n7 "https://github.com/34306/filzajailedds/blob/main/utils/file.c"
click node_n8 "https://github.com/34306/filzajailedds/blob/main/utils/process.c"
click node_n9 "https://github.com/34306/filzajailedds/blob/main/utils/hexdump.c"
click node_n10 "https://github.com/34306/filzajailedds/blob/main/kexploit/kexploit_opa334.m"
click node_n11 "https://github.com/34306/filzajailedds/blob/main/kexploit/krw.m"
click node_n12 "https://github.com/34306/filzajailedds/blob/main/kexploit/offsets.m"
click node_n13 "https://github.com/34306/filzajailedds/blob/main/kexploit/vnode.m"
click node_n14 "https://github.com/34306/filzajailedds/blob/main/kexploit/xpaci.h"
click node_n15 "https://github.com/34306/filzajailedds/blob/main/kpf/patchfinder.m"
click node_n16 "https://github.com/34306/filzajailedds/blob/main/XPF/src/xpf.c"
click node_n17 "https://github.com/34306/filzajailedds/blob/main/XPF/src/ppl.c"
click node_n18 "https://github.com/34306/filzajailedds/blob/main/XPF/src/non_ppl.c"
click node_n19 "https://github.com/34306/filzajailedds/blob/main/XPF/src/bad_recovery.c"
click node_n20 "https://github.com/34306/filzajailedds/blob/main/XPF/external/ChOma/src/MachO.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2,node_n3,node_n4 toneBlue
class node_n5,node_n6 toneAmber
class node_n10,node_n11,node_n12,node_n13,node_n14 toneMint
class node_n15,node_n16,node_n17,node_n18,node_n19 toneRose
class node_n20 toneIndigo
class node_n7,node_n8,node_n9 toneTeal
```

## Components

### Package

Tweak packaging, injection, and entrypoint layer.

- [Tweak entry](https://github.com/34306/filzajailedds/blob/main/Tweak.m): entrypoint · Injected tweak entry that initializes the package's runtime behavior. · `Tweak.m`
- [Filter plist](https://github.com/34306/filzajailedds/blob/main/FilzaApplySandboxExt.plist): injection config · Injection and process-filter configuration for Filza. · `FilzaApplySandboxExt.plist`
- [Package spec](https://github.com/34306/filzajailedds/tree/main/control): dpkg metadata · Distribution metadata showing this is packaged as a tweak. · `control`
- [Build file](https://github.com/34306/filzajailedds/tree/main/Makefile): build script · Build/package instructions for producing the tweak. · `Makefile`

### Userland access

Injected logic that changes Filza's sandbox and file access behavior.

- [Sandbox escape](https://github.com/34306/filzajailedds/blob/main/sandbox_escape.m): userland bypass · Userland logic that expands Filza's accessible paths on jailed devices. · `sandbox_escape.m`
- [APFS ownership](https://github.com/34306/filzajailedds/blob/main/apfs_own.m): file access · Ownership and file-state changes used to widen access to protected paths. · `apfs_own.m`

### Kernel access

Exploit-backed primitives and device-specific kernel helpers.

- [Kernel exploit](https://github.com/34306/filzajailedds/blob/main/kexploit/kexploit_opa334.m): exploit · Exploit implementation that opens the path to kernel memory access. · `kexploit/kexploit_opa334.m`
- [KRW](https://github.com/34306/filzajailedds/blob/main/kexploit/krw.m): primitive · Kernel read/write primitives exposed after exploitation. · `kexploit/krw.m`
- [Offsets](https://github.com/34306/filzajailedds/blob/main/kexploit/offsets.m): device map · Device and OS-specific offset metadata used by the exploit layer. · `kexploit/offsets.m`
- [Vnode helpers](https://github.com/34306/filzajailedds/blob/main/kexploit/vnode.m): kernel helper · Helpers for vnode and filesystem object manipulation in kernel space. · `kexploit/vnode.m`
- [PAC helpers](https://github.com/34306/filzajailedds/blob/main/kexploit/xpaci.h): kernel helper · Pointer authentication helper macros and routines. · `kexploit/xpaci.h`

### Patching

Version-adaptive kernel patch finding and patch application.

- [Patchfinder](https://github.com/34306/filzajailedds/blob/main/kpf/patchfinder.m): offset discovery · Kernel pattern and offset discovery across OS versions. · `kpf/patchfinder.m`
- [XPF core](https://github.com/34306/filzajailedds/blob/main/XPF/src/xpf.c): patch framework · Top-level patching framework coordinating shared logic and execution paths. · `XPF/src/xpf.c`
- [PPL path](https://github.com/34306/filzajailedds/blob/main/XPF/src/ppl.c): patch path · Patch execution path for PPL-constrained environments. · `XPF/src/ppl.c`
- [Non-PPL path](https://github.com/34306/filzajailedds/blob/main/XPF/src/non_ppl.c): patch path · Patch execution path when PPL constraints are not the primary barrier. · `XPF/src/non_ppl.c`
- [Recovery](https://github.com/34306/filzajailedds/blob/main/XPF/src/bad_recovery.c): cleanup · Bad-state recovery and cleanup for patching failures. · `XPF/src/bad_recovery.c`

### Vendor dep

Bundled binary inspection and patch-finding library used by XPF.

- [ChOma](https://github.com/34306/filzajailedds/blob/main/XPF/external/ChOma/src/MachO.c): binary inspection lib · Vendored library for Mach-O, cache, entitlement, and patch inspection. · `XPF/external/ChOma/src/MachO.c`

### Utils

Supporting helpers shared by userland and exploit code.

- [File helpers](https://github.com/34306/filzajailedds/blob/main/utils/file.c): utility · File-related helper routines supporting access and path manipulation. · `utils/file.c`
- [Process helpers](https://github.com/34306/filzajailedds/blob/main/utils/process.c): utility · Process-related helper routines used by the tweak and exploit flow. · `utils/process.c`
- [Hex dump](https://github.com/34306/filzajailedds/blob/main/utils/hexdump.c): utility · Debug and inspection helper for binary data. · `utils/hexdump.c`

## Connections

- Filter plist → Tweak entry: injects · Configuration enables the tweak to load into Filza.
- Tweak entry → Sandbox escape: starts · Entrypoint initializes sandbox-extension logic.
- Tweak entry → APFS ownership: starts · Entrypoint initializes ownership adjustments.
- Sandbox escape → File helpers: uses · Sandbox logic relies on file helpers.
- Sandbox escape → Process helpers: uses · Sandbox logic consults process state.
- APFS ownership → File helpers: uses · Ownership logic operates on filesystem targets.
- Sandbox escape → Kernel exploit: falls back to · Kernel exploitation is used when userland access is insufficient.
- APFS ownership → Kernel exploit: falls back to · Ownership changes can depend on kernel capabilities.
- Kernel exploit → KRW: enables · Exploit produces kernel read/write primitives.
- Kernel exploit → Offsets: adapts to · Exploit behavior depends on device and OS-specific offsets.
- KRW → Vnode helpers: supports · Kernel primitives drive vnode-level filesystem operations.
- KRW → Patchfinder: supports · Read/write access feeds patch location discovery.
- PAC helpers → Kernel exploit: supports · PAC handling assists exploit and kernel execution.
- Patchfinder → XPF core: feeds · Discovered targets are consumed by the patching framework.
- XPF core → PPL path: selects · Framework can execute PPL-aware patching.
- XPF core → Non-PPL path: selects · Framework can execute non-PPL patching.
- XPF core → Recovery: recovers · Framework invokes cleanup on failure or partial patching.
- XPF core → ChOma: uses · Framework uses ChOma for binary and shared-cache inspection.
- ChOma → Patchfinder: assists · Binary and cache parsing improves patch finding.
- PPL path → KRW: uses · PPL path depends on kernel primitives for patching.
- Non-PPL path → KRW: uses · Non-PPL path depends on kernel primitives for patching.