<h1 align="center"> <img src="https://raw.githubusercontent.com/YuWan-030/TrueUUID/main/TrueUUID-banner.svg" width="300" alt="TrueUUID"> </h1> English | (https://github.com/YuWan-030/TrueUUID/blob/main/README_zh-CN.md) TrueUUID adds account verification to modded Minecraft servers that run in offline mode. A premium player's access token stays on their own computer; the server receives only the login proof needed to verify their UUID and skin. The same TrueUUID JAR must be installed on the client and server. Always choose the JAR made for your exact Minecraft version and loader. > > Version 1.2.0 publishes only the 36 exact targets approved in the > (docs/architecture/target-matrix.md). Omitted Minecraft > patches are not implicitly supported. ## Quick start 1. Download or build the JAR for your exact loader and Minecraft version. 2. Put that same JAR in the client's and server's `mods` folders. 3. Set the server to offline mode: ```properties online-mode=false ``` 4. Start the server once to generate the TrueUUID configuration. 5. Join with a matching modded client. The HUD shows green for a verified premium login and red when the server accepts offline fallback. Do not expose a development server created by `run-dev-target.sh` to the internet. It deliberately binds to localhost and uses offline mode for testing. ## What TrueUUID does - Verifies Mojang sessions without sending the player's access token to the server. - Uses the verified UUID, username casing, and signed skin properties during login. - Can allow offline players while blocking offline reuse of names that were previously verified. - Stores known verified names in `trueuuid-registry.json`. - Shows localized login feedback and a small premium/offline status badge. - Supports bounded login timeouts, response limits, HTTPS validation, public address checks, and redirect refusal. - Supports configured Yggdrasil/authlib-injector services on adapters that list that feature in the target matrix. All 36 currently declared adapters include offline-to-verified data migration, admin commands, and the addon API. Every exact target passed the premium, offline fallback, confirmed migration, and known-name denial installed-JAR matrix. Consult the target matrix instead of assuming every implemented feature or an omitted adjacent Minecraft patch was exercised. ## How login verification works 1. The offline-mode server sends the client a one-time login challenge. 2. The client uses its local session to answer the challenge through Mojang's `joinServer` call. Its access token never leaves the client. 3. The server checks the result with Mojang's `hasJoined` endpoint. 4. A successful login receives the verified UUID and signed skin properties. 5. A failed or timed-out check is either rejected or handled by the configured offline-fallback policy. For an allowed Yggdrasil provider, the same flow uses its HTTPS session endpoint. Custom endpoints are disabled until their host is explicitly allowlisted. ## Installation ### Server 1. Install the loader and Minecraft version matching the TrueUUID filename. 2. Copy the JAR into the server's `mods` directory. 3. Set `online-mode=false` in `server.properties`. 4. Keep the server behind a firewall while configuring and testing it. ### Prism Launcher 1. Open the instance matching the JAR's Minecraft version and loader. 2. Select **Edit** → **Mods** → **Add file**. 3. Select the built TrueUUID JAR from the target's `build/libs` directory. 4. Install the same JAR on the server. Do not use a Forge JAR in NeoForge, or a JAR built for another Minecraft patch. For Fabric, use the remapped JAR in `build/libs`, never the development JAR in `build/devlibs`. ## Configuration Forge and NeoForge generate: ```text config/trueuuid-common.toml ``` Fabric generates: ```text config/trueuuid.json ``` Forge and NeoForge use the TOML keys below. Fabric stores the matching login policy settings in the JSON `auth` object; the target matrix lists any adapter-specific gaps. The main policy options are: ```toml auth.timeoutMs = 30000 auth.allowOfflineOnTimeout = false auth.allowOfflineOnFailure = true auth.knownPremiumDenyOffline = true auth.allowOfflineForUnknownOnly = true auth.recentIpGrace.enabled = true auth.recentIpGrace.ttlSeconds = 10 auth.showJoinFeedback = true auth.showJoinTitle = false auth.showAccountOverlay = true ``` The recommended defaults allow an unknown offline name but stop that name from falling back to offline mode after it has completed a verified login. All three loaders can position the account badge. Forge and NeoForge use TOML; Fabric uses the matching keys inside the JSON `auth` object: ```toml auth.overlayCorner = "bottom_right" auth.overlayOffsetX = 0 auth.overlayOffsetY = 0 auth.overlayScale = 1.25 ``` For Yggdrasil/authlib-injector providers, add only hosts you trust: ```toml auth.yggdrasil.apiRootWhitelist = ["littleski