leviathan-crypto 2.1.0 → 3.0.0

package/dist/x25519/embedded.js

@@ -0,0 +1,31 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/x25519/embedded.ts
+//
+// Exports the gzip+base64 curve25519 WASM blob for use as a WasmSource.
+// Ed25519 and X25519 share the same curve25519 WASM binary; both the
+// `leviathan-crypto/ed25519/embedded` and `leviathan-crypto/x25519/embedded`
+// subpaths re-export the same blob under three names: `curve25519Wasm`
+// (canonical), `ed25519Wasm`, and `x25519Wasm` (aliases that read more
+// naturally in the matching subpath context). All three resolve to the
+// identical underlying string; tree-shaking is unaffected.
+export { WASM_GZ_BASE64 as curve25519Wasm, WASM_GZ_BASE64 as x25519Wasm, } from '../embedded/curve25519.js';

package/dist/x25519/index.d.ts

@@ -0,0 +1,43 @@
+import { isInitialized } from '../init.js';
+import type { WasmSource } from '../wasm-source.js';
+import type { X25519KeyPair } from './types.js';
+/**
+ * Initialise the curve25519 WASM module under the `x25519` alias.
+ * Equivalent to `ed25519Init(source)`; both target the same WASM module
+ * and the init layer de-dupes when given identical sources.
+ */
+export declare function x25519Init(source: WasmSource): Promise<void>;
+export type { WasmSource };
+export type { X25519KeyPair, X25519Exports } from './types.js';
+export { isInitialized };
+export declare class X25519 {
+    constructor();
+    private get mx();
+    /**
+     * Deterministic X25519 key generation from a 32-byte secret per
+     * RFC 7748 §6. Clamping is applied internally on every WASM call;
+     * the returned secretKey is a fresh copy of the supplied sk bytes
+     * (NOT pre-clamped).
+     */
+    keygenDerand(sk: Uint8Array): X25519KeyPair;
+    /** Random X25519 key generation, wraps `keygenDerand` with `randomBytes(32)`. */
+    keygen(): X25519KeyPair;
+    /**
+     * X25519 Diffie-Hellman, RFC 7748 §6.
+     *
+     * Computes the shared u-coordinate from the local secret and the
+     * peer's public key. If the resulting shared secret is all-zero
+     * (peer public key is a small-order point per RFC 7748 §7), throws
+     * `KeyAgreementError` rather than returning the degenerate value.
+     * The all-zero scan accumulates via OR across all 32 output bytes
+     * before comparing to zero, so the success path is constant-time;
+     * the throw branches off only after a known-bad outcome is observed.
+     *
+     * @param sk     32-byte local secret (NOT pre-clamped, clamped internally)
+     * @param peerPk 32-byte peer public key (u-coordinate)
+     * @returns 32-byte shared u-coordinate
+     * @throws KeyAgreementError on all-zero shared secret
+     */
+    dh(sk: Uint8Array, peerPk: Uint8Array): Uint8Array;
+    dispose(): void;
+}

package/dist/x25519/index.js

@@ -0,0 +1,159 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/x25519/index.ts
+//
+// X25519 public API. RFC 7748 §5 (algorithm), §6 (keygen + DH), §7
+// (security considerations and the small-order peer-pk rejection that
+// motivates the TS-layer all-zero shared-secret check).
+//
+// Both Ed25519 and X25519 share the curve25519 WASM module;
+// `ed25519Init(source)` and `x25519Init(source)` both target it and the
+// init() layer de-dupes when given identical sources.
+//
+// Per-call lifecycle mirrors the Ed25519 wrapper: stage caller inputs
+// at fixed offsets above the WASM mutable buffer region, call the
+// underlying export, copy outputs to fresh `Uint8Array`s, wipe both
+// the WASM-internal scratch and the TS-side I/O staging region.
+import { getInstance, initModule, isInitialized, _assertNotOwned } from '../init.js';
+import { randomBytes, wipe } from '../utils.js';
+import { KeyAgreementError } from '../errors.js';
+import { validateSecretKey, validatePublicKey } from './validate.js';
+/**
+ * Initialise the curve25519 WASM module under the `x25519` alias.
+ * Equivalent to `ed25519Init(source)`; both target the same WASM module
+ * and the init layer de-dupes when given identical sources.
+ */
+export async function x25519Init(source) {
+    return initModule('curve25519', source);
+}
+export { isInitialized };
+// ── I/O staging layout ─────────────────────────────────────────────────────
+//
+// Same base as the ed25519 wrapper, fixed offsets above the WASM mutable
+// buffer region (BUFFER_END = 7836). Two 32-byte input slots plus one
+// 32-byte output slot, no large variable region.
+const IO_BASE = 8192;
+const SK_STAGE = IO_BASE; // 32 bytes
+const PK_STAGE = IO_BASE + 32; // 32 bytes
+const PEER_STAGE = IO_BASE + 64; // 32 bytes
+const SHARED_STAGE = IO_BASE + 96; // 32 bytes
+function ioWipe(mx) {
+    // Zero the entire TS-managed staging region. wipeBuffers covers
+    // MUTABLE_START..BUFFER_END only; the I/O slots above must be
+    // scrubbed at the wrapper layer.
+    new Uint8Array(mx.memory.buffer).fill(0, IO_BASE, mx.memory.buffer.byteLength);
+}
+export class X25519 {
+    constructor() {
+        if (!isInitialized('curve25519'))
+            throw new Error('leviathan-crypto: call init({ x25519: ... }) before using X25519');
+    }
+    get mx() {
+        return getInstance('curve25519').exports;
+    }
+    /**
+     * Deterministic X25519 key generation from a 32-byte secret per
+     * RFC 7748 §6. Clamping is applied internally on every WASM call;
+     * the returned secretKey is a fresh copy of the supplied sk bytes
+     * (NOT pre-clamped).
+     */
+    keygenDerand(sk) {
+        _assertNotOwned('curve25519');
+        validateSecretKey(sk);
+        const mx = this.mx;
+        const mem = new Uint8Array(mx.memory.buffer);
+        mem.set(sk, SK_STAGE);
+        try {
+            mx.x25519Keygen(SK_STAGE, PK_STAGE);
+            const publicKey = mem.slice(PK_STAGE, PK_STAGE + 32);
+            const secretKey = new Uint8Array(32);
+            secretKey.set(sk);
+            return { publicKey, secretKey };
+        }
+        finally {
+            ioWipe(mx);
+            mx.wipeBuffers();
+        }
+    }
+    /** Random X25519 key generation, wraps `keygenDerand` with `randomBytes(32)`. */
+    keygen() {
+        const sk = randomBytes(32);
+        try {
+            return this.keygenDerand(sk);
+        }
+        finally {
+            wipe(sk);
+        }
+    }
+    /**
+     * X25519 Diffie-Hellman, RFC 7748 §6.
+     *
+     * Computes the shared u-coordinate from the local secret and the
+     * peer's public key. If the resulting shared secret is all-zero
+     * (peer public key is a small-order point per RFC 7748 §7), throws
+     * `KeyAgreementError` rather than returning the degenerate value.
+     * The all-zero scan accumulates via OR across all 32 output bytes
+     * before comparing to zero, so the success path is constant-time;
+     * the throw branches off only after a known-bad outcome is observed.
+     *
+     * @param sk     32-byte local secret (NOT pre-clamped, clamped internally)
+     * @param peerPk 32-byte peer public key (u-coordinate)
+     * @returns 32-byte shared u-coordinate
+     * @throws KeyAgreementError on all-zero shared secret
+     */
+    dh(sk, peerPk) {
+        _assertNotOwned('curve25519');
+        validateSecretKey(sk);
+        validatePublicKey(peerPk);
+        const mx = this.mx;
+        const mem = new Uint8Array(mx.memory.buffer);
+        mem.set(sk, SK_STAGE);
+        mem.set(peerPk, PEER_STAGE);
+        try {
+            mx.x25519DH(SK_STAGE, PEER_STAGE, SHARED_STAGE);
+            const shared = mem.slice(SHARED_STAGE, SHARED_STAGE + 32);
+            // Constant-time OR-accumulate scan, RFC 7748 §6.1
+            // contributory-behaviour requirement. No early exit on the
+            // first non-zero byte.
+            let acc = 0;
+            for (let i = 0; i < 32; i++)
+                acc |= shared[i];
+            if (acc === 0) {
+                wipe(shared);
+                throw new KeyAgreementError('leviathan-crypto: X25519 shared secret is all-zero '
+                    + '(peer public key is a small-order point)');
+            }
+            return shared;
+        }
+        finally {
+            ioWipe(mx);
+            mx.wipeBuffers();
+        }
+    }
+    dispose() {
+        try {
+            this.mx.wipeBuffers();
+            ioWipe(this.mx);
+        }
+        catch { /* idempotent */ }
+    }
+}

package/dist/x25519/types.d.ts

@@ -0,0 +1,25 @@
+export interface X25519KeyPair {
+    /** 32-byte public u-coordinate. */
+    publicKey: Uint8Array;
+    /**
+     * 32-byte secret. Per RFC 7748 §5 / §6 this is "any 32 random bytes";
+     * clamping is applied internally on every WASM call. The stored
+     * secretKey is the unclamped form so that round-tripping through
+     * keygen / external storage preserves byte-equality.
+     */
+    secretKey: Uint8Array;
+}
+/**
+ * The X25519-relevant subset of the curve25519 WASM exports. The
+ * curve25519 module is shared between Ed25519 and X25519; this interface
+ * deliberately surfaces only the X25519 high-level entry points plus the
+ * layout / wipe primitives.
+ */
+export interface X25519Exports {
+    memory: WebAssembly.Memory;
+    getModuleId: () => number;
+    getMemoryPages: () => number;
+    x25519Keygen: (skOff: number, pkOff: number) => void;
+    x25519DH: (skOff: number, peerPkOff: number, sharedOff: number) => void;
+    wipeBuffers: () => void;
+}

package/dist/x25519/types.js

@@ -0,0 +1,27 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/x25519/types.ts
+//
+// X25519 type surface: the WASM export interface for the curve25519
+// module (X25519-relevant subset) and the public key-pair shape returned
+// by keygen / keygenDerand. RFC 7748 §5 / §6.
+export {};

package/dist/x25519/validate.d.ts

@@ -0,0 +1,2 @@
+export declare function validateSecretKey(sk: Uint8Array): void;
+export declare function validatePublicKey(pk: Uint8Array): void;

package/dist/x25519/validate.js

@@ -0,0 +1,39 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       Leviathan Crypto Library
+//     ███████▌    ▀██▀         ███
+//      ███████   ▀███           ▀██ ▀█▄      Repository & Mirror:
+//       ▀██████   ▄▄██            ▀▀  ██▄    github.com/xero/leviathan-crypto
+//         ▀█████▄   ▄██▄             ▄▀▄▀    unpkg.com/leviathan-crypto
+//            ▀████▄   ▄██▄
+//              ▐████   ▐███                  Author: xero (https://x-e.ro)
+//       ▄▄██████████    ▐███         ▄▄      License: MIT
+//    ▄██▀▀▀▀▀▀▀▀▀▀     ▄████      ▄██▀
+//  ▄▀  ▄▄█████████▄▄  ▀▀▀▀▀     ▄███         This file is provided completely
+//   ▄██████▀▀▀▀▀▀██████▄ ▀▄▄▄▄████▀          free, "as is", and without
+//  ████▀    ▄▄▄▄▄▄▄ ▀████▄ ▀█████▀  ▄▄▄▄     warranty of any kind. The author
+//  █████▄▄█████▀▀▀▀▀▀▄ ▀███▄      ▄████      assumes absolutely no liability
+//   ▀██████▀             ▀████▄▄▄████▀       for its {ab,mis,}use.
+//                           ▀█████▀▀
+//
+// src/ts/x25519/validate.ts
+//
+// X25519 caller-side input validation. Pure length / type checks. Peer
+// public-key masking happens inside the WASM (feFromBytes masks bit 255
+// per RFC 7748 §5); the all-zero shared-secret rejection happens in the
+// TS X25519.dh method after the WASM returns.
+export function validateSecretKey(sk) {
+    if (!(sk instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: x25519 secret key must be a Uint8Array');
+    if (sk.length !== 32)
+        throw new RangeError(`leviathan-crypto: x25519 secret key must be 32 bytes (got ${sk.length})`);
+}
+export function validatePublicKey(pk) {
+    if (!(pk instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: x25519 public key must be a Uint8Array');
+    if (pk.length !== 32)
+        throw new RangeError(`leviathan-crypto: x25519 public key must be 32 bytes (got ${pk.length})`);
+}

package/package.json

@@ -1,9 +1,17 @@
 {
 	"name": "leviathan-crypto",
-	"version": "2.1.0",
-	"author": "xero (https://x-e.ro)",
+	"version": "3.0.0",
 	"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.",
+	"description": "Paranoid post-quantum WASM cryptography library with bitsliced ciphers (Serpent, XChaCha20, AES), ML-KEM, lattice and hash-based signatures (ML-DSA, SLH-DSA, hybrid composites), hashing (SHA-2, SHA-3, BLAKE3), forward-secret ratchet, and Fortuna CSPRNG. Zero dependencies, tree-shakeable, and side-effect-free.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xero/leviathan-crypto.git"
+	},
+	"bugs": {
+		"url": "https://github.com/xero/leviathan-crypto/issues"
+	},
+	"homepage": "https://leviathan.3xi.club",
+	"author": "xero (https://x-e.ro)",
 	"type": "module",
 	"sideEffects": false,
 	"exports": {
@@ -19,24 +27,31 @@
 		"./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"
+		"./mlkem": "./dist/mlkem/index.js",
+		"./mlkem/embedded": "./dist/mlkem/embedded.js",
+		"./aes": "./dist/aes/index.js",
+		"./aes/embedded": "./dist/aes/embedded.js",
+		"./blake3": "./dist/blake3/index.js",
+		"./blake3/embedded": "./dist/blake3/embedded.js",
+		"./ecdsa": "./dist/ecdsa/index.js",
+		"./ecdsa/embedded": "./dist/ecdsa/embedded.js",
+		"./ed25519": "./dist/ed25519/index.js",
+		"./ed25519/embedded": "./dist/ed25519/embedded.js",
+		"./mldsa": "./dist/mldsa/index.js",
+		"./mldsa/embedded": "./dist/mldsa/embedded.js",
+		"./slhdsa": "./dist/slhdsa/index.js",
+		"./slhdsa/embedded": "./dist/slhdsa/embedded.js",
+		"./x25519": "./dist/x25519/index.js",
+		"./x25519/embedded": "./dist/x25519/embedded.js",
+		"./ratchet": "./dist/ratchet/index.js",
+		"./sign": "./dist/sign/index.js",
+		"./merkle": "./dist/merkle/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",
@@ -44,38 +59,67 @@
 		"typescript",
 		"wasm",
 		"webassembly",
+		"simd",
+		"isomorphic",
 		"zero-dependency",
 		"constant-time",
+		"bitsliced",
 		"side-channel",
+		"post-quantum",
+		"pqc",
+		"hybrid",
+		"aead",
+		"kem",
+		"key-encapsulation",
+		"signing",
+		"signature",
+		"hashing",
+		"cipher",
 		"serpent",
 		"serpent-256",
-		"cipher",
-		"aead",
 		"chacha20",
 		"xchacha20",
 		"poly1305",
 		"xchacha20-poly1305",
+		"aes",
+		"aes-256",
+		"aes-gcm-siv",
 		"kyber",
 		"ml-kem",
 		"mlkem",
-		"pqc",
-		"post-quantum",
-		"key-encapsulation",
-		"kem",
-		"double-ratchet",
-		"ratchet",
-		"forward-secrecy",
-		"spqr",
+		"ml-dsa",
+		"mldsa",
+		"slh-dsa",
+		"slhdsa",
+		"ed25519",
+		"x25519",
+		"ecdsa",
+		"ecdsa-p256",
+		"p256",
+		"prime256v1",
+		"secp256r1",
 		"sha",
 		"sha-256",
 		"sha-512",
 		"sha-3",
 		"keccak",
 		"shake",
+		"cshake",
+		"blake3",
 		"hmac",
+		"kmac",
 		"hkdf",
+		"argon2",
+		"argon2id",
 		"fortuna",
 		"csprng",
-		"entropy"
+		"entropy",
+		"double-ratchet",
+		"ratchet",
+		"forward-secrecy",
+		"spqr",
+		"merkle",
+		"merkle-tree",
+		"transparency-log"
 	]
 }