Documentation Refresh

.github/actions/install/cmake/action.yml

@@ -14,7 +14,8 @@ runs:
     id: cache-cmake
     uses: actions/cache@v3
     with:
-      path: cmake-${{ inputs.version }}${{ runner.name }}-${{ runner.os }}-${{ runner.arch }}-${{ job.container.id }}-cmake-${{ inputs.version }}
+      path: cmake-${{ inputs.version }}
+      key: ${{ runner.name }}-${{ runner.os }}-${{ runner.arch }}-${{ job.container.id }}-cmake-${{ inputs.version }}
   - name: Build cmake
     if: steps.cache-cmake.outputs.cache-hit != 'true'
     run: |

.github/workflows/documentation.yml

@@ -9,13 +9,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
+      - uses: ssciwr/doxygen-install@v1
+        with:
+          version: "1.10.0"
       - run: sudo apt install graphviz
-      - run: wget https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v1.6.1/doxygen-awesome.css
-      - run: wget https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v1.6.1/doxygen-awesome-sidebar-only.css
-      - uses: mattnotmitt/doxygen-action@v1
-      - name: deploy
+      - run: | 
+          cmake . -DJWT_BUILD_DOCS=ON
+          cmake --build . --target jwt-docs
+      - if: github.event_name == 'push'
+        name: deploy
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./doxy/html
+          publish_dir: ./build/html
           force_orphan: true

.gitignore

@@ -310,8 +310,5 @@ test
 # ClangD cache files
 .cache
 
-doxy/
-doxygen-awesome*.css
-
 build/*
 package-lock.json

CMakeLists.txt

@@ -17,6 +17,7 @@ project(jwt-cpp)
 
 option(JWT_BUILD_EXAMPLES "Configure CMake to build examples (or not)" ON)
 option(JWT_BUILD_TESTS "Configure CMake to build tests (or not)" OFF)
+option(JWT_BUILD_DOCS "Adds a target for building the doxygen documentation" OFF)
 option(JWT_ENABLE_COVERAGE "Enable code coverage testing" OFF)
 option(JWT_ENABLE_FUZZING "Enable fuzz testing" OFF)
 
@@ -153,3 +154,7 @@ endif()
 if(JWT_ENABLE_FUZZING)
   add_subdirectory(tests/fuzz)
 endif()
+
+if(JWT_BUILD_DOCS)
+  add_subdirectory(docs)
+endif()

README.md

@@ -9,7 +9,7 @@
 
 [![Documentation Badge](https://img.shields.io/badge/Documentation-master-blue)](https://thalhammer.github.io/jwt-cpp/)
 
-[![Stars Badge](https://img.shields.io/github/stars/Thalhammer/jwt-cpp)](https://github.com/Thalhammer/jwt-cpp/stargazers)
+[![Stars Badge](https://img.shields.io/github/stars/Thalhammer/jwt-cpp?style=flat)](https://github.com/Thalhammer/jwt-cpp/stargazers)
 [![GitHub release (latest SemVer including pre-releases)](https://img.shields.io/github/v/release/Thalhammer/jwt-cpp?include_prereleases)](https://github.com/Thalhammer/jwt-cpp/releases)
 [![ConanCenter package](https://repology.org/badge/version-for-repo/conancenter/jwt-cpp.svg)](https://repology.org/project/jwt-cpp/versions)
 [![Vcpkg package](https://repology.org/badge/version-for-repo/vcpkg/jwt-cpp.svg)](https://repology.org/project/jwt-cpp/versions)
@@ -19,121 +19,114 @@
 [Windows]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/cross-platform/windows-latest/shields.json
 [Cross-Platform]: https://github.com/Thalhammer/jwt-cpp/actions?query=workflow%3A%22Cross-Platform+CI%22
 
+## Overview
+
 A header only library for creating and validating [JSON Web Tokens](https://tools.ietf.org/html/rfc7519) in C++11. For a great introduction, [read this](https://jwt.io/introduction/).
 
+The objective is to deliver a versatile and universally applicable collection of algorithms, classes, and data structures, fostering adaptability and seamless integration with other libraries that you may already be employing.
+
 ## Signature algorithms
 
-jwt-cpp supports all the algorithms defined by the specifications. The modular design allows to easily add additional algorithms without any problems. If you need any feel free to create a pull request or [open an issue](https://github.com/Thalhammer/jwt-cpp/issues/new).
+jwt-cpp comprehensively supports all algorithms specified in the standard. Its modular design facilitates the seamless [inclusion of additional algorithms](docs/signing.md#custom-signature-algorithms) without encountering any complications. Should you wish to contribute new algorithms, feel free to initiate a pull request or [open an issue](https://github.com/Thalhammer/jwt-cpp/issues/new).
 
 For completeness, here is a list of all supported algorithms:
 
 | HMSC  | RSA   | ECDSA  | PSS   | EdDSA   |
-|-------|-------|--------|-------|---------|
+| ----- | ----- | ------ | ----- | ------- |
 | HS256 | RS256 | ES256  | PS256 | Ed25519 |
 | HS384 | RS384 | ES384  | PS384 | Ed448   |
 | HS512 | RS512 | ES512  | PS512 |         |
 |       |       | ES256K |       |         |
 
-## SSL Compatibility
-
-In the name of flexibility and extensibility, jwt-cpp supports [OpenSSL](https://github.com/openssl/openssl), [LibreSSL](https://github.com/libressl-portable/portable), and [wolfSSL](https://github.com/wolfSSL/wolfssl). Read [this page](docs/ssl.md) for more details. These are the version which are currently being tested:
-
-| OpenSSL           | LibreSSL       | wolfSSL        |
-|-------------------|----------------|----------------|
-| ![1.0.2u][o1.0.2] | ![3.3.6][l3.3] | ![5.1.1][w5.1] |
-| ![1.1.0i][o1.1.0] | ![3.4.3][l3.4] | ![5.2.0][w5.2] |
-| ![1.1.1q][o1.1.1] | ![3.5.3][l3.5] | ![5.3.0][w5.3] |
-| ![3.0.5][o3.0]    |                |                |
-
-> ℹ️ Note: A complete list of versions tested in the past can be found [here](https://github.com/Thalhammer/jwt-cpp/tree/badges).
-
-[o1.0.2]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/openssl/1.0.2u/shields.json
-[o1.1.0]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/openssl/1.1.0i/shields.json
-[o1.1.1]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/openssl/1.1.1q/shields.json
-[o3.0]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/openssl/3.0.5/shields.json
-[l3.3]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/libressl/3.3.6/shields.json
-[l3.4]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/libressl/3.4.3/shields.json
-[l3.5]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/libressl/3.5.3/shields.json
-[w5.1]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/wolfssl/5.1.1/shields.json
-[w5.2]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/wolfssl/5.2.0/shields.json
-[w5.3]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/wolfssl/5.3.0/shields.json
-
-## Overview
-
-There is no hard dependency on a JSON library. Instead, there's a generic `jwt::basic_claim` which is templated around type traits, which described the semantic [JSON types](https://json-schema.org/understanding-json-schema/reference/type.html) for a value, object, array, string, number, integer and boolean, as well as methods to translate between them.
-
-```cpp
-jwt::basic_claim<my_favorite_json_library_traits> claim(json::object({{"json", true},{"example", 0}}));
-```
-
-This allows for complete freedom when picking which libraries you want to use. For more information, [read this page](docs/traits.md)).
-
-For your convenience there are serval traits implementation which provide some popular JSON libraries. They are:
-
-[![picojson][picojson]](https://github.com/kazuho/picojson)
-[![nlohmann][nlohmann]](https://github.com/nlohmann/json)
-[![jsoncons][jsoncons]](https://github.com/danielaparker/jsoncons)
-[![boostjson][boostjson]](https://github.com/boostorg/json)
-
-[picojson]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/traits/kazuho-picojson/shields.json
-[nlohmann]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/traits/nlohmann-json/shields.json
-[jsoncons]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/traits/danielaparker-jsoncons/shields.json
-[boostjson]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Thalhammer/jwt-cpp/badges/traits/boost-json/shields.json
-
-In order to maintain compatibility, [picojson](https://github.com/kazuho/picojson) is still used to provide a specialized `jwt::claim` along with all helpers. Defining `JWT_DISABLE_PICOJSON` will remove this optional dependency. It's possible to directly include the traits defaults for the other JSON libraries. See the [traits examples](https://github.com/Thalhammer/jwt-cpp/tree/master/example/traits) for details.
-
-As for the base64 requirements of JWTs, this library provides `base.h` with all the required implementation; However base64 implementations are very common, with varying degrees of performance. When providing your own base64 implementation, you can define `JWT_DISABLE_BASE64` to remove the jwt-cpp implementation.
+## Getting Started
 
-### Getting Started
+Installation instructions can be found [here](docs/install.md).
 
-Simple example of decoding a token and printing all [claims](https://tools.ietf.org/html/rfc7519#section-4) ([try it out](https://github.com/Thalhammer/jwt-cpp/tree/master/example/print-claims.cpp)):
+A simple example is decoding a token and printing all of its [claims](https://tools.ietf.org/html/rfc7519#section-4) let's ([try it out](https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCIsInNhbXBsZSI6InRlc3QifQ.lQm3N2bVlqt2-1L-FsOjtR6uE-L4E9zJutMWKIe1v1M)):
 
 ```cpp
 #include <jwt-cpp/jwt.h>
 #include <iostream>
 
 int main() {
-    std::string token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
+    std::string token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCIsInNhbXBsZSI6InRlc3QifQ.lQm3N2bVlqt2-1L-FsOjtR6uE-L4E9zJutMWKIe1v1M";
     auto decoded = jwt::decode(token);
 
     for(auto& e : decoded.get_payload_json())
         std::cout << e.first << " = " << e.second << std::endl;
 }
 ```
 
+You can build and run [this example](example/print-claims.cpp) locally after cloning the repository.
+Running some commands, we can see the contents of the [JWT payload](https://datatracker.ietf.org/doc/html/rfc7519#section-3)
+
+```sh
+cmake .
+cmake --build . --target print-claims
+./print-claims
+# iss = "auth0"
+# sample = "test"
+```
+
+You'll very quickly notice JWT are not encrypted but rather cryptographically signed to
+provide [non-repudiation](https://csrc.nist.gov/glossary/term/non_repudiation).
+
 In order to verify a token you first build a verifier and use it to verify a decoded token.
 
 ```cpp
 auto verifier = jwt::verify()
-    .allow_algorithm(jwt::algorithm::hs256{ "secret" })
-    .with_issuer("auth0");
+    .with_issuer("auth0")
+    .with_claim("sample", jwt::claim(std::string("test")));
+    .allow_algorithm(jwt::algorithm::hs256{"secret"})
 
 verifier.verify(decoded_token);
 ```
 
-The created verifier is stateless so you can reuse it for different tokens.
+The verifier is stateless so you can reuse it for different tokens.
 
-Creating a token (and signing) is equally as easy.
+Creating the token above (and signing it) is equally as easy.
 
 ```cpp
 auto token = jwt::create()
-    .set_issuer("auth0")
     .set_type("JWS")
+    .set_issuer("auth0")
     .set_payload_claim("sample", jwt::claim(std::string("test")))
     .sign(jwt::algorithm::hs256{"secret"});
 ```
 
-> To see more examples working with RSA public and private keys, visit our [examples](https://github.com/Thalhammer/jwt-cpp/tree/master/example)!
+If you are looking to issue or verify more unique tokens, checkout out the [examples](https://github.com/Thalhammer/jwt-cpp/tree/master/example) working with RSA public and private keys, elliptic curve tokens, and much more!
+
+### Configuration Options
+
+Building on the goal of providing flexibility.
+
+#### SSL Compatibility
+
+jwt-cpp supports [OpenSSL](https://github.com/openssl/openssl), [LibreSSL](https://github.com/libressl-portable/portable), and [wolfSSL](https://github.com/wolfSSL/wolfssl). For a listed of tested versions, check [this page](docs/ssl.md) for more details.
+
+#### JSON Implementation
+
+There is no strict reliance on a specific JSON library in this context. Instead, the jwt-cpp utilizes a generic `jwt::basic_claim` that is templated based on type trait. This trait provides the semantic [JSON types](https://json-schema.org/understanding-json-schema/reference/type.html) for values, objects, arrays, strings, numbers, integers, and booleans, along with methods to seamlessly translate between them.
+
+This design offers flexibility in choosing the JSON library that best suits your needs. To leverage one of the provided JSON traits, refer to [docs/traits.md](docs/traits.md#selecting-a-json-library) for detailed guidance.
+
+##### Providing your own JSON Traits
+
+```cpp
+jwt::basic_claim<my_favorite_json_library_traits> claim(json::object({{"json", true},{"example", 0}}));
+```
+
+To learn how to writes a trait's implementation, checkout the [these instructions](docs/traits.md#providing-your-own-json-traits)
 
-### Providing your own JSON Traits
+#### Base64 Options
 
-To learn how to writes a trait's implementation, checkout the [these instructions](docs/traits.md)
+With regard to the base64 specifications for JWTs, this library includes `base.h` encompassing all necessary variants. While the library itself offers a proficient base64 implementation, it's worth noting that base64 implementations are widely available, exhibiting diverse performance levels. If you prefer to use your own base64 implementation, you have the option to define `JWT_DISABLE_BASE64` to exclude the jwt-cpp implementation.
 
 ## Contributing
 
-If you have an improvement or found a bug feel free to [open an issue](https://github.com/Thalhammer/jwt-cpp/issues/new) or add the change and create a pull request. If you file a bug please make sure to include as much information about your environment (compiler version, etc.) as possible to help reproduce the issue. If you add a new feature please make sure to also include test cases for it.
+If you have suggestions for improvement or if you've identified a bug, please don't hesitate to [open an issue](https://github.com/Thalhammer/jwt-cpp/issues/new) or contribute by creating a pull request. When reporting a bug, provide comprehensive details about your environment, including compiler version and other relevant information, to facilitate issue reproduction. Additionally, if you're introducing a new feature, ensure that you include corresponding test cases to validate its functionality.
 
-## Dependencies
+### Dependencies
 
 In order to use jwt-cpp you need the following tools.
 
@@ -152,4 +145,5 @@ In order to build the test cases you also need
 See the [FAQs](docs/faqs.md) for tips.
 
 ## Conference Coverage
+
 [![CppCon](https://img.youtube.com/vi/Oq4NW5idmiI/0.jpg)](https://www.youtube.com/watch?v=Oq4NW5idmiI)

docs/.gitignore

@@ -0,0 +1 @@
+doxygen-awesome*.css

docs/CMakeLists.txt

@@ -0,0 +1,23 @@
+file(DOWNLOAD https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.2.1/doxygen-awesome.css
+     ${CMAKE_CURRENT_LIST_DIR}/doxygen-awesome.css
+     EXPECTED_HASH SHA256=9b5549928906e9974cc12dcdde9265e016dc2388ec72d5aa3209f4870914a0c8)
+file(DOWNLOAD https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.2.1/doxygen-awesome-sidebar-only.css
+     ${CMAKE_CURRENT_LIST_DIR}/doxygen-awesome-sidebar-only.css
+     EXPECTED_HASH SHA256=998328b27193b7be007a431bc9be1a6f6855ff4d8fa722ecfdfed79a8931409f)
+
+execute_process(COMMAND doxygen --version RESULT_VARIABLE DOXYGEN_VERSION_RESULT
+                OUTPUT_VARIABLE DOXYGEN_VERSION_RAW_OUTPUT)
+if(NOT DOXYGEN_VERSION_RESULT EQUAL 0)
+  message(AUTHOR_WARNING "Unable to get the version of doxygen")
+else()
+  # Extracts the version from the output of the command run before
+  string(REGEX MATCH "^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)" DOXYGEN_VERSION_OUTPUT
+               "${DOXYGEN_VERSION_RAW_OUTPUT}")
+  message(STATUS "doxygen version detected : ${DOXYGEN_VERSION_OUTPUT}")
+endif()
+
+add_custom_target(jwt-docs COMMAND doxygen ${CMAKE_CURRENT_LIST_DIR}/Doxyfile WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+                  SOURCES ${CMAKE_CURRENT_LIST_DIR}/Doxyfile BYPRODUCTS ${CMAKE_BINARY_DIR}/html/index.html)
+add_custom_command(
+  TARGET jwt-docs POST_BUILD COMMAND ${CMAKE_COMMAND} -E cmake_echo_color --cyan
+                                     "You can prview the documentation: ${CMAKE_BINARY_DIR}/html/index.html")