basic

Documentation

Overview

Package basic provides username/password authentication with secure password hashing.

Index

• Constants
• Variables
• func GenerateResetToken() (string, error)
• type Authenticator
  • func NewAuthenticator(cfg Config) (*Authenticator, error)
  • func (a *Authenticator) Authenticate(ctx context.Context, identifier, password string) (*storage.User, error)
  • func (a *Authenticator) AuthenticateWithTOTP(ctx context.Context, identifier, password, totpCode string) (*storage.User, error)
  • func (a *Authenticator) ChangePassword(ctx context.Context, userID, oldPassword, newPassword string) error
  • func (a *Authenticator) CompletePasswordReset(ctx context.Context, token, newPassword string) error
  • func (a *Authenticator) DisableTOTP(ctx context.Context, userID, totpCode string) error
  • func (a *Authenticator) EnableTOTP(ctx context.Context, userID, accountName string) (*totp.Secret, error)
  • func (a *Authenticator) GenerateEmailVerificationToken(ctx context.Context, userID string) (string, error)
  • func (a *Authenticator) GeneratePasswordResetToken(ctx context.Context, emailOrUsername string) (string, error)
  • func (a *Authenticator) IsTOTPEnabled(ctx context.Context, userID string) (bool, error)
  • func (a *Authenticator) RegenerateTOTPBackupCodes(ctx context.Context, userID string) ([]string, error)
  • func (a *Authenticator) Register(ctx context.Context, req RegisterRequest) (*storage.User, error)
  • func (a *Authenticator) ResendEmailVerificationToken(ctx context.Context, emailOrUsername string) (string, error)
  • func (a *Authenticator) ResetPassword(ctx context.Context, userID, newPassword string) error
  • func (a *Authenticator) ValidatePasswordResetToken(ctx context.Context, token string) (string, error)
  • func (a *Authenticator) VerifyEmail(ctx context.Context, token string) error
• type Config
• type PasswordResetToken
• type RegisterRequest

Constants

const (
	// MinPasswordLength is the minimum required password length.
	MinPasswordLength = 8

	// DefaultBcryptCost is the default bcrypt cost factor.
	DefaultBcryptCost = 12

	// DefaultPasswordResetTTL is the default password reset token TTL.
	DefaultPasswordResetTTL = 1 * time.Hour

	// DefaultEmailVerificationTTL is the default email verification token TTL.
	DefaultEmailVerificationTTL = 24 * time.Hour
)

Variables

var (
	// ErrInvalidCredentials is returned when authentication fails.
	ErrInvalidCredentials = errors.New("invalid credentials")

	// ErrUserExists is returned when attempting to register a user that already exists.
	ErrUserExists = errors.New("user already exists")

	// ErrWeakPassword is returned when a password doesn't meet minimum requirements.
	ErrWeakPassword = errors.New("password does not meet minimum requirements")

	// ErrEmailNotVerified is returned when a user attempts to authenticate without verifying their email.
	ErrEmailNotVerified = errors.New("email not verified")

	// ErrInvalidToken is returned when a token is invalid or expired.
	ErrInvalidToken = errors.New("invalid or expired token")
)

Functions

func GenerateResetToken

func GenerateResetToken() (string, error)

GenerateResetToken generates a secure password reset token. This token should be stored temporarily and sent to the user's email.

Types

type Authenticator

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

Authenticator handles basic username/password authentication.

func NewAuthenticator

func NewAuthenticator(cfg Config) (*Authenticator, error)

NewAuthenticator creates a new basic authenticator.

func (*Authenticator) Authenticate

func (a *Authenticator) Authenticate(ctx context.Context, identifier, password string) (*storage.User, error)

Authenticate verifies user credentials and returns the user if valid. The identifier can be either email or username.

func (*Authenticator) AuthenticateWithTOTP

func (a *Authenticator) AuthenticateWithTOTP(ctx context.Context, identifier, password, totpCode string) (*storage.User, error)

AuthenticateWithTOTP authenticates a user with email/username, password, and TOTP code. This is a convenience method that combines password and TOTP authentication.

func (*Authenticator) ChangePassword

func (a *Authenticator) ChangePassword(ctx context.Context, userID, oldPassword, newPassword string) error

ChangePassword changes a user's password.

func (*Authenticator) CompletePasswordReset

func (a *Authenticator) CompletePasswordReset(ctx context.Context, token, newPassword string) error

CompletePasswordReset validates a password reset token and resets the user's password. This is a convenience method that combines token validation and password reset.

func (*Authenticator) DisableTOTP

func (a *Authenticator) DisableTOTP(ctx context.Context, userID, totpCode string) error

DisableTOTP disables TOTP for a user. Requires a valid TOTP code to prevent accidental or malicious disabling.

func (*Authenticator) EnableTOTP

func (a *Authenticator) EnableTOTP(ctx context.Context, userID, accountName string) (*totp.Secret, error)

EnableTOTP enables TOTP for a user and returns the secret and backup codes. This is a convenience wrapper around totp.Manager.GenerateSecret.

func (*Authenticator) GenerateEmailVerificationToken

func (a *Authenticator) GenerateEmailVerificationToken(ctx context.Context, userID string) (string, error)

GenerateEmailVerificationToken generates and stores an email verification token for a user. The token should be sent to the user's email for verification. Returns the generated token which should be included in the verification link.

func (*Authenticator) GeneratePasswordResetToken

func (a *Authenticator) GeneratePasswordResetToken(ctx context.Context, emailOrUsername string) (string, error)

GeneratePasswordResetToken generates and stores a password reset token for a user. The token should be sent to the user's email for verification. Returns the generated token which should be included in the password reset link.

func (*Authenticator) IsTOTPEnabled

func (a *Authenticator) IsTOTPEnabled(ctx context.Context, userID string) (bool, error)

IsTOTPEnabled checks if TOTP is enabled for a user.

func (*Authenticator) RegenerateTOTPBackupCodes

func (a *Authenticator) RegenerateTOTPBackupCodes(ctx context.Context, userID string) ([]string, error)

RegenerateTOTPBackupCodes generates new backup codes for a user.

func (*Authenticator) Register

func (a *Authenticator) Register(ctx context.Context, req RegisterRequest) (*storage.User, error)

Register creates a new user account with the provided credentials.

func (*Authenticator) ResendEmailVerificationToken

func (a *Authenticator) ResendEmailVerificationToken(ctx context.Context, emailOrUsername string) (string, error)

ResendEmailVerificationToken generates a new email verification token for a user. This is useful when the original token has expired or was lost.

func (*Authenticator) ResetPassword

func (a *Authenticator) ResetPassword(ctx context.Context, userID, newPassword string) error

ResetPassword resets a user's password (without requiring old password). This should be used with additional verification (e.g., email token).

func (*Authenticator) ValidatePasswordResetToken

func (a *Authenticator) ValidatePasswordResetToken(ctx context.Context, token string) (string, error)

ValidatePasswordResetToken validates a password reset token and returns the associated user ID.

func (*Authenticator) VerifyEmail

func (a *Authenticator) VerifyEmail(ctx context.Context, token string) error

VerifyEmail verifies a user's email address using a verification token.

type Config

type Config struct {
	UserStore                storage.UserStore
	CredentialStore          storage.CredentialStore
	BcryptCost               int           // Optional: defaults to DefaultBcryptCost
	RequireEmailVerification bool          // Optional: defaults to false
	PasswordResetTTL         time.Duration // Optional: defaults to DefaultPasswordResetTTL
	EmailVerificationTTL     time.Duration // Optional: defaults to DefaultEmailVerificationTTL
	TOTPManager              *totp.Manager // Optional: if provided, enables TOTP support
}

Config configures the basic authenticator.

type PasswordResetToken

type PasswordResetToken struct {
	Token     string
	UserID    string
	ExpiresAt time.Time
}

PasswordResetToken represents a stored password reset token.

type RegisterRequest

type RegisterRequest struct {
	Email    string                 `json:"email"`
	Username string                 `json:"username,omitempty"`
	Password string                 `json:"password"`
	Name     string                 `json:"name,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

RegisterRequest contains user registration information.