chore: rename project quicnprotochat -> quicproquo (binaries: qpq)

Rename the entire workspace:
- Crate packages: quicnprotochat-{core,proto,server,client,gui,p2p,mobile} -> quicproquo-*
- Binary names: quicnprotochat -> qpq, quicnprotochat-server -> qpq-server,
  quicnprotochat-gui -> qpq-gui
- Default files: *-state.bin -> qpq-state.bin, *-server.toml -> qpq-server.toml,
  *.db -> qpq.db
- Environment variable prefix: QUICNPROTOCHAT_* -> QPQ_*
- App identifier: chat.quicnproto.gui -> chat.quicproquo.gui
- Proto package: quicnprotochat.bench -> quicproquo.bench
- All documentation, Docker, CI, and script references updated

HKDF domain-separation strings and P2P ALPN remain unchanged for
backward compatibility with existing encrypted state and wire protocol.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

crates/quicproquo-client/Cargo.toml

@@ -0,0 +1,67 @@
+[package]
+name        = "quicproquo-client"
+version     = "0.1.0"
+edition     = "2021"
+description = "CLI client for quicproquo."
+license     = "MIT"
+
+[[bin]]
+name = "qpq"
+path = "src/main.rs"
+
+[dependencies]
+quicproquo-core  = { path = "../quicproquo-core" }
+quicproquo-proto = { path = "../quicproquo-proto" }
+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 }
+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"
+
+[dev-dependencies]
+dashmap       = { workspace = true }
+assert_cmd    = "2"
+tempfile      = "3"
+portpicker    = "0.1"
+rand          = "0.8"

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

@@ -0,0 +1,563 @@
+//! 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,
+}
+
+#[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)?;
+        let hex_key = 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)?;
+        let hex_key = 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.
+        plain
+            .execute_batch(&format!(
+                "ATTACH DATABASE '{}' AS encrypted KEY \"x'{hex_key}'\";",
+                enc_path.display()
+            ))
+            .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);",
+        )
+        .context("migrate conversation db")?;
+        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)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)
+             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",
+            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,
+            ],
+        )?;
+        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
+                 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 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| bincode::deserialize(&b).ok())
+                        .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,
+                    })
+                },
+            )
+            .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
+             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 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| bincode::deserialize(&b).ok())
+                .unwrap_or_default();
+
+            Ok(Conversation {
+                id,
+                kind,
+                display_name,
+                mls_group_blob,
+                keystore_blob,
+                member_keys,
+                unread_count,
+                last_activity_ms,
+                created_at_ms,
+            })
+        })?;
+
+        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 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)
+    }
+}
+
+pub fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}

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

@@ -0,0 +1,69 @@
+//! 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) {
+    if msg.is_outgoing {
+        println!("\r{GREEN}> {}{RESET}", msg.body);
+    } 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} {}", msg.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 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/quicproquo-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/quicproquo-client/src/client/mod.rs

@@ -0,0 +1,14 @@
+pub mod commands;
+pub mod conversation;
+pub mod display;
+pub mod hex;
+pub mod repl;
+pub mod retry;
+pub mod rpc;
+pub mod session;
+pub mod state;
+pub mod token_cache;
+
+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/quicproquo-client/src/client/retry.rs

@@ -0,0 +1,86 @@
+//! 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 = None;
+    for attempt in 0..max_retries {
+        match op().await {
+            Ok(t) => return Ok(t),
+            Err(e) => {
+                last_err = Some(e);
+                let err = last_err.as_ref().unwrap();
+                if !is_retriable(err) || attempt + 1 >= max_retries {
+                    break;
+                }
+                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"
+                );
+                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
+}

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

@@ -0,0 +1,684 @@
+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;
+use rustls::{ClientConfig as RustlsClientConfig, RootCertStore};
+use tokio_util::compat::{TokioAsyncReadCompatExt, TokioAsyncWriteCompatExt};
+use capnp_rpc::{rpc_twoparty_capnp::Side, twoparty, RpcSystem};
+
+use quicproquo_core::HybridPublicKey;
+use quicproquo_proto::node_capnp::{auth, node_service};
+
+use crate::AUTH_CONTEXT;
+
+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;
+
+/// Establish a QUIC/TLS connection and return a `NodeService` client.
+///
+/// Must be called from within a `LocalSet` because capnp-rpc is `!Send`.
+pub async fn connect_node(
+    server: &str,
+    ca_cert: &Path,
+    server_name: &str,
+) -> anyhow::Result<node_service::Client> {
+    let addr: SocketAddr = server
+        .parse()
+        .with_context(|| format!("server must be host:port, got {server}"))?;
+
+    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")?;
+
+    let mut tls = 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().expect("AUTH_CONTEXT poisoned");
+    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> {
+    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);
+                    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();
+            let timeout_ms = timeout_ms;
+            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<&quicproquo_core::HybridKeypair>,
+    payload: &[u8],
+) -> anyhow::Result<Vec<u8>> {
+    let kp = hybrid_kp.ok_or_else(|| anyhow::anyhow!("hybrid key required for decryption"))?;
+    quicproquo_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).
+/// 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 key = resp
+        .get()
+        .context("resolve_user: bad response")?
+        .get_identity_key()
+        .context("resolve_user: missing field")?
+        .to_vec();
+
+    if key.is_empty() {
+        Ok(None)
+    } else {
+        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 the 16-byte channel ID.
+/// If a channel already exists between the two users, returns the existing ID.
+pub async fn create_channel(
+    client: &node_service::Client,
+    peer_key: &[u8],
+) -> anyhow::Result<Vec<u8>> {
+    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 channel_id = resp
+        .get()
+        .context("create_channel: bad response")?
+        .get_channel_id()
+        .context("create_channel: missing channel_id")?
+        .to_vec();
+
+    Ok(channel_id)
+}
+
+/// 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/quicproquo-client/src/client/session.rs

@@ -0,0 +1,262 @@
+//! 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 anyhow::Context;
+
+use quicproquo_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.
+    pub password: Option<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>,
+}
+
+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(|b| HybridKeypair::from_bytes(b))
+            .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(String::from),
+            conv_store,
+            active_conversation: None,
+            members: HashMap::new(),
+            pending_member: 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_else(|| 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(),
+        };
+
+        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(|_| 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,
+            false, // existing conversations default to classical
+        ))
+    }
+
+    /// 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(|g| bincode::serialize(g))
+            .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/quicproquo-client/src/client/state.rs

@@ -0,0 +1,292 @@
+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 quicproquo_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)]
+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/quicproquo-client/src/client/token_cache.rs

@@ -0,0 +1,86 @@
+//! 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 => 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();
+}

crates/quicproquo-client/src/lib.rs

@@ -0,0 +1,68 @@
+//! quicproquo 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 `qpq refresh-keypackage`
+//! periodically (e.g. before the server TTL) or after your KeyPackage was consumed:
+//!
+//! ```bash
+//! qpq refresh-keypackage --state qpq-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.quicproquo.dev/getting-started/running-the-client)
+//! docs for details.
+
+use std::sync::RwLock;
+
+pub mod client;
+
+pub use client::commands::{
+    cmd_chat, cmd_check_key, cmd_create_group, cmd_demo_group, 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,
+    receive_pending_plaintexts, whoami_json,
+};
+
+pub use client::repl::run_repl;
+pub use client::rpc::{connect_node, enqueue, fetch_wait};
+
+// Global auth context — RwLock so the REPL can set it after OPAQUE login.
+pub(crate) static AUTH_CONTEXT: RwLock<Option<ClientAuth>> = RwLock::new(None);
+
+#[derive(Clone, Debug)]
+pub struct ClientAuth {
+    pub(crate) version: u16,
+    pub(crate) access_token: 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: 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: raw_token,
+            device_id: device,
+        }
+    }
+}
+
+/// Set (or replace) the global auth context.
+pub fn init_auth(ctx: ClientAuth) {
+    let mut guard = AUTH_CONTEXT.write().expect("AUTH_CONTEXT poisoned");
+    *guard = Some(ctx);
+}

crates/quicproquo-client/src/main.rs

@@ -0,0 +1,567 @@
+//! quicproquo CLI client.
+
+use std::path::PathBuf;
+
+use clap::{Parser, Subcommand};
+
+use quicproquo_client::{
+    cmd_chat, cmd_check_key, cmd_create_group, cmd_demo_group, 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,
+    ClientAuth,
+};
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+#[derive(Debug, Parser)]
+#[command(name = "qpq", about = "quicproquo 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>,
+
+    #[command(subcommand)]
+    command: Command,
+}
+
+#[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 = "qpq-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 = "qpq-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 = "qpq-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 = "qpq-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 = "qpq-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 = "qpq-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 = "qpq-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 = "qpq-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 = "qpq-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 = "qpq-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,
+    },
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+#[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();
+
+    // For the REPL, defer init_auth so it can resolve its own token via OPAQUE.
+    // For all other subcommands, initialize auth immediately.
+    let is_repl = matches!(args.command, Command::Repl { .. });
+    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();
+
+    match args.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,
+        } => {
+            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(),
+                ))
+                .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
+        }
+    }
+}

crates/quicproquo-client/tests/e2e.rs

@@ -0,0 +1,597 @@
+// cargo_bin! only works for current package's binary; we spawn qpq-server from another package.
+#![allow(deprecated)]
+
+use std::{path::PathBuf, process::Command, time::Duration};
+
+use assert_cmd::cargo::cargo_bin;
+use portpicker::pick_unused_port;
+use rand::RngCore;
+use tempfile::TempDir;
+use tokio::time::sleep;
+use hex;
+
+// Required by rustls 0.23 when QUIC/TLS is used from this process (e.g. client in test).
+fn ensure_rustls_provider() {
+    let _ = rustls::crypto::ring::default_provider().install_default();
+}
+
+use quicproquo_client::{
+    cmd_create_group, cmd_invite, cmd_join, cmd_login, cmd_ping, cmd_register_state,
+    cmd_register_user, cmd_send, connect_node, enqueue, fetch_wait, init_auth,
+    receive_pending_plaintexts, ClientAuth,
+};
+use quicproquo_core::IdentityKeypair;
+
+fn hex_encode(bytes: &[u8]) -> String {
+    bytes.iter().map(|b| format!("{b:02x}")).collect()
+}
+
+#[derive(serde::Deserialize)]
+struct StoredStateCompat {
+    identity_seed: [u8; 32],
+    #[allow(dead_code)]
+    group: Option<Vec<u8>>,
+}
+
+async fn wait_for_health(server: &str, ca_cert: &PathBuf, server_name: &str) -> anyhow::Result<()> {
+    let local = tokio::task::LocalSet::new();
+    for _ in 0..30 {
+        if local
+            .run_until(cmd_ping(server, ca_cert, server_name))
+            .await
+            .is_ok()
+        {
+            return Ok(());
+        }
+        sleep(Duration::from_millis(200)).await;
+    }
+    anyhow::bail!("server health never became ready")
+}
+
+/// Creator and joiner register; creator creates group and invites joiner; joiner joins;
+/// creator sends a message; assert joiner's mailbox receives it.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn e2e_happy_path_register_invite_join_send_recv() -> anyhow::Result<()> {
+    ensure_rustls_provider();
+
+    let temp = TempDir::new()?;
+    let base = temp.path();
+    let port = pick_unused_port().expect("free port");
+    let listen = format!("127.0.0.1:{port}");
+    let server = listen.clone();
+    let ca_cert = base.join("server-cert.der");
+    let tls_key = base.join("server-key.der");
+    let data_dir = base.join("data");
+    let auth_token = "devtoken";
+
+    // Spawn server binary.
+    let server_bin = cargo_bin("qpq-server");
+    let child = Command::new(server_bin)
+        .arg("--listen")
+        .arg(&listen)
+        .arg("--data-dir")
+        .arg(&data_dir)
+        .arg("--tls-cert")
+        .arg(&ca_cert)
+        .arg("--tls-key")
+        .arg(&tls_key)
+        .arg("--auth-token")
+        .arg(auth_token)
+        .arg("--allow-insecure-auth")
+        .spawn()
+        .expect("spawn server");
+
+    // Ensure we always terminate the child.
+    struct ChildGuard(std::process::Child);
+    impl Drop for ChildGuard {
+        fn drop(&mut self) {
+            let _ = self.0.kill();
+        }
+    }
+    let child_guard = ChildGuard(child);
+    let _ = child_guard;
+
+    // Wait for server to be healthy and certs to be generated.
+    wait_for_health(&server, &ca_cert, "localhost").await?;
+
+    // Set client auth context.
+    init_auth(ClientAuth::from_parts(auth_token.to_string(), None));
+
+    let local = tokio::task::LocalSet::new();
+
+    let creator_state = base.join("creator.bin");
+    let joiner_state = base.join("joiner.bin");
+
+    local
+        .run_until(cmd_register_state(
+            &creator_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            None,
+        ))
+        .await?;
+
+    local
+        .run_until(cmd_register_state(
+            &joiner_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            None,
+        ))
+        .await?;
+
+    local
+        .run_until(cmd_create_group(&creator_state, &server, "test-group", None))
+        .await?;
+
+    let joiner_bytes = std::fs::read(&joiner_state)?;
+    let joiner_state_compat: StoredStateCompat = bincode::deserialize(&joiner_bytes)?;
+    let joiner_identity = IdentityKeypair::from_seed(joiner_state_compat.identity_seed);
+    let joiner_pk_hex = hex_encode(&joiner_identity.public_key_bytes());
+
+    local
+        .run_until(cmd_invite(
+            &creator_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            &joiner_pk_hex,
+            None,
+        ))
+        .await?;
+
+    local
+        .run_until(cmd_join(&joiner_state, &server, &ca_cert, "localhost", None))
+        .await?;
+
+    local
+        .run_until(cmd_send(
+            &creator_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            Some(&joiner_pk_hex),
+            false,
+            "hello",
+            None,
+        ))
+        .await?;
+
+    local
+        .run_until(async {
+            let client = connect_node(&server, &ca_cert, "localhost").await?;
+            let payloads = fetch_wait(&client, &joiner_identity.public_key_bytes(), 1000).await?;
+            anyhow::ensure!(!payloads.is_empty(), "no payloads delivered to joiner");
+            Ok::<(), anyhow::Error>(())
+        })
+        .await?;
+
+    Ok(())
+}
+
+/// Three-party group: A creates group, invites B then C; B and C join; A sends, B and C receive;
+/// B sends, A and C receive.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn e2e_three_party_group_invite_join_send_recv() -> anyhow::Result<()> {
+    ensure_rustls_provider();
+
+    let temp = TempDir::new()?;
+    let base = temp.path();
+    let port = pick_unused_port().expect("free port");
+    let listen = format!("127.0.0.1:{port}");
+    let server = listen.clone();
+    let ca_cert = base.join("server-cert.der");
+    let tls_key = base.join("server-key.der");
+    let data_dir = base.join("data");
+    let auth_token = "devtoken";
+
+    let server_bin = cargo_bin("qpq-server");
+    let child = Command::new(server_bin)
+        .arg("--listen")
+        .arg(&listen)
+        .arg("--data-dir")
+        .arg(&data_dir)
+        .arg("--tls-cert")
+        .arg(&ca_cert)
+        .arg("--tls-key")
+        .arg(&tls_key)
+        .arg("--auth-token")
+        .arg(auth_token)
+        .arg("--allow-insecure-auth")
+        .spawn()
+        .expect("spawn server");
+
+    struct ChildGuard(std::process::Child);
+    impl Drop for ChildGuard {
+        fn drop(&mut self) {
+            let _ = self.0.kill();
+        }
+    }
+    let _child_guard = ChildGuard(child);
+
+    wait_for_health(&server, &ca_cert, "localhost").await?;
+    init_auth(ClientAuth::from_parts(auth_token.to_string(), None));
+
+    let local = tokio::task::LocalSet::new();
+
+    let creator_state = base.join("creator.bin");
+    let b_state = base.join("b.bin");
+    let c_state = base.join("c.bin");
+
+    local
+        .run_until(cmd_register_state(
+            &creator_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            None,
+        ))
+        .await?;
+    local
+        .run_until(cmd_register_state(
+            &b_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            None,
+        ))
+        .await?;
+    local
+        .run_until(cmd_register_state(
+            &c_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            None,
+        ))
+        .await?;
+
+    let b_bytes = std::fs::read(&b_state)?;
+    let b_compat: StoredStateCompat = bincode::deserialize(&b_bytes)?;
+    let b_pk_hex = hex_encode(&IdentityKeypair::from_seed(b_compat.identity_seed).public_key_bytes());
+
+    let c_bytes = std::fs::read(&c_state)?;
+    let c_compat: StoredStateCompat = bincode::deserialize(&c_bytes)?;
+    let c_pk_hex = hex_encode(&IdentityKeypair::from_seed(c_compat.identity_seed).public_key_bytes());
+
+    local
+        .run_until(cmd_create_group(&creator_state, &server, "test-group", None))
+        .await?;
+
+    local
+        .run_until(cmd_invite(
+            &creator_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            &b_pk_hex,
+            None,
+        ))
+        .await?;
+
+    local
+        .run_until(cmd_invite(
+            &creator_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            &c_pk_hex,
+            None,
+        ))
+        .await?;
+
+    local
+        .run_until(cmd_join(&b_state, &server, &ca_cert, "localhost", None))
+        .await?;
+    local
+        .run_until(cmd_join(&c_state, &server, &ca_cert, "localhost", None))
+        .await?;
+
+    local
+        .run_until(cmd_send(
+            &creator_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            None,
+            true,
+            "hello",
+            None,
+        ))
+        .await?;
+
+    sleep(Duration::from_millis(150)).await;
+
+    let b_plaintexts = local
+        .run_until(receive_pending_plaintexts(
+            &b_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            1500,
+            None,
+        ))
+        .await?;
+    let c_plaintexts = local
+        .run_until(receive_pending_plaintexts(
+            &c_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            1500,
+            None,
+        ))
+        .await?;
+    anyhow::ensure!(
+        b_plaintexts.iter().any(|p| p.as_slice() == b"hello"),
+        "B did not receive 'hello', got {:?}",
+        b_plaintexts
+    );
+    anyhow::ensure!(
+        c_plaintexts.iter().any(|p| p.as_slice() == b"hello"),
+        "C did not receive 'hello', got {:?}",
+        c_plaintexts
+    );
+
+    local
+        .run_until(cmd_send(
+            &b_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            None,
+            true,
+            "hi",
+            None,
+        ))
+        .await?;
+
+    sleep(Duration::from_millis(200)).await;
+
+    let a_plaintexts = local
+        .run_until(receive_pending_plaintexts(
+            &creator_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            1500,
+            None,
+        ))
+        .await?;
+    let c_plaintexts2 = local
+        .run_until(receive_pending_plaintexts(
+            &c_state,
+            &server,
+            &ca_cert,
+            "localhost",
+            1500,
+            None,
+        ))
+        .await?;
+    anyhow::ensure!(
+        a_plaintexts.iter().any(|p| p.as_slice() == b"hi"),
+        "A did not receive 'hi', got {:?}",
+        a_plaintexts
+    );
+    anyhow::ensure!(
+        c_plaintexts2.iter().any(|p| p.as_slice() == b"hi"),
+        "C did not receive 'hi', got {:?}",
+        c_plaintexts2
+    );
+
+    Ok(())
+}
+
+/// Login should refuse if the presented identity key does not match the registered key.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn e2e_login_rejects_mismatched_identity() -> anyhow::Result<()> {
+    ensure_rustls_provider();
+
+    let temp = TempDir::new()?;
+    let base = temp.path();
+    let port = pick_unused_port().expect("free port");
+    let listen = format!("127.0.0.1:{port}");
+    let server = listen.clone();
+    let ca_cert = base.join("server-cert.der");
+    let tls_key = base.join("server-key.der");
+    let data_dir = base.join("data");
+    let auth_token = "devtoken";
+
+    // Spawn server binary.
+    let server_bin = cargo_bin("qpq-server");
+    let child = Command::new(server_bin)
+        .arg("--listen")
+        .arg(&listen)
+        .arg("--data-dir")
+        .arg(&data_dir)
+        .arg("--tls-cert")
+        .arg(&ca_cert)
+        .arg("--tls-key")
+        .arg(&tls_key)
+        .arg("--auth-token")
+        .arg(auth_token)
+        .arg("--allow-insecure-auth")
+        .spawn()
+        .expect("spawn server");
+
+    struct ChildGuard(std::process::Child);
+    impl Drop for ChildGuard {
+        fn drop(&mut self) {
+            let _ = self.0.kill();
+        }
+    }
+    let child_guard = ChildGuard(child);
+    let _ = child_guard;
+
+    wait_for_health(&server, &ca_cert, "localhost").await?;
+
+    init_auth(ClientAuth::from_parts(auth_token.to_string(), None));
+
+    let local = tokio::task::LocalSet::new();
+    let state_path = base.join("user.bin");
+
+    // Register and persist state (includes identity key binding).
+    local
+        .run_until(cmd_register_state(
+            &state_path,
+            &server,
+            &ca_cert,
+            "localhost",
+            None,
+        ))
+        .await?;
+
+    // Register the user with the bound identity so login can enforce mismatches.
+    let state_bytes = std::fs::read(&state_path)?;
+    let stored_state: StoredStateCompat = bincode::deserialize(&state_bytes)?;
+    let identity_hex = hex::encode(
+        IdentityKeypair::from_seed(stored_state.identity_seed).public_key_bytes(),
+    );
+
+    local
+        .run_until(cmd_register_user(
+            &server,
+            &ca_cert,
+            "localhost",
+            "user1",
+            "pass",
+            Some(&identity_hex),
+        ))
+        .await?;
+
+    // Craft an unrelated identity key and attempt login with it.
+    let mut bogus_identity = [0u8; 32];
+    rand::thread_rng().fill_bytes(&mut bogus_identity);
+    let bogus_hex = hex::encode(bogus_identity);
+
+    let result = local
+        .run_until(cmd_login(
+            &server,
+            &ca_cert,
+            "localhost",
+            "user1",
+            "pass",
+            Some(&bogus_hex),
+            None,
+            None,
+        ))
+        .await;
+
+    match result {
+        Ok(_) => anyhow::bail!("login unexpectedly succeeded with mismatched identity"),
+        Err(e) => {
+            // Show the full error chain so we can match the server's E016 response.
+            let msg = format!("{e:#}");
+            anyhow::ensure!(
+                msg.contains("identity") || msg.contains("E016"),
+                "login failed but not for identity mismatch: {msg}"
+            );
+        }
+    }
+
+    Ok(())
+}
+
+/// Sealed Sender: enqueue with valid token (no identity binding) succeeds; recipient can fetch.
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn e2e_sealed_sender_enqueue_then_fetch() -> anyhow::Result<()> {
+    ensure_rustls_provider();
+
+    let temp = TempDir::new()?;
+    let base = temp.path();
+    let port = pick_unused_port().expect("free port");
+    let listen = format!("127.0.0.1:{port}");
+    let server = listen.clone();
+    let ca_cert = base.join("server-cert.der");
+    let tls_key = base.join("server-key.der");
+    let data_dir = base.join("data");
+    let auth_token = "devtoken";
+
+    let server_bin = cargo_bin("qpq-server");
+    let child = Command::new(server_bin)
+        .arg("--listen")
+        .arg(&listen)
+        .arg("--data-dir")
+        .arg(&data_dir)
+        .arg("--tls-cert")
+        .arg(&ca_cert)
+        .arg("--tls-key")
+        .arg(&tls_key)
+        .arg("--auth-token")
+        .arg(auth_token)
+        .arg("--allow-insecure-auth")
+        .arg("--sealed-sender")
+        .spawn()
+        .expect("spawn server");
+
+    struct ChildGuard(std::process::Child);
+    impl Drop for ChildGuard {
+        fn drop(&mut self) {
+            let _ = self.0.kill();
+        }
+    }
+    let _child_guard = ChildGuard(child);
+
+    wait_for_health(&server, &ca_cert, "localhost").await?;
+    init_auth(ClientAuth::from_parts(auth_token.to_string(), None));
+
+    let local = tokio::task::LocalSet::new();
+    let state_path = base.join("recipient.bin");
+
+    local
+        .run_until(cmd_register_state(
+            &state_path,
+            &server,
+            &ca_cert,
+            "localhost",
+            None,
+        ))
+        .await?;
+
+    let state_bytes = std::fs::read(&state_path)?;
+    let stored: StoredStateCompat = bincode::deserialize(&state_bytes)?;
+    let recipient_key = IdentityKeypair::from_seed(stored.identity_seed).public_key_bytes();
+    let identity_hex = hex_encode(&recipient_key);
+
+    local
+        .run_until(cmd_register_user(
+            &server,
+            &ca_cert,
+            "localhost",
+            "recipient",
+            "pass",
+            Some(&identity_hex),
+        ))
+        .await?;
+
+    local
+        .run_until(cmd_login(
+            &server,
+            &ca_cert,
+            "localhost",
+            "recipient",
+            "pass",
+            Some(&identity_hex),
+            None,
+            None,
+        ))
+        .await?;
+
+    let client = local.run_until(connect_node(&server, &ca_cert, "localhost")).await?;
+    local
+        .run_until(enqueue(&client, &recipient_key, b"sealed-payload"))
+        .await?;
+
+    let payloads = local
+        .run_until(fetch_wait(&client, &recipient_key, 500))
+        .await?;
+    anyhow::ensure!(
+        payloads.len() == 1 && payloads[0].1.as_slice() == b"sealed-payload",
+        "expected one payload 'sealed-payload', got {:?}",
+        payloads
+    );
+
+    Ok(())
+}