=== GhostTrap ===
Contributors: laughteronwater
Tags: spam, comments, antispam, security, protection
Requires at least: 5.0
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.0.3
License: GPLv3 or later
License URI: http://www.gnu.org/licenses/gpl.html

Advanced 5-layer invisible spam protection for comments. No captcha, no user friction - professional spam blocking.

== Description ==

**GhostTrap** provides sophisticated invisible spam protection using a comprehensive 5-layer detection system. Legitimate users comment normally while automated spam is silently blocked through advanced timing analysis, cryptographic validation, and behavioral detection.

= 5-Layer Protection System =

* **Timing Analysis** - Detects submissions too fast for human interaction
* **Cryptographic Signatures** - Prevents replay attacks and form manipulation
* **Year Validation** - JavaScript-enhanced field verification
* **JavaScript Detection** - Ensures legitimate browser interaction
* **Honeypot Fields** - Multiple hidden traps catch automated bots

= Professional Features =

* **Enhanced Admin Interface** - Professional statistics dashboard with custom branding
* **Real-time Statistics** - Track protection effectiveness with detailed blocking metrics
* **Configurable Timing** - Adjust detection sensitivity from 5-300 seconds
* **WordPress 6.4+ Compatible** - Full support for block themes and FSE
* **Admin Bar Integration** - Quick spam statistics for administrators
* **Screen Options Control** - User-configurable interface elements

= Zero User Friction =

All protection operates invisibly - no captcha, no puzzles, no delays. Users with JavaScript enabled see normal comment forms, while those with disabled JavaScript get simple year validation. Protection effectiveness remains high in both scenarios.

= Performance Optimized =

* **Lightweight JavaScript** - Only 2KB, loads exclusively on comment pages
* **Smart Script Loading** - Conditional loading based on comment form presence
* **Minimal Database Impact** - Efficient storage with optional spam archiving
* **Browser Compatibility** - Works across all modern browsers with graceful degradation

= GDPR Compliant =

No external services, no tracking, no personal data collection beyond standard WordPress comment processing. All spam detection happens locally on your server.

= Attribution =

Built upon the original Anti-spam plugin foundation by webvitaly, with comprehensive modernization, enhanced detection layers, and professional admin interface for current WordPress compatibility.

== Installation ==

= Automatic Installation =

1. Go to Plugins → Add New in your WordPress admin
2. Search for "GhostTrap"
3. Click Install Now, then Activate
4. Protection starts immediately with default settings
5. Optional: Visit Settings → GhostTrap to customize timing and display options

= Manual Installation =

1. Download the plugin zip file
2. Upload to `/wp-content/plugins/ghosttrap/` directory
3. Activate through WordPress admin Plugins page
4. Configure optional settings at Settings → GhostTrap

= Verification Testing =

After installation, test protection effectiveness:

1. Log out of WordPress admin
2. Navigate to any post with comments enabled
3. Submit a test comment (should work normally)
4. Check Settings → GhostTrap for blocking statistics
5. Optionally enable "Save blocked spam" to review caught submissions

== Frequently Asked Questions ==

= How effective is the 5-layer system? =

GhostTrap blocks virtually all automated spam while maintaining zero friction for legitimate users. The multi-layer approach ensures that even if bots bypass one detection method, additional layers provide backup protection.

= What happens if users disable JavaScript? =

Users with disabled JavaScript (less than 1% of visitors) see a simple year validation field. They enter the current year to submit comments. Protection effectiveness remains high through server-side validation layers.

= Does it impact site performance? =

No measurable impact. JavaScript loads only on pages with comment forms, the detection process adds minimal server processing time, and database queries are optimized for efficiency.

= Can I see what spam was blocked? =

Yes. Enable "Save blocked spam" in Settings → GhostTrap to store blocked submissions in WordPress spam folder for review. This helps fine-tune timing settings if needed.

= Is it compatible with comment plugins? =

GhostTrap works with standard WordPress comment systems, AJAX comment loading, and most comment enhancement plugins. It detects comment forms dynamically and applies protection automatically.

= What about trackbacks and pingbacks? =

* **Trackbacks** are blocked (high spam potential, rarely legitimate)
* **Pingbacks** are allowed (verified WordPress-to-WordPress communication)

= How do I adjust detection sensitivity? =

Visit Settings → GhostTrap to configure timing thresholds. Default 15-second minimum works well for most sites. Increase for slower readers, decrease for higher security on high-traffic sites.

= Does it work with block themes? =

Full compatibility with WordPress block themes, Full Site Editing, Gutenberg comment blocks, and classic themes. The protection system adapts to various comment form implementations.

== Screenshots ==

1. **Access Ghost Trap** - Go to settings in the admin sidebar and select GhostTrap.
2. **Real-time Protection Statistics** - See blocked stats, set form delay timer and spam storage preferences here.
3. **Admin Bar Stats** - Show or hide admin bar stats. They only show up in the admin area, and only if you want them.
4. **Comments Page Stats Notification** - Show or hide comment notifications. They're also dismissable.
5. **Invisible Comment Protection** - A plugin like this should availabe _when_ you need it, but disappear into the background _until_ you need it.

== Changelog ==

= 1.0.3 - 2025-09-27 =

**Minor Changes** - cosmetic changes.

= 1.0.2 - 2025-09-19 =

**Minor Review** - removed orphaned style queue, revised script queue.

= 1.0.1 - 2025-09-19 =

**Minor Review** - Checking edits one last time for compliance.

= 1.0.0 - 2025-09-01 =

**Major Release - Comprehensive Enhancement**

*Enhanced Protection System:*
* **NEW:** 5-layer spam detection with timing analysis and cryptographic validation
* **NEW:** Configurable timing thresholds (5-300 seconds) for customized sensitivity
* **NEW:** Advanced honeypot system with randomized field generation
* **NEW:** JavaScript behavioral detection with form interaction analysis
* **NEW:** Server-side signature validation preventing replay attacks

*Professional Admin Interface:*
* **NEW:** Custom-branded hero banner with GhostTrap SVG integration
* **NEW:** Real-time statistics dashboard with professional design system
* **NEW:** Admin bar spam counter with user visibility controls
* **NEW:** Screen options integration for personalized admin experience
* **NEW:** Contextual help system with comprehensive protection information

*WordPress Compatibility:*
* **NEW:** WordPress 6.4+ full compatibility with block themes and FSE
* **NEW:** Enhanced form detection supporting AJAX and dynamic comment loading
* **NEW:** Dashboard "At a Glance" widget integration for quick statistics
* **NEW:** Modern JavaScript with MutationObserver for dynamic content support
* **NEW:** Comprehensive internationalization with translation-ready strings

*Technical Improvements:*
* **NEW:** WordPress coding standards compliance with comprehensive security hardening
* **NEW:** Performance-optimized script loading with conditional enqueueing
* **NEW:** Enhanced browser compatibility with graceful JavaScript degradation
* **NEW:** Professional PHPDoc documentation throughout codebase
* **NEW:** Comprehensive nonce verification and input sanitization

**Foundation:** Built upon original Anti-spam plugin by webvitaly (GPL v3)
**Architecture:** Complete modernization with 5-layer detection system
**Interface:** Professional admin experience with custom branding integration

== Upgrade Notice ==

= 1.0.0 =
Major release: 5-layer invisible spam protection with professional admin interface. Comprehensive enhancement of the original Anti-spam foundation with advanced detection, timing analysis, and modern WordPress compatibility.

== Privacy Policy ==

GhostTrap operates with privacy-first design principles:

* **No External Services** - All spam detection processing occurs on your server
* **No Personal Data Collection** - Uses only standard WordPress comment data for protection
* **No Tracking or Analytics** - Zero data sharing with third parties or external systems
* **GDPR Fully Compliant** - Minimal data processing with transparent, local-only operation
* **Optional Spam Storage** - Blocked comments stored locally only if explicitly enabled

== Advanced Configuration ==

= Timing Threshold Recommendations =

* **High Security Sites:** 10-15 seconds (stricter protection)
* **General Purpose Sites:** 15-20 seconds (balanced protection)
* **Accessibility-Focused Sites:** 25-30 seconds (accommodates slower interaction)
* **Reading-Heavy Sites:** 30+ seconds (allows time for content review)

= Admin Interface Customization =

* **Admin Bar Statistics** - Toggle spam counter visibility in admin bar
* **Screen Options** - Control information panel display on comments page
* **Dashboard Integration** - Spam statistics in "At a Glance" widget
* **Contextual Help** - Comprehensive protection information in WordPress help system

= Technical Requirements =

**Server Environment:**
* WordPress 5.0 or higher
* PHP 7.4 or higher
* Standard WordPress hosting with wp_options table access

**Browser Support:**
* All modern browsers (Chrome, Firefox, Safari, Edge)
* Internet Explorer 11+ with graceful degradation
* Mobile browsers with full functionality
* JavaScript-disabled browsers with fallback protection

**Performance Specifications:**
* JavaScript payload: ~2KB minified and compressed
* Database impact: Single option row with minimal queries
* Server processing: Sub-millisecond detection analysis
* Memory usage: Negligible footprint during comment processing