v1auth 上下文
验证挑战
邮箱、密码、通行密钥、验证器与恢复码的验证端点，以及失败时的响应形态。
验证挑战是登录/注册流程的中间步骤。所有端点都要求把流程令牌放在 Authorization: Bearer 里，成功后换发一枚新的流程令牌。
端点
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /verify/email | 向指定邮箱发送验证码 |
POST | /verify/email/confirm | 提交邮箱验证码 |
POST | /verify/password | 校验密码 |
POST | /verify/passkey | 取通行密钥断言挑战 |
POST | /verify/passkey/confirm | 提交通行密钥断言 |
POST | /verify/authenticator | 校验验证器 TOTP |
POST | /verify/recovery-code | 校验恢复码 |
邮箱验证
POST /verify/email
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
email | string | ✅ | 接收验证码的邮箱，3–255 字符，服务端去空白并转小写 |
{ "success": true, "flow_token": "eyJhbGciOi..." }注册流程里该地址记为待绑定邮箱；登录流程里会与流程令牌记录的可用方式比对，不匹配时静默成功但不发信。
POST /verify/email/confirm
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | string | ✅ | 邮件中的验证码，4–32 字符 |
校验对象是流程令牌内记录的待验证码列表，成功后该邮箱在流程里被标记为已验证。
密码验证
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
password | string | ✅ | 密码，1–128 字符 |
登录时与库中哈希比对；注册时把 bcrypt 哈希写进流程令牌，等流程结束时落库。
通行密钥验证
POST /verify/passkey
无请求体。返回 PublicKeyCredentialRequestOptions，其中 allowCredentials 由账号已注册的通行密钥填充。
{ "options": { "challenge": "...", "allowCredentials": [] }, "flow_token": "eyJ..." }POST /verify/passkey/confirm
请求体是 AuthenticationResponseJSON（原样透传给 WebAuthn 校验）。校验对象是服务端保存的挑战与凭据公钥。
验证器 TOTP
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | string | ✅ | 6 位数字验证码 |
恢复码
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | string | ✅ | 8–32 字符的一次性恢复码 |
恢复码在库中以哈希形式存放，匹配成功后立即从集合中移除，不能重复使用。
失败时的响应
| 端点 | 失败形态 |
|---|---|
| 通行密钥确认 | 200 + success: false，并带新的 flow_token |
| 验证器 TOTP | 400 + success: false，并带新的 flow_token |
| 恢复码 | 400 + success: false，并带新的 flow_token |
失败也返回流程令牌
客户端必须拿到新的流程令牌才能重试。若失败走 4xx 错误体，令牌就带不回来，用户只能从头开始登录。
通行密钥确认因此固定用 200 表达「这次断言没通过」，而不是用状态码。