@resq-systems/security 1.0.4 → 2.0.0

package/lib/paths.mjs

@@ -0,0 +1,140 @@
+import path from "node:path";
+//#region src/paths.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 Path containment — the *prevention* half of CWE-22, as distinct from
+* the detection rules in `@resq-systems/security/threats`.
+*
+* Detecting `../` is not the control. CWE-22 describes the failure to keep a
+* constructed path inside its restricted directory, so the control is to resolve the
+* candidate against the base and verify the result still lives beneath it. That check
+* holds for inputs no signature catches: an absolute path, a Windows drive-relative
+* path, an alternate separator, or a name whose `..` only appears after normalization.
+*
+* **Node-only.** This module statically imports `node:path` and is therefore published
+* exclusively under the `@resq-systems/security/paths` subpath, never through the
+* package root, so browser bundles of the root barrel stay free of Node builtins.
+*
+* @module @resq-systems/security/paths
+*/
+/** NUL truncates paths in some syscall layers, so it is rejected before resolution. */
+const NUL = "\0";
+/**
+* Resolve an untrusted path against a base directory and verify containment.
+*
+* The candidate is resolved against the base — which also normalizes `.`, `..`, and
+* duplicate separators — and accepted only if the result is the base or sits beneath
+* it. An absolute `untrustedPath` overrides the base under `path.resolve` semantics,
+* so it too is caught by the containment check rather than silently trusted.
+*
+* **This function performs no filesystem I/O**, so it cannot see symlinks. A path that
+* is textually contained may still resolve on disk to a target outside the base. When
+* the target may exist and may be a link, follow up with `fs.promises.realpath` on
+* both the base and the result and re-run {@link isPathContained} on those.
+*
+* @param baseDirectory - Directory the result must stay within. Resolved against the
+*   process working directory when relative.
+* @param untrustedPath - Candidate path from an untrusted source.
+* @param options - See {@link ContainmentOptions}.
+* @returns The resolved absolute path when contained, otherwise `null`. Also `null`
+*   for non-string arguments, an empty base, or a NUL byte in either argument.
+*
+* @example
+* ```ts
+* const base = "/srv/uploads";
+*
+* resolveContainedPath(base, "avatar.png");        // "/srv/uploads/avatar.png"
+* resolveContainedPath(base, "nested/a.txt");      // "/srv/uploads/nested/a.txt"
+* resolveContainedPath(base, "../../etc/passwd");  // null
+* resolveContainedPath(base, "/etc/passwd");       // null
+* ```
+*/
+function resolveContainedPath(baseDirectory, untrustedPath, options = {}) {
+	if (typeof baseDirectory !== "string" || typeof untrustedPath !== "string") return null;
+	if (baseDirectory.length === 0) return null;
+	if (untrustedPath.includes(NUL) || baseDirectory.includes(NUL)) return null;
+	const { allowBaseItself = true } = options;
+	const base = path.resolve(baseDirectory);
+	const candidate = path.resolve(base, untrustedPath);
+	const relative = path.relative(base, candidate);
+	if (relative === "") return allowBaseItself ? candidate : null;
+	if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+	return candidate;
+}
+/**
+* Boolean form of {@link resolveContainedPath}.
+*
+* @param baseDirectory - Directory the candidate must stay within.
+* @param candidatePath - Path to test.
+* @param options - See {@link ContainmentOptions}.
+* @returns `true` when the candidate resolves inside the base.
+*/
+function isPathContained(baseDirectory, candidatePath, options) {
+	return resolveContainedPath(baseDirectory, candidatePath, options) !== null;
+}
+/**
+* Characters invalid in a Windows path segment, plus both separators and the C0
+* control range.
+*/
+const UNSAFE_FILENAME_CHARS = /[<>:"/\\|?*\u0000-\u001f\u007f]/g;
+/**
+* Windows device names, reserved regardless of extension — opening `CON.txt` still
+* targets the console device.
+*/
+const RESERVED_WINDOWS_NAMES = /^(?:CON|PRN|AUX|NUL|COM\d|LPT\d)(?:\.|$)/i;
+/** Longest filename accepted on common filesystems. */
+const MAX_FILENAME_LENGTH = 255;
+/** Longest extension preserved when truncating an over-long filename. */
+const MAX_PRESERVED_EXTENSION = 16;
+/**
+* Reduce an untrusted string to a single safe path segment.
+*
+* Strips directory separators, control characters, and Windows-reserved characters;
+* removes leading dots so the result cannot become `.`/`..` or a hidden file; trims
+* the trailing dots and spaces Windows silently drops (which is how `evil.php.`
+* becomes `evil.php` after the fact); and refuses reserved device names.
+*
+* The output is a *segment*, never a path. Join it onto a base directory yourself and
+* confirm the result with {@link resolveContainedPath} — that remains the containment
+* control; this is only hygiene.
+*
+* @param filename - Untrusted filename, typically from a multipart upload.
+* @param fallback - Returned when nothing usable survives. Defaults to `"file"`.
+* @returns A safe single path segment.
+*
+* @example
+* ```ts
+* sanitizeFilename("../../etc/passwd"); // "etcpasswd"
+* sanitizeFilename("report.pdf.");      // "report.pdf"
+* sanitizeFilename("CON.txt");          // "file"
+* ```
+*/
+function sanitizeFilename(filename, fallback = "file") {
+	if (typeof filename !== "string" || filename.length === 0) return fallback;
+	let safe = filename.normalize("NFC").replace(UNSAFE_FILENAME_CHARS, "").replace(/^\.+/, "").replace(/[. ]+$/, "").trim();
+	if (safe.length === 0) return fallback;
+	if (RESERVED_WINDOWS_NAMES.test(safe)) return fallback;
+	if (safe.length > MAX_FILENAME_LENGTH) {
+		const extension = path.extname(safe).slice(0, MAX_PRESERVED_EXTENSION);
+		safe = safe.slice(0, MAX_FILENAME_LENGTH - extension.length) + extension;
+	}
+	return safe;
+}
+//#endregion
+export { isPathContained, resolveContainedPath, sanitizeFilename };
+
+//# sourceMappingURL=paths.mjs.map

package/lib/paths.mjs.map

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

package/lib/sanitize.d.mts

@@ -1,20 +1,21 @@
 import { Brand } from "@resq-systems/types";
 import { Exit, Option, Schema } from "effect";
 import { Config } from "dompurify";
-
 //#region src/sanitize.d.ts
 /**
- * A Schema with DecodingServices constrained to `never`, allowing synchronous decoding.
+ * A Schema whose decoding services are constrained to `never`, allowing synchronous
+ * decoding without an Effect runtime.
  */
 type SyncSchema<T> = Schema.Codec<T, unknown, never>;
 /**
- * Schema for URL protocol validation
+ * Schema constraining a URL protocol to the recognized safe set.
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
 declare const UrlProtocolSchema: Schema.Literals<readonly ["http:", "https:", "mailto:", "tel:", "ftp:"]>;
+/** One of the protocols accepted by {@link UrlProtocolSchema}. */
 type UrlProtocol = typeof UrlProtocolSchema.Type;
 /**
- * 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)
  */
 declare const PIIRedactionOptionsSchema: Schema.Struct<{
@@ -25,9 +26,10 @@ declare const PIIRedactionOptionsSchema: Schema.Struct<{
   readonly redactIPs: Schema.optional<Schema.Boolean>;
   readonly redactDates: Schema.optional<Schema.Boolean>;
 }>;
+/** Decoded options accepted by {@link redactPIIEffect} / {@link redactPII}. */
 type PIIRedactionOptions = typeof PIIRedactionOptionsSchema.Type;
 /**
- * Schema for user input validation options
+ * Schema for the options controlling {@link validateUserInputEffect}.
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
 declare const UserInputOptionsSchema: Schema.Struct<{
@@ -36,19 +38,34 @@ declare const UserInputOptionsSchema: Schema.Struct<{
   readonly allowNewlines: Schema.optional<Schema.Boolean>;
   readonly trimWhitespace: Schema.optional<Schema.Boolean>;
 }>;
+/** Decoded options accepted by {@link validateUserInputEffect}. */
 type UserInputOptions = typeof UserInputOptionsSchema.Type;
+declare const SafeUrlSchema: Schema.String;
 /**
- * Schema for safe URL - validates URL format and protocol
- * @compliance NIST 800-53 SI-10 (Information Input Validation)
+ * A URL string vouched safe against scheme-based injection. Mint one by
+ * narrowing through the {@link isValidUrl} type guard (backed by
+ * {@link SafeUrlSchema}); the brand guarantees the value is either a
+ * root-relative path or an absolute URL restricted to `http:`/`https:`/
+ * `mailto:`. An authority-opening reference (`//host`, `///host`, `/\host`) is
+ * rejected, since resolving one against a base yields a different host.
+ *
+ * It does **not** guarantee the host is reachable or trusted — for that, validate the
+ * resolved origin with `isAllowedOrigin` from `@resq-systems/security/controls`.
  */
-declare const SafeUrlSchema: Schema.String;
-/** A string that has passed {@link isValidUrl} — a validated, injection-safe URL. */
 type SafeUrl = Brand<string, "SafeUrl">;
 /**
- * Schema for sanitized HTML-safe string (validates as string; escaping done at runtime)
+ * Schema for a sanitized HTML-safe string — validates the value is a string; the
+ * actual escaping is applied at runtime by the sanitization helpers.
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
 declare const SanitizedStringSchema: Schema.String;
+/**
+ * A string carrying the {@link SanitizedStringSchema} contract. The schema is
+ * `S.String` alone, so decoding asserts only that the value is a string —
+ * the actual escaping is applied separately by the sanitization helpers
+ * (e.g. {@link escapeHtml}). The type name signals intent, not a proof of
+ * escaping.
+ */
 type SanitizedString = typeof SanitizedStringSchema.Type;
 /**
  * Schema for email address validation.
@@ -59,34 +76,60 @@ type SanitizedString = typeof SanitizedStringSchema.Type;
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
 declare const EmailSchema: Schema.String;
-/** A string that has passed {@link isValidEmail}. */
+/**
+ * An email address that matches {@link EmailSchema}. Mint one by narrowing
+ * through the {@link isValidEmail} type guard. The brand guarantees only
+ * syntactic well-formedness (including IDN/Punycode TLDs) — not that the
+ * mailbox exists or is deliverable.
+ */
 type Email = Brand<string, "Email">;
 /**
- * Schema for phone number validation (US format)
+ * Schema for phone number validation (US format).
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
 declare const PhoneNumberSchema: Schema.String;
-/** A string that has passed {@link isValidPhone} (US format). */
+/**
+ * A US-format phone number matching {@link PhoneNumberSchema}. Mint one by
+ * narrowing through the {@link isValidPhone} type guard. The brand asserts
+ * the digit/separator shape only; it neither normalizes formatting nor
+ * confirms the number is assigned.
+ */
 type PhoneNumber = Brand<string, "PhoneNumber">;
 /**
- * Schema for SSN validation (US format)
+ * Schema for SSN validation (US format).
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
 declare const SSNSchema: Schema.String;
-/** A string that has passed {@link isValidSSN} (US format). */
+/**
+ * A US Social Security Number matching {@link SSNSchema}. Mint one by
+ * narrowing through the {@link isValidSSN} type guard. The brand asserts
+ * the `NNN-NN-NNNN` shape only — it does not validate area/group ranges or
+ * confirm the number was ever issued. Treat any value as sensitive PII.
+ */
 type SSN = Brand<string, "SSN">;
 /**
- * Schema for credit card number validation
+ * Schema for credit card number validation.
  * @compliance NIST 800-53 SI-10 (Information Input Validation)
  */
 declare const CreditCardSchema: Schema.String;
-/** A string matching the {@link CreditCardSchema} pattern. */
+/**
+ * A card number matching the {@link CreditCardSchema} pattern (13–16 digits
+ * with optional group separators). No exported type guard mints this brand;
+ * decode {@link CreditCardSchema} directly at the boundary. The pattern is a
+ * shape check only — it performs **no** Luhn checksum and does not identify
+ * the issuer. Treat any value as sensitive PII.
+ */
 type CreditCard = Brand<string, "CreditCard">;
 /**
- * Schema for IPv4 address validation
+ * Schema for IPv4 address validation.
  */
 declare const IPv4Schema: Schema.String;
-/** A string matching the {@link IPv4Schema} dotted-quad pattern. */
+/**
+ * A dotted-quad string matching {@link IPv4Schema}. No exported type guard
+ * mints this brand; decode {@link IPv4Schema} directly. The pattern checks
+ * four dot-separated groups of 1–3 digits only — it does **not** bound each
+ * octet to `0–255`, so `999.0.0.1` still matches.
+ */
 type IPv4 = Brand<string, "IPv4">;
 /**
  * Escapes special HTML characters in a string to their corresponding HTML entities,
@@ -107,9 +150,16 @@ declare const escapeHtml: (text: string) => string;
  * Validates and sanitizes a user-supplied URL using Effect Schema.
  * Returns an Exit with the sanitized URL or an error.
  *
+ * 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
@@ -146,17 +196,32 @@ declare const sanitizeUrl: (url: string, allowedProtocols?: readonly UrlProtocol
  * 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.
  */
 declare const sanitizeHtml: (html: string, options?: Config) => string;
 /**
  * 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)
  */
 declare const validateUserInputEffect: (input: string, options?: UserInputOptions) => Exit.Exit<string, Schema.SchemaError>;
@@ -180,10 +245,19 @@ declare const validateUserInput: (input: string, maxLength?: number, allowHtml?:
 /**
  * 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
@@ -216,8 +290,17 @@ declare const parseJsonWithSchema: <A>(jsonString: string, schema: SyncSchema<A>
  */
 declare const sanitizeJson: (jsonString: string) => unknown;
 /**
- * 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.
@@ -231,9 +314,15 @@ declare const stripAnsi: (text: string) => string;
 /**
  * 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)
  */
 declare const redactPIIEffect: (text: string, options?: PIIRedactionOptions) => Exit.Exit<string, Schema.SchemaError>;
@@ -241,9 +330,15 @@ declare const redactPIIEffect: (text: string, options?: PIIRedactionOptions) =>
  * 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
@@ -265,10 +360,17 @@ declare const redactPII: (text: string, options?: PIIRedactionOptions & {
  * 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.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize.d.mts","names":[],"sources":["../src/sanitize.ts"],"mappings":";;;;;;;;KAiCK,UAAA,MAAgB,MAAA,CAAE,KAAA,CAAM,CAAA;;;;;cAUhB,iBAAA,EAAiB,MAAA,CAAA,QAAA;AAAA,KAClB,WAAA,UAAqB,iBAAA,CAAkB,IAAA;;;;;cAMtC,yBAAA,EAAyB,MAAA,CAAA,MAAA;EAAA;;;;;;;KAQ1B,mBAAA,UAA6B,yBAAA,CAA0B,IAAA;;;;;cAMtD,sBAAA,EAAsB,MAAA,CAAA,MAAA;EAAA;;;;;KAMvB,gBAAA,UAA0B,sBAAA,CAAuB,IAAA;;;;;cAMhD,aAAA,EAAa,MAAA,CAAA,MAAA;;KAiBd,OAAA,GAAU,KAAA;;;;;cAMT,qBAAA,EAAqB,MAAA,CAAA,MAAA;AAAA,KACtB,eAAA,UAAyB,qBAAA,CAAsB,IAAA;;;;;AA1C3D;;;;cAoDa,WAAA,EAAW,MAAA,CAAA,MAAA;AA9CxB;AAAA,KAkDY,KAAA,GAAQ,KAAA;;;;;cAMP,iBAAA,EAAiB,MAAA,CAAA,MAAA;;KAIlB,WAAA,GAAc,KAAA;;;;;cAMb,SAAA,EAAS,MAAA,CAAA,MAAA;;KAEV,GAAA,GAAM,KAAA;;;;;cAML,gBAAA,EAAgB,MAAA,CAAA,MAAA;;KAIjB,UAAA,GAAa,KAAA;;;;cAKZ,UAAA,EAAU,MAAA,CAAA,MAAA;;KAEX,IAAA,GAAO,KAAA;;;;;;;;;;AA/EnB;;;;;cAmGa,UAAA,GAAc,IAAA;;;;;AA5E3B;;;;;AAMA;;;;;AACA;;;;cAoGa,iBAAA,GACZ,GAAA,UACA,gBAAA,YAA2B,WAAA,OACzB,IAAA,CAAK,IAAA,SAAa,MAAA,CAAE,WAAA;AA7FvB;;;;;AAIA;;;;;AAMA;;;;;AAVA,cAyIa,WAAA,GACZ,GAAA,UACA,gBAAA,YAA2B,WAAA;;;;;AAvH5B;;;;;AAEA;;;cA+Ka,YAAA,GAAgB,IAAA,UAAc,OAAA,GAAU,MAAA;;AAzKrD;;;;;AAIA;;cA0La,uBAAA,GACZ,KAAA,UACA,OAAA,GAAS,gBAAA,KACP,IAAA,CAAK,IAAA,SAAa,MAAA,CAAE,WAAA;;;AAxLvB;;;;;AAEA;;;;;AAoBA;;;;cAiOa,iBAAA,GAAqB,KAAA,UAAe,SAAA,WAAiB,SAAA;AAlMlE;;;;;;;;;;;;;;;;AAAA,cAuPa,mBAAA,MACZ,UAAA,UACA,MAAA,EAAQ,UAAA,CAAW,CAAA,MACjB,MAAA,CAAO,MAAA,CAAO,CAAA;AA3MjB;;;;;;;;;AA4DA;;;;;;;;;AAqBA;;AAjFA,cAqPa,YAAA,GAAgB,UAAA;;;;;;;;;;;;;cAiChB,SAAA,GAAa,IAAA;;AAnI1B;;;;;;;cAkLa,eAAA,GACZ,IAAA,UACA,OAAA,GAAS,mBAAA,KACP,IAAA,CAAK,IAAA,SAAa,MAAA,CAAE,WAAA;;AAhIvB;;;;;;;;;;;;;;;;;cAiMa,SAAA,GACZ,IAAA,UACA,OAAA,GAAS,mBAAA;EACR,cAAA,GAAiB,KAAA;IAAQ,OAAA,EAAS,MAAA;IAAQ,WAAA;EAAA;AAAA;;AAtH5C;;;;;AA+CA;;;;;;;;;;cA0Ha,aAAA,GACZ,GAAA,WACA,aAAA,aAUA,MAAA;;;;;;;AAlED;;;cAiGa,YAAA,GAAgB,KAAA,aAAgB,KAAA,IAAS,KAAA;;;;;;;;;cAYzC,YAAA,GAAgB,KAAA,aAAgB,KAAA,IAAS,WAAA;;;;;;AAvDtD;;;cAmEa,UAAA,GAAc,GAAA,aAAc,GAAA,IAAO,GAAA;;;;;;AAxBhD;;;cAoCa,UAAA,GAAc,GAAA,aAAc,GAAA,IAAO,OAAA"}
+{"version":3,"file":"sanitize.d.mts","names":[],"sources":["../src/sanitize.ts"],"mappings":";;;;;;;;KAoCK,WAAW,KAAK,OAAE,MAAM;;;;;cAShB,mBAAiB,OAAA;;KAElB,qBAAqB,kBAAkB;;;;;cAMtC,2BAAyB,OAAA;;;;;;;;;KAS1B,6BAA6B,0BAA0B;;;;;cAMtD,wBAAsB,OAAA;;;;;;;KAOvB,0BAA0B,uBAAuB;cAuBhD,eAAa,OAAA;;;;;;;;;;;;KA4Bd,UAAU;;;;;;cAOT,uBAAqB,OAAA;;;;;;;;KAQtB,yBAAyB,sBAAsB;;;;;;;;;cAU9C,aAAW,OAAA;;;;;;;KASZ,QAAQ;;;;;cAMP,mBAAiB,OAAA;;;;;;;KASlB,cAAc;;;;;cAMb,WAAS,OAAA;;;;;;;KAOV,MAAM;;;;;cAML,kBAAgB,OAAA;;;;;;;;KAUjB,aAAa;;;;cAKZ,YAAU,OAAA;;;;;;;KAOX,OAAO;;;;;;;;;;;;;;;cAmBN,aAAc;;;;;;;;;;;;;;;;;;;;;;;;;;cAsCd,oBACZ,aACA,4BAA2B,kBACzB,KAAK,aAAa,OAAE;;;;;;;;;;;;;;;;cA+CV,cACZ,aACA,4BAA2B;;;;;;;;;;;;;;;;;;;;cAyGf,eAAgB,cAAc,UAAU;;;;;;;;;;;;;;;;;cA6BxC,0BACZ,eACA,UAAS,qBACP,KAAK,aAAa,OAAE;;;;;;;;;;;;;;;;;cA+DV,oBAAqB,eAAe,oBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;cAmFrD,sBAAuB,GACnC,oBACA,QAAQ,WAAW,OACjB,OAAO,OAAO;;;;;;;;;;;;;;;;;;;;;cA0CJ,eAAgB;;;;;;;;;;;;;;;;;;;;;;cA0ChB,YAAa;;;;;;;;;;;;;;;cAoEb,kBACZ,cACA,UAAS,wBACP,KAAK,aAAa,OAAE;;;;;;;;;;;;;;;;;;;;;;;;;cAuEV,YACZ,cACA,UAAS;EACR,iBAAiB;IAAQ,SAAS;IAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;cA0D/B,gBACZ,cACA,0BAUA;;;;;;;;;;cA+BY,eAAgB,kBAAgB,SAAS;;;;;;;;;cAYzC,eAAgB,kBAAgB,SAAS;;;;;;;;;cAYzC,aAAc,gBAAc,OAAO;;;;;;;;;cAYnC,aAAc,gBAAc,OAAO"}