Epic: Android Vault Integration (Default, Seamless Key Storage for Altude SDK)

[mocolicious]

Objective
Build a Vault module for the Altude Android SDK, seamlessly integrated as the DEFAULT key storage and signing mechanism via Altude Gas Station initialization. Vault should be the default, feel native, but Gas Station must still support alternate signers. Most developers should not have to interact directly with Vault APIs.

Core Principles

• Altude never manages user keys server-side; it only relays signed transactions.
• Vault is strictly client-side: no custody, no MPC, no server-side recovery, no enclaves.
• Vault is the invisible default path; explicit APIs are only for advanced uses.
• The only explicit Vault interaction is selecting the signer strategy at init (defaults to Vault).
• Explicit Vault APIs for advanced cases are optional.

Desired Developer Experience (DX)

• Typical: AltudeGasStation.init(context, apiKey) // default is Vault
• Custom: AltudeGasStation.init(context, apiKey, signer = SignerStrategy.VaultDefault(...)) or SignerStrategy.External(...)
• Vault follows sensible defaults:
  • Use Vault if biometric/device credential available.
  • If not, fail with clear error or allow choosing external signer — never insecure fallback.
  • Fallback/document behavior precisely.

Epic Outcomes

• Gas Station wires all signing through a Signer abstraction. VaultSigner is the default.
• Non-vault signers remain supported.
• Future modules can plug into the Signer abstraction.

Architecture Requirements

• Create a TransactionSigner interface with methods for public key retrieval and signing.
• Gas Station uses this abstraction; VaultSigner is a concrete implementation.
• Default initialization sets TransactionSigner = VaultSigner, overrideable by dev.

Vault Behavior (mostly invisible)

• Root seed generated and stored encrypted locally.
• Decryption requires user auth (biometric/device credential).
• Ed25519 key derivation for Solana using HKDF with domain separation (appId, walletIndex).
• Session model (defaults to per-operation prompt or short TTL session).
• Prompts handled gracefully by Gas Station as needed.

SDK Initialization Design

• Default: AltudeGasStation.init(context, apiKey) → VaultSigner
• Advanced: AltudeGasStation.init(context, apiKey, options = InitOptions(signerStrategy=...))
• Only explicit "Vault choice" is through init options; most devs never use Vault APIs directly.

Fallback Behavior

• If biometrics unavailable: fail init with remediation steps (never fallback to insecure storage).
• If biometric invalidated: fail with KeyPermanentlyInvalidated.
• Uninstall: device-only keys unrecoverable unless explicit recovery feature enabled in future.

Deliverables

• Vault module/package (internal + advanced APIs)
• VaultSigner as TransactionSigner impl
• Gas Station orchestrates all signing through TransactionSigner, VaultSigner default
• Optional advanced Vault APIs: create, lock, clear, export blob
• Documentation: quickstart, advanced, errors and troubleshooting

Acceptance Criteria

• Dev can integrate and sign/relay with one-line init, no explicit handling of keys
• Default init uses Vault
• Gas Station supports external signers
• No plaintext secrets at rest; no secret logging
• Comprehensive unit/instrumentation tests
• Sample app covering Vault and non-Vault inits, common errors

---

Child issues to create under this epic:

1. Refactor: Introduce TransactionSigner abstraction + wire into Gas Station
2. Implement Vault module internals (seed gen, encrypt at rest, decrypt gated by user auth)
3. Implement VaultSigner (TransactionSigner) with HKDF derivation + Ed25519 signing
4. InitOptions + SignerStrategy API design + defaults
5. UX: BiometricPrompt integration inside signing path (per-op vs TTL session)
6. Error taxonomy + developer messaging + troubleshooting docs
7. Unit tests + instrumentation tests (as feasible)
8. Sample app + integration docs updates

Notes

• Use Jetpack BiometricPrompt
• Prefer Android Keystore AES-GCM/StrongBox
• Established crypto libs for HKDF/Ed25519
• Vault mostly invisible for simple/typical uses