> ## Documentation Index > Fetch the complete documentation index at: https://supastack.dev/llms.txt > Use this file to discover all available pages before exploring further. > For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt # Protezione anti-spam Controlli Turnstile attivabili da env su form pubblici ed endpoint di auth. ## Procedura dettagliata per principianti Prerequisiti: leggi le due guide per principianti di seguito, completa la configurazione locale del Web e apri questo monorepo alla radice nel tuo editor. Le impostazioni Web appartengono a `apps/web/.env.local`; Next.js non legge la radice `.env`. `/dashboard` nella modalità falsa predefinita è una demo senza database; `/auth` necessita di un database migrato. Termini rapidi: uno spazio di lavoro è costituito da utenti, dati e impostazioni separati di un team. Il server è il backend affidabile; mantenere le chiavi del provider fuori dal browser e dal codice del telefono. Una migrazione è una modifica del database con versione che crea o aggiorna tabelle. Un modello AI è il motore che risponde; il catalogo dei modelli è l'elenco del server degli ID e dei prezzi dei modelli disponibili. Un fornitore è un servizio esterno come un servizio di intelligenza artificiale, posta elettronica o fatturazione. Un diritto è una concessione che consente a un'area di lavoro di utilizzare una funzionalità. Un webhook è un messaggio che un servizio invia allo URL di un altro servizio. 1. Creare un widget di test del tornello per l'esatto nome host locale/distribuito. In `apps/web/.env.local`, impostare `CAPTCHA_PROVIDER=turnstile` e `NEXT_PUBLIC_TURNSTILE_SITE_KEY`; inserire `TURNSTILE_SECRET_KEY` solo nell'archivio segreto del server. 2. Riavvia e invia un modulo di contatto di prova. 3. Aspettatevi la sfida e una risposta positiva con token valido. Se ogni richiesta fallisce, confronta il nome host e la coppia di chiavi; non esporre mai la chiave segreta. Per il codice personalizzato, inizia con `prompts/README.md` in dotazione e copia il prompt più vicino: `prompts/new-app-screen.md` per la schermata di un'app o `prompts/new-landing-page.md` per una pagina pubblica. Per il lavoro su server, database o provider, assegna al tuo agente di codifica il compito di questa guida e chiedigli di leggere `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` e i mirror `.ai/` corrispondenti; controllare gli esatti file sorgente nominati qui; elencare file e controlli prima della modifica; preservare la proprietà dello spazio di lavoro e i segreti solo del server; e mostrarti la differenza. Indicagli il comportamento desiderato, i campi di input e output, i ruoli consentiti, i successi e gli errori previsti e l'account, il fornitore o il dispositivo di prova. Utilizzare valori campione; non incollare mai un vero segreto. [Prima di iniziare](https://supastack.dev/it/docs/web/before-you-start.md) [Nozioni di base sui terminali](https://supastack.dev/it/docs/web/terminal-basics.md) [Configurazione locale Web](https://supastack.dev/it/docs/web/ship-in-5-minutes.md) [Messaggi dell'agente e memoria del progetto](https://supastack.dev/it/docs/web/agents.md) ## Abilita entrambi i tasti `CAPTCHA_PROVIDER=off` è l'impostazione predefinita. Seleziona `turnstile`, configura il nome host corrispondente nella tua applicazione Turnstile e fornisci entrambe le chiavi. `NEXT_PUBLIC_TURNSTILE_SITE_KEY` è pubblico; `TURNSTILE_SECRET_KEY` viene utilizzato solo dal verificatore del server. ``` CAPTCHA_PROVIDER=turnstile NEXT_PUBLIC_TURNSTILE_SITE_KEY=your-site-key # TURNSTILE_SECRET_KEY belongs in the server secret store. ``` ## Preservare le superfici protette Il cancello copre i moduli di contatto/newsletter e gli endpoint delle credenziali Better Auth di accesso, registrazione, OTP e reimpostazione della password. Integra la convalida/limitazione della velocità; non sostituisce le sessioni o l'autorizzazione dell'area di lavoro. ## Verificare il rifiuto e il recupero Testare un token valido, un token mancante/scaduto/non valido, un errore del verificatore e un nuovo tentativo dopo la reimpostazione del widget client. Mantieni la copia e l'accesso tramite tastiera utilizzabili tramite controllo umano; controllare la copertura del motore di autenticazione scelto prima di cambiare fornitore. [Moduli protetti](https://supastack.dev/it/docs/web/project-structure.md) [Differenze motore di autenticazione](https://supastack.dev/it/docs/web/project-structure.md) ## Installazione e configurazione CAPTCHA_PROVIDER seleziona il verificatore: off (il default, così lo sviluppo locale resta senza credenziali) o turnstile. Attivare turnstile richiede TURNSTILE_SECRET_KEY sul server e NEXT_PUBLIC_TURNSTILE_SITE_KEY per il widget client — lo schema di config fa fallire l'avvio se ne manca una. apps/web/src/captcha.ts compone un verificatore unico per processo che invia il token all'endpoint siteverify di Cloudflare con un timeout di dieci secondi e fallisce in modo chiuso — un token non verificabile non vale mai come prova di umanità. ``` CAPTCHA_PROVIDER=turnstile TURNSTILE_SECRET_KEY=… # server-only NEXT_PUBLIC_TURNSTILE_SITE_KEY=… Guarded: sign-in/up, OTP send, reset, contact + newsletter forms ``` ## Flusso di implementazione CaptchaWidget (src/captcha-widget.tsx) renderizza il widget e inietta il campo cf-turnstile-response nel form genitore, mentre le chiamate del client auth portano il token nell'header x-captcha-response. Le action di contatto e newsletter verificano prima di scrivere — un controllo fallito restituisce status=captcha invece di creare un lead. packages/auth monta il plugin captcha di better-auth quando il provider è attivo; CAPTCHA_ENDPOINTS copre le rotte di inserimento credenziali ed emissione di token — sign-in, sign-up, invio OTP, reset della password. Gli endpoint consumatori come check-verification-otp restano fuori lista: lì l'OTP o il token stesso è la prova. ## Verifica e risoluzione dei problemi Invia ogni form protetto con token assente e con uno malformato — entrambi devono fallire in modo chiuso. Verifica che un siteverify irraggiungibile rifiuti invece di lasciar passare, che provider=off lasci aperto lo sviluppo locale e che il segreto non arrivi mai ai bundle client o ai log. ## Successivo [Console di amministrazione](https://supastack.dev/it/docs/web/admin.md)