ths-csprng

Standard RNGs assume that once you’ve seeded them, the whole history of how that seed was created just disappears. In reality, if someone can reconstruct the exact physical state of your system—or somehow “look back” in time—your randomness stops being random.

If you buy into a block universe or superdeterminism, that “random” seed was never random at all. It’s just a fixed point in spacetime. To an observer with enough computing power or a view further down the timeline, your private key isn’t secret — it’s already history.

THS (Temporal-Hardening Solution) is an attempt to push back against that. It’s a cryptographic wrapper that turns the problem from “break the math” into “do a massive amount of physical work.” It makes retrocausal attacks or precise state reconstruction much harder by forcing the attacker to simulate real-world chaos.

In short: it uses macroscopic messiness as a defense against microscopic observation.

The “Observer from the Future” Problem

Information doesn’t just vanish (see the Quantum No-Hiding Theorem). It spreads into the environment. If an adversary can reconstruct past states—whether through retrocausality, solving hidden variables, or digging through micro-architectural leaks—traditional seeds become vulnerable.

Normally, a seed is generated at a single point in time (T0). If that moment is reconstructed, your entropy is gone.

THS fixes this by replacing a single seed with a temporal sequence of many moments (T1, T2, T3, …, Tn). To recover your secret, an attacker doesn’t just need to glance at the past—they have to accurately simulate the entire noisy evolution of the machine across hundreds of layers of timing jitter, memory state, and CPU behavior.

Full API context optimized for AI assistants and contributors is available in llms-full.txt.

🚀 Getting Started

npm install ths-csprng

🛠️ Quick Start

Modern ESM (Node.js 18+, Vite, Bun)

import THS from 'ths-csprng';

// Standard 256-bit secure random buffer
const entropy = await THS.random(32);

// High-security hardened key
const masterKey = await THS.random(64, { 
    layers: 512,          // 512 temporal slices
    harden: 3,            // Heavy Argon2id hardening
    mem: 65536,           // 64MB memory cost
    trng: true,           // Try reading directly from /dev/urandom
    sandwichMode: true,   // Append post-generation noise layer
    maxSandwichCount: 5   // 5 additional metabolic snapshot iterations
});

Legacy / Standard CommonJS

const { THS } = require('ths-csprng');

(async () => {
    const entropy = await THS.random(32);
    console.log(entropy.toString('hex'));
})();

💎 The Hardening Levels

You can dial the security up or down depending on how much “weight” you want the key to have.

| Level | Mode | Description | | :--- | :--- | :--- | | 0 / 1 | Basic | Captures high-resolution monotonic time (process.hrtime.bigint()). If Level 1, injects supplemental CSPRNG entropy into each cycle. | | 2 | Machine State | Level 1 + full metabolic collection (captures real-time CPU nanoseconds, process memory usage, V8 heap usage, RAM state, context switches, and SHA3-512 hashed system memory noise). | | 3 | Heavy | Level 2 + Argon2id memory-hardened processing using the metabolic snapshot as a message payload. |

⚙️ Full Configuration Options

const options = {
  layers: 128,             // Temporal slices/iterations (2 to 65536)
  harden: 2,               // 0–3 (hardening depth/metabolic capture level)
  trng: false,             // Force /dev/urandom usage (falls back to crypto.randomBytes)
  buffer: true,            // Return Node.js Buffer (false for Uint8Array)

  // Post-Generation Noise Execution
  sandwichMode: true,      // Captures additional snapshots post-digest to clear footprints
  maxSandwichCount: 3,     // Iteration count for post-generation noise loops (1 to 65536)

  // Argon2id Specifics (Requires harden: 3)
  memoryH: 1,              // Number of Argon2id runs/layers to enforce memory-hardening
  mem: 16384,              // Memory cost in KiB (default 16MB)
  passes: 3,               // (t) time cost iterations
  parallelism: 4,          // (p) parallel execution threads

  label: 'THS-Default-v1'  // KMAC256 personalization string
};

const bytes = await THS.random(32, options);

🧬 Advanced API

Direct Utils

// ESM
import { Utils } from 'ths-csprng';
// or CJS
const { Utils } = require('ths-csprng');

// Directly generate a structured metabolic snapshot buffer
// Params: (harden, maxHardeningThreshold, mem, passes, parallelism, sequentialSalt, useUrandom)
const snapshotBuffer = await Utils.snapshot(2, 1, 16384, 3, 4, 0, false); 

// Fast-path serialization of BigInt values prepended with a 16-bit Big-Endian length header
const bufferedBigInt = Utils.bigIntToBuffer(1234567890n);

// Direct access to the internal TRNG/CSPRNG byte harvester without temporal loops
const raw = await THS.raw(32);

Browser Support

// Uses window.crypto in browser environments or node:crypto when running in server layers.
const buf1 = new Uint32Array(32);
const buf2 = new Uint16Array(32);
const buf3 = new Uint8Array(32);

THS.fillRandom(buf1);
THS.fillRandom(buf2);
THS.fillRandom(buf3);

Convenient Aliases

import { randomBytes, THS } from 'ths-csprng';

// Sync: Standard WebCrypto/CSPRNG array filling
const uintBytes = randomBytes(32); // Returns a Uint8Array
const bufferBytes = Buffer.from(randomBytes(32)); // Safely wrapped into a Node.js Buffer

// Async: Activates full THS.random() multi-layered temporal hardening loop
const secureBytes = await randomBytes(
    32,
    true,   // isHardenRNG boolean flag
    { layers: 64, harden: 2 }
);

// Shorthand Method Aliases
await THS.rand(32);
await THS.rnd(32);

Why should you care?

Most of the crypto world acts like randomness is a solved problem. But with hardware backdoors, VM cloning, and advanced side-channel attacks, standard entropy sources might be more fragile than they look.

THS tries to bridge raw hardware chaos with solid cryptographic primitives, forcing 2n security to be exactly as 2n, not less.

Use Cases

• Everyday apps: Use THS.fillRandom(arr) or randomBytes(len) for fast, reliable, standard randomness.
• Entropy Research / Custom PRNGs: Import the subpath ths-csprng/utils to feed metabolic snapshots directly into your own DRBGs as a source of high-variance, hardware-bound entropy.
• High-value keys: Use THS.random() with harden: 3 when you want seeds that are computationally irreducible — an attacker would need to reconstruct exact nanosecond-level CPU and memory states across hundreds of noisy iterations.

Threat Model

Threat models range from the hypothetical (retrocausality is possible in real-life + proofs) to the theoretically niche (such as the “cold start” entropy problem in serverless environments).

However, the most critical threats involve real-world hardware vulnerabilities that compromise the security of every cryptographic seed and encryption key generated on a device. Whether you are using post-quantum libraries or legacy suites, security is merely an illusion if:

• The entropy source is a single, static “snapshot” in time AND the adversary successfully recovers it.
• The source relies on a mathematically predictable DRBG source, such as the infamous DUAL_EC_DRBG.

[!NOTE]

Hardening Level 3 (Heavy) is computationally expensive by design. It is intended for generating long-term master keys or seeds. If your use case requires high-frequency random bytes (e.g., UUIDs or nonces), use Level 0 or Level 1.

🛠 ️Development & Verification

npm run check        # test + verify checksums
npm run build        # minify + generate docs + checksums
npm test

The project uses:

• terser for minification
• SHA-256 checksums for all built files
• Strict mode + comprehensive test suite

⭐ Contributor(s)

License

Licensed under the Apache License, Version 2.0; a robust, permissive license that includes an explicit grant of patent rights and provides protection against contributor liability.

Copyright © 2026 Aries Harbinger. See the LICENSE file for full details.

🔗 Links

• Github Repository
• npm Package
• Full AI Context llms-full.txt (for contributors / LLM assistants)