认证与双因素
Web.Casa 采用多层认证体系，结合 JWT 令牌、工作量证明挑战和可选的 TOTP 双因素认证。
登录过程按以下步骤执行：
- 用户提交用户名和密码
- 服务端发起 ALTCHA 工作量证明（PoW）挑战，客户端需自动完成计算
- 后端使用 bcrypt 哈希验证用户凭据
- 若启用了 TOTP 双因素认证，用户需输入认证器应用生成的六位动态验证码
- 验证通过后签发 JWT 令牌（HS256 算法）
- 后续所有 API 请求在
Authorization: Bearer <token>头中携带令牌
ALTCHA 不是验证码（CAPTCHA）。 它是由客户端浏览器自动完成的工作量证明挑战，用户无需任何交互操作。该机制可有效防御自动化暴力破解攻击，同时不影响登录体验。
JWT 令牌
Section titled “JWT 令牌”所有需要认证的 API 请求必须携带有效的 JWT 令牌。
| 属性 | 值 |
|---|---|
| 签名算法 | HS256 |
| 请求头 | Authorization: Bearer <token> |
| 密钥配置 | 通过 WEBCASA_JWT_SECRET 环境变量设置 |
重要：
WEBCASA_JWT_SECRET环境变量为必填项。请在/etc/webcasa/webcasa.env中设置一个高强度的随机字符串。
当 Web.Casa 在空数据库上首次启动时，第一个注册的用户将自动获得**管理员（Admin）**角色。此后不再开放自助注册，所有新用户必须由管理员手动创建。
TOTP 双因素认证
Section titled “TOTP 双因素认证”Web.Casa 支持 TOTP（基于时间的一次性密码）作为可选的第二认证因素。
- 进入 设置 > 个人资料
- 点击启用双因素认证
- 使用认证器应用扫描显示的 QR 码
- 输入六位验证码确认绑定
- 立即保存恢复码
兼容的认证器应用
Section titled “兼容的认证器应用”- Google Authenticator
- Microsoft Authenticator
- Authy
- 1Password
- Bitwarden
- 任何兼容 TOTP 的应用（RFC 6238）
恢复码是认证器设备丢失或不可用时的备用登录方式。
- 8 位字母数字组合
- 每个恢复码仅限使用一次，成功登录后即失效
- 在启用双因素认证时生成
- 请保存在安全的离线位置
警告： 如果同时丢失认证器设备和恢复码，需要管理员手动关闭该账户的双因素认证才能恢复访问。
- 最少 6 个字符
- 密码使用 bcrypt 算法哈希后存储
- 明文密码不会被存储或记录到日志