@stryke/hash 0.12.52 → 0.13.0

package/dist/node.mjs

@@ -0,0 +1,613 @@
+import defu from "defu";
+import { glob } from "glob";
+import { readFile } from "node:fs/promises";
+import { hash as hash$1 } from "ohash";
+import { xxHash32 as xxHash32$1 } from "js-xxhash";
+import { createHash } from "node:crypto";
+
+//#region ../type-checks/src/is-null.ts
+const isNull = (value) => {
+	try {
+		return value === null;
+	} catch {
+		return false;
+	}
+};
+
+//#endregion
+//#region ../type-checks/src/is-undefined.ts
+const isUndefined = (value) => {
+	return value === void 0;
+};
+
+//#endregion
+//#region ../type-checks/src/is-empty.ts
+/**
+* Check if the provided value's type is `null` or `undefined`
+*
+* @param value - The value to type check
+* @returns An indicator specifying if the value provided is of type `null` or `undefined`
+*/
+const isEmpty = (value) => {
+	try {
+		return isUndefined(value) || isNull(value);
+	} catch {
+		return false;
+	}
+};
+
+//#endregion
+//#region ../type-checks/src/is-buffer.ts
+const isBufferExists = typeof Buffer !== "undefined";
+/**
+* Check if the provided value's type is `Buffer`
+*/
+const isBuffer = isBufferExists ? Buffer.isBuffer.bind(Buffer) : function isBuffer$1(value) {
+	return false;
+};
+
+//#endregion
+//#region ../type-checks/src/type-detect.ts
+const globalObject = ((Obj) => {
+	if (typeof globalThis === "object") return globalThis;
+	Object.defineProperty(Obj, "typeDetectGlobalObject", {
+		get() {
+			return this;
+		},
+		configurable: true
+	});
+	return globalThis;
+})(Object.prototype);
+
+//#endregion
+//#region ../type-checks/src/is-string.ts
+const isString = (value) => {
+	try {
+		return typeof value === "string";
+	} catch {
+		return false;
+	}
+};
+
+//#endregion
+//#region ../type-checks/src/is-set.ts
+/**
+* The inverse of the `isEmpty` function
+*
+* @param value - The value to type check
+* @returns An indicator specifying if the value provided is **NOT** of type `null` or `undefined`
+*/
+const isSet = (value) => {
+	try {
+		return !isEmpty(value);
+	} catch {
+		return false;
+	}
+};
+
+//#endregion
+//#region ../type-checks/src/is-set-string.ts
+/**
+* Determine if the type is string and is not empty (length greater than zero)
+*
+* @param value - The value to type check
+* @returns An indicator specifying if the value provided is of type `string` and length greater than zero
+*/
+const isSetString = (value) => {
+	try {
+		return isSet(value) && isString(value) && value.length > 0;
+	} catch {
+		return false;
+	}
+};
+
+//#endregion
+//#region src/digest.ts
+/**
+* Creates a new hash object for the specified algorithm.
+*
+* @param algorithm - The algorithm to use for the hash.
+* @returns A new hash object.
+*/
+function createHasher(algorithm) {
+	return new Hasher(algorithm);
+}
+/**
+* Creates a new hash object for the specified algorithm.
+*
+* @remarks
+* This function uses the Web Crypto API to create a hash of the input data.
+*
+* @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest
+*
+* @param data - The data to hash.
+* @param algorithm - The algorithm to use for the hash.
+* @returns A hash string representation of the `data` parameter.
+*/
+async function digest(data, algorithm = "SHA-512") {
+	const encoder = new TextEncoder();
+	const arrayBuffer = await globalThis.crypto.subtle.digest(algorithm, isSetString(data) ? encoder.encode(data) : data);
+	return btoa(String.fromCharCode(...new Uint8Array(arrayBuffer))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+/**
+* Alias for {@link digest}.
+*/
+const hash = digest;
+/**
+* Hash a string or Uint8Array using SHA-256 and return the result as a base64url-encoded string.
+*
+* @param data - The data to hash.
+* @returns A hash string representation of the `data` parameter.
+*/
+const sha256 = async (data) => digest(data, "SHA-256");
+/**
+* Hash a string or Uint8Array using SHA-384 and return the result as a base64url-encoded string.
+*
+* @param data - The data to hash.
+* @returns A hash string representation of the `data` parameter.
+*/
+const sha384 = async (data) => digest(data, "SHA-384");
+/**
+* Hash a string or Uint8Array using SHA-512 and return the result as a base64url-encoded string.
+*
+* @param data - The data to hash.
+* @returns A hash string representation of the `data` parameter.
+*/
+const sha512 = async (data) => digest(data, "SHA-512");
+var Hasher = class {
+	#chunks = [];
+	#algorithm;
+	constructor(algorithm) {
+		this.#algorithm = algorithm;
+	}
+	update(data) {
+		this.#chunks.push(data);
+	}
+	async digest() {
+		const data = new Uint8Array(this.#chunks.reduce((acc, chunk) => acc + chunk.length, 0));
+		let offset = 0;
+		for (const chunk of this.#chunks) {
+			data.set(chunk, offset);
+			offset += chunk.length;
+		}
+		const arrayBuffer = await globalThis.crypto.subtle.digest(this.#algorithm, data);
+		return new Uint8Array(arrayBuffer);
+	}
+};
+
+//#endregion
+//#region src/etag.ts
+/**
+* FNV-1a Hash implementation
+*
+* Ported from https://github.com/tjwebb/fnv-plus/blob/master/index.js
+*
+* @remarks
+* Simplified, optimized and add modified for 52 bit, which provides a larger hash space
+* and still making use of Javascript's 53-bit integer space.
+*/
+const fnv1a52 = (str) => {
+	const len = str.length;
+	let i = 0;
+	let t0 = 0;
+	let v0 = 8997;
+	let t1 = 0;
+	let v1 = 33826;
+	let t2 = 0;
+	let v2 = 40164;
+	let t3 = 0;
+	let v3 = 52210;
+	while (i < len) {
+		v0 ^= str.charCodeAt(i++);
+		t0 = v0 * 435;
+		t1 = v1 * 435;
+		t2 = v2 * 435;
+		t3 = v3 * 435;
+		t2 += v0 << 8;
+		t3 += v1 << 8;
+		t1 += t0 >>> 16;
+		v0 = t0 & 65535;
+		t2 += t1 >>> 16;
+		v1 = t1 & 65535;
+		v3 = t3 + (t2 >>> 16) & 65535;
+		v2 = t2 & 65535;
+	}
+	return (v3 & 15) * 281474976710656 + v2 * 4294967296 + v1 * 65536 + (v0 ^ v3 >> 4);
+};
+/**
+* Generates an ETag for the given payload.
+*
+* @param payload - The payload to generate an ETag for.
+* @param weak - Whether to generate a weak ETag.
+* @returns The generated ETag.
+*/
+const generateETag = (payload, weak = false) => {
+	return `${(weak ? "W/\"" : "\"") + fnv1a52(payload).toString(36) + payload.length.toString(36)}"`;
+};
+
+//#endregion
+//#region ../json/src/canonical.ts
+/**
+* Converts a JavaScript value to a canonical JSON string representation. This function is used for signing JSON objects in a consistent way, ensuring that the same input will always produce the same output string. The canonicalization process includes:
+* - Sorting object keys in lexicographical order.
+* - Removing whitespace and line breaks.
+* - Representing primitive values (null, boolean, number, string) in their standard JSON format.
+* - Recursively applying these rules to nested objects and arrays.
+*
+* This function is designed to produce a deterministic string representation of a JSON value, which is essential for cryptographic signing and verification processes where the exact byte representation of the data must be consistent across different environments and implementations.
+*
+* @param obj - The JavaScript value to convert to a canonical JSON string.
+* @returns A canonical JSON string representation of the input value.
+*/
+function canonicalJson(obj) {
+	if (obj === null || obj === void 0) return "null";
+	if (typeof obj === "boolean" || typeof obj === "number") return JSON.stringify(obj);
+	if (typeof obj === "string") return JSON.stringify(obj);
+	if (Array.isArray(obj)) return `[${obj.map((item) => canonicalJson(item)).join(",")}]`;
+	if (typeof obj === "object") return `{${Object.keys(obj).sort().map((key) => {
+		const value = canonicalJson(obj[key]);
+		return `${JSON.stringify(key)}:${value}`;
+	}).join(",")}}`;
+	return "null";
+}
+
+//#endregion
+//#region ../path/src/regex.ts
+const DRIVE_LETTER_START_REGEX = /^[A-Z]:\//i;
+const DRIVE_LETTER_REGEX = /^[A-Z]:$/i;
+const UNC_REGEX = /^[/\\]{2}/;
+const ABSOLUTE_PATH_REGEX = /^[/\\](?![/\\])|^[/\\]{2}(?!\.)|^~[/\\]|^[A-Z]:[/\\]/i;
+
+//#endregion
+//#region ../path/src/is-type.ts
+/**
+* Check if the path is an absolute path.
+*
+* @param path - The path to check
+* @returns An indicator specifying if the path is an absolute path
+*/
+function isAbsolutePath(path) {
+	return ABSOLUTE_PATH_REGEX.test(slash(path));
+}
+/**
+* Check if the path is an absolute path.
+*
+* @remarks
+* This is an alias for {@link isAbsolutePath}.
+*
+* @param path - The path to check
+* @returns An indicator specifying if the path is an absolute path
+*/
+function isAbsolute(path) {
+	return isAbsolutePath(path);
+}
+
+//#endregion
+//#region ../path/src/slash.ts
+/**
+* Replace backslash to slash
+*
+* @param path - The string to replace
+* @returns The string with replaced backslashes
+*/
+function slash(path) {
+	if (path.startsWith("\\\\?\\")) return path;
+	return path.replace(/\\/g, "/");
+}
+
+//#endregion
+//#region ../path/src/join-paths.ts
+function normalizeWindowsPath(input = "") {
+	if (!input) return input;
+	return input.replace(/\\/g, "/").replace(DRIVE_LETTER_START_REGEX, (r) => r.toUpperCase());
+}
+function correctPaths(path) {
+	if (!path || path.length === 0) return ".";
+	path = normalizeWindowsPath(path);
+	const isUNCPath = path.match(UNC_REGEX);
+	const isPathAbsolute = isAbsolute(path);
+	const trailingSeparator = path[path.length - 1] === "/";
+	path = normalizeString(path, !isPathAbsolute);
+	if (path.length === 0) {
+		if (isPathAbsolute) return "/";
+		return trailingSeparator ? "./" : ".";
+	}
+	if (trailingSeparator) path += "/";
+	if (DRIVE_LETTER_REGEX.test(path)) path += "/";
+	if (isUNCPath) {
+		if (!isPathAbsolute) return `//./${path}`;
+		return `//${path}`;
+	}
+	return isPathAbsolute && !isAbsolute(path) ? `/${path}` : path;
+}
+/**
+* Joins all given path segments together using the platform-specific separator as a delimiter.
+*
+* @remarks
+* Multiple segments can be provided as separate arguments. The resulting path is normalized to remove any redundant or unnecessary segments.
+*
+* @example
+* ```ts
+* import { joinPaths } from 'stryke/path';
+*
+* const fullPath = joinPaths('folder1', 'folder2', '..', 'folder3', 'file.txt');
+* console.log(fullPath); // Output: 'folder1/folder3/file.txt'
+*
+* const absolutePath = joinPaths('/root', 'folder', '.', 'subfolder', 'file.txt');
+* console.log(absolutePath); // Output: '/root/folder/subfolder/file.txt'
+*
+* const windowsPath = joinPaths('C:\\', 'Users', 'Public', '..', 'Documents', 'file.txt');
+* console.log(windowsPath); // Output: 'C:/Users/Documents/file.txt'
+*
+* const uncPath = joinPaths('\\\\Server\\Share', 'Folder', 'File.txt');
+* console.log(uncPath); // Output: '//Server/Share/Folder/File.txt'
+* ```
+*
+* @param segments - The path segments to join.
+* @returns The joined and normalized path string.
+*/
+function joinPaths(...segments) {
+	let result = "";
+	for (const segment of segments) if (segment && slash(segment).replaceAll(/\//g, "") !== ".") {
+		if (result) if (slash(segment).replaceAll(/\//g, "") === "..") result = slash(result).replace(/\/+$/, "").replace(/\/*[^/]+$/, "");
+		else result = `${slash(result).replace(/\/+$/, "")}/${slash(segment).replace(/^\/+/, "")}`;
+		else if (slash(segment).replaceAll(/\//g, "") !== "..") result = segment;
+	}
+	return correctPaths(result);
+}
+/**
+* Resolves a string path, resolving '.' and '.' segments and allowing paths above the root.
+*
+* @param path - The path to normalize.
+* @param allowAboveRoot - Whether to allow the resulting path to be above the root directory.
+* @returns the normalized path string.
+*/
+function normalizeString(path, allowAboveRoot) {
+	let res = "";
+	let lastSegmentLength = 0;
+	let lastSlash = -1;
+	let dots = 0;
+	let char = null;
+	for (let index = 0; index <= path.length; ++index) {
+		if (index < path.length) char = path[index];
+		else if (char === "/") break;
+		else char = "/";
+		if (char === "/") {
+			if (lastSlash === index - 1 || dots === 1) {} else if (dots === 2) {
+				if (res.length < 2 || lastSegmentLength !== 2 || res[res.length - 1] !== "." || res[res.length - 2] !== ".") {
+					if (res.length > 2) {
+						const lastSlashIndex = res.lastIndexOf("/");
+						if (lastSlashIndex === -1) {
+							res = "";
+							lastSegmentLength = 0;
+						} else {
+							res = res.slice(0, lastSlashIndex);
+							lastSegmentLength = res.length - 1 - res.lastIndexOf("/");
+						}
+						lastSlash = index;
+						dots = 0;
+						continue;
+					} else if (res.length > 0) {
+						res = "";
+						lastSegmentLength = 0;
+						lastSlash = index;
+						dots = 0;
+						continue;
+					}
+				}
+				if (allowAboveRoot) {
+					res += res.length > 0 ? "/.." : "..";
+					lastSegmentLength = 2;
+				}
+			} else {
+				if (res.length > 0) res += `/${path.slice(lastSlash + 1, index)}`;
+				else res = path.slice(lastSlash + 1, index);
+				lastSegmentLength = index - lastSlash - 1;
+			}
+			lastSlash = index;
+			dots = 0;
+		} else if (char === "." && dots !== -1) ++dots;
+		else dots = -1;
+	}
+	return res;
+}
+
+//#endregion
+//#region ../fs/src/list-files.ts
+const DEFAULT_OPTIONS = { dot: true };
+/**
+* A files and directories listing helper function
+*
+* @param filesGlob - A glob pattern to match files
+* @returns A list of file paths
+*/
+async function list(filesGlob, options) {
+	return glob(isString(filesGlob) ? filesGlob.includes("*") ? filesGlob : joinPaths(filesGlob, "**/*") : filesGlob.input ? joinPaths(filesGlob.input, filesGlob.glob) : filesGlob.glob, defu(isString(filesGlob) ? {} : {
+		dot: filesGlob.dot,
+		ignore: filesGlob.ignore
+	}, options ?? {}, DEFAULT_OPTIONS));
+}
+/**
+* A file listing helper function
+*
+* @param filesGlob - A glob pattern to match files
+* @returns A list of file paths
+*/
+async function listFiles(filesGlob, options) {
+	const result = (await list(filesGlob, defu({ withFileTypes: true }, options ?? {}))).filter((ret) => ret.isFile());
+	if (!options?.withFileTypes) return result.map((file) => file.fullpath());
+	return result;
+}
+
+//#endregion
+//#region ../fs/src/read-file.ts
+/**
+* Read the given content to the given file path
+*
+* @param filePath - The file path to read to
+*/
+const readFile$1 = async (filePath) => {
+	if (!filePath) throw new Error("No file path provided to read data");
+	return readFile(filePath, { encoding: "utf8" });
+};
+
+//#endregion
+//#region src/murmurhash.ts
+/**
+* Use a [MurmurHash3](https://en.wikipedia.org/wiki/MurmurHash) based algorithm to hash any JS value into a string.
+*
+* @see https://github.com/ohash/ohash
+* @see https://en.wikipedia.org/wiki/MurmurHash
+*
+* @param content - The value to hash
+* @param  options - Hashing options
+* @returns A hashed string value
+*/
+function murmurhash(content, options) {
+	const result = hash$1(content);
+	const maxLength = options?.maxLength ?? 32;
+	return result.length > maxLength ? result.slice(0, maxLength) : result;
+}
+
+//#endregion
+//#region src/hash-files.ts
+/**
+* Hash a list of file paths into a string based on the file content
+*
+* @param files - The list of file paths to hash
+* @param  options - Hashing options
+* @returns A hashed string value
+*/
+async function hashFiles(files, options) {
+	const result = {};
+	await Promise.all(files.map(async (file) => {
+		result[file] = await readFile$1(file);
+	}));
+	return murmurhash(result, options);
+}
+/**
+* Hash a folder path into a string based on the file content
+*
+* @param directoryPath - The folder path to hash
+* @param  options - Hashing options. By default, the `node_modules`, `.git`, `.nx`, `.cache`, and `tmp` folders is ignored.
+* @returns A hashed string value
+*/
+async function hashDirectory(directoryPath, options = {}) {
+	options.ignore = options.ignore ?? [
+		"**/node_modules/**",
+		"**/.git/**",
+		"**/.nx/**",
+		"**/.cache/**",
+		"**/.storm/**",
+		"**/tmp/**"
+	];
+	return hashFiles(await listFiles(directoryPath, options), options);
+}
+
+//#endregion
+//#region src/pbkdf2.ts
+/**
+* Hash a password using PBKDF2 (Web Crypto compatible alternative to Argon2) with SHA-256, 100,000 iterations, and a random salt. The resulting hash is formatted as: `$pbkdf2-sha256$iterations$salt$hash`.
+*
+* @remarks
+* This function uses the Web Crypto API to perform password hashing. It generates a random salt for each password, and uses PBKDF2 with SHA-256 and 100,000 iterations to derive a secure hash. The output is a string that includes the algorithm, iteration count, salt, and hash, which can be stored in a database for later verification using the {@link verifyPassword} function.
+*
+* @param password - The password to hash.
+* @returns A promise that resolves to the hashed password string.
+*/
+async function hashPassword(password) {
+	const encoder = new TextEncoder();
+	const salt = crypto.getRandomValues(new Uint8Array(16));
+	const keyMaterial = await crypto.subtle.importKey("raw", encoder.encode(password), "PBKDF2", false, ["deriveBits"]);
+	const hash$2 = await crypto.subtle.deriveBits({
+		name: "PBKDF2",
+		salt,
+		iterations: 1e5,
+		hash: "SHA-256"
+	}, keyMaterial, 256);
+	return `$pbkdf2-sha256$100000$${btoa(String.fromCharCode(...salt))}$${btoa(String.fromCharCode(...new Uint8Array(hash$2)))}`;
+}
+/**
+* Verify a password against a stored hash in the format produced by {@link hashPassword}.
+*
+* @param password - The password to verify.
+* @param storedHash - The stored hash to verify against.
+* @returns A promise that resolves to true if the password is correct, false otherwise.
+*/
+async function verifyPassword(password, storedHash) {
+	const parts = storedHash.split("$");
+	if (parts.length !== 5 || parts[1] !== "pbkdf2-sha256" || !parts[2] || !parts[3] || !parts[4]) return false;
+	const iterations = Number.parseInt(parts[2], 10);
+	const salt = Uint8Array.from(atob(parts[3]), (c) => c.charCodeAt(0));
+	const expectedHash = parts[4];
+	const encoder = new TextEncoder();
+	const keyMaterial = await crypto.subtle.importKey("raw", encoder.encode(password), "PBKDF2", false, ["deriveBits"]);
+	const hash$2 = await crypto.subtle.deriveBits({
+		name: "PBKDF2",
+		salt,
+		iterations,
+		hash: "SHA-256"
+	}, keyMaterial, 256);
+	return btoa(String.fromCharCode(...new Uint8Array(hash$2))) === expectedHash;
+}
+
+//#endregion
+//#region src/xx-hash.ts
+/**
+* xxHash32 only computes 32-bit values. Run it n times with different seeds to
+* get a larger hash with better collision resistance.
+*
+* @param content - The string to hash
+* @param words - The number of 32-bit words to hash
+* @returns A 128-bit hash
+*/
+function _xxHash32(content, words) {
+	let hash$2 = 0n;
+	for (let i = 0; i < words; i++) hash$2 = (hash$2 << 32n) + BigInt(xxHash32$1(content, i));
+	return hash$2;
+}
+const xxHash32 = (s) => xxHash32$1(s, 0);
+const xxHash64 = (s) => _xxHash32(s, 2);
+const xxHash128 = (s) => _xxHash32(s, 4);
+
+//#endregion
+//#region src/hash-content.ts
+/**
+* Hash the content of a PDU (Protocol Data Unit) by removing the `signatures` and `unsigned` fields, then hashing the remaining content using SHA-256 and encoding it as a base64url string. This function is useful for generating a consistent hash of the PDU content that can be used for integrity verification or caching purposes, while ignoring any fields that may change due to signatures or unsigned data.
+*
+* @param content - The PDU content to hash, represented as a record of string keys and unknown values.
+* @returns A promise that resolves to a base64url-encoded string representing the hash of the PDU content.
+*/
+async function hashContent(content) {
+	const toHash = { ...content };
+	delete toHash.signatures;
+	delete toHash.unsigned;
+	return sha256(canonicalJson(toHash));
+}
+/**
+* Verify the hash of a PDU (Protocol Data Unit) content by hashing the content using the {@link hashContent} function and comparing it to an expected hash value. This function is useful for validating the integrity of the PDU content by ensuring that the computed hash matches the expected hash, which can be used to detect any tampering or corruption of the content.
+*
+* @param content - The PDU content to verify, represented as a record of string keys and unknown values.
+* @param expectedHash - The expected hash value to compare against, represented as a string.
+* @returns A promise that resolves to a boolean indicating whether the computed hash of the content matches the expected hash value (true if they match, false otherwise).
+*/
+async function verifyContent(content, expectedHash) {
+	return await hashContent(content) === expectedHash;
+}
+
+//#endregion
+//#region src/md5.ts
+/**
+* Generate an MD5 hash of the provided content.
+*
+* @param content - The content to hash.
+* @param length - The length of the hash to return.
+* @returns The generated MD5 hash.
+*/
+function md5(content, length = 32) {
+	return createHash("md5").update(content).digest("hex").slice(0, length);
+}
+
+//#endregion
+export { Hasher, createHasher, digest, fnv1a52, generateETag, hash, hashContent, hashDirectory, hashFiles, hashPassword, md5, murmurhash, sha256, sha384, sha512, verifyContent, verifyPassword, xxHash128, xxHash32, xxHash64 };
+//# sourceMappingURL=node.mjs.map