@design-edito/tools 0.4.5 → 0.4.11

package/agnostic/sanitization/html/index.js

@@ -1,127 +1,177 @@
-// src/agnostic/misc/crossenv/window/index.ts
-function exists() {
-  return typeof globalThis !== "undefined" && "window" in globalThis;
+import * as Window from '../../misc/crossenv/window/index.js';
+/**
+ * Default sanitization options.
+ *
+ * Only sets a default recursion depth of 20.
+ */
+export const defaultOptions = { depth: 20 };
+/**
+ * Sanitizes an HTML string according to the provided options.
+ *
+ * @deprecated
+ * @security
+ * ⚠️ SECURITY WARNING
+ * This function is **not a hardened or complete HTML sanitizer**.
+ * It does not guarantee protection against XSS or other injection attacks.
+ *
+ * Correctness and safety depend entirely on strict caller configuration.
+ * In particular, unsafe usage may occur if:
+ * - Wildcards (`'*'`) are used for allowed tags or attributes
+ * - URL-based attributes (`href`, `src`, `xlink:href`, etc.) are insufficiently constrained
+ * - Event handler attributes (`on*`) are not explicitly forbidden
+ * - SVG or MathML content is allowed
+ *
+ * This API must not be used as a security boundary for untrusted HTML.
+ * For security-critical sanitization, use a dedicated, security-audited library.
+ *
+ * @param {string} inputStr - The HTML string to sanitize.
+ * @param {SanitizeHtmlOptions} [options=defaultOptions] - Sanitization configuration.
+ * @returns {string} The sanitized HTML string.
+ *
+ * @throws Will throw an error if no document object is available for creating elements.
+ */
+export function sanitizeHtml(inputStr, options = defaultOptions) {
+    const { document } = Window.get();
+    const wrapperDiv = document.createElement('div');
+    const { inputFreeTransform } = options;
+    wrapperDiv.innerHTML = inputFreeTransform !== undefined ? inputFreeTransform(inputStr) : inputStr;
+    const sanitizedWrapper = sanitizeElement(wrapperDiv, options);
+    const returned = sanitizedWrapper?.innerHTML;
+    return returned ?? '';
 }
-var _window = exists() ? globalThis.window ?? null : null;
-function get() {
-  if (_window !== null) return _window;
-  const message = "window is undefined. Please call Window.setWindow(windowObj) before using Window.get.";
-  throw new Error(message);
-}
-
-// src/agnostic/sanitization/html/index.ts
-var defaultOptions = { depth: 20 };
-function sanitizeHtml(inputStr, options = defaultOptions) {
-  const { document } = get();
-  const wrapperDiv = document.createElement("div");
-  const { inputFreeTransform } = options;
-  wrapperDiv.innerHTML = inputFreeTransform !== void 0 ? inputFreeTransform(inputStr) : inputStr;
-  const sanitizedWrapper = sanitizeElement(wrapperDiv, options);
-  const returned = sanitizedWrapper?.innerHTML;
-  return returned ?? "";
-}
-function sanitizeElement(element, options = defaultOptions) {
-  const { tagName, attributes, childNodes } = element;
-  const {
-    allowedTags = [],
-    allowedAttributes = {},
-    forbiddenTags = [],
-    forbiddenAttributes = {},
-    depth = 20,
-    verbose = false
-  } = options;
-  if (depth <= 0) {
-    console.warn("Max depth reached");
-    return null;
-  }
-  const normalizedTagName = tagName.toLowerCase().trim();
-  const tagIsInForbidden = forbiddenTags.includes("*") || forbiddenTags.includes(normalizedTagName);
-  if (tagIsInForbidden) {
-    if (verbose) console.warn(tagName, "tag is forbidden");
-    return null;
-  }
-  const tagIsInAllowed = allowedTags.includes("*") || allowedTags.includes(normalizedTagName);
-  if (!tagIsInAllowed) {
-    if (verbose) console.warn(tagName, "tag is not allowed");
-    return null;
-  }
-  const returnedElement = get().document.createElement(tagName);
-  const returnedAttributes = Array.from(attributes).filter(({ name: attributeName, value: attributeValue }) => {
-    const allTagsForbiddenAttributes = forbiddenAttributes["*"] ?? [];
-    const thisTagForbiddenAttributes = forbiddenAttributes[normalizedTagName] ?? [];
-    const mergedForbiddenAttributes = [...allTagsForbiddenAttributes, ...thisTagForbiddenAttributes];
-    const isInForbidden = mergedForbiddenAttributes.some(({
-      attributeName: nameTester,
-      attributeValues: valTesters
-    }) => {
-      if (typeof nameTester === "string" && nameTester !== "*" && attributeName !== nameTester) return false;
-      if (typeof nameTester !== "string" && !nameTester.test(attributeName)) return false;
-      if (valTesters === void 0) {
-        if (verbose) console.warn(attributeName, "attribute on", tagName, "tag is forbidden");
-        return true;
-      }
-      if (valTesters.includes("*")) {
-        if (verbose) console.warn(attributeName, "attribute on", tagName, "tag is forbidden");
-        return true;
-      }
-      return valTesters.some((valTester) => {
-        if (typeof valTester === "string" && attributeValue === valTester) {
-          if (verbose) console.warn(attributeValue, "value for", attributeName, "attribute on", tagName, "tag is forbidden. Rule:", valTester);
-          return true;
-        }
-        if (typeof valTester !== "string" && valTester.test(attributeValue)) {
-          if (verbose) console.warn(attributeValue, "value for", attributeName, "attribute on", tagName, "tag is forbidden. Rule:", valTester);
-          return true;
+/**
+ * Recursively sanitizes a DOM element and its descendants according to the provided options.
+ *
+ * @deprecated
+ * @security
+ * ⚠️ SECURITY WARNING
+ * This function is **not a hardened or complete HTML sanitizer**.
+ * It does not guarantee protection against XSS or other injection attacks.
+ *
+ * Correctness and safety depend entirely on strict caller configuration.
+ * In particular, unsafe usage may occur if:
+ * - Wildcards (`'*'`) are used for allowed tags or attributes
+ * - URL-based attributes (`href`, `src`, `xlink:href`, etc.) are insufficiently constrained
+ * - Event handler attributes (`on*`) are not explicitly forbidden
+ * - SVG or MathML content is allowed
+ *
+ * This API must not be used as a security boundary for untrusted HTML.
+ * For security-critical sanitization, use a dedicated, security-audited library.
+ *
+ * @param {Element} element - The DOM element to sanitize.
+ * @param {SanitizeHtmlOptions} [options=defaultOptions] - Sanitization configuration.
+ * @returns {Element | null}
+ * - A sanitized clone of the original element with allowed attributes and children.
+ * - `null` if the element is forbidden or maximum recursion depth is reached.
+ *
+ * @throws Will throw an error if no document object is available for creating elements.
+ */
+export function sanitizeElement(element, options = defaultOptions) {
+    const { tagName, attributes, childNodes } = element;
+    const { allowedTags = [], allowedAttributes = {}, forbiddenTags = [], forbiddenAttributes = {}, depth = 20, verbose = false } = options;
+    if (depth <= 0) {
+        console.warn('Max depth reached');
+        return null;
+    }
+    // Element's tag name checkup
+    const normalizedTagName = tagName.toLowerCase().trim();
+    const tagIsInForbidden = forbiddenTags.includes('*') || forbiddenTags.includes(normalizedTagName);
+    if (tagIsInForbidden) {
+        if (verbose)
+            console.warn(tagName, 'tag is forbidden');
+        return null;
+    }
+    const tagIsInAllowed = allowedTags.includes('*') || allowedTags.includes(normalizedTagName);
+    if (!tagIsInAllowed) {
+        if (verbose)
+            console.warn(tagName, 'tag is not allowed');
+        return null;
+    }
+    const returnedElement = Window.get().document.createElement(tagName);
+    // Element's attributes checkup
+    const returnedAttributes = Array.from(attributes).filter(({ name: attributeName, value: attributeValue }) => {
+        const allTagsForbiddenAttributes = forbiddenAttributes['*'] ?? [];
+        const thisTagForbiddenAttributes = forbiddenAttributes[normalizedTagName] ?? [];
+        const mergedForbiddenAttributes = [...allTagsForbiddenAttributes, ...thisTagForbiddenAttributes];
+        const isInForbidden = mergedForbiddenAttributes.some(({ attributeName: nameTester, attributeValues: valTesters }) => {
+            if (typeof nameTester === 'string' && nameTester !== '*' && attributeName !== nameTester)
+                return false; // attribute name doesnt match
+            if (typeof nameTester !== 'string' && !nameTester.test(attributeName))
+                return false; // attribute name doesnt match
+            if (valTesters === undefined) {
+                if (verbose)
+                    console.warn(attributeName, 'attribute on', tagName, 'tag is forbidden');
+                return true; // attribute name matches, and all values are forbidden
+            }
+            if (valTesters.includes('*')) {
+                if (verbose)
+                    console.warn(attributeName, 'attribute on', tagName, 'tag is forbidden');
+                return true; // attribute name matches, and all values are EXPLICITLY forbidden
+            }
+            return valTesters.some(valTester => {
+                if (typeof valTester === 'string' && attributeValue === valTester) {
+                    if (verbose)
+                        console.warn(attributeValue, 'value for', attributeName, 'attribute on', tagName, 'tag is forbidden. Rule:', valTester);
+                    return true; // attribute value strictly matches
+                }
+                if (typeof valTester !== 'string' && valTester.test(attributeValue)) {
+                    if (verbose)
+                        console.warn(attributeValue, 'value for', attributeName, 'attribute on', tagName, 'tag is forbidden. Rule:', valTester);
+                    return true; // attribute value partially matches
+                }
+                return false;
+            });
+        });
+        if (isInForbidden)
+            return false;
+        const allTagsAllowedAttributes = allowedAttributes['*'] ?? [];
+        const thisTagAllowedAttributes = allowedAttributes[normalizedTagName] ?? [];
+        const mergedAllowedAttributes = [...allTagsAllowedAttributes, ...thisTagAllowedAttributes];
+        let latestNotAllowedReason = [tagName, 'has no allowed attributes'];
+        const isInAllowed = mergedAllowedAttributes.some(({ attributeName: nameTester, attributeValues: valTesters }) => {
+            if (typeof nameTester === 'string' && nameTester !== '*' && attributeName !== nameTester) {
+                latestNotAllowedReason = [attributeName, 'attribute on', tagName, 'tag is not allowed'];
+                return false; // attribute name doesnt match
+            }
+            if (typeof nameTester !== 'string' && !nameTester.test(attributeName)) {
+                latestNotAllowedReason = [attributeName, 'attribute on', tagName, 'tag is not allowed'];
+                return false; // attribute name doesnt match
+            }
+            if (valTesters === undefined)
+                return true; // attribute name matches, and all values are allowed
+            if (valTesters.includes('*'))
+                return true; // attribute name matches, and all values are EXPLICITLY allowed
+            return valTesters.some(valTester => {
+                if (typeof valTester === 'string' && attributeValue === valTester)
+                    return true; // attribute value strictly matches
+                if (typeof valTester !== 'string' && valTester.test(attributeValue))
+                    return true; // attribute value partially matches
+                latestNotAllowedReason = [attributeValue, 'value for', attributeName, 'attribute on', tagName, 'tag is not allowed'];
+                return false;
+            });
+        });
+        if (!isInAllowed) {
+            if (verbose)
+                console.warn(...latestNotAllowedReason);
+            return false;
         }
-        return false;
-      });
+        return true;
     });
-    if (isInForbidden) return false;
-    const allTagsAllowedAttributes = allowedAttributes["*"] ?? [];
-    const thisTagAllowedAttributes = allowedAttributes[normalizedTagName] ?? [];
-    const mergedAllowedAttributes = [...allTagsAllowedAttributes, ...thisTagAllowedAttributes];
-    let latestNotAllowedReason = [tagName, "has no allowed attributes"];
-    const isInAllowed = mergedAllowedAttributes.some(({
-      attributeName: nameTester,
-      attributeValues: valTesters
-    }) => {
-      if (typeof nameTester === "string" && nameTester !== "*" && attributeName !== nameTester) {
-        latestNotAllowedReason = [attributeName, "attribute on", tagName, "tag is not allowed"];
-        return false;
-      }
-      if (typeof nameTester !== "string" && !nameTester.test(attributeName)) {
-        latestNotAllowedReason = [attributeName, "attribute on", tagName, "tag is not allowed"];
-        return false;
-      }
-      if (valTesters === void 0) return true;
-      if (valTesters.includes("*")) return true;
-      return valTesters.some((valTester) => {
-        if (typeof valTester === "string" && attributeValue === valTester) return true;
-        if (typeof valTester !== "string" && valTester.test(attributeValue)) return true;
-        latestNotAllowedReason = [attributeValue, "value for", attributeName, "attribute on", tagName, "tag is not allowed"];
-        return false;
-      });
+    returnedAttributes.forEach(({ name, value }) => {
+        returnedElement.setAttribute(name, value);
     });
-    if (!isInAllowed) {
-      if (verbose) console.warn(...latestNotAllowedReason);
-      return false;
-    }
-    return true;
-  });
-  returnedAttributes.forEach(({ name, value }) => {
-    returnedElement.setAttribute(name, value);
-  });
-  const sanitizedChildNodes = Array.from(childNodes).map((node) => {
-    if (node.nodeType === Node.ELEMENT_NODE) return sanitizeElement(node, { ...options, depth: depth - 1 });
-    else if (node.nodeType === Node.TEXT_NODE) return node;
-    else if (options.keepComments === true && node.nodeType === Node.COMMENT_NODE) return node;
-    return null;
-  }).filter((elt) => elt !== null);
-  returnedElement.replaceChildren(...sanitizedChildNodes);
-  return returnedElement;
+    // Element's children sanitization
+    const sanitizedChildNodes = Array.from(childNodes)
+        .map((node) => {
+        if (node.nodeType === Node.ELEMENT_NODE)
+            return sanitizeElement(node, { ...options, depth: depth - 1 });
+        else if (node.nodeType === Node.TEXT_NODE)
+            return node;
+        else if (options.keepComments === true && node.nodeType === Node.COMMENT_NODE)
+            return node;
+        return null;
+    })
+        .filter((elt) => elt !== null);
+    returnedElement.replaceChildren(...sanitizedChildNodes);
+    return returnedElement;
 }
-export {
-  defaultOptions,
-  sanitizeElement,
-  sanitizeHtml
-};

package/agnostic/sanitization/index.d.ts

@@ -1,4 +1,4 @@
 export * as fileName from './file-name/index.js'
-export * as html from './html/index.js'
 export * as path from './path/index.js'
+export * as html from './html/index.js'
 export * as userInput from './user-input/index.js'

package/agnostic/sanitization/index.js

@@ -1,4 +1,4 @@
 export * as fileName from './file-name/index.js'
-export * as html from './html/index.js'
 export * as path from './path/index.js'
+export * as html from './html/index.js'
 export * as userInput from './user-input/index.js'

package/agnostic/sanitization/path/index.js

@@ -1,16 +1,24 @@
-// src/agnostic/sanitization/file-name/index.ts
-function sanitizeFileName(input, maxLength = 255) {
-  input = input.normalize("NFKC").replace(/[<>:"/\\|?*\x00-\x1F]/g, "").trim().replace(/\s+/g, " ").replace(/\.+/g, ".").replace(/^\.+|\.+$/g, "");
-  if (input.length > maxLength) return null;
-  return input.length > 0 ? input : null;
+import { sanitizeFileName } from '../file-name/index.js';
+/**
+ * Sanitizes a path string by sanitizing each path segment.
+ *
+ * - Removes empty segments and `..` segments to prevent path traversal.
+ * - Sanitizes each segment using `sanitizeFileName`.
+ * - Ensures the returned path starts with a `/`.
+ *
+ * @param {string} targetPath - The path to sanitize.
+ * @returns {string | null} Sanitized absolute path, or null if invalid/empty.
+ */
+export function sanitizePath(targetPath) {
+    const sanitized = targetPath
+        .split('/')
+        .filter(chunk => chunk !== '')
+        .map(chunk => sanitizeFileName(chunk) ?? '')
+        .filter(chunk => chunk !== '' && chunk !== '..')
+        .join('/');
+    if (sanitized === '')
+        return null;
+    return sanitized.startsWith('/')
+        ? sanitized
+        : `/${sanitized}`;
 }
-
-// src/agnostic/sanitization/path/index.ts
-function sanitizePath(targetPath) {
-  const sanitized = targetPath.split("/").filter((chunk) => chunk !== "").map((chunk) => sanitizeFileName(chunk) ?? "").filter((chunk) => chunk !== "" && chunk !== "..").join("/");
-  if (sanitized === "") return null;
-  return sanitized.startsWith("/") ? sanitized : `/${sanitized}`;
-}
-export {
-  sanitizePath
-};

package/agnostic/sanitization/path/index.test.js

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest';
+import { sanitizePath } from './index.js';
+describe('sanitizePath', () => {
+    it('sanitizes each segment and removes empty/.. segments', () => {
+        const input = '/some//../unsafe/..//path/ fi?le.txt';
+        const result = sanitizePath(input);
+        expect(result).toBe('/some/unsafe/path/file.txt');
+    });
+    it('returns null for an empty or fully-invalid path', () => {
+        expect(sanitizePath('')).toBeNull();
+        expect(sanitizePath('/../..///')).toBeNull();
+    });
+    it('ensures the returned path starts with a leading slash', () => {
+        const input = 'relative/path.txt';
+        const result = sanitizePath(input);
+        expect(result?.startsWith('/')).toBe(true);
+    });
+});

package/agnostic/sanitization/types.js

@@ -0,0 +1 @@
+export {};

package/agnostic/sanitization/user-input/index.js

@@ -1,26 +1,38 @@
-// src/agnostic/sanitization/user-input/index.ts
-import xss from "xss";
-var sanitizeUserInput = (input, seen = /* @__PURE__ */ new WeakMap()) => {
-  if (typeof input === "string") return xss(input);
-  if (Array.isArray(input)) {
-    if (seen.has(input)) return seen.get(input);
-    const sanitized = [];
-    seen.set(input, sanitized);
-    sanitized.push(...input.map((item) => sanitizeUserInput(item, seen)));
-    return sanitized;
-  }
-  if (input !== null && typeof input === "object") {
-    if (seen.has(input)) return seen.get(input);
-    const sanitized = {};
-    seen.set(input, sanitized);
-    const entries = Object.entries(input);
-    for (const [key, value] of entries) {
-      sanitized[xss(key)] = sanitizeUserInput(value, seen);
+import xss from 'xss';
+/**
+ * Recursively sanitizes user input to prevent XSS.
+ *
+ * - Strings are sanitized using `xss`.
+ * - Arrays and objects are sanitized recursively.
+ * - Circular references are safely handled via a `WeakMap`.
+ *
+ * @template T
+ * @param input - Input value to sanitize (string, object, or array).
+ * @param [seen] - Internal set to track circular references.
+ * @returns Sanitized input with the same structure as the original.
+ */
+export const sanitizeUserInput = (input, seen = new WeakMap()) => {
+    if (typeof input === 'string')
+        return xss(input);
+    if (Array.isArray(input)) {
+        if (seen.has(input))
+            return seen.get(input);
+        const sanitized = [];
+        seen.set(input, sanitized);
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        sanitized.push(...input.map(item => sanitizeUserInput(item, seen)));
+        return sanitized;
     }
-    return sanitized;
-  }
-  return input;
-};
-export {
-  sanitizeUserInput
+    if (input !== null && typeof input === 'object') {
+        if (seen.has(input))
+            return seen.get(input);
+        const sanitized = {};
+        seen.set(input, sanitized);
+        const entries = Object.entries(input);
+        for (const [key, value] of entries) {
+            sanitized[xss(key)] = sanitizeUserInput(value, seen);
+        }
+        return sanitized;
+    }
+    return input;
 };

package/agnostic/sanitization/user-input/index.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect, vi } from 'vitest';
+import { sanitizeUserInput } from './index.js';
+vi.mock('xss', () => ({
+    default: vi.fn((value) => `sanitized(${value})`)
+}));
+describe('sanitizeUserInput', () => {
+    it('sanitizes plain strings using xss', () => {
+        const result = sanitizeUserInput('<script>alert(1)</script>');
+        expect(result).toBe('sanitized(<script>alert(1)</script>)');
+    });
+    it('recursively sanitizes arrays and objects', () => {
+        const input = {
+            '<key>': ['<v1>', '<v2>'],
+            nested: { '<inner>': '<v3>' }
+        };
+        const result = sanitizeUserInput(input);
+        expect(result).toEqual({
+            'sanitized(<key>)': ['sanitized(<v1>)', 'sanitized(<v2>)'],
+            'sanitized(nested)': { 'sanitized(<inner>)': 'sanitized(<v3>)' }
+        });
+    });
+    it('handles circular references without infinite recursion', () => {
+        const obj = { name: '<name>' };
+        obj.self = obj;
+        const result = sanitizeUserInput(obj);
+        // Just verify it doesn't throw and returns something
+        expect(result).toBeDefined();
+        // The circular reference should still be circular
+        expect(result['sanitized(self)']).toBe(result);
+    });
+});