@metamask-previews/kyc-controller 0.13.0-preview-979919367 → 0.13.0-preview-a26804c

package/CHANGELOG.md

@@ -9,12 +9,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add optional `currentStep` to `KycSessionStatus`. Known values are `processing`, `emailOtpCollection`, `phoneOtpCollection`, `capabilityAuthorization`, `kyc`, `approved`, and `rejected` ([#11094](https://github.com/MetaMask/core/pull/11094))
+  - `KycService.getSessionStatus`, `KycService.getSessionStatusForVendor`, and `KycService.setAuthorizations` read `currentStep` from the kyc-api session response
+  - A missing `currentStep` is left unset. Any other value, including one this package does not know, is returned as sent. Sessions saved before this field existed keep working until the next status fetch
+  - Export `KYC_CURRENT_STEPS` and `KycCurrentStep`
+- Add `KycController.ensureLocalUserSecret` and the `KycController:ensureLocalUserSecret` messenger action, which create and store the UKYC `local_user_secret` when one does not already exist ([#11099](https://github.com/MetaMask/core/pull/11099))
+  - Call it after the user has expressed intent to onboard and before `startSession`, so secret generation and the Encrypted User Storage write happen before session creation
+  - `startSession` still creates the secret when this method has not been called
+  - The secret is not returned
 - Add `KycService.getDataShares` and `KycController.getDataShares`, which list the vendors the customer's verified identity data has been shared with, newest first ([#11158](https://github.com/MetaMask/core/pull/11158))
   - `KycService.getDataShares({ externalUserId })` reads `GET /api/kyc/external-user-id/{externalUserId}/shares` on the idOS relay and returns the unwrapped `shares` array. It requires `idosRelayBaseUrl` to be configured
   - `KycController.getDataShares()` takes the external user id from the session status on state, falling back to the latest session for the vendor on state (which it does not write to state), and returns an empty array when no session can be resolved. It stores nothing
   - Both methods are exposed as the `KycService:getDataShares` and `KycController:getDataShares` messenger actions
 - Export the `KycDataShare` and `GetDataSharesParams` types and the `KycServiceGetDataSharesAction` and `KycControllerGetDataSharesAction` action types ([#11158](https://github.com/MetaMask/core/pull/11158))
 
+### Changed
+
+- When a kyc-api session reports `finalStatus` `pending` and `currentStep` `kyc`, the session returned by those endpoints uses `finalStatus` `new`. Every other `finalStatus` is returned unchanged. This resolves a regression where `finalStatus: pending` originally was only possible after sumsub was fully submitted, but now it is possible when partially submitted. ([#11094](https://github.com/MetaMask/core/pull/11094))
+  - After the SumSub SDK completes, the stored session is `finalStatus` `pending` with `currentStep` `processing`
+
 ## [0.13.0]
 
 ### Added

package/dist/KycController-method-action-types.d.ts

@@ -3,6 +3,29 @@
  * Do not edit manually.
  */
 import type { KycController } from './KycController.js';
+/**
+ * Creates the UKYC `local_user_secret` and stores it in Encrypted User
+ * Storage when one does not already exist.
+ *
+ * Call this after the user has expressed intent to onboard and before
+ * {@link startSession}. Persisting the secret here moves generation and the
+ * storage write off the `startSession` path. `startSession` still reads the
+ * secret, and still creates it when this has not been called.
+ *
+ * Await this call, or attach a rejection handler. A failure does not block
+ * onboarding: {@link startSession} creates the secret if it is still missing.
+ *
+ * The operation is idempotent and uses the same primary entropy source as
+ * session creation. The plaintext secret is not returned and is not sent to
+ * idOS. Only the encrypted User Storage copy is synced.
+ *
+ * @throws When Encrypted User Storage cannot be read or written, or when a
+ * stored secret has an unexpected length.
+ */
+export type KycControllerEnsureLocalUserSecretAction = {
+    type: `KycController:ensureLocalUserSecret`;
+    handler: KycController['ensureLocalUserSecret'];
+};
 /**
  * Starts a KYC session for the given vendor. Reuses a latest vendor session
  * when one exists; otherwise creates a UKYC session.
@@ -12,6 +35,11 @@ import type { KycController } from './KycController.js';
  * kept for an existing session. Creating a vendor customer and UKYC session
  * requires the token, which both requests send as `partnerIdentityToken`.
  *
+ * Session creation derives client material from the UKYC
+ * `local_user_secret`. Call {@link ensureLocalUserSecret} after the user
+ * has expressed intent to onboard so that secret is generated and stored
+ * before this method runs.
+ *
  * @param params - The session parameters.
  * @param params.vendor - Identity vendor for the session.
  * @param params.aal2Token - AAL2 authentication token. Required only when a
@@ -225,5 +253,5 @@ export type KycControllerLaunchProviderFlowAction = {
 /**
  * Union of all KycController action types.
  */
-export type KycControllerMethodActions = KycControllerStartSessionAction | KycControllerResetAction | KycControllerClearStateAction | KycControllerGetSessionStatusForVendorAction | KycControllerGetDataSharesAction | KycControllerGetProviderFlowStatusAction | KycControllerRefreshSessionStatusAction | KycControllerReadSessionStatusAction | KycControllerFetchSessionStatusOnceAction | KycControllerStartSessionStatusPollingAction | KycControllerFetchSessionDisclaimersAction | KycControllerRecordSessionDisclaimersAction | KycControllerHasCompletedSessionDisclaimersAction | KycControllerFetchVendorDisclaimersAction | KycControllerRecordVendorDisclaimersAction | KycControllerHasCompletedVendorDisclaimersAction | KycControllerLaunchProviderFlowAction;
+export type KycControllerMethodActions = KycControllerEnsureLocalUserSecretAction | KycControllerStartSessionAction | KycControllerResetAction | KycControllerClearStateAction | KycControllerGetSessionStatusForVendorAction | KycControllerGetDataSharesAction | KycControllerGetProviderFlowStatusAction | KycControllerRefreshSessionStatusAction | KycControllerReadSessionStatusAction | KycControllerFetchSessionStatusOnceAction | KycControllerStartSessionStatusPollingAction | KycControllerFetchSessionDisclaimersAction | KycControllerRecordSessionDisclaimersAction | KycControllerHasCompletedSessionDisclaimersAction | KycControllerFetchVendorDisclaimersAction | KycControllerRecordVendorDisclaimersAction | KycControllerHasCompletedVendorDisclaimersAction | KycControllerLaunchProviderFlowAction;
 //# sourceMappingURL=KycController-method-action-types.d.ts.map

package/dist/KycController-method-action-types.d.ts.map

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

package/dist/KycController-method-action-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"KycController-method-action-types.js","sourceRoot":"","sources":["../src/KycController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { KycController } from './KycController.js';\n\n/**\n * Starts a KYC session for the given vendor. Reuses a latest vendor session\n * when one exists; otherwise creates a UKYC session.\n *\n * The verified email stored on controller state comes from the partner\n * identity token. When that request returns HTTP 422, a stored email is\n * kept for an existing session. Creating a vendor customer and UKYC session\n * requires the token, which both requests send as `partnerIdentityToken`.\n *\n * @param params - The session parameters.\n * @param params.vendor - Identity vendor for the session.\n * @param params.aal2Token - AAL2 authentication token. Required only when a\n * UKYC session must be created, where it is sent as the Authorization bearer\n * value. Omit it when reusing an existing session.\n * @returns The current or newly created session status.\n */\nexport type KycControllerStartSessionAction = {\n  type: `KycController:startSession`;\n  handler: KycController['startSession'];\n};\n\n/**\n * Stops session-status polling and restores default controller state.\n */\nexport type KycControllerResetAction = {\n  type: `KycController:reset`;\n  handler: KycController['reset'];\n};\n\n/**\n * Restores the controller to its default state.\n */\nexport type KycControllerClearStateAction = {\n  type: `KycController:clearState`;\n  handler: KycController['clearState'];\n};\n\n/**\n * Fetches the latest UKYC session status for a vendor.\n *\n * @param vendor - Identity vendor whose latest session should be queried.\n * @returns The session status, or `null` when none exists.\n */\nexport type KycControllerGetSessionStatusForVendorAction = {\n  type: `KycController:getSessionStatusForVendor`;\n  handler: KycController['getSessionStatusForVendor'];\n};\n\n/**\n * Fetches the vendors this customer's verified identity data has been shared\n * with, newest first.\n *\n * The external user id comes from the session status on state. When no\n * session has been stored yet, the latest session for the vendor on state is\n * fetched first (without writing it to state). An unresolvable session — no\n * vendor on state, or no latest session for it — yields an empty list rather\n * than an error, so consumers can render an empty \"shared with\" list.\n *\n * @returns The data shares, newest first; empty when no session can be\n * resolved.\n */\nexport type KycControllerGetDataSharesAction = {\n  type: `KycController:getDataShares`;\n  handler: KycController['getDataShares'];\n};\n\n/**\n * Returns the durable outcome of the identity-provider flow.\n *\n * @returns The latest provider-flow status.\n */\nexport type KycControllerGetProviderFlowStatusAction = {\n  type: `KycController:getProviderFlowStatus`;\n  handler: KycController['getProviderFlowStatus'];\n};\n\n/**\n * Returns the session already stored on state.\n *\n * Starts session-status polling when `finalStatus` is not `approved`,\n * `rejected`, or `retry`. Does not fetch status or refresh capability\n * authorization.\n *\n * @returns The session status stored at call time.\n * @throws If there is no session on state.\n */\nexport type KycControllerRefreshSessionStatusAction = {\n  type: `KycController:refreshSessionStatus`;\n  handler: KycController['refreshSessionStatus'];\n};\n\n/**\n * Returns the persisted session status.\n *\n * Does not call the network and does not start session-status polling.\n *\n * @returns The session on state, or `null` when none is stored.\n */\nexport type KycControllerReadSessionStatusAction = {\n  type: `KycController:readSessionStatus`;\n  handler: KycController['readSessionStatus'];\n};\n\n/**\n * Fetches `GET /sessions/{id}/status` once and writes the result onto state.\n *\n * Does not start the session-status polling timer.\n *\n * @param sessionId - UKYC session id.\n * @returns The fetched session status.\n */\nexport type KycControllerFetchSessionStatusOnceAction = {\n  type: `KycController:fetchSessionStatusOnce`;\n  handler: KycController['fetchSessionStatusOnce'];\n};\n\n/**\n * Starts polling `GET /sessions/{id}/status` for\n * {@link KycControllerState.sessionStatus}'s current `id`. Each tick writes\n * the result onto state only when the payload changed. The first poll runs\n * immediately. Each later wait starts at 10 seconds and grows by 10 seconds\n * after every poll, including a failed one. Starting the loop again resets\n * that delay. The loop stops once `finalStatus` is `approved`, `rejected`,\n * or `retry`, or when {@link reset} / {@link clearState} runs.\n *\n * @throws If there is no current session id to poll.\n */\nexport type KycControllerStartSessionStatusPollingAction = {\n  type: `KycController:startSessionStatusPolling`;\n  handler: KycController['startSessionStatusPolling'];\n};\n\n/**\n * Fetches the idOS + KYC-provider disclaimer catalog. Pass exactly one of\n * `sessionId` or `country`:\n *\n * - `{ sessionId }` → {@link KycService.fetchSessionDisclaimersBySessionId}\n * (`GET /sessions/{sessionId}/disclaimers`)\n * - `{ country }` → {@link KycService.fetchSessionDisclaimersByCountry}\n * (`GET /disclaimers?country=`)\n *\n * A session-id fetch also writes the catalog to `sessionDisclaimers`.\n *\n * @param params - The parameters. Provide exactly one of `sessionId` or\n * `country`.\n * @param params.sessionId - The UKYC session id.\n * @param params.country - ISO 3166-1 alpha-3 country code.\n * @returns The catalog. Session fetches include consent state; country\n * fetches do not.\n */\nexport type KycControllerFetchSessionDisclaimersAction = {\n  type: `KycController:fetchSessionDisclaimers`;\n  handler: KycController['fetchSessionDisclaimers'];\n};\n\n/**\n * Fetches the session-scoped disclaimer catalog and records consents\n * derived from the T&C2 flags. Already-consented catalog rows are omitted\n * from the POST. A 409 is re-checked with a GET: continue only when every\n * accepted document is now consented, otherwise fail closed.\n *\n * @param params - Accepted session-disclaimer records.\n * @param params.providerDisclaimersAccepted - Accepted Sumsub disclaimer records.\n * @param params.idosDisclaimersAccepted - Accepted idOS disclaimer records.\n * @param params.credentialReusabilityConsentGiven - Whether credential\n * reuse was accepted.\n */\nexport type KycControllerRecordSessionDisclaimersAction = {\n  type: `KycController:recordSessionDisclaimers`;\n  handler: KycController['recordSessionDisclaimers'];\n};\n\n/**\n * Fetches the current session status and reports whether consent was given.\n *\n * @returns Whether `consentStatus` is `given`.\n * @throws If there is no session on state.\n */\nexport type KycControllerHasCompletedSessionDisclaimersAction = {\n  type: `KycController:hasCompletedSessionDisclaimers`;\n  handler: KycController['hasCompletedSessionDisclaimers'];\n};\n\n/**\n * Fetches the vendor T&Cs the customer must accept before a session is\n * created (`GET /vendors/{vendor}/disclaimers?country=`).\n *\n * @param params - The parameters.\n * @param params.vendor - Identity vendor. Defaults to `moonpay`.\n * @param params.country - ISO 3166-1 alpha-3 country code.\n * @returns The disclaimers.\n */\nexport type KycControllerFetchVendorDisclaimersAction = {\n  type: `KycController:fetchVendorDisclaimers`;\n  handler: KycController['fetchVendorDisclaimers'];\n};\n\n/**\n * Records vendor T&C acceptance via {@link KycService.submitVendorDisclaimers}\n * and persists the accepted ids on state.\n *\n * @param params - The parameters.\n * @param params.disclaimerIds - Accepted vendor T&C ids.\n * @returns The vendor signing records.\n * @throws If `vendor` is missing from state.\n */\nexport type KycControllerRecordVendorDisclaimersAction = {\n  type: `KycController:recordVendorDisclaimers`;\n  handler: KycController['recordVendorDisclaimers'];\n};\n\n/**\n * Fetches the current vendor T&C catalog and returns whether every document\n * is already recorded in {@link KycControllerState.vendorDisclaimersAccepted}.\n *\n * @returns Whether persisted acceptance covers the fetched catalog.\n * @throws If `vendor` or `geoCountry` is missing from state.\n */\nexport type KycControllerHasCompletedVendorDisclaimersAction = {\n  type: `KycController:hasCompletedVendorDisclaimers`;\n  handler: KycController['hasCompletedVendorDisclaimers'];\n};\n\n/**\n * Presents the identity-provider verification UI. Currently launches SumSub.\n *\n * @param params - Optional SDK presentation options.\n * @param params.locale - BCP-47 locale for the SDK UI.\n * @param params.debug - Enables SDK debug logging.\n * @returns The durable provider-flow outcome.\n */\nexport type KycControllerLaunchProviderFlowAction = {\n  type: `KycController:launchProviderFlow`;\n  handler: KycController['launchProviderFlow'];\n};\n\n/**\n * Union of all KycController action types.\n */\nexport type KycControllerMethodActions =\n  | KycControllerStartSessionAction\n  | KycControllerResetAction\n  | KycControllerClearStateAction\n  | KycControllerGetSessionStatusForVendorAction\n  | KycControllerGetDataSharesAction\n  | KycControllerGetProviderFlowStatusAction\n  | KycControllerRefreshSessionStatusAction\n  | KycControllerReadSessionStatusAction\n  | KycControllerFetchSessionStatusOnceAction\n  | KycControllerStartSessionStatusPollingAction\n  | KycControllerFetchSessionDisclaimersAction\n  | KycControllerRecordSessionDisclaimersAction\n  | KycControllerHasCompletedSessionDisclaimersAction\n  | KycControllerFetchVendorDisclaimersAction\n  | KycControllerRecordVendorDisclaimersAction\n  | KycControllerHasCompletedVendorDisclaimersAction\n  | KycControllerLaunchProviderFlowAction;\n"]}
+{"version":3,"file":"KycController-method-action-types.js","sourceRoot":"","sources":["../src/KycController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { KycController } from './KycController.js';\n\n/**\n * Creates the UKYC `local_user_secret` and stores it in Encrypted User\n * Storage when one does not already exist.\n *\n * Call this after the user has expressed intent to onboard and before\n * {@link startSession}. Persisting the secret here moves generation and the\n * storage write off the `startSession` path. `startSession` still reads the\n * secret, and still creates it when this has not been called.\n *\n * Await this call, or attach a rejection handler. A failure does not block\n * onboarding: {@link startSession} creates the secret if it is still missing.\n *\n * The operation is idempotent and uses the same primary entropy source as\n * session creation. The plaintext secret is not returned and is not sent to\n * idOS. Only the encrypted User Storage copy is synced.\n *\n * @throws When Encrypted User Storage cannot be read or written, or when a\n * stored secret has an unexpected length.\n */\nexport type KycControllerEnsureLocalUserSecretAction = {\n  type: `KycController:ensureLocalUserSecret`;\n  handler: KycController['ensureLocalUserSecret'];\n};\n\n/**\n * Starts a KYC session for the given vendor. Reuses a latest vendor session\n * when one exists; otherwise creates a UKYC session.\n *\n * The verified email stored on controller state comes from the partner\n * identity token. When that request returns HTTP 422, a stored email is\n * kept for an existing session. Creating a vendor customer and UKYC session\n * requires the token, which both requests send as `partnerIdentityToken`.\n *\n * Session creation derives client material from the UKYC\n * `local_user_secret`. Call {@link ensureLocalUserSecret} after the user\n * has expressed intent to onboard so that secret is generated and stored\n * before this method runs.\n *\n * @param params - The session parameters.\n * @param params.vendor - Identity vendor for the session.\n * @param params.aal2Token - AAL2 authentication token. Required only when a\n * UKYC session must be created, where it is sent as the Authorization bearer\n * value. Omit it when reusing an existing session.\n * @returns The current or newly created session status.\n */\nexport type KycControllerStartSessionAction = {\n  type: `KycController:startSession`;\n  handler: KycController['startSession'];\n};\n\n/**\n * Stops session-status polling and restores default controller state.\n */\nexport type KycControllerResetAction = {\n  type: `KycController:reset`;\n  handler: KycController['reset'];\n};\n\n/**\n * Restores the controller to its default state.\n */\nexport type KycControllerClearStateAction = {\n  type: `KycController:clearState`;\n  handler: KycController['clearState'];\n};\n\n/**\n * Fetches the latest UKYC session status for a vendor.\n *\n * @param vendor - Identity vendor whose latest session should be queried.\n * @returns The session status, or `null` when none exists.\n */\nexport type KycControllerGetSessionStatusForVendorAction = {\n  type: `KycController:getSessionStatusForVendor`;\n  handler: KycController['getSessionStatusForVendor'];\n};\n\n/**\n * Fetches the vendors this customer's verified identity data has been shared\n * with, newest first.\n *\n * The external user id comes from the session status on state. When no\n * session has been stored yet, the latest session for the vendor on state is\n * fetched first (without writing it to state). An unresolvable session — no\n * vendor on state, or no latest session for it — yields an empty list rather\n * than an error, so consumers can render an empty \"shared with\" list.\n *\n * @returns The data shares, newest first; empty when no session can be\n * resolved.\n */\nexport type KycControllerGetDataSharesAction = {\n  type: `KycController:getDataShares`;\n  handler: KycController['getDataShares'];\n};\n\n/**\n * Returns the durable outcome of the identity-provider flow.\n *\n * @returns The latest provider-flow status.\n */\nexport type KycControllerGetProviderFlowStatusAction = {\n  type: `KycController:getProviderFlowStatus`;\n  handler: KycController['getProviderFlowStatus'];\n};\n\n/**\n * Returns the session already stored on state.\n *\n * Starts session-status polling when `finalStatus` is not `approved`,\n * `rejected`, or `retry`. Does not fetch status or refresh capability\n * authorization.\n *\n * @returns The session status stored at call time.\n * @throws If there is no session on state.\n */\nexport type KycControllerRefreshSessionStatusAction = {\n  type: `KycController:refreshSessionStatus`;\n  handler: KycController['refreshSessionStatus'];\n};\n\n/**\n * Returns the persisted session status.\n *\n * Does not call the network and does not start session-status polling.\n *\n * @returns The session on state, or `null` when none is stored.\n */\nexport type KycControllerReadSessionStatusAction = {\n  type: `KycController:readSessionStatus`;\n  handler: KycController['readSessionStatus'];\n};\n\n/**\n * Fetches `GET /sessions/{id}/status` once and writes the result onto state.\n *\n * Does not start the session-status polling timer.\n *\n * @param sessionId - UKYC session id.\n * @returns The fetched session status.\n */\nexport type KycControllerFetchSessionStatusOnceAction = {\n  type: `KycController:fetchSessionStatusOnce`;\n  handler: KycController['fetchSessionStatusOnce'];\n};\n\n/**\n * Starts polling `GET /sessions/{id}/status` for\n * {@link KycControllerState.sessionStatus}'s current `id`. Each tick writes\n * the result onto state only when the payload changed. The first poll runs\n * immediately. Each later wait starts at 10 seconds and grows by 10 seconds\n * after every poll, including a failed one. Starting the loop again resets\n * that delay. The loop stops once `finalStatus` is `approved`, `rejected`,\n * or `retry`, or when {@link reset} / {@link clearState} runs.\n *\n * @throws If there is no current session id to poll.\n */\nexport type KycControllerStartSessionStatusPollingAction = {\n  type: `KycController:startSessionStatusPolling`;\n  handler: KycController['startSessionStatusPolling'];\n};\n\n/**\n * Fetches the idOS + KYC-provider disclaimer catalog. Pass exactly one of\n * `sessionId` or `country`:\n *\n * - `{ sessionId }` → {@link KycService.fetchSessionDisclaimersBySessionId}\n * (`GET /sessions/{sessionId}/disclaimers`)\n * - `{ country }` → {@link KycService.fetchSessionDisclaimersByCountry}\n * (`GET /disclaimers?country=`)\n *\n * A session-id fetch also writes the catalog to `sessionDisclaimers`.\n *\n * @param params - The parameters. Provide exactly one of `sessionId` or\n * `country`.\n * @param params.sessionId - The UKYC session id.\n * @param params.country - ISO 3166-1 alpha-3 country code.\n * @returns The catalog. Session fetches include consent state; country\n * fetches do not.\n */\nexport type KycControllerFetchSessionDisclaimersAction = {\n  type: `KycController:fetchSessionDisclaimers`;\n  handler: KycController['fetchSessionDisclaimers'];\n};\n\n/**\n * Fetches the session-scoped disclaimer catalog and records consents\n * derived from the T&C2 flags. Already-consented catalog rows are omitted\n * from the POST. A 409 is re-checked with a GET: continue only when every\n * accepted document is now consented, otherwise fail closed.\n *\n * @param params - Accepted session-disclaimer records.\n * @param params.providerDisclaimersAccepted - Accepted Sumsub disclaimer records.\n * @param params.idosDisclaimersAccepted - Accepted idOS disclaimer records.\n * @param params.credentialReusabilityConsentGiven - Whether credential\n * reuse was accepted.\n */\nexport type KycControllerRecordSessionDisclaimersAction = {\n  type: `KycController:recordSessionDisclaimers`;\n  handler: KycController['recordSessionDisclaimers'];\n};\n\n/**\n * Fetches the current session status and reports whether consent was given.\n *\n * @returns Whether `consentStatus` is `given`.\n * @throws If there is no session on state.\n */\nexport type KycControllerHasCompletedSessionDisclaimersAction = {\n  type: `KycController:hasCompletedSessionDisclaimers`;\n  handler: KycController['hasCompletedSessionDisclaimers'];\n};\n\n/**\n * Fetches the vendor T&Cs the customer must accept before a session is\n * created (`GET /vendors/{vendor}/disclaimers?country=`).\n *\n * @param params - The parameters.\n * @param params.vendor - Identity vendor. Defaults to `moonpay`.\n * @param params.country - ISO 3166-1 alpha-3 country code.\n * @returns The disclaimers.\n */\nexport type KycControllerFetchVendorDisclaimersAction = {\n  type: `KycController:fetchVendorDisclaimers`;\n  handler: KycController['fetchVendorDisclaimers'];\n};\n\n/**\n * Records vendor T&C acceptance via {@link KycService.submitVendorDisclaimers}\n * and persists the accepted ids on state.\n *\n * @param params - The parameters.\n * @param params.disclaimerIds - Accepted vendor T&C ids.\n * @returns The vendor signing records.\n * @throws If `vendor` is missing from state.\n */\nexport type KycControllerRecordVendorDisclaimersAction = {\n  type: `KycController:recordVendorDisclaimers`;\n  handler: KycController['recordVendorDisclaimers'];\n};\n\n/**\n * Fetches the current vendor T&C catalog and returns whether every document\n * is already recorded in {@link KycControllerState.vendorDisclaimersAccepted}.\n *\n * @returns Whether persisted acceptance covers the fetched catalog.\n * @throws If `vendor` or `geoCountry` is missing from state.\n */\nexport type KycControllerHasCompletedVendorDisclaimersAction = {\n  type: `KycController:hasCompletedVendorDisclaimers`;\n  handler: KycController['hasCompletedVendorDisclaimers'];\n};\n\n/**\n * Presents the identity-provider verification UI. Currently launches SumSub.\n *\n * @param params - Optional SDK presentation options.\n * @param params.locale - BCP-47 locale for the SDK UI.\n * @param params.debug - Enables SDK debug logging.\n * @returns The durable provider-flow outcome.\n */\nexport type KycControllerLaunchProviderFlowAction = {\n  type: `KycController:launchProviderFlow`;\n  handler: KycController['launchProviderFlow'];\n};\n\n/**\n * Union of all KycController action types.\n */\nexport type KycControllerMethodActions =\n  | KycControllerEnsureLocalUserSecretAction\n  | KycControllerStartSessionAction\n  | KycControllerResetAction\n  | KycControllerClearStateAction\n  | KycControllerGetSessionStatusForVendorAction\n  | KycControllerGetDataSharesAction\n  | KycControllerGetProviderFlowStatusAction\n  | KycControllerRefreshSessionStatusAction\n  | KycControllerReadSessionStatusAction\n  | KycControllerFetchSessionStatusOnceAction\n  | KycControllerStartSessionStatusPollingAction\n  | KycControllerFetchSessionDisclaimersAction\n  | KycControllerRecordSessionDisclaimersAction\n  | KycControllerHasCompletedSessionDisclaimersAction\n  | KycControllerFetchVendorDisclaimersAction\n  | KycControllerRecordVendorDisclaimersAction\n  | KycControllerHasCompletedVendorDisclaimersAction\n  | KycControllerLaunchProviderFlowAction;\n"]}

package/dist/KycController.d.ts

@@ -134,6 +134,26 @@ export declare class KycController extends BaseController<typeof controllerName,
      * @param options.trackKycAnalytics - Optional callbacks that record KYC analytics.
      */
     constructor({ messenger, state, sumsubLauncher, trackKycAnalytics, }: KycControllerOptions);
+    /**
+     * Creates the UKYC `local_user_secret` and stores it in Encrypted User
+     * Storage when one does not already exist.
+     *
+     * Call this after the user has expressed intent to onboard and before
+     * {@link startSession}. Persisting the secret here moves generation and the
+     * storage write off the `startSession` path. `startSession` still reads the
+     * secret, and still creates it when this has not been called.
+     *
+     * Await this call, or attach a rejection handler. A failure does not block
+     * onboarding: {@link startSession} creates the secret if it is still missing.
+     *
+     * The operation is idempotent and uses the same primary entropy source as
+     * session creation. The plaintext secret is not returned and is not sent to
+     * idOS. Only the encrypted User Storage copy is synced.
+     *
+     * @throws When Encrypted User Storage cannot be read or written, or when a
+     * stored secret has an unexpected length.
+     */
+    ensureLocalUserSecret(): Promise<void>;
     /**
      * Starts a KYC session for the given vendor. Reuses a latest vendor session
      * when one exists; otherwise creates a UKYC session.
@@ -143,6 +163,11 @@ export declare class KycController extends BaseController<typeof controllerName,
      * kept for an existing session. Creating a vendor customer and UKYC session
      * requires the token, which both requests send as `partnerIdentityToken`.
      *
+     * Session creation derives client material from the UKYC
+     * `local_user_secret`. Call {@link ensureLocalUserSecret} after the user
+     * has expressed intent to onboard so that secret is generated and stored
+     * before this method runs.
+     *
      * @param params - The session parameters.
      * @param params.vendor - Identity vendor for the session.
      * @param params.aal2Token - AAL2 authentication token. Required only when a

package/dist/KycController.d.ts.map

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

package/dist/KycController.js

@@ -6,7 +6,7 @@ import { toBase64Url } from './encoding.js';
 import { getEmailFromPartnerIdentityToken, isEmailRequiredError, } from './partnerIdentityToken.js';
 import { isSumSubFlowCompleted, isSumSubFlowFailed, } from './providers/sumsub.js';
 import { consentRecordsFromAcceptedList } from './sessionDisclaimers.js';
-import { needsCapabilityAuthorizationRefresh, FINAL_STATUSES_TO_STOP_POLLING, } from './types.js';
+import { needsCapabilityAuthorizationRefresh, FINAL_STATUSES_TO_STOP_POLLING, KYC_CURRENT_STEPS, KYC_STATUSES, } from './types.js';
 import { deriveClientMaterial } from './ukyc/deriveClientMaterial.js';
 import { assertAttestedServerPublicKey } from './ukyc/jwtChain.js';
 import { getOrCreateLocalUserSecret, UkycLocalUserSecretStore, } from './ukyc/localUserSecret.js';
@@ -121,6 +121,7 @@ export function getDefaultKycControllerState() {
 }
 // === MESSENGER ===
 const MESSENGER_EXPOSED_METHODS = [
+    'ensureLocalUserSecret',
     'startSession',
     'reset',
     'clearState',
@@ -206,6 +207,28 @@ export class KycController extends BaseController {
             email: getEmailFromPartnerIdentityToken(partnerIdentityToken),
         };
     }
+    /**
+     * Creates the UKYC `local_user_secret` and stores it in Encrypted User
+     * Storage when one does not already exist.
+     *
+     * Call this after the user has expressed intent to onboard and before
+     * {@link startSession}. Persisting the secret here moves generation and the
+     * storage write off the `startSession` path. `startSession` still reads the
+     * secret, and still creates it when this has not been called.
+     *
+     * Await this call, or attach a rejection handler. A failure does not block
+     * onboarding: {@link startSession} creates the secret if it is still missing.
+     *
+     * The operation is idempotent and uses the same primary entropy source as
+     * session creation. The plaintext secret is not returned and is not sent to
+     * idOS. Only the encrypted User Storage copy is synced.
+     *
+     * @throws When Encrypted User Storage cannot be read or written, or when a
+     * stored secret has an unexpected length.
+     */
+    async ensureLocalUserSecret() {
+        await getOrCreateLocalUserSecret(this.#localUserSecretStore);
+    }
     /**
      * Starts a KYC session for the given vendor. Reuses a latest vendor session
      * when one exists; otherwise creates a UKYC session.
@@ -215,6 +238,11 @@ export class KycController extends BaseController {
      * kept for an existing session. Creating a vendor customer and UKYC session
      * requires the token, which both requests send as `partnerIdentityToken`.
      *
+     * Session creation derives client material from the UKYC
+     * `local_user_secret`. Call {@link ensureLocalUserSecret} after the user
+     * has expressed intent to onboard so that secret is generated and stored
+     * before this method runs.
+     *
      * @param params - The session parameters.
      * @param params.vendor - Identity vendor for the session.
      * @param params.aal2Token - AAL2 authentication token. Required only when a
@@ -912,7 +940,10 @@ export class KycController extends BaseController {
                 this.#recordLaunchOutcomeAndTrackAnalytics('submitted', (state) => {
                     state.sessionStatus = {
                         ...currentSessionStatus,
-                        finalStatus: 'pending',
+                        finalStatus: KYC_STATUSES.pending,
+                        // The applicant has submitted documents, so the session is in
+                        // vendor processing rather than still on the `kyc` step.
+                        currentStep: KYC_CURRENT_STEPS.processing,
                     };
                     state.providerFlowStatus = 'submitted';
                 });