rest: filterAppForUser treats app hidden flag as builder-only access gate — built-in account app returns 404 for all normal users

[baozhoutao]

现象(17.0.0-rc.1,真机 A/B 实测)

@objectstack/rest 的 filterAppForUser():

if (item.hidden === true && !sysPerms.has('studio.access') && !sysPerms.has('setup.access')) return null;

把应用的 hidden(语义=不进应用切换器的导航呈现开关)当成了「builder-only / 未发布」的访问开关。而平台内置 account(账户)应用按设计就是 hidden: true(@objectstack/platform-objects 的 ACCOUNT_APP,注释:「Surface via the avatar dropdown, not the App Switcher」;console 头像菜单也特判 e.name !== 'account' 单独给它「个人资料」入口)。

结果:

• 普通用户 GET /api/v1/meta/app 中 account 应用被整个抹掉,点头像 →「个人资料」→ 整屏「App not available — it may still be publishing」;改密码/头像/已关联账户/活动会话/收件箱全部不可达;
• 持 setup.access 的管理员一切正常(只挂 Unpublished 黄条)→ 极易被当成偶发故障,长期无人发现。

期望

hidden 只影响导航呈现(应用切换器/我的应用),不参与访问判定;或给内置 account 应用豁免。

复现

1. 空库启动 17.0.0-rc.1,建任意普通用户(无 studio/setup.access);
2. 普通用户登录 console,点头像 → 个人资料 → App not available;同会话 GET /api/v1/meta/app 无 account。

下游临时对策(修复后可整体删除)

os-project-titanwind-ehr 登记 PLAT-DEF-040,PR steedos-labs/os-project-titanwind-ehr#745:启动插件以系统身份幂等下发 {hidden:false} 的 env 级 overlay(即 UI「Publish」按钮做的事)。副作用是「账户」出现在应用切换器——正因如此更说明 hidden 的两个语义(导航 vs 访问)必须拆开。

[baozhoutao]

Claim: PM loop round 1 (explicit dispatch)
Branch: claude/issue-4829-app-hidden-nav-only
Worktree: framework-issue-4829

Triage note: gate confirmed still present at packages/rest/src/rest-server.ts:1841, with a comment citing ADR-0045 (hidden: true = unpublished, externally invisible). That reading conflicts with platform-objects ACCOUNT_APP's authored hidden: true ("surface via avatar dropdown, not the App Switcher"). The fix must resolve the two semantics contract-first, not special-case blindly — agent will analyze against ADR-0045 and stop with needs_decision if the ADR genuinely mandates the current behavior.

[baozhoutao]

Takeover: the 09:27 claim's session ended with no remote branch and no PR — presumed dead. This PM session (worktree objectstack-pm-dispatch-issues-8b2071) takes over the claim per maintainer's explicit dispatch instruction, reusing branch claude/issue-4829-app-hidden-nav-only. Dispatching now.

[baozhoutao]

Escalation: App.hidden 的语义冲突需要维护者裁决

开发 agent 已完成勘察,未写代码——两份已记录合同在同一个键上正面冲突,任一解法都要新增公共 spec 字段并修订 ADR,超出单个 PR 可单方面裁决的范围。

背景(证据链,均已核实)

1. App.hidden 与 ACCOUNT_APP 同一 commit 诞生(74470ad, 2026-05-28)。spec Zod 文档(packages/spec/src/ui/app.zod.ts:1072-1086)明确定义为纯导航语义:"Hidden apps stay fully routable and permission-checked",shell 经头像菜单呈现。
2. ADR-0045(Accepted 2026-06-12, fa65285)把 hidden:true 重定义为 unpublished/外部不可见,依据是 "ADR-0019 launcher contract (hidden, active)"——但 ADR-0019 全文不含 hidden 一词,即 ADR-0045 引用了不存在的合同,且全文未提 account/头像菜单,从未有意识地废除导航语义。
3. 两套语义各有完整活体实现:导航侧 = ACCOUNT_APP + console 头像菜单;访问侧 = rest gate(packages/rest/src/rest-server.ts:1841)+ publish-drafts 翻转(packages/runtime/src/domains/packages.ts:197-227)+ AI 物化路径。

后果(本 issue 现象):普通用户的 account 应用被 REST 层整个抹掉,改密码/头像/会话管理全部 404;持 setup.access 的管理员无感,长期无人发现。

待决问题

App.hidden 的唯一语义应是哪个?unpublished(访问门)信号应落在哪里?

方案 A —— hidden 恢复纯导航语义(spec 的出生合同),unpublished 另立机器管理键
建议:app 上新增 machine-managed 布尔键,从 authorable input schema 排除,仅由 AI 物化路径写入、publish-drafts 清除;rest gate 改判该键。改动面:spec 新键 + ADR-0045 修订 + cloud 物化写入点 + runtime 翻转点 + rest gate + objectui Unpublished 横幅/Publish 按钮;存量 sys_metadata 行经 ADR-0087 转换(stored 行的 hidden:true 在现政权下语义唯一 = unpublished,可机械改写;代码态 ACCOUNT_APP 不入 sys_metadata,无歧义)。

• 轴①(长期架构):呈现与生命周期是正交概念,合并进一个布尔正是本 bug 根因。A 保留 ADR-0045 全部机制(materialize-invisible、publish=翻转、外部 404),只换承载字段,并把悬空引用修正为真实合同——是修正记录,不是推翻决定。
• 轴②(AI 难写错):hidden:true 是 AI/人类为个人设置类应用会自然写出的键(spec 文档至今就这么教)。A 政权下 unpublished 为机器专属键,input schema 不收,结构性杜绝误写。

方案 B —— 维持 ADR-0045 的 hidden=unpublished,另铸导航呈现键(如 showInLauncher:false)
改 ACCOUNT_APP 授权、重写 spec 文档字符串、objectui 切换器 + 头像菜单改读新键。改动面同样跨三仓。

• 轴①:把误导性命名固化为公共合同,此后每个读到 hidden 的人都要背注解,长期成本显著。
• 轴②:AI 自然写出的 hidden:true = 全员 404,且授权时零反馈,本类 bug 必然复发。

方案 C —— rest 层特判 name==='account':已否决,无合同可指,纯打补丁。

PM 推荐

A,两轴同向,无需权衡。附属子问题(若采纳 A):unpublished 键放 app 级(忠实 ADR-0045 逐 app 翻转,改动最小)还是 package 级(概念上发布单元是包,但要改 gate 取数路径)——推荐 app 级。无论 A/B,均需修订 ADR-0045 并在 gate/翻转点留 ADR 锚(scripts/adr-anchors.json)。

关联

• 分支已认领未产码:claude/issue-4829-app-hidden-nav-only
• 下游临时对策:steedos-labs/os-project-titanwind-ehr PLAT-DEF-040(PR feat: adapt better-auth adapter and objects for sys_ prefix naming convention #745,修复后可整体删除)

[baozhoutao]

Maintainer decision: 暂缓处理(2026-08-03)。issue 保持 needs-user-decision 挂起,不进入派发队列;上面的两轴分析为裁决时的输入。下游 titanwind 的 PLAT-DEF-040 overlay 临时对策继续生效。

[xuyushun441-sys]

维护者裁决(2026-08-04,经 PM 会话 session_018iARDqtrhQgz6fVHDeDkbQ 转达并留档)—— 方向 A1,v17 后实施

本条取代 2026-08-03 09:41 的「暂缓处理」记录。裁决过程说明:PM 曾按议题正文的三选项框架建议"hidden 直接退出访问判定",派发后 dev 正确地停手拒做并核出两个否定该方案的事实 —— ① 该访问门是 ADR-0045 §3(Accepted)的正文机制,带 4 个 pin 测试与 publish-drafts 的翻转实现,直接删除等于用 patch 静默推翻已接受的 ADR(PD #13 禁止);② 真正的病根是 spec 与 ADR 对同一个键各说各话:app.zod.ts:1073-1086 给 hidden 写的出生合同是纯导航("Hidden apps stay fully routable and permission-checked",且点名 Account 类应用),与 ADR-0045 §3 正面冲突。维护者据更正后的分析重新拍板:

裁决内容

1. 方向:A1(新机器管理键承载发布门) —— app 上新增机器专属键(如 unpublished,命名实施时定),从可作者化 input schema 排除:仅 AI 物化路径写入、publish-drafts 清除;REST 访问门改判该键;hidden 回归 spec 出生合同的纯导航语义。同时:修订 ADR-0045(修订状态行,非新 ADR)、在 rest-server.ts 门本体与 runtime/domains/packages.ts 翻转点补 adr-anchors 锚(dev 已核实两处均无锚,正是 PD [WIP] Add Chinese version of the documentation #13 的复发形态)、存量 sys_metadata 行走 ADR-0087 转换、顺带修 ADR-0045 对 ADR-0019 的悬空引用。键放 app 级(忠实 ADR-0045 逐 app 翻转)。
2. 时机:v17 发布之后实施 —— 跨 spec/runtime/rest(+cloud/objectui)的协议变更不进发版窗口。期间下游 titanwind PLAT-DEF-040 的 overlay 临时对策继续有效,修复落地后整体删除。
3. 车道:含 spec 可作者化面变更,实施需 spec 车道牵头或协同;本条裁决供其排批,实施单届时按 ADR-0087/retirement 流程拆分。

归档要点(取自停手 dev 的核查,供实施者直接使用)

• 门本体:packages/rest/src/rest-server.ts:1837-1843;pin 测试:packages/rest/src/rest.test.ts:2890-2922;publish 翻转:packages/runtime/src/domains/packages.ts:195-234;spec 合同:packages/spec/src/ui/app.zod.ts:1073-1086;ADR:docs/adr/0045-...md:96-102, 171-173。
• 两轴论证:呈现与生命周期正交,压进一个布尔是病根;机器专属键让 AI 写出的 hidden:true 结构性地只影响导航(防误写),而删门方案的失败方向是误露且静默,比现状更糟。

needs-user-decision 摘除,改挂 protocol:breaking 待 spec 车道排批。

---

Generated by Claude Code