feat(card): Card Authentication migration from CardSDK to CardController (#27656)

<!--
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**

Migrates Card authentication to the CardController, introducing a
controller-based auth flow that delegates to BaanxProvider and a new
`useCardAuth` hook for UI consumption.

**Why**: Centralizing auth logic in the CardController aligns with the
MetaMask controller architecture, provides a single source of truth for
auth state, and enables future provider-agnostic auth flows. The new
`useCardAuth` hook exposes mutations (initiate, submit, stepAction,
logout) backed by the controller, with React Query for cache
invalidation on success.

**What changed**:

- **CardController**: Added auth methods `initiateAuth`,
`submitCredentials`, `executeStepAction`, and `logout` that delegate to
the active provider (BaanxProvider). Manages `currentSession` for
multi-step flows (email/password → OTP → complete).

- **BaanxProvider**: Implemented `executeStepAction` (generic OTP
trigger) that posts `userId` to `/v1/auth/login/otp`. Renamed from
provider-specific `sendOtp` to align with `ICardProvider` interface.

- **provider-types**: Added optional `executeStepAction?(session:
CardAuthSession): Promise<void>` to `ICardProvider`.

- **useCardAuth hook**: New hook exposing `currentStep`, `initiate`,
`submit`, `stepAction`, and `logout` mutations. Uses CardController for
all auth operations; updates `currentStep` on submit results (OTP,
onboarding required, done); invalidates card queries on login success;
removes queries on logout.

- **auth queries**: Added `authKeys` (initiate, submit, step-action,
logout) to `cardQueries.auth.keys`.

- **getCardProviderErrorMessage**: New utility mapping
`CardProviderError` codes to localized strings for Card authentication
UI.

- **BaanxService / baanx-config**: Minor adjustments for config
resolution and service usage.

- **Tests**: Updated BaanxProvider tests (`sendOtp` →
`executeStepAction`); fixed baanx-config test mock isolation with
`beforeEach` mock clear; expanded CardController tests for auth methods;
added `useCardAuth` unit tests.

## **Changelog**

CHANGELOG entry: Migrated Card authentication to CardController with new
`useCardAuth` hook for controller-based auth flow.

## **Related issues**

Fixes:

## **Manual testing steps**

```gherkin
Feature: Card authentication via CardController

  Scenario: User logs in with email and password (no OTP)
    Given I am on the Card authentication screen
    And I have valid email and password credentials

    When I enter my email and password
    And I tap the login button
    Then I should be authenticated and see the Card home/dashboard

  Scenario: User logs in with email, password, and OTP
    Given I am on the Card authentication screen
    And I have credentials that require OTP verification

    When I enter my email and password
    And I tap the login button
    Then I should see the OTP input screen
    When I tap "Resend code" (or wait for cooldown)
    Then an OTP should be sent to my device/email
    When I enter the OTP code and submit
    Then I should be authenticated and see the Card home/dashboard

  Scenario: User logs out
    Given I am authenticated in the Card flow

    When I log out (or navigate away and return to auth)
    Then I should see the login screen again
    And card queries should be cleared
```

## **Screenshots/Recordings**

No visual design changes — authentication flow (email/password, OTP,
logout) behaves the same; only the underlying implementation
(CardController + useCardAuth vs SDK) changed.

## **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]
> **High Risk**
> High risk because it introduces a new controller-driven
authentication/session lifecycle (multi-step auth, token storage,
refresh, and logout) and changes default provider selection/state, which
can impact login persistence and security-sensitive flows.
> 
> **Overview**
> Migrates card authentication off the UI/SDK path into
`CardController`, adding controller-level methods for `initiateAuth`,
`submitCredentials`, `executeStepAction`, `logout`, and
`validateAndRefreshSession` with token persistence via `CardTokenStore`,
provider delegation, and session/step tracking.
> 
> Adds a new UI hook `useCardAuth` backed by React Query mutations (with
new `cardQueries.auth` keys) to drive the multi-step login flow and to
invalidate/remove card queries on login/logout.
> 
> Standardizes provider step actions by renaming `ICardProvider.sendOtp`
to `executeStepAction` and updating `BaanxProvider` accordingly, plus
adds localized error mapping via `getCardProviderErrorMessage` and
extends Baanx config/service behavior (env override for base URL;
per-request location override for `x-us-env`).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
a91ba19. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: Brunonascdev

app/components/UI/Card/hooks/useCardAuth.test.ts

@@ -0,0 +1,249 @@
+import { renderHook, act } from '@testing-library/react-hooks';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import Engine from '../../../../core/Engine';
+import { cardQueries } from '../queries';
+import { useCardAuth } from './useCardAuth';
+
+jest.mock('@tanstack/react-query', () => ({
+  useMutation: jest.fn(),
+  useQueryClient: jest.fn(),
+}));
+
+jest.mock('../../../../core/Engine', () => ({
+  context: {
+    CardController: {
+      initiateAuth: jest.fn(),
+      submitCredentials: jest.fn(),
+      executeStepAction: jest.fn(),
+      logout: jest.fn(),
+    },
+  },
+}));
+
+jest.mock('../../../../util/Logger', () => ({
+  error: jest.fn(),
+}));
+
+const mockUseMutation = useMutation as jest.Mock;
+const mockUseQueryClient = useQueryClient as jest.Mock;
+const mockController = Engine.context.CardController as jest.Mocked<
+  typeof Engine.context.CardController
+>;
+
+const mockInvalidateQueries = jest.fn();
+const mockRemoveQueries = jest.fn();
+
+describe('useCardAuth', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    mockUseQueryClient.mockReturnValue({
+      invalidateQueries: mockInvalidateQueries,
+      removeQueries: mockRemoveQueries,
+    });
+
+    mockUseMutation.mockImplementation(
+      (opts: {
+        mutationFn: (...args: unknown[]) => Promise<unknown>;
+        onSuccess?: (result: unknown) => void;
+      }) => ({
+        mutateAsync: jest.fn(async (...args: unknown[]) => {
+          const res = await opts.mutationFn(...args);
+          opts.onSuccess?.(res);
+          return res;
+        }),
+        isPending: false,
+        error: null,
+        data: null,
+      }),
+    );
+  });
+
+  it('currentStep starts as email_password', () => {
+    const { result } = renderHook(() => useCardAuth());
+
+    expect(result.current.currentStep).toStrictEqual({
+      type: 'email_password',
+    });
+  });
+
+  it('exposes getErrorMessage for displaying auth errors', () => {
+    const { result } = renderHook(() => useCardAuth());
+
+    expect(result.current.getErrorMessage).toBeDefined();
+    expect(typeof result.current.getErrorMessage).toBe('function');
+  });
+
+  describe('initiate', () => {
+    it('calls controller.initiateAuth', async () => {
+      mockController.initiateAuth.mockResolvedValue(undefined);
+      const { result } = renderHook(() => useCardAuth());
+
+      await act(async () => {
+        await result.current.initiate.mutateAsync('US');
+      });
+
+      expect(mockController.initiateAuth).toHaveBeenCalledWith('US');
+    });
+  });
+
+  describe('submit', () => {
+    it('calls controller.submitCredentials with credentials', async () => {
+      mockController.submitCredentials.mockResolvedValue({
+        done: true,
+        tokenSet: {} as never,
+      });
+      const { result } = renderHook(() => useCardAuth());
+
+      await act(async () => {
+        await result.current.submit.mutateAsync({
+          type: 'email_password',
+          email: 'a@b.com',
+          password: 'p',
+        });
+      });
+
+      expect(mockController.submitCredentials).toHaveBeenCalledWith({
+        type: 'email_password',
+        email: 'a@b.com',
+        password: 'p',
+      });
+    });
+
+    it('resets currentStep and invalidates queries on done:true', async () => {
+      mockController.submitCredentials.mockResolvedValue({ done: true });
+      const { result } = renderHook(() => useCardAuth());
+
+      await act(async () => {
+        await result.current.submit.mutateAsync({
+          type: 'email_password',
+          email: 'a@b.com',
+          password: 'p',
+        });
+      });
+
+      expect(result.current.currentStep).toStrictEqual({
+        type: 'email_password',
+      });
+      expect(mockInvalidateQueries).toHaveBeenCalledWith({
+        queryKey: cardQueries.keys.all(),
+      });
+    });
+
+    it('updates currentStep when nextStep is returned', async () => {
+      mockController.submitCredentials.mockResolvedValue({
+        done: false,
+        nextStep: { type: 'otp', destination: '+1555****90' },
+      });
+      const { result } = renderHook(() => useCardAuth());
+
+      await act(async () => {
+        await result.current.submit.mutateAsync({
+          type: 'email_password',
+          email: 'a@b.com',
+          password: 'p',
+        });
+      });
+
+      expect(result.current.currentStep).toStrictEqual({
+        type: 'otp',
+        destination: '+1555****90',
+      });
+    });
+
+    it('resets currentStep when onboardingRequired is returned', async () => {
+      mockController.submitCredentials.mockResolvedValue({
+        done: false,
+        onboardingRequired: { sessionId: 'ob-1', phase: 'kyc' },
+      });
+      const { result } = renderHook(() => useCardAuth());
+
+      await act(async () => {
+        await result.current.submit.mutateAsync({
+          type: 'email_password',
+          email: 'a@b.com',
+          password: 'p',
+        });
+      });
+
+      expect(result.current.currentStep).toStrictEqual({
+        type: 'email_password',
+      });
+    });
+
+    it('resets currentStep when done:false without nextStep or onboardingRequired', async () => {
+      mockController.submitCredentials.mockResolvedValue({ done: false });
+      const { result } = renderHook(() => useCardAuth());
+
+      await act(async () => {
+        await result.current.submit.mutateAsync({
+          type: 'email_password',
+          email: 'a@b.com',
+          password: 'p',
+        });
+      });
+
+      expect(result.current.currentStep).toStrictEqual({
+        type: 'email_password',
+      });
+    });
+  });
+
+  describe('stepAction', () => {
+    it('calls controller.executeStepAction', async () => {
+      mockController.executeStepAction.mockResolvedValue(undefined);
+      const { result } = renderHook(() => useCardAuth());
+
+      await act(async () => {
+        await result.current.stepAction.mutateAsync();
+      });
+
+      expect(mockController.executeStepAction).toHaveBeenCalled();
+    });
+  });
+
+  describe('logout', () => {
+    it('calls controller.logout', async () => {
+      mockController.logout.mockResolvedValue(undefined);
+      const { result } = renderHook(() => useCardAuth());
+
+      await act(async () => {
+        await result.current.logout.mutateAsync();
+      });
+
+      expect(mockController.logout).toHaveBeenCalled();
+    });
+
+    it('resets currentStep and removes queries on success', async () => {
+      mockController.submitCredentials.mockResolvedValue({
+        done: false,
+        nextStep: { type: 'otp', destination: '+1555****90' },
+      });
+      mockController.logout.mockResolvedValue(undefined);
+      const { result } = renderHook(() => useCardAuth());
+
+      await act(async () => {
+        await result.current.submit.mutateAsync({
+          type: 'email_password',
+          email: 'a@b.com',
+          password: 'p',
+        });
+      });
+      expect(result.current.currentStep).toStrictEqual({
+        type: 'otp',
+        destination: '+1555****90',
+      });
+
+      await act(async () => {
+        await result.current.logout.mutateAsync();
+      });
+
+      expect(result.current.currentStep).toStrictEqual({
+        type: 'email_password',
+      });
+      expect(mockRemoveQueries).toHaveBeenCalledWith({
+        queryKey: cardQueries.keys.all(),
+      });
+    });
+  });
+});

app/components/UI/Card/hooks/useCardAuth.ts

@@ -0,0 +1,75 @@
+import { useState } from 'react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import Engine from '../../../../core/Engine';
+import { cardQueries } from '../queries';
+import {
+  CardAuthStep,
+  CardCredentials,
+} from '../../../../core/Engine/controllers/card-controller/provider-types';
+import { getCardProviderErrorMessage } from '../util/getCardProviderErrorMessage';
+
+function getController() {
+  const controller = Engine.context?.CardController;
+  if (!controller) {
+    throw new Error('CardController not initialized');
+  }
+  return controller;
+}
+
+const LOGIN_STEP: CardAuthStep = { type: 'email_password' };
+
+export const useCardAuth = () => {
+  const queryClient = useQueryClient();
+  const [currentStep, setCurrentStep] = useState<CardAuthStep>(LOGIN_STEP);
+
+  const initiate = useMutation({
+    mutationKey: cardQueries.auth.keys.initiate(),
+    mutationFn: (country: string) => getController().initiateAuth(country),
+    retry: false,
+  });
+
+  const submit = useMutation({
+    mutationKey: cardQueries.auth.keys.submit(),
+    mutationFn: (credentials: CardCredentials) =>
+      getController().submitCredentials(credentials),
+    onSuccess: (result) => {
+      if (result.done || result.onboardingRequired) {
+        setCurrentStep(LOGIN_STEP);
+        if (result.done) {
+          queryClient.invalidateQueries({ queryKey: cardQueries.keys.all() });
+        }
+      } else if (result.nextStep) {
+        setCurrentStep(result.nextStep);
+      } else {
+        // Controller cleared session (done:false without nextStep/onboardingRequired)
+        setCurrentStep(LOGIN_STEP);
+      }
+    },
+    retry: false,
+  });
+
+  const stepAction = useMutation({
+    mutationKey: cardQueries.auth.keys.stepAction(),
+    mutationFn: () => getController().executeStepAction(),
+    retry: false,
+  });
+
+  const logout = useMutation({
+    mutationKey: cardQueries.auth.keys.logout(),
+    mutationFn: () => getController().logout(),
+    onSuccess: () => {
+      setCurrentStep(LOGIN_STEP);
+      queryClient.removeQueries({ queryKey: cardQueries.keys.all() });
+    },
+    retry: false,
+  });
+
+  return {
+    currentStep,
+    initiate,
+    submit,
+    stepAction,
+    logout,
+    getErrorMessage: getCardProviderErrorMessage,
+  };
+};

app/components/UI/Card/queries/auth.ts

@@ -0,0 +1,7 @@
+export const authKeys = {
+  all: () => ['card', 'auth'] as const,
+  initiate: () => [...authKeys.all(), 'initiate'] as const,
+  submit: () => [...authKeys.all(), 'submit'] as const,
+  stepAction: () => [...authKeys.all(), 'step-action'] as const,
+  logout: () => [...authKeys.all(), 'logout'] as const,
+};

app/components/UI/Card/queries/index.ts

@@ -5,6 +5,7 @@ import {
   cashbackWithdrawEstimationOptions,
 } from './cashback';
 import { dashboardKeys } from './dashboard';
+import { authKeys } from './auth';
 
 export const cardQueries = {
   keys: {
@@ -22,4 +23,7 @@ export const cardQueries = {
     walletOptions: cashbackWalletOptions,
     withdrawEstimationOptions: cashbackWithdrawEstimationOptions,
   },
+  auth: {
+    keys: authKeys,
+  },
 };