leviathan-crypto 2.0.1 → 3.0.0

package/dist/utils.js

@@ -21,15 +21,18 @@
 //
 // src/ts/utils.ts
 //
-// 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. */
+// Pure TypeScript utilities, no init() dependency.
+// ── 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`);
+        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 +54,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 +78,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
@@ -110,7 +113,7 @@ export const base64ToBytes = (b64) => {
     }
     return bin;
 };
-/** Uint8Array to base64 string. Pass url=true for base64url (RFC 4648 §5 — no padding characters). */
+/** Uint8Array to base64 string. Pass url=true for base64url (RFC 4648 §5, no padding characters). */
 export const bytesToBase64 = (bytes, url = false) => {
     if (typeof btoa !== 'undefined') {
         const raw = btoa(String.fromCharCode.apply(null, Array.from(bytes)));
@@ -136,65 +139,83 @@ export const bytesToBase64 = (bytes, url = false) => {
     }
     return base64;
 };
-// ── Constant-time comparison ─────────────────────────────────────────────────
-import { CT_WASM } from './ct-wasm.js';
-let _ctCompare = null;
-let _ctMem = null;
-let _ctInit = false;
-// 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. */
-function _initCt() {
-    if (_ctInit)
-        return _ctCompare !== null;
-    _ctInit = true;
+// ── Constant-time comparison ────────────────────────────────────────────────
+import { CTE_WASM } from './cte-wasm.js';
+let _cteCompare = null;
+let _cteMem = null;
+let _cteMemView = null;
+let _cteInit = false;
+let _cteInitError = null;
+export const CTE_MAX_BYTES = 32768;
+function _initCte() {
+    if (_cteInit) {
+        if (_cteInitError)
+            throw _cteInitError;
+        return;
+    }
+    _cteInit = true;
+    if (!hasSIMD()) {
+        _cteInitError = new Error('leviathan-crypto: constantTimeEqual requires WebAssembly SIMD, '
+            + 'this runtime does not support it');
+        throw _cteInitError;
+    }
     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 buf = CTE_WASM.buffer.slice(CTE_WASM.byteOffset, CTE_WASM.byteOffset + CTE_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;
+        _cteMem = exports.memory;
+        _cteMemView = new Uint8Array(_cteMem.buffer);
+        _cteCompare = exports.compare;
     }
-    catch {
-        return false;
+    catch (cause) {
+        _cteInitError = new Error(`leviathan-crypto: cte WASM module failed to instantiate: ${cause.message}`);
+        throw _cteInitError;
     }
 }
 /**
  * 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);
-        }
+    if (a.length > CTE_MAX_BYTES)
+        throw new RangeError(`constantTimeEqual: max ${CTE_MAX_BYTES} bytes (got ${a.length})`);
+    _initCte();
+    const mem = _cteMemView;
+    const compare = _cteCompare;
+    if (!mem || !compare)
+        throw new Error('leviathan-crypto: cte init invariant violated');
+    mem.set(a, 0);
+    mem.set(b, a.length);
+    try {
+        return compare(0, a.length, a.length) === 1;
+    }
+    finally {
+        // Wipe the full cte memory region, not just the bytes we wrote.
+        // Defense in depth against stale residue from longer prior calls.
+        // The module-private WASM memory is never read from outside this
+        // function, but we keep the surface clean regardless.
+        mem.fill(0, 0, CTE_MAX_BYTES * 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 CTE WASM cache, including any cached initialization
+ * error. Exists so the test suite can force re-instantiation across
+ * describe blocks.
+ * @internal
+ */
+export function _cteResetForTesting() {
+    _cteInit = false;
+    _cteCompare = null;
+    _cteMem = null;
+    _cteMemView = null;
+    _cteInitError = null;
+}
 /** Zero a typed array in place. */
 export const wipe = (data) => {
     data.fill(0);
@@ -218,11 +239,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.
@@ -236,7 +261,7 @@ export function hasSIMD() {
         _simd = false;
         return _simd;
     }
-    // Minimal WASM module using v128 — validates iff SIMD is supported
+    // Minimal WASM module using v128, validates iff SIMD is supported
     try {
         _simd = WebAssembly.validate(new Uint8Array([
             0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 123,

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/dist/wasm-source.js

@@ -22,5 +22,5 @@
 // src/ts/wasm-source.ts
 //
 // Union type for all accepted WASM loading strategies.
-// The argument type determines the loading path — no mode string required.
+// The argument type determines the loading path, no mode string required.
 export {};

package/dist/x25519/embedded.d.ts

@@ -0,0 +1 @@
+export { WASM_GZ_BASE64 as curve25519Wasm, WASM_GZ_BASE64 as x25519Wasm, } from '../embedded/curve25519.js';

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})`);
+}