leviathan-crypto 2.0.1 → 3.0.0

package/dist/sign/sign-stream.d.ts

@@ -0,0 +1,25 @@
+import type { StreamableSignatureSuite } from './types.js';
+export declare class SignStream {
+    private readonly suite;
+    private readonly sk;
+    private readonly ctx;
+    private hasher;
+    private finalized;
+    private disposed;
+    constructor(suite: StreamableSignatureSuite, sk: Uint8Array, ctx: Uint8Array);
+    /**
+     * Build the wire-format preamble for `payloadLength`. Available at
+     * any point in the stream lifecycle. See
+     * docs/signing.md#attached-envelope.
+     */
+    buildPreamble(payloadLength: number): Uint8Array;
+    /** Feed a chunk to the running prehash. */
+    update(chunk: Uint8Array): void;
+    /**
+     * Finalize the running prehash and sign. Returns the signature bytes.
+     * Caller writes these as the last segment of the output stream.
+     */
+    finalize(): Uint8Array;
+    /** Wipe lib-owned state. Idempotent. */
+    dispose(): void;
+}

package/dist/sign/sign-stream.js

@@ -0,0 +1,112 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/sign/sign-stream.ts
+//
+// SignStream class, streaming signature production for StreamableSignatureSuite.
+// Sender writes: preamble + payload bytes + sig (from finalize). Wire format
+// is identical to Sign.sign output.
+import { SigningError } from '../errors.js';
+import { wipe } from '../utils.js';
+import { USER_CTX_MAX } from './ctx.js';
+import { createRunningHash } from './hasher.js';
+export class SignStream {
+    suite;
+    sk;
+    ctx;
+    hasher;
+    finalized = false;
+    disposed = false;
+    constructor(suite, sk, ctx) {
+        this.suite = suite;
+        this.sk = sk;
+        if (ctx.length > USER_CTX_MAX)
+            throw new SigningError('sig-ctx-too-long', `user_ctx length ${ctx.length} > ${USER_CTX_MAX}`);
+        // Copy ctx so a later caller-side mutation cannot retroactively
+        // change the bytes the preamble emits.
+        this.ctx = new Uint8Array(ctx);
+        this.hasher = createRunningHash(suite.prehashAlgorithm);
+    }
+    /**
+     * Build the wire-format preamble for `payloadLength`. Available at
+     * any point in the stream lifecycle. See
+     * docs/signing.md#attached-envelope.
+     */
+    buildPreamble(payloadLength) {
+        if (!Number.isInteger(payloadLength) || payloadLength < 0)
+            throw new SigningError('sig-malformed-input', `payloadLength must be a non-negative integer, got ${payloadLength}`);
+        if (payloadLength > 0xFFFFFFFF)
+            throw new SigningError('sig-malformed-input', `payloadLength ${payloadLength} > 2^32 - 1 (wire format payload_len is u32)`);
+        const out = new Uint8Array(2 + this.ctx.length + 4);
+        let pos = 0;
+        out[pos++] = this.suite.formatEnum;
+        out[pos++] = this.ctx.length;
+        out.set(this.ctx, pos);
+        pos += this.ctx.length;
+        out[pos++] = (payloadLength >>> 24) & 0xFF;
+        out[pos++] = (payloadLength >>> 16) & 0xFF;
+        out[pos++] = (payloadLength >>> 8) & 0xFF;
+        out[pos] = payloadLength & 0xFF;
+        return out;
+    }
+    /** Feed a chunk to the running prehash. */
+    update(chunk) {
+        if (this.disposed)
+            throw new SigningError('sig-stream-disposed');
+        if (this.finalized)
+            throw new SigningError('sig-stream-finalized');
+        this.hasher.update(chunk);
+    }
+    /**
+     * Finalize the running prehash and sign. Returns the signature bytes.
+     * Caller writes these as the last segment of the output stream.
+     */
+    finalize() {
+        if (this.disposed)
+            throw new SigningError('sig-stream-disposed');
+        if (this.finalized)
+            throw new SigningError('sig-stream-finalized');
+        this.finalized = true;
+        const h = this.hasher;
+        let digest;
+        try {
+            digest = h.finalize();
+            return this.suite.signPrehashed(this.sk, digest, this.ctx);
+        }
+        finally {
+            if (digest !== undefined)
+                wipe(digest);
+            h.dispose();
+            this.hasher = undefined;
+        }
+    }
+    /** Wipe lib-owned state. Idempotent. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.hasher !== undefined) {
+            this.hasher.dispose();
+            this.hasher = undefined;
+        }
+        wipe(this.ctx);
+    }
+}

package/dist/sign/suites/ecdsa-p256.d.ts

@@ -0,0 +1,2 @@
+import type { StreamableSignatureSuite } from '../types.js';
+export declare const EcdsaP256Suite: StreamableSignatureSuite;

package/dist/sign/suites/ecdsa-p256.js

@@ -0,0 +1,120 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/sign/suites/ecdsa-p256.ts
+//
+// EcdsaP256Suite (0x02, FIPS 186-5 §6.4 over SHA-256). Hedged-by-default
+// per draft-irtf-cfrg-det-sigs-with-noise-05.
+//
+// Catalog + sizes: docs/signaturesuite.md. Suite reference: docs/ecdsa-p256.md.
+import { SigningError } from '../../errors.js';
+import { EcdsaP256 } from '../../ecdsa/index.js';
+import { randomBytes, utf8ToBytes, wipe } from '../../utils.js';
+import { CTX_DOMAIN_MAX } from '../ctx.js';
+import { sha256OneShot } from '../hasher.js';
+function EcdsaP256SuiteFactory(formatEnum, formatName, ctxDomain) {
+    if (utf8ToBytes(ctxDomain).length > CTX_DOMAIN_MAX)
+        throw new Error(`leviathan-crypto: ctxDomain '${ctxDomain}' too long for ${formatName}`);
+    const wasmModules = Object.freeze(['p256', 'sha2']);
+    const prehashAlgorithm = 'sha-256';
+    const prehashSize = 32;
+    function rejectCtx(ctx) {
+        if (ctx.length > 0)
+            throw new SigningError('sig-ctx-unsupported', `${formatName} does not support user context; ECDSA-P256 has `
+                + 'no native ctx parameter in FIPS 186-5 §6.4. Use the '
+                + 'classical+PQ hybrid suites (catalog 0x22 / 0x23) for '
+                + 'context-bound ECDSA-P256 signatures.');
+    }
+    return {
+        formatEnum,
+        formatName,
+        ctxDomain,
+        pkSize: 33,
+        skSize: 32,
+        sigMaxSize: 64,
+        wasmModules,
+        prehashAlgorithm,
+        prehashSize,
+        sign(sk, msg, ctx) {
+            rejectCtx(ctx);
+            const digest = sha256OneShot(msg);
+            const rnd = randomBytes(32);
+            const inst = new EcdsaP256();
+            try {
+                return inst._signInternalPk(sk, digest, rnd);
+            }
+            finally {
+                wipe(rnd);
+                wipe(digest);
+                inst.dispose();
+            }
+        },
+        verify(pk, msg, sig, ctx) {
+            rejectCtx(ctx);
+            const digest = sha256OneShot(msg);
+            const inst = new EcdsaP256();
+            try {
+                return inst.verify(pk, digest, sig);
+            }
+            finally {
+                inst.dispose();
+                wipe(digest);
+            }
+        },
+        keygen() {
+            const inst = new EcdsaP256();
+            try {
+                const kp = inst.keygen();
+                return { pk: kp.publicKey, sk: kp.secretKey };
+            }
+            finally {
+                inst.dispose();
+            }
+        },
+        signPrehashed(sk, digest, ctx) {
+            rejectCtx(ctx);
+            if (digest.length !== prehashSize)
+                throw new SigningError('sig-malformed-input', `digest length ${digest.length} != expected ${prehashSize} for ${formatName}`);
+            const rnd = randomBytes(32);
+            const inst = new EcdsaP256();
+            try {
+                return inst._signInternalPk(sk, digest, rnd);
+            }
+            finally {
+                wipe(rnd);
+                inst.dispose();
+            }
+        },
+        verifyPrehashed(pk, digest, sig, ctx) {
+            rejectCtx(ctx);
+            if (digest.length !== prehashSize)
+                throw new SigningError('sig-malformed-input', `digest length ${digest.length} != expected ${prehashSize} for ${formatName}`);
+            const inst = new EcdsaP256();
+            try {
+                return inst.verify(pk, digest, sig);
+            }
+            finally {
+                inst.dispose();
+            }
+        },
+    };
+}
+export const EcdsaP256Suite = EcdsaP256SuiteFactory(0x02, 'ecdsa-p256', 'ecdsa-p256-envelope-v3');

package/dist/sign/suites/ed25519.d.ts

@@ -0,0 +1,3 @@
+import type { SignatureSuite, StreamableSignatureSuite } from '../types.js';
+export declare const Ed25519Suite: SignatureSuite;
+export declare const Ed25519PreHashSuite: StreamableSignatureSuite;

package/dist/sign/suites/ed25519.js

@@ -0,0 +1,165 @@
+//                  ▄▄▄▄▄▄▄▄▄▄
+//           ▄████████████████████▄▄          ▒  ▄▀▀ ▒ ▒ █ ▄▀▄ ▀█▀ █ ▒ ▄▀▄ █▀▄
+//        ▄██████████████████████ ▀████▄      ▓  ▓▀  ▓ ▓ ▓ ▓▄▓  ▓  ▓▀▓ ▓▄▓ ▓ ▓
+//      ▄█████████▀▀▀     ▀███████▄▄███████▌  ▀▄ ▀▄▄ ▀▄▀ ▒ ▒ ▒  ▒  ▒ █ ▒ ▒ ▒ █
+//     ▐████████▀   ▄▄▄▄     ▀████████▀██▀█▌
+//     ████████      ███▀▀     ████▀  █▀ █▀       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/sign/suites/ed25519.ts
+//
+// Ed25519Suite (0x01, RFC 8032 §5.1.6) and Ed25519PreHashSuite
+// (0x11, Ed25519ph, RFC 8032 §5.1.7).
+//
+// Catalog + sizes: docs/signaturesuite.md. Suite reference: docs/ed25519.md.
+import { utf8ToBytes, wipe } from '../../utils.js';
+import { SigningError } from '../../errors.js';
+import { Ed25519 } from '../../ed25519/index.js';
+import { buildEffectiveCtx, CTX_DOMAIN_MAX, } from '../ctx.js';
+import { sha512OneShot } from '../hasher.js';
+// ── Pure-mode factory ───────────────────────────────────────────────────────
+function Ed25519PureSuite(formatEnum, formatName, ctxDomain) {
+    if (utf8ToBytes(ctxDomain).length > CTX_DOMAIN_MAX)
+        throw new Error(`leviathan-crypto: ctxDomain '${ctxDomain}' too long for ${formatName}`);
+    const wasmModules = Object.freeze(['curve25519']);
+    return {
+        formatEnum,
+        formatName,
+        ctxDomain,
+        pkSize: 32,
+        skSize: 32,
+        sigMaxSize: 64,
+        wasmModules,
+        sign(sk, msg, ctx) {
+            if (ctx.length > 0)
+                throw new SigningError('sig-ctx-unsupported', `${formatName} (pure Ed25519) does not support user context; `
+                    + 'use Ed25519PreHashSuite (formatEnum 0x11) for context-bound signatures');
+            const inst = new Ed25519();
+            try {
+                return inst._signInternalPk(sk, msg);
+            }
+            finally {
+                inst.dispose();
+            }
+        },
+        verify(pk, msg, sig, ctx) {
+            if (ctx.length > 0)
+                throw new SigningError('sig-ctx-unsupported', `${formatName} (pure Ed25519) does not support user context; `
+                    + 'use Ed25519PreHashSuite (formatEnum 0x11) for context-bound signatures');
+            const inst = new Ed25519();
+            try {
+                return inst.verify(pk, msg, sig);
+            }
+            finally {
+                inst.dispose();
+            }
+        },
+        keygen() {
+            const inst = new Ed25519();
+            try {
+                const kp = inst.keygen();
+                return { pk: kp.publicKey, sk: kp.secretKey };
+            }
+            finally {
+                inst.dispose();
+            }
+        },
+    };
+}
+// ── Prehash-mode factory ────────────────────────────────────────────────────
+function Ed25519PrehashSuite(formatEnum, formatName, ctxDomain) {
+    if (utf8ToBytes(ctxDomain).length > CTX_DOMAIN_MAX)
+        throw new Error(`leviathan-crypto: ctxDomain '${ctxDomain}' too long for ${formatName}`);
+    const wasmModules = Object.freeze(['curve25519', 'sha2']);
+    const prehashAlgorithm = 'sha-512';
+    const prehashSize = 64;
+    return {
+        formatEnum,
+        formatName,
+        ctxDomain,
+        pkSize: 32,
+        skSize: 32,
+        sigMaxSize: 64,
+        wasmModules,
+        prehashAlgorithm,
+        prehashSize,
+        sign(sk, msg, ctx) {
+            const effectiveCtx = buildEffectiveCtx(ctxDomain, ctx);
+            const digest = sha512OneShot(msg);
+            const inst = new Ed25519();
+            try {
+                return inst._signPrehashedInternalPk(sk, digest, effectiveCtx);
+            }
+            finally {
+                inst.dispose();
+                wipe(digest);
+                wipe(effectiveCtx);
+            }
+        },
+        verify(pk, msg, sig, ctx) {
+            const effectiveCtx = buildEffectiveCtx(ctxDomain, ctx);
+            const digest = sha512OneShot(msg);
+            const inst = new Ed25519();
+            try {
+                return inst.verifyPrehashed(pk, digest, effectiveCtx, sig);
+            }
+            finally {
+                inst.dispose();
+                wipe(digest);
+                wipe(effectiveCtx);
+            }
+        },
+        keygen() {
+            const inst = new Ed25519();
+            try {
+                const kp = inst.keygen();
+                return { pk: kp.publicKey, sk: kp.secretKey };
+            }
+            finally {
+                inst.dispose();
+            }
+        },
+        signPrehashed(sk, digest, ctx) {
+            if (digest.length !== prehashSize)
+                throw new SigningError('sig-malformed-input', `digest length ${digest.length} != expected ${prehashSize} for ${formatName}`);
+            const effectiveCtx = buildEffectiveCtx(ctxDomain, ctx);
+            const inst = new Ed25519();
+            try {
+                return inst._signPrehashedInternalPk(sk, digest, effectiveCtx);
+            }
+            finally {
+                inst.dispose();
+                wipe(effectiveCtx);
+            }
+        },
+        verifyPrehashed(pk, digest, sig, ctx) {
+            if (digest.length !== prehashSize)
+                throw new SigningError('sig-malformed-input', `digest length ${digest.length} != expected ${prehashSize} for ${formatName}`);
+            const effectiveCtx = buildEffectiveCtx(ctxDomain, ctx);
+            const inst = new Ed25519();
+            try {
+                return inst.verifyPrehashed(pk, digest, effectiveCtx, sig);
+            }
+            finally {
+                inst.dispose();
+                wipe(effectiveCtx);
+            }
+        },
+    };
+}
+// ── Exported suite consts ───────────────────────────────────────────────────
+export const Ed25519Suite = Ed25519PureSuite(0x01, 'ed25519', 'ed25519-envelope-v3');
+export const Ed25519PreHashSuite = Ed25519PrehashSuite(0x11, 'ed25519-prehash', 'ed25519-prehash-envelope-v3');

package/dist/sign/suites/hybrid-classical.d.ts

@@ -0,0 +1,23 @@
+import type { StreamableSignatureSuite } from '../types.js';
+/**
+ * Composite ML-DSA-44 + Ed25519 with SHA-512 prehash.
+ * composite-sigs §6, id-MLDSA44-Ed25519-SHA512 (OID 1.3.6.1.5.5.7.6.39).
+ */
+export declare const MlDsa44Ed25519Suite: StreamableSignatureSuite;
+/**
+ * Composite ML-DSA-65 + Ed25519 with SHA-512 prehash.
+ * composite-sigs §6, id-MLDSA65-Ed25519-SHA512 (OID 1.3.6.1.5.5.7.6.48).
+ */
+export declare const MlDsa65Ed25519Suite: StreamableSignatureSuite;
+/**
+ * Composite ML-DSA-44 + ECDSA-P256 with SHA-256 prehash.
+ * composite-sigs §6, id-MLDSA44-ECDSA-P256-SHA256 (OID 1.3.6.1.5.5.7.6.40).
+ */
+export declare const MlDsa44EcdsaP256Suite: StreamableSignatureSuite;
+/**
+ * Composite ML-DSA-65 + ECDSA-P256 with SHA-512 prehash on the composite
+ * layer; the ECDSA half still hashes M' with SHA-256 per composite-sigs §6
+ * `ecdsa-with-SHA256` and §10.1 (deployment-fit rationale).
+ * composite-sigs §6, id-MLDSA65-ECDSA-P256-SHA512 (OID 1.3.6.1.5.5.7.6.45).
+ */
+export declare const MlDsa65EcdsaP256Suite: StreamableSignatureSuite;