@digitaldefiance/suite-core-lib 3.6.47 → 3.6.48

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Digital Defiance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitaldefiance/suite-core-lib",
-  "version": "3.6.47",
+  "version": "3.6.48",
   "homepage": "https://github.com/Digital-Defiance/suite-core-lib",
   "repository": {
     "type": "git",
@@ -46,6 +46,5 @@
     "@typescript-eslint/parser": "^8.52.0",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.4"
-  },
-  "type": "commonjs"
-}
+  }
+}

package/src/backup-code-string.ts

@@ -0,0 +1,102 @@
+/**
+ * Backup code string class for generating, validating, and formatting backup codes.
+ * Provides type-safe handling of backup codes with multiple output formats.
+ */
+import { Constants } from './constants';
+import { InvalidBackupCodeError } from './errors/invalid-backup-code';
+import { IConstants } from './interfaces';
+
+export class BackupCodeString {
+  private readonly _normalizedCode: string;
+
+  constructor(code: string) {
+    const normalizedCode = BackupCodeString.normalizeCode(code);
+    if (!Constants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
+      throw new InvalidBackupCodeError();
+    }
+    this._normalizedCode = normalizedCode;
+  }
+
+  public get value(): string {
+    return BackupCodeString.formatBackupCode(this._normalizedCode);
+  }
+
+  public get notNullValue(): string {
+    return BackupCodeString.formatBackupCode(this._normalizedCode);
+  }
+
+  public get valueAsHexString(): string {
+    const formattedValue = BackupCodeString.formatBackupCode(
+      this._normalizedCode,
+    );
+    return new TextEncoder().encode(formattedValue).reduce((str, byte) => {
+      return str + byte.toString(16).padStart(2, '0');
+    }, '');
+  }
+
+  public get valueAsBase64String(): string {
+    const formattedValue = BackupCodeString.formatBackupCode(
+      this._normalizedCode,
+    );
+    return btoa(formattedValue);
+  }
+
+  public get valueAsUint8Array(): Uint8Array {
+    const formattedValue = BackupCodeString.formatBackupCode(
+      this._normalizedCode,
+    );
+    return new TextEncoder().encode(formattedValue);
+  }
+
+  public get hasValue(): boolean {
+    return this._normalizedCode.length > 0;
+  }
+
+  public get length(): number {
+    return this._normalizedCode.length;
+  }
+
+  public dispose(): void {
+    // Backup codes are not sensitive enough to require secure disposal
+    // They're already encrypted when stored in the database
+  }
+
+  /**
+   * Format a 32-char normalized code into display form (8 groups of 4).
+   * Does not restrict characters beyond grouping.
+   */
+  public static formatBackupCode(code: string): string {
+    const groups = code.match(/.{1,4}/g) ?? [code];
+    return groups.join('-');
+  }
+  /**
+   * Normalize user-entered code: remove spaces and hyphens, lowercase, and trim.
+   */
+  public static normalizeCode(input: string): string {
+    return input.replace(/[\s-]/g, '').toLowerCase().trim();
+  }
+
+  public static generateBackupCode(): string {
+    const alphabet = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    const rnd = crypto.getRandomValues(new Uint8Array(32));
+    let raw = '';
+    for (let j = 0; j < 32; j++) {
+      raw += alphabet[rnd[j] % alphabet.length];
+    }
+    return raw;
+  }
+
+  /**
+   * Generate the configured number of backup codes.
+   * Note: If generation alphabet/length is controlled elsewhere, prefer that path.
+   */
+  public static generateBackupCodes(
+    constants: IConstants = Constants,
+  ): Array<BackupCodeString> {
+    const codes: Array<BackupCodeString> = [];
+    for (let i = 0; i < constants.BACKUP_CODES.Count; i++) {
+      codes.push(new BackupCodeString(BackupCodeString.generateBackupCode()));
+    }
+    return codes;
+  }
+}

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

@@ -1,6 +1,6 @@
 /**
  * Builders module - fluent builders for common objects
  */
+
 export * from './role-builder';
 export * from './user-builder';
-//# sourceMappingURL=index.d.ts.map

package/src/builders/role-builder.ts

@@ -0,0 +1,67 @@
+/**
+ * Fluent builder for creating role objects
+ */
+
+import type { PlatformID } from '@digitaldefiance/ecies-lib';
+import { Role } from '../enumerations/role';
+import { IRoleBase } from '../interfaces/bases/role';
+
+/**
+ * Builder for creating role objects with fluent API
+ */
+export class RoleBuilder<TID extends PlatformID = PlatformID, TDate extends Date | string = Date> {
+  private data: Partial<IRoleBase<TID, TDate, Role>> = {
+    admin: false,
+    member: false,
+    child: false,
+    system: false,
+  };
+
+  static create<TID extends PlatformID = PlatformID, TDate extends Date | string = Date>(): RoleBuilder<
+    TID,
+    TDate
+  > {
+    return new RoleBuilder<TID, TDate>();
+  }
+
+  withName(name: Role): this {
+    this.data.name = name;
+    return this;
+  }
+
+  asAdmin(): this {
+    this.data.admin = true;
+    this.data.member = false;
+    this.data.child = false;
+    this.data.system = false;
+    return this;
+  }
+
+  asMember(): this {
+    this.data.admin = false;
+    this.data.member = true;
+    this.data.child = false;
+    this.data.system = false;
+    return this;
+  }
+
+  asChild(): this {
+    this.data.admin = false;
+    this.data.member = false;
+    this.data.child = true;
+    this.data.system = false;
+    return this;
+  }
+
+  asSystem(): this {
+    this.data.admin = false;
+    this.data.member = false;
+    this.data.child = false;
+    this.data.system = true;
+    return this;
+  }
+
+  build(): Partial<IRoleBase<TID, TDate, Role>> {
+    return { ...this.data };
+  }
+}

package/src/builders/user-builder.ts

@@ -0,0 +1,81 @@
+/**
+ * Fluent builder for creating user objects
+ */
+
+import type { PlatformID } from '@digitaldefiance/ecies-lib';
+import { AccountStatus } from '../enumerations/account-status';
+import { IUserBase } from '../interfaces/bases/user';
+
+/**
+ * Builder for creating user objects with fluent API
+ */
+export class UserBuilder<
+  TID extends PlatformID = PlatformID,
+  TDate extends Date | string = Date,
+  TLanguage extends string = string,
+> {
+  private data: Partial<IUserBase<TID, TDate, TLanguage, AccountStatus>> = {
+    emailVerified: false,
+    accountStatus: AccountStatus.Active,
+    directChallenge: false,
+    backupCodes: [],
+    timezone: 'UTC',
+  };
+
+  static create<
+    TID extends PlatformID = PlatformID,
+    TDate extends Date | string = Date,
+    TLanguage extends string = string,
+  >(): UserBuilder<TID, TDate, TLanguage> {
+    return new UserBuilder<TID, TDate, TLanguage>();
+  }
+
+  withUsername(username: string): this {
+    this.data.username = username;
+    return this;
+  }
+
+  withEmail(email: string): this {
+    this.data.email = email;
+    return this;
+  }
+
+  withPublicKey(publicKey: string): this {
+    this.data.publicKey = publicKey;
+    return this;
+  }
+
+  withTimezone(timezone: string): this {
+    this.data.timezone = timezone;
+    return this;
+  }
+
+  withSiteLanguage(siteLanguage: TLanguage): this {
+    this.data.siteLanguage = siteLanguage;
+    return this;
+  }
+
+  withEmailVerified(verified: boolean): this {
+    this.data.emailVerified = verified;
+    return this;
+  }
+
+  withAccountStatus(status: AccountStatus): this {
+    this.data.accountStatus = status;
+    return this;
+  }
+
+  withDirectChallenge(enabled: boolean): this {
+    this.data.directChallenge = enabled;
+    return this;
+  }
+
+  withMnemonicRecovery(recovery: string): this {
+    this.data.mnemonicRecovery = recovery;
+    return this;
+  }
+
+  build(): Partial<IUserBase<TID, TDate, TLanguage, AccountStatus>> {
+    return { ...this.data };
+  }
+}

package/src/constants.ts

@@ -0,0 +1,229 @@
+/**
+ * Constants and configuration for the suite-core library.
+ * Provides runtime configuration including backup codes, authentication settings,
+ * validation rules, and site-specific constants.
+ */
+import { ObjectIdProvider } from '@digitaldefiance/ecies-lib';
+import { Role } from './enumerations/role';
+import { IBackupCodeConstants, ICoreConstants } from './interfaces';
+import { IConstants } from './interfaces/constants';
+
+export const BACKUP_CODES: IBackupCodeConstants = Object.freeze({
+  /**
+   * How many backup codes to generate for users
+   */
+  Count: 10 as const,
+  NormalizedHexRegex: /^[a-z0-9]{32}$/, // exactly 32 lowercase alphanumeric chars
+  DisplayRegex: /^([a-z0-9]{4}-){7}[a-z0-9]{4}$/, // xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx
+} as const);
+
+export const CORE: ICoreConstants = Object.freeze({
+  /**
+   * The ID provider to use for generating and parsing IDs
+   */
+  idProvider: new ObjectIdProvider(),
+  /**
+   * Default duration in seconds for which a mnemonic is kept in memory
+   */
+  DefaultExpireMemoryMnemonicSeconds: 300 as const, // 5 minutes
+  /**
+   * Default duration in seconds for which a wallet is kept in memory
+   */
+  DefaultExpireMemoryWalletSeconds: 300 as const, // 5 minutes
+
+  /**
+   * Duration in milliseconds for which a login challenge is valid.
+   */
+  LoginChallengeExpiration: 60000 as const, // 60 seconds
+
+  /**
+   * The expected length of a direct login challenge in bytes
+   */
+  DirectLoginChallengeLength: 104 as const,
+
+  /**
+   * Backup code system configuration
+   */
+  BACKUP_CODES: BACKUP_CODES,
+
+  /**
+   * Duration in milliseconds for which an email token is valid.
+   */
+  EmailTokenExpiration: 86400000 as const, // 24 * 60 * 60 * 1000
+  /**
+   * Length in bytes of the email token generated (is represented as a hex string of twice as many)
+   */
+  EmailTokenLength: 32 as const,
+  /**
+   * Number of rounds for bcrypt hashing. Higher values increase security but also consume more CPU resources.
+   */
+  BcryptRounds: 10 as const,
+  /**
+   * The username of the administrator user.
+   */
+  AdministratorUser: 'admin' as const,
+  /**
+   * The name of the administrator role.
+   */
+  AdministratorRole: Role.Admin as const,
+  /**
+   * The name of the member role.
+   */
+  MemberRole: Role.Member as const,
+  /**
+   * The username of the test user.
+   */
+  MemberUser: 'test' as const,
+  /**
+   * The name of the system role.
+   */
+  SystemRole: Role.System as const,
+  /**
+   * The username of the system user.
+   */
+  SystemUser: 'system' as const,
+  /**
+   * Minimum username length
+   */
+  UsernameMinLength: 3 as const,
+  /**
+   * Maximum username length
+   */
+  UsernameMaxLength: 30 as const,
+  /**
+   * The regular expression for valid usernames.
+   */
+  UsernameRegex: /^[A-Za-z0-9]{3,30}$/,
+  /**
+   * Minimum password length
+   */
+  PasswordMinLength: 8 as const,
+  /**
+   * The regular expression for valid passwords.
+   */
+  PasswordRegex:
+    /^(?=.*[A-Za-z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?])[A-Za-z\d!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]{8,}$/,
+  /**
+   * The regular expression for valid JWT tokens.
+   */
+  JwtSecretRegex: /^[0-9a-f]{64}$/i,
+  /**
+   * The regular expression for valid mnemonic phrases.
+   * BIP39 - supports 12, 15, 18, 21, or 24 word mnemonics
+   */
+  MnemonicRegex:
+    /^(?:\w+\s){11}\w+$|^(?:\w+\s){14}\w+$|^(?:\w+\s){17}\w+$|^(?:\w+\s){20}\w+$|^(?:\w+\s){23}\w+$/i,
+  /**
+   * Matches a 64-character hexadecimal string (SHA-256).
+   */
+  MnemonicHmacRegex: /^[a-f0-9]{64}$/,
+  /**
+   * The regular expression for valid encryption keys.
+   */
+  MnemonicEncryptionKeyRegex: /^[a-f0-9]{64}$/,
+  /**
+   * The amount of time in milliseconds after which an email token can be resent.
+   */
+  EmailTokenResendInterval: 300000 as const, // 5 * 60 * 1000 = 5 minutes
+  /**
+   * The interval in minutes after which an email token can be resent.
+   */
+  EmailTokenResendIntervalMinutes: 5 as const,
+  /**
+   * The site name. Overridden by specific site constants.
+   */
+  Site: 'New Site' as const,
+  /**
+   * The site tagline. Overridden by specific site constants.
+   */
+  SiteTagline: 'New Site Tagline' as const,
+  /**
+   * The site description. Overridden by specific site constants.
+   */
+  SiteDescription: 'Description of the new site' as const,
+  /**
+   * Email domain of usernames on the site. Overridden by specific site constants.
+   */
+  SiteEmailDomain: 'localhost' as const,
+  /**
+   * The hostname of the site. Overridden by specific site constants.
+   */
+  SiteHostname: 'localhost' as const,
+} as const);
+
+export const createConstants: (
+  siteDomain: string,
+  siteHostname: string,
+  overrides?: Partial<IConstants>,
+) => IConstants = (
+  siteDomain: string,
+  siteHostname: string,
+  overrides?: Partial<IConstants>,
+) => {
+  return Object.freeze({
+    ...CORE,
+    /**
+     * The email of the administrator user/admin contact
+     */
+    AdministratorEmail: `admin@${siteDomain}` as const,
+    /**
+     * The email of the test user.
+     */
+    MemberEmail: `test@${siteDomain}` as const,
+    /**
+     * The email of the system user.
+     */
+    SystemEmail: `system@${siteDomain}` as const,
+    /**
+     * The email domain of usernames on the site.
+     */
+    SiteEmailDomain: siteDomain,
+    /**
+     * The hostname of the site.
+     */
+    SiteHostname: siteHostname,
+    /**
+     * The color used to indicate success states.
+     */
+    success_color: '#4CAF50',
+    /**
+     * The color used to indicate failure states.
+     */
+    failure_color: '#F44336',
+    /**
+     * The color used to indicate warning states.
+     */
+    warning_color: '#FF9800',
+    /**
+     * The light variant of the primary text color.
+     */
+    primary_text_light: '#ffffff',
+    /**
+     * The dark variant of the primary text color.
+     */
+    primary_text_dark: '#000000',
+    /**
+     * The light variant of the secondary text color.
+     */
+    secondary_text_light: '#ffffff',
+    /**
+     * The dark variant of the secondary text color.
+     */
+    secondary_text_dark: '#000000',
+    /**
+     * The primary brand color (used for primary theme color)
+     */
+    logo_primary_color: '#050505ff',
+    /**
+     * The primary text color (used for logo and text)
+     */
+    logo_primary_text: '#212121',
+    /**
+     * The secondary text color (used for logo and accents)
+     */
+    logo_secondary_text: '#757575',
+    ...(overrides ?? {}),
+  } as const);
+};
+
+export const Constants = createConstants('localhost', 'localhost');

package/src/core/{errors.d.ts → errors.ts}

@@ -1,9 +1,13 @@
 /**
  * Core error class exports for suite-core-lib
  */
+
+// Base error classes
 export { CoreTypedHandleableError } from '../errors/core-typed-handleable';
 export { TranslatableSuiteError } from '../errors/translatable-suite';
 export { TranslatableSuiteHandleableError } from '../errors/translatable-suite-handleable';
+
+// Common error classes
 export { EmailInUseError } from '../errors/email-in-use';
 export { GenericValidationError } from '../errors/generic-validation';
 export { InvalidCredentialsError } from '../errors/invalid-credentials';
@@ -11,4 +15,3 @@ export { InvalidEmailError } from '../errors/invalid-email';
 export { InvalidUsernameError } from '../errors/invalid-username';
 export { UserNotFoundError } from '../errors/user-not-found';
 export { UsernameInUseError } from '../errors/username-in-use';
-//# sourceMappingURL=errors.d.ts.map

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

@@ -3,5 +3,5 @@
  * Note: Most types are already exported from the main index.ts
  * This module provides convenient grouped exports for commonly used items
  */
+
 export * from './result';
-//# sourceMappingURL=index.d.ts.map

package/src/core/result.ts

@@ -0,0 +1,40 @@
+/**
+ * Result type pattern for better error handling
+ * Provides type-safe success/failure handling without exceptions
+ */
+
+export type Result<T, TError = Error> =
+  | { success: true; data: T }
+  | { success: false; error: TError };
+
+/**
+ * Create a successful result
+ */
+export function success<T>(data: T): Result<T, never> {
+  return { success: true, data };
+}
+
+/**
+ * Create a failed result
+ */
+export function failure<E>(error: E): Result<never, E> {
+  return { success: false, error };
+}
+
+/**
+ * Check if result is successful
+ */
+export function isSuccess<T, E>(
+  result: Result<T, E>,
+): result is { success: true; data: T } {
+  return result.success;
+}
+
+/**
+ * Check if result is a failure
+ */
+export function isFailure<T, E>(
+  result: Result<T, E>,
+): result is { success: false; error: E } {
+  return !result.success;
+}

package/src/core/{types.d.ts → types.ts}

@@ -1,8 +1,12 @@
 /**
  * Core type exports for suite-core-lib
  */
+
+// Common utility types
 export type { DeepPartial } from '../interfaces/deep-partial';
 export type { IFailableResult } from '../interfaces/failable-result';
+
+// Base interface types
 export type { IHasCreation } from '../interfaces/has-creation';
 export type { IHasCreator } from '../interfaces/has-creator';
 export type { IHasId } from '../interfaces/has-id';
@@ -12,6 +16,7 @@ export type { IHasTimestampOwners } from '../interfaces/has-timestamp-owners';
 export type { IHasTimestamps } from '../interfaces/has-timestamps';
 export type { IHasUpdater } from '../interfaces/has-updater';
 export type { IHasUpdates } from '../interfaces/has-updates';
+
+// User and auth types
 export type { BackupCodeString } from '../backup-code-string';
 export type { ITokenUser } from '../interfaces/token-user';
-//# sourceMappingURL=types.d.ts.map