Skip to content

BitChat v0.3.3 — Phase 2.2 Production Release: Authoritative Rust Protocol Integration, Noise XX Interoperability & Stage 3 Mesh Engine

Choose a tag to compare

@github-actions github-actions released this 19 Nov 06:50
· 13 commits to main since this release

BitChat v0.3.3 — Phase 2.2 Production Release: Authoritative Rust Protocol Integration, Noise XX Interoperability & Stage 3 Mesh Engine

BitChat v0.3.3 completes Phase 2.2 and delivers the Stage 3 Mesh & Peer State Engine of the Python-to-Rust migration. While v0.3.2 introduced native Rust cryptographic and transport foundations in rust/bitchat-core, several runtime paths still executed in Python or duplicated work across both languages. In v0.3.3, Rust (bitchat._bitchat_core) becomes the single authoritative execution owner of BitChat's protocol-critical pipeline:

  • Authoritative Rust Noise XX sessions (NativeNoiseSession) with zero eager Python key copies, strict nonce-0 replay protection, and fail-closed u32::MAX nonce exhaustion guards.
  • Cohesive single-FFI protocol engine (NativeProtocolEngine) collapsing inbound decode → fragment reassembly → mesh routing/dedup/rate-limit → Noise XX dispatch → outbound encode from 4+ PyO3 crossings down to 1.
  • Native bounded peer & identity state engine (NativePeerStateEngine) with collision-safe peer_id <-> fingerprint bindings, anti-spoofing nickname validation, and bounded pending direct-message queues (32 per peer / 512 global).
  • Single-pass Rust mesh routing & store-and-forward removing duplicate Python+Rust execution in MeshRouter and StoreAndForwardQueue, plus native NativeAckTracker (0x0A DeliveryAck) and 0x13 NoiseIdentityAnnounce support.
  • Controlled bitchat-tui interoperability supporting legacy 4-byte zero-extended peer IDs (XXXXXXXX00000000) post-Noise-authentication with impostor collision rejection while keeping strict SHA-256 verification for modern peers.
  • Runtime LAN & BLE native integration wiring NativeIpRateLimiter into LAN discovery and controller-negotiated ATT MTU (client.mtu_size) into compute_ble_write_chunk_size.
  • Cross-platform v0.3.3 packages across Windows (x64 .exe + .whl + WinGet manifest), Linux (x86_64 .deb + .AppImage + .whl), macOS Apple Silicon (arm64 .whl), and universal source tarball (.tar.gz).

What's Changed in v0.3.3

Authoritative Rust Noise XX Integration (rust/bitchat-core/src/noise.rs, src/bitchat/crypto/sessions.py, noise.py)

  • NativeNoiseSession Runtime Ownership: NoiseSession now delegates handshake progression, transport AEAD encryption/decryption, replay protection, and state tracking directly to Rust NativeNoiseSession (embedding the 12-phase NativeHandshakeStateMachine).
  • Zero Duplicate Cipher State & Zero Eager Python Key Copies: Removed eager bytes key copying in NoiseCipherState; active symmetric transport keys remain inside zeroize::ZeroizeOnDrop-managed Rust structs. PyNoiseSession is retained strictly for differential equivalence testing and non-native fallback environments.
  • Fail-Closed Nonce Exhaustion & Replay Hardening: Enforced NOISE_MAX_TRANSPORT_NONCE = u32::MAX (with needs_rekey() warning at 1_000_000_000) so 4-byte wire nonces can never wrap around; enforced strict replay rejection including nonce 0; ensured failed AEAD decryptions never mutate the 1,024-entry replay window; and added clean reset_for_rehandshake() zeroization on peer reconnect.

Native Protocol Engine (rust/bitchat-core/src/engine.rs)

  • Implemented NativeProtocolEngine executing wire unpadding/decoding, sender-isolated fragment reassembly, single-pass mesh routing/deduplication/rate-limiting, protocol dispatch (0x01, 0x04, 0x0A, 0x10, 0x11, 0x12, 0x13, 0x25), Noise XX handshake/transport advancement, collision-safe identity binding, and outbound frame encoding in 1 PyO3 crossing.

Native Peer State Engine (rust/bitchat-core/src/engine.rs, src/bitchat/app/session_coordinator.py)

  • Implemented NativePeerStateEngine providing bounded peer registries, collision-safe peer_id <-> fingerprint mappings with reverse collision indices, anti-spoofing nickname protection, bounded pending DM queues (32 per peer / 512 total), and strictly separated observed → authenticated → verified trust levels.

Mesh Router & Store-and-Forward (rust/bitchat-core/src/mesh.rs, src/bitchat/mesh/router.py, store_forward.py)

  • Eliminated parallel Python+Rust execution when _bitchat_core is loaded. NativeMeshRouter (evaluate_incoming_raw), NativeStoreAndForwardQueue, and NativeAckTracker are now the sole authoritative runtime owners for TTL/hop validation, deduplication, rate limiting, store-and-forward queuing, and delivery acknowledgments.

Cross-Implementation Interoperability (bitchat-tui)

  • Added classify_peer_id_raw and normalize_peer_id_raw (rust/bitchat-core/src/protocol.rs) recognizing legacy 4-byte zero-extended bitchat-tui peer IDs (XXXXXXXX00000000) while preserving strict SHA-256(x25519_pub)[:8] validation for modern peers.
  • Legacy peer IDs are bound strictly after Noise XX static-key authentication with collision rejection against impostor keys.
  • Wired 0x13 NoiseIdentityAnnounce (native Ed25519-verified parsing) and 0x0A DeliveryAck (NativeAckTracker), backed by 10 automated interoperability tests in tests/interoperability/test_tui_interop.py.

LAN & BLE Integration (src/bitchat/network/discovery.py, src/bitchat/ble/, src/bitchat/app/session_coordinator.py)

  • Wired NativeIpRateLimiter into LANDiscovery (10 UDP discovery packets/sec per IP).
  • Wired negotiated controller ATT MTU (client.mtu_size) into NativeBleConnectionEngine and compute_ble_write_chunk_size, dynamically sizing BLE write fragments.
  • Replaced the asyncio.sleep(0.04) polling loop in SessionCoordinator with event-driven per-peer asyncio.Event signaling and unified stale handshake timers on time.monotonic().
  • (Architecture transparency: LAN async UDP/TCP socket loops and BLE WinRT/BlueZ OS drivers remain in Python until Stages 4–5 complete.)

Performance Impact (Measured Benchmarks)

Measured via scripts/benchmark_phase22.py on Windows 11 AMD64, Python 3.14.7, Rust stable, release-optimized _bitchat_core v0.3.3 running identical workloads against pure-Python reference implementations:

Operation Pure Python Native Rust (v0.3.3) Measured Speedup
Packet encoding (padded 256 B) 2.12 µs 1.18 µs 1.80x faster
Packet decoding (padded 256 B) 7.15 µs 4.00 µs 1.79x faster
Noise XX full 3-msg handshake 680.36 µs 669.89 µs 1.02x (X25519 scalar-mult bound)
Noise transport encrypt + decrypt (220 B) 87.55 µs 7.38 µs 11.86x faster
Fragmentation & reassembly (2 KB) 104.48 µs 38.18 µs 2.74x faster
Packet deduplication (SHA-256 LRU) 4.46 µs 1.06 µs 4.19x faster
Mesh routing (1-pass Rust vs Python) 7.45 µs 4.33 µs 1.72x faster
LAN TCP stream framing (20 frames) 30.17 µs 1.19 µs 25.34x faster
Full inbound DM pipeline (1,000 packets) 176.25 µs 24.20 µs 7.28x faster

FFI & Python Heap Allocation Improvements

Metric Previous (v0.3.2) v0.3.3
PyO3 crossings per inbound encrypted frame 4+ 1
Python tracemalloc peak allocation (1,000-frame workload) 105.7 KiB 0.8 KiB (~132x lower) (Python pipeline allocation, not total process RAM)
Mesh runtime ownership Parallel Python + Rust Single authoritative Rust path
Peer-state ownership Python dictionaries Bounded native Rust NativePeerStateEngine

Benchmark figures reflect measured workloads in the environment above (re-verified in a second run showing 8.04x inbound DM pipeline speedup and 1.03x Noise handshake) and are not universal hardware guarantees.


Security Improvements

Security Area Previous (v0.3.2) v0.3.3 Improvement
Active Noise session ownership Python-managed session state Authoritative Rust NativeNoiseSession
Secret key memory Eager Python bytes copy in NoiseCipherState ZeroizeOnDrop-managed Rust ownership (does not guarantee erasure from OS swap/crash dumps)
Transport nonce exhaustion No u32::MAX upper ceiling guard Fail-closed NOISE_MAX_TRANSPORT_NONCE = u32::MAX + rekey threshold
Replay protection Nonce-0 exception risk Strict 1,024-entry sliding window including wire nonce 0
AEAD failure handling Risk of mutating replay state before auth Replay window updates strictly after AEAD tag verification succeeds
Peer identity & legacy TUI IDs Unprotected mappings / strict SHA-256 blocked legacy TUI Collision-safe NativePeerStateEngine + post-Noise-auth legacy binding; distinct observed / authenticated / verified trust
Pending DM queue DoS Unbounded _pending_messages dict Hard caps: 32 per peer / 512 globally
Protocol fallback Risk of unintended downgrade Fail-closed rejection on handshake, replay, identity, or AEAD error

Note: Noise XX authentication proves possession of a peer's static private key (continuity), not real-world human identity; out-of-band fingerprint verification (/verify) is required for verified trust.


Python-to-Rust Migration Progress

  • Stage 1 (v0.3.1): Binary codec, padding, fragmentation, reassembly, TCP framing, dedup — ✅ Completed
  • Stage 2 (v0.3.2): Native Rust cryptography & Noise XX foundation — ✅ Completed
  • Phase 2.2 / Stage 3 (v0.3.3): Authoritative Rust Noise XX, NativeProtocolEngine, NativePeerStateEngine, authoritative Mesh Router/Store-and-Forward/ACK tracker, runtime LAN IP rate limiter & BLE ATT MTU sizing — ✅ Completed
  • Stage 4 (Next): Fully native Tokio LAN UDP/TCP transport I/O loops — 🔄 Logic foundations wired; async socket I/O remains in Python
  • Stage 5 (Planned): Fully native Rust BLE OS drivers (WinRT / BlueZ / CoreBluetooth) — 🔄 State/MTU foundations wired; OS drivers remain in Python
  • Stages 6–7 (Planned): Native Rust Session Coordinator, encrypted local storage, and Ratatui TUI/CLI (eventual removal of Python/PyO3/Maturin).

Cross-Platform Packages & Verified SHA-256 Checksums

All 15 release assets were built and verified in GitHub Actions Release run 44473478669:

Platform / Format Asset Filename Size Verified SHA-256
Windows x64 Installer (unsigned open-source build) BitChat-0.3.3-windows-x64.exe 17.76 MB BB0609FCE1B3A68A1EA358024FE501093D330CC092D1BD562EAC5FF124ECCEEC
Linux Debian/Ubuntu (amd64) bitchat_0.3.3_amd64.deb 18.30 MB 6916C412824EC2A93343FEE39F8975C72613C41BE3D4B6BD453DF77B0A4592A6
Linux Universal AppImage (x86_64) BitChat-0.3.3-x86_64.AppImage 20.75 MB C96FB175C97DBC9C32FA160C8A97AA0E72572DBFF01728B7C48F70F82FD20156
Windows Python 3.12+ ABI3 Wheel bitchat-0.3.3-cp312-abi3-win_amd64.whl 987.61 KB 3FA7A9608FDEF55005200264877CF7CEB3B3E24F6D8367B61DF8BA6D7CF8B48F
Linux Python 3.12+ ABI3 Wheel bitchat-0.3.3-cp312-abi3-linux_x86_64.whl 1012.43 KB 4F2136A5070E0173A3C52E5AC21F56E3EB33D536B75CBC09673CFAF9A8A21BDF
macOS Apple Silicon (arm64) ABI3 Wheel bitchat-0.3.3-cp312-abi3-macosx_11_0_arm64.whl 929.78 KB 6259AF88170F981D5D6C1F3395E976B24DF6FB85BC71628251A0BF173B4CBEE4
Universal Source Tarball (sdist) bitchat-0.3.3.tar.gz 317.01 KB 8B96CAFB08564C20ED76C66F8FB2EF97DA00BC99005055105602706ED55F50D6
WinGet Manifest Java-Mx.BitChat.yaml 1.63 KB C440175BC3612E687A0FFBD1FEE4F6E14BE7C63AF79CC7EFADE285D136C235C4

(Matching .sha256 files are attached for every downloadable archive/installer.)


Verification, Testing & Known Limitations

  • CI Verification: Passed on ubuntu-latest and windows-latest across Python 3.12 & 3.13 (cargo fmt, cargo clippy -D warnings, 21/21 cargo test, ruff, pyright, full pytest), plus macos-latest (arm64) wheel build & native/interop tests, plus Windows silent install/uninstall smoke test.
  • Local Verification: Verified on Windows 11 AMD64 (Python 3.14.7, outside the official CI matrix): 21/21 Rust tests, 1,285 Python tests passed (1 skipped), winget validate passing on both multi-file and singleton manifests.
  • Known Limitations:
    • Physical two-machine over-the-air BLE/LAN hardware validation (including live binary testing against bitchat-tui) has not been executed; BLE tests use WinRT/BlueZ fakes and simulated adapters.
    • macOS does not yet ship .dmg/.pkg installers, an Intel x86_64 prebuilt wheel (source build via uv supported), or BLE Peripheral (GATT server) hosting.
    • Windows .exe installer is currently unsigned (NotSigned); verify SHA-256 checksums before execution.
    • Local identity.json private keys rely on OS user ACLs (0600 POSIX / Windows user DACL) without passphrase encryption at rest yet.
    • Flatpak, Snap, and Arch PKGBUILD manifests are updated to 0.3.3 in-repo; no .flatpak bundle asset was emitted by the runner in run 44473478669.

Full Technical Documentation