Documentation
¶
Index ¶
- Constants
- Variables
- func Contexts() ([]*contexts.Context, string, error)
- func CurrentContextToken() (string, bool)
- func EnableInsecureHTTP()
- func LoginTokenForContext(c *contexts.Context) (string, error)
- func LookupCurrentToken() (string, error)
- func MigrateLegacyLoginContext() (migrated bool, err error)
- func RecordLoginContext(rawToken string, activate bool) (string, error)
- func RemoveAllContexts() (int, error)
- func RemoveCurrentContext() error
- func RepoScopedToken(ctx context.Context, clusterBaseURL, repoSlug, action string) (string, error)
- func SetCurrentContext(name string) error
- func SetManagerForTest(t interface{ ... }, mgr *tokenmanager.Manager) func()
- func SetProviderForTest(t interface{ ... }, p Provider)
- func SetRepoExchangeTransportForTest(rt http.RoundTripper) func()
- func TokenForResource(ctx context.Context, resourceBaseURL string) (string, error)
- type Client
- type ContextStore
- 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 overrides the auto-detected provider version. Set to "v1" or "v2"; see effectiveProviderVersion for resolution. Read once at process startup via CurrentProvider.
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 Contexts ¶ added in v0.7.0
Contexts returns all stored login contexts and the current context name, for listing/switching. Order matches on-disk order.
func CurrentContextToken ¶ added in v0.7.0
CurrentContextToken returns the login JWT for the active context in contexts.json, or ("", false) when there is no current context or it has no stored token. This is the contexts.json half of the CLI's credential resolution; callers fall back to the legacy keyring entry so pre-contexts logins keep working until migrated.
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 LoginTokenForContext ¶ added in v0.7.0
LoginTokenForContext returns the login JWT stored for c, read from the OS keyring slot the context points at. The encoded expiry is stripped; the server is the authority on validity and the device-flow login holds no refresh token, so an expired token surfaces as a 401 the caller can translate into a re-login hint.
func LookupCurrentToken ¶
LookupCurrentToken retrieves the active login token. It prefers the current contexts.json context (so a login from this or entiredb's CLIs authenticates control-plane commands), falling back to the legacy entry keyed by the auth issuer (api.AuthBaseURL()) for pre-contexts logins.
func MigrateLegacyLoginContext ¶ added in v0.7.0
MigrateLegacyLoginContext bridges users who logged in before the contexts.json dual-write existed: if the legacy entire-cli/<authBaseURL> keyring entry holds a usable JWT and no context yet covers its issuer, it records an equivalent context (and keychain entry under the shared scheme) so the git remote helper can authenticate without a re-login.
Returns (true, nil) when it created a context. No-ops — returning (false, nil) — when there's no legacy token, the token is opaque (no derivable issuer), or a context for that issuer already exists. Idempotent: safe to call on every helper invocation.
func RecordLoginContext ¶ added in v0.7.0
RecordLoginContext records a freshly obtained login token in the shared contexts.json credential model: it derives the issuer (core URL), handle, and expiry from the token's own claims, stores the token in the OS keyring under the entire-core:<issuer> service scheme entiredb uses, and writes (or updates) the matching context.
Contexts are keyed by identity (core URL + handle): re-logging into the same identity updates its context in place, while a second identity on the same core gets its own context (named handle@host) instead of clobbering the first.
activate controls current_context: login passes true (the just-completed login becomes active, kubectl use-context style); read-time migration passes false so it never silently switches the user's active account — it still sets current_context when none exists yet.
This is the contexts.json half of login's dual-write: the legacy entire-cli/<authBaseURL> keyring entry is still written by the caller so the control-plane readers keep working untouched during the transition. A login recorded here is visible to entiredb's CLIs (and the in-CLI git remote helper) because they share this file and keychain layout.
Returns the context name on success. Errors are returned (not swallowed) so the caller can warn; login still succeeds on the legacy entry.
func RemoveAllContexts ¶ added in v0.7.0
RemoveAllContexts deletes every stored context and its keyring token — a full local logout. Returns the number of contexts removed. Best-effort on the keyring deletes; the contexts.json clear is what makes the CLI fully logged out.
func RemoveCurrentContext ¶ added in v0.7.0
func RemoveCurrentContext() error
RemoveCurrentContext deletes the active context from contexts.json and its keyring token, clearing current_context. It is a no-op (returns nil) when there is no current context. Used by logout.
func RepoScopedToken ¶ added in v0.7.0
RepoScopedToken exchanges the logged-in user's token for a short-lived, repo-scoped access token usable against a data-plane cluster's git endpoints (clone / fetch / info-refs).
The data plane's git gate rejects the raw login bearer (HTTP 403): it only accepts a token whose RFC 8693 audience is <clusterBaseURL><repoSlug> and whose scope is "repo:<action>". This is the same exchange git-remote-entire performs internally for the entire:// transport — the CLI does it in-process when it needs to read the data plane directly (e.g. probing a mirror's clone readiness).
- clusterBaseURL is the data-plane cluster origin (scheme+host, e.g. https://aws-us-east-2.entire.io); a trailing slash is trimmed.
- repoSlug is the full surface-prefixed path (e.g. /gh/octocat/hello or /et/<project>/<repo>), joined to the cluster URL verbatim to form the audience.
- action is "pull" for reads or "push" for writes.
The exchange targets the same core endpoint and client identity the CLI logged in against (AuthBaseURL + the provider's STS path, client_id entire-cli), so a successful login implies a usable exchange. Errors surface verbatim from the STS endpoint (e.g. invalid_target when no mirror matches the slug+cluster).
The subject token is the stored login access token read directly, rather than routed through the refresh-aware tokenmanager. That's deliberate for two reasons: (1) `entire login` (device flow) stores only a bare access token — no refresh token — so there is nothing the manager could refresh that this path can't equally use; an expired login token fails both ways. (2) The manager's exchange also emits an RFC 8693 `resource` parameter alongside `audience`, whereas the data-plane gate keys solely on `audience`; going direct keeps the wire form byte-for-byte what git-remote-entire (and the standalone entiredb CLI) already send. Each call performs a fresh exchange and does not cache — callers that poll (e.g. the mirror clone wait) re-invoke on token expiry. If the CLI gains refresh tokens, route this through the tokenmanager instead.
func SetCurrentContext ¶ added in v0.7.0
SetCurrentContext makes name the active context. Returns an error when no context with that name exists (a stale current pointer is a foot-gun).
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 SetRepoExchangeTransportForTest ¶ added in v0.7.0
func SetRepoExchangeTransportForTest(rt http.RoundTripper) func()
SetRepoExchangeTransportForTest installs rt as the transport used by RepoScopedToken and returns a cleanup function. Test-only.
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 active. See CurrentProvider for the resolution rules (ENTIRE_AUTH_PROVIDER_VERSION wins, then split-host auto-detect, then v1 fallback).
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 ContextStore ¶ added in v0.7.0
type ContextStore struct {
*Store
}
ContextStore wraps the legacy keyring Store so token *reads* prefer the active contexts.json context, falling back to the legacy entire-cli/<authBaseURL> entry. Writes are inherited from Store unchanged — login dual-writes the context via RecordLoginContext, so the write side needs no override here.
This is the single seam that lets the control-plane readers (the tokenmanager, LookupCurrentToken, and `auth status`/`list`) honor a contexts.json login — including one created by entiredb's CLIs that share this file. *ContextStore satisfies both the cli package's tokenStore interface and auth-go's tokenstore.Store.
func NewContextStore ¶ added in v0.7.0
func NewContextStore() *ContextStore
NewContextStore returns a context-preferring view over the legacy store.
func (*ContextStore) GetToken ¶ added in v0.7.0
func (s *ContextStore) GetToken(baseURL string) (string, error)
GetToken prefers the active context's token, falling back to the legacy entry keyed by baseURL.
func (*ContextStore) LoadTokens ¶ added in v0.7.0
func (s *ContextStore) LoadTokens(profile string) (tokens.TokenSet, error)
LoadTokens (the tokenstore.Store method the tokenmanager calls) prefers the active context's token, falling back to the legacy profile entry.
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 freezes on the first call (env vars must be set before then). Tests bypass the singleton via SetProviderForTest.
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