Handsontable 安全指南CSP 配置、HTML 净化sanitizer与 Trusted Types 集成实战【免费下载链接】handsontableJavaScript Data Grid / Data Table with a Spreadsheet Look Feel. Works with React, Angular, and Vue. Supported by the Handsontable team ⚡项目地址: https://gitcode.com/gh_mirrors/ha/handsontableHandsontable 是一款纯浏览器端运行的 JavaScript 数据表格组件其安全模型围绕客户端渲染、不落服务器展开所有 XSS 防护、粘贴内容净化与 CSP 兼容性都由前端方案承担。本文以官方安全文档为骨架结合仓库源码utils/sanitizer.ts、helpers/dom/element.ts、core/settings.ts深入讲解如何配置 Content Security Policy、如何通过sanitizer选项实现上下文感知的内容净化、以及如何在启用 Trusted Types 的页面中正确集成读完即可直接落地到生产项目。概述Handsontable 的安全模型Handsontable 的软件是浏览器端client-side组件不主动与任何服务器通信官方也不提供或推荐特定应用后端方案。这意味着数据从前端到后端、以及后端内部的传输安全完全由应用方负责需要自行确保端到端的加密与校验安全关注点集中在客户端渲染路径即网格把 HTML 写入 DOM 时可能引入的注入风险因此官方安全策略由四部分组成Content Security PolicyCSP兼容性、HTML 内容净化sanitizer选项、Trusted Types 集成以及围绕代码质量与合规的治理措施第三方依赖审计、独立安全审计、保险与代码托管。Content Security PolicyCSP配置Content Security Policy 是应用方用来检测并削弱跨站脚本XSS、数据窃取等攻击的附加安全层。Handsontable 本身不使用外部字体、图片或脚本其界面通过 DOM 节点而非 HTML 字符串构建这一点在 copyPaste.ts 与 helpers/dom/element.ts 的实现中可以得到印证因此你通常只需为它追加两条指令指令作用说明script-src加载 Handsontable 的脚本文件指向你放置 Handsontable 静态资源的源域名style-src ... unsafe-inline加载 Handsontable 的样式文件指向静态资源源unsafe-inline是必需的某些特性例如复制粘贴依赖内联样式写入示例Handsontable 与应用同源托管meta http-equivContent-Security-Policy contentdefault-src none; script-src self; style-src self unsafe-inline示例Handsontable 托管在 CDNcdn.jsdelivr.netmeta http-equivContent-Security-Policy contentdefault-src none; script-src self cdn.jsdelivr.net; style-src self unsafe-inline cdn.jsdelivr.net注意CSP 规则只负责允许哪些资源被加载它并不净化内容真正的 HTML 净化需要配置sanitizer选项见下文两者是互补关系。第三方软件依赖与合规Handsontable 以第三方依赖的形式使用开源软件并承诺持续跟踪依赖更新以保持安全。仓库的package.jsonhandsontable/package.json集中声明了这些依赖官方通过 Snyk 对源码与全部依赖含开源依赖进行漏洞扫描同时借助 Fossa 这类第三方工具保持第三方许可证条款合规。作为使用者保持你安装的 Handsontable 版本及时更新也是整体安全策略的一部分。内容净化HTML sanitizationv18.0 起的行为变化不再内置 HTML 净化器从v18.0开始Handsontable不再包含内置的 HTML 净化器写入 DOM 的 HTML 内容默认原样透传pass-through。这带来一个明确的责任转移如果你渲染的是不受信任的用户 HTML必须自行提供净化器。否则恶意单元格内容中的 HTML 可以在用户浏览器中执行脚本XSS。配置入口是sanitizer选项自 v17.0.0 起提供属于 Core 分类、仅在 grid 级生效不能按列或按单元格设置。它接收原始 HTML 字符串返回一个可安全赋给 DOM 的字符串在启用 Trusted Types 的页面中也可以返回TrustedHTML。由于是纯函数式接口你可以注入任意净化库DOMPurify 等或自研规则。底层调用链sanitizer 是如何被执行的从源码结构看净化逻辑围绕两条路径展开但都汇聚到同一个选项读取fastInnerHTMLhelpers/dom/element.ts网格渲染单元格、表头等常规内容时使用的写入函数。它先用HTML_CHARACTERS正则判断内容是否长得像标记只有命中才走innerHTML路径并调用净化器否则走fastInnerText以纯文本写入文本永远不会进入 sink也永远不会到达净化器。sanitizeHTMLutils/sanitizer.ts为以字符串形式拼接标记的表面服务——剪贴板粘贴路径与嵌套表头nestedHeaders的 ghost table 测量。与fastInnerHTML不同配置了净化器时它会看到每一个负载无论是否标记这与剪贴板路径的既有行为保持一致。两个入口共享同一个缺省警告当未配置净化器而又有标记形态内容要被写入时会通过warnOnce输出一次警告SANITIZER_WARN_KEY按hot.rootElement作用域去重每个实例最多一次提示文案由 missingSanitizerMessage 生成HTML content is being written to the DOM (context) without a sanitizer. Configure the sanitizer option to prevent XSS vulnerabilities.值得注意的细节如果净化器返回空字符串把负载完全剥离fastInnerHTML会调用empty()清空元素而不是执行innerHTML ——因为在require-trusted-types-for script下空字符串赋值同样是一个 Trusted Types sink直接赋值会导致整表崩溃清空则安全地渲染为空白。净化器覆盖的写入面surface/sourceHandsontable 只对它替你写入的 HTML运行净化器第二个参数用于标识写入面write surface方便你按来源应用不同规则写入面Surfacesource参数值列/行表头包括nestedHeaders标签headerpassword单元格类型渲染的内容password上下文菜单与下拉菜单项标签contextMenuselect编辑器的选项selectEditor以 HTML 字符串传入的对话框内容dialog通知消息notification从剪贴板粘贴的 HTMLCopyPaste.pasteHandsontable 自身剪贴板负载网格间粘贴CopyPaste.paste.sourceData这些值在 core/settings.ts 中由SanitizerContext联合类型定义同时在 sanitizer.spec.js 中有对应测试佐证例如sanitizer分别以header上下文收到行表头、列表头与嵌套表头内容。净化器不覆盖的面请自行净化有两个面刻意不经过净化器因为它们存在的目的就是渲染你提供的原始标记html单元格类型autocomplete与dropdown单元格中allowHtml的内容。对这些内容应在传入网格之前自行净化若它们来自用户或外部系统请与任何其他不受信任的 HTML 一视同仁。源码层面utils/sanitizer.ts 的注释明确说明这两个路径按设计渲染原始 HTML 并传入falsefalse表示有意为之的原样写入、不告警。另外还有一条比净化器更窄的路径confirm对话框的title、description与按钮标签始终会被剥离标签因此即使配置了宽松的净化器标记也无法从这里穿透。非标记内容走文本路径净化器看不到它Handsontable 只为形态像标记的内容调用净化器能读作 HTML 标签、标记声明或字符引用的内容。不含这些的文本以纯文本写入永不触及 sink也永不触及你的净化器。例如Smith Sons, Ltd.; est. 1920、Score 50 threshold→ 以文本写入不经过净化器bID/b、a amp; b→ 会被净化并解析。判定规则由 HTML_CHARACTERS 正则实现依次匹配标签形态/?[a-z][^]*、标记声明/处理指令[!?]、命名字符引用[a-z][a-z\d];与数字字符引用#x?[\da-f];且刻意未加g标志以保持.test()无状态。这意味着若你把净化器当作审计钩子或长度限制来用而非剥离标记它不会看到网格写入的每一个值。唯一的例外是剪贴板来源它们会收到每一份负载。特别说明CopyPaste.paste.sourceData与对象单元格粘贴这个 source 携带的是 Handsontable自身的剪贴板负载——正是它让对象值单元格object-valued cell能在两个网格间复制粘贴后保持对象本身。如果你用转义 HTML 而非剥离的净化器处理它负载会变成纯文本粘贴得到的将是显示值而非原始对象。这一行为通过parsePastedValue生效——注意你可能并未显式开启它autocomplete、dropdown、multiSelect单元格类型会替你打开。好消息是该负载会被解析为惰性文档inert document不能加载资源或运行脚本因此直接原样返回这个 source 不会让你暴露于精心构造的剪贴板。从 copyPaste.ts 的实现可见两个剪贴板来源sourceData与text/html分别调用sanitizeHTML后再经htmlToGridSettings解析且解析使用DOMParser构建无浏览上下文的文档——粘贴的 HTML 在解析期间既不能加载资源也不能运行脚本v18.1 起的行为见下文。import type { SanitizerContext } from handsontable; const settings { sanitizer: (content: string, source: SanitizerContext) source CopyPaste.paste ? strict(content) : loose(content), };在 TypeScript 中把第二个参数标注为SanitizerContext即可获得上述取值的自动补全。该类型接受任意其他字符串因此与别的库共享的净化器依然能编译通过代价是它无法拒绝拼写错误的值source contextmenu会编译成一个永远不会执行的分支。当你的规则依赖 source 分支时请对照上表核对拼写。用 DOMPurify 集成最简单可靠的实践是接入成熟的净化库import DOMPurify from dompurify; new Handsontable(container, { sanitizer: (html) DOMPurify.sanitize(html), // ... other options });官方在 metaSchema.ts 的选项文档中还给出了一个最高安全等级的零依赖示例用template解析后仅取textContent并对 做实体转义彻底放弃富文本。从 v18.0 升级到 v18.1 的净化器变更如果你的净化器在第二个参数上做分支v18.1 有两个source值发生了变化innerHTML不再被网格任何部分传入。原先为测量nestedHeaders宽度而进行的离屏offscreenpass 现在上报header与渲染态表头使用同一个值——同一个标签不再以两个名字到达你的净化器dialog现在会被传入。v18.0 中对话框内容以source undefined到达因此它会从处理undefined的分支通常是默认分支移入你可能并未编写的dialog分支。忽略第二参数的净化器无需任何改动。此外v18.1 为两个此前不经过净化器的面新增了净化passwordpassword单元格类型渲染的内容CopyPaste.paste.sourceData两个网格实例之间复制粘贴时使用的自有剪贴板负载。另外自 v18.1 起粘贴的标记通过DOMParser读取构建出的文档没有浏览上下文——无论sanitizer如何配置从剪贴板粘贴的 HTML 在解析期间都无法加载资源或运行脚本。分步迁移说明与代码示例见迁移指南。Trusted Types 与 CSPTrusted Types API 强制要求到达 DOM sink 的值必须来自你编写的 policy。需要明确的是Trusted Types 不是净化器也不能替代净化器——它可以要求存在一个净化器但自身永远做不了净化。例如createHTML: (input) input这样的 policy 能满足浏览器要求却提供不了任何保护真正净化的是你在 policy 内部调用的那个函数。Handsontable 自身不需要 Trusted Types policy它把界面构建为 DOM 节点而非 HTML 字符串因此你的trusted-types指令里无需为它登记条目。这一点与上文不使用外部资源、以 DOM 节点构建界面的定位相互印证。列/行表头是启用强制前需要知道的唯一边界只要表头文本包含或包含一个后随;的Handsontable 就会把它当作 HTML 写入。即使像Smith Sons, Ltd.; est. 1920这样不含任何标记的文本也会走上这条路。在require-trusted-types-for script下浏览器会拒绝那里的普通字符串且该写入不可恢复错误会从构造函数向外传播网格完全无法渲染。返回TrustedHTML的净化器见下例可以同时正确处理这样的表头与真正携带标记的表头。单元格值不受影响它们以文本写入无论怎么写都不会让单元格内容触及 sink。唯一的例外是你通过html单元格类型或allowHtml选择以标记渲染的内容——它们同样需要基于 policy 的净化器。粘贴会降级而非失败剪贴板解析器本身是 sink因此没有净化器时Handsontable 会粘贴剪贴板的纯文本版本而非 HTML 版本并记录一条警告。textExtractor: true也会走同一条表头边界内置抽取需要解析表头来读取读者所见文本因此上述形态的表头同样需要基于 policy 的净化器而你自定义的抽取函数不会——Handsontable 只调用它并使用返回值没有内容触及 sink。你自己的数据仍然需要 policy因为它是 Handsontable 替你写入的。把净化器包进 policy 并返回createHTML的结果const policy window.trustedTypes?.createPolicy(my-app-sanitizer, { createHTML: (input) DOMPurify.sanitize(input), }); new Handsontable(container, { sanitizer: (content, source) policy ? policy.createHTML(content) : DOMPurify.sanitize(content), // ... other options });同时把该 policy 的名字加入你的 CSPtrusted-types指令否则 policy 创建会被阻止。命名请以你的应用命名而非 HandsontablecreatePolicy在名字重复创建时会抛出异常共享名字会与任何其他选用它的代码冲突。Handsontable 会把净化器返回的值原样传给 DOM绝不与其他标记拼接也不转回字符串——这两者都会剥落 trust 并导致浏览器拒绝。还有一点兼容性须知Trusted Types 并非在所有 Handsontable 支持的环境中可用它于 2026 年 2 月才达到 Baseline晚于 Handsontable 支持的最老浏览器因此在 Firefox 148 之前、Safari 26 之前的环境里 policy 是惰性的净化器返回普通字符串的行为与以往完全一致。无论采用何种客户端策略请同时以服务端校验作为补充实现端到端的数据完整性。高质量代码承诺官方承诺交付高质量代码发现问题时尽快修复并保持库的更新而作为使用方的你也需要保持所安装 Handsontable 副本的版本更新才能持续获得安全修复。安全认证与审计官方定期委托独立网络安全专家对完整代码库进行安全审计。仓库的 public 目录存放着对应的证书文件最新审计记录如下审计机构完成日期证书Seqred2022-02-21下载TestArmy2023-04-28下载TestArmy2024-04-19下载TestArmy2025-05-13下载TestArmy2026-07-09下载审计依据行业标准方法执行包括OWASP Top 10与OWASP Application Security Verification StandardASVS。代码审计Snyk官方使用 Snyk 审计代码。Snyk 无缝集成进开发工作流检查源码及所有依赖包括开源依赖中的漏洞并通过邮件或 Slack 提供安全状态通知可在数分钟内完成对package.json的监控并借助其漏洞数据库发现风险。保险与代码托管官方由 Lloyds of London 承保保单同时保护 Handsontable 与其客户客户侧覆盖网络媒体责任、隐私责任与文档丢失、保密义务违约责任、网络安全责任、缓解成本、监管行动与罚款、声誉损害Handsontable 侧覆盖自身数据或网络的损失、业务中断、网络盗窃、网络勒索、电话线路黑客、通知费用与声誉损害。代码托管层面官方代码存放于 GitHub同时将全部代码发布自动托管给源代码托管公司 Codekeeper该服务需额外付费即使托管平台发生意外代码副本仍受保护与托管发布事件发生时 Codekeeper 提供 24/7/365 的快速恢复。报告安全漏洞安全是最高优先级事项。若发现可疑活动或证据可通过 securityhandsontable.com 报告官方承诺及时响应。官方不提供漏洞赏金计划但对安全研究人员与独立开发者的工作表示诚挚感谢。相关阅读从 v18.0 迁移到 v18.1含 sanitizer 变更细节密码单元格类型上下文菜单指南TypeScript 类型指南SanitizerContext等导出类型HTML 单元格类型不经过净化器的面sanitizer选项的完整 JSDoc 定义【免费下载链接】handsontableJavaScript Data Grid / Data Table with a Spreadsheet Look Feel. Works with React, Angular, and Vue. Supported by the Handsontable team ⚡项目地址: https://gitcode.com/gh_mirrors/ha/handsontable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考