@jmruthers/pace-core 0.4.1 → 0.5.1

package/docs/rbac/examples.md

@@ -4,76 +4,68 @@ Practical examples showing how to use the PACE Core RBAC system in real applicat
 
 ## Basic Permission Checking
 
-### Simple Permission Check
+### Page-Level Permission Check
 
 ```tsx
-import { useCan } from '@jmruthers/pace-core/rbac';
-
-function UserProfile({ userId }) {
-  const { hasPermission, isLoading } = useCan();
-  const [canEdit, setCanEdit] = useState(false);
-
-  useEffect(() => {
-    const checkPermission = async () => {
-      if (!isLoading) {
-        const canEditProfile = await hasPermission('update:users', {
-          userId,
-          scope: { organisationId: 'org-456' }
-        });
-        setCanEdit(canEditProfile);
-      }
-    };
-    
-    checkPermission();
-  }, [hasPermission, isLoading, userId]);
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
 
+function UserProfile() {
   return (
     <div>
       <h1>User Profile</h1>
-      {canEdit && <EditButton />}
+      <PagePermissionGuard
+        pageName="profile"
+        operation="update"
+        fallback={null}
+      >
+        <EditButton />
+      </PagePermissionGuard>
     </div>
   );
 }
 ```
 
-### Multiple Permission Checks
+### Multiple Page Permission Checks
 
 ```tsx
-import { useMultiplePermissions } from '@jmruthers/pace-core/rbac';
-
-function UserManagement({ userId, scope }) {
-  const { checkMultiple, isLoading } = useMultiplePermissions();
-  const [permissions, setPermissions] = useState({});
-
-  useEffect(() => {
-    const checkAllPermissions = async () => {
-      if (!isLoading) {
-        const results = await checkMultiple([
-          { userId, scope, permission: 'read:users' },
-          { userId, scope, permission: 'create:users' },
-          { userId, scope, permission: 'update:users' },
-          { userId, scope, permission: 'delete:users' }
-        ]);
-        
-        const permMap = results.reduce((acc, result) => {
-          acc[result.permission] = result.allowed;
-          return acc;
-        }, {});
-        
-        setPermissions(permMap);
-      }
-    };
-    
-    checkAllPermissions();
-  }, [checkMultiple, isLoading, userId, scope]);
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
 
+function UserManagement() {
   return (
     <div>
       <h1>User Management</h1>
-      {permissions['read:users'] && <UserList />}
-      {permissions['create:users'] && <CreateUserButton />}
-      {permissions['update:users'] && <EditUserButton />}
-      {permissions['delete:users'] && <DeleteUserButton />}
+      
+      <PagePermissionGuard
+        pageName="users"
+        operation="read"
+        fallback={null}
+      >
+        <UserList />
+      </PagePermissionGuard>
+      
+      <PagePermissionGuard
+        pageName="users"
+        operation="create"
+        fallback={null}
+      >
+        <CreateUserButton />
+      </PagePermissionGuard>
+      
+      <PagePermissionGuard
+        pageName="users"
+        operation="update"
+        fallback={null}
+      >
+        <EditUserButton />
+      </PagePermissionGuard>
+      
+      <PagePermissionGuard
+        pageName="users"
+        operation="delete"
+        fallback={null}
+      >
+        <DeleteUserButton />
+      </PagePermissionGuard>
     </div>
   );
 }
@@ -81,32 +73,31 @@ function UserManagement({ userId, scope }) {
 
 ## Component-Level Protection
 
-### Permission Guards
+### Page Permission Guards
 
 ```tsx
-import { PermissionGuard } from '@jmruthers/pace-core/rbac';
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
 
-function AdminPanel({ userId, scope }) {
+function AdminPanel() {
   return (
     <div>
       <h1>Admin Panel</h1>
       
-      <PermissionGuard
-        userId={userId}
-        scope={scope}
-        permission="read:users"
+      <PagePermissionGuard
+        pageName="users"
+        operation="read"
+        fallback={null}
       >
         <UserManagement />
-      </PermissionGuard>
+      </PagePermissionGuard>
       
-      <PermissionGuard
-        userId={userId}
-        scope={scope}
-        permission="manage:system"
+      <PagePermissionGuard
+        pageName="system"
+        operation="manage"
         fallback={<div>System management access required</div>}
       >
         <SystemSettings />
-      </PermissionGuard>
+      </PagePermissionGuard>
     </div>
   );
 }
@@ -709,4 +700,184 @@ test('useCan hook returns permission result', async () => {
 });
 ```
 
+## App Context Examples
+
+### Organisation-Based App Example
+
+```tsx
+// components/UserManagement.tsx
+import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
+
+function UserManagement() {
+  return (
+    <div>
+      <h1>User Management</h1>
+      
+      {/* Organisation context is required */}
+      <PermissionEnforcer
+        permissions={['read:users']}
+        operation="user-list"
+        fallback={<div>You need user read permissions</div>}
+      >
+        <UserList />
+      </PermissionEnforcer>
+      
+      <PermissionEnforcer
+        permissions={['create:users']}
+        operation="user-creation"
+        fallback={null} // Don't show if no permission
+      >
+        <CreateUserButton />
+      </PermissionEnforcer>
+    </div>
+  );
+}
+```
+
+### Event-Based App Example
+
+```tsx
+// components/EventDashboard.tsx
+import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
+
+function EventDashboard() {
+  return (
+    <div>
+      <h1>Event Dashboard</h1>
+      
+      {/* Event context is required, organisation is automatically resolved */}
+      <PermissionEnforcer
+        permissions={['read:events']}
+        operation="event-dashboard"
+        fallback={<div>You need event read permissions</div>}
+      >
+        <EventContent />
+      </PermissionEnforcer>
+      
+      <PermissionEnforcer
+        permissions={['manage:participants']}
+        operation="participant-management"
+        fallback={null}
+      >
+        <ParticipantManagement />
+      </PermissionEnforcer>
+    </div>
+  );
+}
+```
+
+### Dynamic Context Handling
+
+```tsx
+// components/AdaptiveComponent.tsx
+import { getAppConfig } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+function AdaptiveComponent({ appId }) {
+  const { selectedOrganisationId, selectedEventId } = useUnifiedAuth();
+  const [appConfig, setAppConfig] = useState(null);
+  
+  useEffect(() => {
+    const loadAppConfig = async () => {
+      const config = await getAppConfig(appId);
+      setAppConfig(config);
+    };
+    loadAppConfig();
+  }, [appId]);
+  
+  if (!appConfig) return <div>Loading app configuration...</div>;
+  
+  // Determine required context based on app type
+  const scope = appConfig.requires_event 
+    ? { eventId: selectedEventId, appId }
+    : { organisationId: selectedOrganisationId, appId };
+  
+  return (
+    <PermissionEnforcer
+      permissions={['read:data']}
+      operation="data-access"
+      scope={scope}
+    >
+      <AppContent />
+    </PermissionEnforcer>
+  );
+}
+```
+
+### Server-Side Context Validation
+
+```typescript
+// pages/api/data/index.ts
+import { getAppConfig, isPermitted } from '@jmruthers/pace-core/rbac';
+
+export async function POST(request: Request) {
+  const { userId, scope, appId } = await request.json();
+  
+  // Check app configuration
+  const appConfig = await getAppConfig(appId);
+  if (!appConfig) {
+    return Response.json({ error: 'App not found' }, { status: 404 });
+  }
+  
+  // Validate context requirements
+  if (appConfig.requires_event && !scope.eventId) {
+    return Response.json({ error: 'Event context required' }, { status: 400 });
+  }
+  
+  if (!appConfig.requires_event && !scope.organisationId) {
+    return Response.json({ error: 'Organisation context required' }, { status: 400 });
+  }
+  
+  // Proceed with permission check
+  const allowed = await isPermitted({ userId, scope, permission: 'read:data' });
+  // ...
+}
+```
+
+### Context-Aware Error Handling
+
+```tsx
+// components/ContextAwareComponent.tsx
+import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
+import { getAppConfig } from '@jmruthers/pace-core/rbac';
+
+function ContextAwareComponent({ appId }) {
+  const [appConfig, setAppConfig] = useState(null);
+  
+  useEffect(() => {
+    getAppConfig(appId).then(setAppConfig);
+  }, [appId]);
+  
+  if (!appConfig) return <div>Loading...</div>;
+  
+  const getContextError = () => {
+    if (appConfig.requires_event) {
+      return (
+        <div>
+          <p>Access denied</p>
+          <p>This app requires event context</p>
+        </div>
+      );
+    } else {
+      return (
+        <div>
+          <p>Access denied</p>
+          <p>This app requires organisation context</p>
+        </div>
+      );
+    }
+  };
+  
+  return (
+    <PermissionEnforcer
+      permissions={['read:data']}
+      operation="data-access"
+      fallback={getContextError()}
+    >
+      <AppContent />
+    </PermissionEnforcer>
+  );
+}
+```
+
 These examples demonstrate the flexibility and power of the PACE Core RBAC system. For more advanced patterns and optimization techniques, see the [Advanced Patterns Guide](./advanced-patterns.md).

package/docs/rbac/getting-started.md

@@ -511,43 +511,158 @@ setupRBAC(supabase, {
 
 This will provide detailed logging of permission checks and help with debugging.
 
-## Event-Based Apps
+## App Context Requirements
 
-For event-based applications, the RBAC system automatically resolves organization context from the event:
+The RBAC system supports two types of applications based on their context requirements:
+
+### Organisation-Based Apps (Default)
+
+**When to use**: Apps that operate at the organisation level without requiring specific event context.
+
+**Examples**:
+- User management systems
+- Organisation settings
+- General dashboards
+- Member directories
+
+**Context Requirements**:
+- ✅ `organisationId` - Required
+- ❌ `eventId` - Optional
+- ❌ `appId` - Optional
+
+```tsx
+// Organisation-based app example
+import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
+
+function UserManagement() {
+  return (
+    <div>
+      <h1>User Management</h1>
+      
+      {/* Requires organisationId in scope */}
+      <PermissionEnforcer
+        permissions={['read:users']}
+        operation="user-management"
+      >
+        <UserList />
+      </PermissionEnforcer>
+    </div>
+  );
+}
+```
+
+**Database Configuration**:
+```sql
+INSERT INTO rbac_apps (name, display_name, requires_event, is_active) 
+VALUES ('user-manager', 'User Manager', false, true);
+```
+
+### Event-Based Apps
+
+**When to use**: Apps that operate within the context of specific events.
+
+**Examples**:
+- Event registration systems
+- Event management dashboards
+- Event-specific reporting
+- Event participant management
+
+**Context Requirements**:
+- ✅ `eventId` - Required
+- ✅ `organisationId` - Automatically resolved from event
+- ❌ `appId` - Optional
 
 ```tsx
 // Event-based app example
-import { PermissionEnforcer, PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
 
 function EventDashboard() {
   return (
     <div>
       <h1>Event Dashboard</h1>
       
-      {/* Organization is automatically resolved from event context */}
+      {/* Requires eventId, organisation is automatically resolved */}
       <PermissionEnforcer
         permissions={['read:events']}
-        operation="dashboard"
+        operation="event-dashboard"
       >
         <EventContent />
       </PermissionEnforcer>
-      
-      <PagePermissionGuard
-        pageName="settings"
-        operation="read"
-      >
-        <EventSettings />
-      </PagePermissionGuard>
     </div>
   );
 }
 ```
 
+**Database Configuration**:
+```sql
+INSERT INTO rbac_apps (name, display_name, requires_event, is_active) 
+VALUES ('event-manager', 'Event Manager', true, true);
+```
+
+### Context Resolution
+
 The system automatically:
-- Resolves organization from event context
-- Handles loading states during resolution
-- Provides appropriate error messages if resolution fails
-- Works seamlessly with both organization-based and event-based apps
+- **Organisation-based apps**: Require `organisationId` in scope
+- **Event-based apps**: Require `eventId` in scope, automatically resolve `organisationId` from event
+- **Validation**: Ensures correct context type based on app configuration
+- **Error handling**: Provides clear error messages for invalid context
+
+### App Configuration
+
+You can check an app's configuration to determine its context requirements:
+
+```typescript
+import { getAppConfig } from '@jmruthers/pace-core/rbac';
+
+// Check if an app is event-based or organisation-based
+const appConfig = await getAppConfig('app-123');
+
+if (appConfig?.requires_event) {
+  console.log('This is an event-based app');
+  // Require eventId in scope
+} else {
+  console.log('This is an organisation-based app');
+  // Require organisationId in scope
+}
+```
+
+### Dynamic Context Handling
+
+```tsx
+// components/AdaptiveComponent.tsx
+import { getAppConfig } from '@jmruthers/pace-core/rbac';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+function AdaptiveComponent({ appId }) {
+  const { selectedOrganisationId, selectedEventId } = useUnifiedAuth();
+  const [appConfig, setAppConfig] = useState(null);
+  
+  useEffect(() => {
+    const loadAppConfig = async () => {
+      const config = await getAppConfig(appId);
+      setAppConfig(config);
+    };
+    loadAppConfig();
+  }, [appId]);
+  
+  if (!appConfig) return <div>Loading app configuration...</div>;
+  
+  // Determine required context based on app type
+  const scope = appConfig.requires_event 
+    ? { eventId: selectedEventId, appId }
+    : { organisationId: selectedOrganisationId, appId };
+  
+  return (
+    <PermissionEnforcer
+      permissions={['read:data']}
+      operation="data-access"
+      scope={scope}
+    >
+      <AppContent />
+    </PermissionEnforcer>
+  );
+}
+```
 
 ## Next Steps