Vladimir-Kryshchenko/dsh-route-fence-linter

dsh-route-fence-linter

在 webServer 上注册的每个插件路由都由最长前缀匹配进行分发，优先于主机的 /api 网关——因此它永远不会经过网关的统一信任检查。每个插件作者都必须自带浏览器信任防护栏，而大多数都没有。这个 linter 会找出那些没有的。

用法

dsh-route-fence scan                       # $DSH_HOME/profiles/web
dsh-route-fence scan /path/to/profile

退出码：0 干净 · 1 至少有一个 FAIL · 2 用法/IO 错误。

判定结果

| 判定 | 含义 |
|---|---|
| PASS | 处理程序在一个防护栏上做了门控，该防护栏在处理 Origin 之前先固定 Host。 |
| WARN | 以下任一情况：在防护栏内部，Origin / sec-fetch-site 在 Host 被固定之前被读取；或者注册的路由定义在被扫描的包之外，因此无法读取其防护栏。请手动确认。 |
| FAIL | 以下任一情况：任何地方都没有 Host 检查；一个将 Origin 与 Host 进行比较但从未将 Host 固定到回环地址的防护栏（可被 DNS 重绑定绕过——攻击者控制两个头且它们匹配）；或者一个存在但此处理程序从未调用的防护栏。 |

无法读取源代码的 bundle 会被报告为 SKIP 并计入摘要——被跳过的 bundle 不是干净的 bundle。

registerFallback 也会被检查，而且当它没有防护栏时，其读取结果比任何路由都更糟：回退座位会应答每一个没有匹配到命名路由的请求，因此一个没有防护栏的回退比一整棵前缀树所暴露的面更广。

扫描范围

扫描覆盖一个包发布的内容（其 package.json 的 files 字段）；未声明 files 的包会被整体扫描。任何被排除的内容都会在输出中以 note 行的形式列出，绝不会被静默丢弃。

按目录名称限定范围的做法曾被尝试并已回退：跳过任何名为 tests/ 或 examples/ 的内容，会让插件把没有防护栏的路由藏在一个具有该名称的目录中，并被报告为干净。发布范围无法以这种方式被钻空子——加载器只能导入已安装的内容。

可被重绑定绕过的形态被评定为 FAIL，而不是 WARN：它在一个真实的、被广泛安装的插件中被实际发现，并已确认可针对一个正在运行的 profile 被利用——一个带有 Host: evil.example 和 Origin: http://evil.example 的请求通过了检查并执行了一个会改变状态的方法。

此工具所检查的防护栏

主机自身使用的形态（以及 dsh-better-sidebar/src/trust-fence.ts 所复制的）：首先将 Host 头固定到回环地址或已配置的受信任权威，拒绝跨站 fetch 标记，然后才比较 Origin。在固定 Host 之前比较 Origin 不是防护栏。

定义在另一个文件中的路由

一个以 routes.map(r => webServer.register(r)) 形式注册的路由，其中 routes 来自 src/web/routes.ts 中的 buildWebRoutes()，在其注册处附近没有任何防护栏——防护栏在一个模块之外。根据注册处周围的文本对这样的路由进行评定，会在真实插件上产生误报 FAIL，因此 linter 改为跟踪该值。
当注册的参数不是内联对象时——而是一个裸标识符、一个工厂调用 build(...)、一个展开，或对其中之一进行 .map / .forEach / .flatMap 时的元素参数——linter 会将该名称解析到处理器实际编写的位置，并在那里对它们进行评级。被追踪定义中的每个处理器都单独评级；一个未加围栏的处理器就会让整个注册失败，因此一个围栏了四条路由却忘了第五条路由的工厂是 FAIL，而不是 PASS。

遍历在每一步都是故障关闭的。只有当它找到真正以围栏为门控的处理器主体时，它才报告 PASS。来自裸说明符导入的路由是 WARN（“在被扫描的包之外——请手动检查”），绝不会是 PASS；解析不到任何被扫描内容的相对导入也是如此。其他任何它无法确定的情况——一个 handler: 是裸函数引用、一个它找不到的工厂、一条超过三个模块跳转的链——都会回退到之前的 FAIL。导入循环会在 (file, name) 对的已访问集合上终止。

说明符解析覆盖了 dsh 插件实际编写的内容：带 .ts / .mts / .tsx / .js / .mjs / .cjs 或无扩展名的相对路径、用 .js 拼写表示 .ts 文件的约定，以及通过 index. 解析的目录导入。它不是 Node 解析器：package.json 的 exports、imports（#alias）、tsconfig 的 paths 以及工作区链接都不会被跟随——它们解析不到任何被扫描内容，即为 WARN。

限制

这是对源文本的启发式分析，而非数据流分析。围栏被识别为既引用 Host 又约束 Host 的最小函数体；当处理器调用该围栏、将其作为值接收，或内联执行该检查时，该处理器就算作已门控——跨文件追踪对追踪到的处理器坚持完全相同的标准。

仍然无法触及的情况：通过包装安装的围栏（register(withFence(route))，其中包装器才是执行检查的一方）、在运行时从配置组装的路由、仅通过裸标识符引用到达的处理器，以及位于非相对说明符之后的路由源。这些会读作 WARN 或 FAIL，绝不会是 PASS。该 linter 还会检查处理器中围栏是否存在，而不是检查它在文本上是否是第一条语句。

报告错误判定；它们是 bug——尤其是错误的 PASS。