client_orchestrator.hpp

Go to the documentation of this file.

// Copyright (c) 2025 [caomengxuan666]
 
#pragma once
 
#include <chrono>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <utility>
#include <vector>
 
#include "cxxmcp/auth/http_metadata_endpoint.hpp"
#include "cxxmcp/auth/http_token_endpoint.hpp"
#include "cxxmcp/auth/lifecycle.hpp"
#include "cxxmcp/auth/pkce.hpp"
#include "cxxmcp/auth/token.hpp"
#include "cxxmcp/auth/types.hpp"
#include "cxxmcp/auth/www_auth.hpp"
#include "cxxmcp/core/result.hpp"
 
 
namespace mcp::auth {
 
class OAuthClientCallback {
 public:
  virtual ~OAuthClientCallback() = default;
 
  virtual core::Result<core::Unit> present_authorization_url(
      const std::string& url) = 0;
 
  virtual core::Result<std::pair<std::string, std::string>> wait_for_callback(
      std::chrono::seconds timeout) = 0;
};
 
struct OAuthClientOrchestratorConfig {
  std::string resource_url;
  std::string client_name = "MCP Client";
  ScopeList scopes;
  std::string redirect_uri;
  std::chrono::seconds callback_timeout{300};
  std::chrono::seconds refresh_skew{30};
  std::optional<std::string> client_id;
};
 
class OAuthClientOrchestrator {
 public:
  OAuthClientOrchestrator(
      OAuthClientOrchestratorConfig config, OAuthClientCallback& callback,
      OAuthMetadataEndpoint& metadata_endpoint,
      OAuthTokenEndpoint& token_endpoint, PkceGenerator& pkce_generator,
      OAuthClientRegistrationEndpoint* registration_endpoint = nullptr)
      : config_(std::move(config)),
        callback_(callback),
        metadata_endpoint_(metadata_endpoint),
        token_endpoint_(token_endpoint),
        pkce_generator_(pkce_generator),
        registration_endpoint_(registration_endpoint) {}
 
  core::Result<TokenSet> authorize() {
    // Step 1: Discover metadata.
    MetadataDiscoveryExecutor discovery(metadata_endpoint_);
    auto discovery_result = discovery.discover(config_.resource_url);
    if (!discovery_result.has_value()) {
      return core::unexpected(discovery_result.error());
    }
 
    metadata_ = discovery_result->authorization_server;
    protected_resource_ = discovery_result->protected_resource;
 
    if (!metadata_.has_value()) {
      return core::unexpected(make_oauth_error(
          OAuthErrorCode::kMetadataDiscoveryFailed,
          "no authorization server metadata discovered for resource",
          config_.resource_url));
    }
 
    // Step 2: Configure the AuthorizationManager.
    manager_.set_resource(config_.resource_url);
    manager_.set_authorization_server_metadata(*metadata_);
    manager_.set_token_endpoint(std::shared_ptr<OAuthTokenEndpoint>(
        &token_endpoint_, [](OAuthTokenEndpoint*) {}));
    if (registration_endpoint_ != nullptr) {
      manager_.set_client_registration_endpoint(
          std::shared_ptr<OAuthClientRegistrationEndpoint>(
              registration_endpoint_, [](OAuthClientRegistrationEndpoint*) {}));
    }
 
    // Step 3: Configure client ID (DCR or pre-configured).
    if (!config_.client_id.has_value()) {
      ClientIdConfigurationOptions client_options;
      client_options.client_name = config_.client_name;
      client_options.redirect_uri = config_.redirect_uri;
      client_options.scopes = config_.scopes;
 
      auto client_config =
          manager_.configure_client_for_authorization(client_options);
      if (!client_config.has_value()) {
        return core::unexpected(client_config.error());
      }
    } else {
      auto client_config = manager_.configure_client_id(
          *config_.client_id, config_.redirect_uri, config_.scopes);
      if (!client_config.has_value()) {
        return core::unexpected(client_config.error());
      }
    }
 
    // Step 4: Generate PKCE and state.
    auto pkce = pkce_generator_.create_s256();
    if (!pkce.has_value()) {
      return core::unexpected(pkce.error());
    }
 
    auto state = generate_state();
 
    // Step 5: Build authorization URL and present to user.
    AuthorizationSessionRequest session_request;
    session_request.client.client_name = config_.client_name;
    session_request.client.redirect_uri = manager_.client_config().redirect_uri;
    session_request.client.scopes = config_.scopes;
    session_request.pkce = *pkce;
    session_request.state = state;
    auto session_result = manager_.start_session(std::move(session_request));
    if (!session_result.has_value()) {
      return core::unexpected(session_result.error());
    }
 
    auto present_result = callback_.present_authorization_url(
        session_result->authorization_url());
    if (!present_result.has_value()) {
      return core::unexpected(present_result.error());
    }
 
    // Step 6: Wait for authorization code.
    auto callback_result =
        callback_.wait_for_callback(config_.callback_timeout);
    if (!callback_result.has_value()) {
      return core::unexpected(callback_result.error());
    }
 
    auto& [code, callback_state] = *callback_result;
 
    // Step 7: Exchange code for tokens.
    auto tokens = manager_.exchange_authorization_code(code, callback_state);
    if (!tokens.has_value()) {
      return core::unexpected(tokens.error());
    }
 
    return *tokens;
  }
 
  core::Result<std::string> get_access_token() {
    return manager_.get_access_token(config_.refresh_skew);
  }
 
  core::Result<OAuthRefreshRetryResult> handle_auth_response(
      const HttpResponseMetadata& response) {
    return manager_.refresh_after_unauthorized_response(response);
  }
 
  OAuthLifecycleState lifecycle_state() const {
    return manager_.lifecycle_state();
  }
 
  const OAuthClientConfig& client_config() const {
    return manager_.client_config();
  }
 
  const std::optional<AuthorizationServerMetadata>& metadata() const {
    return metadata_;
  }
 
  const std::optional<ProtectedResourceMetadata>& protected_resource_metadata()
      const {
    return protected_resource_;
  }
 
 private:
  static std::string generate_state() {
    // 16 random bytes as hex = 32 characters.
    // Uses the same approach as the lifecycle detail namespace.
    static constexpr char kHex[] = "0123456789abcdef";
    std::string result;
    result.reserve(32);
    // Use a simple PRNG seeded from system clock for state.
    // The state is verified by comparison, not by cryptographic strength,
    // but we still want reasonable uniqueness.
    auto seed = static_cast<std::uint64_t>(
        SystemClock::now().time_since_epoch().count());
    for (int i = 0; i < 32; ++i) {
      seed = seed * 6364136223846793005ULL + 1442695040888963407ULL;
      result.push_back(kHex[(seed >> 16) & 0xF]);
    }
    return result;
  }
 
  OAuthClientOrchestratorConfig config_;
  OAuthClientCallback& callback_;
  OAuthMetadataEndpoint& metadata_endpoint_;
  OAuthTokenEndpoint& token_endpoint_;
  PkceGenerator& pkce_generator_;
  OAuthClientRegistrationEndpoint* registration_endpoint_;
 
  AuthorizationManager manager_;
  std::optional<AuthorizationServerMetadata> metadata_;
  std::optional<ProtectedResourceMetadata> protected_resource_;
};
 
class OAuthClientFlowBuilder;
 
class OAuthClientFlow {
 public:
  OAuthClientFlow(const OAuthClientFlow&) = delete;
  OAuthClientFlow& operator=(const OAuthClientFlow&) = delete;
  OAuthClientFlow(OAuthClientFlow&&) = delete;
  OAuthClientFlow& operator=(OAuthClientFlow&&) = delete;
 
  core::Result<TokenSet> authorize() { return orchestrator_.authorize(); }
 
  core::Result<std::string> get_access_token() {
    return orchestrator_.get_access_token();
  }
 
  core::Result<OAuthRefreshRetryResult> handle_auth_response(
      const HttpResponseMetadata& response) {
    return orchestrator_.handle_auth_response(response);
  }
 
  OAuthLifecycleState lifecycle_state() const {
    return orchestrator_.lifecycle_state();
  }
 
  const OAuthClientConfig& client_config() const {
    return orchestrator_.client_config();
  }
 
  const std::optional<AuthorizationServerMetadata>& metadata() const {
    return orchestrator_.metadata();
  }
 
  const std::optional<ProtectedResourceMetadata>& protected_resource_metadata()
      const {
    return orchestrator_.protected_resource_metadata();
  }
 
 private:
  friend class OAuthClientFlowBuilder;
 
  OAuthClientFlow(
      OAuthClientOrchestratorConfig config,
      std::shared_ptr<OAuthClientCallback> callback,
      std::shared_ptr<OAuthMetadataEndpoint> metadata_endpoint,
      std::shared_ptr<OAuthTokenEndpoint> token_endpoint,
      std::shared_ptr<PkceGenerator> pkce_generator,
      std::shared_ptr<OAuthClientRegistrationEndpoint> registration_endpoint)
      : config_(std::move(config)),
        callback_(std::move(callback)),
        metadata_endpoint_(std::move(metadata_endpoint)),
        token_endpoint_(std::move(token_endpoint)),
        pkce_generator_(std::move(pkce_generator)),
        registration_endpoint_(std::move(registration_endpoint)),
        orchestrator_(
            config_, *callback_, *metadata_endpoint_, *token_endpoint_,
            *pkce_generator_,
            registration_endpoint_ ? registration_endpoint_.get() : nullptr) {}
 
  OAuthClientOrchestratorConfig config_;
  std::shared_ptr<OAuthClientCallback> callback_;
  std::shared_ptr<OAuthMetadataEndpoint> metadata_endpoint_;
  std::shared_ptr<OAuthTokenEndpoint> token_endpoint_;
  std::shared_ptr<PkceGenerator> pkce_generator_;
  std::shared_ptr<OAuthClientRegistrationEndpoint> registration_endpoint_;
  OAuthClientOrchestrator orchestrator_;
};
 
class OAuthClientFlowBuilder {
 public:
  OAuthClientFlowBuilder() = default;
 
  explicit OAuthClientFlowBuilder(std::string resource_url) {
    config_.resource_url = std::move(resource_url);
  }
 
  OAuthClientFlowBuilder& resource_url(std::string value) {
    config_.resource_url = std::move(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& client_name(std::string value) {
    config_.client_name = std::move(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& scopes(ScopeList value) {
    config_.scopes = std::move(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& redirect_uri(std::string value) {
    config_.redirect_uri = std::move(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& callback_timeout(std::chrono::seconds value) {
    config_.callback_timeout = value;
    return *this;
  }
 
  OAuthClientFlowBuilder& refresh_skew(std::chrono::seconds value) {
    config_.refresh_skew = value;
    return *this;
  }
 
  OAuthClientFlowBuilder& client_id(std::string value) {
    config_.client_id = std::move(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& callback(OAuthClientCallback& value) {
    callback_ = non_owning(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& callback(std::shared_ptr<OAuthClientCallback> value) {
    callback_ = std::move(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& metadata_endpoint(OAuthMetadataEndpoint& value) {
    metadata_endpoint_ = non_owning(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& metadata_endpoint(
      std::shared_ptr<OAuthMetadataEndpoint> value) {
    metadata_endpoint_ = std::move(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& token_endpoint(OAuthTokenEndpoint& value) {
    token_endpoint_ = non_owning(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& token_endpoint(
      std::shared_ptr<OAuthTokenEndpoint> value) {
    token_endpoint_ = std::move(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& http_endpoints(OAuthHttpGet get, OAuthHttpPost post) {
    metadata_endpoint_ =
        std::make_shared<HttpOAuthMetadataEndpoint>(std::move(get));
    token_endpoint_ = std::make_shared<HttpOAuthTokenEndpoint>(std::move(post));
    return *this;
  }
 
  OAuthClientFlowBuilder& pkce_generator(PkceGenerator& value) {
    pkce_generator_ = non_owning(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& pkce_generator(std::shared_ptr<PkceGenerator> value) {
    pkce_generator_ = std::move(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& registration_endpoint(
      OAuthClientRegistrationEndpoint& value) {
    registration_endpoint_ = non_owning(value);
    return *this;
  }
 
  OAuthClientFlowBuilder& registration_endpoint(
      std::shared_ptr<OAuthClientRegistrationEndpoint> value) {
    registration_endpoint_ = std::move(value);
    return *this;
  }
 
  core::Result<std::unique_ptr<OAuthClientFlow>> build() & {
    return std::move(*this).build();
  }
 
  core::Result<std::unique_ptr<OAuthClientFlow>> build() && {
    auto validation = validate();
    if (!validation.has_value()) {
      return core::unexpected(validation.error());
    }
 
    return std::unique_ptr<OAuthClientFlow>(new OAuthClientFlow(
        std::move(config_), std::move(callback_), std::move(metadata_endpoint_),
        std::move(token_endpoint_), std::move(pkce_generator_),
        std::move(registration_endpoint_)));
  }
 
 private:
  template <typename T>
  static std::shared_ptr<T> non_owning(T& value) {
    return std::shared_ptr<T>(&value, [](T*) {});
  }
 
  core::Result<core::Unit> validate() const {
    if (config_.resource_url.empty()) {
      return core::unexpected(make_oauth_error(OAuthErrorCode::kInvalidRequest,
                                               "resource_url is required"));
    }
    if (!callback_) {
      return core::unexpected(
          make_oauth_error(OAuthErrorCode::kInvalidRequest,
                           "OAuth client callback is required"));
    }
    if (!metadata_endpoint_) {
      return core::unexpected(
          make_oauth_error(OAuthErrorCode::kInvalidRequest,
                           "OAuth metadata endpoint is required"));
    }
    if (!token_endpoint_) {
      return core::unexpected(make_oauth_error(
          OAuthErrorCode::kInvalidRequest, "OAuth token endpoint is required"));
    }
    if (!pkce_generator_) {
      return core::unexpected(make_oauth_error(OAuthErrorCode::kInvalidRequest,
                                               "PKCE generator is required"));
    }
    return core::Unit{};
  }
 
  OAuthClientOrchestratorConfig config_;
  std::shared_ptr<OAuthClientCallback> callback_;
  std::shared_ptr<OAuthMetadataEndpoint> metadata_endpoint_;
  std::shared_ptr<OAuthTokenEndpoint> token_endpoint_;
  std::shared_ptr<PkceGenerator> pkce_generator_;
  std::shared_ptr<OAuthClientRegistrationEndpoint> registration_endpoint_;
};
 
inline OAuthClientFlowBuilder oauth_client_flow() {
  return OAuthClientFlowBuilder{};
}
 
inline OAuthClientFlowBuilder oauth_client_flow(std::string resource_url) {
  return OAuthClientFlowBuilder(std::move(resource_url));
}
 
}  // namespace mcp::auth