元数据不可解析时的 fail-open 残余风险评估(api-exposure / rest-server)

[os-zhuang]

#3391 的独立 follow-up ②。

背景

API 曝露 gate 在元数据不可解析/暂不可用时故意 fail-open(回退到 schema 默认 apiEnabled:true / 无 apiMethods),以免元数据短暂不可用时阻断流量。位置:

• packages/runtime/src/api-exposure.ts(checkApiExposure:def 为空 → { allowed: true })。
• packages/rest/src/rest-server.ts(loadObjectItems 取不到元数据时返回 [] → gate 默认放行;enforceApiAccess 对未知对象放行交由数据层 404)。

目标

评估这条 fail-open 路径的残余安全风险并决定是否收紧:

• 枚举「元数据取不到」的真实成因(冷启动、注册竞态、scoped 服务未就绪、真实故障),判断哪些应 fail-closed。
• 权衡:fail-closed 会不会在正常启动窗口误伤流量?是否可用「元数据已就绪」信号区分「暂时缺」与「确实没有」。
• 若收紧,给出分级策略(例如:对象存在但 enable 不可解析 → fail-closed;整个元数据服务未就绪 → 短暂 fail-open + 告警)。

非阻塞项 —— P1 未改变这条既有行为,此 issue 仅做评估 + 决策。

关联:#3391、#3498、ADR-0049。

[os-zhuang]

评估 + 决策(#3391 follow-up ②)

结论:残余风险 = 低,现行 fail-open 可接受;唯一缺口是"静默",已补可观测性。

关键框架

API 曝露 gate(apiEnabled/apiMethods → checkApiExposure / enforceApiAccess)是曝露面控制,不是授权边界。真正的授权边界是 auth + ObjectQL 安全中间件(CRUD/FLS/RLS),它在数据调用上无条件执行,与 gate 结果无关。因此元数据缺失时 fail-open 不会绕过数据授权——最坏情况只是「作者想从 API 隐藏的某操作」短暂可达,且仍受完整访问控制。

① 「元数据取不到」的成因分级

成因	性质	应对
冷启动 / 注册竞态 / scoped kernel 预热	瞬态	fail-open(fail-closed 会在启动窗口 405 掉一切,零安全收益)
元数据存储宕机 / schema 文档损坏	持续真实故障	fail-open + 记日志(本轮补)
对象未注册(未知对象)	非本议题	交数据层 404(既有,正确)
对象可解析但 enable/apiMethods 存在却不可读(非数组)	理论	见 ③

② 权衡:fail-closed 会否误伤启动窗口?

会。loadObjectItems/checkApiExposure 在每个受门控请求上跑;若在整个元数据服务未就绪时 fail-closed,则每次冷启动都 405 全量流量。而「元数据已就绪」信号存在(getMetaItems 抛错 vs 返回 [] vs 返回不含该对象),但为一个非授权边界的控制建就绪门属过度工程。区分「真故障 vs 空 registry」用抛错/空返回即可——这正是本轮采用的信号。

③ 分级策略(决策)

• 整个元数据服务不可用 → 保持 fail-open;调用方(REST loadObjectItems)对抛出的读记 warn,使持续故障可观测。→ 本轮 PR fix(rest,runtime): make api-exposure metadata fail-open observable (#3545) #3567 落地。
• 对象可解析、但曝露策略存在却不可读(apiMethods 非数组)→ resolveEffectiveApiMethods(api-derivation.ts:238-239) 目前静默当 unrestricted(静默放宽)。但经 Zod 校验的注册路径不可达(仅 raw/带外写入能造成),故把「收紧到 fail-closed」推迟到曝露语义窗口 P2:ApiMethod 枚举收缩至 6 原语(breaking,独立版本) #3543 一并做,不在此单方面改 security-gate 默认。

本轮落地

PR #3567:纯可观测性 + 决策记录,对 gate 行为零变更。rest 的 loadObjectItems 对抛错读记 warn(空 registry 保持静默);runtime 的 api-exposure.ts 把本决策写进契约 doc。新增 3 个回归用例。

---

Generated by Claude Code