mirror of
https://github.com/permissionlesstech/bitchat.git
synced 2026-10-18 07:33:46 +00:00
fabb7b7995
* Constrain the action actor slot, not just the target
The target slot was tightened to a single name token after review found a
preamble could be smuggled through it. The actor slot kept no such
constraint, and it is reachable the same way.
Anchoring the actor to the wire sender stops a peer acting as someone
else, but the sender is a self-chosen nickname, and
InputValidator.validateUserString accepts any non-control characters up
to 50 — spaces included. So the rejected preamble just moves into the
name. A peer nicknamed
SECURITY: session expired, re-verify at evil
sending
* SECURITY: session expired, re-verify at evil took a screenshot *
is speaking as itself, matches `inner == "\(senderBase) took a
screenshot"`, and is handed to the formatter as sender "system" — 44
attacker-chosen characters in the styling that means "this came from the
app, not a person". The hug and slap templates carry it too.
The actor now has to be a name token as well, at the nickname length
bound rather than the target slot's 32 so a legitimate long name does not
silently stop rendering. A space-containing nickname degrades to a plain
message under its own name, which is the same trade already accepted for
the target slot.
Test added first against the unfixed parser: all three templates rendered
as "system", and the existing cases stayed green, so this was a gap in the
fix rather than a regression in it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Pin the actor bound with a legit long-nickname test
The actor uses the nickname length limit (50), not the target slot's 32,
so that a legitimate space-free nickname longer than 32 still renders its
actions as system messages. Nothing asserted that, so the choice read as
arbitrary and a later "simplify to 32" would have silently regressed every
33–50-char nickname's hugs/slaps/screenshots to plain text under their own
name. A 40-char no-space nickname now pins all three templates to system.
Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
* Restrict the action name token to what the formatter won't linkify
Constraining the two slots to "no Swift whitespace" still let a slot carry
a payload that renders dangerously inside the trusted system line
(@Chessing234 on #1662/#1699):
- `* 🫂 bob hugs https://evil.tld *` — the target is whitespace-free and
short, so it matched, rendered as system, and the formatter linkified it:
a tappable attacker-chosen link under trusted styling, one packet, no
preamble. `www.evil.tld` did the same via the "www." hint, with no ":"
or "/" for a naive charset check to catch.
- A unicode separator or bidi mark (U+202E) in a slot passed the
isWhitespace check and reordered the visible text of the system line.
isNameToken now rejects both classes: unicode whitespace/separators and
control/format characters (bidi marks, zero-width joiners), and anything
matching the formatter's exact URL gate — contains("://") || contains
("www.") || contains("http"). A real action still renders: handleEmote
only emits a resolved nickname (optionally `#abcd`-suffixed, left intact)
or "you". An attacker's URL/bidi payload degrades to a plain message under
the sender's own name.
Test asserts the URL (both schemes and the www. variant, in target and
actor slots) and bidi/nbsp cases degrade to plain while the legit shapes
stay system; verified it fails on the pre-fix token. Full suite green.
Co-Authored-By: Claude Fable 5 (1M context) <noreply@anthropic.com>
* Reject blank-rendering scalars in action name tokens
The set-membership test only ever covered separators and control/format
characters, so scalars that render as nothing but fall outside those
categories still smuggled readable free text into a line drawn with
trusted system styling. U+2800 braille pattern blank passed on both the
50-char actor slot and the 32-char target slot, so a hostile nickname
was not even required.
isNameToken now walks the token per scalar and rejects on general
category (space/line/paragraph separator, control, format, surrogate,
private use, unassigned), on isDefaultIgnorableCodePoint — which catches
the hangul fillers, category Lo and otherwise invisible to a category
rule — and on a four-entry denylist of blank-rendering symbols that are
none of the above. Combining marks stay allowed so Persian and Arabic
names carrying harakat keep rendering as actions.
Also corrects two comments that asserted things that are not true:
InputValidator does not run on inbound nicknames (its only caller is
ReadReceipt decoding), and the formatter cannot linkify a system line
because its match loop sits inside the sender != "system" branch, which
makes the URL clause defense in depth rather than a live fix.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Let Persian names keep their half-space
11c503eb rejected every format character, U+200C included. That is
Persian's نیمفاصله: علیرضا, امیرحسین, میرود. Those names stopped
rendering as actions, a cost carried only by Persian and Arabic
speakers, and it bought less than it looked.
The joiner is not in the class that check exists to close. The scalars
it stops are invisible — they open a word gap a reader inspecting the
nickname cannot see. U+200C renders: a visible half-space in Arabic
script, and nothing at all in Latin, where it cannot fake a boundary at
all. As an attack tool it is therefore no stronger than the hyphen, dot
and colon this check has always allowed, and still does: a nickname
reading `SECURITY:session-expired-verify` passes today and always has.
So allow it where the orthography puts it — between two letters, at most
twice — and nowhere else. That admits the names while denying every
shape an attacker wants: a leading or trailing gap, a gap opened after
punctuation (`امنیت:جلسه…`), a gap beside a digit, and any run long
enough to stack a sentence into one token. Every other invisible scalar,
U+2800 and the fillers included, stays rejected.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <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.
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.