lucia-auth

Lucia Auth

基于 Lucia Auth 和 The Copenhagen Book 中的模式，实现安全、面向生产环境的身份验证。

概述

对于基于浏览器的 Web 应用，应将身份验证视为一个系统，而不是一对登录路由。如果用户要求“添加身份验证”，且没有明确要求玩具示例，则默认提供面向生产环境的基线实现。

Web 应用的生产环境基线

如果仓库中尚无等效实现，默认基线如下：

1. 使用电子邮件和密码注册、登录和退出
2. 将会话存储在服务端，并使用 HttpOnly、Secure、SameSite Cookie
3. 电子邮件验证及重新发送流程
4. 密码重置流程
5. 对所有身份验证和发送电子邮件的端点进行速率限制
6. 对所有会改变状态的路由进行 CSRF 防护或严格的 Origin 验证
7. 更改密码、验证／更改电子邮件以及更改权限时，使会话失效
8. 对更改密码／电子邮件、删除账户、停用 MFA 或查看 API 密钥等敏感操作要求重新验证身份（“sudo 模式”）
9. 安全的身份验证后重定向，并防止开放重定向
10. 根据需要叠加可选的 OAuth、TOTP 或 WebAuthn

对于普通 Web 应用，不要默认将 JWT 存储在 localStorage 中。除非架构明确要求使用无状态令牌，否则优先使用服务端会话。

必读参考资料

对于任何基于浏览器的 Web 身份验证任务，请务必先阅读以下资料：

• references/copenhagen-book/password-authentication.md
• references/copenhagen-book/sessions.md
• references/copenhagen-book/csrf.md
• references/copenhagen-book/email-verification.md
• references/copenhagen-book/password-reset.md
• references/copenhagen-book/open-redirect.md
• references/lucia/sessions-basic.md
• references/lucia/sessions-inactivity-timeout.md
• references/lucia/rate-limit-token-bucket.md

视情况阅读以下资料：

• OAuth：references/copenhagen-book/oauth.md，然后阅读 references/lucia/tutorial-github-oauth.md 或 references/lucia/tutorial-google-oauth.md
• MFA：references/copenhagen-book/mfa.md
• WebAuthn／通行密钥：references/copenhagen-book/webauthn.md，然后阅读 references/lucia/example-email-password-2fa-webauthn.md
• 会话权衡：references/lucia/sessions-overview.md、references/lucia/sessions-stateless-tokens.md

实现工作流

1. 检查仓库中现有的身份验证、用户、电子邮件、会话、中间件和数据库模式。
2. 确定身份验证的范围。 对于标准 Web 应用，默认采用上述生产环境基线。
3. 先创建或更新身份验证架构。 至少包括：user、session、email_verification 和 password_reset。 仅在需要时添加 oauth_account、user_totp、user_recovery_code 或 WebAuthn 表。
4. 接着实现安全原语。 包括密码哈希、会话签发／验证、CSRF／来源检查、速率限制、令牌生成和重定向验证。
5. 完整接通用户流程。 包括注册、登录、退出、验证电子邮件、重新发送验证邮件、忘记密码、重置密码、更改密码和撤销会话。
6. 为敏感操作添加重新验证身份的机制。 更改电子邮件／密码、删除账户、停用 MFA 或更改安全设置，都应要求有效期内的会话或新的凭据挑战。
7. 验证行为。 确认 Cookie 标志、速率限制、失效行为、过期令牌处理和异常路径。

安全规则

密码

• 使用 Argon2id 对密码进行哈希。Scrypt 是可接受的后备方案；仅在遗留限制下使用 bcrypt。
• 最短长度为 8 个字符。不要设置过低的最大长度；64–256 个字符是合理范围。
• 不要静默地修剪、规范化或截断密码。
• 允许复制／粘贴，并支持密码管理器。
• 实际可行时，使用 haveibeenpwned 检查密码是否已泄露。
• 对安全敏感的应用，建议启用 MFA；若应用确有需要，则应强制启用。

电子邮件

• 存储或比较电子邮件地址前，先将其规范化为小写。
• 保持验证逻辑简单，避免 ReDoS。
• 不要悄悄移除 +tag 部分。
• 如果使用电子邮件地址恢复身份，须先完成验证，再将其视为可信信息。

会话

• 登录时创建全新的会话。身份验证后，绝不要重复使用预身份验证或匿名会话。
• 存储会话密钥的哈希，而非原始密钥。
• 优先采用闲置过期时间，并设置绝对有效期。
• 为重新身份验证流程跟踪会话的新鲜度。
• 凭据或权限变更时，使所有会话失效。
• 绝不要通过 URL 接受会话令牌。

Cookie

• 默认使用 HttpOnly、Secure、Path=/ 和 SameSite=Lax。
• 仅当用户体验方面的权衡可以接受时，才使用 SameSite=Strict。
• 服务器刷新会话闲置时限时，也要刷新长期有效的 Cookie。

CSRF

• 不要通过 GET 修改状态。
• 检查所有非 GET 浏览器请求的 Origin，缺失或不可信时予以拒绝。
• 对表单较多的应用，增加 CSRF 令牌作为第二层防护。
• 严格限制 CORS，避免 CSRF 令牌被跨源获取。

OAuth / OIDC

• 使用 Authorization Code + PKCE。
• 在回调时验证 state 和代码验证器。
• 提供方支持时，优先使用 client_secret_basic。
• 首先根据提供方主体标识关联账户；仅当提供方明确标记电子邮件地址已验证时，才按电子邮件地址自动关联账户。
• 将任何登录后的 returnTo 或 redirect_to 值限制为同源路径，以净化其内容。

验证与重置令牌

• 为链接使用高熵随机令牌。
• 存储前，使用 SHA-256 对链接令牌进行哈希处理。
• 令牌只能使用一次，并自动过期。
• 将包含令牌的页面置于 Referrer-Policy: strict-origin 保护之下。
• 严格限制发送电子邮件的端点的请求速率。

模板映射

使用这些资源作为起点，并根据仓库中已有的框架和 ORM 进行调整：

• 密码哈希和密码策略：assets/password-utils.ts
• 会话签发、验证、闲置超时和新鲜会话辅助工具：assets/session-manager.ts
• 核心 SQL 架构：assets/session-schema.sql
• 电子邮件验证链接和代码：assets/email-verification.ts
• 密码重置流程：assets/password-reset.ts
• OAuth + PKCE 流程辅助工具：assets/oauth-handler.ts
• CSRF 和 Origin 验证辅助工具：assets/csrf-protection.ts
• 令牌桶速率限制：assets/rate-limit.ts
• TOTP MFA 和恢复代码：assets/totp-mfa.ts

何时应超越基线方案

出现以下情况时，添加 WebAuthn 或通行密钥：

• 用户明确要求使用通行密钥或 WebAuthn
• 产品涉及敏感安全需求
• 应用需要具备抗钓鱼能力的 MFA

出现以下情况时，添加 OAuth：

• 产品已使用外部身份提供方
• 用户明确要求使用社交登录
• 应用可从降低注册门槛中获益

仅在以下情况下使用无状态令牌：

• 应用是无法依赖同源 Cookie 的 API 优先系统；或
• 有明确的多服务架构需求

输出要求

使用此技能时，最终回答应明确说明：

1. 实现了哪些身份验证流程
2. 默认包含了哪些安全控制
3. 用户仍须提供的假设条件或提供方专属配置
4. 哪些内容已在本地验证，哪些仍需集成测试