Migrer depuis Cloudflare Turnstile
Caputchin utilise le même modèle en deux parties que Cloudflare Turnstile, un widget sur la page qui produit un token, et une vérification côté serveur qui le confirme, donc migrer est surtout un échange mécanique, pas une réécriture. Turnstile est le plus proche de Caputchin parmi les fournisseurs courants, parce que les deux renvoient un réussite/échec faisant autorité plutôt qu'un score de risque, donc il n'y a pas de seuil à réajuster. Ce guide donne l'avant-après pour chaque pièce.
Si tu n'as pas encore créé de compte Caputchin et de clé de site, fais d'abord créer ton compte ; tu auras besoin d'une clé publique (cpt_pub_...) pour la page et d'un secret (cpt_sec_...) pour ton backend, le même partage que la clé de site et la clé secrète de Turnstile.
Le modèle mental est inchangé
Tout ce que tu as déjà bâti autour de Turnstile, rendre un widget, collecter un token, le POSTer vers ton serveur, le vérifier avant de faire confiance à la requête, reste. Seuls les noms et les points de terminaison changent.
1. Échange l'extrait client
| Turnstile | Caputchin | |
|---|---|---|
| Script | <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| Élément | <div class="cf-turnstile" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| Champ de token dans un formulaire | cf-turnstile-response (auto-injecté) | caputchin-token (auto-injecté) |
| Lire le token en JS | turnstile.getResponse() | le detail.token de l'événement pass |
Comme Turnstile, le widget Caputchin auto-injecte un champ de token caché dans le formulaire où il se trouve, donc si ton formulaire faisait déjà un POST normal, tu ne changes que l'élément et le nom du champ que ton backend lit. Vois ajouter le widget pour la configuration client complète et le choix CDN contre npm.
2. Échange la vérification serveur
C'est là que les deux sont les plus proches, les formes de requête et de réponse s'alignent presque champ pour champ.
| Turnstile | Caputchin | |
|---|---|---|
| Point de terminaison | POST https://challenges.cloudflare.com/turnstile/v0/siteverify | POST https://caputchin.com/api/v1/siteverify |
| Champs de requête | secret, response | secret, response (identiques) |
| Réponse | { success, challenge_ts, hostname, "error-codes", action, cdata } | { success, challenge_ts, hostname, error-codes } |
| Règle de confiance | agis seulement si success === true | agis seulement si success === true (identique) |
Dans la plupart des stacks, le seul changement à ton code de vérification est l'URL et la valeur du secret ; les deux branchent déjà sur success, donc il n'y a pas de seuil de score à porter. Turnstile accepte aussi du JSON pour l'appel de vérification, exactement comme Caputchin, donc la forme du corps se reporte inchangée. La référence complète requête/réponse, y compris les codes d'erreur, est sur vérifier un token sur ton backend ; les extraits par framework sont dans exemples backend.
Si ton intégration Turnstile lisait action ou cdata dans la réponse, note que Caputchin n'a pas d'équivalent direct ; ce sont des libellés spécifiques à Turnstile que tu règles sur le widget. La métadonnée analogue de Caputchin (quel jeu a été joué, son score) vit dans le bloc platform de la réponse et est informative uniquement.
Ce qui se reporte, et ce qui s'améliore
- Toujours un réussite/échec net. Tu gardes la règle de confiance la plus simple possible,
if (success), sans probabilité ni seuil à maintenir. - La posture de confidentialité pour laquelle tu as choisi Turnstile, gardée. Caputchin ne collecte ni IP, ni User-Agent, ni empreinte, ni télémétrie comportementale ; le protocole n'a nulle part où mettre un identifiant de visiteur. Vois la philosophie.
- Un jeu optionnel. Au lieu d'une épreuve invisible ou gérée, tu peux transformer la vérification en un court jeu que tes visiteurs jouent réellement, et c'est la partie qui tient bon face aux solveurs IA. Vois ajouter un jeu.
- Une CSP stricte reste stricte. Caputchin tourne sous une Content-Security-Policy serrée ; tu autorises quelques origines plutôt que de relâcher ta politique. Vois comment Caputchin met les jeux en bac à sable.
Pièges
- Deux clés, deux foyers. La clé publique (
cpt_pub_...) va sur la page ; le secret (cpt_sec_...) reste côté serveur uniquement, exactement la discipline Turnstile. Ne livre pas le secret au navigateur. - Le token est à usage unique. Comme Turnstile, un token se vérifie une fois. Ne le mets ni en cache ni en rejeu.
- Change le nom du champ que ton backend lit. Le champ caché est
caputchin-token, pascf-turnstile-response, un oubli d'une ligne courant. - Pas d'
action/cdata. Si tu branchais dessus, déplace cette logique ailleurs ; Caputchin ne les porte pas.
Voir aussi
- Ajouter le widget : la configuration client complète.
- Vérifier un token sur ton backend : la référence
siteverifyfaisant autorité. - Exemples backend : l'appel de vérification dans chaque langage.
- Ajouter un jeu : transformer la vérification en un jeu.