feature(pkce): added pkce support

Author: jankapunkt

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

@@ -13,6 +13,7 @@ const promisify = require('promisify-any').use(Promise);
 const ServerError = require('../errors/server-error');
 const is = require('../validator/is');
 const util = require('util');
+const pkce = require('../pkce/pkce');
 
 /**
  * Constructor.
@@ -118,6 +119,36 @@ AuthorizationCodeGrantType.prototype.getAuthorizationCode = function(request, cl
         throw new InvalidGrantError('Invalid grant: `redirect_uri` is not a valid URI');
       }
 
+      // optional: PKCE code challenge
+
+      if (code.codeChallenge) {
+        if (!request.body.code_verifier) {
+          throw new InvalidGrantError('Missing parameter: `code_verifier`');
+        }
+
+        const hash = pkce.getHashForCodeChallenge({
+          method: code.codeChallengeMethod,
+          verifier: request.body.code_verifier
+        });
+
+        if (!hash) {
+          // notice that we assume that codeChallengeMethod is already
+          // checked at an earlier stage when being read from
+          // request.body.code_challenge_method
+          throw new ServerError('Server error: `getAuthorizationCode()` did not return a valid `codeChallengeMethod` property');
+        }
+
+        if (code.codeChallenge !== hash) {
+          throw new InvalidGrantError('Invalid grant: code verifier is invalid');
+        }
+      }
+      else {
+        if (request.body.code_verifier) {
+          // No code challenge but code_verifier was passed in.
+          throw new InvalidGrantError('Invalid grant: code verifier is invalid');
+        }
+      }
+
       return code;
     });
 };

lib/handlers/token-handler.js

@@ -19,6 +19,7 @@ const UnauthorizedClientError = require('../errors/unauthorized-client-error');
 const UnsupportedGrantTypeError = require('../errors/unsupported-grant-type-error');
 const auth = require('basic-auth');
 const is = require('../validator/is');
+const pkce = require('../pkce/pkce');
 
 /**
  * Grant types.
@@ -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);
+  }
+};

lib/utils/string-util.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * Export `StringUtil`.
+ */
+
+module.exports = {
+  /**
+   *
+   * @param str
+   * @return {string}
+   */
+  base64URLEncode: function(str) {
+    return str.toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=/g, '');
+  }
+};

lib/utils/token-util.js

@@ -4,8 +4,8 @@
  * Module dependencies.
  */
 
-const crypto = require('crypto');
 const randomBytes = require('bluebird').promisify(require('crypto').randomBytes);
+const { createHash } = require('../utils/crypto-util');
 
 /**
  * Export `TokenUtil`.
@@ -19,10 +19,7 @@ module.exports = {
 
   generateRandomToken: function() {
     return randomBytes(256).then(function(buffer) {
-      return crypto
-        .createHash('sha256')
-        .update(buffer)
-        .digest('hex');
+      return createHash({ data: buffer, encoding: 'hex' });
     });
   }