trueuuid

A mod that securely verifies premium accounts on an offline-mode server during the login phase, without sending the player's access token to the server.

TrueUUID lets an offline-mode server:

Ask the client to perform Mojang "joinServer" locally. Verify with Mojang Session Server from the server using a nonce. If verification passes: replace the player's UUID with the official premium UUID, fix username casing, and inject skin properties. If verification fails or times out: configurable behavior (kick on timeout by default; failover to offline mode for verification failures by default). Inform the player on join with a Title whether they are in "Online/Premium Mode" or "Offline Mode" and send an explanatory chat message for offline fallback. Note: Client and server must both install this mod. The server must run in offline mode.

Why Privacy-preserving: the player's access token never leaves the client. The client calls joinServer(profile, token, nonce) locally. Better identity integrity: even in offline mode, verified players keep their official UUID and skins. Clear UX: show Title messages for premium vs offline mode, plus a chat hint when falling back to offline. How it works Server is in offline mode. During login (HELLO), the server sends a custom login query with a nonce (transactionId + identifier trueuuid:auth + data). The modded client intercepts this query, reads the nonce, and locally calls MinecraftSessionService.joinServer(profile, token, nonce) (token never sent to the server). The client replies with a boolean ack (no sensitive data). The server calls Mojang Session Server /hasJoined?username=&serverId=[&ip=]. If success: Replace the pending login GameProfile with premium UUID and the name returned from Mojang (ensuring correct casing). Inject skin properties (textures) with signature into the GameProfile property map. After join, force-refresh player info so skins update. Show a green Title "Premium Mode". If failure: Behavior is configurable. By default: Timeout: kick with configurable message. Any verification failure (ack=false / hasJoined failed / server error): fall back to vanilla offline flow (no UUID replacement), then: Show a red Title "Offline Mode" with a short subtitle. Send a chat message explaining that the session failed and it might be due to network issues. Requirements Minecraft: 1.20.X Forge: 47.x (e.g., 47.4.8) Java: 17 Client and server must both install this mod. Server property: online-mode=false Installation Server: Set online-mode=false in server.properties. Place the built JAR in mods/. Client: Place the same JAR in mods/. Tip: If the client does not have this mod, the server will not receive a valid response to the custom login query. Depending on configuration, the server may kick or fall back to offline mode.

Configuration After the first run, a config file is generated:

config/trueuuid-common.toml Keys and defaults (reflecting the recommended behavior):

auth.timeoutMs = 10000 Login-phase wait time (milliseconds) for the client's reply. auth.allowOfflineOnTimeout = false false: kick on timeout (default) true: allow offline fallback if timeout occurs auth.allowOfflineOnFailure = true true: allow offline fallback on any verification failure (default) false: disconnect on failure auth.timeoutKickMessage = "登录超时，未完成正版校验" Kick reason shown on timeout. auth.offlineFallbackMessage = "注意：你当前以离线模式进入服务器；如果你是正版账号，可能是网络原因导致无法成功鉴权。" Chat message shown to the player if they were allowed in via offline fallback. auth.offlineShortSubtitle = "鉴权失败：离线模式" Short subtitle for the Title when in offline mode. auth.onlineShortSubtitle = "已通过正版校验" Short subtitle for the Title when in premium mode. Notes:

The "Title" uses short subtitles to avoid overflowing the screen. The long explanatory message is sent via chat when offline fallback happens. Compatibility and notes Proxies (Bungee/Velocity): The server optionally includes the client IP in the Mojang /hasJoined call when available. If you're behind a proxy that hides the real IP, verification still works because ip is optional for Mojang's endpoint. Skins: Skin properties are injected during login. The server broadcasts a player info refresh after join to force client-side skin updates. If the client is unmodded: it will not respond with the expected payload. Depending on config, the server will either kick or allow offline fallback. Privacy The player's access token is never sent to your server. The token is used locally on the client to call joinServer. The server only receives a boolean ack and then itself contacts Mojang's session server to verify the nonce. License GNU LGPL 3.0 (see gradle.properties / project license) Credits Mojang authlib and session API. Sponge Mixin. ForgeGradle.