Documentation
¶
Overview ¶
Package auth provides a headless, event-driven MTProto authentication state machine.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInputTimeout indicates that the user failed to provide the required input within the specified deadline. ErrInputTimeout = errors.New("auth: headless input timeout exceeded or context canceled") // ErrMaxRetriesPhoneCode indicates that the flow was aborted after too many invalid OTP attempts. ErrMaxRetriesPhoneCode = errors.New("auth: max retries exceeded for invalid phone code") // ErrMaxRetriesPassword indicates that the flow was aborted after too many invalid 2FA password attempts. ErrMaxRetriesPassword = errors.New("auth: max retries exceeded for invalid password") // ErrTOSDeclined indicates that the Telegram Terms of Service were rejected by the user. ErrTOSDeclined = errors.New("auth: user declined terms of service") // ErrSignUpInfoMissing indicates that the mandatory registration parameters (like first_name) were omitted. ErrSignUpInfoMissing = errors.New("auth: mandatory sign-up info (first_name) not provided") )
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action struct {
// SessionID must exactly match the UUIDv4 provided by the Event.
SessionID string `json:"session_id"`
// Value represents the raw input string (Phone, Code, or Password).
Value string `json:"value,omitempty"`
// SignUp holds user details if answering EventTypeNeedSignUp.
SignUp *SignUpInfo `json:"sign_up,omitempty"`
// AcceptTOS specifies whether the user agreed to the Terms of Service.
AcceptTOS bool `json:"accept_tos,omitempty"`
}
Action represents the user's input submitted from the external client (e.g., Web Panel) back to the FSM.
type Event ¶
type Event struct {
// SessionID is the UUIDv4 unique identifier for this authentication flow.
SessionID string `json:"session_id"`
// Type represents the current FSM state demanding user action.
Type EventType `json:"type"`
// Message provides optional context (e.g., specific error description from MTProto).
Message string `json:"message,omitempty"`
// CodeLength specifies the expected length of the OTP code, if applicable.
CodeLength int `json:"code_length,omitempty"`
// Attempt holds the current retry attempt count (e.g., 1 out of 3).
Attempt int `json:"attempt,omitempty"`
// TOS holds the Terms of Service information if Type == EventTypeNeedTOS.
TOS *TOSInfo `json:"tos,omitempty"`
}
Event represents a signal dispatched from the TGBox FSM to the external client (e.g., Web Panel).
type EventType ¶
type EventType string
EventType categorizes the specific state of the authentication state machine.
const ( // EventTypeNeedPhone indicates the FSM is waiting for a phone number. EventTypeNeedPhone EventType = "NEED_PHONE" // EventTypeNeedCode indicates the FSM is waiting for the OTP code. EventTypeNeedCode EventType = "NEED_CODE" // EventTypeInvalidCode indicates the previously provided code was invalid. // The FSM is waiting for the user to try again (up to max retries). EventTypeInvalidCode EventType = "INVALID_CODE" // EventTypeNeedPassword indicates 2FA is enabled and FSM requires a password. EventTypeNeedPassword EventType = "NEED_PASSWORD" // EventTypeInvalidPassword indicates the 2FA password was wrong. EventTypeInvalidPassword EventType = "INVALID_PASSWORD" // EventTypeNeedSignUp indicates the phone is not registered yet. FSM requires user's name. EventTypeNeedSignUp EventType = "NEED_SIGN_UP" // EventTypeNeedTOS indicates the user must accept Telegram's Terms of Service. EventTypeNeedTOS EventType = "NEED_TOS" // EventTypeSuccess signals that the MTProto session is now successfully authorized. EventTypeSuccess EventType = "AUTH_SUCCESS" // EventTypeError signals a fatal authentication error (e.g., banned number, too many retries). EventTypeError EventType = "AUTH_ERROR" )
type FSMOption ¶
type FSMOption func(*HeadlessFSM)
FSMOption is a functional configuration option for HeadlessFSM.
func WithMaxRetries ¶
WithMaxRetries overrides the default maximum number of OTP/password retry attempts.
func WithTimeout ¶
WithTimeout overrides the default deadline for each interactive input request.
type HeadlessFSM ¶
type HeadlessFSM struct {
// contains filtered or unexported fields
}
HeadlessFSM coordinates the MTProto authentication lifecycle without any CLI interactions. It communicates with external systems (like Web Panels) via strictly typed channels.
func NewHeadlessFSM ¶
func NewHeadlessFSM(sessionID string, events chan<- Event, actions <-chan Action, opts ...FSMOption) *HeadlessFSM
NewHeadlessFSM constructs a new headless state machine for a specific authentication session. Use WithTimeout and WithMaxRetries to override defaults.
func (*HeadlessFSM) Authenticate ¶
func (f *HeadlessFSM) Authenticate(ctx context.Context, client *auth.Client, phone string) (err error)
Authenticate drives the precise authentication flow, managing MTProto calls directly to allow local retry loops.
type SignUpInfo ¶
type SignUpInfo struct {
FirstName string `json:"first_name"`
LastName string `json:"last_name,omitempty"`
}
SignUpInfo contains mandatory fields required to register a brand new Telegram account.
func (*SignUpInfo) ExtractUserInfo ¶
func (s *SignUpInfo) ExtractUserInfo() auth.UserInfo
ExtractUserInfo safely transforms our module's SignUpInfo into the structure expected by gotd.
Source Files