Documentation
¶
Index ¶
- Constants
- Variables
- func DefaultIPExtractor(r *http.Request) string
- type Config
- type IPExtractorFunc
- type Option
- func WithAllowedHostnames(hostnames []string) Option
- func WithEndpoints(endpoints []string) Option
- func WithExemptEndpoints(exempt []string) Option
- func WithExpectedAction(action string) Option
- func WithHTTPClient(client *http.Client) Option
- func WithIPExtractor(fn IPExtractorFunc) Option
- func WithMinScore(score float64) Option
- func WithProvider(p Provider) Option
- func WithSecretKey(key string) Option
- func WithSiteKey(key string) Option
- func WithSiteVerifyURLOverride(urlStr string) Option
- func WithTimeout(d time.Duration) Option
- type Plugin
- func (p *Plugin) Config() Config
- func (p *Plugin) ID() string
- func (p *Plugin) Init(ctx *plugin.Context) error
- func (p *Plugin) IsProtectedPath(path string) bool
- func (p *Plugin) Protect() func(next http.Handler) http.Handler
- func (p *Plugin) VerifyToken(ctx context.Context, token string, remoteIP string) error
- type Provider
- type Verifier
Constants ¶
const DefaultMinScore = 0.5
DefaultMinScore defines the default minimum passing score for Google reCAPTCHA v3.
const DefaultVerifyTimeout = 10 * time.Second
DefaultVerifyTimeout specifies the maximum duration allowed for outgoing verification requests.
const HeaderCaptchaResponse = "x-captcha-response"
HeaderCaptchaResponse is the standard HTTP header used by client applications to submit the captcha token.
const PluginID = "captcha"
PluginID is the unique string identifier for the Captcha plugin ("captcha").
Variables ¶
var ( // ErrMissingSecretKey is returned when the SecretKey option is not configured. ErrMissingSecretKey = errors.New("captcha: missing secret key") // ErrMissingCaptchaResponse is returned when incoming request lacks the x-captcha-response header. ErrMissingCaptchaResponse = errors.New("captcha: missing captcha response header") // ErrVerificationFailed is returned when the captcha provider rejects the token. ErrVerificationFailed = errors.New("captcha: verification failed") ErrServiceUnavailable = errors.New("captcha: service unavailable or timeout") // ErrInvalidProvider is returned when an unsupported captcha provider is specified. ErrInvalidProvider = errors.New("captcha: unsupported captcha provider") // ErrScoreTooLow is returned when reCAPTCHA v3 score is lower than MinScore threshold. ErrScoreTooLow = errors.New("captcha: recaptcha score below required minimum") // ErrActionMismatch is returned when returned captcha action does not match ExpectedAction. ErrActionMismatch = errors.New("captcha: action does not match expected action") // ErrHostnameMismatch is returned when returned captcha hostname is not in AllowedHostnames. ErrHostnameMismatch = errors.New("captcha: hostname not in allowed list") )
var DefaultEndpoints = []string{
"/sign-up/email",
"/sign-in/email",
"/request-password-reset",
}
DefaultEndpoints lists the default authentication endpoints protected by captcha verification.
var DefaultExemptEndpoints = []string{
"/sign-in/email-otp",
}
DefaultExemptEndpoints lists endpoints that are exempted from captcha verification.
var DefaultSiteVerifyURLs = map[Provider]string{
ProviderCloudflareTurnstile: "https://challenges.cloudflare.com/turnstile/v0/siteverify",
ProviderGoogleRecaptcha: "https://www.google.com/recaptcha/api/siteverify",
ProviderHCaptcha: "https://api.hcaptcha.com/siteverify",
ProviderCaptchaFox: "https://api.captchafox.com/siteverify",
}
DefaultSiteVerifyURLs maps each captcha provider to its official verification endpoint URL.
Functions ¶
func DefaultIPExtractor ¶
DefaultIPExtractor extracts remote client IP address from request headers or RemoteAddr.
Types ¶
type Config ¶
type Config struct {
// Provider specifies the active captcha provider (Turnstile, reCAPTCHA, hCaptcha, CaptchaFox).
Provider Provider
// SecretKey is the private secret key obtained from the captcha provider dashboard.
SecretKey string
// SiteKey is the public site key (required by hCaptcha and CaptchaFox verification endpoints).
SiteKey string
// Endpoints defines the list of HTTP request path URIs protected by captcha verification.
Endpoints []string
// ExemptEndpoints defines paths explicitly exempted from captcha verification.
ExemptEndpoints []string
// SiteVerifyURLOverride allows overriding the official provider siteverify URL (useful for testing or enterprise endpoints).
SiteVerifyURLOverride string
// MinScore sets minimum score threshold for Google reCAPTCHA v3 (default: 0.5).
MinScore float64
// ExpectedAction validates expected action parameter for Turnstile or reCAPTCHA v3 responses.
ExpectedAction string
// AllowedHostnames restricts valid captcha tokens to specified hostnames/domains.
AllowedHostnames []string
// HTTPClient allows injecting custom *http.Client for outgoing verification requests.
HTTPClient *http.Client
// Timeout specifies maximum duration allowed for outgoing verification HTTP call (default: 10s).
Timeout time.Duration
// IPExtractor function to extract remote IP address from incoming requests.
IPExtractor IPExtractorFunc
}
Config structures all operational settings for the Captcha plugin.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns default operational configuration for the Captcha plugin.
type IPExtractorFunc ¶
IPExtractorFunc extracts the client's remote IP address from an incoming HTTP request.
type Option ¶
type Option func(*Config)
Option configures functional options for the Captcha plugin.
func WithAllowedHostnames ¶
WithAllowedHostnames sets allowed hostnames list.
func WithEndpoints ¶
WithEndpoints configures protected endpoint URIs.
func WithExemptEndpoints ¶
WithExemptEndpoints configures exempted endpoint URIs.
func WithExpectedAction ¶
WithExpectedAction sets expected action string for Turnstile or reCAPTCHA v3.
func WithHTTPClient ¶
WithHTTPClient configures custom HTTP client for verification calls.
func WithIPExtractor ¶
func WithIPExtractor(fn IPExtractorFunc) Option
WithIPExtractor configures custom client IP extractor function.
func WithMinScore ¶
WithMinScore sets minimum score threshold for Google reCAPTCHA v3.
func WithSecretKey ¶
WithSecretKey sets the provider secret key.
func WithSiteVerifyURLOverride ¶
WithSiteVerifyURLOverride overrides provider default siteverify URL.
func WithTimeout ¶
WithTimeout sets maximum timeout for verification HTTP call.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin implements Captcha verification middleware for go-modular-auth.
func (*Plugin) IsProtectedPath ¶
IsProtectedPath determines whether a request path requires captcha verification.
type Provider ¶
type Provider string
Provider identifies a supported captcha verification provider.
const ( // ProviderCloudflareTurnstile represents Cloudflare Turnstile captcha service. ProviderCloudflareTurnstile Provider = "cloudflare-turnstile" // ProviderGoogleRecaptcha represents Google reCAPTCHA v2 / v3 service. ProviderGoogleRecaptcha Provider = "google-recaptcha" // ProviderHCaptcha represents hCaptcha verification service. ProviderHCaptcha Provider = "hcaptcha" // ProviderCaptchaFox represents CaptchaFox verification service. ProviderCaptchaFox Provider = "captchafox" )
Source Files