@jmruthers/pace-core 0.5.54 → 0.5.55

package/docs/core-concepts/rbac-system.md

@@ -52,7 +52,8 @@ Permissions define specific actions users can perform on resources.
 - **read** - View resources
 - **update** - Modify existing resources
 - **delete** - Remove resources
-- **manage** - Full resource management
+
+> **⚠️ Important**: The `manage` operation has been removed for RBAC compliance. Use specific CRUD operations instead.
 
 #### Common Resources
 - **users** - User management
@@ -66,8 +67,10 @@ Permissions define specific actions users can perform on resources.
 - `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
 - `read:events` - View event information (event-app permission)
+- `create:events` - Create new events
+- `update:events` - Modify existing events
+- `delete:events` - Remove events
 
 ### Permission Hierarchy
 
@@ -75,7 +78,7 @@ Permissions follow a hierarchical structure based on organisation roles:
 
 ```
 Organisation Admin
-├── All page permissions (read:page.*, create:page.*, update:page.*, delete:page.*, manage:page.*)
+├── All page permissions (read:page.*, create:page.*, update:page.*, delete:page.*)
 ├── All event-app permissions (read:events, create:events, update:events, delete:events)
 
 Leader
@@ -158,22 +161,27 @@ Permissions can be scoped to specific resources:
 
 The RBAC system uses a **database-first architecture** where all permission logic resides in PostgreSQL functions:
 
-- **RPC Functions** - All permission checks use `get_rbac_permissions()` RPC function
+- **RPC Functions** - All permission checks use `rbac_permissions_get()` RPC function
 - **RLS Protection** - Direct table access is blocked by Row Level Security policies
 - **Elevated Privileges** - RPC functions run with elevated privileges to bypass RLS
 - **Single Source of Truth** - All permission logic centralized in database functions
+- **No Hardcoded Permissions** - All permissions are stored in and retrieved from the database
 
 ### Permission Validation
 
 - **Runtime Checking** - Permissions are validated on every request
-- **Caching** - Permission results are cached for performance
+- **Caching** - Permission results are cached for performance with automatic invalidation
 - **Fallback Handling** - Graceful degradation when permissions are unavailable
+- **CRUD-Only Operations** - Only read, create, update, delete operations are allowed
+- **Automatic Cache Invalidation** - Cache is automatically cleared when permissions change
 
 ### Audit Logging
 
-- **Permission Checks** - All permission checks are logged
+- **Permission Checks** - All permission checks are logged with cache source tracking
 - **Access Attempts** - Failed access attempts are tracked
-- **Permission Changes** - Role and permission modifications are audited
+- **Permission Changes** - Role and permission modifications are automatically audited via database triggers
+- **Cache Invalidation** - Cache invalidation events are logged for debugging
+- **Role Changes** - All role grants and revocations are automatically logged
 
 ### Security Enforcement
 
@@ -187,31 +195,32 @@ The RBAC system provides dedicated database functions for managing user roles. T
 
 ### Key Functions
 
-- **`grant_organisation_role()`** - Grant organisation roles to users
-- **`revoke_organisation_role()`** - Revoke organisation roles from users  
-- **`grant_global_role()`** - Grant global roles (like super_admin)
-- **`revoke_global_role()`** - Revoke global roles
-- **`grant_event_app_role()`** - Grant event-app specific roles
-- **`revoke_event_app_role()`** - Revoke event-app specific roles
-- **`get_user_roles()`** - Get all roles for a user
+- **`rbac_role_grant()`** - Grant roles to users (organisation, global, or event-app)
+- **`rbac_role_revoke()`** - Revoke roles from users
+- **`rbac_permissions_get()`** - Get all permissions for a user in a context
+- **`rbac_permission_check()`** - Check if a user has a specific permission
+- **`rbac_roles_list()`** - List all available roles
+- **`rbac_role_validate()`** - Validate if a user has a specific role
 
 ### Usage Example
 
 ```sql
 -- Grant a member role to a user
-SELECT grant_organisation_role(
+SELECT rbac_role_grant(
     'user-uuid-here',
     'org-uuid-here', 
     'member',
+    'organisation',
     auth.uid(),
     'Welcome to the team!'
 );
 
 -- Promote user to leader
-SELECT grant_organisation_role(
+SELECT rbac_role_grant(
     'user-uuid-here',
     'org-uuid-here',
     'leader', 
+    'organisation',
     auth.uid(),
     'Promoted due to excellent performance'
 );
@@ -219,6 +228,50 @@ SELECT grant_organisation_role(
 
 For complete documentation on role management functions, see **[Role Management Functions](../rbac/role-management-functions.md)**.
 
+## RBAC Compliance & Recent Changes
+
+### Database-Driven Permissions
+
+PACE Core RBAC is now **100% compliant** with enterprise RBAC requirements:
+
+- **No Hardcoded Permissions** - All permissions are stored in and retrieved from the database
+- **CRUD Operations Only** - Only read, create, update, delete operations are allowed (no 'manage' operations)
+- **Automatic Cache Invalidation** - Cache is automatically cleared when permissions change via database triggers
+- **Comprehensive Audit Logging** - All permission changes and role modifications are automatically logged
+
+### Key Compliance Features
+
+#### 1. Database-First Architecture
+- All permission logic resides in PostgreSQL RPC functions
+- No hardcoded permission mappings in application code
+- Single source of truth for all permissions
+
+#### 2. Automatic Cache Management
+- Cache invalidation triggered by database changes
+- Real-time subscription to permission changes
+- Pattern-based cache clearing for optimal performance
+
+#### 3. Complete Audit Trail
+- Database triggers automatically log all role and permission changes
+- Cache source tracking in audit events
+- Comprehensive metadata for compliance reporting
+
+#### 4. Organisation-Specific Permissions
+- Each organisation can define custom page-level permissions
+- Admin app integration for permission management
+- Dynamic RLS policies based on database permissions
+
+### Migration from Legacy Systems
+
+If you're upgrading from a system with hardcoded permissions:
+
+1. **Remove Hardcoded Permission Mappings** - Replace with database queries
+2. **Update Permission Checks** - Use `rbac_permissions_get()` RPC function
+3. **Replace 'manage' Operations** - Use specific CRUD operations instead
+4. **Enable Cache Invalidation** - Ensure realtime subscriptions are active
+
+For detailed migration instructions, see the **[RBAC Migration Guide](../migration/rbac-migration.md)**.
+
 ## What's Next?
 
 - **[Role Management Functions](../rbac/role-management-functions.md)** - Complete guide to role management functions

package/docs/getting-started/examples/basic-auth-app.md

@@ -492,7 +492,6 @@ The app uses PACE Core's design system. You can customize:
 - **Forms**: Use PACE Core's Form components
 - **Data Tables**: Add DataTable for data management
 - **Permissions**: Implement RBAC with useCan hook
-- **Print Reports**: Add PrintLayout components
 
 ## 📚 Next Steps
 

package/docs/implementation-guides/datatable-rbac-usage.md

@@ -38,8 +38,8 @@ function DishesPage() {
         creation: true,           // Will be controlled by create:page.dishes permission
         editing: true,            // Will be controlled by update:page.dishes permission
         deletion: true,           // Will be controlled by delete:page.dishes permission
-        export: true,             // Will be controlled by manage:page.dishes permission
-        import: true              // Will be controlled by manage:page.dishes permission
+        export: true,             // Will be controlled by read:page.dishes permission
+        import: true              // Will be controlled by create:page.dishes permission
       }}
       getRowId={(row) => row.id}
     />
@@ -87,8 +87,8 @@ The DataTable now checks the following page-based permissions:
 | **Create Button** | `create:page.{pageId}` | Controls create functionality |
 | **Edit Actions** | `update:page.{pageId}` | Controls edit/update functionality |
 | **Delete Actions** | `delete:page.{pageId}` | Controls delete functionality |
-| **Export** | `manage:page.{pageId}` | Controls export functionality |
-| **Import** | `manage:page.{pageId}` | Controls import functionality |
+| **Export** | `read:page.{pageId}` | Controls export functionality |
+| **Import** | `create:page.{pageId}` | Controls import functionality |
 
 ### Role-Based Examples
 
@@ -109,8 +109,8 @@ The DataTable now checks the following page-based permissions:
     creation: true,    // ✅ Allowed if planner has create:page.dishes
     editing: true,     // ✅ Allowed if planner has update:page.dishes  
     deletion: false,   // ❌ Disabled if planner lacks delete:page.dishes
-    export: true,      // ✅ Allowed if planner has manage:page.dishes
-    import: false      // ❌ Disabled if planner lacks manage:page.dishes
+    export: true,      // ✅ Allowed if planner has read:page.dishes
+    import: false      // ❌ Disabled if planner lacks create:page.dishes
   }}
   getRowId={(row) => row.id}
 />
@@ -133,8 +133,8 @@ The DataTable now checks the following page-based permissions:
     creation: false,   // ❌ Disabled - viewer typically lacks create:page.dishes
     editing: false,    // ❌ Disabled - viewer typically lacks update:page.dishes
     deletion: false,   // ❌ Disabled - viewer typically lacks delete:page.dishes
-    export: false,     // ❌ Disabled - viewer typically lacks manage:page.dishes
-    import: false      // ❌ Disabled - viewer typically lacks manage:page.dishes
+    export: false,     // ❌ Disabled - viewer typically lacks read:page.dishes
+    import: false      // ❌ Disabled - viewer typically lacks create:page.dishes
   }}
   getRowId={(row) => row.id}
 />
@@ -291,8 +291,8 @@ function DishesPage() {
           creation: true,    // Controlled by create:page.dishes permission
           editing: true,     // Controlled by update:page.dishes permission
           deletion: true,    // Controlled by delete:page.dishes permission
-          export: true,      // Controlled by manage:page.dishes permission
-          import: true       // Controlled by manage:page.dishes permission
+          export: true,      // Controlled by read:page.dishes permission
+          import: true       // Controlled by create:page.dishes permission
         }}
         onCreateRow={handleCreateDish}
         onEditRow={handleEditDish}
@@ -311,6 +311,7 @@ This implementation ensures that:
 - Users with `create:page.dishes` can create new dishes
 - Users with `update:page.dishes` can edit existing dishes
 - Users with `delete:page.dishes` can delete dishes
-- Users with `manage:page.dishes` can export/import data
+- Users with `read:page.dishes` can export data
+- Users with `create:page.dishes` can import data
 
 The DataTable will automatically show/hide features based on the user's actual permissions for the dishes page.