mirror of
https://github.com/permissionlesstech/bitchat.git
synced 2026-09-19 05:00:48 +00:00
b7c6f42b3a
* Gate connected-link trust on a secure session; deny forged direct announces the connected shortcut Residual gap after the rotation-heal containment (#1401): "verified direct" announces prove the signature but not directness — TTL is unsigned — so a malicious connected peer can replay a victim's fresh announce with its TTL restored. When the victim has no live link, the replayer's link rebinds to the victim's ID and reads as "connected", and MessageRouter's connected fast-path then trusts it outright: every DM stalls on a Noise handshake the replayer can never complete and is silently lost while showing "sent". Router-level trust gate (no wire change): - Transport gains canDeliverSecurely(to:) — BLE answers with an established Noise session; Nostr keeps its prompt-delivery predicate; the protocol default forwards to canDeliverPromptly for transports without a forgeable link layer. - MessageRouter.sendPrivate only trusts a connected link outright when it can deliver securely; otherwise it still sends (kicking the handshake on a genuine link) but retains a copy and hands a sealed copy to couriers, like the reachable path. flushOutbox gets the same gate so a flush over an insecure link resends instead of dropping the retained copy. Presence hardening (defense in depth): a "direct" announce arriving on a link already bound to a different peer no longer shortcuts the claimed peer into "connected" — only real link state does. Genuine first-contact and direct announces are unaffected; only the ambiguous heal path loses the forgeable shortcut. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Harden the insecure-link outbox bound; document the second-replay presence gap and the courier metadata tradeoff Review follow-ups on the canDeliverSecurely gate: - flushOutbox no longer counts connected-but-insecure flushes toward the maxSendAttempts drop: the message was actually transmitted over a live link, so a peer whose Noise handshake stalls across reconnect flapping must not burn through the cap and lose the store-and-forward copy the gate exists to preserve. Retention stays bounded by the 24h outbox TTL and the per-peer FIFO cap; acks still clear it. Attempt-counting stays for reachable-only (heuristic) sends. Regression test: >8 connected- insecure flushes keep the retained copy, drop callback never fires. - Document the known second-replay presence gap: linkBoundToOtherPeer reads the binding before rebindLinkAfterVerifiedDirectAnnounce steals the link, so once a first replay has rebound a link to an absent victim's ID, a second replay marks the victim connected. Presence display only — DMs stay on the retain+courier path via the router gate. Not closed at the announce layer because the post-rebind state is indistinguishable from a legitimate rotation/reconnect heal (a supported, field-verified flow). Covered by a two-announce test. - Note the accepted courier-spray metadata tradeoff at the connected- insecure send: nearby verified peers receive a sealed copy (they learn a DM exists, never its content), cleared on ack. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Promote a healed rotation to connected; normalize the secure-delivery probe; retain Codable properties in Periphery Codex review follow-ups on 5017c232: - P1: a legitimate rotation announce necessarily arrives on a link still bound to the OLD peer ID, so the linkBoundToOtherPeer denial stored the new identity as disconnected — and the rebind only fixed link state, never the registry. A healed rotation then read as disconnected until the peer happened to announce again. rebindLinkAfterVerifiedDirect- Announce now promotes the rebound identity to connected after the containment checks pass (registry markConnected + topology/snapshot/ peer-list refresh; the .peerConnected UI event already fired from the announce path). This consciously moves the forged-presence residue from second-replay to first-successful-rebind — bounded by the rebind containment (never steals a live identity, one rebind per link per cooldown) and still display-only: DMs stay gated on canDeliverSecurely. Comments and the pinned tests updated; new regression test covers rotate-on-open-link -> rebind -> isPeerConnected(new) == true. - P2: BLEService.canDeliverSecurely probed the Noise session with the peer ID as given, but sessions are keyed by the short wire ID — a send keyed by the full 64-hex Noise key (favorites resolution) misread an established session as insecure and needlessly retained + couriered every DM until ack. Normalize with toShort() like isPeerConnected. Test drives a real XX handshake and asserts both ID forms pass. - Periphery: the PrekeyBundleStore.StoredBundle.noiseKey "assign-only" flake fired again and slipped past its baselined USR (read exists in loadFromDisk; the indexer intermittently misses it). Replace the baseline entry with retain_codable_properties: true — deterministic, and a truly-dead Codable field is a persisted-format change anyway. Local periphery scan --strict: no unused code detected. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: jack <jackjackbits@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
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.
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 persistent identifiers
- Private Message End-to-End Encryption: Noise Protocol for mesh, NIP-17 for Nostr
- 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
- 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
- 290+ Relay Network: Distributed across the globe for reliability
- NIP-17 Encryption: Gift-wrapped private messages for internet privacy
- Ephemeral Keys: Fresh cryptographic identity per geohash area
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
- NIP-17 gift-wrapping for privacy
- 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
cd bitchat
open bitchat.xcodeproj
To run on a device there're a few steps to prepare the code:
- Clone the local configs:
cp Configs/Local.xcconfig.example Configs/Local.xcconfig - Add your Developer Team ID into the newly created
Configs/Local.xcconfig- Bundle ID would be set to
chat.bitchat.<team_id>(unless you set to something else)
- Bundle ID would be set to
- Entitlements need to be updated manually (TODO: Automate):
- Search and replace
group.chat.bitchatwithgroup.<your_bundle_id>(e.g.group.chat.bitchat.ABC123)
- Search and replace
Option 2: Using just
brew install just
Want to try this on macos: just run will set it up and run from source.
Run just clean afterwards to restore things to original state for mobile app building and development.
Localization
- Base app resources live under
bitchat/Localization/Base.lproj/. Add new copy toLocalizable.stringsand plural rules toLocalizable.stringsdict. - Share extension strings are separate in
bitchatShareExtension/Localization/Base.lproj/Localizable.strings. - 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.