OAuth authorization lifecycle contracts and lightweight state logic. More...

#include <algorithm>
#include <cctype>
#include <chrono>
#include <cstdint>
#include <iomanip>
#include <memory>
#include <optional>
#include <sstream>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "cxxmcp/auth/constant_time.hpp"
#include "cxxmcp/auth/metadata.hpp"
#include "cxxmcp/auth/pkce.hpp"
#include "cxxmcp/auth/registration.hpp"
#include "cxxmcp/auth/token.hpp"
#include "cxxmcp/auth/types.hpp"
#include "cxxmcp/auth/www_auth.hpp"
#include "cxxmcp/core/result.hpp"

Classes
struct	mcp::auth::CredentialKey
	Stable key for OAuth credential storage. More...

struct	mcp::auth::StoredCredentials
	Stored OAuth credentials and granted scope bookkeeping. More...

class	mcp::auth::CredentialStore
	Application-provided OAuth credential persistence boundary. More...

class	mcp::auth::InMemoryCredentialStore
	Non-persistent credential store for tests and simple clients. More...

struct	mcp::auth::StoredAuthorizationState
	Stored one-time authorization state for OAuth code + PKCE flows. More...

class	mcp::auth::StateStore
	Application-provided authorization state persistence boundary. More...

class	mcp::auth::InMemoryStateStore
	Non-persistent authorization state store. More...

struct	mcp::auth::AuthorizationUrlRequest
	Authorization URL construction input. More...

struct	mcp::auth::AuthorizationUrlResult
	Authorization URL plus the state that must be stored for callback. More...

struct	mcp::auth::TokenExchangeRequest
	Token endpoint exchange input. Implementations perform network I/O. More...

struct	mcp::auth::TokenRefreshRequest
	Token endpoint refresh input. Implementations perform network I/O. More...

struct	mcp::auth::TokenClientCredentialsRequest
	Token endpoint client credentials input (SEP-1046). More...

class	mcp::auth::OAuthTokenEndpoint
	Token exchange and refresh network boundary. More...

struct	mcp::auth::ScopeUpgradeConfig
	Scope upgrade policy used after insufficient_scope challenges. More...

struct	mcp::auth::AuthResponseDecision
	Auth response decision derived from status and WWW-Authenticate. More...

struct	mcp::auth::OAuthRefreshRetryResult
	Result of evaluating an HTTP auth response for one-shot retry. More...

struct	mcp::auth::MetadataFetchRequest
	Metadata fetch request routed through application/transport code. More...

class	mcp::auth::OAuthMetadataEndpoint
	OAuth metadata network boundary. More...

struct	mcp::auth::MetadataDiscoveryPlan
	Candidate metadata URLs for an MCP Streamable HTTP resource. More...

struct	mcp::auth::MetadataDiscoveryOptions
	Options for metadata discovery execution. More...

struct	mcp::auth::ScopeSelectionContext
	Inputs for RMCP-style authorization scope selection. More...

class	mcp::auth::MetadataDiscoveryExecutor
	Execute protected-resource and authorization-server discovery. More...

struct	mcp::auth::OAuthSession
	User-facing authorization session for an active code flow. More...

struct	mcp::auth::AuthorizationSessionRequest
	Full client-id selection plus authorization URL request. More...

class	mcp::auth::AuthorizationManager
	Transport-neutral OAuth authorization lifecycle manager. More...

Enumerations
enum class	mcp::auth::OAuthErrorCode { kInvalidRequest = 1 , kAuthorizationRequired = 2 , kAuthorizationPending = 3 , kTokenExchangeUnavailable = 4 , kTokenExchangeFailed = 5 , kTokenRefreshFailed = 6 , kInsufficientScope = 7 , kMetadataDiscoveryFailed = 8 , kClientRegistrationUnavailable = 9 , kClientRegistrationFailed = 10 , kClientMetadataDocumentUnsupported = 11 , kClientMetadataDocumentInvalid = 12 , kClientCredentialsFailed = 13 }
	OAuth lifecycle error codes used inside the stable "auth" category.

enum class	mcp::auth::OAuthLifecycleState { kUnauthorized , kAuthorizationPending , kAuthorized }
	Runtime state for the interactive OAuth lifecycle.

enum class	mcp::auth::AuthResponseAction { kProceed , kAuthorizationRequired , kScopeUpgradeRequired }
	Parsed client action from HTTP auth response metadata.

Functions
core::Error	mcp::auth::make_oauth_error (OAuthErrorCode code, std::string message, std::string detail={})
	Build an auth-category lifecycle error.

std::string	mcp::auth::detail::oauth_url_encode (std::string_view value)

std::string	mcp::auth::detail::join_scopes (const ScopeList &scopes)

ScopeList	mcp::auth::detail::split_scopes (std::string_view scopes)

std::string	mcp::auth::detail::pkce_method_name (PkceCodeChallengeMethod method)

void	mcp::auth::detail::append_query_param (std::string *url, const std::string &name, const std::string &value)

bool	mcp::auth::detail::has_scope (const ScopeList &scopes, const std::string &scope)

void	mcp::auth::detail::append_unique (StringList *values, std::string value)

std::string	mcp::auth::detail::strip_query_and_fragment (std::string url)

std::string	mcp::auth::detail::origin_from_url (std::string_view url)

std::string	mcp::auth::detail::path_from_url (std::string_view url)

bool	mcp::auth::detail::url_has_fragment (std::string_view url)

std::string	mcp::auth::detail::url_scheme (std::string_view url)

bool	mcp::auth::detail::url_has_userinfo (std::string_view url)

std::string	mcp::auth::detail::url_host (std::string_view url)

bool	mcp::auth::detail::url_uses_https (std::string_view url)

bool	mcp::auth::detail::url_uses_loopback_http (std::string_view url)

bool	mcp::auth::detail::redirect_uri_is_secure (std::string_view url)

bool	mcp::auth::detail::metadata_discovery_url_is_safe (std::string_view url)

std::string	mcp::auth::detail::trim_leading_slash (std::string value)

std::optional< std::string >	mcp::auth::detail::header_value (const HeaderMap &headers, std::string_view name)

StringList	mcp::auth::build_protected_resource_metadata_urls (const std::string &resource_url, std::optional< std::string > challenged_resource_metadata_url=std::nullopt)
	Build RFC 9728 protected-resource metadata candidates.

StringList	mcp::auth::build_authorization_server_metadata_urls (const std::string &issuer_or_base_url)
	Build RFC 8414 authorization-server metadata candidates.

MetadataDiscoveryPlan	mcp::auth::build_metadata_discovery_plan (const std::string &resource_url, const AuthResponseDecision &decision=AuthResponseDecision{})
	Build the metadata discovery plan from a resource URL and auth hint.

ScopeList	mcp::auth::select_authorization_scopes (const ScopeSelectionContext &context)
	Select scopes using the RMCP priority order.

void	mcp::auth::add_offline_access_if_supported (ScopeList &scopes, const AuthorizationServerMetadata &metadata)
	SEP-2207: auto-append `offline_access` when the authorization server advertises it in `scopes_supported` and it is not already present.

core::Result< core::Unit >	mcp::auth::validate_client_credentials_metadata (const AuthorizationServerMetadata &metadata, std::string_view token_endpoint_auth_method="client_secret_post")
	SEP-1046: validate that the authorization server supports client credentials authentication.

core::Result< AuthorizationUrlResult >	mcp::auth::build_authorization_url (const AuthorizationUrlRequest &request)
	Build an OAuth authorization URL without performing network I/O.

core::Result< AuthResponseDecision >	mcp::auth::analyze_auth_response (const HttpResponseMetadata &response)
	Analyze status and WWW-Authenticate metadata for OAuth next action.

Variables
constexpr std::chrono::seconds	mcp::auth::kDefaultAuthorizationStateTtl {60}

Detailed Description

OAuth authorization lifecycle contracts and lightweight state logic.

Function Documentation

◆ build_protected_resource_metadata_urls()

StringList mcp::auth::build_protected_resource_metadata_urls	(	const std::string &	resource_url,
		std::optional< std::string >	challenged_resource_metadata_url = `std::nullopt`
	)

inline

Build RFC 9728 protected-resource metadata candidates.

A resource_metadata value from WWW-Authenticate is tried first, then well-known paths derived from the resource URL. This mirrors the RMCP discovery order while keeping actual HTTP I/O outside the SDK model layer.

◆ select_authorization_scopes()

ScopeList mcp::auth::select_authorization_scopes ( const ScopeSelectionContext & context )

inline

Select scopes using the RMCP priority order.

Order: WWW-Authenticate scope, protected-resource metadata, authorization-server metadata, then application defaults.

◆ validate_client_credentials_metadata()

core::Result< core::Unit > mcp::auth::validate_client_credentials_metadata	(	const AuthorizationServerMetadata &	metadata,
		std::string_view	token_endpoint_auth_method = `"client_secret_post"`
	)

inline

SEP-1046: validate that the authorization server supports client credentials authentication.

Checks metadata for the client credentials grant and the client_secret_post authentication method used by the built-in endpoint.

Classes

Enumerations

Functions

Variables

Detailed Description

Function Documentation

◆ build_protected_resource_metadata_urls()

◆ select_authorization_scopes()

◆ validate_client_credentials_metadata()