leviathan-crypto 1.0.0

package/dist/docs/utils.md

@@ -0,0 +1,273 @@
+# Encoding utilities, comparison functions, and random byte generation
+
+## Overview
+
+Pure TypeScript utilities that ship alongside the WASM-backed primitives. These functions have **no `init()` dependency** -- they work immediately on import, without loading any WASM module.
+
+The module covers four areas:
+
+- **Encoding** -- hex, UTF-8, and base64 conversions between strings and `Uint8Array`
+- **Security** -- constant-time comparison and secure memory wiping
+- **Byte manipulation** -- XOR and concatenation of byte arrays
+- **Random** -- cryptographically secure random byte generation
+
+---
+
+## Security Notes
+
+**`constantTimeEqual`** uses an XOR-accumulate pattern with no early return on byte mismatch. Use this function whenever you compare MACs, hashes, authentication tags, or any secret-derived values. **Never** use `===`, `Buffer.equals`, or manual loop-with-break for security comparisons -- those leak timing information that can be exploited to recover secrets.
+
+The length check in `constantTimeEqual` is _not_ constant-time, because array length is non-secret in all standard protocols. If your use case treats length as secret, you must pad to equal length before comparing.
+
+**`wipe`** zeroes a typed array in-place. Call it on keys, plaintext buffers, and any other sensitive data as soon as you are done with them. JavaScript's garbage collector does not guarantee timely or complete erasure of memory.
+
+**`randomBytes`** delegates to `crypto.getRandomValues` (Web Crypto API), which is cryptographically secure in all modern browsers and Node.js 19+. It does not fall back to `Math.random` or any insecure source.
+
+The encoding functions (`hexToBytes`, `bytesToHex`, `utf8ToBytes`, `bytesToUtf8`, `base64ToBytes`, `bytesToBase64`) perform no security-sensitive operations.
+
+---
+
+## API Reference
+
+### hexToBytes
+
+```typescript
+hexToBytes(hex: string): Uint8Array
+```
+
+Converts a hex string to a `Uint8Array`. Accepts lowercase or uppercase characters. An optional `0x` or `0X` prefix is stripped automatically. If the hex string has an odd number of characters, a trailing `0` is appended before decoding.
+
+---
+
+### bytesToHex
+
+```typescript
+bytesToHex(bytes: Uint8Array): string
+```
+
+Converts a `Uint8Array` to a lowercase hex string (no prefix).
+
+---
+
+### utf8ToBytes
+
+```typescript
+utf8ToBytes(str: string): Uint8Array
+```
+
+Encodes a JavaScript string as UTF-8 bytes using the platform `TextEncoder`.
+
+---
+
+### bytesToUtf8
+
+```typescript
+bytesToUtf8(bytes: Uint8Array): string
+```
+
+Decodes UTF-8 bytes to a JavaScript string using the platform `TextDecoder`.
+
+---
+
+### base64ToBytes
+
+```typescript
+base64ToBytes(b64: string): Uint8Array | undefined
+```
+
+Decodes a base64 or base64url string to a `Uint8Array`. Base64url characters (`-`, `_`, `%3d`) are normalized to standard base64 before decoding. Returns `undefined` if the input is not valid base64 (e.g., incorrect length or illegal characters).
+
+> [!NOTE]
+> Valid base64 characters are `A-Z`, `a-z`, `0-9`, `+`, `/`, and `=`.
+> Any other character causes the function to return `undefined`.
+
+---
+
+### bytesToBase64
+
+```typescript
+bytesToBase64(bytes: Uint8Array, url?: boolean): string
+```
+
+Encodes a `Uint8Array` to a base64 string. Pass `url = true` to get base64url encoding (uses `-` and `_` instead of `+` and `/`, and `%3d` instead of `=`). Defaults to standard base64.
+
+---
+
+### constantTimeEqual
+
+```typescript
+constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean
+```
+
+Returns `true` if `a` and `b` contain identical bytes. Uses XOR-accumulate with no early return on mismatch. Returns `false` immediately if the arrays differ in length (length is non-secret).
+
+---
+
+### wipe
+
+```typescript
+wipe(data: Uint8Array | Uint16Array | Uint32Array): void
+```
+
+Zeroes a typed array in-place by calling `fill(0)`. Use this to clear keys, plaintext, or any sensitive material when you are done with it.
+
+---
+
+### xor
+
+```typescript
+xor(a: Uint8Array, b: Uint8Array): Uint8Array
+```
+
+Returns a new `Uint8Array` where each byte is `a[i] ^ b[i]`. Both arrays must have the same length; throws `RangeError` if they differ.
+
+---
+
+### concat
+
+```typescript
+concat(a: Uint8Array, b: Uint8Array): Uint8Array
+```
+
+Returns a new `Uint8Array` containing `a` followed by `b`.
+
+---
+
+### randomBytes
+
+```typescript
+randomBytes(n: number): Uint8Array
+```
+
+Returns `n` cryptographically secure random bytes via the Web Crypto API (`crypto.getRandomValues`).
+
+---
+
+## Usage Examples
+
+### Converting between formats
+
+```typescript
+import { hexToBytes, bytesToHex, utf8ToBytes, bytesToUtf8 } from 'leviathan-crypto'
+
+// Hex round-trip
+const bytes = hexToBytes('deadbeef')
+console.log(bytesToHex(bytes)) // "deadbeef"
+
+// 0x prefix is accepted
+const prefixed = hexToBytes('0xCAFE')
+console.log(bytesToHex(prefixed)) // "cafe"
+
+// UTF-8 round-trip
+const encoded = utf8ToBytes('hello world')
+console.log(bytesToUtf8(encoded)) // "hello world"
+```
+
+---
+
+### Base64 encoding and decoding
+
+```typescript
+import { bytesToBase64, base64ToBytes, utf8ToBytes, bytesToUtf8 } from 'leviathan-crypto'
+
+const data = utf8ToBytes('leviathan-crypto')
+const b64 = bytesToBase64(data)
+console.log(b64) // "bGV2aWF0aGFuLWNyeXB0bw=="
+
+// base64url variant (safe for URLs and filenames)
+const b64url = bytesToBase64(data, true)
+console.log(b64url) // "bGV2aWF0aGFuLWNyeXB0bw%3d%3d"
+
+// Decoding (accepts both standard and url variants)
+const decoded = base64ToBytes(b64)
+if (decoded) console.log(bytesToUtf8(decoded)) // "leviathan-crypto"
+```
+
+---
+
+### Secure MAC comparison
+
+```typescript
+import { constantTimeEqual } from 'leviathan-crypto'
+
+// After computing a MAC over received data, compare it to the expected tag.
+// NEVER use === or .every() for this -- timing leaks enable forgery attacks.
+const computedMac: Uint8Array = hmac.hash(key, message)
+const receivedMac: Uint8Array = getTagFromNetwork()
+
+if (!constantTimeEqual(computedMac, receivedMac)) {
+  throw new Error('Authentication failed: MAC mismatch')
+}
+```
+
+---
+
+### Generating random keys and nonces
+
+```typescript
+import { randomBytes } from 'leviathan-crypto'
+
+const key = randomBytes(32)   // 256-bit symmetric key
+const nonce = randomBytes(24) // 192-bit nonce for XChaCha20
+const iv = randomBytes(16)    // 128-bit IV for Serpent-CBC
+```
+
+---
+
+### Wiping sensitive data after use
+
+```typescript
+import { randomBytes, wipe } from 'leviathan-crypto'
+
+const key = randomBytes(32)
+
+// ... use the key for encryption / decryption ...
+
+// When done, zero the key material so it does not linger in memory
+wipe(key)
+// key is now all zeroes
+```
+
+---
+
+### XOR and concatenation
+
+```typescript
+import { xor, concat, randomBytes } from 'leviathan-crypto'
+
+const a = randomBytes(16)
+const b = randomBytes(16)
+
+// XOR two equal-length arrays
+const xored = xor(a, b)
+
+// Concatenate two arrays
+const combined = concat(a, b)
+console.log(combined.length) // 32
+```
+
+---
+
+## Error Conditions
+
+| Function | Condition | Behavior |
+|---|---|---|
+| `hexToBytes` | Odd-length string | Trailing `0` appended (no error) |
+| `hexToBytes` | Invalid hex characters | Bytes decode as `NaN` -> `0` |
+| `base64ToBytes` | Invalid length or characters | Returns `undefined` |
+| `constantTimeEqual` | Arrays differ in length | Returns `false` immediately |
+| `xor` | Arrays differ in length | Throws `RangeError` |
+| `randomBytes` | `crypto` not available | Throws (runtime-dependent) |
+
+---
+
+## Cross-References
+
+- [README.md](./README.md) — library documentation index and exports table
+- [architecture.md](./architecture.md) — module structure and security rationale
+- [serpent.md](./serpent.md) — Serpent modes consume keys from `randomBytes`; wrappers use `wipe` and `constantTimeEqual`
+- [chacha20.md](./chacha20.md) — ChaCha20/Poly1305 classes use `randomBytes` for nonce generation
+- [sha2.md](./sha2.md) — SHA-2 and HMAC classes; output often converted with `bytesToHex`
+- [sha3.md](./sha3.md) — SHA-3 and SHAKE classes; output often converted with `bytesToHex`
+- [types.md](./types.md) — public interfaces whose implementations rely on these utilities
+- [test-suite.md](./test-suite.md) — test suite structure and vector corpus

package/dist/docs/wasm.md

@@ -0,0 +1,193 @@
+# WebAssembly Primer
+
+> [!NOTE]
+> - A short introduction to WebAssembly concepts as they apply to the leviathan-crypto library.
+> - If you already understand WASM, skip to [Project-Specific Concepts](#project-specific-concepts).
+> - WebAssembly specification and documentation: [webassembly.org](https://webassembly.org/)
+
+## What is WebAssembly?
+
+WebAssembly (WASM) is a binary instruction format that runs in browsers and
+server-side runtimes alongside JavaScript. Rather than a programming language
+one writes by hand, it serves as a compilation target. Code is written in a higher-level
+language, compiled to `.wasm`, and then executed by the browser.
+
+Consider it a small, fast virtual machine built into every modern browser.
+JavaScript can load a `.wasm` binary, call its exported functions, and read
+its results. The WASM code runs in its own sandboxed memory space, and thus cannot
+touch the DOM, access JavaScript variables, or reach the network. It computes
+and returns values, and that is its sole function.
+
+---
+
+## How It Runs
+
+When a browser encounters a `.wasm` binary, it performs two steps:
+
+1. Compilation: The binary is validated and compiled into native machine code.
+   This is fast because WASM is already a low-level format, requiring less
+   work for the compiler compared to parsing and optimizing JavaScript.
+
+2. Instantiation: The compiled module is paired with its imports, such as a
+   memory object, to create a live instance. The instance's exported functions
+   are then callable from JavaScript.
+
+Once instantiated, calling a WASM function is similar to calling any JavaScript
+function: you pass arguments, it runs, and it returns a result. The key difference
+lies in how it runs. WASM execution is deterministic and not subject to the
+JIT compiler's speculative optimizations. Unlike JavaScript, the browser does not rewrite, inline,
+or de-optimize WASM code paths based on runtime profiling.
+
+---
+
+## Why We Use It
+
+Leviathan performs all cryptographic computations in WASM because JavaScript
+engines offer no formal constant-time guarantees for arbitrary code. The JIT
+compiler can introduce timing variations that leak information about secret
+data; WASM execution avoids this class of problem.
+
+For architectural details and security rationale, see [architecture.md](./architecture.md).
+
+**TLDR:** _TypeScript handles the API, and WASM handles the math._
+
+---
+
+## Core Concepts
+
+### Module
+
+A `WebAssembly.Module` is a compiled `.wasm` binary and a stateless
+template for creating instances. You can compile a module once and create
+multiple instances from it. For example, [XChaCha20Poly1305Pool](./chacha20_pool.md)
+uses one compiled module to create many worker instances.
+
+---
+
+### Instance
+
+A WebAssembly.Instance is a live, runnable copy of a module, complete with
+its own memory and state. When you call `init('serpent')`, the library
+compiles the Serpent WASM binary and creates a single instance. All
+Serpent classes (`Serpent`, `SerpentCtr`, `SerpentCbc`) share this instance.
+
+---
+
+### Memory
+
+A `WebAssembly.Memory` is a contiguous block of bytes, essentially a
+ `Uint8Array` that WASM functions can read and write, also known as **linear
+memory**. Each of our WASM modules gets its own memory (3 pages = 192 KB).
+
+The TypeScript layer communicates with WASM by writing inputs to specific offsets
+in this memory, calling a WASM function, and then reading the outputs from other
+offsets. There is no other communication channel, no function arguments for
+large data, and no return values beyond a single number. Memory is the data bus.
+
+---
+
+### Exports
+
+A WASM instance exposes exports: functions and memory that JavaScript can
+access. In leviathan-crypto, every WASM module exports:
+
+- **Getter functions** like getKeyOffset() and getChunkPtOffset(): these
+  return the memory offsets where the TypeScript layer should write inputs
+  or read outputs.
+- **Operation functions** like chachaEncryptChunk() and sha256Final():
+  these perform the actual cryptographic computation on data already in memory.
+- **wipeBuffers():** this zeros all sensitive regions of memory and is called
+  by every class's dispose() method.
+- **memory:** the linear memory object itself, which allows the TypeScript
+  layer to create Uint8Array views over it.
+
+---
+
+### Imports
+
+When instantiating a module, you can pass **imports:** objects the WASM code
+needs from the host. Our modules import only one thing: the Memory object.
+We create the memory on the JavaScript side and pass it in, giving us
+control over its size and lifecycle.
+
+---
+
+## Project-Specific Concepts
+
+### AssemblyScript
+
+The WASM binaries in this project are written in [AssemblyScript](https://www.assemblyscript.org/):
+a TypeScript-like language that compiles to WebAssembly. It resembles
+TypeScript but targets WASM instead of JavaScript. The source code
+resides in `src/asm/` and compiles into `.wasm` binaries in `build/`.
+
+AssemblyScript was selected because its syntax is familiar to TypeScript
+developers. It produces small binaries and grants low-level control over
+memory layout without requiring C, C++, or Rust.
+
+---
+
+### Thunks
+
+In this project, a **thunk** is a base64-encoded WASM binary embedded directly
+within a TypeScript file. The files in `src/ts/embedded/`
+(such as chacha.ts and serpent.ts) each export a single constant:
+
+```typescript
+export const WASM_BASE64 = 'AGFzbQEAAAAB...'
+```
+
+This represents the entire compiled .wasm binary, encoded as a base64 string. When
+you call init('chacha20') in embedded mode (the default), the library
+imports this string, decodes it back into bytes, and compiles it into a
+`WebAssembly.Module`.
+
+Why embed the binary as a string? This approach enables the library to function with zero
+configuration. There's no need to serve .wasm files from a CDN, configure MIME
+types, or establish a build plugin to manage binary imports. Simply npm install and
+import. The tradeoff is bundle size, as base64 encoding increases the size by
+approximately 33% compared to the raw binary. For production deployments where bundle size is
+critical, the library also supports [streaming and manual loading modes](./loader.md).
+
+**TLDR:** Thunks are build artifacts generated by `scripts/embed-wasm.ts`.
+They are gitignored and regenerated during each build. Avoid manual edits.
+
+---
+
+### Buffer Layout
+
+Each WASM module divides its linear memory into fixed regions at known offsets.
+For example, the ChaCha20 module has a region for the key, a region for the
+nonce, a region for plaintext input, a region for ciphertext output, and so on.
+These offsets are defined in `src/asm/*/buffers.ts` and never change at runtime.
+The TypeScript layer calls getter functions (like `getKeyOffset()`) to
+determine where each region starts, then reads and writes `Uint8Array` slices at those
+positions. This is the only way data moves between TypeScript and
+WASM. There is no serialization, no copying to intermediate buffers, and no function call
+overhead for large data. Data is transferred via direct byte writes to shared memory.
+
+The buffer layouts for each module are documented in [architecture.md](./architecture.md).
+
+---
+
+### The `init()` Gate
+
+WASM modules must be compiled and instantiated before use. Because compilation
+returns a Promise, this is an asynchronous operation. Rather than hiding this
+behind lazy auto-initialization, which would make every cryptographic call
+implicitly asynchronous and create race conditions, the library requires an explicit
+`init()` call up front. If you forget, every class immediately throws an error message
+indicating which `init(init()` call is missing. _This is deliberate._
+
+See [init.md](./init.md) for the full API.
+
+---
+
+## Cross-References
+
+- [architecture.md](./architecture.md) — module structure, buffer layouts,
+  security rationale
+- [init.md](./init.md) — `init()` API and the three loading modes
+- [loader.md](./loader.md) — how WASM binaries are loaded and instantiated
+- [chacha20_pool.md](./chacha20_pool.md) — example of one compiled module
+  spawning many instances across workers