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

package/dist/KycService.d.cts

@@ -0,0 +1,169 @@
+import type { CreateServicePolicyOptions } from "@metamask/controller-utils";
+import type { GeolocationControllerGetGeolocationAction } from "@metamask/geolocation-controller";
+import type { Messenger } from "@metamask/messenger";
+import type { AuthenticationControllerGetBearerTokenAction } from "@metamask/profile-sync-controller/auth";
+import type { Infer, Struct } from "@metamask/superstruct";
+import type { KycServiceMethodActions } from "./KycService-method-action-types.cjs";
+import type { KycDisclaimer } from "./types.cjs";
+/**
+ * The name of the {@link KycService}, used to namespace the service's actions.
+ */
+export declare const serviceName = "KycService";
+/**
+ * The supported environments for the Universal KYC API.
+ */
+export type KycServiceEnvironment = 'production' | 'development';
+/**
+ * Actions that {@link KycService} exposes to other consumers.
+ */
+export type KycServiceActions = KycServiceMethodActions;
+/**
+ * Actions from other messengers that {@link KycService} calls.
+ */
+type AllowedActions = AuthenticationControllerGetBearerTokenAction | GeolocationControllerGetGeolocationAction;
+/**
+ * Events that {@link KycService} exposes to other consumers.
+ */
+export type KycServiceEvents = never;
+/**
+ * Events from other messengers that {@link KycService} subscribes to.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger restricted to actions and events accessed by
+ * {@link KycService}.
+ */
+export type KycServiceMessenger = Messenger<typeof serviceName, KycServiceActions | AllowedActions, KycServiceEvents | AllowedEvents>;
+/**
+ * Options for constructing a {@link KycService}.
+ */
+export type KycServiceOptions = {
+    messenger: KycServiceMessenger;
+    fetch: typeof fetch;
+    env: KycServiceEnvironment;
+    /**
+     * Overrides the base URL derived from `env`. When provided, this value is
+     * used verbatim as the base URL for all requests, which is useful for
+     * targeting a local or staging KYC API.
+     */
+    baseUrl?: string;
+    policyOptions?: CreateServicePolicyOptions;
+};
+declare const CreateSessionResponseStruct: Struct<{
+    sessionToken: string;
+}, {
+    sessionToken: Struct<string, null>;
+}>;
+declare const UkycSessionResponseStruct: Struct<{
+    sessionId: string;
+    wrappingPublicKey: string;
+    idosSessionId: string;
+}, {
+    sessionId: Struct<string, null>;
+    wrappingPublicKey: Struct<string, null>;
+    idosSessionId: Struct<string, null>;
+}>;
+export type UkycSessionResponse = Infer<typeof UkycSessionResponseStruct>;
+declare const WrappedKeyResponseStruct: Struct<{
+    status: string;
+    applicantAccessToken: string;
+}, {
+    status: Struct<string, null>;
+    applicantAccessToken: Struct<string, null>;
+}>;
+export type WrappedKeyResponse = Infer<typeof WrappedKeyResponseStruct>;
+export type CreateSessionParams = {
+    email: string;
+    termsAcceptedAt: string;
+    disclaimerIds: string[];
+};
+export type CheckKycRequiredParams = {
+    accessToken: string;
+    country: string;
+    capabilities?: {
+        product: string;
+    }[];
+};
+export type CreateUkycSessionParams = {
+    jwtToken: string;
+    vendorMetadata: Record<string, unknown>;
+};
+export type SubmitWrappedKeyParams = {
+    sessionId: string;
+    wrappedUserKey: string;
+    idosSessionId: string;
+    jwtToken: string;
+};
+/**
+ * `KycService` communicates with the Universal KYC (UKYC) backend to drive the
+ * identity + document-verification flow. It is stateless and platform-agnostic:
+ * HTTP is performed through an injected `fetch`, and the auth bearer token and
+ * geolocation come from other controllers via the messenger.
+ */
+export declare class KycService {
+    #private;
+    readonly name: typeof serviceName;
+    /**
+     * Constructs a new KycService.
+     *
+     * @param options - The constructor options.
+     * @param options.messenger - The messenger suited for this service.
+     * @param options.fetch - A function used to make HTTP requests.
+     * @param options.env - The environment; determines the base URL.
+     * @param options.baseUrl - Overrides the base URL derived from `env`.
+     * @param options.policyOptions - Options for the request service policy.
+     */
+    constructor({ messenger, fetch: fetchFunction, env, baseUrl, policyOptions, }: KycServiceOptions);
+    /**
+     * Resolves the customer's country from the geolocation source and converts it
+     * to an ISO 3166-1 alpha-3 code.
+     *
+     * @returns The alpha-3 country code.
+     * @throws If the country cannot be determined or mapped.
+     */
+    getGeoCountry(): Promise<string>;
+    /**
+     * Fetches the disclaimers the customer must accept before a session is
+     * created.
+     *
+     * @param params - The parameters.
+     * @param params.country - ISO 3166-1 alpha-3 country code.
+     * @returns The disclaimers.
+     */
+    fetchDisclaimers({ country, }: {
+        country: string;
+    }): Promise<KycDisclaimer[]>;
+    /**
+     * Creates a vendor session via the UKYC backend.
+     *
+     * @param params - The session parameters.
+     * @returns The created session token.
+     */
+    createSession(params: CreateSessionParams): Promise<Infer<typeof CreateSessionResponseStruct>>;
+    /**
+     * Checks whether KYC is required for the given access token, country, and
+     * capabilities.
+     *
+     * @param params - The check parameters.
+     * @returns Whether KYC is required.
+     */
+    checkKycRequired(params: CheckKycRequiredParams): Promise<{
+        kycRequired: boolean;
+    }>;
+    /**
+     * Creates a UKYC session for the SumSub document-verification sub-flow.
+     *
+     * @param params - The session parameters.
+     * @returns The UKYC session identifiers and wrapped key.
+     */
+    createUkycSession(params: CreateUkycSessionParams): Promise<UkycSessionResponse>;
+    /**
+     * Exchanges the wrapped user key for a SumSub applicant access token.
+     *
+     * @param params - The exchange parameters.
+     * @returns The applicant access token and status.
+     */
+    submitWrappedKey(params: SubmitWrappedKeyParams): Promise<WrappedKeyResponse>;
+}
+export {};
+//# sourceMappingURL=KycService.d.cts.map

package/dist/KycService.d.cts.map

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

package/dist/KycService.d.mts

@@ -0,0 +1,169 @@
+import type { CreateServicePolicyOptions } from "@metamask/controller-utils";
+import type { GeolocationControllerGetGeolocationAction } from "@metamask/geolocation-controller";
+import type { Messenger } from "@metamask/messenger";
+import type { AuthenticationControllerGetBearerTokenAction } from "@metamask/profile-sync-controller/auth";
+import type { Infer, Struct } from "@metamask/superstruct";
+import type { KycServiceMethodActions } from "./KycService-method-action-types.mjs";
+import type { KycDisclaimer } from "./types.mjs";
+/**
+ * The name of the {@link KycService}, used to namespace the service's actions.
+ */
+export declare const serviceName = "KycService";
+/**
+ * The supported environments for the Universal KYC API.
+ */
+export type KycServiceEnvironment = 'production' | 'development';
+/**
+ * Actions that {@link KycService} exposes to other consumers.
+ */
+export type KycServiceActions = KycServiceMethodActions;
+/**
+ * Actions from other messengers that {@link KycService} calls.
+ */
+type AllowedActions = AuthenticationControllerGetBearerTokenAction | GeolocationControllerGetGeolocationAction;
+/**
+ * Events that {@link KycService} exposes to other consumers.
+ */
+export type KycServiceEvents = never;
+/**
+ * Events from other messengers that {@link KycService} subscribes to.
+ */
+type AllowedEvents = never;
+/**
+ * The messenger restricted to actions and events accessed by
+ * {@link KycService}.
+ */
+export type KycServiceMessenger = Messenger<typeof serviceName, KycServiceActions | AllowedActions, KycServiceEvents | AllowedEvents>;
+/**
+ * Options for constructing a {@link KycService}.
+ */
+export type KycServiceOptions = {
+    messenger: KycServiceMessenger;
+    fetch: typeof fetch;
+    env: KycServiceEnvironment;
+    /**
+     * Overrides the base URL derived from `env`. When provided, this value is
+     * used verbatim as the base URL for all requests, which is useful for
+     * targeting a local or staging KYC API.
+     */
+    baseUrl?: string;
+    policyOptions?: CreateServicePolicyOptions;
+};
+declare const CreateSessionResponseStruct: Struct<{
+    sessionToken: string;
+}, {
+    sessionToken: Struct<string, null>;
+}>;
+declare const UkycSessionResponseStruct: Struct<{
+    sessionId: string;
+    wrappingPublicKey: string;
+    idosSessionId: string;
+}, {
+    sessionId: Struct<string, null>;
+    wrappingPublicKey: Struct<string, null>;
+    idosSessionId: Struct<string, null>;
+}>;
+export type UkycSessionResponse = Infer<typeof UkycSessionResponseStruct>;
+declare const WrappedKeyResponseStruct: Struct<{
+    status: string;
+    applicantAccessToken: string;
+}, {
+    status: Struct<string, null>;
+    applicantAccessToken: Struct<string, null>;
+}>;
+export type WrappedKeyResponse = Infer<typeof WrappedKeyResponseStruct>;
+export type CreateSessionParams = {
+    email: string;
+    termsAcceptedAt: string;
+    disclaimerIds: string[];
+};
+export type CheckKycRequiredParams = {
+    accessToken: string;
+    country: string;
+    capabilities?: {
+        product: string;
+    }[];
+};
+export type CreateUkycSessionParams = {
+    jwtToken: string;
+    vendorMetadata: Record<string, unknown>;
+};
+export type SubmitWrappedKeyParams = {
+    sessionId: string;
+    wrappedUserKey: string;
+    idosSessionId: string;
+    jwtToken: string;
+};
+/**
+ * `KycService` communicates with the Universal KYC (UKYC) backend to drive the
+ * identity + document-verification flow. It is stateless and platform-agnostic:
+ * HTTP is performed through an injected `fetch`, and the auth bearer token and
+ * geolocation come from other controllers via the messenger.
+ */
+export declare class KycService {
+    #private;
+    readonly name: typeof serviceName;
+    /**
+     * Constructs a new KycService.
+     *
+     * @param options - The constructor options.
+     * @param options.messenger - The messenger suited for this service.
+     * @param options.fetch - A function used to make HTTP requests.
+     * @param options.env - The environment; determines the base URL.
+     * @param options.baseUrl - Overrides the base URL derived from `env`.
+     * @param options.policyOptions - Options for the request service policy.
+     */
+    constructor({ messenger, fetch: fetchFunction, env, baseUrl, policyOptions, }: KycServiceOptions);
+    /**
+     * Resolves the customer's country from the geolocation source and converts it
+     * to an ISO 3166-1 alpha-3 code.
+     *
+     * @returns The alpha-3 country code.
+     * @throws If the country cannot be determined or mapped.
+     */
+    getGeoCountry(): Promise<string>;
+    /**
+     * Fetches the disclaimers the customer must accept before a session is
+     * created.
+     *
+     * @param params - The parameters.
+     * @param params.country - ISO 3166-1 alpha-3 country code.
+     * @returns The disclaimers.
+     */
+    fetchDisclaimers({ country, }: {
+        country: string;
+    }): Promise<KycDisclaimer[]>;
+    /**
+     * Creates a vendor session via the UKYC backend.
+     *
+     * @param params - The session parameters.
+     * @returns The created session token.
+     */
+    createSession(params: CreateSessionParams): Promise<Infer<typeof CreateSessionResponseStruct>>;
+    /**
+     * Checks whether KYC is required for the given access token, country, and
+     * capabilities.
+     *
+     * @param params - The check parameters.
+     * @returns Whether KYC is required.
+     */
+    checkKycRequired(params: CheckKycRequiredParams): Promise<{
+        kycRequired: boolean;
+    }>;
+    /**
+     * Creates a UKYC session for the SumSub document-verification sub-flow.
+     *
+     * @param params - The session parameters.
+     * @returns The UKYC session identifiers and wrapped key.
+     */
+    createUkycSession(params: CreateUkycSessionParams): Promise<UkycSessionResponse>;
+    /**
+     * Exchanges the wrapped user key for a SumSub applicant access token.
+     *
+     * @param params - The exchange parameters.
+     * @returns The applicant access token and status.
+     */
+    submitWrappedKey(params: SubmitWrappedKeyParams): Promise<WrappedKeyResponse>;
+}
+export {};
+//# sourceMappingURL=KycService.d.mts.map

package/dist/KycService.d.mts.map

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

package/dist/KycService.mjs

@@ -0,0 +1,234 @@
+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 _KycService_instances, _KycService_messenger, _KycService_fetch, _KycService_baseUrl, _KycService_policy, _KycService_validateResponse, _KycService_request;
+import { createServicePolicy, HttpError } from "@metamask/controller-utils";
+import { array, assert, boolean, string, StructError, type } from "@metamask/superstruct";
+import { alpha2ToAlpha3 } from "./countryCodes.mjs";
+// === GENERAL ===
+/**
+ * The name of the {@link KycService}, used to namespace the service's actions.
+ */
+export const serviceName = 'KycService';
+const KYC_API_URLS = {
+    production: 'https://kyc-api.cx.metamask.io',
+    development: 'https://kyc-api.dev-api.cx.metamask.io',
+};
+// === MESSENGER ===
+const MESSENGER_EXPOSED_METHODS = [
+    'getGeoCountry',
+    'fetchDisclaimers',
+    'createSession',
+    'checkKycRequired',
+    'createUkycSession',
+    'submitWrappedKey',
+];
+// === API RESPONSE SCHEMAS ===
+const DisclaimerStruct = type({
+    id: string(),
+    display_name: string(),
+    url: string(),
+});
+const DisclaimersResponseStruct = array(DisclaimerStruct);
+const CreateSessionResponseStruct = type({ sessionToken: string() });
+// The live KYC API returns the flag under `required`; the service normalizes
+// this to `kycRequired` for consumers (see `checkKycRequired`).
+const KycRequiredResponseStruct = type({ required: boolean() });
+const UkycSessionResponseStruct = type({
+    sessionId: string(),
+    wrappingPublicKey: string(),
+    idosSessionId: string(),
+});
+const WrappedKeyResponseStruct = type({
+    status: string(),
+    applicantAccessToken: string(),
+});
+// === SERVICE DEFINITION ===
+/**
+ * `KycService` communicates with the Universal KYC (UKYC) backend to drive the
+ * identity + document-verification flow. It is stateless and platform-agnostic:
+ * HTTP is performed through an injected `fetch`, and the auth bearer token and
+ * geolocation come from other controllers via the messenger.
+ */
+export class KycService {
+    /**
+     * Constructs a new KycService.
+     *
+     * @param options - The constructor options.
+     * @param options.messenger - The messenger suited for this service.
+     * @param options.fetch - A function used to make HTTP requests.
+     * @param options.env - The environment; determines the base URL.
+     * @param options.baseUrl - Overrides the base URL derived from `env`.
+     * @param options.policyOptions - Options for the request service policy.
+     */
+    constructor({ messenger, fetch: fetchFunction, env, baseUrl, policyOptions, }) {
+        _KycService_instances.add(this);
+        _KycService_messenger.set(this, void 0);
+        _KycService_fetch.set(this, void 0);
+        _KycService_baseUrl.set(this, void 0);
+        _KycService_policy.set(this, void 0);
+        this.name = serviceName;
+        __classPrivateFieldSet(this, _KycService_messenger, messenger, "f");
+        __classPrivateFieldSet(this, _KycService_fetch, fetchFunction, "f");
+        __classPrivateFieldSet(this, _KycService_baseUrl, baseUrl ?? KYC_API_URLS[env], "f");
+        __classPrivateFieldSet(this, _KycService_policy, createServicePolicy(policyOptions ?? {}), "f");
+        __classPrivateFieldGet(this, _KycService_messenger, "f").registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
+    }
+    /**
+     * Resolves the customer's country from the geolocation source and converts it
+     * to an ISO 3166-1 alpha-3 code.
+     *
+     * @returns The alpha-3 country code.
+     * @throws If the country cannot be determined or mapped.
+     */
+    async getGeoCountry() {
+        const location = await __classPrivateFieldGet(this, _KycService_messenger, "f").call('GeolocationController:getGeolocation');
+        // Guard nullish/empty geolocation with the documented domain error rather
+        // than letting `assert(location, string())` surface a superstruct
+        // assertion error (which would change how the failure reads in
+        // `disclaimersError`).
+        const alpha2 = typeof location === 'string' ? location.split('-')[0].toUpperCase() : '';
+        if (!alpha2 || alpha2 === 'UNKNOWN') {
+            throw new Error(`Unable to determine country from geolocation (got "${String(location)}").`);
+        }
+        const alpha3 = alpha2ToAlpha3(alpha2);
+        if (!alpha3) {
+            throw new Error(`Unable to map country code "${alpha2}" to an ISO 3166-1 alpha-3 code.`);
+        }
+        return alpha3;
+    }
+    /**
+     * Fetches the disclaimers the customer must accept before a session is
+     * created.
+     *
+     * @param params - The parameters.
+     * @param params.country - ISO 3166-1 alpha-3 country code.
+     * @returns The disclaimers.
+     */
+    async fetchDisclaimers({ country, }) {
+        const url = new URL('/vendors/moonpay/disclaimers', __classPrivateFieldGet(this, _KycService_baseUrl, "f"));
+        url.searchParams.set('country', country);
+        const data = await __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_request).call(this, url, { method: 'GET' });
+        return __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, DisclaimersResponseStruct, 'disclaimers');
+    }
+    /**
+     * Creates a vendor session via the UKYC backend.
+     *
+     * @param params - The session parameters.
+     * @returns The created session token.
+     */
+    async createSession(params) {
+        const url = new URL('/vendors/moonpay/sessions', __classPrivateFieldGet(this, _KycService_baseUrl, "f"));
+        const data = await __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_request).call(this, url, {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+        return __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, CreateSessionResponseStruct, 'sessions');
+    }
+    /**
+     * Checks whether KYC is required for the given access token, country, and
+     * capabilities.
+     *
+     * @param params - The check parameters.
+     * @returns Whether KYC is required.
+     */
+    async checkKycRequired(params) {
+        const url = new URL('/vendors/moonpay/kyc-required', __classPrivateFieldGet(this, _KycService_baseUrl, "f"));
+        const data = await __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_request).call(this, url, {
+            method: 'POST',
+            body: JSON.stringify({
+                accessToken: params.accessToken,
+                country: params.country,
+                capabilities: params.capabilities ?? [{ product: 'ramps' }],
+            }),
+        });
+        const { required } = __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, KycRequiredResponseStruct, 'kyc-required');
+        return { kycRequired: required };
+    }
+    /**
+     * Creates a UKYC session for the SumSub document-verification sub-flow.
+     *
+     * @param params - The session parameters.
+     * @returns The UKYC session identifiers and wrapped key.
+     */
+    async createUkycSession(params) {
+        const url = new URL('/sessions', __classPrivateFieldGet(this, _KycService_baseUrl, "f"));
+        const data = await __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_request).call(this, url, {
+            method: 'POST',
+            body: JSON.stringify({
+                vendorId: 'moonpay',
+                vendorUserId: 'mockedId',
+                jwtToken: params.jwtToken,
+                vendorMetadata: params.vendorMetadata,
+            }),
+        });
+        return __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, UkycSessionResponseStruct, 'UKYC sessions');
+    }
+    /**
+     * Exchanges the wrapped user key for a SumSub applicant access token.
+     *
+     * @param params - The exchange parameters.
+     * @returns The applicant access token and status.
+     */
+    async submitWrappedKey(params) {
+        const url = new URL(`/sessions/${encodeURIComponent(params.sessionId)}/wrapped-key`, __classPrivateFieldGet(this, _KycService_baseUrl, "f"));
+        const data = await __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_request).call(this, url, {
+            method: 'POST',
+            body: JSON.stringify({
+                wrappedUserKey: params.wrappedUserKey,
+                jwtToken: params.jwtToken,
+                idosSessionId: params.idosSessionId,
+            }),
+        });
+        return __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, WrappedKeyResponseStruct, 'wrapped-key');
+    }
+}
+_KycService_messenger = new WeakMap(), _KycService_fetch = new WeakMap(), _KycService_baseUrl = new WeakMap(), _KycService_policy = new WeakMap(), _KycService_instances = new WeakSet(), _KycService_validateResponse = function _KycService_validateResponse(data, struct, apiName) {
+    try {
+        assert(data, struct);
+        return data;
+    }
+    catch (error) {
+        const detail = error instanceof StructError
+            ? `${error.message} (received: ${JSON.stringify(data)})`
+            : String(error);
+        throw new Error(`Malformed response received from ${apiName} API: ${detail}`);
+    }
+}, _KycService_request = 
+/**
+ * Performs an authenticated JSON request wrapped in the service policy.
+ *
+ * @param url - The request URL.
+ * @param init - The request init (method, body).
+ * @returns The parsed JSON response.
+ */
+async function _KycService_request(url, init) {
+    const bearerToken = await __classPrivateFieldGet(this, _KycService_messenger, "f").call('AuthenticationController:getBearerToken');
+    assert(bearerToken, string());
+    if (!bearerToken) {
+        throw new Error('Unable to obtain an authentication bearer token — is the wallet signed in?');
+    }
+    const response = await __classPrivateFieldGet(this, _KycService_policy, "f").execute(async () => {
+        const localResponse = await __classPrivateFieldGet(this, _KycService_fetch, "f").call(this, url.toString(), {
+            ...init,
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${bearerToken}`,
+            },
+        });
+        if (!localResponse.ok) {
+            throw new HttpError(localResponse.status, `Fetching '${url.toString()}' failed with status '${localResponse.status}'`);
+        }
+        return localResponse;
+    });
+    return response.json();
+};
+//# sourceMappingURL=KycService.mjs.map

package/dist/KycService.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"KycService.mjs","sourceRoot":"","sources":["../src/KycService.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  CreateServicePolicyOptions,\n  ServicePolicy,\n} from '@metamask/controller-utils';\nimport { createServicePolicy, HttpError } from '@metamask/controller-utils';\nimport type { GeolocationControllerGetGeolocationAction } from '@metamask/geolocation-controller';\nimport type { Messenger } from '@metamask/messenger';\nimport type { AuthenticationControllerGetBearerTokenAction } from '@metamask/profile-sync-controller/auth';\nimport type { Infer, Struct } from '@metamask/superstruct';\nimport {\n  array,\n  assert,\n  boolean,\n  string,\n  StructError,\n  type,\n} from '@metamask/superstruct';\n\nimport { alpha2ToAlpha3 } from './countryCodes';\nimport type { KycServiceMethodActions } from './KycService-method-action-types';\nimport type { KycDisclaimer } from './types';\n\n// === GENERAL ===\n\n/**\n * The name of the {@link KycService}, used to namespace the service's actions.\n */\nexport const serviceName = 'KycService';\n\n/**\n * The supported environments for the Universal KYC API.\n */\nexport type KycServiceEnvironment = 'production' | 'development';\n\nconst KYC_API_URLS: Record<KycServiceEnvironment, string> = {\n  production: 'https://kyc-api.cx.metamask.io',\n  development: 'https://kyc-api.dev-api.cx.metamask.io',\n};\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'getGeoCountry',\n  'fetchDisclaimers',\n  'createSession',\n  'checkKycRequired',\n  'createUkycSession',\n  'submitWrappedKey',\n] as const;\n\n/**\n * Actions that {@link KycService} exposes to other consumers.\n */\nexport type KycServiceActions = KycServiceMethodActions;\n\n/**\n * Actions from other messengers that {@link KycService} calls.\n */\ntype AllowedActions =\n  | AuthenticationControllerGetBearerTokenAction\n  | GeolocationControllerGetGeolocationAction;\n\n/**\n * Events that {@link KycService} exposes to other consumers.\n */\nexport type KycServiceEvents = never;\n\n/**\n * Events from other messengers that {@link KycService} subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events accessed by\n * {@link KycService}.\n */\nexport type KycServiceMessenger = Messenger<\n  typeof serviceName,\n  KycServiceActions | AllowedActions,\n  KycServiceEvents | AllowedEvents\n>;\n\n/**\n * Options for constructing a {@link KycService}.\n */\nexport type KycServiceOptions = {\n  messenger: KycServiceMessenger;\n  fetch: typeof fetch;\n  env: KycServiceEnvironment;\n  /**\n   * Overrides the base URL derived from `env`. When provided, this value is\n   * used verbatim as the base URL for all requests, which is useful for\n   * targeting a local or staging KYC API.\n   */\n  baseUrl?: string;\n  policyOptions?: CreateServicePolicyOptions;\n};\n\n// === API RESPONSE SCHEMAS ===\n\nconst DisclaimerStruct = type({\n  id: string(),\n  display_name: string(),\n  url: string(),\n});\nconst DisclaimersResponseStruct = array(DisclaimerStruct);\n\nconst CreateSessionResponseStruct = type({ sessionToken: string() });\n\n// The live KYC API returns the flag under `required`; the service normalizes\n// this to `kycRequired` for consumers (see `checkKycRequired`).\nconst KycRequiredResponseStruct = type({ required: boolean() });\n\nconst UkycSessionResponseStruct = type({\n  sessionId: string(),\n  wrappingPublicKey: string(),\n  idosSessionId: string(),\n});\nexport type UkycSessionResponse = Infer<typeof UkycSessionResponseStruct>;\n\nconst WrappedKeyResponseStruct = type({\n  status: string(),\n  applicantAccessToken: string(),\n});\nexport type WrappedKeyResponse = Infer<typeof WrappedKeyResponseStruct>;\n\n// === PARAM TYPES ===\n\nexport type CreateSessionParams = {\n  email: string;\n  termsAcceptedAt: string;\n  disclaimerIds: string[];\n};\n\nexport type CheckKycRequiredParams = {\n  accessToken: string;\n  country: string;\n  capabilities?: { product: string }[];\n};\n\nexport type CreateUkycSessionParams = {\n  jwtToken: string;\n  vendorMetadata: Record<string, unknown>;\n};\n\nexport type SubmitWrappedKeyParams = {\n  sessionId: string;\n  wrappedUserKey: string;\n  idosSessionId: string;\n  jwtToken: string;\n};\n\n// === SERVICE DEFINITION ===\n\n/**\n * `KycService` communicates with the Universal KYC (UKYC) backend to drive the\n * identity + document-verification flow. It is stateless and platform-agnostic:\n * HTTP is performed through an injected `fetch`, and the auth bearer token and\n * geolocation come from other controllers via the messenger.\n */\nexport class KycService {\n  readonly name: typeof serviceName;\n\n  readonly #messenger: KycServiceMessenger;\n\n  readonly #fetch: typeof fetch;\n\n  readonly #baseUrl: string;\n\n  readonly #policy: ServicePolicy;\n\n  /**\n   * Constructs a new KycService.\n   *\n   * @param options - The constructor options.\n   * @param options.messenger - The messenger suited for this service.\n   * @param options.fetch - A function used to make HTTP requests.\n   * @param options.env - The environment; determines the base URL.\n   * @param options.baseUrl - Overrides the base URL derived from `env`.\n   * @param options.policyOptions - Options for the request service policy.\n   */\n  constructor({\n    messenger,\n    fetch: fetchFunction,\n    env,\n    baseUrl,\n    policyOptions,\n  }: KycServiceOptions) {\n    this.name = serviceName;\n    this.#messenger = messenger;\n    this.#fetch = fetchFunction;\n    this.#baseUrl = baseUrl ?? KYC_API_URLS[env];\n    this.#policy = createServicePolicy(policyOptions ?? {});\n    this.#messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n  }\n\n  /**\n   * Resolves the customer's country from the geolocation source and converts it\n   * to an ISO 3166-1 alpha-3 code.\n   *\n   * @returns The alpha-3 country code.\n   * @throws If the country cannot be determined or mapped.\n   */\n  async getGeoCountry(): Promise<string> {\n    const location = await this.#messenger.call(\n      'GeolocationController:getGeolocation',\n    );\n    // Guard nullish/empty geolocation with the documented domain error rather\n    // than letting `assert(location, string())` surface a superstruct\n    // assertion error (which would change how the failure reads in\n    // `disclaimersError`).\n    const alpha2 =\n      typeof location === 'string' ? location.split('-')[0].toUpperCase() : '';\n    if (!alpha2 || alpha2 === 'UNKNOWN') {\n      throw new Error(\n        `Unable to determine country from geolocation (got \"${String(\n          location,\n        )}\").`,\n      );\n    }\n    const alpha3 = alpha2ToAlpha3(alpha2);\n    if (!alpha3) {\n      throw new Error(\n        `Unable to map country code \"${alpha2}\" to an ISO 3166-1 alpha-3 code.`,\n      );\n    }\n    return alpha3;\n  }\n\n  /**\n   * Fetches the disclaimers the customer must accept before a session is\n   * created.\n   *\n   * @param params - The parameters.\n   * @param params.country - ISO 3166-1 alpha-3 country code.\n   * @returns The disclaimers.\n   */\n  async fetchDisclaimers({\n    country,\n  }: {\n    country: string;\n  }): Promise<KycDisclaimer[]> {\n    const url = new URL('/vendors/moonpay/disclaimers', this.#baseUrl);\n    url.searchParams.set('country', country);\n    const data = await this.#request(url, { method: 'GET' });\n    return this.#validateResponse(\n      data,\n      DisclaimersResponseStruct,\n      'disclaimers',\n    ) as KycDisclaimer[];\n  }\n\n  /**\n   * Creates a vendor session via the UKYC backend.\n   *\n   * @param params - The session parameters.\n   * @returns The created session token.\n   */\n  async createSession(\n    params: CreateSessionParams,\n  ): Promise<Infer<typeof CreateSessionResponseStruct>> {\n    const url = new URL('/vendors/moonpay/sessions', this.#baseUrl);\n    const data = await this.#request(url, {\n      method: 'POST',\n      body: JSON.stringify(params),\n    });\n    return this.#validateResponse(\n      data,\n      CreateSessionResponseStruct,\n      'sessions',\n    );\n  }\n\n  /**\n   * Checks whether KYC is required for the given access token, country, and\n   * capabilities.\n   *\n   * @param params - The check parameters.\n   * @returns Whether KYC is required.\n   */\n  async checkKycRequired(\n    params: CheckKycRequiredParams,\n  ): Promise<{ kycRequired: boolean }> {\n    const url = new URL('/vendors/moonpay/kyc-required', this.#baseUrl);\n    const data = await this.#request(url, {\n      method: 'POST',\n      body: JSON.stringify({\n        accessToken: params.accessToken,\n        country: params.country,\n        capabilities: params.capabilities ?? [{ product: 'ramps' }],\n      }),\n    });\n    const { required } = this.#validateResponse(\n      data,\n      KycRequiredResponseStruct,\n      'kyc-required',\n    );\n    return { kycRequired: required };\n  }\n\n  /**\n   * Creates a UKYC session for the SumSub document-verification sub-flow.\n   *\n   * @param params - The session parameters.\n   * @returns The UKYC session identifiers and wrapped key.\n   */\n  async createUkycSession(\n    params: CreateUkycSessionParams,\n  ): Promise<UkycSessionResponse> {\n    const url = new URL('/sessions', this.#baseUrl);\n    const data = await this.#request(url, {\n      method: 'POST',\n      body: JSON.stringify({\n        vendorId: 'moonpay',\n        vendorUserId: 'mockedId',\n        jwtToken: params.jwtToken,\n        vendorMetadata: params.vendorMetadata,\n      }),\n    });\n    return this.#validateResponse(\n      data,\n      UkycSessionResponseStruct,\n      'UKYC sessions',\n    );\n  }\n\n  /**\n   * Exchanges the wrapped user key for a SumSub applicant access token.\n   *\n   * @param params - The exchange parameters.\n   * @returns The applicant access token and status.\n   */\n  async submitWrappedKey(\n    params: SubmitWrappedKeyParams,\n  ): Promise<WrappedKeyResponse> {\n    const url = new URL(\n      `/sessions/${encodeURIComponent(params.sessionId)}/wrapped-key`,\n      this.#baseUrl,\n    );\n    const data = await this.#request(url, {\n      method: 'POST',\n      body: JSON.stringify({\n        wrappedUserKey: params.wrappedUserKey,\n        jwtToken: params.jwtToken,\n        idosSessionId: params.idosSessionId,\n      }),\n    });\n    return this.#validateResponse(\n      data,\n      WrappedKeyResponseStruct,\n      'wrapped-key',\n    );\n  }\n\n  /**\n   * Validates a parsed API response against a superstruct schema, throwing a\n   * descriptive error when the response does not match.\n   *\n   * Unlike a bare `Struct.is` check, this surfaces exactly which field was\n   * missing or had the wrong type, which is essential for diagnosing shape\n   * mismatches between the client and the live API.\n   *\n   * @param data - The parsed response body.\n   * @param struct - The superstruct schema the body is expected to satisfy.\n   * @param apiName - A human-readable name of the API, used in the error message.\n   * @returns The validated, typed response.\n   * @throws If `data` does not match `struct`.\n   */\n  #validateResponse<Type, Schema>(\n    data: unknown,\n    struct: Struct<Type, Schema>,\n    apiName: string,\n  ): Type {\n    try {\n      assert(data, struct);\n      return data;\n    } catch (error) {\n      const detail =\n        error instanceof StructError\n          ? `${error.message} (received: ${JSON.stringify(data)})`\n          : String(error);\n      throw new Error(\n        `Malformed response received from ${apiName} API: ${detail}`,\n      );\n    }\n  }\n\n  /**\n   * Performs an authenticated JSON request wrapped in the service policy.\n   *\n   * @param url - The request URL.\n   * @param init - The request init (method, body).\n   * @returns The parsed JSON response.\n   */\n  async #request(url: URL, init: RequestInit): Promise<unknown> {\n    const bearerToken = await this.#messenger.call(\n      'AuthenticationController:getBearerToken',\n    );\n    assert(bearerToken, string());\n    if (!bearerToken) {\n      throw new Error(\n        'Unable to obtain an authentication bearer token — is the wallet signed in?',\n      );\n    }\n\n    const response = await this.#policy.execute(async () => {\n      const localResponse = await this.#fetch(url.toString(), {\n        ...init,\n        headers: {\n          'Content-Type': 'application/json',\n          Authorization: `Bearer ${bearerToken}`,\n        },\n      });\n      if (!localResponse.ok) {\n        throw new HttpError(\n          localResponse.status,\n          `Fetching '${url.toString()}' failed with status '${localResponse.status}'`,\n        );\n      }\n      return localResponse;\n    });\n\n    return response.json();\n  }\n}\n"]}