@resq-systems/security 1.0.5 → 2.0.0

package/lib/crypto.mjs

@@ -18,29 +18,25 @@ import { promisify } from "node:util";
 * limitations under the License.
 */
 /**
-* @file Security Utilities
-* @module utils/security
-* @author ResQ
-* @description Provides encryption, hashing, and security functions
-*              for compliance with SOC2, ISO 27001, NIST 800-53.
-*              Includes AES-256-GCM encryption, secure token generation,
-*              and PII masking utilities.
-* @compliance NIST 800-53 SC-28 (Protection of Information at Rest)
-* @compliance NIST 800-53 SC-13 (Cryptographic Protection)
+* @fileoverview Server-side cryptographic utilities — AES-256-GCM authenticated
+* encryption, SHA-256 hashing, secure token generation, and PII masking — guarded
+* by nominal branded types for keys, ciphertext, and masked output. Supports SOC 2,
+* ISO 27001, and NIST 800-53 SC-28 (data at rest) / SC-13 (cryptographic protection)
+* controls.
+*
+* @module @resq-systems/security/crypto
 */
 const scryptAsync = promisify(scrypt);
-/** AES-256-GCM encryption algorithm */
+/** AES-256-GCM encryption algorithm. */
 const ALGORITHM = "aes-256-gcm";
-/** Initialization vector length in bytes */
+/** Initialization vector length in bytes. */
 const IV_LENGTH = 16;
-/** Authentication tag length in bytes */
-const AUTH_TAG_LENGTH = 16;
-/** Salt length for key derivation */
+/** Salt length for key derivation, in bytes. */
 const SALT_LENGTH = 32;
-/** Derived key length (256 bits for AES-256) */
+/** Derived key length in bytes (256 bits for AES-256). */
 const KEY_LENGTH = 32;
 /** Minimum decoded byte length of a well-formed {@link Ciphertext} envelope. */
-const CIPHERTEXT_MIN_BYTES = SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH;
+const CIPHERTEXT_MIN_BYTES = 64;
 /**
 * Smart constructors for {@link EncryptionKey}. The runtime check is a
 * non-empty string — scrypt stretches any non-empty secret into a 256-bit
@@ -103,7 +99,13 @@ async function deriveKey(password, salt) {
 *   the salt/IV are recovered on decryption.
 *
 * @throws From the underlying Node crypto primitives if `encryptionKey`
-*   is empty or scrypt fails.
+*   is empty or scrypt fails. Failure surfaces as a rejected `Promise`,
+*   never a resolved error value.
+*
+* Draws from the platform CSPRNG (`randomBytes`) each call, so it is not
+* a pure function and its output is non-deterministic. There is no
+* `AbortSignal` hook — once awaited the scrypt work runs to completion.
+* Independent calls share no state and are safe to run concurrently.
 *
 * @compliance NIST 800-53 SC-28 (Protection of Information at Rest),
 *   SC-13 (Cryptographic Protection).
@@ -143,7 +145,9 @@ async function encryptData(plaintext, encryptionKey) {
 *
 * @throws Error if the tag does not verify (wrong key, modified
 *   ciphertext, truncated payload). Catch this and treat it as a
-*   security event, not a recoverable error.
+*   security event, not a recoverable error. The rejection comes back
+*   as a rejected `Promise`. No `AbortSignal` is honoured; concurrent
+*   calls are independent and share no state.
 *
 * @example
 * ```ts
@@ -153,10 +157,11 @@ async function encryptData(plaintext, encryptionKey) {
 async function decryptData(encryptedData, encryptionKey) {
 	const combined = Buffer.from(encryptedData, "base64");
 	const salt = combined.subarray(0, SALT_LENGTH);
-	const iv = combined.subarray(SALT_LENGTH, SALT_LENGTH + IV_LENGTH);
-	const authTag = combined.subarray(SALT_LENGTH + IV_LENGTH, SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH);
-	const ciphertext = combined.subarray(SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH);
-	const decipher = createDecipheriv(ALGORITHM, await deriveKey(encryptionKey, salt), iv);
+	const iv = combined.subarray(SALT_LENGTH, 48);
+	const authTag = combined.subarray(48, 64);
+	const ciphertext = combined.subarray(64);
+	const key = await deriveKey(encryptionKey, salt);
+	const decipher = createDecipheriv(ALGORITHM, key, iv);
 	decipher.setAuthTag(authTag);
 	return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
 }
@@ -259,8 +264,14 @@ function maskEmail(email) {
 *   key, e.g. `"token"` matches `"refreshToken"` and `"id_token"`.
 *
 * @returns A new object with sensitive fields redacted and emails
-*   masked. Nested objects are recursed; arrays and primitives pass
-*   through unchanged.
+*   masked. Any non-null object value is recursed and comes back as a
+*   plain object keyed by its enumerable own properties — so arrays
+*   return as index-keyed objects (`["a"]` → `{ "0": "a" }`) and class
+*   instances / `Date`s lose their prototype. Only primitives, `null`,
+*   and `undefined` pass through unchanged.
+*
+* @throws {RangeError} On a circular reference — recursion has no cycle
+*   guard, so a self-referential object overflows the call stack.
 *
 * @example
 * ```ts

package/lib/crypto.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.mjs","names":[],"sources":["../src/crypto.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @file Security Utilities\n * @module utils/security\n * @author ResQ\n * @description Provides encryption, hashing, and security functions\n *              for compliance with SOC2, ISO 27001, NIST 800-53.\n *              Includes AES-256-GCM encryption, secure token generation,\n *              and PII masking utilities.\n * @compliance NIST 800-53 SC-28 (Protection of Information at Rest)\n * @compliance NIST 800-53 SC-13 (Cryptographic Protection)\n */\n\nimport {\n\ttype Brand,\n\tbrandRefiner,\n\ttype PositiveInt,\n\ttoPositiveInt,\n\tunsafeBrand,\n} from \"@resq-systems/types\";\nimport { createCipheriv, createDecipheriv, createHash, randomBytes, scrypt } from \"node:crypto\";\nimport { promisify } from \"node:util\";\n\nconst scryptAsync = promisify(scrypt);\n\n/** AES-256-GCM encryption algorithm */\nconst ALGORITHM = \"aes-256-gcm\";\n/** Initialization vector length in bytes */\nconst IV_LENGTH = 16;\n/** Authentication tag length in bytes */\nconst AUTH_TAG_LENGTH = 16;\n/** Salt length for key derivation */\nconst SALT_LENGTH = 32;\n/** Derived key length (256 bits for AES-256) */\nconst KEY_LENGTH = 32;\n\n// ============================================\n// Nominal (branded) types\n// ============================================\n\n/**\n * Base64 AES-256-GCM payload produced by {@link encryptData} — the\n * `salt | iv | authTag | ciphertext` envelope. Only {@link decryptData}\n * should consume a value of this type; read one back from storage through\n * {@link toCiphertext}.\n */\nexport type Ciphertext = Brand<string, \"Ciphertext\">;\n\n/**\n * A secret accepted by {@link encryptData}/{@link decryptData} as the\n * scrypt password. Mint one at the boundary where the secret enters the\n * process (typically from `process.env`) via {@link toEncryptionKey}.\n */\nexport type EncryptionKey = Brand<string, \"EncryptionKey\">;\n\n/** Cryptographically random hex token minted by {@link generateSecureToken}. */\nexport type SecureToken = Brand<string, \"SecureToken\">;\n\n/** Lowercase 64-char SHA-256 hex digest produced by {@link hashData}. */\nexport type Sha256Hex = Brand<string, \"Sha256Hex\">;\n\n/** A PII string masked for safe logging by {@link maskPII}/{@link maskEmail}. */\nexport type Masked = Brand<string, \"Masked\">;\n\n/** Minimum decoded byte length of a well-formed {@link Ciphertext} envelope. */\nconst CIPHERTEXT_MIN_BYTES = SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH;\n\n/**\n * Smart constructors for {@link EncryptionKey}. The runtime check is a\n * non-empty string — scrypt stretches any non-empty secret into a 256-bit\n * key, so entropy is the caller's responsibility, but an empty key is\n * always a bug.\n */\nconst EncryptionKeyBrand = brandRefiner<string, \"EncryptionKey\">(\n\t(value) => value.length > 0,\n\t\"encryption key\",\n);\n\n/** Type guard: `true` when `value` is a usable {@link EncryptionKey}. */\nexport const isEncryptionKey = EncryptionKeyBrand.is;\n/** Assert `value` is a non-empty secret and brand it, throwing otherwise. */\nexport const toEncryptionKey = EncryptionKeyBrand.from;\n/** Return `value` branded as an {@link EncryptionKey}, or `null` when empty. */\nexport const coerceEncryptionKey = EncryptionKeyBrand.coerce;\n/** Brand `value` as an {@link EncryptionKey} without checking. */\nexport const unsafeEncryptionKey = EncryptionKeyBrand.unsafe;\n\n/**\n * Smart constructors for {@link Ciphertext}. The runtime check verifies the\n * value base64-decodes to at least the fixed envelope header size — enough\n * to reject truncated or non-base64 input before it reaches\n * {@link decryptData}.\n */\nconst CiphertextBrand = brandRefiner<string, \"Ciphertext\">(\n\t(value) => value.length > 0 && Buffer.from(value, \"base64\").length >= CIPHERTEXT_MIN_BYTES,\n\t\"ciphertext\",\n);\n\n/** Type guard: `true` when `value` is a well-formed {@link Ciphertext} envelope. */\nexport const isCiphertext = CiphertextBrand.is;\n/** Assert `value` is a well-formed envelope and brand it, throwing otherwise. */\nexport const toCiphertext = CiphertextBrand.from;\n/** Return `value` branded as a {@link Ciphertext}, or `null` when malformed. */\nexport const coerceCiphertext = CiphertextBrand.coerce;\n/** Brand `value` as a {@link Ciphertext} without checking. */\nexport const unsafeCiphertext = CiphertextBrand.unsafe;\n\n/**\n * Derive a 32-byte (AES-256) key from a password and per-record salt\n * using scrypt with Node's default cost parameters.\n *\n * Internal helper — used inside the encrypt/decrypt round-trip because\n * the salt must travel alongside the ciphertext for decryption to\n * succeed.\n *\n * @internal\n */\nasync function deriveKey(password: string, salt: Buffer): Promise<Buffer> {\n\treturn (await scryptAsync(password, salt, KEY_LENGTH)) as Buffer;\n}\n\n/**\n * Encrypt a UTF-8 string with AES-256-GCM authenticated encryption.\n *\n * Each call generates a fresh random salt and IV — the same plaintext\n * encrypted twice with the same `encryptionKey` produces different\n * ciphertexts, which is the property you want for at-rest encryption.\n *\n * Output layout (base64-encoded): `salt(32) | iv(16) | authTag(16) | ciphertext(*)`.\n * The companion {@link decryptData} understands this layout.\n *\n * @param plaintext - UTF-8 string to encrypt.\n * @param encryptionKey - Caller-supplied secret. Treated as a password\n *   and stretched into a 256-bit AES key via scrypt; can be any length,\n *   though a high-entropy secret (≥ 32 bytes) is strongly preferred.\n *\n * @returns A self-contained base64 string. Store or transmit verbatim;\n *   the salt/IV are recovered on decryption.\n *\n * @throws From the underlying Node crypto primitives if `encryptionKey`\n *   is empty or scrypt fails.\n *\n * @compliance NIST 800-53 SC-28 (Protection of Information at Rest),\n *   SC-13 (Cryptographic Protection).\n *\n * @example\n * ```ts\n * const ct = await encryptData(\"user@example.com\", process.env.PII_KEY!);\n * await db.users.update(id, { email: ct });\n * ```\n */\nexport async function encryptData(\n\tplaintext: string,\n\tencryptionKey: EncryptionKey,\n): Promise<Ciphertext> {\n\tconst salt = randomBytes(SALT_LENGTH);\n\tconst key = await deriveKey(encryptionKey, salt);\n\tconst iv = randomBytes(IV_LENGTH);\n\n\tconst cipher = createCipheriv(ALGORITHM, key, iv);\n\tconst encrypted = Buffer.concat([cipher.update(plaintext, \"utf8\"), cipher.final()]);\n\tconst authTag = cipher.getAuthTag();\n\n\tconst combined = Buffer.concat([salt, iv, authTag, encrypted]);\n\treturn CiphertextBrand.unsafe(combined.toString(\"base64\"));\n}\n\n/**\n * Reverse {@link encryptData}. Verifies the GCM authentication tag\n * before returning plaintext — tampered ciphertexts throw.\n *\n * @param encryptedData - Base64 string produced by {@link encryptData}.\n * @param encryptionKey - Same key/password used to encrypt. Wrong keys\n *   throw an \"Unsupported state or unable to authenticate data\" error\n *   from Node — the authenticated tag failure is indistinguishable from\n *   tampering, by design.\n *\n * @returns The original UTF-8 plaintext.\n *\n * @throws Error if the tag does not verify (wrong key, modified\n *   ciphertext, truncated payload). Catch this and treat it as a\n *   security event, not a recoverable error.\n *\n * @example\n * ```ts\n * const plaintext = await decryptData(stored, process.env.PII_KEY!);\n * ```\n */\nexport async function decryptData(\n\tencryptedData: Ciphertext,\n\tencryptionKey: EncryptionKey,\n): Promise<string> {\n\tconst combined = Buffer.from(encryptedData, \"base64\");\n\n\tconst salt = combined.subarray(0, SALT_LENGTH);\n\tconst iv = combined.subarray(SALT_LENGTH, SALT_LENGTH + IV_LENGTH);\n\tconst authTag = combined.subarray(\n\t\tSALT_LENGTH + IV_LENGTH,\n\t\tSALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH,\n\t);\n\tconst ciphertext = combined.subarray(SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH);\n\n\tconst key = await deriveKey(encryptionKey, salt);\n\n\tconst decipher = createDecipheriv(ALGORITHM, key, iv);\n\tdecipher.setAuthTag(authTag);\n\n\tconst decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);\n\treturn decrypted.toString(\"utf8\");\n}\n\n/**\n * Compute a SHA-256 digest of a UTF-8 string and return it as lowercase\n * hex.\n *\n * **Not for password storage.** SHA-256 is fast by design — use a\n * deliberately slow KDF (`bcrypt`, `argon2`, or `scrypt`) for\n * password-equivalent material. This helper is intended for\n * non-reversible identifiers, content hashes, and idempotency keys.\n *\n * @param data - UTF-8 input.\n * @returns 64-character lowercase hex digest.\n *\n * @example\n * ```ts\n * hashData(\"hello\"); // → \"2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824\"\n * ```\n */\nexport function hashData(data: string): Sha256Hex {\n\treturn unsafeBrand<\"Sha256Hex\", string>(createHash(\"sha256\").update(data).digest(\"hex\"));\n}\n\n/**\n * Generate a cryptographically random hex token suitable for session\n * IDs, password-reset tokens, CSRF tokens, and similar single-use\n * secrets.\n *\n * @param length - Number of random *bytes* to draw as a {@link PositiveInt}\n *   (the returned hex string is twice as long). Default `32` ⇒ 64-char hex\n *   / 256 bits of entropy. Construct non-default lengths with `toPositiveInt`\n *   so zero-byte and negative lengths are unrepresentable.\n * @returns A {@link SecureToken}: lowercase hex string of length `length * 2`.\n *\n * @example\n * ```ts\n * import { toPositiveInt } from \"@resq-systems/types\";\n * generateSecureToken();                 // 64-char hex (256-bit entropy)\n * generateSecureToken(toPositiveInt(16)); // 32-char hex (128-bit entropy)\n * ```\n */\nexport function generateSecureToken(length: PositiveInt = toPositiveInt(32)): SecureToken {\n\treturn unsafeBrand<\"SecureToken\", string>(randomBytes(length).toString(\"hex\"));\n}\n\n/**\n * Mask an arbitrary PII string for safe logging — keeps the first two\n * and last two characters and replaces everything in between with\n * asterisks. Strings of length ≤ 4 are fully masked as `\"****\"`.\n *\n * @param data - Raw PII string.\n * @returns Masked representation safe for logs.\n *\n * @example\n * ```ts\n * maskPII(\"4242424242424242\"); // → \"42************42\"\n * maskPII(\"AB12\");              // → \"****\"\n * ```\n */\nexport function maskPII(data: string): Masked {\n\tif (data.length <= 4) {\n\t\treturn unsafeBrand<\"Masked\", string>(\"****\");\n\t}\n\treturn unsafeBrand<\"Masked\", string>(\n\t\t`${data.slice(0, 2)}${\"*\".repeat(data.length - 4)}${data.slice(-2)}`,\n\t);\n}\n\n/**\n * Mask an email address while preserving the domain — useful for\n * deduplication and support workflows where the domain is non-PII but\n * the local part identifies the user.\n *\n * @param email - Full email. Falls back to {@link maskPII} if the input\n *   does not contain a valid `local@domain` shape.\n * @returns Masked email; e.g. `\"j*****e@example.com\"`.\n *\n * @example\n * ```ts\n * maskEmail(\"jane@example.com\"); // → \"j**e@example.com\"\n * maskEmail(\"ab@example.com\");   // → \"**@example.com\"\n * maskEmail(\"not-an-email\");     // → \"no********il\" (maskPII fallback)\n * ```\n */\nexport function maskEmail(email: string): Masked {\n\tconst parts = email.split(\"@\");\n\tconst local = parts[0];\n\tconst domain = parts[1];\n\tif (!domain || !local) return maskPII(email);\n\tconst maskedLocal =\n\t\tlocal.length > 2\n\t\t\t? `${local[0]}${\"*\".repeat(local.length - 2)}${local[local.length - 1]}`\n\t\t\t: \"**\";\n\treturn unsafeBrand<\"Masked\", string>(`${maskedLocal}@${domain}`);\n}\n\n/**\n * Recursively shallow-copy an object, replacing any field whose key\n * contains a sensitive substring (case-insensitive) with `[REDACTED]`,\n * and masking string fields whose key contains `\"email\"` via\n * {@link maskEmail}.\n *\n * Designed for log structures — preserves shape so log queries continue\n * to work, but ensures secrets and identifiers don't leak. Use as a\n * defensive layer **before** writing structured log lines.\n *\n * @param obj - Object to sanitize. Original is not mutated.\n * @param sensitiveFields - Substring allow-list. Defaults to\n *   `[\"password\", \"passwordHash\", \"token\", \"secret\",\n *   \"twoFactorSecret\", \"apiKey\"]`. Substrings match anywhere in the\n *   key, e.g. `\"token\"` matches `\"refreshToken\"` and `\"id_token\"`.\n *\n * @returns A new object with sensitive fields redacted and emails\n *   masked. Nested objects are recursed; arrays and primitives pass\n *   through unchanged.\n *\n * @example\n * ```ts\n * sanitizeForLogging({\n *   id: 1,\n *   email: \"u@x.com\",\n *   apiKey: \"sk-...\",\n *   nested: { token: \"...\" },\n * });\n * // → { id: 1, email: \"u@x.com\" (masked), apiKey: \"[REDACTED]\", nested: { token: \"[REDACTED]\" } }\n * ```\n */\nexport function sanitizeForLogging(\n\tobj: Record<string, unknown>,\n\tsensitiveFields: string[] = [\n\t\t\"password\",\n\t\t\"passwordHash\",\n\t\t\"token\",\n\t\t\"secret\",\n\t\t\"twoFactorSecret\",\n\t\t\"apiKey\",\n\t],\n): Record<string, unknown> {\n\tconst sanitized: Record<string, unknown> = {};\n\n\tfor (const [key, value] of Object.entries(obj)) {\n\t\tif (sensitiveFields.some((field) => key.toLowerCase().includes(field.toLowerCase()))) {\n\t\t\tsanitized[key] = \"[REDACTED]\";\n\t\t} else if (key.toLowerCase().includes(\"email\") && typeof value === \"string\") {\n\t\t\tsanitized[key] = maskEmail(value);\n\t\t} else if (typeof value === \"object\" && value !== null) {\n\t\t\tsanitized[key] = sanitizeForLogging(value as Record<string, unknown>, sensitiveFields);\n\t\t} else {\n\t\t\tsanitized[key] = value;\n\t\t}\n\t}\n\n\treturn sanitized;\n}\n"],"mappings":"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"}
+{"version":3,"file":"crypto.mjs","names":[],"sources":["../src/crypto.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview Server-side cryptographic utilities — AES-256-GCM authenticated\n * encryption, SHA-256 hashing, secure token generation, and PII masking — guarded\n * by nominal branded types for keys, ciphertext, and masked output. Supports SOC 2,\n * ISO 27001, and NIST 800-53 SC-28 (data at rest) / SC-13 (cryptographic protection)\n * controls.\n *\n * @module @resq-systems/security/crypto\n */\n\nimport {\n\ttype Brand,\n\tbrandRefiner,\n\ttype PositiveInt,\n\ttoPositiveInt,\n\tunsafeBrand,\n} from \"@resq-systems/types\";\nimport { createCipheriv, createDecipheriv, createHash, randomBytes, scrypt } from \"node:crypto\";\nimport { promisify } from \"node:util\";\n\n//#region Constants\nconst scryptAsync = promisify(scrypt);\n\n/** AES-256-GCM encryption algorithm. */\nconst ALGORITHM = \"aes-256-gcm\";\n/** Initialization vector length in bytes. */\nconst IV_LENGTH = 16;\n/** Authentication tag length in bytes. */\nconst AUTH_TAG_LENGTH = 16;\n/** Salt length for key derivation, in bytes. */\nconst SALT_LENGTH = 32;\n/** Derived key length in bytes (256 bits for AES-256). */\nconst KEY_LENGTH = 32;\n//#endregion\n\n//#region Branded Types\n\n/**\n * Base64 AES-256-GCM payload produced by {@link encryptData} — the\n * `salt | iv | authTag | ciphertext` envelope. Only {@link decryptData}\n * should consume a value of this type; read one back from storage through\n * {@link toCiphertext}.\n */\nexport type Ciphertext = Brand<string, \"Ciphertext\">;\n\n/**\n * A secret accepted by {@link encryptData}/{@link decryptData} as the\n * scrypt password. Mint one at the boundary where the secret enters the\n * process (typically from `process.env`) via {@link toEncryptionKey}.\n */\nexport type EncryptionKey = Brand<string, \"EncryptionKey\">;\n\n/** Cryptographically random hex token minted by {@link generateSecureToken}. */\nexport type SecureToken = Brand<string, \"SecureToken\">;\n\n/** Lowercase 64-char SHA-256 hex digest produced by {@link hashData}. */\nexport type Sha256Hex = Brand<string, \"Sha256Hex\">;\n\n/** A PII string masked for safe logging by {@link maskPII}/{@link maskEmail}. */\nexport type Masked = Brand<string, \"Masked\">;\n\n/** Minimum decoded byte length of a well-formed {@link Ciphertext} envelope. */\nconst CIPHERTEXT_MIN_BYTES = SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH;\n\n/**\n * Smart constructors for {@link EncryptionKey}. The runtime check is a\n * non-empty string — scrypt stretches any non-empty secret into a 256-bit\n * key, so entropy is the caller's responsibility, but an empty key is\n * always a bug.\n */\nconst EncryptionKeyBrand = brandRefiner<string, \"EncryptionKey\">(\n\t(value) => value.length > 0,\n\t\"encryption key\",\n);\n\n/** Type guard: `true` when `value` is a usable {@link EncryptionKey}. */\nexport const isEncryptionKey = EncryptionKeyBrand.is;\n/** Assert `value` is a non-empty secret and brand it, throwing otherwise. */\nexport const toEncryptionKey = EncryptionKeyBrand.from;\n/** Return `value` branded as an {@link EncryptionKey}, or `null` when empty. */\nexport const coerceEncryptionKey = EncryptionKeyBrand.coerce;\n/** Brand `value` as an {@link EncryptionKey} without checking. */\nexport const unsafeEncryptionKey = EncryptionKeyBrand.unsafe;\n\n/**\n * Smart constructors for {@link Ciphertext}. The runtime check verifies the\n * value base64-decodes to at least the fixed envelope header size — enough\n * to reject truncated or non-base64 input before it reaches\n * {@link decryptData}.\n */\nconst CiphertextBrand = brandRefiner<string, \"Ciphertext\">(\n\t(value) => value.length > 0 && Buffer.from(value, \"base64\").length >= CIPHERTEXT_MIN_BYTES,\n\t\"ciphertext\",\n);\n\n/** Type guard: `true` when `value` is a well-formed {@link Ciphertext} envelope. */\nexport const isCiphertext = CiphertextBrand.is;\n/** Assert `value` is a well-formed envelope and brand it, throwing otherwise. */\nexport const toCiphertext = CiphertextBrand.from;\n/** Return `value` branded as a {@link Ciphertext}, or `null` when malformed. */\nexport const coerceCiphertext = CiphertextBrand.coerce;\n/** Brand `value` as a {@link Ciphertext} without checking. */\nexport const unsafeCiphertext = CiphertextBrand.unsafe;\n//#endregion\n\n//#region Internal\n\n/**\n * Derive a 32-byte (AES-256) key from a password and per-record salt\n * using scrypt with Node's default cost parameters.\n *\n * Internal helper — used inside the encrypt/decrypt round-trip because\n * the salt must travel alongside the ciphertext for decryption to\n * succeed.\n *\n * @internal\n */\nasync function deriveKey(password: string, salt: Buffer): Promise<Buffer> {\n\treturn (await scryptAsync(password, salt, KEY_LENGTH)) as Buffer;\n}\n//#endregion\n\n//#region Public API\n\n/**\n * Encrypt a UTF-8 string with AES-256-GCM authenticated encryption.\n *\n * Each call generates a fresh random salt and IV — the same plaintext\n * encrypted twice with the same `encryptionKey` produces different\n * ciphertexts, which is the property you want for at-rest encryption.\n *\n * Output layout (base64-encoded): `salt(32) | iv(16) | authTag(16) | ciphertext(*)`.\n * The companion {@link decryptData} understands this layout.\n *\n * @param plaintext - UTF-8 string to encrypt.\n * @param encryptionKey - Caller-supplied secret. Treated as a password\n *   and stretched into a 256-bit AES key via scrypt; can be any length,\n *   though a high-entropy secret (≥ 32 bytes) is strongly preferred.\n *\n * @returns A self-contained base64 string. Store or transmit verbatim;\n *   the salt/IV are recovered on decryption.\n *\n * @throws From the underlying Node crypto primitives if `encryptionKey`\n *   is empty or scrypt fails. Failure surfaces as a rejected `Promise`,\n *   never a resolved error value.\n *\n * Draws from the platform CSPRNG (`randomBytes`) each call, so it is not\n * a pure function and its output is non-deterministic. There is no\n * `AbortSignal` hook — once awaited the scrypt work runs to completion.\n * Independent calls share no state and are safe to run concurrently.\n *\n * @compliance NIST 800-53 SC-28 (Protection of Information at Rest),\n *   SC-13 (Cryptographic Protection).\n *\n * @example\n * ```ts\n * const ct = await encryptData(\"user@example.com\", process.env.PII_KEY!);\n * await db.users.update(id, { email: ct });\n * ```\n */\nexport async function encryptData(\n\tplaintext: string,\n\tencryptionKey: EncryptionKey,\n): Promise<Ciphertext> {\n\tconst salt = randomBytes(SALT_LENGTH);\n\tconst key = await deriveKey(encryptionKey, salt);\n\tconst iv = randomBytes(IV_LENGTH);\n\n\tconst cipher = createCipheriv(ALGORITHM, key, iv);\n\tconst encrypted = Buffer.concat([cipher.update(plaintext, \"utf8\"), cipher.final()]);\n\tconst authTag = cipher.getAuthTag();\n\n\tconst combined = Buffer.concat([salt, iv, authTag, encrypted]);\n\treturn CiphertextBrand.unsafe(combined.toString(\"base64\"));\n}\n\n/**\n * Reverse {@link encryptData}. Verifies the GCM authentication tag\n * before returning plaintext — tampered ciphertexts throw.\n *\n * @param encryptedData - Base64 string produced by {@link encryptData}.\n * @param encryptionKey - Same key/password used to encrypt. Wrong keys\n *   throw an \"Unsupported state or unable to authenticate data\" error\n *   from Node — the authenticated tag failure is indistinguishable from\n *   tampering, by design.\n *\n * @returns The original UTF-8 plaintext.\n *\n * @throws Error if the tag does not verify (wrong key, modified\n *   ciphertext, truncated payload). Catch this and treat it as a\n *   security event, not a recoverable error. The rejection comes back\n *   as a rejected `Promise`. No `AbortSignal` is honoured; concurrent\n *   calls are independent and share no state.\n *\n * @example\n * ```ts\n * const plaintext = await decryptData(stored, process.env.PII_KEY!);\n * ```\n */\nexport async function decryptData(\n\tencryptedData: Ciphertext,\n\tencryptionKey: EncryptionKey,\n): Promise<string> {\n\tconst combined = Buffer.from(encryptedData, \"base64\");\n\n\tconst salt = combined.subarray(0, SALT_LENGTH);\n\tconst iv = combined.subarray(SALT_LENGTH, SALT_LENGTH + IV_LENGTH);\n\tconst authTag = combined.subarray(\n\t\tSALT_LENGTH + IV_LENGTH,\n\t\tSALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH,\n\t);\n\tconst ciphertext = combined.subarray(SALT_LENGTH + IV_LENGTH + AUTH_TAG_LENGTH);\n\n\tconst key = await deriveKey(encryptionKey, salt);\n\n\tconst decipher = createDecipheriv(ALGORITHM, key, iv);\n\tdecipher.setAuthTag(authTag);\n\n\tconst decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);\n\treturn decrypted.toString(\"utf8\");\n}\n\n/**\n * Compute a SHA-256 digest of a UTF-8 string and return it as lowercase\n * hex.\n *\n * **Not for password storage.** SHA-256 is fast by design — use a\n * deliberately slow KDF (`bcrypt`, `argon2`, or `scrypt`) for\n * password-equivalent material. This helper is intended for\n * non-reversible identifiers, content hashes, and idempotency keys.\n *\n * @param data - UTF-8 input.\n * @returns 64-character lowercase hex digest.\n *\n * @example\n * ```ts\n * hashData(\"hello\"); // → \"2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824\"\n * ```\n */\nexport function hashData(data: string): Sha256Hex {\n\treturn unsafeBrand<\"Sha256Hex\", string>(createHash(\"sha256\").update(data).digest(\"hex\"));\n}\n\n/**\n * Generate a cryptographically random hex token suitable for session\n * IDs, password-reset tokens, CSRF tokens, and similar single-use\n * secrets.\n *\n * @param length - Number of random *bytes* to draw as a {@link PositiveInt}\n *   (the returned hex string is twice as long). Default `32` ⇒ 64-char hex\n *   / 256 bits of entropy. Construct non-default lengths with `toPositiveInt`\n *   so zero-byte and negative lengths are unrepresentable.\n * @returns A {@link SecureToken}: lowercase hex string of length `length * 2`.\n *\n * @example\n * ```ts\n * import { toPositiveInt } from \"@resq-systems/types\";\n * generateSecureToken();                 // 64-char hex (256-bit entropy)\n * generateSecureToken(toPositiveInt(16)); // 32-char hex (128-bit entropy)\n * ```\n */\nexport function generateSecureToken(length: PositiveInt = toPositiveInt(32)): SecureToken {\n\treturn unsafeBrand<\"SecureToken\", string>(randomBytes(length).toString(\"hex\"));\n}\n\n/**\n * Mask an arbitrary PII string for safe logging — keeps the first two\n * and last two characters and replaces everything in between with\n * asterisks. Strings of length ≤ 4 are fully masked as `\"****\"`.\n *\n * @param data - Raw PII string.\n * @returns Masked representation safe for logs.\n *\n * @example\n * ```ts\n * maskPII(\"4242424242424242\"); // → \"42************42\"\n * maskPII(\"AB12\");              // → \"****\"\n * ```\n */\nexport function maskPII(data: string): Masked {\n\tif (data.length <= 4) {\n\t\treturn unsafeBrand<\"Masked\", string>(\"****\");\n\t}\n\treturn unsafeBrand<\"Masked\", string>(\n\t\t`${data.slice(0, 2)}${\"*\".repeat(data.length - 4)}${data.slice(-2)}`,\n\t);\n}\n\n/**\n * Mask an email address while preserving the domain — useful for\n * deduplication and support workflows where the domain is non-PII but\n * the local part identifies the user.\n *\n * @param email - Full email. Falls back to {@link maskPII} if the input\n *   does not contain a valid `local@domain` shape.\n * @returns Masked email; e.g. `\"j*****e@example.com\"`.\n *\n * @example\n * ```ts\n * maskEmail(\"jane@example.com\"); // → \"j**e@example.com\"\n * maskEmail(\"ab@example.com\");   // → \"**@example.com\"\n * maskEmail(\"not-an-email\");     // → \"no********il\" (maskPII fallback)\n * ```\n */\nexport function maskEmail(email: string): Masked {\n\tconst parts = email.split(\"@\");\n\tconst local = parts[0];\n\tconst domain = parts[1];\n\tif (!domain || !local) return maskPII(email);\n\tconst maskedLocal =\n\t\tlocal.length > 2\n\t\t\t? `${local[0]}${\"*\".repeat(local.length - 2)}${local[local.length - 1]}`\n\t\t\t: \"**\";\n\treturn unsafeBrand<\"Masked\", string>(`${maskedLocal}@${domain}`);\n}\n\n/**\n * Recursively shallow-copy an object, replacing any field whose key\n * contains a sensitive substring (case-insensitive) with `[REDACTED]`,\n * and masking string fields whose key contains `\"email\"` via\n * {@link maskEmail}.\n *\n * Designed for log structures — preserves shape so log queries continue\n * to work, but ensures secrets and identifiers don't leak. Use as a\n * defensive layer **before** writing structured log lines.\n *\n * @param obj - Object to sanitize. Original is not mutated.\n * @param sensitiveFields - Substring allow-list. Defaults to\n *   `[\"password\", \"passwordHash\", \"token\", \"secret\",\n *   \"twoFactorSecret\", \"apiKey\"]`. Substrings match anywhere in the\n *   key, e.g. `\"token\"` matches `\"refreshToken\"` and `\"id_token\"`.\n *\n * @returns A new object with sensitive fields redacted and emails\n *   masked. Any non-null object value is recursed and comes back as a\n *   plain object keyed by its enumerable own properties — so arrays\n *   return as index-keyed objects (`[\"a\"]` → `{ \"0\": \"a\" }`) and class\n *   instances / `Date`s lose their prototype. Only primitives, `null`,\n *   and `undefined` pass through unchanged.\n *\n * @throws {RangeError} On a circular reference — recursion has no cycle\n *   guard, so a self-referential object overflows the call stack.\n *\n * @example\n * ```ts\n * sanitizeForLogging({\n *   id: 1,\n *   email: \"u@x.com\",\n *   apiKey: \"sk-...\",\n *   nested: { token: \"...\" },\n * });\n * // → { id: 1, email: \"u@x.com\" (masked), apiKey: \"[REDACTED]\", nested: { token: \"[REDACTED]\" } }\n * ```\n */\nexport function sanitizeForLogging(\n\tobj: Record<string, unknown>,\n\tsensitiveFields: string[] = [\n\t\t\"password\",\n\t\t\"passwordHash\",\n\t\t\"token\",\n\t\t\"secret\",\n\t\t\"twoFactorSecret\",\n\t\t\"apiKey\",\n\t],\n): Record<string, unknown> {\n\tconst sanitized: Record<string, unknown> = {};\n\n\tfor (const [key, value] of Object.entries(obj)) {\n\t\tif (sensitiveFields.some((field) => key.toLowerCase().includes(field.toLowerCase()))) {\n\t\t\tsanitized[key] = \"[REDACTED]\";\n\t\t} else if (key.toLowerCase().includes(\"email\") && typeof value === \"string\") {\n\t\t\tsanitized[key] = maskEmail(value);\n\t\t} else if (typeof value === \"object\" && value !== null) {\n\t\t\tsanitized[key] = sanitizeForLogging(value as Record<string, unknown>, sensitiveFields);\n\t\t} else {\n\t\t\tsanitized[key] = value;\n\t\t}\n\t}\n\n\treturn sanitized;\n}\n//#endregion\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,MAAM,cAAc,UAAU,MAAM;;AAGpC,MAAM,YAAY;;AAElB,MAAM,YAAY;;AAIlB,MAAM,cAAc;;AAEpB,MAAM,aAAa;;AA8BnB,MAAM,uBAAuB;;;;;;;AAQ7B,MAAM,qBAAqB,cACzB,UAAU,MAAM,SAAS,GAC1B,gBACD;;AAGA,MAAa,kBAAkB,mBAAmB;;AAElD,MAAa,kBAAkB,mBAAmB;;AAElD,MAAa,sBAAsB,mBAAmB;;AAEtD,MAAa,sBAAsB,mBAAmB;;;;;;;AAQtD,MAAM,kBAAkB,cACtB,UAAU,MAAM,SAAS,KAAK,OAAO,KAAK,OAAO,QAAQ,CAAC,CAAC,UAAU,sBACtE,YACD;;AAGA,MAAa,eAAe,gBAAgB;;AAE5C,MAAa,eAAe,gBAAgB;;AAE5C,MAAa,mBAAmB,gBAAgB;;AAEhD,MAAa,mBAAmB,gBAAgB;;;;;;;;;;;AAehD,eAAe,UAAU,UAAkB,MAA+B;CACzE,OAAQ,MAAM,YAAY,UAAU,MAAM,UAAU;AACrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,eAAsB,YACrB,WACA,eACsB;CACtB,MAAM,OAAO,YAAY,WAAW;CACpC,MAAM,MAAM,MAAM,UAAU,eAAe,IAAI;CAC/C,MAAM,KAAK,YAAY,SAAS;CAEhC,MAAM,SAAS,eAAe,WAAW,KAAK,EAAE;CAChD,MAAM,YAAY,OAAO,OAAO,CAAC,OAAO,OAAO,WAAW,MAAM,GAAG,OAAO,MAAM,CAAC,CAAC;CAClF,MAAM,UAAU,OAAO,WAAW;CAElC,MAAM,WAAW,OAAO,OAAO;EAAC;EAAM;EAAI;EAAS;CAAS,CAAC;CAC7D,OAAO,gBAAgB,OAAO,SAAS,SAAS,QAAQ,CAAC;AAC1D;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,eAAsB,YACrB,eACA,eACkB;CAClB,MAAM,WAAW,OAAO,KAAK,eAAe,QAAQ;CAEpD,MAAM,OAAO,SAAS,SAAS,GAAG,WAAW;CAC7C,MAAM,KAAK,SAAS,SAAS,aAAa,EAAuB;CACjE,MAAM,UAAU,SAAS,SACxB,IACA,EACD;CACA,MAAM,aAAa,SAAS,SAAS,EAAyC;CAE9E,MAAM,MAAM,MAAM,UAAU,eAAe,IAAI;CAE/C,MAAM,WAAW,iBAAiB,WAAW,KAAK,EAAE;CACpD,SAAS,WAAW,OAAO;CAG3B,OADkB,OAAO,OAAO,CAAC,SAAS,OAAO,UAAU,GAAG,SAAS,MAAM,CAAC,CAC/D,CAAC,CAAC,SAAS,MAAM;AACjC;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,SAAS,MAAyB;CACjD,OAAO,YAAiC,WAAW,QAAQ,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC;AACxF;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,oBAAoB,SAAsB,cAAc,EAAE,GAAgB;CACzF,OAAO,YAAmC,YAAY,MAAM,CAAC,CAAC,SAAS,KAAK,CAAC;AAC9E;;;;;;;;;;;;;;;AAgBA,SAAgB,QAAQ,MAAsB;CAC7C,IAAI,KAAK,UAAU,GAClB,OAAO,YAA8B,MAAM;CAE5C,OAAO,YACN,GAAG,KAAK,MAAM,GAAG,CAAC,IAAI,IAAI,OAAO,KAAK,SAAS,CAAC,IAAI,KAAK,MAAM,EAAE,GAClE;AACD;;;;;;;;;;;;;;;;;AAkBA,SAAgB,UAAU,OAAuB;CAChD,MAAM,QAAQ,MAAM,MAAM,GAAG;CAC7B,MAAM,QAAQ,MAAM;CACpB,MAAM,SAAS,MAAM;CACrB,IAAI,CAAC,UAAU,CAAC,OAAO,OAAO,QAAQ,KAAK;CAK3C,OAAO,YAA8B,GAHpC,MAAM,SAAS,IACZ,GAAG,MAAM,KAAK,IAAI,OAAO,MAAM,SAAS,CAAC,IAAI,MAAM,MAAM,SAAS,OAClE,KACgD,GAAG,QAAQ;AAChE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,mBACf,KACA,kBAA4B;CAC3B;CACA;CACA;CACA;CACA;CACA;AACD,GAC0B;CAC1B,MAAM,YAAqC,CAAC;CAE5C,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,GAAG,GAC5C,IAAI,gBAAgB,MAAM,UAAU,IAAI,YAAY,CAAC,CAAC,SAAS,MAAM,YAAY,CAAC,CAAC,GAClF,UAAU,OAAO;MACX,IAAI,IAAI,YAAY,CAAC,CAAC,SAAS,OAAO,KAAK,OAAO,UAAU,UAClE,UAAU,OAAO,UAAU,KAAK;MAC1B,IAAI,OAAO,UAAU,YAAY,UAAU,MACjD,UAAU,OAAO,mBAAmB,OAAkC,eAAe;MAErF,UAAU,OAAO;CAInB,OAAO;AACR"}

package/lib/hash.d.mts

@@ -15,22 +15,67 @@
  * limitations under the License.
  */
 /**
- * Hash a string using the FNV-1a algorithm.
+ * @fileoverview Fast, deterministic, non-cryptographic hashing helpers — a 32-bit
+ * string/buffer hash for cache keys and change detection, plus a lightweight string
+ * obfuscation transform. Not suitable for security-sensitive digests; use the
+ * SHA-256 helper in {@link @resq-systems/security/crypto} for those.
  *
- * Generates a deterministic hash value for a given string using a variant of the FNV-1a
- * (Fowler-Noll-Vo) algorithm. The hash is returned as a string representation of a 32-bit integer.
+ * @module @resq-systems/security/hash
+ */
+/**
+ * Compute a deterministic non-cryptographic 32-bit hash of a string.
+ *
+ * Uses the classic `hash * 31 + charCode` accumulation (expressed as
+ * `(hash << 5) - hash`), yielding the same value for the same input across runs.
+ * Intended for cache keys and change detection, not for security.
+ *
+ * @param string - The input to hash.
+ * @returns The signed 32-bit hash rendered as a decimal string.
+ *
+ * @example
+ * ```ts
+ * getHashForString("hello") === getHashForString("hello"); // → true
+ * ```
  */
 declare function getHashForString(string: string): string;
 /**
- * Hash an object by converting it to JSON and then hashing the resulting string.
+ * Hash an arbitrary value by serializing it to JSON and hashing the result.
+ *
+ * Key ordering follows `JSON.stringify`, so two structurally equal objects with
+ * differently ordered keys can hash differently.
+ *
+ * @param obj - Any JSON-serializable value.
+ * @returns The 32-bit hash of the serialized form, as a decimal string.
+ * @throws {TypeError} When `obj` cannot be serialized: a circular
+ *   reference or a `BigInt` makes `JSON.stringify` throw, and a value
+ *   that stringifies to `undefined` (a bare function, `symbol`, or
+ *   `undefined`) makes the downstream `.length` access throw.
  */
 declare function getHashForObject(obj: unknown): string;
 /**
- * Hash an ArrayBuffer using the FNV-1a algorithm.
+ * Compute a deterministic non-cryptographic 32-bit hash of an `ArrayBuffer`.
+ *
+ * Applies the same accumulation as {@link getHashForString} over each byte.
+ *
+ * @param buffer - The bytes to hash.
+ * @returns The signed 32-bit hash rendered as a decimal string.
  */
 declare function getHashForBuffer(buffer: ArrayBuffer): string;
 /**
- * Applies a string transformation algorithm that rearranges and modifies characters.
+ * Reversibly scramble a string by rotating character blocks and shifting digits.
+ *
+ * A lightweight, non-cryptographic obfuscation: it reorders characters via a fixed
+ * sequence of block rotations, reverses the result, and maps each digit `d` to
+ * `d < 5 ? d + 5 : d > 5 ? d - 5 : d`. Provides obscurity, not security — do not
+ * use it to protect secrets.
+ *
+ * Despite "scramble", the transform is **not a true inverse**: the digit map sends
+ * both `0` and `5` to `5`, so any input containing those digits cannot be
+ * recovered unambiguously. Non-digit characters (including whitespace) are only
+ * reordered, never substituted. Deterministic and free of side effects.
+ *
+ * @param str - The string to transform.
+ * @returns The transformed string, same length as `str`.
  */
 declare function lns(str: string): string;
 //#endregion

package/lib/hash.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.mts","names":[],"sources":["../src/hash.ts"],"mappings":";;AAsBA;;;;;AAYA;;;;;AAOA;;;;;AAaA;;;;;iBAhCgB,gBAAA,CAAiB,MAAA;;;;iBAYjB,gBAAA,CAAiB,GAAA;;;;iBAOjB,gBAAA,CAAiB,MAAA,EAAQ,WAAA;;;;iBAazB,GAAA,CAAI,GAAA"}
+{"version":3,"file":"hash.d.mts","names":[],"sources":["../src/hash.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCgB,iBAAiB;;;;;;;;;;;;;;iBAsBjB,iBAAiB;;;;;;;;;iBAYjB,iBAAiB,QAAQ;;;;;;;;;;;;;;;;;iBA0BzB,IAAI"}

package/lib/hash.mjs

@@ -15,10 +15,27 @@
 * limitations under the License.
 */
 /**
-* Hash a string using the FNV-1a algorithm.
+* @fileoverview Fast, deterministic, non-cryptographic hashing helpers — a 32-bit
+* string/buffer hash for cache keys and change detection, plus a lightweight string
+* obfuscation transform. Not suitable for security-sensitive digests; use the
+* SHA-256 helper in {@link @resq-systems/security/crypto} for those.
 *
-* Generates a deterministic hash value for a given string using a variant of the FNV-1a
-* (Fowler-Noll-Vo) algorithm. The hash is returned as a string representation of a 32-bit integer.
+* @module @resq-systems/security/hash
+*/
+/**
+* Compute a deterministic non-cryptographic 32-bit hash of a string.
+*
+* Uses the classic `hash * 31 + charCode` accumulation (expressed as
+* `(hash << 5) - hash`), yielding the same value for the same input across runs.
+* Intended for cache keys and change detection, not for security.
+*
+* @param string - The input to hash.
+* @returns The signed 32-bit hash rendered as a decimal string.
+*
+* @example
+* ```ts
+* getHashForString("hello") === getHashForString("hello"); // → true
+* ```
 */
 function getHashForString(string) {
 	let hash = 0;
@@ -29,13 +46,28 @@ function getHashForString(string) {
 	return `${hash}`;
 }
 /**
-* Hash an object by converting it to JSON and then hashing the resulting string.
+* Hash an arbitrary value by serializing it to JSON and hashing the result.
+*
+* Key ordering follows `JSON.stringify`, so two structurally equal objects with
+* differently ordered keys can hash differently.
+*
+* @param obj - Any JSON-serializable value.
+* @returns The 32-bit hash of the serialized form, as a decimal string.
+* @throws {TypeError} When `obj` cannot be serialized: a circular
+*   reference or a `BigInt` makes `JSON.stringify` throw, and a value
+*   that stringifies to `undefined` (a bare function, `symbol`, or
+*   `undefined`) makes the downstream `.length` access throw.
 */
 function getHashForObject(obj) {
 	return getHashForString(JSON.stringify(obj));
 }
 /**
-* Hash an ArrayBuffer using the FNV-1a algorithm.
+* Compute a deterministic non-cryptographic 32-bit hash of an `ArrayBuffer`.
+*
+* Applies the same accumulation as {@link getHashForString} over each byte.
+*
+* @param buffer - The bytes to hash.
+* @returns The signed 32-bit hash rendered as a decimal string.
 */
 function getHashForBuffer(buffer) {
 	const view = new DataView(buffer);
@@ -47,7 +79,20 @@ function getHashForBuffer(buffer) {
 	return `${hash}`;
 }
 /**
-* Applies a string transformation algorithm that rearranges and modifies characters.
+* Reversibly scramble a string by rotating character blocks and shifting digits.
+*
+* A lightweight, non-cryptographic obfuscation: it reorders characters via a fixed
+* sequence of block rotations, reverses the result, and maps each digit `d` to
+* `d < 5 ? d + 5 : d > 5 ? d - 5 : d`. Provides obscurity, not security — do not
+* use it to protect secrets.
+*
+* Despite "scramble", the transform is **not a true inverse**: the digit map sends
+* both `0` and `5` to `5`, so any input containing those digits cannot be
+* recovered unambiguously. Non-digit characters (including whitespace) are only
+* reordered, never substituted. Deterministic and free of side effects.
+*
+* @param str - The string to transform.
+* @returns The transformed string, same length as `str`.
 */
 function lns(str) {
 	const result = str.split("");

package/lib/hash.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"hash.mjs","names":[],"sources":["../src/hash.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Hash a string using the FNV-1a algorithm.\n *\n * Generates a deterministic hash value for a given string using a variant of the FNV-1a\n * (Fowler-Noll-Vo) algorithm. The hash is returned as a string representation of a 32-bit integer.\n */\nexport function getHashForString(string: string): string {\n\tlet hash = 0;\n\tfor (let i = 0; i < string.length; i++) {\n\t\thash = (hash << 5) - hash + string.charCodeAt(i);\n\t\thash |= 0; // Convert to 32bit integer\n\t}\n\treturn `${hash}`;\n}\n\n/**\n * Hash an object by converting it to JSON and then hashing the resulting string.\n */\nexport function getHashForObject(obj: unknown): string {\n\treturn getHashForString(JSON.stringify(obj));\n}\n\n/**\n * Hash an ArrayBuffer using the FNV-1a algorithm.\n */\nexport function getHashForBuffer(buffer: ArrayBuffer): string {\n\tconst view = new DataView(buffer);\n\tlet hash = 0;\n\tfor (let i = 0; i < view.byteLength; i++) {\n\t\thash = (hash << 5) - hash + view.getUint8(i);\n\t\thash |= 0; // Convert to 32bit integer\n\t}\n\treturn `${hash}`;\n}\n\n/**\n * Applies a string transformation algorithm that rearranges and modifies characters.\n */\nexport function lns(str: string): string {\n\tconst result = str.split(\"\");\n\tresult.push(...result.splice(0, Math.round(result.length / 5)));\n\tresult.push(...result.splice(0, Math.round(result.length / 4)));\n\tresult.push(...result.splice(0, Math.round(result.length / 3)));\n\tresult.push(...result.splice(0, Math.round(result.length / 2)));\n\treturn result\n\t\t.reverse()\n\t\t.map((n) => {\n\t\t\tconst num = Number(n);\n\t\t\treturn Number.isNaN(num) || n.trim() === \"\"\n\t\t\t\t? n\n\t\t\t\t: num < 5\n\t\t\t\t\t? String(5 + num)\n\t\t\t\t\t: num > 5\n\t\t\t\t\t\t? String(num - 5)\n\t\t\t\t\t\t: n;\n\t\t})\n\t\t.join(\"\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,iBAAiB,QAAwB;CACxD,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACvC,UAAQ,QAAQ,KAAK,OAAO,OAAO,WAAW,EAAE;AAChD,UAAQ;;AAET,QAAO,GAAG;;;;;AAMX,SAAgB,iBAAiB,KAAsB;AACtD,QAAO,iBAAiB,KAAK,UAAU,IAAI,CAAC;;;;;AAM7C,SAAgB,iBAAiB,QAA6B;CAC7D,MAAM,OAAO,IAAI,SAAS,OAAO;CACjC,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,YAAY,KAAK;AACzC,UAAQ,QAAQ,KAAK,OAAO,KAAK,SAAS,EAAE;AAC5C,UAAQ;;AAET,QAAO,GAAG;;;;;AAMX,SAAgB,IAAI,KAAqB;CACxC,MAAM,SAAS,IAAI,MAAM,GAAG;AAC5B,QAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,EAAE,CAAC,CAAC;AAC/D,QAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,EAAE,CAAC,CAAC;AAC/D,QAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,EAAE,CAAC,CAAC;AAC/D,QAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,EAAE,CAAC,CAAC;AAC/D,QAAO,OACL,SAAS,CACT,KAAK,MAAM;EACX,MAAM,MAAM,OAAO,EAAE;AACrB,SAAO,OAAO,MAAM,IAAI,IAAI,EAAE,MAAM,KAAK,KACtC,IACA,MAAM,IACL,OAAO,IAAI,IAAI,GACf,MAAM,IACL,OAAO,MAAM,EAAE,GACf;GACJ,CACD,KAAK,GAAG"}
+{"version":3,"file":"hash.mjs","names":[],"sources":["../src/hash.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview Fast, deterministic, non-cryptographic hashing helpers — a 32-bit\n * string/buffer hash for cache keys and change detection, plus a lightweight string\n * obfuscation transform. Not suitable for security-sensitive digests; use the\n * SHA-256 helper in {@link @resq-systems/security/crypto} for those.\n *\n * @module @resq-systems/security/hash\n */\n\n/**\n * Compute a deterministic non-cryptographic 32-bit hash of a string.\n *\n * Uses the classic `hash * 31 + charCode` accumulation (expressed as\n * `(hash << 5) - hash`), yielding the same value for the same input across runs.\n * Intended for cache keys and change detection, not for security.\n *\n * @param string - The input to hash.\n * @returns The signed 32-bit hash rendered as a decimal string.\n *\n * @example\n * ```ts\n * getHashForString(\"hello\") === getHashForString(\"hello\"); // → true\n * ```\n */\nexport function getHashForString(string: string): string {\n\tlet hash = 0;\n\tfor (let i = 0; i < string.length; i++) {\n\t\thash = (hash << 5) - hash + string.charCodeAt(i);\n\t\thash |= 0; // Coerce the accumulator back to a signed 32-bit integer.\n\t}\n\treturn `${hash}`;\n}\n\n/**\n * Hash an arbitrary value by serializing it to JSON and hashing the result.\n *\n * Key ordering follows `JSON.stringify`, so two structurally equal objects with\n * differently ordered keys can hash differently.\n *\n * @param obj - Any JSON-serializable value.\n * @returns The 32-bit hash of the serialized form, as a decimal string.\n * @throws {TypeError} When `obj` cannot be serialized: a circular\n *   reference or a `BigInt` makes `JSON.stringify` throw, and a value\n *   that stringifies to `undefined` (a bare function, `symbol`, or\n *   `undefined`) makes the downstream `.length` access throw.\n */\nexport function getHashForObject(obj: unknown): string {\n\treturn getHashForString(JSON.stringify(obj));\n}\n\n/**\n * Compute a deterministic non-cryptographic 32-bit hash of an `ArrayBuffer`.\n *\n * Applies the same accumulation as {@link getHashForString} over each byte.\n *\n * @param buffer - The bytes to hash.\n * @returns The signed 32-bit hash rendered as a decimal string.\n */\nexport function getHashForBuffer(buffer: ArrayBuffer): string {\n\tconst view = new DataView(buffer);\n\tlet hash = 0;\n\tfor (let i = 0; i < view.byteLength; i++) {\n\t\thash = (hash << 5) - hash + view.getUint8(i);\n\t\thash |= 0; // Coerce the accumulator back to a signed 32-bit integer.\n\t}\n\treturn `${hash}`;\n}\n\n/**\n * Reversibly scramble a string by rotating character blocks and shifting digits.\n *\n * A lightweight, non-cryptographic obfuscation: it reorders characters via a fixed\n * sequence of block rotations, reverses the result, and maps each digit `d` to\n * `d < 5 ? d + 5 : d > 5 ? d - 5 : d`. Provides obscurity, not security — do not\n * use it to protect secrets.\n *\n * Despite \"scramble\", the transform is **not a true inverse**: the digit map sends\n * both `0` and `5` to `5`, so any input containing those digits cannot be\n * recovered unambiguously. Non-digit characters (including whitespace) are only\n * reordered, never substituted. Deterministic and free of side effects.\n *\n * @param str - The string to transform.\n * @returns The transformed string, same length as `str`.\n */\nexport function lns(str: string): string {\n\tconst result = str.split(\"\");\n\tresult.push(...result.splice(0, Math.round(result.length / 5)));\n\tresult.push(...result.splice(0, Math.round(result.length / 4)));\n\tresult.push(...result.splice(0, Math.round(result.length / 3)));\n\tresult.push(...result.splice(0, Math.round(result.length / 2)));\n\treturn result\n\t\t.reverse()\n\t\t.map((n) => {\n\t\t\tconst num = Number(n);\n\t\t\treturn Number.isNaN(num) || n.trim() === \"\"\n\t\t\t\t? n\n\t\t\t\t: num < 5\n\t\t\t\t\t? String(5 + num)\n\t\t\t\t\t: num > 5\n\t\t\t\t\t\t? String(num - 5)\n\t\t\t\t\t\t: n;\n\t\t})\n\t\t.join(\"\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,iBAAiB,QAAwB;CACxD,IAAI,OAAO;CACX,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;EACvC,QAAQ,QAAQ,KAAK,OAAO,OAAO,WAAW,CAAC;EAC/C,QAAQ;CACT;CACA,OAAO,GAAG;AACX;;;;;;;;;;;;;;AAeA,SAAgB,iBAAiB,KAAsB;CACtD,OAAO,iBAAiB,KAAK,UAAU,GAAG,CAAC;AAC5C;;;;;;;;;AAUA,SAAgB,iBAAiB,QAA6B;CAC7D,MAAM,OAAO,IAAI,SAAS,MAAM;CAChC,IAAI,OAAO;CACX,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,YAAY,KAAK;EACzC,QAAQ,QAAQ,KAAK,OAAO,KAAK,SAAS,CAAC;EAC3C,QAAQ;CACT;CACA,OAAO,GAAG;AACX;;;;;;;;;;;;;;;;;AAkBA,SAAgB,IAAI,KAAqB;CACxC,MAAM,SAAS,IAAI,MAAM,EAAE;CAC3B,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,OACL,QAAQ,CAAC,CACT,KAAK,MAAM;EACX,MAAM,MAAM,OAAO,CAAC;EACpB,OAAO,OAAO,MAAM,GAAG,KAAK,EAAE,KAAK,MAAM,KACtC,IACA,MAAM,IACL,OAAO,IAAI,GAAG,IACd,MAAM,IACL,OAAO,MAAM,CAAC,IACd;CACN,CAAC,CAAC,CACD,KAAK,EAAE;AACV"}

package/lib/index.d.mts

@@ -1,5 +1,20 @@
+import { AddressClassification, OutboundRejectionReason, OutboundUrlPolicy, OutboundUrlVerdict, assertOutboundUrl, classifyAddress, isPubliclyRoutableAddress } from "./controls/address.mjs";
+import { CsrfFailureReason, CsrfTokenOptions, CsrfVerification, CsrfVerifyOptions, createCsrfToken, verifyCsrfToken } from "./controls/csrf.mjs";
+import { CorsResponsePolicy, OriginPolicyOptions, checkCorsResponsePolicy, isAllowedOrigin, normalizeOrigin } from "./controls/origin.mjs";
+import { RedirectPolicyOptions, RedirectRejectionReason, RedirectVerdict, resolveRedirectTarget } from "./controls/redirect.mjs";
+import { GraphQLRequestAnalysis, GraphQLRequestLimits, QueryComplexity, QueryComplexityLimits, analyzeGraphQLRequest, analyzeQueryComplexity, validateJsonpCallback } from "./controls/query.mjs";
+import { JsonPayloadLimits, JsonPayloadReport, checkJsonPayloadLimits } from "./controls/payload.mjs";
+import { FileTypeName, UploadCandidate, UploadRejectionReason, UploadVerdict, assertUploadType, detectFileSignature } from "./controls/upload.mjs";
 import { Ciphertext, EncryptionKey, Masked, SecureToken, Sha256Hex, coerceCiphertext, coerceEncryptionKey, decryptData, encryptData, generateSecureToken, hashData, isCiphertext, isEncryptionKey, maskEmail, maskPII, sanitizeForLogging, toCiphertext, toEncryptionKey, unsafeCiphertext, unsafeEncryptionKey } from "./crypto.mjs";
 import { getHashForBuffer, getHashForObject, getHashForString, lns } from "./hash.mjs";
-import { THREAT_DETECTED_MESSAGE, ThreatDetectionConfig, ThreatDetectionResult, ThreatFinding, ThreatType, containsCommandInjection, containsHomoglyphs, containsNoSQLInjection, containsPathTraversal, containsSQLInjection, containsXSSPatterns, detectThreatPatterns, getThreatErrorMessage, isSafeInput, normalizeUnicode, sanitizeForDisplay, validateSafeEmail, validateSafeName, validateSafeText } from "./validators.mjs";
+import { ALL_THREAT_CONTEXTS, CONFIDENCE_MULTIPLIERS, DEFAULT_THREAT_POLICY, EventContext, InputSource, InputVariant, InputVariantKind, SEVERITY_WEIGHTS, ThreatConfidence, ThreatContext, ThreatFinding, ThreatPolicy, ThreatRule, ThreatSeverity, ThreatType, ThreatVerdict } from "./threats/types.mjs";
+import { THREAT_DETECTED_MESSAGE, ThreatDetectionConfig, ThreatDetectionResult, ThreatSummary, containsCommandInjection, containsHomoglyphs, containsNoSQLInjection, containsPathTraversal, containsPrototypePollution, containsSQLInjection, containsXSSPatterns, detectThreatPatterns, encodeJsonForScript, encodeLogValue, escapeCsvField, escapeHtmlAttribute, escapeHtmlText, getThreatErrorMessage, isSafeInput, normalizeUnicode, sanitizeForDisplay, toCsvRow, validatePersonName, validateSafeEmail, validateSafeName, validateSafeText } from "./validators.mjs";
+import { MAX_SCAN_LENGTH, ThreatScanOptions, ThreatScanResult, scanForThreats } from "./threats/engine.mjs";
+import { THREAT_RULES, assertRuleCatalogIsValid, getRulesForContexts } from "./threats/rules/index.mjs";
+import { ThreatTypeSummary, calculateThreatScore, scoreForFinding, summarizeByType, verdictForScore } from "./threats/scoring.mjs";
+import { buildInputVariants, decodeHtmlEntities, tryPercentDecode } from "./threats/variants.mjs";
+import { ATTACK_PATTERNS, AttackPattern, attackPatternsForCwe } from "./threats/capec.generated.mjs";
+import { areConfusable, foldConfusables, getSkeleton } from "./unicode/confusables.mjs";
+import { IdentifierRestrictionLevel, IdentifierSecurityResult, UnicodeScript, analyzeIdentifier, containsBidiControls, containsInvisibleCharacters, getRestrictionLevel, getScripts, isSafeIdentifier, stripInvisibleCharacters } from "./unicode/index.mjs";
 import { CreditCard, CreditCardSchema, Email, EmailSchema, IPv4, IPv4Schema, PIIRedactionOptions, PIIRedactionOptionsSchema, PhoneNumber, PhoneNumberSchema, SSN, SSNSchema, SafeUrl, SafeUrlSchema, SanitizedString, SanitizedStringSchema, UrlProtocol, UrlProtocolSchema, UserInputOptions, UserInputOptionsSchema, escapeHtml, isValidEmail, isValidPhone, isValidSSN, isValidUrl, parseJsonWithSchema, redactPII, redactPIIEffect, safeStringify, sanitizeHtml, sanitizeJson, sanitizeUrl, sanitizeUrlEffect, stripAnsi, validateUserInput, validateUserInputEffect } from "./sanitize.mjs";
-export { Ciphertext, CreditCard, CreditCardSchema, Email, EmailSchema, EncryptionKey, IPv4, IPv4Schema, Masked, PIIRedactionOptions, PIIRedactionOptionsSchema, PhoneNumber, PhoneNumberSchema, SSN, SSNSchema, SafeUrl, SafeUrlSchema, SanitizedString, SanitizedStringSchema, SecureToken, Sha256Hex, THREAT_DETECTED_MESSAGE, ThreatDetectionConfig, ThreatDetectionResult, ThreatFinding, ThreatType, UrlProtocol, UrlProtocolSchema, UserInputOptions, UserInputOptionsSchema, coerceCiphertext, coerceEncryptionKey, containsCommandInjection, containsHomoglyphs, containsNoSQLInjection, containsPathTraversal, containsSQLInjection, containsXSSPatterns, decryptData, detectThreatPatterns, encryptData, escapeHtml, generateSecureToken, getHashForBuffer, getHashForObject, getHashForString, getThreatErrorMessage, hashData, isCiphertext, isEncryptionKey, isSafeInput, isValidEmail, isValidPhone, isValidSSN, isValidUrl, lns, maskEmail, maskPII, normalizeUnicode, parseJsonWithSchema, redactPII, redactPIIEffect, safeStringify, sanitizeForDisplay, sanitizeForLogging, sanitizeHtml, sanitizeJson, sanitizeUrl, sanitizeUrlEffect, stripAnsi, toCiphertext, toEncryptionKey, unsafeCiphertext, unsafeEncryptionKey, validateSafeEmail, validateSafeName, validateSafeText, validateUserInput, validateUserInputEffect };
+export { ALL_THREAT_CONTEXTS, ATTACK_PATTERNS, type AddressClassification, type AttackPattern, CONFIDENCE_MULTIPLIERS, type Ciphertext, type CorsResponsePolicy, type CreditCard, CreditCardSchema, type CsrfFailureReason, type CsrfTokenOptions, type CsrfVerification, type CsrfVerifyOptions, DEFAULT_THREAT_POLICY, type Email, EmailSchema, type EncryptionKey, type EventContext, type FileTypeName, type GraphQLRequestAnalysis, type GraphQLRequestLimits, type IPv4, IPv4Schema, type IdentifierRestrictionLevel, type IdentifierSecurityResult, type InputSource, type InputVariant, type InputVariantKind, type JsonPayloadLimits, type JsonPayloadReport, MAX_SCAN_LENGTH, type Masked, type OriginPolicyOptions, type OutboundRejectionReason, type OutboundUrlPolicy, type OutboundUrlVerdict, type PIIRedactionOptions, PIIRedactionOptionsSchema, type PhoneNumber, PhoneNumberSchema, type QueryComplexity, type QueryComplexityLimits, type RedirectPolicyOptions, type RedirectRejectionReason, type RedirectVerdict, SEVERITY_WEIGHTS, type SSN, SSNSchema, type SafeUrl, SafeUrlSchema, type SanitizedString, SanitizedStringSchema, type SecureToken, type Sha256Hex, THREAT_DETECTED_MESSAGE, THREAT_RULES, type ThreatConfidence, type ThreatContext, type ThreatDetectionConfig, type ThreatDetectionResult, type ThreatFinding, type ThreatPolicy, type ThreatRule, type ThreatScanOptions, type ThreatScanResult, type ThreatSeverity, type ThreatSummary, type ThreatType, type ThreatTypeSummary, type ThreatVerdict, type UnicodeScript, type UploadCandidate, type UploadRejectionReason, type UploadVerdict, type UrlProtocol, UrlProtocolSchema, type UserInputOptions, UserInputOptionsSchema, analyzeGraphQLRequest, analyzeIdentifier, analyzeQueryComplexity, areConfusable, assertOutboundUrl, assertRuleCatalogIsValid, assertUploadType, attackPatternsForCwe, buildInputVariants, calculateThreatScore, checkCorsResponsePolicy, checkJsonPayloadLimits, classifyAddress, coerceCiphertext, coerceEncryptionKey, containsBidiControls, containsCommandInjection, containsHomoglyphs, containsInvisibleCharacters, containsNoSQLInjection, containsPathTraversal, containsPrototypePollution, containsSQLInjection, containsXSSPatterns, createCsrfToken, decodeHtmlEntities, decryptData, detectFileSignature, detectThreatPatterns, encodeJsonForScript, encodeLogValue, encryptData, escapeCsvField, escapeHtml, escapeHtmlAttribute, escapeHtmlText, foldConfusables, generateSecureToken, getHashForBuffer, getHashForObject, getHashForString, getRestrictionLevel, getRulesForContexts, getScripts, getSkeleton, getThreatErrorMessage, hashData, isAllowedOrigin, isCiphertext, isEncryptionKey, isPubliclyRoutableAddress, isSafeIdentifier, isSafeInput, isValidEmail, isValidPhone, isValidSSN, isValidUrl, lns, maskEmail, maskPII, normalizeOrigin, normalizeUnicode, parseJsonWithSchema, redactPII, redactPIIEffect, resolveRedirectTarget, safeStringify, sanitizeForDisplay, sanitizeForLogging, sanitizeHtml, sanitizeJson, sanitizeUrl, sanitizeUrlEffect, scanForThreats, scoreForFinding, stripAnsi, stripInvisibleCharacters, summarizeByType, toCiphertext, toCsvRow, toEncryptionKey, tryPercentDecode, unsafeCiphertext, unsafeEncryptionKey, validateJsonpCallback, validatePersonName, validateSafeEmail, validateSafeName, validateSafeText, validateUserInput, validateUserInputEffect, verdictForScore, verifyCsrfToken };

package/lib/index.mjs

@@ -1,5 +1,22 @@
 import { coerceCiphertext, coerceEncryptionKey, decryptData, encryptData, generateSecureToken, hashData, isCiphertext, isEncryptionKey, maskEmail, maskPII, sanitizeForLogging, toCiphertext, toEncryptionKey, unsafeCiphertext, unsafeEncryptionKey } from "./crypto.mjs";
 import { getHashForBuffer, getHashForObject, getHashForString, lns } from "./hash.mjs";
-import { THREAT_DETECTED_MESSAGE, containsCommandInjection, containsHomoglyphs, containsNoSQLInjection, containsPathTraversal, containsSQLInjection, containsXSSPatterns, detectThreatPatterns, getThreatErrorMessage, isSafeInput, normalizeUnicode, sanitizeForDisplay, validateSafeEmail, validateSafeName, validateSafeText } from "./validators.mjs";
+import { ALL_THREAT_CONTEXTS, CONFIDENCE_MULTIPLIERS, DEFAULT_THREAT_POLICY, SEVERITY_WEIGHTS } from "./threats/types.mjs";
+import { THREAT_RULES, assertRuleCatalogIsValid, getRulesForContexts } from "./threats/rules/index.mjs";
+import { calculateThreatScore, scoreForFinding, summarizeByType, verdictForScore } from "./threats/scoring.mjs";
+import { buildInputVariants, decodeHtmlEntities, tryPercentDecode } from "./threats/variants.mjs";
+import { MAX_SCAN_LENGTH, scanForThreats } from "./threats/engine.mjs";
+import { areConfusable, foldConfusables, getSkeleton } from "./unicode/confusables.mjs";
+import { analyzeIdentifier, containsBidiControls, containsInvisibleCharacters, getRestrictionLevel, getScripts, isSafeIdentifier, stripInvisibleCharacters } from "./unicode/index.mjs";
+import { THREAT_DETECTED_MESSAGE, containsCommandInjection, containsHomoglyphs, containsNoSQLInjection, containsPathTraversal, containsPrototypePollution, containsSQLInjection, containsXSSPatterns, detectThreatPatterns, encodeJsonForScript, encodeLogValue, escapeCsvField, escapeHtmlAttribute, escapeHtmlText, getThreatErrorMessage, isSafeInput, normalizeUnicode, sanitizeForDisplay, toCsvRow, validatePersonName, validateSafeEmail, validateSafeName, validateSafeText } from "./validators.mjs";
+import { ATTACK_PATTERNS, attackPatternsForCwe } from "./threats/capec.generated.mjs";
+import "./threats/index.mjs";
+import { assertOutboundUrl, classifyAddress, isPubliclyRoutableAddress } from "./controls/address.mjs";
+import { createCsrfToken, verifyCsrfToken } from "./controls/csrf.mjs";
+import { checkCorsResponsePolicy, isAllowedOrigin, normalizeOrigin } from "./controls/origin.mjs";
+import { resolveRedirectTarget } from "./controls/redirect.mjs";
+import { analyzeGraphQLRequest, analyzeQueryComplexity, validateJsonpCallback } from "./controls/query.mjs";
+import { checkJsonPayloadLimits } from "./controls/payload.mjs";
+import { assertUploadType, detectFileSignature } from "./controls/upload.mjs";
+import "./controls/index.mjs";
 import { CreditCardSchema, EmailSchema, IPv4Schema, PIIRedactionOptionsSchema, PhoneNumberSchema, SSNSchema, SafeUrlSchema, SanitizedStringSchema, UrlProtocolSchema, UserInputOptionsSchema, escapeHtml, isValidEmail, isValidPhone, isValidSSN, isValidUrl, parseJsonWithSchema, redactPII, redactPIIEffect, safeStringify, sanitizeHtml, sanitizeJson, sanitizeUrl, sanitizeUrlEffect, stripAnsi, validateUserInput, validateUserInputEffect } from "./sanitize.mjs";
-export { CreditCardSchema, EmailSchema, IPv4Schema, PIIRedactionOptionsSchema, PhoneNumberSchema, SSNSchema, SafeUrlSchema, SanitizedStringSchema, THREAT_DETECTED_MESSAGE, UrlProtocolSchema, UserInputOptionsSchema, coerceCiphertext, coerceEncryptionKey, containsCommandInjection, containsHomoglyphs, containsNoSQLInjection, containsPathTraversal, containsSQLInjection, containsXSSPatterns, decryptData, detectThreatPatterns, encryptData, escapeHtml, generateSecureToken, getHashForBuffer, getHashForObject, getHashForString, getThreatErrorMessage, hashData, isCiphertext, isEncryptionKey, isSafeInput, isValidEmail, isValidPhone, isValidSSN, isValidUrl, lns, maskEmail, maskPII, normalizeUnicode, parseJsonWithSchema, redactPII, redactPIIEffect, safeStringify, sanitizeForDisplay, sanitizeForLogging, sanitizeHtml, sanitizeJson, sanitizeUrl, sanitizeUrlEffect, stripAnsi, toCiphertext, toEncryptionKey, unsafeCiphertext, unsafeEncryptionKey, validateSafeEmail, validateSafeName, validateSafeText, validateUserInput, validateUserInputEffect };
+export { ALL_THREAT_CONTEXTS, ATTACK_PATTERNS, CONFIDENCE_MULTIPLIERS, CreditCardSchema, DEFAULT_THREAT_POLICY, EmailSchema, IPv4Schema, MAX_SCAN_LENGTH, PIIRedactionOptionsSchema, PhoneNumberSchema, SEVERITY_WEIGHTS, SSNSchema, SafeUrlSchema, SanitizedStringSchema, THREAT_DETECTED_MESSAGE, THREAT_RULES, UrlProtocolSchema, UserInputOptionsSchema, analyzeGraphQLRequest, analyzeIdentifier, analyzeQueryComplexity, areConfusable, assertOutboundUrl, assertRuleCatalogIsValid, assertUploadType, attackPatternsForCwe, buildInputVariants, calculateThreatScore, checkCorsResponsePolicy, checkJsonPayloadLimits, classifyAddress, coerceCiphertext, coerceEncryptionKey, containsBidiControls, containsCommandInjection, containsHomoglyphs, containsInvisibleCharacters, containsNoSQLInjection, containsPathTraversal, containsPrototypePollution, containsSQLInjection, containsXSSPatterns, createCsrfToken, decodeHtmlEntities, decryptData, detectFileSignature, detectThreatPatterns, encodeJsonForScript, encodeLogValue, encryptData, escapeCsvField, escapeHtml, escapeHtmlAttribute, escapeHtmlText, foldConfusables, generateSecureToken, getHashForBuffer, getHashForObject, getHashForString, getRestrictionLevel, getRulesForContexts, getScripts, getSkeleton, getThreatErrorMessage, hashData, isAllowedOrigin, isCiphertext, isEncryptionKey, isPubliclyRoutableAddress, isSafeIdentifier, isSafeInput, isValidEmail, isValidPhone, isValidSSN, isValidUrl, lns, maskEmail, maskPII, normalizeOrigin, normalizeUnicode, parseJsonWithSchema, redactPII, redactPIIEffect, resolveRedirectTarget, safeStringify, sanitizeForDisplay, sanitizeForLogging, sanitizeHtml, sanitizeJson, sanitizeUrl, sanitizeUrlEffect, scanForThreats, scoreForFinding, stripAnsi, stripInvisibleCharacters, summarizeByType, toCiphertext, toCsvRow, toEncryptionKey, tryPercentDecode, unsafeCiphertext, unsafeEncryptionKey, validateJsonpCallback, validatePersonName, validateSafeEmail, validateSafeName, validateSafeText, validateUserInput, validateUserInputEffect, verdictForScore, verifyCsrfToken };

package/lib/paths.d.mts

@@ -0,0 +1,92 @@
+//#region src/paths.d.ts
+/**
+ * Copyright 2026 ResQ Systems, Inc.
+ *
+ * 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.
+ */
+/** Options for {@link resolveContainedPath}. */
+interface ContainmentOptions {
+  /**
+   * Treat the base directory itself as an acceptable result. Defaults to `true`.
+   * Pass `false` when the caller requires a path strictly *inside* the base — an
+   * upload target, say, rather than a listing root.
+   */
+  readonly allowBaseItself?: boolean;
+}
+/**
+ * Resolve an untrusted path against a base directory and verify containment.
+ *
+ * The candidate is resolved against the base — which also normalizes `.`, `..`, and
+ * duplicate separators — and accepted only if the result is the base or sits beneath
+ * it. An absolute `untrustedPath` overrides the base under `path.resolve` semantics,
+ * so it too is caught by the containment check rather than silently trusted.
+ *
+ * **This function performs no filesystem I/O**, so it cannot see symlinks. A path that
+ * is textually contained may still resolve on disk to a target outside the base. When
+ * the target may exist and may be a link, follow up with `fs.promises.realpath` on
+ * both the base and the result and re-run {@link isPathContained} on those.
+ *
+ * @param baseDirectory - Directory the result must stay within. Resolved against the
+ *   process working directory when relative.
+ * @param untrustedPath - Candidate path from an untrusted source.
+ * @param options - See {@link ContainmentOptions}.
+ * @returns The resolved absolute path when contained, otherwise `null`. Also `null`
+ *   for non-string arguments, an empty base, or a NUL byte in either argument.
+ *
+ * @example
+ * ```ts
+ * const base = "/srv/uploads";
+ *
+ * resolveContainedPath(base, "avatar.png");        // "/srv/uploads/avatar.png"
+ * resolveContainedPath(base, "nested/a.txt");      // "/srv/uploads/nested/a.txt"
+ * resolveContainedPath(base, "../../etc/passwd");  // null
+ * resolveContainedPath(base, "/etc/passwd");       // null
+ * ```
+ */
+declare function resolveContainedPath(baseDirectory: string, untrustedPath: string, options?: ContainmentOptions): string | null;
+/**
+ * Boolean form of {@link resolveContainedPath}.
+ *
+ * @param baseDirectory - Directory the candidate must stay within.
+ * @param candidatePath - Path to test.
+ * @param options - See {@link ContainmentOptions}.
+ * @returns `true` when the candidate resolves inside the base.
+ */
+declare function isPathContained(baseDirectory: string, candidatePath: string, options?: ContainmentOptions): boolean;
+/**
+ * Reduce an untrusted string to a single safe path segment.
+ *
+ * Strips directory separators, control characters, and Windows-reserved characters;
+ * removes leading dots so the result cannot become `.`/`..` or a hidden file; trims
+ * the trailing dots and spaces Windows silently drops (which is how `evil.php.`
+ * becomes `evil.php` after the fact); and refuses reserved device names.
+ *
+ * The output is a *segment*, never a path. Join it onto a base directory yourself and
+ * confirm the result with {@link resolveContainedPath} — that remains the containment
+ * control; this is only hygiene.
+ *
+ * @param filename - Untrusted filename, typically from a multipart upload.
+ * @param fallback - Returned when nothing usable survives. Defaults to `"file"`.
+ * @returns A safe single path segment.
+ *
+ * @example
+ * ```ts
+ * sanitizeFilename("../../etc/passwd"); // "etcpasswd"
+ * sanitizeFilename("report.pdf.");      // "report.pdf"
+ * sanitizeFilename("CON.txt");          // "file"
+ * ```
+ */
+declare function sanitizeFilename(filename: string, fallback?: string): string;
+//#endregion
+export { ContainmentOptions, isPathContained, resolveContainedPath, sanitizeFilename };
+//# sourceMappingURL=paths.d.mts.map

package/lib/paths.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.mts","names":[],"sources":["../src/paths.ts"],"mappings":";;;;;;;;;;;;;;;;;UAsCiB;;;;;;WAMP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCM,qBACf,uBACA,uBACA,UAAS;;;;;;;;;iBAuCM,gBACf,uBACA,uBACA,UAAU;;;;;;;;;;;;;;;;;;;;;;;;iBAmDK,iBAAiB,kBAAkB"}