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

feat: friend list, bot API, ETH addressing, deep links, docs overhaul

Browse Source 
Tier 1 — New features:
- E2E encrypted friend list: server stores opaque blob (POST/GET /v1/friends),
  protocol-level encrypt/decrypt with HKDF-derived key, 4 tests
- Telegram Bot API compatibility: /bot/register, /bot/:token/getUpdates,
  sendMessage, getMe — TG-style Update objects with proper message mapping
- ETH address resolution: GET /v1/resolve/:address (0x.../alias/@.../fp),
  bidirectional ETH↔fp mapping stored on key registration
- Seed recovery: /seed command in TUI + web client
- URL deep links: /message/@alias, /message/0xABC, /group/#ops
- Group members with online status in GET /groups/:name/members

Tier 2 — UX polish:
- TUI: /friend, /friend <addr>, /unfriend <addr> with presence checking
- Web: friend commands, showGroupMembers() on group join
- Web: ETH address in header, clickable addresses (click→peer or copy)
- Bot: full WireMessage→TG Update mapping (encrypted base64, CallSignal,
  FileHeader, bot_message JSON)

Documentation:
- USAGE.md rewritten: complete user guide with all commands
- SERVER.md rewritten: full admin guide with all 50+ endpoints
- CLIENT.md rewritten: architecture, commands, keyboard, storage
- LLM_HELP.md created: 1083-word token-optimized reference for helper LLM

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
2026-03-29 07:31:54 +04:00
parent dbf5d136cf
commit 7b72f7cba5
15 changed files with 2181 additions and 1023 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
warzone/docs/LLM_HELP.md Normal file
View File

@@ -0,0 +1,159 @@
# featherChat Help Reference
featherChat (codename: warzone) = E2E encrypted messenger. TUI client, web client (WASM), federated servers. Crypto: X3DH key exchange + Double Ratchet. Identity = Ed25519 keypair from 24-word seed.
## Commands
cmd | action | example
--- | --- | ---
/help, /? | show help | /help
/info | show your fp | /info
/eth | show ETH addr | /eth
/seed | show 24-word recovery mnemonic | /seed
/peer <addr>, /p | set DM peer | /peer abc123 or /peer @alice
/reply, /r | reply to last DM sender | /r
/dm | switch to DM mode (clear peer) | /dm
/contacts, /c | list contacts + msg counts | /c
/history, /h [fp] | show conversation history (50 msgs) | /h abc123
/alias <name> | register alias for yourself | /alias alice
/aliases | list all registered aliases | /aliases
/unalias | remove your alias | /unalias
/friend | list friends + online status | /friend
/friend <addr> | add friend | /friend @bob
/unfriend <addr> | remove friend | /unfriend @bob
/devices | list active device sessions | /devices
/kick <id> | kick a device session | /kick dev_abc
/g <name> | switch to group (auto-join) | /g ops
/gcreate <name> | create group | /gcreate ops
/gjoin <name> | join group | /gjoin ops
/glist | list all groups | /glist
/gleave | leave current group | /gleave
/gkick <fp> | kick member (creator only) | /gkick abc123
/gmembers | list group members + status | /gmembers
/file <path> | send file (max 10MB, 64KB chunks) | /file ./doc.pdf
/quit, /q | exit | /q
Navigation: PageUp/PageDown scroll msgs, Up/Down scroll by 1 (empty input), Ctrl+C or Esc quit.
## Addressing
Format | Example | Notes
--- | --- | ---
Fingerprint | abc123def456... | hex string, derived from Ed25519 pubkey
ETH address | 0x742d35Cc... | derived from same seed, checksum format
@alias | @alice | 1-32 alphanum chars, globally unique, 365d TTL
All 3 formats work in /peer. Aliases resolve to fp via server. One alias per user. Register with /alias, recover with recovery key.
## Quick Start
1. `warzone init` -- generates seed, saves identity.seed, prints 24-word mnemonic. WRITE IT DOWN.
2. `warzone register --server https://srv.example.com` -- uploads prekey bundle to srv
3. `warzone tui --server https://srv.example.com` -- opens TUI, connects WebSocket
4. `/peer @alice` or `/peer <fingerprint>` -- set recipient
5. Type msg, press Enter -- encrypted + sent
Recovery: `warzone recover` -- enter 24 words to restore identity on new device.
## Groups
- /gcreate <name> -- create, you become creator + first member
- /gjoin <name> -- join existing (or auto-join via /g <name>)
- type msg in group mode -- fan-out encrypted per-member (sender keys)
- /gleave -- leave current group
- /gmembers -- shows fp, alias, online status, creator flag
- /gkick <fp> -- creator only, removes member
Groups auto-create on join if they don't exist. Server fans out per-member encrypted msgs.
## Files
/file <path> -- sends to current peer/group. Max 10MB. Auto-chunked at 64KB. Includes filename, size, SHA-256 hash. Receiver auto-reassembles.
## Friends
- /friend -- list all friends with online/offline status
- /friend <addr> -- add (fp, ETH, or @alias)
- /unfriend <addr> -- remove
- Friend list stored encrypted on srv (only you can decrypt with your seed)
- Shows alias resolution + presence status
## Devices
- /devices -- list active WS connections (device_id, connected_at)
- /kick <device_id> -- revoke specific device
- Max 5 concurrent device sessions
- /devices/revoke-all API endpoint = panic button (kills all except current)
## Security
- Seed = 24-word BIP39 mnemonic = master key. Derives Ed25519 identity + ETH wallet.
- NEVER share seed. Only way to recover account.
- X3DH key exchange establishes sessions. Double Ratchet provides forward secrecy.
- All DMs E2E encrypted. Group msgs encrypted per-member.
- Server sees: metadata (who talks to whom, timestamps), encrypted blobs, presence.
- Server cannot read msg content.
- Pre-keys: signed pre-key + 10 one-time pre-keys uploaded on register.
- Bot API msgs are NOT E2E encrypted (plaintext JSON envelopes).
## Federation
- 2 servers connected via persistent WebSocket
- Config: JSON file with server_id, shared_secret, peer URL
- Messages auto-route across servers (srv checks remote presence)
- Aliases globally unique across federation
- @alias resolution checks local first, then federated peer
- Same client commands work regardless of which srv peer is on
- Auto-reconnects on connection failure
## Web Client
- Browser access at server root URL (/)
- WASM-compiled client, same crypto as TUI
- PWA: installable, offline-capable (service worker caches shell)
- Same E2E encryption as native client
- Deep links: navigate to specific peers/groups via URL
## Troubleshooting
Problem | Cause | Fix
--- | --- | ---
"peer not registered" | recipient hasn't run register yet | they need to `warzone register`
"session reset" | crypto session re-established | normal after key rotation or recovery, msgs continue
"connection lost" | WS disconnected | auto-reconnects, no action needed
"alias already taken" | someone else has it | pick different name or wait for 365d expiry + 30d grace
"not a member" | sending to group you left | /gjoin <name> first
"invalid token" | bot token expired or wrong | re-register bot
"file too large" | over 10MB | split file manually
no prekeys available | recipient's one-time prekeys exhausted | they need to re-register or come online
## Bot API
Telegram-compatible REST API. Base: /v1/
Endpoint | Method | Body | Returns
--- | --- | --- | ---
/bot/register | POST | {"name":"mybot","fingerprint":"abc..."} | {"token":"...","name":"..."}
/bot/:token/getMe | GET | -- | bot info
/bot/:token/getUpdates | POST | {"timeout":5} | array of Update objects
/bot/:token/sendMessage | POST | {"chat_id":"<fp>","text":"hello"} | msg confirmation
- Token format: fp_prefix:random_hex
- getUpdates: long-poll (max 5s), returns then deletes queued msgs
- sendMessage: plaintext JSON, NOT E2E encrypted
- Updates include: messages, key exchanges, call signals, file headers
- Bot msgs delivered via same routing (WS push or DB queue)
## Server API (other endpoints)
- POST /v1/register -- upload prekey bundle
- GET /v1/keys/:fp -- fetch prekeys for peer
- POST /v1/send -- send encrypted msg
- GET /v1/receive/:fp -- poll msgs (WS preferred)
- WS /v1/ws?fp=<fp>&token=<tok> -- real-time connection
- GET /v1/presence/:fp -- check online status
- GET/POST /v1/friends -- encrypted friend list
- GET /v1/devices -- list sessions
- POST /v1/devices/:id/kick -- kick device
- Alias routes under /v1/alias/*
- Group routes under /v1/groups/*