@digitaldefiance/node-express-suite 1.0.23 → 1.0.24

package/src/application.ts

@@ -1,254 +0,0 @@
-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

@@ -1,336 +0,0 @@
-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

@@ -1,69 +0,0 @@
-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');
-}