auth

Documentation

Index

• Variables
• type LoginState
• type Metadata
  • func (m Metadata) Validate() error
• type PKCEPair
• type SecretRefResolver
• type ServerConfig
  • func ServerConfigFromMCP(ctx context.Context, server aghconfig.MCPServer, ...) (ServerConfig, error)
  • func ServerConfigsFromMCP(ctx context.Context, servers []aghconfig.MCPServer, ...) ([]ServerConfig, error)
  • func (c ServerConfig) Validate() error
• type Service
  • func NewService(store TokenStore, opts ...ServiceOption) (*Service, error)
  • func (s *Service) BeginLogin(ctx context.Context, cfg ServerConfig, redirectURL string) (LoginState, error)
  • func (s *Service) Exchange(ctx context.Context, state LoginState, callbackURL string) (Status, error)
  • func (s *Service) Logout(ctx context.Context, cfg ServerConfig) (Status, error)
  • func (s *Service) Refresh(ctx context.Context, cfg ServerConfig) (Status, error)
  • func (s *Service) Status(ctx context.Context, cfg ServerConfig) (Status, error)
• type ServiceOption
  • func WithHTTPClient(client *http.Client) ServiceOption
  • func WithNow(now func() time.Time) ServiceOption
  • func WithRandom(random io.Reader) ServiceOption
• type Status
• type StatusValue
• type TokenRecord
• type TokenStore

Variables

var ErrTokenNotFound = errors.New("mcp auth: token not found")

ErrTokenNotFound reports missing persisted MCP auth state for one server.

Types

type LoginState

type LoginState struct {
	ServerName       string
	RedirectURL      string
	State            string
	Verifier         string
	AuthorizationURL string
	Metadata         Metadata
	Config           ServerConfig
}

LoginState holds the short-lived in-memory authorization flow state.

type Metadata

type Metadata struct {
	Issuer                        string   `json:"issuer,omitempty"`
	AuthorizationEndpoint         string   `json:"authorization_endpoint"`
	TokenEndpoint                 string   `json:"token_endpoint"`
	RevocationEndpoint            string   `json:"revocation_endpoint,omitempty"`
	CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported,omitempty"`
	ScopesSupported               []string `json:"scopes_supported,omitempty"`
}

Metadata is the OAuth authorization server metadata needed for PKCE flows.

func (Metadata) Validate

func (m Metadata) Validate() error

Validate checks OAuth metadata required by authorization code with PKCE.

type PKCEPair

type PKCEPair struct {
	Verifier  string
	Challenge string
	Method    string
}

PKCEPair holds the generated verifier and S256 code challenge. The verifier is secret and must not be logged.

type SecretRefResolver

type SecretRefResolver func(ctx context.Context, ref string) (string, error)

SecretRefResolver resolves configured env: or vault: refs to plaintext for OAuth token requests.

type ServerConfig

type ServerConfig struct {
	ServerName       string
	Transport        string
	RemoteURL        string
	Type             string
	IssuerURL        string
	MetadataURL      string
	AuthorizationURL string
	TokenURL         string
	RevocationURL    string
	ClientID         string
	ClientSecret     string
	ClientSecretRef  string
	Scopes           []string
}

ServerConfig is the token-free auth configuration used by the OAuth service.

func ServerConfigFromMCP

func ServerConfigFromMCP(
	ctx context.Context,
	server aghconfig.MCPServer,
	resolveSecret SecretRefResolver,
) (ServerConfig, error)

ServerConfigFromMCP converts a config MCP server into token-free auth service input. resolveSecret receives the configured client_secret_ref and returns the actual secret value when present.

func ServerConfigsFromMCP

func ServerConfigsFromMCP(
	ctx context.Context,
	servers []aghconfig.MCPServer,
	resolveSecret SecretRefResolver,
) ([]ServerConfig, error)

ServerConfigsFromMCP returns auth service configs for every auth-enabled MCP server in the supplied list.

func (ServerConfig) Validate

func (c ServerConfig) Validate() error

Validate checks whether a server config is sufficient for auth actions.

type Service

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

Service executes OAuth 2.1 authorization-code flows for remote MCP servers.

func NewService

func NewService(store TokenStore, opts ...ServiceOption) (*Service, error)

NewService constructs an MCP auth service.

func (*Service) BeginLogin

func (s *Service) BeginLogin(
	ctx context.Context,
	cfg ServerConfig,
	redirectURL string,
) (LoginState, error)

BeginLogin discovers metadata, generates PKCE state, and returns the URL the operator must open. The returned verifier is sensitive and must stay in memory.

func (*Service) Exchange

func (s *Service) Exchange(ctx context.Context, state LoginState, callbackURL string) (Status, error)

Exchange validates the OAuth callback and stores the token response.

func (*Service) Logout

func (s *Service) Logout(ctx context.Context, cfg ServerConfig) (Status, error)

Logout revokes the refresh token when revocation metadata is configured, then deletes local durable token state.

func (*Service) Refresh

func (s *Service) Refresh(ctx context.Context, cfg ServerConfig) (Status, error)

Refresh refreshes a persisted token and updates durable storage.

func (*Service) Status

func (s *Service) Status(ctx context.Context, cfg ServerConfig) (Status, error)

Status returns redacted durable auth state for one server.

type ServiceOption

type ServiceOption func(*Service)

ServiceOption configures the OAuth service.

func WithHTTPClient

func WithHTTPClient(client *http.Client) ServiceOption

WithHTTPClient overrides the HTTP client used for metadata and token calls.

func WithNow

func WithNow(now func() time.Time) ServiceOption

WithNow overrides the clock for tests.

func WithRandom

func WithRandom(random io.Reader) ServiceOption

WithRandom overrides the entropy source for tests.

type Status

type Status struct {
	ServerName       string      `json:"server_name"`
	Status           StatusValue `json:"status"`
	RemoteURL        string      `json:"remote_url,omitempty"`
	AuthType         string      `json:"auth_type,omitempty"`
	ClientID         string      `json:"client_id,omitempty"`
	Issuer           string      `json:"issuer,omitempty"`
	Scopes           []string    `json:"scopes,omitempty"`
	ExpiresAt        *time.Time  `json:"expires_at,omitempty"`
	UpdatedAt        *time.Time  `json:"updated_at,omitempty"`
	Refreshable      bool        `json:"refreshable"`
	TokenPresent     bool        `json:"token_present"`
	RevocationURL    string      `json:"revocation_url,omitempty"`
	Diagnostic       string      `json:"diagnostic,omitempty"`
	AuthorizationURL string      `json:"authorization_url,omitempty"`
}

Status is the token-redacted state used by CLI and settings APIs.

type StatusValue

type StatusValue string

StatusValue is the redacted operator-facing authentication state.

const (
	StatusUnconfigured  StatusValue = "unconfigured"
	StatusNeedsLogin    StatusValue = "needs_login"
	StatusAuthenticated StatusValue = "authenticated"
	StatusExpired       StatusValue = "expired"
	StatusInvalid       StatusValue = "invalid"
)

type TokenRecord

type TokenRecord struct {
	ServerName   string
	Issuer       string
	ClientID     string
	Scopes       []string
	AccessToken  string
	RefreshToken string
	TokenType    string
	ExpiresAt    time.Time
	ObtainedAt   time.Time
	UpdatedAt    time.Time
}

TokenRecord is the durable token-store row. It must never be rendered directly in public API or CLI output.

type TokenStore

type TokenStore interface {
	SaveMCPAuthToken(ctx context.Context, token TokenRecord) error
	GetMCPAuthToken(ctx context.Context, serverName string) (TokenRecord, error)
	ListMCPAuthTokens(ctx context.Context) ([]TokenRecord, error)
	DeleteMCPAuthToken(ctx context.Context, serverName string) error
}

TokenStore persists OAuth token material behind a narrow boundary.