@noble/post-quantum 0.6.1 → 0.7.0

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,
@@ -92,6 +94,8 @@ import { sha3_256, shake256 } from '@noble/hashes/sha3.js';
 import { abytes, ahash, anumber, 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) {
@@ -177,6 +204,11 @@ function ecKeygen(curve: CurveAll, allowZeroKey: boolean = false) {
 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 +222,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 +233,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,
   };
 }
 
@@ -359,25 +388,40 @@ 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(realSeedLen!) : 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: realSeedLen, publicKey: pkCoder.bytesLen, secretKey: realSeedLen } },
+    // 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,
   };
@@ -416,14 +460,21 @@ export function combineKEMS(
   combiner: TArg<Combiner>,
   ...kems: TArg<KEM[]>
 ): TRet<KEM> {
+  if (realSeedLen !== undefined) anumber(realSeedLen, 'realSeedLen');
+  if (realMsgLen !== undefined) anumber(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[];
+  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);
+  anumber(realMsgLen, 'realMsgLen');
   const lengths = Object.freeze({
     ...keys.info.lengths,
     msg: realMsgLen,
@@ -491,7 +542,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 +554,11 @@ export function combineSigners(
   expandSeed: TArg<ExpandSeed>,
   ...signers: TArg<Signer[]>
 ): TRet<Signer> {
+  if (realSeedLen !== undefined) anumber(realSeedLen, 'realSeedLen');
+  if (typeof expandSeed !== 'function')
+    throw new TypeError('"expandSeed" expected function, got type=' + typeof expandSeed);
   const rawSigners = signers as 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');
@@ -531,8 +590,8 @@ 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);
@@ -540,7 +599,13 @@ export function combineSigners(
         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;
@@ -581,7 +646,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,
@@ -646,7 +718,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,
@@ -734,6 +813,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 +838,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 +847,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 +876,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 +896,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/ml-dsa.ts

@@ -64,7 +64,16 @@ export type DSAInternal = CryptoKeys & {
   ) => boolean;
 };
 /** Public ML-DSA signer surface. */
-export type DSA = Signer & { internal: TRet<DSAInternal> };
+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>;
+};
 
 // Constants
 // FIPS 204 fixes ML-DSA over R = Z[X]/(X^256 + 1), so every polynomial has 256 coefficients.
@@ -154,6 +163,8 @@ const polyCoder = (d: number, compress: IdNum = id, verify: IdNum = id) =>
   });
 
 // Mutates `a` in place; callers must pass same-length polynomials.
+// NOTE: conditional-reduction variants (as in ml-kem) were measured performance-neutral here —
+// int32 `%` with 23-bit Q is already cheap — so the simpler mod() form is kept for audit.
 const polyAdd = (a_: TArg<Poly>, b_: TArg<Poly>): TRet<Poly> => {
   const a = a_ as Poly;
   const b = b_ as Poly;
@@ -275,13 +286,16 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
     return res0;
   };
 
+  // m = (q-1)/(2γ2): 44 for ML-DSA-44, 16 for 65/87. Hoisted out of UseHint, which runs
+  // per coefficient during verification.
+  const HINT_M = Math.floor((Q - 1) / (2 * GAMMA2));
   const UseHint = (h: number, r: number) => {
     // Returns the high bits of r adjusted according to hint h
-    const m = Math.floor((Q - 1) / (2 * GAMMA2));
     const { r1, r0 } = decompose(r);
     // 3: if h = 1 and r0 > 0 return (r1 + 1) mod m
     // 4: if h = 1 and r0 ≤ 0 return (r1 − 1) mod m
-    if (h === 1) return r0 > 0 ? crystals.mod(r1 + 1, m) | 0 : crystals.mod(r1 - 1, m) | 0;
+    if (h === 1)
+      return r0 > 0 ? crystals.mod(r1 + 1, HINT_M) | 0 : crystals.mod(r1 - 1, HINT_M) | 0;
     return r1 | 0;
   };
   const Power2Round = (r: number) => {
@@ -527,11 +541,32 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
     ): TRet<Uint8Array> => {
       validateSigOpts(opts);
       validateInternalOpts(opts);
-      let { extraEntropy: random, externalMu = false } = opts;
+      const { extraEntropy: random, externalMu = false } = opts;
+      // FIPS 204 external-mu mode expects the 64-byte message representative µ = H(tr || M).
+      if (externalMu) abytes(msg, CRH_BYTES, 'mu');
+      // Prepare entropy before touching decoded secrets: randomBytes() may throw, and an RNG
+      // failure must not leave expanded secret-polynomial copies behind.
+      const ownRnd = random === false || random === undefined;
+      const rnd =
+        random === false
+          ? new Uint8Array(32)
+          : random === undefined
+            ? randomBytes(signRandBytes)
+            : (random as Uint8Array);
+      abytes(rnd, 32, 'extraEntropy');
       // This part can be pre-cached per secretKey, but there is only minor performance improvement,
       // since we re-use a lot of variables to computation.
       // (ρ, K,tr, s1, s2, t0) ← skDecode(sk)
-      const [rho, _K, tr, s1, s2, t0] = secretCoder.decode(secretKey);
+      const decoded = (() => {
+        try {
+          return secretCoder.decode(secretKey);
+        } catch (error) {
+          // A malformed key must not strand entropy owned by the library.
+          if (ownRnd) cleanBytes(rnd);
+          throw error;
+        }
+      })();
+      const [rho, _K, tr, s1, s2, t0] = decoded;
       // Cache matrix to avoid re-compute later
       const A: Poly[][] = []; // A ← ExpandA(ρ)
       const xof = XOF128(rho);
@@ -553,21 +588,14 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
           //    ▷ Compute message representative µ
           shake256.create({ dkLen: CRH_BYTES }).update(tr).update(msg).digest();
 
-      // Compute private random seed
-      const rnd =
-        random === false
-          ? new Uint8Array(32)
-          : random === undefined
-            ? randomBytes(signRandBytes)
-            : random;
-      abytes(rnd, 32, 'extraEntropy');
       const rhoprime = shake256
         .create({ dkLen: CRH_BYTES })
         .update(_K)
         .update(rnd)
         .update(mu)
         .digest(); // ρ′← H(K||rnd||µ, 512)
-
+      // Only wipe entropy we generated; caller-provided extraEntropy stays caller-owned.
+      if (ownRnd) cleanBytes(rnd);
       abytes(rhoprime, CRH_BYTES);
       const x256 = XOF256(rhoprime, ZCoder.bytesLen);
       //  Rejection sampling loop
@@ -638,6 +666,8 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
     ) => {
       validateInternalOpts(opts);
       const { externalMu = false } = opts;
+      // FIPS 204 external-mu mode expects the 64-byte message representative µ = H(tr || M).
+      if (externalMu) abytes(msg, CRH_BYTES, 'mu');
       // ML-DSA.Verify(pk, M, σ): Verifes a signature σ for a message M.
       const [rho, t1] = publicCoder.decode(publicKey); // (ρ, t1) ← pkDecode(pk)
       const tr = shake256(publicKey, { dkLen: TR_BYTES }); // 6: tr ← H(BytesToBits(pk), 512)
@@ -712,10 +742,12 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
       opts: TArg<VerOpts> = {}
     ) => {
       validateVerOpts(opts);
+      abytes(sig, undefined, 'signature');
       return internal.verify(sig, getMessage(msg, opts.context), publicKey);
     },
-    prehash: (hash: CHash) => {
-      checkHash(hash, securityLevel);
+    prehash: (hash: TArg<CHash>): TRet<Signer> => {
+      checkHash(hash as CHash, securityLevel);
+      const rawHash = hash as CHash;
       return Object.freeze({
         info: Object.freeze({ type: 'hashml-dsa' }),
         securityLevel: securityLevel,
@@ -728,7 +760,7 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
           opts: TArg<SigOpts> = {}
         ): TRet<Uint8Array> => {
           validateSigOpts(opts);
-          const M = getMessagePrehash(hash, msg, opts.context);
+          const M = getMessagePrehash(rawHash, msg, opts.context);
           const res = internal.sign(M, secretKey, opts);
           cleanBytes(M);
           return res as TRet<Uint8Array>;
@@ -740,14 +772,34 @@ function getDilithium(opts_: TArg<DilithiumOpts>): TRet<DSA> {
           opts: TArg<VerOpts> = {}
         ) => {
           validateVerOpts(opts);
-          return internal.verify(sig, getMessagePrehash(hash, msg, opts.context), publicKey);
+          abytes(sig, undefined, 'signature');
+          return internal.verify(sig, getMessagePrehash(rawHash, msg, opts.context), publicKey);
         },
       });
     },
   });
 }
 
-/** 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 const ml_dsa44: TRet<DSA> = /* @__PURE__ */ (() =>
   getDilithium({
     ...PARAMS[2],