@jmruthers/pace-core 0.5.193 → 0.6.2

package/src/rbac/hooks/usePermissions.ts

@@ -1,996 +1,15 @@
 /**
- * @file RBAC Permission Hooks
- * @package @jmruthers/pace-core
- * @module RBAC/Hooks
- * @since 1.0.0
- * 
- * This module provides React hooks for RBAC functionality.
- */
-
-import React, { useState, useEffect, useCallback, useMemo, useRef } from 'react';
-import { 
-  UUID, 
-  Scope, 
-  Permission, 
-  PermissionMap,
-  OrganisationContextRequiredError
-} from '../types';
-import { AccessLevel as AccessLevelType } from '../types';
-import { 
-  getAccessLevel, 
-  getPermissionMap, 
-  isPermitted,
-  isPermittedCached 
-} from '../api';
-import { getRBACLogger } from '../config';
-import { scopeEqual } from '../utils/deep-equal';
-import { useAppConfig } from '../../hooks/useAppConfig';
-
-/**
- * Hook to get user's permissions in a scope
- * 
- * @param userId - User ID
- * @param organisationId - Organisation ID
- * @param eventId - Event ID (optional)
- * @param appId - Application ID (optional)
- * @returns Permission state and methods
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { permissions, isLoading, error } = usePermissions(
- *     userId, 
- *     organisationId, 
- *     eventId, 
- *     appId
- *   );
- *   
- *   if (isLoading) return <div>Loading...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *   
- *   return (
- *     <div>
- *       {permissions['read:users'] && <UserList />}
- *       {permissions['create:users'] && <CreateUserButton />}
- *     </div>
- *   );
- * }
- * ```
- */
-export function usePermissions(
-  userId: UUID, 
-  organisationId: string | undefined, 
-  eventId: string | undefined, 
-  appId: string | undefined
-) {
-  const [permissions, setPermissions] = useState<PermissionMap>({} as PermissionMap);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchTrigger, setFetchTrigger] = useState(0);
-  const isFetchingRef = useRef(false);
-  const logger = getRBACLogger();
-  
-  // Track previous values to detect changes imperatively
-  const prevValuesRef = useRef({ userId, organisationId, eventId, appId });
-  
-  // Normalize organisationId to empty string if undefined
-  const orgId = organisationId || '';
-  
-  // Removed excessive logging - only log when scope actually changes (not on every render)
-
-  // Add timeout for missing organisation context (3 seconds)
-  // OPTIMIZATION: Skip timeout if userId is null/undefined (indicates pre-filtered mode)
-  useEffect(() => {
-    // If userId is null/undefined, skip the timeout - this indicates items are pre-filtered
-    // and we don't need to wait for organisation context
-    if (!userId) {
-      return; // Skip timeout when userId is null (pre-filtered mode)
-    }
-    
-    if (!orgId || orgId === null || (typeof orgId === 'string' && orgId.trim() === '')) {
-      const timeoutId = setTimeout(() => {
-        setError(new Error('Organisation context is required for permission checks'));
-        setIsLoading(false);
-      }, 3000); // 3 seconds - typical permission check is < 1 second
-      
-      return () => clearTimeout(timeoutId);
-    }
-    // Clear error if organisation context becomes available
-    if (error?.message === 'Organisation context is required for permission checks') {
-      setError(null);
-    }
-  }, [userId, organisationId, error, orgId]);
-
-  // CRITICAL: Detect parameter changes and trigger fetch
-  // Moved to useEffect to prevent render-time state updates that could cause render loops
-  useEffect(() => {
-    const paramsChanged = 
-      prevValuesRef.current.userId !== userId ||
-      prevValuesRef.current.organisationId !== organisationId ||
-      prevValuesRef.current.eventId !== eventId ||
-      prevValuesRef.current.appId !== appId;
-    
-    if (paramsChanged) {
-      // Only log significant changes (appId changes are most important)
-      if (prevValuesRef.current.appId !== appId) {
-        // AppId changed - triggering fetch
-      }
-      prevValuesRef.current = { userId, organisationId, eventId, appId };
-      // Increment counter to force fetch useEffect to run
-      setFetchTrigger(prev => prev + 1);
-    }
-  }, [userId, organisationId, eventId, appId, logger]);
-
-  useEffect(() => {
-    const fetchPermissions = async () => {
-      // Prevent multiple simultaneous fetches
-      if (isFetchingRef.current) {
-        return;
-      }
-
-      if (!userId) {
-        setPermissions({} as PermissionMap);
-        setIsLoading(false);
-        return;
-      }
-
-      // Don't fetch permissions if scope is invalid (e.g., organisationId is null/empty)
-      // Wait for organisation context to resolve
-      // IMPORTANT: Don't clear existing permissions here - keep them until we have new ones
-      // OPTIMIZATION: If userId is null/undefined, immediately set loading to false
-      // This indicates pre-filtered mode where we don't need to wait for organisation context
-      if (!userId) {
-        setPermissions({} as PermissionMap);
-        setIsLoading(false);
-        return;
-      }
-      
-      if (!orgId || orgId === null || (typeof orgId === 'string' && orgId.trim() === '')) {
-        // Keep existing permissions, just mark as loading
-        setIsLoading(true);
-        setError(null);
-        return;
-      }
-
-      try {
-        isFetchingRef.current = true;
-        setIsLoading(true);
-        setError(null);
-        
-        // Build scope object for API call
-        const scope: Scope = {
-          organisationId: orgId,
-          eventId: eventId,
-          appId: appId
-        };
-        
-        // Fetch new permissions - don't clear old ones until we have new ones
-        const permissionMap = await getPermissionMap({ userId, scope });
-        
-        // Only log if there's a significant change or error
-        const permissionCount = Object.keys(permissionMap).length;
-        if (permissionCount === 0 && Object.keys(permissions).length > 0) {
-          logger.warn('[usePermissions] Permissions fetched but returned empty map', {
-            scope: { organisationId: orgId, eventId, appId }
-          });
-        }
-        
-        // Only update permissions if fetch was successful
-        setPermissions(permissionMap);
-      } catch (err) {
-        // On error, keep existing permissions but set error state
-        // This prevents the UI from losing all items when there's a transient error
-        logger.error('[usePermissions] Failed to fetch permissions:', err);
-        setError(err instanceof Error ? err : new Error('Failed to fetch permissions'));
-        // Don't clear permissions on error - keep what we had
-      } finally {
-        setIsLoading(false);
-        isFetchingRef.current = false;
-      }
-    };
-
-    fetchPermissions();
-  }, [fetchTrigger, userId, organisationId, eventId, appId]);
-
-  const hasPermission = useCallback((permission: Permission): boolean => {
-    if (permissions['*']) {
-      return true;
-    }
-    return permissions[permission] === true;
-  }, [permissions]);
-
-  const hasAnyPermission = useCallback((permissionList: Permission[]): boolean => {
-    if (permissions['*']) {
-      return true;
-    }
-    return permissionList.some(p => permissions[p] === true);
-  }, [permissions]);
-
-  const hasAllPermissions = useCallback((permissionList: Permission[]): boolean => {
-    if (permissions['*']) {
-      return true;
-    }
-    return permissionList.every(p => permissions[p] === true);
-  }, [permissions]);
-
-  const refetch = useCallback(async () => {
-    // Prevent multiple simultaneous fetches
-    if (isFetchingRef.current) {
-      return;
-    }
-
-    if (!userId) {
-      setPermissions({} as PermissionMap);
-      setIsLoading(false);
-      return;
-    }
-
-    // Don't fetch permissions if scope is invalid (e.g., organisationId is null/empty)
-    // IMPORTANT: Don't clear existing permissions - keep them until we have new ones
-    if (!orgId || orgId === null || (typeof orgId === 'string' && orgId.trim() === '')) {
-      // Keep existing permissions, just mark as loading
-      setIsLoading(true);
-      setError(null);
-      return;
-    }
-
-    try {
-      isFetchingRef.current = true;
-      setIsLoading(true);
-      setError(null);
-      
-      // Build scope object for API call
-      const scope: Scope = {
-        organisationId: orgId,
-        eventId: eventId,
-        appId: appId
-      };
-      
-      // Fetch new permissions - don't clear old ones until we have new ones
-      const permissionMap = await getPermissionMap({ userId, scope });
-      
-      // Only update permissions if fetch was successful
-      setPermissions(permissionMap);
-    } catch (err) {
-      // On error, keep existing permissions but set error state
-      // This prevents the UI from losing all items when there's a transient error
-      const logger = getRBACLogger();
-      logger.error('Failed to refetch permissions:', err);
-      setError(err instanceof Error ? err : new Error('Failed to fetch permissions'));
-      // Don't clear permissions on error - keep what we had
-    } finally {
-      setIsLoading(false);
-      isFetchingRef.current = false;
-    }
-  }, [userId, organisationId, eventId, appId]);
-
-  // Memoize the return object to prevent unnecessary re-renders
-  return useMemo(() => ({
-    permissions,
-    isLoading,
-    error,
-    hasPermission,
-    hasAnyPermission,
-    hasAllPermissions,
-    refetch
-  }), [permissions, isLoading, error, hasPermission, hasAnyPermission, hasAllPermissions, refetch]);
-}
-
-/**
- * Hook to check if user can perform an action
- * 
- * @param userId - User ID
- * @param scope - Scope for permission checking
- * @param permission - Permission to check
- * @param pageId - Optional page ID
- * @param useCache - Whether to use cached results
- * @param appName - Optional app name (for PORTAL/ADMIN special case)
- * @returns Permission check state and methods
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { can, isLoading, error } = useCan(userId, scope, 'read:users');
- *   
- *   if (isLoading) return <div>Checking permission...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *   
- *   return can ? <UserList /> : <div>Access denied</div>;
- * }
- * ```
- */
-export function useCan(
-  userId: UUID, 
-  scope: Scope, 
-  permission: Permission, 
-  pageId?: UUID,
-  useCache: boolean = true,
-  appName?: string
-) {
-  const [can, setCan] = useState<boolean>(false);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [isSuperAdmin, setIsSuperAdmin] = useState<boolean | null>(null);
-
-  // Validate scope parameter - handle undefined/null scope gracefully
-  const isValidScope = scope && typeof scope === 'object';
-  const organisationId = isValidScope ? scope.organisationId : undefined;
-  const eventId = isValidScope ? scope.eventId : undefined;
-  const appId = isValidScope ? scope.appId : undefined;
-
-  // Check super-admin status - super admins bypass organisation context requirements
-  useEffect(() => {
-    if (!userId) {
-      setIsSuperAdmin(false);
-      return;
-    }
-
-    let cancelled = false;
-    const checkSuperAdmin = async () => {
-      try {
-        const { isSuperAdmin: checkSuperAdmin } = await import('../api');
-        const isSuper = await checkSuperAdmin(userId);
-        if (!cancelled) {
-          setIsSuperAdmin(isSuper);
-        }
-      } catch (err) {
-        if (!cancelled) {
-          setIsSuperAdmin(false);
-        }
-      }
-    };
-
-    checkSuperAdmin();
-    return () => {
-      cancelled = true;
-    };
-  }, [userId]);
-
-  // Add timeout for missing organisation context (3 seconds)
-  // Only apply timeout for resource-level permissions, not page-level (which can handle null orgs)
-  // Super admins bypass this check
-  useEffect(() => {
-    const isPagePermission = permission.includes(':page.') || !!pageId;
-    const requiresOrgId = !isPagePermission;
-    
-    // Don't block if user is super-admin (they bypass context requirements)
-    if (isSuperAdmin === true) {
-      return;
-    }
-    
-    if (requiresOrgId && (!isValidScope || !organisationId || organisationId === null || (typeof organisationId === 'string' && organisationId.trim() === ''))) {
-      const timeoutId = setTimeout(() => {
-        setError(new Error('Organisation context is required for permission checks'));
-        setIsLoading(false);
-        setCan(false);
-      }, 3000); // 3 seconds - typical permission check is < 1 second
-      
-      return () => clearTimeout(timeoutId);
-    }
-    // Clear error if organisation context becomes available
-    if (error?.message === 'Organisation context is required for permission checks') {
-      setError(null);
-    }
-  }, [isValidScope, organisationId, error, permission, pageId, isSuperAdmin]);
-
-  // Use refs to track the last values to prevent unnecessary re-runs
-  const lastUserIdRef = useRef<UUID | null>(null);
-  const lastScopeRef = useRef<string | null>(null);
-  const lastPermissionRef = useRef<Permission | null>(null);
-  const lastPageIdRef = useRef<UUID | undefined | null>(null);
-  const lastUseCacheRef = useRef<boolean | null>(null);
-
-  // Create a stable scope object for comparison
-  const stableScope = useMemo(() => {
-    if (!isValidScope) {
-      return null;
-    }
-    return {
-      organisationId,
-      eventId,
-      appId,
-    };
-  }, [isValidScope, organisationId, eventId, appId]);
-
-  // Track previous scope for deep equality comparison
-  const prevScopeRef = useRef<Scope | null>(null);
-
-  useEffect(() => {
-    // Use deep equality check for scope to prevent unnecessary re-runs
-    const scopeChanged = !scopeEqual(prevScopeRef.current, stableScope);
-    
-    // Only run if something has actually changed
-    if (
-      lastUserIdRef.current !== userId ||
-      scopeChanged ||
-      lastPermissionRef.current !== permission ||
-      lastPageIdRef.current !== pageId ||
-      lastUseCacheRef.current !== useCache
-    ) {
-      lastUserIdRef.current = userId;
-      prevScopeRef.current = stableScope;
-      lastPermissionRef.current = permission;
-      lastPageIdRef.current = pageId;
-      lastUseCacheRef.current = useCache;
-      
-      // Inline the permission check logic to avoid useCallback dependency issues
-      const checkPermission = async () => {
-        if (!userId) {
-          setCan(false);
-          setIsLoading(false);
-          return;
-        }
-
-        // Validate scope before accessing properties
-        if (!isValidScope) {
-          setIsLoading(true);
-          setCan(false);
-          setError(null);
-          // Timeout is handled in separate useEffect
-          return;
-        }
-
-        // For page-level permissions, allow undefined/null organisationId (database function handles it)
-        // For resource-level permissions, organisationId is required
-        const isPagePermission = permission.includes(':page.') || !!pageId;
-        const requiresOrgId = !isPagePermission;
-        
-        // Check if pageId is a pageName (not a UUID) - if so, we need appId to resolve it
-        const isPageName = pageId && typeof pageId === 'string' && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(pageId);
-        const needsAppIdForPageName = isPagePermission && isPageName;
-        
-        // Don't check permissions if scope is invalid and orgId is required
-        // Wait for organisation context to resolve (unless it's a page permission that can handle null orgs)
-        // Super admins bypass this check - only proceed if super-admin status is confirmed to be true
-        // If super-admin status is still being checked (null), wait for it to complete
-        if (requiresOrgId && (!organisationId || organisationId === null || (typeof organisationId === 'string' && organisationId.trim() === ''))) {
-          // Only proceed if user is confirmed to be super-admin
-          if (isSuperAdmin === true) {
-            // Super-admin bypass - allow check to proceed (isPermitted will handle super-admin bypass)
-          } else {
-            // Not super-admin or still checking - wait for org context or super-admin check to complete
-            setIsLoading(true);
-            setCan(false);
-            setError(null);
-            // Timeout is handled in separate useEffect (Phase 1.4)
-            return;
-          }
-        }
-        
-        // For page-level permissions with pageName (not UUID), we need appId to resolve the pageName to pageId
-        // Wait for appId to be available before checking permissions
-        if (needsAppIdForPageName && (!appId || appId === null || (typeof appId === 'string' && appId.trim() === ''))) {
-          setIsLoading(true);
-          setCan(false);
-          setError(null);
-          // Will re-run when appId becomes available (via scope change detection)
-          return;
-        }
-
-        try {
-          setIsLoading(true);
-          setError(null);
-          
-          // Create a valid scope object for the API call
-          // For page-level permissions, organisationId can be undefined (database handles it)
-          const validScope: Scope = {
-            ...(organisationId ? { organisationId } : {}),
-            ...(eventId ? { eventId } : {}),
-            ...(appId ? { appId } : {})
-          };
-          
-          const result = useCache 
-            ? await isPermittedCached({ userId, scope: validScope, permission, pageId }, undefined, appName)
-            : await isPermitted({ userId, scope: validScope, permission, pageId }, undefined, appName);
-          
-          setCan(result);
-        } catch (err) {
-          const logger = getRBACLogger();
-          logger.error('Permission check error:', { permission, error: err });
-          setError(err instanceof Error ? err : new Error('Failed to check permission'));
-          setCan(false);
-        } finally {
-          setIsLoading(false);
-        }
-      };
-      
-      checkPermission();
-    }
-  }, [userId, stableScope, permission, pageId, useCache, appName, isSuperAdmin]);
-
-  const refetch = useCallback(async () => {
-    if (!userId) {
-      setCan(false);
-      setIsLoading(false);
-      return;
-    }
-
-    // Validate scope before accessing properties
-    if (!isValidScope) {
-      setCan(false);
-      setIsLoading(true);
-      setError(null);
-      return;
-    }
-
-    // For page-level permissions, allow undefined/null organisationId (database function handles it)
-    // For resource-level permissions, organisationId is required
-    const isPagePermission = permission.includes(':page.') || !!pageId;
-    const requiresOrgId = !isPagePermission;
-    
-    // Don't check permissions if scope is invalid and orgId is required
-    if (requiresOrgId && (!organisationId || organisationId === null || (typeof organisationId === 'string' && organisationId.trim() === ''))) {
-      setCan(false);
-      setIsLoading(true);
-      setError(null);
-      return;
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      // Create a valid scope object for the API call
-      // For page-level permissions, organisationId can be undefined (database handles it)
-      const validScope: Scope = {
-        ...(organisationId ? { organisationId } : {}),
-        ...(eventId ? { eventId } : {}),
-        ...(appId ? { appId } : {})
-      };
-      
-      const result = useCache 
-        ? await isPermittedCached({ userId, scope: validScope, permission, pageId }, undefined, appName)
-        : await isPermitted({ userId, scope: validScope, permission, pageId }, undefined, appName);
-      
-      setCan(result);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error('Failed to check permission'));
-      setCan(false);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, isValidScope, organisationId, eventId, appId, permission, pageId, useCache, appName]);
-
-  // Memoize the return object to prevent unnecessary re-renders
-  return useMemo(() => ({
-    can,
-    isLoading,
-    error,
-    refetch
-  }), [can, isLoading, error, refetch]);
-}
-
-/**
- * Hook to get user's access level in a scope
- * 
- * @param userId - User ID
- * @param scope - Scope for access level checking
- * @returns Access level state and methods
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { accessLevel, isLoading, error } = useAccessLevel(userId, scope);
- *   
- *   if (isLoading) return <div>Loading access level...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *   
- *   return (
- *     <div>
- *       Access Level: {accessLevel}
- *       {accessLevel >= AccessLevel.ADMIN && <AdminPanel />}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useAccessLevel(userId: UUID, scope: Scope): {
-  accessLevel: AccessLevelType;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-} {
-  const [accessLevel, setAccessLevel] = useState<AccessLevelType>('viewer');
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  // Get appName from context if available (safely handles missing context)
-  let appName: string | undefined;
-  try {
-    const { appName: contextAppName } = useAppConfig();
-    appName = contextAppName;
-  } catch {
-    // Not available, will use undefined
-  }
-
-  const fetchAccessLevel = useCallback(async () => {
-    if (!userId) {
-      setAccessLevel('viewer');
-      setIsLoading(false);
-      return;
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      // Check super admin status first - super admins bypass context requirements
-      // This allows super admins to check their access level without organisation context
-      const { isSuperAdmin: checkSuperAdmin } = await import('../api');
-      const isSuperAdminUser = await checkSuperAdmin(userId);
-      
-      if (isSuperAdminUser) {
-        setAccessLevel('super');
-        setIsLoading(false);
-        return;
-      }
-
-      // Early validation: check if scope has required context
-      // PORTAL/ADMIN apps allow both contexts to be optional
-      if (appName !== 'PORTAL' && appName !== 'ADMIN' && !scope.organisationId && !scope.eventId) {
-        const orgError = new OrganisationContextRequiredError();
-        setError(orgError);
-        setAccessLevel('viewer');
-        setIsLoading(false);
-        return;
-      }
-      
-      const level = await getAccessLevel({ userId, scope }, null, appName);
-      setAccessLevel(level);
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error('Failed to fetch access level');
-      setError(error);
-      setAccessLevel('viewer');
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, scope.organisationId, scope.eventId, scope.appId, appName]);
-
-  useEffect(() => {
-    fetchAccessLevel();
-  }, [fetchAccessLevel]);
-
-  // Memoize the return object to prevent unnecessary re-renders
-  return useMemo(() => ({
-    accessLevel,
-    isLoading,
-    error,
-    refetch: fetchAccessLevel
-  }), [accessLevel, isLoading, error, fetchAccessLevel]);
-}
-
-/**
- * Hook to check multiple permissions at once
- * 
- * @param userId - User ID
- * @param scope - Scope for permission checking
- * @param permissions - Array of permissions to check
- * @param useCache - Whether to use cached results
- * @returns Multiple permission check results
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { results, isLoading, error } = useMultiplePermissions(
- *     userId, 
- *     scope, 
- *     ['read:users', 'create:users', 'update:users']
- *   );
- *   
- *   if (isLoading) return <div>Checking permissions...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *   
- *   return (
- *     <div>
- *       {results['read:users'] && <UserList />}
- *       {results['create:users'] && <CreateUserButton />}
- *       {results['update:users'] && <EditUserButton />}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useMultiplePermissions(
-  userId: UUID, 
-  scope: Scope, 
-  permissions: Permission[],
-  useCache: boolean = true
-): {
-  results: Record<Permission, boolean>;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-} {
-  const [results, setResults] = useState<Record<Permission, boolean>>({} as Record<Permission, boolean>);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const checkPermissions = useCallback(async () => {
-    if (!userId || permissions.length === 0) {
-      setResults({} as Record<Permission, boolean>);
-      setIsLoading(false);
-      return;
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      const permissionResults: Record<Permission, boolean> = {} as Record<Permission, boolean>;
-      
-      // Check each permission
-      for (const permission of permissions) {
-        const result = useCache 
-          ? await isPermittedCached({ userId, scope, permission })
-          : await isPermitted({ userId, scope, permission });
-        permissionResults[permission] = result;
-      }
-      
-      setResults(permissionResults);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error('Failed to check permissions'));
-      setResults({} as Record<Permission, boolean>);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, scope.organisationId, scope.eventId, scope.appId, permissions, useCache]);
-
-  useEffect(() => {
-    checkPermissions();
-  }, [checkPermissions]);
-
-  // Memoize the return object to prevent unnecessary re-renders
-  return useMemo(() => ({
-    results,
-    isLoading,
-    error,
-    refetch: checkPermissions
-  }), [results, isLoading, error, checkPermissions]);
-}
-
-/**
- * Hook to check if user has any of the specified permissions
- * 
- * @param userId - User ID
- * @param scope - Scope for permission checking
- * @param permissions - Array of permissions to check
- * @param useCache - Whether to use cached results
- * @returns Whether user has any of the permissions
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { hasAny, isLoading, error } = useHasAnyPermission(
- *     userId, 
- *     scope, 
- *     ['read:users', 'create:users']
- *   );
- *   
- *   if (isLoading) return <div>Checking permissions...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *   
- *   return hasAny ? <UserManagementPanel /> : <div>No user permissions</div>;
- * }
- * ```
- */
-export function useHasAnyPermission(
-  userId: UUID, 
-  scope: Scope, 
-  permissions: Permission[],
-  useCache: boolean = true
-): {
-  hasAny: boolean;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-} {
-  const [hasAny, setHasAny] = useState<boolean>(false);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const checkAnyPermission = useCallback(async () => {
-    if (!userId || permissions.length === 0) {
-      setHasAny(false);
-      setIsLoading(false);
-      return;
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      let hasAnyPermission = false;
-      
-      for (const permission of permissions) {
-        const result = useCache 
-          ? await isPermittedCached({ userId, scope, permission })
-          : await isPermitted({ userId, scope, permission });
-        
-        if (result) {
-          hasAnyPermission = true;
-          break;
-        }
-      }
-      
-      setHasAny(hasAnyPermission);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error('Failed to check permissions'));
-      setHasAny(false);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, scope.organisationId, scope.eventId, scope.appId, permissions, useCache]);
-
-  useEffect(() => {
-    checkAnyPermission();
-  }, [checkAnyPermission]);
-
-  // Memoize the return object to prevent unnecessary re-renders
-  return useMemo(() => ({
-    hasAny,
-    isLoading,
-    error,
-    refetch: checkAnyPermission
-  }), [hasAny, isLoading, error, checkAnyPermission]);
-}
-
-/**
- * Hook to check if user has all of the specified permissions
- * 
- * @param userId - User ID
- * @param scope - Scope for permission checking
- * @param permissions - Array of permissions to check
- * @param useCache - Whether to use cached results
- * @returns Whether user has all of the permissions
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { hasAll, isLoading, error } = useHasAllPermissions(
- *     userId, 
- *     scope, 
- *     ['read:users', 'create:users', 'update:users']
- *   );
- *   
- *   if (isLoading) return <div>Checking permissions...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *   
- *   return hasAll ? <FullUserManagementPanel /> : <div>Insufficient permissions</div>;
- * }
- * ```
- */
-export function useHasAllPermissions(
-  userId: UUID, 
-  scope: Scope, 
-  permissions: Permission[],
-  useCache: boolean = true
-): {
-  hasAll: boolean;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-} {
-  const [hasAll, setHasAll] = useState<boolean>(false);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const checkAllPermissions = useCallback(async () => {
-    if (!userId || permissions.length === 0) {
-      setHasAll(false);
-      setIsLoading(false);
-      return;
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      let hasAllPermissions = true;
-      
-      for (const permission of permissions) {
-        const result = useCache 
-          ? await isPermittedCached({ userId, scope, permission })
-          : await isPermitted({ userId, scope, permission });
-        
-        if (!result) {
-          hasAllPermissions = false;
-          break;
-        }
-      }
-      
-      setHasAll(hasAllPermissions);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error('Failed to check permissions'));
-      setHasAll(false);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, scope.organisationId, scope.eventId, scope.appId, permissions, useCache]);
-
-  useEffect(() => {
-    checkAllPermissions();
-  }, [checkAllPermissions]);
-
-  // Memoize the return object to prevent unnecessary re-renders
-  return useMemo(() => ({
-    hasAll,
-    isLoading,
-    error,
-    refetch: checkAllPermissions
-  }), [hasAll, isLoading, error, checkAllPermissions]);
-}
-
-/**
- * Hook to get cached permissions with TTL management
- * 
- * @param userId - User ID
- * @param scope - Scope for permission checking
- * @returns Cached permission state and methods
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { permissions, isLoading, error, invalidateCache } = useCachedPermissions(userId, scope);
- *   
- *   if (isLoading) return <div>Loading cached permissions...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *   
- *   return (
- *     <div>
- *       {permissions['read:users'] && <UserList />}
- *       <button onClick={invalidateCache}>Refresh Permissions</button>
- *     </div>
- *   );
- * }
- * ```
- */
-export function useCachedPermissions(userId: UUID, scope: Scope): {
-  permissions: PermissionMap;
-  isLoading: boolean;
-  error: Error | null;
-  invalidateCache: () => void;
-  refetch: () => Promise<void>;
-} {
-  const [permissions, setPermissions] = useState<PermissionMap>({} as PermissionMap);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const fetchCachedPermissions = useCallback(async () => {
-    if (!userId) {
-      setPermissions({} as PermissionMap);
-      setIsLoading(false);
-      return;
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      const permissionMap = await getPermissionMap({ userId, scope });
-      setPermissions(permissionMap);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error('Failed to fetch cached permissions'));
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, scope.organisationId, scope.eventId, scope.appId]);
-
-  const invalidateCache = useCallback(() => {
-    // This would typically invalidate the cache in the actual implementation
-    // For now, we'll just refetch
-    fetchCachedPermissions();
-  }, [fetchCachedPermissions]);
-
-  useEffect(() => {
-    fetchCachedPermissions();
-  }, [fetchCachedPermissions]);
-
-  // Memoize the return object to prevent unnecessary re-renders
-  return useMemo(() => ({
-    permissions,
-    isLoading,
-    error,
-    invalidateCache,
-    refetch: fetchCachedPermissions
-  }), [permissions, isLoading, error, invalidateCache, fetchCachedPermissions]);
-}
+ * RBAC Permission Hooks
+ *
+ * This barrel file re-exports the permission-related hooks. The implementations
+ * are organized in `./permissions` to keep the modules focused and maintainable.
+ */
+export {
+  usePermissions,
+  useCan,
+  useAccessLevel,
+  useMultiplePermissions,
+  useHasAnyPermission,
+  useHasAllPermissions,
+  useCachedPermissions,
+} from './permissions';