@metamask-previews/profile-sync-controller 32.1.1-preview-db287901b → 32.1.1-preview-d3f9964be

package/CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add `refreshEnrolledCredentials`, `beginCredentialEnrollment` and `completeCredentialEnrollment` to `AuthenticationController`, backed by a memory-only `enrolledCredentials` state and an optional `trace` callback ([#10266](https://github.com/MetaMask/core/pull/10266))
+- Add passkey and email OTP enrollment, verification, credential-list, and elevated-token exchange SDK methods ([#10265](https://github.com/MetaMask/core/pull/10265))
+- Add validated MFA domain types and structured `MfaError` classes with a serialization-safe `mfaCode` ([#10264](https://github.com/MetaMask/core/pull/10264))
 - Add `rampsOrders` to `USER_STORAGE_FEATURE_NAMES` ([#10227](https://github.com/MetaMask/core/pull/10227))
 
 ## [32.1.1]

package/dist/controllers/authentication/AuthenticationController-method-action-types.d.ts

@@ -16,6 +16,43 @@ export type AuthenticationControllerRequestProfilePairingAction = {
     type: `AuthenticationController:requestProfilePairing`;
     handler: AuthenticationController['requestProfilePairing'];
 };
+/**
+ * Refreshes credentials enrolled on the canonical profile.
+ *
+ * @returns The current supported credentials.
+ */
+export type AuthenticationControllerRefreshEnrolledCredentialsAction = {
+    type: `AuthenticationController:refreshEnrolledCredentials`;
+    handler: AuthenticationController['refreshEnrolledCredentials'];
+};
+/**
+ * Begins enrollment of a passkey or email OTP credential.
+ *
+ * @param request - Credential, optional email address, and trace reason.
+ * @returns A challenge for the client-owned ceremony.
+ */
+export type AuthenticationControllerBeginCredentialEnrollmentAction = {
+    type: `AuthenticationController:beginCredentialEnrollment`;
+    handler: AuthenticationController['beginCredentialEnrollment'];
+};
+/**
+ * Completes credential enrollment and refreshes the credential cache.
+ *
+ * A cache-refresh failure does not undo successful enrollment. Email
+ * enrollment invalidates the primary SRP session *after* refresh so the
+ * credentials call can reuse the still-valid access token; the next token
+ * fetch then includes the newly verified email claim. That invalidation
+ * happens even if the session ends mid-request: the enrollment succeeded
+ * on the server, so a token cached across a lock must not be reused
+ * without the new claim.
+ *
+ * @param request - Flow identifier, platform or email proof, and trace reason.
+ * @returns The refreshed credentials, or the existing cache if refresh fails.
+ */
+export type AuthenticationControllerCompleteCredentialEnrollmentAction = {
+    type: `AuthenticationController:completeCredentialEnrollment`;
+    handler: AuthenticationController['completeCredentialEnrollment'];
+};
 export type AuthenticationControllerPerformSignOutAction = {
     type: `AuthenticationController:performSignOut`;
     handler: AuthenticationController['performSignOut'];
@@ -123,5 +160,5 @@ export type AuthenticationControllerIsSignedInAction = {
 /**
  * Union of all AuthenticationController action types.
  */
-export type AuthenticationControllerMethodActions = AuthenticationControllerPerformSignInAction | AuthenticationControllerRequestProfilePairingAction | AuthenticationControllerPerformSignOutAction | AuthenticationControllerClearStateAction | AuthenticationControllerGetBearerTokenAction | AuthenticationControllerGetSessionProfileAction | AuthenticationControllerRefreshCanonicalProfileIdAction | AuthenticationControllerGetUserProfileLineageAction | AuthenticationControllerGetCustomerServiceTokenAction | AuthenticationControllerGetPartnerIdentityTokenAction | AuthenticationControllerIsSignedInAction;
+export type AuthenticationControllerMethodActions = AuthenticationControllerPerformSignInAction | AuthenticationControllerRequestProfilePairingAction | AuthenticationControllerRefreshEnrolledCredentialsAction | AuthenticationControllerBeginCredentialEnrollmentAction | AuthenticationControllerCompleteCredentialEnrollmentAction | AuthenticationControllerPerformSignOutAction | AuthenticationControllerClearStateAction | AuthenticationControllerGetBearerTokenAction | AuthenticationControllerGetSessionProfileAction | AuthenticationControllerRefreshCanonicalProfileIdAction | AuthenticationControllerGetUserProfileLineageAction | AuthenticationControllerGetCustomerServiceTokenAction | AuthenticationControllerGetPartnerIdentityTokenAction | AuthenticationControllerIsSignedInAction;
 //# sourceMappingURL=AuthenticationController-method-action-types.d.ts.map

package/dist/controllers/authentication/AuthenticationController-method-action-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthenticationController-method-action-types.d.ts","sourceRoot":"","sources":["../../../src/controllers/authentication/AuthenticationController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAE9E,MAAM,MAAM,2CAA2C,GAAG;IACxD,IAAI,EAAE,wCAAwC,CAAC;IAC/C,OAAO,EAAE,wBAAwB,CAAC,eAAe,CAAC,CAAC;CACpD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,mDAAmD,GAAG;IAChE,IAAI,EAAE,gDAAgD,CAAC;IACvD,OAAO,EAAE,wBAAwB,CAAC,uBAAuB,CAAC,CAAC;CAC5D,CAAC;AAEF,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,wBAAwB,CAAC,gBAAgB,CAAC,CAAC;CACrD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wCAAwC,GAAG;IACrD,IAAI,EAAE,qCAAqC,CAAC;IAC5C,OAAO,EAAE,wBAAwB,CAAC,YAAY,CAAC,CAAC;CACjD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,4CAA4C,GAAG;IACzD,IAAI,EAAE,yCAAyC,CAAC;IAChD,OAAO,EAAE,wBAAwB,CAAC,gBAAgB,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,+CAA+C,GAAG;IAC5D,IAAI,EAAE,4CAA4C,CAAC;IACnD,OAAO,EAAE,wBAAwB,CAAC,mBAAmB,CAAC,CAAC;CACxD,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,uDAAuD,GAAG;IACpE,IAAI,EAAE,oDAAoD,CAAC;IAC3D,OAAO,EAAE,wBAAwB,CAAC,2BAA2B,CAAC,CAAC;CAChE,CAAC;AAEF,MAAM,MAAM,mDAAmD,GAAG;IAChE,IAAI,EAAE,gDAAgD,CAAC;IACvD,OAAO,EAAE,wBAAwB,CAAC,uBAAuB,CAAC,CAAC;CAC5D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qDAAqD,GAAG;IAClE,IAAI,EAAE,kDAAkD,CAAC;IACzD,OAAO,EAAE,wBAAwB,CAAC,yBAAyB,CAAC,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,qDAAqD,GAAG;IAClE,IAAI,EAAE,kDAAkD,CAAC;IACzD,OAAO,EAAE,wBAAwB,CAAC,yBAAyB,CAAC,CAAC;CAC9D,CAAC;AAEF,MAAM,MAAM,wCAAwC,GAAG;IACrD,IAAI,EAAE,qCAAqC,CAAC;IAC5C,OAAO,EAAE,wBAAwB,CAAC,YAAY,CAAC,CAAC;CACjD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qCAAqC,GAC7C,2CAA2C,GAC3C,mDAAmD,GACnD,4CAA4C,GAC5C,wCAAwC,GACxC,4CAA4C,GAC5C,+CAA+C,GAC/C,uDAAuD,GACvD,mDAAmD,GACnD,qDAAqD,GACrD,qDAAqD,GACrD,wCAAwC,CAAC"}
+{"version":3,"file":"AuthenticationController-method-action-types.d.ts","sourceRoot":"","sources":["../../../src/controllers/authentication/AuthenticationController-method-action-types.ts"],"names":[],"mappings":"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"}

package/dist/controllers/authentication/AuthenticationController-method-action-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"AuthenticationController-method-action-types.js","sourceRoot":"","sources":["../../../src/controllers/authentication/AuthenticationController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { AuthenticationController } from './AuthenticationController.js';\n\nexport type AuthenticationControllerPerformSignInAction = {\n  type: `AuthenticationController:performSignIn`;\n  handler: AuthenticationController['performSignIn'];\n};\n\n/**\n * Marks profile pairing as needed. Clients call this when the SRP set\n * changes (e.g. a new keyring was added) so the next auto-sign-in cycle\n * re-runs `performSignIn` and re-pairs.\n */\nexport type AuthenticationControllerRequestProfilePairingAction = {\n  type: `AuthenticationController:requestProfilePairing`;\n  handler: AuthenticationController['requestProfilePairing'];\n};\n\nexport type AuthenticationControllerPerformSignOutAction = {\n  type: `AuthenticationController:performSignOut`;\n  handler: AuthenticationController['performSignOut'];\n};\n\n/**\n * Resets the controller to `defaultState`. Clients call this on wallet reset\n * so the next wallet starts unsigned with both pairing gates re-armed.\n */\nexport type AuthenticationControllerClearStateAction = {\n  type: `AuthenticationController:clearState`;\n  handler: AuthenticationController['clearState'];\n};\n\n/**\n * Returns a bearer token for the specified SRP, logging in if needed.\n *\n * When called without `entropySourceId`, returns the primary (first) SRP's\n * access token, which is effectively the canonical\n * profile's token that can be used by alias-aware consumers for cross-SRP\n * operations.\n *\n * @param entropySourceId - The entropy source ID. Omit for the primary SRP.\n * @returns The OIDC access token.\n */\nexport type AuthenticationControllerGetBearerTokenAction = {\n  type: `AuthenticationController:getBearerToken`;\n  handler: AuthenticationController['getBearerToken'];\n};\n\n/**\n * Returns the cached session profile, logging in if no session exists.\n *\n * The returned `canonicalProfileId` reflects the value from the most recent\n * login or pairing. In the rare event where a canonical changed because of\n * a pairing that happened on another device, the cached value may be stale\n * until the next login. For guaranteed freshness, call\n * `refreshCanonicalProfileId()` before reading `canonicalProfileId`.\n *\n * @param entropySourceId - The entropy source ID used to derive the key,\n * when multiple sources are available (Multi-SRP).\n * @returns profile for the session.\n */\nexport type AuthenticationControllerGetSessionProfileAction = {\n  type: `AuthenticationController:getSessionProfile`;\n  handler: AuthenticationController['getSessionProfile'];\n};\n\n/**\n * Forces a fresh retrieval of the canonical profile ID from the server\n * and propagates it to all cached SRP sessions.\n *\n * This method invalidates the primary SRP's cached session and forces a\n * re-login. Use it before operations that require a guaranteed-fresh\n * canonical (e.g. storage key derivation for Accounts ADR 0005). For\n * best-effort reads, use\n * `getSessionProfile().canonicalProfileId` instead.\n *\n * Only the primary SRP is re-logged-in regardless of how many SRPs exist —\n * the server returns the current canonical for the entire pairing group\n * from any single SRP login.\n *\n * @returns The refreshed canonical profile ID.\n */\nexport type AuthenticationControllerRefreshCanonicalProfileIdAction = {\n  type: `AuthenticationController:refreshCanonicalProfileId`;\n  handler: AuthenticationController['refreshCanonicalProfileId'];\n};\n\nexport type AuthenticationControllerGetUserProfileLineageAction = {\n  type: `AuthenticationController:getUserProfileLineage`;\n  handler: AuthenticationController['getUserProfileLineage'];\n};\n\n/**\n * Returns a Customer Service specific access token for the specified SRP,\n * logging in if needed.\n *\n * Exchanges the OIDC access token for a short-lived token scoped to the\n * customer-service audience. Customer Service tooling consumes this token to\n * identify and authenticate the user.\n *\n * @param entropySourceId - The entropy source ID. Omit for the primary SRP.\n * @returns The customer-service access token.\n */\nexport type AuthenticationControllerGetCustomerServiceTokenAction = {\n  type: `AuthenticationController:getCustomerServiceToken`;\n  handler: AuthenticationController['getCustomerServiceToken'];\n};\n\n/**\n * Mints a partner identity token for the specified SRP, logging in if needed.\n *\n * Calls `POST /api/v2/oidc/token` with the Hydra login bearer and returns\n * the minted `access_token`. Email on live tokens is under JWT `ext`.\n * HTTP 422 throws `EmailRequiredError` when this profile has no\n * verified email.\n *\n * @param claims - Claim names to embed. Only `email` is supported.\n * @param audience - Partner audience (`kyc` or `iron`).\n * @param entropySourceId - The entropy source ID. Omit for the primary SRP.\n * @returns The partner identity access token.\n */\nexport type AuthenticationControllerGetPartnerIdentityTokenAction = {\n  type: `AuthenticationController:getPartnerIdentityToken`;\n  handler: AuthenticationController['getPartnerIdentityToken'];\n};\n\nexport type AuthenticationControllerIsSignedInAction = {\n  type: `AuthenticationController:isSignedIn`;\n  handler: AuthenticationController['isSignedIn'];\n};\n\n/**\n * Union of all AuthenticationController action types.\n */\nexport type AuthenticationControllerMethodActions =\n  | AuthenticationControllerPerformSignInAction\n  | AuthenticationControllerRequestProfilePairingAction\n  | AuthenticationControllerPerformSignOutAction\n  | AuthenticationControllerClearStateAction\n  | AuthenticationControllerGetBearerTokenAction\n  | AuthenticationControllerGetSessionProfileAction\n  | AuthenticationControllerRefreshCanonicalProfileIdAction\n  | AuthenticationControllerGetUserProfileLineageAction\n  | AuthenticationControllerGetCustomerServiceTokenAction\n  | AuthenticationControllerGetPartnerIdentityTokenAction\n  | AuthenticationControllerIsSignedInAction;\n"]}
+{"version":3,"file":"AuthenticationController-method-action-types.js","sourceRoot":"","sources":["../../../src/controllers/authentication/AuthenticationController-method-action-types.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { AuthenticationController } from './AuthenticationController.js';\n\nexport type AuthenticationControllerPerformSignInAction = {\n  type: `AuthenticationController:performSignIn`;\n  handler: AuthenticationController['performSignIn'];\n};\n\n/**\n * Marks profile pairing as needed. Clients call this when the SRP set\n * changes (e.g. a new keyring was added) so the next auto-sign-in cycle\n * re-runs `performSignIn` and re-pairs.\n */\nexport type AuthenticationControllerRequestProfilePairingAction = {\n  type: `AuthenticationController:requestProfilePairing`;\n  handler: AuthenticationController['requestProfilePairing'];\n};\n\n/**\n * Refreshes credentials enrolled on the canonical profile.\n *\n * @returns The current supported credentials.\n */\nexport type AuthenticationControllerRefreshEnrolledCredentialsAction = {\n  type: `AuthenticationController:refreshEnrolledCredentials`;\n  handler: AuthenticationController['refreshEnrolledCredentials'];\n};\n\n/**\n * Begins enrollment of a passkey or email OTP credential.\n *\n * @param request - Credential, optional email address, and trace reason.\n * @returns A challenge for the client-owned ceremony.\n */\nexport type AuthenticationControllerBeginCredentialEnrollmentAction = {\n  type: `AuthenticationController:beginCredentialEnrollment`;\n  handler: AuthenticationController['beginCredentialEnrollment'];\n};\n\n/**\n * Completes credential enrollment and refreshes the credential cache.\n *\n * A cache-refresh failure does not undo successful enrollment. Email\n * enrollment invalidates the primary SRP session *after* refresh so the\n * credentials call can reuse the still-valid access token; the next token\n * fetch then includes the newly verified email claim. That invalidation\n * happens even if the session ends mid-request: the enrollment succeeded\n * on the server, so a token cached across a lock must not be reused\n * without the new claim.\n *\n * @param request - Flow identifier, platform or email proof, and trace reason.\n * @returns The refreshed credentials, or the existing cache if refresh fails.\n */\nexport type AuthenticationControllerCompleteCredentialEnrollmentAction = {\n  type: `AuthenticationController:completeCredentialEnrollment`;\n  handler: AuthenticationController['completeCredentialEnrollment'];\n};\n\nexport type AuthenticationControllerPerformSignOutAction = {\n  type: `AuthenticationController:performSignOut`;\n  handler: AuthenticationController['performSignOut'];\n};\n\n/**\n * Resets the controller to `defaultState`. Clients call this on wallet reset\n * so the next wallet starts unsigned with both pairing gates re-armed.\n */\nexport type AuthenticationControllerClearStateAction = {\n  type: `AuthenticationController:clearState`;\n  handler: AuthenticationController['clearState'];\n};\n\n/**\n * Returns a bearer token for the specified SRP, logging in if needed.\n *\n * When called without `entropySourceId`, returns the primary (first) SRP's\n * access token, which is effectively the canonical\n * profile's token that can be used by alias-aware consumers for cross-SRP\n * operations.\n *\n * @param entropySourceId - The entropy source ID. Omit for the primary SRP.\n * @returns The OIDC access token.\n */\nexport type AuthenticationControllerGetBearerTokenAction = {\n  type: `AuthenticationController:getBearerToken`;\n  handler: AuthenticationController['getBearerToken'];\n};\n\n/**\n * Returns the cached session profile, logging in if no session exists.\n *\n * The returned `canonicalProfileId` reflects the value from the most recent\n * login or pairing. In the rare event where a canonical changed because of\n * a pairing that happened on another device, the cached value may be stale\n * until the next login. For guaranteed freshness, call\n * `refreshCanonicalProfileId()` before reading `canonicalProfileId`.\n *\n * @param entropySourceId - The entropy source ID used to derive the key,\n * when multiple sources are available (Multi-SRP).\n * @returns profile for the session.\n */\nexport type AuthenticationControllerGetSessionProfileAction = {\n  type: `AuthenticationController:getSessionProfile`;\n  handler: AuthenticationController['getSessionProfile'];\n};\n\n/**\n * Forces a fresh retrieval of the canonical profile ID from the server\n * and propagates it to all cached SRP sessions.\n *\n * This method invalidates the primary SRP's cached session and forces a\n * re-login. Use it before operations that require a guaranteed-fresh\n * canonical (e.g. storage key derivation for Accounts ADR 0005). For\n * best-effort reads, use\n * `getSessionProfile().canonicalProfileId` instead.\n *\n * Only the primary SRP is re-logged-in regardless of how many SRPs exist —\n * the server returns the current canonical for the entire pairing group\n * from any single SRP login.\n *\n * @returns The refreshed canonical profile ID.\n */\nexport type AuthenticationControllerRefreshCanonicalProfileIdAction = {\n  type: `AuthenticationController:refreshCanonicalProfileId`;\n  handler: AuthenticationController['refreshCanonicalProfileId'];\n};\n\nexport type AuthenticationControllerGetUserProfileLineageAction = {\n  type: `AuthenticationController:getUserProfileLineage`;\n  handler: AuthenticationController['getUserProfileLineage'];\n};\n\n/**\n * Returns a Customer Service specific access token for the specified SRP,\n * logging in if needed.\n *\n * Exchanges the OIDC access token for a short-lived token scoped to the\n * customer-service audience. Customer Service tooling consumes this token to\n * identify and authenticate the user.\n *\n * @param entropySourceId - The entropy source ID. Omit for the primary SRP.\n * @returns The customer-service access token.\n */\nexport type AuthenticationControllerGetCustomerServiceTokenAction = {\n  type: `AuthenticationController:getCustomerServiceToken`;\n  handler: AuthenticationController['getCustomerServiceToken'];\n};\n\n/**\n * Mints a partner identity token for the specified SRP, logging in if needed.\n *\n * Calls `POST /api/v2/oidc/token` with the Hydra login bearer and returns\n * the minted `access_token`. Email on live tokens is under JWT `ext`.\n * HTTP 422 throws `EmailRequiredError` when this profile has no\n * verified email.\n *\n * @param claims - Claim names to embed. Only `email` is supported.\n * @param audience - Partner audience (`kyc` or `iron`).\n * @param entropySourceId - The entropy source ID. Omit for the primary SRP.\n * @returns The partner identity access token.\n */\nexport type AuthenticationControllerGetPartnerIdentityTokenAction = {\n  type: `AuthenticationController:getPartnerIdentityToken`;\n  handler: AuthenticationController['getPartnerIdentityToken'];\n};\n\nexport type AuthenticationControllerIsSignedInAction = {\n  type: `AuthenticationController:isSignedIn`;\n  handler: AuthenticationController['isSignedIn'];\n};\n\n/**\n * Union of all AuthenticationController action types.\n */\nexport type AuthenticationControllerMethodActions =\n  | AuthenticationControllerPerformSignInAction\n  | AuthenticationControllerRequestProfilePairingAction\n  | AuthenticationControllerRefreshEnrolledCredentialsAction\n  | AuthenticationControllerBeginCredentialEnrollmentAction\n  | AuthenticationControllerCompleteCredentialEnrollmentAction\n  | AuthenticationControllerPerformSignOutAction\n  | AuthenticationControllerClearStateAction\n  | AuthenticationControllerGetBearerTokenAction\n  | AuthenticationControllerGetSessionProfileAction\n  | AuthenticationControllerRefreshCanonicalProfileIdAction\n  | AuthenticationControllerGetUserProfileLineageAction\n  | AuthenticationControllerGetCustomerServiceTokenAction\n  | AuthenticationControllerGetPartnerIdentityTokenAction\n  | AuthenticationControllerIsSignedInAction;\n"]}

package/dist/controllers/authentication/AuthenticationController.d.ts

@@ -1,9 +1,10 @@
 import { BaseController } from '@metamask/base-controller';
 import type { ControllerGetStateAction, ControllerStateChangeEvent } from '@metamask/base-controller';
+import type { TraceCallback } from '@metamask/controller-utils';
 import type { KeyringControllerGetStateAction, KeyringControllerLockEvent, KeyringControllerUnlockEvent, KeyringControllerWithKeyringV2UnsafeAction } from '@metamask/keyring-controller';
 import type { Messenger } from '@metamask/messenger';
 import type { SeedlessOnboardingControllerGetAccessTokenAction, SeedlessOnboardingControllerGetStateAction } from '@metamask/seedless-onboarding-controller';
-import type { LoginResponse, ProfileAlias, UserProfile, UserProfileLineage, OidcTokenAudience, OidcTokenClaims } from '../../sdk/index.js';
+import type { LoginResponse, ProfileAlias, UserProfile, UserProfileLineage, OidcTokenAudience, OidcTokenClaims, BeginEnrollmentRequest, CompleteEnrollmentRequest, EnrolledCredential, EnrollmentChallenge } from '../../sdk/index.js';
 import { Env } from '../../sdk/index.js';
 import type { MetaMetricsAuth } from '../../shared/types/services.js';
 import { AuthenticationControllerMethodActions } from './AuthenticationController-method-action-types.js';
@@ -11,6 +12,12 @@ declare const controllerName = "AuthenticationController";
 export type AuthenticationControllerState = {
     isSignedIn: boolean;
     srpSessionData?: Record<string, LoginResponse>;
+    /**
+     * Credentials fetched for the current profile. The controller always seeds
+     * this to an empty array; it remains optional so partial-state selectors stay
+     * assignable to the controller state type.
+     */
+    enrolledCredentials?: EnrolledCredential[];
     /**
      * Client gate for profile pairing. Defaults to `true` (fresh install /
      * upgrade), set to `false` after a successful `performSignIn` pair, set
@@ -69,7 +76,7 @@ export type AuthenticationControllerMessenger = Messenger<typeof controllerName,
  */
 export declare class AuthenticationController extends BaseController<typeof controllerName, AuthenticationControllerState, AuthenticationControllerMessenger> {
     #private;
-    constructor({ messenger, state, config, metametrics, }: {
+    constructor({ messenger, state, config, metametrics, trace, }: {
         messenger: AuthenticationControllerMessenger;
         state?: AuthenticationControllerState;
         config?: Partial<ControllerConfig>;
@@ -78,6 +85,7 @@ export declare class AuthenticationController extends BaseController<typeof cont
          * do not want to tie this strictly to extension
          */
         metametrics: MetaMetricsAuth;
+        trace?: TraceCallback;
     });
     performSignIn(): Promise<string[]>;
     /**
@@ -86,6 +94,34 @@ export declare class AuthenticationController extends BaseController<typeof cont
      * re-runs `performSignIn` and re-pairs.
      */
     requestProfilePairing(): void;
+    /**
+     * Refreshes credentials enrolled on the canonical profile.
+     *
+     * @returns The current supported credentials.
+     */
+    refreshEnrolledCredentials(): Promise<EnrolledCredential[]>;
+    /**
+     * Begins enrollment of a passkey or email OTP credential.
+     *
+     * @param request - Credential, optional email address, and trace reason.
+     * @returns A challenge for the client-owned ceremony.
+     */
+    beginCredentialEnrollment(request: BeginEnrollmentRequest): Promise<EnrollmentChallenge>;
+    /**
+     * Completes credential enrollment and refreshes the credential cache.
+     *
+     * A cache-refresh failure does not undo successful enrollment. Email
+     * enrollment invalidates the primary SRP session *after* refresh so the
+     * credentials call can reuse the still-valid access token; the next token
+     * fetch then includes the newly verified email claim. That invalidation
+     * happens even if the session ends mid-request: the enrollment succeeded
+     * on the server, so a token cached across a lock must not be reused
+     * without the new claim.
+     *
+     * @param request - Flow identifier, platform or email proof, and trace reason.
+     * @returns The refreshed credentials, or the existing cache if refresh fails.
+     */
+    completeCredentialEnrollment(request: CompleteEnrollmentRequest): Promise<EnrolledCredential[]>;
     performSignOut(): void;
     /**
      * Resets the controller to `defaultState`. Clients call this on wallet reset

package/dist/controllers/authentication/AuthenticationController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AuthenticationController.d.ts","sourceRoot":"","sources":["../../../src/controllers/authentication/AuthenticationController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EACV,+BAA+B,EAC/B,0BAA0B,EAC1B,4BAA4B,EAC5B,0CAA0C,EAC3C,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EACV,gDAAgD,EAChD,0CAA0C,EAC3C,MAAM,0CAA0C,CAAC;AAGlD,OAAO,KAAK,EAEV,aAAa,EACb,YAAY,EAGZ,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAGL,GAAG,EAGJ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAUtE,OAAO,EAAE,qCAAqC,EAAE,MAAM,mDAAmD,CAAC;AAE1G,QAAA,MAAM,cAAc,6BAA6B,CAAC;AAGlD,MAAM,MAAM,6BAA6B,GAAG;IAC1C,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC/C;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AACF,eAAO,MAAM,YAAY,EAAE,6BAI1B,CAAC;AAkDF,KAAK,gBAAgB,GAAG;IACtB,GAAG,EAAE,GAAG,CAAC;IACT;;;;OAIG;IACH,sBAAsB,EAAE,MAAM,OAAO,CAAC;CACvC,CAAC;AAgBF,MAAM,MAAM,OAAO,GACf,sCAAsC,GACtC,qCAAqC,CAAC;AAE1C,MAAM,MAAM,sCAAsC,GAAG,wBAAwB,CAC3E,OAAO,cAAc,EACrB,6BAA6B,CAC9B,CAAC;AAEF,MAAM,MAAM,wCAAwC,GAClD,0BAA0B,CACxB,OAAO,cAAc,EACrB,6BAA6B,CAC9B,CAAC;AAEJ,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,YAAY,EAAE,CAAC;IAC/B,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,0CAA0C,GAAG;IACvD,IAAI,EAAE,GAAG,OAAO,cAAc,gBAAgB,CAAC;IAC/C,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,MAAM,GACd,wCAAwC,GACxC,0CAA0C,CAAC;AAG/C,KAAK,cAAc,GACf,+BAA+B,GAC/B,0CAA0C,GAC1C,0CAA0C,GAC1C,gDAAgD,CAAC;AAErD,KAAK,aAAa,GAAG,0BAA0B,GAAG,4BAA4B,CAAC;AAG/E,MAAM,MAAM,iCAAiC,GAAG,SAAS,CACvD,OAAO,cAAc,EACrB,OAAO,GAAG,cAAc,EACxB,MAAM,GAAG,aAAa,CACvB,CAAC;AAEF;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,cAAc,CAC1D,OAAO,cAAc,EACrB,6BAA6B,EAC7B,iCAAiC,CAClC;;IAiCC,YAAY,EACV,SAAS,EACT,KAAK,EACL,MAAM,EACN,WAAW,GACZ,EAAE;QACD,SAAS,EAAE,iCAAiC,CAAC;QAC7C,KAAK,CAAC,EAAE,6BAA6B,CAAC;QACtC,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;QACnC;;;WAGG;QACH,WAAW,EAAE,eAAe,CAAC;KAC9B,EAgDA;IAoKY,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAiC9C;IA+GD;;;;OAIG;IACI,qBAAqB,IAAI,IAAI,CAOnC;IAuGM,cAAc,IAAI,IAAI,CAK5B;IAED;;;OAGG;IACI,UAAU,IAAI,IAAI,CAGxB;IAED;;;;;;;;;;OAUG;IACU,cAAc,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAIrE;IAED;;;;;;;;;;;;OAYG;IACU,iBAAiB,CAC5B,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,WAAW,CAAC,CAItB;IAED;;;;;;;;;;;;;;;OAeG;IACU,yBAAyB,IAAI,OAAO,CAAC,MAAM,CAAC,CAgBxD;IAcY,qBAAqB,CAChC,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,kBAAkB,CAAC,CAI7B;IAED;;;;;;;;;;OAUG;IACU,uBAAuB,CAClC,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAIjB;IAED;;;;;;;;;;;;OAYG;IACU,uBAAuB,CAClC,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,iBAAiB,EAC3B,eAAe,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAQjB;IAEM,UAAU,IAAI,OAAO,CAE3B;CA8EF"}
+{"version":3,"file":"AuthenticationController.d.ts","sourceRoot":"","sources":["../../../src/controllers/authentication/AuthenticationController.ts"],"names":[],"mappings":"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"}

package/dist/controllers/authentication/AuthenticationController.js

@@ -1,11 +1,14 @@
 import { BaseController } from '@metamask/base-controller';
-import { assertMessageStartsWithMetamask, AuthType, Env, JwtBearerAuth, PairConflictError, } from '../../sdk/index.js';
-import { getHdKeyringEntropySourceIds, getPrimaryHdKeyringEntropySourceId, } from '../../shared/utils/entropy-source.js';
+import { selectHdKeyringEntropySourceIds } from '@metamask/keyring-controller';
+import { BeginEnrollmentRequestStruct, CompleteEnrollmentRequestStruct, assertValidMfaRequest, } from '../../sdk/authentication-jwt-bearer/mfa/schemas.js';
+import { assertMessageStartsWithMetamask, AuthType, Env, JwtBearerAuth, PairConflictError, getMfaErrorCode, } from '../../sdk/index.js';
+import { getPrimaryHdKeyringEntropySourceId } from '../../shared/utils/entropy-source.js';
 import { getHdKeyringSeed } from '../../shared/utils/hd-keyring-seed.js';
 import { getMessageSigningPublicKey, signMessageWithMessageSigningKey, } from '../../shared/utils/message-signing.js';
 const controllerName = 'AuthenticationController';
 export const defaultState = {
     isSignedIn: false,
+    enrolledCredentials: [],
     needsProfilePairing: true,
     needsSocialPairing: true,
 };
@@ -52,6 +55,17 @@ const metadata = {
         includeInDebugSnapshot: false,
         usedInUi: true,
     },
+    enrolledCredentials: {
+        // Allow-list so new credential types cannot leak identifiers by default.
+        includeInStateLogs: (credentials) => credentials?.map(({ type, status, enrolledAt }) => ({
+            type,
+            status,
+            ...(enrolledAt === undefined ? {} : { enrolledAt }),
+        })) ?? null,
+        persist: false,
+        includeInDebugSnapshot: false,
+        usedInUi: true,
+    },
 };
 const MESSENGER_EXPOSED_METHODS = [
     'performSignIn',
@@ -65,6 +79,9 @@ const MESSENGER_EXPOSED_METHODS = [
     'isSignedIn',
     'requestProfilePairing',
     'clearState',
+    'refreshEnrolledCredentials',
+    'beginCredentialEnrollment',
+    'completeCredentialEnrollment',
 ];
 /**
  * Controller that enables authentication for restricted endpoints.
@@ -73,11 +90,24 @@ const MESSENGER_EXPOSED_METHODS = [
 export class AuthenticationController extends BaseController {
     #metametrics;
     #auth;
+    #trace;
     #config = {
         env: Env.PRD,
         isSocialPairingEnabled: () => false,
     };
     #isUnlocked = false;
+    /**
+     * Bumped whenever the authenticated session ends, so an in-flight MFA
+     * ceremony started under the previous session cannot apply its result.
+     */
+    #authSessionEpoch = 0;
+    /**
+     * Sequence number of the most recently started credentials refresh. Only
+     * that refresh may write the cache, so a slower, earlier request cannot
+     * overwrite a newer list (e.g. an explicit refresh landing after an
+     * enrollment's refresh).
+     */
+    #credentialsRefreshSeq = 0;
     /**
      * Bumped by `requestProfilePairing` and `clearState` so an in-flight
      * `performSignIn` can't clear `needsProfilePairing` afterwards.
@@ -91,11 +121,12 @@ export class AuthenticationController extends BaseController {
                 this.#isUnlocked = true;
             });
             this.messenger.subscribe('KeyringController:lock', () => {
+                this.#authSessionEpoch += 1;
                 this.#isUnlocked = false;
             });
         },
     };
-    constructor({ messenger, state, config, metametrics, }) {
+    constructor({ messenger, state, config, metametrics, trace, }) {
         super({
             messenger,
             metadata,
@@ -111,6 +142,7 @@ export class AuthenticationController extends BaseController {
             isSocialPairingEnabled: config?.isSocialPairingEnabled ?? this.#config.isSocialPairingEnabled,
         };
         this.#metametrics = metametrics;
+        this.#trace = trace ?? ((_request, fn) => fn?.());
         this.#auth = new JwtBearerAuth({
             env: this.#config.env,
             platform: metametrics.agent,
@@ -160,14 +192,19 @@ export class AuthenticationController extends BaseController {
             throw new Error(`${methodName} - unable to proceed, wallet is locked`);
         }
     }
+    #assertAuthSessionEpoch(epoch, methodName) {
+        if (!this.#isUnlocked || this.#authSessionEpoch !== epoch) {
+            throw new Error(`${methodName} - unable to proceed, the authenticated session ended`);
+        }
+    }
     /**
      * Reads the HD keyring entropy source IDs from KeyringController.
      *
      * @returns The HD keyring metadata IDs, primary first.
      */
     #getHdKeyringEntropySourceIds() {
-        const { keyrings } = this.messenger.call('KeyringController:getState');
-        return getHdKeyringEntropySourceIds(keyrings);
+        const keyringState = this.messenger.call('KeyringController:getState');
+        return selectHdKeyringEntropySourceIds(keyringState);
     }
     /**
      * Resolves the primary SRP's entropy source ID from KeyringController rather
@@ -179,8 +216,8 @@ export class AuthenticationController extends BaseController {
      * the wallet is unlocked.
      */
     #getPrimaryEntropySourceId() {
-        const { keyrings } = this.messenger.call('KeyringController:getState');
-        return getPrimaryHdKeyringEntropySourceId(keyrings);
+        const keyringState = this.messenger.call('KeyringController:getState');
+        return getPrimaryHdKeyringEntropySourceId(keyringState);
     }
     /**
      * Resolves the SRP login tag for `raw_message`.
@@ -490,7 +527,146 @@ export class AuthenticationController extends BaseController {
         return (this.state.srpSessionData?.[primaryEntropySourceId]?.profile
             ?.canonicalProfileId ?? null);
     }
+    /**
+     * Runs one MFA network step inside a trace span tagged with the caller's
+     * operation and the credential type, recording the outcome and MFA error
+     * code.
+     *
+     * @param name - Span name.
+     * @param operation - Caller-supplied `reason.operation`.
+     * @param credentialType - Credential type the step concerns.
+     * @param fn - The network step.
+     * @returns The step's result.
+     */
+    async #runMfaRequest(name, operation, credentialType, fn) {
+        const data = { outcome: 'pending' };
+        return await this.#trace({
+            name,
+            tags: { operation, credentialType },
+            data,
+        }, async () => {
+            try {
+                const result = await fn();
+                data.outcome = 'success';
+                return result;
+            }
+            catch (error) {
+                data.outcome = 'error';
+                const mfaCode = getMfaErrorCode(error);
+                if (mfaCode) {
+                    data.mfaErrorCode = mfaCode;
+                }
+                throw error;
+            }
+        });
+    }
+    /**
+     * Refreshes credentials enrolled on the canonical profile.
+     *
+     * @returns The current supported credentials.
+     */
+    async refreshEnrolledCredentials() {
+        this.#assertIsUnlocked('refreshEnrolledCredentials');
+        const sessionEpoch = this.#authSessionEpoch;
+        this.#credentialsRefreshSeq += 1;
+        const refreshSeq = this.#credentialsRefreshSeq;
+        const primaryEntropySourceId = this.#getPrimaryEntropySourceId();
+        const credentials = await this.#runMfaRequest('MFA Credentials Refresh', 'credentials.refresh', 'all', async () => await this.#auth.getMfaCredentials(primaryEntropySourceId));
+        this.#assertAuthSessionEpoch(sessionEpoch, 'refreshEnrolledCredentials');
+        // A newer refresh started while this one was in flight; its result is at
+        // least as fresh, so defer to it rather than overwrite with older data.
+        if (refreshSeq !== this.#credentialsRefreshSeq) {
+            return this.#getEnrolledCredentials();
+        }
+        // Skip the write when nothing changed so subscribers are not woken up by
+        // a fresh-but-identical array.
+        if (JSON.stringify(credentials) !==
+            JSON.stringify(this.#getEnrolledCredentials())) {
+            this.update((state) => {
+                state.enrolledCredentials = credentials;
+            });
+        }
+        return credentials;
+    }
+    /**
+     * Begins enrollment of a passkey or email OTP credential.
+     *
+     * @param request - Credential, optional email address, and trace reason.
+     * @returns A challenge for the client-owned ceremony.
+     */
+    async beginCredentialEnrollment(request) {
+        this.#assertIsUnlocked('beginCredentialEnrollment');
+        const sessionEpoch = this.#authSessionEpoch;
+        assertValidMfaRequest(request, BeginEnrollmentRequestStruct);
+        const primaryEntropySourceId = this.#getPrimaryEntropySourceId();
+        const challenge = await this.#runMfaRequest('MFA Enroll Begin', request.reason.operation, request.type, async () => await this.#auth.beginMfaEnrollment(request.type, {
+            email: request.email,
+            entropySourceId: primaryEntropySourceId,
+        }));
+        this.#assertAuthSessionEpoch(sessionEpoch, 'beginCredentialEnrollment');
+        return challenge;
+    }
+    /**
+     * Completes credential enrollment and refreshes the credential cache.
+     *
+     * A cache-refresh failure does not undo successful enrollment. Email
+     * enrollment invalidates the primary SRP session *after* refresh so the
+     * credentials call can reuse the still-valid access token; the next token
+     * fetch then includes the newly verified email claim. That invalidation
+     * happens even if the session ends mid-request: the enrollment succeeded
+     * on the server, so a token cached across a lock must not be reused
+     * without the new claim.
+     *
+     * @param request - Flow identifier, platform or email proof, and trace reason.
+     * @returns The refreshed credentials, or the existing cache if refresh fails.
+     */
+    async completeCredentialEnrollment(request) {
+        this.#assertIsUnlocked('completeCredentialEnrollment');
+        const sessionEpoch = this.#authSessionEpoch;
+        assertValidMfaRequest(request, CompleteEnrollmentRequestStruct);
+        const { type } = request.proof;
+        const primaryEntropySourceId = this.#getPrimaryEntropySourceId();
+        await this.#runMfaRequest('MFA Enroll Complete', request.reason.operation, type, async () => await this.#auth.completeMfaEnrollment(request.flowId, request.proof, primaryEntropySourceId));
+        try {
+            this.#assertAuthSessionEpoch(sessionEpoch, 'completeCredentialEnrollment');
+        }
+        catch (error) {
+            if (type === 'email_otp') {
+                this.#invalidateSrpSession(primaryEntropySourceId);
+            }
+            throw error;
+        }
+        try {
+            return await this.refreshEnrolledCredentials();
+        }
+        catch {
+            return this.#getEnrolledCredentials();
+        }
+        finally {
+            if (type === 'email_otp') {
+                this.#invalidateSrpSession(primaryEntropySourceId);
+            }
+        }
+    }
+    /**
+     * Drops the cached credential list. Callers that wipe profile state must go
+     * through this so subscribers never keep credentials belonging to a profile
+     * that is no longer active.
+     */
+    #clearEnrolledCredentials() {
+        if (this.#getEnrolledCredentials().length === 0) {
+            return;
+        }
+        this.update((state) => {
+            state.enrolledCredentials = [];
+        });
+    }
+    #getEnrolledCredentials() {
+        return this.state.enrolledCredentials ?? [];
+    }
     performSignOut() {
+        this.#authSessionEpoch += 1;
+        this.#clearEnrolledCredentials();
         this.update((state) => {
             state.isSignedIn = false;
             state.srpSessionData = undefined;
@@ -502,6 +678,8 @@ export class AuthenticationController extends BaseController {
      */
     clearState() {
         this.#profilePairingRequestEpoch += 1;
+        this.#authSessionEpoch += 1;
+        this.#clearEnrolledCredentials();
         this.update(() => ({ ...defaultState }));
     }
     /**