featherChat/warzone/docs/LLM_HELP.md

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 , /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	register alias for yourself	/alias alice
/aliases	list all registered aliases	/aliases
/unalias	remove your alias	/unalias
/friend	list friends + online status	/friend
/friend	add friend	/friend @bob
/unfriend	remove friend	/unfriend @bob
/devices	list active device sessions	/devices
/kick	kick a device session	/kick dev_abc
/g	switch to group (auto-join)	/g ops
/gcreate	create group	/gcreate ops
/gjoin	join group	/gjoin ops
/glist	list all groups	/glist
/gleave	leave current group	/gleave
/gkick	kick member (creator only)	/gkick abc123
/gmembers	list group members + status	/gmembers
/file	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 -- create, you become creator + first member
• /gjoin -- join existing (or auto-join via /g )
• 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 -- creator only, removes member

Groups auto-create on join if they don't exist. Server fans out per-member encrypted msgs.

Files

/file -- 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 -- add (fp, ETH, or @alias)
• /unfriend -- 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 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":"","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=&token= -- 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/*