Logo
simppassforfree
ModAGPL-3.0-or-later

simppassforfree

a good minecraft Identity verification project, can work for Mainstream Loaders

18
Downloads
1
Followers
3 months ago
Updated
📦
2
Versions
managementfabric
Download Latestv1.0.0View on Modrinth

📖About simppassforfree

SimpPassForFree - Authentication & Login Mod

Minecraft Version
Fabric
License

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

  1. Download the Mod

    • Download the JAR file for your Minecraft version from the Releases page

  2. Install Fabric Loader

    • If not already installed, visit the Fabric website to download and install Fabric Loader

  3. Install Fabric API

  4. Install the Mod

    • Place the downloaded mod JAR file into your server's mods directory
    • Restart the server

  5. 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)

  1. After joining the server, players receive a welcome message and login prompt
  2. Players need to obtain their SimpPass UID from the WeChat Mini Program
  3. Use the command in-game: /auth <SimpPassUID>
  4. The system will verify the UID's validity
  5. After successful verification, players need to complete login using a verification code within 120 seconds

Bound User Login

  1. After joining the server, the system automatically detects bound accounts
  2. Players obtain a verification code from the WeChat Mini Program
  3. Use the command in-game: /p <verification_code>
  4. The system verifies the code through the SimpPass API
  5. 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

  1. 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

  2. Session Management

    • 120-second verification window, automatic expiration on timeout
    • Prevents session replay attacks
    • Automatic cleanup of expired sessions

  3. 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:

  1. Set the config/simppassforfree/ directory as shared storage (e.g., NFS, SMB)
  2. Ensure all servers have read/write permissions to the shared directory
  3. All servers will share the same user binding data

🔒 Security Recommendations

  1. 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

  2. Server Security

    • Regularly update server and mod versions
    • Use firewall to restrict server access
    • Enable server log recording

  3. 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:

  1. Confirm the player has correctly bound their SimpPass UID
  2. Check if the verification code is correct (6 digits)
  3. Confirm the verification code has not expired (within 120 seconds)
  4. Check if the server network connection is normal
  5. 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

🙏 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+)