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

Capability: crypto-keys

ADDED Requirements

Package identity

• REQ-KEYS-001: Package name @suaveplan/crypto-keys, packages/universal/crypto-keys.
• REQ-KEYS-002: Runtime deps: @suaveplan/crypto, @suaveplan/error, @suaveplan/types, tslib, zod.

Keypair generation

• REQ-KEYS-010: Exports generateKeypair(algo: SignAlgorithm | AgreeAlgorithm, opts?: { byteSource?: ByteSource; engine?: SignEngine | AgreeEngine }): Keypair.
• REQ-KEYS-011: Keypair = { publicKey: Uint8Array; secretKey: Uint8Array; algorithm: string }.
• REQ-KEYS-012: Delegates to the appropriate @suaveplan/crypto façade based on algo.

Keypair validation

• REQ-KEYS-020: Exports validateKeypair(keypair: Keypair): ValidationResult.
• REQ-KEYS-021: Checks: key lengths match algorithm constants, public key is derivable from secret key (for Ed25519 and X25519).
• REQ-KEYS-022: Returns { valid: boolean; errors: string[] }.

Keychain store

• REQ-KEYS-030: Exports Keychain class: { add(id: string, keypair: Keypair): void; get(id: string): Keypair | undefined; remove(id: string): void; list(): string[]; clear(): void }.
• REQ-KEYS-031: In-memory by default. Accepts an optional KeychainAdapter for persistence.
• REQ-KEYS-032: Exports KeychainAdapter interface: { load(): Promise<Map<string, Keypair>>; save(entries: Map<string, Keypair>): Promise<void> }.
• REQ-KEYS-033: Exports MemoryKeychainAdapter (default) and SerializedKeychainAdapter (serialises to/from JSON string via a provided read/write pair).

Error surface

• REQ-KEYS-040: Exports CryptoKeysError extends SuaveplanError<CryptoKeysCode>.
• REQ-KEYS-041: Codes: CRYPTO_KEYS.KEYPAIR.INVALID, CRYPTO_KEYS.KEYCHAIN.NOT_FOUND, CRYPTO_KEYS.ADAPTER.LOAD_FAILED, CRYPTO_KEYS.ADAPTER.SAVE_FAILED.