trapdoor-yggdrasil

An authentication library, for interfacing with Minecraft's authentication server, Yggdrasil.

Example Usage

YggdrasilAuthenticator

var YggdrasilAuthenticator = require("trapdoor-yggdrasil").YggdrasilAuthenticator;

// We'll start up a new YggdrasilAuthenticator - nothing special, yet.
var a = new YggdrasilAuthenticator();

// First, we'll check to see whether or not the server is up
a.checkAuthServer(function(response) {
    // It is! Log some of that data...
    a.logger.info("Status: " + response["Status"]);
    a.logger.info("Runtime Mode: " + response["Runtime-Mode"]);
    a.logger.info("Application Name: " + response["Application-Name"]);
    a.logger.info("Application Version: " + response["Implementation-Version"]);
    // Make sure to set the authenticatorService appropriately, so that
    // our authenticate call doesn't get mucked up.
    a.authenticatorService = (response["Status"] == "OK");
    // Speaking of which, let's try authenticating now.
    a.authenticate(<username>, <password>, function(response) {
        // Alright, we're in - the profile we just auth'd into.
        a.logger.info(response.selectedProfile);
    }, function(response) {
        // No dice - probably invalid credentials or the like.
        // Log the failure.
        a.logger.fatal(response.errorMessage);
    });
}, function(response) {
    // Super bad luck - Yggdrasil isn't up. Log our failure.
    a.logger.fatal(response.errorMessage);
});

Functions

YggdrasilAuthenticator

new YggdrasilAuthenticator()

Options

N/A

Description

Generates an YggdrasilAuthenticator object, able to take Yggdrasil credentials and generate auth tokens.

YggdrasilAuthenticator#checkAuthServer()

Options

• onSuccess : Callback, called on success - should take one argument, response, which is an object parsed from the JSON chunk returned from the check request.
• onFailure : Callback, called on failure - should take one argument, response, same as above.

Description

Checks if auth server is up and if Status value is OK. Calls onSuccess if it is, onFailure if it isn't - both with a response argument containing an object parsed from the JSON chunk returned from the request.

YggdrasilAuthenticator#authenticate

Options

• username : Username of account to authenticate with (either original MC username or email if migrated)
• password : Password to above account
• onSuccess : Callback, called on success - should take one argument, response, which is an object parsed from the JSON chunk returned from the auth request.
• onFailure : Callback, called on failure - should take one argument, response, same as above.
• clientToken (default: undefined): Client token to be passed into auth reuqest - should be a version 4 UUID. If left undefined, the server will generate one based on Java's UUID.toString().
• agent (default: {"name": "Minecraft", "version": 1}): Agent requesting the authentication, usually should be left to default as this is the only known working value for the purposes of this module.

Description

Makes a HTTPS request to the /authenticate route on Mojang's Yggdrasil authentication server, with the supplied username, password, clientToken and agent arguments. Calls onSuccess if authentication is successful, onFailure if it isn't - both with a response argument containing an object parsed from the JSON chunk returned from the request.

YggdrasilAuthenticator#refresh

Options

• accessToken : Yggdrasil access token, obtained from a previous successful call to authenticate.
• clientToken : Token used in (or obtained from) a previous call to authenticate. Note: This token must be identical to the one used to generate the above accessToken - the call will fail if it is not.
• onSuccess : Callback, called on success - should take one argument, response, which is an object parsed from the JSON chunk returned from the refresh request.
• onFailure : Callback, called on failure - should take one argument, response, same as above.

Description

Makes a HTTPS request to the /refresh route on Mojang's Yggdrasil authentication server, with the supplied accessToken and clientToken arguments. This route attempts to "refresh" a valid accessToken, generating a new one. Calls onSuccess if the refresh was successful, onFailure if it wasn't - both with a response argument containing an object parsed from the JSON chunk returned from the request.

YggdrasilAuthenticator#validate

Options

• accessToken : Yggdrasil access token, obtained from a previous successful call to authenticate.
• clientToken : Token used in (or obtained from) a previous call to authenticate. Note: This token must be identical to the one used to generate the above accessToken - the call will fail if it is not.
• onSuccess : Callback, called on success - should take one argument, response, which is an object parsed from the JSON chunk returned from the validation request.
• onFailure : Callback, called on failure - should take one argument, response, same as above.

Description

Makes a HTTPS request to the /validate route on Mojang's Yggdrasil authentication server, with the supplied accessToken and clientToken arguments. This route checks to see whether or not accessToken is valid and able to be used to authenticate a user. Calls onSuccess if the refresh was successful, onFailure if it wasn't - both with a response argument containing an object parsed from the JSON chunk returned from the request.

YggdrasilAuthenticator#signout

Options

• username : Name of the account to sign out.
• password : Password to the above account.
• onSuccess : Callback, called on success - should take one argument, response, which will be empty if this request was truly successful.
• onFailure : Callback, called on failure - should take one argument, response, which will contain an error object parsed from the JSON the request returned.

Description

Makes a HTTPS request to the /signout route on Mojang's Yggdrasil authentication server, with the supplied username and password arguments. This route invalidates all instances of accessToken connected to this account, effectively "signing out" this user from every device that has stored their accessToken. Calls onSuccess if the signout was successful, onFailure if it wasn't - both with a response argument, which will be empty if the signout was truly successful, but contain error data if it wasn't.

YggdrasilAuthenticator#invalidate

Options

• accessToken : Yggdrasil access token, obtained from a previous successful call to authenticate.
• clientToken : Token used in (or obtained from) a previous call to authenticate. Note: This token must be identical to the one used to generate the above accessToken - the call will fail if it is not.
• onSuccess : Callback, called on success - should take one argument, response, which will be empty if the invalidation was truly successful.
• onFailure : Callback, called on failure - should take one argument, response, which will contain an error object parsed from the JSON the request returned.

Description

Makes a HTTPS request to the /invalidate route on Mojang's Yggdrasil authentication server, with the supplied accessToken and clientToken arguments. This route invalidates the accessToken passed to this function, rendering it unusable for authentication. Calls onSuccess if the invalidation was successful, onFailure if it wasn't - both with a response argument, which will be empty if the invalidation was truly successful, but contain error data if it wasn't.

YggdrasilAuthenticator#generateRequest

Options

• route : The route on Minecraft's Yggdrasil server to be accessed by the request.
• verb : HTTP verb to use when calling this request (e.g. GET, POST, etc.).
• onSuccess : Callback, called on request's success - should take one argument, response, which is an object parsed from the JSON chunk returned from the request.
• onFailure : Callback, called on request's failure - should take one argument, response, same as above.
• debugStatement : A small piece of text to be used in the debug logging, signifying what type of request this is and some of the pertinent (preferably non-sensitive) data it carries.
• requiresAuthServer (default: false): Determines whether or not the request will fail to execute if the current state of Authenticator.authenticatorService (preferably managed though a successful YggdrasilAuthenticator#checkAuthServer callback) is false.
• payload (default: ""): The JSON payload of this request, written to the https.request object only when verb is equivalent to POST.
• successCode (default: 200): The HTTP Status Code criteria for a "successful" call (calls onSuccess) - anything deviating from this successful code will call onFailure.

Description

Internal function, used to generate the https.request objects according to a standard schema.

Note: It is not reccomended to use this function on its own: YggdrasilAuthenticator already provides wrappers for every route available on a Yggdrasil server.

YggdrasilAuthenticator.processYggdrasilResponse

Options

• res :https.request response object - not to be confused with response, the object parsed from the JSON contained in chunk
• chunk : Data obtained from res and an appropriate (internal) data listener on an https.request object. Almost always a JSON string.
• onSuccess : Callback, called on success - should take one argument, response, which is an object parsed from the JSON chunk returned from parsing chunk
• onFailure : Callback, called on failure - should take one argument, response, same as above.

Description

Internal static function, used to process data from https.request responses pointed towards Mojang's Yggdrasil authentication server. Calls onSuccess if the result was successful, onFailure if it wasn't - both with a response argument containing an object parsed from the chunk string.

Notes

Check wiki.vg's authentication page for more information regarding the routes and payloads discussed here.