@metamask-previews/kyc-controller 0.0.0-preview-823dcff → 0.0.0-preview-e57e5c3dc

package/dist/KycController.d.mts

@@ -0,0 +1,255 @@
+import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
+import { BaseController } from "@metamask/base-controller";
+import type { Messenger } from "@metamask/messenger";
+import type { UserStorageControllerPerformGetStorageAction, UserStorageControllerPerformSetStorageAction } from "@metamask/profile-sync-controller/user-storage";
+import type { Json } from "@metamask/utils";
+import type { KycControllerMethodActions } from "./KycController-method-action-types.mjs";
+import type { KycServiceMethodActions } from "./KycService-method-action-types.mjs";
+import type { KycDisclaimer, KycPhase, KycProduct, KycSessionStatus, KycSumSubLauncher, KycSumSubStatus } from "./types.mjs";
+export declare const controllerName = "KycController";
+/**
+ * Describes the shape of the state object for {@link KycController}.
+ */
+export type KycControllerState = {
+    /** Current phase of the identity flow. */
+    phase: KycPhase;
+    /** Human-readable status message for the current phase. */
+    statusMessage: string;
+    /** The current error message, or `null`. */
+    error: string | null;
+    /** Email associated with the session (sourced from the account). */
+    email: string | null;
+    /** ISO-8601 timestamp of the customer's terms acceptance (persisted). */
+    termsAcceptedAt: string | null;
+    /** IDs of the disclaimers the customer accepted (persisted). */
+    acceptedDisclaimerIds: string[];
+    /** Disclaimers fetched for the current country. */
+    disclaimers: KycDisclaimer[];
+    /** Error encountered while loading disclaimers, or `null`. */
+    disclaimersError: string | null;
+    /** Resolved ISO 3166-1 alpha-3 country code. */
+    geoCountry: string | null;
+    /** Vendor session token (not persisted, not logged). */
+    sessionToken: string | null;
+    /** Vendor access token (not persisted, not logged). */
+    accessToken: string | null;
+    /** Vendor customer id, used for the SumSub hand-off. */
+    moonpayCustomerId: string | null;
+    /**
+     * The product the current flow is running for. Captured at `initialize`
+     * (or `acceptTermsAndStartSession`) and used to automatically run the
+     * KYC-required check once authentication completes. `null` outside a
+     * product-scoped flow (in which case the flow stops at `form` and the
+     * consumer drives the check manually).
+     */
+    activeProduct: KycProduct | null;
+    /** Cached "is KYC required" result per product (persisted). */
+    kycRequiredByProduct: Partial<Record<KycProduct, boolean>>;
+    /** ISO-8601 timestamp of the last KYC-required check (persisted). */
+    lastCheckedAt: string | null;
+    /** SumSub document-verification sub-flow state. */
+    sumsub: {
+        status: KycSumSubStatus;
+        result: Json | null;
+        sessionId: string | null;
+        applicantAccessToken: string | null;
+        /**
+         * The latest UKYC session status, populated while polling after the SDK
+         * completes. `null` until the first successful poll.
+         */
+        sessionStatus: KycSessionStatus | null;
+    };
+};
+/**
+ * Constructs the default {@link KycController} state.
+ *
+ * @returns The default state.
+ */
+export declare function getDefaultKycControllerState(): KycControllerState;
+export type KycControllerGetStateAction = ControllerGetStateAction<typeof controllerName, KycControllerState>;
+export type KycControllerActions = KycControllerGetStateAction | KycControllerMethodActions;
+type AllowedActions = KycServiceMethodActions | UserStorageControllerPerformGetStorageAction | UserStorageControllerPerformSetStorageAction;
+export type KycControllerStateChangeEvent = ControllerStateChangeEvent<typeof controllerName, KycControllerState>;
+export type KycControllerEvents = KycControllerStateChangeEvent;
+type AllowedEvents = never;
+export type KycControllerMessenger = Messenger<typeof controllerName, KycControllerActions | AllowedActions, KycControllerEvents | AllowedEvents>;
+/**
+ * Options for constructing a {@link KycController}.
+ */
+export type KycControllerOptions = {
+    messenger: KycControllerMessenger;
+    state?: Partial<KycControllerState>;
+    /**
+     * Platform adapter that presents the SumSub SDK. Injected by each client so
+     * the controller stays platform-agnostic.
+     */
+    sumsubLauncher: KycSumSubLauncher;
+    /**
+     * How often, in milliseconds, to poll the UKYC session status after the
+     * SumSub SDK completes. Defaults to
+     * {@link DEFAULT_SESSION_STATUS_POLL_INTERVAL_MS}.
+     */
+    sessionStatusPollIntervalMs?: number;
+};
+/**
+ * `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 declare class KycController extends BaseController<typeof controllerName, KycControllerState, KycControllerMessenger> {
+    #private;
+    /**
+     * 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.
+     * @param options.sessionStatusPollIntervalMs - How often to poll the UKYC
+     * session status after the SumSub SDK completes.
+     */
+    constructor({ messenger, state, sumsubLauncher, sessionStatusPollIntervalMs, }: KycControllerOptions);
+    /**
+     * 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.
+     */
+    initialize(params?: {
+        email?: string;
+        product?: KycProduct;
+    }): Promise<void>;
+    /**
+     * Loads the disclaimers for the resolved (or provided) country.
+     *
+     * @param params - Optional parameters.
+     * @param params.country - ISO 3166-1 alpha-3 country code override.
+     */
+    loadDisclaimers(params?: {
+        country?: string;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    acceptTermsAndStartSession(params?: {
+        email?: string;
+        product?: KycProduct;
+    }): Promise<void>;
+    /**
+     * Clears the persisted terms acceptance.
+     */
+    clearSavedTerms(): void;
+    /**
+     * 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.
+     */
+    handleFrameMessage(params: {
+        message: unknown;
+    }): Promise<{
+        reply?: unknown;
+    }>;
+    /**
+     * Builds the Check-frame URL, or `null` when no session exists yet.
+     *
+     * @returns The Check-frame URL or `null`.
+     */
+    buildCheckFrameUrl(): string | null;
+    /**
+     * Builds the Auth-frame URL, or `null` when no client token is available.
+     *
+     * @returns The Auth-frame URL or `null`.
+     */
+    buildAuthFrameUrl(): string | null;
+    /**
+     * Builds the Reset-frame URL.
+     *
+     * @returns The Reset-frame URL.
+     */
+    buildResetFrameUrl(): string;
+    /**
+     * 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.
+     */
+    checkKycRequired(params: {
+        product: KycProduct;
+        country?: string;
+    }): Promise<boolean>;
+    /**
+     * 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: {
+        product: KycProduct;
+    }): boolean | undefined;
+    /**
+     * Runs the SumSub document-verification sub-flow end to end:
+     *
+     *  1. requests a per-session wrapping key from the UKYC backend;
+     *  2. verifies its `jwtChain` against the Fractal JWKS and confirms the
+     *     attested session server public key;
+     *  3. derives the `data_encryption_key` from the wallet's UKYC
+     *     `local_user_secret` and wraps it for the session server;
+     *  4. mints a client-signed, read-only `ukyc_capability_token` and creates
+     *     the UKYC session (handing over the wrapped key and the token);
+     *  5. fetches the SumSub applicant access token; and
+     *  6. presents the SDK via the injected launcher.
+     *
+     * If session creation reports the applicant is already approved on the relay
+     * while the vendor is still finalizing (`kycStatus: approved`,
+     * `finalStatus: pending`), the sub-flow stops at step 4 with a
+     * `vendorProcessing` status and a message rather than launching the SDK.
+     *
+     * @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.
+     */
+    startSumSub(params?: {
+        locale?: string;
+        debug?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Fetches the current UKYC session status for the active sub-flow and records
+     * it on state. Useful for a one-off refresh outside the automatic polling
+     * loop that {@link startSumSub} runs.
+     *
+     * @returns The fetched session status.
+     * @throws If there is no active SumSub session to query.
+     */
+    getSessionStatus(): Promise<KycSessionStatus>;
+    /**
+     * Resets the flow to idle, clearing session tokens and sub-flow state while
+     * preserving persisted terms acceptance and the per-product cache.
+     */
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=KycController.d.mts.map

package/dist/KycController.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KycController.d.mts","sourceRoot":"","sources":["../src/KycController.ts"],"names":[],"mappings":"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"}