Documentation

5.2.17 Overview

Finally, a CAPTCHA you can’t read—because you don’t need to! Captcha - HashCash is the CAPTCHA that works behind the scenes, invisible to users and relentless against bots.

Say goodbye to the frustration of squinting at distorted text or matching blurry photos. HashCash takes a different approach: it’s a client-side validation plugin for Joomla that doesn’t rely on third-party services, external resources, or user effort beyond a JavaScript-enabled browser. No mangled words, no math puzzles, no photo grids—just seamless form protection that kicks in the moment a user lands on your page.

First proposed by Adam Back in 1997, HashCash uses a proof-of-work system where the client must solve a complex SHA-256 hash calculation. At its default difficulty (level: 3), this takes hundreds or thousands of attempts, taxing any bot or human abuser enough to make spamming unprofitable. The server verifies the result in a single, lightning-fast check—correct, and the form proceeds; incorrect, and it’s rejected. For detected bots, the optional punish mode cranks the difficulty to an unsolvable level: 32, effectively locking them out.

HashCash runs invisibly in the background, triggered automatically on form load or user interaction (configurable via Delay Start). It combines this computation with a nine-check gauntlet to sniff out bots—everything from fake events to headless browser signatures. An optional nonce trap adds another layer, catching stealth bots that tamper with a hidden field. The result? Your users experience nothing but a smooth form, while bots hit a computational wall.

Installation

1. Download HashCash: Grab the latest version from the RicheyWeb download page. This link may shift over time, so head to http://www.richeyweb.com and search for "HashCash" to find it.
2. Navigate to Joomla Admin: In your Joomla /administrator, go to Extensions > Manage > Install.
3. Upload the File: Select the Upload Package File tab, click Choose File to locate the downloaded plugin, and hit Upload & Install.
4. Enable the Plugin: The extension is now installed but disabled. Go to Extensions > Plugins, search for "HashCash," and open it to configure and enable.

Configuration

Configuring HashCash is straightforward—open the plugin in the Joomla Plugin Manager and tweak these options:

1. Difficulty Level:
   • Sets the number of leading zeros required in the hash (default: 3). Options range from 1 (easiest) to 4 (hardest), balancing bot deterrence with quick computation times—typically milliseconds at level 3.
   • Recommended level 3.  This balances speed with security.  It's not too easy that there's no computational cost, and it's not so hard that it takes more than a few seconds to run.  On a 4-core (8-thread) 2.8GHz Xeon E3-1505M it takes between 5 and 30 seconds to solve a level 4 hash.  Higher difficulty levels lead to longer waits.
   • Default level 3.
2. Delayed Start:
   • When enabled, the HashCash calculation does not begin until the user interacts with the form.  They must type something, click a radio button or checkbox, select something from a select list - whatever it is, they must interact before the calculation begins.
   • This enables all other advanced functionality below.
3. Decorate Known Forms:
   • Known forms are modified on page load to disable the submit button and replace its text with a BS5 spinner and "Loading..." text.  Upon successful calculation, the button is returned to its original state.
   • Find instructions to decorate other forms below.  Let me know if you'd like your decorator added to the plugin.
   • Supported Forms:
     • com_contact.contact (Joomla Contact Form)
     • com_users.registration (Joomla User Registration Form)
     • com_users.remind (Joomla Username Reminder Form)
     • com_users.reset (Joomla Password Reset Form)
4. Enable CDP Runtime Test:
   • Headless bots may be using the Chrome DevTools Protocol (CDP), which can be detected if no countermeasures are used.
   • This is disabled by default, because some developers may have this extension running on their developers.  It's an edge case that can cause false-positives in the bot detection. This bot detection is logged in the JavaScript console if caught by the plugin.
   • Disabled by default.
5. Enable Nonce Test:
   • Bots that are not specifically programmed to ignore this field might be caught manipulating it. 
   • Safe to enable, disabled by default.
6. Trigger JS Event:
   • Users who want to track bot detection can enable this, and implement some method to collect the data.
   • Example Google Analytics tracking is detailed in the article Tracking Spam Bots Like a Pro with GA and HashCash
7. Punish Bots:
   • Bots who are identified by the plugin can be forced to initiate an impossible hashing task.
   • Enabling this is recommended.
   • Disabled by default

Decorate Your Form

To decorate your form, you will need to know the form context (the option and the view), for example option=com_contact&view=contact and create a javascript file.

When correctly named (option.view.js and option.view.min.js) is present in /media/plg_captcha_hashcash/js - the plugin will automatically load it when in that form context.  See /media/plg_captcha_hashcash/js/com_contact.contact.js for an example.

Basic JavaScript structure:

const plg_captcha_hashcash_option_view_class = function() {
    const root = this;
    const construct = function() {
        // do stuff to decorate the form
        window.addEventListener('plg_captcha_hashcash_finished', () => {
            // do stuff to un-decorate the form
        });
    }
    construct();
}
window.addEventListener('DOMContentLoaded', () => {
    new plg_captcha_hashcash_option_view_class();
});