Merge remote-tracking branch 'origin/main' into spec/peer-id-rotation

docs/TOR-INTEGRATION.md

@@ -1,47 +1,53 @@
-Tor-by-default integration (scaffold)
+# Tor integration
 
-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 vendors an Arti-backed Swift package under `localPackages/Arti`, including a Rust static-library xcframework linked by SwiftPM.
+## Overview
 
-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.
+Internet traffic — Nostr relay sockets and the geo-relay directory fetch — is routed through Tor by default, fail-closed: when Tor is wanted but not ready, requests queue rather than falling back to clearnet.
 
-Artifact maintenance
-- Binary provenance, rebuild steps, and current hashes are documented in `docs/ARTI-BINARY-PROVENANCE.md`.
+Tor is provided by **Arti, in-process**, vendored as a Swift package under `localPackages/Arti` wrapping a Rust static-library xcframework. There is no `tor` binary, no `torrc`, and no control port. A SOCKS5 listener on `127.0.0.1:39050` is the only interface.
+
+## Key pieces
+
+- **`TorManager`** — owns the Arti client and its data directory under Application Support, exposes the SOCKS port, and provides `awaitReady()`.
+  - `torEnforced` is compile-time: true unless `BITCHAT_DEV_ALLOW_CLEARNET` is defined. It is not set anywhere in `Configs/` or the project file, so release builds enforce.
+  - `isStarting`, `bootstrapProgress`, and `bootstrapSummary` describe an attempt in flight.
+  - `bootstrapDidStall` becomes true when an attempt spends its whole 75-second deadline without completing, and posts `.TorBootstrapDidStall`. This is the state a network that blocks Tor produces, and it is deliberately distinct from `isStarting`: without it the UI says "starting tor…" indefinitely. It is cleared on each new start or restart.
+- **`TorURLSession`** — a shared `URLSession` with the SOCKS proxy configured when proxying is on, and an unproxied session when it is off. `setProxyMode(useTor:)` is the switch, driven by `NetworkActivationService`.
+- **`NetworkActivationService`** — decides whether Tor may run at all. Tor starts when the activation policy permits it *and* the Tor preference is on. `persistedTorPreference(in:)` is a `nonisolated` read of that preference for callers off the main actor.
+
+Both network call sites go through `TorURLSession`: `NostrRelayManager` (relay websockets) and `GeoRelayDirectory` (directory CSV refresh). There is no other outbound network in the app or the share extension.
+
+## The Tor preference is user-visible
+
+The earlier version of this document said there are no user-visible settings. There is one: a **tor routing** toggle in settings, persisted under `networkActivationService.userTorEnabled`, defaulting to on.
+
+Turning it off is a real change in exposure, not a performance tweak. Every fail-closed guard is conditioned on the preference, so with it off:
+
+- relay websockets connect directly, and every relay operator sees the device IP — including relays carrying private messages;
+- the geo-relay directory fetch also goes direct.
+
+The settings UI states this while the toggle is off.
+
+`GeoRelayDirectory` keys its Tor wait on the *preference*, not on live readiness, and this distinction is load-bearing. With Tor off, waiting for a client that has been shut down would spend the full bootstrap timeout on every refresh and freeze the directory on its cached copy. With Tor on but not ready, the wait must still fail so the fetch is skipped rather than silently leaking the IP.
+
+## Relays
+
+Private messages target the built-in relay set plus any relays added by hand (`NostrRelaySettings`, capped at 8, `.onion` addresses accepted). The built-in set is four well-known clearnet hostnames, so a filter blocking four names would otherwise end internet-delivered private messages until a new build shipped.
+
+## Artifact maintenance
+
+- Binary provenance, rebuild steps, and current hashes: `docs/ARTI-BINARY-PROVENANCE.md`, enforced by `.github/workflows/arti-provenance.yml`.
 - The xcframework must include iOS device, iOS simulator, and macOS arm64 slices.
-- Any refresh should review the Rust source, `Cargo.lock`, generated header, build script, and new hashes together.
+- Any refresh reviews the Rust source, `Cargo.lock`, generated header, build script, and new hashes together. A binary-only update is not acceptable.
 
-Verification
-   - 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.
+## Known gap: no bridges or pluggable transports
 
-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.
+`arti-client` is built with `default-features = false` and features `["tokio", "rustls"]` only — no `pt-client`, no `bridge-client` — and `arti-bitchat/src/lib.rs` bootstraps from stock configuration with no bridge lines and no configurable directory authorities.
 
-torrc template
-The generated torrc (under Application Support/bitchat/tor/torrc) is:
+So in a country that blocks Tor by blocking the public relays and directory authorities, bootstrap never completes. The app reports that clearly now instead of appearing to start forever, and the BLE mesh is unaffected, but there is no circumvention path: obfs4, snowflake, and meek are all unavailable.
 
-  DataDirectory <AppSupport>/bitchat/tor
-  ClientOnly 1
-  SOCKSPort 127.0.0.1:39050
-  ControlPort 127.0.0.1:39051
-  CookieAuthentication 1
-  AvoidDiskWrites 1
-  MaxClientCircuitsPending 8
+Closing this means enabling the pluggable-transport features, plumbing bridge configuration through the FFI and a settings surface, and rebuilding the xcframework under the pinned toolchain with a provenance-manifest update. That is the single largest remaining gap in censorship resilience for the internet transport.
 
-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.
+## Dev bypass (local only)
 
-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.
+Define the Swift compiler flag `BITCHAT_DEV_ALLOW_CLEARNET` to allow direct network access without Tor while developing. Never enable it in release builds.

docs/VERIFYING-A-BUILD.md

@@ -0,0 +1,77 @@
+# Verifying bitchat
+
+This document is about a specific risk: getting a copy of bitchat that someone has modified.
+
+It matters because the repository has been the target of takedown demands. When a repository or a releases page becomes unavailable, mirrors appear, and people who need the app during a shutdown install whatever they can find. That is exactly the moment a trojaned build reaches the people with the most to lose. A modified bitchat can log plaintext, ship keys off the device, or weaken the mesh, and it will look and behave normally while doing it.
+
+The honest summary is short. **Source can be verified. Compiled apps cannot, unless they come from the App Store.** Everything below elaborates on that.
+
+## Getting the app
+
+In order of how much verification is possible:
+
+1. **The App Store.** Apple verifies the developer signature, and the binary cannot be altered without breaking it. This is the only channel where a compiled build is verifiable end to end, and it is the right recommendation for almost everyone.
+2. **Build it yourself from verified source.** See below. Requires a Mac and Xcode, and gives you the strongest guarantee if you can do it.
+3. **A compiled build from anywhere else.** Not verifiable. See "Builds from other sources".
+
+## Verifying source
+
+Every tagged release has a `SOURCE-MANIFEST.txt` produced by `.github/workflows/source-manifest.yml`. It records the tag, the commit, the git tree hash, and a SHA-256 for every tracked file.
+
+Check a copy of the source against it:
+
+```sh
+# From the root of the source you obtained
+grep -v '^#' SOURCE-MANIFEST.txt > /tmp/files.sha256
+shasum -a 256 -c /tmp/files.sha256
+```
+
+Any `FAILED` line means that file differs from the released source. Investigate before building.
+
+The single value that covers the whole tree is the git tree hash in the manifest header:
+
+```sh
+git rev-parse HEAD^{tree}   # must equal the "tree:" line in the manifest
+```
+
+The manifest itself carries a provenance attestation tying it to the workflow run that produced it, so a manifest handed to you along with a mirror is checkable too:
+
+```sh
+gh attestation verify SOURCE-MANIFEST.txt --repo permissionlesstech/bitchat
+```
+
+That last step is what makes this resistant to a hostile mirror. Without it, whoever gives you the source can give you a matching manifest.
+
+### If the manifest is unavailable
+
+Compare against a commit instead. Git object hashes cover content and history, so if you can obtain the expected commit hash through any channel you trust — a second mirror, a maintainer's post elsewhere, someone who cloned earlier — then:
+
+```sh
+git fetch <mirror> --tags
+git rev-parse v1.2.3        # compare against the hash you trust
+git verify-tag v1.2.3       # if the tag is signed
+```
+
+A mirror whose history matches a commit hash you trust from elsewhere is a faithful mirror.
+
+## Builds from other sources
+
+If you have an `.ipa`, an `.apk`, or a Mac app from a forum, a chat group, a file locker, or any mirror, you cannot verify it, and this project cannot help you verify it. There is no published signing key for compiled builds and no reproducible-build pipeline, so there is nothing to compare a binary against.
+
+What to do instead, in order of preference: install from the App Store; build from verified source; or, if neither is possible, treat that build as untrusted — assume anything you type into it may be disclosed, do not use it for anything sensitive, and do not carry it somewhere it being on your phone is itself a risk.
+
+Do not rely on the app looking right. A modified build has no reason to look different.
+
+## For maintainers
+
+Cutting a release:
+
+- Push the tag. `source-manifest.yml` runs and attaches `SOURCE-MANIFEST.txt` to the release; if the release does not exist yet, collect the manifest from the workflow artifact and attach it when you publish.
+- Sign the tag (`git tag -s`). A signed tag lets anyone verify the release came from a key you control, independent of GitHub. This needs a published key fingerprint to be useful — see the gap below.
+- Note the commit hash somewhere outside this repository. If the repository is taken down, a hash recorded elsewhere is what lets people verify a mirror.
+
+Known gaps, so nobody assumes more protection than exists:
+
+- **No published signing key.** Tags are not currently verifiable against a known key. Publishing a fingerprint through channels independent of GitHub, and signing tags with it from then on, is the missing piece.
+- **No verifiable compiled builds outside the App Store.** Closing this needs either a signed-and-notarized release pipeline or a reproducible build, and until one exists the guidance above stands.
+- **No non-GitHub source mirror.** Every remote for this project is on the platform the takedown demands were served to. A mirror on independent infrastructure, published before it is needed, would mean a takedown does not remove the ability to verify.

docs/privacy-assessment.md

@@ -63,6 +63,9 @@ Public archives contain content already intended for public mesh/board distribut
 - When mesh bridge is enabled, public mesh messages not marked “nearby only” are signed under a per-cell Nostr identity and published to a neighborhood rendezvous geohash. Presence and public bridge traffic therefore expose a coarse area to relays and participants.
 - A bridge gateway can carry signed bridge/location events and opaque courier drops for nearby mesh-only peers. It cannot validly publish a neighbor's radio-only message because the author must first sign the bridge event.
 
+- Relays added by hand persist in local preferences (`nostr.customRelays`, at most 8, normalized on read) and are wiped on panic. An added relay names an operator someone chose to route through, so it is treated as sensitive local state rather than inert configuration. `.onion` addresses are accepted, which is the point: the four built-in relays are well-known clearnet hostnames and a filter blocking four names would otherwise end internet-delivered private messages until a new build shipped.
+- Turning the Tor preference off routes relay sockets and the relay-directory fetch directly, disclosing the device IP to every relay operator including those carrying private messages. The settings UI states this while the preference is off.
+
 Residual risk: Nostr relay retention and logging are outside project control. Public events may be copied indefinitely. Timing, coarse location, and participation can be correlated even when content is encrypted or per-cell identities are used.
 
 ## Location
@@ -106,7 +109,7 @@ Not addressed, and deliberately out of scope here:
 
 ## Panic Wipe Coverage
 
-The panic action clears identity/session state, preferences, location state, groups, prekeys, outbox mail, courier mail, bridge dedup state, gossip archive, board data, managed media, and active subscriptions/transports. Managed media deletion completes synchronously, after active media work has been invalidated. Keychain secrets use device-only accessibility, and an install marker detects and clears app keys that survive uninstall before a later reinstall can use them. New persistent stores must add an explicit wipe hook and a regression test.
+The panic action clears identity/session state, preferences, location state, groups, prekeys, outbox mail, courier mail, bridge dedup state, gossip archive, board data, managed media, hand-added relays, and active subscriptions/transports. Managed media deletion completes synchronously, after active media work has been invalidated. Keychain secrets use device-only accessibility, and an install marker detects and clears app keys that survive uninstall before a later reinstall can use them. New persistent stores must add an explicit wipe hook and a regression test.
 
 ## Release Review Checklist