Cloudflare Turnstile

Cloudflare Turnstile è un’alternativa ai CAPTCHA rispettosa della privacy che di solito verifica i visitatori senza alcun rompicapo. Frontmail lo usa per impedire ai bot di abusare della tua chiave pubblica.

Quando un modello ha Richiedi CAPTCHA (Turnstile) attivo, ogni richiesta con chiave pubblica per quel modello deve includere un token Turnstile valido, altrimenti fallisce con captcha_required o captcha_failed prima di costarti un credito. Le richieste con chiave privata (dal tuo server) non richiedono mai un CAPTCHA.

Come funziona

Dove gira il modulo	Chiavi Turnstile di chi	Cosa devi fare
Il tuo sito web	Tue – un widget gratuito nel tuo account Cloudflare	Crea il widget, incolla entrambe le chiavi in Sicurezza → Protezione dai bot (Turnstile), inserisci la chiave del sito nel modulo.
App mobile (`@frontmail/react-native`)	La chiave mobile condivisa di Frontmail	Niente – `<TurnstileWebView>` carica la chiave da solo.

Perché chiavi proprie per i siti web

Il piano gratuito di Turnstile consente 10 nomi host per widget e 20 widget per account; un widget che funziona su qualsiasi nome host è disponibile solo con il piano Enterprise di Cloudflare. Un’unica chiave di Frontmail non può quindi coprire i siti di tutti i nostri clienti. Il tuo widget è gratuito, si configura in circa due minuti e funziona solo sui nomi host che indichi – così nessuno può riutilizzare il tuo CAPTCHA su un altro sito.

Accedi alla dashboard di Cloudflare (basta un account gratuito – il tuo dominio non deve usare Cloudflare).
Apri Turnstile e fai clic su Add widget.
Dagli un nome, ad es. Modulo di contatto.
Aggiungi tutti i nomi host su cui gira il modulo, ad es. example.com e www.example.com. Aggiungi localhost solo se vuoi fare test in locale con chiavi reali – per lo sviluppo locale puoi usare invece le chiavi di test.
Widget mode: va bene Managed (Cloudflare mostra una casella di controllo solo quando ha dei dubbi).
Fai clic su Create e copia la Site Key e la Secret Key.

2. Aggiungi le chiavi a Frontmail

Nella dashboard di Frontmail apri Sicurezza e trova la scheda Protezione dai bot (Turnstile).
Incolla la chiave del sito e la chiave segreta e fai clic su Salva chiavi.
Frontmail verifica subito la chiave segreta con Cloudflare – una chiave errata viene rifiutata con un messaggio chiaro. La chiave segreta viene salvata cifrata e non viene mai più mostrata. Puoi cambiare le chiavi in qualsiasi momento con Sostituisci chiavi o eliminarle con Rimuovi chiavi.
Dopo il salvataggio, fai clic su Attiva il CAPTCHA per tutti i modelli per attivare il CAPTCHA su tutti i modelli esistenti in un colpo solo. I modelli usati come risposta automatica vengono saltati: li invia Frontmail, non il tuo modulo.

Da questo momento i nuovi modelli hanno il CAPTCHA attivo per impostazione predefinita. I modelli creati prima di aggiungere le chiavi partono con il CAPTCHA disattivato: usa il pulsante qui sopra oppure attivalo per ogni modello nell’editor, in Impostazioni → Protezione.

Senza chiavi, l’editor dei modelli non ti permette di attivare il CAPTCHA e ti rimanda alla pagina Sicurezza. L’eccezione è Consenti app mobile: in quel caso puoi attivarlo (con un avviso), perché le app mobile usano la chiave condivisa di Frontmail – le richieste dai siti web verso quel modello falliscono con captcha_not_configured finché non aggiungi le tue chiavi.

Usa la tua chiave del sito (è pubblica – la chiave segreta non lascia mai Frontmail). La scheda Snippet dell’editor dei modelli contiene già il widget con la tua chiave del sito quando il modello richiede il CAPTCHA.

Con HTML semplice e sendForm – mostra il widget dentro il modulo. Turnstile aggiunge un campo nascosto cf-turnstile-response, che sendForm invia automaticamente:

<form id="contact">
  <!-- i tuoi campi -->
  <div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_SITE_KEY"></div>
  <button>Invia</button>
</form>

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

Con i componenti per i framework – passa la chiave del sito a FrontmailForm: caricherà Turnstile, mostrerà il widget, invierà il token e reimposterà il widget al posto tuo:

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

Con send() – mostra tu il widget e passa il token nelle opzioni:

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

Con l’API REST, passa turnstile_token nel body JSON oppure cf-turnstile-response nei moduli multipart.

Come Frontmail verifica il token

Le richieste da un sito web portano un header Origin (o Referer). Frontmail verifica il loro token con la tua chiave segreta e controlla anche che Cloudflare abbia risolto il widget sullo stesso nome host da cui è arrivata la richiesta. Un token proveniente da un altro nome host fallisce con captcha_failed (details.reason: "hostname_mismatch") – quindi elenca nel widget tutti i nomi host del tuo sito.

App mobile

@frontmail/react-native non richiede alcuna chiave del sito. Il suo <TurnstileWebView> recupera la chiave del sito mobile di Frontmail da GET /v1/public-config (con cache) e mostra il widget come pagina inline con l’URL https://mobile.frontmail.dev. Le richieste native non hanno l’header Origin. Attiva Consenti app mobile: senza, queste richieste vengono rifiutate prima del controllo CAPTCHA (anche quando non è impostato alcun sito consentito). Solo allora Frontmail le verifica con la sua chiave segreta mobile condivisa; un’organizzazione che non ha consentito le app mobile non vede mai il proprio CAPTCHA verificato con il widget condiviso e pubblicamente disponibile.

La tua chiave nell’app

Puoi usare il tuo widget anche nell’app: passa a <TurnstileWebView> siteKey e un baseUrl il cui nome host è elencato nel tuo widget (ad es. https://example.com). L’SDK contrassegna allora automaticamente la richiesta con turnstile_key: "org" e Frontmail la verifica con la tua chiave segreta.

Gli altri client nativi (Flutter, Swift, Kotlin…) che chiamano direttamente l’API REST possono fare lo stesso: mostrare il tuo widget in una WebView e inviare turnstile_key: "org" insieme a turnstile_token.

Sviluppo locale

Cloudflare pubblica delle chiavi di test che funzionano offline, su qualsiasi nome host:

Chiave	Valore	Risultato
Chiave del sito	`1x00000000000000000000AA`	Passa sempre
Chiave segreta	`1x0000000000000000000000000000000AA`	Passa sempre
Chiave segreta	`2x0000000000000000000000000000000AA`	Fallisce sempre

Frontmail le accetta in Sicurezza → Protezione dai bot (Turnstile) negli ambienti di sviluppo.

Nei test automatici puoi anche inviare con una chiave privata – le richieste con chiave privata saltano il controllo.

Token

Un token è valido per circa 5 minuti e può essere usato una sola volta.
Dopo ogni invio (riuscito o no), reimposta il widget (turnstile.reset()) prima del tentativo successivo. I componenti per i framework lo fanno automaticamente.
I tentativi ripetuti dall’SDK per lo stesso invio logico riutilizzano la stessa chiave di idempotenza. A una richiesta ripetuta che era già stata accettata si risponde con il risultato del primo tentativo prima del controllo Turnstile, quindi un token già usato non fa fallire il nuovo tentativo.

Errori

Codice	Stato	Quando	Soluzione
`captcha_required`	403	Il modello richiede il CAPTCHA e la richiesta non ha un token.	Aggiungi il widget al modulo o passa `turnstileToken`.
`captcha_failed`	403	Cloudflare ha rifiutato il token – non valido, scaduto, già usato o risolto su un altro nome host (`hostname_mismatch`).	Reimposta il widget e riprova; aggiungi al widget tutti i tuoi nomi host.
`captcha_not_configured`	403	Una richiesta da un sito web per un modello con il CAPTCHA attivo, ma la tua organizzazione non ha chiavi Turnstile (oppure, in produzione, solo chiavi di test di Cloudflare).	Aggiungi le chiavi di un widget reale in Sicurezza → Protezione dai bot (Turnstile).

Disattivazione

Puoi disattivare Richiedi CAPTCHA (Turnstile) per singolo modello nell’editor dei modelli, in Impostazioni → Protezione – per esempio per i modelli inviati solo dal tuo server. Per i moduli pubblici ti consigliamo vivamente di tenerlo attivo.