Bearer auth demo + docs; CTest wiring; extend server tests; ASCII OAuth 2.1 flows

Author: rianna-parla

CMakeLists.txt

@@ -51,6 +51,7 @@ add_library(mcp_cpp STATIC
     src/mcp/Server.cpp
     src/mcp/auth/OAuthClient.cpp
     src/mcp/auth/OAuth2ClientCredentialsAuth.cpp
+    src/mcp/auth/ServerAuth.cpp
 )
 add_library(mcp::cpp ALIAS mcp_cpp)
 

docs/api/server.md

@@ -123,6 +123,102 @@ Notes:
 - Client parsing: handled in [src/mcp/Client.cpp](../../src/mcp/Client.cpp) `parseServerCapabilities()`.
 - Tests: [tests/test_capabilities_logging.cpp](../../tests/test_capabilities_logging.cpp).
 
+## Server-side Bearer authentication (HTTP acceptor)
+
+Header: [include/mcp/auth/ServerAuth.hpp](../../include/mcp/auth/ServerAuth.hpp)
+
+The HTTP server acceptor can enforce Bearer authentication for incoming POSTs to `rpcPath` and `notifyPath` when explicitly enabled.
+
+- API
+  - `void HTTPServer::SetBearerAuth(mcp::auth::ITokenVerifier& verifier, const mcp::auth::RequireBearerTokenOptions& opts)`
+  - `mcp::auth::ITokenVerifier` verifies the bearer token and populates `TokenInfo` (scopes, expiration, extra).
+  - `mcp::auth::RequireBearerTokenOptions` controls enforcement:
+    - `resourceMetadataUrl`: included in `WWW-Authenticate: Bearer resource_metadata=<url>` on 401/403.
+    - `requiredScopes`: all listed scopes must be present; otherwise 403.
+
+- Behavior
+  - Authorization header must be `Authorization: Bearer <token>` (scheme case-insensitive).
+  - On missing/invalid token → 401 Unauthorized.
+  - On missing expiration or expired token → 401 Unauthorized.
+  - On insufficient scope → 403 Forbidden.
+  - When `resourceMetadataUrl` is provided, responses include `WWW-Authenticate: Bearer resource_metadata=<url>`.
+  - On success, the verified token is available during handler execution via `mcp::auth::currentTokenInfo()`.
+  - When `SetBearerAuth(...)` is not called, no authentication is enforced (backward compatible).
+
+- Example (bridge to Server::HandleJSONRPC)
+
+```cpp
+#include "mcp/HTTPServer.hpp"
+#include "mcp/Server.h"
+#include "mcp/auth/ServerAuth.hpp"
+
+mcp::ServerFactory sf;
+auto server = sf.CreateServer({"Demo","1.0.0"});
+
+mcp::HTTPServerFactory hf;
+auto acceptor = hf.CreateTransportAcceptor("http://127.0.0.1:9443");
+
+struct MyVerifier : mcp::auth::ITokenVerifier {
+  bool Verify(const std::string& token, mcp::auth::TokenInfo& out, std::string& err) override {
+    if (token != "demo") { err = "invalid token"; return false; }
+    out.scopes = {"tools:invoke"};
+    out.expiration = std::chrono::system_clock::now() + std::chrono::minutes(5);
+    return true;
+  }
+} verifier;
+
+mcp::auth::RequireBearerTokenOptions opts;
+opts.resourceMetadataUrl = "https://auth.example.com/rs";
+opts.requiredScopes = {"tools:invoke"};
+
+auto* http = dynamic_cast<mcp::HTTPServer*>(acceptor.get());
+if (http) { http->SetBearerAuth(verifier, opts); }
+
+acceptor->SetRequestHandler([&server](const mcp::JSONRPCRequest& req){ return server->HandleJSONRPC(req); });
+acceptor->Start().get();
+```
+
+- Accessing token info in handlers
+  - Inside server/tool handlers, use `mcp::auth::currentTokenInfo()` to read the request’s token metadata.
+
+- Demo (run_demo.sh)
+  - The demo wiring supports environment toggles to exercise this flow end-to-end:
+    - `MCP_HTTP_REQUIRE_BEARER=1` — enable server-side Bearer for the HTTP demo.
+    - `MCP_HTTP_RESOURCE_METADATA_URL=https://auth.example.com/rs` — advertised in `WWW-Authenticate`.
+    - `MCP_HTTP_DEMO_TOKEN=demo` — client token to accept (demo verifier).
+    - `MCP_HTTP_DEMO_SCOPES=s1,s2` — scopes attached by the demo verifier (default `s1,s2`).
+    - `MCP_HTTP_REQUIRED_SCOPES=s1` — required scopes to enforce (optional).
+  - The CTest target `HTTPDemo.BearerAuth` first verifies an unauthorized probe (expects 401 + `WWW-Authenticate`) and then runs the client with a bearer token to observe a successful 200 path.
+
+### Flow (ASCII)
+
+```
++---------+                                            +------------------+
+| Client  |                                            | HTTPServer       |
++---------+                                            +------------------+
+    |  POST /mcp/rpc (no Authorization)                         |
+    |---------------------------------------------------------->|
+    |                                                           |
+    |<----------------------------------------------------------|
+    | 401 Unauthorized                                          |
+    | WWW-Authenticate: Bearer resource_metadata=<url>          |
+    |                                                           |
+    |  POST /mcp/rpc                                            |
+    |(Authorization: Bearer <token with bad scope>)             |
+    |---------------------------------------------------------->|
+    |                                                           |
+    |<----------------------------------------------------------|
+    | 403 Forbidden                                             |
+    | WWW-Authenticate: Bearer resource_metadata=<url>          |
+    |                                                           |
+    |  POST /mcp/rpc                                            |
+    |(Authorization: Bearer <valid token>)                      |
+    |---------------------------------------------------------->|
+    |                                                           |
+    |<----------------------------------------------------------|
+    | 200 OK (JSON-RPC response)                                |
+```
+
 ## Tools
 - void RegisterTool(const std::string& name, ToolHandler handler)
 - void RegisterTool(const Tool& tool, ToolHandler handler)

docs/api/transport.md

@@ -174,6 +174,45 @@ Notes:
 - Secrets are not logged. Prefer environment variables or secure config handling in your process to populate `clientSecret`.
 - The token endpoint response must include `access_token` and may include `expires_in` (seconds). When absent, a default 1‑hour lifetime is assumed.
 
+##### Flow diagrams (ASCII)
+
+- Static Bearer header
+
+```
++-----------+                                      +------------------+
+| Client    |                                      | Resource Server  |
++-----------+                                      +------------------+
+    | Build HTTP request (JSON-RPC over HTTP)
+    | Authorization: Bearer <token>
+    |---------------------------------------------->
+                                                   | POST /mcp/rpc
+                                                   |
+                                                   | 200 OK / Error
+    |<----------------------------------------------
+```
+
+- OAuth 2.1 Client Credentials grant (token fetch + use)
+
+```
++-----------+               +--------------+                 +------------------+
+| Client    |               | Auth Server  |                 | Resource Server  |
++-----------+               +--------------+                 +------------------+
+    | POST /oauth2/token 
+    | (grant_type=client_credentials, 
+    |  client_id, client_secret, scope?)
+    |-------------------------->|
+                                | 
+                                | 200 OK {access_token, expires_in, ...}
+                                |<---------------------------------|
+    | Build HTTP request (JSON-RPC over HTTP)                      |
+    | Authorization: Bearer <access_token>                         |
+    |------------------------------------------------------------->|
+                                                                   | POST /mcp/rpc
+                                                                   |
+                                                                   | 200 OK / Error
+    |<-------------------------------------------------------------|
+```
+
 #### Code-based authentication injection (IAuth)
 
 You can also inject an auth provider programmatically using `IAuth`.

examples/mcp_client/main.cpp

@@ -95,6 +95,12 @@ int main(int argc, char** argv) {
         HTTPTransportFactory f;
         std::string url = getArgValue(argc, argv, "--url").value_or("http://127.0.0.1:9443");
         std::string cfg = parseHttpUrlToConfig(url);
+        if (auto extra = getArgValue(argc, argv, "--httpcfg"); extra.has_value()) {
+            if (!extra->empty()) {
+                if (!cfg.empty() && cfg.back() != ';') { cfg += "; "; }
+                cfg += *extra;
+            }
+        }
         transport = f.CreateTransport(cfg);
     } else {
         LOG_ERROR("Unknown --transport option: {} (expected stdio|shm|http)", transportKind);

examples/mcp_server/main.cpp

@@ -11,6 +11,7 @@
 #include "mcp/SharedMemoryTransport.hpp"
 #include "mcp/HTTPServer.hpp"
 #include "mcp/Protocol.h"
+#include "mcp/auth/ServerAuth.hpp"
 #include <iostream>
 #include <cstddef>
 #include <chrono>
@@ -139,6 +140,69 @@ int main(int argc, char** argv) {
         LOG_INFO("HTTPServer listening at: {} (rpcPath=/mcp/rpc, notifyPath=/mcp/notify)", listen);
         HTTPServerFactory hf;
         auto acceptor = hf.CreateTransportAcceptor(listen);
+
+        // Optional: Configure server-side Bearer auth for demo via environment variables
+        // MCP_HTTP_REQUIRE_BEARER=1 enables; MCP_HTTP_DEMO_TOKEN sets accepted token; 
+        // MCP_HTTP_RESOURCE_METADATA_URL sets metadata URL; MCP_HTTP_REQUIRED_SCOPES is comma-separated list (e.g., "s1,s2").
+        {
+            std::string req = GetEnvOrDefault("MCP_HTTP_REQUIRE_BEARER", "0");
+            if (req == std::string("1")) {
+                // Downcast to HTTPServer to access SetBearerAuth
+                auto* httpSrv = dynamic_cast<HTTPServer*>(acceptor.get());
+                if (httpSrv != nullptr) {
+                    struct DemoTokenVerifier : public mcp::auth::ITokenVerifier {
+                        std::string expected;
+                        std::vector<std::string> demoScopes;
+                        bool Verify(const std::string& token, mcp::auth::TokenInfo& outInfo, std::string& errorMessage) override {
+                            if (token != expected) {
+                                errorMessage = std::string("invalid token");
+                                return false;
+                            }
+                            outInfo.scopes = demoScopes;
+                            outInfo.expiration = std::chrono::system_clock::now() + std::chrono::minutes(5);
+                            return true;
+                        }
+                    };
+                    static DemoTokenVerifier verifier;
+                    verifier.expected = GetEnvOrDefault("MCP_HTTP_DEMO_TOKEN", "demo");
+                    // Default demo scopes allow common checks; adjustable via MCP_HTTP_DEMO_SCOPES
+                    std::string ds = GetEnvOrDefault("MCP_HTTP_DEMO_SCOPES", "s1,s2");
+                    verifier.demoScopes.clear();
+                    {
+                        std::size_t start = 0;
+                        while (start <= ds.size()) {
+                            std::size_t comma = ds.find(',', start);
+                            std::string item = (comma == std::string::npos) ? ds.substr(start) : ds.substr(start, comma - start);
+                            if (!item.empty()) { verifier.demoScopes.push_back(item); }
+                            if (comma == std::string::npos) { break; }
+                            start = comma + 1;
+                        }
+                    }
+                    mcp::auth::RequireBearerTokenOptions aopts;
+                    aopts.resourceMetadataUrl = GetEnvOrDefault("MCP_HTTP_RESOURCE_METADATA_URL", "");
+                    {
+                        std::string rs = GetEnvOrDefault("MCP_HTTP_REQUIRED_SCOPES", "");
+                        aopts.requiredScopes.clear();
+                        if (!rs.empty()) {
+                            std::size_t start = 0;
+                            while (start <= rs.size()) {
+                                std::size_t comma = rs.find(',', start);
+                                std::string item = (comma == std::string::npos) ? rs.substr(start) : rs.substr(start, comma - start);
+                                if (!item.empty()) { aopts.requiredScopes.push_back(item); }
+                                if (comma == std::string::npos) { break; }
+                                start = comma + 1;
+                            }
+                        }
+                    }
+                    httpSrv->SetBearerAuth(verifier, aopts);
+                    LOG_INFO("HTTP Bearer auth enabled for demo (requiredScopes={} resource_metadata={})",
+                             aopts.requiredScopes.size(), aopts.resourceMetadataUrl);
+                } else {
+                    LOG_WARN("HTTP Bearer auth requested but acceptor is not HTTPServer");
+                }
+            }
+        }
+        
         acceptor->SetRequestHandler([&server](const JSONRPCRequest& req) {
             return server->HandleJSONRPC(req);
         });

include/mcp/HTTPServer.hpp

@@ -13,6 +13,7 @@
 #include <memory>
 #include "mcp/Transport.h"
 #include "mcp/JSONRPCTypes.h"
+#include "mcp/auth/ServerAuth.hpp"
 
 namespace mcp {
 
@@ -78,6 +79,23 @@ namespace mcp {
     //==========================================================================================================
     void SetErrorHandler(ITransport::ErrorHandler handler) override;
 
+    //==========================================================================================================
+    // SetBearerAuth
+    // Purpose: Configure optional server-side Bearer authentication for HTTP requests.
+    // Notes:
+    //   - Non-owning reference to an ITokenVerifier implementation; caller must ensure lifetime spans server use.
+    //   - When configured, incoming requests to rpcPath/notifyPath must include a valid
+    //     Authorization: Bearer <token> header. On failure, the server responds with 401/403 and
+    //     includes a WWW-Authenticate: Bearer resource_metadata=<url> header when a URL is provided.
+    //   - On success, the verified TokenInfo is made available for the duration of request handling
+    //     via mcp::auth::CurrentTokenInfo().
+    // Args:
+    //   verifier: Token verifier to validate bearer tokens.
+    //   opts: Required scopes and resource metadata URL for WWW-Authenticate.
+    //==========================================================================================================
+    void SetBearerAuth(mcp::auth::ITokenVerifier& verifier,
+                       const mcp::auth::RequireBearerTokenOptions& opts);
+
 private:
     class Impl;
     std::unique_ptr<Impl> pImpl;

include/mcp/auth/ServerAuth.hpp

@@ -0,0 +1,99 @@
+//==========================================================================================================
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2025 Vinny Parla
+// File: ServerAuth.hpp
+// Purpose: Server-side bearer authentication interfaces and helpers for HTTP server
+//==========================================================================================================
+
+#pragma once
+
+#include <string>
+#include <vector>
+#include <memory>
+#include <unordered_map>
+#include <chrono>
+
+namespace mcp::auth {
+
+//==========================================================================================================
+// TokenInfo
+// Purpose: Information extracted from a bearer token (scopes, expiration, and optional extra fields).
+//==========================================================================================================
+struct TokenInfo {
+    std::vector<std::string> scopes;
+    std::chrono::system_clock::time_point expiration;
+    std::unordered_map<std::string, std::string> extra;
+};
+
+//==========================================================================================================
+// ITokenVerifier
+// Purpose: Interface to validate a bearer token and populate TokenInfo when valid.
+// Returns: true on success (TokenInfo populated); false on failure (set errorMessage).
+//==========================================================================================================
+class ITokenVerifier {
+public:
+    virtual ~ITokenVerifier() = default;
+    virtual bool Verify(const std::string& token, TokenInfo& outInfo, std::string& errorMessage) = 0;
+};
+
+//==========================================================================================================
+// RequireBearerTokenOptions
+// Purpose: Options controlling server-side bearer enforcement and resource metadata advertisement.
+// Fields:
+//   resourceMetadataUrl: URL to include in WWW-Authenticate header when returning 401/403.
+//   requiredScopes: All listed scopes must be present in the token.
+//==========================================================================================================
+struct RequireBearerTokenOptions {
+    std::string resourceMetadataUrl;
+    std::vector<std::string> requiredScopes;
+};
+
+//==========================================================================================================
+// BearerCheckResult
+// Purpose: Result of checking a bearer Authorization header.
+// Fields:
+//   ok: True if authorization passed.
+//   httpStatus: HTTP status to use on failure (401 or 403).
+//   errorMessage: Error message to include in payload.
+//   includeWWWAuthenticate: Whether the caller should include a WWW-Authenticate header.
+//==========================================================================================================
+struct BearerCheckResult {
+    bool ok{false};
+    int httpStatus{401};
+    std::string errorMessage;
+    bool includeWWWAuthenticate{false};
+};
+
+//==========================================================================================================
+// CheckBearerAuth
+// Purpose: Validate Authorization header using the supplied verifier and options.
+// Args:
+//   authHeader: Value of the Authorization header (may be empty).
+//   verifier: Token verifier (must not be null if enforcement is enabled).
+//   opts: Enforcement options (required scopes and resource metadata URL).
+//   outInfo: Populated on success with token information.
+// Returns:
+//   BearerCheckResult indicating success or failure details.
+//==========================================================================================================
+BearerCheckResult CheckBearerAuth(
+    const std::string& authHeader,
+    ITokenVerifier& verifier,
+    const RequireBearerTokenOptions& opts,
+    TokenInfo& outInfo);
+
+//==========================================================================================================
+// Per-request TokenInfo context accessors
+// Purpose: Provide access to the current request's TokenInfo for server handlers.
+//==========================================================================================================
+const TokenInfo* CurrentTokenInfo();
+
+// RAII helper: sets the current TokenInfo for the lifetime of this object, then clears.
+class TokenInfoScope {
+public:
+    explicit TokenInfoScope(const TokenInfo* info);
+    ~TokenInfoScope();
+private:
+    const TokenInfo* prev{nullptr};
+};
+
+} // namespace mcp::auth