@resq-systems/security 1.0.0

package/lib/crypto.mjs

@@ -0,0 +1,294 @@
+import { brandRefiner, toPositiveInt, unsafeBrand } from "@resq-systems/types";
+import { createCipheriv, createDecipheriv, createHash, randomBytes, scrypt } from "node:crypto";
+import { promisify } from "node:util";
+//#region src/crypto.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.
+*/
+/**
+* @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)
+*/
+const scryptAsync = promisify(scrypt);
+/** AES-256-GCM encryption algorithm */
+const ALGORITHM = "aes-256-gcm";
+/** Initialization vector length in bytes */
+const IV_LENGTH = 16;
+/** Authentication tag length in bytes */
+const AUTH_TAG_LENGTH = 16;
+/** Salt length for key derivation */
+const SALT_LENGTH = 32;
+/** Derived key length (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;
+/**
+* Smart constructors for {@link EncryptionKey}. The runtime check is a
+* non-empty string — scrypt stretches any non-empty secret into a 256-bit
+* key, so entropy is the caller's responsibility, but an empty key is
+* always a bug.
+*/
+const EncryptionKeyBrand = brandRefiner((value) => value.length > 0, "encryption key");
+/** Type guard: `true` when `value` is a usable {@link EncryptionKey}. */
+const isEncryptionKey = EncryptionKeyBrand.is;
+/** Assert `value` is a non-empty secret and brand it, throwing otherwise. */
+const toEncryptionKey = EncryptionKeyBrand.from;
+/** Return `value` branded as an {@link EncryptionKey}, or `null` when empty. */
+const coerceEncryptionKey = EncryptionKeyBrand.coerce;
+/** Brand `value` as an {@link EncryptionKey} without checking. */
+const unsafeEncryptionKey = EncryptionKeyBrand.unsafe;
+/**
+* Smart constructors for {@link Ciphertext}. The runtime check verifies the
+* value base64-decodes to at least the fixed envelope header size — enough
+* to reject truncated or non-base64 input before it reaches
+* {@link decryptData}.
+*/
+const CiphertextBrand = brandRefiner((value) => value.length > 0 && Buffer.from(value, "base64").length >= CIPHERTEXT_MIN_BYTES, "ciphertext");
+/** Type guard: `true` when `value` is a well-formed {@link Ciphertext} envelope. */
+const isCiphertext = CiphertextBrand.is;
+/** Assert `value` is a well-formed envelope and brand it, throwing otherwise. */
+const toCiphertext = CiphertextBrand.from;
+/** Return `value` branded as a {@link Ciphertext}, or `null` when malformed. */
+const coerceCiphertext = CiphertextBrand.coerce;
+/** Brand `value` as a {@link Ciphertext} without checking. */
+const unsafeCiphertext = CiphertextBrand.unsafe;
+/**
+* Derive a 32-byte (AES-256) key from a password and per-record salt
+* using scrypt with Node's default cost parameters.
+*
+* Internal helper — used inside the encrypt/decrypt round-trip because
+* the salt must travel alongside the ciphertext for decryption to
+* succeed.
+*
+* @internal
+*/
+async function deriveKey(password, salt) {
+	return await scryptAsync(password, salt, KEY_LENGTH);
+}
+/**
+* Encrypt a UTF-8 string with AES-256-GCM authenticated encryption.
+*
+* Each call generates a fresh random salt and IV — the same plaintext
+* encrypted twice with the same `encryptionKey` produces different
+* ciphertexts, which is the property you want for at-rest encryption.
+*
+* Output layout (base64-encoded): `salt(32) | iv(16) | authTag(16) | ciphertext(*)`.
+* The companion {@link decryptData} understands this layout.
+*
+* @param plaintext - UTF-8 string to encrypt.
+* @param encryptionKey - Caller-supplied secret. Treated as a password
+*   and stretched into a 256-bit AES key via scrypt; can be any length,
+*   though a high-entropy secret (≥ 32 bytes) is strongly preferred.
+*
+* @returns A self-contained base64 string. Store or transmit verbatim;
+*   the salt/IV are recovered on decryption.
+*
+* @throws From the underlying Node crypto primitives if `encryptionKey`
+*   is empty or scrypt fails.
+*
+* @compliance NIST 800-53 SC-28 (Protection of Information at Rest),
+*   SC-13 (Cryptographic Protection).
+*
+* @example
+* ```ts
+* const ct = await encryptData("user@example.com", process.env.PII_KEY!);
+* await db.users.update(id, { email: ct });
+* ```
+*/
+async function encryptData(plaintext, encryptionKey) {
+	const salt = randomBytes(SALT_LENGTH);
+	const key = await deriveKey(encryptionKey, salt);
+	const iv = randomBytes(IV_LENGTH);
+	const cipher = createCipheriv(ALGORITHM, key, iv);
+	const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+	const authTag = cipher.getAuthTag();
+	const combined = Buffer.concat([
+		salt,
+		iv,
+		authTag,
+		encrypted
+	]);
+	return CiphertextBrand.unsafe(combined.toString("base64"));
+}
+/**
+* Reverse {@link encryptData}. Verifies the GCM authentication tag
+* before returning plaintext — tampered ciphertexts throw.
+*
+* @param encryptedData - Base64 string produced by {@link encryptData}.
+* @param encryptionKey - Same key/password used to encrypt. Wrong keys
+*   throw an "Unsupported state or unable to authenticate data" error
+*   from Node — the authenticated tag failure is indistinguishable from
+*   tampering, by design.
+*
+* @returns The original UTF-8 plaintext.
+*
+* @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.
+*
+* @example
+* ```ts
+* const plaintext = await decryptData(stored, process.env.PII_KEY!);
+* ```
+*/
+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);
+	decipher.setAuthTag(authTag);
+	return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+}
+/**
+* Compute a SHA-256 digest of a UTF-8 string and return it as lowercase
+* hex.
+*
+* **Not for password storage.** SHA-256 is fast by design — use a
+* deliberately slow KDF (`bcrypt`, `argon2`, or `scrypt`) for
+* password-equivalent material. This helper is intended for
+* non-reversible identifiers, content hashes, and idempotency keys.
+*
+* @param data - UTF-8 input.
+* @returns 64-character lowercase hex digest.
+*
+* @example
+* ```ts
+* hashData("hello"); // → "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+* ```
+*/
+function hashData(data) {
+	return unsafeBrand(createHash("sha256").update(data).digest("hex"));
+}
+/**
+* Generate a cryptographically random hex token suitable for session
+* IDs, password-reset tokens, CSRF tokens, and similar single-use
+* secrets.
+*
+* @param length - Number of random *bytes* to draw as a {@link PositiveInt}
+*   (the returned hex string is twice as long). Default `32` ⇒ 64-char hex
+*   / 256 bits of entropy. Construct non-default lengths with `toPositiveInt`
+*   so zero-byte and negative lengths are unrepresentable.
+* @returns A {@link SecureToken}: lowercase hex string of length `length * 2`.
+*
+* @example
+* ```ts
+* import { toPositiveInt } from "@resq-systems/types";
+* generateSecureToken();                 // 64-char hex (256-bit entropy)
+* generateSecureToken(toPositiveInt(16)); // 32-char hex (128-bit entropy)
+* ```
+*/
+function generateSecureToken(length = toPositiveInt(32)) {
+	return unsafeBrand(randomBytes(length).toString("hex"));
+}
+/**
+* Mask an arbitrary PII string for safe logging — keeps the first two
+* and last two characters and replaces everything in between with
+* asterisks. Strings of length ≤ 4 are fully masked as `"****"`.
+*
+* @param data - Raw PII string.
+* @returns Masked representation safe for logs.
+*
+* @example
+* ```ts
+* maskPII("4242424242424242"); // → "42************42"
+* maskPII("AB12");              // → "****"
+* ```
+*/
+function maskPII(data) {
+	if (data.length <= 4) return unsafeBrand("****");
+	return unsafeBrand(`${data.slice(0, 2)}${"*".repeat(data.length - 4)}${data.slice(-2)}`);
+}
+/**
+* Mask an email address while preserving the domain — useful for
+* deduplication and support workflows where the domain is non-PII but
+* the local part identifies the user.
+*
+* @param email - Full email. Falls back to {@link maskPII} if the input
+*   does not contain a valid `local@domain` shape.
+* @returns Masked email; e.g. `"j*****e@example.com"`.
+*
+* @example
+* ```ts
+* maskEmail("jane@example.com"); // → "j**e@example.com"
+* maskEmail("ab@example.com");   // → "**@example.com"
+* maskEmail("not-an-email");     // → "no********il" (maskPII fallback)
+* ```
+*/
+function maskEmail(email) {
+	const parts = email.split("@");
+	const local = parts[0];
+	const domain = parts[1];
+	if (!domain || !local) return maskPII(email);
+	return unsafeBrand(`${local.length > 2 ? `${local[0]}${"*".repeat(local.length - 2)}${local[local.length - 1]}` : "**"}@${domain}`);
+}
+/**
+* Recursively shallow-copy an object, replacing any field whose key
+* contains a sensitive substring (case-insensitive) with `[REDACTED]`,
+* and masking string fields whose key contains `"email"` via
+* {@link maskEmail}.
+*
+* Designed for log structures — preserves shape so log queries continue
+* to work, but ensures secrets and identifiers don't leak. Use as a
+* defensive layer **before** writing structured log lines.
+*
+* @param obj - Object to sanitize. Original is not mutated.
+* @param sensitiveFields - Substring allow-list. Defaults to
+*   `["password", "passwordHash", "token", "secret",
+*   "twoFactorSecret", "apiKey"]`. Substrings match anywhere in the
+*   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.
+*
+* @example
+* ```ts
+* sanitizeForLogging({
+*   id: 1,
+*   email: "u@x.com",
+*   apiKey: "sk-...",
+*   nested: { token: "..." },
+* });
+* // → { id: 1, email: "u@x.com" (masked), apiKey: "[REDACTED]", nested: { token: "[REDACTED]" } }
+* ```
+*/
+function sanitizeForLogging(obj, sensitiveFields = [
+	"password",
+	"passwordHash",
+	"token",
+	"secret",
+	"twoFactorSecret",
+	"apiKey"
+]) {
+	const sanitized = {};
+	for (const [key, value] of Object.entries(obj)) if (sensitiveFields.some((field) => key.toLowerCase().includes(field.toLowerCase()))) sanitized[key] = "[REDACTED]";
+	else if (key.toLowerCase().includes("email") && typeof value === "string") sanitized[key] = maskEmail(value);
+	else if (typeof value === "object" && value !== null) sanitized[key] = sanitizeForLogging(value, sensitiveFields);
+	else sanitized[key] = value;
+	return sanitized;
+}
+//#endregion
+export { coerceCiphertext, coerceEncryptionKey, decryptData, encryptData, generateSecureToken, hashData, isCiphertext, isEncryptionKey, maskEmail, maskPII, sanitizeForLogging, toCiphertext, toEncryptionKey, unsafeCiphertext, unsafeEncryptionKey };
+
+//# sourceMappingURL=crypto.mjs.map

package/lib/crypto.mjs.map

@@ -0,0 +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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"}

package/lib/index.d.mts

@@ -0,0 +1,4 @@
+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 { 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 { 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, getThreatErrorMessage, hashData, isCiphertext, isEncryptionKey, isSafeInput, isValidEmail, isValidPhone, isValidSSN, isValidUrl, maskEmail, maskPII, normalizeUnicode, parseJsonWithSchema, redactPII, redactPIIEffect, safeStringify, sanitizeForDisplay, sanitizeForLogging, sanitizeHtml, sanitizeJson, sanitizeUrl, sanitizeUrlEffect, stripAnsi, toCiphertext, toEncryptionKey, unsafeCiphertext, unsafeEncryptionKey, validateSafeEmail, validateSafeName, validateSafeText, validateUserInput, validateUserInputEffect };

package/lib/index.mjs

@@ -0,0 +1,4 @@
+import { coerceCiphertext, coerceEncryptionKey, decryptData, encryptData, generateSecureToken, hashData, isCiphertext, isEncryptionKey, maskEmail, maskPII, sanitizeForLogging, toCiphertext, toEncryptionKey, unsafeCiphertext, unsafeEncryptionKey } from "./crypto.mjs";
+import { THREAT_DETECTED_MESSAGE, containsCommandInjection, containsHomoglyphs, containsNoSQLInjection, containsPathTraversal, containsSQLInjection, containsXSSPatterns, detectThreatPatterns, getThreatErrorMessage, isSafeInput, normalizeUnicode, sanitizeForDisplay, validateSafeEmail, validateSafeName, validateSafeText } from "./validators.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, getThreatErrorMessage, hashData, isCiphertext, isEncryptionKey, isSafeInput, isValidEmail, isValidPhone, isValidSSN, isValidUrl, maskEmail, maskPII, normalizeUnicode, parseJsonWithSchema, redactPII, redactPIIEffect, safeStringify, sanitizeForDisplay, sanitizeForLogging, sanitizeHtml, sanitizeJson, sanitizeUrl, sanitizeUrlEffect, stripAnsi, toCiphertext, toEncryptionKey, unsafeCiphertext, unsafeEncryptionKey, validateSafeEmail, validateSafeName, validateSafeText, validateUserInput, validateUserInputEffect };

package/lib/sanitize.d.mts

@@ -0,0 +1,316 @@
+import { Brand } from "@resq-systems/types";
+import { Exit, Option, Schema } from "effect";
+import { Config } from "dompurify";
+
+//#region src/sanitize.d.ts
+/**
+ * A Schema with DecodingServices constrained to `never`, allowing synchronous decoding.
+ */
+type SyncSchema<T> = Schema.Codec<T, unknown, never>;
+/**
+ * Schema for URL protocol validation
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ */
+declare const UrlProtocolSchema: Schema.Literals<readonly ["http:", "https:", "mailto:", "tel:", "ftp:"]>;
+type UrlProtocol = typeof UrlProtocolSchema.Type;
+/**
+ * Schema for PII redaction options
+ * @compliance NIST 800-53 AU-3 (Content of Audit Records)
+ */
+declare const PIIRedactionOptionsSchema: Schema.Struct<{
+  readonly redactEmails: Schema.optional<Schema.Boolean>;
+  readonly redactPhones: Schema.optional<Schema.Boolean>;
+  readonly redactSSN: Schema.optional<Schema.Boolean>;
+  readonly redactCreditCards: Schema.optional<Schema.Boolean>;
+  readonly redactIPs: Schema.optional<Schema.Boolean>;
+  readonly redactDates: Schema.optional<Schema.Boolean>;
+}>;
+type PIIRedactionOptions = typeof PIIRedactionOptionsSchema.Type;
+/**
+ * Schema for user input validation options
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ */
+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>;
+}>;
+type UserInputOptions = typeof UserInputOptionsSchema.Type;
+/**
+ * Schema for safe URL - validates URL format and protocol
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ */
+declare const SafeUrlSchema: Schema.String;
+/** A string that has passed {@link isValidUrl} — a validated, injection-safe URL. */
+type SafeUrl = Brand<string, "SafeUrl">;
+/**
+ * Schema for sanitized HTML-safe string (validates as string; escaping done at runtime)
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ */
+declare const SanitizedStringSchema: Schema.String;
+type SanitizedString = typeof SanitizedStringSchema.Type;
+/**
+ * Schema for email address validation
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ */
+declare const EmailSchema: Schema.String;
+/** A string that has passed {@link isValidEmail}. */
+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;
+/** A string that has passed {@link isValidPhone} (US format). */
+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;
+/** A string that has passed {@link isValidSSN} (US format). */
+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;
+/** A string matching the {@link CreditCardSchema} pattern. */
+type CreditCard = Brand<string, "CreditCard">;
+/**
+ * Schema for IPv4 address validation
+ */
+declare const IPv4Schema: Schema.String;
+/** A string matching the {@link IPv4Schema} dotted-quad pattern. */
+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.
+ *
+ * @param text - The plain text to escape.
+ * @returns The escaped string safe for HTML rendering.
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ *
+ * @example
+ * ```typescript
+ * escapeHtml('<script>alert("xss")</script>');
+ * // "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"
+ * ```
+ */
+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.
+ *
+ * @param url - The URL to be validated and sanitized.
+ * @param allowedProtocols - Array of allowed URL protocols.
+ * @returns Exit containing the sanitized URL or an error.
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ *
+ * @example
+ * ```typescript
+ * const result = sanitizeUrlEffect('https://example.com');
+ * // Exit.succeed('https://example.com')
+ *
+ * const invalid = sanitizeUrlEffect('javascript:alert(1)');
+ * // Exit.fail(...)
+ * ```
+ */
+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:`.
+ *
+ * @param url - The URL to be validated and sanitized.
+ * @param allowedProtocols - Array of allowed URL protocols.
+ * @returns The sanitized URL if valid, or an empty string if unsafe.
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ *
+ * @example
+ * ```typescript
+ * sanitizeUrl('https://example.com'); // 'https://example.com'
+ * sanitizeUrl('javascript:alert(1)'); // ''
+ * ```
+ */
+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),
+ * it falls back to escaping all HTML characters for safety.
+ *
+ * NOTE: Server-side HTML sanitization requires `jsdom` to be installed in the consuming application
+ * environment; otherwise, it will fall back to escaping HTML characters.
+ *
+ * @param html - The HTML string to sanitize.
+ * @param options - Optional DOMPurify configuration.
+ * @returns The sanitized HTML string.
+ */
+declare const sanitizeHtml: (html: string, options?: Config) => string;
+/**
+ * Validates user input using Effect Schema and returns an Exit.
+ *
+ * @param input - User input to validate and sanitize.
+ * @param options - Validation options.
+ * @returns Exit containing sanitized input or error.
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ */
+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.
+ *
+ * @param input - User input to validate and sanitize.
+ * @param maxLength - Maximum allowed input length. Excess will be truncated.
+ * @param allowHtml - If true, HTML tags are preserved; otherwise, all tags are stripped.
+ * @returns Sanitized input string with length at most `maxLength`.
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ *
+ * @example
+ * ```typescript
+ * validateUserInput('<p>Hello!</p>', 50); // "Hello!"
+ * validateUserInput('<script>alert(1)</script>test', 100); // "test"
+ * ```
+ */
+declare const validateUserInput: (input: string, maxLength?: number, allowHtml?: boolean) => string;
+/**
+ * Safely parses JSON with Effect Schema validation and prototype pollution protection.
+ *
+ * @template A - The expected schema type
+ * @param jsonString - The JSON string to parse.
+ * @param schema - Effect Schema to validate against.
+ * @returns Option containing the parsed and validated object.
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ *
+ * @example
+ * ```typescript
+ * const UserSchema = S.Struct({ name: S.String, age: S.Number });
+ * const result = parseJsonWithSchema('{"name":"John","age":30}', UserSchema);
+ * // Option.some({ name: 'John', age: 30 })
+ * ```
+ */
+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.
+ *
+ * The result is returned as `unknown` — this function performs **no** schema
+ * validation, so it cannot honestly promise any concrete shape for
+ * attacker-controlled input. Narrow the result yourself, or prefer
+ * {@link parseJsonWithSchema}, which validates against an Effect Schema and
+ * returns a typed `Option`.
+ *
+ * @param jsonString - The JSON string to sanitize and parse.
+ * @returns The parsed value (as `unknown`) if valid, or `null` if invalid.
+ * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ *
+ * @example
+ * ```typescript
+ * const obj = sanitizeJson('{"foo":"bar"}');
+ * // obj: unknown — narrow before use, or use parseJsonWithSchema
+ * ```
+ */
+declare const sanitizeJson: (jsonString: string) => unknown;
+/**
+ * Strips ANSI escape codes from a string.
+ * Useful for cleaning terminal output before logging to files.
+ *
+ * @param text - The text potentially containing ANSI codes.
+ * @returns The text with ANSI codes removed.
+ *
+ * @example
+ * ```typescript
+ * stripAnsi('\x1b[31mRed text\x1b[0m'); // 'Red text'
+ * ```
+ */
+declare const stripAnsi: (text: string) => string;
+/**
+ * Redacts PII from text using Effect Schema validated options.
+ *
+ * @param text - The text to redact PII from.
+ * @param options - Configuration options for redaction.
+ * @returns Exit containing redacted text or error.
+ * @compliance NIST 800-53 AU-3 (Content of Audit Records)
+ */
+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.
+ *
+ * @param text - The text to redact PII from.
+ * @param options - Configuration options for redaction.
+ * @returns The text with PII patterns replaced with redaction markers.
+ * @compliance NIST 800-53 AU-3 (Content of Audit Records)
+ *
+ * @example
+ * ```typescript
+ * redactPII('Contact john@example.com or call 555-123-4567');
+ * // 'Contact [EMAIL] or call [PHONE]'
+ *
+ * redactPII('SSN: 123-45-6789');
+ * // 'SSN: [SSN]'
+ * ```
+ */
+declare const redactPII: (text: string, options?: PIIRedactionOptions & {
+  customPatterns?: Array<{
+    pattern: RegExp;
+    replacement: string;
+  }>;
+}) => string;
+/**
+ * Creates a safe string representation of an object for logging,
+ * automatically redacting sensitive fields.
+ *
+ * @param obj - The object to stringify.
+ * @param sensitiveKeys - Array of key names to redact.
+ * @param indent - JSON indentation (default: 2).
+ * @returns A JSON string with sensitive values redacted.
+ * @compliance NIST 800-53 AU-3 (Content of Audit Records)
+ *
+ * @example
+ * ```typescript
+ * safeStringify({ user: 'john', password: 'secret123' }, ['password']);
+ * // '{\n  "user": "john",\n  "password": "[REDACTED]"\n}'
+ * ```
+ */
+declare const safeStringify: (obj: unknown, sensitiveKeys?: string[], indent?: number) => string;
+/**
+ * Validates if a string is a valid email address using Effect Schema.
+ *
+ * Narrows the input to {@link Email} on success, so validated call sites
+ * carry the brand into downstream code.
+ *
+ * @param email - The string to validate.
+ * @returns true if valid email, false otherwise.
+ */
+declare const isValidEmail: (email: string) => email is Email;
+/**
+ * Validates if a string is a valid phone number using Effect Schema.
+ *
+ * Narrows the input to {@link PhoneNumber} on success.
+ *
+ * @param phone - The string to validate.
+ * @returns true if valid phone number, false otherwise.
+ */
+declare const isValidPhone: (phone: string) => phone is PhoneNumber;
+/**
+ * Validates if a string is a valid SSN using Effect Schema.
+ *
+ * Narrows the input to {@link SSN} on success.
+ *
+ * @param ssn - The string to validate.
+ * @returns true if valid SSN, false otherwise.
+ */
+declare const isValidSSN: (ssn: string) => ssn is SSN;
+/**
+ * Validates if a string is a safe URL using Effect Schema.
+ *
+ * Narrows the input to {@link SafeUrl} on success.
+ *
+ * @param url - The string to validate.
+ * @returns true if valid and safe URL, false otherwise.
+ */
+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

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.mts","names":[],"sources":["../src/sanitize.ts"],"mappings":";;;;;;;;KAiCK,UAAA,MAAgB,MAAA,CAAE,KAAA,CAAM,CAAA;;;;;cAUhB,iBAAA,EAAiB,MAAA,CAAA,QAAA;AAAA,KAClB,WAAA,UAAqB,iBAAA,CAAkB,IAAA;;;;;cAMtC,yBAAA,EAAyB,MAAA,CAAA,MAAA;EAAA;;;;;;;KAQ1B,mBAAA,UAA6B,yBAAA,CAA0B,IAAA;;;;;cAMtD,sBAAA,EAAsB,MAAA,CAAA,MAAA;EAAA;;;;;KAMvB,gBAAA,UAA0B,sBAAA,CAAuB,IAAA;;;;;cAMhD,aAAA,EAAa,MAAA,CAAA,MAAA;;KAiBd,OAAA,GAAU,KAAA;;;;;cAMT,qBAAA,EAAqB,MAAA,CAAA,MAAA;AAAA,KACtB,eAAA,UAAyB,qBAAA,CAAsB,IAAA;;;;;cAM9C,WAAA,EAAW,MAAA,CAAA,MAAA;;KAIZ,KAAA,GAAQ,KAAA;;;AA9CpB;;cAoDa,iBAAA,EAAiB,MAAA,CAAA,MAAA;;KAIlB,WAAA,GAAc,KAAA;;;;;cAMb,SAAA,EAAS,MAAA,CAAA,MAAA;;KAEV,GAAA,GAAM,KAAA;;;;;cAML,gBAAA,EAAgB,MAAA,CAAA,MAAA;;KAIjB,UAAA,GAAa,KAAA;;;;cAKZ,UAAA,EAAU,MAAA,CAAA,MAAA;;KAEX,IAAA,GAAO,KAAA;;;;;;;;;;;;;;AA3EnB;cA+Fa,UAAA,GAAc,IAAA;;;;AAzF3B;;;;;AAiBA;;;;;AAMA;;;;;cAiGa,iBAAA,GACZ,GAAA,UACA,gBAAA,YAA2B,WAAA,OACzB,IAAA,CAAK,IAAA,SAAa,MAAA,CAAE,WAAA;;;;;AA7FvB;;;;;AAIA;;;;;AAMA;cA+Ha,WAAA,GACZ,GAAA,UACA,gBAAA,YAA2B,WAAA;;;;AA7H5B;;;;;AAMA;;;;cAiLa,YAAA,GAAgB,IAAA,UAAc,OAAA,GAAU,MAAA;AA/KrD;;;;;AAMA;;;AANA,cAoMa,uBAAA,GACZ,KAAA,UACA,OAAA,GAAS,gBAAA,KACP,IAAA,CAAK,IAAA,SAAa,MAAA,CAAE,WAAA;;AA7LvB;;;;;AAKA;;;;;AAEA;;;;;cAqPa,iBAAA,GAAqB,KAAA,UAAe,SAAA,WAAiB,SAAA;;;;;AAlMlE;;;;;;;;;;;;cAuPa,mBAAA,MACZ,UAAA,UACA,MAAA,EAAQ,UAAA,CAAW,CAAA,MACjB,MAAA,CAAO,MAAA,CAAO,CAAA;;;;;AA3MjB;;;;;;;;;AA4DA;;;;;;;cAyLa,YAAA,GAAgB,UAAA;;AApK7B;;;;;;;;;;;cAqMa,SAAA,GAAa,IAAA;;;;;;AAnI1B;;;cAyKa,eAAA,GACZ,IAAA,UACA,OAAA,GAAS,mBAAA,KACP,IAAA,CAAK,IAAA,SAAa,MAAA,CAAE,WAAA;;;;;;AAvHvB;;;;;;;;;;;;;cAwLa,SAAA,GACZ,IAAA,UACA,OAAA,GAAS,mBAAA;EACR,cAAA,GAAiB,KAAA;IAAQ,OAAA,EAAS,MAAA;IAAQ,WAAA;EAAA;AAAA;AA9I5C;;;;;AAiCA;;;;;AAsCA;;;;;;AAvEA,cAiMa,aAAA,GACZ,GAAA,WACA,aAAA,aAUA,MAAA;;;;;;;;;;cA+BY,YAAA,GAAgB,KAAA,aAAgB,KAAA,IAAS,KAAA;AAjGtD;;;;;;;;AAAA,cA6Ga,YAAA,GAAgB,KAAA,aAAgB,KAAA,IAAS,WAAA;;;;;;;;;cAYzC,UAAA,GAAc,GAAA,aAAc,GAAA,IAAO,GAAA;AAnEhD;;;;;;;;AAAA,cA+Ea,UAAA,GAAc,GAAA,aAAc,GAAA,IAAO,OAAA"}