@digitaldefiance/node-express-suite 3.7.4 → 3.7.5

package/src/interfaces/request-user.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Request user interface for Express request object.
+ * Defines user data structure attached to authenticated requests.
+ * @module interfaces/request-user
+ */
+
+import {
+  ICombinedRolePrivileges,
+  IRoleDTO,
+  IRoleFrontendObject,
+} from '@digitaldefiance/suite-core-lib';
+import { IRoleBackendObject } from './backend-objects/role';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Interface for the user object stored in the request object.
+ * Used for request handling, not for Mongoose documents.
+ * @template TID - Platform ID type (defaults to Buffer)
+ * @template TRole - Role array type (defaults to IRoleDTO[])
+ * @template TLanguage - String type for language (defaults to string)
+ * @template TDate - Date type (defaults to string)
+ */
+export interface IRequestUser<
+  TID extends PlatformID = Buffer,
+  TRole extends
+    | Array<IRoleDTO>
+    | Array<IRoleFrontendObject>
+    | Array<IRoleBackendObject> = Array<IRoleDTO>,
+  TLanguage extends string = string,
+  TDate extends Date | string = string,
+> {
+  /**
+   * The ID of the user
+   */
+  id: TID;
+  /**
+   * The roles associated with the user
+   */
+  roles: TRole;
+  /**
+   * 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: TLanguage;
+  /**
+   * The date the user last logged in
+   */
+  lastLogin?: TDate;
+  /**
+   * 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,33 @@
+/**
+ * @fileoverview Required string keys interface for i18n.
+ * Defines minimum required translation keys for the library.
+ * @module interfaces/required-string-keys
+ */
+
+/**
+ * Base interface defining the minimum required string keys.
+ * 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.
+ * @template T - String key type
+ */
+export type ExtendedStringKeys<T extends string> =
+  T extends keyof RequiredStringKeys ? T : T | keyof RequiredStringKeys;

package/src/interfaces/schema.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Schema interface for Mongoose model registration.
+ * Defines structure for schema map entries with models and discriminators.
+ * @module interfaces/schema
+ */
+
+import { Model, Schema } from '@digitaldefiance/mongoose-types';
+import { IBaseDocument } from '../documents/base';
+import { IDiscriminatorCollections } from '../interfaces/discriminator-collections';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Interface for each schema in the schema map.
+ * Combines Mongoose schema, model, and collection metadata with optional discriminators.
+ * @template T - Document type extending IBaseDocument
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ISchema<
+  TID extends PlatformID,
+  T extends IBaseDocument<any, TID>,
+> {
+  /**
+   * 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<TID, T>;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Server initialization result interface.
+ * Defines structure for test server initialization with admin, member, and system users.
+ * @module interfaces/server-init-result
+ */
+
+import { Member, PlatformID } 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 };
+
+/**
+ * Result of server initialization for testing.
+ * Contains admin, member, and system user accounts with credentials and roles.
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export interface IServerInitResult<TID extends PlatformID = Buffer> {
+  adminRole: IRoleDocument<TID>;
+  adminUser: IUserDocument<string, TID>;
+  adminUsername: string;
+  adminEmail: string;
+  adminMnemonic: string;
+  adminPassword: string;
+  adminBackupCodes: Array<string>;
+  adminMember: Member<TID>;
+  adminUserRole: IUserRoleDocument<TID>;
+  memberRole: IRoleDocument<TID>;
+  memberUser: IUserDocument<string, TID>;
+  memberUsername: string;
+  memberEmail: string;
+  memberMnemonic: string;
+  memberPassword: string;
+  memberBackupCodes: Array<string>;
+  memberMember: Member<TID>;
+  memberUserRole: IUserRoleDocument<TID>;
+  systemRole: IRoleDocument<TID>;
+  systemUser: IUserDocument<string, TID>;
+  systemUsername: string;
+  systemEmail: string;
+  systemMnemonic: string;
+  systemPassword: string;
+  systemBackupCodes: Array<string>;
+  systemMember: Member<TID>;
+  systemUserRole: IUserRoleDocument<TID>;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Status code response wrapper interface.
+ * Wraps API responses with HTTP status codes and optional headers.
+ * @module interfaces/status-code-response
+ */
+
+import { ApiResponse } from '../types';
+
+/**
+ * HTTP response wrapper with status code and headers.
+ * @template T - API response type
+ * @property {number} statusCode - HTTP status code
+ * @property {T} response - Response payload
+ * @property {Record<string, string>} [headers] - Optional HTTP headers
+ */
+export interface IStatusCodeResponse<T extends ApiResponse> {
+  statusCode: number;
+  response: T;
+  headers?: Record<string, string>;
+}

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,15 @@
+/**
+ * @fileoverview Symmetric encryption results interface.
+ * Defines structure for symmetric encryption operation results.
+ * @module interfaces/symmetric-encryption-results
+ */
+
+/**
+ * Results of symmetric encryption operation.
+ * @property {Buffer} encryptedData - Encrypted data buffer
+ * @property {Buffer} key - Encryption key used
+ */
+export interface ISymmetricEncryptionResults {
+  encryptedData: Buffer;
+  key: Buffer;
+}

package/src/interfaces/test-environment.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Test environment interface.
+ * Defines structure for test environment with in-memory MongoDB and initialized accounts.
+ * @module interfaces/test-environment
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { MongoMemoryReplSet } from 'mongodb-memory-server';
+import { IApplication } from './application';
+import { IServerInitResult } from './server-init-result';
+
+/**
+ * Test environment configuration.
+ * Contains application instance, in-memory MongoDB, and test account data.
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export interface ITestEnvironment<TID extends PlatformID = Buffer> {
+  application: IApplication<TID>;
+  mongoServer: MongoMemoryReplSet;
+  mongoUri: string;
+  accountData: IServerInitResult<TID>;
+  dbName: string;
+}

package/src/interfaces/token-response.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Token response interface for authentication.
+ * Extends API message response with JWT token.
+ * @module interfaces/token-response
+ */
+
+import { IApiMessageResponse } from './api-message-response';
+
+/**
+ * API response containing authentication token.
+ * @extends IApiMessageResponse
+ * @property {string} token - JWT authentication token
+ */
+export interface IApiTokenResponse extends IApiMessageResponse {
+  token: string;
+}

package/src/middleware-utils.ts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Middleware initialization utilities.
+ * Configures Express middleware including Helmet, CORS, and body parsers.
+ * @module middleware-utils
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import cors from 'cors';
+import { randomBytes } from 'crypto';
+import {
+  Application,
+  json,
+  NextFunction,
+  Request,
+  Response,
+  urlencoded,
+} from 'express';
+import helmet, { HelmetOptions } from 'helmet';
+import { IncomingMessage, ServerResponse } from 'http';
+import { ISimpleCSPDef, isSimpleCSPDef } from './interfaces/csp-definition';
+
+/**
+ * Creates a CORS options delegate function.
+ * @param {string[]} corsWhitelist - Array of allowed origins
+ * @returns {Function} CORS options delegate
+ */
+export const corsOptionsDelegate = (corsWhitelist: string[]) => {
+  return (
+    req: cors.CorsRequest,
+    callback: (
+      error: Error | null,
+      options: cors.CorsOptions | undefined,
+    ) => void,
+  ) => {
+    let corsOptions: cors.CorsOptions;
+    const origin = req.headers.origin;
+    if (
+      origin &&
+      corsWhitelist.find((w: string | RegExp) => {
+        if (w instanceof RegExp) {
+          return w.test(origin);
+        } else {
+          return w === origin;
+        }
+      })
+    ) {
+      corsOptions = { origin: true };
+    } else {
+      corsOptions = { origin: false };
+    }
+    callback(null, corsOptions);
+  };
+};
+
+/**
+ * Type guard to check if object is HelmetOptions.
+ * @param {unknown} obj - Object to check
+ * @returns {boolean} True if object is HelmetOptions
+ */
+export const isHelmetOptions = (obj: unknown): obj is HelmetOptions => {
+  // A very basic check; in real scenarios, you might want to be more thorough
+  return !!(
+    obj &&
+    typeof obj === 'object' &&
+    ('contentSecurityPolicy' in obj ||
+      'crossOriginEmbedderPolicy' in obj ||
+      'crossOriginOpenerPolicy' in obj ||
+      'crossOriginResourcePolicy' in obj ||
+      'originAgentCluster' in obj ||
+      'referrerPolicy' in obj)
+  );
+};
+
+/**
+ * Initializes Express middleware stack.
+ * Configures Helmet for security headers, CORS, and body parsers.
+ * @param {Application} app - Express application instance
+ * @param {string[]} corsWhitelist - Array of allowed CORS origins
+ * @param {ISimpleCSPDef | HelmetOptions} csp - CSP configuration or Helmet options
+ * @throws {TranslatableSuiteError} If invalid CSP configuration provided
+ */
+export const initMiddleware = (
+  app: Application,
+  corsWhitelist: string[],
+  csp: ISimpleCSPDef | HelmetOptions,
+): void => {
+  // Helmet helps you secure your Express apps by setting various HTTP headers
+  // CSP nonce
+  app.use((req: Request, res: Response, next: NextFunction) => {
+    res.locals['cspNonce'] = randomBytes(32).toString('hex');
+    next();
+  });
+  if (isSimpleCSPDef(csp)) {
+    app.use(
+      helmet({
+        contentSecurityPolicy: {
+          directives: {
+            defaultSrc: ["'self'", ...csp.defaultSrc],
+            imgSrc: ["'self'", 'data:', 'blob:', ...csp.imgSrc],
+            connectSrc: ["'self'", ...csp.connectSrc],
+            scriptSrc: [
+              "'self'",
+              //"'unsafe-inline'",
+              "'strict-dynamic'",
+              (req: IncomingMessage, res: ServerResponse) => {
+                const response = res as Response;
+                return `'nonce-${response.locals['cspNonce']}'`;
+              },
+              ...csp.scriptSrc,
+            ],
+            styleSrc: [
+              "'self'",
+              // "'unsafe-inline'",
+              ...csp.styleSrc,
+            ],
+            fontSrc: ["'self'", ...csp.fontSrc],
+            frameSrc: ["'self'", ...csp.frameSrc],
+          },
+        },
+      }),
+    );
+  } else if (isHelmetOptions(csp)) {
+    app.use(helmet(csp));
+  } else {
+    throw new TranslatableSuiteError(
+      SuiteCoreStringKey.Error_InvalidCspOrHelmetOptionsProvided,
+    );
+  }
+  // Enable CORS
+  app.use(cors(corsOptionsDelegate(corsWhitelist)));
+  // Parse incoming requests with JSON payloads
+  app.use(json());
+  // Parse incoming requests with urlencoded payloads
+  app.use(urlencoded({ extended: true }));
+};

package/src/middlewares/authenticate-crypto.ts

@@ -0,0 +1,237 @@
+/**
+ * @fileoverview Cryptographic authentication middleware for operations requiring private keys.
+ * Validates mnemonic or password to unlock user's private key for sensitive operations.
+ * @module middlewares/authenticate-crypto
+ */
+
+import { SecureString } from '@digitaldefiance/ecies-lib';
+import { ClientSession } from '@digitaldefiance/mongoose-types';
+import {
+  Member as BackendMember,
+  PlatformID,
+} 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';
+
+/**
+ * Express middleware for cryptographic authentication.
+ * Requires mnemonic or password in request body to unlock user's private key.
+ * Attaches authenticated BackendMember with private key to req.eciesUser.
+ * Used for operations requiring cryptographic signing or decryption.
+ * @template TID - Platform ID type (defaults to Buffer)
+ * @template TAccountStatus - Account status type (defaults to AccountStatus)
+ * @param {IApplication<TID>} application - Application instance
+ * @param {Request} req - Express request object
+ * @param {Response} res - Express response object
+ * @param {NextFunction} next - Express next function
+ * @param {TAccountStatus} [activeStatusValue] - Expected active account status
+ * @returns {Promise<Response | void>} Response or void if successful
+ * @throws {InvalidCredentialsError} When credentials are invalid
+ * @throws {InvalidPasswordError} When password is incorrect
+ */
+export async function authenticateCrypto<
+  TID extends PlatformID = Buffer,
+  TAccountStatus extends string = AccountStatus,
+>(
+  application: IApplication<TID>,
+  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, TID>>(
+    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,
+    });
+  }
+}