认证服务

认证服务是 Nodesify Admin 平台的守门人。它处理用户身份识别、会话管理和安全上下文的建立。

登录流程 (/auth/login)

登录过程是一个多步骤的安全工作流：

1. 凭据验证：系统根据数据库验证用户名和密码（使用 bcrypt 哈希）。
2. MFA 检查：
   • 如果用户启用了 MFA，服务器将返回特定的 mfaRequired 响应。此时尚未签发令牌。
   • 客户端随后必须调用 /auth/mfa/verify 以完成登录。
3. 令牌签发：
   • 访问令牌 (Access Token)：响应体中返回的短效 JWT (JSON Web Token)。用于 API 授权的 Bearer 请求头。
   • 刷新令牌 (Refresh Token)：设置为 HttpOnly Cookie 的长效旋转令牌。用于续期访问令牌。
4. CSRF 保护：使用双重提交 Cookie 模式。服务器设置 csrf_token Cookie，并期望在随后的状态变更请求中收到匹配的请求头。

会话管理

为了在提供流畅用户体验的同时保持安全性，我们使用了一种称为带重用检测的刷新令牌旋转 (Refresh Token Rotation with Reuse Detection) 的稳健会话管理策略。

令牌刷新机制 (/auth/token/refresh)

当访问令牌过期时（通常每 15-30 分钟），前端拦截器会自动调用此接口。

1. 旋转（单次使用）：

   • 每次使用刷新令牌获取新的访问令牌时，刷新令牌本身也会被替换。
   • 服务器作废旧的刷新令牌，并在响应 Cookie 中签发一个新的。
   • 这确保了如果刷新令牌被盗，它的有效窗口通常非常短，或者已经失效。

2. 重用检测（防盗保护）：

   • 场景：攻击者窃取了用户的刷新令牌。合法用户先使用了它（触发旋转）。攻击者随后尝试使用该旧的已窃取令牌。
   • 检测：系统识别出正在提交一个已使用/已作废的令牌。
   • 操作：这被视为安全漏洞。系统将撤销整个令牌家族 (Token Family)。
     • 合法用户的活跃会话被中止（他们会被登出）。
     • 攻击者的访问被阻止。
   • 结果：双方都被强制重新认证，确保合法所有者重新获得控制权。

3. 令牌家族 (Token Family)：

   • 一个“家族”将一串旋转的令牌链接到单个根会话登录。
   • 撤销一个家族会使与该特定登录事件关联的所有令牌（过去、现在和未来）立即失效。

活跃会话 (/auth/sessions)

用户和管理员可以查看并管理活跃的登录会话。

• 获取会话 (GET /auth/sessions)：列出当前用户的所有活跃会话，包括设备 (User-Agent)、IP 和最后活跃时间。
• 撤销会话 (DELETE /auth/sessions/:id)：终止特定会话。该会话的刷新令牌立即失效。
• 撤销其他所有会话：一项安全功能，用于“登出所有其他设备”。

MFA 管理 (/auth/mfa)

任何用户都可以启用多因素身份验证 (TOTP) 以增加安全性。

• 设置 (GET /auth/mfa/setup)：生成新的 TOTP 密钥并返回二维码 URL。
• 启用 (POST /auth/mfa/enable)：通过验证代码并激活账号上的 MFA 来确认设置。
• 禁用 (POST /auth/mfa/disable)：关闭 MFA（需要当前密码）。
• 恢复代码：启用 MFA 时，会生成一组一次性使用的恢复代码，用于紧急访问。

账号安全

修改密码 (/auth/password)

• 接口：PUT /auth/password
• 要求：用户必须提供 oldPassword 才能设置 newPassword。
• 效果：修改密码会自动撤销所有其他会话，以确保在账号泄露时，攻击者失去访问权限。

身份模拟 (/auth/impersonate/:id)

所需权限：System:Auth:Impersonate

此功能允许超级管理员以其他用户身份登录以排查问题。

• 机制：服务器为目标用户签发一个新的临时会话。
• 安全：会话持续时间较短（2 小时）。
• 审计：该操作会被记录，并带有明确的“由 [管理员] 模拟”上下文。