@modular-rest/server 1.11.13 → 1.11.14

package/src/middlewares.ts

@@ -0,0 +1,75 @@
+import { Context, Next } from 'koa';
+import { validator as validateObject } from './class/validator';
+import * as userManager from './services/user_manager/service';
+import User from './class/user';
+
+/**
+ * Authentication middleware that secures routes by validating user tokens and managing access control.
+ *
+ * This middleware performs several key functions:
+ * 1. Validates that the incoming request contains an authorization token in the header
+ * 2. Verifies the token is valid by checking against the user management service
+ * 3. Retrieves the associated user object if the token is valid
+ * 4. Attaches the authenticated {@link User} object on ctx.state.user for use in subsequent middleware/routes
+ * 5. Throws appropriate HTTP errors (401, 412) if authentication fails
+ *
+ * The middleware integrates with the permission system to enable role-based access control.
+ * The attached user object provides methods like hasPermission() to check specific permissions.
+ *
+ * Common usage patterns:
+ * - Protecting sensitive API endpoints
+ * - Implementing role-based access control
+ * - Getting the current authenticated user
+ * - Validating user permissions before allowing actions
+ *
+ * @throws {Error} 401 - If no authorization header is present
+ * @throws {Error} 412 - If token validation fails
+ * @param ctx - Koa Context object containing request/response data
+ * @param next - Function to invoke next middleware
+ *
+ * @example
+ * ```typescript
+ * // Inside the router.ts file
+ * import { auth } from '@modular-rest/server';
+ * import { Router } from 'koa-router';
+ *
+ * const name = 'flowers';
+ *
+ * const flowerRouter = new Router();
+ *
+ * flowerRouter.get('/list', auth, (ctx) => {
+ *  // Get the authenticated user
+ *  const user = ctx.state.user;
+ *
+ *  // Then you can check the user's role and permission
+ *  if(user.hasPermission('get_flower')) {
+ *    ctx.body = 'This is a list of flowers: Rose, Lily, Tulip';
+ *  } else {
+ *    ctx.status = 403;
+ *    ctx.body = 'You are not authorized to access this resource';
+ *  }
+ * });
+ *
+ * module.exports.name = name;
+ * module.exports.main = flowerRouter;
+ * ```
+ */
+export async function auth(ctx: Context, next: Next): Promise<void> {
+  const headers = ctx.header;
+  const headersValidated = validateObject(headers, 'authorization');
+
+  if (!headersValidated.isValid) ctx.throw(401, 'authentication is required');
+
+  const token = headers.authorization as string;
+
+  await userManager.main
+    .getUserByToken(token)
+    .then(async (user: User) => {
+      ctx.state.user = user;
+      await next();
+    })
+    .catch(err => {
+      console.log(err);
+      ctx.throw(err.status || 412, err.message);
+    });
+}

package/src/play-test.ts

@@ -0,0 +1,8 @@
+import { createRest } from './application';
+
+const app = createRest({
+  adminUser: {
+    email: 'admin@example.com',
+    password: 'password',
+  },
+});

package/src/services/data_provider/router.ts

@@ -0,0 +1,191 @@
+import { AccessTypes } from '../../class/security';
+import Router from 'koa-router';
+import { validateObject } from '../../class/validator';
+import { create as reply } from '../../class/reply';
+import nestedProperty from 'nested-property';
+import * as service from './service';
+import * as middleware from '../../middlewares';
+import { Context, Next } from 'koa';
+
+const name = 'data-provider';
+
+const dataProvider = new Router();
+
+dataProvider.use('/', middleware.auth, async (ctx: Context, next: Next) => {
+  const body = ctx.request.body;
+  const bodyValidated = validateObject(body, 'database collection');
+
+  // fields validation
+  if (!bodyValidated.isValid) {
+    ctx.throw(412, JSON.stringify(reply('e', { error: bodyValidated.requires })));
+  }
+
+  // type caster
+  if (body.types && body.hasOwnProperty(body.bodyKey || '.')) {
+    const bodyKey = body.bodyKey;
+    for (const key in body.types) {
+      if (body.types.hasOwnProperty(key) && typeof body.types[key] == 'object') {
+        const typeDetail = body.types[key];
+
+        try {
+          const value = nestedProperty.get(body[bodyKey], typeDetail.path);
+          const newProperty =
+            service.TypeCasters[typeDetail.type as keyof typeof service.TypeCasters](value);
+          nestedProperty.set(body[bodyKey], typeDetail.path, newProperty);
+          console.log('newProperty', newProperty, JSON.stringify(body[bodyKey]));
+        } catch (e) {
+          console.log('type caster error', e);
+        }
+      }
+    }
+  }
+
+  await next();
+});
+
+dataProvider.post('/find', async (ctx: Context) => {
+  const body = ctx.request.body;
+  const bodyValidate = validateObject(body, 'database collection query');
+
+  // fields validation
+  if (!bodyValidate.isValid) {
+    ctx.throw(412, JSON.stringify(reply('e', { error: bodyValidate.requires })));
+  }
+
+  // access validation
+  const hasAccess = service.checkAccess(
+    body.database,
+    body.collection,
+    AccessTypes.read,
+    body.query,
+    ctx.state.user
+  );
+  if (!hasAccess) {
+    console.log(body);
+    console.log(ctx.state.user.permission);
+    ctx.throw(403, 'access denied');
+  }
+
+  // collection validation
+  const collection = service.getCollection(body.database, body.collection);
+  if (collection == null) {
+    ctx.throw(412, JSON.stringify(reply('e', { error: 'wrong database or collection' })));
+  }
+
+  // operate on db
+  let queryRequest = collection.find(body.query, body.projection);
+
+  if (body.options) {
+    queryRequest = service.performAdditionalOptionsToQueryObject(queryRequest, body.options);
+  }
+
+  if (body.populates) {
+    try {
+      queryRequest = service.performPopulateToQueryObject(queryRequest, body.populates);
+    } catch (err) {
+      ctx.status = 412;
+      ctx.body = err;
+    }
+  }
+
+  await queryRequest
+    .exec()
+    .then(async docs => {
+      ctx.body = { data: docs };
+    })
+    .catch(err => {
+      ctx.status = err.status || 500;
+      ctx.body = err.message;
+    });
+});
+
+dataProvider.post('/find-one', async (ctx: Context) => {
+  const body = ctx.request.body;
+  const bodyValidate = validateObject(body, 'database collection query');
+
+  // fields validation
+  if (!bodyValidate.isValid) {
+    ctx.throw(412, JSON.stringify(reply('e', { error: bodyValidate.requires })));
+  }
+
+  // access validation
+  const hasAccess = service.checkAccess(
+    body.database,
+    body.collection,
+    AccessTypes.read,
+    body.query,
+    ctx.state.user
+  );
+  if (!hasAccess) ctx.throw(403, 'access denied');
+
+  // collection validation
+  const collection = service.getCollection(body.database, body.collection);
+  if (collection == null) {
+    ctx.throw(412, JSON.stringify(reply('e', { error: 'wrong database or collection' })));
+  }
+
+  // operate on db
+  let queryRequest = collection.findOne(body.query, body.projection, body.options);
+
+  if (body.options) {
+    queryRequest = service.performAdditionalOptionsToQueryObject(queryRequest, body.options);
+  }
+
+  if (body.populates) {
+    try {
+      queryRequest = service.performPopulateToQueryObject(queryRequest, body.populates);
+    } catch (err) {
+      ctx.status = 412;
+      ctx.body = err;
+    }
+  }
+
+  // operate on db
+  await queryRequest
+    .exec()
+    .then(async doc => {
+      ctx.body = { data: doc };
+    })
+    .catch(err => {
+      ctx.status = err.status || 500;
+      ctx.body = err.message;
+    });
+});
+
+dataProvider.post('/count', async (ctx: Context) => {
+  const body = ctx.request.body;
+  const bodyValidate = validateObject(body, 'database collection query');
+
+  // fields validation
+  if (!bodyValidate.isValid) {
+    ctx.throw(412, JSON.stringify(reply('e', { error: bodyValidate.requires })));
+  }
+
+  // access validation
+  const hasAccess = service.checkAccess(
+    body.database,
+    body.collection,
+    AccessTypes.read,
+    body.query,
+    ctx.state.user
+  );
+  if (!hasAccess) ctx.throw(403, 'access denied');
+
+  // collection validation
+  const collection = service.getCollection(body.database, body.collection);
+  if (collection == null) {
+    ctx.throw(412, JSON.stringify(reply('e', { error: 'wrong database or collection' })));
+  }
+
+  await collection
+    .countDocuments(body.query)
+    .then(count => {
+      ctx.body = { data: count };
+    })
+    .catch(err => {
+      ctx.status = err.status || 500;
+      ctx.body = err.message;
+    });
+});
+
+export { name, dataProvider as main };

package/src/services/data_provider/service.ts

@@ -0,0 +1,305 @@
+import mongoose, { Connection, Model, PopulateOptions, Query } from 'mongoose';
+import { AccessTypes, AccessDefinition, Permission } from '../../class/security';
+import triggerOperator from '../../class/trigger_operator';
+import TypeCasters from './typeCasters';
+import { config } from '../../config';
+import { CollectionDefinition } from '../../class/collection_definition';
+import { User } from '../../class/user';
+
+/**
+ * Service name constant
+ * @constant {string}
+ */
+export const name = 'dataProvider';
+
+// Set mongoose options
+mongoose.set('useCreateIndex', true);
+
+// Database connections and collections storage
+const connections: Record<string, Connection> = {};
+const collections: Record<string, Record<string, Model<any>>> = {};
+const permissionDefinitions: Record<string, Record<string, AccessDefinition>> = {};
+
+/**
+ * MongoDB connection options
+ * @interface MongoOption
+ * @property {string} [dbPrefix] - Prefix for database names
+ * @property {string} mongoBaseAddress - MongoDB connection URL
+ */
+export interface MongoOption {
+  dbPrefix?: string;
+  mongoBaseAddress: string;
+}
+
+/**
+ * Collection definition options
+ * @interface CollectionDefinitionOption
+ * @property {CollectionDefinition[]} list - List of collection definitions
+ * @property {MongoOption} mongoOption - MongoDB connection options
+ */
+interface CollectionDefinitionListOption {
+  list: CollectionDefinition[];
+  mongoOption: MongoOption;
+}
+
+/**
+ * Connects to a database and sets up collections based on collection definitions
+ * @function connectToDatabaseByCollectionDefinitionList
+ * @param {string} dbName - Name of the database to connect to
+ * @param {CollectionDefinition[]} [collectionDefinitionList=[]] - List of collection definitions
+ * @param {MongoOption} mongoOption - MongoDB connection options
+ * @returns {Promise<void>} A promise that resolves when the connection is established
+ * @throws {Error} If triggers are not properly configured
+ * @private
+ */
+function connectToDatabaseByCollectionDefinitionList(
+  dbName: string,
+  collectionDefinitionList: CollectionDefinition[] = [],
+  mongoOption: MongoOption
+): Promise<void> {
+  return new Promise((done, reject) => {
+    // Create db connection
+    const fullDbName = (mongoOption.dbPrefix || '') + dbName;
+    const connectionString = mongoOption.mongoBaseAddress;
+
+    console.info(`- Connecting to database: ${fullDbName}`);
+
+    const connection = mongoose.createConnection(connectionString, {
+      useUnifiedTopology: true,
+      useNewUrlParser: true,
+      dbName: fullDbName,
+    });
+
+    // Store connection
+    connections[dbName] = connection;
+
+    // add db models from schemas
+    collectionDefinitionList.forEach(collectionDefinition => {
+      const collection = collectionDefinition.collection;
+      const schema = collectionDefinition.schema;
+
+      if (collections[dbName] == undefined) collections[dbName] = {};
+
+      if (permissionDefinitions[dbName] == undefined) permissionDefinitions[dbName] = {};
+
+      // create model from schema
+      // and store in on global collection object
+      const model = connection.model(collection, schema);
+      collections[dbName][collection] = model;
+
+      // define Access Definition from component permissions
+      // and store it on global access definition object
+      permissionDefinitions[dbName][collection] = new AccessDefinition({
+        database: dbName,
+        collection: collection,
+        permissionList: collectionDefinition.permissions,
+      });
+
+      // add trigger
+      if (collectionDefinition.triggers != undefined) {
+        if (!Array.isArray(collectionDefinition.triggers)) {
+          throw new Error('Triggers must be an array');
+        }
+
+        collectionDefinition.triggers.forEach(trigger => {
+          triggerOperator.addTrigger({
+            ...trigger,
+            database: collectionDefinition.database,
+            collection: collectionDefinition.collection,
+          });
+        });
+      }
+    });
+
+    connection.on('connected', () => {
+      console.info(`- ${fullDbName} database has been connected`);
+      done();
+    });
+  });
+}
+
+/**
+ * Adds collection definitions and connects to their respective databases
+ * @function addCollectionDefinitionByList
+ * @param {CollectionDefinitionListOption} options - Collection definition options
+ * @returns {Promise<void>} A promise that resolves when all collections are set up
+ * @example
+ * ```typescript
+ * await addCollectionDefinitionByList({
+ *   list: [
+ *     new CollectionDefinition({
+ *       database: 'myapp',
+ *       collection: 'users',
+ *       schema: userSchema,
+ *       permissions: [new Permission({ type: 'user_access', read: true })]
+ *     })
+ *   ],
+ *   mongoOption: {
+ *     mongoBaseAddress: 'mongodb://localhost:27017',
+ *     dbPrefix: 'myapp_'
+ *   }
+ * });
+ * ```
+ */
+export async function addCollectionDefinitionByList({
+  list,
+  mongoOption,
+}: CollectionDefinitionListOption): Promise<void> {
+  // Group collection definitions by database
+  const dbGroups: Record<string, CollectionDefinition[]> = {};
+  list.forEach(collectionDefinition => {
+    if (!dbGroups[collectionDefinition.database]) {
+      dbGroups[collectionDefinition.database] = [];
+    }
+    dbGroups[collectionDefinition.database].push(collectionDefinition);
+  });
+
+  // Connect to each database
+  const connectionPromises = Object.entries(dbGroups).map(([dbName, collectionDefinitionList]) =>
+    connectToDatabaseByCollectionDefinitionList(dbName, collectionDefinitionList, mongoOption)
+  );
+
+  await Promise.all(connectionPromises);
+}
+
+/**
+ * Gets a Mongoose model for a specific collection
+ * @function getCollection
+ * @param {string} db - Database name
+ * @param {string} collection - Collection name
+ * @returns {Model<T>} Mongoose model for the collection
+ * @throws {Error} If the collection doesn't exist
+ * @example
+ * ```typescript
+ * const userModel = getCollection('myapp', 'users');
+ * const users = await userModel.find();
+ * ```
+ */
+export function getCollection<T>(db: string, collection: string): Model<T> {
+  if (!collections[db] || !collections[db][collection]) {
+    throw new Error(`Collection ${collection} not found in database ${db}`);
+  }
+  return collections[db][collection];
+}
+
+/**
+ * Gets the permission list for a specific operation on a collection
+ * @function _getPermissionList
+ * @param {string} db - Database name
+ * @param {string} collection - Collection name
+ * @param {string} operationType - Type of operation (read/write)
+ * @returns {any[]} List of permissions
+ * @private
+ */
+function _getPermissionList(db: string, collection: string, operationType: string): Permission[] {
+  if (!permissionDefinitions[db] || !permissionDefinitions[db][collection]) {
+    return [];
+  }
+  return permissionDefinitions[db][collection].permissionList;
+}
+
+/**
+ * Checks if a user has access to perform an operation on a collection
+ * @function checkAccess
+ * @param {string} db - Database name
+ * @param {string} collection - Collection name
+ * @param {string} operationType - Type of operation (read/write)
+ * @param {Record<string, any>} queryOrDoc - Query or document being accessed
+ * @param {User} user - User performing the operation
+ * @returns {boolean} Whether the user has access
+ * @example
+ * ```typescript
+ * const hasAccess = checkAccess('myapp', 'users', 'read', {}, currentUser);
+ * if (hasAccess) {
+ *   const users = await getCollection('myapp', 'users').find();
+ * }
+ * ```
+ */
+export function checkAccess(
+  db: string,
+  collection: string,
+  operationType: string,
+  queryOrDoc: Record<string, any>,
+  user: User
+): boolean {
+  const permissionList = _getPermissionList(db, collection, operationType);
+  return permissionList.some(permission => {
+    if (permission.accessType === 'god_access') return true;
+    if (permission.accessType === 'anonymous_access' && user.type === 'anonymous') return true;
+    if (permission.accessType === 'user_access' && user.type === 'user') return true;
+    return false;
+  });
+}
+
+/**
+ * Converts a string ID to a MongoDB ObjectId
+ * @function getAsID
+ * @param {string} strId - String ID to convert
+ * @returns {mongoose.Types.ObjectId | undefined} MongoDB ObjectId or undefined if invalid
+ * @example
+ * ```typescript
+ * const id = getAsID('507f1f77bcf86cd799439011');
+ * if (id) {
+ *   const doc = await collection.findById(id);
+ * }
+ * ```
+ */
+export function getAsID(strId: string): mongoose.Types.ObjectId | undefined {
+  try {
+    return mongoose.Types.ObjectId(strId);
+  } catch (e) {
+    return undefined;
+  }
+}
+
+/**
+ * Applies populate options to a Mongoose query
+ * @function performPopulateToQueryObject
+ * @param {Query<T, any>} queryObj - Mongoose query object
+ * @param {PopulateOptions[]} [popArr=[]] - Array of populate options
+ * @returns {Query<T, any>} Query with populate options applied
+ * @example
+ * ```typescript
+ * const query = collection.find();
+ * const populatedQuery = performPopulateToQueryObject(query, [
+ *   { path: 'author', select: 'name email' }
+ * ]);
+ * ```
+ */
+export function performPopulateToQueryObject<T = any>(
+  queryObj: Query<T, any>,
+  popArr: PopulateOptions[] = []
+): Query<T, any> {
+  popArr.forEach(pop => {
+    queryObj.populate(pop);
+  });
+  return queryObj;
+}
+
+/**
+ * Applies additional options to a Mongoose query
+ * @function performAdditionalOptionsToQueryObject
+ * @param {Query<T, any>} queryObj - Mongoose query object
+ * @param {Record<string, any>} options - Additional query options
+ * @returns {Query<T, any>} Query with additional options applied
+ * @example
+ * ```typescript
+ * const query = collection.find();
+ * const queryWithOptions = performAdditionalOptionsToQueryObject(query, {
+ *   sort: { createdAt: -1 },
+ *   limit: 10
+ * });
+ * ```
+ */
+export function performAdditionalOptionsToQueryObject<T = any>(
+  queryObj: Query<T, any>,
+  options: Record<string, any>
+): Query<T, any> {
+  Object.entries(options).forEach(([key, value]) => {
+    // @ts-ignore
+    queryObj[key](value);
+  });
+  return queryObj;
+}
+
+export { TypeCasters };

package/src/services/data_provider/typeCasters.ts

@@ -0,0 +1,15 @@
+import mongoose from 'mongoose';
+
+/**
+ * Type casting functions for MongoDB types
+ */
+const TypeCasters = {
+  ObjectId: mongoose.Types.ObjectId,
+  Date: (dateValue: string | Date): Date => {
+    const strDate = dateValue.toString();
+    const mongoDateFormateInString = new Date(strDate).toISOString().split('T')[0];
+    return new Date(mongoDateFormateInString);
+  },
+};
+
+export default TypeCasters;

package/src/services/file/db.ts

@@ -0,0 +1,29 @@
+import mongoose from 'mongoose';
+import schemas from '../../class/db_schemas';
+import { CollectionDefinition } from '../../class/collection_definition';
+import { Permission, PermissionTypes } from '../../class/security';
+import { config } from '../../config';
+import { Schema } from 'mongoose';
+
+module.exports = [
+  new CollectionDefinition({
+    database: 'cms',
+    collection: 'file',
+    schema: schemas.file as unknown as Schema,
+    permissions: [
+      new Permission({
+        accessType: PermissionTypes.upload_file_access,
+        read: true,
+        write: true,
+        onlyOwnData: false,
+      }),
+      new Permission({
+        accessType: PermissionTypes.remove_file_access,
+        read: true,
+        write: true,
+        onlyOwnData: false,
+      }),
+    ],
+    triggers: config.fileTriggers || [],
+  }),
+];