Merge branch 'master' into development

Author: jankapunkt

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+  - jankapunkt
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
+  - https://paypal.me/kuesterjan

.github/workflows/tests-release.yml

@@ -26,7 +26,7 @@ jobs:
     - uses: actions/checkout@v3
     - uses: actions/setup-node@v3
       with:
-        node-version: 16
+        node-version: 20
     # install to create local package-lock.json but don't cache the files
     # also: no audit for dev dependencies
     - run: npm i --package-lock-only  && npm audit --production
@@ -57,7 +57,6 @@ jobs:
         key: ${{ runner.os }}-node-${{ matrix.node }}-${{ hashFiles('**/package-lock.json') }}
         restore-keys: |
           ${{ runner.os }}-node-${{ matrix.node }}
-
     # for this workflow we also require npm audit to pass
     - run: npm i
     - run: npm run test:coverage
@@ -110,6 +109,7 @@ jobs:
     # in order to test the adapter we need to use the current checkout
     # and install it as local dependency
     # we just cloned and install it as local dependency
+    # xxx: added bluebird as explicit dependency
     - run: |
         cd github/testing/express
         npm i

.github/workflows/tests.yml

@@ -23,7 +23,7 @@ jobs:
       - name: setup node
         uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 20
 
       - name: cache dependencies
         uses: actions/cache@v3
@@ -41,7 +41,7 @@ jobs:
     needs: [lint]
     strategy:
       matrix:
-        node: [14, 16, 18]
+        node: [16, 18, 20]
     steps:
     - name: Checkout ${{ matrix.node }}
       uses: actions/checkout@v3

README.md

@@ -6,6 +6,7 @@ Complete, compliant and well tested module for implementing an OAuth2 server in
 [![Tests](https://github.com/node-oauth/node-oauth2-server/actions/workflows/tests.yml/badge.svg)](https://github.com/node-oauth/node-oauth2-server/actions/workflows/tests.yml)
 [![CodeQL Semantic Analysis](https://github.com/node-oauth/node-oauth2-server/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/node-oauth/node-oauth2-server/actions/workflows/codeql-analysis.yml)
 [![Tests for Release](https://github.com/node-oauth/node-oauth2-server/actions/workflows/tests-release.yml/badge.svg)](https://github.com/node-oauth/node-oauth2-server/actions/workflows/tests-release.yml)
+[![Documentation Status](https://readthedocs.org/projects/node-oauthoauth2-server/badge/?version=latest)](https://node-oauthoauth2-server.readthedocs.io/en/latest/?badge=latest)
 [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 ![npm Version](https://img.shields.io/npm/v/@node-oauth/oauth2-server?label=version)
 ![npm Downloads/Week](https://img.shields.io/npm/dw/@node-oauth/oauth2-server)
@@ -19,7 +20,8 @@ NOTE: This project has been forked from [oauthjs/node-oauth2-server](https://git
 npm install @node-oauth/oauth2-server
 ```
 
-The *@node-oauth/oauth2-server* module is framework-agnostic but there are several officially supported wrappers available for popular HTTP server frameworks such as [Express](https://npmjs.org/package/express-oauth-server) and [Koa](https://npmjs.org/package/koa-oauth-server). If you're using one of those frameworks it is strongly recommended to use the respective wrapper module instead of rolling your own.
+The `@node-oauth/oauth2-server` module is framework-agnostic but there are several officially supported wrappers available for popular HTTP server frameworks such as [Express](https://www.npmjs.com/package/@node-oauth/express-oauth-server) and [Koa (not maintained by us)](https://npmjs.org/package/koa-oauth-server).
+If you're using one of those frameworks it is strongly recommended to use the respective wrapper module instead of rolling your own.
 
 
 ## Features
@@ -28,25 +30,28 @@ The *@node-oauth/oauth2-server* module is framework-agnostic but there are sever
 - Can be used with *promises*, *Node-style callbacks*, *ES6 generators* and *async*/*await* (using [Babel](https://babeljs.io)).
 - Fully [RFC 6749](https://tools.ietf.org/html/rfc6749.html) and [RFC 6750](https://tools.ietf.org/html/rfc6750.html) compliant.
 - Implicitly supports any form of storage, e.g. *PostgreSQL*, *MySQL*, *MongoDB*, *Redis*, etc.
+- Support for PKCE
 - Complete [test suite](https://github.com/node-oauth/node-oauth2-server/tree/master/test).
 
-
 ## Documentation
 
-[Documentation](https://oauth2-server.readthedocs.io) is hosted on Read the Docs.
-
+[Documentation](https://node-oauthoauth2-server.readthedocs.io/en/latest/) is hosted on Read the Docs.
+Please leave an issue if something is confusing or missing in the docs.
 
 ## Examples
 
-Most users should refer to our [Express](https://github.com/oauthjs/express-oauth-server/tree/master/examples) or [Koa](https://github.com/oauthjs/koa-oauth-server/tree/master/examples) examples.
+Most users should refer to our [Express (active)](https://github.com/node-oauth/express-oauth-server) or 
+[Koa (not maintained by us)](https://github.com/oauthjs/koa-oauth-server/tree/master/examples) examples.
 
 More examples can be found here: https://github.com/14gasher/oauth-example
 
-## Upgrading from 2.x
+## Migrating from OAuthJs and 3.x
 
-This module has been rewritten using a promise-based approach, introducing changes to the API and model specification. v2.x is no longer supported.
+Version 4.x should not be hard-breaking, however, there were many improvements and fixes that may
+be incompatible with specific behaviour in <= 3.x
 
-Please refer to our [3.0 migration guide](https://oauth2-server.readthedocs.io/en/latest/misc/migrating-v2-to-v3.html) for more information.
+For more info, please read the [changelog](./CHANGELOG.md) or open an issue, if you think something
+is unexpectedly not working.
 
 ## Supported NodeJs versions
 

index.d.ts

@@ -306,7 +306,7 @@ declare namespace OAuth2Server {
          *
          */
         saveAuthorizationCode(
-          code: Pick<AuthorizationCode, 'authorizationCode' | 'expiresAt' | 'redirectUri' | 'scope'>,
+          code: Pick<AuthorizationCode, 'authorizationCode' | 'expiresAt' | 'redirectUri' | 'scope' | 'codeChallenge' | 'codeChallengeMethod'>,
           client: Client,
           user: User,
           callback?: Callback<AuthorizationCode>): Promise<AuthorizationCode | Falsey>;
@@ -322,6 +322,12 @@ declare namespace OAuth2Server {
          *
          */
         validateScope?(user: User, client: Client, scope: string | string[], callback?: Callback<string | Falsey>): Promise<string | string[] | Falsey>;
+        
+        /**
+         * Invoked to check if the provided `redirectUri` is valid for a particular `client`.
+         *
+         */
+        validateRedirectUri?(redirect_uri: string, client: Client): Promise<boolean>;
     }
 
     interface PasswordModel extends BaseModel, RequestAuthenticationModel {
@@ -410,6 +416,8 @@ declare namespace OAuth2Server {
         scope?: string | string[] | undefined;
         client: Client;
         user: User;
+        codeChallenge?: string;
+        codeChallengeMethod?: string;
         [key: string]: any;
     }
 

lib/grant-types/authorization-code-grant-type.js

@@ -12,6 +12,8 @@ const Promise = require('bluebird');
 const promisify = require('promisify-any').use(Promise);
 const ServerError = require('../errors/server-error');
 const isFormat = require('@node-oauth/formats');
+const util = require('util');
+const pkce = require('../pkce/pkce');
 
 /**
  * Constructor.
@@ -164,6 +166,7 @@ class AuthorizationCodeGrantType extends AbstractGrantType {
       });
   }
 
+
   /**
 	 * Save token.
 	 */

lib/handlers/authorize-handler.js

@@ -21,6 +21,7 @@ const UnauthorizedClientError = require('../errors/unauthorized-client-error');
 const isFormat = require('@node-oauth/formats');
 const tokenUtil = require('../utils/token-util');
 const url = require('url');
+const pkce = require('../pkce/pkce');
 
 /**
  * Response types.
@@ -77,10 +78,6 @@ AuthorizeHandler.prototype.handle = function(request, response) {
     throw new InvalidArgumentError('Invalid argument: `response` must be an instance of Response');
   }
 
-  if (request.query.allowed === 'false' || request.body.allowed === 'false') {
-    return Promise.reject(new AccessDeniedError('Access denied: user denied access to application'));
-  }
-
   const fns = [
     this.getAuthorizationCodeLifetime(),
     this.getClient(request),
@@ -98,7 +95,7 @@ AuthorizeHandler.prototype.handle = function(request, response) {
       return Promise.bind(this)
         .then(function() {
           state = this.getState(request);
-          if(request.query.allowed === 'false') {
+          if (request.query.allowed === 'false' || request.body.allowed === 'false') {
             throw new AccessDeniedError('Access denied: user denied access to application');
           }
         })
@@ -114,8 +111,10 @@ AuthorizeHandler.prototype.handle = function(request, response) {
         })
         .then(function(authorizationCode) {
           ResponseType = this.getResponseType(request);
+          const codeChallenge = this.getCodeChallenge(request);
+          const codeChallengeMethod = this.getCodeChallengeMethod(request);
 
-          return this.saveAuthorizationCode(authorizationCode, expiresAt, scope, client, uri, user);
+          return this.saveAuthorizationCode(authorizationCode, expiresAt, scope, client, uri, user, codeChallenge, codeChallengeMethod);
         })
         .then(function(code) {
           const responseType = new ResponseType(code.authorizationCode);
@@ -293,13 +292,20 @@ AuthorizeHandler.prototype.getRedirectUri = function(request, client) {
  * Save authorization code.
  */
 
-AuthorizeHandler.prototype.saveAuthorizationCode = function(authorizationCode, expiresAt, scope, client, redirectUri, user) {
-  const code = {
+AuthorizeHandler.prototype.saveAuthorizationCode = function(authorizationCode, expiresAt, scope, client, redirectUri, user, codeChallenge, codeChallengeMethod) {
+  let code = {
     authorizationCode: authorizationCode,
     expiresAt: expiresAt,
     redirectUri: redirectUri,
     scope: scope
   };
+
+  if(codeChallenge && codeChallengeMethod){
+    code = Object.assign({
+      codeChallenge: codeChallenge,
+      codeChallengeMethod: codeChallengeMethod
+    }, code);
+  }
   return promisify(this.model.saveAuthorizationCode, 3).call(this.model, code, client, user);
 };
 
@@ -369,6 +375,27 @@ AuthorizeHandler.prototype.updateResponse = function(response, redirectUri, stat
   response.redirect(url.format(redirectUri));
 };
 
+AuthorizeHandler.prototype.getCodeChallenge = function(request) {
+  return request.body.code_challenge;
+};
+
+/**
+ * Get code challenge method from request or defaults to plain.
+ * https://www.rfc-editor.org/rfc/rfc7636#section-4.3
+ *
+ * @throws {InvalidRequestError} if request contains unsupported code_challenge_method
+ *  (see https://www.rfc-editor.org/rfc/rfc7636#section-4.4)
+ */
+AuthorizeHandler.prototype.getCodeChallengeMethod = function(request) {
+  const algorithm = request.body.code_challenge_method;
+
+  if (algorithm && !pkce.isValidMethod(algorithm)) {
+    throw new InvalidRequestError(`Invalid request: transform algorithm '${algorithm}' not supported`);
+  }
+
+  return algorithm || 'plain';
+};
+
 /**
  * Export constructor.
  */

lib/handlers/token-handler.js

@@ -18,6 +18,7 @@ const TokenModel = require('../models/token-model');
 const UnauthorizedClientError = require('../errors/unauthorized-client-error');
 const UnsupportedGrantTypeError = require('../errors/unsupported-grant-type-error');
 const auth = require('basic-auth');
+const pkce = require('../pkce/pkce');
 const isFormat = require('@node-oauth/formats');
 
 /**
@@ -114,12 +115,14 @@ TokenHandler.prototype.handle = function(request, response) {
 TokenHandler.prototype.getClient = function(request, response) {
   const credentials = this.getClientCredentials(request);
   const grantType = request.body.grant_type;
+  const codeVerifier = request.body.code_verifier;
+  const isPkce = pkce.isPKCERequest({ grantType, codeVerifier });
 
   if (!credentials.clientId) {
     throw new InvalidRequestError('Missing parameter: `client_id`');
   }
 
-  if (this.isClientAuthenticationRequired(grantType) && !credentials.clientSecret) {
+  if (this.isClientAuthenticationRequired(grantType) && !credentials.clientSecret && !isPkce) {
     throw new InvalidRequestError('Missing parameter: `client_secret`');
   }
 
@@ -174,6 +177,7 @@ TokenHandler.prototype.getClient = function(request, response) {
 TokenHandler.prototype.getClientCredentials = function(request) {
   const credentials = auth(request);
   const grantType = request.body.grant_type;
+  const codeVerifier = request.body.code_verifier;
 
   if (credentials) {
     return { clientId: credentials.name, clientSecret: credentials.pass };
@@ -183,6 +187,12 @@ TokenHandler.prototype.getClientCredentials = function(request) {
     return { clientId: request.body.client_id, clientSecret: request.body.client_secret };
   }
 
+  if (pkce.isPKCERequest({ grantType, codeVerifier })) {
+    if(request.body.client_id) {
+      return { clientId: request.body.client_id };
+    }
+  }
+
   if (!this.isClientAuthenticationRequired(grantType)) {
     if(request.body.client_id) {
       return { clientId: request.body.client_id };

lib/pkce/pkce.js

@@ -0,0 +1,77 @@
+'use strict';
+
+/**
+ * Module dependencies.
+ */
+const { base64URLEncode } = require('../utils/string-util');
+const { createHash } = require('../utils/crypto-util');
+const codeChallengeRegexp = /^([a-zA-Z0-9.\-_~]){43,128}$/;
+/**
+ * Export `TokenUtil`.
+ */
+
+const pkce = {
+  /**
+   * Return hash for code-challenge method-type.
+   *
+   * @param method {String} the code challenge method
+   * @param verifier {String} the code_verifier
+   * @return {String|undefined}
+   */
+  getHashForCodeChallenge: function({ method, verifier }) {
+    // to prevent undesired side-effects when passing some wird values
+    // to createHash or base64URLEncode we first check if the values are right
+    if (pkce.isValidMethod(method) && typeof verifier === 'string' && verifier.length > 0) {
+      if (method === 'plain') {
+        return verifier;
+      }
+
+      if (method === 'S256') {
+        const hash = createHash({ data: verifier });
+        return base64URLEncode(hash);
+      }
+    }
+  },
+
+  /**
+   * Check if the request is a PCKE request. We assume PKCE if grant type is
+   * 'authorization_code' and code verifier is present.
+   *
+   * @param grantType {String}
+   * @param codeVerifier {String}
+   * @return {boolean}
+   */
+  isPKCERequest: function ({ grantType, codeVerifier }) {
+    return grantType === 'authorization_code' && !!codeVerifier;
+  },
+
+  /**
+   * Matches a code verifier (or code challenge) against the following criteria:
+   *
+   * code-verifier = 43*128unreserved
+   * unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
+   * ALPHA = %x41-5A / %x61-7A
+   * DIGIT = %x30-39
+   *
+   * @see: https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+   * @param codeChallenge {String}
+   * @return {Boolean}
+   */
+  codeChallengeMatchesABNF: function (codeChallenge) {
+    return typeof codeChallenge === 'string' &&
+      !!codeChallenge.match(codeChallengeRegexp);
+  },
+
+  /**
+   * Checks if the code challenge method is one of the supported methods
+   * 'sha256' or 'plain'
+   *
+   * @param method {String}
+   * @return {boolean}
+   */
+  isValidMethod: function (method) {
+    return method === 'S256' || method === 'plain';
+  }
+};
+
+module.exports = pkce;

lib/utils/crypto-util.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Export `StringUtil`.
+ */
+
+module.exports = {
+  /**
+   *
+   * @param algorithm {String} the hash algorithm, default is 'sha256'
+   * @param data {Buffer|String|TypedArray|DataView} the data to hash
+   * @param encoding {String|undefined} optional, the encoding to calculate the
+   *    digest
+   * @return {Buffer|String} if {encoding} undefined a {Buffer} is returned, otherwise a {String}
+   */
+  createHash: function({ algorithm = 'sha256', data = undefined, encoding = undefined }) {
+    return crypto
+      .createHash(algorithm)
+      .update(data)
+      .digest(encoding);
+  }
+};