@modular-rest/server 1.11.12 → 1.12.0

package/dist/services/user_manager/service.js

@@ -0,0 +1,628 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = exports.name = void 0;
+const user_1 = require("../../class/user");
+const DataProvider = __importStar(require("../data_provider/service"));
+const JWT = __importStar(require("../jwt/service"));
+const permissionManager_1 = require("./permissionManager");
+/**
+ * Service name constant
+ * @constant {string}
+ */
+exports.name = 'userManager';
+/**
+ * User manager class for handling user operations
+
+ * This service provides functionality for managing users, including:
+ * - User registration and authentication
+ * - Password management
+ * - Token generation and verification
+ * - Temporary ID handling for password reset and verification
+ *
+ */
+class UserManager {
+    /**
+     * @hidden
+     */
+    constructor() {
+        /**
+         * @hidden
+         */
+        this.tempIds = {};
+    }
+    /**
+     * Sets a custom method for generating verification codes
+     * @param {Function} generatorMethod - Function that generates verification codes
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * userManager.setCustomVerificationCodeGeneratorMethod((id, type) => {
+     *   return Math.random().toString(36).substring(2, 8).toUpperCase();
+     * });
+     * ```
+     */
+    setCustomVerificationCodeGeneratorMethod(generatorMethod) {
+        this.verificationCodeGeneratorMethod = generatorMethod;
+    }
+    /**
+     * Generates a verification code for a user
+     * @param {string} id - User ID or identifier
+     * @param {string} idType - Type of ID (email, phone)
+     * @returns {string} Verification code
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * const code = userManager.generateVerificationCode('user@example.com', 'email');
+     * // Returns: '123' (default) or custom generated code
+     * ```
+     */
+    generateVerificationCode(id, idType) {
+        if (this.verificationCodeGeneratorMethod)
+            return this.verificationCodeGeneratorMethod(id, idType);
+        // this is default code
+        return '123';
+    }
+    /**
+     * Gets a user by their ID
+     * @param {string} id - The ID of the user
+     * @returns {Promise<User>} Promise resolving to the user
+     * @throws {Error} If user model is not found or user is not found
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * try {
+     *   const user = await userManager.getUserById('user123');
+     *   console.log('User details:', user);
+     * } catch (error) {
+     *   console.error('Failed to get user:', error);
+     * }
+     * ```
+     */
+    getUserById(id) {
+        return new Promise(async (done, reject) => {
+            const userModel = DataProvider.getCollection('cms', 'auth');
+            if (!userModel) {
+                return reject(new Error('User model not found'));
+            }
+            let userDoc;
+            try {
+                userDoc = await userModel.findOne({ _id: id }).select({ password: 0 }).exec();
+            }
+            catch (error) {
+                return reject(error);
+            }
+            if (!userDoc) {
+                return reject(new Error('User not found'));
+            }
+            try {
+                const user = await user_1.User.loadFromModel(userDoc);
+                done(user);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Gets a user by their identity (email or phone)
+     * @param {string} id - The identity of the user
+     * @param {string} idType - The type of the identity (phone or email)
+     * @returns {Promise<User>} Promise resolving to the user
+     * @throws {Error} If user model is not found or user is not found
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * // Get user by email
+     * const user = await userManager.getUserByIdentity('user@example.com', 'email');
+     *
+     * // Get user by phone
+     * const user = await userManager.getUserByIdentity('+1234567890', 'phone');
+     * ```
+     */
+    getUserByIdentity(id, idType) {
+        return new Promise(async (done, reject) => {
+            const userModel = DataProvider.getCollection('cms', 'auth');
+            if (!userModel) {
+                return reject(new Error('User model not found'));
+            }
+            const query = {};
+            if (idType === 'phone')
+                query['phone'] = id;
+            else if (idType === 'email')
+                query['email'] = id;
+            let userDoc;
+            try {
+                userDoc = await userModel.findOne(query).select({ password: 0 }).exec();
+            }
+            catch (error) {
+                return reject(error);
+            }
+            if (!userDoc) {
+                return reject(new Error('User not found'));
+            }
+            try {
+                const user = await user_1.User.loadFromModel(userDoc);
+                done(user);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Gets a user by their JWT token
+     * @param {string} token - The JWT token of the user
+     * @returns {Promise<User>} Promise resolving to the user
+     * @throws {Error} If token is invalid or user is not found
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * try {
+     *   const user = await userManager.getUserByToken('jwt.token.here');
+     *   console.log('Authenticated user:', user);
+     * } catch (error) {
+     *   console.error('Invalid token:', error);
+     * }
+     * ```
+     */
+    async getUserByToken(token) {
+        const decoded = await JWT.main.verify(token);
+        return this.getUserById(decoded.id);
+    }
+    /**
+     * Checks if a verification code is valid
+     * @param {string} id - The ID of the user
+     * @param {string} code - The verification code
+     * @returns {boolean} Whether the verification code is valid
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * const isValid = userManager.isCodeValid('user123', '123');
+     * if (isValid) {
+     *   // Proceed with verification
+     * }
+     * ```
+     */
+    isCodeValid(id, code) {
+        return this.tempIds.hasOwnProperty(id) && this.tempIds[id].code.toString() === code.toString();
+    }
+    /**
+     * Logs in a user and returns their JWT token
+     * @param {string} [id=''] - The ID of the user (email or phone)
+     * @param {string} [idType=''] - The type of the ID (phone or email)
+     * @param {string} [password=''] - The password of the user
+     * @returns {Promise<string>} Promise resolving to the JWT token
+     * @throws {Error} If user is not found or credentials are invalid
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * try {
+     *   // Login with email
+     *   const token = await userManager.loginUser('user@example.com', 'email', 'password123');
+     *
+     *   // Login with phone
+     *   const token = await userManager.loginUser('+1234567890', 'phone', 'password123');
+     * } catch (error) {
+     *   console.error('Login failed:', error);
+     * }
+     * ```
+     */
+    loginUser(id = '', idType = '', password = '') {
+        return new Promise(async (done, reject) => {
+            // Get user model
+            const userModel = DataProvider.getCollection('cms', 'auth');
+            if (!userModel) {
+                return reject(new Error('User model not found'));
+            }
+            /**
+             * Setup query to find by phone or email
+             */
+            const query = {
+                password: Buffer.from(password).toString('base64'),
+                type: 'user',
+            };
+            if (idType === 'phone')
+                query['phone'] = id;
+            else if (idType === 'email')
+                query['email'] = id;
+            // Get from database
+            let gottenFromDB;
+            try {
+                gottenFromDB = await userModel.findOne(query).exec();
+            }
+            catch (error) {
+                return reject(error);
+            }
+            if (!gottenFromDB) {
+                return reject(new Error('User not found'));
+            }
+            try {
+                // Load user
+                const user = await user_1.User.loadFromModel(gottenFromDB);
+                // Get token payload
+                // This is some information about the user.
+                const payload = user.getBrief();
+                // Generate json web token
+                const token = await JWT.main.sign(payload);
+                done(token);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Issues a JWT token for a user by email
+     * @param {string} email - The email of the user
+     * @returns {Promise<string>} Promise resolving to the JWT token
+     * @throws {Error} If user is not found
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * try {
+     *   const token = await userManager.issueTokenForUser('user@example.com');
+     *   console.log('Issued token:', token);
+     * } catch (error) {
+     *   console.error('Failed to issue token:', error);
+     * }
+     * ```
+     */
+    issueTokenForUser(email) {
+        return new Promise(async (done, reject) => {
+            const userModel = DataProvider.getCollection('cms', 'auth');
+            if (!userModel) {
+                return reject(new Error('User model not found'));
+            }
+            const query = { email: email };
+            // Get from database
+            let gottenFromDB;
+            try {
+                gottenFromDB = await userModel.findOne(query).exec();
+            }
+            catch (error) {
+                return reject(error);
+            }
+            if (!gottenFromDB) {
+                return reject(new Error('User not found'));
+            }
+            try {
+                // Load user
+                const user = await user_1.User.loadFromModel(gottenFromDB);
+                // Get token payload
+                const payload = user.getBrief();
+                // Generate json web token
+                const token = await JWT.main.sign(payload);
+                done(token);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Logs in an anonymous user and returns their JWT token
+     * @returns {Promise<string>} Promise resolving to the JWT token
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * const token = await userManager.loginAnonymous();
+     * console.log('Anonymous token:', token);
+     * ```
+     */
+    loginAnonymous() {
+        return new Promise(async (done, reject) => {
+            const userModel = DataProvider.getCollection('cms', 'auth');
+            if (!userModel) {
+                return reject(new Error('User model not found'));
+            }
+            try {
+                // Create anonymous user document
+                const anonymousUserDoc = await userModel.create({
+                    type: 'anonymous',
+                    permissionGroup: (0, permissionManager_1.getDefaultAnonymousPermissionGroup)().title,
+                    phone: '',
+                    email: '',
+                    password: '',
+                });
+                // Load user from document
+                const user = await user_1.User.loadFromModel(anonymousUserDoc);
+                // Get token payload
+                const payload = user.getBrief();
+                // Generate json web token
+                const token = await JWT.main.sign(payload);
+                done(token);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Registers a temporary ID for verification or password reset
+     * @param {string} id - The ID to register
+     * @param {string} type - The type of temporary ID
+     * @param {string} code - The verification code
+     * @returns {string} The registered ID
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * const tempId = userManager.registerTemporaryID('user@example.com', 'password_reset', '123456');
+     * ```
+     */
+    registerTemporaryID(id, type, code) {
+        this.tempIds[id] = {
+            type,
+            code,
+            timestamp: Date.now(),
+        };
+        return id;
+    }
+    /**
+     * Submits a password for a temporary ID
+     * @param {string} id - The temporary ID
+     * @param {string} password - The new password
+     * @param {string} code - The verification code
+     * @returns {Promise<string>} Promise resolving to the JWT token
+     * @throws {Error} If verification code is invalid or user is not found
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * try {
+     *   const token = await userManager.submitPasswordForTemporaryID(
+     *     'user@example.com',
+     *     'newpassword123',
+     *     '123456'
+     *   );
+     *   console.log('Password set successfully');
+     * } catch (error) {
+     *   console.error('Failed to set password:', error);
+     * }
+     * ```
+     */
+    async submitPasswordForTemporaryID(id, password, code) {
+        if (!this.isCodeValid(id, code)) {
+            throw new Error('Invalid verification code');
+        }
+        const userModel = DataProvider.getCollection('cms', 'auth');
+        if (!userModel) {
+            throw new Error('User model not found');
+        }
+        const query = { email: id };
+        // Get from database
+        let gottenFromDB;
+        try {
+            gottenFromDB = await userModel.findOne(query).exec();
+        }
+        catch (error) {
+            throw error;
+        }
+        if (!gottenFromDB) {
+            throw new Error('User not found');
+        }
+        try {
+            // Load user
+            const user = await user_1.User.loadFromModel(gottenFromDB);
+            // Update password
+            user.password = Buffer.from(password).toString('base64');
+            // Save to database
+            await user.save();
+            // Get token payload
+            const payload = user.getBrief();
+            // Generate json web token
+            const token = await JWT.main.sign(payload);
+            // Remove temporary ID
+            delete this.tempIds[id];
+            return token;
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Changes password for a temporary ID
+     * @param {string} id - The temporary ID
+     * @param {string} password - The new password
+     * @param {string} code - The verification code
+     * @returns {Promise<string>} Promise resolving to the JWT token
+     * @throws {Error} If verification code is invalid or user is not found
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * try {
+     *   const token = await userManager.changePasswordForTemporaryID(
+     *     'user@example.com',
+     *     'newpassword123',
+     *     '123456'
+     *   );
+     *   console.log('Password changed successfully');
+     * } catch (error) {
+     *   console.error('Failed to change password:', error);
+     * }
+     * ```
+     */
+    async changePasswordForTemporaryID(id, password, code) {
+        if (!this.isCodeValid(id, code)) {
+            throw new Error('Invalid verification code');
+        }
+        const userModel = DataProvider.getCollection('cms', 'auth');
+        if (!userModel) {
+            throw new Error('User model not found');
+        }
+        const query = { email: id };
+        // Get from database
+        let gottenFromDB;
+        try {
+            gottenFromDB = await userModel.findOne(query).exec();
+        }
+        catch (error) {
+            throw error;
+        }
+        if (!gottenFromDB) {
+            throw new Error('User not found');
+        }
+        try {
+            // Load user
+            const user = await user_1.User.loadFromModel(gottenFromDB);
+            // Update password
+            user.password = Buffer.from(password).toString('base64');
+            // Save to database
+            await user.save();
+            // Get token payload
+            const payload = user.getBrief();
+            // Generate json web token
+            const token = await JWT.main.sign(payload);
+            // Remove temporary ID
+            delete this.tempIds[id];
+            return token;
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Registers a new user
+     * @param {UserRegistrationDetail} detail - User registration details
+     * @returns {Promise<string>} Promise resolving to the JWT token
+     * @throws {Error} If user model is not found or registration fails
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * try {
+     *   const token = await userManager.registerUser({
+     *     email: 'user@example.com',
+     *     password: 'secure123',
+     *     permissionGroup: 'user',
+     *     phone: '+1234567890'
+     *   });
+     *   console.log('User registered successfully');
+     * } catch (error) {
+     *   console.error('Registration failed:', error);
+     * }
+     * ```
+     */
+    registerUser(detail) {
+        return new Promise(async (done, reject) => {
+            const userModel = DataProvider.getCollection('cms', 'auth');
+            if (!userModel) {
+                return reject(new Error('User model not found'));
+            }
+            try {
+                // Create user document
+                const userDoc = await userModel.create({
+                    ...detail,
+                    type: detail.type || 'user',
+                    permissionGroup: detail.permissionGroup || (0, permissionManager_1.getDefaultPermissionGroups)().title,
+                    phone: detail.phone || '',
+                    email: detail.email || '',
+                    password: detail.password ? Buffer.from(detail.password).toString('base64') : '',
+                });
+                // Load user from document
+                const user = await user_1.User.loadFromModel(userDoc);
+                // Get token payload
+                const payload = user.getBrief();
+                // Generate json web token
+                const token = await JWT.main.sign(payload);
+                done(token);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+    /**
+     * Changes a user's password
+     * @param {Record<string, any>} query - Query to find the user
+     * @param {string} newPass - The new password
+     * @returns {Promise<void>} Promise resolving when password is changed
+     * @throws {Error} If user is not found or password change fails
+     * @example
+     * ```typescript
+     * import { userManager } from '@modular-rest/server';
+     *
+     * try {
+     *   await userManager.changePassword(
+     *     { email: 'user@example.com' },
+     *     'newpassword123'
+     *   );
+     *   console.log('Password changed successfully');
+     * } catch (error) {
+     *   console.error('Failed to change password:', error);
+     * }
+     * ```
+     */
+    async changePassword(query, newPass) {
+        const userModel = DataProvider.getCollection('cms', 'auth');
+        if (!userModel) {
+            throw new Error('User model not found');
+        }
+        const userDoc = await userModel.findOne(query).exec();
+        if (!userDoc) {
+            throw new Error('User not found');
+        }
+        const user = await user_1.User.loadFromModel(userDoc);
+        user.password = Buffer.from(newPass).toString('base64');
+        await user.save();
+    }
+    /**
+     * Gets the singleton instance of UserManager
+     * @returns {UserManager} The UserManager instance
+     * @hidden
+     */
+    static get instance() {
+        if (!this._instance) {
+            this._instance = new UserManager();
+        }
+        return this._instance;
+    }
+}
+/**
+ * Main user manager instance
+ * @constant {UserManager}
+ */
+exports.main = UserManager.instance;

package/docs/system-access-type.md

@@ -0,0 +1,26 @@
+### System Access Types
+
+The permission system works by matching the user's assigned permission types (stored in their permission group) against the required permissions defined on collections and functions. This allows for flexible and granular access control.
+
+For example, a collection could be configured to:
+
+- Allow read access for users with 'user_access' permission
+- Restrict write operations to users with 'advanced_settings' permission
+- Only let users who has the 'upload_file_access' access type in their permission group to upload new files
+
+**Built-in Permission Types**
+
+The system comes with the following pre-defined permission types:
+
+| Permission Type      | Description                                                                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `god_access`         | Grants unrestricted super admin access. Users with this permission can perform any operation and access all collections and functions. |
+| `user_access`        | Basic user-level access for authenticated users. Typically grants read access to most collections and basic functionality.             |
+| `upload_file_access` | Required specifically for file upload operations. Users need this permission to upload files to the system.                            |
+| `remove_file_access` | Required for file deletion operations. Users need this permission to remove files from the system.                                     |
+| `anonymous_access`   | Used for unauthenticated access. Defines what operations are available to users who are not logged in.                                 |
+| `advanced_settings`  | Grants access to advanced system configuration and administrative features. More privileged than basic user access.                    |
+
+These permission types can be combined in permission groups to create different access levels. For example, an admin user might have both `advanced_settings` and `user_access`, while a basic user would only have `user_access`.
+
+You can also define custom permission types for specific needs in your application. The permission system is flexible enough to accommodate any additional access types you require.