README

A local Proof-of-Work CAPTCHA extension for Flarum that protects login, registration and password-reset forms without relying on any external service (no Cloudflare, no Google reCAPTCHA, no cookies).

How it works

1. When an auth modal opens, the browser silently fetches a one-time challenge from the Flarum API.
2. The browser solves a SHA-256 hash puzzle (finds a nonce N such that SHA-256(challenge:N) starts with D hex zeros, where D is the configured difficulty).
3. The solution token challenge:nonce is appended to the form submission.
4. The server verifies the solution and rejects the request if the check fails.

Bots must solve the same puzzle for every request; legitimate users complete it invisibly in the background (< 100 ms at the default difficulty).

Features

• 🔒 No external services – fully self-hosted
• ⚡ Invisible to users – solved automatically while they fill the form
• ⚙️ Configurable difficulty – 3 levels (~100 ms → ~10 s)
• 🌓 Dark / light mode – widget adapts to Flarum's current theme
• 🌍 Italian & English – auto-detected; add more locales in locale/
• 🔁 Replay-proof – each challenge is single-use (stored in Flarum's cache)
• ✅ Flarum 1.x and 2.x compatible

Requirements

Screenshot

Disclaimer

This software is provided "AS IS", without any warranty. While it has been tested and reasonable efforts are made to ensure security and reliability, no guarantees are provided. As an open project, anyone may contribute or report issues, but this does not imply endorsement or liability from the maintainers.

You use this software entirely at your own risk. The authors and contributors are not liable for any damages, data loss, or unexpected behavior resulting from its use, modification, or distribution. Always review and test the code independently before deploying it in critical or production environments.

Installation

composer require peopleinside/fla-powcaptcha

composer require peopleinside/fla-powcaptcha:2.3

Update

composer update peopleinside/fla-powcaptcha

How to remove

composer remove peopleinside/fla-powcaptcha

Then enable the extension in the Flarum admin panel.

Configuration

Go to Admin → Extensions → PoW CAPTCHA and choose:

Development (for contributors only)

The extension is distributed with pre-compiled frontend assets (js/dist/*), so no JS build step is required to install or use it on Flarum 2.x.

After upgrading from an older release on Flarum 1.8, rebuild the forum bundle so auth modals are extended correctly:

cd vendor/peopleinside/fla-powcaptcha/js
npm install
npm run build
php flarum cache:clear

Security Notes

• Each challenge is valid for 5 minutes and is single-use (deleted after successful verification).
• The challenge is a 128-bit cryptographically random value; it cannot be guessed or forged.
• The server independently re-computes the SHA-256 hash to verify the solution.

Running Behind a Reverse Proxy / Load Balancer

Challenges and tokens are bound to the visitor's IP address. If your Flarum instance sits behind a reverse proxy or load balancer that does not populate REMOTE_ADDR with the real client IP, you must set one of the following keys in your config.php so Flarum (and this extension) can resolve the correct IP from forwarded headers:

• 'proxy_headers' => true (or an explicit list of trusted proxy IPs), or
• 'proxy_all' => true

If neither is set and the server also can't fall back to REMOTE_ADDR, IP resolution returns empty and this extension will reject all challenge requests with a 429 to fail safe. A warning is logged in that case ([fla-powcaptcha] ...) — check your Flarum log if users report being unable to log in, register, or reset their password.

License

Apache-2.0