NEXUS hCaptcha Protection

Resumo técnico

O NEXUS hCaptcha Protection protege o login do NEXUS contra bots usando o hCaptcha (Enterprise/Standard, com foco em privacidade): o widget é renderizado no formulário com o botão de submit travado até a verificação, e o token é validado server-side via endpoint oficial siteverify com o IP remoto. A secret key fica apenas no servidor, com configuração por modal no painel, e o filtro aceita tokens de hCaptcha ou reCAPTCHA por compatibilidade.

Escopo executado

• Registro do plugin (registerModal('hcaptcha-modals', modals.php) + style: design.css em plugin.json) e funções backend em backend.php (110 linhas): hcaptcha_get_config(), hcaptcha_save_config(), hcaptcha_verify_token(), hcaptcha_is_enabled() e hcaptcha_get_site_key().
• Filtro before_login (prioridade 5): se habilitado, exige h-captcha-response no POST (aceita também g-recaptcha-response por compatibilidade); valida via hcaptcha_verify_token($token, $_SERVER['REMOTE_ADDR']) e bloqueia o login com mensagem clara se falhar.
• Filtro login_form_after_fields: injeta o container #hcaptcha-container com o widget .h-captcha (data-sitekey, callbacks onHcaptchaSuccess/onHcaptchaExpired) e carrega api.js do hCaptcha + assets/hcaptcha.js.
• Frontend (assets/hcaptcha.js, 27 linhas): trava o botão de submit (disabled + opacidade + cursor) até o widget ser resolvido; onHcaptchaSuccess libera o botão; onHcaptchaExpired trava novamente.
• Verificação server-side: POST https://api.hcaptcha.com/siteverify com secret, response e remoteip (quando disponível), timeout 10s; resposta JSON com success e error-codes traduzidos na mensagem.
• Proteção de configuração: secret key nunca é devolvida completa pela API — hcaptcha_get_config retorna secret_key_masked (6 primeiros + 4 últimos chars); campos de chave no modal são tipo password.
• API com 4 actions: hcaptcha_save_config (site_key + secret_key + enabled, exige ambas para ativar), hcaptcha_get_config (com key mascarada), hcaptcha_verify (validação manual de token) e hcaptcha_sitekey (estado público site_key/enabled).
• Fast Responses: manifesto fastr.json com /hcaptcha (sem arg obrigatório), action hcaptcha_sitekey — mostra o estado público do plugin.
• Sob demanda: cronjob.json com jobs: [] (nenhuma rotina periódica necessária); sem CLI.
• Interface: modal de configuração Alpine.js (hcaptchaConfigModal(), 175 linhas em modals.php) com badge Configurado/Não configurado, link para o painel hCaptcha (dashboard.hcaptcha.com) e campos Site Key/Secret Key.
• Ambiente de laboratório: hcaptcha_is_enabled() retorna false em host de laboratório (nx_is_lab_host()) — evita travar o login em ambientes de teste.

Stack e ferramentas

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

Tags operacionais

• hCaptcha
• Anti-bot
• Login
• Segurança
• Siteverify
• Privacidade
• Proteção Web
• Plugin NEXUS

Resultado operacional

• Bloqueio de bots no login: força a resolução do desafio antes de liberar o submit e valida o token no servidor.
• Validação server-side: siteverify com secret key e IP remoto — o frontend nunca decide sozinho.
• Chaves protegidas: secret key nunca sai do servidor; a API devolve apenas versão mascarada.
• Privacidade: hCaptcha é alternativa focada em privacidade, com modal destacando o painel oficial.
• Controle de ativação: exige Site Key + Secret Key para habilitar; desativado automaticamente em host de laboratório.
• Sem rotinas: plugin puramente sob demanda — sem cron nem CLI.