sanitize-html 2.15.0 → 2.17.0

package/README.md

@@ -745,7 +745,7 @@ This will transform `<disallowed>content <allowed>content</allowed> </disallowed
 
 #### Escape the disallowed tag and all its children even for allowed tags.
 
-if you set `disallowedTagsMode` to `recursiveEscape`, disallowed tag and its children will be escaped even for allowed tags
+if you set `disallowedTagsMode` to `recursiveEscape`, disallowed tags and their children will be escaped even for allowed tags:
 
 ```js
 disallowedTagsMode: `recursiveEscape`
@@ -753,6 +753,15 @@ disallowedTagsMode: `recursiveEscape`
 
 This will transform `<disallowed>hello<p>world</p></disallowed>` to `&lt;disallowed&gt;hello&lt;p&gt;world&lt;/p&gt;&lt;/disallowed&gt;`
 
+#### Escape the disallowed tag, including all its attributes.
+
+By default, attributes are not preserved when tags are escaped. You can set `preserveEscapedAttributes` to `true` to 
+keep the attributes, which will also be escaped and therefore have no effect on the browser.
+
+```js
+preserveEscapedAttributes: true
+```
+
 ### Ignore style attribute contents
 
 Instead of discarding faulty style attributes, you can allow them by disabling the parsing of style attributes:
@@ -781,6 +790,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

@@ -220,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') {
@@ -296,7 +300,14 @@ function sanitizeHtml(html, options, _recursing) {
         }
       }
 
-      if (!allowedAttributesMap || has(allowedAttributesMap, name) || allowedAttributesMap['*']) {
+      const isBeingEscaped = skip && (options.disallowedTagsMode === 'escape' || options.disallowedTagsMode === 'recursiveEscape');
+      const shouldPreserveEscapedAttributes = isBeingEscaped && options.preserveEscapedAttributes;
+
+      if (shouldPreserveEscapedAttributes) {
+        each(attribs, function(value, a) {
+          result += ' ' + a + '="' + escapeHtml((value || ''), true) + '"';
+        });
+      } else if (!allowedAttributesMap || has(allowedAttributesMap, name) || allowedAttributesMap['*']) {
         each(attribs, function(value, a) {
           if (!VALID_HTML_ATTRIBUTE_NAME.test(a)) {
             // This prevents part of an attribute name in the output from being
@@ -544,6 +555,9 @@ function sanitizeHtml(html, options, _recursing) {
       }
     },
     onclosetag: function(name, isImplied) {
+      if (options.onCloseTag) {
+        options.onCloseTag(name, isImplied);
+      }
 
       if (skipText) {
         skipTextDepth--;
@@ -916,7 +930,8 @@ sanitizeHtml.defaults = {
   allowedSchemesAppliedToAttributes: [ 'href', 'src', 'cite' ],
   allowProtocolRelative: true,
   enforceHtmlBoundary: false,
-  parseStyleAttributes: true
+  parseStyleAttributes: true,
+  preserveEscapedAttributes: false
 };
 
 sanitizeHtml.simpleTransform = function(newTagName, newAttribs, merge) {

package/package.json

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