ths-csprng 1.0.1 → 1.0.2

package/README.md

@@ -1,16 +1,6 @@
-<div align="center">
-<img src="./media/banner.png" alt="Banner" width="1250">
-</div>
+# THS (Temporal-Hardening Solution)
 
-<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.
+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 />
 
@@ -18,52 +8,38 @@ In short: it uses macroscopic messiness as a defense against microscopic observa
 
 <br />
 
-<div align="center">
-<img src="./media/illustration.png" alt="Illustration" 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.
+### 🚀 Quick Start
 
-Normally, a seed is generated at a single point in time (T=0). 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₁, 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.
+```bash
+npm install ths-csprng
+```
 
 <br />
 
----
+#### ESM (Node.js 18+, Vite, Bun)
 
-<br />
+```javascript
+import THS from 'ths-csprng';
 
-### 🚀 Getting Started
+// Standard 256-bit secure random buffer
+const entropy = await THS.random(32);
 
-```bash
-npm install ths-csprng
+// High-security hardened key (Computational work required to reconstruct)
+const masterKey = await THS.random(64, { 
+    layers: 512,      // 512 temporal slices
+    harden: 3,        // Heavy Argon2id hardening
+    mem: 65536        // 64MB memory cost
+});
 ```
 
-<br />
-
-### 🛠️ Quick Start
+#### CommonJS
 
 ```javascript
-import THS from 'ths-csprng';
+const THS = require('ths-csprng');
 
 (async () => {
-    // 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'));
+    console.log(entropy.toString('hex'));
 })();
 ```
 
@@ -71,9 +47,7 @@ import THS from 'ths-csprng';
 
 ---
 
-### 💎 The Hardening Levels
-
-You can dial the security up or down depending on how much “weight” you want the key to have.
+### 💎 Hardening Levels
 
 | Level | Mode | Description |
 | :--- | :--- | :--- |
@@ -86,20 +60,20 @@ You can dial the security up or down depending on how much “weight” you want
 
 ---
 
-### ⚙️ Full Configuration Options
+### ⚙️ Full Configuration
 
 ```javascript
-const options = {
-  layers: 128,             // Number of temporal slices (2 to 65536)
+const bytes = await THS.random(32, {
+  layers: 128,             // 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);
+  trng: false,             // Force /dev/urandom usage
+  buffer: true,            // Return Node.js Buffer
+  
+  // Argon2id Specifics (Required for level 3)
+  mem: 16384,              // Memory cost in KB
+  passes: 3,               // Iterations
+  parallelism: 4           // Threads
+});
 ```
 
 <br />
@@ -111,10 +85,12 @@ const bytes = await THS.random(32, options);
 #### Direct Utils
 
 ```javascript
+// ESM
 import Utils from 'ths-csprng/utils';
-import THS from 'ths-csprng';
+// CJS
+const Utils = require('ths-csprng/utils');
 
-// Get a raw metabolic snapshot (T=n)
+// Get a raw metabolic snapshot (*T=n*)
 const snap = await Utils.snapshot(2); 
 
 // Direct access to the internal TRNG/CSPRNG source
@@ -142,30 +118,15 @@ await THS.rnd(32);
 
 <br />
 
-## Why should you care?
-
-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
+---
 
-THS is aimed at situations where the attacker might try to:
+### 🛡️ 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.
 
-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.
+**Note:** Hardening Level 3 is computationally expensive. Use Level 0 or 1 for high-frequency needs like UUIDs or nonces.
 
 <br />
 

package/npm-shrinkwrap.json

@@ -0,0 +1,31 @@
+{
+  "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/"
+      }
+    }
+  }
+}

package/package.json

@@ -1,12 +1,23 @@
 {
   "name": "ths-csprng",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Temporal-Hardening Solution: A CSPRNG wrapper designed to resist historical state reconstruction and hardware backdoors.",
-  "type": "module",
   "main": "./src/index.js",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "npm-shrinkwrap.json"
+  ],
   "exports": {
-    ".": "./src/index.js",
-    "./utils": "./src/util.js"
+    ".": {
+      "import": "./src/index.mjs",
+      "require": "./src/index.js"
+    },
+    "./utils": {
+      "import": "./src/util.mjs",
+      "require": "./src/util.js"
+    }
   },
   "author": "Aries Harbinger",
   "license": "Apache-2.0",

package/src/index.js

@@ -16,15 +16,15 @@
  * limitations under the License.
  */
 
-import Utils from './util.js';
-import { kmac256 } from '@noble/hashes/sha3-addons.js';
-import { createHash, webcrypto } from 'node:crypto';
+const Utils = require('./util.js');
+const { kmac256 } = require('@noble/hashes/sha3-addons.js');
+const { webcrypto } = require('node:crypto');
 
 
 /**
  * Temporal-Hardening Solution - Applied in Random Number Generator
  */
-export const THS = Object.freeze({
+const THS = Object.freeze({
     /**
      * Generates cryptographically secure random bytes with temporal hardening.
      */
@@ -33,10 +33,12 @@ export const THS = Object.freeze({
         layers = 128,             // number of timeline slices (iterations)
         harden = 2,               // levels: 0 (hrtime), 1 (+entropy), 2 (+internal), 3 (+Argon2id)
         trng = false,             // attempts to read /dev/urandom, fallback to randomBytes()
-        hashOut = true,           // whether to hash every moments instead of processing it as raw data
+        buffer = true,            // return as buffer
 
         memoryH = 1,              // number of Argon2id runs        (requires harden=3 level)
         mem = 16384,              // memory hardness of Argon2id    (default: 16MB)
+        passes = 3,               // (t) passes for Argon2id        (default: 3)
+        parallelism = 4,          // (p) parallelism for Argon2id   (default: 4)
         label = 'THS-Default-v1'  // kmac label
 
     } = {}) {
@@ -56,56 +58,40 @@ export const THS = Object.freeze({
         if ('number' !== typeof mem || mem < 1024)
             throw new Error(`Memory set [${mem}] for Argon2id must be a valid number and not be less than 1024 or 1KB.`);
 
-
-        // Collector for metabolic moments (The Message)
-        const moments = [];
-        let seed;
+        const seed = await Utils.getRandom(32, trng);
+        let k;
 
         try {
-            for (let i = 0; i < layers; i++) {
-                const moment = await Utils.snapshot(harden, memoryH, mem, i, trng);
-
-                if (!hashOut) { moments.push(moment); }
-
-                else {
-                  const h = createHash('sha3-512')  // Structurally immune to length-extension attacks
-                    .update(moment)
-                    .digest();
+            k = kmac256.create(seed, {
+                personalization: Utils.toBytes(label),
+                dkLen: length
+            });
 
-                  moment.fill(0);  // immediate wipe
-                  moments.push(h);
-                }
+            for (let i = 0; i < layers; i++) {
+                const moment = await Utils.snapshot(harden, memoryH, mem, passes, parallelism, i, trng);
+                k.update(moment), moment.fill(0);
 
-                // Supplemental entropy injected into the moment collection
                 if (harden >= 1) {
+                    // Supplemental entropy injected into the moment collection
                     const sup = await Utils.getRandom(12, trng);
-                    moments.push(sup);
+                    k.update(sup), sup.fill(0);
                 }
 
                 if (i < layers - 1) await Utils.jitter(trng);
             }
 
-            // Initial KMAC Key
-            seed = await Utils.getRandom(32, trng);
-
-            // Finalize with KMAC256
-            const result = kmac256(seed, Buffer.concat(moments), { 
-                personalization: Utils.toBytes(label),
-                dkLen: length
-            });
+            const out = k.digest();
+            if (!buffer) return out;
 
-            return Buffer.from(result);
+            const b = Buffer.from(out);
+            return out.fill(0), b;
         }
 
-        catch (e) { throw e }
-
-        finally {
-            // Cleanup sensitive memory
-            seed && seed.fill(0);
+        catch (e) { throw e; }
 
-            for (const m of moments) {
-                (m && typeof m.fill === 'function') && m.fill(0);
-            }
+        finally   {
+            seed.fill(0);
+            k = null;
         }
     },
 
@@ -113,19 +99,18 @@ export const THS = Object.freeze({
     rnd (len, o) { return THS.random(len, o) },
 
     // Direct use of /dev/urandom  (fallback to randomBytes)
-    async raw(len)     { return await Utils.getRandom(len, true) },
+    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)
+    fillRandom(arr) {
+        return (
+            (typeof window !== 'undefined' && window.crypto)
+                ? window.crypto
+                : webcrypto
+        ).getRandomValues(arr)
     }
 });
 
-// Must use await
-export const randomBytes = (len, o) => THS.random(len, o);
-
-export default THS;
+module.exports = THS;
+module.exports.THS = THS;
+module.exports.randomBytes = (len, o) => THS.random(len, o);

package/src/index.mjs

@@ -0,0 +1,117 @@
+/**
+ * THS (Temporal-Hardening Solution)
+ *
+ * Copyright 2026 Aries Harbinger
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Utils from './util.mjs';
+import { kmac256 } from '@noble/hashes/sha3-addons.js';
+import { createHash, webcrypto } from 'node:crypto';
+
+
+/**
+ * Temporal-Hardening Solution - Applied in Random Number Generator
+ */
+export const THS = Object.freeze({
+    /**
+     * Generates cryptographically secure random bytes with temporal hardening.
+     */
+    async random(length = 32, {
+
+        layers = 128,             // number of timeline slices (iterations)
+        harden = 2,               // levels: 0 (hrtime), 1 (+entropy), 2 (+internal), 3 (+Argon2id)
+        trng = false,             // attempts to read /dev/urandom, fallback to randomBytes()
+        buffer = true,            // return as buffer
+
+        memoryH = 1,              // number of Argon2id runs        (requires harden=3 level)
+        mem = 16384,              // memory hardness of Argon2id    (default: 16MB)
+        passes = 3,               // (t) passes for Argon2id        (default: 3)
+        parallelism = 4,          // (p) parallelism for Argon2id   (default: 4)
+        label = 'THS-Default-v1'  // kmac label
+
+    } = {}) {
+
+        if (length <= 0)
+            return Buffer.alloc(0);
+
+        if (layers < 2 || layers > 65536)
+            throw new Error(`Layer count [${layers}] is invalid. Requires a temporal span of 2-65536 cycles to ensure metabolic variance.`);
+
+        if (harden < 0 || harden > 3)
+            throw new Error(`Hardening level [${harden}] is unknown. Use 0 (Basic) through 3 (Heavy).`);
+
+        if (harden >= 3 && (memoryH < 1 || memoryH > layers))
+            throw new Error(`Memory hardening cycle count [${memoryH}] exceeds available temporal layers [${layers}].`);
+
+        if ('number' !== typeof mem || mem < 1024)
+            throw new Error(`Memory set [${mem}] for Argon2id must be a valid number and not be less than 1024 or 1KB.`);
+
+        const seed = await Utils.getRandom(32, trng);
+        let k;
+
+        try {
+            k = kmac256.create(seed, {
+                personalization: Utils.toBytes(label),
+                dkLen: length
+            });
+
+            for (let i = 0; i < layers; i++) {
+                const moment = await Utils.snapshot(harden, memoryH, mem, passes, parallelism, i, trng);
+                k.update(moment), moment.fill(0);
+
+                if (harden >= 1) {
+                    // Supplemental entropy injected into the moment collection
+                    const sup = await Utils.getRandom(12, trng);
+                    k.update(sup), sup.fill(0);
+                }
+
+                if (i < layers - 1) await Utils.jitter(trng);
+            }
+
+            const out = k.digest();
+            if (!buffer) return out;
+
+            const b = Buffer.from(out);
+            return out.fill(0), b;
+        }
+
+        catch (e) { throw e; }
+
+        finally   {
+            seed.fill(0);
+            k = null;
+        }
+    },
+
+    rand(len, o) { return THS.random(len, o) },
+    rnd (len, o) { return THS.random(len, o) },
+
+    // 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 = (len, o) => THS.random(len, o);
+
+export default THS;

package/src/util.js

@@ -16,28 +16,27 @@
  * limitations under the License.
  */
 
-import fs from 'node:fs/promises';
-import { promisify } from 'node:util';
-import { randomBytes, timingSafeEqual, argon2 as _argon2 } from 'node:crypto';
+const fs = require('node:fs/promises');
+const { promisify } = require('node:util');
+const { randomBytes, timingSafeEqual, argon2: _argon2 } = require('node:crypto');
 
 const argon2 = promisify(_argon2);
 const defined_past = process.hrtime.bigint();
 
 
-export const Utils = Object.freeze({
+const Utils = Object.freeze({
     /**
      * Captures a high-resolution snapshot of the Node.js metabolic state.
      * Uses concatenation to prevent entropy collisions.
      */
-    async snapshot(h, mh, mem, s, useUrandom) {
+    async snapshot(h, mh, mem, t, p, s, useUrandom) {
         // Level 1: Minimal data
         if (h <= 1) return this.bigIntToBuffer(process.hrtime.bigint());
 
         const u = process.resourceUsage();
         const m = process.memoryUsage();
 
-        // Primary metabolic collection (Machine State)
-        // We use an array to preserve individual entropy of each metric
+        // Level 2: Primary metabolic collection (Machine State)
         const metrics = [
             process.hrtime.bigint(),                            // CPU Nanoseconds
             BigInt(Math.round(process.uptime() * 1_000_000)),
@@ -71,25 +70,33 @@ export const Utils = Object.freeze({
         if (h <= 2 || s >= mh) return b;
 
         // Level 3: Argon2id Memory-Hardening
-        const nonce = await this.getRandom(16, useUrandom);
+        let nonce, memHard;
 
         try {
-            const memHard = await argon2('argon2id', {
+            nonce   = await this.getRandom(16, useUrandom);
+            memHard = await argon2('argon2id', {
                 nonce,
                 message: b,
                 memory: mem,
-                passes: 3,
-                parallelism: 4,
+                passes: t,
+                parallelism: p,
                 tagLength: 64
             });
 
-            return (h <= 3)
-                ? Buffer.concat([b, memHard])
-                : memHard;
+            const result = Buffer.concat([memHard, b]);
+            if (h <= 3) return result;
+
+            throw new Error(`Hardening level [${h}] is unknown. Use 0 (Basic) through 3 (Heavy).`);
         }
 
-        catch (e) { throw e }
-        finally   { nonce.fill(0); }
+        catch (e) { throw e; }
+
+        finally   {
+            // wipe result
+            if (memHard) memHard.fill(0);
+            if (nonce)   nonce.fill(0);
+            b.fill(0);
+        }
     },
 
     /**
@@ -166,4 +173,5 @@ export const Utils = Object.freeze({
     }
 });
 
-export default Utils;
+module.exports = Utils;
+module.exports.Utils = Utils;

package/src/util.mjs

@@ -0,0 +1,176 @@
+/**
+ * THS (Temporal-Hardening Solution)
+ *
+ * Copyright 2026 Aries Harbinger
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { randomBytes, timingSafeEqual, argon2 as _argon2 } from 'node:crypto';
+
+const argon2 = promisify(_argon2);
+const defined_past = process.hrtime.bigint();
+
+
+export const Utils = Object.freeze({
+    /**
+     * Captures a high-resolution snapshot of the Node.js metabolic state.
+     * Uses concatenation to prevent entropy collisions.
+     */
+    async snapshot(h, mh, mem, t, p, s, useUrandom) {
+        // Level 1: Minimal data
+        if (h <= 1) return this.bigIntToBuffer(process.hrtime.bigint());
+
+        const u = process.resourceUsage();
+        const m = process.memoryUsage();
+
+        // Level 2: Primary metabolic collection (Machine State)
+        const metrics = [
+            process.hrtime.bigint(),                            // CPU Nanoseconds
+            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
+            BigInt(u.majorPageFault),                           // Hard I/O faults
+            BigInt(u.voluntaryContextSwitches),
+            BigInt(u.involuntaryContextSwitches),
+            BigInt(m.heapUsed),                                 // V8 actual usage
+            BigInt(m.heapTotal),                                // V8 allocated total
+            BigInt(m.external),                                 // C++ object memory
+            BigInt(m.arrayBuffers || 0),                        // Raw buffer memory
+            BigInt(m.rss),                                      // Resident Set Size (Physical RAM)
+            BigInt(Math.round(performance.now() * 1_000_000)),
+            defined_past,                                       // Process start anchor
+            BigInt(Date.now()),                                 // Wall clock (Temporal anchor)
+            BigInt(s || 0)                                      // Sequential salt
+        ].map(n => this.bigIntToBuffer(n));
+
+        // Map metrics to uniquely structured buffers
+        const b = Buffer.concat([
+
+            // Inject 128 bytes of raw, uninitialized system memory 
+            // (May contain fragments of previous internal function calls/pointers)
+            Buffer.allocUnsafe(128),
+
+            ...metrics
+        ]);
+
+        if (h <= 2 || s >= mh) return b;
+
+        // Level 3: Argon2id Memory-Hardening
+        let nonce, memHard;
+
+        try {
+            nonce   = await this.getRandom(16, useUrandom);
+            memHard = await argon2('argon2id', {
+                nonce,
+                message: b,
+                memory: mem,
+                passes: t,
+                parallelism: p,
+                tagLength: 64
+            });
+
+            const result = Buffer.concat([memHard, b]);
+            if (h <= 3) return result;
+
+            throw new Error(`Hardening level [${h}] is unknown. Use 0 (Basic) through 3 (Heavy).`);
+        }
+
+        catch (e) { throw e; }
+
+        finally   {
+            // wipe result
+            if (memHard) memHard.fill(0);
+            if (nonce)   nonce.fill(0);
+            b.fill(0);
+        }
+    },
+
+    /**
+     * Attempts to harvest raw entropy from the OS device.
+     * Fallback to hardware-backed Node.js randomBytes on failure.
+     */
+    async getRandom(len, useUrandom) {
+        if (!useUrandom) return randomBytes(len);
+
+        let fd;
+        try {
+            fd = await fs.open('/dev/urandom', 'r');
+            const buffer = Buffer.allocUnsafe(len);
+            const { bytesRead } = await fd.read(buffer, 0, len, 0);
+
+            // If we didn't read enough bytes for some reason, fallback
+            return (bytesRead < len)
+                ? randomBytes(len)
+                : buffer;
+        }
+
+        catch (e) { return randomBytes(len);  }
+        finally   { if (fd) await fd.close(); }
+    },
+
+    /**
+     * Micro-architectural noise generator.
+     */
+    async jitter(useUrandom) {
+        const b = await this.getRandom(64, useUrandom);
+        timingSafeEqual(b, b);
+        b.fill(0); 
+    },
+
+    /**
+     * Optimized BigInt to Buffer conversion with 16-bit Length Header.
+     * Prepends a 2-byte length header (Big-Endian) followed by the data.
+     */
+    bigIntToBuffer(n) {
+        if (typeof n !== 'bigint') n = BigInt(n);
+        if (n < 0n) throw new RangeError('Negative values not supported');
+
+        // Fast path for zero: [Length: 0x0001] [Value: 0x00]
+        if (n === 0n) {
+            const buf = Buffer.allocUnsafe(3);
+            buf.writeUInt16BE(1, 0); // Length is 1 byte
+            buf[2] = 0;              // Value is 0
+            return buf;
+        }
+
+        // Convert BigInt to Buffer via Hex
+        let hex = n.toString(16);
+        if (hex.length % 2 !== 0) hex = '0' + hex;
+        const data = Buffer.from(hex, 'hex');
+
+        // Safety check for 16-bit overflow
+        if (data.length > 0xFFFF)
+            throw new RangeError('BigInt exceeds 16-bit length header capacity');
+
+        // Structure: [Header (2 bytes)] + [Data]
+        const header = Buffer.allocUnsafe(2);
+        header.writeUInt16BE(data.length, 0);
+
+        return Buffer.concat([header, data]);
+    },
+
+    /**
+     * Normalizes various input types into a Uint8Array.
+     */
+    toBytes(input) {
+        if (input instanceof Uint8Array) return input;
+        if (typeof input === 'string') return new TextEncoder().encode(input);
+        return new TextEncoder().encode(JSON.stringify(input) || '');
+    }
+});
+
+export default Utils;