@digitaldefiance/node-express-suite 3.7.5 → 3.7.6

package/src/schemas/user.ts

@@ -1,244 +0,0 @@
-/**
- * @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

@@ -1,327 +0,0 @@
-/**
- * @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

@@ -1,46 +0,0 @@
-/**
- * @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,
-    );
-  }
-}