《互联网产品的客户端架构·内容、社交与实时互动》3.2 渲染边界与 sanitize：谁能写 HTML

// file: src/render/sanitize.ts
// tier: L1
// verify: node --test test/render/sanitize.test.ts
import type { InlineMark, InlineSpan, RichBlock, RichDocument } from "./blocks.ts";

export type TrustLevel = "author" | "ops" | "embed";
export type UrlKind = "link" | "image" | "embed";

export interface RenderPolicy {
  trust: TrustLevel;
  allowedTags: readonly string[];
  allowedAttributes: Readonly<Record<string, readonly string[]>>;
  embedHosts: readonly string[];
  forceSandbox: string | null;
}

export interface SanitizeReport {
  html: string;
  removedTags: string[];
  removedAttributes: string[];
  blockedUrls: string[];
}

const AUTHOR_ATTRIBUTES: Record<string, readonly string[]> = {
  a: ["href", "title"], img: ["src", "alt", "width", "height"],
};

const OPS_ATTRIBUTES: Record<string, readonly string[]> = {
  ...AUTHOR_ATTRIBUTES, div: ["class"], span: ["class"], figure: ["class"], figcaption: ["class"],
  table: ["class"], th: ["colspan", "rowspan", "scope"], td: ["colspan", "rowspan"],
};

const AUTHOR_TAGS = [
  "p", "br", "strong", "b", "em", "i", "code", "pre",
  "blockquote", "ul", "ol", "li", "a", "img", "h2", "h3",
];

const OPS_TAGS = [
  ...AUTHOR_TAGS, "div", "span", "figure", "figcaption", "hr",
  "table", "thead", "tbody", "tr", "th", "td",
];

export const POLICIES: Record<TrustLevel, RenderPolicy> = {
  author: {
    trust: "author", allowedTags: AUTHOR_TAGS, allowedAttributes: AUTHOR_ATTRIBUTES,
    embedHosts: [], forceSandbox: null,
  },
  ops: {
    trust: "ops", allowedTags: OPS_TAGS, allowedAttributes: OPS_ATTRIBUTES,
    embedHosts: [], forceSandbox: null,
  },
  embed: {
    trust: "embed", allowedTags: ["iframe", "p", "a"],
    allowedAttributes: {
      iframe: ["src", "title", "width", "height", "allowfullscreen"],
      a: ["href", "title"],
    },
    embedHosts: ["player.example.com", "www.youtube-nocookie.com"],
    forceSandbox: "allow-scripts allow-presentation allow-popups",
  },
};

const VOID_TAGS = new Set(["br", "hr", "img"]);
const RAW_TEXT_DROP = new Set(["script", "style", "template", "noscript", "object", "embed", "form", "svg", "math"]);
const URL_ATTRIBUTES = new Set(["href", "src", "poster", "cite"]);
const TOKEN_PATTERN = /<!--[\s\S]*?-->|<\/?[a-zA-Z][^>]*>/g;
const ATTRIBUTE_PATTERN = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
const NAMED_ENTITIES: Record<string, string> = {
  colon: ":", tab: "\t", newline: "\n", amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", "#39": "'",
};

export function escapeHtml(value: string): string {
  return value.replace(/&(?!(?:[a-zA-Z][a-zA-Z0-9]*|#\d+|#x[0-9a-f]+);)/gi, "&amp;")
    .replaceAll("<", "&lt;").replaceAll(">", "&gt;")
    .replaceAll('"', "&quot;").replaceAll("'", "&#39;");
}

function codePoint(value: number): string {
  return Number.isFinite(value) && value >= 0 && value <= 0x10ffff ? String.fromCodePoint(value) : "";
}

function decodeEntities(value: string): string {
  return value
    .replace(/&#x([0-9a-f]+);?/gi, (_, hex: string) => codePoint(parseInt(hex, 16)))
    .replace(/&#(\d+);?/g, (_, dec: string) => codePoint(parseInt(dec, 10)))
    .replace(/&([a-z]+|#39);/gi, (_, name: string) => NAMED_ENTITIES[name.toLowerCase()] ?? "");
}

export function isSafeUrl(raw: string, kind: UrlKind): boolean {
  const compact = decodeEntities(raw).replace(/[\u0000- \u007f]+/g, "").toLowerCase();
  if (compact === "") return false;
  const scheme = compact.match(/^([a-z][a-z0-9+.-]*):/);
  if (!scheme) return kind !== "embed";
  const name = scheme[1];
  if (kind === "embed") return name === "https";
  if (kind === "image") return name === "http" || name === "https";
  return name === "http" || name === "https" || name === "mailto";
}

export function embedHost(raw: string): string | null {
  try {
    const url = new URL(decodeEntities(raw).trim());
    return url.protocol === "https:" ? url.hostname.toLowerCase() : null;
  } catch {
    return null;
  }
}

interface ParsedTag {
  closing: boolean; name: string; selfClosing: boolean; attributes: Array<[string, string]>;
}

function parseTag(token: string): ParsedTag | null {
  const inner = token.slice(1, -1);
  const closing = inner.startsWith("/");
  const body = closing ? inner.slice(1) : inner;
  const selfClosing = /\/\s*$/.test(body);
  const match = body.replace(/\/\s*$/, "").match(/^\s*([a-zA-Z][a-zA-Z0-9:-]*)([\s\S]*)$/);
  if (!match) return null;
  ATTRIBUTE_PATTERN.lastIndex = 0;
  const attributes = [...match[2].matchAll(ATTRIBUTE_PATTERN)]
    .map((attr): [string, string] => [attr[1].toLowerCase(), attr[2] ?? attr[3] ?? attr[4] ?? ""]);
  return { closing, name: match[1].toLowerCase(), selfClosing, attributes };
}

function findRawTextEnd(input: string, name: string, from: number): number {
  const pattern = new RegExp(`</${name}\\s*[^>]*>`, "ig");
  pattern.lastIndex = from;
  return pattern.exec(input) ? pattern.lastIndex : input.length;
}

function attributeAllowed(policy: RenderPolicy, tag: string, attribute: string): boolean {
  return (policy.allowedAttributes[tag] ?? []).includes(attribute) && !attribute.startsWith("on");
}

function safeAttributes(
  policy: RenderPolicy, tag: string, attributes: Array<[string, string]>, report: SanitizeReport,
): string[] {
  const output: string[] = [];
  for (const [name, value] of attributes) {
    if (!attributeAllowed(policy, tag, name)) {
      report.removedAttributes.push(name);
      continue;
    }
    if (URL_ATTRIBUTES.has(name)) {
      const kind: UrlKind = tag === "iframe" ? "embed" : name === "href" ? "link" : "image";
      if (!isSafeUrl(value, kind)) {
        report.blockedUrls.push(value);
        continue;
      }
    }
    output.push(name === "allowfullscreen" ? "allowfullscreen" : `${name}="${escapeHtml(value)}"`);
  }
  if (tag === "iframe" && policy.forceSandbox) output.push(`sandbox="${policy.forceSandbox}"`);
  return output;
}

export function sanitizeHtml(input: string, trust: TrustLevel): SanitizeReport {
  const policy = POLICIES[trust];
  const report: SanitizeReport = { html: "", removedTags: [], removedAttributes: [], blockedUrls: [] };
  let cursor = 0;
  let token: RegExpExecArray | null;
  TOKEN_PATTERN.lastIndex = 0;
  while ((token = TOKEN_PATTERN.exec(input)) !== null) {
    report.html += escapeHtml(input.slice(cursor, token.index));
    cursor = TOKEN_PATTERN.lastIndex;
    if (token[0].startsWith("<!--")) continue;
    const parsed = parseTag(token[0]);
    if (!parsed) continue;
    const { closing, name, selfClosing, attributes } = parsed;
    if (closing) {
      if (policy.allowedTags.includes(name) && !VOID_TAGS.has(name)) report.html += `</${name}>`;
      else report.removedTags.push(name);
      continue;
    }
    if (RAW_TEXT_DROP.has(name) || !policy.allowedTags.includes(name)) {
      report.removedTags.push(name);
      if (RAW_TEXT_DROP.has(name) && !selfClosing) {
        cursor = findRawTextEnd(input, name, TOKEN_PATTERN.lastIndex);
        TOKEN_PATTERN.lastIndex = cursor;
      }
      continue;
    }
    if (name === "iframe") {
      const src = attributes.find(([key]) => key === "src")?.[1] ?? "";
      const host = embedHost(src);
      if (!host || !policy.embedHosts.includes(host)) {
        report.removedTags.push(name);
        if (src !== "") report.blockedUrls.push(src);
        if (!selfClosing) {
          cursor = findRawTextEnd(input, name, TOKEN_PATTERN.lastIndex);
          TOKEN_PATTERN.lastIndex = cursor;
        }
        continue;
      }
    }
    const safe = safeAttributes(policy, name, attributes, report);
    const tail = VOID_TAGS.has(name) || selfClosing ? " /" : "";
    report.html += `<${name}${safe.length ? ` ${safe.join(" ")}` : ""}${tail}>`;
  }
  report.html += escapeHtml(input.slice(cursor));
  return report;
}

function renderSpans(spans: InlineSpan[], report: SanitizeReport): string {
  return spans.map((item) => {
    let output = escapeHtml(item.text);
    if (item.marks.some((mark) => mark.kind === "code")) output = `<code>${output}</code>`;
    if (item.marks.some((mark) => mark.kind === "italic")) output = `<em>${output}</em>`;
    if (item.marks.some((mark) => mark.kind === "bold")) output = `<strong>${output}</strong>`;
    const link = item.marks.find((mark): mark is Extract<InlineMark, { kind: "link" }> => mark.kind === "link");
    if (link && isSafeUrl(link.href, "link")) {
      output = `<a href="${escapeHtml(link.href)}" rel="nofollow noopener noreferrer" target="_blank">${output}</a>`;
    } else if (link) {
      report.blockedUrls.push(link.href);
    }
    return output;
  }).join("");
}

function renderBlock(block: RichBlock, report: SanitizeReport): string {
  if (block.type === "paragraph") return `<p>${renderSpans(block.spans, report)}</p>`;
  if (block.type === "quote") {
    const footer = block.attribution ? `<footer>${escapeHtml(block.attribution)}</footer>` : "";
    return `<blockquote><p>${renderSpans(block.spans, report)}</p>${footer}</blockquote>`;
  }
  if (block.type === "image") {
    if (!isSafeUrl(block.src, "image")) {
      report.blockedUrls.push(block.src);
      return `<p>${escapeHtml(block.alt || "[图片已拦截]")}</p>`;
    }
    const size = `${block.width ? ` width="${block.width}"` : ""}${block.height ? ` height="${block.height}"` : ""}`;
    return `<img src="${escapeHtml(block.src)}" alt="${escapeHtml(block.alt)}"${size} loading="lazy" />`;
  }
  if (block.type === "video") {
    if (!isSafeUrl(block.src, "image")) { report.blockedUrls.push(block.src); return "<p>[视频已拦截]</p>"; }
    const poster = block.poster && isSafeUrl(block.poster, "image") ? ` poster="${escapeHtml(block.poster)}"` : "";
    return `<video src="${escapeHtml(block.src)}"${poster} controls preload="metadata"></video>`;
  }
  if (block.type === "code") {
    const language = /^[a-z0-9-]+$/i.test(block.language) ? block.language.toLowerCase() : "text";
    return `<pre><code class="language-${language}">${escapeHtml(block.code)}</code></pre>`;
  }
  report.removedTags.push(`unsupported:${block.originalType}`);
  return "";
}

export function renderStructured(document: RichDocument): SanitizeReport {
  const report: SanitizeReport = { html: "", removedTags: [], removedAttributes: [], blockedUrls: [] };
  report.html = document.blocks.map((block) => renderBlock(block, report)).join("");
  return report;
}

$ node --test test/render/sanitize.test.ts
✔ 脚本标签连同内容被丢弃，事件属性被移除 (2.164083ms)
✔ javascript 协议与实体编码绕过都被拦截 (0.611583ms)
✔ 白名单链接、图片与已有实体被原样保留 (0.150333ms)
✔ 运营配置允许 class，作者内容不允许 (0.165667ms)
✔ 第三方嵌入只接受白名单主机的 https iframe，并强制 sandbox (0.285833ms)
✔ 作者内容不能嵌入 iframe，未闭合脚本会吞掉剩余输入 (0.117959ms)
✔ URL 判定区分链接、图片与嵌入三种用途 (0.086292ms)
✔ 结构化渲染天然转义文本，并拦截坏 URL 与未知块 (0.258459ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 232.866958