🛡️ WebsiteCaptcha

Secure Minecraft Player Verification via Embedded Web Server & REST API

---

WebsiteCaptcha is a high-performance Minecraft server plugin designed to enhance server security by requiring players to verify themselves via a web-based CAPTCHA or external custom website before accessing the main game world.

It features an isolated packet-level Limbo world, an embedded web server, a secure REST API, and an SQLite database for persistent verification tracking.

---

Disclaimer

Note: WebsiteCaptcha is an experimental plugin developed as a security solution. Features such as the embedded web server, SQLite database, and timeout mechanics should be tested thoroughly in a controlled environment before deploying to live production servers. Contributions to enhance stability and performance are highly encouraged!

---

Plugin Information

WebsiteCaptcha protects your Minecraft server from bot attacks and unauthorized access by implementing a seamless CAPTCHA verification pipeline. Upon joining, unverified players are isolated in a virtual "Limbo" environment (powered by PacketEvents) where they must complete a CAPTCHA challenge on the built-in web server (default: localhost:8080) or your custom external website (Next.js, Node.js, PHP, etc.).

Once verified, players are seamlessly teleported back to the main game world with their inventory restored.

Key Features

• Google reCAPTCHA Verification: Built-in web server with Google reCAPTCHA v2 support.
• External Custom Website Support: Host your own external verification site (Next.js, React, Node.js, PHP) with Turnstile, Discord OAuth, or custom logic using Web_Type: "Custom" in config.yml.
• Secure REST API & API Key System: Versioned REST API (POST /api/v1/verify & GET /api/v1/session/{id}) authenticated via X-API-Key and X-API-Secret headers with constant-time timing-attack defense, rate limiting, and audit logging (api_audit.log).
• Console API Management: Manage API credentials strictly from the server console terminal using /webcapture api <create|remove|list>.
• Single-Use Verification Sessions: Generates 256-bit secure token sessions (wks_...) valid for 5 minutes that transition atomically upon verification.
• Virtual Limbo World: Unverified players are isolated in a virtual packet-level world with restricted permissions.
• XP Bar Timer: Displays remaining verification time on the XP bar, decreasing smoothly until timeout.
• Configurable Settings: Customize timeout duration, game mode, flight, blindness, network socket binding (bind_address), and inventory hiding via config.yml and api_config.yml.
• Kick Delay: Displays a configurable warning message before kicking timed-out players.
• Version Detection: Logs player Minecraft versions (1.8 to 1.21.4) using PacketEvents.
• Persistent Storage: Stores verification timestamps and states in SQLite (verification.db).
• Custom Templates & Documentation: Access complete Next.js website examples (website_example.zip) and full REST API documentation (api.txt) inside plugins/WebsiteCaptcha/example_custom_web/.

---

How It Works

1. Player Joins: The server logs the player’s IP, username, and client version, then checks SQLite database verification status.
2. Verification Check: If unverified or grace period has expired, the player enters Limbo and a 5-minute single-use VerificationSession is created.
3. CAPTCHA Prompt: A clickable chat message provides a link to the built-in or custom external web verification page.
4. Custom Website / API Verification: The external website verifies the player and sends a secure POST /api/v1/verify request with X-API-Key and X-API-Secret headers.
5. Timeout Mechanism: An XP bar counts down; if time runs out, a kick message appears before disconnection.
6. Success: Upon verification, the session is invalidated, and the player is released from Limbo to the main world with restored inventory.

---

Commands & Permissions

Command	Usage / Description	Permission / Sender
/webcapture api create <name> <creator>	Generate a new API Key & Secret Key	Console Only
/webcapture api remove <name>	Remove an existing API Key	Console Only
/webcapture api list	List all registered API keys	Console Only
/webcaptcha help	Show the plugin help menu	webcaptcha.help / OP
/webcaptcha reload	Reload configuration files	webcaptcha.reload / OP
/webcaptcha portcheck <ip> <port>	Check if a port is open and reachable	OP
/webcaptcha verify clearverify <player>	Clear verification status for a player	webcaptcha.clearverify / OP
/webcaptcha verify setverify <player>	Mark a player as verified	webcaptcha.setverify / OP
/webcaptcha verify whitelist <add|remove|list>	Manage the verification whitelist	webcaptcha.whitelist / OP

---

Installation

1. Dependencies

   • Paper/Bukkit/Spigot: Compatible with versions 1.20 to 1.21.4
   • PacketEvents: Required for Limbo system (download from Modrinth)

2. Quick Setup

   • Download the latest WebsiteCaptcha.jar from Releases.
   • Place it in your server’s plugins folder along with PacketEvents.
   • Start the server to generate config.yml and api_config.yml in plugins/WebsiteCaptcha/.
   • Configure config.yml with your reCAPTCHA or custom website settings.

3. Full Documentation
   For detailed installation steps, configuration options, and troubleshooting, check out our full docs at:
   WebsiteCaptcha Documentation

License

WebsiteCaptcha is licensed under the GNU General Public License v3.0. See the LICENSE file for full details.

---

Credits & Contact

• Author: SalmanDev (GitHub: @Noonenowhoiam @CodeBorisDev)
• Dependencies: PacketEvents by retrooper and contributors.
• Discord Support: @apgamingboy
• GitHub Issues: Report an Issue