@digitaldefiance/node-express-suite 3.7.3 → 3.7.5

package/src/schemas/email-token.ts

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Email token schema factory for MongoDB.
+ * Creates schema for email verification and password reset tokens.
+ * @module schemas/email-token
+ */
+
+import { Schema } from '@digitaldefiance/mongoose-types';
+import {
+  EmailTokenType,
+  getSuiteCoreTranslation,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import validator from 'validator';
+import { BaseModelName } from '../enumerations';
+import { IConstants } from '../interfaces';
+
+/**
+ * Configuration options for creating an email token schema.
+ * @template TTokenType - Token type enum (defaults to EmailTokenType)
+ * @template TModelName - Model name type (defaults to BaseModelName)
+ * @template TConstants - Constants type (defaults to IConstants)
+ */
+export interface EmailTokenSchemaOptions<
+  TTokenType extends string = EmailTokenType,
+  TModelName extends string = BaseModelName,
+  TConstants extends IConstants = IConstants,
+> {
+  /** Token type enum values to use */
+  tokenTypeEnum?: TTokenType[];
+  /** Model name for user reference */
+  userModelName?: TModelName;
+  /** Token expiration time (default: '1d') */
+  expiresIn?: string;
+  /** Custom email validator function */
+  emailValidator?: (v: string) => boolean;
+  /** Custom validation error message function */
+  validationMessage?: (props: { value: string }) => string;
+  constants?: TConstants;
+  /** ID type for references */
+  idType?: any;
+}
+
+/**
+ * Factory function to create an extensible email token schema.
+ * Includes TTL index for automatic token expiration.
+ * @template TTokenType - Token type enum (defaults to EmailTokenType)
+ * @template TModelName - Model name type (defaults to BaseModelName)
+ * @template TConstants - Constants type (defaults to IConstants)
+ * @param {EmailTokenSchemaOptions<TTokenType, TModelName>} options - Schema configuration options
+ * @param {TConstants} [_constants] - Optional constants (reserved for future use)
+ * @returns {Schema} Configured email token schema with TTL and unique indexes
+ */
+export function createEmailTokenSchema<
+  TTokenType extends string = EmailTokenType,
+  TModelName extends string = BaseModelName,
+  TConstants extends IConstants = IConstants,
+>(
+  options: EmailTokenSchemaOptions<TTokenType, TModelName> = {},
+  _constants?: TConstants,
+): Schema {
+  const {
+    tokenTypeEnum = Object.values(EmailTokenType) as TTokenType[],
+    userModelName = BaseModelName.User as TModelName,
+    expiresIn = '1d',
+    validationMessage = (props: { value: string }) =>
+      getSuiteCoreTranslation(SuiteCoreStringKey.Error_InvalidEmailTemplate, {
+        email: props.value,
+      }),
+    idType = Schema.Types.ObjectId,
+  } = options;
+
+  const definition = {
+    userId: {
+      type: idType,
+      required: true,
+      ref: userModelName,
+      immutable: true,
+    },
+    type: {
+      type: String,
+      enum: tokenTypeEnum,
+      required: true,
+      immutable: true,
+    },
+    token: { type: String, required: true, immutable: true, unique: true },
+    email: {
+      type: String,
+      required: true,
+      immutable: true,
+      validate: {
+        validator: (v: string) => validator.isEmail(v),
+        message: validationMessage,
+      },
+    },
+    lastSent: { type: Date, required: false },
+    expiresAt: {
+      type: Date,
+      default: Date.now,
+      index: { expires: expiresIn },
+    },
+  };
+
+  const schema = new Schema(definition, { timestamps: true });
+  schema.index({ userId: 1, email: 1, type: 1 }, { unique: true });
+  return schema;
+}
+
+/**
+ * Default email token schema with base configuration.
+ * Pre-configured schema with 1-day TTL and compound unique index.
+ */
+export const EmailTokenSchema = createEmailTokenSchema();

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

@@ -5,4 +5,3 @@ export * from './schema';
 export * from './used-direct-login-token';
 export * from './user';
 export * from './user-role';
-//# sourceMappingURL=index.d.ts.map

package/src/schemas/mnemonic.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Mnemonic schema factory for MongoDB.
+ * Creates schema for storing HMAC-protected mnemonic hashes.
+ * @module schemas/mnemonic
+ */
+
+import { Schema } from '@digitaldefiance/mongoose-types';
+import {
+  getSuiteCoreTranslation,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { LocalhostConstants as AppConstants } from '../constants';
+import { IConstants } from '../interfaces/constants';
+
+/**
+ * Creates a mnemonic schema with custom or default constants.
+ * @template T - Constants type extending IConstants
+ * @param {Function} [validationMessage] - Optional custom validation message function
+ * @param {T} constants - Constants for validation (defaults to AppConstants)
+ * @returns {Schema} Configured mnemonic schema
+ */
+export function createMnemonicSchema<T extends IConstants = IConstants>(
+  validationMessage?: () => string,
+  constants: T = AppConstants as T,
+): Schema {
+  const definition = {
+    hmac: {
+      type: String,
+      required: true,
+      unique: true,
+      index: true,
+      validate: {
+        validator: (v: string) => constants.MnemonicHmacRegex.test(v),
+        message:
+          validationMessage ||
+          (() =>
+            getSuiteCoreTranslation(SuiteCoreStringKey.Validation_HmacRegex)),
+      },
+    },
+  };
+  return new Schema(definition);
+}
+
+/**
+ * Default mnemonic schema using AppConstants.
+ * Pre-configured schema for standard mnemonic storage.
+ */
+export const MnemonicSchema = createMnemonicSchema();

package/src/schemas/role.ts

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Role schema factory for MongoDB with RBAC support.
+ * Creates schema for role management with validation and immutability.
+ * @module schemas/role
+ */
+
+import {
+  CallbackWithoutResultAndOptionalError,
+  Schema,
+} from '@digitaldefiance/mongoose-types';
+import {
+  Role,
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import { BaseModelName } from '../enumerations';
+import { IConstants } from '../interfaces';
+
+/**
+ * Configuration options for creating a role schema.
+ * @template TRole - Role enum type (defaults to Role)
+ * @template TModelName - Model name type (defaults to BaseModelName)
+ */
+export interface RoleSchemaOptions<
+  TRole extends string = Role,
+  TModelName extends string = BaseModelName,
+> {
+  /** Role enum values to use */
+  roleEnum?: TRole[];
+  /** Model name for user reference */
+  userModelName?: TModelName;
+  /** Custom pre-save validation function */
+  customValidation?: <T = any>(
+    doc: T,
+    next: CallbackWithoutResultAndOptionalError,
+  ) => void;
+  /** ID type for references */
+  idType?: any;
+}
+
+/**
+ * Factory function to create an extensible role schema.
+ * Includes pre-save validation to prevent invalid role combinations.
+ * @template TRole - Role enum type (defaults to Role)
+ * @template TModelName - Model name type (defaults to BaseModelName)
+ * @template TConstants - Constants type (defaults to IConstants)
+ * @param {RoleSchemaOptions<TRole, TModelName>} options - Schema configuration options
+ * @param {TConstants} _constants - Optional constants (reserved for future use)
+ * @returns {Schema} Configured role schema with validation hooks
+ */
+export function createRoleSchema<
+  TRole extends string = Role,
+  TModelName extends string = BaseModelName,
+  TConstants extends IConstants = IConstants,
+>(
+  options: RoleSchemaOptions<TRole, TModelName> = {},
+  _constants: TConstants = {} as TConstants,
+): Schema {
+  const {
+    roleEnum = Object.values(Role) as TRole[],
+    userModelName = BaseModelName.User as TModelName,
+    customValidation,
+    idType = Schema.Types.ObjectId,
+  } = options;
+
+  const definition = {
+    name: {
+      type: String,
+      enum: roleEnum,
+      required: true,
+      immutable: true,
+    },
+    admin: {
+      type: Boolean,
+      default: false,
+      immutable: true,
+    },
+    member: {
+      type: Boolean,
+      default: false,
+      immutable: true,
+    },
+    child: {
+      type: Boolean,
+      default: false,
+      immutable: true,
+    },
+    system: {
+      type: Boolean,
+      default: false,
+      immutable: true,
+    },
+    createdBy: {
+      type: idType,
+      ref: userModelName,
+      required: true,
+      immutable: true,
+    },
+    updatedBy: {
+      type: idType,
+      ref: userModelName,
+      required: true,
+    },
+    deletedAt: {
+      type: Date,
+      optional: true,
+      get: (v: Date) => v,
+      set: (v: Date) => new Date(v.toUTCString()),
+    },
+    deletedBy: {
+      type: idType,
+      ref: userModelName,
+      required: false,
+      optional: true,
+    },
+  };
+
+  const schema = new Schema(definition, { timestamps: true });
+  schema.index({ name: 1 }, { unique: true });
+
+  schema.pre('save', function (next: CallbackWithoutResultAndOptionalError) {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const doc = this;
+    if (customValidation) {
+      customValidation(doc, next);
+    } else {
+      // Default validation
+      if (doc.admin && doc.child) {
+        return next(
+          new TranslatableSuiteError(
+            SuiteCoreStringKey.Error_ChildRoleCannotBeAnAdminRole,
+          ),
+        );
+      }
+      if (doc.system && doc.child) {
+        return next(
+          new TranslatableSuiteError(
+            SuiteCoreStringKey.Error_ChildRoleCannotBeASystemRole,
+          ),
+        );
+      }
+      next();
+    }
+  });
+
+  return schema;
+}
+
+/**
+ * Default role schema with base configuration.
+ * Pre-configured schema with Role enum and validation hooks.
+ */
+export const RoleSchema = createRoleSchema();

package/src/schemas/schema.ts

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview Schema map factory and base model document types.
+ * Creates Mongoose schema map with models for all base collections.
+ * @module schemas/schema
+ */
+
+import { Connection, Schema } from '@digitaldefiance/mongoose-types';
+import {
+  IEmailTokenDocument,
+  IMnemonicDocument,
+  IRoleDocument,
+  IUserDocument,
+  IUserRoleDocument,
+} from '../documents';
+import { IUsedDirectLoginTokenDocument } from '../documents/used-direct-login-token';
+import { BaseModelName } from '../enumerations';
+import { SchemaCollection } from '../enumerations/schema-collection';
+import { IConstants } from '../interfaces';
+import EmailTokenModel from '../models/email-token';
+import MnemonicModel from '../models/mnemonic';
+import RoleModel from '../models/role';
+import UsedDirectLoginTokenModel from '../models/used-direct-login-token';
+import UserModel from '../models/user';
+import UserRoleModel from '../models/user-role';
+import { SchemaMap } from '../types';
+import { EmailTokenSchema, createEmailTokenSchema } from './email-token';
+import { MnemonicSchema, createMnemonicSchema } from './mnemonic';
+import { RoleSchema, createRoleSchema } from './role';
+import {
+  UsedDirectLoginTokenSchema,
+  createUsedDirectLoginTokenSchema,
+} from './used-direct-login-token';
+import { UserSchema, createUserSchema } from './user';
+import { UserRoleSchema, createUserRoleSchema } from './user-role';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Base model document types for all collections.
+ * Maps model names to their document interfaces.
+ */
+export interface BaseModelDocs {
+  EmailToken: IEmailTokenDocument;
+  Mnemonic: IMnemonicDocument;
+  Role: IRoleDocument;
+  UsedDirectLoginToken: IUsedDirectLoginTokenDocument;
+  User: IUserDocument;
+  UserRole: IUserRoleDocument;
+}
+
+/**
+ * Options for customizing schema map creation.
+ * Allows overriding constants, schemas, model names, and collection names.
+ */
+export interface SchemaMapOptions {
+  constants?: IConstants;
+  schemas?: {
+    EmailToken?: Schema<IEmailTokenDocument>;
+    Mnemonic?: Schema<IMnemonicDocument>;
+    Role?: Schema<IRoleDocument>;
+    UsedDirectLoginToken?: Schema<IUsedDirectLoginTokenDocument>;
+    User?: Schema<IUserDocument>;
+    UserRole?: Schema<IUserRoleDocument>;
+  };
+  modelNames?: {
+    EmailToken?: string;
+    Mnemonic?: string;
+    Role?: string;
+    UsedDirectLoginToken?: string;
+    User?: string;
+    UserRole?: string;
+  };
+  collections?: {
+    EmailToken?: string;
+    Mnemonic?: string;
+    Role?: string;
+    UsedDirectLoginToken?: string;
+    User?: string;
+    UserRole?: string;
+  };
+}
+
+/**
+ * Creates a schema map with all base models.
+ * @param {Connection} connection - Mongoose connection instance
+ * @param {SchemaMapOptions} options - Optional customization options
+ * @returns {SchemaMap<TID, BaseModelDocs>} Complete schema map with models
+ */
+export function getSchemaMap<TID extends PlatformID>(
+  connection: Connection,
+  options: SchemaMapOptions = {},
+): SchemaMap<TID, BaseModelDocs> {
+  const schemas = options.schemas ?? {
+    EmailToken: createEmailTokenSchema(undefined, options?.constants),
+    Mnemonic: createMnemonicSchema(undefined, options?.constants),
+    Role: createRoleSchema(undefined, options?.constants),
+    UsedDirectLoginToken: createUsedDirectLoginTokenSchema(
+      undefined,
+      options?.constants,
+    ),
+    User: createUserSchema(
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      options?.constants,
+    ),
+    UserRole: createUserRoleSchema(undefined, options?.constants),
+  };
+  const { modelNames = {}, collections = {} } = options;
+
+  return {
+    EmailToken: {
+      collection: collections.EmailToken ?? SchemaCollection.EmailToken,
+      model: EmailTokenModel(
+        connection,
+        modelNames.EmailToken ?? BaseModelName.EmailToken,
+        collections.EmailToken ?? SchemaCollection.EmailToken,
+        schemas.EmailToken,
+      ),
+      modelName: modelNames.EmailToken ?? BaseModelName.EmailToken,
+      schema: schemas.EmailToken ?? EmailTokenSchema,
+    },
+    Mnemonic: {
+      collection: collections.Mnemonic ?? SchemaCollection.Mnemonic,
+      model: MnemonicModel(
+        connection,
+        modelNames.Mnemonic ?? BaseModelName.Mnemonic,
+        collections.Mnemonic ?? SchemaCollection.Mnemonic,
+        schemas.Mnemonic,
+      ),
+      modelName: modelNames.Mnemonic ?? BaseModelName.Mnemonic,
+      schema: schemas.Mnemonic ?? MnemonicSchema,
+    },
+    Role: {
+      collection: collections.Role ?? SchemaCollection.Role,
+      model: RoleModel(
+        connection,
+        modelNames.Role ?? BaseModelName.Role,
+        collections.Role ?? SchemaCollection.Role,
+        schemas.Role,
+      ),
+      modelName: modelNames.Role ?? BaseModelName.Role,
+      schema: schemas.Role ?? RoleSchema,
+    },
+    UsedDirectLoginToken: {
+      collection:
+        collections.UsedDirectLoginToken ??
+        SchemaCollection.UsedDirectLoginToken,
+      model: UsedDirectLoginTokenModel(
+        connection,
+        modelNames.UsedDirectLoginToken ?? BaseModelName.UsedDirectLoginToken,
+        collections.UsedDirectLoginToken ??
+          SchemaCollection.UsedDirectLoginToken,
+        schemas.UsedDirectLoginToken,
+      ),
+      modelName:
+        modelNames.UsedDirectLoginToken ?? BaseModelName.UsedDirectLoginToken,
+      schema: schemas.UsedDirectLoginToken ?? UsedDirectLoginTokenSchema,
+    },
+    User: {
+      collection: collections.User ?? SchemaCollection.User,
+      model: UserModel(
+        connection,
+        modelNames.User ?? BaseModelName.User,
+        collections.User ?? SchemaCollection.User,
+        schemas.User,
+      ),
+      modelName: modelNames.User ?? BaseModelName.User,
+      schema: schemas.User ?? UserSchema,
+    },
+    UserRole: {
+      collection: collections.UserRole ?? SchemaCollection.UserRole,
+      model: UserRoleModel(
+        connection,
+        modelNames.UserRole ?? BaseModelName.UserRole,
+        collections.UserRole ?? SchemaCollection.UserRole,
+        schemas.UserRole,
+      ),
+      modelName: modelNames.UserRole ?? BaseModelName.UserRole,
+      schema: schemas.UserRole ?? UserRoleSchema,
+    },
+  } as unknown as SchemaMap<TID, BaseModelDocs>;
+}

package/src/schemas/used-direct-login-token.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview Used direct login token schema factory for MongoDB.
+ * Creates schema for tracking consumed direct login tokens.
+ * @module schemas/used-direct-login-token
+ */
+
+import { Schema } from '@digitaldefiance/mongoose-types';
+import { BaseModelName } from '../enumerations';
+import { IConstants } from '../interfaces';
+
+/**
+ * Configuration options for creating a used direct login token schema.
+ * @template TModelName - Model name type (defaults to BaseModelName)
+ */
+export interface UsedDirectLoginTokenSchemaOptions<
+  TModelName extends string = BaseModelName,
+> {
+  /** Model name for user reference */
+  userModelName?: TModelName;
+  /** ID type for references */
+  idType?: any;
+}
+
+/**
+ * Factory function to create an extensible used direct login token schema.
+ * @template TModelName - Model name type (defaults to BaseModelName)
+ * @template TConstants - Constants type (defaults to IConstants)
+ * @param {UsedDirectLoginTokenSchemaOptions<TModelName>} options - Schema configuration options
+ * @param {TConstants} [_constants] - Optional constants (reserved for future use)
+ * @returns {Schema} Configured used direct login token schema with unique index
+ */
+export function createUsedDirectLoginTokenSchema<
+  TModelName extends string = BaseModelName,
+  TConstants extends IConstants = IConstants,
+>(
+  options: UsedDirectLoginTokenSchemaOptions<TModelName> = {},
+  _constants?: TConstants,
+): Schema {
+  const {
+    userModelName = BaseModelName.User as TModelName,
+    idType = Schema.Types.ObjectId,
+  } = options;
+
+  const definition = {
+    userId: { type: idType, required: true, ref: userModelName },
+    token: { type: String, required: true },
+  };
+
+  const schema = new Schema(definition);
+  schema.index({ userId: 1, token: 1 }, { unique: true });
+  return schema;
+}
+
+/**
+ * Default used direct login token schema with base configuration.
+ * Pre-configured schema with ObjectId references and unique compound index.
+ */
+export const UsedDirectLoginTokenSchema = createUsedDirectLoginTokenSchema();

package/src/schemas/user-role.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview User-role relationship schema factory for MongoDB.
+ * Creates schema for many-to-many user-role associations.
+ * @module schemas/user-role
+ */
+
+import { Schema } from '@digitaldefiance/mongoose-types';
+import { BaseModelName } from '../enumerations';
+import { IConstants } from '../interfaces';
+
+/**
+ * Configuration options for creating a user-role schema.
+ * @template TModelName - Model name type (defaults to BaseModelName)
+ */
+export interface UserRoleSchemaOptions<
+  TModelName extends string = BaseModelName,
+> {
+  /** Model name for user reference */
+  userModelName?: TModelName;
+  /** Model name for role reference */
+  roleModelName?: TModelName;
+  /** ID type for references */
+  idType?: any;
+}
+
+/**
+ * Factory function to create an extensible user-role schema.
+ * Includes compound unique index and separate indexes for queries.
+ * @template TModelName - Model name type (defaults to BaseModelName)
+ * @template TConstants - Constants type (defaults to IConstants)
+ * @param {UserRoleSchemaOptions<TModelName>} options - Schema configuration options
+ * @param {TConstants} [_constants] - Optional constants (reserved for future use)
+ * @returns {Schema} Configured user-role schema with indexes
+ */
+export function createUserRoleSchema<
+  TModelName extends string = BaseModelName,
+  TConstants extends IConstants = IConstants,
+>(
+  options: UserRoleSchemaOptions<TModelName> = {},
+  _constants?: TConstants,
+): Schema {
+  const {
+    userModelName = BaseModelName.User as TModelName,
+    roleModelName = BaseModelName.Role as TModelName,
+    idType = Schema.Types.ObjectId,
+  } = options;
+
+  const definition = {
+    userId: {
+      type: idType,
+      ref: userModelName,
+      required: true,
+    },
+    roleId: {
+      type: idType,
+      ref: roleModelName,
+      required: true,
+    },
+    createdBy: {
+      type: idType,
+      ref: userModelName,
+      required: true,
+      immutable: true,
+    },
+    updatedBy: {
+      type: idType,
+      ref: userModelName,
+      required: true,
+    },
+    deletedAt: {
+      type: Date,
+      optional: true,
+    },
+    deletedBy: {
+      type: idType,
+      ref: userModelName,
+      required: false,
+      optional: true,
+    },
+  };
+
+  const schema = new Schema(definition, { timestamps: true });
+  schema.index({ userId: 1, roleId: 1 }, { unique: true });
+  schema.index({ userId: 1 });
+  schema.index({ roleId: 1 });
+  return schema;
+}
+
+/**
+ * Default user-role schema with base configuration.
+ * Pre-configured schema with compound unique index on userId and roleId.
+ */
+export const UserRoleSchema = createUserRoleSchema();