MDN Web API 教程：深入理解 Trusted Types API 安全机制

什么是 Trusted Types API

Trusted Types API 是现代浏览器提供的一套安全防护机制，主要用于防范客户端跨站脚本攻击（XSS）。它通过强制开发者对输入内容进行安全处理，确保任何传递给危险API的数据都经过预定义的净化流程。

XSS 攻击与防御原理

XSS攻击通常发生在攻击者精心构造的数据被直接传递给浏览器执行API时。这些危险API被称为"注入点"(injection sinks)，主要分为三类：

1. HTML注入点：如innerHTML、document.write()等，能解析并执行HTML中的脚本
2. JavaScript注入点：如eval()、scriptElement.text等，直接执行JavaScript代码
3. JavaScript URL注入点：如scriptElement.src等，加载外部脚本

传统防御方式是手动对输入进行转义或净化，但这种方法容易遗漏。Trusted Types API 通过策略模式强制实施安全处理。

核心工作机制

1. 策略对象(TrustedTypePolicy)

开发者需要创建策略对象，定义不同类型输入的处理方法：

const policy = trustedTypes.createPolicy("sanitizePolicy", {
  createHTML: (input) => DOMPurify.sanitize(input), // HTML净化
  createScript: () => throw new Error("No scripts allowed"), // 禁止脚本
  createScriptURL: (url) => { /* URL白名单检查 */ }
});

2. 可信类型对象

策略对象会生成三种可信类型：

• TrustedHTML：安全HTML内容
• TrustedScript：安全JavaScript代码
• TrustedScriptURL：安全脚本URL

3. 内容安全策略(CSP)强制

通过CSP指令确保必须使用可信类型：

Content-Security-Policy: require-trusted-types-for 'script'

这样配置后，直接传递字符串给危险API会抛出TypeError。

实际应用示例

基本使用模式

// 1. 创建净化策略
const sanitizer = trustedTypes.createPolicy("htmlSanitizer", {
  createHTML: (html) => {
    // 使用DOMPurify等库进行净化
    return DOMPurify.sanitize(html);
  }
});

// 2. 处理用户输入
const userInput = "<img src=x onerror=alert(1)>";
const safeHTML = sanitizer.createHTML(userInput);

// 3. 安全使用
document.getElementById("content").innerHTML = safeHTML;

默认策略的妙用

过渡期可以使用默认策略记录未改造的代码：

trustedTypes.createPolicy("default", {
  createHTML(input) {
    console.warn("发现未改造的innerHTML使用:", new Error().stack);
    return input; // 生产环境应返回净化后的内容
  }
});

浏览器兼容性解决方案

对于不支持Trusted Types的浏览器，可以采用以下策略：

1. 完整polyfill方案

<script src="trusted-types.full.js"></script>
<script>
  // 正常使用Trusted Types API
</script>

2. 轻量级tinyfill方案

// 简单polyfill
if (typeof trustedTypes === "undefined") {
  trustedTypes = { createPolicy: (n, rules) => rules };
}

// 应用代码无需修改
const policy = trustedTypes.createPolicy("myPolicy", {
  createHTML: (s) => sanitize(s) // 始终返回字符串
});

最佳实践建议

1. 逐步迁移：先使用默认策略识别所有危险API调用，再逐个替换
2. 严格策略：生产环境策略应默认拒绝可疑输入
3. 组合防御：配合CSP的其他指令如script-src增强防护
4. 测试覆盖：确保所有用户输入路径都经过策略处理
5. 性能考量：复杂净化逻辑可能影响性能，需合理优化

高级应用场景

自定义净化逻辑

const customPolicy = trustedTypes.createPolicy("custom", {
  createHTML: (input) => {
    // 允许有限的HTML标签和属性
    const allowedTags = ["p", "span", "br"];
    const allowedAttrs = ["class", "style"];
    
    // 自定义净化实现...
    return safeHTML;
  }
});

与前端框架集成

现代框架如React、Vue等已内置XSS防护，但可以与Trusted Types结合：

// React示例
function SafeComponent({ html }) {
  const safeHTML = policy.createHTML(html);
  return <div dangerouslySetInnerHTML={{__html: safeHTML}} />;
}

Trusted Types API 通过强制性的安全策略，为Web应用提供了强有力的XSS防护机制。合理使用可以显著提升应用安全性，特别是在处理用户生成内容、富文本编辑等高风险场景下效果尤为明显。