Hcaptcha

A simple Elixir package for implementing hCAPTCHA in Elixir applications.

The package is fork of the recaptcha package which uses a similar flow as needed for hCaptcha.

Installation

1. Add hcaptcha to your mix.exs dependencies

  defp deps do
    [
      {:hcaptcha, "~> 0.9.0"},
    ]
  end

2. List :hcaptcha as an application dependency

  def application do
    [ extra_applications: [:hcaptcha] ]
  end

3. Run mix do deps.get, compile

Config

By default the public and private keys are loaded via the HCAPTCHA_SITEKEY and HCAPTCHA_SECRET environment variables.

  config :hcaptcha,
    sitekey: {:system, "HCAPTCHA_SITEKEY"},
    secret: {:system, "HCAPTCHA_SECRET"}

JSON Decoding

By default hCaptcha will use Jason to decode JSON responses, this can be changed as such:

  config :hcaptcha, :json_library, Poison

Usage

Render the Widget

Use raw (if you're using Phoenix.HTML) and Hcaptcha.Template.display/1 methods to render the captcha widget.

For hcaptcha with checkbox

<form name="someform" method="post" action="/somewhere">
  ...
  <%= raw Hcaptcha.Template.display %>
  ...
</form>

For invisible hcaptcha

<form name="someform" method="post" action="/somewhere">
  ...
  <%= raw Hcaptcha.Template.display(size: "invisible") %>
</form>
  ...

Since hcaptcha loads Javascript code asynchronously, you cannot immediately submit the captcha form. If you have logic that needs to know if the captcha code has already been loaded (for example disabling submit button until fully loaded), it is possible to pass in a JS-callback that will be called once the captcha has finished loading. This can be done as follows:

<form name="someform" method="post" action="/somewhere">
  ...
  <%= raw Hcaptcha.Template.display(onload: "myOnLoadCallback") %>
</form>
  ...

And then in your JS code:

function myOnLoadCallback() {
  // perform extra actions here
}

display method accepts additional options as a keyword list, the options are:

Option	Action	Default
sitekey	Sets key to the data-sitekey hCaptcha div attribute	Public key from the config file
hl	Sets the language of the hCaptcha	en

Verify API

Hcaptcha provides the verify/2 method. Below is an example using a Phoenix controller action:

  def create(conn, params) do
    case Hcaptcha.verify(params["h-captcha-response"]) do
      {:ok, response} -> do_something
      {:error, errors} -> handle_error
    end
  end

verify method sends a POST request to the hCAPTCHA API and returns 2 possible values:

{:ok, %Hcaptcha.Response{challenge_ts: timestamp, hostname: host}} -> The captcha is valid, see the documentation for more details.

{:error, errors} -> errors contains atomised versions of the errors returned by the API, See the error documentation for more details. Errors caused by timeouts in HTTPoison or Jason encoding are also returned as atoms. If the hcaptcha request succeeds but the challenge is failed, a :challenge_failed error is returned.

verify method also accepts a keyword list as the third parameter with the following options:

Option	Action	Default
timeout	Time to wait before timeout	5000 (ms)
secret	Private key to send as a parameter of the API request	Private key from the config file
remote_ip	Optional. The user's IP address, used by hCaptcha	no default

Testing

In order to test your endpoints you should set the secret key to the following value in order to receive a positive result from all queries to the Hcaptcha engine.

config :hcaptcha,
  secret: "0x0000000000000000000000000000000000000000"

Setting up tests without network access can be done also. When configured as such a positive or negative result can be generated locally.

# In Config
config :hcaptcha,
  http_client: Hcaptcha.Http.MockClient,
  secret: "0x0000000000000000000000000000000000000000"


# In Response Checks
  {:ok, _details} = Hcaptcha.verify("valid_response")

  {:error, _details} = Hcaptcha.verify("invalid_response")

Contributing

Check out CONTRIBUTING.md if you want to help.

License

MIT License.