auth

Documentation

Index

• func StartListener(addresses []string, callbackPath string, ...) error
• type Auth
  • func NewAuth(cfg *config.Config) *Auth
  • func (a *Auth) AppName() string
  • func (a *Auth) ForceRefreshOAuth2Token(username string) (string, error)
  • func (a *Auth) GetBearerTokenHeader() (string, error)
  • func (a *Auth) GetOAuth1Header(method, urlStr string, additionalParams map[string]string) (string, error)
  • func (a *Auth) GetOAuth2Header(username string) (string, error)
  • func (a *Auth) GetValidOAuth2Token(username string) (string, error)
  • func (a *Auth) OAuth2Flow(username string) (string, error)
  • func (a *Auth) RefreshOAuth2Token(username string) (string, error)
  • func (a *Auth) StartHeadlessLogin(username string) (*HeadlessLogin, error)
  • func (a *Auth) WithAppName(appName string) *Auth
  • func (a *Auth) WithTokenStore(tokenStore *store.TokenStore) *Auth
• type HeadlessLogin
  • func (h *HeadlessLogin) AuthURL() string
  • func (h *HeadlessLogin) Complete(pasted string) (string, error)
  • func (h *HeadlessLogin) RedirectURI() string

Functions

func StartListener

func StartListener(addresses []string, callbackPath string, callback func(code, state string) error, ready chan<- struct{}) error

Types

type Auth

type Auth struct {
	TokenStore *store.TokenStore
	// contains filtered or unexported fields
}

func NewAuth

func NewAuth(cfg *config.Config) *Auth

NewAuth creates a new Auth object. Credentials are resolved in order: env-var config → active app in .xurl store. If env var credentials are present, they're also backfilled into any migrated app that has tokens but no stored credentials.

func (*Auth) AppName

func (a *Auth) AppName() string

AppName returns the active app name override (empty means use default).

func (*Auth) ForceRefreshOAuth2Token

func (a *Auth) ForceRefreshOAuth2Token(username string) (string, error)

ForceRefreshOAuth2Token always performs the refresh-token grant, ignoring the locally cached expiry. Use it when the server rejects a token the local clock still considers valid (e.g. an HTTP 401 after a revocation or scope change).

func (*Auth) GetBearerTokenHeader

func (a *Auth) GetBearerTokenHeader() (string, error)

GetBearerTokenHeader gets the bearer token from the token store

func (*Auth) GetOAuth1Header

func (a *Auth) GetOAuth1Header(method, urlStr string, additionalParams map[string]string) (string, error)

GetOAuth1Header gets the OAuth1 header for a request

func (*Auth) GetOAuth2Header

func (a *Auth) GetOAuth2Header(username string) (string, error)

GetOAuth2Token gets or refreshes an OAuth2 token

func (*Auth) GetValidOAuth2Token

func (a *Auth) GetValidOAuth2Token(username string) (string, error)

GetValidOAuth2Token returns a valid OAuth2 access token for the active app and the given username, refreshing and persisting it if it has expired. Pass an empty username to use the app's default (or first) user.

Unlike GetOAuth2Header it never launches the interactive browser flow, so it is safe for non-interactive/scripted use. Callers that want browser fallback (e.g. the mcp bridge) should invoke OAuth2Flow themselves when this returns an error. This is the shared token-resolution primitive used by `xurl token` and `xurl mcp`.

func (*Auth) OAuth2Flow

func (a *Auth) OAuth2Flow(username string) (string, error)

OAuth2Flow runs the interactive authorization-code flow: it starts a local callback listener, opens the browser, and waits for the redirect. On machines without a reachable browser/callback, use the headless flow (StartHeadlessLogin) instead.

func (*Auth) RefreshOAuth2Token

func (a *Auth) RefreshOAuth2Token(username string) (string, error)

RefreshOAuth2Token validates and refreshes an OAuth2 token if needed

func (*Auth) StartHeadlessLogin

func (a *Auth) StartHeadlessLogin(username string) (*HeadlessLogin, error)

StartHeadlessLogin begins a headless login: it generates the PKCE/state material and the authorize URL without opening a browser or starting a listener.

func (*Auth) WithAppName

func (a *Auth) WithAppName(appName string) *Auth

WithAppName sets the explicit app name override.

func (*Auth) WithTokenStore

func (a *Auth) WithTokenStore(tokenStore *store.TokenStore) *Auth

WithTokenStore sets the token store for the Auth object

type HeadlessLogin

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

HeadlessLogin is an in-progress headless authorization-code login. Obtain one with StartHeadlessLogin, show the user AuthURL(), then pass whatever they paste back (the full redirect URL or just the code) to Complete. This avoids a local browser/callback entirely, so it works on headless/remote machines and never depends on the browser or a listener succeeding. Presentation is left to the caller -- the auth package never writes prompts itself.

func (*HeadlessLogin) AuthURL

func (h *HeadlessLogin) AuthURL() string

AuthURL is the URL the user opens in a browser (on any device) to authorize.

func (*HeadlessLogin) Complete

func (h *HeadlessLogin) Complete(pasted string) (string, error)

Complete finishes the login from the value the user pasted back -- the full redirect URL, a bare query string, or just the code -- verifying state (when present), exchanging the code for a token, and persisting it.

func (*HeadlessLogin) RedirectURI

func (h *HeadlessLogin) RedirectURI() string

RedirectURI is the callback the browser is redirected to (where the code appears in the address bar), shown to the user so they know what to copy.