?️ WebsiteCaptcha
通过嵌入式 Web 服务器和 REST API 实现安全的 Minecraft 玩家验证
WebsiteCaptcha 是一款高性能的 Minecraft 服务器插件,旨在通过在玩家进入主游戏世界之前要求他们通过基于网页的验证码或外部自定义网站进行自我验证,从而增强服务器安全性。
它具备隔离的网络包级别 Limbo 世界、嵌入式 Web 服务器、安全的 REST API 以及用于持久化验证跟踪的 SQLite 数据库等功能。
免责声明
注意: WebsiteCaptcha 是作为安全解决方案开发的实验性插件。在部署到生产环境之前,应严格控制环境中彻底测试嵌入式 Web 服务器、SQLite 数据库和超时机制等功能。非常鼓励贡献以增强稳定性和性能!
插件信息
WebsiteCaptcha 通过实施无缝的验证码验证管道来保护您的 Minecraft 服务器免受机器人攻击和未授权访问。加入时,未验证的玩家会被隔离在一个虚拟的“Limbo”环境中(由 PacketEvents 提供支持),他们必须完成内置 Web 服务器(默认:localhost:8080)或您自己的自定义外部网站(Next.js、Node.js、PHP 等)上的验证码挑战。
验证通过后,玩家将无缝传送回主游戏世界,并恢复其物品栏。
主要功能
- Google reCAPTCHA 验证:内置支持 Google reCAPTCHA v2 的 Web 服务器。
- 外部自定义网站支持:托管您自己的外部验证站点(Next.js、React、Node.js、PHP),使用 Turnstile、Discord OAuth 或
config.yml 中的 Web_Type: "Custom" 进行自定义逻辑。
- 安全的 REST API 和 API Key 系统:版本化的 REST API(
POST /api/v1/verify 和 GET /api/v1/session/{id})通过 X-API-Key 和 X-API-Secret 头部进行认证,具备恒定时间防时序攻击防御、速率限制和审计日志记录(api_audit.log)。
- 控制台 API 管理:仅通过服务器控制台终端使用
/webcapture api <create|remove|list> 严格管理 API 凭据。
- 一次性验证会话:生成有效期为 5 分钟的 256 位安全令牌会话(
wks_...),并在验证后原子性地转换状态。
- 虚拟 Limbo 世界:未验证的玩家被隔离在一个具有受限权限的虚拟网络包级别世界中。
- 经验条计时器:在经验条上显示剩余验证时间,平滑递减直至超时。
- 可配置设置:通过
config.yml 和 api_config.yml 自定义超时时长、游戏模式、飞行、失明效果、网络套接字绑定(bind_address)以及隐藏物品栏。
- 踢出延迟:在踢出超时的玩家之前显示可配置的警告消息。
- 版本检测:使用 PacketEvents 记录玩家的 Minecraft 版本(1.8 至 1.21.4)。
- 持久化存储:将验证时间戳和状态存储在 SQLite 数据库(
verification.db)中。
- 自定义模板与文档:在
plugins/WebsiteCaptcha/example_custom_web/ 内部获取完整的 Next.js 网站示例(website_example.zip)和完整的 REST API 文档(api.txt)。
工作原理
- 玩家加入:服务器记录玩家的 IP、用户名和客户端版本,然后检查 SQLite 数据库中的验证状态。
- 验证检查:如果未验证或宽限期已过,玩家进入 Limbo 世界,并创建一个为期 5 分钟的一次性
VerificationSession。
- 验证码提示:一条可点击的聊天消息提供链接,指向内置或自定义的外部 Web 验证页面。
- 自定义网站 / API 验证:外部网站验证玩家,并使用
X-API-Key 和 X-API-Secret 头部发送安全的 POST /api/v1/verify 请求。
- 超时机制:经验条倒计时;如果时间耗尽,则在断开连接前出现踢出消息。
- 成功:验证成功后,会话失效,玩家从 Limbo 释放回主世界,并恢复物品栏。
命令与权限
| 命令 |
用法 / 描述 |
权限 / 发送者 |
/webcapture api create <name> <creator> |
生成新的 API Key 和 Secret Key |
仅限控制台 |
/webcapture api remove <name> |
移除现有的 API Key |
仅限控制台 |
/webcapture api list |
列出所有注册的 API keys |
仅限控制台 |
/webcaptcha help |
显示插件帮助菜单 |
webcaptcha.help / OP |
/webcaptcha reload |
重新加载配置文件 |
webcaptcha.reload / OP |
/webcaptcha portcheck <ip> <port> |
检查端口是否开放且可达 |
OP |
/webcaptcha verify clearverify <player> |
清除玩家的验证状态 |
webcaptcha.clearverify / OP |
/webcaptcha verify setverify <player> |
将玩家标记为已验证 |
webcaptcha.setverify / OP |
/webcaptcha verify whitelist <add|remove|list> |
管理验证白名单 |
webcaptcha.whitelist / OP |
安装
-
依赖项
- Paper/Bukkit/Spigot:兼容 1.20 至 1.21.4 版本
- PacketEvents:Limbo 系统必需(可从 Modrinth 下载)
-
快速设置
- 从 Releases 下载最新的
WebsiteCaptcha.jar。
- 将其与 PacketEvents 一起放入服务器的
plugins 文件夹中。
- 启动服务器以在
plugins/WebsiteCaptcha/ 目录下生成 config.yml 和 api_config.yml。
- 根据你的 reCAPTCHA 或自定义网站配置来设置
config.yml。
-
完整文档
如需详细的安装步骤、配置选项及故障排除指南,请查阅我们的完整文档:
WebsiteCaptcha Documentation
许可证
WebsiteCaptcha 遵循 GNU General Public License v3.0 许可协议。有关详细信息,请参阅 LICENSE 文件。
致谢与联系方式
?️ 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
- Player Joins: The server logs the player’s IP, username, and client version, then checks SQLite database verification status.
- Verification Check: If unverified or grace period has expired, the player enters Limbo and a 5-minute single-use
VerificationSession is created.
- CAPTCHA Prompt: A clickable chat message provides a link to the built-in or custom external web verification page.
- 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.
- Timeout Mechanism: An XP bar counts down; if time runs out, a kick message appears before disconnection.
- 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
-
Dependencies
- Paper/Bukkit/Spigot: Compatible with versions 1.20 to 1.21.4
- PacketEvents: Required for Limbo system (download from Modrinth)
-
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.
-
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
评论 0
登录后参与评分
还没有评论,来抢沙发吧