@noble/post-quantum 0.6.1 → 0.7.1

package/src/hybrid.ts

@@ -80,6 +80,8 @@ import { type ECDSA } from '@noble/curves/abstract/weierstrass.js';
 import { x25519 } from '@noble/curves/ed25519.js';
 import { p256, p384 } from '@noble/curves/nist.js';
 import {
+  abool,
+  afunction,
   asciiToBytes,
   bytesToNumberBE,
   bytesToNumberLE,
@@ -89,9 +91,11 @@ import {
 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, type CHash, type CHashXOF } from '@noble/hashes/utils.js';
+import { abytes, ahash, anumber, isBytes, type CHash, type CHashXOF } from '@noble/hashes/utils.js';
 import { ml_kem1024, ml_kem768 } from './ml-kem.ts';
 import {
+  aobject,
+  astring,
   cleanBytes,
   copyBytes,
   randomBytes,
@@ -108,9 +112,32 @@ import {
 type CurveAll = ECDSA | EdDSA | MontgomeryECDH;
 type CurveECDH = ECDSA | MontgomeryECDH;
 type CurveSign = ECDSA | EdDSA;
+const validateKEM = (kem: TArg<KEM>, title: string): TRet<KEM> => {
+  const k = aobject<KEM>(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 as TRet<KEM>;
+};
+const validateSigner = (signer: TArg<Signer>, title: string): TRet<Signer> => {
+  const s = aobject<Signer>(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 as TRet<Signer>;
+};
 
 // Can re-use if decide to signatures support, on other hand getSecretKey is specific and ugly
 function ecKeygen(curve: CurveAll, allowZeroKey: boolean = false) {
+  const c = aobject<CurveAll>(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) {
@@ -154,6 +181,12 @@ function ecKeygen(curve: CurveAll, allowZeroKey: boolean = 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.
@@ -169,14 +202,19 @@ function ecKeygen(curve: CurveAll, allowZeroKey: boolean = 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: CurveECDH, allowZeroKey: boolean = false): TRet<KEM> {
+export function _ecdhKem(curve: CurveECDH, allowZeroKey: boolean = false): TRet<KEM> {
   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: TArg<Uint8Array>, secretKey: TArg<Uint8Array>) => {
+    const res = curve.getSharedSecret(secretKey, cipherText);
+    return (curve.lengths.publicKeyHasPrefix ? res.subarray(1) : res) as TRet<Uint8Array>;
+  };
   return {
     lengths: { ...kg.lengths, msg: kg.lengths.seed, cipherText: kg.lengths.publicKey },
     keygen: kg.keygen,
@@ -190,8 +228,8 @@ export function ecdhKem(curve: CurveECDH, allowZeroKey: boolean = false): TRet<K
       const seed = copyBytes(rand);
       let ek: Uint8Array | undefined = 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) as TRet<Uint8Array>;
         return { sharedSecret, cipherText };
       } finally {
@@ -201,10 +239,7 @@ export function ecdhKem(curve: CurveECDH, allowZeroKey: boolean = false): TRet<K
         if (ek) cleanBytes(ek);
       }
     },
-    decapsulate(cipherText: TArg<Uint8Array>, secretKey: TArg<Uint8Array>) {
-      const res = curve.getSharedSecret(secretKey, cipherText);
-      return (curve.lengths.publicKeyHasPrefix ? res.subarray(1) : res) as TRet<Uint8Array>;
-    },
+    decapsulate,
   };
 }
 
@@ -237,7 +272,7 @@ export function ecSigner(curve: CurveSign, allowZeroKey: boolean = false): TRet<
     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.
@@ -254,7 +289,7 @@ export function ecSigner(curve: CurveSign, allowZeroKey: boolean = false): TRet<
      * 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);
@@ -262,18 +297,26 @@ export function ecSigner(curve: CurveSign, allowZeroKey: boolean = false): TRet<
   };
 }
 
+function positiveLength(value: number, title: string): number {
+  const length = anumber(value, title);
+  if (length === 0) throw new RangeError(`"${title}" expected integer greater than 0, got 0`);
+  return length;
+}
+
 function splitLengths<K extends string, T extends { lengths: Partial<Record<K, number>> }>(
   lst: T[],
   name: K
 ) {
   // Preserve caller order exactly; raw numeric fields still decode as splitCoder() subarray views.
-  return splitCoder(
+  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;
 }
 
 /** Seed-expansion callback used by the hybrid combiners. */
@@ -319,13 +362,15 @@ function combineKeys(
   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: TArg<Uint8Array>): TRet<{
     secretKey: Uint8Array[];
     publicKey: Uint8Array[];
   }> {
-    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.
@@ -359,39 +404,60 @@ function combineKeys(
       if (!ok) cleanBytes(secretKey);
     }
   }
-  return {
-    info: { lengths: { seed: realSeedLen, publicKey: pkCoder.bytesLen, secretKey: realSeedLen } },
-    getPublicKey(secretKey: TArg<Uint8Array>) {
-      // 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 as TRet<Uint8Array>;
-    },
-    keygen(seed: TArg<Uint8Array> = randomBytes(realSeedLen)) {
-      const { publicKey: pk, secretKey } = expandDecapsulationKey(seed);
+  // Standalone (not a method) so getPublicKey / destructured usage never depends on `this`.
+  const keygen = (seed?: TArg<Uint8Array>) => {
+    // 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) as TRet<Uint8Array>;
-        return { secretKey: seed as TRet<Uint8Array>, publicKey };
+        res = {
+          secretKey: root as TRet<Uint8Array>,
+          publicKey: pkCoder.encode(pk) as TRet<Uint8Array>,
+        };
       } 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: TArg<Uint8Array>) => {
+      const keys = keygen(secretKey);
+      // keygen detaches its exported root; getPublicKey discards that half of the result.
+      cleanBytes(keys.secretKey);
+      return keys.publicKey as TRet<Uint8Array>;
     },
+    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
@@ -416,20 +482,56 @@ export function combineKEMS(
   combiner: TArg<Combiner>,
   ...kems: TArg<KEM[]>
 ): TRet<KEM> {
+  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 as Combiner;
   const rawKems = kems as KEM[];
+  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: TArg<Uint8Array[]>,
+    cipherTexts: TArg<Uint8Array[]>,
+    sharedSecrets: TArg<Uint8Array[]>
+  ): TRet<Uint8Array> => {
+    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: TArg<Uint8Array>) =>
+          combined.buffer === value.buffer &&
+          combined.byteOffset < value.byteOffset + value.byteLength &&
+          value.byteOffset < combined.byteOffset + combined.byteLength;
+        const aliasesPublicInput =
+          (publicKeys as Uint8Array[]).some(overlaps) ||
+          (cipherTexts as Uint8Array[]).some(overlaps);
+        if (!aliasesPublicInput) cleanBytes(combined);
+      }
+      throw error;
+    }
+  };
   return Object.freeze({
     lengths,
     getPublicKey: keys.getPublicKey,
@@ -448,11 +550,14 @@ export function combineKEMS(
           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) as TRet<Uint8Array>;
         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) as TRet<Uint8Array>,
+          sharedSecret: combine(pks, cipherText, sharedSecret),
+          cipherText: encodedCipherText,
         };
       } finally {
         // Child encapsulation or combiner failures can happen after some components already
@@ -463,11 +568,16 @@ export function combineKEMS(
     decapsulate(ct: TArg<Uint8Array>, seed: TArg<Uint8Array>) {
       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: Uint8Array[] = [];
       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
         // call; keep the caller/root seed intact, but wipe all derived material even on errors.
@@ -480,10 +590,15 @@ export function combineKEMS(
 // 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
@@ -491,7 +606,11 @@ export function combineKEMS(
  * 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(
@@ -499,7 +618,12 @@ export function combineSigners(
   expandSeed: TArg<ExpandSeed>,
   ...signers: TArg<Signer[]>
 ): TRet<Signer> {
+  if (realSeedLen !== undefined) positiveLength(realSeedLen, 'realSeedLen');
+  if (typeof expandSeed !== 'function')
+    throw new TypeError('"expandSeed" expected function, got type=' + typeof expandSeed);
   const rawSigners = signers as Signer[];
+  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');
@@ -508,7 +632,7 @@ export function combineSigners(
     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.
@@ -531,16 +655,22 @@ export function combineSigners(
       }
     },
     /** 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])) return false;
@@ -563,14 +693,16 @@ export function combineSigners(
  * @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;
  * ```
  */
@@ -581,7 +713,14 @@ export function QSF(
   xof: TArg<XOF>,
   kdf: CHash
 ): TRet<KEM> {
+  astring(label, 'label');
+  validateKEM(pqc, 'pqc');
+  validateKEM(curveKEM, 'curveKEM');
+  if (typeof xof !== 'function' || typeof (xof as any).create !== 'function')
+    throw new TypeError('"xof" expected hash function, got type=' + typeof xof);
   ahash(xof);
+  if (typeof kdf !== 'function' || typeof (kdf as any).create !== 'function')
+    throw new TypeError('"kdf" expected hash function, got type=' + typeof kdf);
   ahash(kdf);
   return combineKEMS(
     32,
@@ -599,7 +738,7 @@ export const QSF_ml_kem768_p256: TRet<KEM> = /* @__PURE__ */ (() =>
   QSF(
     'QSF-KEM(ML-KEM-768,P-256)-XOF(SHAKE256)-KDF(SHA3-256)',
     ml_kem768,
-    ecdhKem(p256, true),
+    _ecdhKem(p256, true),
     shake256,
     sha3_256
   ))();
@@ -608,7 +747,7 @@ export const QSF_ml_kem1024_p384: TRet<KEM> = /* @__PURE__ */ (() =>
   QSF(
     'QSF-KEM(ML-KEM-1024,P-384)-XOF(SHAKE256)-KDF(SHA3-256)',
     ml_kem1024,
-    ecdhKem(p384, true),
+    _ecdhKem(p384, true),
     shake256,
     sha3_256
   ))();
@@ -627,15 +766,17 @@ export const QSF_ml_kem1024_p384: TRet<KEM> = /* @__PURE__ */ (() =>
  * @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;
  * ```
  */
@@ -646,7 +787,14 @@ export function createKitchenSink(
   xof: TArg<XOF>,
   hash: CHash
 ): TRet<KEM> {
+  astring(label, 'label');
+  validateKEM(pqc, 'pqc');
+  validateKEM(curveKEM, 'curveKEM');
+  if (typeof xof !== 'function' || typeof (xof as any).create !== 'function')
+    throw new TypeError('"xof" expected hash function, got type=' + typeof xof);
   ahash(xof);
+  if (typeof hash !== 'function' || typeof (hash as any).create !== 'function')
+    throw new TypeError('"hash" expected hash function, got type=' + typeof hash);
   ahash(hash);
   return combineKEMS(
     32,
@@ -671,9 +819,9 @@ export function createKitchenSink(
   );
 }
 
-// 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.
  */
@@ -734,6 +882,11 @@ function nistCurveKem(curve: ECDSA, scalarLen: number, elemLen: number, nseed: n
     }>;
   }
 
+  // Standalone (not `this.decapsulate`) so encapsulate works even when methods are destructured.
+  const decapsulate = (cipherText: TArg<Uint8Array>, secretKey: TArg<Uint8Array>) => {
+    const full = curve.getSharedSecret(secretKey, cipherText);
+    return full.subarray(1) as TRet<Uint8Array>;
+  };
   return {
     lengths: {
       secretKey: scalarLen,
@@ -754,7 +907,7 @@ function nistCurveKem(curve: ECDSA, scalarLen: number, elemLen: number, nseed: n
       let ek: Uint8Array | undefined = undefined;
       try {
         ek = rejectionSampling(rand).secretKey;
-        const sharedSecret = this.decapsulate(publicKey, ek);
+        const sharedSecret = decapsulate(publicKey, ek);
         const cipherText = curve.getPublicKey(ek, false) as TRet<Uint8Array>;
         return { sharedSecret, cipherText };
       } finally {
@@ -763,10 +916,7 @@ function nistCurveKem(curve: ECDSA, scalarLen: number, elemLen: number, nseed: n
         if (ek) cleanBytes(ek);
       }
     },
-    decapsulate(cipherText: TArg<Uint8Array>, secretKey: TArg<Uint8Array>) {
-      const full = curve.getSharedSecret(secretKey, cipherText);
-      return full.subarray(1) as TRet<Uint8Array>;
-    },
+    decapsulate,
   };
 }
 
@@ -795,10 +945,11 @@ function concreteHybridKem(
     32,
     (seed: TArg<Uint8Array>): TRet<Uint8Array> => {
       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) as TRet<Uint8Array>;
+      // 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 }) as TRet<Uint8Array>;
     },
     (pk: TArg<Uint8Array[]>, ct: TArg<Uint8Array[]>, ss: TArg<Uint8Array[]>) =>
       sha3_256(concatBytes(ss[0], ss[1], ct[1], pk[1], asciiToBytes(label))),
@@ -814,20 +965,3 @@ export const ml_kem768_p256: TRet<KEM> = /* @__PURE__ */ (() =>
 /** P-384 + ML-KEM-1024 hybrid preset. */
 export const ml_kem1024_p384: TRet<KEM> = /* @__PURE__ */ (() =>
   concreteHybridKem('MLKEM1024-P384', ml_kem1024, p384, 48))();
-
-// Legacy aliases
-/** Legacy alias for `ml_kem768_x25519`. */
-export const XWing: TRet<KEM> = /* @__PURE__ */ (() => ml_kem768_x25519)();
-/** Legacy alias for `ml_kem768_x25519`. */
-export const MLKEM768X25519: TRet<KEM> = /* @__PURE__ */ (() => ml_kem768_x25519)();
-/** Legacy alias for `ml_kem768_p256`. */
-export const MLKEM768P256: TRet<KEM> = /* @__PURE__ */ (() => ml_kem768_p256)();
-/** Legacy alias for `ml_kem1024_p384`. */
-export const MLKEM1024P384: TRet<KEM> = /* @__PURE__ */ (() => ml_kem1024_p384)();
-/** Legacy alias for `QSF_ml_kem768_p256`. */
-export const QSFMLKEM768P256: TRet<KEM> = /* @__PURE__ */ (() => QSF_ml_kem768_p256)();
-/** Legacy alias for `QSF_ml_kem1024_p384`. */
-export const QSFMLKEM1024P384: TRet<KEM> = /* @__PURE__ */ (() => QSF_ml_kem1024_p384)();
-/** Legacy alias for `KitchenSink_ml_kem768_x25519`. */
-export const KitchenSinkMLKEM768X25519: TRet<KEM> = /* @__PURE__ */ (() =>
-  KitchenSink_ml_kem768_x25519)();

package/src/index.ts

@@ -19,7 +19,7 @@ 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';
 ```