leviathan-crypto 1.1.0 → 1.3.0

package/SECURITY.md

@@ -1,18 +1,30 @@
 # Leviathan Crypto Library Security Policy
 
+<img src="https://github.com/xero/leviathan-crypto/raw/main/docs/logo.svg" alt="Leviathan logo" width="100" align="left">
+
+- **[Version Support](#supported-versions)**
+- **[Security Posture](#security-posture)**
+- **[Cryptanalytic Audits](#cryptanalytic-reviews)**
+- **[Vulnerability Reporting](#reporting-a-vulnerability)**
+
+---
+
 ## Supported Versions
 
 | Version | Supported |
 |---------|-----------|
-| v1.x    | ✓         |
+| v1.3.x  | ︎✓         |
+| v1.2.x  | ✓         |
+| v1.1.x  | ✗         |
+| v1.0.x  | ✗         |
 
-> [!NOTE]
-> v1.0.0 is the current stable release.
-> This table will be updated as new versions ship.
+> [!WARNING]
+> v1.0.x does not zero intermediate key material in HMAC and HKDF operations.
+> Upgrading to v1.1.0 or later is strongly recommended.
 
 ## Security Posture
 
-leviathan-crypto is a cryptography library. Security is not an afterthought,
+[`leviathan-crypto`](https://leviathan.3xi.club) is a cryptography library. Security is not an afterthought,
 it is the primary design constraint at every layer of the stack.
 
 ### Algorithm Correctness
@@ -23,69 +35,84 @@ against the authoritative specification for that algorithm:
 [RFC 8439][rfc8439] (ChaCha20-Poly1305), [RFC 2104][rfc2104] (HMAC),
 [RFC 5869][rfc5869] (HKDF), and the original
 [Serpent-256 specification][serpent] and S-box reference. No algorithm was
-ported from an existing implementation — the specs are the source of truth.
+ported from an existing implementation. The specs are always the source of truth.
 
 All implementations are verified against published known-answer test vectors
 from NIST, RFC appendices, NESSIE, and the Argon2 reference suite. Vectors
 are immutable: if an implementation produces incorrect output, the
-implementation is fixed — vectors are never adjusted to match code.
+implementation is fixed and vectors are never adjusted to match code.
 
 ### Side-Channel Resistance
 
-Serpent's S-boxes are implemented as Boolean gate circuits — no table
-lookups, no data-dependent memory access, no data-dependent branches. Every
+Serpent's S-boxes are implemented as Boolean gate circuits designed with no table
+lookups, no data-dependent memory access, and no data-dependent branches. Every
 bit is processed unconditionally on every block. This is the most
 timing-safe cipher implementation approach available in a WASM runtime,
 where JIT optimisation can otherwise introduce observable timing variation.
 
-All security-sensitive comparisons (MAC verification, padding validation)
+All security-sensitive comparisons (e.g. MAC verification, padding validation)
 use XOR-accumulate patterns with no early return on mismatch.
 [`constantTimeEqual`][utils] is the mandated comparison function throughout
-the library and its demos.
+the library and its [demos][demos].
 
 ### WASM Execution Model
 
 All cryptographic computation runs in WebAssembly, isolated outside the
 JavaScript JIT. WASM execution is deterministic and not subject to JIT
 speculation or optimisation. Each primitive family compiles to its own
-isolated binary with its own linear memory — key material in the Serpent
-module cannot interact with memory in the SHA-3 module even in principle.
+isolated binary with its own linear memory. For example, key material in
+the Serpent module cannot interact with memory in the SHA-3 module,
+even in principle.
 
-### Cryptanalytic Review
+### Cryptanalytic Reviews
+
+All of our primitives undergo periodic cryptographic implementation reviews.
+
+| Primitive | Audit Description |
+|-----------|-------------------|
+| [serpent_audit][serpent_audit] | Correctness verification, side-channel analysis, cryptanalytic attack paper review |
+| [chacha_audit][chacha_audit] | XChaCha20-Poly1305 correctness, Poly1305 field arithmetic, HChaCha20 nonce extension |
+| [sha2_audit][sha2_audit] | SHA-256/512/384 correctness, HMAC and HKDF composition, constant verification |
+| [sha3_audit][sha3_audit] | Keccak permutation correctness, θ/ρ/π/χ/ι step verification, round constant derivation |
+| [hmac_audit][hmac_audit] | HMAC-SHA256/512/384 construction, key processing, RFC 4231 vector coverage |
+| [hkdf_audit][hkdf_audit] | HKDF extract-then-expand, info field domain separation, SerpentStream key derivation |
+
+#### Additional Serpent-256 research
 
 The security margin of Serpent-256 has been independently researched and
-documented. The best known attack on the full 32-round cipher — biclique
-cryptanalysis — achieves a complexity of 2²⁵⁵·¹⁹ with 2⁴ chosen
+documented. The best known attack on the full 32-round cipher, _"biclique
+cryptanalysis"_, achieves a complexity of 2²⁵⁵·¹⁹ with 2⁴ chosen
 ciphertexts. This provides less than one bit of advantage over exhaustive
 key search and has zero practical impact. Independent research conducted
 against this implementation improved on the published result by −0.20 bits
 through systematic parameter search, confirming no structural weakness
 beyond what the published literature describes.
 
-See: [`xero/BicliqueFinder/biclique_research.md`][biclique] and
-[`leviathan-crypto/wiki/serpent_audit`][serpent-audit] for the full
-analysis.
+See: [`xero/BicliqueFinder/biclique_research.md`][biclique]
 
 ### Authenticated Encryption by Default
 
 Raw unauthenticated cipher modes (`SerpentCbc`, `SerpentCtr`) are exposed
 for power users but are not the recommended entry point. The primary API
 surfaces — `SerpentSeal`, `SerpentStream`, `SerpentStreamSealer` — are
-authenticated by construction. `SerpentStreamSealer` satisfies the
-Cryptographic Doom Principle: MAC verification is the unconditional gate on
-the open path, decryption is unreachable until that gate clears, and
-per-chunk HKDF key derivation with position-bound info extends this
+authenticated by construction.
+
+**`SerpentStreamSealer` satisfies the _Cryptographic Doom Principle_:**
+
+MAC verification is the unconditional gate on the open path,
+decryption is unreachable until that gate clears, and per-chunk
+HKDF key derivation with position-bound info extends this
 guarantee to full stream integrity.
 
 ### Dependency Management
 
-The library has _zero_ runtime JavaScript dependencies by design.
+The library has **zero** runtime dependencies by design.
 `sideEffects: false` is enforced in `package.json`. Argon2id integration
-is documented as an optional external dependency.
-See:" [`leviathan-crypto/wiki/argon2id`][argon2id-wiki].
+is documented as an _optional_ external dependency.
+See: [`leviathan-crypto/wiki/argon2id`][argon2id-wiki].
 
 Build toolchain dependencies are pinned with exact version locks in
-`bun.lock`. GitHub Actions workflows use SHA-pinned action references
+`bun.lock`. GitHub Actions workflows use [SHA-pinned action references][workflows]
 throughout with no floating tags. Supply chain integrity is treated as a
 first-class concern for a cryptography library.
 
@@ -124,10 +151,13 @@ as the single source of authority.
 Use GitHub's private vulnerability reporting form:
 [https://github.com/xero/leviathan-crypto/security/advisories/new][advisory]
 
-This opens a private channel between you and the maintainer. You will
-receive a response ASAP. If the vulnerability is confirmed, a fix will be
-prioritised and a coordinated disclosure timeline agreed upon before any
-public advisory is published.
+This opens a private channel between you and the maintainer, and you will
+receive a response promptly. If the vulnerability is confirmed,
+we will collaborate to fully understand the issue, including a review of
+proposed fixes, so you can track and validate firsthand. Before any public
+advisory is published, we will agree on a coordinated disclosure timeline.
+After disclosure, you are encouraged to publish your own write-up, blog post,
+or research notes, for full hacker scene credit.
 
 ### Direct Contact
 
@@ -141,34 +171,49 @@ If you prefer to contact the maintainer directly:
 
 ### Scope
 
-Reports are in scope for:
+**Reports are in scope for:**
 
-- Correctness bugs in cryptographic implementations (wrong output against
-  test vectors)
-- Side-channel vulnerabilities (timing, memory access patterns)
 - Authentication bypass in AEAD constructions
 - Key material exposure or improper zeroing
+- Incorrect entropy or CSPRNG weaknesses in Fortuna
+- Side-channel vulnerabilities (timing, memory access patterns)
+- Correctness bugs in cryptographic implementations (wrong output against
+  test vectors)
+- Platform-specific behavioral differences (WASM execution, binary output,
+  or timing characteristics that differ across operating systems or CPU
+  architectures)
 - Supply chain issues (dependency tampering, workflow compromise)
+- Improper scope of exported symbols
 
-Out of scope:
+**Out of scope:**
 
-- Unpatched vulnerabilities in third-party packages not maintained by this
-  project
+- Vulnerabilities in third-party packages not maintained by this project.
+  This includes optional peer dependencies such as argon2id.
+  Please report those directly to their maintainers.
 - Issues requiring physical access to the user's device
-
----
-
-[fips180]:       https://csrc.nist.gov/publications/detail/fips/180/4/final
-[fips202]:       https://csrc.nist.gov/publications/detail/fips/202/final
-[rfc8439]:       https://www.rfc-editor.org/rfc/rfc8439
-[rfc2104]:       https://www.rfc-editor.org/rfc/rfc2104
-[rfc5869]:       https://www.rfc-editor.org/rfc/rfc5869
-[serpent]:       https://www.cl.cam.ac.uk/~rja14/Papers/serpent.pdf
-[utils]:         https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal
-[biclique]:      https://github.com/xero/BicliqueFinder/blob/main/biclique-research.md
-[serpent-audit]: https://github.com/xero/leviathan-crypto/wiki/serpent_audit
-[argon2id-wiki]: https://github.com/xero/leviathan-crypto/wiki/argon2id
-[init]:          https://github.com/xero/leviathan-crypto/wiki/init
-[agents]:        https://github.com/xero/leviathan-crypto/blob/main/AGENTS.md
-[advisory]:      https://github.com/xero/leviathan-crypto/security/advisories/new
-[pgp]:           https://0w.nz/pgp.pub
+- Theoretical attacks with no practical exploit path (e.g. complexity
+  improvements that remain computationally infeasible)
+- Issues in the demo applications that do not affect the core library.
+  Please open an issue in the [`leviathan-demos`][demos] repository instead.
+
+[fips180]:        https://csrc.nist.gov/publications/detail/fips/180/4/final
+[fips202]:        https://csrc.nist.gov/publications/detail/fips/202/final
+[rfc8439]:        https://www.rfc-editor.org/rfc/rfc8439
+[rfc2104]:        https://www.rfc-editor.org/rfc/rfc2104
+[rfc5869]:        https://www.rfc-editor.org/rfc/rfc5869
+[serpent]:        https://www.cl.cam.ac.uk/~rja14/Papers/serpent.pdf
+[utils]:          https://github.com/xero/leviathan-crypto/wiki/utils#constanttimeequal
+[demos]:          https://github.com/xero/leviathan-demos/
+[serpent_audit]:  https://github.com/xero/leviathan-crypto/wiki/serpent_audit
+[chacha_audit]:   https://github.com/xero/leviathan-crypto/wiki/chacha_audit
+[sha2_audit]:     https://github.com/xero/leviathan-crypto/wiki/sha2_audit
+[sha3_audit]:     https://github.com/xero/leviathan-crypto/wiki/sha3_audit
+[hmac_audit]:     https://github.com/xero/leviathan-crypto/wiki/hmac_audit
+[hkdf_audit]:     https://github.com/xero/leviathan-crypto/wiki/hkdf_audit
+[biclique]:       https://github.com/xero/BicliqueFinder/blob/main/biclique-research.md
+[argon2id-wiki]:  https://github.com/xero/leviathan-crypto/wiki/argon2id
+[workflows]:      https://github.com/xero/leviathan-crypto/blob/main/scripts/pin-actions.ts
+[init]:           https://github.com/xero/leviathan-crypto/wiki/init
+[agents]:         https://github.com/xero/leviathan-crypto/blob/main/AGENTS.md
+[advisory]:       https://github.com/xero/leviathan-crypto/security/advisories/new
+[pgp]:            https://0w.nz/pgp.pub

package/dist/chacha20/index.js

@@ -25,6 +25,7 @@
 // Uses the init() module cache — call init('chacha20') before constructing.
 import { getInstance, initModule } from '../init.js';
 import { aeadEncrypt, aeadDecrypt, xcEncrypt, xcDecrypt } from './ops.js';
+import { hasSIMD } from '../utils.js';
 const _embedded = () => import('../embedded/chacha.js').then(m => m.WASM_BASE64);
 export async function chacha20Init(mode = 'embedded', opts) {
     return initModule('chacha20', _embedded, mode, opts);
@@ -57,7 +58,8 @@ export class ChaCha20 {
         const ptOff = this.x.getChunkPtOffset();
         const ctOff = this.x.getChunkCtOffset();
         mem.set(chunk, ptOff);
-        this.x.chachaEncryptChunk(chunk.length);
+        const fn = hasSIMD() ? this.x.chachaEncryptChunk_simd : this.x.chachaEncryptChunk;
+        fn(chunk.length);
         return mem.slice(ctOff, ctOff + chunk.length);
     }
     beginDecrypt(key, nonce) {

package/dist/chacha20/types.d.ts

@@ -21,6 +21,8 @@ export interface ChaChaExports {
     chachaResetCounter(): void;
     chachaEncryptChunk(n: number): number;
     chachaDecryptChunk(n: number): number;
+    chachaEncryptChunk_simd(n: number): number;
+    chachaDecryptChunk_simd(n: number): number;
     chachaGenPolyKey(): void;
     hchacha20(): void;
     polyInit(): void;

package/dist/docs/architecture.md

@@ -676,9 +676,11 @@ Source: `src/asm/chacha/buffers.ts`
 | 131492 | 16 | `POLY_S_BUFFER` — s pad: 4 × u32 |
 | 131508 | 24 | `XCHACHA_NONCE_BUFFER` — full 24-byte XChaCha20 nonce |
 | 131532 | 32 | `XCHACHA_SUBKEY_BUFFER` — HChaCha20 output (key material) |
-| 131564 | — | END |
+| 131564 | 4 | *(padding for 16-byte SIMD alignment)* |
+| 131568 | 256 | `CHACHA_SIMD_WORK_BUFFER` — 4-wide inter-block keystream (4 × 64 bytes) |
+| 131824 | — | END |
 
-`wipeBuffers()` zeroes all 14 buffer regions (key, chacha nonce/ctr/block/state, chunk pt/ct, poly key/msg/buf/tag/h/r/rs/s, xchacha nonce/subkey).
+`wipeBuffers()` zeroes all 15 buffer regions (key, chacha nonce/ctr/block/state, chunk pt/ct, poly key/msg/buf/tag/h/r/rs/s, xchacha nonce/subkey, SIMD work).
 
 ### SHA-2 module — 3 pages (192 KB)
 

package/dist/docs/serpent.md

@@ -265,6 +265,12 @@ automatically.
 - **chunk** -- any length up to the module's internal chunk buffer size. Throws
   `RangeError` if the chunk exceeds the maximum size.
 
+> [!NOTE]
+> Automatically dispatches to the 4-wide SIMD path (`encryptChunk_simd`) when
+> the runtime supports WebAssembly SIMD (`hasSIMD()` returns `true`), otherwise
+> falls back to the scalar unrolled path. The dispatch is transparent — no API
+> change required.
+
 ---
 
 #### `beginDecrypt(key: Uint8Array, nonce: Uint8Array): void`
@@ -353,6 +359,12 @@ Decrypts Serpent CBC ciphertext and strips PKCS7 padding.
 
 Returns the decrypted plaintext as a new `Uint8Array`.
 
+> [!NOTE]
+> Automatically dispatches to the 4-wide SIMD path (`cbcDecryptChunk_simd`) when
+> the runtime supports WebAssembly SIMD (`hasSIMD()` returns `true`), otherwise
+> falls back to the scalar unrolled path. CBC encryption has no SIMD variant —
+> each ciphertext block depends on the previous one.
+
 ---
 
 #### `dispose(): void`
@@ -535,7 +547,7 @@ and cross-stream splicing are all detected.
 
 ```typescript
 class SerpentStreamSealer {
-	constructor(key: Uint8Array, chunkSize?: number)
+	constructor(key: Uint8Array, chunkSize?: number, opts?: { framed?: boolean })
 	header(): Uint8Array        // call once before seal() — returns 20 bytes
 	seal(plaintext: Uint8Array): Uint8Array   // exactly chunkSize bytes
 	final(plaintext: Uint8Array): Uint8Array  // <= chunkSize bytes; wipes on return
@@ -543,8 +555,9 @@ class SerpentStreamSealer {
 }
 
 class SerpentStreamOpener {
-	constructor(key: Uint8Array, header: Uint8Array)
+	constructor(key: Uint8Array, header: Uint8Array, opts?: { framed?: boolean })
 	open(chunk: Uint8Array): Uint8Array  // throws on auth failure or post-final
+	feed(bytes: Uint8Array): Uint8Array[]  // framed mode only — accumulates and parses frames
 	dispose(): void
 }
 ```
@@ -576,12 +589,18 @@ wipes its key material and transitions to `dead`. Subsequent `open()` calls thro
 
 ---
 
-#### `constructor(key, chunkSize?)`
+#### `constructor(key, chunkSize?, opts?)`
 
 - **key** — 64-byte key. Throws `RangeError` if wrong length.
 - **chunkSize** — bytes per chunk. Must be 1024–65536. Default: 65536. Throws
   `RangeError` if out of range.
 
+##### Options (`opts`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `framed` | `boolean` | `false` | Prepend `u32be(sealedLen)` to each `seal()`/`final()` output. Use for flat byte streams (files, pipes, TCP). Omit when the transport already frames messages (WebSocket, IPC). |
+
 ---
 
 #### `header()`
@@ -615,12 +634,18 @@ Safe to call after `final()` — no-op if already dead.
 
 ---
 
-#### `constructor(key, header)` (opener)
+#### `constructor(key, header, opts?)` (opener)
 
 - **key** — 64-byte key. Throws `RangeError` if wrong length.
 - **header** — 20-byte stream header from `sealer.header()`. Throws `RangeError`
   if wrong length.
 
+##### Options (`opts`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `framed` | `boolean` | `false` | Enable byte-accumulation mode. Parses `u32be` length prefixes and dispatches complete frames to `open()` internally. Required to use `feed()`. |
+
 ---
 
 #### `open(chunk)`
@@ -631,6 +656,15 @@ plaintext bytes (PKCS7 padding stripped).
 
 ---
 
+#### `feed(bytes: Uint8Array): Uint8Array[]`
+
+Only callable when constructed with `{ framed: true }`. Accumulates incoming bytes,
+parses `u32be` length prefixes, dispatches complete frames to `open()` internally.
+Returns an array of decrypted chunks — zero, one, or more per call depending on how
+many complete frames were buffered. Throws if called on an unframed opener.
+
+---
+
 #### `dispose()` (opener)
 
 Wipes key material. Safe to call at any point — use to abort opening a stream

package/dist/docs/utils.md

@@ -143,6 +143,26 @@ Returns `n` cryptographically secure random bytes via the Web Crypto API (`crypt
 
 ---
 
+### hasSIMD
+
+```typescript
+hasSIMD(): boolean
+```
+
+Returns `true` if the current runtime supports WebAssembly SIMD (the `v128`
+type and associated operations). The result is computed once on first call by
+validating a minimal v128 WASM module, then cached for subsequent calls.
+
+This function is called internally by `SerpentCtr.encryptChunk`,
+`SerpentCbc.decrypt`, and `ChaCha20.encryptChunk` to select the fast SIMD path
+at runtime. It is exported for informational purposes — you do not need to call
+it yourself. SIMD dispatch is fully automatic.
+
+Supported in all modern browsers and Node.js 16+. Returns `false` in older
+environments, which fall back silently to the scalar path.
+
+---
+
 ## Usage Examples
 
 ### Converting between formats
@@ -258,6 +278,7 @@ console.log(combined.length) // 32
 | `constantTimeEqual` | Arrays differ in length | Returns `false` immediately |
 | `xor` | Arrays differ in length | Throws `RangeError` |
 | `randomBytes` | `crypto` not available | Throws (runtime-dependent) |
+| `hasSIMD` | `WebAssembly` not available | Returns `false` |
 
 ---