NEXUS hCaptcha Protection

Technical summary

NEXUS hCaptcha Protection protects the NEXUS login against bots using hCaptcha (Enterprise/Standard, privacy-focused): the widget is rendered in the form with the submit button locked until verification, and the token is validated server-side through the official siteverify endpoint with the remote IP. The secret key stays server-side only, with configuration through a panel modal, and the filter accepts hCaptcha or reCAPTCHA tokens for compatibility.

Executed scope

• Plugin registration (registerModal('hcaptcha-modals', modals.php) + style: design.css in plugin.json) and backend functions in backend.php (110 lines): hcaptcha_get_config(), hcaptcha_save_config(), hcaptcha_verify_token(), hcaptcha_is_enabled() and hcaptcha_get_site_key().
• before_login filter (priority 5): when enabled, requires h-captcha-response in the POST (also accepts g-recaptcha-response for compatibility); validates via hcaptcha_verify_token($token, $_SERVER['REMOTE_ADDR']) and blocks login with a clear message on failure.
• login_form_after_fields filter: injects the #hcaptcha-container with the .h-captcha widget (data-sitekey, onHcaptchaSuccess/onHcaptchaExpired callbacks) and loads the hCaptcha api.js + assets/hcaptcha.js.
• Frontend (assets/hcaptcha.js, 27 lines): locks the submit button (disabled + opacity + cursor) until the widget is solved; onHcaptchaSuccess unlocks the button; onHcaptchaExpired locks it again.
• Server-side verification: POST https://api.hcaptcha.com/siteverify with secret, response and remoteip (when available), 10s timeout; JSON response with success and translated error-codes in the message.
• Config protection: the secret key is never returned in full by the API — hcaptcha_get_config returns secret_key_masked (first 6 + last 4 chars); key fields in the modal are password inputs.
• 4 API actions: hcaptcha_save_config (site_key + secret_key + enabled, both required to activate), hcaptcha_get_config (with masked key), hcaptcha_verify (manual token validation) and hcaptcha_sitekey (public state site_key/enabled).
• Fast Responses: fastr.json manifest with /hcaptcha (no required arg), hcaptcha_sitekey action — shows the plugin's public state.
• On-demand only: cronjob.json with jobs: [] (no periodic routine needed); no CLI.
• UI: Alpine.js config modal (hcaptchaConfigModal(), 175 lines in modals.php) with a Configured/Not-configured badge, a link to the hCaptcha dashboard (dashboard.hcaptcha.com) and Site Key/Secret Key fields.
• Lab environment: hcaptcha_is_enabled() returns false on lab hosts (nx_is_lab_host()) — avoids locking the login in test environments.

Stack and tools

• PHP 8 backend (no framework)
• hCaptcha API — widget (js.hcaptcha.com/1/api.js) + server-side siteverify
• Alpine.js + Tailwind CSS (modal) + assets/hcaptcha.js
• Internal Plugin API (PluginManager filters/modals/actions + fastr.json)

Operational tags

• hCaptcha
• Anti-bot
• Login
• Security
• Siteverify
• Privacy
• Web Protection
• NEXUS Plugin

Operational result

• Bot blocking at login: forces challenge completion before unlocking submit and validates the token on the server.
• Server-side validation: siteverify with the secret key and remote IP — the frontend never decides alone.
• Protected keys: the secret key never leaves the server; the API returns only a masked version.
• Privacy: hCaptcha is a privacy-focused alternative, with the modal highlighting the official dashboard.
• Activation control: requires Site Key + Secret Key to enable; automatically disabled on lab hosts.
• No routines: purely on-demand plugin — no cron or CLI.