@quazardous/qdadm 1.19.3

package/src/security/EntityRolesProvider.ts

@@ -0,0 +1,385 @@
+import { RoleProvider } from './RolesProvider'
+import type {
+  RoleMeta,
+  RoleData,
+  RoleHierarchyMap,
+  RoleProviderContext,
+} from './RolesProvider'
+
+/**
+ * Options for EntityRoleProvider
+ */
+export interface EntityRolesProviderOptions {
+  entityName?: string
+  nameField?: string
+  labelField?: string
+  permissionsField?: string
+  inheritsField?: string
+}
+
+/**
+ * Role entity structure
+ */
+interface RoleEntity {
+  id?: string | number
+  [key: string]: unknown
+}
+
+/**
+ * Entity manager interface (minimal for adapter needs)
+ */
+interface EntityManager {
+  list(params?: Record<string, unknown>): Promise<{ items: RoleEntity[]; data?: RoleEntity[] }>
+  create(data: Record<string, unknown>): Promise<RoleEntity>
+  update(id: string | number, data: Record<string, unknown>): Promise<RoleEntity>
+  delete(id: string | number): Promise<void>
+}
+
+/**
+ * Orchestrator interface (minimal for adapter needs)
+ */
+interface Orchestrator {
+  get(name: string): EntityManager | undefined
+}
+
+/**
+ * Cache structure for roles
+ */
+interface RoleCache {
+  permissions: Record<string, string[]>
+  hierarchy: Record<string, string[]>
+  labels: Record<string, string>
+}
+
+/**
+ * EntityRoleProvider - Roles provider backed by an entity
+ *
+ * Fetches roles and permissions from a 'roles' entity.
+ * Auto-invalidates cache on entity:roles:* signals.
+ * Use this for apps with a role management UI.
+ *
+ * Expected entity schema:
+ * {
+ *   id: 'role-1',
+ *   name: 'ROLE_ADMIN',
+ *   label: 'Administrator',
+ *   permissions: ['entity:**', 'admin:**'],
+ *   inherits: ['ROLE_USER']
+ * }
+ *
+ * @example
+ * // Configure Kernel with entity-based roles
+ * const kernel = new Kernel({
+ *   modules: [SecurityModule, ...],
+ *   security: {
+ *     rolesProvider: new EntityRoleProvider({
+ *       entityName: 'roles',
+ *       nameField: 'name',
+ *       permissionsField: 'permissions',
+ *       inheritsField: 'inherits'
+ *     })
+ *   }
+ * })
+ *
+ * // Load roles before boot
+ * await kernel.options.security.rolesProvider.load()
+ * await kernel.boot()
+ */
+export class EntityRoleProvider extends RoleProvider {
+  private _entityName: string
+  private _nameField: string
+  private _labelField: string
+  private _permissionsField: string
+  private _inheritsField: string
+
+  private _cache: RoleCache | null = null
+  private _ctx: RoleProviderContext | null = null
+  private _orchestrator: Orchestrator | null = null
+  private _signalCleanup: (() => void) | null = null
+  private _loading: Promise<void> | null = null
+
+  constructor(options: EntityRolesProviderOptions = {}) {
+    super()
+    this._entityName = options.entityName || 'roles'
+    this._nameField = options.nameField || 'name'
+    this._labelField = options.labelField || 'label'
+    this._permissionsField = options.permissionsField || 'permissions'
+    this._inheritsField = options.inheritsField || 'inherits'
+  }
+
+  /**
+   * Install adapter (called by Kernel after orchestrator ready)
+   */
+  install(ctx: RoleProviderContext): void {
+    this._ctx = ctx
+    this._orchestrator = ctx.orchestrator as Orchestrator
+
+    // Auto-invalidate on role changes
+    if (ctx.signals) {
+      this._signalCleanup = ctx.signals.on(`entity:${this._entityName}:**`, () => {
+        this.invalidate()
+      })
+    }
+  }
+
+  /**
+   * Uninstall adapter (cleanup)
+   */
+  uninstall(): void {
+    if (this._signalCleanup) {
+      this._signalCleanup()
+      this._signalCleanup = null
+    }
+    this._ctx = null
+    this._orchestrator = null
+    this._cache = null
+    this._loading = null
+  }
+
+  /**
+   * Load roles from entity (async, must be called before use)
+   */
+  async load(): Promise<void> {
+    // Prevent concurrent loads
+    if (this._loading) {
+      return this._loading
+    }
+
+    this._loading = this._doLoad()
+    await this._loading
+    this._loading = null
+  }
+
+  /**
+   * Internal load implementation
+   */
+  private async _doLoad(): Promise<void> {
+    const manager = this._orchestrator?.get(this._entityName)
+    if (!manager) {
+      console.warn(`[EntityRolesProvider] Entity '${this._entityName}' not found`)
+      this._cache = { permissions: {}, hierarchy: {}, labels: {} }
+      return
+    }
+
+    try {
+      const { items: roles } = await manager.list({ page_size: 1000 })
+
+      // Build cache
+      const permissions: Record<string, string[]> = {}
+      const hierarchy: Record<string, string[]> = {}
+      const labels: Record<string, string> = {}
+
+      for (const role of roles) {
+        const name = role[this._nameField] as string
+        if (!name) continue
+
+        permissions[name] = (role[this._permissionsField] as string[]) || []
+        labels[name] = (role[this._labelField] as string) || name
+
+        const inherits = role[this._inheritsField] as string[] | undefined
+        if (inherits && inherits.length > 0) {
+          hierarchy[name] = inherits
+        }
+      }
+
+      this._cache = { permissions, hierarchy, labels }
+    } catch (error) {
+      console.error(`[EntityRolesProvider] Failed to load roles:`, error)
+      this._cache = { permissions: {}, hierarchy: {}, labels: {} }
+    }
+  }
+
+  /**
+   * Get cache, throwing if not loaded
+   */
+  private _getCache(): RoleCache {
+    if (!this._cache) {
+      throw new Error(
+        '[EntityRolesProvider] Roles not loaded. Call load() before using the adapter.'
+      )
+    }
+    return this._cache
+  }
+
+  /**
+   * Get permissions for a role
+   */
+  getPermissions(role: string): string[] {
+    const cache = this._getCache()
+    return cache.permissions[role] || []
+  }
+
+  /**
+   * Get all defined roles
+   */
+  getRoles(): string[] {
+    const cache = this._getCache()
+    return Object.keys(cache.permissions)
+  }
+
+  /**
+   * Get role hierarchy
+   */
+  getHierarchy(): RoleHierarchyMap {
+    const cache = this._getCache()
+    return cache.hierarchy
+  }
+
+  /**
+   * Get role metadata
+   */
+  getRoleMeta(role: string): RoleMeta | null {
+    const cache = this._getCache()
+    const label = cache.labels[role]
+    if (!label) return null
+    return { label }
+  }
+
+  /**
+   * Invalidate cache (triggers reload on next access)
+   * Call this after role changes
+   */
+  invalidate(): void {
+    this._cache = null
+  }
+
+  /**
+   * Check if cache is loaded
+   */
+  get isLoaded(): boolean {
+    return this._cache !== null
+  }
+
+  /**
+   * Entity-backed adapter can always persist (via entity manager)
+   */
+  get canPersist(): boolean {
+    return true
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Role query methods
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Check if a role exists
+   */
+  roleExists(role: string): boolean {
+    const cache = this._getCache()
+    return cache.permissions[role] !== undefined
+  }
+
+  /**
+   * Get complete role object
+   */
+  getRole(role: string): RoleData | null {
+    const cache = this._getCache()
+    if (cache.permissions[role] === undefined) {
+      return null
+    }
+    return {
+      name: role,
+      label: cache.labels[role] || role,
+      permissions: cache.permissions[role] || [],
+      inherits: cache.hierarchy[role] || [],
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Mutation methods (via entity manager)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get the entity manager for roles
+   */
+  private _getManager(): EntityManager {
+    const manager = this._orchestrator?.get(this._entityName)
+    if (!manager) {
+      throw new Error(`Entity '${this._entityName}' not found`)
+    }
+    return manager
+  }
+
+  /**
+   * Create a new role
+   */
+  async createRole(
+    name: string,
+    { label, permissions = [], inherits = [] }: { label?: string; permissions?: string[]; inherits?: string[] } = {}
+  ): Promise<RoleEntity> {
+    if (this.roleExists(name)) {
+      throw new Error(`Role '${name}' already exists`)
+    }
+    const manager = this._getManager()
+    const data = {
+      [this._nameField]: name,
+      [this._labelField]: label || name,
+      [this._permissionsField]: permissions,
+      [this._inheritsField]: inherits,
+    }
+    const result = await manager.create(data)
+    this.invalidate()
+    return result
+  }
+
+  /**
+   * Update an existing role
+   */
+  async updateRole(
+    name: string,
+    { label, permissions, inherits }: { label?: string; permissions?: string[]; inherits?: string[] } = {}
+  ): Promise<RoleEntity> {
+    // Ensure loaded first
+    this._getCache()
+    const manager = this._getManager()
+
+    // Find the role entity by name
+    const response = await manager.list({
+      filter: { [this._nameField]: name },
+      limit: 1,
+    })
+    const roles = response.data || response.items
+    if (roles.length === 0) {
+      throw new Error(`Role '${name}' does not exist`)
+    }
+
+    const roleEntity = roles[0]
+    if (!roleEntity) {
+      throw new Error(`Role '${name}' does not exist`)
+    }
+    const updates: Record<string, unknown> = {}
+    if (label !== undefined) updates[this._labelField] = label
+    if (permissions !== undefined) updates[this._permissionsField] = permissions
+    if (inherits !== undefined) updates[this._inheritsField] = inherits
+
+    const result = await manager.update(roleEntity.id as string | number, updates)
+    this.invalidate()
+    return result
+  }
+
+  /**
+   * Delete a role
+   */
+  async deleteRole(name: string): Promise<void> {
+    // Ensure loaded first
+    this._getCache()
+    const manager = this._getManager()
+
+    // Find the role entity by name
+    const response = await manager.list({
+      filter: { [this._nameField]: name },
+      limit: 1,
+    })
+    const roles = response.data || response.items
+    if (roles.length === 0) {
+      throw new Error(`Role '${name}' does not exist`)
+    }
+
+    const roleToDelete = roles[0]
+    if (!roleToDelete) {
+      throw new Error(`Role '${name}' does not exist`)
+    }
+    await manager.delete(roleToDelete.id as string | number)
+    this.invalidate()
+  }
+}

package/src/security/PermissionMatcher.ts

@@ -0,0 +1,152 @@
+/**
+ * PermissionMatcher - Wildcard permission matching
+ *
+ * Supports two wildcard patterns (similar to signals):
+ * - `*` matches exactly one segment
+ * - `**` matches zero or more segments (greedy)
+ *
+ * Permission format: namespace:target:action
+ * Examples:
+ *   entity:books:read      - specific permission
+ *   entity:books:*         - any action on books
+ *   entity:*:read          - read on any entity
+ *   entity:**              - all entity permissions
+ *   **                     - super admin (matches everything)
+ *
+ * @example
+ * PermissionMatcher.matches('entity:*:read', 'entity:books:read')  // true
+ * PermissionMatcher.matches('entity:**', 'entity:books:read')      // true
+ * PermissionMatcher.matches('**', 'anything:here')                 // true
+ */
+export class PermissionMatcher {
+  /**
+   * Check if a permission pattern matches a required permission
+   *
+   * @param pattern - Pattern with wildcards (e.g., 'entity:*:read')
+   * @param required - Required permission (e.g., 'entity:books:read')
+   * @returns True if pattern matches required
+   *
+   * @example
+   * PermissionMatcher.matches('entity:books:read', 'entity:books:read')  // true (exact)
+   * PermissionMatcher.matches('entity:books:*', 'entity:books:read')     // true (* = one segment)
+   * PermissionMatcher.matches('entity:*:read', 'entity:books:read')      // true
+   * PermissionMatcher.matches('entity:**', 'entity:books:read')          // true (** = greedy)
+   * PermissionMatcher.matches('**', 'entity:books:read')                 // true (super admin)
+   * PermissionMatcher.matches('entity:*:read', 'entity:a:b:read')        // false (* = exactly one)
+   */
+  static matches(pattern: string, required: string): boolean {
+    // Super admin
+    if (pattern === '**') return true
+
+    // Exact match
+    if (pattern === required) return true
+
+    const patternParts = pattern.split(':')
+    const requiredParts = required.split(':')
+
+    return this._matchParts(patternParts, requiredParts, 0, 0)
+  }
+
+  /**
+   * Recursive matching of pattern parts against required parts
+   */
+  private static _matchParts(
+    pattern: string[],
+    required: string[],
+    pi: number,
+    ri: number
+  ): boolean {
+    // Both exhausted = match
+    if (pi === pattern.length && ri === required.length) {
+      return true
+    }
+
+    // Pattern exhausted but required has more = no match
+    if (pi === pattern.length) {
+      return false
+    }
+
+    const p = pattern[pi]
+
+    // ** matches zero or more remaining segments
+    if (p === '**') {
+      // ** at end matches everything remaining
+      if (pi === pattern.length - 1) {
+        return true
+      }
+
+      // Try matching ** against 0, 1, 2, ... segments
+      for (let skip = 0; skip <= required.length - ri; skip++) {
+        if (this._matchParts(pattern, required, pi + 1, ri + skip)) {
+          return true
+        }
+      }
+      return false
+    }
+
+    // Required exhausted but pattern has more (and not **)
+    if (ri === required.length) {
+      return false
+    }
+
+    // * matches exactly one segment
+    if (p === '*') {
+      return this._matchParts(pattern, required, pi + 1, ri + 1)
+    }
+
+    // Literal match
+    if (p === required[ri]) {
+      return this._matchParts(pattern, required, pi + 1, ri + 1)
+    }
+
+    return false
+  }
+
+  /**
+   * Check if any pattern in array matches the required permission
+   *
+   * @param patterns - Array of patterns (user's permissions)
+   * @param required - Required permission to check
+   * @returns True if any pattern matches
+   *
+   * @example
+   * const userPerms = ['entity:*:read', 'entity:*:list', 'auth:impersonate']
+   * PermissionMatcher.any(userPerms, 'entity:books:read')  // true
+   * PermissionMatcher.any(userPerms, 'entity:books:delete') // false
+   */
+  static any(patterns: string[] | null | undefined, required: string): boolean {
+    if (!patterns || patterns.length === 0) return false
+    return patterns.some((p) => this.matches(p, required))
+  }
+
+  /**
+   * Filter permissions that match a pattern
+   *
+   * @param permissions - Array of specific permissions
+   * @param pattern - Pattern to filter by
+   * @returns Permissions that match the pattern
+   *
+   * @example
+   * const allPerms = ['entity:books:read', 'entity:books:create', 'auth:login']
+   * PermissionMatcher.filter(allPerms, 'entity:books:*')  // ['entity:books:read', 'entity:books:create']
+   */
+  static filter(permissions: string[], pattern: string): string[] {
+    return permissions.filter((p) => this.matches(pattern, p))
+  }
+
+  /**
+   * Expand a pattern against registered permissions
+   * Useful for UI: show what a wildcard pattern actually grants
+   *
+   * @param pattern - Pattern to expand
+   * @param allPermissions - All registered permissions
+   * @returns Permissions that the pattern would grant
+   *
+   * @example
+   * const registry = ['entity:books:read', 'entity:books:create', 'entity:loans:read']
+   * PermissionMatcher.expand('entity:*:read', registry)  // ['entity:books:read', 'entity:loans:read']
+   */
+  static expand(pattern: string, allPermissions: string[]): string[] {
+    return allPermissions.filter((p) => this.matches(pattern, p))
+  }
+}