sanitize-html

项目背景与战略目标

sanitize-html 项目旨在为仓颉语言生态构建一个原生、安全的 HTML 内容清洗库，专门用于防御跨站脚本攻击（XSS）。在现代 Web 后端开发中，用户生成的内容（UGC）如评论、富文本博客、论坛帖子等无处不在。直接渲染这些内容极易导致恶意脚本注入，窃取用户 Cookie 或执行非法操作。现有的 Node.js 实现依赖重型运行时，在高并发场景下存在 GC 压力和内存开销问题。本项目将利用仓颉编程语言（Cangjie Language）1.0.0+ 的内存安全特性，从根源上杜绝缓冲区溢出和内存泄漏；借助轻量级线程模型，实现高吞吐量的 HTML 流式清洗；利用强类型系统确保白名单配置的严谨性。目标是打造一款性能超越现有 JS 实现、配置灵活且默认安全的后端 HTML 清洗标准库。

核心功能需求与技术规格

功能模块分解

非功能性需求规范

• 性能指标：中小篇幅 HTML（<50KB）清洗耗时 < 2ms，大文档流式处理吞吐量提升 50%（对比 Node.js 实现）。

• 安全要求：依托仓颉编译期内存检查，杜绝缓冲区溢出；默认启用最严格的安全策略（Disallow unknown tags/attrs）；防止 ReDoS（正则表达式拒绝服务）攻击。

• 可靠性：完善的异常捕获机制，确保在畸形 HTML 输入下服务不崩溃，自动降级或抛出明确错误。

• 可维护性：模块化设计，解析器、过滤器与配置管理器解耦，符合仓颉编码规范。

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

// 定义清洗配置结构
struct SanitizeOptions {
    allowedTags: Set<String>
    allowedAttributes: Map<String, Set<String>> // Tag -> Attributes
    allowProtocolRelative: Bool
    disallowedTagsMode: Enum // "discard", "completelyRemoveText", "leaveAsIs"
    customHandlers: Map<String, Func<Node, Unit>> // 自定义节点处理逻辑
}

// 定义清洗错误类型
enum SanitizeError {
    case MalformedHtml(String)
    case ConfigurationError(String)
    case CssInjectionDetected(String)
}

// HTML 清洗器核心接口
interface HtmlSanitizer {
    // 创建实例，接受配置选项
    static func create(options: SanitizeOptions?) -> HtmlSanitizer

    // 同步清洗 HTML 字符串
    func sanitize(html: String) throws<SanitizeError> Result<String, SanitizeError>

    // 异步流式清洗，适用于大文件
    async func sanitizeStream(input: InputStream, output: OutputStream) throws<SanitizeError> Result<Unit, SanitizeError>
    
    // 获取默认安全配置（推荐）
    static func getDefaultOptions() -> SanitizeOptions
}

项目交付物与实施路线图

阶段性交付物清单

• 第一阶段：HTML 流式解析器 + 基础白名单过滤引擎 + 单元测试 (覆盖率≥95%)。

• 第二阶段：CSS 清洗模块 + 自定义处理器支持 + 性能优化 (零拷贝) + 集成测试 (XSS 攻击向量库验证)。

• 第三阶段：与仓颉 Web 框架集成中间件 + 压力测试报告 + 生产级部署指南 + cjpm 发布包。

项目实施路线图

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

仓颉语言专项质量规范

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

• 类型安全：充分利用泛型与模式匹配处理 HTML 节点树，减少强制类型转换；所有权设计需确保解析过程中内存的高效复用。

• 错误处理：显式声明异常类型（throws），杜绝不可控的运行时崩溃，所有解析错误必须被捕获并转换为业务友好的错误码。

测试与验证标准

• 单元测试：核心模块行覆盖率≥95%（通过 cjpm test --coverage 验证），重点覆盖边界条件、嵌套标签及非法输入。

• 安全基准：建立包含常见 XSS 攻击向量（Script injection, Event handlers, CSS expressions, SVG exploits）的测试集，确保拦截率 100%。

• 性能基准：监控不同大小 HTML 文档的清洗耗时，确保在高并发下 CPU 占用率低于同类 Java/Node 库。

文档与可维护性

• API 文档：代码须包含规范的文档注释（Doc Comments），详细说明白名单配置规则及默认行为。

• 架构决策记录（ADR）：记录关于流式解析 vs DOM 解析的技术选型依据。

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

持续集成质量门禁

#!/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. 安全专项测试 (XSS Vectors)
cjpm test --suite security-xss

# 6. 性能基准测试
cjpm bench

技术栈与开发环境

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

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

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

• 质量工具：cjfmt, cjpm lint, cjpm bench。

• 环境要求：仓颉 1.0.0+ 标准工具链，CI 使用官方/社区认证 Docker 镜像，支持 Linux/x86_64 及 Linux/ARM64 架构。

交付件

验收标准

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. 满足基础的网络安全红线及隐私要求，符合安全编码规范。

过程质量要求