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

Capability: crypto-sodium-engine

ADDED Requirements

Package identity

• REQ-SOD-001: Package name @suaveplan/crypto-sodium, packages/universal/crypto-sodium.
• REQ-SOD-002: Runtime deps: libsodium-wrappers-sumo, @suaveplan/crypto, @suaveplan/error, tslib.
• REQ-SOD-003: Peer dep: @suaveplan/crypto at the same genesis version.

Initialisation

• REQ-SOD-010: Exports sodiumReady(): Promise<void> — resolves when libsodium-wrappers-sumo WASM is initialised. Idempotent; resolves immediately on subsequent calls.
• REQ-SOD-011: All engine implementations call await sodiumReady() internally; callers do not need to call it explicitly.

Engine implementations

• REQ-SOD-020: Exports sodiumAeadEngine: AeadEngine — implements AES-256-GCM (where available via hardware), ChaCha20-Poly1305, XChaCha20-Poly1305 via libsodium.
• REQ-SOD-021: Exports sodiumSignEngine: SignEngine — Ed25519 sign/verify/generateKeypair via libsodium.
• REQ-SOD-022: Exports sodiumAgreeEngine: AgreeEngine — X25519 agree/generateKeypair via libsodium.
• REQ-SOD-023: Exports sodiumSealedBoxEngine: SealedBoxEngine — crypto_box_seal / crypto_box_seal_open semantics.
• REQ-SOD-024: Exports sodiumAuthBoxEngine: AuthBoxEngine — crypto_box_easy / crypto_box_open_easy semantics.

Sodium-exclusive primitives

• REQ-SOD-030: Exports cryptoKdf(key: Uint8Array, subkeyId: number, context: string, length: number): Uint8Array — deterministic subkey derivation via crypto_kdf_derive_from_key. Context must be exactly 8 bytes when encoded.
• REQ-SOD-031: Exports cryptoAuth(key: Uint8Array, message: Uint8Array): Uint8Array — BLAKE2b-based MAC via crypto_auth.
• REQ-SOD-032: Exports cryptoAuthVerify(key: Uint8Array, message: Uint8Array, mac: Uint8Array): boolean — verifies BLAKE2b MAC.
• REQ-SOD-033: Exports cryptoPwhashStr(password: Uint8Array, opts?: { opsLimit?, memLimit? }): string — Argon2id encoded hash string (includes salt, ready to store).
• REQ-SOD-034: Exports cryptoPwhashStrVerify(hash: string, password: Uint8Array): boolean.
• REQ-SOD-035: Exports ristretto255 namespace: { add, sub, mul, fromHash, toBytes, fromBytes, random } — group operations.

Error surface

• REQ-SOD-040: Exports SodiumError extends SuaveplanError<SodiumCode>.
• REQ-SOD-041: Codes: SODIUM.INIT.FAILED, SODIUM.KDF.INVALID_CONTEXT, SODIUM.KDF.INVALID_LENGTH, SODIUM.AUTH.VERIFY_FAILED.