BLE stays the control plane: a sender with a queued file > 64 KiB to a
directly connected peer advertising the wifiBulk capability sends a
bulkTransferOffer (0x04) inside the established Noise session — transferID,
file size, payload SHA-256, a fresh 32-byte token, and a random per-transfer
Bonjour instance name. The receiver answers bulkTransferResponse (0x05) with
its own token half, then both sides meet on a per-transfer
_bitchat-bulk._tcp channel over peer-to-peer Wi-Fi (AWDL).
The TCP stream is secured independently of TLS: both tokens traveled inside
Noise, so only the two peers can derive the ChaChaPoly channel key
(HKDF-SHA256, domain "bitchat-bulk-v1", transferID as salt). Frames are
length-prefixed sealed boxes with structured direction+counter nonces; the
first frame must prove knowledge of the key or the client is disconnected,
and the final hash is verified against the offer before delivery.
Decline, timeout, or any mid-transfer error falls back to BLE fragmentation
exactly once, driving the same TransferProgressManager stream so the UI is
unchanged. Wi-Fi-negotiated transfers may carry up to 8 MiB (new
FileTransferLimits.maxWifiBulkPayloadBytes, enforced by the receiver from
the accepted offer); the BLE path keeps its existing caps.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
An opt-in "internet gateway" toggle lets one connected phone bridge the
local geohash channel for mesh-only peers: signed kind-20000 events ride
a new nostrCarrier (0x28) packet — directed to the gateway for uplink,
broadcast with TTL for downlink — with Schnorr verification at every
hop, CourierStore-style quotas, and explicit loop-prevention rules.
- BitFoundation: MessageType.nostrCarrier = 0x28
- NostrCarrierPacket: 2-byte-length TLV codec (direction, geohash,
signed event JSON), 16 KiB cap, tolerant decoder
- GatewayService: closure-injected policy layer — verify gates (sig,
kind, #g tag, age, size), uplink quotas (10/min/depositor rate limit,
offline queue of 20 total / 5 per depositor, drop-oldest, flush on
reconnect), downlink budget (30/min, bounded drop-oldest backlog),
bounded loop-prevention ID sets
- BLEService: runtime capability bits (advertise .gateway only while
the toggle is on, re-announce on change), signed directed uplink
sends, carrier ingress with depositor signature verification
- Mesh-only senders uplink automatically from sendGeohash when no relay
is connected and a reachable peer advertises .gateway; once-per-
channel "sent via mesh gateway" notice
- UI: gateway toggle beside the Tor toggle, globe header indicator,
VoiceOver labels, xcstrings entries
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Small encrypted crews (hard cap 16) between public broadcast and 1:1 DMs:
Protocol
- MessageType.groupMessage = 0x25: broadcast packets with a cleartext
16-byte group ID + epoch, ChaCha20-Poly1305 ciphertext (epoch bound as
AEAD AAD), inner Ed25519 sender signature over
"bitchat-group-msg-v1"|groupID|messageID|timestamp|content
- NoisePayloadType.groupInvite = 0x06 / .groupKeyUpdate = 0x07:
creator-signed group state (key, epoch, roster) 1:1 over Noise; signature
over "bitchat-group-v1"|groupID|epoch|key-hash|roster-hash and the Noise
session peer must BE the creator
- SyncTypeFlags bit 10 (groupMessage): variable-length LE bitfield widens
1 -> 2 bytes inside the length-prefixed REQUEST_SYNC TLV; old clients
ignore unknown bits and answer with types they know
- PeerCapabilities.localSupported now advertises .groups
Storage
- GroupStore: symmetric keys in the keychain, roster/name/epoch as
protected JSON in Application Support; wiped in panicClearAllData()
Behavior
- Non-members relay 0x25 like any broadcast but cannot read it; group
messages join gossip-sync backfill with the public-message window
- Receivers drop wrong-epoch envelopes, bad sender signatures, and
senders missing from the creator-signed roster
- Fire-and-flood delivery (no per-member acks in v1)
UI
- Groups open as chat windows through the private-chat sheet (virtual
"group_" peer IDs); groups section in the people sheet; /group
create/invite/remove/leave/list commands; invitees get a system message
+ notification and the group appears in their people sheet
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Courier envelopes were sealed with one-way Noise X to the recipient's
long-lived static key, so a later compromise of that key exposed every
envelope captured in transit. This adds one-time prekey bundles:
- PrekeyBundle (MessageType 0x24): 8 one-time Curve25519 public prekeys
bound to the owner's Noise static key by an Ed25519 signature over
"bitchat-prekey-bundle-v1" canonical bytes; gossiped mesh-wide on its
own 60s sync round (SyncTypeFlags bit 9, 200-peer cap, 24h freshness)
and verified against the announce-bound signing key before caching.
- Sealed envelope v2: Noise X where the responder static is the one-time
prekey, prologue "bitchat-prekey-v1" || prekeyID. Sender identity rides
encrypted inside and is authenticated exactly like v1 (blocked-sender
check included). CourierEnvelope gains an optional prekeyID TLV that
v1 decoders skip as unknown.
- Local prekeys live in the Keychain; consumed privates survive a 48h
grace window for spray-and-wait redeliveries, then are deleted (the
forward-secrecy clock starts at deletion). The batch tops back up and
re-gossips when unconsumed count drops below 3, and everything is
wiped in panic mode.
- Routing: courier sealing picks a cached verified bundle when one
exists (one prekey per message, reused across deposit retries), with
the advertised .prekeys capability as a veto for on-mesh peers, and
falls back to static sealing otherwise.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
New MessageType 0x23 carries TLV-encoded board posts and tombstones,
self-signed with the author's Ed25519 key ("bitchat-board-v1" /
"bitchat-board-del-v1" domains) so notices verify without the author
present. BoardStore persists raw signed packets under Application
Support/board/ (200 posts, 5 per author, oldest evicted; expiry sweep;
tombstones retained until the deleted post's original expiry) and is
wiped on panic.
Board packets join gossip sync as bit 8 of the existing variable-length
types bitfield (a second byte old decoders already accept and ignore),
with a 60s round and its own capacity, served straight from the board
store so retention has one owner. Posts relay like broadcasts; urgent
posts get the announce-class TTL cap.
UI: a pin button in the header opens the board for the current channel
(geohash board, or mesh-local board), with urgent-pinned newest-first
listing, compose with urgent toggle and 1/3/7-day expiry, and
swipe-delete on own posts. Geohash posts also publish one-way as
Nostr kind-1 location notes when relays are reachable.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Part A — source-route origination policy:
- Gate route application (BLESourceRouteOriginationPolicy): only packets we
author, directed at a single peer, with TTL headroom, whose recipient is
not directly connected. Relays no longer attach routes to (and re-sign)
packets they merely forward.
- Version-gate paths: MeshTopologyTracker records the highest protocol
version observed per peer; BFS routes require every intermediate hop and
the recipient to be v2-observed, capped at 4 intermediate hops.
- Degrade on failure: BLESourceRouteFailureCache marks a routed send that
sees no inbound traffic from the recipient within 10s as failed and floods
for 60s before retrying routes.
Part B — REQUEST_SYNC fragmentIdFilter (TLV 0x06):
- Requester: BLEFragmentAssemblyBuffer reports stalled broadcast
reassemblies (no new fragment for 5s, retried at most every 10s); the
maintenance pass sends a types=fragment REQUEST_SYNC naming the stalled
8-byte fragment stream IDs to each connected peer.
- Responder: GossipSyncManager restricts the fragment diff to exactly the
named streams, bypassing the since-cursor while the GCS filter still
excludes pieces the requester holds; RSR/TTL-0/rate-limit semantics
unchanged and REQUEST_SYNC stays link-local.
- Bounds: at most 60 IDs per request (60*17-1 = 1019 bytes <= the 1024-byte
decoder cap); oversized 0x06 values are ignored, not fatal.
Docs: SOURCE_ROUTING.md gains the iOS origination policy (§8);
REQUEST_SYNC_MANAGER.md documents 0x05/0x06 as implemented.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Announces now carry an optional capabilities TLV (0x05): a little-endian
bitfield with named bits for upcoming features (prekeys, wifiBulk,
gateway, groups, board, vouch, meshDiagnostics). Old clients skip the
unknown TLV; peers without it decode as nil so features can distinguish
"legacy peer" from "advertises nothing".
PeerCapabilities lives in BitFoundation with a minimal-length encoding
that preserves unknown bits for forward compatibility. Peer capabilities
are stored in the BLE peer registry on verified announce and exposed via
BLEService.peerCapabilities(_:). The local advertisement set is empty
until each feature ships its bit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- BitchatProtocol.swift: stop advertising "timing obfuscation prevents
traffic analysis" — what exists is randomized relay jitter
(RelayController, 10-220 ms) and PKCS#7-style padding to
256/512/1024/2048-byte blocks (MessagePadding); there is no cover
traffic or per-message timing obfuscation. Also update the stale
Message Types list (Delivery/Read are Noise payloads, no Version
negotiation type; add CourierEnvelope/RequestSync/FileTransfer).
- MessageType.swift: header said "6 essential" types; the enum has 9
cases.
WHITEPAPER.md needed no changes: the #1372 rewrite already replaced the
old Bloom-filter and MessageRetryService claims, and its numbers
(dedup 1000/5min, jitter, outbox 100/peer 24h 8 attempts, courier
16 KiB/24h/40-20-5-2 quotas, spray 4/8, gossip 1000/15s/6h) all match
the code.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Store-and-forward previously delivered to an out-of-range peer only if a
mutual favorite happened to be connected at send time and later met the
recipient directly, and everything except courier envelopes died with the
app process. This closes those gaps end to end:
- Persist the MessageRouter outbox to disk, sealed with a ChaChaPoly key
held only in the Keychain (no plaintext at rest); queued private
messages now survive an app kill and flush on next launch.
- Deposit retry: queued messages are re-deposited whenever a new eligible
courier connects, tracked per message so the same courier is never
double-burned, until 3 distinct couriers carry it or it expires.
- Tiered open couriering: signature-verified strangers can now carry mail
(2 envelopes/depositor into a 20-slot pool) alongside mutual favorites
(5 each); overflow evicts verified-tier mail before favorites'.
- Spray-and-wait: envelopes carry a copy budget (4, capped 8, new TLV,
wire-compatible with old clients); couriers split half their remaining
budget with each newly encountered courier so mail diffuses through a
moving crowd.
- Remote handover: a verified relayed announce now floods a copy toward
the multi-hop recipient (directed-relay treatment, 10-min per-envelope
cooldown) while the carried original stays put for a direct encounter.
- Public history: gossip-sync window for whole public messages widened
from 15 min to 6 h, matched on the receive-acceptance side, and the
message store persists to disk so devices bridge partitions and
restarts ("town crier").
- Privacy-safe local delivery counters (bare tallies, log-only) so the
store-and-forward stack is measurable on-device.
- Panic wipe now also clears the sealed outbox, gossip archive, and
counters.
- Rewrite WHITEPAPER.md to describe the app as implemented (Noise XX/X,
actual flood control, courier system, gossip sync, Nostr path); the old
document described a bloom filter, three fragment types, and a
MessageRetryService that don't exist.
1037 macOS tests pass (17 new); iOS builds.
Co-authored-by: jack <jackjackbits@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Friend-courier store-and-forward: mutual favorites carry sealed messages to offline peers
When a private message has no reachable transport, the router now seals it
to the recipient's Noise static key (new one-way Noise X pattern) and hands
the envelope to up to three connected mutual favorites. Couriers store the
opaque ciphertext under strict quotas (20 total, 5 per depositor, 16 KiB,
24 h) and hand it over when the recipient's announce matches a rotating
HMAC recipient tag; the recipient opens it and the message flows through
the normal private-message pipeline, so dedup and delivery acks just work.
- CourierEnvelope TLV + courierEnvelope (0x04) message type in BitFoundation
- Noise X one-way pattern reusing the existing handshake machinery,
domain-separated by a courier prologue; sender identity authenticated
via the ss DH (no forward secrecy - documented tradeoff)
- CourierStore with eviction, file persistence, and panic-wipe integration
- Rotating recipient tags (HMAC over epoch day) so carried envelopes don't
correlate for observers who don't already know the recipient's key
- New "carried" delivery status with figure.walk glyph; header indicator
while carrying mail for others
- Three-node end-to-end test ferrying packets through real BLEService
instances, plus codec/crypto/store/router suites (986 tests green)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Fix courier handoff verification and directed sends
* Authenticate courier deposits by ingress peer
* Gate courier handover on direct announces and isolate store test
Envelopes are removed from the courier store optimistically, so releasing
them on a relayed (multi-hop) announce risks losing carried mail to a
speculative flood that never reaches the recipient. Handover now also
requires the announce to have arrived directly (full TTL), i.e. an actual
encounter with a live link; regression test builds a relayed copy of a
genuinely signed announce (TTL is excluded from announce signatures).
Also make CourierStore's on-disk location injectable so the persistence
test round-trips through a temp directory instead of wiping the real
Application Support store, and reattach BLEAnnounceHandler's doc comment
to the class it describes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Use Xcode-bundled Swift in CI instead of a standalone toolchain
The unpinned setup-swift action installs Swift 6.1, which refuses the
SDK on runner images that have rolled to Xcode 26.5 ("this SDK is not
supported by the compiler"). Jobs passed or failed depending on which
image they landed on. The Xcode-bundled toolchain always matches the
image's SDK, and matches local development. Cache keys now include the
toolchain version so artifacts from one compiler are never restored
into builds with another.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Drop couriered mail from blocked senders at envelope open
The UI-layer block check (isPeerBlocked in the transport event
coordinator) resolves a fingerprint from the live session or peer list,
but a couriered message arrives precisely when its sender is absent —
no session, no registry entry — so the check failed open and a blocked
identity's mail was delivered anyway. Gate in openCourierEnvelope,
where the sealed sender's full static key is in hand.
End-to-end test ferries a full deposit→carry→handover round and
verifies the envelope from a blocked sender never reaches the delegate
(confirmed failing without the gate).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Fix favorites end-to-end: peer-list dedup, Nostr sync, /fav key corruption
- UnifiedPeerService: dedup offline favorites against mesh peers by noise
key. Phase 2 compared a 64-hex noise-key PeerID against 16-hex mesh IDs
(never equal), leaving only a nickname+isConnected heuristic — a mutual
favorite that was reachable-but-not-connected or renamed rendered twice,
and a same-nick stranger could suppress a favorite entirely.
- Nostr inbound: intercept [FAVORITED]/[UNFAVORITED] markers in the live
PM handler so they update theyFavoritedUs instead of rendering as chat
text; mutual favorites can now form over Nostr. Delete the dead
favorite-aware PM variant and ChatNostrCoordinator.handleFavoriteNotification
(unwired, parsed a stale FAVORITE:TRUE|… format no sender emits).
- NostrTransport.isPeerReachable: match short form regardless of incoming
ID width — toggling an offline favorite (addressed by 64-hex noise key)
was silently dropped with no reachable transport.
- BLEService.sendPrivateMessage: normalize recipient to the short ID like
sendFilePrivate, so a 64-hex target hits the existing Noise session
instead of initiating a handshake with a 32-byte wire recipient ID.
- /fav, /unfav: stop writing Data(hexString: peerID.id) — the 8-byte
routing ID for mesh peers — into the favorites store as a "noise key",
and stop double-sending the favorite notification; delegate to
toggleFavorite with a proper state check.
- FavoritesPersistenceService.updatePeerFavoritedUs: keep the stored
nickname when the caller passes the "Unknown" placeholder.
- Bump marketing version to 1.5.4.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Route DMs to mutual favorites via Nostr when a mesh-keyed peer goes offline
Field-tested on device: with a DM window opened while the peer was on
mesh (conversation keyed by the short 16-hex ID), walking out of range
and sending failed instantly with "peer not reachable" even though the
header showed the peer as Nostr-reachable (mutual favorite, npub known).
sendPrivateMessage derived the favorites key as Data(hexString:
peerID.id) — for a short mesh ID that is the 8-byte routing ID, never
the noise key — so the mutual-favorite/Nostr-key checks always came up
empty and the send failed before reaching MessageRouter. Conversations
keyed by the full 64-hex noise-key ID (opened from the offline favorite
row) were unaffected, which is why later tests appeared to work.
Resolve the noise key properly (peerID.noiseKey, then the unified peer
row, then the favorites store by derived short ID) and add a regression
test for the mesh-keyed-peer-goes-offline case.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Label Nostr DMs from favorites with their stored nickname
Field-tested: a DM delivered over the Nostr fallback rendered as
"anon#678e" instead of the sender's name. The inbound handler named the
sender via displayNameForNostrPubkey, which only knows geohash-scoped
names — even though the pipeline had already resolved the sender's
noise key (the conversation is keyed by it).
When the conversation key carries a noise key, prefer the favorite's
stored nickname; geohash DMs (nostr_ keys) keep the anon geo name. This
also stops an inbound Nostr [FAVORITED] from overwriting the stored
nickname with the anon fallback, since the same name feeds
updatePeerFavoritedUs.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Fix courier path for offline favorites addressed by noise-key IDs
Two Codex review findings, both the same ID-width confusion this PR
targets, in the courier flow:
- CourierDirectory.favoritesBacked resolved recipients only via
getFavoriteStatus(forPeerID:), which requires a short 16-hex ID —
offline favorites are addressed by the full 64-hex noise-key ID, so
attemptCourierDeposit silently bailed for exactly the peers couriers
exist to serve. The 64-hex ID now yields its own key directly.
- openCourierEnvelope emitted the derived short mesh ID even when the
sender has no live mesh identity, landing couriered mail in an
unresolvable short-ID thread labeled "Unknown". Absent senders now
emit the full noise-key ID so the message joins the stable favorite
conversation; present senders keep the live short-ID thread.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: jack <jackjackbits@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Mechanical style fixes across the enabled rule set, mostly via
swiftlint --fix (trailing_comma, comma, colon, trailing_newline,
comment_spacing, unused_closure_parameter, unneeded_break_in_switch,
opening_brace) plus hand fixes:
- non_optional_string_data_conversion (45): .data(using: .utf8)! and
?? Data() fallbacks replaced with the non-optional Data(_.utf8),
including two production sites (NIP-44 HKDF info constant and the
announce canonicalization context/nickname bytes — byte-identical
output, only the impossible-nil handling is gone).
- switch_case_alignment: LocationChannel had a misindented closing
brace; also repaired an --fix artifact in BLEService's .none case.
- redundant_string_enum_value: TrustLevel raw values equal to the case
names (encoded form unchanged).
- unused_optional_binding: let _ = binds replaced with != nil / is Bool.
- static_over_final_class: PreviewView.layerClass.
- Resolved the BinaryProtocolTests TODO by documenting that 8-byte
recipient ID truncation is the fixed wire-field size, not a bug.
The 4 remaining violations are all todo markers for a shared
test-helpers module (tracked in #1088) and one Reuse note.
Co-authored-by: jack <jackjackbits@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Centralize UI theme colors into semantic ThemePalette tokens
Introduce AppTheme/ThemePalette (Utils/Theme.swift) with an environment
key and @ThemedPalette property wrapper, persisted via @AppStorage.
Views now resolve background/primary/secondary/accentBlue/alertRed/
divider tokens from the environment instead of computing colors inline,
removing the backgroundColor/textColor/secondaryTextColor prop-drilling
through the header, composer, and people-sheet hierarchy.
Matrix theme output is pixel-identical; this is groundwork for a
user-selectable theme switcher.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Add liquid glass theme with in-app appearance switcher
Add a .liquidGlass AppTheme alongside the matrix terminal theme,
selectable from a one-line APPEARANCE row in the app info sheet
(persisted via @AppStorage, applies live).
Liquid glass renders system fonts and colors over a subtle gradient
backdrop, with the header and composer floating as Liquid Glass panels
(real .glassEffect() on iOS/macOS 26, compiler-gated with an
ultraThinMaterial fallback for older SDKs). The message list scrolls
underneath the chrome via safe-area insets, and all sheets share the
same backdrop and surface language. The matrix theme is unchanged.
Details:
- Theme is threaded through ChatMessageFormatter so message
AttributedStrings switch font design per theme; the per-message
format cache gains a variant key so themes never serve each other's
cached strings
- New palette tokens: accent (interactive tint) and locationAccent
(geohash green), replacing scattered hardcoded greens/blues in the
voice note, waveform, verification, and people-sheet views
- Header controls get full-height tap targets and the people count
becomes a real Button (previously a tap gesture on the cluster)
- CommandSuggestionsView renders nothing when empty instead of a
zero-height view that pushed the composer input off-center
- New appearance strings localized for all 29 catalog languages
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: jack <jackjackbits@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
jack