@quazardous/qdadm 1.19.3

package/src/entity/auth/RoleHierarchy.ts

@@ -0,0 +1,128 @@
+/**
+ * Role hierarchy configuration type
+ */
+export type RoleHierarchyConfig = Record<string, string[]>
+
+/**
+ * RoleHierarchy - Topological role resolution for Symfony-like permission system
+ *
+ * Roles form a Directed Acyclic Graph (DAG) where higher roles inherit
+ * permissions from lower roles. This class resolves the complete set of
+ * roles that a user effectively has based on their assigned roles.
+ *
+ * @example
+ * ```ts
+ * const hierarchy = new RoleHierarchy({
+ *   ROLE_ADMIN: ['ROLE_USER'],           // Admin inherits from User
+ *   ROLE_SUPER_ADMIN: ['ROLE_ADMIN'],    // Super admin inherits from Admin
+ *   ROLE_MANAGER: ['ROLE_USER'],         // Manager also inherits from User
+ * })
+ *
+ * hierarchy.getReachableRoles('ROLE_ADMIN')
+ * // Returns: ['ROLE_ADMIN', 'ROLE_USER']
+ * ```
+ */
+export class RoleHierarchy {
+  readonly map: RoleHierarchyConfig
+
+  constructor(hierarchy: RoleHierarchyConfig = {}) {
+    this.map = hierarchy
+  }
+
+  /**
+   * Resolve all roles reachable from a given role (topological traversal)
+   *
+   * Performs BFS traversal of the role graph to find all inherited roles.
+   * Handles cycles gracefully by tracking visited nodes.
+   */
+  getReachableRoles(role: string): string[] {
+    const visited = new Set<string>()
+    const queue: string[] = [role]
+
+    while (queue.length > 0) {
+      const current = queue.shift()!
+      if (visited.has(current)) continue
+      visited.add(current)
+
+      const parents = this.map[current] || []
+      queue.push(...parents)
+    }
+
+    return [...visited]
+  }
+
+  /**
+   * Check if user with given roles has the required role
+   *
+   * A user has a role if:
+   * 1. They are directly assigned that role, OR
+   * 2. They have a role that inherits from the required role
+   */
+  isGrantedRole(userRoles: string | string[], requiredRole: string): boolean {
+    const roles = Array.isArray(userRoles) ? userRoles : [userRoles]
+
+    for (const role of roles) {
+      const reachable = this.getReachableRoles(role)
+      if (reachable.includes(requiredRole)) return true
+    }
+
+    return false
+  }
+
+  /**
+   * Get all roles that can reach a given role (reverse lookup)
+   *
+   * Useful for finding which roles would grant a specific permission.
+   */
+  getRolesGranting(targetRole: string): string[] {
+    const grantors: string[] = []
+
+    for (const role of Object.keys(this.map)) {
+      if (this.isGrantedRole([role], targetRole)) {
+        grantors.push(role)
+      }
+    }
+
+    // Also check the target role itself
+    if (!grantors.includes(targetRole)) {
+      grantors.push(targetRole)
+    }
+
+    return grantors
+  }
+
+  /**
+   * Validate the hierarchy for cycles (optional sanity check)
+   */
+  validate(): boolean {
+    const visiting = new Set<string>()
+    const visited = new Set<string>()
+
+    const hasCycle = (role: string): boolean => {
+      if (visited.has(role)) return false
+      if (visiting.has(role)) return true
+
+      visiting.add(role)
+      const parents = this.map[role] || []
+      for (const parent of parents) {
+        if (hasCycle(parent)) return true
+      }
+      visiting.delete(role)
+      visited.add(role)
+      return false
+    }
+
+    for (const role of Object.keys(this.map)) {
+      if (hasCycle(role)) return false
+    }
+
+    return true
+  }
+}
+
+/**
+ * Create a RoleHierarchy instance from config
+ */
+export function createRoleHierarchy(config: RoleHierarchyConfig = {}): RoleHierarchy {
+  return new RoleHierarchy(config)
+}

package/src/entity/auth/SecurityChecker.ts

@@ -0,0 +1,202 @@
+import { RoleHierarchy, type RoleHierarchyConfig } from './RoleHierarchy'
+import { PermissionMatcher } from '../../security/PermissionMatcher'
+import { StaticRoleProvider } from '../../security/StaticRolesProvider'
+import type { AuthUser } from './EntityAuthAdapter'
+
+/**
+ * RolesProvider adapter interface (from security module)
+ */
+export interface RoleProvider {
+  getPermissions(role: string): string[]
+  getRoles(): string[]
+  getHierarchy(): RoleHierarchyConfig
+  getAnonymousRole(): string
+  getRoleMeta(role: string): { label?: string; description?: string } | null
+  readonly canPersist: boolean
+}
+
+/**
+ * SecurityChecker constructor options
+ */
+export interface SecurityCheckerOptions {
+  rolesProvider?: RoleProvider
+  roleHierarchy?: RoleHierarchy | RoleHierarchyConfig
+  rolePermissions?: Record<string, string[]>
+  getCurrentUser: () => AuthUser | null
+}
+
+/**
+ * SecurityChecker config for factory
+ */
+export interface SecurityCheckerConfig {
+  rolesProvider?: RoleProvider
+  role_hierarchy?: RoleHierarchyConfig
+  role_permissions?: Record<string, string[]>
+  getCurrentUser: () => AuthUser | null
+}
+
+/**
+ * SecurityChecker - Symfony-inspired permission checking
+ *
+ * Provides the `isGranted(attribute, subject?)` contract for checking permissions.
+ * Supports both role checks (ROLE_*) and permission checks with wildcards.
+ *
+ * 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)
+ */
+export class SecurityChecker {
+  protected _rolesProvider: RoleProvider
+  protected _legacyRoleHierarchy: RoleHierarchy | null
+  readonly getCurrentUser: () => AuthUser | null
+
+  constructor({ rolesProvider, roleHierarchy, rolePermissions, getCurrentUser }: SecurityCheckerOptions) {
+    // Support both new rolesProvider and legacy rolePermissions
+    if (rolesProvider) {
+      this._rolesProvider = rolesProvider
+      this._legacyRoleHierarchy = null
+    } else {
+      // Legacy: create static provider from rolePermissions
+      const hierarchyConfig =
+        roleHierarchy instanceof RoleHierarchy ? {} : (roleHierarchy as RoleHierarchyConfig) || {}
+
+      this._rolesProvider = new StaticRoleProvider({
+        role_hierarchy: hierarchyConfig,
+        role_permissions: rolePermissions || {},
+      })
+
+      this._legacyRoleHierarchy =
+        roleHierarchy instanceof RoleHierarchy
+          ? roleHierarchy
+          : new RoleHierarchy(hierarchyConfig)
+    }
+
+    this.getCurrentUser = getCurrentUser
+  }
+
+  /**
+   * Get role hierarchy (dynamically resolved from rolesProvider)
+   */
+  get roleHierarchy(): RoleHierarchy {
+    if (this._legacyRoleHierarchy) {
+      return this._legacyRoleHierarchy
+    }
+    return new RoleHierarchy(this._rolesProvider.getHierarchy())
+  }
+
+  /**
+   * Get roles provider adapter
+   */
+  get rolesProvider(): RoleProvider {
+    return this._rolesProvider
+  }
+
+  /**
+   * Get role permissions (for backward compatibility / debug panel)
+   */
+  get rolePermissions(): Record<string, string[]> {
+    const roles = this._rolesProvider.getRoles()
+    const perms: Record<string, string[]> = {}
+    for (const role of roles) {
+      perms[role] = this._rolesProvider.getPermissions(role)
+    }
+    return perms
+  }
+
+  /**
+   * Check if current user is granted an attribute (role or permission)
+   *
+   * This is the main contract method, similar to Symfony's isGranted().
+   */
+  isGranted(attribute: string, _subject: unknown = null): boolean {
+    const user = this.getCurrentUser()
+    if (!user) return false
+
+    // 1. Check if it's a role (ROLE_*)
+    if (attribute.startsWith('ROLE_')) {
+      return this.roleHierarchy.isGrantedRole(user.roles || [user.role || ''], attribute)
+    }
+
+    // 2. Check if it's a permission (with wildcard support)
+    const userPerms = this.getUserPermissions(user)
+    return PermissionMatcher.any(userPerms, attribute)
+  }
+
+  /**
+   * Get all permissions for a user (resolved from roles + user overrides)
+   */
+  getUserPermissions(user: AuthUser): string[] {
+    const roles = user.roles || [user.role || '']
+    const perms = new Set<string>()
+
+    for (const role of roles) {
+      if (!role) continue
+      const reachable = this.roleHierarchy.getReachableRoles(role)
+      for (const r of reachable) {
+        const rolePerms = this._rolesProvider.getPermissions(r)
+        rolePerms.forEach((p) => perms.add(p))
+      }
+    }
+
+    // User-specific permission overrides
+    if (user.permissions && Array.isArray(user.permissions)) {
+      user.permissions.forEach((p) => perms.add(p))
+    }
+
+    return [...perms]
+  }
+
+  /**
+   * Check if user can assign a role to another user
+   */
+  canAssignRole(targetRole: string): boolean {
+    return this.isGranted('security:roles:assign') && this.isGranted(targetRole)
+  }
+
+  /**
+   * Get all roles that current user can assign
+   */
+  getAssignableRoles(): string[] {
+    if (!this.isGranted('security:roles:assign')) return []
+
+    const user = this.getCurrentUser()
+    if (!user) return []
+
+    const userRoles = user.roles || [user.role || '']
+    const assignable = new Set<string>()
+
+    for (const role of userRoles) {
+      if (!role) continue
+      const reachable = this.roleHierarchy.getReachableRoles(role)
+      reachable.forEach((r) => assignable.add(r))
+    }
+
+    return [...assignable]
+  }
+}
+
+/**
+ * Create a SecurityChecker instance from config
+ */
+export function createSecurityChecker(config: SecurityCheckerConfig): SecurityChecker {
+  if (config.rolesProvider) {
+    return new SecurityChecker({
+      rolesProvider: config.rolesProvider,
+      getCurrentUser: config.getCurrentUser,
+    })
+  }
+
+  // Legacy config: auto-create static provider
+  return new SecurityChecker({
+    rolesProvider: new StaticRoleProvider({
+      role_hierarchy: config.role_hierarchy || {},
+      role_permissions: config.role_permissions || {},
+    }),
+    getCurrentUser: config.getCurrentUser,
+  })
+}

package/src/entity/auth/factory.ts

@@ -0,0 +1,203 @@
+/**
+ * Auth Factory/Resolver Pattern
+ *
+ * Enables declarative auth adapter configuration with auto-resolution.
+ * Follows the same pattern as storage/factory.js for consistency.
+ */
+
+import { EntityAuthAdapter, type EntityAuthAdapterOptions, type AuthUser } from './EntityAuthAdapter'
+import { PermissiveAuthAdapter } from './PermissiveAdapter'
+import type { CompositeAuthAdapter, CompositeAuthConfig } from './CompositeAuthAdapter'
+
+/**
+ * Auth adapter class type
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AuthAdapterClass = new (options?: any) => EntityAuthAdapter
+
+/**
+ * Built-in auth adapter types
+ */
+export const authTypes: Record<string, AuthAdapterClass> = {
+  permissive: PermissiveAuthAdapter,
+}
+
+/**
+ * Parsed auth pattern
+ */
+export interface ParsedAuthPattern {
+  type: string
+  scope?: string
+  [key: string]: unknown
+}
+
+/**
+ * Auth config object
+ */
+export interface AuthConfig {
+  type?: string
+  [key: string]: unknown
+}
+
+/**
+ * Auth factory context
+ */
+export interface AuthFactoryContext {
+  authTypes?: Record<string, AuthAdapterClass>
+  authResolver?: AuthResolver
+  CompositeAuthAdapter?: new (config: CompositeAuthConfig, context: AuthFactoryContext) => CompositeAuthAdapter
+}
+
+/**
+ * Auth resolver function type
+ */
+export type AuthResolver = (config: AuthConfig, context: AuthFactoryContext) => EntityAuthAdapter
+
+/**
+ * Parse auth pattern 'type' or 'type:scope'
+ */
+export function parseAuthPattern(pattern: string): ParsedAuthPattern | null {
+  if (typeof pattern !== 'string') return null
+
+  const match = pattern.match(/^(\w+)(?::(.+))?$/)
+  if (match && match[1]) {
+    const type = match[1]
+    const scope = match[2]
+    return scope ? { type, scope } : { type }
+  }
+  return null
+}
+
+/**
+ * Default auth resolver - creates adapter instance from config
+ */
+export function defaultAuthResolver(config: AuthConfig, context: AuthFactoryContext = {}): EntityAuthAdapter {
+  const { type, ...rest } = config
+
+  if (!type) {
+    throw new Error('[authFactory] Config object requires "type" property')
+  }
+
+  // Merge built-in types with custom types from context
+  const allTypes = { ...authTypes, ...context.authTypes }
+  const AdapterClass = allTypes[type]
+
+  if (!AdapterClass) {
+    throw new Error(
+      `[authFactory] Unknown auth type: "${type}". ` +
+        `Available: ${Object.keys(allTypes).join(', ')}`
+    )
+  }
+
+  return new AdapterClass(rest)
+}
+
+/**
+ * Check if config is a composite auth config
+ */
+function isCompositeConfig(config: unknown): config is CompositeAuthConfig {
+  return (
+    config !== null &&
+    typeof config === 'object' &&
+    'default' in config &&
+    !('type' in config)
+  )
+}
+
+/**
+ * Auth factory input types
+ */
+export type AuthFactoryInput =
+  | EntityAuthAdapter
+  | ((options?: EntityAuthAdapterOptions) => AuthUser | null)
+  | string
+  | CompositeAuthConfig
+  | AuthConfig
+  | null
+  | undefined
+
+/**
+ * Auth factory - normalizes input and resolves to adapter
+ *
+ * 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
+ */
+export function authFactory(
+  config: AuthFactoryInput,
+  context: AuthFactoryContext = {}
+): EntityAuthAdapter {
+  const { authResolver = defaultAuthResolver } = context
+
+  // Null/undefined → permissive (safe default)
+  if (config == null) {
+    return new PermissiveAuthAdapter()
+  }
+
+  // Function → wrap in EntityAuthAdapter with getCurrentUser callback
+  if (typeof config === 'function') {
+    return new EntityAuthAdapter({ getCurrentUser: config as () => AuthUser | null })
+  }
+
+  // Already an EntityAuthAdapter instance → return directly (backward compatible)
+  if (config instanceof EntityAuthAdapter) {
+    return config
+  }
+
+  // Duck-typed adapter (has canPerform method)
+  if (
+    typeof config === 'object' &&
+    'canPerform' in config &&
+    typeof config.canPerform === 'function'
+  ) {
+    return config as unknown as EntityAuthAdapter
+  }
+
+  // String pattern → parse and resolve
+  if (typeof config === 'string') {
+    const parsed = parseAuthPattern(config)
+    if (!parsed) {
+      throw new Error(`[authFactory] Invalid auth pattern: "${config}"`)
+    }
+    return authResolver(parsed, context)
+  }
+
+  // Config object
+  if (typeof config === 'object') {
+    // Composite config: { default: ..., mapping: { ... } }
+    if (isCompositeConfig(config)) {
+      const CompositeClass = context.authTypes?.composite || context.CompositeAuthAdapter
+      if (!CompositeClass) {
+        throw new Error(
+          '[authFactory] Composite config requires CompositeAuthAdapter. ' +
+            'Pass it via context.CompositeAuthAdapter or register as context.authTypes.composite'
+        )
+      }
+      return new CompositeClass(config, context)
+    }
+
+    // Simple config with type: { type: 'jwt', ... }
+    if ('type' in config && config.type) {
+      return authResolver(config as AuthConfig, context)
+    }
+
+    throw new Error('[authFactory] Config object requires either "type" or "default" property')
+  }
+
+  throw new Error(
+    `[authFactory] Invalid auth config: ${typeof config}. ` +
+      'Expected AuthAdapter instance, string, or config object.'
+  )
+}
+
+/**
+ * Create a custom auth factory with bound context
+ */
+export function createAuthFactory(
+  context: AuthFactoryContext
+): (config: AuthFactoryInput) => EntityAuthAdapter {
+  return (config) => authFactory(config, context)
+}

package/src/entity/auth/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Auth Module
+ *
+ * AuthAdapter interface and implementations for scope/silo permission checks.
+ * Includes Symfony-inspired role hierarchy and security checker.
+ *
+ * Multi-source auth:
+ * - CompositeAuthAdapter routes to different adapters based on entity patterns
+ * - authFactory normalizes config (instance, string, or object)
+ */
+
+// Interface
+export { EntityAuthAdapter, AuthActions } from './EntityAuthAdapter'
+export type { AuthUser, EntityAuthAdapterOptions, AuthAction } from './EntityAuthAdapter'
+
+// Role Hierarchy (topological resolution)
+export { RoleHierarchy, createRoleHierarchy } from './RoleHierarchy'
+export type { RoleHierarchyConfig } from './RoleHierarchy'
+
+// Security Checker (isGranted contract)
+export { SecurityChecker, createSecurityChecker } from './SecurityChecker'
+export type {
+  RoleProvider,
+  SecurityCheckerOptions,
+  SecurityCheckerConfig,
+} from './SecurityChecker'
+
+// Implementations
+export { PermissiveAuthAdapter, createPermissiveAdapter } from './PermissiveAdapter'
+export { CompositeAuthAdapter, createCompositeAuthAdapter } from './CompositeAuthAdapter'
+export type { CompositeAuthConfig } from './CompositeAuthAdapter'
+
+// Factory/Resolver pattern (like storage/factory.ts)
+export {
+  authFactory,
+  createAuthFactory,
+  authTypes,
+  parseAuthPattern,
+  defaultAuthResolver,
+} from './factory'
+export type {
+  ParsedAuthPattern,
+  AuthConfig,
+  AuthFactoryContext,
+  AuthResolver,
+  AuthFactoryInput,
+} from './factory'