User Module

Provide Yggdrasil auth and profile service for Minecraft protocol.

Usage

Microsoft API

Due to the complexity of the Microsoft authentication. The library only provide parts of microsoft login process. You need to implement the rest of the process by yourself.

Overall, according to the wiki.vg, the MS login process can break into following steps:

1. Aquire Microsoft access token by oauth (user -> ms token)
2. Acquire XBox token by Microsoft access token (ms token -> xbox token)
3. Acquire Minecraft access token by XBox token (xbox token -> minecraft token)

The library does not cover the first step.

• For nodejs, you can use msal-node to implement 1st step.
• For browser, you can use msal-browser to implement 1st step.

If you want a reference, this is the live example for nodejs/electron using msal-node.

Here we only demo the case you already got the Microsoft access token.

import { MicrosoftAuthenticator } from '@xmcl/user'

const authenticator = new MicrosoftAuthenticator();

const msAccessToken: string; // the access token you got from msal

const { liveXstsResponse, minecraftXstsResponse } = await authenticator.acquireXBoxToken(msAccessToken);

// You can use liveXstsResponse to get the xbox user avatar and name.
const const xboxGameProfile = await authenticator.getXboxGameProfile(xstsResponse.DisplayClaims.xui[0].xid, xstsResponse.DisplayClaims.xui[0].uhs, liveXstsResponse.Token);

// you can use the xstsResponse to get the minecraft access token
const mcResponse = await authenticator.loginMinecraftWithXBox(minecraftXstsResponse.DisplayClaims.xui[0].uhs, minecraftXstsResponse.Token);

// the accessToken is the common minecraft token we want!
const accessToken: string = mcResponse.access_token;
const username = mcResponse.username;
const expire = mcResponse.expires_in; // in seconds

Yggdrasil API

Most of third-party authentication service is based on Yggdrasil API. See authlib-injector for more information.

The legacy mojang auth server, https://authserver.mojang.com is also a yggdrasil api server, but it is not recommended to use it.

import { YggdrasilClient, YggrasilAuthentication } from "@xmcl/user";

const client = new YggdrasilClient('http://random.authserver');
const username: string;
const password: string;
const clientToken: string; // you can use uuid to generate a client token
// login
const auth: YggrasilAuthentication = await client.login({ username, password, clientToken });

// validate access token, you can use this when you restart the program
const valid: boolean = await client.validate(auth.accessToken, clientToken);

// refresh access token, if token is invalid, you can use this to get a new one
const newAuth: YggrasilAuthentication = await client.refresh({ accessToken: auth.accessToken, clientToken });

Third-party Yggdrasil API

The authlib-injector also implements several API for user skin operation.

We also support these API:

import { YggdrasilThirdPartyClient } from "@xmcl/user";

const client = new YggdrasilThirdPartyClient('http://random.authserver');

const uuid: string; // user uuid

// lookup user profile with texture
const profile = await client.lookup(uuid);
const infos: GameProfile.TexturesInfo | undefined = getTextures(gameProfile);
const skin: GameProfile.Texture = infos!.textures.SKIN!;
const skinUrl: string = skin.url; // use url to display skin
const isSlim: boolean = GameProfile.Texture.isSlim(skin); // determine if model is slim or not

// set user skin
const accessToken: string;
const skinUrl: string;
await client.setTexture({ accessToken, uuid, type: "skin", texture: { url: skinUrl } });

// set user skin via binary
const skinData: Uint8Array;
await client.setTexture({ accessToken, uuid, type: "skin", texture: { data: skinData } });

Offline

import { offline } from "@xmcl/user";

// create a offline user
const offlineUser = offline("username");

// create an offline user with uuid
const offlineUser1 = offline("username", "uuid");

🧾 Classes

MicrosoftAuthenticatorMojangClientMojangErrorProfileNotFoundErrorSetNameErrorSetSkinErrorUnauthorizedErrorYggdrasilClientYggdrasilErrorYggdrasilThirdPartyClient

🤝 Interfaces

GameProfileGameProfileWithPropertiesMicrosoftMinecraftProfileMinecraftAuthResponseMinecraftOwnershipResponseMinecraftProfileErrorResponseMinecraftProfileResponseMojangCapeMojangChallengeMojangChallengeResponseMojangSkinNameChangeInformationProfileLookupExceptionSetTextureOptionXBoxGameProfileResponseXBoxResponseYggdrasilClientOptionsYggdrasilTextureYggdrasilTexturesInfoYggrasilAuthentication

🏳️ Enums

NameAvailability

🏭 Functions

getOfflineUUID

getOfflineUUID(username: string): string

Parameters

• username: string

Return Type

• string

Defined in: packages/user-offline-uuid/index.ts:3

getTextureType

getTextureType(o: YggdrasilTexture): "slim" | "steve"

Parameters

• o: YggdrasilTexture

Return Type

• "slim" | "steve"

Defined in: packages/user/yggdrasil.ts:221

isTextureSlim

isTextureSlim(o: YggdrasilTexture): boolean

Parameters

• o: YggdrasilTexture

Return Type

• boolean

Defined in: packages/user/yggdrasil.ts:217

newToken

newToken(): string

Random generate a new token by uuid v4. It can be client or auth token.

Return Type

• string

Defined in: packages/user/offline.ts:8

offline

offline(username: string, uuid: string): Object

Create an offline auth. It'll ensure the user game profile's uuid is the same for the same username.

Parameters

• username: string The username you want to have in-game.
• uuid: string

Return Type

• Object

Defined in: packages/user/offline.ts:19