sanitize-html 2.14.0 → 2.16.0

package/README.md

@@ -494,6 +494,21 @@ sanitizeHtml(
 );
 ```
 
+The filter function can also return the string `"excludeTag"` to only remove the tag, while keeping its content. For example, you can remove tags for anchors with invalid links:
+
+```js
+sanitizeHtml(
+  'This is a <a href="javascript:alert(123)">bad link</a> and a <a href="https://www.linux.org">good link</a>',
+  {
+    exclusiveFilter: function(frame) {
+      // the href attribute is removed by the URL protocol check
+      return frame.tag === 'a' && !frame.attribs.href ? 'excludeTag' : false;
+    }
+  }
+);
+// Output: 'This is a bad link and a <a href="https://www.linux.org">good link</a>'
+```
+
 The `frame` object supplied to the callback provides the following attributes:
 
 - `tag`: The tag name, i.e. `'img'`.
@@ -709,9 +724,9 @@ This will transform `<disallowed>content</disallowed>` to `&lt;disallowed&gt;con
 
 Valid values are: `'discard'` (default), `'completelyDiscard'` (remove disallowed tag's content), `'escape'` (escape the tag) and `'recursiveEscape'` (to escape the tag and all its content).
 
-#### Discard disallowed but but the inner content of disallowed tags is kept.
+#### Discard disallowed but the inner content of disallowed tags is kept.
 
-If you set `disallowedTagsMode` to `discard`, disallowed tags are discarded but but the inner content of disallowed tags is kept.
+If you set `disallowedTagsMode` to `discard`, disallowed tags are discarded but the inner content of disallowed tags is kept.
 
 ```js
 disallowedTagsMode: 'discard'
@@ -720,7 +735,7 @@ This will transform `<disallowed>content</disallowed>` to `content`
 
 #### Discard entire content of a disallowed tag
 
-If you set `disallowedTagsMode` to `completelyDiscard`, disallowed tags and any content they contain are discarded. Any subtags are still included, as long as those individual subtags are allowed.
+If you set `disallowedTagsMode` to `completelyDiscard`, disallowed tags and any text they contain are discarded. This also discards top-level text. Any subtags are still included, as long as those individual subtags are allowed.
 
 ```js
 disallowedTagsMode: 'completelyDiscard'
@@ -766,6 +781,50 @@ nestingLimit: 6
 
 This will prevent the user from nesting tags more than 6 levels deep. Tags deeper than that are stripped out exactly as if they were disallowed. Note that this means text is preserved in the usual ways where appropriate.
 
+### Advanced filtering
+
+For more advanced filtering you can hook directly into the parsing process using tag open and tag close events.
+
+The `onOpenTag` event is triggered when an opening tag is encountered. It has two arguments:
+- `tagName`: The name of the tag.
+- `attribs`: An object containing the tag's attributes, e.g. `{ src: "/path/to/tux.png" }`.
+
+The `onCloseTag` event is triggered when a closing tag is encountered. It has the following arguments:
+- `tagName`: The name of the tag.
+- `isImplied`: A boolean indicating whether the closing tag is implied (e.g. `<p>foo<p>bar`) or explicit (e.g. `<p>foo</p><p>bar</p>`).
+
+For example, you may want to add spaces around a removed tag, like this:
+```js
+const allowedTags = [ 'b' ];
+let addSpace = false;
+const sanitizedHtml = sanitizeHtml(
+  'There should be<div><p>spaces</p></div>between <b>these</b> words.',
+  {
+    allowedTags,
+    onOpenTag: (tagName, attribs) => {
+      addSpace = !allowedTags.includes(tagName);
+    },
+    onCloseTag: (tagName, isImplied) => {
+      addSpace = !allowedTags.includes(tagName);
+    },
+    textFilter: (text) => {
+      if (addSpace) {
+        addSpace = false;
+        return ' ' + text;
+      }
+      return text;
+    }
+  }
+);
+```
+
+In this example, we are setting a flag when a tag that will be removed has been opened or closed. Then we use the `textFilter` to modify the text to include spaces. The example should produce:
+```
+There should be spaces between <b>these</b> words.
+```
+
+This is a simplified example that is not meant to be production-ready. For your specific case, you may want to keep track of currently open tags, using the open and close events to push and pop items on the stack, or only insert spaces next to a subset of disallowed tags.
+
 ## About ApostropheCMS
 
 sanitize-html was created at [P'unk Avenue](https://punkave.com) for use in [ApostropheCMS](https://apostrophecms.com), an open-source content management system built on Node.js. If you like sanitize-html you should definitely check out ApostropheCMS.

package/index.js

@@ -97,6 +97,7 @@ function sanitizeHtml(html, options, _recursing) {
     this.attribs = attribs || {};
     this.tagPosition = result.length;
     this.text = ''; // Node inner text
+    this.openingTagLength = 0;
     this.mediaChildren = [];
 
     this.updateParentNodeText = function() {
@@ -219,6 +220,10 @@ function sanitizeHtml(html, options, _recursing) {
 
   const parser = new htmlparser.Parser({
     onopentag: function(name, attribs) {
+      if (options.onOpenTag) {
+        options.onOpenTag(name, attribs);
+      }
+
       // If `enforceHtmlBoundary` is `true` and this has found the opening
       // `html` tag, reset the state.
       if (options.enforceHtmlBoundary && name === 'html') {
@@ -268,7 +273,6 @@ function sanitizeHtml(html, options, _recursing) {
             skipTextDepth = 1;
           }
         }
-        skipMap[depth] = true;
       }
       depth++;
       if (skip) {
@@ -279,7 +283,7 @@ function sanitizeHtml(html, options, _recursing) {
             if (options.textFilter) {
               result += options.textFilter(escaped, name);
             } else {
-              result += escapeHtml(frame.innerText);
+              result += escaped;
             }
             addedText = true;
           }
@@ -507,6 +511,7 @@ function sanitizeHtml(html, options, _recursing) {
         result = tempResult + escapeHtml(result);
         tempResult = '';
       }
+      frame.openingTagLength = result.length - frame.tagPosition;
     },
     ontext: function(text) {
       if (skipText) {
@@ -529,11 +534,11 @@ function sanitizeHtml(html, options, _recursing) {
         // your concern, don't allow them. The same is essentially true for style tags
         // which have their own collection of XSS vectors.
         result += text;
-      } else {
+      } else if (!addedText) {
         const escaped = escapeHtml(text, false);
-        if (options.textFilter && !addedText) {
+        if (options.textFilter) {
           result += options.textFilter(escaped, tag);
-        } else if (!addedText) {
+        } else {
           result += escaped;
         }
       }
@@ -543,6 +548,9 @@ function sanitizeHtml(html, options, _recursing) {
       }
     },
     onclosetag: function(name, isImplied) {
+      if (options.onCloseTag) {
+        options.onCloseTag(name, isImplied);
+      }
 
       if (skipText) {
         skipTextDepth--;
@@ -584,9 +592,21 @@ function sanitizeHtml(html, options, _recursing) {
         delete transformMap[depth];
       }
 
-      if (options.exclusiveFilter && options.exclusiveFilter(frame)) {
-        result = result.substr(0, frame.tagPosition);
-        return;
+      if (options.exclusiveFilter) {
+        const filterResult = options.exclusiveFilter(frame);
+        if (filterResult === 'excludeTag') {
+          if (skip) {
+            // no longer escaping the tag since it's not added at all
+            result = tempResult;
+            tempResult = '';
+          }
+          // remove the opening tag from the result
+          result = result.substring(0, frame.tagPosition) + result.substring(frame.tagPosition + frame.openingTagLength);
+          return;
+        } else if (filterResult) {
+          result = result.substring(0, frame.tagPosition);
+          return;
+        }
       }
 
       frame.updateParentNodeMediaChildren();
@@ -832,7 +852,7 @@ sanitizeHtml.defaults = {
     'main', 'nav', 'section',
     // Text content
     'blockquote', 'dd', 'div', 'dl', 'dt', 'figcaption', 'figure',
-    'hr', 'li', 'main', 'ol', 'p', 'pre', 'ul',
+    'hr', 'li', 'menu', 'ol', 'p', 'pre', 'ul',
     // Inline text semantics
     'a', 'abbr', 'b', 'bdi', 'bdo', 'br', 'cite', 'code', 'data', 'dfn',
     'em', 'i', 'kbd', 'mark', 'q',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sanitize-html",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "Clean up user-submitted HTML, preserving allowlisted elements and allowlisted attributes on a per-element basis",
   "sideEffects": false,
   "main": "index.js",