@jmruthers/pace-core 0.2.4

package/docs/implementation-guides/permission-enforcement.md

@@ -0,0 +1,764 @@
+# Permission Enforcement
+
+> **📚 New Developer?** Start with the [Installation](../getting-started/installation.md) guide, then [Quick Start](../getting-started/quick-start.md) to build your first app.
+
+This guide covers all aspects of implementing permission enforcement in PACE Core applications, from layout-level safety nets to granular page-level controls.
+
+## Overview
+
+PACE Core provides multiple layers of permission enforcement:
+
+1. **Layout-Level Enforcement** - Safety net to prevent forgetting permission checks
+2. **Page-Level Enforcement** - Granular control over specific page permissions
+3. **Component-Level Enforcement** - Fine-grained UI element permissions
+4. **Programmatic Enforcement** - Advanced permission management with caching
+
+## 🎯 **Quick Decision Guide**
+
+### When to Use What Pattern
+
+| Pattern | Use When | Scope Required | Benefits |
+|---------|----------|----------------|----------|
+| **PermissionEnforcer** | Protecting pages/large components | No (automatic) | Automatic scope resolution, simple error handling |
+| **usePermissions** | Need actual permission data | Yes (explicit) | Full permission data, custom logic |
+| **useCan** | Individual permission checks | Yes (explicit) | Real-time checking, loading states |
+| **PagePermissionGuard** | Page-level protection | No (automatic) | Page-specific permissions |
+
+### Setup Requirements
+
+**⚠️ REQUIRED: Complete setup before using any patterns**
+
+```tsx
+// 1. Setup RBAC
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+setupRBAC(supabase);
+
+// 2. Wrap with providers
+<UnifiedAuthProvider supabaseClient={supabase} appName="My App">
+  <OrganisationProvider>
+    <YourAppContent />
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+## Layout-Level Permission Enforcement
+
+### Why Layout-Level Enforcement?
+
+Layout-level enforcement provides a safety net that prevents consuming apps from forgetting to implement permission checks. It ensures that every route is automatically validated for permissions.
+
+### Basic Implementation
+
+```tsx
+import { PaceAppLayout } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
+      <Router>
+        <Routes>
+          <Route path="/" element={
+            <PaceAppLayout 
+              appName="My Application"
+              enforcePermissions={true}
+              defaultPermission="read"
+            />
+          }>
+            <Route index element={<HomePage />} />
+            <Route path="dashboard" element={<DashboardPage />} />
+            <Route path="meals" element={<MealsPage />} />
+          </Route>
+        </Routes>
+      </Router>
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+### Route-Specific Permissions
+
+Configure different permissions for different routes:
+
+```tsx
+<PaceAppLayout 
+  appName="Admin Panel"
+  enforcePermissions={true}
+  defaultPermission="read"
+  routePermissions={{
+    '/dashboard': 'read',
+    '/user-management': 'read',
+    '/system-settings': 'update',
+    '/audit-logs': 'read',
+    '/admin-tools': 'delete'
+  }}
+  pageIdMapping={{
+    '/dashboard': 'dashboard',
+    '/user-management': 'user-management',
+    '/system-settings': 'system-admin',
+    '/audit-logs': 'audit-logs',
+    '/admin-tools': 'admin-tools'
+  }}
+/>
+```
+
+### Navigation Filtering
+
+Filter navigation items based on user permissions:
+
+```tsx
+<PaceAppLayout 
+  appName="My Application"
+  navItems={navItems}
+  enforcePermissions={true}
+  filterNavigationByPermissions={true}
+  routePermissions={{
+    '/dashboard': 'read',
+    '/meals': 'read',
+    '/users': 'read',
+    '/settings': 'update',
+    '/admin': 'read'
+  }}
+  pageIdMapping={{
+    '/dashboard': 'dashboard',
+    '/meals': 'meals',
+    '/users': 'user-management',
+    '/settings': 'settings',
+    '/admin': 'system-admin'
+  }}
+/>
+```
+
+### Custom Fallback Components
+
+Provide custom fallback components for better UX:
+
+```tsx
+function AccessDeniedPage() {
+  return (
+    <div className="flex items-center justify-center min-h-screen bg-sec-50">
+      <div className="text-center max-w-md mx-auto p-6">
+        <div className="mb-4">
+          <svg className="mx-auto h-12 w-12 text-acc-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <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-2xl font-bold text-sec-900 mb-2">Access Denied</h2>
+        <p className="text-sec-600 mb-6">
+          You don't have permission to access this page. Please contact your administrator for access.
+        </p>
+        <div className="space-x-4">
+          <Button onClick={() => navigate('/')}>Go Home</Button>
+          <Button variant="outline" onClick={() => navigate('/contact')}>Contact Support</Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <Router>
+      <Routes>
+        <Route path="/" element={
+          <PaceAppLayout 
+            appName="My Application"
+            enforcePermissions={true}
+            permissionFallback={<AccessDeniedPage />}
+          />
+        }>
+          {/* Routes */}
+        </Route>
+      </Routes>
+    </Router>
+  );
+}
+```
+
+## Page-Level Permission Enforcement
+
+### PagePermissionGuard Component
+
+Use `PagePermissionGuard` for comprehensive page-level permission management:
+
+```tsx
+import { PagePermissionGuard, PAGE_IDS } from '@jmruthers/pace-core';
+
+function MealsPage() {
+  return (
+    <PagePermissionGuard pageId={PAGE_IDS.MEALS}>
+      {(permissions) => (
+        <div className="meals-page">
+          <h1>Meals Management</h1>
+          
+          {/* Read permission - show meals list */}
+          {permissions.canRead && <MealsList />}
+          
+          {/* Create permission - show add button */}
+          {permissions.canCreate && <AddMealButton />}
+          
+          {/* Update permission - show edit buttons */}
+          {permissions.canUpdate && <MealEditButtons />}
+          
+          {/* Delete permission - show delete buttons */}
+          {permissions.canDelete && <MealDeleteButtons />}
+          
+          {/* Debug information (development only) */}
+          {process.env.NODE_ENV === 'development' && permissions.debugInfo && (
+            <div className="debug-info">
+              <p>Cache Hits: {permissions.debugInfo.cacheHits}</p>
+              <p>Cache Misses: {permissions.debugInfo.cacheMisses}</p>
+              <p>Avg Response: {permissions.debugInfo.averageResponseTime}ms</p>
+            </div>
+          )}
+        </div>
+      )}
+    </PagePermissionGuard>
+  );
+}
+```
+
+### Specific Permission Guards
+
+Use convenience components for individual permission types:
+
+```tsx
+import { 
+  ReadPermissionGuard, 
+  CreatePermissionGuard, 
+  UpdatePermissionGuard, 
+  DeletePermissionGuard,
+  PAGE_IDS 
+} from '@jmruthers/pace-core';
+
+function UserManagementPage() {
+  return (
+    <div className="user-management">
+      <h1>User Management</h1>
+      
+      <ReadPermissionGuard pageId={PAGE_IDS.USER_MANAGEMENT}>
+        <UserList />
+      </ReadPermissionGuard>
+      
+      <CreatePermissionGuard pageId={PAGE_IDS.USER_MANAGEMENT}>
+        <AddUserButton />
+      </CreatePermissionGuard>
+      
+      <UpdatePermissionGuard pageId={PAGE_IDS.USER_MANAGEMENT}>
+        <UserEditButtons />
+      </UpdatePermissionGuard>
+      
+      <DeletePermissionGuard 
+        pageId={PAGE_IDS.USER_MANAGEMENT}
+        fallback={<p>You need admin privileges to delete users.</p>}
+      >
+        <UserDeleteButtons />
+      </DeletePermissionGuard>
+    </div>
+  );
+}
+```
+
+## Component-Level Permission Enforcement
+
+### PermissionGuard Component
+
+Use `PermissionGuard` for specific CRUD operations:
+
+```tsx
+import { PermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function MealsPage({ userId, scope }) {
+  return (
+    <div className="meals-page">
+      <h1>Meals Management</h1>
+      
+      {/* Read permission - show meals list */}
+      <PermissionGuard 
+        userId={userId}
+        scope={scope}
+        permission="read:meals"
+      >
+        <MealsList />
+      </PermissionGuard>
+      
+      {/* Create permission - show add button */}
+      <PermissionGuard 
+        userId={userId}
+        scope={scope}
+        permission="create:meals"
+      >
+        <AddMealButton />
+      </PermissionGuard>
+      
+      {/* Update permission - show edit buttons */}
+      <PermissionGuard 
+        userId={userId}
+        scope={scope}
+        permission="update:meals"
+      >
+        <MealEditButtons />
+      </PermissionGuard>
+      
+      {/* Delete permission - show delete buttons */}
+      <PermissionGuard 
+        userId={userId}
+        scope={scope}
+        permission="delete:meals"
+        fallback={<p>You don't have permission to delete meals.</p>}
+      >
+        <MealDeleteButtons />
+      </PermissionGuard>
+    </div>
+  );
+}
+```
+
+### AccessLevelGuard Component
+
+Use `AccessLevelGuard` for access level-based UI elements:
+
+```tsx
+import { AccessLevelGuard } from '@jmruthers/pace-core/rbac';
+
+function AdminPanel({ userId, scope }) {
+  return (
+    <div className="admin-panel">
+      {/* Super admin only */}
+      <AccessLevelGuard
+        userId={userId}
+        scope={scope}
+        requiredLevel="super"
+      >
+        <SystemSettings />
+      </AccessLevelGuard>
+      
+      {/* Admin level and above */}
+      <AccessLevelGuard
+        userId={userId}
+        scope={scope}
+        requiredLevel="admin"
+      >
+        <OrganisationSettings />
+      </AccessLevelGuard>
+      
+      {/* Planner level and above */}
+      <AccessLevelGuard
+        userId={userId}
+        scope={scope}
+        requiredLevel="planner"
+      >
+        <EventSettings />
+      </AccessLevelGuard>
+    </div>
+  );
+}
+```
+
+## Programmatic Permission Enforcement
+
+### Advanced Permission Management
+
+Use the RBAC hooks for advanced permission management:
+
+```tsx
+import { useMultiplePermissions, rbacCache } from '@jmruthers/pace-core/rbac';
+
+function AdvancedMealActions({ mealId, userId, scope }) {
+  const { checkMultiple, isLoading } = useMultiplePermissions();
+  
+  const [permissions, setPermissions] = useState({
+    canEdit: false,
+    canDelete: false,
+    canShare: false
+  });
+
+  useEffect(() => {
+    const loadPermissions = async () => {
+      if (!isLoading) {
+        // Check multiple permissions efficiently
+        const results = await checkMultiple([
+          { userId, scope, permission: 'update:meals' },
+          { userId, scope, permission: 'delete:meals' },
+          { userId, scope, permission: 'read:meal-sharing' }
+        ]);
+
+        setPermissions({
+          canEdit: results[0]?.allowed || false,
+          canDelete: results[1]?.allowed || false,
+          canShare: results[2]?.allowed || false
+        });
+      }
+    };
+
+    loadPermissions();
+  }, [checkMultiple, isLoading, mealId, userId, scope]);
+
+  const handlePermissionChange = () => {
+    // Invalidate cache when permissions change
+    rbacCache.invalidate(`${userId}:${scope.organisationId}:*`);
+  };
+
+  return (
+    <div className="meal-actions">
+      {permissions.canEdit && <EditMealButton mealId={mealId} />}
+      {permissions.canDelete && <DeleteMealButton mealId={mealId} />}
+      {permissions.canShare && <ShareMealButton mealId={mealId} />}
+    </div>
+  );
+}
+```
+
+### useCan Hook
+
+Use `useCan` for direct permission checking:
+
+```tsx
+import { useCan } from '@jmruthers/pace-core/rbac';
+
+function MealActions({ mealId }) {
+  const { hasPermission, isLoading } = useCan();
+  const [canEdit, setCanEdit] = useState(false);
+  const [canDelete, setCanDelete] = useState(false);
+
+  useEffect(() => {
+    const checkPermissions = async () => {
+      const editPerm = await hasPermission('update:meals', {
+        userId: 'user-123',
+        scope: { organisationId: 'org-456' }
+      });
+      const deletePerm = await hasPermission('delete:meals', {
+        userId: 'user-123',
+        scope: { organisationId: 'org-456' }
+      });
+      
+      setCanEdit(editPerm);
+      setCanDelete(deletePerm);
+    };
+
+    if (!isLoading) {
+      checkPermissions();
+    }
+  }, [hasPermission, isLoading]);
+
+  if (isLoading) return <LoadingSpinner />;
+
+  return (
+    <div className="meal-actions">
+      {canEdit && <EditMealButton mealId={mealId} />}
+      {canDelete && <DeleteMealButton mealId={mealId} />}
+    </div>
+  );
+}
+```
+
+## Performance Optimization
+
+### 1. Intelligent Caching
+
+The permission cache automatically optimizes performance:
+
+```tsx
+// Cache configuration
+const { checkPermission } = usePermissionCache({
+  defaultTTL: 5 * 60 * 1000, // 5 minutes
+  maxCacheSize: 1000,
+  enableLogging: process.env.NODE_ENV === 'development'
+});
+
+// Permissions are cached automatically
+const canEdit = await checkPermission('update', 'meals'); // First call - cache miss
+const canEditAgain = await checkPermission('update', 'meals'); // Second call - cache hit
+```
+
+### 2. Batch Permission Loading
+
+Load multiple permissions efficiently:
+
+```tsx
+const { checkMultiplePermissions } = usePermissionCache();
+
+// Load all permissions for a page in one operation
+const permissions = await checkMultiplePermissions([
+  ['read', 'meals'],
+  ['create', 'meals'],
+  ['update', 'meals'],
+  ['delete', 'meals']
+]);
+```
+
+### 3. Cache Invalidation
+
+Invalidate cache when permissions change:
+
+```tsx
+const { invalidateCache } = usePermissionCache();
+
+// Invalidate specific page
+invalidateCache('meals');
+
+// Invalidate all permissions
+invalidateCache();
+
+// Invalidate pattern
+invalidateCache('user-.*');
+```
+
+## Security Considerations
+
+### 1. Server-Side Validation
+
+Layout-level enforcement is for UX only. Always validate permissions server-side:
+
+```tsx
+// API endpoint example
+async function handleCreateMeal(req, res) {
+  const { user, supabase } = req;
+  
+  // Check permission server-side
+  const { data: hasPermission } = await supabase.rpc('check_page_permission', {
+    p_user_id: user.id,
+    p_app_name: 'MY_APP',
+    p_page_id: 'meals',
+    p_operation: 'create',
+    p_event_id: req.body.eventId,
+    p_organisation_id: req.body.organisationId
+  });
+
+  if (!hasPermission) {
+    return res.status(403).json({ error: 'Insufficient permissions' });
+  }
+
+  // Proceed with meal creation
+  // ... implementation
+}
+```
+
+### 2. Database-Level Enforcement
+
+Use RLS policies for automatic data protection:
+
+```sql
+-- Example RLS policy for meals table
+CREATE POLICY "meals_organisation_isolation" ON public.meals
+FOR ALL USING (
+  organisation_id = app_current_organisation_id()
+);
+
+CREATE POLICY "meals_crud_permissions" ON public.meals
+FOR SELECT USING (
+  EXISTS (
+    SELECT 1 FROM rbac_page_permissions rpp
+    WHERE rpp.user_id = auth.uid()
+    AND rpp.page_id = 'meals'
+    AND rpp.operation = 'read'
+  )
+);
+```
+
+### 3. Audit Logging
+
+Monitor permission checks for security:
+
+```tsx
+// Enable audit trail in development
+const { getAuditTrail } = usePermissionCache();
+
+// Log permission decisions
+const auditTrail = getAuditTrail();
+console.log('Permission audit:', auditTrail);
+```
+
+## Best Practices
+
+### 1. Use Layout-Level Enforcement
+
+Always enable layout-level enforcement to prevent forgetting permission checks:
+
+```tsx
+<PaceAppLayout 
+  appName="My App"
+  enforcePermissions={true}
+  defaultPermission="read"
+/>
+```
+
+### 2. Use Standardized Page IDs
+
+```tsx
+// ✅ Good - use standardized IDs
+<PagePermissionGuard pageId={PAGE_IDS.MEALS}>
+  {(permissions) => <MealsContent permissions={permissions} />}
+</PagePermissionGuard>
+
+// ❌ Avoid - hardcoded strings
+<PagePermissionGuard pageId="meals">
+  {(permissions) => <MealsContent permissions={permissions} />}
+</PagePermissionGuard>
+```
+
+### 3. Handle Loading States
+
+```tsx
+<PagePermissionGuard pageId={PAGE_IDS.MEALS}>
+  {(permissions) => {
+    if (permissions.isLoading) return <LoadingSpinner />;
+    if (permissions.error) return <ErrorMessage error={permissions.error} />;
+    
+    return <MealsContent permissions={permissions} />;
+  }}
+</PagePermissionGuard>
+```
+
+### 4. Provide Meaningful Fallbacks
+
+```tsx
+<PagePermissionGuard 
+  pageId={PAGE_IDS.MEALS}
+  fallback={
+    <div className="permission-denied">
+      <h3>Access Denied</h3>
+      <p>You don't have permission to access the meals page.</p>
+      <p>Contact your administrator for access.</p>
+    </div>
+  }
+>
+  {(permissions) => <MealsContent permissions={permissions} />}
+</PagePermissionGuard>
+```
+
+### 5. Optimize for Performance
+
+```tsx
+// Use batch loading for multiple permissions
+const { checkMultiplePermissions } = usePermissionCache();
+
+useEffect(() => {
+  const loadAllPermissions = async () => {
+    const results = await checkMultiplePermissions([
+      ['read', PAGE_IDS.MEALS],
+      ['create', PAGE_IDS.MEALS],
+      ['update', PAGE_IDS.MEALS],
+      ['delete', PAGE_IDS.MEALS]
+    ]);
+    
+    // Process results
+    setPermissions(results);
+  };
+  
+  loadAllPermissions();
+}, [checkMultiplePermissions]);
+```
+
+## 🚨 **Troubleshooting Common Errors**
+
+### Error: "can't access property 'organisationId', scope is undefined"
+
+**Cause**: Missing organisation context or incorrect provider setup
+
+**Solution**:
+1. **Ensure OrganisationProvider wraps your app**:
+   ```tsx
+   <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
+     <OrganisationProvider>  {/* ← This is required! */}
+       <YourAppContent />
+     </OrganisationProvider>
+   </UnifiedAuthProvider>
+   ```
+
+2. **Use PermissionEnforcer for automatic scope resolution**:
+   ```tsx
+   // ✅ Good - automatic scope resolution
+   <PermissionEnforcer permissions={['read:events']}>
+     <EventContent />
+   </PermissionEnforcer>
+   
+   // ❌ Avoid - manual scope handling with usePermissions
+   const { permissions } = usePermissions(userId, scope); // scope might be undefined
+   ```
+
+3. **Check that user has selected an organisation**:
+   ```tsx
+   const { selectedOrganisationId } = useUnifiedAuth();
+   if (!selectedOrganisationId) {
+     return <div>Please select an organisation first</div>;
+   }
+   ```
+
+### Error: "RBACNotInitializedError"
+
+**Cause**: Forgot to call `setupRBAC()`
+
+**Solution**:
+```tsx
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+
+// ⚠️ REQUIRED: Call this before using any RBAC features
+setupRBAC(supabase);
+```
+
+### Error: "Organisation context is required but not available"
+
+**Cause**: OrganisationProvider not wrapping your app or user not in any organisation
+
+**Solution**:
+1. Ensure OrganisationProvider wraps your app
+2. Check that user has organisation memberships in the database
+3. Verify user has selected an organisation
+
+### Common Issues
+
+#### 1. Permission checks not working
+- Ensure `enforcePermissions={true}` is set
+- Check that page IDs are correctly mapped
+- Verify user has proper roles assigned
+- Ensure OrganisationProvider is wrapping your app
+
+#### 2. Navigation items not filtering
+- Enable `filterNavigationByPermissions={true}`
+- Ensure `routePermissions` is configured
+- Check that page IDs match the mapping
+
+#### 3. Performance issues
+- Use caching (enabled by default)
+- Limit the number of route-specific permissions
+- Consider using default permissions where possible
+
+#### 4. Custom fallback not showing
+- Ensure `permissionFallback` is provided
+- Check that the component is properly exported
+- Verify the fallback component renders correctly
+
+### Debug Mode
+
+Enable debug logging to troubleshoot permission issues:
+
+```tsx
+// Add to your app for debugging
+const { getDebugInfo } = usePermissionCache();
+
+// Log debug information
+const debugInfo = getDebugInfo();
+console.log('Permission debug:', debugInfo);
+```
+
+## 🎯 **Pattern Selection Guide**
+
+### Use PermissionEnforcer when:
+- Protecting entire pages or large components
+- You want automatic scope resolution
+- You need fallback UI for denied access
+- You want simpler error handling
+
+### Use usePermissions when:
+- You need the actual permission data
+- You're building custom permission logic
+- You need loading states and error handling
+- You're building complex permission-based UI
+
+### Use useCan when:
+- Checking individual permissions
+- You need real-time permission checking
+- You're building dynamic UI based on permissions
+- You need fine-grained control over permission checks
+
+This comprehensive permission enforcement system provides multiple layers of security and UX optimization for PACE Core applications.