Lightweight, Self-Hosted CAPTCHA Solution – xsukax JS CAPTCHA

Preview:

Description:

xsukax JS CAPTCHA is a JavaScript library that generates canvas-based verification challenges to protect your web forms from automated bot submissions.

The library works entirely in the browser without external API calls, third-party tracking, or server-side dependencies.

It creates visually distorted alphanumeric codes using HTML5 Canvas, automatically integrates with existing HTML forms, and handles the complete verification workflow from challenge generation to token-based validation.

It’s great developers who need bot protection without the privacy concerns, recurring costs, or integration complexity of services like reCAPTCHA or hCaptcha.

Features:

• Canvas-based rendering: Generates dynamic, distorted text challenges using HTML5 Canvas API with multiple layers of visual obfuscation.
• Automatic form integration: Detects and attaches to parent forms automatically, preventing submission until verification.
• Privacy-first architecture: No data collection, tracking cookies, or external API calls. Fully GDPR and CCPA compliant.
• Customizable configuration: Adjustable challenge length, timeout durations, and character sets through a simple configuration object.
• Cross-browser compatible: Works on all modern browsers, including Chrome, Firefox, Safari, and Edge.
• Accessibility: Includes refresh functionality and clear status messages for improved usability.
• Token-based verification: Generates secure tokens for server-side validation with time-limited expiration.

Use Cases:

• Form Protection for Static Sites: Static websites built with Jekyll, Hugo, or plain HTML can add bot protection without backend server requirements or authentication systems.
• Privacy-Sensitive Applications: Healthcare portals, legal forms, or applications handling sensitive data can implement verification without exposing user information to third-party CAPTCHA providers.
• High-Volume Forms Without API Costs: Contact forms, registration pages, or survey systems that receive significant traffic can avoid per-request charges associated with commercial CAPTCHA services.
• Internal Business Applications: Corporate intranets, employee portals, or offline-capable web applications can implement verification without internet connectivity dependencies after initial page load.

How To Use It:

1. Import the xsukax JS CAPTCHA library into your web project.

<!-- CDN -->
<script src="https://xsukax.github.io/xsukax-JS-CAPTCHA/captcha.js"></script>
<!-- self-hosted -->
<script src="/captcha.js"></script>

2. Insert a div element with the class xsukax-captcha inside your form element. The library will initialize automatically when the DOM loads.

<form action="/submit" method="POST">
  ... Form Fields Here
  <div class="xsukax-captcha"></div>
  <button type="submit">Submit Button</button>
</form>

3. When forms submit successfully, the library automatically inserts a hidden input field containing a unique token:

<input type="hidden" name="xsukax_captcha_token" value="[32-character-token]">

This is a client-side implementation, so the verification occurs in the browser. For production deployments, implement additional server-side protections:

• Rate limiting based on IP address or session
• Honeypot fields that bots typically fill but humans leave empty
• Request timing analysis to detect automated submissions
• Server-side token validation against expected format
• CSRF token verification for form submissions

The client-side token provides basic protection but can be bypassed by sophisticated bots that execute JavaScript. Combine this with server-side validation for robust security.

4. For more complex scenarios, you can interact with the CAPTCHA instances via a global API. This is useful for single-page applications or forms that use AJAX for submission.

You can assign a custom ID to your container for easier targeting.

<div id="contact-form-captcha" class="xsukax-captcha"></div>

Then, you can access its state from your own scripts.

// Check if a specific CAPTCHA is verified before an AJAX submit
const isVerified = window.xsukaxCAPTCHA.isVerified('contact-form-captcha');
if (isVerified) {
    // Proceed with form submission
} else {
    // Show an error to the user
}
// You can also reset all instances on the page
window.xsukaxCAPTCHA.resetAll();

Alternatives:

• Google reCAPTCHA: The most widely deployed CAPTCHA solution that uses checkbox verification or image selection challenges, but requires Google API integration, collects user data for risk analysis, and depends on external service availability.
• hCaptcha: Privacy-focused commercial alternative that offers similar functionality to reCAPTCHA with better privacy policies and revenue sharing for site owners, though it still requires external API calls and processes user interaction data.

FAQs:

Q: Can I customize the canvas appearance to match my site design?
A: The canvas rendering logic lives in the source code, so you can modify colors, fonts, and distortion parameters directly in the captcha.js file. Look for the canvas drawing functions that set fillStyle, strokeStyle, and font properties. The surrounding UI elements (input field, buttons, messages) use CSS classes that you can override in your stylesheet. For example, target .xsukax-captcha input to style the input field or .xsukax-captcha button for the verify button.

Q: What happens if a user has JavaScript disabled in their browser?
A: The CAPTCHA won’t render at all since it’s entirely JavaScript-based. You need a fallback strategy for these users. Consider implementing a server-side honeypot field or alternative verification method. You can detect JavaScript availability and show a message instructing users to enable JavaScript, or provide an alternative contact method like email or phone for the small percentage of users without JavaScript.

Q: Can bots with JavaScript execution capabilities bypass this CAPTCHA?
A: Yes, sophisticated bots using headless browsers like Puppeteer or Playwright can potentially bypass client-side CAPTCHAs by executing JavaScript and interacting with the DOM. This is a fundamental limitation of any client-side verification system. For high-security applications, combine this with server-side protections like rate limiting by IP, behavioral analysis, and request fingerprinting. The library works well for blocking simple form submission bots but shouldn’t be your only defense against automated attacks.