@digitaldefiance/suite-core-lib 3.6.6 → 3.6.8

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/README.md

@@ -40,36 +40,37 @@ All error messages, validation texts, and user-facing strings are fully localize
 
 ## 🏗️ Architecture Overview
 
-### Type-Safe Interfaces
+### Type-Safe Base Interfaces
 
 ```typescript
 import { 
-  IFrontendUser, 
-  IBackendUser, 
+  IUserBase,
+  IRoleBase,
+  IUserRoleBase,
   AccountStatus, 
   Role,
   CoreLanguage 
 } from '@digitaldefiance/suite-core-lib';
 
-// Frontend-optimized user interface with string-based IDs
-interface AppUser extends IFrontendUser<'en'> {
-  _id: string;
-  siteLanguage: 'en';
-  accountStatus: AccountStatus;
+// Create a user interface with string IDs for frontend applications
+interface FrontendUser extends IUserBase<string, Date, 'en', AccountStatus> {
+  // Additional app-specific fields
 }
 
-// Backend database interface supporting ObjectId types (Default)
-interface DatabaseUser extends IBackendUser<'en'> {
-  _id: Types.ObjectId;
-  createdBy: Types.ObjectId;
-  updatedBy: Types.ObjectId;
+// Create a user interface with ObjectId for MongoDB backend
+import { Types } from 'mongoose';
+interface BackendUser extends IUserBase<Types.ObjectId, Date, 'en', AccountStatus> {
+  // Additional app-specific fields
+}
+
+// Create a user interface with UUID strings for SQL databases
+interface SqlUser extends IUserBase<string, Date, 'en', AccountStatus> {
+  // Additional app-specific fields
 }
 
-// Example: Backend interface using UUIDs (Strings)
-interface SqlUser extends IBackendUser<'en', string> {
-  _id: string;
-  createdBy: string;
-  updatedBy: string;
+// Create custom role interfaces
+interface AppRole extends IRoleBase<string, Date, Role> {
+  // Additional app-specific fields
 }
 ```
 
@@ -120,17 +121,23 @@ The **@digitaldefiance/node-express-suite** package builds upon these primitives
 ### Express.js Framework Usage
 
 ```typescript
-// Internal usage of suite-core-lib primitives in node-express-suite
+// Usage of suite-core-lib primitives in Express applications
 import { 
-  IFrontendUser, 
+  IUserBase,
   AccountStatus, 
   BackupCodeString,
   UserNotFoundError,
+  InvalidBackupCodeError,
   CoreLanguage 
 } from '@digitaldefiance/suite-core-lib';
 
+interface BackupCode {
+  encrypted: string;
+  used: boolean;
+}
+
 // Middleware example: validate backup code input
-function validateBackupCode(userInput: string, storedCodes: IBackupCode[]) {
+function validateBackupCode(userInput: string, storedCodes: BackupCode[]): boolean {
   try {
     const inputCode = new BackupCodeString(userInput);
     return storedCodes.some(stored => 
@@ -149,21 +156,24 @@ function validateBackupCode(userInput: string, storedCodes: IBackupCode[]) {
 ### Frontend Framework Integration
 
 ```typescript
-// Frontend frameworks consume type-safe interfaces
-import { IFrontendUser, AccountStatus } from '@digitaldefiance/suite-core-lib';
+// Frontend frameworks consume type-safe base interfaces
+import { IUserBase, AccountStatus } from '@digitaldefiance/suite-core-lib';
+
+// Define a frontend user type with string IDs and Date objects
+type FrontendUser = IUserBase<string, Date, 'en' | 'fr' | 'es', AccountStatus>;
 
 // React/Vue/Angular component props example
 interface UserProfileProps {
-  user: IFrontendUser<'en' | 'fr' | 'es'>;
+  user: FrontendUser;
   onStatusChange: (status: AccountStatus) => void;
 }
 
 // Function to update user status with type safety
-function updateUserStatus(user: IFrontendUser<string>, status: AccountStatus) {
+function updateUserStatus(user: FrontendUser, status: AccountStatus): FrontendUser {
   return {
     ...user,
     accountStatus: status,
-    updatedAt: new Date().toISOString()
+    updatedAt: new Date()
   };
 }
 ```
@@ -171,11 +181,14 @@ function updateUserStatus(user: IFrontendUser<string>, status: AccountStatus) {
 ### Database Layer Integration
 
 ```typescript
-// Database schemas implementing suite-core-lib interfaces
-import { IBackendUser, IUserRoleBase } from '@digitaldefiance/suite-core-lib';
+// Database schemas implementing suite-core-lib base interfaces
+import { IUserBase, IUserRoleBase, AccountStatus } from '@digitaldefiance/suite-core-lib';
 import { Types } from 'mongoose';
 
-const userSchema = new mongoose.Schema<IBackendUser<'en'>>({
+// Define a MongoDB user type using ObjectId
+type MongoUser = IUserBase<Types.ObjectId, Date, 'en', AccountStatus>;
+
+const userSchema = new mongoose.Schema<MongoUser>({
   _id: { type: Types.ObjectId, required: true },
   username: { type: String, required: true, unique: true },
   email: { type: String, required: true, unique: true },
@@ -186,6 +199,11 @@ const userSchema = new mongoose.Schema<IBackendUser<'en'>>({
   },
   // Additional schema fields matching the interface
 });
+
+// SQL database example with UUID strings
+type SqlUser = IUserBase<string, Date, 'en', AccountStatus> & {
+  customField: string;
+};
 ```
 
 ## 🔧 Advanced Configuration
@@ -259,14 +277,23 @@ The **@digitaldefiance/node-ecies** and **@digitaldefiance/node-express-suite**
 ## 🆕 What's New in v3.0
 
 ### Generic ID Support
-Core interfaces (`IBackendUser`, `IBackendRole`, etc.) now support generic ID types. This enables seamless integration with the new **Pluggable ID Providers** (ObjectId, UUID, GUID) introduced in `@digitaldefiance/ecies-lib` v4.1.0.
+Core base interfaces (`IUserBase`, `IRoleBase`, `IUserRoleBase`, etc.) now support generic ID types. This enables seamless integration with any database system using the **Pluggable ID Providers** (ObjectId, UUID, GUID) introduced in `@digitaldefiance/ecies-lib` v4.1.0.
 
 ```typescript
-// Default behavior (MongoDB ObjectId)
-interface MongoUser extends IBackendUser<'en'> {}
+import { IUserBase, AccountStatus } from '@digitaldefiance/suite-core-lib';
+import { Types } from 'mongoose';
+
+// MongoDB with ObjectId
+type MongoUser = IUserBase<Types.ObjectId, Date, 'en', AccountStatus>;
+
+// SQL database with UUID strings
+type SqlUser = IUserBase<string, Date, 'en', AccountStatus>;
+
+// PostgreSQL with numeric IDs
+type PostgresUser = IUserBase<number, Date, 'en', AccountStatus>;
 
-// Custom ID type (e.g. UUID string)
-interface SqlUser extends IBackendUser<'en', string> {}
+// Frontend with string IDs and ISO date strings
+type FrontendUser = IUserBase<string, string, 'en', AccountStatus>;
 ```
 
 ## ✨ Key Features (v2.1+)
@@ -501,23 +528,31 @@ describe('Error Handling', () => {
 
 ### Cross-Package Testing
 
-Testing with node-express-suite:
+Testing with base interfaces:
 
 ```typescript
-import { IBackendUser, AccountStatus } from '@digitaldefiance/suite-core-lib';
-import { UserService } from '@digitaldefiance/node-express-suite';
+import { IUserBase, AccountStatus } from '@digitaldefiance/suite-core-lib';
+import { Types } from 'mongoose';
+
+// Define your user type
+type TestUser = IUserBase<Types.ObjectId, Date, 'en', AccountStatus>;
 
-describe('Integration with node-express-suite', () => {
-  it('should work with UserService', async () => {
-    const user: IBackendUser = {
+describe('User Management', () => {
+  it('should create user with correct status', () => {
+    const user: TestUser = {
+      _id: new Types.ObjectId(),
       username: 'alice',
       email: 'alice@example.com',
       accountStatus: AccountStatus.Active,
-      // ... other fields
+      emailVerified: true,
+      siteLanguage: 'en',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      // ... other required fields
     };
     
-    // Use with UserService
     expect(user.accountStatus).toBe(AccountStatus.Active);
+    expect(user.emailVerified).toBe(true);
   });
 });
 ```
@@ -526,7 +561,10 @@ describe('Integration with node-express-suite', () => {
 
 ## v3.6.6
 
-- Move models to node-express-suite
+- **Breaking Change**: Move `IFrontend*` and `IBackend*` type aliases to `@digitaldefiance/node-express-suite`
+  - Base interfaces (`IUserBase`, `IRoleBase`, `IUserRoleBase`, etc.) remain in `suite-core-lib` as the core primitives
+  - Framework-specific type aliases moved to `node-express-suite` for better separation of concerns
+  - Migration: Use base interfaces directly (e.g., `IUserBase<string, Date, 'en', AccountStatus>`) or import pre-configured types from `@digitaldefiance/node-express-suite`
 - Update testing
 - Update ecies
 
@@ -593,7 +631,7 @@ None. This is a backward-compatible release focused on internal type safety impr
 ## v3.0.0
 
 - Upgrade ECIES to 4.1.0
-- Update backend interfaces (`IBackendUser`, `IBackendUserRole`, `IBackendTokenRole`, `IBackendUsedDirectLoginToken`) to support generic ID types (defaulting to `Types.ObjectId` for backward compatibility). This enables support for pluggable ID providers (e.g. GUIDs, strings, numbers) introduced in `@digitaldefiance/ecies-lib` v4.1.0.
+- Update base interfaces (`IUserBase`, `IUserRoleBase`, `ITokenRole`, etc.) to support generic ID types. This enables support for pluggable ID providers (e.g. ObjectId, UUID, GUID, numbers) introduced in `@digitaldefiance/ecies-lib` v4.1.0.
 
 ## v2.2.26
 

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@digitaldefiance/suite-core-lib",
-  "version": "3.6.6",
+  "version": "3.6.8",
+  "homepage": "https://github.com/Digital-Defiance/suite-core-lib",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Digital-Defiance/suite-core-lib.git"
+  },
   "description": "Generic user system and document system common core for applications",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -22,8 +27,8 @@
     "publish:public": "npm publish --access public"
   },
   "dependencies": {
-    "@digitaldefiance/ecies-lib": "4.4.2",
-    "@digitaldefiance/i18n-lib": "3.8.0"
+    "@digitaldefiance/ecies-lib": "4.4.7",
+    "@digitaldefiance/i18n-lib": "3.8.2"
   },
   "files": [
     "src",
@@ -41,6 +46,5 @@
     "@typescript-eslint/parser": "^8.48.0",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.4"
-  },
-  "type": "commonjs"
-}
+  }
+}

package/src/backup-code-string.ts

@@ -0,0 +1,96 @@
+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 './user-builder';
 export * from './role-builder';
-//# sourceMappingURL=index.d.ts.map

package/src/builders/role-builder.ts

@@ -0,0 +1,63 @@
+/**
+ * Fluent builder for creating role objects
+ */
+
+import { Role } from '../enumerations/role';
+import { IRoleBase } from '../interfaces/bases/role';
+
+/**
+ * Builder for creating role objects with fluent API
+ */
+export class RoleBuilder<I = string, D extends Date | string = Date> {
+  private data: Partial<IRoleBase<I, D, Role>> = {
+    admin: false,
+    member: false,
+    child: false,
+    system: false,
+  };
+
+  static create<I = string, D extends Date | string = Date>(): RoleBuilder<I, D> {
+    return new RoleBuilder<I, D>();
+  }
+
+  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<I, D, Role>> {
+    return { ...this.data };
+  }
+}

package/src/builders/user-builder.ts

@@ -0,0 +1,72 @@
+/**
+ * Fluent builder for creating user objects
+ */
+
+import { AccountStatus } from '../enumerations/account-status';
+import { IUserBase } from '../interfaces/bases/user';
+
+/**
+ * Builder for creating user objects with fluent API
+ */
+export class UserBuilder<I = string, D extends Date | string = Date, S extends string = string> {
+  private data: Partial<IUserBase<I, D, S, AccountStatus>> = {
+    emailVerified: false,
+    accountStatus: AccountStatus.Active,
+    directChallenge: false,
+    backupCodes: [],
+    timezone: 'UTC',
+  };
+
+  static create<I = string, D extends Date | string = Date, S extends string = string>(): UserBuilder<I, D, S> {
+    return new UserBuilder<I, D, S>();
+  }
+
+  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: S): 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<I, D, S, AccountStatus>> {
+    return { ...this.data };
+  }
+}