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

package/CHANGELOG.md

@@ -9,6 +9,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Support AAL2-gated MFA enrollment and sync the MFA SDK with the latest authentication API spec ([#10374](https://github.com/MetaMask/core/pull/10374))
+  - `beginMfaEnrollment` accepts an `accessToken` option so enrollment can begin with an elevated token
+  - `AuthenticationController.beginCredentialEnrollment` sends the elevated token while a step-up session is live, since enrolling additional credentials requires AAL2
+  - Add the `email_socially_verified`, `multi_primary_srp` and `aal2_required` MFA error codes, a `StepUpRequiredError` class, and support for the `retry_after_seconds` error field when computing `retryAfterMs`
+
+### Changed
+
+- Bump `immer` from `^9.0.6` to `^9.0.21` ([#10331](https://github.com/MetaMask/core/pull/10331))
+
+## [32.2.0]
+
+### Added
+
+- Add `beginStepUp`, `completeStepUp`, `getElevatedProfileToken` and `clearStepUpSession` to `AuthenticationController`, holding the elevated token in memory only behind a hard-expiring `stepUpSessionExpiresAt` state ([#10267](https://github.com/MetaMask/core/pull/10267))
 - 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))
@@ -977,7 +991,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release
 
-[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/profile-sync-controller@32.1.1...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/profile-sync-controller@32.2.0...HEAD
+[32.2.0]: https://github.com/MetaMask/core/compare/@metamask/profile-sync-controller@32.1.1...@metamask/profile-sync-controller@32.2.0
 [32.1.1]: https://github.com/MetaMask/core/compare/@metamask/profile-sync-controller@32.1.0...@metamask/profile-sync-controller@32.1.1
 [32.1.0]: https://github.com/MetaMask/core/compare/@metamask/profile-sync-controller@32.0.0...@metamask/profile-sync-controller@32.1.0
 [32.0.0]: https://github.com/MetaMask/core/compare/@metamask/profile-sync-controller@31.0.0...@metamask/profile-sync-controller@32.0.0

package/README.md

@@ -42,6 +42,27 @@ import { ... } from '@metamask/profile-sync-controller/auth/mocks'
 import { ... } from '@metamask/profile-sync-controller/user-storage/mocks'
 ```
 
+## Multi-factor authentication
+
+`AuthenticationController` exposes UI-independent primitives for passkey and
+email OTP enrollment and step-up verification:
+
+- `refreshEnrolledCredentials()` refreshes the in-memory credential list.
+- `beginCredentialEnrollment()` and `completeCredentialEnrollment()` surround
+  a client-owned passkey ceremony or email-code screen. Beginning enrollment
+  of a second or later credential requires an elevated session:
+  `beginCredentialEnrollment()` sends the elevated token while one is live,
+  and the server otherwise rejects it with `aal2_required`, so clients should
+  step up and retry.
+- `beginStepUp()` and `completeStepUp()` verify an enrolled credential and
+  return an elevated profile token.
+- `getElevatedProfileToken()` reuses a live elevated session when it satisfies
+  the caller's freshness requirement; `clearStepUpSession()` clears it.
+
+Clients must retain the challenge `flowId`, perform the platform ceremony, and
+send the resulting proof to the matching completion method. OTP codes,
+passkey results, and elevated tokens are never persisted in controller state.
+
 ## Contributing
 
 This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/core#readme).

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

@@ -53,6 +53,48 @@ export type AuthenticationControllerCompleteCredentialEnrollmentAction = {
     type: `AuthenticationController:completeCredentialEnrollment`;
     handler: AuthenticationController['completeCredentialEnrollment'];
 };
+/**
+ * Begins step-up verification with an enrolled credential.
+ *
+ * @param request - Credential type and trace reason.
+ * @returns A challenge for the client-owned ceremony.
+ */
+export type AuthenticationControllerBeginStepUpAction = {
+    type: `AuthenticationController:beginStepUp`;
+    handler: AuthenticationController['beginStepUp'];
+};
+/**
+ * Completes step-up verification and opens a short-lived elevated session.
+ *
+ * The AAL2 assertion returned by the MFA service is exchanged at Hydra for
+ * an elevated access token, whose claims are checked before the session
+ * opens. The token itself never enters controller state.
+ *
+ * @param request - Flow identifier, platform or email proof, and trace reason.
+ * @returns The elevated profile access token.
+ */
+export type AuthenticationControllerCompleteStepUpAction = {
+    type: `AuthenticationController:completeStepUp`;
+    handler: AuthenticationController['completeStepUp'];
+};
+/**
+ * Returns the active elevated token when it meets the requested freshness.
+ *
+ * @param request - Optional maximum session age in milliseconds, measured
+ * from when the token was obtained. Zero always requires a new ceremony.
+ * @returns A live elevated token, or null when no reusable session exists.
+ */
+export type AuthenticationControllerGetElevatedProfileTokenAction = {
+    type: `AuthenticationController:getElevatedProfileToken`;
+    handler: AuthenticationController['getElevatedProfileToken'];
+};
+/**
+ * Clears the in-memory elevated session and its expiration timer.
+ */
+export type AuthenticationControllerClearStepUpSessionAction = {
+    type: `AuthenticationController:clearStepUpSession`;
+    handler: AuthenticationController['clearStepUpSession'];
+};
 export type AuthenticationControllerPerformSignOutAction = {
     type: `AuthenticationController:performSignOut`;
     handler: AuthenticationController['performSignOut'];
@@ -160,5 +202,5 @@ export type AuthenticationControllerIsSignedInAction = {
 /**
  * Union of all AuthenticationController action types.
  */
-export type AuthenticationControllerMethodActions = AuthenticationControllerPerformSignInAction | AuthenticationControllerRequestProfilePairingAction | AuthenticationControllerRefreshEnrolledCredentialsAction | AuthenticationControllerBeginCredentialEnrollmentAction | AuthenticationControllerCompleteCredentialEnrollmentAction | AuthenticationControllerPerformSignOutAction | AuthenticationControllerClearStateAction | AuthenticationControllerGetBearerTokenAction | AuthenticationControllerGetSessionProfileAction | AuthenticationControllerRefreshCanonicalProfileIdAction | AuthenticationControllerGetUserProfileLineageAction | AuthenticationControllerGetCustomerServiceTokenAction | AuthenticationControllerGetPartnerIdentityTokenAction | AuthenticationControllerIsSignedInAction;
+export type AuthenticationControllerMethodActions = AuthenticationControllerPerformSignInAction | AuthenticationControllerRequestProfilePairingAction | AuthenticationControllerRefreshEnrolledCredentialsAction | AuthenticationControllerBeginCredentialEnrollmentAction | AuthenticationControllerCompleteCredentialEnrollmentAction | AuthenticationControllerBeginStepUpAction | AuthenticationControllerCompleteStepUpAction | AuthenticationControllerGetElevatedProfileTokenAction | AuthenticationControllerClearStepUpSessionAction | 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":"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"}
+{"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\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"]}
+{"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\n/**\n * Begins step-up verification with an enrolled credential.\n *\n * @param request - Credential type and trace reason.\n * @returns A challenge for the client-owned ceremony.\n */\nexport type AuthenticationControllerBeginStepUpAction = {\n  type: `AuthenticationController:beginStepUp`;\n  handler: AuthenticationController['beginStepUp'];\n};\n\n/**\n * Completes step-up verification and opens a short-lived elevated session.\n *\n * The AAL2 assertion returned by the MFA service is exchanged at Hydra for\n * an elevated access token, whose claims are checked before the session\n * opens. The token itself never enters controller state.\n *\n * @param request - Flow identifier, platform or email proof, and trace reason.\n * @returns The elevated profile access token.\n */\nexport type AuthenticationControllerCompleteStepUpAction = {\n  type: `AuthenticationController:completeStepUp`;\n  handler: AuthenticationController['completeStepUp'];\n};\n\n/**\n * Returns the active elevated token when it meets the requested freshness.\n *\n * @param request - Optional maximum session age in milliseconds, measured\n * from when the token was obtained. Zero always requires a new ceremony.\n * @returns A live elevated token, or null when no reusable session exists.\n */\nexport type AuthenticationControllerGetElevatedProfileTokenAction = {\n  type: `AuthenticationController:getElevatedProfileToken`;\n  handler: AuthenticationController['getElevatedProfileToken'];\n};\n\n/**\n * Clears the in-memory elevated session and its expiration timer.\n */\nexport type AuthenticationControllerClearStepUpSessionAction = {\n  type: `AuthenticationController:clearStepUpSession`;\n  handler: AuthenticationController['clearStepUpSession'];\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  | AuthenticationControllerBeginStepUpAction\n  | AuthenticationControllerCompleteStepUpAction\n  | AuthenticationControllerGetElevatedProfileTokenAction\n  | AuthenticationControllerClearStepUpSessionAction\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

@@ -4,7 +4,7 @@ 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, BeginEnrollmentRequest, CompleteEnrollmentRequest, EnrolledCredential, EnrollmentChallenge } from '../../sdk/index.js';
+import type { LoginResponse, ProfileAlias, UserProfile, UserProfileLineage, OidcTokenAudience, OidcTokenClaims, BeginEnrollmentRequest, CompleteEnrollmentRequest, EnrolledCredential, EnrollmentChallenge, BeginStepUpRequest, CompleteStepUpRequest, ElevatedProfileToken, GetElevatedTokenRequest, StepUpChallenge } 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';
@@ -18,6 +18,11 @@ export type AuthenticationControllerState = {
      * assignable to the controller state type.
      */
     enrolledCredentials?: EnrolledCredential[];
+    /**
+     * Epoch-ms hard expiry of the in-memory elevated session, or undefined when
+     * none is open. Lets UI show "verified" state without holding the token.
+     */
+    stepUpSessionExpiresAt?: number;
     /**
      * Client gate for profile pairing. Defaults to `true` (fresh install /
      * upgrade), set to `false` after a successful `performSignIn` pair, set
@@ -45,6 +50,12 @@ export type AuthenticationControllerState = {
     needsSocialPairing?: boolean;
 };
 export declare const defaultState: AuthenticationControllerState;
+/**
+ * Lifetime of an elevated session. Deliberately shorter than the
+ * elevated token's own `exp` so a fresh ceremony is required per sensitive
+ * action window, per the MFA phase-1 specification.
+ */
+export declare const STEP_UP_SESSION_TTL_MS = 60000;
 type ControllerConfig = {
     env: Env;
     /**
@@ -122,6 +133,36 @@ export declare class AuthenticationController extends BaseController<typeof cont
      * @returns The refreshed credentials, or the existing cache if refresh fails.
      */
     completeCredentialEnrollment(request: CompleteEnrollmentRequest): Promise<EnrolledCredential[]>;
+    /**
+     * Begins step-up verification with an enrolled credential.
+     *
+     * @param request - Credential type and trace reason.
+     * @returns A challenge for the client-owned ceremony.
+     */
+    beginStepUp(request: BeginStepUpRequest): Promise<StepUpChallenge>;
+    /**
+     * Completes step-up verification and opens a short-lived elevated session.
+     *
+     * The AAL2 assertion returned by the MFA service is exchanged at Hydra for
+     * an elevated access token, whose claims are checked before the session
+     * opens. The token itself never enters controller state.
+     *
+     * @param request - Flow identifier, platform or email proof, and trace reason.
+     * @returns The elevated profile access token.
+     */
+    completeStepUp(request: CompleteStepUpRequest): Promise<ElevatedProfileToken>;
+    /**
+     * Returns the active elevated token when it meets the requested freshness.
+     *
+     * @param request - Optional maximum session age in milliseconds, measured
+     * from when the token was obtained. Zero always requires a new ceremony.
+     * @returns A live elevated token, or null when no reusable session exists.
+     */
+    getElevatedProfileToken(request?: GetElevatedTokenRequest): ElevatedProfileToken | null;
+    /**
+     * Clears the in-memory elevated session and its expiration timer.
+     */
+    clearStepUpSession(): void;
     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":"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"}
+{"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,7 +1,9 @@
 import { BaseController } from '@metamask/base-controller';
 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 { BeginEnrollmentRequestStruct, CompleteEnrollmentRequestStruct, assertValidMfaRequest, BeginStepUpRequestStruct, CompleteStepUpRequestStruct, GetElevatedTokenRequestStruct, parseElevatedTokenClaims, } from '../../sdk/authentication-jwt-bearer/mfa/schemas.js';
+import { assertMessageStartsWithMetamask, AuthType, Env, JwtBearerAuth, PairConflictError, getMfaErrorCode, ElevatedTokenInvalidError, } from '../../sdk/index.js';
+import { decodeJwtPayload } from '../../sdk/utils/jwt.js';
+import { toErrorMessage } from '../../sdk/utils/to-error-message.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';
@@ -66,7 +68,19 @@ const metadata = {
         includeInDebugSnapshot: false,
         usedInUi: true,
     },
+    stepUpSessionExpiresAt: {
+        includeInStateLogs: false,
+        persist: false,
+        includeInDebugSnapshot: false,
+        usedInUi: true,
+    },
 };
+/**
+ * Lifetime of an elevated session. Deliberately shorter than the
+ * elevated token's own `exp` so a fresh ceremony is required per sensitive
+ * action window, per the MFA phase-1 specification.
+ */
+export const STEP_UP_SESSION_TTL_MS = 60_000;
 const MESSENGER_EXPOSED_METHODS = [
     'performSignIn',
     'performSignOut',
@@ -82,6 +96,10 @@ const MESSENGER_EXPOSED_METHODS = [
     'refreshEnrolledCredentials',
     'beginCredentialEnrollment',
     'completeCredentialEnrollment',
+    'beginStepUp',
+    'completeStepUp',
+    'getElevatedProfileToken',
+    'clearStepUpSession',
 ];
 /**
  * Controller that enables authentication for restricted endpoints.
@@ -101,6 +119,8 @@ export class AuthenticationController extends BaseController {
      * ceremony started under the previous session cannot apply its result.
      */
     #authSessionEpoch = 0;
+    #stepUpSession = null;
+    #stepUpTimer;
     /**
      * Sequence number of the most recently started credentials refresh. Only
      * that refresh may write the cache, so a slower, earlier request cannot
@@ -123,6 +143,7 @@ export class AuthenticationController extends BaseController {
             this.messenger.subscribe('KeyringController:lock', () => {
                 this.#authSessionEpoch += 1;
                 this.#isUnlocked = false;
+                this.clearStepUpSession();
             });
         },
     };
@@ -136,9 +157,10 @@ export class AuthenticationController extends BaseController {
         if (!metametrics) {
             throw new Error('`metametrics` field is required');
         }
+        // `??` per key so an explicit `undefined` keeps the default rather than
+        // clobbering it.
         this.#config = {
-            ...this.#config,
-            ...config,
+            env: config?.env ?? this.#config.env,
             isSocialPairingEnabled: config?.isSocialPairingEnabled ?? this.#config.isSocialPairingEnabled,
         };
         this.#metametrics = metametrics;
@@ -539,27 +561,43 @@ export class AuthenticationController extends BaseController {
      * @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 () => {
+        }, async (context) => {
             try {
                 const result = await fn();
-                data.outcome = 'success';
+                this.#setTraceAttribute(context, 'outcome', 'success');
                 return result;
             }
             catch (error) {
-                data.outcome = 'error';
+                this.#setTraceAttribute(context, 'outcome', 'error');
                 const mfaCode = getMfaErrorCode(error);
                 if (mfaCode) {
-                    data.mfaErrorCode = mfaCode;
+                    this.#setTraceAttribute(context, 'mfaErrorCode', mfaCode);
+                    if (mfaCode === 'authentication_required' && this.#isUnlocked) {
+                        this.#invalidateSrpSession(this.#getPrimaryEntropySourceId());
+                        // An elevated session must not outlive a rejected base session.
+                        this.clearStepUpSession();
+                    }
                 }
                 throw error;
             }
         });
     }
+    /**
+     * `TraceContext` is opaque in `@metamask/controller-utils`; both clients
+     * hand back a Sentry span, so attributes are set via duck typing and a
+     * non-Sentry context is a silent no-op.
+     *
+     * @param context - Span handed to the trace callback, if any.
+     * @param key - Attribute name.
+     * @param value - Attribute value.
+     */
+    #setTraceAttribute(context, key, value) {
+        const traceSpan = context;
+        traceSpan?.setAttribute?.(key, value);
+    }
     /**
      * Refreshes credentials enrolled on the canonical profile.
      *
@@ -599,9 +637,13 @@ export class AuthenticationController extends BaseController {
         const sessionEpoch = this.#authSessionEpoch;
         assertValidMfaRequest(request, BeginEnrollmentRequestStruct);
         const primaryEntropySourceId = this.#getPrimaryEntropySourceId();
+        // Enrolling beyond the first credential requires AAL2: send the elevated
+        // token while a session is live and let the server decide.
+        const accessToken = this.getElevatedProfileToken()?.accessToken;
         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,
+            accessToken,
         }));
         this.#assertAuthSessionEpoch(sessionEpoch, 'beginCredentialEnrollment');
         return challenge;
@@ -636,6 +678,8 @@ export class AuthenticationController extends BaseController {
             }
             throw error;
         }
+        // The factor set changed: require a fresh ceremony against the new set.
+        this.clearStepUpSession();
         try {
             return await this.refreshEnrolledCredentials();
         }
@@ -648,6 +692,117 @@ export class AuthenticationController extends BaseController {
             }
         }
     }
+    /**
+     * Begins step-up verification with an enrolled credential.
+     *
+     * @param request - Credential type and trace reason.
+     * @returns A challenge for the client-owned ceremony.
+     */
+    async beginStepUp(request) {
+        this.#assertIsUnlocked('beginStepUp');
+        const sessionEpoch = this.#authSessionEpoch;
+        assertValidMfaRequest(request, BeginStepUpRequestStruct);
+        const primaryEntropySourceId = this.#getPrimaryEntropySourceId();
+        const challenge = await this.#runMfaRequest('MFA Step-Up Begin', request.reason.operation, request.type, async () => await this.#auth.beginMfaVerification(request.type, primaryEntropySourceId));
+        this.#assertAuthSessionEpoch(sessionEpoch, 'beginStepUp');
+        return challenge;
+    }
+    /**
+     * Completes step-up verification and opens a short-lived elevated session.
+     *
+     * The AAL2 assertion returned by the MFA service is exchanged at Hydra for
+     * an elevated access token, whose claims are checked before the session
+     * opens. The token itself never enters controller state.
+     *
+     * @param request - Flow identifier, platform or email proof, and trace reason.
+     * @returns The elevated profile access token.
+     */
+    async completeStepUp(request) {
+        this.#assertIsUnlocked('completeStepUp');
+        const sessionEpoch = this.#authSessionEpoch;
+        assertValidMfaRequest(request, CompleteStepUpRequestStruct);
+        const { type } = request.proof;
+        const { operation } = request.reason;
+        const primaryEntropySourceId = this.#getPrimaryEntropySourceId();
+        const assertion = await this.#runMfaRequest('MFA Step-Up Complete', operation, type, async () => await this.#auth.completeMfaVerification(request.flowId, request.proof, primaryEntropySourceId));
+        this.#assertAuthSessionEpoch(sessionEpoch, 'completeStepUp');
+        const accessToken = await this.#runMfaRequest('MFA Token Exchange', operation, type, async () => await this.#auth.exchangeMfaAssertion(assertion.token));
+        this.#assertAuthSessionEpoch(sessionEpoch, 'completeStepUp');
+        let decodedClaims;
+        try {
+            decodedClaims = decodeJwtPayload(accessToken.accessToken);
+        }
+        catch (error) {
+            throw new ElevatedTokenInvalidError(toErrorMessage(error));
+        }
+        const claims = parseElevatedTokenClaims(decodedClaims);
+        if (claims.exp * 1000 <= Date.now()) {
+            throw new ElevatedTokenInvalidError('Elevated token is expired');
+        }
+        const token = { ...accessToken, claims };
+        this.#openStepUpSession(token);
+        return token;
+    }
+    /**
+     * Returns the active elevated token when it meets the requested freshness.
+     *
+     * @param request - Optional maximum session age in milliseconds, measured
+     * from when the token was obtained. Zero always requires a new ceremony.
+     * @returns A live elevated token, or null when no reusable session exists.
+     */
+    getElevatedProfileToken(request = {}) {
+        this.#assertIsUnlocked('getElevatedProfileToken');
+        assertValidMfaRequest(request, GetElevatedTokenRequestStruct);
+        const session = this.#stepUpSession;
+        if (!session) {
+            return null;
+        }
+        const now = Date.now();
+        if (now >= session.expiresAt) {
+            // The hard-expiry timer has not fired yet (e.g. a suspended tab).
+            this.clearStepUpSession();
+            return null;
+        }
+        // `>=` so a zero max age always forces a fresh ceremony. Not cleared: the
+        // max age is this caller's requirement; others may still use the session.
+        const maxAge = request.maxSessionAgeMs;
+        if (maxAge !== undefined && now - session.token.obtainedAt >= maxAge) {
+            return null;
+        }
+        return session.token;
+    }
+    /**
+     * Opens the elevated session. Its lifetime is the session TTL clamped to
+     * the token's own `exp`, so the session never outlives the token.
+     *
+     * @param token - The freshly exchanged elevated token.
+     */
+    #openStepUpSession(token) {
+        this.clearStepUpSession();
+        const expiresAt = Math.min(token.obtainedAt + STEP_UP_SESSION_TTL_MS, token.claims.exp * 1000);
+        this.#stepUpSession = { token, expiresAt };
+        this.update((state) => {
+            state.stepUpSessionExpiresAt = expiresAt;
+        });
+        this.#stepUpTimer = setTimeout(() => this.clearStepUpSession(), Math.max(0, expiresAt - Date.now()));
+        // Never keep a Node process alive for the expiry timer (tests, tooling).
+        this.#stepUpTimer.unref?.();
+    }
+    /**
+     * Clears the in-memory elevated session and its expiration timer.
+     */
+    clearStepUpSession() {
+        if (this.#stepUpTimer !== undefined) {
+            clearTimeout(this.#stepUpTimer);
+            this.#stepUpTimer = undefined;
+        }
+        this.#stepUpSession = null;
+        if (this.state.stepUpSessionExpiresAt !== undefined) {
+            this.update((state) => {
+                state.stepUpSessionExpiresAt = undefined;
+            });
+        }
+    }
     /**
      * Drops the cached credential list. Callers that wipe profile state must go
      * through this so subscribers never keep credentials belonging to a profile
@@ -666,6 +821,7 @@ export class AuthenticationController extends BaseController {
     }
     performSignOut() {
         this.#authSessionEpoch += 1;
+        this.clearStepUpSession();
         this.#clearEnrolledCredentials();
         this.update((state) => {
             state.isSignedIn = false;
@@ -679,6 +835,7 @@ export class AuthenticationController extends BaseController {
     clearState() {
         this.#profilePairingRequestEpoch += 1;
         this.#authSessionEpoch += 1;
+        this.clearStepUpSession();
         this.#clearEnrolledCredentials();
         this.update(() => ({ ...defaultState }));
     }