feat(platform-wallet): add SecretStore keyring + encrypted-file secret backends (secrets feature)

[Claudius-Maginificent]

DRAFT PR — do not merge until CI has been run and #3625 lands.

STACKED ON #3625 (feat/platform-wallet-sqlite-persistor). The base branch for this PR is feat/platform-wallet-sqlite-persistor, not v3.1-dev. Please diff against that base, and merge this PR only after #3625 lands (or rebase onto v3.1-dev at that point).

---

Issue being fixed or feature implemented

Wallet apps built on rs-platform-wallet need a place to persist secret material — BIP-39 mnemonics, BIP-32 seeds, xpriv keys — so a wallet can be rehydrated from storage without the user re-entering their phrase every time. The SQLite persister introduced in #3625 deliberately stores only public/correlation state (UTXOs, identities, contacts, token balances). It must never hold secret bytes, and currently has no companion that does.

Imagine you are building a mobile or desktop wallet on top of rs-platform-wallet. You derive a BIP-39 mnemonic at setup, persist the wallet state via the SQLite backend, and your user closes the app. On next launch, you need to rehydrate the wallet — reconstruct its derived keys — without asking the user to re-enter their phrase. You need a place to store that phrase that is: (a) outside the SQLite file, so backups and DB exports stay secret-free; (b) authenticated and encrypted at rest; (c) keyed by wallet identity, not by the wallet file path. This PR delivers that capability as an explicit, opt-in module, behind a Cargo feature that is off by default.

---

What was done?

New module: platform_wallet_storage::secrets (behind --features secrets)

The secrets Cargo feature (previously a no-op stub at Cargo.toml:110) now activates a complete secrets subsystem under src/secrets/. The feature is not in default — a build that does not opt in compiles exactly as before, with no new dependencies.

SecretStore trait (src/secrets/store.rs)

pub trait SecretStore: Send + Sync {
    fn put(&self, wallet_id: WalletId, label: &str, bytes: &[u8])
        -> Result<(), SecretStoreError>;
    fn get(&self, wallet_id: WalletId, label: &str)
        -> Result<Option<SecretBytes>, SecretStoreError>;
    fn delete(&self, wallet_id: WalletId, label: &str)
        -> Result<(), SecretStoreError>;
}

get returns Option<SecretBytes> — a zeroize-on-drop wrapper, never a bare Vec<u8>. label is validated against ^[A-Za-z0-9._-]{1,64}$ before any backend touches it; wallet_id is a fixed-width 32-byte newtype. An ergonomic put_secret default method accepts &SecretBytes directly. The trait is Send + Sync; a compile assertion mirrors the existing _send_sync_check block.

Zeroizing wrappers (src/secrets/secret.rs)

Two types carry secret material:

• SecretBytes — net-new, byte-oriented, wraps Zeroizing<Vec<u8>>. Redacting Debug ([REDACTED; N]), no Display/Deref/Serialize, constant-time equality via subtle::ConstantTimeEq, best-effort mlock via region. The type used for seeds, derived keys, AEAD key, and decrypted plaintext.
• SecretString — a trimmed in-crate fork of the Secret type from dash-evo-tool (src/model/secret.rs), MIT, with attribution preserved. The egui::TextBuffer impl (including its documented take() leak) is deleted in full — this crate has no egui dependency and the leak vector cannot exist by construction. Redacting Debug, no Display/Deref/Serialize, full-capacity zeroize Drop. Used for mnemonics and passphrases. The PartialEq constant-time XOR fold is retained for passphrase UX equality only; its length-leak caveat is documented in rustdoc and it is explicitly not used for any security decision.

The one unsafe block (slice-from-raw-parts in the forked Drop) carries a // SAFETY: proof and a narrowly-scoped #[allow(unsafe_code)]; the crate-wide #![deny(unsafe_code)] is not relaxed.

Error type (src/secrets/error.rs)

SecretStoreError is a concrete thiserror enum — no Box<dyn Error>, no #[non_exhaustive], no secret bytes in any variant, static #[error("...")] strings. This satisfies the existing NFR-4 / TC-082 grep guard. Variants: BackendUnavailable, KeyringLocked, NotFound, Decrypt, InvalidLabel, Io, KdfFailure, VersionUnsupported, WrongPassphrase, InsecurePermissions.

KdfFailure and Decrypt deliberately omit #[source] — the upstream Argon2 and AEAD errors carry no useful non-secret diagnostic and risk leaking structure.

KeyringStore (src/secrets/keyring.rs)

Uses keyring-core 1.0.0 (the split-crate model) plus per-platform credential-store crates. Namespacing: service = "dash.platform-wallet-storage", account = "{wallet_id_hex}:{label}" — two wallets cannot collide, a different app cannot silently read the entry. Keyring item attributes carry only the non-secret wallet/label index.

Fail-closed by design. Headless Linux (no Secret Service), locked collections, and unavailable daemons surface as typed BackendUnavailable / KeyringLocked errors. There is no silent fallback to plaintext or to EncryptedFileStore. The operator selects the backend explicitly. Per-OS caveats (macOS Keychain ACL, Windows DPAPI same-user limitation, headless Linux) are documented in rustdoc on the impl.

EncryptedFileStore (src/secrets/file/)

Argon2id + XChaCha20-Poly1305 vault file, fully under our control:

• KDF: Argon2id (argon2 0.5.3, pinned) with enforced floors (m ≥ 19 MiB, t ≥ 2, p = 1) and shipped defaults (m = 64 MiB, t = 3). Parameters stored in the file header so future hardening does not strand existing vaults.
• Salt: 32 bytes from OsRng/getrandom, per-vault, unique, in the header. Never constant, never derived from wallet_id or path.
• AEAD: XChaCha20-Poly1305 (chacha20poly1305 0.10.1, pinned). No unauthenticated mode. aes-gcm is deliberately absent.
• Nonce: random 24-byte XNonce freshly generated for every put, stored alongside the ciphertext. Counters are explicitly forbidden (multi-process / restart / file-copy scenario would reuse counter values — catastrophic keystream reuse).
• AAD: canonical length-prefixed format_version ‖ wallet_id ‖ label. Decryption under a different (wallet_id, label) or a rolled-back format_version fails the Poly1305 tag. Blob-swap and replay attacks are structurally rejected.
• Tag failure: returns SecretStoreError::Decrypt and exposes zero decrypted-but-unverified bytes. The combined (non-detached) AEAD decrypt API is used so unverified plaintext is never materialized — consistent with the behavioural lesson of RUSTSEC-2023-0096.
• Passphrase-verification token: a header-stored token allows detecting a wrong passphrase before a full decrypt attempt, without exposing ciphertext bytes.
• File permissions: created at mode 0600 via O_EXCL + fchmod before any plaintext-derived byte is written (not chmod-after). A pre-existing file with looser permissions surfaces as SecretStoreError::InsecurePermissions — never blindly overwritten.
• Atomic + durable writes: temp file in the same directory at 0600, write, fsync temp, rename over target, fsync directory. A crash mid-write never truncates the prior vault.
• Rekey: decrypt-all → re-derive with fresh salt + current params → re-encrypt with fresh per-entry nonces → same atomic replace. No .bak left holding old key material.

MemoryStore (src/secrets/memory.rs)

Test-only backend, gated behind __secrets-test-helpers so it is unreachable from production builds. Stored values are SecretBytes so the zeroize contract is exercised even in tests.

Secrets guard (tests/secrets_guard.rs)

Positive guard test scanning src/secrets/ for tracing::/println!/format! of expose_secret() or plaintext — the complement to tests/secrets_scan.rs, which scans src/sqlite/ and explicitly exempts src/secrets/.

CI: cargo-deny advisories gate (.github/workflows/security-audit-rust.yml, deny.toml)

cargo audit and cargo deny advisories now run with --features secrets in CI so the crypto dependencies (previously unreachable from the default feature set) are covered. All crypto pins are RustSec-clean at adoption (independently verified against the RustSec advisory-db for chacha20poly1305, argon2, zeroize, region, subtle; aes-gcm is not present).

Secrets boundary: unchanged and enforced

The SECRETS.md boundary remains intact. The secrets module lives entirely under src/secrets/. The tests/secrets_scan.rs guard covers src/sqlite/schema/ and migrations/ and exempts src/secrets/ by design — this separation is load-bearing, not stylistic. The new tests/secrets_guard.rs covers the exempt side.

Out of scope for this PR

The SeedProvider trait and the rehydration seam (load_from_persistor signature, wrong-seed gate hardening in rs-platform-wallet/src/manager/load.rs) are not in this PR. They land with the rehydration PR-2 (item S), which depends on this PR as a hard prerequisite. This PR delivers the storage capability; PR-2 delivers the policy that consumes it.

---

How Has This Been Tested?

The following commands form the gate. CI has not yet been run on this branch (it is a draft); commands are the intended test plan.

# Format and lint
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings

# Default build — must compile without secrets
cargo check -p rs-platform-wallet-storage

# With secrets feature — full test suite
cargo test -p rs-platform-wallet-storage --features secrets

# Without secrets feature — confirm no bleed-through
cargo test -p rs-platform-wallet-storage

# Doc tests
cargo test -p rs-platform-wallet-storage --features secrets --doc

# Secrets scan (SQLite side — must stay green)
cargo test -p rs-platform-wallet-storage secrets_scan

# Positive secrets guard (secrets side — must stay green)
cargo test -p rs-platform-wallet-storage secrets_guard

# Zeroize-on-drop (single-threaded, marked #[ignore] by default)
cargo test -p rs-platform-wallet-storage --features secrets -- --ignored --test-threads=1

# Dependency audit with secrets feature (new CI gate)
cargo deny check advisories --features secrets

The following test categories are covered in tests/secrets_api.rs and tests/secrets_guard.rs:

• Round-trip via all three backends (put → drop → reopen → get — byte-exact)
• delete idempotent; missing label → Ok(None)
• Wrong passphrase → SecretStoreError::Decrypt, zero decrypted bytes returned
• AAD blob-swap: ciphertext moved to a different (wallet_id, label) slot → rejected
• Nonce uniqueness across multiple put operations
• Header version rollback → VersionUnsupported
• Vault file at looser-than-0600 → InsecurePermissions
• Crash-mid-write simulation: prior vault intact, no plaintext temp file left
• Rekey: old-key ciphertext unrecoverable, no .bak retained
• Debug of SecretBytes/SecretString is redacted — no secret bytes in output
• MemoryStore unreachable from a --features build that omits __secrets-test-helpers
• Secrets guard scan: no expose_secret() piped into tracing! or format! in src/secrets/
• KeyringStore headless-Linux path: fails with typed error, no panic, no plaintext fallback (CI-gated / #[ignore] on headless)

The PR has been through an internal multi-agent review covering security requirements (threat model, crypto construction, memory hygiene, dependency vetting), QA test coverage, and consistency with the codebase's existing patterns. Findings from that review are reflected in the implementation; no CRITICAL or HIGH items remain open against this PR's scope.

---

Breaking Changes

None. This PR is purely additive:

• The secrets feature is not in default and never will be without an explicit decision. No existing code path changes.
• SECRETS.md is updated to reflect the delivered API (not a contract change — the boundary it describes is unchanged and now enforced by more tests).
• The deny.toml and .github/workflows/security-audit-rust.yml additions are CI-only and do not affect library consumers.

---

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
• I have made corresponding changes to the documentation if needed

For repository code-owners and collaborators only

• I have assigned this pull request to a milestone

---

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b6e14d71-0e56-4ab6-af76-b9a2ab8e44a7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/platform-wallet-storage-secrets

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}