🧩 BladeCAPTCHA

MIT 9 KB No tracking

Esta página detalla cómo integrar y configurar BladeCAPTCHA en tu sitio web.

📦 Requisitos

• Navegador con soporte para Web Workers y JavaScript ES6 Modules (compatibilidad garantizada en navegadores modernos como Chrome, Firefox, Edge y Safari).
• Servidor capaz de servir archivos estáticos y ejecutar código PHP 8.0+, con las siguientes extensiones instaladas: openssl, mbstring y json.

📁 Instalación

1. Descargá el paquete completo desde GitHub o cloná el repositorio.
2. Subí el contenido a tu servidor.
3. Renombrá config/config.sample.php a config/config.php y editá el valor de CAPTCHA_SECRET_KEY, que es la clave secreta con que se validan los tokens. (Más info sobre esta configuración aquí.)

mv config/config.sample.php config/config.php
nano config/config.php

🚀 Uso básico

Importar el módulo captcha.js y llamar a initCaptcha() con la configuración deseada:

<script type="module">
import { initCaptcha } from './captcha.js';
(async () => {
  try {
    await initCaptcha({
      mode: 'autoFormIntegration',
      // otros parámetros...
    });
  } catch (err) {
    console.error(err || err.message);
  }
})();
</script>

⚙️ Configuración (initCaptcha)

La función initCaptcha(options) acepta los siguientes parámetros:

🔀 Ejemplo: autoFormIntegration

▶️ Ver demo

<script type="module">
import { initCaptcha } from './captcha.js';

(async () => {
  try {
    await initCaptcha({
      mode: 'autoFormIntegration',
      apiBaseUrl : '../php',
      formSelector: '#contactForm',
      inputName: 'captcha_token',
      submitButtonSelector: '#submitBtn',
      onStart: () => {
        document.querySelector('#submitBtn').textContent = 'Verificando...';
      },
      onEnd: () => {
        document.querySelector('#submitBtn').textContent = 'Enviar';
      }
    });
  } catch (err) {
     console.error(err || err.message);
  }
})();
</script>

🖐️ Ejemplo: manualHandling

▶️ Ver demo

<script type="module">
import { initCaptcha } from './captcha.js';

(async () => {
  try {
    await initCaptcha({
      mode: 'manualHandling',
      apiBaseUrl : '../php',
      verifyButtonSelector: '#checkHuman',
      statusSelector: '#captchaStatus',
      manualHandlingAutoStartOnLoad: false,
      onStart: () => {
        console.log('Iniciando verificación...');
      },
      onEnd: () => {
        console.log('Verificación cancelada o completada.');
      },
      onProgress: (p) => {
        console.log(`Progreso: ${p}%`);
      }
    });
  } catch (err) {
    console.error(err || err.message);
  }
})();
</script>

💡 Variables auxiliares y contexto compartido

Cuando usamos initCaptcha como módulo ES6 importado, cada llamada a la función se ejecuta en un entorno aislado y las variables internas no están accesibles externamente. Por eso, si necesitamos conservar información entre callbacks —como el texto original de un botón antes de cambiarlo— debemos definir una variable auxiliar en nuestro código, y usarla explícitamente en las funciones que pasamos en la configuración.

▶️ Ver demo

import { initCaptcha } from './captcha.js'; // o ruta correcta

// Definir memo en el contexto del módulo o script
let memo = null; // Variable auxiliar para onStart y onEnd

(async () => {
  try {
    await initCaptcha({
      // otros parámetros...
      onStart: () => {
        const btn = document.querySelector('#submitBtn');
        memo = btn.textContent;  // guardamos texto original en memo
        btn.disabled = true;
        btn.style.cursor = 'wait';
        btn.textContent = 'Por favor espere...';
      },
      onEnd: () => {
        const btn = document.querySelector('#submitBtn');
        btn.textContent = memo;  // restauramos texto original desde memo
        btn.disabled = false;
        btn.style.cursor = 'pointer';
      }
    });
  } catch (err) {
    console.error(err || err.message);
  }
})();

🔄 Ejemplo: autoFormIntegration con múltiples formularios

▶️ Ver demo

<script type="module">
  import { initCaptcha } from './path/to/captcha.js';

  // Array de selectores de formularios que usarán BladeCAPTCHA
  const forms = ['#contactForm', '#loginForm', '#newsletterForm'];

  forms.forEach(async (formSelector) => {
    // Variable auxiliar para guardar el texto original del botón submit
    let memo;

    try {
      await initCaptcha({
        mode: 'autoFormIntegration',
        apiBaseUrl : '../php',
        formSelector: formSelector,
        inputName: 'captcha_token',
        submitButtonSelector: `${formSelector} button[type="submit"]`,
        onStart: () => {
          const btn = document.querySelector(`${formSelector} button[type="submit"]`);
          if (!btn) return;
          memo = btn.textContent;
          btn.textContent = 'Verificando...';
          btn.disabled = true;
          btn.style.cursor = 'wait';
        },
        onEnd: () => {
          const btn = document.querySelector(`${formSelector} button[type="submit"]`);
          if (!btn) return;
          btn.textContent = memo || 'Enviar';
          btn.disabled = false;
          btn.style.cursor = 'pointer';
        }
      });
    } catch (err) {
      console.error(err || err.message);
    }
  });
</script>

🔧 Características técnicas destacadas

📁 Archivo de configuración (PHP)

BladeCAPTCHA permite definir algunos parámetros del comportamiento general desde un archivo PHP simple.

Este archivo define constantes y variables de configuración que son utilizadas por la biblioteca durante la validación del token. Por razones de seguridad es conveniente que sea ubicado fuera del directorio público (por ejemplo, en BladeCAPTCHA/config/config.php).

Ejemplo:

<?php
// BladeCAPTCHA/config/config.php
define('CAPTCHA_SECRET_KEY', '3b7e151628aed2a6abf7158809cf4f3c');
define('CAPTCHA_DIFFICULTY', 4);
define('CAPTCHA_EXPIRY', 300); // 5 minutos

// Configuración CORS para peticiones AJAX desde frontend
$config['cors_enabled'] = true; // Activar/desactivar manejo CORS
$config['cors_allowed_origins'] = [ // Orígenes permitidos para CORS (no usar '*')
    'http://localhost',
    'http://127.0.0.1',
    'http://[::1]'
];
$config['cors_allow_credentials'] = true; // Permitir cookies y credenciales CORS

Parámetros disponibles:

• CAPTCHA_SECRET_KEY: Clave secreta utilizada para firmar y validar desafíos.
• CAPTCHA_DIFFICULTY: Dificultad inicial del desafío PoW (número de ceros iniciales en el hash).
• CAPTCHA_EXPIRY: Tiempo de expiración del desafío PoW (en segundos).
• cors_enabled: (bool) Activar el soporte para CORS.
• cors_allowed_origins: (array) Lista de orígenes permitidos para solicitudes CORS. No usar '*' por seguridad y compatibilidad con credenciales.
• cors_allow_credentials: (bool) Permitir envío de cookies o tokens en las solicitudes CORS.

Si no se define CAPTCHA_SECRET_KEY, no se podrá validar ningún token.

require_once __DIR__ . '/captcha-lib.php';
use function Captcha\validateToken;

<?php
// BladeCAPTCHA/public/php/procesar-formulario.php
require_once __DIR__ . '/captcha-lib.php';
use function Captcha\validateToken;

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('Método no permitido');
}

// Sanitiza y valida el token del captcha (entrada siempre como string)
$token = trim((string)($_POST['captcha_token'] ?? ''));

function render($msg) {
    exit("<!DOCTYPE html><meta charset='UTF-8'><body>$msg</body>");
}

// Validar formato y autenticidad
if (!preg_match('/^[a-f0-9]{32}$/i', $token) || !validateToken($token)) {
    render('❌ CAPTCHA inválido.');
}

if (!isset($_POST['nombre'])) {
    render('❌ Falta el campo "nombre".');
}

// ✅ CAPTCHA válido
echo "<!DOCTYPE html><meta charset='UTF-8'><body><h1>CAPTCHA correcto</h1><pre>";
foreach ($_POST as $k => $v) {
    printf("<strong>%s:</strong> %s\n",
        htmlspecialchars($k, ENT_QUOTES, 'UTF-8'),
        htmlspecialchars((string)$v, ENT_QUOTES, 'UTF-8')
    );
}
echo "</pre></body>";