# Puzzle Gate

**Contributors:** wpsqr  
**Tags:** login security, puzzle captcha, anti-bot, brute force protection  
**Requires at least:** 6.3  
**Tested up to:** 6.9  
**Requires PHP:** 7.4  
**Stable tag:** 1.0.0  
**License:** GPLv2 or later  
**License URI:** https://www.gnu.org/licenses/gpl-2.0.html  

Protect your WordPress login page with a fast, human-friendly puzzle CAPTCHA that blocks bots without frustrating users.

---

## Description

**Puzzle Gate** is a lightweight WordPress security plugin that protects your login page using a **logic-based puzzle CAPTCHA** instead of traditional image or text CAPTCHAs.

Unlike common CAPTCHAs that rely on external services or distorted text, Puzzle Gate uses an **interactive drag-and-drop puzzle** that is easy for humans and extremely difficult for bots to solve automatically.

This release includes **Puzzle #1: Order the Symbols**, where users must arrange randomized symbols into the correct logical order before logging in.

### Why Puzzle Gate?

- No external APIs or tracking
- No images, no third-party services
- Fully self-hosted and privacy-friendly
- Resistant to brute-force and automated attacks
- Fast, modern, and accessible

### How Puzzle #1 Works

1. On the WordPress login page, users see a set of randomized symbols.
2. A short instruction hints at the correct logical order.
3. The user drags and reorders the symbols.
4. The login form is unlocked only after the puzzle is solved correctly.

Puzzle data is generated server-side, hashed securely, and expires automatically to prevent replay attacks.

---

## Features

- Drag-and-drop puzzle CAPTCHA
- Secure server-side validation
- Puzzle expiration (default 60 seconds)
- Regenerates on refresh or failed attempt
- Blocks bots before authentication
- Mobile-friendly and responsive
- Lightweight and fast (no external assets)

---

## Security Highlights

- Puzzle answers are **never stored in plain text**
- Answers are hashed using WordPress salts
- Each puzzle is bound to a unique nonce
- Replay attacks are prevented
- Puzzle is invalidated after successful login
- Compatible with common security plugins

---

## Admin Configuration

Puzzle Gate includes a settings page where administrators can:

- Enable or disable the puzzle CAPTCHA
- Set puzzle difficulty (number of symbols)
- Enable the puzzle only after X failed login attempts
- Whitelist trusted IP addresses

---

## Accessibility

Puzzle Gate is designed to be usable by everyone:

- Keyboard-navigable interface
- Screen-reader-friendly markup
- Alternative non-drag ordering method (dropdowns)

---

## Performance

- Loads in under 200ms on typical hosting environments
- No external scripts or stylesheets
- Optimized for minimal impact on login performance

---

## Installation

1. Upload the `puzzle-gate` folder to the `/wp-content/plugins/` directory  
   **OR** install via the WordPress Plugins screen.
2. Activate the plugin through the *Plugins* menu.
3. Go to **Settings → Puzzle Gate** to configure options.
4. Log out and visit the login page to see the puzzle in action.

---

## Frequently Asked Questions

### Will this slow down my login page?
No. The puzzle is lightweight and optimized to load quickly.

### Can bots solve this puzzle?
The puzzle logic, nonce binding, expiration, and hashing make automated solving extremely difficult.

### What happens if a user fails the puzzle?
The puzzle is regenerated and must be solved again before login is allowed.

### Does it work on mobile devices?
Yes. The puzzle is fully responsive and automatically switches to a dropdown-based interface on mobile devices.

---

## Changelog

### 1.0.0
- Initial release
- Puzzle #1: Order the Symbols
- Admin settings panel
- Accessibility fallback
- Secure nonce-based validation

---

## Upgrade Notice

### 1.0.0
Initial release of Puzzle Gate.

---

## Documentation

Full documentation is available on our website:  
[Puzzle Gate Documentation](https://www.wp-sqr.com/)

---

## Troubleshooting

1. Ensure the Puzzle Gate plugin is activated and your WordPress version is at least 5.2.
2. Deactivate other plugins to check for conflicts.