@digitaldefiance/node-express-suite 1.0.23 → 1.0.25

package/src/services/key-wrapping.ts

@@ -1,434 +0,0 @@
-import { SecureBuffer, SecureString } from '@digitaldefiance/ecies-lib';
-import {
-  Constants as ApiConstants,
-  Pbkdf2Service,
-} from '@digitaldefiance/node-ecies-lib';
-import {
-  createCipheriv,
-  createDecipheriv,
-  createHash,
-  randomBytes,
-} from 'crypto';
-import { Constants as AppConstants } from '../constants';
-import { InvalidNewPasswordError, InvalidPasswordError } from '../errors';
-
-function createPbkdf2Service(): Pbkdf2Service {
-  return Pbkdf2Service.fromConstants(ApiConstants);
-}
-
-export interface WrappedKey {
-  salt: string;
-  iv: string;
-  authTag: string;
-  encryptedMasterKey: string;
-  iterations: number;
-}
-
-// Generic password-wrapped secret payload shape
-export interface PasswordWrappedSecret {
-  salt: string;
-  iv: string;
-  authTag: string;
-  ciphertext: string;
-  iterations: number;
-}
-
-export class KeyWrappingService {
-  // In-flight de-duplication map to share PBKDF2 work across concurrent identical requests
-  // Store a promise of the raw master key bytes, so each caller can get an independent SecureBuffer
-  private static inFlightUnwraps: Map<string, Promise<string>> = new Map();
-
-  /**
-   * Generates a new master key and wraps it with the user's password
-   */
-  public wrapNewMasterKey(password: SecureString): {
-    masterKey: SecureBuffer;
-    wrappedKey: WrappedKey;
-  } {
-    const masterKey = new SecureBuffer(
-      randomBytes(ApiConstants.WRAPPED_KEY.MASTER_KEY_SIZE),
-    );
-    const wrappedKey = this.wrapMasterKey(masterKey, password);
-    return { masterKey, wrappedKey };
-  }
-
-  /**
-   * Wraps an existing master key with a password-derived key
-   */
-  public wrapMasterKey(
-    masterKey: SecureBuffer,
-    password: SecureString,
-  ): WrappedKey {
-    if (AppConstants.PasswordRegex.test(password.value ?? '') === false) {
-      throw new InvalidNewPasswordError();
-    }
-    const salt = randomBytes(ApiConstants.WRAPPED_KEY.SALT_SIZE);
-    const iterations = ApiConstants.WRAPPED_KEY.MIN_ITERATIONS;
-    const pbkdf2Service = createPbkdf2Service();
-
-    // Derive key from password using centralized PBKDF2 service
-    const derivedKey = pbkdf2Service.deriveKeyFromPassword(
-      Buffer.from(password.valueAsUint8Array),
-      salt,
-      iterations,
-      ApiConstants.WRAPPED_KEY.SALT_SIZE,
-      32, // AES-256 key size
-      'sha256', // Keep existing algorithm for compatibility
-    );
-    const passwordKeySecure = new SecureBuffer(derivedKey.hash);
-
-    // Encrypt master key
-    const iv = randomBytes(ApiConstants.WRAPPED_KEY.IV_SIZE);
-    const cipher = createCipheriv('aes-256-gcm', passwordKeySecure.value, iv);
-
-    const encrypted = Buffer.concat([
-      cipher.update(masterKey.value),
-      cipher.final(),
-    ]);
-
-    const authTag = cipher.getAuthTag();
-
-    passwordKeySecure.dispose();
-
-    return {
-      salt: salt.toString('hex'),
-      iv: iv.toString('hex'),
-      authTag: authTag.toString('hex'),
-      encryptedMasterKey: encrypted.toString('hex'),
-      iterations,
-    };
-  }
-
-  /**
-   * Unwraps a master key using the user's password
-   */
-  public unwrapMasterKey(
-    wrappedKey: WrappedKey,
-    password: SecureString,
-  ): SecureBuffer {
-    const salt = Buffer.from(wrappedKey.salt, 'hex');
-    const iv = Buffer.from(wrappedKey.iv, 'hex');
-    const authTag = Buffer.from(wrappedKey.authTag, 'hex');
-    const encrypted = Buffer.from(wrappedKey.encryptedMasterKey, 'hex');
-    const pbkdf2Service = createPbkdf2Service();
-
-    // Derive the same key from password using centralized PBKDF2 service
-    const derivedKey = pbkdf2Service.deriveKeyFromPassword(
-      Buffer.from(password.valueAsUint8Array),
-      salt,
-      wrappedKey.iterations,
-      salt.length, // Use actual salt size
-      32, // AES-256 key size
-      'sha256', // Keep existing algorithm for compatibility
-    );
-    const passwordKeySecure = new SecureBuffer(derivedKey.hash);
-
-    try {
-      const decipher = createDecipheriv(
-        'aes-256-gcm',
-        passwordKeySecure.value,
-        iv,
-      );
-      decipher.setAuthTag(authTag);
-
-      const decrypted = Buffer.concat([
-        decipher.update(encrypted),
-        decipher.final(),
-      ]);
-
-      return new SecureBuffer(decrypted);
-    } catch {
-      throw new InvalidPasswordError();
-    } finally {
-      passwordKeySecure.dispose();
-    }
-  }
-
-  /**
-   * Async version of unwrapMasterKey that uses libuv threadpool via crypto.pbkdf2
-   * to avoid blocking the event loop during password verification.
-   */
-  public async unwrapMasterKeyAsync(
-    wrappedKey: WrappedKey,
-    password: SecureString | string,
-  ): Promise<SecureBuffer> {
-    const __perfEnabled = process.env['PERF_LOGS'] === '1';
-    const _t0 = __perfEnabled ? Date.now() : 0;
-    const salt = Buffer.from(wrappedKey.salt, 'hex');
-    const iv = Buffer.from(wrappedKey.iv, 'hex');
-    const authTag = Buffer.from(wrappedKey.authTag, 'hex');
-    const encrypted = Buffer.from(wrappedKey.encryptedMasterKey, 'hex');
-
-    // Accept either a SecureString (preferred) or a raw password string to avoid
-    // expensive SecureString construction in the hot login path.
-    const pwdBuffer =
-      // amazonq-ignore-next-line false positive
-      typeof password === 'string'
-        ? Buffer.from(password, 'utf8')
-        : Buffer.from(password.valueAsUint8Array);
-    const pbkdf2Service = createPbkdf2Service();
-
-    // Use centralized PBKDF2 service for async key derivation
-    const derivedKey = await pbkdf2Service.deriveKeyFromPasswordAsync(
-      pwdBuffer,
-      salt,
-      wrappedKey.iterations,
-      salt.length, // Use actual salt size
-      32, // AES-256 key size
-      'sha256', // Keep existing algorithm for compatibility
-    );
-    const passwordKeySecure = new SecureBuffer(derivedKey.hash);
-
-    try {
-      const decipher = createDecipheriv(
-        'aes-256-gcm',
-        passwordKeySecure.value,
-        iv,
-      );
-      decipher.setAuthTag(authTag);
-
-      const decrypted = Buffer.concat([
-        decipher.update(encrypted),
-        decipher.final(),
-      ]);
-      if (__perfEnabled)
-        console.warn(
-          '[perf] unwrapMasterKeyAsync pbkdf2',
-          'iters=' + String(wrappedKey.iterations).replace(/[\r\n]/g, ''),
-          'dt=' + (Date.now() - _t0) + 'ms',
-        );
-
-      return new SecureBuffer(decrypted);
-    } catch {
-      throw new InvalidPasswordError();
-    } finally {
-      // Best-effort zero the temporary password buffer
-      try {
-        pwdBuffer.fill(0);
-      } catch {
-        // ignore
-      }
-      passwordKeySecure.dispose();
-    }
-  }
-
-  /**
-   * Deduplicated async unwrap that coalesces concurrent identical PBKDF2 operations.
-   * Keyed by salt + iterations + a short hash of the password. Entry is removed after resolve/reject.
-   */
-  public async unwrapMasterKeyAsyncDedup(
-    wrappedKey: WrappedKey,
-    password: string,
-  ): Promise<SecureBuffer> {
-    // Derive a short cache key; avoid storing raw password by hashing
-    const pwdKey = createHash('sha256')
-      .update(password, 'utf8')
-      .digest('hex')
-      .slice(0, 24);
-    const cacheKey = `${wrappedKey.salt}:${wrappedKey.iterations}:${pwdKey}`;
-    let p = KeyWrappingService.inFlightUnwraps.get(cacheKey);
-    if (!p) {
-      // Compute once, extract raw bytes, dispose the shared SecureBuffer, and cache the bytes
-      p = (async () => {
-        const mk = await this.unwrapMasterKeyAsync(wrappedKey, password);
-        try {
-          const copy = Buffer.from(mk.value);
-          const b64 = copy.toString('base64');
-          // zeroize copy
-          copy.fill(0);
-          return b64;
-        } finally {
-          mk.dispose();
-        }
-      })().finally(() => {
-        // Best-effort cleanup
-        KeyWrappingService.inFlightUnwraps.delete(cacheKey);
-      }) as Promise<string>;
-      KeyWrappingService.inFlightUnwraps.set(cacheKey, p);
-    }
-    const b64 = await p;
-    // Return a fresh SecureBuffer per caller to avoid cross-disposal races
-    const buf = Buffer.from(b64, 'base64');
-    const secure = new SecureBuffer(Buffer.from(buf));
-    buf.fill(0);
-    return secure;
-  }
-
-  /**
-   * Changes password by re-wrapping the master key
-   */
-  public changePassword(
-    wrappedKey: WrappedKey,
-    oldPassword: SecureString,
-    newPassword: SecureString,
-  ): WrappedKey {
-    // Unwrap with old password
-    const masterKey = this.unwrapMasterKey(wrappedKey, oldPassword);
-
-    try {
-      // Re-wrap with new password
-      return this.wrapMasterKey(masterKey, newPassword);
-    } catch (error: unknown) {
-      throw error;
-    } finally {
-      masterKey.dispose();
-    }
-  }
-
-  /**
-   * Wraps arbitrary secret bytes with a password-derived key (AES-256-GCM)
-   */
-  public wrapSecret(
-    secret: SecureBuffer,
-    password: SecureString,
-  ): PasswordWrappedSecret {
-    if (AppConstants.PasswordRegex.test(password.value ?? '') === false) {
-      throw new InvalidNewPasswordError();
-    }
-    const salt = randomBytes(ApiConstants.WRAPPED_KEY.SALT_SIZE);
-    const iterations = ApiConstants.WRAPPED_KEY.MIN_ITERATIONS;
-    const pbkdf2Service = createPbkdf2Service();
-
-    // Derive key from password using centralized PBKDF2 service
-    const derivedKey = pbkdf2Service.deriveKeyFromPassword(
-      Buffer.from(password.valueAsUint8Array),
-      salt,
-      iterations,
-      ApiConstants.WRAPPED_KEY.SALT_SIZE,
-      32, // AES-256 key size
-      'sha256', // Keep existing algorithm for compatibility
-    );
-    const passwordKeySecure = new SecureBuffer(derivedKey.hash);
-
-    try {
-      const iv = randomBytes(ApiConstants.WRAPPED_KEY.IV_SIZE);
-      const cipher = createCipheriv('aes-256-gcm', passwordKeySecure.value, iv);
-      const encrypted = Buffer.concat([
-        cipher.update(secret.value),
-        cipher.final(),
-      ]);
-      const authTag = cipher.getAuthTag();
-      return {
-        salt: salt.toString('hex'),
-        iv: iv.toString('hex'),
-        authTag: authTag.toString('hex'),
-        ciphertext: encrypted.toString('hex'),
-        iterations,
-      };
-    } finally {
-      passwordKeySecure.dispose();
-    }
-  }
-
-  /**
-   * Unwraps a password-wrapped secret (sync)
-   */
-  public unwrapSecret(
-    wrapped: PasswordWrappedSecret,
-    password: SecureString,
-  ): SecureBuffer {
-    const salt = Buffer.from(wrapped.salt, 'hex');
-    const iv = Buffer.from(wrapped.iv, 'hex');
-    const authTag = Buffer.from(wrapped.authTag, 'hex');
-    const encrypted = Buffer.from(wrapped.ciphertext, 'hex');
-    const pbkdf2Service = createPbkdf2Service();
-
-    // Derive key from password using centralized PBKDF2 service
-    const derivedKey = pbkdf2Service.deriveKeyFromPassword(
-      Buffer.from(password.valueAsUint8Array),
-      salt,
-      wrapped.iterations,
-      salt.length, // Use actual salt size
-      32, // AES-256 key size
-      'sha256', // Keep existing algorithm for compatibility
-    );
-    const passwordKeySecure = new SecureBuffer(derivedKey.hash);
-    try {
-      const decipher = createDecipheriv(
-        'aes-256-gcm',
-        passwordKeySecure.value,
-        iv,
-      );
-      decipher.setAuthTag(authTag);
-      const decrypted = Buffer.concat([
-        decipher.update(encrypted),
-        decipher.final(),
-      ]);
-      return new SecureBuffer(decrypted);
-    } catch {
-      throw new InvalidPasswordError();
-    } finally {
-      passwordKeySecure.dispose();
-    }
-  }
-
-  /**
-   * Unwraps a password-wrapped secret (async PBKDF2)
-   */
-  public async unwrapSecretAsync(
-    wrapped: PasswordWrappedSecret,
-    password: SecureString | string,
-  ): Promise<SecureBuffer> {
-    const salt = Buffer.from(wrapped.salt, 'hex');
-    const iv = Buffer.from(wrapped.iv, 'hex');
-    const authTag = Buffer.from(wrapped.authTag, 'hex');
-    const encrypted = Buffer.from(wrapped.ciphertext, 'hex');
-
-    // Validate password parameter before using it
-    // amazonq-ignore-next-line false positive
-    if (typeof password === 'string') {
-      if (password === undefined || password === null) {
-        throw new Error('Password cannot be undefined or null');
-      }
-    } else if (!(password instanceof SecureString)) {
-      throw new Error('Password must be provided as string or SecureString');
-    }
-
-    const pwdBuffer =
-      // amazonq-ignore-next-line false positive
-      typeof password === 'string'
-        ? Buffer.from(password, 'utf8')
-        : await (async () => password.valueAsUint8Array)();
-
-    // Additional safety check
-    if (!pwdBuffer) {
-      throw new Error(
-        'Failed to create password buffer - password may be invalid',
-      );
-    }
-    const pbkdf2Service = createPbkdf2Service();
-
-    // Use centralized PBKDF2 service for async key derivation
-    const derivedKey = await pbkdf2Service.deriveKeyFromPasswordAsync(
-      Buffer.from(pwdBuffer),
-      salt,
-      wrapped.iterations,
-      salt.length, // Use actual salt size
-      32, // AES-256 key size
-      'sha256', // Keep existing algorithm for compatibility
-    );
-    const passwordKeySecure = new SecureBuffer(derivedKey.hash);
-    try {
-      const decipher = createDecipheriv(
-        'aes-256-gcm',
-        passwordKeySecure.value,
-        iv,
-      );
-      decipher.setAuthTag(authTag);
-      const decrypted = Buffer.concat([
-        decipher.update(encrypted),
-        decipher.final(),
-      ]);
-      return new SecureBuffer(decrypted);
-    } catch {
-      throw new InvalidPasswordError();
-    } finally {
-      try {
-        pwdBuffer.fill(0);
-      } catch {
-        // ignore
-      }
-      passwordKeySecure.dispose();
-    }
-  }
-}

package/src/services/mnemonic.ts

@@ -1,167 +0,0 @@
-import { SecureBuffer, SecureString } from '@digitaldefiance/ecies-lib';
-import {
-  SuiteCoreStringKey,
-  TranslatableSuiteError,
-} from '@digitaldefiance/suite-core-lib';
-import { createHmac } from 'crypto';
-import { ClientSession, Model } from 'mongoose';
-import { Constants as AppConstants } from '../constants';
-import { IMnemonicDocument } from '../documents/mnemonic';
-import { KeyWrappingService } from './key-wrapping';
-
-/**
- * Encrypts and stores mnemonics securely, using an HMAC to check for
- * uniqueness without exposing the mnemonic itself.
- */
-export class MnemonicService {
-  private readonly keyWrappingService: KeyWrappingService;
-  private readonly hmacSecret: SecureBuffer;
-  private readonly MnemonicModel: Model<IMnemonicDocument>;
-
-  constructor(
-    mnemonicModel: Model<IMnemonicDocument>,
-    hmacSecret: SecureBuffer,
-    keyWrappingService: KeyWrappingService,
-  ) {
-    this.MnemonicModel = mnemonicModel;
-    // Immediately wrap secrets in secure containers
-    this.hmacSecret = hmacSecret;
-    this.keyWrappingService = keyWrappingService;
-  }
-
-  /**
-   * Disposes of the secure secrets held by this service.
-   */
-  public dispose(): void {
-    this.hmacSecret.dispose();
-  }
-
-  /**
-   * Creates a non-reversible HMAC of the mnemonic for fast, indexed lookups.
-   * @param mnemonic The mnemonic to hash, wrapped in a SecureString.
-   */
-  public getMnemonicHmac(mnemonic: SecureString): string {
-    // Use the raw secret buffer for the HMAC
-    return createHmac('sha256', this.hmacSecret.value)
-      .update(mnemonic.valueAsUint8Array) // Use the raw buffer for consistency
-      .digest('hex');
-  }
-
-  /**
-   * Checks if a mnemonic already exists in the database using its HMAC.
-   * @param mnemonic The mnemonic to check, wrapped in a SecureString.
-   * @param session Optional Mongoose session for transaction support.
-   */
-  public async mnemonicExists(
-    mnemonic: SecureString,
-    session?: ClientSession,
-  ): Promise<boolean> {
-    const hmac = this.getMnemonicHmac(mnemonic);
-    const count = await this.MnemonicModel.countDocuments({ hmac }).session(
-      session ?? null,
-    );
-    return count > 0;
-  }
-
-  /**
-   * Adds a new, unique mnemonic to the database with password-based key wrapping.
-   * @param mnemonic The mnemonic to add, wrapped in a SecureString.
-   * @param password User's password for key wrapping.
-   * @param session Optional Mongoose session for transaction support.
-   */
-  public async addMnemonicWithPassword(
-    mnemonic: SecureString,
-    _password: SecureString,
-    session?: ClientSession,
-  ): Promise<{
-    document: IMnemonicDocument | null;
-  }> {
-    if (!mnemonic.value || !AppConstants.MnemonicRegex.test(mnemonic.value)) {
-      throw new TranslatableSuiteError(
-        SuiteCoreStringKey.Validation_MnemonicRegex,
-      );
-    }
-
-    if (await this.mnemonicExists(mnemonic, session)) {
-      return { document: null };
-    }
-
-    try {
-      const hmac = this.getMnemonicHmac(mnemonic);
-      const [newDoc] = await this.MnemonicModel.create(
-        [
-          {
-            hmac: hmac,
-          },
-        ],
-        { session },
-      );
-      return { document: newDoc };
-    } finally {
-      // nothing to dispose
-    }
-  }
-
-  /**
-   * Adds a new, unique mnemonic to the database.
-   * @param mnemonic The mnemonic to add, wrapped in a SecureString.
-   * @param session Optional Mongoose session for transaction support.
-   */
-  public async addMnemonic(
-    mnemonic: SecureString,
-    session?: ClientSession,
-  ): Promise<IMnemonicDocument | null> {
-    if (!mnemonic.value || !AppConstants.MnemonicRegex.test(mnemonic.value)) {
-      throw new TranslatableSuiteError(
-        SuiteCoreStringKey.Validation_MnemonicRegex,
-      );
-    }
-
-    if (await this.mnemonicExists(mnemonic, session)) {
-      return null;
-    }
-    const hmac = this.getMnemonicHmac(mnemonic);
-    const [newDoc] = await this.MnemonicModel.create(
-      [
-        {
-          hmac: hmac,
-        },
-      ],
-      { session },
-    );
-    return newDoc;
-  }
-
-  /**
-   * Retrieves a mnemonic document by ID.
-   * @param mnemonicId The ID of the mnemonic document.
-   * @param session Optional Mongoose session for transaction support.
-   */
-  public async getMnemonicDocument(
-    mnemonicId: string,
-    session?: ClientSession,
-  ): Promise<IMnemonicDocument | null> {
-    return await this.MnemonicModel.findById(mnemonicId).session(
-      session ?? null,
-    );
-  }
-
-  /**
-   * Decrypts a mnemonic from a document using the service's master encryption key.
-   * @param doc The mnemonic document.
-   */
-
-  /**
-   * Deletes a mnemonic document by ID.
-   * @param mnemonicId The ID of the mnemonic document.
-   * @param session Optional Mongoose session for transaction support.
-   */
-  public async deleteMnemonicDocument(
-    mnemonicId: string,
-    session?: ClientSession,
-  ): Promise<void> {
-    await this.MnemonicModel.findByIdAndDelete(mnemonicId).session(
-      session ?? null,
-    );
-  }
-}

package/src/services/request-user.ts

@@ -1,62 +0,0 @@
-import { IRequestUserDTO, ITokenRole } from '@digitaldefiance/suite-core-lib';
-import { Types } from 'mongoose';
-import { IUserDocument } from '../documents';
-import { IRequestUserBackendObject } from '../interfaces/backend-objects/request-user';
-import { RoleService } from './role';
-
-export class RequestUserService<I, TTokenRole extends ITokenRole<I>> {
-  /**
-   * Given a user document and an array of role documents, create the IRequestUser
-   * @param userDoc
-   * @returns
-   */
-  public static makeRequestUserDTO<
-    I,
-    TTokenRole extends ITokenRole<I>,
-    TRequestUserDTO extends IRequestUserDTO,
-  >(userDoc: IUserDocument, roles: TTokenRole[]): TRequestUserDTO {
-    if (!userDoc._id) {
-      throw new Error('User document is missing _id');
-    }
-    return {
-      id: userDoc._id.toString(),
-      email: userDoc.email,
-      roles: roles.map((r) => RoleService.roleToRoleDTO(r)),
-      username: userDoc.username,
-      timezone: userDoc.timezone,
-      ...(userDoc.lastLogin && { lastLogin: userDoc.lastLogin.toString() }),
-      emailVerified: userDoc.emailVerified,
-      siteLanguage: userDoc.siteLanguage as string,
-    } as TRequestUserDTO;
-  }
-
-  /**
-   * Given a request user, reconstitute dates, objectids, and enums
-   * @param requestUser a RequestUser DTO
-   * @returns An IRequestUserBackendObject
-   */
-  public static hydrateRequestUser<
-    S extends string,
-    TRequestUserDTO extends IRequestUserDTO & { siteLanguage: S },
-  >(requestUser: TRequestUserDTO): IRequestUserBackendObject<S> {
-    const hydratedRoles = requestUser.roles.map((role) =>
-      RoleService.hydrateRoleDTOToBackend(role),
-    );
-
-    const hydratedUser: IRequestUserBackendObject<S> = {
-      id: new Types.ObjectId(requestUser.id),
-      email: requestUser.email,
-      roles: hydratedRoles,
-      username: requestUser.username,
-      timezone: requestUser.timezone,
-      emailVerified: requestUser.emailVerified,
-      siteLanguage: requestUser.siteLanguage,
-    };
-
-    if (requestUser.lastLogin) {
-      hydratedUser.lastLogin = new Date(requestUser.lastLogin);
-    }
-
-    return hydratedUser;
-  }
-}