sanitize-html

项目背景与战略目标

在Web后端开发、富文本编辑器内容存储、邮件系统渲染及API网关数据过滤等场景中，处理用户提交的HTML内容是高风险操作。未经清洗的HTML极易导致跨站脚本攻击（XSS），窃取用户Cookie或执行恶意代码。现有的HTML清洗库多基于动态语言（如JavaScript/Python），存在解析性能瓶颈、正则表达式回溯风险以及在高频并发下的内存安全问题。

本项目旨在利用仓颉编程语言（Cangjie Language）1.0.0+重构 sanitize-html，打造一款原生、极速、零漏洞的后端安全组件。

• 编译期内存安全：利用仓颉的所有权机制和借用检查，彻底杜绝HTML解析过程中的缓冲区溢出和Use-After-Free漏洞，从根源上消除内存型安全风险。

• 高并发清洗能力：依托仓颉轻量级线程模型，单节点可支撑百万级QPS的HTML清洗请求，满足高流量网关和实时内容审核需求。

• 确定性解析引擎：采用基于状态机的DOM解析器替代不安全的正则匹配，确保对畸形HTML的鲁棒性，防止ReDoS（正则拒绝服务）攻击。

• 强类型规则配置：利用仓颉的代数数据类型（ADT）定义清洗规则，确保配置的结构完整性，避免运行时因配置错误导致的安全绕过。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：单次清洗平均延迟 < 5ms (1KB文本)，吞吐量 > 50k QPS (8核机器)，内存峰值 < 2倍输入大小。

• 安全要求：默认开启最严格白名单模式；禁止任何形式的外联资源加载；彻底清除所有JS执行入口。

• 可靠性：对 malformed HTML（畸形标签、未闭合标签）具备极强容错性，不崩溃、不挂起。

• 可维护性：规则引擎与解析器解耦，易于扩展新的标签策略或协议处理器。

核心接口设计示例 (伪代码)

// 定义清洗配置结构
struct SanitizeOptions {
    allowedTags: Set<String>
    allowedAttributes: Map<String, Set<String>> // Tag -> Attributes
    allowedProtocols: Set<String> // e.g., "http", "https"
    disallowedTagsMode: Enum<Discard, ReplaceWithComment>
    stripComments: Bool
}

// 定义清洗结果
struct SanitizeResult {
    cleanedHtml: String
    removedElements: List<String> // 审计日志
    hasPotentialThreat: Bool
}

// 核心清洗接口
interface HtmlSanitizer {
    // 使用默认安全配置
    func sanitize(html: String): Result<SanitizeResult, SanitizeError>
    
    // 使用自定义配置
    func sanitizeWith(html: String, options: SanitizeOptions): Result<SanitizeResult, SanitizeError>
    
    // 流式处理大文件
    func sanitizeStream(input: InputStream, output: OutputStream, options: SanitizeOptions): Result<Int64, SanitizeError>
}

// 错误类型定义
enum SanitizeError {
    case InvalidHtmlFormat(String)
    case ConfigurationError(String)
    case MemoryLimitExceeded
    case InternalParserError(String)
}

// 默认安全预设
object DefaultPresets {
    func getStrictProfile(): SanitizeOptions
    func getRelaxedProfile(): SanitizeOptions
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：基础HTML解析器 + 默认白名单清洗逻辑 + 单元测试 (覆盖率≥95%)。

• 第二阶段：自定义规则引擎 + 流式处理支持 + 性能基准测试 + 模糊测试。

• 第三阶段：高级防御策略（如CSS清洗）+ 压力测试报告 + 生产级部署指南 + cjpm 发布包。

项目实施路线图

技术实现规范与质量认证体系

仓颉语言专项质量规范

• 编码规范：100% 符合仓颉语言官方编码规范，通过 cjfmt 自动格式化校验。

• 类型安全：充分利用模式匹配处理HTML节点类型，利用Option/Result类型显式处理解析失败。

• 错误处理：所有解析异常必须捕获并转换为业务友好的错误码，严禁直接抛出底层异常。

测试与验证标准

• 单元测试：核心模块行覆盖率≥95%，重点覆盖各种畸形HTML、嵌套标签及边界条件。

• 安全测试：必须通过Google XSS Audit Suite及OWASP ZAP扫描，确保无已知XSS向量绕过。

• 模糊测试（Fuzzing）：使用随机生成的HTML片段进行长时间 fuzzing，确保解析器不崩溃、不泄漏。

文档与可维护性

• API 文档：代码须包含规范的文档注释，详细说明各配置项的安全含义。

• 安全最佳实践：提供《后端HTML清洗安全指南》，指导开发者如何配置规则以平衡功能与安全。

• 贡献指南：明确仓颉项目构建、调试、提交全流程规范。

持续集成质量门禁

#!/bin/bash
# PR 自动化流水线脚本

# 1. 格式检查
cjpm fmt --check

# 2. 构建检查
cjpm build
cjpm build --release

# 3. 静态 lint 检查
cjpm lint --deny-warnings

# 4. 全量测试与覆盖率
cjpm test --all-features --coverage

# 5. 安全模糊测试 (Fuzzing)
# cjpm fuzz --duration 3600 --input corpus/html_samples

# 6. 性能基准测试
cjpm bench

技术栈与开发环境

• 核心语言：仓颉编程语言（Cangjie Language）1.0.0 及以上版本（强制）。

• 构建与包管理：CJPM (Cangjie Package Manager)。

• 测试框架：仓颉原生测试框架。

• 质量工具：cjfmt, cjpm lint, cjpm bench, 模糊测试工具。

• 环境要求：仓颉 1.0.0+ 标准工具链，CI 环境需预置大量HTML测试样本集。

交付件

验收标准

1.功能

1. 三方库必须有明确的功能；

2. 如果参考对标库移值开发，功能与参考三方库保持一致。

2.资料

1. Readme：包含简介，软件架构，目录结构，下载安装（编译构建），接口说明，使用示例，约束限制，开源协议，参与贡献等内容；

2. Changelog，三方库版本需包含基本的修改说明。

3.标准遵从性（可选），三方库实现需满足对应协议或行业标准，举例

1. appquth：支持对OAuth 的PKCE扩展；

2. icu4j：支持unicode标准库，通用字符集ISO/IEC 10646。

4.性能目标

1. 性能敏感三方库接口运行性能持平对标三方库

5.开源协议遵从，必须包含License文件

1. 放置合适的开源License协议，建议Apache License Version 2.0；

2. 引用或参考开源三方库，需遵从开源协议。

6.网络安全要求

1. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求