@digitaldefiance/node-express-suite 3.7.4 → 3.7.5

package/src/interfaces/discriminator-collections.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Discriminator collections interface.
+ * Defines structure for Mongoose discriminator model collections.
+ * @module interfaces/discriminator-collections
+ */
+
+import { Model } from '@digitaldefiance/mongoose-types';
+import { IBaseDocument } from '../documents/base';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Collections of discriminator models.
+ * @template T - Document type extending IBaseDocument
+ */
+export interface IDiscriminatorCollections<
+  TID extends PlatformID,
+  T extends IBaseDocument<any, TID>,
+> {
+  byType: Record<string, Model<T>>;
+  array: Array<Model<T>>;
+}

package/src/interfaces/email-service.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Email service interface for sending emails.
+ * Defines contract for email delivery implementations.
+ * @module interfaces/email-service
+ */
+
+/**
+ * Email service interface for sending emails.
+ * Implementations handle email delivery with text and HTML content.
+ */
+export interface IEmailService {
+  /**
+   * Sends an email with text and HTML content.
+   * @param {string} to - Recipient email address
+   * @param {string} subject - Email subject line
+   * @param {string} text - Plain text email body
+   * @param {string} html - HTML email body
+   * @returns {Promise<void>} Resolves when email is sent
+   */
+  sendEmail(
+    to: string,
+    subject: string,
+    text: string,
+    html: string,
+  ): Promise<void>;
+}

package/src/interfaces/environment-mongo.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview MongoDB environment configuration interface.
+ * Defines comprehensive MongoDB connection and behavior settings.
+ * @module interfaces/environment-mongo
+ */
+
+import { ReadConcernLike, WriteConcern } from 'mongodb';
+
+/**
+ * MongoDB environment configuration.
+ * Defines connection pool, timeout, transaction, and consistency settings.
+ */
+export interface IMongoEnvironment {
+  /**
+   * The URI of the MongoDB database
+   */
+  uri: string;
+  /**
+   * The name of the MongoDB database
+   */
+  dbName: string;
+  /**
+   * The maximum number of connections in the connection pool (default: 10)
+   */
+  maxPoolSize: number;
+  /**
+   * The minimum number of connections in the connection pool (default: 2)
+   */
+  minPoolSize: number;
+  /**
+   * The maximum number of milliseconds that a connection can remain idle in the connection pool (default: 30000)
+   */
+  maxIdleTimeMS: number;
+  /**
+   * The maximum time in milliseconds to wait for a connection to be established (default: 5000)
+   */
+  serverSelectionTimeoutMS: number;
+  /**
+   * The maximum time in milliseconds to wait for a socket to be established (default: 30000)
+   */
+  socketTimeoutMS: number;
+  /**
+   * Whether to retry writes (default: true)
+   */
+  retryWrites: boolean;
+  /**
+   * Whether to retry reads (default: true)
+   */
+  retryReads: boolean;
+  /**
+   * The read concern for the MongoDB database
+   */
+  readConcern: ReadConcernLike;
+  /**
+   * The write concern for the MongoDB database (default: { w: 'majority', j: true })
+   */
+  writeConcern: WriteConcern;
+  /**
+   * Whether the MongoDB server supports the setParameter command (MongoDB 4.4+)
+   */
+  setParameterSupported: boolean;
+  /**
+   * Whether the MongoDB server supports setting transactionLifetimeLimitSeconds (MongoDB 4.2+)
+   */
+  transactionLifetimeLimitSecondsSupported: boolean;
+  /**
+   * Whether the MongoDB server supports setting maxTransactionLockRequestTimeoutMillis (MongoDB 4.4+)
+   */
+  maxTransactionLockRequestTimeoutMillisSupported: boolean;
+  /**
+   * How long for transactions to timeout
+   */
+  transactionTimeout: number;
+  /**
+   * The maximum time to wait for a lock when using transactions (MongoDB 4.4+)
+   */
+  transactionLockRequestTimeout: number;
+  /**
+   * Use transactions
+   */
+  useTransactions: boolean;
+  /**
+   * Base delay in milliseconds for transaction retry backoff
+   */
+  transactionRetryBaseDelay: number;
+}

package/src/interfaces/environment.ts

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview Environment interface defining application configuration and credentials.
+ * Contains all environment variables, database configuration, and user credentials.
+ * @module interfaces/environment
+ */
+
+import { SecureBuffer, SecureString } from '@digitaldefiance/ecies-lib';
+import { BackupCode } from '../backup-code';
+import { IMongoEnvironment } from './environment-mongo';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Environment configuration interface for the application.
+ * Contains all configuration values, credentials, and environment-specific settings.
+ * @template TID Platform-specific ID type (Buffer, ObjectId, etc.)
+ */
+export interface IEnvironment<TID extends PlatformID = Buffer> {
+  /**
+   * Whether to use a memory database for local development (eg with MongoMemoryServer)
+   * If set, this will create a new in-memory database instance on application start with the given database name
+   */
+  devDatabase?: string;
+  /**
+   * Whether to print certain console debug messages
+   */
+  debug: boolean;
+  /**
+   * Whether to enable super verbose debug messags
+   */
+  detailedDebug: boolean;
+  /**
+   * The host name of the server
+   */
+  host: string;
+  /**
+   * The port the server is running on
+   */
+  port: number;
+  /**
+   * The base path of the server
+   */
+  basePath: string;
+  /**
+   * The URL of the server
+   */
+  serverUrl: string;
+  /**
+   * The secret used to sign JWTs
+   */
+  jwtSecret: string;
+  /**
+   * The email address to send notifications from
+   */
+  emailSender: string;
+  /**
+   * API distribution directory
+   */
+  apiDistDir: string;
+  /**
+   * react dist dir
+   */
+  reactDistDir: string;
+  /**
+   * The directory and root filename to store HTTPS development certificates
+   */
+  httpsDevCertRoot?: string;
+  /**
+   * The port to use for HTTPS development certificates
+   */
+  httpsDevPort: number;
+  /**
+   * Disable email sending
+   */
+  disableEmailSend: boolean;
+  /**
+   * MongoDB configuration
+   */
+  mongo: IMongoEnvironment;
+  /**
+   * Mnemonic for the admin user
+   */
+  adminMnemonic?: SecureString;
+  /**
+   * The ID of the admin user
+   */
+  adminId?: TID;
+  /**
+   * The creation date of the admin user
+   */
+  adminCreatedAt?: Date;
+  /**
+   * The password of the admin user
+   */
+  adminPassword?: SecureString;
+  /**
+   * The ID of the admin user role object
+   */
+  adminRoleId?: TID;
+  /**
+   * The ID of the admin user's user role object
+   */
+  adminUserRoleId?: TID;
+  /**
+   * Backup codes for the admin user
+   */
+  adminBackupCodes?: BackupCode[];
+  /**
+   * Mnemonic for the member user
+   */
+  memberMnemonic?: SecureString;
+  /**
+   * The ID of the member user
+   */
+  memberId?: TID;
+  /**
+   * The creation date of the member user
+   */
+  memberCreatedAt?: Date;
+  /**
+   * The password of the member user
+   */
+  memberPassword?: SecureString;
+  /**
+   * The ID of the member user role object
+   */
+  memberRoleId?: TID;
+  /**
+   * The ID of the member user's user role object
+   */
+  memberUserRoleId?: TID;
+  /**
+   * Backup codes for the member user
+   */
+  memberBackupCodes?: BackupCode[];
+  /**
+   * Mnemonic for the system user
+   */
+  systemMnemonic?: SecureString;
+  /**
+   * The ID of the system user
+   */
+  systemId?: TID;
+  /**
+   * The creation date of the system user
+   */
+  systemCreatedAt?: Date;
+  /**
+   * The public key of the system user
+   */
+  systemPublicKeyHex?: string;
+  /**
+   * The password of the system user
+   */
+  systemPassword?: SecureString;
+  /**
+   * The ID of the system user role object
+   */
+  systemRoleId?: TID;
+  /**
+   * The ID of the system user's user role object
+   */
+  systemUserRoleId?: TID;
+  /**
+   * Backup codes for the system user
+   */
+  systemBackupCodes?: BackupCode[];
+  /**
+   * HMAC secret for mnemonic encryption
+   */
+  mnemonicHmacSecret: SecureBuffer;
+  /**
+   * Encryption key for mnemonics
+   */
+  mnemonicEncryptionKey: SecureBuffer;
+  /**
+   * The timezone for the server
+   */
+  timezone: string;
+  /**
+   * The default language for the admin interface/CLI
+   */
+  adminLanguage: string;
+  /**
+   * The number of PBKDF2 iterations for key wrapping
+   */
+  pbkdf2Iterations: number;
+  /**
+   * Whether this is a production environment
+   */
+  production: boolean;
+}

package/src/interfaces/failable-result.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Failable result interface for operation outcomes.
+ * Generic interface for operations that can succeed or fail.
+ * @module interfaces/failable-result
+ */
+
+/**
+ * Result of an operation that can succeed or fail.
+ * @template T - Result data type
+ * @property {boolean} success - True if operation succeeded
+ * @property {T} [data] - Result data if successful
+ * @property {string} [message] - Success or informational message
+ * @property {string | Error} [error] - Error message or object if failed
+ */
+export interface IFailableResult<T> {
+  success: boolean;
+  data?: T;
+  message?: string;
+  error?: string | Error;
+}

package/src/interfaces/fec-consts.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Forward Error Correction constants interface.
+ * Defines configuration constants for FEC shard operations.
+ * @module interfaces/fec-consts
+ */
+
+/**
+ * Constants for Forward Error Correction operations.
+ * Defines maximum shard size for data splitting.
+ */
+export interface IFECConsts {
+  /** Maximum size of a single shard */
+  MAX_SHARD_SIZE: number;
+}

package/src/interfaces/flexible-csp.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Flexible CSP configuration interface.
+ * Supports both simple CSP definitions and Helmet options.
+ * @module interfaces/flexible-csp
+ */
+
+import { HelmetOptions } from 'helmet';
+import { isHelmetOptions } from '../middleware-utils';
+import { ISimpleCSPDef, isSimpleCSPDef } from './csp-definition';
+
+/**
+ * Flexible Content Security Policy configuration.
+ * Accepts either simplified CSP definition or full Helmet options.
+ * @property {string[]} corsWhitelist - Allowed CORS origins
+ * @property {ISimpleCSPDef | HelmetOptions} csp - CSP configuration
+ */
+export interface IFlexibleCSP {
+  corsWhitelist: string[];
+  csp: ISimpleCSPDef | HelmetOptions;
+}
+
+/**
+ * Type guard to check if object is flexible CSP configuration.
+ * @param {any} obj - Object to validate
+ * @returns {boolean} True if object matches IFlexibleCSP interface
+ */
+export const isFlexibleCSP = (obj: any): obj is IFlexibleCSP => {
+  return (
+    !!obj &&
+    typeof obj === 'object' &&
+    'corsWhitelist' in obj &&
+    'csp' in obj &&
+    (isSimpleCSPDef(obj.csp) || isHelmetOptions(obj.csp))
+  );
+};

package/src/interfaces/handleable-error-options.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Handleable error options interface.
+ * Defines options for errors that can be handled by error middleware.
+ * @module interfaces/handleable-error-options
+ */
+
+/**
+ * Options for handleable errors.
+ * @property {Error} [cause] - Original error that caused this error
+ * @property {boolean} [handled] - Whether error has been handled
+ * @property {number} [statusCode] - HTTP status code for error response
+ * @property {unknown} [sourceData] - Additional data related to the error
+ */
+export interface HandleableErrorOptions {
+  cause?: Error;
+  handled?: boolean;
+  statusCode?: number;
+  sourceData?: unknown;
+}

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

@@ -32,4 +32,3 @@ export * from './server-init-result';
 export * from './status-code-response';
 export * from './symmetric-encryption-results';
 export * from './token-response';
-//# sourceMappingURL=index.d.ts.map

package/src/interfaces/jwt-consts.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview JWT constants interface.
+ * Defines configuration constants for JWT token generation and validation.
+ * @module interfaces/jwt-consts
+ */
+
+/**
+ * Constants for JWT token configuration.
+ * Defines algorithm and expiration settings.
+ */
+export interface IJwtConsts {
+  /**
+   * Algorithm to use for JWT
+   */
+  ALGORITHM:
+    | 'HS256'
+    | 'HS384'
+    | 'HS512'
+    | 'RS256'
+    | 'RS384'
+    | 'RS512'
+    | 'ES256'
+    | 'ES384'
+    | 'ES512'
+    | 'PS256'
+    | 'PS384'
+    | 'PS512';
+
+  /**
+   * The expiration time for a JWT token in seconds
+   */
+  EXPIRATION_SEC: number;
+}

package/src/interfaces/jwt-sign-response.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview JWT sign response interface.
+ * Defines structure for JWT token generation response with user and role data.
+ * @module interfaces/jwt-sign-response
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import {
+  ITokenRole,
+  ITokenRoleDTO,
+  ITokenUser,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Response from JWT token signing operation.
+ * @template TID - Platform ID type (defaults to Buffer)
+ * @template D - Date type (defaults to Date)
+ * @template TTokenRole - Token role type (defaults to ITokenRole<I, D>)
+ */
+export interface IJwtSignResponse<
+  TID extends PlatformID = Buffer,
+  D extends Date = Date,
+  TTokenRole extends ITokenRole<TID, D> = ITokenRole<TID, D>,
+> {
+  token: string;
+  tokenUser: ITokenUser;
+  roleNames: string[];
+  roleTranslatedNames: string[];
+  roles: TTokenRole[];
+  roleDTOs: ITokenRoleDTO[];
+}

package/src/interfaces/models/email-token.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Email token model interface for frontend.
+ * Defines type alias for email token documents with string IDs.
+ * @module interfaces/models/email-token
+ */
+
+import { IEmailTokenBase } from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Front-end interface for email token collection documents.
+ * Uses string IDs for browser compatibility.
+ */
+export type IFrontendEmailToken = IEmailTokenBase<string, Date, string>;

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

@@ -5,4 +5,3 @@ export * from './token-role';
 export * from './used-direct-login-token';
 export * from './user';
 export * from './user-role';
-//# sourceMappingURL=index.d.ts.map

package/src/interfaces/models/mnemonic.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Mnemonic model interface for frontend.
+ * Defines type alias for mnemonic hash storage documents.
+ * @module interfaces/models/mnemonic
+ */
+
+import { IMnemonicBase } from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Front-end interface for mnemonic hash storage.
+ * Represents a mnemonic hash being stored to check for uniqueness.
+ * Uses string IDs for browser compatibility.
+ */
+export type IFrontendMnemonic = IMnemonicBase<string>;

package/src/interfaces/models/role.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Role model interfaces for frontend.
+ * Defines type alias for role documents with string IDs.
+ * @module interfaces/models/role
+ */
+
+import { IRoleBase } from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Front-end interface for role collection documents.
+ * Uses string IDs for browser compatibility.
+ */
+export type IFrontendRole = IRoleBase<string, Date>;

package/src/interfaces/models/token-role.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Token role model interfaces for frontend and backend.
+ * Defines type aliases for token role documents with platform-specific IDs.
+ * @module interfaces/models/token-role
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { ITokenRole } from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Front-end interface for token role collection documents.
+ * Uses string IDs for browser compatibility.
+ */
+export type IFrontendTokenRole = ITokenRole<string, Date>;
+/**
+ * Back-end interface for token role collection documents.
+ * Uses platform-specific IDs (Buffer, ObjectId, etc.).
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export type IBackendTokenRole<TID extends PlatformID = Buffer> = ITokenRole<
+  TID,
+  Date
+>;

package/src/interfaces/models/used-direct-login-token.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Used direct login token model interfaces for frontend and backend.
+ * Defines type aliases for tracking consumed direct login tokens.
+ * @module interfaces/models/used-direct-login-token
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { IUsedDirectLoginTokenBase } from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Front-end interface for used direct login token documents.
+ * Uses string IDs for browser compatibility.
+ */
+export type IFrontendUsedDirectLoginToken = IUsedDirectLoginTokenBase<string>;
+/**
+ * Back-end interface for used direct login token documents.
+ * Uses platform-specific IDs (Buffer, ObjectId, etc.).
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export type IBackendUsedDirectLoginToken<TID extends PlatformID = Buffer> =
+  IUsedDirectLoginTokenBase<TID>;

package/src/interfaces/models/user-role.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview User-role model interfaces for frontend and backend.
+ * Defines type aliases for user-role relationship documents.
+ * @module interfaces/models/user-role
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { IUserRoleBase } from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Front-end interface for user role collection documents.
+ * Uses string IDs for browser compatibility.
+ */
+export type IFrontendUserRole = IUserRoleBase<string, Date>;
+/**
+ * Back-end interface for user role collection documents.
+ * Uses platform-specific IDs (Buffer, ObjectId, etc.).
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export type IBackendUserRole<TID extends PlatformID = Buffer> = IUserRoleBase<
+  TID,
+  Date
+>;

package/src/interfaces/models/user.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview User model interfaces for frontend and backend.
+ * Defines type aliases for user documents with platform-specific IDs.
+ * @module interfaces/models/user
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { AccountStatus, IUserBase } from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Front-end interface for user collection documents.
+ * Uses string IDs for browser compatibility.
+ * @template TLanguage - Language code type
+ */
+export type IFrontendUser<TLanguage extends string> = IUserBase<
+  string,
+  Date,
+  TLanguage,
+  AccountStatus
+>;
+/**
+ * Back-end interface for user collection documents.
+ * Uses platform-specific IDs (Buffer, ObjectId, etc.).
+ * @template TLanguage - Language code type
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export type IBackendUser<
+  TLanguage extends string,
+  TID extends PlatformID = Buffer,
+> = IUserBase<TID, Date, TLanguage, AccountStatus>;

package/src/interfaces/mongo-errors.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview MongoDB validation errors interface.
+ * Defines structure for Mongoose validation error collections.
+ * @module interfaces/mongo-errors
+ */
+
+import { Error } from '@digitaldefiance/mongoose-types';
+
+/**
+ * Collection of MongoDB validation errors.
+ */
+export interface IMongoErrors {
+  [key: string]: Error.ValidatorError | Error.CastError;
+}