Documentation
¶
Overview ¶
Package captcha defines the pluggable CAPTCHA-verification provider interface and its in-tree implementations (Cloudflare Turnstile and Google reCAPTCHA v3) plus a no-op verifier for deployments that leave CAPTCHA disabled.
The interface is intentionally narrow: a deployment swaps providers via config without the handler layer knowing which backend is in use. The handler passes the client-submitted token and the resolved client IP; the verifier decides pass/fail (reCAPTCHA additionally applies a score threshold internally).
Index ¶
Constants ¶
const ( ProviderTurnstile = "turnstile" ProviderRecaptchaV3 = "recaptcha_v3" )
Provider names select the implementation built from config. They are the accepted values of GATEWAY_CAPTCHA_PROVIDER.
Variables ¶
ErrProviderUnavailable indicates the verifier could not reach the upstream siteverify endpoint or got an unusable response (network failure, non-200 status, malformed body). Distinct from ErrVerificationFailed so the handler can choose to surface a retryable error rather than a hard rejection.
var ErrVerificationFailed = errors.New("captcha: verification failed")
ErrVerificationFailed indicates the token was rejected by the provider (siteverify returned success=false, the reCAPTCHA score fell below the configured threshold, or the response was otherwise not a pass). The handler maps this to a permission-denied error so a client cannot distinguish a forged token from a genuine challenge failure.
Functions ¶
This section is empty.
Types ¶
type NoopVerifier ¶
type NoopVerifier struct{}
NoopVerifier is the disabled-CAPTCHA implementation: it accepts every token (including the empty one). It is wired when CAPTCHA is disabled or no provider is configured, so the handler can always call Verify without a nil check.
type RecaptchaConfig ¶
type RecaptchaConfig struct {
Secret string
ScoreThreshold float64
HTTPClient *http.Client // optional override for tests
VerifyURL string // optional override for tests; defaults to recaptchaVerifyURL
}
RecaptchaConfig configures a RecaptchaV3Verifier. Secret is the reCAPTCHA secret key. ScoreThreshold is the inclusive lower bound a response score must meet to pass (reCAPTCHA v3 returns a 0.0–1.0 risk score; lower is more likely a bot).
type RecaptchaV3Verifier ¶
type RecaptchaV3Verifier struct {
// contains filtered or unexported fields
}
RecaptchaV3Verifier implements Verifier against Google reCAPTCHA v3.
API reference:
POST https://www.google.com/recaptcha/api/siteverify
form: secret, response, [remoteip]
resp: { success, score, action, error-codes }
func NewRecaptchaV3Verifier ¶
func NewRecaptchaV3Verifier(cfg RecaptchaConfig) (*RecaptchaV3Verifier, error)
NewRecaptchaV3Verifier returns a RecaptchaV3Verifier. Secret is required and ScoreThreshold must be in [0,1]; the HTTP client and verify URL fall back to sensible defaults.
func (*RecaptchaV3Verifier) Name ¶
func (v *RecaptchaV3Verifier) Name() string
Name implements Verifier.
type TurnstileConfig ¶
type TurnstileConfig struct {
Secret string
HTTPClient *http.Client // optional override for tests
VerifyURL string // optional override for tests; defaults to turnstileVerifyURL
}
TurnstileConfig configures a TurnstileVerifier. Secret is the Cloudflare Turnstile secret key; everything else is optional.
type TurnstileVerifier ¶
type TurnstileVerifier struct {
// contains filtered or unexported fields
}
TurnstileVerifier implements Verifier against Cloudflare Turnstile.
API reference:
POST https://challenges.cloudflare.com/turnstile/v0/siteverify form: secret, response, [remoteip]
func NewTurnstileVerifier ¶
func NewTurnstileVerifier(cfg TurnstileConfig) (*TurnstileVerifier, error)
NewTurnstileVerifier returns a TurnstileVerifier. Secret is required; the HTTP client and verify URL fall back to sensible defaults.
func (*TurnstileVerifier) Name ¶
func (v *TurnstileVerifier) Name() string
Name implements Verifier.
type Verifier ¶
type Verifier interface {
// Name returns the provider identifier (e.g. "turnstile",
// "recaptcha_v3", "noop").
Name() string
// Verify checks token, optionally binding it to remoteip (the
// resolved client IP; empty omits the binding). It returns nil when
// the token is valid, ErrVerificationFailed when the provider rejects
// it, and ErrProviderUnavailable when the check could not be
// completed.
Verify(ctx context.Context, token, remoteip string) error
}
Verifier validates a client-submitted CAPTCHA token. The service holds exactly one Verifier for the lifetime of the process.
Source Files