leviathan-crypto 1.4.0 → 2.0.1

package/dist/docs/argon2id.md

@@ -5,19 +5,29 @@
 > [`argon2id`](https://www.npmjs.com/package/argon2id) npm package directly and
 > how to pair it with leviathan primitives for passphrase-based encryption.
 
+> ### Table of Contents
+> - [Why Argon2id](#why-argon2id)
+> - [Installation](#installation)
+> - [Basic usage](#basic-usage)
+> - [Parameter presets](#parameter-presets)
+> - [Password hashing and verification](#password-hashing-and-verification)
+> - [Passphrase-based encryption with leviathan-crypto](#passphrase-based-encryption-with-leviathan-crypto)
+> - [Memory note](#memory-note)
+
+---
+
 ## Why Argon2id
 
 Password hashing is the last line of defense when a database is breached. If an
 attacker obtains hashed passwords, the hash function determines how expensive it
-is to recover each plaintext. Traditional hash functions — even iterated ones
-like PBKDF2 — are fast on GPUs and custom hardware. An attacker with a few
+is to recover each plaintext. Traditional hash functions, even iterated ones like PBKDF2, are fast on GPUs and custom hardware. An attacker with a few
 thousand dollars of GPU hardware can test billions of PBKDF2-SHA256 candidates
 per second. bcrypt improves on this with a 4 KiB memory requirement that limits
 GPU parallelism, but 4 KiB is trivial by modern standards.
 
 Argon2 was the winner of the Password Hashing Competition (PHC, 2013–2015),
 selected from 24 submissions after two years of public analysis. It was designed
-specifically to be **memory-hard**, computing the hash requires not just CPU
+specifically to be **memory-hard**: computing the hash requires not just CPU
 time but a large block of RAM that cannot be traded away. An attacker who tries
 to use less memory must perform exponentially more computation, making GPU and
 ASIC attacks economically impractical.
@@ -145,21 +155,23 @@ const valid = constantTimeEqual(candidate, stored.hash);
 ## Passphrase-based encryption with leviathan-crypto
 
 Argon2id produces a root key from a passphrase. HKDF-SHA256 from leviathan then
-expands that root key into the separate encryption and MAC keys that
-`SerpentSeal` and `XChaCha20Poly1305` expect. Keeping the two steps separate
-means the expensive Argon2id call happens once per passphrase, and HKDF handles
-any further key material needed.
+expands that root key into the key material `Seal` and `XChaCha20Poly1305` expect.
+Keeping the two steps separate means the expensive Argon2id call happens once
+per passphrase, and HKDF handles any further key material needed.
 
-### With SerpentSeal
+### With Seal + SerpentCipher
 
-`SerpentSeal` takes a 64-byte key (32-byte enc key + 32-byte MAC key). HKDF
-expands the 32-byte Argon2id output to 64 bytes:
+`SerpentCipher` takes a 32-byte key. HKDF expands the 32-byte Argon2id output
+to 32 bytes with a domain-separation info string:
 
 ```typescript
 import loadArgon2idWasm from 'argon2id';
-import { init, SerpentSeal, HKDF_SHA256 } from 'leviathan-crypto';
+import { init, Seal, SerpentCipher, HKDF_SHA256 } from 'leviathan-crypto';
+
+import { serpentWasm } from 'leviathan-crypto/serpent/embedded';
+import { sha2Wasm }    from 'leviathan-crypto/sha2/embedded';
 
-await init(['serpent', 'sha2']);
+await init({ serpent: serpentWasm, sha2: sha2Wasm });
 const argon2id = await loadArgon2idWasm();
 
 // ── Encrypt ──────────────────────────────────────────────────────────────────
@@ -174,16 +186,14 @@ const rootKey = argon2id({
   tagLength:   32,
 });
 
-const hkdf    = new HKDF_SHA256();
-const fullKey = hkdf.derive(rootKey, argonSalt, new TextEncoder().encode('serpent-seal-v1'), 64);
+const hkdf = new HKDF_SHA256();
+const key  = hkdf.derive(rootKey, argonSalt, new TextEncoder().encode('myapp-serpent-key'), 32);
 hkdf.dispose();
 
-const serpent    = new SerpentSeal();
-const ciphertext = serpent.encrypt(fullKey, plaintext);
-serpent.dispose();
+const blob = Seal.encrypt(SerpentCipher, key, plaintext);
 
-// Store with ciphertext — all required for decryption
-const envelope = { ciphertext, argonSalt };
+// Store with blob — all required for decryption
+const envelope = { blob, argonSalt };
 
 // ── Decrypt ──────────────────────────────────────────────────────────────────
 
@@ -196,13 +206,11 @@ const rootKey2 = argon2id({
   tagLength:   32,
 });
 
-const hkdf2    = new HKDF_SHA256();
-const fullKey2 = hkdf2.derive(rootKey2, envelope.argonSalt, new TextEncoder().encode('serpent-seal-v1'), 64);
+const hkdf2 = new HKDF_SHA256();
+const key2  = hkdf2.derive(rootKey2, envelope.argonSalt, new TextEncoder().encode('myapp-serpent-key'), 32);
 hkdf2.dispose();
 
-const serpent2 = new SerpentSeal();
-const decrypted = serpent2.decrypt(fullKey2, envelope.ciphertext);
-serpent2.dispose();
+const decrypted = Seal.decrypt(SerpentCipher, key2, envelope.blob);
 ```
 
 ### With XChaCha20Poly1305
@@ -214,7 +222,10 @@ generated fresh per encryption; only the Argon2id salt needs to be stored:
 import loadArgon2idWasm from 'argon2id';
 import { init, XChaCha20Poly1305, HKDF_SHA256 } from 'leviathan-crypto';
 
-await init(['chacha20', 'sha2']);
+import { chacha20Wasm } from 'leviathan-crypto/chacha20/embedded';
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded';
+
+await init({ chacha20: chacha20Wasm, sha2: sha2Wasm });
 const argon2id = await loadArgon2idWasm();
 
 // ── Encrypt ──────────────────────────────────────────────────────────────────
@@ -232,7 +243,7 @@ const rootKey = argon2id({
 // tagLength: 32 already matches XChaCha20Poly1305's expected key size
 // HKDF is optional here but included for domain separation.
 const hkdf = new HKDF_SHA256();
-const key  = hkdf.derive(rootKey, argonSalt, new TextEncoder().encode('xchacha-v1'), 32);
+const key  = hkdf.derive(rootKey, argonSalt, new TextEncoder().encode('myapp-xchacha20-key'), 32);
 hkdf.dispose();
 
 const nonce = crypto.getRandomValues(new Uint8Array(24));
@@ -254,7 +265,7 @@ const rootKey2 = argon2id({
 });
 
 const hkdf2 = new HKDF_SHA256();
-const key2  = hkdf2.derive(rootKey2, envelope.argonSalt, new TextEncoder().encode('xchacha-v1'), 32);
+const key2  = hkdf2.derive(rootKey2, envelope.argonSalt, new TextEncoder().encode('myapp-xchacha20-key'), 32);
 hkdf2.dispose();
 
 const xc2       = new XChaCha20Poly1305();
@@ -265,13 +276,13 @@ xc2.dispose();
 > [!CAUTION]
 > Never reuse an Argon2id salt across different passphrases or key derivation
 > contexts. Generate a fresh random salt for each new encryption envelope. The
-> salt is not secret — store it in plaintext alongside the ciphertext.
+> salt is not secret. Store it in plaintext alongside the ciphertext.
 
 ---
 
 ## Memory note
 
->[!IMPORTANT]
+> [!IMPORTANT]
 > Each call to `loadArgon2idWasm()` instantiates a separate WASM instance. The
 > package's own documentation recommends reloading the module between hashes when
 > the `memorySize` varies significantly, since WASM linear memory is not
@@ -284,7 +295,8 @@ xc2.dispose();
 >
 > - [index](./README.md) — Project Documentation index
 > - [sha2](./sha2.md) — HKDF-SHA256 for key expansion from Argon2id root keys
-> - [serpent](./serpent.md) — SerpentSeal: Serpent-256 authenticated encryption (pairs with Argon2id-derived keys)
+> - [serpent](./serpent.md) — `SerpentCipher`: Serpent-256 cipher suite (use with `Seal` and Argon2id-derived keys)
+> - [authenticated encryption](./aead.md) — `Seal`: one-shot AEAD over any `CipherSuite`
 > - [chacha20](./chacha20.md) — XChaCha20Poly1305: ChaCha20 authenticated encryption (pairs with Argon2id-derived keys)
 > - [utils](./utils.md) — `randomBytes` for generating salts, `constantTimeEqual` for hash verification
 > - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline