A captcha provider: one module that is a mishka_installer plugin on the "captcha:providers" event and implements the callbacks below. MishkaCmsCore.Captcha never names a provider: a scope picks one on the settings page's Security tab (security.captcha.provider), and its sign-in, registration, forgot-password and sign-in-link forms ask it.

defmodule MyExtension.Captcha.Acme do
  use MishkaCmsCore.Captcha.Provider, id: "acme", label: "Acme Captcha"

  @site_key "security.captcha.acme.site_key"
  @secret "security.captcha.acme.secret_key"

  @impl true
  def settings do
    [
      site_key(@site_key, gettext_noop("Acme site key"), group: "Acme Captcha"),
      secret(@secret, gettext_noop("Acme secret key"), group: "Acme Captcha")
    ]
  end

  @impl true
  def ready?(site_id), do: own(@site_key, site_id) != nil and secret?(@secret, site_id)

  @impl true
  def browser(site_id, _form, _language) do
    %{
      script: "https://captcha.acme.example/api.js?render=explicit",
      global: "acme",
      mode: :widget,
      options: %{"sitekey" => own(@site_key, site_id)}
    }
  end

  @impl true
  def csp, do: %{script_src: ["https://captcha.acme.example"], frame_src: ["https://captcha.acme.example"]}

  @impl true
  def verify(token, site_id, request) do
    with {:ok, answer} <-
           siteverify("https://captcha.acme.example/siteverify", %{
             secret: Settings.secret(@secret, site_id),
             response: token,
             remoteip: request.remote_ip
           }),
         do: {:ok, %{hostname: answer["hostname"], test?: false}}
  end
end

Supervise the module in the extension's application, like any other plugin. use adds the plugin half — the "captcha:providers" registration, see MishkaCmsCore.ProviderRegistry — plus site_key/3 and secret/3, which build a provider's settings the way the core's are built, own/2, which reads one, and siteverify/2, which asks a provider's server about a token.

Settings

settings/0 declares the provider's own fields, shown on the Security tab under its label. Each scope sets its own (resolve: :own): a site never checks with another site's keys. The secret is a :secret setting; read it with MishkaCmsCore.Settings.secret/2, never get/3.

The browser

browser/3 tells the one Captcha hook (assets/js/shared_hooks.js) how to draw the check for form in language: the script to load, the global it defines, and the mode —

• :widget — a box drawn with global.render(element, options), whose callback hands back the token (Turnstile, reCAPTCHA v2, hCaptcha);
• :score — nothing drawn: global.execute(options.sitekey, %{action: options.action}) is asked for a token as the form is sent (reCAPTCHA v3).

csp/0 names the origins the browser loads the provider from; the security headers allow them on the sites that use it, and nowhere else.

Verifying

verify/3 asks the provider's server about one token, for site_id, with request — %{remote_ip: address | nil, form: form} — through siteverify/2, which reads the answer the same way for every provider. It answers {:ok, %{hostname: host, test?: boolean}}: the address the check was solved on, and whether the scope checks with the provider's published test keys, which pass every token on any address; or {:error, {:failed, detail}} when the token was refused — wrong, expired, used, a low score — or {:error, {:unavailable, detail}} when the provider could not be asked or refused the keys themselves. detail is a short text for the log and the settings page's test.

The registered providers

all/0, offered/0 and fetch/1 ask the "captcha:providers" event which providers are installed: the core's own — Cloudflare Turnstile, Google reCAPTCHA and hCaptcha — register the same way an extension's would.