@digitaldefiance/node-express-suite 3.7.3 → 3.7.5

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

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview MongoDB validation error response interface.
+ * Extends API message response with MongoDB-specific validation errors.
+ * @module interfaces/api-mongo-validation-error-response
+ */
+
+import { IApiMessageResponse } from './api-message-response';
+import { IMongoErrors } from './mongo-errors';
+
+/**
+ * API response for MongoDB validation errors.
+ * @extends IApiMessageResponse
+ * @property {IMongoErrors} errors - MongoDB validation error details
+ */
+export interface IApiMongoValidationErrorResponse extends IApiMessageResponse {
+  errors: IMongoErrors;
+}

package/src/interfaces/api-responses/backup-codes-response.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Backup codes API response interface.
+ * Defines structure for backup code generation responses.
+ * @module interfaces/api-responses/backup-codes-response
+ */
+
+import { IApiMessageResponse } from '../api-message-response';
+
+/**
+ * API response containing backup codes.
+ * @extends IApiMessageResponse
+ */
+export interface IApiBackupCodesResponse extends IApiMessageResponse {
+  backupCodes: Array<string>;
+}

package/src/interfaces/api-responses/challenge-response.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview API response interface for cryptographic challenge requests.
+ * @module interfaces/api-responses/challenge-response
+ */
+
+import { IApiMessageResponse } from '../api-message-response';
+
+/**
+ * API response for cryptographic challenge requests.
+ * Contains a challenge string and server's public key for secure authentication.
+ */
+export interface IApiChallengeResponse extends IApiMessageResponse {
+  /** Challenge string to be signed by the client */
+  challenge: string;
+  /** Server's public key for encrypting the response */
+  serverPublicKey: string;
+}

package/src/interfaces/api-responses/code-count-response.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Code count API response interface.
+ * Defines structure for backup code count responses.
+ * @module interfaces/api-responses/code-count-response
+ */
+
+import { IApiMessageResponse } from '../api-message-response';
+
+/** API response containing backup code count. */
+export interface IApiCodeCountResponse extends IApiMessageResponse {
+  codeCount: number;
+}

package/src/interfaces/api-responses/{index.d.ts → index.ts}

@@ -6,4 +6,3 @@ export * from './mnemonic-response';
 export * from './registration-response';
 export * from './request-user-response';
 export * from './user-settings-response';
-//# sourceMappingURL=index.d.ts.map

package/src/interfaces/api-responses/login-response.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Login API response interface.
+ * Defines structure for successful login responses.
+ * @module interfaces/api-responses/login-response
+ */
+
+import { IRequestUserDTO } from '@digitaldefiance/suite-core-lib';
+import { IApiMessageResponse } from '../api-message-response';
+
+/**
+ * API response for successful login.
+ * @extends IApiMessageResponse
+ */
+export interface IApiLoginResponse extends IApiMessageResponse {
+  user: IRequestUserDTO;
+  token: string;
+  serverPublicKey: string;
+}

package/src/interfaces/api-responses/mnemonic-response.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview API response interface for mnemonic phrase requests.
+ * @module interfaces/api-responses/mnemonic-response
+ */
+
+import { IApiMessageResponse } from '../api-message-response';
+
+/**
+ * API response for mnemonic phrase requests.
+ * Contains a BIP39 mnemonic phrase for key derivation.
+ */
+export interface IApiMnemonicResponse extends IApiMessageResponse {
+  /** BIP39 mnemonic phrase (12-24 words) */
+  mnemonic: string;
+}

package/src/interfaces/api-responses/registration-response.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview API response interface for user registration requests.
+ * @module interfaces/api-responses/registration-response
+ */
+
+import { IApiMessageResponse } from '../api-message-response';
+
+/**
+ * API response for user registration requests.
+ * Contains mnemonic phrase and backup codes for account recovery.
+ */
+export interface IApiRegistrationResponse extends IApiMessageResponse {
+  /** BIP39 mnemonic phrase for key derivation */
+  mnemonic: string;
+  /** Array of backup codes for account recovery */
+  backupCodes: Array<string>;
+}

package/src/interfaces/api-responses/request-user-response.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Request user API response interface.
+ * Defines structure for user data responses.
+ * @module interfaces/api-responses/request-user-response
+ */
+
+import { IRequestUserDTO } from '@digitaldefiance/suite-core-lib';
+import { IApiMessageResponse } from '../api-message-response';
+
+/**
+ * API response containing user data.
+ * @extends IApiMessageResponse
+ */
+export interface IApiRequestUserResponse extends IApiMessageResponse {
+  user: IRequestUserDTO;
+}

package/src/interfaces/api-responses/user-settings-response.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview User settings API response interface.
+ * Defines structure for user settings responses.
+ * @module interfaces/api-responses/user-settings-response
+ */
+
+import { IApiMessageResponse } from '../api-message-response';
+
+/** API response containing user settings. */
+export interface IApiUserSettingsResponse extends IApiMessageResponse {
+  settings: {
+    email: string;
+    timezone: string;
+    currency: string;
+    siteLanguage: string;
+    darkMode: boolean;
+    directChallenge: boolean;
+  };
+}

package/src/interfaces/application.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Application interface defining core application structure and services.
+ * Provides access to environment, constants, database, and service container.
+ * @module interfaces/application
+ */
+
+import mongoose, { Model } from '@digitaldefiance/mongoose-types';
+import { ServiceContainer } from '../container';
+import { IBaseDocument } from '../documents';
+import { Environment } from '../environment';
+import { IConstants } from './constants';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Core application interface providing access to all application services and configuration.
+ * @template TID Platform-specific ID type (Buffer, ObjectId, etc.)
+ */
+export interface IApplication<TID extends PlatformID = Buffer> {
+  /** Application environment configuration */
+  get environment(): Environment<TID>;
+  /** Application constants and configuration values */
+  get constants(): IConstants;
+  /** Mongoose database connection */
+  get db(): typeof mongoose;
+  /** Whether the application is ready to handle requests */
+  get ready(): boolean;
+  /** Service container for dependency injection */
+  get services(): ServiceContainer;
+  /** Plugin manager for extensibility */
+  get plugins(): import('../plugins').PluginManager<TID>;
+  /** Starts the application and initializes all services */
+  start(): Promise<void>;
+  /**
+   * Gets a Mongoose model by name.
+   * @template U Document type extending IBaseDocument
+   * @param modelName Name of the model to retrieve
+   * @returns Mongoose model instance
+   */
+  getModel<U extends IBaseDocument<any, TID>>(modelName: string): Model<U>;
+}

package/src/interfaces/backend-objects/email-token.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Backend email token object type.
+ * Defines email token type for backend operations.
+ * @module interfaces/backend-objects/email-token
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import {
+  EmailTokenType,
+  IEmailTokenBase,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Backend email token object type.
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export type IEmailTokenBackendObject<TID extends PlatformID = Buffer> =
+  IEmailTokenBase<TID, Date, EmailTokenType>;

package/src/interfaces/backend-objects/{index.d.ts → index.ts}

@@ -2,4 +2,3 @@ export * from './email-token';
 export * from './request-user';
 export * from './role';
 export * from './user';
-//# sourceMappingURL=index.d.ts.map

package/src/interfaces/backend-objects/request-user.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Backend request user object type.
+ * Defines request user type for backend operations.
+ * @module interfaces/backend-objects/request-user
+ */
+
+import { IRequestUser } from '../request-user';
+import { IRoleBackendObject } from './role';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Backend request user object type.
+ * @template TLanguage - String type for language
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export type IRequestUserBackendObject<
+  TLanguage extends string,
+  TID extends PlatformID = Buffer,
+> = IRequestUser<TID, Array<IRoleBackendObject<any>>, TLanguage, Date>;

package/src/interfaces/backend-objects/role.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Backend role object type.
+ * Defines role type for backend operations with platform-specific IDs.
+ * @module interfaces/backend-objects/role
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { IRoleBase, Role } from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Backend role object type.
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export type IRoleBackendObject<TID extends PlatformID = Buffer> = IRoleBase<
+  TID,
+  Date,
+  Role
+>;

package/src/interfaces/backend-objects/user.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Backend user object type.
+ * Defines user type for backend operations with platform-specific IDs.
+ * @module interfaces/backend-objects/user
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { AccountStatus, IUserBase } from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Backend user object type.
+ * @template TLanguage - String type for language
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export type IUserBackendObject<
+  TLanguage extends string,
+  TID extends PlatformID = Buffer,
+> = IUserBase<TID, Date, TLanguage, AccountStatus>;

package/src/interfaces/checksum-config.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Checksum configuration interface.
+ * Defines algorithm and encoding options for checksum generation.
+ * @module interfaces/checksum-config
+ */
+
+/**
+ * Configuration for checksum generation.
+ * @property {string} algorithm - Hash algorithm (e.g., 'sha256', 'sha512')
+ * @property {'hex' | 'base64'} encoding - Output encoding format
+ */
+export interface IChecksumConfig {
+  algorithm: string;
+  encoding: 'hex' | 'base64';
+}

package/src/interfaces/checksum-consts.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Checksum constants interface.
+ * Defines configuration constants for SHA3 checksum operations.
+ * @module interfaces/checksum-consts
+ */
+
+/**
+ * Constants for checksum generation and validation.
+ * Defines SHA3 algorithm parameters and encoding settings.
+ */
+export interface IChecksumConsts {
+  /** Default hash bits for SHA3 */
+  SHA3_DEFAULT_HASH_BITS: number;
+
+  /** Length of a SHA3 checksum buffer in bytes */
+  SHA3_BUFFER_LENGTH: number;
+
+  /** Algorithm name for checksums */
+  ALGORITHM: string;
+
+  /** Encoding for checksums */
+  ENCODING: 'hex' | 'base64';
+}

package/src/interfaces/constants.ts

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Constants interface combining all library constants.
+ * Aggregates constants from ECIES, Node ECIES, Suite Core, and Node Express Suite.
+ * @module interfaces/constants
+ */
+
+import { IECIESConstants, IPBkdf2Consts } from '@digitaldefiance/ecies-lib';
+import {
+  IEncryptionConsts,
+  IKeyringConsts,
+  IWrappedKeyConsts,
+  PbkdfProfiles,
+  type IVotingConsts,
+} from '@digitaldefiance/node-ecies-lib';
+import { IConstants as IBaseConstants } from '@digitaldefiance/suite-core-lib';
+import { CipherGCMTypes } from 'crypto';
+import { IChecksumConsts } from './checksum-consts';
+import { IFECConsts } from './fec-consts';
+import { IJwtConsts } from './jwt-consts';
+
+/**
+ * Combination of all constants from all libraries.
+ * Extends base constants with ECIES, Node ECIES, Suite Core, and Node Express Suite constants.
+ */
+export interface IConstants extends IBaseConstants {
+  UINT8_SIZE: number;
+  UINT16_SIZE: number;
+  UINT16_MAX: number;
+  UINT32_SIZE: number;
+  UINT32_MAX: number;
+  UINT64_SIZE: number;
+  UINT64_MAX: bigint;
+  HEX_RADIX: number;
+  /**
+   * Number of rounds for bcrypt hashing. Higher values increase security but also consume more CPU resources.
+   */
+  BcryptRounds: number;
+  /**
+   * Minimum password length
+   */
+  PasswordMinLength: number;
+  /**
+   * The regular expression for valid passwords.
+   */
+  PasswordRegex: RegExp;
+  /**
+   * The regular expression for valid JWT tokens.
+   */
+  JwtSecretRegex: RegExp;
+  /**
+   * The regular expression for valid mnemonic phrases.
+   * BIP39
+   */
+  MnemonicRegex: RegExp;
+  /**
+   * The regular expression for valid HMAC keys.
+   */
+  MnemonicHmacRegex: RegExp;
+  /**
+   * The regular expression for valid encryption keys.
+   */
+  MnemonicEncryptionKeyRegex: RegExp;
+  /**
+   * JWT constants
+   */
+  JWT: IJwtConsts;
+  /**
+   * Forward Error Correction constants
+   */
+  FEC: IFECConsts;
+  /**
+   * ECIES encryption constants
+   */
+  ECIES: IECIESConstants;
+  /**
+   * The length of a raw object ID (not the hex string representation)
+   */
+  OBJECT_ID_LENGTH: number;
+  /**
+   * PBKDF2 key derivation function constants
+   */
+  PBKDF2: IPBkdf2Consts;
+  /**
+   * Predefined PBKDF2 configuration profiles for different use cases
+   */
+  PBKDF2_PROFILES: PbkdfProfiles;
+  /**
+   * Checksum constants used for data integrity
+   */
+  CHECKSUM: IChecksumConsts;
+  /**
+   * Wrapped Key constants used for the key wrapping service
+   */
+  WRAPPED_KEY: IWrappedKeyConsts;
+  /**
+   * Keyring constants used for key management
+   */
+  KEYRING: IKeyringConsts;
+  /**
+   * Encryption constants used for encrypted data
+   */
+  ENCRYPTION: IEncryptionConsts;
+  /**
+   * Voting constants used for homomorphic encryption voting
+   */
+  VOTING: IVotingConsts;
+  /**
+   * Algorithm configuration string for keyring operations
+   */
+  KEYRING_ALGORITHM_CONFIGURATION: CipherGCMTypes;
+  ECIES_VERSION_SIZE: number;
+  ECIES_CIPHER_SUITE_SIZE: number;
+  MEMBER_ID_LENGTH: number;
+}

package/src/interfaces/controller-config.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Controller configuration interface.
+ * Defines type configuration for controllers with platform-specific types.
+ * @module interfaces/controller-config
+ */
+
+import {
+  ITokenRole,
+  ITokenUser,
+  IUserBase,
+} from '@digitaldefiance/suite-core-lib';
+import { IBaseDocument } from '../documents';
+import { Environment } from '../environment';
+import { IApplication } from './application';
+import { IConstants } from './constants';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Configuration interface for controller type parameters.
+ * Defines all type parameters used across controllers.
+ * @template TID - Platform ID type (defaults to Buffer)
+ * @template TDate - Date type (defaults to Date)
+ * @template TLanguage - String type (defaults to string)
+ * @template TAccountStatus - Account status type (defaults to string)
+ */
+export interface IControllerConfig<
+  TID extends PlatformID = Buffer,
+  TDate extends Date = Date,
+  TLanguage extends string = string,
+  TAccountStatus extends string = string,
+> {
+  idType: TID;
+  dateType: TDate;
+  stringType: TLanguage;
+  accountStatusType: TAccountStatus;
+  userType: IUserBase<TID, TDate, TLanguage, TAccountStatus>;
+  tokenRoleType: ITokenRole<TID, TDate>;
+  tokenUserType: ITokenUser;
+  baseDocumentType: IBaseDocument<any, TID>;
+  environmentType: Environment<TID>;
+  constantsType: IConstants;
+  applicationType: IApplication<TID>;
+}
+
+/**
+ * Default controller configuration with standard types.
+ * Uses Buffer for IDs, Date for dates, and string for language/status.
+ */
+export type DefaultControllerConfig = IControllerConfig<
+  Buffer,
+  Date,
+  string,
+  string
+>;

package/src/interfaces/create-user-basics.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview User creation basics interface.
+ * Defines minimal required fields for creating a new user.
+ * @module interfaces/create-user-basics
+ */
+
+/**
+ * Partial interface for creating a new user.
+ * Contains essential user information required during registration.
+ */
+export interface ICreateUserBasics {
+  /**
+   * The username of the user
+   */
+  username: string;
+  /**
+   * The email address of the user
+   */
+  email: string;
+  /**
+   * The timezone of the user
+   */
+  timezone?: string;
+}

package/src/interfaces/csp-config.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview CSP configuration interface with CORS whitelist.
+ * Defines Content Security Policy and CORS settings.
+ * @module interfaces/csp-config
+ */
+
+import { ISimpleCSPDef, isSimpleCSPDef } from './csp-definition';
+
+/**
+ * Content Security Policy configuration with CORS whitelist.
+ * @property {string[]} corsWhitelist - Allowed CORS origins
+ * @property {ISimpleCSPDef} csp - CSP directive definitions
+ */
+export interface ICSPConfig {
+  corsWhitelist: string[];
+  csp: ISimpleCSPDef;
+}
+
+/**
+ * Type guard to check if object is valid CSP configuration.
+ * @param {any} obj - Object to validate
+ * @returns {boolean} True if object matches ICSPConfig interface
+ */
+export const isCSPConfig = (obj: any): obj is ICSPConfig => {
+  return (
+    !!obj &&
+    typeof obj === 'object' &&
+    'corsWhitelist' in obj &&
+    'csp' in obj &&
+    isSimpleCSPDef(obj.csp)
+  );
+};

package/src/interfaces/csp-definition.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Simple CSP directive definition interface.
+ * Defines Content Security Policy directives with static and dynamic sources.
+ * @module interfaces/csp-definition
+ */
+
+import { HelmetOptions } from 'helmet';
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * Simplified Content Security Policy directive definition.
+ * Each directive accepts static strings or dynamic functions for request-specific values.
+ * @property {Array<string | Function>} defaultSrc - Default source directive
+ * @property {Array<string | Function>} imgSrc - Image source directive
+ * @property {Array<string | Function>} connectSrc - Connect source directive (XHR, WebSocket)
+ * @property {Array<string | Function>} scriptSrc - Script source directive
+ * @property {Array<string | Function>} styleSrc - Style source directive
+ * @property {Array<string | Function>} fontSrc - Font source directive
+ * @property {Array<string | Function>} frameSrc - Frame source directive
+ */
+export interface ISimpleCSPDef {
+  defaultSrc: (
+    | string
+    | ((req: IncomingMessage, res: ServerResponse) => string)
+  )[];
+  imgSrc: (string | ((req: IncomingMessage, res: ServerResponse) => string))[];
+  connectSrc: (
+    | string
+    | ((req: IncomingMessage, res: ServerResponse) => string)
+  )[];
+  scriptSrc: (
+    | string
+    | ((req: IncomingMessage, res: ServerResponse) => string)
+  )[];
+  styleSrc: (
+    | string
+    | ((req: IncomingMessage, res: ServerResponse) => string)
+  )[];
+  fontSrc: (string | ((req: IncomingMessage, res: ServerResponse) => string))[];
+  frameSrc: (
+    | string
+    | ((req: IncomingMessage, res: ServerResponse) => string)
+  )[];
+}
+
+/**
+ * Type guard to check if object is simple CSP definition.
+ * @param {ISimpleCSPDef | HelmetOptions} obj - Object to validate
+ * @returns {boolean} True if object matches ISimpleCSPDef interface
+ */
+export const isSimpleCSPDef = (
+  obj: ISimpleCSPDef | HelmetOptions,
+): obj is ISimpleCSPDef => {
+  return (
+    obj &&
+    'defaultSrc' in obj &&
+    'imgSrc' in obj &&
+    'connectSrc' in obj &&
+    'scriptSrc' in obj &&
+    'styleSrc' in obj &&
+    'fontSrc' in obj &&
+    'frameSrc' in obj &&
+    Array.isArray(obj.defaultSrc) &&
+    Array.isArray(obj.imgSrc) &&
+    Array.isArray(obj.connectSrc) &&
+    Array.isArray(obj.scriptSrc) &&
+    Array.isArray(obj.styleSrc) &&
+    Array.isArray(obj.fontSrc) &&
+    Array.isArray(obj.frameSrc)
+  );
+};

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

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Database initialization result interface.
+ * Extends failable result with initialization status flag.
+ * @module interfaces/db-init-result
+ */
+
+import { IFailableResult } from './failable-result';
+
+/**
+ * Result of database initialization operation.
+ * @template T - Result data type
+ * @extends IFailableResult<T>
+ * @property {boolean} alreadyInitialized - True if database was already initialized
+ */
+export interface IDBInitResult<T> extends IFailableResult<T> {
+  alreadyInitialized: boolean;
+}

package/src/interfaces/deep-partial.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Deep partial utility type.
+ * Recursively makes all properties of a type optional.
+ * @module interfaces/deep-partial
+ */
+
+/**
+ * Recursively makes all properties of a type optional.
+ * @template T - Type to make deeply partial
+ * @typedef {Object} DeepPartial
+ */
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};