@jmruthers/pace-core 0.5.183 → 0.5.185

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) {

package/src/types/file-reference.ts

@@ -51,12 +51,18 @@ export enum FileCategory {
   TRAC_TRANSPORT = 'trac_transport'
 }
 
+/**
+ * Options for uploading a file with a file reference
+ * @property pageContext - The page context where the file upload occurs (e.g., 'configuration', 'forms', 'applications')
+ *                          Used for context-aware permission checks. Required to check appropriate page-level permissions.
+ */
 export interface FileUploadOptions {
   table_name: string;
   record_id: string;
   organisation_id: string;
   app_id: AppId;
   category: FileCategory;
+  pageContext: string;
   is_public?: boolean;
   custom_metadata?: Record<string, unknown>;
 }