🧩 BladeCAPTCHA

MIT 9 KB No tracking

This page details how to integrate and configure BladeCAPTCHA on your website.

📦 Requirements

• Browser supporting Web Workers and JavaScript ES6 Modules (guaranteed compatibility with modern browsers such as Chrome, Firefox, Edge, and Safari).
• Server capable of serving static files and running PHP 8.0+, with the following extensions installed: openssl, mbstring, and json.

📁 Installation

1. Download the full package from GitHub or clone the repository.
2. Upload the contents to your server.
3. Rename config/config.sample.php to config/config.php and edit the CAPTCHA_SECRET_KEY value, which is the secret key used to validate tokens. (More info about this configuration here.)

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

🚀 Basic usage

Import the captcha.js module and call initCaptcha() with the desired configuration:

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

⚙️ Configuration (initCaptcha)

The initCaptcha(options) function accepts the following parameters:

🔀 Example: autoFormIntegration

▶️ View 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 = 'Verifying...';
      },
      onEnd: () => {
        document.querySelector('#submitBtn').textContent = 'Submit';
      }
    });
  } catch (err) {
     console.error(err || err.message);
  }
})();
</script>

🖐️ Example: manualHandling

▶️ View 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('Starting verification...');
      },
      onEnd: () => {
        console.log('Verification canceled or completed.');
      },
      onProgress: (p) => {
        console.log(`Progress: ${p}%`);
      }
    });
  } catch (err) {
    console.error(err || err.message);
  }
})();
</script>

💡 Auxiliary variables and shared context

When using initCaptcha as an imported ES6 module, each function call runs in an isolated environment and internal variables are not accessible externally. Therefore, if you need to preserve information between callbacks—like the original text of a button before changing it—you should define an auxiliary variable in your code and explicitly use it in the functions passed in the configuration.

▶️ View demo

import { initCaptcha } from './captcha.js'; // or correct path

// Define memo in the module or script context
let memo = null; // Auxiliary variable for onStart and onEnd

(async () => {
  try {
    await initCaptcha({
      // other parameters...
      onStart: () => {
        const btn = document.querySelector('#submitBtn');
        memo = btn.textContent;  // save original text in memo
        btn.disabled = true;
        btn.style.cursor = 'wait';
        btn.textContent = 'Please wait...';
      },
      onEnd: () => {
        const btn = document.querySelector('#submitBtn');
        btn.textContent = memo;  // restore original text from memo
        btn.disabled = false;
        btn.style.cursor = 'pointer';
      }
    });
  } catch (err) {
    console.error(err || err.message);
  }
})();

🔄 Example: autoFormIntegration with multiple forms

▶️ View demo

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

// Array of form selectors that will use BladeCAPTCHA
const forms = ['#contactForm', '#loginForm', '#newsletterForm'];

forms.forEach(async (formSelector) => {
  // Auxiliary variable to store the original submit button text
  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 = 'Verifying...';
        btn.disabled = true;
        btn.style.cursor = 'wait';
      },
      onEnd: () => {
        const btn = document.querySelector(`${formSelector} button[type="submit"]`);
        if (!btn) return;
        btn.textContent = memo || 'Submit';
        btn.disabled = false;
        btn.style.cursor = 'pointer';
      }
    });
  } catch (err) {
    console.error(err || err.message);
  }
});
</script>

🔧 Key technical features

📁 Configuration file (PHP)

BladeCAPTCHA allows defining some general behavior parameters from a simple PHP file.

This file defines constants and configuration variables used by the library during token validation. For security reasons, it is recommended to place it outside the public directory (e.g., in BladeCAPTCHA/config/config.php).

Example:

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

// CORS configuration for AJAX requests from frontend
$config['cors_enabled'] = true; // Enable/disable CORS handling
$config['cors_allowed_origins'] = [ // Allowed origins for CORS (do not use '*')
    'http://localhost',
    'http://127.0.0.1',
    'http://[::1]'
];
$config['cors_allow_credentials'] = true; // Allow cookies and CORS credentials

Available parameters:

• CAPTCHA_SECRET_KEY: Secret key used to sign and validate challenges.
• CAPTCHA_DIFFICULTY: Initial difficulty of the PoW challenge (number of leading zeros in the hash).
• CAPTCHA_EXPIRY: Expiration time of the PoW challenge (in seconds).
• cors_enabled: (bool) Enable CORS support.
• cors_allowed_origins: (array) List of allowed origins for CORS requests. Do not use '*' for security and credential compatibility.
• cors_allow_credentials: (bool) Allow sending cookies or tokens in CORS requests.

If CAPTCHA_SECRET_KEY is not defined, no token can be validated.

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

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

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('Method not allowed');
}

// Sanitize and validate the captcha token (always as string)
$token = trim((string)($_POST['captcha_token'] ?? ''));

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

// Validate format and authenticity
if (!preg_match('/^[a-f0-9]{32}$/i', $token) || !validateToken($token)) {
    render('❌ Invalid CAPTCHA.');
}

if (!isset($_POST['name'])) {
    render('❌ Missing "name" field.');
}

// ✅ Valid CAPTCHA
echo "<!DOCTYPE html><meta charset='UTF-8'><body><h1>CAPTCHA correct</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>";