@digitaldefiance/suite-core-lib 3.6.47 → 3.6.49

package/src/errors/system-role-not-found.ts

@@ -0,0 +1,15 @@
+/**
+ * Error thrown when the system role cannot be found in the system.
+ */
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import { SuiteCoreStringKey } from '../enumerations';
+import { TranslatableSuiteHandleableError } from './translatable-suite-handleable';
+
+export class SystemRoleNotFoundError extends TranslatableSuiteHandleableError {
+  constructor(language?: CoreLanguageCode) {
+    super(SuiteCoreStringKey.SystemRoleNotFound, undefined, language, {
+      statusCode: 500,
+    });
+    this.name = 'SystemRoleNotFoundError';
+  }
+}

package/src/errors/token-not-found.ts

@@ -0,0 +1,24 @@
+/**
+ * Error thrown when a token cannot be found.
+ */
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import { SuiteCoreStringKey } from '../enumerations';
+import { TranslatableSuiteHandleableError } from './translatable-suite-handleable';
+
+export class TokenNotFoundError extends TranslatableSuiteHandleableError {
+  public readonly token: string;
+  constructor(token: string, language?: CoreLanguageCode, statusCode = 404) {
+    super(
+      SuiteCoreStringKey.TokenNotFoundTemplate,
+      {
+        TOKEN: token,
+      },
+      language,
+      {
+        statusCode,
+      },
+    );
+    this.token = token;
+    this.name = 'TokenNotFoundError';
+  }
+}

package/src/errors/translatable-suite-handleable.ts

@@ -0,0 +1,30 @@
+/**
+ * Translatable handleable error class for suite-core library with i18n and error handling support.
+ */
+import { TranslatableHandleableGenericError } from '@digitaldefiance/i18n-lib';
+import { SuiteCoreStringKey } from '../enumerations';
+import { SuiteCoreComponentId } from '../i18n-setup';
+
+export class TranslatableSuiteHandleableError extends TranslatableHandleableGenericError<SuiteCoreStringKey> {
+  constructor(
+    messageKey: SuiteCoreStringKey,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+    handleableOptions?: {
+      statusCode?: number;
+      cause?: Error;
+      sourceData?: unknown;
+    },
+  ) {
+    super(
+      SuiteCoreComponentId,
+      messageKey,
+      otherVars,
+      language,
+      undefined, // metadata
+      'default', // instanceKey
+      handleableOptions,
+    );
+    this.name = 'TranslatableSuiteHandleableError';
+  }
+}

package/src/errors/translatable-suite.ts

@@ -0,0 +1,37 @@
+/**
+ * Translatable error class for suite-core library with i18n support.
+ */
+import { SuiteCoreStringKey } from '../enumerations/suite-core-string-key';
+import { getSuiteCoreI18nEngine, SuiteCoreComponentId } from '../i18n-setup';
+
+export class TranslatableSuiteError extends Error {
+  public readonly StringName: SuiteCoreStringKey;
+  /**
+   * @param string The translation key or raw string
+   * @param otherVars Variables for interpolation
+   * @param language Optional language override
+   * @param options Error options
+   * @param engine Optional i18n engine override (defaults to node-express-suite component)
+   */
+  constructor(
+    string: SuiteCoreStringKey,
+    otherVars?: Record<string, string | number>,
+    language?: string,
+  ) {
+    const i18nEngine = getSuiteCoreI18nEngine();
+    let translatedMessage: string;
+    try {
+      translatedMessage = i18nEngine.translate(
+        SuiteCoreComponentId,
+        string,
+        otherVars,
+        language,
+      );
+    } catch {
+      translatedMessage = string;
+    }
+    super(translatedMessage);
+    this.name = 'TranslatableSuiteError';
+    this.StringName = string;
+  }
+}

package/src/errors/user-not-found.ts

@@ -0,0 +1,14 @@
+/**
+ * Error thrown when a user cannot be found.
+ */
+import { SuiteCoreStringKey } from '../enumerations';
+import { TranslatableSuiteHandleableError } from './translatable-suite-handleable';
+
+export class UserNotFoundError extends TranslatableSuiteHandleableError {
+  constructor(language?: string, statusCode = 404) {
+    super(SuiteCoreStringKey.Auth_UserNotFound, undefined, language, {
+      statusCode,
+    });
+    this.name = 'UserNotFoundError';
+  }
+}

package/src/errors/username-email-required.ts

@@ -0,0 +1,23 @@
+/**
+ * Error thrown when neither username nor email is provided.
+ */
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import { SuiteCoreStringKey } from '../enumerations';
+import { getSuiteCoreTranslation } from '../i18n-setup';
+import { GenericValidationError } from './generic-validation';
+
+export class UsernameOrEmailRequiredError extends GenericValidationError {
+  constructor(language?: CoreLanguageCode, statusCode = 422) {
+    super(
+      getSuiteCoreTranslation(
+        SuiteCoreStringKey.Validation_UsernameOrEmailRequired,
+        undefined,
+        language,
+      ),
+      {
+        statusCode,
+      },
+    );
+    this.name = 'UsernameOrEmailRequiredError';
+  }
+}

package/src/errors/username-in-use.ts

@@ -0,0 +1,14 @@
+/**
+ * Error thrown when a username is already in use by another account.
+ */
+import { SuiteCoreStringKey } from '../enumerations';
+import { TranslatableSuiteHandleableError } from './translatable-suite-handleable';
+
+export class UsernameInUseError extends TranslatableSuiteHandleableError {
+  constructor(language?: string, statusCode = 422) {
+    super(SuiteCoreStringKey.Validation_UsernameInUse, undefined, language, {
+      statusCode,
+    });
+    this.name = 'UsernameInUseError';
+  }
+}

package/src/i18n-setup.ts

@@ -0,0 +1,150 @@
+/**
+ * Internationalization (i18n) setup and configuration for suite-core library.
+ * Manages i18n engine initialization, component registration, and translation string loading
+ * across 8 supported languages (en-US, en-GB, fr, de, es, zh-CN, ja, uk).
+ */
+import {
+  ComponentConfig,
+  ComponentDefinition,
+  CoreLanguageCode,
+  createDefaultLanguages,
+  EngineConfig,
+  I18nEngine,
+  LanguageCodes,
+} from '@digitaldefiance/i18n-lib';
+import { Role } from './enumerations/role';
+import { SuiteCoreStringKey } from './enumerations/suite-core-string-key';
+import { germanStrings } from './strings/de';
+import { britishEnglishStrings } from './strings/en-GB';
+import { americanEnglishStrings } from './strings/en-US';
+import { spanishStrings } from './strings/es';
+import { frenchStrings } from './strings/fr';
+import { japaneseStrings } from './strings/ja';
+import { ukrainianStrings } from './strings/uk';
+import { mandarinStrings } from './strings/zh-CN';
+
+export const SuiteCoreI18nEngineKey = 'default' as const;
+export const SuiteCoreComponentId = 'suite-core' as const;
+export const SuiteCoreComponent: ComponentDefinition<SuiteCoreStringKey> = {
+  id: SuiteCoreComponentId,
+  name: 'Suite Core Library Component',
+  stringKeys: Object.values(SuiteCoreStringKey),
+};
+export const SuiteCoreComponentStrings: Record<
+  string,
+  Record<SuiteCoreStringKey, string>
+> = {
+  [LanguageCodes.EN_US]: americanEnglishStrings,
+  [LanguageCodes.EN_GB]: britishEnglishStrings,
+  [LanguageCodes.FR]: frenchStrings,
+  [LanguageCodes.DE]: germanStrings,
+  [LanguageCodes.ES]: spanishStrings,
+  [LanguageCodes.ZH_CN]: mandarinStrings,
+  [LanguageCodes.JA]: japaneseStrings,
+  [LanguageCodes.UK]: ukrainianStrings,
+};
+
+const roleTranslations: Record<CoreLanguageCode, Record<Role, string>> = {
+  [LanguageCodes.EN_US]: {
+    [Role.Admin]: 'Administrator',
+    [Role.Member]: 'Member',
+    [Role.System]: 'System',
+  },
+  [LanguageCodes.EN_GB]: {
+    [Role.Admin]: 'Administrator',
+    [Role.Member]: 'Member',
+    [Role.System]: 'System',
+  },
+  [LanguageCodes.FR]: {
+    [Role.Admin]: 'Administrateur',
+    [Role.Member]: 'Membre',
+    [Role.System]: 'Système',
+  },
+  [LanguageCodes.ES]: {
+    [Role.Admin]: 'Administrador',
+    [Role.Member]: 'Miembro',
+    [Role.System]: 'Sistema',
+  },
+  [LanguageCodes.DE]: {
+    [Role.Admin]: 'Administrator',
+    [Role.Member]: 'Mitglied',
+    [Role.System]: 'System',
+  },
+  [LanguageCodes.ZH_CN]: {
+    [Role.Admin]: '管理员',
+    [Role.Member]: '成员',
+    [Role.System]: '系统',
+  },
+  [LanguageCodes.JA]: {
+    [Role.Admin]: '管理者',
+    [Role.Member]: 'メンバー',
+    [Role.System]: 'システム',
+  },
+  [LanguageCodes.UK]: {
+    [Role.Admin]: 'Адміністратор',
+    [Role.Member]: 'Учасник',
+    [Role.System]: 'Система',
+  },
+};
+
+// Suite Core component config
+export function createSuiteCoreComponentConfig(): ComponentConfig {
+  const SuiteCoreComponentConfig: ComponentConfig = {
+    id: SuiteCoreComponentId,
+    strings: SuiteCoreComponentStrings,
+    aliases: ['SuiteCoreStringKey'],
+  };
+  return SuiteCoreComponentConfig;
+}
+
+let _engine: I18nEngine | undefined;
+
+export function getSuiteCoreI18nEngine(config?: EngineConfig): I18nEngine {
+  if (!_engine || !I18nEngine.hasInstance(SuiteCoreI18nEngineKey)) {
+    _engine = I18nEngine.registerIfNotExists(
+      SuiteCoreI18nEngineKey,
+      createDefaultLanguages(),
+      { defaultLanguage: LanguageCodes.EN_US, ...config },
+    );
+
+    _engine.registerIfNotExists(createSuiteCoreComponentConfig());
+    _engine.registerEnum(Role, roleTranslations, 'Role');
+  }
+  return _engine;
+}
+
+export function getSuiteCoreTranslation(
+  key: SuiteCoreStringKey,
+  variables?: Record<string, unknown>,
+  language?: string,
+  config?: EngineConfig,
+): string {
+  return getSuiteCoreI18nEngine(config).translate(
+    SuiteCoreComponentId,
+    key,
+    variables,
+    language,
+  );
+}
+
+export function resetSuiteCoreI18nEngine(): void {
+  I18nEngine.removeInstance(SuiteCoreI18nEngineKey);
+  _engine = undefined;
+}
+
+export function initSuiteCoreI18nEngine(config?: EngineConfig): I18nEngine {
+  return getSuiteCoreI18nEngine(config);
+}
+
+export function safeGetSuiteCoreTranslation(
+  key: SuiteCoreStringKey,
+  variables?: Record<string, unknown>,
+  language?: string,
+  config?: EngineConfig,
+): string {
+  try {
+    return getSuiteCoreTranslation(key, variables, language, config);
+  } catch {
+    return key;
+  }
+}

package/src/{index.d.ts → index.ts}

@@ -1,3 +1,7 @@
+/**
+ * Main entry point for the suite-core library.
+ * Exports all public APIs including builders, constants, enumerations, errors, interfaces, and utilities.
+ */
 export * from './backup-code-string';
 export * from './builders';
 export * from './constants';
@@ -9,4 +13,3 @@ export * from './i18n-setup';
 export * from './interfaces';
 export * from './lib';
 export * from './local-storage-manager';
-//# sourceMappingURL=index.d.ts.map

package/src/interfaces/backup-code-consts.ts

@@ -0,0 +1,18 @@
+/**
+ * Backup code constants interface.
+ */
+export interface IBackupCodeConstants {
+  /**
+   * How many backup codes to generate for users
+   */
+  Count: number;
+  /**
+   * Regex for the backup codes
+   * 32 lowercase alphanumeric character string (a-z0-9)
+   */
+  NormalizedHexRegex: RegExp;
+  /**
+   * Regex for the display format of the backup codes
+   */
+  DisplayRegex: RegExp; // xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx
+}

package/src/interfaces/backup-code.ts

@@ -0,0 +1,9 @@
+/**
+ * Backup code structure with encryption and checksum data.
+ */
+export interface IBackupCode {
+  version: string;
+  checksumSalt: string;
+  checksum: string;
+  encrypted: string;
+}

package/src/interfaces/bases/email-token.ts

@@ -0,0 +1,39 @@
+import type { PlatformID } from '@digitaldefiance/ecies-lib';
+import { EmailTokenType } from '../../enumerations/email-token-type';
+import { IHasId } from '../has-id';
+import { IHasTimestamps } from '../has-timestamps';
+
+/**
+ * Base interface for email token collection documents
+ */
+export interface IEmailTokenBase<
+  TID extends PlatformID,
+  TDate extends Date | string,
+  TEmailTokenType extends EmailTokenType | string,
+>
+  extends IHasId<TID>, IHasTimestamps<TDate> {
+  /**
+   * The user ID associated with the token
+   */
+  userId: TID;
+  /**
+   * The type of token
+   */
+  type: TEmailTokenType;
+  /**
+   * The token value
+   */
+  token: string;
+  /**
+   * The email address the token was sent to
+   */
+  email: string;
+  /**
+   * The date the token was last sent
+   */
+  lastSent?: TDate;
+  /**
+   * The date the token expires
+   */
+  expiresAt: TDate;
+}

package/src/interfaces/bases/{index.d.ts → index.ts}

@@ -1,3 +1,6 @@
+/**
+ * Base interface exports for domain models.
+ */
 export * from './email-token';
 export * from './mnemonic';
 export * from './role';
@@ -5,4 +8,3 @@ export * from './token-role';
 export * from './used-direct-login-token';
 export * from './user';
 export * from './user-role';
-//# sourceMappingURL=index.d.ts.map

package/src/interfaces/bases/mnemonic.ts

@@ -0,0 +1,12 @@
+import type { PlatformID } from '@digitaldefiance/ecies-lib';
+import { IHasId } from '../has-id';
+
+/**
+ * Represents a mnemonic hash being stored to check for uniqueness
+ */
+export interface IMnemonicBase<TID extends PlatformID> extends IHasId<TID> {
+  /**
+   * A non-reversible HMAC of the mnemonic, used for uniqueness checks.
+   */
+  hmac: string;
+}

package/src/interfaces/bases/role.ts

@@ -0,0 +1,43 @@
+import type { PlatformID } from '@digitaldefiance/ecies-lib';
+import { Role } from '../../enumerations/role';
+import { IHasId } from '../has-id';
+import { IHasSoftDelete } from '../has-soft-delete';
+import { IHasSoftDeleter } from '../has-soft-deleter';
+import { IHasTimestampOwners } from '../has-timestamp-owners';
+import { IHasTimestamps } from '../has-timestamps';
+
+export interface IRoleBase<
+  TID extends PlatformID,
+  TDate extends Date | string = Date,
+  TRole extends Role | string = Role,
+>
+  extends
+    IHasId<TID>,
+    IHasTimestamps<TDate>,
+    IHasTimestampOwners<TID>,
+    IHasSoftDelete<TDate>,
+    IHasSoftDeleter<TID> {
+  /**
+   * The name of the role
+   */
+  name: TRole;
+  /**
+   * Whether the role is an admin
+   */
+  admin: boolean;
+  /**
+   * Whether the role is a site member
+   * Must not specify admin or system
+   */
+  member: boolean;
+  /**
+   * Whether the role is a restricted child account
+   * This prevents the account from certain actions
+   * Must not specify admin, member,
+   */
+  child: boolean;
+  /**
+   * Whether the role is a system account
+   */
+  system: boolean;
+}

package/src/interfaces/bases/token-role.ts

@@ -0,0 +1,16 @@
+/**
+ * Token role base interface.
+ * Extended role interface with translated name for JWT token payloads.
+ */
+import type { PlatformID } from '@digitaldefiance/ecies-lib';
+import { IRoleBase } from './role';
+
+export interface ITokenRole<
+  TID extends PlatformID,
+  TDate extends Date | string = Date,
+> extends IRoleBase<TID, TDate> {
+  /**
+   * The translated name of the role
+   */
+  translatedName: string;
+}

package/src/interfaces/bases/used-direct-login-token.ts

@@ -0,0 +1,19 @@
+/**
+ * Used direct login token base interface.
+ * Tracks tokens that have been used for direct login to prevent replay attacks.
+ */
+import type { PlatformID } from '@digitaldefiance/ecies-lib';
+import { IHasId } from '../has-id';
+
+export interface IUsedDirectLoginTokenBase<
+  TID extends PlatformID,
+> extends IHasId<TID> {
+  /**
+   * The user ID associated with the token
+   */
+  userId: TID;
+  /**
+   * The token value that was used
+   */
+  token: string;
+}

package/src/interfaces/bases/user-role.ts

@@ -0,0 +1,26 @@
+import type { PlatformID } from '@digitaldefiance/ecies-lib';
+import { IHasId } from '../has-id';
+import { IHasSoftDelete } from '../has-soft-delete';
+import { IHasSoftDeleter } from '../has-soft-deleter';
+import { IHasTimestampOwners } from '../has-timestamp-owners';
+import { IHasTimestamps } from '../has-timestamps';
+
+export interface IUserRoleBase<
+  TID extends PlatformID,
+  TDate extends Date | string,
+>
+  extends
+    IHasId<TID>,
+    IHasTimestamps<TDate>,
+    IHasTimestampOwners<TID>,
+    IHasSoftDelete<TDate>,
+    IHasSoftDeleter<TID> {
+  /**
+   * The user ID
+   */
+  userId: TID;
+  /**
+   * The role ID
+   */
+  roleId: TID;
+}

package/src/interfaces/bases/user.ts

@@ -0,0 +1,91 @@
+import type { PlatformID } from '@digitaldefiance/ecies-lib';
+import { AccountStatus } from '../../enumerations/account-status';
+import { IBackupCode } from '../backup-code';
+import { IHasId } from '../has-id';
+import { IHasSoftDelete } from '../has-soft-delete';
+import { IHasSoftDeleter } from '../has-soft-deleter';
+import { IHasTimestampOwners } from '../has-timestamp-owners';
+import { IHasTimestamps } from '../has-timestamps';
+
+/**
+ * Base interface for user collection documents
+ */
+export interface IUserBase<
+  TID extends PlatformID,
+  TDate extends Date | string,
+  TLanguage extends string,
+  TAccountStatus extends AccountStatus | string,
+>
+  extends
+    IHasId<TID>,
+    IHasTimestamps<TDate>,
+    IHasTimestampOwners<TID>,
+    IHasSoftDelete<TDate>,
+    IHasSoftDeleter<TID> {
+  /**
+   * The username of the user
+   */
+  username: string;
+  /**
+   * The email address of the user
+   */
+  email: string;
+  /**
+   * The public key for the user
+   */
+  publicKey: string;
+  /**
+   * The currency preference of the user
+   */
+  currency: string;
+  /**
+   * The timezone of the user
+   */
+  timezone: string;
+  /**
+   * The language of the site for the user
+   */
+  siteLanguage: TLanguage;
+  /**
+   * Whether the user prefers dark mode
+   */
+  darkMode: boolean;
+  /**
+   * The date the user last logged in
+   */
+  lastLogin?: TDate;
+  /**
+   * Whether the user has verified their email address
+   */
+  emailVerified: boolean;
+  /**
+   * The status of the user's account, eg 'AdminLock'
+   */
+  accountStatus: TAccountStatus;
+  /**
+   * Reference to the mnemonic document
+   */
+  mnemonicId?: TID;
+  /**
+   * Whether the user has enabled direct challenge
+   */
+  directChallenge: boolean;
+  /**
+   * Password-wrapped ECIES private key
+   */
+  passwordWrappedPrivateKey?: {
+    salt: string;
+    iv: string;
+    authTag: string;
+    ciphertext: string;
+    iterations: number;
+  };
+  /**
+   * Array of backup codes to recover mnemonic/private key
+   */
+  backupCodes: Array<IBackupCode>;
+  /**
+   * Copy of the mnemonic encrypted with the user's public key
+   */
+  mnemonicRecovery: string;
+}

package/src/interfaces/combined-role-privileges.ts

@@ -0,0 +1,9 @@
+/**
+ * Combined role privileges across all role types.
+ */
+export interface ICombinedRolePrivileges {
+  admin: boolean;
+  member: boolean;
+  child: boolean;
+  system: boolean;
+}