跳转到正文
skillsafebeta
← 报告库
用途分类 / 开发辅助

Two Factor Authentication Best Practices Skill 安全审计

作者说它能做什么（原文）

Configure TOTP authenticator apps, send OTP codes via email/SMS, manage backup codes, handle trusted devices, and implement 2FA sign-in flows using Better Auth's twoFactor plugin. Use when users need MFA, multi-factor authentication, authenticator setup, or login security with Better Auth.

第三方安全检查结论

发现安全风险

已检查文件
1
发现的风险
4
会不会运行危险命令？检查是否下载程序后直接运行、让他人远程控制电脑，或藏起要运行的命令。发现 1 项风险
中风险

安装步骤会执行注册表中当时的 latest CLI 并迁移认证数据结构

原文依据：1 处
发现了什么

指南要求运行 `npx auth@latest migrate`。`@latest` 不固定具体版本，执行结果会随发布标签变化；迁移命令还会对认证数据库结构产生持久更改。

为什么需要注意

如果上游最新版本被破坏、行为发生变化或迁移与项目版本不兼容，命令可能在开发者权限下执行意外代码，或导致认证表变更、部署失败和登录中断。

指南把 `npx auth@latest migrate` 列为设置步骤。该命令会取得当时标记为 latest 的 CLI，并且“migrate”步骤旨在改变内置适配器使用的数据结构；同一行也说明 Drizzle/Prisma 走生成并推送的流程。实际影响取决于项目和工具版本，因此运行前应确认版本、生成的迁移内容、备份及回滚方案。

SKILL.md:8来自说明文档打开原文件
1. Add `twoFactor()` plugin to server config with `issuer`2. Add `twoFactorClient()` plugin to client config3. Run `npx auth@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma4. Verify: check that `twoFactorSecret` column exists on user table
会不会泄露文件和密钥？检查是否发送含密码或密钥的文件，以及代码里是否直接写了密钥。发现 1 项风险
中风险

配置接口明确允许明文保存 OTP 和备用码

原文依据：3 处
发现了什么

指南列出的有效配置包括 `storeOTP: "plain"` 和 `storeBackupCodes: "plain"`。虽然完整示例采用加密存储，但复制或选择明文选项会把可用于账户验证或恢复的秘密以可读形式留在数据库中。

为什么需要注意

数据库读取权限、备份泄露、日志误收集或 SQL 注入可能暴露尚未过期的 OTP 或未使用的备用码，从而削弱第二因素保护。

文档确实把 `plain` 列为 OTP 和备用码的可选存储方式。若用户主动采用该选项，数据库泄露或具有数据库读取权限的人可能直接取得仍有效的验证或恢复码。不过完整配置使用 `encrypted`，且文档称备用码默认加密，因此这不是默认示例行为。用户可限制为加密或哈希存储，并要求作者说明为何暴露明文选项。

SKILL.md:137来自说明文档打开原文件
```tstwoFactor({  otpOptions: {    storeOTP: "encrypted", // Options: "plain", "encrypted", "hashed"  },});```
查看另外 2 个位置
SKILL.md:205来自说明文档打开原文件
```tstwoFactor({  backupCodeOptions: {    amount: 10, // Number of codes to generate (default: 10)    length: 10, // Length of each code (default: 10)    storeBackupCodes: "encrypted", // Options: "plain", "encrypted"  },});```
SKILL.md:273来自说明文档打开原文件
TOTP secrets: encrypted with auth secret. Backup codes: encrypted by default. OTP: configurable (`"plain"`, `"encrypted"`, `"hashed"`). Uses constant-time comparison for verification.
会不会删除文件或一直在后台运行？检查是否大范围删除文件、改写磁盘，或设置自动启动。未发现风险
会不会绕过安全保护？检查是否跳过网站安全验证、开放过多文件权限，或取消操作前的确认。发现 2 项风险
中风险

所有验证示例都默认把设备信任 30 天

原文依据：4 处
发现了什么

TOTP、OTP 和备用码示例均固定传入 `trustDevice: true`。说明称受信任状态默认持续 30 天，并会在每次登录时刷新，因此复制这些示例会默认建立长期的第二因素豁免，而不是让用户明确选择。

为什么需要注意

若设备是共享的、遗失的或浏览器会话被窃取，持有该受信任状态的人可能在较长时间内仅凭主凭据登录；持续登录还可能不断延长豁免期。备用码恢复流程也会自动信任设备。

TOTP、OTP 和备用码验证示例都直接启用 `trustDevice: true`，而说明称信任默认持续 30 天并在每次登录时刷新。照抄示例会建立可长期延续的二次验证豁免，且代码没有展示用户选择或撤销信任的界面。用户可要求默认关闭，并仅在用户明确勾选后启用。

SKILL.md:80来自说明文档打开原文件
```tsconst verifyTotp = async (code: string) => {  const { data, error } = await authClient.twoFactor.verifyTotp({    code,    trustDevice: true,  });};
查看另外 3 个位置
SKILL.md:130来自说明文档打开原文件
Send: `authClient.twoFactor.sendOtp()`. Verify: `authClient.twoFactor.verifyOtp({ code, trustDevice: true })`.
SKILL.md:194来自说明文档打开原文件
```tsconst verifyBackupCode = async (code: string) => {  const { data, error } = await authClient.twoFactor.verifyBackupCode({    code,    trustDevice: true,  });};
SKILL.md:245来自说明文档打开原文件
Pass `trustDevice: true` when verifying. Default trust duration: 30 days (`trustDeviceMaxAge`). Refreshes on each sign-in.
低风险

安装命令没有固定依赖版本

原文依据：1 处
发现了什么

安装命令没有指定依赖版本。同样的命令以后可能下载不同代码，你实际安装的内容可能与这次检查时不同。

为什么需要注意

即使命令和报告没变，以后安装时也可能下载到另一份代码。

设置步骤明确使用 `auth@latest`，没有固定具体版本。用户在不同时间运行时，注册表的 `latest` 标签可能指向不同代码，因此无法仅凭本次材料确定将执行的版本。用户可要求作者固定并注明已验证的 CLI 版本。

SKILL.md:10来自说明文档打开原文件
2. Add `twoFactorClient()` plugin to client config3. Run `npx auth@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma4. Verify: check that `twoFactorSecret` column exists on user table
会不会误导 AI 或隐藏内容？检查工作说明是否要求 AI 忽略你的指令、干扰检查结果，或夹带看不见的文字。未发现风险
会不会偷偷改推广链接或收款方？检查是否强制替换推广链接或收款对象，同时要求隐瞒更改。未发现风险

Skill 逻辑拆解

8 个说明模块

该 Skill 是 Better Auth 双因素认证的配置指南，涵盖 TOTP、邮件/短信 OTP、备用码、受信任设备和登录验证流程；所给材料只有说明与示例，没有独立脚本。

查看原文
SKILL.md:2来自说明文档打开原文件
---name: two-factor-authentication-best-practicesdescription: Configure TOTP authenticator apps, send OTP codes via email/SMS, manage backup codes, handle trusted devices, and implement 2FA sign-in flows using Better Auth's twoFactor plugin. Use when users need MFA, multi-factor authentication, authenticator setup, or login security with Better Auth.---

启用 2FA 时要求用户再次验证密码，并且首次 TOTP 验证成功后才会将 2FA 标记为启用；这避免了未完成配置就锁定账户。

查看原文
SKILL.md:46来自说明文档打开原文件
Requires password verification. Returns TOTP URI (for QR code) and backup codes.
SKILL.md:61来自说明文档打开原文件
`twoFactorEnabled` is not set to `true` until first TOTP verification succeeds. Override with `skipVerificationOnEnable: true` (not recommended).

登录流程先验证主凭据，再跳转到第二因素页面；只有第二因素成功后才创建会话 Cookie。

查看原文
SKILL.md:220来自说明文档打开原文件
1. Call `signIn.email({ email, password })`2. Check `context.data.twoFactorRedirect` in `onSuccess`3. If `true`, redirect to `/2fa` verification page4. Verify via TOTP, OTP, or backup code5. Session cookie is created on successful verification

示例通过应用已有的邮件函数把 OTP 发到当前用户的邮箱，并未显示将验证码发送到第三方地址。

查看原文
SKILL.md:112来自说明文档打开原文件
      otpOptions: {        sendOTP: async ({ user, otp }, ctx) => {          await sendEmail({            to: user.email,            subject: "Your verification code",            text: `Your code is: ${otp}`,          });        },
从这里开始 · 工作说明SKILL.md
two-factor-authentication-best-practices
连线表示工作说明包含的模块，不是实际运行顺序。点击模块可查看原文。 另有 2 个章节，可在原文件中查看。
文件与检查记录1 个文件

检查范围与遗漏

逐文件查看涉及的内容

下方列出本次涉及的原文范围；纳入检查不代表已查清所有问题。

  • SKILL.md已纳入全文

这份报告只针对上方版本。我们看了拿到的代码和说明文件，没有实际运行 Skill，也没有检查它另外安装的软件包。因此，这不是“保证安全”的承诺；换了版本或使用环境，结果也可能不同。

  • SKILL.md工作说明

代码和说明中提到的操作

安装其他软件包
SKILL.md:10来自说明文档打开原文件
2. Add `twoFactorClient()` plugin to client config3. Run `npx auth@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma4. Verify: check that `twoFactorSecret` column exists on user table
读取密钥或账号配置
SKILL.md:251来自说明文档打开原文件
Flow: credentials → session removed → temporary 2FA cookie (10 min default) → verify → session created.
读取了多少行
332
文件校验值（用于核对版本）
44b63656861a855682212954b64126479d63be9e7ca87db748bd84dee8a341c3