Random Number Generation

/**
 * Generates cryptographically secure random bytes
 * @param length - Number of random bytes to generate
 * @returns Uint8Array of random bytes
 */
function randombytes_buf(length);

/**
 * Generates deterministic random bytes from a seed
 * @param length - Number of bytes to generate
 * @param seed - 32-byte seed for deterministic generation
 * @returns Uint8Array of pseudorandom bytes
 */
function randombytes_buf_deterministic(length, seed);

// Generate random key
const key = sodium.randombytes_buf(32);

// Generate random nonce
const nonce = sodium.randombytes_buf(24);

// Generate deterministic bytes (useful for testing)
const seed = sodium.randombytes_buf(32);
const deterministicBytes1 = sodium.randombytes_buf_deterministic(64, seed);
const deterministicBytes2 = sodium.randombytes_buf_deterministic(64, seed);
// deterministicBytes1 === deterministicBytes2

/**
 * Generates a random 32-bit unsigned integer
 * @returns Random integer between 0 and 2^32-1
 */
function randombytes_random();

/**
 * Generates a uniform random integer in range [0, upper_bound)
 * @param upper_bound - Exclusive upper bound (must be > 0)
 * @returns Random integer between 0 and upper_bound-1
 */
function randombytes_uniform(upper_bound);

// Generate random 32-bit integer
const randomInt = sodium.randombytes_random();
console.log(randomInt); // e.g., 3847291038

// Generate random integer in specific range
const diceRoll = sodium.randombytes_uniform(6) + 1; // 1-6
const randomIndex = sodium.randombytes_uniform(arrayLength); // 0 to arrayLength-1

// Generate random boolean
const randomBool = sodium.randombytes_uniform(2) === 1;

/**
 * Stirs the entropy pool (generally not needed)
 */
function randombytes_stir();

/**
 * Closes the random number generator (cleanup)
 */
function randombytes_close();

/**
 * Sets a custom random number generator implementation
 * @param implementation - Custom RNG implementation object
 */
function randombytes_set_implementation(implementation);

// Generate keys for different algorithms
const secretboxKey = sodium.randombytes_buf(sodium.crypto_secretbox_KEYBYTES);
const authKey = sodium.randombytes_buf(sodium.crypto_auth_KEYBYTES);
const genericHashKey = sodium.randombytes_buf(sodium.crypto_generichash_KEYBYTES);

// Or use algorithm-specific key generators (recommended)
const secretboxKey2 = sodium.crypto_secretbox_keygen();
const authKey2 = sodium.crypto_auth_keygen();

// Generate nonces for encryption
const secretboxNonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
const boxNonce = sodium.randombytes_buf(sodium.crypto_box_NONCEBYTES);
const aeadNonce = sodium.randombytes_buf(sodium.crypto_aead_chacha20poly1305_ietf_NPUBBYTES);

// Generate salt for password hashing
const salt = sodium.randombytes_buf(sodium.crypto_pwhash_SALTBYTES);

const hash = sodium.crypto_pwhash_str(
  password,
  sodium.crypto_pwhash_OPSLIMIT_INTERACTIVE,
  sodium.crypto_pwhash_MEMLIMIT_INTERACTIVE
);

// Generate session tokens
const sessionToken = sodium.to_hex(sodium.randombytes_buf(32));

// Generate random IDs
const userId = sodium.randombytes_uniform(1000000); // 0-999999

// Generate random strings (base64 encoded)
const randomString = sodium.to_base64(
  sodium.randombytes_buf(32),
  sodium.base64_variants.URLSAFE_NO_PADDING
);

// Randomly select from array
const items = ['apple', 'banana', 'cherry', 'date'];
const randomItem = items[sodium.randombytes_uniform(items.length)];

// Shuffle array (Fisher-Yates)
function shuffle(array) {
  const result = [...array];
  for (let i = result.length - 1; i > 0; i--) {
    const j = sodium.randombytes_uniform(i + 1);
    [result[i], result[j]] = [result[j], result[i]];
  }
  return result;
}

const shuffled = shuffle(['A', 'B', 'C', 'D', 'E']);

// Create deterministic "random" data for tests
const testSeed = new Uint8Array(32).fill(1); // Fixed seed
const testKey = sodium.randombytes_buf_deterministic(32, testSeed);
const testNonce = sodium.randombytes_buf_deterministic(24, testSeed);

// Same seed always produces same output
const sameKey = sodium.randombytes_buf_deterministic(32, testSeed);
// testKey === sameKey