OmniRoute 路由守卫豁免集加固实践：用「精确成员断言」替代「计数快照」，让 LOCAL

OmniRoute 路由守卫豁免集加固实践：用「精确成员断言」替代「计数快照」，让 LOCAL_ONLY 只读豁免测试可命名、可查替换

【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550+ contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

导读

OmniRoute 的授权管线（authz pipeline）将大量「可派生子进程、可被隧道利用为远程代码执行（RCE）」的管理面 API 路由划入LOCAL_ONLY（仅回环）层，并允许极少数只读路径以 GET/HEAD/OPTIONS 从非回环客户端访问。LOCAL_ONLY_API_GET_EXEMPTIONS正是这扇窄门的"白名单"——而一旦测试对它的断言退化为"只看有几个豁免项"，就会同时丧失可诊断性（无法点名越界路径）与防替换能力（同名计数下路径被偷换也照常通过）。本文以维护片段 changelog.d/maintenance/11580-get-exemption-membership-pin.md 为切入点，结合 routeGuard.ts 的实现与相关测试，完整拆解"按精确成员（exact membership）固定豁免集"这条测试加固策略。读完你将掌握：豁免集为什么只能精确匹配、计数断言存在哪两类失效模式、以及如何写出能"命名违规路径"并"捕获替换"的回归断言。

变更缘起：一则 changelog 维护片段

仓库的 changelog.d/ 按features/、fixes/、maintenance/分类收纳变更片段。本次讨论的 11580-get-exemption-membership-pin.md 全文如下：

test(authz):pinLOCAL_ONLY_API_GET_EXEMPTIONSby exact membership instead of by entry count, so the guard names the offending path and also catches a substitution (#11580)

一句话信息量很大：此前该豁免集存在一份"按条数断言"的守卫测试（例如断言集合长度为 1），这次被重写为按精确成员断言。其动机有两点——

可命名（names the offending path）：计数断言失败时只告诉你"期望 1 条、实际 N 条"，却不说是哪一条路径越界；成员断言能直接点名。
捕获替换（catches a substitution）：把/api/system/version偷换成别的路由，集合规模仍然是 1，纯计数断言会静默通过；成员断言则立刻失败。

要真正理解这条测试为什么值得这样加固，需要先看清它守护的对象——三层路由守卫与豁免机制。

从三层路由守卫谈起：豁免集守卫的是什么

路由守卫的完整实现位于 routeGuard.ts。该文件头部注释（L1-L22）定义了三层路由模型：

Tier 1 — LOCAL_ONLY：仅可从回环（loopback）访问。这些路由会派生子进程，暴露给非本地流量属于已知 CVE 类别（文件中引用了 GHSA-fhh6-4qxv-rpqj）。无论认证状态如何，一律无条件拦截，并返回403 LOCAL_ONLY。
Tier 2 — ALWAYS_PROTECTED：即使requireLogin=false也始终要求认证，覆盖破坏性/不可逆操作。
Tier 3 — MANAGEMENT（默认）：要求认证，但在requireLogin=false时放行（既有行为）。

Tier 1 的匹配面由三部分构成：

数据结构	匹配语义	典型示例
`LOCAL_ONLY_API_PREFIXES`（前缀数组）	`path === p \\|\\| path.startsWith(p)`	`/api/mcp/`、`/api/services/`、`/api/system/version`
`LOCAL_ONLY_API_PATTERNS`（正则数组）	`re.test(path)`，覆盖"派生段位于动态参数之后"的路由	`POST /api/providers/{id}/login`、`/refresh-cursor`
`LOCAL_ONLY_MANAGE_SCOPE_BYPASS_PREFIXES`	携带`manage`scope 的 API key 可选择性放行的前缀	`/api/mcp/`

其中LOCAL_ONLY_API_PREFIXES（L33-L76）逐条注释了为何该路径 spawn 子进程：例如/api/cli-tools/runtime/运行 CLI 工具、/api/tunnels/tailscale/login会执行tailscale up、/api/settings/mitm会安装系统级信任根证书、/api/db-backups/exportAll用tar打包导出。这些注释是理解豁免边界的第一手依据——只有"读方法不 spawn、不产生特权变更"的路径，才有资格进入豁免名单。

豁免机制：窄门只对精确路径、只对安全方法开启

由于某些 LOCAL_ONLY 路径本身包含"读安全、写危险"的两面性，守卫需要按 HTTP 方法差异化放行。豁免集的声明与判定逻辑位于 routeGuard.ts L209-L256：

export const LOCAL_ONLY_API_GET_EXEMPTIONS: ReadonlySet<string> = new Set([ "/api/system/version", "/api/tunnels/cloudflared", ]); /** Safe HTTP methods that can be exempted for read-only paths. */ const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]); export function isLocalOnlyPath(path: string, method?: string): boolean { // Method-aware GET exemption: only exact-match paths in the exemption set // are eligible; prefix/wildcard matching is intentionally NOT used... if (method && SAFE_METHODS.has(method.toUpperCase()) && LOCAL_ONLY_API_GET_EXEMPTIONS.has(path)) { return false; } return ( LOCAL_ONLY_API_PREFIXES.some((p) => path === p || path.startsWith(p)) || LOCAL_ONLY_API_PATTERNS.some((re) => re.test(path)) ); }

规则可以归纳为四点：

方法白名单：豁免仅在GET/HEAD/OPTIONS时生效；写方法一律维持 LOCAL_ONLY。
精确匹配：Set.has(path)要求路径与豁免条目逐字节一致，绝不使用前缀或通配——避免把 spawn 路由的子路径一并打开。
安全默认：method参数缺省（例如安全扫描脚本只传路径）时返回true（保守判定），防止任何 spawn 路径被意外放行。
豁免资格有硬性前提：注释（L213-L214）明确——只有读方法不执行任何子进程派生、也不暴露特权变更的路径才允许进入豁免集。

当前豁免集的两位成员及其理由都写在注释里（L216-L221）：

/api/system/version——GET 只读package.json与 npm registry；只有 POST 才触发自动更新（派生git checkout+npm install+pm2）。此路径因 Bug #5083（GET 被局域网误拦）而豁免。
/api/tunnels/cloudflared——GET 只读隧道状态；只有 POST 才派生 cloudflared 进程（#11531）。

为什么"按条数断言"守卫不住豁免集

历史上对该豁免集的守卫是计数式的，典型写法形如assert.equal(LOCAL_ONLY_API_GET_EXEMPTIONS.size, 1)。其缺陷可由测试注释（tests/unit/authz/route-guard-version-get-exemption.test.ts L94-L99）精确概括：

Every entry here opens a local-only path to LAN/remote GET, so the set must never grow by accident. Pinned by membership rather than bysize: a count cannot say WHICH path appeared, and it cannot see a substitution at all — swapping/api/system/versionfor some other route keeps size at 1 and passes.

翻译成两类失效场景：

失守一（无法点名）：集合从 1 涨到 2，断言只是"数量不对"，开发者不得不手动 diff 源码去找是哪条路径被加进来、它凭什么安全。而豁免集每多一个条目，就意味着"向局域网/远端多开一扇只读门"，审查成本应尽量前置到测试本身。
失守二（无法查替换）：攻击者或误操作把既有豁免路径/api/system/version替换成另一条同样敏感、但读方法也 spawn的路径，集合size不变，计数断言直接放行——这是典型的"断言写成恒真式"安全测试反模式。

因此 #11580 的修法不是微调计数，而是从断言对象上根治：不再断言集合的规模，而是断言集合的"内容"。

精确成员校验的落地形态：一份会点名、能查替换的回归测试

加固后的核心断言在 route-guard-version-get-exemption.test.ts L105-L110：

test("LOCAL_ONLY_API_GET_EXEMPTIONS holds exactly the reviewed paths", () => { assert.deepEqual([...LOCAL_ONLY_API_GET_EXEMPTIONS].sort(), [ "/api/system/version", "/api/tunnels/cloudflared", ]); });

这个断言做到了三点：

内容是权威：deepEqual对集合成员做完整比对，多一条、少一条、换一条都会失败，且失败信息直接打印期望与实际数组——违规路径被点名。
顺序无关：先[...set].sort()再比对，集合本身无序也不影响断言稳定性。
变更即评审：测试注释明确写道——"Adding a path is still meant to fail here; the fix is to add it to this list in the same change, with the reason it is safe for a read-only method."（L98-L99）也就是说，任何新增豁免都必须在同一变更里同步更新此断言并附带安全理由，形成"改豁免必经测试评审"的强制路径。

同一测试文件的其余用例则把豁免机制的边界契约全部钉死（L22-L110）：

豁免适用：GET/HEAD/OPTIONS /api/system/version均NOT local-only；
写方法仍封锁：POST/PUT/PATCH/DELETE /api/system/version一律local-only（POST 会派生 git/npm/pm2）；
安全默认：不带 method 调用isLocalOnlyPath('/api/system/version')返回true；
精确匹配边界：GET /api/system/version/extra（子路径）不被豁免，仍为 local-only；
不扩散到其他前缀：GET /api/mcp/sse、GET /api/services/9router/start、GET /api/db-backups/exportAll等一律保持 local-only——证明豁免只作用在精确路径上。

纵深配套：另一个豁免成员的双重锁定

豁免集中的第二位成员/api/tunnels/cloudflared另有专项测试 tests/unit/authz/route-guard-tunnel-processes-local-only.test.ts 单独断言其存在于集合中（LOCAL_ONLY_API_GET_EXEMPTIONS.has("/api/tunnels/cloudflared")）。这与"精确成员"总断言并不重复：专项测试以行为语义（"cloudflared 隧道路由的 GET 被豁免"）组织用例，总断言以集合不变式（"豁免集恰好等于这两条路径"）组织用例，二者构成双向锁定——即便将来重构为其他数据结构，任何一条语义不被某个测试覆盖，另一条也会兜底。这也是"成员断言"优于"计数断言"在可维护性上的又一体现：每一层断言都对应一条可读的业务规则。

源头守卫：`check-route-guard-membership`扫描脚本与测试闭环

除了豁免集的运行时判定测试，仓库还维护了一套源头级扫描机制，防止"本应 LOCAL_ONLY 却未被归类"的派生路由漏网：

扫描脚本 scripts/check/check-route-guard-membership.ts 遍历src/app/api/**/route.ts，将其映射为真实 URL 路径（含动态段占位符），再调用isLocalOnlyPath判断每条 spawn 路由是否都落入了 local-only 面。
测试 tests/unit/check-route-guard-membership.test.ts 为其提供纯函数级别的回归覆盖：例如用"漏掉/api/services/前缀"的合成谓词验证findUnclassifiedSpawnRoutes能精确点名未归类路由（L62-L74）；还验证routeFileToApiPath对动态段与 Windows 反斜杠的归一化（L31-L51），防止误报/漏报。
该测试还固化了两条已归类的 spawn 路径：/api/system/version与/api/db-backups/exportAll必须在LOCAL_ONLY_API_PREFIXES中且不再存在于"冻结的未归类例外"集合（L135-L146）——这与 #11580 加固的豁免集指向同一对路径，可见"版本检查 / 自动更新"是 OmniRoute 安全面中被反复审视的高危区域。

值得注意的是 routeGuard.ts 对每个 spawn 前缀的注释都标注了溯源（如found by 6A.8 route-guard gate、Hard Rules #15/#17），说明这些归类本身就是扫描闸门发现漏洞后的闭环产物，而非一次性人工清单。豁免集采用成员断言，正是为了让"后续每一条新增豁免都经过同等强度的评审"。

实践要点：给豁免守卫测试作者的迁移清单

把"计数断言"迁移为"精确成员断言"的完整检查项如下：

用内容替换规模：assert.equal(set.size, N)→assert.deepEqual([...set].sort(), [...])，让失败信息能点名。
在断言旁维护成员语义注释：逐条说明"为什么该路径的读方法安全、哪类写方法仍被封锁"，评审者可据此判断新增条目的合规性（可参考 route-guard-version-get-exemption.test.ts L94-L104 的写法）。
补充反例用例：至少覆盖"子路径不受豁免"（如/extra）与"其他 spawn 前缀不受豁免"（如/api/mcp/），防止豁免语义被人误读为前缀放行。
保留安全默认断言：对不带 method 的调用断言仍返回保守值，防止脚本路径意外开闸。
让新增豁免在同一变更内红→绿：先让成员断言因新增而失败，再于同一提交中更新豁免集与注释——这正是测试驱动加固（TDD）在安全清单上的标准循环。
与源头扫描联动：若豁免面向的路由属于 spawn 面（如本案例的/api/system/version），同时确保它已被check-route-guard-membership归类为 local-only 并在对应测试中固化，避免"测试自洽但实际路由已不在守卫面内"。

小结

LOCAL_ONLY_API_GET_EXEMPTIONS看似只是两条路径的小集合，却是 OmniRoute "RCE-via-tunnel" 防线（Hard Rules #15/#17、GHSA-fhh6-4qxv-rpqj）上极窄的一道只读侧门。门越小，越需要测试能精确地守住门的内容而非门的数量。#11580 的加固把"豁免集不能意外增长"从一句口头约定，变成了会点名违规路径、能当场识破路径替换的可执行契约——这一"用精确成员断言固定安全白名单"的模式，同样适用于任何"规模小、责任重、常被误加"的权限/豁免/放行清单，值得在同类安全守卫测试中复用。

OmniRoute 路由守卫豁免集加固实践：用「精确成员断言」替代「计数快照」，让 LOCAL_ONLY 只读豁免测试可命名、可查替换