qdadm 0.35.0 → 0.38.0

package/src/security/RoleGranterAdapter.js

@@ -0,0 +1,123 @@
+/**
+ * RoleGranterAdapter - Interface for role → permissions mapping
+ *
+ * The framework provides StaticRoleGranterAdapter (from config object).
+ * Apps can implement custom adapters (entity-based, API-backed, etc.)
+ *
+ * This interface abstracts HOW roles and permissions are stored/retrieved,
+ * allowing apps to use:
+ * - Static config (simple apps, demos)
+ * - Database/entity storage (apps with role management UI)
+ * - External API (microservices architecture)
+ *
+ * @example
+ * // Static adapter (auto-created from config)
+ * security: {
+ *   role_permissions: { ROLE_USER: ['entity:*:read'] }
+ * }
+ *
+ * // Custom adapter
+ * security: {
+ *   roleGranter: new EntityRoleGranterAdapter({ entityName: 'roles' })
+ * }
+ */
+export class RoleGranterAdapter {
+  /**
+   * Get permissions granted to a role
+   *
+   * @param {string} role - Role name (e.g., 'ROLE_USER')
+   * @returns {string[]} Array of permission strings (may include wildcards)
+   *
+   * @example
+   * adapter.getPermissions('ROLE_ADMIN')
+   * // ['entity:**', 'admin:**']
+   */
+  getPermissions(role) {
+    throw new Error('RoleGranterAdapter.getPermissions() must be implemented')
+  }
+
+  /**
+   * Get all defined roles
+   *
+   * @returns {string[]} Array of role names
+   *
+   * @example
+   * adapter.getRoles()
+   * // ['ROLE_USER', 'ROLE_ADMIN', 'ROLE_SUPER_ADMIN']
+   */
+  getRoles() {
+    throw new Error('RoleGranterAdapter.getRoles() must be implemented')
+  }
+
+  /**
+   * Get role hierarchy map
+   *
+   * @returns {Object<string, string[]>} Role → inherited roles
+   *
+   * @example
+   * adapter.getHierarchy()
+   * // { ROLE_ADMIN: ['ROLE_USER'], ROLE_SUPER_ADMIN: ['ROLE_ADMIN'] }
+   */
+  getHierarchy() {
+    throw new Error('RoleGranterAdapter.getHierarchy() must be implemented')
+  }
+
+  /**
+   * Get the role for unauthenticated users
+   *
+   * Always returns 'ROLE_ANONYMOUS' (convention)
+   *
+   * @returns {string} Anonymous role name
+   */
+  getAnonymousRole() {
+    return 'ROLE_ANONYMOUS'
+  }
+
+  /**
+   * Get role metadata (label, description)
+   * Optional - for display purposes
+   *
+   * @param {string} role - Role name
+   * @returns {RoleMeta|null}
+   */
+  getRoleMeta(role) {
+    return null
+  }
+
+  /**
+   * Install adapter (called by Kernel when context is ready)
+   * Override for adapters that need initialization
+   *
+   * @param {Object} ctx - Kernel context
+   */
+  install(ctx) {
+    // Override if needed
+  }
+
+  /**
+   * Uninstall adapter (cleanup)
+   */
+  uninstall() {
+    // Override if needed
+  }
+
+  /**
+   * Check if adapter supports persistence (editing + saving)
+   *
+   * When true, the adapter supports mutations (setRolePermissions, etc.)
+   * AND can persist changes. UI should show edit controls.
+   *
+   * When false, the adapter is read-only. UI should hide edit controls.
+   *
+   * @returns {boolean}
+   */
+  get canPersist() {
+    return false
+  }
+}
+
+/**
+ * @typedef {Object} RoleMeta
+ * @property {string} [label] - Human-readable label
+ * @property {string} [description] - Description
+ */

package/src/security/RoleGranterStorage.js

@@ -0,0 +1,161 @@
+/**
+ * RoleGranterStorage - Storage bridge for roleGranter
+ *
+ * Implements Storage interface and delegates to roleGranter.
+ * Allows RolesManager to use standard EntityManager patterns.
+ */
+
+export class RoleGranterStorage {
+  /**
+   * Static capabilities (standard storage pattern)
+   * @type {import('../entity/storage/index.js').StorageCapabilities}
+   */
+  static capabilities = {
+    supportsTotal: true,
+    supportsFilters: false,
+    supportsPagination: false,
+    supportsCaching: false  // In-memory via roleGranter, no need for EntityManager cache
+  }
+
+  /**
+   * @param {import('./RoleGranterAdapter.js').RoleGranterAdapter} roleGranter
+   */
+  constructor(roleGranter) {
+    this._roleGranter = roleGranter
+  }
+
+  /**
+   * Instance capabilities (merge static + dynamic)
+   *
+   * Dynamic properties:
+   * - requiresAuth: false (roles are system data)
+   * - readOnly: based on roleGranter.canPersist
+   */
+  get capabilities() {
+    return {
+      ...RoleGranterStorage.capabilities,
+      requiresAuth: false,
+      readOnly: !this._roleGranter?.canPersist
+    }
+  }
+
+  /**
+   * List all roles
+   */
+  async list(params = {}) {
+    if (!this._roleGranter) {
+      return { data: [], total: 0 }
+    }
+
+    // Ensure loaded for adapters that need it
+    if (this._roleGranter.ensureReady) {
+      await this._roleGranter.ensureReady()
+    }
+
+    const roleNames = this._roleGranter.getRoles()
+    const roles = roleNames.map(name => this._getRole(name))
+
+    // Simple search filter
+    let filtered = roles
+    if (params.search) {
+      const search = params.search.toLowerCase()
+      filtered = roles.filter(r =>
+        r.name.toLowerCase().includes(search) ||
+        r.label?.toLowerCase().includes(search)
+      )
+    }
+
+    return {
+      items: filtered,
+      total: filtered.length
+    }
+  }
+
+  /**
+   * Get a single role by name
+   */
+  async get(name) {
+    if (!this._roleGranter) return null
+
+    if (this._roleGranter.ensureReady) {
+      await this._roleGranter.ensureReady()
+    }
+
+    return this._getRole(name)
+  }
+
+  /**
+   * Get many roles by names
+   */
+  async getMany(names) {
+    if (!this._roleGranter) return []
+
+    if (this._roleGranter.ensureReady) {
+      await this._roleGranter.ensureReady()
+    }
+
+    return names.map(name => this._getRole(name)).filter(Boolean)
+  }
+
+  /**
+   * Create a new role
+   */
+  async create(data) {
+    if (!this._roleGranter?.createRole) {
+      throw new Error('Role creation not supported by this adapter')
+    }
+    return this._roleGranter.createRole(data.name, {
+      label: data.label,
+      permissions: data.permissions || [],
+      inherits: data.inherits || []
+    })
+  }
+
+  /**
+   * Update an existing role
+   */
+  async update(name, data) {
+    if (!this._roleGranter?.updateRole) {
+      throw new Error('Role update not supported by this adapter')
+    }
+    return this._roleGranter.updateRole(name, {
+      label: data.label,
+      permissions: data.permissions,
+      inherits: data.inherits
+    })
+  }
+
+  /**
+   * Patch a role (partial update)
+   */
+  async patch(name, data) {
+    return this.update(name, data)
+  }
+
+  /**
+   * Delete a role
+   */
+  async delete(name) {
+    if (!this._roleGranter?.deleteRole) {
+      throw new Error('Role deletion not supported by this adapter')
+    }
+    return this._roleGranter.deleteRole(name)
+  }
+
+  /**
+   * Get role object from roleGranter
+   * @private
+   */
+  _getRole(name) {
+    if (this._roleGranter.getRole) {
+      return this._roleGranter.getRole(name)
+    }
+    // Fallback for adapters without getRole
+    return {
+      name,
+      label: this._roleGranter.getLabels?.()[name] || name,
+      permissions: this._roleGranter.getPermissions(name),
+      inherits: this._roleGranter.getHierarchy()[name] || []
+    }
+  }
+}

package/src/security/RolesManager.js

@@ -0,0 +1,81 @@
+/**
+ * RolesManager - System entity manager for roles
+ *
+ * Uses RoleGranterStorage as bridge to roleGranter.
+ * Allows SecurityModule to use standard ctx.crud() pattern.
+ */
+
+import { EntityManager } from '../entity/EntityManager.js'
+import { RoleGranterStorage } from './RoleGranterStorage.js'
+
+export class RolesManager extends EntityManager {
+  /**
+   * @param {Object} options
+   * @param {import('./RoleGranterAdapter.js').RoleGranterAdapter} options.roleGranter
+   * @param {import('./PermissionRegistry.js').PermissionRegistry} options.permissionRegistry
+   */
+  constructor(options = {}) {
+    const storage = new RoleGranterStorage(options.roleGranter)
+
+    super({
+      name: 'roles',
+      labelField: 'label',
+      idField: 'name',
+      system: true,  // System-provided entity
+      fields: {
+        name: { type: 'text', label: 'Role Name', required: true },
+        label: { type: 'text', label: 'Display Label' },
+        permissions: { type: 'array', label: 'Permissions', default: [] },
+        inherits: { type: 'array', label: 'Inherits From', default: [] }
+      },
+      storage
+    })
+
+    this._roleGranter = options.roleGranter
+    this._permissionRegistry = options.permissionRegistry
+  }
+
+  /**
+   * Get roleGranter (for RoleForm permission picker)
+   */
+  get roleGranter() {
+    return this._roleGranter
+  }
+
+  /**
+   * Get permission registry (for RoleForm permission picker)
+   */
+  get permissionRegistry() {
+    return this._permissionRegistry
+  }
+
+  /**
+   * Check if roles can be edited
+   */
+  get canPersist() {
+    return this._roleGranter?.canPersist ?? false
+  }
+
+  /**
+   * Protected system roles that cannot be deleted
+   */
+  static PROTECTED_ROLES = ['ROLE_ANONYMOUS']
+
+  // Permission checks based on canPersist
+  canCreate() { return this.canPersist }
+  canUpdate() { return this.canPersist }
+
+  /**
+   * Check if can delete (general or row-specific)
+   * @param {object} [item] - Optional role to check
+   * @returns {boolean}
+   */
+  canDelete(item) {
+    if (!this.canPersist) return false
+    if (item) {
+      // Protected system roles cannot be deleted
+      return !RolesManager.PROTECTED_ROLES.includes(item.name)
+    }
+    return true
+  }
+}

package/src/security/SecurityModule.js

@@ -0,0 +1,73 @@
+/**
+ * SecurityModule - Role management UI
+ *
+ * Provides a page to view/edit roles and permissions.
+ * Works with any RoleGranterAdapter:
+ * - StaticRoleGranterAdapter: read-only view
+ * - PersistableRoleGranterAdapter: full CRUD
+ * - EntityRoleGranterAdapter: full CRUD via entity
+ *
+ * Registers permissions:
+ * - security:roles:read - View roles list
+ * - security:roles:create - Create new roles
+ * - security:roles:update - Edit existing roles
+ * - security:roles:delete - Delete roles
+ *
+ * @example
+ * import { SecurityModule } from 'qdadm/security'
+ *
+ * const kernel = new Kernel({
+ *   moduleDefs: [SecurityModule, ...],
+ *   security: {
+ *     roleGranter: createLocalStorageRoleGranter({ ... })
+ *   }
+ * })
+ */
+
+import { Module } from '../kernel/Module.js'
+import { RolesManager } from './RolesManager.js'
+
+export class SecurityModule extends Module {
+  static name = 'security'
+  static requires = []
+  static priority = 100 // Load late (after other modules register permissions)
+
+  async connect(ctx) {
+    // ════════════════════════════════════════════════════════════════════════
+    // PERMISSIONS
+    // ════════════════════════════════════════════════════════════════════════
+    ctx.permissions('security', {
+      'roles:read': 'View roles and permissions',
+      'roles:create': 'Create new roles',
+      'roles:update': 'Edit role permissions',
+      'roles:delete': 'Delete roles'
+    })
+
+    // ════════════════════════════════════════════════════════════════════════
+    // ENTITY (wraps roleGranter)
+    // ════════════════════════════════════════════════════════════════════════
+    const rolesManager = new RolesManager({
+      roleGranter: ctx.security?.roleGranter,
+      permissionRegistry: ctx.permissionRegistry
+    })
+
+    ctx.entity('roles', rolesManager)
+
+    // ════════════════════════════════════════════════════════════════════════
+    // ROUTES (using ctx.crud helper)
+    // ════════════════════════════════════════════════════════════════════════
+    ctx.crud('roles', {
+      list: () => import('./pages/RoleList.vue'),
+      form: () => import('./pages/RoleForm.vue')
+    }, {
+      basePath: 'security/roles',
+      nav: {
+        section: 'Security',
+        icon: 'pi pi-shield',
+        permission: 'security:roles:read'
+      }
+    })
+  }
+}
+
+export default SecurityModule

package/src/security/StaticRoleGranterAdapter.js

@@ -0,0 +1,114 @@
+import { RoleGranterAdapter } from './RoleGranterAdapter.js'
+
+/**
+ * StaticRoleGranterAdapter - Role granter from config object
+ *
+ * Default implementation for simple apps and demos.
+ * Auto-created when passing role_permissions object to Kernel.
+ *
+ * @example
+ * // Auto-created by Kernel
+ * const kernel = new Kernel({
+ *   security: {
+ *     role_hierarchy: { ROLE_ADMIN: ['ROLE_USER'] },
+ *     role_permissions: {
+ *       ROLE_USER: ['entity:*:read'],
+ *       ROLE_ADMIN: ['**']
+ *     }
+ *   }
+ * })
+ *
+ * // Or explicit creation
+ * const granter = new StaticRoleGranterAdapter({
+ *   role_hierarchy: { ROLE_ADMIN: ['ROLE_USER'] },
+ *   role_permissions: {
+ *     ROLE_USER: ['entity:*:read'],
+ *     ROLE_ADMIN: ['**']
+ *   },
+ *   role_labels: {
+ *     ROLE_USER: 'User',
+ *     ROLE_ADMIN: 'Administrator'
+ *   }
+ * })
+ */
+export class StaticRoleGranterAdapter extends RoleGranterAdapter {
+  /**
+   * @param {Object} config
+   * @param {Object<string, string[]>} [config.role_hierarchy={}] - Role hierarchy
+   * @param {Object<string, string[]>} [config.role_permissions={}] - Role permissions
+   * @param {Object<string, string>} [config.role_labels={}] - Role display labels
+   */
+  constructor(config = {}) {
+    super()
+    this._hierarchy = config.role_hierarchy || {}
+    this._permissions = config.role_permissions || {}
+    this._labels = config.role_labels || {}
+  }
+
+  /**
+   * Get permissions for a role
+   * @param {string} role
+   * @returns {string[]}
+   */
+  getPermissions(role) {
+    return this._permissions[role] || []
+  }
+
+  /**
+   * Get all defined roles
+   * @returns {string[]}
+   */
+  getRoles() {
+    // Combine roles from permissions and hierarchy
+    const roles = new Set([
+      ...Object.keys(this._permissions),
+      ...Object.keys(this._hierarchy)
+    ])
+
+    // Also include inherited roles
+    for (const inherits of Object.values(this._hierarchy)) {
+      for (const r of inherits) {
+        roles.add(r)
+      }
+    }
+
+    return [...roles]
+  }
+
+  /**
+   * Get role hierarchy
+   * @returns {Object<string, string[]>}
+   */
+  getHierarchy() {
+    return this._hierarchy
+  }
+
+  /**
+   * Get role metadata
+   * @param {string} role
+   * @returns {RoleMeta|null}
+   */
+  getRoleMeta(role) {
+    const label = this._labels[role]
+    if (!label) return null
+    return { label }
+  }
+
+  /**
+   * Update role permissions at runtime (for testing or hot-reload)
+   * @param {string} role
+   * @param {string[]} permissions
+   */
+  setPermissions(role, permissions) {
+    this._permissions[role] = permissions
+  }
+
+  /**
+   * Update role hierarchy at runtime
+   * @param {string} role
+   * @param {string[]} inherits
+   */
+  setHierarchy(role, inherits) {
+    this._hierarchy[role] = inherits
+  }
+}

package/src/security/UsersManager.js

@@ -0,0 +1,122 @@
+/**
+ * UsersManager - System entity manager for users
+ *
+ * Provides standard user entity with:
+ * - username, password, role fields
+ * - role linked to roles entity via reference
+ * - Admin-only access by default (customizable)
+ *
+ * @example
+ * // In a module:
+ * ctx.userEntity({
+ *   storage: new ApiStorage({ endpoint: '/api/users' }),
+ *   extraFields: {
+ *     email: { type: 'email', label: 'Email' }
+ *   }
+ * })
+ */
+
+import { EntityManager } from '../entity/EntityManager.js'
+
+export class UsersManager extends EntityManager {
+  /**
+   * @param {Object} options
+   * @param {Object} options.storage - Storage adapter (required)
+   * @param {Object} [options.extraFields={}] - Additional fields beyond username/password/role
+   * @param {string} [options.adminRole='ROLE_ADMIN'] - Role required for user management
+   * @param {boolean} [options.adminOnly=true] - Restrict access to admin role only
+   * @param {Object} [options.fieldOverrides={}] - Override default field configs
+   */
+  constructor(options = {}) {
+    const {
+      storage,
+      extraFields = {},
+      adminRole = 'ROLE_ADMIN',
+      adminOnly = true,
+      fieldOverrides = {},
+      ...rest
+    } = options
+
+    if (!storage) {
+      throw new Error('[UsersManager] storage is required')
+    }
+
+    // Default fields for users
+    const defaultFields = {
+      username: {
+        type: 'text',
+        label: 'Username',
+        required: true,
+        default: '',
+        ...fieldOverrides.username
+      },
+      password: {
+        type: 'password',
+        label: 'Password',
+        required: true,
+        default: '',
+        listable: false,  // Don't show in list view
+        ...fieldOverrides.password
+      },
+      role: {
+        type: 'select',
+        label: 'Role',
+        reference: { entity: 'roles' },  // Links to roles entity
+        default: 'ROLE_USER',
+        ...fieldOverrides.role
+      }
+    }
+
+    super({
+      name: 'users',
+      labelField: 'username',
+      system: true,  // System-provided entity
+      fields: {
+        ...defaultFields,
+        ...extraFields
+      },
+      storage,
+      ...rest
+    })
+
+    this._adminRole = adminRole
+    this._adminOnly = adminOnly
+  }
+
+  /**
+   * Check if current user has admin role
+   * @returns {boolean}
+   * @private
+   */
+  _isAdmin() {
+    const user = this.authAdapter?.getCurrentUser?.()
+    if (!user) return false
+
+    // Check role directly or in roles array
+    const userRole = user.role || user.roles?.[0]
+    if (!userRole) return false
+
+    // Normalize to uppercase with ROLE_ prefix
+    const normalized = userRole.toUpperCase()
+    const roleToCheck = normalized.startsWith('ROLE_') ? normalized : `ROLE_${normalized}`
+
+    return roleToCheck === this._adminRole
+  }
+
+  // Permission checks - admin only by default
+  canRead() {
+    return this._adminOnly ? this._isAdmin() : true
+  }
+
+  canCreate() {
+    return this._adminOnly ? this._isAdmin() : true
+  }
+
+  canUpdate() {
+    return this._adminOnly ? this._isAdmin() : true
+  }
+
+  canDelete() {
+    return this._adminOnly ? this._isAdmin() : true
+  }
+}