Proteção anti-spam

Passo a passo para iniciantes

Pré-requisitos: Leia os dois guias para iniciantes abaixo, conclua a configuração local da Web e abra este monorepo na raiz do seu editor. As configurações da Web pertencem a apps/web/.env.local; Next.js não lê a raiz .env. /dashboard no modo falso padrão é uma demonstração sem banco de dados; /auth precisa de um banco de dados migrado.

Termos rápidos: um espaço de trabalho consiste em usuários, dados e configurações separados de uma equipe. O servidor é o back-end confiável; mantenha as chaves do provedor fora do navegador e do código do telefone. Uma migração é uma alteração de versão do banco de dados que cria ou atualiza tabelas. Um modelo de IA é o mecanismo que responde; o catálogo de modelos é a lista do servidor de IDs e preços de modelos disponíveis. Um provedor é um serviço externo, como IA, e-mail ou serviço de cobrança. Um direito é uma concessão que permite que um espaço de trabalho use um recurso. Um webhook é uma mensagem que um serviço envia para o URL de outro serviço.

1. Crie um widget de teste Turnstile para o nome de host local/implantado exato. Em apps/web/.env.local, defina CAPTCHA_PROVIDER=turnstile e NEXT_PUBLIC_TURNSTILE_SITE_KEY; coloque TURNSTILE_SECRET_KEY apenas no armazenamento secreto do servidor.

2. Reinicie e envie um formulário de contato de teste.

3. Espere o desafio e uma resposta de token válido bem-sucedida. Se cada solicitação falhar, compare o nome do host e o par de chaves; nunca exponha a chave secreta.

Para código personalizado, comece com o prompts/README.md fornecido e copie o prompt mais próximo: prompts/new-app-screen.md para uma tela de aplicativo ou prompts/new-landing-page.md para uma página pública. Para trabalho de servidor, banco de dados ou provedor, dê ao seu agente de codificação a tarefa deste guia e peça-lhe para ler AGENTS.md, .ai/PROJECT_CONTEXT.md e espelhos .ai/ correspondentes; inspecione os arquivos de origem exatos nomeados aqui; listar arquivos e verificações antes de editar; preservar a propriedade do espaço de trabalho e os segredos apenas do servidor; e mostrar a diferença. Informe o comportamento desejado, campos de entrada e saída, funções permitidas, sucessos e erros esperados e a conta de teste, provedor ou dispositivo. Use valores de amostra; nunca cole um segredo real.

• Antes de começar
• Noções básicas sobre terminais
• Configuração local da Web
• Avisos do agente e memória do projeto

Habilite ambas as chaves

CAPTCHA_PROVIDER=off é o padrão. Selecione turnstile, configure o nome do host correspondente em seu aplicativo Turnstile e forneça ambas as chaves. NEXT_PUBLIC_TURNSTILE_SITE_KEY é público; TURNSTILE_SECRET_KEY é usado apenas pelo verificador do servidor.

CAPTCHA_PROVIDER=turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
# TURNSTILE_SECRET_KEY belongs in the server secret store.

Preservar as superfícies protegidas

O portão cobre formulários de contato/boletim informativo e pontos de extremidade de credenciais de redefinição de senha e login Better Auth, inscrição, OTP. Complementa a validação/limitação de taxa; não substitui sessões ou autorização de espaço de trabalho.

Verifique rejeição e recuperação

Teste um token válido, um token ausente/expirado/inválido, uma falha no verificador e uma nova tentativa após a redefinição do widget do cliente. Mantenha cópia de verificação humana acionável e acesso ao teclado; inspecione a cobertura do mecanismo de autenticação escolhido antes de mudar de provedor.

• Formulários protegidos
• Diferenças do mecanismo de autenticação

Instalação e configuração

O CAPTCHA_PROVIDER seleciona o verificador: off (o padrão, para o desenvolvimento local ficar sem credenciais) ou turnstile. Ativar o turnstile exige TURNSTILE_SECRET_KEY no servidor e NEXT_PUBLIC_TURNSTILE_SITE_KEY para o widget de cliente — o schema de config falha o arranque se faltar algum.

O apps/web/src/captcha.ts compõe um verificador único por processo que envia o token ao endpoint siteverify da Cloudflare com um timeout de dez segundos e falha fechado — um token não verificável nunca conta como prova de humanidade.

CAPTCHA_PROVIDER=turnstile
TURNSTILE_SECRET_KEY=…           # server-only
NEXT_PUBLIC_TURNSTILE_SITE_KEY=…

Guarded: sign-in/up, OTP send, reset,
contact + newsletter forms

Fluxo de implementação

O CaptchaWidget (src/captcha-widget.tsx) renderiza o widget e injeta o campo cf-turnstile-response no formulário pai, enquanto as chamadas do cliente de auth levam o token no cabeçalho x-captcha-response. As ações de contacto e newsletter verificam antes de escrever — uma verificação falhada devolve status=captcha em vez de criar um lead.

O packages/auth monta o plugin captcha do better-auth quando o provider está ativo; o CAPTCHA_ENDPOINTS cobre as rotas de introdução de credenciais e emissão de tokens — sign-in, sign-up, envio de OTP, reposição de palavra-passe. Endpoints consumidores como o check-verification-otp ficam fora da lista: aí o próprio OTP ou token é a prova.

Verificação e resolução de problemas

Submete cada formulário protegido com um token em falta e com um malformado — ambos têm de falhar fechado. Verifica que um siteverify inacessível rejeita em vez de deixar passar, que provider=off mantém o desenvolvimento local aberto, e que o segredo nunca chega aos bundles do cliente nem aos logs.