@metamask-previews/kyc-controller 0.0.0-preview-5bb6dba48 → 0.0.0-preview-efd9e28b2

package/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add `KycSumSubSdkStatus` for the status strings SumSub SDKs (and launchers) report, distinct from controller sub-flow `KycSumSubStatus`.
+- Add an `abandoned` member to `KycSumSubStatus`, recorded when the applicant closes the SumSub SDK without submitting. It separates that outcome from `failed`, which now means only that the flow could not run or was rejected.
 - Add `idosRelayBaseUrl` on `KycService` and `KycService.fetchIdosRelayJwks()` to fetch the idOS relay well-known JWKS used to verify the `ukycCapabilityToken` encryption schema. `encryptionDataKey` continues to verify against idOS enclave JWKS via `fetchIdosEnclaveJwks` / `idosEnclaveBaseUrl`. ([#10008](https://github.com/MetaMask/core/pull/10008))
 - Add session-scoped disclaimer APIs on `KycService` for the idOS / KYC-provider catalog ([#9979](https://github.com/MetaMask/core/pull/9979)):
   - `fetchSessionDisclaimers({ sessionId })` calls `GET /sessions/{sessionId}/disclaimers`
@@ -53,6 +55,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Treat native SumSub `Pending` and `Approved` statuses as a completed applicant flow, and fall back to the SDK `launch` result status when no status-change callback was delivered. Previously only the launcher-normalized `Completed` string counted, so a successful native SDK session was recorded as failed. ([#10133](https://github.com/MetaMask/core/pull/10133))
+- Also treat the SumSub `ActionCompleted`, `FinallyRejected`, and `TemporarilyDeclined` statuses as a submitted applicant flow. Rejection and temporary-decline decisions poll UKYC instead of being recorded as `abandoned`. ([#10133](https://github.com/MetaMask/core/pull/10133))
+- Stop recording an `error` when the applicant closes the SumSub SDK without submitting. Backing out is a normal outcome, but it was reported the same way as a genuine failure, so consumers surfaced "SumSub verification did not complete" to an applicant who had simply changed their mind. `acceptTermsAndStartSession` still rewinds to the `terms` phase and drops the spent UKYC session, but leaves `error` unset and reports the outcome through `sumsub.status = 'abandoned'`, which survives the rewind. An SDK that could not run is still recorded as `failed` with an `error`.
+- Pause user-keyed `GET /kyc/status` polling for the duration of the SumSub sub-flow, then resume it from `startSumSub` itself when the sub-flow settles. A tick landing while the SDK was on screen could flip the status to `completed` and publish `KycController:statusChanged`, pulling consumers (and their signing prompts) in front of a flow the applicant had not finished navigating. Restarting inside `startSumSub` covers abandonment, SDK failure, and callers that do not run `refreshKycStatus` (the MoonPay post-auth path).
 - Stop routing `KycService` write endpoints through the query cache. Every `POST` (`createSession`, `checkKycRequired`, `createVendorCustomer`, `submitVendorDisclaimers`, `submitSessionDisclaimers`, `createUkycSession`, `setAuthorizations`, `createJourney`) now issues its request directly instead of via `fetchQuery`. Previously these were modelled as queries, so two overlapping calls sharing a `queryKey` were deduplicated into a single request — a second `createVendorCustomer` while the first was in flight never reached the API — and their responses were retained in the cache and published on the messenger as `cacheUpdated` payloads, which for these endpoints include session tokens and applicant access tokens. Writes are also no longer retried by the service policy, so a failed non-idempotent request cannot create duplicate records server-side. ([#10007](https://github.com/MetaMask/core/pull/10007))
 - Stop incorrectly prefixing the session client public key onto wrapped `encryptionDataKey` and `ukycCapabilityToken` values from `wrapEncryptionKey`. `data` is now ciphertext+tag only; the server already has the client public key from session creation. ([#10036](https://github.com/MetaMask/core/pull/10036))
 - Clear leftover MoonPay `sessionToken`, `accessToken`, and Check/Auth frame credentials when `initialize` or `createVendorCustomer` switches to another vendor, so `buildCheckFrameUrl` cannot return a MoonPay URL for a consents-path session. ([#9908](https://github.com/MetaMask/core/pull/9908))

package/dist/KycController.cjs

@@ -10,7 +10,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _KycController_instances, _KycController_sumsubLauncher, _KycController_moonPayFrames, _KycController_generation, _KycController_sessionStatusPollIntervalMs, _KycController_pollTimer, _KycController_pollToken, _KycController_userStatusPollIntervalMs, _KycController_userStatusPollTimer, _KycController_userStatusPolling, _KycController_userStatusPollToken, _KycController_localUserSecretStore, _KycController_startConsentsSession, _KycController_recordSessionDisclaimers, _KycController_createSession, _KycController_clearAcceptedTerms, _KycController_continueAfterAuthentication, _KycController_requireTermsReacceptance, _KycController_buildUkycSessionVendorFields, _KycController_createUkycSession, _KycController_fetchAndApplyUserStatus, _KycController_applyUserStatus, _KycController_ensureUserStatusPolling, _KycController_stopUserStatusPolling, _KycController_startSessionStatusPolling, _KycController_pollSessionStatusOnce, _KycController_stopPolling, _KycController_cancelPendingSession, _KycController_updateIfCurrent, _KycController_applyUpdate, _KycController_assertAttestedServerPublicKey, _KycController_fail;
+var _KycController_instances, _KycController_sumsubLauncher, _KycController_moonPayFrames, _KycController_generation, _KycController_sessionStatusPollIntervalMs, _KycController_pollTimer, _KycController_pollToken, _KycController_userStatusPollIntervalMs, _KycController_userStatusPollTimer, _KycController_userStatusPolling, _KycController_userStatusPollToken, _KycController_localUserSecretStore, _KycController_startConsentsSession, _KycController_rewindConsentsFlow, _KycController_recordSessionDisclaimers, _KycController_createSession, _KycController_clearAcceptedTerms, _KycController_continueAfterAuthentication, _KycController_requireTermsReacceptance, _KycController_buildUkycSessionVendorFields, _KycController_createUkycSession, _KycController_fetchAndApplyUserStatus, _KycController_applyUserStatus, _KycController_ensureUserStatusPolling, _KycController_resumeUserStatusAfterSumSub, _KycController_stopUserStatusPolling, _KycController_startSessionStatusPolling, _KycController_pollSessionStatusOnce, _KycController_stopPolling, _KycController_cancelPendingSession, _KycController_updateIfCurrent, _KycController_applyUpdate, _KycController_assertAttestedServerPublicKey, _KycController_fail;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KycController = exports.getDefaultKycControllerState = exports.getDefaultKycProviderDisclaimersAccepted = exports.getDefaultKycVendorDisclaimersAccepted = exports.controllerName = void 0;
 const base_controller_1 = require("@metamask/base-controller");
@@ -35,10 +35,44 @@ const MOCK_JWT_TOKEN = 'mock-jwt-token';
 // cover the KYC session's expected lifetime — including the provider journey —
 // rather than a fixed short window, so this is a session-scoped window.
 const UKYC_CAPABILITY_TOKEN_TTL_MS = 4 * 60 * 60 * 1000;
-// The SumSub SDK status that signals the applicant finished the flow
-// successfully. Any other resolution (abandonment, failure, or a non-success
-// outcome) must not be recorded as `complete`.
-const SUMSUB_COMPLETED_STATUS = 'Completed';
+// SumSub statuses that mean the applicant submitted (see `KycSumSubSdkStatus`
+// for what each one reports). `Completed` covers launchers that normalize the
+// platform status before forwarding it. Review decisions (`Approved`,
+// `FinallyRejected`, `TemporarilyDeclined`) are post-submission outcomes: the
+// applicant finished the SDK, so UKYC is polled for the authoritative
+// decision. Pre-submission statuses (`Ready`, `Initial`, `Incomplete`) must
+// not be recorded as a completed verification.
+const SUMSUB_COMPLETED_STATUSES = new Set([
+    'Completed',
+    'Pending',
+    'Approved',
+    'ActionCompleted',
+    'FinallyRejected',
+    'TemporarilyDeclined',
+]);
+// The only status meaning the SDK could not run, rather than reporting how far
+// the applicant got before closing it.
+const SUMSUB_FAILED_STATUS = 'Failed';
+const SUMSUB_ABANDONED_MESSAGE = 'Identity verification was not finished — accept the terms to try again.';
+/**
+ * Checks whether a SumSub status means the applicant submitted the flow.
+ *
+ * @param status - Status from a launcher callback or launch result.
+ * @returns Whether the applicant submitted, including a review decision.
+ */
+function isSumSubFlowCompleted(status) {
+    return typeof status === 'string' && SUMSUB_COMPLETED_STATUSES.has(status);
+}
+/**
+ * Checks whether the SDK failed to run, as opposed to the applicant closing it
+ * early. Only the former is worth reporting as an error.
+ *
+ * @param result - The result the launcher resolved with.
+ * @returns Whether the SDK failed to run.
+ */
+function isSumSubLaunchFailure(result) {
+    return (result.status === SUMSUB_FAILED_STATUS || typeof result.error === 'string');
+}
 // Phases that represent an active vendor-session flow (tokens issued and/or
 // Check/Auth frames in progress). A repeat `initialize` while in one of these
 // must not restart the session and disrupt the in-flight flow.
@@ -905,145 +939,169 @@ class KycController extends base_controller_1.BaseController {
     async startSumSub(params) {
         // A new sub-flow supersedes any polling still running from a prior run.
         __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_stopPolling).call(this);
-        if (!__classPrivateFieldGet(this, _KycController_sumsubLauncher, "f").isAvailable()) {
-            const error = 'SumSub SDK is not available in this runtime.';
-            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
-                state.sumsub.status = 'failed';
-                state.sumsub.result = { error };
-            });
-            throw new Error(error);
-        }
+        // Paused for the whole sub-flow: a tick landing while the SDK is on screen
+        // publishes `statusChanged`, pulling consumers (and their signing prompts)
+        // in front of a flow the applicant has not finished. Resumed in `finally`
+        // so abandonment, SDK failure, and callers that do not run
+        // `refreshKycStatus` (MoonPay post-auth) still restore the loop.
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_stopUserStatusPolling).call(this);
         // Capture the flow generation so each async step can detect a `reset()`
         // that lands mid-flight and avoid writing stale sub-flow state (or, worse,
         // presenting the SDK) on a controller that is now idle.
         const generation = __classPrivateFieldGet(this, _KycController_generation, "f");
         try {
-            if (!this.state.sumsub.sessionId) {
+            if (!__classPrivateFieldGet(this, _KycController_sumsubLauncher, "f").isAvailable()) {
+                const error = 'SumSub SDK is not available in this runtime.';
                 __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
-                    state.sumsub.status = 'creatingSession';
-                    state.sumsub.result = null;
-                    state.sumsub.sessionStatus = null;
+                    state.sumsub.status = 'failed';
+                    state.sumsub.result = { error };
+                });
+                throw new Error(error);
+            }
+            try {
+                if (!this.state.sumsub.sessionId) {
+                    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+                        state.sumsub.status = 'creatingSession';
+                        state.sumsub.result = null;
+                        state.sumsub.sessionStatus = null;
+                    });
+                    const created = await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_createUkycSession).call(this, generation);
+                    if (!created) {
+                        return {};
+                    }
+                    // A user who already finished the journey can return to a session the
+                    // relay has already approved (`kycStatus`) while the vendor is still
+                    // finalizing its own decision (`finalStatus`). There is nothing left to
+                    // verify, so stop here and surface a message rather than launching the
+                    // SDK again.
+                    if (created.vendorProcessing) {
+                        return {
+                            kycStatus: created.kycStatus,
+                            finalStatus: created.finalStatus,
+                        };
+                    }
+                }
+                // Empty string is a valid "no id to poll" session id used by tests and
+                // must not be coalesced away as missing.
+                // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+                const sessionId = this.state.sumsub.sessionId || '';
+                __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
+                    state.sumsub.status = 'fetchingToken';
+                    state.sumsub.sessionId = sessionId;
                 });
-                const created = await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_createUkycSession).call(this, generation);
-                if (!created) {
+                const { applicantAccessToken } = await this.messenger.call('KycService:createJourney', sessionId);
+                // A reset() may have landed while the session/token was being prepared.
+                // Gate the `launching` write and the decision to open the SDK behind a
+                // single generation check: `#updateIfCurrent` only writes when still
+                // current and reports whether it did. Since there is no `await` between
+                // this check and `launch` below, a successful result guarantees the SDK
+                // is never presented on a flow that a concurrent reset() returned to idle.
+                const stillCurrent = __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
+                    state.sumsub.status = 'launching';
+                    state.sumsub.applicantAccessToken = applicantAccessToken;
+                });
+                if (!stillCurrent) {
                     return {};
                 }
-                // A user who already finished the journey can return to a session the
-                // relay has already approved (`kycStatus`) while the vendor is still
-                // finalizing its own decision (`finalStatus`). There is nothing left to
-                // verify, so stop here and surface a message rather than launching the
-                // SDK again.
-                if (created.vendorProcessing) {
-                    return {
-                        kycStatus: created.kycStatus,
-                        finalStatus: created.finalStatus,
-                    };
+                // Track whether the SDK ever reported a successful completion. A resolved
+                // `launch` alone does not imply success — the applicant may have
+                // abandoned the flow or the SDK may have reported a non-success outcome.
+                let reachedCompletion = false;
+                const result = await __classPrivateFieldGet(this, _KycController_sumsubLauncher, "f").launch({
+                    applicantAccessToken,
+                    onTokenExpiration: async () => {
+                        // A reset() may have superseded this flow while the SDK stayed open.
+                        // Refuse to refresh against the now-stale UKYC session rather than
+                        // silently keeping an orphaned SDK alive.
+                        if (__classPrivateFieldGet(this, _KycController_generation, "f") !== generation) {
+                            throw new Error('KYC flow was reset; SumSub session is no longer active.');
+                        }
+                        const refreshed = await this.messenger.call('KycService:createJourney', sessionId);
+                        return refreshed.applicantAccessToken;
+                    },
+                    onStatusChange: (_prev, next) => {
+                        if (isSumSubFlowCompleted(next)) {
+                            reachedCompletion = true;
+                        }
+                        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
+                            state.sumsub.status = isSumSubFlowCompleted(next)
+                                ? 'complete'
+                                : 'inProgress';
+                        });
+                    },
+                    locale: params?.locale ?? 'en',
+                    debug: params?.debug ?? false,
+                });
+                // Some native SDKs resolve with their final status without first
+                // delivering the corresponding state-change callback.
+                reachedCompletion || (reachedCompletion = isSumSubFlowCompleted(result.status));
+                // A resolved `launch` alone is not the final outcome: only a submission
+                // is worth polling for a decision. Without one, the SDK status is the
+                // only way to tell a failure from an applicant who closed the SDK early
+                // — the UKYC session leaves its initial state as soon as the journey is
+                // created, so it cannot stand in for "the applicant finished".
+                let settledStatus = 'abandoned';
+                if (reachedCompletion) {
+                    settledStatus = 'polling';
                 }
+                else if (isSumSubLaunchFailure(result)) {
+                    settledStatus = 'failed';
+                }
+                const applied = __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
+                    state.sumsub.status = settledStatus;
+                    state.sumsub.result = result;
+                });
+                // Once the SDK completes, the authoritative verification decision comes
+                // from the UKYC backend, not the SDK result. Poll the session status
+                // until it reaches a terminal decision. Guard on `applied` so a `reset()`
+                // that landed during `launch` cannot start polling on an idle flow.
+                if (applied && reachedCompletion) {
+                    if (sessionId) {
+                        await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_startSessionStatusPolling).call(this, sessionId);
+                    }
+                    else {
+                        // No session id to poll against; fall back to treating the SDK
+                        // completion as the final outcome.
+                        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
+                            state.sumsub.status = 'complete';
+                        });
+                    }
+                }
+                return result;
             }
-            // Empty string is a valid "no id to poll" session id used by tests and
-            // must not be coalesced away as missing.
-            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-            const sessionId = this.state.sumsub.sessionId || '';
-            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
-                state.sumsub.status = 'fetchingToken';
-                state.sumsub.sessionId = sessionId;
-            });
-            const { applicantAccessToken } = await this.messenger.call('KycService:createJourney', sessionId);
-            // A reset() may have landed while the session/token was being prepared.
-            // Gate the `launching` write and the decision to open the SDK behind a
-            // single generation check: `#updateIfCurrent` only writes when still
-            // current and reports whether it did. Since there is no `await` between
-            // this check and `launch` below, a successful result guarantees the SDK
-            // is never presented on a flow that a concurrent reset() returned to idle.
-            const stillCurrent = __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
-                state.sumsub.status = 'launching';
-                state.sumsub.applicantAccessToken = applicantAccessToken;
-            });
-            if (!stillCurrent) {
-                return {};
-            }
-            // Track whether the SDK ever reported a successful completion. A resolved
-            // `launch` alone does not imply success — the applicant may have
-            // abandoned the flow or the SDK may have reported a non-success outcome.
-            let reachedCompletion = false;
-            const result = await __classPrivateFieldGet(this, _KycController_sumsubLauncher, "f").launch({
-                applicantAccessToken,
-                onTokenExpiration: async () => {
-                    // A reset() may have superseded this flow while the SDK stayed open.
-                    // Refuse to refresh against the now-stale UKYC session rather than
-                    // silently keeping an orphaned SDK alive.
+            catch (error) {
+                // Applicant already finished KYC — treat as completed for Money toast.
+                if (isSessionAlreadyCompletedError(error)) {
+                    // A reset() may have landed while `launch` was in flight; forcing
+                    // `completed` (and publishing `statusChanged`) on an idle controller
+                    // would resurrect a flow the consumer already tore down.
                     if (__classPrivateFieldGet(this, _KycController_generation, "f") !== generation) {
-                        throw new Error('KYC flow was reset; SumSub session is no longer active.');
-                    }
-                    const refreshed = await this.messenger.call('KycService:createJourney', sessionId);
-                    return refreshed.applicantAccessToken;
-                },
-                onStatusChange: (_prev, next) => {
-                    if (next === SUMSUB_COMPLETED_STATUS) {
-                        reachedCompletion = true;
+                        return { alreadyCompleted: true };
                     }
-                    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
-                        state.sumsub.status =
-                            next === SUMSUB_COMPLETED_STATUS ? 'complete' : 'inProgress';
+                    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUserStatus).call(this, {
+                        status: 'completed',
+                        sumsubSessionId: null,
+                        errorCode: null,
                     });
-                },
-                locale: params?.locale ?? 'en',
-                debug: params?.debug ?? false,
-            });
-            // A resolved `launch` alone is not the final outcome: only a SDK-reported
-            // completion is worth polling for a verification decision. Anything else
-            // (abandonment, non-success) is `failed` and must not be polled.
-            const applied = __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
-                state.sumsub.status = reachedCompletion ? 'polling' : 'failed';
-                state.sumsub.result = result;
-            });
-            // Once the SDK completes, the authoritative verification decision comes
-            // from the UKYC backend, not the SDK result. Poll the session status
-            // until it reaches a terminal decision. Guard on `applied` so a `reset()`
-            // that landed during `launch` cannot start polling on an idle flow.
-            if (applied && reachedCompletion) {
-                if (sessionId) {
-                    await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_startSessionStatusPolling).call(this, sessionId);
-                }
-                else {
-                    // No session id to poll against; fall back to treating the SDK
-                    // completion as the final outcome.
                     __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
                         state.sumsub.status = 'complete';
+                        state.sumsub.result = { alreadyCompleted: true };
+                        state.statusMessage = 'KYC already completed.';
+                        state.phase = 'done';
+                        state.error = null;
                     });
-                }
-            }
-            return result;
-        }
-        catch (error) {
-            // Applicant already finished KYC — treat as completed for Money toast.
-            if (isSessionAlreadyCompletedError(error)) {
-                // A reset() may have landed while `launch` was in flight; forcing
-                // `completed` (and publishing `statusChanged`) on an idle controller
-                // would resurrect a flow the consumer already tore down.
-                if (__classPrivateFieldGet(this, _KycController_generation, "f") !== generation) {
                     return { alreadyCompleted: true };
                 }
-                __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUserStatus).call(this, {
-                    status: 'completed',
-                    sumsubSessionId: null,
-                    errorCode: null,
-                });
+                const result = { error: String(error) };
                 __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
-                    state.sumsub.status = 'complete';
-                    state.sumsub.result = { alreadyCompleted: true };
-                    state.statusMessage = 'KYC already completed.';
-                    state.phase = 'done';
-                    state.error = null;
+                    state.sumsub.status = 'failed';
+                    state.sumsub.result = result;
                 });
-                return { alreadyCompleted: true };
+                return result;
             }
-            const result = { error: String(error) };
-            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
-                state.sumsub.status = 'failed';
-                state.sumsub.result = result;
-            });
-            return result;
+        }
+        finally {
+            await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_resumeUserStatusAfterSumSub).call(this, generation);
         }
     }
     /**
@@ -1214,18 +1272,26 @@ async function _KycController_startConsentsSession(consents) {
         if (__classPrivateFieldGet(this, _KycController_generation, "f") !== generation) {
             return;
         }
-        // `startSumSub` records `sumsub.status = 'failed'` for thrown steps,
-        // an SDK close without Completed, *and* a terminal UKYC rejection
-        // after the SDK reported Completed. Only rewind when there is no
-        // session-status decision yet (abandonment / thrown step). A
-        // Completed-then-rejected poll writes `sessionStatus` and is a
-        // finished flow: refresh user status and land on `done`.
+        // The applicant closed the SDK without submitting. Nothing failed, so
+        // rewind with `error` unset and let consumers offer a retry.
+        if (this.state.sumsub.status === 'abandoned') {
+            await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_rewindConsentsFlow).call(this, {
+                error: null,
+                statusMessage: SUMSUB_ABANDONED_MESSAGE,
+                keepSumSubStatus: 'abandoned',
+            });
+            return;
+        }
+        // `startSumSub` records `failed` for thrown steps, an SDK that could not
+        // run, *and* a terminal UKYC rejection after a submission. Only the first
+        // two rewind. A rejection writes `sessionStatus` and is a finished flow:
+        // refresh user status and land on `done`.
         if (this.state.sumsub.status === 'failed' &&
             this.state.sumsub.sessionStatus === null) {
             const sumsubError = sumsubResult?.error;
             throw new Error(typeof sumsubError === 'string'
                 ? sumsubError
-                : 'SumSub verification did not complete.');
+                : 'SumSub verification could not run.');
         }
         // After SumSub, refresh user-keyed status for the Money toast and start
         // polling while still pending. Soft-fail: toast refresh must not rewind
@@ -1266,20 +1332,41 @@ async function _KycController_startConsentsSession(consents) {
         if (__classPrivateFieldGet(this, _KycController_generation, "f") !== generation) {
             return;
         }
-        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
-            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_clearAcceptedTerms).call(this, state);
-            state.activeProduct = null;
-            state.sessionDisclaimers = null;
-            // Session create ran before recording disclaimers. Drop the leftover
-            // UKYC session so a later `startSumSub` cannot skip consent recording.
-            state.sumsub = { ...getDefaultKycControllerState().sumsub };
-            state.error = `Consents session failed: ${String(error)}`;
-            state.statusMessage =
-                'Consent / verification failed — accept the terms to try again.';
-            state.phase = 'terms';
+        await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_rewindConsentsFlow).call(this, {
+            error: `Consents session failed: ${String(error)}`,
+            statusMessage: 'Consent / verification failed — accept the terms to try again.',
         });
-        await this.loadDisclaimers();
     }
+}, _KycController_rewindConsentsFlow = 
+/**
+ * Returns the consents path to the terms phase after a SumSub sub-flow that
+ * produced no verification decision, and reloads the disclaimers the next
+ * attempt has to re-accept.
+ *
+ * @param options - Rewind options.
+ * @param options.error - Message for `error`, or `null` when the rewind is a
+ * normal outcome rather than a failure.
+ * @param options.statusMessage - Message for `statusMessage`.
+ * @param options.keepSumSubStatus - Sub-flow status to survive the rewind,
+ * for an outcome consumers still need once the call resolves. Defaults to the
+ * reset `idle`.
+ */
+async function _KycController_rewindConsentsFlow({ error, statusMessage, keepSumSubStatus, }) {
+    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_clearAcceptedTerms).call(this, state);
+        state.activeProduct = null;
+        state.sessionDisclaimers = null;
+        // Session create ran before recording disclaimers. Drop the leftover
+        // UKYC session so a later `startSumSub` cannot skip consent recording.
+        state.sumsub = { ...getDefaultKycControllerState().sumsub };
+        if (keepSumSubStatus) {
+            state.sumsub.status = keepSumSubStatus;
+        }
+        state.error = error;
+        state.statusMessage = statusMessage;
+        state.phase = 'terms';
+    });
+    await this.loadDisclaimers();
 }, _KycController_recordSessionDisclaimers = 
 /**
  * Fetches the session-scoped disclaimer catalog and records consents
@@ -1645,6 +1732,28 @@ async function _KycController_fetchAndApplyUserStatus() {
         tick();
     }, __classPrivateFieldGet(this, _KycController_userStatusPollIntervalMs, "f")), "f");
     __classPrivateFieldGet(this, _KycController_userStatusPollTimer, "f").unref?.();
+}, _KycController_resumeUserStatusAfterSumSub = 
+/**
+ * Restores user-keyed `GET /kyc/status` polling after {@link startSumSub}
+ * settles. Skipped when a `reset()` superseded the sub-flow.
+ *
+ * @param generation - Flow generation captured when the sub-flow started.
+ */
+async function _KycController_resumeUserStatusAfterSumSub(generation) {
+    if (__classPrivateFieldGet(this, _KycController_generation, "f") !== generation) {
+        return;
+    }
+    // `session_not_in_valid_state` already wrote `completed`. A follow-up
+    // `GET /kyc/status` can still read a stale `pending` and must not undo it.
+    if (this.state.userStatus === 'completed') {
+        return;
+    }
+    try {
+        await this.refreshKycStatus();
+    }
+    catch (error) {
+        (0, logger_js_1.controllerLog)('KYC status refresh failed:', error);
+    }
 }, _KycController_stopUserStatusPolling = function _KycController_stopUserStatusPolling() {
     __classPrivateFieldSet(this, _KycController_userStatusPollToken, __classPrivateFieldGet(this, _KycController_userStatusPollToken, "f") + 1, "f");
     __classPrivateFieldSet(this, _KycController_userStatusPolling, false, "f");