credentials

README

Circles credentials for Go

Official Go implementation of the Circles credential-provider contract. The package name is credentials and the module is published as github.com/circlesac/credentials-go. It requires Go 1.18 or later.

import "github.com/circlesac/credentials-go"

provider, err := credentials.New()
if err != nil {
    return err
}
credential, err := provider.Resolve(ctx)
if err != nil {
    return err
}

request.Header.Set("Authorization", "Bearer "+credential.Value)

The provider reads canonical and compatibility environment variables and named profiles, migrates legacy crcl profiles without deleting them, refreshes OAuth tokens directly, and uses atomic credential writes with a cross-process lock. SetCurrentProfile shares the selected profile across Circles clients while explicit and environment-selected profiles keep precedence.

The language-neutral cases under schemas/ mirror circlesac/credentials/schemas. CI rejects drift between the canonical cases and this Go module's copy.

Development

go test -race ./...
go vet ./...

Releases use root v* tags.

Documentation

Overview

Package credentials resolves and manages shared Circles credentials.

Index

• func IsError(err error, code ErrorCode) bool
• type Credential
• type CredentialProvider
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type ErrorCode
• type FilePaths
• type Kind
  • func ClassifyCredential(value string) (Kind, *time.Time, error)
• type Option
  • func WithClientID(clientID string) Option
  • func WithConfigFile(path string) Option
  • func WithCredential(value string) Option
  • func WithCredentialProvider(provider CredentialProvider) Option
  • func WithCredentialsFile(path string) Option
  • func WithEnvironment(environment map[string]string) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithHomeDir(home string) Option
  • func WithLockTimeout(timeout time.Duration) Option
  • func WithNow(now func() time.Time) Option
  • func WithProfile(profile string) Option
• type ProfileConfig
• type ProfileCredentials
• type ProfileUpdate
• type Provider
  • func New(configure ...Option) (*Provider, error)
  • func (provider *Provider) ClearProfiles(ctx context.Context) error
  • func (provider *Provider) CurrentProfile(ctx context.Context) (string, bool, error)
  • func (provider *Provider) DeleteProfile(ctx context.Context) error
  • func (provider *Provider) GetProfile(ctx context.Context) (*StoredProfile, error)
  • func (provider *Provider) Paths() FilePaths
  • func (provider *Provider) Refresh(ctx context.Context) (Credential, error)
  • func (provider *Provider) Resolve(ctx context.Context) (Credential, error)
  • func (provider *Provider) SelectedProfileName(ctx context.Context) (string, error)
  • func (provider *Provider) SetCurrentProfile(ctx context.Context, profile string) error
  • func (provider *Provider) UpdateProfile(ctx context.Context, update ProfileUpdate) error
• type Source
• type SourceType
• type StoredProfile

Functions

func IsError

func IsError(err error, code ErrorCode) bool

IsError reports whether err is a Circles credential error with code.

Types

type Credential

type Credential struct {
	Value     string
	Kind      Kind
	ExpiresAt *time.Time
	Source    Source
}

Credential is a resolved Circles Bearer credential.

type CredentialProvider

type CredentialProvider interface {
	Resolve(context.Context) (Credential, error)
}

CredentialProvider resolves a credential with cancellation support.

type Error

type Error struct {
	Code ErrorCode
	// contains filtered or unexported fields
}

Error is safe to show to a user and never contains credential values.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ErrorCode

type ErrorCode string

ErrorCode is a stable, language-neutral credential failure category.

const (
	ErrCredentialNotFound  ErrorCode = "CREDENTIAL_NOT_FOUND"
	ErrInvalidCredential   ErrorCode = "INVALID_CREDENTIAL"
	ErrAmbiguousCredential ErrorCode = "AMBIGUOUS_CREDENTIAL"
	ErrRefreshFailed       ErrorCode = "REFRESH_FAILED"
	ErrProfileConflict     ErrorCode = "PROFILE_CONFLICT"
	ErrCredentialStorage   ErrorCode = "CREDENTIAL_STORAGE_FAILED"
)

type FilePaths

type FilePaths struct {
	ConfigFile            string
	CredentialsFile       string
	LegacyConfigFile      string
	LegacyCredentialsFile string
	LegacyJSONFile        string
}

FilePaths are the canonical and compatibility paths used by a Provider.

type Kind

type Kind string

Kind identifies the Bearer value syntax without authenticating it.

const (
	KindJWT    Kind = "jwt"
	KindAPIKey Kind = "api_key"
)

func ClassifyCredential

func ClassifyCredential(value string) (Kind, *time.Time, error)

ClassifyCredential detects a syntactically valid JWT or opaque API key.

type Option

type Option func(*providerOptions)

Option configures a Provider.

func WithClientID

func WithClientID(clientID string) Option

WithClientID replaces the OAuth public client identifier.

func WithConfigFile

func WithConfigFile(path string) Option

WithConfigFile replaces the shared config path.

func WithCredential

func WithCredential(value string) Option

WithCredential supplies the highest-precedence in-memory Bearer value.

func WithCredentialProvider

func WithCredentialProvider(provider CredentialProvider) Option

WithCredentialProvider supplies the highest-precedence credential provider.

func WithCredentialsFile

func WithCredentialsFile(path string) Option

WithCredentialsFile replaces the shared credentials path.

func WithEnvironment

func WithEnvironment(environment map[string]string) Option

WithEnvironment replaces the process environment, primarily for embedding and tests.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient replaces the OAuth refresh HTTP client.

func WithHomeDir

func WithHomeDir(home string) Option

WithHomeDir replaces the operating-system home directory.

func WithLockTimeout

func WithLockTimeout(timeout time.Duration) Option

WithLockTimeout replaces the cross-process lock wait timeout.

func WithNow

func WithNow(now func() time.Time) Option

WithNow replaces the clock.

func WithProfile

func WithProfile(profile string) Option

WithProfile selects a named profile explicitly.

type ProfileConfig

type ProfileConfig struct {
	APIURL  string
	AuthURL string
	Org     string
}

ProfileConfig contains non-secret endpoint and default-context settings.

type ProfileCredentials

type ProfileCredentials struct {
	AccessToken  string
	RefreshToken string
	APIKey       string
}

ProfileCredentials replaces one profile's credential form.

type ProfileUpdate

type ProfileUpdate struct {
	Config      *ProfileConfig
	Credentials *ProfileCredentials
}

ProfileUpdate updates either or both shared profile files.

type Provider

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

Provider resolves and manages Circles shared credentials.

func New

func New(configure ...Option) (*Provider, error)

New creates a shared credential provider.

func (*Provider) ClearProfiles

func (provider *Provider) ClearProfiles(ctx context.Context) error

ClearProfiles removes all canonical profiles while retaining legacy rollback files.

func (*Provider) CurrentProfile

func (provider *Provider) CurrentProfile(ctx context.Context) (string, bool, error)

CurrentProfile returns the persisted non-secret current-profile selection.

func (*Provider) DeleteProfile

func (provider *Provider) DeleteProfile(ctx context.Context) error

DeleteProfile removes the selected canonical profile while retaining migration history.

func (*Provider) GetProfile

func (provider *Provider) GetProfile(ctx context.Context) (*StoredProfile, error)

GetProfile returns only a selected profile's non-secret settings.

func (*Provider) Paths

func (provider *Provider) Paths() FilePaths

Paths returns non-secret storage paths used by the provider.

func (*Provider) Refresh

func (provider *Provider) Refresh(ctx context.Context) (Credential, error)

Refresh forces OAuth refresh for the selected profile.

func (*Provider) Resolve

func (provider *Provider) Resolve(ctx context.Context) (Credential, error)

Resolve evaluates the shared provider chain.

func (*Provider) SelectedProfileName

func (provider *Provider) SelectedProfileName(ctx context.Context) (string, error)

SelectedProfileName returns the profile selected by explicit options, environment variables, shared current-profile metadata, or legacy default.

func (*Provider) SetCurrentProfile

func (provider *Provider) SetCurrentProfile(ctx context.Context, profile string) error

SetCurrentProfile makes an existing credential profile the shared default selection.

func (*Provider) UpdateProfile

func (provider *Provider) UpdateProfile(ctx context.Context, update ProfileUpdate) error

UpdateProfile atomically replaces each changed profile file.

type Source

type Source struct {
	Type    SourceType `json:"type"`
	Profile string     `json:"profile,omitempty"`
}

Source contains only non-secret diagnostic metadata.

type SourceType

type SourceType string

SourceType identifies the winning provider category.

const (
	SourceExplicit    SourceType = "explicit"
	SourceEnvironment SourceType = "environment"
	SourceProfile     SourceType = "profile"
)

type StoredProfile

type StoredProfile struct {
	Name   string
	Config ProfileConfig
}

StoredProfile is the non-secret portion of a named profile.