@noble/post-quantum 0.5.4 → 0.6.1

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
 
@@ -66,6 +67,9 @@ import {
   slh_dsa_shake_256f,
   slh_dsa_shake_256s,
 } from '@noble/post-quantum/slh-dsa.js';
+import {
+  falcon512, falcon512padded, falcon1024, falcon1024padded,
+} from '@noble/post-quantum/falcon.js';
 import {
   ml_kem768_x25519, ml_kem768_p256, ml_kem1024_p384,
   KitchenSink_ml_kem768_x25519, XWing,
@@ -76,6 +80,7 @@ import {
 - [ML-KEM / Kyber](#ml-kem--kyber-shared-secrets)
 - [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)
 - [What should I use?](#what-should-i-use)
 - [Security](#security)
@@ -88,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);
@@ -99,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*
@@ -109,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).
@@ -133,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
@@ -162,13 +166,37 @@ 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.
 
+### 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
@@ -224,6 +252,10 @@ For [hashes](https://github.com/paulmillr/noble-hashes), use SHA512 or SHA3-512
 
 The library has not been independently audited yet.
 
+- at version 0.6.1, in Apr 2026, it was audited by ourselves (self-audited)
+  - Scope: everything
+  - [Changes since audit](https://github.com/paulmillr/noble-post-quantum/compare/0.6.1..main)
+
 If you see anything unusual: investigate and report.
 
 ### Constant-timeness
@@ -242,9 +274,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
 
@@ -256,36 +289,61 @@ 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`
 
-Noble is the fastest JS implementation of post-quantum algorithms. WASM libraries can be faster.
+Noble is the fastest JS implementation of post-quantum algorithms.
 
 Benchmarks on Apple M4 (**higher is better**):
 
-| OPs/sec           | Keygen | Signing | Verification | Shared secret |
-| ----------------- | ------ | ------- | ------------ | ------------- |
-| ECC x/ed25519     | 14216  | 6849    | 1400         | 1981          |
-| ML-KEM-768        | 3778   |         |              | 3750          |
-| ML-DSA65          | 580    | 272     | 546          |               |
-| SLH-DSA-SHA2-192f | 245    | 8       | 169          |               |
-
 ```
 # ML-KEM768
-keygen x 3,778 ops/sec @ 264μs/op
-encapsulate x 3,220 ops/sec @ 310μs/op
-decapsulate x 4,029 ops/sec @ 248μs/op
+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 580 ops/sec @ 1ms/op
-sign x 272 ops/sec @ 3ms/op
-verify x 546 ops/sec @ 1ms/op
+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 245 ops/sec @ 4ms/op
-sign x 8 ops/sec @ 114ms/op
-verify x 169 ops/sec @ 5ms/op
+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
 ```
 
+Compared with pre-quantum:
+
+| OPs/sec           | 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 |
@@ -299,20 +357,6 @@ SLH-DSA:
 | shake_192f | 35664   | 21ms   | 553ms  | 29ms   |
 | shake_192s | 16224   | 260ms  | 2635ms | 2ms    |
 
-## 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.
-
 ## License
 
 The MIT License (MIT)

package/_crystals.d.ts

@@ -1,34 +1,120 @@
 import type { TypedArray } from '@noble/hashes/utils.js';
-import { type BytesCoderLen, type Coder } from './utils.ts';
+import { type BytesCoderLen, type Coder, type TRet } 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;
-export declare const genCrystals: <T extends TypedArray>(opts: CrystalOpts<T>) => {
+type Crystals<T extends TypedArray> = {
     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>;
 };
-export declare const XOF128: XOF;
-export declare const XOF256: XOF;
+/**
+ * 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>) => TRet<Crystals<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: TRet<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: TRet<XOF>;
+export {};
 //# 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,EACL,KAAK,aAAa,EAElB,KAAK,KAAK,EAGV,KAAK,IAAI,EACV,MAAM,YAAY,CAAC;AAEpB,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,KAAK,QAAQ,CAAC,CAAC,SAAS,UAAU,IAAI;IACpC,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;CACtE,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,UAAU,EAAE,MAAM,WAAW,CAAC,CAAC,CAAC,KAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAwGxF,CAAC;AAwCF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,EAAE,IAAI,CAAC,GAAG,CAA4C,CAAC;AAC1E;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,EAAE,IAAI,CAAC,GAAG,CAA4C,CAAC"}

package/_crystals.js

@@ -5,20 +5,44 @@
 /*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */
 import { FFTCore, reverseBits } from '@noble/curves/abstract/fft.js';
 import { shake128, shake256 } from '@noble/hashes/sha3.js';
-import { cleanBytes, getMask } from "./utils.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,19 +80,23 @@ 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);
         return {
             bytesLen,
-            encode: (poly) => {
+            encode: (poly_) => {
+                const poly = poly_;
                 const r = new Uint8Array(bytesLen);
                 for (let i = 0, buf = 0, bufLen = 0, pos = 0; i < poly.length; i++) {
                     buf |= (c.encode(poly[i]) & mask) << bufLen;
@@ -90,7 +118,16 @@ export const genCrystals = (opts) => {
             },
         };
     };
-    return { mod, smod, nttZetas, NTT, bitsCoder };
+    return {
+        mod,
+        smod,
+        nttZetas: nttZetas,
+        NTT: {
+            encode: (r) => NTT.encode(r),
+            decode: (r) => NTT.decode(r),
+        },
+        bitsCoder: bitsCoder,
+    };
 };
 const createXofShake = (shake) => (seed, blockLen) => {
     if (!blockLen)
@@ -109,6 +146,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 +164,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 { type CryptoKeys, type Signer, type SigOpts, type TRet, type VerOpts } from './utils.ts';
+type FalconRandom = (bytesLength?: number) => TRet<Uint8Array>;
+type FalconSigOpts = SigOpts & {
+    random?: FalconRandom;
+};
+/** 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: TRet<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: TRet<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: TRet<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: TRet<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":"AAyBA,OAAO,EAKL,KAAK,UAAU,EAEf,KAAK,MAAM,EACX,KAAK,OAAO,EAGZ,KAAK,IAAI,EAGT,KAAK,OAAO,EACb,MAAM,YAAY,CAAC;AA0oCpB,KAAK,YAAY,GAAG,CAAC,WAAW,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,UAAU,CAAC,CAAC;AAC/D,KAAK,aAAa,GAAG,OAAO,GAAG;IAAE,MAAM,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC;AACzD,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;AA+pCF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,EAAE,IAAI,CAAC,MAAM,CACgB,CAAC;AACpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,EAAE,IAAI,CAAC,MAAM,CAKlC,CAAC;AAaR;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,IAAI,CAAC,MAAM,CAI7B,CAAC;AACR;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAKnC,CAAC;AAGR,eAAO,MAAM,OAAO,EAAE,GAaf,CAAC"}