本技能用于指导并约束使用 Better Auth 的 twoFactor 插件实现安全的双因素认证（2FA）。以下内容按用途、主要能力、使用方式、适用场景和限制分段说明。
一、用途 该技能提供在应用中添加 2FA 的指引与执行规则，基于 Better Auth 的 twoFactor 插件，配置时以应用名作为 issuer（该名称会显示在用户扫描二维码的身份验证器应用中）。
二、主要能力
- 服务端配置：使用 betterAuth 与 twoFactor 插件，设置 issuer、TOTP 选项、OTP 选项、备份码选项等。
- 客户端配置：使用 createAuthClient 与 twoFactorClient 插件，配置 2FA 验证的重定向行为（onTwoFactorRedirect）。
- 启用 2FA：对凭据账户要求输入密码，Better Auth 1.7 接受 method: "totp" | "otp" 并返回可区分结果。TOTP 返回 URI 与备份码；OTP 不返回。
- TOTP：使用身份验证器应用生成基于时间的验证码，默认 30 秒有效；可通过 QRCode（如 react-qr-code）展示 TOTP URI 供扫描；验证时接受当前时间段前后各一个时间段的验证码，以适配设备时钟差异；可配置 digits（6 或 8）与 period。
- OTP（邮件/短信）：向用户邮箱或手机发送一次性验证码，需要自行实现 sendOTP 函数；可配置 period、digits、allowedAttempts，以及 storeOTP（"plain"、"encrypted"、"hashed" 或自定义加解密）。
- 备份码：在 TOTP 注册时自动生成，用于账户恢复；OTP 注册不生成也不返回备份码。可用 generateBackupCodes 重新生成（会使所有旧码失效），verifyBackupCode 验证；每个备份码只能使用一次，验证成功后会从数据库移除；可配置 amount、length、storeBackupCodes。
- 登录时的 2FA 处理：启用 2FA 的用户登录时响应包含 twoFactorRedirect: true；客户端在 onSuccess 中判断并跳转到 2FA 验证页；服务端使用 auth.api.signInEmail 时可检查 "twoFactorRedirect" in response。
- 受信任设备：验证时传入 trustDevice: true，可在配置期限内跳过后续登录的 2FA 验证；可通过 trustDeviceMaxAge 配置时长（默认 30 天），信任期内的每次成功登录会刷新信任时间。
- 安全考量：包括会话管理（登录后先移除会话 cookie，设置默认 10 分钟的临时 two-factor cookie，验证成功后创建会话 cookie，可配置 twoFactorCookieMaxAge）、速率限制（保持端点速率限制、allowedAttempts 限制针对单个已发放 OTP 的猜测、Better Auth 1.7 支持跨 TOTP/OTP/备份码失败的账户级锁定，成功验证会重置账户计数器，锁定尝试返回 429 与 ACCOUNT_TEMPORARILY_LOCKED，端点限流、单码尝试限制与账户锁定是相互独立的控制）、静态加密（TOTP 密钥使用对称加密与 auth secret 加密；备份码默认加密存储；OTP 可配置明文、加密或哈希存储）、常量时间比较（OTP 验证使用常量时间比较以防时序攻击）。
- 凭据账户要求：默认启用和管理 2FA 需要凭据账户；仅当产品有意允许无密码用户管理 2FA 时才设置 allowPasswordless: true；用户拥有凭据账户时仍需要密码。该选项不会让 OAuth 或其他无密码登录端点自动通过 2FA 挑战。
- 禁用 2FA：使用 disable 并需密码确认；禁用后受信任设备记录会被撤销。
- 提供完整配置示例，整合 TOTP、OTP、账户锁定、备份码与会话相关设置。
三、使用方式
- 在服务端通过 betterAuth({ appName, plugins: [twoFactor({...})] }) 配置。
- 在客户端通过 createAuthClient({ plugins: [twoFactorClient({ onTwoFactorRedirect }) ] }) 配置。
- 按文档中的代码示例调用 authClient.twoFactor.enable、verifyTotp、sendOtp、verifyOtp、generateBackupCodes、verifyBackupCode、disable 等方法，并用 data.method === "totp" 区分 TOTP 与 OTP 返回结构。
- 添加插件后遵循已发布的 schema 工作流：对新数据库或已完成迁移的 1.7 数据库，检查 auth generate 输出，然后使用内置 Kysely 适配器执行 auth migrate，或使用 Prisma/Drizzle 等 ORM 的迁移工具；将 auth 固定到项目所用的 Better Auth 版本；旧的 @better-auth/cli 包不是 1.7 CLI。
四、适用场景 适用于使用 Better Auth 并需要为应用添加 2FA 的项目，尤其是需要 TOTP 身份验证器应用、邮件/短信 OTP、备份码恢复、受信任设备与账户锁定等能力的场景。
五、限制与注意事项
- 已发布的 auth@1.7.2 没有 migrate plan 或 migrate apply 操作，尽管官网显示有这些操作。
- 已填充数据的 1.6 数据库在 schema 变更前，需要按链接参考进行单独的手动数据准备。
- 对 TOTP，twoFactorEnabled 在用户验证注册码之前保持 false，除非启用 skipVerificationOnEnable；该选项不推荐用于大多数用例，它不确认用户是否成功配置了身份验证器应用，也不改变 OTP 注册（OTP 本身即时生效）。
- OTP 需要服务器端提供 otpOptions.sendOTP。
- 仅在 data.method === "totp" 收窄后再渲染二维码与备份码步骤。
- 关于收费、价格、平台支持范围等事实，文中暂未提供。