Come scegliere un'API per i CAPTCHA: dalle directory dei tipi ai cicli di verifica sui tuoi sistemi

Nell'integrazione dei CAPTCHA, l'errore di valutazione più pericoloso raramente è scegliere il nome sbagliato: è scambiare «aver ottenuto un risultato» per «verifica superata». Un client che riceve un token non vuoto, un servizio di verifica che accetta quel token e la tua logica di business che consente l'operazione sono tre eventi distinti. Verificare solo il primo espone i form al rifiuto da parte del backend; trattare il primo direttamente come il terzo rischia di aggirare i controlli interni sui permessi.

Questa guida riguarda lo sviluppo e il test su sistemi di tua proprietà: come identificare i prodotti di challenge, leggere i parametri attuali e il formato di risposta dei tipi di EveryInfra, isolare le configurazioni di test e verificare che i sistemi si fermino nello stato corretto in caso di errore. Valgono anche gli ambienti di test ufficiali e gli ambiti di test esplicitamente autorizzati. Questo articolo non fornisce procedure per operare su account, pagamenti, permessi o challenge di rischio reali di terze parti.

Stabilisci prima cosa testare

Se l'obiettivo è solo confermare che il tuo form salvi i dati dopo una convalida riuscita e blocchi le scritture in caso di errore, privilegia i meccanismi di test ufficiali forniti dal prodotto di challenge. Producono esiti controllabili senza trasformare ogni esecuzione della CI nella risoluzione di una challenge reale. Introdurre un'altra API in questa fase non aggiunge valore ai test e crea solo un'ulteriore dipendenza che richiede un'accettazione autonoma.

Se devi valutare le funzionalità di risoluzione dei CAPTCHA di EveryInfra, dividi il test in due domande indipendenti: se input e output dell'API corrispondono alla forma concordata e se i valori restituiti vengono gestiti correttamente negli ambienti autorizzati. Tieni separate le prove dei due aspetti, senza far valere il successo dell'uno per l'altro. Il punto di partenza della scelta è il compito di test, non il numero di tipi elencati in una directory.

Identifica i prodotti dalla configurazione dell'integrazione, non dall'aspetto

Conferma prodotti, modalità, domini e casi d'uso tramite il codice di integrazione, le configurazioni del backend e la documentazione ufficiale corrispondente alle tue pagine. Una casella di controllo visibile non basta a determinare il tipo di richiesta, e le diverse modalità di uno stesso prodotto non vanno scambiate arbitrariamente. Tieni un registro chiaro dei test: chi possiede la pagina, cosa è consentito testare, quali configurazioni di test si usano e quali sono gli esiti attesi.

Per gli ambienti autorizzati che non gestisci tu, i parametri devono essere forniti da chi gestisce l'ambiente o ricavati dalla documentazione autorizzata. Quando manca il contesto, fermati e chiedi conferma a chi gestisce l'ambiente; non lasciare mai che i programmi indovinino tipi simili o inventino campi. Vedere un identificatore pubblico su una pagina non autorizza azioni automatizzate arbitrarie.

Per esempio, la configurazione hostname di Turnstile accetta nomi di dominio senza protocollo, porta o percorso, e configurare un dominio padre copre anche i suoi sottodomini. Negli ambienti di test gli ambiti devono essere verificati da chi li gestisce, invece di allentare la configurazione per far passare un indirizzo errato; questo è diverso dal campo website_url nelle richieste.

Leggi tipi, disponibilità, parametri e forma dei risultati

Di seguito trovi una lettura gratuita e non autenticata della directory che non crea alcun task di risoluzione. L'esempio seleziona solo due tipi per confrontarne parametri e formati di risposta, non per imporre operazioni su entrambe le challenge. Servono curl e jq; se la lettura della directory fallisce, risolvi prima la fase di discovery e non procedere con le richieste di business usando output vuoti.

set -o pipefail
curl -fsS --max-time 30 'https://api.everyinfra.com/api/v1/captcha/types' \
  | jq -e '[.types[] |
      select(.type == "turnstile" or .type == "recaptcha_grid") |
      {type, available, required_params, optional_params, solution}
    ] | if length == 2 then . else error("expected types missing") end'

In questa osservazione pubblica del 2026/9/4, i parametri obbligatori per turnstile erano website_url e website_key, mentre tra quelli facoltativi c'erano action, cdata e page_data; solution.shape era token e il campo era token. I parametri obbligatori per recaptcha_grid erano body e question, con shape pari a points e campo objects. In quel momento entrambi erano disponibili. Si tratta di una dichiarazione della directory, non di una prova di successo su una challenge reale.

Per questo i gestori dei risultati dovrebbero diramarsi in base al tipo verificato e al formato di solution, invece di prendere sempre i token di primo livello o convertire in stringa oggetti arbitrari. I parametri presenti in optional_params indicano solo che il catalogo li dichiara facoltativi; il successo di una combinazione dipende dagli errori attuali e dalla disponibilità, e non va forzato eliminando vincoli di business essenziali.

Salva il timestamp dell'osservazione insieme alle voci selezionate. Non inviare nulla quando available è false; tratta campi mancanti, tipi errati o errori di lettura come stato sconosciuto e fermati. Anche quando il valore è true, la disponibilità indica solo che durante l'osservazione era possibile provare la funzionalità, senza garantire il successo dei task successivi.

Isola i meccanismi di test ufficiali dalle configurazioni di produzione

Cloudflare Turnstile fornisce sitekey e secret di test per simulare token validi, non validi o già consumati. Token o chiavi di test e di produzione non vanno mai mescolati. Le FAQ di Google reCAPTCHA descrivono chiavi di test separate per v2 e configurazioni di test per v3; i punteggi v3 nell'ambiente di test non vanno considerati indicativi del rischio con traffico reale.

Le sitekey sono identificatori pubblici usati dalle pagine, mentre i secret sono chiavi di convalida del backend. Le configurazioni di test devono essere lette da impostazioni d'ambiente esplicite, senza passare a un comportamento «passa sempre» solo perché una richiesta dichiara di essere un test. All'avvio in produzione controlla l'origine della configurazione e la coerenza dell'ambiente; nei log conserva solo gli stati di audit necessari, senza scrivere secret, token completi o oggetti di richiesta grezzi.

Nel codice di business, metti i servizi di convalida dietro un'interfaccia ristretta: la logica di business riceve risultati di verifica espliciti, mentre i test possono iniettare risultati sintetici. La vera convalida esterna resta implementata lato server. I meccanismi di iniezione devono essere controllati esclusivamente da build di test o configurazioni del server, mai esposti come parametri di richiesta selezionabili dall'utente. Questa è una raccomandazione di design applicativo, non una funzione automatica fornita da EveryInfra.

Gestire separatamente l'accettazione dei token, la verifica lato server e la logica di business

Turnstile richiede ufficialmente chiamate lato server a Siteverify; i soli componenti frontend non costituiscono una protezione completa. La documentazione ufficiale specifica che i token sono validi per cinque minuti e possono essere verificati una sola volta. Non trattare mai i token come credenziali da mettere in cache a lungo o da riutilizzare, e non affidarti a infiniti nuovi tentativi con lo stesso valore per rimediare agli errori di rete.

Anche quando la convalida lato server riesce, la logica di business deve comunque eseguire controlli di sessione, permessi sulle risorse, convalida degli input e controlli contro gli invii duplicati. I CAPTCHA non sono né credenziali dell'account né autorizzazioni a transazioni. Quando i passaggi successivi falliscono, conserva gli errori di business invece di rinominarli «errori del CAPTCHA» generando un numero illimitato di nuovi task.

I dettagli della verifica non si possono copiare da un prodotto all'altro. La documentazione di Google reCAPTCHA sulla convalida backend specifica che i token sono monouso e validi per due minuti, oltre a indicare errori come timeout-or-duplicate, a differenza della finestra di cinque minuti di Turnstile. La gestione degli errori deve essere legata ai prodotti specifici e alle risposte di convalida effettive.

Controlla le condizioni di accettazione del backend con esempi offline

Di seguito trovi un controllo dei risultati per una pagina di test di tua proprietà. La pagina configura esplicitamente hostname come localhost e action come test; i valori attesi provengono da configurazioni fisse del server, non dalle richieste degli utenti. Nelle integrazioni reali, i risultati in arrivo devono essere ottenuti dal tuo server chiamando gli endpoint di verifica ufficiali: non fidarti mai ciecamente di un successo inviato dai client.

function acceptOwnTestVerification(result, expected) {
  if (!expected || typeof expected.hostname !== "string" ||
      !expected.hostname.trim() || typeof expected.action !== "string" ||
      !expected.action.trim()) {
    throw new Error("server-side test configuration required");
  }
  if (!result || typeof result !== "object" || Array.isArray(result)) {
    return { accepted: false, reason: "invalid_response" };
  }
  if (result.success !== true) {
    return { accepted: false, reason: "verification_failed" };
  }
  if (result.hostname !== expected.hostname) {
    return { accepted: false, reason: "hostname_mismatch" };
  }
  if (result.action !== expected.action) {
    return { accepted: false, reason: "action_mismatch" };
  }
  return { accepted: true, reason: "verification_only" };
}

// all values are self-made test fixtures; no network requests, no tokens held or generated.
const expected = { hostname: "localhost", action: "test" };
const synthetic = { success: true, hostname: "localhost", action: "test" };
console.log(acceptOwnTestVerification(synthetic, expected));
// { accepted: true, reason: 'verification_only' }

Questo esempio restituisce verification_only: non emette token, non chiama Siteverify e non invia form. Il controllo impone action perché questa configurazione di test lo richiede esplicitamente; non dare per scontato che tutti i prodotti di challenge restituiscano gli stessi campi. Implementa separatamente le regole di convalida di ogni prodotto invece di riutilizzare una funzione generica con controlli allentati.

Testa singolarmente il successo, il falso successo, i valori di successo in formato stringa, gli errori di dominio, le azioni mancanti, le risposte vuote e le configurazioni server mancanti. Poi verifica l'intero percorso dalla pagina al tuo backend nelle integrazioni di test autorizzate. Superare le funzioni offline dimostra solo la correttezza di quelle valutazioni dei rami, non la verifica di rete, le configurazioni di produzione né l'efficacia nell'individuare i rischi.

Decidi i passi successivi in base a dove si verifica l'errore

• Fase di input: tipi non corrispondenti, valori obbligatori mancanti o combinazioni di parametri non supportate. Correggi prima i parametri; non ripetere in loop richieste identiche.
• Fase della funzionalità: directory sconosciuta o al momento non disponibile. Interrompi i test e registra le osservazioni senza passare arbitrariamente a un altro prodotto per la challenge.
• Fase di chiamata: registra separatamente errori espliciti e timeout. Un risultato non ricevuto non significa che il server non abbia eseguito la richiesta; conserva prima gli identificatori di correlazione della richiesta.
• Fase di validazione: il tuo backend rifiuta i risultati. Registra classificazioni degli errori sicure e i casi di test corrispondenti, e controlla ambienti, domini e azioni invece di allentare i criteri di accettazione.
• Fase di business: la verifica va a buon fine ma si verificano comunque rifiuti dovuti a input, permessi o invii duplicati. Gestiscili con i flussi di business senza fingere che il CAPTCHA non sia stato risolto.

Anche i costi vanno riconciliati su questi livelli. L'implementazione attuale di EveryInfra prevede rami contabili di rimborso dopo una risoluzione non riuscita, ma un errore di verifica lato client o un rifiuto di business non equivale a un errore di risoluzione stabilito dal gateway. Non dedurre rimborsi o ripristini delle riserve solo da un testo rosso nel frontend; riconcilia le richieste identiche usando le risposte alle chiamate e i registri di fatturazione accessibili. Questo articolo non introduce nuovi esempi di recupero del saldo per errori reali, né promette che tutti i rifiuti successivi modifichino gli stati contabili.

Lascia registrazioni dei test verificabili

Un registro di accettazione utile riporta: ambienti autorizzati, modalità del prodotto, timestamp delle osservazioni, categorie di configurazione dei test, strutture dell'input, strutture della risposta, valutazioni di validazione, valutazioni di business e valutazioni di fatturazione. Ometti il contenuto reale ove possibile e usa ID di correlazione mascherati per collegare i risultati dei vari livelli. Documenta esplicitamente le aree non coperte, così i team futuri non scambieranno “directory lette correttamente” per un'accettazione completa.

Verifica i tuoi flussi di successo e di errore con i meccanismi di test ufficiali, valuta i rami API necessari e solo dopo estendi la verifica entro gli ambiti autorizzati. Il criterio per scegliere il tipo di CAPTCHA non è la somiglianza del nome né una risposta con un valore, ma condizioni di input chiare, forme di ritorno interpretabili, valutazioni corrette nel backend e una gestione degli errori che resti nei limiti del business.