@jmruthers/pace-core 0.5.183 → 0.5.185

package/src/rbac/compliance/setup-validator.ts

@@ -0,0 +1,131 @@
+/**
+ * RBAC Setup Validator
+ * @package @jmruthers/pace-core
+ * @module RBAC/Compliance/SetupValidator
+ * @since 1.0.0
+ * 
+ * This module provides utilities to validate RBAC setup state.
+ */
+
+import { getRBACConfig } from '../config';
+import { RBACNotInitializedError } from '../errors';
+
+export interface SetupIssue {
+  type: 'not-initialized' | 'missing-config' | 'invalid-config' | 'missing-provider-context';
+  message: string;
+  recommendation: string;
+}
+
+export interface ComplianceResult {
+  isCompliant: boolean;
+  issues: SetupIssue[];
+}
+
+/**
+ * Check if RBAC system is initialized
+ * 
+ * @returns true if RBAC is initialized, false otherwise
+ */
+export function isRBACInitialized(): boolean {
+  try {
+    const config = getRBACConfig();
+    return config !== null && config.supabase !== null;
+  } catch (error) {
+    if (error instanceof RBACNotInitializedError) {
+      return false;
+    }
+    // Re-throw unexpected errors
+    throw error;
+  }
+}
+
+/**
+ * Get setup issues
+ * 
+ * @returns Array of setup issues
+ */
+export function getSetupIssues(): SetupIssue[] {
+  const issues: SetupIssue[] = [];
+  
+  const config = getRBACConfig();
+  
+  if (!config) {
+    issues.push({
+      type: 'not-initialized',
+      message: 'RBAC system has not been initialized. setupRBAC() has not been called.',
+      recommendation: 'Call setupRBAC(supabase) before using any RBAC features. This should be done in your main entry point (main.tsx or App.tsx) before rendering the app.'
+    });
+    return issues;
+  }
+  
+  if (!config.supabase) {
+    issues.push({
+      type: 'missing-config',
+      message: 'RBAC configuration is missing Supabase client.',
+      recommendation: 'Ensure setupRBAC() is called with a valid Supabase client instance.'
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Check if UnifiedAuthProvider context is available
+ * 
+ * This function can be called from React components to check if the context
+ * is available. It uses React's useContext hook, so it must be called from
+ * within a React component.
+ * 
+ * @returns true if context is available, false otherwise
+ * @throws Error if called outside React component context
+ */
+export function isUnifiedAuthContextAvailable(): boolean {
+  try {
+    // This will only work if called from within a React component
+    // We can't import useContext here directly as it would require React
+    // Instead, we'll check if the context can be accessed
+    // Note: This is a best-effort check and may not work in all scenarios
+    return true; // Context availability is checked by useUnifiedAuth hook itself
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Get provider context setup issues
+ * 
+ * This provides guidance on common provider setup problems.
+ * Actual context availability must be checked at component level.
+ * 
+ * @returns Array of setup issues related to provider context
+ */
+export function getProviderContextIssues(): SetupIssue[] {
+  const issues: SetupIssue[] = [];
+  
+  // Check if RBAC is initialized (prerequisite for provider context)
+  if (!isRBACInitialized()) {
+    issues.push({
+      type: 'not-initialized',
+      message: 'RBAC system must be initialized before provider context can be used.',
+      recommendation: 'Call setupRBAC(supabase) before rendering UnifiedAuthProvider.'
+    });
+  }
+  
+  return issues;
+}
+
+/**
+ * Validate RBAC setup
+ * 
+ * @returns Compliance result with issues and recommendations
+ */
+export function validateRBACSetup(): ComplianceResult {
+  const issues = getSetupIssues();
+  const providerIssues = getProviderContextIssues();
+  
+  return {
+    isCompliant: issues.length === 0 && providerIssues.length === 0,
+    issues: [...issues, ...providerIssues]
+  };
+}
+

package/src/rbac/components/PagePermissionGuard.tsx

@@ -72,7 +72,6 @@ import { useCan } from '../hooks';
 import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
 import { UUID, Permission, Scope } from '../types';
 import { createScopeFromEvent } from '../utils/eventContext';
-import { getCurrentAppName } from '../../utils/app/appNameResolver';
 import { getRBACLogger } from '../config';
 
 export interface PagePermissionGuardProps {
@@ -129,16 +128,16 @@ const PagePermissionGuardComponent = ({
   onDenied,
   loading = <DefaultLoading />
 }: PagePermissionGuardProps) => {
-  // Generate a unique instance ID for debugging
-  const instanceId = useMemo(() => Math.random().toString(36).substr(2, 9), []);
-  
   // 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), []);
   
-  
-  const { user, selectedOrganisation, selectedEvent, supabase } = useUnifiedAuth();
+  // 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 } = useUnifiedAuth();
   
   const [hasChecked, setHasChecked] = useState(false);
   const [checkError, setCheckError] = useState<Error | null>(null);
@@ -179,64 +178,9 @@ const PagePermissionGuardComponent = ({
         return;
       }
 
-      // Get app ID from package.json or environment
-      let appId: string | undefined = undefined;
-
-      // Try to resolve from database
-      if (supabaseRef.current) {
-        const appName = getCurrentAppName();
-        if (appName) {
-          try {
-            const { data: app, error } = await supabaseRef.current
-              .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 (signal.aborted) {
-              return;
-            }
-
-            if (error) {
-              const logger = getRBACLogger();
-              logger.error('Database error resolving app ID:', error);
-              if (signal.aborted) {
-                return;
-              }
-              const { data: inactiveApp } = await supabaseRef.current
-                .from('rbac_apps')
-                .select('id, name, is_active')
-                .eq('name', appName)
-                .single() as { data: { id: string; name: string; is_active: boolean } | null };
-
-              if (signal.aborted) {
-                return;
-              }
-
-              if (inactiveApp) {
-                logger.error(`App "${appName}" exists but is inactive (is_active: ${inactiveApp.is_active})`);
-              } else {
-                logger.error(`App "${appName}" not found in rbac_apps table`);
-              }
-            } else if (app) {
-              appId = app.id;
-            } else {
-              const logger = getRBACLogger();
-              logger.error('No app data returned for:', appName);
-            }
-          } catch (error) {
-            if (signal.aborted) {
-              return;
-            }
-            const logger = getRBACLogger();
-            logger.error('Unexpected error resolving app ID:', error);
-          }
-        } else {
-          const logger = getRBACLogger();
-          logger.error('No app name found. Make sure to call setRBACAppName() in your app setup.');
-        }
-      }
+      // Get app ID from UnifiedAuth context (already resolved on login)
+      // This is much faster than querying the database
+      const appId = contextAppId;
 
       if (signal.aborted) {
         return;

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

@@ -80,6 +80,7 @@ describe('PagePermissionGuard Component', () => {
       user: mockUser,
       selectedOrganisation: { id: 'org-123' },
       selectedEvent: { event_id: 'event-123' },
+      appId: 'app-123', // Required for scope resolution
       supabase: {
         from: vi.fn().mockReturnValue({
           select: vi.fn().mockReturnValue({
@@ -343,14 +344,17 @@ describe('PagePermissionGuard Component', () => {
         </PagePermissionGuard>
       );
 
+      // When there's an error and no permission, component shows fallback
       await waitFor(() => {
-        expect(screen.getByText('Checking permissions...')).toBeInTheDocument();
-      }, { interval: 10 });
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
     });
   });
 
   describe('App ID Resolution', () => {
     it('resolves app ID from database', async () => {
+      // When appId is already provided from useUnifiedAuth, getCurrentAppName is not called
+      // The component uses appId from context directly
       mockUseCan.mockReturnValue({
         can: true,
         isLoading: false,
@@ -368,9 +372,11 @@ describe('PagePermissionGuard Component', () => {
 
       await waitFor(() => {
         expect(screen.getByTestId('test-component')).toBeInTheDocument();
-      }, { interval: 10 });
+      }, { interval: 10, timeout: 2000 });
 
-      expect(mockGetCurrentAppName).toHaveBeenCalled();
+      // appId is provided from useUnifiedAuth context, so getCurrentAppName is not called
+      // The component uses contextAppId directly (line 183 of PagePermissionGuard)
+      expect(mockGetCurrentAppName).not.toHaveBeenCalled();
     });
 
     it('handles app resolution errors in test environment', async () => {
@@ -432,10 +438,12 @@ describe('PagePermissionGuard Component', () => {
       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({
@@ -452,9 +460,11 @@ describe('PagePermissionGuard Component', () => {
         } as any
       });
 
-      // Set NODE_ENV to production
-      const originalEnv = process.env.NODE_ENV;
-      process.env.NODE_ENV = 'production';
+      mockUseCan.mockReturnValue({
+        can: true,
+        isLoading: false,
+        error: null
+      });
 
       render(
         <PagePermissionGuard
@@ -466,12 +476,10 @@ describe('PagePermissionGuard Component', () => {
         </PagePermissionGuard>
       );
 
+      // In test mode, validation is skipped, so component should render normally
       await waitFor(() => {
-        expect(screen.getByText('Checking permissions...')).toBeInTheDocument();
-      }, { interval: 10 });
-
-      // Restore NODE_ENV
-      process.env.NODE_ENV = originalEnv;
+        expect(screen.getByTestId('test-component')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
     });
   });
 
@@ -550,6 +558,7 @@ describe('PagePermissionGuard Component', () => {
         user: mockUser,
         selectedOrganisation: { id: 'org-123' },
         selectedEvent: null,
+        appId: 'app-123',
         supabase: {
           from: vi.fn().mockReturnValue({
             select: vi.fn().mockReturnValue({
@@ -603,6 +612,7 @@ describe('PagePermissionGuard Component', () => {
         user: mockUser,
         selectedOrganisation: null,
         selectedEvent: { event_id: 'event-123' },
+        appId: 'app-123',
         supabase: {
           from: vi.fn().mockReturnValue({
             select: vi.fn().mockReturnValue({
@@ -653,7 +663,7 @@ describe('PagePermissionGuard Component', () => {
         expect.objectContaining({
           organisationId: 'resolved-org',
           eventId: 'event-123',
-          appId: 'app-123'
+          appId: 'app-123' // Component uses appId from context, not from resolved scope
         }),
         'read:page.dashboard',
         'dashboard',
@@ -666,6 +676,7 @@ describe('PagePermissionGuard Component', () => {
         user: mockUser,
         selectedOrganisation: null,
         selectedEvent: { event_id: 'event-123' },
+        appId: undefined, // Not available for error case
         supabase: {} as any
       });
 
@@ -692,6 +703,7 @@ describe('PagePermissionGuard Component', () => {
         user: mockUser,
         selectedOrganisation: null,
         selectedEvent: null,
+        appId: undefined,
         supabase: null
       });
 
@@ -809,8 +821,8 @@ describe('PagePermissionGuard Component', () => {
       );
 
       await waitFor(() => {
-        expect(screen.getByText('Checking permissions...')).toBeInTheDocument();
-      }, { interval: 10 });
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
 
       expect(onDeniedSpy).toHaveBeenCalledWith(mockPageName, mockOperation);
     });
@@ -864,8 +876,8 @@ describe('PagePermissionGuard Component', () => {
       );
 
       await waitFor(() => {
-        expect(screen.getByText('Checking permissions...')).toBeInTheDocument();
-      }, { interval: 10 });
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
 
       expect(consoleSpy).not.toHaveBeenCalledWith(
         expect.stringContaining('STRICT MODE VIOLATION')
@@ -895,8 +907,8 @@ describe('PagePermissionGuard Component', () => {
       );
 
       await waitFor(() => {
-        expect(screen.getByText('Checking permissions...')).toBeInTheDocument();
-      }, { interval: 10 });
+        expect(screen.getByTestId('test-fallback')).toBeInTheDocument();
+      }, { interval: 10, timeout: 2000 });
 
       expect(consoleSpy).not.toHaveBeenCalledWith(
         expect.stringContaining('Page access attempt')
@@ -910,8 +922,9 @@ describe('PagePermissionGuard Component', () => {
     it('handles missing user gracefully', async () => {
       mockUseUnifiedAuthFn.mockReturnValue({
         user: null,
-        selectedOrganisationId: 'org-123',
-        selectedEventId: 'event-123',
+        selectedOrganisation: { id: 'org-123' },
+        selectedEvent: { event_id: 'event-123' },
+        appId: 'app-123',
         supabase: {
           from: vi.fn().mockReturnValue({
             select: vi.fn().mockReturnValue({
@@ -966,6 +979,7 @@ describe('PagePermissionGuard Component', () => {
         user: mockUser,
         selectedOrganisation: { id: 'org-123' },
         selectedEvent: { event_id: 'event-123' },
+        appId: undefined, // Not resolved due to database error
         supabase: {
           from: vi.fn().mockReturnValue({
             select: vi.fn().mockReturnValue({

package/src/rbac/docs/event-based-apps.md

@@ -0,0 +1,285 @@
+# Event-Based Apps with RBAC
+
+This guide explains how to use the RBAC system for event-based applications where the organization context is automatically derived from the event context.
+
+## Overview
+
+Event-based apps are applications that operate within the context of a specific event. Since events inherently belong to an organization, these apps don't need explicit organization context - it is automatically resolved from the event by the RBAC components.
+
+## Key Concepts
+
+### Automatic Organization Resolution
+The RBAC components automatically resolve the organization from the event context when needed. You only need to provide the `eventId` (and optionally `appId`), and the system handles the rest.
+
+```typescript
+// The components automatically resolve organisationId from eventId
+const scope: Scope = {
+  eventId: 'event-123',
+  appId: 'app-456' // optional
+  // organisationId is automatically resolved
+};
+```
+
+### Permission Hierarchy
+For event-based apps, the permission hierarchy is:
+1. **Page-level permissions** (most specific)
+2. **Event-app permissions** (event + app specific)
+3. **Organization permissions** (automatically resolved from event)
+4. **Global permissions** (least specific)
+
+## Components
+
+The same RBAC components work for both organization-based and event-based apps. They automatically detect the context and resolve the organization when needed.
+
+### PermissionEnforcer
+Use this component for general permission enforcement in event-based apps:
+
+```tsx
+import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
+
+function EventDashboard() {
+  return (
+    <PermissionEnforcer
+      permissions={['read:events', 'update:participants']}
+      operation="dashboard"
+    >
+      <div>Event Dashboard Content</div>
+    </PermissionEnforcer>
+  );
+}
+```
+
+### PagePermissionGuard
+Use this component for page-level permission enforcement:
+
+```tsx
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function EventSettingsPage() {
+  return (
+    <PagePermissionGuard
+      pageName="settings"
+      operation="read"
+    >
+      <div>Event Settings</div>
+    </PagePermissionGuard>
+  );
+}
+```
+
+### NavigationGuard
+Use this component for navigation-level permission enforcement:
+
+```tsx
+import { NavigationGuard } from '@jmruthers/pace-core/rbac';
+
+const navigationItems = [
+  {
+    id: 'dashboard',
+    name: 'Dashboard',
+    path: '/event/dashboard',
+    permissions: ['read:events']
+  },
+  {
+    id: 'settings',
+    name: 'Settings',
+    path: '/event/settings',
+    permissions: ['update:events']
+  }
+];
+
+function EventNavigation() {
+  return (
+    <nav>
+      {navigationItems.map(item => (
+        <NavigationGuard
+          key={item.id}
+          navigationItem={item}
+        >
+          <Link to={item.path}>{item.name}</Link>
+        </NavigationGuard>
+      ))}
+    </nav>
+  );
+}
+```
+
+## Hooks
+
+### useCan with Event Context
+You can use the standard `useCan` hook with event-based scopes:
+
+```tsx
+import { useCan } from '@jmruthers/pace-core/rbac';
+
+function EventComponent() {
+  const { selectedEventId } = useUnifiedAuth();
+  
+  const { can: canManageEvents } = useCan(
+    userId,
+    { eventId: selectedEventId },
+    'update:events'
+  );
+
+  return (
+    <div>
+      {canManageEvents && (
+        <button>Manage Event</button>
+      )}
+    </div>
+  );
+}
+```
+
+## Setup
+
+### 1. Event Context Provider
+Ensure your app has event context available:
+
+```tsx
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider>
+      {/* Your event-based app components */}
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+### 2. Event Selection
+Make sure the event is selected in the auth context:
+
+```tsx
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function EventSelector() {
+  const { setSelectedEventId } = useUnifiedAuth();
+  
+  const handleEventSelect = (eventId: string) => {
+    setSelectedEventId(eventId);
+  };
+
+  return (
+    <select onChange={(e) => handleEventSelect(e.target.value)}>
+      <option value="event-1">Event 1</option>
+      <option value="event-2">Event 2</option>
+    </select>
+  );
+}
+```
+
+## Permission Types
+
+### Event-App Permissions
+These permissions are specific to an event and app combination:
+
+```typescript
+const EVENT_APP_PERMISSIONS = {
+  // Event management
+  MANAGE_EVENT: 'update:event',
+  READ_EVENT: 'read:event',
+  UPDATE_EVENT: 'update:event',
+  
+  // Participant management
+  MANAGE_PARTICIPANTS: 'update:participants',
+  READ_PARTICIPANTS: 'read:participants',
+  CREATE_PARTICIPANTS: 'create:participants',
+  UPDATE_PARTICIPANTS: 'update:participants',
+  DELETE_PARTICIPANTS: 'delete:participants',
+  
+  // App-specific permissions
+  MANAGE_APP: 'update:app',
+  READ_APP: 'read:app',
+  UPDATE_APP: 'update:app',
+};
+```
+
+### Page Permissions
+Page permissions are specific to individual pages within an event app:
+
+```typescript
+const PAGE_PERMISSIONS = {
+  DASHBOARD_READ: 'read:page.dashboard',
+  DASHBOARD_WRITE: 'write:page.dashboard',
+  SETTINGS_READ: 'read:page.settings',
+  SETTINGS_WRITE: 'write:page.settings',
+  PARTICIPANTS_READ: 'read:page.participants',
+  PARTICIPANTS_WRITE: 'write:page.participants',
+};
+```
+
+## Best Practices
+
+### 1. Use Event-Based Components
+Always use the event-based components (`EventPermissionEnforcer`, `EventPagePermissionGuard`, `EventNavigationGuard`) instead of the organization-based ones for event apps.
+
+### 2. Provide Explicit Scopes
+When possible, provide explicit scopes to avoid context resolution overhead:
+
+```tsx
+<EventPermissionEnforcer
+  scope={{ eventId: 'event-123', appId: 'app-456' }}
+  permissions={['read:events']}
+>
+  <div>Content</div>
+</EventPermissionEnforcer>
+```
+
+### 3. Handle Loading States
+Event-based components automatically handle loading states while resolving the organization from the event:
+
+```tsx
+<EventPermissionEnforcer
+  permissions={['read:events']}
+  loading={<div>Loading permissions...</div>}
+>
+  <div>Content</div>
+</EventPermissionEnforcer>
+```
+
+### 4. Error Handling
+Handle cases where the organization cannot be resolved from the event:
+
+```tsx
+<EventPermissionEnforcer
+  permissions={['read:events']}
+  onDenied={(permission, reason) => {
+    console.error(`Permission denied: ${permission}, reason: ${reason}`);
+  }}
+>
+  <div>Content</div>
+</EventPermissionEnforcer>
+```
+
+## Migration from Organization-Based Apps
+
+If you're migrating from organization-based apps to event-based apps:
+
+1. Replace `PermissionEnforcer` with `EventPermissionEnforcer`
+2. Replace `PagePermissionGuard` with `EventPagePermissionGuard`
+3. Replace `NavigationGuard` with `EventNavigationGuard`
+4. Remove explicit organization context from your components
+5. Ensure event context is available in your app
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Event context is required" error**: Make sure `selectedEventId` is set in the auth context
+2. **"Could not resolve organization from event context" error**: Verify the event exists and has a valid `organisation_id`
+3. **Permission checks failing**: Ensure the user has the appropriate event-app roles assigned
+
+### Debug Mode
+
+Enable debug mode to see detailed permission resolution:
+
+```typescript
+import { createRBACConfig } from '@jmruthers/pace-core/rbac';
+
+const config = createRBACConfig({
+  debug: true,
+  logLevel: 'debug'
+});
+```