找回密码

找回密码是整条 auth 链路里唯一不要求会话的写操作，因为「忘记密码」的前提就是「进不去」。也正因如此，它必须自带全部防护：IP 限流、地址维度的失败节流、一次性短命令牌，以及「改密后吊销全部会话」的收尾。

端点

方法	路径	说明
`POST`	`/v1/auth/password-reset`	请求重置链接
`POST`	`/v1/auth/password-reset/complete`	用令牌完成重置

两个端点都不接受 Bearer，也不要求 Turnstile——人机验证挡的是批量注册与撞库脚本，而这里已经有 IP 与地址两层节流。

参数	类型	必填	说明
`email`	string	✅	接收重置邮件的地址

{ "success": true, "message": "If this address is registered, a reset link has been sent" }

响应必须一模一样

无论地址是否注册过，响应都相同。发信失败也会被吞掉：若失败转成 5xx，攻击者就能通过「有没有报错」判断这个地址是否注册过。失败本身仍会进服务日志与告警，只是不体现在响应里。

只有绑定了密码的账号才会收到邮件；没有密码的账号（纯通行密钥或纯第三方登录）走账号恢复流程。

参数	类型	必填	说明
`token`	string	✅	邮件里的一次性令牌
`new_password`	string	✅	新密码，8–128 字符

{ "success": true, "message": "Password updated; 3 session(s) signed out" }

令牌一次性且短命，用过即废。重置成功后该账号所有会话都被吊销——旧密码可能已经被人用过，留着会话等于让入侵者继续待在屋里。