3efce2ddf4
Version: - Workspace + protocol: 0.0.21 → 0.0.22 - Web client VERSION: 0.0.17 → 0.0.22 - Service worker cache: wz-v2 → wz-v3 ETH identity: - Added WasmIdentity::eth_address() export (derives from seed via secp256k1) - Web client sends eth_address during key registration - Identity display shows ETH address first, then fingerprint - No more server-side resolve needed — computed client-side CLAUDE.md: - Added MANDATORY version bump rule (4 places to update) - Must bump on every functional change, never skip SW cache Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
89 lines
4.2 KiB
Markdown
89 lines
4.2 KiB
Markdown
# featherChat — Design Principles & Conventions
|
|
|
|
## MANDATORY: Version Bumping
|
|
|
|
**After every set of changes that modifies functionality, bump the version:**
|
|
1. `Cargo.toml` workspace version (e.g. `0.0.22` → `0.0.23`)
|
|
2. `crates/warzone-protocol/Cargo.toml` standalone version (same)
|
|
3. `crates/warzone-server/src/routes/web.rs` JS `VERSION` constant
|
|
4. `crates/warzone-server/src/routes/web.rs` service worker `CACHE` version (`wz-vN` → `wz-v(N+1)`)
|
|
|
|
Never commit functional changes without bumping all four. The service worker cache MUST be bumped or browsers will serve stale WASM.
|
|
|
|
## Architecture Principles
|
|
|
|
1. **Single seed, multiple identities** — Ed25519 (messaging), X25519 (encryption), secp256k1 (ETH address) all derived from one BIP39 seed via HKDF with domain-separated info strings.
|
|
|
|
2. **E2E by default** — All user messages are Double Ratchet encrypted. The server NEVER sees plaintext. Friend lists are client-side encrypted. Only bot messages are plaintext (v1).
|
|
|
|
3. **Server is semi-trusted** — Server sees metadata (who talks to whom, timing, groups) but cannot read message content. Design all features with this trust boundary in mind.
|
|
|
|
4. **Federation is transparent** — Users don't need to know which server their peer is on. Key lookup, alias resolution, and message delivery automatically proxy through federation.
|
|
|
|
5. **Telegram Bot API compatibility** — Bot API follows Telegram conventions (getUpdates, sendMessage, token-in-URL). Bot aliases must end with Bot/bot/_bot.
|
|
|
|
6. **Auth on writes, open reads** — All POST/write endpoints require bearer tokens. GET/read endpoints are public (needed for key exchange before auth is possible).
|
|
|
|
## Coding Conventions
|
|
|
|
### Rust
|
|
- Workspace crates: protocol (no I/O), server (axum), client (ratatui), wasm (wasm-bindgen), mule (future)
|
|
- Error handling: `AppResult<T>` in server, `anyhow::Result` in client, `ProtocolError` in protocol
|
|
- State: `AppState` with `Arc<Mutex<>>` for shared state, `Arc<Database>` for sled
|
|
- Auth: `AuthFingerprint` extractor as first handler param for protected routes
|
|
- Fingerprints: always normalize with `normfp()` (strip non-hex, lowercase)
|
|
- New routes: create `routes/<name>.rs`, add `pub fn routes() -> Router<AppState>`, merge in `routes/mod.rs`
|
|
|
|
### TUI
|
|
- 7 modules in `tui/`: types, draw, commands, input, file_transfer, network, mod
|
|
- All ChatLine must include `timestamp: Local::now()`
|
|
- Add new commands to both the handler chain AND `/help` text
|
|
- Self-messaging prevention: check `normfp(&peer) != normfp(&self.our_fp)`
|
|
|
|
### Web (WASM)
|
|
- JS embedded in `routes/web.rs` as Rust raw string — careful with escaping
|
|
- Service worker cache version must be bumped on WASM changes (`wz-vN`)
|
|
- `WasmSession::initiate()` stores X3DH result — `encrypt_key_exchange` must NOT re-initiate
|
|
|
|
### Federation
|
|
- Persistent WS between servers, NOT HTTP polling
|
|
- Presence re-pushed every 10s + on connect
|
|
- Key lookup: proxy to peer for non-local fingerprints (never cache remote bundles)
|
|
- Alias resolution: fall back to peer if not found locally
|
|
- Registration: check peer to enforce global uniqueness
|
|
|
|
### Bot API
|
|
- Token stored as `bot:<token>` in tokens tree
|
|
- Reverse lookup: `bot_fp:<fingerprint>` → token
|
|
- Alias auto-registered on bot creation with `_bot` suffix
|
|
- Reserved aliases: `*Bot`, `*bot`, `*_bot` blocked for non-bots
|
|
|
|
## Task Naming
|
|
|
|
`FC-P{phase}-T{task}[-S{subtask}]`
|
|
|
|
See `docs/TASK_PLAN.md` for the full breakdown.
|
|
|
|
## Testing
|
|
|
|
- Protocol: unit tests in each module's `#[cfg(test)]`
|
|
- TUI: unit tests for types, input, draw (using ratatui TestBackend)
|
|
- WASM: can't test natively (js-sys dependency) — test equivalent logic in protocol crate
|
|
- Server: no integration tests yet (planned)
|
|
|
|
## Key Files
|
|
|
|
| What | Where |
|
|
|------|-------|
|
|
| Wire format | `warzone-protocol/src/message.rs` |
|
|
| Crypto primitives | `warzone-protocol/src/crypto.rs` |
|
|
| Server state | `warzone-server/src/state.rs` |
|
|
| All routes | `warzone-server/src/routes/mod.rs` |
|
|
| Federation | `warzone-server/src/federation.rs` |
|
|
| TUI commands | `warzone-client/src/tui/commands.rs` |
|
|
| Web client | `warzone-server/src/routes/web.rs` |
|
|
| WASM bridge | `warzone-wasm/src/lib.rs` |
|
|
| Task plan | `docs/TASK_PLAN.md` |
|
|
| Bot API docs | `docs/BOT_API.md` |
|
|
| LLM help ref | `docs/LLM_HELP.md` |
|