# 权限管理系统 —— 深度代码审计报告（第 9 轮）

> **审计范围**：`/internal` 下全部非测试、非 `_gen.go` 生产代码（含 `internal/server/permserver.go`、HTTP logic / handler / middleware、loaders、model 定制层、svc、util、consts）。
> **审计时间**：2026-04-19
> **审计维度**：逻辑一致性 / 并发与 RMW / 资源管理 / 数据完整性 / 安全漏洞 / 边界坍塌 / DB 性能 / 僵尸代码 / 接口契约与对象完整性。
> **与第 8 轮对比**：
>   - **已落地（本轮复核通过，不再复列修复细节）**：
>     - **H-2**（第 8 轮）`checkPermLevel` 读缓存 `MinPermsLevel` 的 TOCTOU —— `internal/logic/auth/access.go:302-347` 现统一调用 `loadFreshMinPermsLevel` 走 DB 复核，`sqlx.ErrNotFound` 降级为"0 roles"、其他 DB 错误向上冒出。
>     - **M-3**（第 7~8 轮）RefreshToken CAS 在签发失败后脏升级 `tokenVersion` —— `internal/logic/pub/refreshTokenLogic.go:90-110` 与 `internal/server/permserver.go:215-230` 均已把 `Generate*Token` 前置到 `IncrementTokenVersionIfMatch` 之前，CAS 只在两份 token 都成功生成后执行。
>     - **M-N1**（第 8 轮）CreateProduct Redis 票据写失败孤儿化 —— `internal/logic/product/createProductLogic.go:178-283` 已落地 `compensateCreatedRows`：ticket Setex 任一步失败都会按 admin / member / product 倒序硬删，并附 WARN 日志便于对账。
>     - **M-N3**（第 8 轮）gRPC `SyncPermsError{Code:404}` 被吞成 `codes.Internal` —— `internal/server/permserver.go:61-90` 已加 `errors.As` 显式映射到 `codes.NotFound`，并保留具体错误文案。
>     - **L-2**（第 7~8 轮）`CountActiveAdminsTx` 僵尸方法 —— `internal/model/productmember/sysProductMemberModel.go` 中仅保留 `CountOtherActiveAdminsTx`，接口与实现两端均已删除旧签名。
>     - **L-N1**（第 8 轮）`sysPermModel` 仍拼接 `fmt.Sprintf("... status = %d", ...)` —— 现统一用 `?` 占位（`FindAllCodesByProductCode:57-67`、`DisableNotInCodesWithTx:100-154`）。
>     - **L-N2**（第 8 轮）`SetUserPerms` 的 `FindByIds` → `BatchInsert` TOCTOU —— `internal/logic/user/setUserPermsLogic.go:148-165` 已在事务内对目标权限集做 `COUNT(*) WHERE status=?` 复核，并要求计数等于入参长度，否则 rollback。
>   - **产品契约接受、不列入风险清单**：
>     - **H-1 同产品成员 PII 互见**（第 6 → 7 → 8 轮累计列入 P0）—— 产品确认"内部系统 + 通讯录互见"为业务契约，不修。该条从本轮起归档，不再进入后续审计复核列表。
>   - **未落地 / 回归**：
>     - **L-3 历史 `DeptId=0` 账号的 `CheckManageAccess` 兜底**（需数据迁移，不属纯代码问题，延续存档）。
>   - **本轮新发现（权重较高的 5 条）**：
>     - **M-N1（新）`userDetailsLoader.Load` 的 `loadOk=false` 契约错位** —— 基础设施故障被同化为业务 403 / "产品已禁用"，前端侧不重试且 SOC 无故障信号。
>     - **M-N2（新）`BatchDel` 中 `unregisterCacheKey` 走串行 N×2 次 SREM** —— 绑/解绑/改角色链路退化为 O(N) Redis RTT，属 N+1。
>     - **M-N3（新）`RoleDetail` 枚举 oracle** —— 跨产品访问 403 vs 404 可区分，可用于穷举合法 roleId。
>     - **M-N4（新）`CreateUser` 未做 caller→`req.DeptId` 的部门链校验** —— 产品 ADMIN 可为**非自己管辖的部门**预埋用户名并占坑，绕过 AddMember 侧部门链防护。
>     - **L-N1（新）`ParseWithHMAC` helper 未统一使用** —— `jwtauthMiddleware.go`、gRPC `VerifyToken` 仍用内联 `token.Method.(*jwt.SigningMethodHMAC)` 断言，三处拷贝导致审计面错位。
>   - **本轮复现的低风险残点**：L-N2 `UpdateUser` 调部门未校验 `dept.Status`；L-N3 `AdminLogin` `IsSuperAdmin` 判断在 bcrypt 之后；L-N4 `sysUserModel.UpdateStatus` 缺乐观锁字段（由上层短路保护）。

---

## 🚩 核心逻辑漏洞 (High Risk)

**本轮无 High Risk 项。**
- 第 8 轮列示的 H-2（`checkPermLevel` TOCTOU）已通过 `loadFreshMinPermsLevel` 闭环，见上方"已落地"小节。
- 第 6~8 轮列示的 H-1（同产品 PII 互见）经产品确认为系统对内使用场景下的既定契约，自本轮起归档、不再纳入审计清单。
- 其余安全类待办均已降级至 Medium / Low，见下节。

---

## ⚠️ 健壮性与性能建议 (Medium / Low)

### M-N1. `userDetailsLoader.loadFromDB` 的 `loadOk=false` 语义错位，导致基础设施故障被同化为业务拒绝（新发现）
- **位置**：`internal/loaders/userDetailsLoader.go:138-204`、`:321-574`（`loadFromDB`、`loadDept`、`loadProduct`、`loadPerms` 等子加载）。
- **描述**：
  - `loadFromDB` 约定：
    - `(ud, true, nil)` — 全量成功，写 5 分钟缓存；
    - `(ud, false, nil)` — 子段（dept / product / membership / roles / perms）中某段失败，**返回残缺 ud、仅跳过缓存写**；
    - `(nil, _, err)` — 主体加载失败，`Load` 向上传 error。
  - `Load(:180-183)` 在 `loadOk=false` 时 `return ud, nil`。调用方拿到的是 `Username≠""`、但 `DeptPath=""` / `Perms=nil` / `ProductStatus=0` 的"半成品"：
    - `jwtauthMiddleware.go` 只校 `tokenVersion` 与 `IsSuperAdmin || MemberType!=""`，**放行**；
    - `refreshTokenLogic.go` 的 `ProductStatus != StatusEnabled` 分支把这种 case 归类为"产品已被禁用"，返 403；
    - 其余业务接口因 `Perms=nil` 命中 `hasPerm=false`，返 403。
  - 结果：一次 Redis / MySQL 抖动对外就是 403 "无权 / 产品禁用"，而真正应该是 503 "上游暂不可用，请重试"。**前端不会重试**，SOC 也不会出现任何异常信号，故障被静默。
- **影响**：
  - 故障可观测性塌陷；SLO 把"基础设施降级"错报成"正常业务拒绝"。
  - 用户体验上，一次瞬时 DB 抖动会对全体在线用户抛"产品已被禁用" / "无权限"——比直接 500 更容易引起误解和 P1 工单。
- **修复方案**：
  1. 把 `loadOk=false` 的语义改为"基础设施故障"：`Load` 里遇到该分支直接 `return nil, ErrLoaderDegraded`（新定义 sentinel）。
  2. HTTP 中间件 & gRPC AuthInterceptor 对 `ErrLoaderDegraded` 统一返 503（或 `codes.Unavailable`），并附 `retry-after`。
  3. 保留 `(ud, false, nil)` 作为内部观测用途时，**改为 panic-safe 的诊断日志聚合**而非对外返回。
  4. 配套：`refreshTokenLogic` 里的 "产品已被禁用" 分支前增加 `if ud.ProductCode != "" && ud.DeptStatus == 0 { return ErrLoaderDegraded }` 兜底。
  5. 单测：`TC-9101 loadPerms 报错 → Load 返回 Unavailable`、`TC-9102 loadProduct 报错 → Load 不返回"产品已禁用"`。

### M-N2. `UserDetailsLoader.BatchDel` 在大 roleId 场景退化为 O(N) Redis RTT（N+1 新发现）
- **位置**：`internal/loaders/userDetailsLoader.go:257-272`，调用方 `internal/logic/role/updateRoleLogic.go`、`internal/logic/role/bindRolePermsLogic.go`、`internal/logic/user/bindRolesLogic.go`。
- **描述**：
  - `BatchDel` 先用一次 `DelCtx(keys...)` 批量删主 key（OK），但紧跟着 **for-range 调用 `unregisterCacheKey`，每个用户串行 2 次 `SremCtx`**（userIndex + productIndex）。
  - 对"角色改名 / 角色禁用 / 批量重绑角色"场景，该角色下绑定的用户数可能上千人（即使"几万部门"不现实，但"单个业务角色跨几千人"在大型中台里常见）。意味着一次普通的 `UpdateRole` 会对 Redis 发出 **2N 次** 串行往返。
  - 相较之下，`registerCacheKey` 已经用 `PipelinedCtx` 合并 RTT，表明作者清楚 pipeline 的必要性，`unregisterCacheKey` 却没同步改造。
- **影响**：
  - 在角色批量维护/权限大盘扫描期对 Redis 连接池形成突刺，尾延迟 P99 明显抬升；极端场景可导致 `UpdateRole` 接口被 go-zero 的 ctx timeout 打断，落入"已 UPDATE DB 但 Clean 缓存失败"的分支（目前该分支仅写 Errorf，不回滚）。
  - 当 Redis 集群跨机房时，2N 串行比一次 pipeline 多出 (N-1)×RTT，个位数 ms 的 RTT 在 N=1000 时就是秒级延迟。
- **修复方案**：
  1. 把 `unregisterCacheKey` 的 per-user 逻辑合入一次 `PipelinedCtx`：对每个 key 发 `pipe.SRem(userIdxKey, cacheKey)` / `pipe.SRem(productIdxKey, cacheKey)`，一次 Exec。
  2. 更彻底：直接给 `BatchDel` 写一个专用 `batchUnregister(ctx, pairs)`，单 pipeline 内合并所有 userIndex / productIndex 的 SREM + 可选 EXPIRE。
  3. 回归测试：`TC-9201 BatchDel(1000 users) 的 Redis 命令数 ≤ 3 次 pipeline Exec`（用 redis-mock 的 CallCount 断言）。

### M-N3. `RoleDetail` 枚举 oracle：跨产品访问 404 vs 403 可区分（新发现）
- **位置**：`internal/logic/role/roleDetailLogic.go:29-58`。
- **描述**：
  - 现状流程：
    1. 先 `SysRoleModel.FindOne(req.Id)`：找不到返 **404 "角色不存在"**；
    2. 再判 `!IsSuperAdmin && caller.ProductCode != role.ProductCode`：返 **403 "无权访问该产品的数据"**。
  - 非超管攻击者遍历 `req.Id`，即可通过响应码精确区分"该 id 不存在" vs "存在于别的产品"，从而绘制跨产品的 role id 分布图，为后续定向攻击（社工、横向越权尝试）提供素材。
  - 同一脚本在 `ProductDetailLogic.productDetail` 也存在（先 `FindOneByCode`，再做成员检查）；`RoleList`/`ProductList` 因天然按 `caller.ProductCode` 过滤不泄漏。
- **影响**：
  - 边界信息泄露，属于"先查后授权"反模式；在任何以 id 为目标的枚举场景都会被利用。
  - 与第 7 轮把 `AdminLogin` 非法用户名的 bcrypt 时序补齐的精神不一致。
- **修复方案**：
  1. 合并成"授权失败即返 404"的统一契约：先用 `caller.ProductCode` 做过滤（或查询时把 `productCode = ?` 塞进 WHERE），未命中或跨产品一律返 `ErrNotFound("角色不存在")`。
  2. `ProductDetailLogic` 同步处理：对非超管直接用 `FindByCodeWithMemberCheck` 或先查 `sys_product_member` 命中后再读 `sys_product`，省掉"存在性差异"泄漏。
  3. 单测：`TC-9301 非超管请求别产品 roleId → 404`、`TC-9302 非超管请求不存在 roleId → 404`，两者响应体必须完全一致。

### M-N4. `CreateUser` 允许产品 ADMIN 为"非自己管辖部门"预埋用户名（新发现）
- **位置**：`internal/logic/user/createUserLogic.go:37-100`。
- **描述**：
  - 现状只用 `RequireProductAdminFor(productCode)` 校验 caller 是该产品的 ADMIN，并用 `FindOne(req.DeptId)` 核对部门存在，**未校验 caller 的 `DeptPath` 是否覆盖 `newDept.Path`**。
  - 产品 ADMIN 可以为任意存在的部门创建用户，随后：
    1. 占坑关键用户名（`admin_*`、`ops_*`、`sre_*` 等易被运营/运维复用的账号）；
    2. 预埋账号后等待配合方（比如跨部门协作的另一位 ADMIN）触发 `AddMember`，由于 `AddMember` 会走 `CheckAddMemberAccess` 的部门链校验，**对方 ADMIN** 的部门链可能覆盖，最终把这个"伪造种子账号"挂进产品。
  - 与 `UpdateUserLogic` 的设计（调部门时严格校验 `caller.DeptPath` 前缀，见 `updateUserLogic.go:116-120`）**不一致**：同样的敏感位，创建时无校验、修改时严校验，出现"先创建后改部门"的绕路。
- **影响**：
  - 横向越权路径：产品 ADMIN 在"应当只管 X 部门"的治理约束下，可以在 DEV 部门、总部部门等任意位置生成账号，后续借由 AddMember 协同路径落地。
  - 用户名命名空间被占用，正常部门 ADMIN 新建时收到"用户名已存在"，排查困难。
- **修复方案**：
  1. 与 `UpdateUserLogic` 保持对称：`if req.DeptId > 0 && !caller.IsSuperAdmin && caller.MemberType != Admin || caller.DeptPath != "" && !strings.HasPrefix(newDept.Path, caller.DeptPath) { return ErrForbidden }`。
  2. 若业务上允许产品 ADMIN "跨部门拉新人"，则至少要求 `req.DeptId` 必须是 caller 所在产品已有成员的部门集合之一（查 `sys_product_member` join `sys_user` 得到部门白名单）。
  3. 单测：`TC-9401 部门 ADMIN 创建跨部门用户 → 403`、`TC-9402 产品 ADMIN 创建本部门子部门用户 → 200`、`TC-9403 SuperAdmin 创建任意部门用户 → 200`。

### L-N1. JWT 解析三处重复：`ParseWithHMAC` helper 未统一使用
- **位置**：
  - 定义：`internal/logic/auth/jwt.go:16-31`；
  - 内联实现 1：`internal/middleware/jwtauthMiddleware.go:62-66`；
  - 内联实现 2：`internal/server/permserver.go` 的 `VerifyToken`（`jwt.ParseWithClaims(... keyfunc {...})`）。
- **描述**：`ParseWithHMAC` 的注释明确写着"所有 JWT 解析点（HTTP 中间件 / gRPC VerifyToken / RefreshToken）统一走这里"，但目前只有 `ParseRefreshToken` 一个调用方。另两处自己又写了一遍 `token.Method.(*jwt.SigningMethodHMAC)` 断言 —— 功能上一致，但：
  - 未来若增加算法白名单（例如仅允许 HS384、禁 HS256）或添加 `typ` 断言，要改 3 处；
  - 把"算法混淆防御"的审计覆盖矩阵从 1 个函数摊到 3 个函数，`test-design.md` 的 TC-0951~0960 只覆盖了 `ParseRefreshToken` 一条路径。
- **影响**：安全属性正确，但代码一致性差、改动风险高。属于"长期隐患"。
- **修复方案**：
  1. `jwtauthMiddleware.go` 改用 `authHelper.ParseWithHMAC(tokenStr, secret, &UserClaims{})`，移除内联 keyfunc；
  2. gRPC `VerifyToken` 同样替换；
  3. 把 TC-0951~0960 复用到这两条路径（直接 table-driven 调三个入口）。

### L-N2. `UpdateUserLogic` 调部门时未校验目标 `dept.Status`
- **位置**：`internal/logic/user/updateUserLogic.go:110-131`。
- **描述**：`FindOne(*req.DeptId)` 仅判存在，不判 `Status`。产品 ADMIN 可把用户调入已 `Disabled` 的部门，随后该用户在 `loadPerms` 里会命中"普通成员 + DeptStatus!=Enabled"分支，其 DEV 全权特权被撤销。若业务意图是"停用部门=冻结该部门所有活动"，该路径破坏了不变量。
- **影响**：中低优。主要是产品语义一致性（"停用部门"的含义被稀释），不构成越权。
- **修复方案**：`if newDept.Status != StatusEnabled { return ErrBadRequest("目标部门已停用") }`，与 `UpdateDept` 禁用时的数据流闭环。

### L-N3. `AdminLogin` `IsSuperAdmin` 判断在 bcrypt 之后，对"合法用户名"的时序侧漏略大于"非法用户名"分支
- **位置**：`internal/logic/pub/adminLoginLogic.go:55-85`。
- **描述**：流程是"查用户 → bcrypt 校验 → 校 `IsSuperAdmin` → 校 status"。对于一个**存在但非超管**的账号，攻击者即便密码随机也会触发 bcrypt 计算（约 60~100ms），与"存在且密码错"分支耗时相近；而"不存在"分支走 `dummyBcryptHash` 也有类似耗时兜底 —— 单凭这点难以区分。但若攻击者能获取大量样本，`IsSuperAdmin` 这一步的耗时（sql 比较）理论上可让"存在但非超管"比"存在是超管且密码错"略快（无 token 签发路径），仍可能形成<10ms 级的统计差。
- **影响**：属学术级别时序泄漏，实战价值低。但该入口按第 7 轮审计精神是"高敏感且对抗公网扫描"，建议把 `IsSuperAdmin` 判断**前置到 `FindByUsername` 之后、bcrypt 之前**：若非超管，仍走 `dummyBcryptHash` 消耗一次 bcrypt，再返回 403，恒定时序。
- **修复方案**：重排为：`FindByUsername → 非超管则用 dummy 计算再统一返 ErrInvalidCredentials → 超管再真 bcrypt → Status 校验`。

### L-N4. `sysUserModel.UpdateStatus` 缺乐观锁字段（由上层短路保护，但 model 自身语义不自洽）
- **位置**：`internal/model/user/sysUserModel.go:154-175`。
- **描述**：`UpdateStatus` 的 `WHERE id=?` 无 `updateTime` / `tokenVersion` 比较；与同文件里 `UpdateProfile` 使用乐观锁、`IncrementTokenVersionIfMatch` 使用 CAS 的风格不一致。上层 `UpdateUserStatusLogic` 做了"状态相同则短路"、`UserDetailsLoader` 5 分钟 TTL 也提供事实一致性，所以实际故障概率低。
- **影响**：不会造成越权，但并发改状态会出现"我改了 Enabled 你覆成 Disabled"的 last-write-wins。
- **修复方案**：把 `UpdateStatus` 改为 `WHERE id=? AND updateTime=?`，接口加入 `expectedUpdateTime` 参数，语义与 `UpdateProfile` 对齐。

---

## ✅ 本轮复核通过、认定安全的机制（仅挑敏感点列示）

| 机制 | 位置 | 关键保护点 |
| --- | --- | --- |
| `checkPermLevel` fresh read | `logic/auth/access.go:302-347`、`loadFreshMinPermsLevel:339-343` | caller.MinPermsLevel 每次走 DB，降级 admin 后续的跨级分配被立即拒绝（第 8 轮 H-2 已闭环） |
| CreateProduct 补偿 | `logic/product/createProductLogic.go:178-283` | Redis 票据写入 `SetexCtx` 失败调用 `compensateCreatedRows` 级联删除 admin / member / product |
| RefreshToken CAS 顺序 | `logic/pub/refreshTokenLogic.go:90-110`、`server/permserver.go:215-230` | 先生成 access+refresh 再 `IncrementTokenVersionIfMatch`，签名失败不会吞掉旧 refresh |
| DeleteDept AB-BA 防护 | `logic/dept/deleteDeptLogic.go` | 自身 `FOR UPDATE`，子部门 / 成员 `FOR SHARE`，锁顺序与 CreateDept 对齐 |
| 负缓存投毒防御 | `loaders/userDetailsLoader.go:161-178` | 写哨兵前再 `FindOne` 强一致复核，避免 Insert→Load 并发把新用户哨兵掉 |
| AddMember 部门链二次校验 | `logic/auth/access.go:CheckAddMemberAccess`、`logic/member/addMemberLogic.go:76-78` | 产品 ADMIN 也要过部门链，切断第 6 轮 H-3 |
| RemoveMember 末位守卫 | `logic/member/removeMemberLogic.go:49-53` | `CountOtherActiveAdminsTx` 事务内排除自己并 lock row，杜绝并发撤 admin 导致 0 admin |
| GuardRoleLevelAssignable | `logic/user/bindRolesLogic.go:86-88` | caller 的 min-level fresh read，避免缓存 admin 权级绑定高于自己的角色 |
| SetUserPerms 事务内复核 | `logic/user/setUserPermsLogic.go:148-165` | `BatchInsertWithTx` 前后 `COUNT(*) WHERE status=?` 复核，并发禁用权限的 TOCTOU 闭环 |
| gRPC SyncPerms 错误分级 | `server/permserver.go:61-90` | `SyncPermsError{Code:404}` → `codes.NotFound`，不再同化为 Internal |
| gRPC 限流剥端口 | `server/permserver.go` / `ratelimit` | PeriodLimit key 用客户端 IP 而非 `host:port`，防单连接多端口绕限 |
| JWT HMAC 断言本身 | `logic/auth/jwt.go:16-31` | `alg=none` / RS256 / ES256 全拒；L-N1 指出的是"调用点未统一"，算法防御自身 OK |

---

## 🎯 修复建议优先级与落地顺序

| 优先级 | 议题 | 预估工作量 | 风险 |
| --- | --- | --- | --- |
| P0 | **M-N1 Loader 半成品降级** | 1 天：新增 sentinel 错误 + 中间件映射 + refreshToken 分支修正 + 2 条新单测 | 中：需验证 5xx 监控告警路径 |
| P1 | **M-N3 RoleDetail 枚举 oracle** | 半天：`RoleDetail` + `ProductDetail` 合并成"404 或 200" | 低 |
| P1 | **M-N4 CreateUser 部门链校验** | 半天：对称复用 `UpdateUserLogic` 的校验代码 | 低 |
| P2 | **M-N2 BatchDel pipeline 化** | 半天：改 `unregisterCacheKey` 支持批量 + 回归压测 | 低 |
| P2 | **L-N1 ParseWithHMAC 统一** | 半天：替换 2 处调用 + table-driven 用例复用 | 低 |
| P3 | **L-N2 UpdateUser 目标部门 Status** | 1 小时 | 低 |
| P3 | **L-N3 AdminLogin IsSuperAdmin 前置** | 1 小时 | 低 |
| P3 | **L-N4 UpdateStatus 乐观锁** | 2 小时（需调上层一处调用） | 低 |
| Backlog | **L-3 `DeptId=0` 历史账号迁移** | 需 DBA 配合 | — |

---

## 📎 审计方法论与覆盖率说明

- 本轮审计共读取并分析 27 个 `.go` 文件（不含 `_test.go` / `_gen.go` / `testdata/`），覆盖 logic（全部）、loaders、server、middleware、model 定制层、consts、util；
- 复核维度：针对第 8 轮每一条未决项都读取相关 code path 做实际行为确认，避免"报告里写修复实际没改"；
- 新发现筛选原则：仅列出**能构造具体攻击序列或业务损害场景**的项，纯风格性建议已过滤；
- "几万部门"等非现实场景已按 USER 要求过滤；保留"角色下绑千人"这一现实高频场景作为 M-N2 的论据。