Files
moyi-model-intelligence-hub/docs/28-verification-delivery-isolation.md
xpp ba5dbc195e
Repository verification / backend (push) Canceled after 0s
Repository verification / frontend (push) Canceled after 0s
fix:"隔离验证码投递并统一密码重置受理"
2026-10-22 08:49:04 +08:00

49 lines
7.4 KiB
Markdown
Raw Permalink 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.
# 验证码投递隔离与重置受理一致性
日期:2026-10-22(Asia/Shanghai)。本增量继续处理 24 号任务表中的认证逻辑缺陷,不代表所有系统开发任务完成。
## 发现与设计
此前重置发送对未知账号立即返回,对已有账号等待邮件/短信网络响应,并只对已有账号执行限额。单次成功 JSON 相同并不能消除 429、发送失败和网络等待带来的账号枚举差异。注册/重置发送还持有全局 PostgreSQL 事务锁等待外部服务。
本轮依照 OWASP Forgot Password Cheat Sheet 的统一消息、相似执行路径、异步处理和配额原则,将受理、投递、账号变更分为三个边界:
- `VerificationService`:仅做输入规范化、公开配置可用性、共享配额、随机码摘要和原子入队。重置请求**不查 users**,已知、未知、停用账号均执行相同 DB/加密写入路径;未知账号同样计入账户、来源及全局预算,不再快速返回。注册仍须有效邀请码。
- `VerificationDispatchService`:事务内原子写码和加密 outbox;后台领取提交后才解密、复查当前代次和账号可用性并调用 sender。网络调用期间没有数据库事务或全局配额锁。`VerifiedAccountService` 原有验证码/账号业务原子性和错误码计数保留。
- `VerificationPurpose`:封闭的注册/密码重置用途枚举,同时提供固定 SQL 表标识及消息目的。邮件不再把重置验证码误写成注册验证码;SMS 沿用服务器配置的通用模板,生产须核对其适用范围。
## 数据与资源边界
V50 给两张验证码表增加 `delivery_id`,并新建 `verification_delivery_outbox`。payload 使用已有 `SecretCipher` 的 AES-GCM,加密账户、验证码、用途与随机代次 ID;工作者检查密文内容中的 ID/用途与队列行一致,防止跨行替换投递。队列表不存明文账户或 OTP;原有码表继续保存摘要,原有发送事件仍含账户/IP,因此**并未声称所有认证表均匿名化或加密**。
共享预算沿用每账户 60 秒 1 次/24 小时 10 次、每来源每小时 30 次、全平台每日 1000 次,注册与重置共同计数。限额锁只覆盖 DB 工作,锁等待最多 2 秒;使用 `clock_timestamp()` 防止排队事务沿用早先开始时间。仍需部署侧 WAF/入口请求上限,不能把发送配额当成全站 DoS 防护。配额计算保留全局序列化与事件扫描,适用于当前低容量内测,未来扩容需专用窗口桶及多租户公平策略。
后台每秒调度,最多两个本机工作线程,`SynchronousQueue` 无内存等待队列;重复调度在繁忙时直接退出。多副本用 `FOR UPDATE SKIP LOCKED` 原子领取,领取状态先提交为 `sending`。领取后的消息只尝试一次:崩溃、网络结果不明或成功回执保存失败都不自动重发。该策略是**至多一次尝试**而不是可靠必达;某些消息可能丢失,用户可在受理冷却期后重新申请。
发送前复查当前 `delivery_id`、未消费、未超过五次、未过期;重置再查账号是否仍 active,未知/停用账号丢弃且不发送。投递失败只按原代次作废,不会消耗后来生成的新码;消费成功/新申请后迟到的旧消息不具备新码效力。状态终结即清除密文 payload,不保留收件人、OTP、异常堆栈或原供应商错误消息到队列表/公开响应。终态保留固定故障码。未处理消息五分钟过期,终态两天后、过期码一天后分批删除;清理当前由空闲 worker 驱动,持续繁忙时物理清理可能延后,过期判断仍生效。
原 SMTP 连接/读写超时和短信 SDK 禁自动重试保持不变。本轮没有证明底层 SDK 的 DNS 或整体调用具备不可绕过的绝对墙钟期限;双线程上限只能限制资源规模,不能保证阻塞线程及时释放。任意网络迟到、数据缓存、不同历史状态造成的可测时序仍未做生产统计验收;本轮不承诺严格恒定时间或消除所有枚举侧信道。
## 对外兼容与上线要求
- 发送接口仍返回 200、`sent: true`、60 秒冷却和 300 秒有效期;`sent` 是历史兼容字段,**只表示受理,并非邮件/短信送达证明**。不返回任务 ID、验证码、内部丢弃原因或凭据。公开重置页改为“若账号存在且可用,将收到重置验证码”。
- 未获取、已消费、已过期、次数耗尽及错误的重置验证码统一返回 `VERIFICATION_INVALID` 与同一消息;不再以“缺失/过期”差异表达内部状态。注册验证码既有错误语义不变。
- 部署本版本前先应用 V50,再启动新后端;所有副本必须使用相同且安全持久化的 `CREDENTIAL_ENCRYPTION_KEY`,并配置 SMTP 或 SMS。缺失加密密钥时能力查询关闭该功能,发送安全失败,不回退明文或同步发送。不要在仍有待发送消息时直接更换密钥。
- 本轮仅在隔离测试库执行迁移;没有修改业务库、真实发送、部署或 push。数据库备份中的历史密文不因在线清理被擦除,仍需备份保留和密钥管理策略。
## 验证证据
新增 `VerificationDispatchPostgresTest` 22 项真实 PostgreSQL 回归,覆盖请求一致性、未知账号同额限制、只向 active 发送、加密/代次校验、供应商失败不外泄和不重试、网络期间无事务/锁、新旧代次隔离、崩溃/过期清理、缺加密密钥、写入失败原子回滚、多连接领取、跨用途预算、统一错误、密文篡改、成功回执保存失败不重发、双线程无队列和 2 秒锁超时。测试用专用合成账户和内存 sender,真实网络只用于本地应用健康检查,没有邮件/短信付费调用。
最终后端命令:`mvn -B -o clean verify`,Java 21 / Maven 3.9.9、独立 PostgreSQL 15.18/Redis 7。**390 项,0 失败、0 错误、0 跳过,JAR 构建成功**,结束于 2026-10-22 08:41:38(Asia/Shanghai)。新增迁移和全部既有认证/MFA/验证码事务/媒体出站/账务/任务回归均参与。日志 `.tools/verification-delivery-final.log` 被忽略。
前端重新运行 `npm run build` 与 `npm test`:构建通过、25 项测试通过。另在本轮独立容器完整启动打包 JAR,Flyway 迁移至 V50,Spring 组件和定时方法成功初始化,`/health` 返回正常;未配置真实邮件/短信,`/api/auth/verification` 返回两通道均关闭,符合安全关闭状态。这只是本地启动冒烟,不替代真实投递或产品验收。
`spec-driven-acceptance-testing` 的共享 Python 环境阻塞仍未解除;本轮没有获授权修改其环境,未自行批准规格,也没有执行或声称 `qa run --project` 通过。仍须用户审阅 draft 后走正式验收。
参考原则:`https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html`。该文档是设计参考,不是对本产品的认证或第三方审计结果。
## 自动化与后续
按用户本轮明确要求,已删除聊天内 `moyi` 每半小时本地提交检查自动化。没有删除产品内部任务/投递 worker。当前按 `git-commit-conventions` 审查完整差异和暂存区,只提交本任务已验证文件,不 push。后续按 24 号表继续管理授权、配置版本、请求传输统一、长请求租约和协议能力;不把本次增量称作全部开发完成。