VeloAuth

VeloAuth

Modrinth

Discord

License

bStats

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

- 🔒 bStats Analytics - Premium nicknames are reserved unless already registered by cracked players - ⚡ bStats Analytics - Mojang account owners skip authentication automatically - 🔄 bStats Analytics - Detects when a premium player renames their Mojang account and updates the database record automatically - 🛡️ bStats Analytics - BCrypt password hashing with brute-force protection - 📱 bStats Analytics - Bedrock players can bypass the auth server when Floodgate integration is enabled - 🗺️ bStats Analytics - Players connect via custom domains (e.g., `pvp.server.com`) and are properly routed to their intended server *after* authentication - 🚫 bStats Analytics - Authentication commands (`/login`, `/register`) are completely hidden from tab-completion once the player is logged in - 🚀 bStats Analytics - Three-layer premium resolution cache: in-memory → database → external API, with 24-hour premium status retention - 🔄 bStats Analytics - Smart handling of premium/cracked nickname conflicts - 📊 bStats Analytics - Complete conflict management with `/vauth conflicts` - 🗄️ bStats Analytics - MySQL, PostgreSQL, H2, SQLite - 🌍 bStats Analytics - EN, PL, DE, FR, RU, TR, SI, FI, ZH_CN, ZH_HK, JA, HI, VI, KO, TH, ID, PT_BR - 🔄 bStats Analytics - 100% database compatibility (no migration needed) - 📢 bStats Analytics - Webhook notifications for security events - 🧵 bStats Analytics - Built on Java 21 for maximum performance - 📈 bStats Analytics - Anonymous usage statistics via bStats

Requirements

- Database - Database (API 3.4.0+) - Database: 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:

```toml [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"] ```

unless 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. redirected to backend server to Velocity 2. redirected to backend server in-memory authorization cache (instant, no I/O) 3. If redirected to backend server, checks redirected to backend server (persistent across restarts) 4. If redirected to backend server, resolves via redirected to backend server in parallel using virtual threads 5. If redirected to backend server, player is sent to the redirected to backend server (unless Floodgate Bedrock bypass applies) 6. Player types redirected to backend server or redirected to backend server 7. redirected to backend server 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

- Automatic blocking unless already registered by cracked players - Automatic blocking when premium players use cracked-registered nicknames - Automatic blocking 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