Protezione anti-spam

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
• Nozioni di base sui terminali
• Configurazione locale Web
• Messaggi dell'agente e memoria del progetto

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
• Differenze motore di autenticazione

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.