feat(card): migrate CardHome to Controller

[Brunonascdev]

Description

This branch finishes the Card Home migration to CardController and fixes the behavior regressions introduced while moving card auth, cardholder state, wallet data, and spending-limit flows away from the old SDK/React Query orchestration.

The motivation for the change was to make CardController the source of truth for Card state, instead of splitting responsibility across the Redux card slice, SDK helpers, and deleted React Query hooks like useLoadCardData / useGetCardExternalWalletDetails.

Key changes in this branch:

• Card authentication and session state now come from CardController

  • CardAuthentication uses useCardAuth.
  • UI now reads controller-backed selectors such as selectIsCardAuthenticated, selectIsCardholder, selectCardholderAccounts, and selectCardUserLocation.
  • Logout and session validation are handled through Engine.context.CardController.
  • Legacy auth verification helpers and side-effect flows were removed.

• Card Home was migrated to controller-backed data and split into smaller hooks/components

  • CardHome.tsx was refactored heavily into focused components and hooks like useCardHomeActions, useCardHomeAnalytics, and useCardProvisioning.
  • Snapshot-based tests touched by this work were removed in favor of explicit assertions.

• Push provisioning was aligned with the new controller/provider architecture

  • Provisioning eligibility was moved into the provider layer.
  • The old Galileo-specific adapter path was removed in favor of the controller adapter.
  • US-only provisioning restrictions and provider-specific feature-flag behavior were preserved.

• Unauthenticated cardholder UX was added

  • Cardholders who are not authenticated now see teaser actions on Card Home instead of a blocking login-required warning.
  • Teaser actions route to Card authentication.
  • Card authentication now shows an informational auth prompt banner for those entry points.
  • Terms and Conditions / Contact support remain visible in that state while Logout stays hidden.

• Spending Limit / delegation flows broken by the migration were restored

  • Card Home now passes the full spending-limit payload again (priorityToken, allTokens, delegationSettings, externalWalletDetailsData) instead of only { flow }.
  • CardHomeData now carries delegationSettings.
  • Supported tokens are enriched with delegationContract, which fixes the "Missing token configuration" delegation failure.
  • Spending Limit can pre-select the priority asset again and the token picker no longer stalls on an infinite spinner.
  • After successful delegation, useSpendingLimit now calls CardController.fetchCardHomeData() so the updated wallet/priority-token state appears automatically without requiring a manual refresh.

• Additional follow-up fixes and test coverage

  • Added/updated controller, provider, Card Home, Spending Limit, provisioning, authentication, and utility tests.
  • Replaced touched card snapshot tests with explicit assertions where applicable.

Changelog

CHANGELOG entry: Fixed MetaMask Card authentication, unauthenticated cardholder actions, and spending limit/delegation refresh flows after the CardController migration.

Related issues

Fixes:

Manual testing steps

Feature: Card controller migration and follow-up flow fixes

  Background:
    Given I have a build from this branch
    And I have access to a MetaMask Card test account

  Scenario: Card authentication uses controller-backed session state
    Given I am logged out of Card
    When I open Card and log in with a valid account
    Then Card Home should load successfully
    And authentication state should be preserved by CardController

    When I log out from Card
    Then CardController should clear the card session
    And I should return to the logged-out Card state

  Scenario: Unauthenticated cardholder sees teaser actions and auth prompt
    Given I am a cardholder but I am not currently authenticated
    When I open Card Home
    Then I should see teaser actions for card management
    And I should see Terms and Conditions and Contact support
    And I should not see Logout

    When I tap Manage limit
    Then the Card authentication screen should open
    And I should see the informational auth prompt banner

  Scenario: Spending Limit opens with delegation-ready token data
    Given I am authenticated on Card Home
    And I have supported card assets available
    When I tap Manage limit
    Then the Spending Limit screen should open
    And the priority asset should be pre-selected

    When I open the Token selector
    Then the asset list should load without an infinite spinner

  Scenario: Delegation refreshes Card Home automatically
    Given I am authenticated on Card Home
    And I open Spending Limit for a token that is not yet enabled
    When I complete delegation successfully
    Then I should return to Card Home
    And the token list and current priority token should refresh automatically
    And I should not need to pull to refresh manually

  Scenario: Push provisioning still respects provider/controller rules
    Given I am authenticated on Card Home with a supported eligible card
    When I review add-to-wallet availability
    Then provisioning eligibility should reflect the provider response
    And provider-specific feature flags should still be respected

Screenshots/Recordings

Before

N/A

After

N/A

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). 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.

---

Note

Medium Risk
Large refactor of CardHome data-flow and interaction handlers to rely on CardController/new hooks, plus navigation/auth gating changes; regressions are possible in card setup, spending-limit, and sensitive actions (PIN/details/freeze). Mostly UI-layer changes but they touch session/logout behavior and several user flows.

Overview
Card Home is migrated to controller-backed state and decomposed into smaller units. CardHome now renders from useCardHomeData() and CardController selectors/capabilities, with UI split into components like CardAlertSection, CardActionsButtons, CardImageSection, CardBalanceDisplay, ManageCardOptions, and CardHomeFooter, plus extracted hooks for actions/analytics/provisioning.

Unauthenticated cardholder UX is changed from “blocked” to “teaser” actions. Manage options (view details/PIN, freeze toggle, cashback, travel, manage card, etc.) can appear while unauthenticated but now route to Routes.CARD.AUTHENTICATION with showAuthPrompt: true; logout stays hidden.

Auth + location handling is adjusted in CardAuthentication. The screen reads showAuthPrompt from route params to show a new info banner (CardMessageBoxType.AuthPrompt), and location selection is now local state (selectedLocation) used during login rather than immediately calling CardController.setUserLocation.

Behavioral/test updates. Tests are updated to mock useRoute, validate new teaser/navigation behavior, switch CardHome tests to useCardHomeData, align freeze with separate freeze/unfreeze mutations, update spending-limit copy expectations, and tighten analytics expectations (don’t emit without a formatted balance).

^{Reviewed by Cursor Bugbot for commit 3baa77b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeCard, SmokeTrade, SmokeConfirmations
• Selected Performance tags: None (no tests recommended)
• Risk Level: high
• AI Confidence: 90%

click to see 🤖 AI reasoning details

E2E Test Selection:
The PR introduces a major refactoring of the MetaMask Card feature:

1. CardController (Critical): Significant changes to the core controller including:

   • New state fields (cardHomeData, cardHomeDataStatus) with fetch lifecycle management
   • New messenger actions: KeyringController:signPersonalMessage, NetworkController:findNetworkClientIdByChainId, TransactionController:addTransaction — integrating card funding with the transaction pipeline
   • New methods for freeze/unfreeze, push provisioning, cashback, and funding approval
   • Account switch detection and data invalidation logic
   • Improved error handling with Promise.allSettled

2. CardHome UI: Major decomposition into sub-components and hooks, with data now sourced from controller state (via useCardHomeData) instead of the SDK directly.

3. Test Infrastructure:

   • FixtureBuilder.withCardController() added and used in all 3 card smoke tests
   • card-button.spec.ts updated to use the new fixture method
   • CardHomeView.ts page object updated with scroll fix for advanced card management

4. All 3 Card smoke tests (card-button.spec.ts, card-home-add-funds.spec.ts, card-home-manage-card.spec.ts) are directly affected and must run under SmokeCard.

5. Per SmokeCard tag description: "When selecting SmokeCard, also select SmokeTrade and SmokeConfirmations (Add Funds uses swaps which require transaction confirmations)." The CardController now also directly calls TransactionController:addTransaction for funding approvals, making SmokeConfirmations especially relevant.

6. No changes to non-Card features (accounts, network, identity, snaps, etc.) so other tags are not needed.

Performance Test Selection:
The changes are focused on the Card feature — a specialized financial feature behind a feature flag. While the CardController now fetches data on account switch and session validation, this is not a core performance-sensitive path (account list rendering, app launch, login, swaps, asset loading). The Card feature is not covered by any existing performance test tags, and the changes don't affect the components or flows measured by the available performance tests (@PerformanceAccountList, @PerformanceOnboarding, @PerformanceLogin, @PerformanceSwaps, @PerformanceLaunch, @PerformanceAssetLoading, @PerformancePredict, @PerformancePreps).

View GitHub Actions results

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3baa77b. Configure here.}

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
83.4% Coverage on New Code
1.6% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

✅ E2E Fixture Validation — Schema is up to date
11 value mismatches detected (expected — fixture represents an existing user).
View details

[Cal-L]

platform file looks good