@theqrl/dilithium5 1.2.1 → 1.2.3

package/README.md

@@ -26,10 +26,11 @@ const pk = new Uint8Array(CryptoPublicKeyBytes);  // 2592 bytes
 const sk = new Uint8Array(CryptoSecretKeyBytes);  // 4896 bytes
 cryptoSignKeypair(null, pk, sk);  // null = random seed
 
-// Sign a message (hedged by default — recommended per TOB-QRLLIB-6).
-// Pass `false` only when deterministic signatures are themselves a
-// protocol requirement (e.g. KAT vector reproduction); for that case
-// use `cryptoSignDeterministic`.
+// Sign a message. The randomized flag is required — there is no default;
+// hedged (`true`) is the recommended mode. Pass `false` only when
+// deterministic signatures are themselves a protocol requirement
+// (e.g. KAT vector reproduction); for that case use
+// `cryptoSignDeterministic`.
 const message = new TextEncoder().encode('Hello, quantum world!');
 const signedMessage = cryptoSign(message, sk, true);  // true = hedged (recommended)
 
@@ -121,7 +122,7 @@ Check if buffer is all zeros (constant-time).
 go-qrllib pre-hashes seeds with SHAKE256 before key generation. To generate matching keys:
 
 ```javascript
-import { shake256 } from '@noble/hashes/sha3';
+import { shake256 } from '@noble/hashes/sha3.js';
 
 // go-qrllib: hashedSeed = SHAKE256(rawSeed)[:32]
 const hashedSeed = shake256(rawSeed, { dkLen: 32 });

package/dist/cjs/dilithium5.d.cts

@@ -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/cjs/dilithium5.js

@@ -707,7 +707,6 @@ genShake(0x1f, 136, 32, /* @__PURE__ */ oidNist(0x0c));
 class KeccakState {
   constructor() {
     this.hasher = null;
-    this.finalized = false;
   }
 }
 
@@ -715,17 +714,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;
@@ -737,17 +737,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;
@@ -766,7 +767,6 @@ function dilithiumShake128StreamInit(state, seed, nonce) {
   shake128Init(state);
   shake128Absorb(state, seed);
   shake128Absorb(state, t);
-  shake128Finalize(state);
 }
 
 function dilithiumShake256StreamInit(state, seed, nonce) {
@@ -780,7 +780,6 @@ function dilithiumShake256StreamInit(state, seed, nonce) {
   shake256Init(state);
   shake256Absorb(state, seed);
   shake256Absorb(state, t);
-  shake256Finalize(state);
 }
 
 function montgomeryReduce(a) {
@@ -1079,6 +1078,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;
@@ -1089,7 +1090,6 @@ function polyChallenge(cP, seed) {
   const state = new KeccakState();
   shake256Init(state);
   shake256Absorb(state, seed);
-  shake256Finalize(state);
   shake256SqueezeBlocks(buf, 0, 1, state);
 
   let signs = 0n;
@@ -1396,6 +1396,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++);
   }
@@ -1602,6 +1605,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) {
@@ -1695,6 +1702,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');
@@ -1743,6 +1753,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.
@@ -1774,6 +1800,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');
@@ -1823,13 +1851,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 {
@@ -1903,10 +1936,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);
   }
 }
 
@@ -1971,7 +2004,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);
     }
@@ -1998,7 +2034,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);
 
@@ -2025,6 +2061,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;
@@ -2033,6 +2072,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;
@@ -2045,10 +2085,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);
   }
 }
 
@@ -2097,13 +2137,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');
@@ -2411,4 +2452,5 @@ exports.unpackSig = unpackSig;
 exports.unpackSk = unpackSk;
 exports.useHint = useHint;
 exports.zeroize = zeroize;
+exports.zeroizePolyVec = zeroizePolyVec;
 exports.zetas = zetas;