suaveplan/openspec/archive/2026-04-18-enterprise-crypto-family/specs/crypto-vault/spec.md

Capability: crypto-vault

ADDED Requirements

Package identity

• REQ-VAULT-001: Package name @suaveplan/crypto-vault, packages/universal/crypto-vault.
• REQ-VAULT-002: Runtime deps: @suaveplan/crypto, @suaveplan/crypto-keys, @suaveplan/hash, @suaveplan/events, @suaveplan/error, @suaveplan/types, @scure/bip39, tslib, zod.

BIP39 mnemonic

• REQ-VAULT-010: Exports generateMnemonic(wordCount?: 12 | 15 | 18 | 21 | 24, opts?: { byteSource? }): string.
• REQ-VAULT-011: Exports validateMnemonic(mnemonic: string): boolean.
• REQ-VAULT-012: Exports mnemonicToSeed(mnemonic: string, passphrase?: string): Uint8Array — 64-byte seed via PBKDF2-SHA512 per BIP39.

Vault lifecycle

• REQ-VAULT-020: Exports Vault class: { unlock(mnemonic, passphrase?), lock(), isLocked(): boolean, sign(keyId, message), derive(path), getPublicKey(keyId) }.
• REQ-VAULT-021: Unlock derives a master key via Argon2id from the mnemonic seed. Locked vault holds no key material in memory.
• REQ-VAULT-022: lock() calls zeroize on all in-memory key buffers before clearing references.
• REQ-VAULT-023: Vault emits typed events via @suaveplan/events: unlocked, locked, signed, derived.

Chain signer

• REQ-VAULT-030: Exports ChainSigner class: { addKey(id, keypair), removeKey(id), sign(keyId, message, opts?) }.
• REQ-VAULT-031: Signs using the key algorithm associated with the stored keypair.

Error surface

• REQ-VAULT-040: Exports CryptoVaultError extends SuaveplanError<CryptoVaultCode>.
• REQ-VAULT-041: Codes: CRYPTO_VAULT.LOCKED, CRYPTO_VAULT.MNEMONIC.INVALID, CRYPTO_VAULT.KEY.NOT_FOUND, CRYPTO_VAULT.DERIVATION.FAILED.