Démarrage rapide
Cap comporte deux parties : un widget, qui s'exécute et résout les défis dans le navigateur du visiteur puis vous remet un jeton, et le serveur (capd), qui émet les défis et vérifie ces jetons.
1. Installer capd
Vous devez d'abord installer capd. Il s'exécute comme un serveur auto-hébergé avec un tableau de bord, des statistiques, des règles et une API. Les clés et les réglages sont stockés dans Valkey. Avant de commencer, vous avez deux choix à faire :
1. Où exécuter capd : vous pouvez l'exécuter sur votre propre serveur avec Docker, utiliser Railway, ou passer par une plateforme serverless comme Workers. Ce guide utilise Docker.
2. Où stocker les statistiques : vous pouvez utiliser DuckDB (léger, idéal pour les petits sites) ou ClickHouse (plus adapté à la montée en charge). Les deux sont intégrés et simples à mettre en place.
curl -fsSLo docker-compose.yml https://raw.githubusercontent.com/tiagozip/cap/main/capd/docker-compose.duckdb.yml
echo "ADMIN_KEY=$(openssl rand -hex 24)" > .env
docker compose up -dcurl -fsSLo docker-compose.yml https://raw.githubusercontent.com/tiagozip/cap/main/capd/docker-compose.yml
echo "ADMIN_KEY=$(openssl rand -hex 24)" > .env
docker compose up -dOuvrez http://localhost:3000 et connectez-vous avec le ADMIN_KEY de .env, qui est le mot de passe du tableau de bord. Créez une clé de site et copiez à la fois la clé de site et sa clé secrète.
Le widget communique avec ce serveur depuis le navigateur de vos visiteurs, il lui faut donc une URL publique en production. Nous recommandons une solution comme Tunnels, mais la documentation de capd couvre la plupart des autres cas, y compris les reverse proxies.
2. Ajouter le widget
Chargez le script en épinglant une version issue de la page des versions :
<script src="https://cdn.jsdelivr.net/npm/cap-widget@<version>"></script>Placez le widget dans votre formulaire :
<form action="/submit" method="POST">
<cap-widget data-cap-api-endpoint="https://cap.example.com/<site-key>/"></cap-widget>
<button type="submit">Submit</button>
</form>Le point d'accès est https://<your-instance>/<site-key>/.
Quand le visiteur résout le défi, le widget ajoute un champ caché cap-token au formulaire. En dehors d'un formulaire, écoutez plutôt l'événement solve :
document.querySelector("cap-widget").addEventListener("solve", (e) => {
const token = e.detail.token;
});La page du widget contient des extraits pour React, Vue, Svelte et d'autres frameworks.
3. Vérifier le jeton
Avant de faire confiance à une soumission, envoyez son jeton à /siteverify depuis votre serveur :
const res = await fetch("https://cap.example.com/<site-key>/siteverify", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ secret: "<secret>", response: token }),
});
const { success } = await res.json();import requests
success = requests.post(
"https://cap.example.com/<site-key>/siteverify",
json={"secret": "<secret>", "response": token},
).json()["success"]$res = file_get_contents("https://cap.example.com/<site-key>/siteverify", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Content-Type: application/json",
"content" => json_encode(["secret" => "<secret>", "response" => $token]),
],
]));
$success = json_decode($res, true)["success"] ?? false;curl -X POST "https://cap.example.com/<site-key>/siteverify" \
-H "Content-Type: application/json" \
-d '{"secret": "<secret>", "response": "<token>"}'<secret> est la clé secrète de la clé de site, pas votre ADMIN_KEY. Confondre les deux est l'erreur d'installation la plus fréquente.
Si vous venez de reCAPTCHA, /siteverify accepte le même format de requête, il suffit donc que votre code de vérification utilise le nom d'hôte de votre serveur.
Un jeton valide renvoie { "success": true }. Chaque jeton ne fonctionne qu'une fois, donc une seconde vérification du même jeton échoue. L'envoyer deux fois permet de tester rapidement l'installation de bout en bout.
Utiliser la bibliothèque core à la place
Si vous préférez émettre et vérifier les défis dans votre propre backend, la bibliothèque core est un paquet npm minimal qui ne fait que cela. Vous stockez les jetons dans votre propre base de données, et vous n'avez ni tableau de bord, ni statistiques, ni limitation de débit.
Étapes suivantes
- Personnaliser le widget : ses libellés, sa langue et son style
- Configurer capd : proxies, fichiers du widget et API
- Lire la référence de la bibliothèque core
- Lire comment fonctionne Cap
