VeloAuth

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

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

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

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)

[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)

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)

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 <password> <confirm>	Register a new account	Hidden once logged in
/login <password>	Log into your account	Available in auth/limbo
/logout	Invalidate session & disconnect	Clean disconnect; requires /login upon return
/changepassword <old> <new>	Update your account password	Requires active session
/2fa setup	Begin TOTP authenticator setup	Requires active session
/2fa verify <code>	Confirm TOTP setup or submit 2FA code	Standard RFC 6238 TOTP
/2fa disable <code>	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
/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 <nickname>	Administrative 2FA reset for recovery
/unregister <nickname>	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
• Issue Tracker: GitHub Issues
• Community & Support: Discord Server
• Documentation: 2FA Guide | Changelog
• License: MIT