Documentation
¶
Overview ¶
Package hcaptcha verifies the hCaptcha answer that a form submission carries.
Its entry point is New(Options), which returns a Handler that calls SiteVerify and runs Options.FailureHandler when the answer does not pass. Read the stored Response with Get.
Index ¶
Constants ¶
const Script = "https://hcaptcha.com/1/api.js"
Script is the hCaptcha's javascript source file that should be incldued in the HTML head or body.
Variables ¶
var ( // DefaultFailureHandler is the default HTTP handler that is fired on hcaptcha failures. // See `Options.FailureHandler`. DefaultFailureHandler = func(ctx *context.Context) { ctx.StopWithStatus(http.StatusTooManyRequests) } )
var HTMLForm = `` /* 174-byte string literal not displayed */
HTMLForm is the default HTML form for clients. It's totally optional, use your own code for the best possible result depending on your web application. See `ParseForm` and `RenderForm` for more.
var VerifyTimeout = 10 * time.Second
VerifyTimeout bounds how long a single verification call may take. Set it before the first verification; the HTTP client is built once, on first use, and later assignments have no effect.
Functions ¶
func New ¶
New returns a route middleware Handler which verifies the hcaptcha response of each incoming request against the given Options.
It calls the `SiteVerify` function and fires the "next" handler when the user completed the hcaptcha successfully, otherwise it calls Options.FailureHandler. The hcaptcha's `Response` (which contains any `ErrorCodes`) is saved on the Request's Context (see the `Get` package-level function).
Instructions at: https://docs.hcaptcha.com/.
Types ¶
type Options ¶
type Options struct {
// Secret is the hcaptcha secret key, from https://dashboard.hcaptcha.com/settings.
// Required.
Secret string `yaml:"Secret"`
// FailureHandler if specified, fired when user does not complete hcaptcha successfully.
// Failure and error codes information are kept as a `Response` value
// in the request's context, retrieved through the `Get` package-level function.
//
// Defaults to DefaultFailureHandler, which writes a status code of
// 429 (Too Many Requests) and no additional information.
FailureHandler context.Handler `yaml:"-"`
// RemoteIP is an optional check for siteverify:
// the user's remote IP address, sent as the "remoteip" form field.
//
// Defaults to empty, not sent.
RemoteIP string `yaml:"RemoteIP"`
// SiteKey is an optional check for siteverify:
// the sitekey form field you expect to see.
//
// Defaults to empty, not sent.
SiteKey string `yaml:"SiteKey"`
}
Options is the configuration for the hcaptcha middleware. The zero value is valid but useless: Secret is required.
type Response ¶
type Response struct {
ChallengeTS string `json:"challenge_ts"`
Hostname string `json:"hostname"`
ErrorCodes []string `json:"error-codes,omitempty"`
Success bool `json:"success"`
Credit bool `json:"credit,omitzero"`
}
Response is the hcaptcha JSON response.
func Get ¶
Get returns the hcaptcha `Response` of the current request and reports whether was found or not.
func SiteVerify ¶
SiteVerify accepts an Iris Context and a secret key (https://dashboard.hcaptcha.com/settings). It returns the hcaptcha's `Response`. The `response.Success` reports whether the validation passed. Any errors are passed through the `response.ErrorCodes` field.
The remoteIP and siteKey input arguments are optional.