Action.requiredPermissions 在 Console 端形同虚设：会话不下发 systemPermissions + 客户端 fail-open（17.0.0-rc.0）

[baozhoutao]

版本

@objectstack/{spec,runtime,console}@17.0.0-rc.0

期望（按 spec 注释）

src/ui/action.zod.ts 里 requiredPermissions 的注释写明这是 ADR-0066 D4 的双面门禁：

System capabilities required to INVOKE this action — a dual-surface gate from ONE declaration: the server (action route) rejects the call with 403 when the caller's systemPermissions don't cover these (the source of truth), and the objectui ActionRunner hides/disables the button using the same requirement.

即：一处声明 → 服务端 403 + 客户端隐藏/禁用按钮。配套的授予侧是权限集的 systemPermissions（src/security/permission.zod.ts:279）。

实测结果：按钮照常显示、照常可点

复现（本地 dev，objectstack dev，Console 以内置管理员登录）：

1. 给某对象的 record_header 动作加一个谁都没有的能力：

{
 name: 'set_parallel_positions',
 label: '设置并行会审岗位',
 locations: ['record_header'],
 type: 'api',
 method: 'POST',
 target: '/api/v1/ts/record-action/<obj>/${param._rowRecord.id}',
 requiredPermissions: ['ehr_probe_capability'], // 没有任何权限集声明过它
 visible: "record.approval_stage == 'qc_director' && record.approval_status == 'pending'",
}

2. objectstack compile → 打开该记录详情页。
3. 按钮正常出现在页头，可点、可提交。

原因（两处）

① 客户端 fail-open

packages/console 打包产物 dist/assets/framework-*.js 的 getActionsForLocation：

.filter(e => {
 let t = e.action.requiredPermissions;
 if (!Array.isArray(t) || t.length === 0) return true;
 let n = this.runner.getContext()?.user?.systemPermissions;
 return !Array.isArray(n) || t.every(e => n.includes(e)); // ← 拿不到就放行
})

会话里没有 systemPermissions 时直接放行。对「隐藏按钮」这类安全语义，fail-open 等于门禁不存在。

② 会话根本没带 systemPermissions

同一页面里 Console 连续两次 POST /api/v1/security/explain → 401 Unauthorized（已登录的 admin 会话），客户端上下文的 user 上也取不到 systemPermissions。服务端 resolveAuthzContext 明明解析出了 { positions, permissions, systemPermissions }（packages/runtime dist index.js:5155 附近），但这份信息没有到达 Console。

附带：服务端那半边并不覆盖所有 action

actionPermissionError 只在平台自己的 action 调用路径上生效（packages/runtime dist index.js:2922 / 4393 / 4752，即 ql.executeAction 路由与 MCP/AI 路径）。type: 'api' 指向自建 endpoint 的动作不经过它，因此这类动作即使声明了 requiredPermissions 也没有任何服务端兜底。spec 注释里「the server (action route) rejects…the source of truth」的措辞容易让人误以为任何 action 都被兜底。

影响

requiredPermissions 是目前唯一的声明式「按能力/岗位控制按钮显隐」手段——动作的 visible 只绑 record 命名空间（写 has(current_user.id) 直接编译失败：bare reference current_user — … binds the record as the record namespace, not at top level；运行期实测 has(user.id) / has(user.permissionSets) / has(user.positions) 的探针按钮全部不显示，只有 visible: 'true' 显示）。这条路一旦空转，应用侧就只能自己写 Hook 在服务端兜底，UI 上无法把按钮对无权用户藏起来。

建议

1. 会话（或 /api/v1/security/explain）向 Console 下发调用方的 effective systemPermissions，并修掉已登录会话下 security/explain 401。
2. 客户端在拿不到 systemPermissions 时 fail-closed（或至少提供显式配置），避免「声明了门禁但静默失效」。
3. 文档/注释明确：服务端 403 只覆盖平台 action 路由，type: 'api' 自建 endpoint 需自行校验。

[baozhoutao]

核实结论：不是误报，三条都成立。但根因比报告里定位的更广 —— 实测发现 ADR-0066 D4 的 UI 门禁在四个 action 界面全都没生效，不止 record_header。

根因

requiredPermissions 的 UI 半边只实现在 ActionEngine.getActionsForLocation 里，而这些 location 实际渲染所在的界面没有一个走引擎 —— 它们各自实现了过滤器（只看 visible/disabled）：

界面	location	渲染器	修前
记录页头	record_header / record_more	page:header	无门禁
列表工具栏	list_toolbar	action:bar	无门禁
行 ⋯ 菜单	list_item	RowActionMenu	无门禁
记录区块	record_section	走引擎，但喂进去的 user 没有 systemPermissions	fail-open

最后一行是报告里推断的 fail-open，机制判断正确，但不是「会话没下发 systemPermissions」：服务端 /api/v1/auth/me/permissions 是带 systemPermissions 的，Console 也挂了 MePermissionsProvider 存了下来。问题是 RecordDetailView 另起了一个会遮蔽外层的 <ActionProvider>，只喂了 {id, name, avatar} 把它盖掉了。在 17.0.0-rc.0 的实际产物里核实过：RecordDetailView-*.js 里 systemPermissions 出现 0 次。

security/explain 401

useRecordEditable 用的是裸 fetch(..., {credentials:'include'})，没走 createAuthenticatedFetch —— 不带 Authorization / tenant 头。bearer-token 会话的凭据在 header 不在 cookie，所以已登录 admin 也 401，随后 fail-open，这个 hook 在它本该服务的部署里等于没跑。服务端路由本身没问题。

服务端覆盖范围

属实。actionPermissionError 只挂在平台 action 路由（POST /api/v1/actions/<object>/<action>）和 MCP/AI 路径上；type:'api' 打自建 endpoint 是浏览器直连，平台看不到这个请求。spec 注释的措辞确实误导。

修复

• objectui objectstack-ai/objectui#2965 —— 新增共享 hook useCapabilityGate()，三个自建过滤器统一走它（语义与引擎一致：缺一个能力就隐藏；空数组=「什么都没有」照样拦；未知才 fail-open）；RecordDetailView 补上 systemPermissions（且只在权限真正加载完后才喂，否则无 PermissionProvider 的独立嵌入会变成全隐藏）；useRecordEditable 改走宿主的已认证 fetch。
• framework docs(spec): state what the action requiredPermissions server gate does NOT cover (#3923) #3943 —— 注释 / describe() / ADR-0066 D4 写明服务端 403 只覆盖平台 action 路由，type:'api' 自建 endpoint 必须自行校验。

实测

showcase 起后端 + objectui 源码 console，admin 实持 setup.access。放两个探针动作（一个要无人持有的能力，一个要 setup.access），四个界面两侧都验：denied 隐藏、allowed 保留。并做了 A/B —— 撤掉 RecordDetailView 的修复刷新，PROBE Section Denied 立刻出现，恢复后消失。

explain 请求现在带 Authorization: Bearer + X-Tenant-ID + Accept-Language（运行时抓取），修前只有 cookie，而该会话根本没有 auth cookie。需要说明：本地 dev 服务端策略较宽松，裸 fetch 也返回 200，所以报告里的 401 没能在 showcase 上复现 —— 401 的成因已定位并由单测覆盖，但那一步是推断而非本地复现。

补充：visible 里用不了用户信息

顺带核实了报告末尾那条。CEL 的 SCOPE_ROOTS 里有 user/os 但没有 current_user，所以编译失败是对的；而 has(user.id) 运行期也不显示，是因为按钮的 visible 走 useCondition（record 作用域），那里没绑 user。这条是独立问题，不在上述两个 PR 范围内，建议单开一条。