mirror of
https://github.com/permissionlesstech/bitchat.git
synced 2026-07-26 19:45:20 +00:00
jackandClaude Opus 5
19a56780d0
Draft protocol spec for review by both iOS and Android before any implementation. Nothing here is implemented; this is the artifact to agree on, since the change is a wire revision neither platform can ship alone. The headline correction, because it is easy to get wrong: rotating the peer ID alone accomplishes nothing. The announce carries the Noise static key, the Ed25519 signing key and the nickname in cleartext, so a rotated ID is re-linked to the same device on its first announce. Rotation and announce confidentiality have to land together. The second thing an implementer needs to know up front is that peerID == SHA-256(noiseStaticKey)[0..8] is not a convention, it is the mechanism that makes peer IDs unforgeable, enforced in the announce preflight and again at handshake completion. Making IDs independent of the key fails both checks for every peer, so a replacement binding has to ship in the same change. The spec proposes one: an Ed25519 proof over (context, epoch, rotating ID, static key) carried inside the completed Noise session via the existing AuthenticatedPeerStatePacket, checked against a pinned signing key — strictly stronger than today's self-signed announce. Design summary: hour-epoch IDs derived from private key material via HKDF+HMAC so no observer can predict or link them; pairwise recognition tags from the X25519 shared secret so mutual favourites still recognise each other with no handshake, padded to fixed slots so the tag count does not leak how many favourites someone has; strangers discovered by handshake-first-identify-second over Noise XX, whose static keys are already encrypted on the wire. Nickname moves inside the session and the neighbour list is dropped rather than rotated. Includes a verified impact inventory separating what breaks hard (the handshake check, the announce preflight, the disk outbox keyed by peer ID, private-media stable IDs and their deletion tombstones, the initiator tie-break, fingerprint-prefix lookups) from what degrades gracefully and what is already safe because it keys on fingerprints or Noise keys. Rollout uses the two mechanisms already proven in this repo: a PeerCapabilities bit (11 is next; 10 is burned) with capabilitiesWereExplicitlyAdvertised to tell an old client from a new one with the bit off, and observed-version gating as used for source routing. Two findings surfaced while writing this and are recorded in the spec. CourierEnvelope.recipientTag is HMAC keyed on the recipient's *public* static key, and since that key is broadcast in cleartext today, any observer in radio range can compute a peer's courier tags for any day — so the whitepaper's "cannot link it across days" does not currently hold, and the pattern must not be copied. And NoiseEncryptionService's buildAnnounceSignature/verifyAnnounceSignature/canonicalAnnounceBytes are present but production-dead, called only from tests; the binding above deliberately uses a different context string so the two can never be confused. Eight open questions are left explicitly unresolved, including the rotation period, whether unsigned v2 announces are an acceptable posture, and whether Android's decoder tolerates trailing bytes the way iOS's does (which decides whether padding coverage can ship ungated). Co-Authored-By: Claude Opus 5 <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 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
- 290+ 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.