=== PureGuard — Bot Protection & Performance ===
Contributors: chanmyayaung
Tags: bot detection, security, firewall, traffic quality, waf
Requires at least: 5.6
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 4.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Three-tier bot protection: server-side WAF + JS challenge page for filtered traffic + engagement tracking.

== Description ==

PureGuard is a three-tier bot protection plugin for WordPress, powered by PureGuard's 18-layer detection engine.

**Tier 1: WAF Bot Protection (Server-Side)**

Checks every visitor's IP and User-Agent against PureGuard's bot detection API before your page loads. Bots are blocked, challenged, redirected, or logged — your choice.

* 18+ detection layers including FireHOL, CrowdSec, datacenter ASN detection, Chrome version analysis, Sec-Fetch header validation, and more
* Three actions: Block (403), Redirect (custom URL), or Log Only (monitor mode)
* Configurable trust threshold (1-10 scale, default 7.0)
* Smart caching — results cached per IP to minimize API calls (configurable 30min to 24hr)
* Graceful degradation — if the API is unreachable, visitors pass through normally
* Skips logged-in users, search engine bots (Google, Bing, etc.), admin pages, AJAX, and REST API
* Dashboard widget showing total checks, blocks, and block rate

**Tier 2: JS Challenge Page (Filtered Traffic)**

Filtered-tier visitors (low trust score or hard-kill signals) are served a lightweight JavaScript challenge page — similar to Cloudflare's browser verification.

* SHA-256 proof-of-work challenge that real browsers solve in 1-3 seconds
* 10 browser integrity checks running client-side (WebDriver, Chrome object, screen size, automation globals, plugins/languages, WebGL renderer, function integrity, viewport ratio, timezone, userAgentData)
* Visitors who pass the challenge receive an HMAC-signed cookie valid for 1 hour
* Bots and headless browsers fail the challenge and are blocked
* Four configurable actions for filtered traffic: Challenge (default), Block, Redirect, or Log Only
* Challenge stats tracked in dashboard (served vs passed)

**Tier 3: Traffic Intelligence (Client-Side)**

For media buyers and publishers who buy traffic from ad networks. Tracks post-click engagement per traffic zone to identify which zones produce real engaged visitors vs bot traffic.

* Time-on-page tracking with beacons at 10s, 30s, and 60s intervals
* Scroll depth tracking (percentage of page scrolled)
* Click interaction detection
* 10 silent browser integrity checks detecting headless browsers, automation frameworks, and bot fingerprints
* Per-zone metrics tagged with zone ID and traffic source
* Data appears in your PureGuard Zone Quality dashboard

**Browser Integrity Checks (10 signals):**

1. WebDriver detection (Selenium, Puppeteer, Playwright)
2. Chrome object verification (fake Chrome user agents)
3. Screen dimensions (headless browsers with 0x0 screens)
4. Automation globals (PhantomJS, Nightmare, Selenium)
5. Plugin and language presence (headless environments)
6. WebGL renderer (SwiftShader, Mesa, llvmpipe in VMs)
7. Native function integrity (overridden browser APIs)
8. Viewport vs screen ratio (impossible dimensions)
9. Timezone consistency (missing or undefined timezone)
10. UserAgentData API (Chrome UA spoofing detection)

**Zero performance impact:**

* WAF check uses WordPress transient caching — repeat visitors are checked instantly from cache
* Engagement script (~2KB) loads in the footer with `defer` — no render blocking
* Uses `navigator.sendBeacon` — completely non-blocking data transmission
* Engagement tracking only activates on single posts and pages with PureGuard URL parameters
* Organic traffic, search engine crawlers, and direct visits are not affected

**Requires a PureGuard account.** Sign up free at [pureguard.io](https://pureguard.io/register).

== Third-Party Services ==

This plugin connects to the PureGuard API to provide bot detection and engagement tracking.

**PureGuard Bot Check API**

* Service URL: https://pureguard.io/api/v7/check
* Used by: WAF Security layer
* When: On each uncached page visit by a non-logged-in visitor
* Data sent: Visitor IP address, User-Agent string, trust threshold setting
* Data received: Bot verdict (ACCEPT/BLOCK), trust score, detection reason

**PureGuard Beacon API**

* Service URL: https://pureguard.io/api/v7/beacon
* Used by: Traffic Intelligence layer
* When: On content pages where PureGuard URL parameters are present (pg_z, pg_src)
* Data sent: Zone ID, source name, time on page (seconds), scroll percentage, click status, browser integrity verdict and flags, page URL

**No personal data is collected.** No cookies are set by the tracking layer. The challenge layer sets one HMAC-signed verification cookie (pgperf_verified) containing only the visitor's IP, expiry timestamp, and a cryptographic signature — no personal data. No browser fingerprints are stored. No email addresses, names, or account information is transmitted.

* PureGuard Website: [https://pureguard.io](https://pureguard.io)
* Privacy Policy: [https://pureguard.io/privacy](https://pureguard.io/privacy)
* Terms of Service: [https://pureguard.io/terms](https://pureguard.io/terms)

== Installation ==

1. Download the plugin ZIP from the WordPress Plugin Directory or from your PureGuard dashboard
2. Go to WordPress Admin > Plugins > Add New > Upload Plugin
3. Upload the ZIP file and click "Install Now"
4. Activate the plugin
5. Go to Settings > PureGuard
6. Enter your PureGuard API key (found in your PureGuard dashboard under Settings)
7. Choose your protection mode: Both, WAF Only, or Traffic Intelligence Only
8. If using WAF, start with "Log Only" action to review detections before enabling blocking
9. Configure Filtered tier action (Challenge recommended) in the Quality Tiers tab

== Frequently Asked Questions ==

= Do I need a PureGuard account? =

Yes. Both layers require a PureGuard API key to function. Sign up free at [pureguard.io](https://pureguard.io/register).

= Will this slow down my site? =

No. The WAF check takes 1-3ms for cached IPs (the vast majority of requests). Uncached checks add ~50ms for the API call, and results are cached for 1 hour by default. The engagement script is ~2KB, loads deferred, and uses non-blocking sendBeacon.

= What is the JS challenge page? =

When a visitor is classified as Filtered (low trust score), they see a lightweight verification page. It runs a SHA-256 proof-of-work computation and 10 browser integrity checks. Real browsers solve it in 1-3 seconds and are automatically redirected to the original page. Bots and headless browsers fail.

= What happens if the PureGuard API is down? =

The plugin degrades gracefully. If the API is unreachable, all visitors pass through normally. A short 5-minute cache is set to avoid repeatedly hitting an unresponsive API.

= Does it block search engines? =

No. Googlebot, Bingbot, DuckDuckBot, YandexBot, Baiduspider, Applebot, and other major search engine bots are automatically whitelisted and never checked against the API.

= Does it affect logged-in users? =

By default, no. Logged-in WordPress users (admins, editors, etc.) skip the WAF check entirely. You can change this in WAF Security settings.

= Does it track all visitors? =

The WAF layer checks all non-logged-in visitors (results are cached). The Traffic Intelligence layer only tracks visitors who arrive with PureGuard URL parameters (pg_z and pg_src). Organic visitors and direct visits are completely ignored by the engagement tracking.

= Does it interfere with ads or other plugins? =

No. The plugin does not modify the DOM, inject visible elements, or interfere with ad networks, caching plugins, or SEO tools.

= Can I use only one layer? =

Yes. In Settings > PureGuard > General, you can choose "WAF Security Only" or "Traffic Intelligence Only" if you don't need both layers.

= What data is sent to PureGuard? =

WAF: Visitor IP and User-Agent. Traffic Intelligence: Zone ID, source name, time on page, scroll depth, click status, browser integrity flags, and page URL. No personal data, cookies, or fingerprints are collected.

== Screenshots ==

1. General settings — API key and protection mode selection
2. WAF Security settings — bot action, trust threshold, cache duration
3. Traffic Intelligence — browser integrity check documentation
4. Quality Tiers — Gold/Silver/Filtered tier actions including JS challenge
5. Stats dashboard — total checks, blocks, challenges served/passed
6. WordPress dashboard widget — quick protection overview
7. JS Challenge page — proof-of-work verification shown to filtered visitors

== Changelog ==

= 4.0.0 =
* BREAKING: All function/option prefixes renamed from `pg_` to `pgperf_` (WordPress Plugin Team requirement — prefixes must be 4+ characters)
* NEW: JS Challenge page for Filtered-tier traffic — SHA-256 proof-of-work + 10 browser integrity checks
* NEW: HMAC-signed verification cookie for visitors who pass the challenge (1 hour validity)
* NEW: Configurable Filtered tier action — Challenge (default), Block, Redirect, or Log Only
* NEW: Challenge statistics tracking (served vs passed) in Stats tab and dashboard widget
* NEW: Automatic migration from v3 `pg_` options to v4 `pgperf_` options on activation
* NEW: Old `pg_waf_` transient cache cleanup during migration
* CHANGED: JS engagement script renamed from `pg-engagement.js` to `pgperf-engagement.js`
* CHANGED: Localized JS variable renamed from `pgData` to `pgperfData`
* CHANGED: Settings group renamed from `pg_settings` to `pgperf_settings`
* CHANGED: Dashboard widget ID renamed from `pg_dashboard_widget` to `pgperf_dashboard_widget`
* CHANGED: All nonce actions/names use `pgperf_` prefix
* CHANGED: Transient cache keys use `pgperf_waf_` prefix
* IMPROVED: Settings registration uses compact loop instead of repeated register_setting calls

= 3.0.0 =
* NEW: Three-tier traffic classification — Gold, Silver, Filtered
* NEW: Configurable Silver tier action — Pass, Redirect, or Log
* NEW: Quality tier breakdown in dashboard widget and stats
* IMPROVED: WAF action now applies to Filtered tier specifically

= 2.0.0 =
* NEW: WAF Security layer — server-side bot blocking via PureGuard 18-layer detection engine
* NEW: Three WAF actions — Block (403), Redirect, or Log Only
* NEW: Configurable trust threshold (1-10 scale)
* NEW: Smart IP verdict caching with configurable TTL
* NEW: Search engine bot whitelist (Google, Bing, etc.)
* NEW: Dashboard widget showing protection stats
* NEW: Tabbed settings page (General, WAF Security, Traffic Intelligence, Stats)
* IMPROVED: 10 browser integrity checks (up from 5)
* CHANGED: API key authentication (replaces workspace key)
* CHANGED: Uses PureGuard API v7 endpoints

= 1.0.0 =
* Initial release
* Time-on-page beacons at 10s, 30s, 60s intervals
* Scroll depth tracking
* Click interaction detection
* 5 browser integrity checks
* Settings page for workspace key configuration

== Upgrade Notice ==

= 4.0.0 =
Major update: all internal prefixes renamed from pg_ to pgperf_ (WordPress Plugin Team requirement). Your settings are automatically migrated on activation. New JS challenge page for filtered traffic — bots must now solve a proof-of-work challenge to access your site.

= 2.0.0 =
Major update: adds WAF bot blocking layer alongside existing engagement tracking. Your workspace key will be automatically migrated to the new API key setting.
