toolbox-x 1.0.0

package/dist/hash.cjs

@@ -0,0 +1,2126 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * 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.
+ */
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primitives = require('./primitives-B26uZolQ.cjs');
+const require_specials = require('./specials-DzLr1ZgU.cjs');
+const require_parse = require('./parse-2ubxXZRp.cjs');
+const require_utils = require('./utils-DLFRgXUC.cjs');
+const require_basics = require('./basics-D_eSv0cu.cjs');
+
+//#region src/hash/utils.ts
+/**
+* * Generates a random hexadecimal string of the specified length.
+*
+* @param length - Number of hex characters to generate.
+* @param uppercase - Whether to return uppercase `A–F` characters. Defaults to `false` (lowercase).
+*
+* @returns A randomly generated hexadecimal string.
+*
+* @remarks
+* - This function generates a random hexadecimal string of the specified length.
+* - It uses {@link crypto.getRandomValues} when available for secure randomness, and falls back to {@link Math.random} if not.
+* - The output is a string of hex characters (`0–9`, `a–f` or `A–F`) with no prefixes or separators.
+* - If `length` is `0` or negative, an empty string is returned.
+*
+* @example
+* // 16-character lowercase hex
+* const id = randomHex(16);
+*
+* @example
+* // 8-character uppercase hex
+* const token = randomHex(8, true);
+*/
+function randomHex(length, uppercase = false) {
+	if (length <= 0) return "";
+	const expected = _bytesToRandomHex(new Uint8Array(Math.ceil(length / 2))).slice(0, length);
+	return uppercase ? expected.toUpperCase() : expected;
+}
+/**
+* * Converts a UTF-8 string to a byte array (`Uint8Array`).
+*
+* This function encodes a JavaScript string into UTF-8 bytes, handling all Unicode code points including supplementary characters (surrogate pairs).
+*
+* @example
+* ```typescript
+* // Basic ASCII
+* const asciiBytes = utf8ToBytes('hello');
+* // Returns:
+* Uint8Array(5) [104, 101, 108, 108, 111]
+*
+* // Unicode characters
+* const unicodeBytes = utf8ToBytes('Hello পৃথিবী!');
+* // Returns:
+* Uint8Array(25) [
+*  72, 101, 108, 108, 111,  32,
+* 224, 166, 170, 224, 167, 131,
+* 224, 166, 165, 224, 166, 191,
+* 224, 166, 172, 224, 167, 128,
+*  33
+* ]
+* ```
+*
+* @param str - The input string to encode as UTF-8 bytes.
+* @returns A `Uint8Array` containing the UTF-8 encoded bytes.
+*
+* @remarks
+* - The encoding follows the UTF-8 specification:
+*   - 1-byte sequence for code points U+0000 to U+007F (ASCII)
+*   - 2-byte sequence for code points U+0080 to U+07FF
+*   - 3-byte sequence for code points U+0800 to U+FFFF
+*   - 4-byte sequence for code points U+10000 to U+10FFFF (surrogate pairs)
+*
+* **Note:** Invalid surrogate pairs in the input string are silently ignored.
+*
+* @see {@link bytesToUtf8} for the inverse operation
+*/
+function utf8ToBytes(str) {
+	const out = [];
+	for (let i = 0; i < str.length; i++) {
+		const code = str.charCodeAt(i);
+		if (code < 128) out.push(code);
+		else if (code < 2048) out.push(192 | code >> 6, 128 | code & 63);
+		else if (code >= 55296 && code <= 57343) {
+			if (code < 56320 && i + 1 < str.length) {
+				const hi = code;
+				const lo = str.charCodeAt(++i);
+				const codePoint = 65536 + (hi - 55296 << 10) + (lo - 56320);
+				out.push(240 | codePoint >> 18, 128 | codePoint >> 12 & 63, 128 | codePoint >> 6 & 63, 128 | codePoint & 63);
+			}
+		} else out.push(224 | code >> 12, 128 | code >> 6 & 63, 128 | code & 63);
+	}
+	return new Uint8Array(out);
+}
+/**
+* * Converts `UTF-8` encoded bytes back to a string.
+*
+* This function decodes a `Uint8Array` containing `UTF-8` bytes into a JavaScript string.
+*
+* @example
+* ```typescript
+* // Decode UTF-8 bytes
+* const bytes = new Uint8Array([104, 101, 108, 108, 111]);
+* const str = bytesToUtf8(bytes);
+* // Returns: 'hello'
+*
+* // Round-trip conversion
+* const original = 'Hello 🌍';
+* const bytes = utf8ToBytes(original);
+* const decoded = bytesToUtf8(bytes);
+* console.log(original === decoded); // true
+* ```
+*
+* @param bytes - A `Uint8Array` containing `UTF-8` encoded bytes.
+* @returns The decoded string.
+*
+* @remarks
+* - The function handles all valid `UTF-8` sequences:
+*   - 1-byte sequences (0xxxxxxx) → ASCII characters
+*   - 2-byte sequences (110xxxxx 10xxxxxx)
+*   - 3-byte sequences (1110xxxx 10xxxxxx 10xxxxxx)
+*   - 4-byte sequences (11110xxx 10xxxxxx 10xxxxxx 10xxxxxx) → surrogate pairs
+*
+* @see {@link utf8ToBytes} for the inverse operation
+*/
+function bytesToUtf8(bytes) {
+	let out = "";
+	let i = 0;
+	while (i < bytes.length) {
+		const b1 = bytes[i++];
+		if (b1 < 128) out += String.fromCharCode(b1);
+		else if (b1 >= 192 && b1 < 224) {
+			const b2 = bytes[i++];
+			out += String.fromCharCode((b1 & 31) << 6 | b2 & 63);
+		} else if (b1 >= 224 && b1 < 240) {
+			const b2 = bytes[i++];
+			const b3 = bytes[i++];
+			out += String.fromCharCode((b1 & 15) << 12 | (b2 & 63) << 6 | b3 & 63);
+		} else {
+			const b2 = bytes[i++];
+			const b3 = bytes[i++];
+			const b4 = bytes[i++];
+			let codePoint = (b1 & 7) << 18 | (b2 & 63) << 12 | (b3 & 63) << 6 | b4 & 63;
+			codePoint -= 65536;
+			out += String.fromCharCode(55296 + (codePoint >> 10 & 1023), 56320 + (codePoint & 1023));
+		}
+	}
+	return out;
+}
+/**
+* * Decodes a `Base64` string to bytes.
+*   - This function converts a `Base64`-encoded string back to its original byte representation.
+*   - It handles standard `Base64` encoding with '=', '+', '/' characters.
+*
+* @example
+* ```typescript
+* // Decode Base64 string
+* const bytes = base64ToBytes('aGVsbG8gd29ybGQ=');
+* // Returns: Uint8Array(11) [104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100]
+*
+* // Empty string
+* const empty = base64ToBytes('');
+* // Returns: Uint8Array(0) []
+* ```
+*
+* @param str - The `Base64`-encoded string to decode.
+* @returns A `Uint8Array` containing the decoded bytes.
+*
+* @remarks
+* - The function supports:
+*   - Standard `Base64` alphabet (A-Z, a-z, 0-9, +, /)
+*   - Padding with '=' characters
+*   - Ignores whitespace (though not explicitly trimmed in this implementation)
+*
+* @see {@link bytesToBase64} for the inverse operation
+*/
+function base64ToBytes(str) {
+	const _b64chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=";
+	const out = [];
+	let i = 0;
+	while (i < str.length) {
+		const h1 = _b64chars.indexOf(str[i++]);
+		const h2 = _b64chars.indexOf(str[i++]);
+		const h3 = _b64chars.indexOf(str[i++]);
+		const h4 = _b64chars.indexOf(str[i++]);
+		const o1 = h1 << 2 | h2 >> 4;
+		const o2 = (h2 & 15) << 4 | h3 >> 2;
+		const o3 = (h3 & 3) << 6 | h4;
+		out.push(o1);
+		if (h3 !== 64) out.push(o2);
+		if (h4 !== 64) out.push(o3);
+	}
+	return new Uint8Array(out);
+}
+/**
+* * Encodes bytes to a `Base64` string.
+*   - This function converts a `Uint8Array` to a `Base64`-encoded string using the standard `Base64` alphabet with padding.
+*
+* @example
+* ```typescript
+* // Encode bytes to Base64
+* const bytes = new Uint8Array([104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100]);
+* const b64 = bytesToBase64(bytes);
+* // Returns: 'aGVsbG8gd29ybGQ='
+*
+* // Empty array
+* const empty = bytesToBase64(new Uint8Array(0));
+* // Returns: ''
+* ```
+*
+* @param bytes - The bytes to encode as `Base64`.
+* @returns The `Base64`-encoded string.
+*
+* @remarks
+* The encoding uses:
+* - Standard `Base64` alphabet (A-Z, a-z, 0-9, +, /)
+* - '=' padding for incomplete groups
+* - No line breaks or whitespace
+*
+* This is a pure JavaScript implementation that doesn't rely on `btoa()`.
+*
+* @see {@link base64ToBytes} for the inverse operation
+*/
+function bytesToBase64(bytes) {
+	const _b64chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=";
+	let out = "";
+	let i = 0;
+	while (i < bytes.length) {
+		const o1 = bytes[i++];
+		const o2 = bytes[i++];
+		const o3 = bytes[i++];
+		const h1 = o1 >> 2;
+		const h2 = (o1 & 3) << 4 | o2 >> 4;
+		const h3 = (o2 & 15) << 2 | o3 >> 6;
+		const h4 = o3 & 63;
+		out += _b64chars[h1] + _b64chars[h2] + _b64chars[isNaN(o2) ? 64 : h3] + _b64chars[isNaN(o3) ? 64 : h4];
+	}
+	return out;
+}
+/**
+* * Concatenates multiple `Uint8Array`s into a single `Uint8Array`.
+*   - This function efficiently combines multiple byte arrays without creating intermediate strings or arrays.
+*
+* @example
+* ```typescript
+* // Concatenate multiple arrays
+* const a = new Uint8Array([1, 2, 3]);
+* const b = new Uint8Array([4, 5]);
+* const c = new Uint8Array([6, 7, 8, 9]);
+* const result = concatBytes(a, b, c);
+* // Returns: Uint8Array(9) [1, 2, 3, 4, 5, 6, 7, 8, 9]
+*
+* // Single array
+* const single = concatBytes(new Uint8Array([1, 2, 3]));
+* // Returns: Uint8Array(3) [1, 2, 3]
+*
+* // No arrays
+* const empty = concatBytes();
+* // Returns: Uint8Array(0) []
+* ```
+*
+* @param parts - One or more `Uint8Array`s to concatenate.
+* @returns A new `Uint8Array` containing all the bytes from the input arrays in the order they were provided.
+*
+* @remarks The function allocates a single `Uint8Array` of the total combined length and copies all bytes into it using `set()` for optimal performance.
+*/
+function concatBytes(...parts) {
+	const len = parts.reduce((s, p) => s + p.length, 0);
+	const out = new Uint8Array(len);
+	let offset = 0;
+	for (const p of parts) {
+		out.set(p, offset);
+		offset += p.length;
+	}
+	return out;
+}
+/**
+* * Computes the `SHA-256` hash of raw bytes.
+*   - This is a pure JavaScript implementation of the `SHA-256` cryptographic hash function that operates directly on byte arrays (`Uint8Array`).
+*
+* @example
+* ```typescript
+* // Hash raw bytes
+* const bytes = new Uint8Array([104, 101, 108, 108, 111]); // "hello"
+* const hash = sha256Bytes(bytes);
+* // Returns: Uint8Array(32) with SHA-256 hash
+*
+* // Verify with string hash
+* const strHash = sha256('hello');
+* const bytesHash = bytesToHex(sha256Bytes(utf8ToBytes('hello')));
+* console.log(strHash === bytesHash); // true
+* ```
+*
+* @param message - The bytes to hash as a `Uint8Array`.
+* @returns A `Uint8Array` of 32 bytes (256 bits) containing the `SHA-256` hash.
+*
+* @remarks
+* - Implementation details:
+*   - Follows the `SHA-256` specification (FIPS 180-4)
+*   - Uses big-endian byte order throughout
+*   - Processes messages in 512-bit (64-byte) blocks
+*   - Applies proper padding with message length
+*   - Uses all required `SHA-256` round constants
+*   - Returns hash as 32-byte array
+*
+* @see {@link hmacSha256} for `HMAC-SHA256` computation
+*/
+function sha256Bytes(message) {
+	const H = new Uint32Array([
+		1779033703,
+		3144134277,
+		1013904242,
+		2773480762,
+		1359893119,
+		2600822924,
+		528734635,
+		1541459225
+	]);
+	const K = new Uint32Array([
+		1116352408,
+		1899447441,
+		3049323471,
+		3921009573,
+		961987163,
+		1508970993,
+		2453635748,
+		2870763221,
+		3624381080,
+		310598401,
+		607225278,
+		1426881987,
+		1925078388,
+		2162078206,
+		2614888103,
+		3248222580,
+		3835390401,
+		4022224774,
+		264347078,
+		604807628,
+		770255983,
+		1249150122,
+		1555081692,
+		1996064986,
+		2554220882,
+		2821834349,
+		2952996808,
+		3210313671,
+		3336571891,
+		3584528711,
+		113926993,
+		338241895,
+		666307205,
+		773529912,
+		1294757372,
+		1396182291,
+		1695183700,
+		1986661051,
+		2177026350,
+		2456956037,
+		2730485921,
+		2820302411,
+		3259730800,
+		3345764771,
+		3516065817,
+		3600352804,
+		4094571909,
+		275423344,
+		430227734,
+		506948616,
+		659060556,
+		883997877,
+		958139571,
+		1322822218,
+		1537002063,
+		1747873779,
+		1955562222,
+		2024104815,
+		2227730452,
+		2361852424,
+		2428436474,
+		2756734187,
+		3204031479,
+		3329325298
+	]);
+	const ml = message.length * 8;
+	const padding = new Uint8Array(message.length + 8 + 64 & -64 || 64);
+	padding.set(message, 0);
+	padding[message.length] = 128;
+	const lenView = new DataView(padding.buffer);
+	lenView.setUint32(padding.length - 8, Math.floor(ml / 4294967296), false);
+	lenView.setUint32(padding.length - 4, ml & 4294967295, false);
+	const w = new Uint32Array(64);
+	const chunkView = new DataView(padding.buffer);
+	for (let offset = 0; offset < padding.length; offset += 64) {
+		for (let t = 0; t < 16; t++) w[t] = chunkView.getUint32(offset + t * 4, false);
+		for (let t = 16; t < 64; t++) {
+			const s0 = (w[t - 15] >>> 7 | w[t - 15] << 25) ^ (w[t - 15] >>> 18 | w[t - 15] << 14) ^ w[t - 15] >>> 3;
+			const s1 = (w[t - 2] >>> 17 | w[t - 2] << 15) ^ (w[t - 2] >>> 19 | w[t - 2] << 13) ^ w[t - 2] >>> 10;
+			w[t] = w[t - 16] + s0 + w[t - 7] + s1 >>> 0;
+		}
+		let a = H[0];
+		let b = H[1];
+		let c = H[2];
+		let d = H[3];
+		let e = H[4];
+		let f = H[5];
+		let g = H[6];
+		let h = H[7];
+		for (let t = 0; t < 64; t++) {
+			const S1 = (e >>> 6 | e << 26) ^ (e >>> 11 | e << 21) ^ (e >>> 25 | e << 7);
+			const ch = e & f ^ ~e & g;
+			const temp1 = h + S1 + ch + K[t] + w[t] >>> 0;
+			const temp2 = ((a >>> 2 | a << 30) ^ (a >>> 13 | a << 19) ^ (a >>> 22 | a << 10)) + (a & b ^ a & c ^ b & c) >>> 0;
+			h = g;
+			g = f;
+			f = e;
+			e = d + temp1 >>> 0;
+			d = c;
+			c = b;
+			b = a;
+			a = temp1 + temp2 >>> 0;
+		}
+		H[0] = H[0] + a >>> 0;
+		H[1] = H[1] + b >>> 0;
+		H[2] = H[2] + c >>> 0;
+		H[3] = H[3] + d >>> 0;
+		H[4] = H[4] + e >>> 0;
+		H[5] = H[5] + f >>> 0;
+		H[6] = H[6] + g >>> 0;
+		H[7] = H[7] + h >>> 0;
+	}
+	const out = new Uint8Array(32);
+	const outView = new DataView(out.buffer);
+	for (let i = 0; i < 8; i++) outView.setUint32(i * 4, H[i], false);
+	return out;
+}
+/**
+* * Computes `HMAC-SHA256` (Hash-based Message Authentication Code using `SHA-256`).
+*  - This function implements the `HMAC` algorithm with `SHA-256` as the underlying hash function, providing message authentication and integrity verification.
+*
+* @example
+* ```typescript
+* // Basic HMAC calculation
+* const key = new TextEncoder().encode('secret-key');
+* const message = new TextEncoder().encode('Hello, world!');
+* const hmac = hmacSha256(key, message);
+*
+* // Using with string inputs
+* const keyBytes = new TextEncoder().encode('my-key');
+* const msgBytes = new TextEncoder().encode('data to authenticate');
+* const hmacResult = hmacSha256(keyBytes, msgBytes);
+* const hexResult = bytesToHex(hmacResult);
+* ```
+*
+* @param key - The secret key as a `Uint8Array`.
+* @param message - The message to authenticate as a `Uint8Array`.
+* @returns A `Uint8Array` of 32 bytes containing the `HMAC-SHA256` tag.
+*
+* @remarks
+* - Algorithm steps:
+*   - 1. Keys longer than 64 bytes are hashed with `SHA-256`
+*   - 2. Keys shorter than 64 bytes are padded with zeros
+*   - 3. Inner hash: `SHA-256((key ⊕ ipad) || message)` where ipad = 0x36 repeated
+*   - 4. Outer hash: `SHA-256((key ⊕ opad) || inner_hash)` where opad = 0x5C repeated
+*
+* - The implementation follows RFC 2104 and RFC 4231 specifications.
+* - Block size for `SHA-256` HMAC is 64 bytes (512 bits).
+*
+* **Common use cases:**
+* - API authentication tokens
+* - Message integrity verification
+* - Key derivation (as part of `HKDF`)
+*
+* @see {@link sha256Bytes} for the underlying hash function
+*/
+function hmacSha256(key, message) {
+	const blockSize = 64;
+	let k = key;
+	if (k.length > blockSize) k = sha256Bytes(k);
+	if (k.length < blockSize) {
+		const tmp = new Uint8Array(blockSize);
+		tmp.set(k, 0);
+		k = tmp;
+	}
+	const oKeyPad = new Uint8Array(blockSize);
+	const iKeyPad = new Uint8Array(blockSize);
+	for (let i = 0; i < blockSize; i++) {
+		oKeyPad[i] = k[i] ^ 92;
+		iKeyPad[i] = k[i] ^ 54;
+	}
+	const inner = new Uint8Array(iKeyPad.length + message.length);
+	inner.set(iKeyPad, 0);
+	inner.set(message, iKeyPad.length);
+	const innerHash = sha256Bytes(inner);
+	const outer = new Uint8Array(oKeyPad.length + innerHash.length);
+	outer.set(oKeyPad, 0);
+	outer.set(innerHash, oKeyPad.length);
+	return sha256Bytes(outer);
+}
+/**
+* * Converts a `Uint8Array` to a `Uint32Array` with big-endian byte order.
+*   - This function groups bytes into 32-bit integers, reading them in big-endian (most significant byte first) order. Missing bytes are treated as zero.
+*
+* @example
+* ```typescript
+* // Convert bytes to 32-bit integers
+* const bytes = new Uint8Array([0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC]);
+* const words = uint8To32ArrayBE(bytes);
+* // Returns: Uint32Array(2) [0x12345678, 0x9ABC0000] or equivalent: Uint32Array(2) [ 305419896, 2596012032 ]
+*
+* // Partial final word
+* const partial = new Uint8Array([0xFF, 0xEE, 0xDD]);
+* const words2 = uint8To32ArrayBE(partial);
+* // Returns: Uint32Array(1) [0xFFEEDD00] or equivalent: Uint32Array(1) [ 4293844224 ]
+* ```
+*
+* @param bytes - The bytes to convert to 32-bit words.
+* @returns A `Uint32Array` containing the 32-bit big-endian words.
+*
+* @remarks
+* - Input length doesn't need to be a multiple of 4
+* - Missing bytes in the final word are padded with zeros
+* - Byte order: `bytes[0]` is the most significant byte of `out[0]`
+* - This is useful for cryptographic operations that work with 32-bit words
+*/
+function uint8To32ArrayBE(bytes) {
+	const len = Math.ceil(bytes.length / 4);
+	const out = new Uint32Array(len);
+	for (let i = 0; i < len; i++) {
+		const base = i * 4;
+		out[i] = (bytes[base] || 0) << 24 | (bytes[base + 1] || 0) << 16 | (bytes[base + 2] || 0) << 8 | (bytes[base + 3] || 0) << 0;
+	}
+	return out;
+}
+/**
+* * Converts a 32-bit integer into a 4-byte `Uint8Array` in big-endian (network) byte order.
+*   - This function takes a 32-bit integer and encodes it as 4 bytes with the most significant byte first (big-endian order), which is the standard for network protocols and many cryptographic operations.
+*
+* @example
+* ```typescript
+* // Convert integer to bytes
+* const bytes = intTo4BytesBE(0x12345678);
+* // Returns: Uint8Array(4) [0x12, 0x34, 0x56, 0x78] or equivalent: Uint8Array(4) [ 18, 52, 86, 120 ]
+*
+* // Maximum 32-bit value
+* const maxBytes = intTo4BytesBE(0xFFFFFFFF);
+* // Returns: Uint8Array(4) [0xFF, 0xFF, 0xFF, 0xFF]
+*
+* // Zero
+* const zeroBytes = intTo4BytesBE(0);
+* // Returns: Uint8Array(4) [0x00, 0x00, 0x00, 0x00]
+* ```
+*
+* @param n - The 32-bit integer to convert. Values beyond 32 bits will be truncated.
+* @returns A 4-byte `Uint8Array` representing the value in big-endian format.
+*
+* @remarks
+* - The function uses unsigned 32-bit arithmetic (`>>>` operator)
+* - Only the lower 32 bits of the input are used (truncation)
+* - Output is always exactly 4 bytes
+* - Big-endian order: byte[0] = most significant, byte[3] = least significant
+*
+* **Common use cases:**
+* - Encoding message lengths in network protocols
+* - Preparing data for cryptographic operations
+* - Converting integers for storage or transmission
+*
+* @see {@link uint8To32ArrayBE} for bytes to 32-bit integers conversion
+*/
+function intTo4BytesBE(n) {
+	const b = new Uint8Array(4);
+	b[0] = n >>> 24 & 255;
+	b[1] = n >>> 16 & 255;
+	b[2] = n >>> 8 & 255;
+	b[3] = n & 255;
+	return b;
+}
+/**
+* * Converts a `Uint8Array` to a lowercase hexadecimal string.
+*   - This function encodes binary data (bytes) as a hexadecimal string, with each byte represented as two lowercase hexadecimal digits (0-9, a-f).
+*
+* @example
+* ```typescript
+* // Convert bytes to hex
+* const bytes = new Uint8Array([0x12, 0xAB, 0xFF, 0x00]);
+* const hex = bytesToHex(bytes);
+* // Returns: '12abff00'
+*
+* // Empty array
+* const emptyHex = bytesToHex(new Uint8Array(0));
+* // Returns: ''
+*
+* // SHA-256 hash to hex
+* const hashBytes = sha256Bytes(utf8ToBytes('hello'));
+* const hashHex = bytesToHex(hashBytes);
+* // Returns: '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
+* ```
+*
+* @param bytes - The bytes to convert to hexadecimal representation.
+* @returns A lowercase hexadecimal string where each byte is represented by two characters (00-ff).
+*
+* @remarks
+* - Always returns lowercase letters (a-f)
+* - Zero pads single-digit hex values (e.g., 0x0F → "0f", not "f")
+* - Efficient O(n) implementation using string concatenation
+* - No prefix (e.g., no "0x" at the beginning)
+*
+* **Common use cases:**
+* - Displaying cryptographic hashes and signatures
+* - Debugging binary data
+* - Converting binary data for JSON serialization
+* - Creating hex-encoded strings for APIs and protocols
+*
+* @see {@link hexToBytes} for reverse process
+*/
+function bytesToHex(bytes) {
+	let hex = "";
+	for (let i = 0; i < bytes.length; i++) {
+		const byte = bytes[i].toString(16).padStart(2, "0");
+		hex += byte;
+	}
+	return hex;
+}
+/**
+* * Converts a hexadecimal string to a `Uint8Array`.
+*   - This function decodes a hexadecimal-encoded string into its raw byte representation, where every two hexadecimal characters (00–ff) are converted into one byte.
+*
+* @example
+* // Convert hex to bytes
+* const hex = '12abff00';
+* const bytes = hexToBytes(hex);
+* // Returns: Uint8Array(4) [18, 171, 255, 0]
+*
+* // Empty string
+* const emptyBytes = hexToBytes('');
+* // Returns: Uint8Array []
+*
+* // Decode SHA-256 hash from hex
+* const hashHex = '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824';
+* const hashBytes = hexToBytes(hashHex);
+* // Returns: Uint8Array(32)
+*
+* @param hex - A hexadecimal string where each byte is represented by two characters (00–ff).
+* @returns A `Uint8Array` containing the decoded bytes. Returns an empty array for invalid input.
+*
+* @remarks
+* - Accepts lowercase and uppercase hexadecimal characters (0–9, a–f, A–F) with or without space between bytes
+* - Ignores no prefixes (e.g., does not support "0x")
+* - Requires an even number of hexadecimal characters
+* - Efficient O(n) implementation with direct byte parsing
+*
+* **Common use cases:**
+* - Decoding cryptographic hashes and signatures
+* - Parsing hex-encoded binary payloads
+* - Reconstructing binary data from storage or transport formats
+* - Working with low-level protocols and binary APIs
+*
+* @see {@link bytesToHex} for the reverse process
+*/
+function hexToBytes(hex) {
+	if (!require_specials.isHexString(hex)) return new Uint8Array();
+	const bytes = _splitByCharLength(hex, 2).map((h) => parseInt(h, 16));
+	return new Uint8Array(bytes);
+}
+
+//#endregion
+//#region src/hash/helpers.ts
+/** Adds two 32-bit numbers */
+function _add32(x, y) {
+	return x + y & 4294967295;
+}
+/** Converts a 32-bit number to a 4-byte hex string */
+function _numToHex(n) {
+	return [
+		0,
+		8,
+		16,
+		24
+	].map((shift) => (n >> shift & 255).toString(16).padStart(2, "0")).join("");
+}
+/** Converts a 64-character string block to an array of 16 numbers */
+function _stringToNumbers(s) {
+	return Array.from({ length: 16 }, (_, i) => {
+		const x = i << 2;
+		return s.charCodeAt(x) | s.charCodeAt(x + 1) << 8 | s.charCodeAt(x + 2) << 16 | s.charCodeAt(x + 3) << 24;
+	});
+}
+/** Common MD5 transformation function */
+function _transform(q, a, b, x, s, t) {
+	const a1 = _add32(_add32(a, q), _add32(x, t));
+	return _add32(a1 << s | a1 >>> 32 - s, b);
+}
+/** Round 1 operation */
+const ff = (a, b, c, d, x, s, t) => {
+	return _transform(b & c | ~b & d, a, b, x, s, t);
+};
+/** Round 2 operation */
+const gg = (a, b, c, d, x, s, t) => {
+	return _transform(b & d | c & ~d, a, b, x, s, t);
+};
+/** Round 3 operation */
+const hh = (a, b, c, d, x, s, t) => {
+	return _transform(b ^ c ^ d, a, b, x, s, t);
+};
+/** Round 4 operation */
+const ii = (a, b, c, d, x, s, t) => {
+	return _transform(c ^ (b | ~d), a, b, x, s, t);
+};
+/** Performs one MD5 cycle on a 4-element state with 16-word block */
+function _md5cycle(x, k) {
+	let a = x[0];
+	let b = x[1];
+	let c = x[2];
+	let d = x[3];
+	a = ff(a, b, c, d, k[0], 7, -680876936);
+	d = ff(d, a, b, c, k[1], 12, -389564586);
+	c = ff(c, d, a, b, k[2], 17, 606105819);
+	b = ff(b, c, d, a, k[3], 22, -1044525330);
+	a = ff(a, b, c, d, k[4], 7, -176418897);
+	d = ff(d, a, b, c, k[5], 12, 1200080426);
+	c = ff(c, d, a, b, k[6], 17, -1473231341);
+	b = ff(b, c, d, a, k[7], 22, -45705983);
+	a = ff(a, b, c, d, k[8], 7, 1770035416);
+	d = ff(d, a, b, c, k[9], 12, -1958414417);
+	c = ff(c, d, a, b, k[10], 17, -42063);
+	b = ff(b, c, d, a, k[11], 22, -1990404162);
+	a = ff(a, b, c, d, k[12], 7, 1804603682);
+	d = ff(d, a, b, c, k[13], 12, -40341101);
+	c = ff(c, d, a, b, k[14], 17, -1502002290);
+	b = ff(b, c, d, a, k[15], 22, 1236535329);
+	a = gg(a, b, c, d, k[1], 5, -165796510);
+	d = gg(d, a, b, c, k[6], 9, -1069501632);
+	c = gg(c, d, a, b, k[11], 14, 643717713);
+	b = gg(b, c, d, a, k[0], 20, -373897302);
+	a = gg(a, b, c, d, k[5], 5, -701558691);
+	d = gg(d, a, b, c, k[10], 9, 38016083);
+	c = gg(c, d, a, b, k[15], 14, -660478335);
+	b = gg(b, c, d, a, k[4], 20, -405537848);
+	a = gg(a, b, c, d, k[9], 5, 568446438);
+	d = gg(d, a, b, c, k[14], 9, -1019803690);
+	c = gg(c, d, a, b, k[3], 14, -187363961);
+	b = gg(b, c, d, a, k[8], 20, 1163531501);
+	a = gg(a, b, c, d, k[13], 5, -1444681467);
+	d = gg(d, a, b, c, k[2], 9, -51403784);
+	c = gg(c, d, a, b, k[7], 14, 1735328473);
+	b = gg(b, c, d, a, k[12], 20, -1926607734);
+	a = hh(a, b, c, d, k[5], 4, -378558);
+	d = hh(d, a, b, c, k[8], 11, -2022574463);
+	c = hh(c, d, a, b, k[11], 16, 1839030562);
+	b = hh(b, c, d, a, k[14], 23, -35309556);
+	a = hh(a, b, c, d, k[1], 4, -1530992060);
+	d = hh(d, a, b, c, k[4], 11, 1272893353);
+	c = hh(c, d, a, b, k[7], 16, -155497632);
+	b = hh(b, c, d, a, k[10], 23, -1094730640);
+	a = hh(a, b, c, d, k[13], 4, 681279174);
+	d = hh(d, a, b, c, k[0], 11, -358537222);
+	c = hh(c, d, a, b, k[3], 16, -722521979);
+	b = hh(b, c, d, a, k[6], 23, 76029189);
+	a = hh(a, b, c, d, k[9], 4, -640364487);
+	d = hh(d, a, b, c, k[12], 11, -421815835);
+	c = hh(c, d, a, b, k[15], 16, 530742520);
+	b = hh(b, c, d, a, k[2], 23, -995338651);
+	a = ii(a, b, c, d, k[0], 6, -198630844);
+	d = ii(d, a, b, c, k[7], 10, 1126891415);
+	c = ii(c, d, a, b, k[14], 15, -1416354905);
+	b = ii(b, c, d, a, k[5], 21, -57434055);
+	a = ii(a, b, c, d, k[12], 6, 1700485571);
+	d = ii(d, a, b, c, k[3], 10, -1894986606);
+	c = ii(c, d, a, b, k[10], 15, -1051523);
+	b = ii(b, c, d, a, k[1], 21, -2054922799);
+	a = ii(a, b, c, d, k[8], 6, 1873313359);
+	d = ii(d, a, b, c, k[15], 10, -30611744);
+	c = ii(c, d, a, b, k[6], 15, -1560198380);
+	b = ii(b, c, d, a, k[13], 21, 1309151649);
+	a = ii(a, b, c, d, k[4], 6, -145523070);
+	d = ii(d, a, b, c, k[11], 10, -1120210379);
+	c = ii(c, d, a, b, k[2], 15, 718787259);
+	b = ii(b, c, d, a, k[9], 21, -343485551);
+	x[0] = _add32(a, x[0]);
+	x[1] = _add32(b, x[1]);
+	x[2] = _add32(c, x[2]);
+	x[3] = _add32(d, x[3]);
+}
+/**
+* Computes UUID timestamp in 100-nanosecond intervals since
+* 00:00:00.00 15 October 1582 (Gregorian epoch).
+*/
+function _uuidTimestamp() {
+	return (BigInt(Date.now()) + 12219292800000n) * 10000n;
+}
+/**
+* Generates a random 48-bit node ID.
+* LSB of first byte must be 1 to indicate a randomly generated node.
+*/
+function _randomNode48() {
+	const node = randomHex(12).split("");
+	return (parseInt(node.slice(0, 2).join(""), 16) | 1).toString(16).padStart(2, "0") + node.slice(2).join("");
+}
+/**
+* Generates random hex string of given byte length using crypto API if available, otherwise falls back to Math.random.
+* @param bytes Instance of {@link Uint8Array} to fill with random values.
+* @returns Hex string representation of the random bytes.
+*/
+function _bytesToRandomHex(bytes) {
+	if (crypto?.getRandomValues) crypto.getRandomValues(bytes);
+	else for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+	let hex = "";
+	for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, "0");
+	return hex;
+}
+/** * Generates a 14-bit clock sequence (2 bytes, but only 14 bits used). */
+function _clockSeq14() {
+	return (parseInt(randomHex(4), 16) & 16383).toString(16).padStart(4, "0");
+}
+/** Convert a hex string to UUID format */
+function _formatUUID(h, v, up) {
+	const part3 = String(v) + h.slice(13, 16);
+	const part4 = _hexVariant(h.slice(16, 18)) + h.slice(18, 20);
+	const formatted = [
+		h.slice(0, 8),
+		h.slice(8, 12),
+		part3,
+		part4,
+		h.slice(20, 32)
+	].join("-");
+	return up ? formatted.toUpperCase() : formatted;
+}
+/** Ensure UUID variant is RFC4122 compliant */
+function _hexVariant(hex) {
+	return (parseInt(hex, 16) & 63 | 128).toString(16).padStart(2, "0");
+}
+/** Check if the uuid `options` is compatible for `v3` and `v5` */
+function _isOptionV3V5(opt) {
+	if (require_specials.isObjectWithKeys(opt, ["name", "namespace"])) return require_specials.isUUID(opt?.namespace) && require_primitives.isNonEmptyString(opt?.name);
+	return false;
+}
+/** Check UUID version after checking for valid UUID from `v1-v8` */
+function _checkUUIDVersion(value, v) {
+	return require_specials.isUUID(value) && value[14] === v;
+}
+/**
+* Compares two encrypted strings or byte arrays in constant time.
+* Prevents timing attacks by ensuring equal-time checks regardless of data differences.
+*/
+function _constantTimeEquals(a, b) {
+	if (a.length !== b.length) return false;
+	const _getRes = (x, idx) => {
+		return require_primitives.isString(x) ? x.charCodeAt(idx) : x[idx];
+	};
+	let res = 0;
+	for (let i = 0; i < a.length; i++) res |= _getRes(a, i) ^ _getRes(b, i);
+	return res === 0;
+}
+/** Split string by substring length, intended to be used internally for hex and binary converters only */
+function _splitByCharLength(str, splitByChars = 2) {
+	if (!require_primitives.isNonEmptyString(str)) return [];
+	const sanitized = str.replace(/\s+/g, "");
+	const result = [];
+	for (let i = 0; i < sanitized.length; i += splitByChars) result.push(sanitized.slice(i, i + splitByChars));
+	return result;
+}
+/** Pad start of a byte with 0 for `hex` or `binary` */
+function _padStartWith0(byte, type) {
+	return byte.toString(type === "hex" ? 16 : 2).padStart(type === "hex" ? 2 : 8, "0");
+}
+
+//#endregion
+//#region src/hash/Cipher.ts
+/**
+* @class Lightweight stream-cipher–style encryption utility using `HMAC-SHA256` for keystream generation and authentication.
+*      - The class derives separate encryption and MAC keys from the provided secret.
+*
+* @remarks
+* - **The encryption scheme is:**
+*   - keystream = `HMAC(encKey, iv || counter)`
+*   - ciphertext = `plaintext XOR keystream`
+*   - tag = `HMAC(macKey, iv || ciphertext)`
+* - This is a custom construction and should not be used for production-grade cryptographic security.
+* - `Cipher` class is a pure JS implementation. It does not rely on `crypto` or Web APIs.
+*/
+var Cipher = class {
+	#secretBytes;
+	#encKey;
+	#macKey;
+	/**
+	* * Creates a new `Cipher` instance using the provided secret.
+	*
+	* @param secret - The secret string used to derive encryption and MAC keys.
+	* 				   Must be a non-empty string.
+	*/
+	constructor(secret) {
+		if (!require_primitives.isNonEmptyString(secret)) throw new Error("Secret must be non-empty string!");
+		this.#secretBytes = utf8ToBytes(secret);
+		this.#encKey = hmacSha256(this.#secretBytes, utf8ToBytes("enc"));
+		this.#macKey = hmacSha256(this.#secretBytes, utf8ToBytes("mac"));
+	}
+	/**
+	* Generates a keystream of the same length as the provided data using a `HMAC`-based counter mode.
+	* The keystream is deterministic from the encryption key and IV.
+	*
+	* @param target - The byte array whose length determines the keystream size.
+	* @param iv - The initialization vector used as input to the `HMAC`.
+	* @returns A byte array representing the generated keystream.
+	*/
+	#genKeystream(target, iv) {
+		const blocks = Math.ceil(target.length / 32);
+		const keystreamParts = [];
+		for (let counter = 0; counter < blocks; counter++) keystreamParts.push(hmacSha256(this.#encKey, concatBytes(iv, intTo4BytesBE(counter))));
+		return concatBytes(...keystreamParts).subarray(0, target.length);
+	}
+	/**
+	* * Encrypts a UTF-8 string.
+	*   - The output format is: `base64( iv || ciphertext || tag )`
+	*
+	* @param text - The plaintext string to encrypt.
+	* @returns A base64-encoded encrypted token.
+	*/
+	encrypt(text) {
+		const plain = utf8ToBytes(text);
+		const iv = sha256Bytes(utf8ToBytes(String(Date.now()) + "-" + String(Math.random()))).subarray(0, 16);
+		const keystream = this.#genKeystream(plain, iv);
+		const ct = new Uint8Array(plain.length);
+		for (let i = 0; i < plain.length; i++) ct[i] = plain[i] ^ keystream[i];
+		return bytesToBase64(concatBytes(iv, ct, hmacSha256(this.#macKey, concatBytes(iv, ct))));
+	}
+	/**
+	* * Checks if a token is structurally valid and contains a matching MAC using the same secret.
+	*
+	* @param token - The base64-encoded encrypted blob to validate.
+	* @returns `true` if the MAC is valid, `false` otherwise.
+	*/
+	isValid(token) {
+		if (!require_specials.isBase64(token)) return false;
+		const blob = base64ToBytes(token);
+		if (blob.length < 48) return false;
+		const iv = blob.subarray(0, 16);
+		const tag = blob.subarray(blob.length - 32);
+		const ct = blob.subarray(16, blob.length - 32);
+		return _constantTimeEquals(hmacSha256(this.#macKey, concatBytes(iv, ct)), tag);
+	}
+	/**
+	* * Decrypts a previously encrypted token.
+	*   - Throws an error if the tag does not match or the token is malformed.
+	*
+	* @param token - The base64-encoded token produced by `encrypt`.
+	* @returns The decrypted plaintext string.
+	*/
+	decrypt(token) {
+		if (!require_specials.isBase64(token)) throw new Error("Token must be a base64 string!");
+		const blob = base64ToBytes(token);
+		if (blob.length < 48) throw new Error("Malformed or tampered token!");
+		const iv = blob.subarray(0, 16);
+		const tag = blob.subarray(blob.length - 32);
+		const ct = blob.subarray(16, blob.length - 32);
+		if (!_constantTimeEquals(hmacSha256(this.#macKey, concatBytes(iv, ct)), tag)) throw new Error("Key in the token is tampered or invalid!)");
+		const keystream = this.#genKeystream(ct, iv);
+		const pt = new Uint8Array(ct.length);
+		for (let i = 0; i < ct.length; i++) pt[i] = ct[i] ^ keystream[i];
+		return bytesToUtf8(pt);
+	}
+};
+
+//#endregion
+//#region src/hash/core.ts
+/**
+* * Computes the `MD5` digest of the given string using a pure JavaScript implementation.
+*
+* @remarks
+* - Pure JavaScript implementation — runs on any JS engine. Does not rely on `crypto` or **Web APIs** or other external libraries.
+* - Highly inspired by the algorithm used in {@link https://github.com/eustatos/pure-md5.git pure-md5} package.
+*
+* @param str - Input text to hash.
+*
+* @returns The `MD5` hash as a 32-character hex string.
+*
+* @example
+* const hash = md5("hello");
+* // → "5d41402abc4b2a76b9719d911017c592" *
+*
+* @example
+* // Used inside UUID v3
+* const digest = md5(namespace + name);
+*/
+function md5(str) {
+	const state = [
+		1732584193,
+		-271733879,
+		-1732584194,
+		271733878
+	];
+	const len = str.length;
+	let i;
+	for (i = 64; i <= len; i += 64) _md5cycle(state, _stringToNumbers(str.substring(i - 64, i)));
+	const $str = str.substring(i - 64);
+	const tail = [
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0
+	];
+	for (i = 0; i < $str.length; i++) tail[i >> 2] |= $str.charCodeAt(i) << (i % 4 << 3);
+	tail[i >> 2] |= 128 << (i % 4 << 3);
+	if (i > 55) {
+		_md5cycle(state, tail);
+		for (let j = 0; j < 16; j++) tail[j] = 0;
+	}
+	tail[14] = len * 8;
+	_md5cycle(state, tail);
+	return state.map(_numToHex).join("");
+}
+/**
+* * Computes the `SHA-1` digest of the given string using a pure JavaScript implementation.
+*
+* @remarks Pure JavaScript implementation — runs on any JS engine. Does not rely on `crypto` or **Web APIs** or other external libraries.
+*
+* @param msg - Input text to hash.
+*
+* @returns The `SHA-1` hash as a 40-character hex string.
+*
+* @example
+* const hash = sha1("hello");
+* // → "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"
+*
+* @example
+* // Used inside UUID v5
+* const digest = sha1(namespace + name);
+*/
+function sha1(msg) {
+	const K = [
+		1518500249,
+		1859775393,
+		2400959708,
+		3395469782
+	];
+	const utf8 = utf8ToBytes(msg);
+	const rotl = (n, bits) => n << bits | n >>> 32 - bits;
+	const toHex = (n) => (n >>> 0).toString(16).padStart(8, "0");
+	const len = utf8.length;
+	const padBytes = (len + 9) % 64 ? 64 - (len + 9) % 64 : 0;
+	const total = len + 1 + padBytes + 8;
+	const words = new Uint32Array(total >>> 2);
+	for (let i = 0; i < utf8.length; i++) words[i >> 2] |= utf8[i] << 24 - i % 4 * 8;
+	words[utf8.length >> 2] |= 128 << 24 - utf8.length % 4 * 8;
+	words[words.length - 1] = utf8.length * 8;
+	const h = [
+		1732584193,
+		4023233417,
+		2562383102,
+		271733878,
+		3285377520
+	];
+	const W = new Uint32Array(80);
+	for (let i = 0; i < words.length; i += 16) {
+		for (let j = 0; j < 16; j++) W[j] = words[i + j] | 0;
+		for (let j = 16; j < 80; j++) W[j] = rotl(W[j - 3] ^ W[j - 8] ^ W[j - 14] ^ W[j - 16], 1);
+		let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4];
+		for (let j = 0; j < 80; j++) {
+			let f, k;
+			if (j < 20) {
+				f = b & c | ~b & d;
+				k = K[0];
+			} else if (j < 40) {
+				f = b ^ c ^ d;
+				k = K[1];
+			} else if (j < 60) {
+				f = b & c | b & d | c & d;
+				k = K[2];
+			} else {
+				f = b ^ c ^ d;
+				k = K[3];
+			}
+			const temp = rotl(a, 5) + f + e + k + W[j] | 0;
+			e = d;
+			d = c;
+			c = rotl(b, 30);
+			b = a;
+			a = temp;
+		}
+		h[0] = h[0] + a | 0;
+		h[1] = h[1] + b | 0;
+		h[2] = h[2] + c | 0;
+		h[3] = h[3] + d | 0;
+		h[4] = h[4] + e | 0;
+	}
+	return h.map(toHex).join("");
+}
+/**
+* * Computes the `SHA-256` hash of a `UTF-8` string and returns it as a lowercase hexadecimal string.
+*
+* @param msg - The input string to hash. Can contain any `UTF-8` characters.
+* @returns A 64-character lowercase hexadecimal string representing the `SHA-256` hash.
+*
+* @remarks Pure JavaScript implementation — runs on any JS engine. Does not rely on `crypto` or **Web APIs** or other external libraries.
+*
+* @example
+* ```typescript
+* // Basic usage
+* const hash = sha256('hello');
+* // Returns: '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
+*
+* // Empty string
+* const emptyHash = sha256('');
+* // Returns: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
+*
+* // Unicode string
+* const unicodeHash = sha256('Hello পৃথিবী!');
+* // Returns: '7037e204b825b83553ba336a6ec35b796d505599286ae864729ed6cb33ae9fe1'
+* ```
+*
+* @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/encoding#sha256bytes sha256Bytes} for hashing raw bytes
+* @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/encoding#utf8tobytes utf8ToBytes} for converting string to bytes
+* @see {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/encoding#bytestohex bytesToHex} for converting bytes to a hexadecimal string
+*/
+function sha256(msg) {
+	if (!require_primitives.isString(msg)) throw new TypeError("Input must be of type string!");
+	return bytesToHex(sha256Bytes(utf8ToBytes(msg)));
+}
+
+//#endregion
+//#region src/hash/Signet.ts
+/**
+* @class A lightweight, secure implementation of JWT-like tokens using `HMAC-SHA256` signatures.
+*      - This class provides methods to create, verify, and decode tokens with a simple API similar to JSON Web Tokens (`JWT`)
+*        but with a smaller footprint and zero dependencies.
+*
+* @remarks
+* - **Features:**
+*   - `HMAC-SHA256` signatures for security
+*   - Time-based claims (expiration, not-before)
+*   - Standard claims (audience, issuer, subject)
+*   - Constant-time signature comparison to prevent timing attacks
+*   - Automatic date conversion for timestamp claims
+*   - `Base64` URL-safe encoding (standard `Base64` in this implementation)
+*
+* - **Security considerations:**
+*   - Keep the secret key secure and rotate periodically
+*   - Use appropriate token expiration times
+*   - Validate all claims relevant to your application
+*   - Store tokens securely (HTTP-only cookies recommended for web)
+*
+* @example
+* ```typescript
+* // Create a token signer
+* const signet = new Signet('my-secret-key');
+*
+* // Sign a token with custom payload and options
+* const token = signet.sign(
+*   { userId: 123, role: 'admin' },
+*   {
+*     expiresIn: '1h',
+*     audience: 'my-app',
+*     issuer: 'auth-service'
+*   }
+* );
+*
+* // Verify a token
+* const result = signet.verify(token, {
+*   audience: 'my-app',
+*   issuer: 'auth-service'
+* });
+*
+* if (result.isValid) {
+*   console.log('Valid token for user:', result.payload.userId);
+* } else {
+*   console.log('Invalid token:', result.error);
+* }
+*
+* // Decode without verification
+* const decoded = signet.decode(token);
+* console.log('Token payload:', decoded.payload);
+* ```
+*/
+var Signet = class {
+	#secretBytes;
+	/**
+	* * Creates a new `Signet` instance with the specified secret key.
+	*
+	* @param secret - The secret key used for signing and verifying tokens.
+	*                 Must be a non-empty string.
+	*
+	* @throws If the secret is not a non-empty string.
+	*
+	* @remarks
+	* - The secret is converted to `UTF-8` bytes and stored internally.
+	* - Choose a strong secret (at least 32 characters) and store it securely.
+	* - For production, consider using key rotation strategies.
+	*
+	* @example
+	* ```typescript
+	* // Initialize with a secret key
+	* const signet = new Signet('super-secret-key-123');
+	*
+	* // Use environment variable for the secret
+	* const signet = new Signet(process.env.JWT_SECRET!);
+	* ```
+	*/
+	constructor(secret) {
+		if (!require_primitives.isNonEmptyString(secret)) throw new Error("Secret must be a non-empty string!");
+		this.#secretBytes = utf8ToBytes(secret);
+	}
+	/** Decodes a token without verifying its signature. */
+	#decode(token) {
+		if (!require_primitives.isNonEmptyString(token)) throw new Error("Token must be a non-empty string!");
+		const parts = token.split(".");
+		if (parts.length !== 3) throw new Error("Token is tampered or malformed!");
+		const [hdr, pld, signature] = parts;
+		const headerBytes = base64ToBytes(hdr);
+		const payloadBytes = base64ToBytes(pld);
+		const headerStr = require_utils.stripJsonEdgeGarbage(bytesToUtf8(headerBytes));
+		const payloadStr = require_utils.stripJsonEdgeGarbage(bytesToUtf8(payloadBytes));
+		let header;
+		try {
+			header = JSON.parse(headerStr);
+		} catch {
+			throw new Error("Cannot parse header!");
+		}
+		let payload;
+		try {
+			const { iat, iatDate, exp, expDate, nbf, nbfDate, aud, sub, iss, ...rest } = JSON.parse(payloadStr);
+			payload = {
+				iat,
+				iatDate: iatDate ? new Date(iatDate) : require_parse._secToDate(iat),
+				...exp && { exp },
+				...exp && { expDate: expDate ? new Date(expDate) : require_parse._secToDate(exp) },
+				...nbf && { nbf },
+				...nbf && { nbfDate: nbfDate ? new Date(nbfDate) : require_parse._secToDate(nbf) },
+				...aud && { aud },
+				...sub && { sub },
+				...iss && { iss },
+				...rest
+			};
+		} catch {
+			throw new Error("Cannot parse payload!");
+		}
+		return {
+			header,
+			payload,
+			signature,
+			signingInput: `${hdr}.${pld}`
+		};
+	}
+	/**
+	* * Creates and signs a new token with the given payload and options.
+	*
+	* @param payload - Custom data to include in the token payload.
+	*                  Must be a `non-empty object`.
+	* @param options - Optional configuration for token claims and expiration.
+	*
+	* @returns A signed token string in the format `header.payload.signature`.
+	*
+	* @throws If payload is not a valid object.
+	*
+	* @remarks
+	* - **The token structure follows JWT format:**
+	*   - Header: Contains algorithm (`HS256`) and token type (`SIGNET+JWT`)
+	*   - Payload: Includes standard claims (`iat`, `exp`, `nbf`, `aud`, `sub`, `iss`) plus custom data
+	*   - Signature: `HMAC-SHA256(signingInput, secret)` (the result of the hash)
+	*   - Signing Inputs: `base64(header) + "." + base64(payload)` (the string that gets hashed)
+	*
+	* - **Automatic claims added:**
+	*   - `iat` (issued at): Current time in seconds
+	*   - `iatDate`: Current time as Date object
+	*   - If `expiresIn` is provided: `exp` and `expDate`
+	*   - If `notBefore` is provided: `nbf` and `nbfDate`
+	*
+	* @example
+	* ```typescript
+	* // Basic token with custom data
+	* const token = signet.sign({ userId: 123, name: 'John' });
+	*
+	* // Token with expiration and claims
+	* const token = signet.sign(
+	*   { userId: 123 },
+	*   {
+	*     expiresIn: '2h',
+	*     audience: 'api.example.com',
+	*     issuer: 'auth-service',
+	*     subject: 'user-123'
+	*   }
+	* );
+	*
+	* // Token valid after 5 minutes
+	* const token = signet.sign(
+	*   { action: 'reset-password' },
+	*   { notBefore: '5m' }
+	* );
+	* ```
+	*/
+	sign(payload, options) {
+		if (!require_specials.isNotEmptyObject(payload)) throw new Error("Payload must be a valid object!");
+		const { expiresIn, notBefore, audience, issuer, subject } = options || {};
+		const iat = require_parse._toSeconds(Date.now());
+		const $payload = {
+			iat,
+			iatDate: require_parse._secToDate(iat),
+			...expiresIn && { exp: iat + require_parse._toSeconds(require_parse.parseMSec(expiresIn)) },
+			...expiresIn && { expDate: require_parse._secToDate(iat + require_parse._toSeconds(require_parse.parseMSec(expiresIn))) },
+			...notBefore && { nbf: iat + require_parse._toSeconds(require_parse.parseMSec(notBefore)) },
+			...notBefore && { nbfDate: require_parse._secToDate(iat + require_parse._toSeconds(require_parse.parseMSec(notBefore))) },
+			...audience && { aud: audience },
+			...subject && { sub: subject },
+			...issuer && { iss: issuer },
+			...payload
+		};
+		const headerJson = require_utils.stableStringify({
+			alg: "HS256",
+			typ: "SIGNET+JWT"
+		});
+		const payloadJson = require_utils.stableStringify($payload);
+		const headerB = utf8ToBytes(headerJson);
+		const payloadB = utf8ToBytes(payloadJson);
+		const signingInput = `${bytesToBase64(headerB)}.${bytesToBase64(payloadB)}`;
+		return `${signingInput}.${bytesToBase64(hmacSha256(this.#secretBytes, utf8ToBytes(signingInput)))}`;
+	}
+	/**
+	* * Decodes a token without verifying its signature.
+	*
+	* @typeParam T - Type of custom data in the token payload.
+	* @param token - The token string to decode.
+	*
+	* @returns The decoded token parts including header, payload, and signatures.
+	*
+	* @throws If the token is malformed, empty, or cannot be parsed.
+	*
+	* @remarks
+	* - Use this method when you need to inspect token contents without verification.
+	* - **Warning:** This does not validate the signature, so the data may have been tampered with.
+	* - Always use {@link verify} method for security-critical operations.
+	* - The payload includes both timestamp values (numbers) and {@link Date} objects for convenience.
+	*
+	* @example
+	* ```typescript
+	* // Decode token to inspect contents
+	* const decoded = signet.decode(token);
+	* console.log('Header:', decoded.header);
+	* console.log('Payload:', decoded.payload);
+	* console.log('Signature:', decoded.signature);
+	*
+	* // Access custom payload data with type safety
+	* const decoded = signet.decode<{ userId: number }>(token);
+	* const userId = decoded.payload.userId; // Type: number
+	* ```
+	*/
+	decode(token) {
+		return this.#decode(token);
+	}
+	/**
+	* * Checks if a token has expired based on its `exp` claim.
+	*
+	* @param token - The token to check.
+	*
+	* @returns `true` if the token has an `exp` claim and current time is past it,
+	*          `false` if token has no expiration or is still valid.
+	*
+	* @throws If the token is malformed or cannot be decoded.
+	*
+	* @remarks
+	* - Tokens without `exp` claim are considered non-expiring (returns `false`)
+	* - Uses current system time for comparison ({@link Date.now()})
+	* - Does not verify the signature (use only with trusted tokens or after verification)
+	*
+	* @example
+	* ```typescript
+	* // Check expiration
+	* if (signet.hasExpired(token)) {
+	*   console.log('Token has expired');
+	*   // Prompt user to re-authenticate
+	* }
+	*
+	* // Use with other validation
+	* const isValid = !signet.hasExpired(token) && !signet.isTooEarly(token);
+	* ```
+	*/
+	hasExpired(token) {
+		const { exp } = this.#decode(token).payload;
+		return exp ? require_parse._toSeconds(Date.now()) > exp : false;
+	}
+	/**
+	* * Checks if a token's `nbf` (not-before) claim indicates it's too early to use.
+	*
+	* @param token - The token to check.
+	*
+	* @returns `true` if the token has an `nbf` claim and current time is before it,
+	*          `false` if token has no `nbf` claim or is already valid.
+	*
+	* @throws If the token is malformed or cannot be decoded.
+	*
+	* @remarks
+	* - Useful for implementing time-based access control, like activation links that shouldn't be used until a certain time.
+	* - Uses current system time for comparison ({@link Date.now()})
+	* - Does not verify the signature (use only with trusted tokens or after verification)
+	*
+	* @example
+	* ```typescript
+	* // Check if token is active yet
+	* if (signet.isTooEarly(token)) {
+	*   console.log('Token not valid yet');
+	*   // Wait before using
+	* }
+	* ```
+	*/
+	isTooEarly(token) {
+		const { nbf } = this.#decode(token).payload;
+		return nbf ? require_parse._toSeconds(Date.now()) < nbf : false;
+	}
+	/**
+	* * Validates a token's `iss` (issuer) claim against an expected value.
+	*
+	* @param token - The token to check.
+	* @param expected - The expected issuer value. If `undefined`, always returns `false`.
+	*
+	* @returns `true` if the token has an `iss` claim that doesn't match the expected value,
+	*          `false` if issuer matches, token has no issuer claim, or expected issuer is undefined.
+	*
+	* @throws If the token is malformed or cannot be decoded.
+	*
+	* @remarks Use this to ensure tokens come from trusted sources in multi-issuer scenarios.
+	*
+	* @example
+	* ```typescript
+	* // Validate issuer
+	* if (signet.isInvalidIssuer(token, 'auth-service')) {
+	*   console.log('Token from unexpected issuer');
+	*   // Reject token
+	* }
+	*
+	* // With optional issuer check
+	* const issuer = process.env.EXPECTED_ISSUER;
+	* if (issuer && signet.isInvalidIssuer(token, issuer)) {
+	*   throw new Error('Invalid issuer');
+	* }
+	* ```
+	*/
+	isInvalidIssuer(token, expected) {
+		if (!expected) return false;
+		const { iss } = this.#decode(token).payload;
+		return iss ? iss !== expected : false;
+	}
+	/**
+	* * Validates a token's `aud` (audience) claim against expected values.
+	*
+	* @param token - The token to check.
+	* @param expected - The expected audience(s). Can be a string or array of strings.
+	*                   If `undefined`, always returns `false`.
+	*
+	* @returns `true` if the token has an `aud` claim and none of its values match any of the expected audiences, `false` otherwise.
+	*
+	* @throws If the token is malformed or cannot be decoded.
+	*
+	* @remarks
+	* - Tokens can have single audience (string) or multiple audiences (string[])
+	* - Returns `false` (valid) if at least one audience matches
+	* - Useful for multi-tenant or multi-service architectures
+	*
+	* @example
+	* ```typescript
+	* // Single audience check
+	* if (signet.isInvalidAudience(token, 'api.example.com')) {
+	*   console.log('Token not intended for this audience');
+	* }
+	*
+	* // Multiple allowed audiences
+	* const validAudiences = ['web-app', 'mobile-app', 'admin-panel'];
+	* if (signet.isInvalidAudience(token, validAudiences)) {
+	*   throw new Error('Invalid audience');
+	* }
+	*
+	* // Token with multiple audiences
+	* // Token payload: { aud: ['web-app', 'mobile-app'] }
+	* // Check if at least one matches
+	* const isValid = !signet.isInvalidAudience(token, ['web-app', 'admin-panel']);
+	* // Returns false (valid) because 'web-app' matches
+	* ```
+	*/
+	isInvalidAudience(token, expected) {
+		if (!expected) return false;
+		const { aud } = this.#decode(token).payload;
+		if (!aud) return false;
+		const payloadAud = Array.isArray(aud) ? aud : [aud];
+		const expectedAud = Array.isArray(expected) ? expected : [expected];
+		return payloadAud.some((tokenAud) => expectedAud.includes(tokenAud));
+	}
+	/**
+	* * Validates a token's `sub` (subject) claim against an expected value.
+	*
+	* @param token - The token to check.
+	* @param expected - The expected subject value. If `undefined`, always returns `false`.
+	*
+	* @returns `true` if the token has a `sub` claim that doesn't match the expected value,
+	*          `false` if subject matches, token has no subject claim, or expected subject is undefined.
+	*
+	* @throws If the token is malformed or cannot be decoded.
+	*
+	* @remarks
+	* - Use this to ensure tokens are being used by the intended user/entity.
+	* - Common for authorization checks where tokens should be user-specific.
+	*
+	* @example
+	* ```typescript
+	* // Validate subject
+	* const userId = 'user-123';
+	* if (signet.isInvalidSubject(token, userId)) {
+	*   console.log('Token not for this user');
+	*   // Reject request
+	* }
+	*
+	* // Optional subject validation
+	* const expectedSubject = getExpectedSubjectFromRequest();
+	* if (expectedSubject && signet.isInvalidSubject(token, expectedSubject)) {
+	*   return response.status(403).send('Invalid subject');
+	* }
+	* ```
+	*/
+	isInvalidSubject(token, expected) {
+		if (!expected) return false;
+		const { sub } = this.#decode(token).payload;
+		return sub ? sub !== expected : false;
+	}
+	/**
+	* * Verifies a token's signature and validates all claims.
+	*
+	* @typeParam T - Type of custom data in the token payload.
+	* @param token - The token string to verify.
+	* @param options - Optional validation criteria for token claims.
+	*
+	* @returns A {@link VerifiedToken} object indicating success or failure.
+	*          - If valid: `{ isValid: true, payload: SignetPayload<T> }`
+	*          - If invalid: `{ isValid: false, error: string }`
+	*
+	* @remarks
+	* - **Performs the following checks in order:**
+	*   - Token structure (3 parts separated by dots)
+	*   - Base64 decoding of header and payload
+	*   - JSON parsing of header and payload
+	*   - Signature verification (constant-time comparison)
+	*   - Expiration check (if `exp` claim exists)
+	*   - Not-before check (if `nbf` claim exists)
+	*   - Issuer validation (if provided in options)
+	*   - Audience validation (if provided in options)
+	*   - Subject validation (if provided in options)
+	*
+	* - **This is the recommended method for most token validation scenarios.**
+	*
+	* @example
+	* ```typescript
+	* // Basic verification
+	* const result = signet.verify(token);
+	* if (result.isValid) {
+	*   console.log('Valid token:', result.payload);
+	* } else {
+	*   console.log('Invalid token:', result.error);
+	* }
+	*
+	* // With claim validation
+	* const result = signet.verify(token, {
+	*   audience: 'api.example.com',
+	*   issuer: 'auth-service',
+	*   subject: 'user-123'
+	* });
+	*
+	* // Type-safe custom payload
+	* interface UserToken {
+	*   userId: number;
+	*   role: string;
+	* }
+	* const result = signet.verify<UserToken>(token);
+	* if (result.isValid) {
+	*   const { userId, role } = result.payload;
+	*   // userId and role are typed
+	* }
+	* ```
+	*/
+	verify(token, options) {
+		try {
+			const { signature, signingInput, payload } = this.#decode(token);
+			const { audience, issuer, subject } = options || {};
+			if (!_constantTimeEquals(signature, bytesToBase64(hmacSha256(this.#secretBytes, utf8ToBytes(signingInput))))) throw new Error("Invalid or tampered signature!");
+			if (this.hasExpired(token)) throw new Error("Token has expired!");
+			if (this.isTooEarly(token)) throw new Error("Token is not active yet!");
+			if (this.isInvalidIssuer(token, issuer)) throw new Error("Invalid token issuer!");
+			if (this.isInvalidAudience(token, audience)) throw new Error("Invalid token audience(s!");
+			if (this.isInvalidSubject(token, subject)) throw new Error("Invalid token subject!");
+			return {
+				isValid: true,
+				payload
+			};
+		} catch (e) {
+			return {
+				isValid: false,
+				error: e instanceof Error ? e.message : String(e)
+			};
+		}
+	}
+	/**
+	* * Verifies a token and throws an error if invalid.
+	*
+	* @typeParam T - Type of custom data in the token payload.
+	* @param token - The token string to verify.
+	* @param options - Optional validation criteria for token claims.
+	*
+	* @returns A valid {@link VerifiedToken} with `isValid: true`.
+	*
+	* @throws If the token is invalid, with a message describing the failure.
+	*
+	* @remarks
+	* - This method is a convenience wrapper around {@link verify} that throws instead of returning an error object.
+	* - Useful for `express`-style middleware or when you want to handle authentication failures with exceptions.
+	* - The thrown error message is the same as the `error` property in the invalid result from {@link verify}.
+	*
+	* @example
+	* ```typescript
+	* // Use in middleware/guard
+	* function authMiddleware(req, res, next) {
+	*   const token = req.headers.authorization?.replace('Bearer ', '');
+	*
+	*   try {
+	*     const result = signet.verifyOrThrow(token, {
+	*       audience: 'api.example.com'
+	*     });
+	*     req.user = result.payload;
+	*     next();
+	*   } catch (error) {
+	*     res.status(401).json({ error: error.message });
+	*   }
+	* }
+	*
+	* // In application code
+	* try {
+	*   const result = signet.verifyOrThrow(token);
+	*   // Token is guaranteed valid here
+	*   processUserRequest(result.payload);
+	* } catch (error) {
+	*   handleAuthError(error);
+	* }
+	* ```
+	*/
+	verifyOrThrow(token, options) {
+		const res = this.verify(token, options);
+		if (!res.isValid) throw new Error(res.error || "Invalid, malformed or expired token!");
+		return res;
+	}
+	/**
+	* * Extracts only the payload from a token without full verification.
+	*
+	* @typeParam T - Type of custom data in the token payload.
+	* @param token - The token string to decode.
+	*
+	* @returns The token payload including standard claims and custom data.
+	*
+	* @throws If the token is malformed, empty, or cannot be parsed.
+	*
+	* @remarks
+	* - This is a convenience method equivalent to `decode(token).payload`.
+	*
+	* - **Security Note:** This method does NOT verify the token signature.
+	*
+	* - **Only use it when:**
+	*   - You've already verified the token elsewhere
+	*   - The token comes from a trusted source
+	*   - You're debugging or logging
+	*   - The operation is not security-critical
+	*
+	* - For security-sensitive operations, always use {@link verify} or {@link verifyOrThrow} method.
+	*
+	* @example
+	* ```typescript
+	* // Quick payload extraction for non-critical operations
+	* const payload = signet.decodePayload(token);
+	* console.log('User ID:', payload.userId);
+	* console.log('Issued at:', payload.iatDate);
+	*
+	* // Type-safe with custom interface
+	* interface AppToken {
+	*   userId: number;
+	*   permissions: string[];
+	* }
+	* const payload = signet.decodePayload<AppToken>(token);
+	* const canDelete = payload.permissions.includes('delete');
+	* ```
+	*/
+	decodePayload(token) {
+		return this.#decode(token).payload;
+	}
+};
+
+//#endregion
+//#region src/hash/TextCodec.ts
+/**
+* @class `TextCodec` provides **UTF-8–safe** conversions between `text`, `hex`, `binary`, and `Base64` representations using byte-level transformations.
+*
+* @example
+* TextCodec.utf8ToHex('ভাষা'); // 'e0 a6 ad e0 a6 be e0 a6 b7 e0 a6 be'
+* TextCodec.hexToUtf8('e0 a6 ad e0 a6 be'); // 'ভা'
+*/
+var TextCodec = class {
+	constructor() {}
+	/**
+	* @static Validates whether a string represents a valid hexadecimal byte sequence.
+	*
+	* @param hex - Hex string, spaced or un-spaced (e.g. "ff 0a" or "ff0a")
+	* @returns `true` if the input is valid hex byte string
+	*
+	* @example
+	* TextCodec.isValidHex('ff 0a');
+	*/
+	static isValidHex(hex) {
+		return require_specials.isHexString(hex);
+	}
+	/**
+	* @static Validates whether a string represents a valid binary byte sequence.
+	*
+	* @param binary - Binary string, spaced or un-spaced
+	* @returns `true` if the input is valid binary byte string
+	*
+	* @example
+	* TextCodec.isValidBinary('01000001');
+	*/
+	static isValidBinary(binary) {
+		return require_specials.isBinaryString(binary);
+	}
+	/**
+	* @static Validates whether a string represents a valid Base64-encoded string.
+	*
+	* @param b64 - Base64 string to check
+	* @returns `true` if the input is valid Base64-encoded string
+	*
+	* @example
+	* TextCodec.isValidBase64('SGVsbG8=');
+	*/
+	static isValidBase64(b64) {
+		return require_specials.isBase64(b64);
+	}
+	/**
+	* @static Converts UTF-8 text into hexadecimal byte representation.
+	*
+	* @param text - UTF-8 text to convert
+	* @param spaced - Whether to separate bytes with spaces, defaults to `true`
+	* @returns Hexadecimal byte string
+	*
+	* @example
+	* TextCodec.utf8ToHex('Hi');
+	*/
+	static utf8ToHex(text, spaced = true) {
+		return [...utf8ToBytes(text)].map((b) => _padStartWith0(b, "hex")).join(spaced ? " " : "");
+	}
+	/**
+	* @static Converts UTF-8 text into binary byte representation.
+	*
+	* @param text - UTF-8 text to convert
+	* @param spaced - Whether to separate bytes with spaces, defaults to `true`
+	* @returns Binary byte string
+	*
+	* @example
+	* TextCodec.utf8ToBinary('A');
+	*/
+	static utf8ToBinary(text, spaced = true) {
+		return [...utf8ToBytes(text)].map((b) => _padStartWith0(b, "binary")).join(spaced ? " " : "");
+	}
+	/**
+	* @static Converts hexadecimal byte string into UTF-8 text.
+	*
+	* @param hex - Hexadecimal byte string
+	* @returns Decoded UTF-8 text
+	*
+	* @example
+	* TextCodec.hexToUtf8('48 69');
+	*/
+	static hexToUtf8(hex) {
+		return bytesToUtf8(hexToBytes(hex));
+	}
+	/**
+	* @static Converts binary byte string into UTF-8 text.
+	*
+	* @param binary - Binary byte string
+	* @returns Decoded UTF-8 text
+	*
+	* @example
+	* TextCodec.binaryToUtf8('01001000 01101001');
+	*/
+	static binaryToUtf8(binary) {
+		if (!require_specials.isBinaryString(binary)) return "";
+		const bytes = _splitByCharLength(binary, 8).map((b) => parseInt(b, 2));
+		return bytesToUtf8(new Uint8Array(bytes));
+	}
+	/**
+	* @static Converts hexadecimal byte string into binary byte string.
+	*
+	* @param hex - Hexadecimal byte string
+	* @param spaced - Whether to separate bytes with spaces, defaults to `true`
+	* @returns Binary byte string
+	*
+	* @example
+	* TextCodec.hexToBinary('ff');
+	*/
+	static hexToBinary(hex, spaced = true) {
+		if (!require_specials.isHexString(hex)) return "";
+		return _splitByCharLength(hex, 2).map((h) => _padStartWith0(parseInt(h, 16), "binary")).join(spaced ? " " : "");
+	}
+	/**
+	* @static Converts binary byte string into hexadecimal byte string.
+	*
+	* @param binary - Binary byte string
+	* @param spaced - Whether to separate bytes with spaces, defaults to `true`
+	* @returns Hexadecimal byte string
+	*
+	* @example
+	* TextCodec.binaryToHex('00000001');
+	*/
+	static binaryToHex(binary, spaced = true) {
+		if (!require_specials.isBinaryString(binary)) return "";
+		return _splitByCharLength(binary, 8).map((b) => _padStartWith0(parseInt(b, 2), "hex")).join(spaced ? " " : "");
+	}
+	/**
+	* @static Converts a Base64-encoded string into UTF-8 text.
+	*
+	* @param b64 - Base64 encoded string
+	* @returns Decoded UTF-8 text
+	*
+	* @example
+	* TextCodec.base64ToUtf8('SGVsbG8=');
+	*/
+	static base64ToUtf8(b64) {
+		if (!require_specials.isBase64(b64)) return "";
+		return bytesToUtf8(base64ToBytes(b64));
+	}
+	/**
+	* @static Converts UTF-8 text into a Base64-encoded string.
+	*
+	* @param text - UTF-8 text to encode
+	* @returns Base64 encoded string
+	*
+	* @example
+	* TextCodec.utf8ToBase64('Hello');
+	*/
+	static utf8ToBase64(text) {
+		if (!require_primitives.isNonEmptyString(text)) return "";
+		return bytesToBase64(utf8ToBytes(text));
+	}
+	/**
+	* @static Converts Base64 directly into hexadecimal byte string.
+	*
+	* @param b64 - Base64 encoded string
+	* @param spaced - Whether to separate bytes with spaces, defaults to `true`
+	* @returns Hexadecimal byte string
+	*
+	* @example
+	* TextCodec.base64ToHex('SGVsbG8=');
+	*/
+	static base64ToHex(b64, spaced = true) {
+		return this.utf8ToHex(this.base64ToUtf8(b64), spaced);
+	}
+	/**
+	* @static Converts Base64 directly into binary byte string.
+	*
+	* @param b64 - Base64 encoded string
+	* @param spaced - Whether to separate bytes with spaces, defaults to `true`
+	* @returns Binary byte string
+	*
+	* @example
+	* TextCodec.base64ToBinary('SGVsbG8=');
+	*/
+	static base64ToBinary(b64, spaced = true) {
+		return this.utf8ToBinary(this.base64ToUtf8(b64), spaced);
+	}
+	/**
+	* @static Converts hexadecimal byte string into a Base64 string.
+	*
+	* @param hex - Hexadecimal byte string
+	* @returns Base64 encoded string
+	*
+	* @example
+	* TextCodec.hexToBase64('48 69');
+	*/
+	static hexToBase64(hex) {
+		return this.utf8ToBase64(this.hexToUtf8(hex));
+	}
+	/**
+	* @static Converts binary byte string into a Base64 string.
+	*
+	* @param binary - Binary byte string
+	* @returns Base64 encoded string
+	*
+	* @example
+	* TextCodec.binaryToBase64('01001000 01101001');
+	*/
+	static binaryToBase64(binary) {
+		return this.utf8ToBase64(this.binaryToUtf8(binary));
+	}
+};
+
+//#endregion
+//#region src/hash/uuid.ts
+/**
+* * Generates UUIDs across all major RFC-compliant versions (1, 3, 4, 5, 6, 7, 8), following standards from `RFC4122`. Default version is `v4`.
+*
+* - **Version behavior:**
+*   - `v1` → Timestamp & node-identifier–based
+*   - `v3` → MD5(namespace + name)
+*   - `v4` → Pure random (correct variant + version injection)
+*   - `v5` → SHA-1(namespace + name)
+*   - `v6` → Re-ordered timestamp variant of `v1` (lexicographically sortable)
+*   - `v7` → Unix-time–based, monotonic-friendly
+*   - `v8` → Custom layout, '“Future'` variant (timestamp + randomness)
+*
+* @param options Controls version, formatting, and required fields for `v3` and `v5`.
+* @returns A 5-parts UUID string formatted with correct version/variant bits.
+*
+* @example
+* // Generate a random UUID v4
+* const id = uuid();
+*
+* @example
+* // Generate uppercase v7
+* const id = uuid({ version: 'v7', uppercase: true });
+*
+* @example
+* // Generate v5 UUID
+* const id = uuid({
+*   version: 'v5',
+*   namespace: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+*   name: 'example'
+* });
+*
+* @remarks
+* - This utility provides a complete, engine-agnostic UUID generator with full RFC compliance, predictable formatting, and reliable uniqueness characteristics, suitable for browsers, Node.js, and restricted JavaScript runtimes.
+* - **Notes**
+*   - `v1` and `v6` use a generated pseudo-node identifier.
+*   - `v4` and `v8` uses {@link Math.random} when {@link crypto.getRandomValues} is unavailable, ensuring broad compatibility.
+*   - `v3` and `v5` use internal `MD5`/`SHA-1` implementations and remain fully deterministic.
+*   - `v7` **do not rely on crypto APIs**, preserving engine-agnostic behavior.
+*
+* - **Limitations**
+*   - `v1`/`v6`: Node identifier is pseudo-random, not derived from real MAC addresses (for privacy).
+*   - `v3`/`v5`: Hash algorithms (`MD5`/`SHA-1`) follow RFC specs but are not cryptographically secure.
+*   - `v7`: Millisecond precision; extremely high throughput may still cause rare collisions.
+*   - `v8`: Uses a simple timestamp + randomness layout; custom layouts are not supported here.
+*
+* - Use {@link https://toolbox.nazmul-nhb.dev/docs/utilities/string/generateRandomID generateRandomID} for customized id generation or {@link https://toolbox.nazmul-nhb.dev/docs/utilities/hash/randomHex randomHex} for hex-only random string with custom length.
+*/
+function uuid(options) {
+	const { version = "v4", uppercase = false } = options || {};
+	switch (version) {
+		case "v1": {
+			const timestamp = _uuidTimestamp().toString(16).padStart(15, "0");
+			const vTimeHigh = (parseInt(timestamp.slice(0, -12).padStart(3, "0"), 16) | 4096).toString(16).padStart(4, "0");
+			const clockSeq = _clockSeq14();
+			const clockSeqHi = (parseInt(clockSeq.slice(0, 2), 16) & 63 | 128).toString(16).padStart(2, "0");
+			return _formatUUID(timestamp.slice(-8) + timestamp.slice(-12, -8) + vTimeHigh + clockSeqHi + clockSeq.slice(2) + _randomNode48(), 1, uppercase);
+		}
+		case "v3":
+			if (_isOptionV3V5(options)) return _formatUUID(md5(options.namespace + options.name), 3, uppercase);
+			throw new Error("v3 requires valid namespace (uuid) and name!");
+		case "v4": return _formatUUID(_bytesToRandomHex(new Uint8Array(16)), 4, uppercase);
+		case "v5":
+			if (_isOptionV3V5(options)) return _formatUUID(sha1(options.namespace + options.name).slice(0, 32), 5, uppercase);
+			throw new Error("v5 requires valid namespace (uuid) and name!");
+		case "v6": {
+			const timestamp = _uuidTimestamp().toString(16).padStart(15, "0");
+			const vTimeLow = (parseInt(timestamp.slice(12).padStart(3, "0"), 16) | 24576).toString(16).padStart(4, "0");
+			const clockSeq = _clockSeq14();
+			const clockSeqHi = (parseInt(clockSeq.slice(0, 2), 16) & 63 | 128).toString(16).padStart(2, "0");
+			return _formatUUID(timestamp.slice(0, 8) + timestamp.slice(8, 12) + vTimeLow + clockSeqHi + clockSeq.slice(2) + _randomNode48(), 6, uppercase);
+		}
+		case "v7": return _formatUUID(Date.now().toString(16).padStart(12, "0") + randomHex(20), 7, uppercase);
+		case "v8": {
+			const ts = BigInt(Date.now());
+			const bytes = new Uint8Array(16);
+			let temp = ts;
+			for (let i = 5; i >= 0; i--) {
+				bytes[i] = Number(temp & 255n);
+				temp >>= 8n;
+			}
+			return _formatUUID(_bytesToRandomHex(bytes), 8, uppercase);
+		}
+		default: throw new RangeError("Unsupported UUID version!");
+	}
+}
+/**
+* * Decodes a UUID into its internal components, including version, variant, timestamps for time-based UUIDs and other metadata.
+*   - Supports `RFC4122` UUID versions: 1-8.
+*
+* @param uuid The UUID string to decode.
+* @returns A structured `DecodedUUID` object, or `null` for invalid UUIDs.
+*
+* @example
+* const info = decodeUUID("f47ac10b-58cc-4372-a567-0e02b2c3d479");
+*
+* @example
+* const info = decodeUUID(uuid({ version: "v1" }));
+*
+* @remarks
+* - Provides a cross-runtime UUID decoder covering essential metadata and timestamp interpretation for time-ordered UUID versions.
+* - **Notes**
+*   - `v1/v6` timestamps are converted from the UUID epoch (1582-10-15) to standard Unix milliseconds.
+*   - `v6` timestamps are lexicographically sortable and decoded accordingly.
+*   - `v7` timestamps map directly to Unix time (48-bit millisecond precision).
+*   - `v8` decoding is minimal because layouts are intentionally user-defined.
+*
+* - **Limitations**
+*   - `v2` decoding is not implemented specifically.
+*   - `v8` decoding only returns timestamp if it matches a known layout.
+*   - `v3/v5` hash UUIDs contain no timestamp information.
+*/
+function decodeUUID(uuid) {
+	if (!require_specials.isUUID(uuid)) return null;
+	const plain = uuid.replace(/-/g, "");
+	const parts = uuid.toLowerCase().split("-");
+	const version = parseInt(parts[2][0], 16);
+	const variantNibble = parseInt(parts[3][0], 16);
+	let variant = "RFC4122";
+	if ((variantNibble & 8) === 0) variant = "NCS";
+	else if ((variantNibble & 12) === 8) variant = "RFC4122";
+	else if ((variantNibble & 14) === 12) variant = "Microsoft";
+	else variant = "Future";
+	const decoded = {
+		version,
+		variant,
+		raw: uuid,
+		plain,
+		singleInt: BigInt("0x" + plain)
+	};
+	const UUID_EPOCH_DIFF = 122192928000000000n;
+	if (version === 1 || version === 6) {
+		let tsHex = parts[2].slice(1) + parts[1] + parts[0];
+		if (version === 6) tsHex = parts[0] + parts[1] + parts[2].slice(1);
+		decoded.timestamp = Number((BigInt("0x" + tsHex) - UUID_EPOCH_DIFF) / 10000n);
+		decoded.node = parts[4];
+		return decoded;
+	}
+	if (version === 7 || version === 8) {
+		const tsHex = parts.join("").slice(0, 12);
+		decoded.variant = version === 7 ? "RFC4122" : "Future";
+		decoded.timestamp = parseInt(tsHex, 16);
+		return decoded;
+	}
+	return decoded;
+}
+/** Check if a value is UUID version 1 */
+function isUUIDv1(value) {
+	return _checkUUIDVersion(value, "1");
+}
+/** Check if a value is UUID version 2 */
+function isUUIDv2(value) {
+	return _checkUUIDVersion(value, "2");
+}
+/** Check if a value is UUID version 3 */
+function isUUIDv3(value) {
+	return _checkUUIDVersion(value, "3");
+}
+/** Check if a value is UUID version 4 */
+function isUUIDv4(value) {
+	return _checkUUIDVersion(value, "4");
+}
+/** Check if a value is UUID version 5 */
+function isUUIDv5(value) {
+	return _checkUUIDVersion(value, "5");
+}
+/** Check if a value is UUID version 6 */
+function isUUIDv6(value) {
+	return _checkUUIDVersion(value, "6");
+}
+/** Check if a value is UUID version 7 */
+function isUUIDv7(value) {
+	return _checkUUIDVersion(value, "7");
+}
+/** Check if a value is UUID version 8 */
+function isUUIDv8(value) {
+	return _checkUUIDVersion(value, "8");
+}
+
+//#endregion
+exports.Cipher = Cipher;
+exports.Signet = Signet;
+exports.TextCodec = TextCodec;
+exports.base64ToBytes = base64ToBytes;
+exports.bytesToBase64 = bytesToBase64;
+exports.bytesToHex = bytesToHex;
+exports.bytesToUtf8 = bytesToUtf8;
+exports.concatBytes = concatBytes;
+exports.decodeUUID = decodeUUID;
+exports.generateRandomID = require_basics.generateRandomID;
+exports.hexToBytes = hexToBytes;
+exports.hmacSha256 = hmacSha256;
+exports.intTo4BytesBE = intTo4BytesBE;
+exports.isUUID = require_specials.isUUID;
+exports.isUUIDv1 = isUUIDv1;
+exports.isUUIDv2 = isUUIDv2;
+exports.isUUIDv3 = isUUIDv3;
+exports.isUUIDv4 = isUUIDv4;
+exports.isUUIDv5 = isUUIDv5;
+exports.isUUIDv6 = isUUIDv6;
+exports.isUUIDv7 = isUUIDv7;
+exports.isUUIDv8 = isUUIDv8;
+exports.md5 = md5;
+exports.randomHex = randomHex;
+exports.randomID = require_basics.generateRandomID;
+exports.sha1 = sha1;
+exports.sha256 = sha256;
+exports.sha256Bytes = sha256Bytes;
+exports.uint8To32ArrayBE = uint8To32ArrayBE;
+exports.utf8ToBytes = utf8ToBytes;
+exports.uuid = uuid;