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

v0.0.21: TUI overhaul, WZP call infrastructure, security hardening, federation

Browse Source 
TUI:
- Split 1,756-line app.rs monolith into 7 modules (types, draw, commands, input, file_transfer, network, mod)
- Message timestamps [HH:MM], scrolling (PageUp/Down/arrows), connection status dot, unread badge
- /help command, terminal bell on incoming DM, /devices + /kick commands
- 44 unit tests (types, input, draw with TestBackend)

Server — WZP Call Infrastructure (FC-2/3/5/6/7/10):
- Call state management (CallState, CallStatus, active_calls, calls + missed_calls sled trees)
- WS call signal awareness (Offer/Answer/Hangup update state, missed call on offline)
- Group call endpoint (POST /groups/:name/call with SHA-256 room ID, fan-out)
- Presence API (GET /presence/:fp, POST /presence/batch)
- Missed call flush on WS reconnect
- WZP relay config + CORS

Server — Security (FC-P1):
- Auth enforcement middleware (AuthFingerprint extractor on 13 write handlers)
- Session auto-recovery (delete corrupted ratchet, show [session reset])
- WS connection cap (5/fingerprint) + global concurrency limit (200)
- Device management (GET /devices, POST /devices/:id/kick, POST /devices/revoke-all)

Server — Federation:
- Two-server federation via JSON config (--federation flag)
- Periodic presence sync (every 5s, full-state, self-healing)
- Message forwarding via HTTP POST with SHA-256(secret||body) auth
- Graceful degradation (peer down = queue locally)
- deliver_or_queue() replaces push-or-queue in ws.rs + messages.rs

Client — Group Messaging:
- SenderKeyDistribution storage + GroupSenderKey decryption in TUI
- sender_keys sled tree in LocalDb

WASM:
- All 8 WireMessage variants handled (no more "unsupported")
- decrypt_group_message() + create_sender_key_from_distribution() exports
- CallSignal parsing with signal_type mapping

Docs:
- ARCHITECTURE.md rewritten with Mermaid diagrams
- README.md created
- TASK_PLAN.md with FC-P{phase}-T{task} naming
- PROGRESS.md updated to v0.0.21

WZP submodule updated to 6f4e8eb (IAX2 trunking, adaptive quality, metrics, all S-tasks done)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
2026-03-28 16:45:58 +04:00
parent 4a4fa9fab4
commit 3e0889e5dc
36 changed files with 5237 additions and 2232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

930
warzone/docs/ARCHITECTURE.md
View File

File diff suppressed because it is too large Load Diff

70
warzone/docs/PROGRESS.md
View File

@@ -1,6 +1,6 @@
# Warzone Messenger (featherChat) — Progress Report
**Current Version:** 0.0.20
**Current Version:** 0.0.21
**Last Updated:** 2026-03-28
---
@@ -68,16 +68,42 @@ Built on the Phase 1 foundation to deliver a complete messaging experience:
| 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 |
---
## Current Version: v0.0.20
## Current Version: v0.0.21
### Codebase Statistics
| Metric | Value |
|-------------------|--------------------------------|
| Crates | 5 (protocol, server, client, wasm, mule) |
| Protocol tests | 28 |
| Total tests | 72 (28 protocol + 44 client) |
| Server routes | 12 files, 9 new endpoints |
| TUI modules | 7 (split from 1 monolith) |
| Rust edition | 2021 |
| Min Rust version | 1.75 |
| License | MIT |
@@ -91,7 +117,7 @@ Built on the Phase 1 foundation to deliver a complete messaging experience:
| prekey | Signed + one-time pre-keys |
| x3dh | Extended Triple Diffie-Hellman |
| ratchet | Double Ratchet state machine |
| message | WireMessage (7 variants), content types|
| message | WireMessage (8 variants incl. CallSignal)|
| sender_keys | Sender Key encrypt/decrypt/rotate |
| history | Encrypted backup format |
| ethereum | secp256k1, Keccak-256, EIP-55 |
@@ -121,18 +147,29 @@ Built on the Phase 1 foundation to deliver a complete messaging experience:
## Test Suite
28 tests across the protocol crate:
72 tests across protocol + client 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 | ~4 | Initiate/respond, shared secret match, with/without OTPK |
| ratchet | ~6 | Encrypt/decrypt, out-of-order, multiple messages, ping-pong |
| 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 | ~2 | Bundle generation, signature verification |
| 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 |
---
@@ -224,11 +261,14 @@ Built on the Phase 1 foundation to deliver a complete messaging experience:
- Cross-compilation CI (Linux x86/ARM, macOS, Windows, WASM)
- PWA: service worker, offline shell, install prompt
### Priority Order
### Priority Order (Updated v0.0.21)
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
1. **Security (FC-P1)** — auth enforcement, rate limiting, device revocation
2. **TUI call integration (FC-P2)** — /call, /accept, /hangup commands
3. **Web call integration (FC-P3)** — WASM CallSignal + browser call UI
4. **Protocol hardening (FC-P4)** — session/message versioning
5. Federation (Phase 3) — multi-server deployment
6. Mule protocol (Phase 4) — physical delivery
7. Polish (FC-P6) — search, reactions, typing indicators
See `TASK_PLAN.md` for the detailed task breakdown with IDs and dependencies.

239
warzone/docs/TASK_PLAN.md Normal file
View File

@@ -0,0 +1,239 @@
# featherChat Task Plan
**Version:** 0.0.21+
**Last Updated:** 2026-03-28
**Naming:** `FC-P{phase}-T{task}[-S{subtask}]`
---
## Completed (This Sprint)
### TUI Refactor
- [x] Split `app.rs` monolith (1,756 lines) into 7 modules: types, draw, commands, input, file_transfer, network, mod
- [x] 44 unit tests across types.rs, input.rs, draw.rs
### TUI Improvements
- [x] Message timestamps `[HH:MM]` on every ChatLine
- [x] Message scrolling (PageUp/Down by 10, Up/Down by 1, auto-snap on send)
- [x] Connection status indicator (green/red dot in header)
- [x] Unread badge `[N new]` when scrolled up
- [x] `/help` command listing all commands + navigation
- [x] Terminal bell on incoming DM
### WZP Server Integration (featherChat side)
- [x] FC-2: Call state management (`calls` + `missed_calls` sled trees, `CallState`, `CallStatus`, `active_calls`)
- [x] FC-3: WS call signaling awareness (Offer creates CallState, Answer updates, Hangup ends + missed call on offline)
- [x] FC-5: Group-to-room mapping (`POST /groups/:name/call` with SHA-256 room ID, fan-out to members)
- [x] FC-6: Presence API (`GET /presence/:fp`, `POST /presence/batch`)
- [x] FC-7: Missed call notifications (flush on WS reconnect as `{"type":"missed_call"}`)
- [x] FC-10: WZP relay config (`GET /wzp/relay-config` + CORS layer)
### WZP Side (all 9 tasks done by WZP team)
- [x] WZP-S-1 through WZP-S-9: Identity alignment, relay auth, signaling bridge, room ACL, crypto handshake, web bridge auth, wzp-proto standalone, CLI seed input, hardcoded assumptions fixed
---
## FC-P1: Security & Auth Foundation
**Goal:** Close the security gaps before wider deployment. Auth enforcement is the critical path.
| ID | Task | Effort | Dep | Status |
|----|------|--------|-----|--------|
| FC-P1-T1 | Auth enforcement middleware | 0.5d | — | TODO |
| FC-P1-T2 | Session auto-recovery | 1d | — | TODO |
| FC-P1-T3 | Rate limiting + connection guards | 0.5d | — | TODO |
| FC-P1-T4 | Device management + session revocation | 1d | T1 | TODO |
### FC-P1-T1: Auth Enforcement Middleware
**What:** Add axum middleware to enforce bearer tokens on protected `/v1/*` routes.
**Why:** Currently anyone can impersonate any fingerprint. Tokens are issued but never required.
**Scope:**
- Extract bearer token from `Authorization` header
- Call `validate_token()` for write operations (send, groups, aliases, calls)
- Read-only routes (health, key fetch) remain unauthenticated
- Return 401 with clear error on invalid/missing token
### FC-P1-T2: Session Auto-Recovery
**What:** When ratchet decryption fails (corrupted state), auto-send a new X3DH KeyExchange.
**Why:** Corrupted session = permanent inability to decrypt from that peer.
**Scope:**
- Detect decryption failure in `process_wire_message()`
- Delete corrupted session from local DB
- Initiate fresh X3DH key exchange
- Show "[session reset]" system message (like Signal)
- Cap auto-recovery attempts (max 3 per peer per hour)
### FC-P1-T3: Rate Limiting + Connection Guards
**What:** Tower rate-limit layer + per-fingerprint connection caps.
**Why:** Zero protection against auth spam, message flooding, WS connection spam.
**Scope:**
- Global rate limit: 100 req/s per IP (tower-governor or tower-http)
- Per-fingerprint WS connection cap: max 5 simultaneous connections
- Auth challenge rate limit: max 10/minute per fingerprint
- Group creation limit: max 5/hour per fingerprint
### FC-P1-T4: Device Management + Session Revocation
**What:** Let users see and kill their active sessions.
**Why:** Compromised or stale devices need to be revocable immediately.
| Subtask | What |
|---------|------|
| FC-P1-T4-S1 | Server: `GET /v1/devices` — list active WS connections (device_id, IP, connected_at) |
| FC-P1-T4-S2 | Server: `POST /v1/devices/:id/kick` — force-close WS + invalidate token |
| FC-P1-T4-S3 | Server: `POST /v1/devices/revoke-all` — nuke all sessions except current |
| FC-P1-T4-S4 | TUI: `/devices` command — list active sessions |
| FC-P1-T4-S5 | TUI: `/kick <device_id>` command — revoke a specific device |
**Dep on T1:** Kick/revoke endpoints must verify the requester owns the fingerprint.
---
## FC-P2: TUI Call Integration
**Goal:** Make call signaling work end-to-end in the TUI. Server infrastructure is ready (FC-2/3/5/6/7).
| ID | Task | Effort | Dep | Status |
|----|------|--------|-----|--------|
| FC-P2-T1 | `/call <fp>` command — send CallSignal::Offer | 0.5d | — | TODO |
| FC-P2-T2 | `/accept` + `/reject` commands | 0.5d | T1 | TODO |
| FC-P2-T3 | `/hangup` command | 0.25d | T1 | TODO |
| FC-P2-T4 | Call state machine (Idle/Ringing/Active/Ended) | 0.5d | T1 | TODO |
| FC-P2-T4-S1 | Incoming call notification banner | 0.25d | T4 | TODO |
| FC-P2-T4-S2 | In-call header indicator (duration, peer) | 0.25d | T4 | TODO |
| FC-P2-T5 | Missed call display (parse WS JSON) | 0.25d | — | TODO |
| FC-P2-T6 | `/contacts` online status via presence API | 0.25d | — | TODO |
---
## FC-P3: Web Call Integration
**Goal:** Enable voice/video calling from the browser through featherChat's web client.
| ID | Task | Effort | Dep | Status |
|----|------|--------|-----|--------|
| FC-P3-T1 | WASM: parse CallSignal in `decrypt_wire_message()` | 0.5d | — | TODO |
| FC-P3-T2 | WASM: `create_call_signal()` export for JS | 0.5d | — | TODO |
| FC-P3-T3 | Web client: call/accept/reject UI | 1d | T1, T2 | TODO |
| FC-P3-T4 | Web client: integrate wzp-web audio bridge | 1d | T3 | TODO |
| FC-P3-T5 | Extract web client from monolith (web.rs) | 1-2d | — | TODO |
---
## FC-P4: Protocol & Architecture
**Goal:** Harden the protocol for forward compatibility and resilience.
| ID | Task | Effort | Dep | Status |
|----|------|--------|-----|--------|
| FC-P4-T1 | Session state versioning | 0.5d | — | TODO |
| FC-P4-T2 | WireMessage versioning (envelope format) | 1d | — | TODO |
| FC-P4-T3 | Periodic auto-backup | 0.5d | — | TODO |
| FC-P4-T4 | libsignal migration assessment | 1-2w | — | TODO |
---
## FC-P5: Major Features
**Goal:** Core differentiators — physical delivery, federation, identity provider.
| ID | Task | Effort | Dep | Status |
|----|------|--------|-----|--------|
| FC-P5-T1 | Mule binary (physical message delivery) | 3-5d | — | TODO |
| FC-P5-T2 | DNS federation (server discovery + relay) | 2-3w | P4-T2 | TODO |
| FC-P5-T3 | OIDC identity provider | 1-2w | P1-T1 | TODO |
| FC-P5-T4 | Smart contract access control | 3-4w | P5-T3 | TODO |
---
## FC-P6: TUI Polish
**Goal:** UX improvements for daily use.
| ID | Task | Effort | Dep | Status |
|----|------|--------|-----|--------|
| FC-P6-T1 | Message search (local history) | 1d | — | TODO |
| FC-P6-T2 | Read receipts (viewport tracking) | 0.5d | — | TODO |
| FC-P6-T3 | Typing indicators | 0.5d | — | TODO |
| FC-P6-T4 | Message reactions (emoji) | 1d | P4-T2 | TODO |
| FC-P6-T5 | Voice messages as attachments | 1d | — | TODO |
| FC-P6-T6 | Message wrapping for long text | 0.5d | — | TODO |
| FC-P6-T7 | Tab completion for commands/aliases | 0.5d | — | TODO |
| FC-P6-T8 | File transfer progress gauge | 0.5d | — | TODO |
---
## Parallelization Guide
Tasks with **no dependencies** that can run simultaneously:
**Sprint A (Security — P1):**
```
FC-P1-T1 (auth middleware) — server only
FC-P1-T2 (session recovery) — client only
FC-P1-T3 (rate limiting) — server only
→ then FC-P1-T4 (devices, needs T1)
```
**Sprint B (TUI Calls — P2):**
```
FC-P2-T1 (call command) → T2 (accept/reject) → T3 (hangup)
FC-P2-T4 (state machine) → T4-S1 (banner) + T4-S2 (header)
FC-P2-T5 (missed calls) — independent
FC-P2-T6 (contacts online) — independent
```
**Sprint C (Web — P3):**
```
FC-P3-T1 (WASM parse) — independent
FC-P3-T2 (WASM create) — independent
FC-P3-T5 (extract web.rs) — independent
→ then T3 (call UI) → T4 (audio)
```
---
## Server Architecture (Post-Sprint)
```
warzone-server/src/
├── main.rs — startup, CORS, state init
├── state.rs — AppState, Connections, CallState, DedupTracker
├── db.rs — sled trees: keys, messages, groups, aliases, tokens, calls, missed_calls
├── errors.rs — AppError, AppResult
├── routes/
│ ├── mod.rs — route composition
│ ├── auth.rs — challenge-response, token validation
│ ├── calls.rs NEW — call CRUD, group call, missed calls API
│ ├── presence.rs NEW — online status (single + batch)
│ ├── wzp.rs NEW — relay config + service token
│ ├── groups.rs — group management + fan-out
│ ├── ws.rs — WebSocket handler + call signal awareness + missed call flush
│ ├── keys.rs — pre-key bundle registration
│ ├── messages.rs — HTTP message queue
│ ├── aliases.rs — alias registration + resolution
│ ├── health.rs — health check
│ └── web.rs — embedded web client
```
## TUI Architecture (Post-Sprint)
```
warzone-client/src/tui/
├── mod.rs — run_tui() entry point + event loop
├── types.rs — App, ChatLine, PendingFileTransfer, ReceiptStatus, normfp()
├── draw.rs — UI rendering (timestamps, scroll, connection dot, unread badge)
├── input.rs — keyboard handling (text editing, scroll keys)
├── commands.rs — /slash commands + /help
├── file_transfer.rs — chunked file send (DM + group)
└── network.rs — WS/HTTP polling + incoming message processing + bell
```
## Test Coverage
| Crate | Tests | What |
|-------|------:|------|
| warzone-protocol | 28 | Crypto, ratchet, X3DH, sender keys, identity, ethereum, prekeys |
| warzone-client (types) | 10 | App init, ChatLine, normfp |
| warzone-client (input) | 25 | All keybindings, scroll, text editing |
| warzone-client (draw) | 9 | Rendering, timestamps, scroll, connection dot, unread badge |
| **Total** | **72** | All passing |