v1auth 上下文凭据管理
验证器应用
绑定 TOTP 验证器：签发 secret 与校验首枚验证码。
验证器应用（TOTP）是第二因素。每个账号只能绑定一个。
端点
| 方法 | 路径 | 说明 | 提权 |
|---|---|---|---|
POST | /v1/auth/credentials/authenticator/options | 签发 secret | max_age=300 |
POST | /v1/auth/credentials/authenticator | 校验首枚验证码后落库 | 无 |
第一步：签发 secret
无请求体。
{
"success": true,
"secret": "JBSWY3DPEHPK3PXP",
"otpauth_uri": "otpauth://totp/MuoCeon:alice?secret=JBSWY3DPEHPK3PXP&issuer=MuoCeon",
"expires_in": 300
}服务端只返回 otpauth:// URI，不返回渲染好的二维码图片：图片编码放在前端做，避免一次性 secret 经过额外的编码再传一遍。
第二步：确认绑定
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | string | ✅ | 验证器当前显示的验证码，4–16 字符 |
{ "success": true, "credential": { "id": "cred_...", "type": "authenticator" } }为什么要先验一枚码
绑定前先校验一次，配对失败在绑定时就暴露，而不是等到下次登录才发现「扫错了二维码」。 secret 在验证码匹配之前一直可读，因此输入错码后可以拿同一枚 secret 重试，不必重新扫码。