featherChat/warzone/README.md

Warzone Messenger (featherChat)

End-to-end encrypted messenger with Signal protocol cryptography, voice/video call integration, and server federation.

Features

• E2E Encrypted DMs — X3DH key exchange + Double Ratchet (forward secrecy)
• Group Messaging — Sender Key protocol (O(1) encryption, fan-out delivery)
• Voice Calls (WZP) — DM and group calls via WarzonePhone audio bridge (QUIC SFU relay, ChaCha20-Poly1305 media)
• Ring Tones — Audible ring on incoming calls (web client)
• Group Calls — Multi-party audio via /gcall, /gjoin, /gleave-call, /gmute
• Read Receipts — Sent, delivered, and read indicators (viewport-based)
• Markdown Rendering — Bold, italic, inline code, headers, quotes, and lists in TUI and web
• File Transfer — Chunked (64KB), SHA-256 verified, ratchet-encrypted
• Admin Commands — /admin-calls, /admin-unalias for server administration
• Federation — Two-server relay with HMAC-authenticated presence sync
• TUI Client — Full-featured terminal UI (ratatui, timestamps, scrolling, receipts)
• Web Client — Identical crypto via WASM (wasm-bindgen)
• Ethereum Identity — Same seed derives messaging keypair + Ethereum address (secp256k1)
• BIP39 Seed — 24-word mnemonic for identity backup/recovery

Architecture

Clients (CLI / TUI / Web)
    |
    | E2E encrypted (ChaCha20-Poly1305)
    |
warzone-server (axum + sled)
    |
    | Federation (HTTP + HMAC)
    |
warzone-server (peer)
    |
    | Call signaling
    |
WarzonePhone Relay (QUIC SFU)

See docs/ARCHITECTURE.md for full architecture with Mermaid diagrams.

Quick Start

Build

cd warzone
cargo build --release

Generate Identity

./target/release/warzone-client init
# Outputs: 24-word BIP39 mnemonic + fingerprint

Start Server

./target/release/warzone-server --bind 0.0.0.0:7700

Start TUI

./target/release/warzone-client tui --server http://localhost:7700

WZP Setup (Voice Calls)

To enable voice calls, run a WarzonePhone relay alongside the server:

# Start the WZP QUIC relay (default port 7701)
./target/release/wzp-relay --bind 0.0.0.0:7701

# Start the server with WZP integration
./target/release/warzone-server --bind 0.0.0.0:7700 --wzp-relay http://localhost:7701

DM calls use /call @alias, group calls use /gcall within a group context.

Federation (Two Servers)

Create alpha.json:

{
  "server_id": "alpha",
  "shared_secret": "your-shared-secret",
  "peer": { "id": "bravo", "url": "http://server-b:7700" },
  "presence_interval_secs": 5
}

# Server A
warzone-server --bind 0.0.0.0:7700 --federation alpha.json

# Server B
warzone-server --bind 0.0.0.0:7700 --federation bravo.json

Messages automatically route across servers.

TUI Commands

Command	Description
/peer <fp> or /p @alias	Set DM peer
/g <name>	Switch to group (auto-join)
/call <fp>	Initiate DM voice call
/accept / /reject	Accept or reject incoming call
/hangup	End current call
/gcall	Start group call in current group
/gjoin	Join active group call
/gleave-call	Leave group call
/gmute	Toggle mute in group call
/file <path>	Send file (max 10MB)
/contacts	List contacts with message counts
/history	Show conversation history
/devices	List active device sessions
/kick <id>	Revoke a device session
/help	Full command list

Crates

Crate	Purpose
warzone-protocol	Crypto & message types (X3DH, Double Ratchet, Sender Keys)
warzone-server	HTTP/WS server with sled DB, federation, call state
warzone-client	CLI + TUI client
warzone-wasm	WASM bridge for web client
warzone-mule	Physical message delivery (planned)

Cryptographic Stack

Primitive	Purpose
Ed25519	Identity signing
X25519	Diffie-Hellman key exchange
ChaCha20-Poly1305	AEAD encryption
HKDF-SHA256	Key derivation
Argon2id	Seed encryption at rest
secp256k1	Ethereum-compatible identity

Security

• Auth enforcement on all write routes (bearer token middleware)
• Session auto-recovery on ratchet corruption
• Per-fingerprint WS connection cap (5 devices)
• Global request concurrency limit (200)
• Device management (list, kick, revoke-all panic button)
• Federation auth: SHA-256(secret || body) on every inter-server request

See docs/SECURITY.md for the full threat model.

Test Suite

155 tests across protocol + client crates (all passing):

• Protocol tests (X3DH, Double Ratchet, Sender Keys, crypto, identity, call signaling)
• TUI tests (rendering, keyboard input, scrolling, state management, call UI, markdown, receipts)

cargo test --workspace

WarzonePhone Integration

All 9 WZP-side integration tasks are complete:

• Shared identity (HKDF alignment, 15 cross-project tests)
• Relay auth (featherChat bearer token validation)
• Signaling bridge (CallSignal through E2E encrypted WS)
• Room access control (hashed room names, ACL)
• Mandatory crypto handshake on all paths

Documentation

Document	Content
ARCHITECTURE.md	Full system architecture with Mermaid diagrams
TASK_PLAN.md	Phase-by-phase task plan (FC-P1 through P6)
PROGRESS.md	Version history and feature timeline
PROTOCOL.md	Wire protocol specification
SECURITY.md	Threat model and security analysis
FUTURE_TASKS.md	Backlog with questions-before-starting

License

MIT