37 lines
2.4 KiB
Markdown
37 lines
2.4 KiB
Markdown
# 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`.
|