boxwood 1.0.0 → 1.1.1

package/README.md

@@ -16,7 +16,7 @@
 7. i18n support
 8. server side
 9. good for seo
-10. small (1 file, 700 LOC~)
+10. small (1 file, 890 LOC~)
 11. easy to start, familiar syntax
 12. easy to test
 
@@ -136,6 +136,16 @@ test("banner renders an optional description", async () => {
 
 You can check the `test` dir for more examples.
 
+## Security
+
+By default, boxwood sanitizes all HTML, SVG and i18n content loaded via its API to protect against basic XSS attacks.
+
+Disabling sanitization ({ sanitize: false }) is only safe for trusted, developer-controlled files. Never use it with user-generated or untrusted content.
+
+All file access is restricted to the project directory and symlinks are not allowed by default to prevent path traversal attacks.
+
+That said, the library is pretty small so please review it and suggest improvements if you have any.
+
 ## Maintainers
 
 [@emilos](https://github.com/emilos)

package/index.js

@@ -1,5 +1,5 @@
-const { join } = require("path")
-const { readFileSync } = require("fs")
+const { join, resolve, sep: separator } = require("path")
+const { readFileSync, realpathSync, lstatSync } = require("fs")
 const csstree = require("css-tree")
 
 function compile(path) {
@@ -106,6 +106,86 @@ const escapeHTML = (string) => {
   })
 }
 
+const normalizePath = (path) => path.replace(/\\/g, "/").replace(/\/+$/, "")
+
+const ALLOWED_RAW_EXTENSIONS = ["html", "txt"]
+const ALLOWED_CODE_EXTENSIONS = ["js", "css", "json"]
+const ALLOWED_IMAGE_EXTENSIONS = ["png", "jpg", "jpeg", "gif", "webp", "svg"]
+const ALLOWED_READ_EXTENSIONS = [
+  ...ALLOWED_RAW_EXTENSIONS,
+  ...ALLOWED_IMAGE_EXTENSIONS,
+  ...ALLOWED_CODE_EXTENSIONS,
+]
+
+function validateSymlinks(path, base) {
+  let relative = path.slice(base.length + 1).split(separator)
+  let current = base
+  for (const part of relative) {
+    if (!part) continue
+    current = resolve(current, part)
+    if (lstatSync(current).isSymbolicLink()) {
+      throw new Error(`FileError: symlinks are not allowed ("${current}")`)
+    }
+  }
+}
+
+function validateFile(path, base) {
+  const normalizedPath = normalizePath(path)
+  const normalizedBase = normalizePath(base)
+
+  const type = extension(normalizedPath)
+
+  if (!type) {
+    throw new Error(`FileError: path "${path}" has no extension`)
+  }
+
+  if (!ALLOWED_READ_EXTENSIONS.includes(type)) {
+    throw new Error(
+      `FileError: unsupported file type "${type}" for path "${path}"`
+    )
+  }
+
+  const stats = lstatSync(normalizedPath)
+  if (!stats.isFile()) {
+    throw new Error(`FileError: path "${path}" is not a file`)
+  }
+
+  if (stats.isSymbolicLink()) {
+    throw new Error(`FileError: path "${path}" is a symbolic link`)
+  }
+
+  if (normalizedPath === normalizedBase) {
+    throw new Error(
+      `FileError: path "${path}" is the same as the current working directory "${base}"`
+    )
+  }
+
+  if (!normalizedPath.startsWith(normalizedBase + "/")) {
+    throw new Error(
+      `FileError: real path "${realPath}" is not within the current working directory "${realBase}"`
+    )
+  }
+}
+
+function readFile(path, encoding) {
+  try {
+    const base = process.cwd()
+    const absoluteBase = resolve(base)
+    const absolutePath = resolve(path)
+    const realBase = realpathSync(absoluteBase)
+    const realPath = realpathSync(absolutePath)
+
+    validateSymlinks(realPath, realBase)
+    validateFile(realPath, realBase)
+
+    return readFileSync(path, encoding)
+  } catch (exception) {
+    throw new Error(
+      `FileError: cannot read file "${path}": ${exception.message}`
+    )
+  }
+}
+
 const BOOLEAN_ATTRIBUTES = [
   "async",
   "autofocus",
@@ -150,9 +230,17 @@ const ALIASES = {
   htmlFor: "for",
 }
 
+const isKeyValid = (key) => /^[a-zA-Z0-9\-_]+$/.test(key)
+
 const attributes = (options) => {
+  if (!options) {
+    return ""
+  }
   const result = []
   for (const key in options) {
+    if (!isKeyValid(key)) {
+      continue
+    }
     const value = options[key]
     if (
       typeof value === "string" ||
@@ -166,10 +254,25 @@ const attributes = (options) => {
         const name = ALIASES[key] || key
         const value = options[key]
         const content = Array.isArray(value) ? classes(...value) : value
-        result.push(name + "=" + '"' + content + '"')
+        result.push(name + "=" + '"' + escapeHTML(content) + '"')
+      }
+    } else if (key === "style" && typeof value === "object") {
+      const styles = []
+      for (const param in value) {
+        if (!isKeyValid(param)) {
+          continue
+        }
+        const result = value[param]
+        if (result) {
+          styles.push(`${decamelize(param)}:${escapeHTML(result)}`)
+        }
+      }
+      if (styles.length > 0) {
+        result.push(`style="${styles.join(";")}"`)
       }
     }
   }
+
   return result.join(" ")
 }
 
@@ -229,9 +332,12 @@ const render = (input, escape = true) => {
     return `<${input.name}>`
   }
 
+  const string = input.attributes ? attributes(input.attributes) : ""
+  const attrs = string ? " " + string : ""
+
   return (
     `<${input.name}` +
-    (input.attributes ? " " + attributes(input.attributes) : "") +
+    attrs +
     ">" +
     render(input.children, isUnescapedTag(input.name)) +
     `</${input.name}>`
@@ -242,9 +348,67 @@ const raw = (children) => {
   return { name: "raw", children }
 }
 
-raw.load = function () {
-  const path = join(...arguments)
-  const content = readFileSync(path, "utf8")
+/**
+ * Never trust HTML files from untrusted sources.
+ *
+ * This function is a basic sanitization of HTML content in case
+ * you've accidentally included a "trusted", but malicious HTML file that was downloaded
+ * from the internet or other untrusted sources.
+ *
+ * This function removes script and style tags, inline event handlers,
+ * and any href attributes that use JavaScript. It does not
+ * guarantee complete security, but it helps to mitigate some common
+ * XSS attacks that can be embedded in HTML files.
+ *
+ * It is recommended to check all HTML files before using them
+ * in your application.
+ *
+ * Never trust user-generated content.
+ */
+
+const sanitizeHTML = (content) => {
+  return content
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+    .replace(/\son\w+="[^"]*"/gi, "")
+    .replace(/\son\w+='[^']*'/gi, "")
+    .replace(/(href|xlink:href)\s*=\s*(['"])javascript:[^'"]*\2/gi, "")
+}
+
+/*
+ * Raw content is a special case where we want to allow
+ * unescaped HTML content to be rendered directly.
+ * This is useful for cases where we want to
+ * include HTML fragments or templates that are
+ * not meant to be escaped, like large blocks of HTML,
+ * or when integrating with third-party libraries
+ * that require raw HTML.
+ *
+ * Please note that this should be used with caution,
+ * as it can lead to XSS vulnerabilities if the content
+ * is not properly sanitized.
+ *
+ * It should only be used for trusted content
+ * or in controlled environments.
+ *
+ * Should not be used for user-generated content.
+ */
+
+raw.load = function (path, options = {}) {
+  const type = extension(path)
+  if (!ALLOWED_RAW_EXTENSIONS.includes(type)) {
+    throw new Error(
+      `RawError: unsupported raw type "${type}" for path "${path}"`
+    )
+  }
+
+  let content = readFile(path, "utf8")
+  if (type === "html" && options.sanitize !== false) {
+    content = sanitizeHTML(content)
+  } else if (type === "txt" && options.escape !== false) {
+    content = escapeHTML(content)
+  }
+
   return raw(content)
 }
 
@@ -329,10 +493,62 @@ function css(inputs) {
   }
 }
 
-css.load = function () {
-  const path = join(...arguments)
+function occurences(input, string) {
+  if (string.length <= 0) {
+    return input.length + 1
+  }
+
+  let count = 0
+  let position = 0
+  const step = string.length
+  while (true) {
+    position = input.indexOf(string, position)
+    if (position >= 0) {
+      count += 1
+      position += step
+    } else {
+      break
+    }
+  }
+  return count
+}
+
+const validateCSS = (content, character1, character2) => {
+  const count1 = occurences(content, character1)
+  const count2 = occurences(content, character2)
+  if (count1 !== count2) {
+    return {
+      valid: false,
+      message: `Mismatched count of ${character1} and ${character2}`,
+    }
+  }
+  return { valid: true }
+}
+
+const CSS_PAIRS = [
+  ["{", "}"],
+  ["(", ")"],
+  ["[", "]"],
+]
+
+function isCSSValid(content) {
+  for (const [left, right] of CSS_PAIRS) {
+    const { valid, message } = validateCSS(content, left, right)
+    if (!valid) {
+      return { valid, message: message }
+    }
+  }
+
+  return { valid: true }
+}
+
+css.load = function (path) {
   const file = path.endsWith(".css") ? path : join(path, "index.css")
-  const content = readFileSync(file, "utf8")
+  const content = readFile(file, "utf8")
+  const { valid, message } = isCSSValid(content)
+  if (!valid) {
+    throw new Error(`CSSError: invalid CSS for path "${file}": ${message}`)
+  }
   return css`
     ${content}
   `
@@ -362,18 +578,23 @@ function js(inputs) {
   }
 }
 
-js.load = function () {
-  const parts = []
-  for (const param of arguments) {
-    if (typeof param === "string") {
-      parts.push(param)
-    }
-  }
-  const path = join(...parts)
+/*
+ * Load a JavaScript file and return a script tag.
+ *
+ * Please note that this should be used with caution,
+ * as it can lead to XSS vulnerabilities if the content
+ * is not properly sanitized.
+ *
+ * It should only be used for trusted content
+ * or in controlled environments.
+ *
+ * Should not be used for user-generated content.
+ */
+
+js.load = function (path, options = {}) {
   const file = path.endsWith(".js") ? path : join(path, "index.js")
-  const content = readFileSync(file, "utf8")
+  const content = readFile(file, "utf8")
 
-  const options = arguments[arguments.length - 1]
   const attributes = options.target ? { target: options.target } : {}
   if (options && options.transform) {
     return {
@@ -519,17 +740,73 @@ function base64({ content, path }) {
   return `data:${media(path)};base64,${content}`
 }
 
-nodes.img.load = function () {
-  const path = join(...arguments)
-  const content = readFileSync(path, "base64")
+nodes.img.load = function (path) {
+  const type = extension(path)
+  if (!ALLOWED_IMAGE_EXTENSIONS.includes(type)) {
+    throw new Error(
+      `ImageError: unsupported image type "${type}" for path "${path}"`
+    )
+  }
+  const content = readFile(path, "base64")
   return (options) => {
     return nodes.img({ src: base64({ content, path }), ...options })
   }
 }
 
-nodes.svg.load = function () {
-  const path = join(...arguments)
-  const content = readFileSync(path, "utf8")
+/*
+  Never trust SVG files from untrusted sources.
+  This function is a basic sanitization of SVG content in case
+  you've accidentally included a "trusted", but malicious SVG file that was downloaded
+  from the internet or other untrusted sources.
+
+  This function removes script and style tags, inline event handlers,
+  and any href attributes that use JavaScript. It does not
+  guarantee complete security, but it helps to mitigate some common
+  XSS attacks that can be embedded in SVG files.
+
+  It is recommended to check all SVG files before using them
+  in your application.
+*/
+const sanitizeSVG = (content) => {
+  return content
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+    .replace(/\son\w+="[^"]*"/gi, "")
+    .replace(/\son\w+='[^']*'/gi, "")
+    .replace(/(href|xlink:href)\s*=\s*(['"])javascript:[^'"]*\2/gi, "")
+}
+
+/*
+ * SVG files are a special case where we want to allow
+ * unescaped SVG content to be rendered directly.
+ * This is useful for cases where we want to
+ * include SVG fragments or templates that are
+ * not meant to be escaped, like large blocks of SVG,
+ * or when integrating with third-party libraries
+ * that require raw SVG.
+ *
+ * Please note that this should be used with caution,
+ * as it can lead to XSS vulnerabilities if the content
+ * is not properly sanitized.
+ *
+ * It should only be used for trusted content
+ * or in controlled environments.
+ *
+ * Should not be used for user-generated content.
+ */
+
+nodes.svg.load = function (path, options = {}) {
+  const type = extension(path)
+  if (type !== "svg") {
+    throw new Error(
+      `SVGError: unsupported SVG type "${type}" for path "${path}"`
+    )
+  }
+  let content = readFile(path, "utf8")
+  if (options.sanitize !== false) {
+    content = sanitizeSVG(content)
+  }
+
   return raw(content)
 }
 
@@ -557,11 +834,16 @@ function classes() {
 }
 
 const json = {
-  load() {
-    const path = join(...arguments)
+  load(path) {
     const file = path.endsWith(".json") ? path : join(path, "index.json")
-    const content = readFileSync(file, "utf8")
-    return JSON.parse(content)
+    const content = readFile(file, "utf8")
+    try {
+      return JSON.parse(content)
+    } catch (exception) {
+      throw new Error(
+        `JSONError: cannot parse file "${file}": ${exception.message}`
+      )
+    }
   },
 }
 
@@ -571,9 +853,18 @@ function i18n(translations) {
   }
 }
 
-i18n.load = function () {
-  const path = join(...arguments)
+i18n.load = function (path, options = {}) {
   const data = json.load(path)
+  if (options.sanitize !== false) {
+    for (const key in data) {
+      for (const lang in data[key]) {
+        if (typeof data[key][lang] === "string") {
+          data[key][lang] = sanitizeHTML(data[key][lang])
+        }
+      }
+    }
+  }
+
   return function translate(language, key) {
     if (!language) {
       throw new Error(`TranslationError: language is undefined`)

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "boxwood",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Compile HTML templates into JS",
   "main": "index.js",
   "scripts": {
-    "test": "node --test --test-reporter=dot",
-    "test:debug": "node --test --test-reporter=spec",
+    "test": "node --test --test-reporter=dot \"test/**/*.test.js\" \"test/**/*.spec.js\"",
+    "test:debug": "node --test --test-reporter=spec \"test/**/*.test.js\" \"test/**/*.spec.js\"",
     "coverage": "c8 npm test",
     "benchmark": "node --test benchmark/index.js",
     "watch": "npm test -- --watch",
     "prepush": "npm test"
   },
   "engines": {
-    "node": ">= 20.11.1"
+    "node": ">= 24.1.0"
   },
   "repository": {
     "type": "git",