recaptcha

README

go-recaptcha

About

This package handles reCAPTCHA (API versions 2 and 3) form submissions in Go.

Usage

Import the package:

import "github.com/tekkamanendless/go-recaptcha"

Create a new reCAPTCHA verifier.

recaptchaVerifier := recaptcha.New("YOUR_PRIVATE_KEY")

Verify a token.

success, err := recaptchaVerifier.Verify("SOME_RECAPTCHA_RESPONSE_TOKEN")

Or verify with a client IP address, too:

success, err := recaptchaVerifier.VerifyRemoteIP(clientIpAddress, "SOME_RECAPTCHA_RESPONSE_TOKEN")

This workflow supports both reCAPTCHA v2 and reCAPTCHA v3.

Testing

You may use the included recaptchatest package to create a reCAPTCHA server suitable for unit testing.

import "github.com/tekkamanendless/go-recaptcha/recaptchatest"

// Create a new reCAPTCHA test server.
testServer := recaptchatest.NewServer()
defer testServer.Close()

// Create a new site.
site := testServer.NewSite()

// Create your reCAPTCHA verifier normally.
recaptchaVerifier := recaptcha.New(site.PrivateKey)

// Override the endpoint.
recaptchaVerifier.VerifyEndpoint = testServer.VerifyEndpoint()

// Generate a response token from the site.
token := site.NewResponseToken()

// Verify the token normally.
success, err := recaptchaVerifier.Verify(token)

Documentation

Overview

Package recaptcha handles reCAPTCHA (http://www.google.com/recaptcha) form submissions

This package is designed to be called from within an HTTP server or web framework which offers reCAPTCHA form inputs and requires them to be evaluated for correctness

Index

• Constants
• type Recaptcha
  • func New(privateKey string) *Recaptcha
  • func (r *Recaptcha) Verify(response string) (bool, error)
  • func (r *Recaptcha) VerifyRemoteIP(remoteIP, response string) (bool, error)
• type RecaptchaResponse

Constants

const DefaultVerifyEndpoint = "https://www.google.com/recaptcha/api/siteverify"

DefaultVerifyEndpoint is the default production endpoint for verifying a token.

Types

type Recaptcha

type Recaptcha struct {
	VerifyEndpoint string // This is the endpoint; if empty, it will default to the production endpoint.
	PrivateKey     string // This is your site's private key.
	// contains filtered or unexported fields
}

Recaptcha contains the configuration and functions necessary to perform reCAPTCHA validations.

func New

func New(privateKey string) *Recaptcha

New creates a new Recaptcha instance that can verify reCAPTCHA tokens.

func (*Recaptcha) Verify

func (r *Recaptcha) Verify(response string) (bool, error)

Verify a response token.

func (*Recaptcha) VerifyRemoteIP

func (r *Recaptcha) VerifyRemoteIP(remoteIP, response string) (bool, error)

VerifyRemoteIP verify a response token along with the IP address.

type RecaptchaResponse

type RecaptchaResponse struct {
	Success     bool      `json:"success"`      // Whether this request was a valid reCAPTCHA token for your site.
	Score       float64   `json:"score"`        // (v3 only) The score for this request (0.0 - 1.0).
	Action      string    `json:"action"`       // (v3 only) The action name for this request (important to verify).
	ChallengeTS time.Time `json:"challenge_ts"` // Timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ).
	Hostname    string    `json:"hostname"`     // The hostname of the site where the reCAPTCHA was solved.
	ErrorCodes  []string  `json:"error-codes"`  // (Optional)
}

RecaptchaResponse is the response that we get back from the "siteverify" endpoint.