opa334/dopamine

Purpose and Entry Points

Dopamine is a rootless, semi-untethered iOS jailbreak for supported arm64/arm64e versions. The primary user-facing entry point is the Objective-C UIKit app; its process starts at Application/Dopamine/main.m, delegates lifecycle setup to Application/Dopamine/App Delegates/DOAppDelegate.m, and presents the main jailbreak flow through Application/Dopamine/UI/DOMainViewController.m.

App Orchestration and State

The app’s jailbreak layer separates user preferences, device/environment handling, exploit selection, and execution orchestration. DOJailbreaker is the high-level coordinator; DOExploitManager selects compatible exploit providers; DOEnvironmentManager manages jailbreak environment state. Key paths:

• Application/Dopamine/Jailbreak/DOJailbreaker.m

• Application/Dopamine/Jailbreak/DOExploitManager.m

• Application/Dopamine/Jailbreak/DOEnvironmentManager.m

Control flow is broadly UI action → preference/environment checks → selected exploit → privileged bootstrap/install/startup work. This boundary keeps UIKit code separate from kernel-facing operations.

Kernel Exploit Provider Layer

Multiple exploit modules expose a common app-facing abstraction, allowing runtime selection by device/OS compatibility. Implementations contain low-level C/Objective-C and assembly interacting with kernel primitives, Mach ports, IOKit objects, GPU surfaces, networking, or ANE interfaces. Representative providers:

• Application/Dopamine/Exploits/kfd/kfd.m

• Application/Dopamine/Exploits/Titan/Titan.m

• Application/Dopamine/Exploits/weightBufs/weightBufs.m

This is a security-critical boundary: exploit-specific kernel read/write acquisition should remain isolated from generic jailbreak and UI logic.

Bootstrap and Rootless Installation

After exploitation, the app bootstrapper prepares the rootless userspace, including compressed payload handling and packaged package-manager assets. It uses bundled resources and jailbreak-side deployment logic rather than a remote application backend. Core paths:

• Application/Dopamine/Jailbreak/DOBootstrapper.m

• Application/Dopamine/Jailbreak/DOBootstrapper+zstd.m

• Application/Dopamine/Resources/sileo.deb

The resulting environment depends on BaseBin binaries, launch daemons, hooking frameworks, and downstream Debian packages.

Privileged Runtime: BaseBin and libjailbreak

BaseBin builds the installed privileged runtime. libjailbreak centralizes kernel primitives, jailbreak-root path resolution, trust-cache handling, code-signing support, and Mach/XPC clients. The dopamine executable is a lower-level launcher/runtime companion:

• BaseBin/libjailbreak/src/libjailbreak.h

• BaseBin/libjailbreak/src/kernel.c

• BaseBin/dopamine/src/main.m

This layer bridges exploit-acquired privileges to durable rootless system behavior and should be treated as the principal ABI boundary for installed components.

System Integration, Daemons, and Hooks

Persistent/system-wide behavior is implemented through launchd hooking, injected hooks, and service processes. launchdhook contains launchd, spawn, XPC, jetsam, and daemon-hook paths; hookd is a dedicated daemon; BaseBin includes launch daemon definitions:

• BaseBin/launchdhook/src/main.m

• BaseBin/launchdhook/src/jbserver/jbserver_mach.c

• BaseBin/_external/basebin/LaunchDaemons/com.opa334.Dopamine.startup.plist

Material platform services are iOS launchd, Mach IPC, XPC, kernel APIs, and private frameworks. Hooks must coordinate through the shared libjailbreak interfaces rather than duplicating privilege or root-path assumptions.

Build and Packaging Topology

The repository builds three deliverable strata: the iOS application, BaseBin runtime, and installable packages. Top-level and component Makefiles coordinate native compilation; the app is an Xcode project. A Swift command-line tool merges Mach-O content for runtime hooking/build preparation:

• Makefile

• Application/Dopamine.xcodeproj/project.pbxproj

• BaseBin/MachOMerger/Sources/MachOMerger/main.swift

Packages supplies rootless support packages such as libroot and a kernel-read/write provider, completing the installed dependency graph.