For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /de/docs/web/captcha.md (or send Accept: text/markdown).

Spam-Schutz

Per Env geschaltete Turnstile-Prüfungen auf öffentlichen Formularen und Auth-Endpunkten.

Zu dieser Anleitung fragen

Schritt-für-Schritt für Einsteiger

Voraussetzungen: Lesen Sie die beiden folgenden Einsteigerhandbücher, schließen Sie die lokale Web-Einrichtung ab und öffnen Sie dieses Monorepo im Stammverzeichnis in Ihrem Editor. Webeinstellungen gehören in apps/web/.env.local; Next.js liest das Stammverzeichnis .env nicht. /dashboard im Standard-Fake-Modus ist eine Demo ohne Datenbank; /auth benötigt eine migrierte Datenbank.

Kurze Begriffe: Ein Arbeitsbereich umfasst die einzelnen Benutzer, Daten und Einstellungen eines Teams. Der Server ist das vertrauenswürdige Backend; Halten Sie Anbieterschlüssel aus Browser- und Telefoncodes fern. Eine Migration ist eine versionierte Datenbankänderung, die Tabellen erstellt oder aktualisiert. Ein KI-Modell ist der Motor, der antwortet; Der Modellkatalog ist die Liste der verfügbaren Modell-IDs und Preise des Servers. Ein Anbieter ist ein externer Dienst wie ein KI-, E-Mail- oder Abrechnungsdienst. Eine Berechtigung ist eine Bewilligung, die einem Arbeitsbereich die Nutzung einer Funktion ermöglicht. Ein Webhook ist eine Nachricht, die ein Dienst an den URL eines anderen Dienstes sendet.

1. Erstellen Sie ein Turnstile-Test-Widget für den genauen lokalen/bereitgestellten Hostnamen. Legen Sie in apps/web/.env.local CAPTCHA_PROVIDER=turnstile und NEXT_PUBLIC_TURNSTILE_SITE_KEY fest. Legen Sie TURNSTILE_SECRET_KEY nur im geheimen Serverspeicher ab.

2. Starten Sie neu und senden Sie ein Testkontaktformular.

3. Erwarten Sie die Herausforderung und eine erfolgreiche Antwort mit einem gültigen Token. Wenn jede Anfrage fehlschlägt, vergleichen Sie Hostname und Schlüsselpaar. Geben Sie niemals den geheimen Schlüssel preis.

Beginnen Sie für benutzerdefinierten Code mit dem bereitgestellten prompts/README.md und kopieren Sie die nächstgelegene Eingabeaufforderung: prompts/new-app-screen.md für einen App-Bildschirm oder prompts/new-landing-page.md für eine öffentliche Seite. Geben Sie Ihrem Programmieragenten für Server-, Datenbank- oder Anbieterarbeiten die Aufgabe dieses Handbuchs und bitten Sie ihn, AGENTS.md, .ai/PROJECT_CONTEXT.md und passende .ai/-Spiegel zu lesen; Überprüfen Sie die hier genannten genauen Quelldateien. Listen Sie Dateien auf und prüfen Sie sie vor der Bearbeitung. Bewahren Sie den Arbeitsbereichseigentum und die Nur-Server-Geheimnisse. und zeige dir den Unterschied. Teilen Sie ihm das gewünschte Verhalten, Eingabe- und Ausgabefelder, zulässige Rollen, erwartete Erfolge und Fehler sowie das Testkonto, den Anbieter oder das Gerät mit. Beispielwerte verwenden; Fügen Sie niemals ein echtes Geheimnis ein.

Beide Schlüssel aktivieren

CAPTCHA_PROVIDER=off ist der Standard. Wähle turnstile, richte den passenden Hostnamen in deiner Turnstile-Anwendung ein und hinterlege beide Schlüssel. NEXT_PUBLIC_TURNSTILE_SITE_KEY ist öffentlich; TURNSTILE_SECRET_KEY wird nur vom serverseitigen Prüfer verwendet.

CAPTCHA_PROVIDER=turnstile
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key
# TURNSTILE_SECRET_KEY belongs in the server secret store.

Geschützte Oberflächen beibehalten

Das Gate deckt Kontakt- und Newsletter-Formulare sowie Better-Auth-Endpunkte für Anmeldung, Registrierung, OTP und Passwortzurücksetzung ab. Es ergänzt Validierung und Rate Limits; es ersetzt weder Sitzungen noch Workspace-Autorisierung.

Ablehnung und Wiederherstellung prüfen

Teste ein gültiges Token, ein fehlendes, abgelaufenes oder ungültiges Token, einen Fehler des Prüfdienstes und einen erneuten Versuch nach dem Zurücksetzen des Client-Widgets. Sorge für verständlichen Text zur menschlichen Prüfung und Tastaturbedienung. Untersuche vor einem Wechsel des Authentifizierungsanbieters, welche Oberflächen dessen Engine abdeckt.

Einrichtung und Konfiguration

CAPTCHA_PROVIDER wählt den Verifier: off (die Vorgabe, damit lokale Entwicklung ohne Credentials bleibt) oder turnstile. Das Aktivieren von turnstile erfordert TURNSTILE_SECRET_KEY auf dem Server und NEXT_PUBLIC_TURNSTILE_SITE_KEY für das Client-Widget — das Config-Schema lässt den Start fehlschlagen, wenn eines davon fehlt.

apps/web/src/captcha.ts komponiert einen prozessweiten Verifier, der das Token mit einem Zehn-Sekunden-Timeout an Cloudflares siteverify-Endpunkt postet und geschlossen fehlschlägt — ein unverifizierbares Token gilt nie als Nachweis von Menschlichkeit.

CAPTCHA_PROVIDER=turnstile
TURNSTILE_SECRET_KEY=…           # server-only
NEXT_PUBLIC_TURNSTILE_SITE_KEY=…

Guarded: sign-in/up, OTP send, reset,
contact + newsletter forms

Implementierungsablauf

CaptchaWidget (src/captcha-widget.tsx) rendert das Widget und injiziert das Feld cf-turnstile-response in das Elternformular, während Auth-Client-Calls das Token im Header x-captcha-response tragen. Die Kontakt- und Newsletter-Actions verifizieren vor dem Schreiben — eine fehlgeschlagene Prüfung liefert status=captcha statt einen Lead anzulegen.

packages/auth mountet das captcha-Plugin von better-auth, wenn der Provider aktiv ist; CAPTCHA_ENDPOINTS deckt die Credential-Eingabe- und Token-ausstellenden Routen ab — Sign-in, Sign-up, OTP-Versand, Passwort-Reset. Konsumierende Endpunkte wie check-verification-otp bleiben ungelistet: Dort ist das OTP oder Token selbst der Nachweis.

Überprüfung und Fehlerbehebung

Sende jedes geschützte Formular mit fehlendem und mit malformedem Token — beide müssen geschlossen fehlschlagen. Verifiziere, dass ein unerreichbarer siteverify ablehnt statt durchzulassen, provider=off die lokale Entwicklung offen lässt und das Secret nie in Client-Bundles oder Logs landet.