@noble/post-quantum 0.7.0 → 0.7.1

package/README.md

@@ -79,7 +79,7 @@ import {
 - [ML-DSA / Dilithium](#ml-dsa--dilithium-signatures)
 - [SLH-DSA / SPHINCS+](#slh-dsa--sphincs-signatures)
 - [Falcon](#falcon-signatures)
-- [hybrid: XWing, KitchenSink and others](#hybrid-xwing-kitchensink-and-others)
+- [hybrid: X-Wing, KitchenSink and others](#hybrid-x-wing-kitchensink-and-others)
 - [What should I use?](#what-should-i-use)
 - [Security](#security)
 - [Contributing & testing](#contributing--testing)
@@ -123,6 +123,25 @@ Old, incompatible version (Kyber) is not provided. Open an issue if you need it.
 > `decapsulate` will simply return a different shared secret.
 > ML-KEM is also probabilistic and relies on quality of CSPRNG.
 
+#### webcrypto: friendly wrapper
+
+WebCrypto-backed ML-KEM and `ml_kem768_x25519` wrappers are also available. Their methods are async
+and require a runtime that implements the corresponding experimental WebCrypto API.
+
+```ts
+import { ml_kem768 } from '@noble/post-quantum/webcrypto.js';
+
+if (await ml_kem768.isSupported()) {
+  const aliceKeys = await ml_kem768.keygen();
+  const { cipherText, sharedSecret: bobShared } = await ml_kem768.encapsulate(aliceKeys.publicKey);
+  const aliceShared = await ml_kem768.decapsulate(cipherText, aliceKeys.secretKey);
+}
+```
+
+The ML-KEM wrappers serialize private keys as 64-byte `raw-seed` values; the X25519 hybrid uses a
+32-byte seed. They can be passed to the corresponding synchronous implementation's `keygen(seed)`,
+but are not expanded decapsulation keys.
+
 ### ML-DSA / Dilithium signatures
 
 ```ts
@@ -157,9 +176,17 @@ const isValidPre = hml.verify(sigPre, msg, keys.publicKey);
 - `context`: domain-separation byte string, up to 255 bytes; must match between `sign` and `verify`
 - `extraEntropy`: hedged-signing randomness. Default is 32 random bytes;
   `false` produces deterministic signatures; custom 32-byte value is also allowed
-- `externalMu`: treat `msg` as the precomputed 64-byte message representative µ
 - `prehash(hash)`: pre-hash variant (HashML-DSA) from FIPS-204
 
+Unknown option keys are rejected rather than ignored, so a misspelling such as
+`{ ctx }` fails loudly instead of silently signing with no domain separation.
+
+`externalMu`, which treats `msg` as the precomputed 64-byte message representative
+µ, is available on `ml_dsa*.internal.sign` / `internal.verify` only. The public
+wrappers reject it: `sign` formats `M'` before the 64-byte check so it could never
+accept a µ, and `verify` did not forward it, returning `false` for a valid
+external-mu signature.
+
 ### SLH-DSA / SPHINCS+ signatures
 
 ```ts
@@ -218,7 +245,27 @@ Lattice-based digital signature algorithm, submitted to NIST PQC Round 3 ([websi
 - `falcon512padded`, `falcon1024padded`: fixed-length detached signatures
 - `attached.seal(...)` / `attached.open(...)`: attached-signature API for Round 3 vectors and interop
 
-### hybrid: XWing, KitchenSink and others
+> [!WARNING]
+> Falcon signing is randomized by design. Leave signing options unset in production so every
+> signature receives a fresh 40-byte public nonce and a fresh 48-byte sampler seed from the system
+> CSPRNG. Falcon's `extraEntropy` option does not have the hedged semantics used by ML-DSA and
+> SLH-DSA:
+>
+> - `extraEntropy: false` seeds an AES-CTR-DRBG with 48 zero bytes. It makes signatures
+>   deterministic for a fixed key and message, and reuses the same nonce and initial random stream
+>   across different messages. This is outside the Falcon Round 3 randomized-hash design.
+> - A 48-byte `extraEntropy` value replaces system randomness; it is not mixed with fresh entropy.
+>   Reusing a value therefore reuses the signing stream.
+> - The raw `random` callback overrides `extraEntropy` and supplies both the nonce and sampler seed.
+>   It exists for test-vector reproduction and should not be used as a production randomness hook.
+>
+> In particular, do not copy ML-DSA examples that use `extraEntropy: false` into Falcon code.
+
+`attached.open(...)` throws when verification fails and returns a fresh copy of the embedded
+message when it succeeds. The result does not alias the attached signature or public-key buffers.
+Detached `verify(...)` returns `false` for an invalid signature.
+
+### hybrid: X-Wing, KitchenSink and others
 
 ```js
 import {
@@ -230,19 +277,32 @@ import {
 
 The hybrid submodule combines post-quantum algorithms with elliptic curve cryptography:
 
-- `ml_kem768_x25519`: ML-KEM-768 + X25519 (CG Framework, same as XWing)
-- `ml_kem768_p256`: ML-KEM-768 + P-256 (CG Framework)
-- `ml_kem1024_p384`: ML-KEM-1024 + P-384 (CG Framework)
+- `ml_kem768_x25519`: ML-KEM-768 + X25519, implementing X-Wing under the descriptive
+  `ml_kem768_x25519` export name. There is no separate `XWing` alias.
+- `ml_kem768_p256`: ML-KEM-768 + P-256 using the current CG framework construction
+- `ml_kem1024_p384`: ML-KEM-1024 + P-384 using the current CG framework construction
 - `KitchenSink_ml_kem768_x25519`: ML-KEM-768 + X25519 with HKDF-SHA256 combiner
-- `QSF_ml_kem768_p256`: ML-KEM-768 + P-256 (QSF construction)
-- `QSF_ml_kem1024_p384`: ML-KEM-1024 + P-384 (QSF construction)
+- `QSF_ml_kem768_p256`, `QSF_ml_kem1024_p384`: legacy compatibility presets for the older
+  QSF/C2PRI naming and labels. New code should use `ml_kem768_p256` and `ml_kem1024_p384`.
+
+> **Security note:** `_ecdhKem(curve)` is an internal raw-ECDH component adapter, not a standalone
+> IND-CCA-secure KEM. It has no KDF and does not bind the encapsulation or recipient public key, so
+> different accepted point encodings can derive the same bytes. Use it only within a specified
+> combiner that performs that binding, or use a standardized DHKEM. The built-in hybrid presets
+> retain their specified combiners and test-vector-compatible behavior.
+
+The current `ml_kem*` presets are tested against these work-in-progress specifications:
 
-The following spec drafts are matched:
+- [irtf-cfrg-hybrid-kems-12](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hybrid-kems-12)
+- [irtf-cfrg-concrete-hybrid-kems-03](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-concrete-hybrid-kems-03)
+- [connolly-cfrg-xwing-kem-10](https://datatracker.ietf.org/doc/html/draft-connolly-cfrg-xwing-kem-10)
 
-- [irtf-cfrg-hybrid-kems-07](https://datatracker.ietf.org/doc/draft-irtf-cfrg-hybrid-kems/)
-- [irtf-cfrg-concrete-hybrid-kems-02](https://datatracker.ietf.org/doc/draft-irtf-cfrg-concrete-hybrid-kems/)
-- [connolly-cfrg-xwing-kem-09](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/)
-- [tls-westerbaan-xyber768d00-03](https://datatracker.ietf.org/doc/draft-tls-westerbaan-xyber768d00/)
+`QSF(...)` is the legacy API name for the construction now called the C2PRI combiner. It derives
+the final secret from `ssPQ || ssT || ctT || ekT || label`; omitting the PQ ciphertext and
+encapsulation key is intentional and relies on the PQ KEM's C2PRI property. The `QSF_*` presets
+retain older draft labels and vectors for compatibility, so they do not implement the current
+concrete preset encodings. They are also unrelated to the separate universal-combiner example in
+NIST SP 800-227.
 
 ### What should I use?
 
@@ -282,9 +342,23 @@ If you see anything unusual: investigate and report.
 
 ### Constant-timeness
 
-There is no protection against side-channel attacks.
-We actively research how to provide this property for post-quantum algorithms in JS.
-Keep in mind that even hardware versions ML-KEM [are vulnerable](https://eprint.iacr.org/2023/1084).
+This pure JavaScript implementation does not claim constant-time execution. JavaScript engines,
+JIT compilers, garbage collection, floating-point operations and `bigint` arithmetic do not offer
+the execution guarantees needed for a formal constant-time claim.
+
+- ML-DSA signing uses rejection loops, early-exit norm checks and conditional arithmetic whose
+  execution depends on secret-key and per-signature state. Fresh randomized signing is the default,
+  but it does not turn the implementation into a constant-time one.
+- Falcon signing uses data-dependent Gaussian and rejection sampling, floating-point operations,
+  and `bigint` paths. Its timing and microarchitectural side-channel posture is materially weaker
+  than a hardened native implementation. Deterministic or repeated signing randomness can make
+  observations easier to correlate and should be avoided.
+- These limitations matter most when an attacker can measure signing closely, such as hostile
+  co-tenancy, shared hardware, or a high-resolution local timing oracle. Use an isolated execution
+  environment or a reviewed native/constant-time backend when that is part of the threat model.
+
+We actively research how to improve this property for post-quantum algorithms in JS. Even hardware
+ML-KEM implementations require careful side-channel engineering and [have had practical attacks](https://eprint.iacr.org/2023/1084).
 
 ### Supply chain security
 

package/_crystals.js

@@ -31,7 +31,7 @@ export const genCrystals = (opts) => {
     // Normalize JS `%` into the canonical Z_m representative `[0, modulo-1]` expected by
     // FIPS 203 §2.3 / FIPS 204 §2.3 before downstream mod-q arithmetic.
     const mod = (a, modulo = Q) => {
-        const result = a % modulo | 0;
+        const result = (a % modulo) | 0;
         return (result >= 0 ? result | 0 : (modulo + result) | 0) | 0;
     };
     // FIPS 204 §7.4 uses the centered `mod ±` representative for low bits, keeping the

package/falcon.d.ts

@@ -22,7 +22,7 @@ export type FalconAttached = CryptoKeys & {
      * @param sig Attached Falcon signature bytes.
      * @param publicKey Falcon public key bytes.
      * @param opts Optional verification options.
-     * @returns Embedded message bytes when the signature is valid.
+     * @returns Fresh message bytes that do not alias either input when the signature is valid.
      */
     open(sig: Uint8Array, publicKey: Uint8Array, opts?: VerOpts): Uint8Array;
 };

package/falcon.js

@@ -12,7 +12,7 @@ import { bytesToNumberLE, numberToHexUnpadded } from '@noble/curves/utils.js';
 import { shake256 } from '@noble/hashes/sha3.js';
 import { abytes, bytesToHex, createView, hexToBytes, randomBytes, swap32IfBE, u32, u8, } from '@noble/hashes/utils.js';
 import { genCrystals } from "./_crystals.js";
-import { baswap64If, cleanBytes, getMask, splitCoder, validateSigOpts, validateVerOpts, } from "./utils.js";
+import { baswap64If, cleanBytes, copyBytes, getMask, splitCoder, validateSigOpts, validateVerOpts, SIG_OPT_KEYS, } from "./utils.js";
 /*
 FIPS-206 would likely improve the situation with spec.
 
@@ -230,8 +230,13 @@ const compCoder = (n) => {
                 const sign = readBits(1);
                 const low = readBits(7);
                 let high = 0;
-                for (; !readBits(1); high++)
-                    ;
+                // Reference comp_decode adds 128 for each unary zero and rejects immediately above 2047.
+                // Waiting for the terminating one first lets an invalid coefficient scan the entire input.
+                while (!readBits(1)) {
+                    high++;
+                    if (high > LIMIT >>> 7)
+                        throw new Error(`limit: ${low | (high << 7)} > ${LIMIT}`);
+                }
                 const v = low | (high << 7);
                 if (sign && v === 0)
                     throw new Error('negative zero encoding');
@@ -510,6 +515,9 @@ const SIGMA_MIN = /* @__PURE__ */ Object.freeze([
     f64b(BigInt('4608433670533905013')),
     f64b(BigInt('4608525754002622308')),
 ]);
+// Upper end of the SamplerZ proof interval from Falcon section 3.9.1. The per-leaf sigma is
+// derived from the reconstructed private basis, so imported keys must be checked against it.
+const SIGMA_MAX = 1.8205;
 // Falcon Table 3.1 RCDT values for chi, split into 24-bit limbs; storage is [high, mid, low],
 // so gaussian0() intentionally compares them against v0, v1, v2 in reverse order. The final
 // RCDT[18] = 0 row is omitted because the algorithm iterates only over i = 0..17.
@@ -1111,6 +1119,51 @@ function getFloatPoly(logn) {
         },
     };
 }
+function ldlFFT(logn, g00t, g01t, g11t) {
+    // Algorithm 8: LDL*(G)
+    // (Page 37)
+    // Require: A full-rank self-adjoint matrix G = (Gᵢⱼ) ∈ FFT(Q[x]/(φ))²ˣ²
+    // Ensure: The LDL* decomposition G = LDL* over FFT(Q[x]/(φ))
+    // Format: All polynomials are in FFT representation.
+    // 1: D₀₀ ← G₀₀
+    // 2: L₁₀ ← G₁₀/G₀₀
+    // 3: D₁₁ ← G₁₁ - L₁₀ ⊙ L₁₀* ⊙ G₀₀
+    // 4: L ← [ 1 0 ; L₁₀ 1 ], D ← [ D₀₀ 0 ; 0 D₁₁ ]
+    // 5: return (L, D)
+    // Algorithm 9: ffLDL*(G)
+    // (Page 37)
+    // Require: A full-rank Gram matrix G ∈ FFT(Q[x]/(xⁿ + 1))²ˣ²
+    // Ensure: A binary tree T
+    // Format: All polynomials are in FFT representation.
+    // 1: (L, D) ← LDL*(G) ▷ L = [ 1 0 ; L₁₀ 1 ], D = [ D₀₀ 0 ; 0 D₁₁ ]
+    // 2: T.value ← L₁₀
+    // 3: if (n = 2) then
+    // 4:     T.leftchild ← D₀₀
+    // 5:     T.rightchild ← D₁₁
+    // 6:     return T
+    // 7: else
+    // 8:     d₀₀, d₀₁ ← splitfft(D₀₀) ▷ dᵢⱼ ∈ FFT(Q[x]/(x^{n/2} + 1))
+    // 9:     d₁₀, d₁₁ ← splitfft(D₁₁)
+    // 10:     G₀ ← [ d₀₀ d₀₁ ; d₀₁* d₀₀ ], G₁ ← [ d₁₀ d₁₁ ; d₁₁* d₁₀ ]
+    //         ▷ Since D₀₀, D₁₁ are self-adjoint, (3.30) applies
+    // 11:     T.leftchild ← ffLDL*(G₀) ▷ Recursive calls
+    // 12:     T.rightchild ← ffLDL*(G₁)
+    // 13:     return T
+    // Recursive calls may alias g00t and g11t, and the top-level arrays persist across signing
+    // retries. LDL replaces array entries, so shallow copies keep both kinds of caller state intact.
+    g00t = g00t.slice();
+    g01t = g01t.slice();
+    g11t = g11t.slice();
+    const hn = 1 << (logn - 1);
+    for (let i = 0; i < hn; i++) {
+        const g01 = g01t[i];
+        const g11 = g11t[i];
+        const mu = fComplex.scale(g01, 1.0 / g00t[i].re);
+        g11t[i] = { re: g11.re - (mu.re * g01.re + mu.im * g01.im), im: g11.im };
+        g01t[i] = fComplex.conj(mu);
+    }
+    return { g00: g00t, g01: g01t, g11: g11t };
+}
 function ApproxExp(x, ccs) {
     // Algorithm 13: ApproxExp(x, ccs), (Page 42)
     // Require: Floating-point values x ∈ [0, ln(2)] and ccs ∈ [0, 1]
@@ -1633,19 +1686,24 @@ function genFalcon(opts) {
     };
     // [ 1B header ] [ 40B nonce ] [ compressed_sig ]
     const SignatureCoderDetached = (logn) => {
-        const sigLen = opts.padded ? opts.sigLen - 1 - NONCELEN : opts.detachedLen;
-        const getSigLen = (s2) => (opts.padded ? sigLen : s2.length);
+        const paddedSigLen = opts.sigLen - 1 - NONCELEN;
+        const getSigLen = (s2) => (opts.padded ? paddedSigLen : s2.length);
         return {
             encode({ nonce, s2 }) {
-                return headerCoder(0x30 + logn, splitCoder('falcon.detachedSignature', NONCELEN, getSigLen(s2))).encode([nonce, opts.padded ? pad(sigLen).encode(s2) : s2]);
+                return headerCoder(0x30 + logn, splitCoder('falcon.detachedSignature', NONCELEN, getSigLen(s2))).encode([nonce, opts.padded ? pad(paddedSigLen).encode(s2) : s2]);
             },
             decode(data) {
+                // Unpadded Round-3 signatures have parameter-set maxima (header + nonce + s2):
+                // 752 bytes for Falcon-512 and 1462 for Falcon-1024. Reject before creating views or
+                // entering the bit decoder so attacker-sized inputs cannot cause proportional work.
+                if (!opts.padded && data.length > 1 + NONCELEN + opts.maxS2Len)
+                    throw new Error('detached signature too long');
                 // Padded detached signatures are fixed-length (`lengths.signature`), so the payload width
                 // must come from the parameter set, not from the input: deriving it would accept appended
                 // zero bytes and truncated padding as extra valid encodings of the same signature.
                 // Unpadded signatures are variable-length; decodeUnpaddedSig() enforces the exact canonical
                 // bitlength of whatever remains.
-                const payloadLen = opts.padded ? sigLen : data.length - NONCELEN - 1;
+                const payloadLen = opts.padded ? paddedSigLen : data.length - NONCELEN - 1;
                 const [nonce, raw] = headerCoder(0x30 + logn, splitCoder('falcon.detachedSignature', NONCELEN, payloadLen)).decode(data);
                 const s2 = decodeSig(raw);
                 return { nonce, s2 };
@@ -1899,47 +1957,6 @@ function genFalcon(opts) {
                     return s + z;
             }
         }
-        ldlFFT(logn, g00t, g01t, g11t) {
-            // Algorithm 8: LDL*(G)
-            // (Page 37)
-            // Require: A full-rank self-adjoint matrix G = (Gᵢⱼ) ∈ FFT(Q[x]/(φ))²ˣ²
-            // Ensure: The LDL* decomposition G = LDL* over FFT(Q[x]/(φ))
-            // Format: All polynomials are in FFT representation.
-            // 1: D₀₀ ← G₀₀
-            // 2: L₁₀ ← G₁₀/G₀₀
-            // 3: D₁₁ ← G₁₁ - L₁₀ ⊙ L₁₀* ⊙ G₀₀
-            // 4: L ← [ 1 0 ; L₁₀ 1 ], D ← [ D₀₀ 0 ; 0 D₁₁ ]
-            // 5: return (L, D)
-            // Algorithm 9: ffLDL*(G)
-            // (Page 37)
-            // Require: A full-rank Gram matrix G ∈ FFT(Q[x]/(xⁿ + 1))²ˣ²
-            // Ensure: A binary tree T
-            // Format: All polynomials are in FFT representation.
-            // 1: (L, D) ← LDL*(G) ▷ L = [ 1 0 ; L₁₀ 1 ], D = [ D₀₀ 0 ; 0 D₁₁ ]
-            // 2: T.value ← L₁₀
-            // 3: if (n = 2) then
-            // 4:     T.leftchild ← D₀₀
-            // 5:     T.rightchild ← D₁₁
-            // 6:     return T
-            // 7: else
-            // 8:     d₀₀, d₀₁ ← splitfft(D₀₀) ▷ dᵢⱼ ∈ FFT(Q[x]/(x^{n/2} + 1))
-            // 9:     d₁₀, d₁₁ ← splitfft(D₁₁)
-            // 10:     G₀ ← [ d₀₀ d₀₁ ; d₀₁* d₀₀ ], G₁ ← [ d₁₀ d₁₁ ; d₁₁* d₁₀ ]
-            //         ▷ Since D₀₀, D₁₁ are self-adjoint, (3.30) applies
-            // 11:     T.leftchild ← ffLDL*(G₀) ▷ Recursive calls
-            // 12:     T.rightchild ← ffLDL*(G₁)
-            // 13:     return T
-            g00t = g00t.slice(); // can be same as g11t and everything will break!
-            const hn = 1 << (logn - 1);
-            for (let i = 0; i < hn; i++) {
-                const g01 = g01t[i];
-                const g11 = g11t[i];
-                const mu = fComplex.scale(g01, 1.0 / g00t[i].re);
-                g11t[i] = { re: g11.re - (mu.re * g01.re + mu.im * g01.im), im: g11.im };
-                g01t[i] = fComplex.conj(mu);
-            }
-            return { g00: g00t, g01: g01t, g11: g11t };
-        }
         splitFFT(logn, f) {
             // Algorithm 1: splitfft(FFT(f))
             // (Page 29)
@@ -2045,7 +2062,13 @@ function genFalcon(opts) {
             // 13: z₀ ← mergefft(z'₀)
             // 14: return z = (z₀, z₁)
             if (logn === 0) {
+                // The dynamic sampler stores 1/σ' instead of σ'. Keygen guarantees this interval,
+                // but an imported compact key may reconstruct an invalid basis. Check the actual LDL*
+                // leaf before it can drive SamplerZ; the negated comparison also rejects NaN/infinity.
                 const leaf = Math.sqrt(g00i[0].re) * INV_SIGMA[this.logn];
+                const sigmaPrime = 1 / leaf;
+                if (!(sigmaPrime >= SIGMA_MIN[this.logn] && sigmaPrime <= SIGMA_MAX))
+                    throw new Error('invalid secretKey: sampler sigma out of range');
                 // 3:     z₀ ← SamplerZ(t₀, σ')
                 //        ▷ Since n=1, tᵢ = invFFT(tᵢ) ∈ Q and zᵢ = invFFT(zᵢ) ∈ Z
                 const t0re = this.samplerZ(t0[0].re, leaf);
@@ -2053,7 +2076,7 @@ function genFalcon(opts) {
                 return { t0: [{ re: t0re, im: 0.0 }], t1: [{ re: t1re, im: 0.0 }] };
             }
             // 6: (l, T₀, T₁) ← (T.value, T.leftchild, T.rightchild)
-            const { g00, g01, g11 } = this.ldlFFT(logn, g00i, g01i, g11i);
+            const { g00, g01, g11 } = ldlFFT(logn, g00i, g01i, g11i);
             const { f0: g00f0, f1: g00f1 } = this.splitSelfAdjFFT(logn, g00);
             const { f0: g11f0, f1: g11f1 } = this.splitSelfAdjFFT(logn, g11);
             // 7: t'₁ ← splitfft(t₁)
@@ -2203,10 +2226,15 @@ function genFalcon(opts) {
         publicKey: publicKeyCoder.bytesLen,
         secretKey: secretKeyCoder.bytesLen,
     });
+    // Falcon takes a sampler callback the other schemes do not, and rejects `context`
+    // with its own message; both stay in the accepted set so the specific errors fire.
+    const FALCON_SIG_OPT_KEYS = [...SIG_OPT_KEYS, 'random'];
     // Noble exposes a 48-byte sampler-seed hook,
     // but Falcon still samples/encodes a separate 40-byte nonce per signature.
     const getRnd = (opts = {}) => {
-        validateSigOpts(opts);
+        // `context` stays in the accepted set so the specific "not supported" error below
+        // still fires, rather than the generic unexpected-option one.
+        opts = validateSigOpts(opts, FALCON_SIG_OPT_KEYS);
         if (opts.context !== undefined)
             throw new Error('context is not supported');
         if (opts.random !== undefined && typeof opts.random !== 'function')
@@ -2221,8 +2249,8 @@ function genFalcon(opts) {
         return (len = 0) => drbg.randomBytes(len);
     };
     const checkVerOpts = (opts = {}) => {
-        validateVerOpts(opts);
-        if (opts.context !== undefined)
+        const normalized = validateVerOpts(opts);
+        if (normalized.context !== undefined)
             throw new Error('context is not supported');
     };
     const tests = Object.freeze({
@@ -2296,12 +2324,43 @@ function genFalcon(opts) {
         },
         open(sig, pk, verOpts = {}) {
             checkVerOpts(verOpts);
-            const { s2, nonce, msg } = SignatureCoder.decode(sig);
-            // Zero-copy API: returned message aliases the caller-provided signature buffer.
-            // Copy it if ownership is needed.
-            if (verifyRaw(pk, s2, nonce, msg))
-                return msg;
-            throw new Error('invalid signature');
+            // Wrong argument types are caller bugs and must stay TypeErrors; only what happens
+            // after this is untrusted input. Detached verify() type-checks the public key the same
+            // way, so open() does too: a wrong type is fatal, and a malformed (wrong-length or
+            // non-canonical) key folds into the single rejection below rather than leaking a raw
+            // codec error, exactly as detached verify() folds it into `false`.
+            abytes(sig, undefined, 'signature');
+            abytes(pk, undefined, 'publicKey');
+            // Decode and verify owned snapshots. Apart from keeping the authenticated result stable
+            // after open() returns, this ensures every verification step observes the same bytes when
+            // an input is backed by SharedArrayBuffer or has subclass-overridden view methods.
+            const ownedSig = copyBytes(sig);
+            const ownedPk = copyBytes(pk);
+            // Decode failures and malformed-key failures are rejected signatures, not internal
+            // faults. Letting the codec's own errors out gave a caller handling untrusted input
+            // several different messages for one corrupt byte, including "end of buffer: len=2
+            // buf=0 lastByte=undefined", which reads as a library bug. Detached verify already
+            // treats every such failure uniformly; open() collapses them into one Error (the
+            // original preserved as `cause`). A well-formed signature that simply does not
+            // validate falls through to the same message with no cause.
+            try {
+                let verifiedMsg;
+                try {
+                    const { s2, nonce, msg } = SignatureCoder.decode(ownedSig);
+                    if (verifyRaw(ownedPk, s2, nonce, msg))
+                        verifiedMsg = msg;
+                }
+                catch (cause) {
+                    throw new Error('invalid signature', { cause });
+                }
+                if (verifiedMsg === undefined)
+                    throw new Error('invalid signature');
+                // Do not retain or expose the full attached-signature allocation through `.buffer`.
+                return copyBytes(verifiedMsg);
+            }
+            finally {
+                cleanBytes(ownedSig, ownedPk);
+            }
         },
     });
     const res = {
@@ -2318,14 +2377,14 @@ function genFalcon(opts) {
 }
 const falcon512opts = {
     N: 512,
+    // Keep the mode an own property: omitted config fields must not inherit from Object.prototype.
+    padded: false,
     // Table 3.3 fixed padded detached bytes, including the detached header byte and 40-byte nonce.
     sigLen: 666,
     fgBits: 6,
     FGBits: 8,
     // Compressed-s payload bytes only, excluding the detached header byte and 40-byte nonce.
     paddedLen: 625,
-    // Payload-only budget: genFalcon() adds the detached header byte and 40-byte nonce around it.
-    detachedLen: 690,
 };
 /**
  * Falcon-512 detached-signature API with the attached helper exposed as `.attached`.
@@ -2357,14 +2416,13 @@ export const falcon512padded = /* @__PURE__ */ (() => genFalcon({
 }))();
 const falcon1024opts = {
     N: 1024,
+    padded: false,
     // Table 3.3 fixed padded detached bytes, including the detached header byte and 40-byte nonce.
     sigLen: 1280,
     fgBits: 5,
     FGBits: 8,
     // Compressed-s payload bytes only, excluding the detached header byte and 40-byte nonce.
     paddedLen: 1239,
-    // Payload-only budget: genFalcon() adds the detached header byte and 40-byte nonce around it.
-    detachedLen: 1280,
 };
 /**
  * Falcon-1024 detached-signature API with the attached helper exposed as `.attached`.
@@ -2405,6 +2463,7 @@ export const __tests = /* @__PURE__ */ (() => Object.freeze({
     INV_SIGMA,
     SIGMA_MIN,
     getFloatPoly,
+    ldlFFT,
     cleanCPoly,
     falcon512: falcon512.__test,
     falcon512padded: falcon512padded.__test,

package/hybrid.d.ts

@@ -84,6 +84,12 @@ type CurveSign = ECDSA | EdDSA;
 /**
  * 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.
@@ -99,12 +105,12 @@ type CurveSign = ECDSA | EdDSA;
  * 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 declare function ecdhKem(curve: CurveECDH, allowZeroKey?: boolean): TRet<KEM>;
+export declare function _ecdhKem(curve: CurveECDH, allowZeroKey?: boolean): TRet<KEM>;
 /**
  * Wraps a curve signer as a generic `Signer`.
  * Signatures stay in the wrapped curve's native byte encoding.
@@ -151,12 +157,18 @@ export declare function expandSeedXof(xof: TArg<XOF>): TRet<ExpandSeed>;
 export type Combiner = (publicKeys: TArg<Uint8Array[]>, cipherTexts: TArg<Uint8Array[]>, sharedSecrets: TArg<Uint8Array[]>) => TRet<Uint8Array>;
 /**
  * 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
@@ -179,10 +191,15 @@ realMsgLen: number | undefined, // how much bytes combiner returns
 expandSeed: TArg<ExpandSeed>, combiner: TArg<Combiner>, ...kems: TArg<KEM[]>): TRet<KEM>;
 /**
  * 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
@@ -211,14 +228,16 @@ export declare function combineSigners(realSeedLen: number | undefined, expandSe
  * @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;
  * ```
  */
@@ -241,15 +260,17 @@ export declare const QSF_ml_kem1024_p384: TRet<KEM>;
  * @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;
  * ```
  */