@jmruthers/pace-core 0.4.1 → 0.5.3

package/docs/rbac/troubleshooting.md

@@ -1,338 +1,316 @@
 # 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.
 
-## Common Issues
+## 🚨 Critical Issues (Fix Immediately)
 
-### 1. "RBAC not initialized" Error
+### 1. "Access Denied" on All Pages - Missing App ID
 
-**Error Message:**
-```
-RBACNotInitializedError: RBAC system not initialized. Please call setupRBAC(supabase) before using any RBAC components or hooks.
-```
+**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`
 
-**Cause:** You forgot to call `setupRBAC()` before using RBAC features.
+**Root Cause:** App name not being set globally for RBAC resolution
 
-**Solution:**
+**Fix:**
 ```typescript
-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>
+// ❌ 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>
+  )
+}
 ```
 
-### 3. Permission Always Denied
+### 2. "Access Denied" on All Pages - Wrong Permission Check
 
 **Symptoms:**
-- Components always show fallback content
-- `useCan` always returns `false`
-
-**Possible Causes:**
-
-**A. Missing Organisation Context**
-```tsx
-// ❌ Wrong - missing organisationId
-<PermissionGuard
-  permission="admin:read"
-  scope={{}} // Missing organisationId
->
-  <AdminPanel />
-</PermissionGuard>
+- Users see "Access Denied" on every page
+- Console shows `[PagePermissionGuard] STRICT MODE VIOLATION` errors
+- All permission checks return `false`
 
-// ✅ Correct
-<PermissionGuard
-  permission="admin:read"
-  scope={{ organisationId: 'org-123' }}
->
-  <AdminPanel />
-</PermissionGuard>
-```
-
-**B. Wrong Permission Format**
-```tsx
-// ❌ Wrong - invalid permission format
-<PermissionGuard
-  permission="admin" // Missing operation
-  scope={{ organisationId: 'org-123' }}
->
-  <AdminPanel />
-</PermissionGuard>
+**Root Cause:** Using manual permission checks instead of PagePermissionGuard
 
-// ✅ Correct
-<PermissionGuard
-  permission="admin:read" // operation:resource format
-  scope={{ organisationId: 'org-123' }}
+**Fix:**
+```typescript
+// ❌ WRONG - This causes the issue
+const { hasPermission } = useRBAC();
+
+// ✅ CORRECT - Use PagePermissionGuard instead
+<PagePermissionGuard
+  pageName="dashboard"
+  operation="read"
+  fallback={<div>Access Denied</div>}
 >
-  <AdminPanel />
-</PermissionGuard>
+  <Dashboard />
+</PagePermissionGuard>
 ```
 
-**C. User Not in Database**
-Check if the user exists in your RBAC tables:
+**Database Check:**
 ```sql
--- 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';
+-- 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';
 ```
 
-### 4. Components Not Rendering
+### 2. 400/406 Database Errors
 
 **Symptoms:**
-- Components show loading state indefinitely
-- Components show error state
+- 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
 
-**Debug Steps:**
+**Root Cause:** App is querying `rbac_apps` with `id=eq.CAKE` instead of `name=eq.CAKE`
 
-**A. Enable Debug Mode**
+**Fix:**
 ```typescript
-import { setupRBAC } from '@jmruthers/pace-core/rbac';
-
-setupRBAC(supabase, {
-  debug: true,
-  logLevel: 'debug',
-});
+// ❌ 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
 ```
 
-**B. Check Console Logs**
-Look for RBAC debug messages in the console.
-
-**C. Check Network Tab**
-Verify that Supabase requests are being made and returning data.
-
-### 5. TypeScript Errors
+**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
 
-**Common TypeScript Issues:**
+### 3. App ID Resolution Failures
 
-**A. Missing Type Imports**
-```typescript
-// ❌ Wrong
-import { PermissionGuard } from '@jmruthers/pace-core/rbac';
+**Symptoms:**
+- Console shows "App not found or inactive" warnings
+- Permission checks return `false` even for valid users
+- App configuration not loading
 
-// ✅ Correct
-import { PermissionGuard, Permission, Scope } from '@jmruthers/pace-core/rbac';
-```
+**Root Cause:** App name mismatch between environment variable and database
 
-**B. Wrong Permission Type**
-```typescript
-// ❌ Wrong
-const permission: string = 'admin:read';
+**Fix:**
+```bash
+# Check your environment variable
+echo $VITE_APP_NAME
 
-// ✅ Correct
-const permission: Permission = 'admin:read';
+# Check your database
+SELECT name, is_active FROM rbac_apps WHERE name = 'your-app-name';
 ```
 
-**C. Wrong Scope Type**
+**Ensure exact match:**
 ```typescript
-// ❌ Wrong
-const scope = { organisationId: 'org-123' };
+// .env.local
+VITE_APP_NAME=my-app
 
-// ✅ Correct
-const scope: Scope = { organisationId: 'org-123' };
+// Database
+INSERT INTO rbac_apps (name, is_active) VALUES ('my-app', true);
+// Must match exactly - case sensitive!
 ```
 
-### 6. Database Connection Issues
+### 4. Permission Checks Always Return False
 
 **Symptoms:**
-- Permission checks fail silently
-- Components show error state
-- Console shows Supabase errors
+- All `useCan` calls return `false`
+- All `PagePermissionGuard` components show fallback content
+- Users can't access anything
 
-**Solutions:**
+**Root Cause:** Missing or incorrect page permissions in database
 
-**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
-);
+**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;
 ```
 
-**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`
+## 🔧 Setup Issues
 
-**C. Check RLS Policies**
-Verify that Row Level Security policies are properly configured.
-
-### 7. Performance Issues
+### 5. Missing Provider Setup
 
 **Symptoms:**
-- Slow permission checks
-- Multiple database requests
-- High memory usage
-
-**Solutions:**
+- "Provider not found" errors
+- Hooks return undefined values
+- App crashes on load
 
-**A. Enable Caching**
+**Fix:**
 ```typescript
-setupRBAC(supabase, {
-  cache: {
-    enabled: true,
-    ttl: 60000, // 60 seconds
-  },
-});
+// ❌ 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>
+  );
+}
 ```
 
-**B. Use Cached Hooks**
-```tsx
-// Use cached versions when possible
-import { useCanCached } from '@jmruthers/pace-core/rbac';
+### 6. Wrong App Context Type
 
-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:
+**Symptoms:**
+- "Invalid context requirements" errors
+- Permission checks fail with context errors
+- Organisation not resolved from event
 
+**Fix:**
 ```typescript
-import { setupRBAC } from '@jmruthers/pace-core/rbac';
-
-setupRBAC(supabase, {
-  debug: true,
-  logLevel: 'debug',
-  developmentMode: true,
-});
+// 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 };
+}
 ```
 
-This will log:
-- Permission check attempts
-- Database queries
-- Cache hits/misses
-- Error details
+### 7. User Not in Database
 
-## Testing Issues
+**Symptoms:**
+- User can log in but has no permissions
+- All permission checks return false
+- No roles found for user
 
-### 1. Mock Providers
+**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';
 
-Use the provided mock providers for testing:
+-- 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');
+```
 
-```typescript
-import { createMockRBACProvider, TestScenarios } from '@jmruthers/pace-core/rbac/testing';
+## 🚀 Quick Fixes
 
-const MockProvider = createMockRBACProvider(TestScenarios.admin);
+### Fix 1: Reset App Configuration
 
-render(
-  <MockProvider>
-    <MyComponent />
-  </MockProvider>
-);
+```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);
 ```
 
-### 2. Test Utilities
+### Fix 2: Grant Admin Role
 
-```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 });
+```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();
 ```
 
-## Getting Help
+### Fix 3: Create Basic Page Permissions
 
-### 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
+```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;
+```
 
-If you're having database issues:
-- Check your Supabase connection
-- Verify your database schema
-- Check your RLS policies
-- Look at the Supabase logs
+## ✅ Verification Checklist
 
-### 5. Still Stuck?
+After applying fixes, verify:
 
-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
+- [ ] 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
 
-## Common Error Codes
+## 🆘 Still Having Issues?
 
-| 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 |
+If you're still having problems:
 
-## Performance Tips
+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
 
-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
+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.

package/docs/security/README.md

@@ -12,6 +12,7 @@ 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
 
@@ -51,6 +52,7 @@ 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';
@@ -70,7 +72,54 @@ function ProtectedComponent() {
 }
 ```
 
-### 3. Password Security
+### 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
 
 Password security is handled by Supabase: