auth

Documentation

Overview

Package auth provides authentication functionality for GitHubby

Index

• Constants
• func FormatTokenSource(source TokenSource) string
• func GetDeviceFlowInstructions(code *device.CodeResponse, hostname string) string
• func MaskToken(token string) string
• func OpenBrowser(url string) error
• func RequestDeviceCode(ctx context.Context) (*device.CodeResponse, error)
• type AuthenticatedUser
  • func ValidateToken(ctx context.Context, token string, hostname string) (*AuthenticatedUser, error)
• type DeviceFlowOptions
  • func DefaultDeviceFlowOptions() *DeviceFlowOptions
• type DeviceFlowResult
  • func PollForToken(ctx context.Context, code *device.CodeResponse) (*DeviceFlowResult, error)
  • func RunDeviceFlow(ctx context.Context, opts *DeviceFlowOptions) (*DeviceFlowResult, error)
• type Storage
  • func NewStorage() *Storage
  • func NewStorageWithConfig(configPath string, useKeychain bool) *Storage
  • func (s *Storage) DeleteToken(hostname string) error
  • func (s *Storage) GetStorageLocation() string
  • func (s *Storage) GetToken(hostname string) (string, TokenSource, error)
  • func (s *Storage) IsKeychainAvailable() bool
  • func (s *Storage) SetToken(hostname, token string) error
• type TokenResult
  • func GetToken(ctx context.Context, explicitToken string, hostname string) (*TokenResult, error)
• type TokenSource

Constants

const (
	// DefaultHostname is the default GitHub hostname
	DefaultHostname = "github.com"

	// EnvGitHubToken is the environment variable for GitHub token
	EnvGitHubToken = "GITHUB_TOKEN"
)

const (
	// GitHubOAuthClientID is the OAuth App client ID for GitHubby
	// This is intentionally public - device flow doesn't require a secret
	// To register your own OAuth App: https://github.com/settings/developers
	GitHubOAuthClientID = "Ov23liwoBdsJgs7M7kLS"

	// DefaultScopes are the OAuth scopes requested during authentication
	// - repo: Full control of private repositories (needed for sync)
	// - read:org: Read org membership (needed for org sync)
	DefaultScopes = "repo read:org"
)

const (
	// KeyringServiceName is the service name used in the system keychain
	KeyringServiceName = "githubby"

	// ConfigFileName is the name of the config file
	ConfigFileName = ".githubby.yaml"
)

Functions

func FormatTokenSource

func FormatTokenSource(source TokenSource) string

FormatTokenSource returns a human-readable description of the token source

func GetDeviceFlowInstructions

func GetDeviceFlowInstructions(code *device.CodeResponse, hostname string) string

GetDeviceFlowInstructions returns user-friendly instructions for device flow

func MaskToken

func MaskToken(token string) string

MaskToken returns a masked version of the token for display

func OpenBrowser

func OpenBrowser(url string) error

OpenBrowser opens the default browser to the specified URL

func RequestDeviceCode

func RequestDeviceCode(ctx context.Context) (*device.CodeResponse, error)

RequestDeviceCode requests a device code from GitHub for OAuth This is the first step of the device flow - returns quickly with a code to show user

Types

type AuthenticatedUser

type AuthenticatedUser struct {
	Login     string
	Name      string
	Email     string
	AvatarURL string
}

AuthenticatedUser contains information about the authenticated user

func ValidateToken

func ValidateToken(ctx context.Context, token string, hostname string) (*AuthenticatedUser, error)

ValidateToken checks if a token is valid by making a test API call

type DeviceFlowOptions

type DeviceFlowOptions struct {
	// ClientID is the OAuth App client ID
	ClientID string
	// Scopes are the OAuth scopes to request
	Scopes []string
	// Hostname is the GitHub hostname (for Enterprise)
	Hostname string
	// OnCode is called when the user code is ready
	OnCode func(code *device.CodeResponse)
	// OnPoll is called during polling
	OnPoll func(interval time.Duration)
}

DeviceFlowOptions configures the device flow authentication

func DefaultDeviceFlowOptions

func DefaultDeviceFlowOptions() *DeviceFlowOptions

DefaultDeviceFlowOptions returns options with sensible defaults

type DeviceFlowResult

type DeviceFlowResult struct {
	Token     string
	TokenType string
	Scopes    []string
}

DeviceFlowResult contains the result of a device flow authentication

func PollForToken

func PollForToken(ctx context.Context, code *device.CodeResponse) (*DeviceFlowResult, error)

PollForToken polls GitHub waiting for user to authorize the device code This blocks until the user completes authorization or the code expires

func RunDeviceFlow

func RunDeviceFlow(ctx context.Context, opts *DeviceFlowOptions) (*DeviceFlowResult, error)

RunDeviceFlow performs OAuth device flow authentication

type Storage

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

Storage handles secure token storage

func NewStorage

func NewStorage() *Storage

NewStorage creates a new Storage instance

func NewStorageWithConfig

func NewStorageWithConfig(configPath string, useKeychain bool) *Storage

NewStorageWithConfig creates a Storage instance with a custom config path (for testing)

func (*Storage) DeleteToken

func (s *Storage) DeleteToken(hostname string) error

DeleteToken removes the stored token for a hostname

func (*Storage) GetStorageLocation

func (s *Storage) GetStorageLocation() string

GetStorageLocation returns a description of where tokens are stored

func (*Storage) GetToken

func (s *Storage) GetToken(hostname string) (string, TokenSource, error)

GetToken retrieves the stored token for a hostname

func (*Storage) IsKeychainAvailable

func (s *Storage) IsKeychainAvailable() bool

IsKeychainAvailable returns whether the system keychain is available

func (*Storage) SetToken

func (s *Storage) SetToken(hostname, token string) error

SetToken stores a token for a hostname

type TokenResult

type TokenResult struct {
	Token    string
	Source   TokenSource
	Hostname string
}

TokenResult contains the resolved token and its source

func GetToken

func GetToken(ctx context.Context, explicitToken string, hostname string) (*TokenResult, error)

GetToken resolves the GitHub token using the following priority: 1. Explicit token (from --token flag) 2. GITHUB_TOKEN environment variable 3. Stored token (keychain or config file)

type TokenSource

type TokenSource string

TokenSource represents where the token was obtained from

const (
	TokenSourceFlag     TokenSource = "flag"
	TokenSourceEnv      TokenSource = "environment"
	TokenSourceKeychain TokenSource = "keychain"
	TokenSourceConfig   TokenSource = "config"
	TokenSourceNone     TokenSource = "none"
)