manawenuz/featherChat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Comprehensive documentation: architecture, usage, integration, progress, security

Browse Source 
docs/ARCHITECTURE.md (531 lines):
  System design, ASCII diagrams, crypto stack, dual-curve identity,
  wire protocol (7 WireMessage variants), server/client architecture,
  data flow diagrams, storage model, extensibility points

docs/USAGE.md (550 lines):
  Complete user guide: installation, all CLI commands (10),
  all TUI commands (20+), all web commands, file transfer,
  identity management, aliases, groups, multi-device, backup,
  keyboard shortcuts

docs/INTEGRATION.md (542 lines):
  WarzonePhone concept, Ethereum/Web3, OIDC, DNS federation,
  transport abstraction, multi-server mode, custom clients,
  ntfy, how-to guides for extending message types/commands/storage

docs/PROGRESS.md (234 lines):
  Timeline, Phase 1 (16 features), Phase 2 (16 features),
  v0.0.20, 28 tests, bugs fixed, known limitations, Phase 3-7 roadmap

docs/SECURITY.md (438 lines):
  Threat model, 8 crypto primitives, key derivation paths,
  forward secrecy, Sender Keys trade-offs, seed security,
  server trust, WASM security, known weaknesses,
  comparison with Signal/Matrix/SimpleX

Total: 3,751 lines across 8 doc files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
2026-03-28 05:25:46 +04:00
parent fb987da8ac
commit 2dbbc61dfe
5 changed files with 2295 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

234
warzone/docs/PROGRESS.md Normal file
View File

@@ -0,0 +1,234 @@
# 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