@jmruthers/pace-core 0.5.109 → 0.5.111

package/docs/rbac/README.md

@@ -12,10 +12,35 @@ The PACE Core RBAC (Role-Based Access Control) system provides comprehensive per
 
 ## 🚨 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)
+**MANDATORY Setup Steps (in order):**
+
+1. **Call `setupRBAC(supabase)` FIRST** - Must be called before any RBAC components or hooks
+   ```typescript
+   // In main.tsx or App.tsx
+   import { setupRBAC } from '@jmruthers/pace-core/rbac';
+   setupRBAC(supabase); // Must be BEFORE rendering App
+   ```
+
+2. **Wrap app with providers** in exact order:
+   ```tsx
+   <UnifiedAuthProvider supabaseClient={supabase} appName={APP_NAME}>
+     <OrganisationProvider>
+       <YourApp />
+     </OrganisationProvider>
+   </UnifiedAuthProvider>
+   ```
+
+3. **Use `PagePermissionGuard` for ALL pages** - This is the ONLY correct way to protect pages
+   ```tsx
+   <PagePermissionGuard pageName="dashboard" operation="read">
+     <DashboardContent />
+   </PagePermissionGuard>
+   ```
+
+4. **Database must be configured** - App, pages, and permissions must exist in database
+5. **User must have organisation role** - Users need roles in `rbac_organisation_roles` table
+6. **App name must match exactly** - Environment variable must match `rbac_apps.name` (case-sensitive)
+7. **Never query RBAC tables directly** - Always use `PagePermissionGuard` or RBAC API functions
 
 ## 🚀 Quick Start
 
@@ -179,34 +204,58 @@ function App() {
 }
 ```
 
-### 2. Check Permissions
+### 2. Protect Pages with PagePermissionGuard
+
+**⚠️ CRITICAL: Always use `PagePermissionGuard` for page-level access. This is the ONLY way to ensure permissions are checked correctly.**
 
 ```tsx
 import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
 
-function UserActions() {
+function UsersPage() {
   return (
-    <div>
-      <PagePermissionGuard
-        pageName="users"
-        operation="update"
-        fallback={null}
-      >
-        <EditButton />
-      </PagePermissionGuard>
-      
-      <PagePermissionGuard
-        pageName="users"
-        operation="delete"
-        fallback={null}
-      >
-        <DeleteButton />
-      </PagePermissionGuard>
-    </div>
+    <PagePermissionGuard
+      pageName="users"
+      operation="read"
+      fallback={<div>You don't have permission to view this page</div>}
+    >
+      <div>
+        <h1>User Management</h1>
+        
+        {/* Multiple operations on same page */}
+        <PagePermissionGuard
+          pageName="users"
+          operation="create"
+          fallback={null}
+        >
+          <AddUserButton />
+        </PagePermissionGuard>
+        
+        <PagePermissionGuard
+          pageName="users"
+          operation="update"
+          fallback={null}
+        >
+          <EditUserButtons />
+        </PagePermissionGuard>
+        
+        <PagePermissionGuard
+          pageName="users"
+          operation="delete"
+          fallback={null}
+        >
+          <DeleteUserButtons />
+        </PagePermissionGuard>
+      </div>
+    </PagePermissionGuard>
   );
 }
 ```
 
+**Important**: 
+- `pageName` must match the `page_name` in `rbac_app_pages` table
+- `operation` can be: `read`, `create`, `update`, or `delete`
+- Permission checked in database is: `{operation}:page.{pageName}` (e.g., `read:page.users`)
+
 ### 3. Protect Components
 
 ```tsx
@@ -230,24 +279,51 @@ function AdminPanel() {
 The RBAC system uses **page-level permissions** with the format: `{operation}:page.{pageName}`
 
 ### Operations
-- `read` - View page content
+- `read` - View page content (required for `PagePermissionGuard` with `operation="read"`)
 - `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:events` - Modify existing events
-- `delete:events` - Remove events
+
+### Page-Level Permission Format
+
+When you use `PagePermissionGuard` with:
+```tsx
+<PagePermissionGuard pageName="dashboard" operation="read">
+```
+
+The system checks for permission: `read:page.dashboard` in the database.
+
+### Database Structure
+
+Permissions are stored in `rbac_page_permissions` table with:
+- `app_page_id` - Links to `rbac_app_pages` table
+- `operation` - One of: `read`, `create`, `update`, `delete`
+- `role_name` - User's role (e.g., `org_admin`, `leader`, `member`)
+- `allowed` - Boolean (`true` if user has permission, `false` otherwise)
+- `organisation_id` - Organisation context (must match user's organisation)
+
+### Examples
+
+If you have a page named `"users"` and check `operation="read"`:
+- System checks: `read:page.users` permission
+- Database query looks in `rbac_page_permissions` for matching `operation='read'` and `page_name='users'`
+- Permission is granted if user's role has `allowed=true` for that page, operation, and organisation
+
+### Complete Example
+
+```sql
+-- Database setup for a "users" page with read permission for org_admin role
+INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed, organisation_id)
+VALUES (
+  (SELECT id FROM rbac_app_pages WHERE page_name = 'users'),
+  'read',
+  'org_admin',
+  true,
+  'your-organisation-id'::uuid
+);
+```
+
+This allows users with `org_admin` role to access `<PagePermissionGuard pageName="users" operation="read">`.
 
 ## 🔒 Security Features
 

package/docs/rbac/advanced-patterns.md

@@ -29,7 +29,7 @@ function UserManagementDashboard({ userId, scope }) {
           { userId, scope, permission: 'create:users' },
           { userId, scope, permission: 'update:users' },
           { userId, scope, permission: 'delete:users' },
-          { userId, scope, permission: 'manage:roles' },
+          { userId, scope, permission: 'update:roles' },
           { userId, scope, permission: 'read:audit_logs' }
         ]);
         
@@ -52,7 +52,7 @@ function UserManagementDashboard({ userId, scope }) {
       {permissions['create:users'] && <CreateUserButton />}
       {permissions['update:users'] && <EditUserButton />}
       {permissions['delete:users'] && <DeleteUserButton />}
-      {permissions['manage:roles'] && <RoleManagement />}
+      {permissions['update:roles'] && <RoleManagement />}
       {permissions['read:audit_logs'] && <AuditLogs />}
     </div>
   );
@@ -289,7 +289,7 @@ function HierarchicalUserManagement({ userId, scope, users }) {
         const permissionChecks = await Promise.all(
           users.map(async (user) => {
             // Check if current user can manage this user based on hierarchy
-            const canManage = await hasPermission('manage:users', { 
+            const canUpdate = await hasPermission('update:users', { 
               userId, 
               scope: { 
                 ...scope, 
@@ -592,27 +592,20 @@ describe('Advanced Permission Patterns', () => {
   });
 
   test('should handle conditional permissions', async () => {
-    const mockHasPermission = jest.fn()
-      .mockResolvedValueOnce(true)  // canEditAny
-      .mockResolvedValueOnce(false); // canDeleteAny
-
-    (useCan as jest.Mock).mockReturnValue({
-      hasPermission: mockHasPermission,
-      isLoading: false,
-      error: null
-    });
-
-    const { result } = renderHook(() => useCan());
+    // Mock the underlying permission API
+    vi.mock('../api', () => ({
+      isPermittedCached: vi.fn().mockResolvedValue(true)
+    }));
 
-    const canEdit = await result.current.hasPermission('update:users', {
-      userId: 'user-123',
-      scope: { organisationId: 'org-456' }
-    });
+    const { result } = renderHook(() => useCan(
+      'user-123',
+      { organisationId: 'org-456', eventId: undefined, appId: undefined },
+      'update:users'
+    ));
 
-    expect(canEdit).toBe(true);
-    expect(mockHasPermission).toHaveBeenCalledWith('update:users', {
-      userId: 'user-123',
-      scope: { organisationId: 'org-456' }
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+      expect(result.current.can).toBe(true);
     });
   });
 

package/docs/rbac/api-reference.md

@@ -247,43 +247,90 @@ function UserActions() {
 
 ### PagePermissionGuard
 
-Conditionally render children based on page-level permissions.
+**⚠️ CRITICAL: This is the PRIMARY component for protecting pages.** Always use `PagePermissionGuard` for page-level permissions. It automatically resolves scope from context and checks permissions in the database.
+
+**Permission Format**: The component checks for permissions in the format `{operation}:page.{pageName}` (e.g., `read:page.dashboard`).
 
 ```typescript
 interface PagePermissionGuardProps {
-  pageName: string;
-  operation: 'read' | 'write' | 'delete' | 'manage';
-  children: React.ReactNode;
-  fallback?: React.ReactNode;
-  strictMode?: boolean;
-  auditLog?: boolean;
-  pageId?: UUID;
-  scope?: Scope;
-  onDenied?: (pageName: string, operation: string, reason: string) => void;
-  loading?: React.ReactNode;
+  pageName: string;           // Page name (e.g., "dashboard", "users") - must match rbac_app_pages.page_name
+  operation: 'read' | 'create' | 'update' | 'delete';  // Operation being performed
+  children: React.ReactNode;   // Content to render if user has permission
+  fallback?: React.ReactNode;  // Content to render if user lacks permission (default: Access Denied component)
+  strictMode?: boolean;        // Enable strict mode for security logging (default: true)
+  auditLog?: boolean;          // Enable audit logging (default: true)
+  pageId?: string;             // Optional page ID override (defaults to pageName)
+  scope?: Scope;               // Optional scope override (defaults to resolving from context)
+  onDenied?: (pageName: string, operation: string) => void;  // Callback when access denied
+  loading?: React.ReactNode;   // Loading state component (default: "Checking permissions...")
 }
 ```
 
-#### Usage
+#### Basic Usage
 
 ```tsx
 import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
 
-function AdminPage() {
+function DashboardPage() {
+  return (
+    <PagePermissionGuard
+      pageName="dashboard"
+      operation="read"
+      fallback={<div>You don't have permission to view the dashboard</div>}
+    >
+      <DashboardContent />
+    </PagePermissionGuard>
+  );
+}
+```
+
+#### Multiple Operations
+
+```tsx
+function UsersPage() {
   return (
     <div>
+      {/* Read permission - show user list */}
       <PagePermissionGuard
-        pageName="admin"
+        pageName="users"
         operation="read"
-        fallback={<div>Admin access required</div>}
+        fallback={null}
+      >
+        <UserList />
+      </PagePermissionGuard>
+      
+      {/* Create permission - show add button */}
+      <PagePermissionGuard
+        pageName="users"
+        operation="create"
+        fallback={null}
       >
-        <AdminSettings />
+        <AddUserButton />
+      </PagePermissionGuard>
+      
+      {/* Update permission - show edit buttons */}
+      <PagePermissionGuard
+        pageName="users"
+        operation="update"
+        fallback={null}
+      >
+        <EditUserButtons />
       </PagePermissionGuard>
     </div>
   );
 }
 ```
 
+#### Important Notes
+
+1. **Automatic Scope Resolution**: `PagePermissionGuard` automatically resolves `organisationId` from `UnifiedAuthProvider` context. You don't need to pass `scope` unless you need custom scope.
+
+2. **Permission Format**: The component checks for `{operation}:page.{pageName}` in the database. Ensure your `rbac_page_permissions` table has entries matching this format.
+
+3. **Loading State**: The component shows a loading state while checking permissions. Provide a custom `loading` prop if needed.
+
+4. **Error Handling**: If permission check fails, the component shows the `fallback`. Check browser console for `[PagePermissionGuard]` logs to debug issues.
+
 ### NavigationGuard
 
 Conditionally render navigation items based on permissions.

package/docs/rbac/examples.md

@@ -234,7 +234,7 @@ function UserForm({ userId, scope, userData }) {
       if (!isLoading) {
         const [canEditRole, canEditPermissions] = await Promise.all([
           hasPermission('update:user_roles', { userId, scope }),
-          hasPermission('manage:permissions', { userId, scope })
+          hasPermission('update:permissions', { userId, scope })
         ]);
         
         setPermissions({ canEditRole, canEditPermissions });
@@ -295,7 +295,7 @@ function Navigation({ userId, scope }) {
     { id: 'users', label: 'Users', permission: 'read:users' },
     { id: 'events', label: 'Events', permission: 'read:events' },
     { id: 'settings', label: 'Settings', permission: 'read:settings' },
-    { id: 'admin', label: 'Admin', permission: 'manage:system' },
+    { id: 'admin', label: 'Admin', permission: 'update:system' },
   ];
 
   useEffect(() => {
@@ -693,19 +693,19 @@ test('renders fallback when user lacks permission', () => {
 ### Testing Hooks
 
 ```tsx
-import { renderHook, act } from '@testing-library/react';
+import { renderHook, waitFor } from '@testing-library/react';
 import { useCan } from '@jmruthers/pace-core/rbac';
 
 test('useCan hook returns permission result', async () => {
-  const { result } = renderHook(() => useCan());
+  const { result } = renderHook(() => useCan(
+    'user-123',
+    { organisationId: 'org-456', eventId: undefined, appId: undefined },
+    'read:users'
+  ));
   
-  await act(async () => {
-    const hasPermission = await result.current.hasPermission('read:users', {
-      userId: 'user-123',
-      scope: { organisationId: 'org-456' }
-    });
-    
-    expect(hasPermission).toBe(true);
+  await waitFor(() => {
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.can).toBe(true);
   });
 });
 ```
@@ -765,7 +765,7 @@ function EventDashboard() {
       </PermissionEnforcer>
       
       <PermissionEnforcer
-        permissions={['manage:participants']}
+        permissions={['update:participants']}
         operation="participant-management"
         fallback={null}
       >

package/docs/rbac/getting-started.md

@@ -70,32 +70,32 @@ export default App;
 
 ## 🎯 **When to Use What Pattern**
 
-### Pattern 1: PermissionEnforcer (Recommended for Pages)
-**Use when**: Protecting entire pages or large components
-**Benefits**: Automatic scope resolution, no manual context handling
+### Pattern 1: PagePermissionGuard (REQUIRED for Pages)
+**Use when**: Protecting entire pages or page-level access
+**Benefits**: Automatic scope resolution, page-level permission checking, strict mode enforcement
 
 ```tsx
-// components/Dashboard.tsx
-import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
+// pages/Dashboard.tsx
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
 
 function Dashboard() {
   return (
-    <div>
-      <h1>Dashboard</h1>
-      
-      {/* Automatic scope resolution - no manual context needed */}
-      <PermissionEnforcer
-        permissions={['read:events']}
-        operation="dashboard"
-        fallback={<div>Access Denied</div>}
-      >
+    <PagePermissionGuard
+      pageName="dashboard"
+      operation="read"
+      fallback={<div>Access Denied</div>}
+    >
+      <div>
+        <h1>Dashboard</h1>
         <EventContent />
-      </PermissionEnforcer>
-    </div>
+      </div>
+    </PagePermissionGuard>
   );
 }
 ```
 
+**⚠️ CRITICAL**: Always use `PagePermissionGuard` for pages. It's the only component that properly checks page-level permissions against the database.
+
 ### Pattern 2: usePermissions (For Data Fetching)
 **Use when**: You need the actual permission data for custom logic
 **Requirements**: Must provide explicit scope
@@ -150,7 +150,7 @@ function UserActions() {
       eventId: undefined,
       appId: undefined
     },
-    'manage:users',
+    'update:users',
     'page-123' // optional pageId
   );
 
@@ -239,7 +239,7 @@ function UserManagement({ userId, organisationId }) {
   const { can, isLoading, error } = useCan(
     userId || '',
     { organisationId: organisationId || '' },
-    'manage:users'
+    'update:users'
   );
 
   if (isLoading) return <div>Checking permissions...</div>;
@@ -495,7 +495,7 @@ function MyComponent() {
   const { can, isLoading, error } = useCan(
     user?.id || '',
     { organisationId: selectedOrganisationId || '' },
-    'manage:users'
+    'update:users'
   );
 
   if (isLoading) return <div>Checking permissions...</div>;