Files
zyt/identity-admin/docs/code-review.md
T
2026-11-11 13:53:14 +08:00

50 lines
8.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 独立身份管理代码审查
修复状态:R1–R4 已在本次交付中修复;以下为修复前的审查证据。引用校验和菜单边界由 HTTP 回归覆盖,改密的旧快照拒绝由 `tests/password-race.php` 覆盖,迟到会话响应由 `tests/session-race.test.mjs` 覆盖。最终执行记录见 `validation.md`。
审查日期:2026-10-30。范围为 `server/` 与 `web/` 的当前源代码及 API 契约;本轮只读实现代码,未安装依赖、启动服务、执行 HTTP 或浏览器测试。以下行为由代码路径推导,运行复现步骤用于后续验证,不表示已经实测。
发现 4 项 P2 问题。其中 R1 是当前 HTTP 验收的明确阻塞项;R2 建议在安全验收前修复。未发现足以证明未认证管理写入、任意控制器调用、提交 `is_root` 提权或直接绕过 root 删除保护的 P0/P1 问题。
## R1 · P2 · 关联不存在返回 404,与输入校验验收约定不一致
**证据:** [IdentityRepository.php:45](C:/zyt/identity-admin/server/app/repository/IdentityRepository.php:45) 在 `associations()` 中直接调用 `require()`;[IdentityRepository.php:15](C:/zyt/identity-admin/server/app/repository/IdentityRepository.php:15) 对不存在记录固定抛出 404。[AccountService.php:46](C:/zyt/identity-admin/server/app/service/AccountService.php:46) 将新增/编辑用户的角色、部门数组送入该方法。[RoleService.php:43](C:/zyt/identity-admin/server/app/service/RoleService.php:43) 对 `menu_id` 也直接调用 `require()`。
因此,提交合法用户字段并携带不存在的 `role_id` 或 `dept_id`,以及提交不存在 `menu_id` 的角色,都会得到 404。当前测试任务明确将这些情况作为输入校验,接受 400/409/422;这三种请求会使现有集成测试失败。这里是实现与验收约定未对齐,并不意味着关联实际上被写入。编辑目标本身不存在时返回 404 仍然合理。
**建议修复:** 新增独立的关联校验方法,查询缺失关联并抛出 422,例如“角色不存在”“部门不存在”“菜单不存在”;保留 `require()` 对所操作目标的 404 语义。不要把所有 404 在异常处理器里整体转换成 422。后续用真实 API 分别覆盖三个无效关联,并确认成功响应后的 lists 中不存在新增账号/角色。
## R2 · P2 · 改密的旧密码校验发生在写事务之前,存在并发覆盖窗口
**证据:** [AuthService.php:114](C:/zyt/identity-admin/server/app/service/AuthService.php:114) 使用请求认证时取得的 `$admin['password_hash']` 验证旧密码,验证通过后才在 [AuthService.php:122](C:/zyt/identity-admin/server/app/service/AuthService.php:122) 进入事务;事务直接更新哈希并删除会话,没有重读当前哈希或校验当前会话仍有效。[Database.php:65](C:/zyt/identity-admin/server/app/repository/Database.php:65) 的 MySQL 写锁从 `transaction()` 内部才开始取得,无法保护其前面的密码验证。相比之下,登录流程已在 [AuthService.php:35](C:/zyt/identity-admin/server/app/service/AuthService.php:35) 做事务内状态与哈希复核。
两个已有会话的改密请求若都先通过旧密码验证,A 提交新密码并撤销旧会话后,B 仍可进入写事务,用同一旧密码对应的认证快照再次改密。B 会覆盖 A 的新密码,即使 B 的会话在 A 提交时已被撤销。这是并发窗口,普通串行的“改密后旧 token 返回 401”测试不能覆盖它。
**建议修复:** 把当前账号重读、当前会话/版本有效性检查和旧密码验证放到同一个受写锁保护的事务内,再更新哈希与撤销会话;也可以使用原哈希条件更新并要求影响行数为 1。避免仅在事务外增加第二次校验。后续通过两个连接和同步屏障,让两个请求均持有旧认证快照,确认只有一个改密成功,另一个失败,且最终密码不会被已撤销的旧会话覆盖。
## R3 · P2 · 菜单路径保存校验与动态路由注册校验不一致,成功保存后可能没有入口
**证据:** [TreeService.php:121](C:/zyt/identity-admin/server/app/service/TreeService.php:121) 允许页面路径 `/profile`、`/login`、`/403` 和包含 `//` 的路径;只对页面空路径和 `/` 做特殊拒绝。[Menus.vue:105](C:/zyt/identity-admin/web/src/views/Menus.vue:105) 的表单正则同样允许这些值,虽然提示文字声称不能使用保留路径。真正注册路由时,[router/index.ts:34](C:/zyt/identity-admin/web/src/router/index.ts:34) 与 [router/index.ts:46](C:/zyt/identity-admin/web/src/router/index.ts:46) 会拒绝保留路径和 `//`,并在 [router/index.ts:54](C:/zyt/identity-admin/web/src/router/index.ts:54) 静默跳过该菜单。
例如 root 新增 `type:C, paths:/profile, component:common/custom, perms:custom/read`,其他必填字段合法时后端接受;前端随后提示“菜单已保存,当前权限与导航已同步”,但菜单永远无法成为动态路由,`/profile` 仍是个人账号页面。用户无法从成功提示辨别配置不可用。
**建议修复:** 在服务端页面路径校验中明确拒绝保留路径和重复斜线,并在前端使用相同规则显示字段错误;保留 `/dashboard` 的既定内置页面语义,避免通过普通自定义页配置占用它。后续分别提交保留路径、重复斜线和正常自定义路径,前两种应返回 422,后一种保存、授权、刷新及深链访问应一致成功。
## R4 · P2 · 旧请求的 401 会无条件清除当前的新会话
**证据:** [http.ts:19](C:/zyt/identity-admin/web/src/services/http.ts:19) 在发送时读取 token,但 [http.ts:43](C:/zyt/identity-admin/web/src/services/http.ts:43) 在收到 401 时重新读取“当前” token,只判断其非空,没有比较失败请求实际携带的 token。[main.ts:15](C:/zyt/identity-admin/web/src/main.ts:15) 的处理器随后无条件清空认证状态、动态路由并跳回登录。新登录会在 [stores/auth.ts:17](C:/zyt/identity-admin/web/src/stores/auth.ts:17) 写入新 token。
如果旧会话的列表或权限请求还在网络中,用户已退出并用新会话登录,迟到的旧请求 401 仍会删除新 token。新登录会话在服务端其实有效,前端却再次退出,表现为登录随机失败。该问题需要请求交错;顺序调用不会出现。
**建议修复:** 记录每个请求发送时的 token 或认证版本,仅在 401 所属版本仍是当前版本时触发全局失效处理;退出和登录时推进版本,并取消或忽略旧版本的认证资料响应。后续延迟旧请求的 401,先完成新登录,再释放旧响应,确认新 token、当前用户和动态路由保持有效;当前会话自身的 401 仍须正常清理。
## 已核实的关键保护与联动
显式路由及默认拒绝可在 [route/app.php:8](C:/zyt/identity-admin/server/route/app.php:8)、[config/route.php:3](C:/zyt/identity-admin/server/config/route.php:3) 找到;所有管理操作先经过 [ApiController.php:26](C:/zyt/identity-admin/server/app/controller/ApiController.php:26) 的会话验证和权限匹配,随后才解析并执行写入。读取选项对全部登录用户开放,符合契约;选项由公开角色投影和菜单/部门树组成,没有暴露密码哈希或会话字段。SQL 值采用绑定参数,管理字段由 `Input::only()` 显式白名单控制。
密码用 `password_hash/password_verify`,随机会话只保存 SHA-256 摘要。登录会复核账号状态,认证 SQL 每次检查停用与到期;退出删当前会话,停用、删除及改密撤销对应会话。权限通过启用角色取并集,并经有效祖先链过滤;角色编辑用字段存在性区分省略和 `menu_id:[]`,空授权不会被忽略。关联用户的角色/部门、有子节点的菜单/部门均有事务内删除保护;父链校验拒绝自己、后代和按钮父节点。root 停用/删除与普通用户编辑 root 都在服务端防护,前端也屏蔽 root 管理编辑和自身停用/删除。
前端使用组件白名单注册菜单路由;首次深链登录会装载当前用户后重新解析,保存管理数据后会刷新当前资料与动态路由,当前页被撤权会回工作台。用户编辑显式复制多角色/多部门数组,角色保存从树读取已选 ID 并显式发送空数组,四类表单都排除新增时的 `id:0`。上述静态路径没有发现字段名错配或依赖不存在 detail 接口的问题。另一管理员修改授权后的浏览器界面依赖顶部刷新或后续资料刷新才更新;后端逐请求授权仍生效。
建议先对齐 R1 使已编写的 HTTP 集成测试可完整执行,再修复 R2–R4,并分别增加并发改密、路径边界和过期响应交错验证。本轮没有把依赖构建或 HTTP 集成结果当作已通过。