ths-csprng 1.0.2 → 1.1.1

package/README.md

@@ -1,14 +1,60 @@
-# THS (Temporal-Hardening Solution)
+<div align="center">
+<img src="https://raw.githubusercontent.com/harnuma9/temporal-hardening-solution-csprng/refs/heads/main/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 />
+
+# ths-csprng
+
+[![npm version](https://img.shields.io/npm/v/ths-csprng.svg)](https://www.npmjs.com/package/ths-csprng)
+![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-green)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/harnuma9/temporal-hardening-solution-csprng/blob/main/LICENSE)
+![Verify Status](https://github.com/harnuma9/temporal-hardening-solution-csprng/actions/workflows/verify.yml/badge.svg)
+[![Socket Badge](https://badge.socket.dev/npm/package/ths-csprng/1.1.1)](https://badge.socket.dev/npm/package/ths-csprng/1.1.1)
+[![Donate](https://img.shields.io/badge/@Harnuma9-Donate-FF4D4D)](https://harnuma9.github.io/donate/)
+
+<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 />
+
+---
+
+<br />
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/harnuma9/temporal-hardening-solution-csprng/refs/heads/main/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 />
+
+> **Full API context optimized for AI assistants and contributors** is available in [`llms-full.txt`](https://github.com/harnuma9/temporal-hardening-solution-csprng/blob/main/llms-full.txt).
 
+<br />
 <br />
 
 ---
 
 <br />
 
-### 🚀 Quick Start
+### 🚀 Getting Started
 
 ```bash
 npm install ths-csprng
@@ -16,7 +62,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,18 +72,19 @@ 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');
+const { THS } = require('ths-csprng');
 
 (async () => {
     const entropy = await THS.random(32);
@@ -47,7 +96,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 +111,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
-  
-  // Argon2id Specifics (Required for level 3)
-  mem: 16384,              // Memory cost in KB
-  passes: 3,               // Iterations
-  parallelism: 4           // Threads
-});
+  trng: false,             // Force /dev/urandom usage (w/ fallback)
+  buffer: true,            // Return Node.js Buffer (false for Uint8Array)
+
+  // 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 />
@@ -82,13 +138,15 @@ const bytes = await THS.random(32, {
 
 ### 🧬 Advanced API
 
+<br />
+
 #### Direct Utils
 
 ```javascript
 // ESM
 import Utils from 'ths-csprng/utils';
-// CJS
-const Utils = require('ths-csprng/utils');
+// or CJS
+const { Utils } = require('ths-csprng/utils');
 
 // Get a raw metabolic snapshot (*T=n*)
 const snap = await Utils.snapshot(2); 
@@ -101,41 +159,153 @@ const raw = await THS.raw(32);
 #### Browser Support
 
 ```javascript
-const buf = new Uint8Array(32);
-THS.fillRandom(buf); 
+// Uses window.crypto or node:crypto depending on environment
+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
 
 ```javascript
-import { randomBytes } from 'ths-csprng';
+import { randomBytes, THS } from 'ths-csprng';
+
+// Sync: Standard CSPRNG fill
+const uintBytes = randomBytes(32); // Uint8Array
+const bufferBytes = Buffer.from(randomBytes(32)); // Buffer
 
-await randomBytes(32);
+// Async: Uses THS.random() temporal hardening
+const secureBytes = await randomBytes(
+    32,
+    true,   // isHardenRNG flag
+    { layers: 64, harden: 2 }
+);
+
+// Method Aliases
 await THS.rand(32);
 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="https://raw.githubusercontent.com/harnuma9/temporal-hardening-solution-csprng/refs/heads/main/media/illustration_2.png" alt="Illustration 2" width="1250">
+</div>
+
+<br />
+
+## 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.
+
+<br />
+
+## Threat Model
+
+Threat models range from the **hypothetical** ([retrocausality](https://www.nwo.nl/en/projects/hexwa91373) is possible in real-life + proofs) to the **theoretically niche** (such as the “[cold start](https://www.ijcrt.org/papers/IJCRT2602064.pdf)” 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](https://en.wikipedia.org/wiki/Dual_EC_DRBG)**.
+
+<br />
+
+### ✅ Scope of Protection
+
+The **THS-CSPRNG wrapper** is specifically engineered to mitigate scenarios where an adversary attempts to:
+
+1. **State Reconstruction**: Reconstruct the historical state of your machine at the precise moment a key was generated. (a core concern in [Cryptanalysis](https://en.wikipedia.org/wiki/Cryptanalysis)).
+2. **VM Replication**: Exploit **VM snapshots** or “cloning” events that cause multiple instances to produce identical, non-unique “random” output.
+3. **Entropy Subversion**: Bypass or predict hardware entropy sources via [manufacturer backdoors](https://en.wikipedia.org/wiki/Hardware_backdoor) or side-channel influence.
+
+<br />
+
+### ❌ Limitations (What it can’t protect)
+
+Although it is a CSPRNG wrapper, engineered to protect generated secrets from theoretical to real-world risks, it does not protect you from:
+
+1. **Actual time travelers**: They can travel from any time physically; that is cheating. A threat model specifically mitigates against any “observations” from 3D observers in the future using speculative “sci-fi” technologies.
+2. **Malware, Spyware, Exploits, etc.**: If your device is compromised at the OS level or pre-loaded with spyware, an adversary doesn't need to predict your entropy—they can simply **[intercept the final generated secrets](https://en.wikipedia.org/wiki/Form_grabbing)** from memory.
+3. **Physical Extraction**: If an adversary has physical access to your hardware and a soldering iron (or a very cold can of compressed air for a “[Cold Boot](https://en.wikipedia.org/wiki/Cold_boot_attack)” attack), they are bypassing the RNG logic entirely to target the stored result *(while TEEs and memory encryption help, physical access might be a game-over scenario)*.
+4. **Human errors**: High-quality entropy cannot save you from logic errors. Hardened seeds are useless if you accidentally log them to a public console, hardcode them into an automated script, or fall victim to a social engineering / **[MITM attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack)**.
+
+<br />
+
+> [!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**.
+
+<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.
+<br />
 
-**Note:** Hardening Level 3 is computationally expensive. Use Level 0 or 1 for high-frequency needs like UUIDs or nonces.
+## 🛠 ️Development & Verification
+
+```bash
+npm run check        # test + verify checksums
+npm run build        # minify + generate docs + checksums
+npm test
+```
+
+<br />
+
+The project uses:
+
+* `terser` for minification
+* SHA-256 checksums for all built files
+* Strict mode + comprehensive test suite
+
+<br />
+
+---
+
+<br />
+
+## ⭐ Contributor(s)
+
+<a href="https://github.com/harnuma9/temporal-hardening-solution-csprng/graphs/contributors">
+  <img alt="contributors" src="https://contrib.rocks/image?repo=harnuma9/temporal-hardening-solution-csprng"/>
+</a>
 
+<br />
+<br />
 <br />
 
 ## 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](./LICENSE)** file for full details.
+Copyright © 2026 Aries Harbinger. See the **[LICENSE](https://github.com/harnuma9/temporal-hardening-solution-csprng/blob/main/LICENSE)** file for full details.
 
+<br />
+<br />
+
+## 🔗 Links
+
+* [Github Repository](https://github.com/harnuma9/temporal-hardening-solution-csprng)
+* [npm Package](https://www.npmjs.com/package/ths-csprng)
+* Full AI Context **[llms-full.txt](https://github.com/harnuma9/temporal-hardening-solution-csprng/blob/main/llms-full.txt)** (for contributors / LLM assistants)
+
+<br />
 <br />
 <br />
 <br />

package/dist/index.min.js

@@ -0,0 +1,2 @@
+import Utils from"ths-csprng/utils";import{kmac256}from"@noble/hashes/sha3-addons.js";import{createHash,webcrypto}from"node:crypto";const THS=Object.freeze({async random(e=32,{layers:r=128,harden:t=2,trng:a=!1,buffer:o=!0,memoryH:n=1,mem:i=16384,passes:s=3,parallelism:l=4,label:c="THS-Default-v1"}={}){if(e<=0)return Buffer.alloc(0);if(r<2||r>65536)throw new Error(`Layer count [${r}] is invalid. Requires a temporal span of 2-65536 cycles to ensure metabolic variance.`);if(t<0||t>3)throw new Error(`Hardening level [${t}] is unknown. Use 0 (Basic) through 3 (Heavy).`);if(t>=3&&(n<1||n>r))throw new Error(`Memory hardening cycle count [${n}] exceeds available temporal layers [${r}].`);if("number"!=typeof i||i<1024)throw new Error(`Memory set [${i}] for Argon2id must be a valid number and not be less than 1024 or 1KB.`);const d=await Utils.getRandom(32,a);let m;try{m=kmac256.create(d,{personalization:Utils.toBytes(c),dkLen:e});for(let e=0;e<r;e++){const o=await Utils.snapshot(t,n,i,s,l,e,a);if(m.update(o),o.fill(0),t>=1){const e=await Utils.getRandom(12,a);m.update(e),e.fill(0)}e<r-1&&await Utils.jitter(a)}const f=m.digest();if(!o)return f;const w=Buffer.from(f);return f?.fill?.(0),w}catch(e){throw e}finally{d?.fill?.(0),m=null}},rand:async(e,r)=>await THS.random(e,r),rnd:async(e,r)=>await THS.random(e,r),raw:async e=>await Utils.getRandom(e,!0),fillRandom:e=>("undefined"!=typeof window&&window.crypto?window.crypto:webcrypto).getRandomValues(e)}),randomBytes=(e,r=!1,t)=>r?new Promise((r,a)=>THS.random(e,t).then(e=>r(e)).catch(e=>a(e))):THS.fillRandom(new Uint8Array(e));export{THS,randomBytes};export default THS;
+//# sourceMappingURL=index.min.js.map

package/dist/index.min.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dist/index.min.js.map","names":["Utils","kmac256","createHash","webcrypto","THS","Object","freeze","random","length","layers","harden","trng","buffer","memoryH","mem","passes","parallelism","label","Buffer","alloc","Error","seed","getRandom","k","create","personalization","toBytes","dkLen","i","moment","snapshot","update","fill","sup","jitter","out","digest","b","from","e","async","len","o","fillRandom","arr","window","crypto","getRandomValues","randomBytes","isHardenRNG","Promise","resolve","reject","then","catch","err","Uint8Array"],"sources":["src/index.js"],"mappings":"OAgBOA,UAAW,0BACTC,YAAe,sCACfC,WAAYC,cAAiB,cAsBtC,MAAMC,IAAMC,OAAOC,OAAO,CAYtB,YAAMC,CAAOC,EAAS,IAAIC,OAEtBA,EAAS,IAAGC,OACZA,EAAS,EAACC,KACVA,GAAO,EAAKC,OACZA,GAAS,EAAIC,QAEbA,EAAU,EAACC,IACXA,EAAM,MAAKC,OACXA,EAAS,EAACC,YACVA,EAAc,EAACC,MAEfA,EAAQ,kBAER,CAAC,GAED,GAAIT,GAAU,EACV,OAAOU,OAAOC,MAAM,GAExB,GAAIV,EAAS,GAAKA,EAAS,MACvB,MAAM,IAAIW,MAAM,gBAAgBX,2FAEpC,GAAIC,EAAS,GAAKA,EAAS,EACvB,MAAM,IAAIU,MAAM,oBAAoBV,mDAExC,GAAIA,GAAU,IAAMG,EAAU,GAAKA,EAAUJ,GACzC,MAAM,IAAIW,MAAM,iCAAiCP,yCAA+CJ,OAEpG,GAAI,iBAAoBK,GAAOA,EAAM,KACjC,MAAM,IAAIM,MAAM,eAAeN,4EAEnC,MAAMO,QAAarB,MAAMsB,UAAU,GAAIX,GACvC,IAAIY,EAEJ,IACIA,EAAItB,QAAQuB,OAAOH,EAAM,CACrBI,gBAAiBzB,MAAM0B,QAAQT,GAC/BU,MAAOnB,IAGX,IAAK,IAAIoB,EAAI,EAAGA,EAAInB,EAAQmB,IAAK,CAC7B,MAAMC,QAAe7B,MAAM8B,SAASpB,EAAQG,EAASC,EAAKC,EAAQC,EAAaY,EAAGjB,GAGlF,GAFAY,EAAEQ,OAAOF,GAASA,EAAOG,KAAK,GAE1BtB,GAAU,EAAG,CAEb,MAAMuB,QAAYjC,MAAMsB,UAAU,GAAIX,GACtCY,EAAEQ,OAAOE,GAAMA,EAAID,KAAK,EAC5B,CAEIJ,EAAInB,EAAS,SAAST,MAAMkC,OAAOvB,EAC3C,CAEA,MAAMwB,EAAMZ,EAAEa,SACd,IAAKxB,EAAQ,OAAOuB,EAEpB,MAAME,EAAInB,OAAOoB,KAAKH,GAEtB,OADAA,GAAKH,OAAO,GACLK,CACX,CAEA,MAAOE,GAAK,MAAMA,CAAG,CAErB,QACIlB,GAAMW,OAAO,GACbT,EAAI,IACR,CACJ,EAQAiB,KAAU,MAACC,EAAKC,UAAkBtC,IAAIG,OAAOkC,EAAKC,GAQlDF,IAAS,MAACC,EAAKC,UAAkBtC,IAAIG,OAAOkC,EAAKC,GAUjDF,IAAS,MAACC,SAAqBzC,MAAMsB,UAAUmB,GAAK,GASpDE,WAAWC,IAEgB,oBAAXC,QAA0BA,OAAOC,OACnCD,OAAOC,OACP3C,WACR4C,gBAAgBH,KAYpBI,YAAc,CAACP,EAAKQ,GAAc,EAAOP,IAEtCO,EAIE,IAAIC,QAAQ,CAACC,EAASC,IACzBhD,IAAIG,OAAOkC,EAAKC,GACXW,KAAKlB,GAAOgB,EAAQhB,IACpBmB,MAAMC,GAAOH,EAAOG,KANlBnD,IAAIuC,WAAW,IAAIa,WAAWf,WASpCrC,IAAK4C,4BACC5C","ignoreList":[]}

package/dist/util.min.js

@@ -0,0 +1,2 @@
+import fs from"node:fs/promises";import{promisify}from"node:util";import{randomBytes,timingSafeEqual,createHash,argon2 as _argon2}from"node:crypto";const argon2=promisify(_argon2),defined_past=process.hrtime.bigint();export const Utils=Object.freeze({async snapshot(e,t,n,r,i,a,o){if(e<=1)return this.bigIntToBuffer(process.hrtime.bigint());const s=process.resourceUsage(),f=process.memoryUsage(),g=[process.hrtime.bigint(),BigInt(Math.round(1e6*process.uptime())),BigInt(s.userCPUTime),BigInt(s.systemCPUTime),BigInt(s.minorPageFault),BigInt(s.majorPageFault),BigInt(s.voluntaryContextSwitches),BigInt(s.involuntaryContextSwitches),BigInt(f.heapUsed),BigInt(f.heapTotal),BigInt(f.external),BigInt(f.arrayBuffers||0),BigInt(f.rss),BigInt(Math.round(1e6*performance.now())),defined_past,BigInt(Date.now()),BigInt(a||0)].map(e=>this.bigIntToBuffer(e)),c=Buffer.allocUnsafe(128),l=createHash("sha3-512").update(c).update(process.hrtime.bigint().toString()).digest();c.fill(0);const u=Buffer.concat([l,...g]);if(l.fill(0),e<=2||a>=t)return u;let m,B;try{m=await this.getRandom(16,o),B=await argon2("argon2id",{nonce:m,message:u,memory:n,passes:r,parallelism:i,tagLength:64});const t=Buffer.concat([B,u]);if(e<=3)return t;throw new Error(`Hardening level [${e}] is unknown. Use 0 (Basic) through 3 (Heavy).`)}catch(e){throw e}finally{B?.fill?.(0),m?.fill?.(0),u?.fill?.(0)}},async getRandom(e,t){if(!t)return randomBytes(e);let n;try{n=await fs.open("/dev/urandom","r");const t=Buffer.allocUnsafe(e),{bytesRead:r}=await n.read(t,0,e,0);return r<e?randomBytes(e):t}catch(t){return randomBytes(e)}finally{n&&await n.close()}},async jitter(e){const t=await this.getRandom(64,e);timingSafeEqual(t,t),t.fill(0)},bigIntToBuffer(e){if("bigint"!=typeof e&&(e=BigInt(e)),e<0n)throw new RangeError("Negative values not supported");if(0n===e){const e=Buffer.allocUnsafe(3);return e.writeUInt16BE(1,0),e[2]=0,e}let t=e.toString(16);t.length%2!=0&&(t="0"+t);const n=Buffer.from(t,"hex");if(n.length>65535)throw new RangeError("BigInt exceeds 16-bit length header capacity");const r=Buffer.allocUnsafe(2);return r.writeUInt16BE(n.length,0),Buffer.concat([r,n])},toBytes:e=>e instanceof Uint8Array?e:"string"==typeof e?(new TextEncoder).encode(e):(new TextEncoder).encode(JSON.stringify(e)||"")});export default Utils;
+//# sourceMappingURL=util.min.js.map

package/dist/util.min.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dist/util.min.js.map","names":["fs","promisify","randomBytes","timingSafeEqual","createHash","_argon2","argon2","defined_past","process","hrtime","bigint","Utils","Object","freeze","snapshot","h","mh","mem","t","p","s","useUrandom","this","bigIntToBuffer","u","resourceUsage","m","memoryUsage","metrics","BigInt","Math","round","uptime","userCPUTime","systemCPUTime","minorPageFault","majorPageFault","voluntaryContextSwitches","involuntaryContextSwitches","heapUsed","heapTotal","external","arrayBuffers","rss","performance","now","Date","map","n","noise","Buffer","allocUnsafe","hashedNoise","update","toString","digest","fill","b","concat","nonce","memHard","getRandom","message","memory","passes","parallelism","tagLength","result","Error","e","len","fd","open","buffer","bytesRead","read","close","jitter","RangeError","buf","writeUInt16BE","hex","length","data","from","header","toBytes","input","Uint8Array","TextEncoder","encode","JSON","stringify"],"sources":["src/util.js"],"mappings":"OAgBOA,OAAQ,0BACNC,cAAiB,mBACjBC,YAAaC,gBAAiBC,qBAAsBC,YAAe,cAE5E,MAAMC,OAASL,UAAUI,SACnBE,aAAeC,QAAQC,OAAOC,gBAQ7B,MAAMC,MAAQC,OAAOC,OAAO,CAiB/B,cAAMC,CAASC,EAAGC,EAAIC,EAAKC,EAAGC,EAAGC,EAAGC,GAEhC,GAAIN,GAAK,EAAG,OAAOO,KAAKC,eAAef,QAAQC,OAAOC,UAEtD,MAAMc,EAAIhB,QAAQiB,gBACZC,EAAIlB,QAAQmB,cAGZC,EAAU,CACZpB,QAAQC,OAAOC,SACfmB,OAAOC,KAAKC,MAAyB,IAAnBvB,QAAQwB,WAC1BH,OAAOL,EAAES,aACTJ,OAAOL,EAAEU,eACTL,OAAOL,EAAEW,gBACTN,OAAOL,EAAEY,gBACTP,OAAOL,EAAEa,0BACTR,OAAOL,EAAEc,4BACTT,OAAOH,EAAEa,UACTV,OAAOH,EAAEc,WACTX,OAAOH,EAAEe,UACTZ,OAAOH,EAAEgB,cAAgB,GACzBb,OAAOH,EAAEiB,KACTd,OAAOC,KAAKC,MAA0B,IAApBa,YAAYC,QAC9BtC,aACAsB,OAAOiB,KAAKD,OACZhB,OAAOT,GAAK,IACd2B,IAAIC,GAAK1B,KAAKC,eAAeyB,IAIzBC,EAAQC,OAAOC,YAAY,KAG3BC,EAAchD,WAAW,YAC1BiD,OAAOJ,GACPI,OAAO7C,QAAQC,OAAOC,SAAS4C,YAC/BC,SAGLN,EAAMO,KAAK,GAGX,MAAMC,EAAIP,OAAOQ,OAAO,CACpBN,KACGxB,IAIP,GAFAwB,EAAYI,KAAK,GAEbzC,GAAK,GAAKK,GAAKJ,EAAI,OAAOyC,EAG9B,IAAIE,EAAOC,EAEX,IACID,QAAgBrC,KAAKuC,UAAU,GAAIxC,GACnCuC,QAAgBtD,OAAO,WAAY,CAC/BqD,QACAG,QAASL,EACTM,OAAQ9C,EACR+C,OAAQ9C,EACR+C,YAAa9C,EACb+C,UAAW,KAGf,MAAMC,EAASjB,OAAOQ,OAAO,CAACE,EAASH,IACvC,GAAI1C,GAAK,EAAG,OAAOoD,EAEnB,MAAM,IAAIC,MAAM,oBAAoBrD,kDACxC,CAEA,MAAOsD,GAAK,MAAMA,CAAG,CAErB,QAEIT,GAASJ,OAAO,GAChBG,GAAOH,OAAO,GACdC,GAAGD,OAAO,EACd,CACJ,EAaA,eAAMK,CAAUS,EAAKjD,GACjB,IAAKA,EAAY,OAAOnB,YAAYoE,GAEpC,IAAIC,EACJ,IACIA,QAAWvE,GAAGwE,KAAK,eAAgB,KACnC,MAAMC,EAASvB,OAAOC,YAAYmB,IAC5BI,UAAEA,SAAoBH,EAAGI,KAAKF,EAAQ,EAAGH,EAAK,GAGpD,OAAQI,EAAYJ,EACdpE,YAAYoE,GACZG,CACV,CAEA,MAAOJ,GAAK,OAAOnE,YAAYoE,EAAO,CACtC,QAAgBC,SAAUA,EAAGK,OAAS,CAC1C,EAWA,YAAMC,CAAOxD,GACT,MAAMoC,QAAUnC,KAAKuC,UAAU,GAAIxC,GACnClB,gBAAgBsD,EAAGA,GACnBA,EAAED,KAAK,EACX,EAWA,cAAAjC,CAAeyB,GAEX,GADiB,iBAANA,IAAgBA,EAAInB,OAAOmB,IAClCA,EAAI,GAAI,MAAM,IAAI8B,WAAW,iCAGjC,GAAU,KAAN9B,EAAU,CACV,MAAM+B,EAAM7B,OAAOC,YAAY,GAG/B,OAFA4B,EAAIC,cAAc,EAAG,GACrBD,EAAI,GAAK,EACFA,CACX,CAGA,IAAIE,EAAMjC,EAAEM,SAAS,IACjB2B,EAAIC,OAAS,GAAM,IAAGD,EAAM,IAAMA,GACtC,MAAME,EAAOjC,OAAOkC,KAAKH,EAAK,OAG9B,GAAIE,EAAKD,OAAS,MACd,MAAM,IAAIJ,WAAW,gDAGzB,MAAMO,EAASnC,OAAOC,YAAY,GAGlC,OAFAkC,EAAOL,cAAcG,EAAKD,OAAQ,GAE3BhC,OAAOQ,OAAO,CAAC2B,EAAQF,GAClC,EAUAG,QAAQC,GACAA,aAAiBC,WAAmBD,EACnB,iBAAVA,GAA2B,IAAIE,aAAcC,OAAOH,IACxD,IAAIE,aAAcC,OAAOC,KAAKC,UAAUL,IAAU,qBAIlD5E","ignoreList":[]}

package/package.json

@@ -1,36 +1,46 @@
 {
   "name": "ths-csprng",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Temporal-Hardening Solution: A CSPRNG wrapper designed to resist historical state reconstruction and hardware backdoors.",
-  "main": "./src/index.js",
-  "files": [
-    "src",
-    "LICENSE",
-    "README.md",
-    "npm-shrinkwrap.json"
-  ],
-  "exports": {
-    ".": {
-      "import": "./src/index.mjs",
-      "require": "./src/index.js"
-    },
-    "./utils": {
-      "import": "./src/util.mjs",
-      "require": "./src/util.js"
-    }
-  },
   "author": "Aries Harbinger",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/harnuma9/temporal-hardening-solution-csprng",
+  "homepage": "https://github.com/harnuma9/temporal-hardening-solution-csprng#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/harnuma9/temporal-hardening-solution-csprng.git"
   },
+  "funding": [
+    {
+      "type": "individual",
+      "url": "https://harnuma9.github.io/donate/"
+    }
+  ],
   "bugs": {
     "url": "https://github.com/harnuma9/temporal-hardening-solution-csprng/issues"
   },
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./dist/index.min.js",
+      "require": "./dist/index.min.js"
+    },
+    "./utils": {
+      "types": "./src/util.d.ts",
+      "import": "./dist/util.min.js",
+      "require": "./dist/util.min.js"
+    }
+  },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "bash update.sh",
+    "verify": "bash verify.sh",
+    "test": "node --test ./test/test_suite.js && node --test ./test/benchmark.js",
+    "check": "npm run test && npm run verify",
+    "prepublishOnly": "npm run check"
   },
   "keywords": [
     "csprng",
@@ -47,6 +57,10 @@
   "dependencies": {
     "@noble/hashes": "^2.2.0"
   },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "docdash": "^2.0.2"
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/index.d.ts

@@ -0,0 +1,108 @@
+export default THS;
+/**
+ * Configuration options for temporal hardening.
+ */
+export type THSOptions = {
+    /**
+     * - Number of timeline slices (iterations). Range: 2-65536.
+     */
+    layers?: number | undefined;
+    /**
+     * - Hardening level: 0 (hrtime), 1 (+entropy), 2 (+internal), 3 (+Argon2id).
+     */
+    harden?: number | undefined;
+    /**
+     * - Attempts to read from /dev/urandom; falls back to CSPRNG.
+     */
+    trng?: boolean | undefined;
+    /**
+     * - If true, returns a Node.js Buffer; otherwise, returns a Uint8Array.
+     */
+    buffer?: boolean | undefined;
+    /**
+     * - Number of Argon2id runs (Requires harden level 3).
+     */
+    memoryH?: number | undefined;
+    /**
+     * - Memory hardness for Argon2id in KiB (Default: 16MB).
+     */
+    mem?: number | undefined;
+    /**
+     * - Number of iterations (t) for Argon2id.
+     */
+    passes?: number | undefined;
+    /**
+     * - Degree of parallelism (p) for Argon2id.
+     */
+    parallelism?: number | undefined;
+    /**
+     * - KMAC personalization string.
+     */
+    label?: string | undefined;
+};
+/**
+ * Configuration options for temporal hardening.
+ * @typedef {Object} THSOptions
+ * @property {number} [layers=128] - Number of timeline slices (iterations). Range: 2-65536.
+ * @property {number} [harden=2] - Hardening level: 0 (hrtime), 1 (+entropy), 2 (+internal), 3 (+Argon2id).
+ * @property {boolean} [trng=false] - Attempts to read from /dev/urandom; falls back to CSPRNG.
+ * @property {boolean} [buffer=true] - If true, returns a Node.js Buffer; otherwise, returns a Uint8Array.
+ * @property {number} [memoryH=1] - Number of Argon2id runs (Requires harden level 3).
+ * @property {number} [mem=16384] - Memory hardness for Argon2id in KiB (Default: 16MB).
+ * @property {number} [passes=3] - Number of iterations (t) for Argon2id.
+ * @property {number} [parallelism=4] - Degree of parallelism (p) for Argon2id.
+ * @property {string} [label='THS-Default-v1'] - KMAC personalization string.
+ */
+/**
+ * Temporal-Hardening Solution - Applied in Random Number Generator.
+ * @namespace THS
+ * @readonly
+ */
+export const THS: Readonly<{
+    /**
+     * Generates cryptographically secure random bytes with temporal hardening.
+     * Incorporates time-variance and system entropy over multiple metabolic cycles.
+     * @async
+     * @memberof THS
+     * @param {number} [length=32] - The desired length of the output bytes.
+     * @param {THSOptions} [options={}] - Hardening and hashing configuration.
+     * @returns {Promise<Buffer|Uint8Array>} The hardened random bytes.
+     * @throws {Error} If layers, harden level, or memory parameters are out of bounds.
+     */
+    random(length?: number, { layers, harden, trng, buffer, memoryH, mem, passes, parallelism, label }?: THSOptions): Promise<Buffer | Uint8Array>;
+    /**
+     * Alias for {@link THS.random}
+     * @async
+     * @memberof THS
+     */
+    rand(len: any, o: any): Promise<any>;
+    /**
+     * Alias for {@link THS.random}
+     * @async
+     * @memberof THS
+     */
+    rnd(len: any, o: any): Promise<any>;
+    /**
+     * Direct access to entropy sources (e.g., /dev/urandom) without temporal hardening.
+     * @async
+     * @memberof THS
+     * @param {number} len - Byte length to retrieve.
+     * @returns {Promise<Buffer>}
+     */
+    raw(len: number): Promise<Buffer>;
+    /**
+     * Fills a typed array with random values using the environment's Webcrypto implementation.
+     * @memberof THS
+     * @param {Uint8Array|Int8Array|Uint16Array|Int16Array|Uint32Array|Int32Array} arr - The array to fill.
+     * @returns {Uint8Array|Int8Array|Uint16Array|Int16Array|Uint32Array|Int32Array} The filled array.
+     */
+    fillRandom(arr: Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array): Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array;
+}>;
+/**
+ * Universal wrapper for random byte generation.
+ * @param {number} len - The number of bytes to generate.
+ * @param {boolean} [isHardenRNG=false] - If true, uses the asynchronous THS hardening logic.
+ * @param {THSOptions} [o] - Options passed only if isHardenRNG is true.
+ * @returns {Uint8Array|Promise<Buffer|Uint8Array>} Returns Uint8Array if synchronous, otherwise a Promise.
+ */
+export function randomBytes(len: number, isHardenRNG?: boolean, o?: THSOptions): Uint8Array | Promise<Buffer | Uint8Array>;

package/src/index.js

@@ -1,6 +1,4 @@
 /**
- * THS (Temporal-Hardening Solution)
- *
  * Copyright 2026 Aries Harbinger
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,17 +14,41 @@
  * limitations under the License.
  */
 
-const Utils = require('./util.js');
-const { kmac256 } = require('@noble/hashes/sha3-addons.js');
-const { webcrypto } = require('node:crypto');
+import Utils from 'ths-csprng/utils';
+import { kmac256 } from '@noble/hashes/sha3-addons.js';
+import { createHash, webcrypto } from 'node:crypto';
+
 
+/**
+ * Configuration options for temporal hardening.
+ * @typedef {Object} THSOptions
+ * @property {number} [layers=128] - Number of timeline slices (iterations). Range: 2-65536.
+ * @property {number} [harden=2] - Hardening level: 0 (hrtime), 1 (+entropy), 2 (+internal), 3 (+Argon2id).
+ * @property {boolean} [trng=false] - Attempts to read from /dev/urandom; falls back to CSPRNG.
+ * @property {boolean} [buffer=true] - If true, returns a Node.js Buffer; otherwise, returns a Uint8Array.
+ * @property {number} [memoryH=1] - Number of Argon2id runs (Requires harden level 3).
+ * @property {number} [mem=16384] - Memory hardness for Argon2id in KiB (Default: 16MB).
+ * @property {number} [passes=3] - Number of iterations (t) for Argon2id.
+ * @property {number} [parallelism=4] - Degree of parallelism (p) for Argon2id.
+ * @property {string} [label='THS-Default-v1'] - KMAC personalization string.
+ */
 
 /**
- * Temporal-Hardening Solution - Applied in Random Number Generator
+ * Temporal-Hardening Solution - Applied in Random Number Generator.
+ * @namespace THS
+ * @readonly
  */
 const THS = Object.freeze({
+
     /**
      * Generates cryptographically secure random bytes with temporal hardening.
+     * Incorporates time-variance and system entropy over multiple metabolic cycles.
+     * @async
+     * @memberof THS
+     * @param {number} [length=32] - The desired length of the output bytes.
+     * @param {THSOptions} [options={}] - Hardening and hashing configuration.
+     * @returns {Promise<Buffer|Uint8Array>} The hardened random bytes.
+     * @throws {Error} If layers, harden level, or memory parameters are out of bounds.
      */
     async random(length = 32, {
 
@@ -39,6 +61,7 @@ const THS = Object.freeze({
         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
 
     } = {}) {
@@ -84,24 +107,51 @@ const THS = Object.freeze({
             if (!buffer) return out;
 
             const b = Buffer.from(out);
-            return out.fill(0), b;
+            out?.fill?.(0);
+            return b;
         }
 
         catch (e) { throw e; }
 
         finally   {
-            seed.fill(0);
+            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)
+    /**
+     * Alias for {@link THS.random}
+     * @async
+     * @memberof THS
+     */
+    async rand(len, o) { return await THS.random(len, o) },
+
+
+    /**
+     * Alias for {@link THS.random}
+     * @async
+     * @memberof THS
+     */
+    async rnd(len, o) { return await THS.random(len, o) },
+
+
+    /**
+     * Direct access to entropy sources (e.g., /dev/urandom) without temporal hardening.
+     * @async
+     * @memberof THS
+     * @param {number} len - Byte length to retrieve.
+     * @returns {Promise<Buffer>}
+     */
     async raw(len)  { return await Utils.getRandom(len, true) },
 
-    // Direct Webcrypto access
+
+    /**
+     * Fills a typed array with random values using the environment's Webcrypto implementation.
+     * @memberof THS
+     * @param {Uint8Array|Int8Array|Uint16Array|Int16Array|Uint32Array|Int32Array} arr - The array to fill.
+     * @returns {Uint8Array|Int8Array|Uint16Array|Int16Array|Uint32Array|Int32Array} The filled array.
+     */
     fillRandom(arr) {
         return (
             (typeof window !== 'undefined' && window.crypto)
@@ -111,6 +161,25 @@ const THS = Object.freeze({
     }
 });
 
-module.exports = THS;
-module.exports.THS = THS;
-module.exports.randomBytes = (len, o) => THS.random(len, o);
+
+/**
+ * Universal wrapper for random byte generation.
+ * @param {number} len - The number of bytes to generate.
+ * @param {boolean} [isHardenRNG=false] - If true, uses the asynchronous THS hardening logic.
+ * @param {THSOptions} [o] - Options passed only if isHardenRNG is true.
+ * @returns {Uint8Array|Promise<Buffer|Uint8Array>} Returns Uint8Array if synchronous, otherwise a Promise.
+ */
+const randomBytes = (len, isHardenRNG = false, o) => {
+    // Simple Random (Synchronous)
+    if (!isHardenRNG)
+        return THS.fillRandom(new Uint8Array(len));
+
+    // Hardened Random (Asynchronous)
+    return new Promise((resolve, reject) =>
+        THS.random(len, o)
+            .then(out => resolve(out))
+            .catch(err => reject(err)));
+};
+
+export { THS, randomBytes };
+export default THS;

package/src/util.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @namespace Utils
+ * @description A collection of cryptographic and system-entropy utilities for the THS framework.
+ * @readonly
+ */
+export const Utils: Readonly<{
+    /**
+     * Captures a high-resolution snapshot of the Node.js metabolic state.
+     * Uses concatenation to prevent entropy collisions and optionally applies Argon2id hardening.
+     * @async
+     * @memberof Utils
+     * @param {number} h - Hardening level: 1 (Basic), 2 (Machine State), 3 (Argon2id).
+     * @param {number} mh - Maximum hardening threshold for the sequential salt.
+     * @param {number} mem - Memory cost for Argon2id (in KiB).
+     * @param {number} t - Iterations (time cost) for Argon2id.
+     * @param {number} p - Parallelism factor for Argon2id.
+     * @param {number} s - Sequential salt/counter to prevent state collisions.
+     * @param {boolean} useUrandom - If true, attempts to read from /dev/urandom directly.
+     * @returns {Promise<Buffer>} A buffer containing the metabolic snapshot.
+     * @throws {Error} Throws if an unknown hardening level is provided or if Argon2 fails.
+     */
+    snapshot(h: number, mh: number, mem: number, t: number, p: number, s: number, useUrandom: boolean): Promise<Buffer>;
+    /**
+     * Attempts to harvest raw entropy from the OS device (/dev/urandom).
+     * Fallbacks to hardware-backed Node.js `crypto.randomBytes` on failure or non-linux systems.
+     *
+     * @async
+     * @memberof Utils
+     * @param {number} len - The number of bytes to generate.
+     * @param {boolean} useUrandom - Whether to force usage of /dev/urandom.
+     * @returns {Promise<Buffer>} A buffer containing random bytes.
+     */
+    getRandom(len: number, useUrandom: boolean): Promise<Buffer>;
+    /**
+     * Micro-architectural noise generator.
+     * Performs a timing-safe comparison on random data to create CPU jitter and then wipes the buffer.
+     * @async
+     * @memberof Utils
+     * @param {boolean} useUrandom - Whether to use /dev/urandom for the jitter source.
+     * @returns {Promise<void>}
+     */
+    jitter(useUrandom: boolean): Promise<void>;
+    /**
+     * Optimized BigInt to Buffer conversion with a 16-bit Length Header.
+     * Prepends a 2-byte length header (Big-Endian) followed by the big-endian representation of the number.
+     * @memberof Utils
+     * @param {bigint|number} n - The BigInt or number to convert.
+     * @returns {Buffer} Buffer formatted as `[Length(2 bytes)][Data]`.
+     * @throws {RangeError} If the value is negative or the resulting byte length exceeds 65535.
+     */
+    bigIntToBuffer(n: bigint | number): Buffer;
+    /**
+     * Normalizes various input types (objects, strings, Uint8Arrays) into a Uint8Array.
+     * Useful for preparing data for cryptographic hashing.
+     * @memberof Utils
+     * @param {Uint8Array|string|object} input - The data to normalize.
+     * @returns {Uint8Array} The input represented as bytes.
+     */
+    toBytes(input: Uint8Array | string | object): Uint8Array;
+}>;
+export default Utils;

package/src/util.js

@@ -1,6 +1,4 @@
 /**
- * THS (Temporal-Hardening Solution)
- *
  * Copyright 2026 Aries Harbinger
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -16,18 +14,35 @@
  * limitations under the License.
  */
 
-const fs = require('node:fs/promises');
-const { promisify } = require('node:util');
-const { randomBytes, timingSafeEqual, argon2: _argon2 } = require('node:crypto');
+import fs from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { randomBytes, timingSafeEqual, createHash, argon2 as _argon2 } from 'node:crypto';
 
 const argon2 = promisify(_argon2);
 const defined_past = process.hrtime.bigint();
 
 
-const Utils = Object.freeze({
+/**
+ * @namespace Utils
+ * @description A collection of cryptographic and system-entropy utilities for the THS framework.
+ * @readonly
+ */
+export const Utils = Object.freeze({
+
     /**
      * Captures a high-resolution snapshot of the Node.js metabolic state.
-     * Uses concatenation to prevent entropy collisions.
+     * Uses concatenation to prevent entropy collisions and optionally applies Argon2id hardening.
+     * @async
+     * @memberof Utils
+     * @param {number} h - Hardening level: 1 (Basic), 2 (Machine State), 3 (Argon2id).
+     * @param {number} mh - Maximum hardening threshold for the sequential salt.
+     * @param {number} mem - Memory cost for Argon2id (in KiB).
+     * @param {number} t - Iterations (time cost) for Argon2id.
+     * @param {number} p - Parallelism factor for Argon2id.
+     * @param {number} s - Sequential salt/counter to prevent state collisions.
+     * @param {boolean} useUrandom - If true, attempts to read from /dev/urandom directly.
+     * @returns {Promise<Buffer>} A buffer containing the metabolic snapshot.
+     * @throws {Error} Throws if an unknown hardening level is provided or if Argon2 fails.
      */
     async snapshot(h, mh, mem, t, p, s, useUrandom) {
         // Level 1: Minimal data
@@ -57,15 +72,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;
 
@@ -93,15 +118,22 @@ const Utils = Object.freeze({
 
         finally   {
             // wipe result
-            if (memHard) memHard.fill(0);
-            if (nonce)   nonce.fill(0);
-            b.fill(0);
+            memHard?.fill?.(0);
+            nonce?.fill?.(0);
+            b?.fill?.(0);
         }
     },
 
+
     /**
-     * Attempts to harvest raw entropy from the OS device.
-     * Fallback to hardware-backed Node.js randomBytes on failure.
+     * Attempts to harvest raw entropy from the OS device (/dev/urandom).
+     * Fallbacks to hardware-backed Node.js `crypto.randomBytes` on failure or non-linux systems.
+     * 
+     * @async
+     * @memberof Utils
+     * @param {number} len - The number of bytes to generate.
+     * @param {boolean} useUrandom - Whether to force usage of /dev/urandom.
+     * @returns {Promise<Buffer>} A buffer containing random bytes.
      */
     async getRandom(len, useUrandom) {
         if (!useUrandom) return randomBytes(len);
@@ -122,8 +154,14 @@ const Utils = Object.freeze({
         finally   { if (fd) await fd.close(); }
     },
 
+
     /**
      * Micro-architectural noise generator.
+     * Performs a timing-safe comparison on random data to create CPU jitter and then wipes the buffer.
+     * @async
+     * @memberof Utils
+     * @param {boolean} useUrandom - Whether to use /dev/urandom for the jitter source.
+     * @returns {Promise<void>}
      */
     async jitter(useUrandom) {
         const b = await this.getRandom(64, useUrandom);
@@ -131,9 +169,14 @@ const Utils = Object.freeze({
         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.
+     * Optimized BigInt to Buffer conversion with a 16-bit Length Header.
+     * Prepends a 2-byte length header (Big-Endian) followed by the big-endian representation of the number.
+     * @memberof Utils
+     * @param {bigint|number} n - The BigInt or number to convert.
+     * @returns {Buffer} Buffer formatted as `[Length(2 bytes)][Data]`.
+     * @throws {RangeError} If the value is negative or the resulting byte length exceeds 65535.
      */
     bigIntToBuffer(n) {
         if (typeof n !== 'bigint') n = BigInt(n);
@@ -163,8 +206,13 @@ const Utils = Object.freeze({
         return Buffer.concat([header, data]);
     },
 
+
     /**
-     * Normalizes various input types into a Uint8Array.
+     * Normalizes various input types (objects, strings, Uint8Arrays) into a Uint8Array.
+     * Useful for preparing data for cryptographic hashing.
+     * @memberof Utils
+     * @param {Uint8Array|string|object} input - The data to normalize.
+     * @returns {Uint8Array} The input represented as bytes.
      */
     toBytes(input) {
         if (input instanceof Uint8Array) return input;
@@ -173,5 +221,4 @@ const Utils = Object.freeze({
     }
 });
 
-module.exports = Utils;
-module.exports.Utils = Utils;
+export default Utils;

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/"
-      }
-    }
-  }
-}

package/src/index.mjs

@@ -1,117 +0,0 @@
-/**
- * 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.mjs

@@ -1,176 +0,0 @@
-/**
- * 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;