VeloAuth

# VeloAuth [](https://modrinth.com/plugin/veloauth) [](https://discord.gg/e2RkPbc3ZR) [](https://github.com/rafalohaki/VeloAuth/blob/main/LICENSE) [](https://bstats.org/plugin/velocity/VeloAuth) [](https://ko-fi.com/rafalo) **Complete Velocity authentication plugin** with intelligent nickname protection, premium auto-login, secure offline player management, and optional self-contained embedded limbo. ## What is VeloAuth? VeloAuth is a comprehensive authentication system for Velocity proxy that handles all player authorization before they reach your backend servers. It includes a loopback-only embedded limbo while maintaining full compatibility with existing external limbo servers, all while protecting nickname ownership through intelligent conflict resolution. ## Live test server Want to see VeloAuth in action? **[2b2t.pl](https://2b2t.pl)** runs the plugin in production — join the server to test premium auto-login, offline registration and nickname protection on a live network. ## Key Features - 🔒 **Intelligent Nickname Protection** - Premium nicknames are reserved unless already registered by cracked players. - ⚡ **Premium Auto-Login** - Mojang account owners skip password entry after session verification; auth/limbo passthrough is an opt-in bypass. - 🔄 **Automatic Nickname Change Detection** - Detects when a premium player renames their Mojang account and updates the database record automatically. - 🛡️ **Secure Offline Auth** - BCrypt password hashing, brute-force protection, and atomic first-owner registration enforced by the database. - 📱 **Optional Floodgate Support** - Bedrock and linked Floodgate accounts are detected before Mojang resolution; only UUIDs confirmed by Floodgate can bypass the auth server. - 🧩 **Optional Self-Contained Limbo** - Use the built-in 1.8-base limbo with a reviewed, checksum-pinned ViaVersion runtime, or keep using an external limbo (NanoLimbo, etc.). - 🗺️ **Forced Hosts Support** - Players connect via custom domains (e.g., `pvp.server.com`) and are properly routed to their intended server *after* authentication. - 🚫 **Smart Command Hiding** - Authentication commands (`/login`, `/register`) are hidden while authorization is active; expired sessions expose them again. - 🚀 **High Performance** - Bounded three-layer premium cache (in-memory → DB → Mojang/Ashcon API), virtual threads (Java 21), and zero blocking on Velocity event loops. - 🔐 **Optional 2FA (TOTP)** - Opt-in RFC 6238 second factor compatible with Google Authenticator, Authy, Aegis. See [2FA.md](https://github.com/rafalohaki/VeloAuth/blob/main/2FA.md) for the operator handbook. - 🔄 **Conflict Resolution** - Smart handling of premium/cracked nickname conflicts with `/vauth conflicts`. - 📊 **Admin & Diagnostic Tools** - Health checks, statistics, and 1-click sanitized diagnostic reports via `/vauth report` (mclo.gs). - 🗄️ **Multi-Database** - MySQL, PostgreSQL, H2, and SQLite with HikariCP connection pooling. - 🌍 **17 Languages & HEX Formatting** - EN, PL, DE, FR, RU, TR, SI, FI, ZH_CN, ZH_HK, JA, HI, VI, KO, TH, ID, PT_BR with full RGB/HEX color support. - 🔄 **LimboAuth Compatible** - 100% database schema compatibility with automatic, additive in-place migrations. - 📢 **Discord Alerts** - Webhook notifications for security anomalies and resolver failure spikes with automated retry logic. ## When to use VeloAuth - **You run a Velocity proxy** with one or more backend servers and need authentication at the proxy layer (not per-backend). - **You accept both premium and cracked players** and need automatic, fail-secure routing — premium players skip `/login`, cracked players go through BCrypt-hashed registration. - **You already use LimboAuth** and want to migrate without losing data — VeloAuth reads and upgrades the same schema seamlessly. - **You want high performance** — premium status is resolved through a three-layer cache without blocking proxy event loops. If you only run a single backend server (Paper/Spigot/Folia) without a proxy, use a backend-side auth plugin instead. ## Operating Profiles Choose how strict nickname protection should be in `plugins/veloauth/config.yml`: ### Profile 1 — **Mixed strict** (default, recommended) ```yaml premium: check-enabled: true allow-cracked-on-premium-nicks: false bypass-auth-server: false ``` * **What you get:** Premium players auto-login with real Mojang UUIDs; cracked players go through `/register` + BCrypt; **premium nicknames are strictly reserved** for Mojang owners. * **What you lose:** Cracked clients trying to join with a registered Mojang username are rejected (*"You are not logged into your Minecraft account"*). * **Best for:** Public servers accepting both types of players where nickname theft prevention matters. ### Profile 2 — **Cracked-only** ```yaml premium: check-enabled: false ``` * **What you get:** Zero HTTP traffic to Mojang/Ashcon, deterministic offline UUIDs for everyone. * **What you lose:** Premium auto-login is disabled for all players; first player to register a nickname owns it. * **Best for:** Private networks, dev environments, or pure offline-mode setups. ### Profile 3 — **Permissive mixed** ```yaml premium: check-enabled: true allow-cracked-on-premium-nicks: true ``` * **What you get:** Existing premium accounts retain premium UUIDs; cracked players can register unclaimed premium-looking usernames. * **What you lose:** New premium players connecting for the first time receive offline UUIDs permanently if not pre-registered as premium. * **Best for:** Cracked-first communities that prioritize admitting all players without kick screens. | Goal | Recommended Profile | | --- | --- | | Maximum security, premium UUIDs preserved | **1 — Mixed strict** | | No Mojang calls, pure offline network | **2 — Cracked-only** | | Accept all connections, unreserved nicknames | **3 — Permissive mixed** | --- ## Requirements * **Java 21 or newer** (tested on Temurin 21) * **Velocity Proxy** (3.4.0+ / 3.5.x line) * **Database**: MySQL, PostgreSQL, H2 (default), or SQLite * **Auth Server Topology**: * **External (default)**: NanoLimbo, LOOHP/Limbo, LimboService, PicoLimbo, or similar. * **Embedded (optional)**: Built-in 1.8 loopback limbo (requires outbound HTTPS to ViaVersion maven repo for runtime staging). --- ## Quick Setup ### 1. Installation 1. Download the latest `veloauth-X.X.X.jar` from Modrinth. 2. Drop it into your Velocity `plugins/` folder. 3. Start and stop Velocity to generate configuration files in `plugins/veloauth/`. 4. Configure database details and auth settings in `plugins/veloauth/config.yml`. 5. Start Velocity. ### 2. Velocity Configuration (`velocity.toml`) ```toml [servers] limbo = "127.0.0.1:25566" # External limbo server (keep out of try list!) lobby = "127.0.0.1:25565" # Primary backend lobby survival = "127.0.0.1:25567" # Secondary backend server try = ["lobby", "survival"] # Fallback backend order for authenticated players [forced-hosts] # Players joining via survival.example.com authenticate in limbo, # then get routed directly to 'survival' instead of 'lobby'. "survival.example.com" = ["survival"] ``` ### 3. VeloAuth Configuration (`plugins/veloauth/config.yml`) ```yaml language: en auth-server: # 'external' (default) uses registered limbo server; 'embedded' starts loopback limbo. mode: external server-name: limbo timeout-seconds: 300 embedded: port: 0 # 0 = auto-select loopback port max-connections: 512 handshake-timeout-seconds: 10 login-timeout-seconds: 15 premium: check-enabled: true allow-cracked-on-premium-nicks: false # Set to true only if verified premium players should skip the auth-server completely bypass-auth-server: false # Optional Floodgate integration floodgate: enabled: false username-prefix: "." bypass-auth-server: true ``` #### Password Complexity Policy (Optional) ```yaml security: min-password-length: 8 max-password-length: 72 password-policy: min-digits: 0 # e.g., 1 = require at least one digit min-uppercase: 0 # e.g., 1 = require at least one uppercase letter min-lowercase: 0 # e.g., 1 = require at least one lowercase letter min-special: 0 # e.g., 1 = require at least one symbol ``` --- ## Commands & Permissions ### Player Commands | Command | Description | Notes | | --- | --- | --- | | `/register ` | Register a new account | Hidden once logged in | | `/login ` | Log into your account | Available in auth/limbo | | `/logout` | Invalidate session & disconnect | Clean disconnect; requires `/login` upon return | | `/changepassword ` | Update your account password | Requires active session | | `/2fa setup` | Begin TOTP authenticator setup | Requires active session | | `/2fa verify ` | Confirm TOTP setup or submit 2FA code | Standard RFC 6238 TOTP | | `/2fa disable ` | Remove 2FA from account | Requires valid TOTP code | | `/2fa qr` / `/2fa status` | Show 2FA enrollment status | Re-enrollment instructions | ### Admin Commands (`veloauth.admin`) | Command | Description | | --- | --- | | `/vauth reload` | Reload configuration & language files | | `/vauth report` | Upload sanitized diagnostic bundle to [mclo.gs](https://mclo.gs) | | `/vauth stats` | Show runtime cache, thread, and connection stats | | `/vauth conflicts` | List active nickname ownership conflicts | | `/vauth cache-reset [player]` | Clear premium resolver/auth caches | | `/vauth 2fa-remove ` | Administrative 2FA reset for recovery | | `/unregister ` | Delete account record from database | --- ## LimboAuth Migration VeloAuth features **100% automatic LimboAuth schema migration**: 1. Stop LimboAuth on your backend servers. 2. Install VeloAuth on your Velocity proxy. 3. Configure `plugins/veloauth/config.yml` with the same database credentials. 4. Start Velocity. Existing accounts and `/premium` flags will be converted seamlessly on startup without manual UUID rewrites. --- ## Links & Support * **Source Code & Releases**: [GitHub Repository](https://github.com/rafalohaki/VeloAuth) * **Issue Tracker**: [GitHub Issues](https://github.com/rafalohaki/VeloAuth/issues) * **Community & Support**: [Discord Server](https://discord.gg/e2RkPbc3ZR) * **Documentation**: [2FA Guide](https://github.com/rafalohaki/VeloAuth/blob/main/2FA.md) | [Changelog](https://github.com/rafalohaki/VeloAuth/blob/main/CHANGELOG.md) * **License**: [MIT](https://github.com/rafalohaki/VeloAuth/blob/main/LICENSE)