From b7f6131eb6ffcf3cb4c9577b1d5c20a4dadb3487 Mon Sep 17 00:00:00 2001 From: jankapunkt Date: Tue, 8 Jul 2025 10:21:58 +0200 Subject: [PATCH 1/2] docs: add about page to summarize scope of this library --- docs/docs/about.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 43 insertions(+) create mode 100644 docs/docs/about.rst diff --git a/docs/docs/about.rst b/docs/docs/about.rst new file mode 100644 index 0000000..a89847c --- /dev/null +++ b/docs/docs/about.rst @@ -0,0 +1,42 @@ +======================== +About Node OAuth2 Server +======================== + +Please read this section carefully to understand the purpose and scope of the Node OAuth2 Server library. + +Scope +===== + +The scope of this library is to provide a headless implementation of an OAuth2 server that can be used in a variety of applications. +It is designed to be flexible and extensible, allowing developers to implement their own models and customize the behavior of the server. + + +Headless +======== + +By headless we mean that the library does not provide a user interface or any specific implementation details for handling user interactions. +It is purely a backend library that can be integrated into any Node.js application or framework. + +The core library is also designed to be framework-agnostic, meaning it does not depend on any specific web framework like Express or Koa. +For these frameworks, we provide separate adapter libraries that can be used to integrate the OAuth2 server into your application. + +Workflows +========= + +The library intends to cover the core OAuth2 workflows, including: +- Authorization Code Grant +- Client Credentials Grant +- Password Grant +- Refresh Token Grant + +While we provide documentation and examples for these workflows, +it is crucial for developers to understand the OAuth2 specification and how to implement these workflows correctly in their applications. +This is especially important for security reasons, as OAuth2 is a complex protocol with many potential pitfalls. + +We do provide links to standards and readings that can help developers understand the OAuth2 specification and how to implement it securely. + +Examples +======== + +We provide generic examples which you can use as foundation. +However, please make sure you understand the OAuth2 specification and how to implement it correctly in your application. diff --git a/docs/index.rst b/docs/index.rst index 7c1ea41..8c298e7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -55,6 +55,7 @@ Contents :maxdepth: 1 :caption: User Documentation + docs/about docs/getting-started docs/adapters From 4a307efa89bc37031e9de17fe44ed90063ecb863 Mon Sep 17 00:00:00 2001 From: jankapunkt Date: Tue, 8 Jul 2025 11:13:50 +0200 Subject: [PATCH 2/2] docs: add arch overview --- docs/_static/diagrams/arch-overview.graphml | 383 ++++++++++++++++++++ docs/_static/diagrams/arch-overview.png | Bin 0 -> 46767 bytes docs/docs/arch.rst | 18 + docs/index.rst | 1 + 4 files changed, 402 insertions(+) create mode 100644 docs/_static/diagrams/arch-overview.graphml create mode 100644 docs/_static/diagrams/arch-overview.png create mode 100644 docs/docs/arch.rst diff --git a/docs/_static/diagrams/arch-overview.graphml b/docs/_static/diagrams/arch-overview.graphml new file mode 100644 index 0000000..b796f59 --- /dev/null +++ b/docs/_static/diagrams/arch-overview.graphml @@ -0,0 +1,383 @@ + + + + + + + + + + + + + + + + + + + + + + + + + OAuth2Server + + + + + + + + + + + + + + + + AuthenticateHandler + + + + + + + + + + + + + + + + AuthorizeHandler + + + + + + + + + + + + + + + + TokenHandler + + + + + + + + + + + + + + + + Model + + + + + + + + + + + + + + + + UserModel + + + + + + + + + + + + + + + + GrantType + + + + + + + + + + + + + + + + AuthorizationCodeGrantType + + + + + + + + + + + + + + + + AuthorizationCodeGrantType + + + + + + + + + + + + + + + + AuthorizationCodeGrantType + + + + + + + + + + + + + + + + AuthorizationCodeGrantType + + + + + + + + + + + + + + + + TokenModel + + + + + + + + + + + + + + + + + + + + + + + + + + implements + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + passed to constructor + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/diagrams/arch-overview.png b/docs/_static/diagrams/arch-overview.png new file mode 100644 index 0000000000000000000000000000000000000000..35e764f442f078865c88be3502f0c4b199522b40 GIT binary patch literal 46767 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 bVV$&ecw%R8nr}Ap>#xWv$)sPr