@metamask/profile-sync-controller 32.3.1 → 33.0.0

package/dist/controllers/authentication/AuthenticationController.js

@@ -1,7 +1,7 @@
 import { BaseController } from '@metamask/base-controller';
 import { selectHdKeyringEntropySourceIds } from '@metamask/keyring-controller';
-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 { BeginEnrollmentRequestStruct, CompleteEnrollmentRequestStruct, assertValidMfaRequest, BeginVerificationRequestStruct, CompleteVerificationRequestStruct, GetVerificationTokenRequestStruct, parseVerificationTokenClaims, } from '../../sdk/authentication-jwt-bearer/mfa/schemas.js';
+import { assertMessageStartsWithMetamask, AuthType, Env, JwtBearerAuth, PairConflictError, getMfaErrorCode, VerificationTokenInvalidError, } 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';
@@ -70,19 +70,27 @@ 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.
+ * Upper bound on a verification session's lifetime. The session also ends at
+ * the verification token's own `exp` (15 minutes today), whichever comes
+ * first, so this only matters if the server ever issues longer-lived tokens.
+ * Callers needing a fresher proof pass `maxSessionAgeMs` to
+ * `getVerificationToken`.
  */
-export const STEP_UP_SESSION_TTL_MS = 60_000;
+export const VERIFICATION_SESSION_TTL_MS = 15 * 60_000;
+/**
+ * Default maximum age of a verification session that may authorize enrolling a
+ * credential. A session opened for an unrelated operation must not be able to
+ * add a factor long after the fact, while a session proven moments ago (or
+ * during the same setup flow, via `maxSessionAgeMs`) may.
+ */
+export const ENROLLMENT_MAX_SESSION_AGE_MS = 2 * 60_000;
+/**
+ * Key of the only verification session held today. Sessions are keyed by token
+ * audience so audience-scoped tokens can be added without reshaping storage.
+ */
+const DEFAULT_AUDIENCE = '';
 const MESSENGER_EXPOSED_METHODS = [
     'performSignIn',
     'performSignOut',
@@ -98,10 +106,10 @@ const MESSENGER_EXPOSED_METHODS = [
     'refreshEnrolledCredentials',
     'beginCredentialEnrollment',
     'completeCredentialEnrollment',
-    'beginStepUp',
-    'completeStepUp',
-    'getElevatedProfileToken',
-    'clearStepUpSession',
+    'beginCredentialVerification',
+    'completeCredentialVerification',
+    'getVerificationToken',
+    'clearVerificationSession',
 ];
 /**
  * Controller that enables authentication for restricted endpoints.
@@ -121,8 +129,12 @@ export class AuthenticationController extends BaseController {
      * ceremony started under the previous session cannot apply its result.
      */
     #authSessionEpoch = 0;
-    #stepUpSession = null;
-    #stepUpTimer;
+    /**
+     * Verification sessions keyed by token audience. At most one session per
+     * audience; only `DEFAULT_AUDIENCE` is used until audience-scoped tokens
+     * exist.
+     */
+    #verificationSessions = new Map();
     /**
      * Sequence number of the most recently started credentials refresh. Only
      * that refresh may write the cache, so a slower, earlier request cannot
@@ -145,7 +157,7 @@ export class AuthenticationController extends BaseController {
             this.messenger.subscribe('KeyringController:lock', () => {
                 this.#authSessionEpoch += 1;
                 this.#isUnlocked = false;
-                this.clearStepUpSession();
+                this.clearVerificationSession();
             });
         },
     };
@@ -604,8 +616,9 @@ export class AuthenticationController extends BaseController {
                     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();
+                        // A verification session must not outlive a rejected base
+                        // session.
+                        this.clearVerificationSession();
                     }
                 }
                 throw error;
@@ -664,9 +677,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;
+        // The server requires AAL2 to add a credential once one that proves AAL2
+        // exists: send the verification token only while a recent enough session
+        // is live and let the server decide. An older session stays open for
+        // other consumers.
+        const accessToken = this.getVerificationToken({
+            maxSessionAgeMs: request.maxSessionAgeMs ?? ENROLLMENT_MAX_SESSION_AGE_MS,
+        })?.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,
@@ -705,8 +722,9 @@ export class AuthenticationController extends BaseController {
             }
             throw error;
         }
-        // The factor set changed: require a fresh ceremony against the new set.
-        this.clearStepUpSession();
+        // The verification session is deliberately kept: adding a factor does not
+        // weaken an earlier proof, and `beginCredentialEnrollment` already limits
+        // which sessions may add the next one.
         try {
             return await this.refreshEnrolledCredentials();
         }
@@ -720,74 +738,77 @@ export class AuthenticationController extends BaseController {
         }
     }
     /**
-     * Begins step-up verification with an enrolled credential.
+     * Begins 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');
+    async beginCredentialVerification(request) {
+        this.#assertIsUnlocked('beginCredentialVerification');
         const sessionEpoch = this.#authSessionEpoch;
-        assertValidMfaRequest(request, BeginStepUpRequestStruct);
+        assertValidMfaRequest(request, BeginVerificationRequestStruct);
         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');
+        const challenge = await this.#runMfaRequest('MFA Verification Begin', request.reason.operation, request.type, async () => await this.#auth.beginMfaVerification(request.type, primaryEntropySourceId));
+        this.#assertAuthSessionEpoch(sessionEpoch, 'beginCredentialVerification');
         return challenge;
     }
     /**
-     * Completes step-up verification and opens a short-lived elevated session.
+     * Completes verification and opens a short-lived verification 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.
+     * The assertion returned by the MFA service is exchanged at Hydra for an
+     * access token. Its assurance level is not checked: the services receiving
+     * the token enforce their own requirements. The token itself never enters
+     * controller state.
      *
      * @param request - Flow identifier, platform or email proof, and trace reason.
-     * @returns The elevated profile access token.
+     * @returns The verification token.
      */
-    async completeStepUp(request) {
-        this.#assertIsUnlocked('completeStepUp');
+    async completeCredentialVerification(request) {
+        this.#assertIsUnlocked('completeCredentialVerification');
         const sessionEpoch = this.#authSessionEpoch;
-        assertValidMfaRequest(request, CompleteStepUpRequestStruct);
+        assertValidMfaRequest(request, CompleteVerificationRequestStruct);
         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 assertion = await this.#runMfaRequest('MFA Verification Complete', operation, type, async () => await this.#auth.completeMfaVerification(request.flowId, request.proof, primaryEntropySourceId));
+        this.#assertAuthSessionEpoch(sessionEpoch, 'completeCredentialVerification');
         const accessToken = await this.#runMfaRequest('MFA Token Exchange', operation, type, async () => await this.#auth.exchangeMfaAssertion(assertion.token));
-        this.#assertAuthSessionEpoch(sessionEpoch, 'completeStepUp');
+        this.#assertAuthSessionEpoch(sessionEpoch, 'completeCredentialVerification');
         let decodedClaims;
         try {
             decodedClaims = decodeJwtPayload(accessToken.accessToken);
         }
         catch (error) {
-            throw new ElevatedTokenInvalidError(toErrorMessage(error));
+            throw new VerificationTokenInvalidError(toErrorMessage(error));
         }
-        const claims = parseElevatedTokenClaims(decodedClaims);
+        const claims = parseVerificationTokenClaims(decodedClaims);
         if (claims.exp * 1000 <= Date.now()) {
-            throw new ElevatedTokenInvalidError('Elevated token is expired');
+            throw new VerificationTokenInvalidError('Verification token is expired');
         }
         const token = { ...accessToken, claims };
-        this.#openStepUpSession(token);
+        this.#openVerificationSession(token);
         return token;
     }
     /**
-     * Returns the active elevated token when it meets the requested freshness.
+     * Returns the active verification 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.
+     * @returns A live verification token, or null when no reusable session
+     * exists.
      */
-    getElevatedProfileToken(request = {}) {
-        this.#assertIsUnlocked('getElevatedProfileToken');
-        assertValidMfaRequest(request, GetElevatedTokenRequestStruct);
-        const session = this.#stepUpSession;
+    getVerificationToken(request = {}) {
+        this.#assertIsUnlocked('getVerificationToken');
+        assertValidMfaRequest(request, GetVerificationTokenRequestStruct);
+        const session = this.#verificationSessions.get(DEFAULT_AUDIENCE);
         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();
+            this.#dropVerificationSession(DEFAULT_AUDIENCE);
             return null;
         }
         // `>=` so a zero max age always forces a fresh ceremony. Not cleared: the
@@ -799,36 +820,40 @@ export class AuthenticationController extends BaseController {
         return session.token;
     }
     /**
-     * Opens the elevated session. Its lifetime is the session TTL clamped to
+     * Opens the verification 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.
+     * @param token - The freshly exchanged verification 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()));
+    #openVerificationSession(token) {
+        const audience = DEFAULT_AUDIENCE;
+        this.#dropVerificationSession(audience);
+        const expiresAt = Math.min(token.obtainedAt + VERIFICATION_SESSION_TTL_MS, token.claims.exp * 1000);
+        const timer = setTimeout(() => this.#dropVerificationSession(audience), Math.max(0, expiresAt - Date.now()));
         // Never keep a Node process alive for the expiry timer (tests, tooling).
-        this.#stepUpTimer.unref?.();
+        timer.unref?.();
+        this.#verificationSessions.set(audience, { token, expiresAt, timer });
     }
     /**
-     * Clears the in-memory elevated session and its expiration timer.
+     * Drops one audience's verification session and its expiration timer.
+     *
+     * @param audience - Audience whose session to drop.
      */
-    clearStepUpSession() {
-        if (this.#stepUpTimer !== undefined) {
-            clearTimeout(this.#stepUpTimer);
-            this.#stepUpTimer = undefined;
+    #dropVerificationSession(audience) {
+        const session = this.#verificationSessions.get(audience);
+        if (session) {
+            clearTimeout(session.timer);
+            this.#verificationSessions.delete(audience);
         }
-        this.#stepUpSession = null;
-        if (this.state.stepUpSessionExpiresAt !== undefined) {
-            this.update((state) => {
-                state.stepUpSessionExpiresAt = undefined;
-            });
+    }
+    /**
+     * Clears every in-memory verification session and its expiration timer.
+     */
+    clearVerificationSession() {
+        for (const { timer } of this.#verificationSessions.values()) {
+            clearTimeout(timer);
         }
+        this.#verificationSessions.clear();
     }
     /**
      * Drops the cached credential list. Callers that wipe profile state must go
@@ -848,7 +873,7 @@ export class AuthenticationController extends BaseController {
     }
     performSignOut() {
         this.#authSessionEpoch += 1;
-        this.clearStepUpSession();
+        this.clearVerificationSession();
         this.#clearEnrolledCredentials();
         this.update((state) => {
             state.isSignedIn = false;
@@ -862,7 +887,7 @@ export class AuthenticationController extends BaseController {
     clearState() {
         this.#profilePairingRequestEpoch += 1;
         this.#authSessionEpoch += 1;
-        this.clearStepUpSession();
+        this.clearVerificationSession();
         this.#clearEnrolledCredentials();
         this.update(() => ({ ...defaultState }));
     }