docs: comprehensive update all docs to v0.0.46
11 files updated to reflect current state (v0.0.22 → v0.0.46): ARCHITECTURE.md: - Ring tones, group calls, read receipts, markdown rendering sections - Bot API expanded (BotFather, numeric IDs, Telegram compat) - Admin commands, known issues, 155 tests TASK_PLAN.md: - All P1-P4 marked DONE with version numbers - Additional completed work section (bots, ETH, ring tones, group calls) - New FC-P7 (Voice & Transport): cpal, Sender Keys, WebTransport - FC-P6-T9/T10 added PROGRESS.md: - Full version history table v0.0.22 through v0.0.46 - Known issues section README.md: - Voice calls, ring tones, group calls, read receipts, markdown, 155 tests SECURITY.md: - Bot API security, voice call security, admin commands sections - Updated protection tables USAGE.md: - Group calls, read receipts, markdown formatting, admin commands CLIENT.md: - Call commands, read receipts, markdown rendering LLM_HELP.md + LLM_BOT_DEV.md: - Call/group call/admin commands, ring tones, per-bot numeric IDs TESTING_E2E.md: - Tests 16-18: ring tones, group calls, admin commands CLAUDE.md: - Ring tone notes, group signal endpoint, MLS roadmap Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
@@ -1,7 +1,9 @@
|
||||
# Warzone Messenger (featherChat) — Architecture
|
||||
|
||||
**Version:** 0.0.21
|
||||
**Status:** Phase 1 + Phase 2 + WZP Integration + Federation
|
||||
**Version:** 0.0.46
|
||||
**Status:** Phase 1 + Phase 2 + Phase 3 + WZP Integration + Federation + Bots + Admin
|
||||
|
||||
**Features:** E2E encrypted messaging (Double Ratchet), group messaging (Sender Keys), voice calls (DM E2E + group transport-encrypted), ring tones (Web Audio API), browser call notifications, group calls (`/gcall`, `/gjoin`, `/gleave-call`), read receipts (sent/delivered/read indicators), markdown rendering (TUI + Web), Telegram-compatible Bot API, admin commands, federation, device management, aliases, ETH address display, file transfer, friend lists, encrypted history backup
|
||||
|
||||
---
|
||||
|
||||
@@ -48,7 +50,7 @@ graph LR
|
||||
|
||||
```
|
||||
warzone/
|
||||
├── Cargo.toml # Workspace root (v0.0.21)
|
||||
├── Cargo.toml # Workspace root (v0.0.46)
|
||||
├── federation.example.json # Federation config template
|
||||
├── crates/
|
||||
│ ├── warzone-protocol/ # Core crypto & message types
|
||||
@@ -227,6 +229,7 @@ Auth-Protected (bearer token required):
|
||||
POST /v1/keys/register|replenish
|
||||
POST /v1/calls/initiate|:id/end
|
||||
POST /v1/groups/:name/call Group call initiation
|
||||
POST /v1/groups/:name/signal Group call signal broadcast
|
||||
POST /v1/devices/:id/kick Kick a device
|
||||
POST /v1/devices/revoke-all Panic button
|
||||
POST /v1/presence/batch Bulk online check
|
||||
@@ -428,9 +431,23 @@ sequenceDiagram
|
||||
| `GET /v1/calls/active` | List active calls |
|
||||
| `POST /v1/calls/missed` | Get & clear missed calls |
|
||||
| `POST /v1/groups/:name/call` | Group call (fan-out to members) |
|
||||
| `POST /v1/groups/:name/signal` | Broadcast call signal to group members |
|
||||
| `GET /v1/presence/:fp` | Check if peer is online |
|
||||
| `GET /v1/wzp/relay-config` | Get relay address + service token |
|
||||
|
||||
### Ring Tones
|
||||
|
||||
- **Incoming call:** Web Audio API oscillator playing a 440/480 Hz dual-tone pattern (classic North American ring cadence)
|
||||
- **Outgoing ringback:** 2 seconds on / 4 seconds off pattern until callee answers or rejects
|
||||
- **Browser notifications:** If the web client tab is in background, an incoming call triggers a system notification so the user does not miss it
|
||||
|
||||
### Group Calls
|
||||
|
||||
- `/gcall <group>` starts a group call room; `/gjoin <group>` joins an existing room; `/gleave-call` leaves
|
||||
- Group call signals are broadcast via `POST /v1/groups/:name/signal` (fan-out to all online members)
|
||||
- Room naming convention: DM calls use a sorted fingerprint pair as room ID; group calls use `gc-<groupname>`
|
||||
- **Encryption:** Group calls are transport-encrypted only (QUIC with TLS). They are NOT end-to-end encrypted. MLS (RFC 9420) key agreement for group call media is on the roadmap.
|
||||
|
||||
### Group Call Room ID
|
||||
|
||||
```
|
||||
@@ -482,12 +499,13 @@ sequenceDiagram
|
||||
S->>U: Deliver reply via WS
|
||||
```
|
||||
|
||||
- Bots register with a fingerprint and get a token
|
||||
- Bot aliases must end with `Bot`, `bot`, or `_bot` (enforced)
|
||||
- Non-bot users cannot register reserved aliases
|
||||
- `getUpdates` returns Telegram-compatible Update objects
|
||||
- `sendMessage` delivers plaintext (no E2E in v1)
|
||||
- **BotFather** creates bots and issues tokens; each bot gets an auto-registered alias
|
||||
- Bot aliases must end with `Bot`, `bot`, or `_bot` (enforced); non-bot users cannot register reserved aliases
|
||||
- **Per-bot numeric ID mapping:** Each user is assigned a unique numeric ID per bot, preventing cross-bot user correlation (privacy)
|
||||
- **Telegram-compatible endpoints:** `getUpdates` (long-poll), `sendMessage`, `editMessage`, `sendDocument`, inline keyboards
|
||||
- `sendMessage` delivers plaintext (no E2E in v1 — bot messages are not encrypted)
|
||||
- Messages from users arrive as encrypted blobs (base64) or plaintext bot messages
|
||||
- **System bots:** Configured via `--bots-config <file>` on server startup; auto-created on first run
|
||||
|
||||
### Addressing
|
||||
|
||||
@@ -519,6 +537,8 @@ ETH↔fingerprint mapping stored on key registration.
|
||||
| Inter-server | Authenticated | SHA-256(secret \|\| body) token |
|
||||
| WS connections | Rate-limited | 5 per fingerprint, 200 global |
|
||||
| WZP relay | Token-gated | featherChat bearer token validation |
|
||||
| DM calls (voice) | E2E encrypted | ChaCha20-Poly1305 over QUIC via WZP relay |
|
||||
| Group calls (voice) | Transport-encrypted only | QUIC/TLS — NOT E2E (MLS on roadmap) |
|
||||
|
||||
### What's NOT Protected (Phase 1 scope)
|
||||
|
||||
@@ -587,11 +607,14 @@ graph TB
|
||||
|
||||
| Crate | Tests | Coverage |
|
||||
|-------|------:|---------|
|
||||
| warzone-protocol | 34 | X3DH, Double Ratchet, Sender Keys, AEAD, HKDF, identity, ethereum, prekeys, mnemonic, friend list, x3dh web client |
|
||||
| warzone-protocol | 39 | X3DH, Double Ratchet, Sender Keys, AEAD, HKDF, identity, ethereum, prekeys, mnemonic, friend list, x3dh web client, receipts |
|
||||
| warzone-client (types) | 10 | App init, scroll, connected, timestamps, normfp |
|
||||
| warzone-client (input) | 25 | Text editing, cursor movement, scroll keys, quit |
|
||||
| warzone-client (draw) | 9 | Rendering, timestamps, connection dot, scroll, unread badge |
|
||||
| **Total** | **122** | All passing |
|
||||
| warzone-client (draw) | 13 | Rendering, timestamps, connection dot, scroll, unread badge, markdown |
|
||||
| warzone-server (integration) | 10 | Route handlers, auth middleware, group ops, call state |
|
||||
| warzone-server (bin) | 10 | CLI args, startup, federation init, bot config |
|
||||
| Other (e2e, misc) | 48 | Client-side E2E flows, file transfer, admin commands |
|
||||
| **Total** | **155** | All passing |
|
||||
|
||||
WZP side: 15 cross-project identity tests + 17 integration tests (separate repo).
|
||||
|
||||
@@ -667,6 +690,46 @@ sequenceDiagram
|
||||
|
||||
---
|
||||
|
||||
## Admin Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/admin-calls` | List all currently active calls on the server |
|
||||
| `/admin-unalias <alias> <pw>` | Force-remove an alias (requires admin password) |
|
||||
| `/admin-help` | Show available admin commands |
|
||||
|
||||
Admin commands are available in the TUI client and are authenticated server-side.
|
||||
|
||||
---
|
||||
|
||||
## Read Receipts
|
||||
|
||||
- **TUI:** Tracks which messages are visible in the viewport and sends `Receipt::Read` back to the sender when a message scrolls into view
|
||||
- **Web:** Sender sees delivery indicators: single check mark (sent) then double check mark (delivered) then blue double check mark (read)
|
||||
- **Deduplication:** Each message is receipted only once; the client tracks which message IDs have already been acknowledged to avoid redundant receipt traffic
|
||||
|
||||
---
|
||||
|
||||
## Markdown Rendering
|
||||
|
||||
- **TUI:** Custom `md_to_spans` parser converts markdown to ratatui `Span` objects supporting bold, italic, inline code, headers, blockquotes, and lists
|
||||
- **Web:** `renderMd()` function in the embedded JS handles code blocks, inline code, bold, italic, headers, links, blockquotes, and ordered/unordered lists
|
||||
- Both renderers are deliberately simple (no AST) to avoid pulling in heavy markdown dependencies
|
||||
|
||||
---
|
||||
|
||||
## Known Issues and Limitations
|
||||
|
||||
| Issue | Details |
|
||||
|-------|---------|
|
||||
| Group call signal delivery | Depends on members being online; there is no offline queue for call signals |
|
||||
| TUI voice calls | Require the web client; no native audio (cpal) integration yet |
|
||||
| Bot messages are plaintext | v1 limitation; bots cannot participate in E2E encryption |
|
||||
| `/gmembers` ETH resolution | Async resolution may briefly show the raw fingerprint before the ETH address loads |
|
||||
| Service worker cache staleness | Cache version in `web.rs` must be bumped on every change or browsers will serve stale WASM/JS content |
|
||||
|
||||
---
|
||||
|
||||
## Extensibility
|
||||
|
||||
### Adding New WireMessage Variants
|
||||
|
||||
Reference in New Issue
Block a user