Documentation
¶
Index ¶
- Constants
- Variables
- func EnableInsecureHTTP()
- func LookupCurrentToken() (string, error)
- func SetManagerForTest(t interface{ ... }, mgr *tokenmanager.Manager) func()
- func SetProviderForTest(t interface{ ... }, p Provider)
- func Token(ctx context.Context, req TokenRequest) (string, error)
- func TokenForResource(ctx context.Context, resourceBaseURL string) (string, error)
- type Client
- type DeviceAuthPoll
- type DeviceAuthStart
- type Provider
- type Store
- func (s *Store) DeleteToken(baseURL string) error
- func (s *Store) DeleteTokens(profile string) error
- func (s *Store) GetToken(baseURL string) (string, error)
- func (s *Store) LoadTokens(profile string) (tokens.TokenSet, error)
- func (s *Store) SaveToken(baseURL, token string) error
- func (s *Store) SaveTokens(profile string, t tokens.TokenSet) error
- type TokenRequest
Constants ¶
const ProviderVersionEnvVar = "ENTIRE_AUTH_PROVIDER_VERSION"
ProviderVersionEnvVar selects which OAuth surface this CLI talks to.
Recognised values:
- "v1" (or unset / unrecognised) — current device-flow surface
- "v2" — next-generation device-flow surface
Read once at process startup via CurrentProvider; later flips within the same process are intentionally ignored. Tests inject via SetProviderForTest rather than mutating the env mid-run.
Variables ¶
var ErrNotLoggedIn = tokenmanager.ErrNotLoggedIn
ErrNotLoggedIn re-exports tokenmanager.ErrNotLoggedIn so callers in the cli package can errors.Is against it without an extra import.
Functions ¶
func EnableInsecureHTTP ¶ added in v0.6.3
func EnableInsecureHTTP()
EnableInsecureHTTP relaxes the package-level manager's HTTPS guard so non-loopback http:// resources (and the auth host's STS endpoint) are permitted during token resolution. The CLI calls this when the user passes --insecure-http-auth to a command that hits the data API on a private network (e.g. a split-host local-dev box where both hosts are plain HTTP).
Call before any TokenForResource invocation — the manager is built lazily on first use and the AllowInsecureHTTP setting is frozen at that point.
func LookupCurrentToken ¶
LookupCurrentToken retrieves the token for the current auth base URL. Tokens are keyed by the auth issuer (api.AuthBaseURL()) since that's the host that minted them; in single-host deployments AuthBaseURL falls back to BaseURL so behaviour is unchanged.
func SetManagerForTest ¶ added in v0.6.3
func SetManagerForTest(t interface{ Helper() }, mgr *tokenmanager.Manager) func()
SetManagerForTest installs mgr as the manager returned by defaultManager() and returns a cleanup function. Test-only.
func SetProviderForTest ¶ added in v0.6.3
func SetProviderForTest(t interface {
Helper()
Cleanup(f func())
}, p Provider)
SetProviderForTest installs p as the Provider returned by CurrentProvider for the duration of the test, and registers a t.Cleanup to remove the override. Test-only.
Takes a tiny interface rather than *testing.T so production builds don't import testing.
func Token ¶ added in v0.6.3
func Token(ctx context.Context, req TokenRequest) (string, error)
Token is the full-control entry point. Use TokenForResource for the common case; this exists so callers can override the wire-level Audience, RequestedTokenType, or Scope per call.
func TokenForResource ¶ added in v0.6.3
TokenForResource returns a bearer token suitable for use against resourceBaseURL, performing an RFC 8693 token exchange when the stored core token's audience doesn't already cover that resource. See tokenmanager.Manager.Token for the full resolution rules.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client wraps a deviceflow.Client preconfigured for whichever provider version is selected via ENTIRE_AUTH_PROVIDER_VERSION (defaulting to v1).
func NewClient ¶
NewClient constructs a Client targeting the active provider version. httpClient.Transport is reused when non-nil (its TLS / proxy config flows through); a nil httpClient or nil Transport falls back to the deviceflow default (http.DefaultTransport).
HTTPS is required by default. Loopback http:// (localhost, 127.0.0.1, ::1) is always permitted — see isLoopbackHTTP. allowInsecureHTTP=true additionally permits non-loopback http:// for cases like local-dev auth hosts on a private network (e.g. http://devbox.internal); the CLI plumbs this from the --insecure-http-auth flag.
func (*Client) PollDeviceAuth ¶
PollDeviceAuth polls the token endpoint. On any OAuth-protocol error (recognised RFC 8628 §3.5 sentinel or unknown but spec-shaped code like invalid_request / invalid_client / server_error), the wire-side code is returned in DeviceAuthPoll.Error so the existing polling loop in login.go can branch on it — known codes hit the dedicated switch arms, unknown codes fall through to the default arm and fail fast. Non-protocol errors (network, decode) are returned as a real error and treated as transient by the polling loop.
func (*Client) StartDeviceAuth ¶
func (c *Client) StartDeviceAuth(ctx context.Context) (*DeviceAuthStart, error)
StartDeviceAuth requests a fresh device code.
type DeviceAuthPoll ¶
type DeviceAuthPoll struct {
AccessToken string
TokenType string
ExpiresIn int
Scope string
Error string
ErrorDescription string
}
DeviceAuthPoll is the historical token-poll response shape. The shim flattens deviceflow's typed errors back into the Error field so existing login.go logic that switches on result.Error keeps working.
ErrorDescription carries the optional `error_description` from the server's RFC 8628 §3.5 error response, when present. Used to give callers a more actionable message than the bare error code.
type DeviceAuthStart ¶
type DeviceAuthStart = deviceflow.DeviceCode
DeviceAuthStart preserves the historical type name; the shape now matches deviceflow.DeviceCode field-for-field.
type Provider ¶ added in v0.6.3
type Provider struct {
ClientID string
DeviceCodePath string
TokenPath string
STSPath string
AuthTokensPath string
}
Provider captures the per-surface bits of OAuth wiring.
STSPath is the RFC 8693 token-exchange endpoint. v1 is the legacy single-host surface where the auth and data API live at the same origin; the same-host shortcut in tokenmanager.Token always wins and STS is never invoked, so v1.STSPath is left empty. v2 exposes a dedicated STS path because it's used in split-host deployments (e.g. us.auth.partial.to mints, partial.to consumes).
AuthTokensPath is the base path for the auth-tokens management endpoint family (list / revoke). Routed at the api.Client layer via (*api.Client).WithAuthTokensPath so the provider table is the single source of truth — no env-var duplication between auth/ and api/.
func CurrentProvider ¶ added in v0.6.3
func CurrentProvider() Provider
CurrentProvider returns the active Provider for this process.
Resolution: read ENTIRE_AUTH_PROVIDER_VERSION exactly once on first call, freeze the result, and return the same Provider on every subsequent call. Tests that need a different provider must use SetProviderForTest before any auth call constructs the singleton.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store manages CLI authentication tokens via a pluggable backend. The production binary always resolves to the OS keyring. A file-backed backend is available only in builds tagged `authfilestore` (used by integration tests to avoid the OS keychain).
Implements tokenstore.Store so it can be passed to tokenmanager.New as the persistence layer. The interface methods (SaveTokens / LoadTokens / DeleteTokens) delegate to the same backend as the legacy SaveToken / GetToken / DeleteToken pair, so production and test paths share a single source of truth.
func NewStore ¶
func NewStore() *Store
NewStore returns a Store backed by the system keyring (or, in `authfilestore` builds, optionally a file-backed test store).
func NewStoreWithService ¶
NewStoreWithService returns a Store with a custom keyring service name (for testing). Honors the same backend selection as NewStore so tests that opt into the file-backed test store via env var see consistent behavior across both constructors.
func (*Store) DeleteToken ¶
DeleteToken removes a stored token for the given base URL. Returns no error if the token does not exist. Prefer DeleteTokens (the tokenstore.Store interface method); DeleteToken is retained for direct-bearer call sites.
func (*Store) DeleteTokens ¶ added in v0.6.3
DeleteTokens implements tokenstore.Store.
func (*Store) GetToken ¶
GetToken retrieves a stored token for the given base URL. Returns an empty string (and no error) if no token is stored, or if the stored value is JSON-shaped (defensive: pre-shim entries are opaque token strings, never JSON; a JSON blob in the keyring is corruption and must not be put on the wire as a bearer).
Prefer LoadTokens (the tokenstore.Store interface method) for new callers — it returns the full TokenSet so refresh tokens and expiry survive the round trip. GetToken is retained for the direct-bearer call sites that only need the access token string.
func (*Store) LoadTokens ¶ added in v0.6.3
LoadTokens implements tokenstore.Store. Reads the bare-string entry and wraps it back into a TokenSet. Returns tokenstore.ErrNotFound when nothing is stored under the profile (or the stored value is JSON-shaped — see GetToken's note about defensive rejection of non-token blobs) so callers can errors.Is against the lib sentinel.
func (*Store) SaveToken ¶
SaveToken persists an access token for the given base URL. Prefer SaveTokens (the tokenstore.Store interface method) for new callers; SaveToken is kept for the legacy direct-bearer call sites (login, logout, auth status/list/revoke) that don't go through the tokenmanager.
func (*Store) SaveTokens ¶ added in v0.6.3
SaveTokens implements tokenstore.Store. Refresh token, scope, expiry, and token type are intentionally dropped — the entire device-flow surface doesn't issue refresh tokens, and the legacy keyring/file layout stores bare access-token strings. If refresh-token support lands, this method (and the tokenBackend interface) become the migration point.
type TokenRequest ¶ added in v0.6.3
type TokenRequest = tokenmanager.TokenRequest
TokenRequest is the entire-CLI alias of tokenmanager.TokenRequest so callers don't have to import the underlying package for the common case. The two types are interchangeable.
Source Files