@jmruthers/pace-core 0.5.109 → 0.5.111

package/docs/rbac/quick-start.md

@@ -25,9 +25,11 @@ A simple user management app that demonstrates:
 
 1. **ALWAYS call `setupRBAC()` first** - This is MANDATORY and must be called before any RBAC features
 2. **Never make direct database queries** to `rbac_apps`, `rbac_global_roles`, or other RBAC tables
-3. **Always use `PagePermissionGuard`** for page-level permissions (not manual permission checks)
-4. **Always set up providers correctly** in the exact order shown
-5. **Use the exact app name** from your environment variable (must match database exactly)
+3. **ALWAYS use `PagePermissionGuard`** for page-level permissions - This is the ONLY way to properly protect pages
+4. **ALWAYS set up providers correctly** in the exact order shown below
+5. **Use the exact app name** from your environment variable (must match database exactly, case-sensitive)
+6. **Ensure database setup is complete** before starting the app - App must be registered with pages and permissions
+7. **User must have organisation role** - Users need roles assigned in `rbac_organisation_roles` table
 
 ## 🚀 Step-by-Step Implementation
 
@@ -127,8 +129,11 @@ WHERE a.name = 'user-manager';
 
 #### 5.3 Set Up Page Permissions
 
+**CRITICAL**: Page permissions use the format `{operation}:page.{pageName}` (e.g., `read:page.dashboard`). The database stores permissions per page per role per organisation.
+
 ```sql
 -- Set up basic permissions for each page (replace 'user-manager' with your actual app name)
+-- IMPORTANT: Replace the organisation_id UUID with your actual organisation ID
 WITH app_pages AS (
   SELECT ap.id as page_id, ap.page_name, a.id as app_id
   FROM rbac_app_pages ap
@@ -146,10 +151,24 @@ SELECT
     WHEN role.role_name = 'member' AND ap.page_name IN ('dashboard', 'users') THEN true
     ELSE false
   END,
-  '00000000-0000-0000-0000-000000000000'::uuid -- Replace with your organisation ID
+  '00000000-0000-0000-0000-000000000000'::uuid -- ⚠️ REPLACE THIS with your actual organisation ID
 FROM app_pages ap
 CROSS JOIN (SELECT unnest(ARRAY['read', 'create', 'update', 'delete']) as operation) op
 CROSS JOIN (SELECT unnest(ARRAY['org_admin', 'leader', 'member']) as role_name) role;
+
+-- Verify permissions were created correctly
+SELECT 
+  a.name as app_name,
+  ap.page_name,
+  pp.operation,
+  pp.role_name,
+  pp.allowed,
+  pp.organisation_id
+FROM rbac_page_permissions pp
+JOIN rbac_app_pages ap ON pp.app_page_id = ap.id
+JOIN rbac_apps a ON ap.app_id = a.id
+WHERE a.name = 'user-manager'
+ORDER BY ap.page_name, pp.operation, pp.role_name;
 ```
 
 #### 5.4 Assign User Roles
@@ -202,28 +221,23 @@ if (!supabaseUrl || !supabaseAnonKey) {
 export const supabase = createClient(supabaseUrl, supabaseAnonKey)
 ```
 
-### 8. Initialize RBAC (MANDATORY - NEW STEP!)
+### 8. Initialize RBAC (MANDATORY!)
 
-**CRITICAL**: You MUST call `setupRBAC()` before using any RBAC features. Create `src/lib/rbac-setup.ts`:
+**CRITICAL**: You MUST call `setupRBAC()` before using any RBAC features. This configures rate limiting (default: 1000 requests/minute) and enables security validation.
 
-```typescript
-// src/lib/rbac-setup.ts
-import { setupRBAC } from '@jmruthers/pace-core/rbac'
-import { supabase } from './supabase'
-
-// ⚠️ REQUIRED: Initialize RBAC before using any RBAC features
-setupRBAC(supabase)
-```
-
-**Then import this in your main entry point:**
+**Option 1: Setup in main entry point (Recommended)**
 
 ```typescript
 // src/main.tsx
 import React from 'react'
 import ReactDOM from 'react-dom/client'
-import './lib/rbac-setup' // ⚠️ Import setup BEFORE App
+import { setupRBAC } from '@jmruthers/pace-core/rbac'
+import { supabase } from './lib/supabase'
 import App from './App'
 
+// ⚠️ CRITICAL: Call setupRBAC BEFORE rendering App
+setupRBAC(supabase)
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <App />
@@ -231,18 +245,24 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 )
 ```
 
-**Or in your App.tsx (alternative approach):**
+**Option 2: Setup in separate file (Alternative)**
 
 ```typescript
-// src/App.tsx
-import React from 'react'
+// src/lib/rbac-setup.ts
 import { setupRBAC } from '@jmruthers/pace-core/rbac'
-import { supabase } from './lib/supabase'
+import { supabase } from './supabase'
 
-// ⚠️ REQUIRED: Call setupRBAC before anything else
-setupRBAC(supabase)
+// ⚠️ REQUIRED: Initialize RBAC before using any RBAC features
+setupRBAC(supabase, {
+  // Optional: Configure rate limiting for high-traffic apps
+  security: {
+    maxPermissionChecksPerMinute: 2000 // Increase from default 1000 if needed
+  }
+})
 
-// ... rest of your app
+// src/main.tsx
+import './lib/rbac-setup' // Import BEFORE App
+import App from './App'
 ```
 
 ### 9. App Setup (CRITICAL)
@@ -560,12 +580,25 @@ export function Users() {
 
 Your RBAC setup is working correctly if:
 
+**Setup Checklist:**
+- [ ] `setupRBAC(supabase)` is called before rendering App
+- [ ] App is registered in `rbac_apps` table with `is_active = true`
+- [ ] Pages exist in `rbac_app_pages` for your app
+- [ ] Page permissions exist in `rbac_page_permissions` for your pages, roles, and organisation
+- [ ] User has an active role in `rbac_organisation_roles` for the organisation
+- [ ] `VITE_APP_NAME` environment variable matches database `rbac_apps.name` exactly
+
+**Runtime Checklist:**
 - [ ] You can log in successfully
+- [ ] Browser console shows "RBAC system initialized successfully"
 - [ ] You see the dashboard without "Access Denied" messages
+- [ ] `PagePermissionGuard` shows loading state, then renders content (not fallback)
 - [ ] You can navigate to the users page
 - [ ] You see "Success! Your RBAC setup is working correctly" on the users page
 - [ ] No 400/406 errors in the browser console
 - [ ] No "App not found" errors in the console
+- [ ] No "STRICT MODE VIOLATION" errors in the console
+- [ ] No "rate_limit_exceeded" errors (if you see these, increase rate limit in setupRBAC)
 
 ## 🚨 Troubleshooting
 
@@ -579,33 +612,75 @@ import { setupRBAC } from '@jmruthers/pace-core/rbac'
 setupRBAC(supabase) // Must be called BEFORE rendering app
 ```
 
-### Issue: "Access Denied" on all pages
+### Issue: "Access Denied" or "STRICT MODE VIOLATION" on all pages
+
+**This is the most common issue. Check these in EXACT ORDER:**
 
-**Check these in order:**
+1. **Verify setupRBAC was called**:
+   - Check browser console for "RBAC system initialized successfully"
+   - If missing, add `setupRBAC(supabase)` in your main.tsx before rendering
 
-1. **Verify your app is registered**:
+2. **Verify your app is registered and active**:
    ```sql
-   SELECT * FROM rbac_apps WHERE name = 'user-manager';
+   SELECT id, name, display_name, requires_event, is_active 
+   FROM rbac_apps 
+   WHERE name = 'user-manager';
    ```
+   - Must return exactly 1 row
+   - `is_active` must be `true`
+   - `name` must match your `VITE_APP_NAME` exactly (case-sensitive)
 
-2. **Check your environment variable**:
+3. **Check your environment variable matches database**:
    ```typescript
-   console.log('App name:', import.meta.env.VITE_APP_NAME);
+   console.log('App name from env:', import.meta.env.VITE_APP_NAME);
+   ```
+   - Must match database `rbac_apps.name` exactly
+
+4. **Verify pages exist for your app**:
+   ```sql
+   SELECT ap.id, ap.page_name, ap.page_description
+   FROM rbac_app_pages ap
+   JOIN rbac_apps a ON ap.app_id = a.id
+   WHERE a.name = 'user-manager'
+   ORDER BY ap.page_name;
    ```
+   - Must have pages for `dashboard`, `users`, etc.
 
-3. **Verify user has roles**:
+5. **Verify user has organisation role**:
    ```sql
-   SELECT * FROM rbac_organisation_roles WHERE user_id = 'your-user-id';
+   SELECT ror.*, u.email
+   FROM rbac_organisation_roles ror
+   JOIN auth.users u ON ror.user_id = u.id
+   WHERE ror.user_id = 'your-user-id'::uuid 
+     AND ror.status = 'active';
    ```
+   - User must have at least one active role
+   - Must be for the organisation you're testing with
 
-4. **Check page permissions exist**:
+6. **Check page permissions exist for user's role**:
    ```sql
-   SELECT pp.*, ap.page_name, a.name as app_name
+   SELECT 
+     ap.page_name,
+     pp.operation,
+     pp.role_name,
+     pp.allowed,
+     pp.organisation_id
    FROM rbac_page_permissions pp
    JOIN rbac_app_pages ap ON pp.app_page_id = ap.id
    JOIN rbac_apps a ON ap.app_id = a.id
-   WHERE a.name = 'user-manager';
+   WHERE a.name = 'user-manager'
+     AND pp.role_name = 'org_admin'  -- Replace with your user's role
+     AND pp.organisation_id = 'your-org-id'::uuid  -- Replace with your org ID
+     AND pp.allowed = true;
    ```
+   - Must have permissions for the pages you're trying to access
+   - Must have `allowed = true` for the operation (read, create, etc.)
+   - `organisation_id` must match the organisation the user is accessing
+
+7. **Check browser console for specific errors**:
+   - Look for `[PagePermissionGuard]` error messages
+   - Look for `[useCan]` permission check logs
+   - Look for rate limit errors (if you see these, you may need to increase the limit)
 
 ### Issue: 400/406 Database Errors
 

package/docs/rbac/troubleshooting.md

@@ -12,11 +12,134 @@ This guide helps you resolve common issues when using the PACE Core RBAC system.
 
 ## 🚨 Critical Issues (Fix Immediately)
 
-### 1. "Access Denied" on All Pages - Missing App ID
+### 1. "STRICT MODE VIOLATION" Error - Page Access Denied
+
+**Symptoms:**
+- Console shows `[PagePermissionGuard] STRICT MODE VIOLATION: User attempted to access protected page without permission`
+- Error object shows: `{ pageName: "menus", operation: "read", userId: "...", scope: {...} }`
+- Pages show fallback/access denied content even for users who should have permission
+- All permission checks return `false`
+
+**Root Cause:** One or more of these issues:
+1. Missing or incorrect database setup (app, pages, or permissions)
+2. User doesn't have organisation role for the organisation being accessed
+3. Page permissions don't exist for user's role and organisation
+4. `setupRBAC()` wasn't called before using RBAC features
+5. Rate limiting is too restrictive (unlikely with default 1000/minute)
+
+**Fix (Check in order):**
+
+**Step 1: Verify setupRBAC was called**
+```typescript
+// Check browser console for this message:
+// "RBAC system initialized successfully"
+
+// If missing, add to main.tsx:
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+setupRBAC(supabase); // BEFORE rendering App
+```
+
+**Step 2: Verify app registration**
+```sql
+-- Check app exists and is active
+SELECT id, name, display_name, requires_event, is_active 
+FROM rbac_apps 
+WHERE name = 'your-app-name';  -- Replace with actual app name
+
+-- Must return 1 row with is_active = true
+-- name must match VITE_APP_NAME environment variable exactly
+```
+
+**Step 3: Verify pages exist**
+```sql
+-- Check pages exist for your app
+SELECT ap.id, ap.page_name, ap.page_description
+FROM rbac_app_pages ap
+JOIN rbac_apps a ON ap.app_id = a.id
+WHERE a.name = 'your-app-name'
+ORDER BY ap.page_name;
+
+-- Must have a page matching your pageName prop (e.g., "menus")
+```
+
+**Step 4: Verify user has organisation role**
+```sql
+-- Check user's role for the organisation
+SELECT ror.*, u.email
+FROM rbac_organisation_roles ror
+JOIN auth.users u ON ror.user_id = u.id
+WHERE ror.user_id = 'user-id-from-error'::uuid 
+  AND ror.organisation_id = 'org-id-from-scope'::uuid  -- From error scope
+  AND ror.status = 'active';
+
+-- User must have at least one active role (e.g., 'org_admin', 'leader', 'member')
+```
+
+**Step 5: Verify page permissions exist**
+```sql
+-- Check permissions for user's role, page, and organisation
+SELECT 
+  ap.page_name,
+  pp.operation,
+  pp.role_name,
+  pp.allowed,
+  pp.organisation_id
+FROM rbac_page_permissions pp
+JOIN rbac_app_pages ap ON pp.app_page_id = ap.id
+JOIN rbac_apps a ON ap.app_id = a.id
+WHERE a.name = 'your-app-name'
+  AND ap.page_name = 'menus'  -- From error pageName
+  AND pp.operation = 'read'   -- From error operation
+  AND pp.role_name = 'org_admin'  -- From Step 4 role
+  AND pp.organisation_id = 'org-id-from-scope'::uuid  -- From error scope
+  AND pp.allowed = true;
+
+-- Must return at least 1 row with allowed = true
+```
+
+**Step 6: Create missing permissions if needed**
+```sql
+-- Grant read permission for a page to a role
+INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed, organisation_id)
+SELECT 
+  ap.id,
+  'read',
+  'org_admin',  -- Or user's actual role
+  true,
+  'your-org-id'::uuid  -- From error scope
+FROM rbac_app_pages ap
+JOIN rbac_apps a ON ap.app_id = a.id
+WHERE a.name = 'your-app-name'
+  AND ap.page_name = 'menus';
+```
+
+### 2. "rate_limit_exceeded" Error
+
+**Symptoms:**
+- Console shows `[RBAC Security] Object { type: "rate_limit_exceeded", userId: "...", details: {...} }`
+- Permission checks stop working temporarily
+- Users can't access pages they should have permission for
+
+**Root Cause:** Default rate limit (1000 requests/minute) exceeded
+
+**Fix:**
+```typescript
+// Increase rate limit in setupRBAC
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+
+setupRBAC(supabase, {
+  security: {
+    maxPermissionChecksPerMinute: 2000  // Increase from default 1000
+  }
+});
+```
+
+**Note:** Rate limiting is per user, so if you have many components checking permissions on page load, you may need a higher limit.
+
+### 3. "Access Denied" on All Pages - Missing App ID
 
 **Symptoms:**
 - Users see "Access Denied" on every page
-- Console shows `[PagePermissionGuard] STRICT MODE VIOLATION` errors
 - Console shows `scope: { organisationId: "...", eventId: "..." }` (missing `appId`)
 - All permission checks return `false`
 
@@ -62,7 +185,8 @@ function App() {
 **Fix:**
 ```typescript
 // ❌ WRONG - This causes the issue
-const { hasPermission } = useRBAC();
+// Don't use useRBAC().hasPermission() - it has been removed
+// Use useCan() hook or PagePermissionGuard instead
 
 // ✅ CORRECT - Use PagePermissionGuard instead
 <PagePermissionGuard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.109",
+  "version": "0.5.111",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {