Skip to main content

qualia_client_core/
nym_live.rs

1//! Live Nym mixnet client bind (official `nym-sdk`).
2//!
3//! Settings/Wallet enable hits this path. Live only after connect succeeds and a
4//! real Recipient address is claimed into identity key `nym`. No fabricated n1….
5//! Default network: sandbox (matches historic `NymConfig`). Override with
6//! `network` arg or `WEBIZEN_NYM_NETWORK=sandbox|mainnet`.
7//!
8//! Identity seed is KeyVault-held under closed keyRole `mixnet`
9//! (≠ `session-authentication`). Host requests seed at enable; agents request
10//! purpose grants only — never hold material.
11
12#![cfg(not(target_arch = "wasm32"))]
13
14use crate::api::{read_identity, save_identity};
15use crate::state::{app_meta_dir, APP_STATE};
16use nym_crypto::hkdf::DerivationMaterial;
17use nym_sdk::mixnet::{MixnetClientBuilder, NymNetworkDetails, StoragePaths};
18use qualia_core_db::key_vault::{KeyRole, KeyRoleGrant};
19use serde::Serialize;
20use std::path::PathBuf;
21use std::sync::atomic::Ordering;
22use std::sync::{Mutex, OnceLock};
23use tokio::sync::{mpsc, oneshot};
24
25const MIXNET_DERIVATION_SALT: &[u8] = b"webizen:keyRole:mixnet:nym-sdk:v1";
26const MIXNET_DERIVATION_INDEX: u32 = 0;
27
28#[derive(Debug, Clone, Serialize)]
29pub struct NymLiveStatus {
30    pub live: bool,
31    pub enabled_wanted: bool,
32    pub address: String,
33    pub network: String,
34    pub error: Option<String>,
35    pub client: &'static str,
36    /// Closed keyRole for this client identity seed.
37    pub key_role: &'static str,
38    /// Where the mixnet seed lives — never the agent.
39    pub seed_holder: &'static str,
40}
41
42struct Runtime {
43    stop_tx: Option<mpsc::Sender<()>>,
44    address: String,
45    network: String,
46    last_error: Option<String>,
47}
48
49static RUNTIME: OnceLock<Mutex<Runtime>> = OnceLock::new();
50
51fn runtime() -> &'static Mutex<Runtime> {
52    RUNTIME.get_or_init(|| {
53        Mutex::new(Runtime {
54            stop_tx: None,
55            address: String::new(),
56            network: String::new(),
57            last_error: None,
58        })
59    })
60}
61
62fn resolve_network(requested: Option<&str>) -> Result<(String, NymNetworkDetails), String> {
63    let raw = requested
64        .map(str::trim)
65        .filter(|s| !s.is_empty())
66        .map(|s| s.to_string())
67        .or_else(|| std::env::var("WEBIZEN_NYM_NETWORK").ok())
68        .unwrap_or_else(|| "sandbox".to_string());
69    let key = raw.to_ascii_lowercase();
70    match key.as_str() {
71        "sandbox" | "sandbox-testnet" | "testnet" => Ok((
72            "sandbox".into(),
73            nym_network_defaults::sandbox::network_details(),
74        )),
75        "mainnet" | "main" => Ok(("mainnet".into(), NymNetworkDetails::new_mainnet())),
76        other => Err(format!(
77            "Nym network '{other}' not approved — use sandbox or mainnet (or WEBIZEN_NYM_NETWORK)"
78        )),
79    }
80}
81
82/// Vault-scoped client dir so first connect derives from KeyVault mixnet seed
83/// (orphan PEMs from pre-vault tips must not win over keyRole material).
84fn client_dir(network: &str) -> PathBuf {
85    app_meta_dir()
86        .join("nym-client")
87        .join(network)
88        .join("kr-mixnet-v1")
89}
90
91fn claim_nym_address(address: &str) -> Result<(), String> {
92    if address.is_empty() || address.starts_with("n1") {
93        return Err("refusing empty or fabricated n1… Nym locator".into());
94    }
95    let mut id = read_identity().unwrap_or_else(|| serde_json::json!({}));
96    if let Some(obj) = id.as_object_mut() {
97        obj.insert("nym".into(), serde_json::Value::String(address.to_string()));
98        obj.remove("nym_mixnet");
99    }
100    save_identity(id)
101}
102
103fn clear_nym_claim() {
104    if let Some(mut id) = read_identity() {
105        if let Some(obj) = id.as_object_mut() {
106            obj.insert("nym".into(), serde_json::Value::String(String::new()));
107            obj.remove("nym_mixnet");
108            let _ = save_identity(id);
109        }
110    }
111}
112
113/// Host-only: request mixnet seed from KeyVault and build Nym DerivationMaterial.
114/// Seed bytes never leave this function into logs, status, or agent grants.
115fn request_mixnet_derivation() -> Result<DerivationMaterial, String> {
116    let state = APP_STATE
117        .get()
118        .ok_or("APP_STATE not initialized — cannot request KeyVault mixnet seed")?;
119    let vault = state
120        .key_vault
121        .lock()
122        .map_err(|_| "KeyVault lock poisoned".to_string())?;
123    if vault.is_locked() {
124        return Err("KeyVault locked — unlock before enabling Nym mixnet".into());
125    }
126    // Purpose tag mixnet ≠ session-authentication (hard-negative).
127    let _session_ctx = KeyRole::SessionAuthentication.vault_context();
128    let mix_ctx = KeyRole::Mixnet.vault_context();
129    debug_assert_ne!(_session_ctx, mix_ctx);
130    let seed = vault.request_role_seed(KeyRole::Mixnet)?;
131    Ok(DerivationMaterial::new(
132        seed,
133        MIXNET_DERIVATION_INDEX,
134        MIXNET_DERIVATION_SALT,
135    ))
136}
137
138/// Agent-facing: request mixnet keyRole purpose — never returns seed.
139pub fn agent_request_mixnet_key_role() -> Result<KeyRoleGrant, String> {
140    let state = APP_STATE.get().ok_or("APP_STATE not initialized")?;
141    let vault = state
142        .key_vault
143        .lock()
144        .map_err(|_| "KeyVault lock poisoned".to_string())?;
145    Ok(vault.agent_request_role(KeyRole::Mixnet))
146}
147
148/// Agent-facing: request any closed keyRole — never returns seed.
149pub fn agent_request_key_role(role: &str) -> Result<KeyRoleGrant, String> {
150    let role = KeyRole::parse(role).ok_or_else(|| {
151        format!("keyRole '{role}' held / not-yet — unknown roles are not other-id")
152    })?;
153    let state = APP_STATE.get().ok_or("APP_STATE not initialized")?;
154    let vault = state
155        .key_vault
156        .lock()
157        .map_err(|_| "KeyVault lock poisoned".to_string())?;
158    Ok(vault.agent_request_role(role))
159}
160
161/// Nym live status.
162pub fn nym_live_status() -> NymLiveStatus {
163    let enabled_wanted = APP_STATE
164        .get()
165        .map(|s| s.nym_relay_active.load(Ordering::Relaxed))
166        .unwrap_or(false);
167    let g = runtime().lock().unwrap();
168    let live = enabled_wanted && g.stop_tx.is_some() && !g.address.is_empty();
169    NymLiveStatus {
170        live,
171        enabled_wanted,
172        address: g.address.clone(),
173        network: g.network.clone(),
174        error: g.last_error.clone(),
175        client: "nym-sdk@1.21.6",
176        key_role: KeyRole::Mixnet.as_str(),
177        seed_holder: "keyvault",
178    }
179}
180
181/// Enable real Nym client. Seed from KeyVault keyRole mixnet; fails honestly if
182/// vault locked or connect/claim does not succeed.
183pub async fn enable_nym(network: Option<String>) -> Result<NymLiveStatus, String> {
184    // Stop any prior session first.
185    let _ = disable_nym().await;
186
187    let (net_name, net_details) = resolve_network(network.as_deref())?;
188    let derivation = request_mixnet_derivation()?;
189
190    let dir = client_dir(&net_name);
191    std::fs::create_dir_all(&dir).map_err(|e| format!("nym client dir: {e}"))?;
192    let storage_paths =
193        StoragePaths::new_from_dir(&dir).map_err(|e| format!("nym storage: {e}"))?;
194
195    log::info!(
196        "Nym: connecting via nym-sdk ({net_name}) keyRole=mixnet seed_holder=keyvault storage={}",
197        dir.display()
198    );
199
200    let mut builder = MixnetClientBuilder::new_with_default_storage(storage_paths)
201        .await
202        .map_err(|e| format!("nym builder storage: {e}"))?
203        .network_details(net_details)
204        .with_derivation_material(derivation);
205
206    if net_name == "mainnet" {
207        // Mainnet bandwidth requires credentials; surface failures honestly.
208        builder = builder.enable_credentials_mode();
209    }
210
211    let disconnected = builder.build().map_err(|e| format!("nym build: {e}"))?;
212
213    let client = disconnected
214        .connect_to_mixnet()
215        .await
216        .map_err(|e| format!("nym connect ({net_name}): {e}"))?;
217
218    let address = client.nym_address().to_string();
219    if address.is_empty() || address.starts_with("n1") {
220        client.disconnect().await;
221        return Err("nym connect returned empty/fabricated address — not claiming".into());
222    }
223
224    claim_nym_address(&address)?;
225
226    let (stop_tx, mut stop_rx) = mpsc::channel::<()>(1);
227    let (ready_tx, ready_rx) = oneshot::channel::<()>();
228
229    tokio::spawn(async move {
230        let mut client = client;
231        let _ = ready_tx.send(());
232        loop {
233            tokio::select! {
234                _ = stop_rx.recv() => {
235                    client.disconnect().await;
236                    break;
237                }
238                msgs = client.wait_for_messages() => {
239                    if msgs.is_none() {
240                        break;
241                    }
242                    // Drain; QFrame routing is a later tip — bind+claim is this tip.
243                }
244            }
245        }
246    });
247
248    let _ = ready_rx.await;
249
250    if let Some(state) = APP_STATE.get() {
251        state.nym_relay_active.store(true, Ordering::Relaxed);
252    }
253
254    {
255        let mut g = runtime().lock().unwrap();
256        g.stop_tx = Some(stop_tx);
257        g.address = address;
258        g.network = net_name;
259        g.last_error = None;
260    }
261
262    log::info!("Nym: live — address claimed (keyRole=mixnet, seed in KeyVault)");
263    Ok(nym_live_status())
264}
265
266/// Disables Nym.
267pub async fn disable_nym() -> Result<NymLiveStatus, String> {
268    let stop = {
269        let mut g = runtime().lock().unwrap();
270        g.stop_tx.take()
271    };
272    if let Some(tx) = stop {
273        let _ = tx.send(()).await;
274        // Brief yield so disconnect can run.
275        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
276    }
277    if let Some(state) = APP_STATE.get() {
278        state.nym_relay_active.store(false, Ordering::Relaxed);
279    }
280    clear_nym_claim();
281    {
282        let mut g = runtime().lock().unwrap();
283        g.address.clear();
284        g.last_error = None;
285    }
286    Ok(nym_live_status())
287}
288
289/// Toggle: enable sandbox (or WEBIZEN_NYM_NETWORK) when off; disable when on.
290pub async fn toggle_nym_relay() -> Result<bool, String> {
291    let currently = APP_STATE
292        .get()
293        .map(|s| s.nym_relay_active.load(Ordering::Relaxed))
294        .unwrap_or(false);
295    if currently {
296        disable_nym().await?;
297        Ok(false)
298    } else {
299        match enable_nym(None).await {
300            Ok(st) => Ok(st.live),
301            Err(e) => {
302                if let Some(state) = APP_STATE.get() {
303                    state.nym_relay_active.store(false, Ordering::Relaxed);
304                }
305                {
306                    let mut g = runtime().lock().unwrap();
307                    g.last_error = Some(e.clone());
308                    g.stop_tx = None;
309                    g.address.clear();
310                }
311                clear_nym_claim();
312                Err(e)
313            }
314        }
315    }
316}
317
318/// Compile-time / unit helper: mixnet purpose context ≠ session-authentication.
319#[cfg(test)]
320mod purpose_sep_tests {
321    use super::*;
322    use qualia_core_db::key_vault::KeyVault;
323
324    #[test]
325    fn mixnet_key_role_is_not_session_authentication() {
326        assert_ne!(
327            KeyRole::Mixnet.as_str(),
328            KeyRole::SessionAuthentication.as_str()
329        );
330        assert_ne!(
331            KeyRole::Mixnet.vault_context(),
332            KeyRole::SessionAuthentication.vault_context()
333        );
334        assert_eq!(KeyRole::Mixnet.as_str(), "mixnet");
335    }
336
337    #[test]
338    fn derivation_salt_names_mixnet_not_session() {
339        let salt = String::from_utf8_lossy(MIXNET_DERIVATION_SALT);
340        assert!(salt.contains("mixnet"));
341        assert!(!salt.contains("session-authentication"));
342    }
343
344    #[test]
345    fn locked_vault_refuses_seed() {
346        let mut vault = KeyVault::new();
347        vault.lock();
348        assert!(vault.request_role_seed(KeyRole::Mixnet).is_err());
349        let g = vault.agent_request_role(KeyRole::Mixnet);
350        assert!(g.vault_locked);
351        assert!(!g.material_held_by_agent);
352    }
353}