Von Cloudflare Turnstile migrieren
Caputchin nutzt dasselbe zweiteilige Modell wie Cloudflare Turnstile, ein Widget auf der Seite, das ein Token produziert, und eine serverseitige Prüfung, die es bestätigt, also ist das Migrieren meist ein mechanischer Tausch, kein Neuschreiben. Turnstile ist der nächste der gängigen Anbieter zu Caputchin, weil beide ein maßgebliches Bestanden/Nicht zurückgeben statt eines Risiko-Scores, also gibt es keine Schwelle neu zu justieren. Diese Anleitung gibt das Vorher-und-Nachher für jedes Stück.
Hast du noch kein Caputchin-Konto und keinen Site-Key erstellt, mach zuerst dein Konto erstellen; du brauchst einen Public Key (cpt_pub_...) für die Seite und ein Secret (cpt_sec_...) für dein Backend, dieselbe Aufteilung wie Turnstiles Site-Key und Secret-Key.
Das mentale Modell ist unverändert
Alles, was du schon um Turnstile gebaut hast, ein Widget rendern, ein Token sammeln, es an deinen Server POSTen, es verifizieren, bevor du der Anfrage traust, bleibt. Nur die Namen und Endpunkte ändern sich.
1. Den Client-Snippet tauschen
| Turnstile | Caputchin | |
|---|---|---|
| Skript | <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"> |
| Element | <div class="cf-turnstile" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| Token-Feld in einem Formular | cf-turnstile-response (auto-eingefügt) | caputchin-token (auto-eingefügt) |
| Das Token in JS lesen | turnstile.getResponse() | das pass-Event detail.token |
Wie Turnstile fügt das Caputchin-Widget ein verstecktes Token-Feld automatisch ein in das Formular, in dem es sitzt, sodass du, wenn dein Formular schon einen normalen POST machte, nur das Element und den Feldnamen änderst, den dein Backend liest. Sieh dir das Widget hinzufügen für die vollständige Client-Einrichtung und die CDN-vs-npm-Wahl an.
2. Die Server-Verifizierung tauschen
Hier sind die zwei am nächsten, die Anfrage- und Antwortformen reihen sich fast Feld für Feld auf.
| Turnstile | Caputchin | |
|---|---|---|
| Endpunkt | POST https://challenges.cloudflare.com/turnstile/v0/siteverify | POST https://caputchin.com/api/v1/siteverify |
| Anfragefelder | secret, response | secret, response (identisch) |
| Antwort | { success, challenge_ts, hostname, "error-codes", action, cdata } | { success, challenge_ts, hostname, error-codes } |
| Vertrauensregel | nur handeln, wenn success === true | nur handeln, wenn success === true (identisch) |
In den meisten Stacks ist die einzige Änderung an deinem Verifizierungscode die URL und der Secret-Wert; beide verzweigen schon auf success, also gibt es keine Score-Schwelle zu portieren. Turnstile akzeptiert auch JSON für den Verifizierungs-Aufruf, genau wie Caputchin, also überträgt sich die Body-Form unverändert. Die vollständige Anfrage-/Antwort-Referenz, einschließlich der Error-Codes, ist auf ein Token auf deinem Backend verifizieren; Framework-Snippets sind in Backend-Beispielen.
Las deine Turnstile-Integration action oder cdata aus der Antwort, beachte, dass Caputchin kein direktes Äquivalent hat; das sind Turnstile-spezifische Labels, die du auf dem Widget setzt. Caputchins analoge Metadaten (welches Spiel gespielt wurde, seine Punktzahl) leben im platform-Block der Antwort und sind nur informativ.
Was übernommen wird und was sich verbessert
- Immer noch ein sauberes Bestanden/Nicht. Du behältst die einfachste mögliche Vertrauensregel,
if (success), ohne Wahrscheinlichkeit oder Schwelle zu pflegen. - Die Datenschutz-Haltung, für die du Turnstile gewählt hast, bleibt. Caputchin erfasst keine IP, keinen User-Agent, keinen Fingerabdruck und keine Verhaltens-Telemetrie; das Protokoll hat nirgendwo, einen Besucher-Identifier abzulegen. Sieh dir die Philosophie an.
- Ein optionales Spiel. Statt einer unsichtbaren oder gemanagten Aufgabe kannst du die Verifizierung in ein kurzes Spiel verwandeln, das deine Besucher tatsächlich spielen, und es ist der Teil, der gegen KI-Löser standhält. Sieh dir ein Spiel hinzufügen an.
- Eine strikte CSP bleibt strikt. Caputchin läuft unter einer engen Content-Security-Policy; du erlaubst ein paar Origins, statt deine Policy zu lockern. Sieh dir wie Caputchin Spiele sandboxt an.
Stolperfallen
- Zwei Keys, zwei Heimaten. Der Public Key (
cpt_pub_...) kommt auf die Seite; das Secret (cpt_sec_...) bleibt nur serverseitig, genau die Turnstile-Disziplin. Liefer das Secret nicht an den Browser. - Das Token ist einmalig. Wie Turnstile verifiziert ein Token einmal. Cache oder spiel es nicht ab.
- Änder den Feldnamen, den dein Backend liest. Das versteckte Feld ist
caputchin-token, nichtcf-turnstile-response, ein häufiger Ein-Zeilen-Fehler. - Kein
action/cdata. Verzweigtest du auf diese, verschieb diese Logik anderswohin; Caputchin trägt sie nicht.
Siehe auch
- Das Widget hinzufügen: die vollständige Client-Einrichtung.
- Ein Token auf deinem Backend verifizieren: die maßgebliche
siteverify-Referenz. - Backend-Beispiele: der Verifizierungs-Aufruf in jeder Sprache.
- Ein Spiel hinzufügen: die Verifizierung in ein Spiel verwandeln.