rbxauth

README

rbxauth

The rbxauth package is a wrapper for the Roblox authentication API (v2).

Documentation

Overview

The rbxauth package is a wrapper for the Roblox version 2 authentication API (Auth v2).

https://auth.roblox.com/docs

Index

• Constants
• func ReadCookies(r io.Reader) (cookies []*http.Cookie, err error)
• func WriteCookies(w io.Writer, cookies []*http.Cookie) (err error)
• type Config
  • func (c Config) Login(username string, password []byte) ([]*http.Cookie, *Step, error)
  • func (c Config) LoginCred(cred Cred, password []byte) (cookies []*http.Cookie, step *Step, err error)
  • func (c Config) LoginID(userID int64, password []byte) ([]*http.Cookie, *Step, error)
  • func (c Config) Logout(cookies []*http.Cookie) (err error)
• type Cred
• type ErrorResponse
  • func (err ErrorResponse) Error() string
• type Step
  • func (s *Step) Resend() (err error)
  • func (s *Step) Verify(code string, remember bool) (cookies []*http.Cookie, err error)
• type Stream
  • func StandardStream() *Stream
  • func (s *Stream) Prompt(username string) (cred Cred, cookies []*http.Cookie, err error)
  • func (s *Stream) PromptCred(cred Cred) (credout Cred, cookies []*http.Cookie, err error)
  • func (s *Stream) PromptID(userID int64) (cred Cred, cookies []*http.Cookie, err error)

Constants

const (
	DefaultLoginEndpoint  = "https://auth.roblox.com/v2/login"
	DefaultLogoutEndpoint = "https://auth.roblox.com/v2/logout"
	DefaultVerifyEndpoint = "https://auth.roblox.com/v2/twostepverification/verify"
	DefaultResendEndpoint = "https://auth.roblox.com/v2/twostepverification/resend"

	// The %d verb is replaced with a user ID.
	DefaultUserIDEndpoint = "https://api.roblox.com/users/%d"
)

Each of these constants define the default value used when the corresponding Endpoint field in Config is an empty string.

const (
	Username    string = "Username"    // The username associated with the account.
	Email       string = "Email"       // The email associated with the account.
	PhoneNumber string = "PhoneNumber" // The phone number associated with the account.
)

These constants define canonical strings used for Cred.Type, and are known to be accepted by the Auth v2 API.

Functions

func ReadCookies

func ReadCookies(r io.Reader) (cookies []*http.Cookie, err error)

ReadCookies parses cookies from r and returns a list of http.Cookies. Cookies are parsed as a number of "Set-Cookie" HTTP headers. Returns an empty list if the reader is empty.

func WriteCookies

func WriteCookies(w io.Writer, cookies []*http.Cookie) (err error)

WriteCookies formats a list of cookies as a number of "Set-Cookie" HTTP headers and writes them to w.

Types

type Config

type Config struct {
	// Client is used to make requests. If nil, the http.DefaultClient is used.
	Client *http.Client

	// Token is a string passed through requests to prevent cross-site request
	// forgery. The config automatically sets the this value from the previous
	// request.
	Token string

	// LoginEndpoint specifies the URL used for logging in.
	LoginEndpoint string
	// LogoutEndpoint specifies the URL used for logging out.
	LogoutEndpoint string
	// VerifyEndpoint specifies the URL used for verifying a two-step
	// authentication code.
	VerifyEndpoint string
	// ResendEndpoint specifies the URL used for resending a two-step
	// authentication code.
	ResendEndpoint string
	// UserIDEndpoint specifies the URL used to fetch a username from an ID. The
	// URL must contain a "%d" format verb, which is replaced with the user ID.
	UserIDEndpoint string
}

Config configures an authentication action. Authentication endpoints must implement Roblox's Auth v2 API. When an endpoint is an empty string, the value of the corresponding Default constant is used instead.

func (Config) Login

func (c Config) Login(username string, password []byte) ([]*http.Cookie, *Step, error)

Login wraps LoginCred, using a username for the credentials.

func (Config) LoginCred

func (c Config) LoginCred(cred Cred, password []byte) (cookies []*http.Cookie, step *Step, err error)

LoginCred attempts to authenticate a user by using the provided credentials.

The cred argument specifies the credentials associated with the account to be authenticated. As a special case, if the Type field is "UserID", then the Ident field is interpreted as an integer, indicating the user ID of the account. Note that an initial request must be made in order to associate the ID with its corresponding credentials.

The password argument is specified as a slice for future compatibility, where the password may be handled within secured memory.

On success, a list of HTTP cookies representing the session are returned. If multi-step authentication is required, then a Step object is additionally returned.

If a response has a non-2XX status, then this function returns an error that implements `interface { StatusCode() int }`.

func (Config) LoginID

func (c Config) LoginID(userID int64, password []byte) ([]*http.Cookie, *Step, error)

LoginID wraps LoginCred, deriving credentials from the given user ID. Note that an initial request must be made in order to associate the ID with its corresponding credentials.

func (Config) Logout

func (c Config) Logout(cookies []*http.Cookie) (err error)

type Cred

type Cred struct {
	Type  string // Type specifies the kind of identifier.
	Ident string // Ident is the identifier itself.
}

Cred holds credentials used to identify an account.

type ErrorResponse

type ErrorResponse struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Field   string `json:"field,omitempty"`
}

ErrorResponse implements the error response model of the API.

func (ErrorResponse) Error

func (err ErrorResponse) Error() string

Error implements the error interface.

type Step

type Step struct {

	// MediaType indicates the means by which the verification code was sent.
	MediaType string
	// contains filtered or unexported fields
}

Step holds the state of a multi-step verification action.

func (*Step) Resend

func (s *Step) Resend() (err error)

Resend retransmits a two-step verification message.

func (*Step) Verify

func (s *Step) Verify(code string, remember bool) (cookies []*http.Cookie, err error)

Verify receives a verification code to complete authentication. If successful, returns HTTP cookies representing the authenticated session.

The remember argument specifies whether the current device should be remembered for future authentication.

type Stream

type Stream struct {
	Config
	io.Reader
	io.Writer
}

Stream uses a io.Reader and an optional io.Writer to perform an interactive login.

func StandardStream

func StandardStream() *Stream

StandardStream returns a Stream connected to stdin and stderr.

func (*Stream) Prompt

func (s *Stream) Prompt(username string) (cred Cred, cookies []*http.Cookie, err error)

Prompt wraps PromptCred, using a username for the credentials. If the username is empty, it will also be prompted.

func (*Stream) PromptCred

func (s *Stream) PromptCred(cred Cred) (credout Cred, cookies []*http.Cookie, err error)

PromptCred prompts a user to login through the specified input stream. Handles multi-step verification, if necessary. If cred.Type and/or cred.Ident are empty, then they will be prompted as well.

Returns the updated cred and cookies, or any error that may have occurred.

func (*Stream) PromptID

func (s *Stream) PromptID(userID int64) (cred Cred, cookies []*http.Cookie, err error)

PromptID wraps PromptCred, deriving credentials from the given user ID. If the ID is less then 1, then it will also be prompted.

Note that an initial request must be made in order to associate the ID with its corresponding credentials.