featherChat/warzone/docs/USAGE.md

# featherChat Usage Guide

**Version:** 0.0.46

---

## Installation

### Build from Source

Requirements: Rust 1.75+, cargo

```bash
git clone <repo-url>
cd warzone

cargo build --release

# Binaries output to target/release/:
#   warzone-server   — relay server (with embedded web client)
#   warzone-client   — CLI / TUI client
```

### WASM Build (Web Client)

Requirements: wasm-pack

```bash
cd crates/warzone-wasm
wasm-pack build --target web
# Output in pkg/ — copy to the web client directory
```

### Linux Cross-Compile

The `scripts/build-linux.sh` script builds Linux x86_64 binaries on a Hetzner Cloud VPS.

```bash
# Full pipeline: create VM, build, download binaries
./scripts/build-linux.sh --all

# Or step by step:
./scripts/build-linux.sh --prepare    # Create VM, install deps, upload source
./scripts/build-linux.sh --build      # Build release binaries on the VM
./scripts/build-linux.sh --transfer   # Download binaries to target/linux-x86_64/
./scripts/build-linux.sh --destroy    # Delete the VM

# One-command ship to all production servers:
./scripts/build-linux.sh --ship       # prepare + build + transfer + deploy + destroy
```

### Server Configuration

```bash
warzone-server --bind 0.0.0.0:7700 --data-dir ./warzone-data
```

| Flag            | Default          | Description                          |
|-----------------|------------------|--------------------------------------|
| `--bind`        | `0.0.0.0:7700`  | Listen address                       |
| `--data-dir`    | `./warzone-data` | sled database path                   |
| `--enable-bots` | *(off)*          | Enable Bot API and BotFather         |

Environment variables:

| Variable                 | Default | Description                  |
|--------------------------|---------|------------------------------|
| `WARZONE_ADMIN_PASSWORD` | `admin` | Password for admin alias ops |
| `RUST_LOG`               | `info`  | Log level filter             |

---

## Identity

### Generate a New Identity

```bash
warzone-client init
# Prompts for passphrase
# Displays fingerprint + 24-word BIP39 mnemonic
# SAVE THE MNEMONIC — it is the only way to recover your identity
```

The seed is stored at `~/.warzone/identity.seed`, encrypted with Argon2id + ChaCha20-Poly1305.

### Recover from Mnemonic

```bash
warzone-client recover abandon ability able about above absent absorb abstract ...
# Prompts for passphrase, restores the same identity
```

### View Your Identity

```bash
warzone-client info
# Fingerprint: a3f8:c912:44be:7d01:9e5a:3b2c:7f80:12d4
```

In the TUI, use `/info` to display your fingerprint, `/seed` to display your 24-word recovery mnemonic, and `/eth` to display your Ethereum address.

### Ethereum Address

Your ETH address is derived from the same seed via domain-separated HKDF. One seed, dual identity.

```bash
warzone-client eth
# Fingerprint: a3f8:c912:44be:7d01:9e5a:3b2c:7f80:12d4
# Ethereum:    0x71C7656EC7ab88b098defB751B7401B5f6d8976F
```

### Addressing

featherChat supports three addressing modes. All three work anywhere a peer address is accepted:

| Format | Example | Description |
|--------|---------|-------------|
| Fingerprint | `a3f8:c912:44be:7d01:9e5a:3b2c:7f80:12d4` | SHA-256 of Ed25519 pubkey, 8 groups of 4 hex digits |
| Alias | `@alice` | Human-readable, server-resolved |
| ETH address | `0x71C7...976F` | Ethereum address derived from the same seed |

---

## TUI Client

Launch the interactive terminal UI:

```bash
warzone-client chat --server http://your-server:7700
warzone-client chat @alice --server http://your-server:7700
warzone-client chat a3f8:c912:... --server http://your-server:7700
```

### Complete Command Reference

#### Peer and Navigation

| Command | Description |
|---------|-------------|
| `/peer <fingerprint>` | Set DM peer by fingerprint |
| `/p @alias` | Set DM peer by alias (short form of `/peer`) |
| `/peer 0x...` | Set DM peer by ETH address |
| `/r [message]` | Reply to last DM sender; optionally include an inline message |
| `/dm` | Switch to DM mode (clear group context) |

```
/peer a3f8:c912:44be:7d01:9e5a:3b2c:7f80:12d4
/p @alice
/peer 0x71C7656EC7ab88b098defB751B7401B5f6d8976F
/r
/r hey, got your message
/dm
```

#### Groups

| Command | Description |
|---------|-------------|
| `/g <name>` | Switch to group (auto-joins if not a member) |
| `/gcreate <name>` | Create a new group (you become creator) |
| `/gjoin <name>` | Join an existing group |
| `/gleave` | Leave the current group |
| `/gkick <fp_or_alias>` | Kick a member (creator only) |
| `/gmembers` | List members of the current group with online status |
| `/glist` | List all groups on the server |

```
/gcreate ops-team
/g ops-team
/gmembers
/gkick @mallory
/gleave
/glist
```

When in a group, the header bar shows `#groupname` and all messages are sent to that group.

#### Alias Management

| Command | Description |
|---------|-------------|
| `/alias <name>` | Register an alias for your fingerprint |
| `/aliases` | List all registered aliases |
| `/unalias` | Remove your alias |

Alias rules: 1-32 alphanumeric characters (plus `_` and `-`), case-insensitive, normalized to lowercase. TTL is 365 days of inactivity, with a 30-day grace period. Registration returns a recovery key — save it.

#### File Transfer

| Command | Description |
|---------|-------------|
| `/file <path>` | Send a file to the current peer or group |

```
/file /path/to/document.pdf
/file ./photo.jpg
```

Files are split into 64 KB chunks, each encrypted with the Double Ratchet session key. The recipient reassembles and verifies a SHA-256 hash over the complete file. Maximum file size is 10 MB. Received files are saved to the current directory.

#### Contacts and History

| Command | Description |
|---------|-------------|
| `/contacts` or `/c` | List all contacts with message counts |
| `/history` or `/h` | Show message history for current peer (last 50) |
| `/history <fp>` | Show history for a specific peer |

#### Identity and Security

| Command | Description |
|---------|-------------|
| `/info` | Show your fingerprint |
| `/eth` | Show your Ethereum address |
| `/seed` | Show your 24-word recovery mnemonic |
| `/devices` | List your active device sessions |
| `/kick <device_id>` | Revoke a specific device session |

#### Friend List

| Command | Description |
|---------|-------------|
| `/friend` | List friends with online/offline status |
| `/friend <address>` | Add a friend by fingerprint or alias |
| `/unfriend <address>` | Remove a friend |

The friend list is end-to-end encrypted and stored on the server as an opaque blob. The server cannot read it. Presence status (online/offline) is shown next to each friend.

#### General

| Command | Description |
|---------|-------------|
| `/help` or `/?` | Show command list |
| `/quit` or `/q` | Exit the TUI |

### Keyboard Navigation

| Key | Action |
|-----|--------|
| PageUp / PageDown | Scroll messages by 10 |
| Up / Down (when input is empty) | Scroll messages by 1 |
| Ctrl+End | Snap scroll to bottom |
| Left / Right | Move cursor in input |
| Home / Ctrl-A | Beginning of line |
| End / Ctrl-E | End of line |
| Ctrl-U | Clear input |
| Ctrl-W | Delete word before cursor |
| Ctrl-C | Quit |

### Receipt Indicators

| Indicator | Meaning |
|-----------|---------|
| Single tick | Sent (no confirmation yet) |
| Double tick (gray) | Delivered (decrypted by recipient) |
| Double tick (blue) | Read (viewed by recipient) |

---

## Web Client

### Access

Navigate to the server URL in a browser (e.g., `http://your-server:7700`). The web client generates a new identity automatically on first visit. Your seed is stored in `localStorage` — back it up using `/seed`.

The web client uses the same E2E encryption as the TUI, compiled to WASM.

### URL Deep Links

The web client supports deep links for direct navigation:

| URL | Effect |
|-----|--------|
| `/message/@alice` | Opens a DM with the alias `@alice` |
| `/message/0xABC...` | Opens a DM with an ETH address |
| `/group/#ops` | Opens the group `#ops` |

Share these links to let someone jump straight into a conversation.

### Clickable Addresses

Fingerprints and addresses displayed in messages are clickable. Clicking an address sets it as your DM peer. If you are currently typing, clicking copies the address instead.

### Supported Commands

The web client supports the same slash commands as the TUI: `/peer`, `/p`, `/r`, `/dm`, `/g`, `/gcreate`, `/gjoin`, `/gleave`, `/gkick`, `/gmembers`, `/glist`, `/alias`, `/aliases`, `/unalias`, `/file`, `/contacts`, `/c`, `/history`, `/h`, `/info`, `/eth`, `/seed`, `/friend`, `/unfriend`, `/devices`, `/kick`, `/help`, `/quit`.

---

## Voice Calls

### Web Client
1. Set a peer (paste ETH address or use `/peer @alias`)
2. Click the Call button or type `/call`
3. Peer sees "Incoming call" and clicks Accept
4. Both allow microphone access
5. Audio flows -- speak normally
6. Click "End Call" or type `/hangup` to end

### TUI Client
1. `/call <peer_address>` -- initiate call
2. Peer sees notification and can use `/accept` or `/reject`
3. Audio currently requires web client (TUI shows hint)
4. `/hangup` -- end call

### Commands
| Command | Description |
|---------|-------------|
| `/call` | Start voice call with current peer |
| `/accept` | Accept incoming call |
| `/reject` | Reject incoming call |
| `/hangup` | End current call |

### Group Calls

Group calls allow multi-party audio within a group context. Any group member can initiate a call, and others can join at any time.

| Command | Description |
|---------|-------------|
| `/gcall` | Start a group call in the current group |
| `/gjoin` | Join an active group call |
| `/gleave-call` | Leave the group call (call continues for others) |
| `/gmute` | Toggle your microphone mute in the group call |

Group call audio is routed through the WZP QUIC SFU relay. Media is transport-encrypted (QUIC TLS) but not E2E encrypted -- the relay can observe audio streams. MLS-based E2E encryption for group calls is planned.

---

## Read Receipts

featherChat tracks message delivery and read status with three indicators:

| Indicator | Symbol | Meaning |
|-----------|--------|---------|
| Sent | Single gray tick | Message sent to server, no confirmation yet |
| Delivered | Double gray tick | Recipient decrypted the message |
| Read | Double blue tick | Recipient viewed the message in their viewport |

Read receipts are sent automatically when messages enter the visible area of the chat window. The system uses the sender's fingerprint for tracking and a dedup set to avoid sending duplicate read receipts for the same message.

---

## Markdown Formatting

Messages support markdown formatting in both the TUI and web client:

| Syntax | Result |
|--------|--------|
| `**bold**` | **bold** |
| `*italic*` | *italic* |
| `` `code` `` | `inline code` |
| `# Header` | Header (at start of line) |
| `> quote` | Block quote (at start of line) |
| `- item` | List item (at start of line) |

Markdown is rendered inline in messages. In the TUI, bold, italic, and code spans use terminal attributes. In the web client, they render as HTML.

---

## Admin Commands

Server administration commands for operators:

| Command | Description |
|---------|-------------|
| `/admin-calls` | List all active calls on the server |
| `/admin-unalias <alias>` | Remove any user's alias (requires admin password) |

`/admin-unalias` prompts for the server's admin password (set via `WARZONE_ADMIN_PASSWORD` environment variable). `/admin-calls` currently has no auth protection -- an admin role system is planned.

---

## Groups

### Creating and Using Groups

```
/gcreate ops-team      # Create (you become creator)
/g ops-team            # Switch to group (auto-joins if needed)
/gjoin ops-team        # Explicitly join an existing group
```

Once in a group, all messages you type go to that group. The server fans out to all members.

### Membership

- `/gmembers` shows all members with aliases and online status.
- The creator can kick members with `/gkick <fingerprint_or_alias>`.
- Any member can leave with `/gleave`.

### Sender Keys

The protocol uses Sender Keys for efficient group encryption. Each member generates a random 32-byte chain key, distributes it to all other members over 1:1 encrypted channels, and encrypts group messages with their sender key. This gives O(1) encryption cost per message instead of O(N). Sender keys are rotated on member join or leave.

---

## File Transfer

Files are transferred end-to-end encrypted through the relay server.

1. The sender reads the file and splits it into 64 KB chunks.
2. A `FileHeader` message is sent with the filename, total size, chunk count, and SHA-256 hash.
3. Each `FileChunk` is encrypted with the Double Ratchet session and sent sequentially.
4. The recipient reassembles all chunks and verifies the SHA-256 hash.
5. The completed file is saved to the current directory.

Maximum file size: **10 MB**. Chunk size: **64 KB**.

---

## Friend List

The friend list provides presence tracking for contacts you care about.

- `/friend <address>` adds a friend (by fingerprint or alias).
- `/friend` lists all friends with their current online/offline status.
- `/unfriend <address>` removes a friend.

The friend list is encrypted client-side and stored on the server as an opaque blob. The server relays it but cannot read its contents.

---

## Bots

### Messaging Bots

Clients auto-detect bot aliases (names ending in `Bot`, `bot`, or `_bot`) and send messages as plaintext -- no E2E session is established. Simply use `/peer @mybot_bot` and type your message. The client handles the rest.

### Creating Bots with BotFather

To create a bot, message `@botfather`:

1. `/peer @botfather`
2. Send a message requesting a new bot (e.g., "create WeatherBot")
3. BotFather registers the bot and returns the API token
4. Use the token to run your bot against the server's Bot API

BotFather is auto-created on servers that have `--enable-bots` enabled. It is the only way to create bots.

### Bot Bridge for Telegram Compatibility

The `tools/bot-bridge.py` script provides a compatibility layer that lets you use existing Telegram bot libraries (python-telegram-bot, aiogram, Telegraf) with featherChat. It translates between the two APIs, handling differences like fingerprint-based addressing and numeric ID translation.

```bash
python tools/bot-bridge.py --token YOUR_BOT_TOKEN --server http://localhost:7700
```

See `docs/BOT_API.md` and `docs/LLM_BOT_DEV.md` for full Bot API documentation.

---

## Federation

Federation connects two featherChat servers so that users on different servers can message each other transparently.

### Setup

Each server needs a federation config file:

```json
{
  "server_id": "alpha",
  "shared_secret": "long-random-string-shared-between-both-servers",
  "peer": {
    "id": "bravo",
    "url": "http://10.0.0.2:7700"
  },
  "presence_interval_secs": 5
}
```

Start the server with federation enabled:

```bash
warzone-server --bind 0.0.0.0:7700 --federation federation.json
```

### How It Works

The two servers maintain a persistent WebSocket connection between them. When a client on server Alpha sends a message to a fingerprint registered on server Bravo, server Alpha forwards the message over the federation link. The recipient's server delivers it via their normal WebSocket connection. Presence information is exchanged on a configurable interval.

From the user's perspective, federation is transparent. You address peers the same way regardless of which server they are on.

---

## Multi-Device

### Setup

1. On the new device, recover from mnemonic: `warzone-client recover <24 words>`
2. Register with the server: `warzone-client register --server http://...`
3. Both devices share the same fingerprint and receive messages.

### Device Management

- `/devices` lists all active sessions for your identity.
- `/kick <device_id>` revokes a specific device session.

Ratchet sessions are per-device and not synchronized between devices. Use encrypted backup/restore (`warzone-client backup` / `warzone-client restore`) to transfer session state.

---

## Encrypted Backup and Restore

```bash
# Export sessions and pre-keys, encrypted with your seed
warzone-client backup my-backup.wzb

# Restore on another device (requires same seed)
warzone-client restore my-backup.wzb
```

The backup contains all Double Ratchet sessions and pre-key secrets. It is encrypted with HKDF(seed, info="warzone-history") + ChaCha20-Poly1305.