VeloAuth

Complete Velocity authentication plugin with intelligent nickname protection, premium auto-login, and secure offline player management.

What is VeloAuth?

VeloAuth is a comprehensive authentication system for Velocity proxy that handles all player authorization before they reach your backend servers. It works with any limbo server to provide a smooth login experience while protecting nickname ownership through intelligent conflict resolution.

Key Features

• 🔒 Intelligent Nickname Protection - Premium nicknames are reserved unless already registered by cracked players
• ⚡ Premium Auto-Login - Mojang account owners skip authentication automatically
• 🔄 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 with brute-force protection
• 📱 Optional Floodgate Support - Bedrock players can bypass the auth server when Floodgate integration is enabled
• 🗺️ 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 completely hidden from tab-completion once the player is logged in
• 🚀 High Performance - Three-layer premium resolution cache: in-memory → database → external API, with 24-hour premium status retention
• 🔄 Conflict Resolution - Smart handling of premium/cracked nickname conflicts
• 📊 Admin Tools - Complete conflict management with /vauth conflicts
• 🗄️ Multi-Database - MySQL, PostgreSQL, H2, SQLite
• 🌍 17 Languages - EN, PL, DE, FR, RU, TR, SI, FI, ZH_CN, ZH_HK, JA, HI, VI, KO, TH, ID, PT_BR
• 🔄 LimboAuth Compatible - 100% database compatibility (no migration needed)
• 📢 Discord Alerts - Webhook notifications for security events
• 🧵 Virtual Threads - Built on Java 21 for maximum performance
• 📈 bStats Analytics - Anonymous usage statistics via bStats

Requirements

• Java 21 or newer
• Velocity proxy (API 3.4.0+)
• Limbo server: NanoLimbo, LOOHP/Limbo, LimboService, PicoLimbo, hpfxd/Limbo, or any other
• Database: MySQL, PostgreSQL, H2, or SQLite

Quick Setup

Installation

1. Download VeloAuth from Modrinth
2. Place the file in your Velocity plugins/ folder
3. Start Velocity - the plugin will create a config.yml file
4. Stop Velocity and configure your database and auth server name in plugins/VeloAuth/config.yml
5. Restart Velocity

Note: Floodgate support is disabled by default. Enable it only if you actually use Geyser/Floodgate.

Velocity Config

Configure your velocity.toml with your limbo/auth server and backend servers:

[servers]
limbo = "127.0.0.1:25566"  # Auth/limbo server (NanoLimbo, LOOHP/Limbo, etc.)
lobby = "127.0.0.1:25565"  # Typical backend server
survival = "127.0.0.1:25567" # Another backend server

try = ["lobby", "survival"]  # Order matters. Do NOT put 'limbo' here.

[forced-hosts]
# VeloAuth fully respects Velocity's forced hosts! 
# Players connecting via this IP will be sent to limbo to login, 
# and then seamlessly transferred to 'survival' instead of 'lobby'.
"survival.example.com" = ["survival"] 

Important: The try configuration controls where authenticated players are redirected by default. VeloAuth automatically skips the limbo server and selects the first available backend server, unless the player used a forced-host domain, in which case they are natively routed to their intended destination!

Discord Webhooks

VeloAuth supports Discord notifications for security events (failed login bursts, brute-force attempts, premium resolution failures). Configure the webhook URL in config.yml under alerts.discord.

Database Config

Supported: H2 (out-of-box), MySQL, PostgreSQL, SQLite

Player Commands

Command	Description	Restrictions
/register <password> <confirm>	Create new account	Hidden after login. No premium nicknames
/login <password>	Login to your account	Hidden after login. Works for all players
/changepassword <old> <new>	Change your password	Must be logged in

Admin Commands

Command	Permission	Description
/unregister <nickname>	veloauth.admin	Remove player account (resolves conflicts)
/vauth reload	veloauth.admin	Reload configuration
/vauth cache-reset [player]	veloauth.admin	Clear authorization cache
/vauth stats	veloauth.admin	Show plugin statistics
/vauth conflicts	veloauth.admin	List nickname conflicts

How It Works

Authentication Flow

1. Player connects to Velocity
2. VeloAuth checks in-memory authorization cache (instant, no I/O)
3. If not in memory, checks database premium cache (persistent across restarts)
4. If not in DB cache, resolves via Mojang/Ashcon API in parallel using virtual threads
5. If not premium, player is sent to the auth server (unless Floodgate Bedrock bypass applies)
6. Player types /login or /register
7. VeloAuth verifies credentials with BCrypt
8. Player is redirected to backend server via try configuration

Premium Resolution (3 layers)

Connect → [In-memory cache] → [Database cache] → [Mojang/Ashcon API]
              ~0ms                ~1ms                 ~200-500ms

All API calls run in parallel on virtual threads. Results are cached in the database and survive proxy restarts.

Nickname Change Detection

When a premium player logs in with a different username than what is stored (Mojang account rename), VeloAuth automatically detects the mismatch and updates the database record, keeping the UUID-to-username mapping accurate without any admin intervention.

Nickname Protection System

• Premium nicknames are reserved unless already registered by cracked players
• Conflict resolution when premium players use cracked-registered nicknames
• Admin tools for managing nickname conflicts
• Automatic blocking of cracked players trying premium nicknames

LimboAuth Migration

VeloAuth is 100% compatible with LimboAuth databases:

1. Stop LimboAuth on your backend servers
2. Install VeloAuth on Velocity
3. Configure VeloAuth to use the same database as LimboAuth
4. Start Velocity - all existing accounts will work automatically

Contributing

Contributions are welcome! Please open an issue or PR.

Support

Need help? Found a bug? Open an issue on GitHub or join our Discord server.

License

This project is licensed under the MIT License