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

7.4 KiB
Raw Permalink Blame History

验证码投递隔离与重置受理一致性

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