文档:ADR-012 统一鉴权中心;编码规范鉴权定调改为资源服务器 + 权限只到端;org CONTRACT.md 重写;debt 鉴权段;CLAUDE.md 铁规矩 5/6

docs/debt.md

@@ -56,14 +56,22 @@ ADR-011 的「绑定先于策略」随岗位一起退场 —— 工作组快照
 `.parallel()` 任一失败即整体失败(失败走向不进 Mastra)、三态聚合投影
 (读实例表不读 run 状态)、`node_instance` 投影表照写(发号权在主工程)。
 
-## 鉴权(ADR-010 落地后的已知欠账)
+## 鉴权(ADR-012 落地后的已知欠账)
 
-- **登录失败无次数限制**:可无限次试口令。单组织 ≤50 人、内网部署下暂缓;
-  接入外网前必须补(按账号 + 来源 IP 双维度退避)。
-- **无口令强度校验、无首登强制改密**:全员初始口令相同(`JCAI_SEED_PASSWORD`),
-  谁都没改过就等于没有口令。治理台「员工」面需补:改密 / 重置 / 强制改密标记。
-- **`setPassword` 已在 org 出口就位但无路由**:改密只能经播种或直接调用例,界面上没有入口。
-- **会话无「登出全部设备」**:`revokeAllOf` 已实现(停用员工时调),但本人无从触发。
+- **撤角色时效 ≤ 5 分钟**:改了 Keycloak 里的角色,现有 access token 到期前仍按旧角色算(手册 13.4);
+  要立即生效在 Keycloak 上 `POST /users/{id}/logout`。停用经名册同步后即时 403。
+- **票据 60 秒可重放窗**(无状态换来的):绑定 sub、只认 GET;要单次得加一张已用票据表。
+- **名册同步是手动按钮**(运营中心 · 员工 · 同步),没有定时;没配 provisioning 就只有首登即建。
+- **web 待按《Keycloak 前端接入手册》接入**:登录页 / Bearer / 401 跳转 / SSE 与下载改走 `GET /api/auth/ticket` /
+  入口亮灯改读 `GET /api/me` 的 `ends`;接入前登不进。那一刻一并清掉 `SURFACE_FNS` 与退役契约。
+- **退役契约下个迭代删**(§12.4 三步之第三步):`loginRoute` `logoutRoute` `sessionRoute` `createStaffRoute`
+  `disableStaff*Route` `listGrantsRoute` `setGrantsRoute` 与 `sessionSchema` / `grant*` / `governanceFunction*` / `disableCheckSchema`。
+- **`groups` 未用**:日后要按部门过滤数据,需 Keycloak 配 group membership mapper。
+- **aud mapper 未配即全线 401**:401 的 message 会点名「给发 token 的那个 client 加 audience mapper」,但没有启动期探测。
+- **无库环境里,路由覆盖的 fail-closed 保险会静默消失**:`apps/api/src/app/__tests__/route-coverage.it.test.ts`
+  用 `describe.skipIf(database === undefined)` 跳过(同目录另外三份 it-test 同款,是仓库级惯例)——
+  没有库的环境里这条测试根本不跑,进程仍 exit 0;正在搭 CI 的人必须先给它一个库,
+  否则「写了路由处理器却没在契约里声明 access」这类漏洞会在 CI 里悄悄放过。
 
 ## 工作组(ADR-011 落地后的已知欠账)