@jmruthers/pace-core 0.5.39 → 0.5.41

package/docs/rbac/rbac-rls-integration.md

@@ -0,0 +1,377 @@
+# RBAC-RLS Integration: Dynamic Permission Enforcement
+
+This document explains how to use the new RBAC-RLS integration system that allows dynamic permission enforcement based on configurable RBAC settings instead of hardcoded RLS policies.
+
+## Overview
+
+The RBAC-RLS integration solves the critical architectural issue where:
+- **RBAC permissions are configurable** - Organizations can set which roles have which CRUD permissions for each page
+- **RLS policies were hardcoded** - Database-level security policies were static and didn't respect the dynamic RBAC configuration
+- **Result:** Users with valid RBAC permissions were blocked by RLS policies, breaking core functionality
+
+## Key Features
+
+### 1. Dynamic Permission Checking
+- **`check_rbac_permission()`** - Checks permissions for basic operations
+- **`check_rbac_permission_with_context()`** - Checks permissions with resource context
+- Both functions respect the current RBAC configuration in real-time
+
+### 2. Automatic Policy Management
+- **`create_rbac_rls_policy()`** - Creates RBAC-aware RLS policies
+- **`update_rbac_policies_for_table()`** - Updates policies for a specific table
+- **`update_all_rbac_policies()`** - Updates all registered policies
+
+### 3. Change Detection
+- Automatic policy updates when RBAC permissions change
+- Audit logging of all policy changes
+- Health monitoring and validation
+
+## Quick Start
+
+### 1. Basic Usage
+
+```sql
+-- Check if current user can delete meals
+SELECT check_rbac_permission_with_context(
+  'delete',           -- operation
+  'meals',            -- page name
+  'org-uuid-here',    -- organisation_id
+  'event-123',        -- event_id (optional)
+  'CAKE'              -- app name
+);
+```
+
+### 2. Creating RBAC-Aware Policies
+
+```sql
+-- Create policies for a table
+SELECT create_rbac_rls_policy(
+  'cake_meal',        -- table name
+  'delete',           -- operation
+  'meals',            -- page name
+  'rbac_delete_meals', -- policy name (optional)
+  'organisation_id',  -- organisation column
+  'meal_event_id',    -- event column (optional)
+  'CAKE'              -- app name
+);
+```
+
+### 3. Registering Tables for Management
+
+```sql
+-- Register a table for automatic policy management
+SELECT register_rbac_table(
+  'cake_meal',                    -- table name
+  'meals',                        -- page name
+  'CAKE',                         -- app name
+  'organisation_id',              -- organisation column
+  'meal_event_id',                -- event column (optional)
+  ARRAY['read', 'create', 'update', 'delete'] -- operations
+);
+```
+
+## API Reference
+
+### Core Functions
+
+#### `check_rbac_permission(operation, page_name, event_id, organisation_id, app_name)`
+
+Checks if the current user has permission for a specific operation on a page.
+
+**Parameters:**
+- `operation` (text): The operation to check ('read', 'create', 'update', 'delete')
+- `page_name` (text): The page name to check permissions for
+- `event_id` (text, optional): Event context for event-scoped permissions
+- `organisation_id` (uuid, optional): Organisation context
+- `app_name` (text, optional): App name (defaults to 'CAKE')
+
+**Returns:** boolean
+
+**Example:**
+```sql
+SELECT check_rbac_permission('delete', 'meals', 'event-123', 'org-uuid', 'CAKE');
+```
+
+#### `check_rbac_permission_with_context(operation, page_name, resource_organisation_id, resource_event_id, app_name)`
+
+Checks RBAC permission with resource context, ensuring user has access to the specific resource.
+
+**Parameters:**
+- `operation` (text): The operation to check
+- `page_name` (text): The page name to check permissions for
+- `resource_organisation_id` (uuid): The organisation ID of the resource
+- `resource_event_id` (text, optional): The event ID of the resource
+- `app_name` (text, optional): App name (defaults to 'CAKE')
+
+**Returns:** boolean
+
+**Example:**
+```sql
+SELECT check_rbac_permission_with_context(
+  'delete', 'meals', resource.organisation_id, resource.meal_event_id, 'CAKE'
+);
+```
+
+### Policy Management Functions
+
+#### `create_rbac_rls_policy(table_name, operation, page_name, policy_name, organisation_column, event_column, app_name)`
+
+Creates or replaces an RLS policy with RBAC-aware permission checking.
+
+**Parameters:**
+- `table_name` (text): Name of the table
+- `operation` (text): Operation ('SELECT', 'INSERT', 'UPDATE', 'DELETE')
+- `page_name` (text): Page name for permission checking
+- `policy_name` (text, optional): Custom policy name
+- `organisation_column` (text, optional): Organisation column name (defaults to 'organisation_id')
+- `event_column` (text, optional): Event column name
+- `app_name` (text, optional): App name (defaults to 'CAKE')
+
+**Returns:** boolean
+
+#### `update_rbac_policies_for_table(table_name, page_name, app_name)`
+
+Updates all RBAC policies for a specific table.
+
+**Parameters:**
+- `table_name` (text): Name of the table
+- `page_name` (text): Page name
+- `app_name` (text, optional): App name (defaults to 'CAKE')
+
+**Returns:** boolean
+
+#### `update_all_rbac_policies()`
+
+Updates RBAC policies for all registered tables.
+
+**Returns:** Table with results for each table
+
+### Management Functions
+
+#### `register_rbac_table(table_name, page_name, app_name, organisation_column, event_column, operations)`
+
+Registers a table for RBAC policy management.
+
+**Parameters:**
+- `table_name` (text): Name of the table
+- `page_name` (text): Page name
+- `app_name` (text, optional): App name (defaults to 'CAKE')
+- `organisation_column` (text, optional): Organisation column name (defaults to 'organisation_id')
+- `event_column` (text, optional): Event column name
+- `operations` (text[], optional): Array of operations (defaults to ['read', 'create', 'update', 'delete'])
+
+**Returns:** boolean
+
+### Validation Functions
+
+#### `validate_rbac_rls_consistency()`
+
+Validates that RLS policies are consistent with RBAC configuration.
+
+**Returns:** Table with validation results
+
+#### `check_rbac_policy_health()`
+
+Checks the health and consistency of RBAC policies.
+
+**Returns:** Table with health check results
+
+## Migration Guide
+
+### From Hardcoded to Dynamic Policies
+
+#### Before (Hardcoded)
+```sql
+-- Old hardcoded policy
+CREATE POLICY "Users can delete meals for their events" ON cake_meal
+FOR DELETE TO public
+USING (EXISTS (SELECT 1 FROM rbac_event_app_roles r 
+  WHERE r.user_id = auth.uid() 
+    AND r.event_id::text = cake_meal.meal_event_id::text 
+    AND r.role = 'event_admin'::rbac_event_app_role));
+```
+
+#### After (Dynamic)
+```sql
+-- New RBAC-aware policy
+CREATE POLICY "rbac_delete_meals" ON cake_meal
+FOR DELETE
+USING (
+  check_rbac_permission_with_context(
+    'delete',
+    'meals',
+    organisation_id,
+    meal_event_id,
+    'CAKE'
+  )
+);
+```
+
+### Migration Steps
+
+1. **Register your table:**
+   ```sql
+   SELECT register_rbac_table('your_table', 'your_page', 'YOUR_APP');
+   ```
+
+2. **Update policies:**
+   ```sql
+   SELECT update_rbac_policies_for_table('your_table', 'your_page', 'YOUR_APP');
+   ```
+
+3. **Verify the migration:**
+   ```sql
+   SELECT * FROM check_rbac_policy_health();
+   ```
+
+## Best Practices
+
+### 1. Policy Naming
+- Use consistent naming: `rbac_{operation}_{page_name}`
+- Example: `rbac_delete_meals`, `rbac_read_deliveries`
+
+### 2. Error Handling
+- Always check return values from policy management functions
+- Monitor the `rbac_policy_audit` table for errors
+- Use health checks regularly
+
+### 3. Performance
+- The RBAC functions are optimized for performance
+- Consider caching for frequently accessed permissions
+- Monitor query performance with large datasets
+
+### 4. Security
+- Always use `check_rbac_permission_with_context()` for resource-specific operations
+- Validate organisation and event context
+- Test permission changes thoroughly
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Policies Not Created
+**Problem:** `create_rbac_rls_policy()` returns false
+**Solution:** Check that the table exists and you have proper permissions
+
+#### 2. Permission Checks Fail
+**Problem:** `check_rbac_permission()` returns false when it should return true
+**Solution:** 
+- Verify the user has the correct role in `rbac_event_app_roles`
+- Check that the page permissions exist in `rbac_page_permissions`
+- Ensure the app and page are properly configured
+
+#### 3. Policies Not Updating
+**Problem:** Changes to RBAC permissions don't reflect in RLS policies
+**Solution:**
+- Check that the table is registered in `rbac_policy_configs`
+- Verify the trigger is working: `SELECT * FROM rbac_policy_audit ORDER BY changed_at DESC LIMIT 10;`
+- Manually update: `SELECT update_rbac_policies_for_table('table_name', 'page_name');`
+
+### Debugging
+
+#### Check Policy Health
+```sql
+SELECT * FROM check_rbac_policy_health();
+```
+
+#### View Policy Audit Log
+```sql
+SELECT * FROM rbac_policy_audit 
+ORDER BY changed_at DESC 
+LIMIT 20;
+```
+
+#### Test Permission Check
+```sql
+-- Test with specific user context
+SELECT check_rbac_permission_with_context(
+  'delete', 'meals', 'org-uuid', 'event-123', 'CAKE'
+);
+```
+
+## Examples
+
+### Complete Table Migration
+
+```sql
+-- 1. Register the table
+SELECT register_rbac_table(
+  'cake_meal',
+  'meals',
+  'CAKE',
+  'organisation_id',
+  'meal_event_id',
+  ARRAY['read', 'create', 'update', 'delete']
+);
+
+-- 2. Update policies
+SELECT update_rbac_policies_for_table('cake_meal', 'meals', 'CAKE');
+
+-- 3. Verify
+SELECT * FROM check_rbac_policy_health() 
+WHERE table_name = 'cake_meal';
+```
+
+### Dynamic Permission Testing
+
+```sql
+-- Test different scenarios
+SELECT 
+  'planner delete meals' as test_case,
+  check_rbac_permission_with_context('delete', 'meals', 'org-uuid', 'event-123', 'CAKE') as result
+UNION ALL
+SELECT 
+  'planner delete deliveries',
+  check_rbac_permission_with_context('delete', 'deliveries', 'org-uuid', 'event-123', 'CAKE')
+UNION ALL
+SELECT 
+  'event_admin delete deliveries',
+  check_rbac_permission_with_context('delete', 'deliveries', 'org-uuid', 'event-123', 'CAKE');
+```
+
+## Monitoring and Maintenance
+
+### Regular Health Checks
+```sql
+-- Run this regularly to ensure system health
+SELECT * FROM validate_rbac_rls_consistency();
+```
+
+### Policy Audit
+```sql
+-- Monitor policy changes
+SELECT 
+  table_name,
+  policy_name,
+  action,
+  changed_at,
+  success,
+  error_message
+FROM rbac_policy_audit
+ORDER BY changed_at DESC;
+```
+
+### Performance Monitoring
+```sql
+-- Check for slow permission checks
+SELECT 
+  query,
+  calls,
+  total_time,
+  mean_time
+FROM pg_stat_statements
+WHERE query LIKE '%check_rbac_permission%'
+ORDER BY mean_time DESC;
+```
+
+## Conclusion
+
+The RBAC-RLS integration provides a robust, dynamic permission enforcement system that:
+
+1. **Respects RBAC configuration** - Policies automatically adapt to permission changes
+2. **Maintains security** - All permission checks are validated at the database level
+3. **Provides auditability** - Complete audit trail of all policy changes
+4. **Enables flexibility** - Organizations can configure permissions without code changes
+5. **Ensures consistency** - RBAC and RLS are always in sync
+
+This system solves the critical architectural issue and provides a foundation for scalable, maintainable permission management across the entire pace suite.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.39",
+  "version": "0.5.41",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {
@@ -104,6 +104,10 @@
     "./source/rbac": {
       "import": "./src/rbac/index.ts",
       "default": "./src/rbac/index.ts"
+    },
+    "./rbac/cli": {
+      "import": "./dist/rbac/cli/policy-manager.js",
+      "default": "./dist/rbac/cli/policy-manager.js"
     }
   },
   "files": [
@@ -151,7 +155,15 @@
     "docs:generate": "node scripts/generate-docs.js generate",
     "docs:update-index": "node scripts/generate-docs.js update-index",
     "docs:generate-api": "node scripts/generate-docs.js generate-api",
-    "docs:all": "node scripts/generate-docs.js all"
+    "docs:all": "node scripts/generate-docs.js all",
+    "_comment_rbac": "RBAC policy management utilities",
+    "rbac:list": "node dist/rbac/cli/policy-manager.js list",
+    "rbac:register": "node dist/rbac/cli/policy-manager.js register",
+    "rbac:update": "node dist/rbac/cli/policy-manager.js update",
+    "rbac:update-all": "node dist/rbac/cli/policy-manager.js update-all",
+    "rbac:health": "node dist/rbac/cli/policy-manager.js health",
+    "rbac:audit": "node dist/rbac/cli/policy-manager.js audit",
+    "rbac:test": "node dist/rbac/cli/policy-manager.js test"
   },
   "keywords": [
     "react",
@@ -209,6 +221,10 @@
   },
   "dependencies": {
     "@supabase/supabase-js": "^2.49.10",
-    "@tanstack/react-query": "^5.56.2"
+    "@tanstack/react-query": "^5.56.2",
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "cli-table3": "^0.6.3"
   }
 }