@metamask-previews/kyc-controller 0.0.0-preview-11d78534e

package/dist/KycController.mjs

@@ -0,0 +1,795 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    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_keypair, _KycController_authClientToken, _KycController_generation, _KycController_continuationInFlight, _KycController_createSession, _KycController_clearAcceptedTerms, _KycController_handleCheckOutcome, _KycController_handleAuthOutcome, _KycController_continueAfterAuthentication, _KycController_requireTermsReacceptance, _KycController_updateIfCurrent, _KycController_applyUpdate, _KycController_fail;
+import { BaseController } from "@metamask/base-controller";
+import { decryptCredentials, generateKeyPair } from "./crypto.mjs";
+// === GENERAL ===
+export const controllerName = 'KycController';
+const FRAMES_BASE_URL = 'https://blocks.moonpay.com/platform/v1';
+const CHANNEL_CHECK = 'ch_1';
+const CHANNEL_AUTH = 'ch_2';
+const CHANNEL_RESET = 'ch_reset';
+// Placeholder credentials for the SumSub sub-flow. These are demo values that
+// must be replaced with real UKYC-issued material before production use.
+const MOCK_JWT_TOKEN = 'mock-jwt-token';
+// 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';
+const kycControllerMetadata = {
+    phase: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: false,
+        usedInUi: true,
+    },
+    statusMessage: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: false,
+        usedInUi: true,
+    },
+    error: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: false,
+        usedInUi: true,
+    },
+    email: {
+        includeInDebugSnapshot: false,
+        includeInStateLogs: false,
+        persist: false,
+        usedInUi: false,
+    },
+    termsAcceptedAt: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: true,
+        usedInUi: false,
+    },
+    acceptedDisclaimerIds: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: true,
+        usedInUi: false,
+    },
+    disclaimers: {
+        includeInDebugSnapshot: false,
+        includeInStateLogs: false,
+        persist: false,
+        usedInUi: true,
+    },
+    disclaimersError: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: false,
+        usedInUi: true,
+    },
+    geoCountry: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: false,
+        usedInUi: true,
+    },
+    sessionToken: {
+        includeInDebugSnapshot: false,
+        includeInStateLogs: false,
+        persist: false,
+        usedInUi: false,
+    },
+    accessToken: {
+        includeInDebugSnapshot: false,
+        includeInStateLogs: false,
+        persist: false,
+        usedInUi: false,
+    },
+    moonpayCustomerId: {
+        includeInDebugSnapshot: false,
+        includeInStateLogs: false,
+        persist: false,
+        usedInUi: false,
+    },
+    activeProduct: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: false,
+        usedInUi: true,
+    },
+    kycRequiredByProduct: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: true,
+        usedInUi: true,
+    },
+    lastCheckedAt: {
+        includeInDebugSnapshot: true,
+        includeInStateLogs: true,
+        persist: true,
+        usedInUi: false,
+    },
+    sumsub: {
+        includeInDebugSnapshot: false,
+        includeInStateLogs: false,
+        persist: false,
+        usedInUi: true,
+    },
+};
+/**
+ * Constructs the default {@link KycController} state.
+ *
+ * @returns The default state.
+ */
+export function getDefaultKycControllerState() {
+    return {
+        phase: 'idle',
+        statusMessage: '',
+        error: null,
+        email: null,
+        termsAcceptedAt: null,
+        acceptedDisclaimerIds: [],
+        disclaimers: [],
+        disclaimersError: null,
+        geoCountry: null,
+        sessionToken: null,
+        accessToken: null,
+        moonpayCustomerId: null,
+        activeProduct: null,
+        kycRequiredByProduct: {},
+        lastCheckedAt: null,
+        sumsub: {
+            status: 'idle',
+            result: null,
+            sessionId: null,
+            applicantAccessToken: null,
+        },
+    };
+}
+// === MESSENGER ===
+const MESSENGER_EXPOSED_METHODS = [
+    'initialize',
+    'loadDisclaimers',
+    'acceptTermsAndStartSession',
+    'clearSavedTerms',
+    'handleFrameMessage',
+    'buildCheckFrameUrl',
+    'buildAuthFrameUrl',
+    'buildResetFrameUrl',
+    'checkKycRequired',
+    'getKycStatus',
+    'startSumSub',
+    'reset',
+];
+// === CONTROLLER DEFINITION ===
+/**
+ * `KycController` orchestrates the vendor-backed KYC / identity-verification
+ * flow (MoonPay identity + SumSub documents) behind a vendor-neutral, per
+ * product surface used by ramps and card. It owns all state, HTTP
+ * orchestration (via `KycService`), crypto, and the frame message protocol;
+ * platform-specific presentation (WebView/iframe, SumSub SDK) is injected.
+ */
+export class KycController extends BaseController {
+    /**
+     * Constructs a new {@link KycController}.
+     *
+     * @param options - The constructor options.
+     * @param options.messenger - The messenger suited for this controller.
+     * @param options.state - Partial initial state; merged over defaults.
+     * @param options.sumsubLauncher - The platform SumSub launcher adapter.
+     */
+    constructor({ messenger, state, sumsubLauncher }) {
+        super({
+            messenger,
+            metadata: kycControllerMetadata,
+            name: controllerName,
+            state: { ...getDefaultKycControllerState(), ...state },
+        });
+        _KycController_instances.add(this);
+        _KycController_sumsubLauncher.set(this, void 0);
+        /** Ephemeral X25519 keypair for the frame key exchange (never persisted). */
+        _KycController_keypair.set(this, void 0);
+        /** Auth-frame client token, kept out of state. */
+        _KycController_authClientToken.set(this, null);
+        /**
+         * Monotonic flow generation. Incremented by {@link reset} so in-flight async
+         * work (e.g. the KYC-required check) can detect that it was superseded and
+         * avoid writing stale results onto a reset controller.
+         */
+        _KycController_generation.set(this, 0);
+        /**
+         * Guards the automatic post-authentication continuation. The Check/Auth
+         * frames can post more than one `complete` message (duplicate or late), each
+         * of which resolves to an `active` outcome with an access token. Without this
+         * flag, every such message would re-enter {@link #continueAfterAuthentication}
+         * and run the KYC-required check / SumSub sub-flow again while a prior run is
+         * still in flight. Set for the duration of a continuation and cleared by
+         * {@link reset} so a fresh flow can continue again.
+         */
+        _KycController_continuationInFlight.set(this, false);
+        __classPrivateFieldSet(this, _KycController_sumsubLauncher, sumsubLauncher, "f");
+        __classPrivateFieldSet(this, _KycController_keypair, generateKeyPair(), "f");
+        this.messenger.registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
+    }
+    /**
+     * Resolves persisted terms + geolocation, and auto-creates a session when
+     * terms are already accepted and an email is available.
+     *
+     * @param params - Optional parameters.
+     * @param params.email - The account email to associate with the session.
+     * @param params.product - The consuming feature the flow runs for. When
+     * provided, the controller automatically runs the KYC-required check once
+     * authentication completes (and chains into document verification when KYC
+     * is required). When omitted, the flow stops at `form` and the consumer must
+     * call `checkKycRequired` manually.
+     */
+    async initialize(params) {
+        // `initialize` starts a fresh flow, so `activeProduct` is always reset to
+        // this call's product (or `null`). Otherwise a prior run's product could
+        // linger and cause `#continueAfterAuthentication` to auto-run the check /
+        // sub-flow when the caller intended the manual (product-less) flow.
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            if (params?.email) {
+                state.email = params.email;
+            }
+            state.activeProduct = params?.product ?? null;
+        });
+        // Resolve country for display; non-blocking.
+        try {
+            const country = await this.messenger.call('KycService:getGeoCountry');
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+                state.geoCountry = country;
+            });
+        }
+        catch {
+            // Ignore; disclaimers loading will surface a country error if needed.
+        }
+        const hasTerms = Boolean(this.state.termsAcceptedAt) &&
+            this.state.acceptedDisclaimerIds.length > 0;
+        if (hasTerms && this.state.email) {
+            await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_createSession).call(this);
+            return;
+        }
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            state.phase = 'terms';
+        });
+        await this.loadDisclaimers();
+    }
+    /**
+     * Loads the disclaimers for the resolved (or provided) country.
+     *
+     * @param params - Optional parameters.
+     * @param params.country - ISO 3166-1 alpha-3 country code override.
+     */
+    async loadDisclaimers(params) {
+        try {
+            const country = params?.country ??
+                this.state.geoCountry ??
+                (await this.messenger.call('KycService:getGeoCountry'));
+            if (country !== this.state.geoCountry) {
+                __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+                    state.geoCountry = country;
+                });
+            }
+            const disclaimers = await this.messenger.call('KycService:fetchDisclaimers', { country });
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+                state.disclaimers = disclaimers;
+                state.disclaimersError = null;
+            });
+        }
+        catch (error) {
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+                state.disclaimersError = `Failed to load disclaimers: ${String(error)}`;
+            });
+        }
+    }
+    /**
+     * Captures terms acceptance for the currently loaded disclaimers and creates
+     * a session.
+     *
+     * @param params - Optional parameters.
+     * @param params.email - The account email to associate with the session.
+     * @param params.product - The consuming feature the flow runs for. See
+     * {@link initialize} for how the product drives the automatic post
+     * authentication continuation.
+     */
+    async acceptTermsAndStartSession(params) {
+        const termsAcceptedAt = new Date().toISOString();
+        const disclaimerIds = this.state.disclaimers.map((disclaimer) => disclaimer.id);
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            if (params?.email) {
+                state.email = params.email;
+            }
+            if (params?.product) {
+                state.activeProduct = params.product;
+            }
+            state.termsAcceptedAt = termsAcceptedAt;
+            state.acceptedDisclaimerIds = disclaimerIds;
+        });
+        await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_createSession).call(this);
+    }
+    /**
+     * Clears the persisted terms acceptance.
+     */
+    clearSavedTerms() {
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_clearAcceptedTerms).call(this, state);
+        });
+    }
+    /**
+     * Handles a message posted by a Check/Auth frame and advances the flow.
+     *
+     * The transport-agnostic caller (WebView on mobile, iframe on web) forwards
+     * the raw message and injects the returned `reply` back into the frame.
+     *
+     * @param params - The parameters.
+     * @param params.message - The raw message posted by the frame.
+     * @returns An object whose optional `reply` should be posted back.
+     */
+    async handleFrameMessage(params) {
+        const payload = params.message;
+        if (!payload) {
+            return {};
+        }
+        if (payload.kind === 'handshake') {
+            const channelId = payload.meta?.channelId;
+            return { reply: { version: 2, meta: { channelId }, kind: 'ack' } };
+        }
+        if (payload.kind !== 'complete') {
+            return {};
+        }
+        const channelId = payload.meta?.channelId;
+        const status = payload.payload?.status;
+        const credsEnvelope = payload.payload?.credentials;
+        const customerId = payload.payload?.customer?.id ?? null;
+        if (customerId) {
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+                state.moonpayCustomerId = customerId;
+            });
+        }
+        if (!status) {
+            return {};
+        }
+        let accessToken;
+        let clientToken;
+        if (credsEnvelope) {
+            try {
+                const { credentials } = decryptCredentials(credsEnvelope, __classPrivateFieldGet(this, _KycController_keypair, "f").privateKey);
+                accessToken = credentials.accessToken;
+                clientToken = credentials.clientToken;
+            }
+            catch (error) {
+                __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_fail).call(this, `Failed to decrypt frame credentials: ${String(error)}`);
+                return {};
+            }
+        }
+        if (channelId === CHANNEL_CHECK) {
+            await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_handleCheckOutcome).call(this, status, accessToken, clientToken);
+            return {};
+        }
+        if (channelId === CHANNEL_AUTH) {
+            await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_handleAuthOutcome).call(this, status, accessToken);
+            return {};
+        }
+        return {};
+    }
+    /**
+     * Builds the Check-frame URL, or `null` when no session exists yet.
+     *
+     * @returns The Check-frame URL or `null`.
+     */
+    buildCheckFrameUrl() {
+        if (!this.state.sessionToken) {
+            return null;
+        }
+        const url = new URL(`${FRAMES_BASE_URL}/check-connection`);
+        url.searchParams.set('sessionToken', this.state.sessionToken);
+        url.searchParams.set('publicKey', __classPrivateFieldGet(this, _KycController_keypair, "f").publicKeyHex);
+        url.searchParams.set('channelId', CHANNEL_CHECK);
+        url.searchParams.set('skipKyc', 'true');
+        return url.toString();
+    }
+    /**
+     * Builds the Auth-frame URL, or `null` when no client token is available.
+     *
+     * @returns The Auth-frame URL or `null`.
+     */
+    buildAuthFrameUrl() {
+        if (!__classPrivateFieldGet(this, _KycController_authClientToken, "f")) {
+            return null;
+        }
+        const url = new URL(`${FRAMES_BASE_URL}/auth`);
+        url.searchParams.set('clientToken', __classPrivateFieldGet(this, _KycController_authClientToken, "f"));
+        url.searchParams.set('publicKey', __classPrivateFieldGet(this, _KycController_keypair, "f").publicKeyHex);
+        url.searchParams.set('channelId', CHANNEL_AUTH);
+        return url.toString();
+    }
+    /**
+     * Builds the Reset-frame URL.
+     *
+     * @returns The Reset-frame URL.
+     */
+    buildResetFrameUrl() {
+        const url = new URL(`${FRAMES_BASE_URL}/reset`);
+        url.searchParams.set('channelId', CHANNEL_RESET);
+        return url.toString();
+    }
+    /**
+     * Checks whether KYC is required for a product and caches the result.
+     *
+     * @param params - The parameters.
+     * @param params.product - The consuming feature.
+     * @param params.country - Optional alpha-3 country override.
+     * @returns Whether KYC is required.
+     */
+    async checkKycRequired(params) {
+        const { accessToken } = this.state;
+        if (!accessToken) {
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_fail).call(this, 'Missing accessToken — repeat the authentication step.');
+            return false;
+        }
+        const country = params.country ?? this.state.geoCountry;
+        if (!country) {
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_fail).call(this, 'Missing country for KYC-required check.');
+            return false;
+        }
+        // Capture the flow generation so we can detect a `reset()` that happens
+        // while the HTTP call is in flight and avoid writing stale results.
+        const generation = __classPrivateFieldGet(this, _KycController_generation, "f");
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            state.phase = 'submit';
+            state.statusMessage = 'Checking KYC status...';
+        });
+        try {
+            const { kycRequired } = await this.messenger.call('KycService:checkKycRequired', { accessToken, country, capabilities: [{ product: params.product }] });
+            // The flow was reset while the check was in flight; discard the result
+            // rather than resurrecting a done/cached state on an idle controller.
+            if (__classPrivateFieldGet(this, _KycController_generation, "f") !== generation) {
+                return false;
+            }
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+                state.kycRequiredByProduct[params.product] = kycRequired;
+                state.lastCheckedAt = new Date().toISOString();
+                state.phase = 'done';
+                state.statusMessage = 'KYC check complete.';
+            });
+            return kycRequired;
+        }
+        catch (error) {
+            if (__classPrivateFieldGet(this, _KycController_generation, "f") !== generation) {
+                return false;
+            }
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_fail).call(this, `KYC check failed: ${String(error)}`);
+            return false;
+        }
+    }
+    /**
+     * Reads the cached "is KYC required" result for a product.
+     *
+     * @param params - The parameters.
+     * @param params.product - The consuming feature.
+     * @returns The cached value, or `undefined` if not yet checked.
+     */
+    getKycStatus(params) {
+        return this.state.kycRequiredByProduct[params.product];
+    }
+    /**
+     * Runs the SumSub document-verification sub-flow: creates a UKYC session,
+     * exchanges the wrapped key for an applicant access token, and presents the
+     * SDK via the injected launcher.
+     *
+     * @param params - Optional parameters.
+     * @param params.locale - BCP-47 locale for the SDK UI.
+     * @param params.debug - Enables SDK debug logging.
+     * @returns The SDK result.
+     */
+    async startSumSub(params) {
+        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);
+        }
+        // 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 {
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+                state.sumsub.status = 'creatingSession';
+                state.sumsub.result = null;
+            });
+            const jwtToken = MOCK_JWT_TOKEN;
+            const { sessionId, wrappingPublicKey, idosSessionId } = await this.messenger.call('KycService:createUkycSession', {
+                jwtToken,
+                vendorMetadata: {
+                    moonPayAccessToken: this.state.accessToken,
+                    moonPayUserId: this.state.moonpayCustomerId,
+                },
+            });
+            // Retain the exchange material so the SDK can refresh its token. The
+            // session's `wrappingPublicKey` is forwarded opaquely as the request's
+            // `wrappedUserKey` field (the /wrapped-key endpoint's body is unchanged).
+            const exchange = {
+                sessionId,
+                wrappedUserKey: wrappingPublicKey,
+                idosSessionId,
+                jwtToken,
+            };
+            __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:submitWrappedKey', exchange);
+            // A reset() landed while the session/token was being prepared; abort
+            // before presenting the SDK rather than launching on an idle controller.
+            if (__classPrivateFieldGet(this, _KycController_generation, "f") !== generation) {
+                return {};
+            }
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+                state.sumsub.status = 'launching';
+                state.sumsub.applicantAccessToken = applicantAccessToken;
+            });
+            // 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:submitWrappedKey', exchange);
+                    return refreshed.applicantAccessToken;
+                },
+                onStatusChange: (_prev, next) => {
+                    if (next === SUMSUB_COMPLETED_STATUS) {
+                        reachedCompletion = true;
+                    }
+                    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
+                        state.sumsub.status =
+                            next === SUMSUB_COMPLETED_STATUS ? 'complete' : 'inProgress';
+                    });
+                },
+                locale: params?.locale ?? 'en',
+                debug: params?.debug ?? false,
+            });
+            // Only record `complete` when the SDK actually reported completion;
+            // otherwise treat the resolved-but-unfinished flow as `failed` so
+            // consumers and UI do not mistake it for a finished verification.
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_updateIfCurrent).call(this, generation, (state) => {
+                state.sumsub.status = reachedCompletion ? 'complete' : 'failed';
+                state.sumsub.result = result;
+            });
+            return result;
+        }
+        catch (error) {
+            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;
+        }
+    }
+    /**
+     * Resets the flow to idle, clearing session tokens and sub-flow state while
+     * preserving persisted terms acceptance and the per-product cache.
+     */
+    reset() {
+        __classPrivateFieldSet(this, _KycController_authClientToken, null, "f");
+        // Invalidate any in-flight async work started before this reset.
+        __classPrivateFieldSet(this, _KycController_generation, __classPrivateFieldGet(this, _KycController_generation, "f") + 1, "f");
+        // Allow the next authenticated flow to auto-continue; any continuation from
+        // the superseded generation will no longer clear this flag (see the
+        // generation guard in `#continueAfterAuthentication`).
+        __classPrivateFieldSet(this, _KycController_continuationInFlight, false, "f");
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            state.phase = 'idle';
+            state.statusMessage = '';
+            state.error = null;
+            state.disclaimers = [];
+            state.disclaimersError = null;
+            state.sessionToken = null;
+            state.accessToken = null;
+            state.moonpayCustomerId = null;
+            state.activeProduct = null;
+            state.sumsub = {
+                status: 'idle',
+                result: null,
+                sessionId: null,
+                applicantAccessToken: null,
+            };
+        });
+    }
+}
+_KycController_sumsubLauncher = new WeakMap(), _KycController_keypair = new WeakMap(), _KycController_authClientToken = new WeakMap(), _KycController_generation = new WeakMap(), _KycController_continuationInFlight = new WeakMap(), _KycController_instances = new WeakSet(), _KycController_createSession = 
+/**
+ * Creates a vendor session from the currently stored terms + email.
+ */
+async function _KycController_createSession() {
+    const { email, termsAcceptedAt, acceptedDisclaimerIds } = this.state;
+    if (!email) {
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_fail).call(this, 'Missing email for session creation.');
+        return;
+    }
+    if (!termsAcceptedAt || acceptedDisclaimerIds.length === 0) {
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_fail).call(this, 'Missing terms acceptance for session creation.');
+        return;
+    }
+    // A new session invalidates any authentication carried over from a prior
+    // session. Clear the stale access token and auth-frame client token so
+    // `buildAuthFrameUrl` cannot return a URL tied to an old client token and
+    // `checkKycRequired` cannot run with an access token from an earlier
+    // authentication. The Check/Auth frames re-populate these for the new
+    // session.
+    __classPrivateFieldSet(this, _KycController_authClientToken, null, "f");
+    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+        state.error = null;
+        state.phase = 'session';
+        state.statusMessage = 'Creating session...';
+        state.accessToken = null;
+    });
+    try {
+        const { sessionToken } = await this.messenger.call('KycService:createSession', { email, termsAcceptedAt, disclaimerIds: acceptedDisclaimerIds });
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            state.sessionToken = sessionToken;
+            state.phase = 'check';
+            state.statusMessage = 'Authenticating via Check frame...';
+        });
+    }
+    catch (error) {
+        // Invalidate the stored acceptance so the customer can retry. Also clear
+        // `activeProduct` so a later `acceptTermsAndStartSession` that omits a
+        // product cannot auto-run the KYC check / SumSub chain for this failed
+        // flow's product — matching how `initialize` starts from a clean product.
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_clearAcceptedTerms).call(this, state);
+            state.activeProduct = null;
+            state.error = `Session creation failed: ${String(error)}`;
+            state.statusMessage =
+                'Session creation failed — accept the terms to try again.';
+            state.phase = 'terms';
+        });
+        await this.loadDisclaimers();
+    }
+}, _KycController_clearAcceptedTerms = function _KycController_clearAcceptedTerms(state) {
+    state.termsAcceptedAt = null;
+    state.acceptedDisclaimerIds = [];
+}, _KycController_handleCheckOutcome = 
+/**
+ * Applies a Check-frame outcome.
+ *
+ * @param status - The frame status.
+ * @param accessToken - The decrypted access token, if any.
+ * @param clientToken - The decrypted client token, if any.
+ */
+async function _KycController_handleCheckOutcome(status, accessToken, clientToken) {
+    if (status === 'active' && accessToken) {
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            state.accessToken = accessToken;
+            state.phase = 'form';
+            state.statusMessage = 'Already authenticated. Review to submit.';
+        });
+        await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_continueAfterAuthentication).call(this);
+        return;
+    }
+    if (status === 'connectionRequired' && clientToken) {
+        __classPrivateFieldSet(this, _KycController_authClientToken, clientToken, "f");
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            state.phase = 'auth';
+            state.statusMessage = 'Verify your email via OTP in the Auth frame.';
+        });
+        return;
+    }
+    if (status === 'termsAcceptanceRequired') {
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_requireTermsReacceptance).call(this);
+        return;
+    }
+    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_fail).call(this, `Check frame returned status: ${status}`);
+}, _KycController_handleAuthOutcome = 
+/**
+ * Applies an Auth-frame outcome.
+ *
+ * @param status - The frame status.
+ * @param accessToken - The decrypted access token, if any.
+ */
+async function _KycController_handleAuthOutcome(status, accessToken) {
+    if (status === 'active' && accessToken) {
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+            state.accessToken = accessToken;
+            state.phase = 'form';
+            state.statusMessage = 'Authenticated. Review to submit.';
+        });
+        await __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_continueAfterAuthentication).call(this);
+        return;
+    }
+    if (status === 'termsAcceptanceRequired') {
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_requireTermsReacceptance).call(this);
+        return;
+    }
+    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_fail).call(this, `Auth frame returned status: ${status}`);
+}, _KycController_continueAfterAuthentication = 
+/**
+ * Continues the flow once authentication has completed (phase `form`).
+ *
+ * When the flow is scoped to a product (see {@link initialize}), the
+ * KYC-required check runs automatically, and — when KYC is required — the
+ * document-verification sub-flow is launched. When no product is set, this is
+ * a no-op and the flow stays at `form` for the consumer to drive manually.
+ *
+ * Errors are already recorded on state by `checkKycRequired` (`error`
+ * phase) and `startSumSub` (`sumsub.status = 'failed'`); this method swallows
+ * them so it can be awaited safely from the frame-message handler.
+ */
+async function _KycController_continueAfterAuthentication() {
+    const product = this.state.activeProduct;
+    if (!product) {
+        return;
+    }
+    // A duplicate or late `complete` message can re-enter here while a prior
+    // continuation is still running; ignore it so the check / sub-flow does not
+    // run twice concurrently.
+    if (__classPrivateFieldGet(this, _KycController_continuationInFlight, "f")) {
+        return;
+    }
+    __classPrivateFieldSet(this, _KycController_continuationInFlight, true, "f");
+    // Capture the generation so a `reset()` landing mid-continuation does not
+    // let the `finally` clear a flag that belongs to a newer flow.
+    const generation = __classPrivateFieldGet(this, _KycController_generation, "f");
+    try {
+        const kycRequired = await this.checkKycRequired({ product });
+        if (!kycRequired) {
+            return;
+        }
+        try {
+            await this.startSumSub();
+        }
+        catch {
+            // `startSumSub` already records `sumsub.status = 'failed'`; swallow the
+            // rethrown error (e.g. SDK unavailable) so the awaited continuation
+            // resolves cleanly rather than surfacing as an unhandled rejection.
+        }
+    }
+    finally {
+        if (__classPrivateFieldGet(this, _KycController_generation, "f") === generation) {
+            __classPrivateFieldSet(this, _KycController_continuationInFlight, false, "f");
+        }
+    }
+}, _KycController_requireTermsReacceptance = function _KycController_requireTermsReacceptance() {
+    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+        __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_clearAcceptedTerms).call(this, state);
+        state.phase = 'terms';
+        state.statusMessage =
+            'The vendor updated its Terms of Use — please re-accept.';
+    });
+}, _KycController_updateIfCurrent = function _KycController_updateIfCurrent(generation, updater) {
+    if (__classPrivateFieldGet(this, _KycController_generation, "f") !== generation) {
+        return false;
+    }
+    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, updater);
+    return true;
+}, _KycController_applyUpdate = function _KycController_applyUpdate(updater) {
+    this.update((state) => {
+        updater(state);
+    });
+}, _KycController_fail = function _KycController_fail(message) {
+    __classPrivateFieldGet(this, _KycController_instances, "m", _KycController_applyUpdate).call(this, (state) => {
+        state.error = message;
+        state.phase = 'error';
+    });
+};
+//# sourceMappingURL=KycController.mjs.map