> ## Documentation Index > Fetch the complete documentation index at: https://supastack.dev/llms.txt > Use this file to discover all available pages before exploring further. > For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt # Proteção anti-spam Verificações Turnstile comutáveis por env em formulários públicos e endpoints de auth. ## 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](https://supastack.dev/pt/docs/web/before-you-start.md) [Noções básicas sobre terminais](https://supastack.dev/pt/docs/web/terminal-basics.md) [Configuração local da Web](https://supastack.dev/pt/docs/web/ship-in-5-minutes.md) [Avisos do agente e memória do projeto](https://supastack.dev/pt/docs/web/agents.md) ## 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](https://supastack.dev/pt/docs/web/project-structure.md) [Diferenças do mecanismo de autenticação](https://supastack.dev/pt/docs/web/project-structure.md) ## 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. ## Seguinte [Consola de administração](https://supastack.dev/pt/docs/web/admin.md)