refactor: Some fixes for premium feature

Xephi · Xephi · commit 68d8834ed83f · 2026-05-02T16:08:05.000+02:00
- evict stale pending entries to prevent memory leak
- atomically replace premium list to avoid concurrent update races
- reject invalid usernames before DB lookup in packet listener
- log rate-limit (429) errors distinctly in Mojang profile API
- rename canBypassWithPremiumAtPreJoin to shouldSkipPreJoinDialogForPremium
- use camelCase premiumUUID as default column name
- clarify why UUID v4 skips the Mojang API call
- use 'Mojang account' wording in premium account_not_found
- clarify session server downtime behavior in FAQ
- simplify premium bypass feature description
diff --git a/README.md b/README.md
@@ -58,7 +58,7 @@ You can also create your own translation file and, if you want, you can share it
   <li>Graphical login/register dialogs, with optional Paper/Folia pre-join dialogs</li>
   <li>Restricted users (associate a username with an IP)</li>
   <li>Protect player's inventory until correct authentication (requires PacketEvents)</li>
-  <li><strong>Premium bypass: Mojang-account holders skip password auth via cryptographic session verification (requires PacketEvents)</strong></li>
+  <li><strong>Premium bypass: Mojang-account holders skip password auth (requires PacketEvents)</strong></li>
   <li>Saves the quit location of the player</li>
   <li>Automatic database backup</li>
   <li>Available languages: <a href="https://github.com/AuthMe/AuthMeReloaded/blob/master/docs/translations.md">translations</a></li>
diff --git a/authme-bungee/src/main/java/fr/xephi/authme/bungee/BungeeProxyBridge.java b/authme-bungee/src/main/java/fr/xephi/authme/bungee/BungeeProxyBridge.java
@@ -52,7 +52,7 @@ public final class BungeeProxyBridge implements Listener {
     private final BungeeAuthenticationStore authenticationStore;
     private final Map<String, AtomicInteger> pendingAutoLogins = new ConcurrentHashMap<>();
     private final Set<String> notifiedAuthServers = ConcurrentHashMap.newKeySet();
-    private final Set<String> premiumUsernames = ConcurrentHashMap.newKeySet();
+    private volatile Set<String> premiumUsernames = ConcurrentHashMap.newKeySet();
     // Players whose Mojang UUID was confirmed by the proxy during the login phase (LoginSuccess with UUID v4)
     private final Set<String> proxyVerifiedPremium = ConcurrentHashMap.newKeySet();
     private final ScheduledExecutorService retryScheduler = Executors.newSingleThreadScheduledExecutor(r -> {
@@ -175,19 +175,20 @@ public void onPluginMessage(PluginMessageEvent event) {
             cancelPendingLogin(parsedMessage.playerName());
         } else if (PREMIUM_SET_MESSAGE.equals(parsedMessage.typeId())) {
             premiumUsernames.add(parsedMessage.playerName());
-            logger.fine("Premium enabled for '" + parsedMessage.playerName() + "' (proxy cache updated)");
+            logger.fine(() -> "Premium enabled for '" + parsedMessage.playerName() + "' (proxy cache updated)");
         } else if (PREMIUM_UNSET_MESSAGE.equals(parsedMessage.typeId())) {
             premiumUsernames.remove(parsedMessage.playerName());
-            logger.fine("Premium disabled for '" + parsedMessage.playerName() + "' (proxy cache updated)");
+            logger.fine(() -> "Premium disabled for '" + parsedMessage.playerName() + "' (proxy cache updated)");
         } else if (PREMIUM_LIST_MESSAGE.equals(parsedMessage.typeId())) {
-            premiumUsernames.clear();
+            Set<String> newPremiumSet = ConcurrentHashMap.newKeySet();
             if (!parsedMessage.playerName().isEmpty()) {
                 for (String name : parsedMessage.playerName().split(",")) {
                     if (!name.isEmpty()) {
-                        premiumUsernames.add(name.trim());
+                        newPremiumSet.add(name.trim());
                     }
                 }
             }
+            premiumUsernames = newPremiumSet;
             logger.info("Premium list received from backend: " + premiumUsernames.size() + " premium player(s)");
         }
     }
diff --git a/authme-core/src/main/java/fr/xephi/authme/listener/packetevents/PremiumVerificationPacketListener.java b/authme-core/src/main/java/fr/xephi/authme/listener/packetevents/PremiumVerificationPacketListener.java
@@ -24,6 +24,7 @@
 import java.util.Optional;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
+import java.util.regex.Pattern;
 
 /**
  * Intercepts {@code LOGIN_START} and {@code ENCRYPTION_RESPONSE} packets to perform
@@ -42,6 +43,8 @@
  */
 public class PremiumVerificationPacketListener extends PacketListenerAbstract {
 
+    private static final Pattern VALID_USERNAME = Pattern.compile("^[a-zA-Z0-9_]{2,16}$");
+
     private final ConsoleLogger logger = ConsoleLoggerFactory.get(PremiumVerificationPacketListener.class);
 
     private final DataSource dataSource;
@@ -64,7 +67,7 @@ public void onPacketReceive(PacketReceiveEvent event) {
     private void handleLoginStart(PacketReceiveEvent event) {
         WrapperLoginClientLoginStart wrapper = new WrapperLoginClientLoginStart(event);
         String username = wrapper.getUsername();
-        if (username == null || username.isEmpty()) {
+        if (username == null || !VALID_USERNAME.matcher(username).matches()) {
             return;
         }
 
diff --git a/authme-core/src/main/java/fr/xephi/authme/service/MojangApiService.java b/authme-core/src/main/java/fr/xephi/authme/service/MojangApiService.java
@@ -46,6 +46,10 @@ public Optional<UUID> fetchUuidByName(String username) {
             if (code == HttpURLConnection.HTTP_NO_CONTENT || code == HttpURLConnection.HTTP_NOT_FOUND) {
                 return Optional.empty();
             }
+            if (code == 429) {
+                logger.warning("Mojang profile API rate-limited (429) for '" + username + "'; try again later");
+                return Optional.empty();
+            }
             if (code != HttpURLConnection.HTTP_OK) {
                 logger.warning("Mojang profile API returned " + code + " for '" + username + "'");
                 return Optional.empty();
diff --git a/authme-core/src/main/java/fr/xephi/authme/service/PremiumLoginVerifier.java b/authme-core/src/main/java/fr/xephi/authme/service/PremiumLoginVerifier.java
@@ -34,6 +34,7 @@
 public class PremiumLoginVerifier {
 
     private static final long VERIFIED_TTL_MS = 60_000L;
+    private static final long PENDING_TTL_MS = 30_000L;
 
     private final ConsoleLogger logger = ConsoleLoggerFactory.get(PremiumLoginVerifier.class);
 
@@ -71,12 +72,18 @@ public PublicKey getPublicKey() {
      * @return a freshly generated 4-byte verify token to embed in the EncryptionRequest
      */
     public byte[] startVerification(String connectionKey, String username, UUID playerUUID) {
+        evictStalePendingEntries();
         byte[] verifyToken = new byte[4];
         secureRandom.nextBytes(verifyToken);
         pending.put(connectionKey, new PendingVerification(username, playerUUID, verifyToken, System.currentTimeMillis()));
         return verifyToken;
     }
 
+    private void evictStalePendingEntries() {
+        long now = System.currentTimeMillis();
+        pending.entrySet().removeIf(e -> now - e.getValue().startedAt() > PENDING_TTL_MS);
+    }
+
     /** Returns true if an in-flight verification exists for this connection. */
     public boolean hasPending(String connectionKey) {
         return pending.containsKey(connectionKey);
diff --git a/authme-core/src/main/java/fr/xephi/authme/service/PremiumService.java b/authme-core/src/main/java/fr/xephi/authme/service/PremiumService.java
@@ -74,7 +74,9 @@ public void enablePremium(Player player) {
 
         UUID playerUuid = player.getUniqueId();
         if (playerUuid.version() == 4) {
-            // UUID v4 = Mojang online UUID (online-mode server or proxy forwarding): use directly.
+            // UUID v4 = Mojang-issued UUID: either the server is in online mode (Mojang already
+            // verified the session at the connection level) or the proxy forwarded a real Mojang
+            // UUID. No extra API call needed — the server's own auth is the source of truth.
             storePremiumUuid(auth, playerUuid, player, player.getName());
         } else {
             // UUID v3 = Bukkit offline UUID: fetch the real UUID from Mojang API.
diff --git a/authme-core/src/main/java/fr/xephi/authme/settings/properties/DatabaseSettings.java b/authme-core/src/main/java/fr/xephi/authme/settings/properties/DatabaseSettings.java
@@ -141,7 +141,7 @@ public final class DatabaseSettings implements SettingsHolder {
     @Comment({"Column for storing the Mojang UUID of premium players",
         "(null if premium mode is off for this player)"})
     public static final Property<String> MYSQL_COL_PREMIUM_UUID =
-        newProperty("DataSource.mySQLColumnPremiumUUID", "premium_uuid");
+        newProperty("DataSource.mySQLColumnPremiumUUID", "premiumUUID");
 
     @Comment("Column for storing players groups")
     public static final Property<String> MYSQL_COL_GROUP =
diff --git a/authme-core/src/main/resources/messages/messages_en.yml b/authme-core/src/main/resources/messages/messages_en.yml
@@ -216,7 +216,7 @@ admin:
 # Premium mode
 premium:
   feature_disabled: '&cPremium mode is not enabled on this server.'
-  account_not_found: '&cNo premium Minecraft account found for your username.'
+  account_not_found: '&cNo Mojang account found for your username.'
   already_enabled: '&ePremium mode is already enabled for your account.'
   enable_success: '&2Premium mode enabled! You will no longer need to authenticate on login.'
   not_enabled: '&ePremium mode is not enabled for your account.'
diff --git a/authme-core/src/main/resources/messages/messages_ro.yml b/authme-core/src/main/resources/messages/messages_ro.yml
@@ -212,6 +212,7 @@ admin:
     first_set_success: '&2Noul prim punct de spawn definit corect.'
     first_set_fail: '&cSetFirstSpawn a eșuat, te rugăm să reîncerci.'
     not_defined: '&cSpawn-ul a eșuat, te rugăm să încearcă să definești spawn-ul.'
+    first_not_defined: '&cPrimul spawn a eșuat, te rugăm să încearcă să definești primul spawn.'
 
 # Modul premium
 premium:
@@ -231,4 +232,3 @@ premium:
     disable_success: '&2Modul premium dezactivat pentru %name.'
     impostor_kicked: '&eUn jucător conectat ca %name a avut un UUID diferit și a fost dat afară.'
     kick_reason: '&cSetările premium ale contului tău au fost modificate de un administrator. Te rugăm să te reconectezi.'
-    first_not_defined: '&cPrimul spawn a eșuat, te rugăm să încearcă să definești primul spawn.'
diff --git a/authme-core/src/test/resources/fr/xephi/authme/datasource/sql-initialize.sql b/authme-core/src/test/resources/fr/xephi/authme/datasource/sql-initialize.sql
@@ -20,7 +20,7 @@ CREATE TABLE authme (
     realname VARCHAR(255) NOT NULL DEFAULT 'Player',
     salt varchar(255),
     hasSession INT NOT NULL DEFAULT '0',
-    premium_uuid VARCHAR(36)
+    premiumUUID VARCHAR(36)
 );
 
 INSERT INTO authme (username, password, ip, lastlogin, x, y, z, world, yaw, pitch, email, isLogged, realname, salt, regdate, regip, totp)
diff --git a/authme-paper-common/src/main/java/fr/xephi/authme/listener/PaperDialogFlowListener.java b/authme-paper-common/src/main/java/fr/xephi/authme/listener/PaperDialogFlowListener.java
@@ -116,7 +116,7 @@ public void onPlayerConfigure(AsyncPlayerConnectionConfigureEvent event) {
 
         PlayerAuth auth = dataSource.getAuth(normalizedName);
         if (auth != null) {
-            if (canBypassWithPremiumAtPreJoin(auth, playerName, playerId)) {
+            if (shouldSkipPreJoinDialogForPremium(auth, playerName, playerId)) {
                 preJoinDialogService.markSkipPostJoinDialog(playerId);
                 return;
             }
@@ -303,7 +303,7 @@ private void completeRegisterResponse(UUID playerId, String kickMessage) {
         }
     }
 
-    private boolean canBypassWithPremiumAtPreJoin(PlayerAuth auth, String playerName, UUID playerId) {
+    private boolean shouldSkipPreJoinDialogForPremium(PlayerAuth auth, String playerName, UUID playerId) {
         if (!commonService.getProperty(PremiumSettings.ENABLE_PREMIUM) || !auth.isPremium()) {
             return false;
         }
diff --git a/authme-paper-common/src/test/java/fr/xephi/authme/listener/PaperDialogFlowListenerTest.java b/authme-paper-common/src/test/java/fr/xephi/authme/listener/PaperDialogFlowListenerTest.java
@@ -379,7 +379,7 @@ public void shouldNotSkipPreJoinDialogsForUnverifiedPremiumPlayer() throws Excep
         given(premiumLoginVerifier.getVerifiedUuid("Bobby")).willReturn(null);  // not yet verified
 
         // UUID v4 that doesn't match stored premium UUID → must return false (impostor or wrong account)
-        assertThat(invokeCanBypassWithPremiumAtPreJoin(listener, auth, "Bobby", playerId), is(false));
+        assertThat(invokeShouldSkipPreJoinDialogForPremium(listener, auth, "Bobby", playerId), is(false));
         verify(preJoinDialogService, never()).markSkipPostJoinDialog(playerId);
     }
 
@@ -406,7 +406,7 @@ public void shouldSkipPreJoinDialogForPremiumPlayerWithOfflineUuidInProxyMode()
         given(commonService.getProperty(PremiumSettings.ENABLE_PREMIUM)).willReturn(true);
         given(premiumLoginVerifier.getVerifiedUuid("Bobby")).willReturn(null); // PacketEvents not active
 
-        assertThat(invokeCanBypassWithPremiumAtPreJoin(listener, auth, "Bobby", offlineUuid), is(true));
+        assertThat(invokeShouldSkipPreJoinDialogForPremium(listener, auth, "Bobby", offlineUuid), is(true));
     }
 
     @Test
@@ -427,7 +427,7 @@ public void shouldSkipPreJoinDialogForPremiumPlayerWithMatchingMojangUuidInProxy
         given(commonService.getProperty(PremiumSettings.ENABLE_PREMIUM)).willReturn(true);
 
         // Profile already has the Mojang UUID (v4) — verify returns true
-        assertThat(invokeCanBypassWithPremiumAtPreJoin(listener, auth, "Bobby", premiumUuid), is(true));
+        assertThat(invokeShouldSkipPreJoinDialogForPremium(listener, auth, "Bobby", premiumUuid), is(true));
     }
 
     @Test
@@ -447,13 +447,13 @@ public void shouldNotSkipPreJoinDialogForImpostorWithMismatchedMojangUuidInProxy
 
         given(commonService.getProperty(PremiumSettings.ENABLE_PREMIUM)).willReturn(true);
 
-        assertThat(invokeCanBypassWithPremiumAtPreJoin(listener, auth, "Bobby", impostorUuid), is(false));
+        assertThat(invokeShouldSkipPreJoinDialogForPremium(listener, auth, "Bobby", impostorUuid), is(false));
     }
 
-    private static boolean invokeCanBypassWithPremiumAtPreJoin(PaperDialogFlowListener listener,
+    private static boolean invokeShouldSkipPreJoinDialogForPremium(PaperDialogFlowListener listener,
             PlayerAuth auth, String playerName, UUID playerId) throws ReflectiveOperationException {
         var method = PaperDialogFlowListener.class
-            .getDeclaredMethod("canBypassWithPremiumAtPreJoin", PlayerAuth.class, String.class, UUID.class);
+            .getDeclaredMethod("shouldSkipPreJoinDialogForPremium", PlayerAuth.class, String.class, UUID.class);
         method.setAccessible(true);
         return (boolean) method.invoke(listener, auth, playerName, playerId);
     }
diff --git a/authme-velocity/src/main/java/fr/xephi/authme/velocity/VelocityProxyBridge.java b/authme-velocity/src/main/java/fr/xephi/authme/velocity/VelocityProxyBridge.java
@@ -55,7 +55,7 @@ final class VelocityProxyBridge {
     private final VelocityAuthenticationStore authenticationStore;
     private final Map<String, AtomicInteger> pendingAutoLogins = new ConcurrentHashMap<>();
     private final Set<String> notifiedAuthServers = ConcurrentHashMap.newKeySet();
-    private final Set<String> premiumUsernames = ConcurrentHashMap.newKeySet();
+    private volatile Set<String> premiumUsernames = ConcurrentHashMap.newKeySet();
     // Players whose Mojang UUID was confirmed by the proxy during the login phase (LoginSuccess with UUID v4)
     private final Set<String> proxyVerifiedPremium = ConcurrentHashMap.newKeySet();
     private final ScheduledExecutorService retryScheduler = Executors.newSingleThreadScheduledExecutor(r -> {
@@ -93,6 +93,10 @@ void onLogin(LoginEvent event) {
     /**
      * Fallback hook on {@link PostLoginEvent}: if the player has a UUID v4 (Mojang-issued), they
      * are recorded as proxy-verified premium even if the {@link LoginEvent} listener missed them.
+     *
+     * <p>This is a secondary signal only — the primary gate is the backend's UUID comparison
+     * ({@code verifiedUuid.equals(auth.getPremiumUuid())}), so a fake v4 UUID injected by a
+     * third-party plugin would still be rejected there unless it matches the stored premium UUID.</p>
      */
     void onPostLogin(PostLoginEvent event) {
         Player player = event.getPlayer();
@@ -217,14 +221,15 @@ void onPluginMessage(PluginMessageEvent event) {
             premiumUsernames.remove(parsedMessage.playerName());
             logger.debug("Premium disabled for '{}' (proxy cache updated)", parsedMessage.playerName());
         } else if (PREMIUM_LIST_MESSAGE.equals(parsedMessage.typeId())) {
-            premiumUsernames.clear();
+            Set<String> newPremiumSet = ConcurrentHashMap.newKeySet();
             if (!parsedMessage.playerName().isEmpty()) {
                 for (String name : parsedMessage.playerName().split(",")) {
                     if (!name.isEmpty()) {
-                        premiumUsernames.add(name.trim());
+                        newPremiumSet.add(name.trim());
                     }
                 }
             }
+            premiumUsernames = newPremiumSet;
             logger.info("Premium list received from backend: {} premium player(s)", premiumUsernames.size());
         }
     }
diff --git a/docs/premium.md b/docs/premium.md
@@ -174,9 +174,11 @@ A: Online-mode servers already enforce Mojang authentication at the server level
 need AuthMe's premium bypass at all. AuthMe is primarily designed for offline-mode servers.
 
 **Q: What happens if Mojang's session server is down?**  
-A: `hasJoined` returns an error → the verified UUID is not stored → `canBypassWithPremium()`
-returns `false` → the player falls through to normal password authentication. The feature
-fails closed: connectivity problems never grant unverified access.
+A: The Minecraft client must contact `sessionserver.mojang.com/session/minecraft/join` before
+sending `ENCRYPTION_RESPONSE` — if that call fails, the client drops the connection entirely and
+the player cannot join at all. On the server side, if `hasJoined` were to return an error anyway,
+the verified UUID is not stored and `canBypassWithPremium()` returns `false`, so the feature
+always fails closed: connectivity problems never grant unverified access.
 
 **Q: What happens if a premium player changes their Minecraft username?**  
 A: The premium bypass is keyed on the **Mojang UUID** (not the name), so a name change does
