service

Documentation

Index

• Constants
• type AuthorizationEnvironment
  • func (e *AuthorizationEnvironment) MultiplayerToken(ctx context.Context, src TokenSource, key *ecdsa.PublicKey) (string, error)
  • func (e *AuthorizationEnvironment) Renew(ctx context.Context, token *Token, user UserConfig) (*Token, error)
  • func (e *AuthorizationEnvironment) ServiceName() string
  • func (e *AuthorizationEnvironment) Token(ctx context.Context, config TokenConfig) (*Token, error)
  • func (e *AuthorizationEnvironment) TokenSource(ctx context.Context, src oauth2.TokenSource, config TokenConfig) TokenSource
  • func (e *AuthorizationEnvironment) UnmarshalJSON(b []byte) error
  • func (e *AuthorizationEnvironment) Verifier() (*oidc.IDTokenVerifier, error)
  • func (e *AuthorizationEnvironment) VerifierContext(ctx context.Context) (*oidc.IDTokenVerifier, error)
• type Configuration
• type DeviceConfig
• type Discovery
  • func Discover(ctx context.Context, appType, version string) (*Discovery, error)
  • func (d *Discovery) Environment(env Environment) error
• type Environment
• type Token
  • func (t *Token) SetAuthHeader(req *http.Request)
  • func (t *Token) Valid() bool
• type TokenConfig
• type TokenSource
• type UserConfig

Constants

const (
	// ApplicationTypeDedicatedServer is the application type for Bedrock Dedicated Server.
	// distributed by Mojang/Microsoft. For only usage for listeners, it might be preferred
	// over ApplicationTypeMinecraftPE.
	ApplicationTypeDedicatedServer = "MinecraftDedicatedServer"

	// ApplicationTypeMinecraftPE is the application type for Minecraft: Bedrock Edition
	// clients on all platform.
	//
	// ApplicationTypeMinecraftPE should be the default application type used in most services
	// as indicates both server and client.
	ApplicationTypeMinecraftPE = "MinecraftPE"
)

const (
	// CapabilityRayTracing indicates that the device is capable for ray tracing.
	CapabilityRayTracing = "RayTracing"
	// CapabilityVibrantVisuals indicates that the device is capable for rendering with Vibrant Visuals mode.
	CapabilityVibrantVisuals = "VibrantVisuals"
)

const DeviceTypeWindows10 = "Windows10"

DeviceTypeWindows10 is reported on both Windows 10/11 devices running either UWP or GDK installation of the game.

const PlatformWindows10 = "Windows10"

PlatformWindows10 is reported on both Windows 10/11 devices running either UWP or GDK installation of the game.

const StorePlatformUWPStore = "uwp.store"

StorePlatformUWPStore defines that Microsoft Store is the primary store platform for the device, and is reported on both Windows 10/11 devices running either UWP or GDK installation of the game.

const TokenTypePlayFab = "PlayFab"

TokenTypePlayFab indicates that PlayFab is used for the underlying identity provider for the TokenConfig.

Types

type AuthorizationEnvironment

type AuthorizationEnvironment struct {
	// ServiceURI is the base URI of the authorization service where requests should be
	// directed. Methods implemented in [Environment] parses this URI as a [url.URL] then
	// appends a relative path for making an API call to the authorization service.
	ServiceURI *url.URL `json:"serviceUri"`
	// Issuer is the issuer used for OpenID Token Authentication.
	Issuer *url.URL `json:"issuer"`
	// PlayFabTitleID is the title ID specific for PlayFab for retail versions of the
	// game. It is typically '20CA2', and this is not something that could be easily
	// changed. By using PlayFabTitleID, the API host for PlayFab will be '<titleID.playfabapi.com>'.
	PlayFabTitleID string `json:"playFabTitleId"`
	// EduPlayFabTitleID is the title ID specific for PlayFab for Education Edition
	// of the game. It is used in educational versions to authenticate with a Student
	// account and to log in with some of the services for Education Edition.
	EduPlayFabTitleID string `json:"eduPlayFabTitleId"`

	// HTTPClient is the HTTP client used for requests made by AuthorizationEnvironment.
	// If nil, [http.DefaultClient] is used.
	HTTPClient *http.Client `json:"-"`

	// KeyRefreshInterval controls how often public keys used for verifying multiplayer tokens may
	// be refreshed. If zero, a default of 30 minutes is used.
	KeyRefreshInterval time.Duration `json:"-"`
	// contains filtered or unexported fields
}

AuthorizationEnvironment represents an authorization environment for Minecraft-related services.

func (*AuthorizationEnvironment) MultiplayerToken

func (e *AuthorizationEnvironment) MultiplayerToken(ctx context.Context, src TokenSource, key *ecdsa.PublicKey) (string, error)

MultiplayerToken issues a token signed by the authorization service that can be used to authenticate with a multiplayer server. The public key can will be used as the 'cpk' claim of the token. Servers can verify this JWT using the remote OpenID configuration published by the authorization service and validate the claims to authenticate the player.

func (*AuthorizationEnvironment) Renew

func (e *AuthorizationEnvironment) Renew(ctx context.Context, token *Token, user UserConfig) (*Token, error)

Renew requests a refresh of a token that may soon expire. The user config must contain a valid PlayFab token that belong to the same user identity that was previously used for the Token. It is recommended to use TokenSource instead which subsequently renews the token.

func (*AuthorizationEnvironment) ServiceName

func (e *AuthorizationEnvironment) ServiceName() string

ServiceName implements service.Environment.ServiceName and returns "auth".

func (*AuthorizationEnvironment) Token

func (e *AuthorizationEnvironment) Token(ctx context.Context, config TokenConfig) (*Token, error)

Token issues a Token through the authorization service using the TokenConfig. If TokenConfig is missing some values for the required fields, it will override them with default values.

func (*AuthorizationEnvironment) TokenSource

func (e *AuthorizationEnvironment) TokenSource(ctx context.Context, src oauth2.TokenSource, config TokenConfig) TokenSource

TokenSource returns an implementation of TokenSource, which subsequently supplies the token by either newly requesting or refreshing an existing, cached token.

Note: The returned TokenSource captures ctx and reuses it for all subsequent refreshes. If you intend to keep the returned TokenSource around after the initial operation completes (for example, beyond a dial context that may be cancelled), pass a context stripped of cancellation/deadlines such as context.WithoutCancel(ctx). This preserves context values (like oauth2.HTTPClient or auth token caches) without future refresh failures due to ctx cancellation.

func (*AuthorizationEnvironment) UnmarshalJSON

func (e *AuthorizationEnvironment) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.UnmarshalJSON. Since UnmarshalText() is not implemented in url.URL and json.Unmarshal attempts to decode the string URL as a struct, it will first decode the URL fields as strings then parse them manually. See: https://github.com/golang/go/issues/52638

func (*AuthorizationEnvironment) Verifier

func (e *AuthorizationEnvironment) Verifier() (*oidc.IDTokenVerifier, error)

Verifier returns an oidc.IDTokenVerifier that can be used to verify the multiplayer token sent from clients in the Login packet to authenticate themselves with a remote OpenID configuration.

func (*AuthorizationEnvironment) VerifierContext

func (e *AuthorizationEnvironment) VerifierContext(ctx context.Context) (*oidc.IDTokenVerifier, error)

VerifierContext returns an oidc.IDTokenVerifier that can be used to verify the multiplayer token sent from clients in the Login packet to authenticate themselves with a remote OpenID configuration.

type Configuration

type Configuration struct {
	// ID is the name of the Configuration.
	// It is typically 'Minecraft'.
	ID string `json:"id"`
	// Parameters contains data-driven parameters for the
	// components of the game client.
	//
	// It encapsulates every value in string even if the underlying type
	// is not string. For example the value true will be present as the
	// string 'true'.
	Parameters map[string]string `json:"parameters"`
}

Configuration represents a configuration set for the application.

type DeviceConfig

type DeviceConfig struct {
	// ApplicationType indicates the type of the application associated with the device. It could be
	// one of constants defined below and is typically 'MinecraftPE' for most cases.
	ApplicationType string `json:"applicationType,omitempty"`

	// Capabilities is a list of features and functionalities supported by the device. Example might
	// include graphics capabilities like 'RayTracing' or other hardware or software features.
	// It is represented as an empty JSON array if none of capabilities are specified.
	Capabilities []string `json:"capabilities"`

	// GameVersion indicates the version of the game running on the device. It is typically [protocol.CurrentVersion]
	// to ensure compatibility with the current version of the `protocol` package.
	GameVersion string `json:"gameVersion,omitempty"`

	// ID is a unique ID associated with the device. It is typically represented in UUID.
	// The simplest way to generate ID is via [github.com/google/uuid.NewString].
	ID string `json:"id,omitempty"`

	// HardwareMemoryTier ranks the tier of the hardware memory measured in the device.
	// It is unclear how this value is determined and how it is used.
	// For example, HardwareMemoryTier is 5 for 16GB devices.
	HardwareMemoryTier int `json:"hardwareMemoryTier,omitempty"`

	// Memory is the total amount of the memory available on the device,
	// represented as a numerical string. It defaults to 16GB if not present.
	Memory string `json:"memory,omitempty"`

	// Platform denotes the platform on which the device operates.
	// Platform could be one of the constants below, including 'Windows10'
	// for Windows 10/11 devices.
	Platform string `json:"platform,omitempty"`

	// PlayFabTitleID is the title ID specific to PlayFab.
	// It is typically '20CA2' for retail versions of the game.
	PlayFabTitleID string `json:"playFabTitleId,omitempty"`

	// StorePlatform represents the digital store platform where an in-app purchase is made.
	// StorePlatform could be one of the constants defined below, including 'UWPStore'
	// for Windows Store.
	StorePlatform string `json:"storePlatform,omitempty"`

	// TreatmentOverrides specifies any custom treatments that should be assigned to the Token.
	// These treatments may affect how the Token is handled or used across various services.
	//
	// For example, the signaling service may reject delivering signals to remote NetherNet network
	// if 'mc-signaling-usewebsockets' is not assigned for the token via TreatmentOverrides.
	TreatmentOverrides []string `json:"treatmentOverrides,omitempty"`

	// Type defines the general type of the device.
	// Type could be one of the constants below, including 'Windows10'
	// for Windows 10/11 devices.
	Type string `json:"type,omitempty"`
}

DeviceConfig describes the configuration of the device that is running the application. It contains several fields that defines the features and capabilities of the device, which are associated with the Token being obtained.

type Discovery

type Discovery struct {
	// ServiceEnvironments is a map where each key represent a service name.
	// Each value contains a nested map where keys are environment types like
	// 'prod' and values are service-specific data represented as [json.RawMessage].
	//
	// Normally, 'prod' will be the only available type for the environment on
	// retail versions of the game.
	ServiceEnvironments map[string]map[string]json.RawMessage `json:"serviceEnvironments"`

	// SupportedEnvironments is a map where each key is the version of the game
	// and each value is a slice of supported environment types for the version.
	// Typically, the only environment type available for a version is "prod".
	SupportedEnvironments map[string][]string `json:"supportedEnvironments,omitempty"`
}

Discovery provides environments for various services for Minecraft: Bedrock Edition.

A Discovery can be obtained from Discover using a specific application type with a build version.

func Discover

func Discover(ctx context.Context, appType, version string) (*Discovery, error)

Discover obtains a Discover for the specific version for the specific application type. The returned Discovery contains environments for various services in Minecraft: Bedrock Edition and will be used as the configuration for each service.

The version typically doesn't matter in any way, but it is still recommended to specify protocol.CurrentVersion to keep up the compatibility with the `protocol` package.

Discover caches the result and can be called multiple times by various services without waiting for network latency each time if cache was hit.

func (*Discovery) Environment

func (d *Discovery) Environment(env Environment) error

Environment looks up for a value in [Discovery.ServiceEnvironments] using [Environment.ServiceName] as the key, then decodes the nested payload into the Environment.

It is called by various network services on Minecraft: Bedrock Edition and is used to set up the environment based on remote configuration.

type Environment

type Environment interface {
	// ServiceName returns the name of the service.
	// It is used as the top-most keys of [Discovery.ServiceEnvironments].
	ServiceName() string
}

Environment represents the configuration for a network service in Minecraft: Bedrock Edition. Each service must implement Environment as a struct representing a JSON object to be decoded from the nested value from [Discovery.ServiceEnvironments].

type Token

type Token struct {
	// AuthorizationHeader is the JWT string that is used as the 'Authorization' header
	// to the requests ongoing to various network services for Minecraft: Bedrock Edition.
	//
	// [Token.SetAuthHeader] can be used to easily set an 'Authorization' header to this
	// value in a [http.Request].
	AuthorizationHeader string `json:"authorizationHeader"`

	// ValidUntil is the expiration time of the Token.
	// Once the current time surpasses the expiration time, the Token
	// is no longer valid, and needs to be either requested again or renewed
	// before the Token expires in a specific delta.
	ValidUntil time.Time `json:"validUntil"`

	// Treatments is a list of treatments that have been assigned to the Token.
	// Treatments may affect how the Token is validated or handled in various network
	// services in Minecraft: Bedrock Edition, and can be overridden using
	// [DeviceConfig.TreatmentOverrides].
	Treatments []string `json:"treatments"`

	// Configuration is a map of configuration specific to the application
	// the Token was authenticated in.
	Configuration map[string]Configuration `json:"configurations"`

	// TreatmentContext is a combination of Treatments separated by ';'.
	// It is unknown how it is used.
	TreatmentContext string `json:"treatmentContext"`
}

Token represents an authentication token used for various network services in Minecraft: Bedrock Edition.

A Token may be issued using AuthorizationEnvironment.Token with a TokenConfig. As each Token has expiration, it is recommended to use a TokenSource so it can be renewed subsequently when it becomes invalid.

func (*Token) SetAuthHeader

func (t *Token) SetAuthHeader(req *http.Request)

SetAuthHeader sets an 'Authorization' header of the request to [Token.AuthorizationHeader].

func (*Token) Valid

func (t *Token) Valid() bool

Valid returns a bool indicating if the Token is valid.

type TokenConfig

type TokenConfig struct {
	// Device holds a configuration of the device for which the Token is being associated.
	// Device contains other non-user-specific fields including treatments or the game version.
	Device DeviceConfig `json:"device,omitempty"`

	// User contains user identity encapsulated in a UserConfig.
	// User contains an identity token authenticated with PlayFab via an external platform.
	User UserConfig `json:"user,omitempty"`
}

TokenConfig defines the configuration required to obtain a Token through the authorization service.

It contains configurations for both devices and users associated with a Token.

type TokenSource

type TokenSource interface {
	// Token returns a Token that is not expired and is determined
	// to be valid from [Token.Valid]. An error may be returned by
	// identity providers such as PlayFab or Xbox Live, rather than
	// by the authorization service.
	Token() (*Token, error)
}

TokenSource supplies a Token for authenticating with various network services in Minecraft: Bedrock Edition from underlying identity providers including PlayFab and Xbox Live.

It is recommended to use AuthorizationEnvironment.TokenSource.

type UserConfig

type UserConfig struct {
	// Language is the base language of the user without region.
	// For example, if the game language was configured to
	// 'en-US', then Language will be 'en'.
	Language string `json:"language,omitempty"`

	// LanguageCode is the user language with the region.
	// It is typically same as what user has configured in the game.
	LanguageCode language.Tag `json:"languageCode,omitempty"`

	// RegionCode denotes the specific region associated with the language.
	// It is typically derived from [language.Tag.Region].
	// For example, if the game language was configured to
	// 'en-US', then RegionCode will be 'US'.
	RegionCode string `json:"regionCode,omitempty"`

	// Token is the identity token used for authentication.
	// It is a crucial field that holds the actual token required to
	// authenticate the user.
	//
	// If TokenType is set to 'PlayFab', then the Token will be the
	// session ticket taken from the initial login response from PlayFab,
	// which is obtained using either an Xbox Live token or custom account.
	Token string `json:"token,omitempty"`

	// TokenType specifies the provider of the Token.
	// The only known value for TokenType is 'PlayFab'.
	TokenType string `json:"tokenType,omitempty"`
}

UserConfig represents the configuration of the user whose Token is authenticated for. It includes various fields related to the identity and language preferences of the user.