@sparksome/big-bang-entropy

Node.js client for the Big Bang Entropy API.

Big Bang Entropy is a public physical entropy project. Its entropy stream is derived from cosmic radio noise captured by an antenna and SDR hardware, then processed by the Big Bang Entropy generator and exposed through simple binary HTTP endpoints.

At a high level, the source pipeline looks like this:

antenna -> SDR (e.g. PlutoSDR, RTL-SDR) -> sdr-node -> UDP -> generator -> entropy pool -> HTTP/TCP clients

This package makes that API easy to use from Node.js. It can fetch raw entropy bytes, return them as text, mix remote entropy with the local Node.js RNG, and generate tokens or passwords.

The recommended API is getMixedEntropy(): it fetches entropy from Big Bang Entropy, reads local entropy with crypto.randomBytes(), and mixes both sources with SHA-512.

This library does not replace the operating system RNG. It lets you add an external physical entropy source to your local randomness pipeline. Do not use the raw API signal directly for security-sensitive work without mixing it with local RNG unless you have a very specific threat model.

Why Physical Entropy?

Physical entropy gives your application an independent randomness source outside the host operating system and cloud runtime. Mixing it with Node.js crypto.randomBytes() adds source diversity, which is useful as a defense-in-depth measure when tokens, secrets, test vectors, or long-lived cryptographic material matter. Cosmic radio noise is not deterministic application state, not a PRNG seed, and not generated by the same machine that consumes it. The safest pattern is still to combine it with local RNG, so security does not depend on any single source.

Installation

npm install @sparksome/big-bang-entropy

Quick Start

import { getMixedEntropy, generateToken } from "@sparksome/big-bang-entropy";

const entropy = await getMixedEntropy(32);
const token = await generateToken();

console.log(entropy.toString("hex"));
console.log(token);

Default Endpoints

Default baseUrl:

https://entropy.sparksome.pl

Default entropy endpoints:

https://entropy.sparksome.pl/raw
https://entropy.sparksome.pl/raw/stream?bytes=1048576

For direct unbuffered small requests, the client can use /raw. For larger requests and buffer refills, it uses /raw/stream?bytes=<bytes>. The default threshold is 1024 bytes and can be changed with streamThresholdBytes.

By default, the client keeps a small on-demand local entropy buffer of 4096 bytes to avoid one HTTP request per token in loops. It does not download entropy in the background. The buffer is filled only when needed, consumed once, and never reused. Set entropyBufferSizeBytes: 0 to disable buffering entirely.

Examples

Fetch Entropy as Hex

import { getEntropyHex } from "@sparksome/big-bang-entropy";

const hex = await getEntropyHex(32);
console.log(hex);

Fetch 1 MB of Entropy

import { getEntropy } from "@sparksome/big-bang-entropy";

const oneMegabyte = await getEntropy(1_048_576);
console.log(oneMegabyte.length);

With the default configuration, this call uses:

/raw/stream?bytes=1048576

Generate a Token

import { generateToken } from "@sparksome/big-bang-entropy";

const token = await generateToken();
console.log(token);

generateToken(32) returns a 64-character hex token by default.

Generate a Password

import { generatePassword } from "@sparksome/big-bang-entropy";

const password = await generatePassword({
  length: 24,
  uppercase: true,
  lowercase: true,
  numbers: true,
  symbols: true
});

console.log(password);

The password generator does not use Math.random. Its randomness comes from getMixedEntropy().

Use a Custom baseUrl

import { createClient } from "@sparksome/big-bang-entropy";

const entropy = createClient({
  baseUrl: "https://entropy.example.com",
  timeoutMs: 5_000,
  retries: 2,
  userAgent: "my-service/1.0.0",
  streamThresholdBytes: 1_024
});

const token = await entropy.generateToken(32);
console.log(token);

Health Check

import { createClient } from "@sparksome/big-bang-entropy";

const entropy = createClient({
  healthUrl: "/health"
});

const health = await entropy.getHealth();

if (!health.ok) {
  console.error("Big Bang Entropy API unavailable", health);
}

If a dedicated health endpoint is not available, getHealth() checks /raw by default. You can later pass healthUrl without changing the calling code.

Fetch Entropy as Base64

import { getEntropyBase64 } from "@sparksome/big-bang-entropy";

const base64 = await getEntropyBase64(48);
console.log(base64);

Base64 output is convenient when entropy needs to be passed through JSON, environment variables, or text-only storage.

Generate Mixed Bytes for Your Own Crypto Flow

import { getMixedEntropy } from "@sparksome/big-bang-entropy";

const seedMaterial = await getMixedEntropy(64);

// Use seedMaterial with your own KDF, envelope encryption, or key rotation flow.
console.log(seedMaterial.toString("hex"));

Use this when you need bytes instead of a formatted token. The returned Buffer is already mixed with local Node.js RNG.

Handle API Errors

import {
  BigBangEntropyError,
  getMixedEntropy
} from "@sparksome/big-bang-entropy";

try {
  const entropy = await getMixedEntropy(32);
  console.log(entropy.toString("hex"));
} catch (error) {
  if (error instanceof BigBangEntropyError) {
    console.error(`Entropy request failed: ${error.code}`, error.message);
  } else {
    throw error;
  }
}

The client fails loudly when the API is unavailable, times out, or returns too little data.

Explicit Local Fallback

import { createClient } from "@sparksome/big-bang-entropy";

const entropy = createClient({
  allowLocalFallback: true,
  timeoutMs: 2_000
});

const bytes = await entropy.getEntropy(32);
console.log(bytes.toString("hex"));

This mode is intentionally opt-in. Use it only when your application can continue with local RNG alone and you are comfortable knowing that external physical entropy may not have been used for that call.

Optimize Token Loops with an Entropy Buffer

import { createClient } from "@sparksome/big-bang-entropy";

const entropy = createClient({
  entropyBufferSizeBytes: 65_536
});

const tokens = [];

for (let index = 0; index < 1_000; index += 1) {
  tokens.push(await entropy.generateToken());
}

console.log(tokens.length);

The client already uses a 4096 byte buffer by default. Raising it can reduce HTTP requests further in larger loops. The client fetches entropy chunks on demand, stores unused API bytes locally, and consumes them once across later calls. There is no background polling and no repeated use of buffered bytes.

API

createClient(options)

const client = createClient({
  baseUrl: "https://entropy.sparksome.pl",
  timeoutMs: 5_000,
  retries: 2,
  userAgent: "@sparksome/big-bang-entropy/0.1.0",
  streamThresholdBytes: 1_024,
  entropyBufferSizeBytes: 4_096,
  allowLocalFallback: false
});

Options:

• baseUrl - defaults to https://entropy.sparksome.pl
• timeoutMs - defaults to 5000
• retries - defaults to 2
• userAgent - defaults to @sparksome/big-bang-entropy/0.1.0
• streamThresholdBytes - defaults to 1024
• entropyBufferSizeBytes - defaults to 4096; small calls consume a local one-time-use API entropy buffer; set to 0 to disable buffering
• healthUrl - optional health endpoint, for example /health
• allowLocalFallback - defaults to false; when set to true, the client may explicitly use local RNG if the API is unavailable

Methods

• getEntropy(bytes): Promise<Buffer>
• getEntropyHex(bytes): Promise<string>
• getEntropyBase64(bytes): Promise<string>
• getMixedEntropy(bytes): Promise<Buffer>
• generateToken(bytes = 32): Promise<string>
• generatePassword(options): Promise<string>
• getHealth(): Promise<HealthResult>

Error Handling

The client does not silently fall back to local RNG. If the API is unavailable, the call fails unless you explicitly set allowLocalFallback: true.

Exported error classes:

• InvalidBytesError
• EntropyApiError
• EntropyTimeoutError
• InsufficientEntropyError
• InvalidPasswordOptionsError

All exported errors extend BigBangEntropyError and expose a code field, such as API_UNAVAILABLE, TIMEOUT, INSUFFICIENT_ENTROPY, or INVALID_BYTES.

TypeScript, ESM, and CommonJS

The package ships TypeScript types and both ESM and CommonJS builds:

import { createClient } from "@sparksome/big-bang-entropy";

const { createClient } = require("@sparksome/big-bang-entropy");

Node.js >=18 is required because the client uses the built-in fetch API.