qdadm 0.36.0 → 0.38.0

package/src/entity/auth/EntityAuthAdapter.js

@@ -1,37 +1,31 @@
 /**
- * EntityAuthAdapter - Interface for entity-level permission checks
+ * EntityAuthAdapter - Thin layer for entity-level permission checks
  *
- * Applications implement this interface to plug their authorization
- * system into qdadm's EntityManager. The adapter provides two levels of permission checks:
+ * Provides entity-level permission checking by delegating to SecurityChecker.
+ * All methods have sensible defaults - subclass only if you need custom behavior.
  *
- * 1. **Scopes** (action-level): Can the user perform this action on this entity type?
- *    Example: Can user create invoices? Can user delete users?
+ * Default behavior (when SecurityChecker is configured):
+ * - canPerform() → isGranted('entity:{entity}:{action}')
+ * - canAccessRecord() → isGranted('entity:{entity}:read', record)
+ * - getCurrentUser() → uses callback if provided, null otherwise
  *
- * 2. **Silos** (record-level): Can the user access this specific record?
- *    Example: Can user see invoice #123? (ownership, team membership, etc.)
- *
- * Note: For user session authentication (login/logout), see SessionAuthAdapter.
- *
- * Usage:
+ * Usage patterns:
  * ```js
- * class MyEntityAuthAdapter extends EntityAuthAdapter {
- *   canPerform(entity, action) {
- *     const user = this.getCurrentUser()
- *     return user?.permissions?.includes(`${entity}:${action}`)
- *   }
- *
- *   canAccessRecord(entity, record) {
- *     const user = this.getCurrentUser()
- *     return record.owner_id === user?.id || record.team_id === user?.team_id
- *   }
+ * // 1. Callback-based (simplest - no subclass needed)
+ * const adapter = new EntityAuthAdapter({
+ *   getCurrentUser: () => myAuthStore.user
+ * })
  *
- *   getCurrentUser() {
- *     return this._userStore.currentUser
+ * // 2. Subclass-based (for custom permission logic)
+ * class MyAdapter extends EntityAuthAdapter {
+ *   canPerform(entity, action) {
+ *     if (['orders', 'invoices'].includes(entity) && !this.getCurrentUser()) {
+ *       return false
+ *     }
+ *     return super.canPerform(entity, action)
  *   }
  * }
  * ```
- *
- * @interface
  */
 export class EntityAuthAdapter {
   /**
@@ -41,6 +35,23 @@ export class EntityAuthAdapter {
    */
   _securityChecker = null
 
+  /**
+   * Callback to get current user (alternative to subclassing)
+   * @type {Function|null}
+   * @private
+   */
+  _getCurrentUserCallback = null
+
+  /**
+   * @param {object} [options]
+   * @param {Function} [options.getCurrentUser] - Callback that returns current user or null
+   */
+  constructor(options = {}) {
+    if (options.getCurrentUser) {
+      this._getCurrentUserCallback = options.getCurrentUser
+    }
+  }
+
   /**
    * Set the SecurityChecker instance for isGranted() delegation
    *
@@ -62,7 +73,7 @@ export class EntityAuthAdapter {
    *
    * @example
    * adapter.isGranted('ROLE_ADMIN')           // Check role
-   * adapter.isGranted('entity:delete')        // Check permission
+   * adapter.isGranted('entity:books:delete')  // Check permission
    * adapter.isGranted('books:delete', book)   // Check with subject
    */
   isGranted(attribute, subject = null) {
@@ -73,8 +84,6 @@ export class EntityAuthAdapter {
   /**
    * Check if current user can assign a specific role
    *
-   * Uses SecurityChecker's canAssignRole if available.
-   *
    * @param {string} targetRole - Role to assign
    * @returns {boolean} True if user can assign this role
    */
@@ -96,50 +105,49 @@ export class EntityAuthAdapter {
   /**
    * Check if the current user can perform an action on an entity type (scope check)
    *
-   * This is the coarse-grained permission check. It determines if the user has
-   * the right to perform a category of actions, regardless of which specific
-   * record they want to act on.
+   * Default: delegates to isGranted('entity:{entity}:{action}')
+   * Override for custom authentication requirements or business rules.
    *
    * @param {string} entity - Entity name (e.g., 'users', 'invoices', 'products')
    * @param {string} action - Action to check: 'read', 'create', 'update', 'delete', 'list'
    * @returns {boolean} True if user can perform the action on this entity type
-   *
-   * @example
-   * adapter.canPerform('invoices', 'create') // true/false
-   * adapter.canPerform('users', 'delete') // true/false
    */
   canPerform(entity, action) {
-    throw new Error('[EntityAuthAdapter] canPerform() must be implemented by subclass')
+    return this.isGranted(`entity:${entity}:${action}`)
   }
 
   /**
    * Check if the current user can access a specific record (silo check)
    *
-   * This is the fine-grained permission check. After the scope check passes,
-   * this determines if the user can access a particular record based on
-   * ownership, team membership, or other business rules.
+   * Default: delegates to isGranted('entity:{entity}:read', record)
+   * Note: Ownership checks are typically handled via EntityManager's isOwn callback.
    *
    * @param {string} entity - Entity name (e.g., 'users', 'invoices')
    * @param {object} record - The full entity record to check access for
    * @returns {boolean} True if user can access this specific record
-   *
-   * @example
-   * adapter.canAccessRecord('invoices', { id: 123, owner_id: 456, ... })
    */
   canAccessRecord(entity, record) {
-    throw new Error('[EntityAuthAdapter] canAccessRecord() must be implemented by subclass')
+    return this.isGranted(`entity:${entity}:read`, record)
   }
 
   /**
    * Get the current authenticated user
    *
-   * Returns the user object or null if not authenticated. The user object
-   * should contain whatever information is needed for permission checks.
+   * Returns user from:
+   * 1. _getCurrentUserCallback if provided in constructor
+   * 2. Subclass override if using class extension pattern
+   * 3. null if neither is configured
+   *
+   * Note: SecurityChecker calls this method, so it cannot delegate back to SecurityChecker.
    *
    * @returns {object|null} Current user object or null if not authenticated
    */
   getCurrentUser() {
-    throw new Error('[EntityAuthAdapter] getCurrentUser() must be implemented by subclass')
+    if (this._getCurrentUserCallback) {
+      return this._getCurrentUserCallback()
+    }
+    // Subclasses can override this method
+    return null
   }
 }
 

package/src/entity/auth/SecurityChecker.js

@@ -1,47 +1,107 @@
 import { RoleHierarchy } from './RoleHierarchy.js'
+import { PermissionMatcher } from '../../security/PermissionMatcher.js'
+import { StaticRoleGranterAdapter } from '../../security/StaticRoleGranterAdapter.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).
+ * Supports both role checks (ROLE_*) and permission checks with wildcards.
  *
- * 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.
+ * Permission format: namespace:target:action
+ * - entity:books:read     - Entity CRUD
+ * - auth:impersonate      - System feature
+ * - admin:config:edit     - Admin feature
+ *
+ * Wildcard patterns (like signals):
+ * - `*` matches exactly one segment
+ * - `**` matches zero or more segments (greedy)
  *
  * @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'],
- *   },
+ *   roleGranter: new StaticRoleGranterAdapter({
+ *     role_hierarchy: { ROLE_ADMIN: ['ROLE_USER'] },
+ *     role_permissions: {
+ *       ROLE_USER: ['entity:*:read', 'entity:*:list'],
+ *       ROLE_ADMIN: ['entity:**', 'admin:**']
+ *     }
+ *   }),
  *   getCurrentUser: () => authStore.user
  * })
  *
- * checker.isGranted('ROLE_ADMIN')           // Check role
- * checker.isGranted('entity:delete')        // Check permission
- * checker.isGranted('books:delete', book)   // Check with subject
- * ```
+ * checker.isGranted('ROLE_ADMIN')              // Check role
+ * checker.isGranted('entity:books:read')       // Check permission
+ * checker.isGranted('entity:books:delete')     // Matches 'entity:**' for ADMIN
  */
 export class SecurityChecker {
   /**
    * @param {Object} options
-   * @param {RoleHierarchy} options.roleHierarchy - Role hierarchy instance
-   * @param {Object<string, string[]>} options.rolePermissions - Permissions per role
+   * @param {RoleGranterAdapter} [options.roleGranter] - Role granter adapter
+   * @param {RoleHierarchy} [options.roleHierarchy] - Role hierarchy (legacy, prefer roleGranter)
+   * @param {Object<string, string[]>} [options.rolePermissions] - Permissions per role (legacy)
    * @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
+  constructor({ roleGranter, roleHierarchy, rolePermissions, getCurrentUser }) {
+    // Support both new roleGranter and legacy rolePermissions
+    if (roleGranter) {
+      this._roleGranter = roleGranter
+      // Note: roleHierarchy is now a getter that reads dynamically from roleGranter
+      // This ensures hierarchy changes after async load() are reflected
+      this._legacyRoleHierarchy = null
+    } else {
+      // Legacy: create static granter from rolePermissions
+      this._roleGranter = new StaticRoleGranterAdapter({
+        role_hierarchy: roleHierarchy instanceof RoleHierarchy
+          ? {} // Can't extract map from RoleHierarchy, use empty
+          : (roleHierarchy || {}),
+        role_permissions: rolePermissions || {}
+      })
+      this._legacyRoleHierarchy = roleHierarchy instanceof RoleHierarchy
+        ? roleHierarchy
+        : new RoleHierarchy(roleHierarchy || {})
+    }
+
     this.getCurrentUser = getCurrentUser
   }
 
+  /**
+   * Get role hierarchy (dynamically resolved from roleGranter)
+   *
+   * This is a getter instead of a cached property to ensure that
+   * hierarchy changes after async load() are reflected immediately.
+   *
+   * @returns {RoleHierarchy}
+   */
+  get roleHierarchy() {
+    // Legacy mode: use cached hierarchy
+    if (this._legacyRoleHierarchy) {
+      return this._legacyRoleHierarchy
+    }
+    // Dynamic mode: create fresh RoleHierarchy from current granter state
+    return new RoleHierarchy(this._roleGranter.getHierarchy())
+  }
+
+  /**
+   * Get role granter adapter
+   * @returns {RoleGranterAdapter}
+   */
+  get roleGranter() {
+    return this._roleGranter
+  }
+
+  /**
+   * Get role permissions (for backward compatibility / debug panel)
+   * @returns {Object<string, string[]>}
+   */
+  get rolePermissions() {
+    const roles = this._roleGranter.getRoles()
+    const perms = {}
+    for (const role of roles) {
+      perms[role] = this._roleGranter.getPermissions(role)
+    }
+    return perms
+  }
+
   /**
    * Check if current user is granted an attribute (role or permission)
    *
@@ -49,16 +109,16 @@ export class SecurityChecker {
    *
    * Checking flow:
    * 1. If attribute starts with 'ROLE_' → check role hierarchy
-   * 2. Check if user has the permission (from role or direct)
+   * 2. Check if user has the permission (with wildcard support)
    *
-   * @param {string} attribute - Role (ROLE_*) or permission (entity:action)
+   * @param {string} attribute - Role (ROLE_*) or permission (namespace:target: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)
+   * checker.isGranted('ROLE_ADMIN')              // true/false
+   * checker.isGranted('entity:books:read')       // true/false
+   * checker.isGranted('entity:books:delete', book)  // true/false (with subject)
    */
   isGranted(attribute, subject = null) {
     const user = this.getCurrentUser()
@@ -72,12 +132,9 @@ export class SecurityChecker {
       )
     }
 
-    // 2. Check if it's a permission
+    // 2. Check if it's a permission (with wildcard support)
     const userPerms = this.getUserPermissions(user)
-    if (userPerms.includes('*')) return true
-    if (userPerms.includes(attribute)) return true
-
-    return false
+    return PermissionMatcher.any(userPerms, attribute)
   }
 
   /**
@@ -85,11 +142,11 @@ export class SecurityChecker {
    *
    * Resolves permissions by:
    * 1. Getting all reachable roles from role hierarchy
-   * 2. Collecting permissions from each role
+   * 2. Collecting permissions from each role via roleGranter
    * 3. Adding any user-specific permission overrides
    *
    * @param {object} user - User object with role/roles and optional permissions
-   * @returns {string[]} Array of all permissions
+   * @returns {string[]} Array of all permissions (may include wildcards)
    */
   getUserPermissions(user) {
     const roles = user.roles || [user.role]
@@ -99,7 +156,7 @@ export class SecurityChecker {
       if (!role) continue
       const reachable = this.roleHierarchy.getReachableRoles(role)
       for (const r of reachable) {
-        const rolePerms = this.rolePermissions[r] || []
+        const rolePerms = this._roleGranter.getPermissions(r)
         rolePerms.forEach(p => perms.add(p))
       }
     }
@@ -115,14 +172,14 @@ export class SecurityChecker {
   /**
    * Check if user can assign a role to another user
    *
-   * Rule: Can only assign roles if user has 'role:assign' permission
+   * Rule: Can only assign roles if user has 'security:roles: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)
+    return this.isGranted('security:roles:assign') && this.isGranted(targetRole)
   }
 
   /**
@@ -131,7 +188,7 @@ export class SecurityChecker {
    * @returns {string[]} Array of assignable role names
    */
   getAssignableRoles() {
-    if (!this.isGranted('role:assign')) return []
+    if (!this.isGranted('security:roles:assign')) return []
 
     const user = this.getCurrentUser()
     if (!user) return []
@@ -153,15 +210,26 @@ export class SecurityChecker {
  * 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 {RoleGranterAdapter} [config.roleGranter] - Role granter adapter
+ * @param {Object<string, string[]>} [config.role_hierarchy] - Role hierarchy config (legacy)
+ * @param {Object<string, string[]>} [config.role_permissions] - Permissions per role (legacy)
  * @param {Function} config.getCurrentUser - User getter function
  * @returns {SecurityChecker}
  */
 export function createSecurityChecker(config) {
+  if (config.roleGranter) {
+    return new SecurityChecker({
+      roleGranter: config.roleGranter,
+      getCurrentUser: config.getCurrentUser
+    })
+  }
+
+  // Legacy config: auto-create static granter
   return new SecurityChecker({
-    roleHierarchy: new RoleHierarchy(config.role_hierarchy || {}),
-    rolePermissions: config.role_permissions || {},
+    roleGranter: new StaticRoleGranterAdapter({
+      role_hierarchy: config.role_hierarchy || {},
+      role_permissions: config.role_permissions || {}
+    }),
     getCurrentUser: config.getCurrentUser
   })
 }

package/src/entity/auth/factory.js

@@ -105,16 +105,20 @@ function isCompositeConfig(config) {
  *
  * Handles:
  * - AuthAdapter instance → return directly (backward compatible)
+ * - Function → wrap as EntityAuthAdapter with getCurrentUser callback
  * - String pattern 'type' → parse and resolve
  * - Config object with 'type' → resolve via registry
  * - Config object with 'default' → create CompositeAuthAdapter
  *
- * @param {EntityAuthAdapter | string | object} config - Auth config
+ * @param {EntityAuthAdapter | Function | string | object} config - Auth config
  * @param {object} [context={}] - Context with authTypes, authResolver
  * @returns {EntityAuthAdapter} Adapter instance
  *
  * @example
- * // Instance passthrough (most common, backward compatible)
+ * // Function (simplest - for getCurrentUser callback)
+ * authFactory(() => authStore.user)  // → EntityAuthAdapter
+ *
+ * // Instance passthrough (backward compatible)
  * authFactory(myAdapter)  // → myAdapter
  *
  * // String patterns
@@ -138,6 +142,11 @@ export function authFactory(config, context = {}) {
     return new PermissiveAuthAdapter()
   }
 
+  // Function → wrap in EntityAuthAdapter with getCurrentUser callback
+  if (typeof config === 'function') {
+    return new EntityAuthAdapter({ getCurrentUser: config })
+  }
+
   // Already an EntityAuthAdapter instance → return directly (backward compatible)
   if (config instanceof EntityAuthAdapter) {
     return config

package/src/entity/auth/factory.test.js

@@ -82,6 +82,35 @@ describe('authFactory', () => {
     })
   })
 
+  describe('function callback', () => {
+    it('wraps function in EntityAuthAdapter with getCurrentUser', () => {
+      const user = { id: 1, name: 'Test' }
+      const result = authFactory(() => user)
+
+      expect(result).toBeInstanceOf(EntityAuthAdapter)
+      expect(result.getCurrentUser()).toBe(user)
+    })
+
+    it('function can return null', () => {
+      const result = authFactory(() => null)
+
+      expect(result).toBeInstanceOf(EntityAuthAdapter)
+      expect(result.getCurrentUser()).toBeNull()
+    })
+
+    it('function is called each time getCurrentUser is called', () => {
+      let callCount = 0
+      const result = authFactory(() => {
+        callCount++
+        return { id: callCount }
+      })
+
+      expect(result.getCurrentUser()).toEqual({ id: 1 })
+      expect(result.getCurrentUser()).toEqual({ id: 2 })
+      expect(callCount).toBe(2)
+    })
+  })
+
   describe('string patterns', () => {
     it('resolves built-in types', () => {
       const result = authFactory('permissive')

package/src/entity/storage/factory.test.js

@@ -59,7 +59,7 @@ describe('defaultStorageResolver', () => {
   it('creates LocalStorage for local type', () => {
     const storage = defaultStorageResolver({ type: 'local', key: 'myKey' }, 'items')
     expect(storage).toBeInstanceOf(LocalStorage)
-    expect(storage.storageKey).toBe('myKey')
+    expect(storage.key).toBe('myKey')
   })
 
   it('creates MemoryStorage for memory type', () => {
@@ -74,7 +74,7 @@ describe('defaultStorageResolver', () => {
 
   it('throws for unknown type', () => {
     expect(() => defaultStorageResolver({ type: 'unknown' }, 'items'))
-      .toThrow('Unknown storage type: unknown')
+      .toThrow('Unknown storage type: "unknown"')
   })
 })
 
@@ -111,9 +111,10 @@ describe('storageFactory', () => {
     expect(result).toBeInstanceOf(MemoryStorage)
   })
 
-  it('handles config object with string storage', () => {
-    const result = storageFactory({ storage: 'api:/api/items' }, 'items')
+  it('handles config object with endpoint (infers api type)', () => {
+    const result = storageFactory({ endpoint: '/api/items' }, 'items')
     expect(result).toBeInstanceOf(ApiStorage)
+    expect(result.endpoint).toBe('/api/items')
   })
 
   it('uses custom resolver when provided', () => {
@@ -133,7 +134,7 @@ describe('storageFactory', () => {
 
   it('throws for unparseable string', () => {
     expect(() => storageFactory('invalid', 'test'))
-      .toThrow('Cannot parse storage pattern')
+      .toThrow('Invalid storage pattern')
   })
 })
 

package/src/index.js

@@ -20,6 +20,9 @@ export * from './entity/index.js'
 // Session auth (user authentication)
 export * from './auth/index.js'
 
+// Security (permissions, roles)
+export * from './security/index.js'
+
 // Orchestrator
 export * from './orchestrator/index.js'