@digitaldefiance/node-express-suite 1.0.22 → 1.0.23

package/src/services/backup-code.ts

@@ -0,0 +1,316 @@
+import {
+  EmailString,
+  MemberType,
+  SecureBuffer,
+  SecureString,
+} from '@digitaldefiance/ecies-lib';
+import {
+  Member as BackendMember,
+  ECIESService,
+} from '@digitaldefiance/node-ecies-lib';
+import {
+  IBackupCode,
+  InvalidBackupCodeError,
+  ITokenRole,
+} from '@digitaldefiance/suite-core-lib';
+import { timingSafeEqual } from 'crypto';
+import { ClientSession, Types } from 'mongoose';
+import { BackupCode } from '../backup-code';
+import { Constants as AppConstants } from '../constants';
+import { IBaseDocument, 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';
+import { Environment } from '../environment';
+import { IConstants } from '../interfaces';
+
+/**
+ * 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 = Types.ObjectId,
+  D extends Date = Date,
+  TTokenRole extends ITokenRole<I, D> = ITokenRole<I, D>,
+  TApplication extends IApplication<any, Types.ObjectId, IBaseDocument<any, Types.ObjectId>, Environment, IConstants> = IApplication<any, Types.ObjectId, IBaseDocument<any, Types.ObjectId>, Environment, IConstants>,
+> extends BaseService {
+  private readonly eciesService: ECIESService;
+  private systemUser?: BackendMember;
+  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 {
+    if (!this.systemUser) {
+      this.systemUser = SystemUserService.getSystemUser(
+        this.application.environment,
+      );
+    }
+    return this.systemUser;
+  }
+
+  /**
+   * Forcibly set the system user (for database initialization)
+   * @param user
+   */
+  public setSystemUser(user: BackendMember): 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,
+    backupCode: string,
+    newPassword?: SecureString,
+    session?: ClientSession,
+  ): Promise<{
+    userDoc: IUserDocument;
+    user: BackendMember;
+    codeCount: number;
+  }> {
+    const normalizedCode = BackupCode.normalizeCode(backupCode);
+    return await this.withTransaction<{
+      userDoc: IUserDocument;
+      user: BackendMember;
+      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,
+          );
+          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,
+          );
+          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,
+    backupCode: string,
+    newPassword?: SecureString,
+    session?: ClientSession,
+  ): Promise<{
+    userDoc: IUserDocument;
+    user: BackendMember;
+    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[]>,
+    saveUser: (user: IUserDocument) => 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 as unknown as string) ?? undefined;
+    }
+    return processed;
+  }
+}

package/src/services/base.ts

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

package/src/services/checksum.ts

@@ -0,0 +1,161 @@
+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';
+
+export class ChecksumService {
+  private readonly config: IChecksumConfig;
+
+  constructor(config?: Partial<IChecksumConfig>) {
+    this.config = {
+      algorithm: CHECKSUM.ALGORITHM,
+      encoding: CHECKSUM.ENCODING,
+      ...config,
+    };
+  }
+
+  /**
+   * 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(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(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 !== CHECKSUM.SHA3_BUFFER_LENGTH ||
+      checksum2.length !== CHECKSUM.SHA3_BUFFER_LENGTH
+    ) {
+      return false;
+    }
+    return checksum1.equals(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(CHECKSUM.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 !== CHECKSUM.SHA3_BUFFER_LENGTH * 2) {
+      throw new Error('Invalid checksum hex string length');
+    }
+    return Buffer.from(hexString, CHECKSUM.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 === CHECKSUM.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(chunk);
+        } else if (typeof chunk === 'number') {
+          hash.update(Buffer.from([chunk]));
+        } else {
+          hash.update(Buffer.from(chunk));
+        }
+      });
+      stream.on('end', () => {
+        const digest = hash.digest();
+        resolve(Buffer.from(digest) as ChecksumBuffer);
+      });
+      stream.on('error', reject);
+    });
+  }
+}