@digitaldefiance/node-express-suite 3.7.3 → 3.7.5

package/src/schemas/user.ts

@@ -0,0 +1,244 @@
+/**
+ * @fileoverview User schema factory for MongoDB with comprehensive validation.
+ * Creates schema for user management with authentication and preferences.
+ * @module schemas/user
+ */
+
+import { isValidTimezone, LanguageCodes } from '@digitaldefiance/i18n-lib';
+import { Schema } from '@digitaldefiance/mongoose-types';
+import {
+  AccountStatus,
+  getSuiteCoreTranslation,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { codes } from 'currency-codes';
+import validator from 'validator';
+import { LocalhostConstants as AppConstants } from '../constants';
+import { BaseModelName } from '../enumerations';
+import { IConstants } from '../interfaces/constants';
+
+/**
+ * Creates a user schema with custom or default constants.
+ * Includes validation for username, email, timezone, currency, and language.
+ * @template T - Constants type extending IConstants
+ * @param {Function} [usernameValidationMessage] - Custom username validation message
+ * @param {Function} [emailValidationMessage] - Custom email validation message
+ * @param {Function} [timezoneValidationMessage] - Custom timezone validation message
+ * @param {Function} [currencyValidationMessage] - Custom currency validation message
+ * @param {readonly string[]} [supportedLanguages] - Supported language codes
+ * @param {any} idType - ID type for references (defaults to ObjectId)
+ * @param {T} constants - Constants for validation (defaults to AppConstants)
+ * @returns {Schema} Configured user schema with timestamps
+ */
+export function createUserSchema<T extends IConstants = IConstants>(
+  usernameValidationMessage?: () => string,
+  emailValidationMessage?: () => string,
+  timezoneValidationMessage?: () => string,
+  currencyValidationMessage?: () => string,
+  supportedLanguages?: readonly string[],
+  idType: any = Schema.Types.ObjectId,
+  constants: T = AppConstants as T,
+): Schema {
+  const definition = {
+    /**
+     * The unique identifier for the user
+     */
+    username: {
+      type: String,
+      required: true,
+      unique: true,
+      validate: {
+        validator: (v: string) => constants.UsernameRegex.test(v),
+        message:
+          usernameValidationMessage ||
+          (() =>
+            getSuiteCoreTranslation(
+              SuiteCoreStringKey.Validation_UsernameRegexErrorTemplate,
+            )),
+      },
+    },
+    /**
+     * The email address for the user
+     */
+    email: {
+      type: String,
+      required: true,
+      unique: true,
+      validate: {
+        validator: (v: string) => validator.isEmail(v),
+        message:
+          emailValidationMessage ||
+          ((props: { value: string }) =>
+            getSuiteCoreTranslation(
+              SuiteCoreStringKey.Error_InvalidEmailTemplate,
+              { email: props.value },
+            )),
+      },
+    },
+    /**
+     * The user's public key, stored in hex format.
+     */
+    publicKey: {
+      type: String,
+      required: true,
+      unique: true,
+    },
+    /**
+     * The timezone for the user
+     */
+    timezone: {
+      type: String,
+      required: true,
+      default: 'UTC',
+      validate: {
+        validator: function (v: string) {
+          return isValidTimezone(v);
+        },
+        message:
+          timezoneValidationMessage ||
+          ((props: { value: string }) =>
+            getSuiteCoreTranslation(
+              SuiteCoreStringKey.Common_NotValidTimeZoneTemplate,
+              { timezone: props.value },
+            )),
+      },
+    },
+    currency: {
+      type: String,
+      required: true,
+      default: 'USD',
+      validate: {
+        validator: function (v: string) {
+          return codes().includes(v);
+        },
+        message:
+          currencyValidationMessage ||
+          ((props: { value: string }) =>
+            getSuiteCoreTranslation(
+              SuiteCoreStringKey.Common_NotValidCurrencyTemplate,
+              { currency: props.value },
+            )),
+      },
+    },
+    /**
+     * The language of the site for the user
+     */
+    siteLanguage: {
+      type: String,
+      enum: supportedLanguages || Object.values(LanguageCodes),
+      default: LanguageCodes.EN_US,
+      required: true,
+    },
+    /**
+     * Whether the user prefers dark mode
+     */
+    darkMode: {
+      type: Boolean,
+      default: false,
+      required: true,
+    },
+    /**
+     * Whether to enable direct challenge login for the user
+     */
+    directChallenge: {
+      type: Boolean,
+      default: true,
+      required: true,
+    },
+    /**
+     * The date the user last logged in
+     */
+    lastLogin: { type: Date, required: false },
+    /**
+     * Whether the user has verified their email address
+     */
+    emailVerified: { type: Boolean, default: false },
+    /**
+     * The status of the user's account
+     */
+    accountStatus: {
+      type: String,
+      enum: Object.values(AccountStatus),
+      default: AccountStatus.PendingEmailVerification,
+    },
+    /**
+     * The user who created the user.
+     */
+    createdBy: {
+      type: idType,
+      ref: BaseModelName.User,
+      required: true,
+      immutable: true,
+    },
+    /**
+     * The user who last updated the user.
+     */
+    updatedBy: {
+      type: idType,
+      ref: BaseModelName.User,
+      optional: true,
+    },
+    /**
+     * The date/time the user was deleted.
+     */
+    deletedAt: { type: Date, optional: true },
+    /**
+     * The user who deleted the user.
+     */
+    deletedBy: {
+      type: idType,
+      ref: BaseModelName.User,
+      optional: true,
+    },
+    /**
+     * Reference to the mnemonic document
+     */
+    mnemonicId: {
+      type: idType,
+      ref: BaseModelName.Mnemonic,
+      required: false,
+    },
+    /**
+     * Copy of the mnemonic encrypted with the user's public key
+     */
+    mnemonicRecovery: {
+      type: String,
+      required: false,
+    },
+    /**
+     * Password-wrapped ECIES private key (Option B)
+     */
+    passwordWrappedPrivateKey: {
+      type: {
+        salt: { type: String, required: true },
+        iv: { type: String, required: true },
+        authTag: { type: String, required: true },
+        ciphertext: { type: String, required: true },
+        iterations: { type: Number, required: true },
+      },
+      required: false,
+    },
+    /**
+     * Array of backup codes to recover mnemonic/private key
+     */
+    backupCodes: {
+      type: [
+        {
+          version: { type: String, required: true },
+          checksumSalt: { type: String, required: true },
+          checksum: { type: String, required: true },
+          encrypted: { type: String, required: true },
+        },
+      ],
+      default: [],
+    },
+  };
+
+  return new Schema(definition, { timestamps: true });
+}
+
+/**
+ * Default user schema with base configuration.
+ * Pre-configured schema with standard validation and supported languages.
+ */
+export const UserSchema = createUserSchema();

package/src/services/backup-code.ts

@@ -0,0 +1,327 @@
+/**
+ * @fileoverview Backup code service for secure account recovery.
+ * Implements v1.0.0 backup code scheme with Argon2id KDF and HKDF-SHA256 checksums.
+ * @module services/backup-code
+ */
+
+import {
+  EmailString,
+  MemberType,
+  SecureBuffer,
+  SecureString,
+} from '@digitaldefiance/ecies-lib';
+import { ClientSession } from '@digitaldefiance/mongoose-types';
+import {
+  Member as BackendMember,
+  ECIESService,
+  PlatformID,
+} 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 for backup code generation, validation, and key recovery.
+ * Implements secure backup code scheme with constant-time validation and key wrapping.
+ * @template TID - Platform ID type (defaults to Buffer)
+ * @template TDate - Date type (defaults to Date)
+ * @template TTokenRole - Token role interface type
+ * @template TApplication - Application interface type
+ * @extends {BaseService<TID>}
+ */
+export class BackupCodeService<
+  TID extends PlatformID = Buffer,
+  TDate extends Date = Date,
+  TTokenRole extends ITokenRole<TID, TDate> = ITokenRole<TID, TDate>,
+  TApplication extends IApplication<TID> = IApplication<TID>,
+> extends BaseService<TID> {
+  private readonly eciesService: ECIESService<TID>;
+  private systemUser?: BackendMember<TID>;
+  private readonly keyWrappingService: KeyWrappingService;
+  private readonly roleService: RoleService<TID, TDate, TTokenRole>;
+
+  /**
+   * Construct a BackupCodeService.
+   */
+  constructor(
+    application: TApplication,
+    eciesService: ECIESService<TID>,
+    keyWrappingService: KeyWrappingService,
+    roleService: RoleService<TID, TDate, 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<TID> {
+    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<TID>;
+    }
+    return this.systemUser;
+  }
+
+  /**
+   * Forcibly set the system user (for database initialization)
+   * @param user
+   */
+  public setSystemUser(user: BackendMember<TID>): 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, TID>,
+    backupCode: string,
+    newPassword?: SecureString,
+    session?: ClientSession,
+  ): Promise<{
+    userDoc: IUserDocument<string, TID>;
+    user: BackendMember<TID>;
+    codeCount: number;
+  }> {
+    const normalizedCode = BackupCode.normalizeCode(backupCode);
+    return await this.withTransaction<{
+      userDoc: IUserDocument<string, TID>;
+      user: BackendMember<TID>;
+      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, TID>,
+    backupCode: string,
+    newPassword?: SecureString,
+    session?: ClientSession,
+  ): Promise<{
+    userDoc: IUserDocument<string, TID>;
+    user: BackendMember<TID>;
+    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, TID>[]>,
+    saveUser: (user: IUserDocument<string, TID>) => 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

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Base service class providing common functionality for all services.
+ * Includes transaction management utilities.
+ * @module services/base
+ */
+
+import { ClientSession } from '@digitaldefiance/mongoose-types';
+import { IApplication } from '../interfaces/application';
+import { TransactionCallback } from '../types';
+import {
+  TransactionOptions,
+  withTransaction as utilsWithTransaction,
+} from '../utils';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Base service class providing common functionality for all services.
+ * Includes transaction wrapper for database operations.
+ * @template TID - Platform ID type (defaults to Buffer)
+ * @template TApplication - Application interface type
+ */
+export class BaseService<
+  TID extends PlatformID = Buffer,
+  TApplication extends IApplication<TID> = IApplication<TID>,
+> {
+  protected readonly application: TApplication;
+
+  constructor(application: TApplication) {
+    this.application = application;
+  }
+  public async withTransaction<T>(
+    callback: TransactionCallback<T>,
+    session?: ClientSession,
+    options?: TransactionOptions<TID>,
+    ...args: unknown[]
+  ) {
+    return await utilsWithTransaction<T, TID>(
+      this.application.db.connection,
+      this.application.environment.mongo.useTransactions,
+      session,
+      callback,
+      options ?? {},
+      ...args,
+    );
+  }
+}