chore(runway): cherry-pick a172652 (#21831)

- feat(card): Card Onboarding edge cases and Onboarding token management
(#21594)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **Description**

<!--
Write a short description of the changes included in this pull request,
also include relevant motivation and context. Have in mind the following
questions:
1. What is the reason for the change?
2. What is the improvement/solution?
-->

This PR improves the Onboarding flow by adding coverage for several edge
cases and refining the token management strategy for the onboarding
token. These updates ensure more reliable handling of onboarding
sessions and reduce potential authentication inconsistencies.

## **Changelog**

<!--
If this PR is not End-User-Facing and should not show up in the
CHANGELOG, you can choose to either:
1. Write `CHANGELOG entry: null`
2. Label with `no-changelog`

If this PR is End-User-Facing, please write a short User-Facing
description in the past tense like:
`CHANGELOG entry: Added a new tab for users to see their NFTs`
`CHANGELOG entry: Fixed a bug that was causing some NFTs to flicker`

(This helps the Release Engineer do their job more quickly and
accurately)
-->

CHANGELOG entry: Added coverage for edge cases in the Onboarding flow
CHANGELOG entry: Improved onboarding token management strategy
CHANGELOG entry: Enhanced session reliability and authentication
consistency

## **Related issues**

Fixes:

## **Manual testing steps**

```gherkin
Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]
```

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

### **After**

<!-- [screenshots/recordings] -->

## **Pre-merge author checklist**

- [x] I’ve followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding

Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I’ve included tests if applicable
- [x] I’ve documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I’ve applied the right labels on the PR (see [labeling

guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Improves card onboarding/login flows, adds robust auth error handling
and access-token storage, and introduces utilities/tests for onboarding
token management.
> 
> - **Card Onboarding/Auth (UI + Flow)**:
> - Redirect login to onboarding when verification is pending; store
`onboardingId` in Redux.
> - Confirm Email: navigates to auth when account exists and shows
toast; resend cooldown; stricter validation.
> - Physical/Mailing Address: on success store short-lived access token,
set authenticated state/location, then continue; improved field handling
and validation; minor UI tweak to area code selector width.
> - **Card Home (Error Handling)**:
> - Detect authentication errors, clear stored tokens and Redux auth
state, and redirect to welcome; hide "Try again" on auth errors.
> - **Auth/Session Management**:
> - `cardTokenVault`: support access-only tokens (optional refresh
token), validate accordingly.
> - `handleLocalAuthentication`: handle access-only tokens (5‑min
buffer), clear on expiry, refresh and persist full tokens; clearer logs.
> - **SDK/Hook Updates**:
> - `CardSDK.getCardDetails` throws `INVALID_CREDENTIALS` on 401;
email/phone verification endpoints and auth flow refinements.
> - `useCardProviderAuthentication`: treat OTP/pending/phase states as
intermediate; proceed only after token exchange; set auth
state/location.
>   - `useRegisterPersonalDetails`: cleanup and naming consistency.
> - **Utilities**:
> - Add `extractTokenExpiration` (default 5 hours) and
`mapCountryToLocation` helpers.
>   - Add `isAuthenticationError` helper to classify auth failures.
> - **Tests & i18n**:
> - Comprehensive tests for Confirm Email, Mailing Address, auth
handling, and token expiration/auth flows.
>   - Add/update locale strings for onboarding and KYC states.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
e94d8c1. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: sophieqgu <[email protected]>
[a172652](a172652)

Co-authored-by: Bruno Nascimento <[email protected]>
Co-authored-by: sophieqgu <[email protected]>

Author: 3 people

app/components/UI/Card/Views/CardAuthentication/CardAuthentication.tsx

@@ -50,6 +50,8 @@ import {
 } from 'react-native-confirmation-code-field';
 import { useStyles } from '../../../../../component-library/hooks';
 import { Theme } from '../../../../../util/theme/models';
+import { useDispatch } from 'react-redux';
+import { setOnboardingId } from '../../../../../core/redux/slices/card';
 
 const CELL_COUNT = 6;
 
@@ -98,7 +100,7 @@ const CardAuthentication = () => {
   >(null);
   const [resendCountdown, setResendCountdown] = useState(60);
   const otpInputRef = useRef<TextInput>(null);
-
+  const dispatch = useDispatch();
   const theme = useTheme();
   const {
     login,
@@ -197,6 +199,16 @@ const CardAuthentication = () => {
           return;
         }
 
+        if (
+          loginResponse?.verificationState === 'PENDING' ||
+          loginResponse?.phase
+        ) {
+          // Switch to OTP step instead of navigating
+          dispatch(setOnboardingId(loginResponse.userId));
+          navigation.navigate(Routes.CARD.ONBOARDING.ROOT);
+          return;
+        }
+
         // Successful login - navigate to home
         navigation.reset({
           index: 0,
@@ -208,7 +220,7 @@ const CardAuthentication = () => {
         setLoading(false);
       }
     },
-    [email, location, login, password, navigation],
+    [email, location, login, password, navigation, dispatch],
   );
 
   // Auto-submit when all OTP digits are entered

app/components/UI/Card/Views/CardHome/CardHome.tsx

@@ -16,7 +16,7 @@ import Text, {
   TextVariant,
 } from '../../../../../component-library/components/Texts/Text';
 import { useNavigation } from '@react-navigation/native';
-import { useSelector } from 'react-redux';
+import { useDispatch, useSelector } from 'react-redux';
 import SensitiveText, {
   SensitiveTextLength,
 } from '../../../../../component-library/components/Texts/SensitiveText';
@@ -54,10 +54,19 @@ import { useCardSDK } from '../../sdk';
 import Routes from '../../../../../constants/navigation/Routes';
 import useIsBaanxLoginEnabled from '../../hooks/isBaanxLoginEnabled';
 import useCardDetails from '../../hooks/useCardDetails';
-import { selectIsAuthenticatedCard } from '../../../../../core/redux/slices/card';
+import {
+  selectIsAuthenticatedCard,
+  setIsAuthenticatedCard,
+  setAuthenticatedPriorityToken,
+  setAuthenticatedPriorityTokenLastFetched,
+  setUserCardLocation,
+} from '../../../../../core/redux/slices/card';
 import { useCardProvision } from '../../hooks/useCardProvision';
 import CardWarningBox from '../../components/CardWarningBox/CardWarningBox';
 import { useIsSwapEnabledForPriorityToken } from '../../hooks/useIsSwapEnabledForPriorityToken';
+import { isAuthenticationError } from '../../util/isAuthenticationError';
+import { removeCardBaanxToken } from '../../util/cardTokenVault';
+import Logger from '../../../../../util/Logger';
 
 /**
  * CardHome Component
@@ -80,6 +89,7 @@ const CardHome = () => {
 
   const { trackEvent, createEventBuilder } = useMetrics();
   const navigation = useNavigation();
+  const dispatch = useDispatch();
   const theme = useTheme();
 
   const styles = createStyles(theme);
@@ -389,6 +399,34 @@ const CardHome = () => {
     [priorityTokenError, cardDetailsError],
   );
 
+  // Handle authentication errors (expired token, invalid credentials, etc.)
+  useEffect(() => {
+    const handleAuthenticationError = async () => {
+      if (!error) {
+        return;
+      }
+
+      // Check if the error is authentication-related
+      if (isAuthenticated && isAuthenticationError(cardDetailsError)) {
+        Logger.log(
+          'CardHome: Authentication error detected, clearing auth state and redirecting',
+        );
+
+        // Clear authentication state
+        await removeCardBaanxToken();
+        dispatch(setIsAuthenticatedCard(false));
+        dispatch(setAuthenticatedPriorityToken(null));
+        dispatch(setAuthenticatedPriorityTokenLastFetched(null));
+        dispatch(setUserCardLocation(null));
+
+        // Redirect to welcome screen for re-authentication
+        navigation.navigate(Routes.CARD.WELCOME);
+      }
+    };
+
+    handleAuthenticationError();
+  }, [error, isAuthenticated, dispatch, navigation, cardDetailsError]);
+
   if (error) {
     return (
       <View style={styles.errorContainer}>
@@ -410,7 +448,7 @@ const CardHome = () => {
         >
           {strings('card.card_home.error_description')}
         </Text>
-        {retries < 3 && (
+        {retries < 3 && !isAuthenticationError(error) && (
           <View style={styles.tryAgainButtonContainer}>
             <Button
               variant={ButtonVariants.Primary}