Repository navigation
BitChat v0.3.3 — Phase 2.2 Production Release: Authoritative Rust Protocol Integration, Noise XX Interoperability & Stage 3 Mesh Engine
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-closedu32::MAXnonce 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-safepeer_id <-> fingerprintbindings, anti-spoofing nickname validation, and bounded pending direct-message queues (32per peer /512global). - Single-pass Rust mesh routing & store-and-forward removing duplicate Python+Rust execution in
MeshRouterandStoreAndForwardQueue, plus nativeNativeAckTracker(0x0A DeliveryAck) and0x13 NoiseIdentityAnnouncesupport. - Controlled
bitchat-tuiinteroperability 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
NativeIpRateLimiterinto LAN discovery and controller-negotiated ATT MTU (client.mtu_size) intocompute_ble_write_chunk_size. - Cross-platform
v0.3.3packages 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)
NativeNoiseSessionRuntime Ownership:NoiseSessionnow delegates handshake progression, transport AEAD encryption/decryption, replay protection, and state tracking directly to RustNativeNoiseSession(embedding the 12-phaseNativeHandshakeStateMachine).- Zero Duplicate Cipher State & Zero Eager Python Key Copies: Removed eager
byteskey copying inNoiseCipherState; active symmetric transport keys remain insidezeroize::ZeroizeOnDrop-managed Rust structs.PyNoiseSessionis retained strictly for differential equivalence testing and non-native fallback environments. - Fail-Closed Nonce Exhaustion & Replay Hardening: Enforced
NOISE_MAX_TRANSPORT_NONCE = u32::MAX(withneeds_rekey()warning at1_000_000_000) so 4-byte wire nonces can never wrap around; enforced strict replay rejection including nonce0; ensured failed AEAD decryptions never mutate the 1,024-entry replay window; and added cleanreset_for_rehandshake()zeroization on peer reconnect.
Native Protocol Engine (rust/bitchat-core/src/engine.rs)
- Implemented
NativeProtocolEngineexecuting 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
NativePeerStateEngineproviding bounded peer registries, collision-safepeer_id <-> fingerprintmappings with reverse collision indices, anti-spoofing nickname protection, bounded pending DM queues (32per peer /512total), and strictly separatedobserved→authenticated→verifiedtrust 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_coreis loaded.NativeMeshRouter(evaluate_incoming_raw),NativeStoreAndForwardQueue, andNativeAckTrackerare 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_rawandnormalize_peer_id_raw(rust/bitchat-core/src/protocol.rs) recognizing legacy 4-byte zero-extendedbitchat-tuipeer IDs (XXXXXXXX00000000) while preserving strictSHA-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) and0x0A DeliveryAck(NativeAckTracker), backed by 10 automated interoperability tests intests/interoperability/test_tui_interop.py.
LAN & BLE Integration (src/bitchat/network/discovery.py, src/bitchat/ble/, src/bitchat/app/session_coordinator.py)
- Wired
NativeIpRateLimiterintoLANDiscovery(10 UDP discovery packets/sec per IP). - Wired negotiated controller ATT MTU (
client.mtu_size) intoNativeBleConnectionEngineandcompute_ble_write_chunk_size, dynamically sizing BLE write fragments. - Replaced the
asyncio.sleep(0.04)polling loop inSessionCoordinatorwith event-driven per-peerasyncio.Eventsignaling and unified stale handshake timers ontime.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-latestandwindows-latestacross Python 3.12 & 3.13 (cargo fmt,cargo clippy -D warnings,21/21cargo test,ruff,pyright, fullpytest), plusmacos-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/21Rust tests,1,285Python tests passed (1skipped),winget validatepassing 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/.pkginstallers, an Intelx86_64prebuilt wheel (source build viauvsupported), or BLE Peripheral (GATT server) hosting. - Windows
.exeinstaller is currently unsigned (NotSigned); verify SHA-256 checksums before execution. - Local
identity.jsonprivate keys rely on OS user ACLs (0600POSIX / Windows user DACL) without passphrase encryption at rest yet. - Flatpak, Snap, and Arch
PKGBUILDmanifests are updated to0.3.3in-repo; no.flatpakbundle asset was emitted by the runner in run44473478669.
- Physical two-machine over-the-air BLE/LAN hardware validation (including live binary testing against