Add an OAuth module foundation with error codes and PKCE

.github/workflows/website-build.yml

@@ -50,6 +50,7 @@ jobs:
           -DSOURCEMETA_CORE_MCP:BOOL=OFF
           -DSOURCEMETA_CORE_HTTP:BOOL=OFF
           -DSOURCEMETA_CORE_JOSE:BOOL=OFF
+          -DSOURCEMETA_CORE_OAUTH:BOOL=OFF
           -DSOURCEMETA_CORE_SEMVER:BOOL=OFF
           -DSOURCEMETA_CORE_GZIP:BOOL=OFF
           -DSOURCEMETA_CORE_HTML:BOOL=OFF

.github/workflows/website-deploy.yml

@@ -60,6 +60,7 @@ jobs:
           -DSOURCEMETA_CORE_MCP:BOOL=OFF
           -DSOURCEMETA_CORE_HTTP:BOOL=OFF
           -DSOURCEMETA_CORE_JOSE:BOOL=OFF
+          -DSOURCEMETA_CORE_OAUTH:BOOL=OFF
           -DSOURCEMETA_CORE_SEMVER:BOOL=OFF
           -DSOURCEMETA_CORE_GZIP:BOOL=OFF
           -DSOURCEMETA_CORE_HTML:BOOL=OFF

CMakeLists.txt

@@ -37,6 +37,7 @@ option(SOURCEMETA_CORE_MCP "Build the Sourcemeta Core MCP library" ON)
 option(SOURCEMETA_CORE_HTTP "Build the Sourcemeta Core HTTP library" ON)
 option(SOURCEMETA_CORE_HTTP_USE_SYSTEM_CURL "Use system cURL for the Sourcemeta Core HTTP library" OFF)
 option(SOURCEMETA_CORE_JOSE "Build the Sourcemeta Core JOSE library" ON)
+option(SOURCEMETA_CORE_OAUTH "Build the Sourcemeta Core OAuth library" ON)
 option(SOURCEMETA_CORE_SEMVER "Build the Sourcemeta Core SemVer library" ON)
 option(SOURCEMETA_CORE_GZIP "Build the Sourcemeta Core GZIP library" ON)
 option(SOURCEMETA_CORE_HTML "Build the Sourcemeta Core HTML library" ON)
@@ -221,6 +222,10 @@ if(SOURCEMETA_CORE_JOSE)
   add_subdirectory(src/core/jose)
 endif()
 
+if(SOURCEMETA_CORE_OAUTH)
+  add_subdirectory(src/core/oauth)
+endif()
+
 if(SOURCEMETA_CORE_SEMVER)
   add_subdirectory(src/core/semver)
 endif()
@@ -389,6 +394,10 @@ if(SOURCEMETA_CORE_TESTS)
     add_subdirectory(test/jose)
   endif()
 
+  if(SOURCEMETA_CORE_OAUTH)
+    add_subdirectory(test/oauth)
+  endif()
+
   if(SOURCEMETA_CORE_SEMVER)
     add_subdirectory(test/semver)
   endif()

config.cmake.in

@@ -31,6 +31,7 @@ if(NOT SOURCEMETA_CORE_COMPONENTS)
   list(APPEND SOURCEMETA_CORE_COMPONENTS mcp)
   list(APPEND SOURCEMETA_CORE_COMPONENTS http)
   list(APPEND SOURCEMETA_CORE_COMPONENTS jose)
+  list(APPEND SOURCEMETA_CORE_COMPONENTS oauth)
   list(APPEND SOURCEMETA_CORE_COMPONENTS semver)
   list(APPEND SOURCEMETA_CORE_COMPONENTS gzip)
   list(APPEND SOURCEMETA_CORE_COMPONENTS html)
@@ -228,6 +229,26 @@ foreach(component ${SOURCEMETA_CORE_COMPONENTS})
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_json.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_crypto.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_jose.cmake")
+  elseif(component STREQUAL "oauth")
+    if(@SOURCEMETA_CORE_CRYPTO_USE_SYSTEM_OPENSSL@)
+      find_dependency(OpenSSL 3.0)
+    endif()
+    if(@SOURCEMETA_CORE_HTTP_USE_SYSTEM_CURL@)
+      find_dependency(CURL)
+    endif()
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_preprocessor.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_numeric.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_io.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_unicode.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_text.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_time.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_json.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_ip.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_uri.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_crypto.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_jose.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_http.cmake")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_oauth.cmake")
   elseif(component STREQUAL "semver")
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_preprocessor.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_text.cmake")

src/core/oauth/CMakeLists.txt

@@ -0,0 +1,20 @@
+sourcemeta_library(NAMESPACE sourcemeta PROJECT core NAME oauth
+  PRIVATE_HEADERS error.h profile.h pkce.h bearer.h
+  SOURCES oauth_error.cc oauth_pkce.cc oauth_bearer.cc oauth_syntax.h)
+
+target_link_libraries(sourcemeta_core_oauth
+  PUBLIC sourcemeta::core::json)
+target_link_libraries(sourcemeta_core_oauth
+  PUBLIC sourcemeta::core::crypto)
+target_link_libraries(sourcemeta_core_oauth
+  PUBLIC sourcemeta::core::jose)
+target_link_libraries(sourcemeta_core_oauth
+  PUBLIC sourcemeta::core::http)
+target_link_libraries(sourcemeta_core_oauth
+  PRIVATE sourcemeta::core::uri)
+target_link_libraries(sourcemeta_core_oauth
+  PRIVATE sourcemeta::core::text)
+
+if(SOURCEMETA_CORE_INSTALL)
+  sourcemeta_library_install(NAMESPACE sourcemeta PROJECT core NAME oauth)
+endif()

src/core/oauth/include/sourcemeta/core/oauth.h

@@ -0,0 +1,25 @@
+#ifndef SOURCEMETA_CORE_OAUTH_H_
+#define SOURCEMETA_CORE_OAUTH_H_
+
+#ifndef SOURCEMETA_CORE_OAUTH_EXPORT
+#include <sourcemeta/core/oauth_export.h>
+#endif
+
+// NOLINTBEGIN(misc-include-cleaner)
+#include <sourcemeta/core/oauth_bearer.h>
+#include <sourcemeta/core/oauth_error.h>
+#include <sourcemeta/core/oauth_pkce.h>
+#include <sourcemeta/core/oauth_profile.h>
+// NOLINTEND(misc-include-cleaner)
+
+/// @defgroup oauth OAuth
+/// @brief A standards-driven implementation of the OAuth 2.0 and 2.1 message
+/// family.
+///
+/// This functionality is included as follows:
+///
+/// ```cpp
+/// #include <sourcemeta/core/oauth.h>
+/// ```
+
+#endif

src/core/oauth/include/sourcemeta/core/oauth_bearer.h

@@ -0,0 +1,59 @@
+#ifndef SOURCEMETA_CORE_OAUTH_BEARER_H_
+#define SOURCEMETA_CORE_OAUTH_BEARER_H_
+
+#ifndef SOURCEMETA_CORE_OAUTH_EXPORT
+#include <sourcemeta/core/oauth_export.h>
+#endif
+
+#include <optional>    // std::optional
+#include <string>      // std::string
+#include <string_view> // std::string_view
+
+namespace sourcemeta::core {
+
+/// @ingroup oauth
+/// Append a `Bearer` credential (RFC 6750 Section 2.1) for an access token to
+/// the sink, returning whether the token is a well-formed `b64token`. Nothing
+/// is appended when it is not. The sink then holds the access token, which is
+/// secret, so a caller that keeps it should use wiping storage. For example:
+///
+/// ```cpp
+/// #include <sourcemeta/core/oauth.h>
+/// #include <cassert>
+/// #include <string>
+///
+/// std::string header;
+/// assert(sourcemeta::core::oauth_bearer_header("mF_9.B5f-4.1JqM", header));
+/// assert(header == "Bearer mF_9.B5f-4.1JqM");
+/// ```
+SOURCEMETA_CORE_OAUTH_EXPORT
+auto oauth_bearer_header(const std::string_view token, std::string &sink)
+    -> bool;
+
+/// @ingroup oauth
+/// Find the value of one authentication parameter within the challenge for a
+/// scheme in a `WWW-Authenticate` header value (RFC 7235 Section 4.1),
+/// returning no value when the scheme or parameter is absent, or the header is
+/// malformed before the parameter is reached. The scheme and parameter name are
+/// matched case insensitively, and a quoted-string value is unescaped (RFC 9110
+/// Section 5.6.4). The full grammar is parsed so that adjacent challenges and
+/// parameters are told apart correctly. For example:
+///
+/// ```cpp
+/// #include <sourcemeta/core/oauth.h>
+/// #include <cassert>
+///
+/// const auto realm{sourcemeta::core::oauth_challenge_parameter(
+///     R"(Bearer realm="example", error="invalid_token")", "Bearer", "realm")};
+/// assert(realm.has_value());
+/// assert(realm.value() == "example");
+/// ```
+SOURCEMETA_CORE_OAUTH_EXPORT
+auto oauth_challenge_parameter(const std::string_view header,
+                               const std::string_view scheme,
+                               const std::string_view name)
+    -> std::optional<std::string>;
+
+} // namespace sourcemeta::core
+
+#endif