@digitaldefiance/node-express-suite-mongo 4.23.0

package/src/services/user.js

@@ -0,0 +1,1504 @@
+"use strict";
+/**
+ * @fileoverview Comprehensive user management service.
+ * Handles user authentication, registration, password management, email verification,
+ * mnemonic recovery, backup codes, and all user-related operations.
+ * @module services/user
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserService = void 0;
+const tslib_1 = require("tslib");
+const ecies_lib_1 = require("@digitaldefiance/ecies-lib");
+const mongoose_types_1 = require("@digitaldefiance/mongoose-types");
+const node_ecies_lib_1 = require("@digitaldefiance/node-ecies-lib");
+const suite_core_lib_1 = require("@digitaldefiance/suite-core-lib");
+const suite_core_lib_2 = require("@digitaldefiance/suite-core-lib");
+const crypto_1 = require("crypto");
+const validator_1 = tslib_1.__importDefault(require("validator"));
+const node_express_suite_1 = require("@digitaldefiance/node-express-suite");
+const model_registry_1 = require("../model-registry");
+const mnemonic_1 = require("./mnemonic");
+const request_user_1 = require("./request-user");
+const base_model_name_1 = require("../enumerations/base-model-name");
+const mongoose_validation_1 = require("../errors/mongoose-validation");
+const direct_login_token_1 = require("./direct-login-token");
+/**
+ * Comprehensive service for user management and authentication.
+ * Provides methods for user creation, authentication (mnemonic/password/challenge),
+ * email verification, password reset, backup code recovery, and settings management.
+ * @template T - User document type
+ * @template TID - Platform ID type
+ * @template TDate - Date type
+ * @template TLanguage - String type for site language
+ * @template TAccountStatus - String type for account status
+ * @template _TEnvironment - Environment type
+ * @template _TConstants - Constants type
+ * @template _TBaseDocument - Base document type
+ * @template TUser - User base interface type
+ * @template TTokenRole - Token role interface type
+ * @template TApplication - Application interface type
+ * @extends {BaseService<TID, TApplication>}
+ */
+class UserService extends node_express_suite_1.BaseService {
+    roleService;
+    eciesService;
+    keyWrappingService;
+    mnemonicService;
+    emailService;
+    backupCodeService;
+    serverUrl;
+    disableEmailSend;
+    constructor(application, roleService, emailService, keyWrappingService, backupCodeService) {
+        super(application);
+        this.roleService = roleService;
+        this.emailService = emailService;
+        this.keyWrappingService = keyWrappingService;
+        this.backupCodeService = backupCodeService;
+        this.serverUrl = application.environment.serverUrl;
+        this.disableEmailSend = application.environment.disableEmailSend;
+        const config = {
+            curveName: this.application.constants.ECIES.CURVE_NAME,
+            primaryKeyDerivationPath: this.application.constants.ECIES.PRIMARY_KEY_DERIVATION_PATH,
+            mnemonicStrength: this.application.constants.ECIES.MNEMONIC_STRENGTH,
+            symmetricAlgorithm: this.application.constants.ECIES.SYMMETRIC_ALGORITHM_CONFIGURATION,
+            symmetricKeyBits: this.application.constants.ECIES.SYMMETRIC.KEY_BITS,
+            symmetricKeyMode: this.application.constants.ECIES.SYMMETRIC.MODE,
+        };
+        this.eciesService = new node_ecies_lib_1.ECIESService(config);
+        const mnemonicModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.Mnemonic);
+        this.mnemonicService = new mnemonic_1.MnemonicService(mnemonicModel, application.environment.mnemonicHmacSecret, this.application.constants);
+    }
+    /**
+     * Given a User Document, make a User DTO
+     * @param user a User Document
+     * @returns An IUserDTO
+     */
+    static userToUserDTO(user) {
+        const provider = (0, node_ecies_lib_1.getEnhancedNodeIdProvider)();
+        const userId = user._id;
+        return {
+            ...(user instanceof mongoose_types_1.Document ? user.toObject() : user),
+            _id: provider.validate(provider.toBytes(userId)) &&
+                provider.idToString(userId),
+            createdAt: (user.createdAt instanceof Date
+                ? user.createdAt.toString()
+                : user.createdAt),
+            createdBy: provider.validate(provider.toBytes(user.createdBy)) &&
+                provider.idToString(user.createdBy),
+            updatedAt: (user.updatedAt instanceof Date
+                ? user.updatedAt.toString()
+                : user.updatedAt),
+            updatedBy: provider.validate(provider.toBytes(user.updatedBy)) &&
+                provider.idToString(user.updatedBy),
+            ...(user.lastLogin
+                ? {
+                    lastLogin: (user.lastLogin instanceof Date
+                        ? user.lastLogin.toString()
+                        : user.lastLogin),
+                }
+                : {}),
+            ...(user.deletedAt
+                ? {
+                    deletedAt: (user.deletedAt instanceof Date
+                        ? user.deletedAt.toString()
+                        : user.deletedAt),
+                }
+                : {}),
+            ...(user.deletedBy
+                ? {
+                    deletedBy: provider.validate(provider.toBytes(user.deletedBy)) &&
+                        provider.idToString(user.deletedBy),
+                }
+                : {}),
+        };
+    }
+    /**
+     * Given a User DTO, reconstitute ids and dates
+     * @param user a User DTO
+     * @returns An IUserBackendObject
+     */
+    hydrateUserDTOToBackend(user) {
+        const provider = (0, node_ecies_lib_1.getEnhancedNodeIdProvider)();
+        return {
+            ...user,
+            _id: provider.idFromString(user._id),
+            ...(user.lastLogin ? { lastLogin: new Date(user.lastLogin) } : {}),
+            createdAt: new Date(user.createdAt),
+            createdBy: provider.idFromString(user.createdBy),
+            updatedAt: new Date(user.updatedAt),
+            updatedBy: provider.idFromString(user.updatedBy),
+            ...(user.deletedAt ? { deletedAt: new Date(user.deletedAt) } : {}),
+            ...(user.deletedBy
+                ? {
+                    deletedBy: provider.idFromString(user.deletedBy),
+                }
+                : {}),
+            ...(user.mnemonicId
+                ? { mnemonicId: provider.idFromString(user.mnemonicId) }
+                : {}),
+        };
+    }
+    /**
+     * Create a new email token to send to the user for email verification
+     * @param userDoc The user to create the email token for
+     * @param type The type of email token to create
+     * @param session The session to use for the query
+     * @returns The email token document
+     */
+    async createEmailToken(userDoc, type, session) {
+        const EmailTokenModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.EmailToken);
+        // If we already have a session, use it directly to avoid nested transactions
+        if (session) {
+            const now = new Date();
+            const tokenData = {
+                userId: userDoc._id,
+                type: type,
+                email: userDoc.email,
+                token: (0, crypto_1.randomBytes)(this.application.constants.EmailTokenLength).toString('hex'),
+                createdAt: now,
+                updatedAt: now,
+                expiresAt: new Date(now.getTime() + this.application.constants.EmailTokenExpiration),
+            };
+            // Use findOneAndUpdate with upsert to avoid duplicate key errors
+            const emailToken = await EmailTokenModel.findOneAndUpdate({
+                userId: userDoc._id,
+                email: userDoc.email,
+                type: type,
+            }, tokenData, {
+                upsert: true,
+                new: true,
+                session,
+            });
+            if (!emailToken) {
+                throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_FailedToCreateEmailToken);
+            }
+            return emailToken;
+        }
+        // Only create a new transaction if no session is provided
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const now = new Date();
+            const tokenData = {
+                userId: userDoc._id,
+                type: type,
+                email: userDoc.email,
+                token: (0, crypto_1.randomBytes)(this.application.constants.EmailTokenLength).toString('hex'),
+                createdAt: now,
+                updatedAt: now,
+                expiresAt: new Date(now.getTime() + this.application.constants.EmailTokenExpiration),
+            };
+            // Use findOneAndUpdate with upsert to avoid duplicate key errors
+            const emailToken = await EmailTokenModel.findOneAndUpdate({
+                userId: userDoc._id,
+                email: userDoc.email,
+                type: type,
+            }, tokenData, {
+                upsert: true,
+                new: true,
+                session: sess,
+            });
+            if (!emailToken) {
+                throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_FailedToCreateEmailToken);
+            }
+            return emailToken;
+        }, undefined, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout,
+        });
+    }
+    /**
+     * Create and send an email token to the user for email verification
+     * @param user The user to send the email token to
+     * @param type The type of email token to send
+     * @param session The session to use for the query
+     * @returns The email token document
+     */
+    async createAndSendEmailToken(user, type = suite_core_lib_1.EmailTokenType.AccountVerification, session, debug = false) {
+        const emailToken = await this.createEmailToken(user, type, session);
+        try {
+            await this.sendEmailToken(emailToken, session, debug);
+        }
+        catch {
+            // keep parity with previous behavior: continue returning token even if email send fails
+        }
+        return emailToken;
+    }
+    /**
+     * Create and send an email token directly within an existing transaction
+     * @param user The user to send the email token to
+     * @param type The type of email token to send
+     * @param session The session to use for the query (required)
+     * @param debug Whether to enable debug logging
+     * @returns The email token document
+     */
+    async createAndSendEmailTokenDirect(user, type = suite_core_lib_1.EmailTokenType.AccountVerification, session, debug = false) {
+        const EmailTokenModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.EmailToken);
+        // Create token directly within the existing session using upsert
+        const now = new Date();
+        const tokenData = {
+            userId: user._id,
+            type: type,
+            email: user.email,
+            token: (0, crypto_1.randomBytes)(this.application.constants.EmailTokenLength).toString('hex'),
+            createdAt: now,
+            updatedAt: now,
+            expiresAt: new Date(now.getTime() + this.application.constants.EmailTokenExpiration),
+        };
+        // Use findOneAndUpdate with upsert to avoid duplicate key errors
+        const emailToken = await EmailTokenModel.findOneAndUpdate({
+            userId: user._id,
+            email: user.email,
+            type: type,
+        }, tokenData, {
+            upsert: true,
+            new: true,
+            session,
+        });
+        if (!emailToken) {
+            throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_FailedToCreateEmailToken);
+        }
+        try {
+            await this.sendEmailToken(emailToken, session, debug);
+        }
+        catch {
+            // Ignore email send errors in direct token creation
+        }
+        return emailToken;
+    }
+    /**
+     * Send an email token to the user for email verification
+     * @param emailToken The email token to send
+     * @param session The session to use for the query
+     * @returns void
+     */
+    async sendEmailToken(emailToken, session, debug = false) {
+        if (this.disableEmailSend) {
+            (0, node_express_suite_1.debugLog)(debug, 'log', 'Email sending disabled for testing');
+            // Still update lastSent and expiration to keep token valid during tests
+            emailToken.lastSent = new Date();
+            emailToken.expiresAt = new Date(Date.now() + this.application.constants.EmailTokenExpiration);
+            await emailToken.save({ session });
+            return;
+        }
+        if (emailToken.lastSent &&
+            emailToken.lastSent.getTime() +
+                this.application.constants.EmailTokenResendInterval >
+                Date.now()) {
+            throw new suite_core_lib_1.EmailTokenSentTooRecentlyError(emailToken.lastSent);
+        }
+        let subjectString;
+        let bodyString;
+        let url;
+        switch (emailToken.type) {
+            case suite_core_lib_1.EmailTokenType.AccountVerification:
+                subjectString = suite_core_lib_1.SuiteCoreStringKey.Email_ConfirmationSubjectTemplate;
+                bodyString = suite_core_lib_1.SuiteCoreStringKey.Email_ConfirmationBody;
+                url = `${this.serverUrl}/verify-email?token=${emailToken.token}`;
+                break;
+            case suite_core_lib_1.EmailTokenType.PasswordReset:
+                subjectString = suite_core_lib_1.SuiteCoreStringKey.Email_ResetPasswordSubjectTemplate;
+                bodyString = suite_core_lib_1.SuiteCoreStringKey.Email_ResetPasswordBody;
+                url = `${this.serverUrl}/forgot-password?token=${emailToken.token}`;
+                break;
+            case suite_core_lib_1.EmailTokenType.LoginRequest:
+                subjectString = suite_core_lib_1.SuiteCoreStringKey.Email_LoginRequestSubjectTemplate;
+                bodyString = suite_core_lib_1.SuiteCoreStringKey.Email_LoginRequestBody;
+                url = `${this.serverUrl}/challenge?token=${emailToken.token}`;
+                break;
+            case suite_core_lib_1.EmailTokenType.MnemonicRecoveryRequest:
+            case suite_core_lib_1.EmailTokenType.PrivateKeyRequest:
+            default:
+                throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_InvalidEmailTokenType);
+        }
+        const emailSubject = (0, suite_core_lib_1.getSuiteCoreTranslation)(subjectString);
+        const emailText = `${(0, suite_core_lib_1.getSuiteCoreTranslation)(bodyString)}\r\n\r\n${url}`;
+        const emailHtml = `<p>${(0, suite_core_lib_1.getSuiteCoreTranslation)(bodyString)}</p><br/><p><a href="${url}">${url}</a></p><p>${(0, suite_core_lib_1.getSuiteCoreTranslation)(suite_core_lib_1.SuiteCoreStringKey.Email_LinkExpiresInTemplate)}</p>`;
+        try {
+            // Use the EmailService to send the email
+            await this.emailService.sendEmail(emailToken.email, emailSubject, emailText, emailHtml);
+            // update last sent/expiration
+            emailToken.lastSent = new Date();
+            emailToken.expiresAt = new Date(Date.now() + this.application.constants.EmailTokenExpiration);
+            await emailToken.save({ session });
+        }
+        catch {
+            throw new suite_core_lib_1.EmailTokenFailedToSendError(emailToken.type);
+        }
+    }
+    /**
+     * Find a user by email or username and enforce account status checks
+     * @param email Optional email
+     * @param username Optional username
+     * @param session Optional mongoose session
+     * @throws UsernameOrEmailRequiredError if neither provided
+     * @throws InvalidCredentialsError if not found or deleted
+     * @throws AccountLockedError | PendingEmailVerificationError | AccountStatusError per status
+     */
+    async findUser(email, username, session) {
+        if (!email && !username) {
+            throw new suite_core_lib_2.UsernameOrEmailRequiredError();
+        }
+        const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+        let userDoc = null;
+        try {
+            if (email) {
+                userDoc = await UserModel.findOne({
+                    email: email.toLowerCase(),
+                })
+                    .session(session ?? null)
+                    .exec();
+            }
+            else if (username) {
+                userDoc = await UserModel.findOne({ username })
+                    .collation({ locale: 'en', strength: 2 })
+                    .session(session ?? null)
+                    .exec();
+            }
+        }
+        catch {
+            // Database error in findUser - convert to InvalidCredentialsError for security
+            throw new suite_core_lib_1.InvalidCredentialsError();
+        }
+        if (!userDoc || userDoc.deletedAt) {
+            if (email) {
+                throw new suite_core_lib_1.InvalidEmailError(ecies_lib_1.InvalidEmailErrorType.Missing);
+            }
+            throw new suite_core_lib_2.UserNotFoundError();
+        }
+        switch (userDoc.accountStatus) {
+            case suite_core_lib_1.AccountStatus.Active:
+                break;
+            case suite_core_lib_1.AccountStatus.AdminLock:
+                throw new suite_core_lib_1.AccountLockedError();
+            case suite_core_lib_1.AccountStatus.PendingEmailVerification:
+                throw new suite_core_lib_1.PendingEmailVerificationError();
+            default:
+                throw new suite_core_lib_1.AccountStatusError(userDoc.accountStatus);
+        }
+        return userDoc;
+    }
+    /**
+     * Finds a user record by ID
+     * @param userId The user ID
+     * @param throwIfNotActive Whether to throw if the user is inactive
+     * @param session The active session, if present
+     * @returns The user document
+     */
+    async findUserById(userId, throwIfNotActive, session, select) {
+        const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+        const baseQuery = UserModel.findById(userId).session(session ?? null);
+        if (select) {
+            // Always include fields needed for status checks
+            const merged = this.ensureRequiredFieldsInProjection(select, [
+                'deletedAt',
+                'accountStatus',
+            ]);
+            baseQuery.select(merged);
+        }
+        const userDoc = (await baseQuery.exec());
+        if (!userDoc || userDoc.deletedAt) {
+            throw new suite_core_lib_2.UserNotFoundError();
+        }
+        if (throwIfNotActive) {
+            switch (userDoc.accountStatus) {
+                case suite_core_lib_1.AccountStatus.Active:
+                    break;
+                case suite_core_lib_1.AccountStatus.AdminLock:
+                    throw new suite_core_lib_1.AccountLockedError();
+                case suite_core_lib_1.AccountStatus.PendingEmailVerification:
+                    throw new suite_core_lib_1.PendingEmailVerificationError();
+                default:
+                    throw new suite_core_lib_1.AccountStatusError(userDoc.accountStatus);
+            }
+        }
+        return userDoc;
+    }
+    /**
+     * Ensure required fields are present in a projection for queries that rely on them.
+     * Supports string and object-style projections. For inclusion projections, adds fields.
+     * For exclusion projections, ensures required fields are not excluded.
+     */
+    ensureRequiredFieldsInProjection(select, required) {
+        if (typeof select === 'string') {
+            const parts = select
+                .split(/\s+/)
+                .map((s) => s.trim())
+                .filter(Boolean);
+            const exclusions = new Set(parts.filter((p) => p.startsWith('-')).map((p) => p.slice(1)));
+            // Remove exclusions on required fields
+            for (const r of required) {
+                exclusions.delete(r);
+            }
+            const cleaned = parts.filter((p) => !p.startsWith('-'));
+            for (const r of required) {
+                if (!cleaned.includes(r))
+                    cleaned.push(r);
+            }
+            const result = [...cleaned, ...[...exclusions].map((r) => `-${r}`)];
+            return result.join(' ');
+        }
+        if (select && typeof select === 'object') {
+            const proj = { ...select };
+            const values = Object.values(proj);
+            const hasInclusions = values.some((v) => v === 1 || v === true);
+            if (hasInclusions) {
+                for (const r of required) {
+                    proj[r] = 1;
+                }
+            }
+            else {
+                const keysToRemove = required.filter((r) => proj[r] === 0 || proj[r] === false || proj[r] === -1);
+                keysToRemove.forEach((key) => delete proj[key]);
+            }
+            return proj;
+        }
+        return select;
+    }
+    /**
+     * Fill in the default values to a user object
+     * @param newUser The user object to fill in
+     * @param createdBy The user ID of the user creating the new user
+     * @returns The filled in user
+     */
+    fillUserDefaults(newUser, createdBy, backupCodes, encryptedMnemonic, userId) {
+        return {
+            ...(userId ? { _id: userId } : {}),
+            timezone: 'UTC',
+            ...newUser,
+            email: newUser.email.toLowerCase(),
+            emailVerified: false,
+            darkMode: false,
+            accountStatus: suite_core_lib_1.AccountStatus.PendingEmailVerification,
+            siteLanguage: 'en-US',
+            duressPasswords: [],
+            publicKey: '',
+            backupCodes,
+            mnemonicRecovery: encryptedMnemonic,
+            currency: 'USD',
+            directChallenge: true,
+            createdAt: new Date(),
+            createdBy: createdBy,
+            updatedAt: new Date(),
+            updatedBy: createdBy,
+        };
+    }
+    /**
+     * Create a new user document from an IUser and unhashed password
+     * @param newUser The user object
+     * @returns The new user document
+     */
+    async makeUserDoc(newUser) {
+        const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+        const newUserDoc = new UserModel(newUser);
+        const validationError = newUserDoc.validateSync();
+        if (validationError) {
+            throw new mongoose_validation_1.MongooseValidationError(validationError.errors);
+        }
+        return newUserDoc;
+    }
+    /**
+     * Create a new user.
+     * Do not set createdBy to a new (non-existing) ObjectId unless you also set newUserId to it.
+     * If newUserId is not set, one will be generated.
+     * @param systemUser The system user performing the operation
+     * @param userData Username, email, password in a ICreateUserBasics object
+     * @param createdBy The user id of the user creating the user
+     * @param newUserId the user id of the new user object- usually the createdBy user id.
+     * @param session The session to use for the query
+     * @param debug Whether to log debug information
+     * @param password The password to use for the new user (optional, if not provided, mnemonic will be used)
+     * @returns The new user document
+     */
+    async newUser(systemUser, userData, createdBy, newUserId, session, debug = false, password, userProvidedMnemonic) {
+        const provider = (0, node_ecies_lib_1.getEnhancedNodeIdProvider)();
+        const _newUserId = newUserId ?? provider.generateTyped();
+        if (!this.application.constants.UsernameRegex.test(userData.username)) {
+            throw new suite_core_lib_1.InvalidUsernameError();
+        }
+        if (password && !this.application.constants.PasswordRegex.test(password)) {
+            throw new node_express_suite_1.InvalidNewPasswordError();
+        }
+        const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const existingEmail = await UserModel.findOne({
+                email: userData.email.toLowerCase(),
+            }).session(sess ?? null);
+            if (existingEmail) {
+                throw new suite_core_lib_1.EmailInUseError();
+            }
+            const existingUsername = await UserModel.findOne({
+                username: { $regex: new RegExp(`^${userData.username}$`, 'i') },
+            }).session(sess ?? null);
+            if (existingUsername) {
+                throw new suite_core_lib_2.UsernameInUseError();
+            }
+            let mnemonic;
+            let member;
+            if (userProvidedMnemonic) {
+                // User-provided mnemonic path: validate, check uniqueness, use directly
+                const trimmedMnemonic = userProvidedMnemonic.trim();
+                if (!this.application.constants.MnemonicRegex.test(trimmedMnemonic)) {
+                    throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Validation_MnemonicRegex);
+                }
+                const trimmedMnemonicSecure = new ecies_lib_1.SecureString(trimmedMnemonic);
+                try {
+                    const exists = await this.mnemonicService.mnemonicExists(trimmedMnemonicSecure, sess);
+                    if (exists) {
+                        throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Validation_MnemonicInUse);
+                    }
+                    const { member: newMember, mnemonic: newMnemonic } = node_ecies_lib_1.Member.newMember(this.eciesService, ecies_lib_1.MemberType.User, userData.username, new ecies_lib_1.EmailString(userData.email), trimmedMnemonicSecure, createdBy);
+                    member = newMember;
+                    mnemonic = newMnemonic;
+                }
+                catch (e) {
+                    trimmedMnemonicSecure.dispose();
+                    throw e;
+                }
+            }
+            else {
+                // Server-generated mnemonic path: retry loop until unique mnemonic found
+                while (!mnemonic || !member) {
+                    try {
+                        const { member: newMember, mnemonic: newMnemonic } = node_ecies_lib_1.Member.newMember(this.eciesService, ecies_lib_1.MemberType.User, userData.username, new ecies_lib_1.EmailString(userData.email), undefined, createdBy);
+                        // make sure the new mnemonic is not already in the database
+                        const mnemonicExists = await this.mnemonicService.mnemonicExists(newMnemonic, sess);
+                        if (!mnemonicExists) {
+                            member = newMember;
+                            mnemonic = newMnemonic;
+                        }
+                    }
+                    catch {
+                        // If we fail to create a new member, we will retry until we succeed.
+                        // This is to ensure that we do not end up with duplicate mnemonics.
+                        (0, node_express_suite_1.debugLog)(debug, 'warn', 'Failed to create a new member, retrying...');
+                    }
+                }
+            }
+            const backupCodes = node_express_suite_1.BackupCode.generateBackupCodes();
+            const encryptedBackupCodes = await node_express_suite_1.BackupCode.encryptBackupCodes(member, systemUser, backupCodes);
+            const encryptedMnemonic = member
+                .encryptData(Buffer.from(mnemonic.value ?? '', 'utf-8'))
+                .toString('hex');
+            const newUserDoc = new UserModel({
+                ...this.fillUserDefaults(userData, createdBy ?? _newUserId, encryptedBackupCodes, encryptedMnemonic, _newUserId),
+                publicKey: member.publicKey.toString('hex'),
+            });
+            const validationError = newUserDoc.validateSync();
+            if (validationError) {
+                throw new mongoose_validation_1.MongooseValidationError(validationError.errors);
+            }
+            // Always add HMAC-only mnemonic doc
+            const newMnemonicDoc = await this.mnemonicService.addMnemonic(mnemonic, sess);
+            if (newMnemonicDoc) {
+                newUserDoc.mnemonicId = newMnemonicDoc._id;
+            }
+            // If password provided, wrap the ECIES private key with the password (Option B)
+            if (password) {
+                const passwordSecure = new ecies_lib_1.SecureString(password);
+                try {
+                    const priv = new ecies_lib_1.SecureBuffer(member.privateKey.value);
+                    try {
+                        const wrapped = this.keyWrappingService.wrapSecret(priv, passwordSecure, this.application.constants);
+                        newUserDoc.passwordWrappedPrivateKey = wrapped;
+                    }
+                    finally {
+                        priv.dispose();
+                    }
+                }
+                finally {
+                    passwordSecure.dispose();
+                }
+            }
+            const savedUserDoc = await newUserDoc.save({ session: sess });
+            const memberRoleId = await this.roleService.getRoleIdByName(this.application.constants.MemberRole, sess);
+            if (!memberRoleId) {
+                throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Error_FailedToLookupRoleTemplate, {
+                    ROLE: (0, suite_core_lib_1.getSuiteCoreTranslation)(suite_core_lib_1.SuiteCoreStringKey.Common_Member),
+                });
+            }
+            await this.roleService.addUserToRole(memberRoleId, savedUserDoc._id, _newUserId, sess);
+            return {
+                user: savedUserDoc,
+                mnemonic: mnemonic.value ?? '',
+                backupCodes: backupCodes.map((code) => code.value ?? ''),
+                ...(password ? { password } : {}),
+            };
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout * 10,
+        });
+    }
+    /**
+     * Get the backup codes for a user.
+     * Requires the user not be deleted or inactive
+     */
+    async getEncryptedUserBackupCodes(userId, session) {
+        const userWithCodes = await this.findUserById(userId, true, session);
+        return userWithCodes.backupCodes;
+    }
+    /**
+     * Resets the given user's backup codes
+     * @param backupUser The user to generate codes for
+     * @param session The current session, if any
+     * @returns A promise of an array of backup codes
+     */
+    async resetUserBackupCodes(backupUser, systemUser, session) {
+        if (!backupUser.hasPrivateKey) {
+            throw new suite_core_lib_1.PrivateKeyRequiredError();
+        }
+        const backupCodes = node_express_suite_1.BackupCode.generateBackupCodes();
+        const encryptedBackupCodes = await node_express_suite_1.BackupCode.encryptBackupCodes(backupUser, systemUser, backupCodes);
+        const UserModel = model_registry_1.ModelRegistry.instance.get('User')?.model;
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            await UserModel.updateOne({ _id: backupUser.id }, { $set: { backupCodes: encryptedBackupCodes } }, { session: sess });
+            return backupCodes;
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout,
+        });
+    }
+    /**
+     * Recover a user's mnemonic from an encrypted mnemonic
+     * @param user The user whose mnemonic to recover
+     * @param encryptedMnemonic The encrypted mnemonic
+     * @returns The recovered mnemonic
+     */
+    recoverMnemonic(user, encryptedMnemonic) {
+        if (!encryptedMnemonic) {
+            throw new suite_core_lib_1.TranslatableSuiteHandleableError(suite_core_lib_1.SuiteCoreStringKey.MnemonicRecovery_Missing, undefined, undefined, {
+                statusCode: 400,
+            });
+        }
+        return new ecies_lib_1.SecureString(user.decryptData(Buffer.from(encryptedMnemonic, 'hex')).toString('utf-8'));
+    }
+    /**
+     * Make a Member from a user document and optional private key
+     * @param userDoc The user document
+     * @param privateKey Optional private key to load the wallet
+     * @param publicKey Optional public key to override the userDoc public key
+     * @param session The current session, if any
+     * @returns A promise containing the created Member
+     */
+    async makeUserFromUserDoc(userDoc, privateKey, publicKey, mnemonic, wallet, session) {
+        const memberType = await this.roleService.getMemberType(userDoc, session);
+        const user = new node_ecies_lib_1.Member(this.eciesService, memberType, userDoc.username, new ecies_lib_1.EmailString(userDoc.email), publicKey ?? Buffer.from(userDoc.publicKey, 'hex'), privateKey, wallet, userDoc._id, new Date(userDoc.createdAt), new Date(userDoc.updatedAt), userDoc.createdBy);
+        if ((privateKey?.originalLength ?? -1) > 0 &&
+            user.hasPrivateKey &&
+            !wallet) {
+            user.loadWallet(mnemonic ?? this.recoverMnemonic(user, userDoc.mnemonicRecovery));
+        }
+        return user;
+    }
+    /**
+     * Challenges a given userDoc with a given mnemonic, returns a system and user Member
+     * @param userDoc The userDoc in question
+     * @param mnemonic The mnemonic to challenge against
+     * @returns A promise containing the user and system Members
+     * @throws InvalidCredentialsError if the challenge fails
+     * @throws AccountLockedError if the account is locked
+     * @throws PendingEmailVerificationError if the email is not verified
+     * @throws AccountStatusError if the account status is invalid
+     */
+    async challengeUserWithMnemonic(userDoc, mnemonic, session) {
+        try {
+            // Verify provided mnemonic corresponds to the stored mnemonic HMAC (no password required)
+            // This prevents any valid mnemonic from authenticating as another user.
+            const MnemonicModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.Mnemonic);
+            if (!userDoc.mnemonicId) {
+                throw new suite_core_lib_1.InvalidCredentialsError();
+            }
+            const mnemonicDoc = await MnemonicModel.findById(userDoc.mnemonicId)
+                .select('hmac')
+                .session(session ?? null)
+                .lean()
+                .exec();
+            if (!mnemonicDoc) {
+                throw new suite_core_lib_1.InvalidCredentialsError();
+            }
+            const computedHmac = this.mnemonicService.getMnemonicHmac(mnemonic);
+            if (computedHmac !== mnemonicDoc.hmac) {
+                throw new suite_core_lib_1.InvalidCredentialsError();
+            }
+            // Create a Member from the provided mnemonic to get the keys
+            const { wallet } = this.eciesService.walletAndSeedFromMnemonic(mnemonic);
+            const privateKey = wallet.getPrivateKey();
+            // Get compressed public key (already includes prefix)
+            const publicKeyWithPrefix = this.eciesService.getPublicKey(Buffer.from(privateKey));
+            const userMember = await this.makeUserFromUserDoc(userDoc, new ecies_lib_1.SecureBuffer(privateKey), publicKeyWithPrefix, mnemonic, wallet, session);
+            // Verify the public key matches the stored userDoc public key
+            if (userMember.publicKey.toString('hex') !== userDoc.publicKey) {
+                throw new suite_core_lib_1.InvalidCredentialsError();
+            }
+            // Generate a nonce challenge to verify they can decrypt with their key
+            const adminMember = node_express_suite_1.SystemUserService.getSystemUser(this.application.environment, this.application.constants);
+            const nonce = (0, crypto_1.randomBytes)(32);
+            const signature = adminMember.sign(nonce);
+            const payload = Buffer.concat([nonce, signature]);
+            const encryptedPayload = userMember.encryptData(payload);
+            const decryptedPayload = userMember.decryptData(encryptedPayload);
+            // Verify the server's signature on the nonce
+            const decryptedNonce = decryptedPayload.subarray(0, 32);
+            const decryptedSignature = decryptedPayload.subarray(32);
+            const isSignatureValid = adminMember.verify(decryptedSignature, decryptedNonce);
+            if (!isSignatureValid || !nonce.equals(decryptedNonce)) {
+                throw new suite_core_lib_1.InvalidCredentialsError();
+            }
+            return {
+                userMember,
+                adminMember: adminMember,
+            };
+        }
+        catch (error) {
+            if (error instanceof suite_core_lib_1.InvalidCredentialsError ||
+                error instanceof suite_core_lib_1.AccountLockedError ||
+                error instanceof suite_core_lib_1.PendingEmailVerificationError ||
+                error instanceof suite_core_lib_1.AccountStatusError) {
+                throw error;
+            }
+            throw new suite_core_lib_1.InvalidCredentialsError();
+        }
+    }
+    /**
+     * Validates a login challenge response
+     * @param challengeResponse The challenge response bytes in hex
+     * @param email The email address of the user
+     * @param username The username of the user
+     * @param session The mongo session for the query
+     * @returns A promise that resolves to the user document, user member, and system member
+     */
+    async loginWithChallengeResponse(challengeResponse, email, username, session) {
+        const challengeBuffer = Buffer.from(challengeResponse, 'hex');
+        // validate the expected challenge response length (8 + 32 + 64 = 104 bytes)
+        if (challengeBuffer.length !=
+            this.application.constants.DirectLoginChallengeLength) {
+            throw new suite_core_lib_1.InvalidChallengeResponseError();
+        }
+        // disassemble the challengeResponse into time, nonce, signature
+        const time = challengeBuffer.subarray(0, 8); // 16 hex characters
+        const nonce = challengeBuffer.subarray(8, 40); // 64 hex characters
+        const signature = challengeBuffer.subarray(40); // 65 * 2 hex characters
+        const timeMs = parseInt(time.toString('hex'), 16);
+        if (new Date().getTime() - timeMs >
+            this.application.constants.LoginChallengeExpiration) {
+            throw new suite_core_lib_1.LoginChallengeExpiredError();
+        }
+        const userDoc = await this.findUser(email, username, session);
+        if (!userDoc && email) {
+            throw new suite_core_lib_1.InvalidEmailError(ecies_lib_1.InvalidEmailErrorType.Missing);
+        }
+        else if (!userDoc) {
+            throw new suite_core_lib_2.UserNotFoundError();
+        }
+        // re-sign the time + nonce and check if the signature matches
+        const adminMember = node_express_suite_1.SystemUserService.getSystemUser(this.application.environment, this.application.constants);
+        const timeAndNonce = Buffer.concat([time, nonce]);
+        const expectedSignature = adminMember.sign(timeAndNonce);
+        if (expectedSignature.toString('hex') !== signature.toString('hex')) {
+            throw new suite_core_lib_1.InvalidChallengeResponseError();
+        }
+        const userMember = await this.makeUserFromUserDoc(userDoc, undefined, undefined, undefined, undefined, session);
+        return {
+            userDoc,
+            userMember,
+            adminMember: adminMember,
+        };
+    }
+    /**
+     * Authenticate a user with client-verified challenge (skips server-side challenge)
+     * @returns The authenticated user document.
+     */
+    async loginWithClientVerifiedChallenge(usernameOrEmail, mnemonic, session) {
+        const UserModel = this.application.getModel(base_model_name_1.BaseModelName.User);
+        const userQuery = validator_1.default.isEmail(usernameOrEmail)
+            ? UserModel.findOne({ email: usernameOrEmail.toLowerCase() }).select('_id username email accountStatus deletedAt mnemonicId publicKey passwordWrappedPrivateKey')
+            : UserModel.findOne({ username: usernameOrEmail })
+                .collation({ locale: 'en', strength: 2 })
+                .select('_id username email accountStatus deletedAt mnemonicId publicKey passwordWrappedPrivateKey');
+        const userDoc = await userQuery.session(session ?? null);
+        if (!userDoc || userDoc.deletedAt) {
+            throw new suite_core_lib_1.InvalidCredentialsError();
+        }
+        // Check account status
+        switch (userDoc.accountStatus) {
+            case suite_core_lib_1.AccountStatus.Active:
+                break;
+            case suite_core_lib_1.AccountStatus.AdminLock:
+                throw new suite_core_lib_1.AccountLockedError();
+            case suite_core_lib_1.AccountStatus.PendingEmailVerification:
+                throw new suite_core_lib_1.PendingEmailVerificationError();
+            default:
+                throw new suite_core_lib_1.AccountStatusError(userDoc.accountStatus);
+        }
+        // Verify mnemonic matches user (simplified verification)
+        try {
+            const MnemonicModel = this.application.getModel(base_model_name_1.BaseModelName.Mnemonic);
+            if (!userDoc.mnemonicId) {
+                throw new suite_core_lib_1.InvalidCredentialsError();
+            }
+            const mnemonicDoc = await MnemonicModel.findById(userDoc.mnemonicId)
+                .select('hmac')
+                .session(session ?? null)
+                .lean()
+                .exec();
+            if (!mnemonicDoc) {
+                throw new suite_core_lib_1.InvalidCredentialsError();
+            }
+            const computedHmac = this.mnemonicService.getMnemonicHmac(mnemonic);
+            if (computedHmac !== mnemonicDoc.hmac) {
+                throw new suite_core_lib_1.InvalidCredentialsError();
+            }
+            // Create Member from mnemonic
+            const { wallet } = this.eciesService.walletAndSeedFromMnemonic(mnemonic);
+            const privateKey = wallet.getPrivateKey();
+            // Get compressed public key (already includes prefix)
+            const publicKeyWithPrefix = this.eciesService.getPublicKey(Buffer.from(privateKey));
+            const userMember = await this.makeUserFromUserDoc(userDoc, new ecies_lib_1.SecureBuffer(privateKey), publicKeyWithPrefix, mnemonic, wallet, session);
+            // Verify public key matches
+            if (userMember.publicKey.toString('hex') !== userDoc.publicKey) {
+                throw new suite_core_lib_1.InvalidCredentialsError();
+            }
+            const adminMember = node_express_suite_1.SystemUserService.getSystemUser(this.application.environment, this.application.constants);
+            return {
+                userMember,
+                adminMember,
+                userDoc,
+            };
+        }
+        catch (error) {
+            if (error instanceof suite_core_lib_1.InvalidCredentialsError ||
+                error instanceof suite_core_lib_1.AccountLockedError ||
+                error instanceof suite_core_lib_1.PendingEmailVerificationError ||
+                error instanceof suite_core_lib_1.AccountStatusError) {
+                throw error;
+            }
+            throw new suite_core_lib_1.InvalidCredentialsError();
+        }
+    }
+    /**
+     * Authenticate a user with their mnemonic.
+     * @returns The authenticated user document.
+     */
+    async loginWithMnemonic(usernameOrEmail, mnemonic, session) {
+        const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+        const userQuery = validator_1.default.isEmail(usernameOrEmail)
+            ? UserModel.findOne({ email: usernameOrEmail.toLowerCase() }).select('_id username email accountStatus deletedAt mnemonicId publicKey passwordWrappedPrivateKey')
+            : UserModel.findOne({ username: usernameOrEmail })
+                .collation({ locale: 'en', strength: 2 })
+                .select('_id username email accountStatus deletedAt mnemonicId publicKey passwordWrappedPrivateKey');
+        const userDoc = await userQuery.session(session ?? null);
+        if (!userDoc || userDoc.deletedAt) {
+            throw new suite_core_lib_1.InvalidCredentialsError();
+        }
+        // Check account status
+        switch (userDoc.accountStatus) {
+            case suite_core_lib_1.AccountStatus.Active:
+                break;
+            case suite_core_lib_1.AccountStatus.AdminLock:
+                throw new suite_core_lib_1.AccountLockedError();
+            case suite_core_lib_1.AccountStatus.PendingEmailVerification:
+                throw new suite_core_lib_1.PendingEmailVerificationError();
+            default:
+                throw new suite_core_lib_1.AccountStatusError(userDoc.accountStatus);
+        }
+        const challengeResponse = await this.challengeUserWithMnemonic(userDoc, mnemonic, session);
+        return { ...challengeResponse, userDoc };
+    }
+    /**
+     * Authenticate a user with their password (for key-wrapped accounts).
+     * @returns The authenticated user document.
+     */
+    async loginWithPassword(usernameOrEmail, password, session) {
+        const UserModel = this.application.getModel(base_model_name_1.BaseModelName.User);
+        const query = validator_1.default.isEmail(usernameOrEmail)
+            ? UserModel.findOne({ email: usernameOrEmail.toLowerCase() })
+            : UserModel.findOne({ username: usernameOrEmail }).collation({
+                locale: 'en',
+                strength: 2,
+            });
+        const userDoc = await query
+            .session(session ?? null)
+            .exec();
+        if (!userDoc || userDoc.deletedAt) {
+            throw new suite_core_lib_1.InvalidCredentialsError();
+        }
+        // Check account status
+        switch (userDoc.accountStatus) {
+            case suite_core_lib_1.AccountStatus.Active:
+                break;
+            case suite_core_lib_1.AccountStatus.AdminLock:
+                throw new suite_core_lib_1.AccountLockedError();
+            case suite_core_lib_1.AccountStatus.PendingEmailVerification:
+                throw new suite_core_lib_1.PendingEmailVerificationError();
+            default:
+                throw new suite_core_lib_1.AccountStatusError(userDoc.accountStatus);
+        }
+        // Check if user has password-based authentication set up (Option B requires passwordWrappedPrivateKey)
+        if (!userDoc.passwordWrappedPrivateKey || !userDoc.mnemonicId) {
+            throw new suite_core_lib_1.PasswordLoginNotEnabledError();
+        }
+        // Unwrap password-wrapped private key and complete challenge with possession of private key
+        const unwrapped = await this.keyWrappingService.unwrapSecretAsync(userDoc.passwordWrappedPrivateKey, password, this.application.constants);
+        // Build user member with unwrapped private key to decrypt challenge
+        // Note: userMember now owns the unwrapped SecureBuffer, so we don't dispose it here
+        const userMember = await this.makeUserFromUserDoc(userDoc, unwrapped, undefined, undefined, undefined, session);
+        // Generate a nonce challenge signed by system
+        const adminMember = node_express_suite_1.SystemUserService.getSystemUser(this.application.environment, this.application.constants);
+        const nonce = (0, crypto_1.randomBytes)(32);
+        const signature = adminMember.sign(nonce);
+        const payload = Buffer.concat([nonce, signature]);
+        const encryptedPayload = userMember.encryptData(payload);
+        const decryptedPayload = userMember.decryptData(encryptedPayload);
+        const decryptedNonce = decryptedPayload.subarray(0, 32);
+        const decryptedSignature = decryptedPayload.subarray(32);
+        const isSignatureValid = adminMember.verify(decryptedSignature, decryptedNonce);
+        if (!isSignatureValid || !nonce.equals(decryptedNonce)) {
+            throw new suite_core_lib_1.InvalidCredentialsError();
+        }
+        return { userDoc, userMember, adminMember: adminMember };
+    }
+    /**
+     * Re-send a previously sent email token
+     * @param userId The user id
+     * @param session The session to use for the query
+     * @returns void
+     * @throws EmailTokenUsedOrInvalidError
+     */
+    async resendEmailToken(userId, type, session, debug = false) {
+        const EmailTokenModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.EmailToken);
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            // look up the most recent email token for a given user, then send it
+            const emailToken = await EmailTokenModel.findOne({
+                userId,
+                type,
+                expiresAt: { $gt: new Date() },
+            })
+                .session(sess ?? null)
+                .sort({ createdAt: -1 })
+                .limit(1);
+            if (!emailToken) {
+                throw new suite_core_lib_1.EmailTokenUsedOrInvalidError();
+            }
+            await this.sendEmailToken(emailToken, sess, debug);
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout * 5,
+        });
+    }
+    /**
+     * Verify the email token and update the user's account status
+     * @param emailToken The email token to verify
+     * @param session The session to use for the query
+     * @returns void
+     * @throws EmailTokenUsedOrInvalidError
+     * @throws EmailTokenExpiredError
+     * @throws EmailVerifiedError
+     * @throws UserNotFoundError
+     */
+    async verifyAccountTokenAndComplete(emailToken, session) {
+        let alreadyVerified = false;
+        await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const EmailTokenModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.EmailToken);
+            const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+            const token = await this.findEmailToken(emailToken, suite_core_lib_1.EmailTokenType.AccountVerification, sess);
+            if (!token) {
+                throw new suite_core_lib_1.EmailTokenUsedOrInvalidError();
+            }
+            if (token.expiresAt < new Date()) {
+                await EmailTokenModel.deleteOne({ _id: token._id }).session(sess ?? null);
+                throw new suite_core_lib_1.EmailTokenExpiredError();
+            }
+            const user = await UserModel.findById(token.userId).session(sess ?? null);
+            if (!user || user.deletedAt) {
+                throw new suite_core_lib_2.UserNotFoundError();
+            }
+            if (user.emailVerified) {
+                // Delete the token and mark to throw error after transaction commits
+                await EmailTokenModel.deleteOne({ _id: token._id }).session(sess ?? null);
+                alreadyVerified = true;
+                return;
+            }
+            // set user email to token email and mark as verified
+            user.email = token.email;
+            user.emailVerified = true;
+            user.accountStatus = suite_core_lib_1.AccountStatus.Active;
+            user.updatedBy = user._id;
+            await user.save({ session: sess });
+            // Delete the token after successful verification
+            await EmailTokenModel.deleteOne({ _id: token._id }).session(sess ?? null);
+            // add the user to the member role
+            const memberRoleId = await this.roleService.getRoleIdByName(this.application.constants.MemberRole, sess);
+            if (memberRoleId) {
+                await this.roleService.addUserToRole(memberRoleId, user._id, user._id, sess);
+            }
+            else {
+                throw new Error('Member role not found');
+            }
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout * 5,
+        });
+        if (alreadyVerified) {
+            throw new suite_core_lib_1.EmailVerifiedError(409);
+        }
+    }
+    /**
+     * Validate the email token
+     * @param token The token to validate
+     * @param restrictType The type of email token to validate (or throw)
+     * @param session The session to use for the query
+     * @returns void
+     * @throws EmailTokenUsedOrInvalidError
+     */
+    async validateEmailToken(token, restrictType, session) {
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const EmailTokenModel = this.application.getModel(base_model_name_1.BaseModelName.EmailToken);
+            const emailToken = await EmailTokenModel.findOne({
+                token,
+                ...(restrictType ? { type: suite_core_lib_1.EmailTokenType.PasswordReset } : {}),
+            }).session(sess ?? null);
+            if (!emailToken) {
+                throw new suite_core_lib_1.EmailTokenUsedOrInvalidError();
+            }
+            else if (emailToken.expiresAt < new Date()) {
+                await EmailTokenModel.deleteOne({ _id: emailToken._id }).session(sess ?? null);
+                throw new suite_core_lib_1.EmailTokenExpiredError();
+            }
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout * 5,
+        });
+    }
+    /**
+     * Updates the user's language
+     * @param userId - The ID of the user
+     * @param newLanguage - The new language
+     * @param session - The session to use for the query
+     * @returns The updated user
+     */
+    async updateSiteLanguage(userId, newLanguage, session) {
+        const provider = (0, node_ecies_lib_1.getEnhancedNodeIdProvider)();
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+            const userDoc = await UserModel.findByIdAndUpdate(provider.idFromString(userId), {
+                siteLanguage: newLanguage,
+            }, { new: true }).session(sess ?? null);
+            if (!userDoc) {
+                throw new suite_core_lib_2.UserNotFoundError();
+            }
+            const roles = await this.roleService.getUserRoles(userDoc._id);
+            const tokenRoles = this.roleService.rolesToTokenRoles(roles);
+            return request_user_1.RequestUserService.makeRequestUserDTO(userDoc, tokenRoles);
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout * 5,
+        });
+    }
+    /**
+     * Updates the user's Dark Mode preference
+     * @param userId - The ID of the user
+     * @param newDarkMode - The new Dark Mode preference
+     * @param session - The session to use for the query
+     * @returns The updated user
+     */
+    async updateDarkMode(userId, newDarkMode, session) {
+        const provider = (0, node_ecies_lib_1.getEnhancedNodeIdProvider)();
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+            const userDoc = await UserModel.findByIdAndUpdate(provider.idFromString(userId), {
+                darkMode: newDarkMode,
+            }, { new: true }).session(sess ?? null);
+            if (!userDoc) {
+                throw new suite_core_lib_2.UserNotFoundError();
+            }
+            const roles = await this.roleService.getUserRoles(userDoc._id);
+            const tokenRoles = this.roleService.rolesToTokenRoles(roles);
+            return request_user_1.RequestUserService.makeRequestUserDTO(userDoc, tokenRoles);
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout * 5,
+        });
+    }
+    /**
+     * Updates multiple user settings at once
+     * @param userId - The ID of the user
+     * @param settings - Object containing settings to update
+     * @param session - The session to use for the query
+     * @returns The updated user
+     */
+    async updateUserSettings(userId, settings, session) {
+        const provider = (0, node_ecies_lib_1.getEnhancedNodeIdProvider)();
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+            const userDoc = await UserModel.findById(provider.idFromString(userId)).session(sess ?? null);
+            if (!userDoc) {
+                throw new suite_core_lib_2.UserNotFoundError();
+            }
+            // Check if email is changing and if it's already in use
+            if (settings.email &&
+                settings.email.toLowerCase() !== userDoc.email.toLowerCase()) {
+                const existingUser = await UserModel.findOne({
+                    email: settings.email.toLowerCase(),
+                    _id: { $ne: userDoc._id },
+                }).session(sess ?? null);
+                if (existingUser) {
+                    throw new suite_core_lib_1.EmailInUseError();
+                }
+                // Send verification email for new address
+                userDoc.email = settings.email.toLowerCase();
+                await this.createAndSendEmailTokenDirect(userDoc, suite_core_lib_1.EmailTokenType.AccountVerification, sess, this.application.environment.debug);
+            }
+            // Update other settings
+            if (settings.timezone !== undefined)
+                userDoc.timezone = settings.timezone;
+            if (settings.siteLanguage !== undefined)
+                userDoc.siteLanguage = settings.siteLanguage;
+            if (settings.darkMode !== undefined)
+                userDoc.darkMode = settings.darkMode;
+            if (settings.currency !== undefined)
+                userDoc.currency = settings.currency;
+            if (settings.directChallenge !== undefined)
+                userDoc.directChallenge = settings.directChallenge;
+            await userDoc.save({ session: sess });
+            const roles = await this.roleService.getUserRoles(userDoc._id);
+            const tokenRoles = this.roleService.rolesToTokenRoles(roles);
+            return request_user_1.RequestUserService.makeRequestUserDTO(userDoc, tokenRoles);
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout * 5,
+        });
+    }
+    /**
+     * Changes the user's password by re-wrapping their master key
+     * @param userId - The ID of the user
+     * @param currentPassword - The current password
+     * @param newPassword - The new password
+     * @param session - The session to use for the query
+     * @returns void
+     */
+    async changePassword(userId, currentPassword, newPassword, session) {
+        const provider = (0, node_ecies_lib_1.getEnhancedNodeIdProvider)();
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+            const userDoc = await UserModel.findById(provider.idFromString(userId)).session(sess ?? null);
+            if (!userDoc || !userDoc.passwordWrappedPrivateKey) {
+                throw new suite_core_lib_2.UserNotFoundError();
+            }
+            if (!this.application.constants.PasswordRegex.test(newPassword)) {
+                throw new node_express_suite_1.InvalidNewPasswordError();
+            }
+            const currentPasswordSecure = new ecies_lib_1.SecureString(currentPassword);
+            const newPasswordSecure = new ecies_lib_1.SecureString(newPassword);
+            try {
+                // Unwrap existing private key and rewrap under new password
+                const priv = this.keyWrappingService.unwrapSecret(userDoc.passwordWrappedPrivateKey, currentPasswordSecure);
+                try {
+                    const wrapped = this.keyWrappingService.wrapSecret(priv, newPasswordSecure, this.application.constants);
+                    userDoc.passwordWrappedPrivateKey = wrapped;
+                    await userDoc.save({ session: sess });
+                }
+                finally {
+                    priv.dispose();
+                }
+            }
+            catch (error) {
+                // Re-throw original error so controller can map it properly
+                // Re-throw original error so controller can map it properly
+                throw error;
+            }
+            finally {
+                currentPasswordSecure.dispose();
+                newPasswordSecure.dispose();
+            }
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout * 5,
+        });
+    }
+    /**
+     * Retrieve an email token by its token string and type
+     * @param token - The token string
+     * @param type - The type of the email token
+     * @param session - The session to use for the query
+     * @returns The email token document or null if not found
+     */
+    async findEmailToken(token, type, session) {
+        const EmailTokenModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.EmailToken);
+        return await EmailTokenModel.findOne({
+            token: token.toLowerCase().trim(),
+            ...(type ? { type } : {}),
+            expiresAt: { $gt: new Date() },
+        }).session(session ?? null);
+    }
+    /**
+     * Verify email token is valid
+     * @param token - The email token
+     * @param session - The session to use for the query
+     * @returns void
+     */
+    async verifyEmailToken(token, type, session) {
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            // Find and validate the token
+            const emailToken = await this.findEmailToken(token, type, sess);
+            if (!emailToken) {
+                throw new suite_core_lib_1.EmailTokenUsedOrInvalidError();
+            }
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout * 5,
+        });
+    }
+    /**
+     * Reset password using email token
+     * @param token - The email token
+     * @param newPassword - The new password
+     * @param session - The session to use for the query
+     * @returns void
+     */
+    async resetPasswordWithToken(token, newPassword, credential, // either mnemonic or current password; required
+    session) {
+        if (!this.application.constants.PasswordRegex.test(newPassword)) {
+            throw new node_express_suite_1.InvalidNewPasswordError();
+        }
+        if (!credential) {
+            throw new suite_core_lib_1.EmailTokenUsedOrInvalidError();
+        }
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const EmailTokenModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.EmailToken);
+            const UserModel = model_registry_1.ModelRegistry.instance.getTypedModel(base_model_name_1.BaseModelName.User);
+            // Find and validate the token
+            const emailToken = await this.findEmailToken(token, suite_core_lib_1.EmailTokenType.PasswordReset, sess);
+            if (!emailToken) {
+                throw new suite_core_lib_1.EmailTokenUsedOrInvalidError();
+            }
+            // Find the user
+            const userDoc = await UserModel.findById(emailToken.userId).session(sess ?? null);
+            if (!userDoc) {
+                throw new suite_core_lib_2.UserNotFoundError();
+            }
+            // Update password-wrapped secrets based on credential type (Option B)
+            const newPasswordSecure = new ecies_lib_1.SecureString(newPassword);
+            try {
+                if (this.application.constants.MnemonicRegex.test(credential)) {
+                    // Credential is mnemonic: verify it belongs to this user via public key
+                    const providedMnemonic = new ecies_lib_1.SecureString(credential);
+                    try {
+                        const { wallet } = this.eciesService.walletAndSeedFromMnemonic(providedMnemonic);
+                        const privateKey = wallet.getPrivateKey();
+                        // Get compressed public key (already includes prefix)
+                        const pub = this.eciesService.getPublicKey(Buffer.from(privateKey));
+                        if (pub.toString('hex') !== userDoc.publicKey) {
+                            throw new suite_core_lib_1.InvalidCredentialsError();
+                        }
+                        // Wrap private key with new password
+                        const priv = new ecies_lib_1.SecureBuffer(privateKey);
+                        try {
+                            const wrappedPriv = this.keyWrappingService.wrapSecret(priv, newPasswordSecure, this.application.constants);
+                            userDoc.passwordWrappedPrivateKey = wrappedPriv;
+                            await userDoc.save({ session: sess });
+                        }
+                        finally {
+                            priv.dispose();
+                        }
+                    }
+                    finally {
+                        providedMnemonic.dispose();
+                    }
+                }
+                else {
+                    // Credential is current password: unwrap existing master key
+                    if (!userDoc.passwordWrappedPrivateKey) {
+                        throw new suite_core_lib_1.InvalidCredentialsError();
+                    }
+                    const privateKeyBuf = await this.keyWrappingService.unwrapSecretAsync(userDoc.passwordWrappedPrivateKey, credential, this.application.constants);
+                    try {
+                        // Re-wrap the existing private key under the new password
+                        const wrappedPriv = this.keyWrappingService.wrapSecret(privateKeyBuf, newPasswordSecure, this.application.constants);
+                        userDoc.passwordWrappedPrivateKey = wrappedPriv;
+                        await userDoc.save({ session: sess });
+                    }
+                    finally {
+                        privateKeyBuf.dispose();
+                    }
+                }
+                // Delete the used token
+                await EmailTokenModel.deleteOne({ _id: emailToken._id }).session(sess ?? null);
+                // Dispose temporary master key
+            }
+            finally {
+                newPasswordSecure.dispose();
+            }
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout * 5,
+        });
+    }
+    /**
+     * Generate a login challenge for the client to sign
+     * @returns The login challenge in hex
+     */
+    generateDirectLoginChallenge() {
+        const adminMember = node_express_suite_1.SystemUserService.getSystemUser(this.application.environment, this.application.constants);
+        const time = Buffer.alloc(8);
+        time.writeBigUInt64BE(BigInt(new Date().getTime()));
+        const nonce = (0, crypto_1.randomBytes)(32);
+        const signature = adminMember.sign(Buffer.concat([time, nonce]));
+        return Buffer.concat([time, nonce, signature]).toString('hex');
+    }
+    /**
+     * Verifies a direct login challenge response
+     * @param serverSignedRequest The login challenge response in hex
+     * @param session The mongoose session, if provided
+     * @returns A promise with the user document and user member object
+     */
+    async verifyDirectLoginChallenge(serverSignedRequest, signature, username, email, session) {
+        return await this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            // serverSignedRequest is:
+            // time (8) +
+            // nonce (32) +
+            // server signature (64) +
+            // signature (64)
+            if (serverSignedRequest.length <
+                (8 + 32 + this.application.constants.ECIES.SIGNATURE_SIZE) * 2) {
+                throw new suite_core_lib_1.InvalidChallengeResponseError();
+            }
+            // get signed request into a buffer
+            const requestBuffer = Buffer.from(serverSignedRequest, 'hex');
+            // start tracking offset
+            let offset = 0;
+            // get the time
+            const time = requestBuffer.subarray(offset, 8);
+            offset += 8;
+            // get the nonce
+            const nonce = requestBuffer.subarray(offset, 40);
+            offset += 32;
+            // get the server signature
+            const serverSignature = requestBuffer.subarray(offset, this.application.constants.ECIES.SIGNATURE_SIZE + 40);
+            offset += this.application.constants.ECIES.SIGNATURE_SIZE;
+            const signedDataLength = offset;
+            if (offset !== requestBuffer.length) {
+                throw new suite_core_lib_1.InvalidChallengeResponseError();
+            }
+            // validate time is within acceptable range
+            const timeMs = time.readBigUInt64BE();
+            if (new Date().getTime() - Number(timeMs) >
+                this.application.constants.LoginChallengeExpiration) {
+                throw new suite_core_lib_1.LoginChallengeExpiredError();
+            }
+            // validate the server's signature on the time + nonce portion
+            const adminMember = node_express_suite_1.SystemUserService.getSystemUser(this.application.environment, this.application.constants);
+            if (!adminMember.verify(serverSignature, Buffer.concat([time, nonce]))) {
+                throw new suite_core_lib_1.InvalidChallengeResponseError();
+            }
+            // locate the user by email or username
+            const userDoc = await this.findUser(email, username, sess);
+            if (!userDoc) {
+                throw new suite_core_lib_1.InvalidChallengeResponseError();
+            }
+            // get the user's member object
+            const user = await this.makeUserFromUserDoc(userDoc, undefined, undefined, undefined, undefined, sess);
+            // get the signed portion of the response
+            const signedData = requestBuffer.subarray(0, signedDataLength);
+            // verify the user's signature on the signed portion
+            if (!user.verify(Buffer.from(signature, 'hex'), signedData)) {
+                throw new suite_core_lib_1.InvalidChallengeResponseError();
+            }
+            if (userDoc.directChallenge !== true) {
+                throw new suite_core_lib_1.DirectChallengeNotEnabledError();
+            }
+            // if the user is valid, try to use the token (prevents replay attacks)
+            await direct_login_token_1.DirectLoginTokenService.useToken(this.application, userDoc._id, nonce.toString('hex'));
+            // if successful, update lastLogin
+            await this.updateLastLogin(userDoc._id);
+            // return the user document and member object
+            return { userDoc, userMember: user };
+        }, session, { timeoutMs: this.application.environment.mongo.transactionTimeout });
+    }
+    /**
+     * Request a login link via email
+     * @param email Email address
+     * @param username Username
+     * @param session Existing session, if any
+     * @returns void
+     */
+    async requestEmailLogin(email, username, session) {
+        return this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const userDoc = await this.findUser(email, username, sess);
+            if (!userDoc) {
+                return;
+            }
+            await this.createAndSendEmailToken(userDoc, suite_core_lib_1.EmailTokenType.LoginRequest, sess, this.application.environment.debug);
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout,
+        });
+    }
+    /**
+     * Validate an email login token challenge
+     * @param token The token to challenge
+     * @param signature The signature of the token by the user's private key
+     * @param session The session to use for the query
+     * @returns The user document if the challenge is valid
+     */
+    async validateEmailLoginTokenChallenge(token, signature, session) {
+        return this.withTransaction(async (_sess) => {
+            const sess = _sess;
+            const emailToken = await this.findEmailToken(token, suite_core_lib_1.EmailTokenType.LoginRequest, sess);
+            if (!emailToken) {
+                throw new suite_core_lib_1.EmailTokenUsedOrInvalidError();
+            }
+            const userDoc = await this.findUser(emailToken.email, undefined, sess);
+            if (!userDoc) {
+                throw new suite_core_lib_2.UserNotFoundError();
+            }
+            const user = await this.makeUserFromUserDoc(userDoc, undefined, undefined, undefined, undefined, sess);
+            const result = user.verify(Buffer.from(signature, 'hex'), Buffer.from(token, 'hex'));
+            if (!result) {
+                throw new suite_core_lib_1.InvalidChallengeResponseError();
+            }
+            await emailToken.deleteOne({ session: sess ?? null });
+            await this.updateLastLogin(userDoc._id);
+            return userDoc;
+        }, session, {
+            timeoutMs: this.application.environment.mongo.transactionTimeout,
+        });
+    }
+    /**
+     * Updates the user's last login time atomically
+     * @param userId - The ID of the user
+     * @returns void
+     */
+    async updateLastLogin(userId) {
+        const UserModel = model_registry_1.ModelRegistry.instance.get('User')?.model;
+        try {
+            // Check if the database connection is still open
+            const connection = this.application.db.connection;
+            if (connection.readyState !== 1) {
+                // Connection is not open (0 = disconnected, 1 = connected, 2 = connecting, 3 = disconnecting)
+                return; // Silently return if connection is not available
+            }
+            // Use atomic update to avoid conflicts and ensure we only update lastLogin
+            // Use a separate session to avoid interfering with any ongoing transactions
+            await UserModel.updateOne({ _id: userId }, {
+                $set: { lastLogin: new Date() },
+                $setOnInsert: {}, // Prevent any unintended document creation
+            }, {
+                upsert: false, // Never create a new document
+                runValidators: false, // Skip validation for performance since we're only updating lastLogin
+                // Don't use any session to avoid transaction conflicts
+            });
+        }
+        catch (error) {
+            // Check if the error is due to client being closed
+            if (error instanceof Error &&
+                (error.message.includes('client was closed') ||
+                    error.message.includes('MongoClientClosedError') ||
+                    error.name === 'MongoClientClosedError')) {
+                // This is expected during shutdown, don't log it as an error
+                return;
+            }
+            // If this fails, it's not critical for login functionality. Ignore and move on.
+        }
+    }
+}
+exports.UserService = UserService;
+//# sourceMappingURL=user.js.map