MC Auth Lib

A pipeline-based authentication library for Minecraft, supporting multiple authentication schemes.

Usage

Microsoft Local Web Server Authentication

val authScheme = MSLocalWebServerScheme("your-client-id", 25575)

authScheme.authenticate { stage, maxStages, result ->
    when (result) {
        is AuthResult.Ok -> println("$stage/$maxStages: ${result.msg}")
        is AuthResult.Err -> println("Error @ $stage: ${result.error}")
    }
}.thenAccept { session ->
    println("Logged in as ${session.username}")
}

// or refresh an account with a refresh token
authScheme.refresh("refreshToken") { stage, maxStages, result ->
    when (result) {
        is AuthResult.Ok -> println("$stage/$maxStages: ${result.msg}")
        is AuthResult.Err -> println("Error @ $stage: ${result.error}")
    }
}.thenAccept { session ->
    println("Logged in as ${session.username}")
}

Cookie-Based Authentication

val authScheme = CookieAuthScheme()
val cookieFile = File("cookies.txt")

authScheme.import(cookieFile) { stage, maxStages, result ->
  when (result) {
      is AuthResult.Ok -> println("$stage/$maxStages: ${result.msg}")
      is AuthResult.Err -> println("Error @ $stage: ${result.error}")
  }
}.thenAccept { session ->
    println("Logged in as ${session.username}")
}

// or directly authenticate with a cookie header
authScheme.authenticate("COOKIE_HEADER_STRING") { stage, maxStages, result ->
    // handle progress here
}

Reference

SessionData

Represents an authenticated session:

data class SessionData(
    val username: String,        // Minecraft username
    val uuid: String,            // Player UUID
    val accessToken: String,     // Minecraft access token
    val refreshToken: String,    // Refresh token (if available, usually unavailable for cookie accounts)
    val cookie: String,          // Cookie header (for cookie auth)
    val lastUpdated: Long,       // Timestamp of last refresh / update
    val type: GameAuthenticationType  // Authentication type (MICROSOFT, NETSCAPE_COOKIE)
)

AuthResult

Class representing the result of authentication:

sealed class AuthResult {
    data class Ok(
        val data: Map<String, Any> = emptyMap(),
        val msg: String? = null
    ) : AuthResult()
    
    data class Err(
        val error: String
    ) : AuthResult()
}

StateCallback

Interface for tracking authentication progress:

fun interface StateCallback {
    fun invoke(stage: Int, maxStages: Int, ctx: Context, result: AuthResult)
}

Custom Authentication Pipelines

You can create custom authentication pipelines like this:

val customPipeline = Pipeline(
    listOf(
        YourCustomStage(),
        AnotherStage(),
        MinecraftProfileStage()
    )
)

customPipeline.run(
    initial = mapOf("someData" to "value"),
    stateChange = { stage, maxStages, ctx, result ->
        // handle updates
    }
)

To create your own custom authentication stage, implement the Stage interface:

class CustomStage : Stage {
    override val name = "Custom Authentication"
    
    override fun run(ctx: Context): CompletableFuture<AuthResult> {
        return CompletableFuture.supplyAsync {
            runCatching {
                val someValue: String = ctx.require("someKey")
              
                // logic here or some shit idk what u want
              
                AuthResult.Ok(
                    mapOf("resultKey" to "resultValue"),
                    "Custom stage completed"
                )
            }.getOrElse { 
                AuthResult.Err("Custom stage error: ${it.message}") 
            }
        }
    }
}

Errors

All authentication methods return CompletableFuture<SessionData>. You can handle errors like this:

authScheme.authenticate()
    .thenAccept { session ->
        // success - use the session.
    }
    .exceptionally { throwable ->
        println("Authentication failed: ${throwable.message}")
        null
    }

Support

For issues, questions, or contributions, please kindly fuck off.