@nymphjs/tilmeld 1.0.0-beta.55 → 1.0.0-beta.57

package/dist/Tilmeld.js

@@ -11,15 +11,64 @@ const errors_1 = require("./errors");
 const Group_1 = __importDefault(require("./Group"));
 const User_1 = __importDefault(require("./User"));
 const enforceTilmeld_1 = require("./enforceTilmeld");
+/**
+ * A user and group system for Nymph.js.
+ *
+ * Written by Hunter Perrin for SciActive.
+ *
+ * @author Hunter Perrin <hperrin@gmail.com>
+ * @copyright SciActive Inc
+ * @see http://nymph.io/
+ */
 class Tilmeld {
+    /**
+     * Create a new instance of Tilmeld.
+     *
+     * @param config The Tilmeld configuration.
+     */
     constructor(config) {
+        /**
+         * The Nymph instance.
+         */
         this.nymph = {};
+        /**
+         * The currently logged in user.
+         */
         this.currentUser = null;
+        /**
+         * The user class for this instance of Tilmeld.
+         */
         this.User = User_1.default;
+        /**
+         * The group class for this instance of Tilmeld.
+         */
         this.Group = Group_1.default;
+        /**
+         * If you will be performing authentication functions (logging in/out), you
+         * should set these so Tilmeld can read and write cookies and headers.
+         *
+         * If you want the user to be authenticated with the cookie and/or header they
+         * provide, you should set at least the request. It's better to set both, so
+         * the JWT can be updated if needed.
+         *
+         * After you set these, call `authenticate()` to read user authentication data
+         * from them and fill the user's session.
+         *
+         * If you want to support cookie based authentication (which still requires an
+         * XSRF token for security), you should enable the cookie parser middleware.
+         */
         this.request = null;
         this.response = null;
+        /**
+         * Used to avoid infinite loop.
+         */
         this.alreadyLoggedOutSwitch = false;
+        /**
+         * Gatekeeper ability cache.
+         *
+         * Gatekeeper will cache the user's abilities that it calculates, so it can
+         * check faster if that user has been checked before.
+         */
         this.gatekeeperCache = null;
         this.config = { ...conf_1.ConfigDefaults, ...config };
         if (this.config.emailUsernames &&
@@ -33,6 +82,11 @@ class Tilmeld {
             }
         }
     }
+    /**
+     * This is used internally by Nymph. Don't call it yourself.
+     *
+     * @returns A clone of this instance.
+     */
     clone() {
         const tilmeld = new Tilmeld(this.config);
         tilmeld.request = this.request;
@@ -41,19 +95,30 @@ class Tilmeld {
         tilmeld.gatekeeperCache = this.gatekeeperCache;
         return tilmeld;
     }
+    /**
+     * Initialize Tilmeld.
+     *
+     * This is meant to be called internally by Nymph. Don't call this directly.
+     *
+     * @param nymph The Nymph instance.
+     */
     init(nymph) {
         this.nymph = nymph;
         if (this.nymph.driver == null) {
             throw new Error("Tilmeld can't be configured before Nymph.");
         }
+        // Configure the classes.
         if (nymph.parent) {
+            // This is a cloned Nymph, it should have classes already.
             this.User = this.nymph.getEntityClass(User_1.default);
             this.Group = this.nymph.getEntityClass(Group_1.default);
         }
         else {
+            // This is a new Nymph, add the classes.
             this.User = this.nymph.addEntityClass(User_1.default);
             this.Group = this.nymph.addEntityClass(Group_1.default);
         }
+        // Clone the current user so its Nymph instance is correct.
         if (this.currentUser) {
             const currentUserGUID = this.currentUser.guid;
             const currentUserCDate = this.currentUser.cdate;
@@ -71,8 +136,19 @@ class Tilmeld {
             this.currentUser.$updateDataProtection();
             this.currentUser.$updateGroupDataProtection();
         }
+        // Set up access control hooks when Nymph is called.
+        this.nymph.config.debugLog('tilmeld', 'Initializing access controls.');
         this.initAccessControl();
     }
+    /**
+     * Check to see if the current user has an ability.
+     *
+     * If `ability` is undefined, it will check to see if a user is currently
+     * logged in.
+     *
+     * @param ability The ability.
+     * @returns Whether the user has the given ability.
+     */
     gatekeeper(ability) {
         if (this.currentUser == null || this.gatekeeperCache == null) {
             return false;
@@ -84,6 +160,7 @@ class Tilmeld {
             !!this.currentUser.abilities?.includes('system/admin'));
     }
     initAccessControl() {
+        // Check for the skip access control option and add AC selectors.
         const handleQuery = function (nymph, options, selectors) {
             const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(nymph);
             if (!options ||
@@ -93,38 +170,45 @@ class Tilmeld {
                 if (options?.source === 'client') {
                     if ((!tilmeld.currentUser ||
                         (!tilmeld.currentUser.abilities?.includes('tilmeld/admin') &&
-                            !tilmeld.currentUser.abilities?.includes('system/admin'))) &&
+                            !tilmeld.currentUser.abilities?.includes('system/admin'))) && // The user is not an admin.
                         ((!tilmeld.config.enableUserSearch &&
-                            options.class?.factorySync() instanceof User_1.default) ||
+                            options.class?.factorySync() instanceof User_1.default) || // The use is searching for a user and searching is disabled.
                             (!tilmeld.config.enableGroupSearch &&
-                                options.class?.factorySync() instanceof Group_1.default)) &&
-                        (selectors[0] == null ||
-                            selectors[0].type !== '&' ||
-                            (!('guid' in selectors[0]) && !('equal' in selectors[0])) ||
+                                options.class?.factorySync() instanceof Group_1.default)) && // Or the same, but for a group.
+                        (selectors[0] == null || // No selector specified.
+                            selectors[0].type !== '&' || // Or the type is not and.
+                            (!('guid' in selectors[0]) && !('equal' in selectors[0])) || // Or they're searching for something other than guid or equal.
                             ('guid' in selectors[0] &&
                                 (!selectors[0].guid?.length ||
-                                    !selectors[0].guid?.[0]?.length)) ||
+                                    !selectors[0].guid?.[0]?.length)) || // Or they're not searching for a specific guid.
                             ('equal' in selectors[0] &&
                                 selectors[0].equal?.[0]?.[0] !== 'username' &&
-                                selectors[0].equal?.[0]?.[0] !== 'groupname'))) {
+                                selectors[0].equal?.[0]?.[0] !== 'groupname')) // Or they're not searching for a specific username/groupname.
+                    ) {
+                        // If the user is not specifically searching for a GUID or username,
+                        // and they're not allowed to search, it should fail.
                         throw new errors_1.AccessControlError('No permission to search.');
                     }
                 }
+                // Add access control selectors
                 tilmeld.addAccessControlSelectors(options, selectors);
             }
         };
         handleQuery.skipOnClone = true;
+        // Filter entities being deleted for user permissions.
         const checkPermissionsDelete = async function (nymph, entity) {
             const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(nymph);
             if (typeof entity.$tilmeldDeleteSkipAC === 'function' &&
                 entity.$tilmeldDeleteSkipAC()) {
                 return;
             }
+            // Test for permissions.
             if (!tilmeld.checkPermissions(entity, nymph_1.TilmeldAccessLevels.FULL_ACCESS)) {
                 throw new errors_1.AccessControlError('No permission to delete.');
             }
         };
         checkPermissionsDelete.skipOnClone = true;
+        // Filter entities being deleted for user permissions.
         const checkPermissionsDeleteByID = async function (nymph, guid, className) {
             const entity = await nymph.getEntity({ class: nymph.getEntityClass(className ?? 'Entity') }, { type: '&', guid: guid });
             if (entity != null) {
@@ -132,6 +216,8 @@ class Tilmeld {
             }
         };
         checkPermissionsDeleteByID.skipOnClone = true;
+        // Filter entities being saved for user permissions, and filter any
+        // disallowed changes to AC properties.
         const checkPermissionsSaveAndFilterAcChanges = async function (nymph, entity) {
             const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(nymph);
             if (!entity) {
@@ -142,6 +228,8 @@ class Tilmeld {
                 return;
             }
             if (entity.guid != null) {
+                // If the entity is not new, check that the user has full access before
+                // allowing a change to ac properties.
                 const originalAc = entity.$getOriginalAcValues();
                 const newAc = entity.$getCurrentAcValues();
                 function areAcPropertiesChanged(a, b) {
@@ -191,6 +279,7 @@ class Tilmeld {
                 }
                 if (areAcPropertiesChanged(originalAc, newAc)) {
                     if (!tilmeld.checkPermissions(entity, nymph_1.TilmeldAccessLevels.FULL_ACCESS, undefined, originalAc)) {
+                        // Only allow changes to AC properties if the user has full access.
                         throw new errors_1.AccessControlError('No permission to change access control properties.');
                     }
                     if ((originalAc.user != null && originalAc.user !== newAc.user) ||
@@ -207,11 +296,28 @@ class Tilmeld {
                     }
                 }
             }
+            // Test for permissions.
             if (!tilmeld.checkPermissions(entity, nymph_1.TilmeldAccessLevels.WRITE_ACCESS)) {
                 throw new errors_1.AccessControlError('No permission to write.');
             }
         };
         checkPermissionsSaveAndFilterAcChanges.skipOnClone = true;
+        /*
+         * Add the current user's "user", "group", and access control to new entity.
+         *
+         * This occurs right before an entity is saved. It only alters the entity
+         * if:
+         *
+         * - There is a user logged in.
+         * - The entity is new (doesn't have a GUID.)
+         * - The entity is not a user or group.
+         *
+         * Default access control is
+         *
+         * - acUser = TilmeldAccessLevels.FULL_ACCESS
+         * - acGroup = TilmeldAccessLevels.READ_ACCESS
+         * - acOther = TilmeldAccessLevels.NO_ACCESS
+         */
         const addAccess = async function (nymph, entity) {
             const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(nymph);
             const user = tilmeld.currentUser;
@@ -306,6 +412,12 @@ class Tilmeld {
         this.nymph.on('beforeDeleteEntity', checkPermissionsDelete);
         this.nymph.on('beforeDeleteEntityByID', checkPermissionsDeleteByID);
     }
+    /**
+     * Add selectors to a list of options and selectors which will limit results
+     * to only entities the current user has access to.
+     *
+     * @param optionsAndSelectors The options and selectors of the query.
+     */
     addAccessControlSelectors(options, selectors) {
         const user = this.currentUser;
         if (options == null) {
@@ -314,12 +426,15 @@ class Tilmeld {
         else if ('class' in options &&
             (options.class?.factorySync() instanceof User_1.default ||
                 options.class?.factorySync() instanceof Group_1.default)) {
+            // They are requesting a user/group. Always accessible for reading.
             return;
         }
         if (user == null || user.guid == null) {
             selectors.push({
                 type: '|',
+                // Other access control is sufficient.
                 gte: [['acOther', nymph_1.TilmeldAccessLevels.READ_ACCESS]],
+                // The user and group are not set.
                 selector: [
                     {
                         type: '&',
@@ -334,6 +449,7 @@ class Tilmeld {
                     type: '&',
                     '!defined': [['user', 'group']],
                 },
+                // It is owned by the user.
                 {
                     type: '&',
                     ref: [['user', user.guid]],
@@ -344,18 +460,23 @@ class Tilmeld {
             const acRefs = [];
             const gid = user.$getGid();
             if (gid != null) {
+                // It belongs to the user's primary group.
                 groupRefs.push(['group', gid]);
+                // User's primary group is listed in acRead, acWrite, or acFull.
                 acRefs.push(['acRead', gid]);
                 acRefs.push(['acWrite', gid]);
                 acRefs.push(['acFull', gid]);
             }
             const gids = user.$getGids();
             for (let curGid of gids ?? []) {
+                // It belongs to the user's secondary group.
                 groupRefs.push(['group', curGid]);
+                // User's secondary group is listed in acRead, acWrite, or acFull.
                 acRefs.push(['acRead', curGid]);
                 acRefs.push(['acWrite', curGid]);
                 acRefs.push(['acFull', curGid]);
             }
+            // All the group refs.
             if (groupRefs.length) {
                 subSelectors.push({
                     type: '&',
@@ -368,6 +489,7 @@ class Tilmeld {
                     ],
                 });
             }
+            // All the acRead, acWrite, and acFull refs.
             if (acRefs.length) {
                 subSelectors.push({
                     type: '|',
@@ -376,8 +498,11 @@ class Tilmeld {
             }
             const selector = {
                 type: '|',
+                // Other access control is sufficient.
                 gte: [['acOther', nymph_1.TilmeldAccessLevels.READ_ACCESS]],
+                // The user and group are not set.
                 selector: subSelectors,
+                // The user is listed in acRead, acWrite, or acFull.
                 ref: [
                     ['acRead', user.guid],
                     ['acWrite', user.guid],
@@ -387,12 +512,76 @@ class Tilmeld {
             selectors.push(selector);
         }
     }
+    /**
+     * Check an entity's permissions for a user.
+     *
+     * This will check the AC (Access Control) properties of the entity. These
+     * include the following properties:
+     *
+     * - acUser
+     * - acGroup
+     * - acOther
+     * - acRead
+     * - acWrite
+     * - acFull
+     *
+     * "acUser" refers to the entity's owner, "acGroup" refers to all users in the
+     * entity's group and all ancestor groups, and "acOther" refers to any user
+     * who doesn't fit these descriptions.
+     *
+     * Each of these properties should be either NO_ACCESS, READ_ACCESS,
+     * WRITE_ACCESS, or FULL_ACCESS.
+     *
+     * - NO_ACCESS - the user has no access to the entity.
+     * - READ_ACCESS, the user has read access to the entity.
+     * - WRITE_ACCESS, the user has read and write access to the entity, but can't
+     *   delete it, change its access controls, or change its ownership.
+     * - FULL_ACCESS, the user has read, write, and delete access to the entity,
+     *   as well as being able to manage its access controls and ownership.
+     *
+     * These properties default to:
+     *
+     * - acUser = TilmeldAccessLevels.FULL_ACCESS
+     * - acGroup = TilmeldAccessLevels.READ_ACCESS
+     * - acOther = TilmeldAccessLevels.NO_ACCESS
+     *
+     * "acRead", "acWrite", and "acFull" are arrays of users and/or groups that
+     * also have those permissions.
+     *
+     * Only users with FULL_ACCESS have the ability to change any of the ac*,
+     * user, and group properties.
+     *
+     * The following conditions will result in different checks, which determine
+     * whether the check passes:
+     *
+     * - It is a user or group. (True for READ_ACCESS or Tilmeld admins.)
+     * - No user is logged in. (Check other AC.)
+     * - The entity is the user. (Always true.)
+     * - It is the user's primary group. (True for READ_ACCESS.)
+     * - The user or its groups are listed in "acRead". (True for READ_ACCESS.)
+     * - The user or its groups are listed in "acWrite". (True for READ_ACCESS and
+     *   WRITE_ACCESS.)
+     * - The user or its groups are listed in "acFull". (Always true.)
+     * - Its "user" is the user. (It is owned by the user.) (Check user AC.)
+     * - Its "group" is the user's primary group. (Check group AC.)
+     * - Its "group" is one of the user's secondary groups. (Check group AC.)
+     * - Its "group" is a descendant of one of the user's groups. (Check group
+     *   AC.)
+     * - None of the above. (Check other AC.)
+     *
+     * @param entity The entity to check.
+     * @param type The lowest level of permission to consider a pass.
+     * @param user The user to check permissions for. If null, uses the current user. If false, checks for public access.
+     * @param acProperties The acProperties to use instead of getting them from the entity.
+     * @returns Whether the current user has at least `type` permission for the entity.
+     */
     checkPermissions(entity, type = nymph_1.TilmeldAccessLevels.READ_ACCESS, user, acProperties) {
         if (!acProperties) {
             acProperties = entity.$getCurrentAcValues();
         }
         let userOrNull = null;
         let userOrEmpty = this.User.factorySync();
+        // Calculate the user.
         if (user == null) {
             userOrNull = this.currentUser;
             userOrEmpty = this.User.current(true);
@@ -401,29 +590,35 @@ class Tilmeld {
             userOrNull = user;
             userOrEmpty = user;
         }
+        // Users and groups are always readable. Editable by Tilmeld admins.
         if ((entity instanceof User_1.default || entity instanceof Group_1.default) &&
             (type === nymph_1.TilmeldAccessLevels.READ_ACCESS ||
                 userOrEmpty.abilities?.includes('tilmeld/admin') ||
                 userOrEmpty.abilities?.includes('system/admin'))) {
             return true;
         }
+        // Load access control, since we need it now...
         const acUser = acProperties.acUser ?? nymph_1.TilmeldAccessLevels.FULL_ACCESS;
         const acGroup = acProperties.acGroup ?? nymph_1.TilmeldAccessLevels.READ_ACCESS;
         const acOther = acProperties.acOther ?? nymph_1.TilmeldAccessLevels.NO_ACCESS;
         if (userOrNull == null) {
             return acOther >= type;
         }
+        // Check if the entity is the user.
         if (userOrEmpty.$is(entity)) {
             return true;
         }
+        // Check if the entity is the user's group. Always readable.
         const gid = userOrEmpty.$getGid();
         if (gid != null &&
             entity.guid === gid &&
             type === nymph_1.TilmeldAccessLevels.READ_ACCESS) {
             return true;
         }
+        // Calculate all the groups the user belongs to.
         let allGids = gid == null ? [] : [gid];
         allGids = allGids.concat(userOrEmpty.$getGids() ?? []);
+        // Check access ac properties.
         const checks = [
             {
                 type: nymph_1.TilmeldAccessLevels.FULL_ACCESS,
@@ -450,6 +645,7 @@ class Tilmeld {
                 }
             }
         }
+        // Check ownership ac properties.
         if (acProperties.user != null && acProperties.user === userOrNull.guid) {
             return acUser >= type;
         }
@@ -458,8 +654,33 @@ class Tilmeld {
         }
         return acOther >= type;
     }
+    /**
+     * Check a UID's permissions for a user.
+     *
+     * ## THIS ONLY CHECKS AUTOMATICALLY FOR CLIENT REQUESTS.
+     *
+     * UID functions on the Node.js side are not checked automatically. This
+     * function is only run automatically for UID functions run from the client.
+     * You should call this function manually if you're running a UID function on
+     * the Node.js side and you want it gated.
+     *
+     * This will check the Tilmeld config and the user's abilities.
+     *
+     * - READ_ACCESS, the UID is listed in clientReadableUIDs or the user has the
+     *   "uid/get/nameofuid" ability.
+     * - WRITE_ACCESS, the UID is listed in clientEnabledUIDs or the user has the
+     *   "uid/new/nameofuid" ability.
+     * - FULL_ACCESS, the UID is listed in clientSetabledUIDs or the user has the
+     *   "uid/set/nameofuid" ability.
+     *
+     * @param name The UID to check.
+     * @param type The lowest level of permission to consider a pass.
+     * @param user The user to check permissions for. If null, uses the current user. If false, checks for public access.
+     * @returns Whether the current user has at least `type` permission for the UID.
+     */
     async checkClientUIDPermissions(name, type = nymph_1.TilmeldAccessLevels.READ_ACCESS, user) {
         let userOrEmpty = this.User.factorySync();
+        // Calculate the user.
         if (user == null) {
             userOrEmpty = this.User.current(true);
         }
@@ -489,12 +710,21 @@ class Tilmeld {
         }
         return false;
     }
+    /**
+     * Fill session user data.
+     *
+     * @param user The user.
+     */
     async fillSession(user) {
         this.currentUser = user;
         this.gatekeeperCache = await user.$getGatekeeperCache();
+        // Now update the data protection on the user and all the groups.
         this.currentUser.$updateDataProtection();
         this.currentUser.$updateGroupDataProtection();
     }
+    /**
+     * Clear session user data.
+     */
     clearSession() {
         const user = this.currentUser;
         this.currentUser = null;
@@ -504,7 +734,14 @@ class Tilmeld {
             user.$updateGroupDataProtection();
         }
     }
+    /**
+     * Validate and extract the user from a token.
+     *
+     * @param token The authentication token.
+     * @returns The user on success, null on failure.
+     */
     async extractToken(token) {
+        this.nymph.config.debugLog('tilmeld', 'Extracting and validating token.');
         const extract = this.config.jwtExtract(this.config, token);
         if (extract == null) {
             return null;
@@ -519,18 +756,38 @@ class Tilmeld {
         }
         return user;
     }
-    async authenticate(skipXsrfToken = false) {
+    /**
+     * Check for TILMELDAUTH and TILMELDSWITCH tokens, and, if set, authenticate
+     * from it/them.
+     *
+     * You can also call this function after setting `response.locals.user` to the
+     * user you want to authenticate. You *should* check for `user.enabled` before
+     * setting this variable, unless you explicitly want to log in as a disabled
+     * user. (The user must be an instance of the User class for this Tilmeld
+     * instance.)
+     *
+     * This function will set `response.locals.user` to the logged in user on
+     * successful authentication.
+     *
+     * @param skipXsrfToken Skip the XSRF token check.
+     * @param skipRenew Skip the token renewal step, even if the token is close to expiration.
+     * @returns True if a user was authenticated, false on any failure.
+     */
+    async authenticate(skipXsrfToken = false, skipRenew = false) {
         if (this.request == null) {
             return false;
         }
         if (this.response &&
             this.response.locals.user &&
             this.response.locals.user instanceof this.User) {
+            // The user has already been authenticated through some other means.
             const user = this.response.locals.user;
             await this.fillSession(user);
             return true;
         }
         const cookies = this.request.cookies ?? {};
+        // If a client does't support cookies, they can use the X-TILMELDAUTH header
+        // to provide the auth token.
         let fromAuthHeader = false;
         let authToken;
         let switchToken;
@@ -555,12 +812,16 @@ class Tilmeld {
         let switchExtract;
         if (skipXsrfToken ||
             this.request.originalUrl.startsWith(this.config.setupPath)) {
+            // The request is for the setup app, or we were told to skip the XSRF
+            // check, so don't check for the XSRF token.
             authExtract = this.config.jwtExtract(this.config, authToken);
             switchExtract = switchToken
                 ? this.config.jwtExtract(this.config, switchToken)
                 : null;
         }
         else {
+            // The request is for something else, so check for a valid XSRF token,
+            // unless the auth token is provided by a header (instead of a cookie).
             const xsrfToken = this.request.header('x-xsrf-token');
             if (xsrfToken == null && !fromAuthHeader) {
                 return false;
@@ -589,6 +850,7 @@ class Tilmeld {
             return false;
         }
         if (switchGuid && switchExpire && switchExpire.getTime() > Date.now()) {
+            // Load the switch user.
             const switchUser = await this.User.factory(switchGuid);
             if (switchUser.guid == null) {
                 await this.logoutSwitch();
@@ -601,7 +863,10 @@ class Tilmeld {
                 return true;
             }
         }
-        if (expire.getTime() < Date.now() + this.config.jwtRenew * 1000) {
+        if (!skipRenew &&
+            expire.getTime() < Date.now() + this.config.jwtRenew * 1000) {
+            // If the user is less than renew time from needing a new token, give them
+            // a new one.
             await this.login(user, fromAuthHeader);
         }
         else {
@@ -612,6 +877,14 @@ class Tilmeld {
         }
         return true;
     }
+    /**
+     * Logs the given user into the system.
+     *
+     * @param user The user.
+     * @param sendAuthHeader Send the auth token as a custom header.
+     * @param sendCookie Send the auth token as a cookie.
+     * @returns True on success, false on failure.
+     */
     async login(user, sendAuthHeader, sendCookie = true) {
         if (user.guid != null && user.enabled) {
             if (this.response) {
@@ -624,7 +897,7 @@ class Tilmeld {
                             path: this.config.cookiePath,
                             maxAge: this.config.jwtExpire * 1000,
                             secure: appUrl.protocol === 'https:',
-                            httpOnly: false,
+                            httpOnly: false, // Allow JS access (for CSRF protection).
                             sameSite: appUrl.protocol === 'https:' ? 'lax' : 'strict',
                         });
                     }
@@ -639,6 +912,16 @@ class Tilmeld {
         }
         return false;
     }
+    /**
+     * Adds a switch auth token for the given user.
+     *
+     * This effectively logs the current user in to the system as the given user.
+     *
+     * @param user The user.
+     * @param sendAuthHeader Send the auth token as a custom header.
+     * @param sendCookie Send the auth token as a cookie.
+     * @returns True on success, false on failure.
+     */
     async loginSwitch(user, sendAuthHeader, sendCookie = true) {
         if (user.guid != null) {
             if (this.response) {
@@ -651,7 +934,7 @@ class Tilmeld {
                             path: this.config.cookiePath,
                             maxAge: this.config.jwtSwitchExpire * 1000,
                             secure: appUrl.protocol === 'https:',
-                            httpOnly: false,
+                            httpOnly: false, // Allow JS access (for PubSub auth token).
                             sameSite: appUrl.protocol === 'https:' ? 'lax' : 'strict',
                         });
                     }
@@ -666,6 +949,11 @@ class Tilmeld {
         }
         return false;
     }
+    /**
+     * Logs the current user out of the system.
+     *
+     * @param clearCookie Clear the auth cookie. (Also send a header.)
+     */
     async logout(clearCookie = true) {
         if (this.request && !this.alreadyLoggedOutSwitch) {
             const cookies = this.request.cookies ?? {};
@@ -686,6 +974,11 @@ class Tilmeld {
             this.response.locals.user = null;
         }
     }
+    /**
+     * Clears the switch user out of the system.
+     *
+     * @param clearCookie Clear the auth cookie. (Also send a header.)
+     */
     async logoutSwitch(clearCookie = true) {
         this.clearSession();
         if (this.response) {
@@ -697,7 +990,7 @@ class Tilmeld {
                 this.response.set('X-TILMELDSWITCH', '');
             }
             this.response.locals.user = null;
-            await this.authenticate();
+            await this.authenticate(false, true);
         }
     }
 }