@digitaldefiance/node-express-suite 3.7.5 → 3.7.6

package/src/application.ts

@@ -1,330 +0,0 @@
-/**
- * @fileoverview Main application class with Express server.
- * Extends BaseApplication with HTTP/HTTPS server and routing.
- * @module application
- */
-
-import { HandleableError } from '@digitaldefiance/i18n-lib';
-import mongoose from '@digitaldefiance/mongoose-types';
-import {
-  Constants,
-  getSuiteCoreI18nEngine,
-  SuiteCoreComponentId,
-  SuiteCoreStringKey,
-  TranslatableSuiteError,
-} from '@digitaldefiance/suite-core-lib';
-import express, {
-  Application as ExpressApplication,
-  NextFunction,
-  Request,
-  Response,
-} from 'express';
-import { readFileSync } from 'fs';
-import { HelmetOptions } from 'helmet';
-import { Server } from 'http';
-import { createServer } from 'https';
-import { isAbsolute, normalize, resolve } from 'path';
-import { BaseApplication } from './application-base';
-import { IBaseDocument } from './documents/base';
-import { Environment } from './environment';
-import {
-  IApplication,
-  ICSPConfig,
-  IFailableResult,
-  isCSPConfig,
-  IServerInitResult,
-} from './interfaces';
-import { IConstants } from './interfaces/constants';
-import { IFlexibleCSP, isFlexibleCSP } from './interfaces/flexible-csp';
-import { initMiddleware, isHelmetOptions } from './middleware-utils';
-import { AppRouter } from './routers/app';
-import { BaseRouter } from './routers/base';
-import { DatabaseInitializationService } from './services';
-import { SchemaMap } from './types';
-import { debugLog, handleError, sendApiMessageResponse } from './utils';
-import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
-
-/**
- * Application class
- */
-type ServerWithOptionalClose = Server & { closeAllConnections?: () => void };
-
-export class Application<
-  TInitResults extends IServerInitResult<TID>,
-  TModelDocs extends Record<string, IBaseDocument<any, TID>>,
-  TID extends PlatformID = Buffer,
-  TEnvironment extends Environment<TID> = Environment<TID>,
-  TConstants extends IConstants = IConstants,
-  TAppRouter extends AppRouter<TID> = AppRouter<TID>,
->
-  extends BaseApplication<TID, TModelDocs, TInitResults, TConstants>
-  implements IApplication<TID>
-{
-  public readonly expressApp: ExpressApplication;
-  private server: ServerWithOptionalClose | null = null;
-  private readonly _cspConfig: ICSPConfig | HelmetOptions | IFlexibleCSP;
-  private readonly _apiRouterFactory: (
-    app: IApplication<TID>,
-  ) => BaseRouter<TID>;
-  private readonly _appRouterFactory: (
-    apiRouter: BaseRouter<TID>,
-  ) => TAppRouter;
-  private readonly _initMiddleware: typeof initMiddleware;
-  private _apiRouter?: BaseRouter<TID>;
-
-  public override get environment(): TEnvironment {
-    return super.environment as TEnvironment;
-  }
-
-  protected registerServices(): void {
-    // Services will be registered by subclasses or ApiRouter
-    // Base implementation does nothing
-  }
-
-  constructor(
-    environment: TEnvironment,
-    apiRouterFactory: (app: IApplication<TID>) => BaseRouter<TID>,
-    schemaMapFactory: (
-      connection: mongoose.Connection,
-    ) => SchemaMap<TID, TModelDocs>,
-    databaseInitFunction: (
-      application: BaseApplication<TID, TModelDocs, TInitResults>,
-    ) => Promise<IFailableResult<TInitResults>>,
-    initResultHashFunction: (initResults: TInitResults) => string,
-    cspConfig: ICSPConfig | HelmetOptions | IFlexibleCSP = {
-      corsWhitelist: [],
-      csp: {
-        defaultSrc: [],
-        imgSrc: [],
-        connectSrc: [],
-        scriptSrc: [],
-        styleSrc: [],
-        fontSrc: [],
-        frameSrc: [],
-      },
-    },
-    constants: TConstants = Constants as TConstants,
-    appRouterFactory: (apiRouter: BaseRouter<TID>) => TAppRouter = (
-      apiRouter,
-    ) => new AppRouter(apiRouter) as TAppRouter,
-    customInitMiddleware: typeof initMiddleware = initMiddleware,
-  ) {
-    super(
-      environment,
-      schemaMapFactory,
-      databaseInitFunction,
-      initResultHashFunction,
-      constants,
-    );
-    this._apiRouterFactory = apiRouterFactory;
-    this._appRouterFactory = appRouterFactory;
-    this._initMiddleware = customInitMiddleware;
-    this.expressApp = express();
-    this.server = null;
-    this._cspConfig = cspConfig;
-    this.registerServices();
-  }
-
-  public override async start(mongoUri?: string): Promise<void> {
-    const engine = getSuiteCoreI18nEngine({ constants: this.constants });
-    await super.start(mongoUri, true);
-    if (this.devDatabase) {
-      const result = await this.initializeDevDatabase();
-      DatabaseInitializationService.printServerInitResults(result, false);
-    }
-    try {
-      this._apiRouter = this._apiRouterFactory(this);
-      if (isFlexibleCSP(this._cspConfig) || isCSPConfig(this._cspConfig)) {
-        this._initMiddleware(
-          this.expressApp,
-          this._cspConfig.corsWhitelist,
-          this._cspConfig.csp,
-        );
-      } else if (isHelmetOptions(this._cspConfig)) {
-        this._initMiddleware(this.expressApp, [], this._cspConfig);
-      }
-      const appRouter = this._appRouterFactory(this._apiRouter);
-
-      appRouter.init(this.expressApp);
-      this.expressApp.use(
-        (
-          err: HandleableError | Error,
-          req: Request,
-          res: Response,
-          _next: NextFunction,
-        ) => {
-          if (
-            res.headersSent ||
-            (err as { _errorHandlerProcessing?: boolean })
-              ._errorHandlerProcessing
-          ) {
-            return;
-          }
-          (
-            err as { _errorHandlerProcessing?: boolean }
-          )._errorHandlerProcessing = true;
-
-          const safeHandle = () => {
-            try {
-              const handleableError =
-                err instanceof HandleableError
-                  ? err
-                  : new HandleableError(
-                      err instanceof Error ? err : new Error(String(err)),
-                      { cause: err },
-                    );
-              handleError(
-                handleableError,
-                res,
-                sendApiMessageResponse,
-                () => {},
-              );
-            } catch {
-              res.status(500).json({
-                message: engine.translate(
-                  SuiteCoreComponentId,
-                  SuiteCoreStringKey.Error_RecursiveErrorHandlingDetected,
-                ),
-                error: {
-                  message:
-                    err instanceof Error
-                      ? err.message
-                      : engine.translate(
-                          SuiteCoreComponentId,
-                          SuiteCoreStringKey.Common_UnexpectedError,
-                        ),
-                },
-              });
-            }
-          };
-
-          setImmediate(safeHandle);
-        },
-      );
-
-      const serversReady: Promise<void>[] = [];
-      serversReady.push(
-        new Promise<void>((resolve) => {
-          this.server = this.expressApp.listen(
-            this.environment.port,
-            this.environment.host,
-            () => {
-              debugLog(
-                this.environment.debug,
-                'log',
-                `[ ${engine.translate(
-                  SuiteCoreComponentId,
-                  SuiteCoreStringKey.Common_Ready,
-                )} ] http://${this.environment.host}:${this.environment.port}`,
-              );
-              resolve();
-            },
-          ) as ServerWithOptionalClose;
-        }),
-      );
-
-      if (this.environment.httpsDevCertRoot) {
-        try {
-          const certRoot = normalize(this.environment.httpsDevCertRoot);
-          if (!isAbsolute(certRoot) || certRoot.includes('..')) {
-            throw new TranslatableSuiteError(
-              SuiteCoreStringKey.Error_InvalidCertificatePathMustBeAbsolute,
-            );
-          }
-          const certPath = normalize(resolve(certRoot + '.pem'));
-          const keyPath = normalize(resolve(certRoot + '-key.pem'));
-          if (certPath.includes('..') || keyPath.includes('..')) {
-            throw new TranslatableSuiteError(
-              SuiteCoreStringKey.Error_InvalidCertificatePathAfterResolution,
-            );
-          }
-          const options = {
-            // amazonq-ignore-next-line fixed above
-            key: readFileSync(keyPath),
-            // amazonq-ignore-next-line fixed above
-            cert: readFileSync(certPath),
-          };
-
-          serversReady.push(
-            new Promise<void>((resolve) => {
-              createServer(options, this.expressApp).listen(
-                this.environment.httpsDevPort,
-                this.environment.host,
-                () => {
-                  console.log(
-                    `[ ${engine.translate(
-                      SuiteCoreComponentId,
-                      SuiteCoreStringKey.Common_Ready,
-                    )} ] https://${this.environment.host}:${
-                      this.environment.httpsDevPort
-                    }`,
-                  );
-                  resolve();
-                },
-              );
-            }),
-          );
-        } catch (err) {
-          console.error('Failed to start HTTPS server:', err);
-        }
-      }
-
-      await Promise.all(serversReady);
-      this._ready = true;
-    } catch (err) {
-      console.error(
-        engine.translate(
-          SuiteCoreComponentId,
-          SuiteCoreStringKey.Error_FailedToStartApplication,
-        ),
-        err,
-      );
-      if (process.env['NODE_ENV'] === 'test') {
-        throw err;
-      }
-      process.exit(1);
-    }
-  }
-
-  public override async stop(): Promise<void> {
-    const engine = getSuiteCoreI18nEngine({ constants: this.constants });
-    if (this.server) {
-      debugLog(
-        this.environment.debug,
-        'log',
-        `[ ${engine.translate(
-          SuiteCoreComponentId,
-          SuiteCoreStringKey.Common_Stopping,
-        )} ] ${engine.translate(
-          SuiteCoreComponentId,
-          SuiteCoreStringKey.Common_ApplicationAndDatabase,
-        )}`,
-      );
-      await new Promise<void>((resolve, reject) => {
-        this.server!.closeAllConnections?.();
-        this.server!.close((err) => {
-          if (err) {
-            reject(err);
-          } else {
-            resolve();
-          }
-        });
-      });
-      this.server = null;
-    }
-
-    await super.stop();
-    this._ready = false;
-    debugLog(
-      this.environment.debug,
-      'log',
-      `[ ${engine.translate(
-        SuiteCoreComponentId,
-        SuiteCoreStringKey.Common_Stopped,
-      )} ] ${engine.translate(
-        SuiteCoreComponentId,
-        SuiteCoreStringKey.Common_ApplicationAndDatabase,
-      )}`,
-    );
-  }
-}

package/src/backup-code.ts

@@ -1,348 +0,0 @@
-/**
- * @fileoverview Backup code implementation with v1.0.0 encryption scheme.
- * Provides secure backup code generation, encryption, validation using Argon2id and HKDF-SHA256.
- * @module backup-code
- */
-
-import { MemberType } from '@digitaldefiance/ecies-lib';
-import {
-  Constants as ApiConstants,
-  Member as BackendMember,
-  PlatformID,
-} from '@digitaldefiance/node-ecies-lib';
-import {
-  BackupCodeString,
-  IBackupCode,
-  InvalidBackupCodeError,
-  PrivateKeyRequiredError,
-  SuiteCoreStringKey,
-  TranslatableSuiteError,
-} from '@digitaldefiance/suite-core-lib';
-import * as argon2 from 'argon2';
-import { createHmac, randomBytes, timingSafeEqual } from 'crypto';
-import { LocalhostConstants } from './constants';
-import { InvalidBackupCodeVersionError } from './errors/invalid-backup-code-version';
-import { IConstants } from './interfaces';
-import { SymmetricService } from './services/symmetric';
-
-/**
- * Class representing a backup code string with associated operations.
- *
- * v1 scheme:
- * - Code: 32 lowercase alphanumerics (a–z0–9), displayed as 8 groups of 4: xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx
- * - Checksum/tag: HKDF-SHA256(codeUtf8, salt, "backup-checksum") → 32 bytes (stored as hex)
- * - KDF for encryption key: Argon2id(codeUtf8, salt) → 32 bytes
- * - Encryption: SymmetricService AEAD (encryptedData must embed IV + authTag + ciphertext)
- * - Wrapping: AEAD blob wrapped with system user's asymmetric key (ECIES)
- */
-export class BackupCode extends BackupCodeString {
-  /** Current backup code scheme version implemented by this service. */
-  public static readonly BackupCodeVersion = '1.0.0';
-  // Centralized Argon2id parameters (tunable)
-  private static readonly Argon2Params = {
-    type: argon2.argon2id,
-    hashLength: 32, // derive AES-256 key
-    timeCost: 3,
-    memoryCost: 65536, // 64 MiB
-    parallelism: 1,
-    raw: true as const,
-  } as const;
-
-  constructor(code: string) {
-    super(code);
-  }
-
-  /**
-   * Generate the configured number of backup codes.
-   * Note: If generation alphabet/length is controlled elsewhere, prefer that path.
-   */
-  public static override generateBackupCodes(
-    constants: IConstants = LocalhostConstants,
-  ): Array<BackupCode> {
-    const codes: Array<BackupCode> = [];
-    for (let i = 0; i < constants.BACKUP_CODES.Count; i++) {
-      codes.push(new BackupCode(BackupCode.generateBackupCode()));
-    }
-    return codes;
-  }
-
-  /**
-   * HKDF-Extract-and-Expand using HMAC-SHA-256.
-   *
-   * PRK = HMAC(salt, ikm)
-   * T(0) = empty
-   * T(i) = HMAC(PRK, T(i-1) || info || i)
-   * OKM = first 'length' bytes of T(1) || T(2) || ...
-   */
-  public static hkdfSha256(
-    ikm: Buffer,
-    salt: Buffer,
-    info: Buffer,
-    length: number,
-  ): Buffer {
-    if (length === 0) {
-      return Buffer.alloc(0);
-    }
-
-    // HKDF-Extract: PRK = HMAC-Hash(salt, IKM)
-    // If salt is empty, use a string of HashLen zeros
-    const actualSalt = salt.length === 0 ? Buffer.alloc(32, 0) : salt;
-    const prk = createHmac('sha256', actualSalt).update(ikm).digest();
-
-    // HKDF-Expand
-    const blocks: Buffer[] = [];
-    let prev = Buffer.alloc(0);
-    const n = Math.ceil(length / 32);
-
-    for (let i = 1; i <= n; i++) {
-      const hmac = createHmac('sha256', prk);
-      hmac.update(prev);
-      hmac.update(info);
-      hmac.update(Buffer.from([i]));
-      prev = Buffer.from(hmac.digest());
-      blocks.push(prev);
-    }
-
-    return Buffer.concat(blocks).subarray(0, length);
-  }
-
-  /**
-   * v1: Derive a 32-byte encryption key from a normalized backup code using Argon2id and the per-code salt.
-   * Uses UTF-8 bytes of the normalized code (not hex).
-   */
-  public static async getBackupKeyV1(
-    checksumSaltHex: string,
-    normalizedCode: string,
-    constants: IConstants = LocalhostConstants,
-  ): Promise<Buffer> {
-    if (!constants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
-      throw new InvalidBackupCodeError();
-    }
-    const codeBytes = Buffer.from(normalizedCode, 'utf8');
-    const checksumSalt = Buffer.from(checksumSaltHex, 'hex');
-    try {
-      const key = (await argon2.hash(codeBytes, {
-        ...BackupCode.Argon2Params,
-        salt: checksumSalt,
-      })) as Buffer;
-      return key; // 32-byte Buffer
-    } finally {
-      codeBytes.fill(0);
-    }
-  }
-
-  /**
-   * v1: Compute a 32-byte checksum/tag for a normalized code using HKDF-SHA256(codeUtf8, salt, "backup-checksum").
-   */
-  private static computeChecksumV1(
-    normalizedCode: string,
-    checksumSalt: Buffer,
-  ): Buffer {
-    const codeBytes = Buffer.from(normalizedCode, 'utf8');
-    try {
-      return BackupCode.hkdfSha256(
-        codeBytes,
-        checksumSalt,
-        Buffer.from('backup-checksum'),
-        32,
-      );
-    } finally {
-      codeBytes.fill(0);
-    }
-  }
-
-  public async encrypt<TID extends PlatformID = Buffer>(
-    backupUser: BackendMember<TID>,
-    systemUser: BackendMember<TID>,
-    constants: IConstants = LocalhostConstants,
-  ): Promise<IBackupCode> {
-    if (!backupUser.hasPrivateKey) {
-      throw new PrivateKeyRequiredError();
-    }
-    if (systemUser.type !== MemberType.System) {
-      throw new TranslatableSuiteError(
-        SuiteCoreStringKey.Error_SystemUserMustBeSystemMemberType,
-      );
-    }
-    const raw = this.value ?? '';
-    const normalized = BackupCode.normalizeCode(raw);
-    if (
-      !(
-        constants.BACKUP_CODES.DisplayRegex.test(raw) ||
-        constants.BACKUP_CODES.NormalizedHexRegex.test(normalized)
-      )
-    ) {
-      throw new InvalidBackupCodeError();
-    }
-
-    const checksumSalt = randomBytes(ApiConstants.PBKDF2.SALT_BYTES);
-    const checksumBuf = BackupCode.computeChecksumV1(normalized, checksumSalt);
-    const encryptionKey = await BackupCode.getBackupKeyV1(
-      checksumSalt.toString('hex'),
-      normalized,
-      constants,
-    );
-
-    try {
-      const sealed = SymmetricService.encryptBuffer(
-        Buffer.from(backupUser.privateKey!.value),
-        encryptionKey,
-      );
-      const wrappedEncryptedPrivateKey = systemUser
-        .encryptData(sealed.encryptedData)
-        .toString('hex');
-
-      return {
-        version: BackupCode.BackupCodeVersion,
-        checksumSalt: checksumSalt.toString('hex'),
-        checksum: checksumBuf.toString('hex'),
-        encrypted: wrappedEncryptedPrivateKey,
-      } as IBackupCode;
-    } finally {
-      encryptionKey.fill(0);
-      checksumBuf.fill(0);
-    }
-  }
-
-  /**
-   * v1: Encrypt and wrap backup codes for a user.
-   * - Validates code format (display or normalized)
-   * - Computes HKDF checksum/tag
-   * - Derives Argon2id encryption key (32 bytes) from UTF-8 code
-   * - Encrypts the private key with AEAD and wraps with system user
-   */
-  public static async encryptBackupCodesV1<TID extends PlatformID = Buffer>(
-    backupUser: BackendMember<TID>,
-    systemUser: BackendMember<TID>,
-    codes: Array<BackupCode>,
-  ): Promise<Array<IBackupCode>> {
-    const encryptedCodes: Array<IBackupCode> = [];
-    for (const code of codes) {
-      encryptedCodes.push(await code.encrypt(backupUser, systemUser));
-    }
-    return encryptedCodes;
-  }
-
-  /** Delegate to current version. */
-  public static encryptBackupCodes<TID extends PlatformID = Buffer>(
-    backupUser: BackendMember<TID>,
-    systemUser: BackendMember<TID>,
-    codes: Array<BackupCode>,
-  ): Promise<Array<IBackupCode>> {
-    return BackupCode.encryptBackupCodesV1(backupUser, systemUser, codes);
-  }
-
-  /**
-   * v1: Validate whether a backup code exists (unused) in the provided collection.
-   * Uses constant-time comparison of binary checksums (codeUtf8 + salt).
-   */
-  public static validateBackupCodeV1(
-    encryptedBackupCodes: Array<IBackupCode>,
-    backupCode: string,
-    constants: IConstants = LocalhostConstants,
-  ): boolean {
-    const normalizedCode = BackupCodeString.normalizeCode(backupCode);
-    if (!constants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
-      return false;
-    }
-    const codeBytes = Buffer.from(normalizedCode, 'utf8');
-    try {
-      for (const code of encryptedBackupCodes) {
-        if (code.version !== BackupCode.BackupCodeVersion) continue;
-        const checksumSalt = Buffer.from(code.checksumSalt, 'hex');
-        const expected = BackupCode.hkdfSha256(
-          codeBytes,
-          checksumSalt,
-          Buffer.from('backup-checksum'),
-          32,
-        );
-        if (
-          code.checksum.length === expected.length * 2 &&
-          timingSafeEqual(Buffer.from(code.checksum, 'hex'), expected)
-        ) {
-          return true;
-        }
-      }
-      return false;
-    } finally {
-      codeBytes.fill(0);
-    }
-  }
-
-  /**
-   * Validate a backup code against any supported version present in the collection.
-   */
-  public static validateBackupCode(
-    encryptedBackupCodes: Array<IBackupCode>,
-    backupCode: string,
-    constants: IConstants = LocalhostConstants,
-  ): boolean {
-    const normalizedCode = BackupCodeString.normalizeCode(backupCode);
-    if (!constants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
-      return false;
-    }
-    if (
-      encryptedBackupCodes.some(
-        (c) => c.version === BackupCode.BackupCodeVersion,
-      )
-    ) {
-      return this.validateBackupCodeV1(
-        encryptedBackupCodes.filter(
-          (c) => c.version === BackupCode.BackupCodeVersion,
-        ),
-        normalizedCode,
-      );
-    }
-    return false;
-  }
-
-  /**
-   * Detect the version by matching checksum against stored codes; returns the matched version.
-   */
-  public static detectBackupCodeVersion(
-    encryptedBackupCodes: Array<IBackupCode>,
-    backupCode: string,
-    constants: IConstants = LocalhostConstants,
-  ): string {
-    const normalizedCode = BackupCodeString.normalizeCode(backupCode);
-    if (!constants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
-      throw new InvalidBackupCodeError();
-    }
-
-    const v1Set = encryptedBackupCodes.filter(
-      (c) => c.version === BackupCode.BackupCodeVersion,
-    );
-    if (v1Set.length) {
-      const codeBytes = Buffer.from(normalizedCode, 'utf8');
-      try {
-        for (const c of v1Set) {
-          const checksumSalt = Buffer.from(c.checksumSalt, 'hex');
-          const expected = BackupCode.hkdfSha256(
-            codeBytes,
-            checksumSalt,
-            Buffer.from('backup-checksum'),
-            32,
-          );
-          if (
-            c.checksum.length === expected.length * 2 &&
-            timingSafeEqual(Buffer.from(c.checksum, 'hex'), expected)
-          ) {
-            return c.version;
-          }
-        }
-      } finally {
-        // zeroize
-        codeBytes.fill(0);
-      }
-    }
-
-    const versionsInSet = new Set(encryptedBackupCodes.map((c) => c.version));
-    if (
-      versionsInSet.size > 0 &&
-      !versionsInSet.has(BackupCode.BackupCodeVersion)
-    ) {
-      throw new InvalidBackupCodeVersionError([...versionsInSet][0]);
-    }
-    throw new InvalidBackupCodeError();
-  }
-}