v1auth 上下文
第三方登录回调
POST /v1/auth/provider/:provider/callback：用第三方授权码换取本平台会话令牌。
第三方登录的落点。它把提供商回调拿到的授权码换成本平台的会话令牌；若该身份尚未注册，会自动建号。
请求
POST /v1/auth/provider/:provider/callback，provider 取 github 或 microsoft。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | string | ✅ | 提供商回调拿到的授权码，1–1024 字符 |
redirect_uri | string | ✅ | 与发起登录时的地址完全一致 |
did | string | ✅ | 设备标识，8–256 字符 |
code_verifier | string | ✅ | PKCE 原始值，43–128 字符 |
{
"success": true,
"message": "Signed in",
"is_new_user": false,
"access_token": "eyJ...",
"refresh_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 900,
"acr": "urn:muoceon:acr:aal1",
"auth_time": "2026-11-14T08:31:12.000Z"
}| 字段 | 说明 |
|---|---|
is_new_user | 本次回调是否新建了账号 |
| 其余字段 | 与令牌的会话令牌对完全一致 |
行为约定
| 约定 | 说明 |
|---|---|
| 自动建号 | 无匹配账号时创建新用户，用户名是随机 UUIDv7 |
| 只取必要信息 | 只用提供商的 sub 与展示名，忽略邮箱 |
| PKCE 必填 | 缺了它，攻击者能把自己的授权码塞进受害者浏览器，让受害者登进攻击者的账号 |
| 错误码语义 | 提供商拒绝该码返回 AUTH_PROVIDER_AUTHORIZATION_FAILED（400）；提供商不可达返回 AUTH_PROVIDER_UNAVAILABLE（502） |
这里不会返回 401
401 的语义是「调用方的令牌无效」。本端点没有 Bearer，所以它从不使用 401：
授权码被拒是 400，提供商挂了是 502。混用会让客户端去刷新一枚根本不存在的令牌。
与绑定端点的区别
| 维度 | 登录回调（本页） | 绑定（第三方身份） |
|---|---|---|
| 认证 | 匿名 | 会话 + max_age=300 |
| 结果 | 签发会话令牌 | 在现有账号上新增一条凭据 |
| 建号 | 可能自动建号 | 绝不建号 |
did | 必填 | 不接收 |
两者刻意分开：合成一个端点后，一旦标志位被漏传或伪造，一个本该只用于登录的端点就会获得往任意账号挂凭据的能力。