feat(wallet): version and tune per-wallet KDF encryption parameters

Author: gospeltout

DEVELOPER_GUIDE.md

@@ -179,6 +179,45 @@ export STARFORGE_CONFIG_DIR=~/.starforge-dev
 ### Secret Redaction & Security Logging
 StarForge enforces centralized secret redaction via `crate::utils::redaction::redact_secrets`. Tracing output streams (`RUST_LOG`) and CLI error output streams automatically sanitize Stellar secret keys (`S...`), hex private keys, BIP-39 mnemonic seed phrases, auth tokens (`Bearer`, `ghp_`, `sk-`), signed XDR transaction payloads, and embedded URL credentials before output. Existing helper functions (`redact_public_key`, `redact_secret_value`, `redact_signed_xdr`) delegate to this centralized engine.
 
+### Password-Based Encryption & KDF Parameter Tuning
+
+StarForge encrypts Stellar secret keys at rest using **Argon2id** key derivation and **AES-256-GCM** authenticated encryption.
+
+#### KDF Versioning & Schema Formats
+
+- **Version 1 (`KDF_VERSION_1 = 1`)**: Argon2id + AES-256-GCM.
+- **Bundle Formats**:
+  - Legacy 3-part: `salt:nonce:ciphertext` (library defaults: 32,768 KiB memory, 3 iterations, 1 parallelism thread).
+  - 5-part: `salt:nonce:ciphertext:mem:iterations` (custom memory cost and iteration count).
+  - 6-part: `salt:nonce:ciphertext:mem:iterations:parallelism` (custom memory, iterations, and parallelism).
+  - Versioned 7-part: `v1:salt:nonce:ciphertext:mem:iterations:parallelism` (explicit version prefixing for modern tuned bundles).
+
+#### Parameter Bounds & Safety Constraints
+
+- **Memory Cost (`mem`)**: Min 8,192 KiB (8 MiB), Max 2,097,152 KiB (2 GiB).
+- **Iterations (`iterations`)**: Min 1, Max 100.
+- **Parallelism (`parallelism`)**: Min 1, Max 64 threads.
+
+#### Per-Wallet Metadata & Safe Upgrades
+
+KDF parameters are stored per wallet (`WalletEntry.kdf_options` and metadata embedded in `secret_key`). Wallet encryption parameters can be tuned or upgraded safely without data loss using:
+
+```bash
+# Tune KDF parameters for a specific wallet
+starforge wallet tune-kdf alice --mem 65536 --iterations 4 --parallelism 2
+
+# Upgrade wallet KDF to global configuration settings
+starforge wallet tune-kdf alice --use-global
+```
+
+The upgrade procedure enforces zero-data-loss safety:
+1. Validates existing password against current bundle before making any changes.
+2. Validates new KDF parameters against security bounds.
+3. Re-encrypts secret key with new parameters.
+4. Performs a verification decryption round-trip on the new bundle before persisting changes to disk and database.
+5. If any validation or decryption step fails, the original encrypted secret and metadata remain completely unchanged.
+
+
 ### Development Workflow
 
 ```bash

src/commands/wallet.rs

@@ -270,6 +270,23 @@ pub enum WalletCommands {
         #[arg(long, value_enum)]
         hardware: Option<hardware_wallet::HardwareWalletKind>,
     },
+    /// Tune or upgrade KDF encryption parameters for a saved encrypted wallet
+    TuneKdf {
+        /// Wallet name to upgrade
+        name: String,
+        /// Argon2 memory cost in KiB (e.g. 65536)
+        #[arg(long)]
+        mem: Option<u32>,
+        /// Argon2 iteration count (e.g. 4)
+        #[arg(long)]
+        iterations: Option<u32>,
+        /// Argon2 parallelism factor (e.g. 2)
+        #[arg(long)]
+        parallelism: Option<u32>,
+        /// Upgrade to global configuration KDF parameters
+        #[arg(long, default_value = "false")]
+        use_global: bool,
+    },
     /// Derive all 10 Stellar addresses (m/44'/148'/0..9') from a BIP39 recovery phrase
     Derive,
     /// Multi-signature account management
@@ -450,10 +467,99 @@ pub async fn handle(cmd: WalletCommands) -> Result<()> {
             hardware,
         } => sign_message(name, message, hardware),
         WalletCommands::Derive => derive_addresses(),
+        WalletCommands::TuneKdf {
+            name,
+            mem,
+            iterations,
+            parallelism,
+            use_global,
+        } => tune_wallet_kdf(&name, mem, iterations, parallelism, use_global),
         WalletCommands::Multisig(cmd) => handle_multisig(cmd).await,
     }
 }
 
+fn tune_wallet_kdf(
+    name: &str,
+    mem: Option<u32>,
+    iterations: Option<u32>,
+    parallelism: Option<u32>,
+    use_global: bool,
+) -> Result<()> {
+    p::header(&format!("Tune KDF Encryption Parameters: '{}'", name));
+
+    let cfg = config::load()?;
+    let wallet = cfg
+        .wallets
+        .iter()
+        .find(|w| w.name == name)
+        .ok_or_else(|| anyhow::anyhow!("Wallet '{}' not found", name))?;
+
+    let secret_bundle = wallet
+        .secret_key
+        .as_ref()
+        .ok_or_else(|| anyhow::anyhow!("Wallet '{}' has no secret key saved", name))?;
+
+    if !secret_bundle.contains(':') {
+        anyhow::bail!(
+            "Wallet '{}' is unencrypted. Run `wallet rotate --encrypt` to enable encryption first.",
+            name
+        );
+    }
+
+    let current_meta = wallet
+        .kdf_metadata()
+        .ok_or_else(|| anyhow::anyhow!("Failed to parse current KDF metadata for '{}'", name))?;
+
+    p::kv("Current KDF Version", &current_meta.version.to_string());
+    p::kv("Current Memory", &format!("{} KiB", current_meta.mem));
+    p::kv("Current Iterations", &current_meta.iterations.to_string());
+    p::kv("Current Parallelism", &current_meta.parallelism.to_string());
+
+    if !use_global && mem.is_none() && iterations.is_none() && parallelism.is_none() {
+        anyhow::bail!(
+            "Specify at least one parameter to update (--mem, --iterations, --parallelism) or use --use-global."
+        );
+    }
+
+    let global_default = cfg.wallet_encryption.as_ref();
+    let target_options = if use_global {
+        global_default.cloned().unwrap_or_default()
+    } else {
+        crypto::KdfOptions {
+            mem: mem.or(Some(current_meta.mem)),
+            iterations: iterations.or(Some(current_meta.iterations)),
+            parallelism: parallelism.or(Some(current_meta.parallelism)),
+        }
+    };
+
+    target_options.validate()?;
+
+    let password = crypto::prompt_password("Enter wallet passphrase", false)?;
+
+    config::upgrade_wallet_kdf(name, &password, Some(target_options))?;
+
+    let updated_cfg = config::load()?;
+    let updated_wallet = updated_cfg
+        .wallets
+        .iter()
+        .find(|w| w.name == name)
+        .ok_or_else(|| anyhow::anyhow!("Wallet '{}' not found after upgrade", name))?;
+
+    if let Some(new_meta) = updated_wallet.kdf_metadata() {
+        p::separator();
+        p::success(&format!(
+            "Successfully upgraded KDF parameters for wallet '{}'",
+            name
+        ));
+        p::kv("Upgraded KDF Version", &new_meta.version.to_string());
+        p::kv("Upgraded Memory", &format!("{} KiB", new_meta.mem));
+        p::kv("Upgraded Iterations", &new_meta.iterations.to_string());
+        p::kv("Upgraded Parallelism", &new_meta.parallelism.to_string());
+    }
+
+    Ok(())
+}
+
 fn parse_duration(input: &str) -> Result<std::time::Duration> {
     let trimmed = input.trim().to_lowercase();
     if trimmed.ends_with("ms") {
@@ -694,13 +800,19 @@ async fn create(
     println!();
 
     p::step(2, steps, "Saving to ~/.starforge/config.toml…");
+    let kdf = if encrypt {
+        kdf_options(mem, iterations, parallelism, cfg.wallet_encryption.as_ref())
+    } else {
+        None
+    };
     let wallet = config::WalletEntry {
         name: name.clone(),
         public_key: public_key.clone(),
         secret_key: Some(secret_to_store),
         network: network.clone(),
         created_at: Utc::now().to_rfc3339(),
         funded: false,
+        kdf_options: kdf,
         rotation_history: Vec::new(),
     };
     cfg.wallets.push(wallet);
@@ -1670,6 +1782,7 @@ fn import_from_hardware(
         network,
         created_at: Utc::now().to_rfc3339(),
         funded: false,
+        kdf_options: None,
         rotation_history: vec![],
     });
     config::save(&updated_cfg)?;
@@ -1719,13 +1832,19 @@ fn import_from_mnemonic(
         secret_key
     };
 
+    let kdf = if encrypt {
+        kdf_options(None, None, None, cfg.wallet_encryption.as_ref())
+    } else {
+        None
+    };
     cfg.wallets.push(config::WalletEntry {
         name: name.clone(),
         public_key,
         secret_key: Some(secret_to_store),
         network: network.clone(),
         created_at: Utc::now().to_rfc3339(),
         funded: false,
+        kdf_options: kdf,
         rotation_history: Vec::new(),
     });
 
@@ -1777,13 +1896,19 @@ fn import_from_secret_key(
         secret_key
     };
 
+    let kdf = if encrypt {
+        kdf_options(None, None, None, cfg.wallet_encryption.as_ref())
+    } else {
+        None
+    };
     cfg.wallets.push(config::WalletEntry {
         name: name.clone(),
         public_key,
         secret_key: Some(secret_to_store),
         network,
         created_at: Utc::now().to_rfc3339(),
         funded: false,
+        kdf_options: kdf,
         rotation_history: Vec::new(),
     });
 
@@ -1835,13 +1960,23 @@ fn import_wallets(file: PathBuf) -> Result<()> {
 
     let imported = backup.wallets.len();
     for wallet in backup.wallets {
+        let kdf_options = wallet
+            .secret_key
+            .as_ref()
+            .and_then(|s| crypto::extract_kdf_metadata(s).ok())
+            .map(|m| crypto::KdfOptions {
+                mem: Some(m.mem),
+                iterations: Some(m.iterations),
+                parallelism: Some(m.parallelism),
+            });
         cfg.wallets.push(config::WalletEntry {
             name: wallet.name,
             public_key: wallet.public_key,
             secret_key: wallet.secret_key,
             network: wallet.network,
             created_at: wallet.created_at,
             funded: wallet.funded,
+            kdf_options,
             rotation_history: Vec::new(),
         });
     }

src/utils/config.rs

@@ -103,13 +103,39 @@ pub fn validate_network(network: &str) -> Result<()> {
 pub fn validate_secret_key(secret: &str) -> Result<()> {
     if secret.contains(':') {
         let parts: Vec<&str> = secret.split(':').collect();
+
+        if parts[0] == "v1" {
+            if parts.len() != 7 {
+                anyhow::bail!(
+                    "Invalid v1 encrypted secret bundle format: expected 7 parts (v1:salt:nonce:ciphertext:mem:iterations:parallelism), got {}",
+                    parts.len()
+                );
+            }
+            for part in parts.iter().skip(1).take(3) {
+                BASE64
+                    .decode(part)
+                    .map_err(|_| anyhow::anyhow!("Invalid base64 in encrypted secret bundle"))?;
+            }
+            let mem: u32 = parts[4]
+                .parse()
+                .map_err(|_| anyhow::anyhow!("Invalid KDF memory cost: must be a valid u32"))?;
+            let iterations: u32 = parts[5]
+                .parse()
+                .map_err(|_| anyhow::anyhow!("Invalid KDF iteration count: must be a valid u32"))?;
+            let parallelism: u32 = parts[6]
+                .parse()
+                .map_err(|_| anyhow::anyhow!("Invalid KDF parallelism factor: must be a valid u32"))?;
+            crypto::validate_kdf_params(Some(mem), Some(iterations), Some(parallelism))?;
+            return Ok(());
+        }
+
         // Accept:
         // - 3-part (legacy: salt:nonce:ciphertext)
         // - 5-part (KDF without p_cost: salt:nonce:ciphertext:mem:iterations)
         // - 6-part (KDF with p_cost: salt:nonce:ciphertext:mem:iterations:parallelism)
         if parts.len() != 3 && parts.len() != 5 && parts.len() != 6 {
             anyhow::bail!(
-                "Invalid encrypted secret bundle format: expected 3, 5, or 6 parts, got {}",
+                "Invalid encrypted secret bundle format: expected 3, 5, 6, or 7 parts, got {}",
                 parts.len()
             );
         }
@@ -122,19 +148,29 @@ pub fn validate_secret_key(secret: &str) -> Result<()> {
         }
 
         // If 5 or 6-part bundle, validate KDF parameters are valid u32
+        let mut mem = None;
+        let mut iterations = None;
+        let mut parallelism = None;
         if parts.len() >= 5 {
-            parts[3]
-                .parse::<u32>()
-                .map_err(|_| anyhow::anyhow!("Invalid KDF memory cost: must be a valid u32"))?;
-            parts[4]
-                .parse::<u32>()
-                .map_err(|_| anyhow::anyhow!("Invalid KDF iteration count: must be a valid u32"))?;
+            mem = Some(
+                parts[3]
+                    .parse::<u32>()
+                    .map_err(|_| anyhow::anyhow!("Invalid KDF memory cost: must be a valid u32"))?,
+            );
+            iterations = Some(
+                parts[4]
+                    .parse::<u32>()
+                    .map_err(|_| anyhow::anyhow!("Invalid KDF iteration count: must be a valid u32"))?,
+            );
         }
         if parts.len() == 6 {
-            parts[5].parse::<u32>().map_err(|_| {
-                anyhow::anyhow!("Invalid KDF parallelism factor: must be a valid u32")
-            })?;
+            parallelism = Some(
+                parts[5].parse::<u32>().map_err(|_| {
+                    anyhow::anyhow!("Invalid KDF parallelism factor: must be a valid u32")
+                })?,
+            );
         }
+        crypto::validate_kdf_params(mem, iterations, parallelism)?;
 
         return Ok(());
     }
@@ -657,10 +693,55 @@ pub struct WalletEntry {
     pub network: String,
     pub created_at: String,
     pub funded: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub kdf_options: Option<crypto::KdfOptions>,
     #[serde(default)]
     pub rotation_history: Vec<WalletRotationRecord>,
 }
 
+impl WalletEntry {
+    /// Get explicit or extracted KDF metadata for this wallet entry if encrypted.
+    pub fn kdf_metadata(&self) -> Option<crypto::KdfMetadata> {
+        let secret = self.secret_key.as_ref()?;
+        crypto::extract_kdf_metadata(secret).ok()
+    }
+}
+
+/// Upgrade or tune KDF parameters for a stored wallet.
+pub fn upgrade_wallet_kdf(
+    wallet_name: &str,
+    password: &str,
+    new_kdf: Option<crypto::KdfOptions>,
+) -> Result<()> {
+    let mut cfg = load()?;
+    let wallet = cfg
+        .wallets
+        .iter_mut()
+        .find(|w| w.name == wallet_name)
+        .ok_or_else(|| anyhow::anyhow!("Wallet '{}' not found", wallet_name))?;
+
+    let secret_bundle = wallet
+        .secret_key
+        .as_ref()
+        .ok_or_else(|| anyhow::anyhow!("Wallet '{}' has no secret key saved", wallet_name))?;
+
+    if !secret_bundle.contains(':') {
+        anyhow::bail!(
+            "Wallet '{}' secret key is not encrypted. KDF parameters can only be tuned for encrypted wallets.",
+            wallet_name
+        );
+    }
+
+    let upgraded_bundle =
+        crypto::upgrade_wallet_kdf_secret(password, secret_bundle, new_kdf.as_ref())?;
+
+    wallet.secret_key = Some(upgraded_bundle);
+    wallet.kdf_options = new_kdf;
+
+    save(&cfg)?;
+    Ok(())
+}
+
 #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
 pub struct WalletRotationRecord {
     pub rotated_at: String,