WIP: neobank use generalized kyc-controller vendors

[jiexi]

Description

Adopt the generalized KYC vendor APIs from @metamask/kyc-controller so the VBA Iron path is a vendor-scoped customer create, not an Iron-only method.

• Replace KycController.createIronCustomer({ email }) with createVendorCustomer({ vendor: 'iron', email }) in ironKycFlow.
• Delegate KycService:createVendorCustomer on the KYC messenger instead of the Iron-specific actions (createIronCustomer, fetchIronDisclaimers, checkIronKycRequired).
• Resolve KycService baseUrl from KYC_API_URL with a METAMASK_ENVIRONMENT fallback (dev / uat / production) so Engine can construct the service in tests and local runs when Babel inlines an empty KYC_API_URL.
• Hydrate new persisted KYC fields (termsAcceptedVendor, sumsubTncAccepted, idosTncAccepted) and RampsController.autoramps in test background state.
• Reset KYC controller on Engine reset
• Bump @metamask/kyc-controller and @metamask/ramps-controller previews from c34a16a37 to 2317a52 (MetaMask/core#9908, MetaMask/core#9931).

Changelog

CHANGELOG entry: null

Related issues

Refs: MetaMask/core#9908
Refs: MetaMask/core#9931

Manual testing steps

Feature: VBA Iron KYC on generalized vendor APIs

  Scenario: user starts Iron KYC from Get Pix Key
    Given the Brazil neobank flag is on and the user is signed in
    When the user taps Agree and continue
    Then KycController.initialize runs with vendor iron and product money
    And the app navigates to verify identity

  Scenario: user submits email and completes SumSub
    Given Iron disclaimers are already loaded
    When the user submits an email on the mock KYC email screen
    Then createVendorCustomer is called with vendor iron and that email
    And acceptTermsAndStartSession launches SumSub

  Scenario: Engine constructs KycService without KYC_API_URL
    Given KYC_API_URL is empty (Jest / local)
    When Engine initializes KycService
    Then the service uses the environment-derived KYC host instead of rejecting an empty baseUrl

Screenshots/Recordings

N/A — vendor API rename and Engine wiring; no intended product UI change.

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.

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

Medium Risk
Touches KYC customer creation, UKYC JWKS hosts, and wallet reset behavior for persisted verification state—important for neobank onboarding but scoped to vendor API migration and Engine wiring rather than new user-facing flows.

Overview
This PR wires the Brazil VBA Iron path to the generalized @metamask/kyc-controller vendor APIs instead of Iron-only controller/service methods.

Iron KYC flow now calls KycController.createVendorCustomer({ vendor: 'iron', email }) (tests and ironKycFlow updated). The KYC controller messenger delegates the new service actions—vendor customer create, vendor/session disclaimers, idOS enclave/relay JWKS, and setAuthorizations—replacing the old Iron-specific and Fractal encryption JWKS actions.

KycService initialization resolves baseUrl via KYC_API_URL when inlined from builds, with a METAMASK_ENVIRONMENT fallback to dev/uat/production KYC API hosts so Engine can construct the service when the env var is empty in Jest/local. Fractal encryption config in AppConstants is split into IDOS_ENCLAVE_URL and IDOS_RELAY_URL (updated production hosts) and passed into KycService as idosEnclaveBaseUrl / idosRelayBaseUrl.

Wallet lifecycle: Engine.resetState clears KycController state so KYC email, terms, and verification do not leak across wallets. NeoBankService gains delegated AuthenticationController:getSessionProfile (aligned with ramps preview resolving customer id from Profile Sync). Test background state adds new persisted KYC fields and RampsController.autoramps.

Dependency previews bump @metamask/kyc-controller to c61613ed2 and pin @metamask/ramps-controller to a matching preview.

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

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​metamask-previews/​ramps-controller@​20.0.0-preview-c34a16a37
	npm/​@​metamask-previews/​kyc-controller@​0.0.0-preview-c34a16a37 ⏵ 0.0.0-preview-c61613ed2	+9		+1	+2

View full report

[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.

[socket-security]

Warning

MetaMask internal reviewing guidelines:

• Do not ignore-all
• Each alert has instructions on how to review if you don't know what it means. If lost, ask your Security Liaison or the supply-chain group
• Copy-paste ignore lines for specific packages or a group of one kind with a note on what research you did to deem it safe.
  @SocketSecurity ignore npm/PACKAGE@VERSION

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Network access: npm @metamask-previews/ramps-controller in module globalThis["fetch"] Module: globalThis["fetch"] Location: Package overview From: package.json → npm/@metamask-previews/ramps-controller@20.0.0-preview-c34a16a37 ℹ Read more on: This package | This alert | What is network access? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should remove all network access that is functionally unnecessary. Consumers should audit network access to ensure legitimate use. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@metamask-previews/ramps-controller@20.0.0-preview-c34a16a37. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[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 86506a1. Configure here.}

[cursor]

KYC init test expects localhost URL

Medium Severity

The new kycServiceInit test expects baseUrl to be http://localhost:3000, and the init JSDoc now says that host is hardcoded, but the constructor still passes getKycApiBaseUrl(). In Jest, METAMASK_ENVIRONMENT is test and KYC_API_URL is empty, so that helper returns https://kyc-api.dev-api.cx.metamask.io. The assertion will fail, and the docs no longer match production wiring.

Additional Locations (1)

• app/core/Engine/controllers/kyc/kyc-service-init.ts#L53-L73

 

^{Reviewed by Cursor Bugbot for commit 86506a1. 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: @PerformanceMoney
• Risk Level: high
• AI Confidence: 100%

click to see 🤖 AI reasoning details

E2E Test Selection:
Hard rule (controller-version-update): @MetaMask controller package version updated in package.json: @metamask/kyc-controller, @metamask/ramps-controller. Running all tests.

Performance Test Selection:
The PR updates @metamask/ramps-controller and @metamask/kyc-controller to new preview versions, and modifies the KYC flow initialization and state management. The @PerformanceMoney tag covers Money Home balance and activity content loading, which could be affected by the ramps-controller changes. The other performance tags (@PerformanceLaunch, @PerformanceLogin, etc.) are not directly impacted as the changes are scoped to the Money/KYC feature area.

View GitHub Actions results