turnstile-go

Go client for verifying Cloudflare Turnstile CAPTCHA tokens.

Features

• Standard library only (net/http, encoding/json).
• Rejects tokens over 2048 bytes and caps response reads at 64 KB.
• Returns challenge timestamp, hostname, error codes, action, and client data (cdata).
• Supports custom HTTP clients, timeouts, and idempotency keys.

Installation

go get github.com/fumbledlol/turnstile-go

Usage

Simple verification

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/fumbledlol/turnstile-go"
)

func main() {
	secretKey := "0x4AAAAAA..."
	token := "0.xxxxxxx..."

	res, err := turnstile.Verify(context.Background(), secretKey, token, turnstile.VerifyParams{
		RemoteIP: "198.51.100.1",
	})
	if err != nil {
		log.Fatalf("Verification error: %v", err)
	}

	if res.Success {
		fmt.Printf("Accepted: host=%s action=%s\n", res.Hostname, res.Action)
	} else {
		fmt.Printf("Rejected: codes=%v\n", res.ErrorCodes)
	}
}

Reusable client

For servers handling frequent checks, create a client once:

client := turnstile.New(secretKey,
    turnstile.WithTimeout(3 * time.Second),
    turnstile.WithHTTPClient(httpClient),
)

res, err := client.Verify(ctx, token, turnstile.VerifyParams{
    RemoteIP:       r.RemoteAddr,
    IdempotencyKey: requestID,
})

License

MIT