Support Floodgate Global Linking

[tnqzh123]

This Pull Request resolves #291.

Code generated by OpenAI Codex with GPT-5.5 xhigh.

To enable Floodgate Global Linking support, the auth server must add feature.floodgate_global_linking feature flag to their metadata and implement APIs described below.

APIs to implement

Endpoints

GET /geyser/v2/link/bedrock/{xuid}
GET /geyser/v2/link/java/{uuid}

xuid is a 64-bit integer, and uuid can be a UUID with or without dashes.

Success Responses

The two APIs have the same JSON response:

{
  "bedrock_id": 12345678901234567890, # XUID
  "java_id": "f702c5d3-9d5c-457f-80c6-91c664757092", # Java Edition UUID with dashes
  "java_name": "SSSSSteven", # Java Edition profile name
  "last_name_update": 1780453291994 # Unix timestamp of last profile name change
}

Error Responses

If no link exists for the specified UUID or XUID, these two APIs should respond HTTP 200 OK with an empty JSON object:

{}

If the provided xuid or uuid is malformed, these two APIs should respond HTTP 400 Bad Request with the following JSON body:

{
  "message": "human readable error message"
}

References

Geyser REST APIs doc:

• Get linked Java account from Bedrock xuid
• Get linked Bedrock account from Java UUID
• Full OpenAPI doc (JSON)

[tnqzh123]

I also made a yggdrasil-mock fork for demostration: tnqzh123/yggdrasil-mock

You can set your own XUID in application.yml: https://github.com/tnqzh123/yggdrasil-mock/blob/ac792c2bca493eb4e13fcbd85e4fb9bd3e31c9bc/server/src/main/resources/default-application.yaml#L11-L13

[tnqzh123]

To get the XUID of a Microsoft account, you can:

• Use online tools like cxkes.me or third-party APIs like OpenXBL.
• Decode its Minecraft Access token, take the xid claims inside (not recommended as Access Token format is subjected to change).
• Request a new XSTS Token with RelyingParty http://xboxlive.com, take DisplayClaims.xui[0].xid from response. See this Stack Overflow thread for more details.

[evan-goode]

Interesting! This would support the following use case, correct?:

1. Player runs JE and logs into server using authlib-injector account
2. Player links their authlib-injector account to their Microsoft BE account (somehow)
3. Player runs BE and logs into the same server using their Microsoft account, and has all the same items, permissions, player UUID, etc. as when they played on JE with their authlib-injector account?

Adding this to authlib-injector would substantially expand its scope... So far, authlib-injector only overrides requests to Mojang URLs, and the authlib-injector API spec is mostly routes that are provided by Mojang, or were at some point.

Floodgate is only needed on the MC server, not the client, right? A more conservative approach would be to have server admins configure Floodgate to point to a different endpoint (GeyserMC/Floodgate#675), which could happen to also be the authlib-injector server. It would be more like "Blessing Skin/Drasl implement both the GeyserMC Floodgate API AND the authlib-injector API" rather than "the authlib-injector API includes the Floodgate API".

[tnqzh123]

Floodgate is only needed on the MC server, not the client, right? A more conservative approach would be to have server admins configure Floodgate to point to a different endpoint, which could happen to also be the authlib-injector server. It would be more like "Blessing Skin/Drasl implement both the GeyserMC Floodgate API AND the authlib-injector API" rather than "the authlib-injector API includes the Floodgate API".

It will be great if Geyser is willing to do so!