feat(TRAM-3997): launch Sumsub through KycController after VBA email collection

[Akaryatrh]

Description

Before this PR, the VBA email screen launched Sumsub from the UI with MOCK_SUMSUB_APPLICANT_ACCESS_TOKEN, and KycController was constructed with a no-op launcher.
Now after customer creation, sumSubLauncher is injected into KycController, and verification is started through the controller.

• Once the customer exists, the hook loads the pre-session idOS / Sumsub catalog via KycController.fetchSessionDisclaimers({ country }) and calls acceptTermsAndStartSession with product: 'money' and the catalog consents.
• The controller owns the whole hand-off: it creates the UKYC session, submits the wrapped authorizations, then fetches the applicant access token from POST /sessions/{sessionId}/journey (KycService:createJourney) and hands it to the launcher. Token expiry re-calls the same endpoint.
• The launcher only presents the native SDK (lazy native-module load, token-refresh and status callbacks). Closing the SDK without submitting (sumsub.status === 'abandoned') is not treated as an error.
• KycService now receives idosEnclaveBaseUrl and idosRelayBaseUrl so startSumSub can fetch the JWKS it verifies the session encryption schemas against before reaching the journey call.
• @metamask/kyc-controller is bumped to 0.2.0-preview-97d6b86c0.

Get Pix Key still loads vendor T&Cs via initialize + loadDisclaimers; initialize now also passes product: 'money' so the KYC-required check and Sumsub hand-off stay scoped to Money.

Changelog

CHANGELOG entry: Sumsub flow opens after email submission.

Related issues

Fixes: TRAM-3997

Manual testing steps

Feature: VBA KYC Sumsub session via KycController

  Background:
    Given the native Sumsub module is linked (rebuild after adding the SDK)
    And KYC_API_URL points at a reachable Universal KYC host
    And the user is signed in with a MetaMask profile JWT
    And the user is on Get Pix Key and vendor T&Cs have loaded
    And the user continues to Verify Identity
    And idOS / Sumsub catalog T&Cs have loaded
    And the user continues to What's your email?

  Scenario: user starts Sumsub after entering email
    Given KYC customer creation and session start are configured to succeed

    When the user enters "  user@example.com  " and presses Continue
    Then the Iron customer is created or resumed with email user@example.com
    And acceptTermsAndStartSession is called with product money and catalog consents
    And a UKYC session is created and its authorizations are submitted
    And the applicant access token is fetched from the session journey endpoint
    And the native Sumsub SDK is presented with that token

  Scenario: user cannot continue without an email
    Given the email field is empty

    When the user looks at Continue
    Then Continue is disabled
    And the Sumsub SDK is not launched

  Scenario: user sees an error when customer creation fails
    Given createVendorCustomer records an error on controller state

    When the user enters an email and presses Continue
    Then an alert is shown
    And the Sumsub SDK is not launched
    And the user remains on the email screen

  Scenario: user sees an error when vendor T&Cs were not loaded
    Given KycController.state.vendorDisclaimers is empty

    When the user enters an email and presses Continue
    Then an alert asks the user to go back to Get your Pix Key
    And acceptTermsAndStartSession is not called

  Scenario: user abandons Sumsub without submitting
    Given the Sumsub SDK is presented

    When the user closes the SDK before submitting
    Then no error alert is shown
    And the user remains on the email screen

Screenshots/Recordings

Before

N/A

After

Simulator.Screen.Recording.-.iPhone.15.Pro.Max.-.2026-09-10.at.19.30.10.mov

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.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

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

High Risk
Changes identity verification orchestration, UKYC session/consent posting, and real SumSub token flow—security- and compliance-sensitive paths with new idOS backend configuration.

Overview
Routes VBA identity verification through KycController instead of launching SumSub from the email screen with a mock applicant token.

After the user submits email, useKycEmailVerification creates the Iron customer, loads the pre-session idOS/SumSub catalog via fetchSessionDisclaimers, then calls acceptTermsAndStartSession with product: 'money' and catalog consent keys. SumSub presentation is owned by the controller via an injected Engine-level sumsubLauncher (the UI-local launchSumSubSdk helper and kycSumSubLauncherStub are removed). Closing SumSub with sumsub.status === 'abandoned' is treated as a non-error exit; missing vendor T&Cs on the prior Get Pix Key step surfaces a dedicated alert.

Get Pix Key disclaimer loading now passes product: 'money' on KycController.initialize. KycService init wires IDOS_ENCLAVE_URL / IDOS_RELAY_URL (with UAT defaults and builds.yml / Jest env updates).

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

[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 0c18346. Configure here.}

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeAccounts, SmokeConfirmations, SmokeNetworkAbstractions, SmokeNetworkExpansion, SmokeSwap, SmokeStake, SmokeWalletPlatform, SmokeMoney, SmokePerps, SmokeMultiChainAPI, SmokePredictions, SmokeSeedlessOnboarding, SmokeBrowser, SmokeSnaps, SmokeMMConnect
• Selected Performance tags: None (no tests recommended)
• Risk Level: high
• AI Confidence: 100%

click to see 🤖 AI reasoning details

E2E Test Selection:
Hard rule (en-locale-change): locales/languages/en.json changed — UI strings and E2E text/label selectors may diverge (including platform casing like Android textAllCaps). Running all tests.

Performance Test Selection:
The changes are focused on KYC/identity verification flows (SumSub SDK integration, idOS URL configuration, VBA hooks). These are user-initiated identity flows that don't affect app launch, login, asset loading, account list rendering, or other performance-sensitive paths. No performance test tags are relevant to KYC/VBA flows. The @PerformanceMoney tag covers Money Home balance and activity content loading, not KYC identity verification flows.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
95.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud