🛡️ 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

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