bitchat/docs/TOR-INTEGRATION.md at main

mirror of https://github.com/jackjackbits/bitchat.git synced 2026-04-21 03:02:15 -04:00

Files

jack 5f44af19da tor by default, small (#564 )

* feat(tor): Tor-by-default scaffold and integration

- Add TorManager with static/dlopen start, torrc generation, SOCKS probe
- Add TorURLSession; route Nostr/Web fetches via SOCKS proxy
- Add chat system messages for Tor status; show progress (macOS) and ready
- Disable ControlPort bootstrap monitor on iOS; keep it on macOS
- Make Tor waits non-blocking; avoid main-actor stalls on startup
- Queue & flush Nostr subscriptions on relay connect; skip duplicates
- Always rewrite torrc at launch to fix iOS container path mismatches
- Link libz; add project wiring for tor-nolzma.xcframework
- Minor fixes: SOCKS probe resumeOnce guard, entitlement for network.server (macOS)

* iOS: deterministic Tor recovery + 100% gating; BLE-first; session rebuild

- Restart/wake Tor on foreground via ControlPort (ACTIVE/SHUTDOWN),
  avoid restarts during bootstrap; add NWPathMonitor to trigger checks
- Use NWConnection control polling for GETINFO; remove blocking CFStream
  readers to avoid QoS inversions; compute readiness from SOCKS + 100%
- Rebuild TorURLSession on resume; reset Nostr connections to rebind
- Gate all internet after full bootstrap; keep BLE mesh startup fast
- Fix Swift 6 capture issues; hop UI updates to @MainActor
- Remove Tor progress spam; persist initial "starting tor..." system message

* UI: show Tor system messages only in geohash channels (not mesh)

- Gate "starting tor..." and readiness/timeout messages to geohash view
- Add helper addGeohashOnlySystemMessage() to avoid posting to mesh timeline
- Persist system messages in geohash backing store via addPublicSystemMessage()

* Relays: treat repeated -1011 handshake failures as permanent; skip reconnects

- Classify NSURLErrorBadServerResponse as permanent and stop retrying
- Filter permanently-failed relays from subscribe/connect attempts
- Avoid reconnect scheduling for permanently failed relays

* Embed Tor via tor_api; deterministic restart + Nostr gating; add Tor notifications

- Run Tor via tor_api in a dedicated thread with OwningControllerFD
- Cleanly stop Tor on background; restart on .active (single instance)
- Avoid fallback to tor_main/dlopen; add is-running check to prevent duplicates
- Fix argv lifetime in C glue to avoid strcmp crash on start
- Gate Nostr connect/subscribe/send until Tor is fully ready
- Rebuild URLSession + reset relays after Tor readiness (scene-based)
- Remove TorDidBecomeReady double-reset and appDidBecomeActive resubscribe
- Add TorWillRestart/TorDidBecomeReady notifications and chat system messages
- Debounce path-change restarts; ACTIVE poke first; coalesce subs; cancel stale reconnect timers
- Project: add CTorHost.c and TorNotifications.swift to targets; fix libz.tbd path

* Defer Nostr setup logs until Tor is ready; fix subscribe coalescing and reconnect generation

- Move "Connecting to Nostr relays" log after awaitReady()
- Log "Queuing subscription" when Tor not ready; only coalesce when handler exists
- Clear coalescer on unsubscribe
- Cancel stale reconnect timers using connectionGeneration
- Remove app-level TorDidBecomeReady reset to avoid duplicate reconnects
- Debounce path-change restarts

* Gate Nostr init/subscription logs until Tor is ready

- ChatViewModel: await Tor readiness before initializing Nostr and logging
- Only log GeoDM subscription when Tor is ready to avoid early noise

* Make Nostr connect single-sourced; defer DM subscription until connected

- Remove duplicate connect call from ChatViewModel; let scene-based flow connect
- Setup DM subscription once on first connection via  sink
- Reduce early subscription send/cancel noise after Tor restarts

* On launch, queue Nostr subscriptions without initiating connects; let centralized connect handle it

- In subscribe(), if no connections exist, just list relays and queue subs
- Avoids early send/cancel churn before connect() runs post-Tor-ready

* Always queue subscriptions and flush on connection; avoid immediate sends

- Prevents early send/cancel churn at launch and during reconnects
- If relays are already connected, flush immediately; otherwise pending until connected

* UI: scope Tor restart messages to geohash channels; skip initial foreground restart on cold launch to avoid confusing system message in #mesh

* geo: disable background sampling + notifications\n- Gate sampling to foreground only (beginGeohashSampling, watchers)\n- Suppress geohash activity notifications unless app is active\n- Stop sampling explicitly on background scene phase

* Update BitchatApp.swift

Co-authored-by: asmo <asmogo@protonmail.com>

* Update BitchatApp.swift

Co-authored-by: asmo <asmogo@protonmail.com>

* Update BitchatApp.swift

Co-authored-by: asmo <asmogo@protonmail.com>

* Update bitchat/BitchatApp.swift

Co-authored-by: asmo <asmogo@protonmail.com>

* Update bitchat/BitchatApp.swift

Co-authored-by: asmo <asmogo@protonmail.com>

* fix(iOS App): resolve merge artifacts in scenePhase handler\n- Remove duplicate didEnterBackground state\n- Fix switch/if braces and logic for foreground restart gating

---------

Co-authored-by: jack <jackjackbits@users.noreply.github.com>
Co-authored-by: asmo <asmogo@protonmail.com>

2025-09-11 19:08:43 +02:00

3.6 KiB

Raw Permalink Blame History

Tor-by-default integration (scaffold)

Overview

All network traffic is routed via a local Tor SOCKS5 proxy by default, with fail-closed behavior when Tor isn’t ready. There are no user-visible settings.
This repo now includes a minimal TorManager and TorURLSession to make dropping in an embedded Tor framework straightforward.

Key pieces

TorManager
- Boots Tor, manages a DataDirectory under Application Support, exposes SOCKS at 127.0.0.1:39050, and provides awaitReady().
- Fails closed by default until Tor is bootstrapped. For local development only, define BITCHAT_DEV_ALLOW_CLEARNET to bypass Tor.
TorURLSession
- Provides a shared URLSession configured with a SOCKS5 proxy when Tor is enforced/ready.
- NostrRelayManager and GeoRelayDirectory now use this session and await Tor readiness before starting network activity.

Drop‑in steps

Build or obtain a small Tor framework
- Recommended: Tor C (client-only) with static linking and dead-strip.
- Configure Tor with a minimal feature set: ./configure
  --enable-static
  --disable-asciidoc --disable-unittests --disable-manpage
  --disable-zstd --disable-lzma --enable-zlib
  --disable-systemd --disable-ptrace --disable-seccomp CFLAGS="-Os -fdata-sections -ffunction-sections"
  LDFLAGS="-Wl,-dead_strip"
- Build a tiny OpenSSL/LibreSSL (no engines, strip symbols) or reuse system crypto where permitted on macOS.
Add the framework to Xcode targets
- Drop your xcframework into Frameworks/. The project is prewired in project.yml to link/embed Frameworks/tor-nolzma.xcframework (rename yours to match, or update the path).
- Ensure the binary includes the slices you need (iOS device/simulator and/or macOS). If your xcframework lacks simulator slices, you can still build/run on device or macOS arm64; simulator will fail to link.
- On iOS, it will be embedded and signed automatically.
Wire Tor bootstrap in TorManager.startTor()
- Two paths are already implemented:
  - If a module named Tor is present (iCepa API), it starts TORThread directly.
  - Otherwise, it attempts a dynamic load (dlopen) of a bundled framework binary named tor-nolzma.framework/tor-nolzma (or Tor.framework/Tor), resolves tor_run_main, and launches Tor on a background thread.
- TorManager writes a torrc and then probes 127.0.0.1:39050 until ready.
Verify networking
- On app launch, TorManager.startIfNeeded() is called implicitly by awaitReady().
- NostrRelayManager.connect() awaits readiness, then creates WebSocket tasks via TorURLSession.shared.
- GeoRelayDirectory.fetchRemote() awaits readiness, then fetches via TorURLSession.shared.
Optional macOS optimization
- Detect a system Tor binary (e.g., /opt/homebrew/bin/tor) and run it as a subprocess to avoid bundling. Keep the embedded fallback for portability.

torrc template The generated torrc (under Application Support/bitchat/tor/torrc) is:

DataDirectory /bitchat/tor ClientOnly 1 SOCKSPort 127.0.0.1:39050 ControlPort 127.0.0.1:39051 CookieAuthentication 1 AvoidDiskWrites 1 MaxClientCircuitsPending 8

Dev bypass (local only)

To temporarily allow direct network without Tor for local development:
- Add Swift compiler flag: BITCHAT_DEV_ALLOW_CLEARNET
- This enables a clearnet session in TorURLSession when Tor isn’t present.
- Never enable this in release builds.

Notes

We intentionally do not change any app-level APIs: consumers simply use TorURLSession via existing code paths.
When Tor is missing in release builds, the app will not connect (fail-closed), logging a clear reason.

3.6 KiB Raw Permalink Blame History Unescape Escape

3.6 KiB

Raw Permalink Blame History