@jmruthers/pace-core 0.5.189 → 0.5.191

package/src/rbac/hooks/useResolvedScope.ts

@@ -9,16 +9,27 @@
  * consistent scope resolution logic.
  */
 
-import { useEffect, useState, useRef } from 'react';
+import { useEffect, useState, useRef, useMemo } from 'react';
 import { SupabaseClient } from '@supabase/supabase-js';
 import type { Database } from '../../types/database';
 import type { Scope } from '../types';
-import { createScopeFromEvent } from '../utils/eventContext';
+import { ContextValidator } from '../utils/contextValidator';
+import type { AppConfig } from '../utils/contextValidator';
 import { getCurrentAppName } from '../../utils/app/appNameResolver';
 import { createLogger } from '../../utils/core/logger';
 
 const log = createLogger('useResolvedScope');
 
+// Cache app config to avoid repeated database queries
+// App config rarely changes during a session, so we can cache it
+const appConfigCache = new Map<string, { appId: string; appConfig: AppConfig; timestamp: number }>();
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+// Export function to clear cache (for testing)
+export function clearAppConfigCache(): void {
+  appConfigCache.clear();
+}
+
 export interface UseResolvedScopeOptions {
   /** Supabase client instance */
   supabase: SupabaseClient<Database> | null;
@@ -78,11 +89,12 @@ export function useResolvedScope({
   });
   
   // Update stable scope ref in useEffect to avoid updates during render
+  // For PORTAL, allow scopes without organisationId
   useEffect(() => {
-    if (resolvedScope && resolvedScope.organisationId) {
+    if (resolvedScope) {
       const newScope = {
-        organisationId: resolvedScope.organisationId,
-        appId: resolvedScope.appId,
+        organisationId: resolvedScope.organisationId || '',
+        appId: resolvedScope.appId || '',
         eventId: resolvedScope.eventId
       };
       
@@ -92,16 +104,19 @@ export function useResolvedScope({
           stableScopeRef.current.appId !== newScope.appId) {
         stableScopeRef.current = {
           organisationId: newScope.organisationId,
-          appId: newScope.appId || '',
+          appId: newScope.appId,
           eventId: newScope.eventId
         };
       }
-    } else if (!resolvedScope) {
+    } else {
       // Reset to empty scope when no resolved scope
       stableScopeRef.current = { organisationId: '', appId: '', eventId: undefined };
     }
   }, [resolvedScope]);
   
+  // Get app name to check if it's PORTAL (needed for return logic)
+  const appName = getCurrentAppName();
+  
   const stableScope = stableScopeRef.current;
   
   useEffect(() => {
@@ -123,20 +138,28 @@ export function useResolvedScope({
       setError(null);
       
       try {
-        // Get app ID from package.json or environment
+        // Get app name and config
+        const appName = getCurrentAppName();
         let appId: string | undefined = undefined;
+        let appConfig: AppConfig | null = null;
         
-        // Try to resolve from database
-        if (supabase) {
-          const appName = getCurrentAppName();
-          if (appName) {
-            try {
+        // Try to resolve app config from database (with caching)
+        if (supabase && appName) {
+          try {
+            // Check cache first
+            const cached = appConfigCache.get(appName);
+            const now = Date.now();
+            if (cached && (now - cached.timestamp) < CACHE_TTL) {
+              appId = cached.appId;
+              appConfig = cached.appConfig;
+            } else {
+              // Cache miss or expired - fetch from database
               const { data: app, error } = await supabase
                 .from('rbac_apps')
-                .select('id, name, is_active')
+                .select('id, name, requires_event, is_active')
                 .eq('name', appName)
                 .eq('is_active', true)
-                .single() as { data: { id: string; name: string; is_active: boolean } | null; error: any };
+                .single() as { data: { id: string; name: string; requires_event: boolean; is_active: boolean } | null; error: any };
               
               if (error) {
                 // Check if app exists but is inactive
@@ -148,83 +171,89 @@ export function useResolvedScope({
                 
                 if (inactiveApp) {
                   log.error(`App "${appName}" exists but is inactive (is_active: ${inactiveApp.is_active})`);
+                  // Don't cache inactive apps - set appId to undefined
+                  appId = undefined;
                 } else {
                   log.error(`App "${appName}" not found in rbac_apps table`);
+                  // Don't cache missing apps - set appId to undefined
+                  appId = undefined;
                 }
               } else if (app) {
                 appId = app.id;
+                appConfig = { requires_event: app.requires_event ?? false };
+                // Only cache successful lookups of active apps
+                appConfigCache.set(appName, { appId, appConfig, timestamp: now });
               }
-            } catch (error) {
-              log.error('Unexpected error resolving app ID:', error);
             }
+          } catch (error) {
+            log.error('Unexpected error resolving app config:', error);
           }
         }
 
-        // Resolve scope based on available context
-
-        // If we have both organisation and event, use them directly
-        if (selectedOrganisationId && selectedEventId) {
-          if (!cancelled) {
-            setResolvedScope({
-              organisationId: selectedOrganisationId,
-              eventId: selectedEventId,
-              appId: appId
-            });
-            setIsLoading(false);
-          }
-          return;
-        }
+        // Build initial scope from available context
+        // For event-required apps: Only use eventId (org will be derived)
+        // For org-required apps: Only use organisationId (event is optional)
+        const initialScope: Scope = {
+          organisationId: appConfig?.requires_event ? undefined : (selectedOrganisationId || undefined),
+          eventId: selectedEventId || undefined,
+          appId: appId
+        };
 
-        // If we only have organisation, use it
-        if (selectedOrganisationId) {
-          if (!cancelled) {
-            setResolvedScope({
-              organisationId: selectedOrganisationId,
-              eventId: selectedEventId || undefined,
-              appId: appId
-            });
-            setIsLoading(false);
-          }
-          return;
-        }
+        // Use ContextValidator to resolve required context
+        // For PORTAL, always allow scope resolution even if appConfig is null
+        const validation = await ContextValidator.resolveRequiredContext(
+          initialScope,
+          appConfig,
+          appName || undefined,
+          supabase
+        );
 
-        // If we only have event, resolve organisation from event
-        if (selectedEventId && supabase) {
-          try {
-            const eventScope = await createScopeFromEvent(supabase, selectedEventId, appId);
-            if (!eventScope) {
-              log.error('Could not resolve organization from event context');
-              if (!cancelled) {
-                setResolvedScope(null);
-                setError(new Error('Could not resolve organisation from event context'));
-                setIsLoading(false);
-              }
-              return;
-            }
-            // Preserve the resolved app ID
+        if (!validation.isValid) {
+          // For PORTAL/ADMIN apps, allow scope without org/event even if validation fails
+          if (appName === 'PORTAL' || appName === 'ADMIN') {
             if (!cancelled) {
-              setResolvedScope({
-                ...eventScope,
-                appId: appId || eventScope.appId
-              });
+              // For PORTAL/ADMIN, we need at least an appId. If we don't have it from the query,
+              // we'll set it to undefined and let the component handle it (it can use contextAppId)
+              const optionalContextScope: Scope = {
+                organisationId: undefined,
+                eventId: undefined,
+                appId: appId || undefined // appId might be undefined if query failed, that's OK
+              };
+              setResolvedScope(optionalContextScope);
+              setError(null);
               setIsLoading(false);
             }
-          } catch (err) {
-            log.error('Error resolving scope from event:', err);
+            return;
+          }
+          
+          // For event-required apps: if validation fails but we have an eventId, return scope with eventId
+          // The organisation will be derived later during permission checks
+          if (appConfig?.requires_event && selectedEventId) {
             if (!cancelled) {
-              setResolvedScope(null);
-              setError(err as Error);
+              const eventScope: Scope = {
+                organisationId: undefined, // Will be derived from event during permission check
+                eventId: selectedEventId,
+                appId: appId || undefined
+              };
+              setResolvedScope(eventScope);
+              setError(null); // Don't set error - let permission check handle derivation
               setIsLoading(false);
             }
+            return;
+          }
+          
+          if (!cancelled) {
+            setResolvedScope(null);
+            setError(validation.error || new Error('Context validation failed'));
+            setIsLoading(false);
           }
           return;
         }
 
-        // No context available
-        log.error('No organisation or event context available');
+        // Set resolved scope
         if (!cancelled) {
-          setResolvedScope(null);
-          setError(new Error('No organisation or event context available'));
+          setResolvedScope(validation.resolvedScope);
+          setError(null);
           setIsLoading(false);
         }
       } catch (err) {
@@ -242,8 +271,37 @@ export function useResolvedScope({
     };
   }, [selectedOrganisationId, selectedEventId, supabase]);
   
+  // Return scope if it has appId (for PORTAL/ADMIN) or organisationId (for other apps)
+  // For PORTAL/ADMIN, always return a scope (even if empty) so components can use contextAppId
+  const allowsOptionalContexts = appName === 'PORTAL' || appName === 'ADMIN';
+  const hasValidScope = allowsOptionalContexts
+    ? true // PORTAL/ADMIN always have valid scope (even without org/event/appId)
+    : (stableScope.appId || stableScope.organisationId);
+  
+  // CRITICAL FIX: Memoize finalScope to prevent creating new object references on every render
+  // This prevents infinite loops in useCan and other hooks that depend on scope equality
+  const finalScope: Scope | null = useMemo(() => {
+    if (!hasValidScope) {
+      return allowsOptionalContexts ? {} : null;
+    }
+    
+    // Build scope object only with defined values to ensure stable reference
+    const scope: Scope = {};
+    if (stableScope.organisationId) {
+      scope.organisationId = stableScope.organisationId;
+    }
+    if (stableScope.eventId) {
+      scope.eventId = stableScope.eventId;
+    }
+    if (stableScope.appId) {
+      scope.appId = stableScope.appId;
+    }
+    
+    return scope;
+  }, [hasValidScope, allowsOptionalContexts, stableScope.organisationId, stableScope.eventId, stableScope.appId]);
+  
   return {
-    resolvedScope: stableScope.organisationId ? stableScope as Scope : null,
+    resolvedScope: finalScope,
     isLoading,
     error
   };

package/src/rbac/hooks/useSecureSupabase.ts

@@ -95,7 +95,7 @@
  *
  * - Must be used within `UnifiedAuthProvider` context
  * - Requires `useOrganisations` and `useEvents` hooks to be available
- * - Environment variables `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` must be set
+ * - Environment variables `VITE_SUPABASE_URL` and `VITE_SUPABASE_PUBLISHABLE_KEY` must be set
  *   (or `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY` for Next.js)
  *
  * ## See Also
@@ -120,6 +120,7 @@ import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
 import { useOrganisations } from '../../hooks/useOrganisations';
 import { useEvents } from '../../hooks/useEvents';
 import { useResolvedScope } from './useResolvedScope';
+import { useSuperAdminBypass } from './useSuperAdminBypass';
 import { createSecureClient, SecureSupabaseClient } from '../secureClient';
 import type { Database } from '../../types/database';
 import type { SupabaseClient } from '@supabase/supabase-js';
@@ -134,13 +135,15 @@ const MAX_CACHE_SIZE = 5;
 
 /**
  * Get cache key for secure client based on context
+ * CRITICAL: Must include isSuperAdmin in cache key to ensure correct filtering behavior
  */
 function getCacheKey(
   organisationId: string,
   eventId: string | undefined,
-  appId: string | undefined
+  appId: string | undefined,
+  isSuperAdmin: boolean
 ): string {
-  return `${organisationId}-${eventId || 'no-event'}-${appId || 'no-app'}`;
+  return `${organisationId}-${eventId || 'no-event'}-${appId || 'no-app'}-${isSuperAdmin ? 'super' : 'regular'}`;
 }
 
 /**
@@ -162,8 +165,8 @@ function getSupabaseConfig(): { url: string; key: string } | null {
                      getEnvVar('NEXT_PUBLIC_SUPABASE_URL') || 
                      null;
                      
-  const supabaseKey = getEnvVar('VITE_SUPABASE_ANON_KEY') || 
-                     getEnvVar('NEXT_PUBLIC_SUPABASE_ANON_KEY') || 
+  const supabaseKey = getEnvVar('VITE_SUPABASE_PUBLISHABLE_KEY') || 
+                     getEnvVar('NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY') || 
                      null;
 
   if (!supabaseUrl || !supabaseKey) {
@@ -210,6 +213,16 @@ export function useSecureSupabase(
   const eventsContext = useEvents();
   const { selectedEvent } = eventsContext;
   const eventLoading = 'eventLoading' in eventsContext ? eventsContext.eventLoading : false;
+  
+  // Check super admin status for conditional filtering
+  // Use both verified status and metadata hint to avoid race conditions
+  // Strategy: Use verified status if available, otherwise use metadata hint during verification
+  // This prevents creating clients with wrong super admin status before verification completes
+  const { isSuperAdmin: verifiedIsSuperAdmin, isLoading: isVerifyingSuperAdmin } = useSuperAdminBypass();
+  const metadataHint = Boolean(user?.app_metadata?.is_super_admin) || Boolean(user?.user_metadata?.is_super_admin);
+  // If verified as super admin, use that. If verification in progress, use metadata hint optimistically.
+  // Once verification completes and user is not super admin, verifiedIsSuperAdmin will be false.
+  const isSuperAdmin = verifiedIsSuperAdmin || (isVerifyingSuperAdmin && metadataHint);
 
   // Resolve scope to get appId
   const { resolvedScope } = useResolvedScope({
@@ -235,19 +248,20 @@ export function useSecureSupabase(
       return baseClient || authSupabase || null;
     }
     
-    // If we have organisation context, create or reuse a secure client
-    if (selectedOrganisation?.id && user?.id) {
-      const organisationId = selectedOrganisation.id;
-      const eventId = selectedEvent?.event_id;
-      
-      // Get appId from resolved scope if available
-      const appId = resolvedScope?.appId;
-
+    // Use resolved scope to get organisationId (derived from event if needed)
+    // For event-required apps, resolvedScope.organisationId is derived from event
+    // For org-required apps, resolvedScope.organisationId comes from selectedOrganisation
+    const organisationId = resolvedScope?.organisationId;
+    const eventId = resolvedScope?.eventId || selectedEvent?.event_id;
+    const appId = resolvedScope?.appId;
+    
+    // If we have organisation context (from resolved scope), create or reuse a secure client
+    if (organisationId && user?.id) {
       // Update previous context
       prevContextRef.current = { organisationId, eventId, appId };
 
-      // Check cache first
-      const cacheKey = getCacheKey(organisationId, eventId, appId);
+      // Check cache first (must include isSuperAdmin in key for correct filtering)
+      const cacheKey = getCacheKey(organisationId, eventId, appId, isSuperAdmin);
       const cachedClient = secureClientCache.get(cacheKey);
 
       if (cachedClient) {
@@ -259,7 +273,7 @@ export function useSecureSupabase(
       const config = getSupabaseConfig();
       if (!config || !config.url || !config.key) {
         logger.warn('useSecureSupabase', 'Missing Supabase environment variables. Falling back to base client.', {
-          note: 'Ensure VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY are set in your environment.'
+          note: 'Ensure VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_KEY are set in your environment.'
         });
         return baseClient || authSupabase || null;
       }
@@ -270,7 +284,8 @@ export function useSecureSupabase(
           config.key,
           organisationId as any, // organisationId is string, UUID is string alias
           eventId,
-          appId as any // appId is string | undefined, UUID is string alias
+          appId as any, // appId is string | undefined, UUID is string alias
+          isSuperAdmin // Pass super admin status for conditional filtering
         );
 
         // Cache the client for reuse
@@ -296,11 +311,13 @@ export function useSecureSupabase(
     // Fallback to base client when context is not available
     return baseClient || authSupabase || null;
   }, [
-    selectedOrganisation?.id,
+    resolvedScope?.organisationId,
+    resolvedScope?.eventId,
+    resolvedScope?.appId,
     selectedEvent?.event_id,
     user?.id,
     eventLoading,
-    resolvedScope?.appId,
+    isSuperAdmin,
     baseClient,
     authSupabase
   ]);

package/src/rbac/hooks/useSuperAdminBypass.ts

@@ -0,0 +1,126 @@
+/**
+ * @file useSuperAdminBypass
+ * @package @jmruthers/pace-core
+ *
+ * Detects whether the current user is a super admin, keeps the
+ * server session override flag in sync, and exposes a boolean
+ * that downstream hooks can use to bypass organisation scoping.
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useUnifiedAuth, type UnifiedAuthContextType } from '../../providers/services/UnifiedAuthProvider';
+import { isSuperAdmin as fetchIsSuperAdmin } from '../api';
+import { setSuperAdminOverrideFlag } from '../../utils/context/superAdminOverride';
+import { createLogger } from '../../utils/core/logger';
+
+const log = createLogger('useSuperAdminBypass');
+
+export interface SuperAdminBypassState {
+  /** True when the user has been verified as a super admin */
+  isSuperAdmin: boolean;
+  /** True while the hook is checking the server */
+  isLoading: boolean;
+  /** Error returned by the verification request, if any */
+  error: Error | null;
+}
+
+function useSafeUnifiedAuth(): UnifiedAuthContextType | null {
+  try {
+    return useUnifiedAuth();
+  } catch (error) {
+    log.debug('useSuperAdminBypass', 'UnifiedAuthProvider not available, falling back to defaults', {
+      error: error instanceof Error ? error.message : error
+    });
+    return null;
+  }
+}
+
+export function useSuperAdminBypass(): SuperAdminBypassState {
+  const authContext = useSafeUnifiedAuth();
+  const user = authContext?.user ?? null;
+  const supabase = authContext?.supabase ?? null;
+  const metadataHint =
+    Boolean(user?.app_metadata?.is_super_admin) ||
+    Boolean(user?.user_metadata?.is_super_admin);
+
+  const [isSuperAdminState, setIsSuperAdminState] = useState<boolean>(metadataHint);
+  const [hasVerified, setHasVerified] = useState<boolean>(!user?.id);
+  const [isLoading, setIsLoading] = useState<boolean>(!!user?.id);
+  const [error, setError] = useState<Error | null>(null);
+  const lastOverrideValueRef = useRef<boolean | null>(null);
+
+  // Verify against the RBAC engine whenever the user changes
+  useEffect(() => {
+    if (!user?.id) {
+      setIsSuperAdminState(false);
+      setHasVerified(true);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    let cancelled = false;
+    setIsLoading(true);
+    setError(null);
+
+    fetchIsSuperAdmin(user.id)
+      .then((result) => {
+        if (cancelled) {
+          return;
+        }
+        setIsSuperAdminState(result);
+        setHasVerified(true);
+      })
+      .catch((err) => {
+        if (cancelled) {
+          return;
+        }
+        const normalisedError =
+          err instanceof Error ? err : new Error('Failed to resolve super admin status');
+        setError(normalisedError);
+        setIsSuperAdminState(false);
+        setHasVerified(false);
+        log.error('Unable to verify super admin status', normalisedError);
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [user?.id]);
+
+  const shouldBypass = hasVerified && isSuperAdminState;
+
+  // Keep the database session flag in sync for auditing/RLS helpers
+  useEffect(() => {
+    if (!supabase) {
+      return;
+    }
+    if (lastOverrideValueRef.current === shouldBypass) {
+      return;
+    }
+    lastOverrideValueRef.current = shouldBypass;
+
+    setSuperAdminOverrideFlag({
+      supabase,
+      enabled: shouldBypass,
+      reason: 'pace-core-super-admin-bypass'
+    }).catch(() => {
+      // Errors are logged inside the helper
+    });
+  }, [supabase, shouldBypass]);
+
+  return useMemo(
+    () => ({
+      isSuperAdmin: shouldBypass,
+      isLoading,
+      error
+    }),
+    [shouldBypass, isLoading, error]
+  );
+}
+

package/src/rbac/request-deduplication.ts

@@ -27,7 +27,7 @@ const inFlightRequests = new Map<string, Promise<boolean>>();
 function generateDeduplicationKey(input: PermissionCheck): string {
   return RBACCache.generatePermissionKey({
     userId: input.userId,
-    organisationId: input.scope.organisationId!,
+    organisationId: input.scope.organisationId, // Can be undefined for page-level permissions
     eventId: input.scope.eventId,
     appId: input.scope.appId,
     permission: input.permission,