@noble/post-quantum 0.5.3 → 0.6.0

package/README.md

@@ -8,6 +8,7 @@ Auditable & minimal JS implementation of post-quantum public-key cryptography.
 - 🦾 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
 
@@ -67,17 +68,20 @@ import {
   slh_dsa_shake_256s,
 } from '@noble/post-quantum/slh-dsa.js';
 import {
-  XWing,
-  KitchenSinkMLKEM768X25519,
-  QSFMLKEM768P256, QSFMLKEM1024P384,
-  MLKEM768P256, MLKEM768X25519, MLKEM1024P384,
-} from '@noble/post-quantum/hybrids.js';
+  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';
 ```
 
 - [ML-KEM / Kyber](#ml-kem--kyber-shared-secrets)
 - [ML-DSA / Dilithium](#ml-dsa--dilithium-signatures)
 - [SLH-DSA / SPHINCS+](#slh-dsa--sphincs-signatures)
-- [Hybrids: XWing, KitchenSink and others](#hybrids-xwing-kitchensink-and-others)
+- [Falcon](#falcon-signatures)
+- [hybrid: XWing, KitchenSink and others](#hybrid-xwing-kitchensink-and-others)
 - [What should I use?](#what-should-i-use)
 - [Security](#security)
 - [Speed](#speed)
@@ -89,6 +93,7 @@ import {
 ```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';
 const seed = randomBytes(64); // seed is optional
 const aliceKeys = ml_kem768.keygen(seed);
 const { cipherText, sharedSecret: bobShared } = ml_kem768.encapsulate(aliceKeys.publicKey);
@@ -100,7 +105,7 @@ const malloryShared = ml_kem768.decapsulate(cipherText, malloryKeys.secretKey);
 notDeepStrictEqual(aliceShared, malloryShared); // Different key!
 ```
 
-Lattice-based key encapsulation mechanism, defined in [FIPS-203](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf).
+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)).
 Can be used as follows:
 
 1. *Alice* generates secret & public keys, then sends publicKey to *Bob*
@@ -110,7 +115,6 @@ Can be used as follows:
   Now, both Alice and Bob have same sharedSecret key
   without exchanging in plainText: aliceShared == bobShared.
 
-See [website](https://www.pq-crystals.org/kyber/resources.shtml) and [repo](https://github.com/pq-crystals/kyber).
 There are some concerns with regards to security: see
 [djb blog](https://blog.cr.yp.to/20231003-countcorrectly.html) and
 [mailing list](https://groups.google.com/a/list.nist.gov/g/pqc-forum/c/W2VOzy0wz_E).
@@ -134,9 +138,8 @@ const sig = ml_dsa65.sign(msg, keys.secretKey);
 const isValid = ml_dsa65.verify(sig, msg, keys.publicKey);
 ```
 
-Lattice-based digital signature algorithm, defined in [FIPS-204](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.204.pdf). See
-[website](https://www.pq-crystals.org/dilithium/index.shtml) and
-[repo](https://github.com/pq-crystals/dilithium).
+Lattice-based digital signature algorithm, defined in [FIPS-204](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.204.pdf) ([website](https://www.pq-crystals.org/dilithium/index.shtml),
+[repo](https://github.com/pq-crystals/dilithium)).
 The internals are similar to ML-KEM, but keys and params are different.
 
 ### SLH-DSA / SPHINCS+ signatures
@@ -163,37 +166,62 @@ const sig2 = sph.sign(msg2, keys2.secretKey);
 const isValid2 = sph.verify(sig2, msg2, keys2.publicKey);
 ```
 
-Hash-based digital signature algorithm, defined in [FIPS-205](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.205.pdf).
-See [website](https://sphincs.org) and [repo](https://github.com/sphincs/sphincsplus). We implement spec v3.1 with FIPS adjustments.
+Hash-based digital signature algorithm, defined in [FIPS-205](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.205.pdf) ([website](https://sphincs.org), [repo](https://github.com/sphincs/sphincsplus)). We implement spec v3.1 with FIPS adjustments.
+
+- sha2 vs shake (sha3): indicates internal hash function used
+- 128 / 192 / 256: indicates security level in bits
+- s / f: indicates small vs fast trade-off
 
-There are many different kinds,
-but basically `sha2` / `shake` indicate internal hash, `128` / `192` / `256` indicate security level, and `s` /`f` indicate trade-off (Small / Fast).
 SLH-DSA is slow: see [benchmarks](#speed) for key size & speed.
 
-### Hybrids: XWing, KitchenSink and others
+### Falcon signatures
+
+```ts
+import { falcon512, falcon1024 } from '@noble/post-quantum/falcon.js';
+import { randomBytes } from '@noble/post-quantum/utils.js';
+const seed3 = randomBytes(48); // seed is optional
+const keys3 = falcon512.keygen(seed3);
+const msg3 = new TextEncoder().encode('hello noble');
+const sig3 = falcon512.sign(msg3, keys3.secretKey);
+const isValid3 = falcon512.verify(sig3, msg3, keys3.publicKey);
+```
+
+Lattice-based digital signature algorithm, submitted to NIST PQC Round 3 ([website](https://falcon-sign.info/), [Round 3 submissions](https://csrc.nist.gov/projects/post-quantum-cryptography/post-quantum-cryptography-standardization/round-3-submissions)).
+
+> [!WARNING]
+> This is Falcon Round 3, not FN-DSA. FN-DSA is not final yet.
+> FN-DSA (FIPS-206) would most likely be backwards-incompatible with Falcon.
+> The implementation passes the published Round 3 KATs.
+
+- `falcon512`, `falcon1024`: variable-length detached signatures
+- `falcon512padded`, `falcon1024padded`: fixed-length detached signatures
+- `attached.seal(...)` / `attached.open(...)`: attached-signature API for Round 3 vectors and interop
+
+### hybrid: XWing, KitchenSink and others
 
 ```js
 import {
-  XWing,
-  KitchenSinkMLKEM768X25519,
-  QSFMLKEM768P256, QSFMLKEM1024P384,
-  MLKEM768P256, MLKEM768X25519, MLKEM1024P384,
-} from '@noble/post-quantum/hybrids.js';
+  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';
 ```
 
-- **XWing** / **MLKEM768X25519**: ML-KEM-768 + X25519 (CG Framework)
-- **KitchenSinkMLKEM768X25519**: ML-KEM-768 + X25519 with HKDF-SHA256 combiner
-- **QSFMLKEM768P256**: ML-KEM-768 + P-256 (QSF construction)
-- **QSFMLKEM1024P384**: ML-KEM-1024 + P-384 (QSF construction)
-- **MLKEM768P256**: ML-KEM-768 + P-256 (CG Framework)
-- **MLKEM1024P384**: ML-KEM-1024 + P-384 (CG Framework)
+Hybrid submodule combine 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)
+- `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)
 
 The following spec drafts are matched:
 
-- [irtf-cfrg-hybrid-kems](https://datatracker.ietf.org/doc/draft-irtf-cfrg-hybrid-kems/)
-- [irtf-cfrg-concrete-hybrid-kems](https://datatracker.ietf.org/doc/draft-irtf-cfrg-concrete-hybrid-kems/)
-- [connolly-cfrg-xwing-kem](https://datatracker.ietf.org/doc/draft-connolly-cfrg-xwing-kem/)
-- [tls-westerbaan-xyber768d00](https://datatracker.ietf.org/doc/draft-tls-westerbaan-xyber768d00/)
+- [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/)
 
 ### What should I use?
 
@@ -224,6 +252,8 @@ For [hashes](https://github.com/paulmillr/noble-hashes), use SHA512 or SHA3-512
 
 The library has not been independently audited yet.
 
+v0.6.0 (Mar 2026) has been undergone through a self-audit. All files were in scope.
+
 If you see anything unusual: investigate and report.
 
 ### Constant-timeness
@@ -242,9 +272,10 @@ 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 is 1 dependency; and a few dev dependencies:
+For this package, there are 2 dependencies; and a few dev dependencies:
 
-- [noble-hashes](https://github.com/paulmillr/noble-hashes) provides cryptographic hashing functionality
+- [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
 - 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
 
@@ -260,9 +291,7 @@ Browsers have had weaknesses in the past - and could again - but implementing a
 
 > `npm run bench`
 
-Noble is the fastest JS implementation of post-quantum algorithms.
-WASM libraries can be faster.
-For SLH-DSA, SHAKE slows everything down 8x, and -s versions do another 20-50x slowdown.
+Noble is the fastest JS implementation of post-quantum algorithms. WASM libraries can be faster.
 
 Benchmarks on Apple M4 (**higher is better**):
 
@@ -288,16 +317,18 @@ sign x 8 ops/sec @ 114ms/op
 verify x 169 ops/sec @ 5ms/op
 ```
 
-SLH-DSA (\_shake is 8x slower):
+SLH-DSA:
 
 |           | sig size | keygen | sign   | verify |
 | --------- | -------- | ------ | ------ | ------ |
 | sha2_128f | 18088    | 4ms    | 90ms   | 6ms    |
-| sha2_128s | 7856     | 260ms  | 2000ms | 2ms    |
 | sha2_192f | 35664    | 6ms    | 160ms  | 9ms    |
-| sha2_192s | 16224    | 380ms  | 3800ms | 3ms    |
 | 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    |
 
 ## Contributing & testing
 

package/_crystals.d.ts

@@ -1,34 +1,118 @@
 import type { TypedArray } from '@noble/hashes/utils.js';
 import { type BytesCoderLen, type Coder } from './utils.ts';
+/** Extendable-output reader used by the CRYSTALS implementations. */
 export type XOF = (seed: Uint8Array, blockLen?: number) => {
+    /**
+     * Read diagnostic counters for the current XOF session.
+     * @returns Current call and XOF block counters.
+     */
     stats: () => {
         calls: number;
         xofs: number;
     };
+    /**
+     * Select one `(x, y)` coordinate pair and get a block reader for it.
+     * Only one coordinate stream is live at a time: a later `get(...)` call rebinds the shared
+     * SHAKE state and invalidates older readers.
+     * Each squeeze aliases one mutable internal output buffer, so callers must copy blocks they
+     * want to retain before the next read.
+     * @param x - First matrix coordinate.
+     * @param y - Second matrix coordinate.
+     * @returns Lazy block reader for that coordinate pair.
+     */
     get: (x: number, y: number) => () => Uint8Array;
+    /** Wipe any buffered state once the reader is no longer needed. */
     clean: () => void;
 };
 /** CRYSTALS (ml-kem, ml-dsa) options */
+/** Shared polynomial and NTT parameters for CRYSTALS algorithms. */
 export type CrystalOpts<T extends TypedArray> = {
+    /**
+     * Allocate one zeroed polynomial/vector container.
+     * @param n - Number of coefficients to allocate.
+     * @returns Fresh typed container.
+     */
     newPoly: TypedCons<T>;
+    /** Polynomial size, typically `256`. */
     N: number;
+    /** Prime modulus used for all coefficient arithmetic. */
     Q: number;
+    /** Inverse transform normalization factor:
+     * `256**-1 mod q` for Dilithium, `128**-1 mod q` for Kyber.
+     */
     F: number;
+    /** Principal root of unity for the transform domain. */
     ROOT_OF_UNITY: number;
+    /** Number of bits used for bit-reversal ordering. */
     brvBits: number;
+    /** `true` for Kyber/ML-KEM mode, `false` for Dilithium/ML-DSA mode. */
     isKyber: boolean;
 };
+/** Constructor function for typed polynomial containers. */
 export type TypedCons<T extends TypedArray> = (n: number) => T;
+/**
+ * Creates shared modular arithmetic, NTT, and packing helpers for CRYSTALS schemes.
+ * @param opts - Polynomial and transform parameters. See {@link CrystalOpts}.
+ * @returns CRYSTALS arithmetic and encoding helpers.
+ * @example
+ * Create shared modular arithmetic and NTT helpers for a CRYSTALS parameter set.
+ * ```ts
+ * const crystals = genCrystals({
+ *   newPoly: (n) => new Uint16Array(n),
+ *   N: 256,
+ *   Q: 3329,
+ *   F: 3303,
+ *   ROOT_OF_UNITY: 17,
+ *   brvBits: 7,
+ *   isKyber: true,
+ * });
+ * const reduced = crystals.mod(-1);
+ * ```
+ */
 export declare const genCrystals: <T extends TypedArray>(opts: CrystalOpts<T>) => {
     mod: (a: number, modulo?: number) => number;
     smod: (a: number, modulo?: number) => number;
     nttZetas: T;
     NTT: {
+        /** Forward transform in place. Mutates and returns `r`. */
         encode: (r: T) => T;
+        /** Inverse transform in place. Mutates and returns `r`. */
         decode: (r: T) => T;
     };
     bitsCoder: (d: number, c: Coder<number, number>) => BytesCoderLen<T>;
 };
+/**
+ * SHAKE128-based extendable-output reader factory used by ML-KEM.
+ * `get(x, y)` selects one coordinate pair at a time; calling it again invalidates previously
+ * returned readers, and each squeeze reuses one mutable internal output buffer.
+ * @param seed - Seed bytes for the reader.
+ * @param blockLen - Optional output block length.
+ * @returns Stateful XOF reader.
+ * @example
+ * Build the ML-KEM SHAKE128 matrix expander and read one block.
+ * ```ts
+ * import { randomBytes } from '@noble/post-quantum/utils.js';
+ * import { XOF128 } from '@noble/post-quantum/_crystals.js';
+ * const reader = XOF128(randomBytes(32));
+ * const block = reader.get(0, 0)();
+ * ```
+ */
 export declare const XOF128: XOF;
+/**
+ * SHAKE256-based extendable-output reader factory used by ML-DSA.
+ * `get(x, y)` appends raw one-byte coordinates to the seed, invalidates previously returned
+ * readers, and reuses one mutable internal output buffer for each squeeze.
+ * @param seed - Seed bytes for the reader.
+ * @param blockLen - Optional output block length.
+ * @returns Stateful XOF reader.
+ * @example
+ * Build the ML-DSA SHAKE256 coefficient expander and read one block.
+ * ```ts
+ * import { randomBytes } from '@noble/post-quantum/utils.js';
+ * import { XOF256 } from '@noble/post-quantum/_crystals.js';
+ * const reader = XOF256(randomBytes(32));
+ * const block = reader.get(0, 0)();
+ * ```
+ */
 export declare const XOF256: XOF;
 //# sourceMappingURL=_crystals.d.ts.map

package/_crystals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_crystals.d.ts","sourceRoot":"","sources":["src/_crystals.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,KAAK,aAAa,EAAc,KAAK,KAAK,EAAW,MAAM,YAAY,CAAC;AAEjF,MAAM,MAAM,GAAG,GAAG,CAChB,IAAI,EAAE,UAAU,EAChB,QAAQ,CAAC,EAAE,MAAM,KACd;IACH,KAAK,EAAE,MAAM;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,UAAU,CAAC;IAChD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF,wCAAwC;AACxC,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,IAAI;IAC9C,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,UAAU,IAAI,CAAC,CAAC,EAAE,MAAM,KAAK,CAAC,CAAC;AAE/D,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,UAAU,EAC9C,MAAM,WAAW,CAAC,CAAC,CAAC,KACnB;IACD,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7C,QAAQ,EAAE,CAAC,CAAC;IACZ,GAAG,EAAE;QACH,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;KACrB,CAAC;IACF,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC;CAuFtE,CAAC;AAsCF,eAAO,MAAM,MAAM,EAAE,GAA8C,CAAC;AACpE,eAAO,MAAM,MAAM,EAAE,GAA8C,CAAC"}
+{"version":3,"file":"_crystals.d.ts","sourceRoot":"","sources":["src/_crystals.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,KAAK,aAAa,EAAc,KAAK,KAAK,EAAW,MAAM,YAAY,CAAC;AAEjF,qEAAqE;AACrE,MAAM,MAAM,GAAG,GAAG,CAChB,IAAI,EAAE,UAAU,EAChB,QAAQ,CAAC,EAAE,MAAM,KACd;IACH;;;OAGG;IACH,KAAK,EAAE,MAAM;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C;;;;;;;;;OASG;IACH,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,UAAU,CAAC;IAChD,mEAAmE;IACnE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF,wCAAwC;AACxC,oEAAoE;AACpE,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,IAAI;IAC9C;;;;OAIG;IACH,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACtB,wCAAwC;IACxC,CAAC,EAAE,MAAM,CAAC;IACV,yDAAyD;IACzD,CAAC,EAAE,MAAM,CAAC;IACV;;OAEG;IACH,CAAC,EAAE,MAAM,CAAC;IACV,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,4DAA4D;AAC5D,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,UAAU,IAAI,CAAC,CAAC,EAAE,MAAM,KAAK,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,UAAU,EAC9C,MAAM,WAAW,CAAC,CAAC,CAAC,KACnB;IACD,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7C,QAAQ,EAAE,CAAC,CAAC;IACZ,GAAG,EAAE;QACH,2DAA2D;QAC3D,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;QACpB,2DAA2D;QAC3D,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;KACrB,CAAC;IACF,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC;CA+FtE,CAAC;AAwCF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,EAAE,GAA8C,CAAC;AACpE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,EAAE,GAA8C,CAAC"}

package/_crystals.js

@@ -6,19 +6,43 @@
 import { FFTCore, reverseBits } from '@noble/curves/abstract/fft.js';
 import { shake128, shake256 } from '@noble/hashes/sha3.js';
 import { cleanBytes, getMask } from "./utils.js";
+/**
+ * Creates shared modular arithmetic, NTT, and packing helpers for CRYSTALS schemes.
+ * @param opts - Polynomial and transform parameters. See {@link CrystalOpts}.
+ * @returns CRYSTALS arithmetic and encoding helpers.
+ * @example
+ * Create shared modular arithmetic and NTT helpers for a CRYSTALS parameter set.
+ * ```ts
+ * const crystals = genCrystals({
+ *   newPoly: (n) => new Uint16Array(n),
+ *   N: 256,
+ *   Q: 3329,
+ *   F: 3303,
+ *   ROOT_OF_UNITY: 17,
+ *   brvBits: 7,
+ *   isKyber: true,
+ * });
+ * const reduced = crystals.mod(-1);
+ * ```
+ */
 export const genCrystals = (opts) => {
     // isKyber: true means Kyber, false means Dilithium
     const { newPoly, N, Q, F, ROOT_OF_UNITY, brvBits, isKyber } = 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;
         return (result >= 0 ? result | 0 : (modulo + result) | 0) | 0;
     };
-    // -(Q-1)/2 < a <= (Q-1)/2
+    // FIPS 204 §7.4 uses the centered `mod ±` representative for low bits, keeping the
+    // positive midpoint when `modulo` is even.
+    // Center to `[-floor((modulo-1)/2), floor(modulo/2)]`.
     const smod = (a, modulo = Q) => {
         const r = mod(a, modulo) | 0;
         return (r > modulo >> 1 ? (r - modulo) | 0 : r) | 0;
     };
-    // Generate zettas (different from roots of unity, negacyclic uses phi, where acyclic uses omega)
+    // Kyber uses the FIPS 203 Appendix A `BitRev_7` table here via the first 128 entries, while
+    // Dilithium uses the FIPS 204 §7.5 / Appendix B `BitRev_8` zetas table over all 256 entries.
     function getZettas() {
         const out = newPoly(N);
         for (let i = 0; i < N; i++) {
@@ -56,13 +80,16 @@ export const genCrystals = (opts) => {
         },
         decode: (r) => {
             dit(r);
+            // The inverse-NTT normalization factor is family-specific: FIPS 203 Algorithm 10 line 14
+            // uses `128^-1 mod q` for Kyber, while FIPS 204 Algorithm 42 lines 21-23 use `256^-1 mod q`.
             // kyber uses 128 here, because brv && stuff
             for (let i = 0; i < r.length; i++)
                 r[i] = mod(F * r[i]);
             return r;
         },
     };
-    // Encode polynominal as bits
+    // 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) => {
         const mask = getMask(d);
         const bytesLen = d * (N / 8);
@@ -109,6 +136,8 @@ const createXofShake = (shake) => (seed, blockLen) => {
     return {
         stats: () => ({ calls, xofs }),
         get: (x, y) => {
+            // Rebind to `seed || x || y` so callers can implement the spec's per-coordinate
+            // SHAKE inputs like `rho || j || i` and `rho || IntegerToBytes(counter, 2)`.
             _seed[seedLen + 0] = x;
             _seed[seedLen + 1] = y;
             h.destroy();
@@ -125,6 +154,38 @@ const createXofShake = (shake) => (seed, blockLen) => {
         },
     };
 };
+/**
+ * SHAKE128-based extendable-output reader factory used by ML-KEM.
+ * `get(x, y)` selects one coordinate pair at a time; calling it again invalidates previously
+ * returned readers, and each squeeze reuses one mutable internal output buffer.
+ * @param seed - Seed bytes for the reader.
+ * @param blockLen - Optional output block length.
+ * @returns Stateful XOF reader.
+ * @example
+ * Build the ML-KEM SHAKE128 matrix expander and read one block.
+ * ```ts
+ * import { randomBytes } from '@noble/post-quantum/utils.js';
+ * import { XOF128 } from '@noble/post-quantum/_crystals.js';
+ * const reader = XOF128(randomBytes(32));
+ * const block = reader.get(0, 0)();
+ * ```
+ */
 export const XOF128 = /* @__PURE__ */ createXofShake(shake128);
+/**
+ * SHAKE256-based extendable-output reader factory used by ML-DSA.
+ * `get(x, y)` appends raw one-byte coordinates to the seed, invalidates previously returned
+ * readers, and reuses one mutable internal output buffer for each squeeze.
+ * @param seed - Seed bytes for the reader.
+ * @param blockLen - Optional output block length.
+ * @returns Stateful XOF reader.
+ * @example
+ * Build the ML-DSA SHAKE256 coefficient expander and read one block.
+ * ```ts
+ * import { randomBytes } from '@noble/post-quantum/utils.js';
+ * import { XOF256 } from '@noble/post-quantum/_crystals.js';
+ * const reader = XOF256(randomBytes(32));
+ * const block = reader.get(0, 0)();
+ * ```
+ */
 export const XOF256 = /* @__PURE__ */ createXofShake(shake256);
 //# sourceMappingURL=_crystals.js.map

package/_crystals.js.map

@@ -1 +1 @@
-{"version":3,"file":"_crystals.js","sourceRoot":"","sources":["src/_crystals.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"_crystals.js","sourceRoot":"","sources":["src/_crystals.ts"],"names":[],"mappings":"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"}

package/falcon.d.ts

@@ -0,0 +1,84 @@
+import { randomBytes } from '@noble/hashes/utils.js';
+import { type CryptoKeys, type Signer, type SigOpts, type VerOpts } from './utils.ts';
+type FalconSigOpts = SigOpts & {
+    random?: typeof randomBytes;
+};
+/** Falcon attached-signature API. */
+export type FalconAttached = CryptoKeys & {
+    /** Key lengths plus the 48-byte sampler-seed hook for signing. */
+    lengths: CryptoKeys['lengths'] & {
+        signRand?: number;
+    };
+    /**
+     * Signs a message and appends it to the returned attached signature.
+     * @param msg Message bytes to sign.
+     * @param secretKey Falcon secret key bytes.
+     * @param opts Optional Falcon signing options.
+     * @returns Attached signature containing both the message and signature.
+     */
+    seal(msg: Uint8Array, secretKey: Uint8Array, opts?: FalconSigOpts): Uint8Array;
+    /**
+     * Verifies an attached signature and returns the embedded message.
+     * @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.
+     */
+    open(sig: Uint8Array, publicKey: Uint8Array, opts?: VerOpts): Uint8Array;
+};
+/** Falcon detached-signature API with an attached-signature helper. */
+export type Falcon = Signer & {
+    /** Attached-signature helper for the same Falcon parameter set. */
+    attached: FalconAttached;
+};
+/**
+ * Falcon-512 detached-signature API with the attached helper exposed as `.attached`.
+ * @example
+ * Generate a Falcon-512 keypair and verify one detached signature.
+ * ```ts
+ * const { secretKey, publicKey } = falcon512.keygen();
+ * const msg = new Uint8Array([1, 2, 3]);
+ * const sig = falcon512.sign(msg, secretKey);
+ * falcon512.verify(sig, msg, publicKey);
+ * ```
+ */
+export declare const falcon512: Falcon;
+/**
+ * Falcon-512 padded detached-signature API with the attached helper exposed as `.attached`.
+ * @example
+ * Generate a Falcon-512 padded keypair and verify one detached signature.
+ * ```ts
+ * const { secretKey, publicKey } = falcon512padded.keygen();
+ * const msg = new Uint8Array([1, 2, 3]);
+ * const sig = falcon512padded.sign(msg, secretKey);
+ * falcon512padded.verify(sig, msg, publicKey);
+ * ```
+ */
+export declare const falcon512padded: Falcon;
+/**
+ * Falcon-1024 detached-signature API with the attached helper exposed as `.attached`.
+ * @example
+ * Generate a Falcon-1024 keypair and verify one detached signature.
+ * ```ts
+ * const { secretKey, publicKey } = falcon1024.keygen();
+ * const msg = new Uint8Array([1, 2, 3]);
+ * const sig = falcon1024.sign(msg, secretKey);
+ * falcon1024.verify(sig, msg, publicKey);
+ * ```
+ */
+export declare const falcon1024: Falcon;
+/**
+ * Falcon-1024 padded detached-signature API with the attached helper exposed as `.attached`.
+ * @example
+ * Generate a Falcon-1024 padded keypair and verify one detached signature.
+ * ```ts
+ * const { secretKey, publicKey } = falcon1024padded.keygen();
+ * const msg = new Uint8Array([1, 2, 3]);
+ * const sig = falcon1024padded.sign(msg, secretKey);
+ * falcon1024padded.verify(sig, msg, publicKey);
+ * ```
+ */
+export declare const falcon1024padded: Falcon;
+export declare const __tests: any;
+export {};
+//# sourceMappingURL=falcon.d.ts.map

package/falcon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"falcon.d.ts","sourceRoot":"","sources":["src/falcon.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,WAAW,EAKZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAIL,KAAK,UAAU,EAEf,KAAK,MAAM,EACX,KAAK,OAAO,EAKZ,KAAK,OAAO,EACb,MAAM,YAAY,CAAC;AA2oCpB,KAAK,aAAa,GAAG,OAAO,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,WAAW,CAAA;CAAE,CAAC;AAC/D,qCAAqC;AACrC,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG;IACxC,kEAAkE;IAClE,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,UAAU,CAAC;IAC/E;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CAC1E,CAAC;AACF,uEAAuE;AACvE,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,cAAc,CAAC;CAC1B,CAAC;AAioCF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,EAAE,MAC2B,CAAC;AACpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,EAAE,MAKvB,CAAC;AAaR;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,MAIlB,CAAC;AACR;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAKxB,CAAC;AAGR,eAAO,MAAM,OAAO,EAAE,GAYjB,CAAC"}