eae01ef9d8
* Validate relay-directory changes in PR CI The weekly automation validates a relay snapshot before it pushes its branch, but that check lives inside the scheduled job. A change to the reviewed relay directory that arrives as a pull request is validated by nothing at all, which is the ground two relay-data PRs were closed on: "PR CI doesn't run the validator, and untraceable relay-directory updates aren't something we can merge on faith" (#1632, also #1673). This runs the validator on a pull request touching relays/ or the validator itself, against the base branch's reviewed copy, and publishes the row count, unique-relay count and SHA-256 to the job summary. The hash is the point: the relay automation already publishes one for every snapshot it proposes, so a reviewer can now match a proposed file against it instead of taking provenance on faith. The gate deliberately runs the base branch's validator rather than the pull request's copy of it. Otherwise a change that edits the data and the validator together certifies itself -- dropping 86% of the directory passes if the same commit relaxes MIN_BASELINE_FRACTION, and the summary still reports "validated". The scheduled job validates from a main checkout for the same reason. The pull request's own validator is still exercised by the unit-test step. A pull_request run executes the workflow definition from the pull request's own head, so a pull request can always edit this file and change its own gate. That path is visible in the diff, which is what review is for; what the reviewed-validator gate closes is the quiet one. Read-only and never pull_request_target: the job runs PR-authored code, so it holds no write scope and no secrets. checkout is @v5 like the other read-only PR workflows rather than SHA-pinned, since that pin exists to protect the write-capable token in fetch_georelays.yml. What it catches: malformed rows, out-of-range coordinates, insecure hosts, conflicting duplicate relays, and snapshots that lose half or double the baseline's relays. What it does not: a re-ordered file whose rows are each valid still passes -- with a different hash, which the summary makes visible. The accompanying test asserts the job's security-relevant shape as text, following the precedent in test_fetch_georelays_workflow.py: the trigger, the absent write scope, --output never pointed at the tracked CSV, and that the gate reads the validator from the base branch. * Split the gate from the code under review Codex review on d627b9f found three holes, all confirmed by rehearsal. The gate ran the base branch's validator, but read the candidate from the worktree and ran the pull request's unit tests first. A test file that rewrites relays/online_relays_gps.csv at import time therefore decided what the gate validated: the summary reported 441 rows and the hash of a file the pull request never proposed, exit 0, while the 60-row CSV in the commit was what would merge. The published hash is the whole argument for reviewing relay data on evidence, so a hash that can describe different bytes than the ones merging is worse than no hash at all. The workflow is now two jobs with an explicit split: - gate is the trust boundary. It checks out the base commit, so nothing the pull request wrote is present to run, and reads the candidate as a git object pinned to the event's head SHA instead of from a worktree. Both inputs come from the event, so a base branch that advances while the job is queued cannot change the verdict. - proposed-validator runs pull-request code, so it is not a trust boundary. It runs the unit tests and, new here, the proposed validator against the real directory. Without that a validator change is only ever exercised against small synthetic fixtures: capping MAX_ROWS at 400 passes the unit tests and the gate, then breaks the weekly automation after merge with "CSV exceeds 400 data rows". Checking out the base commit also removes last round's git show of the validator -- at base.sha the reviewed validator is simply the one in the workspace. Rehearsed per case, with each branch's diff verified first: a malicious PR that swaps the CSV from a test now exits 1 where it previously passed green; the current automation snapshot still validates to the hash published in #1617; a corrupt CSV, a stricter validator, and a CI-only change all land where they should.
bitchat
A decentralized peer-to-peer messaging app with dual transport architecture: local Bluetooth mesh networks for offline communication and internet-based Nostr protocol for global reach. No accounts, no phone numbers, no central servers. It's the side-groupchat.
Getting a copy you can trust
Install from the App Store, or build from source you have verified. A compiled build from anywhere else cannot be verified — see Verifying bitchat for how to check source against the per-release hash manifest, and for what to do if that is the only build you can get.
This matters more than it usually would: this repository has been the target of takedown demands, and when a repository or releases page disappears, mirrors appear that nobody can check.
License
This project is released into the public domain. See the LICENSE file for details.
Features
- Dual Transport Architecture: Bluetooth mesh for offline + Nostr protocol for internet-based messaging
- Location-Based Channels: Geographic chat rooms using geohash coordinates over global Nostr relays
- Intelligent Message Routing: Automatically chooses best transport (Bluetooth → Nostr fallback)
- Decentralized Mesh Network: Automatic peer discovery and multi-hop message relay over Bluetooth LE
- Privacy First: No accounts, no phone numbers, no servers. Note that the mesh does use a persistent per-device identifier derived from your identity key — see the whitepaper on identity and metadata for what a nearby radio can observe
- Private Message End-to-End Encryption: Noise Protocol for mesh, BitChat private envelopes for Nostr fallback
- IRC-Style Commands: Familiar
/slap,/msg,/whostyle interface - Universal App: Native support for iOS and macOS
- Emergency Wipe: Triple-tap to instantly clear all data
- Performance Optimizations: LZ4 message compression, adaptive battery modes, and optimized networking
Technical Architecture
BitChat uses a hybrid messaging architecture with two complementary transport layers:
Bluetooth Mesh Network (Offline)
- Local Communication: Direct peer-to-peer within Bluetooth range
- Multi-hop Relay: Messages route through nearby devices (max 7 hops)
- No Internet Required: Works completely offline in disaster scenarios
- Noise Protocol Encryption: End-to-end encryption, with forward secrecy for live sessions (store-and-forward mail is sealed without it — see the whitepaper)
- Binary Protocol: Compact packet format optimized for Bluetooth LE constraints
- Automatic Discovery: Peer discovery and connection management
- Adaptive Power: Battery-optimized duty cycling
Nostr Protocol (Internet)
- Global Reach: Connect with users worldwide via internet relays
- Location Channels: Geographic chat rooms using geohash coordinates
- 440+ Relay Network: Distributed across the globe for reliability
- BitChat Private Envelopes: App-specific encrypted private messages over Nostr relays
- Ephemeral Keys: Fresh cryptographic identity per geohash area
BitChat's private-envelope format is proprietary and is not NIP-17,
NIP-44, or NIP-59 compatible. It uses Nostr as a relay transport but only
interoperates with BitChat clients: private payloads travel inside kind-1059
events whose v2:-prefixed content is a BitChat-specific XChaCha20-Poly1305
construction, not NIP-44 encryption.
Channel Types
mesh #bluetooth
- Transport: Bluetooth Low Energy mesh network
- Scope: Local devices within multi-hop range
- Internet: Not required
- Use Case: Offline communication, protests, disasters, remote areas
Location Channels (block #dr5rsj7, neighborhood #dr5rs, country #dr)
- Transport: Nostr protocol over internet
- Scope: Geographic areas defined by geohash precision
block(7 chars): City block levelneighborhood(6 chars): District/neighborhoodcity(5 chars): City levelprovince(4 chars): State/provinceregion(2 chars): Country/large region
- Internet: Required (connects to Nostr relays)
- Use Case: Location-based community chat, local events, regional discussions
Direct Message Routing
Private messages use intelligent transport selection:
-
Bluetooth First (preferred when available)
- Direct connection with established Noise session
- Fastest and most private option
-
Nostr Fallback (when Bluetooth unavailable)
- Uses recipient's Nostr public key
- BitChat's app-specific private-envelope encryption
- Routes through global relay network
-
Smart Queuing (when neither available)
- Messages queued until transport becomes available
- Automatic delivery when connection established
For detailed protocol documentation, see the Technical Whitepaper.
Setup
Option 1: Using Xcode
open bitchat.xcodeproj
For a signed device build, create your ignored local configuration and replace the example team ID with your Apple Developer Team ID:
cp Configs/Local.xcconfig.example Configs/Local.xcconfig
Local.xcconfig.example derives unique app and App Group identifiers from that
team ID. The entitlement files already reference $(APP_GROUP_ID), so tracked
project or entitlement files do not need to be edited.
Useful command-line checks from the repository root:
# macOS Debug build without signing
xcodebuild -project bitchat.xcodeproj -scheme "bitchat (macOS)" \
-configuration Debug CODE_SIGNING_ALLOWED=NO build
# Full SwiftPM test suite
swift test
# iOS simulator tests
xcodebuild -project bitchat.xcodeproj -scheme "bitchat (iOS)" \
-sdk iphonesimulator \
-destination 'platform=iOS Simulator,name=iPhone 17' test
If iPhone 17 is unavailable, choose an installed simulator from:
xcodebuild -showdestinations -project bitchat.xcodeproj -scheme "bitchat (iOS)"
Option 2: Using just
brew install just
just check
just run
just build and just run use the current bitchat (macOS) scheme and keep
Xcode output in the ignored .DerivedData/ directory. They never patch source,
project, configuration, or entitlement files.
just clean removes only .DerivedData/ and .build/. It does not invoke Git
or restore tracked files, so uncommitted work is preserved. just test runs the
SwiftPM suite and just test-ios runs the iPhone 17 simulator suite.
Localization
- App localizations live in
bitchat/Localizable.xcstrings. - Share extension strings are separate in
bitchatShareExtension/Localization/Localizable.xcstrings. - Prefer keys that describe intent (
app_info.features.offline.title) and reuse existing ones where possible. - Run
xcodebuild -project bitchat.xcodeproj -scheme "bitchat (macOS)" -configuration Debug CODE_SIGNING_ALLOWED=NO buildto compile-check any localization updates.