auth

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package auth handles authentication and OAuth flows.

Index

Constants

View Source
const (
	// KeyringService is the service name used in the system keychain.
	KeyringService = "xf"

	// KeyringUser is the user/account name used in the system keychain.
	KeyringUser = "oauth-token"
)

Variables

View Source
var (
	ErrStoreUnavailable = errors.New("credential storage unavailable")
	ErrConfigMismatch   = errors.New("authentication configuration mismatch")

	// ErrAuthRequired indicates that authentication is required.
	ErrAuthRequired = errors.New("authentication required")

	// ErrAuthFailed indicates an authentication operation failed.
	ErrAuthFailed = errors.New("authentication failed")

	// ErrAuthExpired indicates the authentication token has expired.
	ErrAuthExpired = errors.New("authentication expired")

	// ErrInvalidInput indicates invalid input to an auth function.
	ErrInvalidInput = errors.New("invalid input")

	// ErrUnsupported indicates an unsupported operation or platform.
	ErrUnsupported = errors.New("unsupported")
)

Functions

func ErrorMessage

func ErrorMessage(err error) string

ErrorMessage removes classification sentinels from user-facing diagnostics.

func OpenBrowser

func OpenBrowser(ctx context.Context, urlStr string) error

OpenBrowser opens a URL in the user's default browser.

Types

type CallbackResult

type CallbackResult struct {
	Code  string
	State string
	Error string
}

CallbackResult holds the result of the OAuth callback.

type CallbackServer

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

CallbackServer handles the OAuth redirect callback from the authorization server.

func NewCallbackServer

func NewCallbackServer(ctx context.Context, path string) (*CallbackServer, error)

NewCallbackServer creates a new callback server.

func (*CallbackServer) RedirectURI

func (cs *CallbackServer) RedirectURI() string

RedirectURI returns the callback server's redirect URI.

func (*CallbackServer) Shutdown

func (cs *CallbackServer) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the callback server.

func (*CallbackServer) Start

func (cs *CallbackServer) Start()

Start begins listening for the OAuth callback.

func (*CallbackServer) WaitForCallback

func (cs *CallbackServer) WaitForCallback(ctx context.Context) (*CallbackResult, error)

WaitForCallback waits for the OAuth callback result.

type FileStore

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

FileStore stores OAuth credentials separately from ordinary configuration.

func (*FileStore) DeleteToken

func (s *FileStore) DeleteToken() error

func (*FileStore) LoadToken

func (s *FileStore) LoadToken() (*Token, error)

func (*FileStore) LoadTokenForLogout

func (s *FileStore) LoadTokenForLogout() (*Token, error)

func (*FileStore) Path

func (s *FileStore) Path() string

func (*FileStore) PrepareLogin

func (s *FileStore) PrepareLogin() error

PrepareLogin rejects known storage failures before browser authentication. The temporary probe does not replace existing credentials.

func (*FileStore) SaveToken

func (s *FileStore) SaveToken(token *Token) error

func (*FileStore) Source

func (s *FileStore) Source() string

type IntrospectResponse

type IntrospectResponse struct {
	Active   bool   `json:"active"`
	Username string `json:"username,omitempty"`
	Scope    string `json:"scope,omitempty"`
	Exp      int64  `json:"exp,omitempty"`
	Iat      int64  `json:"iat,omitempty"`
}

IntrospectResponse represents the token introspection response.

type Keychain

type Keychain struct{}

Keychain manages secure token storage in the system keychain.

func NewKeychain

func NewKeychain() *Keychain

NewKeychain creates a new Keychain instance.

func (*Keychain) DeleteToken

func (k *Keychain) DeleteToken() error

DeleteToken removes the token from the keychain.

func (*Keychain) IsAvailable

func (k *Keychain) IsAvailable() bool

IsAvailable checks if the system keychain is accessible.

func (*Keychain) LoadToken

func (k *Keychain) LoadToken() (*Token, error)

LoadToken retrieves the stored token from the keychain.

func (*Keychain) LoadTokenForLogout

func (k *Keychain) LoadTokenForLogout() (*Token, error)

func (*Keychain) PrepareLogin

func (k *Keychain) PrepareLogin() error

func (*Keychain) SaveToken

func (k *Keychain) SaveToken(token *Token) error

SaveToken stores a token in the keychain.

func (*Keychain) Source

func (k *Keychain) Source() string

type OAuthClient

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

OAuthClient handles the OAuth authentication flow.

func NewOAuthClient

func NewOAuthClient(cfg *config.OAuthConfig) *OAuthClient

NewOAuthClient creates a new OAuth client.

func (*OAuthClient) AuthorizationURL

func (c *OAuthClient) AuthorizationURL(pkce *PKCEParams, redirectURI string) string

AuthorizationURL generates the OAuth authorization URL.

func (*OAuthClient) ExchangeCode

func (c *OAuthClient) ExchangeCode(ctx context.Context, code string, pkce *PKCEParams, redirectURI string) (*Token, error)

ExchangeCode exchanges an authorization code for a token.

func (*OAuthClient) IntrospectToken

func (c *OAuthClient) IntrospectToken(ctx context.Context, accessToken string) (*IntrospectResponse, error)

IntrospectToken checks the validity and metadata of a token.

func (*OAuthClient) RefreshToken

func (c *OAuthClient) RefreshToken(ctx context.Context, refreshToken string) (*Token, error)

RefreshToken refreshes an expired access token.

func (*OAuthClient) RevokeToken

func (c *OAuthClient) RevokeToken(ctx context.Context, token string) error

RevokeToken revokes an access or refresh token.

type PKCEParams

type PKCEParams struct {
	// CodeVerifier is the random string used to generate the challenge.
	CodeVerifier string

	// CodeChallenge is the S256 hash of the verifier.
	CodeChallenge string

	// CodeChallengeMethod is always "S256".
	CodeChallengeMethod string

	// State is a random string to prevent CSRF attacks.
	State string
}

PKCEParams contains the PKCE parameters for an OAuth flow.

func GeneratePKCE

func GeneratePKCE() (*PKCEParams, error)

GeneratePKCE generates new PKCE parameters for an OAuth flow.

type Store

type Store interface {
	LoadToken() (*Token, error)
	SaveToken(*Token) error
	DeleteToken() error
	Source() string
}

Store is the selected credential source. Environment credentials are read-only.

func NewStore

func NewStore() (Store, error)

NewStore resolves environment credentials before the configured persistent store.

type Token

type Token struct {
	// External tokens have no local expiry or refresh metadata.
	External     bool      `json:"-"`
	AccessToken  string    `json:"access_token"`
	RefreshToken string    `json:"refresh_token,omitempty"`
	TokenType    string    `json:"token_type"`
	ExpiresAt    time.Time `json:"expires_at"`
	Scope        string    `json:"scope,omitempty"`
	IssuedAt     time.Time `json:"issued_at"`
	BaseURL      string    `json:"base_url"`
}

Token represents an OAuth token with expiry information.

func RequireAuthFrom

func RequireAuthFrom(store Store) (*Token, error)

RequireAuthFrom loads credentials and checks their configured destination.

func (*Token) IsExpired

func (t *Token) IsExpired() bool

IsExpired checks if the token has expired, accounting for clock skew.

func (*Token) IsExpiringSoon

func (t *Token) IsExpiringSoon(within time.Duration) bool

IsExpiringSoon checks if the token will expire within the given duration.

func (*Token) TimeUntilExpiry

func (t *Token) TimeUntilExpiry() time.Duration

TimeUntilExpiry returns the duration until the token expires.

type TokenResponse

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	TokenType    string `json:"token_type"`
	ExpiresIn    int    `json:"expires_in"`
	RefreshToken string `json:"refresh_token,omitempty"`
	Scope        string `json:"scope,omitempty"`
}

TokenResponse represents the OAuth token response.

type WritableStore

type WritableStore interface {
	Store
	PrepareLogin() error
	LoadTokenForLogout() (*Token, error)
}

WritableStore supports the persistent authentication lifecycle. Logout may read an insecure regular file solely to revoke its credentials.

func NewWritableStore

func NewWritableStore() (WritableStore, error)

NewWritableStore selects persistent storage without relying on display labels.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL