@resq-systems/security 1.0.5 → 2.1.0

package/lib/sanitize.mjs

@@ -2,7 +2,7 @@ import { Exit, Option, Schema } from "effect";
 import DOMPurify from "dompurify";
 //#region src/sanitize.ts
 /**
-* Schema for URL protocol validation
+* Schema constraining a URL protocol to the recognized safe set.
 * @compliance NIST 800-53 SI-10 (Information Input Validation)
 */
 const UrlProtocolSchema = Schema.Literals([
@@ -13,7 +13,7 @@ const UrlProtocolSchema = Schema.Literals([
 	"ftp:"
 ]);
 /**
-* Schema for PII redaction options
+* Schema for the per-category toggles that drive {@link redactPII}.
 * @compliance NIST 800-53 AU-3 (Content of Audit Records)
 */
 const PIIRedactionOptionsSchema = Schema.Struct({
@@ -25,7 +25,7 @@ const PIIRedactionOptionsSchema = Schema.Struct({
 	redactDates: Schema.optional(Schema.Boolean)
 });
 /**
-* Schema for user input validation options
+* Schema for the options controlling {@link validateUserInputEffect}.
 * @compliance NIST 800-53 SI-10 (Information Input Validation)
 */
 const UserInputOptionsSchema = Schema.Struct({
@@ -35,12 +35,29 @@ const UserInputOptionsSchema = Schema.Struct({
 	trimWhitespace: Schema.optional(Schema.Boolean)
 });
 /**
-* Schema for safe URL - validates URL format and protocol
+* Schema for a safe URL — validates URL format and restricts to safe protocols.
 * @compliance NIST 800-53 SI-10 (Information Input Validation)
 */
+/**
+* Whether a reference opens a URL *authority* component — i.e. can name a different
+* host once resolved against a base.
+*
+* `//evil.example` resolved against `https://trusted.example/page` yields host
+* `evil.example`, and so do `///evil.example` and `/\evil.example`: the WHATWG URL
+* parser treats a backslash as a slash in the relative-slash state.
+*
+* This must be checked **before** the root-relative fast path. A `startsWith("//")`
+* guard alone is insufficient twice over: it misses the backslash forms entirely, and
+* `//evil.example` that falls through to `new URL()` throws without a base and lands in
+* the catch branch, whose `[a-zA-Z0-9/_.-]` character class happily accepts it.
+*
+* @internal
+*/
+const opensAuthority = (url) => /^[/\\]{2}/.test(url.trim());
 const SafeUrlSchema = Schema.String.check(Schema.makeFilter((url) => {
 	if (!url || url.trim() === "") return false;
-	if (url.startsWith("/") && !url.startsWith("//")) return true;
+	if (opensAuthority(url)) return false;
+	if (url.startsWith("/")) return true;
 	try {
 		const parsed = new URL(url);
 		return [
@@ -53,7 +70,8 @@ const SafeUrlSchema = Schema.String.check(Schema.makeFilter((url) => {
 	}
 }, { message: "Invalid or unsafe URL" }));
 /**
-* Schema for sanitized HTML-safe string (validates as string; escaping done at runtime)
+* Schema for a sanitized HTML-safe string — validates the value is a string; the
+* actual escaping is applied at runtime by the sanitization helpers.
 * @compliance NIST 800-53 SI-10 (Information Input Validation)
 */
 const SanitizedStringSchema = Schema.String;
@@ -67,22 +85,22 @@ const SanitizedStringSchema = Schema.String;
 */
 const EmailSchema = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.(?:[A-Za-z]{2,}|xn--[A-Za-z0-9-]+)$/));
 /**
-* Schema for phone number validation (US format)
+* 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)
+* 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
+* 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
+* Schema for IPv4 address validation.
 */
 const IPv4Schema = Schema.String.check(Schema.isPattern(/^(?:\d{1,3}\.){3}\d{1,3}$/));
 /**
@@ -107,9 +125,16 @@ const escapeHtml = (text) => {
 * Validates and sanitizes a user-supplied URL using Effect Schema.
 * Returns an Exit with the sanitized URL or an error.
 *
+* Pure and total — failure is encoded as a resolved {@link Exit.Exit} failure
+* (an `Exit.fail` carrying a {@link S.SchemaError}), never a thrown exception.
+*
 * @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.
+* @param allowedProtocols - Allowed URL protocols; a root-relative path (`/foo`) is
+*   always accepted regardless of this list. An authority-opening reference — `//host`,
+*   `///host`, or `/\host` — is always **rejected**, because it names a different host
+*   once resolved and would otherwise bypass this list entirely.
+* @returns An {@link Exit.Exit}: success carries the accepted URL string,
+*   failure carries a {@link S.SchemaError}.
 * @compliance NIST 800-53 SI-10 (Information Input Validation)
 *
 * @example
@@ -129,7 +154,8 @@ const sanitizeUrlEffect = (url, allowedProtocols = [
 	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;
+		if (opensAuthority(trimmed)) return false;
+		if (trimmed.startsWith("/")) return true;
 		try {
 			const parsed = new URL(trimmed);
 			if (!allowedProtocols.includes(parsed.protocol)) return false;
@@ -165,9 +191,42 @@ const sanitizeUrl = (url, allowedProtocols = [
 	return Exit.isSuccess(result) ? result.value : "";
 };
 let purifyInstance;
+/**
+* Add `rel="noopener noreferrer"` to any link that opens a new browsing context.
+*
+* Without it the opened page receives a live `window.opener` handle and can navigate
+* the original tab to a phishing page — reverse tabnabbing, WSTG-CLNT-14. DOMPurify
+* does not add this by default, and unlike most of CLNT-14 the fix lives inside code
+* this package already owns, so a weakness no signature can detect becomes one that is
+* simply prevented.
+*
+* Modern browsers imply `noopener` for `target="_blank"`; this covers older engines and
+* the named-target case (`target="win1"`), which remains exploitable everywhere.
+*
+* Note that DOMPurify's default configuration strips `target` outright, so this hook is
+* a no-op unless the caller opts back in with `ADD_ATTR: ["target"]` or a custom
+* `ALLOWED_ATTR` — which is precisely the configuration that reintroduces the risk.
+*
+* @internal
+*/
+const addNoopenerToTargetedLinks = (node) => {
+	if (typeof node.hasAttribute !== "function" || !node.hasAttribute("target")) return;
+	const target = node.getAttribute("target");
+	if (target === null || target === "_self" || target === "_parent" || target === "_top") return;
+	const existing = (node.getAttribute("rel") ?? "").split(/\s+/).filter(Boolean);
+	for (const required of ["noopener", "noreferrer"]) if (!existing.includes(required)) existing.push(required);
+	node.setAttribute("rel", existing.join(" "));
+};
+/** Register the reverse-tabnabbing hook on a DOMPurify instance. */
+const withHooks = (purify) => {
+	purify.addHook("afterSanitizeAttributes", (node) => {
+		addNoopenerToTargetedLinks(node);
+	});
+	return purify;
+};
 const getPurify = () => {
 	if (purifyInstance !== void 0) return purifyInstance;
-	if (typeof window !== "undefined") purifyInstance = DOMPurify;
+	if (typeof window !== "undefined") purifyInstance = withHooks(DOMPurify);
 	else try {
 		const nodeModule = globalThis.process?.getBuiltinModule?.("module");
 		if (!nodeModule) {
@@ -175,7 +234,8 @@ const getPurify = () => {
 			return purifyInstance;
 		}
 		const { JSDOM } = nodeModule.createRequire(import.meta.url)("jsdom");
-		purifyInstance = DOMPurify(new JSDOM("").window);
+		const dom = new JSDOM("");
+		purifyInstance = withHooks(DOMPurify(dom.window));
 	} catch {
 		purifyInstance = null;
 	}
@@ -189,9 +249,16 @@ const getPurify = () => {
 * NOTE: Server-side HTML sanitization requires `jsdom` to be installed in the consuming application
 * environment; otherwise, it will fall back to escaping HTML characters.
 *
+* On the first server-side call this lazily resolves `node:module` and
+* `require`s `jsdom` to build a DOMPurify instance; the instance is cached at
+* module scope, so subsequent calls incur no further module loading. Returns
+* `""` for non-string or empty input and never throws — any loader failure is
+* swallowed and downgraded to {@link escapeHtml}.
+*
 * @param html - The HTML string to sanitize.
 * @param options - Optional DOMPurify configuration.
-* @returns The sanitized HTML string.
+* @returns The sanitized HTML string, or the escaped string when no DOM is
+*   available.
 */
 const sanitizeHtml = (html, options) => {
 	if (!html || typeof html !== "string") return "";
@@ -202,9 +269,17 @@ const sanitizeHtml = (html, options) => {
 /**
 * Validates user input using Effect Schema and returns an Exit.
 *
+* Strips HTML (unless `allowHtml`), collapses whitespace, and repeatedly
+* removes dangerous URI schemes and inline handlers until the string
+* stabilizes — the fixed-point loop defeats nested-payload bypasses such as
+* `javascrjavascript:ipt:`. Failure is a resolved {@link Exit.Exit} failure,
+* never a throw; the only failure path is a non-string reaching `S.String`.
+*
 * @param input - User input to validate and sanitize.
-* @param options - Validation options.
-* @returns Exit containing sanitized input or error.
+* @param options - Validation options. Defaults: `maxLength` 500, `allowHtml`
+*   false, `allowNewlines` false, `trimWhitespace` true.
+* @returns An {@link Exit.Exit}: success carries the sanitized string truncated
+*   to `maxLength`; failure carries a {@link S.SchemaError}.
 * @compliance NIST 800-53 SI-10 (Information Input Validation)
 */
 const validateUserInputEffect = (input, options = {}) => {
@@ -253,32 +328,52 @@ const validateUserInput = (input, maxLength = 500, allowHtml = false) => {
 	});
 	return Exit.isSuccess(result) ? result.value : "";
 };
+/** Own keys removed at every level, because assigning them reaches the prototype. */
+const DANGEROUS_KEYS = [
+	"__proto__",
+	"constructor",
+	"prototype"
+];
 /**
-* Recursively removes dangerous prototype pollution keys from an object.
+* Strip prototype-pollution keys (`__proto__`, `constructor`, `prototype`) from
+* every node of a parsed JSON value.
+*
+* **Mutates `val` in place** (deletes offending keys) and returns nothing;
+* callers pass a freshly `JSON.parse`d value they own. The walk is iterative and
+* unbounded in depth: every node is visited, however deeply nested.
+*
+* @internal
 */
-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 sanitizeObject = (val) => {
+	const stack = [val];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (typeof current !== "object" || current === null) continue;
+		if (Array.isArray(current)) {
+			for (const item of current) stack.push(item);
+			continue;
+		}
+		const obj = current;
+		for (const key of DANGEROUS_KEYS) if (key in obj) delete obj[key];
+		for (const key of Object.keys(obj)) stack.push(obj[key]);
 	}
-	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
+* Never throws: malformed JSON, a non-string argument, and schema-validation
+* failure all resolve to {@link Option.none} rather than a thrown error, so the
+* failure channel is the `Option` itself. As a side effect the parsed value is
+* stripped of prototype-pollution keys in place before validation (the value is
+* freshly created by `JSON.parse`, so no caller state is mutated).
+*
+* @template A - The decoded value type the `schema` produces on success; the
+*   returned `Option` carries this type.
 * @param jsonString - The JSON string to parse.
-* @param schema - Effect Schema to validate against.
-* @returns Option containing the parsed and validated object.
+* @param schema - Effect Schema to validate against; its decode must require no
+*   services ({@link SyncSchema}) so parsing stays synchronous.
+* @returns {@link Option.some} with the parsed, validated value, or
+*   {@link Option.none} on any parse or validation failure.
 * @compliance NIST 800-53 SI-10 (Information Input Validation)
 *
 * @example
@@ -332,8 +427,17 @@ const sanitizeJson = (jsonString) => {
 	}
 };
 /**
-* Strips ANSI escape codes from a string.
-* Useful for cleaning terminal output before logging to files.
+* Strips ANSI escape sequences from a string.
+*
+* Removes CSI sequences (colour, cursor movement, screen and line erasure, mode
+* switches), OSC sequences (window title and similar), two-character escapes, and
+* any bare ESC left over. This is the control named by `LOG-ANSI-ESCAPE-001`: a
+* terminal-backed log sink treats these as commands, so an attacker who lands them
+* in a log can scroll earlier entries away or overwrite them (CWE-117).
+*
+* Removal is destructive by design — the sequence goes, and any text it carried
+* goes with it. Where the record matters more than the rendering, escape the
+* characters instead of deleting them.
 *
 * @param text - The text potentially containing ANSI codes.
 * @returns The text with ANSI codes removed.
@@ -345,10 +449,11 @@ const sanitizeJson = (jsonString) => {
 */
 const stripAnsi = (text) => {
 	if (!text || typeof text !== "string") return "";
-	return text.replaceAll(/\x1b\[[0-9;]*m/g, "");
+	return text.replaceAll(/\u001b(?:\[[0-?]{0,32}[ -/]{0,8}[@-~]|\][^\u0007\u001b]{0,512}(?:\u0007|\u001b\\)|[ -/]{0,8}[0-~])?/g, "");
 };
 /**
-* PII pattern definitions with Effect Schema validation
+* PII pattern catalog: each entry pairs a global-match regex with the marker that
+* replaces every hit during redaction.
 * @compliance NIST 800-53 AU-3 (Content of Audit Records)
 */
 const PII_PATTERNS = {
@@ -388,9 +493,15 @@ const PII_PATTERNS = {
 /**
 * Redacts PII from text using Effect Schema validated options.
 *
+* Total — never throws. Failure to decode `options` is returned as a resolved
+* {@link Exit.Exit} failure carrying the {@link S.SchemaError}. By default
+* dates are **not** redacted (`redactDates` defaults to `false`); every other
+* category defaults to `true`.
+*
 * @param text - The text to redact PII from.
 * @param options - Configuration options for redaction.
-* @returns Exit containing redacted text or error.
+* @returns An {@link Exit.Exit}: success carries the redacted text, failure
+*   carries a {@link S.SchemaError} from invalid `options`.
 * @compliance NIST 800-53 AU-3 (Content of Audit Records)
 */
 const redactPIIEffect = (text, options = {}) => {
@@ -416,9 +527,15 @@ const redactPIIEffect = (text, options = {}) => {
 * 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.
+* @param text - The text to redact PII from. Non-string input yields `""`.
+* @param options - Configuration options for redaction, plus optional
+*   `customPatterns` applied after the built-ins. Each `pattern` **must** be a
+*   global (`/g`) RegExp.
+* @returns The text with PII patterns replaced with redaction markers, or `""`
+*   for non-string input. If the built-in options fail schema validation the
+*   original `text` is returned unredacted rather than throwing.
+* @throws {TypeError} If any `customPatterns` entry uses a non-global RegExp —
+*   `String.prototype.replaceAll` rejects non-global patterns.
 * @compliance NIST 800-53 AU-3 (Content of Audit Records)
 *
 * @example
@@ -449,10 +566,17 @@ const redactPII = (text, options = {}) => {
 * Creates a safe string representation of an object for logging,
 * automatically redacting sensitive fields.
 *
+* Never throws: any serialization failure — a circular reference, a `BigInt`
+* value, a throwing `toJSON` — is caught and returned as the sentinel string
+* `"[Unable to stringify object]"`. Key matching is case-insensitive and
+* compares the full key name (not substrings), so `apiKey` matches only the
+* literal `"apiKey"`, not `"apiKeyId"`.
+*
 * @param obj - The object to stringify.
-* @param sensitiveKeys - Array of key names to redact.
+* @param sensitiveKeys - Key names to redact, compared case-insensitively.
 * @param indent - JSON indentation (default: 2).
-* @returns A JSON string with sensitive values redacted.
+* @returns A JSON string with sensitive values redacted, or the sentinel
+*   `"[Unable to stringify object]"` when serialization fails.
 * @compliance NIST 800-53 AU-3 (Content of Audit Records)
 *
 * @example

package/lib/sanitize.mjs.map

@@ -1 +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 *\n * Accepts a 2+ character alphabetic TLD or a Punycode/IDN `xn--…` TLD (e.g.\n * `.xn--p1ai` for `.рф`) so internationalized domains are not rejected. Kept in\n * sync with `@resq-systems/email-templates`'s `EmailAddress` brand.\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,}|xn--[A-Za-z0-9-]+)$/),\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\t// TLD alternation mirrors `EmailSchema` so IDN/Punycode addresses\n\t// (e.g. `user@example.xn--p1ai`) are redacted, not leaked. The `xn--` branch\n\t// is tried first: unlike the anchored (`$`) validators, this pattern ends in\n\t// `\\b`, so `[A-Za-z]{2,}` would otherwise match just `xn` and stop at the\n\t// hyphen, leaving `--p1ai` unredacted. (Also drops the stray `|` from the\n\t// former `[A-Z|a-z]` class.)\n\temail: {\n\t\tpattern: /\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.(?:xn--[A-Za-z0-9-]+|[A-Za-z]{2,})\\b/g,\n\t\tmarker: \"[EMAIL]\",\n\t},\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":"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"}
+{"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 * @fileoverview Type-safe input sanitization built on Effect Schema — HTML escaping\n * and DOMPurify-backed HTML sanitization, safe-URL validation, prototype-pollution-\n * hardened JSON parsing, PII redaction, and branded validators for email, phone, SSN,\n * and more. Supports NIST 800-53 SI-10 (input validation) and AU-3 (audit content).\n *\n * @module @resq-systems/security/sanitize\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//#region Types\n\n/**\n * A Schema whose decoding services are constrained to `never`, allowing synchronous\n * decoding without an Effect runtime.\n */\ntype SyncSchema<T> = S.Codec<T, unknown, never>;\n//#endregion\n\n//#region Schemas\n\n/**\n * Schema constraining a URL protocol to the recognized safe set.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const UrlProtocolSchema = S.Literals([\"http:\", \"https:\", \"mailto:\", \"tel:\", \"ftp:\"]);\n/** One of the protocols accepted by {@link UrlProtocolSchema}. */\nexport type UrlProtocol = typeof UrlProtocolSchema.Type;\n\n/**\n * Schema for the per-category toggles that drive {@link redactPII}.\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});\n/** Decoded options accepted by {@link redactPIIEffect} / {@link redactPII}. */\nexport type PIIRedactionOptions = typeof PIIRedactionOptionsSchema.Type;\n\n/**\n * Schema for the options controlling {@link validateUserInputEffect}.\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});\n/** Decoded options accepted by {@link validateUserInputEffect}. */\nexport type UserInputOptions = typeof UserInputOptionsSchema.Type;\n\n/**\n * Schema for a safe URL — validates URL format and restricts to safe protocols.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\n/**\n * Whether a reference opens a URL *authority* component — i.e. can name a different\n * host once resolved against a base.\n *\n * `//evil.example` resolved against `https://trusted.example/page` yields host\n * `evil.example`, and so do `///evil.example` and `/\\evil.example`: the WHATWG URL\n * parser treats a backslash as a slash in the relative-slash state.\n *\n * This must be checked **before** the root-relative fast path. A `startsWith(\"//\")`\n * guard alone is insufficient twice over: it misses the backslash forms entirely, and\n * `//evil.example` that falls through to `new URL()` throws without a base and lands in\n * the catch branch, whose `[a-zA-Z0-9/_.-]` character class happily accepts it.\n *\n * @internal\n */\nconst opensAuthority = (url: string): boolean => /^[/\\\\]{2}/.test(url.trim());\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 (opensAuthority(url)) return false;\n\t\t\tif (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/**\n * A URL string vouched safe against scheme-based injection. Mint one by\n * narrowing through the {@link isValidUrl} type guard (backed by\n * {@link SafeUrlSchema}); the brand guarantees the value is either a\n * root-relative path or an absolute URL restricted to `http:`/`https:`/\n * `mailto:`. An authority-opening reference (`//host`, `///host`, `/\\host`) is\n * rejected, since resolving one against a base yields a different host.\n *\n * It does **not** guarantee the host is reachable or trusted — for that, validate the\n * resolved origin with `isAllowedOrigin` from `@resq-systems/security/controls`.\n */\nexport type SafeUrl = Brand<string, \"SafeUrl\">;\n\n/**\n * Schema for a sanitized HTML-safe string — validates the value is a string; the\n * actual escaping is applied at runtime by the sanitization helpers.\n * @compliance NIST 800-53 SI-10 (Information Input Validation)\n */\nexport const SanitizedStringSchema = S.String;\n/**\n * A string carrying the {@link SanitizedStringSchema} contract. The schema is\n * `S.String` alone, so decoding asserts only that the value is a string —\n * the actual escaping is applied separately by the sanitization helpers\n * (e.g. {@link escapeHtml}). The type name signals intent, not a proof of\n * escaping.\n */\nexport type SanitizedString = typeof SanitizedStringSchema.Type;\n\n/**\n * Schema for email address validation.\n *\n * Accepts a 2+ character alphabetic TLD or a Punycode/IDN `xn--…` TLD (e.g.\n * `.xn--p1ai` for `.рф`) so internationalized domains are not rejected. Kept in\n * sync with `@resq-systems/email-templates`'s `EmailAddress` brand.\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,}|xn--[A-Za-z0-9-]+)$/),\n);\n/**\n * An email address that matches {@link EmailSchema}. Mint one by narrowing\n * through the {@link isValidEmail} type guard. The brand guarantees only\n * syntactic well-formedness (including IDN/Punycode TLDs) — not that the\n * mailbox exists or is deliverable.\n */\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/**\n * A US-format phone number matching {@link PhoneNumberSchema}. Mint one by\n * narrowing through the {@link isValidPhone} type guard. The brand asserts\n * the digit/separator shape only; it neither normalizes formatting nor\n * confirms the number is assigned.\n */\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/**\n * A US Social Security Number matching {@link SSNSchema}. Mint one by\n * narrowing through the {@link isValidSSN} type guard. The brand asserts\n * the `NNN-NN-NNNN` shape only — it does not validate area/group ranges or\n * confirm the number was ever issued. Treat any value as sensitive PII.\n */\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/**\n * A card number matching the {@link CreditCardSchema} pattern (13–16 digits\n * with optional group separators). No exported type guard mints this brand;\n * decode {@link CreditCardSchema} directly at the boundary. The pattern is a\n * shape check only — it performs **no** Luhn checksum and does not identify\n * the issuer. Treat any value as sensitive PII.\n */\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/**\n * A dotted-quad string matching {@link IPv4Schema}. No exported type guard\n * mints this brand; decode {@link IPv4Schema} directly. The pattern checks\n * four dot-separated groups of 1–3 digits only — it does **not** bound each\n * octet to `0–255`, so `999.0.0.1` still matches.\n */\nexport type IPv4 = Brand<string, \"IPv4\">;\n//#endregion\n\n//#region Sanitization\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 * Pure and total — failure is encoded as a resolved {@link Exit.Exit} failure\n * (an `Exit.fail` carrying a {@link S.SchemaError}), never a thrown exception.\n *\n * @param url - The URL to be validated and sanitized.\n * @param allowedProtocols - Allowed URL protocols; a root-relative path (`/foo`) is\n *   always accepted regardless of this list. An authority-opening reference — `//host`,\n *   `///host`, or `/\\host` — is always **rejected**, because it names a different host\n *   once resolved and would otherwise bypass this list entirely.\n * @returns An {@link Exit.Exit}: success carries the accepted URL string,\n *   failure carries a {@link S.SchemaError}.\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\t// Before the root-relative fast path: an authority-opening reference can\n\t\t\t\t// name a different host and bypasses `allowedProtocols` entirely.\n\t\t\t\tif (opensAuthority(trimmed)) return false;\n\t\t\t\tif (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\n/**\n * Add `rel=\"noopener noreferrer\"` to any link that opens a new browsing context.\n *\n * Without it the opened page receives a live `window.opener` handle and can navigate\n * the original tab to a phishing page — reverse tabnabbing, WSTG-CLNT-14. DOMPurify\n * does not add this by default, and unlike most of CLNT-14 the fix lives inside code\n * this package already owns, so a weakness no signature can detect becomes one that is\n * simply prevented.\n *\n * Modern browsers imply `noopener` for `target=\"_blank\"`; this covers older engines and\n * the named-target case (`target=\"win1\"`), which remains exploitable everywhere.\n *\n * Note that DOMPurify's default configuration strips `target` outright, so this hook is\n * a no-op unless the caller opts back in with `ADD_ATTR: [\"target\"]` or a custom\n * `ALLOWED_ATTR` — which is precisely the configuration that reintroduces the risk.\n *\n * @internal\n */\nconst addNoopenerToTargetedLinks = (node: Element): void => {\n\tif (typeof node.hasAttribute !== \"function\" || !node.hasAttribute(\"target\")) return;\n\n\tconst target = node.getAttribute(\"target\");\n\t// `_self`, `_parent`, and `_top` stay in the current context and grant no handle.\n\tif (target === null || target === \"_self\" || target === \"_parent\" || target === \"_top\") return;\n\n\tconst existing = (node.getAttribute(\"rel\") ?? \"\").split(/\\s+/).filter(Boolean);\n\tfor (const required of [\"noopener\", \"noreferrer\"]) {\n\t\tif (!existing.includes(required)) existing.push(required);\n\t}\n\tnode.setAttribute(\"rel\", existing.join(\" \"));\n};\n\n/** Register the reverse-tabnabbing hook on a DOMPurify instance. */\nconst withHooks = (purify: typeof DOMPurify): typeof DOMPurify => {\n\tpurify.addHook(\"afterSanitizeAttributes\", (node) => {\n\t\taddNoopenerToTargetedLinks(node as unknown as Element);\n\t});\n\treturn purify;\n};\n\nconst getPurify = (): typeof DOMPurify | null => {\n\tif (purifyInstance !== undefined) return purifyInstance;\n\n\tif (typeof window !== \"undefined\") {\n\t\tpurifyInstance = withHooks(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 = withHooks(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 * On the first server-side call this lazily resolves `node:module` and\n * `require`s `jsdom` to build a DOMPurify instance; the instance is cached at\n * module scope, so subsequent calls incur no further module loading. Returns\n * `\"\"` for non-string or empty input and never throws — any loader failure is\n * swallowed and downgraded to {@link escapeHtml}.\n *\n * @param html - The HTML string to sanitize.\n * @param options - Optional DOMPurify configuration.\n * @returns The sanitized HTML string, or the escaped string when no DOM is\n *   available.\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 * Strips HTML (unless `allowHtml`), collapses whitespace, and repeatedly\n * removes dangerous URI schemes and inline handlers until the string\n * stabilizes — the fixed-point loop defeats nested-payload bypasses such as\n * `javascrjavascript:ipt:`. Failure is a resolved {@link Exit.Exit} failure,\n * never a throw; the only failure path is a non-string reaching `S.String`.\n *\n * @param input - User input to validate and sanitize.\n * @param options - Validation options. Defaults: `maxLength` 500, `allowHtml`\n *   false, `allowNewlines` false, `trimWhitespace` true.\n * @returns An {@link Exit.Exit}: success carries the sanitized string truncated\n *   to `maxLength`; failure carries a {@link S.SchemaError}.\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/** Own keys removed at every level, because assigning them reaches the prototype. */\nconst DANGEROUS_KEYS = [\"__proto__\", \"constructor\", \"prototype\"] as const;\n\n/**\n * Strip prototype-pollution keys (`__proto__`, `constructor`, `prototype`) from\n * every node of a parsed JSON value.\n *\n * **Mutates `val` in place** (deletes offending keys) and returns nothing;\n * callers pass a freshly `JSON.parse`d value they own. The walk is iterative and\n * unbounded in depth: every node is visited, however deeply nested.\n *\n * @internal\n */\nconst sanitizeObject = (val: unknown): void => {\n\t// Walked with an explicit stack rather than by recursion. The previous version\n\t// bounded itself at depth 50 to avoid overflowing the call stack and returned\n\t// early past that, so wrapping the payload in 51 layers carried `__proto__`\n\t// through untouched — and feeding the resulting leaf to an ordinary recursive\n\t// deep-merge set `Object.prototype.isAdmin`. The cap was never cycle protection:\n\t// both callers parse JSON first, and JSON cannot express a cycle. Dropping the\n\t// recursion removes the reason for the cap, so every node is now visited.\n\tconst stack: unknown[] = [val];\n\n\twhile (stack.length > 0) {\n\t\tconst current = stack.pop();\n\n\t\tif (typeof current !== \"object\" || current === null) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (Array.isArray(current)) {\n\t\t\tfor (const item of current) {\n\t\t\t\tstack.push(item);\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst obj = current as Record<string, unknown>;\n\t\tfor (const key of DANGEROUS_KEYS) {\n\t\t\tif (key in obj) {\n\t\t\t\tdelete obj[key];\n\t\t\t}\n\t\t}\n\t\tfor (const key of Object.keys(obj)) {\n\t\t\tstack.push(obj[key]);\n\t\t}\n\t}\n};\n\n/**\n * Safely parses JSON with Effect Schema validation and prototype pollution protection.\n *\n * Never throws: malformed JSON, a non-string argument, and schema-validation\n * failure all resolve to {@link Option.none} rather than a thrown error, so the\n * failure channel is the `Option` itself. As a side effect the parsed value is\n * stripped of prototype-pollution keys in place before validation (the value is\n * freshly created by `JSON.parse`, so no caller state is mutated).\n *\n * @template A - The decoded value type the `schema` produces on success; the\n *   returned `Option` carries this type.\n * @param jsonString - The JSON string to parse.\n * @param schema - Effect Schema to validate against; its decode must require no\n *   services ({@link SyncSchema}) so parsing stays synchronous.\n * @returns {@link Option.some} with the parsed, validated value, or\n *   {@link Option.none} on any parse or validation failure.\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 sequences from a string.\n *\n * Removes CSI sequences (colour, cursor movement, screen and line erasure, mode\n * switches), OSC sequences (window title and similar), two-character escapes, and\n * any bare ESC left over. This is the control named by `LOG-ANSI-ESCAPE-001`: a\n * terminal-backed log sink treats these as commands, so an attacker who lands them\n * in a log can scroll earlier entries away or overwrite them (CWE-117).\n *\n * Removal is destructive by design — the sequence goes, and any text it carried\n * goes with it. Where the record matters more than the rendering, escape the\n * characters instead of deleting them.\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// Every escape sequence, not just the colour ones. The previous pattern was\n\t// `/\\\\x1b\\\\[[0-9;]*m/` — SGR only — so `ESC[2J` (erase display), `ESC[?1049h`\n\t// (alternate screen buffer), `ESC[5A` (cursor up, which overwrites the audit\n\t// lines already written) and `ESC]0;...` (set window title) all survived the\n\t// function that `LOG-ANSI-ESCAPE-001` names as its control. Colour was the one\n\t// case handled, and the only one that is merely cosmetic.\n\t//\n\t// Alternatives are ordered CSI, OSC, then the general ECMA-48 form (ESC,\n\t// intermediates 0x20-0x2F, final 0x30-0x7E), which covers Fs escapes such as\n\t// ESC c. Every quantifier is bounded and none is nested, so nothing backtracks.\n\t// A trailing `?` also removes a bare ESC that begins no valid sequence.\n\treturn text.replaceAll(\n\t\t// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping ANSI requires matching control characters\n\t\t/\\u001b(?:\\[[0-?]{0,32}[ -/]{0,8}[@-~]|\\][^\\u0007\\u001b]{0,512}(?:\\u0007|\\u001b\\\\)|[ -/]{0,8}[0-~])?/g,\n\t\t\"\",\n\t);\n};\n\n//#endregion\n\n//#region PII Redaction\n\n/**\n * PII pattern catalog: each entry pairs a global-match regex with the marker that\n * replaces every hit during redaction.\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\t// TLD alternation mirrors `EmailSchema` so IDN/Punycode addresses\n\t// (e.g. `user@example.xn--p1ai`) are redacted, not leaked. The `xn--` branch\n\t// is tried first: unlike the anchored (`$`) validators, this pattern ends in\n\t// `\\b`, so `[A-Za-z]{2,}` would otherwise match just `xn` and stop at the\n\t// hyphen, leaving `--p1ai` unredacted. (Also drops the stray `|` from the\n\t// former `[A-Z|a-z]` class.)\n\temail: {\n\t\tpattern: /\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.(?:xn--[A-Za-z0-9-]+|[A-Za-z]{2,})\\b/g,\n\t\tmarker: \"[EMAIL]\",\n\t},\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 * Total — never throws. Failure to decode `options` is returned as a resolved\n * {@link Exit.Exit} failure carrying the {@link S.SchemaError}. By default\n * dates are **not** redacted (`redactDates` defaults to `false`); every other\n * category defaults to `true`.\n *\n * @param text - The text to redact PII from.\n * @param options - Configuration options for redaction.\n * @returns An {@link Exit.Exit}: success carries the redacted text, failure\n *   carries a {@link S.SchemaError} from invalid `options`.\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. Non-string input yields `\"\"`.\n * @param options - Configuration options for redaction, plus optional\n *   `customPatterns` applied after the built-ins. Each `pattern` **must** be a\n *   global (`/g`) RegExp.\n * @returns The text with PII patterns replaced with redaction markers, or `\"\"`\n *   for non-string input. If the built-in options fail schema validation the\n *   original `text` is returned unredacted rather than throwing.\n * @throws {TypeError} If any `customPatterns` entry uses a non-global RegExp —\n *   `String.prototype.replaceAll` rejects non-global patterns.\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 * Never throws: any serialization failure — a circular reference, a `BigInt`\n * value, a throwing `toJSON` — is caught and returned as the sentinel string\n * `\"[Unable to stringify object]\"`. Key matching is case-insensitive and\n * compares the full key name (not substrings), so `apiKey` matches only the\n * literal `\"apiKey\"`, not `\"apiKeyId\"`.\n *\n * @param obj - The object to stringify.\n * @param sensitiveKeys - Key names to redact, compared case-insensitively.\n * @param indent - JSON indentation (default: 2).\n * @returns A JSON string with sensitive values redacted, or the sentinel\n *   `\"[Unable to stringify object]\"` when serialization fails.\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//#endregion\n\n//#region Validation Helpers\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//#endregion\n"],"mappings":"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"}

package/lib/threats/capec.generated.d.mts

@@ -0,0 +1,59 @@
+//#region src/threats/capec.generated.d.ts
+/**
+ * Copyright 2026 ResQ Systems, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @fileoverview GENERATED FILE — do not edit by hand.
+ *
+ * MITRE CAPEC attack patterns whose Related Weaknesses intersect a CWE this catalog
+ * uses. Derived from CAPEC view 1000 (Mechanisms of Attack), filtered to Standard and
+ * Detailed abstractions because Meta patterns are too abstract to help anyone triaging
+ * a finding.
+ *
+ * **Attribution, not conformance.** A CAPEC id tells a reader which family of attack a
+ * finding belongs to and where to read more. It does not assert that the rule detects
+ * every technique in that pattern, and nothing here changes a score or a verdict.
+ *
+ * Regenerate with `bun scripts/generate-capec.ts <capec-1000.csv>`.
+ *
+ * @module @resq-systems/security/threats/capec
+ */
+/** One CAPEC attack pattern, reduced to what a consumer triaging a finding needs. */
+interface AttackPattern {
+  /** CAPEC identifier. */
+  readonly capec: number;
+  /** Pattern name, as published by MITRE. */
+  readonly name: string;
+  /** MITRE abstraction level: "Standard" or "Detailed". */
+  readonly abstraction: string;
+  /** MITRE's typical severity for the pattern. */
+  readonly severity: string;
+  /** Catalog CWEs this pattern relates to. */
+  readonly cwes: readonly number[];
+}
+/** Every relevant pattern, ordered by CAPEC id. */
+declare const ATTACK_PATTERNS: readonly AttackPattern[];
+/**
+ * Attack patterns related to a weakness.
+ *
+ * @param cwe - CWE identifier, typically a rule's `cwe` field.
+ * @returns Related patterns, or an empty array when none is mapped. Empty means MITRE
+ *   publishes no Standard or Detailed pattern for that weakness — not that the weakness
+ *   is unimportant.
+ */
+declare function attackPatternsForCwe(cwe: number | undefined): readonly AttackPattern[];
+//#endregion
+export { ATTACK_PATTERNS, AttackPattern, attackPatternsForCwe };
+//# sourceMappingURL=capec.generated.d.mts.map

package/lib/threats/capec.generated.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capec.generated.d.mts","names":[],"sources":["../../src/threats/capec.generated.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAkCiB;;WAEP;;WAEA;;WAEA;;WAEA;;WAEA;;;cAIG,0BAA0B;;;;;;;;;iBAknBvB,qBAAqB,mCAAmC"}