two-factor-authentication-best-practices

two-factor-authentication-best-practices skill 概覽

two-factor-authentication-best-practices skill 是一份聚焦在為 Better Auth 導入 2FA 的實作指南，不是泛泛而談的 MFA 入門說明。它最適合已經在使用 Better Auth、現在需要可直接落地、少踩坑指引的開發者，用來處理 TOTP 驗證器 App、OTP 傳送、backup codes、trusted-device 管理，以及 twoFactor plugin 所要求的登入流程調整。

這個 skill 能幫你完成什麼

如果你的實際目標，是在 Better Auth 裡為 Access Control 上線一套安全且可運作的 2FA 流程，就應該用這個 skill：安裝 plugin、正確串接 server 與 client、執行 migration，並處理從啟用、驗證到復原的完整使用者旅程。

最適合的使用者

這個 skill 特別適合：

• 已經在現有應用中使用 Better Auth，現在要補上 MFA 的團隊
• 需要實務型 two-factor-authentication-best-practices，而不是理論解說的團隊
• 想先把 TOTP 做好，再補上 backup codes 或 email/SMS OTP 等備援路徑的開發者

它和一般提示詞有什麼不同

一般提示詞可能只會解釋 MFA 概念；這個 skill 在你需要 Better Auth 專屬落地細節時更有價值，例如：

• 用 twoFactor() 設定 server plugin
• 用 twoFactorClient() 設定 client plugin
• migration 與 schema 驗證
• 啟用流程的實際行為，包括 2FA 何時才算真正啟用
• 登入過程中的 redirect 處理

安裝前你該先知道的事

這個 skill 的設計本來就很聚焦。它預設 Better Auth 已經在你的技術棧裡。如果你需要的是與廠商無關的驗證架構規劃、合規政策撰寫，或 MFA 產品比較，那它就不是正確的起點。

如何使用 two-factor-authentication-best-practices skill

這個 skill 的安裝脈絡

這個 skill 位於 better-auth/skills repository 下的 better-auth/twoFactor。從 repository 可見資訊來看，目前只有一個 SKILL.md 檔案，沒有 helper scripts 或額外參考檔，因此它的價值主要來自直接的實作指引，而不是自動化工具。

如果你的環境有 skill loader，就從 repo 安裝並指定 twoFactor skill。若你是手動閱讀，請直接打開：

• better-auth/twoFactor/SKILL.md

先讀這個檔案

在動手改 app 程式碼之前，先讀 SKILL.md。對這個 skill 來說，這個檔案就包含了多數使用者最在意的關鍵決策：

• server 設定
• client 設定
• migration 步驟
• 啟用流程
• TOTP 驗證行為

這算是少見的情況：先讀單一來源檔案，就足以很快判斷這個 skill 是否適合你的需求。

這個 skill 至少需要哪些輸入資訊

若你希望 two-factor-authentication-best-practices skill 產出真正有用的內容，至少要提供：

• 你的 Better Auth server config 檔案路徑
• 你的 Better Auth client config 檔案路徑
• 你要的是純 TOTP，還是 TOTP 加上 email/SMS OTP
• 你的 user table 狀態與 migration 進度
• 你希望的 UX：setup、challenge、backup codes、trusted devices 要怎麼設計

少了這些資訊，結果通常會停留在過於籠統的建議。

核心設定路徑

這個 skill 展示的實務設定流程如下：

1. 在 Better Auth server config 中加入 twoFactor()
2. 設定 issuer
3. 在 client config 中加入 twoFactorClient()
4. 執行 npx @better-auth/cli migrate
5. 確認你的 user table 裡有預期的 2FA secret 欄位

這個 migration 檢查很重要，因為很多看似安裝失敗的案例，真正原因其實是 schema 不一致，而不是 plugin 本身有問題。

用 server-side 範例作為實作錨點

這個 skill 的 server 設定核心大致如下：

import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";

export const auth = betterAuth({
  appName: "My App",
  plugins: [
    twoFactor({
      issuer: "My App",
    }),
  ],
});

實務上最重要的輸入是 issuer，因為它會影響驗證器 App 中的顯示名稱，以及使用者在 setup 過程中的信任感。

Client-side 範例與 redirect 處理

client 流程和 plugin 安裝本身同樣重要：

import { createAuthClient } from "better-auth/client";
import { twoFactorClient } from "better-auth/client/plugins";

export const authClient = createAuthClient({
  plugins: [
    twoFactorClient({
      onTwoFactorRedirect() {
        window.location.href = "/2fa";
      },
    }),
  ],
});

如果你是在做 Access Control 的 two-factor-authentication-best-practices，不要把 redirect 處理當成可有可無的 UI 修飾。它本來就是驗證流程的一部分。你應該一開始就決定 challenge 畫面放在哪個路由，以及該頁面需要接收哪些狀態。

怎麼下 prompt，才能讓這個 skill 發揮效果

弱的請求：

• 「Help me add 2FA」

強的請求：

• 「I use Better Auth in a React app. My server config is in src/lib/auth.ts and my client auth setup is in src/lib/auth-client.ts. I want TOTP with backup codes, a /settings/security enrollment page, a /2fa challenge route, and a migration checklist. Show exact code changes and call out anything that can break the flow.」

後者之所以更好，是因為它提供了足夠上下文，讓這個 skill 能直接產出可實作的結果，而不是停留在寬泛建議。

如何把模糊需求整理成完整 prompt

要更有效使用 two-factor-authentication-best-practices，建議用這個格式：

• 目前技術棧：framework、Better Auth 檔案位置
• 想要的驗證因子：TOTP、email OTP、SMS OTP、backup codes
• UX 節點：enrollment page、challenge route、recovery flow
• 安全規則：password verification、trusted devices、session 行為
• 輸出格式：patch、checklist、code snippets，或 review notes

例如：

Apply two-factor-authentication-best-practices to my Better Auth setup.
Server file: `server/auth.ts`
Client file: `web/auth-client.ts`
Need: TOTP enrollment, backup codes, trusted-device option, redirect to `/auth/2fa`
Also include migration verification and note when `twoFactorEnabled` becomes true.

能減少失誤的工作流程

一套比較可靠的流程是：

1. 先確認 Better Auth 在未啟用 2FA 的情況下已正常運作
2. 加入 server plugin
3. 加入 client plugin 與 redirect 處理
4. 執行 migration
5. 驗證 schema 變更
6. 實作 enrollment UI
7. 測試第一次驗證
8. 加上 backup code 顯示與儲存的 UX
9. 測試登入 challenge 與 recovery 路徑

這個順序很重要，因為如果在 migration 和流程串接完成前就先做 UI，常常會把真正的斷點藏起來，導致除錯方向失準。

很多團隊會漏掉的重要行為

這個 skill 特別指出一個關鍵細節：twoFactorEnabled 不會在使用者一開始啟用時就變成 true，而是要等到第一次 TOTP 驗證成功之後才會切換。這會直接影響：

• onboarding 邏輯
• enrollment 開始後的 UI 狀態
• audit logging
• 使用者掃了 QR code 但從未完成驗證時，客服與支援團隊的判讀方式

這正是此 skill 比一般 MFA 提示詞更有用的地方：它保留了真正會影響實作成敗的行為細節。

這個 skill 不會幫你自動化哪些事

在這個 skill 的 repository 路徑下，沒有內建 scripts、rules 或支援檔案。因此你應該把它當成高訊號的實作指南，而不是 turnkey installer。你仍然需要：

• 依照你的 framework 調整程式碼
• 自行建立 QR code UI
• 決定 backup codes 要如何呈現、確認與保存
• 在自己的 app 中實測 trusted-device 與 recovery 行為

two-factor-authentication-best-practices skill 常見問題

這個 skill 只適用於 Better Auth 嗎？

是。這份 two-factor-authentication-best-practices 指南是專門針對 Better Auth 的 twoFactor plugin，以及相關 client plugin 的使用方式。如果你使用的是 Auth.js、Firebase Auth、Cognito，或自建 auth stack，請改找其他資源。

適合新手嗎？

前提是你已經有一套可運作的 Better Auth 安裝，這樣它對新手算友善；但它不是一份完整的 authentication、database 或 migration workflow 入門教學。

只涵蓋 TOTP 嗎？

不只。skill 說明中也提到 email/SMS OTP、backup codes、trusted devices，以及登入流程處理。不過從可見的設定範例來看，重點最明確的仍是 TOTP，所以如果你要快速落地，TOTP 會是最清晰的一條路。

什麼情況下不該用這個 skill？

以下情況建議跳過這個 skill：

• 你不是使用 Better Auth
• 你需要的是產品比較，而不是實作協助
• 你想要的是不含程式碼的廣義 two-factor-authentication-best-practices 政策建議
• 你要的是 WebAuthn 或 passkeys 作為主要因子，而不是 Better Auth 這套 2FA plugin 流程

這比直接問 AI model 更好嗎？

如果你做的是 Better Auth 專屬的 2FA 實作，通常是。一般模型很可能會給出與 Better Auth plugin API 或啟用行為不一致的 MFA 建議；這個 skill 的價值就在於把解法收斂到正確的 primitives 上。

它對 Access Control 設計有幫助嗎？

有，但只在它的範圍內有幫助。two-factor-authentication-best-practices 在 Access Control 這個角度下，最有價值的情境是你需要在登入與帳號保護上實施 step-up security。若你要處理更廣泛的授權模型，例如 RBAC 或 ABAC，它就沒那麼適合。

如何改進 two-factor-authentication-best-practices skill 的使用效果

提供你實際的檔案路徑與目前程式碼結構

想最快提升輸出品質，最有效的方法就是提供目前的 server 與 client auth 檔案。這樣 skill 才能產出符合你 import 結構、plugin array 形式與路由模式的修改建議。

一開始就明確指定驗證因子與復原策略

直接說清楚你要哪些流程：

• 只要 TOTP
• TOTP 加 backup codes
• TOTP 加 email/SMS fallback
• trusted-device support
• enrollment 前需要重新驗證 password

這些選項會實質改變輸出內容；如果你不說，skill 就只能自行猜測。

明確要求 migration 與驗證步驟

很常見的失敗模式是只拿到 code snippets，卻沒有操作層面的檢查。建議你直接要求：

• migration command
• schema verification step
• 預期應存在的欄位
• enrollment 與 sign-in challenge 的測試案例

這樣會讓 two-factor-authentication-best-practices 的安裝流程更安全，也更容易驗證。

要求 skill 把 setup 與 UX 分開說明

可以要求它依區塊輸出：

1. plugin installation
2. schema changes
3. enrollment UI
4. challenge flow
5. backup/recovery handling
6. test checklist

這樣能避免回答把程式碼、路由與政策建議混在一起，導致內容難以落地。

注意這些常見失敗模式

多數不理想的結果都來自：

• 忘了加 client plugin
• 漏掉 redirect logic
• 沒有執行 migration
• 誤以為第一次驗證前 2FA 就已經啟用
• 只做了 QR 顯示，卻沒處理 backup codes
• 把 trusted devices 當成純 UI 功能看待

如果你在第一版回答裡看到上述缺口，應該要求它重新檢查並修正整體流程。

在第一版之後再迭代

當這個 skill 已經給出一版實作方案後，可以再追問來提升品質：

• 「What edge cases are missing?」
• 「Review this flow for lockout risk.」
• 「Add test scenarios for failed TOTP, backup code use, and device trust.」
• 「Rewrite this for my exact route structure.」

很多時候，真正接近可上線水準的內容，都是在第二輪之後才補齊的。