@bcts/rand 1.0.0-alpha.9 → 1.0.0-beta.0

package/src/random-number-generator.ts

@@ -1,46 +1,34 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from bc-rand-rust/src/random_number_generator.rs
 
-import { wideMulU32, wideMulU64 } from "./widening.js";
-import {
-  toMagnitude,
-  toMagnitude64 as _toMagnitude64,
-  fromMagnitude as _fromMagnitude,
-  fromMagnitude64 as _fromMagnitude64,
-} from "./magnitude.js";
+import { wideMulU8, wideMulU16, wideMulU32, wideMulU64 } from "./widening.js";
+import { toMagnitude, toMagnitude64, fromMagnitude64 } from "./magnitude.js";
 
 /**
  * Interface for random number generators.
- * This is the TypeScript equivalent of Rust's RandomNumberGenerator trait
- * which extends RngCore + CryptoRng.
  *
- * This is compatible with the RandomNumberGenerator Swift protocol used
- * in MacOS and iOS, which is important for cross-platform testing.
+ * The TypeScript equivalent of Rust's `RandomNumberGenerator` trait
+ * (which extends `RngCore + CryptoRng`).
  */
 export interface RandomNumberGenerator {
-  /**
-   * Returns the next random 32-bit unsigned integer.
-   */
+  /** Returns the next random 32-bit unsigned integer. */
   nextU32(): number;
 
-  /**
-   * Returns the next random 64-bit unsigned integer as a bigint.
-   */
+  /** Returns the next random 64-bit unsigned integer as a bigint. */
   nextU64(): bigint;
 
-  /**
-   * Fills the given Uint8Array with random bytes.
-   */
+  /** Fills the given Uint8Array with random bytes. */
   fillBytes(dest: Uint8Array): void;
 
-  /**
-   * Returns a Uint8Array of random bytes of the given size.
-   */
+  /** Returns a Uint8Array of random bytes of the given size. */
   randomData(size: number): Uint8Array;
 
-  /**
-   * Fills the given Uint8Array with random bytes.
-   * Alias for fillBytes for compatibility.
-   */
+  /** Fills the given Uint8Array with random bytes. Alias for fillBytes. */
   fillRandomData(data: Uint8Array): void;
 }
 
@@ -60,197 +48,364 @@ export function rngFillRandomData(rng: RandomNumberGenerator, data: Uint8Array):
   rng.fillRandomData(data);
 }
 
+// =====================================================================
+// Lemire's "nearly divisionless" upper-bound sampler
+// (https://arxiv.org/abs/1805.10941)
+//
+// Rust exposes a single generic `rng_next_with_upper_bound<T>`. JavaScript
+// has no integer-width generics, so we provide one specialization per
+// width — `U8`, `U16`, `U32`, `U64` — exactly mirroring the Rust dispatch.
+// =====================================================================
+
 /**
- * Returns a random value that is less than the given upper bound.
- *
- * Uses Lemire's "nearly divisionless" method for generating random
- * integers in an interval. For a detailed explanation, see:
- * https://arxiv.org/abs/1805.10941
- *
- * @param rng - The random number generator to use
- * @param upperBound - The upper bound for the randomly generated value. Must be non-zero.
- * @returns A random value in the range [0, upperBound). Every value in the range is equally likely.
+ * Returns a random `u8` value strictly less than `upperBound`.
  */
-export function rngNextWithUpperBound(rng: RandomNumberGenerator, upperBound: bigint): bigint {
-  if (upperBound === 0n) {
-    throw new Error("upperBound must be non-zero");
+export function rngNextWithUpperBoundU8(rng: RandomNumberGenerator, upperBound: number): number {
+  if (upperBound === 0) throw new Error("upperBound must be non-zero");
+  const ub = upperBound & 0xff;
+  let random = Number(rng.nextU64() & 0xffn);
+  let m = wideMulU8(random, ub);
+  if (m[0] < ub) {
+    const t = ((0x100 - ub) & 0xff) % ub;
+    while (m[0] < t) {
+      random = Number(rng.nextU64() & 0xffn);
+      m = wideMulU8(random, ub);
+    }
   }
+  return m[1];
+}
 
-  // We use Lemire's "nearly divisionless" method for generating random
-  // integers in an interval. For a detailed explanation, see:
-  // https://arxiv.org/abs/1805.10941
+/**
+ * Returns a random `u16` value strictly less than `upperBound`.
+ */
+export function rngNextWithUpperBoundU16(rng: RandomNumberGenerator, upperBound: number): number {
+  if (upperBound === 0) throw new Error("upperBound must be non-zero");
+  const ub = upperBound & 0xffff;
+  let random = Number(rng.nextU64() & 0xffffn);
+  let m = wideMulU16(random, ub);
+  if (m[0] < ub) {
+    const t = ((0x10000 - ub) & 0xffff) % ub;
+    while (m[0] < t) {
+      random = Number(rng.nextU64() & 0xffffn);
+      m = wideMulU16(random, ub);
+    }
+  }
+  return m[1];
+}
 
-  const bitmask = 0xffffffffffffffffn; // u64 max
-  let random = rng.nextU64() & bitmask;
-  let m = wideMulU64(random, upperBound);
+/**
+ * Returns a random `u32` value strictly less than `upperBound`.
+ */
+export function rngNextWithUpperBoundU32(rng: RandomNumberGenerator, upperBound: number): number {
+  if (upperBound === 0) throw new Error("upperBound must be non-zero");
+  const ub = upperBound >>> 0;
+  let random = Number(rng.nextU64() & 0xffffffffn);
+  let m = wideMulU32(random, ub);
+  if (Number(m[0]) < ub) {
+    const t = ((0x100000000 - ub) >>> 0) % ub;
+    while (Number(m[0]) < t) {
+      random = Number(rng.nextU64() & 0xffffffffn);
+      m = wideMulU32(random, ub);
+    }
+  }
+  return Number(m[1]);
+}
 
-  if (m[0] < upperBound) {
-    // t = (0 - upperBound) % upperBound
-    const negUpperBound = (bitmask + 1n - upperBound) & bitmask;
-    const t = negUpperBound % upperBound;
+/**
+ * Returns a random `u64` value strictly less than `upperBound`.
+ */
+export function rngNextWithUpperBoundU64(rng: RandomNumberGenerator, upperBound: bigint): bigint {
+  if (upperBound === 0n) throw new Error("upperBound must be non-zero");
+  const mask64 = 0xffffffffffffffffn;
+  const ub = upperBound & mask64;
+  let random = rng.nextU64() & mask64;
+  let m = wideMulU64(random, ub);
+  if (m[0] < ub) {
+    // wrapping_sub(0, ub) within u64
+    const t = ((mask64 + 1n - ub) & mask64) % ub;
     while (m[0] < t) {
-      random = rng.nextU64() & bitmask;
-      m = wideMulU64(random, upperBound);
+      random = rng.nextU64() & mask64;
+      m = wideMulU64(random, ub);
     }
   }
-
   return m[1];
 }
 
 /**
- * Returns a random 32-bit value that is less than the given upper bound.
- * This matches Rust's behavior when called with u32 type.
- *
- * Uses Lemire's "nearly divisionless" method with 32-bit arithmetic.
+ * Alias of `rngNextWithUpperBoundU64`. Kept for API backwards compatibility.
  *
- * @param rng - The random number generator to use
- * @param upperBound - The upper bound for the randomly generated value. Must be non-zero and fit in u32.
- * @returns A random u32 value in the range [0, upperBound).
+ * @deprecated Prefer the explicit-width name `rngNextWithUpperBoundU64`.
  */
-export function rngNextWithUpperBoundU32(rng: RandomNumberGenerator, upperBound: number): number {
-  if (upperBound === 0) {
-    throw new Error("upperBound must be non-zero");
+export const rngNextWithUpperBound = rngNextWithUpperBoundU64;
+
+// =====================================================================
+// Range / closed-range samplers
+//
+// Mirrors Rust `rng_next_in_range<T>` and `rng_next_in_closed_range<T>`.
+// `from_u64(...).unwrap()` in the early-return branch panics in Rust when
+// the random `u64` does not fit in `T`. We mirror that with a thrown
+// `Error` so cross-platform behavior matches exactly.
+// =====================================================================
+
+function fromU64ThrowsIfAbove(value: bigint, max: bigint): bigint {
+  if (value > max) {
+    throw new Error("from_u64 conversion overflow");
   }
+  return value;
+}
 
-  const upperBoundU32 = upperBound >>> 0;
-  const bitmask = 0xffffffff;
+/** Random `u8` in the half-open range [start, end). */
+export function rngNextInRangeU8(rng: RandomNumberGenerator, start: number, end: number): number {
+  if (start >= end) throw new Error("start must be less than end");
+  const lo = start & 0xff;
+  const hi = end & 0xff;
+  const delta = (hi - lo) & 0xff;
+  if (delta === 0xff) {
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0xffn));
+  }
+  return (lo + rngNextWithUpperBoundU8(rng, delta)) & 0xff;
+}
 
-  // Get random and mask to 32 bits (matches Rust behavior)
-  let random = Number(rng.nextU64() & BigInt(bitmask));
-  let m = wideMulU32(random, upperBoundU32);
+/** Random `u16` in the half-open range [start, end). */
+export function rngNextInRangeU16(rng: RandomNumberGenerator, start: number, end: number): number {
+  if (start >= end) throw new Error("start must be less than end");
+  const lo = start & 0xffff;
+  const hi = end & 0xffff;
+  const delta = (hi - lo) & 0xffff;
+  if (delta === 0xffff) {
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0xffffn));
+  }
+  return (lo + rngNextWithUpperBoundU16(rng, delta)) & 0xffff;
+}
 
-  if (Number(m[0]) < upperBoundU32) {
-    // t = (0 - upperBound) % upperBound (wrapping subtraction)
-    const t = ((bitmask + 1 - upperBoundU32) >>> 0) % upperBoundU32;
-    while (Number(m[0]) < t) {
-      random = Number(rng.nextU64() & BigInt(bitmask));
-      m = wideMulU32(random, upperBoundU32);
-    }
+/** Random `u32` in the half-open range [start, end). */
+export function rngNextInRangeU32(rng: RandomNumberGenerator, start: number, end: number): number {
+  if (start >= end) throw new Error("start must be less than end");
+  const lo = start >>> 0;
+  const hi = end >>> 0;
+  const delta = (hi - lo) >>> 0;
+  if (delta === 0xffffffff) {
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0xffffffffn));
   }
+  return (lo + rngNextWithUpperBoundU32(rng, delta)) >>> 0;
+}
 
-  return Number(m[1]);
+/** Random `u64` in the half-open range [start, end). */
+export function rngNextInRangeU64(rng: RandomNumberGenerator, start: bigint, end: bigint): bigint {
+  if (start >= end) throw new Error("start must be less than end");
+  const mask64 = 0xffffffffffffffffn;
+  const delta = (end - start) & mask64;
+  if (delta === mask64) {
+    // Every u64 fits in u64 — `from_u64::<u64>` is total — no throw.
+    return rng.nextU64();
+  }
+  return (start + rngNextWithUpperBoundU64(rng, delta)) & mask64;
 }
 
 /**
- * Returns a random value within the specified range [start, end) using 32-bit arithmetic.
- * This matches Rust's behavior when called with i32 types.
+ * Alias of `rngNextInRangeU64`. Kept for API backwards compatibility.
  *
- * @param rng - The random number generator to use
- * @param start - The lower bound (inclusive) as i32
- * @param end - The upper bound (exclusive) as i32
- * @returns A random i32 value within the bounds
+ * @deprecated Prefer the explicit-width name `rngNextInRangeU64`.
  */
-export function rngNextInRangeI32(rng: RandomNumberGenerator, start: number, end: number): number {
-  if (start >= end) {
-    throw new Error("start must be less than end");
+export const rngNextInRange = rngNextInRangeU64;
+
+/** Random `i8` in the half-open range [start, end). */
+export function rngNextInRangeI8(rng: RandomNumberGenerator, start: number, end: number): number {
+  if (start >= end) throw new Error("start must be less than end");
+  const lo = (start << 24) >> 24;
+  const hi = (end << 24) >> 24;
+  const delta = toMagnitude(hi - lo, 8);
+  if (delta === 0xff) {
+    // i8::from_u64 succeeds only when value <= i8::MAX = 127
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0x7fn));
   }
+  const random = rngNextWithUpperBoundU8(rng, delta);
+  return ((lo + random) << 24) >> 24;
+}
 
-  const startI32 = start | 0;
-  const endI32 = end | 0;
-  const delta = toMagnitude(endI32 - startI32, 32);
+/** Random `i16` in the half-open range [start, end). */
+export function rngNextInRangeI16(rng: RandomNumberGenerator, start: number, end: number): number {
+  if (start >= end) throw new Error("start must be less than end");
+  const lo = (start << 16) >> 16;
+  const hi = (end << 16) >> 16;
+  const delta = toMagnitude(hi - lo, 16);
+  if (delta === 0xffff) {
+    // i16::from_u64 succeeds only when value <= i16::MAX = 32767
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0x7fffn));
+  }
+  const random = rngNextWithUpperBoundU16(rng, delta);
+  return ((lo + random) << 16) >> 16;
+}
 
+/** Random `i32` in the half-open range [start, end). */
+export function rngNextInRangeI32(rng: RandomNumberGenerator, start: number, end: number): number {
+  if (start >= end) throw new Error("start must be less than end");
+  const lo = start | 0;
+  const hi = end | 0;
+  const delta = toMagnitude(hi - lo, 32);
   if (delta === 0xffffffff) {
-    return rng.nextU32() | 0;
+    // i32::from_u64 succeeds only when value <= i32::MAX = 2147483647
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0x7fffffffn));
   }
-
   const random = rngNextWithUpperBoundU32(rng, delta);
-  return (startI32 + random) | 0;
+  return (lo + random) | 0;
 }
 
-/**
- * Returns a random value within the specified range [start, end).
- *
- * @param rng - The random number generator to use
- * @param start - The lower bound (inclusive)
- * @param end - The upper bound (exclusive)
- * @returns A random value within the bounds of the range
- */
-export function rngNextInRange(rng: RandomNumberGenerator, start: bigint, end: bigint): bigint {
-  if (start >= end) {
-    throw new Error("start must be less than end");
+/** Random `i64` in the half-open range [start, end). */
+export function rngNextInRangeI64(rng: RandomNumberGenerator, start: bigint, end: bigint): bigint {
+  if (start >= end) throw new Error("start must be less than end");
+  const delta = toMagnitude64(end - start);
+  const mask64 = 0xffffffffffffffffn;
+  if (delta === mask64) {
+    // i64::from_u64 succeeds only when value <= i64::MAX = (2^63 - 1)
+    return fromU64ThrowsIfAbove(rng.nextU64(), 0x7fffffffffffffffn);
   }
+  const random = rngNextWithUpperBoundU64(rng, delta);
+  return fromMagnitude64((toMagnitude64(start) + random) & mask64);
+}
 
-  const delta = end - start;
+/** Random `u8` in the closed range [start, end]. */
+export function rngNextInClosedRangeU8(
+  rng: RandomNumberGenerator,
+  start: number,
+  end: number,
+): number {
+  if (start > end) throw new Error("start must be less than or equal to end");
+  const lo = start & 0xff;
+  const hi = end & 0xff;
+  const delta = (hi - lo) & 0xff;
+  if (delta === 0xff) {
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0xffn));
+  }
+  return (lo + rngNextWithUpperBoundU8(rng, delta + 1)) & 0xff;
+}
 
-  // If delta covers the entire range, just return a random value
-  const maxU64 = 0xffffffffffffffffn;
-  if (delta === maxU64) {
-    return rng.nextU64();
+/** Random `u16` in the closed range [start, end]. */
+export function rngNextInClosedRangeU16(
+  rng: RandomNumberGenerator,
+  start: number,
+  end: number,
+): number {
+  if (start > end) throw new Error("start must be less than or equal to end");
+  const lo = start & 0xffff;
+  const hi = end & 0xffff;
+  const delta = (hi - lo) & 0xffff;
+  if (delta === 0xffff) {
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0xffffn));
   }
+  return (lo + rngNextWithUpperBoundU16(rng, delta + 1)) & 0xffff;
+}
 
-  const random = rngNextWithUpperBound(rng, delta);
-  return start + random;
+/** Random `u32` in the closed range [start, end]. */
+export function rngNextInClosedRangeU32(
+  rng: RandomNumberGenerator,
+  start: number,
+  end: number,
+): number {
+  if (start > end) throw new Error("start must be less than or equal to end");
+  const lo = start >>> 0;
+  const hi = end >>> 0;
+  const delta = (hi - lo) >>> 0;
+  if (delta === 0xffffffff) {
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0xffffffffn));
+  }
+  return (lo + rngNextWithUpperBoundU32(rng, delta + 1)) >>> 0;
 }
 
-/**
- * Returns a random value within the specified closed range [start, end].
- *
- * @param rng - The random number generator to use
- * @param start - The lower bound (inclusive)
- * @param end - The upper bound (inclusive)
- * @returns A random value within the bounds of the range
- */
-export function rngNextInClosedRange(
+/** Random `u64` in the closed range [start, end]. */
+export function rngNextInClosedRangeU64(
   rng: RandomNumberGenerator,
   start: bigint,
   end: bigint,
 ): bigint {
-  if (start > end) {
-    throw new Error("start must be less than or equal to end");
-  }
-
-  const delta = end - start;
-
-  // If delta covers the entire range, just return a random value
-  const maxU64 = 0xffffffffffffffffn;
-  if (delta === maxU64) {
+  if (start > end) throw new Error("start must be less than or equal to end");
+  const mask64 = 0xffffffffffffffffn;
+  const delta = (end - start) & mask64;
+  if (delta === mask64) {
     return rng.nextU64();
   }
-
-  const random = rngNextWithUpperBound(rng, delta + 1n);
-  return start + random;
+  return (start + rngNextWithUpperBoundU64(rng, delta + 1n)) & mask64;
 }
 
 /**
- * Returns a random value within the specified closed range [start, end] for i32 values.
- * Convenience function that handles signed 32-bit integers.
+ * Alias of `rngNextInClosedRangeU64`. Kept for API backwards compatibility.
  *
- * @param rng - The random number generator to use
- * @param start - The lower bound (inclusive) as i32
- * @param end - The upper bound (inclusive) as i32
- * @returns A random i32 value within the bounds of the range
+ * @deprecated Prefer the explicit-width name `rngNextInClosedRangeU64`.
  */
-export function rngNextInClosedRangeI32(
+export const rngNextInClosedRange = rngNextInClosedRangeU64;
+
+/** Random `i8` in the closed range [start, end]. */
+export function rngNextInClosedRangeI8(
   rng: RandomNumberGenerator,
   start: number,
   end: number,
 ): number {
-  if (start > end) {
-    throw new Error("start must be less than or equal to end");
+  if (start > end) throw new Error("start must be less than or equal to end");
+  const lo = (start << 24) >> 24;
+  const hi = (end << 24) >> 24;
+  const delta = toMagnitude(hi - lo, 8);
+  if (delta === 0xff) {
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0x7fn));
   }
+  const random = rngNextWithUpperBoundU8(rng, delta + 1);
+  return ((lo + random) << 24) >> 24;
+}
 
-  // Convert to i32
-  const startI32 = start | 0;
-  const endI32 = end | 0;
-
-  // Calculate delta as u32 magnitude
-  const delta = toMagnitude(endI32 - startI32, 32);
+/** Random `i16` in the closed range [start, end]. */
+export function rngNextInClosedRangeI16(
+  rng: RandomNumberGenerator,
+  start: number,
+  end: number,
+): number {
+  if (start > end) throw new Error("start must be less than or equal to end");
+  const lo = (start << 16) >> 16;
+  const hi = (end << 16) >> 16;
+  const delta = toMagnitude(hi - lo, 16);
+  if (delta === 0xffff) {
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0x7fffn));
+  }
+  const random = rngNextWithUpperBoundU16(rng, delta + 1);
+  return ((lo + random) << 16) >> 16;
+}
 
-  // If delta covers the entire u32 range, just return a random value
+/** Random `i32` in the closed range [start, end]. */
+export function rngNextInClosedRangeI32(
+  rng: RandomNumberGenerator,
+  start: number,
+  end: number,
+): number {
+  if (start > end) throw new Error("start must be less than or equal to end");
+  const lo = start | 0;
+  const hi = end | 0;
+  const delta = toMagnitude(hi - lo, 32);
   if (delta === 0xffffffff) {
-    return rng.nextU32() | 0;
+    return Number(fromU64ThrowsIfAbove(rng.nextU64(), 0x7fffffffn));
   }
-
   const random = rngNextWithUpperBoundU32(rng, delta + 1);
-  return (startI32 + random) | 0;
+  return (lo + random) | 0;
+}
+
+/** Random `i64` in the closed range [start, end]. */
+export function rngNextInClosedRangeI64(
+  rng: RandomNumberGenerator,
+  start: bigint,
+  end: bigint,
+): bigint {
+  if (start > end) throw new Error("start must be less than or equal to end");
+  const delta = toMagnitude64(end - start);
+  const mask64 = 0xffffffffffffffffn;
+  if (delta === mask64) {
+    return fromU64ThrowsIfAbove(rng.nextU64(), 0x7fffffffffffffffn);
+  }
+  const random = rngNextWithUpperBoundU64(rng, delta + 1n);
+  return fromMagnitude64((toMagnitude64(start) + random) & mask64);
 }
 
 /**
- * Returns a fixed-size array of random bytes.
+ * Returns a random fixed-size byte array.
  *
- * @param rng - The random number generator to use
- * @param size - The size of the array to return
- * @returns A Uint8Array of the specified size filled with random bytes
+ * Mirrors Rust's `rng_random_array<const N: usize>()` but takes the size at
+ * runtime since JavaScript lacks const generics.
  */
 export function rngRandomArray(rng: RandomNumberGenerator, size: number): Uint8Array {
   const data = new Uint8Array(size);
@@ -259,10 +414,8 @@ export function rngRandomArray(rng: RandomNumberGenerator, size: number): Uint8A
 }
 
 /**
- * Returns a random boolean value.
- *
- * @param rng - The random number generator to use
- * @returns A random boolean
+ * Returns a random boolean. Mirrors Rust's `rng_random_bool` which tests
+ * whether `next_u32()` is a multiple of 2.
  */
 export function rngRandomBool(rng: RandomNumberGenerator): boolean {
   return (rng.nextU32() & 1) === 0;
@@ -270,9 +423,6 @@ export function rngRandomBool(rng: RandomNumberGenerator): boolean {
 
 /**
  * Returns a random 32-bit unsigned integer.
- *
- * @param rng - The random number generator to use
- * @returns A random u32 value
  */
 export function rngRandomU32(rng: RandomNumberGenerator): number {
   return rng.nextU32();

package/src/secure-random.ts

@@ -1,22 +1,19 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from bc-rand-rust/src/secure_random.rs
 
 import type { RandomNumberGenerator } from "./random-number-generator.js";
 
 /**
- * Detects the crypto API available in the current environment.
- * Works in both Node.js and browser environments.
+ * Returns the Web Crypto API for the current environment. Available natively
+ * in browsers and in Node.js >= 15 via `globalThis.crypto`.
  */
 function getCrypto(): Crypto {
-  // Browser environment
-  if (
-    typeof globalThis !== "undefined" &&
-    globalThis.crypto !== null &&
-    globalThis.crypto !== undefined
-  ) {
-    return globalThis.crypto;
-  }
-  // Node.js environment - globalThis.crypto is also available in Node.js >= 15
-  if (typeof globalThis.crypto !== "undefined") {
+  if (typeof globalThis !== "undefined" && globalThis.crypto != null) {
     return globalThis.crypto;
   }
   throw new Error("No crypto API available in this environment");
@@ -36,13 +33,16 @@ export function randomData(size: number): Uint8Array {
  */
 export function fillRandomData(data: Uint8Array): void {
   const crypto = getCrypto();
-  crypto.getRandomValues(data);
+  crypto.getRandomValues(data as Uint8Array<ArrayBuffer>);
 }
 
 /**
  * Returns the next cryptographically strong random 64-bit unsigned integer.
+ *
+ * This mirrors Rust's module-private `secure_random::next_u64()` and is not
+ * re-exported from the package surface (matches Rust `lib.rs` behavior).
  */
-export function nextU64(): bigint {
+function nextU64(): bigint {
   const data = new Uint8Array(8);
   fillRandomData(data);
   const view = new DataView(data.buffer);
@@ -59,12 +59,12 @@ export function nextU64(): bigint {
 export class SecureRandomNumberGenerator implements RandomNumberGenerator {
   /**
    * Returns the next random 32-bit unsigned integer.
+   *
+   * Mirrors Rust's `next_u32` impl which returns `next_u64() as u32` —
+   * the low 32 bits of a 64-bit draw.
    */
   nextU32(): number {
-    const data = new Uint8Array(4);
-    fillRandomData(data);
-    const view = new DataView(data.buffer);
-    return view.getUint32(0, true) >>> 0; // little-endian, unsigned
+    return Number(this.nextU64() & 0xffffffffn) >>> 0;
   }
 
   /**
@@ -95,3 +95,13 @@ export class SecureRandomNumberGenerator implements RandomNumberGenerator {
     fillRandomData(data);
   }
 }
+
+/**
+ * Returns a thread-local cryptographically-strong RNG. Mirrors Rust's
+ * `thread_rng()`. In TypeScript there are no thread-locals, so this returns
+ * a fresh `SecureRandomNumberGenerator` — every instance backs onto the
+ * same Web Crypto source, so the effect is equivalent.
+ */
+export function threadRng(): SecureRandomNumberGenerator {
+  return new SecureRandomNumberGenerator();
+}