@digitaldefiance/node-express-suite 3.6.21 → 3.6.24

package/src/services/backup-code.ts

@@ -1,321 +0,0 @@
-import {
-  EmailString,
-  MemberType,
-  SecureBuffer,
-  SecureString,
-} from '@digitaldefiance/ecies-lib';
-import { ClientSession, Types } from '@digitaldefiance/mongoose-types';
-import {
-  Member as BackendMember,
-  ECIESService,
-} from '@digitaldefiance/node-ecies-lib';
-import {
-  IBackupCode,
-  InvalidBackupCodeError,
-  ITokenRole,
-} from '@digitaldefiance/suite-core-lib';
-import { timingSafeEqual } from 'crypto';
-import { BackupCode } from '../backup-code';
-import { LocalhostConstants as AppConstants } from '../constants';
-import { IUserDocument } from '../documents';
-import { InvalidBackupCodeVersionError } from '../errors/invalid-backup-code-version';
-import { IApplication } from '../interfaces/application';
-import { BaseService } from './base';
-import { KeyWrappingService } from './index';
-import { RoleService } from './role';
-import { SymmetricService } from './symmetric';
-import { SystemUserService } from './system-user';
-
-/**
- * Service handling generation, storage, validation, consumption, and recovery using backup codes.
- *
- * 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 BackupCodeService<
-  I extends string | Types.ObjectId = Types.ObjectId,
-  D extends Date = Date,
-  TTokenRole extends ITokenRole<I, D> = ITokenRole<I, D>,
-  TApplication extends IApplication = IApplication,
-> extends BaseService {
-  private readonly eciesService: ECIESService;
-  private systemUser?: BackendMember<I>;
-  private readonly keyWrappingService: KeyWrappingService;
-  private readonly roleService: RoleService<I, D, TTokenRole>;
-
-  /**
-   * Construct a BackupCodeService.
-   */
-  constructor(
-    application: TApplication,
-    eciesService: ECIESService,
-    keyWrappingService: KeyWrappingService,
-    roleService: RoleService<I, D, TTokenRole>,
-  ) {
-    super(application);
-    this.eciesService = eciesService;
-    this.keyWrappingService = keyWrappingService;
-    this.roleService = roleService;
-  }
-
-  /**
-   * Get the lazily-initialized system user for key wrapping/unwrapping.
-   */
-  private getSystemUser(): BackendMember<I> {
-    if (!this.systemUser) {
-      // System user is always created with Buffer IDs, but we need to cast to the generic type I
-      // This is safe because the system user's ID type is compatible with all ID types
-      this.systemUser = SystemUserService.getSystemUser(
-        this.application.environment,
-        this.application.constants,
-      ) as unknown as BackendMember<I>;
-    }
-    return this.systemUser;
-  }
-
-  /**
-   * Forcibly set the system user (for database initialization)
-   * @param user
-   */
-  public setSystemUser(user: BackendMember<I>): void {
-    this.systemUser = user;
-  }
-
-  /**
-   * v1: Consume (validate and remove) a backup code via constant-time checksum match.
-   */
-  public useBackupCodeV1(
-    encryptedBackupCodes: Array<IBackupCode>,
-    backupCode: string,
-  ): { newCodesArray: Array<IBackupCode>; code: IBackupCode } {
-    const normalizedCode = BackupCode.normalizeCode(backupCode);
-    if (!AppConstants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
-      throw new InvalidBackupCodeError();
-    }
-    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)
-        ) {
-          const checksumHex = expected.toString('hex');
-          return {
-            newCodesArray: encryptedBackupCodes.filter(
-              (c) => c.checksum !== checksumHex,
-            ),
-            code,
-          };
-        }
-      }
-      throw new InvalidBackupCodeError();
-    } finally {
-      codeBytes.fill(0);
-    }
-  }
-
-  /**
-   * Consume a backup code by first detecting the version and then dispatching to the appropriate handler.
-   */
-  public useBackupCode(
-    encryptedBackupCodes: Array<IBackupCode>,
-    backupCode: string,
-  ): { newCodesArray: Array<IBackupCode>; code: IBackupCode } {
-    const version = BackupCode.detectBackupCodeVersion(
-      encryptedBackupCodes,
-      backupCode,
-    );
-    switch (version) {
-      case BackupCode.BackupCodeVersion:
-        return this.useBackupCodeV1(
-          encryptedBackupCodes.filter(
-            (c) => c.version === BackupCode.BackupCodeVersion,
-          ),
-          backupCode,
-        );
-      default:
-        throw new InvalidBackupCodeVersionError(version);
-    }
-  }
-
-  /**
-   * v1: Recover a user's private key using a backup code.
-   */
-  public async recoverKeyWithBackupCodeV1(
-    userDoc: IUserDocument<string, I>,
-    backupCode: string,
-    newPassword?: SecureString,
-    session?: ClientSession,
-  ): Promise<{
-    userDoc: IUserDocument<string, I>;
-    user: BackendMember<I>;
-    codeCount: number;
-  }> {
-    const normalizedCode = BackupCode.normalizeCode(backupCode);
-    return await this.withTransaction<{
-      userDoc: IUserDocument<string, I>;
-      user: BackendMember<I>;
-      codeCount: number;
-    }>(
-      async (sess: ClientSession | undefined) => {
-        const { code, newCodesArray } = this.useBackupCodeV1(
-          userDoc.backupCodes,
-          normalizedCode,
-        );
-        userDoc.backupCodes = newCodesArray;
-
-        let decryptionKey: Buffer | undefined;
-        try {
-          const adminMember = this.getSystemUser();
-          decryptionKey = await BackupCode.getBackupKeyV1(
-            code.checksumSalt,
-            normalizedCode,
-            this.application.constants,
-          );
-          const privateKeyUnwrapped = adminMember.decryptData(
-            Buffer.from(code.encrypted, 'hex'),
-          );
-          const decryptedPrivateKey = new SecureBuffer(
-            SymmetricService.decryptBuffer(privateKeyUnwrapped, decryptionKey),
-          );
-
-          const memberType: MemberType = await this.roleService.getMemberType(
-            userDoc,
-            session,
-          );
-          const user = new BackendMember(
-            this.eciesService,
-            memberType,
-            userDoc.username,
-            new EmailString(userDoc.email),
-            Buffer.from(userDoc.publicKey, 'hex'),
-            decryptedPrivateKey,
-            undefined,
-            userDoc._id,
-            new Date(userDoc.createdAt),
-            new Date(userDoc.updatedAt),
-          );
-
-          if (!newPassword) {
-            await userDoc.save({ session: sess });
-            return {
-              userDoc,
-              user,
-              codeCount: newCodesArray.length,
-            };
-          }
-
-          const wrapped = this.keyWrappingService.wrapSecret(
-            decryptedPrivateKey,
-            newPassword,
-            this.application.constants,
-          );
-          userDoc.passwordWrappedPrivateKey = wrapped;
-          await userDoc.save({ session: sess });
-          return { userDoc, user, codeCount: newCodesArray.length };
-        } finally {
-          if (decryptionKey) decryptionKey.fill(0);
-        }
-      },
-      session,
-      {
-        timeoutMs: this.application.environment.mongo.transactionTimeout * 5,
-      },
-    );
-  }
-
-  /**
-   * Recover a user's private key using a backup code (version-dispatched).
-   */
-  public async recoverKeyWithBackupCode(
-    userDoc: IUserDocument<string, I>,
-    backupCode: string,
-    newPassword?: SecureString,
-    session?: ClientSession,
-  ): Promise<{
-    userDoc: IUserDocument<string, I>;
-    user: BackendMember<I>;
-    codeCount: number;
-  }> {
-    const version = BackupCode.detectBackupCodeVersion(
-      userDoc.backupCodes,
-      backupCode,
-    );
-    switch (version) {
-      case BackupCode.BackupCodeVersion:
-        return this.recoverKeyWithBackupCodeV1(
-          userDoc,
-          backupCode,
-          newPassword,
-          session,
-        );
-      default:
-        throw new InvalidBackupCodeVersionError(version);
-    }
-  }
-
-  /**
-   * Rewrap system-wrapped AEAD blobs from old system key to new one without touching inner AEAD.
-   */
-  public async rewrapAllUsersBackupCodes(
-    fetchBatch: (
-      afterId?: string,
-      limit?: number,
-    ) => Promise<IUserDocument<string, I>[]>,
-    saveUser: (user: IUserDocument<string, I>) => Promise<void>,
-    oldSystem: BackendMember,
-    newSystem: BackendMember,
-    options?: { batchSize?: number; onProgress?: (count: number) => void },
-  ): Promise<number> {
-    const batchSize = options?.batchSize ?? 500;
-    let processed = 0;
-    let afterId: string | undefined;
-
-    for (;;) {
-      const users = await fetchBatch(afterId, batchSize);
-      if (!users.length) break;
-
-      for (const user of users) {
-        let modified = false;
-        for (const bc of user.backupCodes ?? []) {
-          try {
-            const sealed = oldSystem.decryptData(
-              Buffer.from(bc.encrypted, 'hex'),
-            );
-            const rewrapped = newSystem.encryptData(sealed).toString('hex');
-            if (rewrapped !== bc.encrypted) {
-              bc.encrypted = rewrapped;
-              modified = true;
-            }
-          } catch (e) {
-            throw new Error(
-              `Failed to rewrap backup code for user ${user._id}: ${
-                (e as Error).message
-              }`,
-            );
-          }
-        }
-        if (modified) {
-          await saveUser(user);
-          processed++;
-          options?.onProgress?.(processed);
-        }
-      }
-
-      afterId = users[users.length - 1]?._id?.toString() ?? undefined;
-    }
-    return processed;
-  }
-}

package/src/services/base.ts

@@ -1,30 +0,0 @@
-import { ClientSession } from '@digitaldefiance/mongoose-types';
-import { IApplication } from '../interfaces/application';
-import { TransactionCallback } from '../types';
-import {
-  TransactionOptions,
-  withTransaction as utilsWithTransaction,
-} from '../utils';
-
-export class BaseService<TApplication extends IApplication = IApplication> {
-  protected readonly application: TApplication;
-
-  constructor(application: TApplication) {
-    this.application = application;
-  }
-  public async withTransaction<T>(
-    callback: TransactionCallback<T>,
-    session?: ClientSession,
-    options?: TransactionOptions,
-    ...args: unknown[]
-  ) {
-    return await utilsWithTransaction<T>(
-      this.application.db.connection,
-      this.application.environment.mongo.useTransactions,
-      session,
-      callback,
-      options ?? {},
-      ...args,
-    );
-  }
-}

package/src/services/checksum.ts

@@ -1,167 +0,0 @@
-import {
-  ChecksumBuffer,
-  ChecksumString,
-} from '@digitaldefiance/node-ecies-lib';
-import { createHash } from 'crypto';
-import { promises as fs } from 'fs';
-import { CHECKSUM } from '../constants';
-import { IChecksumConfig } from '../interfaces/checksum-config';
-import { IChecksumConsts } from '../interfaces/checksum-consts';
-
-export class ChecksumService {
-  private readonly config: IChecksumConfig;
-  protected readonly constants: IChecksumConsts;
-
-  constructor(
-    config?: Partial<IChecksumConfig>,
-    constants: IChecksumConsts = CHECKSUM,
-  ) {
-    this.config = {
-      algorithm: constants.ALGORITHM,
-      encoding: constants.ENCODING,
-      ...config,
-    };
-    this.constants = constants;
-  }
-
-  /**
-   * Calculate a checksum for a buffer
-   * @param data - The data to calculate the checksum for
-   * @returns The checksum as a Buffer
-   */
-  public calculateChecksum(data: Buffer): ChecksumBuffer {
-    const hash = createHash(this.config.algorithm);
-    hash.update(new Uint8Array(data));
-    const digest = hash.digest();
-    return Buffer.from(digest) as ChecksumBuffer;
-  }
-
-  /**
-   * Calculate a checksum for multiple buffers
-   * @param buffers - The buffers to calculate the checksum for
-   * @returns The checksum as a Buffer
-   */
-  public calculateChecksumForBuffers(buffers: Buffer[]): ChecksumBuffer {
-    const hash = createHash(this.config.algorithm);
-    for (const buffer of buffers) {
-      hash.update(new Uint8Array(buffer));
-    }
-    const digest = hash.digest();
-    return Buffer.from(digest) as ChecksumBuffer;
-  }
-
-  /**
-   * Calculate a checksum for a string
-   * @param str - The string to calculate the checksum for
-   * @returns The checksum as a Buffer
-   */
-  public calculateChecksumForString(str: string): ChecksumBuffer {
-    return this.calculateChecksum(Buffer.from(str, 'utf8'));
-  }
-
-  /**
-   * Compare two checksums for equality
-   * @param checksum1 - The first checksum
-   * @param checksum2 - The second checksum
-   * @returns True if the checksums are equal, false otherwise
-   */
-  public compareChecksums(
-    checksum1: ChecksumBuffer,
-    checksum2: ChecksumBuffer,
-  ): boolean {
-    if (
-      checksum1.length !== this.constants.SHA3_BUFFER_LENGTH ||
-      checksum2.length !== this.constants.SHA3_BUFFER_LENGTH
-    ) {
-      return false;
-    }
-    return checksum1.equals(new Uint8Array(checksum2));
-  }
-
-  /**
-   * Convert a checksum to a hex string
-   * @param checksum - The checksum to convert
-   * @returns The checksum as a hex string
-   */
-  public checksumToHexString(checksum: ChecksumBuffer): ChecksumString {
-    return checksum.toString(this.constants.ENCODING) as ChecksumString;
-  }
-
-  /**
-   * Convert a hex string to a checksum
-   * @param hexString - The hex string to convert
-   * @returns The checksum as a Buffer
-   */
-  public hexStringToChecksum(hexString: string): ChecksumBuffer {
-    if (hexString.length !== this.constants.SHA3_BUFFER_LENGTH * 2) {
-      throw new Error('Invalid checksum hex string length');
-    }
-    return Buffer.from(hexString, this.constants.ENCODING) as ChecksumBuffer;
-  }
-
-  /**
-   * Validate a checksum buffer
-   * @param checksum - The checksum to validate
-   * @returns True if the checksum is valid, false otherwise
-   */
-  public validateChecksum(checksum: ChecksumBuffer): boolean {
-    return checksum.length === this.constants.SHA3_BUFFER_LENGTH;
-  }
-
-  /**
-   * Calculate a checksum for a file
-   * @param filePath - The path to the file
-   * @returns The checksum as a Buffer
-   */
-  public async calculateChecksumForFile(
-    filePath: string,
-  ): Promise<ChecksumBuffer> {
-    // Removed dynamic import by using the data service to read file data
-    // This is a temporary solution that can be replaced with a proper file service
-    // The implementation now delegates file reading to the caller
-    const buffer = Buffer.from(await this.readFile(filePath));
-    return this.calculateChecksum(buffer);
-  }
-
-  /**
-   * Internal file reading method
-   * @private
-   */
-  private async readFile(filePath: string): Promise<Buffer> {
-    // Import fs using a static import that's available at module load time
-    // This solves the dynamic import/require issues
-    try {
-      return await fs.readFile(filePath);
-    } catch {
-      throw new Error(`Failed to read file at path: ${filePath}`);
-    }
-  }
-
-  /**
-   * Calculate a checksum for a stream
-   * @param stream - The readable stream
-   * @returns The checksum as a Buffer
-   */
-  public calculateChecksumForStream(
-    stream: NodeJS.ReadableStream,
-  ): Promise<ChecksumBuffer> {
-    return new Promise((resolve, reject) => {
-      const hash = createHash(this.config.algorithm);
-      stream.on('data', (chunk) => {
-        // Ensure chunk is a Buffer before updating hash
-        if (Buffer.isBuffer(chunk)) {
-          hash.update(new Uint8Array(chunk));
-        } else if (typeof chunk === 'number') {
-          hash.update(new Uint8Array(Buffer.from([chunk])));
-        } else {
-          hash.update(new Uint8Array(Buffer.from(chunk)));
-        }
-      });
-      stream.on('end', () => {
-        const digest = hash.digest();
-        resolve(Buffer.from(digest) as ChecksumBuffer);
-      });
-      stream.on('error', reject);
-    });
-  }
-}