# @suaveplan/crypto-sodium - libsodium-backed engine implementations for @suaveplan/crypto — AEAD (XChaCha20-Poly1305, ChaCha20-Poly1305, AES-256-GCM), Ed25519 sign, X25519 agree, sealed-box, auth-box, KDF, BLAKE2b auth, Argon2id pwhash, Ristretto255 group ops.

## Summary

libsodium-backed engine implementations for `@suaveplan/crypto`. Provides AEAD encryption, Ed25519 signing, X25519 key agreement, sealed-box, auth-box, deterministic KDF, BLAKE2b MAC, Argon2id password hashing, and Ristretto255 group operations — all via the `libsodium-wrappers-sumo` WASM module.

<!-- begin:auto-docs -->
## Documentation tree

- [sodium-aead-engine](./src/engines/sodium-aead-engine/sodium-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [sodium-aead-engine](./src/engines/sodium-aead-engine/sodium-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [sodium-agree-engine](./src/engines/sodium-agree-engine/sodium-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [sodium-agree-engine](./src/engines/sodium-agree-engine/sodium-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [sodium-auth-box-engine](./src/engines/sodium-auth-box-engine/sodium-auth-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [sodium-auth-box-engine](./src/engines/sodium-auth-box-engine/sodium-auth-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [sodium-sealed-box-engine](./src/engines/sodium-sealed-box-engine/sodium-sealed-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [sodium-sealed-box-engine](./src/engines/sodium-sealed-box-engine/sodium-sealed-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [sodium-sign-engine](./src/engines/sodium-sign-engine/sodium-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [sodium-sign-engine](./src/engines/sodium-sign-engine/sodium-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [sodium-error](./src/errors/sodium-error/sodium-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [sodium-error](./src/errors/sodium-error/sodium-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [crypto-auth](./src/primitives/crypto-auth/crypto-auth.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [crypto-auth](./src/primitives/crypto-auth/crypto-auth.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [crypto-kdf](./src/primitives/crypto-kdf/crypto-kdf.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [crypto-kdf](./src/primitives/crypto-kdf/crypto-kdf.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [crypto-pwhash](./src/primitives/crypto-pwhash/crypto-pwhash.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [crypto-pwhash](./src/primitives/crypto-pwhash/crypto-pwhash.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [ristretto255](./src/primitives/ristretto255/ristretto255.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [ristretto255](./src/primitives/ristretto255/ristretto255.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [sodium-aead-engine](./src/engines/sodium-aead-engine/sodium-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-agree-engine](./src/engines/sodium-agree-engine/sodium-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-agree-engine](./src/engines/sodium-agree-engine/sodium-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-auth-box-engine](./src/engines/sodium-auth-box-engine/sodium-auth-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-auth-box-engine](./src/engines/sodium-auth-box-engine/sodium-auth-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sealed-box-engine](./src/engines/sodium-sealed-box-engine/sodium-sealed-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sealed-box-engine](./src/engines/sodium-sealed-box-engine/sodium-sealed-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sign-engine](./src/engines/sodium-sign-engine/sodium-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sign-engine](./src/engines/sodium-sign-engine/sodium-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-error](./src/errors/sodium-error/sodium-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-error](./src/errors/sodium-error/sodium-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-auth](./src/primitives/crypto-auth/crypto-auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-auth](./src/primitives/crypto-auth/crypto-auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-kdf](./src/primitives/crypto-kdf/crypto-kdf.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-kdf](./src/primitives/crypto-kdf/crypto-kdf.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-pwhash](./src/primitives/crypto-pwhash/crypto-pwhash.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-pwhash](./src/primitives/crypto-pwhash/crypto-pwhash.md) — <!-- begin:auto-docs --> _(no submodules)_- [ristretto255](./src/primitives/ristretto255/ristretto255.md) — <!-- begin:auto-docs --> _(no submodules)_- [ristretto255](./src/primitives/ristretto255/ristretto255.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-aead-engine](./src/engines/sodium-aead-engine/sodium-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-agree-engine](./src/engines/sodium-agree-engine/sodium-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-agree-engine](./src/engines/sodium-agree-engine/sodium-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-auth-box-engine](./src/engines/sodium-auth-box-engine/sodium-auth-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-auth-box-engine](./src/engines/sodium-auth-box-engine/sodium-auth-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sealed-box-engine](./src/engines/sodium-sealed-box-engine/sodium-sealed-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sealed-box-engine](./src/engines/sodium-sealed-box-engine/sodium-sealed-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sign-engine](./src/engines/sodium-sign-engine/sodium-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sign-engine](./src/engines/sodium-sign-engine/sodium-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-error](./src/errors/sodium-error/sodium-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-error](./src/errors/sodium-error/sodium-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-auth](./src/primitives/crypto-auth/crypto-auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-auth](./src/primitives/crypto-auth/crypto-auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-kdf](./src/primitives/crypto-kdf/crypto-kdf.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-kdf](./src/primitives/crypto-kdf/crypto-kdf.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-pwhash](./src/primitives/crypto-pwhash/crypto-pwhash.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-pwhash](./src/primitives/crypto-pwhash/crypto-pwhash.md) — <!-- begin:auto-docs --> _(no submodules)_- [ristretto255](./src/primitives/ristretto255/ristretto255.md) — <!-- begin:auto-docs --> _(no submodules)_- [ristretto255](./src/primitives/ristretto255/ristretto255.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-aead-engine](./src/engines/sodium-aead-engine/sodium-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-agree-engine](./src/engines/sodium-agree-engine/sodium-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-agree-engine](./src/engines/sodium-agree-engine/sodium-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-auth-box-engine](./src/engines/sodium-auth-box-engine/sodium-auth-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-auth-box-engine](./src/engines/sodium-auth-box-engine/sodium-auth-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sealed-box-engine](./src/engines/sodium-sealed-box-engine/sodium-sealed-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sealed-box-engine](./src/engines/sodium-sealed-box-engine/sodium-sealed-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sign-engine](./src/engines/sodium-sign-engine/sodium-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sign-engine](./src/engines/sodium-sign-engine/sodium-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-error](./src/errors/sodium-error/sodium-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-error](./src/errors/sodium-error/sodium-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-auth](./src/primitives/crypto-auth/crypto-auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-auth](./src/primitives/crypto-auth/crypto-auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-kdf](./src/primitives/crypto-kdf/crypto-kdf.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-kdf](./src/primitives/crypto-kdf/crypto-kdf.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-pwhash](./src/primitives/crypto-pwhash/crypto-pwhash.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-pwhash](./src/primitives/crypto-pwhash/crypto-pwhash.md) — <!-- begin:auto-docs --> _(no submodules)_- [ristretto255](./src/primitives/ristretto255/ristretto255.md) — <!-- begin:auto-docs --> _(no submodules)_- [ristretto255](./src/primitives/ristretto255/ristretto255.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-aead-engine](./src/engines/sodium-aead-engine/sodium-aead-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-agree-engine](./src/engines/sodium-agree-engine/sodium-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_  - [sodium-agree-engine](./src/engines/sodium-agree-engine/sodium-agree-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-auth-box-engine](./src/engines/sodium-auth-box-engine/sodium-auth-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_  - [sodium-auth-box-engine](./src/engines/sodium-auth-box-engine/sodium-auth-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sealed-box-engine](./src/engines/sodium-sealed-box-engine/sodium-sealed-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_  - [sodium-sealed-box-engine](./src/engines/sodium-sealed-box-engine/sodium-sealed-box-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-sign-engine](./src/engines/sodium-sign-engine/sodium-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_  - [sodium-sign-engine](./src/engines/sodium-sign-engine/sodium-sign-engine.md) — <!-- begin:auto-docs --> _(no submodules)_- [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_  - [codes](./src/errors/codes/codes.md) — <!-- begin:auto-docs --> _(no submodules)_- [sodium-error](./src/errors/sodium-error/sodium-error.md) — <!-- begin:auto-docs --> _(no submodules)_  - [sodium-error](./src/errors/sodium-error/sodium-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_  - [init](./src/init/init.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-auth](./src/primitives/crypto-auth/crypto-auth.md) — <!-- begin:auto-docs --> _(no submodules)_  - [crypto-auth](./src/primitives/crypto-auth/crypto-auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-kdf](./src/primitives/crypto-kdf/crypto-kdf.md) — <!-- begin:auto-docs --> _(no submodules)_  - [crypto-kdf](./src/primitives/crypto-kdf/crypto-kdf.md) — <!-- begin:auto-docs --> _(no submodules)_- [crypto-pwhash](./src/primitives/crypto-pwhash/crypto-pwhash.md) — <!-- begin:auto-docs --> _(no submodules)_  - [crypto-pwhash](./src/primitives/crypto-pwhash/crypto-pwhash.md) — <!-- begin:auto-docs --> _(no submodules)_- [ristretto255](./src/primitives/ristretto255/ristretto255.md) — <!-- begin:auto-docs --> _(no submodules)_  - [ristretto255](./src/primitives/ristretto255/ristretto255.md) — <!-- begin:auto-docs --> _(no submodules)_
## Installation

```sh
bun add @suaveplan/crypto-sodium
```

## Initialisation

libsodium loads as WebAssembly. Call `sodiumReady()` before using any synchronous engine:

```ts
import { sodiumReady } from "@suaveplan/crypto-sodium/init";
await sodiumReady(); // one-time WASM init
```

Async primitives (`cryptoKdf`, `cryptoAuth`, `ristretto255.*`, etc.) call `sodiumReady()` internally.

## Modules

| Subpath | Exports |
|---------|---------|
| `@suaveplan/crypto-sodium` | Everything (re-exports all modules) |
| `@suaveplan/crypto-sodium/init` | [`init.md`](src/init/init.md) — `sodiumReady` |
| `@suaveplan/crypto-sodium/engines` | All five engines |
| `@suaveplan/crypto-sodium/engines/aead` | [`sodium-aead-engine.md`](src/engines/sodium-aead-engine.md) — AEAD |
| `@suaveplan/crypto-sodium/engines/sign` | [`sodium-sign-engine.md`](src/engines/sodium-sign-engine.md) — Ed25519 |
| `@suaveplan/crypto-sodium/engines/agree` | [`sodium-agree-engine.md`](src/engines/sodium-agree-engine.md) — X25519 |
| `@suaveplan/crypto-sodium/engines/sealed-box` | [`sodium-sealed-box-engine.md`](src/engines/sodium-sealed-box-engine.md) — anonymous box |
| `@suaveplan/crypto-sodium/engines/auth-box` | [`sodium-auth-box-engine.md`](src/engines/sodium-auth-box-engine.md) — authenticated box |
| `@suaveplan/crypto-sodium/primitives/kdf` | [`crypto-kdf.md`](src/primitives/crypto-kdf.md) — BLAKE2b KDF |
| `@suaveplan/crypto-sodium/primitives/auth` | [`crypto-auth.md`](src/primitives/crypto-auth.md) — BLAKE2b MAC |
| `@suaveplan/crypto-sodium/primitives/pwhash` | [`crypto-pwhash.md`](src/primitives/crypto-pwhash.md) — Argon2id |
| `@suaveplan/crypto-sodium/primitives/ristretto255` | [`ristretto255.md`](src/primitives/ristretto255.md) — group ops |
| `@suaveplan/crypto-sodium/errors` | [`sodium-error.md`](src/errors/sodium-error.md) — `SodiumError`, `SODIUM_CODES` |

## Quick Examples

```ts
import { sodiumReady, sodiumSignEngine, cryptoKdf } from "@suaveplan/crypto-sodium";

await sodiumReady();

// Ed25519 sign/verify
const kp = sodiumSignEngine.generateKeypair();
const sig = sodiumSignEngine.sign(kp.secretKey, new TextEncoder().encode("msg"));
const ok = sodiumSignEngine.verify(kp.publicKey, sig, new TextEncoder().encode("msg"));

// BLAKE2b KDF
const masterKey = crypto.getRandomValues(new Uint8Array(32));
const encKey = await cryptoKdf(masterKey, 1, "SuavEncr", 32);
```

## License

MIT