featherChat/warzone/docs/TASK_PLAN.md

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

• Split app.rs monolith (1,756 lines) into 7 modules: types, draw, commands, input, file_transfer, network, mod
• 44 unit tests across types.rs, input.rs, draw.rs

TUI Improvements

• Message timestamps [HH:MM] on every ChatLine
• Message scrolling (PageUp/Down by 10, Up/Down by 1, auto-snap on send)
• Connection status indicator (green/red dot in header)
• Unread badge [N new] when scrolled up
• /help command listing all commands + navigation
• Terminal bell on incoming DM

WZP Server Integration (featherChat side)

• FC-2: Call state management (calls + missed_calls sled trees, CallState, CallStatus, active_calls)
• FC-3: WS call signaling awareness (Offer creates CallState, Answer updates, Hangup ends + missed call on offline)
• FC-5: Group-to-room mapping (POST /groups/:name/call with SHA-256 room ID, fan-out to members)
• FC-6: Presence API (GET /presence/:fp, POST /presence/batch)
• FC-7: Missed call notifications (flush on WS reconnect as {"type":"missed_call"})
• FC-10: WZP relay config (GET /wzp/relay-config + CORS layer)

WZP Side (all 9 tasks done by WZP team)

• 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