accounts/docs/api/auth.md

认证与鉴权

会话认证（默认）

1. 登录 POST /api/auth/login 成功后返回：

• token：会话 token
• expiresAt
• user

2. 客户端后续请求携带：

• Authorization: Bearer <session-token> 或
• Cookie xc_session=<session-token>

邮件验证

• 发送验证码：POST /api/auth/register/send
• 验证并注册：POST /api/auth/register/verify

当 SMTP 未配置或使用示例域名时，邮箱验证会自动关闭。

MFA（TOTP）

• 申请 secret：POST /api/auth/mfa/totp/provision
• 验证并启用：POST /api/auth/mfa/totp/verify
• 关闭 MFA：POST /api/auth/mfa/disable

登录接口在部分场景会返回 mfaToken，用于后续验证。

JWT 令牌服务（可选）

启用 auth.enable: true 后提供：

• POST /api/auth/token/exchange：使用 OAuth 回调签发的一次性 exchange_code 换取真实会话 token
• POST /api/auth/token/refresh：刷新 access token

注意事项：

• token/exchange 只接受后端签发的一次性 exchange_code，不再接受调用方自报 user_id/email/roles
• token/exchange 返回的 token/access_token 是同一个真实会话 token，供前端 BFF 写入 xc_session
• 当前版本多数保护路由仍使用会话 token，JWT refresh 仅保留给 token/refresh
• 若开启 JWT 中间件，业务逻辑仍可能需要会话 token；因此控制面应优先走会话模型

建议：若主要使用会话认证，请将 auth.enable 设为 false。