LoginX — Player Authentication & Session Protection

LoginX is a secure, modern authentication plugin for Minecraft servers that require players to register and log in. It protects accounts with encrypted passwords, persistent sessions, client fingerprinting, and a two-phase Mojang premium verification system — all built with async database operations for minimal server impact.

---

Why LoginX?

LoginX was designed with a clean, layered architecture separating auth, session, security, and premium logic. It goes beyond basic login/register by actively protecting against account takeovers, alt account flooding, brute-force attacks, and replay attacks — out of the box, with zero extra setup.

---

Core Features

🔑 Authentication

• Password hashing with Argon2 or bcrypt (configurable in config.yml)
• Configurable minimum password length
• Login timeout — players who don't authenticate within N seconds are kicked
• /changepass command for players to update their own password securely

🕐 Session Management

• Persistent sessions — authenticated players are remembered across reconnects
• Rolling sessions — activity extends the session timer automatically
• Sessions are invalidated on IP change to prevent session hijacking
• Sessions are invalidated on fingerprint change for extra protection
• Automatic session cleanup task runs in the background to purge expired sessions

🖐 Client Fingerprinting

• Tracks each player's client brand and protocol version on join
• Detects when a player's fingerprint changes and can block or flag it
• Configurable max fingerprint changes per 7 days to limit suspicious behaviour
• Stricter fingerprint enforcement available for premium-locked accounts

⭐ Premium Account Linking (/premium) FIXING IT

LoginX uses a two-phase Mojang verification handshake to let players permanently link their account to their real Mojang/Microsoft identity:

1. Player runs /premium → LoginX queries the Mojang Profiles API to confirm the username exists
2. Player is kicked and asked to reconnect within 60 seconds using the official launcher
3. On reconnect, LoginX verifies the session against Mojang's session servers using a unique token
4. If verified → account is permanently premium-locked to the real Mojang UUID
5. Premium-locked players are auto-logged in on future joins — no password prompt needed

This prevents name impersonation: anyone can claim a premium username, but only the real account owner can pass the session server check.

🛡️ Security

• Brute-force protection — account is temporarily locked after too many failed login attempts (configurable threshold and ban duration)
• Alt account limiting — max registered accounts per IP address
• Anti-replay protection — blocks reuse of intercepted authentication tokens
• Console log filtering — sensitive auth details are stripped from server logs

🗄️ Database

• Supports SQLite (zero-config, default) and MySQL
• Fully async database operations — no blocking the main thread
• Separate tables for player accounts, sessions, and fingerprint change history

---

✦ Commands

| Command | Description | Permission |
|---|---|---|
| /register <password> <confirm> | Create a new account | loginx.player |
| /login <password> | Log in to your account | loginx.player |
| /logout | End your current session | loginx.player |
| /changepass <old> <new> <confirm> | Change your password | loginx.player |
| /premium | Link account to Mojang via 2-phase verification | loginx.premium |
| /loginx reload | Reload config and messages | loginx.admin |
| /loginx info | View plugin status and stats | loginx.admin |
| /loginx session <player> | Inspect a player's session | loginx.admin |
| /loginx forcepremium <player> | Force-lock an account as premium | loginx.admin |

---

✦ Permissions

| Permission | Default | Description |
|---|---|---|
| loginx.player | everyone | Basic auth commands |
| loginx.premium | everyone | Access to /premium |
| loginx.admin | op | All admin commands |
| loginx.bypass | false | Skip authentication entirely |

---

✦ Configuration Highlights

auth:
  min-password-length: 8
  login-timeout-seconds: 30
  password-hash: ARGON2  # or BCRYPT

session:
  enabled: true
  timeout-minutes: 30
  rolling: true
  invalidate-on-ip-change: true
  invalidate-on-fingerprint-change: true

fingerprint:
  enabled: true
  max-changes-per-7d: 1

security:
  max-accounts-per-ip: 3
  brute-force:
    max-attempts: 5
    temp-ban-minutes: 10

database:
  type: sqlite  # or mysql

All messages are fully customizable via messages.yml.

---

✦ Developer API

LoginX exposes a public LoginXAPI class for third-party plugin integration. Check session state, listen to auth events, and more. Full documentation is available on the GitHub repository.

---

✦ Compatibility

| Platform | Status |
|---|---|
| Paper 1.20+ | ✅ Fully supported |
| Spigot | ✅ Supported |
| Bukkit | ⚠️ May work, not tested |

Java 17+ required · Minecraft 1.20+

---

✦ Support & Links

• 💻 Source code → GitHub

Please do not use Modrinth comments for bug reports.

NOTE There is problems with /premium I am working on it