From bcfda3400933ce13b99d725eb4d185021dc4434a Mon Sep 17 00:00:00 2001 From: wkc <978997012@qq.com> Date: Mon, 30 Mar 2026 10:32:33 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=E5=AF=86=E7=A0=81=E5=8A=A0?= =?UTF-8?q?=E5=AF=86=E4=BC=A0=E8=BE=93=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...-03-30-login-password-encryption-design.md | 26 ++ ...-03-30-login-password-encryption-design.md | 265 ++++++++++++++++++ 2 files changed, 291 insertions(+) create mode 100644 doc/implementation-report-2026-03-30-login-password-encryption-design.md create mode 100644 docs/superpowers/specs/2026-03-30-login-password-encryption-design.md diff --git a/doc/implementation-report-2026-03-30-login-password-encryption-design.md b/doc/implementation-report-2026-03-30-login-password-encryption-design.md new file mode 100644 index 0000000..93db186 --- /dev/null +++ b/doc/implementation-report-2026-03-30-login-password-encryption-design.md @@ -0,0 +1,26 @@ +# 系统登录与密码类接口加密传输设计实施记录 + +## 实施时间 +- 2026-03-30 + +## 修改内容 +- 新增系统登录与密码类接口加密传输设计文档 +- 明确采用固定密钥的对称加密方案 +- 明确覆盖正式密码提交接口并排除 `/login/test` +- 明确前端在 API 提交前加密、后端在控制器入口前统一解密 +- 明确不采用明密文兼容处理 + +## 文档路径 +- `docs/superpowers/specs/2026-03-30-login-password-encryption-design.md` +- `doc/implementation-report-2026-03-30-login-password-encryption-design.md` + +## 设计结论 +- 对正式密码提交接口启用固定密钥对称加密传输 +- 保持原有请求字段名不变，仅对密码字段做加密与解密 +- 解密成功后继续复用现有认证、校验与 BCrypt 入库逻辑 +- `/login/test` 保持现状，不接入本次改动 + +## 说明 +- 已按要求检查设计文档保存路径，正式设计文档保存至 `docs/superpowers/specs` +- 仓库约束禁止启用 subagent，本次设计文档复审采用本地自检方式处理 +- 设计确认后，下一步需要分别产出后端实施计划和前端实施计划 diff --git a/docs/superpowers/specs/2026-03-30-login-password-encryption-design.md b/docs/superpowers/specs/2026-03-30-login-password-encryption-design.md new file mode 100644 index 0000000..fc17e89 --- /dev/null +++ b/docs/superpowers/specs/2026-03-30-login-password-encryption-design.md @@ -0,0 +1,265 @@ +# 系统登录与密码类接口加密传输设计文档 + +## 1. 背景 + +当前系统登录、注册、修改密码、重置密码、新增用户等正式接口，在请求体中直接传输明文密码。后端在收到密码后再执行现有的登录校验或 BCrypt 加密入库逻辑。 + +本次需求是在不改变现有业务语义的前提下，为所有正式密码提交接口增加“密码加密传输”能力，避免密码以明文形式直接出现在接口请求体中。 + +## 2. 已确认约束 + +- 采用对称加密方案 +- 前端使用固定密钥加密密码字段 +- 后端使用同一固定密钥解密密码字段 +- 覆盖所有正式密码提交接口 +- 明确不包含 `/login/test` +- 不新增兼容性或补丁性方案 +- 不允许“解密失败后按明文继续处理” +- 保持最短路径实现，不改现有账号、认证、密码存储主逻辑 + +## 3. 接口范围 + +本次加密传输仅覆盖以下正式接口： + +- `/login` +- `/register` +- `/system/user/profile/updatePwd` +- `/system/user/resetPwd` +- `/system/user` + +各接口需要处理的密码字段如下： + +- `/login`：`password` +- `/register`：`password` +- `/system/user/profile/updatePwd`：`oldPassword`、`newPassword` +- `/system/user/resetPwd`：`password` +- `/system/user`：`password` + +以下接口不在本次范围内： + +- `/login/test` +- 任何不提交密码字段的接口 + +## 4. 现状分析 + +### 4.1 前端现状 + +当前前端接口调用中，登录、注册、个人修改密码、管理员重置密码、管理员新增用户都直接提交明文密码字段。仓库中虽然已经存在 `JSEncrypt` 工具，但仅用于“记住密码”场景下 Cookie 的本地存储加密，并没有用于登录或其他正式密码接口。 + +### 4.2 后端现状 + +后端正式接口的密码处理链路如下： + +- 登录接口直接读取 `LoginBody.password` 并交给认证流程 +- 注册接口直接读取 `RegisterBody.password` 并执行 BCrypt 加密入库 +- 修改密码接口直接读取 `oldPassword`、`newPassword` 并执行旧密码校验和新密码入库 +- 管理员重置密码和新增用户接口直接读取 `SysUser.password` 并执行 BCrypt 加密 + +现有后端没有统一的密码传输解密层，因此如果直接在前端加密而后端不解密，现有校验链路会全部失效。 + +## 5. 方案对比 + +### 方案一：保留现有字段名，前端加密后提交，后端统一解密 + +做法： + +- 保持现有请求结构不变 +- 前端在 API 提交前仅加密密码字段 +- 后端在控制器进入业务逻辑前，对密码字段统一解密 + +优点： + +- 改动路径最短 +- 页面、DTO、控制器入参结构基本不变 +- 现有业务校验和 BCrypt 逻辑可直接复用 + +缺点： + +- 需要明确每个接口的密码字段清单 +- 前后端都要维护一份受控字段映射 + +### 方案二：新增专用密文字段 + +做法： + +- 每个接口新增 `encryptedPassword`、`encryptedOldPassword` 等字段 +- 后端只处理密文字段 + +优点： + +- 语义清楚 +- 明文和密文边界直观 + +缺点： + +- 改动面大 +- 前后端 DTO、表单、测试样例都要整体调整 +- 不符合本次最短路径实现原则 + +### 方案三：全局请求拦截器加密 + 全局参数层解密 + +做法： + +- 前端在 axios 拦截器中按 URL 自动加密密码字段 +- 后端在过滤器或参数解析层统一自动解密 + +优点： + +- 页面层改动最少 + +缺点： + +- 隐式逻辑过重 +- 对不同入参类型的接口可读性差 +- 不利于后续定位问题 + +## 6. 设计结论 + +采用方案一。 + +本次仅在接口边界增加密码加密传输能力，业务层继续只处理解密后的明文密码。传输链路如下： + +1. 前端表单收集用户输入的密码明文 +2. API 提交前，使用固定对称密钥加密密码字段 +3. 后端控制器收到请求后，先对约定密码字段解密 +4. 解密成功后继续走现有业务逻辑 +5. 解密失败时直接返回错误，不进入后续业务处理 + +`/login/test` 保持现状，不加入加密与解密逻辑。 + +## 7. 前端设计 + +### 7.1 设计目标 + +前端只负责“在请求发出前对密码字段加密”，不在页面组件中分散实现逻辑，也不修改表单字段命名。 + +### 7.2 收口位置 + +加密逻辑收口在 API 调用层，不放在页面组件层。 + +原因： + +- 登录页、注册页、个人中心、用户管理都存在密码提交场景 +- 若每个页面独立处理，加密逻辑容易分散和重复 +- API 层更容易统一维护接口与字段映射 + +### 7.3 前端改动点 + +- 新增统一的对称加密工具 +- 新增“密码字段加密”辅助方法 +- 在以下接口调用前对对应字段加密： + - 登录 + - 注册 + - 个人修改密码 + - 管理员重置密码 + - 管理员新增用户 +- 保持请求字段名不变 + +### 7.4 配置方式 + +前端固定密钥通过环境配置读取，不直接散落在业务代码中。 + +## 8. 后端设计 + +### 8.1 设计目标 + +后端只负责“在进入现有业务逻辑前将密码字段解密为明文”，不改动现有认证和密码存储主流程。 + +### 8.2 收口位置 + +解密逻辑收口在控制器入口之后、业务逻辑之前，由统一的密码解密工具完成。 + +原因： + +- 当前接口入参类型不统一，包含 `LoginBody`、`RegisterBody`、`SysUser` 和 `Map` +- 如果直接放到全局过滤器或参数解析层，会增加隐式复杂度 +- 控制器显式调用统一解密工具，路径更短、更直观 + +### 8.3 后端改动点 + +- 新增统一的对称解密工具 +- 新增面向不同入参类型的密码字段解密方法 +- 在以下正式接口进入业务逻辑前显式解密： + - `SysLoginController.login` + - `SysRegisterController.register` + - `SysProfileController.updatePwd` + - `SysUserController.resetPwd` + - `SysUserController.add` +- 不改动 `SysLoginController.loginWithoutCaptcha` + +### 8.4 业务链路保持不变 + +解密成功后继续沿用现有逻辑： + +- 登录继续走认证管理器与 `SysPasswordService` +- 注册继续走 BCrypt 加密入库 +- 个人修改密码继续先校验旧密码，再加密新密码入库 +- 管理员重置密码和新增用户继续走 BCrypt 加密入库 + +## 9. 配置设计 + +前后端分别维护固定对称密钥配置： + +- 前端从环境变量读取固定密钥 +- 后端从 `application.yml` 读取固定密钥 + +本次设计默认前后端使用同一把固定密钥，不涉及动态下发、轮换或多套密钥管理。 + +## 10. 错误处理 + +本次只采用单一路径，不做兼容分支： + +- 受控正式接口收到密码字段后，后端默认按密文处理 +- 任一密码字段解密失败，接口直接返回错误 +- 不允许“尝试解密失败后继续按明文处理” +- 不允许只加密部分密码字段后继续流转 + +修改密码接口中，`oldPassword` 与 `newPassword` 必须同时成功解密后才能进入现有校验流程。 + +## 11. 非目标 + +本次不包含以下内容： + +- 不修改 `/login/test` +- 不改造密码存储方式 +- 不改造现有 BCrypt 校验逻辑 +- 不引入非对称加密 +- 不增加密钥动态下发能力 +- 不增加明密文双通道兼容逻辑 +- 不修改与密码无关的请求字段 + +## 12. 风险与控制 + +主要风险如下： + +1. 前后端固定密钥不一致，会导致所有正式密码接口失败 +2. 某些密码字段漏加密或漏解密，会导致登录失败或入库异常 +3. 个人修改密码接口包含多个密码字段，若字段映射错误，会导致旧密码校验失败 + +控制方式： + +- 前后端统一约定固定密钥配置名称与用途 +- 将密码字段清单明确写入实现计划 +- 将正式接口逐一纳入测试验证 +- 保持 `/login/test` 完全不接入，避免影响现有测试用途 + +## 13. 验证方案 + +实施后至少验证以下场景： + +1. `/login` 提交加密后的 `password` 可以正常登录 +2. `/register` 提交加密后的 `password` 可以正常注册 +3. `/system/user/profile/updatePwd` 提交加密后的 `oldPassword`、`newPassword` 可以正常修改密码 +4. `/system/user/resetPwd` 提交加密后的 `password` 可以正常重置密码 +5. `/system/user` 提交加密后的 `password` 可以正常新增用户 +6. 受控正式接口在密文非法时直接失败 +7. `/login/test` 仍按现有方式运行，不受本次改动影响 + +## 14. 实施范围 + +- 前端：登录、注册、个人中心、用户管理相关 API 和密码加密工具 +- 后端：登录、注册、个人中心、用户管理相关控制器和密码解密工具 +- 配置：前端环境配置、后端应用配置 +- 数据库：无表结构改动 + +本次属于接口边界增强，不涉及数据库结构和核心认证机制重构。