@faryzal2020/v-perms 1.0.0

package/src/index.js

@@ -0,0 +1,73 @@
+import PrismaAdapter from './adapters/PrismaAdapter.js';
+import PermissionChecker from './core/PermissionChecker.js';
+import PermissionManager from './core/PermissionManager.js';
+import CacheManager from './core/CacheManager.js';
+import Logger from './utils/logger.js';
+import * as errors from './core/errors.js';
+
+/**
+ * Create permission system instance
+ * @param {PrismaClient} prismaClient - Prisma client instance
+ * @param {object} options - Configuration options
+ * @param {object} options.redis - Redis client instance (optional)
+ * @param {boolean} options.enableCache - Enable caching (default: true)
+ * @param {number} options.cacheTTL - Cache TTL in seconds (default: 300)
+ * @param {boolean} options.debug - Enable debug logging (default: false)
+ * @returns {Object} Permission system instance
+ */
+function createPermissionSystem(prismaClient, options = {}) {
+    const {
+        redis = null,
+        enableCache = true,
+        cacheTTL = 300,
+        debug = false,
+    } = options;
+
+    const logger = new Logger(debug);
+    const cacheManager = new CacheManager(redis, { enabled: enableCache, ttl: cacheTTL });
+    const adapter = new PrismaAdapter(prismaClient, logger);
+    const checker = new PermissionChecker(adapter, cacheManager, logger);
+    const manager = new PermissionManager(adapter, checker, cacheManager, logger);
+
+    return {
+        // Core components
+        manager,
+        checker,
+        adapter,
+        cache: cacheManager,
+        logger,
+
+        // Convenience methods for permission checking
+        can: (userId, permission) => checker.checkPermission(userId, permission),
+        canRole: (roleId, permission) => checker.checkRolePermission(roleId, permission),
+
+        // Direct access to commonly used manager methods
+        createPermission: (...args) => manager.createPermission(...args),
+        deletePermission: (...args) => manager.deletePermission(...args),
+        createRole: (...args) => manager.createRole(...args),
+        deleteRole: (...args) => manager.deleteRole(...args),
+        assignPermission: (...args) => manager.assignPermission(...args),
+        removePermission: (...args) => manager.removePermission(...args),
+        assignRole: (...args) => manager.assignRole(...args),
+        removeRole: (...args) => manager.removeRole(...args),
+        banPermission: (...args) => manager.banPermission(...args),
+        checkPermission: (...args) => manager.checkPermission(...args),
+
+        // Cache control
+        invalidateUserCache: (userId) => cacheManager.invalidateUser(userId),
+        invalidateRoleCache: (roleId) => cacheManager.invalidateRole(roleId),
+        clearCache: () => cacheManager.clear(),
+    };
+}
+
+export {
+    createPermissionSystem,
+    PrismaAdapter,
+    PermissionChecker,
+    PermissionManager,
+    CacheManager,
+    Logger,
+    errors,
+};
+
+export default createPermissionSystem;

package/src/prisma/schema.prisma

@@ -0,0 +1,86 @@
+// This schema is designed to be copied into your existing Prisma schema
+// Compatible with PostgreSQL, MySQL, and SQLite
+
+model Role {
+  id          String   @id @default(cuid())
+  name        String   @unique
+  description String?
+  priority    Int      @default(0)
+  isDefault   Boolean  @default(false)
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  userRoles        UserRole[]
+  rolePermissions  RolePermission[]
+  inheritedRoles   RoleInheritance[] @relation("ParentRole")
+  inheritsFrom     RoleInheritance[] @relation("ChildRole")
+
+  @@map("roles")
+}
+
+model Permission {
+  id          String   @id @default(cuid())
+  key         String   @unique
+  description String?
+  category    String?
+  createdAt   DateTime @default(now())
+
+  rolePermissions RolePermission[]
+  userPermissions UserPermission[]
+
+  @@index([category])
+  @@map("permissions")
+}
+
+model UserRole {
+  userId     String
+  roleId     String
+  assignedAt DateTime @default(now())
+
+  // Note: Replace 'User' with your actual User model name
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+  role Role @relation(fields: [roleId], references: [id], onDelete: Cascade)
+
+  @@id([userId, roleId])
+  @@map("user_roles")
+}
+
+model RolePermission {
+  roleId       String
+  permissionId String
+  granted      Boolean  @default(true)
+  assignedAt   DateTime @default(now())
+
+  role       Role       @relation(fields: [roleId], references: [id], onDelete: Cascade)
+  permission Permission @relation(fields: [permissionId], references: [id], onDelete: Cascade)
+
+  @@id([roleId, permissionId])
+  @@map("role_permissions")
+}
+
+model UserPermission {
+  userId       String
+  permissionId String
+  granted      Boolean  @default(true)
+  assignedAt   DateTime @default(now())
+
+  // Note: Replace 'User' with your actual User model name
+  user       User       @relation(fields: [userId], references: [id], onDelete: Cascade)
+  permission Permission @relation(fields: [permissionId], references: [id], onDelete: Cascade)
+
+  @@id([userId, permissionId])
+  @@map("user_permissions")
+}
+
+model RoleInheritance {
+  roleId         String
+  inheritsFromId String
+  priority       Int      @default(0)
+  createdAt      DateTime @default(now())
+
+  role         Role @relation("ParentRole", fields: [roleId], references: [id], onDelete: Cascade)
+  inheritsFrom Role @relation("ChildRole", fields: [inheritsFromId], references: [id], onDelete: Cascade)
+
+  @@id([roleId, inheritsFromId])
+  @@map("role_inheritance")
+}

package/src/utils/logger.js

@@ -0,0 +1,64 @@
+/**
+ * Debug logging utility with on/off toggle
+ */
+class Logger {
+    constructor(enabled = false) {
+        this.enabled = enabled;
+    }
+
+    /**
+     * Enable debug logging
+     */
+    enable() {
+        this.enabled = true;
+    }
+
+    /**
+     * Disable debug logging
+     */
+    disable() {
+        this.enabled = false;
+    }
+
+    /**
+     * Log debug message
+     * @param {...any} args - Arguments to log
+     */
+    debug(...args) {
+        if (this.enabled) {
+            console.log('[v-perms:debug]', ...args);
+        }
+    }
+
+    /**
+     * Log info message
+     * @param {...any} args - Arguments to log
+     */
+    info(...args) {
+        if (this.enabled) {
+            console.info('[v-perms:info]', ...args);
+        }
+    }
+
+    /**
+     * Log warning message
+     * @param {...any} args - Arguments to log
+     */
+    warn(...args) {
+        if (this.enabled) {
+            console.warn('[v-perms:warn]', ...args);
+        }
+    }
+
+    /**
+     * Log error message
+     * @param {...any} args - Arguments to log
+     */
+    error(...args) {
+        if (this.enabled) {
+            console.error('[v-perms:error]', ...args);
+        }
+    }
+}
+
+export default Logger;

package/src/utils/wildcard.js

@@ -0,0 +1,44 @@
+/**
+ * Check if a permission key matches a wildcard pattern
+ * @param {string} pattern - Pattern like "endpoint.*" or "*"
+ * @param {string} permissionKey - Actual permission like "endpoint.admin.users"
+ * @returns {boolean}
+ */
+function matchesWildcard(pattern, permissionKey) {
+    // Universal wildcard matches everything
+    if (pattern === '*') return true;
+
+    // Exact match
+    if (pattern === permissionKey) return true;
+
+    // Wildcard suffix match (e.g., "endpoint.*")
+    if (pattern.endsWith('.*')) {
+        const prefix = pattern.slice(0, -2);
+        // Matches the prefix itself or anything starting with prefix.
+        return permissionKey === prefix || permissionKey.startsWith(prefix + '.');
+    }
+
+    return false;
+}
+
+/**
+ * Generate all possible wildcard patterns for a permission key
+ * @param {string} permissionKey - Like "endpoint.admin.users.delete"
+ * @returns {string[]} - ["endpoint.admin.users.*", "endpoint.admin.*", "endpoint.*", "*"]
+ */
+function generateWildcardPatterns(permissionKey) {
+    const parts = permissionKey.split('.');
+    const patterns = ['*'];
+
+    // Generate patterns from most specific to least specific
+    for (let i = parts.length - 1; i > 0; i--) {
+        patterns.push([...parts.slice(0, i), '*'].join('.'));
+    }
+
+    return patterns;
+}
+
+export {
+    matchesWildcard,
+    generateWildcardPatterns,
+};