Files

Trey t dc072ad8f5 Add CLAUDE.md and README

CLAUDE.md documents architecture, build flow, proxy pipeline,
IPC/logging conventions, and gotchas for future Claude sessions.
README gives a user-facing overview, setup steps, and stack.

2026-04-11 12:55:08 -05:00

3.5 KiB

Raw Permalink Blame History

Proxy

An on-device iOS HTTP/HTTPS proxy with MITM decryption. Inspect every request your phone makes, from your phone. No computer required.

Think Proxyman or Charles, but running entirely on-device through a Network Extension.

Features

Live traffic capture — see every request/response grouped by domain as it happens
TLS decryption — per-domain leaf certs signed by an on-device root CA, with LRU caching
Auto-pinning detection — domains that fail TLS (SSL-pinned apps) fall back to passthrough automatically and get listed in the Pinned tab
Rules — block list, SSL-proxying allow list, Map Local, DNS spoofing, breakpoints
Compose — craft arbitrary HTTP requests, import from curl, replay captured requests
Rich viewers — JSON tree, hex view, headers, gzip/brotli decoding
App lock — Face ID / Touch ID gate
iPhone + iPad — adaptive layout with sidebar on iPad, tabs on iPhone

How it works

   App traffic
        │
        ▼
   NEPacketTunnelProvider  ──────►  NEProxySettings → 127.0.0.1:PORT
                                          │
                                          ▼
                              SwiftNIO ProxyServer (in the extension)
                                          │
                        ┌─────────────────┼─────────────────┐
                        ▼                 ▼                 ▼
                  Plain HTTP         CONNECT +         CONNECT +
                  (capture)          MITM decrypt      passthrough
                                     (leaf cert)       (pinned domains)

The packet tunnel doesn't route IP — it just installs a local proxy redirect in the system network settings. All traffic hits the in-process SwiftNIO server, where it's parsed, captured into SQLite (via GRDB), and forwarded upstream. TLS is decrypted by generating a leaf cert per SNI, signed by a root CA the user installs into their device trust store.

Setup

Open in Xcode 26.3+ (iOS 17 SDK or later)
Run xcodegen generate to build the project file
Set your DEVELOPMENT_TEAM in project.yml or Xcode signing
Build & run the ProxyApp scheme on a device (packet tunnel extensions don't fully work in the simulator)
Inside the app, tap More → Install Certificate, follow the Safari prompt to install the profile, then go to Settings → General → About → Certificate Trust Settings and enable full trust for ProxyCA
Tap Start Proxy on the home screen — iOS will prompt for VPN permission
Browse. Watch the traffic roll in.

Project structure

App/ — SwiftUI entry point, AppState, adaptive ContentView
PacketTunnel/ — NEPacketTunnelProvider extension
ProxyCore/ — static framework with the NIO pipeline, GRDB data layer, and shared utilities
UI/ — SwiftUI screens (Home, Pin, Compose, More)
project.yml — xcodegen config (edit this, not the .xcodeproj)

See CLAUDE.md for architecture details, conventions, and gotchas.

Stack

SwiftUI (iOS 17+)
SwiftNIO / SwiftNIOSSL / SwiftNIOExtras
swift-certificates / swift-crypto (CA + leaf cert generation)
GRDB (SQLite in the App Group container)
Network Extension (NEPacketTunnelProvider)
os.Logger for structured logging across app + extension

Status

Personal project. Not App Store–distributed (Network Extensions with packet-tunnel-provider require a provisioning profile).

License

Private.

3.5 KiB Raw Permalink Blame History Unescape Escape