@noble/post-quantum 0.6.1 → 0.7.0

package/ml-dsa.d.ts

@@ -1,3 +1,4 @@
+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 = {
@@ -17,6 +18,13 @@ export type DSAInternal = CryptoKeys & {
 /** 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

package/ml-dsa.js

@@ -72,6 +72,8 @@ const polyCoder = (d, compress = id, verify = id) => crystals.bitsCoder(d, {
     decode: (i) => verify(compress(i)),
 });
 // 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_, b_) => {
     const a = a_;
     const b = b_;
@@ -179,14 +181,16 @@ function getDilithium(opts_) {
         // See dilithium-py README section "Optimising decomposition and making hints".
         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, r) => {
         // 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;
+            return r0 > 0 ? crystals.mod(r1 + 1, HINT_M) | 0 : crystals.mod(r1 - 1, HINT_M) | 0;
         return r1 | 0;
     };
     const Power2Round = (r) => {
@@ -421,11 +425,34 @@ function getDilithium(opts_) {
         sign: (msg, secretKey, opts = {}) => {
             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;
+            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 = []; // A ← ExpandA(ρ)
             const xof = XOF128(rho);
@@ -448,19 +475,15 @@ function getDilithium(opts_) {
                 : // 6: µ ← H(tr||M, 512)
                     //    ▷ 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
@@ -532,6 +555,9 @@ function getDilithium(opts_) {
         verify: (sig, msg, publicKey, opts = {}) => {
             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)
@@ -604,10 +630,12 @@ function getDilithium(opts_) {
         },
         verify: (sig, msg, publicKey, opts = {}) => {
             validateVerOpts(opts);
+            abytes(sig, undefined, 'signature');
             return internal.verify(sig, getMessage(msg, opts.context), publicKey);
         },
         prehash: (hash) => {
             checkHash(hash, securityLevel);
+            const rawHash = hash;
             return Object.freeze({
                 info: Object.freeze({ type: 'hashml-dsa' }),
                 securityLevel: securityLevel,
@@ -616,20 +644,40 @@ function getDilithium(opts_) {
                 getPublicKey: internal.getPublicKey,
                 sign: (msg, secretKey, opts = {}) => {
                     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;
                 },
                 verify: (sig, msg, publicKey, opts = {}) => {
                     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 = /* @__PURE__ */ (() => getDilithium({
     ...PARAMS[2],
     CRH_BYTES: 64,
@@ -659,4 +707,3 @@ export const ml_dsa87 = /* @__PURE__ */ (() => getDilithium({
     XOF256,
     securityLevel: 256,
 }))();
-//# sourceMappingURL=ml-dsa.js.map

package/ml-kem.d.ts

@@ -26,20 +26,61 @@ export type KEMParam = {
  * not a generic security label.
  */
 export declare const PARAMS: Record<string, KEMParam>;
+/**
+ * Prepared (pre-expanded) ML-KEM public key. Experimental prototype.
+ * Caches only public data: packed ek, the expanded matrix Â, decoded t̂ and H(ek). No secret
+ * material is retained between calls; secret keys passed to `decapsulate` are decoded and wiped
+ * per call, exactly like the one-shot API. `clean()` wipes the expanded Â/t̂ cache; the packed
+ * public key and H(ek) are public and are not wiped. The object must not be used afterwards.
+ */
+export type KEMPrepared = {
+    /**
+     * Detached copy of the source public key. Treat as read-only while the prepared object is in use.
+     * Callers may wipe it after final use; any mutation invalidates subsequent operations.
+     */
+    publicKey: Uint8Array;
+    /** Same as `KEM.encapsulate`, minus per-call ek re-validation and  re-expansion. */
+    encapsulate: (msg?: Uint8Array) => {
+        cipherText: Uint8Array;
+        sharedSecret: Uint8Array;
+    };
+    /**
+     * Same as `KEM.decapsulate`; throws if `secretKey` does not embed this public key.
+     * The embedded-ek byte comparison plus stored-hash comparison is equivalent to the
+     * FIPS 203 §7.3 hash input check.
+     */
+    decapsulate: (cipherText: Uint8Array, secretKey: Uint8Array) => Uint8Array;
+    /** Wipe cached (public) data. */
+    clean: () => void;
+};
+/** KEM with prepared-key support. */
+export type MLKEM = KEM & {
+    prepare: (publicKey: Uint8Array) => KEMPrepared;
+};
 /**
  * ML-KEM-512: Table 2 row `k=2, η1=3, η2=2, du=10, dv=4`; Table 3 sizes `800/1632/768/32`.
  * The ASD lifecycle note here is external policy guidance, not a FIPS 203 requirement.
+ * @example
+ * Generate deterministic ML-KEM-512 keys, encapsulate a shared secret, and decapsulate it.
+ * ```ts
+ * import { ml_kem512 } from '@noble/post-quantum/ml-kem.js';
+ * const seed = new Uint8Array(ml_kem512.lengths.seed!);
+ * const { secretKey, publicKey } = ml_kem512.keygen(seed);
+ * const msg = new Uint8Array(ml_kem512.lengths.msgRand!);
+ * const { cipherText, sharedSecret } = ml_kem512.encapsulate(publicKey, msg);
+ * const recovered = ml_kem512.decapsulate(cipherText, secretKey);
+ * const publicKey2 = ml_kem512.getPublicKey(secretKey);
+ * ```
  */
-export declare const ml_kem512: TRet<KEM>;
+export declare const ml_kem512: TRet<MLKEM>;
 /**
  * ML-KEM-768: Table 2 row `k=3, η1=2, η2=2, du=10, dv=4`; Table 3 sizes `1184/2400/1088/32`.
  * The ASD lifecycle note here is external policy guidance, not a FIPS 203 requirement.
  */
-export declare const ml_kem768: TRet<KEM>;
+export declare const ml_kem768: TRet<MLKEM>;
 /**
  * ML-KEM-1024: Table 2 row `k=4, η1=2, η2=2, du=11, dv=5`; Table 3 sizes `1568/3168/1568/32`.
  * The ASD lifecycle note here is external policy guidance, not a FIPS 203 requirement.
  */
-export declare const ml_kem1024: TRet<KEM>;
+export declare const ml_kem1024: TRet<MLKEM>;
 export declare const __tests: any;
-//# sourceMappingURL=ml-kem.d.ts.map

package/ml-kem.js

@@ -84,24 +84,32 @@ const byteCoder = (d) => crystals.bitsCoder(d, d === 12
 // Kinda like convertRadix2 from @scure/base.
 // decode(encode(t)) == t, but there is loss of information on encode(decode(t))
 const polyCoder = (d) => (d === 12 ? byteCoder(12) : crystals.bitsCoder(d, compress(d)));
+// Coefficients always stay reduced in [0, Q) here (samplers, NTT and coders all reduce),
+// so one conditional correction replaces the generic mod().
 function polyAdd(a_, b_) {
     const a = a_;
     const b = b_;
     // Mutates `a` in place; callers must pass two N=256 polynomials.
-    for (let i = 0; i < N; i++)
-        a[i] = crystals.mod(a[i] + b[i]); // a += b
+    for (let i = 0; i < N; i++) {
+        const r = a[i] + b[i]; // a += b
+        a[i] = r >= Q ? r - Q : r;
+    }
 }
 function polySub(a_, b_) {
     const a = a_;
     const b = b_;
     // Mutates `a` in place; callers must pass two N=256 polynomials.
-    for (let i = 0; i < N; i++)
-        a[i] = crystals.mod(a[i] - b[i]); // a -= b
+    for (let i = 0; i < N; i++) {
+        const r = a[i] - b[i]; // a -= b
+        a[i] = r < 0 ? r + Q : r;
+    }
 }
 // FIPS-203: Computes the product of two degree-one polynomials with respect to a quadratic modulus
 function BaseCaseMultiply(a0, a1, b0, b1, zeta) {
     // `zeta` here is Algorithm 11's γ = ζ^(2BitRev_7(i)+1).
-    const c0 = crystals.mod(a1 * b1 * zeta + a0 * b0);
+    // Reduce a1*b1 before multiplying by zeta: a1*b1*zeta would reach ~2^35, forcing JS engines
+    // into slow float fmod; with the extra reduction every intermediate fits int32.
+    const c0 = crystals.mod(crystals.mod(a1 * b1) * zeta + a0 * b0);
     const c1 = crystals.mod(a0 * b1 + a1 * b0);
     return { c0, c1 };
 }
@@ -191,6 +199,34 @@ const genKPKE = (opts_) => {
     const secretCoder = vecCoder(polyCoder(12), K);
     const cipherCoder = splitCoder('ciphertext', vecCoder(polyU, K), polyV);
     const seedCoder = splitCoder('seed', 32, 32);
+    // Algorithm 14 (K-PKE.Encrypt) core, after ek parsing. `tHat` and every poly returned by
+    // `getA(i, j)` are treated as disposable scratch: they are mutated in place and wiped/dropped,
+    // so callers holding cached copies must pass fresh copies.
+    const encryptCore = (tHat, getA, msg, seed) => {
+        const rHat = [];
+        for (let i = 0; i < K; i++)
+            rHat.push(crystals.NTT.encode(sampleCBD(PRF, seed, i, ETA1)));
+        const tmp2 = new Uint16Array(N);
+        const u = [];
+        for (let i = 0; i < K; i++) {
+            const e1 = sampleCBD(PRF, seed, K + i, ETA2);
+            const tmp = new Uint16Array(N);
+            for (let j = 0; j < K; j++) {
+                const aij = getA(i, j); // A[j][i], inplace transpose access
+                polyAdd(tmp, MultiplyNTTs(aij, rHat[j])); // t += aij * rHat[j]
+            }
+            polyAdd(e1, crystals.NTT.decode(tmp)); // e1 += tmp
+            u.push(e1);
+            polyAdd(tmp2, MultiplyNTTs(tHat[i], rHat[i])); // t2 += tHat[i] * rHat[i]
+            cleanBytes(tmp);
+        }
+        const e2 = sampleCBD(PRF, seed, 2 * K, ETA2);
+        polyAdd(e2, crystals.NTT.decode(tmp2)); // e2 += tmp2
+        const v = poly1.decode(msg); // encode plaintext m into polynomial v
+        polyAdd(v, e2); // v += e2
+        cleanBytes(tHat, rHat, tmp2, e2);
+        return cipherCoder.encode([u, v]);
+    };
     return {
         secretCoder,
         lengths: {
@@ -231,31 +267,26 @@ const genKPKE = (opts_) => {
         },
         encrypt: (publicKey, msg, seed) => {
             const [tHat, rho] = publicCoder.decode(publicKey);
-            const rHat = [];
-            for (let i = 0; i < K; i++)
-                rHat.push(crystals.NTT.encode(sampleCBD(PRF, seed, i, ETA1)));
             const x = XOF(rho);
-            const tmp2 = new Uint16Array(N);
-            const u = [];
-            for (let i = 0; i < K; i++) {
-                const e1 = sampleCBD(PRF, seed, K + i, ETA2);
-                const tmp = new Uint16Array(N);
-                for (let j = 0; j < K; j++) {
-                    const aij = SampleNTT(x.get(i, j)); // A[j][i], inplace transpose access
-                    polyAdd(tmp, MultiplyNTTs(aij, rHat[j])); // t += aij * rHat[j]
-                }
-                polyAdd(e1, crystals.NTT.decode(tmp)); // e1 += tmp
-                u.push(e1);
-                polyAdd(tmp2, MultiplyNTTs(tHat[i], rHat[i])); // t2 += tHat[i] * rHat[i]
-                cleanBytes(tmp);
-            }
+            const res = encryptCore(tHat, (i, j) => SampleNTT(x.get(i, j)), msg, seed);
             x.clean();
-            const e2 = sampleCBD(PRF, seed, 2 * K, ETA2);
-            polyAdd(e2, crystals.NTT.decode(tmp2)); // e2 += tmp2
-            const v = poly1.decode(msg); // encode plaintext m into polynomial v
-            polyAdd(v, e2); // v += e2
-            cleanBytes(tHat, rHat, tmp2, e2);
-            return cipherCoder.encode([u, v]);
+            return res;
+        },
+        // Expands the full  matrix (public data derived from rho) once, so repeated encryptions
+        // against the same ek skip the K² SampleNTT XOF expansions. Cached polys are copied per
+        // call because encryptCore mutates its inputs in place.
+        prepare: (publicKey) => {
+            const [tHat, rho] = publicCoder.decode(publicKey);
+            const x = XOF(rho);
+            const A = [];
+            for (let i = 0; i < K; i++)
+                for (let j = 0; j < K; j++)
+                    A.push(SampleNTT(x.get(i, j)));
+            x.clean();
+            return {
+                encrypt: (msg, seed) => encryptCore(tHat.map((p) => p.slice()), (i, j) => A[i * K + j].slice(), msg, seed),
+                clean: () => cleanBytes(tHat, A),
+            };
         },
         decrypt: (cipherText, privateKey) => {
             const [u, v] = cipherCoder.decode(cipherText);
@@ -287,6 +318,18 @@ function createKyber(opts) {
     const secretCoder = splitCoder('secretKey', lengths.secretKey, lengths.publicKey, 32, 32);
     const msgLen = 32;
     const seedLen = 64;
+    // FIPS-203 includes additional verification check for modulus
+    const validateModulus = (publicKey, fn) => {
+        const eke = publicKey.subarray(0, 384 * rawOpts.K);
+        // Copy because of inplace encoding
+        const ek = KPKESecretCoder.encode(KPKESecretCoder.decode(copyBytes(eke)));
+        // (Modulus check.) Perform the computation ek ← ByteEncode12(ByteDecode12(eke)).
+        // If ek = ̸ eke, the input is invalid. (See Section 4.2.1.)
+        const ok = equalBytes(ek, eke);
+        cleanBytes(ek);
+        if (!ok)
+            throw new Error(`ML-KEM.${fn}: wrong publicKey modulus`);
+    };
     const kemLengths = Object.freeze({
         ...lengths,
         seed: 64,
@@ -316,17 +359,7 @@ function createKyber(opts) {
         encapsulate: (publicKey, msg = randomBytes(msgLen)) => {
             abytes(publicKey, lengths.publicKey, 'publicKey');
             abytes(msg, msgLen, 'message');
-            // FIPS-203 includes additional verification check for modulus
-            const eke = publicKey.subarray(0, 384 * opts.K);
-            // Copy because of inplace encoding
-            const ek = KPKESecretCoder.encode(KPKESecretCoder.decode(copyBytes(eke)));
-            // (Modulus check.) Perform the computation ek ← ByteEncode12(ByteDecode12(eke)).
-            // If ek = ̸ eke, the input is invalid. (See Section 4.2.1.)
-            if (!equalBytes(ek, eke)) {
-                cleanBytes(ek);
-                throw new Error('ML-KEM.encapsulate: wrong publicKey modulus');
-            }
-            cleanBytes(ek);
+            validateModulus(publicKey, 'encapsulate');
             // derive randomness
             const kr = HASH512.create().update(msg).update(HASH256(publicKey)).digest();
             const cipherText = KPKE.encrypt(publicKey, msg, kr.subarray(32, 64));
@@ -356,9 +389,57 @@ function createKyber(opts) {
             // if ciphertexts do not match, “implicitly reject”
             const isValid = equalBytes(cipherText, cipherText2);
             const Kbar = KDF.create({ dkLen: 32 }).update(z).update(cipherText).digest();
-            cleanBytes(msg, cipherText2, !isValid ? Khat : Kbar);
+            // kr[32:64] is the derived K-PKE encryption randomness: wipe it like encapsulate() does.
+            cleanBytes(msg, cipherText2, kr.subarray(32), !isValid ? Khat : Kbar);
             return (isValid ? Khat : Kbar);
         },
+        /**
+         * Experimental prototype: pre-expand a public key so repeated encapsulate/decapsulate
+         * against the same key skip re-validation, H(ek), t̂ decoding and the K² SampleNTT
+         * XOF expansions of Â. Only public data is cached; see {@link KEMPrepared}.
+         */
+        prepare: (publicKey) => {
+            abytes(publicKey, lengths.publicKey, 'publicKey');
+            validateModulus(publicKey, 'prepare');
+            const ek = copyBytes(publicKey); // detach from the caller before caching
+            const publicKeyHash = HASH256(ek);
+            const cached = KPKE.prepare(ek);
+            return Object.freeze({
+                publicKey: ek,
+                encapsulate: (msg = randomBytes(msgLen)) => {
+                    abytes(msg, msgLen, 'message');
+                    const kr = HASH512.create().update(msg).update(publicKeyHash).digest();
+                    const cipherText = cached.encrypt(msg, kr.subarray(32, 64));
+                    cleanBytes(kr.subarray(32));
+                    return {
+                        cipherText: cipherText,
+                        sharedSecret: kr.subarray(0, 32),
+                    };
+                },
+                decapsulate: (cipherText, secretKey) => {
+                    abytes(secretKey, secretCoder.bytesLen, 'secretKey');
+                    abytes(cipherText, lengths.cipherText, 'cipherText');
+                    const [sk, ekEmbedded, storedHash, z] = secretCoder.decode(secretKey);
+                    // Under KEMPrepared's read-only publicKey contract, bind dk to the prepared key.
+                    // Together with publicKeyHash = H(ek) computed in prepare(), this is equivalent to (and
+                    // stronger than) FIPS 203 §7.3's `H(dk[384k : 768k+32]) == dk[768k+32 : 768k+64]`.
+                    if (!equalBytes(ekEmbedded, ek) || !equalBytes(storedHash, publicKeyHash))
+                        throw new Error('ML-KEM.decapsulate: secretKey does not match prepared publicKey');
+                    const msg = KPKE.decrypt(cipherText, sk);
+                    // derive randomness, Khat, rHat = G(mHat || h)
+                    const kr = HASH512.create().update(msg).update(publicKeyHash).digest();
+                    const Khat = kr.subarray(0, 32);
+                    // re-encrypt using the derived randomness and cached Â/t̂
+                    const cipherText2 = cached.encrypt(msg, kr.subarray(32, 64));
+                    // if ciphertexts do not match, “implicitly reject”
+                    const isValid = equalBytes(cipherText, cipherText2);
+                    const Kbar = KDF.create({ dkLen: 32 }).update(z).update(cipherText).digest();
+                    cleanBytes(msg, cipherText2, kr.subarray(32), !isValid ? Khat : Kbar);
+                    return (isValid ? Khat : Kbar);
+                },
+                clean: cached.clean,
+            });
+        },
     });
 }
 // FIPS 203's PRF_eta binding: current callers use only 32-byte keys, one-byte nonces,
@@ -388,6 +469,17 @@ const mk = (params) => createKyber({
 /**
  * ML-KEM-512: Table 2 row `k=2, η1=3, η2=2, du=10, dv=4`; Table 3 sizes `800/1632/768/32`.
  * The ASD lifecycle note here is external policy guidance, not a FIPS 203 requirement.
+ * @example
+ * Generate deterministic ML-KEM-512 keys, encapsulate a shared secret, and decapsulate it.
+ * ```ts
+ * import { ml_kem512 } from '@noble/post-quantum/ml-kem.js';
+ * const seed = new Uint8Array(ml_kem512.lengths.seed!);
+ * const { secretKey, publicKey } = ml_kem512.keygen(seed);
+ * const msg = new Uint8Array(ml_kem512.lengths.msgRand!);
+ * const { cipherText, sharedSecret } = ml_kem512.encapsulate(publicKey, msg);
+ * const recovered = ml_kem512.decapsulate(cipherText, secretKey);
+ * const publicKey2 = ml_kem512.getPublicKey(secretKey);
+ * ```
  */
 export const ml_kem512 = /* @__PURE__ */ (() => mk(PARAMS[512]))();
 /**
@@ -441,4 +533,3 @@ export const __tests = /* @__PURE__ */ (() => Object.freeze({
         }
     },
 }))();
-//# sourceMappingURL=ml-kem.js.map

package/package.json

@@ -1,40 +1,32 @@
 {
   "name": "@noble/post-quantum",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Auditable & minimal JS implementation of post-quantum cryptography: FIPS 203, 204, 205, Falcon",
   "files": [
     "*.js",
-    "*.js.map",
     "*.d.ts",
-    "*.d.ts.map",
     "src"
   ],
   "dependencies": {
-    "@noble/ciphers": "~2.2.0",
-    "@noble/curves": "~2.2.0",
-    "@noble/hashes": "~2.2.0"
+    "@noble/ciphers": "~2.3.0",
+    "@noble/curves": "~2.3.0",
+    "@noble/hashes": "~2.3.0"
   },
   "devDependencies": {
-    "@paulmillr/jsbt": "0.5.0",
+    "@paulmillr/jsbt": "0.6.5",
     "@types/node": "25.3.0",
     "fast-check": "4.2.0",
     "prettier": "3.6.2",
     "typescript": "6.0.2"
   },
   "scripts": {
-    "bench": "node test/benchmark.ts",
+    "benchmark": "node benchmark/pq.ts",
+    "benchmark:size": "npx bismar@0.1 -s",
     "build": "tsc",
-    "build:release": "npx --no @paulmillr/jsbt esbuild test/build",
-    "check": "npm run check:readme && npm run check:treeshake && npm run check:jsdoc",
-    "check:readme": "npx --no @paulmillr/jsbt readme package.json",
-    "check:treeshake": "npx --no @paulmillr/jsbt treeshake package.json test/build/out-treeshake",
-    "check:jsdoc": "npx --no @paulmillr/jsbt tsdoc package.json",
-    "build:clean": "rm *.{js,js.map,d.ts,d.ts.map} 2> /dev/null",
+    "check": "jsbt-check",
+    "build:clean": "rm *.{js,d.ts} 2> /dev/null",
     "format": "prettier --write 'src/**/*.{js,ts}' 'test/**/*.{js,ts,mjs}'",
     "test": "node test/index.ts",
-    "test:bun": "bun test/index.ts",
-    "test:deno": "deno --allow-env --allow-read test/index.ts",
-    "test:node20": "cd test; npx tsc; node compiled/test/index.js",
     "test:slow": "SLOW_TESTS=1 node test/index.ts"
   },
   "exports": {

package/slh-dsa.d.ts

@@ -40,12 +40,16 @@ export type SphincsHashOpts = {
 export declare const PARAMS: Record<string, SphincsOpts>;
 /** Address byte array of size `ADDR_BYTES`. */
 export type ADRS = Uint8Array;
-/** Hash and tweakable-hash callbacks bound to one SLH-DSA keypair context. */
+/** Hash and tweakable-hash callbacks bound to one SLH-DSA keypair context.
+ * Buffer-aliasing contract: `PRFaddr`, `thash1` and `thashN` return views into per-context
+ * scratch buffers (one per lane), so callers must consume or copy a result before the next
+ * call on the same lane. `clean()` wipes the scratch buffers along with the hash states.
+ */
 export type Context = {
     /**
      * Derive a PRF output for one address.
      * @param addr - Address bytes.
-     * @returns PRF output bytes.
+     * @returns PRF output bytes (scratch view; copy to retain).
      */
     PRFaddr: (addr: TArg<ADRS>) => TRet<Uint8Array>;
     /**
@@ -131,6 +135,23 @@ export declare const slh_dsa_shake_256s: TRet<SphincsSigner>;
  * SLH-DSA-SHA2-128f: Table 2 row `n=16, h=66, d=22, h'=3, a=6, k=33, lg w=4, m=34`;
  * lengths `publicKey=32`, `secretKey=64`, `signature=17088`, `seed=48`, `signRand=16`.
  * Also exposes `.prehash(...)`.
+ * @example
+ * Generate deterministic SLH-DSA keys, sign one message, and verify the signature.
+ * ```ts
+ * import { sha256 } from '@noble/hashes/sha2.js';
+ * import { slh_dsa_sha2_128f } from '@noble/post-quantum/slh-dsa.js';
+ * const seed = new Uint8Array(slh_dsa_sha2_128f.lengths.seed!);
+ * const { secretKey, publicKey } = slh_dsa_sha2_128f.keygen(seed);
+ * const msg = new TextEncoder().encode('hello noble');
+ * const sig = slh_dsa_sha2_128f.sign(msg, secretKey);
+ * const isValid = slh_dsa_sha2_128f.verify(sig, msg, publicKey);
+ * const recovered = slh_dsa_sha2_128f.getPublicKey(secretKey);
+ * const context = new Uint8Array([1, 2, 3]);
+ * const prehash = slh_dsa_sha2_128f.prehash(sha256);
+ * const preSig = prehash.sign(msg, secretKey, { context });
+ * const preValid = prehash.verify(preSig, msg, publicKey, { context });
+ * const internalSig = slh_dsa_sha2_128f.internal.sign(msg, secretKey);
+ * ```
  */
 export declare const slh_dsa_sha2_128f: TRet<SphincsSigner>;
 /**
@@ -163,4 +184,3 @@ export declare const slh_dsa_sha2_256f: TRet<SphincsSigner>;
  * Also exposes `.prehash(...)`.
  */
 export declare const slh_dsa_sha2_256s: TRet<SphincsSigner>;
-//# sourceMappingURL=slh-dsa.d.ts.map