@noble/post-quantum 0.6.1 → 0.7.1

package/README.md

@@ -3,22 +3,20 @@
 Auditable & minimal JS implementation of post-quantum public-key cryptography.
 
 - 🔒 Auditable
-- 🔻 Tree-shakeable: unused code is excluded from your builds
-- 🔍 Reliable: tests ensure correctness
+- 🪶 Minimal: 7KB (gzipped) ML-KEM, unused code is excluded from your builds
+- 🏎 Fast: hand-optimized for caveats of JS engines
+- 🔍 Reliable: ACVP / wycheproof tests ensure correctness
 - 🦾 ML-KEM & CRYSTALS-Kyber: lattice-based KEM from FIPS-203
 - 🔋 ML-DSA & CRYSTALS-Dilithium: lattice-based signatures from FIPS-204
 - 🐈 SLH-DSA & SPHINCS+: hash-based Winternitz signatures from FIPS-205
 - 🦅 Falcon: lattice-based signatures from Falcon Round 3
-- 🍡 Hybrid algorithms, combining classic & post-quantum: Concrete, XWing, KitchenSink
-- 🪶 16KB (gzipped) for everything, including bundled hashes & curves
-
-Take a glance at [GitHub Discussions](https://github.com/paulmillr/noble-post-quantum/discussions) for questions and support.
+- 🍡 Hybrid algorithms (combining classic & post-quantum)
 
 > [!IMPORTANT]
-> NIST published [IR 8547](https://nvlpubs.nist.gov/nistpubs/ir/2024/NIST.IR.8547.ipd.pdf),
-> prohibiting classical cryptography (RSA, DSA, ECDSA, ECDH) after 2035.
-> Australian ASD does same thing [after 2030](https://www.cyber.gov.au/resources-business-and-government/essential-cyber-security/ism/cyber-security-guidelines/guidelines-cryptography).
-> Take it into an account while designing a new cryptographic system.
+> NIST published draft [IR 8547](https://nvlpubs.nist.gov/nistpubs/ir/2024/NIST.IR.8547.ipd.pdf),
+> which proposes prohibiting classical cryptography (RSA, DSA, ECDSA, ECDH) after 2035.
+> Australia's ASD does the same [after 2030](https://www.cyber.gov.au/resources-business-and-government/essential-cyber-security/ism/cyber-security-guidelines/guidelines-cryptography).
+> Take this into account when designing new cryptographic systems.
 
 ### This library belongs to _noble_ cryptography
 
@@ -34,6 +32,7 @@ Take a glance at [GitHub Discussions](https://github.com/paulmillr/noble-post-qu
   [post-quantum](https://github.com/paulmillr/noble-post-quantum),
   5kb [secp256k1](https://github.com/paulmillr/noble-secp256k1) /
   [ed25519](https://github.com/paulmillr/noble-ed25519)
+- WASM version: [awasm-noble](https://github.com/paulmillr/awasm-noble)
 - [Check out the homepage](https://paulmillr.com/noble/)
   for reading resources, documentation, and apps built with noble
 
@@ -72,8 +71,7 @@ import {
 } 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,
+  KitchenSink_ml_kem768_x25519, QSF_ml_kem768_p256, QSF_ml_kem1024_p384,
 } from '@noble/post-quantum/hybrid.js';
 ```
 
@@ -81,19 +79,18 @@ 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)
-- [Speed](#speed)
 - [Contributing & testing](#contributing--testing)
+- [Speed](#speed)
 - [License](#license)
 
 ### ML-KEM / Kyber shared secrets
 
 ```ts
 import { ml_kem512, ml_kem768, ml_kem1024 } from '@noble/post-quantum/ml-kem.js';
-import { randomBytes } from '@noble/post-quantum/utils.js';
-import { notDeepStrictEqual } from 'node:assert';
+import { equalBytes, randomBytes } from '@noble/post-quantum/utils.js';
 const seed = randomBytes(64); // seed is optional
 const aliceKeys = ml_kem768.keygen(seed);
 const { cipherText, sharedSecret: bobShared } = ml_kem768.encapsulate(aliceKeys.publicKey);
@@ -102,7 +99,7 @@ const aliceShared = ml_kem768.decapsulate(cipherText, aliceKeys.secretKey);
 // Warning: Can be MITM-ed
 const malloryKeys = ml_kem768.keygen();
 const malloryShared = ml_kem768.decapsulate(cipherText, malloryKeys.secretKey); // No error!
-notDeepStrictEqual(aliceShared, malloryShared); // Different key!
+console.log(equalBytes(aliceShared, malloryShared)); // false: different key!
 ```
 
 Lattice-based key encapsulation mechanism, defined in [FIPS-203](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf) ([website](https://www.pq-crystals.org/kyber/resources.shtml), [repo](https://github.com/pq-crystals/kyber)).
@@ -126,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
@@ -142,6 +158,35 @@ Lattice-based digital signature algorithm, defined in [FIPS-204](https://nvlpubs
 [repo](https://github.com/pq-crystals/dilithium)).
 The internals are similar to ML-KEM, but keys and params are different.
 
+`sign` / `verify` accept optional parameters:
+
+```ts
+import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js';
+import { sha512 } from '@noble/hashes/sha2.js';
+const keys = ml_dsa65.keygen();
+const msg = new TextEncoder().encode('hello noble');
+const ctx = new Uint8Array([1, 2, 3]);
+const sigCtx = ml_dsa65.sign(msg, keys.secretKey, { context: ctx }); // verify needs same context
+const sigDet = ml_dsa65.sign(msg, keys.secretKey, { extraEntropy: false }); // deterministic
+const hml = ml_dsa65.prehash(sha512); // HashML-DSA
+const sigPre = hml.sign(msg, keys.secretKey);
+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
+- `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
@@ -172,6 +217,9 @@ Hash-based digital signature algorithm, defined in [FIPS-205](https://nvlpubs.ni
 - 128 / 192 / 256: indicates security level in bits
 - s / f: indicates small vs fast trade-off
 
+`sign` / `verify` accept the same optional `context`, `extraEntropy` and `prehash(hash)`
+(HashSLH-DSA) parameters as ML-DSA. With `extraEntropy: false`, signing is deterministic.
+
 SLH-DSA is slow: see [benchmarks](#speed) for key size & speed.
 
 ### Falcon signatures
@@ -197,53 +245,87 @@ 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 {
   ml_kem768_x25519, ml_kem768_p256, ml_kem1024_p384,
-  KitchenSink_ml_kem768_x25519, XWing,
+  KitchenSink_ml_kem768_x25519,
   QSF_ml_kem768_p256, QSF_ml_kem1024_p384,
 } from '@noble/post-quantum/hybrid.js';
 ```
 
-Hybrid submodule combine post-quantum algorithms with elliptic curve cryptography:
+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`.
 
-The following spec drafts are matched:
+> **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.
 
-- [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/)
+The current `ml_kem*` presets are tested against these work-in-progress specifications:
+
+- [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)
+
+`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?
 
-|         | Speed  | Key size    | Sig size    | Created in | Popularized in | Post-quantum? |
-| ------- | ------ | ----------- | ----------- | ---------- | -------------- | ------------- |
-| RSA     | Normal | 256B - 2KB  | 256B - 2KB  | 1970s      | 1990s          | No            |
-| ECC     | Normal | 32 - 256B   | 48 - 128B   | 1980s      | 2010s          | No            |
-| ML-KEM  | Fast   | 1.6 - 31KB  | 1KB         | 1990s      | 2020s          | Yes           |
-| ML-DSA  | Normal | 1.3 - 2.5KB | 2.5 - 4.5KB | 1990s      | 2020s          | Yes           |
-| SLH-DSA | Slow   | 32 - 128B   | 17 - 50KB   | 1970s      | 2020s          | Yes           |
-| FN-DSA  | Slow   | 0.9 - 1.8KB | 0.6 - 1.2KB | 1990s      | 2020s          | Yes           |
+|         | Speed  | Key size    | Sig / CT size | Created in | Popularized in | Post-quantum? |
+| ------- | ------ | ----------- | ------------- | ---------- | -------------- | ------------- |
+| RSA     | Normal | 256B - 2KB  | 256B - 2KB    | 1970s      | 1990s          | No            |
+| ECC     | Normal | 32 - 256B   | 48 - 128B     | 1980s      | 2010s          | No            |
+| ML-KEM  | Fast   | 0.8 - 1.6KB | 0.8 - 1.6KB   | 1990s      | 2020s          | Yes           |
+| ML-DSA  | Normal | 1.3 - 2.5KB | 2.5 - 4.5KB   | 1990s      | 2020s          | Yes           |
+| SLH-DSA | Slow   | 32 - 128B   | 17 - 50KB     | 1970s      | 2020s          | Yes           |
+| FN-DSA  | Slow   | 0.9 - 1.8KB | 0.6 - 1.2KB   | 1990s      | 2020s          | Yes           |
 
-We suggest to use ECC + ML-KEM for key agreement, ECC + SLH-DSA for signatures.
+ML-KEM is a KEM, not a signature scheme: its last column is ciphertext (CT) size.
+We suggest using ECC + ML-KEM for key agreement, ECC + SLH-DSA for signatures.
 
 ML-KEM and ML-DSA are lattice-based. SLH-DSA is hash-based, which means it is built on top of older, more conservative primitives. NIST guidance for security levels:
 
 - Category 3 (~AES-192): ML-KEM-768, ML-DSA-65, SLH-DSA-192
 - Category 5 (~AES-256): ML-KEM-1024, ML-DSA-87, SLH-DSA-256
 
-NIST recommends to use cat-3+, while australian [ASD only allows cat-5 after 2030](https://www.cyber.gov.au/resources-business-and-government/essential-cyber-security/ism/cyber-security-guidelines/guidelines-cryptography).
+NIST recommends cat-3+, while Australian [ASD only allows cat-5 after 2030](https://www.cyber.gov.au/resources-business-and-government/essential-cyber-security/ism/cyber-security-guidelines/guidelines-cryptography).
 
-It's also useful to check out [NIST SP 800-131Ar3](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar3.ipd.pdf)
+It's also useful to check out draft [NIST SP 800-131Ar3](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-131Ar3.ipd.pdf)
 for "Transitioning the Use of Cryptographic Algorithms and Key Lengths".
 
 For [hashes](https://github.com/paulmillr/noble-hashes), use SHA512 or SHA3-512 (not SHA256); and for [ciphers](https://github.com/paulmillr/noble-ciphers) ensure AES-256 or ChaCha.
@@ -260,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
 
@@ -274,10 +370,11 @@ Keep in mind that even hardware versions ML-KEM [are vulnerable](https://eprint.
   - Version ranges are locked, and changes are checked with npm-diff.
 - **Dev dependencies** are excluded from end-user installs; they're only used for development and build steps.
 
-For this package, there are 2 dependencies; and a few dev dependencies:
+For this package, there are 3 dependencies; and a few dev dependencies:
 
 - [noble-hashes](https://github.com/paulmillr/noble-hashes) provides cryptographic hashing functionality, used internally in every algorithm
 - [noble-curves](https://github.com/paulmillr/noble-curves) provides elliptic curve cryptography for hybrid algorithms
+- [noble-ciphers](https://github.com/paulmillr/noble-ciphers) provides AES-CTR DRBG and ChaCha20, used internally in Falcon
 - jsbt is used for benchmarking / testing / build tooling and developed by the same author
 - prettier, fast-check and typescript are used for code quality / test generation / ts compilation
 
@@ -289,73 +386,63 @@ which is considered a cryptographically secure PRNG.
 
 Browsers have had weaknesses in the past - and could again - but implementing a userspace CSPRNG is even worse, as there’s no reliable userspace source of high-quality entropy.
 
-## Contributing & testing
-
-- `npm install && npm run build && npm test` will build the code and run tests.
-- `npm run lint` / `npm run format` will run linter / fix linter issues.
-- `npm run bench` will run benchmarks
-- `npm run build:release` will build single file
-
-Check out [github.com/paulmillr/guidelines](https://github.com/paulmillr/guidelines)
-for general coding practices and rules.
-
-See [paulmillr.com/noble](https://paulmillr.com/noble/)
-for useful resources, articles, documentation and demos
-related to the library.
-
 ## Speed
 
-> `npm run bench`
+> `npm run benchmark`
 
 Noble is the fastest JS implementation of post-quantum algorithms.
 
-Benchmarks on Apple M4 (**higher is better**):
+There is experimental [git branch](https://github.com/paulmillr/noble-post-quantum/tree/awasm),
+which uses WASM-based [awasm-noble](https://github.com/paulmillr/awasm-noble) for hashing.
+It has 80% faster ML-KEM, 30% faster ML-DSA, 2.3x faster SLH-DSA-SHA256, 15x faster SLH-DSA-SHAKE.
+Try it out.
 
-```
-# ML-KEM768
-keygen x 4,277 ops/sec @ 233μs/op
-encapsulate x 3,470 ops/sec @ 288μs/op
-decapsulate x 3,757 ops/sec @ 266μs/op
-# ML-DSA65
-keygen x 669 ops/sec @ 1ms/op
-sign x 271 ops/sec @ 3ms/op
-verify x 565 ops/sec @ 1ms/op
-# SLH-DSA SHA2 192f
-keygen x 235 ops/sec @ 4ms/op
-sign x 8 ops/sec @ 117ms/op
-verify x 159 ops/sec @ 6ms/op
-# Falcon512
-keygen x 14 ops/sec @ 66ms/op ± 11.01% (56ms..96ms)
-sign x 749 ops/sec @ 1ms/op
-verify x 2,160 ops/sec @ 462μs/op
-# Falcon1024
-keygen x 4 ops/sec @ 247ms/op ± 5.22% (234ms..266ms)
-sign x 343 ops/sec @ 2ms/op
-verify x 950 ops/sec @ 1ms/op
-```
+Benchmarks on Apple M4 (operations/sec, **higher is better**):
 
-Compared with pre-quantum:
-
-| OPs/sec           | Keygen | Signing | Verification | Shared secret |
+| Primitive         | Keygen | Signing | Verification | Shared secret |
 | ----------------- | ------ | ------- | ------------ | ------------- |
-| ECC x/ed25519     | 12648  | 6157    | 1255         | 1981          |
-| ML-KEM-768        | 4277   |         |              | 3757          |
-| ML-DSA65          | 669    | 271     | 565          |               |
-| SLH-DSA-SHA2-192f | 235    | 8       | 159          |               |
-| Falcon512         | 14     | 749     | 950          |               |
-
-SLH-DSA:
-
-|           | sig size | keygen | sign   | verify |
-| --------- | -------- | ------ | ------ | ------ |
-| sha2_128f | 18088    | 4ms    | 90ms   | 6ms    |
-| sha2_192f | 35664    | 6ms    | 160ms  | 9ms    |
-| sha2_256f | 49856    | 15ms   | 340ms  | 9ms    |
-| sha2_128s | 7856     | 260ms  | 2000ms | 2ms    |
-| sha2_192s | 16224    | 380ms  | 3800ms | 3ms    |
-| sha2_256s | 29792    | 250ms  | 3400ms | 4ms    |
-| shake_192f | 35664   | 21ms   | 553ms  | 29ms   |
-| shake_192s | 16224   | 260ms  | 2635ms | 2ms    |
+| ML-KEM-768        | 4661   |         |              | 4089          |
+| ML-DSA-65         | 719    | 294     | 610          |               |
+| Falcon512         | 14     | 749     | 2160         |               |
+| SLH-DSA-SHA2-192f | 321    | 11       | 198          |               |
+| Pre-quantum x/ed25519 | 12648  | 6157    | 1255         | 1981          |
+
+SLH-DSA (`s` variants have 2x shorter signatures; SHAKE is very slow):
+
+|            | keygen | sign   | verify |
+| ---------- | ------ | ------ | ------ |
+| sha2_128f  | 2ms    | 47ms   | 3ms    |
+| shake_128f | 10ms   | 237ms  | 14ms   |
+| sha2_192f  | 3.2ms  | 93ms   | 5.1ms  |
+| shake_192f | 15ms   | 396ms  | 21ms   |
+| sha2_256f  | 8.5ms  | 187ms  | 5.2ms  |
+| shake_256f | 40ms   | 813ms  | 22ms   |
+| sha2_128s  | 140ms  | 1068ms | 1.1ms  |
+| shake_128s | 673ms  | 5114ms | 5.2ms  |
+| sha2_192s  | 209ms  | 2114ms | 1.9ms  |
+| shake_192s | 974ms  | 8779ms | 7.1ms  |
+| sha2_256s  | 137ms  | 1941ms | 2.7ms  |
+| shake_256s | 645ms  | 7689ms | 11ms   |
+
+Key and signature sizes:
+
+| Variant | Public key | Secret key | Signature / Ciphertext |
+|---|---:|---:|---:|
+| ML-KEM-512 | 800 | 1632 | 768 |
+| ML-KEM-768 | 1184 | 2400 | 1088 |
+| ML-KEM-1024 | 1568 | 3168 | 1568 |
+| ML-DSA-44 | 1312 | 2560 | 2420 |
+| ML-DSA-65 | 1952 | 4032 | 3309 |
+| ML-DSA-87 | 2592 | 4896 | 4627 |
+| Falcon512 | 897 | 1281 | 666 |
+| Falcon1024 | 1793 | 2305 | 1280 |
+| SLH-DSA-128f | 32 | 64 | 17088 |
+| SLH-DSA-128s | 32 | 64 | 7856 |
+| SLH-DSA-192f | 48 | 96 | 35664 |
+| SLH-DSA-192s | 48 | 96 | 16224 |
+| SLH-DSA-256f | 64 | 128 | 49856 |
+| SLH-DSA-256s | 64 | 128 | 29792 |
+
 
 ## License
 

package/_crystals.d.ts

@@ -55,9 +55,15 @@ type Crystals<T extends TypedArray> = {
     smod: (a: number, modulo?: number) => number;
     nttZetas: T;
     NTT: {
-        /** Forward transform in place. Mutates and returns `r`. */
+        /**
+         * Forward transform in place. Mutates and returns `r`.
+         * Kyber-mode input coefficients must already use canonical representatives in `[0, Q)`.
+         */
         encode: (r: T) => T;
-        /** Inverse transform in place. Mutates and returns `r`. */
+        /**
+         * Inverse transform in place. Mutates and returns `r`.
+         * Kyber-mode input coefficients must already use canonical representatives in `[0, Q)`.
+         */
         decode: (r: T) => T;
     };
     bitsCoder: (d: number, c: Coder<number, number>) => BytesCoderLen<T>;
@@ -117,4 +123,3 @@ export declare const XOF128: TRet<XOF>;
  */
 export declare const XOF256: TRet<XOF>;
 export {};
-//# sourceMappingURL=_crystals.d.ts.map

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
@@ -57,14 +57,34 @@ export const genCrystals = (opts) => {
     // Explained: https://electricdusk.com/ntt.html
     // Kyber has slightly different params, since there is no 512th primitive root of unity mod q,
     // only 256th primitive root of unity mod. Which also complicates MultiplyNTT.
-    const field = {
-        add: (a, b) => mod((a | 0) + (b | 0)) | 0,
-        sub: (a, b) => mod((a | 0) - (b | 0)) | 0,
-        mul: (a, b) => mod((a | 0) * (b | 0)) | 0,
-        inv: (_a) => {
-            throw new Error('not implemented');
-        },
+    const inv = (_a) => {
+        throw new Error('not implemented');
     };
+    // ML-KEM (Kyber) polynomials always enter the transform reduced to [0, Q), so add/sub only
+    // need one conditional correction instead of `%`; measured ~20% faster NTT there.
+    // ML-DSA keeps the generic mod() path on purpose: its first forward stage sees centered
+    // (negative) coefficients, and `sub(a, t)` can drop below -Q (t is a mul output in [0, Q)),
+    // so a single correction is not enough. A guarded fast path with mod() fallback was measured
+    // slower than plain `%` for the 23-bit Q (V8 int32 modulo is one div; the branches lose).
+    const field = isKyber
+        ? {
+            add: (a, b) => {
+                const r = (a + b) | 0;
+                return r >= Q ? (r - Q) | 0 : r;
+            },
+            sub: (a, b) => {
+                const r = (a - b) | 0;
+                return r < 0 ? (r + Q) | 0 : r;
+            },
+            mul: (a, b) => mod((a | 0) * (b | 0)) | 0,
+            inv,
+        }
+        : {
+            add: (a, b) => mod((a | 0) + (b | 0)) | 0,
+            sub: (a, b) => mod((a | 0) - (b | 0)) | 0,
+            mul: (a, b) => mod((a | 0) * (b | 0)) | 0,
+            inv,
+        };
     const nttOpts = {
         N,
         roots: nttZetas,
@@ -91,6 +111,13 @@ export const genCrystals = (opts) => {
     // Pack one little-endian `d`-bit word per coefficient, matching FIPS 203 ByteEncode /
     // ByteDecode and the FIPS 204 BitsToBytes-based polynomial packing helpers.
     const bitsCoder = (d, c) => {
+        // Validate the carry shape once: JS bitwise operations silently truncate wider accumulators.
+        for (let i = 0, bufLen = 0; i < N; i++) {
+            bufLen += d;
+            if (bufLen > 32)
+                getMask(bufLen);
+            bufLen %= 8;
+        }
         const mask = getMask(d);
         const bytesLen = d * (N / 8);
         return {
@@ -101,8 +128,10 @@ export const genCrystals = (opts) => {
                 for (let i = 0, buf = 0, bufLen = 0, pos = 0; i < poly.length; i++) {
                     buf |= (c.encode(poly[i]) & mask) << bufLen;
                     bufLen += d;
+                    // Take the low byte directly: `& 0xff` matches the previous getMask(bufLen) result
+                    // after Uint8Array truncation, without a validated function call per output byte.
                     for (; bufLen >= 8; bufLen -= 8, buf >>= 8)
-                        r[pos++] = buf & getMask(bufLen);
+                        r[pos++] = buf & 0xff;
                 }
                 return r;
             },
@@ -198,4 +227,3 @@ export const XOF128 = /* @__PURE__ */ createXofShake(shake128);
  * ```
  */
 export const XOF256 = /* @__PURE__ */ createXofShake(shake256);
-//# sourceMappingURL=_crystals.js.map

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;
 };
@@ -81,4 +81,3 @@ export declare const falcon1024: TRet<Falcon>;
 export declare const falcon1024padded: TRet<Falcon>;
 export declare const __tests: any;
 export {};
-//# sourceMappingURL=falcon.d.ts.map