docs: fix links and cover missing topics

jankapunkt · web-flow · commit a036be52467b · 2023-08-07T13:16:30.000+02:00
Merge pull request #208 from node-oauth/docs-update
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#   install:
+#   - requirements: docs/requirements.txt
diff --git a/docs/api/errors/access-denied-error.rst b/docs/api/errors/access-denied-error.rst
@@ -6,7 +6,7 @@ The resource owner or authorization server denied the request. See :rfc:`Section
 
 ::
 
-  const AccessDeniedError = require('oauth2-server/lib/errors/access-denied-error');
+  const AccessDeniedError = require('@node-oauth/oauth2-server/lib/errors/access-denied-error');
 
 --------
 
diff --git a/docs/api/errors/insufficient-scope-error.rst b/docs/api/errors/insufficient-scope-error.rst
@@ -6,7 +6,7 @@ The request requires higher privileges than provided by the access token. See :r
 
 ::
 
-  const InsufficientScopeError = require('oauth2-server/lib/errors/insufficient-scope-error');
+  const InsufficientScopeError = require('@node-oauth/oauth2-server/lib/errors/insufficient-scope-error');
 
 --------
 
diff --git a/docs/api/errors/invalid-argument-error.rst b/docs/api/errors/invalid-argument-error.rst
@@ -6,7 +6,7 @@ An invalid argument was encountered.
 
 ::
 
-  const InvalidArgumentError = require('oauth2-server/lib/errors/invalid-argument-error');
+  const InvalidArgumentError = require('@node-oauth/oauth2-server/lib/errors/invalid-argument-error');
 
 .. note:: This error indicates that the module is used incorrectly (i.e., there is a programming error) and should never be seen because of external errors (like invalid data sent by a client).
 
diff --git a/docs/api/errors/invalid-client-error.rst b/docs/api/errors/invalid-client-error.rst
@@ -6,7 +6,7 @@ Client authentication failed (e.g., unknown client, no client authentication inc
 
 ::
 
-  const InvalidClientError = require('oauth2-server/lib/errors/invalid-client-error');
+  const InvalidClientError = require('@node-oauth/oauth2-server/lib/errors/invalid-client-error');
 
 --------
 
diff --git a/docs/api/errors/invalid-grant-error.rst b/docs/api/errors/invalid-grant-error.rst
@@ -6,7 +6,7 @@ The provided authorization grant (e.g., authorization code, resource owner crede
 
 ::
 
-  const InvalidGrantError = require('oauth2-server/lib/errors/invalid-grant-error');
+  const InvalidGrantError = require('@node-oauth/oauth2-server/lib/errors/invalid-grant-error');
 
 --------
 
diff --git a/docs/api/errors/invalid-request-error.rst b/docs/api/errors/invalid-request-error.rst
@@ -6,7 +6,7 @@ The request is missing a required parameter, includes an invalid parameter value
 
 ::
 
-  const InvalidRequestError = require('oauth2-server/lib/errors/invalid-request-error');
+  const InvalidRequestError = require('@node-oauth/oauth2-server/lib/errors/invalid-request-error');
 
 --------
 
diff --git a/docs/api/errors/invalid-scope-error.rst b/docs/api/errors/invalid-scope-error.rst
@@ -6,7 +6,7 @@ The requested scope is invalid, unknown, or malformed. See :rfc:`Section 4.1.2.1
 
 ::
 
-  const InvalidScopeError = require('oauth2-server/lib/errors/invalid-scope-error');
+  const InvalidScopeError = require('@node-oauth/oauth2-server/lib/errors/invalid-scope-error');
 
 --------
 
diff --git a/docs/api/errors/invalid-token-error.rst b/docs/api/errors/invalid-token-error.rst
@@ -6,7 +6,7 @@ The access token provided is expired, revoked, malformed, or invalid for other r
 
 ::
 
-  const InvalidTokenError = require('oauth2-server/lib/errors/invalid-token-error');
+  const InvalidTokenError = require('@node-oauth/oauth2-server/lib/errors/invalid-token-error');
 
 --------
 
diff --git a/docs/api/errors/oauth-error.rst b/docs/api/errors/oauth-error.rst
@@ -6,7 +6,7 @@ Base class for all errors returned by this module.
 
 ::
 
-  const OAuthError = require('oauth2-server/lib/errors/oauth-error');
+  const OAuthError = require('@node-oauth/oauth2-server/lib/errors/oauth-error');
 
 --------
 
diff --git a/docs/api/errors/server-error.rst b/docs/api/errors/server-error.rst
@@ -6,7 +6,7 @@ The authorization server encountered an unexpected condition that prevented it f
 
 ::
 
-  const ServerError = require('oauth2-server/lib/errors/server-error');
+  const ServerError = require('@node-oauth/oauth2-server/lib/errors/server-error');
 
 ``ServerError`` is used to wrap unknown exceptions encountered during request processing.
 
diff --git a/docs/api/errors/unauthorized-client-error.rst b/docs/api/errors/unauthorized-client-error.rst
@@ -6,7 +6,7 @@ The authenticated client is not authorized to use this authorization grant type.
 
 ::
 
-  const UnauthorizedClientError = require('oauth2-server/lib/errors/unauthorized-client-error');
+  const UnauthorizedClientError = require('@node-oauth/oauth2-server/lib/errors/unauthorized-client-error');
 
 --------
 
diff --git a/docs/api/errors/unauthorized-request-error.rst b/docs/api/errors/unauthorized-request-error.rst
@@ -6,7 +6,7 @@ The request lacked any authentication information or the client attempted to use
 
 ::
 
-  const UnauthorizedRequestError = require('oauth2-server/lib/errors/unauthorized-request-error');
+  const UnauthorizedRequestError = require('@node-oauth/oauth2-server/lib/errors/unauthorized-request-error');
 
 According to :rfc:`Section 3.1 of RFC 6750 <6750#section-3.1>` you should just fail the request with ``401 Unauthorized`` and not send any error information in the body if this error occurs:
 
diff --git a/docs/api/errors/unsupported-grant-type-error.rst b/docs/api/errors/unsupported-grant-type-error.rst
@@ -6,7 +6,7 @@ The authorization grant type is not supported by the authorization server. See :
 
 ::
 
-  const UnsupportedGrantTypeError = require('oauth2-server/lib/errors/unsupported-grant-type-error');
+  const UnsupportedGrantTypeError = require('@node-oauth/oauth2-server/lib/errors/unsupported-grant-type-error');
 
 --------
 
diff --git a/docs/api/errors/unsupported-response-type-error.rst b/docs/api/errors/unsupported-response-type-error.rst
@@ -6,7 +6,7 @@ The authorization server does not supported obtaining an authorization code usin
 
 ::
 
-  const UnsupportedResponseTypeError = require('oauth2-server/lib/errors/unsupported-response-type-error');
+  const UnsupportedResponseTypeError = require('@node-oauth/oauth2-server/lib/errors/unsupported-response-type-error');
 
 --------
 
diff --git a/docs/api/oauth2-server.rst b/docs/api/oauth2-server.rst
@@ -6,7 +6,7 @@ Represents an OAuth2 server instance.
 
 ::
 
-  const OAuth2Server = require('oauth2-server');
+  const OAuth2Server = require('@node-oauth/oauth2-server');
 
 --------
 
@@ -94,7 +94,7 @@ Possible errors include but are not limited to:
 :doc:`/api/errors/unauthorized-request-error`:
   The protected resource request failed authentication.
 
-The returned ``Promise`` **must** be ignored if ``callback`` is used.
+**Versions <=4.x note:** The returned ``Promise`` **must** be ignored if ``callback`` is used.
 
 **Remarks:**
 
@@ -139,7 +139,7 @@ Authorizes a token request.
 +-----------------------------------------+-----------------+-----------------------------------------------------------------------------+
 | [options={}]                            | Object          | Handler options.                                                            |
 +-----------------------------------------+-----------------+-----------------------------------------------------------------------------+
-| [options.authenticateHandler=undefined] | Object          | The authenticate handler (see remarks section).                             |
+| [options.authenticateHandler=undefined] | Object          | The authenticate handler (see remarks section below).                             |
 +-----------------------------------------+-----------------+-----------------------------------------------------------------------------+
 | [options.allowEmptyState=false]         | Boolean         | Allow clients to specify an empty ``state``.                                |
 +-----------------------------------------+-----------------+-----------------------------------------------------------------------------+
@@ -158,7 +158,7 @@ Possible errors include but are not limited to:
 :doc:`/api/errors/access-denied-error`
   The resource owner denied the access request (i.e. ``request.query.allow`` was ``'false'``).
 
-The returned ``Promise`` **must** be ignored if ``callback`` is used.
+**Versions <=4.x note:** The returned ``Promise`` **must** be ignored if ``callback`` is used.
 
 **Remarks:**
 
@@ -252,7 +252,7 @@ Possible errors include but are not limited to:
 :doc:`/api/errors/invalid-grant-error`:
   The access token request was invalid or not authorized.
 
-The returned ``Promise`` **must** be ignored if ``callback`` is used.
+**Versions <=4.x note:** The returned ``Promise`` **must** be ignored if ``callback`` is used.
 
 **Remarks:**
 
diff --git a/docs/api/request.rst b/docs/api/request.rst
@@ -6,7 +6,7 @@ Represents an incoming HTTP request.
 
 ::
 
-  const Request = require('oauth2-server').Request;
+  const Request = require('@node-oauth/oauth2-server').Request;
 
 --------
 
@@ -50,7 +50,7 @@ To convert `Express' request`_ to a ``Request`` simply pass ``req`` as ``options
 ::
 
   function(req, res, next) {
-    var request = new Request(req);
+    let request = new Request(req);
     // ...
   }
 
diff --git a/docs/api/response.rst b/docs/api/response.rst
@@ -6,7 +6,7 @@ Represents an outgoing HTTP response.
 
 ::
 
-  const Response = require('oauth2-server').Response;
+  const Response = require('@node-oauth/oauth2-server').Response;
 
 --------
 
@@ -46,7 +46,7 @@ To convert `Express' response`_ to a ``Response`` simply pass ``res`` as ``optio
 ::
 
   function(req, res, next) {
-    var response = new Response(res);
+    let response = new Response(res);
     // ...
   }
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# oauth2-server documentation build configuration file, created by
+# @node-oauth/oauth2-server documentation build configuration file, created by
 # sphinx-quickstart on Thu Nov 17 16:47:05 2016.
 #
 # This file is execfile()d with the current directory set to its containing dir.
@@ -272,5 +272,5 @@
 highlight_language = 'js'
 
 def setup(app):
-    app.add_stylesheet('custom.css')
+    app.add_css_file('custom.css')
 
diff --git a/docs/docs/adapters.rst b/docs/docs/adapters.rst
@@ -7,9 +7,9 @@ The *oauth2-server* module is typically not used directly but through one of the
 .. framework-agnostic but there are several officially supported adapters available for popular HTTP server frameworks such as Express_ and Koa_.
 
 - express-oauth-server_ for Express_
-- koa-oauth-server_ for Koa_
+- koa-oauth-server_ for Koa_ (outdated, maintainer wanted!)
 
-.. _express-oauth-server: https://npmjs.org/package/express-oauth-server
+.. _express-oauth-server: https://www.npmjs.com/package/@node-oauth/express-oauth-server
 .. _Express: https://npmjs.org/package/express
 .. _koa-oauth-server: https://npmjs.org/package/koa-oauth-server
 .. _Koa: https://npmjs.org/package/koa
diff --git a/docs/docs/getting-started.rst b/docs/docs/getting-started.rst
@@ -9,16 +9,16 @@ Installation
 
 oauth2-server_ is available via npm_.
 
-.. _oauth2-server: https://npmjs.org/package/oauth2-server
+.. _oauth2-server: https://www.npmjs.com/package/@node-oauth/oauth2-server
 .. _npm: https://npmjs.org
 
 .. code-block:: sh
 
-  $ npm install oauth2-server
+  $ npm install @node-oauth/oauth2-server
 
-.. note:: The *oauth2-server* module is framework-agnostic but there are several officially supported adapters available for popular HTTP server frameworks such as Express_ and Koa_. If you're using one of those frameworks it is strongly recommended to use the respective adapter module instead of rolling your own.
+.. note:: The *oauth2-server* module is framework-agnostic but there are several officially supported adapters available for popular HTTP server frameworks such as Express_ and Koa_ (maintainer wanted!). If you're using one of those frameworks it is strongly recommended to use the respective adapter module instead of rolling your own.
 
-.. _Express: https://npmjs.org/package/express-oauth-server
+.. _Express: https://www.npmjs.com/package/@node-oauth/express-oauth-server
 .. _Koa: https://npmjs.org/package/koa-oauth-server
 
 
@@ -29,12 +29,14 @@ Features
 
 - Supports :ref:`authorization code <AuthorizationCodeGrant>`, :ref:`client credentials <ClientCredentialsGrant>`, :ref:`refresh token <RefreshTokenGrant>` and :ref:`password <PasswordGrant>` grant, as well as :ref:`extension grants <ExtensionGrants>`, with scopes.
 - Can be used with *promises*, *Node-style callbacks*, *ES6 generators* and *async*/*await* (using Babel_).
+- From version 5.0.0 fully native async/await implemented
 - Fully :rfc:`6749` and :rfc:`6750` compliant.
+- Supports PKCE (:rfc:`7636`)
 - Implicitly supports any form of storage, e.g. *PostgreSQL*, *MySQL*, *MongoDB*, *Redis*, etc.
 - Complete `test suite`_.
 
 .. _Babel: https://babeljs.io
-.. _test suite: https://github.com/oauthjs/node-oauth2-server/tree/master/test
+.. _test suite: https://github.com/node-oauth/node-oauth2-server/tree/master/test
 
 
 .. _quick-start:
@@ -46,7 +48,7 @@ Quick Start
 
 ::
 
-  const OAuth2Server = require('oauth2-server');
+  const OAuth2Server = require('@node-oauth/oauth2-server');
 
   const oauth = new OAuth2Server({
     model: require('./model')
@@ -78,7 +80,7 @@ Quick Start
 
 ::
 
-  const AccessDeniedError = require('oauth2-server/lib/errors/access-denied-error');
+  const AccessDeniedError = require('@node-oauth/oauth2-server/lib/errors/access-denied-error');
 
   oauth.authorize(request, response)
     .then((code) => {
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,13 +1,13 @@
-===============
- oauth2-server
-===============
+==========================
+ @node-oauth/oauth2-server
+==========================
 
-oauth2-server_ is a complete, compliant and well tested module for implementing an OAuth2 server in Node.js_. The project is `hosted on GitHub`_ and the included test suite is automatically `run on Travis CI`_.
+oauth2-server_ is a complete, compliant and well tested module for implementing an OAuth2 server in Node.js_. The project is `hosted on GitHub`_ and the included test suite is automatically `run on GitHub CI`_.
 
-.. _oauth2-server: https://npmjs.org/package/oauth2-server
+.. _oauth2-server: https://www.npmjs.com/package/@node-oauth/oauth2-server
 .. _Node.js: https://nodejs.org
-.. _hosted on GitHub: https://github.com/oauthjs/node-oauth2-server
-.. _run on Travis CI: https://travis-ci.org/oauthjs/node-oauth2-server
+.. _hosted on GitHub: https://github.com/node-oauth/node-oauth2-server
+.. _run on GitHub CI: https://github.com/node-oauth/node-oauth2-server/actions
 
 :ref:`installation`
 
@@ -17,7 +17,7 @@ Example Usage
 
 ::
 
-  const OAuth2Server = require('oauth2-server');
+  const OAuth2Server = require('@node-oauth/oauth2-server');
   const Request = OAuth2Server.Request;
   const Response = OAuth2Server.Response;
 
@@ -84,5 +84,6 @@ See the :doc:`/model/spec` of what is required from the model passed to :doc:`/a
    :hidden:
 
    misc/extension-grants
+   misc/pkce
    misc/migrating-v2-to-v3
 
diff --git a/docs/misc/extension-grants.rst b/docs/misc/extension-grants.rst
@@ -6,7 +6,7 @@ Create a subclass of ``AbstractGrantType`` and create methods `handle` and `save
 
 .. code-block:: js
 
-  const OAuth2Server = require('oauth2-server');
+  const OAuth2Server = require('@node-oauth/oauth2-server');
   const AbstractGrantType = OAuth2Server.AbstractGrantType;
   const InvalidArgumentError = OAuth2Server.InvalidArgumentError;
   const InvalidRequestError = OAuth2Server.InvalidRequestError;
diff --git a/docs/misc/migrating-v2-to-v3.rst b/docs/misc/migrating-v2-to-v3.rst
@@ -11,7 +11,7 @@ Middlewares
 The naming of the exposed middlewares has changed to match the OAuth2 _RFC_ more closely. Please refer to the table below:
 
 +-------------------+------------------------------------------------+
-| oauth2-server 2.x | oauth2-server 3.x                              |
+| oauth2-server 2.x | @node-oauth/oauth2-server 3.x                              |
 +===================+================================================+
 | authorise         | authenticate                                   |
 +-------------------+------------------------------------------------+
diff --git a/docs/misc/pkce.rst b/docs/misc/pkce.rst
diff --git a/docs/model/spec.rst b/docs/model/spec.rst
diff --git a/docs/npm_conf.py b/docs/npm_conf.py
