安全导航目标
安全导航目的地¶
{
"scope": "global",
"triggers": {
"navigation": [
"FR2",
"FR3",
"FR4",
"FR6",
"FR7",
"FR8",
"DEC-1",
"DEC-2",
"DEC-3"
]
}
}
意图¶
无论由哪个组件绘制、导航是原生还是命令式的、框架路由器是否替换了原生锚点,激活 Astryx 链接的人都应获得相同的目标安全性。组件组合不得创建绕过共享规则的路径。
本规范接受共享导航目标契约。family:navigation-destinations 记录了在原生、自定义路由器、命令式和 Markdown 导航中的采用情况。接受该契约本身并不确立实现或精确标题验证。
非目标¶
- 验证 URL 语法、要求绝对 URL,或将目的地限制为主机白名单。
- 为图像、媒体、下载文件、CSS、fetch 或其他嵌入式资源 URL 定义内容策略。这些 sink 具有不同的功能和内容类型风险;已接受链接目的地的下载仍受支持。Markdown 图像 URL 是例外:Markdown 的解析器通过其链接规则(DEC-3)决定它们。
- 在控制权离开 Astryx 后,清理调用方拥有的 JSX、自定义 Markdown 插件输出或任意消费者回调。
- 替换内容安全策略(Content Security Policy)、路由器授权、服务器验证或应用级访问控制。
- 添加允许组件绕过或配置该规则的公共 prop。
- 更改链接标签、target/rel 行为、禁用语义或普通 URL 解析。
需求¶
- FR1 — 一条规则覆盖每个 Astryx 拥有的导航出口。 在 Astryx 渲染、委托或命令式激活调用方控制的导航目标之前,该目标必须(MUST)通过本规范中的契约。从原生锚点迁移到路由器组件或更大的可点击表面不得(MUST NOT)削弱该契约。
- FR2 — 检查遵循浏览器方案规范化。 方案检查必须(MUST)移除 ASCII 控制字符
U+0000–U+001F和U+007F,修剪外部空白,并以不区分大小写的方式比较 ASCII 方案文本。这可以防止被阻止的方案被浏览器忽略的字符隐藏。 - FR3 — 可执行文档方案被阻止。 以
javascript:、vbscript:或data:text/html开头的规范化导航目标不得(MUST NOT)成为可执行导航。该检查在查询、哈希、target、修饰键或指针按钮差异可以选择另一个 sink 之前应用。解析器负责 Markdown 链接和图像 URL 的安全性:它还阻止链接和图像中任何媒体类型的每个data:URL。渲染器仅在真实绕过路径(如果存在)处保留检查(DEC-3)。 - FR4 — 普通目的地继续正常工作。 相对路径、同文档片段、协议相对 URL 以及普通方案(如
http:、https:、mailto:、tel:和安全自定义方案)必须(MUST)保留其现有的导航行为,包括从已接受目的地的下载。该契约不重写、解析或按主机过滤已接受的目的地。已接受的结构化路由器目的地必须(MUST)保留其对象身份。 - FR5 — 原生、自定义和命令式路径都被覆盖。 完整规则必须(MUST)适用于 React DOM 锚点、通过
LinkProvider或as接缝提供的自定义组件,以及包括window.open和window.location在内的命令式出口。React DOM 自身的清理器不是原生锚点例外。中键点击和 Cmd/Ctrl 点击也不是例外。 - FR6 — 拒绝在导航边界失败关闭。 被阻止的目标必须(MUST)渲染为惰性状态,且不得(MUST NOT)到达命令式浏览器 API。对于被拒绝的目标,不得(MUST NOT)调用自定义路由器,包括用
undefined替换被拒绝的值。当这样做无法激活被拒绝的目标时,组件可以(MAY)保留非导航渲染和消费者回调。 - FR7 — 路由器目标 props 是独立的 sink。 当自定义链接组件可以同时接收
href和to时,每个提供的值都必须(MUST)独立通过规则。如果任一被拒绝,结果必须(MUST)是惰性的:不调用自定义路由器,也不回退到另一个目标,即使它是安全的。当两者都被接受时,显式的to保留其文档化的优先级。受支持的结构化目的地必须(MUST)遵循相同的规则,包括每个带方案的href、pathname或protocol字段以及这些字段构成的目标。单独的方案或未经检查的字段不得(MUST NOT)提供绕过规则的路径。已接受的字段和对象身份保持不变。 - FR8 — Markdown 的解析器应用共享规则并拥有其 URL 决策。 Markdown 的解析器必须(MUST)将共享导航规则及其规范化应用于每个链接和图像目标,并且还必须(MUST)拒绝每个
data:URL(DEC-3)。<Markdown>仅渲染其解析的节点,并仅在真实绕过路径(如果存在)处保留检查。Markdown 之外的共享 Core 导航管道仅拒绝共享的被阻止方案。 - IR1 — 共享出口使用共享所有者。 委托链接或命令式导航的 Core 组件必须(MUST)使用一个共享策略所有者,而不是维护组件本地的被阻止方案列表。Markdown 的解析器调用共享策略所有者并仅添加其
data:检查(DEC-3);它不保留共享被阻止方案列表的副本。 - IR2 — 每个不同的 sink 都有对变更敏感的覆盖。 当从原生锚点、自定义
href、自定义to、受支持的结构化目的地(包括protocol)、新标签页、修饰点击、中键点击、普通命令式导航或 Markdown 链接解析/渲染中移除防护时,验证必须(MUST)失败。如果自定义组件被调用时使用了undefined或另一个目标作为回退,被拒绝路由器的覆盖必须(MUST)失败。 - IR3 — 新的导航表面加入该家族。 接受调用方控制的导航目的地的新组件或 hook 必须(MUST)在发布前加入
family:navigation-destinations并重用共享所有者。
平台支持¶
- 支持的功能/引擎下限:Astryx Core 支持的每个浏览器和框架链接集成。
- 不支持的行为:忽略已过滤的目标 props 或根据其他调用方数据构造目标的自定义组件不在保证范围内;Astryx MUST NOT 声称调用方所有的行为已得到净化。
- 浏览器证据:真实 Chromium 验证每个被阻止的 scheme 在原生路径和命令式路径上保持惰性,且普通相对链接、外部链接、修饰点击、中键点击和下载行为仍然可用。单元集成测试验证自定义路由交接和对象同一性;真实框架 SSR 验证拒绝渲染时不会调用需要目标的路由器。
当前状态影响¶
family:navigation-destinations 是该行为的完整共享所有者。其成员覆盖当前所有接受或派生导航目标的 Core 组件,包括其公共成员拥有实际 href 的聚合组件记录。
实现和验证必须覆盖:
- 原生锚点上的完整被阻止 scheme 规则,而不仅仅是 React DOM 自身的
javascript:保护; - 自定义
href和to,包括受支持的结构化目标及其独立的protocol,只要任一值被拒绝就进行惰性渲染; - 所有命令式和委派激活,同时保留已接受的目标和消费者回调;
- 符合规范的 Markdown 导航,其中 Markdown 链接和图片 URL 由其解析器决定(DEC-3);
- 在记录完成家族采用之前提供精确 HEAD(exact-head)证据。
不会添加组件局部公开 prop。异常行为属于调用方所有的自定义渲染,位于此安全导航契约之外,而不是通过 LinkProvider 或 as 绕过。消费者文档应在组件记录 href 或路由接缝处说明共享结果;应链接到共享规则,而不是在每个 prop 行重复 scheme 列表。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR2, FR3, FR4, FR8 | 共享谓词与 Markdown 解析/渲染套件 | 混合大小写;嵌入控件;相对/哈希;http(s);mailto/tel;安全自定义 scheme;下载;被阻止的 scheme;Markdown 链接和图片中的每个 data: URL |
移除规范化或更改一个被阻止的前缀会使导航矩阵不一致 |
| FR5, FR6, FR7 | useLinkComponent 集成测试和框架 SSR 测试 |
原生锚点;提供者;as;安全/被拒绝的 href 和 to 的任意组合;结构化 pathname/href/protocol;已接受对象的同一性 |
被拒绝的目标会调用路由器,包括使用 undefined 或安全回退时;已接受的目标丢失同一性或优先级;SSR 抛出异常 |
| FR1, FR3, FR5, FR6 | useClickableContainer 集成测试 |
普通点击;_blank;Cmd/Ctrl+点击;中键点击;委派交互 ref |
被阻止的值到达 window.open/window.location,或普通导航路径停止工作 |
| FR1, IR1, IR3 | 家族成员与源码使用审计 | 每个当前的 useLinkComponent、useClickableContainer、Markdown 和直接原生锚点目标所有者 |
新的调用方控制导航出口在家族之外发布或重复本地规则 |
| 浏览器契约 | 真实 Chromium 探测 | 原生锚点上的所有被阻止前缀;自定义路由器替身;命令式同标签页/新标签页;修饰点击和中键点击;已接受目标和下载 | 脚本执行、发生被阻止的导航、被拒绝的目标获得链接激活,或普通浏览器功能退化 |
完成标准¶
本规范仅在满足以下条件时才从 accepted 移至 shipped:
family:navigation-destinations中的每个采用缺口都已关闭,或作为明确的所有者批准例外被记录;- exact-head 测试覆盖原生锚点、结构化路由器目标、惰性路由器拒绝,以及每个不同的命令式和 Markdown 导航出口;
- 源码/成员审计未发现家族之外由调用方控制的 Core 导航出口;
- 消费者文档描述共享结果,且不暗示除 Markdown 图片外的嵌入资源或调用方拥有的渲染器会获得相同策略。
决策日志¶
DEC-1 — 目标安全性随导航出口而定¶
参考: spec:AST-005/DEC-1
决策者: cixzhang,2026-08-31
所有能够激活调用方控制导航目标的 Astryx 自有路径都遵循统一的被阻止 scheme 规则。该保证在组件组合、自定义框架路由器、修饰点击、中键点击和命令式导航中依然成立,因为这些是同一用户意图的替代出口。
被否决:仅依赖 React DOM。React 可以保护它渲染的 href,但不会检查传递给自定义路由器的 props,也不会干预 window.open 或 window.location。
DEC-2 — 嵌入式资源仍作为独立策略¶
参考: spec:AST-005/DEC-2
决策者: cixzhang、2026-08-31
导航目的地与嵌入式资源属于不同的 sink 类别。本规范阻止导航中可执行的文档 scheme,但不裁定允许哪些图片来源、下载内容或抓取资源。来自已接受导航目的地的下载保持可用。因此,Markdown 可以拒绝更广的资源集合,同时仍匹配共享导航矩阵。
已否决:为每个 URL 形态的值设置一个无差别的 “safe URL” 布尔值。这会掩盖导航文档与嵌入或抓取资源之间的实质差异,并可能意外放宽或收窄无关的公开行为。
对于 Markdown 链接和图片,本决策已被 DEC-3 部分取代。
DEC-3 — Markdown 解析器全权负责 URL 安全,并阻止所有 data: URL¶
参考: spec:AST-005/DEC-3
决策者: cixzhang、2026-11-10
Markdown 解析器对 Markdown 的 URL 安全负全责。除了共享导航规则之外,它还阻止链接或图片中任意媒体类型的每一个 data: URL,并且 <Markdown> 只渲染其解析出的节点,不再进行第二次 scheme 检查。因此,解析器的公开树中不会为自定义渲染器携带任何 data: URL。对于 Markdown 链接,这比 DEC-2 所述的共享导航矩阵更严格;对其他每个成员的共享规则保持不变。不来自解析源的导航 URL(如插件的 base URL)会在其进入处被检查。
已否决:仅在 Markdown 图片中阻止 data:,这会让 data: 链接残留在解析器的公开树中。已否决:在渲染器中做第二次 scheme 检查,这会对仅由解析器产生的节点重复应用解析器的规则。
未决问题¶
无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx