SimpPassForFree - 身份验证与登录模组
一款跨加载器的 Minecraft 玩家身份验证与登录系统,为服务器提供可靠的身份核验服务。
? 概述
SimpPassForFree 是一款专为 Minecraft Fabric 服务器设计的玩家认证模组。它通过与 SimpPass API 集成,有效防止小号注册和验证码滥用,从而解决需要可靠身份验证的场景问题。
当前版本:Fabric 1.20.1 和 1.20.2
开发计划:Forge 和 Paper 版本正在开发中
未来计划:针对 Minecraft 1.21.11+ 的字节码注入版本,具备完整的加载器兼容性
✨ 功能特性
? 安全验证机制
本模组使用官方 SimpPass API 进行玩家身份验证,集成了多种安全机制:
1. 微信小程序验证
- 玩家需要通过微信小程序获取验证码
- 微信账号实名认证确保玩家身份真实性
- 防止批量注册和虚假账号
2. SimpPass API 安全验证
- 通过官方 SimpPass API 进行验证
- API 端集成多重安全机制(包括 IP 检查、地理位置、风控等)
- 确保验证过程的安全性与可靠性
?️ 游戏内安全防护
登录状态管理
- 未认证限制:未通过验证的玩家无法执行任何游戏操作
- 无法移动(位置锁定)
- 无法使用物品和方块交互
- 无法使用大部分游戏指令
- 无法发送聊天消息(除白名单指令外)
会话管理
- 120 秒验证窗口:玩家加入服务器后有 120 秒的时间完成验证
- 自动踢出:超时未完成验证的玩家将被自动踢出
- 会话保护:防止会话劫持和重放攻击
数据持久化
- 玩家绑定信息本地存储
- 自动记录最后登录时间
- 支持多服务器共享配置(通过配置文件)
? 用户体验优化
- 友好提示:清晰的登录引导和错误提示
- 快速验证流程:简化的两步验证(绑定 + 验证码)
- 自动识别:自动识别已绑定用户,直接进行验证码登录
- 登录状态广播:玩家可在服务器中看到其他玩家的登录状态
? 快速开始
前置要求
- Minecraft 版本:1.20.1 或 1.20.2
- Fabric Loader:≥ 0.18.4
- Fabric API:最新版本
- Java:17 或更高版本
安装步骤
-
下载模组
-
安装 Fabric Loader
-
安装 Fabric API
-
安装模组
- 将下载的模组 JAR 文件放入服务器的
mods 目录
- 重启服务器
-
配置开发者 UUID
- 服务器启动后,模组会在
config/simppassforfree/ 目录下创建配置文件
- 编辑配置文件并输入你的 SimpPass 开发者 UUID
- 重启服务器使配置生效
配置说明
配置文件位置:config/simppassforfree/config.json
{
"developer_uuid": "your-developer-uuid-here",
"session_timeout_seconds": 120,
"kick_on_timeout": true
}
配置选项:
developer_uuid:你的 SimpPass 开发者 UUID(必填)
session_timeout_seconds:验证会话超时时间(秒),默认 120
kick_on_timeout:超时是否自动踢出玩家,默认 true
? 使用指南
玩家流程
首次登录(账号绑定)
- 加入服务器后,玩家会收到欢迎消息和登录提示
- 玩家需要通过微信小程序获取自己的 SimpPass UID
- 在游戏中使用指令:
/auth <SimpPassUID>
- 系统将验证 UID 的有效性
- 验证成功后,玩家需在 120 秒内使用验证码完成登录
已绑定用户登录
- 加入服务器后,系统自动检测已绑定账号
- 玩家从微信小程序获取验证码
- 在游戏中使用指令:
/p <verification_code>
- 系统通过 SimpPass API 验证代码
- 验证成功后,玩家可以正常游戏
指令列表
/auth <SimpPassUID>
- 功能:绑定或验证 SimpPass UID
- 权限:所有玩家
- 说明:
- 首次使用:绑定新的 SimpPass 账号
- 已绑定:启动验证流程,提示使用
/p 指令
/p <verification_code>
- 功能:使用验证码完成登录验证
- 权限:所有玩家
- 说明:
- 必须在绑定 UID 后的 120 秒内使用
- 验证码需从微信小程序获取
- 验证成功后,玩家可以正常游戏
白名单指令
未认证玩家可使用以下命令:
/p - 验证码登录命令
/auth - 账号绑定命令
/help - 帮助命令
/list - 查看在线玩家
/me - 动作命令
/tell, /msg, /w, /r - 私聊命令
/tellraw - 原始消息命令
/version - 版本信息
/seed - Seed 信息
/scoreboard - 记分板命令
/team - 队伍命令
/bossbar - Boss 条命令
/datapack - 数据包命令
? 技术架构
加载器兼容性设计
本模组采用模块化设计,将核心功能与特定加载器的实现分离:
- 核心模块:跨加载器通用核心功能(用户数据管理、API 客户端等)
- 加载器适配层:特定加载器的实现(Fabric、Forge、Paper 等)
- 统一接口:通过统一接口实现跨加载器兼容
核心模块
- 用户数据管理 (
UserDataManager):管理玩家绑定信息和用户数据持久化
- 认证会话管理 (
AuthSessionManager):管理登录会话和验证流程
- 玩家认证管理 (
PlayerAuthManager):管理玩家登录状态和权限控制
- API 客户端 (
SimpPassApiClient):与 SimpPass API 服务器通信
- 命令处理器 (
AuthCommands):处理玩家认证相关命令(特定加载器实现)
- 命令拦截器 (
CommandInterceptor):拦截未认证玩家的命令执行(特定加载器实现)
- 事件处理器 (
PlayerJoinHandler, AuthEventHandler):处理玩家加入和认证事件(特定加载器实现)
未来架构:字节码注入版本
在 Minecraft 1.21.11+ 版本中,我们将发布一个字节码注入版本:
- 字节码注入:直接使用 ASM 等工具进行字节码注入,无需特定加载器实现
- 自动检测:自动检测服务器使用的加载器类型
- 统一实现:一套代码适用于所有加载器
- 性能优化:减少适配层开销,提升性能
安全机制实现
-
SimpPass API 验证
- 通过官方 SimpPass API 进行用户验证
- API 端处理 IP 地址、地理位置等安全检查
- 确保验证过程的安全性和可靠性
-
会话管理
- 120 秒验证窗口,超时自动过期
- 防止会话重放攻击
- 自动清理过期会话
-
游戏内保护
- 未认证玩家无法执行游戏操作
- 位置锁定防止未经授权移动
- 命令拦截保护服务器安全
?️ 高级配置
自定义验证超时时间
修改配置文件中的 session_timeout_seconds 值(单位为秒):
{
"session_timeout_seconds": 180
}
配置超时踢出行为
您可以配置是否在超时时自动踢出玩家:
{
"kick_on_timeout": false
}
当设置为 false 时,超时的玩家不会被自动踢出,但仍无法执行游戏操作。
多服务器配置共享
如果您有多个服务器,可以共享用户数据:
- 将
config/simppassforfree/ 目录设置为共享存储(例如 NFS、SMB)
- 确保所有服务器对该共享目录具有读写权限
- 所有服务器将共享相同的用户绑定数据
? 安全建议
-
保护开发者 UUID
- 不要与他人分享您的开发者 UUID
- 如果泄露,请定期更改 UUID
- 使用环境变量或加密配置文件存储 UUID
-
服务器安全
- 定期更新服务器和模组版本
- 使用防火墙限制服务器访问
- 启用服务器日志记录
-
监控异常行为
- 定期检查服务器日志
- 注意异常的登录尝试
- 及时处理安全事件
? 性能指标
- 验证延迟:平均 < 500ms
- API 响应时间:平均 < 300ms
- 内存占用:< 10MB
- CPU 占用:< 1%(空闲时)
- 并发支持:支持 100+ 名玩家同时在线验证
? 常见问题
Q: 如果玩家无法登录该怎么办?
A: 请检查以下内容:
- 确认玩家已正确绑定其 SimpPass UID
- 检查验证码是否正确(6 位数字)
- 确认证码未过期(120 秒内有效)
- 检查服务器网络连接是否正常
- 查看服务器日志以获取详细错误信息
Q: 如何重置玩家的绑定信息?
A: 删除 config/simppassforfree/<player_name>/user.json 文件,玩家需要重新绑定。
Q: 还支持哪些其他 Minecraft 版本?
A:
- Fabric 版本:
- ✅ 已发布:1.20.1, 1.20.2
- ? 开发中:1.14 - 1.20.0, 1.20.3 - 1.21.11
- Forge 版本:开发中,计划支持 1.12.2 - 1.21.11
- Paper 版本:开发中,计划支持 1.7.0 - 1.21.11(1.16.5 以下版本为 Spigot)
- 字节码注入版本:计划用于 Minecraft 1.21.11+ 版本,将支持所有主流加载器
- 其他版本:可通过自定义服务提供支持
Q: Forge/Paper 版本何时发布?
A: Forge 和 Paper 版本正在积极开发中,预计将在后续版本中发布。请关注项目更新以获取具体发布日期。
Q: 字节码注入版本的优点是什么?
A:字节码注入版本将针对 Minecraft 1.21.11+ 发布,具有以下优势:
- 全加载器兼容:自动支持 Fabric、Forge、Paper、Quilt 等所有主流加载器。
- 无需选择版本:一个版本适用于所有加载器。
- 性能更佳:通过字节码注入实现更高效的兼容性。
- 易于维护:统一的代码库降低了维护成本。
Q: 如何查看玩家登录日志?
A:登录日志记录在服务器控制台和日志文件中,可以使用日志分析工具进行查看。
Q: 验证失败的原因有哪些?
A:常见原因包括:
- 验证码错误或已过期
- SimpPass API 验证失败(可能涉及 IP、地理位置、风控因素等)
- 网络连接问题
- 开发者 UUID 配置错误
?️ 开发路线图
当前阶段(已完成)
- ✅ Fabric 1.20.1 版本
- ✅ Fabric 1.20.2 版本
- ✅ 核心功能实现
- ✅ 多种安全验证机制
短期计划(进行中)
- ? 其他 Fabric 版本(1.14 - 1.20.0, 1.20.3 - 1.21.11)
- ? Forge 版本开发(1.12.2 - 1.21.11)
- ? Paper/Spigot 版本开发(1.7.0 - 1.21.11)
中期计划
- ? 支持更多加载器(Quilt、NeoForge 等)
- ? 性能优化与代码重构
- ? 增强安全机制
- ? 完成各版本的全面兼容性测试
长期计划
- ? Minecraft 1.21.11+ 字节码注入版本
- ? 全加载器自动兼容
- ? 统一代码库与维护流程
- ? 向后兼容支持(支持更早的 Minecraft 版本)
? 许可证
本项目基于 GPL-3.0 许可证授权。
? 贡献指南
欢迎贡献!请随时提交 Issue 和 Pull Request。
? 联系方式
? 致谢
感谢所有为本项目做出贡献的开发者和用户!
注意:使用此模组即表示您同意遵守相关法律法规及服务器规则。请勿将此模组用于非法用途。
版本信息:
- 当前版本:Fabric 1.20.1/1.20.2
- 开发中:
- Fabric:1.14 - 1.20.0, 1.20.3 - 1.21.11
- Forge:1.12.2 - 1.21.11
- Paper/Spigot:1.7.0 - 1.21.11(1.16.5 以下版本使用 Spigot)
- 计划中:字节码注入版本(Minecraft 1.21.11+)
SimpPassForFree - Authentication & Login Mod
A cross-loader Minecraft player authentication and login system that provides reliable identity verification for servers.
? Overview
SimpPassForFree is a player authentication mod designed for Minecraft Fabric servers. It solves scenarios requiring reliable authentication by integrating with the SimpPass API, effectively preventing alt accounts and verification code abuse through multiple security mechanisms.
Current Version: Fabric 1.20.1 and 1.20.2
Development Plan: Forge and Paper versions in development
Future: Bytecode injection version for Minecraft 1.21.11+ with full loader compatibility
✨ Features
? Security Verification Mechanism
This mod uses the official SimpPass API for player identity verification, which integrates multiple security mechanisms:
1. WeChat Mini Program Verification
- Players need to obtain verification codes through WeChat Mini Program
- WeChat account real-name authentication ensures player identity authenticity
- Prevents batch registration and fake accounts
2. SimpPass API Security Verification
- Verification through the official SimpPass API
- API-side integration of multiple security mechanisms (including IP checks, geolocation, risk control, etc.)
- Ensures security and reliability of the verification process
?️ In-Game Security Protection
Login Status Management
- Unauthenticated Restrictions: Players who haven't passed verification cannot perform any game operations
- Cannot move (position locked)
- Cannot use items and block interactions
- Cannot use most game commands
- Cannot send chat messages (except whitelisted commands)
Session Management
- 120-second Verification Window: Players have 120 seconds to complete verification after joining the server
- Auto Kick: Players who fail to verify within the timeout will be automatically kicked
- Session Protection: Prevents session hijacking and replay attacks
Data Persistence
- Player binding information stored locally
- Automatic recording of last login time
- Support for multi-server shared configuration (via configuration files)
? User Experience Optimization
- Friendly Messages: Clear login guidance and error prompts
- Quick Verification Process: Simplified two-step verification (bind + verification code)
- Auto-Recognition: Automatically recognizes bound users for direct verification code login
- Login Status Broadcast: Players can see other players' login status in the server
? Quick Start
Requirements
- Minecraft Version: 1.20.1 or 1.20.2
- Fabric Loader: ≥ 0.18.4
- Fabric API: Latest version
- Java: 17 or higher
Installation
-
Download the Mod
- Download the JAR file for your Minecraft version from the Releases page
-
Install Fabric Loader
- If not already installed, visit the Fabric website to download and install Fabric Loader
-
Install Fabric API
-
Install the Mod
- Place the downloaded mod JAR file into your server's
mods directory
- Restart the server
-
Configure Developer UUID
- After the server starts, the mod will create a configuration file in
config/simppassforfree/
- Edit the configuration file and enter your SimpPass developer UUID
- Restart the server for the configuration to take effect
Configuration
Configuration file location: config/simppassforfree/config.json
{
"developer_uuid": "your-developer-uuid-here",
"session_timeout_seconds": 120,
"kick_on_timeout": true
}
Configuration Options:
developer_uuid: Your SimpPass developer UUID (required)
session_timeout_seconds: Verification session timeout in seconds, default 120
kick_on_timeout: Whether to automatically kick players on timeout, default true
? Usage Guide
Player Flow
First-Time Login (Account Binding)
- After joining the server, players receive a welcome message and login prompt
- Players need to obtain their SimpPass UID from the WeChat Mini Program
- Use the command in-game:
/auth <SimpPassUID>
- The system will verify the UID's validity
- After successful verification, players need to complete login using a verification code within 120 seconds
Bound User Login
- After joining the server, the system automatically detects bound accounts
- Players obtain a verification code from the WeChat Mini Program
- Use the command in-game:
/p <verification_code>
- The system verifies the code through the SimpPass API
- After successful verification, players can play normally
Commands
/auth <SimpPassUID>
- Function: Bind or verify SimpPass UID
- Permission: All players
- Description:
- First use: Bind a new SimpPass account
- Already bound: Start verification process, prompt to use
/p command
/p <verification_code>
- Function: Complete login verification using verification code
- Permission: All players
- Description:
- Must be used within 120 seconds after binding UID
- Verification code obtained from WeChat Mini Program
- After successful verification, players can play normally
Whitelisted Commands
Unauthenticated players can use the following commands:
/p - Verification code login command
/auth - Account binding command
/help - Help command
/list - View online players
/me - Action command
/tell, /msg, /w, /r - Private message commands
/tellraw - Raw message command
/version - Version information
/seed - Seed information
/scoreboard - Scoreboard commands
/team - Team commands
/bossbar - Boss bar commands
/datapack - Datapack commands
? Technical Architecture
Loader Compatibility Design
This mod uses a modular design, separating core functionality from loader-specific implementations:
- Core Modules: Cross-loader common core functionality (user data management, API client, etc.)
- Loader Adapter Layer: Loader-specific implementations (Fabric, Forge, Paper, etc.)
- Unified Interface: Cross-loader compatibility through unified interfaces
Core Modules
- User Data Management (
UserDataManager): Manages player binding information and user data persistence
- Authentication Session Management (
AuthSessionManager): Manages login sessions and verification flow
- Player Authentication Management (
PlayerAuthManager): Manages player login status and permission control
- API Client (
SimpPassApiClient): Communicates with SimpPass API server
- Command Handlers (
AuthCommands): Handles player authentication-related commands (loader-specific implementation)
- Command Interceptor (
CommandInterceptor): Intercepts command execution for unauthenticated players (loader-specific implementation)
- Event Handlers (
PlayerJoinHandler, AuthEventHandler): Handles player join and authentication events (loader-specific implementation)
Future Architecture: Bytecode Injection Version
In Minecraft 1.21.11+ version, we will release a bytecode injection version:
- Bytecode Injection: Direct bytecode injection using tools like ASM, no loader-specific implementation needed
- Auto-Detection: Automatically detects the loader type used by the server
- Unified Implementation: One codebase works for all loaders
- Performance Optimization: Reduces adapter layer overhead, improves performance
Security Mechanism Implementation
-
SimpPass API Verification
- User verification through the official SimpPass API
- API-side handling of IP addresses, geolocation, and other security checks
- Ensures security and reliability of the verification process
-
Session Management
- 120-second verification window, automatic expiration on timeout
- Prevents session replay attacks
- Automatic cleanup of expired sessions
-
In-Game Protection
- Unauthenticated players cannot perform game operations
- Position locking prevents unauthorized movement
- Command interception protects server security
?️ Advanced Configuration
Custom Verification Timeout
Modify the session_timeout_seconds value in the configuration file (in seconds):
{
"session_timeout_seconds": 180
}
Configure Timeout Kick Behavior
You can configure whether to automatically kick players on timeout:
{
"kick_on_timeout": false
}
When set to false, timed-out players will not be automatically kicked but still cannot perform game operations.
Multi-Server Configuration Sharing
If you have multiple servers, you can share user data:
- Set the
config/simppassforfree/ directory as shared storage (e.g., NFS, SMB)
- Ensure all servers have read/write permissions to the shared directory
- All servers will share the same user binding data
? Security Recommendations
-
Protect Developer UUID
- Do not share your developer UUID with others
- Regularly change UUID if leaked
- Use environment variables or encrypted configuration files to store UUID
-
Server Security
- Regularly update server and mod versions
- Use firewall to restrict server access
- Enable server log recording
-
Monitor Abnormal Behavior
- Regularly check server logs
- Pay attention to abnormal login attempts
- Handle security incidents promptly
? Performance Metrics
- Verification Latency: Average < 500ms
- API Response Time: Average < 300ms
- Memory Usage: < 10MB
- CPU Usage: < 1% (when idle)
- Concurrent Support: Supports 100+ players simultaneously verifying online
? Frequently Asked Questions
Q: What should I do if a player cannot log in?
A: Please check the following:
- Confirm the player has correctly bound their SimpPass UID
- Check if the verification code is correct (6 digits)
- Confirm the verification code has not expired (within 120 seconds)
- Check if the server network connection is normal
- View server logs for detailed error information
Q: How do I reset a player's binding information?
A: Delete the config/simppassforfree/<player_name>/user.json file, and the player will need to rebind.
Q: What other Minecraft versions are supported?
A:
- Fabric Version:
- ✅ Released: 1.20.1, 1.20.2
- ? In Development: 1.14 - 1.20.0, 1.20.3 - 1.21.11
- Forge Version: In development, planned support for 1.12.2 - 1.21.11
- Paper Version: In development, planned support for 1.7.0 - 1.21.11 (Spigot for versions below 1.16.5)
- Bytecode Injection Version: Planned for Minecraft 1.21.11+ version, will support all mainstream loaders
- Other Versions: Can be supported through custom services
Q: When will Forge/Paper versions be released?
A: Forge and Paper versions are actively under development and are expected to be released in future versions. Please follow project updates for specific release dates.
Q: What are the advantages of the bytecode injection version?
A: The bytecode injection version will be released for Minecraft 1.21.11+ with the following advantages:
- Full Loader Compatibility: Automatically supports all mainstream loaders like Fabric, Forge, Paper, Quilt, etc.
- No Version Selection: One version works for all loaders
- Better Performance: More efficient compatibility through bytecode injection
- Easy Maintenance: Unified codebase reduces maintenance costs
Q: How do I view player login logs?
A: Login logs are recorded in the server console and log files, which can be viewed using log analysis tools.
Q: What are the reasons for verification failure?
A: Common reasons include:
- Incorrect or expired verification code
- SimpPass API verification failure (may include IP, geolocation, risk control factors, etc.)
- Network connection issues
- Incorrect developer UUID configuration
?️ Development Roadmap
Current Stage (Completed)
- ✅ Fabric 1.20.1 version
- ✅ Fabric 1.20.2 version
- ✅ Core functionality implementation
- ✅ Multiple security verification mechanisms
Short-term Plan (In Progress)
- ? Other Fabric versions (1.14 - 1.20.0, 1.20.3 - 1.21.11)
- ? Forge version development (1.12.2 - 1.21.11)
- ? Paper/Spigot version development (1.7.0 - 1.21.11)
Mid-term Plan
- ? Support for more loaders (Quilt, NeoForge, etc.)
- ? Performance optimization and code refactoring
- ? Enhanced security mechanisms
- ? Complete compatibility testing for various versions
Long-term Plan
- ? Minecraft 1.21.11+ bytecode injection version
- ? Full loader automatic compatibility
- ? Unified codebase and maintenance process
- ? Backward compatibility support (support for earlier Minecraft versions)
? License
This project is licensed under the GPL-3.0 license.
? Contributing
Contributions are welcome! Please feel free to submit Issues and Pull Requests.
? Contact
- Issue Reporting: GitHub Issues
- Custom Services:
- Technical Support: Contact through the custom services website
? Acknowledgments
Thanks to all developers and users who have contributed to this project!
Note: Using this mod means you agree to comply with relevant laws, regulations, and server rules. Please do not use this mod for illegal purposes.
Version Information:
- Current Version: Fabric 1.20.1/1.20.2
- In Development:
- Fabric: 1.14 - 1.20.0, 1.20.3 - 1.21.11
- Forge: 1.12.2 - 1.21.11
- Paper/Spigot: 1.7.0 - 1.21.11 (Spigot for versions below 1.16.5)
- Planned: Bytecode injection version (Minecraft 1.21.11+)
评论 0
登录后参与评分
还没有评论,来抢沙发吧