@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/rbac/troubleshooting.md

@@ -1,316 +1,338 @@
 # RBAC Troubleshooting Guide
 
-> **📚 Quick Start**: If you're new to RBAC, start with the [Quick Start Guide](./quick-start.md) first.
-
 This guide helps you resolve common issues when using the PACE Core RBAC system.
 
-## 🚨 Critical Issues (Fix Immediately)
+## Common Issues
 
-### 1. "Access Denied" on All Pages - Missing App ID
+### 1. "RBAC not initialized" Error
 
-**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`
+**Error Message:**
+```
+RBACNotInitializedError: RBAC system not initialized. Please call setupRBAC(supabase) before using any RBAC components or hooks.
+```
 
-**Root Cause:** App name not being set globally for RBAC resolution
+**Cause:** You forgot to call `setupRBAC()` before using RBAC features.
 
-**Fix:**
+**Solution:**
 ```typescript
-// ❌ WRONG - Missing setRBACAppName call
-import { UnifiedAuthProvider } from '@jmruthers/pace-core/providers'
-
-function App() {
-  return (
-    <UnifiedAuthProvider supabaseClient={supabase}>
-      {/* Your app */}
-    </UnifiedAuthProvider>
-  )
-}
-
-// ✅ CORRECT - Set app name globally
-import { setRBACAppName } from '@jmruthers/pace-core/utils'
-
-const APP_NAME = import.meta.env.VITE_APP_NAME
-setRBACAppName(APP_NAME) // CRITICAL: This must be called
-
-function App() {
-  return (
-    <UnifiedAuthProvider supabaseClient={supabase}>
-      {/* Your app */}
-    </UnifiedAuthProvider>
-  )
-}
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(SUPABASE_URL, SUPABASE_KEY);
+
+// Call this BEFORE using any RBAC features
+setupRBAC(supabase);
+```
+
+**Where to call it:**
+- In your main App component
+- In your index.tsx file
+- In your _app.tsx file (Next.js)
+- Early in your application initialization
+
+### 2. "User context not available" Error
+
+**Error Message:**
+```
+PermissionGuard: No userId provided and could not infer from context
+```
+
+**Cause:** PermissionGuard can't find the user ID.
+
+**Solutions:**
+
+**Option 1: Pass userId explicitly**
+```tsx
+<PermissionGuard
+  userId="user-123"
+  permission="admin:read"
+  scope={{ organisationId: 'org-456' }}
+>
+  <AdminPanel />
+</PermissionGuard>
+```
+
+**Option 2: Set up auth context**
+```tsx
+// Set user in global context
+window.__PACE_USER__ = { id: 'user-123' };
+
+// Or use your auth provider
+const { user } = useAuth();
+<PermissionGuard
+  userId={user.id}
+  permission="admin:read"
+  scope={{ organisationId: 'org-456' }}
+>
+  <AdminPanel />
+</PermissionGuard>
 ```
 
-### 2. "Access Denied" on All Pages - Wrong Permission Check
+### 3. Permission Always Denied
 
 **Symptoms:**
-- Users see "Access Denied" on every page
-- Console shows `[PagePermissionGuard] STRICT MODE VIOLATION` errors
-- All permission checks return `false`
+- Components always show fallback content
+- `useCan` always returns `false`
 
-**Root Cause:** Using manual permission checks instead of PagePermissionGuard
+**Possible Causes:**
 
-**Fix:**
-```typescript
-// ❌ WRONG - This causes the issue
-const { hasPermission } = useRBAC();
-
-// ✅ CORRECT - Use PagePermissionGuard instead
-<PagePermissionGuard
-  pageName="dashboard"
-  operation="read"
-  fallback={<div>Access Denied</div>}
+**A. Missing Organisation Context**
+```tsx
+// ❌ Wrong - missing organisationId
+<PermissionGuard
+  permission="admin:read"
+  scope={{}} // Missing organisationId
+>
+  <AdminPanel />
+</PermissionGuard>
+
+// ✅ Correct
+<PermissionGuard
+  permission="admin:read"
+  scope={{ organisationId: 'org-123' }}
 >
-  <Dashboard />
-</PagePermissionGuard>
+  <AdminPanel />
+</PermissionGuard>
 ```
 
-**Database Check:**
+**B. Wrong Permission Format**
+```tsx
+// ❌ Wrong - invalid permission format
+<PermissionGuard
+  permission="admin" // Missing operation
+  scope={{ organisationId: 'org-123' }}
+>
+  <AdminPanel />
+</PermissionGuard>
+
+// ✅ Correct
+<PermissionGuard
+  permission="admin:read" // operation:resource format
+  scope={{ organisationId: 'org-123' }}
+>
+  <AdminPanel />
+</PermissionGuard>
+```
+
+**C. User Not in Database**
+Check if the user exists in your RBAC tables:
 ```sql
--- Verify your app exists and is active
-SELECT * FROM rbac_apps WHERE name = 'your-app-name' AND is_active = true;
-
--- Check if pages exist for your app
-SELECT ap.*, a.name as app_name
-FROM rbac_app_pages ap
-JOIN rbac_apps a ON ap.app_id = a.id
-WHERE a.name = 'your-app-name';
+-- Check if user has any roles
+SELECT * FROM rbac_global_roles WHERE user_id = 'your-user-id';
+SELECT * FROM rbac_organisation_roles WHERE user_id = 'your-user-id';
+SELECT * FROM rbac_event_app_roles WHERE user_id = 'your-user-id';
 ```
 
-### 2. 400/406 Database Errors
+### 4. Components Not Rendering
 
 **Symptoms:**
-- Console shows `XHR GET` requests failing with 400/406 status codes
-- Errors like `id=eq.CAKE&is_active=eq.true` in network tab
-- Permission checks fail silently
+- Components show loading state indefinitely
+- Components show error state
 
-**Root Cause:** App is querying `rbac_apps` with `id=eq.CAKE` instead of `name=eq.CAKE`
+**Debug Steps:**
 
-**Fix:**
+**A. Enable Debug Mode**
 ```typescript
-// ❌ WRONG - Don't make direct database queries
-const { data } = await supabase
-  .from('rbac_apps')
-  .select('*')
-  .eq('id', 'CAKE'); // This causes 400 error
-
-// ✅ CORRECT - Use the providers and hooks
-const { user, selectedOrganisationId } = useUnifiedAuth();
-// The providers handle app ID resolution automatically
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+
+setupRBAC(supabase, {
+  debug: true,
+  logLevel: 'debug',
+});
 ```
 
-**Prevention:**
-- Never make direct queries to `rbac_apps`, `rbac_global_roles`, or other RBAC tables
-- Always use the provided hooks and components
-- Let the core library handle all RBAC database operations
+**B. Check Console Logs**
+Look for RBAC debug messages in the console.
 
-### 3. App ID Resolution Failures
+**C. Check Network Tab**
+Verify that Supabase requests are being made and returning data.
 
-**Symptoms:**
-- Console shows "App not found or inactive" warnings
-- Permission checks return `false` even for valid users
-- App configuration not loading
+### 5. TypeScript Errors
 
-**Root Cause:** App name mismatch between environment variable and database
+**Common TypeScript Issues:**
 
-**Fix:**
-```bash
-# Check your environment variable
-echo $VITE_APP_NAME
+**A. Missing Type Imports**
+```typescript
+// ❌ Wrong
+import { PermissionGuard } from '@jmruthers/pace-core/rbac';
 
-# Check your database
-SELECT name, is_active FROM rbac_apps WHERE name = 'your-app-name';
+// ✅ Correct
+import { PermissionGuard, Permission, Scope } from '@jmruthers/pace-core/rbac';
 ```
 
-**Ensure exact match:**
+**B. Wrong Permission Type**
 ```typescript
-// .env.local
-VITE_APP_NAME=my-app
+// ❌ Wrong
+const permission: string = 'admin:read';
 
-// Database
-INSERT INTO rbac_apps (name, is_active) VALUES ('my-app', true);
-// Must match exactly - case sensitive!
+// ✅ Correct
+const permission: Permission = 'admin:read';
 ```
 
-### 4. Permission Checks Always Return False
+**C. Wrong Scope Type**
+```typescript
+// ❌ Wrong
+const scope = { organisationId: 'org-123' };
+
+// ✅ Correct
+const scope: Scope = { organisationId: 'org-123' };
+```
+
+### 6. Database Connection Issues
 
 **Symptoms:**
-- All `useCan` calls return `false`
-- All `PagePermissionGuard` components show fallback content
-- Users can't access anything
+- Permission checks fail silently
+- Components show error state
+- Console shows Supabase errors
 
-**Root Cause:** Missing or incorrect page permissions in database
+**Solutions:**
 
-**Fix:**
-```sql
--- Check if page permissions exist
-SELECT pp.*, ap.page_name, a.name as app_name
-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';
-
--- If no permissions exist, create them
-WITH app_pages AS (
-  SELECT ap.id as page_id, ap.page_name, a.id as app_id
-  FROM rbac_app_pages ap
-  JOIN rbac_apps a ON ap.app_id = a.id
-  WHERE a.name = 'your-app-name'
-)
-INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed, organisation_id)
-SELECT 
-  ap.page_id,
-  'read',
-  'org_admin',
-  true,
-  'your-organisation-id'::uuid
-FROM app_pages ap;
+**A. Check Supabase Configuration**
+```typescript
+// Verify your Supabase client is properly configured
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!, // Make sure this is set
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY! // Make sure this is set
+);
 ```
 
-## 🔧 Setup Issues
+**B. Check Database Schema**
+Make sure your database has the required RBAC tables:
+- `rbac_global_roles`
+- `rbac_organisation_roles`
+- `rbac_event_app_roles`
+- `rbac_page_permissions`
 
-### 5. Missing Provider Setup
+**C. Check RLS Policies**
+Verify that Row Level Security policies are properly configured.
+
+### 7. Performance Issues
 
 **Symptoms:**
-- "Provider not found" errors
-- Hooks return undefined values
-- App crashes on load
+- Slow permission checks
+- Multiple database requests
+- High memory usage
+
+**Solutions:**
 
-**Fix:**
+**A. Enable Caching**
 ```typescript
-// ❌ WRONG - Missing providers
-function App() {
-  return (
-    <div>
-      <MyComponent />
-    </div>
-  );
-}
-
-// ✅ CORRECT - Proper provider setup
-function App() {
-  return (
-    <UnifiedAuthProvider 
-      supabaseClient={supabase} 
-      appName={APP_NAME}
-    >
-      <OrganisationProvider>
-        <EventProvider>
-          <MyComponent />
-        </EventProvider>
-      </OrganisationProvider>
-    </UnifiedAuthProvider>
-  );
-}
+setupRBAC(supabase, {
+  cache: {
+    enabled: true,
+    ttl: 60000, // 60 seconds
+  },
+});
 ```
 
-### 6. Wrong App Context Type
+**B. Use Cached Hooks**
+```tsx
+// Use cached versions when possible
+import { useCanCached } from '@jmruthers/pace-core/rbac';
 
-**Symptoms:**
-- "Invalid context requirements" errors
-- Permission checks fail with context errors
-- Organisation not resolved from event
+const { can } = useCanCached(userId, scope, permission);
+```
+
+**C. Optimize Database Queries**
+Make sure you have proper indexes on frequently queried columns.
+
+## Debug Mode
+
+Enable debug mode to get detailed logging:
 
-**Fix:**
 ```typescript
-// Check your app configuration
-const appConfig = await getAppConfig(appId);
-
-if (appConfig?.requires_event) {
-  // Event-based app - requires eventId
-  const scope = { eventId: selectedEventId, appId };
-} else {
-  // Organisation-based app - requires organisationId
-  const scope = { organisationId: selectedOrganisationId, appId };
-}
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+
+setupRBAC(supabase, {
+  debug: true,
+  logLevel: 'debug',
+  developmentMode: true,
+});
 ```
 
-### 7. User Not in Database
+This will log:
+- Permission check attempts
+- Database queries
+- Cache hits/misses
+- Error details
 
-**Symptoms:**
-- User can log in but has no permissions
-- All permission checks return false
-- No roles found for user
+## Testing Issues
 
-**Fix:**
-```sql
--- Check if user has any roles
-SELECT * FROM rbac_organisation_roles WHERE user_id = 'your-user-id';
-SELECT * FROM rbac_global_roles WHERE user_id = 'your-user-id';
+### 1. Mock Providers
 
--- If no roles exist, create them
-INSERT INTO rbac_organisation_roles (user_id, organisation_id, role, status)
-VALUES ('your-user-id'::uuid, 'your-organisation-id'::uuid, 'org_admin', 'active');
-```
+Use the provided mock providers for testing:
 
-## 🚀 Quick Fixes
+```typescript
+import { createMockRBACProvider, TestScenarios } from '@jmruthers/pace-core/rbac/testing';
 
-### Fix 1: Reset App Configuration
+const MockProvider = createMockRBACProvider(TestScenarios.admin);
 
-```sql
--- Delete and recreate your app
-DELETE FROM rbac_apps WHERE name = 'your-app-name';
-INSERT INTO rbac_apps (name, display_name, requires_event, is_active) 
-VALUES ('your-app-name', 'Your App', false, true);
+render(
+  <MockProvider>
+    <MyComponent />
+  </MockProvider>
+);
 ```
 
-### Fix 2: Grant Admin Role
+### 2. Test Utilities
 
-```sql
--- Give user org_admin role
-INSERT INTO rbac_organisation_roles (user_id, organisation_id, role, status)
-VALUES ('your-user-id'::uuid, 'your-organisation-id'::uuid, 'org_admin', 'active')
-ON CONFLICT (user_id, organisation_id) DO UPDATE SET
-  role = 'org_admin',
-  status = 'active',
-  updated_at = NOW();
+```typescript
+import { 
+  createMockSupabaseClient,
+  createTestScope,
+  createTestUser,
+  mockPermissions
+} from '@jmruthers/pace-core/rbac/testing';
+
+const mockSupabase = createMockSupabaseClient();
+const testScope = createTestScope({ organisationId: 'test-org' });
+const testUser = createTestUser({ id: 'test-user' });
+const permissions = mockPermissions({ admin: true });
 ```
 
-### Fix 3: Create Basic Page Permissions
+## Getting Help
 
-```sql
--- Create basic permissions for all pages
-WITH app_pages AS (
-  SELECT ap.id as page_id, a.id as app_id
-  FROM rbac_app_pages ap
-  JOIN rbac_apps a ON ap.app_id = a.id
-  WHERE a.name = 'your-app-name'
-)
-INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed, organisation_id)
-SELECT 
-  ap.page_id,
-  op.operation,
-  'org_admin',
-  true,
-  'your-organisation-id'::uuid
-FROM app_pages ap
-CROSS JOIN (SELECT unnest(ARRAY['read', 'create', 'update', 'delete']) as operation) op;
-```
+### 1. Check the Logs
+
+Enable debug mode and check the console for detailed error messages.
+
+### 2. Verify Your Setup
+
+Make sure you've followed the [Getting Started Guide](./getting-started.md) correctly.
+
+### 3. Check the Examples
+
+Look at the [Examples](./examples.md) for working code patterns.
+
+### 4. Database Issues
 
-## ✅ Verification Checklist
+If you're having database issues:
+- Check your Supabase connection
+- Verify your database schema
+- Check your RLS policies
+- Look at the Supabase logs
 
-After applying fixes, verify:
+### 5. Still Stuck?
 
-- [ ] App name in environment variable matches database exactly
-- [ ] User has at least one role in the database
-- [ ] Page permissions exist for the pages you're trying to access
-- [ ] You're using `PagePermissionGuard` instead of manual permission checks
-- [ ] You're not making direct database queries to RBAC tables
-- [ ] All providers are properly set up
-- [ ] No 400/406 errors in the console
-- [ ] Permission checks return `true` for admin users
+If you're still having issues:
+- Check the [API Reference](./api-reference.md) for detailed documentation
+- Look at the [Examples](./examples.md) for more complex scenarios
+- Review the [Migration Guide](../migration/rbac-migration.md) if you're migrating from legacy RBAC
 
-## 🆘 Still Having Issues?
+## Common Error Codes
 
-If you're still having problems:
+| Error Code | Description | Solution |
+|------------|-------------|----------|
+| `RBAC_NOT_INITIALIZED` | RBAC system not set up | Call `setupRBAC(supabase)` |
+| `MISSING_USER_CONTEXT` | No user ID available | Pass `userId` prop or set up auth context |
+| `INVALID_SCOPE` | Invalid scope provided | Check scope object has required fields |
+| `ORGANISATION_CONTEXT_REQUIRED` | Missing organisation context | Provide `organisationId` in scope |
+| `PERMISSION_DENIED` | User doesn't have permission | Check user's roles and permissions |
 
-1. **Check the [Quick Start Guide](./quick-start.md)** - Follow it exactly
-2. **Enable debug mode** and check console logs
-3. **Verify your database setup** matches the examples exactly
-4. **Test with a super admin user** to bypass permission checks
-5. **Check the [API Reference](./api-reference.md)** for correct usage patterns
+## Performance Tips
 
-Remember: The RBAC system is designed to be secure by default. If permissions are being denied, it's usually because the setup isn't quite right. Follow this guide step by step, and your RBAC system will work perfectly.
+1. **Use Caching**: Enable caching for better performance
+2. **Batch Permission Checks**: Use `useMultiplePermissions` for multiple checks
+3. **Optimize Database**: Add proper indexes to your RBAC tables
+4. **Use Development Mode**: Disable caching in development for easier debugging
+5. **Monitor Performance**: Use debug mode to identify slow queries

package/docs/security/README.md

@@ -12,7 +12,6 @@ PACE Core is designed with security as a first-class concern, providing:
 - **Audit logging** for compliance and monitoring
 - **Input validation** and sanitization
 - **XSS protection** and secure coding practices
-- **Auto-logout on inactivity** for enhanced security
 
 ## Authentication Security
 
@@ -52,7 +51,6 @@ Sessions are automatically managed by PACE Core:
 - **Secure session storage** using HTTP-only cookies
 - **Session validation** on every request
 - **Automatic logout** on token expiration
-- **Inactivity auto-logout** after 30 minutes of inactivity (configurable)
 
 ```tsx
 import { useUnifiedAuth } from '@jmruthers/pace-core';
@@ -72,54 +70,7 @@ function ProtectedComponent() {
 }
 ```
 
-### 3. Inactivity Auto-Logout
-
-PACE Core includes built-in inactivity tracking for enhanced security:
-
-- **Automatic logout** after 30 minutes of inactivity (configurable)
-- **Warning modal** appears 60 seconds before logout
-- **Cross-tab synchronization** - activity in any tab resets the timer
-- **Persistence** - survives page reloads and browser restarts
-- **Production-safe** - cannot be disabled in production builds
-
-```tsx
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <UnifiedAuthProvider
-      supabaseClient={supabaseClient}
-      appName="my-app"
-      idleTimeoutMs={30 * 60 * 1000} // 30 minutes
-      warnBeforeMs={60 * 1000}       // 60 seconds warning
-      onIdleLogout={() => {
-        // Handle redirect to login page
-        window.location.href = '/login';
-      }}
-    >
-      <YourApp />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-#### Monitored Events
-
-The inactivity tracker monitors:
-- Mouse events (click, move, scroll, wheel)
-- Touch events (start, move, end)
-- Keyboard events (keydown, keyup, keypress)
-- Focus events (focus, blur)
-- Page visibility changes
-
-#### Security Benefits
-
-- **Prevents unauthorized access** if user leaves device unattended
-- **Reduces session hijacking risk** by limiting session duration
-- **Compliance support** for security requirements
-- **Cross-tab protection** ensures consistent security across all tabs
-
-### 4. Password Security
+### 3. Password Security
 
 Password security is handled by Supabase: