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 <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.

Bot alias reservation: names ending in Bot, bot, or _bot are reserved for the Bot API. Non-bot users cannot register these aliases.

## 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)

### BotFather

`@botfather` is the only way to create bots. It is auto-created on first server start (token printed in server logs). Users message `@botfather` to register new bots. The server must be started with `--enable-bots` to activate bot functionality.

### Registration

Bots are created via BotFather, which calls POST /v1/bot/register with a `botfather_token` field. Each bot has an `owner` field linking it to the user who requested creation.

Bot aliases must end with Bot, bot, or _bot. Non-bots cannot use these.

### Plaintext Bot Messaging

Clients auto-detect bot aliases (names ending in Bot/bot/_bot) and send messages unencrypted (plaintext JSON). No E2E session is established for standard bot interactions.

### E2E Bot Option

Bots can optionally participate in E2E encryption by registering with a seed and prekey bundle. Pass `e2e: true` + `bundle` + `eth_address` in the registration request. Users messaging an E2E bot establish a normal X3DH session.

### Bot Bridge

`tools/bot-bridge.py` provides Telegram library compatibility. It translates between featherChat Bot API and standard TG bot libraries (python-telegram-bot, aiogram, Telegraf).

### Endpoints

|Endpoint|Method|Body|
|---|---|---|
|/bot/:token/getMe|GET|--|
|/bot/:token/getUpdates|POST|{"timeout":50}|
|/bot/:token/sendMessage|POST|{"chat_id":"<fp_or_numeric>","text":"Hello","parse_mode":"HTML"}|
|/bot/:token/setWebhook|POST|{"url":"https://..."}|
|/bot/:token/deleteWebhook|POST|--|
|/bot/:token/getWebhookInfo|GET|--|

- Token format: fp_prefix:random_hex
- getUpdates: long-poll (max 50s), returns then deletes queued msgs
- sendMessage: plaintext JSON, NOT E2E encrypted (unless E2E bot)
- Bot msgs delivered via same routing (WS push or DB queue)
- Webhooks: updates are delivered live to the registered URL (POST with JSON body)
- chat_id: accepts hex fingerprint or numeric ID (TG compatibility)
- parse_mode: `HTML` renders basic HTML tags (<b>, <i>, <code>, <a>) in clients
- from.id is numeric (integer), from.id_str contains the hex fingerprint

Update types in getUpdates:
- Encrypted msg: text=null, raw_encrypted=base64
- Bot msg (plaintext): text="actual text", from.is_bot=true
- Call signal: text="/call_Offer", call_signal={type,payload}
- File: document={file_name,file_size}

Echo bot (Python):
```python
import requests, time
TOKEN = "your_token"
API = f"http://srv:7700/v1/bot/{TOKEN}"
while True:
    for u in requests.post(f"{API}/getUpdates",json={"timeout":50}).json().get("result",[]):
        m = u["message"]
        if m.get("text"): requests.post(f"{API}/sendMessage",json={"chat_id":m["chat"]["id"],"text":"Echo: "+m["text"]})
    time.sleep(1)
```

## 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/*