feat: implement PKCE extension for Authorization Code Grant (RFC 7636) (#240)

* feat: implement PKCE extension for Authorization Code Grant (RFC 7636)

See protocol details here:
https://www.rfc-editor.org/rfc/rfc7636.html

* fix: removes duplicated toString('base64url')

* feat: address PR review and document challenge methods

* fix: swap it in types and args check

Author: big-kahuna-burger

README.md

@@ -206,6 +206,11 @@ fastify.register(oauthPlugin, {
     // custom query param that will be passed to callbackUri
     access_type: 'offline', // will tell Google to send a refreshToken too
   },
+  pkce: 'S256'
+  // check if your provider supports PKCE, 
+  // in case they do, 
+  // use of this parameter is highly encouraged 
+  // in order to prevent authorization code interception attacks
 });
 ```
 
@@ -252,6 +257,14 @@ This fastify plugin adds 5 utility decorators to your fastify instance using the
   - `refresh_token` (optional, only if the `offline scope` was originally requested, as seen in the callbackUriParams example)
   - `token_type` (generally `'Bearer'`)
   - `expires_in` (number of seconds for the token to expire, e.g. `240000`)
+
+- OR `getAccessTokenFromAuthorizationCodeFlow(request, reply, callback)` variant with 3 arguments, which should be used when PKCE extension is used.
+  This allows fastify-oauth2 to delete PKCE code_verifier cookie so it doesn't stay in browser in case server has issue when fetching token. See [Google With PKCE example for more](./examples/google-with-pkce.js).
+  
+  *Important to note*: if your provider supports `S256` as code_challenge_method, always prefer that. 
+  Only use `plain` when your provider doesn't support `S256`.
+
+
 - `getNewAccessTokenUsingRefreshToken(Token, params, callback)`: A function that takes a `AccessToken`-Object as `Token` and retrieves a new `AccessToken`-Object. This is generally useful with background processing workers to re-issue a new AccessToken when the previous AccessToken has expired. The `params` argument is optional and it is an object that can be used to pass in additional parameters to the refresh request (e.g. a stricter set of scopes). If the callback is not passed this function will return a Promise. The object resulting from the callback call or the resolved Promise is a new `AccessToken` object (see above). Example of how you would use it for `name:googleOAuth2`:
 ```js
 fastify.googleOAuth2.getNewAccessTokenUsingRefreshToken(currentAccessToken, (err, newAccessToken) => {

examples/google-with-pkce.js

@@ -0,0 +1,84 @@
+'use strict'
+
+const fastify = require('fastify')({ logger: { level: 'trace' } })
+const sget = require('simple-get')
+
+const cookieOpts = {
+  // domain: 'localhost',
+  path: '/',
+  secure: true,
+  sameSite: 'lax',
+  httpOnly: true
+}
+
+// const oauthPlugin = require('fastify-oauth2')
+fastify.register(require('@fastify/cookie'), {
+  secret: ['my-secret'],
+  parseOptions: cookieOpts
+})
+
+const oauthPlugin = require('..')
+fastify.register(oauthPlugin, {
+  name: 'googleOAuth2',
+  scope: ['openid', 'profile', 'email'],
+  credentials: {
+    client: {
+      id: process.env.CLIENT_ID,
+      secret: process.env.CLIENT_SECRET
+    },
+    auth: oauthPlugin.GOOGLE_CONFIGURATION
+  },
+  startRedirectPath: '/login/google',
+  callbackUri: 'http://localhost:3000/interaction/callback/google',
+  cookie: cookieOpts,
+  pkce: 'S256'
+  /* use S256:
+
+  Most modern providers (authorization servers) that are up to date with standards,
+  will support S256 and also announce that in discovery endpoint (.well-known/openid-configuration):
+  ...
+  "code_challenge_methods_supported": [
+    "S256",
+    "plain"
+  ]
+  ...
+
+  "plain" is also supported in this library but it's use is discouraged.
+  Only do it in case that you use some legacy provider (authorization server),
+  and you see provider's .well-known/openid-configuration
+  endpoint has only that single challenge method:
+  ...
+  "code_challenge_methods_supported": [
+    "plain"
+  ]
+  */
+})
+
+fastify.get('/interaction/callback/google', function (request, reply) {
+  // Note that in this example a "reply" is also passed, it's so that code verifier cookie can be cleaned before
+  // token is requested from token endpoint
+  this.googleOAuth2.getAccessTokenFromAuthorizationCodeFlow(request, reply, (err, result) => {
+    if (err) {
+      reply.send(err)
+      return
+    }
+
+    sget.concat({
+      url: 'https://www.googleapis.com/oauth2/v2/userinfo',
+      method: 'GET',
+      headers: {
+        Authorization: 'Bearer ' + result.token.access_token
+      },
+      json: true
+    }, function (err, res, data) {
+      if (err) {
+        reply.send(err)
+        return
+      }
+      reply.send(data)
+    })
+  })
+})
+
+fastify.listen({ port: 3000 })
+fastify.log.info('go to http://localhost:3000/login/google')

index.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { randomBytes } = require('node:crypto')
+const { randomBytes, createHash } = require('node:crypto')
 
 const fp = require('fastify-plugin')
 const { AuthorizationCode } = require('simple-oauth2')
@@ -9,9 +9,15 @@ const kGenerateCallbackUriParams = Symbol.for('fastify-oauth2.generate-callback-
 const { promisify, callbackify } = require('node:util')
 
 const USER_AGENT = 'fastify-oauth2'
+const VERIFIER_COOKIE_NAME = 'oauth2-code-verifier'
+const PKCE_METHODS = ['S256', 'plain']
+
+const random = (bytes = 32) => randomBytes(bytes).toString('base64url')
+const codeVerifier = random
+const codeChallenge = verifier => createHash('sha256').update(verifier).digest('base64url')
 
 function defaultGenerateStateFunction () {
-  return randomBytes(16).toString('base64url')
+  return random(16)
 }
 
 function defaultCheckStateFunction (request, callback) {
@@ -74,7 +80,9 @@ function fastifyOauth2 (fastify, options, next) {
   if (options.userAgent && typeof options.userAgent !== 'string') {
     return next(new Error('options.userAgent should be a string'))
   }
-
+  if (options.pkce && (typeof options.pkce !== 'string' || !PKCE_METHODS.includes(options.pkce))) {
+    return next(new Error('options.pkce should be one of "S256" | "plain" when used'))
+  }
   if (!fastify.hasReplyDecorator('cookie')) {
     fastify.register(require('@fastify/cookie'))
   }
@@ -89,7 +97,8 @@ function fastifyOauth2 (fastify, options, next) {
     checkStateFunction = defaultCheckStateFunction,
     startRedirectPath,
     tags = [],
-    schema = { tags }
+    schema = { tags },
+    pkce
   } = options
 
   const userAgent = options.userAgent === false
@@ -113,11 +122,23 @@ function fastifyOauth2 (fastify, options, next) {
 
     reply.setCookie('oauth2-redirect-state', state, cookieOpts)
 
+    // when PKCE extension is used
+    let pkceParams = {}
+    if (pkce) {
+      const verifier = codeVerifier()
+      const challenge = pkce === 'S256' ? codeChallenge(verifier) : verifier
+      pkceParams = {
+        code_challenge: challenge,
+        code_challenge_method: pkce
+      }
+      reply.setCookie(VERIFIER_COOKIE_NAME, verifier, cookieOpts)
+    }
+
     const urlOptions = Object.assign({}, generateCallbackUriParams(callbackUriParams, request, scope, state), {
       redirect_uri: callbackUri,
       scope,
       state
-    })
+    }, pkceParams)
 
     return oauth2.authorizeURL(urlOptions)
   }
@@ -128,34 +149,44 @@ function fastifyOauth2 (fastify, options, next) {
     reply.redirect(authorizationUri)
   }
 
-  const cbk = function (o, code, callback) {
+  const cbk = function (o, code, pkceParams, callback) {
     const body = Object.assign({}, tokenRequestParams, {
       code,
       redirect_uri: callbackUri
-    })
+    }, pkceParams)
 
     return callbackify(o.oauth2.getToken.bind(o.oauth2, body))(callback)
   }
 
-  function getAccessTokenFromAuthorizationCodeFlowCallbacked (request, callback) {
+  function getAccessTokenFromAuthorizationCodeFlowCallbacked (request, reply, callback) {
     const code = request.query.code
+    const pkceParams = pkce ? { code_verifier: request.cookies['oauth2-code-verifier'] } : {}
+
+    const _callback = typeof reply === 'function' ? reply : callback
+
+    if (reply && typeof reply !== 'function') {
+      // cleanup a cookie if plugin user uses (req, res, cb) signature variant of getAccessToken fn
+      clearCodeVerifierCookie(reply)
+    }
 
     checkStateFunction(request, function (err) {
       if (err) {
         callback(err)
         return
       }
-      cbk(fastify[name], code, callback)
+      cbk(fastify[name], code, pkceParams, _callback)
     })
   }
 
   const getAccessTokenFromAuthorizationCodeFlowPromisified = promisify(getAccessTokenFromAuthorizationCodeFlowCallbacked)
 
-  function getAccessTokenFromAuthorizationCodeFlow (request, callback) {
-    if (!callback) {
-      return getAccessTokenFromAuthorizationCodeFlowPromisified(request)
+  function getAccessTokenFromAuthorizationCodeFlow (request, reply, callback) {
+    const _callback = typeof reply === 'function' ? reply : callback
+
+    if (!_callback) {
+      return getAccessTokenFromAuthorizationCodeFlowPromisified(request, reply)
     }
-    getAccessTokenFromAuthorizationCodeFlowCallbacked(request, callback)
+    getAccessTokenFromAuthorizationCodeFlowCallbacked(request, reply, _callback)
   }
 
   function getNewAccessTokenUsingRefreshTokenCallbacked (refreshToken, params, callback) {
@@ -200,6 +231,10 @@ function fastifyOauth2 (fastify, options, next) {
     revokeAllTokenCallbacked(token, params, callback)
   }
 
+  function clearCodeVerifierCookie (reply) {
+    reply.clearCookie(VERIFIER_COOKIE_NAME, cookieOpts)
+  }
+
   const oauth2 = new AuthorizationCode(credentials)
 
   if (startRedirectPath) {