@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/rbac/README.md

@@ -1,91 +1,48 @@
 # RBAC System
 
-> **📚 New to RBAC?** Start with the [Quick Start Guide](./quick-start.md) to get up and running in 10 minutes.
+> **📚 New to RBAC?** Start with the [Quick Start Guide](./quick-start.md) to get up and running in 5 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 { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+import { useCan, PermissionGuard } from '@jmruthers/pace-core/rbac';
 
 function MyComponent() {
+  const { hasPermission, isLoading } = useCan();
+  
+  if (isLoading) return <div>Loading...</div>;
+  
   return (
-    <PagePermissionGuard
-      pageName="users"
-      operation="read"
-      fallback={<div>Access Denied</div>}
+    <PermissionGuard
+      userId="user-123"
+      scope={{ organisationId: "org-456" }}
+      permission="read:users"
     >
       <UserList />
-    </PagePermissionGuard>
+    </PermissionGuard>
   );
 }
 ```
 
 ## 📖 Core Concepts
 
-- **[Quick Start](./quick-start.md)** - Get up and running in 10 minutes (foolproof guide)
+- **[Quick Start](./quick-start.md)** - Get up and running in 5 minutes
 - **[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
-
-## 🏗️ 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**
+- **[Super Admin Guide](./super-admin-guide.md)** - Super admin access implementation
+- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
 
 ## 🎯 Key Features
 
-- **🔐 Secure by Default** - Organisation context enforced, RLS integrated, database-first API
-- **⚡ High Performance** - Intelligent caching with 60s TTL, optimized RPC calls
+- **🔐 Secure by Default** - Organisation context enforced, RLS integrated
+- **⚡ High Performance** - Intelligent caching with 60s TTL
 - **🎨 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
 
@@ -115,58 +72,27 @@ 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 { 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);
+import { RBACProvider } from '@jmruthers/pace-core/rbac';
 
 function App() {
   return (
-    <UnifiedAuthProvider supabaseClient={supabase}>
+    <UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
       <OrganisationProvider>
-        <YourApp />
+        <RBACProvider>
+          <YourApp />
+        </RBACProvider>
       </OrganisationProvider>
     </UnifiedAuthProvider>
   );
@@ -176,26 +102,38 @@ function App() {
 ### 2. Check Permissions
 
 ```tsx
-import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
-
-function UserActions() {
+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]);
+  
   return (
     <div>
-      <PagePermissionGuard
-        pageName="users"
-        operation="update"
-        fallback={null}
-      >
-        <EditButton />
-      </PagePermissionGuard>
-      
-      <PagePermissionGuard
-        pageName="users"
-        operation="delete"
-        fallback={null}
-      >
-        <DeleteButton />
-      </PagePermissionGuard>
+      {canEdit && <EditButton />}
+      {canDelete && <DeleteButton />}
     </div>
   );
 }
@@ -204,44 +142,39 @@ function UserActions() {
 ### 3. Protect Components
 
 ```tsx
-import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+import { PermissionGuard } from '@jmruthers/pace-core/rbac';
 
 function AdminPanel() {
   return (
-    <PagePermissionGuard
-      pageName="admin"
-      operation="read"
+    <PermissionGuard
+      userId="user-123"
+      scope={{ organisationId: "org-456" }}
+      permission="manage:users"
       fallback={<div>Access denied</div>}
     >
       <UserManagement />
-    </PagePermissionGuard>
+    </PermissionGuard>
   );
 }
 ```
 
 ## 🎨 Permission Format
 
-The RBAC system uses **page-level permissions** with the format: `{operation}:page.{pageName}`
+Permissions follow the format: `{operation}:{resource}[.{context}]`
 
 ### Operations
-- `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
+- `read` - View resources
+- `create` - Create new resources
+- `update` - Modify existing resources
+- `delete` - Remove resources
+- `manage` - Full resource management
+
+### Examples
+- `read:users` - View user information
 - `create:events` - Create new events
-- `update:events` - Modify existing events
-- `delete:events` - Remove events
+- `update:organisations` - Modify organisation settings
+- `delete:data` - Remove data
+- `manage:system` - Full system administration
 
 ## 🔒 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. **Note**: For page-level permissions, prefer `PagePermissionGuard` component.
+Check individual permissions with caching and loading states.
 
 ```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, selectedEventId } = useUnifiedAuth();
+  const { user, selectedOrganisationId } = useUnifiedAuth();
   
-  // For non-page permissions (e.g., event-app permissions)
+  // Explicit scope required for useCan
   const { can, isLoading, error } = useCan(
     user?.id || '',
     { 
       organisationId: selectedOrganisationId || '',
-      eventId: selectedEventId || undefined,
-      appId: undefined // Will be resolved automatically
+      eventId: undefined,
+      appId: undefined
     },
-    'read:events', // Event-app permission
-    undefined // No pageId for event-app permissions
+    'update:users',
+    'page-123' // optional pageId
   );
 
   if (error) return <div>Error: {error.message}</div>;
@@ -43,7 +43,7 @@ function UserActions() {
 
   return (
     <div>
-      {can && <EventActions />}
+      {can && <EditButton />}
     </div>
   );
 }
@@ -663,37 +663,6 @@ 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