leviathan-crypto 1.4.0 → 2.0.0

package/dist/docs/sha2.md

@@ -1,4 +1,4 @@
-# SHA-2 hash functions and HMAC TypeScript API
+# SHA-2 TypeScript API
 
 > [!NOTE]
 > Cryptographic hashing and message authentication using SHA-256, SHA-384,
@@ -6,42 +6,49 @@
 >
 > See [SHA-2 implementation audit](./sha2_audit.md), [HMAC audit](./hmac_audit.md), and [HKDF audit](./hkdf_audit.md) for algorithm correctness verifications.
 
+> ### Table of Contents
+> - [Overview](#overview)
+> - [Security Notes](#security-notes)
+> - [Module Init](#module-init)
+> - [API Reference](#api-reference)
+> - [Usage Examples](#usage-examples)
+> - [Error Conditions](#error-conditions)
+
+---
+
 ## Overview
 
 SHA-2 is a family of cryptographic hash functions standardized in
 [FIPS 180-4](https://csrc.nist.gov/publications/detail/fips/180/4/final).
-A hash function takes an input of any size -- a password, a file, a single
-byte -- and produces a fixed-size output called a **digest** (sometimes called
+A hash function takes an input of any size (a password, a file, a single byte) and produces a fixed-size output called a **digest** (sometimes called
 a "fingerprint" or "hash"). Even the smallest change to the input produces a
 completely different digest. This makes hash functions useful for verifying that
 data has not been tampered with.
 
 leviathan-crypto provides three SHA-2 variants:
 
-- **SHA-256** -- 32-byte (256-bit) digest. The most widely used variant. Use
-  this unless you have a specific reason to choose another.
-- **SHA-512** -- 64-byte (512-bit) digest. Higher security margin. Faster than
-  SHA-256 on 64-bit platforms.
-- **SHA-384** -- 48-byte (384-bit) digest. A truncated variant of SHA-512.
-  Useful when you need a digest longer than 256 bits but shorter than 512 bits,
-  or when a protocol specifies it (e.g. TLS cipher suites).
+**SHA-256.** 32-byte (256-bit) digest. The most widely used variant. Use this unless you have a specific reason to choose another.
+
+**SHA-512.** 64-byte (512-bit) digest. Higher security margin. Faster than SHA-256 on 64-bit platforms.
+
+**SHA-384.** 48-byte (384-bit) digest. A truncated variant of SHA-512. Useful when you need a digest longer than 256 bits but shorter than 512 bits, or when a protocol specifies it (e.g. TLS cipher suites).
 
 **HMAC** (Hash-based Message Authentication Code, [RFC 2104](https://www.rfc-editor.org/rfc/rfc2104))
 combines a secret key with a hash function to produce a **tag** that proves both
 the integrity and the authenticity of a message. Anyone can compute a plain SHA-256
-hash of a message -- but only someone who holds the secret key can compute the
-correct HMAC tag. This means the recipient can verify that the message was sent by
-someone who knows the key, and that it was not modified in transit.
+hash of a message. But only someone who holds the secret key can compute the correct HMAC tag. The recipient can then verify that the message was sent by
+someone who knows the key and that it was not modified in transit.
 
 leviathan-crypto provides three HMAC variants corresponding to each hash:
 
-- **HMAC_SHA256** -- 32-byte tag, using SHA-256
-- **HMAC_SHA512** -- 64-byte tag, using SHA-512
-- **HMAC_SHA384** -- 48-byte tag, using SHA-384
+**HMAC_SHA256.** 32-byte tag.
+
+**HMAC_SHA512.** 64-byte tag.
+
+**HMAC_SHA384.** 48-byte tag.
 
 All computation runs in WebAssembly. The TypeScript classes handle input
-validation and the JS/WASM boundary -- they never implement cryptographic
-algorithms directly.
+validation and the JS/WASM boundary. They never implement cryptographic algorithms directly.
 
 ---
 
@@ -70,7 +77,7 @@ encryption with leviathan primitives.
 Never construct a MAC by concatenating a secret and a message and hashing them:
 
 ```typescript
-// DANGEROUS -- DO NOT DO THIS
+// DANGEROUS: DO NOT DO THIS
 const bad = sha256.hash(concat(secret, message))
 ```
 
@@ -94,8 +101,7 @@ HMAC keys should be **at least as long as the hash output**:
 Keys shorter than this are technically valid (they will be zero-padded
 internally) but provide less security than the hash function offers. Keys
 longer than the hash block size (64 bytes for SHA-256, 128 bytes for
-SHA-384/SHA-512) are pre-hashed automatically per RFC 2104 section 3 -- this is
-handled for you, but there is no benefit to using very long keys.
+SHA-384/SHA-512) are pre-hashed automatically per RFC 2104 section 3. There is no benefit to using very long keys.
 
 ### Always use constant-time comparison for HMAC verification
 
@@ -121,24 +127,25 @@ with a hash or HMAC instance.
 Each module subpath exports its own init function for consumers who want
 tree-shakeable imports.
 
-### `sha2Init(mode?, opts?)`
+### `sha2Init(source)`
 
 Initializes only the sha2 WASM binary. Equivalent to calling the
-root `init(['sha2'], mode, opts)` but without pulling the other three
+root `init({ sha2: source })` but without pulling the other three
 modules into the bundle.
 
 **Signature:**
 
 ```typescript
-async function sha2Init(mode?: Mode, opts?: InitOpts): Promise<void>
+async function sha2Init(source: WasmSource): Promise<void>
 ```
 
 **Usage:**
 
 ```typescript
 import { sha2Init, SHA256 } from 'leviathan-crypto/sha2'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await sha2Init()
+await sha2Init(sha2Wasm)
 const sha = new SHA256()
 ```
 
@@ -146,7 +153,7 @@ const sha = new SHA256()
 
 ## API Reference
 
-All classes require `init(['sha2'])` or the subpath `sha2Init()` to be called first.
+All classes require `init({ sha2: sha2Wasm })` or the subpath `sha2Init(sha2Wasm)` to be called first.
 Constructing any SHA-2 class before initialization throws an error.
 
 ### SHA256
@@ -161,16 +168,11 @@ class SHA256 {
 }
 ```
 
-**`constructor()`** -- Creates a new SHA256 instance. Throws if `init(['sha2'])`
-has not been called.
+**`constructor()`** Creates a new SHA256 instance. Throws if `init({ sha2: sha2Wasm })` has not been called.
 
-**`hash(msg: Uint8Array): Uint8Array`** -- Hashes the entire message and returns
-a 32-byte `Uint8Array` digest. The message can be any length (including empty).
-Large messages are internally chunked and streamed through the WASM hash function,
-so memory usage stays constant regardless of input size.
+**`hash(msg: Uint8Array): Uint8Array`** Hashes the entire message and returns a 32-byte `Uint8Array` digest. The message can be any length including empty. Large messages are internally chunked and streamed through the WASM hash function, so memory usage stays constant regardless of input size.
 
-**`dispose(): void`** -- Wipes all internal WASM buffers (hash state, input
-buffer, output buffer). Call this when you are done with the instance.
+**`dispose(): void`** Wipes all internal WASM buffers (hash state, input buffer, output buffer). Call this when you are done with the instance.
 
 ---
 
@@ -186,11 +188,11 @@ class SHA512 {
 }
 ```
 
-**`constructor()`** -- Creates a new SHA512 instance. Throws if not initialized.
+**`constructor()`** Creates a new SHA512 instance. Throws if not initialized.
 
-**`hash(msg: Uint8Array): Uint8Array`** -- Returns a 64-byte digest.
+**`hash(msg: Uint8Array): Uint8Array`** Returns a 64-byte digest.
 
-**`dispose(): void`** -- Wipes all internal WASM buffers.
+**`dispose(): void`** Wipes all internal WASM buffers.
 
 ---
 
@@ -207,11 +209,11 @@ class SHA384 {
 }
 ```
 
-**`constructor()`** -- Creates a new SHA384 instance. Throws if not initialized.
+**`constructor()`** Creates a new SHA384 instance. Throws if not initialized.
 
-**`hash(msg: Uint8Array): Uint8Array`** -- Returns a 48-byte digest.
+**`hash(msg: Uint8Array): Uint8Array`** Returns a 48-byte digest.
 
-**`dispose(): void`** -- Wipes all internal WASM buffers.
+**`dispose(): void`** Wipes all internal WASM buffers.
 
 ---
 
@@ -227,15 +229,11 @@ class HMAC_SHA256 {
 }
 ```
 
-**`constructor()`** -- Creates a new HMAC_SHA256 instance. Throws if not
-initialized.
+**`constructor()`** Creates a new HMAC_SHA256 instance. Throws if not initialized.
 
-**`hash(key: Uint8Array, msg: Uint8Array): Uint8Array`** -- Computes the
-HMAC-SHA256 tag for the given message using the given key. Returns a 32-byte
-`Uint8Array`. Keys longer than 64 bytes are automatically pre-hashed with
-SHA-256 per RFC 2104 section 3.
+**`hash(key: Uint8Array, msg: Uint8Array): Uint8Array`** Computes the HMAC-SHA256 tag for the given message using the given key. Returns a 32-byte `Uint8Array`. Keys longer than 64 bytes are automatically pre-hashed with SHA-256 per RFC 2104 section 3.
 
-**`dispose(): void`** -- Wipes all internal WASM buffers, including key material.
+**`dispose(): void`** Wipes all internal WASM buffers, including key material.
 
 ---
 
@@ -251,13 +249,11 @@ class HMAC_SHA512 {
 }
 ```
 
-**`constructor()`** -- Creates a new HMAC_SHA512 instance. Throws if not
-initialized.
+**`constructor()`** Creates a new HMAC_SHA512 instance. Throws if not initialized.
 
-**`hash(key: Uint8Array, msg: Uint8Array): Uint8Array`** -- Returns a 64-byte
-HMAC tag. Keys longer than 128 bytes are pre-hashed with SHA-512.
+**`hash(key: Uint8Array, msg: Uint8Array): Uint8Array`** Returns a 64-byte HMAC tag. Keys longer than 128 bytes are pre-hashed with SHA-512.
 
-**`dispose(): void`** -- Wipes all internal WASM buffers.
+**`dispose(): void`** Wipes all internal WASM buffers.
 
 ---
 
@@ -273,13 +269,11 @@ class HMAC_SHA384 {
 }
 ```
 
-**`constructor()`** -- Creates a new HMAC_SHA384 instance. Throws if not
-initialized.
+**`constructor()`** Creates a new HMAC_SHA384 instance. Throws if not initialized.
 
-**`hash(key: Uint8Array, msg: Uint8Array): Uint8Array`** -- Returns a 48-byte
-HMAC tag. Keys longer than 128 bytes are pre-hashed with SHA-384.
+**`hash(key: Uint8Array, msg: Uint8Array): Uint8Array`** Returns a 48-byte HMAC tag. Keys longer than 128 bytes are pre-hashed with SHA-384.
 
-**`dispose(): void`** -- Wipes all internal WASM buffers.
+**`dispose(): void`** Wipes all internal WASM buffers.
 
 ---
 
@@ -302,26 +296,15 @@ class HKDF_SHA256 {
 }
 ```
 
-**`constructor()`** -- Creates a new HKDF_SHA256 instance. Throws if
-`init(['sha2'])` has not been called.
+**`constructor()`** Creates a new HKDF_SHA256 instance. Throws if `init({ sha2: sha2Wasm })` has not been called.
 
-**`extract(salt, ikm): Uint8Array`** -- RFC 5869 section 2.2. Computes
-`PRK = HMAC-SHA256(salt, IKM)`. Returns a 32-byte pseudorandom key. If `salt`
-is `null` or empty, defaults to 32 zero bytes per RFC section 2.2.
+**`extract(salt, ikm): Uint8Array`** RFC 5869 section 2.2. Computes `PRK = HMAC-SHA256(salt, IKM)`. Returns a 32-byte pseudorandom key. If `salt` is `null` or empty, defaults to 32 zero bytes per RFC section 2.2.
 
-**`expand(prk, info, length): Uint8Array`** -- RFC 5869 section 2.3. Derives
-`length` bytes of output keying material from a 32-byte PRK. `info` provides
-application-specific context (can be empty). `length` must be between 1 and
-8160 (255 x 32). Throws `RangeError` if `prk` is not exactly 32 bytes or if
-`length` is out of range.
+**`expand(prk, info, length): Uint8Array`** RFC 5869 section 2.3. Derives `length` bytes of output keying material from a 32-byte PRK. `info` provides application-specific context (can be empty). `length` must be between 1 and 8160 (255 x 32). Throws `RangeError` if `prk` is not exactly 32 bytes or if `length` is out of range.
 
-**`derive(ikm, salt, info, length): Uint8Array`** -- One-shot: calls
-`extract(salt, ikm)` then `expand(prk, info, length)`. This is the correct
-path for most callers. `extract()` and `expand()` are exposed separately for
-advanced use cases such as key separation and ratchets -- callers who reach for
-them should know why.
+**`derive(ikm, salt, info, length): Uint8Array`** One-shot: calls `extract(salt, ikm)` then `expand(prk, info, length)`. This is the correct path for most callers. `extract()` and `expand()` are exposed separately for advanced use cases such as key separation and ratchets. Callers who reach for them should know why.
 
-**`dispose(): void`** -- Releases the internal HMAC instance.
+**`dispose(): void`** Releases the internal HMAC instance.
 
 ---
 
@@ -340,11 +323,9 @@ class HKDF_SHA512 {
 }
 ```
 
-**`extract(salt, ikm)`** -- If `salt` is `null` or empty, defaults to 64 zero
-bytes.
+**`extract(salt, ikm)`** If `salt` is `null` or empty, defaults to 64 zero bytes.
 
-**`expand(prk, info, length)`** -- PRK must be exactly 64 bytes. `length` must
-be between 1 and 16320. Throws `RangeError` otherwise.
+**`expand(prk, info, length)`** PRK must be exactly 64 bytes. `length` must be between 1 and 16320. Throws `RangeError` otherwise.
 
 > [!NOTE]
 > HKDF is a pure TypeScript composition over the WASM-backed HMAC classes.
@@ -355,8 +336,9 @@ be between 1 and 16320. Throws `RangeError` otherwise.
 
 ```typescript
 import { init, HKDF_SHA256, bytesToHex } from 'leviathan-crypto'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await init(['sha2'])
+await init({ sha2: sha2Wasm })
 
 const hkdf = new HKDF_SHA256()
 const ikm = new Uint8Array(32) // your input keying material
@@ -375,13 +357,14 @@ hkdf.dispose()
 
 ### Example 1: Hash a message with SHA-256
 
-The most common operation: hash a string and get a hex-encoded digest.
+Hash a string and get a hex-encoded digest.
 
 ```typescript
 import { init, SHA256, bytesToHex, utf8ToBytes } from 'leviathan-crypto'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
 // Step 1: Initialize the SHA-2 WASM module (do this once at app startup)
-await init(['sha2'])
+await init({ sha2: sha2Wasm })
 
 // Step 2: Create a SHA256 instance
 const sha = new SHA256()
@@ -395,7 +378,7 @@ const digest = sha.hash(message)
 console.log(bytesToHex(digest))
 // => "315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3"
 
-// Step 5: Clean up -- wipes hash state from WASM memory
+// Step 5: Clean up, wipes hash state from WASM memory
 sha.dispose()
 ```
 
@@ -407,8 +390,9 @@ response.
 
 ```typescript
 import { init, SHA256, bytesToHex } from 'leviathan-crypto'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await init(['sha2'])
+await init({ sha2: sha2Wasm })
 
 // Suppose you have file contents as an ArrayBuffer (from FileReader, fetch, etc.)
 const response = await fetch('https://example.com/file.bin')
@@ -421,8 +405,7 @@ console.log('SHA-256:', bytesToHex(digest))
 sha.dispose()
 ```
 
-The library handles large inputs automatically -- it streams the data through
-the WASM hash function in chunks, so you do not need to worry about memory.
+The library handles large inputs automatically. It streams the data through the WASM hash function in chunks, so you do not need to worry about memory.
 
 ### Example 3: Using SHA-512 or SHA-384
 
@@ -430,8 +413,9 @@ The API is identical for all three hash variants. Only the output size differs.
 
 ```typescript
 import { init, SHA256, SHA384, SHA512, bytesToHex, utf8ToBytes } from 'leviathan-crypto'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await init(['sha2'])
+await init({ sha2: sha2Wasm })
 
 const msg = utf8ToBytes('Same message, different hashes')
 
@@ -451,16 +435,17 @@ sha512.dispose()
 ### Example 4: Generate and verify an HMAC
 
 Use HMAC when you need to prove that a message was created by someone who holds
-a secret key. A typical pattern: one side generates a tag, the other side
-recomputes the tag with the same key and checks that they match.
+a secret key. One side generates a tag, the other side recomputes the tag with
+the same key and checks that they match.
 
 ```typescript
 import {
 	init, HMAC_SHA256, constantTimeEqual, randomBytes,
 	bytesToHex, utf8ToBytes
 } from 'leviathan-crypto'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await init(['sha2'])
+await init({ sha2: sha2Wasm })
 
 // Generate a random 32-byte key (do this once, store it securely)
 const key = randomBytes(32)
@@ -480,7 +465,7 @@ const recomputed = hmac.hash(key, message)
 
 // Use constant-time comparison to check the tags
 if (constantTimeEqual(tag, recomputed)) {
-	console.log('Message is authentic -- it was not tampered with')
+	console.log('Message is authentic. It was not tampered with.')
 } else {
 	console.log('WARNING: message has been modified or key is wrong')
 }
@@ -488,31 +473,32 @@ if (constantTimeEqual(tag, recomputed)) {
 hmac.dispose()
 ```
 
-### Example 5: HMAC verification -- the wrong way vs. the right way
+### Example 5: HMAC verification — the right way
 
-This is important enough to call out separately. The difference between these
-two approaches is the difference between a secure system and a broken one.
+The difference between these two approaches is the difference between a secure
+system and a broken one.
 
 ```typescript
 import { init, HMAC_SHA256, constantTimeEqual, bytesToHex } from 'leviathan-crypto'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await init(['sha2'])
+await init({ sha2: sha2Wasm })
 const hmac = new HMAC_SHA256()
 
 // Suppose you received a message with a tag and you recomputed the expected tag:
 const receivedTag = hmac.hash(key, message)
 const expectedTag = hmac.hash(key, message)
 
-// WRONG -- timing attack vulnerable!
+// WRONG: timing attack vulnerable
 // JavaScript's === operator compares byte-by-byte and returns false as soon as
 // it finds a mismatch. An attacker can measure the response time to figure out
 // how many leading bytes of the tag are correct, then forge a valid tag one
 // byte at a time.
 if (bytesToHex(receivedTag) === bytesToHex(expectedTag)) {
-	// This "works" but is insecure
+	// This works but is insecure
 }
 
-// RIGHT -- constant-time comparison
+// RIGHT: constant-time comparison
 // constantTimeEqual always examines every byte, regardless of where the first
 // difference is. The comparison takes the same amount of time whether zero
 // bytes match or all bytes match.
@@ -529,8 +515,9 @@ The pattern is identical to HMAC-SHA256. Use a 64-byte key for full security.
 
 ```typescript
 import { init, HMAC_SHA512, constantTimeEqual, randomBytes, utf8ToBytes } from 'leviathan-crypto'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await init(['sha2'])
+await init({ sha2: sha2Wasm })
 
 // 64-byte key for HMAC-SHA512
 const key = randomBytes(64)
@@ -552,8 +539,9 @@ SHA-2 is well-defined for empty inputs. This can be useful as a sanity check.
 
 ```typescript
 import { init, SHA256, bytesToHex } from 'leviathan-crypto'
+import { sha2Wasm } from 'leviathan-crypto/sha2/embedded'
 
-await init(['sha2'])
+await init({ sha2: sha2Wasm })
 
 const sha = new SHA256()
 const digest = sha.hash(new Uint8Array(0))
@@ -570,14 +558,14 @@ sha.dispose()
 
 ### Module not initialized
 
-If you construct any SHA-2 class before calling `init(['sha2'])`, the
+If you construct any SHA-2 class before calling `init({ sha2: sha2Wasm })`, the
 constructor throws immediately:
 
 ```
-Error: leviathan-crypto: call init(['sha2']) before using this class
+Error: leviathan-crypto: call init({ sha2: ... }) before using this class
 ```
 
-**Fix:** Call `await init(['sha2'])` at application startup, before creating any
+**Fix:** Call `await init({ sha2: sha2Wasm })` at application startup, before creating any
 SHA-2 instances.
 
 ```typescript
@@ -585,7 +573,7 @@ SHA-2 instances.
 const sha = new SHA256() // Error!
 
 // Do this instead:
-await init(['sha2'])
+await init({ sha2: sha2Wasm })
 const sha = new SHA256() // OK
 ```
 
@@ -616,7 +604,7 @@ SHA-2 is well-defined for zero-length messages and will return the correct diges
 > - [architecture](./architecture.md) — architecture overview, module relationships, buffer layouts, and build pipeline
 > - [asm_sha2](./asm_sha2.md) — WASM implementation details (AssemblyScript buffer layout, compression functions)
 > - [sha3](./sha3.md) — alternative: SHA-3 family (immune to length extension attacks)
-> - [serpent](./serpent.md) — SerpentSeal and SerpentStream use HMAC-SHA256 and HKDF internally
+> - [serpent](./serpent.md) — `SerpentCipher` uses HMAC-SHA256 and HKDF internally via `Seal` and `SealStream`
 > - [argon2id](./argon2id.md) — Argon2id password hashing; HKDF expands Argon2id root keys
 > - [fortuna](./fortuna.md) — Fortuna CSPRNG uses SHA-256 for entropy accumulation
 > - [utils](./utils.md) — `constantTimeEqual`, `bytesToHex`, `utf8ToBytes`, `randomBytes`