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：使用 public_token 换取 access/refresh
• POST /api/auth/token/refresh：刷新 access token

注意事项：

• token/exchange 需要调用方提供 user_id/email/roles
• 当前版本多数保护路由仍使用会话 token，JWT 仅作为中间件校验存在
• 若开启 JWT，中间件要求 Authorization: Bearer <access-token>，但业务逻辑仍可能需要会话 token

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