[provision group] case insensitive email matching

Usernames and emails in our Cognito user pool are case sensitive (at
least the way we have them set up) but we want to avoid the situation
where we add a "new" email when there's an existing email which is the
same except for casing.

Resolves <#1258>

Author: jameshadfield

scripts/provision-group-check-users.js

@@ -163,8 +163,49 @@ async function getUserRoles(group, username) {
   return existingRoles;
 }
 
+/**
+ * The cognito pools we use are case-sensitive for emails, but we want to avoid
+ * provisioning multiple emails with different casings. Here we create a lookup
+ * dictionary by uppercase email addresses, and for good measure spit out warnings
+ * if there are multiple emails with different casings.
+ */
+function summariseEmails(usersByEmail) {
+  const db = {}
+  for (const email of Object.keys(usersByEmail)) {
+    const key = email.toUpperCase();
+    Object.hasOwn(db, key) ? db[key].push(email) : (db[key]=[email]);
+  }
+  // eslint-disable-next-line no-unused-vars
+  for (const [_key, emails] of Object.entries(db)) {
+    if (emails.length>1) {
+      console.log(`WARNING: Multiple emails with different casings present in pool: ${emails.join(', ')}`)
+    }
+  }
+  return db;
+}
+
+/**
+ * Match a provided case-sensitive *email* against the *emailDb* which is
+ * indexed by all-caps emails. This is necessary because cognito (at least the
+ * way we have it) is case-sensitive, but emails are generally case-insensitive.
+ * Ultimately we want to avoid situations where we provision multiple emails
+ * which differ only in their casing.
+ * @param {object} emailDb
+ * @param {string} email
+ * @returns {object} exact: boolean (whether the email is an exact match),
+ *  candidates: string[] cognito URLs which are identical to the provided email
+ *  except for potential different casing
+ */
+function searchEmails(emailDb, email) {
+  const candidates = emailDb[email.toUpperCase()] || [];
+  const exact = candidates.includes(email);
+  if (candidates.length===0) return false
+  return {candidates, exact}
+}
 
 async function queryUsernames(group, members, usersByEmail, usersByUsername) {
+  const emailDb = summariseEmails(usersByEmail); // uppercase emails for searching purposes
+
   for (const member of members) {
     console.log()
     console.log(`Membership request for user "${member.username}" (${member.email}), role: ${member.role}`)
@@ -175,7 +216,29 @@ async function queryUsernames(group, members, usersByEmail, usersByUsername) {
       process.exit(2)
     }
 
-    if (Object.hasOwn(usersByEmail, member.email)) {
+    /* match emails because cognito is case-sensitive and emails generally aren't */
+    const emailMatch = searchEmails(emailDb, member.email);
+
+    if (emailMatch) {
+
+      /* If the email's not an exact match, then print out a warning and go to the next member */
+      if (!emailMatch.exact) {
+        if (emailMatch.candidates.length===1) {
+          console.log(`\tWARNING: The provided email ${member.email} wasn't an exact match - you probably meant "${emailMatch.candidates[0]}"`)
+          console.log(`\tACTION: try again with the case-corrected email`)
+        } else {
+          console.log(`\tWARNING: The provided email ${member.email} wasn't an exact match but there are` +
+            `multiple different (case-sensitive) matches: ${emailMatch.candidates.join(", ")}`)
+          console.log(`\tACTION: try again with a case-corrected email or (better) unify these various emails before proceeding`)
+        }
+        continue
+      }
+      /* If it's an exact match but there are also other (case-sensitive) alternatives, proceed with a loud warning */
+      if (emailMatch.candidates.length>1) {
+        console.log(`\tWARNING: while this exact email already exists, other emails with different casing also exist (see earlier warnings). ` +
+          `We recommend you unify these emails (and associated usernames) before proceeding`)
+      }
+
       // Pay the cost upfront to get all the roles currently set (in the context of the chosen
       // Nextstrain group) for all cognito users associated with this email address
       console.log(`\tThis email address is currently associated with ${usersByEmail[member.email].length} user(s)`)
@@ -187,8 +250,6 @@ async function queryUsernames(group, members, usersByEmail, usersByUsername) {
       }
       const numAssociatedUsers = usersByEmail[member.email].length;
 
-      // TODO XXX - check case of emails...
-
       if (member.username) {
         // Simplest case: the requested username is associated with the requested email
         if (Object.hasOwn(userRoles, member.username)) {