@modular-rest/server 1.11.13 → 1.12.0

package/dist/services/functions/service.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.name = void 0;
+exports.defineFunction = defineFunction;
+exports.runFunction = runFunction;
+exports.addFunction = addFunction;
+/**
+ * Service name constant
+ * @constant {string}
+ */
+exports.name = 'functions';
+/**
+ * Storage for registered functions
+ * @private
+ */
+const functions = [];
+/**
+ * To define a function you need to create a `functions.[js|ts]` in each module of your app and return am array called `functions`, and then define all your functions with calling the `defineFunction` method.
+ *
+ * The `defineFunction` method serves as a core utility for creating custom functions dynamically. This method allows you to specify various parameters, including the name of the function, the permissions required for access, and the corresponding logic that should be executed when the function is invoked.
+ *
+ * @summary
+ * Define a server function to be called by clients.
+ *
+ * @param {DefinedFunction} options - The function definition options. See {@link DefinedFunction} for detailed parameter descriptions.
+ * @expandType DefinedFunction
+ *
+ * @returns {Object} The defined function object which system will use to generate a router for the function, generall the client library will use the router to call the function.
+ * @throws {Error} If function name already exists, permission types are missing, or callback is invalid
+ *
+ * @example
+ * Here is an example illustrating how to use the `defineFunction` method effectively:
+ * ```typescript
+ * // /modules/myModule/functions.ts
+ *
+ * import { defineFunction } from "@modular-rest/server";
+ *
+ * const getServerTime = defineFunction({
+ *   name: "getServerTime",
+ *   permissionTypes: ["anonymous_access"],
+ *   callback: (params) => {
+ *     // return your data only
+ *     return `
+ *       Welcome, ${params.username}!
+ *       The current server time is ${new Date().toLocaleString()}.
+ *     `;
+ *
+ *     // error handling,
+ *     // client gets error code 400, and the message
+ *     // throw new Error('An error occurred');
+ *   },
+ * });
+ *
+ * module.exports.functions = [getServerTime];
+ * ```
+ * In this example, we define a function named `getServerTime` that requires the `user` permission type to access. When the function is called, it will return a message containing the current server time and the username of the user who invoked the function.
+ *
+ * ---
+ *
+ * By utilizing the `defineFunction` method, developers are empowered to create custom functionality effortlessly within the Modular REST framework, enhancing both the versatility and security of their applications.
+ */
+function defineFunction(options) {
+    // Check if the function already exists
+    const existingFunction = functions.find(f => f.name === exports.name);
+    if (existingFunction) {
+        throw new Error(`Function with name ${exports.name} already exists`);
+    }
+    // Check if the permission types provided
+    if (!options.permissionTypes || !options.permissionTypes.length) {
+        throw new Error(`Permission types not provided for function ${exports.name}`);
+    }
+    // Check if the callback is a function
+    if (typeof options.callback !== 'function') {
+        throw new Error(`Callback is not a function for function ${exports.name}`);
+    }
+    // Add the function to the list of functions
+    return options;
+}
+/**
+ * Runs a function by name with arguments and user context
+ *
+ * @param {string} name - Name of the function to run
+ * @param {any} args - Arguments to pass to the function
+ * @param {User} user - User attempting to run the function
+ * @returns {Promise<any>} Promise resolving to function result
+ * @throws {Error} If function not found or user lacks required permissions
+ *
+ * @private
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await runFunction('calculateTotal', {
+ *     items: [
+ *       { price: 10 },
+ *       { price: 20 }
+ *     ]
+ *   }, currentUser);
+ *   console.log('Total:', result); // 30
+ * } catch (error) {
+ *   console.error('Function execution failed:', error);
+ * }
+ * ```
+ */
+function runFunction(name, args, user) {
+    return new Promise((resolve, reject) => {
+        const func = functions.find(f => f.name === name);
+        if (!func) {
+            return reject(new Error(`Function with name ${name} not found`));
+        }
+        const hasPermission = func.permissionTypes.some(permissionType => user.hasPermission(permissionType));
+        if (!hasPermission) {
+            const userBrief = user.getBrief();
+            const userPermissions = typeof userBrief.permissionGroup === 'object' && userBrief.permissionGroup
+                ? userBrief.permissionGroup.allowedAccessTypes
+                : 'none';
+            reject(new Error(`User does not have permission to run function ${name}:
+        Function permissions: ${func.permissionTypes}
+        User permissions: ${userPermissions}
+        `));
+        }
+        else {
+            try {
+                resolve(func.callback(args));
+            }
+            catch (e) {
+                reject(e);
+            }
+        }
+    });
+}
+/**
+ * Adds a function to the registry, this method is used for internal use only,
+ * it will add all defined functions to the registry.
+ *
+ * @param {DefinedFunction} func - Function to add
+ * @throws {Error} If function name already exists
+ *
+ * @private
+ *
+ * @example
+ * ```typescript
+ * const myFunction = defineFunction({
+ *   name: 'myFunction',
+ *   permissionTypes: ['user_access'],
+ *   callback: (args) => args.value * 2
+ * });
+ *
+ * addFunction(myFunction);
+ * ```
+ */
+function addFunction(func) {
+    // Check if the function already exists
+    const existingFunction = functions.find(f => f.name === func.name);
+    if (existingFunction) {
+        throw new Error(`Function with name ${func.name} already exists`);
+    }
+    functions.push(func);
+}

package/dist/services/jwt/router.d.ts

@@ -0,0 +1,4 @@
+import Router from 'koa-router';
+declare const name = "verify";
+declare const verify: Router<any, {}>;
+export { name, verify as main };

package/dist/services/jwt/router.js

@@ -0,0 +1,99 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = exports.name = void 0;
+const koa_router_1 = __importDefault(require("koa-router"));
+const validator_1 = require("../../class/validator");
+const reply_1 = require("../../class/reply");
+const service = __importStar(require("./service"));
+const name = 'verify';
+exports.name = name;
+const verify = new koa_router_1.default();
+exports.main = verify;
+verify.post('/token', async (ctx) => {
+    const body = ctx.request.body;
+    // validate result
+    const bodyValidate = (0, validator_1.validateObject)(body, 'token');
+    // fields validation
+    if (!bodyValidate.isValid) {
+        ctx.status = 412;
+        ctx.body = (0, reply_1.create)('e', {
+            e: bodyValidate.requires,
+        });
+        return;
+    }
+    await service.main
+        .verify(body.token)
+        .then(payload => (ctx.body = (0, reply_1.create)('s', { user: payload })))
+        .catch(err => {
+        ctx.status = 412;
+        ctx.body = (0, reply_1.create)('e', { e: err });
+    });
+});
+verify.post('/checkAccess', async (ctx) => {
+    const body = ctx.request.body;
+    // validate result
+    const bodyValidate = (0, validator_1.validateObject)(body, 'token permissionField');
+    // fields validation
+    if (!bodyValidate.isValid) {
+        ctx.status = 412;
+        ctx.body = (0, reply_1.create)('e', {
+            e: bodyValidate.requires,
+        });
+        return;
+    }
+    const payload = await service.main.verify(body.token).catch(err => {
+        console.log(err);
+        ctx.throw(412, err.message);
+    });
+    const userid = payload.id;
+    await global.services.userManager.main
+        .getUserById(userid)
+        .then((user) => {
+        const key = user.hasPermission(body.permissionField);
+        ctx.body = (0, reply_1.create)('s', { access: key });
+    })
+        .catch((err) => {
+        ctx.status = 412;
+        ctx.body = (0, reply_1.create)('e', { e: err });
+    });
+});
+verify.get('/ready', async (ctx) => {
+    // it's health check, so return success
+    ctx.body = (0, reply_1.create)('s', {});
+});

package/dist/services/jwt/service.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Service name constant
+ * @constant {string}
+ */
+export declare const name = "jwt";
+/**
+ * JWT service class for handling JSON Web Token operations
+ * @class JWT
+ * @description
+ * This class provides methods for signing and verifying JSON Web Tokens using RS256 algorithm.
+ * It requires both private and public keys to be set before use.
+ *
+ * @example
+ * ```typescript
+ * // Set up keys
+ * main.setKies(privateKey, publicKey);
+ *
+ * // Sign a token
+ * const token = await main.sign({ userId: '123', role: 'admin' });
+ *
+ * // Verify a token
+ * const decoded = await main.verify(token);
+ * console.log(decoded.userId); // '123'
+ * ```
+ */
+declare class JWT {
+    private privateKey?;
+    private publicKey?;
+    /**
+     * Sets the private and public keys for JWT operations
+     * @param {string} privateKey - Private key for signing tokens (PEM format)
+     * @param {string} publicKey - Public key for verifying tokens (PEM format)
+     * @throws {Error} If either key is invalid
+     * @example
+     * ```typescript
+     * // Using PEM format keys
+     * const privateKey = `-----BEGIN PRIVATE KEY-----
+     * MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSnAgEAAoIBAQC9QFi67s...
+     * -----END PRIVATE KEY-----`;
+     *
+     * const publicKey = `-----BEGIN PUBLIC KEY-----
+     * MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvUBYuu7...
+     * -----END PUBLIC KEY-----`;
+     *
+     * main.setKies(privateKey, publicKey);
+     * ```
+     */
+    setKies(privateKey: string, publicKey: string): void;
+    /**
+     * Signs a payload and creates a JWT token using RS256 algorithm
+     * @param {Record<string, any>} payload - Data to be encoded in the token
+     * @returns {Promise<string>} A promise that resolves to the signed JWT token
+     * @throws {Error} If private key is not set or signing fails
+     * @example
+     * ```typescript
+     * // Sign a token with user data
+     * const token = await main.sign({
+     *   userId: '123',
+     *   role: 'admin',
+     *   exp: Math.floor(Date.now() / 1000) + (60 * 60) // 1 hour expiry
+     * });
+     *
+     * // Sign a token with custom claims
+     * const token = await main.sign({
+     *   sub: 'user123',
+     *   iss: 'myapp.com',
+     *   aud: 'myapp.com',
+     *   iat: Math.floor(Date.now() / 1000)
+     * });
+     * ```
+     */
+    sign(payload: Record<string, any>): Promise<string>;
+    /**
+     * Verifies a JWT token and returns its decoded payload
+     * @param {string} token - JWT token to verify
+     * @returns {Promise<Record<string, any>>} A promise that resolves to the decoded payload
+     * @throws {Error} If public key is not set, token is invalid, or verification fails
+     * @example
+     * ```typescript
+     * try {
+     *   const decoded = await main.verify(token);
+     *   console.log('Token is valid:', decoded);
+     *   // Access decoded data
+     *   const { userId, role } = decoded;
+     * } catch (error) {
+     *   console.error('Token verification failed:', error);
+     * }
+     * ```
+     */
+    verify(token: string): Promise<Record<string, any>>;
+}
+/**
+ * Main JWT service instance
+ * @constant {JWT}
+ */
+export declare const main: JWT;
+export {};

package/dist/services/jwt/service.js

@@ -0,0 +1,135 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = exports.name = void 0;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+/**
+ * Service name constant
+ * @constant {string}
+ */
+exports.name = 'jwt';
+/**
+ * JWT service class for handling JSON Web Token operations
+ * @class JWT
+ * @description
+ * This class provides methods for signing and verifying JSON Web Tokens using RS256 algorithm.
+ * It requires both private and public keys to be set before use.
+ *
+ * @example
+ * ```typescript
+ * // Set up keys
+ * main.setKies(privateKey, publicKey);
+ *
+ * // Sign a token
+ * const token = await main.sign({ userId: '123', role: 'admin' });
+ *
+ * // Verify a token
+ * const decoded = await main.verify(token);
+ * console.log(decoded.userId); // '123'
+ * ```
+ */
+class JWT {
+    /**
+     * Sets the private and public keys for JWT operations
+     * @param {string} privateKey - Private key for signing tokens (PEM format)
+     * @param {string} publicKey - Public key for verifying tokens (PEM format)
+     * @throws {Error} If either key is invalid
+     * @example
+     * ```typescript
+     * // Using PEM format keys
+     * const privateKey = `-----BEGIN PRIVATE KEY-----
+     * MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSnAgEAAoIBAQC9QFi67s...
+     * -----END PRIVATE KEY-----`;
+     *
+     * const publicKey = `-----BEGIN PUBLIC KEY-----
+     * MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvUBYuu7...
+     * -----END PUBLIC KEY-----`;
+     *
+     * main.setKies(privateKey, publicKey);
+     * ```
+     */
+    setKies(privateKey, publicKey) {
+        if (!privateKey || !publicKey) {
+            throw new Error('Both private and public keys are required');
+        }
+        this.privateKey = privateKey;
+        this.publicKey = publicKey;
+    }
+    /**
+     * Signs a payload and creates a JWT token using RS256 algorithm
+     * @param {Record<string, any>} payload - Data to be encoded in the token
+     * @returns {Promise<string>} A promise that resolves to the signed JWT token
+     * @throws {Error} If private key is not set or signing fails
+     * @example
+     * ```typescript
+     * // Sign a token with user data
+     * const token = await main.sign({
+     *   userId: '123',
+     *   role: 'admin',
+     *   exp: Math.floor(Date.now() / 1000) + (60 * 60) // 1 hour expiry
+     * });
+     *
+     * // Sign a token with custom claims
+     * const token = await main.sign({
+     *   sub: 'user123',
+     *   iss: 'myapp.com',
+     *   aud: 'myapp.com',
+     *   iat: Math.floor(Date.now() / 1000)
+     * });
+     * ```
+     */
+    sign(payload) {
+        return new Promise((done, reject) => {
+            const option = { algorithm: 'RS256' };
+            if (!this.privateKey) {
+                return reject(new Error('Private key is not set. Call setKies() first.'));
+            }
+            try {
+                const token = jsonwebtoken_1.default.sign(payload, this.privateKey, option);
+                done(token);
+            }
+            catch (error) {
+                reject(error instanceof Error ? error.message : String(error));
+            }
+        });
+    }
+    /**
+     * Verifies a JWT token and returns its decoded payload
+     * @param {string} token - JWT token to verify
+     * @returns {Promise<Record<string, any>>} A promise that resolves to the decoded payload
+     * @throws {Error} If public key is not set, token is invalid, or verification fails
+     * @example
+     * ```typescript
+     * try {
+     *   const decoded = await main.verify(token);
+     *   console.log('Token is valid:', decoded);
+     *   // Access decoded data
+     *   const { userId, role } = decoded;
+     * } catch (error) {
+     *   console.error('Token verification failed:', error);
+     * }
+     * ```
+     */
+    verify(token) {
+        return new Promise((done, reject) => {
+            const option = { algorithm: 'RS256' };
+            if (!this.publicKey) {
+                return reject(new Error('Public key is not set. Call setKies() first.'));
+            }
+            try {
+                const decoded = jsonwebtoken_1.default.verify(token, this.publicKey, option);
+                done(decoded);
+            }
+            catch (error) {
+                reject(error instanceof Error ? error.message : String(error));
+            }
+        });
+    }
+}
+/**
+ * Main JWT service instance
+ * @constant {JWT}
+ */
+exports.main = new JWT();

package/dist/services/user_manager/db.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/user_manager/db.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const mongoose_1 = require("mongoose");
+const collection_definition_1 = require("../../class/collection_definition");
+const security_1 = require("../../class/security");
+const config_1 = require("../../config");
+const trigger_operator_1 = __importDefault(require("../../class/trigger_operator"));
+const authSchema = new mongoose_1.Schema({
+    permissionGroup: String,
+    email: String,
+    phone: String,
+    password: String,
+    type: { type: String, default: 'user', enum: ['user', 'anonymous'] },
+}, { timestamps: true });
+authSchema.index({ email: 1 }, { unique: true });
+authSchema.pre(['save', 'updateOne'], function (next) {
+    // Encode the password before saving
+    if (this.isModified && this.isModified('password')) {
+        this.password = Buffer.from(this.password).toString('base64');
+    }
+    next();
+});
+authSchema.post('save', function (doc, next) {
+    trigger_operator_1.default.call('insert-one', 'cms', 'auth', {
+        query: null,
+        queryResult: doc._doc,
+    });
+    next();
+});
+authSchema.post('findOneAndUpdate', function (doc, next) {
+    trigger_operator_1.default.call('update-one', 'cms', 'auth', {
+        query: null,
+        queryResult: doc._doc,
+    });
+    next();
+});
+authSchema.post('updateOne', function (result, next) {
+    trigger_operator_1.default.call('update-one', 'cms', 'auth', {
+        query: null,
+        queryResult: result,
+    });
+    next();
+});
+authSchema.post('findOneAndDelete', function (doc, next) {
+    trigger_operator_1.default.call('remove-one', 'cms', 'auth', {
+        query: null,
+        queryResult: doc._doc,
+    });
+    next();
+});
+authSchema.post('deleteOne', function (result, next) {
+    trigger_operator_1.default.call('remove-one', 'cms', 'auth', {
+        query: null,
+        queryResult: result,
+    });
+    next();
+});
+module.exports = [
+    new collection_definition_1.CollectionDefinition({
+        database: 'cms',
+        collection: 'auth',
+        schema: authSchema,
+        permissions: [
+            new security_1.Permission({
+                accessType: security_1.PermissionTypes.advanced_settings,
+                read: true,
+                write: true,
+            }),
+        ],
+        triggers: config_1.config.authTriggers || [],
+    }),
+];

package/dist/services/user_manager/permissionManager.d.ts

@@ -0,0 +1,19 @@
+import { PermissionGroup } from '../../class/security';
+/**
+ * Get the default permission group
+ * @returns Default permission group
+ * @throws Error if default permission group not found
+ */
+export declare function getDefaultPermissionGroups(): PermissionGroup;
+/**
+ * Get the anonymous permission group
+ * @returns Anonymous permission group
+ * @throws Error if anonymous permission group not found
+ */
+export declare function getDefaultAnonymousPermissionGroup(): PermissionGroup;
+/**
+ * Get the administrator permission group
+ * @returns Administrator permission group
+ * @throws Error if administrator permission group not found
+ */
+export declare function getDefaultAdministratorPermissionGroup(): PermissionGroup;

package/dist/services/user_manager/permissionManager.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultPermissionGroups = getDefaultPermissionGroups;
+exports.getDefaultAnonymousPermissionGroup = getDefaultAnonymousPermissionGroup;
+exports.getDefaultAdministratorPermissionGroup = getDefaultAdministratorPermissionGroup;
+const config_1 = require("../../config");
+/**
+ * Get the default permission group
+ * @returns Default permission group
+ * @throws Error if default permission group not found
+ */
+function getDefaultPermissionGroups() {
+    const defaultPermissionGroups = config_1.config.permissionGroups?.find(group => group.isDefault);
+    if (defaultPermissionGroups == null) {
+        throw new Error('Default permission group not found');
+    }
+    return defaultPermissionGroups;
+}
+/**
+ * Get the anonymous permission group
+ * @returns Anonymous permission group
+ * @throws Error if anonymous permission group not found
+ */
+function getDefaultAnonymousPermissionGroup() {
+    const anonymousPermission = config_1.config.permissionGroups?.find(group => group.isAnonymous);
+    if (anonymousPermission == null) {
+        throw new Error('Anonymous permission group not found');
+    }
+    return anonymousPermission;
+}
+/**
+ * Get the administrator permission group
+ * @returns Administrator permission group
+ * @throws Error if administrator permission group not found
+ */
+function getDefaultAdministratorPermissionGroup() {
+    const administratorPermission = config_1.config.permissionGroups?.find(group => group.title.toString() === 'administrator');
+    if (administratorPermission == null) {
+        throw new Error('Administrator permission group not found');
+    }
+    return administratorPermission;
+}

package/dist/services/user_manager/router.d.ts

@@ -0,0 +1,4 @@
+import Router from 'koa-router';
+declare const name = "user";
+declare const userManager: Router<any, {}>;
+export { name, userManager as main };