plugin-auth: break-glass 守卫 —— SCIM/ban 不得停用最后一个管理员(ADR-0024 D5.2,cloud#621 转入)

[claude]

来源:跨座位转移件。 Part of objectstack-ai/cloud#621(Enterprise Identity SCIM — V1 follow-ups)的第 1 项。cloud#621 的其余各项留在 cloud 队列;这一项落点在本仓(packages/plugins/plugin-auth),按 One-main-backlog 规则转来。

设计依据:ADR-0024 D5.2(cloud ADR-0071 的 SCIM V1 已落地,机制在 framework plugin-auth,OS_SCIM_ENABLED 默认关)。原单把本项标为 non-negotiable。

问题

SCIM / ban 路径必须永远不能停用环境 owner 或最后一个本地管理员。一次 IdP 误配置、或一次过宽的 deprovision,就足以让整个组织把自己锁在门外 —— 而 SCIM 的写入是外部系统驱动的,没有人在回车前看一眼。

要求(照抄原单)

1. sys_user 的 beforeUpdate 钩子:当一次更新会导致剩余 0 个未被 ban 的管理员时,拒绝 banned=true;
2. enforced SSO 模式不得停用最后一个本地管理员的密码 —— 这是 IdP 故障时的逃生口;
3. 测试:尝试 ban 最后一个管理员 → 被拒;IdP 故障路径下 owner 的本地登录仍可用。

⚠️ 派发前必做的前提核对(分诊座位已做一轮,结论是「部分可能已存在」)

origin/main 上 packages/plugins/plugin-auth/src/auth-manager.ts 已经有 break-glass 相关代码,但只覆盖密码那一半:

:1241   // env owner / a local admin keeps one as the break-glass escape hatch
:3846   * owner back, so the break-glass admin never loses self-service password

⇒ 第 2 项(密码逃生口)看起来已有实现;而第 1 项(ban 守卫)未搜到对应逻辑 —— 未命中「剩余 0 个未 ban 管理员则拒绝」这一形状的判定。

⛔ 请 dev 在动手前逐条复核这三项的现状,只实现真正缺失的部分:范围可能显著小于正文。核对方法用 git grep <pattern> origin/main -- packages/plugins/plugin-auth,⛔ 不要在共享主检出的工作树里 grep(它的 HEAD 由别的 agent 摆布,可能落后数十提交)。

相关

• 原单:objectstack-ai/cloud#621(其余各项:token-admin UI、cloud-managed gate 验证、source-marking 归并、真实 IdP E2E)
• ⚠️ SCIM: 停在 @better-auth/scim rc.1,等正式版再整体迁移 —— rc.2 换掉了整套模型 #3653(SCIM 停在 @better-auth/scim rc.1 等正式版,pm:on-hold)—— 本项是本仓自己的 sys_user 钩子,⛔ 不依赖 @better-auth/scim 的版本,故不受 SCIM: 停在 @better-auth/scim rc.1,等正式版再整体迁移 —— rc.2 换掉了整套模型 #3653 挂起影响,可独立落地。若实现中发现必须触碰 @better-auth/scim 的模型面,请停下并回报,那一刻 SCIM: 停在 @better-auth/scim rc.1,等正式版再整体迁移 —— rc.2 换掉了整套模型 #3653 才成为前置。
• plugin-auth: convertWhere() 整体忽略 better-auth 的 Where.mode: 'insensitive'(SCIM 会发它) #5814(convertWhere() 忽略 Where.mode,SCIM 会发它,domain:identity / pm:blocked)—— 同为 SCIM 相邻缺陷,不同落点,无依赖。

---

Generated by Claude Code

[baozhoutao]

认领:PM 循环第 5 轮(domain:identity 车道)
会话:session_01JwwiU9bjhwy2SWj13ho8uv
分支:claude/issue-5892-last-admin-breakglass
Worktree:objectstack-issue-5892
域:domain:identity
文件面:packages/plugins/plugin-auth/**(守卫实现 + 测试;相邻既有面 identity-write-guard.test.ts / auth-manager.ts break-glass 段)+ .changeset/*;⛔ 触碰 @better-auth/scim 模型面即停(那一刻 #3653 成为前置)

PM 已于 origin/main 复核前提探测:密码逃生口半边已有(auth-manager.ts:1241/:1291/:3846 等),「剩余 0 个未 ban 管理员则拒绝」形状零命中 —— 与分诊「部分可能已存在,只实现真缺的」结论一致,派发令带逐项复核要求。与同批 #5876(plugin-security)/#5860(plugin-audit)不同包不相交。

---

Generated by Claude Code

[baozhoutao]

复核 ACCEPT(PM,session_01JwwiU9bjhwy2SWj13ho8uv,第 5 轮):交付 PR #5939。

• 逐项前提复核兑现,范围正确收缩:①(ban 守卫)确认零命中 → 新建 last-admin-ban-guard.ts(363 行);②(enforced SSO 密码逃生口)确认已有实现(LAST_LOCAL_CREDENTIAL 守卫等三处)→ 只补 pin 不重写(break-glass-local-credential.test.ts,7 条);③ 测试两侧齐(共 27 条新增)。
• 守卫实现要点核对:by-id 与谓词/multi 写路径都守;对 isSystem 上下文同样生效 —— 正确,better-auth/SCIM 走的正是 system 路径,豁免它守卫就形同虚设;管理员判据复用平台唯一等级尺(invitation-role-cap.ts 导出 isOrgAdminGrade),不另造第二把尺;枚举失败/超上限 fail-closed;拒绝信息响亮。配套的 PERMISSION_DENIED → FORBIDDEN 映射让这条拒绝抵达 SCIM 时是可解释的 403 而非 500。
• 文件面守恒:9 文件全在 plugin-auth/** + changeset(minor,user-visible 安全守卫);未触 @better-auth/scim 模型面(SCIM: 停在 @better-auth/scim rc.1,等正式版再整体迁移 —— rc.2 换掉了整套模型 #3653 未被激活为前置)、未触 spec/objectql。
• 反向验证:boot({unguarded:true}) 对照系证明守卫注册前 ban 最后一个管理员成功 —— 红态即 plugin-auth: break-glass 守卫 —— SCIM/ban 不得停用最后一个管理员(ADR-0024 D5.2,cloud#621 转入) #5892 之前的现实。依赖包回归(runtime 1463 测试)与七道门禁全绿。
• 越界发现已核,且分诊已极速入队:最后一个管理员的「删除」路径无守卫:目标不持本地密码时,SCIM/admin remove 可删掉环境最后一个管理员 #5941(最后管理员的删除路径无守卫 —— 可达缺陷,本单 beforeUpdate 不覆盖 delete)、「这个 membership 是不是管理员」有两种拼写,大小写敏感性不同:isOrgOrPlatformAdmin 对 role='Owner' 答否,等级尺答是 #5942(管理员判据两种拼写、大小写敏感性相反 —— 观察类)均已带 pm:queue + domain:identity 回流本车道,最后一个管理员的「删除」路径无守卫:目标不持本地密码时,SCIM/admin remove 可删掉环境最后一个管理员 #5941 下轮优先;两单可能同触 auth-manager.ts,跨轮串行。

CI 全绿,转 ready 入合并队列。

---

Generated by Claude Code