chore: rename quicproquo → quicprochat in Rust workspace

Rename all crate directories, package names, binary names, proto
package/module paths, ALPN strings, env var prefixes, config filenames,
mDNS service names, and plugin ABI symbols from quicproquo/qpq to
quicprochat/qpc.

crates/quicprochat-client/Cargo.toml

@@ -0,0 +1,103 @@
+[package]
+name        = "quicprochat-client"
+version     = "0.1.0"
+edition.workspace     = true
+description = "CLI client for quicprochat."
+license     = "Apache-2.0 OR MIT"
+repository.workspace  = true
+
+[[bin]]
+name = "qpc"
+path = "src/main.rs"
+
+[dependencies]
+quicprochat-core  = { path = "../quicprochat-core" }
+quicprochat-proto = { path = "../quicprochat-proto" }
+quicprochat-kt    = { path = "../quicprochat-kt" }
+openmls_rust_crypto = { workspace = true }
+
+# Serialisation + RPC
+capnp         = { workspace = true }
+capnp-rpc     = { workspace = true }
+
+# Async
+tokio         = { workspace = true }
+tokio-util    = { workspace = true }
+futures       = { workspace = true }
+serde         = { workspace = true }
+serde_json    = { workspace = true }
+bincode       = { workspace = true }
+
+# Crypto — OPAQUE PAKE
+opaque-ke     = { workspace = true }
+rand          = { workspace = true }
+
+# Error handling
+anyhow        = { workspace = true }
+thiserror     = { workspace = true }
+
+# Crypto — for fingerprint verification in fetch-key subcommand
+sha2          = { workspace = true }
+argon2        = { workspace = true }
+chacha20poly1305 = { workspace = true }
+ciborium      = { workspace = true }
+zeroize       = { workspace = true }
+quinn         = { workspace = true }
+quinn-proto   = { workspace = true }
+rustls        = { workspace = true }
+
+# Logging
+tracing       = { workspace = true }
+tracing-subscriber = { workspace = true }
+
+# CLI
+clap          = { workspace = true }
+
+# Local message/conversation storage
+rusqlite      = { workspace = true }
+
+# Hex encoding/decoding
+hex           = { workspace = true }
+
+# Secure password prompting (no echo)
+rpassword     = "5"
+
+# mDNS discovery for mesh mode (Freifunk). Only compiled with --features mesh.
+mdns-sd = { version = "0.12", optional = true }
+
+# Optional P2P transport for direct node-to-node messaging.
+quicprochat-p2p = { path = "../quicprochat-p2p", optional = true }
+
+# Optional TUI dependencies (Ratatui full-screen interface).
+ratatui = { version = "0.29", optional = true, default-features = false, features = ["crossterm"] }
+crossterm = { version = "0.28", optional = true }
+
+# YAML playbook parsing (only compiled with --features playbook).
+serde_yaml = { version = "0.9", optional = true }
+
+# v2 SDK-based CLI (thin shell over quicprochat-sdk).
+quicprochat-sdk = { path = "../quicprochat-sdk", optional = true }
+quicprochat-rpc = { path = "../quicprochat-rpc", optional = true }
+rustyline      = { workspace = true, optional = true }
+
+[lints]
+workspace = true
+
+[features]
+# Enable mesh-mode features: mDNS local peer discovery + P2P transport.
+# Build: cargo build -p quicprochat-client --features mesh
+mesh = ["dep:mdns-sd", "dep:quicprochat-p2p"]
+# Enable full-screen Ratatui TUI: cargo build -p quicprochat-client --features tui
+tui = ["dep:ratatui", "dep:crossterm"]
+# Enable playbook (scripted command execution): YAML parser + serde derives.
+# Build: cargo build -p quicprochat-client --features playbook
+playbook = ["dep:serde_yaml"]
+# v2 CLI over SDK: cargo build -p quicprochat-client --features v2
+v2 = ["dep:quicprochat-sdk", "dep:quicprochat-rpc", "dep:rustyline"]
+
+[dev-dependencies]
+dashmap       = { workspace = true }
+assert_cmd    = "2"
+tempfile      = "3"
+portpicker    = "0.1"
+rand          = "0.8"

crates/quicprochat-client/src/client/command_engine.rs

@@ -0,0 +1,508 @@
+//! Command engine: typed command enum, registry, and execution bridge.
+//!
+//! Maps every REPL slash command and lifecycle operation into a single `Command`
+//! enum with typed parameters. `CommandRegistry` parses raw input and delegates
+//! execution to the existing `cmd_*` handlers in `repl.rs`.
+
+use std::collections::HashMap;
+
+use quicprochat_proto::node_capnp::node_service;
+
+use super::repl::{Input, SlashCommand, parse_input};
+use super::session::SessionState;
+
+// ── Comparison operator for assert conditions ────────────────────────────────
+
+/// Comparison operator used in playbook assertions.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "playbook", derive(serde::Serialize, serde::Deserialize))]
+pub enum CmpOp {
+    Eq,
+    Ne,
+    Gt,
+    Lt,
+    Gte,
+    Lte,
+}
+
+impl CmpOp {
+    /// Evaluate this comparison: `lhs <op> rhs`.
+    pub fn eval(&self, lhs: usize, rhs: usize) -> bool {
+        match self {
+            CmpOp::Eq => lhs == rhs,
+            CmpOp::Ne => lhs != rhs,
+            CmpOp::Gt => lhs > rhs,
+            CmpOp::Lt => lhs < rhs,
+            CmpOp::Gte => lhs >= rhs,
+            CmpOp::Lte => lhs <= rhs,
+        }
+    }
+}
+
+// ── Assert conditions for playbook testing ───────────────────────────────────
+
+/// Conditions that can be asserted in a playbook step.
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "playbook", derive(serde::Serialize, serde::Deserialize))]
+pub enum AssertCondition {
+    Connected,
+    LoggedIn,
+    InConversation { name: String },
+    MessageCount { op: CmpOp, count: usize },
+    MemberCount { op: CmpOp, count: usize },
+    Custom { expression: String },
+}
+
+// ── Command enum ─────────────────────────────────────────────────────────────
+
+/// Every operation the client can perform, with typed parameters.
+///
+/// This is a superset of `SlashCommand` — it adds lifecycle operations
+/// (`Connect`, `Login`, `Register`, `SendMessage`, `Wait`, `Assert`, `SetVar`)
+/// that are needed for non-interactive / playbook execution.
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "playbook", derive(serde::Serialize, serde::Deserialize))]
+pub enum Command {
+    // ── Lifecycle (not in SlashCommand) ──────────────────────────────────
+    Connect {
+        server: String,
+        ca_cert: Option<String>,
+        insecure: bool,
+    },
+    Login {
+        username: String,
+        password: String,
+    },
+    Register {
+        username: String,
+        password: String,
+    },
+    SendMessage {
+        text: String,
+    },
+    Wait {
+        duration_ms: u64,
+    },
+    Assert {
+        condition: AssertCondition,
+    },
+    SetVar {
+        name: String,
+        value: String,
+    },
+
+    // ── SlashCommand mirror ─────────────────────────────────────────────
+    Help,
+    Quit,
+    Whoami,
+    List,
+    Switch { target: String },
+    Dm { username: String },
+    CreateGroup { name: String },
+    Invite { target: String },
+    Remove { target: String },
+    Leave,
+    Join,
+    Members,
+    GroupInfo,
+    Rename { name: String },
+    History { count: usize },
+
+    // Mesh
+    MeshPeers,
+    MeshServer { addr: String },
+    MeshSend { peer_id: String, message: String },
+    MeshBroadcast { topic: String, message: String },
+    MeshSubscribe { topic: String },
+    MeshRoute,
+    MeshIdentity,
+    MeshStore,
+
+    // Security / crypto
+    Verify { username: String },
+    UpdateKey,
+    Typing,
+    TypingNotify { enabled: bool },
+    React { emoji: String, index: Option<usize> },
+    Edit { index: usize, new_text: String },
+    Delete { index: usize },
+    SendFile { path: String },
+    Download { index: usize },
+    DeleteAccount,
+    Disappear { arg: Option<String> },
+    Privacy { arg: Option<String> },
+    VerifyFs,
+    RotateAllKeys,
+    Devices,
+    RegisterDevice { name: String },
+    RevokeDevice { id_prefix: String },
+}
+
+impl Command {
+    /// Convert a `Command` to a `SlashCommand` when possible.
+    ///
+    /// Returns `None` for lifecycle commands that have no `SlashCommand`
+    /// equivalent (`Connect`, `Login`, `Register`, `SendMessage`, `Wait`,
+    /// `Assert`, `SetVar`).
+    pub(crate) fn to_slash(&self) -> Option<SlashCommand> {
+        match self.clone() {
+            // Lifecycle — no SlashCommand equivalent
+            Command::Connect { .. }
+            | Command::Login { .. }
+            | Command::Register { .. }
+            | Command::SendMessage { .. }
+            | Command::Wait { .. }
+            | Command::Assert { .. }
+            | Command::SetVar { .. } => None,
+
+            // 1:1 mirror
+            Command::Help => Some(SlashCommand::Help),
+            Command::Quit => Some(SlashCommand::Quit),
+            Command::Whoami => Some(SlashCommand::Whoami),
+            Command::List => Some(SlashCommand::List),
+            Command::Switch { target } => Some(SlashCommand::Switch { target }),
+            Command::Dm { username } => Some(SlashCommand::Dm { username }),
+            Command::CreateGroup { name } => Some(SlashCommand::CreateGroup { name }),
+            Command::Invite { target } => Some(SlashCommand::Invite { target }),
+            Command::Remove { target } => Some(SlashCommand::Remove { target }),
+            Command::Leave => Some(SlashCommand::Leave),
+            Command::Join => Some(SlashCommand::Join),
+            Command::Members => Some(SlashCommand::Members),
+            Command::GroupInfo => Some(SlashCommand::GroupInfo),
+            Command::Rename { name } => Some(SlashCommand::Rename { name }),
+            Command::History { count } => Some(SlashCommand::History { count }),
+            Command::MeshPeers => Some(SlashCommand::MeshPeers),
+            Command::MeshServer { addr } => Some(SlashCommand::MeshServer { addr }),
+            Command::MeshSend { peer_id, message } => {
+                Some(SlashCommand::MeshSend { peer_id, message })
+            }
+            Command::MeshBroadcast { topic, message } => {
+                Some(SlashCommand::MeshBroadcast { topic, message })
+            }
+            Command::MeshSubscribe { topic } => Some(SlashCommand::MeshSubscribe { topic }),
+            Command::MeshRoute => Some(SlashCommand::MeshRoute),
+            Command::MeshIdentity => Some(SlashCommand::MeshIdentity),
+            Command::MeshStore => Some(SlashCommand::MeshStore),
+            Command::Verify { username } => Some(SlashCommand::Verify { username }),
+            Command::UpdateKey => Some(SlashCommand::UpdateKey),
+            Command::Typing => Some(SlashCommand::Typing),
+            Command::TypingNotify { enabled } => Some(SlashCommand::TypingNotify { enabled }),
+            Command::React { emoji, index } => Some(SlashCommand::React { emoji, index }),
+            Command::Edit { index, new_text } => Some(SlashCommand::Edit { index, new_text }),
+            Command::Delete { index } => Some(SlashCommand::Delete { index }),
+            Command::SendFile { path } => Some(SlashCommand::SendFile { path }),
+            Command::Download { index } => Some(SlashCommand::Download { index }),
+            Command::DeleteAccount => Some(SlashCommand::DeleteAccount),
+            Command::Disappear { arg } => Some(SlashCommand::Disappear { arg }),
+            Command::Privacy { arg } => Some(SlashCommand::Privacy { arg }),
+            Command::VerifyFs => Some(SlashCommand::VerifyFs),
+            Command::RotateAllKeys => Some(SlashCommand::RotateAllKeys),
+            Command::Devices => Some(SlashCommand::Devices),
+            Command::RegisterDevice { name } => Some(SlashCommand::RegisterDevice { name }),
+            Command::RevokeDevice { id_prefix } => {
+                Some(SlashCommand::RevokeDevice { id_prefix })
+            }
+        }
+    }
+}
+
+// ── CommandResult ────────────────────────────────────────────────────────────
+
+/// Outcome of executing a single `Command`.
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "playbook", derive(serde::Serialize, serde::Deserialize))]
+pub struct CommandResult {
+    pub success: bool,
+    pub output: Option<String>,
+    pub error: Option<String>,
+    /// Structured key-value outputs for variable capture in playbooks.
+    pub data: HashMap<String, String>,
+}
+
+impl CommandResult {
+    fn ok() -> Self {
+        Self {
+            success: true,
+            output: None,
+            error: None,
+            data: HashMap::new(),
+        }
+    }
+
+    fn err(msg: String) -> Self {
+        Self {
+            success: false,
+            output: None,
+            error: Some(msg),
+            data: HashMap::new(),
+        }
+    }
+}
+
+// ── CommandRegistry ──────────────────────────────────────────────────────────
+
+/// Parses raw input into `Command` and delegates execution to the existing
+/// REPL handlers.
+pub struct CommandRegistry;
+
+impl CommandRegistry {
+    /// Parse a raw input line into a `Command`.
+    ///
+    /// Returns `None` for empty input. Returns `Some(Command::SendMessage)`
+    /// for plain chat text. Slash commands are parsed via the existing
+    /// `parse_input` function.
+    pub fn parse(line: &str) -> Option<Command> {
+        match parse_input(line) {
+            Input::Empty => None,
+            Input::ChatMessage(text) => Some(Command::SendMessage { text }),
+            Input::Slash(sc) => Some(slash_to_command(sc)),
+        }
+    }
+
+    /// Execute a `Command`, delegating slash commands to the existing
+    /// `handle_slash` dispatch and handling lifecycle commands directly.
+    ///
+    /// Currently, output from `cmd_*` handlers goes to stdout (unchanged).
+    /// `CommandResult` captures success/failure status; stdout capture can
+    /// be added later.
+    pub async fn execute(
+        cmd: &Command,
+        session: &mut SessionState,
+        client: &node_service::Client,
+    ) -> CommandResult {
+        match cmd {
+            Command::Wait { duration_ms } => {
+                tokio::time::sleep(std::time::Duration::from_millis(*duration_ms)).await;
+                CommandResult::ok()
+            }
+            Command::SetVar { name, value } => {
+                let mut result = CommandResult::ok();
+                result.data.insert(name.clone(), value.clone());
+                result
+            }
+            Command::Assert { condition } => execute_assert(condition, session),
+            Command::Connect { .. } | Command::Login { .. } | Command::Register { .. } => {
+                // These lifecycle commands require external context (endpoint,
+                // OPAQUE state) that lives outside SessionState. The playbook
+                // executor will handle them directly; calling execute() for
+                // them is an error.
+                CommandResult::err(
+                    "lifecycle commands (connect/login/register) must be handled by the playbook executor".into(),
+                )
+            }
+            Command::SendMessage { text } => {
+                match super::repl::do_send(session, client, text).await {
+                    Ok(()) => CommandResult::ok(),
+                    Err(e) => CommandResult::err(format!("{e:#}")),
+                }
+            }
+            Command::Quit => CommandResult::ok(),
+            other => {
+                // All remaining variants have a SlashCommand equivalent.
+                if let Some(sc) = other.to_slash() {
+                    match execute_slash(session, client, sc).await {
+                        Ok(()) => CommandResult::ok(),
+                        Err(e) => CommandResult::err(format!("{e:#}")),
+                    }
+                } else {
+                    CommandResult::err("command has no slash equivalent".into())
+                }
+            }
+        }
+    }
+}
+
+// ── Conversion helpers ──────────────────────────────────────────────────────
+
+/// Convert a `SlashCommand` into the corresponding `Command`.
+fn slash_to_command(sc: SlashCommand) -> Command {
+    match sc {
+        SlashCommand::Help => Command::Help,
+        SlashCommand::Quit => Command::Quit,
+        SlashCommand::Whoami => Command::Whoami,
+        SlashCommand::List => Command::List,
+        SlashCommand::Switch { target } => Command::Switch { target },
+        SlashCommand::Dm { username } => Command::Dm { username },
+        SlashCommand::CreateGroup { name } => Command::CreateGroup { name },
+        SlashCommand::Invite { target } => Command::Invite { target },
+        SlashCommand::Remove { target } => Command::Remove { target },
+        SlashCommand::Leave => Command::Leave,
+        SlashCommand::Join => Command::Join,
+        SlashCommand::Members => Command::Members,
+        SlashCommand::GroupInfo => Command::GroupInfo,
+        SlashCommand::Rename { name } => Command::Rename { name },
+        SlashCommand::History { count } => Command::History { count },
+        SlashCommand::MeshPeers => Command::MeshPeers,
+        SlashCommand::MeshServer { addr } => Command::MeshServer { addr },
+        SlashCommand::MeshSend { peer_id, message } => Command::MeshSend { peer_id, message },
+        SlashCommand::MeshBroadcast { topic, message } => {
+            Command::MeshBroadcast { topic, message }
+        }
+        SlashCommand::MeshSubscribe { topic } => Command::MeshSubscribe { topic },
+        SlashCommand::MeshRoute => Command::MeshRoute,
+        SlashCommand::MeshIdentity => Command::MeshIdentity,
+        SlashCommand::MeshStore => Command::MeshStore,
+        SlashCommand::Verify { username } => Command::Verify { username },
+        SlashCommand::UpdateKey => Command::UpdateKey,
+        SlashCommand::Typing => Command::Typing,
+        SlashCommand::TypingNotify { enabled } => Command::TypingNotify { enabled },
+        SlashCommand::React { emoji, index } => Command::React { emoji, index },
+        SlashCommand::Edit { index, new_text } => Command::Edit { index, new_text },
+        SlashCommand::Delete { index } => Command::Delete { index },
+        SlashCommand::SendFile { path } => Command::SendFile { path },
+        SlashCommand::Download { index } => Command::Download { index },
+        SlashCommand::DeleteAccount => Command::DeleteAccount,
+        SlashCommand::Disappear { arg } => Command::Disappear { arg },
+        SlashCommand::Privacy { arg } => Command::Privacy { arg },
+        SlashCommand::VerifyFs => Command::VerifyFs,
+        SlashCommand::RotateAllKeys => Command::RotateAllKeys,
+        SlashCommand::Devices => Command::Devices,
+        SlashCommand::RegisterDevice { name } => Command::RegisterDevice { name },
+        SlashCommand::RevokeDevice { id_prefix } => Command::RevokeDevice { id_prefix },
+    }
+}
+
+// ── Execution helpers ───────────────────────────────────────────────────────
+
+/// Execute a `SlashCommand` using the existing `cmd_*` handlers from `repl.rs`.
+///
+/// This duplicates the dispatch table from `handle_slash` but returns
+/// `anyhow::Result<()>` instead of printing errors inline — the caller
+/// decides how to surface errors.
+async fn execute_slash(
+    session: &mut SessionState,
+    client: &node_service::Client,
+    cmd: SlashCommand,
+) -> anyhow::Result<()> {
+    use super::repl::*;
+    match cmd {
+        SlashCommand::Help => {
+            print_help();
+            Ok(())
+        }
+        SlashCommand::Quit => Ok(()),
+        SlashCommand::Whoami => cmd_whoami(session),
+        SlashCommand::List => cmd_list(session),
+        SlashCommand::Switch { target } => cmd_switch(session, &target),
+        SlashCommand::Dm { username } => cmd_dm(session, client, &username).await,
+        SlashCommand::CreateGroup { name } => cmd_create_group(session, &name),
+        SlashCommand::Invite { target } => cmd_invite(session, client, &target).await,
+        SlashCommand::Remove { target } => cmd_remove(session, client, &target).await,
+        SlashCommand::Leave => cmd_leave(session, client).await,
+        SlashCommand::Join => cmd_join(session, client).await,
+        SlashCommand::Members => cmd_members(session, client).await,
+        SlashCommand::GroupInfo => cmd_group_info(session, client).await,
+        SlashCommand::Rename { name } => cmd_rename(session, &name),
+        SlashCommand::History { count } => cmd_history(session, count),
+        SlashCommand::MeshPeers => cmd_mesh_peers(),
+        SlashCommand::MeshServer { addr } => {
+            super::display::print_status(&format!(
+                "mesh server hint: reconnect with --server {addr} to use this node"
+            ));
+            Ok(())
+        }
+        SlashCommand::MeshSend { peer_id, message } => cmd_mesh_send(&peer_id, &message),
+        SlashCommand::MeshBroadcast { topic, message } => cmd_mesh_broadcast(&topic, &message),
+        SlashCommand::MeshSubscribe { topic } => cmd_mesh_subscribe(&topic),
+        SlashCommand::MeshRoute => cmd_mesh_route(session),
+        SlashCommand::MeshIdentity => cmd_mesh_identity(session),
+        SlashCommand::MeshStore => cmd_mesh_store(session),
+        SlashCommand::Verify { username } => cmd_verify(session, client, &username).await,
+        SlashCommand::UpdateKey => cmd_update_key(session, client).await,
+        SlashCommand::Typing => cmd_typing(session, client).await,
+        SlashCommand::TypingNotify { enabled } => {
+            session.typing_notify_enabled = enabled;
+            super::display::print_status(&format!(
+                "typing notifications {}",
+                if enabled { "enabled" } else { "disabled" }
+            ));
+            Ok(())
+        }
+        SlashCommand::React { emoji, index } => cmd_react(session, client, &emoji, index).await,
+        SlashCommand::Edit { index, new_text } => {
+            cmd_edit(session, client, index, &new_text).await
+        }
+        SlashCommand::Delete { index } => cmd_delete(session, client, index).await,
+        SlashCommand::SendFile { path } => cmd_send_file(session, client, &path).await,
+        SlashCommand::Download { index } => cmd_download(session, client, index).await,
+        SlashCommand::DeleteAccount => cmd_delete_account(session, client).await,
+        SlashCommand::Disappear { arg } => cmd_disappear(session, arg.as_deref()),
+        SlashCommand::Privacy { arg } => cmd_privacy(session, arg.as_deref()),
+        SlashCommand::VerifyFs => cmd_verify_fs(session),
+        SlashCommand::RotateAllKeys => cmd_rotate_all_keys(session, client).await,
+        SlashCommand::Devices => cmd_devices(client).await,
+        SlashCommand::RegisterDevice { name } => cmd_register_device(client, &name).await,
+        SlashCommand::RevokeDevice { id_prefix } => cmd_revoke_device(client, &id_prefix).await,
+    }
+}
+
+/// Assert a condition against the current session state.
+fn execute_assert(condition: &AssertCondition, session: &SessionState) -> CommandResult {
+    match condition {
+        AssertCondition::Connected => {
+            // We have a session => we got past connect. Always true when
+            // execute() is called with a valid client reference.
+            CommandResult::ok()
+        }
+        AssertCondition::LoggedIn => {
+            let guard = crate::AUTH_CONTEXT
+                .read()
+                .expect("AUTH_CONTEXT poisoned");
+            if guard.is_some() {
+                CommandResult::ok()
+            } else {
+                CommandResult::err("not logged in".into())
+            }
+        }
+        AssertCondition::InConversation { name } => {
+            if let Some(display) = session.active_display_name() {
+                if display.contains(name.as_str()) {
+                    CommandResult::ok()
+                } else {
+                    CommandResult::err(format!(
+                        "active conversation is '{display}', expected '{name}'"
+                    ))
+                }
+            } else {
+                CommandResult::err("no active conversation".into())
+            }
+        }
+        AssertCondition::MessageCount { op, count } => {
+            let actual = session
+                .active_conversation
+                .as_ref()
+                .and_then(|id| session.conv_store.load_all_messages(id).ok())
+                .map(|msgs| msgs.len())
+                .unwrap_or(0);
+            if op.eval(actual, *count) {
+                CommandResult::ok()
+            } else {
+                CommandResult::err(format!(
+                    "message count assertion failed: {actual} {op:?} {count}"
+                ))
+            }
+        }
+        AssertCondition::MemberCount { op, count } => {
+            let actual = session
+                .active_conversation
+                .as_ref()
+                .and_then(|id| session.members.get(id))
+                .map(|m| m.member_identities().len())
+                .unwrap_or(0);
+            if op.eval(actual, *count) {
+                CommandResult::ok()
+            } else {
+                CommandResult::err(format!(
+                    "member count assertion failed: {actual} {op:?} {count}"
+                ))
+            }
+        }
+        AssertCondition::Custom { expression } => {
+            // Custom expressions are not evaluated yet; always pass.
+            let mut result = CommandResult::ok();
+            result.data.insert("expression".into(), expression.clone());
+            result
+        }
+    }
+}
+

crates/quicprochat-client/src/client/conversation.rs

@@ -0,0 +1,798 @@
+//! Multi-conversation state backed by SQLite (SQLCipher-encrypted when a
+//! password is provided).
+//!
+//! Each conversation (DM or group) has its own MLS group blob, keystore blob,
+//! member list, and message history.
+
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use anyhow::Context;
+use argon2::{Algorithm, Argon2, Params, Version};
+use rand::RngCore;
+use rusqlite::{params, Connection, OptionalExtension};
+use zeroize::Zeroizing;
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+/// 16-byte conversation identifier.
+///   - DMs: the channel_id returned by `createChannel` (server-assigned UUID).
+///   - Groups: SHA-256(group_name)[..16].
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct ConversationId(pub [u8; 16]);
+
+impl ConversationId {
+    pub fn from_slice(s: &[u8]) -> Option<Self> {
+        if s.len() == 16 {
+            let mut buf = [0u8; 16];
+            buf.copy_from_slice(s);
+            Some(Self(buf))
+        } else {
+            None
+        }
+    }
+
+    /// Derive a conversation ID from a group name via SHA-256 truncation.
+    pub fn from_group_name(name: &str) -> Self {
+        use sha2::{Sha256, Digest};
+        let hash = Sha256::digest(name.as_bytes());
+        let mut buf = [0u8; 16];
+        buf.copy_from_slice(&hash[..16]);
+        Self(buf)
+    }
+
+    pub fn hex(&self) -> String {
+        hex::encode(self.0)
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ConversationKind {
+    /// 1:1 DM channel with a specific peer.
+    Dm {
+        peer_key: Vec<u8>,
+        peer_username: Option<String>,
+    },
+    /// Named group with N members.
+    Group { name: String },
+}
+
+#[derive(Clone, Debug)]
+pub struct Conversation {
+    pub id: ConversationId,
+    pub kind: ConversationKind,
+    pub display_name: String,
+    /// Serialized MLS group (bincode).
+    pub mls_group_blob: Option<Vec<u8>>,
+    /// Serialized keystore (bincode HashMap).
+    pub keystore_blob: Option<Vec<u8>>,
+    /// Member identity keys (bincode Vec<Vec<u8>>).
+    pub member_keys: Vec<Vec<u8>>,
+    pub unread_count: u32,
+    pub last_activity_ms: u64,
+    pub created_at_ms: u64,
+    /// Whether this conversation uses hybrid (X25519 + ML-KEM-768) MLS keys.
+    pub is_hybrid: bool,
+    /// Highest server-side delivery sequence number seen.
+    pub last_seen_seq: u64,
+}
+
+#[derive(Clone, Debug)]
+pub struct StoredMessage {
+    pub conversation_id: ConversationId,
+    pub message_id: Option<[u8; 16]>,
+    pub sender_key: Vec<u8>,
+    pub sender_name: Option<String>,
+    pub body: String,
+    pub msg_type: String,
+    pub ref_msg_id: Option<[u8; 16]>,
+    pub timestamp_ms: u64,
+    pub is_outgoing: bool,
+}
+
+// ── Key derivation (Argon2id, matching state.rs parameters) ─────────────────
+
+const ARGON2_M_COST: u32 = 19 * 1024;
+const ARGON2_T_COST: u32 = 2;
+const ARGON2_P_COST: u32 = 1;
+const SALT_LEN: usize = 16;
+
+/// Derive a 32-byte SQLCipher key from the user password and a random salt.
+fn derive_convdb_key(password: &str, salt: &[u8]) -> anyhow::Result<Zeroizing<[u8; 32]>> {
+    let params = Params::new(ARGON2_M_COST, ARGON2_T_COST, ARGON2_P_COST, Some(32))
+        .map_err(|e| anyhow::anyhow!("argon2 params: {e}"))?;
+    let argon2 = Argon2::new(Algorithm::Argon2id, Version::default(), params);
+    let mut key = Zeroizing::new([0u8; 32]);
+    argon2
+        .hash_password_into(password.as_bytes(), salt, &mut *key)
+        .map_err(|e| anyhow::anyhow!("convdb key derivation: {e}"))?;
+    Ok(key)
+}
+
+/// Read or create a 16-byte random salt at `salt_path` (mode 0o600).
+fn get_or_create_salt(salt_path: &Path) -> anyhow::Result<Vec<u8>> {
+    if salt_path.exists() {
+        let bytes = std::fs::read(salt_path).context("read convdb salt")?;
+        anyhow::ensure!(bytes.len() == SALT_LEN, "invalid convdb salt length");
+        return Ok(bytes);
+    }
+    let mut salt = vec![0u8; SALT_LEN];
+    rand::rngs::OsRng.fill_bytes(&mut salt);
+    std::fs::write(salt_path, &salt).context("write convdb salt")?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::set_permissions(salt_path, std::fs::Permissions::from_mode(0o600)).ok();
+    }
+    Ok(salt)
+}
+
+// ── ConversationStore ────────────────────────────────────────────────────────
+
+pub struct ConversationStore {
+    conn: Connection,
+}
+
+impl ConversationStore {
+    /// Open or create the conversation database at `db_path`.
+    /// If `password` is `Some`, the database is encrypted with SQLCipher using
+    /// an Argon2id-derived key. Existing unencrypted databases are migrated
+    /// transparently.
+    pub fn open(db_path: &Path, password: Option<&str>) -> anyhow::Result<Self> {
+        if let Some(parent) = db_path.parent() {
+            std::fs::create_dir_all(parent).ok();
+        }
+
+        match password {
+            Some(pw) => Self::open_encrypted(db_path, pw),
+            None => Self::open_plain(db_path),
+        }
+    }
+
+    fn open_plain(db_path: &Path) -> anyhow::Result<Self> {
+        let conn = Connection::open(db_path).context("open conversation db")?;
+        conn.execute_batch("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;")
+            .context("set pragmas")?;
+        Self::migrate(&conn)?;
+        Ok(Self { conn })
+    }
+
+    fn open_encrypted(db_path: &Path, password: &str) -> anyhow::Result<Self> {
+        let salt_path = PathBuf::from(format!("{}-salt", db_path.display()));
+        let already_encrypted = salt_path.exists();
+
+        // Migrate an existing unencrypted database before opening with encryption.
+        if db_path.exists() && !already_encrypted {
+            Self::migrate_plain_to_encrypted(db_path, &salt_path, password)?;
+            // After migration, salt file exists and DB is encrypted — fall through.
+        }
+
+        let salt = get_or_create_salt(&salt_path)?;
+        let key = derive_convdb_key(password, &salt)?;
+        #[allow(clippy::needless_borrows_for_generic_args)]
+        let hex_key = Zeroizing::new(hex::encode(&*key));
+
+        let conn = Connection::open(db_path).context("open conversation db")?;
+        conn.pragma_update(None, "key", format!("x'{}'", &*hex_key))
+            .context("set SQLCipher key")?;
+        conn.execute_batch("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;")
+            .context("set pragmas")?;
+        Self::migrate(&conn)?;
+        Ok(Self { conn })
+    }
+
+    /// Migrate an unencrypted `.convdb` to an encrypted one in-place.
+    fn migrate_plain_to_encrypted(
+        db_path: &Path,
+        salt_path: &Path,
+        password: &str,
+    ) -> anyhow::Result<()> {
+        let salt = get_or_create_salt(salt_path)?;
+        let key = derive_convdb_key(password, &salt)?;
+        #[allow(clippy::needless_borrows_for_generic_args)]
+        let hex_key = Zeroizing::new(hex::encode(&*key));
+
+        let enc_path = db_path.with_extension("convdb-enc");
+
+        // Open the existing plaintext database.
+        let plain = Connection::open(db_path).context("open plain convdb for migration")?;
+        plain.execute_batch("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;").ok();
+
+        // Attach a new encrypted database and export into it.
+        // Sanitize the path to prevent SQL injection (ATTACH does not support parameterized paths).
+        let enc_path_str = enc_path.display().to_string();
+        anyhow::ensure!(
+            !enc_path_str.contains('\''),
+            "database path must not contain single quotes: {enc_path_str}"
+        );
+        plain
+            .execute_batch(&format!(
+                "ATTACH DATABASE '{enc_path_str}' AS encrypted KEY \"x'{}'\";",
+                &*hex_key
+            ))
+            .context("attach encrypted db for migration")?;
+        plain
+            .execute_batch("SELECT sqlcipher_export('encrypted');")
+            .context("sqlcipher_export to encrypted db")?;
+        plain
+            .execute_batch("DETACH DATABASE encrypted;")
+            .context("detach encrypted db")?;
+
+        drop(plain);
+
+        // Swap files: encrypted → original.
+        std::fs::rename(&enc_path, db_path).context("replace convdb with encrypted version")?;
+        // Clean up WAL/SHM left from the plaintext open.
+        let wal = PathBuf::from(format!("{}-wal", db_path.display()));
+        let shm = PathBuf::from(format!("{}-shm", db_path.display()));
+        std::fs::remove_file(&wal).ok();
+        std::fs::remove_file(&shm).ok();
+
+        tracing::info!("migrated conversation database to encrypted storage");
+        Ok(())
+    }
+
+    fn migrate(conn: &Connection) -> anyhow::Result<()> {
+        conn.execute_batch(
+            "CREATE TABLE IF NOT EXISTS conversations (
+                id              BLOB PRIMARY KEY,
+                kind            TEXT NOT NULL,
+                display_name    TEXT NOT NULL,
+                peer_key        BLOB,
+                peer_username   TEXT,
+                group_name      TEXT,
+                mls_group_blob  BLOB,
+                keystore_blob   BLOB,
+                member_keys     BLOB,
+                unread_count    INTEGER NOT NULL DEFAULT 0,
+                last_activity_ms INTEGER NOT NULL DEFAULT 0,
+                created_at_ms   INTEGER NOT NULL DEFAULT 0
+            );
+
+            CREATE TABLE IF NOT EXISTS messages (
+                id              INTEGER PRIMARY KEY AUTOINCREMENT,
+                conversation_id BLOB NOT NULL REFERENCES conversations(id),
+                message_id      BLOB,
+                sender_key      BLOB NOT NULL,
+                sender_name     TEXT,
+                body            TEXT NOT NULL,
+                msg_type        TEXT NOT NULL,
+                ref_msg_id      BLOB,
+                timestamp_ms    INTEGER NOT NULL,
+                is_outgoing     INTEGER NOT NULL DEFAULT 0
+            );
+
+            CREATE INDEX IF NOT EXISTS idx_messages_conv
+                ON messages(conversation_id, timestamp_ms);
+
+            CREATE TABLE IF NOT EXISTS outbox (
+                id              INTEGER PRIMARY KEY AUTOINCREMENT,
+                conversation_id BLOB NOT NULL,
+                recipient_key   BLOB NOT NULL,
+                payload         BLOB NOT NULL,
+                created_at_ms   INTEGER NOT NULL,
+                retry_count     INTEGER NOT NULL DEFAULT 0,
+                status          TEXT NOT NULL DEFAULT 'pending'
+            );
+            CREATE INDEX IF NOT EXISTS idx_outbox_status
+                ON outbox(status, created_at_ms);",
+        )
+        .context("migrate conversation db")?;
+
+        // Additive migrations for new columns (safe to re-run; errors ignored if column already exists).
+        conn.execute_batch("ALTER TABLE conversations ADD COLUMN is_hybrid INTEGER NOT NULL DEFAULT 0;").ok();
+        conn.execute_batch("ALTER TABLE conversations ADD COLUMN last_seen_seq INTEGER NOT NULL DEFAULT 0;").ok();
+
+        Ok(())
+    }
+
+    // ── Conversation CRUD ────────────────────────────────────────────────
+
+    pub fn save_conversation(&self, conv: &Conversation) -> anyhow::Result<()> {
+        let (kind_str, peer_key, peer_username, group_name) = match &conv.kind {
+            ConversationKind::Dm {
+                peer_key,
+                peer_username,
+            } => ("dm", Some(peer_key.as_slice()), peer_username.as_deref(), None),
+            ConversationKind::Group { name } => ("group", None, None, Some(name.as_str())),
+        };
+        let member_keys_blob = bincode::serialize(&conv.member_keys)
+            .context("serialize member_keys")?;
+
+        self.conn.execute(
+            "INSERT INTO conversations
+                (id, kind, display_name, peer_key, peer_username, group_name,
+                 mls_group_blob, keystore_blob, member_keys, unread_count,
+                 last_activity_ms, created_at_ms, is_hybrid, last_seen_seq)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14)
+             ON CONFLICT(id) DO UPDATE SET
+                display_name = excluded.display_name,
+                mls_group_blob = excluded.mls_group_blob,
+                keystore_blob = excluded.keystore_blob,
+                member_keys = excluded.member_keys,
+                unread_count = excluded.unread_count,
+                last_activity_ms = excluded.last_activity_ms,
+                is_hybrid = excluded.is_hybrid,
+                last_seen_seq = excluded.last_seen_seq",
+            params![
+                conv.id.0.as_slice(),
+                kind_str,
+                conv.display_name,
+                peer_key,
+                peer_username,
+                group_name,
+                conv.mls_group_blob,
+                conv.keystore_blob,
+                member_keys_blob,
+                conv.unread_count,
+                conv.last_activity_ms,
+                conv.created_at_ms,
+                conv.is_hybrid as i32,
+                conv.last_seen_seq as i64,
+            ],
+        )?;
+        Ok(())
+    }
+
+    pub fn load_conversation(&self, id: &ConversationId) -> anyhow::Result<Option<Conversation>> {
+        self.conn
+            .query_row(
+                "SELECT kind, display_name, peer_key, peer_username, group_name,
+                        mls_group_blob, keystore_blob, member_keys, unread_count,
+                        last_activity_ms, created_at_ms, is_hybrid, last_seen_seq
+                 FROM conversations WHERE id = ?1",
+                params![id.0.as_slice()],
+                |row| {
+                    let kind_str: String = row.get(0)?;
+                    let display_name: String = row.get(1)?;
+                    let peer_key: Option<Vec<u8>> = row.get(2)?;
+                    let peer_username: Option<String> = row.get(3)?;
+                    let group_name: Option<String> = row.get(4)?;
+                    let mls_group_blob: Option<Vec<u8>> = row.get(5)?;
+                    let keystore_blob: Option<Vec<u8>> = row.get(6)?;
+                    let member_keys_blob: Option<Vec<u8>> = row.get(7)?;
+                    let unread_count: u32 = row.get(8)?;
+                    let last_activity_ms: u64 = row.get(9)?;
+                    let created_at_ms: u64 = row.get(10)?;
+                    let is_hybrid_int: i32 = row.get(11)?;
+                    let last_seen_seq: i64 = row.get(12)?;
+
+                    let kind = if kind_str == "dm" {
+                        ConversationKind::Dm {
+                            peer_key: peer_key.unwrap_or_default(),
+                            peer_username,
+                        }
+                    } else {
+                        ConversationKind::Group {
+                            name: group_name.unwrap_or_default(),
+                        }
+                    };
+
+                    let member_keys: Vec<Vec<u8>> = member_keys_blob
+                        .and_then(|b| match bincode::deserialize(&b) {
+                            Ok(v) => Some(v),
+                            Err(e) => {
+                                tracing::warn!(conv = %hex::encode(id.0), "bincode deserialize member_keys failed: {e}");
+                                None
+                            }
+                        })
+                        .unwrap_or_default();
+
+                    Ok(Conversation {
+                        id: id.clone(),
+                        kind,
+                        display_name,
+                        mls_group_blob,
+                        keystore_blob,
+                        member_keys,
+                        unread_count,
+                        last_activity_ms,
+                        created_at_ms,
+                        is_hybrid: is_hybrid_int != 0,
+                        last_seen_seq: last_seen_seq as u64,
+                    })
+                },
+            )
+            .optional()
+            .context("load conversation")
+    }
+
+    pub fn list_conversations(&self) -> anyhow::Result<Vec<Conversation>> {
+        let mut stmt = self.conn.prepare(
+            "SELECT id, kind, display_name, peer_key, peer_username, group_name,
+                    mls_group_blob, keystore_blob, member_keys, unread_count,
+                    last_activity_ms, created_at_ms, is_hybrid, last_seen_seq
+             FROM conversations ORDER BY last_activity_ms DESC",
+        )?;
+        let rows = stmt.query_map([], |row| {
+            let id_blob: Vec<u8> = row.get(0)?;
+            let kind_str: String = row.get(1)?;
+            let display_name: String = row.get(2)?;
+            let peer_key: Option<Vec<u8>> = row.get(3)?;
+            let peer_username: Option<String> = row.get(4)?;
+            let group_name: Option<String> = row.get(5)?;
+            let mls_group_blob: Option<Vec<u8>> = row.get(6)?;
+            let keystore_blob: Option<Vec<u8>> = row.get(7)?;
+            let member_keys_blob: Option<Vec<u8>> = row.get(8)?;
+            let unread_count: u32 = row.get(9)?;
+            let last_activity_ms: u64 = row.get(10)?;
+            let created_at_ms: u64 = row.get(11)?;
+            let is_hybrid_int: i32 = row.get(12)?;
+            let last_seen_seq: i64 = row.get(13)?;
+
+            let id = ConversationId::from_slice(&id_blob).unwrap_or(ConversationId([0; 16]));
+            let kind = if kind_str == "dm" {
+                ConversationKind::Dm {
+                    peer_key: peer_key.unwrap_or_default(),
+                    peer_username,
+                }
+            } else {
+                ConversationKind::Group {
+                    name: group_name.unwrap_or_default(),
+                }
+            };
+            let member_keys: Vec<Vec<u8>> = member_keys_blob
+                .and_then(|b| match bincode::deserialize(&b) {
+                    Ok(v) => Some(v),
+                    Err(e) => {
+                        tracing::warn!(conv = %hex::encode(&id_blob), "bincode deserialize member_keys failed: {e}");
+                        None
+                    }
+                })
+                .unwrap_or_default();
+
+            Ok(Conversation {
+                id,
+                kind,
+                display_name,
+                mls_group_blob,
+                keystore_blob,
+                member_keys,
+                unread_count,
+                last_activity_ms,
+                created_at_ms,
+                is_hybrid: is_hybrid_int != 0,
+                last_seen_seq: last_seen_seq as u64,
+            })
+        })?;
+
+        let mut convs = Vec::new();
+        for row in rows {
+            convs.push(row?);
+        }
+        Ok(convs)
+    }
+
+    /// Find a DM conversation by the peer's identity key.
+    pub fn find_dm_by_peer(&self, peer_key: &[u8]) -> anyhow::Result<Option<Conversation>> {
+        let id_blob: Option<Vec<u8>> = self
+            .conn
+            .query_row(
+                "SELECT id FROM conversations WHERE kind = 'dm' AND peer_key = ?1",
+                params![peer_key],
+                |row| row.get(0),
+            )
+            .optional()?;
+
+        match id_blob {
+            Some(blob) => {
+                let id = ConversationId::from_slice(&blob)
+                    .context("invalid conversation id in db")?;
+                self.load_conversation(&id)
+            }
+            None => Ok(None),
+        }
+    }
+
+    /// Find a group conversation by name.
+    pub fn find_group_by_name(&self, name: &str) -> anyhow::Result<Option<Conversation>> {
+        let id_blob: Option<Vec<u8>> = self
+            .conn
+            .query_row(
+                "SELECT id FROM conversations WHERE kind = 'group' AND group_name = ?1",
+                params![name],
+                |row| row.get(0),
+            )
+            .optional()?;
+
+        match id_blob {
+            Some(blob) => {
+                let id = ConversationId::from_slice(&blob)
+                    .context("invalid conversation id in db")?;
+                self.load_conversation(&id)
+            }
+            None => Ok(None),
+        }
+    }
+
+    pub fn increment_unread(&self, id: &ConversationId) -> anyhow::Result<()> {
+        self.conn.execute(
+            "UPDATE conversations SET unread_count = unread_count + 1 WHERE id = ?1",
+            params![id.0.as_slice()],
+        )?;
+        Ok(())
+    }
+
+    pub fn reset_unread(&self, id: &ConversationId) -> anyhow::Result<()> {
+        self.conn.execute(
+            "UPDATE conversations SET unread_count = 0 WHERE id = ?1",
+            params![id.0.as_slice()],
+        )?;
+        Ok(())
+    }
+
+    pub fn update_activity(&self, id: &ConversationId, ts_ms: u64) -> anyhow::Result<()> {
+        self.conn.execute(
+            "UPDATE conversations SET last_activity_ms = ?2 WHERE id = ?1 AND last_activity_ms < ?2",
+            params![id.0.as_slice(), ts_ms],
+        )?;
+        Ok(())
+    }
+
+    // ── Message CRUD ─────────────────────────────────────────────────────
+
+    pub fn save_message(&self, msg: &StoredMessage) -> anyhow::Result<()> {
+        self.conn.execute(
+            "INSERT INTO messages
+                (conversation_id, message_id, sender_key, sender_name, body,
+                 msg_type, ref_msg_id, timestamp_ms, is_outgoing)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
+            params![
+                msg.conversation_id.0.as_slice(),
+                msg.message_id.as_ref().map(|id| id.as_slice()),
+                msg.sender_key,
+                msg.sender_name,
+                msg.body,
+                msg.msg_type,
+                msg.ref_msg_id.as_ref().map(|id| id.as_slice()),
+                msg.timestamp_ms,
+                msg.is_outgoing as i32,
+            ],
+        )?;
+        Ok(())
+    }
+
+    pub fn load_recent_messages(
+        &self,
+        conv_id: &ConversationId,
+        limit: usize,
+    ) -> anyhow::Result<Vec<StoredMessage>> {
+        let mut stmt = self.conn.prepare(
+            "SELECT message_id, sender_key, sender_name, body, msg_type,
+                    ref_msg_id, timestamp_ms, is_outgoing
+             FROM messages
+             WHERE conversation_id = ?1
+             ORDER BY timestamp_ms DESC
+             LIMIT ?2",
+        )?;
+        let rows = stmt.query_map(params![conv_id.0.as_slice(), limit.min(u32::MAX as usize) as u32], |row| {
+            let message_id: Option<Vec<u8>> = row.get(0)?;
+            let sender_key: Vec<u8> = row.get(1)?;
+            let sender_name: Option<String> = row.get(2)?;
+            let body: String = row.get(3)?;
+            let msg_type: String = row.get(4)?;
+            let ref_msg_id: Option<Vec<u8>> = row.get(5)?;
+            let timestamp_ms: u64 = row.get(6)?;
+            let is_outgoing: i32 = row.get(7)?;
+
+            fn to_16(v: &[u8]) -> Option<[u8; 16]> {
+                if v.len() == 16 {
+                    let mut buf = [0u8; 16];
+                    buf.copy_from_slice(v);
+                    Some(buf)
+                } else {
+                    None
+                }
+            }
+
+            Ok(StoredMessage {
+                conversation_id: conv_id.clone(),
+                message_id: message_id.as_deref().and_then(to_16),
+                sender_key,
+                sender_name,
+                body,
+                msg_type,
+                ref_msg_id: ref_msg_id.as_deref().and_then(to_16),
+                timestamp_ms,
+                is_outgoing: is_outgoing != 0,
+            })
+        })?;
+
+        let mut msgs = Vec::new();
+        for row in rows {
+            msgs.push(row?);
+        }
+        // Reverse so oldest first
+        msgs.reverse();
+        Ok(msgs)
+    }
+
+    /// Load all messages for a conversation, oldest first (no limit).
+    pub fn load_all_messages(&self, conv_id: &ConversationId) -> anyhow::Result<Vec<StoredMessage>> {
+        let mut stmt = self.conn.prepare(
+            "SELECT message_id, sender_key, sender_name, body, msg_type,
+                    ref_msg_id, timestamp_ms, is_outgoing
+             FROM messages
+             WHERE conversation_id = ?1
+             ORDER BY timestamp_ms ASC, id ASC",
+        )?;
+        let rows = stmt.query_map(params![conv_id.0.as_slice()], |row| {
+            let message_id: Option<Vec<u8>> = row.get(0)?;
+            let sender_key: Vec<u8> = row.get(1)?;
+            let sender_name: Option<String> = row.get(2)?;
+            let body: String = row.get(3)?;
+            let msg_type: String = row.get(4)?;
+            let ref_msg_id: Option<Vec<u8>> = row.get(5)?;
+            let timestamp_ms: u64 = row.get(6)?;
+            let is_outgoing: i32 = row.get(7)?;
+
+            fn to_16(v: &[u8]) -> Option<[u8; 16]> {
+                if v.len() == 16 {
+                    let mut buf = [0u8; 16];
+                    buf.copy_from_slice(v);
+                    Some(buf)
+                } else {
+                    None
+                }
+            }
+
+            Ok(StoredMessage {
+                conversation_id: conv_id.clone(),
+                message_id: message_id.as_deref().and_then(to_16),
+                sender_key,
+                sender_name,
+                body,
+                msg_type,
+                ref_msg_id: ref_msg_id.as_deref().and_then(to_16),
+                timestamp_ms,
+                is_outgoing: is_outgoing != 0,
+            })
+        })?;
+
+        let mut msgs = Vec::new();
+        for row in rows {
+            msgs.push(row?);
+        }
+        Ok(msgs)
+    }
+
+    /// Update the body of an existing message (for edits).
+    pub fn update_message_body(
+        &self,
+        conv_id: &ConversationId,
+        message_id: &[u8; 16],
+        new_body: &str,
+    ) -> anyhow::Result<bool> {
+        let rows = self.conn.execute(
+            "UPDATE messages SET body = ?3 WHERE conversation_id = ?1 AND message_id = ?2",
+            params![conv_id.0.as_slice(), message_id.as_slice(), new_body],
+        )?;
+        Ok(rows > 0)
+    }
+
+    /// Mark a message as deleted (sets body to "[deleted]" and msg_type to "deleted").
+    pub fn delete_message(
+        &self,
+        conv_id: &ConversationId,
+        message_id: &[u8; 16],
+    ) -> anyhow::Result<bool> {
+        let rows = self.conn.execute(
+            "UPDATE messages SET body = '[deleted]', msg_type = 'deleted' WHERE conversation_id = ?1 AND message_id = ?2",
+            params![conv_id.0.as_slice(), message_id.as_slice()],
+        )?;
+        Ok(rows > 0)
+    }
+
+    /// Save a message, deduplicating by message_id within the same conversation.
+    /// Returns `true` if the message was saved (new), `false` if it was a duplicate.
+    pub fn save_message_dedup(&self, msg: &StoredMessage) -> anyhow::Result<bool> {
+        if let Some(ref mid) = msg.message_id {
+            let exists: bool = self.conn.query_row(
+                "SELECT EXISTS(SELECT 1 FROM messages WHERE message_id = ?1 AND conversation_id = ?2)",
+                params![mid.as_slice(), msg.conversation_id.0.as_slice()],
+                |row| row.get(0),
+            )?;
+            if exists {
+                return Ok(false);
+            }
+        }
+        self.save_message(msg)?;
+        Ok(true)
+    }
+
+    // ── Sequence tracking ──────────────────────────────────────────────
+
+    pub fn update_last_seen_seq(&self, id: &ConversationId, seq: u64) -> anyhow::Result<()> {
+        self.conn.execute(
+            "UPDATE conversations SET last_seen_seq = ?2 WHERE id = ?1 AND last_seen_seq < ?2",
+            params![id.0.as_slice(), seq as i64],
+        )?;
+        Ok(())
+    }
+
+    // ── Outbox (offline queue) ────────────────────────────────────────
+
+    pub fn enqueue_outbox(
+        &self,
+        conv_id: &ConversationId,
+        recipient_key: &[u8],
+        payload: &[u8],
+    ) -> anyhow::Result<()> {
+        self.conn.execute(
+            "INSERT INTO outbox (conversation_id, recipient_key, payload, created_at_ms)
+             VALUES (?1, ?2, ?3, ?4)",
+            params![conv_id.0.as_slice(), recipient_key, payload, now_ms() as i64],
+        )?;
+        Ok(())
+    }
+
+    pub fn load_pending_outbox(&self) -> anyhow::Result<Vec<OutboxEntry>> {
+        let mut stmt = self.conn.prepare(
+            "SELECT id, conversation_id, recipient_key, payload, retry_count
+             FROM outbox WHERE status = 'pending' ORDER BY created_at_ms",
+        )?;
+        let rows = stmt.query_map([], |row| {
+            let id: i64 = row.get(0)?;
+            let conv_blob: Vec<u8> = row.get(1)?;
+            let recipient_key: Vec<u8> = row.get(2)?;
+            let payload: Vec<u8> = row.get(3)?;
+            let retry_count: u32 = row.get(4)?;
+            Ok(OutboxEntry {
+                id,
+                conversation_id: ConversationId::from_slice(&conv_blob)
+                    .unwrap_or(ConversationId([0; 16])),
+                recipient_key,
+                payload,
+                retry_count,
+            })
+        })?;
+        let mut entries = Vec::new();
+        for row in rows {
+            entries.push(row?);
+        }
+        Ok(entries)
+    }
+
+    pub fn mark_outbox_sent(&self, id: i64) -> anyhow::Result<()> {
+        self.conn.execute(
+            "UPDATE outbox SET status = 'sent' WHERE id = ?1",
+            params![id],
+        )?;
+        Ok(())
+    }
+
+    pub fn mark_outbox_failed(&self, id: i64, retry_count: u32) -> anyhow::Result<()> {
+        let new_status = if retry_count > 5 { "failed" } else { "pending" };
+        self.conn.execute(
+            "UPDATE outbox SET retry_count = ?2, status = ?3 WHERE id = ?1",
+            params![id, retry_count, new_status],
+        )?;
+        Ok(())
+    }
+
+    /// Delete messages older than `cutoff_ms` (epoch milliseconds) across all conversations.
+    pub fn delete_messages_before(&self, cutoff_ms: u64) -> anyhow::Result<usize> {
+        let rows = self.conn.execute(
+            "DELETE FROM messages WHERE timestamp_ms < ?1",
+            params![cutoff_ms as i64],
+        )?;
+        Ok(rows)
+    }
+}
+
+/// An entry in the offline outbox queue.
+#[derive(Clone, Debug)]
+pub struct OutboxEntry {
+    pub id: i64,
+    pub conversation_id: ConversationId,
+    pub recipient_key: Vec<u8>,
+    pub payload: Vec<u8>,
+    pub retry_count: u32,
+}
+
+pub fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}

crates/quicprochat-client/src/client/display.rs

@@ -0,0 +1,82 @@
+//! Terminal display helpers for the REPL.
+
+use super::conversation::StoredMessage;
+use super::session::SessionState;
+
+// ANSI color codes
+const RESET: &str = "\x1b[0m";
+const BOLD: &str = "\x1b[1m";
+const DIM: &str = "\x1b[2m";
+const GREEN: &str = "\x1b[32m";
+const CYAN: &str = "\x1b[36m";
+const YELLOW: &str = "\x1b[33m";
+
+/// Print the REPL prompt showing the active conversation and unread count.
+pub fn print_prompt(session: &SessionState) {
+    use std::io::Write;
+    let name = session
+        .active_display_name()
+        .unwrap_or_else(|| "no conversation".into());
+    let unread = session.total_unread();
+    if unread > 0 {
+        print!("{DIM}[{RESET}{BOLD}{name}{RESET} {YELLOW}{unread} unread{RESET}{DIM}]{RESET} > ");
+    } else {
+        print!("{DIM}[{RESET}{BOLD}{name}{RESET}{DIM}]{RESET} > ");
+    }
+    let _ = std::io::stdout().flush();
+}
+
+/// Print an incoming or outgoing message.
+pub fn print_message(msg: &StoredMessage) {
+    let body = if msg.msg_type == "reaction" {
+        format!("reacted {}", msg.body)
+    } else {
+        msg.body.clone()
+    };
+    if msg.is_outgoing {
+        println!("\r{GREEN}> {body}{RESET}");
+    } else {
+        let fallback = hex::encode(&msg.sender_key[..4]);
+        let sender = msg.sender_name.as_deref().unwrap_or(&fallback);
+        println!("\r{CYAN}{BOLD}[{sender}]{RESET} {body}");
+    }
+}
+
+/// Print a message received in real-time (clears current line first).
+pub fn print_incoming(sender: &str, body: &str) {
+    use std::io::Write;
+    // Clear current line, print message, then re-show prompt context
+    print!("\r\x1b[2K");
+    println!("{CYAN}{BOLD}[{sender}]{RESET} {body}");
+    let _ = std::io::stdout().flush();
+}
+
+/// Print a system/status message.
+pub fn print_status(msg: &str) {
+    println!("{DIM}  {msg}{RESET}");
+}
+
+/// Print a transient typing indicator (clears current line first).
+pub fn print_typing(sender: &str) {
+    use std::io::Write;
+    print!("\r\x1b[2K");
+    println!("{DIM}  {sender} is typing...{RESET}");
+    let _ = std::io::stdout().flush();
+}
+
+/// Print an error message.
+pub fn print_error(msg: &str) {
+    println!("{YELLOW}  error: {msg}{RESET}");
+}
+
+/// Format a conversation list entry for `/list`.
+pub fn format_conv_line(display_name: &str, kind: &str, unread: u32, members: usize) -> String {
+    let unread_str = if unread > 0 {
+        format!(" {YELLOW}({unread} new){RESET}")
+    } else {
+        String::new()
+    };
+    format!(
+        "  {BOLD}{display_name}{RESET} {DIM}[{kind}, {members} members]{RESET}{unread_str}"
+    )
+}

crates/quicprochat-client/src/client/hex.rs

@@ -0,0 +1,7 @@
+pub fn encode(bytes: impl AsRef<[u8]>) -> String {
+    hex::encode(bytes)
+}
+
+pub fn decode(s: &str) -> Result<Vec<u8>, &'static str> {
+    hex::decode(s).map_err(|_| "invalid hex string")
+}

crates/quicprochat-client/src/client/mesh_discovery.rs

@@ -0,0 +1,148 @@
+//! mDNS-based peer discovery for Freifunk / community mesh deployments.
+//!
+//! Browse for `_quicprochat._udp.local.` services on the local network and
+//! surface them as [`DiscoveredPeer`] structs. Servers announce themselves
+//! automatically on startup; this module lets clients find them without manual
+//! configuration.
+//!
+//! # Usage
+//!
+//! ```no_run
+//! use quicprochat_client::client::mesh_discovery::MeshDiscovery;
+//!
+//! let disc = MeshDiscovery::start()?;
+//! // Give mDNS time to collect announcements before reading.
+//! std::thread::sleep(std::time::Duration::from_secs(2));
+//! for peer in disc.peers() {
+//!     println!("found: {} at {}", peer.domain, peer.server_addr);
+//! }
+//! # Ok::<(), quicprochat_client::client::mesh_discovery::MeshDiscoveryError>(())
+//! ```
+
+#[cfg(feature = "mesh")]
+use mdns_sd::{ServiceDaemon, ServiceEvent};
+use std::net::SocketAddr;
+#[cfg(feature = "mesh")]
+use std::sync::{Arc, Mutex};
+#[cfg(feature = "mesh")]
+use std::collections::HashMap;
+
+/// A qpc server discovered on the local network via mDNS.
+#[derive(Debug, Clone)]
+pub struct DiscoveredPeer {
+    /// Federation domain of the remote server (e.g. `"node1.freifunk.net"`).
+    pub domain: String,
+    /// QUIC RPC address to connect to.
+    pub server_addr: SocketAddr,
+}
+
+/// A running mDNS browse session.
+///
+/// Starts immediately on construction; drop to stop browsing.
+pub struct MeshDiscovery {
+    #[cfg(feature = "mesh")]
+    _daemon: ServiceDaemon,
+    #[cfg(feature = "mesh")]
+    peers: Arc<Mutex<HashMap<String, DiscoveredPeer>>>,
+}
+
+#[derive(thiserror::Error, Debug)]
+pub enum MeshDiscoveryError {
+    #[error("mDNS daemon failed to start: {0}")]
+    DaemonError(String),
+    #[error("mDNS browse failed: {0}")]
+    BrowseError(String),
+    #[error("mesh feature not compiled (rebuild with --features mesh)")]
+    FeatureDisabled,
+}
+
+impl MeshDiscovery {
+    /// Start browsing for `_quicprochat._udp.local.` services.
+    ///
+    /// Returns immediately; peers are collected in the background.
+    /// Returns [`MeshDiscoveryError::FeatureDisabled`] when built without the
+    /// `mesh` feature.
+    pub fn start() -> Result<Self, MeshDiscoveryError> {
+        #[cfg(feature = "mesh")]
+        {
+            Self::start_inner()
+        }
+        #[cfg(not(feature = "mesh"))]
+        {
+            Err(MeshDiscoveryError::FeatureDisabled)
+        }
+    }
+
+    #[cfg(feature = "mesh")]
+    fn start_inner() -> Result<Self, MeshDiscoveryError> {
+        let daemon = ServiceDaemon::new()
+            .map_err(|e| MeshDiscoveryError::DaemonError(e.to_string()))?;
+
+        let receiver = daemon
+            .browse("_quicprochat._udp.local.")
+            .map_err(|e| MeshDiscoveryError::BrowseError(e.to_string()))?;
+
+        let peers: Arc<Mutex<HashMap<String, DiscoveredPeer>>> =
+            Arc::new(Mutex::new(HashMap::new()));
+        let peers_bg = Arc::clone(&peers);
+
+        // Process mDNS events in a background thread (ServiceDaemon is sync).
+        std::thread::spawn(move || {
+            for event in receiver {
+                match event {
+                    ServiceEvent::ServiceResolved(info) => {
+                        // Extract the qpc server address from TXT records.
+                        let server_addr_str = info
+                            .get_property_val_str("server")
+                            .map(|s| s.to_string());
+                        let domain = info
+                            .get_property_val_str("domain")
+                            .map(|s| s.to_string())
+                            .unwrap_or_else(|| info.get_fullname().to_string());
+
+                        if let Some(addr_str) = server_addr_str {
+                            if let Ok(addr) = addr_str.parse::<SocketAddr>() {
+                                let peer = DiscoveredPeer {
+                                    domain: domain.clone(),
+                                    server_addr: addr,
+                                };
+                                if let Ok(mut map) = peers_bg.lock() {
+                                    map.insert(domain, peer);
+                                }
+                            }
+                        }
+                    }
+                    ServiceEvent::ServiceRemoved(_ty, fullname) => {
+                        if let Ok(mut map) = peers_bg.lock() {
+                            map.retain(|_, p| {
+                                !fullname.contains(&p.domain)
+                            });
+                        }
+                    }
+                    // Other events (SearchStarted, SearchStopped) are informational.
+                    _ => {}
+                }
+            }
+        });
+
+        Ok(Self {
+            _daemon: daemon,
+            peers,
+        })
+    }
+
+    /// Return a snapshot of all peers discovered so far.
+    pub fn peers(&self) -> Vec<DiscoveredPeer> {
+        #[cfg(feature = "mesh")]
+        {
+            self.peers
+                .lock()
+                .map(|m| m.values().cloned().collect())
+                .unwrap_or_default()
+        }
+        #[cfg(not(feature = "mesh"))]
+        {
+            vec![]
+        }
+    }
+}

crates/quicprochat-client/src/client/mod.rs

@@ -0,0 +1,24 @@
+pub mod command_engine;
+pub mod commands;
+pub mod conversation;
+pub mod display;
+pub mod hex;
+pub mod mesh_discovery;
+#[cfg(feature = "playbook")]
+pub mod playbook;
+pub mod repl;
+pub mod retry;
+pub mod rpc;
+pub mod session;
+pub mod state;
+pub mod token_cache;
+#[cfg(feature = "tui")]
+pub mod tui;
+#[cfg(feature = "v2")]
+pub mod v2_repl;
+#[cfg(all(feature = "v2", feature = "tui"))]
+pub mod v2_tui;
+
+pub use commands::*;
+pub use rpc::{connect_node, enqueue, fetch_all, fetch_hybrid_key, fetch_key_package, fetch_wait, upload_hybrid_key, upload_key_package};
+pub use state::{decode_identity_key, load_existing_state, load_or_init_state, save_state};

crates/quicprochat-client/src/client/playbook.rs

@@ -0,0 +1,868 @@
+//! YAML playbook parser and executor.
+//!
+//! Playbooks describe a sequence of client commands in YAML format.
+//! They support variable substitution, assertions, loops, and per-step
+//! error handling policies.
+//!
+//! ```yaml
+//! name: "smoke test"
+//! steps:
+//!   - command: dm
+//!     args: { username: "bob" }
+//!   - command: send
+//!     args: { text: "Hello from playbook" }
+//!   - command: assert
+//!     condition: message_count
+//!     op: gte
+//!     value: 1
+//! ```
+//!
+//! Requires the `playbook` cargo feature.
+
+use std::collections::HashMap;
+use std::path::Path;
+use std::time::{Duration, Instant};
+
+use anyhow::{Context, bail};
+use quicprochat_proto::node_capnp::node_service;
+use serde::{Deserialize, Serialize};
+
+use super::command_engine::{AssertCondition, CmpOp, Command, CommandRegistry};
+use super::session::SessionState;
+
+// ── Playbook structs ────────────────────────────────────────────────────────
+
+/// A parsed YAML playbook.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Playbook {
+    pub name: String,
+    #[serde(default)]
+    pub description: Option<String>,
+    #[serde(default)]
+    pub variables: HashMap<String, String>,
+    pub steps: Vec<PlaybookStep>,
+}
+
+/// A single step in a playbook.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PlaybookStep {
+    pub command: String,
+    #[serde(default)]
+    pub args: HashMap<String, serde_yaml::Value>,
+    /// For assert steps: the condition name.
+    #[serde(default)]
+    pub condition: Option<String>,
+    /// For assert steps: comparison operator.
+    #[serde(default)]
+    pub op: Option<String>,
+    /// For assert steps: expected value.
+    #[serde(default)]
+    pub value: Option<serde_yaml::Value>,
+    /// Capture the command output into this variable name.
+    #[serde(default)]
+    pub capture: Option<String>,
+    /// Error handling policy for this step.
+    #[serde(default)]
+    pub on_error: OnError,
+    /// Optional loop specification.
+    #[serde(rename = "loop", default)]
+    pub loop_spec: Option<LoopSpec>,
+}
+
+/// What to do when a step fails.
+#[derive(Debug, Clone, Serialize, Deserialize, Default, PartialEq)]
+#[serde(rename_all = "lowercase")]
+pub enum OnError {
+    #[default]
+    Fail,
+    Skip,
+    Continue,
+}
+
+/// Loop specification for repeating a step.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LoopSpec {
+    pub var: String,
+    pub from: usize,
+    pub to: usize,
+}
+
+// ── Report structs ──────────────────────────────────────────────────────────
+
+/// Summary of a playbook execution.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PlaybookReport {
+    pub name: String,
+    pub total_steps: usize,
+    pub passed: usize,
+    pub failed: usize,
+    pub skipped: usize,
+    pub duration: Duration,
+    pub step_results: Vec<StepResult>,
+}
+
+impl PlaybookReport {
+    /// True if all steps passed (no failures).
+    pub fn all_passed(&self) -> bool {
+        self.failed == 0
+    }
+}
+
+impl std::fmt::Display for PlaybookReport {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        writeln!(f, "Playbook: {}", self.name)?;
+        writeln!(
+            f,
+            "Result:   {} passed, {} failed, {} skipped ({} total)",
+            self.passed, self.failed, self.skipped, self.total_steps,
+        )?;
+        writeln!(f, "Duration: {:.2}s", self.duration.as_secs_f64())?;
+        for sr in &self.step_results {
+            let status = if sr.success { "OK" } else { "FAIL" };
+            write!(
+                f,
+                "  [{}/{}] {} ... {} ({:.1}ms)",
+                sr.step_index + 1,
+                self.total_steps,
+                sr.command,
+                status,
+                sr.duration.as_secs_f64() * 1000.0,
+            )?;
+            if let Some(ref e) = sr.error {
+                write!(f, " — {e}")?;
+            }
+            writeln!(f)?;
+        }
+        Ok(())
+    }
+}
+
+/// Result of a single step execution.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StepResult {
+    pub step_index: usize,
+    pub command: String,
+    pub success: bool,
+    pub duration: Duration,
+    pub output: Option<String>,
+    pub error: Option<String>,
+}
+
+// ── PlaybookRunner ──────────────────────────────────────────────────────────
+
+/// Executes a parsed `Playbook` step-by-step.
+pub struct PlaybookRunner {
+    playbook: Playbook,
+    vars: HashMap<String, String>,
+}
+
+impl PlaybookRunner {
+    /// Load a playbook from a YAML file.
+    pub fn from_file(path: &Path) -> anyhow::Result<Self> {
+        let content =
+            std::fs::read_to_string(path).with_context(|| format!("read {}", path.display()))?;
+        Self::from_str(&content)
+    }
+
+    /// Parse a playbook from a YAML string.
+    pub fn from_str(yaml: &str) -> anyhow::Result<Self> {
+        let playbook: Playbook =
+            serde_yaml::from_str(yaml).context("parse playbook YAML")?;
+        let vars = playbook.variables.clone();
+        Ok(Self { playbook, vars })
+    }
+
+    /// Override or add variables before execution.
+    pub fn set_var(&mut self, name: impl Into<String>, value: impl Into<String>) {
+        self.vars.insert(name.into(), value.into());
+    }
+
+    /// Execute all steps, returning a report.
+    pub async fn run(
+        &mut self,
+        session: &mut SessionState,
+        client: &node_service::Client,
+    ) -> PlaybookReport {
+        let start = Instant::now();
+        let total = self.expanded_step_count();
+        let mut results = Vec::new();
+        let mut passed = 0usize;
+        let mut failed = 0usize;
+        let mut skipped = 0usize;
+        let mut step_idx = 0usize;
+        let mut abort = false;
+
+        for step in &self.playbook.steps.clone() {
+            if abort {
+                skipped += 1;
+                results.push(StepResult {
+                    step_index: step_idx,
+                    command: step.command.clone(),
+                    success: false,
+                    duration: Duration::ZERO,
+                    output: None,
+                    error: Some("skipped (prior failure)".into()),
+                });
+                step_idx += 1;
+                continue;
+            }
+
+            if let Some(ref ls) = step.loop_spec {
+                for i in ls.from..=ls.to {
+                    self.vars.insert(ls.var.clone(), i.to_string());
+                    let sr = self.execute_step(step, step_idx, total, session, client).await;
+                    if sr.success {
+                        passed += 1;
+                    } else {
+                        failed += 1;
+                        if step.on_error == OnError::Fail {
+                            abort = true;
+                        }
+                    }
+                    results.push(sr);
+                    step_idx += 1;
+                    if abort {
+                        break;
+                    }
+                }
+            } else {
+                let sr = self.execute_step(step, step_idx, total, session, client).await;
+                if sr.success {
+                    passed += 1;
+                } else {
+                    match step.on_error {
+                        OnError::Fail => {
+                            failed += 1;
+                            abort = true;
+                        }
+                        OnError::Skip => skipped += 1,
+                        OnError::Continue => failed += 1,
+                    }
+                }
+                results.push(sr);
+                step_idx += 1;
+            }
+        }
+
+        PlaybookReport {
+            name: self.playbook.name.clone(),
+            total_steps: step_idx,
+            passed,
+            failed,
+            skipped,
+            duration: start.elapsed(),
+            step_results: results,
+        }
+    }
+
+    /// Execute a single step.
+    async fn execute_step(
+        &mut self,
+        step: &PlaybookStep,
+        index: usize,
+        total: usize,
+        session: &mut SessionState,
+        client: &node_service::Client,
+    ) -> StepResult {
+        let t = Instant::now();
+        let cmd = match self.step_to_command(step) {
+            Ok(c) => c,
+            Err(e) => {
+                return StepResult {
+                    step_index: index,
+                    command: step.command.clone(),
+                    success: false,
+                    duration: t.elapsed(),
+                    output: None,
+                    error: Some(format!("{e:#}")),
+                };
+            }
+        };
+
+        eprintln!(
+            "[{}/{}] {} ...",
+            index + 1,
+            total,
+            step.command,
+        );
+
+        let cr = CommandRegistry::execute(&cmd, session, client).await;
+
+        // Capture output into variable if requested.
+        if let Some(ref var_name) = step.capture {
+            if let Some(ref out) = cr.output {
+                self.vars.insert(var_name.clone(), out.clone());
+            }
+            for (k, v) in &cr.data {
+                self.vars.insert(format!("{var_name}.{k}"), v.clone());
+            }
+        }
+
+        StepResult {
+            step_index: index,
+            command: step.command.clone(),
+            success: cr.success,
+            duration: t.elapsed(),
+            output: cr.output,
+            error: cr.error,
+        }
+    }
+
+    /// Convert a YAML step into a typed `Command`.
+    fn step_to_command(&self, step: &PlaybookStep) -> anyhow::Result<Command> {
+        let cmd_name = step.command.as_str();
+        match cmd_name {
+            // ── Lifecycle commands ────────────────────────────────────────
+            "connect" => Ok(Command::Connect {
+                server: self.resolve_str(&step.args, "server")?,
+                ca_cert: self.opt_str(&step.args, "ca_cert"),
+                insecure: self.opt_bool(&step.args, "insecure"),
+            }),
+            "login" => Ok(Command::Login {
+                username: self.resolve_str(&step.args, "username")?,
+                password: self.resolve_str(&step.args, "password")?,
+            }),
+            "register" => Ok(Command::Register {
+                username: self.resolve_str(&step.args, "username")?,
+                password: self.resolve_str(&step.args, "password")?,
+            }),
+            "send" | "send-message" => Ok(Command::SendMessage {
+                text: self.resolve_str(&step.args, "text")?,
+            }),
+            "wait" => Ok(Command::Wait {
+                duration_ms: self.resolve_u64(&step.args, "duration_ms")?,
+            }),
+            "set-var" | "setvar" => Ok(Command::SetVar {
+                name: self.resolve_str(&step.args, "name")?,
+                value: self.resolve_str(&step.args, "value")?,
+            }),
+            "assert" => {
+                let condition = self.build_assert_condition(step)?;
+                Ok(Command::Assert { condition })
+            }
+
+            // ── Session / identity ───────────────────────────────────────
+            "help" => Ok(Command::Help),
+            "quit" | "exit" => Ok(Command::Quit),
+            "whoami" => Ok(Command::Whoami),
+            "list" | "ls" => Ok(Command::List),
+            "switch" | "sw" => Ok(Command::Switch {
+                target: self.resolve_str(&step.args, "target")?,
+            }),
+            "dm" => Ok(Command::Dm {
+                username: self.resolve_str(&step.args, "username")?,
+            }),
+            "create-group" | "cg" => Ok(Command::CreateGroup {
+                name: self.resolve_str(&step.args, "name")?,
+            }),
+            "invite" => Ok(Command::Invite {
+                target: self.resolve_str(&step.args, "target")?,
+            }),
+            "remove" | "kick" => Ok(Command::Remove {
+                target: self.resolve_str(&step.args, "target")?,
+            }),
+            "leave" => Ok(Command::Leave),
+            "join" => Ok(Command::Join),
+            "members" => Ok(Command::Members),
+            "group-info" | "gi" => Ok(Command::GroupInfo),
+            "rename" => Ok(Command::Rename {
+                name: self.resolve_str(&step.args, "name")?,
+            }),
+            "history" | "hist" => Ok(Command::History {
+                count: self.opt_usize(&step.args, "count").unwrap_or(20),
+            }),
+
+            // ── Security / crypto ────────────────────────────────────────
+            "verify" => Ok(Command::Verify {
+                username: self.resolve_str(&step.args, "username")?,
+            }),
+            "update-key" | "rotate-key" => Ok(Command::UpdateKey),
+            "typing" => Ok(Command::Typing),
+            "typing-notify" => Ok(Command::TypingNotify {
+                enabled: self.opt_bool(&step.args, "enabled"),
+            }),
+            "react" => Ok(Command::React {
+                emoji: self.resolve_str(&step.args, "emoji")?,
+                index: self.opt_usize(&step.args, "index"),
+            }),
+            "edit" => Ok(Command::Edit {
+                index: self.resolve_usize(&step.args, "index")?,
+                new_text: self.resolve_str(&step.args, "new_text")?,
+            }),
+            "delete" | "del" => Ok(Command::Delete {
+                index: self.resolve_usize(&step.args, "index")?,
+            }),
+            "send-file" | "sf" => Ok(Command::SendFile {
+                path: self.resolve_str(&step.args, "path")?,
+            }),
+            "download" | "dl" => Ok(Command::Download {
+                index: self.resolve_usize(&step.args, "index")?,
+            }),
+            "delete-account" => Ok(Command::DeleteAccount),
+            "disappear" => Ok(Command::Disappear {
+                arg: self.opt_str(&step.args, "duration"),
+            }),
+            "privacy" => Ok(Command::Privacy {
+                arg: self.opt_str(&step.args, "setting"),
+            }),
+            "verify-fs" => Ok(Command::VerifyFs),
+            "rotate-all-keys" => Ok(Command::RotateAllKeys),
+            "devices" => Ok(Command::Devices),
+            "register-device" => Ok(Command::RegisterDevice {
+                name: self.resolve_str(&step.args, "name")?,
+            }),
+            "revoke-device" => Ok(Command::RevokeDevice {
+                id_prefix: self.resolve_str(&step.args, "id_prefix")?,
+            }),
+
+            // ── Mesh ─────────────────────────────────────────────────────
+            "mesh-peers" => Ok(Command::MeshPeers),
+            "mesh-server" => Ok(Command::MeshServer {
+                addr: self.resolve_str(&step.args, "addr")?,
+            }),
+            "mesh-send" => Ok(Command::MeshSend {
+                peer_id: self.resolve_str(&step.args, "peer_id")?,
+                message: self.resolve_str(&step.args, "message")?,
+            }),
+            "mesh-broadcast" => Ok(Command::MeshBroadcast {
+                topic: self.resolve_str(&step.args, "topic")?,
+                message: self.resolve_str(&step.args, "message")?,
+            }),
+            "mesh-subscribe" => Ok(Command::MeshSubscribe {
+                topic: self.resolve_str(&step.args, "topic")?,
+            }),
+            "mesh-route" => Ok(Command::MeshRoute),
+            "mesh-identity" | "mesh-id" => Ok(Command::MeshIdentity),
+            "mesh-store" => Ok(Command::MeshStore),
+
+            other => bail!("unknown command: {other}"),
+        }
+    }
+
+    /// Build an `AssertCondition` from a playbook step.
+    fn build_assert_condition(&self, step: &PlaybookStep) -> anyhow::Result<AssertCondition> {
+        let cond = step
+            .condition
+            .as_deref()
+            .context("assert step requires 'condition' field")?;
+        match cond {
+            "connected" => Ok(AssertCondition::Connected),
+            "logged_in" => Ok(AssertCondition::LoggedIn),
+            "in_conversation" => {
+                let name = self.resolve_str(&step.args, "name")
+                    .or_else(|_| step.value.as_ref()
+                        .and_then(|v| v.as_str())
+                        .map(|s| self.substitute(s))
+                        .context("assert in_conversation requires 'name' arg or 'value'"))?;
+                Ok(AssertCondition::InConversation { name })
+            }
+            "message_count" => {
+                let op = self.parse_cmp_op(step.op.as_deref().unwrap_or("gte"))?;
+                let count = step
+                    .value
+                    .as_ref()
+                    .and_then(|v| v.as_u64())
+                    .context("message_count assert requires numeric 'value'")?
+                    as usize;
+                Ok(AssertCondition::MessageCount { op, count })
+            }
+            "member_count" => {
+                let op = self.parse_cmp_op(step.op.as_deref().unwrap_or("gte"))?;
+                let count = step
+                    .value
+                    .as_ref()
+                    .and_then(|v| v.as_u64())
+                    .context("member_count assert requires numeric 'value'")?
+                    as usize;
+                Ok(AssertCondition::MemberCount { op, count })
+            }
+            other => Ok(AssertCondition::Custom {
+                expression: other.to_string(),
+            }),
+        }
+    }
+
+    fn parse_cmp_op(&self, s: &str) -> anyhow::Result<CmpOp> {
+        match s {
+            "eq" | "==" => Ok(CmpOp::Eq),
+            "ne" | "!=" => Ok(CmpOp::Ne),
+            "gt" | ">" => Ok(CmpOp::Gt),
+            "lt" | "<" => Ok(CmpOp::Lt),
+            "gte" | ">=" => Ok(CmpOp::Gte),
+            "lte" | "<=" => Ok(CmpOp::Lte),
+            other => bail!("unknown comparison operator: {other}"),
+        }
+    }
+
+    // ── Variable substitution helpers ────────────────────────────────────
+
+    /// Substitute `$varname` and `${VAR:-default}` in a string.
+    fn substitute(&self, s: &str) -> String {
+        let mut result = String::with_capacity(s.len());
+        let mut chars = s.chars().peekable();
+        while let Some(c) = chars.next() {
+            if c == '$' {
+                if chars.peek() == Some(&'{') {
+                    chars.next(); // consume '{'
+                    let mut key = String::new();
+                    let mut default = None;
+                    while let Some(&ch) = chars.peek() {
+                        if ch == '}' {
+                            chars.next();
+                            break;
+                        }
+                        if ch == ':' && chars.clone().nth(1) == Some('-') {
+                            chars.next(); // consume ':'
+                            chars.next(); // consume '-'
+                            let mut def = String::new();
+                            while let Some(&dch) = chars.peek() {
+                                if dch == '}' {
+                                    chars.next();
+                                    break;
+                                }
+                                def.push(dch);
+                                chars.next();
+                            }
+                            default = Some(def);
+                            break;
+                        }
+                        key.push(ch);
+                        chars.next();
+                    }
+                    if let Some(val) = self.vars.get(&key) {
+                        result.push_str(val);
+                    } else if let Ok(val) = std::env::var(&key) {
+                        result.push_str(&val);
+                    } else if let Some(def) = default {
+                        result.push_str(&def);
+                    }
+                } else {
+                    let mut key = String::new();
+                    while let Some(&ch) = chars.peek() {
+                        if ch.is_alphanumeric() || ch == '_' {
+                            key.push(ch);
+                            chars.next();
+                        } else {
+                            break;
+                        }
+                    }
+                    if let Some(val) = self.vars.get(&key) {
+                        result.push_str(val);
+                    } else {
+                        result.push('$');
+                        result.push_str(&key);
+                    }
+                }
+            } else {
+                result.push(c);
+            }
+        }
+        result
+    }
+
+    /// Resolve a required string argument with variable substitution.
+    fn resolve_str(
+        &self,
+        args: &HashMap<String, serde_yaml::Value>,
+        key: &str,
+    ) -> anyhow::Result<String> {
+        let val = args
+            .get(key)
+            .with_context(|| format!("missing required argument: {key}"))?;
+        match val {
+            serde_yaml::Value::String(s) => Ok(self.substitute(s)),
+            serde_yaml::Value::Number(n) => Ok(n.to_string()),
+            serde_yaml::Value::Bool(b) => Ok(b.to_string()),
+            other => Ok(format!("{other:?}")),
+        }
+    }
+
+    /// Resolve an optional string argument.
+    fn opt_str(
+        &self,
+        args: &HashMap<String, serde_yaml::Value>,
+        key: &str,
+    ) -> Option<String> {
+        args.get(key).map(|v| match v {
+            serde_yaml::Value::String(s) => self.substitute(s),
+            serde_yaml::Value::Number(n) => n.to_string(),
+            serde_yaml::Value::Bool(b) => b.to_string(),
+            other => format!("{other:?}"),
+        })
+    }
+
+    /// Resolve an optional bool argument (defaults to false).
+    fn opt_bool(
+        &self,
+        args: &HashMap<String, serde_yaml::Value>,
+        key: &str,
+    ) -> bool {
+        args.get(key)
+            .and_then(|v| v.as_bool())
+            .unwrap_or(false)
+    }
+
+    /// Resolve a required usize argument.
+    fn resolve_usize(
+        &self,
+        args: &HashMap<String, serde_yaml::Value>,
+        key: &str,
+    ) -> anyhow::Result<usize> {
+        let val = args
+            .get(key)
+            .with_context(|| format!("missing required argument: {key}"))?;
+        val.as_u64()
+            .map(|n| n as usize)
+            .with_context(|| format!("argument '{key}' must be a positive integer"))
+    }
+
+    /// Resolve a required u64 argument.
+    fn resolve_u64(
+        &self,
+        args: &HashMap<String, serde_yaml::Value>,
+        key: &str,
+    ) -> anyhow::Result<u64> {
+        let val = args
+            .get(key)
+            .with_context(|| format!("missing required argument: {key}"))?;
+        val.as_u64()
+            .with_context(|| format!("argument '{key}' must be a positive integer"))
+    }
+
+    /// Resolve an optional usize argument.
+    fn opt_usize(
+        &self,
+        args: &HashMap<String, serde_yaml::Value>,
+        key: &str,
+    ) -> Option<usize> {
+        args.get(key).and_then(|v| v.as_u64()).map(|n| n as usize)
+    }
+
+    /// Count total expanded steps (including loop iterations).
+    fn expanded_step_count(&self) -> usize {
+        self.playbook
+            .steps
+            .iter()
+            .map(|s| {
+                if let Some(ref ls) = s.loop_spec {
+                    if ls.to >= ls.from {
+                        ls.to - ls.from + 1
+                    } else {
+                        0
+                    }
+                } else {
+                    1
+                }
+            })
+            .sum()
+    }
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_minimal_playbook() {
+        let yaml = r#"
+name: "test"
+steps:
+  - command: whoami
+  - command: list
+"#;
+        let runner = PlaybookRunner::from_str(yaml).unwrap();
+        assert_eq!(runner.playbook.name, "test");
+        assert_eq!(runner.playbook.steps.len(), 2);
+        assert_eq!(runner.playbook.steps[0].command, "whoami");
+    }
+
+    #[test]
+    fn parse_playbook_with_variables() {
+        let yaml = r#"
+name: "var test"
+variables:
+  user: alice
+  server: "127.0.0.1:5001"
+steps:
+  - command: dm
+    args:
+      username: "$user"
+"#;
+        let runner = PlaybookRunner::from_str(yaml).unwrap();
+        assert_eq!(runner.vars["user"], "alice");
+        assert_eq!(runner.vars["server"], "127.0.0.1:5001");
+    }
+
+    #[test]
+    fn variable_substitution() {
+        let mut vars = HashMap::new();
+        vars.insert("name".to_string(), "alice".to_string());
+        vars.insert("port".to_string(), "5001".to_string());
+        let runner = PlaybookRunner {
+            playbook: Playbook {
+                name: "test".into(),
+                description: None,
+                variables: HashMap::new(),
+                steps: vec![],
+            },
+            vars,
+        };
+        assert_eq!(runner.substitute("hello $name"), "hello alice");
+        assert_eq!(runner.substitute("port=$port!"), "port=5001!");
+        assert_eq!(runner.substitute("${name}@server"), "alice@server");
+        assert_eq!(
+            runner.substitute("${missing:-default}"),
+            "default"
+        );
+        assert_eq!(runner.substitute("no vars here"), "no vars here");
+    }
+
+    #[test]
+    fn step_to_command_mapping() {
+        let yaml = r#"
+name: "mapping test"
+variables:
+  user: bob
+steps:
+  - command: dm
+    args:
+      username: "$user"
+  - command: send
+    args:
+      text: "hello"
+  - command: history
+    args:
+      count: 10
+  - command: wait
+    args:
+      duration_ms: 500
+"#;
+        let runner = PlaybookRunner::from_str(yaml).unwrap();
+        let cmd0 = runner.step_to_command(&runner.playbook.steps[0]).unwrap();
+        assert!(matches!(cmd0, Command::Dm { username } if username == "bob"));
+
+        let cmd1 = runner.step_to_command(&runner.playbook.steps[1]).unwrap();
+        assert!(matches!(cmd1, Command::SendMessage { text } if text == "hello"));
+
+        let cmd2 = runner.step_to_command(&runner.playbook.steps[2]).unwrap();
+        assert!(matches!(cmd2, Command::History { count: 10 }));
+
+        let cmd3 = runner.step_to_command(&runner.playbook.steps[3]).unwrap();
+        assert!(matches!(cmd3, Command::Wait { duration_ms: 500 }));
+    }
+
+    #[test]
+    fn parse_assert_step() {
+        let yaml = r#"
+name: "assert test"
+steps:
+  - command: assert
+    condition: message_count
+    op: gte
+    value: 5
+"#;
+        let runner = PlaybookRunner::from_str(yaml).unwrap();
+        let cmd = runner.step_to_command(&runner.playbook.steps[0]).unwrap();
+        match cmd {
+            Command::Assert {
+                condition: AssertCondition::MessageCount { op, count },
+            } => {
+                assert_eq!(op, CmpOp::Gte);
+                assert_eq!(count, 5);
+            }
+            other => panic!("expected Assert MessageCount, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn parse_loop_spec() {
+        let yaml = r#"
+name: "loop test"
+steps:
+  - command: send
+    args:
+      text: "msg $i"
+    loop:
+      var: i
+      from: 1
+      to: 5
+"#;
+        let runner = PlaybookRunner::from_str(yaml).unwrap();
+        assert_eq!(runner.expanded_step_count(), 5);
+        let ls = runner.playbook.steps[0].loop_spec.as_ref().unwrap();
+        assert_eq!(ls.var, "i");
+        assert_eq!(ls.from, 1);
+        assert_eq!(ls.to, 5);
+    }
+
+    #[test]
+    fn on_error_defaults_to_fail() {
+        let yaml = r#"
+name: "error test"
+steps:
+  - command: whoami
+  - command: list
+    on_error: continue
+  - command: quit
+    on_error: skip
+"#;
+        let runner = PlaybookRunner::from_str(yaml).unwrap();
+        assert_eq!(runner.playbook.steps[0].on_error, OnError::Fail);
+        assert_eq!(runner.playbook.steps[1].on_error, OnError::Continue);
+        assert_eq!(runner.playbook.steps[2].on_error, OnError::Skip);
+    }
+
+    #[test]
+    fn cmp_op_parsing() {
+        let runner = PlaybookRunner::from_str("name: t\nsteps: []").unwrap();
+        assert!(matches!(runner.parse_cmp_op("eq"), Ok(CmpOp::Eq)));
+        assert!(matches!(runner.parse_cmp_op("=="), Ok(CmpOp::Eq)));
+        assert!(matches!(runner.parse_cmp_op("gte"), Ok(CmpOp::Gte)));
+        assert!(matches!(runner.parse_cmp_op(">="), Ok(CmpOp::Gte)));
+        assert!(matches!(runner.parse_cmp_op("<"), Ok(CmpOp::Lt)));
+        assert!(runner.parse_cmp_op("invalid").is_err());
+    }
+
+    #[test]
+    fn report_display() {
+        let report = PlaybookReport {
+            name: "test".into(),
+            total_steps: 3,
+            passed: 2,
+            failed: 1,
+            skipped: 0,
+            duration: Duration::from_millis(150),
+            step_results: vec![
+                StepResult {
+                    step_index: 0,
+                    command: "whoami".into(),
+                    success: true,
+                    duration: Duration::from_millis(10),
+                    output: None,
+                    error: None,
+                },
+                StepResult {
+                    step_index: 1,
+                    command: "dm".into(),
+                    success: true,
+                    duration: Duration::from_millis(50),
+                    output: None,
+                    error: None,
+                },
+                StepResult {
+                    step_index: 2,
+                    command: "assert".into(),
+                    success: false,
+                    duration: Duration::from_millis(1),
+                    output: None,
+                    error: Some("message count 0 < 1".into()),
+                },
+            ],
+        };
+        let s = format!("{report}");
+        assert!(s.contains("2 passed, 1 failed"));
+        assert!(s.contains("[3/3] assert ... FAIL"));
+    }
+}

crates/quicprochat-client/src/client/retry.rs

@@ -0,0 +1,207 @@
+//! Retry with exponential backoff for transient RPC failures.
+
+use std::future::Future;
+use std::time::Duration;
+
+use rand::Rng;
+use tracing::warn;
+
+/// Default maximum number of retry attempts (including the first try).
+pub const DEFAULT_MAX_RETRIES: u32 = 3;
+/// Default base delay in milliseconds for exponential backoff.
+pub const DEFAULT_BASE_DELAY_MS: u64 = 500;
+
+/// Runs an async operation with retries. On `Ok(t)` returns immediately.
+/// On `Err(e)`: if `is_retriable(&e)` and `attempt < max_retries`, sleeps with
+/// exponential backoff (plus jitter) then retries; otherwise returns the last error.
+pub async fn retry_async<F, Fut, T, E, P>(
+    op: F,
+    max_retries: u32,
+    base_delay_ms: u64,
+    is_retriable: P,
+) -> Result<T, E>
+where
+    F: Fn() -> Fut,
+    Fut: Future<Output = Result<T, E>>,
+    P: Fn(&E) -> bool,
+{
+    let mut last_err: Option<E> = None;
+    for attempt in 0..max_retries {
+        match op().await {
+            Ok(t) => return Ok(t),
+            Err(e) => {
+                if !is_retriable(&e) || attempt + 1 >= max_retries {
+                    return Err(e);
+                }
+                let delay_ms = base_delay_ms * 2u64.saturating_pow(attempt);
+                let jitter_ms = rand::thread_rng().gen_range(0..=delay_ms / 2);
+                let total_ms = delay_ms + jitter_ms;
+                warn!(
+                    attempt = attempt + 1,
+                    max_retries,
+                    delay_ms = total_ms,
+                    "RPC failed, retrying after backoff"
+                );
+                last_err = Some(e);
+                tokio::time::sleep(Duration::from_millis(total_ms)).await;
+            }
+        }
+    }
+    match last_err {
+        Some(e) => Err(e),
+        None => unreachable!(
+            "retry_async: last_err is always Some when loop exits after an Err"
+        ),
+    }
+}
+
+/// Classifies `anyhow::Error` for retry: returns `false` for auth or invalid-param
+/// errors (do not retry), `true` for transient errors (network, timeout, server 5xx).
+/// When in doubt, returns `true` (retry).
+pub fn anyhow_is_retriable(err: &anyhow::Error) -> bool {
+    let s = format!("{:#}", err);
+    let s_lower = s.to_lowercase();
+    // Do not retry: auth / permission
+    if s_lower.contains("unauthorized")
+        || s_lower.contains("auth failed")
+        || s_lower.contains("access denied")
+        || s_lower.contains("401")
+        || s_lower.contains("forbidden")
+        || s_lower.contains("403")
+        || s_lower.contains("token")
+    {
+        return false;
+    }
+    // Do not retry: bad request / invalid params
+    if s_lower.contains("bad request")
+        || s_lower.contains("400")
+        || s_lower.contains("invalid param")
+        || s_lower.contains("fingerprint mismatch")
+    {
+        return false;
+    }
+    // Retry: network, timeout, connection, server error, or anything else
+    true
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn retry_success_first_attempt() {
+        let result = retry_async(|| async { Ok::<_, String>(42) }, 3, 10, |_| true).await;
+        assert_eq!(result.unwrap(), 42);
+    }
+
+    #[tokio::test]
+    async fn retry_succeeds_after_one_failure() {
+        let counter = std::sync::Arc::new(std::sync::atomic::AtomicU32::new(0));
+        let c = counter.clone();
+        let result = retry_async(
+            || {
+                let c = c.clone();
+                async move {
+                    let n = c.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+                    if n == 0 {
+                        Err("transient failure".to_string())
+                    } else {
+                        Ok(99)
+                    }
+                }
+            },
+            3,
+            1, // minimal delay for test speed
+            |_| true,
+        )
+        .await;
+        assert_eq!(result.unwrap(), 99);
+        assert_eq!(counter.load(std::sync::atomic::Ordering::SeqCst), 2);
+    }
+
+    #[tokio::test]
+    async fn retry_non_retriable_fails_immediately() {
+        let counter = std::sync::Arc::new(std::sync::atomic::AtomicU32::new(0));
+        let c = counter.clone();
+        let result = retry_async(
+            || {
+                let c = c.clone();
+                async move {
+                    c.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+                    Err::<(), _>("permanent error")
+                }
+            },
+            5,
+            1,
+            |_: &&str| false, // nothing is retriable
+        )
+        .await;
+        assert!(result.is_err());
+        assert_eq!(counter.load(std::sync::atomic::Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn retry_exhausts_all_attempts() {
+        let counter = std::sync::Arc::new(std::sync::atomic::AtomicU32::new(0));
+        let c = counter.clone();
+        let result = retry_async(
+            || {
+                let c = c.clone();
+                async move {
+                    c.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+                    Err::<(), _>("still failing")
+                }
+            },
+            3,
+            1,
+            |_| true,
+        )
+        .await;
+        assert!(result.is_err());
+        assert_eq!(counter.load(std::sync::atomic::Ordering::SeqCst), 3);
+    }
+
+    #[test]
+    fn anyhow_is_retriable_classifications() {
+        // Auth errors should NOT be retriable
+        let auth_errors = [
+            "unauthorized access",
+            "HTTP 401 Unauthorized",
+            "forbidden resource",
+            "HTTP 403 Forbidden",
+            "auth failed for user",
+            "access denied",
+            "invalid token",
+        ];
+        for msg in &auth_errors {
+            let err = anyhow::anyhow!("{msg}");
+            assert!(!anyhow_is_retriable(&err), "expected non-retriable: {msg}");
+        }
+
+        // Bad-request errors should NOT be retriable
+        let bad_req_errors = [
+            "bad request: missing field",
+            "HTTP 400 Bad Request",
+            "invalid param: username",
+            "fingerprint mismatch",
+        ];
+        for msg in &bad_req_errors {
+            let err = anyhow::anyhow!("{msg}");
+            assert!(!anyhow_is_retriable(&err), "expected non-retriable: {msg}");
+        }
+
+        // Transient errors SHOULD be retriable
+        let transient_errors = [
+            "connection refused",
+            "network timeout",
+            "server error 500",
+            "stream reset",
+            "something unknown happened",
+        ];
+        for msg in &transient_errors {
+            let err = anyhow::anyhow!("{msg}");
+            assert!(anyhow_is_retriable(&err), "expected retriable: {msg}");
+        }
+    }
+}

crates/quicprochat-client/src/client/rpc.rs

@@ -0,0 +1,978 @@
+use std::net::SocketAddr;
+use std::path::Path;
+use std::sync::Arc;
+
+use anyhow::Context;
+use quinn::{ClientConfig, Endpoint};
+use quinn_proto::crypto::rustls::QuicClientConfig;
+use rustls::pki_types::{CertificateDer, ServerName, UnixTime};
+use rustls::{ClientConfig as RustlsClientConfig, RootCertStore};
+use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
+use capnp_rpc::{rpc_twoparty_capnp::Side, twoparty, RpcSystem};
+
+use quicprochat_core::HybridPublicKey;
+use quicprochat_proto::node_capnp::{auth, node_service};
+
+use crate::{AUTH_CONTEXT, INSECURE_SKIP_VERIFY};
+
+use super::retry::{anyhow_is_retriable, retry_async, DEFAULT_BASE_DELAY_MS, DEFAULT_MAX_RETRIES};
+
+/// Cap'n Proto traversal limit (words). 4 Mi words = 32 MiB; bounds DoS from deeply nested or large messages.
+const CAPNP_TRAVERSAL_LIMIT_WORDS: usize = 4 * 1024 * 1024;
+
+/// A [`rustls::client::danger::ServerCertVerifier`] that accepts any certificate.
+///
+/// **Development only.** Using this in production disables all TLS guarantees.
+#[derive(Debug)]
+struct InsecureServerCertVerifier;
+
+impl rustls::client::danger::ServerCertVerifier for InsecureServerCertVerifier {
+    fn verify_server_cert(
+        &self,
+        _end_entity: &CertificateDer<'_>,
+        _intermediates: &[CertificateDer<'_>],
+        _server_name: &ServerName<'_>,
+        _ocsp_response: &[u8],
+        _now: UnixTime,
+    ) -> Result<rustls::client::danger::ServerCertVerified, rustls::Error> {
+        Ok(rustls::client::danger::ServerCertVerified::assertion())
+    }
+
+    fn verify_tls12_signature(
+        &self,
+        _message: &[u8],
+        _cert: &CertificateDer<'_>,
+        _dss: &rustls::DigitallySignedStruct,
+    ) -> Result<rustls::client::danger::HandshakeSignatureValid, rustls::Error> {
+        Ok(rustls::client::danger::HandshakeSignatureValid::assertion())
+    }
+
+    fn verify_tls13_signature(
+        &self,
+        _message: &[u8],
+        _cert: &CertificateDer<'_>,
+        _dss: &rustls::DigitallySignedStruct,
+    ) -> Result<rustls::client::danger::HandshakeSignatureValid, rustls::Error> {
+        Ok(rustls::client::danger::HandshakeSignatureValid::assertion())
+    }
+
+    fn supported_verify_schemes(&self) -> Vec<rustls::SignatureScheme> {
+        rustls::crypto::ring::default_provider()
+            .signature_verification_algorithms
+            .supported_schemes()
+    }
+}
+
+/// Establish a QUIC/TLS connection and return a `NodeService` client.
+///
+/// Must be called from within a `LocalSet` because capnp-rpc is `!Send`.
+///
+/// Reads [`INSECURE_SKIP_VERIFY`] to decide whether to bypass certificate
+/// verification (set once at startup via [`crate::set_insecure_skip_verify`]).
+pub async fn connect_node(
+    server: &str,
+    ca_cert: &Path,
+    server_name: &str,
+) -> anyhow::Result<node_service::Client> {
+    let skip = INSECURE_SKIP_VERIFY.load(std::sync::atomic::Ordering::Relaxed);
+    connect_node_opt(server, ca_cert, server_name, skip).await
+}
+
+/// Like [`connect_node`] but with an explicit `insecure_skip_verify` toggle.
+///
+/// When `insecure_skip_verify` is `true`, certificate verification is disabled entirely.
+/// This is intended for development and testing only.
+pub async fn connect_node_opt(
+    server: &str,
+    ca_cert: &Path,
+    server_name: &str,
+    insecure_skip_verify: bool,
+) -> anyhow::Result<node_service::Client> {
+    let addr: SocketAddr = server
+        .parse()
+        .with_context(|| format!("server must be host:port, got {server}"))?;
+
+    let mut tls = if insecure_skip_verify {
+        RustlsClientConfig::builder()
+            .dangerous()
+            .with_custom_certificate_verifier(Arc::new(InsecureServerCertVerifier))
+            .with_no_client_auth()
+    } else {
+        let cert_bytes =
+            std::fs::read(ca_cert).with_context(|| format!("read ca_cert {ca_cert:?}"))?;
+        let mut roots = RootCertStore::empty();
+        roots
+            .add(CertificateDer::from(cert_bytes))
+            .context("add root cert")?;
+        RustlsClientConfig::builder()
+            .with_root_certificates(roots)
+            .with_no_client_auth()
+    };
+    tls.alpn_protocols = vec![b"capnp".to_vec()];
+
+    let crypto = QuicClientConfig::try_from(tls)
+        .map_err(|e| anyhow::anyhow!("invalid client TLS config: {e}"))?;
+
+    let bind_addr: SocketAddr = "0.0.0.0:0".parse().context("parse client bind address")?;
+    let mut endpoint = Endpoint::client(bind_addr)?;
+    endpoint.set_default_client_config(ClientConfig::new(Arc::new(crypto)));
+
+    let connection = endpoint
+        .connect(addr, server_name)
+        .context("quic connect init")?
+        .await
+        .context("quic connect failed")?;
+
+    let (send, recv) = connection.open_bi().await.context("open bi stream")?;
+
+    let mut reader_opts = capnp::message::ReaderOptions::new();
+    reader_opts.traversal_limit_in_words(Some(CAPNP_TRAVERSAL_LIMIT_WORDS));
+    let network = twoparty::VatNetwork::new(
+        recv.compat(),
+        send.compat_write(),
+        Side::Client,
+        reader_opts,
+    );
+
+    let mut rpc_system = RpcSystem::new(Box::new(network), None);
+    let client: node_service::Client = rpc_system.bootstrap(Side::Server);
+
+    tokio::task::spawn_local(rpc_system);
+
+    Ok(client)
+}
+
+pub fn set_auth(auth: &mut auth::Builder<'_>) -> anyhow::Result<()> {
+    let guard = AUTH_CONTEXT
+        .read()
+        .map_err(|e| anyhow::anyhow!("AUTH_CONTEXT lock poisoned: {e}"))?;
+    let ctx = guard.as_ref().ok_or_else(|| {
+        anyhow::anyhow!(
+            "init_auth must be called before RPCs (use a bearer or session token for authenticated commands)"
+        )
+    })?;
+    auth.set_version(ctx.version);
+    auth.set_access_token(&ctx.access_token);
+    auth.set_device_id(&ctx.device_id);
+    Ok(())
+}
+
+/// Upload a KeyPackage and verify the fingerprint echoed by the AS.
+pub async fn upload_key_package(
+    client: &node_service::Client,
+    identity_key: &[u8],
+    package: &[u8],
+) -> anyhow::Result<()> {
+    let mut req = client.upload_key_package_request();
+    {
+        let mut p = req.get();
+        p.set_identity_key(identity_key);
+        p.set_package(package);
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+
+    let resp = req
+        .send()
+        .promise
+        .await
+        .context("upload_key_package RPC failed")?;
+
+    let server_fp = resp
+        .get()
+        .context("upload_key_package: bad response")?
+        .get_fingerprint()
+        .context("upload_key_package: missing fingerprint")?
+        .to_vec();
+
+    let local_fp = super::state::sha256(package);
+    anyhow::ensure!(server_fp == local_fp, "fingerprint mismatch");
+    Ok(())
+}
+
+/// Fetch a KeyPackage for `identity_key` from the AS.
+pub async fn fetch_key_package(
+    client: &node_service::Client,
+    identity_key: &[u8],
+) -> anyhow::Result<Vec<u8>> {
+    let mut req = client.fetch_key_package_request();
+    {
+        let mut p = req.get();
+        p.set_identity_key(identity_key);
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+
+    let resp = req
+        .send()
+        .promise
+        .await
+        .context("fetch_key_package RPC failed")?;
+
+    let pkg = resp
+        .get()
+        .context("fetch_key_package: bad response")?
+        .get_package()
+        .context("fetch_key_package: missing package field")?
+        .to_vec();
+
+    Ok(pkg)
+}
+
+/// Enqueue an opaque payload to the DS for `recipient_key`.
+/// Returns the per-inbox sequence number assigned by the server.
+/// Retries on transient failures with exponential backoff.
+pub async fn enqueue(
+    client: &node_service::Client,
+    recipient_key: &[u8],
+    payload: &[u8],
+) -> anyhow::Result<u64> {
+    enqueue_with_ttl(client, recipient_key, payload, None).await
+}
+
+/// Enqueue with an optional TTL (seconds). 0 or None means no expiry.
+pub async fn enqueue_with_ttl(
+    client: &node_service::Client,
+    recipient_key: &[u8],
+    payload: &[u8],
+    ttl_secs: Option<u32>,
+) -> anyhow::Result<u64> {
+    let client = client.clone();
+    let recipient_key = recipient_key.to_vec();
+    let payload = payload.to_vec();
+    retry_async(
+        || {
+            let client = client.clone();
+            let recipient_key = recipient_key.clone();
+            let payload = payload.clone();
+            async move {
+                let mut req = client.enqueue_request();
+                {
+                    let mut p = req.get();
+                    p.set_recipient_key(&recipient_key);
+                    p.set_payload(&payload);
+                    p.set_channel_id(&[]);
+                    p.set_version(1);
+                    if let Some(ttl) = ttl_secs {
+                        p.set_ttl_secs(ttl);
+                    }
+                    let mut auth = p.reborrow().init_auth();
+                    set_auth(&mut auth)?;
+                }
+                let resp = req.send().promise.await.context("enqueue RPC failed")?;
+                let seq = resp.get().context("enqueue: bad response")?.get_seq();
+                Ok(seq)
+            }
+        },
+        DEFAULT_MAX_RETRIES,
+        DEFAULT_BASE_DELAY_MS,
+        anyhow_is_retriable,
+    )
+    .await
+}
+
+/// Fetch and drain all payloads for `recipient_key`.
+/// Returns `(seq, payload)` pairs — sort by `seq` before MLS processing.
+/// Retries on transient failures with exponential backoff.
+pub async fn fetch_all(
+    client: &node_service::Client,
+    recipient_key: &[u8],
+) -> anyhow::Result<Vec<(u64, Vec<u8>)>> {
+    let client = client.clone();
+    let recipient_key = recipient_key.to_vec();
+    retry_async(
+        || {
+            let client = client.clone();
+            let recipient_key = recipient_key.clone();
+            async move {
+                let mut req = client.fetch_request();
+                {
+                    let mut p = req.get();
+                    p.set_recipient_key(&recipient_key);
+                    p.set_channel_id(&[]);
+                    p.set_version(1);
+                    p.set_limit(0); // fetch all
+                    let mut auth = p.reborrow().init_auth();
+                    set_auth(&mut auth)?;
+                }
+
+                let resp = req.send().promise.await.context("fetch RPC failed")?;
+
+                let list = resp
+                    .get()
+                    .context("fetch: bad response")?
+                    .get_payloads()
+                    .context("fetch: missing payloads")?;
+
+                let mut payloads = Vec::with_capacity(list.len() as usize);
+                for i in 0..list.len() {
+                    let entry = list.get(i);
+                    let seq = entry.get_seq();
+                    let data = entry
+                        .get_data()
+                        .context("fetch: envelope data read failed")?
+                        .to_vec();
+                    payloads.push((seq, data));
+                }
+
+                Ok(payloads)
+            }
+        },
+        DEFAULT_MAX_RETRIES,
+        DEFAULT_BASE_DELAY_MS,
+        anyhow_is_retriable,
+    )
+    .await
+}
+
+/// Long-poll for payloads with optional timeout (ms).
+/// Returns `(seq, payload)` pairs — sort by `seq` before MLS processing.
+/// Retries on transient failures with exponential backoff.
+pub async fn fetch_wait(
+    client: &node_service::Client,
+    recipient_key: &[u8],
+    timeout_ms: u64,
+) -> anyhow::Result<Vec<(u64, Vec<u8>)>> {
+    let client = client.clone();
+    let recipient_key = recipient_key.to_vec();
+    retry_async(
+        || {
+            let client = client.clone();
+            let recipient_key = recipient_key.clone();
+            async move {
+                let mut req = client.fetch_wait_request();
+                {
+                    let mut p = req.get();
+                    p.set_recipient_key(&recipient_key);
+                    p.set_timeout_ms(timeout_ms);
+                    p.set_channel_id(&[]);
+                    p.set_version(1);
+                    p.set_limit(0); // fetch all
+                    let mut auth = p.reborrow().init_auth();
+                    set_auth(&mut auth)?;
+                }
+
+                let resp = req.send().promise.await.context("fetch_wait RPC failed")?;
+
+                let list = resp
+                    .get()
+                    .context("fetch_wait: bad response")?
+                    .get_payloads()
+                    .context("fetch_wait: missing payloads")?;
+
+                let mut payloads = Vec::with_capacity(list.len() as usize);
+                for i in 0..list.len() {
+                    let entry = list.get(i);
+                    let seq = entry.get_seq();
+                    let data = entry
+                        .get_data()
+                        .context("fetch_wait: envelope data read failed")?
+                        .to_vec();
+                    payloads.push((seq, data));
+                }
+
+                Ok(payloads)
+            }
+        },
+        DEFAULT_MAX_RETRIES,
+        DEFAULT_BASE_DELAY_MS,
+        anyhow_is_retriable,
+    )
+    .await
+}
+
+/// Upload a hybrid (X25519 + ML-KEM-768) public key for an identity.
+pub async fn upload_hybrid_key(
+    client: &node_service::Client,
+    identity_key: &[u8],
+    hybrid_pk: &HybridPublicKey,
+) -> anyhow::Result<()> {
+    let mut req = client.upload_hybrid_key_request();
+    {
+        let mut p = req.get();
+        p.set_identity_key(identity_key);
+        p.set_hybrid_public_key(&hybrid_pk.to_bytes());
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+    req.send()
+        .promise
+        .await
+        .context("upload_hybrid_key RPC failed")?;
+    Ok(())
+}
+
+/// Fetch a peer's hybrid public key from the server.
+///
+/// Returns `None` if the peer has not uploaded a hybrid key.
+pub async fn fetch_hybrid_key(
+    client: &node_service::Client,
+    identity_key: &[u8],
+) -> anyhow::Result<Option<HybridPublicKey>> {
+    let mut req = client.fetch_hybrid_key_request();
+    {
+        let mut p = req.get();
+        p.set_identity_key(identity_key);
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+
+    let resp = req
+        .send()
+        .promise
+        .await
+        .context("fetch_hybrid_key RPC failed")?;
+
+    let pk_bytes = resp
+        .get()
+        .context("fetch_hybrid_key: bad response")?
+        .get_hybrid_public_key()
+        .context("fetch_hybrid_key: missing field")?
+        .to_vec();
+
+    if pk_bytes.is_empty() {
+        return Ok(None);
+    }
+
+    let pk = HybridPublicKey::from_bytes(&pk_bytes).context("invalid hybrid public key")?;
+    Ok(Some(pk))
+}
+
+/// Decrypt a hybrid envelope. Requires a hybrid key; no fallback to plaintext MLS.
+pub fn try_hybrid_decrypt(
+    hybrid_kp: Option<&quicprochat_core::HybridKeypair>,
+    payload: &[u8],
+) -> anyhow::Result<Vec<u8>> {
+    let kp = hybrid_kp.ok_or_else(|| anyhow::anyhow!("hybrid key required for decryption"))?;
+    quicprochat_core::hybrid_decrypt(kp, payload, b"", b"").map_err(|e| anyhow::anyhow!("{e}"))
+}
+
+/// Peek at queued payloads without removing them.
+/// Returns `(seq, payload)` pairs sorted by seq.
+/// Retries on transient failures with exponential backoff.
+pub async fn peek(
+    client: &node_service::Client,
+    recipient_key: &[u8],
+) -> anyhow::Result<Vec<(u64, Vec<u8>)>> {
+    let client = client.clone();
+    let recipient_key = recipient_key.to_vec();
+    retry_async(
+        || {
+            let client = client.clone();
+            let recipient_key = recipient_key.clone();
+            async move {
+                let mut req = client.peek_request();
+                {
+                    let mut p = req.get();
+                    p.set_recipient_key(&recipient_key);
+                    p.set_channel_id(&[]);
+                    p.set_version(1);
+                    p.set_limit(0); // peek all
+                    let mut auth = p.reborrow().init_auth();
+                    set_auth(&mut auth)?;
+                }
+
+                let resp = req.send().promise.await.context("peek RPC failed")?;
+
+                let list = resp
+                    .get()
+                    .context("peek: bad response")?
+                    .get_payloads()
+                    .context("peek: missing payloads")?;
+
+                let mut payloads = Vec::with_capacity(list.len() as usize);
+                for i in 0..list.len() {
+                    let entry = list.get(i);
+                    let seq = entry.get_seq();
+                    let data = entry
+                        .get_data()
+                        .context("peek: envelope data read failed")?
+                        .to_vec();
+                    payloads.push((seq, data));
+                }
+
+                Ok(payloads)
+            }
+        },
+        DEFAULT_MAX_RETRIES,
+        DEFAULT_BASE_DELAY_MS,
+        anyhow_is_retriable,
+    )
+    .await
+}
+
+/// Acknowledge all messages up to and including `seq_up_to`.
+/// Retries on transient failures with exponential backoff.
+pub async fn ack(
+    client: &node_service::Client,
+    recipient_key: &[u8],
+    seq_up_to: u64,
+) -> anyhow::Result<()> {
+    let client = client.clone();
+    let recipient_key = recipient_key.to_vec();
+    retry_async(
+        || {
+            let client = client.clone();
+            let recipient_key = recipient_key.clone();
+            async move {
+                let mut req = client.ack_request();
+                {
+                    let mut p = req.get();
+                    p.set_recipient_key(&recipient_key);
+                    p.set_channel_id(&[]);
+                    p.set_version(1);
+                    p.set_seq_up_to(seq_up_to);
+                    let mut auth = p.reborrow().init_auth();
+                    set_auth(&mut auth)?;
+                }
+                req.send().promise.await.context("ack RPC failed")?;
+                Ok(())
+            }
+        },
+        DEFAULT_MAX_RETRIES,
+        DEFAULT_BASE_DELAY_MS,
+        anyhow_is_retriable,
+    )
+    .await
+}
+
+/// Fetch multiple peers' hybrid keys in a single round-trip.
+/// Returns `None` for peers who have not uploaded a hybrid key.
+/// Retries on transient failures with exponential backoff.
+pub async fn fetch_hybrid_keys(
+    client: &node_service::Client,
+    identity_keys: &[&[u8]],
+) -> anyhow::Result<Vec<Option<HybridPublicKey>>> {
+    let client = client.clone();
+    let identity_keys: Vec<Vec<u8>> = identity_keys.iter().map(|k| k.to_vec()).collect();
+    retry_async(
+        || {
+            let client = client.clone();
+            let identity_keys = identity_keys.clone();
+            async move {
+                let mut req = client.fetch_hybrid_keys_request();
+                {
+                    let mut p = req.get();
+                    let mut list = p.reborrow().init_identity_keys(identity_keys.len() as u32);
+                    for (i, ik) in identity_keys.iter().enumerate() {
+                        list.set(i as u32, ik);
+                    }
+                    let mut auth = p.reborrow().init_auth();
+                    set_auth(&mut auth)?;
+                }
+
+                let resp = req
+                    .send()
+                    .promise
+                    .await
+                    .context("fetch_hybrid_keys RPC failed")?;
+
+                let keys = resp
+                    .get()
+                    .context("fetch_hybrid_keys: bad response")?
+                    .get_keys()
+                    .context("fetch_hybrid_keys: missing keys")?;
+
+                let mut result = Vec::with_capacity(keys.len() as usize);
+                for i in 0..keys.len() {
+                    let pk_bytes = keys
+                        .get(i)
+                        .context("fetch_hybrid_keys: key read failed")?
+                        .to_vec();
+                    if pk_bytes.is_empty() {
+                        result.push(None);
+                    } else {
+                        let pk = HybridPublicKey::from_bytes(&pk_bytes)
+                            .context("invalid hybrid public key")?;
+                        result.push(Some(pk));
+                    }
+                }
+
+                Ok(result)
+            }
+        },
+        DEFAULT_MAX_RETRIES,
+        DEFAULT_BASE_DELAY_MS,
+        anyhow_is_retriable,
+    )
+    .await
+}
+
+/// Enqueue the same payload to multiple recipients in a single round-trip.
+/// Returns per-recipient sequence numbers.
+/// Retries on transient failures with exponential backoff.
+pub async fn batch_enqueue(
+    client: &node_service::Client,
+    recipient_keys: &[&[u8]],
+    payload: &[u8],
+) -> anyhow::Result<Vec<u64>> {
+    let client = client.clone();
+    let recipient_keys: Vec<Vec<u8>> = recipient_keys.iter().map(|k| k.to_vec()).collect();
+    let payload = payload.to_vec();
+    retry_async(
+        || {
+            let client = client.clone();
+            let recipient_keys = recipient_keys.clone();
+            let payload = payload.clone();
+            async move {
+                let mut req = client.batch_enqueue_request();
+                {
+                    let mut p = req.get();
+                    let mut list = p.reborrow().init_recipient_keys(recipient_keys.len() as u32);
+                    for (i, rk) in recipient_keys.iter().enumerate() {
+                        list.set(i as u32, rk);
+                    }
+                    p.set_payload(&payload);
+                    p.set_channel_id(&[]);
+                    p.set_version(1);
+                    let mut auth = p.reborrow().init_auth();
+                    set_auth(&mut auth)?;
+                }
+
+                let resp = req
+                    .send()
+                    .promise
+                    .await
+                    .context("batch_enqueue RPC failed")?;
+
+                let seqs = resp
+                    .get()
+                    .context("batch_enqueue: bad response")?
+                    .get_seqs()
+                    .context("batch_enqueue: missing seqs")?;
+
+                let mut result = Vec::with_capacity(seqs.len() as usize);
+                for i in 0..seqs.len() {
+                    result.push(seqs.get(i));
+                }
+
+                Ok(result)
+            }
+        },
+        DEFAULT_MAX_RETRIES,
+        DEFAULT_BASE_DELAY_MS,
+        anyhow_is_retriable,
+    )
+    .await
+}
+
+/// Resolve a username to its Ed25519 identity key (32 bytes).
+///
+/// When the server returns a non-empty `inclusionProof`, the client verifies it
+/// against the identity key using the Key Transparency Merkle proof. Proof
+/// verification failure is treated as a hard error (the server is misbehaving).
+/// If the server sends no proof (empty field), the key is returned as-is —
+/// callers can decide whether to require proofs for security-critical flows.
+///
+/// Returns `None` if the username is not registered.
+pub async fn resolve_user(
+    client: &node_service::Client,
+    username: &str,
+) -> anyhow::Result<Option<Vec<u8>>> {
+    let mut req = client.resolve_user_request();
+    {
+        let mut p = req.get();
+        p.set_username(username);
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+
+    let resp = req
+        .send()
+        .promise
+        .await
+        .context("resolve_user RPC failed")?;
+
+    let reader = resp.get().context("resolve_user: bad response")?;
+
+    let key = reader
+        .get_identity_key()
+        .context("resolve_user: missing identity_key field")?
+        .to_vec();
+
+    if key.is_empty() {
+        return Ok(None);
+    }
+
+    // Verify the KT inclusion proof when the server sends one.
+    let proof_bytes = reader
+        .get_inclusion_proof()
+        .context("resolve_user: missing inclusion_proof field")?
+        .to_vec();
+
+    if !proof_bytes.is_empty() {
+        let proof = quicprochat_kt::InclusionProof::from_bytes(&proof_bytes)
+            .context("resolve_user: inclusion proof deserialise failed")?;
+        quicprochat_kt::verify_inclusion(&proof, username, &key)
+            .context("resolve_user: KT inclusion proof verification FAILED — possible key mislabelling")?;
+    }
+
+    Ok(Some(key))
+}
+
+/// Reverse lookup: resolve an identity key to the registered username.
+/// Returns `None` if no username is associated with the key.
+pub async fn resolve_identity(
+    client: &node_service::Client,
+    identity_key: &[u8],
+) -> anyhow::Result<Option<String>> {
+    let mut req = client.resolve_identity_request();
+    {
+        let mut p = req.get();
+        p.set_identity_key(identity_key);
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+
+    let resp = req
+        .send()
+        .promise
+        .await
+        .context("resolve_identity RPC failed")?;
+
+    let username = resp
+        .get()
+        .context("resolve_identity: bad response")?
+        .get_username()
+        .context("resolve_identity: missing field")?
+        .to_str()
+        .unwrap_or("")
+        .to_string();
+
+    if username.is_empty() {
+        Ok(None)
+    } else {
+        Ok(Some(username))
+    }
+}
+
+/// Create a 1:1 DM channel with a peer.
+///
+/// Returns `(channel_id, was_new)` where `channel_id` is the stable 16-byte identifier and
+/// `was_new` is `true` iff this call created the channel for the first time. When `was_new` is
+/// `false`, the channel already existed (created by the peer), and the caller should wait for
+/// the peer's MLS Welcome to arrive via the background poller rather than creating a new MLS group.
+pub async fn create_channel(
+    client: &node_service::Client,
+    peer_key: &[u8],
+) -> anyhow::Result<(Vec<u8>, bool)> {
+    let mut req = client.create_channel_request();
+    {
+        let mut p = req.get();
+        p.set_peer_key(peer_key);
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+
+    let resp = req
+        .send()
+        .promise
+        .await
+        .context("create_channel RPC failed")?;
+
+    let reader = resp.get().context("create_channel: bad response")?;
+    let channel_id = reader
+        .get_channel_id()
+        .context("create_channel: missing channel_id")?
+        .to_vec();
+    let was_new = reader.get_was_new();
+
+    Ok((channel_id, was_new))
+}
+
+/// Upload a single chunk of a blob to the server.
+///
+/// `blob_hash` is the expected SHA-256 hash (32 bytes) of the complete blob.
+/// Returns the `blob_id` once the server has received and verified the final chunk.
+pub async fn upload_blob_chunk(
+    client: &node_service::Client,
+    blob_hash: &[u8],
+    chunk: &[u8],
+    offset: u64,
+    total_size: u64,
+    mime_type: &str,
+) -> anyhow::Result<Vec<u8>> {
+    let mut req = client.upload_blob_request();
+    {
+        let mut p = req.get();
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+        p.set_blob_hash(blob_hash);
+        p.set_chunk(chunk);
+        p.set_offset(offset);
+        p.set_total_size(total_size);
+        p.set_mime_type(mime_type);
+    }
+    let resp = req.send().promise.await.context("upload_blob RPC failed")?;
+    let blob_id = resp
+        .get()
+        .context("upload_blob: bad response")?
+        .get_blob_id()
+        .context("upload_blob: missing blob_id")?
+        .to_vec();
+    Ok(blob_id)
+}
+
+/// Download a single chunk of a blob from the server.
+///
+/// Returns `(chunk_bytes, total_size, mime_type)`.
+pub async fn download_blob_chunk(
+    client: &node_service::Client,
+    blob_id: &[u8],
+    offset: u64,
+    length: u32,
+) -> anyhow::Result<(Vec<u8>, u64, String)> {
+    let mut req = client.download_blob_request();
+    {
+        let mut p = req.get();
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+        p.set_blob_id(blob_id);
+        p.set_offset(offset);
+        p.set_length(length);
+    }
+    let resp = req.send().promise.await.context("download_blob RPC failed")?;
+    let reader = resp.get().context("download_blob: bad response")?;
+    let chunk = reader.get_chunk().context("download_blob: missing chunk")?.to_vec();
+    let total_size = reader.get_total_size();
+    let mime_type = reader
+        .get_mime_type()
+        .context("download_blob: missing mime_type")?
+        .to_str()
+        .unwrap_or("application/octet-stream")
+        .to_string();
+    Ok((chunk, total_size, mime_type))
+}
+
+/// Delete the authenticated user's account on the server.
+/// Requires an identity-bound session (OPAQUE login).
+pub async fn delete_account(
+    client: &node_service::Client,
+) -> anyhow::Result<bool> {
+    let mut req = client.delete_account_request();
+    {
+        let mut p = req.get();
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+
+    let resp = req
+        .send()
+        .promise
+        .await
+        .context("delete_account RPC failed")?;
+
+    let success = resp
+        .get()
+        .context("delete_account: bad response")?
+        .get_success();
+
+    Ok(success)
+}
+
+/// Register a device for the authenticated identity.
+pub async fn register_device(
+    client: &node_service::Client,
+    device_id: &[u8],
+    device_name: &str,
+) -> anyhow::Result<bool> {
+    let mut req = client.register_device_request();
+    {
+        let mut p = req.get();
+        p.set_device_id(device_id);
+        p.set_device_name(device_name);
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+
+    let resp = req
+        .send()
+        .promise
+        .await
+        .context("register_device RPC failed")?;
+
+    let success = resp
+        .get()
+        .context("register_device: bad response")?
+        .get_success();
+
+    Ok(success)
+}
+
+/// List all registered devices for the authenticated identity.
+pub async fn list_devices(
+    client: &node_service::Client,
+) -> anyhow::Result<Vec<(Vec<u8>, String, u64)>> {
+    let mut req = client.list_devices_request();
+    {
+        let mut p = req.get();
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+
+    let resp = req
+        .send()
+        .promise
+        .await
+        .context("list_devices RPC failed")?;
+
+    let devices = resp
+        .get()
+        .context("list_devices: bad response")?
+        .get_devices()
+        .context("list_devices: missing devices field")?;
+
+    let mut result = Vec::with_capacity(devices.len() as usize);
+    for i in 0..devices.len() {
+        let entry = devices.get(i);
+        let device_id = entry
+            .get_device_id()
+            .context("list_devices: missing device_id")?
+            .to_vec();
+        let device_name = entry
+            .get_device_name()
+            .context("list_devices: missing device_name")?
+            .to_str()
+            .unwrap_or("")
+            .to_string();
+        let registered_at = entry.get_registered_at();
+        result.push((device_id, device_name, registered_at));
+    }
+
+    Ok(result)
+}
+
+/// Revoke (remove) a registered device.
+pub async fn revoke_device(
+    client: &node_service::Client,
+    device_id: &[u8],
+) -> anyhow::Result<bool> {
+    let mut req = client.revoke_device_request();
+    {
+        let mut p = req.get();
+        p.set_device_id(device_id);
+        let mut auth = p.reborrow().init_auth();
+        set_auth(&mut auth)?;
+    }
+
+    let resp = req
+        .send()
+        .promise
+        .await
+        .context("revoke_device RPC failed")?;
+
+    let success = resp
+        .get()
+        .context("revoke_device: bad response")?
+        .get_success();
+
+    Ok(success)
+}
+
+/// Return the current Unix timestamp in milliseconds.
+pub fn current_timestamp_ms() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}

crates/quicprochat-client/src/client/session.rs

@@ -0,0 +1,291 @@
+//! Runtime session state for the interactive REPL.
+//!
+//! Wraps the legacy `StoredState` (identity + hybrid key) and adds
+//! multi-conversation management via `ConversationStore`.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use std::time::Instant;
+
+use anyhow::Context;
+use zeroize::Zeroizing;
+
+use quicprochat_core::{DiskKeyStore, GroupMember, HybridKeypair, IdentityKeypair};
+
+use super::conversation::{
+    now_ms, Conversation, ConversationId, ConversationKind, ConversationStore,
+};
+use super::state::{load_or_init_state, keystore_path};
+
+/// Runtime state for an interactive REPL session.
+pub struct SessionState {
+    /// Long-term identity keypair.
+    pub identity: Arc<IdentityKeypair>,
+    /// Post-quantum hybrid keypair.
+    pub hybrid_kp: Option<HybridKeypair>,
+    /// Path to the legacy state file (for backward compat with one-shot commands).
+    pub state_path: PathBuf,
+    /// Optional password for the legacy state file. Zeroized on drop. (M9)
+    pub password: Option<Zeroizing<String>>,
+    /// SQLite-backed conversation + message store.
+    pub conv_store: ConversationStore,
+    /// Currently active conversation.
+    pub active_conversation: Option<ConversationId>,
+    /// In-memory GroupMember instances keyed by conversation ID.
+    pub members: HashMap<ConversationId, GroupMember>,
+    /// Holds the GroupMember whose KeyPackage was uploaded to the server.
+    /// Its keystore contains the HPKE init private key needed to decrypt
+    /// incoming Welcome messages. Consumed on auto-join, then replenished.
+    pub pending_member: Option<GroupMember>,
+    /// Whether to display typing indicators from others (session preference).
+    pub typing_notify_enabled: bool,
+    /// Tracks who is currently typing and when the indicator was last received.
+    /// Entries older than 10 seconds are considered expired.
+    pub typing_indicators: HashMap<String, Instant>,
+    /// Per-conversation disappearing message TTL in seconds. None = messages persist.
+    pub disappear_ttl: HashMap<ConversationId, u32>,
+    /// When true, /members and /group-info redact identity keys as `[redacted-XXXX]`.
+    pub redact_keys: bool,
+    /// When Some(secs), auto-clear local messages older than this duration.
+    pub auto_clear_secs: Option<u32>,
+    /// When true, send periodic dummy messages for traffic analysis resistance.
+    pub padding_enabled: bool,
+    /// Last epoch at which we sent a message (for /verify-fs).
+    pub last_send_epoch: Option<u64>,
+}
+
+impl SessionState {
+    /// Load identity from the legacy state file, open the conversation store,
+    /// and migrate any existing single-group state into the conversation DB.
+    pub fn load(
+        state_path: &Path,
+        password: Option<&str>,
+    ) -> anyhow::Result<Self> {
+        let state = load_or_init_state(state_path, password)?;
+
+        let identity = Arc::new(IdentityKeypair::from_seed(state.identity_seed));
+        let hybrid_kp = state
+            .hybrid_key
+            .as_ref()
+            .map(HybridKeypair::from_bytes)
+            .transpose()
+            .context("decode hybrid key")?;
+
+        // Open the conversation DB next to the state file.
+        // When a state password is provided, encrypt the DB with SQLCipher.
+        let db_path = state_path.with_extension("convdb");
+        let conv_store = ConversationStore::open(&db_path, password)?;
+
+        let mut session = Self {
+            identity,
+            hybrid_kp,
+            state_path: state_path.to_path_buf(),
+            password: password.map(|p| Zeroizing::new(String::from(p))),
+            conv_store,
+            active_conversation: None,
+            members: HashMap::new(),
+            pending_member: None,
+            typing_notify_enabled: true,
+            typing_indicators: HashMap::new(),
+            disappear_ttl: HashMap::new(),
+            redact_keys: false,
+            auto_clear_secs: None,
+            padding_enabled: false,
+            last_send_epoch: None,
+        };
+
+        // Migrate legacy single-group into conversations if present and not yet migrated.
+        if state.group.is_some() {
+            session.migrate_legacy_group(state_path, &state.group)?;
+        }
+
+        // Load all existing conversations' GroupMembers into memory.
+        session.load_all_members()?;
+
+        Ok(session)
+    }
+
+    /// Migrate the legacy single-group from StoredState into the conversation DB.
+    fn migrate_legacy_group(
+        &mut self,
+        state_path: &Path,
+        group_blob: &Option<Vec<u8>>,
+    ) -> anyhow::Result<()> {
+        let blob = match group_blob {
+            Some(b) => b,
+            None => return Ok(()),
+        };
+
+        // Reconstruct GroupMember using the legacy keystore and group blob.
+        let ks_path = keystore_path(state_path);
+        let ks = DiskKeyStore::persistent(&ks_path)?;
+        let group = bincode::deserialize(blob).context("decode legacy group")?;
+        let member = GroupMember::new_with_state(
+            Arc::clone(&self.identity),
+            ks,
+            Some(group),
+            false, // legacy groups are classical
+        );
+
+        let group_id_bytes = member.group_id().unwrap_or_default();
+
+        // Use the first 16 bytes of the group_id as the ConversationId.
+        let conv_id = if group_id_bytes.len() >= 16 {
+            ConversationId::from_slice(&group_id_bytes[..16])
+                .unwrap_or(ConversationId([0; 16]))
+        } else {
+            ConversationId::from_group_name(&hex::encode(&group_id_bytes))
+        };
+
+        // Check if already migrated.
+        if self.conv_store.load_conversation(&conv_id)?.is_some() {
+            return Ok(());
+        }
+
+        let member_keys = member.member_identities();
+        let short_id = &hex::encode(&group_id_bytes)[..8.min(group_id_bytes.len() * 2)];
+        let conv = Conversation {
+            id: conv_id.clone(),
+            kind: ConversationKind::Group {
+                name: format!("legacy-{short_id}"),
+            },
+            display_name: format!("legacy-{short_id}"),
+            mls_group_blob: Some(blob.clone()),
+            keystore_blob: None,
+            member_keys,
+            unread_count: 0,
+            last_activity_ms: now_ms(),
+            created_at_ms: now_ms(),
+            is_hybrid: false,
+            last_seen_seq: 0,
+        };
+
+        self.conv_store.save_conversation(&conv)?;
+        self.members.insert(conv_id, member);
+
+        Ok(())
+    }
+
+    /// Load all conversations from the DB and create in-memory GroupMember instances.
+    fn load_all_members(&mut self) -> anyhow::Result<()> {
+        let convs = self.conv_store.list_conversations()?;
+        for conv in convs {
+            if self.members.contains_key(&conv.id) {
+                continue;
+            }
+            let member = self.create_member_from_conv(&conv)?;
+            self.members.insert(conv.id.clone(), member);
+        }
+        Ok(())
+    }
+
+    /// Create a GroupMember from a stored conversation.
+    fn create_member_from_conv(&self, conv: &Conversation) -> anyhow::Result<GroupMember> {
+        let ks_path = self.keystore_path_for(&conv.id);
+        let ks = DiskKeyStore::persistent(&ks_path)
+            .unwrap_or_else(|e| {
+                tracing::warn!(path = %ks_path.display(), error = %e, "DiskKeyStore open failed, falling back to ephemeral");
+                DiskKeyStore::ephemeral()
+            });
+
+        let group = conv
+            .mls_group_blob
+            .as_ref()
+            .map(|b| bincode::deserialize(b))
+            .transpose()
+            .context("decode MLS group from conversation db")?;
+
+        Ok(GroupMember::new_with_state(
+            Arc::clone(&self.identity),
+            ks,
+            group,
+            conv.is_hybrid,
+        ))
+    }
+
+    /// Path for a per-conversation keystore file.
+    fn keystore_path_for(&self, conv_id: &ConversationId) -> PathBuf {
+        let dir = self.state_path.with_extension("keystores");
+        dir.join(format!("{}.ks", conv_id.hex()))
+    }
+
+    /// Persist a conversation's MLS group state back to the DB.
+    pub fn save_member(&self, conv_id: &ConversationId) -> anyhow::Result<()> {
+        let member = self.members.get(conv_id).context("no such conversation")?;
+        let blob = member
+            .group_ref()
+            .map(bincode::serialize)
+            .transpose()
+            .context("serialize MLS group")?;
+
+        let member_keys = member.member_identities();
+
+        // Update the mls_group_blob and member_keys in the DB.
+        if let Some(mut conv) = self.conv_store.load_conversation(conv_id)? {
+            conv.mls_group_blob = blob;
+            conv.member_keys = member_keys;
+            self.conv_store.save_conversation(&conv)?;
+        }
+
+        Ok(())
+    }
+
+    /// Persist all in-memory group states back to the DB.
+    pub fn save_all(&self) -> anyhow::Result<()> {
+        for conv_id in self.members.keys() {
+            if let Err(e) = self.save_member(conv_id) {
+                tracing::warn!(conv = %conv_id.hex(), error = %e, "failed to save conversation");
+            }
+        }
+        Ok(())
+    }
+
+    /// Add a new conversation and its GroupMember to the session.
+    pub fn add_conversation(
+        &mut self,
+        conv: Conversation,
+        member: GroupMember,
+    ) -> anyhow::Result<()> {
+        // Ensure keystore directory exists
+        let ks_path = self.keystore_path_for(&conv.id);
+        if let Some(parent) = ks_path.parent() {
+            std::fs::create_dir_all(parent).ok();
+        }
+
+        self.conv_store.save_conversation(&conv)?;
+        self.members.insert(conv.id.clone(), member);
+        Ok(())
+    }
+
+    /// Get a mutable reference to a conversation's GroupMember.
+    pub fn get_member_mut(&mut self, conv_id: &ConversationId) -> Option<&mut GroupMember> {
+        self.members.get_mut(conv_id)
+    }
+
+    /// Public key bytes for this identity.
+    pub fn identity_bytes(&self) -> Vec<u8> {
+        self.identity.public_key_bytes().to_vec()
+    }
+
+    /// Short hex prefix of the identity key for display.
+    pub fn identity_short(&self) -> String {
+        hex::encode(&self.identity.public_key_bytes()[..4])
+    }
+
+    /// Get display name of a conversation.
+    pub fn active_display_name(&self) -> Option<String> {
+        let id = self.active_conversation.as_ref()?;
+        self.conv_store.load_conversation(id).ok().flatten().map(|c| c.display_name)
+    }
+
+    /// Count total unread across all conversations.
+    pub fn total_unread(&self) -> u32 {
+        self.conv_store
+            .list_conversations()
+            .unwrap_or_default()
+            .iter()
+            .map(|c| c.unread_count)
+            .sum()
+    }
+}

crates/quicprochat-client/src/client/state.rs

@@ -0,0 +1,293 @@
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use anyhow::Context;
+use argon2::{Algorithm, Argon2, Params, Version};
+use chacha20poly1305::{
+    aead::{Aead, KeyInit},
+    ChaCha20Poly1305, Key, Nonce,
+};
+use rand::RngCore;
+use serde::{Deserialize, Serialize};
+
+use quicprochat_core::{DiskKeyStore, GroupMember, HybridKeypair, HybridKeypairBytes, IdentityKeypair};
+
+/// Magic bytes for encrypted client state files.
+const STATE_MAGIC: &[u8; 4] = b"QPCE";
+const STATE_SALT_LEN: usize = 16;
+const STATE_NONCE_LEN: usize = 12;
+
+#[derive(Serialize, Deserialize)]
+pub struct StoredState {
+    pub identity_seed: [u8; 32],
+    pub group: Option<Vec<u8>>,
+    /// Post-quantum hybrid keypair (X25519 + ML-KEM-768). `None` for state created before hybrid was added.
+    #[serde(default)]
+    pub hybrid_key: Option<HybridKeypairBytes>,
+    /// Cached member public keys for group participants.
+    #[serde(default)]
+    pub member_keys: Vec<Vec<u8>>,
+}
+
+impl StoredState {
+    pub fn into_parts(self, state_path: &Path) -> anyhow::Result<(GroupMember, Option<HybridKeypair>)> {
+        let identity = Arc::new(IdentityKeypair::from_seed(self.identity_seed));
+        let group = self
+            .group
+            .map(|bytes| bincode::deserialize(&bytes).context("decode group"))
+            .transpose()?;
+        let key_store = DiskKeyStore::persistent(keystore_path(state_path))?;
+        let hybrid = self.hybrid_key.is_some();
+        let member = GroupMember::new_with_state(identity, key_store, group, hybrid);
+
+        let hybrid_kp = self
+            .hybrid_key
+            .map(|bytes| HybridKeypair::from_bytes(&bytes).context("decode hybrid key"))
+            .transpose()?;
+
+        Ok((member, hybrid_kp))
+    }
+
+    pub fn from_parts(member: &GroupMember, hybrid_kp: Option<&HybridKeypair>) -> anyhow::Result<Self> {
+        let group = member
+            .group_ref()
+            .map(|g| bincode::serialize(g).context("serialize group"))
+            .transpose()?;
+
+        Ok(Self {
+            identity_seed: *member.identity_seed(),
+            group,
+            hybrid_key: hybrid_kp.map(|kp| kp.to_bytes()),
+            member_keys: Vec::new(),
+        })
+    }
+}
+
+/// Argon2id parameters for client state key derivation (auditable; matches argon2 crate defaults).
+/// - Memory: 19 MiB (m_cost = 19*1024 KiB)
+/// - Time: 2 iterations
+/// - Parallelism: 1 lane
+const ARGON2_STATE_M_COST: u32 = 19 * 1024;
+const ARGON2_STATE_T_COST: u32 = 2;
+const ARGON2_STATE_P_COST: u32 = 1;
+
+/// Derive a 32-byte key from a password and salt using Argon2id with explicit parameters.
+fn derive_state_key(password: &str, salt: &[u8]) -> anyhow::Result<[u8; 32]> {
+    let params = Params::new(ARGON2_STATE_M_COST, ARGON2_STATE_T_COST, ARGON2_STATE_P_COST, Some(32))
+        .map_err(|e| anyhow::anyhow!("argon2 params: {e}"))?;
+    let argon2 = Argon2::new(Algorithm::Argon2id, Version::default(), params);
+    let mut key = [0u8; 32];
+    argon2
+        .hash_password_into(password.as_bytes(), salt, &mut key)
+        .map_err(|e| anyhow::anyhow!("argon2 key derivation failed: {e}"))?;
+    Ok(key)
+}
+
+/// Encrypt `plaintext` with the QPCE format: magic(4) | salt(16) | nonce(12) | ciphertext.
+pub fn encrypt_state(password: &str, plaintext: &[u8]) -> anyhow::Result<Vec<u8>> {
+    let mut salt = [0u8; STATE_SALT_LEN];
+    rand::rngs::OsRng.fill_bytes(&mut salt);
+
+    let mut nonce_bytes = [0u8; STATE_NONCE_LEN];
+    rand::rngs::OsRng.fill_bytes(&mut nonce_bytes);
+
+    let key = zeroize::Zeroizing::new(derive_state_key(password, &salt)?);
+    let cipher = ChaCha20Poly1305::new(Key::from_slice(&*key));
+    let nonce = Nonce::from_slice(&nonce_bytes);
+
+    let ciphertext = cipher
+        .encrypt(nonce, plaintext)
+        .map_err(|e| anyhow::anyhow!("state encryption failed: {e}"))?;
+
+    let mut out = Vec::with_capacity(4 + STATE_SALT_LEN + STATE_NONCE_LEN + ciphertext.len());
+    out.extend_from_slice(STATE_MAGIC);
+    out.extend_from_slice(&salt);
+    out.extend_from_slice(&nonce_bytes);
+    out.extend_from_slice(&ciphertext);
+    Ok(out)
+}
+
+/// Decrypt a QPCE-formatted state file.
+pub fn decrypt_state(password: &str, data: &[u8]) -> anyhow::Result<Vec<u8>> {
+    let header_len = 4 + STATE_SALT_LEN + STATE_NONCE_LEN;
+    anyhow::ensure!(
+        data.len() > header_len,
+        "encrypted state file too short ({} bytes)",
+        data.len()
+    );
+
+    let salt = &data[4..4 + STATE_SALT_LEN];
+    let nonce_bytes = &data[4 + STATE_SALT_LEN..header_len];
+    let ciphertext = &data[header_len..];
+
+    let key = zeroize::Zeroizing::new(derive_state_key(password, salt)?);
+    let cipher = ChaCha20Poly1305::new(Key::from_slice(&*key));
+    let nonce = Nonce::from_slice(nonce_bytes);
+
+    let plaintext = cipher
+        .decrypt(nonce, ciphertext)
+        .map_err(|_| anyhow::anyhow!("state decryption failed (wrong password?)"))?;
+
+    Ok(plaintext)
+}
+
+/// Returns true if raw bytes begin with the QPCE magic header.
+pub fn is_encrypted_state(bytes: &[u8]) -> bool {
+    bytes.len() >= 4 && &bytes[..4] == STATE_MAGIC
+}
+
+pub fn load_or_init_state(path: &Path, password: Option<&str>) -> anyhow::Result<StoredState> {
+    if path.exists() {
+        let mut state = load_existing_state(path, password)?;
+        // Generate hybrid keypair if missing (upgrade from older state).
+        if state.hybrid_key.is_none() {
+            state.hybrid_key = Some(HybridKeypair::generate().to_bytes());
+            write_state(path, &state, password)?;
+        }
+        return Ok(state);
+    }
+
+    let identity = IdentityKeypair::generate();
+    let hybrid_kp = HybridKeypair::generate();
+    let key_store = DiskKeyStore::persistent(keystore_path(path))?;
+    let member = GroupMember::new_with_state(Arc::new(identity), key_store, None, false);
+    let state = StoredState::from_parts(&member, Some(&hybrid_kp))?;
+    write_state(path, &state, password)?;
+    Ok(state)
+}
+
+pub fn load_existing_state(path: &Path, password: Option<&str>) -> anyhow::Result<StoredState> {
+    let bytes = std::fs::read(path).with_context(|| format!("read state file {path:?}"))?;
+
+    if is_encrypted_state(&bytes) {
+        let pw = password
+            .context("state file is encrypted (QPCE); a password is required to decrypt it")?;
+        let plaintext = decrypt_state(pw, &bytes)?;
+        bincode::deserialize(&plaintext).context("decode encrypted state")
+    } else {
+        bincode::deserialize(&bytes).context("decode state")
+    }
+}
+
+pub fn save_state(
+    path: &Path,
+    member: &GroupMember,
+    hybrid_kp: Option<&HybridKeypair>,
+    password: Option<&str>,
+) -> anyhow::Result<()> {
+    let state = StoredState::from_parts(member, hybrid_kp)?;
+    write_state(path, &state, password)
+}
+
+pub fn write_state(path: &Path, state: &StoredState, password: Option<&str>) -> anyhow::Result<()> {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent).with_context(|| format!("create dir {parent:?}"))?;
+    }
+    let plaintext = bincode::serialize(state).context("encode state")?;
+
+    let bytes = if let Some(pw) = password {
+        encrypt_state(pw, &plaintext)?
+    } else {
+        plaintext
+    };
+
+    let tmp = path.with_extension("tmp");
+    std::fs::write(&tmp, bytes).with_context(|| format!("write state temp {tmp:?}"))?;
+    std::fs::rename(&tmp, path).with_context(|| format!("rename state {tmp:?} -> {path:?}"))?;
+    Ok(())
+}
+
+pub fn decode_identity_key(hex_str: &str) -> anyhow::Result<Vec<u8>> {
+    let bytes = super::hex::decode(hex_str)
+        .map_err(|e| anyhow::anyhow!(e))
+        .context("identity key must be hex")?;
+    anyhow::ensure!(bytes.len() == 32, "identity key must be 32 bytes");
+    Ok(bytes)
+}
+
+pub fn keystore_path(state_path: &Path) -> PathBuf {
+    let mut path = state_path.to_path_buf();
+    path.set_extension("ks");
+    path
+}
+
+pub fn sha256(bytes: &[u8]) -> Vec<u8> {
+    use sha2::{Digest, Sha256};
+    Sha256::digest(bytes).to_vec()
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn encrypt_decrypt_roundtrip() {
+        let plaintext = b"test state data";
+        let password = "test-password";
+        let encrypted = encrypt_state(password, plaintext).unwrap();
+        assert!(is_encrypted_state(&encrypted));
+        let decrypted = decrypt_state(password, &encrypted).unwrap();
+        assert_eq!(decrypted, plaintext);
+    }
+
+    #[test]
+    fn wrong_password_fails() {
+        let plaintext = b"test state data";
+        let encrypted = encrypt_state("correct", plaintext).unwrap();
+        assert!(decrypt_state("wrong", &encrypted).is_err());
+    }
+
+    #[test]
+    fn state_encrypt_decrypt_round_trip() {
+        let state = StoredState {
+            identity_seed: [42u8; 32],
+            hybrid_key: None,
+            group: None,
+            member_keys: Vec::new(),
+        };
+        let password = "test-password";
+        let plaintext = bincode::serialize(&state).unwrap();
+        let encrypted = encrypt_state(password, &plaintext).unwrap();
+        let decrypted = decrypt_state(password, &encrypted).unwrap();
+        let recovered: StoredState = bincode::deserialize(&decrypted).unwrap();
+        assert_eq!(recovered.identity_seed, state.identity_seed);
+        assert!(recovered.hybrid_key.is_none());
+        assert!(recovered.group.is_none());
+    }
+
+    #[test]
+    fn state_encrypt_decrypt_with_hybrid_key() {
+        use zeroize::Zeroizing;
+        let state = StoredState {
+            identity_seed: [7u8; 32],
+            hybrid_key: Some(HybridKeypairBytes {
+                x25519_sk: Zeroizing::new([1u8; 32]),
+                mlkem_dk: Zeroizing::new(vec![3u8; 2400]),
+                mlkem_ek: vec![4u8; 1184],
+            }),
+            group: None,
+            member_keys: Vec::new(),
+        };
+        let password = "another-password";
+        let plaintext = bincode::serialize(&state).unwrap();
+        let encrypted = encrypt_state(password, &plaintext).unwrap();
+        let decrypted = decrypt_state(password, &encrypted).unwrap();
+        let recovered: StoredState = bincode::deserialize(&decrypted).unwrap();
+        assert_eq!(recovered.identity_seed, state.identity_seed);
+        assert!(recovered.hybrid_key.is_some());
+    }
+
+    #[test]
+    fn state_wrong_password_fails() {
+        let state = StoredState {
+            identity_seed: [99u8; 32],
+            hybrid_key: None,
+            group: None,
+            member_keys: Vec::new(),
+        };
+        let plaintext = bincode::serialize(&state).unwrap();
+        let encrypted = encrypt_state("correct", &plaintext).unwrap();
+        assert!(decrypt_state("wrong", &encrypted).is_err());
+    }
+}

crates/quicprochat-client/src/client/token_cache.rs

@@ -0,0 +1,179 @@
+//! Cached session token stored next to the state file.
+//!
+//! File format (no password): two lines — username and hex-encoded session token.
+//! File format (with password): QPCE-encrypted version of the above.
+//! The token has a server-side 24h TTL; no client-side expiry tracking.
+
+use std::path::{Path, PathBuf};
+
+use anyhow::Context;
+
+use super::state::{decrypt_state, encrypt_state, is_encrypted_state};
+
+pub struct CachedSession {
+    pub username: String,
+    pub token_hex: String,
+}
+
+/// Derive the session cache path: `{state_path}.session`.
+fn session_cache_path(state_path: &Path) -> PathBuf {
+    state_path.with_extension("session")
+}
+
+/// Parse the two-line format (username + token_hex) from plaintext bytes.
+fn parse_session_lines(text: &str) -> Option<CachedSession> {
+    let mut lines = text.lines();
+    let username = lines.next()?.trim().to_string();
+    let token_hex = lines.next()?.trim().to_string();
+    if username.is_empty() || token_hex.is_empty() {
+        return None;
+    }
+    if hex::decode(&token_hex).is_err() {
+        return None;
+    }
+    Some(CachedSession { username, token_hex })
+}
+
+/// Load a cached session token. Returns None if file is missing or malformed.
+/// Decrypts if the file is QPCE-encrypted (requires `password`).
+pub fn load_cached_session(state_path: &Path, password: Option<&str>) -> Option<CachedSession> {
+    let path = session_cache_path(state_path);
+    let raw = std::fs::read(&path).ok()?;
+
+    if is_encrypted_state(&raw) {
+        let pw = password?;
+        let plaintext = decrypt_state(pw, &raw).ok()?;
+        let text = String::from_utf8(plaintext).ok()?;
+        parse_session_lines(&text)
+    } else {
+        let text = String::from_utf8(raw).ok()?;
+        parse_session_lines(&text)
+    }
+}
+
+/// Save a session token to the cache file (mode 0o600 on Unix).
+/// Encrypts with QPCE if `password` is provided.
+pub fn save_cached_session(
+    state_path: &Path,
+    username: &str,
+    token_hex: &str,
+    password: Option<&str>,
+) -> anyhow::Result<()> {
+    let path = session_cache_path(state_path);
+    let contents = format!("{username}\n{token_hex}\n");
+
+    let bytes = match password {
+        Some(pw) => encrypt_state(pw, contents.as_bytes())?,
+        None => {
+            #[cfg(not(unix))]
+            tracing::warn!(
+                "storing session token as plaintext (no password set); \
+                 file permissions cannot be restricted on this platform"
+            );
+            contents.into_bytes()
+        }
+    };
+
+    std::fs::write(&path, bytes).with_context(|| format!("write session cache {path:?}"))?;
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let perms = std::fs::Permissions::from_mode(0o600);
+        std::fs::set_permissions(&path, perms).ok();
+    }
+
+    Ok(())
+}
+
+/// Remove the cached session file.
+pub fn clear_cached_session(state_path: &Path) {
+    let path = session_cache_path(state_path);
+    std::fs::remove_file(&path).ok();
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn plaintext_round_trip() {
+        let dir = tempfile::tempdir().unwrap();
+        let state_path = dir.path().join("state.bin");
+
+        let token = hex::encode(b"session-token-bytes");
+        save_cached_session(&state_path, "alice", &token, None).unwrap();
+        let loaded = load_cached_session(&state_path, None).unwrap();
+        assert_eq!(loaded.username, "alice");
+        assert_eq!(loaded.token_hex, token);
+    }
+
+    #[test]
+    fn encrypted_round_trip() {
+        let dir = tempfile::tempdir().unwrap();
+        let state_path = dir.path().join("state.bin");
+        let password = "strong-password";
+
+        let token = hex::encode(b"encrypted-token");
+        save_cached_session(&state_path, "bob", &token, Some(password)).unwrap();
+
+        // Encrypted file should start with QPCE magic
+        let raw = std::fs::read(session_cache_path(&state_path)).unwrap();
+        assert_eq!(&raw[..4], b"QPCE");
+
+        let loaded = load_cached_session(&state_path, Some(password)).unwrap();
+        assert_eq!(loaded.username, "bob");
+        assert_eq!(loaded.token_hex, token);
+    }
+
+    #[test]
+    fn wrong_password_returns_none() {
+        let dir = tempfile::tempdir().unwrap();
+        let state_path = dir.path().join("state.bin");
+
+        let token = hex::encode(b"secret-token");
+        save_cached_session(&state_path, "carol", &token, Some("correct")).unwrap();
+        let result = load_cached_session(&state_path, Some("wrong"));
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn missing_file_returns_none() {
+        let dir = tempfile::tempdir().unwrap();
+        let state_path = dir.path().join("nonexistent.bin");
+        assert!(load_cached_session(&state_path, None).is_none());
+    }
+
+    #[test]
+    fn clear_removes_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let state_path = dir.path().join("state.bin");
+
+        let token = hex::encode(b"to-be-deleted");
+        save_cached_session(&state_path, "dave", &token, None).unwrap();
+        assert!(session_cache_path(&state_path).exists());
+
+        clear_cached_session(&state_path);
+        assert!(!session_cache_path(&state_path).exists());
+    }
+
+    #[test]
+    fn malformed_content_returns_none() {
+        let dir = tempfile::tempdir().unwrap();
+        let state_path = dir.path().join("state.bin");
+        let cache_path = session_cache_path(&state_path);
+
+        // Not valid hex on second line
+        std::fs::write(&cache_path, "alice\nnot-hex-data\n").unwrap();
+        assert!(load_cached_session(&state_path, None).is_none());
+
+        // Only one line
+        std::fs::write(&cache_path, "alice\n").unwrap();
+        assert!(load_cached_session(&state_path, None).is_none());
+
+        // Empty file
+        std::fs::write(&cache_path, "").unwrap();
+        assert!(load_cached_session(&state_path, None).is_none());
+    }
+}

crates/quicprochat-client/src/client/tui/mod.rs

@@ -0,0 +1,807 @@
+//! Full-screen Ratatui TUI for quicprochat.
+//!
+//! Layout:
+//!   ┌──────────────┬──────────────────────────────────────────┐
+//!   │  Channels    │           Messages                       │
+//!   │  (20%)       │           (80%)                          │
+//!   │              │                                          │
+//!   │              ├──────────────────────────────────────────┤
+//!   │              │  Input bar                               │
+//!   └──────────────┴──────────────────────────────────────────┘
+//!
+//! Keyboard:
+//!   Enter        — send message
+//!   Up / Down    — scroll message history
+//!   Tab          — next channel
+//!   Shift+Tab    — prev channel
+//!   Ctrl+C / q   — quit
+
+use std::path::Path;
+use std::sync::Arc;
+use std::time::Duration;
+
+use anyhow::Context;
+use crossterm::{
+    event::{self, DisableMouseCapture, EnableMouseCapture, Event, KeyCode, KeyModifiers},
+    execute,
+    terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
+};
+use ratatui::{
+    backend::CrosstermBackend,
+    layout::{Constraint, Direction, Layout, Rect},
+    style::{Color, Modifier, Style},
+    text::{Line, Span},
+    widgets::{Block, Borders, List, ListItem, ListState, Paragraph, Wrap},
+    Frame, Terminal,
+};
+use tokio::sync::mpsc;
+use tokio::time::interval;
+
+use crate::{ClientAuth, init_auth};
+use super::commands::{opaque_login, opaque_register};
+use super::conversation::{now_ms, ConversationId, StoredMessage};
+use super::rpc::{
+    connect_node, enqueue, fetch_hybrid_key, fetch_wait, try_hybrid_decrypt, upload_hybrid_key,
+    upload_key_package,
+};
+use super::session::SessionState;
+use super::state::load_or_init_state;
+use super::token_cache::{load_cached_session, save_cached_session};
+
+use quicprochat_core::{
+    AppMessage, DiskKeyStore, GroupMember, IdentityKeypair, ReceivedMessage,
+    hybrid_encrypt, parse as parse_app_msg, serialize_chat,
+};
+use quicprochat_proto::node_capnp::node_service;
+
+// ── App events ───────────────────────────────────────────────────────────────
+
+/// Events sent from background tasks into the main TUI loop.
+enum TuiEvent {
+    /// A key event from the terminal.
+    Key(event::KeyEvent),
+    /// New messages received from the server (conv_id, sender_short, body).
+    NewMessages(Vec<(ConversationId, String, String)>),
+    /// Tick — redraw periodically even if nothing happened.
+    Tick,
+}
+
+// ── Display message ───────────────────────────────────────────────────────────
+
+#[derive(Clone)]
+struct DisplayMessage {
+    sender: String,
+    body: String,
+    timestamp_ms: u64,
+    is_outgoing: bool,
+}
+
+// ── App state ─────────────────────────────────────────────────────────────────
+
+struct App {
+    /// Channel (conversation) names shown in the sidebar.
+    channel_names: Vec<String>,
+    /// Conversation IDs, parallel to `channel_names`.
+    channel_ids: Vec<ConversationId>,
+    /// Index of the selected channel in the sidebar.
+    selected_channel: usize,
+    /// Messages for the currently active channel.
+    messages: Vec<DisplayMessage>,
+    /// Current input buffer.
+    input: String,
+    /// Scroll offset (0 = bottom).
+    scroll_offset: usize,
+    /// Whether the user has requested quit.
+    should_quit: bool,
+    /// Short identity string for display.
+    identity_short: String,
+}
+
+impl App {
+    fn new(session: &SessionState) -> anyhow::Result<Self> {
+        let convs = session.conv_store.list_conversations()?;
+        let channel_names: Vec<String> = convs.iter().map(|c| c.display_name.clone()).collect();
+        let channel_ids: Vec<ConversationId> = convs.iter().map(|c| c.id.clone()).collect();
+
+        Ok(Self {
+            channel_names,
+            channel_ids,
+            selected_channel: 0,
+            messages: Vec::new(),
+            input: String::new(),
+            scroll_offset: 0,
+            should_quit: false,
+            identity_short: session.identity_short(),
+        })
+    }
+
+    fn active_conv_id(&self) -> Option<&ConversationId> {
+        self.channel_ids.get(self.selected_channel)
+    }
+
+    /// Reload messages for the currently selected channel from the session store.
+    fn reload_messages(&mut self, session: &SessionState) -> anyhow::Result<()> {
+        let conv_id = match self.active_conv_id() {
+            Some(id) => id.clone(),
+            None => {
+                self.messages.clear();
+                return Ok(());
+            }
+        };
+        let stored = session.conv_store.load_recent_messages(&conv_id, 200)?;
+        self.messages = stored
+            .into_iter()
+            .map(|m| {
+                let sender = if m.is_outgoing {
+                    format!("me({})", &self.identity_short)
+                } else if let Some(name) = &m.sender_name {
+                    name.clone()
+                } else {
+                    // Shorten sender key to 8 hex chars.
+                    let hex_short = hex::encode(&m.sender_key[..m.sender_key.len().min(4)]);
+                    format!("{hex_short}")
+                };
+                DisplayMessage {
+                    sender,
+                    body: m.body,
+                    timestamp_ms: m.timestamp_ms,
+                    is_outgoing: m.is_outgoing,
+                }
+            })
+            .collect();
+        // Reset scroll to bottom on channel switch.
+        self.scroll_offset = 0;
+        Ok(())
+    }
+
+    fn select_next_channel(&mut self, session: &SessionState) {
+        if self.channel_names.is_empty() {
+            return;
+        }
+        self.selected_channel = (self.selected_channel + 1) % self.channel_names.len();
+        let _ = self.reload_messages(session);
+    }
+
+    fn select_prev_channel(&mut self, session: &SessionState) {
+        if self.channel_names.is_empty() {
+            return;
+        }
+        if self.selected_channel == 0 {
+            self.selected_channel = self.channel_names.len() - 1;
+        } else {
+            self.selected_channel -= 1;
+        }
+        let _ = self.reload_messages(session);
+    }
+
+    fn scroll_up(&mut self) {
+        self.scroll_offset = self.scroll_offset.saturating_add(1);
+    }
+
+    fn scroll_down(&mut self) {
+        self.scroll_offset = self.scroll_offset.saturating_sub(1);
+    }
+
+    /// Append newly received messages to the in-memory list (no DB reload needed
+    /// since we already have them from the poll task, but we also save them via
+    /// the session so they appear on reload).
+    fn append_messages(&mut self, msgs: Vec<(ConversationId, String, String)>) {
+        let active = self.active_conv_id().cloned();
+        for (conv_id, sender, body) in msgs {
+            if active.as_ref() == Some(&conv_id) {
+                self.messages.push(DisplayMessage {
+                    sender,
+                    body,
+                    timestamp_ms: now_ms(),
+                    is_outgoing: false,
+                });
+                // Snap to bottom if user wasn't scrolled.
+                if self.scroll_offset == 0 {
+                    // Already at bottom — nothing to do.
+                }
+            }
+        }
+    }
+}
+
+// ── Drawing ───────────────────────────────────────────────────────────────────
+
+fn ui(frame: &mut Frame, app: &App) {
+    let size = frame.area();
+
+    // Top-level split: sidebar | main area.
+    let h_chunks = Layout::default()
+        .direction(Direction::Horizontal)
+        .constraints([Constraint::Percentage(20), Constraint::Percentage(80)])
+        .split(size);
+
+    // Main area split: messages | input bar.
+    let v_chunks = Layout::default()
+        .direction(Direction::Vertical)
+        .constraints([Constraint::Min(3), Constraint::Length(3)])
+        .split(h_chunks[1]);
+
+    draw_sidebar(frame, app, h_chunks[0]);
+    draw_messages(frame, app, v_chunks[0]);
+    draw_input(frame, app, v_chunks[1]);
+}
+
+fn draw_sidebar(frame: &mut Frame, app: &App, area: Rect) {
+    let items: Vec<ListItem> = app
+        .channel_names
+        .iter()
+        .enumerate()
+        .map(|(i, name)| {
+            let style = if i == app.selected_channel {
+                Style::default()
+                    .fg(Color::Cyan)
+                    .add_modifier(Modifier::BOLD | Modifier::REVERSED)
+            } else {
+                Style::default().fg(Color::Cyan)
+            };
+            ListItem::new(Line::from(Span::styled(name.clone(), style)))
+        })
+        .collect();
+
+    let block = Block::default()
+        .title(" Channels ")
+        .borders(Borders::ALL)
+        .style(Style::default().fg(Color::DarkGray));
+
+    let mut list_state = ListState::default();
+    if !app.channel_names.is_empty() {
+        list_state.select(Some(app.selected_channel));
+    }
+
+    frame.render_stateful_widget(
+        List::new(items).block(block),
+        area,
+        &mut list_state,
+    );
+}
+
+fn draw_messages(frame: &mut Frame, app: &App, area: Rect) {
+    let channel_title = app
+        .channel_names
+        .get(app.selected_channel)
+        .map(|n| format!(" {n} "))
+        .unwrap_or_else(|| " Messages ".to_string());
+
+    let block = Block::default()
+        .title(channel_title)
+        .borders(Borders::ALL)
+        .style(Style::default().fg(Color::DarkGray));
+
+    let inner_height = area.height.saturating_sub(2) as usize;
+
+    // Build lines from messages (newest at bottom).
+    let mut lines: Vec<Line> = app
+        .messages
+        .iter()
+        .map(|m| {
+            let ts = format_timestamp(m.timestamp_ms);
+            let ts_span = Span::styled(ts, Style::default().fg(Color::DarkGray));
+
+            let sender_style = if m.is_outgoing {
+                Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD)
+            } else {
+                Style::default().fg(Color::Green).add_modifier(Modifier::BOLD)
+            };
+            let sender_span = Span::styled(format!(" {} ", m.sender), sender_style);
+            let body_span = Span::raw(m.body.clone());
+
+            Line::from(vec![ts_span, sender_span, body_span])
+        })
+        .collect();
+
+    // Apply scroll: scroll_offset=0 means newest at bottom.
+    let total = lines.len();
+    let visible_start = if total > inner_height {
+        let bottom = total - app.scroll_offset.min(total);
+        bottom.saturating_sub(inner_height)
+    } else {
+        0
+    };
+    let visible_end = if total > inner_height {
+        total - app.scroll_offset.min(total)
+    } else {
+        total
+    };
+    let visible_lines: Vec<Line> = lines
+        .drain(visible_start..visible_end.min(lines.len()))
+        .collect();
+
+    let paragraph = Paragraph::new(visible_lines)
+        .block(block)
+        .wrap(Wrap { trim: false });
+
+    frame.render_widget(paragraph, area);
+}
+
+fn draw_input(frame: &mut Frame, app: &App, area: Rect) {
+    let block = Block::default()
+        .title(" Input (Enter=send, Tab=switch channel, q/Ctrl+C=quit) ")
+        .borders(Borders::ALL)
+        .style(Style::default().fg(Color::DarkGray));
+
+    let input_text = Paragraph::new(app.input.as_str())
+        .block(block)
+        .style(Style::default().fg(Color::White));
+
+    frame.render_widget(input_text, area);
+
+    // Position cursor at end of input.
+    let cursor_x = area.x + 1 + app.input.len() as u16;
+    let cursor_y = area.y + 1;
+    if cursor_x < area.x + area.width - 1 {
+        frame.set_cursor_position((cursor_x, cursor_y));
+    }
+}
+
+fn format_timestamp(ms: u64) -> String {
+    // Simple HH:MM format from epoch ms.
+    let secs = ms / 1000;
+    let hours = (secs / 3600) % 24;
+    let minutes = (secs / 60) % 60;
+    format!("[{:02}:{:02}] ", hours, minutes)
+}
+
+// ── Message polling task ──────────────────────────────────────────────────────
+
+/// Background task that polls the server for new messages and sends them via `tx`.
+async fn poll_task(
+    mut session: SessionState,
+    client: node_service::Client,
+    tx: mpsc::Sender<TuiEvent>,
+) {
+    let mut poll_interval = interval(Duration::from_millis(1000));
+    poll_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+
+    loop {
+        poll_interval.tick().await;
+
+        let identity_bytes = session.identity_bytes();
+        let payloads = match fetch_wait(&client, &identity_bytes, 0).await {
+            Ok(p) => p,
+            Err(_) => continue,
+        };
+
+        if payloads.is_empty() {
+            continue;
+        }
+
+        let mut new_msgs: Vec<(ConversationId, String, String)> = Vec::new();
+        let my_key = session.identity_bytes();
+
+        let mut sorted = payloads;
+        sorted.sort_by_key(|(seq, _)| *seq);
+
+        for (_seq, payload) in &sorted {
+            let mls_payload = match try_hybrid_decrypt(session.hybrid_kp.as_ref(), payload) {
+                Ok(b) => b,
+                Err(_) => payload.clone(),
+            };
+
+            let conv_ids: Vec<ConversationId> = session.members.keys().cloned().collect();
+
+            for conv_id in &conv_ids {
+                let member = match session.members.get_mut(conv_id) {
+                    Some(m) => m,
+                    None => continue,
+                };
+
+                match member.receive_message(&mls_payload) {
+                    Ok(ReceivedMessage::Application(plaintext)) => {
+                        let (sender_key, app_bytes) = {
+                            let after_unpad = quicprochat_core::padding::unpad(&plaintext)
+                                .unwrap_or_else(|_| plaintext.clone());
+
+                            if quicprochat_core::sealed_sender::is_sealed(&after_unpad) {
+                                match quicprochat_core::sealed_sender::unseal(&after_unpad) {
+                                    Ok((sk, inner)) => (sk.to_vec(), inner),
+                                    Err(_) => (my_key.clone(), after_unpad),
+                                }
+                            } else {
+                                (my_key.clone(), after_unpad)
+                            }
+                        };
+
+                        let (body, msg_id, msg_type, ref_msg_id) =
+                            match parse_app_msg(&app_bytes) {
+                                Ok((_, AppMessage::Chat { message_id, body })) => (
+                                    String::from_utf8_lossy(&body).to_string(),
+                                    Some(message_id),
+                                    "chat",
+                                    None,
+                                ),
+                                Ok((_, AppMessage::Reply { ref_msg_id, body })) => (
+                                    String::from_utf8_lossy(&body).to_string(),
+                                    None,
+                                    "reply",
+                                    Some(ref_msg_id),
+                                ),
+                                Ok((_, AppMessage::Reaction { ref_msg_id, emoji })) => (
+                                    String::from_utf8_lossy(&emoji).to_string(),
+                                    None,
+                                    "reaction",
+                                    Some(ref_msg_id),
+                                ),
+                                _ => (
+                                    String::from_utf8_lossy(&app_bytes).to_string(),
+                                    None,
+                                    "chat",
+                                    None,
+                                ),
+                            };
+
+                        let stored = StoredMessage {
+                            conversation_id: conv_id.clone(),
+                            message_id: msg_id,
+                            sender_key: sender_key.clone(),
+                            sender_name: None,
+                            body: body.clone(),
+                            msg_type: msg_type.into(),
+                            ref_msg_id,
+                            timestamp_ms: now_ms(),
+                            is_outgoing: false,
+                        };
+
+                        if session.conv_store.save_message(&stored).is_ok() {
+                            let sender_short = hex::encode(&sender_key[..sender_key.len().min(4)]);
+                            new_msgs.push((conv_id.clone(), sender_short, body));
+                        }
+
+                        let _ = session.conv_store.update_activity(conv_id, now_ms());
+                        let _ = session.save_member(conv_id);
+                        break;
+                    }
+                    Ok(ReceivedMessage::StateChanged) | Ok(ReceivedMessage::SelfRemoved) => {
+                        let _ = session.save_member(conv_id);
+                        break;
+                    }
+                    _ => {}
+                }
+            }
+        }
+
+        if !new_msgs.is_empty() {
+            if tx.send(TuiEvent::NewMessages(new_msgs)).await.is_err() {
+                break;
+            }
+        }
+    }
+}
+
+// ── Send message ──────────────────────────────────────────────────────────────
+
+async fn send_message(
+    session: &mut SessionState,
+    client: &node_service::Client,
+    conv_id: &ConversationId,
+    text: &str,
+) -> anyhow::Result<()> {
+    let my_key = session.identity_bytes();
+    let identity = Arc::clone(&session.identity);
+
+    let member = session
+        .members
+        .get_mut(conv_id)
+        .context("no GroupMember for this conversation")?;
+
+    // Wrap in structured AppMessage format.
+    let app_payload = serialize_chat(text.as_bytes(), None)
+        .context("serialize app message")?;
+
+    // Metadata protection: seal + pad.
+    let sealed = quicprochat_core::sealed_sender::seal(&identity, &app_payload);
+    let padded = quicprochat_core::padding::pad(&sealed);
+
+    let ct = member.send_message(&padded).context("MLS encrypt")?;
+
+    let recipients: Vec<Vec<u8>> = member
+        .member_identities()
+        .into_iter()
+        .filter(|id| id.as_slice() != my_key.as_slice())
+        .collect();
+
+    for recipient_key in &recipients {
+        let peer_hybrid_pk = fetch_hybrid_key(client, recipient_key).await?;
+        let payload = if let Some(ref pk) = peer_hybrid_pk {
+            hybrid_encrypt(pk, &ct, b"", b"").context("hybrid encrypt")?
+        } else {
+            ct.clone()
+        };
+        enqueue(client, recipient_key, &payload).await?;
+    }
+
+    // Extract message_id from what we just serialized.
+    let msg_id = parse_app_msg(&app_payload)
+        .ok()
+        .and_then(|(_, m)| match m {
+            AppMessage::Chat { message_id, .. } => Some(message_id),
+            _ => None,
+        });
+
+    // Save outgoing message.
+    let stored = StoredMessage {
+        conversation_id: conv_id.clone(),
+        message_id: msg_id,
+        sender_key: my_key,
+        sender_name: Some("you".into()),
+        body: text.to_string(),
+        msg_type: "chat".into(),
+        ref_msg_id: None,
+        timestamp_ms: now_ms(),
+        is_outgoing: true,
+    };
+    session.conv_store.save_message(&stored)?;
+    session.conv_store.update_activity(conv_id, now_ms())?;
+    session.save_member(conv_id)?;
+
+    Ok(())
+}
+
+// ── TUI entry point ───────────────────────────────────────────────────────────
+
+/// Entry point for `qpc tui`. Sets up the terminal, runs the event loop, and
+/// restores the terminal on exit.
+pub async fn run_tui(
+    state_path: &Path,
+    server: &str,
+    ca_cert: &Path,
+    server_name: &str,
+    password: Option<&str>,
+    username: Option<&str>,
+    opaque_password: Option<&str>,
+    access_token: &str,
+    device_id: Option<&str>,
+) -> anyhow::Result<()> {
+    // ── Auth ──────────────────────────────────────────────────────────────────
+    let resolved_token = resolve_tui_access_token(
+        state_path,
+        server,
+        ca_cert,
+        server_name,
+        password,
+        username,
+        opaque_password,
+        access_token,
+    )
+    .await?;
+
+    let token_bytes = hex::decode(&resolved_token)
+        .unwrap_or_else(|_| resolved_token.into_bytes());
+    let auth_ctx = ClientAuth::from_raw(token_bytes, device_id.map(String::from));
+    init_auth(auth_ctx);
+
+    // ── Session + RPC ─────────────────────────────────────────────────────────
+    let mut session = SessionState::load(state_path, password)?;
+    let client = connect_node(server, ca_cert, server_name).await?;
+
+    // Auto-upload KeyPackage.
+    let _ = auto_upload_keys_tui(&session, &client).await;
+
+    // ── Terminal setup ────────────────────────────────────────────────────────
+    enable_raw_mode().context("enable raw mode")?;
+    let mut stdout = std::io::stdout();
+    execute!(stdout, EnterAlternateScreen, EnableMouseCapture)
+        .context("enter alternate screen")?;
+    let backend = CrosstermBackend::new(stdout);
+    let mut terminal = Terminal::new(backend).context("create terminal")?;
+
+    let result = tui_loop(&mut terminal, &mut session, client).await;
+
+    // ── Terminal cleanup (always restore, even on error) ───────────────────
+    disable_raw_mode().ok();
+    execute!(
+        terminal.backend_mut(),
+        LeaveAlternateScreen,
+        DisableMouseCapture
+    )
+    .ok();
+    terminal.show_cursor().ok();
+
+    session.save_all()?;
+
+    result
+}
+
+async fn tui_loop(
+    terminal: &mut Terminal<CrosstermBackend<std::io::Stdout>>,
+    session: &mut SessionState,
+    client: node_service::Client,
+) -> anyhow::Result<()> {
+    let mut app = App::new(session)?;
+    app.reload_messages(session)?;
+
+    let (event_tx, mut event_rx) = mpsc::channel::<TuiEvent>(256);
+
+    // ── Keyboard event task ───────────────────────────────────────────────────
+    let key_tx = event_tx.clone();
+    tokio::task::spawn_local(async move {
+        loop {
+            // crossterm event polling — 50ms timeout so we can tick.
+            match event::poll(Duration::from_millis(50)) {
+                Ok(true) => {
+                    if let Ok(Event::Key(key)) = event::read() {
+                        if key_tx.send(TuiEvent::Key(key)).await.is_err() {
+                            break;
+                        }
+                    }
+                }
+                Ok(false) => {
+                    // No event — send a tick so the UI redraws.
+                    if key_tx.send(TuiEvent::Tick).await.is_err() {
+                        break;
+                    }
+                }
+                Err(_) => break,
+            }
+        }
+    });
+
+    // ── Message poll task ─────────────────────────────────────────────────────
+    // Clone session state for the poll task (it needs its own SessionState).
+    let poll_session = SessionState::load(
+        &session.state_path.clone(),
+        session.password.as_ref().map(|p| p.as_str()),
+    )?;
+    let poll_tx = event_tx.clone();
+    tokio::task::spawn_local(poll_task(poll_session, client.clone(), poll_tx));
+
+    // ── Main loop ─────────────────────────────────────────────────────────────
+    loop {
+        terminal.draw(|f| ui(f, &app)).context("draw")?;
+
+        match event_rx.recv().await {
+            None => break,
+            Some(TuiEvent::Tick) => {
+                // Just redraw.
+            }
+            Some(TuiEvent::NewMessages(msgs)) => {
+                app.append_messages(msgs);
+            }
+            Some(TuiEvent::Key(key)) => {
+                match key.code {
+                    KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => {
+                        app.should_quit = true;
+                    }
+                    KeyCode::Char('q') if app.input.is_empty() => {
+                        app.should_quit = true;
+                    }
+                    KeyCode::Enter => {
+                        let text = app.input.trim().to_string();
+                        if !text.is_empty() {
+                            app.input.clear();
+                            if let Some(conv_id) = app.active_conv_id().cloned() {
+                                match send_message(session, &client, &conv_id, &text).await {
+                                    Ok(()) => {
+                                        // Add to in-memory list immediately.
+                                        app.messages.push(DisplayMessage {
+                                            sender: format!("me({})", app.identity_short),
+                                            body: text,
+                                            timestamp_ms: now_ms(),
+                                            is_outgoing: true,
+                                        });
+                                    }
+                                    Err(_e) => {
+                                        // Silently drop — user will see nothing happened.
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    KeyCode::Char(c) => {
+                        app.input.push(c);
+                    }
+                    KeyCode::Backspace => {
+                        app.input.pop();
+                    }
+                    KeyCode::Up => {
+                        app.scroll_up();
+                    }
+                    KeyCode::Down => {
+                        app.scroll_down();
+                    }
+                    KeyCode::Tab => {
+                        if key.modifiers.contains(KeyModifiers::SHIFT) {
+                            app.select_prev_channel(session);
+                        } else {
+                            app.select_next_channel(session);
+                        }
+                        app.reload_messages(session)?;
+                    }
+                    _ => {}
+                }
+            }
+        }
+
+        if app.should_quit {
+            break;
+        }
+    }
+
+    Ok(())
+}
+
+// ── Startup helpers ───────────────────────────────────────────────────────────
+
+async fn auto_upload_keys_tui(
+    session: &SessionState,
+    client: &node_service::Client,
+) -> anyhow::Result<()> {
+    let ks_path = session.state_path.with_extension("pending.ks");
+    let ks = DiskKeyStore::persistent(&ks_path).unwrap_or_else(|_| DiskKeyStore::ephemeral());
+    let mut member = GroupMember::new_with_state(
+        Arc::clone(&session.identity),
+        ks,
+        None,
+        false,
+    );
+    let kp_bytes = member.generate_key_package().context("generate KeyPackage")?;
+    let id_key = session.identity.public_key_bytes();
+    upload_key_package(client, &id_key, &kp_bytes).await?;
+    if let Some(ref hkp) = session.hybrid_kp {
+        upload_hybrid_key(client, &id_key, &hkp.public_key()).await?;
+    }
+    Ok(())
+}
+
+async fn resolve_tui_access_token(
+    state_path: &Path,
+    server: &str,
+    ca_cert: &Path,
+    server_name: &str,
+    state_password: Option<&str>,
+    username: Option<&str>,
+    opaque_password: Option<&str>,
+    cli_access_token: &str,
+) -> anyhow::Result<String> {
+    if !cli_access_token.is_empty() {
+        return Ok(cli_access_token.to_string());
+    }
+
+    if let Some(cached) = load_cached_session(state_path, state_password) {
+        return Ok(cached.token_hex);
+    }
+
+    let username = match username {
+        Some(u) => u.to_string(),
+        None => {
+            use std::io::Write;
+            eprint!("Username: ");
+            std::io::stderr().flush().ok();
+            let mut input = String::new();
+            std::io::stdin()
+                .read_line(&mut input)
+                .context("failed to read username")?;
+            let trimmed = input.trim().to_string();
+            anyhow::ensure!(!trimmed.is_empty(), "username is required");
+            trimmed
+        }
+    };
+
+    let opaque_password = match opaque_password {
+        Some(p) => p.to_string(),
+        None => rpassword::read_password().context("failed to read password")?,
+    };
+
+    let state = load_or_init_state(state_path, state_password)?;
+    let identity = IdentityKeypair::from_seed(state.identity_seed);
+    let identity_key = identity.public_key_bytes().to_vec();
+
+    let node_client = connect_node(server, ca_cert, server_name).await?;
+
+    match opaque_register(&node_client, &username, &opaque_password, Some(&identity_key)).await {
+        Ok(()) | Err(_) => {}
+    }
+
+    let token_bytes = opaque_login(&node_client, &username, &opaque_password, &identity_key)
+        .await
+        .context("OPAQUE login failed")?;
+    let token_hex = hex::encode(&token_bytes);
+
+    save_cached_session(state_path, &username, &token_hex, state_password)?;
+
+    Ok(token_hex)
+}

crates/quicprochat-client/src/lib.rs

@@ -0,0 +1,177 @@
+//! quicprochat CLI client library.
+//!
+//! # KeyPackage expiry and refresh
+//!
+//! KeyPackages are single-use (consumed when someone fetches them for an invite) and the server
+//! may enforce a TTL (e.g. 24 hours). To stay invitable, run `qpc refresh-keypackage`
+//! periodically (e.g. before the server TTL) or after your KeyPackage was consumed:
+//!
+//! ```bash
+//! qpc refresh-keypackage --state qpc-state.bin --server 127.0.0.1:7000
+//! ```
+//!
+//! Use the same `--access-token` (or `QPQ_ACCESS_TOKEN`) as for other authenticated
+//! commands. See the [running-the-client](https://docs.quicprochat.dev/getting-started/running-the-client)
+//! docs for details.
+
+use std::sync::RwLock;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use zeroize::Zeroizing;
+
+pub mod client;
+#[cfg(feature = "v2")]
+pub mod v2_commands;
+
+pub use client::commands::{
+    cmd_chat, cmd_check_key, cmd_create_group, cmd_demo_group, cmd_export, cmd_export_verify,
+    cmd_fetch_key, cmd_health, cmd_health_json, cmd_invite, cmd_join, cmd_login, cmd_ping,
+    cmd_recv, cmd_register, cmd_register_state, cmd_refresh_keypackage, cmd_register_user,
+    cmd_send, cmd_whoami, opaque_login, receive_pending_plaintexts, whoami_json,
+};
+
+pub use client::command_engine::{Command, CommandRegistry, CommandResult};
+#[cfg(feature = "playbook")]
+pub use client::playbook::{Playbook, PlaybookReport, PlaybookRunner};
+pub use client::repl::run_repl;
+pub use client::rpc::{connect_node, connect_node_opt, create_channel, enqueue, fetch_wait, resolve_user};
+
+// ── ClientContext: structured holder for session-scoped auth + TLS config ────
+
+/// Holds the authentication credentials and TLS policy for a client session.
+///
+/// Prefer constructing a `ClientContext` and passing it explicitly where
+/// possible. The global `AUTH_CONTEXT` / `INSECURE_SKIP_VERIFY` statics
+/// delegate to a `ClientContext` under the hood and exist only for backward
+/// compatibility with call-sites that have not yet been migrated.
+pub struct ClientContext {
+    auth: RwLock<Option<ClientAuth>>,
+    insecure_skip_verify: AtomicBool,
+}
+
+impl ClientContext {
+    /// Create a new context with no auth and TLS verification enabled.
+    pub fn new() -> Self {
+        Self {
+            auth: RwLock::new(None),
+            insecure_skip_verify: AtomicBool::new(false),
+        }
+    }
+
+    /// Create a context pre-loaded with auth credentials.
+    pub fn with_auth(auth: ClientAuth) -> Self {
+        Self {
+            auth: RwLock::new(Some(auth)),
+            insecure_skip_verify: AtomicBool::new(false),
+        }
+    }
+
+    /// Set (or replace) the auth credentials.
+    ///
+    /// # Panics
+    /// Panics if the RwLock is poisoned (a thread panicked while holding it).
+    /// A poisoned lock indicates unrecoverable state corruption.
+    #[allow(clippy::expect_used)]
+    pub fn set_auth(&self, ctx: ClientAuth) {
+        let mut guard = self.auth.write().expect("ClientContext auth lock poisoned");
+        *guard = Some(ctx);
+    }
+
+    /// Read the current auth snapshot (cloned).
+    ///
+    /// # Panics
+    /// Panics if the RwLock is poisoned (a thread panicked while holding it).
+    /// A poisoned lock indicates unrecoverable state corruption.
+    #[allow(clippy::expect_used)]
+    pub fn get_auth(&self) -> Option<ClientAuth> {
+        let guard = self.auth.read().expect("ClientContext auth lock poisoned");
+        guard.clone()
+    }
+
+    /// Returns true if auth credentials have been set.
+    ///
+    /// # Panics
+    /// Panics if the RwLock is poisoned (a thread panicked while holding it).
+    /// A poisoned lock indicates unrecoverable state corruption.
+    #[allow(clippy::expect_used)]
+    pub fn is_authenticated(&self) -> bool {
+        let guard = self.auth.read().expect("ClientContext auth lock poisoned");
+        guard.is_some()
+    }
+
+    /// Enable or disable insecure TLS mode.
+    pub fn set_insecure_skip_verify(&self, enabled: bool) {
+        self.insecure_skip_verify.store(enabled, Ordering::Relaxed);
+    }
+
+    /// Read the current insecure-skip-verify flag.
+    pub fn insecure_skip_verify(&self) -> bool {
+        self.insecure_skip_verify.load(Ordering::Relaxed)
+    }
+}
+
+impl Default for ClientContext {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+// ── Global statics (thin wrappers, kept for backward compat) ─────────────────
+
+/// Global auth context — delegates to a process-wide `ClientContext`.
+/// Prefer passing `&ClientContext` explicitly in new code.
+pub(crate) static AUTH_CONTEXT: RwLock<Option<ClientAuth>> = RwLock::new(None);
+
+/// When `true`, [`connect_node`] skips TLS certificate verification.
+/// Prefer `ClientContext::set_insecure_skip_verify` in new code.
+pub(crate) static INSECURE_SKIP_VERIFY: AtomicBool = AtomicBool::new(false);
+
+/// Enable or disable insecure (no-verify) TLS mode globally.
+///
+/// **Development only.** When enabled, all outgoing connections skip certificate
+/// verification, making them vulnerable to MITM attacks.
+pub fn set_insecure_skip_verify(enabled: bool) {
+    INSECURE_SKIP_VERIFY.store(enabled, Ordering::Relaxed);
+}
+
+#[derive(Clone, Debug)]
+pub struct ClientAuth {
+    pub(crate) version: u16,
+    /// Bearer or OPAQUE session token. Zeroized on drop. (M8)
+    pub(crate) access_token: Zeroizing<Vec<u8>>,
+    pub(crate) device_id: Vec<u8>,
+}
+
+impl ClientAuth {
+    /// Build a client auth context from optional token and device id.
+    pub fn from_parts(access_token: String, device_id: Option<String>) -> Self {
+        let token = access_token.into_bytes();
+        let device = device_id.unwrap_or_default().into_bytes();
+        Self {
+            version: 1,
+            access_token: Zeroizing::new(token),
+            device_id: device,
+        }
+    }
+
+    /// Build from raw token bytes (e.g. a 32-byte OPAQUE session token).
+    pub fn from_raw(raw_token: Vec<u8>, device_id: Option<String>) -> Self {
+        let device = device_id.unwrap_or_default().into_bytes();
+        Self {
+            version: 1,
+            access_token: Zeroizing::new(raw_token),
+            device_id: device,
+        }
+    }
+}
+
+/// Set (or replace) the global auth context.
+///
+/// # Panics
+/// Panics if the RwLock is poisoned (a thread panicked while holding it).
+/// A poisoned lock indicates unrecoverable state corruption.
+#[allow(clippy::expect_used)]
+pub fn init_auth(ctx: ClientAuth) {
+    let mut guard = AUTH_CONTEXT.write().expect("AUTH_CONTEXT poisoned");
+    *guard = Some(ctx);
+}

crates/quicprochat-client/src/main.rs

@@ -0,0 +1,883 @@
+//! quicprochat CLI client.
+
+// ── v2 feature gate: when compiled with --features v2, use the SDK-based CLI.
+#[cfg(feature = "v2")]
+mod v2_commands;
+#[cfg(feature = "v2")]
+mod v2_main;
+
+#[cfg(feature = "v2")]
+fn main() {
+    v2_main::main();
+}
+
+// ── v1 CLI (default) ─────────────────────────────────────────────────────────
+#[cfg(not(feature = "v2"))]
+use std::path::{Path, PathBuf};
+#[cfg(not(feature = "v2"))]
+use anyhow::Context;
+#[cfg(not(feature = "v2"))]
+use clap::{Parser, Subcommand};
+#[cfg(not(feature = "v2"))]
+use quicprochat_client::{
+    cmd_chat, cmd_check_key, cmd_create_group, cmd_demo_group, cmd_export, cmd_export_verify,
+    cmd_fetch_key, cmd_health, cmd_invite, cmd_join, cmd_login, cmd_ping, cmd_recv, cmd_register,
+    cmd_register_state, cmd_refresh_keypackage, cmd_register_user, cmd_send, cmd_whoami,
+    init_auth, run_repl, set_insecure_skip_verify, ClientAuth,
+};
+#[cfg(all(feature = "tui", not(feature = "v2")))]
+use quicprochat_client::client::tui::run_tui;
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+#[cfg(not(feature = "v2"))]
+
+#[derive(Debug, Parser)]
+#[command(name = "qpc", about = "quicprochat CLI client", version)]
+struct Args {
+    /// Path to the server's TLS certificate (self-signed by default).
+    #[arg(
+        long,
+        global = true,
+        default_value = "data/server-cert.der",
+        env = "QPQ_CA_CERT"
+    )]
+    ca_cert: PathBuf,
+
+    /// Expected TLS server name (must match the certificate SAN).
+    #[arg(
+        long,
+        global = true,
+        default_value = "localhost",
+        env = "QPQ_SERVER_NAME"
+    )]
+    server_name: String,
+
+    /// Bearer token or OPAQUE session token for authenticated requests.
+    /// Not required for register-user and login commands.
+    #[arg(
+        long,
+        global = true,
+        env = "QPQ_ACCESS_TOKEN",
+        default_value = ""
+    )]
+    access_token: String,
+
+    /// Optional device identifier (UUID bytes encoded as hex or raw string).
+    #[arg(long, global = true, env = "QPQ_DEVICE_ID")]
+    device_id: Option<String>,
+
+    /// Password to encrypt/decrypt client state files (QPCE format).
+    /// If set, state files are encrypted at rest with Argon2id + ChaCha20Poly1305.
+    #[arg(long, global = true, env = "QPQ_STATE_PASSWORD")]
+    state_password: Option<String>,
+
+    /// DANGER: Skip TLS certificate verification. Development only.
+    /// Disables all certificate checks, making the connection vulnerable to MITM attacks.
+    #[arg(
+        long = "danger-accept-invalid-certs",
+        global = true,
+        env = "QPQ_DANGER_ACCEPT_INVALID_CERTS"
+    )]
+    danger_accept_invalid_certs: bool,
+
+    // ── Default-repl args (used when no subcommand is given) ─────────
+    /// State file path (identity + MLS state). Used when running the default REPL.
+    #[arg(long, default_value = "qpc-state.bin", env = "QPQ_STATE")]
+    state: PathBuf,
+
+    /// Server address (host:port). Used when running the default REPL.
+    #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+    server: String,
+
+    /// OPAQUE username for automatic registration/login.
+    #[arg(long, env = "QPQ_USERNAME")]
+    username: Option<String>,
+
+    /// OPAQUE password (prompted securely if --username is set but --password is not).
+    #[arg(long, env = "QPQ_PASSWORD")]
+    password: Option<String>,
+
+    /// Do not auto-start a local qpc-server (useful when connecting to a remote server).
+    #[arg(long, env = "QPQ_NO_SERVER")]
+    no_server: bool,
+
+    #[command(subcommand)]
+    command: Option<Command>,
+}
+
+#[cfg(not(feature = "v2"))]
+#[derive(Debug, Subcommand)]
+enum Command {
+    /// Register a new user via OPAQUE (password never leaves the client).
+    RegisterUser {
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+        /// Username for the new account.
+        #[arg(long)]
+        username: String,
+        /// Password (will be used in OPAQUE PAKE; server never sees it).
+        #[arg(long)]
+        password: String,
+    },
+
+    /// Log in via OPAQUE and receive a session token.
+    Login {
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+        #[arg(long)]
+        username: String,
+        #[arg(long)]
+        password: String,
+        /// Hex-encoded Ed25519 identity key (64 hex chars). Optional if --state is provided.
+        #[arg(long)]
+        identity_key: Option<String>,
+        /// State file to derive the identity key (requires same password if encrypted).
+        #[arg(long)]
+        state: Option<PathBuf>,
+        /// Password for the encrypted state file (if any).
+        #[arg(long)]
+        state_password: Option<String>,
+    },
+
+    /// Show local identity key, fingerprint, group status, and hybrid key status.
+    Whoami {
+        /// State file path (identity + MLS state).
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+    },
+
+    /// Check server connectivity and print status.
+    Health {
+        /// Server address (host:port).
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+    },
+
+    /// Check if a peer has registered a hybrid key (non-consuming lookup).
+    CheckKey {
+        /// Server address (host:port).
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+
+        /// Peer's Ed25519 identity public key (64 hex chars = 32 bytes).
+        identity_key: String,
+    },
+
+    /// Send a Ping to the server and print the round-trip time.
+    Ping {
+        /// Server address (host:port).
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+    },
+
+    /// Generate a fresh MLS KeyPackage and upload it to the Authentication Service.
+    Register {
+        /// Server address (host:port).
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+    },
+
+    /// Fetch a peer's KeyPackage from the Authentication Service.
+    FetchKey {
+        /// Server address (host:port).
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+
+        /// Target peer's Ed25519 identity public key (64 hex chars = 32 bytes).
+        identity_key: String,
+    },
+
+    /// Run a two-party MLS demo (creator + joiner) against live AS and DS.
+    DemoGroup {
+        /// Server address (host:port).
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+    },
+
+    /// Upload the persistent identity's KeyPackage to the AS (uses state file).
+    RegisterState {
+        /// State file path (identity + MLS state).
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+
+        /// Authentication Service address (host:port).
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+    },
+
+    /// Refresh the KeyPackage on the server (existing state only).
+    /// Run periodically (e.g. before server TTL ~24h) or after your KeyPackage was consumed so others can invite you.
+    RefreshKeypackage {
+        /// State file path (identity + MLS state).
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+
+        /// Server address (host:port).
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+    },
+
+    /// Create a persistent group and save state to disk.
+    CreateGroup {
+        /// State file path (identity + MLS state).
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+
+        /// Server address (host:port).
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+
+        /// Group identifier (arbitrary bytes, typically a human-readable name).
+        #[arg(long)]
+        group_id: String,
+    },
+
+    /// Invite a peer into the group and deliver a Welcome via DS.
+    Invite {
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+        /// Peer identity public key (64 hex chars = 32 bytes).
+        #[arg(long)]
+        peer_key: String,
+    },
+
+    /// Join a group by fetching the Welcome from the DS.
+    Join {
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+    },
+
+    /// Send an application message via the DS.
+    Send {
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+        /// Recipient identity key (hex, 32 bytes -> 64 chars). Omit when using --all.
+        #[arg(long)]
+        peer_key: Option<String>,
+        /// Send to all other group members (N-way groups).
+        #[arg(long)]
+        all: bool,
+        /// Plaintext message to send.
+        #[arg(long)]
+        msg: String,
+    },
+
+    /// Receive and decrypt all pending messages from the DS.
+    Recv {
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+
+        /// Wait for up to this many milliseconds if no messages are queued.
+        #[arg(long, default_value_t = 0)]
+        wait_ms: u64,
+
+        /// Continuously long-poll for messages.
+        #[arg(long)]
+        stream: bool,
+    },
+
+    /// Interactive multi-conversation REPL. Supports /dm, /create-group, /invite, /join, /switch, and more.
+    /// Automatically registers and logs in if --username/--password are provided (or prompts interactively).
+    Repl {
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+        /// OPAQUE username for automatic registration/login.
+        #[arg(long, env = "QPQ_USERNAME")]
+        username: Option<String>,
+        /// OPAQUE password (prompted securely if --username is set but --password is not).
+        #[arg(long, env = "QPQ_PASSWORD")]
+        password: Option<String>,
+        /// Do not auto-start a local qpc-server.
+        #[arg(long, env = "QPQ_NO_SERVER")]
+        no_server: bool,
+    },
+
+    /// Full-screen Ratatui TUI (requires --features tui).
+    /// Channels sidebar, scrollable message view, and inline input bar.
+    #[cfg(feature = "tui")]
+    Tui {
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+        /// OPAQUE username for automatic registration/login.
+        #[arg(long, env = "QPQ_USERNAME")]
+        username: Option<String>,
+        /// OPAQUE password (prompted securely if --username is set but --password is not).
+        #[arg(long, env = "QPQ_PASSWORD")]
+        password: Option<String>,
+    },
+
+    /// Interactive 1:1 chat: type to send, incoming messages printed as [peer] <msg>. Ctrl+D to exit.
+    /// In a two-person group, peer is chosen automatically; use --peer-key only with 3+ members.
+    Chat {
+        #[arg(
+            long,
+            default_value = "qpc-state.bin",
+            env = "QPQ_STATE"
+        )]
+        state: PathBuf,
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+        /// Peer identity key (hex, 64 chars). Omit in a two-person group to use the only other member.
+        #[arg(long)]
+        peer_key: Option<String>,
+        /// How often to poll for incoming messages (milliseconds).
+        #[arg(long, default_value_t = 500)]
+        poll_interval_ms: u64,
+    },
+
+    /// Export a conversation's message history to an encrypted, tamper-evident transcript file.
+    ///
+    /// The output file uses Argon2id + ChaCha20-Poly1305 encryption with a SHA-256 hash chain
+    /// linking every record. Use `qpc export verify` to check chain integrity without decrypting.
+    Export {
+        /// Path to the conversation database (.convdb file).
+        #[arg(long, default_value = "qpc-convdb.sqlite", env = "QPQ_CONV_DB")]
+        conv_db: PathBuf,
+
+        /// Conversation ID to export (32 hex chars = 16 bytes).
+        #[arg(long)]
+        conv_id: String,
+
+        /// Output path for the .qpct transcript file.
+        #[arg(long, default_value = "transcript.qpct")]
+        output: PathBuf,
+
+        /// Password used to encrypt the transcript (separate from the state/DB password).
+        #[arg(long, env = "QPQ_TRANSCRIPT_PASSWORD")]
+        transcript_password: Option<String>,
+
+        /// Password for the encrypted conversation database (if any).
+        #[arg(long, env = "QPQ_STATE_PASSWORD")]
+        db_password: Option<String>,
+    },
+
+    /// Verify the hash-chain integrity of a transcript file without decrypting content.
+    ExportVerify {
+        /// Path to the .qpct transcript file to verify.
+        #[arg(long)]
+        input: PathBuf,
+    },
+
+    /// Execute a YAML playbook (scripted command sequence) and exit.
+    /// Requires `--features playbook`.
+    #[cfg(feature = "playbook")]
+    Run {
+        /// Path to the YAML playbook file.
+        playbook: PathBuf,
+
+        /// State file path (identity + MLS state).
+        #[arg(long, default_value = "qpc-state.bin", env = "QPQ_STATE")]
+        state: PathBuf,
+
+        /// Server address (host:port).
+        #[arg(long, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+        server: String,
+
+        /// OPAQUE username for automatic login.
+        #[arg(long, env = "QPQ_USERNAME")]
+        username: Option<String>,
+
+        /// OPAQUE password.
+        #[arg(long, env = "QPQ_PASSWORD")]
+        password: Option<String>,
+
+        /// Override playbook variables: KEY=VALUE (repeatable).
+        #[arg(long = "var", short = 'V')]
+        vars: Vec<String>,
+    },
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+#[cfg(not(feature = "v2"))]
+/// Returns `qpc-{username}.bin` when `state` is still at the default
+/// (`qpc-state.bin`) and a username has been provided. Otherwise returns
+/// `state` unchanged. This lets `qpc --username alice` automatically isolate
+/// Alice's state without requiring a manual `--state` flag.
+fn derive_state_path(state: PathBuf, username: Option<&str>) -> PathBuf {
+    if state == Path::new("qpc-state.bin") {
+        if let Some(uname) = username {
+            return PathBuf::from(format!("qpc-{uname}.bin"));
+        }
+    }
+    state
+}
+
+// ── Playbook execution ───────────────────────────────────────────────────────
+
+#[cfg(all(feature = "playbook", not(feature = "v2")))]
+async fn run_playbook(
+    playbook_path: &Path,
+    state: &Path,
+    server: &str,
+    ca_cert: &Path,
+    server_name: &str,
+    state_pw: Option<&str>,
+    username: Option<&str>,
+    password: Option<&str>,
+    access_token: &str,
+    device_id: Option<&str>,
+    extra_vars: &[String],
+) -> anyhow::Result<()> {
+    use quicprochat_client::PlaybookRunner;
+
+    let insecure = std::env::var("QPQ_DANGER_ACCEPT_INVALID_CERTS").is_ok();
+
+    // Connect to server.
+    let client =
+        quicprochat_client::connect_node_opt(server, ca_cert, server_name, insecure)
+            .await
+            .context("connect to server")?;
+
+    // Build session state.
+    let mut session = quicprochat_client::client::session::SessionState::load(state, state_pw)
+        .context("load session state")?;
+
+    // If username/password provided, do OPAQUE login.
+    if let (Some(uname), Some(pw)) = (username, password) {
+        if let Err(e) =
+            quicprochat_client::opaque_login(&client, uname, pw, &session.identity.public_key_bytes()).await
+        {
+            eprintln!("OPAQUE login failed: {e:#}");
+        }
+    } else if !access_token.is_empty() {
+        let auth = ClientAuth::from_parts(access_token.to_string(), device_id.map(String::from));
+        init_auth(auth);
+    }
+
+    // Load playbook.
+    let mut runner = PlaybookRunner::from_file(playbook_path)
+        .with_context(|| format!("load playbook: {}", playbook_path.display()))?;
+
+    // Inject extra variables from --var KEY=VALUE flags.
+    for kv in extra_vars {
+        if let Some((k, v)) = kv.split_once('=') {
+            runner.set_var(k, v);
+        } else {
+            eprintln!("warning: ignoring malformed --var '{kv}' (expected KEY=VALUE)");
+        }
+    }
+
+    // Inject connection info as variables.
+    runner.set_var("_server", server);
+    if let Some(u) = username {
+        runner.set_var("_username", u);
+    }
+
+    let report = runner.run(&mut session, &client).await;
+    print!("{report}");
+
+    if report.all_passed() {
+        Ok(())
+    } else {
+        std::process::exit(1);
+    }
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+#[cfg(not(feature = "v2"))]
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // Install the rustls crypto provider before any TLS operations.
+    let _ = rustls::crypto::ring::default_provider().install_default();
+
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("warn")),
+        )
+        .init();
+
+    let args = Args::parse();
+
+    if args.danger_accept_invalid_certs {
+        eprintln!("WARNING: TLS verification disabled — insecure mode");
+        set_insecure_skip_verify(true);
+    }
+
+    // For the REPL and TUI, defer init_auth so they can resolve their own token via OPAQUE.
+    // For all other subcommands, initialize auth immediately.
+    #[cfg(not(feature = "tui"))]
+    let is_repl = matches!(args.command, None | Some(Command::Repl { .. }));
+    #[cfg(feature = "tui")]
+    let is_repl = matches!(args.command, None | Some(Command::Repl { .. }) | Some(Command::Tui { .. }));
+    if !is_repl {
+        let auth_ctx = ClientAuth::from_parts(args.access_token.clone(), args.device_id.clone());
+        init_auth(auth_ctx);
+    }
+
+    let state_pw = args.state_password.as_deref();
+
+    // Default to REPL when no subcommand is given.
+    let no_server = args.no_server;
+    let command = args.command.unwrap_or_else(|| Command::Repl {
+        state: derive_state_path(args.state, args.username.as_deref()),
+        server: args.server,
+        username: args.username,
+        password: args.password,
+        no_server,
+    });
+
+    match command {
+        Command::RegisterUser {
+            server,
+            username,
+            password,
+        } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_register_user(
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    &username,
+                    &password,
+                    None,
+                ))
+                .await
+        }
+        Command::Login {
+            server,
+            username,
+            password,
+            identity_key,
+            state,
+            state_password,
+        } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_login(
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    &username,
+                    &password,
+                    identity_key.as_deref(),
+                    state.as_deref(),
+                    state_password.as_deref(),
+                ))
+                .await
+        }
+        Command::Whoami { state } => cmd_whoami(&state, state_pw),
+        Command::Health { server } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_health(&server, &args.ca_cert, &args.server_name))
+                .await
+        }
+        Command::CheckKey {
+            server,
+            identity_key,
+        } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_check_key(
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    &identity_key,
+                ))
+                .await
+        }
+        Command::Ping { server } => cmd_ping(&server, &args.ca_cert, &args.server_name).await,
+        Command::Register { server } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_register(&server, &args.ca_cert, &args.server_name))
+                .await
+        }
+        Command::FetchKey {
+            server,
+            identity_key,
+        } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_fetch_key(
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    &identity_key,
+                ))
+                .await
+        }
+        Command::DemoGroup { server } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_demo_group(&server, &args.ca_cert, &args.server_name))
+                .await
+        }
+        Command::RegisterState { state, server } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_register_state(
+                    &state,
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    state_pw,
+                ))
+                .await
+        }
+        Command::RefreshKeypackage { state, server } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_refresh_keypackage(
+                    &state,
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    state_pw,
+                ))
+                .await
+        }
+        Command::CreateGroup {
+            state,
+            server,
+            group_id,
+        } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_create_group(&state, &server, &group_id, state_pw))
+                .await
+        }
+        Command::Invite {
+            state,
+            server,
+            peer_key,
+        } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_invite(
+                    &state,
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    &peer_key,
+                    state_pw,
+                ))
+                .await
+        }
+        Command::Join { state, server } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_join(
+                    &state,
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    state_pw,
+                ))
+                .await
+        }
+        Command::Send {
+            state,
+            server,
+            peer_key,
+            all,
+            msg,
+        } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_send(
+                    &state,
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    peer_key.as_deref(),
+                    all,
+                    &msg,
+                    state_pw,
+                ))
+                .await
+        }
+        Command::Recv {
+            state,
+            server,
+            wait_ms,
+            stream,
+        } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_recv(
+                    &state,
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    wait_ms,
+                    stream,
+                    state_pw,
+                ))
+                .await
+        }
+        Command::Repl {
+            state,
+            server,
+            username,
+            password,
+            no_server,
+        } => {
+            let state = derive_state_path(state, username.as_deref());
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(run_repl(
+                    &state,
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    state_pw,
+                    username.as_deref(),
+                    password.as_deref(),
+                    &args.access_token,
+                    args.device_id.as_deref(),
+                    no_server,
+                ))
+                .await
+        }
+        Command::Chat {
+            state,
+            server,
+            peer_key,
+            poll_interval_ms,
+        } => {
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(cmd_chat(
+                    &state,
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    peer_key.as_deref(),
+                    state_pw,
+                    poll_interval_ms,
+                ))
+                .await
+        }
+        #[cfg(feature = "tui")]
+        Command::Tui {
+            state,
+            server,
+            username,
+            password,
+        } => {
+            let state = derive_state_path(state, username.as_deref());
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(run_tui(
+                    &state,
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    state_pw,
+                    username.as_deref(),
+                    password.as_deref(),
+                    &args.access_token,
+                    args.device_id.as_deref(),
+                ))
+                .await
+        }
+        Command::Export {
+            conv_db,
+            conv_id,
+            output,
+            transcript_password,
+            db_password,
+        } => {
+            // Prompt for transcript password if not provided.
+            let tp = match transcript_password {
+                Some(p) => p,
+                None => {
+                    eprint!("Transcript password: ");
+                    rpassword::read_password()
+                        .context("failed to read transcript password")?
+                }
+            };
+            cmd_export(
+                &conv_db,
+                &conv_id,
+                &output,
+                &tp,
+                db_password.as_deref().or(state_pw),
+            )
+        }
+        Command::ExportVerify { input } => cmd_export_verify(&input),
+        #[cfg(feature = "playbook")]
+        Command::Run {
+            playbook,
+            state,
+            server,
+            username,
+            password,
+            vars,
+        } => {
+            let state = derive_state_path(state, username.as_deref());
+            let local = tokio::task::LocalSet::new();
+            local
+                .run_until(run_playbook(
+                    &playbook,
+                    &state,
+                    &server,
+                    &args.ca_cert,
+                    &args.server_name,
+                    state_pw,
+                    username.as_deref(),
+                    password.as_deref(),
+                    &args.access_token,
+                    args.device_id.as_deref(),
+                    &vars,
+                ))
+                .await
+        }
+    }
+}

crates/quicprochat-client/src/v2_commands.rs

@@ -0,0 +1,228 @@
+//! v2 CLI command implementations — thin wrappers over the SDK.
+
+use quicprochat_sdk::client::QpqClient;
+use quicprochat_sdk::error::SdkError;
+
+/// Register a new user account via OPAQUE.
+pub async fn cmd_register_user(
+    client: &mut QpqClient,
+    username: &str,
+    password: &str,
+) -> Result<(), SdkError> {
+    client.register(username, password).await?;
+    let key = client.identity_key().unwrap_or_default();
+    println!("registered user: {username}");
+    println!("identity key  : {}", hex::encode(key));
+    Ok(())
+}
+
+/// Log in via OPAQUE and print session info.
+pub async fn cmd_login(
+    client: &mut QpqClient,
+    username: &str,
+    password: &str,
+) -> Result<(), SdkError> {
+    client.login(username, password).await?;
+    println!("logged in as: {username}");
+    if let Some(key) = client.identity_key() {
+        println!("identity key: {}", hex::encode(key));
+    }
+    Ok(())
+}
+
+/// Print local identity information.
+pub fn cmd_whoami(client: &QpqClient) {
+    match client.username() {
+        Some(u) => println!("username    : {u}"),
+        None => println!("username    : (not logged in)"),
+    }
+    match client.identity_key() {
+        Some(k) => println!("identity key: {}", hex::encode(k)),
+        None => println!("identity key: (none)"),
+    }
+    println!("connected   : {}", client.is_connected());
+    println!("authenticated: {}", client.is_authenticated());
+}
+
+/// Health check — connect to the server and report status.
+pub async fn cmd_health(client: &mut QpqClient) -> Result<(), SdkError> {
+    let start = std::time::Instant::now();
+    // The SDK connect() already establishes a QUIC connection.
+    // If we're already connected, just report success.
+    if !client.is_connected() {
+        client.connect().await?;
+    }
+    let rtt_ms = start.elapsed().as_millis();
+    println!("status : ok");
+    println!("rtt    : {rtt_ms}ms");
+    Ok(())
+}
+
+/// Resolve a username to its identity key.
+pub async fn cmd_resolve(client: &mut QpqClient, username: &str) -> Result<(), SdkError> {
+    let rpc = client.rpc()?;
+    match quicprochat_sdk::users::resolve_user(rpc, username).await? {
+        Some(key) => {
+            println!("{username} -> {}", hex::encode(&key));
+        }
+        None => {
+            println!("{username}: not found");
+        }
+    }
+    Ok(())
+}
+
+/// List registered devices.
+pub async fn cmd_devices_list(client: &mut QpqClient) -> Result<(), SdkError> {
+    let rpc = client.rpc()?;
+    let devices = quicprochat_sdk::devices::list_devices(rpc).await?;
+    if devices.is_empty() {
+        println!("no devices registered");
+    } else {
+        println!("{:<36}  {:<20}  {}", "DEVICE ID", "NAME", "REGISTERED AT");
+        for d in &devices {
+            println!(
+                "{:<36}  {:<20}  {}",
+                hex::encode(&d.device_id),
+                d.device_name,
+                d.registered_at,
+            );
+        }
+    }
+    Ok(())
+}
+
+/// Register a new device.
+pub async fn cmd_devices_register(
+    client: &mut QpqClient,
+    device_id: &str,
+    device_name: &str,
+) -> Result<(), SdkError> {
+    let rpc = client.rpc()?;
+    let id_bytes = hex::decode(device_id)
+        .map_err(|e| SdkError::Other(anyhow::anyhow!("invalid device_id hex: {e}")))?;
+    let was_new = quicprochat_sdk::devices::register_device(rpc, &id_bytes, device_name).await?;
+    if was_new {
+        println!("device registered: {device_name}");
+    } else {
+        println!("device already registered: {device_name}");
+    }
+    Ok(())
+}
+
+/// Revoke a device.
+pub async fn cmd_devices_revoke(
+    client: &mut QpqClient,
+    device_id: &str,
+) -> Result<(), SdkError> {
+    let rpc = client.rpc()?;
+    let id_bytes = hex::decode(device_id)
+        .map_err(|e| SdkError::Other(anyhow::anyhow!("invalid device_id hex: {e}")))?;
+    let revoked = quicprochat_sdk::devices::revoke_device(rpc, &id_bytes).await?;
+    if revoked {
+        println!("device revoked: {device_id}");
+    } else {
+        println!("device not found: {device_id}");
+    }
+    Ok(())
+}
+
+/// Set up account recovery — generate codes and upload encrypted bundles.
+pub async fn cmd_recovery_setup(client: &mut QpqClient) -> Result<(), SdkError> {
+    // Load identity seed from state file.
+    let state_path = client.config_state_path();
+    let stored = quicprochat_sdk::state::load_state(&state_path, None)
+        .map_err(|e| SdkError::Crypto(format!("load identity for recovery: {e}")))?;
+
+    let rpc = client.rpc()?;
+    let codes =
+        quicprochat_sdk::recovery::setup_recovery(rpc, &stored.identity_seed, &[]).await?;
+
+    println!("=== RECOVERY CODES ===");
+    println!("Save these codes securely. They will NOT be shown again.");
+    println!("Each code can independently recover your account.");
+    println!();
+    for (i, code) in codes.iter().enumerate() {
+        println!("  {}. {}", i + 1, code);
+    }
+    println!();
+    println!("{} codes generated and uploaded.", codes.len());
+    Ok(())
+}
+
+// ── Outbox commands ──────────────────────────────────────────────────────────
+
+/// List pending outbox entries.
+pub fn cmd_outbox_list(client: &QpqClient) -> Result<(), SdkError> {
+    let store = client.conversations()?;
+    let entries = quicprochat_sdk::outbox::list_pending(store)?;
+    if entries.is_empty() {
+        println!("outbox is empty — no pending messages");
+    } else {
+        println!("{:<6}  {:<34}  {:<8}  PAYLOAD SIZE", "ID", "CONVERSATION", "RETRIES");
+        for e in &entries {
+            println!(
+                "{:<6}  {:<34}  {:<8}  {} bytes",
+                e.id,
+                e.conversation_id.hex(),
+                e.retry_count,
+                e.payload.len(),
+            );
+        }
+        println!("\n{} pending entries", entries.len());
+    }
+    Ok(())
+}
+
+/// Retry sending all pending outbox entries.
+pub async fn cmd_outbox_retry(client: &mut QpqClient) -> Result<(), SdkError> {
+    let rpc = client.rpc()?;
+    let store = client.conversations()?;
+    let (sent, failed) = quicprochat_sdk::outbox::flush_outbox(rpc, store).await?;
+    println!("outbox flush: {sent} sent, {failed} permanently failed");
+    Ok(())
+}
+
+/// Clear permanently failed outbox entries.
+pub fn cmd_outbox_clear(client: &QpqClient) -> Result<(), SdkError> {
+    let store = client.conversations()?;
+    let cleared = quicprochat_sdk::outbox::clear_failed(store)?;
+    println!("cleared {cleared} failed outbox entries");
+    Ok(())
+}
+
+/// Recover an account from a recovery code.
+pub async fn cmd_recovery_restore(
+    client: &mut QpqClient,
+    code: &str,
+) -> Result<(), SdkError> {
+    let rpc = client.rpc()?;
+    let (identity_seed, conversation_ids) =
+        quicprochat_sdk::recovery::recover_account(rpc, code).await?;
+
+    // Restore identity.
+    let keypair = quicprochat_core::IdentityKeypair::from_seed(identity_seed);
+    client.set_identity_key(keypair.public_key_bytes().to_vec());
+
+    println!("account recovered successfully");
+    println!("identity key: {}", hex::encode(keypair.public_key_bytes()));
+    if !conversation_ids.is_empty() {
+        println!(
+            "{} conversations need rejoin (peers must re-invite this device)",
+            conversation_ids.len()
+        );
+    }
+
+    // Save recovered state.
+    let state = quicprochat_sdk::state::StoredState {
+        identity_seed,
+        group: None,
+        hybrid_key: None,
+        member_keys: Vec::new(),
+    };
+    let state_path = client.config_state_path();
+    quicprochat_sdk::state::save_state(&state_path, &state, None)?;
+    println!("state saved to {}", state_path.display());
+
+    Ok(())
+}

crates/quicprochat-client/src/v2_main.rs

@@ -0,0 +1,563 @@
+//! v2 CLI entry point — thin shell over `quicprochat_sdk::QpqClient`.
+//!
+//! Activated via `--features v2`. Replaces the v1 Cap'n Proto RPC main
+//! with a simplified command surface backed by the SDK.
+
+use std::path::{Path, PathBuf};
+use std::process::Command as ProcessCommand;
+use std::time::Duration;
+
+use anyhow::Context;
+use clap::{Parser, Subcommand};
+
+use quicprochat_sdk::client::QpqClient;
+use quicprochat_sdk::config::ClientConfig;
+
+use crate::v2_commands;
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+#[derive(Debug, Parser)]
+#[command(name = "qpc", about = "quicprochat CLI client (v2)", version)]
+struct Args {
+    /// Server address (host:port).
+    #[arg(long, global = true, default_value = "127.0.0.1:7000", env = "QPQ_SERVER")]
+    server: String,
+
+    /// TLS server name (must match certificate SAN).
+    #[arg(long, global = true, default_value = "localhost", env = "QPQ_SERVER_NAME")]
+    server_name: String,
+
+    /// Path to local conversation database.
+    #[arg(long, global = true, default_value = "conversations.db", env = "QPQ_CONV_DB")]
+    db_path: PathBuf,
+
+    /// Password for encrypting the local database.
+    #[arg(long, global = true, env = "QPQ_DB_PASSWORD")]
+    db_password: Option<String>,
+
+    /// Path to the client state file (identity key, MLS state).
+    #[arg(long, global = true, default_value = "qpc-state.bin", env = "QPQ_STATE")]
+    state: PathBuf,
+
+    /// DANGER: Skip TLS certificate verification. Development only.
+    #[arg(
+        long = "danger-accept-invalid-certs",
+        global = true,
+        env = "QPQ_DANGER_ACCEPT_INVALID_CERTS"
+    )]
+    danger_accept_invalid_certs: bool,
+
+    /// Do not auto-start a local qpc-server.
+    #[arg(long, global = true, env = "QPQ_NO_SERVER")]
+    no_server: bool,
+
+    #[command(subcommand)]
+    command: Cmd,
+}
+
+#[derive(Debug, Subcommand)]
+enum Cmd {
+    /// Register a new user via OPAQUE (password never leaves the client).
+    RegisterUser {
+        /// Username for the new account.
+        #[arg(long)]
+        username: String,
+        /// Password (used in OPAQUE PAKE; server never sees it).
+        #[arg(long)]
+        password: String,
+    },
+
+    /// Log in via OPAQUE and receive a session token.
+    Login {
+        #[arg(long)]
+        username: String,
+        #[arg(long)]
+        password: String,
+    },
+
+    /// Show local identity info.
+    Whoami,
+
+    /// Server health check.
+    Health,
+
+    /// Send a message to a conversation.
+    Send {
+        /// Conversation name (group name or DM peer username).
+        #[arg(long)]
+        to: String,
+        /// Message text.
+        #[arg(long)]
+        msg: String,
+    },
+
+    /// Receive pending messages from a conversation.
+    Recv {
+        /// Conversation name.
+        #[arg(long)]
+        from: String,
+    },
+
+    /// Start or resume a DM with a user.
+    Dm {
+        /// Peer username.
+        username: String,
+    },
+
+    /// Group management commands.
+    Group {
+        #[command(subcommand)]
+        action: GroupCmd,
+    },
+
+    /// Resolve a username to its identity key.
+    Resolve {
+        /// Username to look up.
+        username: String,
+    },
+
+    /// Device management.
+    Devices {
+        #[command(subcommand)]
+        action: DevicesCmd,
+    },
+
+    /// Account recovery management.
+    Recovery {
+        #[command(subcommand)]
+        action: RecoveryCmd,
+    },
+
+    /// Offline outbox management.
+    Outbox {
+        #[command(subcommand)]
+        action: OutboxCmd,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+enum GroupCmd {
+    /// Create a new group.
+    Create {
+        /// Group name.
+        name: String,
+    },
+    /// Invite a user to a group.
+    Invite {
+        /// Group name.
+        #[arg(long)]
+        group: String,
+        /// Username to invite.
+        #[arg(long)]
+        user: String,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+enum DevicesCmd {
+    /// List registered devices.
+    List,
+    /// Register a new device.
+    Register {
+        /// Device ID (hex).
+        #[arg(long)]
+        id: String,
+        /// Human-readable device name.
+        #[arg(long)]
+        name: String,
+    },
+    /// Revoke a device.
+    Revoke {
+        /// Device ID (hex).
+        #[arg(long)]
+        id: String,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+enum RecoveryCmd {
+    /// Generate recovery codes and upload encrypted bundles.
+    Setup,
+    /// Recover account from a recovery code.
+    Restore {
+        /// Recovery code (e.g. "A3B7K9").
+        code: String,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+enum OutboxCmd {
+    /// Show pending outbox entries.
+    List,
+    /// Retry sending all pending outbox entries.
+    Retry,
+    /// Clear permanently failed outbox entries.
+    Clear,
+}
+
+// ── Auto-server launch ───────────────────────────────────────────────────────
+
+/// RAII guard that kills an auto-started server process on drop.
+struct ServerGuard(Option<std::process::Child>);
+
+impl Drop for ServerGuard {
+    fn drop(&mut self) {
+        if let Some(ref mut child) = self.0 {
+            let _ = child.kill();
+            let _ = child.wait();
+        }
+    }
+}
+
+/// Find the `qpc-server` binary: same directory as current exe, then PATH.
+fn find_server_binary() -> Option<PathBuf> {
+    if let Ok(exe) = std::env::current_exe() {
+        let sibling = exe.with_file_name("qpc-server");
+        if sibling.exists() {
+            return Some(sibling);
+        }
+    }
+    std::env::var_os("PATH").and_then(|paths| {
+        std::env::split_paths(&paths)
+            .map(|dir| dir.join("qpc-server"))
+            .find(|p| p.exists())
+    })
+}
+
+/// Try a QUIC health probe to the server address.
+async fn probe_server(server_addr: &str) -> bool {
+    use std::net::ToSocketAddrs;
+    let addr = match server_addr.to_socket_addrs() {
+        Ok(mut addrs) => match addrs.next() {
+            Some(a) => a,
+            None => return false,
+        },
+        Err(_) => return false,
+    };
+    // Simple TCP probe — if the port is open, the server is likely running.
+    tokio::net::TcpStream::connect(addr)
+        .await
+        .is_ok()
+}
+
+/// Start a local qpc-server if one isn't already running.
+/// Returns a guard that kills the child on drop (if we started one).
+async fn ensure_server_running(
+    server_addr: &str,
+    data_dir: &Path,
+    no_server: bool,
+) -> anyhow::Result<ServerGuard> {
+    if no_server {
+        return Ok(ServerGuard(None));
+    }
+
+    if probe_server(server_addr).await {
+        return Ok(ServerGuard(None));
+    }
+
+    let binary = find_server_binary().ok_or_else(|| {
+        anyhow::anyhow!(
+            "server at {server_addr} is not reachable and qpc-server binary not found; \
+             start a server manually or install qpc-server"
+        )
+    })?;
+
+    let cert_path = data_dir.join("server-cert.der");
+    let key_path = data_dir.join("server-key.der");
+
+    eprintln!("starting server on {server_addr}...");
+
+    let child = ProcessCommand::new(&binary)
+        .args([
+            "--allow-insecure-auth",
+            "--listen",
+            server_addr,
+            "--tls-cert",
+            &cert_path.to_string_lossy(),
+            "--tls-key",
+            &key_path.to_string_lossy(),
+        ])
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .spawn()
+        .with_context(|| format!("failed to spawn {}", binary.display()))?;
+
+    let guard = ServerGuard(Some(child));
+
+    // Poll until the server is ready.
+    let mut delay = Duration::from_millis(100);
+    let max_wait = Duration::from_secs(3);
+    let start = std::time::Instant::now();
+
+    loop {
+        tokio::time::sleep(delay).await;
+
+        if probe_server(server_addr).await {
+            eprintln!("server ready");
+            return Ok(guard);
+        }
+
+        if start.elapsed() > max_wait {
+            anyhow::bail!(
+                "auto-started qpc-server but it did not become ready within {max_wait:?}"
+            );
+        }
+
+        delay = (delay * 2).min(Duration::from_secs(1));
+    }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/// Build a `ClientConfig` from CLI args.
+fn build_config(args: &Args) -> anyhow::Result<ClientConfig> {
+    let server_addr = args
+        .server
+        .parse()
+        .with_context(|| format!("invalid server address: {}", args.server))?;
+
+    Ok(ClientConfig {
+        server_addr,
+        server_name: args.server_name.clone(),
+        db_path: args.db_path.clone(),
+        db_password: args.db_password.clone(),
+        state_path: args.state.clone(),
+        accept_invalid_certs: args.danger_accept_invalid_certs,
+        ..ClientConfig::default()
+    })
+}
+
+/// Build, connect, and return a `QpqClient`. Loads identity from state file
+/// if it exists.
+async fn connect_client(args: &Args) -> anyhow::Result<QpqClient> {
+    let config = build_config(args)?;
+    let mut client = QpqClient::new(config);
+
+    // Try loading identity from state file.
+    if args.state.exists() {
+        match quicprochat_sdk::state::load_state(&args.state, args.db_password.as_deref()) {
+            Ok(stored) => {
+                let keypair = quicprochat_core::IdentityKeypair::from_seed(stored.identity_seed);
+                client.set_identity_key(keypair.public_key_bytes().to_vec());
+            }
+            Err(e) => {
+                tracing::debug!("could not load state from {}: {e}", args.state.display());
+            }
+        }
+    }
+
+    client.connect().await.context("failed to connect to server")?;
+    Ok(client)
+}
+
+// ── Entry point ──────────────────────────────────────────────────────────────
+
+pub fn main() {
+    // Install the rustls crypto provider before any TLS operations.
+    let _ = rustls::crypto::ring::default_provider().install_default();
+
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("warn")),
+        )
+        .init();
+
+    let args = Args::parse();
+
+    let rt = tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .build()
+        .unwrap_or_else(|e| {
+            eprintln!("fatal: {e}");
+            std::process::exit(1);
+        });
+
+    if let Err(e) = rt.block_on(run(args)) {
+        eprintln!("error: {e:#}");
+        std::process::exit(1);
+    }
+}
+
+async fn run(args: Args) -> anyhow::Result<()> {
+    // Auto-start server if needed (except for whoami which is local-only).
+    let data_dir = args.state.parent().unwrap_or_else(|| Path::new("."));
+    let _server_guard = match args.command {
+        Cmd::Whoami => ServerGuard(None),
+        _ => ensure_server_running(&args.server, data_dir, args.no_server).await?,
+    };
+
+    match args.command {
+        Cmd::RegisterUser {
+            ref username,
+            ref password,
+        } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_register_user(&mut client, username, password)
+                .await
+                .context("register-user failed")?;
+        }
+
+        Cmd::Login {
+            ref username,
+            ref password,
+        } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_login(&mut client, username, password)
+                .await
+                .context("login failed")?;
+        }
+
+        Cmd::Whoami => {
+            // Whoami is local-only — create client without connecting.
+            let config = build_config(&args)?;
+            let mut client = QpqClient::new(config);
+            if args.state.exists() {
+                match quicprochat_sdk::state::load_state(
+                    &args.state,
+                    args.db_password.as_deref(),
+                ) {
+                    Ok(stored) => {
+                        let keypair =
+                            quicprochat_core::IdentityKeypair::from_seed(stored.identity_seed);
+                        client.set_identity_key(keypair.public_key_bytes().to_vec());
+                    }
+                    Err(e) => {
+                        eprintln!("warning: could not load state: {e}");
+                    }
+                }
+            }
+            v2_commands::cmd_whoami(&client);
+        }
+
+        Cmd::Health => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_health(&mut client)
+                .await
+                .context("health check failed")?;
+        }
+
+        Cmd::Resolve { ref username } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_resolve(&mut client, username)
+                .await
+                .context("resolve failed")?;
+        }
+
+        Cmd::Dm { ref username } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_resolve(&mut client, username)
+                .await
+                .context("dm setup failed")?;
+            // For now, print the resolved key. Full DM creation requires
+            // MLS group state, which will be handled in the REPL flow.
+            println!("(DM creation with full MLS setup is available in the REPL)");
+        }
+
+        Cmd::Send { ref to, ref msg } => {
+            let _ = (to, msg);
+            let _client = connect_client(&args).await?;
+            // Full send requires MLS group state restoration — deferred to REPL.
+            println!("(send is currently available in the REPL; one-shot send coming soon)");
+        }
+
+        Cmd::Recv { ref from } => {
+            let _ = from;
+            let _client = connect_client(&args).await?;
+            println!("(recv is currently available in the REPL; one-shot recv coming soon)");
+        }
+
+        Cmd::Group {
+            action: GroupCmd::Create { ref name },
+        } => {
+            let _ = name;
+            let _client = connect_client(&args).await?;
+            println!("(group create is currently available in the REPL; one-shot coming soon)");
+        }
+
+        Cmd::Group {
+            action:
+                GroupCmd::Invite {
+                    ref group,
+                    ref user,
+                },
+        } => {
+            let _ = (group, user);
+            let _client = connect_client(&args).await?;
+            println!("(group invite is currently available in the REPL; one-shot coming soon)");
+        }
+
+        Cmd::Devices {
+            action: DevicesCmd::List,
+        } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_devices_list(&mut client)
+                .await
+                .context("devices list failed")?;
+        }
+
+        Cmd::Devices {
+            action: DevicesCmd::Register { ref id, ref name },
+        } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_devices_register(&mut client, id, name)
+                .await
+                .context("device register failed")?;
+        }
+
+        Cmd::Devices {
+            action: DevicesCmd::Revoke { ref id },
+        } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_devices_revoke(&mut client, id)
+                .await
+                .context("device revoke failed")?;
+        }
+
+        Cmd::Recovery {
+            action: RecoveryCmd::Setup,
+        } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_recovery_setup(&mut client)
+                .await
+                .context("recovery setup failed")?;
+        }
+
+        Cmd::Recovery {
+            action: RecoveryCmd::Restore { ref code },
+        } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_recovery_restore(&mut client, code)
+                .await
+                .context("recovery restore failed")?;
+        }
+
+        Cmd::Outbox {
+            action: OutboxCmd::List,
+        } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_outbox_list(&client)
+                .context("outbox list failed")?;
+        }
+
+        Cmd::Outbox {
+            action: OutboxCmd::Retry,
+        } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_outbox_retry(&mut client)
+                .await
+                .context("outbox retry failed")?;
+        }
+
+        Cmd::Outbox {
+            action: OutboxCmd::Clear,
+        } => {
+            let mut client = connect_client(&args).await?;
+            v2_commands::cmd_outbox_clear(&client)
+                .context("outbox clear failed")?;
+        }
+    }
+
+    Ok(())
+}