Migrer depuis hCaptcha
Caputchin utilise le même modèle en deux parties que hCaptcha, 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 la forme siteverify que hCaptcha lui-même suit. 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 hCaptcha.
Le modèle mental est inchangé
Tout ce que tu as déjà bâti autour de hCaptcha, 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
| hCaptcha | Caputchin | |
|---|---|---|
| Script | <script src="https://js.hcaptcha.com/1/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| Élément | <div class="h-captcha" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| Champ de token dans un formulaire | h-captcha-response (auto-injecté) | caputchin-token (auto-injecté) |
| Lire le token en JS | hcaptcha.getResponse() | le detail.token de l'événement pass |
Comme hCaptcha, 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.
| hCaptcha | Caputchin | |
|---|---|---|
| Point de terminaison | POST https://api.hcaptcha.com/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", score? } | { success, challenge_ts, hostname, error-codes, score? } |
| Règle de confiance | agis seulement si success === true | agis seulement si success === true (identique) |
Une note de format : le point de terminaison de vérification de hCaptcha attend application/x-www-form-urlencoded, tandis que celui de Caputchin accepte du JSON. Si ton code existant envoyait des champs encodés en formulaire, bascule le corps en JSON ({"secret":"...","response":"..."}) avec Content-Type: application/json. Les champs eux-mêmes sont inchangés. La référence complète requête/réponse est sur vérifier un token sur ton backend ; les extraits par framework sont dans exemples backend.
3. Laisse tomber le score, si tu utilisais hCaptcha Enterprise
hCaptcha Enterprise renvoie un score de risque (où un nombre plus haut signifie plus de risque) et te demande de choisir un seuil. 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 estimation de risque.
Si ton code avait if (data.score < 0.7), remplace-le par if (data.success). Le champ score de Caputchin n'a aucun rapport : il n'existe que pour les manches de jeu et est le score du jeu (informatif, pour tes propres tableaux des scores), jamais un risque ou une probabilité de bot, donc ne fonde pas l'accès dessus. (Note que la direction est aussi opposée, le score de hCaptcha monte avec le risque ; celui de Caputchin monte avec la performance de jeu.)
Ce qui se reporte, et ce qui s'améliore
- La posture de confidentialité pour laquelle tu as choisi hCaptcha, 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, donc il n'y en a aucun à laisser fuiter ni à vendre. Vois la philosophie.
- Un jeu optionnel. Au lieu d'une épreuve de sélection d'images, 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 hCaptcha. Ne livre pas le secret au navigateur. - Le token est à usage unique. Comme hCaptcha, 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, pash-captcha-response, un oubli d'une ligne courant. - Format du corps. Envoie la requête de vérification en JSON, pas encodée en formulaire.
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.