@postalsys/email-text-tools 2.4.22 → 2.4.24

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "2.4.22"
+    ".": "2.4.24"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.4.24](https://github.com/postalsys/email-text-tools/compare/v2.4.23...v2.4.24) (2026-10-18)
+
+
+### Bug Fixes
+
+* contain painting in the outer wrapper too ([d1a8f9b](https://github.com/postalsys/email-text-tools/commit/d1a8f9bf2dd4fcad7adb983c243c524703cad79f))
+
+## [2.4.23](https://github.com/postalsys/email-text-tools/compare/v2.4.22...v2.4.23) (2026-10-18)
+
+
+### Bug Fixes
+
+* contain the message in a wrapper the sender cannot style, drop SVG, MathML and link openers ([7d79698](https://github.com/postalsys/email-text-tools/commit/7d79698f224c2bd4412d4dcd5d261d17c74022c1))
+
 ## [2.4.22](https://github.com/postalsys/email-text-tools/compare/v2.4.21...v2.4.22) (2026-10-18)
 
 

package/README.md

@@ -11,6 +11,12 @@ Email text tools
 - CSS rules whose selector uses `:is()`, `:where()`, `:has()` or a `:not()` containing another pseudo-class, and any `<style>` text beyond 256 KB per message
 - CSS inlining altogether when the style text holds more than 5,000 selectors, the document more than 50,000 elements, or the product of the two exceeds 5,000,000 (inlining costs one selector match per element). The sanitized HTML is then returned with its `<style>` rules dropped and `data-css-inlining="skipped"` on the wrapper `<div>`
 - a `style` attribute that still names a forbidden property after the CSSOM has filtered it, which means the CSSOM could not parse that declaration: the attribute is reduced to the declarations it did parse, or removed
+- SVG and MathML (DOMPurify runs with the `html` profile only): the namespace confusion between the three is where most sanitizer bypasses have come from, and mail has no use for either
+- `width`, `min-width`, `max-width`, `height`, `min-height` and `max-height` from the body's own style, which would otherwise size the container the host gave the message
+
+The output is two wrappers: an outer `<div style="overflow: auto; contain: paint;">` that is never given anything else, and inside it a `<div>` carrying the sanitized styles of the message body. Everything the body does (its margins, a `display: contents`, a box-shadow) is clipped by the outer element. `position` is forbidden on every element because it is the one property that escapes an overflow clip, and the paint containment makes the outer element the containing block of a fixed or absolute descendant in case one slips through. Every `a` and `area` gets `target="_blank" rel="noopener noreferrer"`, whatever `rel` it came with.
+
+Markup without a `<style>` start tag is sanitized once; the first pass exists to find and filter the stylesheets before they are inlined.
 
 Input nested more than about 1000 elements deep, or that the parser cannot process, is rendered as escaped plain text instead of throwing. `inlineHtml()` applies the same depth limit to the quoted message and to the new content, and quotes escaped text instead when it is exceeded.
 

package/lib/mime-html.js

@@ -72,12 +72,14 @@ const FORBID_STYLES = [
     'zoom'
 ];
 
-// Matches the style text of any element that could carry one of FORBID_STYLES
-const FORBID_STYLES_HINT = /position|float|clip|zoom|anim|offset|scrollbar|paint|clear|\ball\b/i;
+// Properties to remove from style attributes: the list, a cheap test for style text that could
+// name one of them, and a test for one of them in declaration position (at the start, or after any
+// character that cannot be part of a longer property name, so "background-position" is not one)
+function styleRule(properties, hint) {
+    return { properties, hint, declaration: new RegExp('(?:^|[^a-z0-9-])(?:' + properties.join('|') + ')\\s*:', 'i') };
+}
 
-// A forbidden property in declaration position: at the start, or after any character that cannot
-// be part of a longer property name, so "background-position" is not one
-const FORBID_STYLES_DECLARATION = new RegExp('(?:^|[^a-z0-9-])(?:' + FORBID_STYLES.join('|') + ')\\s*:', 'i');
+const FORBID_STYLES_RULE = styleRule(FORBID_STYLES, /position|float|clip|zoom|anim|offset|scrollbar|paint|clear|\ball\b/i);
 
 // Resolves CSS escape sequences (\6F, \o) the way a browser does before it matches a property
 // name, so that a forbidden property cannot hide behind an escaped character
@@ -94,6 +96,22 @@ function decodeCssEscapes(value) {
 // keep the style at first
 const FORBID_TAGS_ALL = ['style'].concat(FORBID_TAGS);
 
+// HTML only. The default profiles admit SVG and MathML too, and the namespace confusion between
+// the three is where most sanitizer bypasses have come from: markup one parser closes inside an
+// <svg> or <mglyph> and another reads as HTML. Mail has no use for either, the major webmail
+// clients strip inline SVG and MathML never reached a mail client, so both go.
+const USE_PROFILES = { html: true };
+
+// A start tag the HTML parser reads as a style element: the name followed by whitespace, "/" or
+// ">". Any other character inside the name makes it some other element, and a "<style" at the
+// very end of the input is dropped by the parser, so markup this does not match has no stylesheet.
+const STYLE_TAG = /<style[\s/>]/i;
+
+// The dimensions of the body. In mail they are page-layout leftovers ("width: 100%; height: 100%",
+// "min-height: 100vh") that would only pad or scroll the box the message is shown in, and they
+// were removed when the body was the outermost element, which consumers may rely on.
+const BODY_STYLES_RULE = styleRule(['width', 'min-width', 'max-width', 'height', 'min-height', 'max-height'], /width|height/i);
+
 // One sanitizer for the module. Every sanitize() call passes its full config, so calls do not
 // leak settings into each other.
 const DOMPurify = createDOMPurify(new JSDOM('').window);
@@ -329,8 +347,15 @@ function prepareHtml(message) {
         throw new Error('HTML is nested too deep to process');
     }
 
+    if (!STYLE_TAG.test(html)) {
+        // No style element can come out of this markup, so there is nothing to inline. This pass
+        // exists to find and filter the stylesheets before juice sees them, and without one it
+        // would only add a parse and a serialization to the pass finishHtml() makes anyway.
+        return { html, hasStyle: false, inliningSkipped: false };
+    }
+
     // first pass, returns the <html> element of the fixed HTML page
-    const root = DOMPurify.sanitize(html, { WHOLE_DOCUMENT: true, FORCE_BODY: false, FORBID_TAGS, FORBID_ATTR, RETURN_DOM: true });
+    const root = DOMPurify.sanitize(html, { WHOLE_DOCUMENT: true, FORCE_BODY: false, USE_PROFILES, FORBID_TAGS, FORBID_ATTR, RETURN_DOM: true });
 
     // Remove any style tags from within body content
     const body = root.querySelector('body');
@@ -368,71 +393,85 @@ function prepareHtml(message) {
     return { html: root.outerHTML, hasStyle, inliningSkipped };
 }
 
-// Second sanitization pass and post-processing of the juice output.
+// Removes the properties of a style rule from an element the way a browser will read them, by the
+// CSSOM first and then by the attribute text the CSSOM did not parse.
+function removeStyleProperties(node, rule) {
+    if (!rule.hint.test(node.getAttribute('style') || '')) {
+        return;
+    }
+    for (const property of rule.properties) {
+        node.style.removeProperty(property);
+    }
+    // removeProperty() rewrites the attribute from the CSSOM, which only holds the declarations
+    // cssstyle managed to parse. A forbidden property still named in the attribute after that was
+    // never parsed and would go out verbatim for the browser to read its own way: cssstyle 5 parses
+    // nothing from an attribute whose "background: url()" shorthand is followed by more
+    // declarations, a browser reads every one of them. Keep only what the CSSOM parsed, which may
+    // be nothing
+    const remaining = node.getAttribute('style') || '';
+    if (rule.declaration.test(remaining)) {
+        const parsed = node.style.cssText;
+        if (parsed) {
+            node.setAttribute('style', parsed);
+        } else {
+            node.removeAttribute('style');
+        }
+    } else if (!remaining.trim()) {
+        node.removeAttribute('style');
+    }
+}
+
+// The sanitization pass that produces the output (the second one when there was a stylesheet to
+// inline, the only one otherwise) and the post-processing of its result.
 function finishHtml(html, inliningSkipped) {
-    // second pass, outputs a BODY DOM element
+    // outputs a BODY DOM element
     const dom = DOMPurify.sanitize(html, {
         RETURN_DOM: true,
         WHOLE_DOCUMENT: false,
         FORCE_BODY: true,
+        USE_PROFILES,
         FORBID_TAGS: FORBID_TAGS_ALL,
         FORBID_ATTR
     });
 
-    // mark all links to be opened in a new window
-    for (let elm of dom.querySelectorAll('a')) {
-        elm.setAttribute('target', '_blank');
+    // Every link opens a new browsing context that gets neither an opener nor a referrer. Browsers
+    // imply noopener for target="_blank", but rel="opener" opts back in and the sender writes rel,
+    // and an opener can navigate the page the message is shown in. An <area> is a link too.
+    for (const link of dom.querySelectorAll('a, area')) {
+        link.setAttribute('target', '_blank');
+        link.setAttribute('rel', 'noopener noreferrer');
     }
 
-    dom.style.overflow = 'auto';
-
-    // return <BODY> HTML
-    dom.style.removeProperty('width');
-    dom.style.removeProperty('min-width');
-    dom.style.removeProperty('max-width');
-    dom.style.removeProperty('height');
-    dom.style.removeProperty('min-height');
-    dom.style.removeProperty('max-height');
-
     // remove specific style properties, touching the CSSOM only where the style text could name one
     for (const node of [dom, ...dom.querySelectorAll('[style]')]) {
         if (!node.style) {
             continue;
         }
-        let styleText = node.getAttribute('style') || '';
+        const styleText = node.getAttribute('style') || '';
         if (styleText.indexOf('\\') >= 0) {
             // A browser resolves CSS escapes in property names (p\osition is position) but jsdom's
-            // CSSOM does not, so the check below would miss them. Decode first and write the
+            // CSSOM does not, so the checks below would miss them. Decode first and write the
             // decoded text back so the CSSOM sees the same properties the browser will
-            styleText = decodeCssEscapes(styleText);
-            node.setAttribute('style', styleText);
-        }
-        if (FORBID_STYLES_HINT.test(styleText)) {
-            for (let disallowedStyle of FORBID_STYLES) {
-                node.style.removeProperty(disallowedStyle);
-            }
-            // removeProperty() rewrites the attribute from the CSSOM, which only holds the
-            // declarations cssstyle managed to parse. A forbidden property still named in the
-            // attribute after that was never parsed and would go out verbatim for the browser to
-            // read its own way: cssstyle 5 parses nothing from an attribute whose "background:
-            // url()" shorthand is followed by more declarations, a browser reads every one of
-            // them. Keep only what the CSSOM parsed, which may be nothing
-            if (FORBID_STYLES_DECLARATION.test(node.getAttribute('style') || '')) {
-                const parsed = node.style.cssText;
-                if (parsed) {
-                    node.setAttribute('style', parsed);
-                } else {
-                    node.removeAttribute('style');
-                }
-            }
+            node.setAttribute('style', decodeCssEscapes(styleText));
         }
+        removeStyleProperties(node, FORBID_STYLES_RULE);
     }
-
-    let bodyStyles = (dom.getAttribute('style') || '').toString().trim();
-
-    // embed into a styled container; the attribute tells the caller the CSS inlining caps were hit
+    removeStyleProperties(dom, BODY_STYLES_RULE);
+
+    const bodyStyles = (dom.getAttribute('style') || '').trim();
+
+    // Two wrappers. The outer one is ours alone and clips everything inside it; the inner one is
+    // the message body with the styles it came with. While the body's styles sat on the clipping
+    // element, a sender could undo the clipping (display: contents or inline, an overflow-x:
+    // visible written after our overflow) or move the element itself over the page around it (a
+    // negative margin, a box-shadow or an outline a few thousand pixels wide). Position is the
+    // one property that escapes an overflow clip, and it is forbidden above; paint containment
+    // makes the outer box the containing block of a fixed or absolute descendant as well, so a
+    // position that slipped past the filter would still be clipped by it. The attribute tells
+    // the caller the CSS inlining caps were hit
     const marker = inliningSkipped ? ' data-css-inlining="skipped"' : '';
-    return `<div style="${he.encode(bodyStyles)}"${marker}>${dom.innerHTML.trim()}</div>`;
+    const body = bodyStyles ? `<div style="${he.encode(bodyStyles)}">` : '<div>';
+    return `<div style="overflow: auto; contain: paint;"${marker}>${body}${dom.innerHTML.trim()}</div></div>`;
 }
 
 // Runs the pipeline and renders the plain text fallback when it fails, for example when a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@postalsys/email-text-tools",
-    "version": "2.4.22",
+    "version": "2.4.24",
     "description": "Email text tools",
     "main": "index.js",
     "scripts": {

package/test/containment.test.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const { mimeHtml } = require('..');
+
+// The message is shown inside a page that is not the sender's. These tests pin what keeps it there:
+// a clipping wrapper the sender cannot style, links that cannot reach back, no foreign content.
+
+describe('container', () => {
+    it('wraps a message with no body styles in a bare inner element', () => {
+        assert.equal(mimeHtml({ html: '<p>x</p>' }), '<div style="overflow: auto; contain: paint;"><div><p>x</p></div></div>');
+    });
+
+    it('keeps the body styles off the clipping wrapper', () => {
+        const html =
+            '<html><body style="display: contents; margin: -500px; overflow: visible; overflow-x: visible; box-shadow: 0 0 0 9999px red; outline: 9999px solid red; color: red">' +
+            '<div style="transform: translateY(-300px)">x</div></body></html>';
+        const out = mimeHtml({ html });
+        assert.ok(out.endsWith('</div></div>'), out);
+        const inner = /^<div style="overflow: auto; contain: paint;"><div style="([^"]*)">/.exec(out)[1];
+        assert.match(inner, /display: contents/);
+        assert.match(inner, /margin: -500px/);
+        assert.match(inner, /color: red/);
+        assert.match(out, /transform: translateY\(-300px\)/);
+    });
+
+    it('puts a body rule from the stylesheet on the inner element too', () => {
+        const html = '<html><head><style>body { display: contents; margin: -200px; } p { color: red; }</style></head><body><p>x</p></body></html>';
+        const out = mimeHtml({ html });
+        assert.ok(out.startsWith('<div style="overflow: auto; contain: paint;"><div style="'), out);
+        assert.match(out, /display: contents/);
+        assert.match(out, /color: red/);
+    });
+
+    it('drops the dimensions of the body and keeps its other styles', () => {
+        const out = mimeHtml({
+            html: '<html><body style="width: 600px; min-height: 100vh; max-width: 50%; background-color: #fff; color: red">x</body></html>'
+        });
+        assert.doesNotMatch(out, /width|height/);
+        assert.match(out, /background-color: (?:#fff|rgb\(255, 255, 255\))/);
+        assert.match(out, /color: red/);
+    });
+
+    it('drops a body width the CSSOM could not parse', () => {
+        // cssstyle parses nothing from this attribute, a browser reads the width
+        const out = mimeHtml({ html: '<html><body style="background:url(https://example.com/x.gif) no-repeat; width: 5000px">x</body></html>' });
+        assert.equal(out, '<div style="overflow: auto; contain: paint;"><div>x</div></div>');
+    });
+
+    it('keeps body styles the CSSOM could not parse when none of them is forbidden', () => {
+        // the old wrapper lost every body style here, because setting its overflow rewrote the
+        // attribute from a CSSOM that held nothing
+        const out = mimeHtml({ html: '<html><body style="background:url(https://example.com/x.gif) no-repeat; color:red; font:12px serif">x</body></html>' });
+        assert.ok(out.includes('<div style="background:url(https://example.com/x.gif) no-repeat; color:red; font:12px serif">x</div>'), out);
+    });
+
+    it('still removes position everywhere, including the body', () => {
+        const out = mimeHtml({ html: '<html><body style="position: fixed; inset: 0; color: red"><div style="position: sticky; top: 0">x</div></body></html>' });
+        assert.doesNotMatch(out, /position/);
+        assert.match(out, /color: red/);
+        assert.match(out, /top: 0/);
+    });
+
+    it('marks skipped inlining on the outer wrapper', () => {
+        let css = '';
+        for (let i = 0; i <= 5000; i++) {
+            css += `.c${i} { color: red; }\n`;
+        }
+        const out = mimeHtml({ html: `<html><head><style>${css}</style></head><body style="color: blue"><p class="c1">x</p></body></html>` });
+        assert.ok(out.startsWith('<div style="overflow: auto; contain: paint;" data-css-inlining="skipped"><div style="color: blue">'), out.slice(0, 120));
+    });
+});
+
+describe('links', () => {
+    it('opens every link in a new context that gets no opener and no referrer', () => {
+        const out = mimeHtml({ html: '<a href="https://example.com/" rel="opener">x</a><a href="https://example.com/" target="_top" rel="nofollow">y</a>' });
+        assert.equal((out.match(/<a /g) || []).length, 2);
+        assert.doesNotMatch(out, /rel="opener"|rel="nofollow"|_top/);
+        assert.equal((out.match(/target="_blank"/g) || []).length, 2);
+        assert.equal((out.match(/rel="noopener noreferrer"/g) || []).length, 2);
+    });
+
+    it('treats an image map area as a link', () => {
+        const out = mimeHtml({
+            html: '<img src="https://example.com/i.png" usemap="#m"><map name="m"><area shape="rect" coords="0,0,9,9" href="https://example.com/"></map>'
+        });
+        assert.match(out, /<area [^>]*target="_blank"/);
+        assert.match(out, /<area [^>]*rel="noopener noreferrer"/);
+    });
+});
+
+describe('foreign content', () => {
+    it('removes SVG and MathML', () => {
+        const out = mimeHtml({
+            html:
+                '<p>a</p><svg width="20" height="20"><circle cx="10" cy="10" r="8"/></svg><math><mi>x</mi></math>' +
+                '<math><mtext><table><mglyph><style><!--</style><img title="--><img src=1 onerror=alert(1)>"><p>b</p>'
+        });
+        assert.doesNotMatch(out, /<svg|<math|<circle|<mi|onerror/);
+        assert.ok(out.includes('<p>a</p>'), out);
+    });
+});
+
+describe('single sanitization pass for markup without a stylesheet', () => {
+    it('sanitizes the same way', () => {
+        const out = mimeHtml({
+            html: '<p onclick="x()">a</p><script>alert(1)</script><a href="javascript:alert(1)">b</a><iframe src="https://example.com/"></iframe>'
+        });
+        assert.equal(out, '<div style="overflow: auto; contain: paint;"><div><p>a</p><a target="_blank" rel="noopener noreferrer">b</a></div></div>');
+    });
+
+    for (const [label, tag, close] of [
+        ['upper case', '<STYLE>', '</STYLE>'],
+        ['whitespace after the name', '<style\n>', '</style>'],
+        ['a self-closing slash', '<style/>', '</style>']
+    ]) {
+        it(`still inlines a stylesheet whose tag uses ${label}`, () => {
+            const out = mimeHtml({ html: `<html><head>${tag}p { color: red; }${close}</head><body><p>x</p></body></html>` });
+            assert.match(out, /color: red/, out);
+        });
+    }
+
+    it('leaves a style tag that is only text alone', () => {
+        const out = mimeHtml({ html: '<p>write &lt;style&gt; to add rules</p>' });
+        assert.equal(out, '<div style="overflow: auto; contain: paint;"><div><p>write &lt;style&gt; to add rules</p></div></div>');
+    });
+});

package/test/hardening.test.js

@@ -257,7 +257,7 @@ describe('hostile input hardening', () => {
     });
 
     describe('CSS inlining caps', () => {
-        const SKIPPED_PREFIX = '<div style="overflow: auto;" data-css-inlining="skipped">';
+        const SKIPPED_PREFIX = '<div style="overflow: auto; contain: paint;" data-css-inlining="skipped">';
 
         function styled(css, body) {
             return `<html><head><style>${css}</style></head><body>${body}</body></html>`;
@@ -298,7 +298,7 @@ describe('hostile input hardening', () => {
             // rules nested in a media query are not matched against elements and do not count
             const css = `${rules(2000)}p.x { color: blue; }\n@media screen { ${rules(4000)} }`;
             const result = mimeHtml({ html: styled(css, '<p class="x">y</p>'.repeat(2000)) });
-            assert.ok(result.startsWith('<div style="overflow: auto;"><p'), result.slice(0, 80));
+            assert.ok(result.startsWith('<div style="overflow: auto; contain: paint;"><div><p'), result.slice(0, 80));
             assert.match(result, /color: blue/);
         });
 
@@ -451,7 +451,7 @@ describe('hostile input hardening', () => {
             assert.equal(afterText, false);
             assert.equal(afterMime, true);
             assert.equal(asyncType, 'function');
-            assert.equal(out, '<div style="overflow: auto;"><p>x</p></div>');
+            assert.equal(out, '<div style="overflow: auto; contain: paint;"><div><p>x</p></div></div>');
         });
 
         it('keeps mimeHtml enumerable and destructurable', () => {