auth

Documentation

Overview

Package auth provides authentication on top of tg.Client.

Index

• Variables
• func IsKeyUnregistered(err error) bool
• func IsUnauthorized(err error) bool
• type Client
  • func NewClient(api *tg.Client, rand io.Reader, appID int, appHash string) *Client
  • func (c *Client) AcceptTOS(ctx context.Context, id tg.DataJSON) error
  • func (c *Client) Bot(ctx context.Context, token string) (*tg.AuthAuthorization, error)
  • func (c *Client) IfNecessary(ctx context.Context, flow Flow) error
  • func (c *Client) Password(ctx context.Context, password string) (*tg.AuthAuthorization, error)
  • func (c *Client) SendCode(ctx context.Context, phone string, options SendCodeOptions) (*tg.AuthSentCode, error)
  • func (c *Client) SignIn(ctx context.Context, phone, code, codeHash string) (*tg.AuthAuthorization, error)
  • func (c *Client) SignUp(ctx context.Context, s SignUp) (*tg.AuthAuthorization, error)
  • func (c *Client) Status(ctx context.Context) (*Status, error)
  • func (c *Client) Test(ctx context.Context, dc int) error
  • func (c *Client) TestUser(ctx context.Context, phone string, dc int) error
• type CodeAuthenticator
• type CodeAuthenticatorFunc
  • func (c CodeAuthenticatorFunc) Code(ctx context.Context, sentCode *tg.AuthSentCode) (string, error)
• type Flow
  • func NewFlow(auth UserAuthenticator, opt SendCodeOptions) Flow
  • func (f Flow) Run(ctx context.Context, client FlowClient) error
• type FlowClient
• type SendCodeOptions
• type SignUp
• type SignUpRequired
  • func (s *SignUpRequired) Error() string
  • func (s *SignUpRequired) Is(err error) bool
• type Status
• type UserAuthenticator
  • func CodeOnly(phone string, code CodeAuthenticator) UserAuthenticator
  • func Constant(phone, password string, code CodeAuthenticator) UserAuthenticator
  • func Env(prefix string, code CodeAuthenticator) UserAuthenticator
  • func Test(randReader io.Reader, dc int) UserAuthenticator
  • func TestUser(phone string, dc int) UserAuthenticator
• type UserInfo

Variables

var ErrPasswordAuthNeeded = errors.New("2FA required")

ErrPasswordAuthNeeded means that 2FA auth is required.

Call Client.Password to provide 2FA password.

var ErrPasswordInvalid = errors.New("invalid password")

ErrPasswordInvalid means that password provided to Password is invalid.

Note that telegram does not trim whitespace characters by default, check that provided password is expected and clean whitespaces if needed. You can use strings.TrimSpace(password) for this.

var ErrPasswordNotProvided = errors.New("password requested but not provided")

ErrPasswordNotProvided means that password requested by Telegram, but not provided by user.

Functions

func IsKeyUnregistered

func IsKeyUnregistered(err error) bool

IsKeyUnregistered reports whether err is AUTH_KEY_UNREGISTERED error.

Deprecated: use IsUnauthorized.

func IsUnauthorized

func IsUnauthorized(err error) bool

IsUnauthorized reports whether err is 401 UNAUTHORIZED.

https://core.telegram.org/api/errors#401-unauthorized

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client implements Telegram authentication.

func NewClient

func NewClient(
	api *tg.Client,
	rand io.Reader,
	appID int,
	appHash string,
) *Client

NewClient initializes and returns Telegram authentication client.

func (*Client) AcceptTOS

func (c *Client) AcceptTOS(ctx context.Context, id tg.DataJSON) error

AcceptTOS accepts version of Terms Of Service.

func (*Client) Bot

func (c *Client) Bot(ctx context.Context, token string) (*tg.AuthAuthorization, error)

Bot performs bot authentication request.

func (*Client) IfNecessary

func (c *Client) IfNecessary(ctx context.Context, flow Flow) error

IfNecessary runs given auth flow if current session is not authorized.

func (*Client) Password

func (c *Client) Password(ctx context.Context, password string) (*tg.AuthAuthorization, error)

Password performs login via secure remote password (aka 2FA).

Method can be called after SignIn to provide password if requested.

func (*Client) SendCode

func (c *Client) SendCode(ctx context.Context, phone string, options SendCodeOptions) (*tg.AuthSentCode, error)

SendCode requests code for provided phone number, returning code hash and error if any. Use AuthFlow to reduce boilerplate.

This method should be called first in user authentication flow.

func (*Client) SignIn

func (c *Client) SignIn(ctx context.Context, phone, code, codeHash string) (*tg.AuthAuthorization, error)

SignIn performs sign in with provided user phone, code and code hash.

If ErrPasswordAuthNeeded is returned, call Password to provide 2FA password.

To obtain codeHash, use SendCode.

func (*Client) SignUp

func (c *Client) SignUp(ctx context.Context, s SignUp) (*tg.AuthAuthorization, error)

SignUp registers a validated phone number in the system.

To obtain codeHash, use SendCode. Use AuthFlow helper to handle authentication flow.

func (*Client) Status

func (c *Client) Status(ctx context.Context) (*Status, error)

Status gets authorization status of client.

func (*Client) Test

func (c *Client) Test(ctx context.Context, dc int) error

Test creates and runs auth flow using Test authenticator if current session is not authorized.

func (*Client) TestUser

func (c *Client) TestUser(ctx context.Context, phone string, dc int) error

TestUser creates and runs auth flow using TestUser authenticator if current session is not authorized.

type CodeAuthenticator

type CodeAuthenticator interface {
	Code(ctx context.Context, sentCode *tg.AuthSentCode) (string, error)
}

CodeAuthenticator asks user for received authentication code.

type CodeAuthenticatorFunc

type CodeAuthenticatorFunc func(ctx context.Context, sentCode *tg.AuthSentCode) (string, error)

CodeAuthenticatorFunc is functional wrapper for CodeAuthenticator.

func (CodeAuthenticatorFunc) Code

func (c CodeAuthenticatorFunc) Code(ctx context.Context, sentCode *tg.AuthSentCode) (string, error)

Code implements CodeAuthenticator interface.

type Flow

type Flow struct {
	Auth    UserAuthenticator
	Options SendCodeOptions
}

Flow simplifies boilerplate for authentication flow.

func NewFlow

func NewFlow(auth UserAuthenticator, opt SendCodeOptions) Flow

NewFlow initializes new authentication flow.

func (Flow) Run

func (f Flow) Run(ctx context.Context, client FlowClient) error

Run starts authentication flow on client.

type FlowClient

type FlowClient interface {
	SignIn(ctx context.Context, phone, code, codeHash string) (*tg.AuthAuthorization, error)
	SendCode(ctx context.Context, phone string, options SendCodeOptions) (*tg.AuthSentCode, error)
	Password(ctx context.Context, password string) (*tg.AuthAuthorization, error)
	SignUp(ctx context.Context, s SignUp) (*tg.AuthAuthorization, error)
}

FlowClient abstracts telegram client for Flow.

type SendCodeOptions

type SendCodeOptions struct {
	// AllowFlashCall allows phone verification via phone calls.
	AllowFlashCall bool
	// Pass true if the phone number is used on the current device.
	// Ignored if AllowFlashCall is not set.
	CurrentNumber bool
	// If a token that will be included in eventually sent SMSs is required:
	// required in newer versions of android, to use the android SMS receiver APIs.
	AllowAppHash bool
}

SendCodeOptions defines how to send auth code to user.

type SignUp

type SignUp struct {
	PhoneNumber   string
	PhoneCodeHash string
	FirstName     string
	LastName      string
}

SignUp wraps parameters for SignUp.

type SignUpRequired

type SignUpRequired struct {
	TermsOfService tg.HelpTermsOfService
}

SignUpRequired means that log in failed because corresponding account does not exist, so sign up is required.

func (*SignUpRequired) Error

func (s *SignUpRequired) Error() string

func (*SignUpRequired) Is

func (s *SignUpRequired) Is(err error) bool

Is returns true if err is SignUpRequired.

type Status

type Status struct {
	// Authorized is true if client is authorized.
	Authorized bool
	// User is current User object.
	User *tg.User
}

Status represents authorization status.

type UserAuthenticator

type UserAuthenticator interface {
	Phone(ctx context.Context) (string, error)
	Password(ctx context.Context) (string, error)
	AcceptTermsOfService(ctx context.Context, tos tg.HelpTermsOfService) error
	SignUp(ctx context.Context) (UserInfo, error)
	CodeAuthenticator
}

UserAuthenticator asks user for phone, password and received authentication code.

func CodeOnly

func CodeOnly(phone string, code CodeAuthenticator) UserAuthenticator

CodeOnly creates UserAuthenticator with constant phone and no password.

func Constant

func Constant(phone, password string, code CodeAuthenticator) UserAuthenticator

Constant creates UserAuthenticator with constant phone and password.

func Env

func Env(prefix string, code CodeAuthenticator) UserAuthenticator

Env creates UserAuthenticator which gets phone and password from environment variables.

func Test

func Test(randReader io.Reader, dc int) UserAuthenticator

Test returns UserAuthenticator that authenticates via testing credentials.

Can be used only with testing server. Will perform sign up if test user is not registered.

func TestUser

func TestUser(phone string, dc int) UserAuthenticator

TestUser returns UserAuthenticator that authenticates via testing credentials. Uses given phone to sign in/sign up.

Can be used only with testing server. Will perform sign up if test user is not registered.

type UserInfo

type UserInfo struct {
	FirstName string
	LastName  string
}

UserInfo represents user info required for sign up.