Persist --hd-path on plain seed-phrase keys

[fnando]

What

Persist --hd-path on seed-phrase identities (both plain seed-phrase and Secure Store) for stellar keys generate and stellar keys add, and honor it as a default in later derivations:

• Secret::SeedPhrase gains an optional hd_path field that travels with the identity.
• Secret::public_key / private_key / signer fall back to the persisted hd_path when the caller passes None.
• Secret::SecureStore already persisted hd_path on disk (see Cache secure-store public key in identity files. #2533), but ignored it at derivation time. It now also falls back to the persisted value when the caller passes None, matching Secret::SeedPhrase. Caller-supplied indices still take precedence.
• keys add rejects --hd-path against incompatible inputs (raw secret keys, --public-key).

Closes #2538.

Why

--hd-path was accepted but silently dropped on the plain seed-phrase path, and was persisted-but-ignored for Secure Store, so later commands derived index 0 unless the user re-passed the flag every time. Approach (3) from the issue (persist on the identity, schema-bumped with #[serde(default)]) keeps behavior consistent across all storage modes — without breaking identity files written before this field existed.

The Secure Store fallback was added during review after empirical testing showed keys public-key <name> returned the index-0 key even though hd_path was already on disk.

Known limitations

• Identity files written before this PR have no hd_path field; they parse fine and behave as before (derivation index defaults to 0). Re-running keys add / keys generate with --hd-path is the way to migrate them, but this is not required.
• --hd-path against a raw secret key or --public-key is now a hard error rather than being silently ignored. This is intentional but is a behavior change for anyone who was passing the flag in those modes.

[Copilot]

Pull request overview

This PR updates the Stellar CLI identity/secret model so --hd-path is persisted for plain seed-phrase identities (non-secure-store, non---as-secret) and then reused as the default derivation index in later commands.

Changes:

• Extend Secret::SeedPhrase with an optional persisted hd_path and make key derivation fall back to it when the caller doesn’t pass an index.
• Persist --hd-path for stellar keys generate and stellar keys add when storing a plain seed phrase; reject --hd-path for incompatible keys add modes (--public-key, raw secret key).
• Add/update unit tests and refresh help docs to reflect the new behavior.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
cmd/soroban-cli/src/config/secret.rs	Add hd_path to SeedPhrase secrets; default derivation uses persisted index; add TOML/back-compat tests.
cmd/soroban-cli/src/config/key.rs	Update key round-trip test construction for the new SeedPhrase shape.
cmd/soroban-cli/src/commands/keys/secret.rs	Update pattern match to tolerate the new SeedPhrase field.
cmd/soroban-cli/src/commands/keys/generate.rs	Persist hd_path for plain seed-phrase identities; update help text and add a test.
cmd/soroban-cli/src/commands/keys/add.rs	Persist hd_path when parsing seed phrases; reject hd_path for public key / secret key inputs; add tests.
cmd/crates/soroban-test/tests/it/util.rs	Update helper to construct SeedPhrase with hd_path: None.
FULL_HELP_DOCS.md	Update CLI help output text for --hd-path.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

[mootz12]

LG2M. Two somewhat related things flagged in comments. IMO we should either create issues to fix before the next release or fix in this PR.

The impl for plain seed-phrase keys approved, tho.

[leighmcculloch]

The code changes here look good, but I'm wondering if this will be experienced as a breaking change and if any thought needs to be given to a rollout, or protecting existing uses from happening?

For anybody who's already stored a key and they're using it in some places without passing the --hd-path, are they going to see changes?

...without breaking identity files written before this field existed.

From the PR description it sounds like this concern has been addressed already. If that's the case looks good to me.

[fnando]

@leighmcculloch this is a follow up on #2539, which defaults to --hd-path=0 if you have no saved path.