@jmruthers/pace-core 0.2.4

package/src/rbac/components/PagePermissionGuard.tsx

@@ -0,0 +1,430 @@
+/**
+ * @file Page Permission Guard Component
+ * @package @jmruthers/pace-core
+ * @module RBAC/Components/PagePermissionGuard
+ * @since 2.0.0
+ *
+ * A component that enforces page-level permissions and prevents apps from bypassing
+ * permission checks. This is a critical security component that ensures all pages
+ * are properly protected.
+ *
+ * Features:
+ * - Page-level permission enforcement
+ * - Strict mode to prevent bypassing
+ * - Automatic audit logging
+ * - Integration with existing RBAC system
+ * - Clear error messages for unauthorized access
+ * - TypeScript support with strict typing
+ *
+ * @example
+ * ```tsx
+ * // Basic page protection
+ * <PagePermissionGuard
+ *   pageName="dashboard"
+ *   operation="read"
+ *   fallback={<AccessDeniedPage />}
+ * >
+ *   <DashboardPage />
+ * </PagePermissionGuard>
+ * 
+ * // Strict mode (prevents bypassing)
+ * <PagePermissionGuard
+ *   pageName="admin"
+ *   operation="read"
+ *   strictMode={true}
+ *   fallback={<AccessDeniedPage />}
+ * >
+ *   <AdminPage />
+ * </PagePermissionGuard>
+ * 
+ * // With custom fallback
+ * <PagePermissionGuard
+ *   pageName="settings"
+ *   operation="update"
+ *   fallback={<div>You don't have permission to access settings</div>}
+ * >
+ *   <SettingsPage />
+ * </PagePermissionGuard>
+ * ```
+ *
+ * @security
+ * - Enforces page-level permissions
+ * - Prevents apps from bypassing permission checks
+ * - Automatic audit logging for all page access attempts
+ * - Integration with existing RBAC system
+ * - Clear error messages for unauthorized access
+ *
+ * @performance
+ * - Optimized with useMemo and useCallback
+ * - Cached permission checks
+ * - Minimal re-renders
+ * - Efficient error handling
+ *
+ * @dependencies
+ * - React 18+ - Component framework
+ * - useCan hook - Permission checking
+ * - useUnifiedAuth - Authentication context
+ * - RBAC types - Type definitions
+ */
+
+import React, { useMemo, useCallback, useEffect, useState } from 'react';
+import { useCan } from '../hooks';
+import { useUnifiedAuth } from '../../providers/UnifiedAuthProvider';
+import { UUID, Permission, Scope } from '../types';
+import { createScopeFromEvent } from '../utils/eventContext';
+import { getCurrentAppName } from '../../utils/appNameResolver';
+
+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;
+}
+
+/**
+ * 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
+ */
+export function PagePermissionGuard({
+  pageName,
+  operation,
+  children,
+  fallback = <DefaultAccessDenied />,
+  strictMode = true,
+  auditLog = true,
+  pageId,
+  scope,
+  onDenied,
+  loading = <DefaultLoading />
+}: PagePermissionGuardProps) {
+  const { user, selectedOrganisationId, selectedEventId, supabase } = useUnifiedAuth();
+  const [hasChecked, setHasChecked] = useState(false);
+  const [checkError, setCheckError] = useState<Error | null>(null);
+  const [resolvedScope, setResolvedScope] = useState<Scope | null>(null);
+
+  // Resolve scope - either use provided scope or resolve from context
+  useEffect(() => {
+    const resolveScope = async () => {
+      if (scope) {
+        setResolvedScope(scope);
+        return;
+      }
+
+      // Get app ID from package.json or environment
+      let appId: string | undefined = undefined;
+      
+      // Try to resolve from database
+      if (supabase) {
+        const appName = getCurrentAppName();
+        if (appName) {
+          try {
+            console.log('[PagePermissionGuard] Resolving app name to ID:', appName);
+            const { data: app, error } = await supabase
+              .from('rbac_apps')
+              .select('id, name, is_active')
+              .eq('name', appName)
+              .eq('is_active', true)
+              .single() as { data: { id: string; name: string; is_active: boolean } | null; error: any };
+            
+            if (error) {
+              console.error('[PagePermissionGuard] Database error resolving app ID:', error);
+              // Check if app exists but is inactive
+              const { data: inactiveApp } = await supabase
+                .from('rbac_apps')
+                .select('id, name, is_active')
+                .eq('name', appName)
+                .single() as { data: { id: string; name: string; is_active: boolean } | null };
+              
+              if (inactiveApp) {
+                console.error(`[PagePermissionGuard] App "${appName}" exists but is inactive (is_active: ${inactiveApp.is_active})`);
+              } else {
+                console.error(`[PagePermissionGuard] App "${appName}" not found in rbac_apps table`);
+              }
+            } else if (app) {
+              appId = app.id;
+              console.log('[PagePermissionGuard] Successfully resolved app ID:', app.id);
+            } else {
+              console.error('[PagePermissionGuard] No app data returned for:', appName);
+            }
+          } catch (error) {
+            console.error('[PagePermissionGuard] Unexpected error resolving app ID:', error);
+          }
+        } else {
+          console.error('[PagePermissionGuard] No app name found. Make sure to call setRBACAppName() in your app setup.');
+        }
+      }
+
+      // If we have both organisation and event, use them directly
+      if (selectedOrganisationId && selectedEventId) {
+        if (!appId) {
+          // In test environments, allow undefined appId
+          if (process.env.NODE_ENV === 'test') {
+            console.warn('[PagePermissionGuard] App ID not resolved in test environment, proceeding without it');
+          } else {
+            console.error('[PagePermissionGuard] CRITICAL: App ID not resolved. Check console for details.');
+            setCheckError(new Error('App ID not resolved. Check console for database errors.'));
+            setResolvedScope(null); // Ensure we don't proceed with incomplete scope
+            return;
+          }
+        }
+        
+        // Validate that appId is a UUID, not an app name (only in production)
+        if (process.env.NODE_ENV === 'production' && appId) {
+          const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+          if (!uuidRegex.test(appId)) {
+            console.error('[PagePermissionGuard] CRITICAL: App ID is not a valid UUID:', appId);
+            setCheckError(new Error(`Invalid app ID format: ${appId}. Expected UUID.`));
+            setResolvedScope(null); // Ensure we don't proceed with invalid scope
+            return;
+          }
+        }
+        const resolvedScope = {
+          organisationId: selectedOrganisationId,
+          eventId: selectedEventId,
+          appId: appId
+        };
+        console.log('[PagePermissionGuard] Setting resolved scope:', resolvedScope);
+        setResolvedScope(resolvedScope);
+        return;
+      }
+
+      // If we only have organisation, use it
+      if (selectedOrganisationId) {
+        if (!appId) {
+          // In test environments, allow undefined appId
+          if (process.env.NODE_ENV === 'test') {
+            console.warn('[PagePermissionGuard] App ID not resolved in test environment, proceeding without it');
+          } else {
+            console.error('[PagePermissionGuard] CRITICAL: App ID not resolved. Check console for details.');
+            setCheckError(new Error('App ID not resolved. Check console for database errors.'));
+            setResolvedScope(null); // Ensure we don't proceed with incomplete scope
+            return;
+          }
+        }
+        
+        // Validate that appId is a UUID, not an app name (only in production)
+        if (process.env.NODE_ENV === 'production' && appId) {
+          const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+          if (!uuidRegex.test(appId)) {
+            console.error('[PagePermissionGuard] CRITICAL: App ID is not a valid UUID:', appId);
+            setCheckError(new Error(`Invalid app ID format: ${appId}. Expected UUID.`));
+            setResolvedScope(null); // Ensure we don't proceed with invalid scope
+            return;
+          }
+        }
+        const resolvedScope = {
+          organisationId: selectedOrganisationId,
+          eventId: selectedEventId || undefined,
+          appId: appId
+        };
+        console.log('[PagePermissionGuard] Setting resolved scope (org only):', resolvedScope);
+        setResolvedScope(resolvedScope);
+        return;
+      }
+
+      // If we only have event, resolve organisation from event
+      if (selectedEventId && supabase) {
+        try {
+          const eventScope = await createScopeFromEvent(supabase, selectedEventId);
+          if (!eventScope) {
+            setCheckError(new Error('Could not resolve organization from event context'));
+            setResolvedScope(null); // Ensure we don't proceed with incomplete scope
+            return;
+          }
+          // Preserve the resolved app ID
+          setResolvedScope({
+            ...eventScope,
+            appId: appId || eventScope.appId
+          });
+        } catch (error) {
+          setCheckError(error as Error);
+          setResolvedScope(null); // Ensure we don't proceed with incomplete scope
+        }
+        return;
+      }
+
+      // No context available
+      setCheckError(new Error('Either organisation context or event context is required for page permission checking'));
+      setResolvedScope(null); // Ensure we don't proceed with incomplete scope
+    };
+
+    resolveScope();
+  }, [scope, selectedOrganisationId, selectedEventId, supabase]);
+
+  // Determine the page ID for permission checking
+  const effectivePageId = useMemo((): string => {
+    return pageId || pageName;
+  }, [pageId, pageName]);
+
+  // Build the permission string
+  const permission = useMemo((): Permission => {
+    return `${operation}:page.${pageName}` as Permission;
+  }, [operation, pageName]);
+
+  // Check if user has permission - only call useCan when we have a resolved scope
+  // If resolvedScope is null, we're still resolving, so show loading state
+  console.log('[PagePermissionGuard] Calling useCan with scope:', resolvedScope);
+  console.log('[PagePermissionGuard] resolvedScope:', resolvedScope);
+  console.log('[PagePermissionGuard] selectedEventId:', selectedEventId);
+  
+  console.log('[PagePermissionGuard] About to call useCan with:', {
+    userId: user?.id || '',
+    scope: resolvedScope || { organisationId: '', appId: '', eventId: selectedEventId || undefined },
+    permission,
+    pageId: effectivePageId,
+    useCache: true
+  });
+  
+  const { can, isLoading: canIsLoading, error: canError } = useCan(
+    user?.id || '',
+    resolvedScope || { organisationId: '', appId: '', eventId: selectedEventId || undefined },
+    permission,
+    effectivePageId,
+    true // Use cache
+  );
+  
+  console.log('[PagePermissionGuard] useCan returned:', { can, canIsLoading, canError });
+  
+  // Combine loading states - we're loading if either scope is resolving OR permission check is loading
+  const isLoading = !resolvedScope || canIsLoading;
+  const error = checkError || canError;
+  
+  console.log('[PagePermissionGuard] Combined state:', { 
+    can, 
+    isLoading, 
+    canIsLoading,
+    resolvedScopeExists: !!resolvedScope,
+    error: error?.message 
+  });
+
+  // Handle permission check completion
+  useEffect(() => {
+    if (!isLoading && !error) {
+      setHasChecked(true);
+      setCheckError(null);
+      
+      if (!can && onDenied) {
+        onDenied(pageName, operation);
+      }
+    } else if (error) {
+      setCheckError(error);
+      setHasChecked(true);
+    }
+  }, [can, isLoading, error, pageName, operation, onDenied]);
+
+  // Log page access attempt for audit
+  useEffect(() => {
+    if (auditLog && hasChecked && !isLoading) {
+      console.log(`[PagePermissionGuard] Page access attempt:`, {
+        pageName,
+        operation,
+        userId: user?.id,
+        scope: resolvedScope,
+        allowed: can,
+        timestamp: new Date().toISOString()
+      });
+    }
+  }, [auditLog, hasChecked, isLoading, pageName, operation, user?.id, resolvedScope, can]);
+
+  // Handle strict mode violations
+  useEffect(() => {
+    if (strictMode && hasChecked && !isLoading && !can) {
+      console.error(`[PagePermissionGuard] STRICT MODE VIOLATION: User attempted to access protected page without permission`, {
+        pageName,
+        operation,
+        userId: user?.id,
+        scope: resolvedScope,
+        timestamp: new Date().toISOString()
+      });
+    }
+  }, [strictMode, hasChecked, isLoading, can, pageName, operation, user?.id, resolvedScope]);
+
+  // Show loading state
+  if (isLoading || !resolvedScope || !hasChecked) {
+    return <>{loading}</>;
+  }
+
+  // Show error state
+  if (checkError) {
+    console.error(`[PagePermissionGuard] Permission check failed for page ${pageName}:`, checkError);
+    return <>{fallback}</>;
+  }
+
+  // Show access denied
+  if (!can) {
+    return <>{fallback}</>;
+  }
+
+  // Show protected content
+  return <>{children}</>;
+}
+
+/**
+ * Default access denied component
+ */
+function DefaultAccessDenied() {
+  return (
+    <div className="flex flex-col items-center justify-center min-h-[200px] p-8 text-center">
+      <div className="mb-4">
+        <svg className="w-16 h-16 text-acc-500 mx-auto" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L3.732 16.5c-.77.833.192 2.5 1.732 2.5z" />
+        </svg>
+      </div>
+      <h2 className="text-xl font-semibold text-sec-900 mb-2">Access Denied</h2>
+      <p className="text-sec-600 mb-4">You don't have permission to access this page.</p>
+      <button 
+        onClick={() => window.history.back()}
+        className="px-4 py-2 bg-main-600 text-main-50 rounded-md hover:bg-main-700 transition-colors"
+      >
+        Go Back
+      </button>
+    </div>
+  );
+}
+
+/**
+ * Default loading component
+ */
+function DefaultLoading() {
+  return (
+    <div className="flex items-center justify-center min-h-[200px] p-8">
+      <div className="flex items-center space-x-2">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-main-600"></div>
+        <span className="text-sec-600">Checking permissions...</span>
+      </div>
+    </div>
+  );
+}
+
+export default PagePermissionGuard;

package/src/rbac/components/PagePermissionProvider.tsx

@@ -0,0 +1,274 @@
+/**
+ * @file Page Permission Provider Component
+ * @package @jmruthers/pace-core
+ * @module RBAC/Components/PagePermissionProvider
+ * @since 2.0.0
+ *
+ * A context provider that manages page-level permissions across the entire application.
+ * This component ensures that all pages are properly protected and provides centralized
+ * page permission management.
+ *
+ * Features:
+ * - App-wide page permission management
+ * - Strict mode to prevent bypassing
+ * - Automatic audit logging
+ * - Integration with existing RBAC system
+ * - Page permission tracking
+ * - Error handling and recovery
+ *
+ * @example
+ * ```tsx
+ * // Basic app setup with page permissions
+ * <PagePermissionProvider strictMode={true} auditLog={true}>
+ *   <App />
+ * </PagePermissionProvider>
+ * 
+ * // With custom configuration
+ * <PagePermissionProvider
+ *   strictMode={true}
+ *   auditLog={true}
+ *   onPageAccess={(pageName, operation, allowed) => {
+ *     console.log(`Page access: ${pageName} ${operation} - ${allowed ? 'allowed' : 'denied'}`);
+ *   }}
+ * >
+ *   <App />
+ * </PagePermissionProvider>
+ * ```
+ *
+ * @security
+ * - Enforces page-level permissions across the app
+ * - Prevents apps from bypassing permission checks
+ * - Automatic audit logging for all page access attempts
+ * - Integration with existing RBAC system
+ * - Page permission tracking and monitoring
+ *
+ * @performance
+ * - Optimized with useMemo and useCallback
+ * - Efficient context updates
+ * - Minimal re-renders
+ * - Cached permission checks
+ *
+ * @dependencies
+ * - React 18+ - Context and hooks
+ * - useUnifiedAuth - Authentication context
+ * - RBAC types - Type definitions
+ */
+
+import React, { createContext, useContext, useState, useCallback, useMemo, useEffect } from 'react';
+import { useUnifiedAuth } from '../../providers/UnifiedAuthProvider';
+import { UUID, Scope, Permission } from '../types';
+
+export interface PagePermissionContextType {
+  /** Check if user has permission for a page */
+  hasPagePermission: (pageName: string, operation: string, pageId?: string, scope?: Scope) => boolean;
+  
+  /** Get all page permissions for current user */
+  getPagePermissions: () => Record<string, string[]>;
+  
+  /** Check if page permission checking is enabled */
+  isEnabled: boolean;
+  
+  /** Check if strict mode is enabled */
+  isStrictMode: boolean;
+  
+  /** Check if audit logging is enabled */
+  isAuditLogEnabled: boolean;
+  
+  /** Get page access history */
+  getPageAccessHistory: () => PageAccessRecord[];
+  
+  /** Clear page access history */
+  clearPageAccessHistory: () => void;
+}
+
+export interface PageAccessRecord {
+  pageName: string;
+  operation: string;
+  userId: UUID;
+  scope: Scope;
+  allowed: boolean;
+  timestamp: string;
+  pageId?: string;
+}
+
+export interface PagePermissionProviderProps {
+  /** Child components */
+  children: React.ReactNode;
+  
+  /** Enable strict mode to prevent bypassing (default: true) */
+  strictMode?: boolean;
+  
+  /** Enable audit logging (default: true) */
+  auditLog?: boolean;
+  
+  /** Callback when page access is attempted */
+  onPageAccess?: (pageName: string, operation: string, allowed: boolean, record: PageAccessRecord) => void;
+  
+  /** Callback when strict mode violation occurs */
+  onStrictModeViolation?: (pageName: string, operation: string, record: PageAccessRecord) => void;
+  
+  /** Maximum number of access records to keep in history */
+  maxHistorySize?: number;
+}
+
+const PagePermissionContext = createContext<PagePermissionContextType | null>(null);
+
+/**
+ * PagePermissionProvider - Manages page-level permissions across the app
+ * 
+ * This provider ensures that all pages are properly protected and provides
+ * centralized page permission management with strict enforcement.
+ * 
+ * @param props - Provider props
+ * @returns React element with page permission context
+ */
+export function PagePermissionProvider({
+  children,
+  strictMode = true,
+  auditLog = true,
+  onPageAccess,
+  onStrictModeViolation,
+  maxHistorySize = 1000
+}: PagePermissionProviderProps) {
+  const { user, selectedOrganisationId, selectedEventId } = useUnifiedAuth();
+  const [pageAccessHistory, setPageAccessHistory] = useState<PageAccessRecord[]>([]);
+  const [isEnabled, setIsEnabled] = useState(true);
+
+  // Get current scope
+  const currentScope = useMemo((): Scope | null => {
+    if (!selectedOrganisationId) return null;
+    
+    return {
+      organisationId: selectedOrganisationId,
+      eventId: selectedEventId || undefined,
+      appId: undefined
+    };
+  }, [selectedOrganisationId, selectedEventId]);
+
+  // Check if user has permission for a page
+  const hasPagePermission = useCallback((
+    pageName: string, 
+    operation: string, 
+    pageId?: string, 
+    scope?: Scope
+  ): boolean => {
+    if (!isEnabled) return true;
+    if (!user?.id) return false;
+    
+    const effectiveScope = scope || currentScope;
+    if (!effectiveScope) return false;
+    
+    // Use the existing RBAC system to check permissions
+    // This is a synchronous check for the context - actual permission checking
+    // happens in the PagePermissionGuard component using useCan hook
+    const permission = `${operation}:page.${pageName}` as Permission;
+    
+    // Return false by default (secure by default) - let individual PagePermissionGuard
+    // components handle the actual permission checking asynchronously
+    // This context is mainly for tracking and audit purposes
+    return false;
+  }, [isEnabled, user?.id, currentScope]);
+
+  // Get all page permissions for current user
+  const getPagePermissions = useCallback((): Record<string, string[]> => {
+    if (!isEnabled || !user?.id) return {};
+    
+    // For now, return empty object - this will be enhanced with actual permission checking
+    // when we integrate with the existing RBAC system
+    return {};
+  }, [isEnabled, user?.id]);
+
+  // Get page access history
+  const getPageAccessHistory = useCallback((): PageAccessRecord[] => {
+    return [...pageAccessHistory];
+  }, [pageAccessHistory]);
+
+  // Clear page access history
+  const clearPageAccessHistory = useCallback(() => {
+    setPageAccessHistory([]);
+  }, []);
+
+  // Record page access attempt
+  const recordPageAccess = useCallback((
+    pageName: string,
+    operation: string,
+    allowed: boolean,
+    pageId?: string,
+    scope?: Scope
+  ) => {
+    if (!auditLog || !user?.id) return;
+    
+    const record: PageAccessRecord = {
+      pageName,
+      operation,
+      userId: user.id,
+      scope: scope || currentScope || { organisationId: '' },
+      allowed,
+      timestamp: new Date().toISOString(),
+      pageId
+    };
+    
+    setPageAccessHistory(prev => {
+      const newHistory = [record, ...prev];
+      return newHistory.slice(0, maxHistorySize);
+    });
+    
+    if (onPageAccess) {
+      onPageAccess(pageName, operation, allowed, record);
+    }
+    
+    if (strictMode && !allowed && onStrictModeViolation) {
+      onStrictModeViolation(pageName, operation, record);
+    }
+  }, [auditLog, user?.id, currentScope, maxHistorySize, onPageAccess, onStrictModeViolation, strictMode]);
+
+  // Context value
+  const contextValue = useMemo((): PagePermissionContextType => ({
+    hasPagePermission,
+    getPagePermissions,
+    isEnabled,
+    isStrictMode: strictMode,
+    isAuditLogEnabled: auditLog,
+    getPageAccessHistory,
+    clearPageAccessHistory
+  }), [
+    hasPagePermission,
+    getPagePermissions,
+    isEnabled,
+    strictMode,
+    auditLog,
+    getPageAccessHistory,
+    clearPageAccessHistory
+  ]);
+
+  // Log strict mode violations
+  useEffect(() => {
+    if (strictMode && auditLog) {
+      console.log(`[PagePermissionProvider] Strict mode enabled - all page access attempts will be logged and enforced`);
+    }
+  }, [strictMode, auditLog]);
+
+  return (
+    <PagePermissionContext.Provider value={contextValue}>
+      {children}
+    </PagePermissionContext.Provider>
+  );
+}
+
+/**
+ * Hook to use page permission context
+ * 
+ * @returns Page permission context
+ * @throws Error if used outside of PagePermissionProvider
+ */
+export function usePagePermissions(): PagePermissionContextType {
+  const context = useContext(PagePermissionContext);
+  
+  if (!context) {
+    throw new Error('usePagePermissions must be used within a PagePermissionProvider');
+  }
+  
+  return context;
+}
+
+export default PagePermissionProvider;