@theqrl/dilithium5 1.1.2 → 1.2.0

package/README.md

@@ -26,9 +26,12 @@ const pk = new Uint8Array(CryptoPublicKeyBytes);  // 2592 bytes
 const sk = new Uint8Array(CryptoSecretKeyBytes);  // 4896 bytes
 cryptoSignKeypair(null, pk, sk);  // null = random seed
 
-// Sign a message
+// 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`.
 const message = new TextEncoder().encode('Hello, quantum world!');
-const signedMessage = cryptoSign(message, sk, false);  // false = deterministic
+const signedMessage = cryptoSign(message, sk, true);  // true = hedged (recommended)
 
 // Verify and extract
 const extracted = cryptoSignOpen(signedMessage, pk);
@@ -144,6 +147,7 @@ See [SECURITY.md](../../SECURITY.md) for important information about:
 
 - JavaScript memory security limitations
 - Constant-time verification
+- **Signing timing variability** — signing is not constant-time due to the algorithm's rejection sampling loop; see SECURITY.md for measured impact and deployment mitigations
 - Secure key handling recommendations
 
 ## Requirements

package/dist/cjs/dilithium5.d.cts

@@ -0,0 +1,367 @@
+/**
+ * TypeScript definitions for @theqrl/dilithium5
+ * Dilithium-5 post-quantum digital signature scheme
+ */
+
+// Constants
+export const Shake128Rate: number;
+export const Shake256Rate: number;
+export const Stream128BlockBytes: number;
+export const Stream256BlockBytes: number;
+export const SeedBytes: number;
+export const CRHBytes: number;
+export const TRBytes: number;
+export const N: number;
+export const Q: number;
+export const QInv: number;
+export const D: number;
+export const K: number;
+export const L: number;
+export const ETA: number;
+export const TAU: number;
+export const BETA: number;
+export const GAMMA1: number;
+export const GAMMA2: number;
+export const OMEGA: number;
+export const PolyT1PackedBytes: number;
+export const PolyT0PackedBytes: number;
+export const PolyETAPackedBytes: number;
+export const PolyZPackedBytes: number;
+export const PolyVecHPackedBytes: number;
+export const PolyW1PackedBytes: number;
+export const CryptoPublicKeyBytes: number;
+export const CryptoSecretKeyBytes: number;
+export const CryptoBytes: number;
+export const PolyUniformNBlocks: number;
+export const PolyUniformETANBlocks: number;
+export const PolyUniformGamma1NBlocks: number;
+export const zetas: readonly number[];
+
+// Core signing functions
+
+/**
+ * Generate a Dilithium-5 key pair
+ * @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
+ * @throws Error if pk/sk buffers are wrong size or null
+ */
+export function cryptoSignKeypair(
+  seed: Uint8Array | null,
+  pk: Uint8Array,
+  sk: Uint8Array
+): Uint8Array;
+
+/**
+ * Create a signature for a message
+ * @param sig - Output buffer for signature (must be CryptoBytes length minimum)
+ * @param m - Message to sign (hex string or Uint8Array; strings are parsed as hex only)
+ * @param sk - Secret key
+ * @param randomizedSigning - If true, use random nonce; if false, deterministic
+ * @returns 0 on success
+ * @throws Error if sk is wrong size
+ */
+export function cryptoSignSignature(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  sk: Uint8Array,
+  randomizedSigning: boolean
+): number;
+
+/**
+ * Sign a message, returning signature concatenated with message
+ * @param msg - Message to sign
+ * @param sk - Secret key
+ * @param randomizedSigning - If true, use random nonce; if false, deterministic
+ * @returns Signed message (signature || message)
+ * @throws Error if signing fails
+ */
+export function cryptoSign(
+  msg: Uint8Array | string,
+  sk: Uint8Array,
+  randomizedSigning: boolean
+): Uint8Array;
+
+/**
+ * Create a deterministic Dilithium5 detached signature
+ * (`randomizedSigning = false` wrapper for `cryptoSignSignature`).
+ *
+ * **Use only when the deterministic property is itself a requirement**.
+ * For general-purpose signing prefer `cryptoSignSignature` with
+ * `randomizedSigning = true` (hedged — TOB-QRLLIB-6).
+ */
+export function cryptoSignSignatureDeterministic(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  sk: Uint8Array
+): number;
+
+/**
+ * Attached-form deterministic Dilithium5 signing
+ * (`randomizedSigning = false` wrapper for `cryptoSign`).
+ * Same recommendation as `cryptoSignSignatureDeterministic`.
+ * (TOB-QRLLIB-6.)
+ */
+export function cryptoSignDeterministic(
+  msg: Uint8Array | string,
+  sk: Uint8Array
+): Uint8Array;
+
+/**
+ * Verify a signature
+ * @param sig - Signature to verify
+ * @param m - Message that was signed (hex string or Uint8Array; strings are parsed as hex only)
+ * @param pk - Public key
+ * @returns true if signature is valid, false otherwise
+ */
+export function cryptoSignVerify(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  pk: Uint8Array
+): boolean;
+
+/**
+ * Open a signed message (verify and extract message)
+ * @param sm - Signed message (signature || message)
+ * @param pk - Public key
+ * @returns Message if valid, undefined if verification fails (or if
+ *   sm is null / undefined / non-Uint8Array / shorter than
+ *   CryptoBytes — see `cryptoSignOpenWithReason` for distinct
+ *   failure-mode reporting)
+ */
+export function cryptoSignOpen(
+  sm: Uint8Array,
+  pk: Uint8Array
+): Uint8Array | undefined;
+
+/**
+ * Failure-mode discriminator returned by `cryptoSignOpenWithReason`.
+ * (TOB-QRLLIB-14: distinct failure modes for Open.)
+ */
+export type CryptoSignOpenReason =
+  | 'invalid-sm-type'
+  | 'invalid-sm-length'
+  | 'invalid-pk'
+  | 'verification-failed';
+
+/**
+ * Open a signed message with a typed failure-mode report.
+ * (TOB-QRLLIB-14.) Behavioural twin of `cryptoSignOpen` that
+ * distinguishes API-shape problems (input wrong type / length /
+ * shape) from genuine verification failures.
+ *
+ * `cryptoSignOpen` is kept unchanged and continues to return
+ * `undefined` for any failure mode. Use this variant when you need
+ * to log or route on specific failure modes.
+ *
+ * @param sm - Signed message (signature || message)
+ * @param pk - Public key
+ */
+export function cryptoSignOpenWithReason(
+  sm: Uint8Array,
+  pk: Uint8Array
+):
+  | { ok: true; message: Uint8Array }
+  | { ok: false; reason: CryptoSignOpenReason };
+
+// Utility functions
+
+/**
+ * Zero out a buffer (best-effort, see SECURITY.md for limitations)
+ * @param buffer - Buffer to zero
+ * @throws TypeError if buffer is not Uint8Array
+ */
+export function zeroize(buffer: Uint8Array): void;
+
+/**
+ * Check if buffer is all zeros using constant-time comparison
+ * @param buffer - Buffer to check
+ * @returns true if all bytes are zero
+ * @throws TypeError if buffer is not Uint8Array
+ */
+export function isZero(buffer: Uint8Array): boolean;
+
+// Internal classes (exported but primarily for internal use)
+
+export class Poly {
+  coeffs: Int32Array;
+  constructor();
+  copy(poly: Poly): void;
+}
+
+export class PolyVecK {
+  vec: Poly[];
+  constructor();
+}
+
+export class PolyVecL {
+  vec: Poly[];
+  constructor();
+  copy(polyVecL: PolyVecL): void;
+}
+
+export class KeccakState {
+  constructor();
+}
+
+// Internal functions (exported but primarily for internal use)
+export function polyNTT(a: Poly): void;
+export function polyInvNTTToMont(a: Poly): void;
+export function polyChallenge(c: Poly, seed: Uint8Array): void;
+export function ntt(a: Int32Array): void;
+export function invNTTToMont(a: Int32Array): void;
+export function montgomeryReduce(a: bigint): bigint;
+export function reduce32(a: number): number;
+export function cAddQ(a: number): number;
+export function decompose(a0: Int32Array, i: number, a: number): number;
+export function power2round(a0: Int32Array, i: number, a: number): number;
+export function makeHint(a0: number, a1: number): number;
+export function useHint(a: number, hint: number): number;
+export function packPk(pk: Uint8Array, rho: Uint8Array, t1: PolyVecK): void;
+export function packSk(
+  sk: Uint8Array,
+  rho: Uint8Array,
+  tr: Uint8Array,
+  key: Uint8Array,
+  t0: PolyVecK,
+  s1: PolyVecL,
+  s2: PolyVecK
+): void;
+export function packSig(
+  sig: Uint8Array,
+  c: Uint8Array,
+  z: PolyVecL,
+  h: PolyVecK
+): void;
+export function unpackPk(rho: Uint8Array, t1: PolyVecK, pk: Uint8Array): void;
+export function unpackSk(
+  rho: Uint8Array,
+  tr: Uint8Array,
+  key: Uint8Array,
+  t0: PolyVecK,
+  s1: PolyVecL,
+  s2: PolyVecK,
+  sk: Uint8Array
+): void;
+export function unpackSig(
+  c: Uint8Array,
+  z: PolyVecL,
+  h: PolyVecK,
+  sig: Uint8Array
+): number;
+
+// FIPS 202 SHAKE primitives (low-level XOF interface, primarily internal)
+export function shake128Init(state: KeccakState): void;
+export function shake128Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake128Finalize(state: KeccakState): void;
+export function shake128SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+export function shake256Init(state: KeccakState): void;
+export function shake256Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake256Finalize(state: KeccakState): void;
+export function shake256SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+
+// Dilithium-specific stream initializers
+export function dilithiumShake128StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+export function dilithiumShake256StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+
+// Polynomial operations (internal)
+export function polyReduce(a: Poly): void;
+export function polyCAddQ(a: Poly): void;
+export function polyAdd(c: Poly, a: Poly, b: Poly): void;
+export function polySub(c: Poly, a: Poly, b: Poly): void;
+export function polyShiftL(a: Poly): void;
+export function polyPointWiseMontgomery(c: Poly, a: Poly, b: Poly): void;
+export function polyPower2round(a1: Poly, a0: Poly, a: Poly): void;
+export function polyDecompose(a1: Poly, a0: Poly, a: Poly): void;
+export function polyMakeHint(h: Poly, a0: Poly, a1: Poly): number;
+export function polyUseHint(b: Poly, a: Poly, h: Poly): void;
+export function polyChkNorm(a: Poly, b: number): number;
+export function rejUniform(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniform(a: Poly, seed: Uint8Array, nonce: number): void;
+export function rejEta(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniformEta(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyZUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyUniformGamma1(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyEtaPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyEtaUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT1Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT0Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT0Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyZPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyW1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+
+// Polynomial vector operations (internal)
+export function polyVecMatrixExpand(mat: PolyVecL[], rho: Uint8Array): void;
+export function polyVecMatrixPointWiseMontgomery(
+  t: PolyVecK,
+  mat: PolyVecL[],
+  v: PolyVecL
+): void;
+export function polyVecLUniformEta(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLUniformGamma1(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLReduce(v: PolyVecL): void;
+export function polyVecLAdd(w: PolyVecL, u: PolyVecL, v: PolyVecL): void;
+export function polyVecLNTT(v: PolyVecL): void;
+export function polyVecLInvNTTToMont(v: PolyVecL): void;
+export function polyVecLPointWisePolyMontgomery(
+  r: PolyVecL,
+  a: Poly,
+  v: PolyVecL
+): void;
+export function polyVecLPointWiseAccMontgomery(
+  w: Poly,
+  u: PolyVecL,
+  v: PolyVecL
+): void;
+export function polyVecLChkNorm(v: PolyVecL, bound: number): number;
+export function polyVecKUniformEta(v: PolyVecK, seed: Uint8Array, nonce: number): void;
+export function polyVecKReduce(v: PolyVecK): void;
+export function polyVecKCAddQ(v: PolyVecK): void;
+export function polyVecKAdd(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKSub(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKShiftL(v: PolyVecK): void;
+export function polyVecKNTT(v: PolyVecK): void;
+export function polyVecKInvNTTToMont(v: PolyVecK): void;
+export function polyVecKPointWisePolyMontgomery(
+  r: PolyVecK,
+  a: Poly,
+  v: PolyVecK
+): void;
+export function polyVecKChkNorm(v: PolyVecK, bound: number): number;
+export function polyVecKPower2round(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKDecompose(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKMakeHint(h: PolyVecK, v0: PolyVecK, v1: PolyVecK): number;
+export function polyVecKUseHint(w: PolyVecK, u: PolyVecK, h: PolyVecK): void;
+export function polyVecKPackW1(r: Uint8Array, w1: PolyVecK): void;

package/dist/cjs/dilithium5.js

@@ -1354,6 +1354,12 @@ function packSig(sigP, c, z, h) {
   for (let i = 0; i < K; ++i) {
     for (let j = 0; j < N; ++j) {
       if (h.vec[i].coeffs[j] !== 0) {
+        if (h.vec[i].coeffs[j] !== 1) {
+          throw new Error('hint coefficients must be binary (0 or 1)');
+        }
+        if (k >= OMEGA) {
+          throw new Error(`hint count exceeds OMEGA (${OMEGA})`);
+        }
         sig[sigOffset + k++] = j;
       }
     }
@@ -1794,6 +1800,31 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
   }
 }
 
+/**
+ * Create a **deterministic** Dilithium5 detached signature
+ * (`randomizedSigning = false`).
+ *
+ * Convenience wrapper that hard-wires the deterministic mode so callers
+ * who *need* byte-identical signatures for the same `(sk, message)`
+ * — KAT vector reproduction, deterministic-test fixtures, RANDAO-style
+ * protocols — get a clearly-named entry point rather than passing a
+ * bare boolean.
+ *
+ * **Use only when the deterministic property is itself a requirement.**
+ * For general-purpose signing prefer [cryptoSignSignature] with
+ * `randomizedSigning = true` (hedged signing — TOB-QRLLIB-6 audit
+ * recommendation for parity with the lattice-scheme guidance applied
+ * to the Go and Rust ports).
+ *
+ * @param {Uint8Array} sig - Output buffer for signature (must be at least CryptoBytes bytes)
+ * @param {string|Uint8Array} m - Message to sign
+ * @param {Uint8Array} sk - Secret key (must be CryptoSecretKeyBytes bytes)
+ * @returns {number} 0 on success
+ */
+function cryptoSignSignatureDeterministic(sig, m, sk) {
+  return cryptoSignSignature(sig, m, sk, /* randomizedSigning */ false);
+}
+
 /**
  * Sign a message, returning signature concatenated with message.
  *
@@ -1829,6 +1860,24 @@ function cryptoSign(msg, sk, randomizedSigning) {
   return sm;
 }
 
+/**
+ * Attached-form **deterministic** Dilithium5 signing
+ * (`randomizedSigning = false`).
+ *
+ * Convenience wrapper that hard-wires the deterministic mode for the
+ * attached `signature || message` form. Same recommendation as
+ * [cryptoSignSignatureDeterministic]: use only when determinism is a
+ * protocol requirement; for general-purpose signing prefer
+ * [cryptoSign] with `randomizedSigning = true` (hedged — TOB-QRLLIB-6).
+ *
+ * @param {string|Uint8Array} msg - Message to sign
+ * @param {Uint8Array} sk - Secret key
+ * @returns {Uint8Array} Signed message (signature || message)
+ */
+function cryptoSignDeterministic(msg, sk) {
+  return cryptoSign(msg, sk, /* randomizedSigning */ false);
+}
+
 /**
  * Verify a detached signature.
  *
@@ -1937,7 +1986,12 @@ function cryptoSignVerify(sig, m, pk) {
  * }
  */
 function cryptoSignOpen(sm, pk) {
-  if (sm.length < CryptoBytes) {
+  // Type-guard `sm` so callers passing `null` / `undefined` / non-Uint8Array
+  // get a clean `undefined` return rather than a `Cannot read properties of
+  // null (reading 'length')` thrown deep in the call chain. Mirrors the
+  // existing `pk` / `sig` instanceof checks in `cryptoSignVerify`.
+  // (TOB-QRLLIB-11.)
+  if (!(sm instanceof Uint8Array) || sm.length < CryptoBytes) {
     return undefined;
   }
 
@@ -1950,6 +2004,37 @@ function cryptoSignOpen(sm, pk) {
   return msg;
 }
 
+/**
+ * Open a signed message with a typed failure-mode report.
+ *
+ * Behavioural twin of [cryptoSignOpen], but returns a discriminated
+ * union so callers can distinguish between API-shape problems (input
+ * was the wrong type / length / shape) and genuine cryptographic
+ * verification failures. See the ML-DSA-87 sibling for the rationale
+ * (TOB-QRLLIB-14).
+ *
+ * @param {Uint8Array} sm Signed message (signature || message).
+ * @param {Uint8Array} pk Public key.
+ * @returns {{ok: true, message: Uint8Array} | {ok: false, reason: 'invalid-sm-type'|'invalid-sm-length'|'invalid-pk'|'verification-failed'}}
+ */
+function cryptoSignOpenWithReason(sm, pk) {
+  if (!(sm instanceof Uint8Array)) {
+    return { ok: false, reason: 'invalid-sm-type' };
+  }
+  if (sm.length < CryptoBytes) {
+    return { ok: false, reason: 'invalid-sm-length' };
+  }
+  if (!(pk instanceof Uint8Array) || pk.length !== CryptoPublicKeyBytes) {
+    return { ok: false, reason: 'invalid-pk' };
+  }
+  const sig = sm.slice(0, CryptoBytes);
+  const msg = sm.slice(CryptoBytes);
+  if (!cryptoSignVerify(sig, msg, pk)) {
+    return { ok: false, reason: 'verification-failed' };
+  }
+  return { ok: true, message: msg };
+}
+
 exports.BETA = BETA;
 exports.CRHBytes = CRHBytes;
 exports.CryptoBytes = CryptoBytes;
@@ -1987,9 +2072,12 @@ exports.TAU = TAU;
 exports.TRBytes = TRBytes;
 exports.cAddQ = cAddQ;
 exports.cryptoSign = cryptoSign;
+exports.cryptoSignDeterministic = cryptoSignDeterministic;
 exports.cryptoSignKeypair = cryptoSignKeypair;
 exports.cryptoSignOpen = cryptoSignOpen;
+exports.cryptoSignOpenWithReason = cryptoSignOpenWithReason;
 exports.cryptoSignSignature = cryptoSignSignature;
+exports.cryptoSignSignatureDeterministic = cryptoSignSignatureDeterministic;
 exports.cryptoSignVerify = cryptoSignVerify;
 exports.decompose = decompose;
 exports.dilithiumShake128StreamInit = dilithiumShake128StreamInit;

package/dist/mjs/dilithium5.d.mts

@@ -0,0 +1,367 @@
+/**
+ * TypeScript definitions for @theqrl/dilithium5
+ * Dilithium-5 post-quantum digital signature scheme
+ */
+
+// Constants
+export const Shake128Rate: number;
+export const Shake256Rate: number;
+export const Stream128BlockBytes: number;
+export const Stream256BlockBytes: number;
+export const SeedBytes: number;
+export const CRHBytes: number;
+export const TRBytes: number;
+export const N: number;
+export const Q: number;
+export const QInv: number;
+export const D: number;
+export const K: number;
+export const L: number;
+export const ETA: number;
+export const TAU: number;
+export const BETA: number;
+export const GAMMA1: number;
+export const GAMMA2: number;
+export const OMEGA: number;
+export const PolyT1PackedBytes: number;
+export const PolyT0PackedBytes: number;
+export const PolyETAPackedBytes: number;
+export const PolyZPackedBytes: number;
+export const PolyVecHPackedBytes: number;
+export const PolyW1PackedBytes: number;
+export const CryptoPublicKeyBytes: number;
+export const CryptoSecretKeyBytes: number;
+export const CryptoBytes: number;
+export const PolyUniformNBlocks: number;
+export const PolyUniformETANBlocks: number;
+export const PolyUniformGamma1NBlocks: number;
+export const zetas: readonly number[];
+
+// Core signing functions
+
+/**
+ * Generate a Dilithium-5 key pair
+ * @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
+ * @throws Error if pk/sk buffers are wrong size or null
+ */
+export function cryptoSignKeypair(
+  seed: Uint8Array | null,
+  pk: Uint8Array,
+  sk: Uint8Array
+): Uint8Array;
+
+/**
+ * Create a signature for a message
+ * @param sig - Output buffer for signature (must be CryptoBytes length minimum)
+ * @param m - Message to sign (hex string or Uint8Array; strings are parsed as hex only)
+ * @param sk - Secret key
+ * @param randomizedSigning - If true, use random nonce; if false, deterministic
+ * @returns 0 on success
+ * @throws Error if sk is wrong size
+ */
+export function cryptoSignSignature(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  sk: Uint8Array,
+  randomizedSigning: boolean
+): number;
+
+/**
+ * Sign a message, returning signature concatenated with message
+ * @param msg - Message to sign
+ * @param sk - Secret key
+ * @param randomizedSigning - If true, use random nonce; if false, deterministic
+ * @returns Signed message (signature || message)
+ * @throws Error if signing fails
+ */
+export function cryptoSign(
+  msg: Uint8Array | string,
+  sk: Uint8Array,
+  randomizedSigning: boolean
+): Uint8Array;
+
+/**
+ * Create a deterministic Dilithium5 detached signature
+ * (`randomizedSigning = false` wrapper for `cryptoSignSignature`).
+ *
+ * **Use only when the deterministic property is itself a requirement**.
+ * For general-purpose signing prefer `cryptoSignSignature` with
+ * `randomizedSigning = true` (hedged — TOB-QRLLIB-6).
+ */
+export function cryptoSignSignatureDeterministic(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  sk: Uint8Array
+): number;
+
+/**
+ * Attached-form deterministic Dilithium5 signing
+ * (`randomizedSigning = false` wrapper for `cryptoSign`).
+ * Same recommendation as `cryptoSignSignatureDeterministic`.
+ * (TOB-QRLLIB-6.)
+ */
+export function cryptoSignDeterministic(
+  msg: Uint8Array | string,
+  sk: Uint8Array
+): Uint8Array;
+
+/**
+ * Verify a signature
+ * @param sig - Signature to verify
+ * @param m - Message that was signed (hex string or Uint8Array; strings are parsed as hex only)
+ * @param pk - Public key
+ * @returns true if signature is valid, false otherwise
+ */
+export function cryptoSignVerify(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  pk: Uint8Array
+): boolean;
+
+/**
+ * Open a signed message (verify and extract message)
+ * @param sm - Signed message (signature || message)
+ * @param pk - Public key
+ * @returns Message if valid, undefined if verification fails (or if
+ *   sm is null / undefined / non-Uint8Array / shorter than
+ *   CryptoBytes — see `cryptoSignOpenWithReason` for distinct
+ *   failure-mode reporting)
+ */
+export function cryptoSignOpen(
+  sm: Uint8Array,
+  pk: Uint8Array
+): Uint8Array | undefined;
+
+/**
+ * Failure-mode discriminator returned by `cryptoSignOpenWithReason`.
+ * (TOB-QRLLIB-14: distinct failure modes for Open.)
+ */
+export type CryptoSignOpenReason =
+  | 'invalid-sm-type'
+  | 'invalid-sm-length'
+  | 'invalid-pk'
+  | 'verification-failed';
+
+/**
+ * Open a signed message with a typed failure-mode report.
+ * (TOB-QRLLIB-14.) Behavioural twin of `cryptoSignOpen` that
+ * distinguishes API-shape problems (input wrong type / length /
+ * shape) from genuine verification failures.
+ *
+ * `cryptoSignOpen` is kept unchanged and continues to return
+ * `undefined` for any failure mode. Use this variant when you need
+ * to log or route on specific failure modes.
+ *
+ * @param sm - Signed message (signature || message)
+ * @param pk - Public key
+ */
+export function cryptoSignOpenWithReason(
+  sm: Uint8Array,
+  pk: Uint8Array
+):
+  | { ok: true; message: Uint8Array }
+  | { ok: false; reason: CryptoSignOpenReason };
+
+// Utility functions
+
+/**
+ * Zero out a buffer (best-effort, see SECURITY.md for limitations)
+ * @param buffer - Buffer to zero
+ * @throws TypeError if buffer is not Uint8Array
+ */
+export function zeroize(buffer: Uint8Array): void;
+
+/**
+ * Check if buffer is all zeros using constant-time comparison
+ * @param buffer - Buffer to check
+ * @returns true if all bytes are zero
+ * @throws TypeError if buffer is not Uint8Array
+ */
+export function isZero(buffer: Uint8Array): boolean;
+
+// Internal classes (exported but primarily for internal use)
+
+export class Poly {
+  coeffs: Int32Array;
+  constructor();
+  copy(poly: Poly): void;
+}
+
+export class PolyVecK {
+  vec: Poly[];
+  constructor();
+}
+
+export class PolyVecL {
+  vec: Poly[];
+  constructor();
+  copy(polyVecL: PolyVecL): void;
+}
+
+export class KeccakState {
+  constructor();
+}
+
+// Internal functions (exported but primarily for internal use)
+export function polyNTT(a: Poly): void;
+export function polyInvNTTToMont(a: Poly): void;
+export function polyChallenge(c: Poly, seed: Uint8Array): void;
+export function ntt(a: Int32Array): void;
+export function invNTTToMont(a: Int32Array): void;
+export function montgomeryReduce(a: bigint): bigint;
+export function reduce32(a: number): number;
+export function cAddQ(a: number): number;
+export function decompose(a0: Int32Array, i: number, a: number): number;
+export function power2round(a0: Int32Array, i: number, a: number): number;
+export function makeHint(a0: number, a1: number): number;
+export function useHint(a: number, hint: number): number;
+export function packPk(pk: Uint8Array, rho: Uint8Array, t1: PolyVecK): void;
+export function packSk(
+  sk: Uint8Array,
+  rho: Uint8Array,
+  tr: Uint8Array,
+  key: Uint8Array,
+  t0: PolyVecK,
+  s1: PolyVecL,
+  s2: PolyVecK
+): void;
+export function packSig(
+  sig: Uint8Array,
+  c: Uint8Array,
+  z: PolyVecL,
+  h: PolyVecK
+): void;
+export function unpackPk(rho: Uint8Array, t1: PolyVecK, pk: Uint8Array): void;
+export function unpackSk(
+  rho: Uint8Array,
+  tr: Uint8Array,
+  key: Uint8Array,
+  t0: PolyVecK,
+  s1: PolyVecL,
+  s2: PolyVecK,
+  sk: Uint8Array
+): void;
+export function unpackSig(
+  c: Uint8Array,
+  z: PolyVecL,
+  h: PolyVecK,
+  sig: Uint8Array
+): number;
+
+// FIPS 202 SHAKE primitives (low-level XOF interface, primarily internal)
+export function shake128Init(state: KeccakState): void;
+export function shake128Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake128Finalize(state: KeccakState): void;
+export function shake128SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+export function shake256Init(state: KeccakState): void;
+export function shake256Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake256Finalize(state: KeccakState): void;
+export function shake256SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+
+// Dilithium-specific stream initializers
+export function dilithiumShake128StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+export function dilithiumShake256StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+
+// Polynomial operations (internal)
+export function polyReduce(a: Poly): void;
+export function polyCAddQ(a: Poly): void;
+export function polyAdd(c: Poly, a: Poly, b: Poly): void;
+export function polySub(c: Poly, a: Poly, b: Poly): void;
+export function polyShiftL(a: Poly): void;
+export function polyPointWiseMontgomery(c: Poly, a: Poly, b: Poly): void;
+export function polyPower2round(a1: Poly, a0: Poly, a: Poly): void;
+export function polyDecompose(a1: Poly, a0: Poly, a: Poly): void;
+export function polyMakeHint(h: Poly, a0: Poly, a1: Poly): number;
+export function polyUseHint(b: Poly, a: Poly, h: Poly): void;
+export function polyChkNorm(a: Poly, b: number): number;
+export function rejUniform(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniform(a: Poly, seed: Uint8Array, nonce: number): void;
+export function rejEta(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniformEta(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyZUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyUniformGamma1(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyEtaPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyEtaUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT1Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT0Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT0Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyZPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyW1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+
+// Polynomial vector operations (internal)
+export function polyVecMatrixExpand(mat: PolyVecL[], rho: Uint8Array): void;
+export function polyVecMatrixPointWiseMontgomery(
+  t: PolyVecK,
+  mat: PolyVecL[],
+  v: PolyVecL
+): void;
+export function polyVecLUniformEta(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLUniformGamma1(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLReduce(v: PolyVecL): void;
+export function polyVecLAdd(w: PolyVecL, u: PolyVecL, v: PolyVecL): void;
+export function polyVecLNTT(v: PolyVecL): void;
+export function polyVecLInvNTTToMont(v: PolyVecL): void;
+export function polyVecLPointWisePolyMontgomery(
+  r: PolyVecL,
+  a: Poly,
+  v: PolyVecL
+): void;
+export function polyVecLPointWiseAccMontgomery(
+  w: Poly,
+  u: PolyVecL,
+  v: PolyVecL
+): void;
+export function polyVecLChkNorm(v: PolyVecL, bound: number): number;
+export function polyVecKUniformEta(v: PolyVecK, seed: Uint8Array, nonce: number): void;
+export function polyVecKReduce(v: PolyVecK): void;
+export function polyVecKCAddQ(v: PolyVecK): void;
+export function polyVecKAdd(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKSub(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKShiftL(v: PolyVecK): void;
+export function polyVecKNTT(v: PolyVecK): void;
+export function polyVecKInvNTTToMont(v: PolyVecK): void;
+export function polyVecKPointWisePolyMontgomery(
+  r: PolyVecK,
+  a: Poly,
+  v: PolyVecK
+): void;
+export function polyVecKChkNorm(v: PolyVecK, bound: number): number;
+export function polyVecKPower2round(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKDecompose(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKMakeHint(h: PolyVecK, v0: PolyVecK, v1: PolyVecK): number;
+export function polyVecKUseHint(w: PolyVecK, u: PolyVecK, h: PolyVecK): void;
+export function polyVecKPackW1(r: Uint8Array, w1: PolyVecK): void;

package/dist/mjs/dilithium5.js

@@ -975,6 +975,12 @@ function packSig(sigP, c, z, h) {
   for (let i = 0; i < K; ++i) {
     for (let j = 0; j < N; ++j) {
       if (h.vec[i].coeffs[j] !== 0) {
+        if (h.vec[i].coeffs[j] !== 1) {
+          throw new Error('hint coefficients must be binary (0 or 1)');
+        }
+        if (k >= OMEGA) {
+          throw new Error(`hint count exceeds OMEGA (${OMEGA})`);
+        }
         sig[sigOffset + k++] = j;
       }
     }
@@ -1415,6 +1421,31 @@ function cryptoSignSignature(sig, m, sk, randomizedSigning) {
   }
 }
 
+/**
+ * Create a **deterministic** Dilithium5 detached signature
+ * (`randomizedSigning = false`).
+ *
+ * Convenience wrapper that hard-wires the deterministic mode so callers
+ * who *need* byte-identical signatures for the same `(sk, message)`
+ * — KAT vector reproduction, deterministic-test fixtures, RANDAO-style
+ * protocols — get a clearly-named entry point rather than passing a
+ * bare boolean.
+ *
+ * **Use only when the deterministic property is itself a requirement.**
+ * For general-purpose signing prefer [cryptoSignSignature] with
+ * `randomizedSigning = true` (hedged signing — TOB-QRLLIB-6 audit
+ * recommendation for parity with the lattice-scheme guidance applied
+ * to the Go and Rust ports).
+ *
+ * @param {Uint8Array} sig - Output buffer for signature (must be at least CryptoBytes bytes)
+ * @param {string|Uint8Array} m - Message to sign
+ * @param {Uint8Array} sk - Secret key (must be CryptoSecretKeyBytes bytes)
+ * @returns {number} 0 on success
+ */
+function cryptoSignSignatureDeterministic(sig, m, sk) {
+  return cryptoSignSignature(sig, m, sk, /* randomizedSigning */ false);
+}
+
 /**
  * Sign a message, returning signature concatenated with message.
  *
@@ -1450,6 +1481,24 @@ function cryptoSign(msg, sk, randomizedSigning) {
   return sm;
 }
 
+/**
+ * Attached-form **deterministic** Dilithium5 signing
+ * (`randomizedSigning = false`).
+ *
+ * Convenience wrapper that hard-wires the deterministic mode for the
+ * attached `signature || message` form. Same recommendation as
+ * [cryptoSignSignatureDeterministic]: use only when determinism is a
+ * protocol requirement; for general-purpose signing prefer
+ * [cryptoSign] with `randomizedSigning = true` (hedged — TOB-QRLLIB-6).
+ *
+ * @param {string|Uint8Array} msg - Message to sign
+ * @param {Uint8Array} sk - Secret key
+ * @returns {Uint8Array} Signed message (signature || message)
+ */
+function cryptoSignDeterministic(msg, sk) {
+  return cryptoSign(msg, sk, /* randomizedSigning */ false);
+}
+
 /**
  * Verify a detached signature.
  *
@@ -1558,7 +1607,12 @@ function cryptoSignVerify(sig, m, pk) {
  * }
  */
 function cryptoSignOpen(sm, pk) {
-  if (sm.length < CryptoBytes) {
+  // Type-guard `sm` so callers passing `null` / `undefined` / non-Uint8Array
+  // get a clean `undefined` return rather than a `Cannot read properties of
+  // null (reading 'length')` thrown deep in the call chain. Mirrors the
+  // existing `pk` / `sig` instanceof checks in `cryptoSignVerify`.
+  // (TOB-QRLLIB-11.)
+  if (!(sm instanceof Uint8Array) || sm.length < CryptoBytes) {
     return undefined;
   }
 
@@ -1571,4 +1625,35 @@ function cryptoSignOpen(sm, pk) {
   return 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, cryptoSignKeypair, cryptoSignOpen, cryptoSignSignature, 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 };
+/**
+ * Open a signed message with a typed failure-mode report.
+ *
+ * Behavioural twin of [cryptoSignOpen], but returns a discriminated
+ * union so callers can distinguish between API-shape problems (input
+ * was the wrong type / length / shape) and genuine cryptographic
+ * verification failures. See the ML-DSA-87 sibling for the rationale
+ * (TOB-QRLLIB-14).
+ *
+ * @param {Uint8Array} sm Signed message (signature || message).
+ * @param {Uint8Array} pk Public key.
+ * @returns {{ok: true, message: Uint8Array} | {ok: false, reason: 'invalid-sm-type'|'invalid-sm-length'|'invalid-pk'|'verification-failed'}}
+ */
+function cryptoSignOpenWithReason(sm, pk) {
+  if (!(sm instanceof Uint8Array)) {
+    return { ok: false, reason: 'invalid-sm-type' };
+  }
+  if (sm.length < CryptoBytes) {
+    return { ok: false, reason: 'invalid-sm-length' };
+  }
+  if (!(pk instanceof Uint8Array) || pk.length !== CryptoPublicKeyBytes) {
+    return { ok: false, reason: 'invalid-pk' };
+  }
+  const sig = sm.slice(0, CryptoBytes);
+  const msg = sm.slice(CryptoBytes);
+  if (!cryptoSignVerify(sig, msg, pk)) {
+    return { ok: false, reason: 'verification-failed' };
+  }
+  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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theqrl/dilithium5",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Dilithium-5 cryptography",
   "keywords": [
     "dilithium",
@@ -44,8 +44,14 @@
   },
   "exports": {
     ".": {
-      "import": "./dist/mjs/dilithium5.js",
-      "require": "./dist/cjs/dilithium5.js"
+      "import": {
+        "types": "./dist/mjs/dilithium5.d.mts",
+        "default": "./dist/mjs/dilithium5.js"
+      },
+      "require": {
+        "types": "./dist/cjs/dilithium5.d.cts",
+        "default": "./dist/cjs/dilithium5.js"
+      }
     }
   },
   "type": "module",

package/src/index.d.ts

@@ -83,6 +83,31 @@ export function cryptoSign(
   randomizedSigning: boolean
 ): Uint8Array;
 
+/**
+ * Create a deterministic Dilithium5 detached signature
+ * (`randomizedSigning = false` wrapper for `cryptoSignSignature`).
+ *
+ * **Use only when the deterministic property is itself a requirement**.
+ * For general-purpose signing prefer `cryptoSignSignature` with
+ * `randomizedSigning = true` (hedged — TOB-QRLLIB-6).
+ */
+export function cryptoSignSignatureDeterministic(
+  sig: Uint8Array,
+  m: Uint8Array | string,
+  sk: Uint8Array
+): number;
+
+/**
+ * Attached-form deterministic Dilithium5 signing
+ * (`randomizedSigning = false` wrapper for `cryptoSign`).
+ * Same recommendation as `cryptoSignSignatureDeterministic`.
+ * (TOB-QRLLIB-6.)
+ */
+export function cryptoSignDeterministic(
+  msg: Uint8Array | string,
+  sk: Uint8Array
+): Uint8Array;
+
 /**
  * Verify a signature
  * @param sig - Signature to verify
@@ -100,13 +125,46 @@ export function cryptoSignVerify(
  * Open a signed message (verify and extract message)
  * @param sm - Signed message (signature || message)
  * @param pk - Public key
- * @returns Message if valid, undefined if verification fails
+ * @returns Message if valid, undefined if verification fails (or if
+ *   sm is null / undefined / non-Uint8Array / shorter than
+ *   CryptoBytes — see `cryptoSignOpenWithReason` for distinct
+ *   failure-mode reporting)
  */
 export function cryptoSignOpen(
   sm: Uint8Array,
   pk: Uint8Array
 ): Uint8Array | undefined;
 
+/**
+ * Failure-mode discriminator returned by `cryptoSignOpenWithReason`.
+ * (TOB-QRLLIB-14: distinct failure modes for Open.)
+ */
+export type CryptoSignOpenReason =
+  | 'invalid-sm-type'
+  | 'invalid-sm-length'
+  | 'invalid-pk'
+  | 'verification-failed';
+
+/**
+ * Open a signed message with a typed failure-mode report.
+ * (TOB-QRLLIB-14.) Behavioural twin of `cryptoSignOpen` that
+ * distinguishes API-shape problems (input wrong type / length /
+ * shape) from genuine verification failures.
+ *
+ * `cryptoSignOpen` is kept unchanged and continues to return
+ * `undefined` for any failure mode. Use this variant when you need
+ * to log or route on specific failure modes.
+ *
+ * @param sm - Signed message (signature || message)
+ * @param pk - Public key
+ */
+export function cryptoSignOpenWithReason(
+  sm: Uint8Array,
+  pk: Uint8Array
+):
+  | { ok: true; message: Uint8Array }
+  | { ok: false; reason: CryptoSignOpenReason };
+
 // Utility functions
 
 /**
@@ -192,3 +250,118 @@ export function unpackSig(
   h: PolyVecK,
   sig: Uint8Array
 ): number;
+
+// FIPS 202 SHAKE primitives (low-level XOF interface, primarily internal)
+export function shake128Init(state: KeccakState): void;
+export function shake128Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake128Finalize(state: KeccakState): void;
+export function shake128SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+export function shake256Init(state: KeccakState): void;
+export function shake256Absorb(state: KeccakState, input: Uint8Array): void;
+export function shake256Finalize(state: KeccakState): void;
+export function shake256SqueezeBlocks(
+  out: Uint8Array,
+  outputOffset: number,
+  nBlocks: number,
+  state: KeccakState
+): void;
+
+// Dilithium-specific stream initializers
+export function dilithiumShake128StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+export function dilithiumShake256StreamInit(
+  state: KeccakState,
+  seed: Uint8Array,
+  nonce: number
+): void;
+
+// Polynomial operations (internal)
+export function polyReduce(a: Poly): void;
+export function polyCAddQ(a: Poly): void;
+export function polyAdd(c: Poly, a: Poly, b: Poly): void;
+export function polySub(c: Poly, a: Poly, b: Poly): void;
+export function polyShiftL(a: Poly): void;
+export function polyPointWiseMontgomery(c: Poly, a: Poly, b: Poly): void;
+export function polyPower2round(a1: Poly, a0: Poly, a: Poly): void;
+export function polyDecompose(a1: Poly, a0: Poly, a: Poly): void;
+export function polyMakeHint(h: Poly, a0: Poly, a1: Poly): number;
+export function polyUseHint(b: Poly, a: Poly, h: Poly): void;
+export function polyChkNorm(a: Poly, b: number): number;
+export function rejUniform(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniform(a: Poly, seed: Uint8Array, nonce: number): void;
+export function rejEta(
+  a: Int32Array,
+  aOffset: number,
+  len: number,
+  buf: Uint8Array,
+  bufLen: number
+): number;
+export function polyUniformEta(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyZUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyUniformGamma1(a: Poly, seed: Uint8Array, nonce: number): void;
+export function polyEtaPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyEtaUnpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT1Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyT0Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyT0Unpack(r: Poly, a: Uint8Array, aOffset: number): void;
+export function polyZPack(r: Uint8Array, rOffset: number, a: Poly): void;
+export function polyW1Pack(r: Uint8Array, rOffset: number, a: Poly): void;
+
+// Polynomial vector operations (internal)
+export function polyVecMatrixExpand(mat: PolyVecL[], rho: Uint8Array): void;
+export function polyVecMatrixPointWiseMontgomery(
+  t: PolyVecK,
+  mat: PolyVecL[],
+  v: PolyVecL
+): void;
+export function polyVecLUniformEta(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLUniformGamma1(v: PolyVecL, seed: Uint8Array, nonce: number): void;
+export function polyVecLReduce(v: PolyVecL): void;
+export function polyVecLAdd(w: PolyVecL, u: PolyVecL, v: PolyVecL): void;
+export function polyVecLNTT(v: PolyVecL): void;
+export function polyVecLInvNTTToMont(v: PolyVecL): void;
+export function polyVecLPointWisePolyMontgomery(
+  r: PolyVecL,
+  a: Poly,
+  v: PolyVecL
+): void;
+export function polyVecLPointWiseAccMontgomery(
+  w: Poly,
+  u: PolyVecL,
+  v: PolyVecL
+): void;
+export function polyVecLChkNorm(v: PolyVecL, bound: number): number;
+export function polyVecKUniformEta(v: PolyVecK, seed: Uint8Array, nonce: number): void;
+export function polyVecKReduce(v: PolyVecK): void;
+export function polyVecKCAddQ(v: PolyVecK): void;
+export function polyVecKAdd(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKSub(w: PolyVecK, u: PolyVecK, v: PolyVecK): void;
+export function polyVecKShiftL(v: PolyVecK): void;
+export function polyVecKNTT(v: PolyVecK): void;
+export function polyVecKInvNTTToMont(v: PolyVecK): void;
+export function polyVecKPointWisePolyMontgomery(
+  r: PolyVecK,
+  a: Poly,
+  v: PolyVecK
+): void;
+export function polyVecKChkNorm(v: PolyVecK, bound: number): number;
+export function polyVecKPower2round(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKDecompose(v1: PolyVecK, v0: PolyVecK, v: PolyVecK): void;
+export function polyVecKMakeHint(h: PolyVecK, v0: PolyVecK, v1: PolyVecK): number;
+export function polyVecKUseHint(w: PolyVecK, u: PolyVecK, h: PolyVecK): void;
+export function polyVecKPackW1(r: Uint8Array, w1: PolyVecK): void;