Design an HTML sanitiser

/** Parser-agnostic tree. Build it from parse5 on the server or DOMParser / a <template> in the browser. */
export type HNode =
  | { kind: "text"; text: string }                                         // already entity-decoded
  | { kind: "el"; tag: string; attrs: [string, string][]; children: HNode[] }
  | { kind: "drop" };                                                      // comments, doctypes, foreign-namespace elements

export interface SanitizePolicy {
  tags: ReadonlySet<string>;                                  // kept as elements
  dropWithContent: ReadonlySet<string>;                       // removed with everything inside
  attrs: Readonly<Record<string, ReadonlySet<string>>>;       // per tag; "*" applies to all kept tags
  urlAttrs: Readonly<Record<string, ReadonlySet<string>>>;    // attribute -> allowed schemes
  maxDepth: number;
}

export interface Sanitizer { sanitize(html: string): string }

export const DEFAULT_POLICY: SanitizePolicy = {
  tags: new Set(["p", "br", "b", "strong", "i", "em", "u", "s", "code", "pre", "blockquote", "ul", "ol", "li",
    "a", "h2", "h3", "h4", "table", "thead", "tbody", "tr", "th", "td", "img", "span"]),
  dropWithContent: new Set(["script", "style", "template", "noscript", "iframe", "object", "embed", "svg", "math",
    "textarea", "title", "xmp", "noembed", "noframes", "plaintext", "select", "option"]),
  attrs: {
    "*": new Set(["title", "lang", "dir"]),
    a: new Set(["href"]),
    img: new Set(["src", "alt", "width", "height"]),
    td: new Set(["colspan", "rowspan"]),
    th: new Set(["colspan", "rowspan"]),
  },
  urlAttrs: { href: new Set(["http:", "https:", "mailto:"]), src: new Set(["http:", "https:"]) },
  maxDepth: 100,
};

const VOID = new Set(["br", "img"]);
const NUMERIC = new Set(["width", "height", "colspan", "rowspan"]);

/** Resolve against a dummy base with the WHATWG parser, exactly as a browser would, and read the scheme it sees. */
export function safeUrl(value: string, schemes: ReadonlySet<string>): string | null {
  let u: URL;
  try { u = new URL(value.trim(), "https://relative.invalid/"); } catch { return null; }
  return schemes.has(u.protocol) ? value.trim() : null;
}

function cleanAttrs(tag: string, attrs: readonly [string, string][], policy: SanitizePolicy): [string, string][] {
  const out: [string, string][] = [];
  const seen = new Set<string>();
  for (const [raw, value] of attrs) {
    const name = raw.toLowerCase();
    if (seen.has(name)) continue;                                  // first occurrence wins, as in the HTML parser
    seen.add(name);
    if (!policy.attrs["*"]?.has(name) && !policy.attrs[tag]?.has(name)) continue;
    const schemes = policy.urlAttrs[name];
    if (schemes) {
      const safe = safeUrl(value, schemes);
      if (safe !== null) out.push([name, safe]);
    } else if (!NUMERIC.has(name) || /^\d{1,4}$/.test(value)) {
      out.push([name, value]);
    }
  }
  if (tag === "a") out.push(["rel", "nofollow ugc noopener"]);
  return out;
}

export function sanitizeTree(nodes: readonly HNode[], policy: SanitizePolicy, depth = 0): HNode[] {
  if (depth > policy.maxDepth) return [];                          // pathological nesting: drop rather than recurse forever
  const out: HNode[] = [];
  for (const n of nodes) {
    if (n.kind === "drop") continue;
    if (n.kind === "text") { out.push(n); continue; }
    const tag = n.tag.toLowerCase();
    if (policy.dropWithContent.has(tag)) continue;
    const children = sanitizeTree(n.children, policy, depth + 1);
    if (!policy.tags.has(tag)) { out.push(...children); continue; }   // unknown but harmless: unwrap, keep the text
    out.push({ kind: "el", tag, attrs: cleanAttrs(tag, n.attrs, policy), children: VOID.has(tag) ? [] : children });
  }
  return out;
}

const escText = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/ /g, "&nbsp;");
const escAttr = (s: string) => escText(s).replace(/"/g, "&quot;");     // < and > escaped in attributes too: blunts mXSS

export function serialize(nodes: readonly HNode[]): string {
  let html = "";
  for (const n of nodes) {
    if (n.kind === "text") html += escText(n.text);
    else if (n.kind === "el") {
      html += "<" + n.tag + n.attrs.map(([k, v]) => " " + k + "=\"" + escAttr(v) + "\"").join("") + ">";
      if (!VOID.has(n.tag)) html += serialize(n.children) + "</" + n.tag + ">";
    }
  }
  return html;
}

import { parseFragment } from "parse5";

const HTML_NS = "http://www.w3.org/1999/xhtml";
interface P5 { nodeName: string; tagName?: string; namespaceURI?: string; attrs?: { name: string; value: string }[]; value?: string; childNodes?: P5[] }

function fromParse5(n: P5): HNode {
  if (n.nodeName === "#text") return { kind: "text", text: n.value ?? "" };
  if (!n.tagName || n.namespaceURI !== HTML_NS) return { kind: "drop" };   // comments, SVG and MathML subtrees
  return { kind: "el", tag: n.tagName, attrs: (n.attrs ?? []).map((a) => [a.name, a.value]), children: (n.childNodes ?? []).map(fromParse5) };
}

export function sanitize(html: string, policy: SanitizePolicy = DEFAULT_POLICY): string {
  const root = parseFragment(html) as unknown as P5;                         // same algorithm as browsers (WHATWG spec)
  return serialize(sanitizeTree((root.childNodes ?? []).map(fromParse5), policy));
}

import { describe, it, expect } from "vitest";

const corpus: [string, string][] = [
  ["<script>alert(1)</script>hi", "hi"],
  ["<img src=x onerror=alert(1)>", "<img src=\"x\">"],
  ["<a href=\"jav&#x09;ascript:alert(1)\">x</a>", "<a rel=\"nofollow ugc noopener\">x</a>"],
  ["<a href=\" JAVASCRIPT:alert(1)\">x</a>", "<a rel=\"nofollow ugc noopener\">x</a>"],
  ["<svg><script>alert(1)</script></svg>ok", "ok"],
  ["<div onclick=\"x()\"><b>bold</b></div>", "<b>bold</b>"],
  ["<p title=\"a&quot;><script>\">t</p>", "<p title=\"a&quot;&gt;&lt;script&gt;\">t</p>"],
  ["<img src=\"data:image/svg+xml;base64,PHN2Zz4=\">", "<img>"],
];

describe("sanitize", () => {
  it.each(corpus)("%s", (input, expected) => {
    expect(sanitize(input)).toBe(expected);
  });
  it("is stable on its own output", () => {
    for (const [input] of corpus) {
      const once = sanitize(input);
      expect(sanitize(once)).toBe(once);
    }
  });
});