@metamask/ramps-controller 24.0.0 → 25.1.0

package/dist/RampsController.js

@@ -85,24 +85,56 @@ export const RAMPS_CONTROLLER_REQUIRED_CONTROLLER_ACTIONS = [
     'KycController:refreshSessionStatus',
     'KycController:hasCompletedVendorDisclaimers',
     'KycController:hasCompletedSessionDisclaimers',
+    'KycController:clearState',
     'RemoteFeatureFlagController:getState',
     'UserStorageController:getState',
     'UserStorageController:performGetStorageAllFeatureEntries',
     'UserStorageController:performBatchSetStorage',
 ];
 /**
- * The Mobile route for the current VBA onboarding step.
+ * KYC vocabulary used on the VBA onboarding snapshot. `'none'` means no
+ * session exists yet (or the vendor returned an unrecognized status).
  */
-export var VbaOnboardingStage;
-(function (VbaOnboardingStage) {
-    VbaOnboardingStage["EmailOtpRequired"] = "EmailOtpRequired";
-    VbaOnboardingStage["VendorTermsRequired"] = "VendorTermsRequired";
-    VbaOnboardingStage["ProviderTermsRequired"] = "ProviderTermsRequired";
-    VbaOnboardingStage["KycRequired"] = "KycRequired";
-    VbaOnboardingStage["KycPending"] = "KycPending";
-    VbaOnboardingStage["KycRejected"] = "KycRejected";
-    VbaOnboardingStage["Completed"] = "Completed";
-})(VbaOnboardingStage || (VbaOnboardingStage = {}));
+export const VBA_KYC_STATUSES = [
+    'none',
+    'new',
+    'retry',
+    'pending',
+    'approved',
+    'rejected',
+];
+/**
+ * Autoramp setup progress after KYC has been approved.
+ * `'in_progress'` is reserved for hosts that observe an in-flight hydrate;
+ * {@link RampsController.hydrateVbaOnboarding} itself returns `'ready'` or
+ * `'retryable_failure'` once the coalesced run settles.
+ */
+export const VBA_AUTORAMP_STATUSES = [
+    'not_ready',
+    'in_progress',
+    'ready',
+    'retryable_failure',
+];
+const EMPTY_VBA_ONBOARDING_SNAPSHOT = {
+    sessionExists: false,
+    vendorDisclaimersComplete: false,
+    sessionDisclaimersComplete: false,
+    kycStatus: 'none',
+    autorampStatus: 'not_ready',
+};
+const VBA_KYC_STATUS_SET = new Set(VBA_KYC_STATUSES);
+/**
+ * Maps a vendor status string onto the snapshot vocabulary.
+ *
+ * @param value - Raw KYC status from the session.
+ * @returns A known {@link VbaKycStatus}, or `'none'` when missing/unknown.
+ */
+function toVbaKycStatus(value) {
+    if (value && VBA_KYC_STATUS_SET.has(value)) {
+        return value;
+    }
+    return 'none';
+}
 /**
  * Distinguishes an already-materialized {@link AutorampAccount} from the
  * create-fields shape accepted by {@link RampsController.addAutoramp}.
@@ -237,12 +269,6 @@ const rampsControllerMetadata = {
         includeInStateLogs: true,
         usedInUi: true,
     },
-    vbaOnboardingStage: {
-        persist: true,
-        includeInDebugSnapshot: true,
-        includeInStateLogs: true,
-        usedInUi: true,
-    },
 };
 /**
  * Creates a default resource state object.
@@ -288,7 +314,6 @@ export function getDefaultRampsControllerState() {
         orders: [],
         autoramps: [],
         providerAutoSelected: false,
-        vbaOnboardingStage: null,
     };
 }
 const DEPENDENT_RESOURCE_KEYS = [
@@ -450,6 +475,7 @@ const MESSENGER_EXPOSED_METHODS = [
     'startOrderPolling',
     'stopOrderPolling',
     'getBuyWidgetData',
+    'getFallbackBuyWidgetData',
     'addPrecreatedOrder',
     'getOrder',
     'getOrderFromCallback',
@@ -2500,15 +2526,17 @@ export class RampsController extends BaseController {
         }
     }
     /**
-     * Hydrates the Mobile-routable VBA onboarding stage from KYC state and
-     * completes wallet and autoramp setup after KYC acceptance.
+     * Refreshes KYC session facts and, when Iron has approved KYC, activates the
+     * Money Account (wallet registration + autoramp). Hosts map the returned
+     * {@link VbaOnboardingSnapshot} onto their own funnel; this method does not
+     * name screens.
      *
      * Overlapping calls share one run so polling cannot trigger duplicate wallet
      * signatures or autoramp creation.
      *
      * @param params - VBA onboarding parameters.
      * @param params.walletAddress - Monad Money Account wallet address.
-     * @returns The hydrated onboarding stage.
+     * @returns Independent KYC and autoramp facts for the current customer.
      */
     async hydrateVbaOnboarding({ walletAddress, }) {
         if (this.#vbaOnboardingHydrationPromise) {
@@ -2526,20 +2554,21 @@ export class RampsController extends BaseController {
         }
     }
     async #hydrateVbaOnboarding(walletAddress) {
-        // Fetch the customer's latest session from the vendor account so each stage
-        // reflects backend truth (e.g. re-verification required after a new
-        // document) rather than only device-local state. A `null` session means no
-        // customer/session exists yet, so onboarding starts at the email step.
         // Prefer the in-memory/persisted session status over the backend
-        // latest-status endpoint: after SumSub the backend endpoint lags (it still
-        // reports kycStatus 'new' right after an 'approved' applicant result), while
+        // latest-status endpoint: after SumSub the backend endpoint can lag, while
         // the controller state reflects the journey/SDK outcome. Fall back to a
         // backend fetch only when the controller has no session in state (e.g. a
         // reinstall/cleared state resuming an existing customer, or a brand-new user
         // with no session at all).
         let session = null;
+        // Whether `session` came from persisted controller state (as opposed to a
+        // fresh backend fetch, which is always scoped to the current user). Only a
+        // persisted session can belong to a previous identity, so only that path
+        // needs the ownership check below.
+        let sessionFromCache = false;
         try {
             session = this.messenger.call('KycController:refreshSessionStatus');
+            sessionFromCache = true;
         }
         catch {
             try {
@@ -2547,48 +2576,43 @@ export class RampsController extends BaseController {
             }
             catch {
                 // No session exists for this customer yet: the backend returns 404
-                // ("KYC session not found"), which surfaces as a rejection here. Treat
-                // it as "start onboarding at the email step" rather than an error.
+                // ("KYC session not found"), which surfaces as a rejection here.
                 session = null;
             }
         }
         if (!session) {
-            return this.#setVbaOnboardingStage(VbaOnboardingStage.EmailOtpRequired);
-        }
-        if (!(await this.messenger.call('KycController:hasCompletedVendorDisclaimers'))) {
-            return this.#setVbaOnboardingStage(VbaOnboardingStage.VendorTermsRequired);
-        }
-        if (!(await this.messenger.call('KycController:hasCompletedSessionDisclaimers'))) {
-            return this.#setVbaOnboardingStage(VbaOnboardingStage.ProviderTermsRequired);
-        }
-        // Status fields draw from the KYC vocabulary (new | pending | approved |
-        // rejected | retry). `finalStatus` is the vendor's final decision, which
-        // stays `pending` until Iron finalizes. `kycStatus` is the SumSub applicant
-        // outcome (from the journey/SDK result): `new` before the applicant runs
-        // SumSub, moving to `approved`/`pending` once they submit while the vendor
-        // finalizes. So gate the SumSub screen on `kycStatus`, and only complete
-        // onboarding once `finalStatus` is the terminal `approved`.
-        const { finalStatus, kycStatus } = session;
-        if (finalStatus === 'rejected' || kycStatus === 'rejected') {
-            return this.#setVbaOnboardingStage(VbaOnboardingStage.KycRejected);
-        }
-        if (finalStatus !== 'approved') {
-            if (kycStatus === 'new' || kycStatus === 'retry') {
-                // Applicant still has to run (or re-run) SumSub document verification.
-                return this.#setVbaOnboardingStage(VbaOnboardingStage.KycRequired);
-            }
-            // Submitted; vendor is finalizing → "verification in progress".
-            return this.#setVbaOnboardingStage(VbaOnboardingStage.KycPending);
+            return { ...EMPTY_VBA_ONBOARDING_SNAPSHOT };
+        }
+        // A persisted session can outlive the identity that created it — e.g. a new
+        // wallet created over an install that still holds a previous customer's
+        // session. Reusing it makes the backend reject every session-scoped call
+        // (owner mismatch), dead-ending the user. Verify ownership up front against
+        // the signed-in profile and, on a mismatch, discard the stale session.
+        if (sessionFromCache &&
+            !(await this.#isVbaSessionOwnedByCurrentProfile(session))) {
+            this.messenger.call('KycController:clearState');
+            return { ...EMPTY_VBA_ONBOARDING_SNAPSHOT };
+        }
+        const vendorDisclaimersComplete = await this.messenger.call('KycController:hasCompletedVendorDisclaimers');
+        const sessionDisclaimersComplete = await this.messenger.call('KycController:hasCompletedSessionDisclaimers');
+        const snapshot = {
+            sessionExists: true,
+            vendorDisclaimersComplete,
+            sessionDisclaimersComplete,
+            kycStatus: toVbaKycStatus(session.finalStatus),
+            autorampStatus: 'not_ready',
+        };
+        if (snapshot.kycStatus !== 'approved') {
+            return snapshot;
         }
         if (!walletAddress.trim()) {
             throw new Error('walletAddress is required after KYC acceptance.');
         }
         // KYC is approved; the remaining work activates the Money account (register
         // the wallet + ensure an autoramp). Those calls hit the neobank backend and
-        // can fail transiently (e.g. an address-list lookup timeout). If they do,
-        // keep the user on the "verification in progress" screen so a refresh
-        // retries the activation, rather than dropping them onto the recoverable-
-        // error screen — the KYC decision itself already succeeded.
+        // can fail transiently (e.g. an address-list lookup timeout). Surface
+        // `retryable_failure` so the host can keep the user on a pending screen
+        // rather than a fatal error — the KYC decision itself already succeeded.
         try {
             const registration = await this.registerMoneyAccountWallet({
                 address: walletAddress,
@@ -2613,17 +2637,31 @@ export class RampsController extends BaseController {
             }
         }
         catch {
-            return this.#setVbaOnboardingStage(VbaOnboardingStage.KycPending);
+            return { ...snapshot, autorampStatus: 'retryable_failure' };
         }
-        return this.#setVbaOnboardingStage(VbaOnboardingStage.Completed);
+        return { ...snapshot, autorampStatus: 'ready' };
     }
-    #setVbaOnboardingStage(stage) {
-        if (this.state.vbaOnboardingStage !== stage) {
-            this.update((state) => {
-                state.vbaOnboardingStage = stage;
-            });
+    /**
+     * Whether a persisted KYC session belongs to the currently signed-in profile.
+     * A session's `externalUserId` is the canonical profile id captured when the
+     * session was created, so it must match the current profile for the session
+     * to be reused. When the current identity cannot be resolved, err on the side
+     * of keeping the session (return `true`) so a transient profile-read failure
+     * never discards a valid session.
+     *
+     * @param session - The persisted KYC session status to check.
+     * @returns Whether the session is owned by the current profile.
+     */
+    async #isVbaSessionOwnedByCurrentProfile(session) {
+        const profile = await this.messenger.call('AuthenticationController:getSessionProfile');
+        const canonicalId = typeof profile?.canonicalProfileId === 'string' &&
+            profile.canonicalProfileId.length > 0
+            ? profile.canonicalProfileId
+            : profile?.profileId;
+        if (typeof canonicalId !== 'string' || canonicalId.length === 0) {
+            return true;
         }
-        return stage;
+        return session.externalUserId === canonicalId;
     }
     /**
      * Removes a local autoramp last-seen cursor by id.
@@ -2852,6 +2890,37 @@ export class RampsController extends BaseController {
         if (!buyUrl) {
             return null;
         }
+        return this.#fetchBuyWidget(buyUrl);
+    }
+    /**
+     * Fetches the widget data for a quote's hosted-flow fallback (see
+     * `getBuyWidgetFallback`), used when an embedded checkout turns the user away.
+     *
+     * @param fallback - The buy-widget fallback attached to the quote.
+     * @param options - Optional request options.
+     * @param options.redirectUrl - Where the hosted flow returns to; set as the
+     * `redirectUrl` query parameter, replacing any existing value.
+     * @returns Promise resolving to the hosted BuyWidget, or null if the fallback has no URL or the response has an empty url.
+     * @throws TypeError if the fallback URL is not a valid URL.
+     * @throws Rethrows errors from the RampsService (e.g. HttpError, network failures) so clients can react to fetch failures.
+     */
+    async getFallbackBuyWidgetData(fallback, options) {
+        if (!fallback?.url) {
+            return null;
+        }
+        const buyUrl = new URL(fallback.url);
+        if (options?.redirectUrl) {
+            buyUrl.searchParams.set('redirectUrl', options.redirectUrl);
+        }
+        return this.#fetchBuyWidget(buyUrl.toString());
+    }
+    /**
+     * Resolves a buy-widget request URL into the provider widget via the RampsService.
+     *
+     * @param buyUrl - The buy-widget request URL.
+     * @returns Promise resolving to the BuyWidget, or null if the response has an empty url.
+     */
+    async #fetchBuyWidget(buyUrl) {
         const buyWidget = await this.messenger.call('RampsService:getBuyWidgetUrl', buyUrl);
         if (!buyWidget?.url) {
             return null;