@resq-systems/security 2.0.0 → 2.1.1

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 * @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":"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"}
+{"version":3,"file":"crypto.mjs","names":[],"sources":["../src/crypto.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n * SPDX-License-Identifier: Apache-2.0\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":"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"}

package/lib/hash.d.mts

@@ -1,6 +1,7 @@
 //#region src/hash.d.ts
 /**
  * Copyright 2026 ResQ Systems, Inc.
+ * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -37,7 +38,7 @@
  * getHashForString("hello") === getHashForString("hello"); // → true
  * ```
  */
-declare function getHashForString(string: string): string;
+export declare function getHashForString(string: string): string;
 /**
  * Hash an arbitrary value by serializing it to JSON and hashing the result.
  *
@@ -51,7 +52,7 @@ declare function getHashForString(string: string): string;
  *   that stringifies to `undefined` (a bare function, `symbol`, or
  *   `undefined`) makes the downstream `.length` access throw.
  */
-declare function getHashForObject(obj: unknown): string;
+export declare function getHashForObject(obj: unknown): string;
 /**
  * Compute a deterministic non-cryptographic 32-bit hash of an `ArrayBuffer`.
  *
@@ -60,7 +61,7 @@ declare function getHashForObject(obj: unknown): string;
  * @param buffer - The bytes to hash.
  * @returns The signed 32-bit hash rendered as a decimal string.
  */
-declare function getHashForBuffer(buffer: ArrayBuffer): string;
+export declare function getHashForBuffer(buffer: ArrayBuffer): string;
 /**
  * Reversibly scramble a string by rotating character blocks and shifting digits.
  *
@@ -77,7 +78,6 @@ declare function getHashForBuffer(buffer: ArrayBuffer): string;
  * @param str - The string to transform.
  * @returns The transformed string, same length as `str`.
  */
-declare function lns(str: string): string;
+export declare function lns(str: string): string;
 //#endregion
-export { getHashForBuffer, getHashForObject, getHashForString, lns };
 //# sourceMappingURL=hash.d.mts.map

package/lib/hash.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.mts","names":[],"sources":["../src/hash.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCgB,iBAAiB;;;;;;;;;;;;;;iBAsBjB,iBAAiB;;;;;;;;;iBAYjB,iBAAiB,QAAQ;;;;;;;;;;;;;;;;;iBA0BzB,IAAI"}
+{"version":3,"file":"hash.d.mts","names":[],"sources":["../src/hash.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAyCgB,iBAAiB;;;;;;;;;;;;;;wBAsBjB,iBAAiB;;;;;;;;;wBAYjB,iBAAiB,QAAQ;;;;;;;;;;;;;;;;;wBA0BzB,IAAI"}

package/lib/hash.mjs

@@ -1,6 +1,7 @@
 //#region src/hash.ts
 /**
 * Copyright 2026 ResQ Systems, Inc.
+* SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.

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 * @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"}
+{"version":3,"file":"hash.mjs","names":[],"sources":["../src/hash.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n * SPDX-License-Identifier: Apache-2.0\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,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/paths.d.mts

@@ -1,6 +1,7 @@
 //#region src/paths.d.ts
 /**
  * Copyright 2026 ResQ Systems, Inc.
+ * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,7 +16,7 @@
  * limitations under the License.
  */
 /** Options for {@link resolveContainedPath}. */
-interface ContainmentOptions {
+export 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
@@ -53,7 +54,7 @@ interface ContainmentOptions {
  * resolveContainedPath(base, "/etc/passwd");       // null
  * ```
  */
-declare function resolveContainedPath(baseDirectory: string, untrustedPath: string, options?: ContainmentOptions): string | null;
+export declare function resolveContainedPath(baseDirectory: string, untrustedPath: string, options?: ContainmentOptions): string | null;
 /**
  * Boolean form of {@link resolveContainedPath}.
  *
@@ -62,7 +63,7 @@ declare function resolveContainedPath(baseDirectory: string, untrustedPath: stri
  * @param options - See {@link ContainmentOptions}.
  * @returns `true` when the candidate resolves inside the base.
  */
-declare function isPathContained(baseDirectory: string, candidatePath: string, options?: ContainmentOptions): boolean;
+export declare function isPathContained(baseDirectory: string, candidatePath: string, options?: ContainmentOptions): boolean;
 /**
  * Reduce an untrusted string to a single safe path segment.
  *
@@ -86,7 +87,6 @@ declare function isPathContained(baseDirectory: string, candidatePath: string, o
  * sanitizeFilename("CON.txt");          // "file"
  * ```
  */
-declare function sanitizeFilename(filename: string, fallback?: string): string;
+export 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

@@ -1 +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"}
+{"version":3,"file":"paths.d.mts","names":[],"sources":["../src/paths.ts"],"mappings":";;;;;;;;;;;;;;;;;;iBAuCiB;;;;;;WAMP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoCM,qBACf,uBACA,uBACA,UAAS;;;;;;;;;wBAuCM,gBACf,uBACA,uBACA,UAAU;;;;;;;;;;;;;;;;;;;;;;;;wBAmDK,iBAAiB,kBAAkB"}

package/lib/paths.mjs

@@ -2,6 +2,7 @@ import path from "node:path";
 //#region src/paths.ts
 /**
 * Copyright 2026 ResQ Systems, Inc.
+* SPDX-License-Identifier: Apache-2.0
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.

package/lib/paths.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"paths.mjs","names":[],"sources":["../src/paths.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 Path containment — the *prevention* half of CWE-22, as distinct from\n * the detection rules in `@resq-systems/security/threats`.\n *\n * Detecting `../` is not the control. CWE-22 describes the failure to keep a\n * constructed path inside its restricted directory, so the control is to resolve the\n * candidate against the base and verify the result still lives beneath it. That check\n * holds for inputs no signature catches: an absolute path, a Windows drive-relative\n * path, an alternate separator, or a name whose `..` only appears after normalization.\n *\n * **Node-only.** This module statically imports `node:path` and is therefore published\n * exclusively under the `@resq-systems/security/paths` subpath, never through the\n * package root, so browser bundles of the root barrel stay free of Node builtins.\n *\n * @module @resq-systems/security/paths\n */\n\nimport path from \"node:path\";\n\n//#region Containment\n\n/** Options for {@link resolveContainedPath}. */\nexport interface ContainmentOptions {\n\t/**\n\t * Treat the base directory itself as an acceptable result. Defaults to `true`.\n\t * Pass `false` when the caller requires a path strictly *inside* the base — an\n\t * upload target, say, rather than a listing root.\n\t */\n\treadonly allowBaseItself?: boolean;\n}\n\n/** NUL truncates paths in some syscall layers, so it is rejected before resolution. */\nconst NUL = \"\\u0000\";\n\n/**\n * Resolve an untrusted path against a base directory and verify containment.\n *\n * The candidate is resolved against the base — which also normalizes `.`, `..`, and\n * duplicate separators — and accepted only if the result is the base or sits beneath\n * it. An absolute `untrustedPath` overrides the base under `path.resolve` semantics,\n * so it too is caught by the containment check rather than silently trusted.\n *\n * **This function performs no filesystem I/O**, so it cannot see symlinks. A path that\n * is textually contained may still resolve on disk to a target outside the base. When\n * the target may exist and may be a link, follow up with `fs.promises.realpath` on\n * both the base and the result and re-run {@link isPathContained} on those.\n *\n * @param baseDirectory - Directory the result must stay within. Resolved against the\n *   process working directory when relative.\n * @param untrustedPath - Candidate path from an untrusted source.\n * @param options - See {@link ContainmentOptions}.\n * @returns The resolved absolute path when contained, otherwise `null`. Also `null`\n *   for non-string arguments, an empty base, or a NUL byte in either argument.\n *\n * @example\n * ```ts\n * const base = \"/srv/uploads\";\n *\n * resolveContainedPath(base, \"avatar.png\");        // \"/srv/uploads/avatar.png\"\n * resolveContainedPath(base, \"nested/a.txt\");      // \"/srv/uploads/nested/a.txt\"\n * resolveContainedPath(base, \"../../etc/passwd\");  // null\n * resolveContainedPath(base, \"/etc/passwd\");       // null\n * ```\n */\nexport function resolveContainedPath(\n\tbaseDirectory: string,\n\tuntrustedPath: string,\n\toptions: ContainmentOptions = {},\n): string | null {\n\tif (typeof baseDirectory !== \"string\" || typeof untrustedPath !== \"string\") {\n\t\treturn null;\n\t}\n\tif (baseDirectory.length === 0) return null;\n\n\t// `a.txt\\0.png` can pass an extension check and then open `a.txt`.\n\tif (untrustedPath.includes(NUL) || baseDirectory.includes(NUL)) {\n\t\treturn null;\n\t}\n\n\tconst { allowBaseItself = true } = options;\n\n\tconst base = path.resolve(baseDirectory);\n\tconst candidate = path.resolve(base, untrustedPath);\n\tconst relative = path.relative(base, candidate);\n\n\tif (relative === \"\") {\n\t\treturn allowBaseItself ? candidate : null;\n\t}\n\n\t// `path.relative` yields a `..`-prefixed path when the candidate escapes, and an\n\t// absolute path when the two sit on different Windows drives.\n\tif (relative === \"..\" || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {\n\t\treturn null;\n\t}\n\n\treturn candidate;\n}\n\n/**\n * Boolean form of {@link resolveContainedPath}.\n *\n * @param baseDirectory - Directory the candidate must stay within.\n * @param candidatePath - Path to test.\n * @param options - See {@link ContainmentOptions}.\n * @returns `true` when the candidate resolves inside the base.\n */\nexport function isPathContained(\n\tbaseDirectory: string,\n\tcandidatePath: string,\n\toptions?: ContainmentOptions,\n): boolean {\n\treturn resolveContainedPath(baseDirectory, candidatePath, options) !== null;\n}\n\n//#endregion\n\n//#region Filename sanitization\n\n/**\n * Characters invalid in a Windows path segment, plus both separators and the C0\n * control range.\n */\n// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are invalid in filenames and must be stripped\nconst UNSAFE_FILENAME_CHARS = /[<>:\"/\\\\|?*\\u0000-\\u001f\\u007f]/g;\n\n/**\n * Windows device names, reserved regardless of extension — opening `CON.txt` still\n * targets the console device.\n */\nconst RESERVED_WINDOWS_NAMES = /^(?:CON|PRN|AUX|NUL|COM\\d|LPT\\d)(?:\\.|$)/i;\n\n/** Longest filename accepted on common filesystems. */\nconst MAX_FILENAME_LENGTH = 255;\n\n/** Longest extension preserved when truncating an over-long filename. */\nconst MAX_PRESERVED_EXTENSION = 16;\n\n/**\n * Reduce an untrusted string to a single safe path segment.\n *\n * Strips directory separators, control characters, and Windows-reserved characters;\n * removes leading dots so the result cannot become `.`/`..` or a hidden file; trims\n * the trailing dots and spaces Windows silently drops (which is how `evil.php.`\n * becomes `evil.php` after the fact); and refuses reserved device names.\n *\n * The output is a *segment*, never a path. Join it onto a base directory yourself and\n * confirm the result with {@link resolveContainedPath} — that remains the containment\n * control; this is only hygiene.\n *\n * @param filename - Untrusted filename, typically from a multipart upload.\n * @param fallback - Returned when nothing usable survives. Defaults to `\"file\"`.\n * @returns A safe single path segment.\n *\n * @example\n * ```ts\n * sanitizeFilename(\"../../etc/passwd\"); // \"etcpasswd\"\n * sanitizeFilename(\"report.pdf.\");      // \"report.pdf\"\n * sanitizeFilename(\"CON.txt\");          // \"file\"\n * ```\n */\nexport function sanitizeFilename(filename: string, fallback = \"file\"): string {\n\tif (typeof filename !== \"string\" || filename.length === 0) return fallback;\n\n\tlet safe = filename\n\t\t.normalize(\"NFC\")\n\t\t.replace(UNSAFE_FILENAME_CHARS, \"\")\n\t\t.replace(/^\\.+/, \"\")\n\t\t.replace(/[. ]+$/, \"\")\n\t\t.trim();\n\n\tif (safe.length === 0) return fallback;\n\tif (RESERVED_WINDOWS_NAMES.test(safe)) return fallback;\n\n\tif (safe.length > MAX_FILENAME_LENGTH) {\n\t\tconst extension = path.extname(safe).slice(0, MAX_PRESERVED_EXTENSION);\n\t\tsafe = safe.slice(0, MAX_FILENAME_LENGTH - extension.length) + extension;\n\t}\n\n\treturn safe;\n}\n\n//#endregion\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCZ,SAAgB,qBACf,eACA,eACA,UAA8B,CAAC,GACf;CAChB,IAAI,OAAO,kBAAkB,YAAY,OAAO,kBAAkB,UACjE,OAAO;CAER,IAAI,cAAc,WAAW,GAAG,OAAO;CAGvC,IAAI,cAAc,SAAS,GAAG,KAAK,cAAc,SAAS,GAAG,GAC5D,OAAO;CAGR,MAAM,EAAE,kBAAkB,SAAS;CAEnC,MAAM,OAAO,KAAK,QAAQ,aAAa;CACvC,MAAM,YAAY,KAAK,QAAQ,MAAM,aAAa;CAClD,MAAM,WAAW,KAAK,SAAS,MAAM,SAAS;CAE9C,IAAI,aAAa,IAChB,OAAO,kBAAkB,YAAY;CAKtC,IAAI,aAAa,QAAQ,SAAS,WAAW,KAAK,KAAK,KAAK,KAAK,KAAK,WAAW,QAAQ,GACxF,OAAO;CAGR,OAAO;AACR;;;;;;;;;AAUA,SAAgB,gBACf,eACA,eACA,SACU;CACV,OAAO,qBAAqB,eAAe,eAAe,OAAO,MAAM;AACxE;;;;;AAWA,MAAM,wBAAwB;;;;;AAM9B,MAAM,yBAAyB;;AAG/B,MAAM,sBAAsB;;AAG5B,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;AAyBhC,SAAgB,iBAAiB,UAAkB,WAAW,QAAgB;CAC7E,IAAI,OAAO,aAAa,YAAY,SAAS,WAAW,GAAG,OAAO;CAElE,IAAI,OAAO,SACT,UAAU,KAAK,CAAC,CAChB,QAAQ,uBAAuB,EAAE,CAAC,CAClC,QAAQ,QAAQ,EAAE,CAAC,CACnB,QAAQ,UAAU,EAAE,CAAC,CACrB,KAAK;CAEP,IAAI,KAAK,WAAW,GAAG,OAAO;CAC9B,IAAI,uBAAuB,KAAK,IAAI,GAAG,OAAO;CAE9C,IAAI,KAAK,SAAS,qBAAqB;EACtC,MAAM,YAAY,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,uBAAuB;EACrE,OAAO,KAAK,MAAM,GAAG,sBAAsB,UAAU,MAAM,IAAI;CAChE;CAEA,OAAO;AACR"}
+{"version":3,"file":"paths.mjs","names":[],"sources":["../src/paths.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n * SPDX-License-Identifier: Apache-2.0\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 Path containment — the *prevention* half of CWE-22, as distinct from\n * the detection rules in `@resq-systems/security/threats`.\n *\n * Detecting `../` is not the control. CWE-22 describes the failure to keep a\n * constructed path inside its restricted directory, so the control is to resolve the\n * candidate against the base and verify the result still lives beneath it. That check\n * holds for inputs no signature catches: an absolute path, a Windows drive-relative\n * path, an alternate separator, or a name whose `..` only appears after normalization.\n *\n * **Node-only.** This module statically imports `node:path` and is therefore published\n * exclusively under the `@resq-systems/security/paths` subpath, never through the\n * package root, so browser bundles of the root barrel stay free of Node builtins.\n *\n * @module @resq-systems/security/paths\n */\n\nimport path from \"node:path\";\n\n//#region Containment\n\n/** Options for {@link resolveContainedPath}. */\nexport interface ContainmentOptions {\n\t/**\n\t * Treat the base directory itself as an acceptable result. Defaults to `true`.\n\t * Pass `false` when the caller requires a path strictly *inside* the base — an\n\t * upload target, say, rather than a listing root.\n\t */\n\treadonly allowBaseItself?: boolean;\n}\n\n/** NUL truncates paths in some syscall layers, so it is rejected before resolution. */\nconst NUL = \"\\u0000\";\n\n/**\n * Resolve an untrusted path against a base directory and verify containment.\n *\n * The candidate is resolved against the base — which also normalizes `.`, `..`, and\n * duplicate separators — and accepted only if the result is the base or sits beneath\n * it. An absolute `untrustedPath` overrides the base under `path.resolve` semantics,\n * so it too is caught by the containment check rather than silently trusted.\n *\n * **This function performs no filesystem I/O**, so it cannot see symlinks. A path that\n * is textually contained may still resolve on disk to a target outside the base. When\n * the target may exist and may be a link, follow up with `fs.promises.realpath` on\n * both the base and the result and re-run {@link isPathContained} on those.\n *\n * @param baseDirectory - Directory the result must stay within. Resolved against the\n *   process working directory when relative.\n * @param untrustedPath - Candidate path from an untrusted source.\n * @param options - See {@link ContainmentOptions}.\n * @returns The resolved absolute path when contained, otherwise `null`. Also `null`\n *   for non-string arguments, an empty base, or a NUL byte in either argument.\n *\n * @example\n * ```ts\n * const base = \"/srv/uploads\";\n *\n * resolveContainedPath(base, \"avatar.png\");        // \"/srv/uploads/avatar.png\"\n * resolveContainedPath(base, \"nested/a.txt\");      // \"/srv/uploads/nested/a.txt\"\n * resolveContainedPath(base, \"../../etc/passwd\");  // null\n * resolveContainedPath(base, \"/etc/passwd\");       // null\n * ```\n */\nexport function resolveContainedPath(\n\tbaseDirectory: string,\n\tuntrustedPath: string,\n\toptions: ContainmentOptions = {},\n): string | null {\n\tif (typeof baseDirectory !== \"string\" || typeof untrustedPath !== \"string\") {\n\t\treturn null;\n\t}\n\tif (baseDirectory.length === 0) return null;\n\n\t// `a.txt\\0.png` can pass an extension check and then open `a.txt`.\n\tif (untrustedPath.includes(NUL) || baseDirectory.includes(NUL)) {\n\t\treturn null;\n\t}\n\n\tconst { allowBaseItself = true } = options;\n\n\tconst base = path.resolve(baseDirectory);\n\tconst candidate = path.resolve(base, untrustedPath);\n\tconst relative = path.relative(base, candidate);\n\n\tif (relative === \"\") {\n\t\treturn allowBaseItself ? candidate : null;\n\t}\n\n\t// `path.relative` yields a `..`-prefixed path when the candidate escapes, and an\n\t// absolute path when the two sit on different Windows drives.\n\tif (relative === \"..\" || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {\n\t\treturn null;\n\t}\n\n\treturn candidate;\n}\n\n/**\n * Boolean form of {@link resolveContainedPath}.\n *\n * @param baseDirectory - Directory the candidate must stay within.\n * @param candidatePath - Path to test.\n * @param options - See {@link ContainmentOptions}.\n * @returns `true` when the candidate resolves inside the base.\n */\nexport function isPathContained(\n\tbaseDirectory: string,\n\tcandidatePath: string,\n\toptions?: ContainmentOptions,\n): boolean {\n\treturn resolveContainedPath(baseDirectory, candidatePath, options) !== null;\n}\n\n//#endregion\n\n//#region Filename sanitization\n\n/**\n * Characters invalid in a Windows path segment, plus both separators and the C0\n * control range.\n */\n// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are invalid in filenames and must be stripped\nconst UNSAFE_FILENAME_CHARS = /[<>:\"/\\\\|?*\\u0000-\\u001f\\u007f]/g;\n\n/**\n * Windows device names, reserved regardless of extension — opening `CON.txt` still\n * targets the console device.\n */\nconst RESERVED_WINDOWS_NAMES = /^(?:CON|PRN|AUX|NUL|COM\\d|LPT\\d)(?:\\.|$)/i;\n\n/** Longest filename accepted on common filesystems. */\nconst MAX_FILENAME_LENGTH = 255;\n\n/** Longest extension preserved when truncating an over-long filename. */\nconst MAX_PRESERVED_EXTENSION = 16;\n\n/**\n * Reduce an untrusted string to a single safe path segment.\n *\n * Strips directory separators, control characters, and Windows-reserved characters;\n * removes leading dots so the result cannot become `.`/`..` or a hidden file; trims\n * the trailing dots and spaces Windows silently drops (which is how `evil.php.`\n * becomes `evil.php` after the fact); and refuses reserved device names.\n *\n * The output is a *segment*, never a path. Join it onto a base directory yourself and\n * confirm the result with {@link resolveContainedPath} — that remains the containment\n * control; this is only hygiene.\n *\n * @param filename - Untrusted filename, typically from a multipart upload.\n * @param fallback - Returned when nothing usable survives. Defaults to `\"file\"`.\n * @returns A safe single path segment.\n *\n * @example\n * ```ts\n * sanitizeFilename(\"../../etc/passwd\"); // \"etcpasswd\"\n * sanitizeFilename(\"report.pdf.\");      // \"report.pdf\"\n * sanitizeFilename(\"CON.txt\");          // \"file\"\n * ```\n */\nexport function sanitizeFilename(filename: string, fallback = \"file\"): string {\n\tif (typeof filename !== \"string\" || filename.length === 0) return fallback;\n\n\tlet safe = filename\n\t\t.normalize(\"NFC\")\n\t\t.replace(UNSAFE_FILENAME_CHARS, \"\")\n\t\t.replace(/^\\.+/, \"\")\n\t\t.replace(/[. ]+$/, \"\")\n\t\t.trim();\n\n\tif (safe.length === 0) return fallback;\n\tif (RESERVED_WINDOWS_NAMES.test(safe)) return fallback;\n\n\tif (safe.length > MAX_FILENAME_LENGTH) {\n\t\tconst extension = path.extname(safe).slice(0, MAX_PRESERVED_EXTENSION);\n\t\tsafe = safe.slice(0, MAX_FILENAME_LENGTH - extension.length) + extension;\n\t}\n\n\treturn safe;\n}\n\n//#endregion\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCZ,SAAgB,qBACf,eACA,eACA,UAA8B,CAAC,GACf;CAChB,IAAI,OAAO,kBAAkB,YAAY,OAAO,kBAAkB,UACjE,OAAO;CAER,IAAI,cAAc,WAAW,GAAG,OAAO;CAGvC,IAAI,cAAc,SAAS,GAAG,KAAK,cAAc,SAAS,GAAG,GAC5D,OAAO;CAGR,MAAM,EAAE,kBAAkB,SAAS;CAEnC,MAAM,OAAO,KAAK,QAAQ,aAAa;CACvC,MAAM,YAAY,KAAK,QAAQ,MAAM,aAAa;CAClD,MAAM,WAAW,KAAK,SAAS,MAAM,SAAS;CAE9C,IAAI,aAAa,IAChB,OAAO,kBAAkB,YAAY;CAKtC,IAAI,aAAa,QAAQ,SAAS,WAAW,KAAK,KAAK,KAAK,KAAK,KAAK,WAAW,QAAQ,GACxF,OAAO;CAGR,OAAO;AACR;;;;;;;;;AAUA,SAAgB,gBACf,eACA,eACA,SACU;CACV,OAAO,qBAAqB,eAAe,eAAe,OAAO,MAAM;AACxE;;;;;AAWA,MAAM,wBAAwB;;;;;AAM9B,MAAM,yBAAyB;;AAG/B,MAAM,sBAAsB;;AAG5B,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;AAyBhC,SAAgB,iBAAiB,UAAkB,WAAW,QAAgB;CAC7E,IAAI,OAAO,aAAa,YAAY,SAAS,WAAW,GAAG,OAAO;CAElE,IAAI,OAAO,SACT,UAAU,KAAK,CAAC,CAChB,QAAQ,uBAAuB,EAAE,CAAC,CAClC,QAAQ,QAAQ,EAAE,CAAC,CACnB,QAAQ,UAAU,EAAE,CAAC,CACrB,KAAK;CAEP,IAAI,KAAK,WAAW,GAAG,OAAO;CAC9B,IAAI,uBAAuB,KAAK,IAAI,GAAG,OAAO;CAE9C,IAAI,KAAK,SAAS,qBAAqB;EACtC,MAAM,YAAY,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,uBAAuB;EACrE,OAAO,KAAK,MAAM,GAAG,sBAAsB,UAAU,MAAM,IAAI;CAChE;CAEA,OAAO;AACR"}

package/lib/sanitize.d.mts

@@ -11,14 +11,14 @@ type SyncSchema<T> = Schema.Codec<T, unknown, never>;
  * Schema constraining a URL protocol to the recognized safe set.
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
-declare const UrlProtocolSchema: Schema.Literals<readonly ["http:", "https:", "mailto:", "tel:", "ftp:"]>;
+export declare const UrlProtocolSchema: Schema.Literals<readonly ["http:", "https:", "mailto:", "tel:", "ftp:"]>;
 /** One of the protocols accepted by {@link UrlProtocolSchema}. */
-type UrlProtocol = typeof UrlProtocolSchema.Type;
+export type UrlProtocol = typeof UrlProtocolSchema.Type;
 /**
  * Schema for the per-category toggles that drive {@link redactPII}.
  * @compliance NIST 800-53 AU-3 (Content of Audit Records)
  */
-declare const PIIRedactionOptionsSchema: Schema.Struct<{
+export declare const PIIRedactionOptionsSchema: Schema.Struct<{
   readonly redactEmails: Schema.optional<Schema.Boolean>;
   readonly redactPhones: Schema.optional<Schema.Boolean>;
   readonly redactSSN: Schema.optional<Schema.Boolean>;
@@ -27,20 +27,20 @@ declare const PIIRedactionOptionsSchema: Schema.Struct<{
   readonly redactDates: Schema.optional<Schema.Boolean>;
 }>;
 /** Decoded options accepted by {@link redactPIIEffect} / {@link redactPII}. */
-type PIIRedactionOptions = typeof PIIRedactionOptionsSchema.Type;
+export type PIIRedactionOptions = typeof PIIRedactionOptionsSchema.Type;
 /**
  * Schema for the options controlling {@link validateUserInputEffect}.
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
-declare const UserInputOptionsSchema: Schema.Struct<{
+export declare const UserInputOptionsSchema: Schema.Struct<{
   readonly maxLength: Schema.optional<Schema.Int>;
   readonly allowHtml: Schema.optional<Schema.Boolean>;
   readonly allowNewlines: Schema.optional<Schema.Boolean>;
   readonly trimWhitespace: Schema.optional<Schema.Boolean>;
 }>;
 /** Decoded options accepted by {@link validateUserInputEffect}. */
-type UserInputOptions = typeof UserInputOptionsSchema.Type;
-declare const SafeUrlSchema: Schema.String;
+export type UserInputOptions = typeof UserInputOptionsSchema.Type;
+export declare const SafeUrlSchema: Schema.String;
 /**
  * A URL string vouched safe against scheme-based injection. Mint one by
  * narrowing through the {@link isValidUrl} type guard (backed by
@@ -52,13 +52,13 @@ declare const SafeUrlSchema: Schema.String;
  * It does **not** guarantee the host is reachable or trusted — for that, validate the
  * resolved origin with `isAllowedOrigin` from `@resq-systems/security/controls`.
  */
-type SafeUrl = Brand<string, "SafeUrl">;
+export type SafeUrl = Brand<string, "SafeUrl">;
 /**
  * Schema for a sanitized HTML-safe string — validates the value is a string; the
  * actual escaping is applied at runtime by the sanitization helpers.
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
-declare const SanitizedStringSchema: Schema.String;
+export declare const SanitizedStringSchema: Schema.String;
 /**
  * A string carrying the {@link SanitizedStringSchema} contract. The schema is
  * `S.String` alone, so decoding asserts only that the value is a string —
@@ -66,7 +66,7 @@ declare const SanitizedStringSchema: Schema.String;
  * (e.g. {@link escapeHtml}). The type name signals intent, not a proof of
  * escaping.
  */
-type SanitizedString = typeof SanitizedStringSchema.Type;
+export type SanitizedString = typeof SanitizedStringSchema.Type;
 /**
  * Schema for email address validation.
  *
@@ -75,43 +75,43 @@ type SanitizedString = typeof SanitizedStringSchema.Type;
  * sync with `@resq-systems/email-templates`'s `EmailAddress` brand.
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
-declare const EmailSchema: Schema.String;
+export declare const EmailSchema: Schema.String;
 /**
  * An email address that matches {@link EmailSchema}. Mint one by narrowing
  * through the {@link isValidEmail} type guard. The brand guarantees only
  * syntactic well-formedness (including IDN/Punycode TLDs) — not that the
  * mailbox exists or is deliverable.
  */
-type Email = Brand<string, "Email">;
+export type Email = Brand<string, "Email">;
 /**
  * Schema for phone number validation (US format).
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
-declare const PhoneNumberSchema: Schema.String;
+export declare const PhoneNumberSchema: Schema.String;
 /**
  * A US-format phone number matching {@link PhoneNumberSchema}. Mint one by
  * narrowing through the {@link isValidPhone} type guard. The brand asserts
  * the digit/separator shape only; it neither normalizes formatting nor
  * confirms the number is assigned.
  */
-type PhoneNumber = Brand<string, "PhoneNumber">;
+export type PhoneNumber = Brand<string, "PhoneNumber">;
 /**
  * Schema for SSN validation (US format).
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
-declare const SSNSchema: Schema.String;
+export declare const SSNSchema: Schema.String;
 /**
  * A US Social Security Number matching {@link SSNSchema}. Mint one by
  * narrowing through the {@link isValidSSN} type guard. The brand asserts
  * the `NNN-NN-NNNN` shape only — it does not validate area/group ranges or
  * confirm the number was ever issued. Treat any value as sensitive PII.
  */
-type SSN = Brand<string, "SSN">;
+export type SSN = Brand<string, "SSN">;
 /**
  * Schema for credit card number validation.
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
-declare const CreditCardSchema: Schema.String;
+export declare const CreditCardSchema: Schema.String;
 /**
  * A card number matching the {@link CreditCardSchema} pattern (13–16 digits
  * with optional group separators). No exported type guard mints this brand;
@@ -119,18 +119,18 @@ declare const CreditCardSchema: Schema.String;
  * shape check only — it performs **no** Luhn checksum and does not identify
  * the issuer. Treat any value as sensitive PII.
  */
-type CreditCard = Brand<string, "CreditCard">;
+export type CreditCard = Brand<string, "CreditCard">;
 /**
  * Schema for IPv4 address validation.
  */
-declare const IPv4Schema: Schema.String;
+export declare const IPv4Schema: Schema.String;
 /**
  * A dotted-quad string matching {@link IPv4Schema}. No exported type guard
  * mints this brand; decode {@link IPv4Schema} directly. The pattern checks
  * four dot-separated groups of 1–3 digits only — it does **not** bound each
  * octet to `0–255`, so `999.0.0.1` still matches.
  */
-type IPv4 = Brand<string, "IPv4">;
+export type IPv4 = Brand<string, "IPv4">;
 /**
  * Escapes special HTML characters in a string to their corresponding HTML entities,
  * preventing direct injection of HTML and JavaScript when rendering untrusted content.
@@ -145,7 +145,7 @@ type IPv4 = Brand<string, "IPv4">;
  * // "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"
  * ```
  */
-declare const escapeHtml: (text: string) => string;
+export declare const escapeHtml: (text: string) => string;
 /**
  * Validates and sanitizes a user-supplied URL using Effect Schema.
  * Returns an Exit with the sanitized URL or an error.
@@ -171,7 +171,7 @@ declare const escapeHtml: (text: string) => string;
  * // Exit.fail(...)
  * ```
  */
-declare const sanitizeUrlEffect: (url: string, allowedProtocols?: readonly UrlProtocol[]) => Exit.Exit<string, Schema.SchemaError>;
+export declare const sanitizeUrlEffect: (url: string, allowedProtocols?: readonly UrlProtocol[]) => Exit.Exit<string, Schema.SchemaError>;
 /**
  * Validates and sanitizes a user-supplied URL, ensuring it conforms to allowed protocols
  * and is not a vector for injection attacks like `javascript:` or `data:`.
@@ -187,7 +187,7 @@ declare const sanitizeUrlEffect: (url: string, allowedProtocols?: readonly UrlPr
  * sanitizeUrl('javascript:alert(1)'); // ''
  * ```
  */
-declare const sanitizeUrl: (url: string, allowedProtocols?: readonly UrlProtocol[]) => string;
+export declare const sanitizeUrl: (url: string, allowedProtocols?: readonly UrlProtocol[]) => string;
 /**
  * Sanitizes HTML to prevent XSS attacks.
  * Uses DOMPurify under the hood. If DOM is not available (e.g. server-side without JSDOM),
@@ -207,7 +207,7 @@ declare const sanitizeUrl: (url: string, allowedProtocols?: readonly UrlProtocol
  * @returns The sanitized HTML string, or the escaped string when no DOM is
  *   available.
  */
-declare const sanitizeHtml: (html: string, options?: Config) => string;
+export declare const sanitizeHtml: (html: string, options?: Config) => string;
 /**
  * Validates user input using Effect Schema and returns an Exit.
  *
@@ -224,7 +224,7 @@ declare const sanitizeHtml: (html: string, options?: Config) => string;
  *   to `maxLength`; failure carries a {@link S.SchemaError}.
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
-declare const validateUserInputEffect: (input: string, options?: UserInputOptions) => Exit.Exit<string, Schema.SchemaError>;
+export declare const validateUserInputEffect: (input: string, options?: UserInputOptions) => Exit.Exit<string, Schema.SchemaError>;
 /**
  * Validates and sanitizes generic user input by trimming, removing HTML tags (unless allowed),
  * normalizing whitespace, and removing dangerous patterns to prevent XSS and basic injection flaws.
@@ -241,7 +241,7 @@ declare const validateUserInputEffect: (input: string, options?: UserInputOption
  * validateUserInput('<script>alert(1)</script>test', 100); // "test"
  * ```
  */
-declare const validateUserInput: (input: string, maxLength?: number, allowHtml?: boolean) => string;
+export declare const validateUserInput: (input: string, maxLength?: number, allowHtml?: boolean) => string;
 /**
  * Safely parses JSON with Effect Schema validation and prototype pollution protection.
  *
@@ -267,7 +267,7 @@ declare const validateUserInput: (input: string, maxLength?: number, allowHtml?:
  * // Option.some({ name: 'John', age: 30 })
  * ```
  */
-declare const parseJsonWithSchema: <A>(jsonString: string, schema: SyncSchema<A>) => Option.Option<A>;
+export declare const parseJsonWithSchema: <A>(jsonString: string, schema: SyncSchema<A>) => Option.Option<A>;
 /**
  * Sanitizes and safely parses a JSON string, removing suspicious syntax elements that could
  * potentially result in JSON polyglot exploits or prototype pollution.
@@ -288,7 +288,7 @@ declare const parseJsonWithSchema: <A>(jsonString: string, schema: SyncSchema<A>
  * // obj: unknown — narrow before use, or use parseJsonWithSchema
  * ```
  */
-declare const sanitizeJson: (jsonString: string) => unknown;
+export declare const sanitizeJson: (jsonString: string) => unknown;
 /**
  * Strips ANSI escape sequences from a string.
  *
@@ -310,7 +310,7 @@ declare const sanitizeJson: (jsonString: string) => unknown;
  * stripAnsi('\x1b[31mRed text\x1b[0m'); // 'Red text'
  * ```
  */
-declare const stripAnsi: (text: string) => string;
+export declare const stripAnsi: (text: string) => string;
 /**
  * Redacts PII from text using Effect Schema validated options.
  *
@@ -325,7 +325,7 @@ declare const stripAnsi: (text: string) => string;
  *   carries a {@link S.SchemaError} from invalid `options`.
  * @compliance NIST 800-53 AU-3 (Content of Audit Records)
  */
-declare const redactPIIEffect: (text: string, options?: PIIRedactionOptions) => Exit.Exit<string, Schema.SchemaError>;
+export declare const redactPIIEffect: (text: string, options?: PIIRedactionOptions) => Exit.Exit<string, Schema.SchemaError>;
 /**
  * Redacts common PII patterns in a string for safe logging.
  * Detects and masks SSNs, credit cards, emails, phone numbers, etc.
@@ -350,7 +350,7 @@ declare const redactPIIEffect: (text: string, options?: PIIRedactionOptions) =>
  * // 'SSN: [SSN]'
  * ```
  */
-declare const redactPII: (text: string, options?: PIIRedactionOptions & {
+export declare const redactPII: (text: string, options?: PIIRedactionOptions & {
   customPatterns?: Array<{
     pattern: RegExp;
     replacement: string;
@@ -379,7 +379,7 @@ declare const redactPII: (text: string, options?: PIIRedactionOptions & {
  * // '{\n  "user": "john",\n  "password": "[REDACTED]"\n}'
  * ```
  */
-declare const safeStringify: (obj: unknown, sensitiveKeys?: string[], indent?: number) => string;
+export declare const safeStringify: (obj: unknown, sensitiveKeys?: string[], indent?: number) => string;
 /**
  * Validates if a string is a valid email address using Effect Schema.
  *
@@ -389,7 +389,7 @@ declare const safeStringify: (obj: unknown, sensitiveKeys?: string[], indent?: n
  * @param email - The string to validate.
  * @returns true if valid email, false otherwise.
  */
-declare const isValidEmail: (email: string) => email is Email;
+export declare const isValidEmail: (email: string) => email is Email;
 /**
  * Validates if a string is a valid phone number using Effect Schema.
  *
@@ -398,7 +398,7 @@ declare const isValidEmail: (email: string) => email is Email;
  * @param phone - The string to validate.
  * @returns true if valid phone number, false otherwise.
  */
-declare const isValidPhone: (phone: string) => phone is PhoneNumber;
+export declare const isValidPhone: (phone: string) => phone is PhoneNumber;
 /**
  * Validates if a string is a valid SSN using Effect Schema.
  *
@@ -407,7 +407,7 @@ declare const isValidPhone: (phone: string) => phone is PhoneNumber;
  * @param ssn - The string to validate.
  * @returns true if valid SSN, false otherwise.
  */
-declare const isValidSSN: (ssn: string) => ssn is SSN;
+export declare const isValidSSN: (ssn: string) => ssn is SSN;
 /**
  * Validates if a string is a safe URL using Effect Schema.
  *
@@ -416,7 +416,6 @@ declare const isValidSSN: (ssn: string) => ssn is SSN;
  * @param url - The string to validate.
  * @returns true if valid and safe URL, false otherwise.
  */
-declare const isValidUrl: (url: string) => url is SafeUrl;
+export declare const isValidUrl: (url: string) => url is SafeUrl;
 //#endregion
-export { 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 };
 //# sourceMappingURL=sanitize.d.mts.map

package/lib/sanitize.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.d.mts","names":[],"sources":["../src/sanitize.ts"],"mappings":";;;;;;;;KAoCK,WAAW,KAAK,OAAE,MAAM;;;;;cAShB,mBAAiB,OAAA;;KAElB,qBAAqB,kBAAkB;;;;;cAMtC,2BAAyB,OAAA;;;;;;;;;KAS1B,6BAA6B,0BAA0B;;;;;cAMtD,wBAAsB,OAAA;;;;;;;KAOvB,0BAA0B,uBAAuB;cAuBhD,eAAa,OAAA;;;;;;;;;;;;KA4Bd,UAAU;;;;;;cAOT,uBAAqB,OAAA;;;;;;;;KAQtB,yBAAyB,sBAAsB;;;;;;;;;cAU9C,aAAW,OAAA;;;;;;;KASZ,QAAQ;;;;;cAMP,mBAAiB,OAAA;;;;;;;KASlB,cAAc;;;;;cAMb,WAAS,OAAA;;;;;;;KAOV,MAAM;;;;;cAML,kBAAgB,OAAA;;;;;;;;KAUjB,aAAa;;;;cAKZ,YAAU,OAAA;;;;;;;KAOX,OAAO;;;;;;;;;;;;;;;cAmBN,aAAc;;;;;;;;;;;;;;;;;;;;;;;;;;cAsCd,oBACZ,aACA,4BAA2B,kBACzB,KAAK,aAAa,OAAE;;;;;;;;;;;;;;;;cA+CV,cACZ,aACA,4BAA2B;;;;;;;;;;;;;;;;;;;;cAyGf,eAAgB,cAAc,UAAU;;;;;;;;;;;;;;;;;cA6BxC,0BACZ,eACA,UAAS,qBACP,KAAK,aAAa,OAAE;;;;;;;;;;;;;;;;;cA+DV,oBAAqB,eAAe,oBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;cAmFrD,sBAAuB,GACnC,oBACA,QAAQ,WAAW,OACjB,OAAO,OAAO;;;;;;;;;;;;;;;;;;;;;cA0CJ,eAAgB;;;;;;;;;;;;;;;;;;;;;;cA0ChB,YAAa;;;;;;;;;;;;;;;cAoEb,kBACZ,cACA,UAAS,wBACP,KAAK,aAAa,OAAE;;;;;;;;;;;;;;;;;;;;;;;;;cAuEV,YACZ,cACA,UAAS;EACR,iBAAiB;IAAQ,SAAS;IAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;cA0D/B,gBACZ,cACA,0BAUA;;;;;;;;;;cA+BY,eAAgB,kBAAgB,SAAS;;;;;;;;;cAYzC,eAAgB,kBAAgB,SAAS;;;;;;;;;cAYzC,aAAc,gBAAc,OAAO;;;;;;;;;cAYnC,aAAc,gBAAc,OAAO"}
+{"version":3,"file":"sanitize.d.mts","names":[],"sources":["../src/sanitize.ts"],"mappings":";;;;;;;;KAqCK,WAAW,KAAK,OAAE,MAAM;;;;;qBAShB,mBAAiB,OAAA;;YAElB,qBAAqB,kBAAkB;;;;;qBAMtC,2BAAyB,OAAA;;;;;;;;;YAS1B,6BAA6B,0BAA0B;;;;;qBAMtD,wBAAsB,OAAA;;;;;;;YAOvB,0BAA0B,uBAAuB;qBAuBhD,eAAa,OAAA;;;;;;;;;;;;YA4Bd,UAAU;;;;;;qBAOT,uBAAqB,OAAA;;;;;;;;YAQtB,yBAAyB,sBAAsB;;;;;;;;;qBAU9C,aAAW,OAAA;;;;;;;YASZ,QAAQ;;;;;qBAMP,mBAAiB,OAAA;;;;;;;YASlB,cAAc;;;;;qBAMb,WAAS,OAAA;;;;;;;YAOV,MAAM;;;;;qBAML,kBAAgB,OAAA;;;;;;;;YAUjB,aAAa;;;;qBAKZ,YAAU,OAAA;;;;;;;YAOX,OAAO;;;;;;;;;;;;;;;qBAmBN,aAAc;;;;;;;;;;;;;;;;;;;;;;;;;;qBAsCd,oBACZ,aACA,4BAA2B,kBACzB,KAAK,aAAa,OAAE;;;;;;;;;;;;;;;;qBA+CV,cACZ,aACA,4BAA2B;;;;;;;;;;;;;;;;;;;;qBAyGf,eAAgB,cAAc,UAAU;;;;;;;;;;;;;;;;;qBA6BxC,0BACZ,eACA,UAAS,qBACP,KAAK,aAAa,OAAE;;;;;;;;;;;;;;;;;qBA+DV,oBAAqB,eAAe,oBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmFrD,sBAAuB,GACnC,oBACA,QAAQ,WAAW,OACjB,OAAO,OAAO;;;;;;;;;;;;;;;;;;;;;qBA0CJ,eAAgB;;;;;;;;;;;;;;;;;;;;;;qBA0ChB,YAAa;;;;;;;;;;;;;;;qBAoEb,kBACZ,cACA,UAAS,wBACP,KAAK,aAAa,OAAE;;;;;;;;;;;;;;;;;;;;;;;;;qBAuEV,YACZ,cACA,UAAS;EACR,iBAAiB;IAAQ,SAAS;IAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;qBA0D/B,gBACZ,cACA,0BAUA;;;;;;;;;;qBA+BY,eAAgB,kBAAgB,SAAS;;;;;;;;;qBAYzC,eAAgB,kBAAgB,SAAS;;;;;;;;;qBAYzC,aAAc,gBAAc,OAAO;;;;;;;;;qBAYnC,aAAc,gBAAc,OAAO"}