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](docs/ARCHITECTURE.md) for full architecture with Mermaid diagrams.

## Quick Start

### Build

```bash
cd warzone
cargo build --release
```

### Generate Identity

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

### Start Server

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

### Start TUI

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

### WZP Setup (Voice Calls)

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

```bash
# 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`:
```json
{
  "server_id": "alpha",
  "shared_secret": "your-shared-secret",
  "peer": { "id": "bravo", "url": "http://server-b:7700" },
  "presence_interval_secs": 5
}
```

```bash
# 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](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)

```bash
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](docs/ARCHITECTURE.md) | Full system architecture with Mermaid diagrams |
| [TASK_PLAN.md](docs/TASK_PLAN.md) | Phase-by-phase task plan (FC-P1 through P6) |
| [PROGRESS.md](docs/PROGRESS.md) | Version history and feature timeline |
| [PROTOCOL.md](docs/PROTOCOL.md) | Wire protocol specification |
| [SECURITY.md](docs/SECURITY.md) | Threat model and security analysis |
| [FUTURE_TASKS.md](docs/FUTURE_TASKS.md) | Backlog with questions-before-starting |

## License

MIT