leviathan-crypto 2.0.0 → 2.1.0

package/dist/utils.js

@@ -23,13 +23,17 @@
 //
 // Pure TypeScript utilities — no init() dependency.
 // Ported from leviathan/src/base.ts (Convert namespace, Util namespace, constantTimeEqual).
-// ── Encoding ─────────────────────────────────────────────────────────────────
-/** Hex string to Uint8Array. Accepts lowercase/uppercase, optional 0x prefix. Throws RangeError on odd-length input. */
+// ── Encoding ────────────────────────────────────────────────────────────────
+/** Hex string to Uint8Array. Accepts lowercase/uppercase, optional 0x prefix. Throws RangeError on odd-length or non-hex input. */
 export const hexToBytes = (hex) => {
     if (hex.startsWith('0x') || hex.startsWith('0X'))
         hex = hex.slice(2);
     if (hex.length % 2)
         throw new RangeError(`hexToBytes: odd-length string (${hex.length} chars) — input must be an even-length hex string`);
+    // parseInt('0g', 16) returns 0 (not NaN) because it stops at the first
+    // invalid char — silent wrong-answer. Reject non-hex chars up front.
+    if (hex.length > 0 && !/^[0-9a-fA-F]*$/.test(hex))
+        throw new RangeError('hexToBytes: input contains non-hex characters');
     const bin = new Uint8Array(hex.length >>> 1);
     for (let i = 0, len = hex.length >>> 1; i < len; i++)
         bin[i] = parseInt(hex.slice(i << 1, (i << 1) + 2), 16);
@@ -51,20 +55,20 @@ export const utf8ToBytes = (str) => {
 export const bytesToUtf8 = (bytes) => {
     return new TextDecoder().decode(bytes);
 };
-/** Base64 or base64url string to Uint8Array. Handles padded, unpadded, and legacy %3d padding. Returns undefined on invalid input. */
+/** Base64 or base64url string to Uint8Array. Handles padded, unpadded, and legacy %3d padding. Throws RangeError on invalid input. */
 export const base64ToBytes = (b64) => {
     // Normalise base64url → base64
     b64 = b64.replace(/-/g, '+').replace(/_/g, '/').replace(/%3d/gi, '=');
     // Re-pad if unpadded (RFC 4648 §5 base64url omits '=')
     const rem = b64.length % 4;
     if (rem === 1)
-        return undefined; // always invalid — no valid b64 produces this
+        throw new RangeError('base64ToBytes: invalid base64 input'); // no valid b64 produces this
     if (rem === 2)
         b64 += '==';
     if (rem === 3)
         b64 += '=';
     if (!/^[A-Za-z0-9+/]*={0,2}$/.test(b64))
-        return undefined;
+        throw new RangeError('base64ToBytes: invalid base64 input');
     let strlen = b64.length / 4 * 3;
     if (b64.charAt(b64.length - 1) === '=')
         strlen--;
@@ -75,7 +79,7 @@ export const base64ToBytes = (b64) => {
             return new Uint8Array(atob(b64).split('').map(c => c.charCodeAt(0)));
         }
         catch {
-            return undefined;
+            throw new RangeError('base64ToBytes: invalid base64 input');
         }
     }
     // Fallback: manual decode
@@ -136,65 +140,90 @@ export const bytesToBase64 = (bytes, url = false) => {
     }
     return base64;
 };
-// ── Constant-time comparison ─────────────────────────────────────────────────
+// ── Constant-time comparison ────────────────────────────────────────────────
 import { CT_WASM } from './ct-wasm.js';
 let _ctCompare = null;
 let _ctMem = null;
 let _ctInit = false;
+let _ctInitError = null;
 // CT WASM module uses 1 page (64KB) of linear memory with both buffers
 // laid out side-by-side: a at offset 0, b at offset a.length.
 // Max per-side = _ctMem.buffer.byteLength >>> 1 = 32768 bytes.
 // In practice the largest comparison is a 32-byte HMAC-SHA-256 tag.
 export const CT_MAX_BYTES = 32768;
-/** Try to compile the SIMD WASM ct module. Returns false if unavailable. */
+/**
+ * Compile and instantiate the SIMD WASM ct module. On failure, caches the
+ * branded error and re-throws on every subsequent call; no retries, no
+ * fallback. Throws on runtimes without WebAssembly SIMD and on any
+ * instantiation error.
+ */
 function _initCt() {
-    if (_ctInit)
-        return _ctCompare !== null;
+    if (_ctInit) {
+        if (_ctInitError)
+            throw _ctInitError;
+        return;
+    }
     _ctInit = true;
+    if (!hasSIMD()) {
+        _ctInitError = new Error('leviathan-crypto: constantTimeEqual requires WebAssembly SIMD — '
+            + 'this runtime does not support it');
+        throw _ctInitError;
+    }
     try {
-        if (!hasSIMD())
-            return false;
-        _ctMem = new WebAssembly.Memory({ initial: 1, maximum: 1 });
         const buf = CT_WASM.buffer.slice(CT_WASM.byteOffset, CT_WASM.byteOffset + CT_WASM.byteLength);
         const mod = new WebAssembly.Module(buf);
-        const inst = new WebAssembly.Instance(mod, { env: { memory: _ctMem } });
-        _ctCompare = inst.exports.compare;
-        return true;
+        const inst = new WebAssembly.Instance(mod);
+        const exports = inst.exports;
+        _ctMem = exports.memory;
+        _ctCompare = exports.compare;
     }
-    catch {
-        return false;
+    catch (cause) {
+        _ctInitError = new Error(`leviathan-crypto: ct WASM module failed to instantiate: ${cause.message}`);
+        throw _ctInitError;
     }
 }
 /**
  * Constant-time byte-array equality.
- * Uses WASM SIMD when available (no JIT short-circuiting, no speculative
- * optimization). Falls back to a JS XOR-accumulate loop on runtimes
- * without SIMD support.
- * Length check is not constant-time (length is non-secret in all protocols).
- * Max input size: 32768 bytes per side (enforced regardless of code path).
+ * Runs entirely inside a WASM SIMD module (v128 XOR accumulate with
+ * branch-free reduction). Throws on runtimes without SIMD support —
+ * no JS fallback. Length check is not constant-time (length is
+ * non-secret in all protocols). Max input size: 32768 bytes per side.
  */
 export const constantTimeEqual = (a, b) => {
     if (a.length !== b.length)
         return false;
     if (a.length > CT_MAX_BYTES)
         throw new RangeError(`constantTimeEqual: max ${CT_MAX_BYTES} bytes (got ${a.length})`);
-    if (_initCt() && _ctMem && _ctCompare) {
-        const mem = new Uint8Array(_ctMem.buffer);
-        mem.set(a, 0);
-        mem.set(b, a.length);
-        try {
-            return _ctCompare(0, a.length, a.length) === 1;
-        }
-        finally {
-            mem.fill(0, 0, a.length * 2);
-        }
+    _initCt();
+    // Copy module-level refs to locals. _initCt() either populates both
+    // _ctMem and _ctCompare or throws; the null check below is a defensive
+    // invariant guard that is unreachable on a correctly-initialized module.
+    const memObj = _ctMem;
+    const compare = _ctCompare;
+    if (!memObj || !compare)
+        throw new Error('leviathan-crypto: ct init invariant violated');
+    const mem = new Uint8Array(memObj.buffer);
+    mem.set(a, 0);
+    mem.set(b, a.length);
+    try {
+        return compare(0, a.length, a.length) === 1;
+    }
+    finally {
+        mem.fill(0, 0, a.length * 2);
     }
-    // JS fallback — best-effort constant-time via XOR accumulate
-    let diff = 0;
-    for (let i = 0; i < a.length; i++)
-        diff |= a[i] ^ b[i];
-    return diff === 0;
 };
+/**
+ * Reset the internal CT WASM cache, including any cached initialization
+ * error. Exists so the test suite can force re-instantiation across
+ * describe blocks.
+ * @internal
+ */
+export function _ctResetForTesting() {
+    _ctInit = false;
+    _ctCompare = null;
+    _ctMem = null;
+    _ctInitError = null;
+}
 /** Zero a typed array in place. */
 export const wipe = (data) => {
     data.fill(0);
@@ -218,11 +247,15 @@ export const concat = (...arrays) => {
 };
 /** Cryptographically secure random bytes via Web Crypto API. */
 export const randomBytes = (n) => {
+    if (typeof globalThis.crypto === 'undefined'
+        || typeof globalThis.crypto.getRandomValues !== 'function')
+        throw new Error('leviathan-crypto: crypto.getRandomValues is required — '
+            + 'this runtime does not expose the Web Crypto API');
     const buf = new Uint8Array(n);
-    crypto.getRandomValues(buf);
+    globalThis.crypto.getRandomValues(buf);
     return buf;
 };
-// ── SIMD detection ───────────────────────────────────────────────────────────
+// ── SIMD detection ──────────────────────────────────────────────────────────
 let _simd = null;
 /**
  * Detects WASM SIMD support once and caches the result.

package/dist/wasm-source.d.ts

@@ -1,12 +1,13 @@
 /**
  * All accepted forms of WASM input for init functions.
  *
- * - `string`                — gzip+base64 embedded blob (from `/embedded` subpath)
- * - `URL`                   — fetched via `WebAssembly.instantiateStreaming`
- * - `ArrayBuffer`           — raw WASM bytes, compiled inline
- * - `Uint8Array`            — raw WASM bytes, compiled inline
- * - `WebAssembly.Module`    — pre-compiled module (Cloudflare Workers, edge runtimes)
- * - `Response`              — streaming instantiation from an in-flight fetch response
- * - `Promise<Response>`     — streaming instantiation from a deferred fetch
+ * - `string`                   — gzip+base64 embedded blob (from `/embedded` subpath)
+ * - `URL`                      — streaming-compiled from `fetch(url)`
+ * - `ArrayBuffer`              — raw WASM bytes, compiled inline
+ * - `Uint8Array`               — raw WASM bytes, compiled inline
+ * - `WebAssembly.Module`       — pre-compiled module (Cloudflare Workers, edge runtimes)
+ * - `Response`                 — streaming-compiled from an in-flight fetch
+ * - `PromiseLike<WasmSource>`  — any thenable resolving to another `WasmSource`; nesting
+ *                                is resolved recursively (max depth 3).
  */
-export type WasmSource = string | URL | ArrayBuffer | Uint8Array | WebAssembly.Module | Response | Promise<Response>;
+export type WasmSource = string | URL | ArrayBuffer | Uint8Array | WebAssembly.Module | Response | PromiseLike<WasmSource>;

package/package.json

@@ -1,66 +1,81 @@
 {
-  "name": "leviathan-crypto",
-  "version": "2.0.0",
-  "author": "xero (https://x-e.ro)",
-  "license": "MIT",
-  "description": "Zero-dependency WASM cryptography for TypeScript. Paranoid ciphers, post-quantum key encapsulation, and Fortuna CSPRNG behind a strictly typed API. All computation runs outside the JS JIT on vector-verified primitives.",
-  "type": "module",
-  "sideEffects": false,
-  "exports": {
-    ".": "./dist/index.js",
-    "./stream": "./dist/stream/index.js",
-    "./serpent": "./dist/serpent/index.js",
-    "./serpent/embedded": "./dist/serpent/embedded.js",
-    "./chacha20": "./dist/chacha20/index.js",
-    "./chacha20/embedded": "./dist/chacha20/embedded.js",
-    "./sha2": "./dist/sha2/index.js",
-    "./sha2/embedded": "./dist/sha2/embedded.js",
-    "./sha3": "./dist/sha3/index.js",
-    "./sha3/embedded": "./dist/sha3/embedded.js",
-    "./keccak": "./dist/keccak/index.js",
-    "./keccak/embedded": "./dist/keccak/embedded.js",
-    "./kyber": "./dist/kyber/index.js",
-    "./kyber/embedded": "./dist/kyber/embedded.js"
-  },
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "SECURITY.md",
-    "CLAUDE.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/xero/leviathan-crypto.git"
-  },
-  "homepage": "https://leviathan.3xi.club",
-  "bugs": {
-    "url": "https://github.com/xero/leviathan-crypto/issues"
-  },
-  "keywords": [
-    "cryptography",
-    "encryption",
-    "serpent",
-    "serpent-256",
-    "cipher",
-    "crypto",
-    "typescript",
-    "wasm",
-    "webassembly",
-    "chacha20",
-    "xchacha20",
-    "poly1305",
-    "xchacha20-poly1305",
-    "aead",
-    "sha",
-    "sha-256",
-    "sha-512",
-    "sha-3",
-    "keccak",
-    "shake",
-    "hmac",
-    "hkdf",
-    "fortuna",
-    "csprng",
-    "entropy"
-  ]
+	"name": "leviathan-crypto",
+	"version": "2.1.0",
+	"author": "xero (https://x-e.ro)",
+	"license": "MIT",
+	"description": "Post-quantum WASM cryptography with paranoid ciphers (Serpent-256, XChaCha20-Poly1305), ML-KEM, and forward-secret ratcheting. Zero dependencies. Constant-time verified and strictly typed.",
+	"type": "module",
+	"sideEffects": false,
+	"exports": {
+		".": "./dist/index.js",
+		"./stream": "./dist/stream/index.js",
+		"./serpent": "./dist/serpent/index.js",
+		"./serpent/embedded": "./dist/serpent/embedded.js",
+		"./chacha20": "./dist/chacha20/index.js",
+		"./chacha20/embedded": "./dist/chacha20/embedded.js",
+		"./sha2": "./dist/sha2/index.js",
+		"./sha2/embedded": "./dist/sha2/embedded.js",
+		"./sha3": "./dist/sha3/index.js",
+		"./sha3/embedded": "./dist/sha3/embedded.js",
+		"./keccak": "./dist/keccak/index.js",
+		"./keccak/embedded": "./dist/keccak/embedded.js",
+		"./kyber": "./dist/kyber/index.js",
+		"./kyber/embedded": "./dist/kyber/embedded.js",
+		"./ratchet": "./dist/ratchet/index.js"
+	},
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"SECURITY.md",
+		"CLAUDE.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xero/leviathan-crypto.git"
+	},
+	"homepage": "https://leviathan.3xi.club",
+	"bugs": {
+		"url": "https://github.com/xero/leviathan-crypto/issues"
+	},
+	"keywords": [
+		"cryptography",
+		"encryption",
+		"crypto",
+		"typescript",
+		"wasm",
+		"webassembly",
+		"zero-dependency",
+		"constant-time",
+		"side-channel",
+		"serpent",
+		"serpent-256",
+		"cipher",
+		"aead",
+		"chacha20",
+		"xchacha20",
+		"poly1305",
+		"xchacha20-poly1305",
+		"kyber",
+		"ml-kem",
+		"mlkem",
+		"pqc",
+		"post-quantum",
+		"key-encapsulation",
+		"kem",
+		"double-ratchet",
+		"ratchet",
+		"forward-secrecy",
+		"spqr",
+		"sha",
+		"sha-256",
+		"sha-512",
+		"sha-3",
+		"keccak",
+		"shake",
+		"hmac",
+		"hkdf",
+		"fortuna",
+		"csprng",
+		"entropy"
+	]
 }