cliauth

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Jun 21, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyAuthenticatorConfigOverrides

func ApplyAuthenticatorConfigOverrides(auth Authenticator, overrides AuthenticatorConfig) error

ApplyAuthenticatorConfigOverrides reads the authenticator's current runtime config, merges the provided overrides, and reapplies the result.

func ListAuthenticatorTypes

func ListAuthenticatorTypes() []string

ListAuthenticatorTypes returns the types of all registered Authenticator factories.

func RegisterAuthenticatorFactory

func RegisterAuthenticatorFactory(cliauthType string, factory AuthenticatorFactory)

RegisterAuthenticatorFactory registers an Authenticator factory by CLI Authenticator Type.

Types

type Authenticator

type Authenticator interface {
	// GetConfig returns the runtime configuration currently applied to this authenticator instance.
	GetConfig() AuthenticatorConfig
	// SetConfig applies runtime configuration to this authenticator instance.
	SetConfig(cfg AuthenticatorConfig) error
	// Login initiates the interactive CLI login flow and returns a new credential on success.
	Login(ctx context.Context, req LoginRequest, reporter LoginStatusReporter) (*credentialmgr.Credential, error)
	// Refresh attempts to refresh the given credential before it expires.
	// Returns nil to indicate no refresh is needed; returns an updated credential on success.
	Refresh(ctx context.Context, cred *credentialmgr.Credential) (*credentialmgr.Credential, error)
	// RefreshLeadTime returns how far in advance of token expiry to attempt a refresh.
	// Returning nil disables provider-level background pre-refresh scheduling.
	RefreshLeadTime() *time.Duration
}

Authenticator handles the CLI login flow for a specific provider. Each concrete implementation covers one CLI tool (e.g. Codex, Claude CLI).

func NewAuthenticator

func NewAuthenticator(cliname string) (Authenticator, error)

NewAuthenticator creates an Authenticator by CLI name using registered factories.

type AuthenticatorConfig

type AuthenticatorConfig struct {
	CallbackPort     int           `json:"callback_port,omitempty"`
	NoBrowser        bool          `json:"no_browser,omitempty"`
	DeviceFlow       bool          `json:"device_flow,omitempty"`
	TransportProfile string        `json:"transport_profile,omitempty"`
	Network          NetworkConfig `json:"network"`
}

AuthenticatorConfig describes the runtime configuration supported by built-in CLI authenticators.

func (*AuthenticatorConfig) ApplyOverrides

func (c *AuthenticatorConfig) ApplyOverrides(overrides AuthenticatorConfig)

ApplyOverrides merges non-zero override values into the receiver while preserving any existing runtime defaults already present on the config.

func (*AuthenticatorConfig) Defaults

func (c *AuthenticatorConfig) Defaults()

Defaults fills in zero values with sensible defaults.

type AuthenticatorFactory

type AuthenticatorFactory func() (Authenticator, error)

AuthenticatorFactory creates an Authenticator instance.

type AuthenticatorState

type AuthenticatorState struct {
	Name    string              `json:"name"`
	Enabled bool                `json:"enabled"`
	Config  AuthenticatorConfig `json:"config"`
}

AuthenticatorState describes a supported or enabled Authenticator.

type AutoRefresher

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

AutoRefresher manages credential lifecycle: loading, registration, update, and automatic background refresh scheduling.

func NewAutoRefresher

func NewAutoRefresher(credMgr CredentialManager, manager *Manager) *AutoRefresher

NewAutoRefresher constructs an AutoRefresher. manager may be nil when authenticator-backed refresh is not needed.

func (*AutoRefresher) IsRunning

func (r *AutoRefresher) IsRunning() bool

IsRunning reports whether the background refresh loop is currently active.

func (*AutoRefresher) Load

func (r *AutoRefresher) Load(ctx context.Context) error

Load reads all CLI-auth credentials from the store and registers them in memory. Call once during startup.

func (*AutoRefresher) RegisterLoginCredential

func (r *AutoRefresher) RegisterLoginCredential(ctx context.Context, cred *CLIAuthCredential) error

RegisterLoginCredential adds a new credential obtained from a CLI login flow.

func (*AutoRefresher) Start

func (r *AutoRefresher) Start(ctx context.Context)

Start starts the background goroutines that periodically refresh expiring credentials. Call Stop to shut it down.

func (*AutoRefresher) Stop

func (r *AutoRefresher) Stop()

Stop stops the background refresh goroutines.

type CLIAuthCredential

type CLIAuthCredential struct {
	credentialmgr.Credential
	// Status is the lifecycle status managed by the Manager.
	// Use StatusDisabled to mark a credential as intentionally disabled.
	Status Status `json:"status"`
	// StatusMessage holds a short description for the current status.
	StatusMessage string `json:"status_message,omitempty"`
	// LastRefreshedAt records the last successful source-level refresh.
	LastRefreshedAt time.Time `json:"last_refreshed_at,omitempty"`
	// NextRefreshAfter is the earliest time a source-level refresh should retrigger.
	NextRefreshAfter time.Time `json:"next_refresh_after,omitempty"`
}

CLIAuthCredential encapsulates the runtime state and metadata for a single upstream credential.

func NewCLIAuthCredential

func NewCLIAuthCredential(cred *credentialmgr.Credential) *CLIAuthCredential

NewCLIAuthCredential wraps a shared credential with CLI-auth runtime state.

func (*CLIAuthCredential) Clone

Clone shallow copies the CLIAuthCredential, duplicating maps to avoid accidental mutation.

func (*CLIAuthCredential) IsDisabled

func (c *CLIAuthCredential) IsDisabled() bool

IsDisabled reports whether the credential has been intentionally disabled.

type CredentialManager

type CredentialManager interface {
	GetCredential(id string) *credentialmgr.Credential
	ListCredentials(filter credentialmgr.Filter) []*credentialmgr.Credential
	RegisterCredential(ctx context.Context, cred *credentialmgr.Credential) error
	UpdateCredential(ctx context.Context, cred *credentialmgr.Credential) error
	DeregisterCredential(ctx context.Context, id string) error
}

CredentialManager captures the credential store/snapshot operations cliauth needs from the shared credential manager.

func WrapSharedCredentialManager

func WrapSharedCredentialManager(manager *credentialmgr.Manager) CredentialManager

WrapSharedCredentialManager adapts the shared credential manager to the cliauth-focused CredentialManager interface.

type HeapItem

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

type LoginRequest

type LoginRequest struct {
	ProviderID string
	Scope      string
}

LoginRequest describes the provider binding metadata that the admin layer resolved before invoking a runtime authenticator.

type LoginStatusReporter

type LoginStatusReporter interface {
	UpdateLoginStatus(update LoginStatusUpdate)
}

LoginStatusReporter receives login progress updates suitable for surfacing via the admin API.

type LoginStatusUpdate

type LoginStatusUpdate struct {
	Phase           string `json:"phase,omitempty"`
	Message         string `json:"message,omitempty"`
	VerificationURL string `json:"verification_url,omitempty"`
	UserCode        string `json:"user_code,omitempty"`
}

LoginStatusUpdate describes a user-visible state transition during an interactive login flow.

type Manager

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

Manager orchestrates authenticator lifecycle: registration, enable/disable, and selection.

func NewManager

func NewManager() *Manager

NewManager constructs a CLI Authenticators Manager.

func (*Manager) DisableAuthenticator

func (m *Manager) DisableAuthenticator(cliname string) error

DisableAuthenticator deregisters an Authenticator by CLI name.

func (*Manager) EnableAuthenticator

func (m *Manager) EnableAuthenticator(cliname string, cfg AuthenticatorConfig) (AuthenticatorState, error)

EnableAuthenticator creates and registers a runtime Authenticator by CLI name. The provided config is applied to the runtime authenticator on top of the factory defaults before registration.

func (*Manager) GetAuthenticator

func (m *Manager) GetAuthenticator(cliname string) (Authenticator, bool)

GetAuthenticator returns the Authenticator registered for the given CLI name.

func (*Manager) GetAuthenticatorState

func (m *Manager) GetAuthenticatorState(cliname string) (AuthenticatorState, bool)

GetAuthenticatorState returns lifecycle metadata for the given CLI name. If the authenticator is not enabled but its factory is registered, a disabled state with the factory defaults is returned.

func (*Manager) ListAuthenticatorStates

func (m *Manager) ListAuthenticatorStates() []AuthenticatorState

ListAuthenticatorStates returns all supported authenticators, marking the ones that are currently enabled with their runtime metadata.

func (*Manager) RegisterAuthenticator

func (m *Manager) RegisterAuthenticator(cliname string, auth Authenticator)

RegisterAuthenticator registers an Authenticator for a CLI name.

func (*Manager) SetCredentialManager

func (m *Manager) SetCredentialManager(credentialMgr *credentialmgr.Manager)

type MinHeap

type MinHeap []*HeapItem

func (MinHeap) Len

func (h MinHeap) Len() int

func (MinHeap) Less

func (h MinHeap) Less(i, j int) bool

func (*MinHeap) Pop

func (h *MinHeap) Pop() any

func (*MinHeap) Push

func (h *MinHeap) Push(x any)

func (MinHeap) Swap

func (h MinHeap) Swap(i, j int)

type NetworkConfig

type NetworkConfig = httpclient.NetworkConfig

NetworkConfig re-exports the shared HTTP network config type for authenticator configs.

type RefreshJobDispatcher

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

func (*RefreshJobDispatcher) DispatchLoop

func (d *RefreshJobDispatcher) DispatchLoop(ctx context.Context)

func (*RefreshJobDispatcher) Enqueue

func (d *RefreshJobDispatcher) Enqueue(id string)

func (*RefreshJobDispatcher) Reset

func (d *RefreshJobDispatcher) Reset(ids []string, now time.Time)

type Status

type Status string

Status represents the lifecycle state of a CLIAuthCredential entry.

const (
	// StatusUnknown means the credential state could not be determined.
	StatusUnknown Status = "unknown"
	// StatusActive indicates the credential is valid and ready for use.
	StatusActive Status = "active"
	// StatusPending indicates the credential is waiting for an external action.
	StatusPending Status = "pending"
	// StatusRefreshing indicates the credential is undergoing a refresh flow.
	StatusRefreshing Status = "refreshing"
	// StatusError indicates the credential is temporarily unavailable due to errors.
	StatusError Status = "error"
	// StatusDisabled marks the credential as intentionally disabled.
	StatusDisabled Status = "disabled"
)

Directories

Path Synopsis
Package authenticator provides concrete Authenticator implementations for CLI login flows.
Package authenticator provides concrete Authenticator implementations for CLI login flows.

Jump to

Keyboard shortcuts

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