task(settings): Create Mfa Guard and Error Boundary

Because:
- We want to wrap certain pages with an MFA requirement

This Commit:
- Updates the cache to hold a JWT
- Creates a guard component that invokes the MFA Modal if the JWT is missing
- Creates an error boundary that clears invalid or expired JWTs

Author: dschom

packages/functional-tests/tests/misc/mfa.spec.ts

@@ -19,29 +19,33 @@ test.describe('severity-2 #smoke', () => {
   }) => {
     const credentials = await testAccountTracker.signUpSync();
     const client = target.createAuthClient(2);
-    let resp = await client.mfaRequestOtp(credentials.sessionToken, 'test');
-    expect(resp.status).toBe('success');
+    const resp1 = await client.mfaRequestOtp(credentials.sessionToken, 'test');
+    expect(resp1.status).toBe('success');
 
     // Verify the otp code
     const code = await target.emailClient.getVerifyAccountChangeCode(
       credentials.email
     );
 
     // Try accessing the protected action test endpoint with jwt
-    resp = await client.mfaOtpVerify(credentials.sessionToken, code, 'test');
-    expect(resp.accessToken).toBeDefined();
-    const jwtAccessToken = resp.accessToken;
+    const resp2 = await client.mfaOtpVerify(
+      credentials.sessionToken,
+      code,
+      'test'
+    );
+    expect(resp2.accessToken).toBeDefined();
+    const jwtAccessToken = resp2.accessToken;
 
     // Try accessing the protected action again
-    resp = await client.mfaTestGet(jwtAccessToken);
-    expect(resp.status).toBe('success');
+    const resp3 = await client.mfaTestGet(jwtAccessToken);
+    expect(resp3.status).toBe('success');
 
-    resp = await client.mfaTestPost(jwtAccessToken);
-    expect(resp.status).toBe('success');
+    const resp4 = await client.mfaTestPost(jwtAccessToken);
+    expect(resp4.status).toBe('success');
 
     let scopeError = undefined;
     try {
-      resp = await client.mfaTestPost2(jwtAccessToken);
+      await client.mfaTestPost2(jwtAccessToken);
     } catch (err) {
       scopeError = err;
     }

packages/fxa-auth-client/lib/client.ts

@@ -1517,7 +1517,7 @@ export default class AuthClient {
     sessionToken: hexstring,
     action: string,
     headers?: Headers
-  ) {
+  ): Promise<{ status: string }> {
     return this.sessionPost(
       '/mfa/otp/request',
       sessionToken,
@@ -1533,7 +1533,7 @@ export default class AuthClient {
     code: string,
     action: string,
     headers?: Headers
-  ) {
+  ): Promise<{ accessToken: string }> {
     return this.sessionPost(
       '/mfa/otp/verify',
       sessionToken,
@@ -1545,7 +1545,10 @@ export default class AuthClient {
     );
   }
 
-  async mfaTestGet(jwt: string, headers?: Headers) {
+  async mfaTestGet(
+    jwt: string,
+    headers?: Headers
+  ): Promise<{ status: string }> {
     return this.jwtGet('/mfa/test', jwt, headers);
   }
 

packages/fxa-auth-server/config/index.ts

@@ -2402,7 +2402,8 @@ const convictConf = convict({
     },
     ftlUrl: {
       template: {
-        default: 'https://raw.githubusercontent.com/mozilla/fxa-cms-l10n/main/locales/{locale}/cms.ftl',
+        default:
+          'https://raw.githubusercontent.com/mozilla/fxa-cms-l10n/main/locales/{locale}/cms.ftl',
         doc: 'URL template for FTL files. Use {locale} placeholder for locale substitution',
         env: 'CMS_L10N_FTL_URL_TEMPLATE',
         format: String,
@@ -2412,7 +2413,7 @@ const convictConf = convict({
         doc: 'Timeout for FTL requests in milliseconds',
         env: 'CMS_L10N_FTL_TIMEOUT',
         format: Number,
-      }
+      },
     },
     ftlCache: {
       memoryTtl: {
@@ -2520,7 +2521,7 @@ const convictConf = convict({
         env: 'MFA__OTP__WINDOW',
       },
       digits: {
-        default: 8,
+        default: 6,
         doc: 'Length of code',
         format: Number,
         env: 'MFA__OTP__DIGITS',

packages/fxa-auth-server/lib/routes/auth-schemes/mfa.ts

@@ -31,10 +31,16 @@ export const strategy = (config: ConfigType) => {
         audience: config.mfa.jwt.audience,
         issuer: config.mfa.jwt.issuer,
       };
-      const decoded = jwt.verify(token, key, opts) as {
-        sub?: string;
-        scope?: string[];
-      };
+
+      let decoded;
+      try {
+        decoded = jwt.verify(token, key, opts) as {
+          sub?: string;
+          scope?: string[];
+        };
+      } catch (err) {
+        throw AppError.invalidToken(err.message);
+      }
 
       // Ensure required state
       if (decoded.sub == null || decoded.scope == null) {

packages/fxa-auth-server/test/local/routes/mfa.js

@@ -33,7 +33,7 @@ describe('mfa', () => {
       enabled: true,
       actions: ['test'],
       otp: {
-        digits: 8,
+        digits: 6,
       },
       jwt: {
         secretKey: 'foxes',
@@ -158,6 +158,7 @@ describe('mfa', () => {
       error = err;
     }
     assert.isDefined(error);
+    assert.equal(error.errno, 110);
     assert.equal(error.message, 'jwt malformed');
   });
 
@@ -172,6 +173,7 @@ describe('mfa', () => {
       error = err;
     }
     assert.isDefined(error);
+    assert.equal(error.errno, 110);
     assert.equal(error.message, 'jwt expired');
   });
 });

packages/fxa-settings/src/components/Settings/MfaGuard/error-boundary.test.tsx

@@ -0,0 +1,77 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { MfaErrorBoundary } from './error-boundary';
+import { JwtTokenCache } from '../../../lib/cache';
+
+const mockScope = 'test';
+const mockSessionToken = 'session-xyz';
+const mockJwt = 'jwt-123';
+
+describe('MfaErrorBoundary', () => {
+  let removeSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    removeSpy = jest.spyOn(JwtTokenCache, 'removeToken');
+  });
+
+  afterEach(() => {
+    removeSpy.mockReset();
+  });
+
+  it('renders children when no error occurs', () => {
+    render(
+      <MfaErrorBoundary
+        requiredScope={mockScope}
+        sessionToken={mockSessionToken}
+        jwt={mockJwt}
+        fallback={<div>fallback</div>}
+      >
+        <div>child</div>
+      </MfaErrorBoundary>
+    );
+
+    expect(screen.getByText('child')).toBeInTheDocument();
+  });
+
+  it('renders fallback and removes JWT on auth error (401/110)', () => {
+    const ref = React.createRef<MfaErrorBoundary>();
+    const { rerender } = render(
+      <MfaErrorBoundary
+        ref={ref}
+        requiredScope={mockScope}
+        sessionToken={mockSessionToken}
+        jwt="jwt-2"
+        fallback={<div>fallback</div>}
+      >
+        <div>child</div>
+      </MfaErrorBoundary>
+    );
+
+    const authError: any = new Error('invalid jwt');
+    authError.code = 401;
+    authError.errno = 110;
+
+    // Simulate boundary catching the error
+    ref.current?.componentDidCatch(authError, {} as any);
+
+    // Trigger a render so updated state is reflected in output
+    rerender(
+      <MfaErrorBoundary
+        ref={ref}
+        requiredScope={mockScope}
+        sessionToken={mockSessionToken}
+        jwt="jwt-2"
+        fallback={<div>fallback</div>}
+      >
+        <div>child</div>
+      </MfaErrorBoundary>
+    );
+
+    expect(screen.getByText('fallback')).toBeInTheDocument();
+    expect(removeSpy).toHaveBeenCalledWith(mockSessionToken, mockScope);
+  });
+});

packages/fxa-settings/src/components/Settings/MfaGuard/error-boundary.tsx

@@ -0,0 +1,80 @@
+import { Component, ReactNode } from 'react';
+import { MfaScope } from '../../../lib/types';
+import { JwtTokenCache } from '../../../lib/cache';
+
+/**
+ * Error Boundary Implementation.
+ *
+ * This error boundary's only job is to handle errors that percolate up related to
+ * invalid JWTs. This can happen if a user leaves a flow open for a while, and
+ * the once-valid JWT expires. In this case, when they submit the JWT an invalid
+ * state will be returned, and we should clear the JWT from our cache so the
+ * user has an opportunity to get a new one via the MfaModalDialog.
+ *
+ * This error boundary is specifically tailored to the MfaGuard. Don't try
+ * to export it or reuse it!
+ */
+type MfaErrorBoundaryProps = {
+  requiredScope: MfaScope;
+  sessionToken: string;
+  jwt: string;
+  children: ReactNode;
+  fallback: ReactNode;
+};
+
+type MfaErrorBoundaryState = { hasError: boolean; error: any | null };
+
+export class MfaErrorBoundary extends Component<
+  MfaErrorBoundaryProps,
+  MfaErrorBoundaryState
+> {
+  state: MfaErrorBoundaryState;
+
+  constructor(props: any) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: any) {
+    if (error && error.code === 401 && error.errno === 110) {
+      return { hasError: true };
+    }
+
+    return undefined;
+  }
+
+  componentDidCatch(error: any, info: any) {
+    if (error && error.code === 401 && error.errno === 110) {
+      this.setState({
+        hasError: true,
+        error: error,
+      });
+
+      JwtTokenCache.removeToken(
+        this.props.sessionToken,
+        this.props.requiredScope
+      );
+    } else {
+      // Causes error to bubble up to the next error boundary
+      throw error;
+    }
+  }
+
+  componentDidUpdate(prevProps: MfaErrorBoundaryProps) {
+    // Until a new code is provided, consider the error to still be valid.
+    if (prevProps.jwt !== this.props.jwt) {
+      this.setState({
+        hasError: false,
+        error: null,
+      });
+    }
+  }
+
+  render() {
+    if (this.state.hasError && this.state.error) {
+      return this.props.fallback;
+    }
+
+    return this.props.children;
+  }
+}

packages/fxa-settings/src/components/Settings/MfaGuard/index.stories.tsx

@@ -0,0 +1,80 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import React from 'react';
+import { Meta } from '@storybook/react';
+import { withLocalization, withLocation } from 'fxa-react/lib/storybooks';
+import { action } from '@storybook/addon-actions';
+import { AppContext } from '../../../models';
+import { mockAppContext } from '../../../models/mocks';
+import { MfaGuard } from './index';
+import { JwtTokenCache } from '../../../lib/cache';
+
+const scope: 'test' = 'test';
+const session = 'session-xyz';
+
+function initLocalAccount(sessionToken: string) {
+  // Match Storage fullKey logic: '__fxa_storage.' prefix
+  const NS = '__fxa_storage';
+  const uid = 'abc123';
+  const accounts = {
+    [uid]: {
+      uid,
+      sessionToken,
+      email: '[email protected]',
+      verified: true,
+      lastLogin: Date.now(),
+    },
+  };
+  window.localStorage.setItem(`${NS}.accounts`, JSON.stringify(accounts));
+  window.localStorage.setItem(`${NS}.currentAccountUid`, JSON.stringify(uid));
+}
+
+const authClient = {
+  mfaRequestOtp: async (st: string, sc: string) => {
+    action('mfaRequestOtp')({ sessionToken: st, scope: sc });
+    return undefined;
+  },
+  mfaOtpVerify: async (st: string, code: string, sc: string) => {
+    action('mfaOtpVerify')({ sessionToken: st, code, scope: sc });
+    return { accessToken: 'storybook-jwt' } as any;
+  },
+} as any;
+
+export default {
+  title: 'Components/Settings/MfaGuard',
+  component: MfaGuard,
+  decorators: [withLocalization, withLocation('/settings')],
+} as Meta;
+
+export const JwtMissingShowsModal = () => {
+  initLocalAccount(session);
+  // Ensure no token present so guard triggers OTP flow
+  try {
+    if (JwtTokenCache.hasToken(session, scope)) {
+      JwtTokenCache.removeToken(session, scope);
+    }
+  } catch {}
+
+  return (
+    <AppContext.Provider value={mockAppContext({ authClient } as any)}>
+      <MfaGuard requiredScope={scope}>
+        <div>Secured content</div>
+      </MfaGuard>
+    </AppContext.Provider>
+  );
+};
+
+export const JwtPresentRendersChildren = () => {
+  initLocalAccount(session);
+  JwtTokenCache.setToken(session, scope, 'jwt-present');
+
+  return (
+    <AppContext.Provider value={mockAppContext({ authClient } as any)}>
+      <MfaGuard requiredScope={scope}>
+        <div>Secured content</div>
+      </MfaGuard>
+    </AppContext.Provider>
+  );
+};