render-safe.mjs

Functions

Imports

It imports render-allowlist.mjs, render-error.mjs, render-url.mjs. Imported by render-conformance.mjs, render-nomath.mjs.

Source

1// The second layer of the safe-HTML guarantee. render.mjs is safe by construction (no raw HTML pass-through, URL policy last, KaTeX
2// trust off); this scans the OUTPUT with a parser, not a regex, and refuses an element or attribute outside an allowlist. The
3// construction rests on options one edit could flip, so the scan is what notices when one has.
4//
5// The allowlist is DERIVED, not written: render-allowlist.mjs is regenerated from the conformance corpus by test/render-safe.test.mjs,
6// which fails both ways (a tag or attribute in the output but not in the list, and one in the list that never appears).
7
8import { parseFragment } from "parse5";
9
10import { DEFAULT_ALLOWLIST } from "./render-allowlist.mjs";
11import { ContentError } from "./render-error.mjs";
12import { isAllowedUrl } from "./render-url.mjs";
13
14/** Attributes whose value is a URL, whatever the element. */
15const URL_ATTRIBUTES = new Set([
16  "href",
17  "src",
18  "xlink:href",
19  "action",
20  "formaction",
21  "poster",
22  "data",
23  "background",
24  "cite",
25  "ping",
26]);
27
28/**
29 * The one form of `style` that may carry a url(): the pipeline's own low-quality image placeholder (render-nomath.mjs, rehypeImageSources).
30 * Anything else with a url() is refused.
31 */
32export const LQIP_STYLE = /^background-image:url\("data:image\/(?:webp|png|jpeg|avif|gif);base64,[A-Za-z0-9+/=]*"\)$/;
33
34/**
35 * The URLs in a srcset: each comma-separated candidate is a URL, then an optional descriptor.
36 *
37 * @param {string} value
38 * @returns {string[]}
39 */
40export function srcsetUrls(value) {
41  return value
42    .split(",")
43    .map((candidate) => candidate.trim().split(/\s+/)[0] ?? "")
44    .filter(Boolean);
45}
46
47/**
48 * @typedef {{ tags: ReadonlySet<string>, attributes: ReadonlySet<string> }} Allowlist
49 * `attributes` holds "tag attribute" pairs, one space between.
50 *
51 * @typedef {{ kind: string, tag: string, attribute?: string, detail?: string }} Violation
52 */
53
54/**
55 * @param {string} value
56 * @returns {boolean}
57 */
58function styleIsSafe(value) {
59  if (LQIP_STYLE.test(value)) return true;
60  // A CSS escape or comment can spell url( or expression( without writing it, so neither is allowed anywhere.
61  if (/[\\]|\/\*/.test(value)) return false;
62  return !/url\s*\(|expression\s*\(|@import|behavior\s*:|-moz-binding/i.test(value);
63}
64
65/**
66 * @param {import("parse5").DefaultTreeAdapterMap["parentNode"]} root
67 * @param {(node: any) => void} visitNode
68 */
69function walk(root, visitNode) {
70  /** @type {any[]} */
71  const stack = [root];
72  while (stack.length > 0) {
73    const node = stack.pop();
74    visitNode(node);
75    // <template> keeps its children under `content`.
76    if (node.content) stack.push(node.content);
77    for (const child of node.childNodes ?? []) stack.push(child);
78  }
79}
80
81/**
82 * Reads the output the way a browser would and reports what it finds. The counts say how much was read, so zero violations cannot
83 * mean zero read.
84 *
85 * @param {string} html
86 * @param {Allowlist} [allowlist]
87 * @returns {{ violations: Violation[], elements: number, attributes: number }}
88 */
89export function scanHtml(html, allowlist = DEFAULT_ALLOWLIST) {
90  /** @type {Violation[]} */
91  const violations = [];
92  let elements = 0;
93  let attributes = 0;
94
95  walk(parseFragment(html), (node) => {
96    if (node.nodeName === "#comment") {
97      violations.push({ kind: "comment", tag: "#comment" });
98      return;
99    }
100    if (!node.tagName) return;
101
102    elements += 1;
103    const tag = node.tagName;
104    if (!allowlist.tags.has(tag)) violations.push({ kind: "element", tag });
105
106    for (const { name, value } of node.attrs) {
107      attributes += 1;
108      if (/^on/i.test(name)) {
109        violations.push({ kind: "event-handler", tag, attribute: name });
110        continue;
111      }
112      if (!allowlist.attributes.has(`${tag} ${name}`)) {
113        violations.push({ kind: "attribute", tag, attribute: name });
114        continue;
115      }
116      if (URL_ATTRIBUTES.has(name.toLowerCase()) && !isAllowedUrl(value)) {
117        violations.push({ kind: "url", tag, attribute: name, detail: value.slice(0, 80) });
118      }
119      if (name.toLowerCase() === "srcset") {
120        for (const url of srcsetUrls(value)) {
121          if (!isAllowedUrl(url)) violations.push({ kind: "url", tag, attribute: name, detail: url.slice(0, 80) });
122        }
123      }
124      if (name === "style" && !styleIsSafe(value)) {
125        violations.push({ kind: "style", tag, attribute: name, detail: value.slice(0, 80) });
126      }
127    }
128  });
129
130  return { violations, elements, attributes };
131}
132
133/**
134 * Fails closed: throws, so a save path refuses the write instead of storing HTML it could not vouch for.
135 *
136 * @param {string} html
137 * @param {Allowlist} [allowlist]
138 */
139export function assertSafe(html, allowlist = DEFAULT_ALLOWLIST) {
140  const { violations } = scanHtml(html, allowlist);
141  if (violations.length === 0) return;
142  const shown = violations
143    .slice(0, 5)
144    .map((v) => `${v.kind} ${v.tag}${v.attribute ? ` ${v.attribute}` : ""}${v.detail ? ` (${v.detail})` : ""}`)
145    .join("; ");
146  throw new ContentError(
147    "(rendered output)",
148    `unsafe output refused: ${violations.length} violation${violations.length === 1 ? "" : "s"}: ${shown}`,
149  );
150}
151
152/**
153 * The tags and "tag attribute" pairs that appear in rendered output, for deriving the allowlist.
154 *
155 * @param {Iterable<string>} outputs rendered HTML fragments
156 * @returns {{ tags: string[], attributes: string[] }} sorted
157 */
158export function inventory(outputs) {
159  const tags = new Set();
160  const attributes = new Set();
161  for (const html of outputs) {
162    walk(parseFragment(html), (node) => {
163      if (!node.tagName) return;
164      tags.add(node.tagName);
165      for (const { name } of node.attrs) attributes.add(`${node.tagName} ${name}`);
166    });
167  }
168  return { tags: [...tags].sort(), attributes: [...attributes].sort() };
169}