xsts

type DisplayClaims struct {
	// UserInfo lists the users claimed by the token.
	//
	// For most XSTS tokens, only a single UserInfo is claimed by the token.
	UserInfo []UserInfo `json:"xui"`
}

type Privileges []uint32

type Token internal.Token[DisplayClaims]

type TokenSource interface {
	// XSTSToken returns an XSTS token issued for the specified relying party.
	//
	// The relying party identifies the service for which the token is valid
	// and determines which claims are included in the resulting token. Common
	// relying parties include:
	//   - "http://xboxlive.com" for Xbox Live user services
	//   - Title- or service-specific endpoints
	//
	// In most cases, the relying party is resolved automatically using
	// NSAL (Network Security Allow List) based on the request URL by the caller.
	//
	// The provided context controls the lifetime of the request and may be
	// used to cancel in-flight authentication operations.
	//
	// Implementations may cache and reuse tokens until they expire
	XSTSToken(ctx context.Context, relyingParty string) (*Token, error)
}

type UnderlyingToken interface {
	Valid() bool
}

type UserInfo struct {
	xasu.UserInfo

	// GamerTag is the user's display name.
	//
	// This is the primary name shown in Xbox experiences and most games.
	// For users with modern gamertags, this value is the concatenation of
	// ModernGamerTag and ModernGamerTagSuffix without a separator.
	//
	// This field is only present in tokens that rely on the
	// party "http://xboxlive.com".
	GamerTag string `json:"gtg,omitempty"`

	// XUID is the user's unique numeric Xbox user identifier.
	//
	// XUIDs are stable across services and are commonly used for identifying
	// users in Xbox Live APIs.
	//
	// This field is only present in tokens that rely on the
	// party "http://xboxlive.com".
	XUID string `json:"xid,omitempty"`

	// ModernGamerTag is the base portion of a modern gamertag, excluding
	// the numeric suffix.
	//
	// This field is only present for users who have modern gamertags and
	// only in tokens that rely on the party "http://xboxlive.com".
	ModernGamerTag string `json:"mgt,omitempty"`

	// ModernGamerTagSuffix is the numeric suffix of a modern gamertag,
	// without the hash character.
	//
	// This field is only present for users who have modern gamertags and
	// only in tokens that rely on the party "http://xboxlive.com".
	ModernGamerTagSuffix string `json:"mgs,omitempty"`

	// UniqueModernGamerTag is the fully qualified modern gamertag in the
	// format "[UserInfo.ModernGamerTag]#[UserInfo.ModernGamerTagSuffix]".
	//
	// This value uniquely identifies the user among modern gamertags.
	// It is only present in tokens that rely on the
	// party "http://xboxlive.com".
	UniqueModernGamerTag string `json:"umg,omitempty"`

	// AgeGroup indicates the age classification of the user account.
	//
	// Typical values include "Adult", "Teen", and "Child", as defined by
	// the AgeGroup* constants in this package. Non-adult values are commonly
	// associated with family accounts managed by an adult account.
	//
	// This field is only present in tokens that rely on the
	// party "http://xboxlive.com".
	AgeGroup string `json:"agg,omitempty"`

	// Privileges lists the privileges granted to the user.
	//
	// Each entry corresponds to a numeric privilege identifier defined by
	// the Privilege* constants in this package. Privileges control access
	// to features such as multiplayer, communication, and content sharing.
	//
	// This field is only present in tokens that rely on the
	// party "http://xboxlive.com".
	Privileges Privileges `json:"prv,omitempty"`
}

type UserInfoProvider interface {
	// UserInfo returns the UserInfo extracted from the XSTS token's
	// display claims.
	//
	// The returned value must represent valid user information derived
	// from the authorization token. Implementations are expected to
	// cache this information after the initial sign-in.
	//
	// This method does not return an error to simplify caller logic.
	UserInfo() UserInfo
}