Cloudflare Turnstile

Cloudflare Turnstile to przyjazna dla prywatności alternatywa dla CAPTCHA, która zwykle weryfikuje odwiedzających bez żadnych zagadek. Frontmail używa jej, żeby boty nie mogły nadużywać twojego klucza publicznego.

Gdy szablon ma włączone Wymagaj CAPTCHA (Turnstile), każde żądanie z kluczem publicznym do tego szablonu musi zawierać ważny token Turnstile. W przeciwnym razie kończy się błędem captcha_required lub captcha_failed, zanim zużyje kredyt. Żądania z kluczem prywatnym (z twojego serwera) nigdy nie potrzebują CAPTCHA.

Jak to działa

Gdzie działa formularz	Czyje klucze Turnstile	Co robisz
Twoja strona	Twoje – darmowy widget na twoim własnym koncie Cloudflare	Tworzysz widget, wklejasz oba klucze w Bezpieczeństwo → Ochrona przed botami (Turnstile) i umieszczasz site key w formularzu.
Aplikacja mobilna (`@frontmail/react-native`)	Wspólny mobilny klucz Frontmail	Nic – `<TurnstileWebView>` sam pobiera klucz.

Dlaczego na stronach własne klucze

Darmowy plan Turnstile pozwala na 10 nazw hostów (hostnames) na widget i 20 widgetów na konto; widget działający na dowolnej domenie Cloudflare oferuje tylko w planie Enterprise. Jeden klucz Frontmail nie obsłużyłby więc stron wszystkich klientów. Własny widget jest darmowy, konfiguracja zajmuje około dwóch minut i działa tylko na domenach, które w nim podasz – nikt więc nie użyje twojej CAPTCHA na innej stronie.

Zaloguj się do panelu Cloudflare (wystarczy darmowe konto – twoja domena nie musi korzystać z Cloudflare).
Otwórz Turnstile i kliknij Add widget.
Nadaj mu nazwę, np. Formularz kontaktowy.
Dodaj wszystkie domeny, na których działa formularz, np. example.com i www.example.com. localhost dodaj tylko wtedy, gdy chcesz lokalnie testować z prawdziwymi kluczami – do lokalnego developmentu lepiej nadają się klucze testowe.
Widget mode: wystarczy Managed (Cloudflare pokazuje pole wyboru tylko wtedy, gdy nie jest pewien).
Kliknij Create i skopiuj Site Key (klucz witryny) oraz Secret Key (klucz tajny).

2. Dodaj klucze do Frontmail

W panelu Frontmail otwórz Bezpieczeństwo i znajdź kartę Ochrona przed botami (Turnstile).
Wklej site key i secret key, a następnie kliknij Zapisz klucze.
Frontmail od razu sprawdza secret key w Cloudflare – błędny klucz zostanie odrzucony z czytelnym komunikatem. Klucz tajny jest przechowywany w postaci zaszyfrowanej i nigdy więcej nie jest wyświetlany. Klucze możesz w każdej chwili zmienić przyciskiem Zastąp klucze albo usunąć przyciskiem Usuń klucze.
Po zapisaniu kliknij Włącz CAPTCHA we wszystkich szablonach, żeby włączyć CAPTCHA we wszystkich istniejących szablonach za jednym razem. Szablony używane jako automatyczna odpowiedź są pomijane – wysyła je Frontmail, a nie twój formularz.

Od tej chwili nowe szablony mają CAPTCHA włączoną domyślnie. Szablony utworzone przed dodaniem kluczy mają ją wyłączoną – użyj przycisku powyżej albo włącz ją w poszczególnych szablonach w edytorze, w Ustawienia → Ochrona.

Bez kluczy edytor szablonu nie pozwoli włączyć CAPTCHA i odeśle cię na stronę Bezpieczeństwo. Wyjątkiem jest włączone Zezwól na aplikacje mobilne: wtedy możesz ją włączyć (z ostrzeżeniem), bo aplikacje mobilne korzystają ze wspólnego klucza Frontmail – żądania ze stron do takiego szablonu będą jednak kończyć się błędem captcha_not_configured, dopóki nie dodasz kluczy.

Użyj swojego site key (jest publiczny – secret key nigdy nie opuszcza Frontmail). Zakładka Kod w edytorze szablonu zawiera już widget z twoim site key, jeśli szablon wymaga CAPTCHA.

Ze zwykłym HTML i sendForm – wyrenderuj widget wewnątrz formularza. Turnstile dodaje ukryte pole cf-turnstile-response, które sendForm wysyła automatycznie:

<form id="contact">
  <!-- twoje pola -->
  <div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_SITE_KEY"></div>
  <button>Wyślij</button>
</form>

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

Z komponentami dla frameworków – przekaż site key do FrontmailForm, a komponent załaduje Turnstile, wyrenderuje widget, wyśle token i zresetuje widget za ciebie:

React i Svelte: <FrontmailForm turnstileSiteKey="YOUR_TURNSTILE_SITE_KEY" …>
Vue: <FrontmailForm turnstile-site-key="YOUR_TURNSTILE_SITE_KEY" …>

Z send() – wyrenderuj widget samodzielnie i przekaż token w opcjach:

await send('svc_01J9…', 'tpl_contact', params, { turnstileToken: token });

Przez REST API przekaż turnstile_token w treści JSON albo cf-turnstile-response w formularzach multipart.

Jak Frontmail weryfikuje token

Żądania ze stron niosą nagłówek Origin (lub Referer). Frontmail weryfikuje ich token twoim secret key i dodatkowo sprawdza, czy Cloudflare rozwiązał widget na tej samej domenie, z której przyszło żądanie. Token z innej domeny kończy się błędem captcha_failed (details.reason: "hostname_mismatch") – dlatego podaj w widgecie wszystkie domeny swojej strony.

Aplikacje mobilne

@frontmail/react-native nie potrzebuje site key. Komponent <TurnstileWebView> pobiera mobilny site key Frontmail z GET /v1/public-config (z cache) i wyświetla widget jako osadzoną stronę pod adresem https://mobile.frontmail.dev. Żądania natywne nie mają nagłówka Origin. Włącz Zezwól na aplikacje mobilne – bez tego takie żądania są odrzucane jeszcze przed sprawdzeniem CAPTCHA (także wtedy, gdy nie ustawiono żadnych dozwolonych domen). Dopiero wtedy Frontmail weryfikuje je swoim wspólnym mobilnym kluczem tajnym; w organizacji, która nie zezwoliła na aplikacje mobilne, CAPTCHA nigdy nie jest sprawdzana względem wspólnego, publicznie dostępnego widgetu.

Własny klucz w aplikacji

Własnego widgetu możesz użyć także w aplikacji: przekaż do <TurnstileWebView> siteKey oraz baseUrl, którego domena jest wpisana w twoim widgecie (np. https://example.com). SDK automatycznie oznaczy wtedy żądanie turnstile_key: "org", a Frontmail zweryfikuje je twoim secret key.

Inni klienci natywni (Flutter, Swift, Kotlin…), którzy wywołują REST API bezpośrednio, mogą zrobić to samo: wyrenderować twój widget w WebView i wysłać turnstile_key: "org" razem z turnstile_token.

Lokalny development

Cloudflare publikuje klucze testowe, które działają offline i na dowolnej domenie:

Klucz	Wartość	Wynik
Site key	`1x00000000000000000000AA`	Zawsze przechodzi
Secret key	`1x0000000000000000000000000000000AA`	Zawsze przechodzi
Secret key	`2x0000000000000000000000000000000AA`	Zawsze kończy się błędem

Frontmail przyjmuje je w Bezpieczeństwo → Ochrona przed botami (Turnstile) w środowiskach deweloperskich.

W testach automatycznych możesz też wysyłać z kluczem prywatnym – żądania z nim pomijają to sprawdzenie.

Tokeny

Token jest ważny około 5 minut i można go użyć tylko raz.
Po każdej wysyłce (udanej lub nie) zresetuj widget (turnstile.reset()) przed kolejną próbą. Komponenty dla frameworków robią to automatycznie.
Ponowne próby SDK dla tej samej logicznej wysyłki używają tego samego klucza idempotencji. Na ponowione żądanie, które zostało już przyjęte, Frontmail odpowiada wynikiem pierwszej próby jeszcze przed sprawdzeniem Turnstile, więc zużyty token nie powoduje błędu ponowienia.

Błędy

Kod	Status	Kiedy	Rozwiązanie
`captcha_required`	403	Szablon wymaga CAPTCHA, a żądanie nie ma tokenu.	Dodaj widget do formularza albo przekaż `turnstileToken`.
`captcha_failed`	403	Cloudflare odrzucił token – jest nieprawidłowy, wygasł, został już użyty albo rozwiązano go na innej domenie (`hostname_mismatch`).	Zresetuj widget i spróbuj ponownie; dodaj do widgetu wszystkie swoje domeny.
`captcha_not_configured`	403	Żądanie ze strony do szablonu z włączoną CAPTCHA, ale organizacja nie ma kluczy Turnstile (albo na produkcji ma tylko testowe klucze Cloudflare).	Dodaj klucze prawdziwego widgetu w Bezpieczeństwo → Ochrona przed botami (Turnstile).

Wyłączanie

Wymagaj CAPTCHA (Turnstile) możesz wyłączyć w poszczególnych szablonach w edytorze szablonu, w Ustawienia → Ochrona – na przykład w szablonach wysyłanych tylko z twojego serwera. W publicznych formularzach zdecydowanie zalecamy zostawić ją włączoną.