@jmruthers/pace-core 0.4.1 → 0.5.3

package/docs/rbac/README.md

@@ -1,48 +1,91 @@
 # RBAC System
 
-> **📚 New to RBAC?** Start with the [Quick Start Guide](./quick-start.md) to get up and running in 5 minutes.
+> **📚 New to RBAC?** Start with the [Quick Start Guide](./quick-start.md) to get up and running in 10 minutes.
 
 The PACE Core RBAC (Role-Based Access Control) system provides comprehensive permission management with organisation context enforcement, caching, and audit logging.
 
+## 🚨 Critical Rules (Follow These or It Won't Work)
+
+1. **Never make direct database queries** to `rbac_apps`, `rbac_global_roles`, or other RBAC tables
+2. **Always use `PagePermissionGuard`** for page-level permissions (not manual permission checks)
+3. **Always set up providers correctly** in the exact order shown
+4. **Use the exact app name** from your environment variable (must match database exactly)
+
 ## 🚀 Quick Start
 
 ```tsx
-import { useCan, PermissionGuard } from '@jmruthers/pace-core/rbac';
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
 
 function MyComponent() {
-  const { hasPermission, isLoading } = useCan();
-  
-  if (isLoading) return <div>Loading...</div>;
-  
   return (
-    <PermissionGuard
-      userId="user-123"
-      scope={{ organisationId: "org-456" }}
-      permission="read:users"
+    <PagePermissionGuard
+      pageName="users"
+      operation="read"
+      fallback={<div>Access Denied</div>}
     >
       <UserList />
-    </PermissionGuard>
+    </PagePermissionGuard>
   );
 }
 ```
 
 ## 📖 Core Concepts
 
-- **[Quick Start](./quick-start.md)** - Get up and running in 5 minutes
+- **[Quick Start](./quick-start.md)** - Get up and running in 10 minutes (foolproof guide)
 - **[API Reference](./api-reference.md)** - Complete API documentation
+- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
 - **[Examples](./examples.md)** - Practical usage examples
 - **[Advanced Patterns](./advanced-patterns.md)** - Complex scenarios and optimizations
-- **[Super Admin Guide](./super-admin-guide.md)** - Super admin access implementation
-- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
+
+## 🏗️ Architecture & Security Model
+
+### **Database-First Design**
+
+The RBAC system uses a **database-first architecture** where all permission logic resides in PostgreSQL functions:
+
+- ✅ **Primary API**: `get_rbac_permissions()` RPC function (runs with elevated privileges)
+- ✅ **Security**: RLS policies protect direct table access
+- ✅ **Performance**: Single RPC call vs multiple client queries
+- ✅ **Consistency**: All permission logic centralized in database
+
+**Why This Design?**
+
+1. **Security**: Client-side queries are protected by RLS policies. The RPC function is the **intended API** for permission checks.
+2. **Performance**: One RPC call fetches all permissions instead of multiple client queries
+3. **Correctness**: Database function contains the authoritative permission logic
+4. **Maintainability**: Permission logic in one place, not scattered across client code
+
+**Important**: The RBAC engine uses `get_rbac_permissions()` RPC for page-level permissions because:
+- Client queries to `rbac_page_permissions` are **intentionally blocked by RLS**
+- The RPC function validates access and returns only permissions for the user's roles
+- This is **not bypassing security** - it's using the **correct security API**
 
 ## 🎯 Key Features
 
-- **🔐 Secure by Default** - Organisation context enforced, RLS integrated
-- **⚡ High Performance** - Intelligent caching with 60s TTL
+- **🔐 Secure by Default** - Organisation context enforced, RLS integrated, database-first API
+- **⚡ High Performance** - Intelligent caching with 60s TTL, optimized RPC calls
 - **🎨 React Integration** - Hooks and components for easy UI integration
 - **🔄 Real-time Updates** - Automatic cache invalidation on permission changes
 - **📊 Audit Logging** - Complete audit trail for all permission checks
 - **🛡️ Type Safe** - Full TypeScript support with strict typing
+- **🏢 Flexible App Context** - Support for both organisation-based and event-based apps
+- **🔄 Automatic Context Resolution** - Event-based apps automatically resolve organisation context
+
+## 🔧 Recent Updates
+
+### Super Admin Bypass in Event Context (v2.0.0)
+Fixed an issue where super admins were unable to bypass permission checks in event-based apps. Super admins now have full access regardless of context type (organisation-based or event-based apps).
+
+```tsx
+// ✅ Super admin bypass now works in event context
+<PagePermissionGuard
+  pageName="admin-panel"
+  operation="read"
+  scope={{ eventId: 'event-456' }} // Only event context needed
+>
+  <AdminPanel />
+</PagePermissionGuard>
+```
 
 ## 🏗️ Architecture
 
@@ -72,27 +115,58 @@ graph TD
 - `isPermitted` - Server-side permission checking
 - `getAccessLevel` - Get user's access level
 - `getPermissionMap` - Get all permissions for a scope
+- `getAppConfig` - Get app configuration including context requirements
 
 ### Advanced Features
 - `SecureSupabaseClient` - Secure database access with context enforcement
 - `RBACCache` - Intelligent caching system
 - `AuditManager` - Complete audit logging
 
+## 🏢 App Context Requirements
+
+The RBAC system supports two types of applications:
+
+### Organisation-Based Apps (Default)
+- **Context**: Requires `organisationId` in scope
+- **Use case**: User management, organisation settings, general dashboards
+- **Database**: `rbac_apps.requires_event = false`
+
+### Event-Based Apps
+- **Context**: Requires `eventId` in scope, automatically resolves `organisationId` from event
+- **Use case**: Event registration, event management, event-specific reporting
+- **Database**: `rbac_apps.requires_event = true`
+
+```typescript
+// Check app configuration
+import { getAppConfig } from '@jmruthers/pace-core/rbac';
+
+const appConfig = await getAppConfig('app-123');
+if (appConfig?.requires_event) {
+  // Event-based app - require eventId
+  const scope = { eventId: 'event-123', appId: 'app-123' };
+} else {
+  // Organisation-based app - require organisationId
+  const scope = { organisationId: 'org-123', appId: 'app-123' };
+}
+```
+
 ## 🔧 Basic Usage
 
 ### 1. Setup
 
 ```tsx
 import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core';
-import { RBACProvider } from '@jmruthers/pace-core/rbac';
+import { setRBACAppName } from '@jmruthers/pace-core/utils';
+
+// CRITICAL: Set app name globally for RBAC resolution
+const APP_NAME = import.meta.env.VITE_APP_NAME;
+setRBACAppName(APP_NAME);
 
 function App() {
   return (
-    <UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+    <UnifiedAuthProvider supabaseClient={supabase}>
       <OrganisationProvider>
-        <RBACProvider>
-          <YourApp />
-        </RBACProvider>
+        <YourApp />
       </OrganisationProvider>
     </UnifiedAuthProvider>
   );
@@ -102,38 +176,26 @@ function App() {
 ### 2. Check Permissions
 
 ```tsx
-import { useCan } from '@jmruthers/pace-core/rbac';
-
-function UserActions({ userId }) {
-  const { hasPermission, isLoading } = useCan();
-  
-  const [canEdit, setCanEdit] = useState(false);
-  const [canDelete, setCanDelete] = useState(false);
-  
-  useEffect(() => {
-    const checkPermissions = async () => {
-      const editPerm = await hasPermission('update:users', {
-        userId,
-        scope: { organisationId: 'org-456' }
-      });
-      const deletePerm = await hasPermission('delete:users', {
-        userId,
-        scope: { organisationId: 'org-456' }
-      });
-      
-      setCanEdit(editPerm);
-      setCanDelete(deletePerm);
-    };
-    
-    if (!isLoading) {
-      checkPermissions();
-    }
-  }, [hasPermission, isLoading, userId]);
-  
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function UserActions() {
   return (
     <div>
-      {canEdit && <EditButton />}
-      {canDelete && <DeleteButton />}
+      <PagePermissionGuard
+        pageName="users"
+        operation="update"
+        fallback={null}
+      >
+        <EditButton />
+      </PagePermissionGuard>
+      
+      <PagePermissionGuard
+        pageName="users"
+        operation="delete"
+        fallback={null}
+      >
+        <DeleteButton />
+      </PagePermissionGuard>
     </div>
   );
 }
@@ -142,39 +204,44 @@ function UserActions({ userId }) {
 ### 3. Protect Components
 
 ```tsx
-import { PermissionGuard } from '@jmruthers/pace-core/rbac';
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
 
 function AdminPanel() {
   return (
-    <PermissionGuard
-      userId="user-123"
-      scope={{ organisationId: "org-456" }}
-      permission="manage:users"
+    <PagePermissionGuard
+      pageName="admin"
+      operation="read"
       fallback={<div>Access denied</div>}
     >
       <UserManagement />
-    </PermissionGuard>
+    </PagePermissionGuard>
   );
 }
 ```
 
 ## 🎨 Permission Format
 
-Permissions follow the format: `{operation}:{resource}[.{context}]`
+The RBAC system uses **page-level permissions** with the format: `{operation}:page.{pageName}`
 
 ### Operations
-- `read` - View resources
-- `create` - Create new resources
-- `update` - Modify existing resources
-- `delete` - Remove resources
-- `manage` - Full resource management
-
-### Examples
-- `read:users` - View user information
+- `read` - View page content
+- `create` - Create new content on page
+- `update` - Modify existing content on page
+- `delete` - Remove content from page
+- `manage` - Full page management
+
+### Page-Level Examples
+- `read:page.dashboard` - View dashboard page
+- `create:page.users` - Create users on users page
+- `update:page.settings` - Modify settings page
+- `delete:page.admin` - Remove content from admin page
+- `manage:page.system` - Full system page management
+
+### Event-App Permissions
+- `read:events` - View event information
 - `create:events` - Create new events
-- `update:organisations` - Modify organisation settings
-- `delete:data` - Remove data
-- `manage:system` - Full system administration
+- `update:events` - Modify existing events
+- `delete:events` - Remove events
 
 ## 🔒 Security Features
 

package/docs/rbac/api-reference.md

@@ -6,7 +6,7 @@ Complete API documentation for the PACE Core RBAC system.
 
 ### useCan
 
-Check individual permissions with caching and loading states.
+Check individual permissions with caching and loading states. **Note**: For page-level permissions, prefer `PagePermissionGuard` component.
 
 ```typescript
 interface UseCanReturn {
@@ -24,18 +24,18 @@ import { useCan } from '@jmruthers/pace-core/rbac';
 import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
 
 function UserActions() {
-  const { user, selectedOrganisationId } = useUnifiedAuth();
+  const { user, selectedOrganisationId, selectedEventId } = useUnifiedAuth();
   
-  // Explicit scope required for useCan
+  // For non-page permissions (e.g., event-app permissions)
   const { can, isLoading, error } = useCan(
     user?.id || '',
     { 
       organisationId: selectedOrganisationId || '',
-      eventId: undefined,
-      appId: undefined
+      eventId: selectedEventId || undefined,
+      appId: undefined // Will be resolved automatically
     },
-    'update:users',
-    'page-123' // optional pageId
+    'read:events', // Event-app permission
+    undefined // No pageId for event-app permissions
   );
 
   if (error) return <div>Error: {error.message}</div>;
@@ -43,7 +43,7 @@ function UserActions() {
 
   return (
     <div>
-      {can && <EditButton />}
+      {can && <EventActions />}
     </div>
   );
 }
@@ -663,6 +663,37 @@ console.log('User permissions:', permissions);
 // { 'users': ['read', 'create'], 'events': ['read'] }
 ```
 
+### getAppConfig
+
+Get app configuration including context requirements.
+
+```typescript
+function getAppConfig(appId: UUID): Promise<{ requires_event: boolean } | null>;
+```
+
+#### Usage
+
+```tsx
+import { getAppConfig } from '@jmruthers/pace-core/rbac';
+
+// Check app configuration
+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
+}
+```
+
+#### Return Values
+
+- `{ requires_event: true }` - Event-based app requiring event context
+- `{ requires_event: false }` - Organisation-based app requiring organisation context
+- `null` - App not found or inactive
+
 ## Secure Client
 
 ### SecureSupabaseClient