ths-csprng 1.0.1 → 1.1.0

package/README.md

@@ -19,7 +19,7 @@ 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">
+<img src="./media/illustration_1.png" alt="Illustration 1" width="1250">
 </div>
 
 <br />
@@ -28,9 +28,9 @@ In short: it uses macroscopic messiness as a defense against microscopic observa
 
 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=0). If that moment is reconstructed, your entropy is gone.
+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₁, 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.
+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 />
 
@@ -48,22 +48,31 @@ npm install ths-csprng
 
 ### 🛠️ Quick Start
 
+#### Modern ESM (Node.js 18+, Vite, Bun)
+
 ```javascript
 import THS from 'ths-csprng';
 
+// 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
+});
+```
+
+#### Legacy / Standard CommonJS
+
+```javascript
+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'));
 })();
 ```
 
@@ -90,12 +99,17 @@ You can dial the security up or down depending on how much “weight” you want
 
 ```javascript
 const options = {
-  layers: 128,             // Number of temporal slices (2 to 65536)
+  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)
+  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
 };
 
@@ -111,10 +125,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
@@ -144,9 +160,15 @@ await THS.rnd(32);
 
 ## 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.
+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.
+THS tries to bridge raw hardware chaos with solid cryptographic primitives, forcing 2<sup>n</sup> security to be exactly as 2<sup>n</sup>, not less.
+
+<br />
+
+<div align="center">
+<img src="./media/illustration_2.png" alt="Illustration 2" width="1250">
+</div>
 
 <br />
 
@@ -169,6 +191,12 @@ THS is aimed at situations where the attacker might try to:
 
 <br />
 
+## ⚠️ Performance 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 />
+
 ## 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.

package/package.json

@@ -1,12 +1,23 @@
 {
   "name": "ths-csprng",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "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, createHash, 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)),
@@ -58,38 +57,56 @@ export const Utils = Object.freeze({
             BigInt(s || 0)                                      // Sequential salt
         ].map(n => this.bigIntToBuffer(n));
 
-        // Map metrics to uniquely structured buffers
-        const b = Buffer.concat([
+        // 128 bytes of raw, uninitialized system memory
+        // (May contain fragments of previous internal function calls/pointers, which is an additional entropy source)
+        const noise = Buffer.allocUnsafe(128);
 
-            // Inject 128 bytes of raw, uninitialized system memory 
-            // (May contain fragments of previous internal function calls/pointers)
-            Buffer.allocUnsafe(128),
+        // Hash that insecure system memory with SHA3-512
+        const hashedNoise = createHash('sha3-512')
+            .update(noise)
+            .update(process.hrtime.bigint().toString())
+            .digest();
 
+        // 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;
 
         // 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 +183,5 @@ export const Utils = Object.freeze({
     }
 });
 
-export default Utils;
+module.exports = Utils;
+module.exports.Utils = Utils;

package/src/util.mjs

@@ -0,0 +1,186 @@
+/**
+ * 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, createHash, 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));
+
+        // 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();
+
+        // 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;
+
+        // 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;