GET /meta/books/:name(复数拼写)绕过 ADR-0046 §6.7 audience 门禁 —— 缓存分支的 doc/book 排除写的是字面量比较

[qq9340100]

发现于 #5881 的实施测量(旁证,与该单改动无关 —— 改前改后同样成立)。基线 origin/main @ 8e2bbba24。

事实

packages/rest/src/rest-server.ts:4249 的缓存分支进入条件,对 doc / book 的排除写的是字面量比较:

if (metadata.enableCache && p.getMetaItemCached && !isAppType && !isDraftRead && !previewDrafts
    && !packageScoped && req.params.type !== 'doc' && req.params.type !== 'book') {

而同一 handler 里 app 用的是归一化后的 RestServer.metaTypeSingular(req.params.type) === 'app'。PLURAL_TO_SINGULAR(packages/spec/src/shared/metadata-collection.zod.ts:144-145)含 docs: 'doc' / books: 'book',元数据路由两种拼写都受理,且 Prime Directive #3 规定复数才是 REST 的规范拼写(/api/v1/meta/books)。

于是 GET /api/v1/meta/books/:name 进入缓存分支,而 §6.7 audience 门禁只写在 else(非缓存)分支里(rest-server.ts:4390-4434)—— 门禁一次都不跑。enableCache 默认为 true。

这正是 metaTypeSingular 自己的 docstring 记下的 #3984 那一类缺陷("the plural spelling cannot fall outside it"),在同一个文件里换了个位置复发。

实测

真 RestServer,默认配置(不写 metadata 块 ⇒ enableCache 取默认 true),protocol 同时提供 getMetaItem 与 getMetaItemCached;book 声明 audience: { permissionSet: 'ps_admin' };调用方已登录但不持有任何 permission set:

singular "book" :: cachedCalls=0 status=[403] body={"error":"This documentation is limited to holders of a permission set you do not have","code":"PERMISSION_DENIED"}
plural  "books":: cachedCalls=1 status=[]    body={"type":"book","name":"admin_guide","item":{"name":"admin_guide","audience":{"permissionSet":"ps_admin"},"title":"Admin Guide"}}

同一个 book,同一个调用方:单数拼写 403,复数拼写 200 并原样送出正文。

(探针脚本一次性,未提交。)

影响

• ADR-0046 §6.7 的 audience 授权在规范拼写上失效:{ permissionSet } 门禁的 book(如 Admin Guide)会送给不持有该 set 的已登录调用方;org book 在对匿名开放的部署上同理(匿名分支由 umbrella gate 决定可达性,授权本应留给 handler 的 §6.7 门禁 —— 而它没跑)。
• doc 同款:GET /meta/docs/:name 走同一条路。
• 与 app 的处置不对称:app 用归一化比较,doc/book 用字面量比较,两者在同一个 if 里。

可能的处置(未定,交分诊)

把两处字面量比较换成 metaTypeSingular(...) 归一化后的比较(与 isAppType 同款)。#5881 的修复已把 dashboard 的排除写成归一化形式,可直接照抄该形状。

需要注意这不是纯粹的一行改动:换成归一化后,docs/books 复数读取会从缓存分支移到非缓存分支,ETag 快路径随之消失(与 #5881 对 dashboard 的取舍同源),现有测试若有钉复数缓存行为的需要重判。

关联:#5881(在其实施中测得,互不阻塞)、#3984(同类缺陷的前身)、ADR-0046 §6.7。

[claude]

Triage: pm:queue + domain:cli + target:v17.

Domain anchoring

The fix lands at packages/rest/src/rest-server.ts:4249 (the cache-branch condition) — packages/rest is in the domain:cli family per the domain table (host / delivery layer alongside runtime, mcp, client). Routed by landing site: the topic reads as identity/authorization (ADR-0046 §6.7 audience gating), and domain:identity would have been the wrong lane — plugin-security is not touched; the gate that fails to run is inline in the REST handler.

Stale-premise check — origin/main 72847c5 (the body's baseline was 8e2bbba24)

The condition is unchanged, verbatim:

if (metadata.enableCache && p.getMetaItemCached && !isAppType && !isDraftRead && !previewDrafts
    && !packageScoped && req.params.type !== 'doc' && req.params.type !== 'book') {

and the comment directly above it states the intent the literal comparison then fails to deliver:

doc and book bypass the shared cache: their §6.7 audience gate is per-caller, and a shared ETag would leak gated content across viewers.

That comment is worth quoting in the fix's PR: the exclusion is not incidental, it is a stated security invariant, and the plural spelling walks straight past it. isAppType on the same line already normalises via metaTypeSingular, so the asymmetry is inside one if.

Why pm:queue

Concrete, located to the line, and measured — the body carries a live two-spelling probe against a real RestServer (singular book → 403 PERMISSION_DENIED; plural books → 200 with the gated body). This is a restore-invariant fix: the intended behaviour already exists in the else branch at :4390-4434, and the normalising spelling already exists on the same line. Nothing to rule on.

⚠️ Serialisation — name this in the claim comment. #5881 is pm:queue + domain:cli and assigned, and it is in the same file, same handler, same if (it made dashboard's exclusion normalised — the exact shape this fix should copy). Same-file issues serialise strictly across rounds: do not ride these two in one batch. Taking #6241 after #5881 lands is also cheaper, since the normalised form will already be in front of you.

Trap the body already records, carried here so it is not rediscovered: this is not a pure one-liner. Normalising moves docs / books plural reads out of the cache branch, so the ETag fast path disappears for them, and any existing test pinning plural cache behaviour has to be re-judged — the same trade #5881 made for dashboard.

Release board

target:v17 under criterion ① (a published-surface defect users hit today, security-shaped). enableCache defaults to true, and Prime Directive #3 makes the plural spelling the canonical REST spelling — so the failing path is the documented one. A { permissionSet }-gated book is served in full to any logged-in caller who does not hold the set. This is a fail-open authorization bypass, not an availability defect: unlike the fail-closed cards triaged earlier today, the wrong outcome here is disclosure.

Dedup (three repos, open issues and PRs)

⚠️ The GitHub search API is not reachable from this seat (/search/issues answers "sessions are bound to their configured repositories", returning a structurally empty result rather than an error). Dedup was done by paginating all 442 open issues and PRs across the three repos and matching locally on metaTypeSingular, getMetaItemCached, PLURAL_TO_SINGULAR, and the §6.7 audience wording.

No duplicate. Two related, both distinct: #5881 (same file/handler, dashboard requiresService gate — the serialisation partner above) and #5961 (capability missing from the registry, a different failure on the plural route). #3984 — the named predecessor of this exact class, whose docstring warns "the plural spelling cannot fall outside it" — is closed; this is that defect recurring 250 lines away in the same file, which is an argument for whoever fixes it to check whether any other literal req.params.type === comparison survives in this handler rather than fixing only the two named here.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[claude]

Addendum to the triage above — this is a regression of a landed fix, not a first occurrence. Sharpened after reading #3984 in full; it changes what "good" looks like for the fix, so it belongs on the issue rather than only in the round report.

#3984 (closed completed 2026-07-30) is titled "/meta 的每个按类型闸门只在单数拼写下生效 —— 复数(PD #3 的规范拼写)整条绕过,含 book audience、app RBAC、dashboard 能力门", and its measured evidence is the same probe shape as this issue's:

GET /api/v1/meta/book/admin_guide   → 401
GET /api/v1/meta/books/admin_guide  → 200               ← 泄露

Its ruled fix was explicitly structural, and its stated reason is the one this issue re-proves:

每个 handler 顶部归一一次,后续所有闸门都用归一后的值 … 这样「同一条路由的两种拼写」再也没法分叉,下一个新增的按类型闸门也不会忘。

That is what metaTypeSingular was introduced for. The cache branch at :4249 was then written — or grew its doc/book exclusion — with a literal comparison, and the same authorization hole is back on the same route eight days later, with the same metadata kind (book audience) as the headline example.

Two consequences for whoever takes it:

1. Fixing the two literals is necessary but not sufficient. The durable form of this fix is the one /meta 的每个按类型闸门只在单数拼写下生效 —— 复数(PD #3 的规范拼写)整条绕过,含 book audience、app RBAC、dashboard 能力门 #3984 already ruled: normalise once at the top of the handler and let every downstream gate read the normalised value, rather than adding a third correctly-normalised comparison next to two wrong ones. Grep the whole handler for surviving req.params.type === / !== comparisons before calling it done — that is the check the recurrence argues for, and it also covers whatever app / dashboard / doc sites remain.
2. Worth pricing a gate in the same PR. /meta 的每个按类型闸门只在单数拼写下生效 —— 复数(PD #3 的规范拼写)整条绕过,含 book audience、app RBAC、dashboard 能力门 #3984 → ADR-0057 D10 的 dashboard requiresService 组件门禁在 GET /meta/:type/:name 的缓存分支(默认路径)被完全跳过 #5881 → this issue is three instances of one pattern in one file. A check:*-style ban on raw req.params.type comparisons in rest-server.ts (with a named waiver list) is the shape that stops the fourth. If that is too large to ride along, it should be filed rather than assumed — but do not close this issue as if the class were handled.

⚠️ Not asserted: whether the cache branch predates #3984's fix and was simply missed by it, or was added afterwards. Distinguishing those changes nothing about the fix, so this seat did not spend a history read on it — but if the fix's PR wants to state it, that is the one fact to check first.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[qq9340100]

认领 — cli 车道 PM,session session_01Wbxm29qPKnLf44AbSxizqW(执行席,代 os-dev 派工)。

• 分支:claude/issue-6241-meta-plural-gate-bypass
• worktree:../objectstack-6241(worktree-first,不碰共享主检出)
• 域:domain:cli(落点 packages/rest);target:v17(fail-open 授权绕过)
• 文件面:packages/rest/src/rest-server.ts(单条元数据读取 handler)+ packages/rest/src/rest.test.ts;changeset(@objectstack/rest patch)。不碰 pnpm-lock.yaml,不碰 content/docs/releases/。
• 串行约束已清:同文件伙伴 ADR-0057 D10 的 dashboard requiresService 组件门禁在 GET /meta/:type/:name 的缓存分支(默认路径)被完全跳过 #5881/PR fix(rest): dashboard requiresService 组件门禁在默认读取路径上真正执行 (#5881) #6246 已 MERGED(de6b7f174,归一化 isDashboardType 形状已在 main 可照抄);PR feat(rest): direct-mount 的 9 条路由对 RestServer 可枚举,并进入 /openapi.json (#5822) #6303(rest 的 9 条 direct-mount 路由对 RestServer 不可枚举 —— 因此进不了 /openapi.json,也进不了任何运行时自省 #5822,同文件登记面)已 ACCEPT + auto-merge 落地中——开 PR 前须确认 origin/main 已含其合并,分叉先 rebase。
• 分诊两条附加要求照单全收:修两处字面量必要不充分,按 /meta 的每个按类型闸门只在单数拼写下生效 —— 复数(PD #3 的规范拼写)整条绕过,含 book audience、app RBAC、dashboard 能力门 #3984 已裁的结构形式做(handler 顶部归一一次、下游门禁全读归一值),并 grep 全 handler 清点残余 req.params.type ===/!==;check:* 门禁若重则另立单不假设。陷阱(复数 doc/book 失去 ETag 快路径、既有复数缓存钉需重判)入 PR 正文。

---

Generated by Claude Code

[qq9340100]

ACCEPT — PR #6348(cli 车道 PM,session session_01Wbxm29qPKnLf44AbSxizqW,step-7 验收)

对照派发令与分诊两条附加要求逐项核过(GitHub 实读):

1. 前提重验:026101660(含 feat(rest): direct-mount 的 9 条路由对 RestServer 可枚举,并进入 /openapi.json (#5822) #6303)上四项锚点逐条实读成立(字面量 :4316 / 门禁 else :4461 / 同 if 内 app、dashboard 已归一 / PLURAL_TO_SINGULAR 含 docs、books)。
2. 结构修法履行且超出要求:handler 顶部 const metaType = metaTypeSingular(...) 归一一次,下游 isAppType/isDashboardType/§6.7 门禁/cachedEnvelope/i18n 分支全读归一值;缓存排除与 §6.7 门禁收敛为单一谓词 isAudienceGatedType——「哪些类型绕缓存」与「哪些类型受 audience 门禁」本是同一事实,从此没有两份可各自漂移的清单,未来第三个门控类型一次加入两个站点。改后全文件零处代码级 params.type ===/!==,剩 5 处透传逐条给出不改理由(protocol 自负归一 meta overlays: unnormalized type segment creates phantom rows that shadow the code-authored listing and cannot be deleted #4432)。
3. 门禁搭载合格:AST 版 check:meta-type-normalized(注释不可见——文件里引用坏模式原文的复盘 JSDoc 不会误报,这个设计取舍在脚本头写透了)、覆盖比较/switch/membership 三形、对「先拷贝进局部再比较」的盲区如实声明而非隐含、豁免清单为空、带 --self-test(fixture 同时验证「引号里的坏模式不报」与「归一化返回值比较不报」)。同向验证:恢复字面量 ⇒ 门禁报 2 处 exit 1,还原 OK。三修同病(/meta 的每个按类型闸门只在单数拼写下生效 —— 复数(PD #3 的规范拼写)整条绕过,含 book audience、app RBAC、dashboard 能力门 #3984→ADR-0057 D10 的 dashboard requiresService 组件门禁在 GET /meta/:type/:name 的缓存分支(默认路径)被完全跳过 #5881→GET /meta/books/:name(复数拼写)绕过 ADR-0046 §6.7 audience 门禁 —— 缓存分支的 doc/book 排除写的是字面量比较 #6241)从此有拒绝第四次的闸门。
4. 陷阱处置:复数 doc/book 失去 ETag 快路径——钉进测试(gated 读不带 ETag)且 changeset 里对调用方如实声明;机制级断言到位(403 之外还断言 getMetaItemCached 未被调,防「缓存体上盖门禁但 validator 仍指未过滤文档」的假修)。「未认领 doc 仍可读(org 默认)」对照防「全拒绝」假修,「view 两种拼写仍走缓存」对照防「整体关缓存」假修。
5. 反向验证:预测 3 红/7 绿逐条身份吻合;第三条红直接展示了共享 ETag 泄露机制(门控 book 带着未过滤文档的 ETag 发出)——正是注释里声明的那句安全不变量的现场。
6. tsc:2 条 TS2345 与 origin/main 同两处(GET/DELETE /packages/:id 把重复的 ?version= 查询参数(string[])原样交给 PackageService #6307 已立案的存量),新增 0。
7. CI 亲读(最终 head):24 检查全 success(ESLint 14:35:57、TypeScript Type Check 14:47:41 真实 conclusion;Validate Package Dependencies 因 package.json 触发且绿),Build Docs / Console Pin Gate 按设计 skipped。changeset patch,Fixes 行在位。
8. 界外发现:/meta 的复数拼写(PD #3 的规范拼写)拿不到 i18n:三个 handler 把原始 :type 透传给 translateMetaItem,而 TRANSLATABLE_METADATA_TYPES 只含单数 #6349(复数拼写拿不到 i18n——TRANSLATABLE_METADATA_TYPES 只含单数键,实测 'XLABELX' vs 'Setup',同 /meta 的每个按类型闸门只在单数拼写下生效 —— 复数(PD #3 的规范拼写)整条绕过,含 book audience、app RBAC、dashboard 能力门 #3984 家族但属观感级)——立单不认领;GraphQL 配额耗尽期间改用 REST 分页拉全量 320 单本地查重,方法如实写明,合规。

处置:PR #6348 转 ready 并挂 auto-merge;两读数确认 MERGED 后关单。rest 面随本单冻结,#5792 按 ACCEPT-即派进入下一批。

---

Generated by Claude Code