Cloudflare Turnstile

Cloudflare Turnstile je alternatíva ku CAPTCHA, ktorá šetrí súkromie a návštevníkov zvyčajne overí bez akejkoľvek hádanky. Frontmail ho používa, aby boty nemohli zneužívať váš verejný kľúč.

Keď má šablóna zapnuté Vyžadovať CAPTCHA (Turnstile), musí každá požiadavka s verejným kľúčom na ňu obsahovať platný token Turnstile. Inak skončí chybou captcha_required alebo captcha_failed skôr, ako vás bude stáť kredit. Požiadavky so súkromným kľúčom (z vášho servera) CAPTCHA nepotrebujú nikdy.

Ako to funguje

Kde formulár beží	Čie kľúče Turnstile	Čo urobíte
Váš web	Vaše – bezplatný widget vo vašom vlastnom účte Cloudflare	Vytvoríte widget, oba kľúče vložíte do Zabezpečenie → Ochrana pred botmi (Turnstile) a site key dáte do formulára.
Mobilná aplikácia (@frontmail/react-native)	Zdieľaný mobilný kľúč Frontmailu	Nič – <TurnstileWebView> si kľúč načíta sám.

Prečo pre weby vlastné kľúče

Bezplatný tarif Turnstile povoľuje 10 hostiteľov (hostnames) na widget a 20 widgetov na účet; widget, ktorý funguje na ľubovoľnej doméne, ponúka Cloudflare len v tarife Enterprise. Jeden kľúč Frontmailu by teda weby všetkých zákazníkov nepokryl. Vlastný widget je zadarmo, nastavíte ho približne za dve minúty a funguje len na doménach, ktoré v ňom uvediete – vašu CAPTCHA tak nikto nepoužije na cudzom webe.

1. Vytvorte widget Turnstile v Cloudflare

1. Prihláste sa do dashboardu Cloudflare (stačí bezplatný účet – vaša doména nemusí používať Cloudflare).
2. Otvorte Turnstile a kliknite na Add widget.
3. Pomenujte ho, napr. Kontaktný formulár.
4. Pridajte všetky domény, na ktorých formulár beží, napr. example.com a www.example.com. localhost pridajte len vtedy, keď chcete lokálne skúšať so skutočnými kľúčmi – na lokálny vývoj sa hodia skôr testovacie kľúče.
5. Widget mode: stačí Managed (začiarkavacie políčko Cloudflare ukáže, len keď si nie je istý).
6. Kliknite na Create a skopírujte Site Key (kľúč webu) a Secret Key (tajný kľúč).

2. Vložte kľúče do Frontmailu

1. V dashboarde Frontmailu otvorte Zabezpečenie a nájdite kartu Ochrana pred botmi (Turnstile).
2. Vložte site key a secret key a kliknite na Uložiť kľúče.
3. Frontmail secret key hneď overí u Cloudflare – nesprávny kľúč odmietne so zrozumiteľnou správou. Uloží ho šifrovane a už ho nikdy nezobrazí. Kľúče môžete kedykoľvek zmeniť tlačidlom Nahradiť kľúče alebo zmazať tlačidlom Odstrániť kľúče.
4. Po uložení kliknite na Zapnúť CAPTCHA pre všetky šablóny a CAPTCHA sa zapne pri všetkých existujúcich šablónach naraz. Šablóny použité ako automatická odpoveď sa preskočia – tie odosiela Frontmail, nie váš formulár.

Nové šablóny potom majú CAPTCHA zapnutú automaticky. Šablóny vytvorené skôr, než ste kľúče pridali, ju majú vypnutú – zapnite ju tlačidlom vyššie alebo pri jednotlivých šablónach v editore v Nastavenia → Ochrana.

Bez kľúčov vám editor šablóny CAPTCHA zapnúť nedovolí a odkáže vás na stránku Zabezpečenie. Výnimkou je zapnuté Povoliť mobilné aplikácie: vtedy ju zapnúť možno (s upozornením), pretože mobilné aplikácie používajú zdieľaný kľúč Frontmailu – požiadavky z webov na takú šablónu však budú končiť chybou captcha_not_configured, kým kľúče nepridáte.

3. Pridajte widget do formulára

Použite svoj site key (je verejný – secret key Frontmail nikdy nevydá). Karta Kód v editore šablóny už widget s vaším site key obsahuje, ak šablóna CAPTCHA vyžaduje.

S čistým HTML a sendForm – vykreslite widget vnútri formulára. Turnstile pridá skryté pole cf-turnstile-response, ktoré sendForm odošle automaticky:

<form id="contact">
  <!-- vaše polia -->
  <div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_SITE_KEY"></div>
  <button>Odoslať</button>
</form>

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

S komponentmi pre frameworky – odovzdajte site key komponentu FrontmailForm a ten načíta Turnstile, vykreslí widget, odošle token a widget po odoslaní resetuje:

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

So send() – widget vykreslite sami a token odovzdajte v options:

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

Cez REST API odovzdajte turnstile_token v JSON tele alebo cf-turnstile-response v multipart formulároch.

Ako Frontmail token overuje

Požiadavky z webu nesú hlavičku Origin (alebo Referer). Frontmail ich token overí vaším secret key a navyše skontroluje, že Cloudflare widget vyriešil na tej istej doméne, z ktorej požiadavka prišla. Token z inej domény skončí chybou captcha_failed (details.reason: "hostname_mismatch") – preto vo widgete uveďte všetky domény svojho webu.

Mobilné aplikácie

@frontmail/react-native žiadny site key nepotrebuje. Komponent <TurnstileWebView> si mobilný site key Frontmailu načíta z GET /v1/public-config (s cache) a widget zobrazí ako vloženú stránku s adresou https://mobile.frontmail.dev. Natívne požiadavky nemajú hlavičku Origin. Zapnite Povoliť mobilné aplikácie – bez toho sa také požiadavky odmietnu ešte pred kontrolou CAPTCHA (aj keď nemáte nastavené žiadne povolené weby). Až potom ich Frontmail overí svojím zdieľaným mobilným tajným kľúčom; pri organizácii, ktorá mobilné aplikácie nepovolila, sa CAPTCHA voči zdieľanému, verejne dostupnému widgetu nikdy neoveruje.

Vlastný kľúč v aplikácii

Vlastný widget môžete použiť aj v aplikácii: odovzdajte komponentu <TurnstileWebView> siteKey a baseUrl, ktorého doména je vo vašom widgete uvedená (napr. https://example.com). SDK potom požiadavku automaticky označí turnstile_key: "org" a Frontmail ju overí vaším secret key.

Iní natívni klienti (Flutter, Swift, Kotlin…), ktorí volajú REST API priamo, to môžu urobiť rovnako: vykreslia váš widget vo WebView a spolu s turnstile_token pošlú turnstile_key: "org".

Lokálny vývoj

Cloudflare zverejňuje testovacie kľúče, ktoré fungujú offline a na akejkoľvek doméne:

Kľúč	Hodnota	Výsledok
Site key	1x00000000000000000000AA	Vždy prejde
Secret key	1x0000000000000000000000000000000AA	Vždy prejde
Secret key	2x0000000000000000000000000000000AA	Vždy zlyhá

Frontmail ich v Zabezpečenie → Ochrana pred botmi (Turnstile) prijme vo vývojových prostrediach.

V produkcii testovacie kľúče odmietame

Testovacie kľúče pustia každú požiadavku – ochranu tým vypnete. Produkčná služba ich preto neuloží (400, details.reason: "test_keys") a šablóna organizácie, ktorá má testovací secret stále uložený, končí chybou captcha_not_configured (details.reason: "test_secret"), kým nepridáte kľúče skutočného widgetu.

V automatizovaných testoch môžete tiež odosielať so súkromným kľúčom – požiadavky s ním kontrolu preskakujú.

Tokeny

• Token platí približne 5 minút a možno ho použiť len raz.
• Po každom odoslaní (úspešnom aj neúspešnom) widget pred ďalším pokusom resetujte (turnstile.reset()). Komponenty pre frameworky to robia automaticky.
• Opakované pokusy SDK o to isté logické odoslanie používajú rovnaký idempotency key. Na opakovanú požiadavku, ktorá už bola prijatá, Frontmail odpovie výsledkom prvého pokusu ešte pred kontrolou Turnstile, takže použitý token opakovanie nezhodí.

Chyby

Kód	Status	Kedy	Riešenie
captcha_required	403	Šablóna vyžaduje CAPTCHA a požiadavka nemá token.	Pridajte widget do formulára alebo odovzdajte turnstileToken.
captcha_failed	403	Cloudflare token odmietol – je neplatný, vypršal, už bol použitý alebo bol vyriešený na inej doméne (hostname_mismatch).	Resetujte widget a skúste to znova; do widgetu pridajte všetky svoje domény.
captcha_not_configured	403	Požiadavka z webu na šablónu so zapnutou CAPTCHA, ale organizácia nemá kľúče Turnstile (v produkcii ani iné než testovacie kľúče Cloudflare).	Pridajte kľúče skutočného widgetu v Zabezpečenie → Ochrana pred botmi (Turnstile).

Vypnutie

Vyžadovať CAPTCHA (Turnstile) môžete vypnúť pri jednotlivých šablónach v editore šablóny v Nastavenia → Ochrana – napríklad pri šablónach, ktoré sa odosielajú len z vášho servera. Pri verejných formulároch dôrazne odporúčame nechať ju zapnutú.

V dashboarde

Kľúče nájdete v Nastaveniach zabezpečenia, nastavenia šablóny opisuje Editor šablón.