@digitaldefiance/node-express-suite 1.0.21 → 1.0.23

package/src/application.ts

@@ -0,0 +1,254 @@
+import { HandleableError } from '@digitaldefiance/i18n-lib';
+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 { Server } from 'http';
+import { createServer } from 'https';
+import mongoose, { Types } from 'mongoose';
+import { isAbsolute, normalize, resolve } from 'path';
+import { BaseApplication } from './application-base';
+import { IBaseDocument } from './documents/base';
+import { Environment } from './environment';
+import { IApplication, ICSPConfig, IFailableResult } from './interfaces';
+import { IConstants } from './interfaces/constants';
+import { Middlewares } from './middlewares';
+import { AppRouter } from './routers/app';
+import { BaseRouter } from './routers/base';
+import { SchemaMap } from './types';
+import { debugLog, handleError, sendApiMessageResponse } from './utils';
+
+/**
+ * Application class
+ */
+type ServerWithOptionalClose = Server & { closeAllConnections?: () => void };
+
+export class Application<
+    T,
+    I extends Types.ObjectId | string,
+    TInitResults,
+    TModelDocs extends Record<string, IBaseDocument<any>>,
+    TBaseDocument extends IBaseDocument<T, I> = IBaseDocument<T, I>,
+    TEnvironment extends Environment = Environment,
+    TConstants extends IConstants = IConstants,
+  >
+  extends BaseApplication<TModelDocs, TInitResults, TConstants>
+  implements IApplication<T, I, TBaseDocument, TEnvironment, TConstants>
+{
+  public readonly expressApp: ExpressApplication;
+  private server: ServerWithOptionalClose | null = null;
+  private readonly _cspConfig: ICSPConfig;
+  private readonly _apiRouter: BaseRouter;
+
+  public override get environment(): TEnvironment {
+    return super.environment as TEnvironment;
+  }
+
+  constructor(
+    environment: TEnvironment,
+    apiRouter: BaseRouter,
+    schemaMapFactory: (
+      connection: mongoose.Connection,
+    ) => SchemaMap<TModelDocs>,
+    databaseInitFunction: (
+      application: BaseApplication<TModelDocs, TInitResults>,
+    ) => Promise<IFailableResult<TInitResults>>,
+    initResultHashFunction: (initResults: TInitResults) => string,
+    cspConfig: ICSPConfig = {
+      corsWhitelist: [],
+      csp: {
+        defaultSrc: [],
+        imgSrc: [],
+        connectSrc: [],
+        scriptSrc: [],
+        styleSrc: [],
+        fontSrc: [],
+        frameSrc: [],
+      },
+    },
+    constants: TConstants = Constants as TConstants,
+  ) {
+    super(
+      environment,
+      schemaMapFactory,
+      databaseInitFunction,
+      initResultHashFunction,
+      constants,
+    );
+    this._apiRouter = apiRouter;
+    this.expressApp = express();
+    this.server = null;
+    this._cspConfig = cspConfig;
+  }
+
+  public override async start(mongoUri?: string): Promise<void> {
+    const engine = getSuiteCoreI18nEngine();
+    await super.start(mongoUri, true);
+    try {
+      Middlewares.init(
+        this.expressApp,
+        this._cspConfig.corsWhitelist,
+        this._cspConfig.csp,
+      );
+      const appRouter = new AppRouter(this._apiRouter);
+
+      appRouter.init(this.expressApp);
+      this.expressApp.use(
+        (
+          err: HandleableError | Error,
+          req: Request,
+          res: Response,
+          next: NextFunction,
+        ) => {
+          const handleableError =
+            err instanceof HandleableError
+              ? err
+              : new HandleableError(
+                  new Error(
+                    err.message ||
+                      engine.translate(
+                        SuiteCoreComponentId,
+                        SuiteCoreStringKey.Common_UnexpectedError,
+                      ),
+                  ),
+                  { cause: err },
+                );
+          handleError(handleableError, res, sendApiMessageResponse, next);
+        },
+      );
+
+      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,
+                () => {
+                  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();
+    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,336 @@
+import { MemberType } from '@digitaldefiance/ecies-lib';
+import {
+  Constants as ApiConstants,
+  Member as BackendMember,
+} from '@digitaldefiance/node-ecies-lib';
+import {
+  BackupCodeString,
+  IBackupCode,
+  InvalidBackupCodeError,
+  PrivateKeyRequiredError,
+} from '@digitaldefiance/suite-core-lib';
+import * as argon2 from 'argon2';
+import { createHmac, randomBytes, timingSafeEqual } from 'crypto';
+import { Constants } 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 = Constants,
+  ): 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 = Constants,
+  ): 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 unknown 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(
+    backupUser: BackendMember,
+    systemUser: BackendMember,
+    constants: IConstants = Constants,
+  ): Promise<IBackupCode> {
+    if (!backupUser.hasPrivateKey) {
+      throw new PrivateKeyRequiredError();
+    }
+    if (systemUser.type !== MemberType.System) {
+      throw new Error('System user must be of MemberType.System');
+    }
+    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,
+    );
+
+    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(
+    backupUser: BackendMember,
+    systemUser: BackendMember,
+    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(
+    backupUser: BackendMember,
+    systemUser: BackendMember,
+    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 = Constants,
+  ): 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 = Constants,
+  ): 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 = Constants,
+  ): 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();
+  }
+}

package/src/constants.ts

@@ -0,0 +1,69 @@
+import { ECIES as ECIESDefaults } from '@digitaldefiance/ecies-lib';
+import { createConstants } from '@digitaldefiance/suite-core-lib';
+import { IFECConsts } from './interfaces';
+import { IChecksumConsts } from './interfaces/checksum-consts';
+import { IConstants } from './interfaces/constants';
+import { IJwtConsts } from './interfaces/jwt-consts';
+
+/**
+ * Constants for checksum operations
+ * These values are critical for data integrity and MUST NOT be changed
+ * in an already established system as it will break all existing checksums.
+ */
+export const CHECKSUM: IChecksumConsts = Object.freeze({
+  /** Default hash bits for SHA3 */
+  SHA3_DEFAULT_HASH_BITS: 512 as const,
+
+  /** Length of a SHA3 checksum buffer in bytes */
+  SHA3_BUFFER_LENGTH: 64 as const,
+
+  /** algorithm to use for checksum */
+  ALGORITHM: 'sha3-512' as const,
+
+  /** encoding to use for checksum */
+  ENCODING: 'hex' as const,
+} as const);
+
+export const JWT: IJwtConsts = {
+  /**
+   * Algorithm to use for JWT
+   */
+  ALGORITHM: 'HS256' as const,
+
+  /**
+   * The expiration time for a JWT token in seconds
+   */
+  EXPIRATION_SEC: 86400 as const,
+} as const;
+
+export const FEC: IFECConsts = {
+  /**
+   * Maximum size of a single shard
+   */
+  MAX_SHARD_SIZE: 1048576 as const,
+} as const;
+
+// use defaults from ecies-lib
+export const ECIES = Object.freeze(ECIESDefaults);
+
+export const createExpressConstants = (
+  siteDomain: string,
+  overrides?: Partial<IConstants>,
+): IConstants => {
+  return Object.freeze({
+    ...createConstants(siteDomain, overrides),
+    CHECKSUM: CHECKSUM,
+    JWT: JWT,
+    FEC: FEC,
+    ECIES: ECIES,
+  } as const);
+};
+
+export const Constants: IConstants = createExpressConstants('localhost');
+
+if (
+  CHECKSUM.SHA3_BUFFER_LENGTH !== CHECKSUM.SHA3_DEFAULT_HASH_BITS / 8 ||
+  CHECKSUM.SHA3_BUFFER_LENGTH !== CHECKSUM.SHA3_DEFAULT_HASH_BITS / 8
+) {
+  throw new Error('Invalid checksum constants');
+}