@faryzal2020/v-perms 1.0.0

package/src/core/PermissionChecker.js

@@ -0,0 +1,203 @@
+import { generateWildcardPatterns } from '../utils/wildcard.js';
+
+/**
+ * Core permission checking logic with caching and wildcard support
+ */
+class PermissionChecker {
+    constructor(adapter, cacheManager, logger) {
+        this.adapter = adapter;
+        this.cache = cacheManager;
+        this.logger = logger;
+    }
+
+    /**
+     * Check if a user has a specific permission
+     * @param {string} userId
+     * @param {string} permissionKey
+     * @returns {Promise<boolean>}
+     */
+    async checkPermission(userId, permissionKey) {
+        this.logger.debug('checkPermission:', userId, permissionKey);
+
+        // Check cache first
+        const cached = await this.cache.get('user', userId, permissionKey);
+        if (cached !== null) {
+            this.logger.debug('Cache hit:', cached);
+            return cached;
+        }
+
+        const result = await this._checkPermissionUncached(userId, permissionKey);
+
+        // Cache result
+        await this.cache.set('user', result, userId, permissionKey);
+
+        return result;
+    }
+
+    /**
+     * Check if a role has a specific permission
+     * @param {string} roleId
+     * @param {string} permissionKey
+     * @returns {Promise<boolean>}
+     */
+    async checkRolePermission(roleId, permissionKey) {
+        this.logger.debug('checkRolePermission:', roleId, permissionKey);
+
+        // Check cache first
+        const cached = await this.cache.get('role', roleId, permissionKey);
+        if (cached !== null) {
+            return cached;
+        }
+
+        const result = await this._checkRolePermissionUncached(roleId, permissionKey);
+
+        // Cache result
+        await this.cache.set('role', result, roleId, permissionKey);
+
+        return result;
+    }
+
+    /**
+     * Check permission without using cache
+     * @private
+     */
+    async _checkPermissionUncached(userId, permissionKey) {
+        // 1. Check user-specific permissions (highest priority)
+        const userPerm = await this.adapter.getUserPermission(userId, permissionKey);
+        if (userPerm !== null) {
+            this.logger.debug('User direct permission:', userPerm.granted);
+            return userPerm.granted;
+        }
+
+        // Check user wildcards
+        const wildcardPatterns = generateWildcardPatterns(permissionKey);
+        for (const pattern of wildcardPatterns) {
+            const userWildcard = await this.adapter.getUserPermission(userId, pattern);
+            if (userWildcard !== null) {
+                this.logger.debug('User wildcard match:', pattern, userWildcard.granted);
+                return userWildcard.granted;
+            }
+        }
+
+        // 2. Get all roles with inheritance
+        const allRoles = await this._getUserRolesWithInheritance(userId);
+        this.logger.debug('User roles (with inheritance):', allRoles.map(r => r.name));
+
+        // 3. Check each role's permissions (by priority)
+        for (const role of allRoles) {
+            const rolePerm = await this.adapter.getRolePermission(role.id, permissionKey);
+            if (rolePerm !== null) {
+                this.logger.debug('Role direct permission:', role.name, rolePerm.granted);
+                return rolePerm.granted;
+            }
+
+            // Check role wildcards
+            for (const pattern of wildcardPatterns) {
+                const roleWildcard = await this.adapter.getRolePermission(role.id, pattern);
+                if (roleWildcard !== null) {
+                    this.logger.debug('Role wildcard match:', role.name, pattern, roleWildcard.granted);
+                    return roleWildcard.granted;
+                }
+            }
+        }
+
+        // 4. Default deny
+        this.logger.debug('No permission found, default deny');
+        return false;
+    }
+
+    /**
+     * Check role permission without using cache
+     * @private
+     */
+    async _checkRolePermissionUncached(roleId, permissionKey) {
+        // Check direct permission
+        const rolePerm = await this.adapter.getRolePermission(roleId, permissionKey);
+        if (rolePerm !== null) {
+            return rolePerm.granted;
+        }
+
+        // Check wildcards
+        const wildcardPatterns = generateWildcardPatterns(permissionKey);
+        for (const pattern of wildcardPatterns) {
+            const roleWildcard = await this.adapter.getRolePermission(roleId, pattern);
+            if (roleWildcard !== null) {
+                return roleWildcard.granted;
+            }
+        }
+
+        // Check inherited roles
+        const inheritedRoles = await this._getRoleInheritanceRecursive(roleId);
+        for (const inheritedRole of inheritedRoles) {
+            const inheritedPerm = await this.adapter.getRolePermission(inheritedRole.id, permissionKey);
+            if (inheritedPerm !== null) {
+                return inheritedPerm.granted;
+            }
+
+            for (const pattern of wildcardPatterns) {
+                const inheritedWildcard = await this.adapter.getRolePermission(inheritedRole.id, pattern);
+                if (inheritedWildcard !== null) {
+                    return inheritedWildcard.granted;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Get all roles for a user including inherited roles
+     * @private
+     */
+    async _getUserRolesWithInheritance(userId) {
+        const directRoles = await this.adapter.getUserRoles(userId);
+        const allRoles = new Map();
+
+        const collectRoles = async (roleId, visited = new Set()) => {
+            if (visited.has(roleId)) return;
+            visited.add(roleId);
+
+            const role = await this.adapter.getRole(roleId);
+            if (!role) return;
+
+            allRoles.set(role.id, role);
+
+            const inheritedRoles = await this.adapter.getRoleInheritance(roleId);
+            for (const inherited of inheritedRoles) {
+                await collectRoles(inherited.inheritsFromId, visited);
+            }
+        };
+
+        for (const role of directRoles) {
+            await collectRoles(role.id);
+        }
+
+        // Sort by priority (highest first)
+        return Array.from(allRoles.values()).sort((a, b) => b.priority - a.priority);
+    }
+
+    /**
+     * Get all inherited roles recursively
+     * @private
+     */
+    async _getRoleInheritanceRecursive(roleId, visited = new Set()) {
+        if (visited.has(roleId)) return [];
+        visited.add(roleId);
+
+        const inheritedRoles = await this.adapter.getRoleInheritance(roleId);
+        const allInherited = [];
+
+        for (const inherited of inheritedRoles) {
+            const role = await this.adapter.getRole(inherited.inheritsFromId);
+            if (role) {
+                allInherited.push(role);
+                const deeper = await this._getRoleInheritanceRecursive(inherited.inheritsFromId, visited);
+                allInherited.push(...deeper);
+            }
+        }
+
+        return allInherited;
+    }
+}
+
+export default PermissionChecker;

package/src/core/PermissionManager.js

@@ -0,0 +1,410 @@
+import {
+    RoleNotFoundError,
+    PermissionNotFoundError,
+} from './errors.js';
+
+/**
+ * High-level API for managing permissions, roles, and users
+ */
+class PermissionManager {
+    constructor(adapter, checker, cacheManager, logger) {
+        this.adapter = adapter;
+        this.checker = checker;
+        this.cache = cacheManager;
+        this.logger = logger;
+    }
+
+    // ==================== Permission Operations ====================
+
+    /**
+     * Create a new permission
+     * @param {string} key - Permission key (e.g., 'endpoint.users.list')
+     * @param {string|null} description - Description of the permission
+     * @param {string|null} category - Category for grouping
+     * @returns {Promise<Object>}
+     */
+    async createPermission(key, description = null, category = null) {
+        this.logger.debug('createPermission:', key, description, category);
+        return await this.adapter.createPermission({ key, description, category });
+    }
+
+    /**
+     * Delete a permission
+     * @param {string} permissionKey
+     * @returns {Promise<boolean>}
+     */
+    async deletePermission(permissionKey) {
+        this.logger.debug('deletePermission:', permissionKey);
+        return await this.adapter.deletePermission(permissionKey);
+    }
+
+    /**
+     * List all permissions
+     * @returns {Promise<Array>}
+     */
+    async listPermissions() {
+        return await this.adapter.listAllPermissions();
+    }
+
+    /**
+     * Get a permission by key
+     * @param {string} permissionKey
+     * @returns {Promise<Object|null>}
+     */
+    async getPermission(permissionKey) {
+        return await this.adapter.getPermission(permissionKey);
+    }
+
+    // ==================== Role Operations ====================
+
+    /**
+     * Create a new role
+     * @param {string} name - Unique role name
+     * @param {string|null} description - Role description
+     * @param {number} priority - Role priority (higher = more important)
+     * @param {boolean} isDefault - Whether to auto-assign to new users
+     * @returns {Promise<Object>}
+     */
+    async createRole(name, description = null, priority = 0, isDefault = false) {
+        this.logger.debug('createRole:', name, description, priority, isDefault);
+        return await this.adapter.createRole({ name, description, priority, isDefault });
+    }
+
+    /**
+     * Delete a role
+     * @param {string} roleIdOrName - Role ID or name
+     * @returns {Promise<boolean>}
+     */
+    async deleteRole(roleIdOrName) {
+        this.logger.debug('deleteRole:', roleIdOrName);
+        const role = await this._resolveRole(roleIdOrName);
+        if (!role) {
+            throw new RoleNotFoundError(roleIdOrName);
+        }
+
+        // Invalidate cache for all users with this role
+        await this.cache.invalidateRole(role.id);
+
+        return await this.adapter.deleteRole(role.id);
+    }
+
+    /**
+     * List all roles
+     * @returns {Promise<Array>}
+     */
+    async listRoles() {
+        return await this.adapter.listAllRoles();
+    }
+
+    /**
+     * Get a role by ID or name
+     * @param {string} roleIdOrName
+     * @returns {Promise<Object|null>}
+     */
+    async getRole(roleIdOrName) {
+        return await this._resolveRole(roleIdOrName);
+    }
+
+    /**
+     * Update a role
+     * @param {string} roleIdOrName
+     * @param {Object} data - Fields to update
+     * @returns {Promise<Object>}
+     */
+    async updateRole(roleIdOrName, data) {
+        const role = await this._resolveRole(roleIdOrName);
+        if (!role) {
+            throw new RoleNotFoundError(roleIdOrName);
+        }
+
+        await this.cache.invalidateRole(role.id);
+        return await this.adapter.updateRole(role.id, data);
+    }
+
+    // ==================== Assignment Operations ====================
+
+    /**
+     * Assign permission to role or user
+     * @param {string} permissionKey - Permission key (supports wildcards)
+     * @param {string} targetId - Role ID/name or User ID
+     * @param {string} targetType - 'role' or 'user'
+     * @returns {Promise<Object>}
+     */
+    async assignPermission(permissionKey, targetId, targetType = 'role') {
+        this.logger.debug('assignPermission:', permissionKey, targetId, targetType);
+
+        if (targetType === 'role') {
+            const role = await this._resolveRole(targetId);
+            if (!role) {
+                throw new RoleNotFoundError(targetId);
+            }
+
+            await this.cache.invalidateRole(role.id);
+            return await this.adapter.assignPermissionToRole(permissionKey, role.id, true);
+        } else if (targetType === 'user') {
+            await this.cache.invalidateUser(targetId);
+            return await this.adapter.assignPermissionToUser(permissionKey, targetId, true);
+        } else {
+            throw new Error(`Invalid targetType: ${targetType}. Must be 'role' or 'user'.`);
+        }
+    }
+
+    /**
+     * Ban/deny permission (set granted=false)
+     * @param {string} permissionKey
+     * @param {string} targetId - Role ID/name or User ID
+     * @param {string} targetType - 'role' or 'user'
+     * @returns {Promise<Object>}
+     */
+    async banPermission(permissionKey, targetId, targetType = 'role') {
+        this.logger.debug('banPermission:', permissionKey, targetId, targetType);
+
+        if (targetType === 'role') {
+            const role = await this._resolveRole(targetId);
+            if (!role) {
+                throw new RoleNotFoundError(targetId);
+            }
+
+            await this.cache.invalidateRole(role.id);
+            return await this.adapter.assignPermissionToRole(permissionKey, role.id, false);
+        } else if (targetType === 'user') {
+            await this.cache.invalidateUser(targetId);
+            return await this.adapter.assignPermissionToUser(permissionKey, targetId, false);
+        } else {
+            throw new Error(`Invalid targetType: ${targetType}. Must be 'role' or 'user'.`);
+        }
+    }
+
+    /**
+     * Remove permission assignment
+     * @param {string} permissionKey
+     * @param {string} targetId - Role ID/name or User ID
+     * @param {string} targetType - 'role' or 'user'
+     * @returns {Promise<boolean>}
+     */
+    async removePermission(permissionKey, targetId, targetType = 'role') {
+        this.logger.debug('removePermission:', permissionKey, targetId, targetType);
+
+        if (targetType === 'role') {
+            const role = await this._resolveRole(targetId);
+            if (!role) {
+                throw new RoleNotFoundError(targetId);
+            }
+
+            await this.cache.invalidateRole(role.id);
+            return await this.adapter.removePermissionFromRole(permissionKey, role.id);
+        } else if (targetType === 'user') {
+            await this.cache.invalidateUser(targetId);
+            return await this.adapter.removePermissionFromUser(permissionKey, targetId);
+        } else {
+            throw new Error(`Invalid targetType: ${targetType}. Must be 'role' or 'user'.`);
+        }
+    }
+
+    /**
+     * Assign role to user
+     * @param {string} roleIdOrName
+     * @param {string} userId
+     * @returns {Promise<Object>}
+     */
+    async assignRole(roleIdOrName, userId) {
+        this.logger.debug('assignRole:', roleIdOrName, userId);
+
+        const role = await this._resolveRole(roleIdOrName);
+        if (!role) {
+            throw new RoleNotFoundError(roleIdOrName);
+        }
+
+        await this.cache.invalidateUser(userId);
+        return await this.adapter.assignRoleToUser(userId, role.id);
+    }
+
+    /**
+     * Remove role from user
+     * @param {string} roleIdOrName
+     * @param {string} userId
+     * @returns {Promise<boolean>}
+     */
+    async removeRole(roleIdOrName, userId) {
+        this.logger.debug('removeRole:', roleIdOrName, userId);
+
+        const role = await this._resolveRole(roleIdOrName);
+        if (!role) {
+            throw new RoleNotFoundError(roleIdOrName);
+        }
+
+        await this.cache.invalidateUser(userId);
+        return await this.adapter.removeRoleFromUser(userId, role.id);
+    }
+
+    /**
+     * Set role inheritance (roleId inherits from inheritFromRoleId)
+     * @param {string} roleIdOrName
+     * @param {string} inheritFromRoleIdOrName
+     * @param {number} priority
+     * @returns {Promise<Object>}
+     */
+    async setRoleInheritance(roleIdOrName, inheritFromRoleIdOrName, priority = 0) {
+        this.logger.debug('setRoleInheritance:', roleIdOrName, inheritFromRoleIdOrName, priority);
+
+        const role = await this._resolveRole(roleIdOrName);
+        if (!role) {
+            throw new RoleNotFoundError(roleIdOrName);
+        }
+
+        const inheritFromRole = await this._resolveRole(inheritFromRoleIdOrName);
+        if (!inheritFromRole) {
+            throw new RoleNotFoundError(inheritFromRoleIdOrName);
+        }
+
+        await this.cache.invalidateRole(role.id);
+        return await this.adapter.setRoleInheritance(role.id, inheritFromRole.id, priority);
+    }
+
+    /**
+     * Remove role inheritance
+     * @param {string} roleIdOrName
+     * @param {string} inheritFromRoleIdOrName
+     * @returns {Promise<boolean>}
+     */
+    async removeRoleInheritance(roleIdOrName, inheritFromRoleIdOrName) {
+        this.logger.debug('removeRoleInheritance:', roleIdOrName, inheritFromRoleIdOrName);
+
+        const role = await this._resolveRole(roleIdOrName);
+        if (!role) {
+            throw new RoleNotFoundError(roleIdOrName);
+        }
+
+        const inheritFromRole = await this._resolveRole(inheritFromRoleIdOrName);
+        if (!inheritFromRole) {
+            throw new RoleNotFoundError(inheritFromRoleIdOrName);
+        }
+
+        await this.cache.invalidateRole(role.id);
+        return await this.adapter.removeRoleInheritance(role.id, inheritFromRole.id);
+    }
+
+    // ==================== Check Operations ====================
+
+    /**
+     * Check if user/role has permission
+     * @param {string} targetId - User ID or Role ID
+     * @param {string} permissionKey
+     * @param {string} targetType - 'user' or 'role'
+     * @returns {Promise<boolean>}
+     */
+    async checkPermission(targetId, permissionKey, targetType = 'user') {
+        if (targetType === 'user') {
+            return await this.checker.checkPermission(targetId, permissionKey);
+        } else if (targetType === 'role') {
+            return await this.checker.checkRolePermission(targetId, permissionKey);
+        } else {
+            throw new Error(`Invalid targetType: ${targetType}. Must be 'user' or 'role'.`);
+        }
+    }
+
+    // ==================== Query Operations ====================
+
+    /**
+     * Get all roles assigned to a user
+     * @param {string} userId
+     * @returns {Promise<Array>}
+     */
+    async getUserRoles(userId) {
+        return await this.adapter.getUserRoles(userId);
+    }
+
+    /**
+     * Get all permissions for a user (direct + role-based)
+     * @param {string} userId
+     * @returns {Promise<Object>} - { direct: [], fromRoles: [] }
+     */
+    async getUserPermissions(userId) {
+        const directPermissions = await this.adapter.getUserDirectPermissions(userId);
+        const roles = await this.adapter.getUserRoles(userId);
+
+        const rolePermissions = [];
+        for (const role of roles) {
+            const permissions = await this.adapter.getRolePermissions(role.id);
+            rolePermissions.push({
+                role: role.name,
+                roleId: role.id,
+                permissions,
+            });
+        }
+
+        return {
+            direct: directPermissions,
+            fromRoles: rolePermissions,
+        };
+    }
+
+    /**
+     * Get all permissions assigned to a role
+     * @param {string} roleIdOrName
+     * @returns {Promise<Array>}
+     */
+    async getRolePermissions(roleIdOrName) {
+        const role = await this._resolveRole(roleIdOrName);
+        if (!role) {
+            throw new RoleNotFoundError(roleIdOrName);
+        }
+        return await this.adapter.getRolePermissions(role.id);
+    }
+
+    /**
+     * Get roles that a role inherits from
+     * @param {string} roleIdOrName
+     * @returns {Promise<Array>}
+     */
+    async getRoleInheritance(roleIdOrName) {
+        const role = await this._resolveRole(roleIdOrName);
+        if (!role) {
+            throw new RoleNotFoundError(roleIdOrName);
+        }
+        return await this.adapter.getRoleInheritance(role.id);
+    }
+
+    // ==================== Cache Operations ====================
+
+    /**
+     * Invalidate cache for a specific user
+     * @param {string} userId
+     */
+    async invalidateUserCache(userId) {
+        return await this.cache.invalidateUser(userId);
+    }
+
+    /**
+     * Invalidate cache for a specific role
+     * @param {string} roleId
+     */
+    async invalidateRoleCache(roleId) {
+        return await this.cache.invalidateRole(roleId);
+    }
+
+    /**
+     * Clear entire cache
+     */
+    async clearAllCache() {
+        return await this.cache.clear();
+    }
+
+    // ==================== Helper Methods ====================
+
+    /**
+     * Resolve role by ID or name
+     * @private
+     */
+    async _resolveRole(roleIdOrName) {
+        // First try as ID
+        let role = await this.adapter.getRole(roleIdOrName);
+        if (role) return role;
+
+        // Then try as name
+        role = await this.adapter.getRoleByName(roleIdOrName);
+        return role;
+    }
+}
+
+export default PermissionManager;

package/src/core/errors.js

@@ -0,0 +1,92 @@
+/**
+ * Base error class for permission-related errors
+ */
+class PermissionError extends Error {
+  constructor(message, code, details = {}) {
+    super(message);
+    this.name = 'PermissionError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/**
+ * Error thrown when a user is not found
+ */
+class UserNotFoundError extends PermissionError {
+  constructor(userId) {
+    super(`User not found: ${userId}`, 'USER_NOT_FOUND', { userId });
+    this.name = 'UserNotFoundError';
+  }
+}
+
+/**
+ * Error thrown when a role is not found
+ */
+class RoleNotFoundError extends PermissionError {
+  constructor(roleId) {
+    super(`Role not found: ${roleId}`, 'ROLE_NOT_FOUND', { roleId });
+    this.name = 'RoleNotFoundError';
+  }
+}
+
+/**
+ * Error thrown when a permission is not found
+ */
+class PermissionNotFoundError extends PermissionError {
+  constructor(permissionKey) {
+    super(`Permission not found: ${permissionKey}`, 'PERMISSION_NOT_FOUND', { permissionKey });
+    this.name = 'PermissionNotFoundError';
+  }
+}
+
+/**
+ * Error thrown when a role is already assigned to a user
+ */
+class RoleAlreadyAssignedError extends PermissionError {
+  constructor(userId, roleId) {
+    super(`Role already assigned to user`, 'ROLE_ALREADY_ASSIGNED', { userId, roleId });
+    this.name = 'RoleAlreadyAssignedError';
+  }
+}
+
+/**
+ * Error thrown when a permission already exists
+ */
+class PermissionAlreadyExistsError extends PermissionError {
+  constructor(permissionKey) {
+    super(`Permission already exists: ${permissionKey}`, 'PERMISSION_EXISTS', { permissionKey });
+    this.name = 'PermissionAlreadyExistsError';
+  }
+}
+
+/**
+ * Error thrown when a role already exists
+ */
+class RoleAlreadyExistsError extends PermissionError {
+  constructor(roleName) {
+    super(`Role already exists: ${roleName}`, 'ROLE_EXISTS', { roleName });
+    this.name = 'RoleAlreadyExistsError';
+  }
+}
+
+/**
+ * Error thrown when circular inheritance is detected
+ */
+class CircularInheritanceError extends PermissionError {
+  constructor(roleId, inheritsFromId) {
+    super(`Circular inheritance detected`, 'CIRCULAR_INHERITANCE', { roleId, inheritsFromId });
+    this.name = 'CircularInheritanceError';
+  }
+}
+
+export {
+  PermissionError,
+  UserNotFoundError,
+  RoleNotFoundError,
+  PermissionNotFoundError,
+  RoleAlreadyAssignedError,
+  PermissionAlreadyExistsError,
+  RoleAlreadyExistsError,
+  CircularInheritanceError,
+};