PremiumBridge Velocity

PremiumBridge Velocity is a secure proxy companion for Velocity networks.

It keeps your Minecraft backend in offline mode so offline players can still join, while verified online sessions are checked at the proxy and passed to PremiumBridge on the backend through signed assertions and modern player information forwarding.

PremiumBridge required

🎯 What makes it different

Feature	Benefit
🔐 Proxy-side verification	Online sessions are checked before the backend authentication flow.
🛡️ Signed verification result	The backend accepts online auto-login only after validating a short-lived signed assertion.
🔗 Modern forwarding	Online UUID, skin properties, and profile data are forwarded natively to Paper.
🚫 No raw encryption handshake	Velocity mode does not use a custom backend `EncryptionRequest` packet.
🌐 Offline backend support	The backend can remain in offline mode for offline players.
✅ Safe identity handling	UUIDs and IP addresses are never treated as proof of account ownership.

⚖️ Offline backend, online proxy experience

The server backend remains in offline mode, but Velocity handles the online verification step before the player reaches the backend.

Online players can receive:

Seamless online-session verification
Native UUID and skin profile forwarding
Automatic PremiumBridge authentication on the backend
Compatibility with configured AuthMe or OpeNLogin integration
A clean login experience without a custom backend encryption handshake

Offline players continue to use the normal backend authentication flow and are not treated as online automatically.

💫 Velocity Support

PremiumBridge Velocity is an optional companion module. PremiumBridge does not require Velocity, but this module is required when PremiumBridge is used behind a Velocity proxy.

To enable Velocity support:

Put PremiumBridge-Velocity.jar into Velocity/plugins/.
Put PremiumBridge.jar into the plugins/ folder of every Paper or Purpur backend.
Enable player-info-forwarding-mode = "modern" in velocity.toml.
Enable native Velocity forwarding in config/paper-global.yml and use the same forwarding secret.
Set premium-verification.mode to velocity-modern in the backend configuration.
Copy the companion shared secret to every backend and restart the proxy and backends.

Keep backend ports protected so players cannot bypass the proxy.

🔄 Compatibility

The module is designed for PremiumBridge backend releases supporting:

Minecraft Java 1.21.9-1.21.11
Minecraft Java 26.1.x
Minecraft Java 26.2

Supported backend platforms: Paper and compatible forks such as Purpur.

📋 Requirements

Velocity with modern player information forwarding
PremiumBridge on every backend
AuthMe, OpeNLogin, or another supported backend authentication plugin
ProtocolLib on the backend when required by the selected PremiumBridge features

This project is the Velocity companion module. It is not a standalone backend authentication plugin.

✨ Extra features provided by the backend plugin

When installed together with PremiumBridge on the backend, the network can also use:

🔑 Optional online auto-registration
🔄 Offline-to-online data migration
🛡️ Online nickname protection
🔇 Auth-plugin message filtering for verified online players
👤 AddHeads integration through the addhead.premium permission
📚 Public API for other plugins