企业官网建设流程全解析

office-open-xml-viewer 是一款运行在浏览器中的 Office Open XML 文档查看器，它将 DOCX、XLSX、PPTX 文件直接渲染到 HTML Canvas 上。正因为运行在用户浏览器里、又要解析来路不明的 Office 文件，它的安全设计格外值得拆解：从 [MS-OFFCRYPTO] 密码解密到 ZIP 炸弹防御，再到层层资源限制，这套机制确保敏感文档不离开浏览器，恶意文件也无法拖垮页面。🔒

为什么浏览器端 Office 查看器需要安全设计

在服务器上渲染 Office 文件，隔离靠进程；而在浏览器里，一份精心构造的文档只要被打开，就可能占用你当前的标签页、耗尽内存，甚至诱导出不必要的网络请求。office-open-xml-viewer 把安全边界直接做进了加载管线：所有解析、解密、渲染都在本地完成，风险被转化为确定性的类型化错误，而不是不可控的崩溃。

MS-OFFCRYPTO 加密：密码文档在本地解密，文件永不出浏览器

支持 Agile 加密的密码文档加载

带密码保护的.docx/.xlsx/.pptx文件本质是 OLE2/CFB 容器而不是 ZIP。给它传入密码即可在客户端完成解密：

const doc = await DocxDocument.load(bytes, { password: 'secret' });

解密流程在 decrypt-ooxml.ts 中分三步走：提取EncryptionInfo与EncryptedPackage流 → 识别加密版本 → 校验密码并解密。只有 [MS-OFFCRYPTO] §2.3.4 定义的Agile 加密（v4.4）受到支持；遗留的 Standard / Extensible 方案会返回类型化的unsupported-encryption错误，而不是静默失败。

底层如何用 WebCrypto 实现

核心实现在 agile.ts，完全构建在浏览器原生 WebCrypto 之上：

• 密钥派生：按规范执行 SHA 摘要链式迭代（spin count 常见为 100,000 次），因此解密一个受保护文件大约增加 1 秒左右的主线程耗时
• 分段解密：密文按 4096 字节分段，逐段 AES-CBC 解密，每段使用基于分段的独立 IV
• 版本识别：encryption-info.ts 解析 8 字节二进制头 + XML 描述符，精确区分 agile / standard / extensible / unknown

所有失败都被归一为三种原因：invalid-password（密码错误）、unsupported-encryption（不支持的加密方案）、corrupt（容器损坏），调用方无需解析任何错误消息字符串。🛡️

诚实的安全边界：HMAC 完整性不做校验

README 中明确写道：解密可以恢复明文，但不校验[MS-OFFCRYPTO] §2.3.4.14 的 HMAC 数据完整性标签，即对密文的篡改不会被检测到。因此官方建议：把解密输出当作来自不受信来源的普通输入同等对待。这种"不夸大安全声明"的做法，本身就是成熟安全设计的体现。

ZIP 炸弹防御：资源准入限制如何挡住"小文件放大攻击"

Office 文件是 ZIP 压缩包，压缩体积无法作为内存安全的代理指标——一个几 MB 的包可以解压出数百 MB 的部件。office-open-xml-viewer 的解法是准入门禁（admission policy）：先测量、后放行，超限立即拒绝并"毒化"整个会话。

三层默认限额与不可关闭的硬上限

默认策略记录在 resource-policy.json：

即使把某个字段设为null禁用公开限额，内部硬上限依然生效。策略归一化逻辑见 resource-policy.ts：限额会被转换成三个 u64 参数传入 Rust/WASM 解析器，主线程、Worker、Node 三条链路共享同一套口径。

不信任任何"声明"，只相信实际输出

设计文档 ooxml-resource-governance-design.md 指出：ZIP 中央目录里的声明大小是不可信数据，攻击者可以伪造一个"很小"的声明。因此限额同时校验声明值与实际解压器输出，累计预算按"实际读取的不同条目"计费，重复读取同一部件不会重复扣费。默认值的选择有明确依据——见 ooxml-resource-default-calibration.md，公共样本中最大的压缩包只有 80 个条目，4,096 的默认值留有 20 倍以上余量，而单个 128 MiB 的限额恰好能在约 268 MiB 的病态工作表放大之前将其拦下。

触发限额会发生什么

超限会以OoxmlResourceLimitError（code === 'ooxml-resource-limit'）拒绝加载，其details.violation结构化报告资源名、指标、限额、观测值与使用快照。应用也可以按自己的文档语料自定义预算：

new XlsxViewer(container, { resourceLimits: { maxArchiveEntryBytes: 64 * 1024 * 1024, maxTotalInflatedBytes: 192 * 1024 * 1024, maxArchiveEntries: 2048, }, });

资源限制全貌：从工作表行数以到图片解码

XLSX 工作表逻辑预算

压缩包层面挡不住"合法但巨大"的表格，因此工作表模型另有逻辑预算（默认：10 万行 / 25 万单元格 / 32 MiB 字符串 / 64 MiB JSON），可通过xlsxWorksheetLimits调整，见 load-options.ts 的类型说明。

图片与嵌入字体的独立硬守卫

• 图片解码：默认 128 MiB 解码 RGBA 预算，单张保留面不超过 32 Mi 像素 / 128 MiB；超限以类型化错误拒绝，而不是静默吞图（见 README Security & Privacy）
• 嵌入字体：DOCX 的.odttf混淆字体按 ECMA-376 §17.8.1 去混淆后，受 30 MiB 硬上限保护，见 embedded.ts

隐私设计：默认零网络、Canvas-only 渲染、XXE 安全

隐私视角下，office-open-xml-viewer 有几条硬边界：

• Canvas-only 渲染：文档被解码后直接绘制到 Canvas，源文件中的脚本、超链接、表单等活动内容不会被执行或注入 DOM
• 默认零网络：库不发任何遥测，也不联系第三方服务；主题 Web 字体（Carlito/Caladea）仅在显式传入useGoogleFonts: true时才从 Google Fonts 加载，README 甚至专门提示其 GDPR 影响
• XXE 安全：Rust 侧 XML 解析使用roxmltree，默认不解析外部实体
• 模糊测试（fuzzing）加固：fuzz/ 目录下的 14 个 fuzz target 持续对解析器注入畸形包，配套的确定性 OPC 构造器见 fuzz/src/lib.rs
• Worker 隔离：解析与渲染可运行在 Web Worker（mode: 'worker'），把大量失败隔离在 UI 主线程之外

可观测性：不泄露文档内容的调试报告

安全设施如果不可观测就等于不存在。加载完成（无论成败）后，你可以拿到一份构造上不含内容的机器可读报告：它只包含压缩包计数器与配置限额，永不包含源 URL、文件名、文档文本或密码。

• debug: true：控制台输出一张紧凑的资源使用卡片
• onResourceMetrics回调 /getResourceMetrics()：以编程方式获取快照，便于按自身文档语料校准限额（选型方法见校准文档）

📊 这套报告让你既能向团队证明"这个查看器不会吃光浏览器内存"，又不用为遥测数据打任何隐私补丁。

小结：一份可以直接抄作业的安全清单

对新手集成者来说，默认值已经足够安全；如果你的文档语料偏大，先用onResourceMetrics收集真实数据，再适度调高resourceLimits——这正是官方校准文档推荐的流程。