@jmruthers/pace-core 0.6.9 → 0.6.11

package/src/rbac/components/PagePermissionGuard.test.tsx

@@ -0,0 +1,1430 @@
+/**
+ * @file PagePermissionGuard Component Tests
+ * @package @jmruthers/pace-core
+ * @module RBAC/Components/PagePermissionGuard
+ * @since 2.0.0
+ * 
+ * Comprehensive tests for the PagePermissionGuard component covering all critical functionality.
+ */
+
+import { render, screen, waitFor } from '@testing-library/react';
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { ReactNode } from 'react';
+import { PagePermissionGuard } from './PagePermissionGuard';
+import { useUnifiedAuth } from '../../../providers/services/UnifiedAuthProvider';
+
+// Following testing standards: use timeout parameter to prevent hanging
+const TEST_TIMEOUT = 10000; // 10 seconds per test
+
+// Mock the RBAC hooks - mock individual file since barrel was removed
+// CRITICAL: Use hoisted mock so vi.mocked() works correctly
+const mockUseCanFn = vi.hoisted(() => vi.fn());
+vi.mock('../hooks/usePermissions', () => ({
+  useCan: mockUseCanFn
+}));
+
+// Mock the auth provider
+const mockUseUnifiedAuthFn = vi.fn();
+vi.mock('../../providers/services/UnifiedAuthProvider', () => ({
+  useUnifiedAuth: () => mockUseUnifiedAuthFn(),
+  UnifiedAuthProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+}));
+
+// Mock the event context utility
+vi.mock('../../utils/eventContext', () => ({
+  createScopeFromEvent: vi.fn()
+}));
+
+// Mock useResolvedScope hook
+vi.mock('../hooks/useResolvedScope', () => ({
+  useResolvedScope: vi.fn()
+}));
+
+// Mock the app name resolver
+vi.mock('../../utils/app/appNameResolver', () => ({
+  getCurrentAppName: vi.fn()
+}));
+
+// Mock the RBAC API for super admin checks
+vi.mock('../api', async () => {
+  const actual = await vi.importActual('../api');
+  return {
+    ...actual,
+    isSuperAdmin: vi.fn().mockResolvedValue(false) // Default to not super admin
+  };
+});
+
+import { useResolvedScope } from '../hooks/useResolvedScope';
+import { getCurrentAppName } from '../../utils/app/appNameResolver';
+import { isSuperAdmin } from '../api';
+
+// Mock data
+const mockUser = {
+  id: 'user-123',
+  email: 'test@example.com'
+};
+
+const mockScope = {
+  organisationId: 'org-123',
+  eventId: 'event-123',
+  appId: 'app-123'
+};
+
+const mockPageName = 'dashboard';
+const mockOperation = 'read' as const;
+
+// Test component
+const TestComponent = ({ children }: { children: ReactNode }) => (
+  <main data-testid="test-component">{children}</main>
+);
+
+const TestFallback = () => (
+  <main data-testid="test-fallback">Access Denied</main>
+);
+
+const TestLoading = () => (
+  <main data-testid="test-loading">Loading...</main>
+);
+
+describe('PagePermissionGuard Component', () => {
+  const mockGetCurrentAppName = vi.mocked(getCurrentAppName);
+  const mockUseResolvedScope = vi.mocked(useResolvedScope);
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    
+    // Default mock implementations
+    // For org-required apps: selectedOrganisation is available
+    // For event-required apps: selectedOrganisation is null, org derived from event
+    mockUseUnifiedAuthFn.mockReturnValue({
+      user: mockUser,
+      selectedOrganisation: { id: 'org-123' }, // Available for org-required apps, null for event-required
+      selectedEvent: { event_id: 'event-123', organisation_id: 'org-123' },
+      appId: 'app-123', // Required for scope resolution
+      appName: 'test-app',
+      appConfig: { requires_event: false }, // Default to org-required for tests
+      supabase: {
+        from: vi.fn().mockReturnValue({
+          select: vi.fn().mockReturnValue({
+            eq: vi.fn().mockReturnValue({
+              eq: vi.fn().mockReturnValue({
+                single: vi.fn().mockResolvedValue({
+                  data: { id: 'app-123', name: 'test-app', is_active: true, requires_event: false },
+                  error: null
+                })
+              })
+            })
+          })
+        })
+      } as any
+    });
+    
+    mockGetCurrentAppName.mockReturnValue('test-app');
+    
+    // Mock useResolvedScope to return resolved scope immediately
+    mockUseResolvedScope.mockReturnValue({
+      resolvedScope: {
+        organisationId: 'org-123',
+        eventId: 'event-123',
+        appId: 'app-123'
+      },
+      isLoading: false,
+      error: null
+    });
+    
+    mockUseCanFn.mockReturnValue({
+      can: true,
+      isLoading: false,
+      error: null
+    });
+  });
+
+  describe('Rendering', () => {
+    it('renders children when permission is granted', async () => {
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+        expect(screen.getByText('Protected Page')).toBeInTheDocument();
+      }, { interval: 10 });
+    });
+
+    it('renders fallback when permission is denied and shows loading state', async () => {
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: false,
+        error: null
+      });
+
+      const { rerender } = render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+      await waitFor(() => {
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+        expect(screen.queryByTestId('test-component')).not.toBeInTheDocument();
+      }, { interval: 10 });
+
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: true,
+        error: null
+      });
+      rerender(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          loading={<TestLoading />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+      expect(screen.getByTestId('test-loading')).toBeInTheDocument();
+      expect(screen.queryByTestId('test-component')).not.toBeInTheDocument();
+    });
+
+    it('uses default fallback and loading when none provided', async () => {
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: false,
+        error: null
+      });
+
+      const { rerender } = render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+      await waitFor(() => {
+        expect(screen.getByText('Access Denied')).toBeInTheDocument();
+        expect(screen.getByText('You don\'t have permission to access this page.')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
+
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: true,
+        error: null
+      });
+      rerender(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+      expect(screen.getByText('Checking permissions...')).toBeInTheDocument();
+    });
+  });
+
+  describe('Permission Checking', () => {
+    it('builds correct permission string, uses custom pageId, handles different operations, and handles errors gracefully', async () => {
+      const customPageId = 'custom-dashboard';
+      
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      const { rerender } = render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      // Check that useCan was called with correct parameters
+      // precomputedSuperAdmin can be null (checking), true/false (checked), or undefined
+      expect(mockUseCanFn).toHaveBeenCalled();
+      const callArgs = mockUseCanFn.mock.calls[0];
+      expect(callArgs[0]).toBe('user-123');
+      expect(callArgs[1]).toEqual({
+        organisationId: 'org-123',
+        eventId: 'event-123',
+        appId: 'app-123'
+      });
+      expect(callArgs[2]).toBe('read:page.dashboard');
+      expect(callArgs[3]).toBe('dashboard');
+      expect(callArgs[4]).toBe(true);
+      // precomputedSuperAdmin can be null, true, false, or undefined
+      expect(callArgs[5] === null || callArgs[5] === true || callArgs[5] === false || callArgs[5] === undefined).toBe(true);
+      expect(callArgs[6]).toBe('test-app');
+
+      vi.clearAllMocks();
+      rerender(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          pageId={customPageId}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+      
+      // Check that useCan was called with correct parameters for custom pageId
+      expect(mockUseCanFn).toHaveBeenCalled();
+      const customPageIdCallArgs = mockUseCanFn.mock.calls[0];
+      expect(customPageIdCallArgs[0]).toBe('user-123');
+      expect(customPageIdCallArgs[1]).toEqual({
+        organisationId: 'org-123',
+        eventId: 'event-123',
+        appId: 'app-123'
+      });
+      expect(customPageIdCallArgs[2]).toBe('read:page.dashboard');
+      expect(customPageIdCallArgs[3]).toBe(customPageId);
+      expect(customPageIdCallArgs[4]).toBe(true);
+      // precomputedSuperAdmin can be null, true, false, or undefined
+      expect(customPageIdCallArgs[5] === null || customPageIdCallArgs[5] === true || customPageIdCallArgs[5] === false || customPageIdCallArgs[5] === undefined).toBe(true);
+      expect(customPageIdCallArgs[6]).toBe('test-app');
+
+      const operations = ['create', 'update'] as const;
+      for (const operation of operations) {
+        vi.clearAllMocks();
+        mockUseCanFn.mockReturnValue({
+          can: true,
+          isLoading: false,
+          error: null
+        });
+        rerender(
+          <PagePermissionGuard
+            pageName={mockPageName}
+            operation={operation}
+          >
+            <TestComponent>Protected Page</TestComponent>
+          </PagePermissionGuard>
+        );
+        await waitFor(() => {
+          expect(screen.getByTestId('test-component')).toBeInTheDocument();
+        }, { interval: 10 });
+        
+        // Check that useCan was called with correct parameters for operation
+        expect(mockUseCanFn).toHaveBeenCalled();
+        const operationCallArgs = mockUseCanFn.mock.calls[0];
+        expect(operationCallArgs[0]).toBe('user-123');
+        expect(operationCallArgs[1]).toEqual({
+          organisationId: 'org-123',
+          eventId: 'event-123',
+          appId: 'app-123'
+        });
+        expect(operationCallArgs[2]).toBe(`${operation}:page.dashboard`);
+        expect(operationCallArgs[3]).toBe('dashboard');
+        expect(operationCallArgs[4]).toBe(true);
+        // precomputedSuperAdmin can be null, true, false, or undefined
+        expect(operationCallArgs[5] === null || operationCallArgs[5] === true || operationCallArgs[5] === false || operationCallArgs[5] === undefined).toBe(true);
+        expect(operationCallArgs[6]).toBe('test-app');
+      }
+
+      const error = new Error('Permission check failed');
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: false,
+        error
+      });
+      rerender(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+      await waitFor(() => {
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
+    });
+  });
+
+  describe('App ID Resolution', () => {
+    it('resolves app ID from database', async () => {
+      // useResolvedScope will call getCurrentAppName to resolve app config
+      // The component uses appId from context when available
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
+
+      // useResolvedScope calls getCurrentAppName to resolve app config
+      // The component uses contextAppId when available, but useResolvedScope still needs app name
+      // So getCurrentAppName may be called by useResolvedScope
+      // The important thing is that the component works correctly
+      expect(screen.getByTestId('test-component')).toBeInTheDocument();
+    });
+
+    it('handles app resolution errors in test environment', async () => {
+      mockGetCurrentAppName.mockReturnValue(null);
+      
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      // Set NODE_ENV to test
+      const originalEnv = process.env.NODE_ENV;
+      process.env.NODE_ENV = 'test';
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          scope={mockScope}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      // Restore NODE_ENV
+      process.env.NODE_ENV = originalEnv;
+    });
+
+    it('handles app resolution errors in production', async () => {
+      mockGetCurrentAppName.mockReturnValue(null);
+      
+      // When app resolution fails, useResolvedScope should return null scope or error
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: null,
+        isLoading: true, // Still loading when app resolution fails
+        error: null
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: true,
+        error: null
+      });
+      
+      // Mock import.meta.env.MODE for production using vi.stubEnv
+      vi.stubEnv('MODE', 'production');
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      // Component should show loading when scope is still resolving
+      expect(screen.getByText('Checking permissions...')).toBeInTheDocument();
+
+      // Restore environment
+      vi.unstubAllEnvs();
+    });
+
+    it('validates app ID format in production', async () => {
+      mockGetCurrentAppName.mockReturnValue('test-app');
+      
+      // Mock database returning invalid app ID
+      // In test mode, validation is skipped, so component should work normally
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: { id: 'org-123' },
+        selectedEvent: { event_id: 'event-123' },
+        appId: 'app-123',
+        supabase: {
+          from: vi.fn().mockReturnValue({
+            select: vi.fn().mockReturnValue({
+              eq: vi.fn().mockReturnValue({
+                eq: vi.fn().mockReturnValue({
+                  single: vi.fn().mockResolvedValue({
+                    data: { id: 'invalid-app-id', name: 'test-app', is_active: true },
+                    error: null
+                  })
+                })
+              })
+            })
+          })
+        } as any
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      // In test mode, validation is skipped, so component should render normally
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
+    });
+  });
+
+  describe('Scope Resolution', () => {
+    it('uses provided scope when available', async () => {
+      const customScope = {
+        organisationId: 'custom-org',
+        eventId: 'custom-event',
+        appId: 'custom-app'
+      };
+
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          scope={customScope}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      expect(mockUseCanFn).toHaveBeenCalledWith(
+        'user-123',
+        customScope,
+        'read:page.dashboard',
+        'dashboard',
+        true,
+        null, // precomputedSuperAdmin
+        'test-app'
+      );
+    });
+
+    it('resolves scope from organisation and event context (org-required app)', async () => {
+      // For org-required apps, organisation is primary, event is optional
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      expect(mockUseCanFn).toHaveBeenCalledWith(
+        'user-123',
+        {
+          organisationId: 'org-123',
+          eventId: 'event-123',
+          appId: 'app-123'
+        },
+        'read:page.dashboard',
+        'dashboard',
+        true,
+        null, // precomputedSuperAdmin
+        'test-app'
+      );
+    });
+
+    it('resolves scope from organisation only (org-required app)', async () => {
+      // For org-required apps, organisation is primary context, event is optional
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: { id: 'org-123' },
+        selectedEvent: null,
+        appId: 'app-123',
+        appName: 'test-app',
+        supabase: {
+          from: vi.fn().mockReturnValue({
+            select: vi.fn().mockReturnValue({
+              eq: vi.fn().mockReturnValue({
+                eq: vi.fn().mockReturnValue({
+                  single: vi.fn().mockResolvedValue({
+                    data: { id: 'app-123', name: 'test-app', is_active: true },
+                    error: null
+                  })
+                })
+              })
+            })
+          })
+        } as any
+      });
+
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: {
+          organisationId: 'org-123',
+          eventId: undefined,
+          appId: 'app-123'
+        },
+        isLoading: false,
+        error: null
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      expect(mockUseCanFn).toHaveBeenCalledWith(
+        'user-123',
+        {
+          organisationId: 'org-123',
+          eventId: undefined,
+          appId: 'app-123'
+        },
+        'read:page.dashboard',
+        'dashboard',
+        true,
+        null, // precomputedSuperAdmin
+        'test-app'
+      );
+    });
+
+    it('resolves scope from event context when organisation not available (event-required app)', async () => {
+      // For event-required apps, selectedOrganisation is null, org is derived from event
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: null, // Not available for event-required apps
+        selectedEvent: { event_id: 'event-123' },
+        appId: 'app-123',
+        appName: 'test-app',
+        supabase: {
+          from: vi.fn().mockReturnValue({
+            select: vi.fn().mockReturnValue({
+              eq: vi.fn().mockReturnValue({
+                eq: vi.fn().mockReturnValue({
+                  single: vi.fn().mockResolvedValue({
+                    data: { id: 'app-123', name: 'test-app', is_active: true },
+                    error: null
+                  })
+                })
+              })
+            })
+          })
+        } as any
+      });
+
+      // Mock useResolvedScope to return scope resolved from event
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: {
+          organisationId: 'resolved-org',
+          eventId: 'event-123',
+          appId: 'app-123'
+        },
+        isLoading: false,
+        error: null
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      expect(mockUseCanFn).toHaveBeenCalledWith(
+        'user-123',
+        {
+          organisationId: 'resolved-org',
+          eventId: 'event-123',
+          appId: 'app-123' // Component uses appId from context, not from resolved scope
+        },
+        'read:page.dashboard',
+        'dashboard',
+        true,
+        null, // precomputedSuperAdmin
+        'test-app'
+      );
+    });
+
+    it('handles scope resolution errors', async () => {
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: null,
+        selectedEvent: { event_id: 'event-123' },
+        appId: undefined, // Not available for error case
+        appName: 'test-app',
+        supabase: {} as any
+      });
+
+      const error = new Error('Could not resolve organisation from event');
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: null,
+        isLoading: false,
+        error
+      });
+
+      // Mock useCan to return quickly so component can process error
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      // Component shows fallback when there's a scope error
+      await waitFor(() => {
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
+    });
+
+    it('handles missing context gracefully', async () => {
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: null,
+        selectedEvent: null,
+        appId: undefined,
+        appName: 'test-app',
+        supabase: null
+      });
+
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: null,
+        isLoading: true,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      expect(screen.getByText('Checking permissions...')).toBeInTheDocument();
+    });
+  });
+
+  describe('Security Features', () => {
+    it('invokes onDenied callback when strict mode blocks access', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const onDenied = vi.fn();
+
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          strictMode={true}
+          fallback={<TestFallback />}
+          onDenied={onDenied}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      expect(onDenied).toHaveBeenCalledWith(mockPageName, mockOperation);
+
+      consoleSpy.mockRestore();
+    });
+
+    it('does not call onDenied multiple times when audit logging rerenders', async () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const onDenied = vi.fn();
+
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: false,
+        error: null
+      });
+
+      const { rerender } = render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          auditLog={true}
+          fallback={<TestFallback />}
+          onDenied={onDenied}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      rerender(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          auditLog={true}
+          fallback={<TestFallback />}
+          onDenied={onDenied}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(onDenied).toHaveBeenCalledTimes(1);
+      }, { interval: 10 });
+
+      consoleSpy.mockRestore();
+    });
+
+    it('calls onDenied callback when access is denied', async () => {
+      const onDeniedSpy = vi.fn();
+      
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          onDenied={onDeniedSpy}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
+
+      expect(onDeniedSpy).toHaveBeenCalledWith(mockPageName, mockOperation);
+    });
+
+    it('does not call onDenied when access is granted', async () => {
+      const onDeniedSpy = vi.fn();
+      
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          onDenied={onDeniedSpy}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      expect(onDeniedSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Configuration Options', () => {
+    it('respects strictMode setting', async () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          strictMode={false}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
+
+      expect(consoleSpy).not.toHaveBeenCalledWith(
+        expect.stringContaining('STRICT MODE VIOLATION')
+      );
+
+      consoleSpy.mockRestore();
+    });
+
+    it('respects auditLog setting', async () => {
+      const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          auditLog={false}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
+
+      expect(consoleSpy).not.toHaveBeenCalledWith(
+        expect.stringContaining('Page access attempt')
+      );
+
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('handles missing user gracefully', async () => {
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: null,
+        selectedOrganisation: null, // No org when user is missing
+        selectedEvent: null, // No event when user is missing
+        appId: undefined,
+        appName: 'test-app',
+        supabase: null
+      });
+
+      // When user is missing, scope resolution should return null
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: null,
+        isLoading: false,
+        error: null
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: false,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      // Component shows loading when user is missing (no valid user to check permissions for)
+      expect(screen.getByText('Checking permissions...')).toBeInTheDocument();
+    });
+
+    it('handles database errors during app resolution', async () => {
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: { id: 'org-123' },
+        selectedEvent: { event_id: 'event-123' },
+        appId: undefined, // Not resolved due to database error
+        appName: 'test-app',
+        supabase: {
+          from: vi.fn().mockReturnValue({
+            select: vi.fn().mockReturnValue({
+              eq: vi.fn().mockReturnValue({
+                eq: vi.fn().mockReturnValue({
+                  single: vi.fn().mockResolvedValue({
+                    data: null,
+                    error: { message: 'Database error' }
+                  })
+                })
+              })
+            })
+          })
+        } as any
+      });
+
+      // When database error occurs, useResolvedScope might still return a scope (with appId undefined)
+      // or might return null. For PORTAL app, it can work without appId
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: {
+          organisationId: 'org-123',
+          eventId: 'event-123',
+          appId: undefined // App resolution failed
+        },
+        isLoading: false,
+        error: null
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: true, // Permission check can still succeed without appId for page permissions
+        isLoading: false,
+        error: null
+      });
+
+      // Set NODE_ENV to production
+      const originalEnv = process.env.NODE_ENV;
+      process.env.NODE_ENV = 'production';
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+          fallback={<TestFallback />}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      // Component can still work if scope is resolved (even without appId for page permissions)
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
+
+      // Restore NODE_ENV
+      process.env.NODE_ENV = originalEnv;
+    });
+  });
+
+  describe('Super Admin Bypass Logic', () => {
+    it('renders without errors when super admin check is in progress', async () => {
+      vi.mocked(isSuperAdmin).mockResolvedValue(false);
+      
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: { id: 'org-123' },
+        selectedEvent: { event_id: 'event-123' },
+        appId: 'app-123',
+        appName: 'test-app',
+        supabase: {} as any
+      });
+
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: mockScope,
+        isLoading: false,
+        error: null
+      });
+
+      // Super admin check is async, so initially isSuperAdmin will be null
+      mockUseCanFn.mockReturnValue({
+        can: true, // Normal permission check
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      // Wait for super admin check to complete
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { timeout: TEST_TIMEOUT, interval: 100 });
+    }, TEST_TIMEOUT);
+
+    it('handles super admin check gracefully when user is not super admin', async () => {
+      vi.mocked(isSuperAdmin).mockResolvedValue(false);
+      
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: { id: 'org-123' },
+        selectedEvent: { event_id: 'event-123' },
+        appId: 'app-123',
+        appName: 'test-app',
+        supabase: {} as any
+      });
+
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: mockScope,
+        isLoading: false,
+        error: null
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      // Should use normal permission check (not super admin)
+      expect(mockUseCanFn).toHaveBeenCalled();
+    }, TEST_TIMEOUT);
+
+    it('handles super admin check timeout gracefully', async () => {
+      // Mock isSuperAdmin to timeout
+      vi.mocked(isSuperAdmin).mockImplementation(() => 
+        new Promise((_, reject) => 
+          setTimeout(() => reject(new Error('Super admin check timeout')), 11000)
+        )
+      );
+
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: { id: 'org-123' },
+        selectedEvent: { event_id: 'event-123' },
+        appId: 'app-123',
+        appName: 'test-app',
+        supabase: {} as any
+      });
+
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: mockScope,
+        isLoading: false,
+        error: null
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: true, // Fallback to normal permission check
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      // Should fall back to normal permission check after timeout
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { timeout: 12000, interval: 100 });
+    }, 12000);
+  });
+
+  describe('PORTAL/ADMIN App Scope Handling', () => {
+    it('allows scope without organisation for PORTAL app', async () => {
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: null, // No organisation for PORTAL
+        selectedEvent: null,
+        appId: 'app-123',
+        appName: 'PORTAL',
+        supabase: {} as any
+      });
+
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: {
+          organisationId: undefined,
+          eventId: undefined,
+          appId: 'app-123'
+        },
+        isLoading: false,
+        error: null
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      // Should call useCan with scope that has undefined organisationId (allowed for PORTAL)
+      expect(mockUseCanFn).toHaveBeenCalledWith(
+        'user-123',
+        expect.objectContaining({
+          appId: 'app-123'
+        }),
+        'read:page.dashboard',
+        'dashboard',
+        true,
+        null, // precomputedSuperAdmin
+        'PORTAL'
+      );
+    }, TEST_TIMEOUT);
+
+    it('allows scope without organisation for ADMIN app', async () => {
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: null,
+        selectedEvent: null,
+        appId: 'app-123',
+        appName: 'ADMIN',
+        supabase: {} as any
+      });
+
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: {
+          organisationId: undefined,
+          eventId: undefined,
+          appId: 'app-123'
+        },
+        isLoading: false,
+        error: null
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      expect(mockUseCanFn).toHaveBeenCalledWith(
+        'user-123',
+        expect.objectContaining({
+          appId: 'app-123'
+        }),
+        'read:page.dashboard',
+        'dashboard',
+        true,
+        null,
+        'ADMIN'
+      );
+    }, TEST_TIMEOUT);
+
+    it('uses contextAppId when resolved scope appId is missing for PORTAL/ADMIN', async () => {
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: null,
+        selectedEvent: null,
+        appId: 'context-app-123', // Available from context
+        appName: 'PORTAL',
+        supabase: {} as any
+      });
+
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: {
+          organisationId: undefined,
+          eventId: undefined,
+          appId: undefined // Missing from resolved scope
+        },
+        isLoading: false,
+        error: null
+      });
+
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10 });
+
+      // Should use contextAppId as fallback
+      expect(mockUseCanFn).toHaveBeenCalledWith(
+        'user-123',
+        expect.objectContaining({
+          appId: 'context-app-123'
+        }),
+        'read:page.dashboard',
+        'dashboard',
+        true,
+        null,
+        'PORTAL'
+      );
+    }, TEST_TIMEOUT);
+  });
+
+  describe('Timeout Warnings', () => {
+    it('handles long loading states gracefully', async () => {
+      mockUseUnifiedAuthFn.mockReturnValue({
+        user: mockUser,
+        selectedOrganisation: { id: 'org-123' },
+        selectedEvent: { event_id: 'event-123' },
+        appId: 'app-123',
+        appName: 'test-app',
+        supabase: {} as any
+      });
+
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: mockScope,
+        isLoading: false,
+        error: null
+      });
+
+      // Make permission check slow initially
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: true, // Still loading
+        error: null
+      });
+
+      render(
+        <PagePermissionGuard
+          pageName={mockPageName}
+          operation={mockOperation}
+        >
+          <TestComponent>Protected Page</TestComponent>
+        </PagePermissionGuard>
+      );
+
+      // Component should show loading state
+      expect(screen.getByText('Checking permissions...')).toBeInTheDocument();
+
+      // Then resolve the permission check
+      mockUseCanFn.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
+
+      await waitFor(() => {
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { timeout: TEST_TIMEOUT, interval: 100 });
+    }, TEST_TIMEOUT);
+  });
+});