Add --hd-path flag to keys add --secure-store (#2539)

Author: fnando

FULL_HELP_DOCS.md

@@ -1138,6 +1138,7 @@ Add a new identity (keypair, ledger, OS specific secure store)
 
 - `--public-key <PUBLIC_KEY>` — Add a public key, ed25519, or muxed account, e.g. G1.., M2..
 - `--overwrite` — Overwrite existing identity if it already exists. When combined with --secure-store, also replaces the existing Secure Store entry
+- `--hd-path <HD_PATH>` — When importing a seed phrase into the Secure Store, which `hd_path` to derive the key at
 
 ###### **Options (Global):**
 
@@ -1206,7 +1207,7 @@ Generate a new identity using a 24-word seed phrase The seed phrase can be store
 
   On Mac this uses Keychain, on Windows it is Secure Store Service, and on \*nix platforms it uses a combination of the kernel keyutils and DBus-based Secret Service.
 
-- `--hd-path <HD_PATH>` — When generating a secret key, which `hd_path` should be used from the original `seed_phrase`
+- `--hd-path <HD_PATH>` — With `--as-secret` or `--secure-store`, which `hd_path` to derive the key at from the seed phrase
 - `--fund` — Fund generated key pair
 
   Default value: `false`

cmd/crates/soroban-test/tests/it/integration/secure_store.rs

@@ -113,4 +113,60 @@ async fn secure_store_key_management() {
         .success()
         .stdout_as_str();
     assert!(new_secure_store_address.starts_with('G'));
+
+    // `keys add --secure-store --hd-path N` must derive and cache the public
+    // key at the requested HD path, and persist `hd_path` in the identity TOML.
+    let seed_phrase = "aisle reflect depart add safe fury dress artist bronze abuse warrior clap inquiry ask mandate deputy view trade debate flip priority boy depart recipe";
+
+    let add_default = "secure-store-add-default";
+    sandbox
+        .new_assert_cmd("keys")
+        .write_stdin(format!("{seed_phrase}\n"))
+        .args(["add", add_default, "--secure-store"])
+        .assert()
+        .success();
+    let address_default = sandbox
+        .new_assert_cmd("keys")
+        .args(["address", add_default])
+        .assert()
+        .success()
+        .stdout_as_str();
+
+    let add_hd_path = "secure-store-add-hd-path";
+    sandbox
+        .new_assert_cmd("keys")
+        .write_stdin(format!("{seed_phrase}\n"))
+        .args(["add", add_hd_path, "--secure-store", "--hd-path", "5"])
+        .assert()
+        .success();
+    let address_hd_path = sandbox
+        .new_assert_cmd("keys")
+        .args(["address", add_hd_path, "--hd-path", "5"])
+        .assert()
+        .success()
+        .stdout_as_str();
+
+    assert!(address_hd_path.starts_with('G'));
+    assert_ne!(
+        address_default, address_hd_path,
+        "expected --hd-path 5 to derive a different public key than the default path"
+    );
+
+    let identity_path = sandbox
+        .config_dir()
+        .join("identity")
+        .join(format!("{add_hd_path}.toml"));
+    let identity_toml = std::fs::read_to_string(&identity_path).unwrap_or_else(|err| {
+        panic!("expected identity file at {identity_path:?}: {err}");
+    });
+    assert!(
+        identity_toml.contains("hd_path = 5"),
+        "expected hd_path = 5 to be persisted after `keys add --secure-store --hd-path 5`, \
+         but identity file was:\n{identity_toml}"
+    );
+    assert!(
+        identity_toml.contains(&format!("public_key = \"{}\"", address_hd_path.trim())),
+        "expected cached public_key to match the address derived at hd_path 5, \
+         but identity file was:\n{identity_toml}"
+    );
 }

cmd/soroban-cli/src/commands/keys/add.rs

@@ -61,6 +61,10 @@ pub struct Cmd {
     /// --secure-store, also replaces the existing Secure Store entry.
     #[arg(long)]
     pub overwrite: bool,
+
+    /// When importing a seed phrase into the Secure Store, which `hd_path` to derive the key at.
+    #[arg(long)]
+    pub hd_path: Option<usize>,
 }
 
 impl Cmd {
@@ -113,7 +117,7 @@ impl Cmd {
                 print,
                 &self.name,
                 &seed_phrase,
-                None,
+                self.hd_path,
                 self.overwrite,
             )?)
         } else {

cmd/soroban-cli/src/commands/keys/generate.rs

@@ -50,7 +50,7 @@ pub struct Cmd {
     #[command(flatten)]
     pub config_locator: locator::Args,
 
-    /// When generating a secret key, which `hd_path` should be used from the original `seed_phrase`.
+    /// With `--as-secret` or `--secure-store`, which `hd_path` to derive the key at from the seed phrase.
     #[arg(long)]
     pub hd_path: Option<usize>,