ths-csprng 1.0.0 → 1.0.2

package/README.md

@@ -1,90 +1,132 @@
-<div align="center">
-<img src="./media/banner.png" alt="Banner" width="1250">
-</div>
+# THS (Temporal-Hardening Solution)
+
+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 />
+
+---
 
 <br />
 
-Standard RNGs are built on the naive assumption that once a seed is "randomized," the history of its creation just... disappears.
+### 🚀 Quick Start
 
-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.
+```bash
+npm install ths-csprng
+```
 
 <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.
+#### ESM (Node.js 18+, Vite, Bun)
 
-**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.
+```javascript
+import THS from 'ths-csprng';
 
-To put it simply, it is a “Macroscopic Chaos as a defense against Microscopic Observation.”
+// Standard 256-bit secure random buffer
+const entropy = await THS.random(32);
 
-<br />
+// 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
+});
+```
 
----
+#### CommonJS
 
-<br />
+```javascript
+const THS = require('ths-csprng');
 
-<div align="center">
-<img src="./media/illustration.png" alt="Illustration" width="1250">
-</div>
+(async () => {
+    const entropy = await THS.random(32);
+    console.log(entropy.toString('hex'));
+})();
+```
 
 <br />
 
-## 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.
+### 💎 Hardening Levels
 
-THS creates **Computational Fog**. Instead of a mathematical point, it binds your secret to the "metabolic noise" of your CPU at a specific nanosecond.
+| 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 />
 
-### How it actually works:
+---
+
+### ⚙️ Full Configuration
 
-* **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.
+```javascript
+const bytes = await THS.random(32, {
+  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
+  
+  // Argon2id Specifics (Required for level 3)
+  mem: 16384,              // Memory cost in KB
+  passes: 3,               // Iterations
+  parallelism: 4           // Threads
+});
+```
 
 <br />
 
 ---
 
-<br />
+### 🧬 Advanced API
 
-## Getting Started
+#### Direct Utils
 
-```bash
-npm install ths-csprng
+```javascript
+// ESM
+import Utils from 'ths-csprng/utils';
+// CJS
+const Utils = require('ths-csprng/utils');
+
+// 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);
 ```
 
-<br />
 
-### Quick Start
+#### Browser Support
 
 ```javascript
-import THS from 'ths-csprng';
+const buf = new Uint8Array(32);
+THS.fillRandom(buf); 
+```
 
-(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)
-  });
-})();
+
+#### 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**.
+---
 
-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.
+### 🛡️ 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.
 
-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.
+**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,11 +1,23 @@
 {
   "name": "ths-csprng",
-  "version": "1.0.0",
+  "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"
+    ".": {
+      "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 } 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 = {
+const THS = Object.freeze({
     /**
      * Generates cryptographically secure random bytes with temporal hardening.
      */
@@ -33,10 +33,12 @@ export const THS = {
         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,69 +58,59 @@ export const THS = {
         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);
+            const out = k.digest();
+            if (!buffer) return out;
 
-            // Finalize with KMAC256
-            const result = kmac256(seed, Buffer.concat(moments), { 
-                personalization: Utils.toBytes(label),
-                dkLen: length
-            });
-
-            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;
         }
     },
 
-    async rand(len, o) { return await THS.random(len, o) },
-    async rnd (len, o) { return await THS.random(len, o) },
-
-    // direct use raw random (fallback to randomBytes)
-    async raw(len)     { return await Utils.getRandom(len, true) }
-};
-
-// Must use await
-export const randomBytes = async (len, o) => {
-    return await THS.random(len, o);
-};
-
-export default THS;
+    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)
+    }
+});
+
+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,31 +16,30 @@
  * 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 = {
+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)), 
+            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 +54,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
@@ -71,25 +70,33 @@ export const Utils = {
         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);
+        }
     },
 
     /**
@@ -164,6 +171,7 @@ export const Utils = {
         if (typeof input === 'string') return new TextEncoder().encode(input);
         return new TextEncoder().encode(JSON.stringify(input) || '');
     }
-};
+});
 
-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;