@metamask/profile-sync-controller 32.1.1 → 32.2.0

package/dist/controllers/authentication/AuthenticationController.js

@@ -1,11 +1,16 @@
 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, 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';
 const controllerName = 'AuthenticationController';
 export const defaultState = {
     isSignedIn: false,
+    enrolledCredentials: [],
     needsProfilePairing: true,
     needsSocialPairing: true,
 };
@@ -52,7 +57,30 @@ 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,
+    },
+    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',
@@ -65,6 +93,13 @@ const MESSENGER_EXPOSED_METHODS = [
     'isSignedIn',
     'requestProfilePairing',
     'clearState',
+    'refreshEnrolledCredentials',
+    'beginCredentialEnrollment',
+    'completeCredentialEnrollment',
+    'beginStepUp',
+    'completeStepUp',
+    'getElevatedProfileToken',
+    'clearStepUpSession',
 ];
 /**
  * Controller that enables authentication for restricted endpoints.
@@ -73,11 +108,26 @@ 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;
+    #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
+     * 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 +141,13 @@ export class AuthenticationController extends BaseController {
                 this.#isUnlocked = true;
             });
             this.messenger.subscribe('KeyringController:lock', () => {
+                this.#authSessionEpoch += 1;
                 this.#isUnlocked = false;
+                this.clearStepUpSession();
             });
         },
     };
-    constructor({ messenger, state, config, metametrics, }) {
+    constructor({ messenger, state, config, metametrics, trace, }) {
         super({
             messenger,
             metadata,
@@ -105,12 +157,14 @@ 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;
+        this.#trace = trace ?? ((_request, fn) => fn?.());
         this.#auth = new JwtBearerAuth({
             env: this.#config.env,
             platform: metametrics.agent,
@@ -160,14 +214,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 +238,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 +549,276 @@ 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) {
+        return await this.#trace({
+            name,
+            tags: { operation, credentialType },
+        }, async (context) => {
+            try {
+                const result = await fn();
+                this.#setTraceAttribute(context, 'outcome', 'success');
+                return result;
+            }
+            catch (error) {
+                this.#setTraceAttribute(context, 'outcome', 'error');
+                const mfaCode = getMfaErrorCode(error);
+                if (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.
+     *
+     * @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;
+        }
+        // The factor set changed: require a fresh ceremony against the new set.
+        this.clearStepUpSession();
+        try {
+            return await this.refreshEnrolledCredentials();
+        }
+        catch {
+            return this.#getEnrolledCredentials();
+        }
+        finally {
+            if (type === 'email_otp') {
+                this.#invalidateSrpSession(primaryEntropySourceId);
+            }
+        }
+    }
+    /**
+     * 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
+     * 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.clearStepUpSession();
+        this.#clearEnrolledCredentials();
         this.update((state) => {
             state.isSignedIn = false;
             state.srpSessionData = undefined;
@@ -502,6 +830,9 @@ export class AuthenticationController extends BaseController {
      */
     clearState() {
         this.#profilePairingRequestEpoch += 1;
+        this.#authSessionEpoch += 1;
+        this.clearStepUpSession();
+        this.#clearEnrolledCredentials();
         this.update(() => ({ ...defaultState }));
     }
     /**