@noble/post-quantum 0.5.3 → 0.6.0

package/src/utils.ts

@@ -9,14 +9,60 @@ import {
   abytes,
   abytes as abytes_,
   concatBytes,
-  isBytes,
+  isLE,
   randomBytes as randb,
 } from '@noble/hashes/utils.js';
-export { abytes } from '@noble/hashes/utils.js';
-export { concatBytes };
+/**
+ * Asserts that a value is a byte array and optionally checks its length.
+ * Returns the original reference unchanged on success, and currently also accepts Node `Buffer`
+ * values through the upstream validator.
+ * This helper throws on malformed input, so APIs that must return `false` need to guard lengths
+ * before decoding or before calling it.
+ * @example
+ * Validate that a value is a byte array with the expected length.
+ * ```ts
+ * abytes(new Uint8Array([1]), 1);
+ * ```
+ */
+const abytesDoc: typeof abytes = abytes;
+export { abytesDoc as abytes };
+/**
+ * Concatenates byte arrays into a new `Uint8Array`.
+ * Zero arguments return an empty `Uint8Array`.
+ * Invalid segments throw before allocation because each argument is validated first.
+ * @example
+ * Concatenate two byte arrays into one result.
+ * ```ts
+ * concatBytes(new Uint8Array([1]), new Uint8Array([2]));
+ * ```
+ */
+const concatBytesDoc: typeof concatBytes = concatBytes;
+export { concatBytesDoc as concatBytes };
+/**
+ * Returns cryptographically secure random bytes.
+ * Requires `globalThis.crypto.getRandomValues` and throws if that API is unavailable.
+ * `bytesLength` is validated by the upstream helper as a non-negative integer before allocation,
+ * so negative and fractional values both throw instead of truncating through JS `ToIndex`.
+ * @example
+ * Generate a fresh random seed.
+ * ```ts
+ * const seed = randomBytes(4);
+ * ```
+ */
 export const randomBytes: typeof randb = randb;
 
-// Compares 2 u8a-s in kinda constant time
+/**
+ * Compares two byte arrays in a length-constant way for equal lengths.
+ * Unequal lengths return `false` immediately, and there is no runtime type validation.
+ * @param a - First byte array.
+ * @param b - Second byte array.
+ * @returns Whether both arrays contain the same bytes.
+ * @example
+ * Compare two byte arrays for equality.
+ * ```ts
+ * equalBytes(new Uint8Array([1]), new Uint8Array([1]));
+ * ```
+ */
 export function equalBytes(a: Uint8Array, b: Uint8Array): boolean {
   if (a.length !== b.length) return false;
   let diff = 0;
@@ -24,52 +70,170 @@ export function equalBytes(a: Uint8Array, b: Uint8Array): boolean {
   return diff === 0;
 }
 
-// copy bytes to new u8a (aligned). Because Buffer.slice is broken.
+/**
+ * Copies bytes into a fresh `Uint8Array`.
+ * Returns a detached plain `Uint8Array`, and currently accepts broader array-like / iterable
+ * inputs because it delegates directly to `Uint8Array.from(...)`.
+ * @param bytes - Source bytes.
+ * @returns Copy of the input bytes.
+ * @example
+ * Copy bytes into a fresh array.
+ * ```ts
+ * copyBytes(new Uint8Array([1, 2]));
+ * ```
+ */
 export function copyBytes(bytes: Uint8Array): Uint8Array {
   return Uint8Array.from(bytes);
 }
 
+/**
+ * Byte-swaps each 64-bit lane in place.
+ * Falcon's exact binary64 tables are stored as little-endian byte payloads, so BE runtimes need
+ * this boundary helper before aliasing them as host `Float64Array` lanes.
+ * @param arr - Byte buffer whose length is a multiple of 8.
+ * @returns The same buffer after in-place 64-bit lane byte swaps.
+ */
+export function byteSwap64<T extends ArrayBufferView>(arr: T): T {
+  const bytes = new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+  for (let i = 0; i < bytes.length; i += 8) {
+    const a0 = bytes[i + 0];
+    const a1 = bytes[i + 1];
+    const a2 = bytes[i + 2];
+    const a3 = bytes[i + 3];
+    bytes[i + 0] = bytes[i + 7];
+    bytes[i + 1] = bytes[i + 6];
+    bytes[i + 2] = bytes[i + 5];
+    bytes[i + 3] = bytes[i + 4];
+    bytes[i + 4] = a3;
+    bytes[i + 5] = a2;
+    bytes[i + 6] = a1;
+    bytes[i + 7] = a0;
+  }
+  return arr;
+}
+export const baswap64If: <T extends ArrayBufferView>(arr: T) => T = isLE
+  ? (arr) => arr
+  : byteSwap64;
+
+/** Shared key-generation surface for signers and KEMs. */
 export type CryptoKeys = {
+  /** Optional metadata about the algorithm family or variant. */
   info?: { type?: string };
+  /** Public byte lengths for the exported key material. */
   lengths: { seed?: number; publicKey?: number; secretKey?: number };
+  /**
+   * Generate one secret/public keypair.
+   * @param seed - Optional seed bytes for deterministic key generation.
+   * @returns Fresh secret/public keypair.
+   */
   keygen: (seed?: Uint8Array) => { secretKey: Uint8Array; publicKey: Uint8Array };
+  /**
+   * Derive one public key from a secret key.
+   * @param secretKey - Secret key bytes.
+   * @returns Public key bytes.
+   */
   getPublicKey: (secretKey: Uint8Array) => Uint8Array;
 };
 
+/** Verification options shared by the signature APIs. */
 export type VerOpts = {
+  /** Optional application-defined context string. */
   context?: Uint8Array;
 };
+/** Signing options shared by the signature APIs. */
 export type SigOpts = VerOpts & {
   // Compatibility with @noble/curves: false to disable, enabled by default, user can pass U8A
+  /** Optional extra entropy or `false` to disable randomized signing. */
   extraEntropy?: Uint8Array | false;
 };
 
+/**
+ * Validates that an options bag is a plain object.
+ * @param opts - Options object to validate.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate that an options bag is a plain object.
+ * ```ts
+ * validateOpts({});
+ * ```
+ */
 export function validateOpts(opts: object): void {
-  // We try to catch u8a, since it was previously valid argument at this position
-  if (typeof opts !== 'object' || opts === null || isBytes(opts))
-    throw new Error('expected opts to be an object');
+  // Arrays silently passed here before, but these call sites expect named option-bag fields.
+  if (Object.prototype.toString.call(opts) !== '[object Object]')
+    throw new TypeError('expected valid options object');
 }
 
+/**
+ * Validates common verification options.
+ * `context` itself is validated with `abytes(...)`, and individual algorithms may narrow support
+ * further after this shared plain-object gate.
+ * @param opts - Verification options. See {@link VerOpts}.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate common verification options.
+ * ```ts
+ * validateVerOpts({ context: new Uint8Array([1]) });
+ * ```
+ */
 export function validateVerOpts(opts: VerOpts): void {
   validateOpts(opts);
   if (opts.context !== undefined) abytes(opts.context, undefined, 'opts.context');
 }
 
+/**
+ * Validates common signing options.
+ * `extraEntropy` is validated with `abytes(...)`; exact lengths and extra algorithm-specific
+ * restrictions are enforced later by callers.
+ * @param opts - Signing options. See {@link SigOpts}.
+ * @throws On wrong argument types. {@link TypeError}
+ * @example
+ * Validate common signing options.
+ * ```ts
+ * validateSigOpts({ extraEntropy: new Uint8Array([1]) });
+ * ```
+ */
 export function validateSigOpts(opts: SigOpts): void {
   validateVerOpts(opts);
   if (opts.extraEntropy !== false && opts.extraEntropy !== undefined)
     abytes(opts.extraEntropy, undefined, 'opts.extraEntropy');
 }
 
-/** Generic interface for signatures. Has keygen, sign and verify. */
+/** Generic signature interface with key generation, signing, and verification. */
 export type Signer = CryptoKeys & {
+  /** Public byte lengths for signatures and signing randomness. */
   lengths: { signRand?: number; signature?: number };
+  /**
+   * Sign one message.
+   * @param msg - Message bytes to sign.
+   * @param secretKey - Secret key bytes.
+   * @param opts - Optional signing options.
+   * @returns Signature bytes.
+   */
   sign: (msg: Uint8Array, secretKey: Uint8Array, opts?: SigOpts) => Uint8Array;
+  /**
+   * Verify one signature.
+   * @param sig - Signature bytes.
+   * @param msg - Signed message bytes.
+   * @param publicKey - Public key bytes.
+   * @param opts - Optional verification options.
+   * @returns `true` when the signature is valid, `false` when all inputs are well-formed but the
+   * signature check does not pass. Some implementations also treat malformed signature encodings as
+   * a verification failure and return `false`.
+   * @throws On malformed API arguments or unsupported verification options.
+   */
   verify: (sig: Uint8Array, msg: Uint8Array, publicKey: Uint8Array, opts?: VerOpts) => boolean;
 };
 
+/** Generic key encapsulation mechanism interface. */
 export type KEM = CryptoKeys & {
+  /** Public byte lengths for ciphertexts and optional message randomness. */
   lengths: { cipherText?: number; msg?: number; msgRand?: number };
+  /**
+   * Encapsulate one shared secret to a recipient public key.
+   * @param publicKey - Recipient public key bytes.
+   * @param msg - Optional caller-provided randomness/message seed.
+   * @returns Ciphertext plus shared secret.
+   */
   encapsulate: (
     publicKey: Uint8Array,
     msg?: Uint8Array
@@ -77,19 +241,48 @@ export type KEM = CryptoKeys & {
     cipherText: Uint8Array;
     sharedSecret: Uint8Array;
   };
+  /**
+   * Recover the shared secret from a ciphertext and recipient secret key.
+   * @param cipherText - Ciphertext bytes.
+   * @param secretKey - Recipient secret key bytes.
+   * @returns Decapsulated shared secret.
+   */
   decapsulate: (cipherText: Uint8Array, secretKey: Uint8Array) => Uint8Array;
 };
 
+/** Bidirectional encoder/decoder interface. */
 export interface Coder<F, T> {
+  /**
+   * Serialize one value.
+   * @param from - Value to encode.
+   * @returns Encoded representation.
+   */
   encode(from: F): T;
+  /**
+   * Parse one serialized value.
+   * @param to - Encoded representation.
+   * @returns Decoded value.
+   */
   decode(to: T): F;
 }
 
+/** Encoder/decoder interface specialized for byte arrays. */
 export interface BytesCoder<T> extends Coder<T, Uint8Array> {
+  /**
+   * Serialize one value into bytes.
+   * @param data - Value to encode.
+   * @returns Encoded bytes.
+   */
   encode: (data: T) => Uint8Array;
+  /**
+   * Parse one byte array into a value.
+   * @param bytes - Encoded bytes.
+   * @returns Decoded value.
+   */
   decode: (bytes: Uint8Array) => T;
 }
 
+/** Fixed-length byte encoder/decoder. */
 export type BytesCoderLen<T> = BytesCoder<T> & { bytesLen: number };
 
 // nano-packed, because struct encoding is hard.
@@ -97,6 +290,21 @@ type UnCoder<T> = T extends BytesCoder<infer U> ? U : never;
 type SplitOut<T extends (number | BytesCoderLen<any>)[]> = {
   [K in keyof T]: T[K] extends number ? Uint8Array : UnCoder<T[K]>;
 };
+/**
+ * Builds a fixed-layout coder from byte lengths and nested coders.
+ * Raw-length fields decode as zero-copy `subarray(...)` views, and nested coders may preserve that
+ * aliasing too. Nested coder `encode(...)` results are treated as owned scratch: `splitCoder`
+ * copies them into the output and then zeroizes them with `fill(0)`. If a nested encoder forwards
+ * caller-owned bytes, it must do so only after detaching them into a disposable copy.
+ * @param label - Label used in validation errors.
+ * @param lengths - Field lengths or nested coders.
+ * @returns Composite fixed-length coder.
+ * @example
+ * Build a fixed-layout coder from byte lengths and nested coders.
+ * ```ts
+ * splitCoder('demo', 1, 2).encode([new Uint8Array([1]), new Uint8Array([2, 3])]);
+ * ```
+ */
 export function splitCoder<T extends (number | BytesCoderLen<any>)[]>(
   label: string,
   ...lengths: T
@@ -132,13 +340,32 @@ export function splitCoder<T extends (number | BytesCoderLen<any>)[]>(
   } as any;
 }
 // nano-packed.array (fixed size)
+/**
+ * Builds a fixed-length vector coder from another fixed-length coder.
+ * Element decoding receives `subarray(...)` views, so aliasing depends on the element coder.
+ * Element coder `encode(...)` results are treated as owned scratch: `vecCoder` copies them into
+ * the output and then zeroizes them with `fill(0)`. If an element encoder forwards caller-owned
+ * bytes, it must do so only after detaching them into a disposable copy. `vecCoder` also trusts
+ * the `BytesCoderLen` contract: each encoded element must already be exactly `c.bytesLen` bytes.
+ * @param c - Element coder.
+ * @param vecLen - Number of elements in the vector.
+ * @returns Fixed-length vector coder.
+ * @example
+ * Build a fixed-length vector coder from another fixed-length coder.
+ * ```ts
+ * vecCoder(
+ *   { bytesLen: 1, encode: (n: number) => Uint8Array.of(n), decode: (b: Uint8Array) => b[0] || 0 },
+ *   2
+ * ).encode([1, 2]);
+ * ```
+ */
 export function vecCoder<T>(c: BytesCoderLen<T>, vecLen: number): BytesCoderLen<T[]> {
   const bytesLen = vecLen * c.bytesLen;
   return {
     bytesLen,
     encode: (u: T[]): Uint8Array => {
       if (u.length !== vecLen)
-        throw new Error(`vecCoder.encode: wrong length=${u.length}. Expected: ${vecLen}`);
+        throw new RangeError(`vecCoder.encode: wrong length=${u.length}. Expected: ${vecLen}`);
       const res = new Uint8Array(bytesLen);
       for (let i = 0, pos = 0; i < u.length; i++) {
         const b = c.encode(u[i]);
@@ -158,7 +385,17 @@ export function vecCoder<T>(c: BytesCoderLen<T>, vecLen: number): BytesCoderLen<
   };
 }
 
-// cleanBytes(Uint8Array.of(), [Uint16Array.of(), Uint32Array.of()])
+/**
+ * Overwrites supported typed-array inputs with zeroes in place.
+ * Accepts direct typed arrays and one-level arrays of them.
+ * @param list - Typed arrays or one-level lists of typed arrays to clear.
+ * @example
+ * Overwrite typed arrays with zeroes.
+ * ```ts
+ * const buf = Uint8Array.of(1, 2, 3);
+ * cleanBytes(buf);
+ * ```
+ */
 export function cleanBytes(...list: (TypedArray | TypedArray[])[]): void {
   for (const t of list) {
     if (Array.isArray(t)) for (const b of t) b.fill(0);
@@ -166,25 +403,75 @@ export function cleanBytes(...list: (TypedArray | TypedArray[])[]): void {
   }
 }
 
+/**
+ * Creates a 32-bit mask with the lowest `bits` bits set.
+ * @param bits - Number of low bits to keep.
+ * @returns Bit mask with `bits` ones.
+ * @example
+ * Create a low-bit mask for packed-field operations.
+ * ```ts
+ * const mask = getMask(4);
+ * ```
+ */
 export function getMask(bits: number): number {
-  return (1 << bits) - 1; // 4 -> 0b1111
+  if (!Number.isSafeInteger(bits) || bits < 0 || bits > 32)
+    throw new RangeError(`expected bits in [0..32], got ${bits}`);
+  // JS shifts are modulo 32, so bit 32 needs an explicit full-width mask.
+  return bits === 32 ? 0xffffffff : ~(-1 << bits) >>> 0;
 }
 
-export const EMPTY: Uint8Array = Uint8Array.of();
+/** Shared empty byte array used as the default context. */
+export const EMPTY: Uint8Array = /* @__PURE__ */ Uint8Array.of();
 
+/**
+ * Builds the domain-separated message payload for the pure sign/verify paths.
+ * Context length `255` is valid; only `ctx.length > 255` is rejected.
+ * @param msg - Message bytes.
+ * @param ctx - Optional context bytes.
+ * @returns Domain-separated message payload.
+ * @throws On wrong argument ranges or values. {@link RangeError}
+ * @example
+ * Build the domain-separated payload before direct signing.
+ * ```ts
+ * const payload = getMessage(new Uint8Array([1, 2]));
+ * ```
+ */
 export function getMessage(msg: Uint8Array, ctx: Uint8Array = EMPTY): Uint8Array {
   abytes_(msg);
   abytes_(ctx);
-  if (ctx.length > 255) throw new Error('context should be less than 255 bytes');
+  if (ctx.length > 255) throw new RangeError('context should be 255 bytes or less');
   return concatBytes(new Uint8Array([0, ctx.length]), ctx, msg);
 }
 
+// DER tag+length plus the shared NIST hash OID arc 2.16.840.1.101.3.4.2.* used by the
+// FIPS 204 / FIPS 205 pre-hash wrappers; the final byte selects SHA-256, SHA-512, SHAKE128,
+// SHAKE256, or another approved hash/XOF under that subtree.
 // 06 09 60 86 48 01 65 03 04 02
 const oidNistP = /* @__PURE__ */ Uint8Array.from([6, 9, 0x60, 0x86, 0x48, 1, 0x65, 3, 4, 2]);
 
+/**
+ * Validates that a hash exposes a NIST hash OID and enough collision resistance.
+ * Current accepted surface is broader than the FIPS algorithm tables: any hash/XOF under the NIST
+ * `2.16.840.1.101.3.4.2.*` subtree is accepted if its effective `outputLen` is strong enough.
+ * XOF callers must pass a callable whose `outputLen` matches the digest length they actually intend
+ * to sign; bare `shake128` / `shake256` defaults are too short for the stronger prehash modes.
+ * @param hash - Hash function to validate.
+ * @param requiredStrength - Minimum required collision-resistance strength in bits.
+ * @throws If the hash metadata or collision resistance is insufficient. {@link Error}
+ * @example
+ * Validate that a hash exposes a NIST hash OID and enough collision resistance.
+ * ```ts
+ * import { sha256 } from '@noble/hashes/sha2.js';
+ * import { checkHash } from '@noble/post-quantum/utils.js';
+ * checkHash(sha256, 128);
+ * ```
+ */
 export function checkHash(hash: CHash, requiredStrength: number = 0): void {
   if (!hash.oid || !equalBytes(hash.oid.subarray(0, 10), oidNistP))
     throw new Error('hash.oid is invalid: expected NIST hash');
+  // FIPS 204 / FIPS 205 require both collision and second-preimage strength; for approved NIST
+  // hashes/XOFs under this OID subtree, the collision bound from the configured digest length is
+  // the tighter runtime check, so enforce that lower bound here.
   const collisionResistance = (hash.outputLen * 8) / 2;
   if (requiredStrength > collisionResistance) {
     throw new Error(
@@ -196,6 +483,24 @@ export function checkHash(hash: CHash, requiredStrength: number = 0): void {
   }
 }
 
+/**
+ * Builds the domain-separated prehash payload for the prehash sign/verify paths.
+ * Callers are expected to vet `hash.oid` first, e.g. via `checkHash(...)`; calling this helper
+ * directly with a hash object that lacks `oid` currently throws later inside `concatBytes(...)`.
+ * Context length `255` is valid; only `ctx.length > 255` is rejected.
+ * @param hash - Prehash function.
+ * @param msg - Message bytes.
+ * @param ctx - Optional context bytes.
+ * @returns Domain-separated prehash payload.
+ * @throws On wrong argument ranges or values. {@link RangeError}
+ * @example
+ * Build the domain-separated prehash payload for external hashing.
+ * ```ts
+ * import { sha256 } from '@noble/hashes/sha2.js';
+ * import { getMessagePrehash } from '@noble/post-quantum/utils.js';
+ * getMessagePrehash(sha256, new Uint8Array([1, 2]));
+ * ```
+ */
 export function getMessagePrehash(
   hash: CHash,
   msg: Uint8Array,
@@ -203,7 +508,7 @@ export function getMessagePrehash(
 ): Uint8Array {
   abytes_(msg);
   abytes_(ctx);
-  if (ctx.length > 255) throw new Error('context should be less than 255 bytes');
+  if (ctx.length > 255) throw new RangeError('context should be 255 bytes or less');
   const hashed = hash(msg);
   return concatBytes(new Uint8Array([1, ctx.length]), ctx, hash.oid!, hashed);
 }