# Warzone Messenger (featherChat) — Progress Report

**Current Version:** 0.0.20
**Last Updated:** 2026-03-28

---

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

---

## Current Version: v0.0.20

### Codebase Statistics

| Metric            | Value                          |
|-------------------|--------------------------------|
| Crates            | 5 (protocol, server, client, wasm, mule) |
| Protocol tests    | 28                             |
| 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 (7 variants), content types|
| 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
- 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
- Encrypted backup and restore
- Contact list and message history
- Multi-device support (basic)

---

## Test Suite

28 tests across the protocol crate:

| Module        | Tests | Coverage                                    |
|---------------|-------|---------------------------------------------|
| identity      | 3     | Deterministic derivation, mnemonic roundtrip, fingerprint format |
| crypto        | 4     | AEAD roundtrip, wrong key, wrong AAD, HKDF determinism |
| x3dh          | ~4    | Initiate/respond, shared secret match, with/without OTPK |
| ratchet       | ~6    | Encrypt/decrypt, out-of-order, multiple messages, ping-pong |
| 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        | ~2    | Bundle generation, signature verification    |

---

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

---

## Known Issues and Limitations

### Current Limitations

1. **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.

2. **No sealed sender:** The server sees sender and recipient fingerprints in message routing metadata. Planned for Phase 6.

3. **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.

4. **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.

5. **No rate limiting:** No protection against message flooding or registration spam. Planned for Phase 7.

6. **Single server only:** No federation between servers yet. Planned for Phase 3.

7. **No push notifications:** Users must keep a WebSocket connection open or poll. ntfy integration planned for Phase 7.

8. **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.

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

10. **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

### Phase 3 — Federation & Key Transparency (next priority)

- DNS TXT record format for server discovery
- User self-signed key publication to DNS
- Key verification: server vs DNS cross-check
- Server-to-server mutual TLS
- Federated message delivery
- Server key pinning (TOFU)
- Gossip-based peer discovery

### Phase 4 — Warzone Delivery

- Mule protocol specification and implementation
- Mule authentication and authorization
- Message pickup with capacity declaration
- Delivery receipt enforcement
- Outer encryption layer (hide metadata from mule)
- Bundle compression (zstd)
- Mule CLI binary

### Phase 5 — Transport Fallbacks

- Bluetooth mule transfer (phone-to-phone)
- LoRa transport layer (compact binary format)
- mDNS / LAN discovery for local mesh
- Wi-Fi Direct for nearby device sync

### Phase 6 — Metadata Protection

- Sealed sender (server doesn't know the sender)
- Onion routing between federated servers (opt-in)
- Padding and traffic shaping
- Traffic analysis resistance

### Phase 7 — Polish & Operations

- ntfy push notification integration
- DNS-over-HTTPS for censored networks
- Admin CLI for server management
- Rate limiting and abuse prevention
- Monitoring and health checks
- Audit logging
- Server-at-rest encryption (optional `--encrypt-db` flag)
- Cross-compilation CI (Linux x86/ARM, macOS, Windows, WASM)
- PWA: service worker, offline shell, install prompt

### Priority Order

1. Federation (Phase 3) — enables multi-server deployment
2. Mule protocol (Phase 4) — core differentiator for warzone use
3. Sealed sender (Phase 6) — strongest metadata privacy
4. Push notifications (Phase 7) — usability for mobile/desktop
5. Transport fallbacks (Phase 5) — Bluetooth, LoRa
6. Polish (Phase 7) — rate limiting, admin tools, CI