Add reCAPTCHA Invisible and hCaptcha CAPTCHA providers

nikosdion · claude · nikosdion · commit 454968e804b5 · 2026-02-11T15:00:11.000+02:00
Introduce a CaptchaFactory to replace hardcoded provider checks, and add
two new CAPTCHA implementations: Google reCAPTCHA Invisible v2 and
hCaptcha. Each provider is self-contained with its own script tags and
server-side verification. The sysconfig UI conditionally shows API key
fields based on the selected provider.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/.env.dist b/.env.dist
@@ -269,9 +269,31 @@ PANOPTICON_USER_REGISTRATION_ACTIVATION_TRIES=3
 # CAPTCHA provider
 # The CAPTCHA provider to use on the registration form. Options:
 # - altcha: Self-hosted ALTCHA proof-of-work challenge (default)
+# - recaptcha_invisible: Google reCAPTCHA Invisible (requires API keys)
+# - hcaptcha: hCaptcha (requires API keys)
 # - none: No CAPTCHA
 PANOPTICON_CAPTCHA_PROVIDER=altcha
 
+# reCAPTCHA Site Key
+# The site key from the Google reCAPTCHA admin console.
+# Only required when captcha_provider is set to recaptcha_invisible.
+PANOPTICON_CAPTCHA_RECAPTCHA_SITE_KEY=
+
+# reCAPTCHA Secret Key
+# The secret key from the Google reCAPTCHA admin console.
+# Only required when captcha_provider is set to recaptcha_invisible.
+PANOPTICON_CAPTCHA_RECAPTCHA_SECRET_KEY=
+
+# hCaptcha Site Key
+# The site key from the hCaptcha dashboard.
+# Only required when captcha_provider is set to hcaptcha.
+PANOPTICON_CAPTCHA_HCAPTCHA_SITE_KEY=
+
+# hCaptcha Secret Key
+# The secret key from the hCaptcha dashboard.
+# Only required when captcha_provider is set to hcaptcha.
+PANOPTICON_CAPTCHA_HCAPTCHA_SECRET_KEY=
+
 # Login with passkey
 # Should passkeys be allowed as a login method?
 PANOPTICON_PASSKEY_LOGIN=true
diff --git a/ViewTemplates/Sysconfig/default_registration.blade.php b/ViewTemplates/Sysconfig/default_registration.blade.php
@@ -168,8 +168,10 @@
             <div class="col-sm-9">
                 {{ $this->container->html->select->genericList(
                     data: [
-                        'altcha' => $this->getLanguage()->text('PANOPTICON_SYSCONFIG_OPT_CAPTCHA_ALTCHA'),
-                        'none'   => $this->getLanguage()->text('PANOPTICON_SYSCONFIG_OPT_CAPTCHA_NONE'),
+                        'altcha'              => $this->getLanguage()->text('PANOPTICON_SYSCONFIG_OPT_CAPTCHA_ALTCHA'),
+                        'recaptcha_invisible' => $this->getLanguage()->text('PANOPTICON_SYSCONFIG_OPT_CAPTCHA_RECAPTCHA_INVISIBLE'),
+                        'hcaptcha'            => $this->getLanguage()->text('PANOPTICON_SYSCONFIG_OPT_CAPTCHA_HCAPTCHA'),
+                        'none'                => $this->getLanguage()->text('PANOPTICON_SYSCONFIG_OPT_CAPTCHA_NONE'),
                     ],
                     name: 'options[captcha_provider]',
                     attribs: [
@@ -183,5 +185,69 @@
                 </div>
             </div>
         </div>
+
+        {{-- captcha_recaptcha_site_key --}}
+        <div class="row mb-3" data-showon='[{"field":"options[user_registration]","values":["admin","self"],"sign":"=","op":""},{"field":"options[captcha_provider]","values":["recaptcha_invisible"],"sign":"=","op":"AND"}]'>
+            <label for="captcha_recaptcha_site_key" class="col-sm-3 col-form-label">
+                @lang('PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_RECAPTCHA_SITE_KEY')
+            </label>
+            <div class="col-sm-9">
+                <input type="text" class="form-control" id="captcha_recaptcha_site_key"
+                       name="options[captcha_recaptcha_site_key]"
+                       value="{{{ $config->get('captcha_recaptcha_site_key', '') }}}"
+                >
+                <div class="form-text">
+                    @lang('PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_RECAPTCHA_SITE_KEY_HELP')
+                </div>
+            </div>
+        </div>
+
+        {{-- captcha_recaptcha_secret_key --}}
+        <div class="row mb-3" data-showon='[{"field":"options[user_registration]","values":["admin","self"],"sign":"=","op":""},{"field":"options[captcha_provider]","values":["recaptcha_invisible"],"sign":"=","op":"AND"}]'>
+            <label for="captcha_recaptcha_secret_key" class="col-sm-3 col-form-label">
+                @lang('PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_RECAPTCHA_SECRET_KEY')
+            </label>
+            <div class="col-sm-9">
+                <input type="text" class="form-control" id="captcha_recaptcha_secret_key"
+                       name="options[captcha_recaptcha_secret_key]"
+                       value="{{{ $config->get('captcha_recaptcha_secret_key', '') }}}"
+                >
+                <div class="form-text">
+                    @lang('PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_RECAPTCHA_SECRET_KEY_HELP')
+                </div>
+            </div>
+        </div>
+
+        {{-- captcha_hcaptcha_site_key --}}
+        <div class="row mb-3" data-showon='[{"field":"options[user_registration]","values":["admin","self"],"sign":"=","op":""},{"field":"options[captcha_provider]","values":["hcaptcha"],"sign":"=","op":"AND"}]'>
+            <label for="captcha_hcaptcha_site_key" class="col-sm-3 col-form-label">
+                @lang('PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_HCAPTCHA_SITE_KEY')
+            </label>
+            <div class="col-sm-9">
+                <input type="text" class="form-control" id="captcha_hcaptcha_site_key"
+                       name="options[captcha_hcaptcha_site_key]"
+                       value="{{{ $config->get('captcha_hcaptcha_site_key', '') }}}"
+                >
+                <div class="form-text">
+                    @lang('PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_HCAPTCHA_SITE_KEY_HELP')
+                </div>
+            </div>
+        </div>
+
+        {{-- captcha_hcaptcha_secret_key --}}
+        <div class="row mb-3" data-showon='[{"field":"options[user_registration]","values":["admin","self"],"sign":"=","op":""},{"field":"options[captcha_provider]","values":["hcaptcha"],"sign":"=","op":"AND"}]'>
+            <label for="captcha_hcaptcha_secret_key" class="col-sm-3 col-form-label">
+                @lang('PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_HCAPTCHA_SECRET_KEY')
+            </label>
+            <div class="col-sm-9">
+                <input type="text" class="form-control" id="captcha_hcaptcha_secret_key"
+                       name="options[captcha_hcaptcha_secret_key]"
+                       value="{{{ $config->get('captcha_hcaptcha_secret_key', '') }}}"
+                >
+                <div class="form-text">
+                    @lang('PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_HCAPTCHA_SECRET_KEY_HELP')
+                </div>
+            </div>
+        </div>
     </div>
 </div>
diff --git a/ViewTemplates/Users/register.blade.php b/ViewTemplates/Users/register.blade.php
@@ -7,24 +7,16 @@
 
 defined('AKEEBA') || die;
 
-use Akeeba\Panopticon\Factory;
-use Akeeba\Panopticon\Library\Captcha\AltchaCaptcha;
-use Awf\Utils\Template;
+use Akeeba\Panopticon\Library\Captcha\CaptchaFactory;
 
 /** @var \Akeeba\Panopticon\View\Users\Html $this */
 
 $container       = $this->getContainer();
 $captchaProvider = $container->appConfig->get('captcha_provider', 'altcha');
 
 // Generate CAPTCHA challenge
-$captchaHtml = '';
-
-if ($captchaProvider === 'altcha')
-{
-    $captcha     = new AltchaCaptcha($container);
-    $captchaHtml = $captcha->renderChallenge();
-    Template::addJs('media://altcha/altcha.js', $container->application, defer: true);
-}
+$captcha     = CaptchaFactory::make($captchaProvider, $container);
+$captchaHtml = $captcha?->renderChallenge() ?? '';
 
 ?>
 
diff --git a/languages/en-GB.ini b/languages/en-GB.ini
@@ -1454,7 +1454,17 @@ PANOPTICON_SYSCONFIG_LBL_FIELD_REGISTRATION_ACTIVATION_TRIES="Maximum activation
 PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_PROVIDER="CAPTCHA provider"
 PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_PROVIDER_HELP="The CAPTCHA provider to use on the registration form to prevent automated registrations."
 PANOPTICON_SYSCONFIG_OPT_CAPTCHA_ALTCHA="ALTCHA (self-hosted proof-of-work)"
+PANOPTICON_SYSCONFIG_OPT_CAPTCHA_RECAPTCHA_INVISIBLE="reCAPTCHA Invisible (Google)"
+PANOPTICON_SYSCONFIG_OPT_CAPTCHA_HCAPTCHA="hCaptcha"
 PANOPTICON_SYSCONFIG_OPT_CAPTCHA_NONE="None"
+PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_RECAPTCHA_SITE_KEY="reCAPTCHA Site Key"
+PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_RECAPTCHA_SITE_KEY_HELP="Enter the site key from your Google reCAPTCHA admin console. You need an Invisible reCAPTCHA v2 key."
+PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_RECAPTCHA_SECRET_KEY="reCAPTCHA Secret Key"
+PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_RECAPTCHA_SECRET_KEY_HELP="Enter the secret key from your Google reCAPTCHA admin console."
+PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_HCAPTCHA_SITE_KEY="hCaptcha Site Key"
+PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_HCAPTCHA_SITE_KEY_HELP="Enter the site key from your hCaptcha dashboard."
+PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_HCAPTCHA_SECRET_KEY="hCaptcha Secret Key"
+PANOPTICON_SYSCONFIG_LBL_FIELD_CAPTCHA_HCAPTCHA_SECRET_KEY_HELP="Enter the secret key from your hCaptcha dashboard."
 
 PANOPTICON_SYSCONFIG_LBL_EXTENSIONS_TABLE_CAPTION="Table of known extensions and their automatic update preferences"
 PANOPTICON_SYSCONFIG_LBL_EXTENSIONS_CMS="CMS Type"
diff --git a/src/Application/Trait/DefaultConfigurationTrait.php b/src/Application/Trait/DefaultConfigurationTrait.php
@@ -111,6 +111,10 @@ public function getDefaultConfiguration(): array
 			'user_registration_activation_days'          => 7,
 			'user_registration_activation_tries'         => 3,
 			'captcha_provider'                           => 'altcha',
+			'captcha_recaptcha_site_key'                 => '',
+			'captcha_recaptcha_secret_key'               => '',
+			'captcha_hcaptcha_site_key'                  => '',
+			'captcha_hcaptcha_secret_key'                => '',
 		];
 	}
 
@@ -144,7 +148,7 @@ public function getConfigurationOptionAutocomplete(string $key, $currentValue):
 			'dbdriver' => ['mysqli', 'pdomysql'],
 			'dbhost' => array_filter(['localhost', '127.0.0.1', $this->get('dbhost')]),
 			'user_registration' => ['disabled', 'admin', 'self'],
-			'captcha_provider' => ['altcha', 'none'],
+			'captcha_provider' => ['altcha', 'none', 'recaptcha_invisible', 'hcaptcha'],
 			'user_registration_activation_days' => [1, 3, 5, 7, 14, 30],
 			'user_registration_activation_tries' => [1, 3, 5, 10],
 			'default' => [],
@@ -225,7 +229,7 @@ private function getConfigurationOptionFilterCallback(string $key): callable
 			'user_registration_activation_days' => fn($x) => $this->validateInteger($x, 7, 1, 90),
 			'user_registration_activation_tries' => fn($x) => $this->validateInteger($x, 3, 1, 100),
 			'captcha_provider' => fn($x) => $this->validatePresetValues(
-				$x, 'altcha', ['altcha', 'none']
+				$x, 'altcha', ['altcha', 'none', 'recaptcha_invisible', 'hcaptcha']
 			),
 			default => fn($x) => $x,
 		};
diff --git a/src/Controller/Users.php b/src/Controller/Users.php
@@ -11,7 +11,7 @@
 
 use Akeeba\Panopticon\Controller\Trait\ACLTrait;
 use Akeeba\Panopticon\Factory;
-use Akeeba\Panopticon\Library\Captcha\AltchaCaptcha;
+use Akeeba\Panopticon\Library\Captcha\CaptchaFactory;
 use Akeeba\Panopticon\Library\Passkey\Authentication;
 use Akeeba\Panopticon\View\Users\Html;
 use Awf\Mvc\DataController;
@@ -233,15 +233,11 @@ public function register(): void
 		{
 			// Validate CAPTCHA
 			$captchaProvider = $appConfig->get('captcha_provider', 'altcha');
+			$captcha         = CaptchaFactory::make($captchaProvider, $container);
 
-			if ($captchaProvider === 'altcha')
+			if ($captcha !== null && !$captcha->validateResponse())
 			{
-				$captcha = new AltchaCaptcha($container);
-
-				if (!$captcha->validateResponse())
-				{
-					throw new RuntimeException($lang->text('PANOPTICON_USERS_ERR_CAPTCHA_FAILED'));
-				}
+				throw new RuntimeException($lang->text('PANOPTICON_USERS_ERR_CAPTCHA_FAILED'));
 			}
 
 			// Validate passwords match
diff --git a/src/Library/Captcha/AltchaCaptcha.php b/src/Library/Captcha/AltchaCaptcha.php
@@ -54,6 +54,7 @@ public function renderChallenge(): string
 		$challengeJson = htmlspecialchars(json_encode($challenge), ENT_QUOTES, 'UTF-8');
 
 		return <<<HTML
+<script src="media/altcha/altcha.js" defer></script>
 <altcha-widget challengejson="{$challengeJson}" auto="onsubmit"></altcha-widget>
 HTML;
 	}
diff --git a/src/Library/Captcha/CaptchaFactory.php b/src/Library/Captcha/CaptchaFactory.php
@@ -0,0 +1,34 @@
+<?php
+/**
+ * @package   panopticon
+ * @copyright Copyright (c)2023-2026 Nicholas K. Dionysopoulos / Akeeba Ltd
+ * @license   https://www.gnu.org/licenses/agpl-3.0.txt GNU Affero General Public License, version 3 or later
+ */
+
+namespace Akeeba\Panopticon\Library\Captcha;
+
+defined('AKEEBA') || die;
+
+use Awf\Container\Container;
+
+class CaptchaFactory
+{
+	/**
+	 * Create a CAPTCHA provider instance based on the provider name.
+	 *
+	 * @param   string     $provider   The provider name (e.g. 'altcha', 'recaptcha_invisible', 'hcaptcha', 'none')
+	 * @param   Container  $container  The application container
+	 *
+	 * @return  CaptchaInterface|null  The CAPTCHA provider instance, or null for 'none'
+	 */
+	public static function make(string $provider, Container $container): ?CaptchaInterface
+	{
+		return match ($provider)
+		{
+			'altcha'               => new AltchaCaptcha($container),
+			'recaptcha_invisible'  => new RecaptchaInvisibleCaptcha($container),
+			'hcaptcha'             => new HCaptchaCaptcha($container),
+			default                => null,
+		};
+	}
+}
diff --git a/src/Library/Captcha/HCaptchaCaptcha.php b/src/Library/Captcha/HCaptchaCaptcha.php
@@ -0,0 +1,111 @@
+<?php
+/**
+ * @package   panopticon
+ * @copyright Copyright (c)2023-2026 Nicholas K. Dionysopoulos / Akeeba Ltd
+ * @license   https://www.gnu.org/licenses/agpl-3.0.txt GNU Affero General Public License, version 3 or later
+ */
+
+namespace Akeeba\Panopticon\Library\Captcha;
+
+defined('AKEEBA') || die;
+
+use Awf\Container\Container;
+use GuzzleHttp\RequestOptions;
+
+/**
+ * hCaptcha Invisible CAPTCHA implementation.
+ *
+ * Uses hCaptcha's invisible mode which triggers automatically on form submit.
+ * The challenge is verified server-side via hCaptcha's siteverify API.
+ */
+class HCaptchaCaptcha implements CaptchaInterface
+{
+	private string $siteKey;
+
+	private string $secretKey;
+
+	public function __construct(
+		private readonly Container $container
+	)
+	{
+		$this->siteKey   = trim((string) $this->container->appConfig->get('captcha_hcaptcha_site_key', ''));
+		$this->secretKey = trim((string) $this->container->appConfig->get('captcha_hcaptcha_secret_key', ''));
+	}
+
+	public function getName(): string
+	{
+		return 'hcaptcha';
+	}
+
+	public function getLabel(): string
+	{
+		return 'hCaptcha';
+	}
+
+	public function renderChallenge(): string
+	{
+		if (empty($this->siteKey))
+		{
+			return '';
+		}
+
+		$siteKeyAttr = htmlspecialchars($this->siteKey, ENT_QUOTES, 'UTF-8');
+
+		return <<<HTML
+<script src="https://js.hcaptcha.com/1/api.js" async defer></script>
+<div id="panopticon-hcaptcha-invisible"></div>
+<script>
+    var onHCaptchaSubmit = function(token) {
+        document.getElementById("panopticon-hcaptcha-invisible").closest("form").submit();
+    };
+    document.addEventListener("DOMContentLoaded", function() {
+        var form = document.getElementById("panopticon-hcaptcha-invisible").closest("form");
+        if (!form) return;
+        form.addEventListener("submit", function(e) {
+            if (document.getElementById("h-captcha-response") && document.getElementById("h-captcha-response").value) return;
+            e.preventDefault();
+            hcaptcha.execute();
+        });
+    });
+</script>
+<div class="h-captcha" data-sitekey="{$siteKeyAttr}" data-size="invisible" data-callback="onHCaptchaSubmit"></div>
+HTML;
+	}
+
+	public function validateResponse(): bool
+	{
+		if (empty($this->secretKey))
+		{
+			return false;
+		}
+
+		$input    = $this->container->input;
+		$response = $input->get('h-captcha-response', '', 'raw');
+
+		if (empty($response))
+		{
+			return false;
+		}
+
+		try
+		{
+			$options              = $this->container->httpFactory->getDefaultRequestOptions();
+			$options[RequestOptions::FORM_PARAMS] = [
+				'secret'   => $this->secretKey,
+				'response' => $response,
+				'sitekey'  => $this->siteKey,
+			];
+
+			$client   = $this->container->httpFactory->makeClient(cache: false, singleton: false);
+			$httpResp = $client->post('https://api.hcaptcha.com/siteverify', $options);
+
+			$body = json_decode((string) $httpResp->getBody(), true);
+
+			return !empty($body['success']);
+		}
+		catch (\Throwable)
+		{
+			return false;
+		}
+	}
+}
diff --git a/src/Library/Captcha/RecaptchaInvisibleCaptcha.php b/src/Library/Captcha/RecaptchaInvisibleCaptcha.php
diff --git a/src/Model/Sysconfig.php b/src/Model/Sysconfig.php

Original file line number	Diff line number	Diff line change
`@@ -54,6 +54,7 @@ public function renderChallenge(): string`
`54`	`54`	`$challengeJson = htmlspecialchars(json_encode($challenge), ENT_QUOTES, 'UTF-8');`
`55`	`55`
`56`	`56`	`return <<<HTML`
	`57`	`+<script src="media/altcha/altcha.js" defer></script>`
`57`	`58`	`<altcha-widget challengejson="{$challengeJson}" auto="onsubmit"></altcha-widget>`
`58`	`59`	`HTML;`
`59`	`60`	`}`