dc072ad8f5
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.
74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# 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
|
||
|
||
1. Open in Xcode 26.3+ (iOS 17 SDK or later)
|
||
2. Run `xcodegen generate` to build the project file
|
||
3. Set your `DEVELOPMENT_TEAM` in `project.yml` or Xcode signing
|
||
4. Build & run the `ProxyApp` scheme on a device (packet tunnel extensions don't fully work in the simulator)
|
||
5. 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`
|
||
6. Tap **Start Proxy** on the home screen — iOS will prompt for VPN permission
|
||
7. 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](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.
|