docs: merged master docs into 5.0.0

jankapunkt · jankapunkt · commit 6d27e3fb36bc · 2023-11-06T08:25:55.000+01:00
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');
 
 --------
 
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/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
@@ -0,0 +1,141 @@
+================
+ PKCE Support
+================
+
+Starting with release 4.3.0_ this library supports PKCE (Proof Key for Code Exchange by OAuth Public Clients) as
+defined in :rfc:`7636`.
+
+.. _4.3.0: https://github.com/node-oauth/node-oauth2-server/releases/tag/v4.3.0
+
+The PKCE integrates only with the :ref:`authorization code <AuthorizationCodeGrant>`. The abstract workflow looks like
+the following:
+
+::
+
+                                                 +-------------------+
+                                                 |   Authz Server    |
+       +--------+                                | +---------------+ |
+       |        |--(A)- Authorization Request ---->|               | |
+       |        |       + t(code_verifier), t_m  | | Authorization | |
+       |        |                                | |    Endpoint   | |
+       |        |<-(B)---- Authorization Code -----|               | |
+       |        |                                | +---------------+ |
+       | Client |                                |                   |
+       |        |                                | +---------------+ |
+       |        |--(C)-- Access Token Request ---->|               | |
+       |        |          + code_verifier       | |    Token      | |
+       |        |                                | |   Endpoint    | |
+       |        |<-(D)------ Access Token ---------|               | |
+       +--------+                                | +---------------+ |
+                                                 +-------------------+
+
+                     Figure 2: Abstract Protocol Flow
+
+See :rfc:`Section 1 of RFC 7636 <7636#section-1.1>`.
+
+1. Authorization request
+========================
+
+.. _PKCE#authorizationRequest:
+
+    A. The client creates and records a secret named the "code_verifier" and derives a transformed version "t(code_verifier)" (referred to as the "code_challenge"), which is sent in the OAuth 2.0 Authorization Request along with the transformation method "t_m".
+
+The following shows an example of how a client could generate a `code_challenge`` and
+``code_challenge_method`` for the authorizazion request.
+
+::
+
+    const base64URLEncode = str => str.toString('base64')
+          .replace(/\+/g, '-')
+          .replace(/\//g, '_')
+          .replace(/=/g, '')
+
+    // This is the code_verifier, which is INITIALLY KEPT SECRET on the client
+    // and which is later passed as request param to the token endpoint.
+    // DO NOT SEND this with the authorization request!
+    const codeVerifier = base64URLEncode(crypto.randomBytes(32))
+
+    // This is the hashed version of the verifier, which is sent to the authorization endpoint.
+    // This is named t(code_verifier) in the above workflow
+    // Send this with the authorization request!
+    const codeChallenge = base64URLEncode(crypto.createHash('sha256').update(codeVerifier).digest())
+
+    // This is the name of the code challenge method
+    // This is named t_m in the above workflow
+    // Send this with the authorization request!
+    const codeChallengeMethod = 'S256'
+
+    // add these to the request that is fired from the client
+
+In this project the authorize endpoint calls OAuth2Server.prototype.authorize which itself uses AuthorizeHandler.
+If your Request body contains code_challenge and code_challenge_method then PKCE is active.
+
+::
+
+    const server = new OAuth2Server({ model })
+
+    // this could be added to express or other middleware
+    const authorizeEndpoint = function (req, res, next) {
+      const request = new Request(req)
+      req.query.code_challenge        // the codeChallenge value
+      req.query.code_challenge_method // 'S256'
+
+      server.authorize(request, response, options)
+        .then(function (code) {
+          // add code to response, code should not contain
+          // code_challenge or code_challenge_method
+        })
+        .catch(function (err) {
+          // handle error condition
+        })
+    }
+
+2. Authorization response
+=========================
+
+.. _PKCE#authorizationResponse:
+
+    B. The Authorization Endpoint responds as usual but records "t(code_verifier)" and the transformation method.
+
+The ``AuthorizeHandler.handle`` saves code challenge and code challenge method automatically via ``model.saveAuthorizationCode``.
+Note that this calls your model with additional properties ``code.codeChallenge`` and ``code.codeChallengeMethod``.
+
+
+3. Access Token Request
+=======================
+
+.. _PKCE#accessTokenRequest:
+
+    C. The client then sends the authorization code in the Access Token Request as usual but includes the "code_verifier" secret generated at (A).
+
+This is usually done in your token endpoint, that uses ``OAuth2Server.token``.
+
+::
+
+    const server = new OAuth2Server({ model })
+
+    // ...authorizeEndpoint
+
+    // this could be added to express or other middleware
+    const tokenEndpoint = function (req, res, next) {
+      const request = new Request(req)
+      request.body.code_verifier // the non-hashed code verifier
+      server.token(request, response, options)
+            .then(function (code) {
+              // add code to response, code should contain
+            })
+            .catch(function (err) {
+              // handle error condition
+            })
+    }
+
+Note that your client should have kept ``code_verifier`` a secret until this step and now includes it as param for the token endpoint call.
+
+
+    D. The authorization server transforms "code_verifier" and compares it to "t(code_verifier)" from (B). Access is denied if they are not equal.
+
+This will call ``model.getAuthorizationCode`` to load the code.
+The loaded code has to contain ``codeChallenge`` and ``codeChallengeMethod``.
+If ``model.saveAuthorizationCode`` did not cover these values when saving the code then this step will deny the request.
+
+See :ref:`Model#saveAuthorizationCode` and :ref:`Model#getAuthorizationCode`
diff --git a/docs/model/spec.rst b/docs/model/spec.rst
diff --git a/docs/npm_conf.py b/docs/npm_conf.py
