task(auth): Create a new auth strategy for verifiedSessionTokens

Because:
- We want to create an auth strategy so it is easy to ensure a route requires a verified session state

This Commit:
- Creates a new auth strategy, verified-session-token
- Registers strategy with server
- Makes checks configurable
- Emits metrics for failing checks

Author: dschom

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

@@ -31,6 +31,28 @@ const convictConf = convict({
     default: 1,
     env: 'AUTH_API_VERSION',
   },
+  authStrategies: {
+    verifiedSessionToken: {
+      skipEmailVerifiedCheckForRoutes: {
+        default: '',
+        doc: 'A regex that defines the routes that should skip the email verification check.',
+        env: 'AUTH_STRATEGIES__VERIFIED_SESSION_TOKEN__SKIP_EMAIL_CHECK_FOR_ROUTES',
+        format: String,
+      },
+      skipTokenVerifiedCheckForRoutes: {
+        default: '',
+        doc: 'A regex that defines the routes that should skip the token verified check.',
+        env: 'AUTH_STRATEGIES__VERIFIED_SESSION_TOKEN__SKIP_TOKEN_VERIFIED_CHECK_FOR_ROUTES',
+        format: String,
+      },
+      skipAalCheckForRoutes: {
+        default: '',
+        doc: 'A regex that defines the routes that should skip the account assurance level check.',
+        env: 'AUTH_STRATEGIES__VERIFIED_SESSION_TOKEN__SKIP_AAL_CHECK_FOR_ROUTES',
+        format: String,
+      },
+    },
+  },
   // TODO: Remove this after we have synchronized login records to Firestore
   firestore: {
     credentials: {

packages/fxa-auth-server/lib/routes/auth-schemes/hawk-fxa-token.js

@@ -160,4 +160,5 @@ function strategy(
 
 module.exports = {
   strategy,
+  parseAuthorizationHeader,
 };

packages/fxa-auth-server/lib/routes/auth-schemes/verified-session-token.js

@@ -0,0 +1,137 @@
+/* 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/. */
+
+'use strict';
+
+const AppError = require('../../error');
+const authMethods = require('../../authMethods');
+const { parseAuthorizationHeader } = require('./hawk-fxa-token');
+
+/**
+ * Authentication strategy that validates a Hawk session token and ensures:
+ * 1) account email is verified
+ * 2) session token is verified (no tokenVerificationId)
+ * 3) account AAL and session AAL match
+ *
+ * @param {Function} getCredentialsFunc - function to fetch a session token by id
+ * @param {Object} db - database interface to fetch account and factors
+ * @returns {Function}
+ */
+function strategy(getCredentialsFunc, db, config, statsd) {
+  const tokenNotFoundError = () => {
+    const error = AppError.unauthorized('Token not found');
+    error.isMissing = true;
+    return error;
+  };
+
+  // Extract regular expressions to allow for optional skipping of certain routes for certain checks.
+  const verifiedSessionTokenConfig =
+    config?.authStrategies?.verifiedSessionToken;
+
+  const skipEmailVerifiedCheckForRoutes =
+    verifiedSessionTokenConfig?.skipEmailVerifiedCheckForRoutes
+      ? new RegExp(verifiedSessionTokenConfig.skipEmailVerifiedCheckForRoutes)
+      : null;
+
+  const skipTokenVerifiedCheckForRoutes =
+    verifiedSessionTokenConfig?.skipTokenVerifiedCheckForRoutes
+      ? new RegExp(verifiedSessionTokenConfig.skipTokenVerifiedCheckForRoutes)
+      : null;
+
+  const skipAalCheckForRoutes =
+    verifiedSessionTokenConfig?.skipAalCheckForRoutes
+      ? new RegExp(verifiedSessionTokenConfig.skipAalCheckForRoutes)
+      : null;
+
+  return function (server, options) {
+    return {
+      authenticate: async function (req, h) {
+        const auth = req.headers.authorization;
+
+        if (!auth) {
+          // if this strategy is selected, auth *cannot* be optional
+          // "optional" mode is not supported
+          throw tokenNotFoundError();
+        }
+
+        const parsedHeader = parseAuthorizationHeader(auth);
+        let token;
+        try {
+          token = await getCredentialsFunc(parsedHeader.id);
+        } catch (_) {}
+
+        if (!token) {
+          throw tokenNotFoundError();
+        }
+
+        // Fetch the account for further checks
+        const account = await db.account(token.uid);
+
+        // 1) account email is verified
+        if (!account?.primaryEmail?.isVerified) {
+          if (skipEmailVerifiedCheckForRoutes?.test(req.route.path)) {
+            statsd?.increment(
+              'verified_session_token.primary_email_not_verified.skipped',
+              [
+                // Important! Using req.route.path which has much lower cardinality than req.path
+                req.route.path,
+              ]
+            );
+          } else {
+            statsd?.increment(
+              'verified_session_token.primary_email_not_verified.error',
+              [req.route.path]
+            );
+            throw AppError.unverifiedAccount();
+          }
+        }
+
+        // 2) session token is verified
+        if (token.tokenVerificationId || token.tokenVerified === false) {
+          if (skipTokenVerifiedCheckForRoutes?.test(req.route.path)) {
+            console.log('!!! verified_session_token.token_verified.skipped');
+            statsd?.increment('verified_session_token.token_verified.skipped', [
+              req.route.path,
+            ]);
+          } else {
+            statsd?.increment('verified_session_token.token_verified.error', [
+              req.route.path,
+            ]);
+            throw AppError.unverifiedSession();
+          }
+        }
+
+        // 3) account AAL and session AAL match
+        const accountAmr = await authMethods.availableAuthenticationMethods(
+          db,
+          account
+        );
+        const accountAal = authMethods.maximumAssuranceLevel(accountAmr);
+        const sessionAal = token.authenticatorAssuranceLevel;
+
+        if (accountAal !== sessionAal) {
+          if (skipAalCheckForRoutes?.test(req.route.path)) {
+            console.log('!!! verified_session_token.aal.skipped');
+            statsd?.increment('verified_session_token.aal.skipped', [
+              req.route.path,
+            ]);
+          } else {
+            statsd?.increment('verified_session_token.aal.error', [
+              req.route.path,
+            ]);
+            throw AppError.unauthorized('AAL mismatch');
+          }
+        }
+
+        return h.authenticated({
+          credentials: token,
+        });
+      },
+    };
+  };
+}
+
+module.exports = {
+  strategy,
+};

packages/fxa-auth-server/lib/server.js

@@ -25,6 +25,7 @@ const {
 } = require('fxa-shared/sentry/report-validation-error');
 const { logErrorWithGlean } = require('./metrics/glean');
 const mfa = require('./routes/auth-schemes/mfa');
+const verifiedSessionToken = require('./routes/auth-schemes/verified-session-token');
 
 function trimLocale(header) {
   if (!header) {
@@ -497,6 +498,17 @@ async function create(log, error, config, routes, db, statsd, glean, customs) {
   );
   server.auth.strategy('mfa', 'mfa');
 
+  server.auth.scheme(
+    'verified-session-token',
+    verifiedSessionToken.strategy(
+      makeCredentialFn(db.sessionToken.bind(db)),
+      db,
+      config,
+      statsd
+    )
+  );
+  server.auth.strategy('verifiedSessionToken', 'verified-session-token');
+
   // register all plugins and Swagger configuration
   await server.register([
     {