ths-csprng 1.0.2 → 1.1.0

package/README.md

@@ -1,6 +1,16 @@
-# THS (Temporal-Hardening Solution)
+<div align="center">
+<img src="./media/banner.png" alt="Banner" width="1250">
+</div>
 
-THS is a **security-hardened CSPRNG wrapper** designed to protect cryptographic seeds against historical state reconstruction and hardware backdoors. It replaces single-point-in-time entropy with a temporal sequence of "metabolic" system noise, forcing adversaries to perform massive physical work to recover keys.
+<br />
+
+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](https://en.wikipedia.org/wiki/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.
 
 <br />
 
@@ -8,7 +18,27 @@ THS is a **security-hardened CSPRNG wrapper** designed to protect cryptographic
 
 <br />
 
-### 🚀 Quick Start
+<div align="center">
+<img src="./media/illustration_1.png" alt="Illustration 1" width="1250">
+</div>
+
+<br />
+
+## The “Observer from the Future” Problem
+
+Information doesn’t just vanish (see the **[Quantum No-Hiding Theorem](https://en.wikipedia.org/wiki/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 (*T*<sub>0</sub>). If that moment is reconstructed, your entropy is gone.
+
+THS fixes this by replacing a single seed with a temporal sequence of many moments (*T*<sub>1</sub>, *T*<sub>2</sub>, *T*<sub>3</sub>, …, *T*<sub>n</sub>). 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.
+
+<br />
+
+---
+
+<br />
+
+### 🚀 Getting Started
 
 ```bash
 npm install ths-csprng
@@ -16,7 +46,9 @@ npm install ths-csprng
 
 <br />
 
-#### ESM (Node.js 18+, Vite, Bun)
+### 🛠️ Quick Start
+
+#### Modern ESM (Node.js 18+, Vite, Bun)
 
 ```javascript
 import THS from 'ths-csprng';
@@ -24,15 +56,16 @@ import THS from 'ths-csprng';
 // Standard 256-bit secure random buffer
 const entropy = await THS.random(32);
 
-// High-security hardened key (Computational work required to reconstruct)
+// 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
+    mem: 65536,       // 64MB memory cost
+    trng: true        // Try reading directly from /dev/urandom
 });
 ```
 
-#### CommonJS
+#### Legacy / Standard CommonJS
 
 ```javascript
 const THS = require('ths-csprng');
@@ -47,7 +80,9 @@ const THS = require('ths-csprng');
 
 ---
 
-### 💎 Hardening Levels
+### 💎 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 |
 | :--- | :--- | :--- |
@@ -60,20 +95,25 @@ const THS = require('ths-csprng');
 
 ---
 
-### ⚙️ Full Configuration
+### ⚙️ Full Configuration Options
 
 ```javascript
-const bytes = await THS.random(32, {
+const options = {
   layers: 128,             // Temporal slices (2 to 65536)
   harden: 2,               // 0–3 (hardening depth)
-  trng: false,             // Force /dev/urandom usage
-  buffer: true,            // Return Node.js Buffer
+  trng: false,             // Force /dev/urandom usage (w/ fallback)
+  buffer: true,            // Return Node.js Buffer (false for Uint8Array)
   
-  // Argon2id Specifics (Required for level 3)
-  mem: 16384,              // Memory cost in KB
-  passes: 3,               // Iterations
-  parallelism: 4           // Threads
-});
+  // Argon2id Specifics (Requires harden: 3)
+  memoryH: 1,              // Number of Argon2id cycles per layer
+  mem: 16384,              // Memory cost in KB (default 16MB)
+  passes: 3,               // (t) iterations
+  parallelism: 4,          // (p) parallel threads
+  
+  label: 'THS-Default-v1'  // KMAC personalization string
+};
+
+const bytes = await THS.random(32, options);
 ```
 
 <br />
@@ -118,15 +158,42 @@ await THS.rnd(32);
 
 <br />
 
----
+## 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 2<sup>n</sup> security to be exactly as 2<sup>n</sup>, not less.
+
+<br />
+
+<div align="center">
+<img src="./media/illustration_2.png" alt="Illustration 2" width="1250">
+</div>
+
+<br />
+
+## Use Cases
+
+* **Everyday apps:** Use `THS.fillRandom()` or `THS.raw()` for fast, reliable 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.
+
+
+<br />
+
+## Threat Model
+
+THS is aimed at situations where the attacker might try to:
+
+1. Reconstruct the historical state of your machine when the key was generated.
+2. Exploit VM snapshots that cause cloned instances to produce identical “random” output.
+3. Bypass or predict hardware entropy sources through backdoors or manufacturer influence.
+
+<br />
 
-### 🛡️ Threat Model
-THS is designed for high-stakes environments where an attacker might:
-1. **Reconstruct historical states** of a machine to guess seeds.
-2. **Exploit VM Snapshots** where cloned instances produce identical "random" output.
-3. **Bypass Hardware Backdoors** by mixing high-variance "metabolic" noise into the entropy pool.
+## ⚠️ Performance Note
 
-**Note:** Hardening Level 3 is computationally expensive. Use Level 0 or 1 for high-frequency needs like UUIDs or nonces.
+**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**.
 
 <br />
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ths-csprng",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Temporal-Hardening Solution: A CSPRNG wrapper designed to resist historical state reconstruction and hardware backdoors.",
   "main": "./src/index.js",
   "files": [

package/src/util.js

@@ -18,7 +18,7 @@
 
 const fs = require('node:fs/promises');
 const { promisify } = require('node:util');
-const { randomBytes, timingSafeEqual, argon2: _argon2 } = require('node:crypto');
+const { randomBytes, timingSafeEqual, createHash, argon2: _argon2 } = require('node:crypto');
 
 const argon2 = promisify(_argon2);
 const defined_past = process.hrtime.bigint();
@@ -57,15 +57,25 @@ const Utils = Object.freeze({
             BigInt(s || 0)                                      // Sequential salt
         ].map(n => this.bigIntToBuffer(n));
 
-        // Map metrics to uniquely structured buffers
-        const b = Buffer.concat([
+        // 128 bytes of raw, uninitialized system memory
+        // (May contain fragments of previous internal function calls/pointers, which is an additional entropy source)
+        const noise = Buffer.allocUnsafe(128);
+
+        // Hash that insecure system memory with SHA3-512
+        const hashedNoise = createHash('sha3-512')
+            .update(noise)
+            .update(process.hrtime.bigint().toString())
+            .digest();
 
-            // Inject 128 bytes of raw, uninitialized system memory 
-            // (May contain fragments of previous internal function calls/pointers)
-            Buffer.allocUnsafe(128),
+        // Wipe the noise immediately
+        noise.fill(0);
 
+        // Map metrics to uniquely structured buffers
+        const b = Buffer.concat([
+            hashedNoise,     // This is a COPY of the digest
             ...metrics
         ]);
+        hashedNoise.fill(0); // Wipe the hashed noise
 
         if (h <= 2 || s >= mh) return b;
 

package/src/util.mjs

@@ -18,7 +18,7 @@
 
 import fs from 'node:fs/promises';
 import { promisify } from 'node:util';
-import { randomBytes, timingSafeEqual, argon2 as _argon2 } from 'node:crypto';
+import { randomBytes, timingSafeEqual, createHash, argon2 as _argon2 } from 'node:crypto';
 
 const argon2 = promisify(_argon2);
 const defined_past = process.hrtime.bigint();
@@ -57,15 +57,25 @@ export const Utils = Object.freeze({
             BigInt(s || 0)                                      // Sequential salt
         ].map(n => this.bigIntToBuffer(n));
 
-        // Map metrics to uniquely structured buffers
-        const b = Buffer.concat([
+        // 128 bytes of raw, uninitialized system memory
+        // (May contain fragments of previous internal function calls/pointers, which is an additional entropy source)
+        const noise = Buffer.allocUnsafe(128);
+
+        // Hash that insecure system memory with SHA3-512
+        const hashedNoise = createHash('sha3-512')
+            .update(noise)
+            .update(process.hrtime.bigint().toString())
+            .digest();
 
-            // Inject 128 bytes of raw, uninitialized system memory 
-            // (May contain fragments of previous internal function calls/pointers)
-            Buffer.allocUnsafe(128),
+        // Wipe the noise immediately
+        noise.fill(0);
 
+        // Map metrics to uniquely structured buffers
+        const b = Buffer.concat([
+            hashedNoise,     // This is a COPY of the digest
             ...metrics
         ]);
+        hashedNoise.fill(0); // Wipe the hashed noise
 
         if (h <= 2 || s >= mh) return b;
 

package/npm-shrinkwrap.json

@@ -1,31 +0,0 @@
-{
-  "name": "ths-csprng",
-  "version": "1.0.2",
-  "lockfileVersion": 3,
-  "requires": true,
-  "packages": {
-    "": {
-      "name": "ths-csprng",
-      "version": "1.0.2",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@noble/hashes": "^2.2.0"
-      },
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/@noble/hashes": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-2.2.0.tgz",
-      "integrity": "sha512-IYqDGiTXab6FniAgnSdZwgWbomxpy9FtYvLKs7wCUs2a8RkITG+DFGO1DM9cr+E3/RgADRpFjrKVaJ1z6sjtEg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 20.19.0"
-      },
-      "funding": {
-        "url": "https://paulmillr.com/funding/"
-      }
-    }
-  }
-}