featherChat/warzone/docs/PROGRESS.md

Warzone Messenger (featherChat) — Progress Report

Current Version: 0.0.46 Last Updated: 2026-03-30

---

Project Timeline

Phase 0 — Python Prototype (pre-Rust)

The project began as chat.py, a Python WebSocket chat with basic features:

• Basic chat server + web UI
• WebSocket SSH tunnel
• Nginx reverse proxy + ArvanCloud deployment
• ECDH + AES-GCM DMs (no forward secrecy)
• Group chat with passwords
• PWA support
• File upload

Phase 1 — Identity & Crypto Foundation (Rust Rewrite)

The Rust rewrite established the cryptographic foundation:

Feature	Version	Status
Cargo workspace scaffold (5 crates)	0.0.1	Done
Seed-based identity (Ed25519 + X25519)	0.0.2	Done
BIP39 mnemonic generation and recovery	0.0.2	Done
Seed encryption at rest (Argon2id + ChaCha20-Poly1305)	0.0.3	Done
Pre-key bundle generation and storage	0.0.4	Done
X3DH key exchange implementation	0.0.5	Done
Double Ratchet for 1:1 messaging	0.0.6	Done
Basic server: axum, sled DB, store-and-forward	0.0.4	Done
CLI client with subcommands	0.0.5	Done
WASM bridge (warzone-wasm crate)	0.0.8	Done
Server auth (challenge-response, bearer tokens)	0.0.9	Done
OTP key replenishment	0.0.9	Done
Fetch-and-delete delivery	0.0.7	Done
Aliases with TTL, recovery keys	0.0.10	Done
17 protocol tests	0.0.10	Done
CLI <-> Web interop verified	0.0.10	Done

Phase 2 — Core Messaging

Built on the Phase 1 foundation to deliver a complete messaging experience:

Feature	Version	Status
TUI client (ratatui + crossterm)	0.0.7	Done
Web client (WASM)	0.0.8	Done
WebSocket real-time push	0.0.11	Done
Delivery receipts (sent/delivered/read)	0.0.12	Done
File transfer (chunked, SHA-256 verified)	0.0.13	Done
Group chat (server fan-out)	0.0.10	Done
Group management (create/join/leave/kick)	0.0.14	Done
Sender Keys for group encryption	0.0.15	Done
Message deduplication (bounded FIFO)	0.0.16	Done
Ethereum-compatible identity (secp256k1)	0.0.14	Done
Encrypted backup/restore	0.0.17	Done
Local message history (sled)	0.0.17	Done
Contact list with message counts	0.0.17	Done
Alias auto-renewal on activity	0.0.18	Done
Multi-device key registration	0.0.18	Done
DB lock handling with user-friendly errors	0.0.19	Done
Readline-style TUI editing (Ctrl-A/E/U/W)	0.0.19	Done
Reply shortcut (/r, /reply)	0.0.19	Done
28 protocol tests	0.0.20	Done

Phase 2.5 — WZP Integration & TUI Overhaul (v0.0.21)

Feature	Version	Status
warzone-protocol standalone-importable	0.0.21	Done
CallSignal WireMessage variant	0.0.21	Done
Auth token validation endpoint	0.0.21	Done
TUI modular split (7 modules from 1)	0.0.21	Done
TUI message timestamps [HH:MM]	0.0.21	Done
TUI message scrolling (PageUp/Down/arrows)	0.0.21	Done
TUI connection status indicator	0.0.21	Done
TUI unread message badge	0.0.21	Done
TUI /help command	0.0.21	Done
TUI terminal bell on incoming DM	0.0.21	Done
44 TUI unit tests (types, input, draw)	0.0.21	Done
Call state management (server)	0.0.21	Done
WS call signaling awareness	0.0.21	Done
Group-to-room mapping + group call API	0.0.21	Done
Presence/online status API	0.0.21	Done
Missed call notifications	0.0.21	Done
WZP relay config + CORS	0.0.21	Done
WZP submodule: all 9 S-tasks done	0.0.21	Done
72 total tests (28 protocol + 44 client)	0.0.21	Done

---

Version History

Version	Date	Highlights
0.0.22	2026-03-28	ETH identity in web client
0.0.23-24	2026-03-28	ETH display everywhere (TUI + Web)
0.0.25-26	2026-03-28	Federation persistent WS, text selection
0.0.27-29	2026-03-29	Bot API: BotFather, getUpdates, sendMessage
0.0.30-31	2026-03-29	Bot numeric IDs, inline keyboards
0.0.32-33	2026-03-29	System bots config, version bump
0.0.34	2026-03-29	Bot sendMessage fix, per-bot ID mapping
0.0.35	2026-03-29	WASM create_call_signal, selectable identity
0.0.36	2026-03-29	Web call UI (call/accept/reject/hangup)
0.0.37	2026-03-29	TUI call state UI, missed calls, inline keyboards
0.0.38	2026-03-29	Session versioning, wire envelope, auto-backup
0.0.39	2026-03-30	Contacts online, message wrap, tab complete, OTPK
0.0.40	2026-03-30	Call reload, ETH cache prefill, 10 server tests
0.0.41	2026-03-30	Read receipts (viewport tracking)
0.0.42	2026-03-30	Markdown rendering in TUI messages
0.0.43	2026-03-30	Voice calls via WZP audio bridge
0.0.44	2026-03-30	Web UI polish, ETH display, call routing fixes
0.0.45	2026-03-30	Call ring tones + group calls
0.0.46	2026-03-30	Group call fixes, admin commands, ETH in members

---

Current Version: v0.0.46

Codebase Statistics

Metric	Value
Crates	5 (protocol, server, client, wasm, mule)
Total tests	~155 (protocol + client + server)
Server routes	12 files, 15+ endpoints
TUI modules	7 (split from 1 monolith)
Rust edition	2021
Min Rust version	1.75
License	MIT

Protocol Crate Modules

Module	Approximate Scope
identity	Seed, keypair derivation, fingerprints
crypto	HKDF, ChaCha20-Poly1305 AEAD
prekey	Signed + one-time pre-keys
x3dh	Extended Triple Diffie-Hellman
ratchet	Double Ratchet state machine
message	WireMessage (8 variants incl. CallSignal)
sender_keys	Sender Key encrypt/decrypt/rotate
history	Encrypted backup format
ethereum	secp256k1, Keccak-256, EIP-55
types	Fingerprint, DeviceId, SessionId
mnemonic	BIP39 encode/decode
store	Storage trait definitions
errors	Error types

Feature Summary

Working end-to-end:

• 1:1 encrypted DMs with forward secrecy (X3DH + Double Ratchet)
• Group messaging with Sender Keys
• WebSocket real-time delivery + offline queue
• File transfer (up to 10 MB, chunked, SHA-256 verified)
• Delivery and read receipts (viewport tracking)
• TUI client with full command set
• Web client (WASM) with identical crypto
• Alias system with TTL, recovery, admin
• Challenge-response authentication
• Ethereum address derivation from same seed (displayed in TUI + Web)
• Encrypted backup and restore (with auto-backup)
• Contact list and message history
• Multi-device support (basic)
• Bot API with BotFather (Telegram-compatible)
• Voice calls (1:1 via WZP, Web audio bridge)
• Group calls (transport-encrypted, fan-out signaling)
• Call ring tones (Web Audio API oscillators)
• Markdown rendering in TUI + Web messages
• Federation with persistent WebSocket
• Admin commands
• Session state versioning + wire envelope format

---

Test Suite

~155 tests across protocol + client + server crates:

Protocol Tests (28)

Module	Tests	Coverage
identity	3	Deterministic derivation, mnemonic roundtrip, fingerprint format
crypto	4	AEAD roundtrip, wrong key, wrong AAD, HKDF determinism
x3dh	1	Shared secret match between Alice and Bob
ratchet	5	Basic, bidirectional, multiple, out-of-order, 100 messages
sender_keys	4	Basic encrypt/decrypt, multiple messages, rotation, old key rejection
ethereum	5	Deterministic derivation, address format, checksum, sign/verify, different seeds
history	2	Roundtrip encryption, wrong seed rejection
prekey	3	SPK verify, tamper detection, OTPK generation
mnemonic	1	BIP39 roundtrip

Client Tests (44)

Module	Tests	Coverage
tui::types	10	App init, scroll/connected defaults, ChatLine timestamps, normfp, add_message
tui::input	25	8 text editing, 7 cursor movement, 2 quit, 8 scroll keybindings
tui::draw	9	Rendering smoke, header fingerprint, connection dot (red/green), timestamps, scroll show/hide, unread badge

Server Tests (10+)

Area	Tests	Coverage
integration	10+	Call reload, ETH cache, presence, routing

---

Bugs Fixed

Bug	Version Fixed	Description
X3DH OTPK mismatch	0.0.8	Web client regenerated SPK on each page load, causing X3DH failures. Fixed by persisting SPK secret in localStorage and restoring on load.
Axum route syntax	0.0.11	Route path parameters used wrong syntax for axum 0.7. Updated to /:param format.
WASM SPK regeneration	0.0.12	WasmIdentity regenerated pre-keys on every bundle_bytes() call. Fixed by caching the bundle and storing SPK secret bytes.
DB lock handling	0.0.19	sled database lock caused cryptic panic when another warzone process was running. Added user-friendly error message with recovery instructions.
Dedup overflow	0.0.16	Dedup tracker grew unbounded. Fixed with FIFO eviction at 10,000 entries.
Alias normalization	0.0.18	Fingerprints with colons caused lookup failures. Added normalize_fp() to strip non-hex characters.
Receipt routing	0.0.12	Receipts sent to wrong fingerprint when switching peers in TUI. Fixed by including correct sender_fingerprint in Receipt wire messages.
Lookbehind regex	0.0.42	JS lookbehind regex broke Safari markdown rendering. Replaced with forward-compatible pattern.
Resolve parens warning	0.0.43	Unnecessary parentheses in resolve.rs caused compiler warning. Removed.

---

Known Issues and Limitations

Known Issues

1. Group call signals only reach online members: Offline members do not receive group call join signals. They must be online when the call starts.

2. TUI voice needs web client: The TUI cannot capture/play audio natively; voice calls require the web client with WZP audio bridge. TUI voice via cpal is planned (FC-P7-T1).

3. Bot messages are plaintext: Bot API messages are not E2E encrypted (v1 design decision). Bots see and send cleartext.

4. Group calls are transport-encrypted only: Group call audio is encrypted by QUIC on the wire but the WZP relay can see plaintext audio. MLS E2E encryption is planned (FC-P5-T5).

5. Service worker cache must be bumped: After WASM changes, the wz-vN cache version in web.rs must be incremented or browsers serve stale code.

Existing Limitations

6. No perfect forward secrecy in groups: Sender Keys provide forward secrecy within a chain but not per-message PFS like Double Ratchet. Acceptable for groups under 50 members.

7. No sealed sender: The server sees sender and recipient fingerprints in message routing metadata.

8. No server-at-rest encryption: The sled database on the server is unencrypted. Message content is E2E encrypted, but metadata (fingerprints, timestamps, group membership) is visible to the server operator.

9. Auth tokens in memory: Challenge-response tokens are partially stored in memory (challenges are in a static HashMap). Production deployment should use the DB for all auth state.

10. Single server only: No full federation between servers yet. Persistent WS relay exists but full DNS discovery is planned.

11. No push notifications: Users must keep a WebSocket connection open or poll.

12. Web client: no OTPKs: The web client does not generate one-time pre-keys (cannot reliably store secrets). X3DH works without DH4, but replay protection is slightly weaker.

13. Web client: localStorage only: Seed and session data stored in browser localStorage. Clearing browser data = lost identity.

14. No message ordering guarantees: Messages may arrive out of order. The Double Ratchet handles this for decryption, but the UI does not reorder displayed messages.

---

Roadmap: What's Next

Priority Order (Updated v0.0.46)

1. TUI voice via cpal (FC-P7-T1) — native audio capture/playback
2. Web extract (FC-P3-T5) — extract web.rs monolith into separate files
3. MLS group E2E (FC-P5-T5) — RFC 9420 for group call encryption
4. Sender Keys for DM call E2E (FC-P7-T2) — encrypted call signaling
5. WebTransport (FC-P7-T3) — replace wzp-web bridge
6. Federation (Phase 3) — DNS discovery + multi-server
7. Mule protocol (Phase 4) — physical delivery
8. Polish (FC-P6) — search, reactions, typing indicators, virtual scroll

See TASK_PLAN.md for the detailed task breakdown with IDs and dependencies.