@jmruthers/pace-core 0.5.184 → 0.5.186

package/src/rbac/docs/event-based-apps.md

@@ -0,0 +1,285 @@
+# Event-Based Apps with RBAC
+
+This guide explains how to use the RBAC system for event-based applications where the organization context is automatically derived from the event context.
+
+## Overview
+
+Event-based apps are applications that operate within the context of a specific event. Since events inherently belong to an organization, these apps don't need explicit organization context - it is automatically resolved from the event by the RBAC components.
+
+## Key Concepts
+
+### Automatic Organization Resolution
+The RBAC components automatically resolve the organization from the event context when needed. You only need to provide the `eventId` (and optionally `appId`), and the system handles the rest.
+
+```typescript
+// The components automatically resolve organisationId from eventId
+const scope: Scope = {
+  eventId: 'event-123',
+  appId: 'app-456' // optional
+  // organisationId is automatically resolved
+};
+```
+
+### Permission Hierarchy
+For event-based apps, the permission hierarchy is:
+1. **Page-level permissions** (most specific)
+2. **Event-app permissions** (event + app specific)
+3. **Organization permissions** (automatically resolved from event)
+4. **Global permissions** (least specific)
+
+## Components
+
+The same RBAC components work for both organization-based and event-based apps. They automatically detect the context and resolve the organization when needed.
+
+### PermissionEnforcer
+Use this component for general permission enforcement in event-based apps:
+
+```tsx
+import { PermissionEnforcer } from '@jmruthers/pace-core/rbac';
+
+function EventDashboard() {
+  return (
+    <PermissionEnforcer
+      permissions={['read:events', 'update:participants']}
+      operation="dashboard"
+    >
+      <div>Event Dashboard Content</div>
+    </PermissionEnforcer>
+  );
+}
+```
+
+### PagePermissionGuard
+Use this component for page-level permission enforcement:
+
+```tsx
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function EventSettingsPage() {
+  return (
+    <PagePermissionGuard
+      pageName="settings"
+      operation="read"
+    >
+      <div>Event Settings</div>
+    </PagePermissionGuard>
+  );
+}
+```
+
+### NavigationGuard
+Use this component for navigation-level permission enforcement:
+
+```tsx
+import { NavigationGuard } from '@jmruthers/pace-core/rbac';
+
+const navigationItems = [
+  {
+    id: 'dashboard',
+    name: 'Dashboard',
+    path: '/event/dashboard',
+    permissions: ['read:events']
+  },
+  {
+    id: 'settings',
+    name: 'Settings',
+    path: '/event/settings',
+    permissions: ['update:events']
+  }
+];
+
+function EventNavigation() {
+  return (
+    <nav>
+      {navigationItems.map(item => (
+        <NavigationGuard
+          key={item.id}
+          navigationItem={item}
+        >
+          <Link to={item.path}>{item.name}</Link>
+        </NavigationGuard>
+      ))}
+    </nav>
+  );
+}
+```
+
+## Hooks
+
+### useCan with Event Context
+You can use the standard `useCan` hook with event-based scopes:
+
+```tsx
+import { useCan } from '@jmruthers/pace-core/rbac';
+
+function EventComponent() {
+  const { selectedEventId } = useUnifiedAuth();
+  
+  const { can: canManageEvents } = useCan(
+    userId,
+    { eventId: selectedEventId },
+    'update:events'
+  );
+
+  return (
+    <div>
+      {canManageEvents && (
+        <button>Manage Event</button>
+      )}
+    </div>
+  );
+}
+```
+
+## Setup
+
+### 1. Event Context Provider
+Ensure your app has event context available:
+
+```tsx
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider>
+      {/* Your event-based app components */}
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+### 2. Event Selection
+Make sure the event is selected in the auth context:
+
+```tsx
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function EventSelector() {
+  const { setSelectedEventId } = useUnifiedAuth();
+  
+  const handleEventSelect = (eventId: string) => {
+    setSelectedEventId(eventId);
+  };
+
+  return (
+    <select onChange={(e) => handleEventSelect(e.target.value)}>
+      <option value="event-1">Event 1</option>
+      <option value="event-2">Event 2</option>
+    </select>
+  );
+}
+```
+
+## Permission Types
+
+### Event-App Permissions
+These permissions are specific to an event and app combination:
+
+```typescript
+const EVENT_APP_PERMISSIONS = {
+  // Event management
+  MANAGE_EVENT: 'update:event',
+  READ_EVENT: 'read:event',
+  UPDATE_EVENT: 'update:event',
+  
+  // Participant management
+  MANAGE_PARTICIPANTS: 'update:participants',
+  READ_PARTICIPANTS: 'read:participants',
+  CREATE_PARTICIPANTS: 'create:participants',
+  UPDATE_PARTICIPANTS: 'update:participants',
+  DELETE_PARTICIPANTS: 'delete:participants',
+  
+  // App-specific permissions
+  MANAGE_APP: 'update:app',
+  READ_APP: 'read:app',
+  UPDATE_APP: 'update:app',
+};
+```
+
+### Page Permissions
+Page permissions are specific to individual pages within an event app:
+
+```typescript
+const PAGE_PERMISSIONS = {
+  DASHBOARD_READ: 'read:page.dashboard',
+  DASHBOARD_WRITE: 'write:page.dashboard',
+  SETTINGS_READ: 'read:page.settings',
+  SETTINGS_WRITE: 'write:page.settings',
+  PARTICIPANTS_READ: 'read:page.participants',
+  PARTICIPANTS_WRITE: 'write:page.participants',
+};
+```
+
+## Best Practices
+
+### 1. Use Event-Based Components
+Always use the event-based components (`EventPermissionEnforcer`, `EventPagePermissionGuard`, `EventNavigationGuard`) instead of the organization-based ones for event apps.
+
+### 2. Provide Explicit Scopes
+When possible, provide explicit scopes to avoid context resolution overhead:
+
+```tsx
+<EventPermissionEnforcer
+  scope={{ eventId: 'event-123', appId: 'app-456' }}
+  permissions={['read:events']}
+>
+  <div>Content</div>
+</EventPermissionEnforcer>
+```
+
+### 3. Handle Loading States
+Event-based components automatically handle loading states while resolving the organization from the event:
+
+```tsx
+<EventPermissionEnforcer
+  permissions={['read:events']}
+  loading={<div>Loading permissions...</div>}
+>
+  <div>Content</div>
+</EventPermissionEnforcer>
+```
+
+### 4. Error Handling
+Handle cases where the organization cannot be resolved from the event:
+
+```tsx
+<EventPermissionEnforcer
+  permissions={['read:events']}
+  onDenied={(permission, reason) => {
+    console.error(`Permission denied: ${permission}, reason: ${reason}`);
+  }}
+>
+  <div>Content</div>
+</EventPermissionEnforcer>
+```
+
+## Migration from Organization-Based Apps
+
+If you're migrating from organization-based apps to event-based apps:
+
+1. Replace `PermissionEnforcer` with `EventPermissionEnforcer`
+2. Replace `PagePermissionGuard` with `EventPagePermissionGuard`
+3. Replace `NavigationGuard` with `EventNavigationGuard`
+4. Remove explicit organization context from your components
+5. Ensure event context is available in your app
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Event context is required" error**: Make sure `selectedEventId` is set in the auth context
+2. **"Could not resolve organization from event context" error**: Verify the event exists and has a valid `organisation_id`
+3. **Permission checks failing**: Ensure the user has the appropriate event-app roles assigned
+
+### Debug Mode
+
+Enable debug mode to see detailed permission resolution:
+
+```typescript
+import { createRBACConfig } from '@jmruthers/pace-core/rbac';
+
+const config = createRBACConfig({
+  debug: true,
+  logLevel: 'debug'
+});
+```

package/src/rbac/errors.ts

@@ -4,6 +4,7 @@ import {
   OrganisationContextRequiredError,
   InvalidScopeError,
   MissingUserContextError,
+  RBACNotInitializedError,
 } from './types';
 
 export enum RBACErrorCategory {
@@ -154,3 +155,13 @@ export function mapErrorCategoryToSecurityEventType(category: RBACErrorCategory)
       return 'unknown_error';
   }
 }
+
+// Re-export error classes for convenience
+export {
+  RBACError,
+  PermissionDeniedError,
+  OrganisationContextRequiredError,
+  InvalidScopeError,
+  MissingUserContextError,
+  RBACNotInitializedError,
+};

package/src/rbac/hooks/useRoleManagement.ts

@@ -13,25 +13,46 @@
  * import { useRoleManagement } from '@jmruthers/pace-core/rbac';
  *
  * function UserRolesComponent() {
- *   const { revokeEventAppRole, grantEventAppRole, isLoading, error } = useRoleManagement();
+ *   const { 
+ *     revokeEventAppRole, 
+ *     grantEventAppRole,
+ *     grantGlobalRole,
+ *     revokeGlobalRole,
+ *     grantOrganisationRole,
+ *     revokeOrganisationRole,
+ *     isLoading, 
+ *     error 
+ *   } = useRoleManagement();
  *
- *   const handleRevokeRole = async (roleId: string, roleData: EventAppRoleData) => {
- *     const result = await revokeEventAppRole({
- *       userId: roleData.user_id,
- *       organisationId: roleData.organisation_id,
- *       eventId: roleData.event_id,
- *       appId: roleData.app_id,
- *       role: roleData.role
+ *   // Grant a global role
+ *   const handleGrantGlobalRole = async () => {
+ *     const result = await grantGlobalRole({
+ *       user_id: userId,
+ *       role: 'super_admin'
  *     });
+ *     if (result.success) {
+ *       toast({ title: 'Role granted successfully' });
+ *     }
+ *   };
  *
+ *   // Grant an organisation role
+ *   const handleGrantOrgRole = async () => {
+ *     const result = await grantOrganisationRole({
+ *       user_id: userId,
+ *       organisation_id: orgId,
+ *       role: 'org_admin'
+ *     });
  *     if (result.success) {
- *       toast({ title: 'Role revoked successfully' });
- *     } else {
- *       toast({ title: 'Failed to revoke role', variant: 'destructive' });
+ *       toast({ title: 'Role granted successfully' });
  *     }
  *   };
  *
- *   return <button onClick={() => handleRevokeRole(roleId, roleData)}>Revoke Role</button>;
+ *   return (
+ *     <div>
+ *       <button onClick={handleGrantGlobalRole}>Grant Super Admin</button>
+ *       <button onClick={handleGrantOrgRole}>Grant Org Admin</button>
+ *     </div>
+ *   );
  * }
  * ```
  */
@@ -48,6 +69,17 @@ export interface EventAppRoleData {
   role: 'viewer' | 'participant' | 'planner' | 'event_admin';
 }
 
+export interface OrganisationRoleData {
+  user_id: UUID;
+  organisation_id: UUID;
+  role: 'supporter' | 'member' | 'leader' | 'org_admin';
+}
+
+export interface GlobalRoleData {
+  user_id: UUID;
+  role: 'super_admin';
+}
+
 export interface RevokeEventAppRoleParams extends EventAppRoleData {
   revoked_by?: UUID;
 }
@@ -58,6 +90,26 @@ export interface GrantEventAppRoleParams extends EventAppRoleData {
   valid_to?: string | null;
 }
 
+export interface RevokeOrganisationRoleParams extends OrganisationRoleData {
+  revoked_by?: UUID;
+}
+
+export interface GrantOrganisationRoleParams extends OrganisationRoleData {
+  granted_by?: UUID;
+  valid_from?: string;
+  valid_to?: string | null;
+}
+
+export interface RevokeGlobalRoleParams extends GlobalRoleData {
+  revoked_by?: UUID;
+}
+
+export interface GrantGlobalRoleParams extends GlobalRoleData {
+  granted_by?: UUID;
+  valid_from?: string;
+  valid_to?: string | null;
+}
+
 export interface RoleManagementResult {
   success: boolean;
   message?: string;
@@ -244,10 +296,238 @@ export function useRoleManagement() {
     }
   }, [user?.id, supabase]);
 
+  /**
+   * Grant a global role using the unified RPC function
+   * 
+   * This function uses the `rbac_role_grant` RPC which:
+   * - Runs with SECURITY DEFINER privileges
+   * - Includes proper permission checks
+   * - Automatically populates audit fields (granted_by, timestamps)
+   * - Complies with Row-Level Security policies
+   * 
+   * @param params - Role grant parameters
+   * @returns Promise resolving to operation result with role ID
+   */
+  const grantGlobalRole = useCallback(async (
+    params: GrantGlobalRoleParams
+  ): Promise<RoleManagementResult> => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const { data, error: rpcError } = await supabase.rpc('rbac_role_grant', {
+        p_user_id: params.user_id,
+        p_role_type: 'global',
+        p_role_name: params.role,
+        p_context_id: null, // Global roles don't need context
+        p_granted_by: params.granted_by || user?.id || undefined
+      });
+
+      if (rpcError) {
+        throw new Error(rpcError.message || 'Failed to grant role');
+      }
+
+      // rbac_role_grant returns a table with success, message, role_id, error_code
+      const result = Array.isArray(data) && data.length > 0 ? data[0] : null;
+
+      if (!result || !result.success) {
+        return {
+          success: false,
+          error: result?.message || result?.error_code || 'Failed to grant role',
+          message: result?.message
+        };
+      }
+
+      return {
+        success: true,
+        message: result.message || 'Role granted successfully',
+        roleId: result.role_id
+      };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Unknown error occurred';
+      setError(err instanceof Error ? err : new Error(errorMessage));
+      return {
+        success: false,
+        error: errorMessage
+      };
+    } finally {
+      setIsLoading(false);
+    }
+  }, [user?.id, supabase]);
+
+  /**
+   * Revoke a global role using the unified RPC function
+   * 
+   * This function uses the `rbac_role_revoke` RPC which:
+   * - Runs with SECURITY DEFINER privileges
+   * - Includes proper permission checks
+   * - Automatically populates audit fields (revoked_by, timestamps)
+   * - Complies with Row-Level Security policies
+   * 
+   * @param params - Role revocation parameters
+   * @returns Promise resolving to operation result
+   */
+  const revokeGlobalRole = useCallback(async (
+    params: RevokeGlobalRoleParams
+  ): Promise<RoleManagementResult> => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const { data, error: rpcError } = await supabase.rpc('rbac_role_revoke', {
+        p_user_id: params.user_id,
+        p_role_type: 'global',
+        p_role_name: params.role,
+        p_context_id: null, // Global roles don't need context
+        p_revoked_by: params.revoked_by || user?.id || undefined
+      });
+
+      if (rpcError) {
+        throw new Error(rpcError.message || 'Failed to revoke role');
+      }
+
+      // rbac_role_revoke returns a table with success, message, revoked_count, error_code
+      const result = Array.isArray(data) && data.length > 0 ? data[0] : null;
+
+      return {
+        success: result?.success === true,
+        message: result?.message || undefined,
+        error: result?.success === false ? (result?.message || result?.error_code || 'Unknown error') : undefined
+      };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Unknown error occurred';
+      setError(err instanceof Error ? err : new Error(errorMessage));
+      return {
+        success: false,
+        error: errorMessage
+      };
+    } finally {
+      setIsLoading(false);
+    }
+  }, [user?.id, supabase]);
+
+  /**
+   * Grant an organisation role using the unified RPC function
+   * 
+   * This function uses the `rbac_role_grant` RPC which:
+   * - Runs with SECURITY DEFINER privileges
+   * - Includes proper permission checks
+   * - Automatically populates audit fields (granted_by, timestamps)
+   * - Complies with Row-Level Security policies
+   * 
+   * @param params - Role grant parameters
+   * @returns Promise resolving to operation result with role ID
+   */
+  const grantOrganisationRole = useCallback(async (
+    params: GrantOrganisationRoleParams
+  ): Promise<RoleManagementResult> => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const { data, error: rpcError } = await supabase.rpc('rbac_role_grant', {
+        p_user_id: params.user_id,
+        p_role_type: 'organisation',
+        p_role_name: params.role,
+        p_context_id: params.organisation_id, // Organisation ID as context
+        p_granted_by: params.granted_by || user?.id || undefined
+      });
+
+      if (rpcError) {
+        throw new Error(rpcError.message || 'Failed to grant role');
+      }
+
+      // rbac_role_grant returns a table with success, message, role_id, error_code
+      const result = Array.isArray(data) && data.length > 0 ? data[0] : null;
+
+      if (!result || !result.success) {
+        return {
+          success: false,
+          error: result?.message || result?.error_code || 'Failed to grant role',
+          message: result?.message
+        };
+      }
+
+      return {
+        success: true,
+        message: result.message || 'Role granted successfully',
+        roleId: result.role_id
+      };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Unknown error occurred';
+      setError(err instanceof Error ? err : new Error(errorMessage));
+      return {
+        success: false,
+        error: errorMessage
+      };
+    } finally {
+      setIsLoading(false);
+    }
+  }, [user?.id, supabase]);
+
+  /**
+   * Revoke an organisation role using the unified RPC function
+   * 
+   * This function uses the `rbac_role_revoke` RPC which:
+   * - Runs with SECURITY DEFINER privileges
+   * - Includes proper permission checks
+   * - Automatically populates audit fields (revoked_by, timestamps)
+   * - Complies with Row-Level Security policies
+   * 
+   * @param params - Role revocation parameters
+   * @returns Promise resolving to operation result
+   */
+  const revokeOrganisationRole = useCallback(async (
+    params: RevokeOrganisationRoleParams
+  ): Promise<RoleManagementResult> => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const { data, error: rpcError } = await supabase.rpc('rbac_role_revoke', {
+        p_user_id: params.user_id,
+        p_role_type: 'organisation',
+        p_role_name: params.role,
+        p_context_id: params.organisation_id, // Organisation ID as context
+        p_revoked_by: params.revoked_by || user?.id || undefined
+      });
+
+      if (rpcError) {
+        throw new Error(rpcError.message || 'Failed to revoke role');
+      }
+
+      // rbac_role_revoke returns a table with success, message, revoked_count, error_code
+      const result = Array.isArray(data) && data.length > 0 ? data[0] : null;
+
+      return {
+        success: result?.success === true,
+        message: result?.message || undefined,
+        error: result?.success === false ? (result?.message || result?.error_code || 'Unknown error') : undefined
+      };
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : 'Unknown error occurred';
+      setError(err instanceof Error ? err : new Error(errorMessage));
+      return {
+        success: false,
+        error: errorMessage
+      };
+    } finally {
+      setIsLoading(false);
+    }
+  }, [user?.id, supabase]);
+
   return {
+    // Event app roles (existing)
     revokeEventAppRole,
     grantEventAppRole,
     revokeRoleById,
+    // Global roles (new)
+    grantGlobalRole,
+    revokeGlobalRole,
+    // Organisation roles (new)
+    grantOrganisationRole,
+    revokeOrganisationRole,
+    // Shared state
     isLoading,
     error
   };

package/src/rbac/index.ts

@@ -113,3 +113,33 @@ export {
 
 // Permissions
 export * from './permissions';
+
+// Compliance
+export {
+  isRBACInitialized,
+  validateRBACSetup,
+  getSetupIssues,
+  type SetupIssue,
+  type ComplianceResult,
+} from './compliance/setup-validator';
+
+export {
+  checkRuntimeCompliance,
+  validateAndWarn,
+  type RuntimeComplianceResult,
+} from './compliance/runtime-compliance';
+
+export {
+  validateDatabaseConfiguration,
+  type DatabaseComplianceResult,
+  type DatabaseIssue,
+} from './compliance/database-validator';
+
+export {
+  getQuickFixes,
+  getCustomAuthCodeFixes,
+  getDuplicateConfigFixes,
+  getUnprotectedPageFixes,
+  getDirectSupabaseAuthFixes,
+  type QuickFix,
+} from './compliance/quick-fix-suggestions';

package/src/services/OrganisationService.ts

@@ -519,6 +519,7 @@ export class OrganisationService extends BaseService implements IOrganisationSer
       
       // Auto-select organisation: try persisted, then primary, then first
       let initialOrg: Organisation | null = null;
+      let selectionMethod: 'persisted' | 'admin' | 'first' = 'first';
       
       // 1. Try to restore from localStorage
       try {
@@ -530,6 +531,7 @@ export class OrganisationService extends BaseService implements IOrganisationSer
             const validPersistedOrg = activeOrgs.find(org => org.id === persistedOrg.id);
             if (validPersistedOrg) {
               initialOrg = validPersistedOrg;
+              selectionMethod = 'persisted';
             } else {
               logger.warn("OrganisationService", "Persisted organisation not found in active orgs, clearing cache");
               localStorage.removeItem('pace-core-selected-organisation');
@@ -552,6 +554,7 @@ export class OrganisationService extends BaseService implements IOrganisationSer
           const foundOrg = organisations.find((org) => org.id === adminMembership.organisation_id);
           if (foundOrg) {
             initialOrg = foundOrg;
+            selectionMethod = 'admin';
           }
         }
       }
@@ -559,6 +562,7 @@ export class OrganisationService extends BaseService implements IOrganisationSer
       // 3. Fall back to first organisation
       if (!initialOrg) {
         initialOrg = activeOrgs[0];
+        selectionMethod = 'first';
       }
       
       if (!initialOrg) {