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

package/dist/KycService.cjs

@@ -0,0 +1,417 @@
+"use strict";
+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_fetch, _KycService_baseUrl, _KycService_fractalEncryptionBaseUrl, _KycService_validateResponse, _KycService_requestJson;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KycService = exports.serviceName = void 0;
+const base_data_service_1 = require("@metamask/base-data-service");
+const controller_utils_1 = require("@metamask/controller-utils");
+const superstruct_1 = require("@metamask/superstruct");
+const utils_1 = require("@metamask/utils");
+const countryCodes_js_1 = require("./countryCodes.cjs");
+const constants_js_1 = require("./ukyc/constants.cjs");
+const storageAccessToken_js_1 = require("./ukyc/storageAccessToken.cjs");
+// === GENERAL ===
+/**
+ * The name of the {@link KycService}, used to namespace the service's actions.
+ */
+exports.serviceName = 'KycService';
+// === MESSENGER ===
+const MESSENGER_EXPOSED_METHODS = [
+    'getGeoCountry',
+    'fetchDisclaimers',
+    'createSession',
+    'checkKycRequired',
+    'getWrappingKey',
+    'fetchJwks',
+    'createUkycSession',
+    'createJourney',
+    'getSessionStatus',
+];
+// === API RESPONSE SCHEMAS ===
+const DisclaimerStruct = (0, superstruct_1.type)({
+    id: (0, superstruct_1.string)(),
+    display_name: (0, superstruct_1.string)(),
+    url: (0, superstruct_1.string)(),
+});
+const DisclaimersResponseStruct = (0, superstruct_1.array)(DisclaimerStruct);
+const CreateSessionResponseStruct = (0, superstruct_1.type)({ sessionToken: (0, superstruct_1.string)() });
+// The live KYC API returns the flag under `required`; the service normalizes
+// this to `kycRequired` for consumers (see `checkKycRequired`).
+const KycRequiredResponseStruct = (0, superstruct_1.type)({ required: (0, superstruct_1.boolean)() });
+// The session server's X25519 public key, in JWK-like form, returned by
+// `/wrapping-key`. `x` is the base64url public key used to wrap the user key.
+const SessionServerPublicKeyStruct = (0, superstruct_1.type)({
+    kty: (0, superstruct_1.string)(),
+    crv: (0, superstruct_1.string)(),
+    x: (0, superstruct_1.string)(),
+});
+const WrappingKeyResponseStruct = (0, superstruct_1.type)({
+    id: (0, superstruct_1.string)(),
+    jwtChain: (0, superstruct_1.string)(),
+    sessionServerPublicKey: SessionServerPublicKeyStruct,
+});
+// A single Ed25519 (OKP) JWK. `type` (not `object`) keeps optional/extra JWK
+// fields (`use`, `alg`) from failing validation.
+const JwkStruct = (0, superstruct_1.type)({
+    kty: (0, superstruct_1.string)(),
+    crv: (0, superstruct_1.string)(),
+    x: (0, superstruct_1.string)(),
+    kid: (0, superstruct_1.string)(),
+});
+const JwksResponseStruct = (0, superstruct_1.type)({ keys: (0, superstruct_1.array)(JwkStruct) });
+const UkycSessionResponseStruct = (0, superstruct_1.type)({
+    sessionId: (0, superstruct_1.string)(),
+    // The relay-side KYC decision (e.g. `approved`) and the vendor-side final
+    // status (e.g. `pending`) at session-creation time. Present when the applicant
+    // already has a session in flight; absent for a brand-new session.
+    kycStatus: (0, superstruct_1.optional)((0, superstruct_1.string)()),
+    finalStatus: (0, superstruct_1.optional)((0, superstruct_1.string)()),
+});
+const ApplicantAccessTokenResponseStruct = (0, superstruct_1.type)({
+    status: (0, superstruct_1.string)(),
+    applicantAccessToken: (0, superstruct_1.string)(),
+});
+const SessionStatusResponseStruct = (0, superstruct_1.type)({
+    finalStatus: (0, superstruct_1.string)(),
+    statusMessage: (0, superstruct_1.optional)((0, superstruct_1.string)()),
+    externalUserId: (0, superstruct_1.string)(),
+    kycStatus: (0, superstruct_1.string)(),
+    vendor: (0, superstruct_1.string)(),
+    vendorStatus: (0, superstruct_1.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.
+ *
+ * It extends {@link BaseDataService}, so every request is routed through
+ * `fetchQuery`: it is wrapped in the shared service policy (retries, circuit
+ * breaker) and its result is exposed via the service's `QueryClient`. Read-only
+ * endpoints (`fetchDisclaimers`, `fetchJwks`) are cached with a `staleTime`;
+ * the session-creating and status-polling endpoints opt out of caching
+ * (`staleTime`/`cacheTime` of `0`) so they never serve a stale result.
+ */
+class KycService extends base_data_service_1.BaseDataService {
+    /**
+     * 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.baseUrl - Base URL of the KYC API
+     * @param options.fractalEncryptionBaseUrl - Base URL of the Fractal
+     * encryption service, from which the JWKS used to verify the wrapping-key
+     * `jwtChain` is fetched.
+     * @param options.queryClientConfig - Shared configuration for all queries
+     * exposed by the service.
+     * @param options.policyOptions - Options for the request service policy.
+     */
+    constructor({ messenger, fetch: fetchFunction, baseUrl, fractalEncryptionBaseUrl, queryClientConfig = {}, policyOptions = {}, }) {
+        super({
+            name: exports.serviceName,
+            messenger,
+            queryClientConfig,
+            policyOptions,
+        });
+        _KycService_instances.add(this);
+        _KycService_fetch.set(this, void 0);
+        _KycService_baseUrl.set(this, void 0);
+        _KycService_fractalEncryptionBaseUrl.set(this, void 0);
+        __classPrivateFieldSet(this, _KycService_fetch, fetchFunction, "f");
+        if (!baseUrl) {
+            throw new Error('KycService: baseUrl is required');
+        }
+        __classPrivateFieldSet(this, _KycService_baseUrl, baseUrl, "f");
+        __classPrivateFieldSet(this, _KycService_fractalEncryptionBaseUrl, fractalEncryptionBaseUrl ?? '', "f");
+        this.messenger.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 this.messenger.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 = (0, countryCodes_js_1.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 this.fetchQuery({
+            queryKey: [`${this.name}:fetchDisclaimers`, country],
+            queryFn: async () => __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_requestJson).call(this, url, { method: 'GET' }),
+            staleTime: (0, utils_1.inMilliseconds)(5, utils_1.Duration.Minute),
+        });
+        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 this.fetchQuery({
+            queryKey: [
+                `${this.name}:createSession`,
+                params.email,
+                params.termsAcceptedAt,
+                params.disclaimerIds,
+            ],
+            queryFn: async () => __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_requestJson).call(this, url, {
+                method: 'POST',
+                body: JSON.stringify(params),
+            }),
+            // A session-creating mutation must never serve a stale/cached result.
+            staleTime: 0,
+            cacheTime: 0,
+        });
+        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 capabilities = params.capabilities ?? [{ product: 'ramps' }];
+        const data = await this.fetchQuery({
+            queryKey: [
+                `${this.name}:checkKycRequired`,
+                params.accessToken,
+                params.country,
+                capabilities,
+            ],
+            queryFn: async () => __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_requestJson).call(this, url, {
+                method: 'POST',
+                body: JSON.stringify({
+                    accessToken: params.accessToken,
+                    country: params.country,
+                    capabilities,
+                }),
+            }),
+            // The requirement can change server-side, so always re-check.
+            staleTime: 0,
+            cacheTime: 0,
+        });
+        const { required } = __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, KycRequiredResponseStruct, 'kyc-required');
+        return { kycRequired: required };
+    }
+    /**
+     * Requests a per-session wrapping key from the UKYC backend.
+     *
+     * The client sends its ephemeral X25519 public key; the backend responds with
+     * its session public key (`sessionServerPublicKey`) and a `jwtChain` that
+     * attests it. The caller must verify `jwtChain` against the Fractal JWKS
+     * (see {@link KycService.fetchJwks}) before trusting the key to wrap the
+     * `data_encryption_key`.
+     *
+     * @param params - The parameters.
+     * @param params.sessionClientPublicKey - Our ephemeral X25519 public key
+     * (base64url).
+     * @returns The wrapping key id, `jwtChain`, and session server public key.
+     */
+    async getWrappingKey(params) {
+        const url = new URL('/wrapping-key', __classPrivateFieldGet(this, _KycService_baseUrl, "f"));
+        const data = await this.fetchQuery({
+            queryKey: [`${this.name}:getWrappingKey`, params.sessionClientPublicKey],
+            queryFn: async () => __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_requestJson).call(this, url, {
+                method: 'POST',
+                body: JSON.stringify({
+                    sessionClientPublicKey: params.sessionClientPublicKey,
+                }),
+            }),
+            // A per-session key exchange must always run fresh.
+            staleTime: 0,
+            cacheTime: 0,
+        });
+        return __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, WrappingKeyResponseStruct, 'wrapping-key');
+    }
+    /**
+     * Fetches the Fractal encryption service JWKS used to verify the `jwtChain`
+     * returned by {@link KycService.getWrappingKey}.
+     *
+     * This is an unauthenticated request to a well-known path on the Fractal
+     * host, distinct from the UKYC base URL.
+     *
+     * @returns The JWKS keys.
+     */
+    async fetchJwks() {
+        if (!__classPrivateFieldGet(this, _KycService_fractalEncryptionBaseUrl, "f")) {
+            throw new Error('KycService: fractalEncryptionBaseUrl is not configured; cannot fetch JWKS to verify the wrapping key.');
+        }
+        const url = new URL(constants_js_1.UKYC_JWKS_PATH, __classPrivateFieldGet(this, _KycService_fractalEncryptionBaseUrl, "f"));
+        const data = await this.fetchQuery({
+            queryKey: [`${this.name}:fetchJwks`, __classPrivateFieldGet(this, _KycService_fractalEncryptionBaseUrl, "f")],
+            queryFn: async () => __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_requestJson).call(this, url, { method: 'GET' }, { authenticated: false }),
+            staleTime: (0, utils_1.inMilliseconds)(1, utils_1.Duration.Hour),
+        });
+        return __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, JwksResponseStruct, 'JWKS');
+    }
+    /**
+     * Creates a UKYC session for the SumSub document-verification sub-flow,
+     * handing over the wrapped `data_encryption_key` and the client-signed,
+     * read-only `ukyc_capability_token` that authorizes later storage access for
+     * the session.
+     *
+     * @param params - The session parameters.
+     * @returns The UKYC session identifiers.
+     */
+    async createUkycSession(params) {
+        const url = new URL('/sessions', __classPrivateFieldGet(this, _KycService_baseUrl, "f"));
+        const data = await this.fetchQuery({
+            queryKey: [
+                `${this.name}:createUkycSession`,
+                params.wrappedEncryptionKey.sessionId,
+            ],
+            queryFn: async () => __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_requestJson).call(this, url, {
+                method: 'POST',
+                body: JSON.stringify({
+                    vendorId: 'moonpay',
+                    vendorUserId: 'mockedId',
+                    jwtToken: params.jwtToken,
+                    vendorMetadata: params.vendorMetadata,
+                    wrappedEncryptionKey: params.wrappedEncryptionKey,
+                    ukycCapabilityToken: (0, storageAccessToken_js_1.encodeStorageAccessTokenForHeader)(params.ukycCapabilityToken),
+                }),
+            }),
+            // A session-creating mutation must never serve a stale/cached result.
+            staleTime: 0,
+            cacheTime: 0,
+        });
+        return __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, UkycSessionResponseStruct, 'UKYC sessions');
+    }
+    /**
+     * Creates (or refreshes) the SumSub verification journey for a UKYC session,
+     * returning the applicant access token used to launch the SDK.
+     *
+     * @param sessionId - The UKYC session id from `createUkycSession`.
+     * @returns The applicant access token and status.
+     */
+    async createJourney(sessionId) {
+        const url = new URL(`/sessions/${encodeURIComponent(sessionId)}/journey`, __classPrivateFieldGet(this, _KycService_baseUrl, "f"));
+        const data = await this.fetchQuery({
+            queryKey: [`${this.name}:createJourney`, sessionId],
+            queryFn: async () => __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_requestJson).call(this, url, { method: 'POST' }),
+            // Journeys are (re)created on demand; do not reuse a cached token.
+            staleTime: 0,
+            cacheTime: 0,
+        });
+        return __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, ApplicantAccessTokenResponseStruct, 'journey');
+    }
+    /**
+     * Fetches the current status of a UKYC session. Polled after the SumSub SDK
+     * completes to determine the final verification decision.
+     *
+     * @param params - The parameters.
+     * @param params.sessionId - The UKYC session id.
+     * @returns The session status.
+     */
+    async getSessionStatus(params) {
+        const url = new URL(`/sessions/${encodeURIComponent(params.sessionId)}/status`, __classPrivateFieldGet(this, _KycService_baseUrl, "f"));
+        const data = await this.fetchQuery({
+            queryKey: [`${this.name}:getSessionStatus`, params.sessionId],
+            queryFn: async () => __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_requestJson).call(this, url, { method: 'GET' }),
+            // Status is polled for a terminal decision, so it must always be fresh.
+            staleTime: 0,
+            cacheTime: 0,
+        });
+        return __classPrivateFieldGet(this, _KycService_instances, "m", _KycService_validateResponse).call(this, data, SessionStatusResponseStruct, 'session status');
+    }
+}
+exports.KycService = KycService;
+_KycService_fetch = new WeakMap(), _KycService_baseUrl = new WeakMap(), _KycService_fractalEncryptionBaseUrl = new WeakMap(), _KycService_instances = new WeakSet(), _KycService_validateResponse = function _KycService_validateResponse(data, struct, apiName) {
+    try {
+        (0, superstruct_1.assert)(data, struct);
+        return data;
+    }
+    catch (error) {
+        const detail = error instanceof superstruct_1.StructError
+            ? `${error.message} (received: ${JSON.stringify(data)})`
+            : // `assert` only ever throws `StructError` for the plain structs used
+                // here, so this is a defensive fallback that is not exercised.
+                /* istanbul ignore next */
+                String(error);
+        throw new Error(`Malformed response received from ${apiName} API: ${detail}`);
+    }
+}, _KycService_requestJson = 
+/**
+ * Performs a single JSON request.
+ *
+ * This is meant to be used as the `queryFn` for {@link fetchQuery}, which
+ * wraps it in the shared service policy (retries, circuit breaker). Requests
+ * are authenticated with the wallet bearer token by default; pass
+ * `{ authenticated: false }` for calls to services that do not expect it
+ * (e.g. the Fractal JWKS endpoint).
+ *
+ * @param url - The request URL.
+ * @param init - The request init (method, body).
+ * @param options - Request options.
+ * @param options.authenticated - Whether to attach the bearer token. Defaults
+ * to `true`.
+ * @returns The parsed JSON response.
+ */
+async function _KycService_requestJson(url, init, options = {}) {
+    const { authenticated = true } = options;
+    const headers = {};
+    // Only advertise a JSON body when one is actually sent; bodyless requests
+    // (e.g. `createJourney`) must not carry a `Content-Type`.
+    if (init.body !== undefined && init.body !== null) {
+        headers['Content-Type'] = 'application/json';
+    }
+    if (authenticated) {
+        const bearerToken = await this.messenger.call('AuthenticationController:getBearerToken');
+        (0, superstruct_1.assert)(bearerToken, (0, superstruct_1.string)());
+        if (!bearerToken) {
+            throw new Error('Unable to obtain an authentication bearer token — is the wallet signed in?');
+        }
+        headers.Authorization = `Bearer ${bearerToken}`;
+    }
+    const response = await __classPrivateFieldGet(this, _KycService_fetch, "f").call(this, url.toString(), {
+        ...init,
+        headers,
+    });
+    if (!response.ok) {
+        throw new controller_utils_1.HttpError(response.status, `Fetching '${url.toString()}' failed with status '${response.status}'`);
+    }
+    return (await response.json());
+};
+//# sourceMappingURL=KycService.cjs.map

package/dist/KycService.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"KycService.cjs","sourceRoot":"","sources":["../src/KycService.ts"],"names":[],"mappings":"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","sourcesContent":["import { BaseDataService } from '@metamask/base-data-service';\nimport type {\n  DataServiceCacheUpdatedEvent,\n  DataServiceGranularCacheUpdatedEvent,\n  DataServiceInvalidateQueriesAction,\n} from '@metamask/base-data-service';\nimport type { CreateServicePolicyOptions } from '@metamask/controller-utils';\nimport { 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  optional,\n  string,\n  StructError,\n  type,\n} from '@metamask/superstruct';\nimport type { Json } from '@metamask/utils';\nimport { Duration, inMilliseconds } from '@metamask/utils';\nimport type { QueryClientConfig } from '@tanstack/query-core';\n\nimport { alpha2ToAlpha3 } from './countryCodes.js';\nimport type { KycServiceMethodActions } from './KycService-method-action-types.js';\nimport type { KycDisclaimer, KycSessionStatus } from './types.js';\nimport { UKYC_JWKS_PATH } from './ukyc/constants.js';\nimport { encodeStorageAccessTokenForHeader } from './ukyc/storageAccessToken.js';\nimport type { UkycStorageAccessToken } from './ukyc/storageAccessToken.js';\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// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'getGeoCountry',\n  'fetchDisclaimers',\n  'createSession',\n  'checkKycRequired',\n  'getWrappingKey',\n  'fetchJwks',\n  'createUkycSession',\n  'createJourney',\n  'getSessionStatus',\n] as const;\n\n/**\n * Invalidates cached queries serviced by {@link KycService}.\n */\nexport type KycServiceInvalidateQueriesAction =\n  DataServiceInvalidateQueriesAction<typeof serviceName>;\n\n/**\n * Actions that {@link KycService} exposes to other consumers.\n */\nexport type KycServiceActions =\n  | KycServiceMethodActions\n  | KycServiceInvalidateQueriesAction;\n\n/**\n * Actions from other messengers that {@link KycService} calls.\n */\ntype AllowedActions =\n  | AuthenticationControllerGetBearerTokenAction\n  | GeolocationControllerGetGeolocationAction;\n\n/**\n * Published when {@link KycService}'s cache is updated.\n */\nexport type KycServiceCacheUpdatedEvent =\n  DataServiceCacheUpdatedEvent<typeof serviceName>;\n\n/**\n * Published when a single key within {@link KycService}'s cache is updated.\n */\nexport type KycServiceGranularCacheUpdatedEvent =\n  DataServiceGranularCacheUpdatedEvent<typeof serviceName>;\n\n/**\n * Events that {@link KycService} exposes to other consumers.\n */\nexport type KycServiceEvents =\n  | KycServiceCacheUpdatedEvent\n  | KycServiceGranularCacheUpdatedEvent;\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  /**\n   * Mandatory value that sets the base url to KYC api\n   */\n  baseUrl: string;\n  /**\n   * Base URL of the Fractal encryption service, from which the JWKS used to\n   * verify the `jwtChain` returned by {@link KycService.getWrappingKey} is\n   * fetched. Required to run the wrapping-key exchange in\n   * {@link KycService.fetchJwks}.\n   */\n  fractalEncryptionBaseUrl?: string;\n  /**\n   * Shared configuration applied to all queries exposed by the service (e.g. a\n   * default `staleTime`/`cacheTime`). Each data service gets its own\n   * `QueryClient`.\n   */\n  queryClientConfig?: QueryClientConfig;\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\n// The session server's X25519 public key, in JWK-like form, returned by\n// `/wrapping-key`. `x` is the base64url public key used to wrap the user key.\nconst SessionServerPublicKeyStruct = type({\n  kty: string(),\n  crv: string(),\n  x: string(),\n});\n\nconst WrappingKeyResponseStruct = type({\n  id: string(),\n  jwtChain: string(),\n  sessionServerPublicKey: SessionServerPublicKeyStruct,\n});\nexport type WrappingKeyResponse = Infer<typeof WrappingKeyResponseStruct>;\n\n// A single Ed25519 (OKP) JWK. `type` (not `object`) keeps optional/extra JWK\n// fields (`use`, `alg`) from failing validation.\nconst JwkStruct = type({\n  kty: string(),\n  crv: string(),\n  x: string(),\n  kid: string(),\n});\nconst JwksResponseStruct = type({ keys: array(JwkStruct) });\nexport type JwksResponse = Infer<typeof JwksResponseStruct>;\n\nconst UkycSessionResponseStruct = type({\n  sessionId: string(),\n  // The relay-side KYC decision (e.g. `approved`) and the vendor-side final\n  // status (e.g. `pending`) at session-creation time. Present when the applicant\n  // already has a session in flight; absent for a brand-new session.\n  kycStatus: optional(string()),\n  finalStatus: optional(string()),\n});\nexport type UkycSessionResponse = Infer<typeof UkycSessionResponseStruct>;\n\nconst ApplicantAccessTokenResponseStruct = type({\n  status: string(),\n  applicantAccessToken: string(),\n});\nexport type ApplicantAccessTokenResponse = Infer<\n  typeof ApplicantAccessTokenResponseStruct\n>;\n\nconst SessionStatusResponseStruct = type({\n  finalStatus: string(),\n  statusMessage: optional(string()),\n  externalUserId: string(),\n  kycStatus: string(),\n  vendor: string(),\n  vendorStatus: string(),\n});\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 GetWrappingKeyParams = {\n  sessionClientPublicKey: string;\n};\n\n/**\n * The wrapped `data_encryption_key` sent to the UKYC backend when creating a\n * session. `encryptedKey` and `nonce` are produced by `wrapEncryptionKey`;\n * `sessionId` is the wrapping key id returned by `getWrappingKey`.\n */\nexport type WrappedEncryptionKey = {\n  sessionId: string;\n  encryptedKey: string;\n  nonce: string;\n};\n\nexport type CreateUkycSessionParams = {\n  jwtToken: string;\n  vendorMetadata: Record<string, unknown>;\n  wrappedEncryptionKey: WrappedEncryptionKey;\n  /**\n   * The client-signed `ukyc_capability_token` (envelope: payload + Ed25519\n   * signature) authorizing later storage access for this session. It is minted\n   * by the client with `read`-only scope — see the UKYC storage-and-auth spec\n   * for how it is formed. Only the client holds the signing key, so only the\n   * client can mint it. The envelope is base64url-encoded into a compact string\n   * before it is sent to the backend.\n   */\n  ukycCapabilityToken: UkycStorageAccessToken;\n};\n\nexport type GetSessionStatusParams = {\n  sessionId: 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 *\n * It extends {@link BaseDataService}, so every request is routed through\n * `fetchQuery`: it is wrapped in the shared service policy (retries, circuit\n * breaker) and its result is exposed via the service's `QueryClient`. Read-only\n * endpoints (`fetchDisclaimers`, `fetchJwks`) are cached with a `staleTime`;\n * the session-creating and status-polling endpoints opt out of caching\n * (`staleTime`/`cacheTime` of `0`) so they never serve a stale result.\n */\nexport class KycService extends BaseDataService<\n  typeof serviceName,\n  KycServiceMessenger\n> {\n  readonly #fetch: typeof fetch;\n\n  readonly #baseUrl: string;\n\n  readonly #fractalEncryptionBaseUrl: string;\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.baseUrl - Base URL of the KYC API\n   * @param options.fractalEncryptionBaseUrl - Base URL of the Fractal\n   * encryption service, from which the JWKS used to verify the wrapping-key\n   * `jwtChain` is fetched.\n   * @param options.queryClientConfig - Shared configuration for all queries\n   * exposed by the service.\n   * @param options.policyOptions - Options for the request service policy.\n   */\n  constructor({\n    messenger,\n    fetch: fetchFunction,\n    baseUrl,\n    fractalEncryptionBaseUrl,\n    queryClientConfig = {},\n    policyOptions = {},\n  }: KycServiceOptions) {\n    super({\n      name: serviceName,\n      messenger,\n      queryClientConfig,\n      policyOptions,\n    });\n    this.#fetch = fetchFunction;\n    if (!baseUrl) {\n      throw new Error('KycService: baseUrl is required');\n    }\n    this.#baseUrl = baseUrl;\n    this.#fractalEncryptionBaseUrl = fractalEncryptionBaseUrl ?? '';\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.fetchQuery({\n      queryKey: [`${this.name}:fetchDisclaimers`, country],\n      queryFn: async () => this.#requestJson(url, { method: 'GET' }),\n      staleTime: inMilliseconds(5, Duration.Minute),\n    });\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.fetchQuery({\n      queryKey: [\n        `${this.name}:createSession`,\n        params.email,\n        params.termsAcceptedAt,\n        params.disclaimerIds,\n      ],\n      queryFn: async () =>\n        this.#requestJson(url, {\n          method: 'POST',\n          body: JSON.stringify(params),\n        }),\n      // A session-creating mutation must never serve a stale/cached result.\n      staleTime: 0,\n      cacheTime: 0,\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 capabilities = params.capabilities ?? [{ product: 'ramps' }];\n    const data = await this.fetchQuery({\n      queryKey: [\n        `${this.name}:checkKycRequired`,\n        params.accessToken,\n        params.country,\n        capabilities,\n      ],\n      queryFn: async () =>\n        this.#requestJson(url, {\n          method: 'POST',\n          body: JSON.stringify({\n            accessToken: params.accessToken,\n            country: params.country,\n            capabilities,\n          }),\n        }),\n      // The requirement can change server-side, so always re-check.\n      staleTime: 0,\n      cacheTime: 0,\n    });\n    const { required } = this.#validateResponse(\n      data,\n      KycRequiredResponseStruct,\n      'kyc-required',\n    );\n    return { kycRequired: required };\n  }\n\n  /**\n   * Requests a per-session wrapping key from the UKYC backend.\n   *\n   * The client sends its ephemeral X25519 public key; the backend responds with\n   * its session public key (`sessionServerPublicKey`) and a `jwtChain` that\n   * attests it. The caller must verify `jwtChain` against the Fractal JWKS\n   * (see {@link KycService.fetchJwks}) before trusting the key to wrap the\n   * `data_encryption_key`.\n   *\n   * @param params - The parameters.\n   * @param params.sessionClientPublicKey - Our ephemeral X25519 public key\n   * (base64url).\n   * @returns The wrapping key id, `jwtChain`, and session server public key.\n   */\n  async getWrappingKey(\n    params: GetWrappingKeyParams,\n  ): Promise<WrappingKeyResponse> {\n    const url = new URL('/wrapping-key', this.#baseUrl);\n    const data = await this.fetchQuery({\n      queryKey: [`${this.name}:getWrappingKey`, params.sessionClientPublicKey],\n      queryFn: async () =>\n        this.#requestJson(url, {\n          method: 'POST',\n          body: JSON.stringify({\n            sessionClientPublicKey: params.sessionClientPublicKey,\n          }),\n        }),\n      // A per-session key exchange must always run fresh.\n      staleTime: 0,\n      cacheTime: 0,\n    });\n    return this.#validateResponse(\n      data,\n      WrappingKeyResponseStruct,\n      'wrapping-key',\n    );\n  }\n\n  /**\n   * Fetches the Fractal encryption service JWKS used to verify the `jwtChain`\n   * returned by {@link KycService.getWrappingKey}.\n   *\n   * This is an unauthenticated request to a well-known path on the Fractal\n   * host, distinct from the UKYC base URL.\n   *\n   * @returns The JWKS keys.\n   */\n  async fetchJwks(): Promise<JwksResponse> {\n    if (!this.#fractalEncryptionBaseUrl) {\n      throw new Error(\n        'KycService: fractalEncryptionBaseUrl is not configured; cannot fetch JWKS to verify the wrapping key.',\n      );\n    }\n    const url = new URL(UKYC_JWKS_PATH, this.#fractalEncryptionBaseUrl);\n    const data = await this.fetchQuery({\n      queryKey: [`${this.name}:fetchJwks`, this.#fractalEncryptionBaseUrl],\n      queryFn: async () =>\n        this.#requestJson(url, { method: 'GET' }, { authenticated: false }),\n      staleTime: inMilliseconds(1, Duration.Hour),\n    });\n    return this.#validateResponse(data, JwksResponseStruct, 'JWKS');\n  }\n\n  /**\n   * Creates a UKYC session for the SumSub document-verification sub-flow,\n   * handing over the wrapped `data_encryption_key` and the client-signed,\n   * read-only `ukyc_capability_token` that authorizes later storage access for\n   * the session.\n   *\n   * @param params - The session parameters.\n   * @returns The UKYC session identifiers.\n   */\n  async createUkycSession(\n    params: CreateUkycSessionParams,\n  ): Promise<UkycSessionResponse> {\n    const url = new URL('/sessions', this.#baseUrl);\n    const data = await this.fetchQuery({\n      queryKey: [\n        `${this.name}:createUkycSession`,\n        params.wrappedEncryptionKey.sessionId,\n      ],\n      queryFn: async () =>\n        this.#requestJson(url, {\n          method: 'POST',\n          body: JSON.stringify({\n            vendorId: 'moonpay',\n            vendorUserId: 'mockedId',\n            jwtToken: params.jwtToken,\n            vendorMetadata: params.vendorMetadata,\n            wrappedEncryptionKey: params.wrappedEncryptionKey,\n            ukycCapabilityToken: encodeStorageAccessTokenForHeader(\n              params.ukycCapabilityToken,\n            ),\n          }),\n        }),\n      // A session-creating mutation must never serve a stale/cached result.\n      staleTime: 0,\n      cacheTime: 0,\n    });\n    return this.#validateResponse(\n      data,\n      UkycSessionResponseStruct,\n      'UKYC sessions',\n    );\n  }\n\n  /**\n   * Creates (or refreshes) the SumSub verification journey for a UKYC session,\n   * returning the applicant access token used to launch the SDK.\n   *\n   * @param sessionId - The UKYC session id from `createUkycSession`.\n   * @returns The applicant access token and status.\n   */\n  async createJourney(\n    sessionId: string,\n  ): Promise<ApplicantAccessTokenResponse> {\n    const url = new URL(\n      `/sessions/${encodeURIComponent(sessionId)}/journey`,\n      this.#baseUrl,\n    );\n    const data = await this.fetchQuery({\n      queryKey: [`${this.name}:createJourney`, sessionId],\n      queryFn: async () => this.#requestJson(url, { method: 'POST' }),\n      // Journeys are (re)created on demand; do not reuse a cached token.\n      staleTime: 0,\n      cacheTime: 0,\n    });\n    return this.#validateResponse(\n      data,\n      ApplicantAccessTokenResponseStruct,\n      'journey',\n    );\n  }\n\n  /**\n   * Fetches the current status of a UKYC session. Polled after the SumSub SDK\n   * completes to determine the final verification decision.\n   *\n   * @param params - The parameters.\n   * @param params.sessionId - The UKYC session id.\n   * @returns The session status.\n   */\n  async getSessionStatus(\n    params: GetSessionStatusParams,\n  ): Promise<KycSessionStatus> {\n    const url = new URL(\n      `/sessions/${encodeURIComponent(params.sessionId)}/status`,\n      this.#baseUrl,\n    );\n    const data = await this.fetchQuery({\n      queryKey: [`${this.name}:getSessionStatus`, params.sessionId],\n      queryFn: async () => this.#requestJson(url, { method: 'GET' }),\n      // Status is polled for a terminal decision, so it must always be fresh.\n      staleTime: 0,\n      cacheTime: 0,\n    });\n    return this.#validateResponse(\n      data,\n      SessionStatusResponseStruct,\n      'session status',\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          : // `assert` only ever throws `StructError` for the plain structs used\n            // here, so this is a defensive fallback that is not exercised.\n            /* istanbul ignore next */\n            String(error);\n      throw new Error(\n        `Malformed response received from ${apiName} API: ${detail}`,\n      );\n    }\n  }\n\n  /**\n   * Performs a single JSON request.\n   *\n   * This is meant to be used as the `queryFn` for {@link fetchQuery}, which\n   * wraps it in the shared service policy (retries, circuit breaker). Requests\n   * are authenticated with the wallet bearer token by default; pass\n   * `{ authenticated: false }` for calls to services that do not expect it\n   * (e.g. the Fractal JWKS endpoint).\n   *\n   * @param url - The request URL.\n   * @param init - The request init (method, body).\n   * @param options - Request options.\n   * @param options.authenticated - Whether to attach the bearer token. Defaults\n   * to `true`.\n   * @returns The parsed JSON response.\n   */\n  async #requestJson(\n    url: URL,\n    init: RequestInit,\n    options: { authenticated?: boolean } = {},\n  ): Promise<Json> {\n    const { authenticated = true } = options;\n\n    const headers: Record<string, string> = {};\n\n    // Only advertise a JSON body when one is actually sent; bodyless requests\n    // (e.g. `createJourney`) must not carry a `Content-Type`.\n    if (init.body !== undefined && init.body !== null) {\n      headers['Content-Type'] = 'application/json';\n    }\n\n    if (authenticated) {\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      headers.Authorization = `Bearer ${bearerToken}`;\n    }\n\n    const response = await this.#fetch(url.toString(), {\n      ...init,\n      headers,\n    });\n    if (!response.ok) {\n      throw new HttpError(\n        response.status,\n        `Fetching '${url.toString()}' failed with status '${response.status}'`,\n      );\n    }\n\n    return (await response.json()) as Json;\n  }\n}\n"]}