recaptcha

README

recaptcha

The purpose of this package is to provide a simple interface to the Google reCAPTCHA V3 service for verifying requests server side in Golang.

Basic usage

For complete examples, please see the examples directory.

import "github.com/MicahParks/recaptcha"

Step 1: Create the verifier

// Create the verifier.
verifier := recaptcha.NewVerifierV3("mySecret", recaptcha.VerifierV3Options{})

Step 2: Verify the request with Google

// Verify the request with Google.
response, err := verifier.Verify(ctx, frontendToken, remoteAddr)
if err != nil {
    // Handle the error.
}

Step 3: Check the response

// Check the reCAPTCHA response.
err = response.Check(recaptcha.V3ResponseCheckOptions{
    Action:   []string{"submit"},
    Hostname: []string{"example.com"},
    Score:    0.5,
})
if err != nil {
    // Fail the request.
}

Test coverage

Test coverage is currently >90%.

References

• reCAPTCHA V3 docs
• reCAPTCHA V3 server side docs

Documentation

Overview

Package recaptcha implements server side validation of reCAPTCHA V3 responses.

See the below linked documentation for more information: https://developers.google.com/recaptcha/docs/v3 https://developers.google.com/recaptcha/docs/verify

Index

• Variables
• type V3Response
  • func (resp V3Response) Check(options V3ResponseCheckOptions) error
• type V3ResponseCheckOptions
• type VerifierV3
  • func NewTestVerifierV3(response V3Response, err error) VerifierV3
  • func NewVerifierV3(secret string, options VerifierV3Options) VerifierV3
• type VerifierV3Options

Variables

var (
	// ErrCheck indicates that the reCAPTCHA response failed a check.
	ErrCheck = errors.New("reCAPTCHA check failed")

	// ErrInvalidVerifyInputs indicates that the reCAPTCHA V3 verify inputs are invalid.
	ErrInvalidVerifyInputs = errors.New("reCAPTCHA V3 verify inputs are invalid")
)

Types

type V3Response

type V3Response struct {
	APKPackageName string    `json:"apk_package_name"`
	Action         string    `json:"action"`
	ChallengeTS    time.Time `json:"challenge_ts"`
	ErrorCodes     []string  `json:"error-codes"`
	Hostname       string    `json:"hostname"`
	Score          float64   `json:"score"`
	Success        bool      `json:"success"`
}

V3Response is the response from Google's reCAPTCHA V3 API.

func (V3Response) Check

func (resp V3Response) Check(options V3ResponseCheckOptions) error

Check confirms the reCAPATCHA V3 response is valid and meets the given requirements.

type V3ResponseCheckOptions

type V3ResponseCheckOptions struct {
	// APKPackageName confirms the response's APK package name is in the given slice.
	APKPackageName []string
	// Action confirms the response's action is in the given slice.
	Action []string
	// Hostname confirms the response's hostname is in the given slice.
	Hostname []string
	// Score confirms the response's score is at least this value.
	Score float64
}

V3ResponseCheckOptions are the options for checking a reCAPTCHA V3 response.

type VerifierV3

type VerifierV3 interface {
	Verify(ctx context.Context, response string, remoteIP string) (V3Response, error)
}

VerifierV3 is the interface for verifying reCAPTCHA V3 responses.

func NewTestVerifierV3

func NewTestVerifierV3(response V3Response, err error) VerifierV3

NewTestVerifierV3 creates a new reCAPTCHA V3 verifier that returns the given response and error. The intended purpose is for testing.

func NewVerifierV3

func NewVerifierV3(secret string, options VerifierV3Options) VerifierV3

NewVerifierV3 creates a new reCAPTCHA V3 verifier.

type VerifierV3Options

type VerifierV3Options struct {
	HTTPClient *http.Client
	VerifyURL  string
}

VerifierV3Options are the options for creating a new reCAPTCHA V3 verifier. All fields can safely be left blank.