@resq-systems/security 2.1.0 → 2.1.1

package/lib/hash.d.mts

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

package/lib/hash.d.mts.map

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

package/lib/hash.mjs

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

package/lib/hash.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"hash.mjs","names":[],"sources":["../src/hash.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview Fast, deterministic, non-cryptographic hashing helpers — a 32-bit\n * string/buffer hash for cache keys and change detection, plus a lightweight string\n * obfuscation transform. Not suitable for security-sensitive digests; use the\n * SHA-256 helper in {@link @resq-systems/security/crypto} for those.\n *\n * @module @resq-systems/security/hash\n */\n\n/**\n * Compute a deterministic non-cryptographic 32-bit hash of a string.\n *\n * Uses the classic `hash * 31 + charCode` accumulation (expressed as\n * `(hash << 5) - hash`), yielding the same value for the same input across runs.\n * Intended for cache keys and change detection, not for security.\n *\n * @param string - The input to hash.\n * @returns The signed 32-bit hash rendered as a decimal string.\n *\n * @example\n * ```ts\n * getHashForString(\"hello\") === getHashForString(\"hello\"); // → true\n * ```\n */\nexport function getHashForString(string: string): string {\n\tlet hash = 0;\n\tfor (let i = 0; i < string.length; i++) {\n\t\thash = (hash << 5) - hash + string.charCodeAt(i);\n\t\thash |= 0; // Coerce the accumulator back to a signed 32-bit integer.\n\t}\n\treturn `${hash}`;\n}\n\n/**\n * Hash an arbitrary value by serializing it to JSON and hashing the result.\n *\n * Key ordering follows `JSON.stringify`, so two structurally equal objects with\n * differently ordered keys can hash differently.\n *\n * @param obj - Any JSON-serializable value.\n * @returns The 32-bit hash of the serialized form, as a decimal string.\n * @throws {TypeError} When `obj` cannot be serialized: a circular\n *   reference or a `BigInt` makes `JSON.stringify` throw, and a value\n *   that stringifies to `undefined` (a bare function, `symbol`, or\n *   `undefined`) makes the downstream `.length` access throw.\n */\nexport function getHashForObject(obj: unknown): string {\n\treturn getHashForString(JSON.stringify(obj));\n}\n\n/**\n * Compute a deterministic non-cryptographic 32-bit hash of an `ArrayBuffer`.\n *\n * Applies the same accumulation as {@link getHashForString} over each byte.\n *\n * @param buffer - The bytes to hash.\n * @returns The signed 32-bit hash rendered as a decimal string.\n */\nexport function getHashForBuffer(buffer: ArrayBuffer): string {\n\tconst view = new DataView(buffer);\n\tlet hash = 0;\n\tfor (let i = 0; i < view.byteLength; i++) {\n\t\thash = (hash << 5) - hash + view.getUint8(i);\n\t\thash |= 0; // Coerce the accumulator back to a signed 32-bit integer.\n\t}\n\treturn `${hash}`;\n}\n\n/**\n * Reversibly scramble a string by rotating character blocks and shifting digits.\n *\n * A lightweight, non-cryptographic obfuscation: it reorders characters via a fixed\n * sequence of block rotations, reverses the result, and maps each digit `d` to\n * `d < 5 ? d + 5 : d > 5 ? d - 5 : d`. Provides obscurity, not security — do not\n * use it to protect secrets.\n *\n * Despite \"scramble\", the transform is **not a true inverse**: the digit map sends\n * both `0` and `5` to `5`, so any input containing those digits cannot be\n * recovered unambiguously. Non-digit characters (including whitespace) are only\n * reordered, never substituted. Deterministic and free of side effects.\n *\n * @param str - The string to transform.\n * @returns The transformed string, same length as `str`.\n */\nexport function lns(str: string): string {\n\tconst result = str.split(\"\");\n\tresult.push(...result.splice(0, Math.round(result.length / 5)));\n\tresult.push(...result.splice(0, Math.round(result.length / 4)));\n\tresult.push(...result.splice(0, Math.round(result.length / 3)));\n\tresult.push(...result.splice(0, Math.round(result.length / 2)));\n\treturn result\n\t\t.reverse()\n\t\t.map((n) => {\n\t\t\tconst num = Number(n);\n\t\t\treturn Number.isNaN(num) || n.trim() === \"\"\n\t\t\t\t? n\n\t\t\t\t: num < 5\n\t\t\t\t\t? String(5 + num)\n\t\t\t\t\t: num > 5\n\t\t\t\t\t\t? String(num - 5)\n\t\t\t\t\t\t: n;\n\t\t})\n\t\t.join(\"\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,iBAAiB,QAAwB;CACxD,IAAI,OAAO;CACX,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;EACvC,QAAQ,QAAQ,KAAK,OAAO,OAAO,WAAW,CAAC;EAC/C,QAAQ;CACT;CACA,OAAO,GAAG;AACX;;;;;;;;;;;;;;AAeA,SAAgB,iBAAiB,KAAsB;CACtD,OAAO,iBAAiB,KAAK,UAAU,GAAG,CAAC;AAC5C;;;;;;;;;AAUA,SAAgB,iBAAiB,QAA6B;CAC7D,MAAM,OAAO,IAAI,SAAS,MAAM;CAChC,IAAI,OAAO;CACX,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,YAAY,KAAK;EACzC,QAAQ,QAAQ,KAAK,OAAO,KAAK,SAAS,CAAC;EAC3C,QAAQ;CACT;CACA,OAAO,GAAG;AACX;;;;;;;;;;;;;;;;;AAkBA,SAAgB,IAAI,KAAqB;CACxC,MAAM,SAAS,IAAI,MAAM,EAAE;CAC3B,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,OACL,QAAQ,CAAC,CACT,KAAK,MAAM;EACX,MAAM,MAAM,OAAO,CAAC;EACpB,OAAO,OAAO,MAAM,GAAG,KAAK,EAAE,KAAK,MAAM,KACtC,IACA,MAAM,IACL,OAAO,IAAI,GAAG,IACd,MAAM,IACL,OAAO,MAAM,CAAC,IACd;CACN,CAAC,CAAC,CACD,KAAK,EAAE;AACV"}
+{"version":3,"file":"hash.mjs","names":[],"sources":["../src/hash.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ Systems, Inc.\n * SPDX-License-Identifier: Apache-2.0\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview Fast, deterministic, non-cryptographic hashing helpers — a 32-bit\n * string/buffer hash for cache keys and change detection, plus a lightweight string\n * obfuscation transform. Not suitable for security-sensitive digests; use the\n * SHA-256 helper in {@link @resq-systems/security/crypto} for those.\n *\n * @module @resq-systems/security/hash\n */\n\n/**\n * Compute a deterministic non-cryptographic 32-bit hash of a string.\n *\n * Uses the classic `hash * 31 + charCode` accumulation (expressed as\n * `(hash << 5) - hash`), yielding the same value for the same input across runs.\n * Intended for cache keys and change detection, not for security.\n *\n * @param string - The input to hash.\n * @returns The signed 32-bit hash rendered as a decimal string.\n *\n * @example\n * ```ts\n * getHashForString(\"hello\") === getHashForString(\"hello\"); // → true\n * ```\n */\nexport function getHashForString(string: string): string {\n\tlet hash = 0;\n\tfor (let i = 0; i < string.length; i++) {\n\t\thash = (hash << 5) - hash + string.charCodeAt(i);\n\t\thash |= 0; // Coerce the accumulator back to a signed 32-bit integer.\n\t}\n\treturn `${hash}`;\n}\n\n/**\n * Hash an arbitrary value by serializing it to JSON and hashing the result.\n *\n * Key ordering follows `JSON.stringify`, so two structurally equal objects with\n * differently ordered keys can hash differently.\n *\n * @param obj - Any JSON-serializable value.\n * @returns The 32-bit hash of the serialized form, as a decimal string.\n * @throws {TypeError} When `obj` cannot be serialized: a circular\n *   reference or a `BigInt` makes `JSON.stringify` throw, and a value\n *   that stringifies to `undefined` (a bare function, `symbol`, or\n *   `undefined`) makes the downstream `.length` access throw.\n */\nexport function getHashForObject(obj: unknown): string {\n\treturn getHashForString(JSON.stringify(obj));\n}\n\n/**\n * Compute a deterministic non-cryptographic 32-bit hash of an `ArrayBuffer`.\n *\n * Applies the same accumulation as {@link getHashForString} over each byte.\n *\n * @param buffer - The bytes to hash.\n * @returns The signed 32-bit hash rendered as a decimal string.\n */\nexport function getHashForBuffer(buffer: ArrayBuffer): string {\n\tconst view = new DataView(buffer);\n\tlet hash = 0;\n\tfor (let i = 0; i < view.byteLength; i++) {\n\t\thash = (hash << 5) - hash + view.getUint8(i);\n\t\thash |= 0; // Coerce the accumulator back to a signed 32-bit integer.\n\t}\n\treturn `${hash}`;\n}\n\n/**\n * Reversibly scramble a string by rotating character blocks and shifting digits.\n *\n * A lightweight, non-cryptographic obfuscation: it reorders characters via a fixed\n * sequence of block rotations, reverses the result, and maps each digit `d` to\n * `d < 5 ? d + 5 : d > 5 ? d - 5 : d`. Provides obscurity, not security — do not\n * use it to protect secrets.\n *\n * Despite \"scramble\", the transform is **not a true inverse**: the digit map sends\n * both `0` and `5` to `5`, so any input containing those digits cannot be\n * recovered unambiguously. Non-digit characters (including whitespace) are only\n * reordered, never substituted. Deterministic and free of side effects.\n *\n * @param str - The string to transform.\n * @returns The transformed string, same length as `str`.\n */\nexport function lns(str: string): string {\n\tconst result = str.split(\"\");\n\tresult.push(...result.splice(0, Math.round(result.length / 5)));\n\tresult.push(...result.splice(0, Math.round(result.length / 4)));\n\tresult.push(...result.splice(0, Math.round(result.length / 3)));\n\tresult.push(...result.splice(0, Math.round(result.length / 2)));\n\treturn result\n\t\t.reverse()\n\t\t.map((n) => {\n\t\t\tconst num = Number(n);\n\t\t\treturn Number.isNaN(num) || n.trim() === \"\"\n\t\t\t\t? n\n\t\t\t\t: num < 5\n\t\t\t\t\t? String(5 + num)\n\t\t\t\t\t: num > 5\n\t\t\t\t\t\t? String(num - 5)\n\t\t\t\t\t\t: n;\n\t\t})\n\t\t.join(\"\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,iBAAiB,QAAwB;CACxD,IAAI,OAAO;CACX,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;EACvC,QAAQ,QAAQ,KAAK,OAAO,OAAO,WAAW,CAAC;EAC/C,QAAQ;CACT;CACA,OAAO,GAAG;AACX;;;;;;;;;;;;;;AAeA,SAAgB,iBAAiB,KAAsB;CACtD,OAAO,iBAAiB,KAAK,UAAU,GAAG,CAAC;AAC5C;;;;;;;;;AAUA,SAAgB,iBAAiB,QAA6B;CAC7D,MAAM,OAAO,IAAI,SAAS,MAAM;CAChC,IAAI,OAAO;CACX,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,YAAY,KAAK;EACzC,QAAQ,QAAQ,KAAK,OAAO,KAAK,SAAS,CAAC;EAC3C,QAAQ;CACT;CACA,OAAO,GAAG;AACX;;;;;;;;;;;;;;;;;AAkBA,SAAgB,IAAI,KAAqB;CACxC,MAAM,SAAS,IAAI,MAAM,EAAE;CAC3B,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,KAAK,GAAG,OAAO,OAAO,GAAG,KAAK,MAAM,OAAO,SAAS,CAAC,CAAC,CAAC;CAC9D,OAAO,OACL,QAAQ,CAAC,CACT,KAAK,MAAM;EACX,MAAM,MAAM,OAAO,CAAC;EACpB,OAAO,OAAO,MAAM,GAAG,KAAK,EAAE,KAAK,MAAM,KACtC,IACA,MAAM,IACL,OAAO,IAAI,GAAG,IACd,MAAM,IACL,OAAO,MAAM,CAAC,IACd;CACN,CAAC,CAAC,CACD,KAAK,EAAE;AACV"}

package/lib/paths.d.mts

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

package/lib/paths.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.mts","names":[],"sources":["../src/paths.ts"],"mappings":";;;;;;;;;;;;;;;;;UAsCiB;;;;;;WAMP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCM,qBACf,uBACA,uBACA,UAAS;;;;;;;;;iBAuCM,gBACf,uBACA,uBACA,UAAU;;;;;;;;;;;;;;;;;;;;;;;;iBAmDK,iBAAiB,kBAAkB"}
+{"version":3,"file":"paths.d.mts","names":[],"sources":["../src/paths.ts"],"mappings":";;;;;;;;;;;;;;;;;;iBAuCiB;;;;;;WAMP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoCM,qBACf,uBACA,uBACA,UAAS;;;;;;;;;wBAuCM,gBACf,uBACA,uBACA,UAAU;;;;;;;;;;;;;;;;;;;;;;;;wBAmDK,iBAAiB,kBAAkB"}

package/lib/paths.mjs

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

package/lib/paths.mjs.map

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

package/lib/sanitize.d.mts

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

package/lib/sanitize.d.mts.map

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