TrueUUID

English | 简体中文

A Forge 1.20.X 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

1. Server is in offline mode. During login (HELLO), the server sends a custom login query with a nonce (transactionId + identifier trueuuid:auth + data).
2. The modded client intercepts this query, reads the nonce, and locally calls MinecraftSessionService.joinServer(profile, token, nonce) (token never sent to the server).
3. The client replies with a boolean ack (no sensitive data).
4. The server calls Mojang Session Server /hasJoined?username={name}&serverId={nonce}[&ip={ip}].
5. 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".
6. 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.

---

Maintained by: @YuWan-030