RustNotMC/docs/microsoft-account.md

# Microsoft account sign-in and online-mode play

Horizon signs players in with their Microsoft account in the launcher and joins online-mode
(authenticated) servers like vanilla 26.3 does. The launcher plays only with an account that owns
Minecraft: Java Edition ([the owner gate](#the-owner-gate)); offline names, LAN and offline-mode
servers play behind it. This note is the design, the status of each part and what Ludovic has to
register.

## What Ludovic registers (needs his accounts)

Nothing below can be done by an agent: the app registrations belong to Ludovic. A build without
the client ID can't sign in, so its launcher can't start the game ("This build of the launcher has
no Microsoft sign-in"); release builds have it.

1. **Azure app registration** (https://portal.azure.com → Microsoft Entra ID → App registrations →
   New registration):
   - Name: `Horizon` (shown to players on the Microsoft consent page).
   - Supported account types: **Personal Microsoft accounts only** (Minecraft accounts are
     consumer accounts; the launcher uses the `consumers` tenant).
   - Redirect URI: none needed for the device-code flow. If the form insists, add a
     "Mobile and desktop applications" redirect `https://login.microsoftonline.com/common/oauth2/nativeclient`.
   - After creating it: Authentication → Advanced settings → **Allow public client flows: Yes**
     (this enables the device-code flow; there is no client secret, Horizon is a public client).
   - API permissions: none to add. The launcher requests the scopes `XboxLive.signin offline_access`
     at sign-in time; `offline_access` gives the refresh token.
   - Copy the **Application (client) ID** (a GUID).
2. **Minecraft API access** (Mojang): new Azure apps are refused by
   `api.minecraftservices.com/authentication/login_with_xbox` (HTTP 403, "Invalid app registration")
   until Mojang approves them. Apply with the form linked from https://aka.ms/mce-reviewappid
   (Minecraft Java "App ID review"), giving the client ID above, the app name, the project URL
   (https://github.com/horizon-rust/horizon) and a short description ("open-source Minecraft Java
   Edition client written in Rust; signs players in to join online-mode servers"). Approval takes
   days to weeks; sign-in fails at the Minecraft step with "This app is not approved by Mojang yet"
   until then.
3. **Where the ID goes**:
   - Release builds: the GitHub repository variable (not a secret: client IDs are public)
     `HORIZON_MSA_CLIENT_ID`; the launcher's build reads it with `option_env!` at compile time.
   - Any build, at run time: the environment variable `HORIZON_MSA_CLIENT_ID` overrides the built-in
     value (empty or unset = not configured).

Never use another application's client ID (the official launcher's or another launcher's).

## Flow (launcher)

All requests use HTTPS and JSON except the two OAuth calls (form-encoded):

1. **Device code**: `POST https://login.microsoftonline.com/consumers/oauth2/v2.0/devicecode`
   (`client_id`, `scope=XboxLive.signin offline_access`). The launcher shows the `user_code` and
   `verification_uri` (https://www.microsoft.com/link) with a copy button and opens the browser.
2. **Poll** `POST …/consumers/oauth2/v2.0/token` (`grant_type=urn:ietf:params:oauth:grant-type:device_code`)
   every `interval` seconds; `authorization_pending` waits, `slow_down` adds 5 s, `authorization_declined`,
   `expired_token` and `bad_verification_code` end the sign-in with a message. Result: the Microsoft
   access token and refresh token.
3. **Xbox Live**: `POST https://user.auth.xboxlive.com/user/authenticate` with
   `AuthMethod=RPS, SiteName=user.auth.xboxlive.com, RpsTicket=d=<MS access token>`,
   `RelyingParty=http://auth.xboxlive.com`. Result: the XBL token and the user hash (`uhs`).
4. **XSTS**: `POST https://xsts.auth.xboxlive.com/xsts/authorize` with the XBL token,
   `SandboxId=RETAIL`, `RelyingParty=rp://api.minecraftservices.com/`. The `XErr` codes become
   messages: 2148916233 no Xbox profile yet, 2148916235 Xbox Live not available in the country,
   2148916236/2148916237 adult verification (South Korea), 2148916238 child account (needs a family).
5. **Minecraft**: `POST https://api.minecraftservices.com/authentication/login_with_xbox`
   (`identityToken = "XBL3.0 x=<uhs>;<XSTS token>"`). Result: the Minecraft access token (24 h).
6. **Entitlements**: `GET https://api.minecraftservices.com/entitlements/mcstore`: the account must
   own `game_minecraft` or `product_minecraft` (Game Pass included), else "This account doesn't own
   Minecraft Java Edition".
7. **Profile**: `GET https://api.minecraftservices.com/minecraft/profile`: UUID, name, skins, capes.
   404 = owns the game but has no profile yet ("Create your Minecraft profile on minecraft.net first").

## The owner gate

Decided 2026-10-27 (Ludovic, after a modder's suggestion): like other launchers, Horizon's
launcher starts the game only while an account in it owns Java Edition. Offline play stays
possible; the launcher just doesn't offer it on its own.

- **Play needs an owner.** Every Play (Home, instances and packs, `horizon-launcher play`,
  `modpack play`, the MCP's `play`) asks `account::launch` first. It asks the Minecraft services
  again for each account, the selected one first, until one owns the game: the token renewal
  (below) if due, then entitlements and profile. Without an owner the game doesn't start and Play
  says "Sign in with a Microsoft account that owns Minecraft: Java Edition to play", with Sign in.
- **The window says it once.** A player without an owner (one who played offline until now) sees
  the gate's screen once when the launcher opens: why Horizon needs the account ("like other
  launchers"), that worlds, offline names and settings stay where they are, and Sign in, which shows
  the device code on the same screen. It comes back whenever Play is refused; Not now closes it,
  and Home keeps a Sign in row (`launcher/src/owner_page.rs`).
- **The answer lives with the tokens.** Each account's keychain item keeps the last answer
  (`owns`), so no plain file can say yes. With no network (or a sign-in that can't be renewed) the
  last answer stands: being offline never blocks a player who passed before, and the game starts
  without a session, offline. An answer of "doesn't own" (or no profile) blocks at once.
- **Offline names play behind an owner.** They can be added and played only while an owning
  account is signed in. Signing the last one out keeps them, and they play again once one is back.
- **Who isn't affected:** the game binary itself (`horizon-client`, `horizon-ctl launch`, the
  harnesses, CI), the dedicated server and `horizon-server`, the website. There is no bypass flag:
  the launcher's tests use accounts in a memory store (`MemoryStore`, and `HORIZON_NO_KEYCHAIN`
  for the CLI and MCP tests, which then have no owner).

## Downloading the game for an owner

Decided 2026-10-27. This is the only exception to "Horizon never downloads the game", and it
applies only on the player's machine, for an account the owner gate just asked about. The
launcher's "Download and prepare" (`horizon-launcher prepare --download`) fetches the pinned
version straight from Mojang (`launcher/src/mojang.rs`): the version file, the client jar,
libraries, the asset index and the assets, each checked against the size and sha1 Mojang lists.
They go to `minecraft/` in the launcher's data folder, and the preparation runs as usual. The
download can be cancelled and goes on where it stopped. CI, agents, harnesses and the repo never
download or keep Mojang's files.

Refresh: the Minecraft token is renewed from the Microsoft refresh token (steps 2-5 with
`grant_type=refresh_token`) when it has less than an hour left, before every launch; steps 6-7 run
at every launch (the owner gate). A refused
refresh token (`invalid_grant`) asks the player to sign in again. Several accounts can be signed in;
one is selected. "Sign out" deletes the account's secrets from the keychain.

## Token storage

- Secrets (the Microsoft refresh token, the Minecraft access token and its expiry, the last
  ownership answer) go to the OS
  keychain, one item per account: Keychain on macOS, Credential Manager on Windows, the Secret
  Service (GNOME Keyring, KWallet) on Linux. Service name `dev.playhorizon.launcher`, account = the
  Minecraft UUID. Credential Manager takes at most 2560 bytes per item, which the secrets of a sign-in
  exceed: on macOS and Windows a longer secret is split over the items `<uuid>`, `<uuid>.1`, `<uuid>.2`...
- `accounts.json` in the launcher's data folder keeps only public data: UUID, name, skin URL, which
  account is selected. Never a token.
- No keychain available (a Linux box without a Secret Service, a locked keychain): sign-in still
  works for the session but nothing is saved, and the launcher says "No keychain available: you will
  have to sign in again next time" (it never falls back to a plain file).
- Tokens never appear in logs, errors, `horizon-launcher` CLI output, MCP results or crash reports.
  Requests are logged by endpoint name only.

## Handing the session to the game

Vanilla's launcher passes `--accessToken <token>` on the command line, where every user of the
machine can read it in the process list. Horizon keeps it out of argv:

- The launcher writes `session-<random>.json` (mode 0600 on Unix, created new, in the game home's
  `sessions/` folder) with `{"name", "uuid", "access_token", "user_type": "msa", "xuid"}` and starts
  the game with `--session-file PATH`.
- The game reads the file at start and deletes it at once; the token lives only in the game's memory.
  A file older than two minutes is refused (and deleted), so a stale file can't be replayed.
- Without a session file the game is offline as today (`--name`, offline UUID).
- `HORIZON_SESSION_FILE` is the same as `--session-file` (development and harnesses).

## Online-mode login (game)

Vanilla's `ClientHandshakePacketListenerImpl.handleHello`, `Crypt` and authlib's
`MinecraftServicesSessionService.joinServer`:

1. `ClientboundHelloPacket` (server id, X.509 RSA public key, challenge, should_authenticate).
2. Generate a random 16-byte AES key (the shared secret).
3. Server hash: SHA-1 over `serverId` (ISO-8859-1), the shared secret, the encoded public key;
   `new BigInteger(digest).toString(16)` (signed two's complement hex, e.g. "Notch" →
   `4ed1f46bbe04bc756bcb17c0c7ce3e4632f06a48`, "jeb_" → `-7c9d5b0044c130109a5d7b5fb5c317c02b4e28c1`).
4. If `should_authenticate`: `POST` the session service's `join` endpoint
   `{"accessToken", "selectedProfile" (undashed UUID), "serverId": hash}`, the URL taken from the
   services discovery document (`https://discovery.minecraftservices.com/minecraft/client`, fetched
   once per game). Errors map like authlib's `MinecraftClientHttpException`:
   `ForbiddenOperationException` or 401 → "Failed to log in: Invalid session (Try restarting your
   game and the launcher)", `InsufficientPrivilegesException` → "Multiplayer is disabled…",
   `multiplayer.access.banned` / `FORCED_USERNAME_CHANGE` → "You are banned from playing online",
   5xx or no network → "The authentication servers are currently not reachable…". Without a session
   the game says "This server is in online mode. Sign in with your Microsoft account in the Horizon
   launcher to join it." (Vanilla goes on after a failed join on LAN-discovered servers, which then
   refuse the player anyway; Horizon stops at once.)
5. Send `ServerboundKeyPacket` (the secret and the challenge, each RSA PKCS#1 v1.5 encrypted with
   the server key), then AES/CFB8 (key = IV = the secret) both ways.

The connecting screen follows vanilla's states: "Connecting to the server..." until the encryption
request, "Logging in..." while joining the session service, "Encrypting...", then "Joining world...".
Code: `horizon-protocol` (`rsa.rs`, `crypto::server_hash`), `horizon-client` (`auth.rs`, `net.rs`).

Horizon's own dedicated and LAN servers stay offline-mode (they don't verify players with the
session service); that is separate work.

`HORIZON_API_DISCOVERY` overrides the discovery URL, the counterpart of authlib's
`-Dminecraft.api.discovery.host`; it is how the harness points both the vanilla server and Horizon at
a local mock.

## Skins and capes (part b)

Profile properties (`textures`, base64 JSON) arrive in `ClientboundPlayerInfoUpdatePacket` for every
player and in the login profile for ourselves. Like authlib's `unpackTextures`, only URLs under the
discovery document's `profiles/getTexture` `validUris` (textures.minecraft.net) are fetched; skins
(classic/slim from the `metadata.model`), capes and elytra textures are downloaded over HTTPS on a
worker thread, cached on disk by texture hash (`assets/skins/xx/hash`, like vanilla's
`SkinManager`), converted from legacy 64×32 the way `SkinTextureDownloader` does and given to the
player renderer. Until a skin arrives the default skin for the UUID shows (as today).

## Chat signing (part d)

26.3's dedicated servers default to `enforce-secure-profile=true`. A client without a chat session
can join and play, but every chat message and signed command argument is refused with "Chat
disabled due to missing profile public key. Please try reconnecting." (`SignedMessageChain.Decoder.unsigned`).
To chat on such servers the game will:

- fetch the profile key pair from the services `player/getCertificates` endpoint (Minecraft token);
- send `ServerboundChatSessionUpdatePacket` (random session UUID, key expiry, public key, Mojang's
  key signature) after joining;
- sign each chat message and signable command argument with SHA256withRSA over vanilla's
  `SignedMessageBody` layout and keep the last-seen message tracker and acknowledgements.

Until part d lands, Horizon joins online servers but chat works only where
`enforce-secure-profile=false` (or the server can't validate keys).

## Harnesses

`tools/test_online_mode_parity.py` (dev only, needs no account): a local mock of the Minecraft
services (discovery document, `join`, `hasJoined`/`verify`, no public keys) and a vanilla 26.3
dedicated server in online mode started with `-Dminecraft.api.discovery.host=<mock>` (authlib
10.0.77's only override: it replaces the whole discovery URL; the old `minecraft.api.session.host`
style properties are gone). Horizon's
headless client (`HORIZON_NET_REPORT`) joins with a session file holding a mock token: the server
verifies the join through the mock with the hash it computed itself (so the RSA wrapping, the hash
and AES/CFB8 are all checked against vanilla's code), the player spawns, chats and runs `/list`.
Negative cases: a token the mock rejects (the client must show vanilla's "Invalid session" message)
and a client that skips the join (the server must say "Failed to verify username!").

Rust unit tests: server hash vectors (Notch, jeb_, simon), RSA wrapping round trip with a test key,
X.509 key parsing, AES/CFB8 vectors (already in `horizon-protocol`), the session file (permissions,
age, deletion), the error mapping. Launcher: the whole token chain against a local mock of the
Microsoft, Xbox and Minecraft endpoints, and the keychain abstraction with an in-memory backend.

## PR plan

- (a) Game: online-mode handshake, encryption, session join, session file, harness (15/15 checks
  against vanilla 26.3 on macOS).
- (c) Launcher: device-code sign-in, token chain, keychain, accounts UI, CLI/MCP (`account list`,
  `account sign-in`, `account sign-out`, never tokens), session file handoff.
- (b) Game: skins and capes over HTTPS, the real names and skins in game.
- (d) Game: chat signing (profile keys, chat session, signed messages and commands).

Each part ships on its own: online mode needs a session, which only (c) creates.