@omnitronix/rng-server-core

GLI-11 certified random number generation algorithms for server-side gaming applications.

Provides high-quality, auditable RNG with secure seeding, output whitening, automatic reseeding, and bias-free integer generation. Designed for regulated gaming environments that require deterministic replay and statistical certification.

Installation

npm install @omnitronix/rng-server-core

Usage

Basic Random Number Generation

import { RNGEngine, SeederType } from "@omnitronix/rng-server-core";

// Create engine with secure (ChaCha20) seeding (default)
const rng = new RNGEngine();

// Or use software seeding for testing
const testRng = new RNGEngine(SeederType.SOFTWARE);

Generate a Single Integer

const result = rng.generateSingle(1, 100);
console.log(result.value); // integer in [1, 100]
console.log(result.seed);  // seed used for this generation

Generate a Float

const result = rng.generateFloat();
console.log(result.value); // float in [0, 1)

Generate a Batch of Integers

const result = rng.generateBatch(1, 6, 5);
console.log(result.value); // e.g. [3, 1, 6, 2, 4]

Generate a Batch of Floats

const result = rng.generateBatchFloats(10);
console.log(result.value); // 10 floats in [0, 1)

Deterministic Replay

Every generation records its seed so results can be reproduced for auditing:

const original = rng.generateSingle(1, 100, 42);
const replayed = rng.generateSingle(1, 100, 42);
// original.value === replayed.value

// Replay a specific index in a sequence
const value = rng.replayFromSeed(42, 5); // 6th raw value from seed 42

API Reference

RNGEngine

Constructor

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | seederType | SeederType | SeederType.SECURE | Seeding strategy (SECURE for ChaCha20, SOFTWARE for testing) |

Methods

| Method | Returns | Description | |--------|---------|-------------| | generateSingle(min, max, seed?) | RngOutcome | Random integer in [min, max] | | generateFloat(seed?) | RngOutcome | Random float in [0, 1) | | generateBatch(min, max, count, seed?) | RngOutcome | Array of random integers in [min, max] | | generateBatchFloats(count, seed?) | RngOutcome | Array of random floats in [0, 1) | | replayFromSeed(seed, index) | number | Replay raw value at index from seed |

RngOutcome

Returned by all generation methods:

| Property | Type | Description | |----------|------|-------------| | id | string | Unique UUID for this generation | | seed | number | Seed used (provided or auto-generated) | | value | number \| number[] | Generated value(s) | | timestamp | Date | When the value was generated | | min | number | Minimum of the requested range | | max | number | Maximum of the requested range |

Exports

// Main API
import { RNGEngine } from "@omnitronix/rng-server-core";

// Domain objects
import { RngOutcome } from "@omnitronix/rng-server-core";

// Entropy & seeders (advanced)
import { EntropyGenerator, SecureSeeder, SoftwareSeeder } from "@omnitronix/rng-server-core";

// Types
import type { RngOutcomeData, ISeeder } from "@omnitronix/rng-server-core";
import { SeederType } from "@omnitronix/rng-server-core";

Algorithm Overview

Mersenne Twister (MT19937)

The base PRNG is a standard MT19937 implementation with a 624-element state vector and a period of 2^19937 - 1.

Hardened Mersenne Twister

Wraps the base MT with three hardening layers required for GLI-11 compliance:

1. SHA-256 output whitening -- Every raw 32-bit MT output is hashed through SHA-256 before use. This eliminates the known linear relationships in raw MT output.

2. Rejection sampling -- Integer range mapping uses rejection sampling instead of modulo. This eliminates modulo bias so every value in the requested range has exactly equal probability (GLI-11 section 3.3.1).

3. Automatic reseeding -- After every 1,000 generations the engine reseeds from the secure seeder. This limits the window of predictability if internal state were ever compromised.

Secure Seeding

The default SecureSeeder generates seeds using ChaCha20 with a random 256-bit key and 96-bit nonce sourced from Node.js crypto.randomBytes. This provides cryptographically strong initial state.

GLI-11 Compliance

This package addresses the following GLI-11 Technical Standards requirements:

• 3.2.3 Reseeding -- Automatic periodic reseeding from a cryptographic source
• 3.3.1 Uniform distribution -- Rejection sampling eliminates modulo bias
• Replay capability -- Deterministic replay from any seed for audit verification
• Output unpredictability -- SHA-256 whitening prevents state recovery from output

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Build
npm run build

License

Proprietary -- Omnitronix