@jmruthers/pace-core 0.5.189 → 0.5.190

package/src/rbac/hooks/usePermissions.ts

@@ -12,7 +12,8 @@ import {
   UUID, 
   Scope, 
   Permission, 
-  PermissionMap
+  PermissionMap,
+  OrganisationContextRequiredError
 } from '../types';
 import { AccessLevel as AccessLevelType } from '../types';
 import { 
@@ -23,6 +24,7 @@ import {
 } 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
@@ -97,28 +99,30 @@ export function usePermissions(
     if (error?.message === 'Organisation context is required for permission checks') {
       setError(null);
     }
-  }, [userId, organisationId, error]);
-
-  // CRITICAL: Detect parameter changes imperatively and trigger fetch
-  // This bypasses React's useEffect dependency tracking which is failing to detect appId changes
-  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) {
-      logger.debug('[usePermissions] AppId changed - triggering fetch', {
-        prevAppId: prevValuesRef.current.appId,
-        newAppId: appId
-      });
+  }, [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) {
+        logger.debug('[usePermissions] AppId changed - triggering fetch', {
+          prevAppId: prevValuesRef.current.appId,
+          newAppId: appId
+        });
+      }
+      prevValuesRef.current = { userId, organisationId, eventId, appId };
+      // Increment counter to force fetch useEffect to run
+      setFetchTrigger(prev => prev + 1);
     }
-    prevValuesRef.current = { userId, organisationId, eventId, appId };
-    // Increment counter to force useEffect to run
-    setFetchTrigger(prev => prev + 1);
-  }
+  }, [userId, organisationId, eventId, appId, logger]);
 
   useEffect(() => {
     const fetchPermissions = async () => {
@@ -283,6 +287,7 @@ export function usePermissions(
  * @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
@@ -302,7 +307,8 @@ export function useCan(
   scope: Scope, 
   permission: Permission, 
   pageId?: UUID,
-  useCache: boolean = true
+  useCache: boolean = true,
+  appName?: string
 ) {
   const [can, setCan] = useState<boolean>(false);
   const [isLoading, setIsLoading] = useState(true);
@@ -315,8 +321,12 @@ export function useCan(
   const appId = isValidScope ? scope.appId : undefined;
 
   // Add timeout for missing organisation context (3 seconds)
+  // Only apply timeout for resource-level permissions, not page-level (which can handle null orgs)
   useEffect(() => {
-    if (!isValidScope || !organisationId || organisationId === null || (typeof organisationId === 'string' && organisationId.trim() === '')) {
+    const isPagePermission = permission.includes(':page.') || !!pageId;
+    const requiresOrgId = !isPagePermission;
+    
+    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);
@@ -329,7 +339,7 @@ export function useCan(
     if (error?.message === 'Organisation context is required for permission checks') {
       setError(null);
     }
-  }, [isValidScope, organisationId, error]);
+  }, [isValidScope, organisationId, error, permission, pageId]);
 
   // Use refs to track the last values to prevent unnecessary re-runs
   const lastUserIdRef = useRef<UUID | null>(null);
@@ -388,30 +398,50 @@ export function useCan(
           return;
         }
 
-        // Don't check permissions if scope is invalid (e.g., organisationId is null/empty)
-        // Wait for organisation context to resolve
-        if (!organisationId || organisationId === null || (typeof organisationId === 'string' && organisationId.trim() === '')) {
+        // 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)
+        if (requiresOrgId && (!organisationId || organisationId === null || (typeof organisationId === 'string' && organisationId.trim() === ''))) {
           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 ? { organisationId } : {}),
             ...(eventId ? { eventId } : {}),
             ...(appId ? { appId } : {})
           };
           
           const result = useCache 
-            ? await isPermittedCached({ userId, scope: validScope, permission, pageId })
-            : await isPermitted({ userId, scope: validScope, permission, pageId });
+            ? await isPermittedCached({ userId, scope: validScope, permission, pageId }, undefined, appName)
+            : await isPermitted({ userId, scope: validScope, permission, pageId }, undefined, appName);
           
           setCan(result);
         } catch (err) {
@@ -426,7 +456,7 @@ export function useCan(
       
       checkPermission();
     }
-  }, [userId, stableScope, permission, pageId, useCache]);
+  }, [userId, stableScope, permission, pageId, useCache, appName]);
 
   const refetch = useCallback(async () => {
     if (!userId) {
@@ -443,8 +473,13 @@ export function useCan(
       return;
     }
 
-    // Don't check permissions if scope is invalid (e.g., organisationId is null/empty)
-    if (!organisationId || organisationId === null || (typeof organisationId === 'string' && organisationId.trim() === '')) {
+    // 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);
@@ -456,15 +491,16 @@ export function useCan(
       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 ? { organisationId } : {}),
         ...(eventId ? { eventId } : {}),
         ...(appId ? { appId } : {})
       };
       
       const result = useCache 
-        ? await isPermittedCached({ userId, scope: validScope, permission, pageId })
-        : await isPermitted({ userId, scope: validScope, permission, pageId });
+        ? await isPermittedCached({ userId, scope: validScope, permission, pageId }, undefined, appName)
+        : await isPermitted({ userId, scope: validScope, permission, pageId }, undefined, appName);
       
       setCan(result);
     } catch (err) {
@@ -473,7 +509,7 @@ export function useCan(
     } finally {
       setIsLoading(false);
     }
-  }, [userId, isValidScope, organisationId, eventId, appId, permission, pageId, useCache]);
+  }, [userId, isValidScope, organisationId, eventId, appId, permission, pageId, useCache, appName]);
 
   // Memoize the return object to prevent unnecessary re-renders
   return useMemo(() => ({
@@ -518,6 +554,15 @@ export function useAccessLevel(userId: UUID, scope: Scope): {
   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');
@@ -529,15 +574,37 @@ export function useAccessLevel(userId: UUID, scope: Scope): {
       setIsLoading(true);
       setError(null);
       
-      const level = await getAccessLevel({ userId, scope });
+      // 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) {
-      setError(err instanceof Error ? err : new Error('Failed to fetch access level'));
+      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]);
+  }, [userId, scope.organisationId, scope.eventId, scope.appId, appName]);
 
   useEffect(() => {
     fetchAccessLevel();

package/src/rbac/hooks/useRBAC.test.ts

@@ -108,10 +108,18 @@ describe('useRBAC', () => {
 
     expect(mockResolveAppContext).toHaveBeenCalledWith({ userId: 'user-1', appName: 'test-app' });
     expect(mockGetPermissionMap).toHaveBeenCalledWith(
-      expect.objectContaining({
+      {
         userId: 'user-1',
-        scope: expect.objectContaining({ organisationId: 'org-1' }),
-      }),
+        scope: {
+          organisationId: 'org-1',
+          eventId: undefined,
+          appId: 'app-123'
+        }
+      },
+      {
+        requires_event: false,
+      },
+      'test-app'
     );
   });
 

package/src/rbac/hooks/useRBAC.ts

@@ -21,6 +21,7 @@ import {
   getRoleContext,
 } from '../api';
 import { getRBACLogger } from '../config';
+import { ContextValidator } from '../utils/contextValidator';
 import type {
   UserRBACContext,
   GlobalRole,
@@ -55,8 +56,10 @@ export function useRBAC(pageId?: string): UserRBACContext {
   const { 
     user, 
     session, 
+    supabase,
     appName, 
     appConfig,
+    appId: contextAppId,
     selectedOrganisation,
     isContextReady: orgContextReady,
     organisationLoading: orgLoading,
@@ -64,11 +67,6 @@ export function useRBAC(pageId?: string): UserRBACContext {
     eventLoading
   } = useUnifiedAuth();
   
-  // Check if app requires event context
-  // IMPORTANT: If appConfig is null initially, default to true (safer for event-based apps)
-  // This prevents premature loading when appConfig hasn't loaded yet
-  const requiresEvent = appConfig?.requires_event ?? (appConfig === null ? true : false);
-  
   // Removed excessive logging - hook initialization logged only on first mount or significant changes
 
   const [globalRole, setGlobalRole] = useState<GlobalRole | null>(null);
@@ -95,55 +93,79 @@ export function useRBAC(pageId?: string): UserRBACContext {
       return;
     }
 
-    // Wait for organisation context to be ready before loading RBAC
-    // This is critical - without organisation ID, RPC calls can't resolve permissions
-    if (orgLoading || !orgContextReady || !selectedOrganisation?.id) {
+    // Build initial scope from available context
+    // For event-required apps: use organisation_id from selectedEvent if available (faster than deriving)
+    // For org-required apps: use selectedOrganisation.id
+    const initialScope: Scope = {
+      organisationId: appConfig?.requires_event 
+        ? (selectedEvent?.organisation_id || selectedOrganisation?.id) 
+        : selectedOrganisation?.id,
+      eventId: selectedEvent?.event_id || undefined,
+      appId: undefined
+    };
+
+    // Check if context is ready using ContextValidator
+    const contextReady = ContextValidator.isContextReady(
+      initialScope,
+      appConfig,
+      appName,
+      !!selectedEvent,
+      !!selectedOrganisation
+    );
+
+    // PORTAL/ADMIN special case: context is always ready
+    if (appName !== 'PORTAL' && appName !== 'ADMIN' && !contextReady) {
+      // Wait for appropriate context based on app config
       setIsLoading(true);
       return;
     }
 
-    // For event-based apps, wait for event context to be ready before loading RBAC
-    // This prevents NetworkError when RPC calls are made before event context is available
-    if (requiresEvent) {
-      if (eventLoading || !selectedEvent) {
-        // Event context not ready yet - don't load RBAC yet
-        // This prevents premature RPC calls that can cause NetworkError
-        // Set loading state so React knows we're waiting
-        setIsLoading(true);
-        return;
-      }
-    }
-
     setIsLoading(true);
     setError(null);
 
     // Only log at debug level - loading RBAC context is normal operation
-    // Changed from warn to debug to reduce console noise
     logger.debug('[useRBAC] Loading RBAC context', {
       appName,
-      requiresEvent,
+      appConfig,
       hasSelectedEvent: !!selectedEvent,
       selectedEventId: selectedEvent?.event_id,
       organisationId: selectedOrganisation?.id
     });
 
     try {
-      let appId: UUID | undefined;
-      if (appName) {
+      let appId: UUID | undefined = contextAppId; // Use contextAppId as default (already resolved in UnifiedAuthProvider)
+      
+      if (appName && !appId) {
         // Wrap RPC call in try-catch to handle NetworkError gracefully
         try {
           const resolved = await resolveAppContext({ userId: user.id as UUID, appName });
-          if (!resolved || !resolved.hasAccess) {
+          // For PORTAL/ADMIN apps, allow access even if hasAccess is false (users can view their own profile, super admins have global access)
+          if (!resolved) {
+            if (appName === 'PORTAL' || appName === 'ADMIN') {
+              // For PORTAL/ADMIN, try to get appId directly from database
+              logger.debug(`[useRBAC] ${appName} app context not resolved, attempting direct lookup`);
+              try {
+                const { getAppConfigByName } = await import('../api');
+                const config = await getAppConfigByName(appName);
+                // We can't get appId from config, but that's OK - use contextAppId or proceed without
+                logger.debug(`[useRBAC] ${appName} app - proceeding without appId for page-level permissions`);
+              } catch (err) {
+                logger.debug(`[useRBAC] ${appName} app - proceeding without appId for page-level permissions`);
+              }
+            } else {
+              throw new Error(`User does not have access to app "${appName}"`);
+            }
+          } else if (!resolved.hasAccess && appName !== 'PORTAL' && appName !== 'ADMIN') {
             throw new Error(`User does not have access to app "${appName}"`);
+          } else {
+            appId = resolved.appId;
           }
-          appId = resolved.appId;
         } catch (rpcError: any) {
           // Handle NetworkError - might be due to timing issue
           if (rpcError?.message?.includes('NetworkError') || rpcError?.message?.includes('fetch')) {
             logger.warn('[useRBAC] NetworkError resolving app context - may be timing issue, will retry when context is ready', {
               appName,
               error: rpcError.message,
-              requiresEvent,
               eventLoading,
               hasSelectedEvent: !!selectedEvent
             });
@@ -151,23 +173,44 @@ export function useRBAC(pageId?: string): UserRBACContext {
             setIsLoading(false);
             return;
           }
-          // Re-throw other errors
-          throw rpcError;
+          // For PORTAL/ADMIN, allow proceeding without app access check (for profile pages, super admin access)
+          if (appName === 'PORTAL' || appName === 'ADMIN') {
+            logger.debug(`[useRBAC] ${appName} app - allowing access despite app context resolution failure`);
+            // appId will use contextAppId or be undefined, which is OK for PORTAL/ADMIN page-level permissions
+          } else {
+            // Re-throw other errors for non-PORTAL apps
+            throw rpcError;
+          }
         }
       }
 
+      // Update scope with appId (use contextAppId as fallback for PORTAL)
       const scope: Scope = {
-        organisationId: selectedOrganisation?.id,
-        eventId: selectedEvent?.event_id || undefined,
-        appId,
+        ...initialScope,
+        appId: appId || contextAppId,
       };
       
-      setCurrentScope(scope);
+      // Resolve required context using ContextValidator
+      // Pass supabase client to allow deriving organisation from event for event-required apps
+      const validation = await ContextValidator.resolveRequiredContext(
+        scope,
+        appConfig,
+        appName,
+        supabase || null
+      );
+
+      if (!validation.isValid || !validation.resolvedScope) {
+        throw validation.error || new Error('Context validation failed');
+      }
+
+      const resolvedScope = validation.resolvedScope;
+      setCurrentScope(resolvedScope);
 
+      // Pass appConfig and appName to API calls for context validation
       const [map, roleContext, accessLevel] = await Promise.all([
-        getPermissionMap({ userId: user.id as UUID, scope }),
-        getRoleContext({ userId: user.id as UUID, scope }),
-        getAccessLevel({ userId: user.id as UUID, scope }),
+        getPermissionMap({ userId: user.id as UUID, scope: resolvedScope }, appConfig, appName),
+        getRoleContext({ userId: user.id as UUID, scope: resolvedScope }, appConfig, appName),
+        getAccessLevel({ userId: user.id as UUID, scope: resolvedScope }, appConfig, appName),
       ]);
 
       setPermissionMap(map);
@@ -180,8 +223,8 @@ export function useRBAC(pageId?: string): UserRBACContext {
       if (permissionCount === 0) {
         logger.warn('[useRBAC] RBAC context loaded but returned 0 permissions', {
           appName,
-          organisationId: selectedOrganisation.id,
-          eventId: selectedEvent?.event_id
+          organisationId: resolvedScope.organisationId,
+          eventId: resolvedScope.eventId
         });
       }
     } catch (err) {
@@ -192,7 +235,7 @@ export function useRBAC(pageId?: string): UserRBACContext {
     } finally {
       setIsLoading(false);
     }
-  }, [appName, logger, resetState, selectedEvent?.event_id, selectedOrganisation?.id, session, user, requiresEvent, eventLoading, appConfig, orgContextReady, orgLoading]);
+  }, [appName, logger, resetState, selectedEvent?.event_id, selectedOrganisation?.id, session, user, eventLoading, appConfig, orgContextReady, orgLoading]);
 
   const hasGlobalPermission = useCallback(
     (permission: string): boolean => {
@@ -221,7 +264,7 @@ export function useRBAC(pageId?: string): UserRBACContext {
 
   useEffect(() => {
     loadRBACContext();
-  }, [loadRBACContext, appName, requiresEvent, eventLoading, selectedEvent?.event_id, user, session, selectedOrganisation?.id, orgContextReady, orgLoading]);
+  }, [loadRBACContext, appName, appConfig, eventLoading, selectedEvent?.event_id, user, session, selectedOrganisation?.id, orgContextReady, orgLoading]);
 
   return {
     user,