fixes: state not saved when using handleEmailVerify

docs/idx.md

@@ -68,7 +68,7 @@ This module provides convenience methods to support popular scenarios to communi
 
 #### Flow
 
-In addition to the default authentication flow, this SDK supports several pre-defined flows, such as [register](#idxregister) and [recoverPassword](#idxrecoverpassword). A flow can be started by calling one of the available [flow entrypoints](#flow-entrypoints) or by passing a valid flow identifier string to [`startTransaction`](#idxstarttransaction). The `flow` is saved with the transaction which enables the [proceed](#idxproceed) method to corrrectly handle remediations without additional context. Starting a new flow discards any existing in-progress transaction of a different type. For example, if an authentication flow is in-progress, a call to [authenticate](#idxauthenticate) or [proceed](#idxproceed) will continue using the current transaction but a call to [register](#idxregister) or [recoverPassword](#idxrecoverpassword) will start a new transaction.
+In addition to the default authentication flow, this SDK supports several pre-defined flows, such as [register](#idxregister), [recoverPassword](#idxrecoverpassword) and [unlockAccount](#idxunlockaccount). A flow can be started by calling one of the available [flow entrypoints](#flow-entrypoints) or by passing a valid flow identifier string to [`startTransaction`](#idxstarttransaction). The `flow` is saved with the transaction which enables the [proceed](#idxproceed) method to corrrectly handle remediations without additional context. Starting a new flow discards any existing in-progress transaction of a different type. For example, if an authentication flow is in-progress, a call to [authenticate](#idxauthenticate) or [proceed](#idxproceed) will continue using the current transaction but a call to a [flow entrypoint](#flow-entrypoints) will start a new transaction.
 
 ```javascript
 
@@ -88,6 +88,7 @@ The [flow](#flow) is set automatically when calling one of these methods:
 - [`idx.authenticate`](#idxauthenticate)
 - [`idx.register`](#idxregister)
 - [`idx.recoverPassword`](#idxrecoverpassword)
+- [`idx.unlockAccount`](#idxunlockaccount)
 
 The `flow` will be set to `default` unless otherwise specified in [`idx.startTransaction`](#idxstarttransaction)
 
@@ -428,6 +429,56 @@ const {
 } = await authClient.idx.proceed({ password: 'xxx' });
 ```
 
+#### `idx.unlockAccount`
+
+The convenience method for starting a self service account recovery` flow.
+
+Example (Account unlock with email authenticator verification)
+
+**Up-Front**:
+
+```javascript
+const { 
+  status, // IdxStatus.PENDING
+  nextStep: { 
+    inputs // [{ name: 'verificationCode', ... }]
+  }
+} = await authClient.idx.unlockAccount({
+  username: 'xxx',
+  authenticators: [AuthenticatorKey.OKTA_EMAIL /* 'okta_email' */]
+});
+// submit verification code
+const { 
+  status,  // IdxStatus.TERMINAL
+  messages // 'Your Account is now unlocked!'
+} = await authClient.idx.proceed({ verificationCode: 'xxx' });
+```
+
+**On-Demand**:
+
+```javascript
+const { 
+  status, // IdxStatus.PENDING
+  nextStep: { 
+    inputs // [{ name: 'username', ... }]
+  } 
+} = await authClient.idx.unlockAccount();
+// gather username from user input and
+// user sees a list of authenticators and selects "email"
+const { 
+  status, // IdxStatus.PENDING
+  nextStep: { 
+    inputs, // [{ name: 'authenticator', ... }] 
+    options // [{ name: 'email', ... }, ...]
+  } 
+} = await authClient.idx.proceed({ username, authenticator: AuthenticatorKey.OKTA_EMAIL });
+// gather verification code from email (this call should happen in a separated request)
+const { 
+  status,  // IdxStatus.TERMINAL
+  messages // 'Your Account is now unlocked!'
+} = await authClient.idx.proceed({ verificationCode: 'xxx' });
+```
+
 #### `idx.start`
 
 Alias for [idx.startTransaction](#idxstarttransaction)

lib/idx/emailVerify.ts

@@ -15,7 +15,6 @@ import { OktaAuthInterface } from '../types';
 
 import CustomError from '../errors/CustomError';
 import { urlParamsToObject  } from '../oidc/util/urlParams';
-import { saveTransactionMeta } from './transactionMeta';
 
 export interface EmailVerifyCallbackResponse {
   state: string;
@@ -51,7 +50,6 @@ export function parseEmailVerifyCallback(urlPath: string): EmailVerifyCallbackRe
 export async function handleEmailVerifyCallback(authClient: OktaAuthInterface, search: string) {
   if (isEmailVerifyCallback(search)) {
     const { state, otp } = parseEmailVerifyCallback(search);
-    await saveTransactionMeta(authClient, { state });
     if (authClient.idx.canProceed({ state })) {
       // same browser / device
       return await authClient.idx.proceed({ state, otp });

lib/idx/run.ts

@@ -26,7 +26,7 @@ import {
   FlowIdentifier,
 } from '../types';
 import { IdxResponse, isIdxResponse } from './types/idx-js';
-import { getSavedTransactionMeta } from './transactionMeta';
+import { getSavedTransactionMeta, saveTransactionMeta } from './transactionMeta';
 import { ProceedOptions } from './proceed';
 
 export type RunOptions = ProceedOptions & RemediateOptions & {
@@ -234,6 +234,10 @@ export async function run(
   if (shouldClearTransaction) {
     authClient.transactionManager.clear({ clearSharedStorage });
   }
+  else if (meta?.state) {
+    // ensures state is saved to sessionStorage
+    saveTransactionMeta(authClient, { ...meta });
+  }
 
   // from idx-js, used by the widget
   const { actions, context, neededToProceed, proceed, rawIdxState } = idxResponse || {};

test/apps/react-oie/config-overrides.js

@@ -6,7 +6,7 @@ envModule.setEnvironmentVarsFromTestEnv();
 
 const env = {};
 // List of environment variables made available to the app
-['ISSUER', 'CLIENT_ID'].forEach((key) => {
+['ISSUER', 'SPA_CLIENT_ID', 'CLIENT_ID'].forEach((key) => {
   if (!process.env[key]) {
     throw new Error(`Environment variable ${key} must be set. See README.md`);
   }

test/apps/react-oie/src/App.js

@@ -142,6 +142,7 @@ export default function App() {
       <button onClick={startIdxFlow('authenticate')}>Login</button>
       <button onClick={startIdxFlow('recoverPassword')}>Recover Password</button>
       <button onClick={startIdxFlow('register')}>Registration</button>
+      <button onClick={startIdxFlow('unlockAccount')}>Unlock Account</button>
       <button onClick={startIdxFlow('idp')}>IDP</button>
     </div>
   );

test/spec/idx/emailVerify.ts

@@ -7,15 +7,6 @@ import {
   EmailVerifyCallbackError
 } from '../../../lib/idx/emailVerify';
 
-jest.mock('../../../lib/idx/transactionMeta', () => {
-  const actual = jest.requireActual('../../../lib/idx/transactionMeta');
-  return {
-    ...actual,
-    getSavedTransactionMeta: () => {},
-    saveTransactionMeta: () => {}
-  };
-});
-
 describe('emailVerify', () => {
 
   describe('isEmailVerifyCallback', () => {

test/spec/idx/run.ts

@@ -17,7 +17,8 @@ import { IdxResponseFactory } from '@okta/test.support/idx';
 
 jest.mock('../../../lib/idx/transactionMeta', () => {
   return {
-    getSavedTransactionMeta: () => {}
+    getSavedTransactionMeta: () => {},
+    saveTransactionMeta: () => {}
   };
 });
 
@@ -234,6 +235,14 @@ describe('idx/run', () => {
         status: IdxStatus.PENDING,
       });
     });
+
+    it('saves `state` in transaction meta', async () => {
+      const { authClient, transactionMeta } = testContext;
+
+      jest.spyOn(mocked.transactionMeta, 'saveTransactionMeta');
+      await run(authClient);
+      expect(mocked.transactionMeta.saveTransactionMeta).toHaveBeenCalledWith(authClient, transactionMeta);
+    });
   });
 
   describe('response is terminal', () => {