@theqrl/dilithium5 1.2.1 → 1.2.3

package/dist/mjs/dilithium5.d.mts

@@ -44,11 +44,13 @@ export const zetas: readonly number[];
  * @param seed - Optional 32-byte seed for deterministic key generation (null for random)
  * @param pk - Output buffer for public key (must be CryptoPublicKeyBytes length)
  * @param sk - Output buffer for secret key (must be CryptoSecretKeyBytes length)
- * @returns The seed used for key generation
+ * @returns The seed used for key generation. **Secret-key-equivalent**: anyone
+ *   holding it can regenerate the full keypair — store it with the same care
+ *   as `sk` and `zeroize()` it when no longer needed.
  * @throws Error if pk/sk buffers are wrong size or null
  */
 export function cryptoSignKeypair(
-  seed: Uint8Array | null,
+  seed: Uint8Array | null | undefined,
   pk: Uint8Array,
   sk: Uint8Array
 ): Uint8Array;
@@ -182,43 +184,73 @@ export function zeroize(buffer: Uint8Array): void;
  */
 export function isZero(buffer: Uint8Array): boolean;
 
+/**
+ * Zero the coefficient arrays of a polynomial vector (best-effort, see
+ * SECURITY.md). Centralizes the secret-wiping pattern used by signing paths.
+ *
+ * @deprecated Internal API — its parameter types (`PolyVecK`/`PolyVecL`) are
+ * themselves internal and cannot be constructed through the documented
+ * surface, so this is a stable function over deprecated types. Not part of
+ * the stable documented API; will move behind a subpath or be removed at the
+ * next major version. See CONTRIBUTING.md "Public API surface policy".
+ */
+export function zeroizePolyVec(polyVec: PolyVecK | PolyVecL): void;
+
 // Internal classes (exported but primarily for internal use)
 
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export class Poly {
   coeffs: Int32Array;
   constructor();
   copy(poly: Poly): void;
 }
 
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export class PolyVecK {
   vec: Poly[];
   constructor();
 }
 
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export class PolyVecL {
   vec: Poly[];
   constructor();
   copy(polyVecL: PolyVecL): void;
 }
 
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export class KeccakState {
   constructor();
 }
 
 // Internal functions (exported but primarily for internal use)
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyNTT(a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyInvNTTToMont(a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyChallenge(c: Poly, seed: Uint8Array): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function ntt(a: Int32Array): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function invNTTToMont(a: Int32Array): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function montgomeryReduce(a: bigint): bigint;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function reduce32(a: number): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function cAddQ(a: number): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function decompose(a0: Int32Array, i: number, a: number): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function power2round(a0: Int32Array, i: number, a: number): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function makeHint(a0: number, a1: number): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function useHint(a: number, hint: number): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function packPk(pk: Uint8Array, rho: Uint8Array, t1: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function packSk(
   sk: Uint8Array,
   rho: Uint8Array,
@@ -228,13 +260,16 @@ export function packSk(
   s1: PolyVecL,
   s2: PolyVecK
 ): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function packSig(
   sig: Uint8Array,
   c: Uint8Array,
   z: PolyVecL,
   h: PolyVecK
 ): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function unpackPk(rho: Uint8Array, t1: PolyVecK, pk: Uint8Array): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function unpackSk(
   rho: Uint8Array,
   tr: Uint8Array,
@@ -244,6 +279,7 @@ export function unpackSk(
   s2: PolyVecK,
   sk: Uint8Array
 ): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function unpackSig(
   c: Uint8Array,
   z: PolyVecL,
@@ -252,18 +288,26 @@ export function unpackSig(
 ): number;
 
 // FIPS 202 SHAKE primitives (low-level XOF interface, primarily internal)
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function shake128Init(state: KeccakState): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function shake128Absorb(state: KeccakState, input: Uint8Array): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function shake128Finalize(state: KeccakState): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function shake128SqueezeBlocks(
   out: Uint8Array,
   outputOffset: number,
   nBlocks: number,
   state: KeccakState
 ): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function shake256Init(state: KeccakState): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function shake256Absorb(state: KeccakState, input: Uint8Array): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function shake256Finalize(state: KeccakState): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function shake256SqueezeBlocks(
   out: Uint8Array,
   outputOffset: number,
@@ -272,11 +316,13 @@ export function shake256SqueezeBlocks(
 ): void;
 
 // Dilithium-specific stream initializers
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function dilithiumShake128StreamInit(
   state: KeccakState,
   seed: Uint8Array,
   nonce: number
 ): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function dilithiumShake256StreamInit(
   state: KeccakState,
   seed: Uint8Array,
@@ -284,17 +330,29 @@ export function dilithiumShake256StreamInit(
 ): void;
 
 // Polynomial operations (internal)
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyReduce(a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyCAddQ(a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyAdd(c: Poly, a: Poly, b: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polySub(c: Poly, a: Poly, b: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyShiftL(a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyPointWiseMontgomery(c: Poly, a: Poly, b: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyPower2round(a1: Poly, a0: Poly, a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyDecompose(a1: Poly, a0: Poly, a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyMakeHint(h: Poly, a0: Poly, a1: Poly): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyUseHint(b: Poly, a: Poly, h: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyChkNorm(a: Poly, b: number): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function rejUniform(
   a: Int32Array,
   aOffset: number,
@@ -302,7 +360,9 @@ export function rejUniform(
   buf: Uint8Array,
   bufLen: number
 ): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyUniform(a: Poly, seed: Uint8Array, nonce: number): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function rejEta(
   a: Int32Array,
   aOffset: number,
@@ -310,58 +370,95 @@ export function rejEta(
   buf: Uint8Array,
   bufLen: number
 ): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyUniformEta(a: Poly, seed: Uint8Array, nonce: number): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyZUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyUniformGamma1(a: Poly, seed: Uint8Array, nonce: number): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyEtaPack(r: Uint8Array, rOffset: number, a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyEtaUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyT1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyT1Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyT0Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyT0Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyZPack(r: Uint8Array, rOffset: number, a: Poly): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyW1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
 
 // Polynomial vector operations (internal)
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecMatrixExpand(mat: PolyVecL[], rho: Uint8Array): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecMatrixPointWiseMontgomery(
   t: PolyVecK,
   mat: PolyVecL[],
   v: PolyVecL
 ): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecLUniformEta(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecLUniformGamma1(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecLReduce(v: PolyVecL): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecLAdd(w: PolyVecL, u: PolyVecL, v: PolyVecL): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecLNTT(v: PolyVecL): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecLInvNTTToMont(v: PolyVecL): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecLPointWisePolyMontgomery(
   r: PolyVecL,
   a: Poly,
   v: PolyVecL
 ): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecLPointWiseAccMontgomery(
   w: Poly,
   u: PolyVecL,
   v: PolyVecL
 ): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecLChkNorm(v: PolyVecL, bound: number): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKUniformEta(v: PolyVecK, seed: Uint8Array, nonce: number): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKReduce(v: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKCAddQ(v: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKAdd(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKSub(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKShiftL(v: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKNTT(v: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKInvNTTToMont(v: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKPointWisePolyMontgomery(
   r: PolyVecK,
   a: Poly,
   v: PolyVecK
 ): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKChkNorm(v: PolyVecK, bound: number): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKPower2round(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKDecompose(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKMakeHint(h: PolyVecK, v0: PolyVecK, v1: PolyVecK): number;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKUseHint(w: PolyVecK, u: PolyVecK, h: PolyVecK): void;
+/** @deprecated Internal API — not part of the stable documented surface; will move behind a subpath or be removed at the next major version. See CONTRIBUTING.md "Public API surface policy". */
 export function polyVecKPackW1(r: Uint8Array, w1: PolyVecK): void;

package/dist/mjs/dilithium5.js

@@ -76,7 +76,6 @@ const zetas = [
 class KeccakState {
   constructor() {
     this.hasher = null;
-    this.finalized = false;
   }
 }
 
@@ -84,17 +83,18 @@ class KeccakState {
 
 function shake128Init(state) {
   state.hasher = shake128.create({});
-  state.finalized = false;
 }
 
 function shake128Absorb(state, input) {
   state.hasher.update(input);
 }
 
-function shake128Finalize(state) {
-  // Mark as finalized - actual finalization happens on first xofInto call
-  state.finalized = true;
-}
+/**
+ * No-op retained for API parity with the C reference's absorb/finalize/squeeze
+ * flow: @noble/hashes finalizes the sponge automatically on the first
+ * xofInto() call, so there is no separate finalize step to perform.
+ */
+function shake128Finalize() {}
 
 function shake128SqueezeBlocks(out, outputOffset, nBlocks, state) {
   const len = nBlocks * Shake128Rate;
@@ -106,17 +106,18 @@ function shake128SqueezeBlocks(out, outputOffset, nBlocks, state) {
 
 function shake256Init(state) {
   state.hasher = shake256.create({});
-  state.finalized = false;
 }
 
 function shake256Absorb(state, input) {
   state.hasher.update(input);
 }
 
-function shake256Finalize(state) {
-  // Mark as finalized - actual finalization happens on first xofInto call
-  state.finalized = true;
-}
+/**
+ * No-op retained for API parity with the C reference's absorb/finalize/squeeze
+ * flow: @noble/hashes finalizes the sponge automatically on the first
+ * xofInto() call, so there is no separate finalize step to perform.
+ */
+function shake256Finalize() {}
 
 function shake256SqueezeBlocks(out, outputOffset, nBlocks, state) {
   const len = nBlocks * Shake256Rate;
@@ -135,7 +136,6 @@ function dilithiumShake128StreamInit(state, seed, nonce) {
   shake128Init(state);
   shake128Absorb(state, seed);
   shake128Absorb(state, t);
-  shake128Finalize(state);
 }
 
 function dilithiumShake256StreamInit(state, seed, nonce) {
@@ -149,7 +149,6 @@ function dilithiumShake256StreamInit(state, seed, nonce) {
   shake256Init(state);
   shake256Absorb(state, seed);
   shake256Absorb(state, t);
-  shake256Finalize(state);
 }
 
 function montgomeryReduce(a) {
@@ -448,6 +447,8 @@ function polyUniformGamma1(a, seed, nonce) {
 }
 
 function polyChallenge(cP, seed) {
+  // Invariant tripwire: internal callers always pass a SeedBytes-long
+  // challenge hash; anything else indicates a regression in sign/verify.
   if (seed.length !== SeedBytes) throw new Error('invalid seed length');
 
   let b;
@@ -458,7 +459,6 @@ function polyChallenge(cP, seed) {
   const state = new KeccakState();
   shake256Init(state);
   shake256Absorb(state, seed);
-  shake256Finalize(state);
   shake256SqueezeBlocks(buf, 0, 1, state);
 
   let signs = 0n;
@@ -765,6 +765,9 @@ function polyVecLChkNorm(v, bound) {
 
 function polyVecKUniformEta(v, seed, nonceP) {
   let nonce = nonceP;
+  if (seed.length !== CRHBytes) {
+    throw new Error(`invalid seed length ${seed.length} | Expected length ${CRHBytes}`);
+  }
   for (let i = 0; i < K; ++i) {
     polyUniformEta(v.vec[i], seed, nonce++);
   }
@@ -971,6 +974,10 @@ function packSig(sigP, c, z, h) {
     sig[sigOffset + i] = 0;
   }
 
+  // Invariant tripwires: h produced by polyVecKMakeHint is always binary
+  // with at most OMEGA set coefficients (the sign loop re-samples
+  // otherwise). A violation here means an internal regression upstream —
+  // fail loudly rather than emit a malformed signature.
   let k = 0;
   for (let i = 0; i < K; ++i) {
     for (let j = 0; j < N; ++j) {
@@ -1064,6 +1071,9 @@ function randomBytes(size) {
       cryptoObj.getRandomValues(out.subarray(i, Math.min(size, i + MAX_BYTES)));
     }
     if (size >= 16) {
+      // Invariant tripwire: a healthy CSPRNG never returns 16 leading zero
+      // bytes (p = 2^-128). All-zero output means the platform RNG is
+      // catastrophically broken — refuse to hand it to key generation.
       let acc = 0;
       for (let i = 0; i < 16; i++) acc |= out[i];
       if (acc === 0) throw new Error('getRandomValues returned all zeros');
@@ -1112,6 +1122,22 @@ function zeroize(buffer) {
   }
 }
 
+/**
+ * Attempts to zero the coefficient arrays of a polynomial vector
+ * (PolyVecL/PolyVecK). Centralizes the secret-wiping pattern used by the
+ * signing paths so every sensitive PolyVec is cleared the same way.
+ *
+ * Same BEST-EFFORT caveats as zeroize() — see SECURITY.md.
+ *
+ * @param {{vec: {coeffs: Int32Array}[]}} polyVec - The polynomial vector to zero
+ * @returns {void}
+ */
+function zeroizePolyVec(polyVec) {
+  for (let i = 0; i < polyVec.vec.length; i++) {
+    polyVec.vec[i].coeffs.fill(0);
+  }
+}
+
 /**
  * Checks if a buffer is all zeros.
  * Uses constant-time comparison to avoid timing leaks.
@@ -1143,6 +1169,8 @@ function isZero(buffer) {
  * @private
  */
 function hexToBytes(hex) {
+  // Unreachable via the public API: messageToBytes routes only strings here.
+  // Kept as defense-in-depth for any future direct internal caller.
   /* c8 ignore start */
   if (typeof hex !== 'string') {
     throw new Error('message must be a hex string');
@@ -1192,13 +1220,18 @@ function messageToBytes(message) {
  *   Pass null or undefined for random key generation.
  * @param {Uint8Array} pk - Output buffer for public key (must be CryptoPublicKeyBytes = 2592 bytes)
  * @param {Uint8Array} sk - Output buffer for secret key (must be CryptoSecretKeyBytes = 4896 bytes)
- * @returns {Uint8Array} The seed used for key generation (useful when passedSeed is null)
+ * @returns {Uint8Array} The seed used for key generation (useful when passedSeed is null).
+ *   **The returned seed is secret-key-equivalent**: anyone holding it can
+ *   regenerate the full keypair. Store it with the same care as `sk` and
+ *   `zeroize()` it as soon as it is no longer needed.
  * @throws {Error} If pk/sk buffers are null or wrong size, or if seed is wrong size
  *
  * @example
  * const pk = new Uint8Array(CryptoPublicKeyBytes);
  * const sk = new Uint8Array(CryptoSecretKeyBytes);
  * const seed = cryptoSignKeypair(null, pk, sk);
+ * // ... persist or use seed (it can regenerate sk!) ...
+ * zeroize(seed);
  */
 function cryptoSignKeypair(passedSeed, pk, sk) {
   try {
@@ -1272,10 +1305,10 @@ function cryptoSignKeypair(passedSeed, pk, sk) {
     zeroize(seedBuf);
     zeroize(rhoPrime);
     zeroize(key);
-    for (let i = 0; i < L; i++) s1.vec[i].coeffs.fill(0);
-    for (let i = 0; i < K; i++) s2.vec[i].coeffs.fill(0);
-    if (s1hat) for (let i = 0; i < L; i++) s1hat.vec[i].coeffs.fill(0);
-    for (let i = 0; i < K; i++) t0.vec[i].coeffs.fill(0);
+    zeroizePolyVec(s1);
+    zeroizePolyVec(s2);
+    if (s1hat) zeroizePolyVec(s1hat);
+    zeroizePolyVec(t0);
   }
 }
 
@@ -1340,7 +1373,10 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
     const mu = shake256.create({}).update(tr).update(mBytes).xof(CRHBytes);
 
     if (randomizedSigning) {
-      rhoPrime = new Uint8Array(randomBytes(CRHBytes));
+      // randomBytes already returns a fresh Uint8Array; assign it directly so
+      // no unwiped intermediate copy is left behind (rhoPrime is zeroized in
+      // the finally block).
+      rhoPrime = randomBytes(CRHBytes);
     } else {
       rhoPrime = shake256.create({}).update(key).update(mu).xof(CRHBytes);
     }
@@ -1367,7 +1403,7 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
       const cHash = shake256
         .create({})
         .update(mu)
-        .update(sig.slice(0, K * PolyW1PackedBytes))
+        .update(sig.subarray(0, K * PolyW1PackedBytes))
         .xof(SeedBytes);
       sig.set(cHash);
 
@@ -1394,6 +1430,9 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
       polyVecKPointWisePolyMontgomery(h, cp, t0);
       polyVecKInvNTTToMont(h);
       polyVecKReduce(h);
+      // Statistically rare rejection (depends on key/challenge interaction);
+      // no deterministic trigger is known, so it is exercised by long fuzz
+      // campaigns rather than unit vectors.
       /* c8 ignore start */
       if (polyVecKChkNorm(h, GAMMA2) !== 0) {
         continue;
@@ -1402,6 +1441,7 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
 
       polyVecKAdd(w0, w0, h);
       const n = polyVecKMakeHint(h, w0, w1);
+      // Statistically rare rejection — same rationale as the ct0 check above.
       /* c8 ignore start */
       if (n > OMEGA) {
         continue;
@@ -1414,10 +1454,10 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
   } finally {
     zeroize(key);
     zeroize(rhoPrime);
-    for (let i = 0; i < L; i++) s1.vec[i].coeffs.fill(0);
-    for (let i = 0; i < K; i++) s2.vec[i].coeffs.fill(0);
-    for (let i = 0; i < K; i++) t0.vec[i].coeffs.fill(0);
-    for (let i = 0; i < L; i++) y.vec[i].coeffs.fill(0);
+    zeroizePolyVec(s1);
+    zeroizePolyVec(s2);
+    zeroizePolyVec(t0);
+    zeroizePolyVec(y);
   }
 }
 
@@ -1466,13 +1506,14 @@ function cryptoSignSignatureDeterministic(sig, m, sk) {
 function cryptoSign(msg, sk, randomizedSigning) {
   const msgBytes = messageToBytes(msg);
 
+  // Place the message after the signature area. (The C reference uses a
+  // backwards copy because its sm/m buffers may alias; here they never do.)
   const sm = new Uint8Array(CryptoBytes + msgBytes.length);
-  const mLen = msgBytes.length;
-  for (let i = 0; i < mLen; ++i) {
-    sm[CryptoBytes + mLen - 1 - i] = msgBytes[mLen - 1 - i];
-  }
+  sm.set(msgBytes, CryptoBytes);
   const result = cryptoSignSignature(sm, msgBytes, sk, randomizedSigning);
 
+  // Unreachable: cryptoSignSignature returns 0 or throws — defensive
+  // tripwire in case a future change introduces a non-zero failure return.
   /* c8 ignore start */
   if (result !== 0) {
     throw new Error('failed to sign');
@@ -1656,4 +1697,4 @@ function cryptoSignOpenWithReason(sm, pk) {
   return { ok: true, message: msg };
 }
 
-export { BETA, CRHBytes, CryptoBytes, CryptoPublicKeyBytes, CryptoSecretKeyBytes, D, ETA, GAMMA1, GAMMA2, K, KeccakState, L, N, OMEGA, Poly, PolyETAPackedBytes, PolyT0PackedBytes, PolyT1PackedBytes, PolyUniformETANBlocks, PolyUniformGamma1NBlocks, PolyUniformNBlocks, PolyVecHPackedBytes, PolyVecK, PolyVecL, PolyW1PackedBytes, PolyZPackedBytes, Q, QInv, SeedBytes, Shake128Rate, Shake256Rate, Stream128BlockBytes, Stream256BlockBytes, TAU, TRBytes, cAddQ, cryptoSign, cryptoSignDeterministic, cryptoSignKeypair, cryptoSignOpen, cryptoSignOpenWithReason, cryptoSignSignature, cryptoSignSignatureDeterministic, cryptoSignVerify, decompose, dilithiumShake128StreamInit, dilithiumShake256StreamInit, invNTTToMont, isZero, makeHint, montgomeryReduce, ntt, packPk, packSig, packSk, polyAdd, polyCAddQ, polyChallenge, polyChkNorm, polyDecompose, polyEtaPack, polyEtaUnpack, polyInvNTTToMont, polyMakeHint, polyNTT, polyPointWiseMontgomery, polyPower2round, polyReduce, polyShiftL, polySub, polyT0Pack, polyT0Unpack, polyT1Pack, polyT1Unpack, polyUniform, polyUniformEta, polyUniformGamma1, polyUseHint, polyVecKAdd, polyVecKCAddQ, polyVecKChkNorm, polyVecKDecompose, polyVecKInvNTTToMont, polyVecKMakeHint, polyVecKNTT, polyVecKPackW1, polyVecKPointWisePolyMontgomery, polyVecKPower2round, polyVecKReduce, polyVecKShiftL, polyVecKSub, polyVecKUniformEta, polyVecKUseHint, polyVecLAdd, polyVecLChkNorm, polyVecLInvNTTToMont, polyVecLNTT, polyVecLPointWiseAccMontgomery, polyVecLPointWisePolyMontgomery, polyVecLReduce, polyVecLUniformEta, polyVecLUniformGamma1, polyVecMatrixExpand, polyVecMatrixPointWiseMontgomery, polyW1Pack, polyZPack, polyZUnpack, power2round, reduce32, rejEta, rejUniform, shake128Absorb, shake128Finalize, shake128Init, shake128SqueezeBlocks, shake256Absorb, shake256Finalize, shake256Init, shake256SqueezeBlocks, unpackPk, unpackSig, unpackSk, useHint, zeroize, zetas };
+export { BETA, CRHBytes, CryptoBytes, CryptoPublicKeyBytes, CryptoSecretKeyBytes, D, ETA, GAMMA1, GAMMA2, K, KeccakState, L, N, OMEGA, Poly, PolyETAPackedBytes, PolyT0PackedBytes, PolyT1PackedBytes, PolyUniformETANBlocks, PolyUniformGamma1NBlocks, PolyUniformNBlocks, PolyVecHPackedBytes, PolyVecK, PolyVecL, PolyW1PackedBytes, PolyZPackedBytes, Q, QInv, SeedBytes, Shake128Rate, Shake256Rate, Stream128BlockBytes, Stream256BlockBytes, TAU, TRBytes, cAddQ, cryptoSign, cryptoSignDeterministic, cryptoSignKeypair, cryptoSignOpen, cryptoSignOpenWithReason, cryptoSignSignature, cryptoSignSignatureDeterministic, cryptoSignVerify, decompose, dilithiumShake128StreamInit, dilithiumShake256StreamInit, invNTTToMont, isZero, makeHint, montgomeryReduce, ntt, packPk, packSig, packSk, polyAdd, polyCAddQ, polyChallenge, polyChkNorm, polyDecompose, polyEtaPack, polyEtaUnpack, polyInvNTTToMont, polyMakeHint, polyNTT, polyPointWiseMontgomery, polyPower2round, polyReduce, polyShiftL, polySub, polyT0Pack, polyT0Unpack, polyT1Pack, polyT1Unpack, polyUniform, polyUniformEta, polyUniformGamma1, polyUseHint, polyVecKAdd, polyVecKCAddQ, polyVecKChkNorm, polyVecKDecompose, polyVecKInvNTTToMont, polyVecKMakeHint, polyVecKNTT, polyVecKPackW1, polyVecKPointWisePolyMontgomery, polyVecKPower2round, polyVecKReduce, polyVecKShiftL, polyVecKSub, polyVecKUniformEta, polyVecKUseHint, polyVecLAdd, polyVecLChkNorm, polyVecLInvNTTToMont, polyVecLNTT, polyVecLPointWiseAccMontgomery, polyVecLPointWisePolyMontgomery, polyVecLReduce, polyVecLUniformEta, polyVecLUniformGamma1, polyVecMatrixExpand, polyVecMatrixPointWiseMontgomery, polyW1Pack, polyZPack, polyZUnpack, power2round, reduce32, rejEta, rejUniform, shake128Absorb, shake128Finalize, shake128Init, shake128SqueezeBlocks, shake256Absorb, shake256Finalize, shake256Init, shake256SqueezeBlocks, unpackPk, unpackSig, unpackSk, useHint, zeroize, zeroizePolyVec, zetas };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theqrl/dilithium5",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Dilithium-5 cryptography",
   "keywords": [
     "dilithium",
@@ -34,8 +34,6 @@
     "test": "../../node_modules/mocha/bin/mocha.js --require ../../scripts/node-test-setup.cjs --timeout 10000",
     "test:browser": "playwright test",
     "build": "rollup -c && ./fixup",
-    "lint-check": "eslint 'src/**/*.js' 'test/**/*.js'",
-    "lint": "eslint --fix 'src/**/*.js' 'test/**/*.js'",
     "coverage": "c8 npm run test",
     "report-coverage": "c8 --reporter=text-lcov npm run test > coverage.lcov"
   },
@@ -73,7 +71,7 @@
     "prettier": "3.8.3",
     "rollup": "4.60.3",
     "serialize-javascript": "7.0.5",
-    "tar": "7.5.14"
+    "tar": "7.5.15"
   },
   "dependencies": {
     "@noble/hashes": "2.2.0"