[provision group] Check changes against cognito

The provision-users command requires us to provide both a username and
email for each user we want to add. A common use case is being given a
(long) list of emails and wanting to check if a user already exists
for each email, which is exactly what this script does. It goes further
with the intention of giving confidence that we're not provisioning
new users when we could be associating new roles/groups with already
existing users.

Author: jameshadfield

scripts/provision-group-check-users.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import { ArgumentParser } from 'argparse';
+import {
+    CognitoIdentityProviderClient,
+    ListUsersCommand,
+    AdminListGroupsForUserCommand
+  } from '@aws-sdk/client-cognito-identity-provider';
+import fs from 'fs';
+import yaml from 'js-yaml';
+import process from 'process';
+import { Group } from '../src/groups.js';
+import { reportUnhandledRejectionsAtExit } from '../src/utils/scripts.js';
+/**
+ * COGNITO_USER_POOL_ID will read from the eponymous env variable or look in a
+ * config file. The config file is set via the env variable `CONFIG_FILE`, or
+ * either env/production/config.json or env/testing/config.json depending on
+ * your environment (NODE_ENV) */
+import { COGNITO_USER_POOL_ID, PRODUCTION } from '../src/config.js';
+
+const DESCRIPTION = `
+  A helper script to check provided emails against existing cognito users
+  in the pool. The CLI interface is the same as 'provision-group' however
+  no changes will be made (to cognito) by this script.
+
+  We attempt to check various scenarios (email matches, username matches) and print
+  verbose output so that we can update existing users where possible.
+
+  P.S. Set 'CONFIG_FILE=env/production/config.json' to use the production cognito
+  user pool; by default we'll use the pool defined in 'env/testing/config.json'
+  or the env variable 'COGNITO_USER_POOL_ID' if set.
+`;
+
+const REGION = COGNITO_USER_POOL_ID.split("_")[0];
+const cognito = new CognitoIdentityProviderClient({ region: REGION });
+
+function parseArgs() {
+    const argparser = new ArgumentParser({description: DESCRIPTION});
+    argparser.addArgument("groupName", {metavar: "<name>", help: "Name of the Nextstrain Group"});
+    argparser.addArgument("--members", {
+      dest: "membersFile",
+      metavar: "<file.yaml>",
+      required: true,
+      help: `
+        A YAML file describing the members to add to the Group.
+        The file must be an array of objects (i.e.  dict/map/hash).
+        Each object must contain an "email" key which is case-sensitive.
+        The "username" key is optional for this script, but is required when you actually create provision the group membership.
+        The "role" key is optional and may be set to "viewers", "editors", or "owners"; the default if not provided is "viewers".
+      `
+    });
+    return argparser.parseArgs();
+  }
+
+
+async function main({groupName, membersFile}) {
+  // Canonicalizes name for us and ensures a data entry exists.
+  const group = new Group(groupName);
+  console.log(`[debug] Node environment: ${PRODUCTION ? 'production' : 'testing'}`)
+  const members = readMembersFile(membersFile)
+  const {usersByEmail, usersByUsername} = await cognitoUsers()
+  await queryUsernames(group, members, usersByEmail, usersByUsername)
+}
+
+
+function readMembersFile(file) {
+  const members = yaml.load(fs.readFileSync(file));
+
+  const validationErrors = !Array.isArray(members)
+    ? ["Not an array"]
+    : members.filter(m => !m.email)
+      .map(m => `Email missing for member ${JSON.stringify(m)}`)
+    ;
+
+  if (validationErrors.length) {
+    const msg = validationErrors.map((err, i) => ` ${i+1}. ${err}`).join("\n");
+    const s = validationErrors.length === 1 ? "" : "s";
+    throw new Error(`Members file contains ${validationErrors.length} error${s}:\n${msg}`);
+  }
+
+  return members;
+}
+
+function getEmailFromUser(user) {
+  return user.Attributes.filter(({Name}) => Name==='email')[0].Value;
+}
+
+/**
+ * Returns all the users in the pool. NOTE: we could make a cheaper request and query by email,
+ * but in order to perform case-insensitive email matching we gather them all here.
+ */
+async function cognitoUsers() {
+  // https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cognito-identity-provider/command/ListUsersCommand/
+  console.log(`[debug] Fetching existing membership data for cognito user pool "${COGNITO_USER_POOL_ID}"`)
+  const params = {
+    AttributesToGet: ['email'], // all users must have this else cmd fails
+    UserPoolId: COGNITO_USER_POOL_ID,
+    // Limit: 60, // default: 60
+  }
+  let Users, PaginationToken;
+  try {
+    ({Users, PaginationToken} = await cognito.send(new ListUsersCommand(params)));
+    while (PaginationToken) {
+      const data = await cognito.send(new ListUsersCommand({...params, PaginationToken}));
+      Users = [...Users, ...data.Users]
+      PaginationToken = data.PaginationToken
+    }
+  } catch (e) {
+    // Importing the actual error is difficult due to @aws-sdk/property-provider (where the error is defined)
+    // being a nested dependency of `@aws-sdk/credential-provider-node`.
+    if (e.name === 'CredentialsProviderError') {
+      console.error(`FATAL ERROR: ${e.message}`)
+      process.exit(2);
+    }
+    throw e;
+  }
+  // there may be duplicate emails (different users)
+  const [usersByEmail, usersByUsername] = [{}, {}]
+  for (const user of Users) {
+    const email = getEmailFromUser(user);
+    Object.hasOwn(usersByEmail, email) ? usersByEmail[email].push(user) : (usersByEmail[email]=[user])
+    usersByUsername[user.Username] = user; // Username is unique (within a user pool)
+  }
+
+  return {usersByEmail, usersByUsername};
+}
+
+
+/**
+ * For a given nextstrain group and username, return the list of roles this username
+ * already has for the (nextstrain) group. In theory a user should only have a single
+ * role, but there's nothing enforcing this as far as I'm aware, so we return an array
+ */
+async function getUserRoles(group, username) {
+  // roles are based upon group membership, which must be queried per-username
+  const params = {
+    Username: username,
+    UserPoolId: COGNITO_USER_POOL_ID,
+  }
+  let cognitoGroups = [];
+  try {
+    const res = await cognito.send(new AdminListGroupsForUserCommand(params));
+    cognitoGroups = res.Groups.map((g) => g.GroupName);
+    if (!Array.isArray(cognitoGroups)) {
+      throw new Error(`unexpected type for "Groups" data from the AdminListGroupsForUserCommand request for user ${username}`)
+    }
+  } catch (e) {
+    console.error(`FATAL ERROR while fetching (cognito) groups for user ${username}`)
+    console.error(e)
+    process.exit(2)
+  }
+
+  // for the specified nextstrain group, which cognito groups are relevant?
+  // (each cognito group corresponds to a role)
+  const rolesByCognitoGroup = new Map(
+    Array.from(group.membershipRoles.entries())
+      .map(([role, groupName]) => [groupName, role])
+  );
+
+  const existingRoles = cognitoGroups
+    .map((g) => rolesByCognitoGroup.has(g) ? rolesByCognitoGroup.get(g) : false)
+    .filter(Boolean);
+
+  return existingRoles;
+}
+
+
+async function queryUsernames(group, members, usersByEmail, usersByUsername) {
+  for (const member of members) {
+    console.log()
+    console.log(`Membership request for user "${member.username}" (${member.email}), role: ${member.role}`)
+
+    // ensure requested role is valid for this group
+    if (!group.membershipRoles.has(member.role)) {
+      console.error(`FATAL ERROR: Group ${group.name} doesn't support the role ${member.role}`)
+      process.exit(2)
+    }
+
+    if (Object.hasOwn(usersByEmail, member.email)) {
+      // 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)`)
+      const userRoles = {};
+      for (const user of usersByEmail[member.email]) {
+        const roles = await getUserRoles(group, user.Username);
+        userRoles[user.Username] = roles;
+        console.log(`\t\t"${user.Username}" ` + (roles.length ? `roles: ${roles.join(", ")}` : '(no roles for this group)'))
+      }
+      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)) {
+          if (userRoles[member.username].includes(member.role)) {
+            console.log(`\tRequested email & username already has the role ${member.role}`);
+            console.log(`\tNO ACTION NEEDED`);
+            continue
+          }
+          console.log(`\tThis will change the role for user ${member.username} to ${member.role}`);
+          if (numAssociatedUsers>1) {
+            console.log(`\tACTION: Check above to see if there's another username which may be better suited, or if this role change is necessary and is desired`);
+          }
+          continue
+        }
+
+        // situation: username exists and is associated with another email
+        if (Object.hasOwn(usersByUsername, member.username)) {
+          const usernameEmail = getEmailFromUser(usersByUsername[member.username]);
+          const usernameRoles = await getUserRoles(group, member.username);
+          console.log(`\tRequested username is associated with a different email address: "${usernameEmail}"`)
+          console.log(`\tThat user currently has ` + (usernameRoles.length ? `roles ${usernameRoles.join(', ')}` : 'no roles associated with this group'))
+          console.log(`\tACTION: Change the username or email for this member`)
+          continue
+        }
+
+        // situation: supplied username doesn't exist, will be created
+        console.log(`\tThis will create a new user ${member.username} with role ${member.role}`)
+        if (numAssociatedUsers>0) {
+          console.log(`\tWARNING: The email already has associated users, consider using one of them instead.`)
+        }
+        continue
+      }
+
+      // situation: email exists, no username provided
+      console.log(`\tACTION: You didn't provide a username, so choose one of the ones which already exist for this email.`)
+      continue
+    }
+
+    // Situation: no email match
+    console.log(`\tThis email address is currently not associated with any users`)
+
+    // situation: there is a username match under a different email
+    if (member.username && Object.hasOwn(usersByUsername, member.username)) {
+      const usernameEmail = getEmailFromUser(usersByUsername[member.username]);
+      const usernameRoles = await getUserRoles(group, member.username);
+      console.log(`\tRequested username is associated with a different email address: "${usernameEmail}"`)
+      console.log(`\tThat user currently has ` + (usernameRoles.length ? `the role ${usernameRoles.join(', ')}` : 'no roles associated with this group'))
+      console.log(`\tACTION: Change the email for this member, or choose a different username`);
+      continue
+    }
+
+    // situation: no email nor username match
+    if (member.username) {
+      console.log(`\tThis will create a new user with this email and username`);
+      continue
+    }
+    console.log(`\tThis will create a new user but you will need to also define a username`);
+    continue
+  }
+}
+
+reportUnhandledRejectionsAtExit();
+main(parseArgs())
+  .catch((error) => {
+    process.exitCode = 1;
+    console.error(error)
+  });