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
- Variables
- func SettingDefs() []settings.Def
- type Answer
- type Config
- type CustomVerifier
- type Options
- type Service
- func (s *Service) CustomProviders() []any
- func (s *Service) NewImage() (id string, png []byte, err error)
- func (s *Service) RegisterProvider(owner, id string, fn CustomVerifier) error
- func (s *Service) UnregisterProviders(owner string)
- func (s *Service) Verify(ctx context.Context, c Config, a Answer, remoteIP string) error
Constants ¶
const ( None = "none" Image = "image" Turnstile = "turnstile" ReCAPTCHA = "recaptcha" HCaptcha = "hcaptcha" )
Providers.
Variables ¶
var ( // ErrInvalid means the answer is wrong, expired or already used. ErrInvalid = errors.New("captcha answer is wrong or expired") // closed: no captcha check, no registration. ErrUnavailable = errors.New("captcha service unavailable") )
Functions ¶
func SettingDefs ¶
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 ¶
ConfigFrom reads the active provider and its keys from a settings snapshot.
type CustomVerifier ¶ added in v1.1.0
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 (*Service) CustomProviders ¶ added in v1.1.0
CustomProviders returns sorted IDs of currently registered plugin CAPTCHA providers.
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
UnregisterProviders removes every custom CAPTCHA provider owned by owner.