Documentation
¶
Overview ¶
Package auth is the public auth API for the restish config and CLI.
The token cache (CachedToken, TokenStore, TokenCache) and the auth-handler interfaces (Handler, Param, AuthContext, Prompter, Logger, ForceCapable) are part of the supported public surface. External tools that need to share the restish OAuth token cache, or embed restish in a Go binary and register custom auth handlers, use this package.
The restish CLI's bundled auth-handler implementations (api-key, basic, bearer, oauth-*, and the external-tool approval flow) are not exposed here; they live in the unexported internal/auth package because their field shapes are tied to the restish auth registry and may change. External embedders that need OAuth should use golang.org/x/oauth2 directly rather than depending on restish's handlers.
Index ¶
- func DefaultTokenCachePath() string
- func LoadTokenCache(path string) (map[string]CachedToken, error)
- func SaveTokenCache(path string, m map[string]CachedToken) error
- type AuthContext
- type CachedToken
- type ForceCapable
- type Handler
- type Logger
- type Param
- type Prompter
- type TokenCache
- func (c *TokenCache) Delete(key string) error
- func (c *TokenCache) DeletePrefix(prefix string) error
- func (c *TokenCache) Get(key string) (*CachedToken, error)
- func (c *TokenCache) Path() string
- func (c *TokenCache) Refresh(key string, force bool, refresh func(CachedToken) (CachedToken, error)) (*CachedToken, bool, error)
- func (c *TokenCache) Set(key string, token CachedToken) error
- type TokenStore
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultTokenCachePath ¶
func DefaultTokenCachePath() string
DefaultTokenCachePath returns the path to the default token cache file, honoring the same RSH_CONFIG_DIR / RSH_CONFIG / XDG overrides as config.NewPaths. It is the canonical location for tools that want to share the Restish token cache.
func LoadTokenCache ¶
func LoadTokenCache(path string) (map[string]CachedToken, error)
LoadTokenCache reads the full token cache at path into a map. Returns an empty map when the file does not exist. External readers that do not need the in-process locking of TokenCache can call this directly.
func SaveTokenCache ¶
func SaveTokenCache(path string, m map[string]CachedToken) error
SaveTokenCache writes m as a CBOR token cache to path, atomically and under the sibling file lock.
Types ¶
type AuthContext ¶
type AuthContext struct {
APIName string
ProfileName string
BaseURL string
CacheKey string
Params map[string]string // user-supplied only
TokenStore TokenStore
Prompter Prompter
Stderr io.Writer
HTTPClient *http.Client
Logger Logger
Force bool // bypass cached access tokens for a single retry
}
AuthContext carries the request-scoped auth environment into a handler.
type CachedToken ¶
type CachedToken struct {
AccessToken string `cbor:"access_token" json:"access_token"`
TokenType string `cbor:"token_type,omitempty" json:"token_type,omitempty"`
RefreshToken string `cbor:"refresh_token,omitempty" json:"refresh_token,omitempty"`
Expiry time.Time `cbor:"expiry,omitempty" json:"expiry,omitempty"`
}
CachedToken holds a cached OAuth2 access token and optional refresh token.
func (*CachedToken) IsExpired ¶
func (t *CachedToken) IsExpired() bool
IsExpired reports whether the token is expired (or will expire within 30s).
type ForceCapable ¶
type ForceCapable interface {
SupportsForce()
}
ForceCapable marks handlers that can meaningfully bypass cached credentials after a 401 and retry once with fresh auth state.
type Handler ¶
type Handler interface {
Parameters() []Param
Authenticate(ctx context.Context, req *http.Request, ac AuthContext) error
}
Handler is implemented by each auth mechanism.
type Param ¶
type Param struct {
Name string
Description string
Required bool
Secret bool // true -> don't echo when prompting
}
Param describes a configuration parameter required by an auth handler.
type Prompter ¶
type Prompter interface {
Prompt(prompt string) (string, error)
PromptSecret(prompt string) (string, error)
}
Prompter reads interactive values from the user.
type TokenCache ¶
type TokenCache struct {
// contains filtered or unexported fields
}
TokenCache persists OAuth2 tokens as a flat CBOR map at a given file path. All operations are safe for concurrent use.
func NewTokenCache ¶
func NewTokenCache(path string) *TokenCache
NewTokenCache returns a TokenCache that stores tokens at path.
func (*TokenCache) Delete ¶
func (c *TokenCache) Delete(key string) error
Delete removes the entry for key. Returns nil when key is absent.
func (*TokenCache) DeletePrefix ¶
func (c *TokenCache) DeletePrefix(prefix string) error
DeletePrefix removes every cached token whose key begins with prefix.
func (*TokenCache) Get ¶
func (c *TokenCache) Get(key string) (*CachedToken, error)
Get returns the cached token for key, or (nil, nil) if not found.
func (*TokenCache) Path ¶
func (c *TokenCache) Path() string
Path returns the file path the cache reads from and writes to.
func (*TokenCache) Refresh ¶
func (c *TokenCache) Refresh(key string, force bool, refresh func(CachedToken) (CachedToken, error)) (*CachedToken, bool, error)
Refresh serializes a cached OAuth refresh for key across processes. It re-reads the cache under the sibling file lock, skips refresh when another process already stored a valid token, then stores the refreshed token before releasing the lock.
func (*TokenCache) Set ¶
func (c *TokenCache) Set(key string, token CachedToken) error
Set stores token under key, creating or updating the cache file.
type TokenStore ¶
type TokenStore interface {
Get(key string) (*CachedToken, error)
Set(key string, token CachedToken) error
Delete(key string) error
DeletePrefix(prefix string) error
}
TokenStore persists OAuth-style bearer tokens keyed by API/profile. *TokenCache satisfies this interface.
Source Files