@quazardous/qdadm 1.19.3

package/src/security/RolesProvider.ts

@@ -0,0 +1,167 @@
+/**
+ * RoleProvider - Interface for role → permissions mapping
+ *
+ * The framework provides StaticRoleProvider (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: {
+ *   rolesProvider: new EntityRoleProvider({ entityName: 'roles' })
+ * }
+ */
+
+/**
+ * Role metadata for display purposes
+ */
+export interface RoleMeta {
+  label?: string
+  description?: string
+}
+
+/**
+ * Complete role data object
+ *
+ * Note: `id` is optional and maps to `name` for EntityManager compatibility
+ * when using idField: 'name'
+ */
+export interface RoleData {
+  name: string
+  label: string
+  permissions: string[]
+  inherits: string[]
+  /** Virtual id field (equals name) for EntityRecord compatibility */
+  id?: string
+}
+
+/**
+ * Role hierarchy mapping
+ */
+export type RoleHierarchyMap = Record<string, string[]>
+
+/**
+ * Role permissions mapping
+ */
+export type RolePermissionsMap = Record<string, string[]>
+
+/**
+ * Role labels mapping
+ */
+export type RoleLabelsMap = Record<string, string>
+
+/**
+ * Kernel context interface (minimal for adapter needs)
+ */
+export interface RoleProviderContext {
+  signals?: {
+    on: (pattern: string, handler: () => void) => () => void
+  }
+  orchestrator?: {
+    get: (name: string) => unknown
+  }
+  [key: string]: unknown
+}
+
+export class RoleProvider {
+  /**
+   * Get permissions granted to a role
+   *
+   * @param role - Role name (e.g., 'ROLE_USER')
+   * @returns Array of permission strings (may include wildcards)
+   *
+   * @example
+   * adapter.getPermissions('ROLE_ADMIN')
+   * // ['entity:**', 'admin:**']
+   */
+  getPermissions(_role: string): string[] {
+    throw new Error('RoleProvider.getPermissions() must be implemented')
+  }
+
+  /**
+   * Get all defined roles
+   *
+   * @returns Array of role names
+   *
+   * @example
+   * adapter.getRoles()
+   * // ['ROLE_USER', 'ROLE_ADMIN', 'ROLE_SUPER_ADMIN']
+   */
+  getRoles(): string[] {
+    throw new Error('RoleProvider.getRoles() must be implemented')
+  }
+
+  /**
+   * Get role hierarchy map
+   *
+   * @returns Role → inherited roles
+   *
+   * @example
+   * adapter.getHierarchy()
+   * // { ROLE_ADMIN: ['ROLE_USER'], ROLE_SUPER_ADMIN: ['ROLE_ADMIN'] }
+   */
+  getHierarchy(): RoleHierarchyMap {
+    throw new Error('RoleProvider.getHierarchy() must be implemented')
+  }
+
+  /**
+   * Get the role for unauthenticated users
+   *
+   * Always returns 'ROLE_ANONYMOUS' (convention)
+   *
+   * @returns Anonymous role name
+   */
+  getAnonymousRole(): string {
+    return 'ROLE_ANONYMOUS'
+  }
+
+  /**
+   * Get role metadata (label, description)
+   * Optional - for display purposes
+   *
+   * @param role - Role name
+   * @returns Role metadata or null
+   */
+  getRoleMeta(_role: string): RoleMeta | null {
+    return null
+  }
+
+  /**
+   * Install adapter (called by Kernel when context is ready)
+   * Override for adapters that need initialization
+   *
+   * @param ctx - Kernel context
+   */
+  install(_ctx: RoleProviderContext): void {
+    // Override if needed
+  }
+
+  /**
+   * Uninstall adapter (cleanup)
+   */
+  uninstall(): void {
+    // 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.
+   */
+  get canPersist(): boolean {
+    return false
+  }
+}

package/src/security/RolesProviderStorage.ts

@@ -0,0 +1,211 @@
+/**
+ * RoleProviderStorage - Storage bridge for rolesProvider
+ *
+ * Implements Storage interface and delegates to rolesProvider.
+ * Allows RolesManager to use standard EntityManager patterns.
+ */
+
+import type { StorageCapabilities } from '../types'
+import type { RoleProvider, RoleData } from './RolesProvider'
+
+/**
+ * List parameters for role listing
+ */
+export interface RoleListParams {
+  search?: string
+  [key: string]: unknown
+}
+
+/**
+ * List result for roles
+ */
+export interface RoleListResult {
+  items: RoleData[]
+  total: number
+}
+
+/**
+ * Role data for create/update operations
+ */
+export interface RoleInput {
+  name: string
+  label?: string
+  permissions?: string[]
+  inherits?: string[]
+}
+
+/**
+ * Extended RoleProvider with optional mutation methods
+ */
+interface MutableRoleProvider extends RoleProvider {
+  ensureReady?(): Promise<void>
+  getLabels?(): Record<string, string>
+  getRole?(name: string): RoleData | null
+  createRole?(
+    name: string,
+    options: { label?: string; permissions?: string[]; inherits?: string[] }
+  ): Promise<RoleData>
+  updateRole?(
+    name: string,
+    options: { label?: string; permissions?: string[]; inherits?: string[] }
+  ): Promise<RoleData>
+  deleteRole?(name: string): Promise<void>
+}
+
+export class RoleProviderStorage {
+  /**
+   * Storage name for debug display (survives minification)
+   */
+  static storageName = 'RoleProviderStorage'
+
+  /**
+   * Static capabilities (standard storage pattern)
+   */
+  static capabilities: StorageCapabilities = {
+    supportsTotal: true,
+    supportsFilters: false,
+    supportsPagination: false,
+    supportsCaching: false, // In-memory via rolesProvider, no need for EntityManager cache
+  }
+
+  private _rolesProvider: MutableRoleProvider | null
+
+  constructor(rolesProvider: RoleProvider | null) {
+    this._rolesProvider = rolesProvider as MutableRoleProvider | null
+  }
+
+  /**
+   * Instance capabilities (merge static + dynamic)
+   *
+   * Dynamic properties:
+   * - requiresAuth: false (roles are system data)
+   * - readOnly: based on rolesProvider.canPersist
+   */
+  get capabilities(): StorageCapabilities & { requiresAuth: boolean; readOnly: boolean } {
+    return {
+      ...RoleProviderStorage.capabilities,
+      requiresAuth: false,
+      readOnly: !this._rolesProvider?.canPersist,
+    }
+  }
+
+  /**
+   * List all roles
+   */
+  async list(params: RoleListParams = {}): Promise<RoleListResult> {
+    if (!this._rolesProvider) {
+      return { items: [], total: 0 }
+    }
+
+    // Ensure loaded for adapters that need it
+    if (this._rolesProvider.ensureReady) {
+      await this._rolesProvider.ensureReady()
+    }
+
+    const roleNames = this._rolesProvider.getRoles()
+    const roles = roleNames.map((name) => this._getRole(name)).filter((r): r is RoleData => r !== null)
+
+    // 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: string): Promise<RoleData | null> {
+    if (!this._rolesProvider) return null
+
+    if (this._rolesProvider.ensureReady) {
+      await this._rolesProvider.ensureReady()
+    }
+
+    return this._getRole(name)
+  }
+
+  /**
+   * Get many roles by names
+   */
+  async getMany(names: string[]): Promise<RoleData[]> {
+    if (!this._rolesProvider) return []
+
+    if (this._rolesProvider.ensureReady) {
+      await this._rolesProvider.ensureReady()
+    }
+
+    return names.map((name) => this._getRole(name)).filter((r): r is RoleData => r !== null)
+  }
+
+  /**
+   * Create a new role
+   */
+  async create(data: RoleInput): Promise<RoleData> {
+    if (!this._rolesProvider?.createRole) {
+      throw new Error('Role creation not supported by this adapter')
+    }
+    return this._rolesProvider.createRole(data.name, {
+      label: data.label,
+      permissions: data.permissions || [],
+      inherits: data.inherits || [],
+    })
+  }
+
+  /**
+   * Update an existing role
+   */
+  async update(name: string, data: Partial<RoleInput>): Promise<RoleData> {
+    if (!this._rolesProvider?.updateRole) {
+      throw new Error('Role update not supported by this adapter')
+    }
+    return this._rolesProvider.updateRole(name, {
+      label: data.label,
+      permissions: data.permissions,
+      inherits: data.inherits,
+    })
+  }
+
+  /**
+   * Patch a role (partial update)
+   */
+  async patch(name: string, data: Partial<RoleInput>): Promise<RoleData> {
+    return this.update(name, data)
+  }
+
+  /**
+   * Delete a role
+   */
+  async delete(name: string): Promise<void> {
+    if (!this._rolesProvider?.deleteRole) {
+      throw new Error('Role deletion not supported by this adapter')
+    }
+    return this._rolesProvider.deleteRole(name)
+  }
+
+  /**
+   * Get role object from rolesProvider
+   */
+  private _getRole(name: string): RoleData | null {
+    if (!this._rolesProvider) return null
+
+    if (this._rolesProvider.getRole) {
+      return this._rolesProvider.getRole(name)
+    }
+    // Fallback for adapters without getRole
+    return {
+      name,
+      label: this._rolesProvider.getLabels?.()[name] || name,
+      permissions: this._rolesProvider.getPermissions(name),
+      inherits: this._rolesProvider.getHierarchy()[name] || [],
+    }
+  }
+}

package/src/security/SecurityModule.ts

@@ -0,0 +1,94 @@
+/**
+ * SecurityModule - Role management UI
+ *
+ * Provides a page to view/edit roles and permissions.
+ * Works with any RoleProvider:
+ * - StaticRoleProvider: read-only view
+ * - PersistableRoleProvider: full CRUD
+ * - EntityRoleProvider: full CRUD via entity
+ *
+ * Dynamically registers permissions from managers:
+ * - RolesManager.adminPermission (default: security:roles:manage)
+ * - security:users:manage (for UsersManager)
+ *
+ * @example
+ * import { SecurityModule } from '@quazardous/qdadm/security'
+ *
+ * const kernel = new Kernel({
+ *   moduleDefs: [SecurityModule, ...],
+ *   security: {
+ *     rolesProvider: createLocalStorageRolesProvider({ ... })
+ *   }
+ * })
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import { Module } from '../kernel/Module'
+import { RolesManager } from './RolesManager'
+import type { RoleProvider } from './RolesProvider'
+import type { PermissionRegistry } from './PermissionRegistry'
+
+/**
+ * Kernel context interface for modules
+ */
+interface ModuleContext {
+  security?: {
+    rolesProvider?: RoleProvider
+  }
+  permissionRegistry?: PermissionRegistry
+  entity(name: string, manager: unknown): void
+  permissions(namespace: string, permissions: Record<string, string>): void
+  crud(
+    name: string,
+    pages: { list?: () => Promise<unknown>; form?: () => Promise<unknown> },
+    options?: { basePath?: string; nav?: { section?: string; icon?: string; permission?: string } }
+  ): void
+}
+
+export class SecurityModule extends Module {
+  static override moduleName = 'security'
+  static override requires: string[] = []
+  static override priority = 100 // Load late (after other modules register permissions)
+
+  async connect(ctx: ModuleContext): Promise<void> {
+    // ════════════════════════════════════════════════════════════════════════
+    // ENTITY (wraps rolesProvider)
+    // ════════════════════════════════════════════════════════════════════════
+    const rolesManager = new RolesManager({
+      rolesProvider: ctx.security?.rolesProvider ?? null,
+      permissionRegistry: ctx.permissionRegistry ?? null,
+    })
+
+    ctx.entity('roles', rolesManager)
+
+    // ════════════════════════════════════════════════════════════════════════
+    // PERMISSIONS (registered after entity so we can read adminPermission)
+    // ════════════════════════════════════════════════════════════════════════
+    const rolesPerm = rolesManager.adminPermission?.replace('security:', '') || 'roles:manage'
+    ctx.permissions('security', {
+      [rolesPerm]: 'Manage roles (view, create, edit, delete)',
+      'users:manage': 'Manage users (view, create, edit, delete)',
+    })
+
+    // ════════════════════════════════════════════════════════════════════════
+    // 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/StaticRolesProvider.ts

@@ -0,0 +1,117 @@
+import { RoleProvider } from './RolesProvider'
+import type {
+  RoleMeta,
+  RoleHierarchyMap,
+  RolePermissionsMap,
+  RoleLabelsMap,
+} from './RolesProvider'
+
+/**
+ * Static roles provider configuration
+ */
+export interface StaticRolesProviderConfig {
+  role_hierarchy?: RoleHierarchyMap
+  role_permissions?: RolePermissionsMap
+  role_labels?: RoleLabelsMap
+}
+
+/**
+ * StaticRoleProvider - Roles provider 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 provider = new StaticRoleProvider({
+ *   role_hierarchy: { ROLE_ADMIN: ['ROLE_USER'] },
+ *   role_permissions: {
+ *     ROLE_USER: ['entity:*:read'],
+ *     ROLE_ADMIN: ['**']
+ *   },
+ *   role_labels: {
+ *     ROLE_USER: 'User',
+ *     ROLE_ADMIN: 'Administrator'
+ *   }
+ * })
+ */
+export class StaticRoleProvider extends RoleProvider {
+  protected _hierarchy: RoleHierarchyMap
+  protected _permissions: RolePermissionsMap
+  protected _labels: RoleLabelsMap
+
+  constructor(config: StaticRolesProviderConfig = {}) {
+    super()
+    this._hierarchy = config.role_hierarchy || {}
+    this._permissions = config.role_permissions || {}
+    this._labels = config.role_labels || {}
+  }
+
+  /**
+   * Get permissions for a role
+   */
+  getPermissions(role: string): string[] {
+    return this._permissions[role] || []
+  }
+
+  /**
+   * Get all defined roles
+   */
+  getRoles(): string[] {
+    // Combine roles from permissions and hierarchy
+    const roles = new Set<string>([
+      ...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
+   */
+  getHierarchy(): RoleHierarchyMap {
+    return this._hierarchy
+  }
+
+  /**
+   * Get role metadata
+   */
+  getRoleMeta(role: string): RoleMeta | null {
+    const label = this._labels[role]
+    if (!label) return null
+    return { label }
+  }
+
+  /**
+   * Update role permissions at runtime (for testing or hot-reload)
+   */
+  setPermissions(role: string, permissions: string[]): void {
+    this._permissions[role] = permissions
+  }
+
+  /**
+   * Update role hierarchy at runtime
+   */
+  setHierarchy(role: string, inherits: string[]): void {
+    this._hierarchy[role] = inherits
+  }
+}