@digitaldefiance/node-express-suite 3.7.3 → 3.7.5

package/src/application.ts

@@ -0,0 +1,330 @@
+/**
+ * @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

@@ -0,0 +1,348 @@
+/**
+ * @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();
+  }
+}