SideGate - Velocity v1.2.2-hotfix.1

What Is SideGate Velocity?
SideGate Velocity performs the Premium/Guest login decision before a player reaches your backend servers.

Premium players stay on Velocity's normal online authentication path. Usernames that are not registered as Premium can be admitted as Guests using an allow-all policy or a username allowlist.

The companion SideGate Bukkit plugin receives the forwarded identity and applies Guest tags, gamemode, titles, messages, and chat prefix on each backend.

Core Features

• Proxy-Level Hybrid Login: Select online or offline authentication per connection.
• Asynchronous Premium Detection: Mojang profile checks do not block the proxy event thread.
• Fail-Closed Behavior: API errors and unexpected responses remain on Premium authentication.
• Guest Admission Policy: Allow every non-Premium username or use allowed-guests.
• Premium Overrides: Force configured usernames to always use Premium authentication.
• Premium-Name Protection: Replace Velocity's generic invalid-session response with a clear configurable message.
• Bedrock Support: Detect Floodgate/Geyser players and skip Java Premium/Guest classification.
• Floodgate-Friendly: Preserve Floodgate's authenticated offline login path and other existing pre-login decisions.
• Minecraft 1.20+ Guard: Reject older Java protocols with a configurable message.
• Modern Forwarding Validation: Disable routing when required proxy settings are unsafe or incomplete.
• Connection-Safe Tracking: Track Guest candidates per connection with expiration.
• Useful Logging: Optional PREMIUM, GUEST, DENIED, and UNAVAILABLE decision logs.
• Admin Commands: /sidegate reload and /sidegate status.
• Public API: Synchronous and asynchronous login evaluation for addon developers.

Requirements and External Dependencies
All required and optional external dependencies are disclosed below with publicly accessible links.

• Java:Java 17 or newer
  • https://adoptium.net/
• Proxy software:Velocity 3.4 or newer
  • https://papermc.io/software/velocity
  • https://docs.papermc.io/velocity/
• Minecraft Java: Minecraft Java 1.20 or newer
• Backend companion plugin:SideGate Bukkit 1.2.2 on every backend server
  • https://dev.tamkungz.me/documentation/sidegate/
• Backend dependency:ProtocolLib 5.x or newer
  • https://www.spigotmc.org/resources/protocollib.1997/
  • https://github.com/dmulloy2/ProtocolLib/releases/tag/dev-build
• Backend software:Paper-compatible server with Velocity forwarding support
  • https://papermc.io/software/paper
  • https://docs.papermc.io/velocity/player-information-forwarding/
• Forwarding:Velocity modern player forwarding
  • https://docs.papermc.io/velocity/player-information-forwarding/
• Optional Bedrock support:Floodgate and/or Geyser installed on Velocity
  • https://geysermc.org/download/
  • https://geysermc.org/wiki/floodgate/setup/

Network Setup

• Client
• Velocity with online-mode=true and SideGate Velocity
• Modern forwarding protected by forwarding.secret
• Bukkit backend with online-mode=false and SideGate Bukkit

• Install this jar in the Velocity plugins directory.
• Install SideGate Bukkit and ProtocolLib on every backend.
• Set Velocity online-mode=true.
• Set player-info-forwarding-mode="modern".
• Configure a long random forwarding.secret.
• Configure the same secret in Paper's Velocity proxy settings.
• Set backend server.properties to online-mode=false.
• Set proxy-mode.enabled=true in SideGate Bukkit.
• Firewall backend ports so players cannot bypass the proxy.

Velocity Configuration

• enable-guest-mode: true
• proxy-mode.enabled: true
• auto-detect-premium: true
• allow-all-guests: true
• premium-usernames: Names that must always use Premium authentication
• allowed-guests: Used when allow-all-guests is false
• logging.login-decisions: true
• bedrock.enabled: true
• bedrock.force-floodgate-offline-mode: true
• compatibility.require-minecraft-1-20-or-newer: true
• messages.guest-denied: Message shown to denied Guests
• messages.premium-session-failure: Premium-name conflict message
• messages.unsupported-version: Message shown to Java clients older than 1.20

Important Behavior

• Velocity owns admission and authentication decisions.
• Bukkit owns Guest gameplay actions and player-facing join effects.
• Mojang API failure never automatically grants Guest access.
• A Premium-registered username must still pass Mojang session verification.
• Bedrock connections detected through Floodgate/Geyser are not sent through the Java Premium lookup.
• Encrypted-session FALLBACK_TO_GUEST is not currently available on Velocity.

Tested Environment

• Velocity 3.5.0-SNAPSHOT build 595
• Paper 26.1.2 build 64
• Minecraft 26.1.2 client
• Velocity runtime on Java 21
• Paper backend runtime on Java 25

Links

• Documentation: https://dev.tamkungz.me/documentation/sidegate/
• Issue tracker: https://github.com/TamKungZ/SideGate/issues
• Public reference snapshot: https://github.com/TamKungZ/SideGate

Dependency Disclosure
All required and optional external dependencies are disclosed in the Requirements and External Dependencies section above and should also be listed in the resource Dependencies tab.

License
Closed Source / Proprietary

• Normal server usage is allowed.
• Separate addon plugins using the SideGate public API are allowed.
• Redistribution, resale, modification, and repackaging are not allowed without permission.
• Commercial server monetization requires prior written permission.
• Contact: [email protected]

Security Notice
Guest/offline identities can be impersonated. Production networks should use an authentication plugin, UUID-based permissions, backups, and strict backend firewall rules.

Do not expose backend server ports publicly.