# 验证码投递隔离与重置受理一致性 日期: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 号表继续管理授权、配置版本、请求传输统一、长请求租约和协议能力;不把本次增量称作全部开发完成。