本技能为使用 Better Auth 实现安全的邮箱与密码认证提供指导与强制规则，主要面向需要在应用中集成邮箱/密码登录的开发者。
用途 用于在 Better Auth 中正确配置邮箱与密码认证，涵盖邮箱验证、密码重置、密码哈希以及相关安全防护，帮助避免虚假注册、账号劫持和常见认证漏洞。
主要能力
- 邮箱验证：通过 emailVerification.sendVerificationEmail 配置验证邮件发送函数，防止虚假注册并确认用户可访问注册邮箱。可启用 emailAndPassword.requireEmailVerification 阻止未验证用户登录，启用后未验证用户每次登录尝试都会收到新的验证邮件（需先配置 sendVerificationEmail，且仅适用于邮箱/密码登录）。
- 客户端校验：虽然 Better Auth 在服务端校验输入，仍建议实现客户端校验，以提供即时反馈并减少无效请求带来的服务器负载。
- 回调 URL：注册和登录请求中的 callbackURL 应始终使用包含 origin 的绝对 URL，避免后端与前端不同域时 Better Auth 推断 origin 出现问题。
- 密码重置流程：需提供 sendResetPassword 函数以发送重置邮件，可选 onPasswordReset 事件钩子。调用 requestPasswordReset（服务端 auth.api 或客户端 authClient）发送重置链接，email 为必填，建议同时配置 redirectTo。
- 安全防护：
- 防时序攻击：内部使用 runInBackgroundOrAwait 后台发信避免阻塞响应；用户不存在时仍执行令牌生成与占位数据库查询以保持响应时间一致；API 始终返回固定消息“If this email exists in our system, check your email for the reset link”。在无服务器平台需配置 backgroundTasks.handler（如 waitUntil）确保邮件可靠发送。
- 令牌安全：重置令牌使用 generateId(24) 生成 24 位字母数字高熵字符串；默认 1 小时过期，可通过 resetPasswordTokenExpiresIn（秒）配置；重置成功后立即删除令牌，防止复用。
- 会话撤销：启用 revokeSessionsOnPasswordReset 可在重置密码时使所有现有会话失效。
- 重定向校验：redirectTo 会依据 trustedOrigins 校验，恶意重定向 URL 将返回 403。
- 密码要求：重置时新密码需满足长度要求，默认最小 8 字符（minPasswordLength）、最大 128 字符（maxPasswordLength），均可配置。
- 密码哈希：默认使用 scrypt，因其慢速且内存密集、Node.js 原生支持、OWASP 在无 Argon2id 时推荐。可通过 emailAndPassword.password 提供自定义 hash 与 verify 函数改用其他算法（如 Argon2id，示例使用 @node-rs/argon2 并配置 memoryCost、timeCost、parallelism、outputLen、algorithm）。注意在已有系统上切换哈希算法会导致旧密码用户无法登录，需规划迁移策略。
使用方式 在 Better Auth 配置对象中设置 emailVerification、emailAndPassword（enabled、sendResetPassword、onPasswordReset、requireEmailVerification、resetPasswordTokenExpiresIn、revokeSessionsOnPasswordReset、minPasswordLength、maxPasswordLength、password.hash/verify）以及 advanced.backgroundTasks.handler 等选项。客户端通过 authClient.signUp.email、authClient.requestPasswordReset 等调用。
适用场景 需要为 Web 应用实现邮箱/密码注册、登录、邮箱验证和密码重置，并希望遵循安全最佳实践的开发场景。
限制 requireEmailVerification 仅适用于邮箱/密码登录且依赖 sendVerificationEmail 配置；切换密码哈希算法需迁移策略；无服务器平台需自行配置后台任务处理器；资料未提供收费、价格、平台支持范围等其他信息。