@noble/post-quantum 0.6.0 → 0.7.0

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 { 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) {
@@ -110,12 +133,15 @@ function ecKeygen(curve, allowZeroKey = false) {
             const seedScalar = Fn.isLE ? bytesToNumberLE(seed) : bytesToNumberBE(seed);
             // Reduce directly into [0, ORDER); scalar 0 still stays invalid.
             const secretKey = Fn.toBytes(Fn.create(seedScalar));
-            return { secretKey, publicKey: curve.getPublicKey(secretKey) };
+            return {
+                secretKey: secretKey,
+                publicKey: curve.getPublicKey(secretKey),
+            };
         };
     }
     return {
         lengths: { secretKey: lengths.secretKey, publicKey: lengths.publicKey, seed: lengths.seed },
-        keygen,
+        keygen: (seed) => keygen(seed),
         getPublicKey: (secretKey) => curve.getPublicKey(secretKey),
     };
 }
@@ -146,6 +172,11 @@ 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,
@@ -156,8 +187,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 };
             }
@@ -169,10 +200,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,
     };
 }
 /**
@@ -253,10 +281,12 @@ function splitLengths(lst, name) {
 export function expandSeedXof(xof) {
     // Forward the caller seed directly: XOFs are expected to treat inputs as read-only, and this
     // adapter only translates the requested byte length into the hash API's `dkLen` option.
-    return (seed, seedLen) => xof(seed, { dkLen: seedLen });
+    return ((seed, seedLen) => xof(seed, { dkLen: seedLen }));
 }
 function combineKeys(realSeedLen, // how much bytes expandSeed expects
-expandSeed, ...ck) {
+expandSeed_, ...ck_) {
+    const expandSeed = expandSeed_;
+    const ck = ck_;
     const seedCoder = splitLengths(ck, 'seed');
     const pkCoder = splitLengths(ck, 'publicKey');
     // Allows to use identity functions for combiner/expandSeed
@@ -298,26 +328,43 @@ 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(realSeedLen) : 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: 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) => {
+            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,
     };
@@ -351,20 +398,33 @@ expandSeed, ...ck) {
 export function combineKEMS(realSeedLen, // how much bytes expandSeed expects
 realMsgLen, // how much bytes combiner returns
 expandSeed, combiner, ...kems) {
-    const keys = combineKeys(realSeedLen, expandSeed, ...kems);
-    const ctCoder = splitLengths(kems, 'cipherText');
-    const pkCoder = splitLengths(kems, 'publicKey');
-    const msgCoder = splitLengths(kems, 'msg');
+    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;
+    const rawKems = kems;
+    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);
-    return {
-        lengths: {
-            ...keys.info.lengths,
-            msg: realMsgLen,
-            msgRand: msgCoder.bytesLen,
-            cipherText: ctCoder.bytesLen,
-        },
+    anumber(realMsgLen, 'realMsgLen');
+    const lengths = Object.freeze({
+        ...keys.info.lengths,
+        msg: realMsgLen,
+        msgRand: msgCoder.bytesLen,
+        cipherText: ctCoder.bytesLen,
+    });
+    return Object.freeze({
+        lengths,
         getPublicKey: keys.getPublicKey,
         keygen: keys.keygen,
         encapsulate(pk, randomness = randomBytes(msgCoder.bytesLen)) {
@@ -373,15 +433,15 @@ expandSeed, combiner, ...kems) {
             const sharedSecret = [];
             const cipherText = [];
             try {
-                for (let i = 0; i < kems.length; i++) {
-                    const enc = kems[i].encapsulate(pks[i], rand[i]);
+                for (let i = 0; i < rawKems.length; i++) {
+                    const enc = rawKems[i].encapsulate(pks[i], rand[i]);
                     sharedSecret.push(enc.sharedSecret);
                     cipherText.push(enc.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(combiner(pks, cipherText, sharedSecret)),
+                    sharedSecret: copyBytes(rawCombiner(pks, cipherText, sharedSecret)),
                     cipherText: ctCoder.encode(cipherText),
                 };
             }
@@ -394,11 +454,11 @@ expandSeed, combiner, ...kems) {
         decapsulate(ct, seed) {
             const cts = ctCoder.decode(ct);
             const { publicKey, secretKey } = keys.expandDecapsulationKey(seed);
-            const sharedSecret = kems.map((i, j) => i.decapsulate(cts[j], secretKey[j]));
+            const sharedSecret = rawKems.map((i, j) => i.decapsulate(cts[j], secretKey[j]));
             try {
                 // 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(combiner(publicKey, cts, sharedSecret));
+                return copyBytes(rawCombiner(publicKey, cts, sharedSecret));
             }
             finally {
                 // Decapsulation only needs the expanded child secret keys and child shared secrets for this
@@ -406,7 +466,7 @@ expandSeed, combiner, ...kems) {
                 cleanBytes(secretKey, sharedSecret);
             }
         },
-    };
+    });
 }
 // There is no specs for this, but can be useful
 // realSeedLen: how much bytes expandSeed expects.
@@ -423,13 +483,24 @@ 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) {
-    const keys = combineKeys(realSeedLen, expandSeed, ...signers);
-    const sigCoder = splitLengths(signers, 'signature');
-    const pkCoder = splitLengths(signers, 'publicKey');
+    if (realSeedLen !== undefined)
+        anumber(realSeedLen, 'realSeedLen');
+    if (typeof expandSeed !== 'function')
+        throw new TypeError('"expandSeed" expected function, got type=' + typeof expandSeed);
+    const rawSigners = signers;
+    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');
     return {
         lengths: { ...keys.info.lengths, signature: sigCoder.bytesLen, signRand: 0 },
         getPublicKey: keys.getPublicKey,
@@ -445,7 +516,7 @@ export function combineSigners(realSeedLen, expandSeed, ...signers) {
                 throw new Error('combineSigners does not support context; use the underlying signer directly');
             const { secretKey } = keys.expandDecapsulationKey(seed);
             try {
-                const sigs = signers.map((i, j) => i.sign(message, secretKey[j]));
+                const sigs = rawSigners.map((i, j) => i.sign(message, secretKey[j]));
                 return sigCoder.encode(sigs);
             }
             finally {
@@ -455,17 +526,24 @@ 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);
             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 < signers.length; i++) {
-                if (!signers[i].verify(sigs[i], message, pks[i]))
+            for (let i = 0; i < rawSigners.length; i++) {
+                if (!rawSigners[i].verify(sigs[i], message, pks[i]))
                     return false;
             }
             return true;
@@ -497,7 +575,14 @@ export function combineSigners(realSeedLen, expandSeed, ...signers) {
  * ```
  */
 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);
 }
@@ -532,7 +617,14 @@ export const QSF_ml_kem1024_p384 = /* @__PURE__ */ (() => QSF('QSF-KEM(ML-KEM-10
  * ```
  */
 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));
@@ -587,6 +679,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,
@@ -607,7 +704,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 };
             }
@@ -618,10 +715,7 @@ function nistCurveKem(curve, scalarLen, elemLen, nseed) {
                     cleanBytes(ek);
             }
         },
-        decapsulate(cipherText, secretKey) {
-            const full = curve.getSharedSecret(secretKey, cipherText);
-            return full.subarray(1);
-        },
+        decapsulate,
     };
 }
 /**
@@ -641,29 +735,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

@@ -14,8 +14,15 @@ import {
   slh_dsa_shake_192f, slh_dsa_shake_192s,
   slh_dsa_shake_256f, slh_dsa_shake_256s,
 } from '@noble/post-quantum/slh-dsa.js';
+import {
+  falcon512, falcon512padded, falcon1024, falcon1024padded,
+} from '@noble/post-quantum/falcon.js';
+import {
+  ml_kem768_x25519, ml_kem768_p256, ml_kem1024_p384,
+  KitchenSink_ml_kem768_x25519, XWing,
+  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 VerOpts } from './utils.ts';
+import type { CHash } from '@noble/hashes/utils.js';
+import { type CryptoKeys, type Signer, type SigOpts, type TArg, type TRet, type VerOpts } 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: Uint8Array, secretKey: Uint8Array, opts?: SigOpts & DSAInternalOpts) => Uint8Array;
-    verify: (sig: Uint8Array, msg: Uint8Array, pubKey: Uint8Array, opts?: VerOpts & DSAInternalOpts) => boolean;
+    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;
 };
 /** Public ML-DSA signer surface. */
 export type DSA = Signer & {
-    internal: DSAInternal;
+    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. */
-export declare const ml_dsa44: DSA;
+/**
+ * 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: DSA;
+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: DSA;
-//# sourceMappingURL=ml-dsa.d.ts.map
+export declare const ml_dsa87: TRet<DSA>;