auth

Documentation

Overview

Package auth provides OAuth2 authentication for email providers.

Index

• Variables
• func BuildXOAuth2String(email, token string) []byte
• func DefaultTokenDir() (string, error)
• func DeviceCodeAuth(ctx context.Context, oauthCfg *oauth2.Config, deviceAuthURL string) (*oauth2.Token, error)
• func NewTokenSource(store *TokenStore, accountID string, oauthCfg *oauth2.Config) (oauth2.TokenSource, error)
• type Provider
  • func DetectOAuthProvider(email string) *Provider
  • func OAuthConfig(account *config.Account) (*oauth2.Config, *Provider, error)
• type TokenStore
  • func NewTokenStore(baseDir string) (*TokenStore, error)
  • func (s *TokenStore) Delete(accountID string) error
  • func (s *TokenStore) Load(accountID string) (*oauth2.Token, error)
  • func (s *TokenStore) Path(accountID string) string
  • func (s *TokenStore) Save(accountID string, token *oauth2.Token) error
• type XOAuth2Client
  • func NewXOAuth2Client(email, accessToken string) *XOAuth2Client
  • func (c *XOAuth2Client) Next(challenge []byte) ([]byte, error)
  • func (c *XOAuth2Client) Start() (string, []byte, error)

Variables

var (
	ErrDeviceCodeExpired = errors.New("device code expired — please re-run authorization")
	ErrDeviceCodeDenied  = errors.New("authorization denied by user")
	ErrProviderUnknown   = errors.New("no OAuth2 provider for email domain")
	ErrDeviceCodeHTTP    = errors.New("device code request failed")
	ErrTokenEndpoint     = errors.New("token endpoint error")
)

Sentinel errors for device code flow and token operations.

var ErrTokenNotFound = errors.New("oauth2 token not found (run device code auth first)")

ErrTokenNotFound indicates no token file exists for the account.

var ErrXOAuth2Failed = errors.New("XOAUTH2 authentication failed")

ErrXOAuth2Failed indicates the server rejected XOAUTH2 authentication.

var Providers = map[string]Provider{
	"gmail": {
		Name:          "Gmail",
		AuthURL:       "https://accounts.google.com/o/oauth2/auth",
		TokenURL:      "https://oauth2.googleapis.com/token",
		DeviceAuthURL: "https://oauth2.googleapis.com/device/code",
		Scopes:        []string{"https://mail.google.com/"},
	},
	"outlook": {
		Name:          "Outlook",
		AuthURL:       "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
		TokenURL:      "https://login.microsoftonline.com/common/oauth2/v2.0/token",
		DeviceAuthURL: "https://login.microsoftonline.com/common/oauth2/v2.0/devicecode",
		Scopes: []string{
			"https://outlook.office365.com/IMAP.AccessAsUser.All",
			"https://outlook.office365.com/SMTP.Send",
			"offline_access",
		},
	},
}

Providers is the registry of known OAuth2 email providers.

Functions

func BuildXOAuth2String

func BuildXOAuth2String(email, token string) []byte

BuildXOAuth2String builds the XOAUTH2 initial response per RFC 7628.

func DefaultTokenDir

func DefaultTokenDir() (string, error)

DefaultTokenDir returns the default token storage directory.

func DeviceCodeAuth

func DeviceCodeAuth(
	ctx context.Context,
	oauthCfg *oauth2.Config,
	deviceAuthURL string,
) (*oauth2.Token, error)

DeviceCodeAuth runs the OAuth2 device authorization grant (RFC 8628).

func NewTokenSource

func NewTokenSource(
	store *TokenStore,
	accountID string,
	oauthCfg *oauth2.Config,
) (oauth2.TokenSource, error)

NewTokenSource creates a token source that auto-refreshes and persists tokens.

Types

type Provider

type Provider struct {
	Name          string
	AuthURL       string
	TokenURL      string
	DeviceAuthURL string
	Scopes        []string
}

Provider holds OAuth2 configuration for an email provider.

func DetectOAuthProvider

func DetectOAuthProvider(email string) *Provider

DetectOAuthProvider returns the OAuth2 provider for the given email address. Returns nil if the domain is not recognized.

func OAuthConfig

func OAuthConfig(account *config.Account) (*oauth2.Config, *Provider, error)

OAuthConfig builds an oauth2.Config from an account and its detected provider.

type TokenStore

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

TokenStore persists OAuth2 tokens as JSON files.

func NewTokenStore

func NewTokenStore(baseDir string) (*TokenStore, error)

NewTokenStore creates a TokenStore, ensuring the base directory exists.

func (*TokenStore) Delete

func (s *TokenStore) Delete(accountID string) error

Delete removes the token file for the given account.

func (*TokenStore) Load

func (s *TokenStore) Load(accountID string) (*oauth2.Token, error)

Load reads a token from disk for the given account.

func (*TokenStore) Path

func (s *TokenStore) Path(accountID string) string

Path returns the token file path for the given account.

func (*TokenStore) Save

func (s *TokenStore) Save(accountID string, token *oauth2.Token) error

Save persists a token to disk using atomic write (temp file + rename).

type XOAuth2Client

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

XOAuth2Client implements the go-sasl Client interface for XOAUTH2 authentication. The XOAUTH2 mechanism sends the user's email and OAuth2 bearer token in a single initial response.

func NewXOAuth2Client

func NewXOAuth2Client(email, accessToken string) *XOAuth2Client

NewXOAuth2Client creates a new XOAUTH2 SASL client.

func (*XOAuth2Client) Next

func (c *XOAuth2Client) Next(challenge []byte) ([]byte, error)

Next handles server challenges. In XOAUTH2, any server challenge indicates authentication failure. Returns an empty response (required by protocol) and the challenge as an error.

func (*XOAuth2Client) Start

func (c *XOAuth2Client) Start() (string, []byte, error)

Start returns the XOAUTH2 mechanism name and initial response.