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

package/dist/User.js

@@ -14,6 +14,15 @@ const qrcode_1 = require("qrcode");
 const enforceTilmeld_1 = require("./enforceTilmeld");
 const AbleObject_1 = __importDefault(require("./AbleObject"));
 const errors_1 = require("./errors");
+/**
+ * A user data model.
+ *
+ * Written by Hunter Perrin for SciActive.
+ *
+ * @author Hunter Perrin <hperrin@gmail.com>
+ * @copyright SciActive Inc
+ * @see http://nymph.io/
+ */
 class User extends AbleObject_1.default {
     static async factory(guid) {
         return (await super.factory(guid));
@@ -42,7 +51,11 @@ class User extends AbleObject_1.default {
         this.$privateData = [...User.DEFAULT_PRIVATE_DATA];
         this.$allowlistData = [...User.DEFAULT_ALLOWLIST_DATA];
         this.$allowlistTags = [];
+        /**
+         * This is explicitly used only during the registration proccess.
+         */
         this.$skipAcWhenSaving = false;
+        // Defaults.
         this.$data.enabled = true;
         this.$data.abilities = [];
         this.$data.groups = [];
@@ -56,6 +69,12 @@ class User extends AbleObject_1.default {
         }
         return tilmeld.currentUser;
     }
+    /**
+     * Send an account recovery link.
+     *
+     * @param data The input data from the client.
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     static async sendRecovery(data) {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
         if (!tilmeld.config.pwRecovery) {
@@ -67,6 +86,7 @@ class User extends AbleObject_1.default {
         let user;
         const options = {};
         if (!tilmeld.config.emailUsernames && data.recoveryType === 'username') {
+            // Create a username recovery email.
             const getUser = await this.nymph.getEntity({ class: tilmeld.User, skipAc: true }, {
                 type: '&',
                 ilike: ['email', data.account.replace(/([\\%_])/g, (s) => `\\${s}`)],
@@ -77,6 +97,7 @@ class User extends AbleObject_1.default {
                     message: 'Requested account is not accessible.',
                 };
             }
+            // Send the recovery email.
             user = getUser;
             options.template = 'RecoverUsername';
             options.message = {
@@ -88,6 +109,7 @@ class User extends AbleObject_1.default {
             options.locals = {};
         }
         else if (data.recoveryType === 'password') {
+            // Create a password recovery email.
             const getUser = await tilmeld.User.factoryUsername(data.account);
             if (getUser.guid == null) {
                 return {
@@ -95,11 +117,13 @@ class User extends AbleObject_1.default {
                     message: 'Requested account is not accessible.',
                 };
             }
+            // Create a unique secret.
             getUser.recoverSecret = (0, guid_1.humanSecret)();
             getUser.recoverSecretDate = Date.now();
             if (!(await getUser.$saveSkipAC())) {
                 return { result: false, message: "Couldn't save recovery secret." };
             }
+            // Send the recovery email.
             user = getUser;
             options.template = 'RecoverPassword';
             options.message = {
@@ -116,6 +140,8 @@ class User extends AbleObject_1.default {
         else {
             return { result: false, message: 'Invalid recovery type.' };
         }
+        this.nymph.config.debugLog('tilmeld', `User account recovery (${options.template}) request for "${user.username}".`);
+        // Send the email.
         if (await tilmeld.config.sendEmail(tilmeld, options, user)) {
             return {
                 result: true,
@@ -127,6 +153,12 @@ class User extends AbleObject_1.default {
             return { result: false, message: "Couldn't send recovery email." };
         }
     }
+    /**
+     * Recover account details.
+     *
+     * @param data The input data from the client.
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     static async recover(data) {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
         if (!tilmeld.config.pwRecovery) {
@@ -150,6 +182,7 @@ class User extends AbleObject_1.default {
         if (!('password' in data) || !data.password.length) {
             return { result: false, message: 'Password cannot be empty.' };
         }
+        this.nymph.config.debugLog('tilmeld', `User account recovery for "${user.username}".`);
         user.$password(data.password);
         delete user.recoverSecret;
         delete user.recoverSecretDate;
@@ -231,6 +264,8 @@ class User extends AbleObject_1.default {
                 message: e.message,
             };
         }
+        this.$nymph.config.debugLog('tilmeld', `User login for "${this.$data.username}".`);
+        // Authentication was successful, attempt to login.
         if (!(await tilmeld.login(this, true))) {
             return { result: false, message: 'Incorrect login/password.' };
         }
@@ -240,6 +275,7 @@ class User extends AbleObject_1.default {
                 await callback(this);
             }
         }
+        // Login was successful.
         return { result: true, message: 'You are logged in.' };
     }
     async $switchUser(data) {
@@ -286,6 +322,8 @@ class User extends AbleObject_1.default {
                 message: e.message,
             };
         }
+        this.$nymph.config.debugLog('tilmeld', `User login switch for "${user.username}" to "${this.$data.username}".`);
+        // Authentication was successful, attempt to login.
         if (!(await tilmeld.loginSwitch(this, true))) {
             return { result: false, message: 'Incorrect login/password.' };
         }
@@ -295,8 +333,13 @@ class User extends AbleObject_1.default {
                 await callback(this);
             }
         }
+        // Login was successful.
         return { result: true, message: 'You are logged in.' };
     }
+    /**
+     * Log a user out of the system.
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     async $logout() {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
         try {
@@ -313,6 +356,7 @@ class User extends AbleObject_1.default {
                 message: e.message,
             };
         }
+        this.$nymph.config.debugLog('tilmeld', `User logout for "${this.$data.username}".`);
         await tilmeld.logout();
         for (let callback of this.constructor
             .afterLogoutCallbacks) {
@@ -347,6 +391,9 @@ class User extends AbleObject_1.default {
         }
         return null;
     }
+    /**
+     * Get the user's group descendants.
+     */
     async $getDescendantGroups() {
         if (this.$descendantGroups == null) {
             this.$descendantGroups = [];
@@ -419,6 +466,11 @@ class User extends AbleObject_1.default {
         super.$putData(data, sdata);
         this.$updateDataProtection();
     }
+    /**
+     * Update the data protection arrays for a user.
+     *
+     * @param givenUser User to update protection for. If undefined, will use the currently logged in user.
+     */
     $updateDataProtection(givenUser) {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
         let user = givenUser ?? tilmeld.User.current();
@@ -429,11 +481,14 @@ class User extends AbleObject_1.default {
             this.$privateData.push('username');
         }
         const isCurrentUser = user != null && user.$is(this);
+        // While loading, accessing abilities on the current user will infinitely
+        // loop, but if this is the current user, we can use its abilities.
         const abilities = (isCurrentUser || user == null
             ? this.$data.abilities
             : user?.abilities) ?? [];
         const isNewUser = this.guid == null;
         if (isCurrentUser) {
+            // Users can check to see what abilities they have.
             this.$clientEnabledMethods.push('$gatekeeper');
             this.$clientEnabledMethods.push('$changePassword');
             this.$clientEnabledMethods.push('$revokeCurrentTokens');
@@ -447,12 +502,14 @@ class User extends AbleObject_1.default {
         if (user != null &&
             (abilities.includes('tilmeld/admin') ||
                 abilities.includes('system/admin'))) {
+            // Users who can edit other users can see most of their data.
             this.$privateData = ['password', 'salt', 'totpSecret'];
             this.$clientEnabledMethods.push('$hasTOTPSecret');
             this.$clientEnabledMethods.push('$removeTOTPSecret');
             this.$allowlistData = undefined;
         }
         else if (isCurrentUser || isNewUser) {
+            // Users can see their own data, and edit some of it.
             if (tilmeld.config.allowUsernameChange || isNewUser) {
                 this.$allowlistData.push('username');
             }
@@ -470,10 +527,24 @@ class User extends AbleObject_1.default {
                 this.$allowlistData.push('phone');
             }
             this.$privateData = [
+                // The things that are commented are there to show what is _not_ private.
+                // 'abilities',
+                // 'username',
+                // 'nameFirst',
+                // 'nameMiddle',
+                // 'nameLast',
+                // 'name',
+                // 'email',
+                // 'avatar',
+                // 'phone',
+                // 'group',
+                // 'groups',
+                // 'inheritAbilities',
                 'enabled',
                 'secret',
                 'emailChangeDate',
                 'newEmailSecret',
+                // 'newEmailAddress',
                 'cancelEmailSecret',
                 'cancelEmailAddress',
                 'recoverSecret',
@@ -481,6 +552,7 @@ class User extends AbleObject_1.default {
                 'salt',
                 'password',
                 'passwordTemp',
+                // 'revokeTokenDate',
                 'totpSecret',
             ];
         }
@@ -488,6 +560,7 @@ class User extends AbleObject_1.default {
             !isCurrentUser &&
             (abilities.includes('tilmeld/switch') ||
                 abilities.includes('system/admin'))) {
+            // Users with this ability can switch to other users.
             this.$clientEnabledMethods.push('$switchUser');
         }
     }
@@ -501,18 +574,36 @@ class User extends AbleObject_1.default {
             }
         }
     }
+    /**
+     * Check to see if a user has an ability.
+     *
+     * This function will check both user and group abilities, if the user is
+     * marked to inherit the abilities of its group.
+     *
+     * If `ability` is undefined, it will check to see if the user is currently
+     * logged in.
+     *
+     * If the user has the "system/admin" ability, this function will return true.
+     *
+     * @param ability The ability.
+     * @returns True or false.
+     */
     async $gatekeeper(ability) {
         await this.$wake();
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
         if (ability == null) {
             return tilmeld.User.current()?.$is(this) ?? false;
         }
+        // Check the cache to see if we've already checked this user.
         if (this.$gatekeeperCache == null) {
             this.$gatekeeperCache = await this.$getGatekeeperCache();
         }
         return ((ability in this.$gatekeeperCache && !!this.$gatekeeperCache[ability]) ||
             !!this.$data.abilities?.includes('system/admin'));
     }
+    /**
+     * Build a gatekeeper cache object.
+     */
     async $getGatekeeperCache() {
         await this.$wake();
         let abilities = this.$data.abilities ?? [];
@@ -537,6 +628,11 @@ class User extends AbleObject_1.default {
         this.$gatekeeperCache = undefined;
         return ret;
     }
+    /**
+     * Send the user email verification/change/cancellation links.
+     *
+     * @returns True on success, false on failure.
+     */
     async $sendEmailVerification() {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
         if (this.guid == null) {
@@ -601,6 +697,12 @@ class User extends AbleObject_1.default {
         }
         return success;
     }
+    /**
+     * Add the user to a (secondary) group.
+     *
+     * @param group The group.
+     * @returns True if the user is already in the group. The resulting array of groups if the user was not.
+     */
     async $addGroup(group) {
         await Promise.all(this.$data.groups?.map((e) => e.$wake()) || []);
         let groups = this.$data.groups;
@@ -614,6 +716,12 @@ class User extends AbleObject_1.default {
         }
         return true;
     }
+    /**
+     * Check the given password against the user's.
+     *
+     * @param password The password in question.
+     * @returns True if the passwords match, otherwise false.
+     */
     $checkPassword(password) {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
         switch (tilmeld.config.pwMethod) {
@@ -627,6 +735,12 @@ class User extends AbleObject_1.default {
                     (0, sha256_1.default)(password + this.$data.salt).toString(enc_base64_1.default));
         }
     }
+    /**
+     * Remove the user from a (secondary) group.
+     *
+     * @param group The group.
+     * @returns True if the user wasn't in the group. The resulting array of groups if the user was.
+     */
     async $delGroup(group) {
         await Promise.all(this.$data.groups?.map((e) => e.$wake()) || []);
         let groups = this.$data.groups || [];
@@ -642,6 +756,12 @@ class User extends AbleObject_1.default {
         }
         return true;
     }
+    /**
+     * Check whether the user is in a (primary or secondary) group.
+     *
+     * @param group The group, or the group's GUID.
+     * @returns True or false.
+     */
     async $inGroup(group) {
         if (typeof group === 'string') {
             if (this.$data.group?.guid === group) {
@@ -656,7 +776,14 @@ class User extends AbleObject_1.default {
         }
         return (group.$is(this.$data.group) || group.$inArray(this.$data.groups ?? []));
     }
+    /**
+     * Check whether the user is a descendant of a group.
+     *
+     * @param group The group, or the group's GUID.
+     * @returns True or false.
+     */
     async $isDescendant(group) {
+        // Check to see if the user is in a descendant group of the given group.
         await this.$data.group?.$wake();
         if (this.$data.group != null &&
             this.$data.group?.cdate != null &&
@@ -671,11 +798,19 @@ class User extends AbleObject_1.default {
         }
         return false;
     }
+    /**
+     * A frontend accessible method to change the user's password.
+     *
+     * @param data The input data from the client.
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     async $changePassword(data) {
+        this.$nymph.config.debugLog('tilmeld', `Password change request for "${this.$data.username}".`);
         if (!('newPassword' in data) || !data.newPassword.length) {
             return { result: false, message: 'Please specify a password.' };
         }
         if (!this.$checkPassword(data.currentPassword ?? '')) {
+            this.$nymph.config.debugLog('tilmeld', `Incorrect password for change request for "${this.$data.username}".`);
             return { result: false, message: 'Incorrect password.' };
         }
         this.$data.passwordTemp = data.newPassword;
@@ -693,6 +828,12 @@ class User extends AbleObject_1.default {
             return { result: false, message: "Couldn't save new password." };
         }
     }
+    /**
+     * Change the user's password.
+     *
+     * @param password The new password.
+     * @returns The resulting password or hash which is stored in the entity.
+     */
     $password(password) {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
         switch (tilmeld.config.pwMethod) {
@@ -712,6 +853,12 @@ class User extends AbleObject_1.default {
         }
         return this.$data.password;
     }
+    /**
+     * A frontend accessible method to revoke all currently issued tokens.
+     *
+     * @param data The input data from the client.
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     async $revokeCurrentTokens(data) {
         if (!this.$checkPassword(data.password ?? '')) {
             return { result: false, message: 'Incorrect password.' };
@@ -732,6 +879,12 @@ class User extends AbleObject_1.default {
     async $hasTOTPSecret() {
         return this.$data.totpSecret != null;
     }
+    /**
+     * Check the given code against the user's TOTP secret.
+     *
+     * @param code The code in question.
+     * @returns True if the code is valid, otherwise false.
+     */
     $checkTOTPCode(code) {
         if (this.$data.totpSecret == null) {
             return false;
@@ -747,6 +900,11 @@ class User extends AbleObject_1.default {
         });
         return totp.validate({ token: code, window: 2 }) != null;
     }
+    /**
+     * A frontend accessible method to generate a new TOTP secret.
+     *
+     * @returns An object with 'uri', 'qrcode', and 'secret'.
+     */
     async $getNewTOTPSecret() {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
         if (this.$data.totpSecret != null) {
@@ -769,6 +927,12 @@ class User extends AbleObject_1.default {
             secret: secret.base32,
         };
     }
+    /**
+     * A frontend accessible method to save a TOTP secret into the user's account.
+     *
+     * @param data The input data from the client.
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     async $saveTOTPSecret(data) {
         if (!this.$checkPassword(data.password ?? '')) {
             return { result: false, message: 'Incorrect password.' };
@@ -806,6 +970,13 @@ class User extends AbleObject_1.default {
             return { result: false, message: "Couldn't save two factor secret." };
         }
     }
+    /**
+     * A frontend accessible method to remove the TOTP secret from the user's
+     * account.
+     *
+     * @param data The input data from the client.
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     async $removeTOTPSecret(data) {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
         if (data) {
@@ -849,8 +1020,14 @@ class User extends AbleObject_1.default {
             return { result: false, message: "Couldn't remove two factor secret." };
         }
     }
+    /**
+     * Check that a username is valid.
+     *
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     async $checkUsername() {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
+        this.$nymph.config.debugLog('tilmeld', `Username check "${this.$data.username}".`);
         if (!tilmeld.config.emailUsernames) {
             if (this.$data.username == null || !this.$data.username.length) {
                 return { result: false, message: 'Please specify a username.' };
@@ -937,8 +1114,14 @@ class User extends AbleObject_1.default {
             return await this.$checkEmail();
         }
     }
+    /**
+     * Check that an email is unique.
+     *
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     async $checkEmail() {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
+        this.$nymph.config.debugLog('tilmeld', `Email check "${this.$data.email}".`);
         if (this.$data.email == null || !this.$data.email.length) {
             if (tilmeld.config.verifyEmail) {
                 return { result: false, message: 'Please specify an email.' };
@@ -972,8 +1155,14 @@ class User extends AbleObject_1.default {
             message: this.guid != null ? 'Email is valid.' : 'Email address is valid!',
         };
     }
+    /**
+     * Check that a phone number is unique.
+     *
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     async $checkPhone() {
         const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(this);
+        this.$nymph.config.debugLog('tilmeld', `Phone check "${this.$data.phone}".`);
         if (this.$data.phone == null || !this.$data.phone.length) {
             return { result: false, message: 'Please specify a phone number.' };
         }
@@ -1040,6 +1229,7 @@ class User extends AbleObject_1.default {
         if (tilmeld.config.emailUsernames) {
             this.$data.email = this.$data.username;
         }
+        // Start transaction.
         const transaction = 'tilmeld-register-' + (0, guid_1.nanoid)();
         const nymph = this.$nymph;
         const tnymph = await this.$nymph.startTransaction(transaction);
@@ -1065,8 +1255,10 @@ class User extends AbleObject_1.default {
                     message: e.message,
                 };
             }
+            // Add primary group.
             let generatedPrimaryGroup = null;
             if (tilmeld.config.generatePrimary) {
+                // Generate a new primary group for the user.
                 generatedPrimaryGroup = await tilmeld.Group.factory();
                 generatedPrimaryGroup.groupname = this.$data.username;
                 generatedPrimaryGroup.avatar = this.$data.avatar;
@@ -1095,6 +1287,7 @@ class User extends AbleObject_1.default {
                 this.$data.group = generatedPrimaryGroup;
             }
             else {
+                // Add the default primary.
                 const group = await tnymph.getEntity({ class: tilmeld.Group }, {
                     type: '&',
                     equal: ['defaultPrimary', true],
@@ -1103,15 +1296,18 @@ class User extends AbleObject_1.default {
                     this.$data.group = group;
                 }
             }
+            // Add secondary groups.
             if (tilmeld.config.userFields.includes('email') &&
                 tilmeld.config.verifyEmail &&
                 tilmeld.config.unverifiedAccess) {
+                // Add the default secondaries for unverified users.
                 this.$data.groups = await tnymph.getEntities({ class: tilmeld.Group }, {
                     type: '&',
                     equal: ['unverifiedSecondary', true],
                 });
             }
             else {
+                // Add the default secondaries.
                 this.$data.groups = await tnymph.getEntities({ class: tilmeld.Group }, {
                     type: '&',
                     equal: ['defaultSecondary', true],
@@ -1119,6 +1315,7 @@ class User extends AbleObject_1.default {
             }
             if (tilmeld.config.userFields.includes('email') &&
                 tilmeld.config.verifyEmail) {
+                // The user will be enabled after verifying their e-mail address.
                 if (!tilmeld.config.unverifiedAccess) {
                     this.$data.enabled = false;
                 }
@@ -1126,6 +1323,8 @@ class User extends AbleObject_1.default {
             else {
                 this.$data.enabled = true;
             }
+            // If create_admin is true and there are no other users, grant
+            // "system/admin".
             let madeAdmin = false;
             if (tilmeld.config.createAdmin) {
                 const otherUsers = await tnymph.getEntities({
@@ -1134,13 +1333,17 @@ class User extends AbleObject_1.default {
                     limit: 1,
                     return: 'guid',
                 });
+                // Make sure it's not just null, cause that means an error.
                 if (!otherUsers.length) {
                     this.$grant('system/admin');
                     this.$data.enabled = true;
                     madeAdmin = true;
                 }
             }
+            this.$nymph.config.debugLog('tilmeld', `Registering new user "${this.$data.username}".`);
             if (await this.$saveSkipAC()) {
+                this.$nymph.config.debugLog('tilmeld', `New user registered "${this.$data.username}".`);
+                // Send the new user registered email.
                 if (tilmeld.config.userRegisteredRecipient != null) {
                     await tilmeld.config.sendEmail(tilmeld, {
                         template: 'UserRegistered',
@@ -1157,6 +1360,7 @@ class User extends AbleObject_1.default {
                         },
                     }, this);
                 }
+                // Save the primary group.
                 if (generatedPrimaryGroup != null) {
                     generatedPrimaryGroup.user = this;
                     if (!(await generatedPrimaryGroup.$saveSkipAC())) {
@@ -1169,6 +1373,7 @@ class User extends AbleObject_1.default {
                         };
                     }
                 }
+                // Finish up.
                 if (tilmeld.config.verifyEmail &&
                     !tilmeld.config.unverifiedAccess &&
                     !madeAdmin &&
@@ -1210,6 +1415,7 @@ class User extends AbleObject_1.default {
             else {
                 await tnymph.rollback(transaction);
                 this.$nymph = nymph;
+                this.$nymph.config.debugError('tilmeld', `Error registering new user "${this.$data.username}".`);
                 return {
                     result: false,
                     loggedin: false,
@@ -1220,6 +1426,7 @@ class User extends AbleObject_1.default {
         catch (e) {
             await tnymph.rollback(transaction);
             this.$nymph = nymph;
+            this.$nymph.config.debugError('tilmeld', `Error registering new user "${this.$data.username}": ${e}`);
             throw e;
         }
         try {
@@ -1247,6 +1454,7 @@ class User extends AbleObject_1.default {
             throw new errors_1.BadDataError("You don't have the authority to modify system admins.");
         }
         let sendVerification = false;
+        // Formatting.
         this.$data.username = this.$data.username.trim();
         if (tilmeld.config.emailUsernames) {
             this.$data.email = this.$data.username;
@@ -1260,6 +1468,7 @@ class User extends AbleObject_1.default {
                 (this.$data.nameMiddle ? ' ' + this.$data.nameMiddle : '') +
                 (this.$data.nameLast ? ' ' + this.$data.nameLast : '');
         this.$data.enabled = !!this.$data.enabled;
+        // Clear empty values.
         if (this.$data.nameFirst === '' ||
             !tilmeld.config.userFields.includes('name')) {
             delete this.$data.nameFirst;
@@ -1327,6 +1536,7 @@ class User extends AbleObject_1.default {
         if (this.$data.inheritAbilities === false) {
             delete this.$data.inheritAbilities;
         }
+        // Verification.
         const unCheck = await this.$checkUsername();
         if (!unCheck.result) {
             throw new errors_1.BadUsernameError(unCheck.message);
@@ -1338,10 +1548,16 @@ class User extends AbleObject_1.default {
                 throw new errors_1.BadEmailError(emCheck.message);
             }
         }
+        // Email changes.
         if (!tilmeld.gatekeeper('tilmeld/admin') &&
             tilmeld.config.userFields.includes('email')) {
+            // The user isn't an admin, so email address changes should contain some
+            // security measures.
             if (tilmeld.config.verifyEmail) {
+                // The user needs to verify this new email address.
                 if (this.guid == null) {
+                    // If this is the first user, they'll be made an admin, so they don't
+                    // need to verify.
                     if (!this.$data.abilities?.includes('system/admin')) {
                         this.$data.secret = (0, guid_1.nanoid)();
                         sendVerification = true;
@@ -1349,6 +1565,7 @@ class User extends AbleObject_1.default {
                 }
                 else if (this.$originalEmail != null &&
                     this.$originalEmail !== this.$data.email) {
+                    // The user already has an old email address.
                     if (tilmeld.config.emailRateLimit !== '' &&
                         this.$data.emailChangeDate != null &&
                         this.$data.emailChangeDate >=
@@ -1360,13 +1577,18 @@ class User extends AbleObject_1.default {
                     else {
                         if (this.$data.newEmailSecret == null &&
                             tilmeld.config.emailRateLimit !== '' &&
+                            // Make sure the user has at least the rate limit time to cancel
+                            // an email change.
                             (this.$data.emailChangeDate == null ||
                                 this.$data.emailChangeDate <
                                     (0, strtotime_1.default)('-' + tilmeld.config.emailRateLimit) * 1000)) {
+                            // Save the old email in case the cancel change link is clicked.
                             this.$data.cancelEmailAddress = this.$originalEmail;
                             this.$data.cancelEmailSecret = (0, guid_1.nanoid)();
                             this.$data.emailChangeDate = Date.now();
                         }
+                        // Save the new address and reset to the old one (until they verify
+                        // it).
                         this.$data.newEmailAddress = this.$data.email;
                         this.$data.email = this.$originalEmail;
                         if (tilmeld.config.emailUsernames) {
@@ -1380,9 +1602,13 @@ class User extends AbleObject_1.default {
             else if (this.guid != null &&
                 this.$originalEmail != null &&
                 this.$originalEmail !== this.$data.email &&
+                // Make sure the user has at least the rate limit time to cancel an
+                // email change.
                 (this.$data.emailChangeDate == null ||
                     this.$data.emailChangeDate <
                         (0, strtotime_1.default)('-' + tilmeld.config.emailRateLimit) * 1000)) {
+                // The user doesn't need to verify their new email address, but should
+                // be able to cancel the email change from their old address.
                 this.$data.cancelEmailAddress = this.$originalEmail;
                 this.$data.cancelEmailSecret = (0, guid_1.nanoid)();
                 sendVerification = true;
@@ -1401,6 +1627,7 @@ class User extends AbleObject_1.default {
         catch (e) {
             throw new errors_1.BadDataError(e?.message);
         }
+        // Start transaction.
         const transaction = 'tilmeld-save-' + (0, guid_1.nanoid)();
         const nymph = this.$nymph;
         const tnymph = await this.$nymph.startTransaction(transaction);
@@ -1410,6 +1637,7 @@ class User extends AbleObject_1.default {
         await group?.$wake();
         if (group != null && group.user != null && this.$is(group.user)) {
             try {
+                // Update the user's generated primary group.
                 group.groupname = this.$data.username;
                 group.avatar = this.$data.avatar;
                 if (tilmeld.config.userFields.includes('email')) {
@@ -1444,6 +1672,7 @@ class User extends AbleObject_1.default {
         }
         if (ret) {
             if (sendVerification) {
+                // The email has changed, so send a new verification email.
                 if (!(await this.$sendEmailVerification())) {
                     await tnymph.rollback(transaction);
                     this.guid = preGuid;
@@ -1458,6 +1687,7 @@ class User extends AbleObject_1.default {
             await tnymph.commit(transaction);
             const tilmeld = (0, enforceTilmeld_1.enforceTilmeld)(nymph);
             if (tilmeld.User.current(true).$is(this)) {
+                // Update the user in the session cache.
                 await tilmeld.fillSession(this);
             }
         }
@@ -1467,6 +1697,9 @@ class User extends AbleObject_1.default {
         this.$nymph = nymph;
         return ret;
     }
+    /**
+     * This should *never* be accessible on the client.
+     */
     async $saveSkipAC() {
         this.$skipAcWhenSaving = true;
         return await this.$save();
@@ -1497,6 +1730,7 @@ class User extends AbleObject_1.default {
         if (!(prop in this)) {
             throw new Error('Invalid event type.');
         }
+        // @ts-ignore: The callback should always be the right type here.
         this[prop].push(callback);
         return () => this.off(event, callback);
     }
@@ -1505,13 +1739,18 @@ class User extends AbleObject_1.default {
         if (!(prop in this)) {
             return false;
         }
+        // @ts-ignore: The callback should always be the right type here.
         const i = this[prop].indexOf(callback);
         if (i > -1) {
+            // @ts-ignore: The callback should always be the right type here.
             this[prop].splice(i, 1);
         }
         return true;
     }
 }
+/**
+ * The instance of Tilmeld to use for queries.
+ */
 User.ETYPE = 'tilmeld_user';
 User.class = 'User';
 User.checkUsernameCallbacks = [];
@@ -1529,8 +1768,15 @@ User.DEFAULT_CLIENT_ENABLED_METHODS = [
     '$register',
 ];
 User.DEFAULT_PRIVATE_DATA = [
+    // The things that are commented are there to show what is _not_ private.
     'abilities',
+    // 'username',
+    // 'nameFirst',
+    // 'nameMiddle',
+    // 'nameLast',
+    // 'name',
     'email',
+    // 'avatar',
     'phone',
     'group',
     'groups',