featherChat/warzone/docs/PROGRESS.md

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