@modular-rest/server 1.11.13 → 1.11.14

package/src/class/reply.ts

@@ -0,0 +1,59 @@
+/**
+ * Response status type
+ */
+export type ResponseStatus = 's' | 'f' | 'e';
+
+/**
+ * Response object interface
+ */
+export interface ResponseObject {
+  status: 'success' | 'fail' | 'error';
+  [key: string]: any;
+}
+
+/**
+ * Creates a response object with the given status and detail.
+ *
+ * @param status - The status of the response. Can be "s" for success, "f" for fail, or "e" for error.
+ * @param detail - The detail of the response. Can contain any additional information about the response.
+ * @returns The response object with the given status and detail.
+ *
+ * @example
+ * ```typescript
+ * import { reply } from '@modular-rest/server';
+ *
+ * // inside the router
+ * const response = reply.create("s", { message: "Hello, world!" });
+ * ctx.body = response;
+ * ctx.status = 200;
+ * ```
+ */
+export function create(status: ResponseStatus, detail: Record<string, any> = {}): ResponseObject {
+  // Initialize with a default status that will be overwritten
+  const result: ResponseObject = {
+    status: 'success',
+    ...detail,
+  };
+
+  // define status
+  switch (status) {
+    case 's':
+      result.status = 'success';
+      break;
+
+    case 'f':
+      result.status = 'fail';
+      break;
+
+    case 'e':
+      result.status = 'error';
+      break;
+
+    default:
+      result.status = 'success';
+      break;
+  }
+
+  // return
+  return result;
+}

package/src/class/security.ts

@@ -0,0 +1,250 @@
+/**
+ * Permission type string literal type that defines various access levels and capabilities
+ 
+ * @inline
+ */
+export type AccessType =
+  | 'god_access'
+  | 'user_access'
+  | 'upload_file_access'
+  | 'remove_file_access'
+  | 'anonymous_access'
+  | 'advanced_settings'
+  | string;
+
+/**
+ * Defines access control for a specific database collection
+ *
+ * @internal
+ */
+export class AccessDefinition {
+  /** @hidden */
+  database: string;
+  /** @hidden */
+  collection: string;
+  /** @hidden */
+  permissionList: Permission[];
+
+  /**
+   * Creates a new AccessDefinition instance
+   * @param {Object} options - Configuration options
+   * @param {string} options.database - The name of the database
+   * @param {string} options.collection - The name of the collection
+   * @param {Permission[]} options.permissionList - List of permissions
+   */
+  constructor({
+    database,
+    collection,
+    permissionList,
+  }: {
+    database: string;
+    collection: string;
+    permissionList: Permission[];
+  }) {
+    this.database = database;
+    this.collection = collection;
+    this.permissionList = permissionList;
+  }
+}
+
+/**
+ * Defines a permission for accessing data within the system. This class is a fundamental component used in both the {@link defineCollection} method and {@link CollectionDefinition} class
+ * by specifying which permission types can interact with them. The permission system matches a user's assigned permission types against
+ * the collection's permissions to determine access levels. For example, a collection can allow read access for 'user_access' while
+ * restricting writes to 'advanced_settings' permissions.
+ *
+ * @remark
+ * {@include ../../docs/system-access-type.md}
+ *
+ * @example
+ * ```typescript
+ * import { Permission } from '@modular-rest/server';
+ *
+ * const permission = new Permission({
+ *   type: 'user_access',
+ *   read: true,
+ *   write: true,
+ *   onlyOwnData: true,
+ *   ownerIdField: 'userId'
+ * });
+ * ```
+ */
+export class Permission {
+  /** @hidden */
+  accessType: AccessType;
+  /** @hidden */
+  read: boolean;
+  /** @hidden */
+  write: boolean;
+  /** @hidden */
+  onlyOwnData: boolean;
+  /** @hidden */
+  ownerIdField: string;
+
+  /**
+   * Creates a new Permission instance
+   * @param {Object} options - Configuration options
+   *
+   * @param {AccessType} options.type - The type of permission,system defined or custom. check the **Remarks section** for more information.
+   *
+   * @param {boolean} [options.read=false] - Whether read access is granted
+   * @param {boolean} [options.write=false] - Whether write access is granted
+   * @param {boolean} [options.onlyOwnData=false] - Whether access is limited to own data
+   * @param {string} [options.ownerIdField='refId'] - Field name for owner identification
+   */
+  constructor({
+    accessType: type,
+    read = false,
+    write = false,
+    onlyOwnData = false,
+    ownerIdField = 'refId',
+  }: {
+    accessType: AccessType;
+    read?: boolean;
+    write?: boolean;
+    onlyOwnData?: boolean;
+    ownerIdField?: string;
+  }) {
+    this.accessType = type;
+    this.read = read;
+    this.write = write;
+    this.onlyOwnData = onlyOwnData;
+    this.ownerIdField = ownerIdField;
+  }
+}
+
+/**
+ * A comprehensive access control mechanism that manages user permissions through grouped access types.
+ *
+ * Permission groups are a fundamental security concept that define and enforce what actions users
+ * can perform within the system. They provide a flexible and maintainable way to handle authorization
+ * by grouping related access types together.
+ *
+ * These groups enable users to:
+ * 1. Read and write data from collections that match their access types, allowing granular control
+ *    over database operations
+ * 2. Execute specific functions that require matching access types, ensuring that sensitive
+ *    operations are only performed by authorized users
+ * 3. Perform custom developer-defined actions by validating against the user's access types,
+ *    enabling extensible permission-based features
+ *
+ * Permission groups can be configured as default groups for new users or anonymous groups for
+ * unauthenticated access, providing a complete authorization framework.
+ *
+ * @class PermissionGroup
+ * @property {string} title - The title of the permission group
+ * @property {boolean} isDefault - This is a default group, on `true` this permission group will be given to any new user automatically.
+ * @property {boolean} isAnonymous - This is a anonymous group, on `true` will be used for anonymous users.
+ * @property {AccessType[]} allowedAccessTypes - List of valid access types.
+ * @example
+ * ```typescript
+ * const group = new PermissionGroup({
+ *   title: 'Admin',
+ *   isDefault: true,
+ *   allowedAccessTypes: ['god_access', 'advanced_settings']
+ * });
+ * ```
+ */
+export class PermissionGroup {
+  /** @hidden */
+  title: string;
+  /** @hidden */
+  isDefault: boolean;
+  /** @hidden */
+  isAnonymous: boolean;
+  /** @hidden */
+  allowedAccessTypes: AccessType[];
+
+  /**
+   * Creates a new PermissionGroup instance
+   * @param {Object} options - Configuration options
+   * @param {string} options.title - The title of the group
+   * @param {boolean} [options.isDefault=false] - Whether this is a default group
+   * @param {boolean} [options.isAnonymous=false] - Whether this group is for anonymous users
+   * @param {AccessType[]} [options.allowedAccessTypes=[]] - List of valid permission types
+   */
+  constructor({
+    title,
+    isDefault = false,
+    isAnonymous = false,
+    allowedAccessTypes = [],
+  }: {
+    title: string;
+    isDefault?: boolean;
+    isAnonymous?: boolean;
+    allowedAccessTypes?: AccessType[];
+  }) {
+    this.title = title;
+    this.isDefault = isDefault;
+    this.isAnonymous = isAnonymous;
+    this.allowedAccessTypes = allowedAccessTypes;
+  }
+}
+
+/**
+ * Provides static access to access type constants
+ * @class AccessTypes
+ */
+export class AccessTypes {
+  /**
+   * Get the string representing read access type
+   * @returns {string} The read access type
+   */
+  static get read(): string {
+    return 'read';
+  }
+
+  /**
+   * Get the string representing write access type
+   * @returns {string} The write access type
+   */
+  static get write(): string {
+    return 'write';
+  }
+}
+
+/**
+ * Provides static access to permission type constants
+ * @class PermissionTypes
+ */
+export class PermissionTypes {
+  /**
+   * Get the string representing god access permission type
+   * @returns {string} The god access permission type
+   */
+  static get god_access(): AccessType {
+    return 'god_access';
+  }
+
+  /**
+   * Get the string representing advanced settings permission type
+   * @returns {string} The advanced settings permission type
+   */
+  static get advanced_settings(): AccessType {
+    return 'advanced_settings';
+  }
+
+  /**
+   * Get the string representing user access permission type
+   * @returns {string} The user access permission type
+   */
+  static get user_access(): AccessType {
+    return 'user_access';
+  }
+
+  /**
+   * Get the string representing upload file access permission type
+   * @returns {string} The upload file access permission type
+   */
+  static get upload_file_access(): AccessType {
+    return 'upload_file_access';
+  }
+
+  /**
+   * Get the string representing remove file access permission type
+   * @returns {string} The remove file access permission type
+   */
+  static get remove_file_access(): AccessType {
+    return 'remove_file_access';
+  }
+}

package/src/class/trigger_operator.ts

@@ -0,0 +1,142 @@
+import { DatabaseOperation } from './database_trigger';
+
+/**
+ * Interface defining a database trigger
+ * @interface Trigger
+ * @property {DatabaseOperation} operation - The database operation that triggers this callback
+ * @property {string} database - The database name to monitor
+ * @property {string} collection - The collection name to monitor
+ * @property {(data: any) => void} callback - Function to execute when trigger conditions are met
+ * @example
+ * ```typescript
+ * const trigger: Trigger = {
+ *   operation: 'insert',
+ *   database: 'myDB',
+ *   collection: 'users',
+ *   callback: (data) => {
+ *     console.log('New user inserted:', data);
+ *   }
+ * };
+ * ```
+ */
+interface Trigger {
+  operation: DatabaseOperation;
+  database: string;
+  collection: string;
+  callback: (data: any) => void;
+}
+
+/**
+ * Singleton class for managing database triggers
+ * Provides functionality to add and execute triggers based on database operations
+ * @class TriggerOperator
+ * @example
+ * ```typescript
+ * // Add a trigger for user insertions
+ * TriggerOperator.instance.addTrigger({
+ *   operation: 'insert',
+ *   database: 'myDB',
+ *   collection: 'users',
+ *   callback: (data) => {
+ *     console.log('New user inserted:', data);
+ *   }
+ * });
+ * ```
+ */
+class TriggerOperator {
+  private triggers: Trigger[] = [];
+  private static _instance: TriggerOperator | null = null;
+
+  private constructor() {}
+
+  /**
+   * Gets the singleton instance of TriggerOperator
+   * @static
+   * @returns {TriggerOperator} The singleton instance
+   */
+  static get instance(): TriggerOperator {
+    if (!TriggerOperator._instance) {
+      TriggerOperator._instance = new TriggerOperator();
+    }
+    return TriggerOperator._instance;
+  }
+
+  /**
+   * Adds a new trigger to the registry
+   * @param {Trigger} trigger - The trigger configuration to add
+   * @throws {Error} If trigger is invalid or already exists
+   * @example
+   * ```typescript
+   * // Add a trigger for document updates
+   * TriggerOperator.instance.addTrigger({
+   *   operation: 'update',
+   *   database: 'myDB',
+   *   collection: 'documents',
+   *   callback: (data) => {
+   *     console.log('Document updated:', data);
+   *   }
+   * });
+   * ```
+   */
+  addTrigger(trigger: Trigger): void {
+    // Validate trigger
+    if (!trigger.operation || !trigger.database || !trigger.collection || !trigger.callback) {
+      throw new Error('Invalid trigger configuration');
+    }
+
+    // Check for duplicate triggers
+    const exists = this.triggers.some(
+      t =>
+        t.operation === trigger.operation &&
+        t.database === trigger.database &&
+        t.collection === trigger.collection
+    );
+
+    if (exists) {
+      throw new Error(
+        `Trigger already exists for operation ${trigger.operation} on ${trigger.database}.${trigger.collection}`
+      );
+    }
+
+    this.triggers.push(trigger);
+  }
+
+  /**
+   * Executes all matching triggers for a given database operation
+   * @param {DatabaseOperation} operation - The database operation that occurred
+   * @param {string} database - The database where the operation occurred
+   * @param {string} collection - The collection where the operation occurred
+   * @param {any} data - The data associated with the operation
+   * @example
+   * ```typescript
+   * // This would typically be called by the database layer
+   * TriggerOperator.instance.call(
+   *   'insert',
+   *   'myDB',
+   *   'users',
+   *   { id: 1, name: 'John' }
+   * );
+   * ```
+   */
+  call(operation: DatabaseOperation, database: string, collection: string, data: any): void {
+    this.triggers.forEach(trigger => {
+      if (
+        operation === trigger.operation &&
+        database === trigger.database &&
+        collection === trigger.collection &&
+        trigger.callback
+      ) {
+        try {
+          trigger.callback(data);
+        } catch (error) {
+          console.error(
+            `Error executing trigger for ${operation} on ${database}.${collection}:`,
+            error
+          );
+        }
+      }
+    });
+  }
+}
+
+export = TriggerOperator.instance;

package/src/class/user.ts

@@ -0,0 +1,199 @@
+import { config } from '../config';
+import { PermissionGroup, AccessType } from './security';
+import { validator as validateObject } from './validator';
+import { Document, Model } from 'mongoose';
+
+/**
+ * User detail interface
+ */
+interface UserDetail {
+  permissionGroup?: string | PermissionGroup;
+  phone?: string;
+  email?: string;
+  password?: string;
+  fullname?: string;
+  type?: string;
+  [key: string]: any;
+}
+
+/**
+ * User class representing a user in the system
+ *
+ * @public
+ */
+export class User {
+  id: string;
+  permissionGroup: string;
+  phone: string;
+  email: string;
+  password: string;
+  type: string;
+  dbModel: any;
+
+  /**
+   * Create a user
+   * @param id - User ID
+   * @param permissionGroup - Permission group name
+   * @param phone - User phone
+   * @param email - User email
+   * @param password - User password
+   * @param type - User type
+   * @param model - Database model
+   *
+   * @hidden
+   */
+  constructor(
+    id: string,
+    permissionGroup: string,
+    phone: string,
+    email: string,
+    password: string,
+    type: string,
+    model: any
+  ) {
+    this.id = id;
+    this.permissionGroup = permissionGroup;
+    this.email = email;
+    this.phone = phone;
+    this.password = password;
+    this.type = type;
+    this.dbModel = model;
+  }
+
+  /**
+   * Get brief user information
+   * @returns Brief user info object
+   */
+  getBrief(): UserDetail {
+    const permissionGroup = config.permissionGroups?.find(
+      group => group.title === this.permissionGroup
+    );
+
+    if (!permissionGroup) {
+      throw new Error('Permission group not found on user object');
+    }
+
+    const brief: UserDetail = {
+      id: this.id,
+      permissionGroup: permissionGroup,
+      phone: this.phone,
+      email: this.email,
+      type: this.type,
+    };
+
+    return brief;
+  }
+
+  /**
+   * Update user details
+   * @param detail - Object containing user details to update
+   */
+  setNewDetail(detail: UserDetail): void {
+    if (detail.phone) this.phone = detail.phone;
+    if (detail.email) this.email = detail.email;
+    if (detail.password) this.password = detail.password;
+  }
+
+  /**
+   * Check if user has a specific permission
+   * @param accessType - Permission to check
+   * @returns True if user has permission, false otherwise
+   */
+  hasPermission(accessType: string): boolean {
+    const permissionGroup = config.permissionGroups?.find(
+      group => group.title === this.permissionGroup
+    );
+
+    if (permissionGroup == null) return false;
+
+    let key = false;
+
+    if (permissionGroup.allowedAccessTypes) {
+      for (let i = 0; i < permissionGroup.allowedAccessTypes.length; i++) {
+        const userPermissionType = permissionGroup.allowedAccessTypes[i];
+
+        if (userPermissionType === accessType) {
+          key = true;
+          break;
+        }
+      }
+    }
+
+    return key;
+  }
+
+  /**
+   * Save user to database
+   */
+  async save(): Promise<void> {
+    if (!this.dbModel) {
+      throw new Error('User model is not initialized');
+    }
+
+    this.dbModel['permissionGroup'] = this.permissionGroup;
+    this.dbModel['phone'] = this.phone;
+    this.dbModel['email'] = this.email;
+    this.dbModel['password'] = this.password;
+
+    await this.dbModel.save();
+  }
+
+  /**
+   * Load user from database model
+   * @param model - Database model
+   * @returns Promise resolving to User instance
+   */
+  static loadFromModel(model: any): Promise<User> {
+    return new Promise((done, reject) => {
+      // check required fields
+      const isValidData = validateObject(model, '_id permissionGroup');
+
+      if (!isValidData.isValid) {
+        return reject(User.notValid(model));
+      }
+
+      const id = model.id;
+      const permissionGroup = model.permissionGroup;
+      const phone = model.phone;
+      const email = model.email;
+      const password = model.password;
+      const type = model.type;
+
+      //create user
+      const newUser = new User(id, permissionGroup, phone, email, password, type, model);
+      done(newUser);
+    });
+  }
+
+  /**
+   * Create user from model and details
+   * @param model - Mongoose model
+   * @param detail - User details
+   * @returns Promise resolving to User instance
+   */
+  static createFromModel(model: Model<any>, detail: UserDetail): Promise<User> {
+    return new Promise(async (done, reject) => {
+      //create user
+      try {
+        const newUserDoc = await new model(detail).save();
+        const newUser = await User.loadFromModel(newUserDoc);
+        done(newUser);
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Create error for invalid user
+   * @param object - Invalid user object
+   * @returns Error message
+   */
+  static notValid(object: any): string {
+    const error = `user detail are not valid ${JSON.stringify(object)}`;
+    console.error(error);
+    return error;
+  }
+}
+
+export default User;