two-factor-authentication-best-practices

Visão geral da skill two-factor-authentication-best-practices

A skill two-factor-authentication-best-practices é um guia de implementação focado em adicionar 2FA a uma configuração com Better Auth, não um material genérico explicando MFA. Ela é mais indicada para desenvolvedores que já usam Better Auth e precisam de orientação prática, com pouca margem para tentativa e erro, para apps TOTP, entrega de OTP, códigos de backup, tratamento de dispositivos confiáveis e mudanças no fluxo de login exigidas pelo plugin twoFactor.

O que esta skill ajuda você a fazer

Use esta skill quando o objetivo real for colocar no ar um fluxo de 2FA seguro e funcional para Access Control com Better Auth: instalar o plugin, conectar corretamente as partes de servidor e cliente, rodar migrations e cuidar da jornada do usuário do setup até a verificação e recuperação.

Para quem ela é mais indicada

Esta skill é uma ótima escolha para:

• usuários de Better Auth adicionando MFA a uma aplicação existente
• times que precisam de two-factor-authentication-best-practices prático, e não teoria
• desenvolvedores implementando reforço de login com TOTP primeiro, seguido de caminhos de fallback como códigos de backup ou entrega de OTP

O que a diferencia de um prompt genérico

Um prompt comum pode descrever conceitos de MFA. Esta skill é mais útil quando você precisa de detalhes específicos de uso com Better Auth:

• configuração do plugin no servidor com twoFactor()
• configuração do plugin no cliente com twoFactorClient()
• migration e verificação de schema
• comportamento do fluxo de ativação, incluindo quando o 2FA passa a ficar realmente habilitado
• tratamento de redirect durante o login

O que saber antes de instalar

Esta skill é propositalmente específica. Ela assume que Better Auth já faz parte da sua stack. Se você precisa de arquitetura de autenticação neutra em relação a fornecedor, redação de políticas de compliance ou comparação entre produtos de MFA, este não é o ponto de partida certo.

Como usar a skill two-factor-authentication-best-practices

Contexto de instalação desta skill

Esta skill fica no repositório better-auth/skills, em better-auth/twoFactor. Como as evidências do repositório mostram apenas um arquivo SKILL.md e nenhuma automação auxiliar ou referências extras, espere que o valor esteja na orientação direta de implementação, e não em scripts prontos.

Se o seu ambiente usa um skill loader, instale a partir do repositório e aponte para a skill twoFactor. Se você estiver consultando manualmente, abra:

• better-auth/twoFactor/SKILL.md

Leia este arquivo primeiro

Comece por SKILL.md antes de mexer no código da sua aplicação. Nesta skill, esse arquivo reúne as decisões mais importantes para quem vai implementar:

• configuração do servidor
• configuração do cliente
• etapa de migration
• fluxo de ativação
• comportamento da verificação TOTP

Este é um caso raro em que ler primeiro o único arquivo-fonte já basta para decidir rapidamente se a skill serve para o seu cenário.

Entradas mínimas que a skill precisa

Para obter uma saída útil da skill two-factor-authentication-best-practices, informe:

• o caminho do arquivo de configuração do servidor Better Auth
• o caminho do arquivo de configuração do cliente Better Auth
• se você quer apenas TOTP ou TOTP com OTP por email/SMS
• o status da sua tabela de usuários e das migrations
• a UX desejada para setup, desafio, códigos de backup e dispositivos confiáveis

Sem esses detalhes, o resultado tende a ficar genérico demais.

Caminho principal de configuração

O caminho prático de configuração mostrado pela skill é:

1. Adicionar twoFactor() à configuração de servidor do Better Auth
2. Definir um issuer
3. Adicionar twoFactorClient() à configuração do cliente
4. Executar npx @better-auth/cli migrate
5. Verificar se a tabela de usuários contém a coluna de segredo de 2FA esperada

Essa checagem da migration importa porque muitas instalações que falham, na prática, são problemas de incompatibilidade de schema, e não do plugin em si.

Exemplo do lado do servidor para orientar sua implementação

A skill centraliza a configuração do servidor desta forma:

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

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

Na prática, a entrada mais importante é o issuer, porque ele afeta como o app autenticador exibe a conta e o nível de confiança do usuário durante o setup.

Exemplo do lado do cliente e tratamento de redirect

O fluxo do cliente importa tanto quanto a instalação do 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";
      },
    }),
  ],
});

Em two-factor-authentication-best-practices para Access Control, não trate o handling de redirect como um acabamento opcional. Ele faz parte do fluxo de autenticação. Decida cedo onde vai ficar a tela de desafio e de que estado ela precisa.

Como escrever um bom prompt para a skill

Um pedido fraco:

• "Help me add 2FA"

Um pedido forte:

• "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."

A versão mais forte dá contexto suficiente para a skill produzir uma resposta pronta para implementação, em vez de conselhos amplos.

Como transformar um objetivo vago em um prompt completo

Use este padrão para aproveitar melhor a skill two-factor-authentication-best-practices:

• stack atual: framework, local dos arquivos do Better Auth
• fatores desejados: TOTP, email OTP, SMS OTP, códigos de backup
• pontos de UX: página de ativação, rota de desafio, fluxo de recuperação
• regras de segurança: verificação de senha, dispositivos confiáveis, comportamento de sessão
• formato de saída: patch, checklist, snippets de código ou notas de revisão

Exemplo:

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.

Fluxo de trabalho que reduz erros

Uma sequência confiável é:

1. Confirmar que o Better Auth já funciona sem 2FA
2. Adicionar o plugin no servidor
3. Adicionar o plugin no cliente e a lógica de redirect
4. Rodar a migration
5. Verificar as mudanças no schema
6. Implementar a UI de ativação
7. Testar a primeira verificação
8. Adicionar a UX de exibição e armazenamento dos códigos de backup
9. Testar o desafio no login e os caminhos de recuperação

Essa ordem importa porque fazer a UI antes da migration e da ligação do fluxo costuma esconder os verdadeiros pontos de quebra.

Comportamento importante que muitos times deixam passar

A skill destaca um detalhe crítico: twoFactorEnabled não passa a ser true até que a primeira verificação TOTP seja concluída com sucesso. Isso afeta:

• lógica de onboarding
• estado da UI depois que a ativação começa
• audit logging
• expectativa do suporte quando o usuário escaneia um QR code mas nunca conclui a verificação

Esse é exatamente o tipo de detalhe de implementação que torna a skill mais útil do que um prompt genérico sobre MFA.

O que esta skill não automatiza

Não há scripts, regras ou arquivos de suporte incluídos no caminho deste repositório para esta skill. Portanto, trate-a como um guia de alto sinal, não como um instalador turnkey. Você ainda precisa:

• adaptar o código ao seu framework
• construir a UI do QR code
• decidir como os códigos de backup serão exibidos e confirmados
• testar o comportamento de dispositivos confiáveis e recuperação dentro da sua própria aplicação

FAQ da skill two-factor-authentication-best-practices

Esta skill é só para Better Auth?

Sim. Este guia two-factor-authentication-best-practices trata especificamente do plugin twoFactor do Better Auth e do uso do plugin correspondente no cliente. Se você usa Auth.js, Firebase Auth, Cognito ou uma stack de autenticação própria, procure outro recurso.

Ela é boa para iniciantes?

Ela é amigável para iniciantes apenas se você já tiver uma instalação funcional de Better Auth. Não é uma introdução completa a autenticação, bancos de dados ou fluxos de migration.

Ela cobre apenas TOTP?

Não. A descrição da skill também aponta para OTP por email/SMS, códigos de backup, dispositivos confiáveis e tratamento do fluxo de login. Mas os exemplos visíveis de configuração enfatizam fortemente TOTP, então espere que TOTP seja o caminho mais claro.

Quando eu não deveria usar esta skill?

Ignore esta skill se:

• você não usa Better Auth
• você precisa de comparação de produtos, não de ajuda de implementação
• você quer orientações amplas de política de two-factor-authentication-best-practices sem código
• você precisa de WebAuthn ou passkeys como fator principal, em vez do fluxo de plugin 2FA do Better Auth

Ela é melhor do que perguntar direto para um modelo de IA?

Para trabalho de 2FA específico de Better Auth, em geral sim. Um modelo genérico pode sugerir padrões de MFA que não combinam com as APIs dos plugins do Better Auth nem com o comportamento de ativação. Esta skill reduz o espaço de solução aos componentes certos.

Ela ajuda com design de Access Control?

Sim, dentro do escopo. O ângulo de two-factor-authentication-best-practices para Access Control é mais forte quando você precisa reforçar a segurança no login e na proteção da conta. Ela é menos útil para modelos mais amplos de autorização, como RBAC ou ABAC.

Como melhorar a skill two-factor-authentication-best-practices

Informe os caminhos reais dos arquivos e o formato atual do código

A forma mais rápida de melhorar a qualidade da resposta é fornecer os arquivos atuais de autenticação do servidor e do cliente. Isso permite que a skill produza edições compatíveis com a sua estrutura de imports, o formato do array de plugins e os padrões de roteamento do projeto.

Defina o fator e a política de recuperação desde o início

Diga exatamente quais fluxos você quer:

• apenas TOTP
• TOTP com códigos de backup
• TOTP com fallback por email/SMS
• suporte a dispositivos confiáveis
• revalidação de senha antes da ativação

Essas escolhas mudam materialmente a resposta. Se você omitir isso, a skill terá de adivinhar.

Peça explicitamente as etapas de migration e verificação

Um modo comum de falha é receber snippets de código sem as validações operacionais. Peça:

• comando de migration
• etapa de verificação do schema
• presença esperada da coluna
• casos de teste para ativação e desafio no login

Isso torna o processo de instalação de two-factor-authentication-best-practices mais seguro.

Peça que a skill separe setup de UX

Solicite a resposta em seções:

1. instalação do plugin
2. mudanças no schema
3. UI de ativação
4. fluxo de desafio
5. tratamento de backup/recuperação
6. checklist de testes

Isso evita respostas misturadas, em que código, roteamento e recomendações de política aparecem embaralhados.

Fique atento a estes modos de falha comuns

A maioria dos resultados ruins vem de:

• esquecer o plugin do cliente
• não implementar a lógica de redirect
• não rodar a migration
• assumir que o 2FA está habilitado antes da primeira verificação
• implementar a exibição do QR sem tratar os códigos de backup
• tratar dispositivos confiáveis como recurso apenas de UI

Se você encontrar uma dessas lacunas na primeira resposta, peça uma revisão corrigindo o fluxo.

Faça uma segunda iteração depois do primeiro rascunho

Depois que a skill entregar um plano de implementação, melhore o resultado pedindo:

• "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."

Essa segunda rodada é, muitas vezes, o momento em que a skill realmente fica pronta para uso em produção.