captcha

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package captcha verifies that a form was filled in by a person. The provider is a runtime setting (hot reload): the built-in image captcha (no third-party service, works in mainland China), Cloudflare Turnstile, Google reCAPTCHA (via recaptcha.net, reachable from China) or hCaptcha.

Index

Constants

View Source
const (
	None      = "none"
	Image     = "image"
	Turnstile = "turnstile"
	ReCAPTCHA = "recaptcha"
	HCaptcha  = "hcaptcha"
)

Providers.

Variables

View Source
var (
	// ErrInvalid means the answer is wrong, expired or already used.
	ErrInvalid = errors.New("captcha answer is wrong or expired")
	// ErrUnavailable means the third-party service could not be asked. Forms fail
	// closed: no captcha check, no registration.
	ErrUnavailable = errors.New("captcha service unavailable")
)

Functions

func SettingDefs

func SettingDefs() []settings.Def

SettingDefs are the captcha settings. Site keys are public (the widget needs them); secret keys never leave the server.

Types

type Answer

type Answer struct {
	ID    string `json:"id,omitempty" doc:"Image captcha challenge id"`
	Value string `json:"value" maxLength:"4096" doc:"Typed text (image captcha) or the widget token"`
}

Answer is what the browser sends: for the image captcha the challenge id and the typed text, for widget providers only the token in Value.

type Config

type Config struct {
	Provider  string
	SiteKey   string // public, given to the browser widget
	SecretKey string // server side only
}

Config is the active provider and its keys (from settings).

func ConfigFrom

func ConfigFrom(s *settings.Snapshot) Config

ConfigFrom reads the active provider and its keys from a settings snapshot.

func (Config) Enabled

func (c Config) Enabled() bool

Enabled reports whether forms must carry a captcha.

type CustomVerifier added in v1.1.0

type CustomVerifier func(ctx context.Context, a Answer, remoteIP string) error

CustomVerifier verifies a widget/challenge answer for a plugin-provided provider.

type Options

type Options struct {
	HTTPClient *http.Client
	// Endpoints overrides siteverify URLs per provider (tests, self-hosted proxies).
	Endpoints map[string]string
	Log       *slog.Logger
}

Options configure a Service; the zero value is fine.

type Service

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

Service issues image challenges and verifies answers for every provider.

func NewService

func NewService(o Options) *Service

NewService creates a Service.

func (*Service) CustomProviders added in v1.1.0

func (s *Service) CustomProviders() []any

CustomProviders returns sorted IDs of currently registered plugin CAPTCHA providers.

func (*Service) NewImage

func (s *Service) NewImage() (id string, png []byte, err error)

NewImage creates an image challenge. The answer stays on the server.

func (*Service) RegisterProvider added in v1.1.0

func (s *Service) RegisterProvider(owner, id string, fn CustomVerifier) error

RegisterProvider registers a plugin CAPTCHA verification provider owned by owner.

func (*Service) UnregisterProviders added in v1.1.0

func (s *Service) UnregisterProviders(owner string)

UnregisterProviders removes every custom CAPTCHA provider owned by owner.

func (*Service) Verify

func (s *Service) Verify(ctx context.Context, c Config, a Answer, remoteIP string) error

Verify checks an answer against the configured provider. With the provider off it always succeeds.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL