@digitaldefiance/node-express-suite 3.7.4 → 3.7.5

package/src/services/mnemonic.ts

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview Mnemonic phrase management service.
+ * Securely stores mnemonic HMACs for uniqueness checking without exposing phrases.
+ * @module services/mnemonic
+ */
+
+import { SecureBuffer, SecureString } from '@digitaldefiance/ecies-lib';
+import { ClientSession, Model } from '@digitaldefiance/mongoose-types';
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import { createHmac } from 'crypto';
+import { IMnemonicDocument } from '../documents/mnemonic';
+import { IConstants } from '../interfaces';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Service for secure mnemonic phrase storage and validation.
+ * Uses HMAC for uniqueness checking without storing actual mnemonics.
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export class MnemonicService<TID extends PlatformID = Buffer> {
+  private readonly hmacSecret: SecureBuffer;
+  private readonly MnemonicModel: Model<IMnemonicDocument<TID>>;
+  private readonly constants: IConstants;
+
+  constructor(
+    mnemonicModel: Model<IMnemonicDocument<TID>>,
+    hmacSecret: SecureBuffer,
+    constants: IConstants,
+  ) {
+    this.MnemonicModel = mnemonicModel;
+    // Immediately wrap secrets in secure containers
+    this.hmacSecret = hmacSecret;
+    this.constants = constants;
+  }
+
+  /**
+   * Disposes of the secure secrets held by this service.
+   */
+  public dispose(): void {
+    this.hmacSecret.dispose();
+  }
+
+  /**
+   * Creates a non-reversible HMAC of the mnemonic for fast, indexed lookups.
+   * @param mnemonic The mnemonic to hash, wrapped in a SecureString.
+   */
+  public getMnemonicHmac(mnemonic: SecureString): string {
+    // Use the raw secret buffer for the HMAC
+    return createHmac('sha256', this.hmacSecret.value)
+      .update(mnemonic.valueAsUint8Array) // Use the raw buffer for consistency
+      .digest('hex');
+  }
+
+  /**
+   * Checks if a mnemonic already exists in the database using its HMAC.
+   * @param mnemonic The mnemonic to check, wrapped in a SecureString.
+   * @param session Optional Mongoose session for transaction support.
+   */
+  public async mnemonicExists(
+    mnemonic: SecureString,
+    session?: ClientSession,
+  ): Promise<boolean> {
+    const hmac = this.getMnemonicHmac(mnemonic);
+    const count = await this.MnemonicModel.countDocuments({ hmac }).session(
+      session ?? null,
+    );
+    return count > 0;
+  }
+
+  /**
+   * Adds a new, unique mnemonic to the database with password-based key wrapping.
+   * @param mnemonic The mnemonic to add, wrapped in a SecureString.
+   * @param password User's password for key wrapping.
+   * @param session Optional Mongoose session for transaction support.
+   */
+  public async addMnemonicWithPassword(
+    mnemonic: SecureString,
+    _password: SecureString,
+    session?: ClientSession,
+  ): Promise<{
+    document: IMnemonicDocument<TID> | null;
+  }> {
+    if (!mnemonic.value || !this.constants.MnemonicRegex.test(mnemonic.value)) {
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Validation_MnemonicRegex,
+      );
+    }
+
+    if (await this.mnemonicExists(mnemonic, session)) {
+      return { document: null };
+    }
+
+    try {
+      const hmac = this.getMnemonicHmac(mnemonic);
+      const [newDoc] = await this.MnemonicModel.create(
+        [
+          {
+            hmac: hmac,
+          },
+        ],
+        { session },
+      );
+      return { document: newDoc };
+    } finally {
+      // nothing to dispose
+    }
+  }
+
+  /**
+   * Adds a new, unique mnemonic to the database.
+   * @param mnemonic The mnemonic to add, wrapped in a SecureString.
+   * @param session Optional Mongoose session for transaction support.
+   */
+  public async addMnemonic(
+    mnemonic: SecureString,
+    session?: ClientSession,
+  ): Promise<IMnemonicDocument<TID> | null> {
+    if (!mnemonic.value || !this.constants.MnemonicRegex.test(mnemonic.value)) {
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Validation_MnemonicRegex,
+      );
+    }
+
+    if (await this.mnemonicExists(mnemonic, session)) {
+      return null;
+    }
+    const hmac = this.getMnemonicHmac(mnemonic);
+    const [newDoc] = await this.MnemonicModel.create(
+      [
+        {
+          hmac: hmac,
+        },
+      ],
+      { session },
+    );
+    return newDoc;
+  }
+
+  /**
+   * Retrieves a mnemonic document by ID.
+   * @param mnemonicId The ID of the mnemonic document.
+   * @param session Optional Mongoose session for transaction support.
+   */
+  public async getMnemonicDocument(
+    mnemonicId: TID,
+    session?: ClientSession,
+  ): Promise<IMnemonicDocument<TID> | null> {
+    return await this.MnemonicModel.findById(mnemonicId).session(
+      session ?? null,
+    );
+  }
+
+  /**
+   * Decrypts a mnemonic from a document using the service's master encryption key.
+   * @param doc The mnemonic document.
+   */
+
+  /**
+   * Deletes a mnemonic document by ID.
+   * @param mnemonicId The ID of the mnemonic document.
+   * @param session Optional Mongoose session for transaction support.
+   */
+  public async deleteMnemonicDocument(
+    mnemonicId: TID,
+    session?: ClientSession,
+  ): Promise<void> {
+    await this.MnemonicModel.findByIdAndDelete(mnemonicId).session(
+      session ?? null,
+    );
+  }
+}

package/src/services/request-user.ts

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Service for transforming user documents into request user DTOs and backend objects.
+ * Handles serialization and deserialization of user data for API requests and JWT tokens.
+ * @module services/request-user
+ */
+
+import {
+  IRequestUserDTO,
+  IRoleDTO,
+  ITokenRole,
+} from '@digitaldefiance/suite-core-lib';
+import { IUserDocument } from '../documents';
+import { IRequestUserBackendObject } from '../interfaces/backend-objects/request-user';
+import { RoleService } from './role';
+import {
+  getEnhancedNodeIdProvider,
+  PlatformID,
+} from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Service for converting between user documents, DTOs, and backend objects.
+ * Provides transformation methods for user data in different contexts (API, JWT, database).
+ * @template TID Platform-specific ID type (Buffer, ObjectId, etc.)
+ * @template _TTokenRole Token role type implementing ITokenRole
+ */
+export class RequestUserService<
+  TID extends PlatformID,
+  _TTokenRole extends ITokenRole<TID>,
+> {
+  /**
+   * Converts a user document and roles into a request user DTO for API responses.
+   * Calculates combined role privileges and serializes IDs to strings.
+   * @template TID Platform-specific ID type
+   * @template TLanguage Site language string literal type
+   * @template TTokenRole Token role type
+   * @template TRequestUserDTO Request user DTO type
+   * @param userDoc User document from database
+   * @param roles Array of token roles for the user
+   * @returns Request user DTO suitable for API responses
+   * @throws {Error} If user document is missing _id
+   */
+  public static makeRequestUserDTO<
+    TID extends PlatformID,
+    TLanguage extends string,
+    TTokenRole extends ITokenRole<TID>,
+    TRequestUserDTO extends IRequestUserDTO,
+  >(
+    userDoc:
+      | IUserDocument<TLanguage, TID>
+      | (Pick<
+          IUserDocument<TLanguage, TID>,
+          keyof IUserDocument<TLanguage, TID>
+        > & {
+          _id: PlatformID;
+        }),
+    roles: TTokenRole[],
+  ): TRequestUserDTO {
+    if (!userDoc._id) {
+      throw new Error('User document is missing _id');
+    }
+
+    // Calculate combined role privileges across all roles
+    const rolePrivileges = {
+      admin: roles.some((r) => r.admin),
+      member: roles.some((r) => r.member),
+      child: roles.some((r) => r.child),
+      system: roles.some((r) => r.system),
+    };
+
+    const provider = getEnhancedNodeIdProvider<TID>();
+    return {
+      id: provider.idToString(userDoc._id),
+      email: userDoc.email,
+      roles: roles.map((r) => RoleService.roleToRoleDTO(r)),
+      rolePrivileges,
+      username: userDoc.username,
+      timezone: userDoc.timezone,
+      currency: userDoc.currency,
+      directChallenge: userDoc.directChallenge,
+      emailVerified: userDoc.emailVerified,
+      darkMode: userDoc.darkMode,
+      siteLanguage: userDoc.siteLanguage as string,
+      ...(userDoc.lastLogin && { lastLogin: userDoc.lastLogin.toString() }),
+    } as TRequestUserDTO;
+  }
+
+  /**
+   * Hydrates a request user DTO back into a backend object with typed IDs and dates.
+   * Converts string IDs to platform-specific types and reconstitutes Date objects.
+   * @template TID Platform-specific ID type
+   * @template TLanguage Site language string literal type
+   * @template TRequestUserDTO Request user DTO type with site language
+   * @param requestUser Request user DTO from API or JWT
+   * @returns Backend object with typed IDs and dates
+   */
+  public static hydrateRequestUser<
+    TID extends PlatformID,
+    TLanguage extends string,
+    TRequestUserDTO extends IRequestUserDTO & { siteLanguage: TLanguage },
+  >(requestUser: TRequestUserDTO): IRequestUserBackendObject<TLanguage, TID> {
+    const provider = getEnhancedNodeIdProvider<TID>();
+    const convert = (id: string) => provider.idFromString(id);
+    const hydratedRoles = requestUser.roles.map((role: IRoleDTO) =>
+      RoleService.hydrateRoleDTOToBackend<TID>(role),
+    );
+
+    const hydratedUser: IRequestUserBackendObject<TLanguage, TID> = {
+      id: convert(requestUser.id),
+      email: requestUser.email,
+      roles: hydratedRoles,
+      rolePrivileges: requestUser.rolePrivileges,
+      username: requestUser.username,
+      timezone: requestUser.timezone,
+      currency: requestUser.currency,
+      directChallenge: requestUser.directChallenge,
+      emailVerified: requestUser.emailVerified,
+      darkMode: requestUser.darkMode,
+      siteLanguage: requestUser.siteLanguage,
+    };
+
+    if (requestUser.lastLogin) {
+      hydratedUser.lastLogin = new Date(requestUser.lastLogin);
+    }
+
+    return hydratedUser;
+  }
+}

package/src/services/role.ts

@@ -0,0 +1,417 @@
+/**
+ * @fileoverview Role-based access control (RBAC) service.
+ * Manages roles, user-role relationships, and permission checks.
+ * @module services/role
+ */
+
+import { MemberType } from '@digitaldefiance/ecies-lib';
+import {
+  GlobalActiveContext,
+  I18nEngine,
+  IActiveContext,
+} from '@digitaldefiance/i18n-lib';
+import { ClientSession, Document } from '@digitaldefiance/mongoose-types';
+import {
+  IRoleBase,
+  IRoleDTO,
+  ITokenRole,
+  ITokenRoleDTO,
+  LastAdminError,
+  Role,
+} from '@digitaldefiance/suite-core-lib';
+import { IUserDocument } from '../documents';
+import { IRoleDocument } from '../documents/role';
+import { IUserRoleDocument } from '../documents/user-role';
+import { BaseModelName } from '../enumerations/base-model-name';
+import { IApplication } from '../interfaces/application';
+import { IRoleBackendObject } from '../interfaces/backend-objects/role';
+import { ModelRegistry } from '../model-registry';
+import { omit } from '../utils';
+import { BaseService } from './base';
+import {
+  getEnhancedNodeIdProvider,
+  type PlatformID,
+} from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Service for managing roles and role-based access control.
+ * Handles role creation, user-role assignments, and permission queries.
+ * @template TID - Platform ID type (defaults to Buffer)
+ * @template TDate - Date type (defaults to Date)
+ * @template TTokenRole - Token role interface type
+ * @extends {BaseService<TID>}
+ */
+export class RoleService<
+  TID extends PlatformID = Buffer,
+  TDate extends Date = Date,
+  TTokenRole extends ITokenRole<TID, TDate> = ITokenRole<TID, TDate>,
+> extends BaseService<TID> {
+  /**
+   * Constructor for the role service
+   * @param application The application object
+   */
+  constructor(application: IApplication<TID>) {
+    super(application);
+  }
+
+  public static roleToRoleDTO<
+    TID extends PlatformID = Buffer,
+    TDate extends Date = Date,
+  >(
+    role: ITokenRole<TID, TDate> | IRoleDocument<TID> | Partial<IRoleBase<TID>>,
+  ): ITokenRoleDTO {
+    const provider = getEnhancedNodeIdProvider<TID>();
+    const roleObj = role instanceof Document ? role.toObject() : role;
+    return {
+      _id: provider.idToString(roleObj._id),
+      name: roleObj.name as string,
+      admin: roleObj.admin ?? false,
+      member: roleObj.member ?? false,
+      child: roleObj.child ?? false,
+      system: roleObj.system ?? false,
+      translatedName:
+        'translatedName' in role ? role.translatedName : role.name,
+      createdAt: (roleObj.createdAt instanceof Date
+        ? roleObj.createdAt.toISOString()
+        : roleObj.createdAt) as string,
+      createdBy: provider.idToString(roleObj.createdBy),
+      updatedAt: (roleObj.updatedAt instanceof Date
+        ? roleObj.updatedAt.toISOString()
+        : roleObj.updatedAt) as string,
+      updatedBy: provider.idToString(roleObj.updatedBy),
+      ...(roleObj.deletedAt
+        ? {
+            deletedAt: (roleObj.deletedAt instanceof Date
+              ? roleObj.deletedAt.toISOString()
+              : roleObj.deletedAt) as string,
+          }
+        : {}),
+      ...(role.deletedBy
+        ? {
+            deletedBy: provider.idToString(roleObj.deletedBy),
+          }
+        : {}),
+    } as ITokenRoleDTO;
+  }
+
+  /**
+   * Given a Role DTO, reconstitute ids and dates
+   * @param role The Role DTO
+   * @returns An IRoleBackendObject
+   */
+  public static hydrateRoleDTOToBackend<TID extends PlatformID = Buffer>(
+    role: ITokenRoleDTO,
+  ): IRoleBackendObject<TID> {
+    const idProvider = getEnhancedNodeIdProvider<TID>();
+    const convert = (id: string) => idProvider.idFromString(id);
+    return {
+      ...(omit<ITokenRoleDTO, 'translatedName'>(role, [
+        'translatedName',
+      ]) as IRoleDTO),
+      _id: convert(role._id),
+      name: role.name as Role,
+      createdAt: new Date(role.createdAt),
+      createdBy: convert(role.createdBy),
+      updatedAt: new Date(role.updatedAt),
+      updatedBy: convert(role.updatedBy),
+      ...(role.deletedAt ? { deletedAt: new Date(role.deletedAt) } : {}),
+      ...(role.deletedBy
+        ? {
+            deletedBy: convert(role.deletedBy),
+          }
+        : {}),
+    } as IRoleBackendObject<TID>;
+  }
+
+  /**
+   * Gets the role ID by name
+   * @param roleName The name of the role
+   * @returns The role ID or null if not found
+   */
+  public async getRoleIdByName(
+    roleName: Role,
+    session?: ClientSession,
+  ): Promise<TID | null> {
+    const RoleModel = ModelRegistry.instance.get<any, any>(
+      BaseModelName.Role,
+    ).model;
+    const role = await RoleModel.findOne({ name: roleName }, undefined, {
+      session,
+    }).select('_id');
+    if (!role) {
+      return null;
+    }
+    return role._id as TID;
+  }
+
+  /**
+   * Creates a new role
+   * @param roleData The role data
+   * @param session Optional mongoose session
+   * @returns The created role document
+   */
+  public async createRole(
+    roleData: IRoleBase<TID, TDate, Role>,
+    session?: ClientSession | null,
+  ): Promise<IRoleDocument<TID>> {
+    const RoleModel = ModelRegistry.instance.get<any, any>(
+      BaseModelName.Role,
+    ).model;
+    const role = new RoleModel(roleData);
+    const savedRole = await role.save(session ? { session } : {});
+    return savedRole as IRoleDocument<TID>;
+  }
+
+  /**
+   * Adds a user to a role
+   * @param roleId - The role id
+   * @param userId - The user id
+   * @param createdBy - The user creating the relationship
+   * @param session Optional mongoose session
+   */
+  public async addUserToRole(
+    roleId: TID,
+    userId: TID,
+    createdBy: TID,
+    session?: ClientSession,
+    overrideId?: TID,
+  ): Promise<IUserRoleDocument<TID>> {
+    const UserRoleModel = ModelRegistry.instance.get<any, any>(
+      BaseModelName.UserRole,
+    ).model;
+
+    // Check if the user-role relationship already exists (and is not deleted)
+    const existingUserRole = await UserRoleModel.findOne({
+      userId,
+      roleId,
+      deletedAt: { $exists: false },
+    }).session(session ?? null);
+
+    if (existingUserRole) {
+      // Relationship already exists, no need to create it again
+      return existingUserRole;
+    }
+
+    const userRole = new UserRoleModel({
+      ...(overrideId ? { _id: overrideId } : {}),
+      userId,
+      roleId,
+      createdBy,
+      updatedBy: createdBy,
+    });
+    const result = await userRole.save({ session });
+    return result;
+  }
+
+  /**
+   * Removes a user from a role
+   * @param roleId - The role id
+   * @param userId - The user id
+   * @param deletedBy - The user removing the relationship
+   * @param session Optional mongoose session
+   * @throws LastAdminError if attempting to remove the last admin
+   */
+  public async removeUserFromRole(
+    roleId: TID,
+    userId: TID,
+    deletedBy: TID,
+    session?: ClientSession,
+  ): Promise<void> {
+    const RoleModel = ModelRegistry.instance.get<any, any>(
+      BaseModelName.Role,
+    ).model;
+    const UserRoleModel = ModelRegistry.instance.get<any, any>(
+      BaseModelName.UserRole,
+    ).model;
+
+    const role = await RoleModel.findById(roleId).session(session ?? null);
+    if (role?.admin) {
+      const adminCount = await UserRoleModel.countDocuments({
+        roleId,
+        deletedAt: { $exists: false },
+      }).session(session ?? null);
+      if (adminCount <= 1) {
+        throw new LastAdminError();
+      }
+    }
+
+    await UserRoleModel.findOneAndUpdate(
+      { userId, roleId, deletedAt: { $exists: false } },
+      { deletedAt: new Date(), deletedBy },
+      { session },
+    );
+  }
+
+  /**
+   * Deletes a role by ID
+   * @param roleId The role ID
+   * @param deleter The ID of the user deleting the role
+   * @param hardDelete Whether to hard delete the role
+   * @param session Optional mongoose session
+   */
+  public async deleteRole(
+    roleId: TID,
+    deleter: TID,
+    hardDelete: boolean,
+    session?: ClientSession,
+  ): Promise<void> {
+    const RoleModel = ModelRegistry.instance.get<any, any>(
+      BaseModelName.Role,
+    ).model;
+    if (hardDelete) {
+      await RoleModel.findByIdAndDelete(roleId).session(session ?? null);
+    } else {
+      await RoleModel.findByIdAndUpdate(roleId, {
+        deletedAt: new Date(),
+        deletedBy: deleter,
+      }).session(session ?? null);
+    }
+  }
+
+  /**
+   * Gets all roles for a user
+   * @param userId The user ID
+   * @param session Optional mongoose session
+   * @returns The roles the user is a member of
+   */
+  public async getUserRoles(
+    userId: TID,
+    session?: ClientSession,
+  ): Promise<IRoleDocument<TID>[]> {
+    const UserRoleModel = ModelRegistry.instance.get<any, any>(
+      BaseModelName.UserRole,
+    ).model;
+    const RoleModel = ModelRegistry.instance.get<any, any>(
+      BaseModelName.Role,
+    ).model;
+    if (!UserRoleModel || !RoleModel) throw new Error('Model not registered');
+
+    // Return full documents
+    const userRoles = await UserRoleModel.find({
+      userId,
+      deletedAt: { $exists: false },
+    })
+      .select('roleId')
+      .session(session ?? null);
+
+    const roleIds = userRoles.map((ur) => ur.roleId);
+    return (await RoleModel.find({
+      _id: { $in: roleIds },
+      deletedAt: { $exists: false },
+    }).session(session ?? null)) as IRoleDocument<TID>[];
+  }
+
+  /**
+   * Gets all users for a role
+   * @param roleId The role ID
+   * @param session Optional mongoose session
+   * @returns The user IDs that are members of the role
+   */
+  public async getRoleUsers(
+    roleId: TID,
+    session?: ClientSession,
+  ): Promise<TID[]> {
+    const UserRoleModel = ModelRegistry.instance.get<any, any>(
+      BaseModelName.UserRole,
+    ).model;
+
+    // Return full documents
+    const userRoles = await UserRoleModel.find({
+      roleId,
+      deletedAt: { $exists: false },
+    })
+      .select('userId')
+      .session(session ?? null);
+
+    return userRoles.map((ur) => ur.userId);
+  }
+
+  /** Convert roles to translated TokenRoles */
+  public rolesToTokenRoles(
+    roles: Array<IRoleBackendObject<TID>>,
+    overrideLanguage?: string,
+  ): Array<TTokenRole> {
+    return roles.map((role) => {
+      const engine = I18nEngine.getInstance('default');
+      const userLang = GlobalActiveContext.getInstance<
+        string,
+        IActiveContext<string>
+      >().userLanguage;
+      const lang = (overrideLanguage || userLang || 'en-US') as string;
+      const roleTranslation = engine.translateEnum(Role, role.name, lang);
+      // Convert Mongoose document to plain object if needed
+      const roleObj = role instanceof Document ? role.toObject() : role;
+      return {
+        ...roleObj,
+        translatedName: roleTranslation,
+      } as TTokenRole;
+    });
+  }
+
+  public async isUserAdmin(
+    userDoc: IUserDocument<string, TID>,
+    session?: ClientSession,
+    providedRoles?: Array<IRoleDocument<TID>>,
+  ): Promise<boolean> {
+    const roles =
+      providedRoles ?? (await this.getUserRoles(userDoc._id, session));
+    if (roles.filter((r) => r.admin).length > 0) {
+      return true;
+    }
+    return false;
+  }
+
+  public async isUserMember(
+    userDoc: IUserDocument<string, TID>,
+    session?: ClientSession,
+    providedRoles?: Array<IRoleDocument<TID>>,
+  ): Promise<boolean> {
+    const roles =
+      providedRoles ?? (await this.getUserRoles(userDoc._id, session));
+    if (roles.filter((r) => r.member).length > 0) {
+      return true;
+    }
+    return false;
+  }
+
+  public async isUserChild(
+    userDoc: IUserDocument<string, TID>,
+    session?: ClientSession,
+    providedRoles?: Array<IRoleDocument<TID>>,
+  ): Promise<boolean> {
+    const roles =
+      providedRoles ?? (await this.getUserRoles(userDoc._id, session));
+    if (roles.filter((r) => r.child).length > 0) {
+      return true;
+    }
+    return false;
+  }
+
+  public async isSystemUser(
+    userDoc: IUserDocument<string, TID>,
+    session?: ClientSession,
+    providedRoles?: Array<IRoleDocument<TID>>,
+  ): Promise<boolean> {
+    const roles =
+      providedRoles ?? (await this.getUserRoles(userDoc._id, session));
+    return roles.some((r) => r.system);
+  }
+
+  public async getMemberType(
+    userDoc: IUserDocument<string, TID>,
+    session?: ClientSession,
+    providedRoles?: Array<IRoleDocument<TID>>,
+  ): Promise<MemberType> {
+    const roles =
+      providedRoles ?? (await this.getUserRoles(userDoc._id, session));
+    if (await this.isSystemUser(userDoc, session, roles)) {
+      return MemberType.System;
+    } else if (await this.isUserAdmin(userDoc, session, roles)) {
+      return MemberType.Admin;
+    } else if (await this.isUserMember(userDoc, session, roles)) {
+      return MemberType.User;
+    } else {
+      return MemberType.Anonymous;
+    }
+  }
+}