qdadm 0.17.0 → 0.25.0

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/entity/storage/ApiStorage.js

@@ -22,9 +22,26 @@
  */
 export class ApiStorage {
   /**
-   * API calls benefit from EntityManager cache layer to reduce network requests
+   * Storage capabilities declaration.
+   * Describes what features this storage adapter supports.
+   *
+   * @type {import('./index.js').StorageCapabilities}
    */
-  supportsCaching = true
+  static capabilities = {
+    supportsTotal: true,
+    supportsFilters: true,
+    supportsPagination: true,
+    supportsCaching: true
+  }
+
+  /**
+   * Backward-compatible instance getter for supportsCaching.
+   * @deprecated Use static ApiStorage.capabilities.supportsCaching instead
+   * @returns {boolean}
+   */
+  get supportsCaching() {
+    return ApiStorage.capabilities.supportsCaching
+  }
 
   constructor(options = {}) {
     const {

package/src/entity/storage/LocalStorage.js

@@ -19,9 +19,32 @@
  */
 export class LocalStorage {
   /**
-   * LocalStorage is already in-memory, no need for EntityManager cache layer
+   * Storage capabilities declaration.
+   * Describes what features this storage adapter supports.
+   *
+   * LocalStorage operates with browser localStorage:
+   * - supportsTotal: true - Returns accurate total from stored data
+   * - supportsFilters: true - Filters in-memory via list() params
+   * - supportsPagination: true - Paginates in-memory
+   * - supportsCaching: false - Already local, no cache benefit
+   *
+   * @type {import('./index.js').StorageCapabilities}
    */
-  supportsCaching = false
+  static capabilities = {
+    supportsTotal: true,
+    supportsFilters: true,
+    supportsPagination: true,
+    supportsCaching: false
+  }
+
+  /**
+   * Backward-compatible instance getter for supportsCaching.
+   * @deprecated Use static LocalStorage.capabilities.supportsCaching instead
+   * @returns {boolean}
+   */
+  get supportsCaching() {
+    return LocalStorage.capabilities.supportsCaching
+  }
 
   constructor(options = {}) {
     const {

package/src/entity/storage/MemoryStorage.js

@@ -18,6 +18,34 @@
  * ```
  */
 export class MemoryStorage {
+  /**
+   * Storage capabilities declaration.
+   * Describes what features this storage adapter supports.
+   *
+   * MemoryStorage operates entirely in-memory:
+   * - supportsTotal: true - Returns accurate total from in-memory data
+   * - supportsFilters: true - Filters in-memory via list() params
+   * - supportsPagination: true - Paginates in-memory
+   * - supportsCaching: false - Already in-memory, no cache benefit
+   *
+   * @type {import('./index.js').StorageCapabilities}
+   */
+  static capabilities = {
+    supportsTotal: true,
+    supportsFilters: true,
+    supportsPagination: true,
+    supportsCaching: false
+  }
+
+  /**
+   * Backward-compatible instance getter for supportsCaching.
+   * @deprecated Use static MemoryStorage.capabilities.supportsCaching instead
+   * @returns {boolean}
+   */
+  get supportsCaching() {
+    return MemoryStorage.capabilities.supportsCaching
+  }
+
   constructor(options = {}) {
     const {
       idField = 'id',

package/src/entity/storage/MockApiStorage.js

@@ -20,9 +20,32 @@
  */
 export class MockApiStorage {
   /**
-   * In-memory storage with persistence doesn't benefit from EntityManager cache
+   * Storage capabilities declaration.
+   * Describes what features this storage adapter supports.
+   *
+   * MockApiStorage operates with in-memory Map + localStorage persistence:
+   * - supportsTotal: true - Returns accurate total from in-memory data
+   * - supportsFilters: true - Filters in-memory via list() params
+   * - supportsPagination: true - Paginates in-memory
+   * - supportsCaching: false - Already in-memory, no cache benefit
+   *
+   * @type {import('./index.js').StorageCapabilities}
    */
-  supportsCaching = false
+  static capabilities = {
+    supportsTotal: true,
+    supportsFilters: true,
+    supportsPagination: true,
+    supportsCaching: false
+  }
+
+  /**
+   * Backward-compatible instance getter for supportsCaching.
+   * @deprecated Use static MockApiStorage.capabilities.supportsCaching instead
+   * @returns {boolean}
+   */
+  get supportsCaching() {
+    return MockApiStorage.capabilities.supportsCaching
+  }
 
   constructor(options = {}) {
     const {

package/src/entity/storage/SdkStorage.js

@@ -95,9 +95,24 @@
  */
 export class SdkStorage {
   /**
-   * SDK calls benefit from EntityManager cache layer to reduce network requests
+   * Storage capabilities declaration
+   * @type {import('./index.js').StorageCapabilities}
    */
-  supportsCaching = true
+  static capabilities = {
+    supportsTotal: true,      // list() returns { items, total }
+    supportsFilters: true,    // list() accepts filters param
+    supportsPagination: true, // list() accepts page/page_size
+    supportsCaching: true     // Benefits from EntityManager cache layer
+  }
+
+  /**
+   * Backward-compat instance getter for supportsCaching
+   * @deprecated Use SdkStorage.capabilities.supportsCaching instead
+   * @returns {boolean}
+   */
+  get supportsCaching() {
+    return SdkStorage.capabilities.supportsCaching
+  }
 
   /**
    * @param {object} options

package/src/entity/storage/index.js

@@ -5,6 +5,111 @@
  * EntityManagers can use these or implement their own storage.
  */
 
+/**
+ * Storage Capabilities Interface
+ *
+ * Static capabilities declaration that storage adapters expose via `static capabilities = {...}`.
+ * EntityManager reads these via `storage.constructor.capabilities` to determine feature support.
+ *
+ * All properties default to `false` if not declared (conservative assumption).
+ * Custom storage implementations that don't declare capabilities will degrade gracefully
+ * via fallback to empty `{}`.
+ *
+ * @typedef {object} StorageCapabilities
+ * @property {boolean} [supportsTotal=false] - Storage `list()` returns `{ items, total }` with accurate total count
+ * @property {boolean} [supportsFilters=false] - Storage `list()` accepts `filters` param and handles filtering
+ * @property {boolean} [supportsPagination=false] - Storage `list()` accepts `page`/`page_size` params
+ * @property {boolean} [supportsCaching=false] - Storage benefits from EntityManager cache layer (network-based storages)
+ * @property {string[]} [searchFields] - Fields to search when filtering locally. Supports own fields ('title')
+ *   and parent entity fields ('book.title') via EntityManager.parents config. When undefined, all string
+ *   fields are searched (default behavior). When defined, only listed fields are searched.
+ */
+
+/**
+ * Migration Guide for Custom Storage Adapters
+ *
+ * If you have a custom storage adapter, you can add capabilities support in two ways:
+ *
+ * **Option 1: Static capabilities (recommended)**
+ * Add a static `capabilities` property to your class. EntityManager reads this via
+ * `storage.constructor.capabilities`. This is the preferred pattern for new code.
+ *
+ * ```js
+ * export class MyCustomStorage {
+ *   static capabilities = {
+ *     supportsTotal: true,
+ *     supportsFilters: true,
+ *     supportsPagination: true,
+ *     supportsCaching: true // set to false for in-memory storages
+ *   }
+ *
+ *   // Backward-compat instance getter (optional, for smooth migration)
+ *   get supportsCaching() {
+ *     return MyCustomStorage.capabilities.supportsCaching
+ *   }
+ *
+ *   async list(params) { ... }
+ *   async get(id) { ... }
+ *   // ... other methods
+ * }
+ * ```
+ *
+ * **Option 2: Instance property only (legacy)**
+ * Keep using instance properties. EntityManager's `isCacheEnabled` check uses:
+ * `if (storage?.supportsCaching === false) return false`
+ * This works with instance properties directly.
+ *
+ * ```js
+ * export class MyLegacyStorage {
+ *   supportsCaching = true // or false for in-memory
+ *
+ *   async list(params) { ... }
+ * }
+ * ```
+ *
+ * **No capabilities declared**
+ * If your storage doesn't declare capabilities, EntityManager will:
+ * - Assume `supportsTotal: false` (disables auto-caching threshold check)
+ * - Assume `supportsCaching: undefined` (caching allowed, but threshold check fails)
+ * - Gracefully degrade without errors
+ *
+ * Use `getStorageCapabilities(storage)` helper to read merged capabilities with defaults.
+ */
+
+/**
+ * Default capabilities for storages that don't declare their own.
+ * All capabilities default to false for safe degradation.
+ *
+ * @type {StorageCapabilities}
+ */
+export const DEFAULT_STORAGE_CAPABILITIES = {
+  supportsTotal: false,
+  supportsFilters: false,
+  supportsPagination: false,
+  supportsCaching: false
+}
+
+/**
+ * Read capabilities from a storage instance.
+ * Accesses static `capabilities` property via constructor with fallback to defaults.
+ *
+ * @param {object} storage - Storage adapter instance
+ * @returns {StorageCapabilities} Merged capabilities with defaults
+ *
+ * @example
+ * const caps = getStorageCapabilities(myStorage)
+ * if (caps.supportsTotal) {
+ *   // Storage provides accurate total count
+ * }
+ */
+export function getStorageCapabilities(storage) {
+  const declared = storage?.constructor?.capabilities || {}
+  return {
+    ...DEFAULT_STORAGE_CAPABILITIES,
+    ...declared
+  }
+}
+
 export { ApiStorage, createApiStorage } from './ApiStorage.js'
 export { LocalStorage, createLocalStorage } from './LocalStorage.js'
 export { MemoryStorage, createMemoryStorage } from './MemoryStorage.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'
 
@@ -34,6 +38,9 @@ export * from './hooks/index.js'
 // Core (extension helpers)
 export * from './core/index.js'
 
+// Query (MongoDB-like filtering)
+export * from './query/index.js'
+
 // Utils
 export * from './utils/index.js'