feat(adapter-wp): HTML 白名单清洗与差异收集
sanitize-html@^2（MIT）白名单清洗 + onOpenTag 观察钩子按文档序收集 SanitizeDiff[] （镜像判定从 SANITIZE_CONFIG 单源推导；仪表化与清洗输出字节等价，测试钉死）。 白名单决策冻结：h1/布局标签/内联样式/iframe 拒绝（diff 留痕），外链 img 含 1x1 追踪像素本切片保留（远程依赖报告归 Task 6，路径重写归阶段 3）。 测试 184→204。 Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
浅念
@@ -2,3 +2,4 @@ export * from './limits.js'
|
||||
export * from './parse/php-unserialize.js'
|
||||
export * from './parse/wxr-stream.js'
|
||||
export * from './map/item-to-row.js'
|
||||
export * from './sanitize/html.js'
|
||||
|
||||
@@ -0,0 +1,263 @@
|
||||
// WordPress 正文 HTML 白名单清洗（Plan 2 Task 5，ADR-009）：清洗本体交 sanitize-html
|
||||
// （锁 ^2，MIT），本模块只做两件事——集中导出白名单配置 {@link SANITIZE_CONFIG}，
|
||||
// 与"清洗 + 差异收集"纯函数 {@link sanitizeBodyHtml}。原文永远保留在 Source Snapshot
|
||||
// 是调用方的职责（ADR-009），本模块不碰存储；白名单升级后可对原文重跑本函数。
|
||||
//
|
||||
// 差异收集方案取舍（选定 onOpenTag 观察钩子，JSDoc 钉死）：
|
||||
// - sanitize-html 无原生"移除回调"。候选方案：
|
||||
// a) onOpenTag(name, attribs)——官方类型支持的观察钩子，对**每个**开标签事件触发
|
||||
// （含未批准标签），携带**未过滤**的原始属性表；纯观察、零输出影响（测试钉死
|
||||
// 与无仪表化运行的字节等价）。
|
||||
// b) transformTags——同样先于白名单判定触发，但具变换语义（须原样回显
|
||||
// {tagName, attribs}），仪表化借道变换机制过重。
|
||||
// c) exclusiveFilter——只见"存活"元素（关闭时回调、属性已过滤），看不到移除。
|
||||
// d) before/after 字符串对比——等价变形（属性重排序/自闭合规范化/实体转义）
|
||||
// 制造假差异，不可靠。
|
||||
// e) 正则预扫描——非 tokenizer 精度（注释/引号内 '>'/大小式变形），仅可作为
|
||||
// 下策。onOpenTag 复用 sanitize-html 自身解析器（htmlparser2）的事件流，
|
||||
// 精度与清洗本体同源，故选 a。
|
||||
// - 镜像逻辑（判断"什么会被拒"）从 SANITIZE_CONFIG 单源推导，不另立策略表：
|
||||
// 标签 ∈ allowedTags？属性 ∈ allowedAttributes[tag] ∪ allowedAttributes['*']？
|
||||
// URL 属性（allowedSchemesAppliedToAttributes）协议 ∈ allowedSchemes
|
||||
// （含 allowedSchemesByTag 覆盖与协议相对 URL 规则，语义镜像 launder.naughtyHref）。
|
||||
// - 不镜像的清洗路径（ exotic，报告中不体现；清洗本体不受影响）：
|
||||
// 属性名合法性校验、空值非布尔属性删除、meta refresh content、SVG animate 名单、
|
||||
// allowedClasses 过滤、srcset 部分候选重写（仅"全部候选被拒→整属性删除"记账，
|
||||
// 候选切分为近似逗号分割）、空 srcset 删除。
|
||||
// - 记账粒度：按**白名单拒绝的开标签事件**逐次记录（文档序；属性按声明序）——
|
||||
// 不按"最终 DOM 差异"去重：discard 剥壳语义下未批准容器的子内容会被解包保留，
|
||||
// 其属性过滤真实发生，同样值得留痕；宁多报不漏报（审计定位用途）。
|
||||
// 顺序确定 → 同输入必得同 diffs（纯函数，无共享状态，测试钉死）。
|
||||
//
|
||||
// 白名单范围决策（冻结；改动须评审，测试钉死值域）：
|
||||
// - h1 不入白名单：标题层级归主题层（文章标题由主题渲染 h1），正文从 h2 起；
|
||||
// 出现 h1 会进 diff（removed-tag），文本按 discard 语义保留。
|
||||
// - 布局语义标签（section/article/header/footer/nav/aside/main）不入白名单：
|
||||
// discard 剥壳保留子内容，布局由阶段 3 主题层重建，不透传源站布局。
|
||||
// - script/style/iframe/form/svg/math 等一律拒绝；iframe 无宿主白名单通道——
|
||||
// "allowIframe: false"的等价物就是 allowedTags 缺席（本库无此独立开关）。
|
||||
// - style 属性与 <style> 标签均拒绝（ADR-009：内联样式是风险面，清洗后进产出的
|
||||
// 内容不得携带 CSS；未来若放开须走 allowedStyles 显式子集评审）。
|
||||
// - class/id 透传：WP 对齐类（alignleft 等）与锚点依赖之；class 值是惰性文本，
|
||||
// 安全边界在标签/属性白名单，不 class 名单（阶段 3 主题自行取舍是否消费）。
|
||||
// - **追踪像素策略（本切片钉死）**：外链 <img>（含 1x1 追踪像素形态）一律保留——
|
||||
// 移除判定只看白名单（script/事件属性/危险协议/未批准标签），不按尺寸/域名猜测
|
||||
// 意图。外链资源清单属 Task 6 的"远程依赖报告"范畴，路径重写（含媒体本地化）属
|
||||
// 阶段 3；本模块不越权。
|
||||
|
||||
import sanitizeHtml, { type Attributes, type IOptions } from 'sanitize-html'
|
||||
|
||||
/** 单条清洗差异：一次被白名单拒绝的标签/属性出现（审计与报告的最小记账单元） */
|
||||
export interface SanitizeDiff {
|
||||
/** 'removed-tag'：标签未批准（属性不重复记账）；'removed-attr'：标签保留但属性被拒 */
|
||||
type: 'removed-tag' | 'removed-attr'
|
||||
/** 小写标签名（htmlparser2 归一） */
|
||||
tag: string
|
||||
/** 仅 'removed-attr'：被拒属性名（小写）。'removed-tag' 时无此键 */
|
||||
attr?: string
|
||||
/** 被移除内容的重构摘要：removed-tag=开标签重构 `<tag a="v">`；removed-attr=属性序列化 `a="v"`；控制字符已转义，截前 80 字符 */
|
||||
excerpt: string
|
||||
}
|
||||
|
||||
/** sanitizeBodyHtml 返回：清洗后 HTML + 差异清单（文档序） */
|
||||
export interface SanitizeResult {
|
||||
html: string
|
||||
diffs: SanitizeDiff[]
|
||||
}
|
||||
|
||||
/**
|
||||
* 白名单清洗配置（集中导出，后续阶段可复用于 preview CSP 对齐；冻结浅层）。
|
||||
* 镜像判定（diff 收集）与清洗本体共用本配置——单源，改这里两边同步。
|
||||
* allowedSchemesAppliedToAttributes 显式钉死 ['href','src','cite']（本白名单内
|
||||
* 仅这三类 URL 属性；显式化使镜像判定不依赖库默认值）。
|
||||
*/
|
||||
export const SANITIZE_CONFIG: Readonly<IOptions> = Object.freeze({
|
||||
// 编辑性内容标签（WP 正文实况：块编辑器的 figure/div/span、表格、列表、引用、
|
||||
// 代码、详情折叠等）；h1/布局标签/style/iframe 的排除理由见模块头
|
||||
allowedTags: [
|
||||
'a', 'abbr', 'b', 'blockquote', 'br', 'caption', 'cite', 'code', 'col', 'colgroup',
|
||||
'dd', 'del', 'details', 'div', 'dl', 'dt', 'em', 'figcaption', 'figure', 'h2',
|
||||
'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'img', 'ins', 'kbd', 'li',
|
||||
'mark', 'ol', 'p', 'pre', 'q', 's', 'samp', 'small', 'span', 'strong',
|
||||
'sub', 'summary', 'sup', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'time',
|
||||
'tr', 'u', 'ul', 'var',
|
||||
],
|
||||
allowedAttributes: {
|
||||
'*': ['class', 'dir', 'id', 'lang', 'title'],
|
||||
a: ['href', 'name', 'rel', 'target'],
|
||||
img: ['alt', 'decoding', 'height', 'loading', 'sizes', 'src', 'srcset', 'width'],
|
||||
blockquote: ['cite'],
|
||||
col: ['span'],
|
||||
colgroup: ['span'],
|
||||
del: ['cite', 'datetime'],
|
||||
ins: ['cite', 'datetime'],
|
||||
li: ['value'],
|
||||
ol: ['reversed', 'start', 'type'],
|
||||
q: ['cite'],
|
||||
td: ['colspan', 'headers', 'rowspan', 'scope'],
|
||||
th: ['abbr', 'colspan', 'headers', 'rowspan', 'scope'],
|
||||
time: ['datetime'],
|
||||
details: ['open'],
|
||||
},
|
||||
// 协议白名单：常规 Web + 联系方式（mailto/tel，WP 站点 CTA 常见）；
|
||||
// data:/javascript:/vbscript: 等一律拒绝（data: 图片走私亦拒绝，进 diff）
|
||||
allowedSchemes: ['http', 'https', 'mailto', 'tel'],
|
||||
// 协议相对 URL（//cdn.example/x）放行：WP 混合协议遗留常见，浏览器按页面协议解析
|
||||
allowProtocolRelative: true,
|
||||
// URL 属性名单见 JSDoc；其余配置走库默认（discard 剥壳、nonTextTags 连内容删）
|
||||
allowedSchemesAppliedToAttributes: ['href', 'src', 'cite'],
|
||||
})
|
||||
|
||||
/** excerpt 上限（字符）：审计摘要够定位即可，控制报告体积 */
|
||||
const EXCERPT_MAX = 80
|
||||
|
||||
// ---- 镜像判定的派生索引（SANITIZE_CONFIG 冻结 → 模块级一次派生，纯常量视图）----
|
||||
|
||||
// allowedTags 的 false 形态（全拒绝）语义上等于空集——镜像统一为空 Set
|
||||
const TAGS_CFG = SANITIZE_CONFIG.allowedTags
|
||||
const ALLOWED_TAGS: ReadonlySet<string> = new Set(
|
||||
TAGS_CFG === false || TAGS_CFG === undefined ? [] : TAGS_CFG,
|
||||
)
|
||||
|
||||
const ALLOWED_ATTRS = new Map<string, ReadonlySet<string>>()
|
||||
{
|
||||
const configured = SANITIZE_CONFIG.allowedAttributes
|
||||
if (configured !== false && configured !== undefined) {
|
||||
for (const [tag, attrs] of Object.entries(configured)) {
|
||||
// AllowedAttribute 允许 {name, values} 受限值形态；本配置只用字符串形态，
|
||||
// 镜像只认字符串（受限值形态若未来启用，须同步扩展此处）
|
||||
ALLOWED_ATTRS.set(
|
||||
tag,
|
||||
new Set(attrs.filter((a): a is string => typeof a === 'string')),
|
||||
)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const EMPTY_ATTRS: ReadonlySet<string> = new Set()
|
||||
|
||||
const SCHEME_ATTRS: ReadonlySet<string> = new Set(
|
||||
SANITIZE_CONFIG.allowedSchemesAppliedToAttributes ?? ['href', 'src', 'cite'],
|
||||
)
|
||||
|
||||
// 协议表归一小写（launder 以小写比较 scheme；配置值大小写不敏感）。
|
||||
// boolean 形态（false=不过滤）不参与镜像——本配置为 string[]，测试钉死
|
||||
const SCHEMES_CFG = SANITIZE_CONFIG.allowedSchemes
|
||||
const ALLOWED_SCHEMES: readonly string[] | undefined = Array.isArray(SCHEMES_CFG)
|
||||
? SCHEMES_CFG.map((s: string) => s.toLowerCase())
|
||||
: undefined
|
||||
|
||||
const SCHEMES_BY_TAG = new Map<string, readonly string[]>()
|
||||
{
|
||||
const byTag = SANITIZE_CONFIG.allowedSchemesByTag
|
||||
if (byTag !== false && byTag !== undefined) {
|
||||
for (const [tag, schemes] of Object.entries(byTag)) {
|
||||
SCHEMES_BY_TAG.set(tag, schemes.map((s: string) => s.toLowerCase()))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const ALLOW_PROTOCOL_RELATIVE = SANITIZE_CONFIG.allowProtocolRelative ?? true
|
||||
|
||||
/**
|
||||
* launder.naughtyHref 的语义镜像（sanitize-html 2.18 经 launder 判定 URL 属性）：
|
||||
* 清理（剥 \x00-\x20 与 HTML 注释——浏览器忽略它们，常用于走私 scheme）后取
|
||||
* scheme 前缀；无 scheme 时仅协议相对 URL 受 allowProtocolRelative 约束。
|
||||
* 镜像而非复用（launder 未导出公开契约）：若库升级判定变化，测试对照
|
||||
* （仪表化等价测试 + 协议用例）会暴露漂移。
|
||||
*/
|
||||
function isNaughtyUrl(rawUrl: string, allowedSchemes: readonly string[]): boolean {
|
||||
// 浏览器会忽略 URL 中的控制字符（\x00-\x20，常见 scheme 走私手法，见 OWASP
|
||||
// XSS Filter Evasion Cheat Sheet#Embedded tab）——控制字符正是本清洗的目标，豁免
|
||||
// eslint-disable-next-line no-control-regex
|
||||
let href = rawUrl.replace(/[\x00-\x20]+/g, '')
|
||||
for (;;) {
|
||||
const start = href.indexOf('<!--')
|
||||
if (start === -1) break
|
||||
const end = href.indexOf('-->', start + 4)
|
||||
if (end === -1) break
|
||||
href = href.slice(0, start) + href.slice(end + 3)
|
||||
}
|
||||
const scheme = href.match(/^([a-zA-Z][a-zA-Z0-9.\-+]*):/)?.[1]
|
||||
if (scheme === undefined) {
|
||||
if (/^[/\\]{2}/.test(href)) return !ALLOW_PROTOCOL_RELATIVE
|
||||
return false
|
||||
}
|
||||
return !allowedSchemes.includes(scheme.toLowerCase())
|
||||
}
|
||||
|
||||
function schemesFor(tag: string): readonly string[] {
|
||||
return SCHEMES_BY_TAG.get(tag) ?? ALLOWED_SCHEMES ?? []
|
||||
}
|
||||
|
||||
/** 控制字符（C0 + DEL）→ \uXXXX 转义文本（摘要在 JSON/日志里可见可 grep） */
|
||||
function escapeControlChars(text: string): string {
|
||||
// 转义控制字符是本函数职责本身，豁免（同上：字符类里写控制字符是有意为之）
|
||||
// eslint-disable-next-line no-control-regex
|
||||
return text.replace(/[\x00-\x1f\x7f]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`)
|
||||
}
|
||||
|
||||
function makeExcerpt(raw: string): string {
|
||||
return escapeControlChars(raw).slice(0, EXCERPT_MAX)
|
||||
}
|
||||
|
||||
/** 开标签重构（属性原值经 JSON.stringify 序列化——引号/反斜杠/控制字符一并转义） */
|
||||
function openingTagMarkup(tag: string, attribs: Attributes): string {
|
||||
let markup = `<${tag}`
|
||||
for (const [name, value] of Object.entries(attribs)) {
|
||||
markup += ` ${name}=${JSON.stringify(value)}`
|
||||
}
|
||||
return `${markup}>`
|
||||
}
|
||||
|
||||
/**
|
||||
* 单个开标签事件的拒绝记账（onOpenTag 回调体）：
|
||||
* 标签被拒 → 只记 removed-tag（其属性随标签消失，不重复记账）；
|
||||
* 标签放行 → 逐属性记（未批准 / URL 协议被拒 / srcset 全候选被拒）。
|
||||
*/
|
||||
function recordRejections(diffs: SanitizeDiff[], tag: string, attribs: Attributes): void {
|
||||
if (!ALLOWED_TAGS.has(tag)) {
|
||||
diffs.push({ type: 'removed-tag', tag, excerpt: makeExcerpt(openingTagMarkup(tag, attribs)) })
|
||||
return
|
||||
}
|
||||
const tagAttrs = ALLOWED_ATTRS.get(tag) ?? EMPTY_ATTRS
|
||||
const starAttrs = ALLOWED_ATTRS.get('*') ?? EMPTY_ATTRS
|
||||
const schemes = schemesFor(tag)
|
||||
for (const [attr, value] of Object.entries(attribs)) {
|
||||
const excerpt = makeExcerpt(`${attr}=${JSON.stringify(value)}`)
|
||||
if (!tagAttrs.has(attr) && !starAttrs.has(attr)) {
|
||||
diffs.push({ type: 'removed-attr', tag, attr, excerpt })
|
||||
continue
|
||||
}
|
||||
if (SCHEME_ATTRS.has(attr) && isNaughtyUrl(value, schemes)) {
|
||||
diffs.push({ type: 'removed-attr', tag, attr, excerpt })
|
||||
continue
|
||||
}
|
||||
// srcset/imagesrcset 逐候选协议过滤的镜像：全部候选被拒时库会整属性删除（近似
|
||||
// 逗号切分，仅 diff 判定用）；部分被拒仅重写不删除，不记账
|
||||
if (attr === 'srcset' || attr === 'imagesrcset') {
|
||||
const candidates = value.split(',').map((part) => part.trim().split(/\s+/)[0] ?? '')
|
||||
if (candidates.length > 0 && candidates.every((url) => url !== '' && isNaughtyUrl(url, schemes))) {
|
||||
diffs.push({ type: 'removed-attr', tag, attr, excerpt })
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* WordPress 正文 HTML 白名单清洗（纯函数）：清洗本体 = sanitize-html + SANITIZE_CONFIG；
|
||||
* 差异 = onOpenTag 观察钩子按文档序收集（方案取舍与记账粒度见模块头）。
|
||||
* 同输入必得同输出与同 diffs；每调用独立 diffs 数组，调用方持有即可安全归档。
|
||||
*/
|
||||
export function sanitizeBodyHtml(html: string): SanitizeResult {
|
||||
const diffs: SanitizeDiff[] = []
|
||||
// 展开副本承载仅本次调用的仪表化钩子（SANITIZE_CONFIG 冻结，库的默认值归一
|
||||
// 写入副本，不触碰导出常量）；onOpenTag 为纯观察——输出与无钩子运行字节一致（测试钉死）
|
||||
const cleaned = sanitizeHtml(html, {
|
||||
...SANITIZE_CONFIG,
|
||||
onOpenTag: (name, attribs) => {
|
||||
recordRejections(diffs, name, attribs)
|
||||
},
|
||||
})
|
||||
return { html: cleaned, diffs }
|
||||
}
|
||||
Reference in New Issue
Block a user