# 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.