=== HashCash - Proof of Work CAPTCHA ===
Contributors: richeyweb
Donate link: https://www.paypal.com/donate/?hosted_button_id=BTL9WZ8NU56RC
Tags: proof of work, antispam, anti-spam, captcha, contact form 7
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.10
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Invisible Proof-of-Work CAPTCHA. No checkboxes, no image grids, no Google, no tracking. Just spam protection that gets out of the way.

== Description ==

https://www.youtube.com/watch?v=HbzP1NsaiwI

**HashCash** stops spam by making the visitor's browser do the work — not the visitor.

While your user fills out a form, HashCash runs a cryptographic proof-of-work calculation silently in the background. By the time they hit Submit, the work is done. No checkbox to click. No images to identify. No third-party service watching over their shoulder.

This is the WordPress port of a Joomla plugin with a 12-year track record — originally released three years before Google launched reCAPTCHA v3. The core idea hasn't changed: spam protection should be invisible to real users and brutal to bots.

**What makes HashCash different:**

* **No third-party services.** No reCAPTCHA, no hCaptcha, no Cloudflare Turnstile. Nothing phones home.
* **No tracking, no cookies.** GDPR and CCPA friendly by design, not by policy.
* **Nothing for users to solve.** A brief "Securing this form..." indicator appears while the calculation runs — that's it. No puzzles, no clicks, no friction.
* **Logged-in users are exempt.** Trusted users never see the indicator at all.
* **Adjustable difficulty.** SHA-256 at level 1 by default for maximum compatibility. Argon2id available for sites that need state-of-the-art memory-hard hashing.
* **Bot punishment mode.** Suspicious behavior triggers difficulty so high the proof-of-work becomes computationally unsolvable. The bot spins forever. Legitimate users never notice.
* **Automatic protection.** Works out of the box on WordPress comments, login, registration, lost password, and Contact Form 7. No configuration required.

**Supported hash algorithms:**
* SHA-256 (default — fast, broadly compatible)
* SHA-384 / SHA-512
* PBKDF2
* PBKDF2 (64KB)
* Argon2id (recommended for maximum security — requires PHP sodium extension)

**Works automatically with:**
* WordPress comment forms
* WordPress login form
* WordPress registration form
* WordPress lost password form
* Contact Form 7

**Add to any other form:**

Use the shortcode `[hashcash]` to add protection to any form on your site.

== Installation ==

1. Upload the `captcha-hashcash` folder to `/wp-content/plugins/`
2. Activate through the **Plugins** menu in WordPress
3. Go to **Settings → HashCash** to review defaults
4. Done. All supported forms are protected automatically.

No API keys. No account required. No third-party setup.

== Frequently Asked Questions ==

= Does this replace reCAPTCHA / hCaptcha? =

Yes. HashCash requires no third-party service, no API key, and sends no data to external servers. If you're using reCAPTCHA or hCaptcha specifically to avoid tracking your users, HashCash is a direct replacement.

= What does the user actually see? =

While the proof-of-work calculation runs, a brief "Securing this form..." message appears and the submit button is temporarily disabled. When the calculation completes — usually within seconds at default settings — the button re-enables and the indicator disappears. There is nothing for the user to click, solve, or interact with.

= Do logged-in users see the indicator? =

No. Logged-in users are exempt from HashCash verification entirely.

= Will it slow down my site? =

No. The proof-of-work calculation runs in a Web Worker (a background browser thread) and only starts when the user interacts with the form. Your page load time is not affected.

= What is Argon2id and should I use it? =

Argon2id is the current gold standard for memory-hard cryptographic hashing — it's specifically designed to be expensive for bots running at scale while remaining fast enough for individual users. It requires the PHP sodium extension (available by default in PHP 7.2+). If your server supports it, it's the strongest option available. SHA-256 remains the default for maximum compatibility.

= What is "bot punishment mode"? =

When suspicious behavior is detected (automated form submission patterns, headless browsers, CDP runtime signatures), HashCash can either silently fail or make the proof-of-work impossible to solve. Punishment mode chooses the latter — the bot wastes significant compute resources without knowing it was detected, while legitimate users are unaffected.

= Does it work with Contact Form 7? =

Yes, automatically. If the user is not logged in, HashCash is injected into every CF7 form without any configuration. You can also use the `[hashcash]` shortcode for manual placement.

= Is it accessible? =

Yes. The indicator is visual feedback only — it does not interfere with screen readers or keyboard navigation. There is no interactive challenge of any kind.

= What happens if the proof-of-work expires? =

Each proof-of-work calculation is timestamped. On submission, the server verifies that timestamp is within 30 minutes of the current time — this prevents replay attacks, where a bot captures a valid solution and reuses it repeatedly. HashCash automatically refreshes the calculation before it expires, so users who leave a form open for an extended period never encounter a validation failure on submission.

= Is this related to the original HashCash email anti-spam system? =

Yes. HashCash as a concept dates to 1997 — it was originally designed to combat email spam using proof-of-work. This plugin applies the same principle to web forms, using modern cryptographic algorithms where the original used SHA-1.

== Screenshots ==

1. Settings page — adjust difficulty, algorithm, and behavior options
2. Form protection in action — brief indicator, no user interaction required

== Changelog ==

= 1.0.2 =
* Argon2id support added — state-of-the-art memory-hard hashing via PHP sodium extension
* Smart proof-of-work refresh — automatically re-mines before expiration
* Improved bot detection — CDP runtime detection, headless browser fingerprinting
* Contact Form 7 automatic integration

= 1.0.1 =
* Bug fix: shortcode name attribute

= 1.0.0 =
* Initial WordPress release
* Ported from Joomla HashCash (12-year track record)
* SHA-256, SHA-384, SHA-512, PBKDF2 support
* Automatic protection for comments, login, registration, lost password
* Bot punishment mode
* Adjustable difficulty (1–12)

== Upgrade Notice ==

= 1.0.2 =
Adds Argon2id support and smart proof-of-work refresh. Recommended for all users.

== Support ==

For support, feature requests, or custom integrations:
https://www.richeyweb.com/

HashCash for WordPress is maintained by Michael Richey — author of the original Joomla HashCash plugin, with over 12 years of proof-of-work CAPTCHA development.