@digitaldefiance/node-express-suite 3.7.3 → 3.7.5

package/src/services/jwt.ts

@@ -0,0 +1,146 @@
+/**
+ * @fileoverview JWT token service for authentication and authorization.
+ * Handles JWT token generation, signing, and verification with role-based access control.
+ * @module services/jwt
+ */
+
+import {
+  ITokenRole,
+  ITokenRoleDTO,
+  ITokenUser,
+} from '@digitaldefiance/suite-core-lib';
+import {
+  JsonWebTokenError,
+  JwtPayload,
+  TokenExpiredError as JwtTokenExpiredError,
+  sign,
+  verify,
+  VerifyOptions,
+} from 'jsonwebtoken';
+import { promisify } from 'util';
+import { IUserDocument } from '../documents/user';
+import { InvalidJwtTokenError } from '../errors/invalid-jwt-token';
+import { TokenExpiredError } from '../errors/token-expired';
+import { IApplication } from '../interfaces/application';
+import { IJwtSignResponse } from '../interfaces/jwt-sign-response';
+import { BaseService } from './base';
+import { RoleService } from './role';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+const verifyAsync = promisify<
+  string,
+  string | Buffer,
+  VerifyOptions,
+  JwtPayload | string
+>(verify);
+
+/**
+ * Service for JWT token operations including generation, signing, and verification.
+ * Integrates with role service to embed user roles in JWT tokens.
+ * @template TID - Platform ID type (defaults to Buffer)
+ * @template TDate - Date type (defaults to Date)
+ * @template TTokenRole - Token role interface type
+ * @template TTokenUser - Token user interface type
+ * @template TApplication - Application interface type
+ * @extends {BaseService<TID, TApplication>}
+ */
+export class JwtService<
+  TID extends PlatformID = Buffer,
+  TDate extends Date = Date,
+  TTokenRole extends ITokenRole<TID, TDate> = ITokenRole<TID, TDate>,
+  TTokenUser extends ITokenUser = ITokenUser,
+  TApplication extends IApplication<TID> = IApplication<TID>,
+> extends BaseService<TID, TApplication> {
+  private readonly roleService: RoleService<TID, TDate, TTokenRole>;
+
+  /**
+   * Constructor for the JWT service
+   * @param application The application object
+   */
+  constructor(application: TApplication) {
+    super(application);
+    this.roleService = new RoleService<TID, TDate, TTokenRole>(application);
+  }
+
+  /**
+   * Sign a JWT token for a user
+   * @param userDoc The user document to sign the token for
+   * @param jwtSecret The secret to sign the token with
+   * @param overrideLanguage Optional language to use for role translations
+   * @returns The signed token
+   */
+  public async signToken(
+    userDoc: IUserDocument<string, TID>,
+    jwtSecret: string,
+    overrideLanguage?: string,
+  ): Promise<IJwtSignResponse<TID, TDate, TTokenRole>> {
+    // look for roles the user is a member of (the role contains the user id in the user's roles array)
+    const roles = await this.roleService.getUserRoles(userDoc._id);
+    const tokenRoles: Array<TTokenRole> = this.roleService.rolesToTokenRoles(
+      roles,
+      overrideLanguage,
+    );
+    const tokenRoleDTOs = tokenRoles.map((role) =>
+      RoleService.roleToRoleDTO<TID, TDate>(role),
+    );
+    const roleTranslatedNames = tokenRoles.map((role) => role.translatedName);
+    const roleNames = tokenRoles.map((role) => role.name);
+    const tokenUser = {
+      userId: userDoc._id.toString(),
+      roles: tokenRoleDTOs,
+    } as TTokenUser;
+    // amazonq-ignore-next-line false positive
+    const token = sign(tokenUser, jwtSecret, {
+      algorithm: this.application.constants.JWT.ALGORITHM,
+      allowInsecureKeySizes: false,
+      expiresIn: this.application.constants.JWT.EXPIRATION_SEC,
+    });
+    return {
+      token,
+      tokenUser,
+      roleNames,
+      roleTranslatedNames,
+      roles: tokenRoles,
+      roleDTOs: tokenRoleDTOs,
+    };
+  }
+
+  /**
+   * Verify a JWT token and return the user data
+   * @param token The token to verify
+   * @returns The user data
+   * @throws InvalidTokenError
+   */
+  public async verifyToken(token: string): Promise<TTokenUser | null> {
+    try {
+      const decoded = (await verifyAsync(
+        token,
+        this.application.environment.jwtSecret,
+        {
+          algorithms: [this.application.constants.JWT.ALGORITHM],
+        },
+      )) as JwtPayload;
+
+      if (
+        typeof decoded === 'object' &&
+        decoded !== null &&
+        'userId' in decoded &&
+        'roles' in decoded
+      ) {
+        return {
+          userId: decoded['userId'] as string,
+          roles: decoded['roles'] as ITokenRoleDTO[],
+        } as TTokenUser;
+      } else {
+        return null;
+      }
+    } catch (err) {
+      if (err instanceof JwtTokenExpiredError) {
+        throw new TokenExpiredError();
+      } else if (err instanceof JsonWebTokenError) {
+        throw err;
+      }
+      throw new InvalidJwtTokenError();
+    }
+  }
+}

package/src/services/key-wrapping.ts

@@ -0,0 +1,528 @@
+/**
+ * @fileoverview Service for password-based key wrapping and unwrapping using AES-256-GCM.
+ * Provides secure master key management, password changes, and generic secret wrapping.
+ * @module services/key-wrapping
+ */
+
+import { SecureBuffer, SecureString } from '@digitaldefiance/ecies-lib';
+import {
+  Constants,
+  IConstants,
+  Pbkdf2Service,
+} from '@digitaldefiance/node-ecies-lib';
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes,
+} from 'crypto';
+import { InvalidNewPasswordError, InvalidPasswordError } from '../errors';
+
+/**
+ * Creates a PBKDF2 service instance from constants.
+ * @param constants Configuration constants
+ * @returns Configured PBKDF2 service
+ */
+function createPbkdf2Service(constants: IConstants): Pbkdf2Service {
+  return Pbkdf2Service.fromConstants(constants);
+}
+
+/**
+ * Represents a password-wrapped master key with all encryption metadata.
+ */
+export interface WrappedKey {
+  /** Hex-encoded salt for PBKDF2 key derivation */
+  salt: string;
+  /** Hex-encoded initialization vector for AES-GCM */
+  iv: string;
+  /** Hex-encoded authentication tag for AES-GCM */
+  authTag: string;
+  /** Hex-encoded encrypted master key */
+  encryptedMasterKey: string;
+  /** Number of PBKDF2 iterations used */
+  iterations: number;
+}
+
+/**
+ * Generic password-wrapped secret payload with encryption metadata.
+ */
+export interface PasswordWrappedSecret {
+  /** Hex-encoded salt for PBKDF2 key derivation */
+  salt: string;
+  /** Hex-encoded initialization vector for AES-GCM */
+  iv: string;
+  /** Hex-encoded authentication tag for AES-GCM */
+  authTag: string;
+  /** Hex-encoded encrypted secret data */
+  ciphertext: string;
+  /** Number of PBKDF2 iterations used */
+  iterations: number;
+}
+
+/**
+ * Service for password-based key wrapping and unwrapping operations.
+ * Provides secure master key management with AES-256-GCM encryption and PBKDF2 key derivation.
+ * Supports both synchronous and asynchronous operations with deduplication for concurrent requests.
+ */
+export class KeyWrappingService {
+  /**
+   * In-flight de-duplication map to share PBKDF2 work across concurrent identical requests.
+   * Stores promises of base64-encoded master key bytes for sharing across callers.
+   * @private
+   */
+  private static inFlightUnwraps: Map<string, Promise<string>> = new Map();
+
+  /**
+   * Generates a new random master key and wraps it with the user's password.
+   * @param password User's password for wrapping
+   * @param constants Configuration constants (defaults to Constants)
+   * @returns Object containing the master key and wrapped key metadata
+   * @throws {InvalidNewPasswordError} If password doesn't meet requirements
+   */
+  public wrapNewMasterKey(
+    password: SecureString,
+    constants: IConstants = Constants,
+  ): {
+    masterKey: SecureBuffer;
+    wrappedKey: WrappedKey;
+  } {
+    const masterKey = new SecureBuffer(
+      randomBytes(constants.WRAPPED_KEY.MASTER_KEY_SIZE),
+    );
+    const wrappedKey = this.wrapMasterKey(masterKey, password, constants);
+    return { masterKey, wrappedKey };
+  }
+
+  /**
+   * Wraps an existing master key with a password-derived key using AES-256-GCM.
+   * @param masterKey Master key to wrap
+   * @param password User's password for wrapping
+   * @param constants Configuration constants (defaults to Constants)
+   * @returns Wrapped key metadata including salt, IV, auth tag, and encrypted key
+   * @throws {InvalidNewPasswordError} If password doesn't meet requirements
+   */
+  public wrapMasterKey(
+    masterKey: SecureBuffer,
+    password: SecureString,
+    constants: IConstants = Constants,
+  ): WrappedKey {
+    if (constants.PasswordRegex.test(password.value ?? '') === false) {
+      throw new InvalidNewPasswordError();
+    }
+    const salt = randomBytes(constants.WRAPPED_KEY.SALT_SIZE);
+    const iterations = constants.WRAPPED_KEY.MIN_ITERATIONS;
+    const pbkdf2Service = createPbkdf2Service(constants);
+
+    // Derive key from password using centralized PBKDF2 service
+    const derivedKey = pbkdf2Service.deriveKeyFromPassword(
+      Buffer.from(password.valueAsUint8Array),
+      salt,
+      iterations,
+      constants.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(constants.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 (synchronous).
+   * @param wrappedKey Wrapped key metadata
+   * @param password User's password for unwrapping
+   * @param constants Configuration constants (defaults to Constants)
+   * @returns Unwrapped master key in a SecureBuffer
+   * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+   */
+  public unwrapMasterKey(
+    wrappedKey: WrappedKey,
+    password: SecureString,
+    constants: IConstants = Constants,
+  ): 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(constants);
+
+    // 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.
+   * @param wrappedKey Wrapped key metadata
+   * @param password User's password (SecureString or raw string)
+   * @param constants Configuration constants (defaults to Constants)
+   * @returns Promise resolving to unwrapped master key in a SecureBuffer
+   * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+   */
+  public async unwrapMasterKeyAsync(
+    wrappedKey: WrappedKey,
+    password: SecureString | string,
+    constants: IConstants = Constants,
+  ): 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(constants);
+
+    // 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 + password hash to avoid redundant computation.
+   * @param wrappedKey Wrapped key metadata
+   * @param password User's password as string
+   * @param constants Configuration constants (defaults to Constants)
+   * @returns Promise resolving to unwrapped master key in a SecureBuffer
+   * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+   */
+  public async unwrapMasterKeyAsyncDedup(
+    wrappedKey: WrappedKey,
+    password: string,
+    constants: IConstants = Constants,
+  ): 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,
+          constants,
+        );
+        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 with a new password.
+   * @param wrappedKey Current wrapped key metadata
+   * @param oldPassword Current password
+   * @param newPassword New password
+   * @param constants Configuration constants (defaults to Constants)
+   * @returns New wrapped key metadata
+   * @throws {InvalidPasswordError} If old password is incorrect
+   * @throws {InvalidNewPasswordError} If new password doesn't meet requirements
+   */
+  public changePassword(
+    wrappedKey: WrappedKey,
+    oldPassword: SecureString,
+    newPassword: SecureString,
+    constants: IConstants = Constants,
+  ): WrappedKey {
+    // Unwrap with old password
+    const masterKey = this.unwrapMasterKey(wrappedKey, oldPassword, constants);
+
+    try {
+      // Re-wrap with new password
+      return this.wrapMasterKey(masterKey, newPassword, constants);
+    } finally {
+      masterKey.dispose();
+    }
+  }
+
+  /**
+   * Wraps arbitrary secret bytes with a password-derived key using AES-256-GCM.
+   * @param secret Secret data to wrap
+   * @param password User's password for wrapping
+   * @param constants Configuration constants (defaults to Constants)
+   * @returns Password-wrapped secret metadata
+   * @throws {InvalidNewPasswordError} If password doesn't meet requirements
+   */
+  public wrapSecret(
+    secret: SecureBuffer,
+    password: SecureString,
+    constants: IConstants = Constants,
+  ): PasswordWrappedSecret {
+    if (constants.PasswordRegex.test(password.value ?? '') === false) {
+      throw new InvalidNewPasswordError();
+    }
+    const salt = randomBytes(constants.WRAPPED_KEY.SALT_SIZE);
+    const iterations = constants.WRAPPED_KEY.MIN_ITERATIONS;
+    const pbkdf2Service = createPbkdf2Service(constants);
+
+    // Derive key from password using centralized PBKDF2 service
+    const derivedKey = pbkdf2Service.deriveKeyFromPassword(
+      Buffer.from(password.valueAsUint8Array),
+      salt,
+      iterations,
+      constants.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(constants.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 (synchronous).
+   * @param wrapped Password-wrapped secret metadata
+   * @param password User's password for unwrapping
+   * @param constants Configuration constants (defaults to Constants)
+   * @returns Unwrapped secret in a SecureBuffer
+   * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+   */
+  public unwrapSecret(
+    wrapped: PasswordWrappedSecret,
+    password: SecureString,
+    constants: IConstants = Constants,
+  ): 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(constants);
+
+    // 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 using async PBKDF2 to avoid blocking.
+   * @param wrapped Password-wrapped secret metadata
+   * @param password User's password (SecureString or raw string)
+   * @param constants Configuration constants (defaults to Constants)
+   * @returns Promise resolving to unwrapped secret in a SecureBuffer
+   * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+   * @throws {Error} If password is undefined, null, or invalid type
+   */
+  public async unwrapSecretAsync(
+    wrapped: PasswordWrappedSecret,
+    password: SecureString | string,
+    constants: IConstants = Constants,
+  ): 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(constants);
+
+    // 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();
+    }
+  }
+}