qdadm 0.36.0 → 0.38.1

package/src/security/EntityRoleGranterAdapter.js

@@ -0,0 +1,350 @@
+import { RoleGranterAdapter } from './RoleGranterAdapter.js'
+
+/**
+ * EntityRoleGranterAdapter - Role granter 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: {
+ *     roleGranter: new EntityRoleGranterAdapter({
+ *       entityName: 'roles',
+ *       nameField: 'name',
+ *       permissionsField: 'permissions',
+ *       inheritsField: 'inherits'
+ *     })
+ *   }
+ * })
+ *
+ * // Load roles before boot
+ * await kernel.options.security.roleGranter.load()
+ * await kernel.boot()
+ */
+export class EntityRoleGranterAdapter extends RoleGranterAdapter {
+  /**
+   * @param {Object} options
+   * @param {string} [options.entityName='roles'] - Entity name for roles
+   * @param {string} [options.nameField='name'] - Field for role name
+   * @param {string} [options.labelField='label'] - Field for display label
+   * @param {string} [options.permissionsField='permissions'] - Field for permissions array
+   * @param {string} [options.inheritsField='inherits'] - Field for parent roles (hierarchy)
+   */
+  constructor(options = {}) {
+    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'
+
+    this._cache = null
+    this._ctx = null
+    this._orchestrator = null
+    this._signalCleanup = null
+    this._loading = null
+  }
+
+  /**
+   * Install adapter (called by Kernel after orchestrator ready)
+   * @param {Object} ctx - Kernel context
+   */
+  install(ctx) {
+    this._ctx = ctx
+    this._orchestrator = ctx.orchestrator
+
+    // Auto-invalidate on role changes
+    if (ctx.signals) {
+      this._signalCleanup = ctx.signals.on(`entity:${this._entityName}:**`, () => {
+        this.invalidate()
+      })
+    }
+  }
+
+  /**
+   * Uninstall adapter (cleanup)
+   */
+  uninstall() {
+    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)
+   * @returns {Promise<void>}
+   */
+  async load() {
+    // 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() {
+    const manager = this._orchestrator?.get(this._entityName)
+    if (!manager) {
+      console.warn(`[EntityRoleGranter] Entity '${this._entityName}' not found`)
+      this._cache = { permissions: {}, hierarchy: {}, labels: {} }
+      return
+    }
+
+    try {
+      const { data: roles } = await manager.list({ limit: 1000 })
+
+      // Build cache
+      const permissions = {}
+      const hierarchy = {}
+      const labels = {}
+
+      for (const role of roles) {
+        const name = role[this._nameField]
+        if (!name) continue
+
+        permissions[name] = role[this._permissionsField] || []
+        labels[name] = role[this._labelField] || name
+
+        const inherits = role[this._inheritsField]
+        if (inherits?.length > 0) {
+          hierarchy[name] = inherits
+        }
+      }
+
+      this._cache = { permissions, hierarchy, labels }
+    } catch (error) {
+      console.error(`[EntityRoleGranter] Failed to load roles:`, error)
+      this._cache = { permissions: {}, hierarchy: {}, labels: {} }
+    }
+  }
+
+  /**
+   * Ensure cache is loaded (throws if not)
+   * @private
+   */
+  _ensureLoaded() {
+    if (!this._cache) {
+      throw new Error(
+        '[EntityRoleGranter] Roles not loaded. Call load() before using the adapter.'
+      )
+    }
+  }
+
+  /**
+   * Get permissions for a role
+   * @param {string} role
+   * @returns {string[]}
+   */
+  getPermissions(role) {
+    this._ensureLoaded()
+    return this._cache.permissions[role] || []
+  }
+
+  /**
+   * Get all defined roles
+   * @returns {string[]}
+   */
+  getRoles() {
+    this._ensureLoaded()
+    return Object.keys(this._cache.permissions)
+  }
+
+  /**
+   * Get role hierarchy
+   * @returns {Object<string, string[]>}
+   */
+  getHierarchy() {
+    this._ensureLoaded()
+    return this._cache.hierarchy
+  }
+
+  /**
+   * Get role metadata
+   * @param {string} role
+   * @returns {RoleMeta|null}
+   */
+  getRoleMeta(role) {
+    this._ensureLoaded()
+    const label = this._cache.labels[role]
+    if (!label) return null
+    return { label }
+  }
+
+  /**
+   * Invalidate cache (triggers reload on next access)
+   * Call this after role changes
+   */
+  invalidate() {
+    this._cache = null
+  }
+
+  /**
+   * Check if cache is loaded
+   * @returns {boolean}
+   */
+  get isLoaded() {
+    return this._cache !== null
+  }
+
+  /**
+   * Entity-backed adapter can always persist (via entity manager)
+   * @returns {boolean}
+   */
+  get canPersist() {
+    return true
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Role query methods
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Check if a role exists
+   * @param {string} role - Role name
+   * @returns {boolean}
+   */
+  roleExists(role) {
+    this._ensureLoaded()
+    return this._cache.permissions[role] !== undefined
+  }
+
+  /**
+   * Get complete role object
+   * @param {string} role - Role name
+   * @returns {Object|null}
+   */
+  getRole(role) {
+    this._ensureLoaded()
+    if (!this.roleExists(role)) {
+      return null
+    }
+    return {
+      name: role,
+      label: this._cache.labels[role] || role,
+      permissions: this._cache.permissions[role] || [],
+      inherits: this._cache.hierarchy[role] || []
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Mutation methods (via entity manager)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get the entity manager for roles
+   * @returns {Object}
+   * @private
+   */
+  _getManager() {
+    const manager = this._orchestrator?.get(this._entityName)
+    if (!manager) {
+      throw new Error(`Entity '${this._entityName}' not found`)
+    }
+    return manager
+  }
+
+  /**
+   * Create a new role
+   * @param {string} name - Role name
+   * @param {Object} [options]
+   * @param {string} [options.label] - Display label
+   * @param {string[]} [options.permissions=[]] - Permissions
+   * @param {string[]} [options.inherits=[]] - Parent roles
+   * @returns {Promise<Object>} Created role entity
+   */
+  async createRole(name, { label, permissions = [], inherits = [] } = {}) {
+    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
+   * @param {string} name - Role name
+   * @param {Object} [options]
+   * @param {string} [options.label] - Display label
+   * @param {string[]} [options.permissions] - Permissions
+   * @param {string[]} [options.inherits] - Parent roles
+   * @returns {Promise<Object>} Updated role entity
+   */
+  async updateRole(name, { label, permissions, inherits } = {}) {
+    this._ensureLoaded()
+    const manager = this._getManager()
+
+    // Find the role entity by name
+    const { data: roles } = await manager.list({
+      filter: { [this._nameField]: name },
+      limit: 1
+    })
+    if (roles.length === 0) {
+      throw new Error(`Role '${name}' does not exist`)
+    }
+
+    const roleEntity = roles[0]
+    const updates = {}
+    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, updates)
+    this.invalidate()
+    return result
+  }
+
+  /**
+   * Delete a role
+   * @param {string} name - Role name
+   * @returns {Promise<void>}
+   */
+  async deleteRole(name) {
+    this._ensureLoaded()
+    const manager = this._getManager()
+
+    // Find the role entity by name
+    const { data: roles } = await manager.list({
+      filter: { [this._nameField]: name },
+      limit: 1
+    })
+    if (roles.length === 0) {
+      throw new Error(`Role '${name}' does not exist`)
+    }
+
+    await manager.delete(roles[0].id)
+    this.invalidate()
+  }
+}

package/src/security/PermissionMatcher.js

@@ -0,0 +1,148 @@
+/**
+ * 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 {string} pattern - Pattern with wildcards (e.g., 'entity:*:read')
+   * @param {string} required - Required permission (e.g., 'entity:books:read')
+   * @returns {boolean} 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, required) {
+    // 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, required, pi, ri) {
+    // 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 {string[]} patterns - Array of patterns (user's permissions)
+   * @param {string} required - Required permission to check
+   * @returns {boolean} 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, required) {
+    if (!patterns || patterns.length === 0) return false
+    return patterns.some(p => this.matches(p, required))
+  }
+
+  /**
+   * Filter permissions that match a pattern
+   *
+   * @param {string[]} permissions - Array of specific permissions
+   * @param {string} pattern - Pattern to filter by
+   * @returns {string[]} 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, pattern) {
+    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 {string} pattern - Pattern to expand
+   * @param {string[]} allPermissions - All registered permissions
+   * @returns {string[]} 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, allPermissions) {
+    return allPermissions.filter(p => this.matches(pattern, p))
+  }
+}