90 lines
16 KiB
Markdown
90 lines
16 KiB
Markdown
# @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
|