a008850c9e
Four things from review. Two were bugs, one was a miss, one was an overstated
claim of mine.
**A row could get its seal back by renaming away and back.** Moving off the
rendered name fixed three false positives and introduced this: a message row
renders `message.sender`, frozen at receipt, while the gate asked about the
peer's CURRENT name. So verify as "ravi", announce "medic", post to the public
timeline, announce "ravi" again — the live name is bound once more and the
archived row renders `<@medic ✓>`, a seal beside a name the key was never
trusted under. Exactly what this PR exists to stop.
The fix is not to check both names but to notice that a live row and a
historical row ask different questions:
live row (peer list, DM header, encryption status)
is the name this peer is announcing NOW the one it was verified under?
message row (public timeline, DM rows)
is the name ON THIS ROW the one it was verified under?
So `sealAppliesToRow(fingerprint:renderedSender:)` compares the row's own
sender against the pinned baseline and never consults the live name. That
kills the rename-back, and it also makes each row self-consistent in the other
direction: a historical "ravi ✓" stays sealed while that key is currently
renamed, because that row really was ravi. Requiring both names to match would
have retroactively unsealed accurate history on every ordinary rename.
Comparing a rendered name again needs the `#abcd` collision suffix stripped,
which is what pushed me off it before — `splitSuffix()` also removes every
"@", and nothing in `validateNickname` forbids one, so "ravi@hq" compared
unequal to itself. Hence `withoutCollisionSuffix`, which strips only a trailing
"#" plus four hex digits and touches nothing else.
**The vouched panel in the fingerprint sheet was ungated** —
`FingerprintView.swift:192`, the teal hollow seal with "vouched by N" and the
voucher names, read `voucherCount` and never consulted the binding. That is
the seal this PR is named for, in the sheet I had singled out as the place the
distinction should be explained. `voucherCount` and `voucherNames` are now
suppressed together: a voucher list beside a name nobody vouched for is the
same claim as the seal.
**Correcting my own claim.** I wrote that nothing branches on `.noiseVerified`
beyond the glyph and that every behavioural site treats it and `.noiseSecured`
alike. That was 3-for-4. `FingerprintView.swift:87` tints the status icon
`== .noiseVerified ? .green : textColor`, and `accessibilityDescription`
differs per case, so VoiceOver stops saying "verified" on a demoted DM header.
Both are the right outcome, but "nothing moves" was wrong and the sheet now
shows a plain lock above a bold green "verified" until the copy lands.
**Collision counting now folds.** `PeerDisplayNameResolver` counted collisions
on the displayed name, so the suffix that exists to make namesakes
distinguishable stayed silent for a case variant or a fullwidth Ｍ. The count
key is now `precomposedStringWithCompatibilityMapping.lowercased()` — one line,
no new data — which closes case, fullwidth, mathematical, script and roman
numeral forms, and subsumes the canonical folding Swift's String keys were
giving for free. Cross-script homoglyphs still need a real table and are
pinned as a known gap with a test to flip. The displayed name is never folded.
Also: both seal sites took a `queue.sync` via `isVerified` and then a second
for the binding, and in the formatter the check feeds the format cache key so
the cache does not shield it. Both are one call now. The two derived queries
are protocol requirements with default implementations, so the concrete manager
answers in a single lock while conformances only supply the primitives.
Tests: 6 new for `PeerDisplayNameResolver`, which had none, including the
known-gap rows; 5 more in the binding suite for the per-row rule — the
rename-back, a historical row keeping its seal, suffix and "@" handling, and
the fail-open cases. With the row check reverted to the live name, 3 of them
fail.
Suites here: 187 pass / 1908 tests, no result differing from main; 34 still
need an app bundle this machine cannot provide.
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.