Clarify roles claim in token.js

src/api/auth/src/token.js

@@ -10,20 +10,26 @@ const { JWT_ISSUER, JWT_AUDIENCE, SECRET, JWT_EXPIRES_IN } = process.env;
  * @returns {string} the JWT for this user
  */
 function createToken(email, name, roles) {
+  // The token we create includes a number of claims in the payload
   const payload = {
-    // The token is issued by us (e.g., this server)
+    // iss claim: the token is issued by us (e.g., this server)
     iss: JWT_ISSUER,
-    // It is intended for the services running at this api origin
+    // aud claim: it is intended for the services running at this api origin
     aud: JWT_AUDIENCE,
-    // The subject of this token, the user's nameID (i.e., their Seneca email address)
+    // sub claim: the subject of this token (e.g., their email address)
     sub: email,
-    // The user's display name
+    // name claim: the display name
     name,
-    // User roles.  We have 4 currently:
-    //   1. seneca (authenticated with Seneca's SSO)
-    //   1. telescope (authenticated Telescope user)
-    //   2. admin (authenticated Telescope user with isAdmin=true in Firebase)
-    //   3. service (a Telescope microservice, see createServiceToken() in Satellite)
+    // roles claim: an Arry of one or more authorization roles. There are various
+    // combinations possible. For authenticated users, we currently have the
+    // following, and/ a user will have one or more, depending on their account type:
+    //   1. seneca (user was authenticated with Seneca's SSO)
+    //   2. telescope (user has a Telescope account with the Users service)
+    //   3. admin (user's Telescope account includes isAdmin=true)
+    //
+    // We also have a service token role, for cases where microservices need to
+    // communicate with one another using protected routes:
+    //   4. service (a Telescope microservice, see createServiceToken() in Satellite)
     roles,
   };