auth

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Jul 16, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package auth manages local OAuth application and token state.

Index

Constants

View Source 
const (

	// GrantTypeAuthorizationCode is the persisted authorization-code OAuth grant variant.
	GrantTypeAuthorizationCode = "authorization_code"
	// GrantTypeClientCredentials is the persisted client-credentials OAuth grant variant.
	GrantTypeClientCredentials = "client_credentials"
)

Variables

This section is empty.

Functions

func AppConfigEmpty 

func AppConfigEmpty(app AppConfig) bool

AppConfigEmpty reports whether OAuth app configuration is unset.

func SplitScopes 

func SplitScopes(value string) []string

SplitScopes parses comma- or whitespace-delimited OAuth scopes.

Types

type AppConfig 

type AppConfig struct {
	ClientID     string   `json:"client_id,omitempty"`
	ClientSecret string   `json:"client_secret,omitempty"`
	RedirectURI  string   `json:"redirect_uri,omitempty"`
	Scopes       []string `json:"scopes,omitempty"`
}

AppConfig is the saved OAuth application material.

Secret-bearing fields (ClientSecret) must appear in String/GoString/MarshalJSON redaction below AND in persistedAppConfig for on-disk persistence.

func AppConfigFromEnv 

func AppConfigFromEnv(env Env) AppConfig

AppConfigFromEnv resolves OAuth app material from environment variables.

func MergeAppConfig 

func MergeAppConfig(base AppConfig, override AppConfig) AppConfig

MergeAppConfig overlays explicitly supplied OAuth app material onto a base config.

func (AppConfig) GoString added in v0.7.0 

func (app AppConfig) GoString() string

GoString redacts secret material for fmt's %#v verb.

func (AppConfig) MarshalJSON added in v0.7.0 

func (app AppConfig) MarshalJSON() ([]byte, error)

MarshalJSON redacts secret material so json.Marshal never emits raw values.

func (AppConfig) String added in v0.7.0 

func (app AppConfig) String() string

String redacts secret material for fmt's %v, %+v, and %s verbs.

type AuthError 

type AuthError struct {
	Code    ErrorCode
	Message string
	Err     error
}

AuthError reports a stable OAuth auth/readiness failure without secrets.

func NewError 

func NewError(code ErrorCode, message string) *AuthError

NewError returns a structured OAuth auth/readiness error.

func WrapError 

func WrapError(code ErrorCode, message string, err error) *AuthError

WrapError returns a structured OAuth auth/readiness error with a cause.

func (*AuthError) Error 

func (err *AuthError) Error() string

func (*AuthError) Unwrap 

func (err *AuthError) Unwrap() error

type CredentialKind added in v0.7.1 

type CredentialKind uint8

CredentialKind identifies the provenance and recovery contract of an OAuth credential. 

const (
	// CredentialKindMissing identifies an absent OAuth credential.
	CredentialKindMissing CredentialKind = iota
	// CredentialKindInjectedAccessToken identifies a non-recoverable process override.
	CredentialKindInjectedAccessToken
	// CredentialKindLocalAccessToken identifies local token material without an explicit recovery grant.
	CredentialKindLocalAccessToken
	// CredentialKindAuthorizationCode identifies a refreshable authorization-code credential.
	CredentialKindAuthorizationCode
	// CredentialKindClientCredentials identifies a reacquirable OAuth app credential.
	CredentialKindClientCredentials
)

func CredentialKindFromToken added in v0.7.1 

func CredentialKindFromToken(token TokenState) CredentialKind

CredentialKindFromToken returns the explicit recovery variant persisted with a local token.

func (CredentialKind) Recoverable added in v0.7.1 

func (kind CredentialKind) Recoverable() bool

Recoverable reports whether the credential kind permits an OAuth token exchange.

type Env 

type Env interface {
	Lookup(key string) (string, bool)
}

Env resolves environment variables by key.

type ErrorCode 

type ErrorCode string

ErrorCode is a stable machine-readable OAuth failure reason. 

const (
	ErrorCodeNotConfigured  ErrorCode = "AUTH_NOT_CONFIGURED"
	ErrorCodeTokenExpired   ErrorCode = "AUTH_TOKEN_EXPIRED" //nolint:gosec // OAuth error code label, not a credential.
	ErrorCodeRefreshFailed  ErrorCode = "AUTH_REFRESH_FAILED"
	ErrorCodeReauthRequired ErrorCode = "AUTH_REAUTH_REQUIRED"
	ErrorCodeMissingScope   ErrorCode = "MISSING_SCOPE"
	ErrorCodeActorMismatch  ErrorCode = "AUTH_ACTOR_MISMATCH"
	ErrorCodeTargetMismatch ErrorCode = "AUTH_TARGET_MISMATCH"
	// ErrorCodeTargetNotConfigured separates "no pinned target exists" from a genuine mismatch so
	// agents recover by configuring .linctl.toml instead of reauthorizing.
	ErrorCodeTargetNotConfigured ErrorCode = "AUTH_TARGET_NOT_CONFIGURED"
)

Error codes classify OAuth auth/readiness failures for command output.

type Paths 

type Paths struct {
	AppConfigPath string
	TokenPath     string
}

Paths identifies the local auth files.

func DefaultPaths 

func DefaultPaths(env Env) (Paths, error)

DefaultPaths returns OS-native user paths for linctl auth state.

type ProfileState 

type ProfileState struct {
	App   AppConfig  `json:"app,omitempty"`
	Token TokenState `json:"token,omitempty"`
}

ProfileState is auth state scoped to one auth profile.

type Session 

type Session struct {
	State           State
	Profile         string
	App             AppConfig
	Token           TokenState
	CredentialKind  CredentialKind
	TokenSource     string
	PersistentToken bool
}

Session is the selected OAuth state for one linctl profile.

func SelectLocalSession added in v0.7.1 

func SelectLocalSession(ctx context.Context, request SessionRequest) (Session, error)

SelectLocalSession loads profile state and process app configuration without applying an injected access token.

func SelectSession 

func SelectSession(ctx context.Context, request SessionRequest) (Session, error)

SelectSession loads local auth state once and overlays process OAuth material.

type SessionRequest 

type SessionRequest struct {
	Env     Env
	Store   Store
	Profile string
}

SessionRequest describes the sources used to select OAuth state.

type State 

type State struct {
	App      AppConfig               `json:"app,omitempty"`
	Token    TokenState              `json:"token,omitempty"`
	Profiles map[string]ProfileState `json:"profiles,omitempty"`
}

State groups local auth state while keeping app config and tokens separate.

func (State) Profile 

func (state State) Profile(profile string) ProfileState

Profile returns the auth state selected by a profile name.

type Store 

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

Store reads and writes local auth state.

func NewStore 

func NewStore(paths Paths) Store

NewStore returns a local auth state store.

func (Store) ClearAppConfig 

func (store Store) ClearAppConfig(ctx context.Context, profile string) error

ClearAppConfig removes saved OAuth app configuration while preserving token state.

func (Store) ClearTokenState 

func (store Store) ClearTokenState(ctx context.Context, profile string) error

ClearTokenState removes saved OAuth token material while preserving app config.

func (Store) Load 

func (store Store) Load(ctx context.Context) (State, error)

Load reads local auth state. Missing files resolve as empty state.

func (Store) Save 

func (store Store) Save(ctx context.Context, state State) error

Save writes local auth state.

func (Store) SaveAppConfig 

func (store Store) SaveAppConfig(ctx context.Context, profile string, app AppConfig) error

SaveAppConfig writes OAuth app configuration without touching token state.

func (Store) SaveTokenState 

func (store Store) SaveTokenState(ctx context.Context, profile string, token TokenState) error

SaveTokenState writes OAuth token state without touching app configuration.

func (Store) TransactTokenState added in v0.7.1 

func (store Store) TransactTokenState(
	ctx context.Context,
	profile string,
	transaction TokenStateTransaction,
) (TokenState, error)

TransactTokenState reloads, updates, and persists one profile's token under one cross-process lock. The transaction callback must not call Store persistence methods because the lock is not reentrant.

type TokenEndpointError 

type TokenEndpointError struct {
	Code       ErrorCode
	StatusCode int
	OAuthError string
}

TokenEndpointError reports a token endpoint failure without secret values.

func NewTokenEndpointError 

func NewTokenEndpointError(code ErrorCode, statusCode int, oauthError string) *TokenEndpointError

NewTokenEndpointError returns a redacted structured token endpoint error.

func (*TokenEndpointError) Error 

func (err *TokenEndpointError) Error() string

type TokenState 

type TokenState struct {
	AccessToken  string     `json:"access_token,omitempty"`
	RefreshToken string     `json:"refresh_token,omitempty"`
	TokenType    string     `json:"token_type,omitempty"`
	Scopes       []string   `json:"scopes,omitempty"`
	ExpiresAt    *time.Time `json:"expires_at,omitempty"`
	Actor        string     `json:"actor,omitempty"`
	GrantType    string     `json:"grant_type,omitempty"`
}

TokenState is the saved OAuth token material.

Secret-bearing fields (AccessToken, RefreshToken) must appear in String/GoString/MarshalJSON redaction below AND in persistedTokenState for on-disk persistence.

func NewTokenState 

func NewTokenState(
	accessToken string,
	refreshToken string,
	tokenType string,
	expiresAt time.Time,
	scopes []string,
) TokenState

NewTokenState maps OAuth token endpoint fields into local auth state.

func (TokenState) Equal added in v0.7.1 

func (token TokenState) Equal(other TokenState) bool

Equal reports whether all persisted token fields match.

func (TokenState) GoString added in v0.7.0 

func (token TokenState) GoString() string

GoString redacts secret material for fmt's %#v verb.

func (TokenState) MarshalJSON added in v0.7.0 

func (token TokenState) MarshalJSON() ([]byte, error)

MarshalJSON redacts secret material so json.Marshal never emits raw values.

func (TokenState) String added in v0.7.0 

func (token TokenState) String() string

String redacts secret material for fmt's %v, %+v, and %s verbs.

type TokenStateTransaction added in v0.7.1 

type TokenStateTransaction func(current TokenState) (TokenState, error)

TokenStateTransaction updates one profile's token while its state-file lock is held.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.