@jmruthers/pace-core 0.6.10 → 0.6.12

package/src/rbac/components/PagePermissionGuard.tsx

@@ -26,7 +26,7 @@
  * >
  *   <DashboardPage />
  * </PagePermissionGuard>
- * 
+ *
  * // Strict mode (prevents bypassing)
  * <PagePermissionGuard
  *   pageName="admin"
@@ -36,7 +36,7 @@
  * >
  *   <AdminPage />
  * </PagePermissionGuard>
- * 
+ *
  * // With custom fallback
  * <PagePermissionGuard
  *   pageName="settings"
@@ -67,58 +67,89 @@
  * - RBAC types - Type definitions
  */
 
-import React, { useMemo, useEffect, useState, useRef } from 'react';
-import { useCan } from '../hooks/usePermissions';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
 import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
-import { useResolvedScope } from '../hooks/useResolvedScope';
 import { Permission, Scope } from '../types';
-import { getRBACLogger } from '../config';
-
-const logger = getRBACLogger();
-import { scopeEqual } from '../utils/deep-equal';
+import { useSuperAdminCheck } from '../hooks/useSuperAdminCheck';
+import { usePageGuardScope } from '../hooks/usePageGuardScope';
+import { usePagePermissionCheck } from '../hooks/usePagePermissionCheck';
+import { usePageAccessLogging } from '../hooks/usePageAccessLogging';
 import { AccessDenied } from './AccessDenied';
 import { Alert, AlertTitle } from '../../components/Alert/Alert';
 import { LoadingSpinner } from '../../components/LoadingSpinner/LoadingSpinner';
+import { cn } from '../../utils/core/cn';
+import { setPrintTitle } from '../../theming/runtime';
 
 export interface PagePermissionGuardProps {
   /** Name of the page being protected */
   pageName: string;
-  
+
   /** Operation being performed on the page */
   operation: 'read' | 'create' | 'update' | 'delete';
-  
+
   /** Content to render when user has permission */
   children: React.ReactNode;
-  
+
   /** Content to render when user lacks permission */
   fallback?: React.ReactNode;
-  
+
   /** Enable strict mode to prevent bypassing (default: true) */
   strictMode?: boolean;
-  
+
   /** Force audit logging for this page access (default: true) */
   auditLog?: boolean;
-  
+
   /** Custom page ID for permission checking */
   pageId?: string;
-  
+
   /** Custom scope for permission checking */
   scope?: Scope;
-  
+
   /** Callback when access is denied */
   onDenied?: (pageName: string, operation: string) => void;
-  
+
   /** Loading state content */
   loading?: React.ReactNode;
+
+  /** Print page orientation for this page (default: 'portrait') */
+  printPageOrientation?: 'portrait' | 'landscape';
+
+  /** Title used in print headers/margin-box (sets --print-title). */
+  printTitle?: string;
+}
+
+type PageGuardView = 'super-admin' | 'loading' | 'denied' | 'content' | 'fallback';
+
+function getPageGuardView(state: {
+  isSuperAdmin: boolean | null;
+  hasValidUser: boolean;
+  isLoading: boolean;
+  hasChecked: boolean;
+  scopeError: Error | null;
+  can: boolean;
+  effectiveCan: boolean;
+  effectiveScope: Scope | null;
+  allowsOptionalContexts: boolean;
+  shouldBypassScopeForSuperAdmin: boolean;
+}): PageGuardView {
+  const { isSuperAdmin, hasValidUser, isLoading, hasChecked, scopeError, can, effectiveCan, effectiveScope, allowsOptionalContexts, shouldBypassScopeForSuperAdmin } = state;
+  if (isSuperAdmin === true && hasValidUser) return 'super-admin';
+  if (isLoading || !hasValidUser || !hasChecked || isSuperAdmin === null) return 'loading';
+  const hasValidScope = shouldBypassScopeForSuperAdmin ? true : (allowsOptionalContexts ? true : effectiveScope !== null);
+  const checkComplete = hasChecked && !isLoading;
+  if (scopeError && !can) return 'denied';
+  if (checkComplete && hasValidScope && hasValidUser && !scopeError && !effectiveCan) return 'denied';
+  if (checkComplete && hasValidScope && hasValidUser && !scopeError && effectiveCan) return 'content';
+  return 'fallback';
 }
 
 /**
  * PagePermissionGuard - Enforces page-level permissions
- * 
+ *
  * This component ensures that users can only access pages they have permission for.
  * It integrates with the existing RBAC system and provides strict enforcement to
  * prevent apps from bypassing permission checks.
- * 
+ *
  * @param props - Component props
  * @returns React element with permission enforcement
  */
@@ -132,382 +163,157 @@ const PagePermissionGuardComponent = ({
   pageId,
   scope,
   onDenied,
-  loading = <DefaultLoading />
+  loading = <DefaultLoading />,
+  printPageOrientation = 'portrait',
+  printTitle
 }: PagePermissionGuardProps) => {
+  // Set --print-title when printTitle prop is provided; clear on unmount or when prop is removed
+  useEffect(() => {
+    if (printTitle) setPrintTitle(printTitle);
+    return () => {
+      if (typeof document !== 'undefined' && document.documentElement) {
+        document.documentElement.style.removeProperty('--print-title');
+      }
+    };
+  }, [printTitle]);
+
   // Track render count for debugging
   const renderCountRef = useRef(0);
   renderCountRef.current += 1;
-  
+
   // Generate a unique instance ID for debugging (must be called before any conditional returns)
   const _instanceId = useMemo(() => Math.random().toString(36).substr(2, 9), []);
-  
+
   // Use UnifiedAuth hook - if context is not available, it will throw and ErrorBoundary will handle it
   // This is better than checking for context and returning early, which causes infinite loops
   const { user, selectedOrganisation, selectedEvent, supabase, appId: contextAppId, appName } = useUnifiedAuth();
-  
-  const [hasChecked, setHasChecked] = useState(false);
-  const hasLoggedSuperAdminRef = useRef(false);
+  const { isSuperAdmin } = useSuperAdminCheck(user?.id);
 
-  // Determine the page ID for permission checking
-  const effectivePageId = useMemo((): string => {
-    return pageId || pageName;
-  }, [pageId, pageName]);
-  
-  // Check super admin status directly - don't rely on useRBAC which might not be loaded yet
-  // This ensures super admins get immediate access without waiting for RBAC context to load
-  const [isSuperAdmin, setIsSuperAdmin] = useState<boolean | null>(null);
-  
-  useEffect(() => {
-    if (!user?.id) {
-      setIsSuperAdmin(false);
-      return;
-    }
+  const effectivePageId = useMemo(() => pageId || pageName, [pageId, pageName]);
+  const permission = useMemo((): Permission => `${operation}:page.${pageName}` as Permission, [operation, pageName]);
 
-    let cancelled = false;
-    const checkSuperAdmin = async () => {
-      const startTime = Date.now();
-      try {
-        const { isSuperAdmin: checkSuperAdmin } = await import('../api');
-        
-        // Add timeout to prevent hanging
-        const timeoutPromise = new Promise<boolean>((_, reject) => {
-          setTimeout(() => reject(new Error('Super admin check timeout')), 10000);
-        });
-        
-        const isSuper = await Promise.race([
-          checkSuperAdmin(user.id),
-          timeoutPromise
-        ]);
-        
-        const elapsed = Date.now() - startTime;
-        
-        if (!cancelled) {
-          setIsSuperAdmin(isSuper);
-          if (process.env.NODE_ENV === 'development') {
-            const logger = getRBACLogger();
-            logger.debug('[PagePermissionGuard] Super admin check completed', {
-              userId: user.id,
-              isSuperAdmin: isSuper,
-              elapsedMs: elapsed
-            });
-          }
-        }
-      } catch (err) {
-        const elapsed = Date.now() - startTime;
-        if (!cancelled) {
-          const logger = getRBACLogger();
-          logger.error('[PagePermissionGuard] Error checking super admin', { 
-            error: err,
-            userId: user.id,
-            elapsedMs: elapsed
-          });
-          // On timeout or error, assume not super admin (fail secure)
-          // But log it so we can debug
-          setIsSuperAdmin(false);
-        }
-      }
-    };
-
-    checkSuperAdmin();
-    return () => {
-      cancelled = true;
-    };
-  }, [user?.id]);
-  
-  // Use useResolvedScope hook for consistent scope resolution
-  // For event-required apps: selectedOrganisation is null, org derived from event
-  // For org-required apps: selectedOrganisation is available, event optional
-  // For page-level permissions, PORTAL app allows both contexts to be optional
-  // NOTE: Super admins bypass scope requirements, but we still need to call the hook
-  const { resolvedScope: hookResolvedScope, isLoading: scopeLoading, error: scopeError } = useResolvedScope({
+  const {
+    effectiveScope,
+    stableScope,
+    scopeForPermissionCheck,
+    scopeLoading,
+    scopeError,
+    allowsOptionalContexts
+  } = usePageGuardScope({
     supabase,
-    selectedOrganisationId: selectedOrganisation?.id || null,
-    selectedEventId: selectedEvent?.event_id || null,
-    selectedEventOrganisationId: selectedEvent?.organisation_id || null
+    selectedOrganisationId: selectedOrganisation?.id ?? null,
+    selectedEventId: selectedEvent?.event_id ?? null,
+    selectedEventOrganisationId: selectedEvent?.organisation_id ?? null,
+    scope,
+    contextAppId,
+    appName,
+    isSuperAdmin
   });
-  
-  // For super admins, we can use a minimal scope since they bypass all checks
-  // This prevents scope resolution from blocking super admin access
-  const shouldBypassScopeForSuperAdmin = isSuperAdmin === true;
-  
-  // Use provided scope if available, otherwise use resolved scope
-  // For PORTAL app page-level permissions, allow scope without org/event
-  // Ensure appId is available for PORTAL/ADMIN (use contextAppId as fallback)
-  // For event-required apps: if resolved scope is null but we have a selectedEvent, include eventId
-  const allowsOptionalContexts = useMemo(() => appName === 'PORTAL' || appName === 'ADMIN', [appName]);
-  const effectiveScope: Scope | null = useMemo(() => scope || (hookResolvedScope ? {
-    ...hookResolvedScope,
-    appId: hookResolvedScope.appId || (allowsOptionalContexts ? contextAppId : undefined)
-  } : (allowsOptionalContexts && contextAppId ? {
-    organisationId: undefined,
-    eventId: undefined,
-    appId: contextAppId
-  } : (selectedEvent?.event_id ? {
-    organisationId: undefined, // Will be derived from event
-    eventId: selectedEvent.event_id,
-    appId: contextAppId || undefined
-  } : null))), [scope, hookResolvedScope, allowsOptionalContexts, contextAppId, selectedEvent?.event_id]);
-  const checkError = scopeError;
 
-  // Build the permission string
-  const permission = useMemo((): Permission => {
-    return `${operation}:page.${pageName}` as Permission;
-  }, [operation, pageName]);
-
-  // Create a stable scope that only includes valid values
-  // For page-level permissions, PORTAL/ADMIN apps allow undefined org/event
-  // Use ref to track previous scope for deep equality comparison
-  const prevScopeRef = useRef<Scope | null>(null);
-  const stableScope = useMemo(() => {
-    // For PORTAL/ADMIN apps, allow scope without org/event for page-level permissions
-    if (allowsOptionalContexts && effectiveScope) {
-      const newScope: Scope = {
-        organisationId: effectiveScope.organisationId,
-        appId: effectiveScope.appId || contextAppId || undefined,
-        eventId: effectiveScope.eventId
-      };
-      
-      if (scopeEqual(prevScopeRef.current, newScope)) {
-        return prevScopeRef.current!;
-      }
-      
-      prevScopeRef.current = newScope;
-      return newScope;
-    }
-    
-    // For other apps, require org context (unless it's a page permission)
-    // For event-required apps: include eventId even if organisationId is not yet available (will be derived)
-    const newScope: Scope = effectiveScope && effectiveScope.organisationId
-      ? {
-          organisationId: effectiveScope.organisationId,
-          appId: effectiveScope.appId || contextAppId || undefined,
-          eventId: effectiveScope.eventId || undefined
-        }
-      : { 
-          organisationId: effectiveScope?.organisationId || undefined, 
-          appId: effectiveScope?.appId || contextAppId || undefined, 
-          eventId: effectiveScope?.eventId || selectedEvent?.event_id || undefined 
-        };
-    
-    // Only return new object if scope actually changed (deep equality check)
-    if (scopeEqual(prevScopeRef.current, newScope)) {
-      return prevScopeRef.current!;
-    }
-    
-    prevScopeRef.current = newScope;
-    return newScope;
-  }, [effectiveScope, contextAppId, selectedEvent?.event_id, allowsOptionalContexts]);
-
-  // For super admins, use a minimal valid scope since they bypass all checks
-  // This prevents scope validation from blocking super admin access
-  const scopeForPermissionCheck = shouldBypassScopeForSuperAdmin && !stableScope?.organisationId
-    ? { 
-        organisationId: undefined, 
-        appId: contextAppId || undefined, 
-        eventId: selectedEvent?.event_id || undefined 
-      }
-    : stableScope;
-  
-  // CRITICAL: If super admin is confirmed, skip useCan entirely to avoid any blocking
-  // Super admins have access to everything, so no need to check permissions
+  const shouldBypassScopeForSuperAdmin = isSuperAdmin === true;
   const shouldSkipPermissionCheck = isSuperAdmin === true;
-  
-  // Check if user has permission - only call useCan when we have a resolved scope with valid organisationId
-  // If resolvedScope is null or has no organisationId, useCan will keep isLoading=true
-  // Pass appName to useCan so it can be passed to isPermitted for PORTAL/ADMIN special case
-  // Pass precomputed super admin status to avoid duplicate checks in useCan
-  // For super admins, we can skip the check entirely, but still call useCan with a dummy scope to avoid hook rule violations
-  const { can, isLoading: canIsLoading, error: canError } = useCan(
-    user?.id || '',
-    shouldSkipPermissionCheck ? { organisationId: undefined, appId: contextAppId || undefined, eventId: undefined } : scopeForPermissionCheck,
+
+  const { can, effectiveCan, canIsLoading, canError } = usePagePermissionCheck({
+    userId: user?.id ?? '',
+    scopeForPermissionCheck,
+    shouldSkipPermissionCheck,
+    contextAppId,
     permission,
     effectivePageId,
-    true, // Use cache
-    isSuperAdmin, // precomputedSuperAdmin - null if checking, true/false if checked
-    appName // Pass appName for PORTAL/ADMIN special case
-  );
-  
-  // Override can for super admins - they always have access
-  const effectiveCan = shouldSkipPermissionCheck ? true : can;
-  const effectiveIsLoading = shouldSkipPermissionCheck ? false : canIsLoading;
-  
-  
-  // Combine loading states - we're loading if scope resolution or permission check is loading
-  // For page-level permissions, PORTAL/ADMIN apps allow undefined organisationId
-  // Super admins bypass scope resolution - don't wait for it
-  const isLoading = shouldBypassScopeForSuperAdmin ? effectiveIsLoading : (scopeLoading || effectiveIsLoading);
-  const error = checkError || canError;
-
-  // Handle permission check completion
-  useEffect(() => {
-    if (!isLoading && !error) {
-      setHasChecked(true);
-      
-      if (!effectiveCan && onDenied) {
-        onDenied(pageName, operation);
-      }
-    } else if (error) {
-      setHasChecked(true);
-    }
-  }, [effectiveCan, isLoading, error, pageName, operation, onDenied]);
-
-  // Log page access attempt for audit
-  useEffect(() => {
-    if (auditLog && hasChecked && !isLoading) {
-      const rbacLogger = getRBACLogger();
-      rbacLogger.debug('Page access attempt:', {
-        pageName,
-        operation,
-        userId: user?.id,
-        scope: effectiveScope,
-        allowed: effectiveCan,
-        isSuperAdmin,
-        timestamp: new Date().toISOString()
-      });
-    }
-  }, [auditLog, hasChecked, isLoading, pageName, operation, user?.id, effectiveScope, effectiveCan, isSuperAdmin]);
-
-
-  // Handle strict mode violations
-  useEffect(() => {
-    if (strictMode && hasChecked && !isLoading && !effectiveCan && !shouldBypassScopeForSuperAdmin) {
-      const logger = getRBACLogger();
-      logger.error(`STRICT MODE VIOLATION: User attempted to access protected page without permission`, {
-        pageName,
-        operation,
-        permission: `${operation}:page.${pageName}`,
-        pageId: effectivePageId,
-        userId: user?.id,
-        scope: effectiveScope,
-        scopeValid: allowsOptionalContexts ? true : (effectiveScope !== null), // PORTAL/ADMIN allow scope without org/event
-        checkError,
-        canError,
-        isSuperAdmin,
-        timestamp: new Date().toISOString()
-      });
-    }
-  }, [strictMode, hasChecked, isLoading, effectiveCan, shouldBypassScopeForSuperAdmin, pageName, operation, effectivePageId, user?.id, effectiveScope, allowsOptionalContexts, checkError, canError, isSuperAdmin]);
-
-  // Calculate the actual render state - FIXED: Proper state calculation
-  // Add defensive checks to ensure we have valid state
-  // For page-level permissions, PORTAL/ADMIN apps allow scope without org/event
-  // Super admins bypass scope validation
-  const hasValidScopeForPagePermissions = shouldBypassScopeForSuperAdmin ? true : (allowsOptionalContexts ? true : (effectiveScope !== null));
-  const hasValidUser = user && user.id;
-  const isPermissionCheckComplete = hasChecked && !isLoading;
-  
-  const shouldShowAccessDenied = isPermissionCheckComplete && hasValidScopeForPagePermissions && hasValidUser && !checkError && !effectiveCan;
-  const shouldShowContent = isPermissionCheckComplete && hasValidScopeForPagePermissions && hasValidUser && !checkError && effectiveCan;
-
-  
-
-  // Debug logging for permission check state (only log when state actually changes, not on every render)
-  const lastLogStateRef = useRef<string>('');
-  useEffect(() => {
-    if (process.env.NODE_ENV === 'development') {
-      const currentState = JSON.stringify({
-        pageName,
-        userId: user?.id,
-        isSuperAdmin,
-        isLoading,
-        scopeLoading,
-        canIsLoading,
-        hasChecked,
-        hasValidUser,
-        effectiveCan
-      });
-      // Only log if state actually changed
-      if (currentState !== lastLogStateRef.current) {
-        lastLogStateRef.current = currentState;
-        logger.debug('Permission check state', {
-          pageName,
-          userId: user?.id,
-          isSuperAdmin,
-          isLoading,
-          scopeLoading,
-          canIsLoading,
-          hasChecked,
-          hasValidUser,
-          effectiveCan,
-          stableScope,
-          effectiveScope
-        });
-      }
-    }
-  }, [pageName, user?.id, isSuperAdmin, isLoading, scopeLoading, canIsLoading, hasChecked, hasValidUser, effectiveCan, stableScope, effectiveScope]);
-
-  // Show loading state - if we're still loading or don't have valid state
-  // For page-level permissions, we don't require organisation context, so only check for user and loading state
-  // Add timeout warning for debugging
-  useEffect(() => {
-    if (isLoading && isSuperAdmin === null && hasValidUser) {
-      const timeout = setTimeout(() => {
-        logger.warn('Permission check taking longer than expected', {
-          pageName,
-          userId: user?.id,
-          isSuperAdmin,
-          scopeLoading,
-          canIsLoading,
-          hasChecked,
-          stableScope,
-          effectiveScope,
-          appName
-        });
-      }, 5000);
-      return () => clearTimeout(timeout);
-    }
-  }, [isLoading, isSuperAdmin, hasValidUser, pageName, user?.id, scopeLoading, canIsLoading, hasChecked, stableScope, effectiveScope, appName]);
+    isSuperAdmin,
+    appName
+  });
 
-  // CRITICAL: Super admins bypass all checks - show content immediately once confirmed
-  // This must be checked AFTER all hooks are called to avoid React hooks rule violations
-  // Log super admin access only once when it's first confirmed (not on every render)
-  useEffect(() => {
-    if (isSuperAdmin === true && hasValidUser && !hasLoggedSuperAdminRef.current && process.env.NODE_ENV === 'development') {
-      hasLoggedSuperAdminRef.current = true;
-      logger.debug('Super admin access granted - bypassing all checks', {
-        pageName,
-        userId: user?.id,
-        operation
-      });
-    }
-    // Reset log flag if super admin status changes back to false/null
-    if (isSuperAdmin !== true) {
-      hasLoggedSuperAdminRef.current = false;
-    }
-  }, [isSuperAdmin, hasValidUser, pageName, user?.id, operation]);
-  
-  if (isSuperAdmin === true && hasValidUser) {
-    // Super admin confirmed - grant access immediately
-    return <>{children}</>;
-  }
+  const isLoading = shouldBypassScopeForSuperAdmin ? canIsLoading : scopeLoading || canIsLoading;
+  const error = scopeError ?? canError;
 
-  if (isLoading || !hasValidUser || !hasChecked || isSuperAdmin === null) {
-    return loading || <p>Checking permissions...</p>;
-  }
+  const [hasChecked, setHasChecked] = useState(false);
+  const hasValidUser = Boolean(user?.id);
 
-  // Show error state - only if we have an error AND no permission
-  if (checkError && !can) {
-    return fallback;
-  }
+  usePageAccessLogging({
+    setHasChecked,
+    hasChecked,
+    isLoading,
+    error,
+    effectiveCan,
+    pageName,
+    operation,
+    onDenied,
+    auditLog,
+    userId: user?.id,
+    effectiveScope,
+    isSuperAdmin,
+    strictMode,
+    shouldBypassScopeForSuperAdmin,
+    effectivePageId,
+    allowsOptionalContexts,
+    checkError: scopeError,
+    canError,
+    scopeLoading,
+    canIsLoading,
+    hasValidUser,
+    stableScope,
+    appName
+  });
 
-  // Show access denied - if permission check is complete and user doesn't have permission
-  if (shouldShowAccessDenied) {
-    return fallback;
-  }
+  const view = getPageGuardView({
+    isSuperAdmin,
+    hasValidUser,
+    isLoading,
+    hasChecked,
+    scopeError,
+    can,
+    effectiveCan,
+    effectiveScope,
+    allowsOptionalContexts,
+    shouldBypassScopeForSuperAdmin
+  });
 
-  // Show protected content - if permission check is complete and user has permission
-  if (shouldShowContent) {
-    return <>{children}</>;
+  switch (view) {
+    case 'super-admin':
+      return (
+        <PageGuardLayout printPageOrientation={printPageOrientation}>
+          {children}
+        </PageGuardLayout>
+      );
+    case 'loading':
+      return loading || <p>Checking permissions...</p>;
+    case 'denied':
+      return fallback;
+    case 'content':
+      return (
+        <PageGuardLayout printPageOrientation={printPageOrientation} withPrintPadding>
+          {children}
+        </PageGuardLayout>
+      );
+    default:
+      return fallback;
   }
+};
 
-  // Fallback: This should never happen, but just in case
-  return fallback;
+function PageGuardLayout({
+  children,
+  printPageOrientation,
+  withPrintPadding = false
+}: {
+  children: React.ReactNode;
+  printPageOrientation: 'portrait' | 'landscape';
+  withPrintPadding?: boolean;
+}) {
+  return (
+    <main
+      className={cn(
+        'px-4 w-[min(var(--app-width),100%)] mx-auto py-8',
+        withPrintPadding && 'print:p-0 print:pb-[40mm]',
+        printPageOrientation === 'landscape' && 'print-page-landscape',
+        printPageOrientation === 'portrait' && 'print-page-portrait'
+      )}
+    >
+      {children}
+    </main>
+  );
 }
 
-
-/**
- * Default loading component
- */
 function DefaultLoading() {
   return (
     <Alert role="status" aria-live="polite">
@@ -517,8 +323,7 @@ function DefaultLoading() {
       </AlertTitle>
     </Alert>
   );
-};
+}
 
-// Memoize component to prevent unnecessary re-renders when props haven't changed
 export const PagePermissionGuard = React.memo(PagePermissionGuardComponent);
 export default PagePermissionGuard;