featherChat/warzone/docs/USAGE.md

# featherChat Usage Guide

**Version:** 0.0.21

---

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

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

---

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

---

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