Migrer depuis reCAPTCHA
Caputchin utilise le même modèle en deux parties que reCAPTCHA, 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. L'échange serveur en particulier reflète à dessein la forme siteverify de reCAPTCHA. 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 reCAPTCHA.
Le modèle mental est inchangé
Tout ce que tu as déjà bâti autour de reCAPTCHA, 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
| reCAPTCHA (case à cocher v2) | Caputchin | |
|---|---|---|
| Script | <script src="https://www.google.com/recaptcha/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| Élément | <div class="g-recaptcha" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| Champ de token dans un formulaire | g-recaptcha-response (auto-injecté) | caputchin-token (auto-injecté) |
| Lire le token en JS | grecaptcha.getResponse() | le detail.token de l'événement pass |
Comme reCAPTCHA, 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.
| reCAPTCHA | Caputchin | |
|---|---|---|
| Point de terminaison | POST https://www.google.com/recaptcha/api/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" } | { success, challenge_ts, hostname, error-codes, score? } |
| 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. 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.
3. Mappe le score, si tu utilisais reCAPTCHA v3
reCAPTCHA v3 renvoie un score (0.0 à 1.0) et te demande de choisir un seuil, tu devines à quel point une requête semblait humaine. Caputchin ne fonctionne pas comme ça : success est un réussite/échec faisant autorité, parce que la vérification a réellement été réussie (une vérification de proof of work, ou une manche de jeu re-dérivée sur le serveur), pas une probabilité.
Si ton code avait if (data.score >= 0.5), remplace-le par if (data.success). Le champ score de Caputchin n'existe que pour les manches de jeu et est le score du jeu (informatif, pour tes propres tableaux des scores), jamais une probabilité de bot, donc ne fonde pas l'accès dessus.
Ce qui s'améliore dans le passage
- Aucune collecte de données visiteur. reCAPTCHA profile tes visiteurs ; 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 widget, pas v2-contre-v3. Il n'y a pas de produit invisible/score séparé entre lesquels choisir ; un élément couvre la case à cocher et le jeu optionnel.
- Un jeu optionnel. Au lieu d'une grille de feux de circulation, tu peux transformer la vérification en un court jeu que tes visiteurs jouent réellement. 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 reCAPTCHA. Ne livre pas le secret au navigateur. - Le token est à usage unique. Comme reCAPTCHA, 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, pasg-recaptcha-response, un oubli d'une ligne courant.
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.