feat: authorize & onboard accepts pkce & codeChallenge options

`codeChallenge` - usually generated from a server from a code verifier,
pass this value to the authorize or onboard call and it redirects
back to the server where the token exchanging happens without
exposing the code verifier to the client side application.

`pkce` - this will tells the SDK to auto generate a code challenge,
this use case is for an application who wish to authorize or onboard
with PKCE flow and exchange the token on the client side.

Author: mt-max

docs/README.md

@@ -84,8 +84,9 @@ mtLinkSdk.authorize(options);
 | <span id="api-authorize_options">options</span> | object | false | Value set during `init`. | Optional parameters as described in [common options](#common-api-options). |
 | options.scopes | string <p><strong>OR</strong></p> string[] | false | Value set during `init`.<p><strong>OR</strong></p>`guest_read` | Access scopes you're requesting. This can be a single scope, or an array of scopes.<br /><br />Currently supported scopes are:<br />`guest_read`, `accounts_read`, `points_read`, `point_transactions_read`, `transactions_read`, `transactions_write`, `expense_claims_read`, `categories_read`, `investment_accounts_read`, `investment_transactions_read`, `notifications_read`, `request_refresh`, `life_insurance_read`. |
 | options.redirectUri | string | false | Value set during `init`. | OAuth redirection URI, refer [here](https://www.oauth.com/oauth2-servers/redirect-uris/) for more details.<br /><br /><strong>NOTE:</strong> This function will throw an error if this value is undefined <strong>and</strong> no default value was provided in the [init options](?id=api-init_options). |
-| options.state | string | false | You can pass in an optional value here during OAuth authorization request and validate the value is still same after an OAuth redirection. [Click here](https://tools.ietf.org/html/rfc6749#section-4.1.1)|
-| options.codeVerifier | string | false | Value set during `init`. | We only support SHA256, therefore this `codeVerifier` will be used to generate the `code_challenge` using the SHA256 hash algorithm. [Click here](https://auth0.com/docs/api-auth/tutorials/authorization-code-grant-pkce) for more details.</p><strong>NOTE:</strong> Make sure to set this value explicitly if your server generates an identifier for the OAuth authorization request so that you can use to acquire the access token after the OAuth redirect occurs. |
+| options.state | string | false | Value set during `init`.<p><strong>OR</strong></p>Randomly generated [uuid](<https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)>). | Refer [here](https://auth0.com/docs/protocols/oauth2/oauth-state) for more details.<br /><br /><strong>NOTE:</strong> Make sure to set this value explicitly if your server generates an identifier for the OAuth authorization request so that you can use to acquire the access token after the OAuth redirect occurs. |
+| options.codeChallenge | string | false | | We only support SHA256 as code challenge method, therefore please ensure the `code_challenge` was generated using the SHA256 hash algorithm. [Click here](https://auth0.com/docs/api-auth/tutorials/authorization-code-grant-pkce) for more details.</p><strong>NOTE:</strong> Set this value only if your server wish to use PKCE flow. |
+| options.pkce | boolean | false | false | Set to `true` if you wish to use PKCE flow on the client side, SDK will automatically generate the code challenge from a locally generated code verifier and use the code verifier in [exchangeToken](#exchangetoken).  |
 | <span id="authorize_option_force_logout">options.forceLogout</span> | boolean | false | `false` | Force existing guest session to logout and call authorize with a clean state. |
 | options.country | `AU`, ` JP` | false | Value set during `init`. | Server location for the guest to login or sign up. If you wish to restrict your guest to only one country, make sure to set this value.<br /><br /><strong>NOTE:</strong> For apps created after 2020-07-08, the sign up form will display a country selection dropdown for the guest to select a country when this value is undefined or invalid. |
 
@@ -117,8 +118,6 @@ mtLinkSdk.onboard(options)
 
 Since we are using PKCE/Code grant, we will have to exchange the `code` for a token. You can optionally pass `code` via options parameter or it will fallback to automatically extract it from the browser URL.
 
-Options for the, `codeVerifier` and `onboard` calls will use the default value from `init`, however if you explicitly pass a new value when calling `authorize` or `onboard` via the options parameter, make sure to reuse the same value when calling this API, otherwise the authentication server will throw an error due to a value mismatch.
-
 `code` will be invalidated (can be used only once) after exchanged for a token, it is your responsibility to store the token yourself as the SDK does not store it internally.
 
 Refer [here](https://www.oauth.com/oauth2-servers/pkce/authorization-code-exchange/) for more details.
@@ -138,7 +137,7 @@ const token = await mtLinkSdk.exchangeToken(options);
 | - | - | - | - | - |
 | options | object | false | Value set during `init`. | Optional parameters. |
 | options.code | string | false | Value from browser URL | Code from OAuth redirection used to exchange for a token, SDK will try to extract it from the browser URL if none is provided.<br /><br /><strong>NOTE:</strong> SDK will throw an error if no value is provided here and the client library failed to extract it from browser URL. |
-| options.codeVerifier | string | false | Value set during `init`. | Make sure the value of `codeVerifier` here is the same codeVerifier value used during the `authorize` or `onboard` call. |
+| options.codeVerifier | string | false | | If you pass a `codeChallenge` option during the `authorize` or `onboard` call and wish to exchange the token on the client side application, make sure to set the code verifier used to generate the said `codeChallenge` here. |
 | options.redirectUri | string | false | Value set during `init`. | Make sure the value of `redirectUri` here is the same redirectUri value used during the `authorize` or `onboard` call.<br /><br /><strong>NOTE:</strong> The SDK will throw an error if both this parameter and the default value from the [init options](?id=api-init_options) are undefined. |
 
 ### tokenInfo

src/api/authorize.ts

@@ -1,16 +1,17 @@
 import { stringify } from 'qs';
-import { createHash } from 'crypto';
-import { encode } from 'url-safe-base64';
 
-import { constructScopes, generateConfigs, mergeConfigs, getIsTabValue } from '../helper';
+import {
+  constructScopes,
+  generateConfigs,
+  mergeConfigs,
+  getIsTabValue,
+  generateCodeChallenge,
+} from '../helper';
 import { MY_ACCOUNT_DOMAINS } from '../server-paths';
 import { StoredOptions, AuthorizeOptions } from '../typings';
 import storage from '../storage';
 
-export default function authorize(
-  storedOptions: StoredOptions,
-  options: AuthorizeOptions = {}
-): void {
+export default function authorize(storedOptions: StoredOptions, options: AuthorizeOptions = {}): void {
   if (!window) {
     throw new Error('[mt-link-sdk] `authorize` only works in the browser.');
   }
@@ -22,7 +23,6 @@ export default function authorize(
     locale,
     scopes: defaultScopes,
     redirectUri: defaultRedirectUri,
-    codeVerifier: defaultCodeVerifier,
     country: defaultCountry,
   } = storedOptions;
 
@@ -33,36 +33,32 @@ export default function authorize(
   const {
     scopes = defaultScopes,
     redirectUri = defaultRedirectUri,
-    codeVerifier = defaultCodeVerifier,
     country = defaultCountry,
+    pkce = false,
+    codeChallenge,
     isNewTab,
     state,
     ...rest
   } = options;
 
-  // update codeVerifier
-  if (codeVerifier !== defaultCodeVerifier) {
-    storage.set('codeVerifier', codeVerifier);
-  }
-
   if (!redirectUri) {
     throw new Error(
       '[mt-link-sdk] Missing option `redirectUri` in `authorize`, make sure to pass one via `authorize` options or `init` options.'
     );
   }
 
-  const codeChallenge =
-    codeVerifier &&
-    encode(createHash('sha256').update(codeVerifier).digest('base64').split('=')[0]);
+  storage.del('cv');
+
+  const cc = codeChallenge || (pkce && generateCodeChallenge());
 
   const queryString = stringify({
     client_id: clientId,
     cobrand_client_id: cobrandClientId,
     response_type: 'code',
     scope: constructScopes(scopes),
     redirect_uri: redirectUri,
-    code_challenge: codeChallenge || undefined,
-    code_challenge_method: codeVerifier ? 'S256' : undefined,
+    code_challenge: cc || undefined,
+    code_challenge_method: cc ? 'S256' : undefined,
     state,
     country,
     locale,

src/api/exchange-token.ts

@@ -2,6 +2,7 @@ import qs from 'qs';
 
 import { MY_ACCOUNT_DOMAINS } from '../server-paths';
 import { StoredOptions, ExchangeTokenOptions } from '../typings';
+import storage from '../storage';
 
 function getCode(): string | undefined {
   // not available in node environment
@@ -23,8 +24,7 @@ export default async function exchangeToken(
   const {
     clientId,
     redirectUri: defaultRedirectUri,
-    mode,
-    codeVerifier: defaultCodeVerifier,
+    mode
   } = storedOptions;
 
   if (!clientId) {
@@ -33,8 +33,8 @@ export default async function exchangeToken(
 
   const {
     redirectUri = defaultRedirectUri,
-    codeVerifier = defaultCodeVerifier,
     code = getCode(),
+    codeVerifier,
   } = options;
 
   if (!code) {
@@ -60,8 +60,7 @@ export default async function exchangeToken(
         client_id: clientId,
         grant_type: 'authorization_code',
         redirect_uri: redirectUri,
-        code_verifier: codeVerifier || undefined,
-        code_challenge_method: codeVerifier ? 'S256' : undefined,
+        code_verifier: codeVerifier || (code ? storage.get('cv') : undefined),
       }),
     });
 

src/api/onboard.ts

@@ -1,8 +1,12 @@
 import { stringify } from 'qs';
-import { createHash } from 'crypto';
-import { encode } from 'url-safe-base64';
 
-import { constructScopes, generateConfigs, mergeConfigs, getIsTabValue } from '../helper';
+import {
+  constructScopes,
+  generateConfigs,
+  mergeConfigs,
+  getIsTabValue,
+  generateCodeChallenge,
+} from '../helper';
 import { MY_ACCOUNT_DOMAINS } from '../server-paths';
 import { StoredOptions, OnboardOptions } from '../typings';
 import storage from '../storage';
@@ -19,7 +23,6 @@ export default function onboard(storedOptions: StoredOptions, options: OnboardOp
     locale,
     scopes: defaultScopes,
     redirectUri: defaultRedirectUri,
-    codeVerifier: defaultCodeVerifier,
     country: defaultCountry,
   } = storedOptions;
 
@@ -30,32 +33,29 @@ export default function onboard(storedOptions: StoredOptions, options: OnboardOp
   const {
     scopes = defaultScopes,
     redirectUri = defaultRedirectUri,
-    codeVerifier = defaultCodeVerifier,
     country = defaultCountry,
+    pkce = false,
+    codeChallenge,
     isNewTab,
     state,
     ...rest
   } = options;
+
   const configs = mergeConfigs(storedOptions, rest, [
     'authAction',
     'showAuthToggle',
     'showRememberMe',
     'forceLogout',
   ]);
 
-  const { email } = configs;
-
-  // update codeVerifier
-  if (codeVerifier !== defaultCodeVerifier) {
-    storage.set('codeVerifier', codeVerifier);
-  }
-
   if (!redirectUri) {
     throw new Error(
       '[mt-link-sdk] Missing option `redirectUri` in `onboard`, make sure to pass one via `onboard` options or `init` options.'
     );
   }
 
+  const { email } = configs;
+
   if (!email) {
     throw new Error(
       '[mt-link-sdk] Missing option `email` in `onboard`, make sure to pass one via `onboard` options or `init` options.'
@@ -68,18 +68,18 @@ export default function onboard(storedOptions: StoredOptions, options: OnboardOp
     );
   }
 
-  const codeChallenge =
-    codeVerifier &&
-    encode(createHash('sha256').update(codeVerifier).digest('base64').split('=')[0]);
+  storage.del('cv');
+
+  const cc = codeChallenge || (pkce && generateCodeChallenge());
 
   const queryString = stringify({
     client_id: clientId,
     cobrand_client_id: cobrandClientId,
     response_type: 'code',
     scope: constructScopes(scopes),
     redirect_uri: redirectUri,
-    code_challenge: codeChallenge || undefined,
-    code_challenge_method: codeVerifier ? 'S256' : undefined,
+    code_challenge: cc || undefined,
+    code_challenge_method: cc ? 'S256' : undefined,
     state,
     country,
     locale,

src/helper.ts

@@ -2,6 +2,10 @@ declare const __VERSION__: string;
 
 import { stringify } from 'qs';
 import { snakeCase } from 'snake-case';
+import { createHash } from 'crypto';
+import { encode } from 'url-safe-base64';
+import { v4 as uuid } from 'uuid';
+import storage from './storage';
 
 import { Scopes, InitOptions, ConfigsOptions, AuthAction } from './typings';
 
@@ -83,3 +87,11 @@ export function generateConfigs(configs: ConfigsOptions = {}): string {
     ...snakeCaseConfigs,
   });
 }
+
+export function generateCodeChallenge(): string {
+  const codeVerifier = uuid();
+
+  storage.set('cv', codeVerifier);
+
+  return encode(createHash('sha256').update(codeVerifier).digest('base64').split('=')[0]);
+}

src/index.ts

@@ -12,12 +12,12 @@ import {
   LogoutOptions,
   InitOptions,
   AuthorizeOptions,
+  OnboardOptions,
   ExchangeTokenOptions,
   RequestMagicLinkOptions,
   TokenInfo,
   Mode,
 } from './typings';
-import storage from './storage';
 
 export * from './typings';
 
@@ -26,7 +26,6 @@ const validModes: Mode[] = ['production', 'staging', 'develop', 'local'];
 export class MtLinkSdk {
   public storedOptions: StoredOptions = {
     mode: 'production',
-    codeVerifier: storage.get('codeVerifier') || '',
   };
 
   public init(clientId: string, options: InitOptions = {}): void {
@@ -43,15 +42,13 @@ export class MtLinkSdk {
       clientId,
       mode: validModes.indexOf(mode) === -1 ? 'production' : mode,
     };
-
-    storage.set('codeVerifier', this.storedOptions.codeVerifier);
   }
 
   public authorize(options?: AuthorizeOptions): void {
     authorize(this.storedOptions, options);
   }
 
-  public onboard(options?: AuthorizeOptions): void {
+  public onboard(options?: OnboardOptions): void {
     onboard(this.storedOptions, options);
   }
 

src/typings.ts

@@ -59,7 +59,6 @@ interface AuthorizeConfigsOptions {
 interface OAuthSharedParams {
   state?: string;
   redirectUri?: string;
-  codeVerifier?: string;
 }
 
 export interface AuthorizeOptions
@@ -68,22 +67,27 @@ export interface AuthorizeOptions
     AuthorizeConfigsOptions {
   country?: string;
   scopes?: Scopes;
+  codeChallenge?: string;
+  pkce?: boolean;
 }
 
 export type Mode = 'production' | 'staging' | 'develop' | 'local';
-export type InitOptions = Omit<AuthorizeOptions, 'forceLogout'> &
+export type InitOptions = Omit<
+  Omit<Omit<AuthorizeOptions, 'forceLogout'>, 'codeChallenge'>,
+  'pkce'
+> &
   PrivateParams & {
     mode?: Mode;
     locale?: string;
   };
 export interface StoredOptions extends InitOptions {
   clientId?: string;
   mode: Mode;
-  codeVerifier: string;
 }
 
 export interface ExchangeTokenOptions extends OAuthSharedParams {
   code?: string;
+  codeVerifier?: string;
 }
 
 export type LogoutOptions = ConfigsOptions;