37e02c1851
A vouched or verified key can rename itself onto a nickname the user trusts and keep rendering the seal beside the new name. `VouchAttestation.signableBytes` covers `voucheeFingerprint | voucheeSigningKey | timestampMs` and says nothing about a name — which is right; the attestation should stay name-free. But the seal is *rendered* beside a self-claimed nickname: `PeerListModel` derives `verifiedBadge`/`vouchedBadge` from the fingerprint and then shows `peer.displayName`, which falls back to the peer-claimed `nickname` whenever `localPetname` is unset. So the seal is read next to a name that nothing binds it to. Earn one genuine vouch as "ravi", announce "medic", and every device that trusts the real medic now shows a second trusted-looking medic. This is the mirror of #1661's case. That one is same nickname, new key; this is same key, new nickname. The binding has to live on the receiver, because the receiver is the only party that knows which name the key was presenting when it decided to trust it. So `IdentityCache` gains `trustedNicknames`, pinned when trust is established, and all three places that render a seal — the peer list, the public-timeline seal and the DM seal — suppress it while the peer presents a different name. Where it is pinned, and why: - On the FIRST vouch only, never moved by a later one. Otherwise an attacker renames and the next voucher silently re-anchors the seal to the new name. - Re-verifying DOES move it: the user just checked this key in person, under whatever name it shows now. - On the first announce seen while trust already stands. A vouch normally arrives for a peer we have not seen announce — it comes over Noise from someone else, and the vouchee may be hops away — so there is no name to bind to at record time. The announce path deliberately does NOT pin before trust exists: binding to whatever name we happened to see first would suppress the seal of a peer who renamed *before* being vouched. - Never on an empty nickname, and a missing baseline never suppresses. Peers trusted by earlier builds have none, and dropping their seals on upgrade would teach users to ignore the signal. Each seal site compares against the name it actually renders, not against the stored `claimedNickname`. That matters: offline favourite rows take their name from the persisted favourite relationship, which can lag the last announce, and a message row shows the sender as of that message. Comparing the rendered string keeps the seal truthful about the name the user is looking at. Message senders can carry a `#abcd` disambiguation suffix that an announced nickname never has, so a `displayedSender` overload strips it with the existing `splitSuffix()`. That overload is a protocol extension rather than a new requirement, so it needs no mock changes and its logic sits in a layer the tests can reach. A local petname already outranks the claimed nickname for display, so there is nothing to spoof there and the seal stands. The known limit, pinned by a test so it is explicit: if we never saw the key under its real name, its first announce IS the baseline, so an impersonating first announce is not caught. Closing that needs the nickname signed into the attestation, which is a wire change and deliberately not attempted here. `FingerprintView`'s vouched panel is left alone: that sheet is an explicit inspection surface keyed by fingerprint, where showing the trust state is the point. No wire or protocol change, and no new user-facing strings. Suppressing the seal is the security fix; explaining it in the UI wants the notice plumbing #1661 is adding, so it is left for a follow-up. `trustedNicknames` decodes with `decodeIfPresent` like the other post-v1 fields, so caches written by older builds still load. Tests: SecureIdentityStateManagerNicknameBindingTests (15) covers the rename attack, the second-voucher laundering attempt, the vouch-before-first-announce path and its residual gap, the no-pin-before-trust rule, suffix handling in both directions, rebinding on re-verification, clearing on unverify only when no vouch remains, both fail-open cases, and persistence compatibility each way. `TestIdentityManager` in UnifiedPeerServiceTests also conforms to the protocol and is updated.
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.