@digitaldefiance/node-express-suite 3.7.4 → 3.7.5

package/src/errors/express-validation.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Express validation error for handling express-validator validation failures.
+ * Wraps validation errors with translatable error messages.
+ * @module errors/express-validation
+ */
+
+import { TranslatableGenericError } from '@digitaldefiance/i18n-lib';
+import {
+  SuiteCoreComponentId,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { Result, ValidationError } from 'express-validator';
+
+/**
+ * Error thrown when express-validator validation fails.
+ * Contains the validation errors and sets HTTP status code to 422 (Unprocessable Entity).
+ */
+export class ExpressValidationError extends TranslatableGenericError<SuiteCoreStringKey> {
+  /** Validation errors from express-validator */
+  public readonly errors: Result<ValidationError> | ValidationError[];
+  /** HTTP status code (422 for validation errors) */
+  public readonly statusCode?: number = 422;
+
+  /**
+   * Creates a new express validation error.
+   * @param errors Validation errors from express-validator
+   */
+  constructor(errors: Result<ValidationError> | ValidationError[]) {
+    const errorsArray = Array.isArray(errors) ? errors : errors.array();
+    const _errorCount = errorsArray.length;
+    super(
+      SuiteCoreComponentId,
+      SuiteCoreStringKey.Validation_ExpressValidationFailed,
+    );
+    this.errors = errors;
+    this.name = 'ExpressValidationError';
+  }
+}

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

@@ -10,4 +10,3 @@ export * from './model-not-registered';
 export * from './mongoose-validation';
 export * from './symmetric';
 export * from './token-expired';
-//# sourceMappingURL=index.d.ts.map

package/src/errors/invalid-backup-code-version.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Error for invalid backup code version.
+ * Thrown when attempting to use a backup code with an unsupported version.
+ * @module errors/invalid-backup-code-version
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Error thrown when a backup code has an invalid or unsupported version.
+ */
+export class InvalidBackupCodeVersionError extends TranslatableSuiteError {
+  /** The invalid version string */
+  public readonly version: string;
+
+  /**
+   * Creates a new invalid backup code version error.
+   * @param version The invalid version string
+   */
+  constructor(version: string) {
+    super(SuiteCoreStringKey.Error_InvalidBackupCodeVersionTemplate, {
+      version,
+    });
+    this.version = version;
+    this.name = 'InvalidBackupCodeVersionError';
+  }
+}

package/src/errors/invalid-jwt-token.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Error for invalid JWT tokens.
+ * Thrown when JWT token validation fails, sets HTTP status code to 401.
+ * @module errors/invalid-jwt-token
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteHandleableError,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Error thrown when a JWT token is invalid or malformed.
+ * Sets HTTP status code to 401 (Unauthorized).
+ */
+export class InvalidJwtTokenError extends TranslatableSuiteHandleableError {
+  /**
+   * Creates a new invalid JWT token error.
+   */
+  constructor() {
+    super(SuiteCoreStringKey.Validation_InvalidToken, { statusCode: 401 });
+    this.name = 'InvalidJwtTokenError';
+  }
+}

package/src/errors/invalid-model.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Error for invalid model keys in the model registry.
+ * Thrown when attempting to access a model with an invalid key.
+ * @module errors/invalid-model
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Error thrown when a model key is invalid or not recognized.
+ */
+export class InvalidModelError extends TranslatableSuiteError {
+  /**
+   * Creates a new invalid model error.
+   * @param modelKey The invalid model key
+   */
+  constructor(public readonly modelKey: string) {
+    super(SuiteCoreStringKey.Error_InvalidModelKeyTemplate, { modelKey });
+    this.name = 'InvalidModelError';
+  }
+}

package/src/errors/invalid-new-password.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Error for invalid new passwords that don't meet requirements.
+ * Thrown during password changes or registration when password validation fails.
+ * @module errors/invalid-new-password
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteHandleableError,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Error thrown when a new password doesn't meet security requirements.
+ * Sets HTTP status code to 422 (Unprocessable Entity).
+ */
+export class InvalidNewPasswordError extends TranslatableSuiteHandleableError {
+  /**
+   * Creates a new invalid new password error.
+   * @param language Optional language code for error message
+   * @param statusCode HTTP status code (defaults to 422)
+   */
+  constructor(language?: string, statusCode = 422) {
+    super(
+      SuiteCoreStringKey.Validation_PasswordRegexErrorTemplate,
+      undefined,
+      language,
+      {
+        statusCode,
+      },
+    );
+    this.name = 'InvalidNewPasswordError';
+  }
+}

package/src/errors/invalid-password.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Error for invalid passwords during authentication.
+ * Thrown when password verification fails, sets HTTP status code to 403.
+ * @module errors/invalid-password
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteHandleableError,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Error thrown when a password is incorrect during authentication.
+ * Sets HTTP status code to 403 (Forbidden).
+ */
+export class InvalidPasswordError extends TranslatableSuiteHandleableError {
+  /**
+   * Creates a new invalid password error.
+   * @param language Optional language code for error message
+   * @param statusCode HTTP status code (defaults to 403)
+   */
+  constructor(language?: string, statusCode = 403) {
+    super(SuiteCoreStringKey.Validation_InvalidPassword, undefined, language, {
+      statusCode,
+    });
+    this.name = 'InvalidPasswordError';
+  }
+}

package/src/errors/missing-validated-data.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Error for missing validated data in request processing.
+ * Thrown when expected validated data is not present after validation middleware.
+ * @module errors/missing-validated-data
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteHandleableError,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Error thrown when validated data is missing from the request.
+ * Sets HTTP status code to 422 (Unprocessable Entity).
+ * @template _TLanguage Language string literal type
+ * @template _TContext Context string literal type
+ */
+export class MissingValidatedDataError<
+  _TLanguage extends string,
+  _TContext extends string,
+> extends TranslatableSuiteHandleableError {
+  /** The missing field name (if single field) */
+  public readonly field?: string;
+  /** The missing field names (if multiple fields) */
+  public readonly fields?: string[];
+
+  /**
+   * Creates a new missing validated data error.
+   * @param data Field name(s) that are missing
+   */
+  constructor(data?: string | string[]) {
+    let message: SuiteCoreStringKey;
+    let fields: string[] | undefined;
+    let field: string;
+    if (data && Array.isArray(data)) {
+      message =
+        SuiteCoreStringKey.Validation_MissingValidatedDataForFieldTemplate;
+      field = data.join(', ');
+      fields = data;
+    } else if (data) {
+      message =
+        SuiteCoreStringKey.Validation_MissingValidatedDataForFieldTemplate;
+      field = String(data);
+    } else {
+      message = SuiteCoreStringKey.Validation_MissingValidatedData;
+      field = '';
+    }
+    super(message, { field }, undefined, {
+      statusCode: 422,
+    });
+    this.field = field;
+    this.fields = fields;
+    this.name = 'MissingValidatedDataError';
+  }
+}

package/src/errors/mnemonic-or-password-required.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Error for missing mnemonic or password during authentication.
+ * Thrown when neither mnemonic nor password is provided for login.
+ * @module errors/mnemonic-or-password-required
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteHandleableError,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Error thrown when neither mnemonic nor password is provided for authentication.
+ * Sets HTTP status code to 422 (Unprocessable Entity).
+ */
+export class MnemonicOrPasswordRequiredError extends TranslatableSuiteHandleableError {
+  /**
+   * Creates a new mnemonic or password required error.
+   */
+  constructor() {
+    super(SuiteCoreStringKey.Validation_MnemonicOrPasswordRequired, {
+      statusCode: 422,
+    });
+    this.name = 'MnemonicOrPasswordRequiredError';
+  }
+}

package/src/errors/model-not-registered.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Error for models not registered in the model registry.
+ * Thrown when attempting to access a model that hasn't been registered.
+ * @module errors/model-not-registered
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Error thrown when attempting to access a model that is not registered.
+ */
+export class ModelNotRegisteredError extends TranslatableSuiteError {
+  /**
+   * Creates a new model not registered error.
+   * @param modelName The name of the unregistered model
+   */
+  constructor(public readonly modelName: string) {
+    super(SuiteCoreStringKey.Error_ModelNotRegisteredTemplate, { modelName });
+    this.name = 'ModelNotRegisteredError';
+  }
+}

package/src/errors/mongoose-validation.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Mongoose validation error wrapper with translatable messages.
+ * Wraps Mongoose validation errors with HTTP status code 422.
+ * @module errors/mongoose-validation
+ */
+
+import { CoreLanguageCode, HandleableError } from '@digitaldefiance/i18n-lib';
+import { Error } from '@digitaldefiance/mongoose-types';
+import {
+  getSuiteCoreI18nEngine,
+  SuiteCoreComponentId,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { IApplication } from '../interfaces';
+
+/**
+ * Error thrown when Mongoose validation fails.
+ * Contains the validation errors and sets HTTP status code to 422 (Unprocessable Entity).
+ */
+export class MongooseValidationError extends HandleableError {
+  /** Mongoose validation errors by field path */
+  public readonly errors: {
+    [path: string]: Error.CastError | Error.ValidatorError;
+  };
+
+  /**
+   * Creates a new Mongoose validation error.
+   * @param validationErrors Mongoose validation errors by field path
+   * @param language Optional language code for error message
+   * @param application Optional application instance for i18n
+   */
+  constructor(
+    validationErrors: {
+      [path: string]: Error.CastError | Error.ValidatorError;
+    },
+    language?: CoreLanguageCode,
+    application?: IApplication,
+  ) {
+    const coreEngine = getSuiteCoreI18nEngine(
+      application ? { constants: application.constants } : undefined,
+    );
+    super(
+      new Error(
+        `${coreEngine.translate(
+          SuiteCoreComponentId,
+          SuiteCoreStringKey.Validation_MongooseValidationError,
+          undefined,
+          language,
+        )}: ${JSON.stringify(validationErrors)}`,
+      ),
+      { statusCode: 422 },
+    );
+    this.name = 'MongooseValidationError';
+    this.errors = validationErrors;
+  }
+}

package/src/errors/symmetric.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Symmetric encryption error with typed error codes.
+ * Provides specific error types for symmetric encryption failures.
+ * @module errors/symmetric
+ */
+
+import { CoreLanguageCode, PluginTypedError } from '@digitaldefiance/i18n-lib';
+import {
+  SuiteCoreComponentId,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { LocalhostConstants } from '../constants';
+import { SymmetricErrorType } from '../enumerations/symmetric-error-type';
+import { IConstants } from '../interfaces/constants';
+import { SymmetricService } from '../services/symmetric';
+
+/**
+ * Error thrown when symmetric encryption operations fail.
+ * Provides typed error codes for different failure scenarios.
+ */
+export class SymmetricError extends PluginTypedError<
+  typeof SymmetricErrorType,
+  SuiteCoreStringKey
+> {
+  /**
+   * Creates a new symmetric encryption error.
+   * @param type Type of symmetric error
+   * @param language Optional language code for error message
+   * @param constants Constants for key size information (defaults to LocalhostConstants)
+   */
+  constructor(
+    type: SymmetricErrorType,
+    language?: CoreLanguageCode,
+    constants: IConstants = LocalhostConstants,
+  ) {
+    super(
+      SuiteCoreComponentId,
+      type,
+      {
+        [SymmetricErrorType.DataNullOrUndefined]:
+          SuiteCoreStringKey.Error_SymmetricDataNullOrUndefined,
+        [SymmetricErrorType.InvalidKeyLength]:
+          SuiteCoreStringKey.Error_SymmetricInvalidKeyLengthTemplate,
+      },
+      language,
+      {
+        KEY_BITS: SymmetricService.symmetricKeyBits(constants.ECIES),
+        KEY_BYTES: SymmetricService.symmetricKeyBytes(constants.ECIES),
+      },
+    );
+    this.name = 'SymmetricError';
+  }
+}

package/src/errors/token-expired.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Error for expired tokens.
+ * Thrown when a JWT or other token has expired, sets HTTP status code to 401.
+ * @module errors/token-expired
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Error thrown when a token has expired.
+ * Sets HTTP status code to 401 (Unauthorized).
+ */
+export class TokenExpiredError extends TranslatableSuiteError {
+  /**
+   * Creates a new token expired error.
+   */
+  constructor() {
+    super(SuiteCoreStringKey.Validation_TokenExpired, { statusCode: 401 });
+    this.name = 'TokenExpiredError';
+  }
+}

package/src/get-language.ts

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Language detection and configuration utilities.
+ * Sets global admin language from environment or command-line arguments.
+ * @module get-language
+ */
+
+import {
+  GlobalActiveContext,
+  IActiveContext,
+  LanguageRegistry,
+} from '@digitaldefiance/i18n-lib';
+import {
+  getSuiteCoreTranslation,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { debugLog } from './utils';
+
+/**
+ * Sets global admin language from process arguments or environment variables.
+ * Prioritizes command-line --language argument, then LANGUAGE env var, then existing context.
+ * @returns {string} The configured language code
+ */
+export function setGlobalActiveContextAdminLanguageFromProcessArgvOrEnv(): string {
+  const consoleLanguageEnv = process.env['LANGUAGE'];
+  const consoleLanguageArgv = process.argv.find((arg) =>
+    arg.startsWith('--language='),
+  );
+
+  const context = GlobalActiveContext.getInstance<
+    string,
+    IActiveContext<string>
+  >();
+
+  // Prioritize command-line argument, then environment variable, then existing context
+  const rawLanguage =
+    (consoleLanguageArgv
+      ? consoleLanguageArgv.split('=')[1]
+      : consoleLanguageEnv) ?? context.adminLanguage;
+
+  if (!rawLanguage) {
+    return context.adminLanguage;
+  }
+
+  const consoleLanguage = rawLanguage.replace(/^['"]|['"]$/g, '');
+
+  if (LanguageRegistry.hasLanguage(consoleLanguage)) {
+    context.setAdminLanguage(consoleLanguage as string);
+    return context.adminLanguage;
+  }
+
+  // If the language is invalid, log a warning and return the unchanged (default) language
+  debugLog(
+    true,
+    'error',
+    getSuiteCoreTranslation(
+      SuiteCoreStringKey.Error_InvalidLanguageCodeTemplate,
+      {
+        LANGUAGE: consoleLanguage,
+        DEFAULT_LANGUAGE: context.adminLanguage,
+      },
+    ),
+  );
+  return context.adminLanguage;
+}

package/src/get-timezone.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Timezone detection and configuration utilities.
+ * Sets global admin timezone from environment or command-line arguments.
+ * @module get-timezone
+ */
+
+import type { Timezone as TimezoneType } from '@digitaldefiance/i18n-lib';
+import {
+  GlobalActiveContext,
+  IActiveContext,
+  isValidTimezone,
+} from '@digitaldefiance/i18n-lib';
+import { existsSync, readFileSync } from 'fs';
+
+// Type for Timezone constructor
+type TimezoneConstructor = new (tz: string) => TimezoneType;
+
+/**
+ * Creates a Timezone instance from the same module as GlobalActiveContext.
+ * @param {string} tz - Timezone string
+ * @returns {TimezoneType} Timezone instance
+ */
+function createTimezone(tz: string): TimezoneType {
+  const context = GlobalActiveContext.getInstance<
+    string,
+    IActiveContext<string>
+  >();
+  // Get the Timezone constructor from the existing timezone object
+  const TimezoneConstructor = context.adminTimezone
+    .constructor as TimezoneConstructor;
+  return new TimezoneConstructor(tz);
+}
+
+/**
+ * Sets global admin timezone from process arguments, environment, or system configuration.
+ * Prioritizes: --timezone argument > TZ env var > /etc/timezone > existing context.
+ * @returns {string} The configured timezone string
+ */
+export function setGlobalActiveContextAdminTimezoneFromProcessArgvOrEnv(): string {
+  const systemTz = existsSync('/etc/timezone')
+    ? readFileSync('/etc/timezone', 'utf8').trim()
+    : undefined;
+  const consoleTimezoneEnv = process.env['TZ'];
+  const consoleTimezoneArgv = process.argv.find((arg) =>
+    arg.startsWith('--timezone='),
+  );
+
+  // Prioritize command-line argument, then environment variable, then /etc/timezone
+  // if command-line argument is set, and is valid (isValidTimezone), use that
+  // if TZ env is set, and is valid (isValidTimezone), use that
+  // if /etc/timezone has a timezone, and is valid (isValidTimezone) use that
+  const validSystemTz =
+    systemTz && isValidTimezone(systemTz) ? systemTz : undefined;
+  const validConsoleTimezoneEnv =
+    consoleTimezoneEnv && isValidTimezone(consoleTimezoneEnv)
+      ? consoleTimezoneEnv
+      : undefined;
+  const argValue = consoleTimezoneArgv?.split('=')[1];
+  const validConsoleTimezoneArgv =
+    argValue && isValidTimezone(argValue) ? argValue : undefined;
+
+  const context = GlobalActiveContext.getInstance<
+    string,
+    IActiveContext<string>
+  >();
+
+  const timezoneStr =
+    validConsoleTimezoneArgv ??
+    validConsoleTimezoneEnv ??
+    validSystemTz ??
+    context.adminTimezone.value;
+
+  const finalTimezone = timezoneStr ?? 'UTC';
+  context.adminTimezone = createTimezone(finalTimezone);
+  return finalTimezone;
+}

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

@@ -1,4 +1,5 @@
 import 'reflect-metadata';
+
 export * from './application';
 export * from './application-base';
 export * from './application-concrete';
@@ -32,7 +33,48 @@ export * from './schemas';
 export * from './services';
 export * from './transactions';
 export * from './types';
-export { type DEBUG_TYPE, debugLog, directLog, getValueAtPath, mapZodIssuesToValidationErrors, requireValidatedFieldsAsync, requireOneOfValidatedFieldsAsync, requireValidatedFieldsOrThrow, isValidStringObjectId as isValidStringId, DEFAULT_RETRY_ATTEMPTS, DEFAULT_TRANSACTION_TIMEOUT, DEFAULT_TRANSACTION_LOCK_REQUEST_TIMEOUT, type TransactionOptions, getDefaultBaseDelay, withTransaction, sendApiMessageResponse, sendApiErrorResponse, sendApiExpressValidationErrorResponse, sendApiMongoValidationErrorResponse, sendRawJsonResponse, handleError, locatePEMRoot, lengthEncodeData, decodeLengthEncodedData, isValidTimezone, omit, validateEnumCollection, uint8ArrayToBase64, base64ToUint8Array, uint8ArrayToHex, hexToUint8Array, crc16, stringToUint8Array, uint8ArrayToString, randomBytes, arraysEqual, concatUint8Arrays, getLengthEncodingTypeForLength, getLengthEncodingTypeFromValue, getLengthForLengthType, parseBackupCodes, } from './utils';
+export {
+  type DEBUG_TYPE,
+  debugLog,
+  directLog,
+  getValueAtPath,
+  mapZodIssuesToValidationErrors,
+  requireValidatedFieldsAsync,
+  requireOneOfValidatedFieldsAsync,
+  requireValidatedFieldsOrThrow,
+  isValidStringObjectId as isValidStringId,
+  DEFAULT_RETRY_ATTEMPTS,
+  DEFAULT_TRANSACTION_TIMEOUT,
+  DEFAULT_TRANSACTION_LOCK_REQUEST_TIMEOUT,
+  type TransactionOptions,
+  getDefaultBaseDelay,
+  withTransaction,
+  sendApiMessageResponse,
+  sendApiErrorResponse,
+  sendApiExpressValidationErrorResponse,
+  sendApiMongoValidationErrorResponse,
+  sendRawJsonResponse,
+  handleError,
+  locatePEMRoot,
+  lengthEncodeData,
+  decodeLengthEncodedData,
+  isValidTimezone,
+  omit,
+  validateEnumCollection,
+  uint8ArrayToBase64,
+  base64ToUint8Array,
+  uint8ArrayToHex,
+  hexToUint8Array,
+  crc16,
+  stringToUint8Array,
+  uint8ArrayToString,
+  randomBytes,
+  arraysEqual,
+  concatUint8Arrays,
+  getLengthEncodingTypeForLength,
+  getLengthEncodingTypeFromValue,
+  getLengthForLengthType,
+  parseBackupCodes,
+} from './utils';
 export type { TransactionOptions as UtilsTransactionOptions } from './utils';
 export * from './validation';
-//# sourceMappingURL=index.d.ts.map

package/src/interfaces/api-error-response.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Generic API error response interface.
+ * Extends API message response with error details.
+ * @module interfaces/api-error-response
+ */
+
+import { IApiMessageResponse } from './api-message-response';
+
+/**
+ * Generic API error response.
+ * @extends IApiMessageResponse
+ */
+export interface IApiErrorResponse extends IApiMessageResponse {
+  error: unknown;
+}

package/src/interfaces/api-express-validation-error-response.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Express validation error response interface.
+ * Extends API message response with express-validator errors.
+ * @module interfaces/api-express-validation-error-response
+ */
+
+import { Result, ValidationError } from 'express-validator';
+import { IApiMessageResponse } from './api-message-response';
+
+/**
+ * API response for express-validator validation errors.
+ * @extends IApiMessageResponse
+ */
+export interface IApiExpressValidationErrorResponse extends IApiMessageResponse {
+  errors: ValidationError[] | Result<ValidationError>;
+  errorType?: string;
+}

package/src/interfaces/api-message-response.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Base API message response interface.
+ * Defines minimal structure for all API responses.
+ * @module interfaces/api-message-response
+ */
+
+/**
+ * Base API response with message.
+ */
+export interface IApiMessageResponse {
+  message: string;
+}