<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\library;
/**
* Sanitizes untrusted HTML against a permissive-but-safe allowlist.
* Built for rendering text/html email bodies inline without giving
* the message author the ability to run script, beacon to a tracker
* pixel via a stylesheet, or otherwise hijack the page.
*
* Approach: parse the input with DOMDocument, walk the tree
* post-order, drop elements whose tag is not on the allowlist,
* strip attributes that are not on the per-tag allowlist, and
* restrict href / src URLs to http, https, and mailto. The result
* is serialised back to HTML.
*
* What survives sanitisation:
* - structural and semantic tags (p, div, span, section, article,
* header, footer, aside, blockquote, etc.);
* - inline formatting (strong, b, em, i, u, s, small, mark, sub,
* sup, code, kbd, samp, var);
* - headings (h1 through h6) and breaks (br, hr);
* - lists (ul, ol, li, dl, dt, dd);
* - tables (table, thead, tbody, tfoot, tr, td, th, caption,
* colgroup, col) with colspan / rowspan / scope preserved;
* - hyperlinks (a) with href restricted to http(s) / mailto;
* - images (img) with src restricted to http(s); alt, width,
* height preserved;
* - a safe subset of inline style: colour, typography, spacing,
* border, list, display, and visibility declarations (so a
* message can, for instance, hide its own preheader).
*
* What does not survive:
* - script, style, link, meta, base, iframe, object, embed,
* form, input, button, select, textarea, applet, frame,
* frameset (any tag that can fetch, run, or load active
* content);
* - every on* event handler attribute (onclick, onload,
* onmouseover, onerror, etc.);
* - the unsafe part of a style attribute: any declaration whose
* property is not on the safe list (position, z-index, float,
* and friends, which can lift content over the page), whose
* value carries a hazard such as url() or expression() (CSS
* that beacons or, on legacy IE, runs script), or that sets a
* fixed-pixel width that would overflow a narrow pane;
* - href and src values with schemes other than http, https,
* or mailto -- in particular javascript: and data: schemes
* are dropped.
*
* Image src is allowed for usability with formatted mail, but a
* caller that wants to block remote images for privacy reasons
* (tracker pixels) can pre-process the output to remove image src
* attributes. A "block remote images" toggle in the mail UI is a
* sensible future extension; this class deliberately stops at
* the security boundary.
*
* @author Chris Pollett
*/
class HtmlSanitizer
{
/**
* Tags whose content is rendered as-is after their attributes
* are filtered. Anything not in this set is removed entirely
* along with its descendants.
*/
private const ALLOWED_TAGS = ['a', 'p', 'br', 'hr', 'span',
'div', 'section', 'article', 'header', 'footer', 'aside',
'main', 'nav', 'strong', 'b', 'em', 'i', 'u', 's',
'small', 'mark', 'sub', 'sup', 'h1', 'h2', 'h3', 'h4',
'h5', 'h6', 'ul', 'ol', 'li', 'dl', 'dt', 'dd',
'blockquote', 'q', 'cite', 'code', 'pre', 'kbd', 'samp',
'var', 'table', 'thead', 'tbody', 'tfoot', 'tr', 'td',
'th', 'caption', 'colgroup', 'col', 'img', 'figure',
'figcaption', 'address', 'time'];
/**
* Attributes allowed on every allowed tag (the global set,
* keyed by '*') and tag-specific allowed attributes. An
* attribute on an allowed tag that appears in neither map is
* stripped.
*/
private const ALLOWED_ATTRS = [
'*' => ['title', 'lang', 'dir', 'style'],
'a' => ['href'],
'img' => ['src', 'alt', 'width', 'height'],
'td' => ['rowspan', 'colspan', 'headers'],
'th' => ['rowspan', 'colspan', 'scope', 'abbr'],
'col' => ['span'],
'colgroup' => ['span'],
'time' => ['datetime'],
];
/**
* Tags that are dropped without dropping their children.
* When the input is a full HTML document, the wrapping html,
* head, and body tags arrive at the sanitiser as elements
* that are not on the allowed list -- treating them like any
* other disallowed tag would discard the entire body content
* along with them. Instead we splice their children up into
* the parent and remove the wrapper. The children are then
* walked normally, so style/meta/link inside <head> are still
* dropped and the body content emerges at the top level of
* the cleaned output.
*
* center and font are obsolete presentational wrappers that
* HTML mail still uses heavily for layout (a newsletter often
* wraps its entire body in a single <center>). They carry no
* content of their own, so they are unwrapped rather than
* removed; dropping them with their subtree would blank out
* the whole message.
*/
private const UNWRAP_TAGS = ['html', 'body', 'head', 'center',
'font'];
/**
* URL schemes allowed in href and src attribute values. A
* relative URL (no scheme) is treated as safe and preserved
* unchanged so anchors to fragments within the same document
* continue to work; everything with a scheme that is not on
* this list is dropped.
*/
private const ALLOWED_SCHEMES = ['http', 'https', 'mailto'];
/**
* Inline CSS properties kept when an element carries a style
* attribute. The set covers the colour, typography, spacing,
* border, and list formatting that formatted mail relies on,
* plus display and visibility so a message can hide its own
* preheader. It deliberately omits anything that can lift an
* element out of flow or over the surrounding page -- there
* is no position, top/right/bottom/left, z-index, float, or
* clear -- and omits min-width, which bulk mail commonly sets
* to a desktop pixel figure that then overflows a phone.
*/
private const SAFE_STYLE_PROPERTIES = ['color',
'background-color', 'background', 'font', 'font-family',
'font-size', 'font-style', 'font-weight', 'font-variant',
'line-height', 'letter-spacing', 'word-spacing',
'text-align', 'text-decoration', 'text-transform',
'text-indent', 'vertical-align', 'white-space',
'word-break', 'word-wrap', 'overflow-wrap', 'padding',
'padding-top', 'padding-right', 'padding-bottom',
'padding-left', 'margin', 'margin-top', 'margin-right',
'margin-bottom', 'margin-left', 'border', 'border-top',
'border-right', 'border-bottom', 'border-left',
'border-width', 'border-style', 'border-color',
'border-radius', 'border-collapse', 'border-spacing',
'list-style', 'list-style-type', 'list-style-position',
'caption-side', 'display', 'visibility', 'width',
'max-width', 'height', 'max-height'];
/**
* Substrings that, if present in a style value, cause the
* whole declaration to be dropped. url( would let a stylesheet
* fetch a remote resource (a tracker beacon, and a way around
* the remote-image block); expression( and behavior are legacy
* script-in-CSS; @import pulls a remote sheet; the comment and
* angle-bracket markers and the backslash defeat escape-based
* attempts to smuggle one of the above past this check.
*/
private const STYLE_VALUE_HAZARDS = ['url(', 'expression(',
'javascript:', '@import', '/*', '*/', '<', '>', '\\',
'behavior'];
/**
* Sanitises an HTML fragment, returning a string of HTML
* containing only allowlisted tags and attributes with safe
* URL schemes. The result is suitable for inline rendering in
* a content pane. An empty input returns the empty string.
*
* @param string $html the untrusted HTML fragment
* @param bool $block_remote_images when true, each remote
* image is marked so the browser does not fetch it on
* render: the src is left untouched, but loading="lazy"
* and a mail-blocked-image class are added. The class
* hides the image (display:none), so a lazy image has
* no layout box and is never near the viewport, and the
* browser does not fetch it. The caller offers a "load
* remote images" control that removes the class; the
* revealed image then loads natively through the normal
* image path. This defends against tracker-pixel beacons
* in mail without ever rewriting src.
* @return string sanitised HTML
*/
public static function sanitize($html, $block_remote_images = false)
{
if ($html === null || $html === '') {
return '';
}
$html = self::preNormalize($html);
$dom = new \DOMDocument('1.0', 'UTF-8');
/* libxml emits warnings for malformed HTML, which all
real-world mail is; capture and discard them so they do
not reach Yioop's global handler. */
$previous_state = libxml_use_internal_errors(true);
/* the XML processing instruction at the top is the
well-documented trick for forcing libxml to interpret
the bytes as UTF-8 rather than its default Latin-1; the
NOIMPLIED + NODEFDTD flags tell loadHTML not to wrap
the fragment in implicit html/body elements. */
$wrapper = '<?xml encoding="UTF-8" ?>' .
'<div id="__sanitize_root">' . $html . '</div>';
$dom->loadHTML($wrapper, LIBXML_HTML_NOIMPLIED |
LIBXML_HTML_NODEFDTD);
libxml_clear_errors();
libxml_use_internal_errors($previous_state);
$root = $dom->getElementById('__sanitize_root');
if ($root === null) {
return '';
}
self::cleanElement($root, $block_remote_images);
$output = '';
foreach ($root->childNodes as $child) {
$output .= $dom->saveHTML($child);
}
return $output;
}
/**
* Pre-pass over the raw HTML to scrub markup oddities that
* survive MIME decoding but confuse libxml. Two patterns are
* targeted; both originate from Outlook-template wrappers
* embedded in newsletters and bulk-mail tooling:
*
* 1. `<!/Wrapper Fix>`-style pseudo-closers: look like an
* SGML comment-open prefix but aren't valid markup. libxml
* treats them as literal text so the would-be opener
* (handled below) never gets closed.
* 2. `<Wrapper Fix>`-style pseudo-openers: an unknown tag
* name followed by a space and bare-word "attributes"
* rather than the real attr=value form. libxml accepts
* these as elements but cleanElement strips unknown tags,
* taking the rest of the row's content with them.
*
* Both are deleted entirely. Real shorthand-boolean syntax
* (e.g. <input disabled>) is preserved because its tag name
* is a known HTML element and the regex below only targets
* the more specific pseudo-pattern.
*
* @param string $html raw HTML before parsing
* @return string $html with the pseudo-markup removed
*/
private static function preNormalize($html)
{
/* drop "<!/Anything>" closers. The leading "<!" looks
like the start of a comment or declaration but the
"/" after means none of the real markup productions
match it, so libxml escapes the whole thing as text. */
$html = preg_replace('/<![\/][^>]*>/', '', $html);
/* drop "<TagName Word ...>" openers where TagName is a
tag the HTML spec doesn't define AND the body of the
tag has a space-separated bare word with no "=" or
quote. The (?!a |b |c |...) negative lookahead would
be tedious; instead we just require the tag-body to
contain no "=" at all, which leaves real shorthand
booleans alone (since those have either no body or a
single boolean attribute name -- our pattern requires
a SPACE inside the body, signalling two-word free
text, which boolean shorthand never has). */
$html = preg_replace(
'/<[A-Za-z][A-Za-z0-9]*\s+[A-Za-z][A-Za-z0-9]*\s*>/',
'', $html);
/* drop meta-charset declarations. The MIME pipeline has
already decoded the body to UTF-8 by the time we get
here; the document head's meta is the SENDER's notion
of the bytes when they composed the message, not what
we are actually holding. libxml's loadHTML consults
the meta and would re-decode the bytes through that
charset -- turning UTF-8 em-dashes and smart quotes
into Latin-1 mojibake when the meta declares (e.g.)
Windows-1252 inside a part the MIME header declared
UTF-8. Outlook 2010 and many enterprise mail systems
emit exactly that combination. Two shapes are
targeted: <meta http-equiv="Content-Type" ...> and
<meta charset=...>. Both case-insensitive. */
$html = preg_replace(
'/<meta\s+[^>]*http-equiv\s*=\s*' .
'["\']?content-type["\']?[^>]*>/i', '', $html);
$html = preg_replace(
'/<meta\s+[^>]*charset\s*=[^>]*>/i', '', $html);
return $html;
}
/**
* Walks an element's children in document order, applying
* tag-level policy: disallowed tags are removed entirely (the
* subtree goes with them); unwrap tags (html, body, head) are
* removed but their children are spliced into the parent in
* the deleted tag's place and become subjects of the same
* walk; allowed tags are kept, their attributes filtered, and
* the walk recurses into their children.
*
* Iteration is index-based against the live childNodes list
* rather than over a pre-captured snapshot, because the
* snapshot would not see children that are spliced in by an
* unwrap step. After a removal or splice, the index does not
* advance so the new node at that position is processed next.
*
* @param \DOMElement $element the subtree root to clean
* @param bool $block_remote_images forwarded to
* cleanAttributes so remote images are marked for
* deferred (lazy, hidden) loading
*/
private static function cleanElement($element,
$block_remote_images)
{
$i = 0;
while ($i < $element->childNodes->length) {
$child = $element->childNodes->item($i);
if (!($child instanceof \DOMElement)) {
$i++;
continue;
}
$tag = strtolower($child->tagName);
if (in_array($tag, self::UNWRAP_TAGS, true)) {
/* splice the unwrap element's children into the
parent in its place; they will be inspected by
continued iteration at the same index. */
while ($child->firstChild) {
$element->insertBefore($child->firstChild,
$child);
}
$element->removeChild($child);
/* do not increment $i: the next child to inspect
has shifted into the current position. */
continue;
}
if (!in_array($tag, self::ALLOWED_TAGS, true)) {
$element->removeChild($child);
/* do not increment $i: the next sibling has
shifted into the current position. */
continue;
}
self::cleanElement($child, $block_remote_images);
self::cleanAttributes($child, $tag,
$block_remote_images);
$i++;
}
}
/**
* Strips every attribute on an allowed element that is not
* also explicitly allowed for its tag (or globally). Also
* filters URL-bearing attributes (href, src) through
* sanitizeUrl so dangerous schemes (javascript:, data:, vbs:)
* are dropped. Every attribute whose name begins with "on"
* is dropped unconditionally as an event handler.
*
* When $block_remote_images is true and the element is an
* img with an http(s) src, the src is left untouched but
* loading="lazy" and a mail-blocked-image class are added,
* so the browser defers fetching the (now hidden) image
* until the reader reveals it. The caller provides a "load
* remote images" affordance that removes the class.
*
* @param \DOMElement $element the element to clean
* @param string $tag the lowercased tag name
* @param bool $block_remote_images whether to mark remote
* images for deferred loading
*/
private static function cleanAttributes($element, $tag,
$block_remote_images)
{
$allowed_global = self::ALLOWED_ATTRS['*'] ?? [];
$allowed_specific = self::ALLOWED_ATTRS[$tag] ?? [];
$allowed = array_merge($allowed_global, $allowed_specific);
$attributes = iterator_to_array($element->attributes);
foreach ($attributes as $attr) {
$name = strtolower($attr->name);
if (str_starts_with($name, 'on')) {
$element->removeAttribute($attr->name);
continue;
}
if (!in_array($name, $allowed, true)) {
$element->removeAttribute($attr->name);
continue;
}
if ($name === 'style') {
$clean_style = self::sanitizeStyle($attr->value);
if ($clean_style === '') {
$element->removeAttribute($attr->name);
} else {
$element->setAttribute($attr->name,
$clean_style);
}
continue;
}
if ($name === 'href' || $name === 'src') {
$clean_url = self::sanitizeUrl($attr->value);
if ($clean_url === null) {
$element->removeAttribute($attr->name);
continue;
}
if ($clean_url !== $attr->value) {
$element->setAttribute($attr->name, $clean_url);
}
}
}
if ($block_remote_images && $tag === 'img') {
$url = $element->getAttribute('src');
if (preg_match('#^https?:#i', $url)) {
$element->setAttribute('loading', 'lazy');
$element->setAttribute('class',
'mail-blocked-image');
/* drop any inline display/visibility the message
set on the image: left in place it would
override the mail-blocked-image rule that hides
it, and a shown blocked image is a fetched one,
defeating the block. */
$style = $element->getAttribute('style');
if ($style !== '') {
$kept = self::sanitizeStyle($style,
['display', 'visibility']);
if ($kept === '') {
$element->removeAttribute('style');
} else {
$element->setAttribute('style', $kept);
}
}
}
}
}
/**
* Returns a sanitised version of a URL, or null when the URL
* should be dropped entirely. Schemes other than http, https,
* and mailto are rejected outright (in particular javascript:
* and data: are rejected, both of which can carry script).
* A URL without a scheme (relative path, fragment anchor) is
* passed through unchanged. Whitespace and control characters
* are stripped from the front before scheme detection so a
* value like " java\tscript:..." cannot sneak past via
* tab-insertion.
*
* @param string $url the raw URL value
* @return string|null cleaned URL, or null to drop
*/
private static function sanitizeUrl($url)
{
/* strip control characters and ASCII whitespace that can
otherwise hide a scheme prefix; preserve the rest of
the URL byte-exactly. */
$cleaned = preg_replace('/[\x00-\x20]+/', '', $url);
if ($cleaned === '') {
return null;
}
/* no colon = no scheme = relative URL = safe. */
if (strpos($cleaned, ':') === false) {
return $url;
}
/* a fragment-only URL (starts with #) also has no
scheme even when colons appear later. */
if ($cleaned[0] === '#') {
return $url;
}
$parts = explode(':', $cleaned, 2);
$scheme = strtolower($parts[0]);
if (in_array($scheme, self::ALLOWED_SCHEMES, true)) {
return $url;
}
return null;
}
/**
* Filters an inline style attribute down to a safe subset.
* Each semicolon-separated declaration is kept only when its
* property is on the safe-property allowlist, its value holds
* none of the hazard substrings (url(, expression(, and so
* on), and -- for width -- the value is a percentage or auto
* rather than a fixed length that would overflow a narrow
* pane. A caller may name extra properties to exclude on top
* of the allowlist; a blocked image excludes display and
* visibility so the message cannot un-hide it.
*
* @param string $style the raw style attribute value
* @param array $exclude property names to drop even when they
* are otherwise on the allowlist
* @return string the kept declarations joined by "; ", or the
* empty string when nothing is kept
*/
private static function sanitizeStyle($style, $exclude = [])
{
$safe = [];
foreach (explode(';', $style) as $declaration) {
$colon = strpos($declaration, ':');
if ($colon === false) {
continue;
}
$property = strtolower(trim(substr($declaration, 0,
$colon)));
$value = trim(substr($declaration, $colon + 1));
if ($property === '' || $value === '') {
continue;
}
if (!in_array($property, self::SAFE_STYLE_PROPERTIES,
true)) {
continue;
}
if (in_array($property, $exclude, true)) {
continue;
}
$lower_value = strtolower($value);
$unsafe = false;
foreach (self::STYLE_VALUE_HAZARDS as $hazard) {
if (strpos($lower_value, $hazard) !== false) {
$unsafe = true;
break;
}
}
if ($unsafe) {
continue;
}
/* a fixed-length width is the usual reason a message
overflows a narrow pane, so width is kept only as a
percentage or auto; max-width is left alone since it
only caps a width, never forces one. */
if ($property === 'width' &&
!preg_match('/^(auto|\d+(\.\d+)?%)$/', $value)) {
continue;
}
$safe[] = $property . ': ' . $value;
}
return implode('; ', $safe);
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software