@resq-systems/security 1.0.0

package/lib/sanitize.mjs

@@ -0,0 +1,529 @@
+import { Exit, Option, Schema } from "effect";
+import DOMPurify from "dompurify";
+//#region src/sanitize.ts
+/**
+* Schema for URL protocol validation
+* @compliance NIST 800-53 SI-10 (Information Input Validation)
+*/
+const UrlProtocolSchema = Schema.Literals([
+	"http:",
+	"https:",
+	"mailto:",
+	"tel:",
+	"ftp:"
+]);
+/**
+* Schema for PII redaction options
+* @compliance NIST 800-53 AU-3 (Content of Audit Records)
+*/
+const PIIRedactionOptionsSchema = Schema.Struct({
+	redactEmails: Schema.optional(Schema.Boolean),
+	redactPhones: Schema.optional(Schema.Boolean),
+	redactSSN: Schema.optional(Schema.Boolean),
+	redactCreditCards: Schema.optional(Schema.Boolean),
+	redactIPs: Schema.optional(Schema.Boolean),
+	redactDates: Schema.optional(Schema.Boolean)
+});
+/**
+* Schema for user input validation options
+* @compliance NIST 800-53 SI-10 (Information Input Validation)
+*/
+const UserInputOptionsSchema = Schema.Struct({
+	maxLength: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
+	allowHtml: Schema.optional(Schema.Boolean),
+	allowNewlines: Schema.optional(Schema.Boolean),
+	trimWhitespace: Schema.optional(Schema.Boolean)
+});
+/**
+* Schema for safe URL - validates URL format and protocol
+* @compliance NIST 800-53 SI-10 (Information Input Validation)
+*/
+const SafeUrlSchema = Schema.String.check(Schema.makeFilter((url) => {
+	if (!url || url.trim() === "") return false;
+	if (url.startsWith("/") && !url.startsWith("//")) return true;
+	try {
+		const parsed = new URL(url);
+		return [
+			"http:",
+			"https:",
+			"mailto:"
+		].includes(parsed.protocol);
+	} catch {
+		return /^[a-zA-Z0-9/_.-]+$/.test(url);
+	}
+}, { message: "Invalid or unsafe URL" }));
+/**
+* Schema for sanitized HTML-safe string (validates as string; escaping done at runtime)
+* @compliance NIST 800-53 SI-10 (Information Input Validation)
+*/
+const SanitizedStringSchema = Schema.String;
+/**
+* Schema for email address validation
+* @compliance NIST 800-53 SI-10 (Information Input Validation)
+*/
+const EmailSchema = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/));
+/**
+* Schema for phone number validation (US format)
+* @compliance NIST 800-53 SI-10 (Information Input Validation)
+*/
+const PhoneNumberSchema = Schema.String.check(Schema.isPattern(/^(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}$/));
+/**
+* Schema for SSN validation (US format)
+* @compliance NIST 800-53 SI-10 (Information Input Validation)
+*/
+const SSNSchema = Schema.String.check(Schema.isPattern(/^\d{3}[-\s]?\d{2}[-\s]?\d{4}$/));
+/**
+* Schema for credit card number validation
+* @compliance NIST 800-53 SI-10 (Information Input Validation)
+*/
+const CreditCardSchema = Schema.String.check(Schema.isPattern(/^(?:\d{4}[-\s]?){3}\d{4}$|^\d{15,16}$/));
+/**
+* Schema for IPv4 address validation
+*/
+const IPv4Schema = Schema.String.check(Schema.isPattern(/^(?:\d{1,3}\.){3}\d{1,3}$/));
+/**
+* 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;"
+* ```
+*/
+const escapeHtml = (text) => {
+	if (!text || typeof text !== "string") return "";
+	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&#039;");
+};
+/**
+* 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(...)
+* ```
+*/
+const sanitizeUrlEffect = (url, allowedProtocols = [
+	"http:",
+	"https:",
+	"mailto:"
+]) => {
+	const CustomSafeUrlSchema = Schema.String.check(Schema.makeFilter((u) => {
+		if (!u || u.trim() === "") return false;
+		const trimmed = u.trim();
+		if (trimmed.startsWith("/") && !trimmed.startsWith("//")) return true;
+		try {
+			const parsed = new URL(trimmed);
+			if (!allowedProtocols.includes(parsed.protocol)) return false;
+			if (parsed.hostname.includes("javascript:") || parsed.hostname.includes("data:")) return false;
+			return true;
+		} catch {
+			return /^[a-zA-Z0-9/_.-]+$/.test(trimmed) && !trimmed.includes("javascript:") && !trimmed.includes("data:");
+		}
+	}, { message: "Invalid or unsafe URL" }));
+	return Schema.decodeUnknownExit(CustomSafeUrlSchema)(url);
+};
+/**
+* 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)'); // ''
+* ```
+*/
+const sanitizeUrl = (url, allowedProtocols = [
+	"http:",
+	"https:",
+	"mailto:"
+]) => {
+	const result = sanitizeUrlEffect(url, allowedProtocols);
+	return Exit.isSuccess(result) ? result.value : "";
+};
+let purifyInstance;
+const getPurify = () => {
+	if (purifyInstance !== void 0) return purifyInstance;
+	if (typeof window !== "undefined") purifyInstance = DOMPurify;
+	else try {
+		const nodeModule = globalThis.process?.getBuiltinModule?.("module");
+		if (!nodeModule) {
+			purifyInstance = null;
+			return purifyInstance;
+		}
+		const { JSDOM } = nodeModule.createRequire(import.meta.url)("jsdom");
+		purifyInstance = DOMPurify(new JSDOM("").window);
+	} catch {
+		purifyInstance = null;
+	}
+	return purifyInstance;
+};
+/**
+* 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.
+*/
+const sanitizeHtml = (html, options) => {
+	if (!html || typeof html !== "string") return "";
+	const purify = getPurify();
+	if (purify) return purify.sanitize(html, options);
+	return escapeHtml(html);
+};
+/**
+* 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)
+*/
+const validateUserInputEffect = (input, options = {}) => {
+	const { maxLength = 500, allowHtml = false, allowNewlines = false, trimWhitespace = true } = options;
+	const parsed = Schema.decodeUnknownExit(Schema.String)(input);
+	if (Exit.isFailure(parsed)) return parsed;
+	let result = parsed.value;
+	if (trimWhitespace) result = result.trim();
+	if (!allowHtml) {
+		let prev;
+		do {
+			prev = result;
+			result = result.replaceAll(/<[^>]*>/g, "");
+		} while (result !== prev);
+	} else result = sanitizeHtml(result);
+	if (!allowNewlines) result = result.replaceAll(/[\r\n]+/g, " ");
+	result = result.replaceAll(/\s+/g, " ");
+	let prevScheme;
+	do {
+		prevScheme = result;
+		result = result.replaceAll(/javascript:/gi, "").replaceAll(/data:/gi, "").replaceAll(/vbscript:/gi, "").replaceAll(/on\w+=/gi, "");
+	} while (result !== prevScheme);
+	return Exit.succeed(result.slice(0, maxLength));
+};
+/**
+* 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"
+* ```
+*/
+const validateUserInput = (input, maxLength = 500, allowHtml = false) => {
+	if (!input || typeof input !== "string") return "";
+	const result = validateUserInputEffect(input, {
+		maxLength,
+		allowHtml
+	});
+	return Exit.isSuccess(result) ? result.value : "";
+};
+/**
+* Recursively removes dangerous prototype pollution keys from an object.
+*/
+const sanitizeObject = (val, depth = 0) => {
+	if (depth > 50) return;
+	if (typeof val !== "object" || val === null) return;
+	if (Array.isArray(val)) {
+		for (const item of val) sanitizeObject(item, depth + 1);
+		return;
+	}
+	const dangerous = [
+		"__proto__",
+		"constructor",
+		"prototype"
+	];
+	const obj = val;
+	for (const key of dangerous) if (key in obj) delete obj[key];
+	for (const key of Object.keys(obj)) sanitizeObject(obj[key], depth + 1);
+};
+/**
+* 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 })
+* ```
+*/
+const parseJsonWithSchema = (jsonString, schema) => {
+	if (!jsonString || typeof jsonString !== "string") return Option.none();
+	try {
+		const sanitized = jsonString.replaceAll(/\)\s*\{/g, ") {}").replaceAll(/\]\s*\{/g, "] {}").replaceAll(/\}\s*\{/g, "} {}");
+		const parsed = JSON.parse(sanitized);
+		sanitizeObject(parsed);
+		const result = Schema.decodeUnknownExit(schema)(parsed);
+		return Exit.isSuccess(result) ? Option.some(result.value) : Option.none();
+	} catch {
+		return Option.none();
+	}
+};
+/**
+* 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
+* ```
+*/
+const sanitizeJson = (jsonString) => {
+	if (!jsonString || typeof jsonString !== "string") return null;
+	try {
+		const sanitized = jsonString.replaceAll(/\)\s*\{/g, ") {}").replaceAll(/\]\s*\{/g, "] {}").replaceAll(/\}\s*\{/g, "} {}");
+		const parsed = JSON.parse(sanitized);
+		sanitizeObject(parsed);
+		return parsed;
+	} catch {
+		return null;
+	}
+};
+/**
+* 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'
+* ```
+*/
+const stripAnsi = (text) => {
+	if (!text || typeof text !== "string") return "";
+	return text.replaceAll(/\x1b\[[0-9;]*m/g, "");
+};
+/**
+* PII pattern definitions with Effect Schema validation
+* @compliance NIST 800-53 AU-3 (Content of Audit Records)
+*/
+const PII_PATTERNS = {
+	ssn: {
+		pattern: /\b\d{3}[-\s]?\d{2}[-\s]?\d{4}\b/g,
+		marker: "[SSN]"
+	},
+	creditCard: {
+		pattern: /\b(?:\d{4}[-\s]?){3}\d{4}\b/g,
+		marker: "[CREDIT_CARD]"
+	},
+	creditCardAlt: {
+		pattern: /\b\d{15,16}\b/g,
+		marker: "[CREDIT_CARD]"
+	},
+	email: {
+		pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+		marker: "[EMAIL]"
+	},
+	phone: {
+		pattern: /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+		marker: "[PHONE]"
+	},
+	ipv4: {
+		pattern: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+		marker: "[IP_ADDRESS]"
+	},
+	ipv6: {
+		pattern: /\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\b/g,
+		marker: "[IP_ADDRESS]"
+	},
+	date: {
+		pattern: /\b(?:\d{1,2}[/-]\d{1,2}[/-]\d{2,4}|\d{4}[/-]\d{1,2}[/-]\d{1,2})\b/g,
+		marker: "[DATE]"
+	}
+};
+/**
+* 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)
+*/
+const redactPIIEffect = (text, options = {}) => {
+	const parsed = Schema.decodeUnknownExit(PIIRedactionOptionsSchema)(options);
+	if (Exit.isFailure(parsed)) return Exit.failCause(parsed.cause);
+	const { redactEmails = true, redactPhones = true, redactSSN = true, redactCreditCards = true, redactIPs = true, redactDates = false } = parsed.value;
+	let result = text;
+	if (redactSSN) result = result.replaceAll(PII_PATTERNS.ssn.pattern, PII_PATTERNS.ssn.marker);
+	if (redactCreditCards) {
+		result = result.replaceAll(PII_PATTERNS.creditCard.pattern, PII_PATTERNS.creditCard.marker);
+		result = result.replaceAll(PII_PATTERNS.creditCardAlt.pattern, PII_PATTERNS.creditCardAlt.marker);
+	}
+	if (redactEmails) result = result.replaceAll(PII_PATTERNS.email.pattern, PII_PATTERNS.email.marker);
+	if (redactPhones) result = result.replaceAll(PII_PATTERNS.phone.pattern, PII_PATTERNS.phone.marker);
+	if (redactIPs) {
+		result = result.replaceAll(PII_PATTERNS.ipv4.pattern, PII_PATTERNS.ipv4.marker);
+		result = result.replaceAll(PII_PATTERNS.ipv6.pattern, PII_PATTERNS.ipv6.marker);
+	}
+	if (redactDates) result = result.replaceAll(PII_PATTERNS.date.pattern, PII_PATTERNS.date.marker);
+	return Exit.succeed(result);
+};
+/**
+* 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]'
+* ```
+*/
+const redactPII = (text, options = {}) => {
+	if (!text || typeof text !== "string") return "";
+	const { redactEmails = true, redactPhones = true, redactSSN = true, redactCreditCards = true, redactIPs = true, redactDates = false, customPatterns = [] } = options;
+	const result = redactPIIEffect(text, {
+		redactEmails,
+		redactPhones,
+		redactSSN,
+		redactCreditCards,
+		redactIPs,
+		redactDates
+	});
+	let output = Exit.isSuccess(result) ? result.value : text;
+	for (const { pattern, replacement } of customPatterns) output = output.replaceAll(pattern, replacement);
+	return output;
+};
+/**
+* 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}'
+* ```
+*/
+const safeStringify = (obj, sensitiveKeys = [
+	"password",
+	"token",
+	"apiKey",
+	"secret",
+	"authorization",
+	"cookie",
+	"ssn",
+	"creditCard"
+], indent = 2) => {
+	const sensitiveKeysLower = new Set(sensitiveKeys.map((k) => k.toLowerCase()));
+	const replacer = (_key, value) => {
+		if (_key && sensitiveKeysLower.has(_key.toLowerCase())) return "[REDACTED]";
+		return value;
+	};
+	try {
+		return JSON.stringify(obj, replacer, indent);
+	} catch {
+		return "[Unable to stringify object]";
+	}
+};
+/**
+* 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.
+*/
+const isValidEmail = (email) => {
+	return Exit.isSuccess(Schema.decodeUnknownExit(EmailSchema)(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.
+*/
+const isValidPhone = (phone) => {
+	return Exit.isSuccess(Schema.decodeUnknownExit(PhoneNumberSchema)(phone));
+};
+/**
+* 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.
+*/
+const isValidSSN = (ssn) => {
+	return Exit.isSuccess(Schema.decodeUnknownExit(SSNSchema)(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.
+*/
+const isValidUrl = (url) => {
+	return Exit.isSuccess(Schema.decodeUnknownExit(SafeUrlSchema)(url));
+};
+//#endregion
+export { 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 };
+
+//# sourceMappingURL=sanitize.mjs.map

package/lib/sanitize.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.mjs","names":["S"],"sources":["../src/sanitize.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 Input sanitization utilities for XSS prevention and data validation\n * @module utils/sanitize\n * @author ResQ\n * @description Provides type-safe input sanitization using Effect Schema for validation.\n *              Includes utilities for HTML escaping, URL validation, PII redaction, and more.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\n\nimport type { Brand } from \"@resq-systems/types\";\nimport { Exit, Option, Schema as S } from \"effect\";\nimport DOMPurify from \"dompurify\";\nimport type { Config, WindowLike } from \"dompurify\";\n\n/**\n * A Schema with DecodingServices constrained to `never`, allowing synchronous decoding.\n */\ntype SyncSchema<T> = S.Codec<T, unknown, never>;\n\n// ============================================\n// Effect Schema Definitions\n// ============================================\n\n/**\n * Schema for URL protocol validation\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const UrlProtocolSchema = S.Literals([\"http:\", \"https:\", \"mailto:\", \"tel:\", \"ftp:\"]);\nexport type UrlProtocol = typeof UrlProtocolSchema.Type;\n\n/**\n * Schema for PII redaction options\n * @compliance NIST 800-53 AU-3 (Content of Audit Records)\n */\nexport const PIIRedactionOptionsSchema = S.Struct({\n\tredactEmails: S.optional(S.Boolean),\n\tredactPhones: S.optional(S.Boolean),\n\tredactSSN: S.optional(S.Boolean),\n\tredactCreditCards: S.optional(S.Boolean),\n\tredactIPs: S.optional(S.Boolean),\n\tredactDates: S.optional(S.Boolean),\n});\nexport type PIIRedactionOptions = typeof PIIRedactionOptionsSchema.Type;\n\n/**\n * Schema for user input validation options\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const UserInputOptionsSchema = S.Struct({\n\tmaxLength: S.optional(S.Int.check(S.isGreaterThan(0))),\n\tallowHtml: S.optional(S.Boolean),\n\tallowNewlines: S.optional(S.Boolean),\n\ttrimWhitespace: S.optional(S.Boolean),\n});\nexport type UserInputOptions = typeof UserInputOptionsSchema.Type;\n\n/**\n * Schema for safe URL - validates URL format and protocol\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const SafeUrlSchema = S.String.check(\n\tS.makeFilter(\n\t\t(url: string) => {\n\t\t\tif (!url || url.trim() === \"\") return false;\n\t\t\tif (url.startsWith(\"/\") && !url.startsWith(\"//\")) return true;\n\t\t\ttry {\n\t\t\t\tconst parsed = new URL(url);\n\t\t\t\tconst safeProtocols = [\"http:\", \"https:\", \"mailto:\"];\n\t\t\t\treturn safeProtocols.includes(parsed.protocol);\n\t\t\t} catch {\n\t\t\t\treturn /^[a-zA-Z0-9/_.-]+$/.test(url);\n\t\t\t}\n\t\t},\n\t\t{ message: \"Invalid or unsafe URL\" },\n\t),\n);\n/** A string that has passed {@link isValidUrl} — a validated, injection-safe URL. */\nexport type SafeUrl = Brand<string, \"SafeUrl\">;\n\n/**\n * Schema for sanitized HTML-safe string (validates as string; escaping done at runtime)\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const SanitizedStringSchema = S.String;\nexport type SanitizedString = typeof SanitizedStringSchema.Type;\n\n/**\n * Schema for email address validation\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const EmailSchema = S.String.check(\n\tS.isPattern(/^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$/),\n);\n/** A string that has passed {@link isValidEmail}. */\nexport type Email = Brand<string, \"Email\">;\n\n/**\n * Schema for phone number validation (US format)\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const PhoneNumberSchema = S.String.check(\n\tS.isPattern(/^(?:\\+?1[-.\\s]?)?\\(?\\d{3}\\)?[-.\\s]?\\d{3}[-.\\s]?\\d{4}$/),\n);\n/** A string that has passed {@link isValidPhone} (US format). */\nexport type PhoneNumber = Brand<string, \"PhoneNumber\">;\n\n/**\n * Schema for SSN validation (US format)\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const SSNSchema = S.String.check(S.isPattern(/^\\d{3}[-\\s]?\\d{2}[-\\s]?\\d{4}$/));\n/** A string that has passed {@link isValidSSN} (US format). */\nexport type SSN = Brand<string, \"SSN\">;\n\n/**\n * Schema for credit card number validation\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const CreditCardSchema = S.String.check(\n\tS.isPattern(/^(?:\\d{4}[-\\s]?){3}\\d{4}$|^\\d{15,16}$/),\n);\n/** A string matching the {@link CreditCardSchema} pattern. */\nexport type CreditCard = Brand<string, \"CreditCard\">;\n\n/**\n * Schema for IPv4 address validation\n */\nexport const IPv4Schema = S.String.check(S.isPattern(/^(?:\\d{1,3}\\.){3}\\d{1,3}$/));\n/** A string matching the {@link IPv4Schema} dotted-quad pattern. */\nexport type IPv4 = Brand<string, \"IPv4\">;\n\n// ============================================\n// Sanitization Functions\n// ============================================\n\n/**\n * Escapes special HTML characters in a string to their corresponding HTML entities,\n * preventing direct injection of HTML and JavaScript when rendering untrusted content.\n *\n * @param text - The plain text to escape.\n * @returns The escaped string safe for HTML rendering.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n *\n * @example\n * ```typescript\n * escapeHtml('<script>alert(\"xss\")</script>');\n * // \"&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;\"\n * ```\n */\nexport const escapeHtml = (text: string): string => {\n\tif (!text || typeof text !== \"string\") {\n\t\treturn \"\";\n\t}\n\n\treturn text\n\t\t.replaceAll(\"&\", \"&amp;\")\n\t\t.replaceAll(\"<\", \"&lt;\")\n\t\t.replaceAll(\">\", \"&gt;\")\n\t\t.replaceAll('\"', \"&quot;\")\n\t\t.replaceAll(\"'\", \"&#039;\");\n};\n\n/**\n * Validates and sanitizes a user-supplied URL using Effect Schema.\n * Returns an Exit with the sanitized URL or an error.\n *\n * @param url - The URL to be validated and sanitized.\n * @param allowedProtocols - Array of allowed URL protocols.\n * @returns Exit containing the sanitized URL or an error.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n *\n * @example\n * ```typescript\n * const result = sanitizeUrlEffect('https://example.com');\n * // Exit.succeed('https://example.com')\n *\n * const invalid = sanitizeUrlEffect('javascript:alert(1)');\n * // Exit.fail(...)\n * ```\n */\nexport const sanitizeUrlEffect = (\n\turl: string,\n\tallowedProtocols: readonly UrlProtocol[] = [\"http:\", \"https:\", \"mailto:\"],\n): Exit.Exit<string, S.SchemaError> => {\n\tconst CustomSafeUrlSchema = S.String.check(\n\t\tS.makeFilter(\n\t\t\t(u: string) => {\n\t\t\t\tif (!u || u.trim() === \"\") return false;\n\t\t\t\tconst trimmed = u.trim();\n\t\t\t\tif (trimmed.startsWith(\"/\") && !trimmed.startsWith(\"//\")) return true;\n\t\t\t\ttry {\n\t\t\t\t\tconst parsed = new URL(trimmed);\n\t\t\t\t\tif (!allowedProtocols.includes(parsed.protocol)) return false;\n\t\t\t\t\tif (parsed.hostname.includes(\"javascript:\") || parsed.hostname.includes(\"data:\")) {\n\t\t\t\t\t\treturn false;\n\t\t\t\t\t}\n\t\t\t\t\treturn true;\n\t\t\t\t} catch {\n\t\t\t\t\treturn (\n\t\t\t\t\t\t/^[a-zA-Z0-9/_.-]+$/.test(trimmed) &&\n\t\t\t\t\t\t!trimmed.includes(\"javascript:\") &&\n\t\t\t\t\t\t!trimmed.includes(\"data:\")\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t},\n\t\t\t{ message: \"Invalid or unsafe URL\" },\n\t\t),\n\t);\n\n\treturn S.decodeUnknownExit(CustomSafeUrlSchema)(url);\n};\n\n/**\n * Validates and sanitizes a user-supplied URL, ensuring it conforms to allowed protocols\n * and is not a vector for injection attacks like `javascript:` or `data:`.\n *\n * @param url - The URL to be validated and sanitized.\n * @param allowedProtocols - Array of allowed URL protocols.\n * @returns The sanitized URL if valid, or an empty string if unsafe.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n *\n * @example\n * ```typescript\n * sanitizeUrl('https://example.com'); // 'https://example.com'\n * sanitizeUrl('javascript:alert(1)'); // ''\n * ```\n */\nexport const sanitizeUrl = (\n\turl: string,\n\tallowedProtocols: readonly UrlProtocol[] = [\"http:\", \"https:\", \"mailto:\"],\n): string => {\n\tconst result = sanitizeUrlEffect(url, allowedProtocols);\n\treturn Exit.isSuccess(result) ? result.value : \"\";\n};\n\nlet purifyInstance: typeof DOMPurify | null | undefined;\n\nconst getPurify = (): typeof DOMPurify | null => {\n\tif (purifyInstance !== undefined) return purifyInstance;\n\n\tif (typeof window !== \"undefined\") {\n\t\tpurifyInstance = DOMPurify;\n\t} else {\n\t\ttry {\n\t\t\t// Resolve `node:module` at runtime (server-side only) via\n\t\t\t// process.getBuiltinModule so browser bundlers never see a static\n\t\t\t// `node:module` import. Available on Node >=20.16 and Bun; absent in\n\t\t\t// browsers, where the `window` branch above is taken instead. jsdom is an\n\t\t\t// optional peer dependency — install it for server-side HTML sanitization.\n\t\t\tconst proc = (globalThis as { process?: { getBuiltinModule?: (m: string) => unknown } })\n\t\t\t\t.process;\n\t\t\tconst nodeModule = proc?.getBuiltinModule?.(\"module\") as\n\t\t\t\t| { createRequire(path: string | URL): (id: string) => unknown }\n\t\t\t\t| undefined;\n\t\t\tif (!nodeModule) {\n\t\t\t\tpurifyInstance = null;\n\t\t\t\treturn purifyInstance;\n\t\t\t}\n\t\t\tconst req = nodeModule.createRequire(import.meta.url);\n\t\t\tconst { JSDOM } = req(\"jsdom\") as {\n\t\t\t\tJSDOM: new (\n\t\t\t\t\thtml?: string,\n\t\t\t\t) => {\n\t\t\t\t\twindow: WindowLike;\n\t\t\t\t};\n\t\t\t};\n\t\t\tconst dom = new JSDOM(\"\");\n\t\t\tpurifyInstance = DOMPurify(dom.window);\n\t\t} catch {\n\t\t\tpurifyInstance = null;\n\t\t}\n\t}\n\treturn purifyInstance;\n};\n\n/**\n * Sanitizes HTML to prevent XSS attacks.\n * Uses DOMPurify under the hood. If DOM is not available (e.g. server-side without JSDOM),\n * it falls back to escaping all HTML characters for safety.\n *\n * NOTE: Server-side HTML sanitization requires `jsdom` to be installed in the consuming application\n * environment; otherwise, it will fall back to escaping HTML characters.\n *\n * @param html - The HTML string to sanitize.\n * @param options - Optional DOMPurify configuration.\n * @returns The sanitized HTML string.\n */\nexport const sanitizeHtml = (html: string, options?: Config): string => {\n\tif (!html || typeof html !== \"string\") {\n\t\treturn \"\";\n\t}\n\n\tconst purify = getPurify();\n\tif (purify) {\n\t\treturn purify.sanitize(html, options) as string;\n\t}\n\n\treturn escapeHtml(html);\n};\n\n/**\n * Validates user input using Effect Schema and returns an Exit.\n *\n * @param input - User input to validate and sanitize.\n * @param options - Validation options.\n * @returns Exit containing sanitized input or error.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const validateUserInputEffect = (\n\tinput: string,\n\toptions: UserInputOptions = {},\n): Exit.Exit<string, S.SchemaError> => {\n\tconst {\n\t\tmaxLength = 500,\n\t\tallowHtml = false,\n\t\tallowNewlines = false,\n\t\ttrimWhitespace = true,\n\t} = options;\n\n\tconst parsed = S.decodeUnknownExit(S.String)(input);\n\tif (Exit.isFailure(parsed)) return parsed;\n\n\tlet result = parsed.value;\n\n\tif (trimWhitespace) {\n\t\tresult = result.trim();\n\t}\n\n\tif (!allowHtml) {\n\t\tlet prev: string;\n\t\tdo {\n\t\t\tprev = result;\n\t\t\tresult = result.replaceAll(/<[^>]*>/g, \"\");\n\t\t} while (result !== prev);\n\t} else {\n\t\tresult = sanitizeHtml(result);\n\t}\n\n\tif (!allowNewlines) {\n\t\tresult = result.replaceAll(/[\\r\\n]+/g, \" \");\n\t}\n\n\tresult = result.replaceAll(/\\s+/g, \" \");\n\n\t// Loop until stable to prevent bypass via nested patterns (e.g. \"javascrjavascript:ipt:\")\n\tlet prevScheme: string;\n\tdo {\n\t\tprevScheme = result;\n\t\tresult = result\n\t\t\t.replaceAll(/javascript:/gi, \"\")\n\t\t\t.replaceAll(/data:/gi, \"\")\n\t\t\t.replaceAll(/vbscript:/gi, \"\")\n\t\t\t.replaceAll(/on\\w+=/gi, \"\");\n\t} while (result !== prevScheme);\n\n\treturn Exit.succeed(result.slice(0, maxLength));\n};\n\n/**\n * Validates and sanitizes generic user input by trimming, removing HTML tags (unless allowed),\n * normalizing whitespace, and removing dangerous patterns to prevent XSS and basic injection flaws.\n *\n * @param input - User input to validate and sanitize.\n * @param maxLength - Maximum allowed input length. Excess will be truncated.\n * @param allowHtml - If true, HTML tags are preserved; otherwise, all tags are stripped.\n * @returns Sanitized input string with length at most `maxLength`.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n *\n * @example\n * ```typescript\n * validateUserInput('<p>Hello!</p>', 50); // \"Hello!\"\n * validateUserInput('<script>alert(1)</script>test', 100); // \"test\"\n * ```\n */\nexport const validateUserInput = (input: string, maxLength = 500, allowHtml = false): string => {\n\tif (!input || typeof input !== \"string\") {\n\t\treturn \"\";\n\t}\n\n\tconst result = validateUserInputEffect(input, { maxLength, allowHtml });\n\treturn Exit.isSuccess(result) ? result.value : \"\";\n};\n\n/**\n * Recursively removes dangerous prototype pollution keys from an object.\n */\nconst sanitizeObject = (val: unknown, depth = 0): void => {\n\tif (depth > 50) {\n\t\treturn;\n\t}\n\tif (typeof val !== \"object\" || val === null) {\n\t\treturn;\n\t}\n\tif (Array.isArray(val)) {\n\t\tfor (const item of val) {\n\t\t\tsanitizeObject(item, depth + 1);\n\t\t}\n\t\treturn;\n\t}\n\tconst dangerous = [\"__proto__\", \"constructor\", \"prototype\"];\n\tconst obj = val as Record<string, unknown>;\n\tfor (const key of dangerous) {\n\t\tif (key in obj) {\n\t\t\tdelete obj[key];\n\t\t}\n\t}\n\tfor (const key of Object.keys(obj)) {\n\t\tsanitizeObject(obj[key], depth + 1);\n\t}\n};\n\n/**\n * Safely parses JSON with Effect Schema validation and prototype pollution protection.\n *\n * @template A - The expected schema type\n * @param jsonString - The JSON string to parse.\n * @param schema - Effect Schema to validate against.\n * @returns Option containing the parsed and validated object.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n *\n * @example\n * ```typescript\n * const UserSchema = S.Struct({ name: S.String, age: S.Number });\n * const result = parseJsonWithSchema('{\"name\":\"John\",\"age\":30}', UserSchema);\n * // Option.some({ name: 'John', age: 30 })\n * ```\n */\nexport const parseJsonWithSchema = <A>(\n\tjsonString: string,\n\tschema: SyncSchema<A>,\n): Option.Option<A> => {\n\tif (!jsonString || typeof jsonString !== \"string\") {\n\t\treturn Option.none();\n\t}\n\n\ttry {\n\t\tconst sanitized = jsonString\n\t\t\t.replaceAll(/\\)\\s*\\{/g, \") {}\")\n\t\t\t.replaceAll(/\\]\\s*\\{/g, \"] {}\")\n\t\t\t.replaceAll(/\\}\\s*\\{/g, \"} {}\");\n\n\t\tconst parsed = JSON.parse(sanitized);\n\n\t\tsanitizeObject(parsed);\n\n\t\tconst result = S.decodeUnknownExit(schema)(parsed);\n\t\treturn Exit.isSuccess(result) ? Option.some(result.value as A) : Option.none();\n\t} catch {\n\t\treturn Option.none();\n\t}\n};\n\n/**\n * Sanitizes and safely parses a JSON string, removing suspicious syntax elements that could\n * potentially result in JSON polyglot exploits or prototype pollution.\n *\n * The result is returned as `unknown` — this function performs **no** schema\n * validation, so it cannot honestly promise any concrete shape for\n * attacker-controlled input. Narrow the result yourself, or prefer\n * {@link parseJsonWithSchema}, which validates against an Effect Schema and\n * returns a typed `Option`.\n *\n * @param jsonString - The JSON string to sanitize and parse.\n * @returns The parsed value (as `unknown`) if valid, or `null` if invalid.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n *\n * @example\n * ```typescript\n * const obj = sanitizeJson('{\"foo\":\"bar\"}');\n * // obj: unknown — narrow before use, or use parseJsonWithSchema\n * ```\n */\nexport const sanitizeJson = (jsonString: string): unknown => {\n\tif (!jsonString || typeof jsonString !== \"string\") {\n\t\treturn null;\n\t}\n\n\ttry {\n\t\tconst sanitized = jsonString\n\t\t\t.replaceAll(/\\)\\s*\\{/g, \") {}\")\n\t\t\t.replaceAll(/\\]\\s*\\{/g, \"] {}\")\n\t\t\t.replaceAll(/\\}\\s*\\{/g, \"} {}\");\n\n\t\tconst parsed: unknown = JSON.parse(sanitized);\n\n\t\tsanitizeObject(parsed);\n\n\t\treturn parsed;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\n/**\n * Strips ANSI escape codes from a string.\n * Useful for cleaning terminal output before logging to files.\n *\n * @param text - The text potentially containing ANSI codes.\n * @returns The text with ANSI codes removed.\n *\n * @example\n * ```typescript\n * stripAnsi('\\x1b[31mRed text\\x1b[0m'); // 'Red text'\n * ```\n */\nexport const stripAnsi = (text: string): string => {\n\tif (!text || typeof text !== \"string\") {\n\t\treturn \"\";\n\t}\n\t// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI codes require control characters\n\treturn text.replaceAll(/\\x1b\\[[0-9;]*m/g, \"\");\n};\n\n// ============================================\n// PII Redaction Functions\n// ============================================\n\n/**\n * PII pattern definitions with Effect Schema validation\n * @compliance NIST 800-53 AU-3 (Content of Audit Records)\n */\nconst PII_PATTERNS = {\n\tssn: { pattern: /\\b\\d{3}[-\\s]?\\d{2}[-\\s]?\\d{4}\\b/g, marker: \"[SSN]\" },\n\tcreditCard: { pattern: /\\b(?:\\d{4}[-\\s]?){3}\\d{4}\\b/g, marker: \"[CREDIT_CARD]\" },\n\tcreditCardAlt: { pattern: /\\b\\d{15,16}\\b/g, marker: \"[CREDIT_CARD]\" },\n\temail: { pattern: /\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b/g, marker: \"[EMAIL]\" },\n\tphone: { pattern: /\\b(?:\\+?1[-.\\s]?)?\\(?\\d{3}\\)?[-.\\s]?\\d{3}[-.\\s]?\\d{4}\\b/g, marker: \"[PHONE]\" },\n\tipv4: { pattern: /\\b(?:\\d{1,3}\\.){3}\\d{1,3}\\b/g, marker: \"[IP_ADDRESS]\" },\n\tipv6: { pattern: /\\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\\b/g, marker: \"[IP_ADDRESS]\" },\n\tdate: {\n\t\tpattern: /\\b(?:\\d{1,2}[/-]\\d{1,2}[/-]\\d{2,4}|\\d{4}[/-]\\d{1,2}[/-]\\d{1,2})\\b/g,\n\t\tmarker: \"[DATE]\",\n\t},\n} as const;\n\n/**\n * Redacts PII from text using Effect Schema validated options.\n *\n * @param text - The text to redact PII from.\n * @param options - Configuration options for redaction.\n * @returns Exit containing redacted text or error.\n * @compliance NIST 800-53 AU-3 (Content of Audit Records)\n */\nexport const redactPIIEffect = (\n\ttext: string,\n\toptions: PIIRedactionOptions = {},\n): Exit.Exit<string, S.SchemaError> => {\n\tconst parsed = S.decodeUnknownExit(PIIRedactionOptionsSchema)(options);\n\tif (Exit.isFailure(parsed)) return Exit.failCause(parsed.cause);\n\n\tconst {\n\t\tredactEmails = true,\n\t\tredactPhones = true,\n\t\tredactSSN = true,\n\t\tredactCreditCards = true,\n\t\tredactIPs = true,\n\t\tredactDates = false,\n\t} = parsed.value;\n\n\tlet result = text;\n\n\tif (redactSSN) {\n\t\tresult = result.replaceAll(PII_PATTERNS.ssn.pattern, PII_PATTERNS.ssn.marker);\n\t}\n\n\tif (redactCreditCards) {\n\t\tresult = result.replaceAll(PII_PATTERNS.creditCard.pattern, PII_PATTERNS.creditCard.marker);\n\t\tresult = result.replaceAll(\n\t\t\tPII_PATTERNS.creditCardAlt.pattern,\n\t\t\tPII_PATTERNS.creditCardAlt.marker,\n\t\t);\n\t}\n\n\tif (redactEmails) {\n\t\tresult = result.replaceAll(PII_PATTERNS.email.pattern, PII_PATTERNS.email.marker);\n\t}\n\n\tif (redactPhones) {\n\t\tresult = result.replaceAll(PII_PATTERNS.phone.pattern, PII_PATTERNS.phone.marker);\n\t}\n\n\tif (redactIPs) {\n\t\tresult = result.replaceAll(PII_PATTERNS.ipv4.pattern, PII_PATTERNS.ipv4.marker);\n\t\tresult = result.replaceAll(PII_PATTERNS.ipv6.pattern, PII_PATTERNS.ipv6.marker);\n\t}\n\n\tif (redactDates) {\n\t\tresult = result.replaceAll(PII_PATTERNS.date.pattern, PII_PATTERNS.date.marker);\n\t}\n\n\treturn Exit.succeed(result);\n};\n\n/**\n * Redacts common PII patterns in a string for safe logging.\n * Detects and masks SSNs, credit cards, emails, phone numbers, etc.\n *\n * @param text - The text to redact PII from.\n * @param options - Configuration options for redaction.\n * @returns The text with PII patterns replaced with redaction markers.\n * @compliance NIST 800-53 AU-3 (Content of Audit Records)\n *\n * @example\n * ```typescript\n * redactPII('Contact john@example.com or call 555-123-4567');\n * // 'Contact [EMAIL] or call [PHONE]'\n *\n * redactPII('SSN: 123-45-6789');\n * // 'SSN: [SSN]'\n * ```\n */\nexport const redactPII = (\n\ttext: string,\n\toptions: PIIRedactionOptions & {\n\t\tcustomPatterns?: Array<{ pattern: RegExp; replacement: string }>;\n\t} = {},\n): string => {\n\tif (!text || typeof text !== \"string\") {\n\t\treturn \"\";\n\t}\n\n\tconst {\n\t\tredactEmails = true,\n\t\tredactPhones = true,\n\t\tredactSSN = true,\n\t\tredactCreditCards = true,\n\t\tredactIPs = true,\n\t\tredactDates = false,\n\t\tcustomPatterns = [],\n\t} = options;\n\n\tconst result = redactPIIEffect(text, {\n\t\tredactEmails,\n\t\tredactPhones,\n\t\tredactSSN,\n\t\tredactCreditCards,\n\t\tredactIPs,\n\t\tredactDates,\n\t});\n\n\tlet output = Exit.isSuccess(result) ? result.value : text;\n\n\tfor (const { pattern, replacement } of customPatterns) {\n\t\toutput = output.replaceAll(pattern, replacement);\n\t}\n\n\treturn output;\n};\n\n/**\n * Creates a safe string representation of an object for logging,\n * automatically redacting sensitive fields.\n *\n * @param obj - The object to stringify.\n * @param sensitiveKeys - Array of key names to redact.\n * @param indent - JSON indentation (default: 2).\n * @returns A JSON string with sensitive values redacted.\n * @compliance NIST 800-53 AU-3 (Content of Audit Records)\n *\n * @example\n * ```typescript\n * safeStringify({ user: 'john', password: 'secret123' }, ['password']);\n * // '{\\n  \"user\": \"john\",\\n  \"password\": \"[REDACTED]\"\\n}'\n * ```\n */\nexport const safeStringify = (\n\tobj: unknown,\n\tsensitiveKeys: string[] = [\n\t\t\"password\",\n\t\t\"token\",\n\t\t\"apiKey\",\n\t\t\"secret\",\n\t\t\"authorization\",\n\t\t\"cookie\",\n\t\t\"ssn\",\n\t\t\"creditCard\",\n\t],\n\tindent = 2,\n): string => {\n\tconst sensitiveKeysLower = new Set(sensitiveKeys.map((k) => k.toLowerCase()));\n\n\tconst replacer = (_key: string, value: unknown): unknown => {\n\t\tif (_key && sensitiveKeysLower.has(_key.toLowerCase())) {\n\t\t\treturn \"[REDACTED]\";\n\t\t}\n\t\treturn value;\n\t};\n\n\ttry {\n\t\treturn JSON.stringify(obj, replacer, indent);\n\t} catch {\n\t\treturn \"[Unable to stringify object]\";\n\t}\n};\n\n// ============================================\n// Validation Helpers\n// ============================================\n\n/**\n * Validates if a string is a valid email address using Effect Schema.\n *\n * Narrows the input to {@link Email} on success, so validated call sites\n * carry the brand into downstream code.\n *\n * @param email - The string to validate.\n * @returns true if valid email, false otherwise.\n */\nexport const isValidEmail = (email: string): email is Email => {\n\treturn Exit.isSuccess(S.decodeUnknownExit(EmailSchema)(email));\n};\n\n/**\n * Validates if a string is a valid phone number using Effect Schema.\n *\n * Narrows the input to {@link PhoneNumber} on success.\n *\n * @param phone - The string to validate.\n * @returns true if valid phone number, false otherwise.\n */\nexport const isValidPhone = (phone: string): phone is PhoneNumber => {\n\treturn Exit.isSuccess(S.decodeUnknownExit(PhoneNumberSchema)(phone));\n};\n\n/**\n * Validates if a string is a valid SSN using Effect Schema.\n *\n * Narrows the input to {@link SSN} on success.\n *\n * @param ssn - The string to validate.\n * @returns true if valid SSN, false otherwise.\n */\nexport const isValidSSN = (ssn: string): ssn is SSN => {\n\treturn Exit.isSuccess(S.decodeUnknownExit(SSNSchema)(ssn));\n};\n\n/**\n * Validates if a string is a safe URL using Effect Schema.\n *\n * Narrows the input to {@link SafeUrl} on success.\n *\n * @param url - The string to validate.\n * @returns true if valid and safe URL, false otherwise.\n */\nexport const isValidUrl = (url: string): url is SafeUrl => {\n\treturn Exit.isSuccess(S.decodeUnknownExit(SafeUrlSchema)(url));\n};\n"],"mappings":";;;;;;;AA2CA,MAAa,oBAAoBA,OAAE,SAAS;CAAC;CAAS;CAAU;CAAW;CAAQ;CAAO,CAAC;;;;;AAO3F,MAAa,4BAA4BA,OAAE,OAAO;CACjD,cAAcA,OAAE,SAASA,OAAE,QAAQ;CACnC,cAAcA,OAAE,SAASA,OAAE,QAAQ;CACnC,WAAWA,OAAE,SAASA,OAAE,QAAQ;CAChC,mBAAmBA,OAAE,SAASA,OAAE,QAAQ;CACxC,WAAWA,OAAE,SAASA,OAAE,QAAQ;CAChC,aAAaA,OAAE,SAASA,OAAE,QAAQ;CAClC,CAAC;;;;;AAOF,MAAa,yBAAyBA,OAAE,OAAO;CAC9C,WAAWA,OAAE,SAASA,OAAE,IAAI,MAAMA,OAAE,cAAc,EAAE,CAAC,CAAC;CACtD,WAAWA,OAAE,SAASA,OAAE,QAAQ;CAChC,eAAeA,OAAE,SAASA,OAAE,QAAQ;CACpC,gBAAgBA,OAAE,SAASA,OAAE,QAAQ;CACrC,CAAC;;;;;AAOF,MAAa,gBAAgBA,OAAE,OAAO,MACrCA,OAAE,YACA,QAAgB;AAChB,KAAI,CAAC,OAAO,IAAI,MAAM,KAAK,GAAI,QAAO;AACtC,KAAI,IAAI,WAAW,IAAI,IAAI,CAAC,IAAI,WAAW,KAAK,CAAE,QAAO;AACzD,KAAI;EACH,MAAM,SAAS,IAAI,IAAI,IAAI;AAE3B,SAAO;GADgB;GAAS;GAAU;GACtB,CAAC,SAAS,OAAO,SAAS;SACvC;AACP,SAAO,qBAAqB,KAAK,IAAI;;GAGvC,EAAE,SAAS,yBAAyB,CACpC,CACD;;;;;AAQD,MAAa,wBAAwBA,OAAE;;;;;AAOvC,MAAa,cAAcA,OAAE,OAAO,MACnCA,OAAE,UAAU,mDAAmD,CAC/D;;;;;AAQD,MAAa,oBAAoBA,OAAE,OAAO,MACzCA,OAAE,UAAU,wDAAwD,CACpE;;;;;AAQD,MAAa,YAAYA,OAAE,OAAO,MAAMA,OAAE,UAAU,gCAAgC,CAAC;;;;;AAQrF,MAAa,mBAAmBA,OAAE,OAAO,MACxCA,OAAE,UAAU,wCAAwC,CACpD;;;;AAOD,MAAa,aAAaA,OAAE,OAAO,MAAMA,OAAE,UAAU,4BAA4B,CAAC;;;;;;;;;;;;;;;AAsBlF,MAAa,cAAc,SAAyB;AACnD,KAAI,CAAC,QAAQ,OAAO,SAAS,SAC5B,QAAO;AAGR,QAAO,KACL,WAAW,KAAK,QAAQ,CACxB,WAAW,KAAK,OAAO,CACvB,WAAW,KAAK,OAAO,CACvB,WAAW,MAAK,SAAS,CACzB,WAAW,KAAK,SAAS;;;;;;;;;;;;;;;;;;;;AAqB5B,MAAa,qBACZ,KACA,mBAA2C;CAAC;CAAS;CAAU;CAAU,KACnC;CACtC,MAAM,sBAAsBA,OAAE,OAAO,MACpCA,OAAE,YACA,MAAc;AACd,MAAI,CAAC,KAAK,EAAE,MAAM,KAAK,GAAI,QAAO;EAClC,MAAM,UAAU,EAAE,MAAM;AACxB,MAAI,QAAQ,WAAW,IAAI,IAAI,CAAC,QAAQ,WAAW,KAAK,CAAE,QAAO;AACjE,MAAI;GACH,MAAM,SAAS,IAAI,IAAI,QAAQ;AAC/B,OAAI,CAAC,iBAAiB,SAAS,OAAO,SAAS,CAAE,QAAO;AACxD,OAAI,OAAO,SAAS,SAAS,cAAc,IAAI,OAAO,SAAS,SAAS,QAAQ,CAC/E,QAAO;AAER,UAAO;UACA;AACP,UACC,qBAAqB,KAAK,QAAQ,IAClC,CAAC,QAAQ,SAAS,cAAc,IAChC,CAAC,QAAQ,SAAS,QAAQ;;IAI7B,EAAE,SAAS,yBAAyB,CACpC,CACD;AAED,QAAOA,OAAE,kBAAkB,oBAAoB,CAAC,IAAI;;;;;;;;;;;;;;;;;AAkBrD,MAAa,eACZ,KACA,mBAA2C;CAAC;CAAS;CAAU;CAAU,KAC7D;CACZ,MAAM,SAAS,kBAAkB,KAAK,iBAAiB;AACvD,QAAO,KAAK,UAAU,OAAO,GAAG,OAAO,QAAQ;;AAGhD,IAAI;AAEJ,MAAM,kBAA2C;AAChD,KAAI,mBAAmB,KAAA,EAAW,QAAO;AAEzC,KAAI,OAAO,WAAW,YACrB,kBAAiB;KAEjB,KAAI;EAQH,MAAM,aAFQ,WACZ,SACuB,mBAAmB,SAAS;AAGrD,MAAI,CAAC,YAAY;AAChB,oBAAiB;AACjB,UAAO;;EAGR,MAAM,EAAE,UADI,WAAW,cAAc,OAAO,KAAK,IAC5B,CAAC,QAAQ;AAQ9B,mBAAiB,UAAU,IADX,MAAM,GACQ,CAAC,OAAO;SAC/B;AACP,mBAAiB;;AAGnB,QAAO;;;;;;;;;;;;;;AAeR,MAAa,gBAAgB,MAAc,YAA6B;AACvE,KAAI,CAAC,QAAQ,OAAO,SAAS,SAC5B,QAAO;CAGR,MAAM,SAAS,WAAW;AAC1B,KAAI,OACH,QAAO,OAAO,SAAS,MAAM,QAAQ;AAGtC,QAAO,WAAW,KAAK;;;;;;;;;;AAWxB,MAAa,2BACZ,OACA,UAA4B,EAAE,KACQ;CACtC,MAAM,EACL,YAAY,KACZ,YAAY,OACZ,gBAAgB,OAChB,iBAAiB,SACd;CAEJ,MAAM,SAASA,OAAE,kBAAkBA,OAAE,OAAO,CAAC,MAAM;AACnD,KAAI,KAAK,UAAU,OAAO,CAAE,QAAO;CAEnC,IAAI,SAAS,OAAO;AAEpB,KAAI,eACH,UAAS,OAAO,MAAM;AAGvB,KAAI,CAAC,WAAW;EACf,IAAI;AACJ,KAAG;AACF,UAAO;AACP,YAAS,OAAO,WAAW,YAAY,GAAG;WAClC,WAAW;OAEpB,UAAS,aAAa,OAAO;AAG9B,KAAI,CAAC,cACJ,UAAS,OAAO,WAAW,YAAY,IAAI;AAG5C,UAAS,OAAO,WAAW,QAAQ,IAAI;CAGvC,IAAI;AACJ,IAAG;AACF,eAAa;AACb,WAAS,OACP,WAAW,iBAAiB,GAAG,CAC/B,WAAW,WAAW,GAAG,CACzB,WAAW,eAAe,GAAG,CAC7B,WAAW,YAAY,GAAG;UACpB,WAAW;AAEpB,QAAO,KAAK,QAAQ,OAAO,MAAM,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;AAmBhD,MAAa,qBAAqB,OAAe,YAAY,KAAK,YAAY,UAAkB;AAC/F,KAAI,CAAC,SAAS,OAAO,UAAU,SAC9B,QAAO;CAGR,MAAM,SAAS,wBAAwB,OAAO;EAAE;EAAW;EAAW,CAAC;AACvE,QAAO,KAAK,UAAU,OAAO,GAAG,OAAO,QAAQ;;;;;AAMhD,MAAM,kBAAkB,KAAc,QAAQ,MAAY;AACzD,KAAI,QAAQ,GACX;AAED,KAAI,OAAO,QAAQ,YAAY,QAAQ,KACtC;AAED,KAAI,MAAM,QAAQ,IAAI,EAAE;AACvB,OAAK,MAAM,QAAQ,IAClB,gBAAe,MAAM,QAAQ,EAAE;AAEhC;;CAED,MAAM,YAAY;EAAC;EAAa;EAAe;EAAY;CAC3D,MAAM,MAAM;AACZ,MAAK,MAAM,OAAO,UACjB,KAAI,OAAO,IACV,QAAO,IAAI;AAGb,MAAK,MAAM,OAAO,OAAO,KAAK,IAAI,CACjC,gBAAe,IAAI,MAAM,QAAQ,EAAE;;;;;;;;;;;;;;;;;;AAoBrC,MAAa,uBACZ,YACA,WACsB;AACtB,KAAI,CAAC,cAAc,OAAO,eAAe,SACxC,QAAO,OAAO,MAAM;AAGrB,KAAI;EACH,MAAM,YAAY,WAChB,WAAW,YAAY,OAAO,CAC9B,WAAW,YAAY,OAAO,CAC9B,WAAW,YAAY,OAAO;EAEhC,MAAM,SAAS,KAAK,MAAM,UAAU;AAEpC,iBAAe,OAAO;EAEtB,MAAM,SAASA,OAAE,kBAAkB,OAAO,CAAC,OAAO;AAClD,SAAO,KAAK,UAAU,OAAO,GAAG,OAAO,KAAK,OAAO,MAAW,GAAG,OAAO,MAAM;SACvE;AACP,SAAO,OAAO,MAAM;;;;;;;;;;;;;;;;;;;;;;;AAwBtB,MAAa,gBAAgB,eAAgC;AAC5D,KAAI,CAAC,cAAc,OAAO,eAAe,SACxC,QAAO;AAGR,KAAI;EACH,MAAM,YAAY,WAChB,WAAW,YAAY,OAAO,CAC9B,WAAW,YAAY,OAAO,CAC9B,WAAW,YAAY,OAAO;EAEhC,MAAM,SAAkB,KAAK,MAAM,UAAU;AAE7C,iBAAe,OAAO;AAEtB,SAAO;SACA;AACP,SAAO;;;;;;;;;;;;;;;AAgBT,MAAa,aAAa,SAAyB;AAClD,KAAI,CAAC,QAAQ,OAAO,SAAS,SAC5B,QAAO;AAGR,QAAO,KAAK,WAAW,mBAAmB,GAAG;;;;;;AAW9C,MAAM,eAAe;CACpB,KAAK;EAAE,SAAS;EAAoC,QAAQ;EAAS;CACrE,YAAY;EAAE,SAAS;EAAgC,QAAQ;EAAiB;CAChF,eAAe;EAAE,SAAS;EAAkB,QAAQ;EAAiB;CACrE,OAAO;EAAE,SAAS;EAAwD,QAAQ;EAAW;CAC7F,OAAO;EAAE,SAAS;EAA4D,QAAQ;EAAW;CACjG,MAAM;EAAE,SAAS;EAAgC,QAAQ;EAAgB;CACzE,MAAM;EAAE,SAAS;EAAiD,QAAQ;EAAgB;CAC1F,MAAM;EACL,SAAS;EACT,QAAQ;EACR;CACD;;;;;;;;;AAUD,MAAa,mBACZ,MACA,UAA+B,EAAE,KACK;CACtC,MAAM,SAASA,OAAE,kBAAkB,0BAA0B,CAAC,QAAQ;AACtE,KAAI,KAAK,UAAU,OAAO,CAAE,QAAO,KAAK,UAAU,OAAO,MAAM;CAE/D,MAAM,EACL,eAAe,MACf,eAAe,MACf,YAAY,MACZ,oBAAoB,MACpB,YAAY,MACZ,cAAc,UACX,OAAO;CAEX,IAAI,SAAS;AAEb,KAAI,UACH,UAAS,OAAO,WAAW,aAAa,IAAI,SAAS,aAAa,IAAI,OAAO;AAG9E,KAAI,mBAAmB;AACtB,WAAS,OAAO,WAAW,aAAa,WAAW,SAAS,aAAa,WAAW,OAAO;AAC3F,WAAS,OAAO,WACf,aAAa,cAAc,SAC3B,aAAa,cAAc,OAC3B;;AAGF,KAAI,aACH,UAAS,OAAO,WAAW,aAAa,MAAM,SAAS,aAAa,MAAM,OAAO;AAGlF,KAAI,aACH,UAAS,OAAO,WAAW,aAAa,MAAM,SAAS,aAAa,MAAM,OAAO;AAGlF,KAAI,WAAW;AACd,WAAS,OAAO,WAAW,aAAa,KAAK,SAAS,aAAa,KAAK,OAAO;AAC/E,WAAS,OAAO,WAAW,aAAa,KAAK,SAAS,aAAa,KAAK,OAAO;;AAGhF,KAAI,YACH,UAAS,OAAO,WAAW,aAAa,KAAK,SAAS,aAAa,KAAK,OAAO;AAGhF,QAAO,KAAK,QAAQ,OAAO;;;;;;;;;;;;;;;;;;;;AAqB5B,MAAa,aACZ,MACA,UAEI,EAAE,KACM;AACZ,KAAI,CAAC,QAAQ,OAAO,SAAS,SAC5B,QAAO;CAGR,MAAM,EACL,eAAe,MACf,eAAe,MACf,YAAY,MACZ,oBAAoB,MACpB,YAAY,MACZ,cAAc,OACd,iBAAiB,EAAE,KAChB;CAEJ,MAAM,SAAS,gBAAgB,MAAM;EACpC;EACA;EACA;EACA;EACA;EACA;EACA,CAAC;CAEF,IAAI,SAAS,KAAK,UAAU,OAAO,GAAG,OAAO,QAAQ;AAErD,MAAK,MAAM,EAAE,SAAS,iBAAiB,eACtC,UAAS,OAAO,WAAW,SAAS,YAAY;AAGjD,QAAO;;;;;;;;;;;;;;;;;;AAmBR,MAAa,iBACZ,KACA,gBAA0B;CACzB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA,EACD,SAAS,MACG;CACZ,MAAM,qBAAqB,IAAI,IAAI,cAAc,KAAK,MAAM,EAAE,aAAa,CAAC,CAAC;CAE7E,MAAM,YAAY,MAAc,UAA4B;AAC3D,MAAI,QAAQ,mBAAmB,IAAI,KAAK,aAAa,CAAC,CACrD,QAAO;AAER,SAAO;;AAGR,KAAI;AACH,SAAO,KAAK,UAAU,KAAK,UAAU,OAAO;SACrC;AACP,SAAO;;;;;;;;;;;;AAiBT,MAAa,gBAAgB,UAAkC;AAC9D,QAAO,KAAK,UAAUA,OAAE,kBAAkB,YAAY,CAAC,MAAM,CAAC;;;;;;;;;;AAW/D,MAAa,gBAAgB,UAAwC;AACpE,QAAO,KAAK,UAAUA,OAAE,kBAAkB,kBAAkB,CAAC,MAAM,CAAC;;;;;;;;;;AAWrE,MAAa,cAAc,QAA4B;AACtD,QAAO,KAAK,UAAUA,OAAE,kBAAkB,UAAU,CAAC,IAAI,CAAC;;;;;;;;;;AAW3D,MAAa,cAAc,QAAgC;AAC1D,QAAO,KAAK,UAAUA,OAAE,kBAAkB,cAAc,CAAC,IAAI,CAAC"}