feat(sanitize): add sanitizeHtml, sanitizeJson, and sanitizeUrl utilities (#22)

Author: bnidev

.changeset/little-brooms-sing.md

@@ -0,0 +1,5 @@
+---
+"@bnidev/js-utils": minor
+---
+
+feat(sanitize): add `sanitizeJson` utility for safe JSON parsing

.changeset/twenty-signs-cheat.md

@@ -0,0 +1,5 @@
+---
+"@bnidev/js-utils": minor
+---
+
+feat(sanitize): add `sanitizeHtml` utility for rich-text HTML cleaning

.changeset/two-apes-warn.md

@@ -0,0 +1,5 @@
+---
+"@bnidev/js-utils": minor
+---
+
+feat(sanitize): add `sanitizeUrl` utility with protocol allowlist

src/index.ts

@@ -13,6 +13,9 @@
  * @categoryDescription Object
  * Utility functions for working with objects, including deep cloning, merging, and property manipulation.
  *
+ * @categoryDescription Sanitize
+ * Utility functions for sanitizing and validating data, such as JSON, HTML, and URLs, to prevent security issues like XSS and injection attacks.
+ *
  * @categoryDescription String
  * Utility functions for string manipulation, including formatting, parsing, and validation.
  *
@@ -36,6 +39,8 @@ export * from './math'
 
 export * from './object'
 
+export * from './sanitize'
+
 export * from './string'
 
 export * from './timing'

src/sanitize/__tests__/sanitizeHtml.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import { sanitizeHtml } from '../sanitizeHtml'
+
+describe('sanitizeHtml', () => {
+  it('preserves allowed tags and content', () => {
+    const input = '<p>Hello <strong>World</strong></p>'
+    const output = sanitizeHtml(input)
+    expect(output).toBe('<p>Hello <strong>World</strong></p>')
+  })
+
+  it('removes disallowed tags but preserves inner content', () => {
+    const input = '<script>alert("XSS")</script><p>Safe</p>'
+    const output = sanitizeHtml(input)
+    expect(output).toBe('alert("XSS")<p>Safe</p>')
+  })
+
+  it('removes disallowed attributes', () => {
+    const input = '<p style="color: red;" onclick="alert(1)">Hello</p>'
+    const output = sanitizeHtml(input)
+    expect(output).toBe('<p>Hello</p>')
+  })
+
+  it('preserves allowed attributes on allowed tags', () => {
+    const input = '<a href="https://example.com" target="_blank">Link</a>'
+    const output = sanitizeHtml(input)
+    expect(output).toBe(
+      '<a href="https://example.com" target="_blank">Link</a>'
+    )
+  })
+
+  it('removes dangerous javascript: hrefs', () => {
+    const input = '<a href="javascript:alert(1)">Click me</a>'
+    const output = sanitizeHtml(input)
+    expect(output).toBe('<a>Click me</a>')
+  })
+
+  it('removes dangerous data: URIs', () => {
+    const input = '<a href="data:text/html;base64,...">Click me</a>'
+    const output = sanitizeHtml(input)
+    expect(output).toBe('<a>Click me</a>')
+  })
+
+  it('allows custom tags and attributes if provided', () => {
+    const input = '<custom-el data-id="123">Test</custom-el>'
+    const output = sanitizeHtml(input, ['custom-el'], {
+      'custom-el': ['data-id']
+    })
+    expect(output).toBe('<custom-el data-id="123">Test</custom-el>')
+  })
+
+  it('unwraps unknown custom elements if not allowed', () => {
+    const input = '<my-tag><b>Bold</b></my-tag>'
+    const output = sanitizeHtml(input)
+    expect(output).toBe('<b>Bold</b>')
+  })
+
+  it('is case-insensitive for tag and attribute matching', () => {
+    const input = '<A HREF="https://example.com" TARGET="_blank">Link</A>'
+    const output = sanitizeHtml(input)
+    expect(output).toBe(
+      '<a href="https://example.com" target="_blank">Link</a>'
+    )
+  })
+
+  it('unwraps nested disallowed tags correctly', () => {
+    const input = '<div><span><script>alert(1)</script></span></div>'
+    const output = sanitizeHtml(input)
+    expect(output).toBe('alert(1)')
+  })
+})

src/sanitize/__tests__/sanitizeJson.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest'
+import { sanitizeJson } from '../sanitizeJson'
+
+type Person = { name: string }
+
+function isPerson(obj: unknown): obj is Person {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'name' in obj &&
+    typeof (obj as Record<string, unknown>).name === 'string'
+  )
+}
+
+describe('sanitizeJson', () => {
+  it('parses valid JSON without validation', () => {
+    const input = '{"foo": "bar"}'
+    const result = sanitizeJson(input)
+
+    expect(result.success).toBe(true)
+    expect(result.value).toEqual({ foo: 'bar' })
+    expect(result.error).toBeUndefined()
+  })
+
+  it('returns error on invalid JSON', () => {
+    const input = '{"foo": "bar"'
+    const result = sanitizeJson(input)
+
+    expect(result.success).toBe(false)
+    expect(result.value).toBeNull()
+    expect(result.error).toBeInstanceOf(Error)
+    expect(typeof result.error?.message).toBe('string')
+  })
+
+  it('validates object when validator is provided and passes', () => {
+    const input = '{"name": "Alice"}'
+    const result = sanitizeJson<Person>(input, isPerson)
+
+    expect(result.success).toBe(true)
+    expect(result.value).toEqual({ name: 'Alice' })
+  })
+
+  it('returns error when validation fails', () => {
+    const input = '{"name": 42}'
+    const result = sanitizeJson<Person>(input, isPerson)
+
+    expect(result.success).toBe(false)
+    expect(result.value).toBeNull()
+    expect(result.error?.message).toBe('Validation failed')
+  })
+
+  it('returns unknown error for non-Error throw', () => {
+    // mock JSON.parse to throw a non-Error
+    const originalParse = JSON.parse
+    JSON.parse = () => {
+      throw 'non-error string'
+    }
+
+    const result = sanitizeJson('{"test": true}')
+    expect(result.success).toBe(false)
+    expect(result.error).toBeInstanceOf(Error)
+    expect(result.error?.message).toBe('Unknown JSON parsing error')
+
+    JSON.parse = originalParse
+  })
+})

src/sanitize/__tests__/sanitizeUrl.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+import { sanitizeUrl } from '../sanitizeUrl'
+
+describe('sanitizeUrl', () => {
+  it('returns success and normalized URL for valid http URL', () => {
+    const result = sanitizeUrl('http://example.com')
+    expect(result.success).toBe(true)
+    expect(result.value).toBe('http://example.com/')
+    expect(result.error).toBeUndefined()
+  })
+
+  it('rejects disallowed protocol by default', () => {
+    const result = sanitizeUrl('mailto:user@example.com')
+    expect(result.success).toBe(false)
+    expect(result.value).toBeNull()
+    expect(result.error).toBeInstanceOf(Error)
+    expect(result.error?.message).toMatch(/Disallowed protocol/)
+  })
+
+  it('accepts custom allowed protocols', () => {
+    const result = sanitizeUrl('mailto:user@example.com', {
+      allowedProtocols: ['mailto:', 'http:']
+    })
+    expect(result.success).toBe(true)
+    expect(result.value).toBe('mailto:user@example.com')
+    expect(result.error).toBeUndefined()
+  })
+
+  it('returns original input when normalize option is false', () => {
+    const result = sanitizeUrl('http://example.com', { normalize: false })
+    expect(result.success).toBe(true)
+    expect(result.value).toBe('http://example.com')
+  })
+
+  it('returns error for invalid URL string', () => {
+    const result = sanitizeUrl('not-a-url')
+    expect(result.success).toBe(false)
+    expect(result.value).toBeNull()
+    expect(result.error).toBeInstanceOf(Error)
+    expect(result.error?.message).toMatch(/Invalid URL/)
+  })
+
+  it('handles non-Error exceptions gracefully', () => {
+    const OriginalURL = globalThis.URL
+
+    globalThis.URL = class {
+      constructor() {
+        throw 'some string error'
+      }
+    } as unknown as typeof URL
+
+    const result = sanitizeUrl('http://example.com')
+
+    expect(result.success).toBe(false)
+    expect(result.value).toBeNull()
+    expect(result.error).toBeInstanceOf(Error)
+    expect(result.error?.message).toBe('Invalid URL')
+
+    globalThis.URL = OriginalURL
+  })
+})

src/sanitize/index.ts

@@ -0,0 +1,5 @@
+// Export all modules from the 'sanitize' directory
+
+export * from './sanitizeHtml'
+export * from './sanitizeJson'
+export * from './sanitizeUrl'

src/sanitize/sanitizeHtml.ts

@@ -0,0 +1,97 @@
+/**
+ * Sanitizes a string of HTML, preserving only safe tags and attributes for rich text rendering.
+ *
+ * This function removes any tags and attributes that are not explicitly allowed, helping to prevent
+ * XSS (cross-site scripting) attacks and unwanted formatting. It is designed primarily for use with
+ * rich text editors, comments, or other user-generated content where a limited set of semantic HTML
+ * is acceptable.
+ *
+ * By default, only common formatting tags (`<p>`, `<strong>`, `<ul>`, etc.) are preserved. Layout
+ * and styling tags like `<div>` and `<span>` are excluded by design to keep the output clean and focused.
+ *
+ * @param dirtyHtml - The input HTML string to sanitize.
+ * @param allowedTags - An array of tag names (lowercase) to allow. Defaults to safe formatting tags.
+ * @param allowedAttributes - A map of tag names to allowed attributes. Keys and attribute names should be lowercase.
+ *
+ * @returns The sanitized HTML string.
+ *
+ * @remarks
+ * This function uses the DOM API and is safe to run in the browser.
+ * It prevents XSS by stripping dangerous tags and attribute values.
+ *
+ * @category Sanitize
+ *
+ * @example Imports
+ * ```ts
+ * // ES Module
+ * import { sanitizeHtml } from '@bnidev/js-utils'
+ *
+ * // CommonJS
+ * const { sanitizeHtml } = require('@bnidev/js-utils')
+ * ```
+ *
+ * @example Usage
+ * ```ts
+ * sanitizeHtml('<p onclick="alert()">Hi <strong>there</strong></p>')
+ * // → '<p>Hi <strong>there</strong></p>'
+ * ```
+ */
+export function sanitizeHtml(
+  dirtyHtml: string,
+  allowedTags: string[] = [
+    'b',
+    'i',
+    'em',
+    'strong',
+    'a',
+    'ul',
+    'ol',
+    'li',
+    'p',
+    'br'
+  ],
+  allowedAttributes: Record<string, string[]> = { a: ['href', 'target', 'rel'] }
+): string {
+  const parser = new DOMParser()
+  const doc = parser.parseFromString(dirtyHtml, 'text/html')
+
+  const isDangerousAttr = (attrName: string, value: string): boolean => {
+    if (attrName === 'href' || attrName === 'src') {
+      const val = value.trim().toLowerCase()
+      return (
+        val.startsWith('javascript:') ||
+        val.startsWith('data:') ||
+        val.startsWith('vbscript:')
+      )
+    }
+    return false
+  }
+
+  const sanitizeNode = (node: Element) => {
+    const tag = node.tagName.toLowerCase()
+
+    if (!allowedTags.includes(tag)) {
+      node.replaceWith(...Array.from(node.childNodes)) // unwrap disallowed tag
+      return
+    }
+
+    for (const attr of Array.from(node.attributes)) {
+      const attrName = attr.name.toLowerCase()
+      const tagAttrs = allowedAttributes[tag] || []
+
+      if (
+        !tagAttrs.includes(attrName) ||
+        isDangerousAttr(attrName, attr.value)
+      ) {
+        node.removeAttribute(attr.name)
+      }
+    }
+  }
+
+  const walker = doc.body.querySelectorAll('*')
+  for (const el of walker) {
+    sanitizeNode(el)
+  }
+
+  return doc.body.innerHTML
+}