turnstile

README

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

Documentation

Index

• Constants
• Variables
• type Client
  • func New(secret string, opts ...Option) *Client
  • func (c *Client) Verify(ctx context.Context, token string, params ...VerifyParams) (*Result, error)
• type Option
  • func WithEndpoint(endpoint string) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithTimeout(timeout time.Duration) Option
• type Result
  • func Verify(ctx context.Context, secret, token string, params ...VerifyParams) (*Result, error)
• type VerifyParams

Constants

const (
	// DefaultEndpoint is Cloudflare Turnstile's siteverify endpoint.
	DefaultEndpoint = "https://challenges.cloudflare.com/turnstile/v0/siteverify"

	// DefaultTimeout is the default HTTP request timeout.
	DefaultTimeout = 5 * time.Second
)

Variables

var (
	// ErrMissingSecret is returned when the secret key is empty.
	ErrMissingSecret = errors.New("turnstile: secret key is required")

	// ErrMissingToken is returned when the response token is empty.
	ErrMissingToken = errors.New("turnstile: response token is required")

	// ErrTokenTooLarge is returned when the response token exceeds 2048 bytes.
	ErrTokenTooLarge = errors.New("turnstile: token is too large")

	// ErrInvalidStatus is returned when Cloudflare returns a non-200 HTTP status code.
	ErrInvalidStatus = errors.New("turnstile: verification returned non-200 status")
)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client verifies Cloudflare Turnstile tokens.

func New

func New(secret string, opts ...Option) *Client

New creates a new Turnstile verification client.

func (*Client) Verify

func (c *Client) Verify(ctx context.Context, token string, params ...VerifyParams) (*Result, error)

Verify validates a token against Cloudflare Turnstile.

type Option

type Option func(*Client)

Option configures the Turnstile Client.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint sets a custom verification endpoint.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom http.Client.

func WithTimeout

func WithTimeout(timeout time.Duration) Option

WithTimeout configures the default HTTP client timeout.

type Result

type Result struct {
	Success     bool      `json:"success"`
	ChallengeTS time.Time `json:"challenge_ts"`
	Hostname    string    `json:"hostname"`
	ErrorCodes  []string  `json:"error-codes"`
	Action      string    `json:"action"`
	CData       string    `json:"cdata"`
}

Result represents the verification response from Cloudflare Turnstile.

func Verify

func Verify(ctx context.Context, secret, token string, params ...VerifyParams) (*Result, error)

Verify validates a Turnstile token using a new default client.

type VerifyParams

type VerifyParams struct {
	RemoteIP       string
	IdempotencyKey string
}

VerifyParams contains optional verification arguments.