auth

Documentation

Overview

Package auth provides OAuth 2.0 token acquisition for authenticated A2A and MCP targets. It supports two flows:

• Client credentials (machine-to-machine, no user interaction)
• Authorization code with PKCE (for targets that require user consent)

Index

• func DiscoverTokenURL(ctx context.Context, issuer string) string
• type AuthCodeConfig
• type ClientCredentialsConfig
• type PKCEFlowConfig
• type PKCEParams
  • func GeneratePKCE() (*PKCEParams, error)
• type TokenResponse
  • func ExchangeAuthCode(ctx context.Context, cfg AuthCodeConfig) (*TokenResponse, error)
  • func FetchClientCredentialsToken(ctx context.Context, cfg ClientCredentialsConfig) (*TokenResponse, error)
  • func PerformPKCEFlow(ctx context.Context, cfg PKCEFlowConfig) (*TokenResponse, error)

Functions

func DiscoverTokenURL

func DiscoverTokenURL(ctx context.Context, issuer string) string

DiscoverTokenURL attempts to discover the OAuth 2.0 token endpoint from an OpenID Connect or OAuth metadata document at the given issuer URL. Returns an empty string if discovery fails; the caller should fall back to a manually configured TokenURL.

Only https:// issuer URLs are accepted to avoid SSRF against plaintext endpoints.

Types

type AuthCodeConfig

type AuthCodeConfig struct {
	// TokenURL is the OAuth 2.0 token endpoint.
	TokenURL string
	// ClientID is the OAuth client identifier.
	ClientID string
	// RedirectURI is the callback URI registered with the authorization server.
	RedirectURI string
	// Code is the authorization code received from the authorization server callback.
	Code string
	// PKCEVerifier is the PKCE code verifier generated before the authorization request.
	PKCEVerifier string
	// Timeout is the HTTP timeout for the token request.
	Timeout time.Duration
}

AuthCodeConfig holds parameters for an authorization code + PKCE token exchange.

type ClientCredentialsConfig

type ClientCredentialsConfig struct {
	// TokenURL is the OAuth 2.0 token endpoint (e.g. https://auth.example.com/oauth/token).
	TokenURL string
	// ClientID is the OAuth client identifier.
	ClientID string
	// ClientSecret is the OAuth client secret.
	ClientSecret string
	// Scopes is the list of scopes to request.
	Scopes []string
	// Audience is the target API identifier (optional; used by Auth0, Okta, etc.).
	Audience string
	// Timeout is the HTTP timeout for the token request (default: 15s).
	Timeout time.Duration
}

ClientCredentialsConfig holds the parameters for a client credentials grant.

type PKCEFlowConfig

type PKCEFlowConfig struct {
	// AuthURL is the OAuth 2.0 authorization endpoint
	// (e.g. https://auth.example.com/authorize).
	AuthURL string

	// TokenURL is the OAuth 2.0 token endpoint where the authorization code
	// will be exchanged for an access token.
	TokenURL string

	// ClientID is the OAuth client identifier registered with the authorization server.
	ClientID string

	// RedirectPort is the local TCP port the callback listener binds to on
	// 127.0.0.1. The full redirect URI is http://127.0.0.1:<port>/callback.
	// Defaults to 9876 when zero.
	RedirectPort int

	// Scopes is the list of scopes to request.
	Scopes []string

	// Audience is the optional API audience identifier (Auth0/Okta-style).
	Audience string

	// OpenBrowser controls whether the CLI attempts to open the system browser
	// automatically. When false, the user is expected to manually open the
	// printed authorization URL.
	OpenBrowser bool

	// Logger receives status messages during the flow (URL prompts, success
	// confirmations). Pass io.Discard for silent operation. May be nil.
	Logger func(format string, args ...interface{})

	// CallbackTimeout is the maximum time to wait for the redirect callback.
	// Defaults to 5 minutes when zero.
	CallbackTimeout time.Duration
}

PKCEFlowConfig holds parameters for the interactive PKCE authorization code flow.

type PKCEParams

type PKCEParams struct {
	// Verifier is the random secret used to derive the challenge.
	Verifier string
	// Challenge is the S256-encoded value sent to the authorization endpoint.
	Challenge string
}

PKCEParams holds the PKCE code verifier and challenge for an authorization code flow.

func GeneratePKCE

func GeneratePKCE() (*PKCEParams, error)

GeneratePKCE generates a cryptographically secure PKCE verifier and S256 challenge.

type TokenResponse

type TokenResponse struct {
	AccessToken string `json:"access_token"`
	TokenType   string `json:"token_type"`
	ExpiresIn   int    `json:"expires_in"`
	Scope       string `json:"scope"`
}

TokenResponse holds the fields returned by an OAuth 2.0 token endpoint.

func ExchangeAuthCode

func ExchangeAuthCode(ctx context.Context, cfg AuthCodeConfig) (*TokenResponse, error)

ExchangeAuthCode exchanges an authorization code (plus PKCE verifier) for tokens.

The TokenURL must use HTTPS to prevent cleartext transmission of authorization codes. HTTP token endpoints are rejected with an explicit error.

func FetchClientCredentialsToken

func FetchClientCredentialsToken(ctx context.Context, cfg ClientCredentialsConfig) (*TokenResponse, error)

FetchClientCredentialsToken performs an OAuth 2.0 client credentials grant and returns a bearer token ready to use in Authorization headers.

The TokenURL must use HTTPS to prevent cleartext transmission of client credentials. HTTP token endpoints are rejected with an explicit error.

func PerformPKCEFlow

func PerformPKCEFlow(ctx context.Context, cfg PKCEFlowConfig) (*TokenResponse, error)

PerformPKCEFlow runs an interactive OAuth 2.0 authorization code flow with PKCE. It generates a verifier/challenge, builds an authorization URL, optionally opens the user's browser, listens for the redirect callback, and exchanges the returned code for tokens.

Both AuthURL and TokenURL must use HTTPS. The function blocks until the user completes the consent flow or CallbackTimeout elapses.