feat(mfa): add the soft prompt step to the state machine

Author: dariusz-biela

src/components/MultifactorAuthentication/Context/MultifactorAuthenticationInternalApiContext.ts

@@ -21,6 +21,9 @@ type MultifactorAuthenticationInternalApi = {
     /** Notify the machine that the close animation has fully finished. Called by the modal navigator on teardown; the machine then moves from `closing` back to `closed`. */
     notifyModalClosed: () => void;
 
+    /** Approve the soft prompt. Called by the prompt screen's confirm button; the machine persists the acceptance and moves the flow on. */
+    approveSoftPrompt: () => void;
+
     /** Centralized back-press / backdrop entry. */
     requestCancel: () => void;
 

src/components/MultifactorAuthentication/Context/MultifactorAuthenticationMainContext.tsx

@@ -86,6 +86,7 @@ function MultifactorAuthenticationContextProvider({children}: MultifactorAuthent
 
     const closeModal = () => send({type: 'CLOSE_MODAL'});
     const notifyModalClosed = () => send({type: 'MODAL_CLOSED'});
+    const approveSoftPrompt = () => send({type: 'SOFT_PROMPT_APPROVED'});
 
     // There is no cancel-confirmation dialog yet, so every cancel path closes the modal directly.
     const requestCancel = () => send({type: 'CLOSE_MODAL'});
@@ -100,6 +101,7 @@ function MultifactorAuthenticationContextProvider({children}: MultifactorAuthent
         state,
         closeModal,
         notifyModalClosed,
+        approveSoftPrompt,
         requestCancel,
         hideCancelConfirm,
         confirmCancel,

src/components/MultifactorAuthentication/Context/index.ts

@@ -2,4 +2,3 @@ export {default as MultifactorAuthenticationContextProviders} from './Multifacto
 export {useMultifactorAuthentication} from './MultifactorAuthenticationExternalApiContext';
 export {useMultifactorAuthenticationActions} from './MultifactorAuthenticationActionsContext';
 export {useMultifactorAuthenticationState} from './MultifactorAuthenticationStateContext';
-export {default as usePromptContent} from './usePromptContent';

src/components/MultifactorAuthentication/Context/state.ts

@@ -22,9 +22,6 @@ type MultifactorAuthenticationState = {
     /** Challenge received from backend for authorization (full object with allowCredentials, rpId, challenge) */
     authorizationChallenge: AuthenticationChallenge | undefined;
 
-    /** Whether user approved the soft prompt for biometric setup */
-    softPromptApproved: boolean;
-
     /** Whether registration step has been completed */
     isRegistrationComplete: boolean;
 
@@ -46,7 +43,6 @@ const DEFAULT_STATE: MultifactorAuthenticationState = {
     validateCode: undefined,
     registrationChallenge: undefined,
     authorizationChallenge: undefined,
-    softPromptApproved: false,
     isRegistrationComplete: false,
     isAuthorizationComplete: false,
     isFlowComplete: false,

src/components/MultifactorAuthentication/Context/stateReducer.ts

@@ -25,8 +25,6 @@ function stateReducer(state: MultifactorAuthenticationState, action: Action): Mu
             return {...state, registrationChallenge: action.payload};
         case 'SET_AUTHORIZATION_CHALLENGE':
             return {...state, authorizationChallenge: action.payload};
-        case 'SET_SOFT_PROMPT_APPROVED':
-            return {...state, softPromptApproved: action.payload};
         case 'SET_REGISTRATION_COMPLETE':
             return {...state, isRegistrationComplete: action.payload};
         case 'SET_AUTHORIZATION_COMPLETE':

src/components/MultifactorAuthentication/Context/types.ts

@@ -12,7 +12,6 @@ type Action =
     | {type: 'SET_VALIDATE_CODE'; payload: string | undefined}
     | {type: 'SET_REGISTRATION_CHALLENGE'; payload: RegistrationChallenge | undefined}
     | {type: 'SET_AUTHORIZATION_CHALLENGE'; payload: AuthenticationChallenge | undefined}
-    | {type: 'SET_SOFT_PROMPT_APPROVED'; payload: boolean}
     | {type: 'SET_REGISTRATION_COMPLETE'; payload: boolean}
     | {type: 'SET_AUTHORIZATION_COMPLETE'; payload: boolean}
     | {type: 'SET_FLOW_COMPLETE'; payload: boolean}

src/components/MultifactorAuthentication/Context/usePromptContent.ts

@@ -1,8 +1,11 @@
+import {deviceVerificationType} from '@components/MultifactorAuthentication/biometrics/operations';
 import {navigate as mfaNavigate, resetMfaNavigation} from '@components/MultifactorAuthentication/mfaNavigation';
 
 import {createUnhandledExceptionMFAError, getMFAFailureError} from '@libs/MultifactorAuthentication/shared/MFAResult';
 import Navigation from '@libs/Navigation/Navigation';
 
+import {hasEverAcceptedSoftPrompt, markHasAcceptedSoftPrompt} from '@userActions/MultifactorAuthentication';
+
 import CONST from '@src/CONST';
 import SCREENS from '@src/SCREENS';
 
@@ -14,15 +17,20 @@ import createActors from './mfaActors';
 
 const MFA_STATE = CONST.MULTIFACTOR_AUTHENTICATION.MFA_STATE;
 
-// Absolute target for the outcome branch. The device check runs under `preparing`, so reaching the
-// sibling `outcome` branch needs an id target rather than a relative one.
+// Absolute targets for the screen branches. The device check runs under `preparing`, so reaching a
+// sibling branch needs an id target rather than a relative one.
 const OUTCOME_TARGET = `#${MFA_STATE.OUTCOME}` as const;
+const PROMPT_TARGET = `#${MFA_STATE.PROMPT}` as const;
+
+// Which prompt variant the screen renders is a device property, resolved once per platform.
+const PROMPT_TYPE = CONST.MULTIFACTOR_AUTHENTICATION.PROMPT_TYPE_MAP[deviceVerificationType];
 
 const DEFAULT_CONTEXT: MfaContext = {
     error: undefined,
     scenarioName: undefined,
     scenario: undefined,
     payload: undefined,
+    softPromptApproved: false,
     isCancelConfirmVisible: false,
 };
 
@@ -69,6 +77,13 @@ const MFAMachine = setup({
         navigateToFailureOutcome: () => {
             Navigation.runAfterTransition(() => mfaNavigate(SCREENS.MULTIFACTOR_AUTHENTICATION.OUTCOME_FAILURE));
         },
+        navigateToPrompt: () => {
+            Navigation.runAfterTransition(() => mfaNavigate(SCREENS.MULTIFACTOR_AUTHENTICATION.PROMPT, {promptType: PROMPT_TYPE}));
+        },
+        approveSoftPrompt: assign({softPromptApproved: true}),
+        // The durable "asked once" flag lives in Onyx, so future flows on this device can skip the
+        // prompt. Owned by the machine so every sender of SOFT_PROMPT_APPROVED persists it.
+        persistSoftPromptAcceptance: () => markHasAcceptedSoftPrompt(),
         // Runs on CLOSE_MODAL: drops the cancel-confirmation modal so it cannot linger over the
         // closing navigator (CLOSE_MODAL can fire without the flow completing, e.g. an offline cancel).
         hideCancelConfirmModal: assign({isCancelConfirmVisible: false}),
@@ -119,11 +134,16 @@ const MFAMachine = setup({
                                     }
                                     return {allowedAuthenticationMethods: context.scenario.allowedAuthenticationMethods};
                                 },
-                                // Every result enters the outcome resolver. A refusal stores its
-                                // blocking MFAError first, so the resolver selects failure from that
-                                // error, while an eligible device with no error selects success.
+                                // An eligible device moves on to the soft prompt, with two overrides.
+                                // A stored error always wins: the flow goes straight to the outcome
+                                // resolver, which selects failure. A user who already accepted the
+                                // soft prompt on this device (read from Onyx at decision time) skips
+                                // it. A refusal stores its blocking MFAError first and resolves the
+                                // same way as a stored error.
                                 onDone: [
-                                    {guard: ({event}) => event.output.success, target: OUTCOME_TARGET},
+                                    {guard: ({context, event}) => event.output.success && context.error !== undefined, target: OUTCOME_TARGET},
+                                    {guard: ({event}) => event.output.success && hasEverAcceptedSoftPrompt(), target: OUTCOME_TARGET},
+                                    {guard: ({event}) => event.output.success, target: PROMPT_TARGET},
                                     {target: OUTCOME_TARGET, actions: assign({error: ({event}) => getMFAFailureError(event.output)})},
                                 ],
                                 // Expected refusals travel as failed results through onDone, so a
@@ -136,6 +156,24 @@ const MFAMachine = setup({
                         },
                     },
                 },
+                // The soft-prompt screen: asks the user to consent to biometric verification before
+                // the flow continues. Entered only when the user has never accepted the prompt on
+                // this device; the registration vs reinstall variants arrive with the registration
+                // decision.
+                [MFA_STATE.PROMPT]: {
+                    id: MFA_STATE.PROMPT,
+                    entry: ['navigateToPrompt'],
+                    initial: MFA_STATE.AWAITING_SOFT_PROMPT,
+                    on: {
+                        SOFT_PROMPT_APPROVED: {
+                            target: MFA_STATE.OUTCOME,
+                            actions: ['approveSoftPrompt', 'persistSoftPromptAcceptance'],
+                        },
+                    },
+                    states: {
+                        [MFA_STATE.AWAITING_SOFT_PROMPT]: {},
+                    },
+                },
                 [MFA_STATE.OUTCOME]: {
                     id: MFA_STATE.OUTCOME,
                     initial: MFA_STATE.RESOLVING_OUTCOME,

src/components/MultifactorAuthentication/machine/mfaMachine.ts

@@ -29,6 +29,12 @@ type MfaContext = {
     /** Additional parameters for the current scenario */
     payload: MultifactorAuthenticationScenarioAdditionalParams<MultifactorAuthenticationScenario> | undefined;
 
+    /**
+     * Whether the user approved the soft prompt during this flow. The durable acceptance lives in
+     * Onyx under the device-biometrics key; this flag only tracks the current flow.
+     */
+    softPromptApproved: boolean;
+
     /** Whether the cancel-confirmation modal triggered by a back press is currently visible */
     isCancelConfirmVisible: boolean;
 };
@@ -59,9 +65,10 @@ type MultifactorAuthenticationInitEvent<T extends MultifactorAuthenticationScena
  *
  * CLOSE_MODAL requests the close so the flow moves to `closing`. MODAL_CLOSED is the navigator's
  * notification that the close animation fully finished, which moves `closing` to `closed` and wipes
- * the context.
+ * the context. SOFT_PROMPT_APPROVED is sent by the prompt screen's confirm button and moves the flow
+ * past the soft prompt.
  */
-type MfaEvent = MultifactorAuthenticationInitEvent | {type: 'CLOSE_MODAL'} | {type: 'MODAL_CLOSED'};
+type MfaEvent = MultifactorAuthenticationInitEvent | {type: 'CLOSE_MODAL'} | {type: 'MODAL_CLOSED'} | {type: 'SOFT_PROMPT_APPROVED'};
 
 /** Describes the input the machine passes to the device-check actor. */
 type ValidateDeviceInput = {allowedAuthenticationMethods: AllowedAuthenticationMethods};

src/components/MultifactorAuthentication/machine/types.ts

@@ -221,6 +221,8 @@ const MFA_STATE = {
     CLOSING: 'closing',
     PREPARING: 'preparing',
     VALIDATING_DEVICE: 'validatingDevice',
+    PROMPT: 'prompt',
+    AWAITING_SOFT_PROMPT: 'awaitingSoftPrompt',
     OUTCOME: 'outcome',
     RESOLVING_OUTCOME: 'resolvingOutcome',
     SUCCESS: 'success',
@@ -319,6 +321,7 @@ const SHARED_VALUES = {
         MODAL_BACKDROP: 'MultifactorAuthenticationModalBackdrop',
         OUTCOME_SCREEN: 'MultifactorAuthenticationOutcomeScreen',
         OUTCOME_CONFIRM_BUTTON: 'MultifactorAuthenticationOutcomeConfirmButton',
+        PROMPT_CONFIRM_BUTTON: 'MultifactorAuthenticationPromptConfirmButton',
     },
 } as const;