@metamask/profile-sync-controller 32.3.1 → 34.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,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.
+ * 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 STEP_UP_SESSION_TTL_MS = 60_000;
+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 +98,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 +121,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
@@ -135,6 +139,10 @@ export class AuthenticationController extends BaseController {
      * `performSignIn` can't clear `needsProfilePairing` afterwards.
      */
     #profilePairingRequestEpoch = 0;
+    /**
+     * Sign-in currently running. Overlapping callers share it.
+     */
+    #ongoingSignIn;
     #keyringController = {
         setupLockedStateSubscriptions: () => {
             const { isUnlocked } = this.messenger.call('KeyringController:getState');
@@ -145,7 +153,7 @@ export class AuthenticationController extends BaseController {
             this.messenger.subscribe('KeyringController:lock', () => {
                 this.#authSessionEpoch += 1;
                 this.#isUnlocked = false;
-                this.clearStepUpSession();
+                this.clearVerificationSession();
             });
         },
     };
@@ -337,6 +345,18 @@ export class AuthenticationController extends BaseController {
     }
     async performSignIn() {
         this.#assertIsUnlocked('performSignIn');
+        if (this.#ongoingSignIn) {
+            return await this.#ongoingSignIn;
+        }
+        const signIn = this.#runPerformSignIn().finally(() => {
+            if (this.#ongoingSignIn === signIn) {
+                this.#ongoingSignIn = undefined;
+            }
+        });
+        this.#ongoingSignIn = signIn;
+        return await signIn;
+    }
+    async #runPerformSignIn() {
         const epochAtStart = this.#profilePairingRequestEpoch;
         const entropySourceIds = this.#getHdKeyringEntropySourceIds();
         const accessTokens = [];
@@ -604,8 +624,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 +685,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,
@@ -678,6 +703,11 @@ export class AuthenticationController extends BaseController {
     /**
      * Completes credential enrollment and refreshes the credential cache.
      *
+     * The server returns an assertion for the new credential, which opens a
+     * verification session like `completeCredentialVerification`, replacing
+     * any earlier one. If that exchange fails, the earlier session is kept:
+     * the credential is enrolled either way.
+     *
      * 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
@@ -694,8 +724,22 @@ export class AuthenticationController extends BaseController {
         const sessionEpoch = this.#authSessionEpoch;
         assertValidMfaRequest(request, CompleteEnrollmentRequestStruct);
         const { type } = request.proof;
+        const { operation } = request.reason;
         const primaryEntropySourceId = this.#getPrimaryEntropySourceId();
-        await this.#runMfaRequest('MFA Enroll Complete', request.reason.operation, type, async () => await this.#auth.completeMfaEnrollment(request.flowId, request.proof, primaryEntropySourceId));
+        const assertion = await this.#runMfaRequest('MFA Enroll Complete', operation, type, async () => await this.#auth.completeMfaEnrollment(request.flowId, request.proof, primaryEntropySourceId));
+        try {
+            await this.#openVerificationSessionFromAssertion(assertion, {
+                operation,
+                type,
+                sessionEpoch,
+                methodName: 'completeCredentialEnrollment',
+            });
+        }
+        catch {
+            // Callers see no session and verify the credential instead.
+        }
+        // Also catches a session that ended during the enrollment request; the
+        // exchange above then ran for nothing, and its session was never opened.
         try {
             this.#assertAuthSessionEpoch(sessionEpoch, 'completeCredentialEnrollment');
         }
@@ -705,8 +749,6 @@ 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();
         }
@@ -720,74 +762,103 @@ 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');
+        return await this.#openVerificationSessionFromAssertion(assertion, {
+            operation,
+            type,
+            sessionEpoch,
+            methodName: 'completeCredentialVerification',
+        });
+    }
+    /**
+     * Exchanges an MFA assertion at Hydra and opens the verification session
+     * with the resulting token.
+     *
+     * @param assertion - Assertion returned by a verify or enroll completion.
+     * @param context - Trace tags and the session the call started in.
+     * @param context.operation - Feature operation, for tracing.
+     * @param context.type - Credential type the assertion proves, for tracing.
+     * @param context.sessionEpoch - Authenticated session the call started in.
+     * @param context.methodName - Public method name, for error messages.
+     * @returns The verification token.
+     */
+    async #openVerificationSessionFromAssertion(assertion, { operation, type, sessionEpoch, methodName, }) {
         const accessToken = await this.#runMfaRequest('MFA Token Exchange', operation, type, async () => await this.#auth.exchangeMfaAssertion(assertion.token));
-        this.#assertAuthSessionEpoch(sessionEpoch, 'completeStepUp');
+        this.#assertAuthSessionEpoch(sessionEpoch, methodName);
         let decodedClaims;
         try {
             decodedClaims = decodeJwtPayload(accessToken.accessToken);
         }
         catch (error) {
-            throw new ElevatedTokenInvalidError(toErrorMessage(error));
+            throw new VerificationTokenInvalidError(toErrorMessage(error));
         }
-        const claims = parseElevatedTokenClaims(decodedClaims);
-        if (claims.exp * 1000 <= Date.now()) {
-            throw new ElevatedTokenInvalidError('Elevated token is expired');
+        const claims = parseVerificationTokenClaims(decodedClaims);
+        if (!Number.isFinite(accessToken.expiresIn) || accessToken.expiresIn <= 0) {
+            throw new VerificationTokenInvalidError('Verification token has no remaining lifetime');
         }
         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.
+     *
+     * Low-level: features should go through the client MFA kit
+     * (`verifyOrEnroll`), which reuses a matching session without showing any
+     * screen and checks which method proved it. Read the token directly only
+     * from code that cannot show UI, and treat `null` as "let the UI layer
+     * ask".
      *
      * @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 +870,41 @@ export class AuthenticationController extends BaseController {
         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.
+     * Opens the verification session for the lifetime the server gave the token.
+     * It is measured from `expires_in` on the local clock rather than read from
+     * `exp`, so a skewed device clock cannot shorten or extend it.
      *
-     * @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 = token.obtainedAt + token.expiresIn * 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 +924,7 @@ export class AuthenticationController extends BaseController {
     }
     performSignOut() {
         this.#authSessionEpoch += 1;
-        this.clearStepUpSession();
+        this.clearVerificationSession();
         this.#clearEnrolledCredentials();
         this.update((state) => {
             state.isSignedIn = false;
@@ -862,7 +938,7 @@ export class AuthenticationController extends BaseController {
     clearState() {
         this.#profilePairingRequestEpoch += 1;
         this.#authSessionEpoch += 1;
-        this.clearStepUpSession();
+        this.clearVerificationSession();
         this.#clearEnrolledCredentials();
         this.update(() => ({ ...defaultState }));
     }