# theiphoneos1project/microinjector architecture

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

- Interactive diagram: https://gitdiagram.com/theiphoneos1project/microinjector
- Repository: https://github.com/theiphoneos1project/microinjector

## Overview

#### Purpose and entry points
MicroInjector is a runtime code-injection platform for armv6 devices running iPhone OS 1.x. It installs a launchd bootstrap path that loads injection code into system processes, while exposing native hooking APIs through `MicroInjector.h` and Cydia Substrate-compatible shims through `SubstrateShims.c`.

Key build/package entry points are `Makefile`, `LaunchDaemon.plist`, and `PxlPkg.plist`.

#### Boot-time launchd bootstrap
The launch daemon configuration in `LaunchDaemon.plist` starts the bootstrap executable during system boot. `launchd_trampoline/launchd_trampoline.c` acts as a small intermediate process/loader stage, allowing the project to establish injection before normal launchd-managed workloads proceed.

The bootstrap path is deliberately guarded by a user-abort mechanism implemented in `inject_launchd/inject_launchd.c`.

#### Safe-mode / injection abort boundary
`inject_launchd/inject_launchd.c` detects held hardware buttons during boot and avoids injection when Home, Volume Up, or Volume Down is pressed. Hardware input handling is separated into:
- `inject_launchd/buttons.c`
- `inject_launchd/iokit_private.h`

This is the main recovery boundary: a failed or incompatible injected payload can be bypassed without removing the package.

#### launchd process injection
The injector executable manipulates the launchd task using low-level task and Mach-oriented primitives:
- `inject_launchd/inject_launchd.c`
- `inject_launchd/task_primitives.c`
- `inject_launchd/task_primitives.h`

This stage is architecture- and OS-version-sensitive. It crosses the strongest privilege boundary in the repository: an external bootstrap process obtains sufficient control over launchd to place the runtime loader into its address space.

#### In-process loader and payload discovery
Once injection reaches a target process, `Loader/MicroLoader.m` provides the Objective-C-aware in-process loading stage. It is responsible for bringing the MicroInjector runtime/payload behavior into the process context rather than relying on the external injector thereafter.

`Loader/MISafeModeAlert.m` and `Loader/MISafeModeAlert.h` provide an in-process failure/safe-mode user interface, complementing the boot-button escape hatch.

#### Native hooking runtime
The public runtime API is defined in:
- `MicroInjector.h`
- `MicroInjector.c`
- `MicroInjectorInternal.h`

This layer implements the core function, memory, Objective-C method, class-pair, image, and symbol manipulation capabilities used by injected code. `HookFunction.c` is a focused implementation unit for native function interception.

#### Substrate compatibility surface
`SubstrateShims.c` adapts the project’s native runtime to expected Cydia Substrate-style APIs. This is the compatibility boundary for existing tweaks or payloads written against Substrate conventions, allowing them to use MicroInjector without directly depending on its internal API.

#### Runtime and platform dependencies
The project targets legacy iPhone OS 1.x on armv6 and depends on private platform behavior, including IOKit input access and task/process manipulation. Building requires clang, an unofficial iPhone OS 1 SDK, and a patched linker supporting the Objective-C fragile runtime, as encoded by `Makefile`. Distribution is packaged as a PXL installer artifact via `PxlPkg.plist`.

Main entry points: [`MicroInjector.c`](https://github.com/theiphoneos1project/microinjector/blob/main/MicroInjector.c) (MicroInjector runtime), [`inject_launchd/inject_launchd.c`](https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/inject_launchd.c) (launchd injector), [`Makefile`](https://github.com/theiphoneos1project/microinjector/blob/main/Makefile) (Build rules), [`Loader/MicroLoader.m`](https://github.com/theiphoneos1project/microinjector/blob/main/Loader/MicroLoader.m) (MicroLoader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot bootstrap"]
  node_launchd_plist["Launch daemon config<br/>launchd plist<br/>[LaunchDaemon.plist]"]
  node_trampoline["launchd trampoline<br/>bootstrap loader"]
end

subgraph group_injector["Privilege boundary"]
  node_inject_launchd{{"launchd injector<br/>privileged injector<br/>[inject_launchd.c]"}}
  node_buttons["Boot button detection<br/>hardware input<br/>[buttons.c]"]
  node_iokit_private["Private IOKit access<br/>platform interface<br/>[iokit_private.h]"]
  node_task_primitives["Task/Mach primitives<br/>process control<br/>[task_primitives.c]"]
  node_task_primitives_api["Task primitive API<br/>internal header<br/>[task_primitives.h]"]
  node_launchd{{"launchd task<br/>system process"}}
end

subgraph group_runtime["In-process runtime"]
  node_microloader["MicroLoader<br/>in-process loader<br/>[MicroLoader.m]"]
  node_safe_mode_alert["Safe-mode alert<br/>in-process recovery UI<br/>[MISafeModeAlert.m]"]
  node_safe_mode_alert_api["Safe-mode alert API<br/>header<br/>[MISafeModeAlert.h]"]
  node_native_api["MicroInjector public API<br/>native hooking API<br/>[MicroInjector.h]"]
  node_native_runtime["MicroInjector runtime<br/>hooking runtime<br/>[MicroInjector.c]"]
  node_runtime_internal["Runtime internals<br/>internal header"]
  node_function_hook["Function hook engine<br/>native interception<br/>[HookFunction.c]"]
  node_substrate_shims["Substrate shims<br/>compatibility API<br/>[SubstrateShims.c]"]
  node_payloads["Injected payloads<br/>tweaks and injected code"]
end

subgraph group_distribution["Build and package"]
  node_makefile["Build rules<br/>build entry point"]
  node_pxlpkg["PXL package manifest<br/>installer metadata<br/>[PxlPkg.plist]"]
end

node_launchd_plist -->|"starts at boot"| node_trampoline
node_trampoline -->|"establishes bootstrap"| node_inject_launchd
node_iokit_private -->|"declares input access"| node_buttons
node_buttons -.->|"abort signal"| node_inject_launchd
node_task_primitives_api -->|"defines interface"| node_task_primitives
node_task_primitives -->|"provides task control"| node_inject_launchd
node_inject_launchd -->|"injects after guard passes"| node_launchd
node_launchd -->|"loads in process"| node_microloader
node_microloader -->|"activates runtime"| node_native_runtime
node_safe_mode_alert_api -->|"defines interface"| node_safe_mode_alert
node_microloader -.->|"shows failure state"| node_safe_mode_alert
node_runtime_internal -->|"internal contracts"| node_native_runtime
node_function_hook -->|"implements interception"| node_native_runtime
node_native_api -->|"public interface"| node_native_runtime
node_native_runtime -->|"native hooks and manipulation"| node_payloads
node_substrate_shims -->|"adapts to runtime"| node_native_runtime
node_substrate_shims -->|"Substrate-compatible API"| node_payloads
node_makefile -->|"builds"| node_trampoline
node_makefile -->|"builds"| node_inject_launchd
node_makefile -->|"builds"| node_microloader
node_makefile -->|"builds"| node_native_runtime
node_pxlpkg -->|"packages bootstrap config"| node_launchd_plist

click node_launchd_plist "https://github.com/theiphoneos1project/microinjector/blob/main/LaunchDaemon.plist"
click node_trampoline "https://github.com/theiphoneos1project/microinjector/blob/main/launchd_trampoline/launchd_trampoline.c"
click node_inject_launchd "https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/inject_launchd.c"
click node_buttons "https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/buttons.c"
click node_iokit_private "https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/iokit_private.h"
click node_task_primitives "https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/task_primitives.c"
click node_task_primitives_api "https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/task_primitives.h"
click node_microloader "https://github.com/theiphoneos1project/microinjector/blob/main/Loader/MicroLoader.m"
click node_safe_mode_alert "https://github.com/theiphoneos1project/microinjector/blob/main/Loader/MISafeModeAlert.m"
click node_safe_mode_alert_api "https://github.com/theiphoneos1project/microinjector/blob/main/Loader/MISafeModeAlert.h"
click node_native_api "https://github.com/theiphoneos1project/microinjector/blob/main/MicroInjector.h"
click node_native_runtime "https://github.com/theiphoneos1project/microinjector/blob/main/MicroInjector.c"
click node_runtime_internal "https://github.com/theiphoneos1project/microinjector/blob/main/MicroInjectorInternal.h"
click node_function_hook "https://github.com/theiphoneos1project/microinjector/blob/main/HookFunction.c"
click node_substrate_shims "https://github.com/theiphoneos1project/microinjector/blob/main/SubstrateShims.c"
click node_makefile "https://github.com/theiphoneos1project/microinjector/blob/main/Makefile"
click node_pxlpkg "https://github.com/theiphoneos1project/microinjector/blob/main/PxlPkg.plist"

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_launchd_plist,node_trampoline toneBlue
class node_inject_launchd,node_buttons,node_iokit_private,node_task_primitives,node_task_primitives_api,node_launchd toneAmber
class node_microloader,node_safe_mode_alert,node_safe_mode_alert_api,node_native_api,node_native_runtime,node_runtime_internal,node_function_hook,node_substrate_shims,node_payloads toneMint
class node_makefile,node_pxlpkg toneRose
```

## Components

### Boot bootstrap

Establishes launchd injection during system boot.

- [Launch daemon config](https://github.com/theiphoneos1project/microinjector/blob/main/LaunchDaemon.plist): launchd plist · Starts the bootstrap executable at boot. · `LaunchDaemon.plist`
- [launchd trampoline](https://github.com/theiphoneos1project/microinjector/blob/main/launchd_trampoline/launchd_trampoline.c): bootstrap loader · Intermediate process stage before normal launchd workloads. · `launchd_trampoline/launchd_trampoline.c`

### Privilege boundary

Controls guarded access to the launchd task.

- [launchd injector](https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/inject_launchd.c): privileged injector · Checks abort state and injects the loader into launchd. · `inject_launchd/inject_launchd.c`
- [Boot button detection](https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/buttons.c): hardware input · Detects Home and volume-button recovery gesture. · `inject_launchd/buttons.c`
- [Private IOKit access](https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/iokit_private.h): platform interface · Private input declarations used by boot-button detection. · `inject_launchd/iokit_private.h`
- [Task/Mach primitives](https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/task_primitives.c): process control · Low-level primitives for manipulating the launchd task. · `inject_launchd/task_primitives.c`
- [Task primitive API](https://github.com/theiphoneos1project/microinjector/blob/main/inject_launchd/task_primitives.h): internal header · `inject_launchd/task_primitives.h`
- **launchd task**: system process · Strong privilege boundary and injection target.

### In-process runtime

Loads payload behavior and exposes hooking APIs.

- [MicroLoader](https://github.com/theiphoneos1project/microinjector/blob/main/Loader/MicroLoader.m): in-process loader · Objective-C-aware loading stage inside injected processes. · `Loader/MicroLoader.m`
- [Safe-mode alert](https://github.com/theiphoneos1project/microinjector/blob/main/Loader/MISafeModeAlert.m): in-process recovery UI · Reports injected-runtime failures to the user. · `Loader/MISafeModeAlert.m`
- [Safe-mode alert API](https://github.com/theiphoneos1project/microinjector/blob/main/Loader/MISafeModeAlert.h): header · `Loader/MISafeModeAlert.h`
- [MicroInjector public API](https://github.com/theiphoneos1project/microinjector/blob/main/MicroInjector.h): native hooking API · Public API for injected code. · `MicroInjector.h`
- [MicroInjector runtime](https://github.com/theiphoneos1project/microinjector/blob/main/MicroInjector.c): hooking runtime · Provides function, memory, Objective-C, image, and symbol manipulation. · `MicroInjector.c`
- [Runtime internals](https://github.com/theiphoneos1project/microinjector/blob/main/MicroInjectorInternal.h): internal header · `MicroInjectorInternal.h`
- [Function hook engine](https://github.com/theiphoneos1project/microinjector/blob/main/HookFunction.c): native interception · Focused implementation of native function interception. · `HookFunction.c`
- [Substrate shims](https://github.com/theiphoneos1project/microinjector/blob/main/SubstrateShims.c): compatibility API · Maps Cydia Substrate-style payload APIs onto MicroInjector. · `SubstrateShims.c`
- **Injected payloads**: tweaks and injected code · Use native or Substrate-compatible APIs in process context.

### Build and package

Builds legacy armv6 artifacts and installer metadata.

- [Build rules](https://github.com/theiphoneos1project/microinjector/blob/main/Makefile): build entry point · Encodes clang, legacy SDK, armv6, and patched-linker requirements. · `Makefile`
- [PXL package manifest](https://github.com/theiphoneos1project/microinjector/blob/main/PxlPkg.plist): installer metadata · Packages the platform as a PXL installer artifact. · `PxlPkg.plist`

## Connections

- Launch daemon config → launchd trampoline: starts at boot
- launchd trampoline → launchd injector: establishes bootstrap
- Private IOKit access → Boot button detection: declares input access
- Boot button detection → launchd injector: abort signal · Held Home or volume buttons bypass injection.
- Task primitive API → Task/Mach primitives: defines interface
- Task/Mach primitives → launchd injector: provides task control
- launchd injector → launchd task: injects after guard passes
- launchd task → MicroLoader: loads in process
- MicroLoader → MicroInjector runtime: activates runtime
- Safe-mode alert API → Safe-mode alert: defines interface
- MicroLoader → Safe-mode alert: shows failure state
- Runtime internals → MicroInjector runtime: internal contracts
- Function hook engine → MicroInjector runtime: implements interception
- MicroInjector public API → MicroInjector runtime: public interface
- MicroInjector runtime → Injected payloads: native hooks and manipulation
- Substrate shims → MicroInjector runtime: adapts to runtime
- Substrate shims → Injected payloads: Substrate-compatible API
- Build rules → launchd trampoline: builds
- Build rules → launchd injector: builds
- Build rules → MicroLoader: builds
- Build rules → MicroInjector runtime: builds
- PXL package manifest → Launch daemon config: packages bootstrap config