Merge branch 'master' into rfc7009

Author: jankapunkt

.eslintignore

@@ -0,0 +1,5 @@
+.github
+.nyc_output
+coverage
+docs/*
+node_modules

.github/workflows/deploy_docs.yml

@@ -0,0 +1,64 @@
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+#
+name: Deploy VitePress site to Pages
+
+on:
+  push:
+    branches: [master]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      # - uses: pnpm/action-setup@v3 # Uncomment this block if you're using pnpm
+      #   with:
+      #     version: 9 # Not needed if you've set "packageManager" in package.json
+      # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: npm # or pnpm / yarn
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Install dependencies
+        run: npm ci # or pnpm install / yarn install / bun install
+      - name: Build with VitePress
+        run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CONTRIBUTING.md

@@ -7,18 +7,18 @@ in order to get your pull requests accepted.
 ## Disclose security vulnerabilities
 
 First things first:
-This project has strong security implications and we appreciate every help to
+This project has strong security implications, and we appreciate every help to
 improve security.
 
-**However, please read our [security policy](./SECURITY.md), before taking 
-actions.**
+**However, please read our [security policy](https://github.com/node-oauth/node-oauth2-server/security/policy),
+before taking actions.**
 
 
 
 ## Guiding principles
 
 Before contributing to this project it is important to understand how this 
-project and it's collaborators views itself regarding it's scope and purpose.
+project and it's collaborators views itself regarding its scope and purpose.
 
 ### OAuth2 standard compliance
 
@@ -38,7 +38,7 @@ Extended readings:
 - [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients](https://datatracker.ietf.org/doc/html/rfc7636)
 - [RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591)
 
-### Framework agnostic
+### Framework-agnostic
 
 Design decisions and implementations are always done with keeping in mind, that
 there are multiple frameworks out there that use this project.
@@ -47,8 +47,7 @@ there are multiple frameworks out there that use this project.
 
 ## Development
 
-If you want to fix bugs or add new features, **please read this chapter and it's 
-sections carefully!**
+If you want to fix bugs or add new features, **please read this chapter and it's sections carefully!**
 
 ### No PR without issue
 
@@ -60,24 +59,24 @@ and discuss, whether this is a useful addition to the project.
 First, clone and install this project from source via
 
 ```bash
-$ git clone git@github.com:node-oauth/node-oauth2-server.git
-$ cd node-oauth2-server
-$ git checkout development # important! do not work on master!
-$ npm install
+git clone git@github.com:node-oauth/node-oauth2-server.git
+cd node-oauth2-server
+git checkout development # important! do not work on master!
+npm install
 ```
 
 From here you can run several scripts for development purposes:
 
 ```bash
-$ npm run test           # runs the tests once
-$ npm run test:coverage  # runs the tests including coverage
-$ npm run docs           # generates the API docs
+npm run test           # runs the tests once
+npm run test:coverage  # runs the tests including coverage
+npm run docs           # generates the API docs
 ```
 
 To work on a new feature or a fix please create a new branch:
 
 ```bash
-$ git checkout -b feature-xyz # or fix-xyz
+git checkout -b feature-xyz # or fix-xyz
 ```
 
 ### Coding rules
@@ -93,8 +92,9 @@ with ticket number at the end of summary:
 ```
 <type>(<scope>): <short summary> #<issue number>
 ```
+
 Summary in present tense. Not capitalized. No period at the end.
-The <type> and <summary> fields are mandatory, the (<scope>) and #<number> field is optional.
+The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` and `#<number>` fields are optional.
 
 ### Run the tests before committing
 
@@ -105,13 +105,13 @@ the history with commits, that are solely targeting lint fixes.
 You can run the tests via
 
 ```bash
-$ npm run test
+npm run test
 ```
 
 or  
 
 ```bash
-$ npm run test:coverage
+npm run test:coverage
 ```
 
 to see your coverage.
@@ -152,7 +152,7 @@ Also make sure, to comply with the following list:
 
 #### Review process
 
-Finally your PR needs to pass the review process:
+Finally, your PR needs to pass the review process:
 
 - A certain amount of maintainers needs to review and accept your PR
 - Please **expect change requests**! They will occur and are intended to improve
@@ -165,3 +165,31 @@ Finally your PR needs to pass the review process:
 #### After merge
 
 Please delete your branch after merge.
+
+## Documentation
+
+We use Vitepress+Markdown for our documentation.
+If you want to contribute to the docs, please get familiar with Vitepress: https://vitepress.dev
+
+### Setting up docs
+
+You need NPM to set up the docs using the following:
+
+```shell
+npm install
+npm run docs:setup
+```
+
+You can then edit the `guide` section manually.
+
+### API Docs
+
+**DO NOT** edit the `api` section, as API docs are automatically
+generated from our internal JSDoc comments.
+
+Instead, update the comments directly within the code and run `npm run docs:api`
+to generate the api docs.
+
+### Building the docs
+
+Run `npm run docs:build` to build the docs.

docs/.gitignore

@@ -0,0 +1,2 @@
+.vitepress/cache
+.vitepress/dist

docs/.vitepress/config.mts

@@ -0,0 +1,111 @@
+import {defineConfig} from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+    title: "@node-oauth/oauth2-server",
+    description: "OAuth2 server for Node.js",
+    base: '/node-oauth2-server/',
+    head: [['link', { rel: 'icon', href: '/images/favicon.ico' }]],
+    themeConfig: {
+        // https://vitepress.dev/reference/default-theme-config
+        nav: [
+            {text: 'Home', link: '/'},
+            {text: 'Guide', link: '/guide/getting-started'},
+            {text: 'API', link: '/api/server'}
+        ],
+
+        sidebar: [
+            {
+                text: 'Guide',
+                items: [
+                    {text: 'Getting started', link: '/guide/getting-started'},
+                    {text: 'Grant types', link: '/guide/grant-types'},
+                    {text: 'Model', link: '/guide/model'},
+                    {text: 'Token types', link: '/guide/token-types'},
+                    {text: 'PKCE', link: '/guide/pkce'},
+                    {text: 'Adapters', link: '/guide/adapters'},
+                    {text: 'Migrating to v5', link: '/guide/migrating-to-v5'},
+                    {text: 'Contributing', link: '/guide/contributing'},
+                ]
+            },
+            {
+                text: 'API',
+                items: [
+                    {text: 'OAuth2Server', link: '/api/server'},
+                    {text: 'Model', link: '/api/model'},
+                    {text: 'Request', link: '/api/request'},
+                    {text: 'Response', link: '/api/response'},
+                    {
+                        text: 'Errors', items: [
+                            {text: 'Access Denied', link: '/api/errors/access-denied-error'},
+                            {text: 'Insufficient Scope', link: '/api/errors/insufficient-scope-error'},
+                            {text: 'Invalid Argument', link: '/api/errors/invalid-argument-error'},
+                            {text: 'Invalid Client', link: '/api/errors/invalid-client-error'},
+                            {text: 'Invalid Grant', link: '/api/errors/invalid-grant-error'},
+                            {text: 'Invalid Request', link: '/api/errors/invalid-request-error'},
+                            {text: 'Invalid Scope', link: '/api/errors/invalid-scope-error'},
+                            {text: 'Invalid Token', link: '/api/errors/invalid-token-error'},
+                            {text: 'OAuth Error', link: '/api/errors/oauth-error'},
+                            {text: 'Server Error', link: '/api/errors/server-error'},
+                            {text: 'Unauthorized Client', link: '/api/errors/unauthorized-client-error'},
+                            {text: 'Unauthorized Request', link: '/api/errors/unauthorized-request-error'},
+                            {text: 'Unsupported Grant Type', link: '/api/errors/unsupported-grant-type-error'},
+                            {text: 'Unsupported Response Type', link: '/api/errors/unsupported-response-type-error'},
+                        ]
+                    },
+                    {
+                        text: 'Grant Types', items: [
+                            { text: 'Abstract Grant Type', link: '/api/grant-types/abstract-grant-type' },
+                            { text: 'Authorization Code', link: '/api/grant-types/authorization-code-grant-type' },
+                            { text: 'Client Credentials', link: '/api/grant-types/client-credentials-grant-type' },
+                            { text: 'Password', link: '/api/grant-types/password-grant-type' },
+                            { text: 'Refresh Token', link: '/api/grant-types/refresh-token-grant-type' },
+                        ]
+                    },
+                    {
+                        text: 'Handlers', items: [
+                            { text: 'Authenticate Handler', link: '/api/handlers/authenticate-handler' },
+                            { text: 'Authorize Handler', link: '/api/handlers/authorize-handler' },
+                            { text: 'Token Handler', link: '/api/handlers/token-handler' },
+                        ]
+                    },
+                    {
+                        text: 'Models', items: [
+                            { text: 'Token Model', link: '/api/models/token-model' },
+                        ]
+                    },
+                    {
+                        text: 'PKCE', items: [
+                            { text: 'PKCE', link: '/api/pkce/pkce' },
+                        ]
+                    },
+                    {
+                        text: 'Response Types', items: [
+                            { text: 'Code', link: '/api/response-types/code-response-type' },
+                            { text: 'Token', link: '/api/response-types/token-response-type' },
+                        ]
+                    },
+                    {
+                        text: 'Token Types', items: [
+                            { text: 'Bearer', link: '/api/token-types/bearer-token-type' },
+                            { text: 'Mac', link: '/api/token-types/mac-token-type' },
+                        ]
+                    },
+                    {
+                        text: 'Utils', items: [
+                            { text: 'Crypto', link: '/api/utils/crypto-util' },
+                            { text: 'Date', link: '/api/utils/date-util' },
+                            { text: 'Scope', link: '/api/utils/scope-util' },
+                            { text: 'String', link: '/api/utils/string-util' },
+                            { text: 'Token', link: '/api/utils/token-util' },
+                        ]
+                    },
+                ]
+            }
+        ],
+
+        socialLinks: [
+            {icon: 'github', link: 'https://github.com/node-oauth/node-oauth2-server'}
+        ]
+    }
+})