=== CaptchaFlow – CAPTCHA & Spam Protection for Forms ===
Contributors: templatesell
Tags: captcha, spam protection, recaptcha, turnstile, anti-spam
Requires at least: 6.5
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Protect Contact Form 7, WPForms, WooCommerce, login, comments and more with Cloudflare Turnstile, reCAPTCHA, hCaptcha, or no-signup challenges.

== Description ==

🛡️ **Stop form spam across your whole site with one switch**

**CaptchaFlow** protects every form on your WordPress site with one switch. Choose a CAPTCHA provider — or a self-hosted challenge that needs no signup at all — and CaptchaFlow attaches it to your login page, comment form, checkout, and every supported form plugin automatically. No template editing, no per-form configuration, no code.

🔗 [Plugin home](https://templatesell.net/captchaflow/) · [All features](https://templatesell.net/captchaflow/features/) · [Documentation](https://templatesell.net/captchaflow/docs/) · [FAQ](https://templatesell.net/captchaflow/faq/) · [Changelog](https://templatesell.net/captchaflow/changelog/)

= ✨ Why choose CaptchaFlow? =

🧩 **Every Form, One Switch** – CaptchaFlow detects the forms on your site and protects them all. New forms are covered the moment you create them.

🪤 **Three Layers on Every Submission** – A honeypot field with a randomized name, a time trap that catches inhumanly fast submissions, and your chosen challenge. Obvious bots are rejected by the first two layers without ever reaching your provider, which keeps your pages fast and your provider quota low.

🎛️ **Six Challenge Types** – Cloudflare Turnstile, Google reCAPTCHA v2 and v3, hCaptcha, or a self-hosted Math or Question challenge that needs no account at all.

⚡ **Built for Fast Sites** – Zero assets on pages without a protected form, a dependency-free public script under 3 KB compressed, and under 5 ms of server time per verification.

🗄️ **Works With Page Caching** – Challenge data is never baked into cached HTML, so a cached page stays correct for every visitor.

🔒 **Privacy First** – No telemetry, no account, and nothing sent to us. IP addresses are shortened before logging and email addresses stored only as one-way hashes.

🩺 **Diagnostics You Can Trust** – One click tests your keys, latency, REST, cron, and cache setup, and warns you before another plugin double-injects a CAPTCHA.

🌍 **Translation Ready** – Every string is translatable, a POT file ships with the plugin, and the admin fully supports RTL languages.

♿ **Accessible by Default** – Challenges are keyboard-operable, labelled for screen readers, and respect reduced-motion preferences. The no-JavaScript fallback is plain accessible HTML.

🧑‍💻 **Developer Friendly** – Documented hooks and filters, a PHP SDK for custom forms, and a CSS-selector adapter for anything hand-built.

= 📋 Supported forms =

* WordPress login, registration, password reset, and comments
* WooCommerce login, registration, and password reset
* Contact Form 7
* WPForms
* Fluent Forms
* Forminator
* Ninja Forms
* Gravity Forms
* Elementor Pro forms
* Any other form, via a CSS selector

= 🔐 Supported challenges =

* **Cloudflare Turnstile** — free, privacy-friendly, usually invisible (recommended)
* **Google reCAPTCHA v2** — the familiar checkbox
* **Google reCAPTCHA v3** — invisible, score-based
* **hCaptcha** — privacy-focused alternative
* **Math challenge** — a simple sum; no account, no external service
* **Question challenge** — your own question and answer; no external service

= ⏱️ 60-second setup =

Activate the plugin, pick a challenge in the setup wizard, paste your keys (or skip that step with a self-hosted challenge), and you are protected. The wizard ends with a live test so you can see your site issuing challenges before you close it.

Step-by-step guides for every provider are in the [documentation](https://templatesell.net/captchaflow/docs/).

= 🔏 Privacy first =

CaptchaFlow sends no data to us — there is no phoning home, no telemetry, and no account. The only external requests are the verification calls to the CAPTCHA provider you choose, and the self-hosted Math and Question challenges make no external requests at all. Visitor email addresses are stored only as one-way hashes in your own database, and the event log trims itself on the schedule you set.

Visitor IP addresses are shortened to the network they came from before they are logged — enough to spot a flood from one place, not enough to single out a person. You can turn that off if you need exact addresses for investigating abuse. CaptchaFlow also writes suggested wording for your privacy policy that describes your actual configuration, and plugs into Tools → Export Personal Data and Erase Personal Data so a visitor's request covers the spam log too.

CaptchaFlow uses the official public APIs of Cloudflare Turnstile, Google reCAPTCHA, and hCaptcha. Those names are trademarks of their respective owners; CaptchaFlow is not affiliated with or endorsed by Cloudflare, Google, or Intuition Machines.

= 🩺 Diagnostics you can trust =

One click runs a full self-test: provider reachability and key validity with round-trip latency, REST availability, cron health, cache-plugin detection with copy-paste exclusion rules, and a curated list of plugins known to double-inject CAPTCHAs. Export the whole report as text and attach it to a support ticket.

= 🚀 CaptchaFlow Pro =

Everything above is free and stays free. Pro is for sites where spam has stopped being accidental — [see the full comparison and pricing](https://templatesell.net/captchaflow/pricing/).

🚦 **Rate Limiting & IP Firewall** – Throttle repeat submitters with a sliding window, and block or allow individual addresses and whole countries.

📧 **Email & Phone Validation** – Reject disposable mailboxes and malformed numbers before they reach your inbox or your CRM.

🧠 **Behaviour Analysis & Spam Scoring** – Every submission is scored on how it was filled in, so borderline cases are challenged instead of silently allowed.

🌐 **Country Rules & Conditional Challenges** – Ask for a harder challenge only where abuse actually comes from, and leave everyone else undisturbed.

🛒 **WooCommerce Checkout & Review Protection** – Extends protection to checkout and product reviews, where store spam actually costs you money.

📊 **Analytics, Alerts & Health Reports** – See what is being blocked and why, and get told when something changes rather than finding out later.

🔌 **Developer API, Webhooks & White Label** – Hook verification into your own systems, and hand clients a plugin that carries your name.

💡 **Recommendations & Auto-Optimization** – CaptchaFlow watches its own results and suggests the settings that would block more with less friction.

Every Pro plan includes a 14-day trial with no card required.

== External services ==

CaptchaFlow contacts an external service only when you have chosen a challenge that is hosted by one — Cloudflare Turnstile, Google reCAPTCHA v2, Google reCAPTCHA v3, or hCaptcha. If you choose the Math or Question challenge, CaptchaFlow makes no external requests at all and nothing on this list applies to your site.

CaptchaFlow itself is not a service. It has no servers, no account, and no telemetry: nothing is ever sent to CaptchaFlow or to TemplateSell.

= Cloudflare Turnstile =

Used only when Turnstile is the selected challenge.

* The visitor's browser loads the challenge widget from https://challenges.cloudflare.com/turnstile/v0/api.js on any page showing a protected form. Cloudflare receives whatever a browser sends when requesting a script, including the visitor's IP address and user agent.
* When the form is submitted, your server sends the challenge token, your Turnstile secret key, and the visitor's IP address to https://challenges.cloudflare.com/turnstile/v0/siteverify to ask whether the challenge was passed. The request identifies your site in its user-agent string.
* The same verification endpoint is called with a dummy token when you test your keys on the Provider screen.

Terms of service: https://www.cloudflare.com/website-terms/ — Privacy policy: https://www.cloudflare.com/privacypolicy/

= Google reCAPTCHA (v2 and v3) =

Used only when reCAPTCHA v2 or v3 is the selected challenge.

* The visitor's browser loads the challenge widget from https://www.google.com/recaptcha/api.js on any page showing a protected form. Google receives whatever a browser sends when requesting a script, including the visitor's IP address and user agent, and reCAPTCHA additionally observes visitor interaction in order to score the request.
* When the form is submitted, your server sends the challenge token, your reCAPTCHA secret key, and the visitor's IP address to https://www.google.com/recaptcha/api/siteverify to ask whether the challenge was passed. The request identifies your site in its user-agent string.
* The same verification endpoint is called with a dummy token when you test your keys on the Provider screen.

Terms of service: https://policies.google.com/terms — Privacy policy: https://policies.google.com/privacy

= hCaptcha =

Used only when hCaptcha is the selected challenge.

* The visitor's browser loads the challenge widget from https://js.hcaptcha.com/1/api.js on any page showing a protected form. hCaptcha receives whatever a browser sends when requesting a script, including the visitor's IP address and user agent.
* When the form is submitted, your server sends the challenge token, your hCaptcha secret key, and the visitor's IP address to https://api.hcaptcha.com/siteverify to ask whether the challenge was passed. The request identifies your site in its user-agent string.
* The same verification endpoint is called with a dummy token when you test your keys on the Provider screen.

Terms of service: https://www.hcaptcha.com/terms — Privacy policy: https://www.hcaptcha.com/privacy

Cloudflare, Google, and hCaptcha are trademarks of their respective owners. CaptchaFlow is not affiliated with or endorsed by Cloudflare, Google, or Intuition Machines, and uses only each provider's official public API.

== Installation ==

1. Install and activate CaptchaFlow from the Plugins screen.
2. The setup wizard opens automatically. Choose a challenge — Cloudflare Turnstile if you want the least visitor friction, or the Math challenge if you don't want to create any account.
3. Paste your site key and secret key if your challenge needs them. They are tested the moment you paste them.
4. Leave "Protect every form" on, finish, and watch the live test pass.

That is the whole setup. To fine-tune, the Forms screen lets you protect sources individually, and the Provider screen lets you switch challenges at any time.

== Frequently Asked Questions ==

= Do I need a CAPTCHA account? =

No. The Math and Question challenges run entirely on your own site with no signup. If you prefer Turnstile, reCAPTCHA, or hCaptcha, you create free keys with that provider and paste them in.

= Which CAPTCHA should I choose? =

Cloudflare Turnstile for most sites: it is free, privacy-friendly, and most visitors never see a puzzle. Choose reCAPTCHA if you already use it elsewhere, hCaptcha if you want a privacy-focused alternative to Google, or a self-hosted challenge if you want no third-party service at all.

= Will it slow my site down? =

No. Pages without a protected form load zero CaptchaFlow assets. Pages with one load a single script under 3 KB compressed, and the provider connection is warmed up in advance. Server-side verification adds under 5 milliseconds.

= Does it work with caching plugins? =

Yes, by design. CaptchaFlow never puts visitor-specific data in your page HTML, so cached pages stay correct for every visitor. The challenge itself is fetched by the browser with caching disabled. The diagnostics screen detects your caching plugin and confirms the challenge endpoint is returning fresh responses through it.

= Does it work if a visitor has JavaScript disabled? =

Yes. Forms fall back to an accessible text challenge that works with no JavaScript at all.

= What happens if my CAPTCHA provider goes down? =

You decide. By default CaptchaFlow fails open: submissions are accepted rather than locking real visitors out, and the honeypot and time trap keep filtering bots. You can switch to fail closed in Settings if you prefer.

= Will it clash with the CAPTCHA built into my form plugin? =

Run the built-in diagnostics: CaptchaFlow detects other CAPTCHA plugins and warns you before two challenges end up on one form. Disable the other CAPTCHA on forms CaptchaFlow protects.

= Can I protect a custom-coded form? =

Yes. Enter a CSS selector on the Forms screen and CaptchaFlow protects every matching form, including forms rendered by page builders or custom themes.

= Does it protect WooCommerce checkout? =

The free plugin protects WooCommerce login, registration, and password reset. Checkout and order-related protection is part of CaptchaFlow Pro.

= Where do the spam statistics live? =

In your own database. The dashboard shows blocked totals for today, this week, this month, and a 30-day trend. Nothing is sent anywhere.

= What data does CaptchaFlow collect about my visitors? =

None for us, and almost none at all. Verification events are logged in your database for the retention period you choose (30 days by default), then deleted automatically. Each event records the time, which form it was, the verdict, a one-way hash of the submitter's email address, and their IP address shortened to its network. The address itself is never stored.

= Is it GDPR-friendly? =

It is built to be. Visitor IP addresses are shortened before they are logged, email addresses are stored only as one-way hashes, and nothing is sent to us. Under Settings → Privacy you will find suggested policy wording generated from your actual configuration — a site using only the Math or Question challenge is told, correctly, that nothing leaves it; a site using an external provider gets that provider named with a link to its policy. Export and erasure requests made through Tools → Export Personal Data and Erase Personal Data include the spam log automatically.

= What happens to my spam statistics when someone asks to be erased? =

They stay accurate. Erasing removes the email hash and the IP address from the matching records but keeps the record itself, which by then identifies nobody. Deleting the rows outright would rewrite your site's history every time somebody exercised their right to erasure.

= Does it support multisite? =

Yes, CaptchaFlow works on multisite networks. Each site configures its own protection.

= Is it translation-ready? =

Yes. Every string is translatable, a POT file ships with the plugin, and the admin fully supports RTL languages.

= Is it accessible? =

Yes. The challenges are keyboard-operable, labelled for screen readers, and respect reduced-motion preferences. The no-JavaScript fallback is plain accessible HTML.

= How do I get help? =

Open a thread in the support forum. Please attach the diagnostics report (Tools → Diagnostics → Export report) — it contains no keys or secrets and answers most environment questions in one attachment.

== Screenshots ==

1. Dashboard — protection status, blocked-spam counters, and a 30-day trend.
2. Setup wizard — protected in under a minute.
3. Forms — every detected form source with one protect-all switch.
4. Provider — challenge cards with plain-language trade-offs and key testing.
5. Tools — one-click diagnostics and the theme compatibility checker.
6. Dark mode — the whole admin, at night.

== Changelog ==

= 1.1.0 =
* New: a Pro screen in the admin describing what CaptchaFlow Pro adds, reachable from the menu.
* The Pro entry is hidden automatically on sites that already run Pro.
* No changes to form protection, providers, or how visitor data is handled.

= 1.0.0 =
* Initial release.
* Protection for WordPress core forms (login, registration, password reset, comments), WooCommerce account forms, Contact Form 7, WPForms, Fluent Forms, Forminator, Ninja Forms, Gravity Forms, Elementor Pro, and any form via CSS selector.
* Providers: Cloudflare Turnstile, Google reCAPTCHA v2/v3, hCaptcha, self-hosted Math and Question challenges.
* Honeypot and time-trap pre-checks on every submission.
* Cache-safe challenge delivery; no visitor data in page HTML.
* Setup wizard, one-click diagnostics with text export, theme compatibility checker.
* Dashboard with blocked-spam counters and 30-day trend; daily statistics rollups.
* Encrypted provider secrets at rest; deferred log writes; automatic log retention.
* Privacy: IP addresses shortened to their network before logging, suggested privacy-policy wording generated from your configuration, and export/erase handlers wired into the WordPress privacy tools.

== Upgrade Notice ==

= 1.1.0 =
Adds a Pro information screen in the admin. Form protection, providers, and visitor-data handling are unchanged.

= 1.0.0 =
Initial release.
