@modular-rest/server 1.11.13 → 1.11.15

package/src/helper/data_insertion.ts

@@ -0,0 +1,94 @@
+import * as DataProvider from '../services/data_provider/service';
+import {
+  getDefaultAnonymousPermissionGroup,
+  getDefaultAdministratorPermissionGroup,
+} from '../services/user_manager/permissionManager';
+import * as userManager from '../services/user_manager/service';
+
+/**
+ * Admin user credentials interface
+ * @interface AdminCredentials
+ * @property {string} email - Admin user email address
+ * @property {string} password - Admin user password
+ */
+interface AdminCredentials {
+  email: string;
+  password: string;
+}
+
+/**
+ * Creates default system users if they don't exist
+ * @function createAdminUser
+ * @param {AdminCredentials} credentials - Admin user credentials
+ * @returns {Promise<void>} A promise that resolves when the operation is complete
+ * @throws {Error} If admin credentials are invalid or if the operation fails
+ * @description
+ * This function performs the following operations:
+ * 1. Checks if an anonymous user exists, creates one if it doesn't
+ * 2. Checks if an administrator user exists, creates one if it doesn't
+ * 3. Uses the provided credentials for the administrator user
+ *
+ * @example
+ * ```typescript
+ * // Create default system users
+ * await createAdminUser({
+ *   email: 'admin@example.com',
+ *   password: 'secure-password'
+ * });
+ *
+ * // The function will:
+ * // 1. Create an anonymous user if it doesn't exist
+ * // 2. Create an admin user with the provided credentials if it doesn't exist
+ * // 3. Do nothing if both users already exist
+ * ```
+ */
+export async function createAdminUser({ email, password }: AdminCredentials): Promise<void> {
+  const authModel = DataProvider.getCollection('cms', 'auth');
+
+  try {
+    const isAnonymousExisted = await authModel.countDocuments({ type: 'anonymous' }).exec();
+
+    const isAdministratorExisted = await authModel
+      .countDocuments({ type: 'user', email: email })
+      .exec();
+
+    if (isAnonymousExisted === 0) {
+      await userManager.main.registerUser({
+        permissionGroup: getDefaultAnonymousPermissionGroup().title,
+        email: '',
+        phone: '',
+        password: '',
+        type: 'anonymous',
+      });
+      // await new authModel({
+      //   permission: getDefaultAnonymousPermissionGroup().title,
+      //   email: "",
+      //   phone: "",
+      //   password: "",
+      //   type: "anonymous",
+      // }).save();
+    }
+
+    if (isAdministratorExisted === 0) {
+      if (!email || !password) {
+        return Promise.reject('Invalid email or password for admin user.');
+      }
+
+      await userManager.main.registerUser({
+        permissionGroup: getDefaultAdministratorPermissionGroup().title,
+        email: email,
+        password: password,
+        type: 'user',
+      });
+
+      // await new authModel({
+      //   permission: getDefaultAdministratorPermissionGroup().title,
+      //   email: email,
+      //   password: password,
+      //   type: "user",
+      // }).save();
+    }
+  } catch (e) {
+    return Promise.reject(e);
+  }
+}

package/src/helper/presetup_services.ts

@@ -0,0 +1,96 @@
+import * as DataInsertion from './data_insertion';
+import * as JWT from '../services/jwt/service';
+import * as FileService from '../services/file/service';
+import generateKeypair from 'keypair';
+
+/**
+ * Setup options interface for initializing required services
+ * @interface SetupOptions
+ * @property {Object} [keypair] - JWT keypair configuration
+ * @property {string} keypair.private - Private key for JWT signing
+ * @property {string} keypair.public - Public key for JWT verification
+ * @property {Object} adminUser - Admin user configuration
+ * @property {string} adminUser.email - Admin user email address
+ * @property {string} adminUser.password - Admin user password
+ * @property {string} [uploadDirectory] - Directory for file uploads
+ */
+interface SetupOptions {
+  keypair?: {
+    private: string;
+    public: string;
+  };
+  adminUser: {
+    email: string;
+    password: string;
+  };
+  uploadDirectory?: string;
+}
+
+/**
+ * Sets up required services for the application to run
+ * @function setup
+ * @param {SetupOptions} options - Setup configuration options
+ * @returns {Promise<void>} A promise that resolves when setup is complete
+ * @throws {Error} If admin user configuration is missing or if setup fails
+ * @description
+ * This function performs the following setup operations:
+ * 1. Configures JWT with provided or generated keypair
+ * 2. Creates default system users (admin and anonymous)
+ * 3. Configures file upload directory if specified
+ *
+ * @example
+ * ```typescript
+ * // Setup with custom keypair
+ * await setup({
+ *   keypair: {
+ *     private: 'your-private-key',
+ *     public: 'your-public-key'
+ *   },
+ *   adminUser: {
+ *     email: 'admin@example.com',
+ *     password: 'secure-password'
+ *   },
+ *   uploadDirectory: './uploads'
+ * });
+ *
+ * // Setup with auto-generated keypair
+ * await setup({
+ *   adminUser: {
+ *     email: 'admin@example.com',
+ *     password: 'secure-password'
+ *   }
+ * });
+ * ```
+ */
+export async function setup({ keypair, adminUser, uploadDirectory }: SetupOptions): Promise<void> {
+  /**
+   * Json web Token
+   *
+   * Setup private and public keys for JWT module
+   */
+  let keyPairToUse = keypair;
+  if (!keyPairToUse) {
+    // generate new keypair
+    keyPairToUse = generateKeypair();
+  }
+
+  JWT.main.setKies(keyPairToUse.private, keyPairToUse.public);
+
+  if (!adminUser) {
+    throw new Error('Admin user is not supported in TypeScript version');
+  }
+  /**
+   * Data Insertion
+   *
+   * Insert admin user
+   * for the first time
+   */
+  await DataInsertion.createAdminUser(adminUser);
+
+  /**
+   * File Service
+   */
+  if (uploadDirectory) {
+    FileService.main.setUploadDirectory(uploadDirectory);
+  }
+}

package/src/index.ts

@@ -0,0 +1,146 @@
+// Application
+import { createRest } from './application';
+import { Schema } from 'mongoose';
+
+// Utilities
+import * as paginator from './class/paginator';
+import * as reply from './class/reply';
+import { validator } from './class/validator';
+import { getCollection } from './services/data_provider/service';
+import { defineFunction } from './services/functions/service';
+import TypeCasters from './services/data_provider/typeCasters';
+
+import { main as userManager } from './services/user_manager/service';
+import { main as fileService } from './services/file/service';
+
+// Base class
+import { CollectionDefinition, defineCollection } from './class/collection_definition';
+import { schemas } from './class/db_schemas';
+import DatabaseTrigger from './class/database_trigger';
+import CmsTrigger from './class/cms_trigger';
+import {
+  AccessDefinition,
+  Permission,
+  PermissionTypes,
+  PermissionGroup,
+  AccessTypes,
+} from './class/security';
+import * as middleware from './middlewares';
+
+/**
+ * @description Creates a new REST API instance
+ * @example
+ * ```typescript
+ * const rest = createRest();
+ * ```
+ * @returns A new REST API instance
+ */
+export { createRest };
+
+export { CollectionDefinition, defineCollection };
+
+/**
+ * @description Provides predefined database schemas
+ * @example
+ * ```typescript
+ * const userSchema = new Schema({
+ *   name: String,
+ *   avatar: Schemas.file
+ * });
+ * ```
+ */
+export { schemas };
+
+/**
+ * @description Mongoose Schema class for defining data models
+ */
+export { Schema };
+
+/**
+ * @description Handles database triggers and events
+ * @example
+ * ```typescript
+ * const trigger = new DatabaseTrigger('insert-one', (data) => {
+ *   // Handle insert event
+ * });
+ * ```
+ */
+export { DatabaseTrigger };
+
+/**
+ * @description Handles CMS triggers and events
+ */
+export { CmsTrigger };
+
+/**
+ * @description Security and access control definitions
+ * @example
+ * ```typescript
+ * const permission = new Permission({
+ *   type: 'user_access',
+ *   read: true,
+ *   write: true
+ * });
+ * ```
+ */
+export { AccessDefinition, Permission, PermissionTypes, PermissionGroup, AccessTypes };
+
+/**
+ * @description Defines custom functions for the API
+ * @example
+ * ```typescript
+ * defineFunction('sendEmail', async (data) => {
+ *   // Send email logic
+ * });
+ * ```
+ */
+export { defineFunction };
+
+/**
+ * @description Type casting utilities for data transformation
+ */
+export { TypeCasters };
+
+/**
+ * @description Input validation utilities
+ */
+export { validator };
+
+/**
+ * @description Response handling utilities
+ */
+export { reply };
+
+/**
+ * @description Pagination utilities
+ */
+export { paginator };
+
+/**
+ * @description Database collection access utilities
+ */
+export { getCollection };
+
+/**
+ * @description File handling utilities
+ * @example
+ * ```typescript
+ * const file = await fileService.getFile('fileId');
+ * const link = fileService.getFileLink('fileId');
+ * ```
+ */
+export { fileService };
+
+/**
+ * @description Middleware utilities
+ */
+export { middleware };
+
+/**
+ * @description User management utilities
+ * @example
+ * ```typescript
+ * const user = await userManager.getUserById('userId');
+ * ```
+ */
+export { userManager };

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',
+  },
+});