ths-csprng 1.0.0 → 1.0.1

package/README.md

@@ -4,17 +4,13 @@
 
 <br />
 
-Standard RNGs are built on the naive assumption that once a seed is "randomized," the history of its creation just... disappears.
+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.
 
-In reality, if an observer can violate causality or reconstruct the precise physical state of a system, your "randomness" is just an entry in a ledger.
+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.
 
-<br />
-
-If you are on to a **Block Universe** or **Superdeterministic** model, your "random" seed is just a static coordinate in spacetime. To an observer with enough compute or a vantage point further down the temporal axis, your private key isn't a secret — it’s a historical fact.
+**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.
 
-**THS (Temporal-Hardening Solution)** is an attempt to fix this. It is a cryptographic wrapper that forces an adversary to move from attacking logic to attacking physical work, which makes “retrocausal observation” or state reconstruction exponentially challenging.
-
-To put it simply, it is a “Macroscopic Chaos as a defense against Microscopic Observation.”
+In short: it uses macroscopic messiness as a defense against microscopic observation.
 
 <br />
 
@@ -28,19 +24,13 @@ To put it simply, it is a “Macroscopic Chaos as a defense against Microscopic
 
 <br />
 
-## The "Observer from the Future" Problem
+## The “Observer from the Future” Problem
 
-Information doesn't just vanish (shout out to the **[Quantum No-Hiding Theorem](https://en.wikipedia.org/wiki/No-hiding_theorem)**). It leaks into the environment. If someone compromises your hardware or develops a way to reconstruct historical system states, your static seeds are toast.
+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.
 
-THS creates **Computational Fog**. Instead of a mathematical point, it binds your secret to the "metabolic noise" of your CPU at a specific nanosecond.
+Normally, a seed is generated at a single point in time (T=0). If that moment is reconstructed, your entropy is gone.
 
-<br />
-
-### How it actually works:
-
-* **Micro-Architectural Jitter:** Harvesting the tiny, unpredictable timing variances in your CPU clock caused by interrupts and thread scheduling.
-* **Physical Binding:** Capturing "ghost data" from uninitialized memory, we inject artifacts of the machine's immediate past into the entropy pool.
-* **Memory-Hardened Anchors:** We use **Argon2id** to spin up a shifting memory state. This forces an attacker to simulate a massive slice of physical RAM history just to see what happened in that one millisecond.
+THS fixes this by replacing a single seed with a temporal sequence of many moments (T₁, T₂, …, Tₙ). 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 />
 
@@ -48,7 +38,7 @@ THS creates **Computational Fog**. Instead of a mathematical point, it binds you
 
 <br />
 
-## Getting Started
+### 🚀 Getting Started
 
 ```bash
 npm install ths-csprng
@@ -56,35 +46,126 @@ npm install ths-csprng
 
 <br />
 
-### Quick Start
+### 🛠️ Quick Start
 
 ```javascript
 import THS from 'ths-csprng';
 
 (async () => {
-  // Get a 512-bit seed tied to this specific moment in hardware history
-  const seed = await THS.random(64);
-
-  // Deep hardening for keys meant to outlast the current paradigm
-  const key = await THS.random(32, { 
-    layers: 500,     // Increase the temporal iterations (slices)
-    harden: 3,       // Full metabolic collection + Argon2id
-    mem: 256 * 1024, // Prevents the "Cold Start Problem"
-    memoryH: 1,      // Run Argon2id at once
-    trng: true       // Use randomness from /dev/urandom directly (Unix-like only)
-  });
+    // 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
+    });
+    
+    console.log(masterKey.toString('hex'));
 })();
 ```
 
 <br />
 
+---
+
+### 💎 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** | **Basic** | High-resolution hardware timing (`hrtime`) per slice. |
+| **1** | **Entropy** | Level 0 + supplemental CSPRNG entropy injection. |
+| **2** | **Internal** | Level 1 + metabolic collection (Internal state snapshots). |
+| **3** | **Heavy** | Level 2 + **Argon2id** memory-hardened processing. |
+
+<br />
+
+---
+
+### ⚙️ Full Configuration Options
+
+```javascript
+const options = {
+  layers: 128,             // Number of temporal slices (2 to 65536)
+  harden: 2,               // 0–3 (hardening depth)
+  trng: false,             // Fallback to internal CSPRNG or /dev/urandom
+  hashOut: true,           // SHA3-512 hash each slice to avoid raw memory leaks
+  memoryH: 1,              // Argon2id iterations (only with harden: 3)
+  mem: 16384,              // Argon2id memory cost in KB (default 16MB)
+  label: 'THS-Default-v1'  // KMAC personalization string
+};
+
+const bytes = await THS.random(32, options);
+```
+
+<br />
+
+---
+
+### 🧬 Advanced API
+
+#### Direct Utils
+
+```javascript
+import Utils from 'ths-csprng/utils';
+import THS from 'ths-csprng';
+
+// Get a raw metabolic snapshot (T=n)
+const snap = await Utils.snapshot(2); 
+
+// Direct access to the internal TRNG/CSPRNG source
+const raw = await THS.raw(32);
+```
+
+
+#### Browser Support
+
+```javascript
+const buf = new Uint8Array(32);
+THS.fillRandom(buf); 
+```
+
+
+#### Convenient Aliases
+
+```javascript
+import { randomBytes } from 'ths-csprng';
+
+await randomBytes(32);
+await THS.rand(32);
+await THS.rnd(32);
+```
+
+<br />
+
 ## Why should you care?
 
-Most people **don't need this**.
+Most of the crypto world acts like randomness is a solved problem. But in 2026, 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.
+
+<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
 
-If you're building a todo app, move on. If you believe that the future cannot affect the past, that hardware manufacturers never lie, and that “random” numbers are truly disconnected from the physical state of the machine, then this tool is just a very complex way to waste CPU cycles.
+THS is aimed at situations where the attacker might try to:
 
-Temporal-Hardening Solution (THS) is designed for high-integrity cryptographic secrets where the threat model includes **historical state reconstruction** or **backdoored hardware**. It is a defense against the reality that even if your randomness is 100% deterministic within a closed system, it must be **Computationally Irreducible** to an outsider.
+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 />
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "ths-csprng",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Temporal-Hardening Solution: A CSPRNG wrapper designed to resist historical state reconstruction and hardware backdoors.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./utils": "./src/util.js"
   },
   "author": "Aries Harbinger",
   "license": "Apache-2.0",

package/src/index.js

@@ -18,13 +18,13 @@
 
 import Utils from './util.js';
 import { kmac256 } from '@noble/hashes/sha3-addons.js';
-import { createHash } from 'node:crypto';
+import { createHash, webcrypto } from 'node:crypto';
 
 
 /**
  * Temporal-Hardening Solution - Applied in Random Number Generator
  */
-export const THS = {
+export const THS = Object.freeze({
     /**
      * Generates cryptographically secure random bytes with temporal hardening.
      */
@@ -109,16 +109,23 @@ export const THS = {
         }
     },
 
-    async rand(len, o) { return await THS.random(len, o) },
-    async rnd (len, o) { return await THS.random(len, o) },
+    rand(len, o) { return THS.random(len, o) },
+    rnd (len, o) { return THS.random(len, o) },
 
-    // direct use raw random (fallback to randomBytes)
-    async raw(len)     { return await Utils.getRandom(len, true) }
-};
+    // Direct use of /dev/urandom  (fallback to randomBytes)
+    async raw(len)     { return await Utils.getRandom(len, true) },
+
+    // Direct Webcrypto access
+    fillRandom(arr)    {
+      return (
+        (typeof window !== 'undefined' && window.crypto)
+          ? window.crypto
+          : webcrypto
+      ).getRandomValues(arr)
+    }
+});
 
 // Must use await
-export const randomBytes = async (len, o) => {
-    return await THS.random(len, o);
-};
+export const randomBytes = (len, o) => THS.random(len, o);
 
 export default THS;

package/src/util.js

@@ -24,7 +24,7 @@ const argon2 = promisify(_argon2);
 const defined_past = process.hrtime.bigint();
 
 
-export const Utils = {
+export const Utils = Object.freeze({
     /**
      * Captures a high-resolution snapshot of the Node.js metabolic state.
      * Uses concatenation to prevent entropy collisions.
@@ -40,7 +40,7 @@ export const Utils = {
         // We use an array to preserve individual entropy of each metric
         const metrics = [
             process.hrtime.bigint(),                            // CPU Nanoseconds
-            BigInt(Math.round(process.uptime() * 1_000_000)), 
+            BigInt(Math.round(process.uptime() * 1_000_000)),
             BigInt(u.userCPUTime),                              // User-space CPU usage
             BigInt(u.systemCPUTime),                            // Kernel-space CPU usage
             BigInt(u.minorPageFault),                           // Soft memory faults
@@ -55,7 +55,7 @@ export const Utils = {
             BigInt(Math.round(performance.now() * 1_000_000)),
             defined_past,                                       // Process start anchor
             BigInt(Date.now()),                                 // Wall clock (Temporal anchor)
-            BigInt(s)                                           // Sequential salt
+            BigInt(s || 0)                                      // Sequential salt
         ].map(n => this.bigIntToBuffer(n));
 
         // Map metrics to uniquely structured buffers
@@ -164,6 +164,6 @@ export const Utils = {
         if (typeof input === 'string') return new TextEncoder().encode(input);
         return new TextEncoder().encode(JSON.stringify(input) || '');
     }
-};
+});
 
 export default Utils;