Migre do Cloudflare Turnstile

O Caputchin usa o mesmo modelo em duas partes do Cloudflare Turnstile, um widget na página que produz um token e uma conferência no servidor que o confirma, então migrar é em boa parte uma troca mecânica, não uma reescrita. O Turnstile é o mais próximo do Caputchin entre os provedores comuns, porque ambos retornam um aprova/reprova autoritativo em vez de um score de risco, então não há limiar para reajustar. Este guia dá o antes e depois de cada peça.

Se você ainda não criou uma conta e uma chave de site no Caputchin, crie sua conta primeiro; você vai precisar de uma chave pública (cpt_pub_...) para a página e de um segredo (cpt_sec_...) para o seu backend, a mesma divisão da chave de site e da chave secreta do Turnstile.

O modelo mental não muda

Tudo o que você já construiu em torno do Turnstile, renderizar um widget, coletar um token, fazer POST dele no seu servidor, verificá-lo antes de confiar na requisição, permanece. Só os nomes e os endpoints mudam.

1. Troque o trecho do cliente

Como o Turnstile, o widget do Caputchin autoinjeta um campo de token oculto no formulário em que fica, então se o seu formulário já fazia um POST normal, você só muda o elemento e o nome do campo que seu backend lê. Veja adicionar o widget para a configuração completa do cliente e a escolha entre CDN e npm.

2. Troque a verificação no servidor

É aqui que os dois ficam mais próximos, os formatos de requisição e resposta se alinham quase campo a campo.

Na maioria dos stacks, a única mudança no seu código de verificação é a URL e o valor do segredo; ambos já ramificam em success, então não há limiar de score para portar. O Turnstile também aceita JSON na chamada de verificação, exatamente como o Caputchin, então o formato do corpo se mantém inalterado. A referência completa de requisição/resposta, incluindo os códigos de erro, está em verificar um token no seu backend; trechos por framework estão em exemplos de backend.

Se a sua integração com o Turnstile lia action ou cdata na resposta, note que o Caputchin não tem equivalente direto; esses são rótulos específicos do Turnstile que você define no widget. O metadado análogo do Caputchin (qual jogo foi jogado, sua pontuação) vive no bloco platform da resposta e é apenas informativo.

O que se mantém, e o que melhora

• Ainda um aprova/reprova limpo. Você mantém a regra de confiança mais simples possível, if (success), sem probabilidade nem limiar para manter.
• A postura de privacidade pela qual você escolheu o Turnstile, mantida. O Caputchin não coleta IP, User-Agent, impressão digital nem telemetria comportamental; o protocolo não tem onde pôr um identificador de visitante. Veja a filosofia.
• Um jogo opcional. Em vez de um desafio invisível ou gerenciado, você pode transformar a verificação em um jogo curto que seus visitantes de fato jogam, e é a parte que resiste a solucionadores de IA. Veja adicionar um jogo.
• Uma CSP estrita continua estrita. O Caputchin roda sob uma Content-Security-Policy apertada; você permite algumas origens em vez de afrouxar sua política. Veja como o Caputchin coloca os jogos em sandbox.

Pegadinhas

• Duas chaves, dois lares. A chave pública (cpt_pub_...) vai na página; o segredo (cpt_sec_...) fica só no servidor, exatamente a disciplina do Turnstile. Não envie o segredo ao navegador.
• O token é de uso único. Como no Turnstile, um token verifica uma vez. Não o cacheie nem o reenvie.
• Mude o nome do campo que seu backend lê. O campo oculto é caputchin-token, não cf-turnstile-response, um deslize comum de uma linha.
• Sem action / cdata. Se você ramificava nesses, mova essa lógica para outro lugar; o Caputchin não os carrega.

Veja também

• Adicionar o widget: a configuração completa do cliente.
• Verificar um token no seu backend: a referência autoritativa do siteverify.
• Exemplos de backend: a chamada de verificação em cada linguagem.
• Adicionar um jogo: transforme a verificação em um jogo.