@noble/post-quantum 0.6.1 → 0.7.1

package/hybrid.js

@@ -79,15 +79,38 @@ import {} from '@noble/curves/abstract/montgomery.js';
 import {} from '@noble/curves/abstract/weierstrass.js';
 import { x25519 } from '@noble/curves/ed25519.js';
 import { p256, p384 } from '@noble/curves/nist.js';
-import { asciiToBytes, bytesToNumberBE, bytesToNumberLE, concatBytes, numberToBytesBE, } from '@noble/curves/utils.js';
+import { abool, afunction, asciiToBytes, bytesToNumberBE, bytesToNumberLE, concatBytes, numberToBytesBE, } from '@noble/curves/utils.js';
 import { expand, extract } from '@noble/hashes/hkdf.js';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { sha3_256, shake256 } from '@noble/hashes/sha3.js';
-import { abytes, ahash, anumber } from '@noble/hashes/utils.js';
+import { abytes, ahash, anumber, isBytes } from '@noble/hashes/utils.js';
 import { ml_kem1024, ml_kem768 } from "./ml-kem.js";
-import { cleanBytes, copyBytes, randomBytes, splitCoder, validateSigOpts, validateVerOpts, } from "./utils.js";
+import { aobject, astring, cleanBytes, copyBytes, randomBytes, splitCoder, validateSigOpts, validateVerOpts, } from "./utils.js";
+const validateKEM = (kem, title) => {
+    const k = aobject(kem, title);
+    aobject(k.lengths, `${title}.lengths`);
+    afunction(k.keygen, `${title}.keygen`);
+    afunction(k.getPublicKey, `${title}.getPublicKey`);
+    afunction(k.encapsulate, `${title}.encapsulate`);
+    afunction(k.decapsulate, `${title}.decapsulate`);
+    return k;
+};
+const validateSigner = (signer, title) => {
+    const s = aobject(signer, title);
+    aobject(s.lengths, `${title}.lengths`);
+    afunction(s.keygen, `${title}.keygen`);
+    afunction(s.getPublicKey, `${title}.getPublicKey`);
+    afunction(s.sign, `${title}.sign`);
+    afunction(s.verify, `${title}.verify`);
+    return s;
+};
 // Can re-use if decide to signatures support, on other hand getSecretKey is specific and ugly
 function ecKeygen(curve, allowZeroKey = false) {
+    const c = aobject(curve, 'curve');
+    aobject(c.lengths, 'curve.lengths');
+    afunction(c.keygen, 'curve.keygen');
+    afunction(c.getPublicKey, 'curve.getPublicKey');
+    abool(allowZeroKey, 'allowZeroKey');
     const lengths = curve.lengths;
     let keygen = curve.keygen;
     if (allowZeroKey) {
@@ -125,6 +148,12 @@ function ecKeygen(curve, allowZeroKey = false) {
 /**
  * Wraps an ECDH-capable curve as a KEM.
  * Shared secrets stay in the wrapped curve's raw ECDH byte format with no built-in KDF.
+ *
+ * SECURITY: this is a low-level component adapter, not a standalone IND-CCA-secure KEM. It does
+ * not bind the encapsulation or recipient public key into the secret, so distinct accepted point
+ * encodings can produce the same output. Use it only inside a construction whose specified
+ * combiner binds those values, or use a standardized DHKEM with labeled extract-and-expand.
+ *
  * On SEC 1 / Weierstrass curves, that means the compressed shared-point body without the
  * 1-byte `0x02` / `0x03` prefix.
  * The X25519 path also leaves RFC 7748's optional all-zero shared-secret check to callers.
@@ -140,15 +169,20 @@ function ecKeygen(curve, allowZeroKey = false) {
  * Wrap an ECDH-capable curve as a generic KEM.
  * ```ts
  * import { x25519 } from '@noble/curves/ed25519.js';
- * import { ecdhKem } from '@noble/post-quantum/hybrid.js';
- * const kem = ecdhKem(x25519);
+ * import { _ecdhKem } from '@noble/post-quantum/hybrid.js';
+ * const kem = _ecdhKem(x25519);
  * const publicKeyLen = kem.lengths.publicKey;
  * ```
  */
-export function ecdhKem(curve, allowZeroKey = false) {
+export function _ecdhKem(curve, allowZeroKey = false) {
     const kg = ecKeygen(curve, allowZeroKey);
     if (!curve.getSharedSecret)
         throw new Error('wrong curve'); // ed25519 doesn't have one!
+    // Standalone (not `this.decapsulate`) so encapsulate works even when methods are destructured.
+    const decapsulate = (cipherText, secretKey) => {
+        const res = curve.getSharedSecret(secretKey, cipherText);
+        return (curve.lengths.publicKeyHasPrefix ? res.subarray(1) : res);
+    };
     return {
         lengths: { ...kg.lengths, msg: kg.lengths.seed, cipherText: kg.lengths.publicKey },
         keygen: kg.keygen,
@@ -159,8 +193,8 @@ export function ecdhKem(curve, allowZeroKey = false) {
             const seed = copyBytes(rand);
             let ek = undefined;
             try {
-                ek = this.keygen(seed).secretKey;
-                const sharedSecret = this.decapsulate(publicKey, ek);
+                ek = kg.keygen(seed).secretKey;
+                const sharedSecret = decapsulate(publicKey, ek);
                 const cipherText = curve.getPublicKey(ek);
                 return { sharedSecret, cipherText };
             }
@@ -172,10 +206,7 @@ export function ecdhKem(curve, allowZeroKey = false) {
                     cleanBytes(ek);
             }
         },
-        decapsulate(cipherText, secretKey) {
-            const res = curve.getSharedSecret(secretKey, cipherText);
-            return (curve.lengths.publicKeyHasPrefix ? res.subarray(1) : res);
-        },
+        decapsulate,
     };
 }
 /**
@@ -208,7 +239,7 @@ export function ecSigner(curve, allowZeroKey = false) {
         keygen: kg.keygen,
         getPublicKey: kg.getPublicKey,
         sign: (message, secretKey, opts = {}) => {
-            validateSigOpts(opts);
+            opts = validateSigOpts(opts);
             // This generic wrapper intentionally keeps the Signer contract to message + key only.
             // Backend-specific knobs like ECDSA extraEntropy or Ed25519ctx context cannot be forwarded
             // uniformly through combineSigners(), so callers that need them must use the curve directly.
@@ -223,20 +254,28 @@ export function ecSigner(curve, allowZeroKey = false) {
          * generic opts and lets wrapped-curve malformed-input errors escape unchanged.
          */
         verify: (signature, message, publicKey, opts = {}) => {
-            validateVerOpts(opts);
+            opts = validateVerOpts(opts);
             if (opts.context !== undefined)
                 throw new Error('ecSigner does not support context; use the underlying curve directly');
             return curve.verify(signature, message, publicKey);
         },
     };
 }
+function positiveLength(value, title) {
+    const length = anumber(value, title);
+    if (length === 0)
+        throw new RangeError(`"${title}" expected integer greater than 0, got 0`);
+    return length;
+}
 function splitLengths(lst, name) {
     // Preserve caller order exactly; raw numeric fields still decode as splitCoder() subarray views.
-    return splitCoder(name, ...lst.map((i) => {
+    const coder = splitCoder(name, ...lst.map((i) => {
         if (typeof i.lengths[name] !== 'number')
             throw new Error('wrong length: ' + name);
-        return i.lengths[name];
+        return positiveLength(i.lengths[name], name);
     }));
+    positiveLength(coder.bytesLen, name);
+    return coder;
 }
 // It is XOF for most cases, but can be more complex!
 /**
@@ -265,11 +304,9 @@ expandSeed_, ...ck_) {
     const seedCoder = splitLengths(ck, 'seed');
     const pkCoder = splitLengths(ck, 'publicKey');
     // Allows to use identity functions for combiner/expandSeed
-    if (realSeedLen === undefined)
-        realSeedLen = seedCoder.bytesLen;
-    anumber(realSeedLen);
+    const rootSeedLen = positiveLength(realSeedLen === undefined ? seedCoder.bytesLen : realSeedLen, 'realSeedLen');
     function expandDecapsulationKey(seed) {
-        abytes(seed, realSeedLen);
+        abytes(seed, rootSeedLen);
         const expandedRaw = expandSeed(seed, seedCoder.bytesLen);
         // Identity/subarray expanders can hand back caller-owned seed storage. Detach those outputs so
         // later cleanup can wipe the expanded schedule without mutating the caller's root seed bytes.
@@ -303,39 +340,62 @@ expandSeed_, ...ck_) {
                 cleanBytes(secretKey);
         }
     }
-    return {
-        info: { lengths: { seed: realSeedLen, publicKey: pkCoder.bytesLen, secretKey: realSeedLen } },
-        getPublicKey(secretKey) {
-            // Composite secret keys are root seeds, so public-key derivation reruns key expansion from
-            // that seed instead of decoding a packed child-secret-key structure.
-            return this.keygen(secretKey).publicKey;
-        },
-        keygen(seed = randomBytes(realSeedLen)) {
-            const { publicKey: pk, secretKey } = expandDecapsulationKey(seed);
+    // Standalone (not a method) so getPublicKey / destructured usage never depends on `this`.
+    const keygen = (seed) => {
+        // Detach the root: the exported secretKey must not alias caller-owned seed bytes, so later
+        // caller mutation of the seed cannot silently change the secret key (and vice versa).
+        const root = seed === undefined ? randomBytes(rootSeedLen) : copyBytes(seed);
+        let res;
+        try {
+            const { publicKey: pk, secretKey } = expandDecapsulationKey(root);
             try {
-                const publicKey = pkCoder.encode(pk);
-                return { secretKey: seed, publicKey };
+                res = {
+                    secretKey: root,
+                    publicKey: pkCoder.encode(pk),
+                };
             }
             finally {
-                cleanBytes(pk);
-                // The exported secretKey is the caller/root seed itself; child secret keys are internal
+                // The exported secretKey is the (detached) root seed; child secret keys are internal
                 // expansion outputs that are cleaned whether encoding succeeds or throws.
-                cleanBytes(secretKey);
+                cleanBytes(pk, secretKey);
             }
+            return res;
+        }
+        finally {
+            if (!res)
+                cleanBytes(root);
+        }
+    };
+    return {
+        info: { lengths: { seed: rootSeedLen, publicKey: pkCoder.bytesLen, secretKey: rootSeedLen } },
+        // Composite secret keys are root seeds, so public-key derivation reruns key expansion from
+        // that seed instead of decoding a packed child-secret-key structure.
+        getPublicKey: (secretKey) => {
+            const keys = keygen(secretKey);
+            // keygen detaches its exported root; getPublicKey discards that half of the result.
+            cleanBytes(keys.secretKey);
+            return keys.publicKey;
         },
+        keygen,
         expandDecapsulationKey,
-        realSeedLen,
+        realSeedLen: rootSeedLen,
     };
 }
 // This generic function that combines multiple KEMs into single one
 /**
  * Combines multiple KEMs into one composite KEM.
- * @param realSeedLen - Input seed length expected by `expandSeed`.
- * @param realMsgLen - Shared-secret length returned by `combiner`.
+ * @param realSeedLen - Positive input seed length expected by `expandSeed`, or `undefined` to use
+ * the sum of component seed lengths. Callers remain responsible for choosing a security-appropriate
+ * size.
+ * @param realMsgLen - Positive shared-secret length returned by `combiner`, or `undefined` to use
+ * the sum of component message lengths.
  * @param expandSeed - Seed expander used to derive per-KEM seeds.
  * @param combiner - Combines the per-KEM outputs into one shared secret.
- * @param kems - KEM implementations to combine.
+ * @param kems - At least one KEM implementation. A construction advertised as hybrid normally
+ * supplies two or more.
  * @returns Composite KEM.
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws If there are no components or any required length resolves to zero. {@link RangeError}
  * @example
  * Combine multiple KEMs into one composite KEM.
  * ```ts
@@ -356,21 +416,53 @@ expandSeed_, ...ck_) {
 export function combineKEMS(realSeedLen, // how much bytes expandSeed expects
 realMsgLen, // how much bytes combiner returns
 expandSeed, combiner, ...kems) {
+    if (realSeedLen !== undefined)
+        positiveLength(realSeedLen, 'realSeedLen');
+    if (realMsgLen !== undefined)
+        positiveLength(realMsgLen, 'realMsgLen');
+    if (typeof expandSeed !== 'function')
+        throw new TypeError('"expandSeed" expected function, got type=' + typeof expandSeed);
+    if (typeof combiner !== 'function')
+        throw new TypeError('"combiner" expected function, got type=' + typeof combiner);
     const rawCombiner = combiner;
     const rawKems = kems;
+    if (rawKems.length === 0)
+        throw new RangeError('combineKEMS requires at least one KEM');
+    for (let i = 0; i < rawKems.length; i++)
+        validateKEM(rawKems[i], `kems[${i}]`);
     const keys = combineKeys(realSeedLen, expandSeed, ...rawKems);
     const ctCoder = splitLengths(rawKems, 'cipherText');
     const pkCoder = splitLengths(rawKems, 'publicKey');
     const msgCoder = splitLengths(rawKems, 'msg');
-    if (realMsgLen === undefined)
-        realMsgLen = msgCoder.bytesLen;
-    anumber(realMsgLen);
+    const sharedSecretLen = positiveLength(realMsgLen === undefined ? msgCoder.bytesLen : realMsgLen, 'realMsgLen');
     const lengths = Object.freeze({
         ...keys.info.lengths,
-        msg: realMsgLen,
+        msg: sharedSecretLen,
         msgRand: msgCoder.bytesLen,
         cipherText: ctCoder.bytesLen,
     });
+    const combine = (publicKeys, cipherTexts, sharedSecrets) => {
+        const combined = rawCombiner(publicKeys, cipherTexts, sharedSecrets);
+        try {
+            return copyBytes(abytes(combined, sharedSecretLen, 'sharedSecret'));
+        }
+        catch (error) {
+            if (isBytes(combined)) {
+                // A combiner may return any callback argument. Public keys during encapsulation and
+                // ciphertexts during decapsulation are views into caller-owned inputs, so wipe an invalid
+                // byte result only when its range does not overlap either public argument vector. Child
+                // shared-secret aliases are already wiped by the operation's outer finally block.
+                const overlaps = (value) => combined.buffer === value.buffer &&
+                    combined.byteOffset < value.byteOffset + value.byteLength &&
+                    value.byteOffset < combined.byteOffset + combined.byteLength;
+                const aliasesPublicInput = publicKeys.some(overlaps) ||
+                    cipherTexts.some(overlaps);
+                if (!aliasesPublicInput)
+                    cleanBytes(combined);
+            }
+            throw error;
+        }
+    };
     return Object.freeze({
         lengths,
         getPublicKey: keys.getPublicKey,
@@ -386,11 +478,14 @@ expandSeed, combiner, ...kems) {
                     sharedSecret.push(enc.sharedSecret);
                     cipherText.push(enc.cipherText);
                 }
+                // Validate and detach public ciphertexts before deriving a final secret from them. This
+                // also ensures a malformed child cannot make us allocate and then strand a combined key.
+                const encodedCipherText = ctCoder.encode(cipherText);
                 return {
                     // Detach the combiner result before cleanup: a caller-provided combiner may alias one of
                     // the child sharedSecret buffers, and those child buffers are zeroized immediately below.
-                    sharedSecret: copyBytes(rawCombiner(pks, cipherText, sharedSecret)),
-                    cipherText: ctCoder.encode(cipherText),
+                    sharedSecret: combine(pks, cipherText, sharedSecret),
+                    cipherText: encodedCipherText,
                 };
             }
             finally {
@@ -402,11 +497,16 @@ expandSeed, combiner, ...kems) {
         decapsulate(ct, seed) {
             const cts = ctCoder.decode(ct);
             const { publicKey, secretKey } = keys.expandDecapsulationKey(seed);
-            const sharedSecret = rawKems.map((i, j) => i.decapsulate(cts[j], secretKey[j]));
+            const sharedSecret = [];
             try {
+                // Child decapsulate() is inside the try: it can throw on an attacker-supplied ciphertext
+                // (e.g. a low-order X25519 point), and by then the expanded child secret keys — plus any
+                // child shared secrets already produced — are live and must still be wiped.
+                for (let i = 0; i < rawKems.length; i++)
+                    sharedSecret.push(rawKems[i].decapsulate(cts[i], secretKey[i]));
                 // Detach the decapsulation result before cleanup: the combiner may hand back one of the
                 // child shared-secret buffers, and those temporary buffers are zeroized below.
-                return copyBytes(rawCombiner(publicKey, cts, sharedSecret));
+                return combine(publicKey, cts, sharedSecret);
             }
             finally {
                 // Decapsulation only needs the expanded child secret keys and child shared secrets for this
@@ -420,10 +520,15 @@ expandSeed, combiner, ...kems) {
 // realSeedLen: how much bytes expandSeed expects.
 /**
  * Combines multiple signers into one composite signer.
- * @param realSeedLen - Input seed length expected by `expandSeed`.
+ * @param realSeedLen - Positive input seed length expected by `expandSeed`, or `undefined` to use
+ * the sum of component seed lengths. Callers remain responsible for choosing a security-appropriate
+ * size.
  * @param expandSeed - Seed expander used to derive per-signer seeds.
- * @param signers - Signers to combine.
+ * @param signers - At least one signer. A construction advertised as hybrid normally supplies two
+ * or more.
  * @returns Composite signer.
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws If there are no components or any required length resolves to zero. {@link RangeError}
  * @example
  * Combine multiple signers into one composite signer.
  * ```ts
@@ -431,11 +536,23 @@ expandSeed, combiner, ...kems) {
  * import { combineSigners, expandSeedXof } from '@noble/post-quantum/hybrid.js';
  * import { ml_dsa44 } from '@noble/post-quantum/ml-dsa.js';
  * const hybrid = combineSigners(32, expandSeedXof(shake256), ml_dsa44, ml_dsa44);
- * const { publicKey } = hybrid.keygen();
+ * const seed = new Uint8Array(hybrid.lengths.seed!).fill(1);
+ * const { secretKey, publicKey } = hybrid.keygen(seed);
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = hybrid.sign(msg, secretKey);
+ * const isValid = hybrid.verify(sig, msg, publicKey);
  * ```
  */
 export function combineSigners(realSeedLen, expandSeed, ...signers) {
+    if (realSeedLen !== undefined)
+        positiveLength(realSeedLen, 'realSeedLen');
+    if (typeof expandSeed !== 'function')
+        throw new TypeError('"expandSeed" expected function, got type=' + typeof expandSeed);
     const rawSigners = signers;
+    if (rawSigners.length === 0)
+        throw new RangeError('combineSigners requires at least one signer');
+    for (let i = 0; i < rawSigners.length; i++)
+        validateSigner(rawSigners[i], `signers[${i}]`);
     const keys = combineKeys(realSeedLen, expandSeed, ...rawSigners);
     const sigCoder = splitLengths(rawSigners, 'signature');
     const pkCoder = splitLengths(rawSigners, 'publicKey');
@@ -444,7 +561,7 @@ export function combineSigners(realSeedLen, expandSeed, ...signers) {
         getPublicKey: keys.getPublicKey,
         keygen: keys.keygen,
         sign(message, seed, opts = {}) {
-            validateSigOpts(opts);
+            opts = validateSigOpts(opts);
             // This generic wrapper intentionally keeps the composite signer contract to message + root
             // seed only. Per-signer opts like context or extraEntropy cannot be preserved uniformly
             // across mixed backends, so callers that need them must use the underlying signer directly.
@@ -464,14 +581,21 @@ export function combineSigners(realSeedLen, expandSeed, ...signers) {
             }
         },
         /** Verify one combined signature.
-         * Returns `false` when the aggregate signature/publicKey decode succeeds but any child verify
-         * check fails. Throws on unsupported generic opts or malformed aggregate encodings.
+         * Wrong-length aggregate signatures return `false` (matching ml-dsa / slh-dsa behavior), as
+         * does any failing child verify. Throws on unsupported generic opts or malformed publicKey.
          */
         verify: (signature, message, publicKey, opts = {}) => {
-            validateVerOpts(opts);
+            opts = validateVerOpts(opts);
             if (opts.context !== undefined)
                 throw new Error('combineSigners does not support context; use the underlying signer directly');
+            // Malformed signature *length* is a verification failure, not a thrown type error —
+            // consistent with ml-dsa / slh-dsa. Must run before sigCoder.decode, which throws.
+            // Preserve TypeError for non-byte API arguments before treating byte lengths as invalid.
+            abytes(signature, undefined, 'signature');
+            // A signature failure must not hide malformed aggregate public-key bytes.
             const pks = pkCoder.decode(publicKey);
+            if (signature.length !== sigCoder.bytesLen)
+                return false;
             const sigs = sigCoder.decode(signature);
             for (let i = 0; i < rawSigners.length; i++) {
                 if (!rawSigners[i].verify(sigs[i], message, pks[i]))
@@ -494,26 +618,35 @@ export function combineSigners(realSeedLen, expandSeed, ...signers) {
  * @param xof - XOF used for seed expansion.
  * @param kdf - Hash used for the final combiner.
  * @returns Hybrid KEM.
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws On wrong argument ranges or values. {@link RangeError}
  * @example
  * Build a QSF hybrid KEM preset from a PQ KEM and an elliptic-curve KEM.
  * ```ts
  * import { p256 } from '@noble/curves/nist.js';
  * import { sha3_256, shake256 } from '@noble/hashes/sha3.js';
- * import { QSF, ecdhKem } from '@noble/post-quantum/hybrid.js';
+ * import { QSF, _ecdhKem } from '@noble/post-quantum/hybrid.js';
  * import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
- * const kem = QSF('example', ml_kem768, ecdhKem(p256, true), shake256, sha3_256);
+ * const kem = QSF('example', ml_kem768, _ecdhKem(p256, true), shake256, sha3_256);
  * const publicKeyLen = kem.lengths.publicKey;
  * ```
  */
 export function QSF(label, pqc, curveKEM, xof, kdf) {
+    astring(label, 'label');
+    validateKEM(pqc, 'pqc');
+    validateKEM(curveKEM, 'curveKEM');
+    if (typeof xof !== 'function' || typeof xof.create !== 'function')
+        throw new TypeError('"xof" expected hash function, got type=' + typeof xof);
     ahash(xof);
+    if (typeof kdf !== 'function' || typeof kdf.create !== 'function')
+        throw new TypeError('"kdf" expected hash function, got type=' + typeof kdf);
     ahash(kdf);
     return combineKEMS(32, kdf.outputLen, expandSeedXof(xof), (pk, ct, ss) => kdf(concatBytes(ss[0], ss[1], ct[1], pk[1], asciiToBytes(label))), pqc, curveKEM);
 }
 /** QSF preset combining ML-KEM-768 with P-256. */
-export const QSF_ml_kem768_p256 = /* @__PURE__ */ (() => QSF('QSF-KEM(ML-KEM-768,P-256)-XOF(SHAKE256)-KDF(SHA3-256)', ml_kem768, ecdhKem(p256, true), shake256, sha3_256))();
+export const QSF_ml_kem768_p256 = /* @__PURE__ */ (() => QSF('QSF-KEM(ML-KEM-768,P-256)-XOF(SHAKE256)-KDF(SHA3-256)', ml_kem768, _ecdhKem(p256, true), shake256, sha3_256))();
 /** QSF preset combining ML-KEM-1024 with P-384. */
-export const QSF_ml_kem1024_p384 = /* @__PURE__ */ (() => QSF('QSF-KEM(ML-KEM-1024,P-384)-XOF(SHAKE256)-KDF(SHA3-256)', ml_kem1024, ecdhKem(p384, true), shake256, sha3_256))();
+export const QSF_ml_kem1024_p384 = /* @__PURE__ */ (() => QSF('QSF-KEM(ML-KEM-1024,P-384)-XOF(SHAKE256)-KDF(SHA3-256)', ml_kem1024, _ecdhKem(p384, true), shake256, sha3_256))();
 /**
  * Builds the "KitchenSink" hybrid KEM combiner.
  * The current builder always derives a fixed 32-byte output,
@@ -528,20 +661,29 @@ export const QSF_ml_kem1024_p384 = /* @__PURE__ */ (() => QSF('QSF-KEM(ML-KEM-10
  * @param xof - XOF used for seed expansion.
  * @param hash - Hash used for HKDF extraction and expansion.
  * @returns Hybrid KEM.
+ * @throws On wrong argument types. {@link TypeError}
+ * @throws On wrong argument ranges or values. {@link RangeError}
  * @example
  * Build the "KitchenSink" hybrid KEM combiner.
  * ```ts
  * import { sha256 } from '@noble/hashes/sha2.js';
  * import { shake256 } from '@noble/hashes/sha3.js';
- * import { createKitchenSink, ecdhKem } from '@noble/post-quantum/hybrid.js';
+ * import { createKitchenSink, _ecdhKem } from '@noble/post-quantum/hybrid.js';
  * import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
  * import { x25519 } from '@noble/curves/ed25519.js';
- * const kem = createKitchenSink('example', ml_kem768, ecdhKem(x25519), shake256, sha256);
+ * const kem = createKitchenSink('example', ml_kem768, _ecdhKem(x25519), shake256, sha256);
  * const publicKeyLen = kem.lengths.publicKey;
  * ```
  */
 export function createKitchenSink(label, pqc, curveKEM, xof, hash) {
+    astring(label, 'label');
+    validateKEM(pqc, 'pqc');
+    validateKEM(curveKEM, 'curveKEM');
+    if (typeof xof !== 'function' || typeof xof.create !== 'function')
+        throw new TypeError('"xof" expected hash function, got type=' + typeof xof);
     ahash(xof);
+    if (typeof hash !== 'function' || typeof hash.create !== 'function')
+        throw new TypeError('"hash" expected hash function, got type=' + typeof hash);
     ahash(hash);
     return combineKEMS(32, 32, expandSeedXof(xof), (pk, ct, ss) => {
         const preimage = concatBytes(ss[0], ss[1], ct[0], pk[0], ct[1], pk[1], asciiToBytes(label));
@@ -554,9 +696,9 @@ export function createKitchenSink(label, pqc, curveKEM, xof, hash) {
         return res;
     }, pqc, curveKEM);
 }
-// Internal alias only: this stays exactly `ecdhKem(x25519)`
+// Internal alias only: this stays exactly `_ecdhKem(x25519)`
 // and inherits that wrapper's mutation/oracle behavior.
-const x25519kem = /* @__PURE__ */ ecdhKem(x25519);
+const x25519kem = /* @__PURE__ */ _ecdhKem(x25519);
 /** KitchenSink preset combining ML-KEM-768 with X25519.
  * Caller randomness splits into 32 ML-KEM coins plus a 32-byte X25519 ephemeral-secret seed.
  */
@@ -596,6 +738,11 @@ function nistCurveKem(curve, scalarLen, elemLen, nseed) {
         const publicKey = curve.getPublicKey(secretKey, false);
         return { secretKey, publicKey };
     }
+    // Standalone (not `this.decapsulate`) so encapsulate works even when methods are destructured.
+    const decapsulate = (cipherText, secretKey) => {
+        const full = curve.getSharedSecret(secretKey, cipherText);
+        return full.subarray(1);
+    };
     return {
         lengths: {
             secretKey: scalarLen,
@@ -616,7 +763,7 @@ function nistCurveKem(curve, scalarLen, elemLen, nseed) {
             let ek = undefined;
             try {
                 ek = rejectionSampling(rand).secretKey;
-                const sharedSecret = this.decapsulate(publicKey, ek);
+                const sharedSecret = decapsulate(publicKey, ek);
                 const cipherText = curve.getPublicKey(ek, false);
                 return { sharedSecret, cipherText };
             }
@@ -627,10 +774,7 @@ function nistCurveKem(curve, scalarLen, elemLen, nseed) {
                     cleanBytes(ek);
             }
         },
-        decapsulate(cipherText, secretKey) {
-            const full = curve.getSharedSecret(secretKey, cipherText);
-            return full.subarray(1);
-        },
+        decapsulate,
     };
 }
 /**
@@ -650,29 +794,14 @@ function concreteHybridKem(label, mlkem, curve, nseed) {
     const totalSeedLen = mlkemSeedLen + nseed;
     return combineKEMS(32, 32, (seed) => {
         abytes(seed, 32);
-        const expanded = shake256(seed, { dkLen: totalSeedLen });
-        const mlkemSeed = expanded.subarray(0, mlkemSeedLen);
-        const curveSeed = expanded.subarray(mlkemSeedLen, totalSeedLen);
-        return concatBytes(mlkemSeed, curveSeed);
+        // One SHAKE256 stream split by the seed coder as mlkemSeed (64) || curveSeed (nseed).
+        // Returned directly: the previous concatBytes of two adjacent subarrays produced an
+        // identical copy while leaving this original buffer unwiped; expandDecapsulationKey
+        // wipes the returned buffer after the child seeds are copied out.
+        return shake256(seed, { dkLen: totalSeedLen });
     }, (pk, ct, ss) => sha3_256(concatBytes(ss[0], ss[1], ct[1], pk[1], asciiToBytes(label))), mlkem, curveKem);
 }
 /** P-256 + ML-KEM-768 hybrid preset. */
 export const ml_kem768_p256 = /* @__PURE__ */ (() => concreteHybridKem('MLKEM768-P256', ml_kem768, p256, 128))();
 /** P-384 + ML-KEM-1024 hybrid preset. */
 export const ml_kem1024_p384 = /* @__PURE__ */ (() => concreteHybridKem('MLKEM1024-P384', ml_kem1024, p384, 48))();
-// Legacy aliases
-/** Legacy alias for `ml_kem768_x25519`. */
-export const XWing = /* @__PURE__ */ (() => ml_kem768_x25519)();
-/** Legacy alias for `ml_kem768_x25519`. */
-export const MLKEM768X25519 = /* @__PURE__ */ (() => ml_kem768_x25519)();
-/** Legacy alias for `ml_kem768_p256`. */
-export const MLKEM768P256 = /* @__PURE__ */ (() => ml_kem768_p256)();
-/** Legacy alias for `ml_kem1024_p384`. */
-export const MLKEM1024P384 = /* @__PURE__ */ (() => ml_kem1024_p384)();
-/** Legacy alias for `QSF_ml_kem768_p256`. */
-export const QSFMLKEM768P256 = /* @__PURE__ */ (() => QSF_ml_kem768_p256)();
-/** Legacy alias for `QSF_ml_kem1024_p384`. */
-export const QSFMLKEM1024P384 = /* @__PURE__ */ (() => QSF_ml_kem1024_p384)();
-/** Legacy alias for `KitchenSink_ml_kem768_x25519`. */
-export const KitchenSinkMLKEM768X25519 = /* @__PURE__ */ (() => KitchenSink_ml_kem768_x25519)();
-//# sourceMappingURL=hybrid.js.map

package/index.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -19,11 +19,10 @@ import {
 } from '@noble/post-quantum/falcon.js';
 import {
   ml_kem768_x25519, ml_kem768_p256, ml_kem1024_p384,
-  KitchenSink_ml_kem768_x25519, XWing,
+  KitchenSink_ml_kem768_x25519,
   QSF_ml_kem768_p256, QSF_ml_kem1024_p384,
 } from '@noble/post-quantum/hybrid.js';
 ```
  */
 throw new Error('root module cannot be imported: import submodules instead. Check out README');
 export {};
-//# sourceMappingURL=index.js.map

package/ml-dsa.d.ts

@@ -1,4 +1,5 @@
-import { type CryptoKeys, type Signer, type SigOpts, type TArg, type TRet, type VerOpts } from './utils.ts';
+import type { CHash } from '@noble/hashes/utils.js';
+import { type CryptoKeys, type Signer, type SigOpts, type TArg, type TRet } from './utils.ts';
 /** Internal ML-DSA options. */
 export type DSAInternalOpts = {
     /**
@@ -11,12 +12,19 @@ export type DSAInternalOpts = {
 /** ML-DSA signer surface with access to the internal message formatting mode. */
 export type DSAInternal = CryptoKeys & {
     lengths: Signer['lengths'];
-    sign: (msg: TArg<Uint8Array>, secretKey: TArg<Uint8Array>, opts?: TArg<SigOpts & DSAInternalOpts>) => TRet<Uint8Array>;
-    verify: (sig: TArg<Uint8Array>, msg: TArg<Uint8Array>, pubKey: TArg<Uint8Array>, opts?: TArg<VerOpts & DSAInternalOpts>) => boolean;
+    sign: (msg: TArg<Uint8Array>, secretKey: TArg<Uint8Array>, opts?: TArg<Omit<SigOpts, 'context'> & DSAInternalOpts>) => TRet<Uint8Array>;
+    verify: (sig: TArg<Uint8Array>, msg: TArg<Uint8Array>, pubKey: TArg<Uint8Array>, opts?: TArg<DSAInternalOpts>) => boolean;
 };
 /** Public ML-DSA signer surface. */
 export type DSA = Signer & {
     internal: TRet<DSAInternal>;
+    securityLevel: number;
+    /**
+     * HashML-DSA (FIPS 204 §5.4) variant which signs a pre-hashed message.
+     * @param hash - Approved hash, checked against the parameter set security level.
+     * @returns Signer which pre-hashes `msg` before formatting `M'`.
+     */
+    prehash: (hash: TArg<CHash>) => TRet<Signer>;
 };
 /** Various lattice params. */
 /** Public ML-DSA parameter-set description. */
@@ -45,10 +53,28 @@ export type DSAParam = {
  * while `C_TILDE_BYTES`, `TR_BYTES`, `CRH_BYTES`, and `securityLevel` live in the preset wrappers.
  */
 export declare const PARAMS: Record<string, DSAParam>;
-/** ML-DSA-44 for 128-bit security level. Not recommended after 2030, as per ASD. */
+/**
+ * ML-DSA-44 for 128-bit security level. Not recommended after 2030, as per ASD.
+ * @example
+ * Generate deterministic ML-DSA-44 keys, sign one message, and verify the signature.
+ * ```ts
+ * import { sha256 } from '@noble/hashes/sha2.js';
+ * import { ml_dsa44 } from '@noble/post-quantum/ml-dsa.js';
+ * const seed = new Uint8Array(ml_dsa44.lengths.seed!);
+ * const { secretKey, publicKey } = ml_dsa44.keygen(seed);
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = ml_dsa44.sign(msg, secretKey);
+ * const isValid = ml_dsa44.verify(sig, msg, publicKey);
+ * const recovered = ml_dsa44.getPublicKey(secretKey);
+ * const context = new Uint8Array([1, 2, 3]);
+ * const prehash = ml_dsa44.prehash(sha256);
+ * const preSig = prehash.sign(msg, secretKey, { context });
+ * const preValid = prehash.verify(preSig, msg, publicKey, { context });
+ * const internalSig = ml_dsa44.internal.sign(msg, secretKey);
+ * ```
+ */
 export declare const ml_dsa44: TRet<DSA>;
 /** ML-DSA-65 for 192-bit security level. Not recommended after 2030, as per ASD. */
 export declare const ml_dsa65: TRet<DSA>;
 /** ML-DSA-87 for 256-bit security level. OK after 2030, as per ASD. */
 export declare const ml_dsa87: TRet<DSA>;
-//# sourceMappingURL=ml-dsa.d.ts.map