From 201dbac49a1bdce81594165212f42c80a1d37dbb Mon Sep 17 00:00:00 2001 From: jack <212554440+jackjackbits@users.noreply.github.com> Date: Tue, 7 Jul 2026 14:10:58 +0200 Subject: [PATCH] docs: reconcile protocol docstrings with implementation (#1374) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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: jack Co-authored-by: Claude Fable 5 --- bitchat/Protocols/BitchatProtocol.swift | 16 +++++++++------- .../Sources/BitFoundation/MessageType.swift | 2 +- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/bitchat/Protocols/BitchatProtocol.swift b/bitchat/Protocols/BitchatProtocol.swift index 4ebe6509..267d8cc5 100644 --- a/bitchat/Protocols/BitchatProtocol.swift +++ b/bitchat/Protocols/BitchatProtocol.swift @@ -18,7 +18,7 @@ /// - Efficient binary message encoding /// - Message fragmentation for large payloads /// - TTL-based routing for mesh networks -/// - Privacy features like padding and timing obfuscation +/// - Privacy features: message padding and randomized relay jitter /// - Integration points for end-to-end encryption /// /// ## Protocol Design @@ -38,18 +38,20 @@ /// 7. **Decoding**: Binary data parsed back to message objects /// /// ## Security Considerations -/// - Message padding obscures actual content length -/// - Timing obfuscation prevents traffic analysis +/// - Message padding (to 256/512/1024/2048-byte blocks) obscures actual content length +/// - Randomized relay jitter reduces the traffic-analysis signal; there is no +/// cover traffic or per-message timing obfuscation /// - Integration with Noise Protocol for E2E encryption /// - No persistent identifiers in protocol headers /// /// ## Message Types /// - **Announce/Leave**: Peer presence notifications -/// - **Message**: User chat messages (broadcast or directed) +/// - **Message**: Public chat messages /// - **Fragment**: Multi-part message handling -/// - **Delivery/Read**: Message acknowledgments -/// - **Noise**: Encrypted channel establishment -/// - **Version**: Protocol version negotiation +/// - **NoiseHandshake/NoiseEncrypted**: Encrypted channel establishment and +/// all private payloads (messages, delivery acks, read receipts) +/// - **CourierEnvelope**: Sealed store-and-forward mail +/// - **RequestSync/FileTransfer**: Gossip history sync and media transfer /// /// ## Future Extensions /// The protocol is designed to be extensible: diff --git a/localPackages/BitFoundation/Sources/BitFoundation/MessageType.swift b/localPackages/BitFoundation/Sources/BitFoundation/MessageType.swift index ceac0cd0..23f391b9 100644 --- a/localPackages/BitFoundation/Sources/BitFoundation/MessageType.swift +++ b/localPackages/BitFoundation/Sources/BitFoundation/MessageType.swift @@ -7,7 +7,7 @@ // /// Simplified BitChat protocol message types. -/// Reduced from 24 types to just 6 essential ones. +/// Consolidated from the original 24 wire types down to the 9 cases below. /// All private communication metadata (receipts, status) is embedded in noiseEncrypted payloads. public enum MessageType: UInt8 { // Public messages (unencrypted)