Merge pull request lelylan#328 from lelylan/feature/refresh-persistent-access-tokens

Add support to refresh persistent access tokens

Author: jonathansamines

API.md

@@ -60,6 +60,9 @@ Additional options will be automatically serialized as params for the token requ
 
 * `httpOptions` All [wreck](https://github.com/hapijs/wreck) options can be overriden as documented by the module `http` options.
 
+#### .createToken(token) => AccessToken
+Creates a new access token by providing a valid plain token object.
+
 ### new ResourceOwnerPassword(options)
 This submodule provides support for the OAuth2 [Resource Owner Password Credentials](https://oauth.net/2/grant-types/password/) grant type.
 
@@ -75,6 +78,9 @@ Additional options will be automatically serialized as params for the token requ
 
 * `httpOptions` All [wreck](https://github.com/hapijs/wreck) options can be overriden as documented by the module `http` options.
 
+#### .createToken(token) => AccessToken
+Creates a new access token by providing a valid plain token object.
+
 ### new ClientCredentials(options)
 This submodule provides support for the OAuth2 [Client Credentials](https://oauth.net/2/grant-types/client-credentials/) grant type.
 
@@ -88,6 +94,9 @@ Additional options will be automatically serialized as params for the token requ
 
 * `httpOptions` All [wreck](https://github.com/hapijs/wreck) options can be overriden as documented by the module `http` options.
 
+#### .createToken(token) => AccessToken
+Creates a new access token by providing a valid plain token object.
+
 ### AccessToken
 #### .expired([expirationWindowSeconds]) => Boolean
 Determines if the current access token is definitely expired or not
@@ -107,3 +116,8 @@ Revokes either the access or refresh token depending on the {tokenType} value. T
 
 #### .revokeAll() => Promise
 Revokes both the current access and refresh tokens
+
+#### .token
+Immutable object containing the token object provided while constructing a new access token instance. This property will usually have the schema as specified by [RFC6750](https://tools.ietf.org/html/rfc6750#section-4), but the exact properties may vary between authorization servers.
+
+Please also note, that the current implementation will always add an **expires_at** property regardless of the authorization server response, as we require it to to provide the refresh token functionality.

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 
 ## Next
+### Improvements
+- Add support to refresh persitent access tokens
+
 ### Maintainance
 - Remove usage of [date-fns](https://date-fns.org/) production dependency
 - Setup [volta](https://volta.sh/) instead of nvm to handle node versions

README.md

@@ -159,7 +159,32 @@ On completion of any [supported grant type](#supported-grant-types) an access to
 
 #### Refresh an access token
 
-When a token expires we need a mechanism to obtain a new access token. The [AccessToken](./API.md#accesstoken) methods can be used to perform the token refresh process.
+On long lived applications, it is often necessary to refresh access tokens. In such scenarios the access token is usually persisted in an external database by first serializing it.
+
+
+```javascript
+async function run() {
+  const accessTokenJSONString = JSON.stringify(accessToken);
+
+  await persistAccessTokenJSON(accessTokenJSONString);
+}
+
+run();
+```
+
+By the time we need to refresh the persistent access token, we can get back an [AccessToken](./API.md#accesstoken) instance by using the client's [.createToken](./API.md#createtokentoken--accesstoken) method.
+
+```javascript
+async function run() {
+  const accessTokenJSONString = await getPersistedAccessTokenJSON();
+
+  let accessToken = client.createToken(JSON.parse(accessTokenJSONString));
+}
+
+run();
+```
+
+Once we have determined the access token needs refreshing with the [.expired()](./API.md##expiredexpirationwindowseconds--boolean) method, we can finally refresh it with a [.refresh()](#refreshparams--promiseaccesstoken) method call.
 
 ```javascript
 async function run() {
@@ -179,7 +204,7 @@ async function run() {
 run();
 ```
 
-The `expired` helper is useful for knowing when a token has definitively expired. However, there is a common race condition when tokens are near expiring. If an OAuth 2.0 token is issued with a `expires_in` property (as opposed to an `expires_at` property), there can be discrepancies between the time the OAuth 2.0 server issues the access token and when it is received.
+The [.expired()](./API.md##expiredexpirationwindowseconds--boolean) helper is useful for knowing when a token has definitively expired. However, there is a common race condition when tokens are near expiring. If an OAuth 2.0 token is issued with a `expires_in` property (as opposed to an `expires_at` property), there can be discrepancies between the time the OAuth 2.0 server issues the access token and when it is received.
 
 These come down to factors such as network and processing latency and can be worked around by preemptively refreshing the access token:
 

lib/access-token/index.js

@@ -79,4 +79,13 @@ module.exports = class AccessToken {
     await this.revoke(ACCESS_TOKEN_PROPERTY_NAME);
     await this.revoke(REFRESH_TOKEN_PROPERTY_NAME);
   }
+
+  /**
+   * Get the access token's internal JSON representation
+   *
+   * @returns {String}
+   */
+  toJSON() {
+    return this.token;
+  }
 };

lib/grants/authorization-code.js

@@ -49,6 +49,16 @@ module.exports = class AuthorizationCode {
     const parameters = GrantParams.forGrant('authorization_code', this.#config.options, params);
     const response = await this.#client.request(this.#config.auth.tokenPath, parameters.toObject(), httpOptions);
 
-    return new AccessToken(this.#config, this.#client, response);
+    return this.createToken(response);
+  }
+
+  /**
+   * Creates a new access token instance from a plain object
+   *
+   * @param {Object} token Plain object representation of an access token
+   * @returns {AccessToken}
+   */
+  createToken(token) {
+    return new AccessToken(this.#config, this.#client, token);
   }
 };

lib/grants/client-credentials.js

@@ -24,6 +24,16 @@ module.exports = class ClientCredentials {
     const parameters = GrantParams.forGrant('client_credentials', this.#config.options, params);
     const response = await this.#client.request(this.#config.auth.tokenPath, parameters.toObject(), httpOptions);
 
-    return new AccessToken(this.#config, this.#client, response);
+    return this.createToken(response);
+  }
+
+  /**
+   * Creates a new access token instance from a plain object
+   *
+   * @param {Object} token Plain object representation of an access token
+   * @returns {AccessToken}
+   */
+  createToken(token) {
+    return new AccessToken(this.#config, this.#client, token);
   }
 };

lib/grants/resource-owner-password.js

@@ -26,6 +26,16 @@ module.exports = class ResourceOwnerPassword {
     const parameters = GrantParams.forGrant('password', this.#config.options, params);
     const response = await this.#client.request(this.#config.auth.tokenPath, parameters.toObject(), httpOptions);
 
-    return new AccessToken(this.#config, this.#client, response);
+    return this.createToken(response);
+  }
+
+  /**
+   * Creates a new access token instance from a plain object
+   *
+   * @param {Object} token Plain object representation of an access token
+   * @returns {AccessToken}
+   */
+  createToken(token) {
+    return new AccessToken(this.#config, this.#client, token);
   }
 };

test/access-token.js

@@ -3,7 +3,12 @@
 const test = require('ava');
 const Chance = require('chance');
 const accessTokenMixin = require('chance-access-token');
-const { isValid, isDate, differenceInSeconds } = require('date-fns');
+const {
+  isValid,
+  isDate,
+  differenceInSeconds,
+  isEqual,
+} = require('date-fns');
 
 const AccessToken = require('../lib/access-token');
 const Client = require('../lib/client');
@@ -125,6 +130,19 @@ test('@create => ignores the expiration parsing when no expiration property is p
   t.not(has(accessToken.token, 'expires_at'));
 });
 
+test('@toJSON => serializes the access token information in an equivalent format', (t) => {
+  const config = createModuleConfig();
+  const client = new Client(config);
+
+  const accessTokenResponse = chance.accessToken();
+
+  const accessToken = new AccessToken(config, client, accessTokenResponse);
+  const restoredAccessToken = new AccessToken(config, client, JSON.parse(JSON.stringify(accessToken)));
+
+  t.deepEqual(restoredAccessToken.token, accessToken.token);
+  t.true(isEqual(restoredAccessToken.token.expires_at, accessToken.token.expires_at));
+});
+
 test('@expired => returns true when expired', (t) => {
   const config = createModuleConfig();
   const client = new Client(config);

test/authorization-code.js

@@ -5,6 +5,7 @@ const { AuthorizationCode } = require('../index');
 const AccessToken = require('../lib/access-token');
 const { createModuleConfig } = require('./_module-config');
 const {
+  getAccessToken,
   createAuthorizationServer,
   getJSONEncodingScopeOptions,
   getFormEncodingScopeOptions,
@@ -173,6 +174,13 @@ test('@authorizeURL => returns the authorization URL with a custom module config
   t.is(actual, expected);
 });
 
+test('@createToken => creates a new access token instance from a JSON object', async (t) => {
+  const oauth2 = new AuthorizationCode(createModuleConfig());
+  const accessToken = oauth2.createToken(getAccessToken());
+
+  t.true(accessToken instanceof AccessToken);
+});
+
 test.serial('@getToken => resolves to an access token (body credentials and JSON format)', async (t) => {
   const expectedRequestParams = {
     grant_type: 'authorization_code',

test/client-credentials.js

@@ -5,12 +5,20 @@ const { ClientCredentials } = require('../index');
 const AccessToken = require('../lib/access-token');
 const { createModuleConfig } = require('./_module-config');
 const {
+  getAccessToken,
   createAuthorizationServer,
   getJSONEncodingScopeOptions,
   getFormEncodingScopeOptions,
   getHeaderCredentialsScopeOptions,
 } = require('./_authorization-server-mock');
 
+test('@createToken => creates a new access token instance from a JSON object', async (t) => {
+  const oauth2 = new ClientCredentials(createModuleConfig());
+  const accessToken = oauth2.createToken(getAccessToken());
+
+  t.true(accessToken instanceof AccessToken);
+});
+
 test.serial('@getToken => resolves to an access token (body credentials and JSON format)', async (t) => {
   const expectedRequestParams = {
     grant_type: 'client_credentials',