Skip to main content

Authentication & Limbo Core

BharatMC's login engine runs an In-Process Netty Auth Limbo within the Velocity proxy JVM, terminating packet streams locally and routing verified connections to backend Paper servers without intermediate lobby servers.

⚡ Core Engine Features​

1. Centralized Redis Connection Pool & Provider API​

To avoid opening redundant socket connections across Velocity plugins, bharatmc-login hosts a high-concurrency Lettuce + Apache Commons Pool2 instance (maxTotal: 16, minIdle: 2, testOnBorrow: true):

  • Exposed publicly to sister plugins (BharatMCSocial, BharatMCVoteVelocity) via BharatLoginAPI.get().withRedis(...) and BharatLoginAPI.get().runRedis(...).
  • Eliminates Connection Leaks: Subordinate plugins borrow connections from the master pool rather than instantiating separate Lettuce clients.
  • PreLogin Thread Safety: Ensures concurrent player handshakes cannot clobber or block each other's Redis calls.
  • Caffeine Fallback Cache: In the event of temporary network blips, an in-memory 60-second bounded cache handles transient validations without stale authentication risk.

2. In-Process Netty Virtual Limbo​

  • Emulates a lightweight Minecraft world directly in Velocity memory.
  • Uses multi-version NBT dimension codecs (codec_1_16.nbt through codec_26_2.nbt) so players on any modern Minecraft client (1.16 to 1.21.x) can connect and authenticate without seeing packet decode errors.
  • Players cannot move, chat, or execute non-whitelisted commands while trapped in Limbo.

3. Sticky IP Sessions (session-expiry-hours: 24)​

  • When a player authenticates successfully, their IP and UUID lease are cached in Redis.
  • If they disconnect and rejoin from the exact same IP address within 24 hours, they bypass /login entirely.

4. 120-Second Fast-Reconnect Grace Period​

  • If a player times out or disconnects during active gameplay (e.g., in PvP or dungeon raids):
    • Their last connected sub-server (e.g. lifesteal, survival, skyblock) is retained in memory.
    • Reconnecting within 120 seconds routes them directly back to their last server, completely bypassing the Hub/Lobby.

5. Hybrid Bedrock, Cracked & Mojang Premium​

  • Bedrock (Geyser/Floodgate): Xbox Live authenticated players (prefixed with *) are automatically logged in upon connection.
  • Mojang Premium FastLogin (/premium): Original Minecraft Java players can bind their account to Mojang online-mode cryptographic authentication to skip password prompts forever.
  • Cracked (/cracked): Reverts account verification back to password prompts.

⚙️ Full Configuration: config.yml​

Below is the complete verbatim configuration for bharatmc-login:

# BharatMC Auth System Configuration
# Debug mode — accepts both: 'debug: true' OR 'debug:\n  enabled: true'
debug: false

use-limbo: true
# In-process Netty high-performance auth server running directly inside the Velocity proxy.
# Zero external dependencies, zero latency, seamless routing.
embedded-auth-limbo: true

auth-limbo:
  # Name of the Limbo server registered in velocity.toml [servers]
  server-name: "auth-limbo"
  # Enforces cryptographic secure chat signing (1.19+).
  # Set to false to allow offline/cracked and unverified clients without chat errors.
  enforces-secure-chat: false

api:
  url: "https://api.bharatmc.net"
  key: "YOUR_API_KEY"

database:
  postgresql:
    host: "127.0.0.1"
    port: 5432
    database: "bharatmc_main"
    username: "bharatmc_user"
    password: "YOUR_DB_PASSWORD"
  redis:
    host: "127.0.0.1"
    port: 6379
    password: "YOUR_REDIS_PASSWORD"

security:
  # Max cracked accounts allowed per IP address (registration cap)
  max-accounts-per-ip: 3
  # Whether to block players from REGISTERING if they exceed the IP limit
  block-registrations-over-ip-limit: true
  # Whether to block players from LOGGING IN if their IP is over the account limit
  block-logins-over-ip-limit: false
  # Auto-login players if they rejoin from the same IP (sticky sessions)
  sticky-ip-session: true
  # Session duration in seconds (default: 86400 = 24 hours)
  session-expiry-hours: 24
  # Authentication timeout in seconds (kicks player if they do not login/register in time)
  auth-timeout: 60
  # Automatic Premium Username Hijack Protection
  hijack-protection: true
  # Cosmetic/Skin UUID support (Lunar Client fix)
  cosmetic-uuid-support: true

# ─────────────────────────────────────────────────────────────────────────────
# Analytics & Session Tracking
# ─────────────────────────────────────────────────────────────────────────────
analytics:
  # Timezone for all timestamps sent to the backend and written to the database.
  # Uses Java ZoneId format. Examples: Asia/Kolkata, UTC, America/New_York, Europe/London
  timezone: "Asia/Kolkata"
  # How often (in seconds) the proxy sends a server analytics heartbeat to Redis.
  # Lower = more real-time dashboard, higher = less load. Min: 5s, Recommended: 30s
  heartbeat-interval: 30

# ─────────────────────────────────────────────────────────────────────────────
# Queue System
# ─────────────────────────────────────────────────────────────────────────────
queue:
  enabled: true
  max-players: 50

# ─────────────────────────────────────────────────────────────────────────────
# Grace Period - Last Server Fast-Reconnect
# ─────────────────────────────────────────────────────────────────────────────
# When a player disconnects, their last server is remembered.
# If they reconnect within 'seconds', they are sent directly back to that server
# instead of going through lobby. Works with dynamic server names via prefix matching.
#
# IP tracking note:
#   first_address = IP when the account was first registered (never changes)
#   last address  = most recent IP (updates every login)
#   IP history    = full log in user_ips table (all unique IPs with timestamps)
grace-period:
  enabled: true
  # How many seconds the grace period lasts after disconnect
  seconds: 120

  # Servers eligible for grace period redirect.
  # Use the server name from velocity.toml (or a prefix of it).
  # Example: 'lifesteal' will match 'lifesteal', 'lifesteal1', 'lifesteal2', etc.
  # Leave empty to allow ALL servers (except excluded ones below).
  servers:
    - lifesteal
    - survival
    - skyblock
    - prison
    - factions
    - minigames
    - creative
    - pvp
    - bedwars
    - skywars

  # Servers that are NEVER eligible for grace period redirect.
  # Add hub, lobby, and auth servers here to prevent routing back to them.
  excluded-servers:
    - lobby
    - hub
    - auth
    - limbo
    - proxy

bot-protection:
  # Global join rate limit (per second) across all proxies
  max-joins-per-second: 10

branding:
  prefix: "<gradient:#00C9FF:#92FE9D>✦ BHARAT</gradient> <dark_gray>»</dark_gray> "
  error-prefix: "<gradient:#FF416C:#FF4B2B>✕ SYSTEM</gradient> <dark_gray>»</dark_gray> "

messages:
  require-ping-kick: "<gradient:#FF416C:#FF4B2B>✕ VERIFICATION REQUIRED</gradient>\n\n<gray>Please refresh your server list to authenticate your connection.</gray>\n<dark_gray>Reason: Anti-Bot Handshake Required</dark_gray>"
  ip-blocked: "<gradient:#FF416C:#FF4B2B>✕ ACCESS RESTRICTED</gradient>\n\n<gray>Your IP address has been temporarily rate-limited.</gray>\n<dark_gray>Please wait a few minutes or contact support on Discord.</dark_gray>"
  max-accounts-reached: "<gradient:#FF416C:#FF4B2B>✕ REGISTRATION CAP</gradient>\n\n<gray>You have reached the maximum allowed accounts for this IP.</gray>"
  login-success: "<gradient:#00C9FF:#92FE9D>✦ BHARAT</gradient> <dark_gray>»</dark_gray> <white>Welcome back to <gradient:#00C9FF:#92FE9D>BharatMC</gradient>!</white>"
  already-connected: "<gradient:#FF416C:#FF4B2B>✕ SESSION ACTIVE</gradient>\n\n<gray>You are already connected to this proxy network.</gray>\n<dark_gray>Terminating stale session...</dark_gray>"