@digitaldefiance/node-express-suite 3.6.20 → 3.6.21

package/src/interfaces/models/{user.d.ts → user.ts}

@@ -1,11 +1,19 @@
 import { Types } from '@digitaldefiance/mongoose-types';
 import { AccountStatus, IUserBase } from '@digitaldefiance/suite-core-lib';
+
 /**
  * Front-end Base interface for user collection documents
  */
-export type IFrontendUser<TLanguage extends string> = IUserBase<string, Date, TLanguage, AccountStatus>;
+export type IFrontendUser<TLanguage extends string> = IUserBase<
+  string,
+  Date,
+  TLanguage,
+  AccountStatus
+>;
 /**
  * Back-end Base interface for user collection documents
  */
-export type IBackendUser<TLanguage extends string, I = Types.ObjectId> = IUserBase<I, Date, TLanguage, AccountStatus>;
-//# sourceMappingURL=user.d.ts.map
+export type IBackendUser<
+  TLanguage extends string,
+  I = Types.ObjectId,
+> = IUserBase<I, Date, TLanguage, AccountStatus>;

package/src/interfaces/mongo-errors.ts

@@ -0,0 +1,5 @@
+import { Error } from '@digitaldefiance/mongoose-types';
+
+export interface IMongoErrors {
+  [key: string]: Error.ValidatorError | Error.CastError;
+}

package/src/interfaces/request-user.ts

@@ -0,0 +1,70 @@
+import { Types } from '@digitaldefiance/mongoose-types';
+import {
+  ICombinedRolePrivileges,
+  IRoleDTO,
+  IRoleFrontendObject,
+} from '@digitaldefiance/suite-core-lib';
+import { IRoleBackendObject } from './backend-objects/role';
+
+/**
+ * Interface for the user object stored in the request object
+ * This is not used for mongoose but for request handling
+ */
+export interface IRequestUser<
+  I extends Types.ObjectId | string = string,
+  R extends
+    | Array<IRoleDTO>
+    | Array<IRoleFrontendObject>
+    | Array<IRoleBackendObject> = Array<IRoleDTO>,
+  S extends string = string,
+  D extends Date | string = string,
+> {
+  /**
+   * The ID of the user
+   */
+  id: I;
+  /**
+   * The roles associated with the user
+   */
+  roles: R;
+  /**
+   * Combined role privileges across all user roles
+   */
+  rolePrivileges: ICombinedRolePrivileges;
+  /**
+   * The username of the user
+   */
+  username: string;
+  /**
+   * The email address of the user
+   */
+  email: string;
+  /**
+   * The timezone of the user
+   */
+  timezone: string;
+  /**
+   * The currency preference of the user
+   */
+  currency: string;
+  /**
+   * Whether the user has direct challenge login enabled
+   */
+  directChallenge: boolean;
+  /**
+   * The language of the user
+   */
+  siteLanguage: S;
+  /**
+   * The date the user last logged in
+   */
+  lastLogin?: D;
+  /**
+   * Whether the user has verified their email address
+   */
+  emailVerified: boolean;
+  /**
+   * Whether the user prefers dark mode
+   */
+  darkMode: boolean;
+}

package/src/interfaces/required-string-keys.ts

@@ -0,0 +1,26 @@
+/**
+ * Base interface defining the minimum required string keys that must be implemented
+ * by any application using this library
+ */
+export interface RequiredStringKeys {
+  Common_UnexpectedError: string;
+  Error_EngineAlreadySet: string;
+  Error_EngineNotSet: string;
+  Error_LengthExceedsMaximum: string;
+  Error_LengthIsInvalidType: string;
+  // Validation errors
+  ValidationError: string;
+  Validation_MissingValidatedData: string;
+  Validation_MissingValidatedDataForField: string;
+
+  // Admin/system messages
+  Admin_NoMongoDbClientFoundFallingBack: string;
+  Admin_TransactionFailedTransientTemplate: string;
+  Admin_TransactionTimeoutTemplate: string;
+}
+
+/**
+ * Type constraint to ensure user's string key enum extends the required keys
+ */
+export type ExtendedStringKeys<T extends string> =
+  T extends keyof RequiredStringKeys ? T : T | keyof RequiredStringKeys;

package/src/interfaces/schema.ts

@@ -0,0 +1,31 @@
+import { Model, Schema } from '@digitaldefiance/mongoose-types';
+import { IBaseDocument } from '../documents/base';
+import { IDiscriminatorCollections } from '../interfaces/discriminator-collections';
+
+/**
+ * Interface for each schema in the schema map
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ISchema<T extends IBaseDocument<any>> {
+  /**
+   * The name of the collection, eg 'models'
+   */
+  collection: string;
+  /**
+   * The model for the schema
+   */
+
+  model: Model<T>;
+  /**
+   * The name of the model, eg 'Model'
+   */
+  modelName: string;
+  /**
+   * The schema for the model
+   */
+  schema: Schema;
+  /**
+   * Discriminators for the model
+   */
+  discriminators?: IDiscriminatorCollections<T>;
+}

package/src/interfaces/server-init-result.ts

@@ -0,0 +1,40 @@
+import { Types } from '@digitaldefiance/mongoose-types';
+import { Member } from '@digitaldefiance/node-ecies-lib';
+import { IRoleDocument } from '../documents/role';
+import { IUserDocument } from '../documents/user';
+import { IUserRoleDocument } from '../documents/user-role';
+
+// Re-export essential document types
+export type { IRoleDocument, IUserDocument, IUserRoleDocument };
+
+export interface IServerInitResult<
+  I extends Types.ObjectId | string = Types.ObjectId,
+> {
+  adminRole: IRoleDocument<I>;
+  adminUser: IUserDocument<string, I>;
+  adminUsername: string;
+  adminEmail: string;
+  adminMnemonic: string;
+  adminPassword: string;
+  adminBackupCodes: Array<string>;
+  adminMember: Member<I>;
+  adminUserRole: IUserRoleDocument<I>;
+  memberRole: IRoleDocument<I>;
+  memberUser: IUserDocument<string, I>;
+  memberUsername: string;
+  memberEmail: string;
+  memberMnemonic: string;
+  memberPassword: string;
+  memberBackupCodes: Array<string>;
+  memberMember: Member<I>;
+  memberUserRole: IUserRoleDocument<I>;
+  systemRole: IRoleDocument<I>;
+  systemUser: IUserDocument<string, I>;
+  systemUsername: string;
+  systemEmail: string;
+  systemMnemonic: string;
+  systemPassword: string;
+  systemBackupCodes: Array<string>;
+  systemMember: Member<I>;
+  systemUserRole: IUserRoleDocument<I>;
+}

package/src/interfaces/status-code-response.ts

@@ -0,0 +1,7 @@
+import { ApiResponse } from '../types';
+
+export interface IStatusCodeResponse<T extends ApiResponse> {
+  statusCode: number;
+  response: T;
+  headers?: Record<string, string>;
+}

package/src/interfaces/symmetric-encryption-results.d.ts

@@ -1,5 +1,5 @@
 export interface ISymmetricEncryptionResults {
-    encryptedData: Buffer;
-    key: Buffer;
+  encryptedData: Buffer;
+  key: Buffer;
 }
-//# sourceMappingURL=symmetric-encryption-results.d.ts.map
+//# sourceMappingURL=symmetric-encryption-results.d.ts.map

package/src/interfaces/symmetric-encryption-results.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symmetric-encryption-results.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/symmetric-encryption-results.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,2BAA2B;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb"}
+{"version":3,"file":"symmetric-encryption-results.d.ts","sourceRoot":"","sources":["symmetric-encryption-results.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,2BAA2B;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb"}

package/src/interfaces/symmetric-encryption-results.js.map

@@ -1 +1 @@
-{"version":3,"file":"symmetric-encryption-results.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/symmetric-encryption-results.ts"],"names":[],"mappings":""}
+{"version":3,"file":"symmetric-encryption-results.js","sourceRoot":"","sources":["symmetric-encryption-results.ts"],"names":[],"mappings":""}

package/src/interfaces/symmetric-encryption-results.ts

@@ -0,0 +1,4 @@
+export interface ISymmetricEncryptionResults {
+  encryptedData: Buffer;
+  key: Buffer;
+}

package/src/interfaces/{test-environment.d.ts → test-environment.ts}

@@ -1,11 +1,11 @@
 import { MongoMemoryReplSet } from 'mongodb-memory-server';
 import { IApplication } from './application';
 import { IServerInitResult } from './server-init-result';
+
 export interface ITestEnvironment {
-    application: IApplication;
-    mongoServer: MongoMemoryReplSet;
-    mongoUri: string;
-    accountData: IServerInitResult;
-    dbName: string;
+  application: IApplication;
+  mongoServer: MongoMemoryReplSet;
+  mongoUri: string;
+  accountData: IServerInitResult;
+  dbName: string;
 }
-//# sourceMappingURL=test-environment.d.ts.map

package/src/interfaces/{token-response.d.ts → token-response.ts}

@@ -1,5 +1,5 @@
 import { IApiMessageResponse } from './api-message-response';
+
 export interface IApiTokenResponse extends IApiMessageResponse {
-    token: string;
+  token: string;
 }
-//# sourceMappingURL=token-response.d.ts.map

package/src/middlewares/authenticate-crypto.ts

@@ -0,0 +1,216 @@
+import { SecureString } from '@digitaldefiance/ecies-lib';
+import { ClientSession, Types } from '@digitaldefiance/mongoose-types';
+import { Member as BackendMember } from '@digitaldefiance/node-ecies-lib';
+import {
+  AccountStatus,
+  getSuiteCoreTranslation,
+  InvalidCredentialsError,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { NextFunction, Request, Response } from 'express';
+import { ServiceKeys } from '../container';
+import { IUserDocument } from '../documents/user';
+import { BaseModelName } from '../enumerations';
+import { InvalidPasswordError } from '../errors';
+import { IApplication } from '../interfaces/application';
+import { withTransaction } from '../utils';
+
+/**
+ * Middleware to authenticate crypto operations requiring private key access
+ * Expects mnemonic or password in request body for fresh authentication
+ */
+export async function authenticateCrypto<
+  I extends Types.ObjectId | string = Types.ObjectId,
+  TAccountStatus extends string = AccountStatus,
+>(
+  application: IApplication,
+  req: Request,
+  res: Response,
+  next: NextFunction,
+  activeStatusValue: TAccountStatus = AccountStatus.Active as TAccountStatus,
+): Promise<Response | void> {
+  if (!req.user) {
+    return res.status(401).send(
+      // amazonq-ignore-next-line false positive, hardcoded string
+      getSuiteCoreTranslation(SuiteCoreStringKey.Validation_InvalidToken),
+    );
+  }
+
+  // Try validatedBody first (if validation has run), then fall back to raw body
+  // Note: This middleware runs BEFORE validation, so validatedBody may not exist yet
+  const validatedBody = (req as Request & { validatedBody?: unknown })
+    .validatedBody as Record<string, unknown> | undefined;
+  const rawBody = req.body as Record<string, unknown> | undefined;
+  const sourceBody = validatedBody ?? rawBody;
+
+  if (!sourceBody) {
+    return res.status(400).send({
+      // amazonq-ignore-next-line false positive, hardcoded string
+      message: getSuiteCoreTranslation(
+        SuiteCoreStringKey.Validation_MnemonicOrPasswordRequired,
+      ),
+    });
+  }
+
+  const mnemonic =
+    typeof sourceBody['mnemonic'] === 'string'
+      ? (sourceBody['mnemonic'] as string)
+      : undefined;
+  const password =
+    // amazonq-ignore-next-line false positive
+    typeof sourceBody['password'] === 'string'
+      ? (sourceBody['password'] as string)
+      : undefined;
+  if (!mnemonic && !password) {
+    return res.status(400).send({
+      // amazonq-ignore-next-line false positive, hardcoded string
+      message: getSuiteCoreTranslation(
+        SuiteCoreStringKey.Validation_MnemonicOrPasswordRequired,
+      ),
+    });
+  }
+  const UserModel = application.getModel<IUserDocument<string, I>>(
+    BaseModelName.User,
+  );
+  const userService = application.services.get(ServiceKeys.USER) as {
+    loginWithMnemonic: (
+      email: string,
+      mnemonic: SecureString,
+      session?: ClientSession,
+    ) => Promise<any>;
+    loginWithPassword: (
+      email: string,
+      password: string,
+      session?: ClientSession,
+    ) => Promise<any>;
+  };
+
+  try {
+    return await withTransaction<Response | void>(
+      application.db.connection,
+      application.environment.mongo.useTransactions,
+      undefined,
+      async (sess: ClientSession | undefined) => {
+        const userDoc = await UserModel.findById(req.user!.id)
+          .session(sess ?? null)
+          .exec();
+
+        if (!userDoc || userDoc.accountStatus !== activeStatusValue) {
+          return res.status(403).send(
+            // amazonq-ignore-next-line false positive, hardcoded string
+            getSuiteCoreTranslation(SuiteCoreStringKey.Validation_UserNotFound),
+          );
+        }
+
+        // Ensure we're only authenticating the currently logged-in user
+        if (userDoc._id.toString() !== req.user!.id) {
+          return res.status(403).send(
+            // amazonq-ignore-next-line false positive, hardcoded string
+            getSuiteCoreTranslation(
+              SuiteCoreStringKey.Validation_InvalidCredentials,
+            ),
+          );
+        }
+
+        let loginResult: {
+          userDoc: IUserDocument;
+          userMember: BackendMember;
+          adminMember: BackendMember;
+        };
+
+        if (mnemonic) {
+          // Authenticate with mnemonic
+          const userMnemonic = new SecureString(mnemonic);
+          try {
+            loginResult = await userService.loginWithMnemonic(
+              userDoc.email,
+              userMnemonic,
+              sess,
+            );
+          } finally {
+            userMnemonic.dispose();
+          }
+        } else if (password) {
+          // Authenticate with password
+          loginResult = await userService.loginWithPassword(
+            userDoc.email,
+            password,
+            sess,
+          );
+        } else {
+          // Should not happen due to earlier guard; keeps TypeScript happy
+          return res.status(400).send({
+            // amazonq-ignore-next-line false positive, hardcoded string
+            message: getSuiteCoreTranslation(
+              SuiteCoreStringKey.Validation_MnemonicOrPasswordRequired,
+            ),
+          });
+        }
+
+        // Double-check authenticated user matches logged-in user
+        if (loginResult.userDoc._id.toString() !== req.user!.id) {
+          return res.status(403).send(
+            // amazonq-ignore-next-line false positive, hardcoded string
+            getSuiteCoreTranslation(
+              SuiteCoreStringKey.Validation_InvalidCredentials,
+            ),
+          );
+        }
+
+        // Attach the fully authenticated member (with private key) to the request
+        req.eciesUser = loginResult.userMember;
+        // Do not attach the admin user to the request; it's a process-wide singleton
+        // and must not be disposed as part of request cleanup.
+
+        next();
+        return;
+      },
+      {
+        timeoutMs: application.environment.mongo.transactionTimeout,
+      },
+    );
+  } catch (err) {
+    if (
+      err instanceof InvalidCredentialsError ||
+      err instanceof InvalidPasswordError
+    ) {
+      // amazonq-ignore-next-line false positive
+      console.error(
+        'Crypto authentication failed:',
+        `userId=${String(req.user?.id || 'unknown').replace(
+          /[\r\n]/g,
+          '',
+        )} hasPassword=${!!password} hasMnemonic=${!!mnemonic}`,
+      );
+      return res.status(401).send({
+        // amazonq-ignore-next-line false positive, hardcoded string
+        message: getSuiteCoreTranslation(
+          SuiteCoreStringKey.Validation_InvalidCredentials,
+        ),
+      });
+    }
+    const sanitizedErr =
+      err instanceof Error
+        ? err.message.replace(/[\r\n]/g, ' ')
+        : String(err).replace(/[\r\n]/g, ' ');
+    console.error(
+      `${getSuiteCoreTranslation(
+        SuiteCoreStringKey.Error_UnexpectedErrorInAuthenticateCrypto,
+      )}:`,
+      sanitizedErr,
+    );
+    if (err instanceof Error && err.stack) {
+      console.error(
+        `${getSuiteCoreTranslation(SuiteCoreStringKey.Common_StackTrace)}:`,
+        err.stack,
+      );
+    }
+    return res.status(500).send({
+      // amazonq-ignore-next-line false positive, hardcoded string
+      message: getSuiteCoreTranslation(
+        SuiteCoreStringKey.Common_UnexpectedError,
+      ),
+      error: err,
+    });
+  }
+}

package/src/middlewares/authenticate-token.ts

@@ -0,0 +1,150 @@
+import type { Timezone as TimezoneType } from '@digitaldefiance/i18n-lib';
+import { GlobalActiveContext } from '@digitaldefiance/i18n-lib';
+import { ClientSession, Types } from '@digitaldefiance/mongoose-types';
+import {
+  AccountStatus,
+  getSuiteCoreTranslation,
+  ITokenRole,
+  ITokenUser,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { NextFunction, Request, Response } from 'express';
+import { IncomingHttpHeaders } from 'http';
+import { IUserDocument } from '../documents/user';
+import { BaseModelName } from '../enumerations/base-model-name';
+import { TokenExpiredError } from '../errors/token-expired';
+import { IApplication } from '../interfaces/application';
+import { JwtService } from '../services/jwt';
+import { RequestUserService } from '../services/request-user';
+import { RoleService } from '../services/role';
+import { withTransaction } from '../utils';
+
+// Type for Timezone constructor
+type TimezoneConstructor = new (tz: string) => TimezoneType;
+
+// Helper to create Timezone from the same module instance as GlobalActiveContext
+function createTimezone(tz: string): TimezoneType {
+  const context = GlobalActiveContext.getInstance();
+  const TimezoneConstructor = context.adminTimezone
+    .constructor as TimezoneConstructor;
+  return new TimezoneConstructor(tz);
+}
+
+/**
+ * Find the auth token in the headers
+ * @param headers The headers
+ * @returns The auth token
+ */
+export function findAuthToken(headers: IncomingHttpHeaders): string | null {
+  const authHeader = headers['Authorization'] || headers['authorization'];
+  if (authHeader && typeof authHeader === 'string') {
+    const parts = authHeader.split(' ');
+    if (parts.length === 2 && parts[0].toLowerCase() === 'bearer') {
+      return parts[1];
+    }
+  }
+  return null;
+}
+
+/**
+ * Middleware to authenticate a token
+ * @param application The application
+ * @param req The request
+ * @param res The response
+ * @param next The next function
+ * @returns The response
+ */
+export async function authenticateToken<
+  I extends Types.ObjectId | string = Types.ObjectId,
+  D extends Date = Date,
+  TTokenRole extends ITokenRole<I, D> = ITokenRole<I, D>,
+  TTokenUser extends ITokenUser = ITokenUser,
+  TApplication extends IApplication = IApplication,
+>(
+  application: TApplication,
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): Promise<Response> {
+  const UserModel = application.getModel<IUserDocument<string, I>>(
+    BaseModelName.User,
+  );
+  const token = findAuthToken(req.headers);
+  if (token == null) {
+    return res
+      .status(401)
+      .send(
+        getSuiteCoreTranslation(SuiteCoreStringKey.Validation_InvalidToken),
+      );
+  }
+
+  try {
+    return await withTransaction<Response>(
+      application.db.connection,
+      application.environment.mongo.useTransactions,
+      undefined,
+      async (sess: ClientSession | undefined) => {
+        const jwtService = new JwtService<
+          I,
+          D,
+          TTokenRole,
+          TTokenUser,
+          TApplication
+        >(application);
+        const user: TTokenUser | null = await jwtService.verifyToken(token);
+        if (user === null) {
+          return res.status(403).send(
+            // amazonq-ignore-next-line false positive, hardcoded string
+            getSuiteCoreTranslation(SuiteCoreStringKey.Validation_UserNotFound),
+          );
+        }
+        const userDoc = await UserModel.findById(user.userId)
+          .select('-password')
+          .session(sess ?? null)
+          .exec();
+        if (!userDoc || userDoc.accountStatus !== AccountStatus.Active) {
+          return res.status(403).send(
+            // amazonq-ignore-next-line false positive, hardcoded string
+            getSuiteCoreTranslation(SuiteCoreStringKey.Validation_UserNotFound),
+          );
+        }
+        const roleService = new RoleService<I, D, TTokenRole>(application);
+        const roles = await roleService.getUserRoles(userDoc._id as I, sess);
+        const tokenRoles = roleService.rolesToTokenRoles(roles);
+        req.user = RequestUserService.makeRequestUserDTO(userDoc, tokenRoles);
+        const context = GlobalActiveContext.getInstance();
+        context.userLanguage = userDoc.siteLanguage ?? context.userLanguage;
+        context.setLanguageContextSpace('user');
+        context.userTimezone = createTimezone(userDoc.timezone);
+        next();
+        return res;
+      },
+      {
+        timeoutMs: application.environment.mongo.transactionTimeout,
+      },
+    );
+  } catch (err) {
+    if (err instanceof TokenExpiredError) {
+      return res.status(401).send({
+        message: getSuiteCoreTranslation(
+          SuiteCoreStringKey.Validation_TokenExpired,
+        ),
+        error: err,
+      });
+    } else if (err instanceof Error && err.name === 'JsonWebTokenError') {
+      return res.status(400).send({
+        message: getSuiteCoreTranslation(
+          SuiteCoreStringKey.Validation_InvalidToken,
+        ),
+        error: err,
+      });
+    } else {
+      return res.status(500).send({
+        message: getSuiteCoreTranslation(
+          SuiteCoreStringKey.Common_UnexpectedError,
+        ),
+        error: err,
+      });
+    }
+  }
+}

package/src/middlewares/cleanup-crypto.ts

@@ -0,0 +1,37 @@
+import { NextFunction, Request, Response } from 'express';
+
+/**
+ * Middleware to clean up crypto resources after request completion
+ * Should be used after crypto operations to ensure private keys are disposed
+ */
+export function cleanupCrypto(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void {
+  // Store original end function
+  const originalEnd = res.end;
+
+  // Override end function to cleanup before response
+  const wrappedEnd = function (this: Response, ...args: unknown[]) {
+    // Cleanup eciesUser if it exists
+    if (req.eciesUser) {
+      try {
+        // Dispose of sensitive cryptographic material
+        req.eciesUser.dispose();
+        req.eciesUser = undefined;
+      } catch (error) {
+        console.error('Error cleaning up crypto resources:', error);
+      }
+    }
+    // Do not dispose system user here; it may be a process-wide singleton
+
+    // Call original end function
+    // Type assertion needed because we're wrapping the end function
+    return originalEnd.apply(this, args as Parameters<typeof originalEnd>);
+  } as typeof res.end;
+
+  res.end = wrappedEnd;
+
+  next();
+}

package/src/middlewares/{index.d.ts → index.ts}

@@ -2,4 +2,3 @@ export * from './authenticate-crypto';
 export * from './authenticate-token';
 export * from './cleanup-crypto';
 export * from './set-global-context-language';
-//# sourceMappingURL=index.d.ts.map