leviathan-crypto 2.1.0 → 3.0.0

package/dist/ecdsa/index.js

@@ -0,0 +1,366 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/ecdsa/index.ts
+//
+// ECDSA-P256 public API. FIPS 186-5 §6 over the NIST P-256 curve
+// (SP 800-186 §3.2.1.3). Hedged-or-deterministic K per RFC 6979 §3.2
+// and draft-irtf-cfrg-det-sigs-with-noise-05. Strict-S verify (low-S
+// enforced).
+//
+// Uncompressed pk per SEC 1 §2.3.4 is available via
+// `pointDecompress` and `EcdsaP256.keygenUncompressed`. The composite
+// ML-DSA + ECDSA suites need the 65-byte `0x04 || X || Y` form.
+import { getInstance, initModule, isInitialized, _assertNotOwned } from '../init.js';
+import { randomBytes, wipe } from '../utils.js';
+import { SigningError } from '../errors.js';
+import { validateSeed, validateSecretKey, validatePublicKey, validateMessageHash, validateSignature, validateEntropy, } from './validate.js';
+/**
+ * Initialise the p256 WASM module. Loads the underlying binary
+ * (scalar, no SIMD) into the `p256` slot.
+ */
+export async function ecdsaP256Init(source) {
+    return initModule('p256', source);
+}
+export { isInitialized };
+export { encodeEcPrivateKey, decodeEcPrivateKey } from './ecprivatekey-der.js';
+// ── I/O staging layout ─────────────────────────────────────────────────────
+//
+// The p256 module's mutable buffer region ends at BUFFER_END = 7054
+// (see src/asm/p256/buffers.ts). The TS layer stages caller-supplied
+// inputs and reads outputs from a fixed region above that. The module
+// is allocated 3 pages (196608 bytes); the I/O region stretches from
+// 8192 to the end of linear memory.
+//
+// Each slot is sized to its maximum useful content and rounded to a
+// 32-byte boundary for layout clarity. The WASM exports read every
+// input once at the start of execution, so co-locating per-call
+// inputs in this region is safe.
+const IO_BASE = 8192;
+const SEED_STAGE = IO_BASE; // 32 bytes (seed for keygen, sk for sign)
+const PK_STAGE = IO_BASE + 64; // 33 bytes (compressed pk, SEC 1 §2.3.3)
+const SIG_STAGE = IO_BASE + 128; // 64 bytes (raw r||s)
+const MSG_HASH_STAGE = IO_BASE + 192; // 32 bytes (SHA-256 digest)
+const RND_STAGE = IO_BASE + 224; // 32 bytes (per-call entropy Z)
+const POINT_STAGE = IO_BASE + 256; // 96 bytes (projective X:Y:Z, decompression output)
+const PK_XY_STAGE = IO_BASE + 352; // 64 bytes (BE X || Y, staging for SEC 1 §2.3.4 emit)
+function ioWipe(mx) {
+    // Zero the entire TS-managed staging region. wipeBuffers covers
+    // MUTABLE_START..BUFFER_END only; the I/O region above lives outside
+    // that range and must be scrubbed by the wrapper.
+    new Uint8Array(mx.memory.buffer).fill(0, IO_BASE, mx.memory.buffer.byteLength);
+}
+function rethrowTrap(err, discriminator, message) {
+    // The WASM module's fault-injection check (sign's pk-mismatch path)
+    // terminates with `unreachable`, which surfaces as
+    // WebAssembly.RuntimeError. Re-throw any such trap as a typed
+    // SigningError so callers can branch on it.
+    if (err instanceof WebAssembly.RuntimeError)
+        throw new SigningError(discriminator, message);
+    throw err;
+}
+/**
+ * Normalise a caller-supplied public key to the 33-byte compressed
+ * SEC 1 §2.3.3 form required by the WASM ABI. 33-byte inputs are
+ * returned as-is; 65-byte inputs (uncompressed, SEC 1 §2.3.4,
+ * 0x04 || x || y) are converted by dropping y and setting the prefix
+ * to 0x02 or 0x03 based on the parity of the y coordinate (LSB of
+ * y[31] in big-endian). Constant-time is not required: pk is public.
+ *
+ * Validation of the prefix byte happens at the WASM layer
+ * (`pointDecompress` rejects anything that is not 0x02 / 0x03 with an
+ * on-curve x), so this helper does not branch on whether the input
+ * was a strict uncompressed (0x04) or hybrid (0x06 / 0x07, SEC 1
+ * §2.3.5) encoding.
+ */
+function normalizePublicKey(pk) {
+    if (pk.length === 33)
+        return pk;
+    // pk has already passed validatePublicKey, so length is 33 or 65.
+    const out = new Uint8Array(33);
+    out[0] = 0x02 | (pk[64] & 0x01);
+    out.set(pk.subarray(1, 33), 1);
+    return out;
+}
+/**
+ * Decompress a 33-byte SEC 1 §2.3.3 compressed P-256 public key to the
+ * 65-byte SEC 1 §2.3.4 uncompressed encoding `0x04 || X || Y`.
+ *
+ * The compressed form encodes only the affine x coordinate plus a
+ * single parity bit (in the prefix byte: 0x02 even-y, 0x03 odd-y).
+ * Recovery of y solves the curve equation
+ * `y² = x³ - 3x + b mod p` (SP 800-186 §3.2.1.3, P-256 has a = -3)
+ * and selects the y root whose parity matches the prefix. The
+ * substrate runs the modular square root inside the p256 WASM
+ * (`feSqrt` via the p ≡ 3 (mod 4) shortcut, x^((p+1)/4)); rejecting
+ * invalid inputs that have no square root or whose recovered (x, y)
+ * lies off-curve.
+ *
+ * Rejection cases (all throw `SigningError('sig-malformed-input')`):
+ *   - prefix byte not in {0x02, 0x03}
+ *   - x coordinate is not the x of any on-curve point (no quadratic
+ *     residue exists for `x³ - 3x + b mod p`)
+ *
+ * Length / shape rejections throw `TypeError` / `RangeError` per the
+ * usual leviathan-crypto contract-violation posture.
+ *
+ * Requires `init({ p256: ... })`. Uses the same p256 module singleton
+ * as `EcdsaP256`; concurrency-safe alongside non-stateful uses (the
+ * `_assertNotOwned` check fires if a stateful instance is holding
+ * the module).
+ *
+ * @param pk33 33-byte compressed pk per SEC 1 §2.3.3
+ * @returns    65-byte uncompressed pk per SEC 1 §2.3.4 (0x04 || X || Y)
+ */
+export function pointDecompress(pk33) {
+    if (!isInitialized('p256'))
+        throw new Error('leviathan-crypto: call init({ p256: ... }) before using pointDecompress');
+    if (!(pk33 instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 compressed public key must be a Uint8Array');
+    if (pk33.length !== 33)
+        throw new RangeError(`leviathan-crypto: ecdsa-p256 compressed public key must be 33 bytes (got ${pk33.length})`);
+    if (pk33[0] !== 0x02 && pk33[0] !== 0x03)
+        throw new SigningError('sig-malformed-input', 'leviathan-crypto: ecdsa-p256 compressed public key prefix must be 0x02 or 0x03 per SEC 1 §2.3.3 '
+            + `(got 0x${pk33[0].toString(16).padStart(2, '0')})`);
+    _assertNotOwned('p256');
+    const mx = getInstance('p256').exports;
+    const mem = new Uint8Array(mx.memory.buffer);
+    mem.set(pk33, PK_STAGE);
+    try {
+        const ok = mx.pointDecompress(POINT_STAGE, PK_STAGE);
+        if (ok !== 1)
+            throw new SigningError('sig-malformed-input', 'leviathan-crypto: ecdsa-p256 compressed public key x coordinate has no on-curve y '
+                + '(point decompression failed per SEC 1 §2.3.4)');
+        // pointDecompress writes (X : Y : Z = 1) in the FE limb form
+        // at POINT_STAGE..+96. feToBytes converts each FE to 32-byte BE
+        // per SP 800-186 §3.2.1.3 coordinate encoding.
+        mx.feToBytes(PK_XY_STAGE, POINT_STAGE); // X (32 BE)
+        mx.feToBytes(PK_XY_STAGE + 32, POINT_STAGE + 32); // Y (32 BE)
+        const out = new Uint8Array(65);
+        out[0] = 0x04;
+        out.set(mem.subarray(PK_XY_STAGE, PK_XY_STAGE + 64), 1);
+        return out;
+    }
+    finally {
+        ioWipe(mx);
+        mx.wipeBuffers();
+    }
+}
+export class EcdsaP256 {
+    constructor() {
+        if (!isInitialized('p256'))
+            throw new Error('leviathan-crypto: call init({ p256: ... }) before using EcdsaP256');
+    }
+    get mx() {
+        return getInstance('p256').exports;
+    }
+    /**
+     * Deterministic ECDSA-P256 key generation from a 32-byte seed.
+     * d = seed mod n per FIPS 186-5 §A.4.2 (testing-candidates style,
+     * single candidate). pk = [d]G compressed to 33 bytes per SEC 1
+     * §2.3.3. The vanishingly rare seed mod n == 0 case traps in the
+     * WASM and surfaces as a SigningError here.
+     *
+     * @param seed 32-byte BE input
+     * @returns 33-byte compressed pk and a fresh 32-byte copy of the
+     *          secret scalar d (sk === seed for this derivation, the
+     *          caller may use either as the private value).
+     */
+    keygenDerand(seed) {
+        _assertNotOwned('p256');
+        validateSeed(seed);
+        const mx = this.mx;
+        const mem = new Uint8Array(mx.memory.buffer);
+        mem.set(seed, SEED_STAGE);
+        try {
+            try {
+                mx.ecdsaKeygen(SEED_STAGE, PK_STAGE);
+            }
+            catch (err) {
+                rethrowTrap(err, 'sig-malformed-input', 'leviathan-crypto: ecdsa-p256 keygen aborted, seed mod n is zero '
+                    + '(2^-256 probability event; supply a different seed)');
+            }
+            const publicKey = mem.slice(PK_STAGE, PK_STAGE + 33);
+            const secretKey = new Uint8Array(32);
+            secretKey.set(seed);
+            return { publicKey, secretKey };
+        }
+        finally {
+            ioWipe(mx);
+            mx.wipeBuffers();
+        }
+    }
+    /** Random ECDSA-P256 key generation, wraps `keygenDerand` with `randomBytes(32)`. */
+    keygen() {
+        const seed = randomBytes(32);
+        try {
+            return this.keygenDerand(seed);
+        }
+        finally {
+            wipe(seed);
+        }
+    }
+    /**
+     * Key generation that returns the public key in the 65-byte SEC 1
+     * §2.3.4 uncompressed encoding `0x04 || X || Y`, rather than the
+     * 33-byte compressed form `keygen` / `keygenDerand` return. The
+     * secret-key half is the same 32-byte raw scalar `d`.
+     *
+     * Internally runs `keygen` (or `keygenDerand` if a seed is supplied)
+     * to obtain the compressed pk, then `pointDecompress` to expand it.
+     * The compressed intermediate is wiped before return.
+     *
+     * @param seed Optional 32-byte seed; passes through to `keygenDerand`
+     *             when present, falls back to `keygen` (CSPRNG seed) when
+     *             omitted.
+     */
+    keygenUncompressed(seed) {
+        const kp = seed === undefined ? this.keygen() : this.keygenDerand(seed);
+        try {
+            const publicKey = pointDecompress(kp.publicKey);
+            return { publicKey, secretKey: kp.secretKey };
+        }
+        catch (err) {
+            wipe(kp.secretKey);
+            throw err;
+        }
+        finally {
+            wipe(kp.publicKey);
+        }
+    }
+    /**
+     * Hedged-or-deterministic ECDSA-P256 sign per FIPS 186-5 §6.4 with
+     * RFC 6979 §3.5 low-S normalisation. The K nonce is derived per
+     * RFC 6979 §3.2 (deterministic) when `rnd` is all-zero, or per
+     * draft-irtf-cfrg-det-sigs-with-noise-05 (hedged) otherwise. The
+     * hedged path is the recommended default; pass `randomBytes(32)`.
+     *
+     * The WASM re-derives pk = [d]G internally and compares it against
+     * the caller-supplied `pk`. A mismatch traps via `unreachable` and
+     * is rethrown as `SigningError('sig-malformed-input')`. This
+     * defends against fault injection that would bias the per-signature
+     * randomness derivation by forcing the caller to also know pk.
+     *
+     * @param sk       32-byte secret scalar d
+     * @param pk       33-byte compressed or 65-byte uncompressed pk;
+     *                 cross-checked by WASM after derivation
+     * @param msgHash  32-byte SHA-256(M) digest (caller-computed)
+     * @param rnd      32-byte per-call entropy Z; all-zero selects
+     *                 deterministic RFC 6979 §3.2, non-zero selects
+     *                 the hedged path
+     * @returns 64-byte raw r || s signature, low-S normalised
+     * @throws  SigningError('sig-malformed-input') on pk-mismatch
+     *          (fault-injection trap)
+     */
+    sign(sk, pk, msgHash, rnd) {
+        _assertNotOwned('p256');
+        validateSecretKey(sk);
+        validatePublicKey(pk);
+        validateMessageHash(msgHash);
+        validateEntropy(rnd);
+        const pkC = normalizePublicKey(pk);
+        const mx = this.mx;
+        const mem = new Uint8Array(mx.memory.buffer);
+        mem.set(sk, SEED_STAGE);
+        mem.set(pkC, PK_STAGE);
+        mem.set(msgHash, MSG_HASH_STAGE);
+        mem.set(rnd, RND_STAGE);
+        try {
+            try {
+                mx.ecdsaSign(SEED_STAGE, PK_STAGE, MSG_HASH_STAGE, RND_STAGE, SIG_STAGE);
+            }
+            catch (err) {
+                rethrowTrap(err, 'sig-malformed-input', 'leviathan-crypto: ecdsa-p256 sign aborted, pk does not match the pk derived from sk '
+                    + '(likely fault injection or caller misuse)');
+            }
+            return mem.slice(SIG_STAGE, SIG_STAGE + 64);
+        }
+        finally {
+            ioWipe(mx);
+            mx.wipeBuffers();
+        }
+    }
+    /**
+     * Suite-only: hedged-or-deterministic sign that derives pk
+     * internally and skips the fault-injection cross-check. See
+     * AGENTS.md "SignatureSuite lifecycle". Underscore-prefixed,
+     * not part of the public API.
+     */
+    _signInternalPk(sk, msgHash, rnd) {
+        _assertNotOwned('p256');
+        validateSecretKey(sk);
+        validateMessageHash(msgHash);
+        validateEntropy(rnd);
+        const mx = this.mx;
+        const mem = new Uint8Array(mx.memory.buffer);
+        mem.set(sk, SEED_STAGE);
+        mem.set(msgHash, MSG_HASH_STAGE);
+        mem.set(rnd, RND_STAGE);
+        try {
+            mx.ecdsaSignInternalPk(SEED_STAGE, MSG_HASH_STAGE, RND_STAGE, SIG_STAGE);
+            return mem.slice(SIG_STAGE, SIG_STAGE + 64);
+        }
+        finally {
+            ioWipe(mx);
+            mx.wipeBuffers();
+        }
+    }
+    /**
+     * Strict ECDSA-P256 verify per FIPS 186-5 §6.5 with low-S
+     * enforcement (RFC 6979 §3.5). Returns `true` on success, `false`
+     * on every signature failure mode: off-curve / identity pk, r or
+     * s out of [1, n-1], high-S, or the signature equation failing.
+     * Throws only on caller-side contract violations (wrong-length
+     * inputs).
+     *
+     * @param pk       33-byte compressed or 65-byte uncompressed pk
+     * @param msgHash  32-byte SHA-256(M) digest
+     * @param sig      64-byte raw r || s (use `ecdsaSignatureFromDer`
+     *                 to convert DER-encoded signatures first)
+     */
+    verify(pk, msgHash, sig) {
+        _assertNotOwned('p256');
+        validatePublicKey(pk);
+        validateMessageHash(msgHash);
+        validateSignature(sig);
+        const pkC = normalizePublicKey(pk);
+        const mx = this.mx;
+        const mem = new Uint8Array(mx.memory.buffer);
+        mem.set(pkC, PK_STAGE);
+        mem.set(msgHash, MSG_HASH_STAGE);
+        mem.set(sig, SIG_STAGE);
+        try {
+            return mx.ecdsaVerify(PK_STAGE, MSG_HASH_STAGE, SIG_STAGE) === 1;
+        }
+        finally {
+            ioWipe(mx);
+            mx.wipeBuffers();
+        }
+    }
+    dispose() {
+        // Idempotent; per-method wipe runs anyway.
+        try {
+            this.mx.wipeBuffers();
+            ioWipe(this.mx);
+        }
+        catch { /* idempotent */ }
+    }
+}

package/dist/ecdsa/types.d.ts

@@ -0,0 +1,31 @@
+export interface EcdsaP256KeyPair {
+    /** 33-byte compressed public key per SEC 1 §2.3.3, 0x02 / 0x03 || x. */
+    publicKey: Uint8Array;
+    /** 32-byte secret scalar d ∈ [1, n-1] per FIPS 186-5 §6.2.1, private-key generation. */
+    secretKey: Uint8Array;
+}
+/**
+ * The ECDSA-P256-relevant subset of the p256 WASM exports.
+ *
+ * The p256 module hosts the full elliptic-curve substrate (field,
+ * scalar, point, RFC 6979 K derivation, embedded SHA-256 + HMAC) and
+ * the four high-level ECDSA entry points (keygen, sign, signInternalPk,
+ * verify). The wrapper additionally drives `pointDecompress` + `feToBytes`
+ * for the SEC 1 §2.3.4 uncompressed-pk emission path; those two
+ * substrate exports are public because no high-level ABI covers
+ * "given a compressed pk, return its uncompressed form" without
+ * round-tripping through verify. Substrate test hooks live outside
+ * the consumer-facing ABI.
+ */
+export interface EcdsaP256Exports {
+    memory: WebAssembly.Memory;
+    getModuleId: () => number;
+    getMemoryPages: () => number;
+    feToBytes: (outOff: number, feOff: number) => void;
+    pointDecompress: (outOff: number, srcOff: number) => number;
+    ecdsaKeygen: (seedOff: number, pkOff: number) => void;
+    ecdsaSign: (skOff: number, pkOff: number, msgHashOff: number, rndOff: number, sigOff: number) => void;
+    ecdsaSignInternalPk: (skOff: number, msgHashOff: number, rndOff: number, sigOff: number) => void;
+    ecdsaVerify: (pkOff: number, msgHashOff: number, sigOff: number) => number;
+    wipeBuffers: () => void;
+}

package/dist/ecdsa/types.js

@@ -0,0 +1,28 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/ecdsa/types.ts
+//
+// ECDSA-P256 type surface: the WASM export interface for the p256
+// module and the public key-pair shape returned by keygen /
+// keygenDerand. FIPS 186-5 §6, ECDSA and SP 800-186 §3.2.1.3, P-256
+// parameters.
+export {};

package/dist/ecdsa/validate.d.ts

@@ -0,0 +1,18 @@
+export declare function validateSeed(seed: Uint8Array): void;
+export declare function validateSecretKey(sk: Uint8Array): void;
+/**
+ * Accepts both 33-byte compressed (SEC 1 §2.3.3, 0x02 / 0x03 || x) and
+ * 65-byte uncompressed (SEC 1 §2.3.4, 0x04 || x || y) inputs. The WASM
+ * ABI consumes only the 33-byte compressed form; the wrapper layer
+ * normalises 65-byte inputs to compressed before staging into WASM
+ * memory (see `normalizePublicKey` in `./index.ts`). Constant-time is
+ * not required at pk import since pk is public material.
+ *
+ * Length-only at this layer; on-curve / canonical-x checks happen in
+ * `pointDecompress` (verify) or via the fault-injection pk-mismatch
+ * trap (sign).
+ */
+export declare function validatePublicKey(pk: Uint8Array): void;
+export declare function validateMessageHash(h: Uint8Array): void;
+export declare function validateSignature(sig: Uint8Array): void;
+export declare function validateEntropy(rnd: Uint8Array): void;

package/dist/ecdsa/validate.js

@@ -0,0 +1,92 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/ecdsa/validate.ts
+//
+// ECDSA-P256 caller-side input validation. Pure length / type checks;
+// curve membership, canonical-encoding rejection, scalar-range checks
+// ([1, n-1] for d, r, s), low-S enforcement, and the fault-injection
+// pk-mismatch trap all live inside the WASM layer.
+//
+// TypeError for non-Uint8Array, RangeError for wrong-length. Matches
+// the ed25519 / mldsa / mlkem validation conventions.
+export function validateSeed(seed) {
+    if (!(seed instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 seed must be a Uint8Array');
+    if (seed.length !== 32)
+        throw new RangeError(`leviathan-crypto: ecdsa-p256 seed must be 32 bytes (got ${seed.length})`);
+}
+export function validateSecretKey(sk) {
+    // 32-byte big-endian scalar d per FIPS 186-5 §6.2.1, private-key
+    // generation. The d ∈ [1, n-1] range check lives in WASM
+    // (scalarIsZero rejection plus scalar arithmetic mod n).
+    if (!(sk instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 secret key must be a Uint8Array');
+    if (sk.length !== 32)
+        throw new RangeError(`leviathan-crypto: ecdsa-p256 secret key must be 32 bytes (got ${sk.length})`);
+}
+/**
+ * Accepts both 33-byte compressed (SEC 1 §2.3.3, 0x02 / 0x03 || x) and
+ * 65-byte uncompressed (SEC 1 §2.3.4, 0x04 || x || y) inputs. The WASM
+ * ABI consumes only the 33-byte compressed form; the wrapper layer
+ * normalises 65-byte inputs to compressed before staging into WASM
+ * memory (see `normalizePublicKey` in `./index.ts`). Constant-time is
+ * not required at pk import since pk is public material.
+ *
+ * Length-only at this layer; on-curve / canonical-x checks happen in
+ * `pointDecompress` (verify) or via the fault-injection pk-mismatch
+ * trap (sign).
+ */
+export function validatePublicKey(pk) {
+    if (!(pk instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 public key must be a Uint8Array');
+    if (pk.length !== 33 && pk.length !== 65)
+        throw new RangeError('leviathan-crypto: ecdsa-p256 public key must be 33 bytes (compressed, SEC 1 §2.3.3) '
+            + `or 65 bytes (uncompressed, SEC 1 §2.3.4) (got ${pk.length})`);
+}
+export function validateMessageHash(h) {
+    // ECDSA-P256 takes a 32-byte SHA-256 digest; the suite layer drives
+    // the actual hashing. FIPS 186-5 §6.4.1 requires hlen = qlen = 256
+    // for P-256 + SHA-256 so the bits2int truncation is a no-op.
+    if (!(h instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 message hash must be a Uint8Array');
+    if (h.length !== 32)
+        throw new RangeError(`leviathan-crypto: ecdsa-p256 message hash must be 32 bytes (got ${h.length})`);
+}
+export function validateSignature(sig) {
+    // Raw r || s wire form, 64 bytes total. DER-wrapped signatures pass
+    // through `ecdsaSignatureFromDer` first; that helper produces a
+    // 64-byte output. The r, s ∈ [1, n-1] and low-S checks happen in
+    // WASM during ecdsaVerify.
+    if (!(sig instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 signature must be a Uint8Array');
+    if (sig.length !== 64)
+        throw new RangeError(`leviathan-crypto: ecdsa-p256 signature must be 64 bytes raw r||s (got ${sig.length})`);
+}
+export function validateEntropy(rnd) {
+    // Per-call entropy Z, 32 bytes. All-zero selects the deterministic
+    // RFC 6979 §3.2 K-derivation path; non-zero selects the hedged
+    // path per draft-irtf-cfrg-det-sigs-with-noise-05.
+    if (!(rnd instanceof Uint8Array))
+        throw new TypeError('leviathan-crypto: ecdsa-p256 entropy must be a Uint8Array');
+    if (rnd.length !== 32)
+        throw new RangeError(`leviathan-crypto: ecdsa-p256 entropy must be 32 bytes (got ${rnd.length})`);
+}

package/dist/ed25519/embedded.d.ts

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

package/dist/ed25519/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/ed25519/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 ed25519Wasm, } from '../embedded/curve25519.js';

package/dist/ed25519/index.d.ts

@@ -0,0 +1,70 @@
+import { isInitialized } from '../init.js';
+import type { WasmSource } from '../wasm-source.js';
+import type { Ed25519KeyPair } from './types.js';
+/**
+ * Initialise the curve25519 WASM module under the `ed25519` alias.
+ * Equivalent to `x25519Init(source)`; both target the same WASM module
+ * and the init layer de-dupes when given identical sources.
+ */
+export declare function ed25519Init(source: WasmSource): Promise<void>;
+export type { WasmSource };
+export type { Ed25519KeyPair, Ed25519Exports } from './types.js';
+export { isInitialized };
+export declare class Ed25519 {
+    constructor();
+    private get mx();
+    /**
+     * Deterministic Ed25519 key generation, RFC 8032 §5.1.5.
+     * @param seed 32-byte secret seed
+     * @returns 32-byte verifying key and a fresh 32-byte secret-key copy
+     *          of the supplied seed (the spec defines sk = seed).
+     */
+    keygenDerand(seed: Uint8Array): Ed25519KeyPair;
+    /** Random Ed25519 key generation, wraps `keygenDerand` with `randomBytes(32)`. */
+    keygen(): Ed25519KeyPair;
+    /**
+     * Pure Ed25519 sign, RFC 8032 §5.1.6.
+     *
+     * The WASM re-derives pk from `sk` internally and compares it against
+     * the caller-supplied `pk`; a mismatch traps via `unreachable` and is
+     * rethrown as `SigningError('sig-ed25519-pk-mismatch')`. This defends
+     * against fault injection that bias the per-signature randomness
+     * derivation by forcing the caller to also know pk.
+     */
+    sign(sk: Uint8Array, pk: Uint8Array, M: Uint8Array): Uint8Array;
+    /**
+     * Ed25519ph sign, RFC 8032 §5.1.7 (prehash, dom2 phflag=1).
+     *
+     * Caller supplies the 64-byte SHA-512(M) digest; the library does not
+     * compute it. Same pk-mismatch fault-injection trap as `sign`.
+     */
+    signPrehashed(sk: Uint8Array, pk: Uint8Array, digest: Uint8Array, ctx: Uint8Array): Uint8Array;
+    /**
+     * Suite-only: pure Ed25519 sign that derives pk internally and
+     * skips the fault-injection cross-check. See AGENTS.md
+     * "SignatureSuite lifecycle". Underscore-prefixed, not part of
+     * the public API.
+     */
+    _signInternalPk(sk: Uint8Array, M: Uint8Array): Uint8Array;
+    /**
+     * Suite-only: Ed25519ph mirror of `_signInternalPk`. See
+     * AGENTS.md "SignatureSuite lifecycle".
+     */
+    _signPrehashedInternalPk(sk: Uint8Array, digest: Uint8Array, ctx: Uint8Array): Uint8Array;
+    /**
+     * Strict pure Ed25519 verify, RFC 8032 §5.1.7 / FIPS 186-5 §7.6.4.
+     *
+     * Returns `true` on success, `false` on every signature failure mode:
+     * off-curve pk, non-canonical R, non-canonical S (>= L), small-order
+     * pk, or signature equation inequality. Throws only on caller-side
+     * contract violations (wrong-length pk / M / sig).
+     */
+    verify(pk: Uint8Array, M: Uint8Array, sig: Uint8Array): boolean;
+    /**
+     * Strict Ed25519ph verify, RFC 8032 §5.1.7 prehash. Same rejection
+     * conditions as {@link verify} plus the dom2(F=1, ctx) prefix on the
+     * per-spec SHA-512 inputs (handled inside the WASM).
+     */
+    verifyPrehashed(pk: Uint8Array, digest: Uint8Array, ctx: Uint8Array, sig: Uint8Array): boolean;
+    dispose(): void;
+}