qdadm 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/entity/EntityManager.js

@@ -328,6 +328,51 @@ export class EntityManager {
     return this._authAdapter
   }
 
+  /**
+   * Build permission string for an action based on entity_permissions config
+   *
+   * The permission format depends on the security config:
+   * - entity_permissions: false → 'entity:read'
+   * - entity_permissions: true → 'books:read'
+   * - entity_permissions: ['books'] → 'books:read' for books, 'entity:read' for others
+   *
+   * @param {string} action - Action name (read, create, update, delete, list)
+   * @returns {string} - Permission string
+   * @private
+   */
+  _getPermissionString(action) {
+    const checker = this.authAdapter._securityChecker
+    if (!checker) return `entity:${action}`
+
+    const config = checker.entityPermissions
+    if (config === false) return `entity:${action}`
+    if (config === true) return `${this.name}:${action}`
+    if (Array.isArray(config) && config.includes(this.name)) {
+      return `${this.name}:${action}`
+    }
+    return `entity:${action}`
+  }
+
+  /**
+   * Check permission using isGranted() if security is configured
+   *
+   * Falls back to traditional canPerform()/canAccessRecord() if no SecurityChecker.
+   * This method respects the entity_permissions config for granular permissions.
+   *
+   * @param {string} action - Action to check (read, create, update, delete, list)
+   * @param {object} [subject] - Optional subject for context-aware checks
+   * @returns {boolean}
+   */
+  checkPermission(action, subject = null) {
+    // If isGranted is available, use it
+    if (this.authAdapter.isGranted && this.authAdapter._securityChecker) {
+      const perm = this._getPermissionString(action)
+      return this.authAdapter.isGranted(perm, subject)
+    }
+    // Fallback to traditional method
+    return this.canAccess(action, subject)
+  }
+
   /**
    * Set the auth adapter
    * @param {AuthAdapter|null} adapter

package/src/entity/auth/AuthAdapter.js

@@ -33,6 +33,65 @@
  * @interface
  */
 export class AuthAdapter {
+  /**
+   * SecurityChecker instance for isGranted() delegation
+   * @type {import('./SecurityChecker.js').SecurityChecker|null}
+   * @private
+   */
+  _securityChecker = null
+
+  /**
+   * Set the SecurityChecker instance for isGranted() delegation
+   *
+   * @param {import('./SecurityChecker.js').SecurityChecker} checker
+   */
+  setSecurityChecker(checker) {
+    this._securityChecker = checker
+  }
+
+  /**
+   * Check if current user is granted an attribute (Symfony-like contract)
+   *
+   * This is the unified permission check method. It delegates to SecurityChecker
+   * if one is configured, otherwise returns true (permissive fallback).
+   *
+   * @param {string} attribute - Role (ROLE_*) or permission (entity:action)
+   * @param {object} [subject] - Optional subject for context-aware checks
+   * @returns {boolean} True if user is granted the attribute
+   *
+   * @example
+   * adapter.isGranted('ROLE_ADMIN')           // Check role
+   * adapter.isGranted('entity:delete')        // Check permission
+   * adapter.isGranted('books:delete', book)   // Check with subject
+   */
+  isGranted(attribute, subject = null) {
+    if (!this._securityChecker) return true // Permissive if not configured
+    return this._securityChecker.isGranted(attribute, subject)
+  }
+
+  /**
+   * Check if current user can assign a specific role
+   *
+   * Uses SecurityChecker's canAssignRole if available.
+   *
+   * @param {string} targetRole - Role to assign
+   * @returns {boolean} True if user can assign this role
+   */
+  canAssignRole(targetRole) {
+    if (!this._securityChecker) return true
+    return this._securityChecker.canAssignRole(targetRole)
+  }
+
+  /**
+   * Get all roles that current user can assign
+   *
+   * @returns {string[]} Array of assignable role names
+   */
+  getAssignableRoles() {
+    if (!this._securityChecker) return []
+    return this._securityChecker.getAssignableRoles()
+  }
+
   /**
    * Check if the current user can perform an action on an entity type (scope check)
    *

package/src/entity/auth/RoleHierarchy.js

@@ -0,0 +1,153 @@
+/**
+ * RoleHierarchy - Topological role resolution for Symfony-like permission system
+ *
+ * Roles form a Directed Acyclic Graph (DAG) where higher roles inherit
+ * permissions from lower roles. This class resolves the complete set of
+ * roles that a user effectively has based on their assigned roles.
+ *
+ * @example
+ * ```js
+ * const hierarchy = new RoleHierarchy({
+ *   ROLE_ADMIN: ['ROLE_USER'],           // Admin inherits from User
+ *   ROLE_SUPER_ADMIN: ['ROLE_ADMIN'],    // Super admin inherits from Admin
+ *   ROLE_MANAGER: ['ROLE_USER'],         // Manager also inherits from User
+ * })
+ *
+ * hierarchy.getReachableRoles('ROLE_ADMIN')
+ * // Returns: ['ROLE_ADMIN', 'ROLE_USER']
+ *
+ * hierarchy.isGrantedRole(['ROLE_ADMIN'], 'ROLE_USER')
+ * // Returns: true (admin has user permissions)
+ * ```
+ */
+export class RoleHierarchy {
+  /**
+   * @param {Object<string, string[]>} hierarchy - Role inheritance map
+   *        Keys are role names, values are arrays of parent roles they inherit from
+   */
+  constructor(hierarchy = {}) {
+    this.map = hierarchy
+  }
+
+  /**
+   * Resolve all roles reachable from a given role (topological traversal)
+   *
+   * Performs BFS traversal of the role graph to find all inherited roles.
+   * Handles cycles gracefully by tracking visited nodes.
+   *
+   * @param {string} role - Starting role to resolve
+   * @returns {string[]} All roles including the starting role and all inherited roles
+   *
+   * @example
+   * // With hierarchy: { ROLE_ADMIN: ['ROLE_USER'] }
+   * hierarchy.getReachableRoles('ROLE_ADMIN')
+   * // Returns: ['ROLE_ADMIN', 'ROLE_USER']
+   */
+  getReachableRoles(role) {
+    const visited = new Set()
+    const queue = [role]
+
+    while (queue.length > 0) {
+      const current = queue.shift()
+      if (visited.has(current)) continue
+      visited.add(current)
+
+      const parents = this.map[current] || []
+      queue.push(...parents)
+    }
+
+    return [...visited]
+  }
+
+  /**
+   * Check if user with given roles has the required role
+   *
+   * A user has a role if:
+   * 1. They are directly assigned that role, OR
+   * 2. They have a role that inherits from the required role
+   *
+   * @param {string|string[]} userRoles - Role(s) assigned to the user
+   * @param {string} requiredRole - The role to check for
+   * @returns {boolean} True if user has the required role (directly or inherited)
+   *
+   * @example
+   * // With hierarchy: { ROLE_ADMIN: ['ROLE_USER'] }
+   * hierarchy.isGrantedRole(['ROLE_ADMIN'], 'ROLE_USER')  // true
+   * hierarchy.isGrantedRole(['ROLE_USER'], 'ROLE_ADMIN')  // false
+   */
+  isGrantedRole(userRoles, requiredRole) {
+    const roles = Array.isArray(userRoles) ? userRoles : [userRoles]
+
+    for (const role of roles) {
+      const reachable = this.getReachableRoles(role)
+      if (reachable.includes(requiredRole)) return true
+    }
+
+    return false
+  }
+
+  /**
+   * Get all roles that can reach a given role (reverse lookup)
+   *
+   * Useful for finding which roles would grant a specific permission.
+   *
+   * @param {string} targetRole - The role to find grantors for
+   * @returns {string[]} All roles that have the target role in their reachable set
+   */
+  getRolesGranting(targetRole) {
+    const grantors = []
+
+    for (const role of Object.keys(this.map)) {
+      if (this.isGrantedRole([role], targetRole)) {
+        grantors.push(role)
+      }
+    }
+
+    // Also check the target role itself
+    if (!grantors.includes(targetRole)) {
+      grantors.push(targetRole)
+    }
+
+    return grantors
+  }
+
+  /**
+   * Validate the hierarchy for cycles (optional sanity check)
+   *
+   * @returns {boolean} True if hierarchy is valid (no cycles)
+   */
+  validate() {
+    const visiting = new Set()
+    const visited = new Set()
+
+    const hasCycle = (role) => {
+      if (visited.has(role)) return false
+      if (visiting.has(role)) return true
+
+      visiting.add(role)
+      const parents = this.map[role] || []
+      for (const parent of parents) {
+        if (hasCycle(parent)) return true
+      }
+      visiting.delete(role)
+      visited.add(role)
+      return false
+    }
+
+    for (const role of Object.keys(this.map)) {
+      if (hasCycle(role)) return false
+    }
+
+    return true
+  }
+}
+
+/**
+ * Create a RoleHierarchy instance from config
+ *
+ * @param {Object<string, string[]>} config - Role hierarchy configuration
+ * @returns {RoleHierarchy}
+ */
+export function createRoleHierarchy(config = {}) {
+  return new RoleHierarchy(config)
+}

package/src/entity/auth/SecurityChecker.js

@@ -0,0 +1,167 @@
+import { RoleHierarchy } from './RoleHierarchy.js'
+
+/**
+ * SecurityChecker - Symfony-inspired permission checking
+ *
+ * Provides the `isGranted(attribute, subject?)` contract for checking permissions.
+ * Supports both role checks (ROLE_*) and permission checks (entity:action).
+ *
+ * Note: Symfony's full security system includes "voters" for custom business logic
+ * (e.g., "owner can edit their own posts"). This implementation focuses on
+ * role hierarchy + declarative permissions. For complex rules, override
+ * EntityManager.canRead/canWrite methods directly.
+ *
+ * @example
+ * ```js
+ * const checker = new SecurityChecker({
+ *   roleHierarchy: new RoleHierarchy({ ROLE_ADMIN: ['ROLE_USER'] }),
+ *   rolePermissions: {
+ *     ROLE_USER: ['entity:read', 'entity:list'],
+ *     ROLE_ADMIN: ['entity:create', 'entity:update', 'entity:delete'],
+ *   },
+ *   getCurrentUser: () => authStore.user
+ * })
+ *
+ * checker.isGranted('ROLE_ADMIN')           // Check role
+ * checker.isGranted('entity:delete')        // Check permission
+ * checker.isGranted('books:delete', book)   // Check with subject
+ * ```
+ */
+export class SecurityChecker {
+  /**
+   * @param {Object} options
+   * @param {RoleHierarchy} options.roleHierarchy - Role hierarchy instance
+   * @param {Object<string, string[]>} options.rolePermissions - Permissions per role
+   * @param {Function} options.getCurrentUser - Function returning current user or null
+   */
+  constructor({ roleHierarchy, rolePermissions = {}, getCurrentUser }) {
+    this.roleHierarchy = roleHierarchy instanceof RoleHierarchy
+      ? roleHierarchy
+      : new RoleHierarchy(roleHierarchy || {})
+    this.rolePermissions = rolePermissions
+    this.getCurrentUser = getCurrentUser
+  }
+
+  /**
+   * Check if current user is granted an attribute (role or permission)
+   *
+   * This is the main contract method, similar to Symfony's isGranted().
+   *
+   * Checking flow:
+   * 1. If attribute starts with 'ROLE_' → check role hierarchy
+   * 2. Check if user has the permission (from role or direct)
+   *
+   * @param {string} attribute - Role (ROLE_*) or permission (entity:action)
+   * @param {object} [subject] - Optional subject for context-aware checks (reserved for future use)
+   * @returns {boolean} True if user is granted the attribute
+   *
+   * @example
+   * checker.isGranted('ROLE_ADMIN')           // true/false
+   * checker.isGranted('entity:delete')        // true/false
+   * checker.isGranted('books:delete', book)   // true/false (with subject)
+   */
+  isGranted(attribute, subject = null) {
+    const user = this.getCurrentUser()
+    if (!user) return false
+
+    // 1. Check if it's a role (ROLE_*)
+    if (attribute.startsWith('ROLE_')) {
+      return this.roleHierarchy.isGrantedRole(
+        user.roles || [user.role],
+        attribute
+      )
+    }
+
+    // 2. Check if it's a permission
+    const userPerms = this.getUserPermissions(user)
+    if (userPerms.includes('*')) return true
+    if (userPerms.includes(attribute)) return true
+
+    return false
+  }
+
+  /**
+   * Get all permissions for a user (resolved from roles + user overrides)
+   *
+   * Resolves permissions by:
+   * 1. Getting all reachable roles from role hierarchy
+   * 2. Collecting permissions from each role
+   * 3. Adding any user-specific permission overrides
+   *
+   * @param {object} user - User object with role/roles and optional permissions
+   * @returns {string[]} Array of all permissions
+   */
+  getUserPermissions(user) {
+    const roles = user.roles || [user.role]
+    const perms = new Set()
+
+    for (const role of roles) {
+      if (!role) continue
+      const reachable = this.roleHierarchy.getReachableRoles(role)
+      for (const r of reachable) {
+        const rolePerms = this.rolePermissions[r] || []
+        rolePerms.forEach(p => perms.add(p))
+      }
+    }
+
+    // User-specific permission overrides
+    if (user.permissions && Array.isArray(user.permissions)) {
+      user.permissions.forEach(p => perms.add(p))
+    }
+
+    return [...perms]
+  }
+
+  /**
+   * Check if user can assign a role to another user
+   *
+   * Rule: Can only assign roles if user has 'role:assign' permission
+   * AND has the target role (or higher) themselves.
+   *
+   * @param {string} targetRole - Role to assign
+   * @returns {boolean} True if user can assign this role
+   */
+  canAssignRole(targetRole) {
+    return this.isGranted('role:assign') && this.isGranted(targetRole)
+  }
+
+  /**
+   * Get all roles that current user can assign
+   *
+   * @returns {string[]} Array of assignable role names
+   */
+  getAssignableRoles() {
+    if (!this.isGranted('role:assign')) return []
+
+    const user = this.getCurrentUser()
+    if (!user) return []
+
+    const userRoles = user.roles || [user.role]
+    const assignable = new Set()
+
+    for (const role of userRoles) {
+      if (!role) continue
+      const reachable = this.roleHierarchy.getReachableRoles(role)
+      reachable.forEach(r => assignable.add(r))
+    }
+
+    return [...assignable]
+  }
+}
+
+/**
+ * Create a SecurityChecker instance from config
+ *
+ * @param {Object} config
+ * @param {Object<string, string[]>} config.role_hierarchy - Role hierarchy config
+ * @param {Object<string, string[]>} config.role_permissions - Permissions per role
+ * @param {Function} config.getCurrentUser - User getter function
+ * @returns {SecurityChecker}
+ */
+export function createSecurityChecker(config) {
+  return new SecurityChecker({
+    roleHierarchy: new RoleHierarchy(config.role_hierarchy || {}),
+    rolePermissions: config.role_permissions || {},
+    getCurrentUser: config.getCurrentUser
+  })
+}

package/src/entity/auth/index.js

@@ -2,10 +2,17 @@
  * Auth Module
  *
  * AuthAdapter interface and implementations for scope/silo permission checks.
+ * Includes Symfony-inspired role hierarchy and security checker.
  */
 
 // Interface
 export { AuthAdapter, AuthActions } from './AuthAdapter.js'
 
+// Role Hierarchy (topological resolution)
+export { RoleHierarchy, createRoleHierarchy } from './RoleHierarchy.js'
+
+// Security Checker (isGranted contract)
+export { SecurityChecker, createSecurityChecker } from './SecurityChecker.js'
+
 // Implementations
 export { PermissiveAuthAdapter, createPermissiveAdapter } from './PermissiveAdapter.js'

package/src/index.js

@@ -4,6 +4,10 @@
  * A framework for building admin dashboards with Vue 3, PrimeVue, and Vue Router.
  */
 
+// Version (from package.json)
+import pkg from '../package.json'
+export const version = pkg.version
+
 // Kernel (simplified bootstrap)
 export * from './kernel/index.js'
 

package/src/kernel/Kernel.js

@@ -51,6 +51,7 @@ import { createSignalBus } from './SignalBus.js'
 import { createZoneRegistry } from '../zones/ZoneRegistry.js'
 import { registerStandardZones } from '../zones/zones.js'
 import { createHookRegistry } from '../hooks/HookRegistry.js'
+import { createSecurityChecker } from '../entity/auth/SecurityChecker.js'
 
 export class Kernel {
   /**
@@ -71,6 +72,7 @@ export class Kernel {
    * @param {object} options.features - Feature toggles { auth, poweredBy }
    * @param {object} options.primevue - PrimeVue config { plugin, theme, options }
    * @param {object} options.layouts - Layout components { list, form, dashboard, base }
+   * @param {object} options.security - Security config { role_hierarchy, role_permissions, entity_permissions }
    */
   constructor(options) {
     this.options = options
@@ -81,6 +83,7 @@ export class Kernel {
     this.zoneRegistry = null
     this.hookRegistry = null
     this.layoutComponents = null
+    this.securityChecker = null
   }
 
   /**
@@ -88,12 +91,17 @@ export class Kernel {
    * @returns {App} Vue app instance ready to mount
    */
   createApp() {
-    this._initModules()
-    this._createRouter()
+    // 1. Create services first (modules need them)
     this._createSignalBus()
     this._createHookRegistry()
-    this._createOrchestrator()
     this._createZoneRegistry()
+    // 2. Initialize modules (can use all services, registers routes)
+    this._initModules()
+    // 3. Create router (needs routes from modules)
+    this._createRouter()
+    // 4. Create orchestrator and remaining components
+    this._createOrchestrator()
+    this._setupSecurity()
     this._createLayoutComponents()
     this._createVueApp()
     this._installPlugins()
@@ -102,13 +110,19 @@ export class Kernel {
 
   /**
    * Initialize modules from glob import
+   * Passes services to modules for zone/signal/hook registration
    */
   _initModules() {
     if (this.options.sectionOrder) {
       setSectionOrder(this.options.sectionOrder)
     }
     if (this.options.modules) {
-      initModules(this.options.modules, this.options.modulesOptions || {})
+      initModules(this.options.modules, {
+        ...this.options.modulesOptions,
+        zones: this.zoneRegistry,
+        signals: this.signals,
+        hooks: this.hookRegistry
+      })
     }
   }
 
@@ -211,6 +225,44 @@ export class Kernel {
     })
   }
 
+  /**
+   * Setup security layer (role hierarchy, permissions)
+   *
+   * If security config is provided, creates a SecurityChecker and wires it
+   * into the entityAuthAdapter for isGranted() support.
+   *
+   * Security config:
+   * ```js
+   * security: {
+   *   role_hierarchy: { ROLE_ADMIN: ['ROLE_USER'] },
+   *   role_permissions: {
+   *     ROLE_USER: ['entity:read', 'entity:list'],
+   *     ROLE_ADMIN: ['entity:create', 'entity:update', 'entity:delete'],
+   *   },
+   *   entity_permissions: false  // false | true | ['books', 'loans']
+   * }
+   * ```
+   */
+  _setupSecurity() {
+    const { security, entityAuthAdapter } = this.options
+    if (!security) return
+
+    // Create SecurityChecker with role hierarchy and permissions
+    this.securityChecker = createSecurityChecker({
+      role_hierarchy: security.role_hierarchy || {},
+      role_permissions: security.role_permissions || {},
+      getCurrentUser: () => entityAuthAdapter?.getCurrentUser?.() || null
+    })
+
+    // Store entity_permissions config for EntityManager to use
+    this.securityChecker.entityPermissions = security.entity_permissions ?? false
+
+    // Wire SecurityChecker into entityAuthAdapter
+    if (entityAuthAdapter?.setSecurityChecker) {
+      entityAuthAdapter.setSecurityChecker(this.securityChecker)
+    }
+  }
+
   /**
    * Create zone registry for extensible UI composition
    * Registers standard zones during bootstrap.
@@ -386,4 +438,21 @@ export class Kernel {
   get layouts() {
     return this.layoutComponents
   }
+
+  /**
+   * Get the SecurityChecker instance
+   * @returns {import('../entity/auth/SecurityChecker.js').SecurityChecker|null}
+   */
+  getSecurityChecker() {
+    return this.securityChecker
+  }
+
+  /**
+   * Shorthand accessor for security checker
+   * Allows `kernel.security.isGranted(...)` syntax
+   * @returns {import('../entity/auth/SecurityChecker.js').SecurityChecker|null}
+   */
+  get security() {
+    return this.securityChecker
+  }
 }

package/src/module/moduleRegistry.js

@@ -1,28 +1,28 @@
 /**
  * Module Registry - Auto-discovery and registration system
  *
- * Each module can provide an init.js that registers:
- * - Routes
- * - Navigation items
- * - Route families (for active state detection)
+ * Each module provides an init.js that registers:
+ * - Routes & Navigation (via registry)
+ * - Zone blocks (via zones)
+ * - Signal handlers (via signals)
+ * - Hooks (via hooks)
  *
  * Usage in module (modules/agents/init.js):
  *
- *   export function init(registry) {
- *     registry.addRoutes('agents', [
- *       { path: '', name: 'agents', component: () => import('./pages/AgentList.vue') },
- *       { path: 'create', name: 'agent-create', component: () => import('./pages/AgentForm.vue') },
- *       { path: ':id/edit', name: 'agent-edit', component: () => import('./pages/AgentForm.vue') }
- *     ])
+ *   export function init({ registry, zones, signals, hooks }) {
+ *     // Routes & Navigation
+ *     registry.addRoutes('agents', [...])
+ *     registry.addNavItem({ section: 'Simulation', route: 'agents', ... })
+ *     registry.addRouteFamily('agents', ['agent-'])
  *
- *     registry.addNavItem({
- *       section: 'Simulation',
- *       route: 'agents',
- *       icon: 'pi pi-user',
- *       label: 'Agents'
- *     })
+ *     // Zone blocks
+ *     zones.registerBlock('agents-list-header', { id: 'agents-header', component: Header })
  *
- *     registry.addRouteFamily('agents', ['agent-'])
+ *     // Signal handlers
+ *     signals.on('agents:created', handleCreated)
+ *
+ *     // Hooks
+ *     hooks.register('agents:presave', validateAgent)
  *   }
  */
 
@@ -134,24 +134,33 @@ export function setSectionOrder(order) {
  *
  * Usage in app:
  *   const moduleInits = import.meta.glob('./modules/* /init.js', { eager: true })
- *   initModules(moduleInits)
+ *   initModules(moduleInits, { zones, signals, hooks })
  *
  * @param {object} moduleInits - Result of import.meta.glob
- * @param {object} options - { coreNavItems: [] } - Core items not in modules
+ * @param {object} options - { coreNavItems, zones, signals, hooks }
+ * @param {Array} options.coreNavItems - Core nav items not in modules
+ * @param {ZoneRegistry} options.zones - Zone registry for block registration
+ * @param {SignalBus} options.signals - Signal bus for event handlers
+ * @param {HookRegistry} options.hooks - Hook registry for lifecycle hooks
  */
 export function initModules(moduleInits, options = {}) {
+  const { coreNavItems, zones, signals, hooks } = options
+
   // Add core nav items (pages that aren't in modules)
-  if (options.coreNavItems) {
-    for (const item of options.coreNavItems) {
+  if (coreNavItems) {
+    for (const item of coreNavItems) {
       registry.addNavItem(item)
     }
   }
 
+  // Context passed to module init functions
+  const context = { registry, zones, signals, hooks }
+
   // Initialize all discovered modules
   for (const path in moduleInits) {
     const module = moduleInits[path]
     if (typeof module.init === 'function') {
-      module.init(registry)
+      module.init(context)
     }
   }
 }

package/src/zones/ZoneRegistry.js

@@ -294,11 +294,18 @@ export class ZoneRegistry {
       this._wrapGraph.get(zoneName).set(block.id, block.wraps)
     }
 
-    // Check for duplicate ID (for 'add' operations only)
-    if (block.id && operation === 'add') {
+    // Check for duplicate ID
+    if (block.id) {
       const existingIndex = zone.blocks.findIndex(b => b.id === block.id)
       if (existingIndex !== -1) {
-        // Replace existing block with same ID
+        // Warn in debug mode - duplicates shouldn't happen with proper module init
+        if (this._debug) {
+          console.warn(
+            `[qdadm:zones] Duplicate block ID "${block.id}" in zone "${zoneName}". ` +
+            `This may indicate a module is being initialized multiple times.`
+          )
+        }
+        // Replace existing block (backward compatibility)
         zone.blocks[existingIndex] = block
       } else {
         zone.blocks.push(block)