=== HSArticle Math CAPTCHA for Forms ===
Contributors: hsarticle
Tags: captcha, spam, contact form 7, wpforms, bot protection
Requires at least: 5.5
Tested up to: 7.0
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Math CAPTCHA for CF7, WPForms, and any HTML form. Zero config — install, add shortcode or use auto inject from settings.

== Description ==

HSArticle Math CAPTCHA for Forms adds a math CAPTCHA to any WordPress form. No API keys. No third-party services. No configuration needed to get started.

**Features:**

* Math CAPTCHA — addition, subtraction, multiplication with sensible number ranges
* Two display modes: distorted canvas image (bot-resistant) or plain text (accessible)
* Server-side validation — answer stored in PHP session with HMAC signature, never exposed to the client
* Honeypot field — silent bot trap alongside the math challenge
* Rate limiting — blocks IPs after 10 failed attempts per 10 minutes
* Refresh button — generate a new question without reloading
* WPForms auto inject — protect any WPForms (free or pro) without adding a shortcode
* Registered as a CF7 form tag — no unknown tag warnings in the CF7 editor
* Session only starts on pages that actually contain a form — no impact on page caching elsewhere
* Clean admin page under its own menu — not buried under Settings

**Supported form plugins:**

* Contact Form 7
* WPForms (Free and Pro)
* Any HTML form via the [hs_mcf_captcha] shortcode

== Installation ==

1. Upload the plugin folder to /wp-content/plugins/
2. Activate via the Plugins menu
3. Go to Math CAPTCHA in the left admin menu
4. Choose display mode and configure WPForms auto inject if needed

**Contact Form 7:** In the form editor add [hs_mcf_captcha] before [submit]

**WPForms Free:** Go to Math CAPTCHA settings and tick the forms you want to protect

**WPForms Pro:** Add an HTML field and paste [hs_mcf_captcha], or use auto inject

**Any HTML form:** <?php echo do_shortcode('[hs_mcf_captcha]'); ?>

== Frequently Asked Questions ==

= Does this need an API key? =
No. Fully self-hosted, no external services.

= Does it work with WPForms free? =
Yes. Use the auto inject option in plugin settings — no HTML field required.

= Is it GDPR friendly? =
Yes. No data is sent to third parties. The answer is stored in a server-side PHP session only and cleared immediately after validation.

= Does it affect page caching? =
The plugin only starts a PHP session on pages that actually render a form. Pages without a form are not affected. For pages with forms, you should exclude them from full-page caching in your caching plugin (WP Rocket, W3 Total Cache, LiteSpeed Cache, etc.) to ensure the CAPTCHA field ID matches the session. This is standard practice for any form page.

= What if PHP sessions are disabled on my host? =
Most shared hosts have PHP sessions enabled. If CAPTCHA validation always fails, ask your host to confirm sessions are available. Some managed hosts (such as WP Engine) restrict native PHP sessions — contact their support to enable session handling.

= Can bots bypass this? =
Sophisticated bots that render JavaScript and solve math can bypass any math CAPTCHA. This plugin stops the vast majority of spam bots which are simple automated form fillers. Additional layers (honeypot field and IP rate limiting) are built in. For high-security forms consider combining with Cloudflare Turnstile or hCaptcha.

== Changelog ==

= 1.0.0 =
* Initial release
