@jmruthers/pace-core 0.6.1 → 0.6.3

package/src/rbac/hooks/permissions/useCan.ts

@@ -0,0 +1,377 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { isPermitted, isPermittedCached } from '../../api';
+import { getRBACLogger } from '../../config';
+import { Permission, Scope, UUID } from '../../types';
+import { scopeEqual } from '../../utils/deep-equal';
+
+/**
+ * Hook to check if user can perform an action
+ *
+ * @param userId - User ID
+ * @param scope - Scope for permission checking
+ * @param permission - Permission to check
+ * @param pageId - Optional page ID
+ * @param useCache - Whether to use cached results
+ * @param appName - Optional app name (for PORTAL/ADMIN special case)
+ * @returns Permission check state and methods
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { can, isLoading, error } = useCan(userId, scope, 'read:users');
+ *
+ *   if (isLoading) return <div>Checking permission...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return can ? <UserList /> : <div>Access denied</div>;
+ * }
+ * ```
+ */
+export function useCan(
+  userId: UUID,
+  scope: Scope,
+  permission: Permission,
+  pageId?: UUID,
+  useCache: boolean = true,
+  /**
+   * Pre-computed super admin flag to avoid duplicate super admin checks.
+   * Callers should check super admin once and pass the result to all useCan hooks.
+   * Pass null if not checked yet, false/true if checked.
+   * Defaults to null (not checked yet) - hook will check if needed.
+   */
+  precomputedSuperAdmin: boolean | null = null,
+  appName?: string,
+) {
+  // CRITICAL FIX: Initialize isSuperAdmin from precomputed value immediately
+  // This prevents permission checks from running when we already know the user is a super admin
+  // If precomputedSuperAdmin is true, we can immediately set can=true and isLoading=false
+  const [isSuperAdmin, setIsSuperAdmin] = useState<boolean | null>(precomputedSuperAdmin ?? null);
+  
+  // For super admins, immediately grant permissions without waiting
+  const initialCan = precomputedSuperAdmin === true ? true : false;
+  const initialIsLoading = precomputedSuperAdmin === true ? false : true;
+  
+  const [can, setCan] = useState<boolean>(initialCan);
+  const [isLoading, setIsLoading] = useState<boolean>(initialIsLoading);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Validate scope parameter - handle undefined/null scope gracefully
+  const isValidScope = scope && typeof scope === 'object';
+  const organisationId = isValidScope ? scope.organisationId : undefined;
+  const eventId = isValidScope ? scope.eventId : undefined;
+  const appId = isValidScope ? scope.appId : undefined;
+
+  // CRITICAL FIX: Immediately update state when precomputedSuperAdmin changes to true
+  // This ensures super admins get immediate access without waiting for permission checks
+  useEffect(() => {
+    if (precomputedSuperAdmin === true && isSuperAdmin !== true) {
+      setIsSuperAdmin(true);
+      setCan(true);
+      setIsLoading(false);
+      setError(null);
+    } else if (precomputedSuperAdmin === false && isSuperAdmin !== false) {
+      setIsSuperAdmin(false);
+    }
+  }, [precomputedSuperAdmin, isSuperAdmin]);
+
+  // Check super-admin status - super admins bypass organisation context requirements
+  // PERFORMANCE OPTIMIZATION: Use precomputed value directly - no duplicate checks
+  // Callers must check super admin once and pass the result (null if not checked yet)
+  useEffect(() => {
+    // If precomputed value is null, it means not checked yet - check ourselves
+    if (precomputedSuperAdmin === null) {
+      if (!userId) {
+        setIsSuperAdmin(false);
+        return;
+      }
+
+      let cancelled = false;
+      const checkSuperAdmin = async () => {
+        const startTime = Date.now();
+        try {
+          const { isSuperAdmin: checkSuperAdmin } = await import('../../api');
+
+          // Add timeout warning
+          const timeoutWarning = setTimeout(() => {
+            if (!cancelled) {
+              console.warn('[useCan] Super admin check taking longer than 5 seconds', {
+                userId,
+                elapsedMs: Date.now() - startTime,
+              });
+            }
+          }, 5000);
+
+          const isSuper = await checkSuperAdmin(userId);
+          clearTimeout(timeoutWarning);
+
+          if (!cancelled) {
+            const elapsed = Date.now() - startTime;
+            if (elapsed > 1000) {
+              console.warn('[useCan] Super admin check took longer than expected', {
+                userId,
+                elapsedMs: elapsed,
+              });
+            }
+            setIsSuperAdmin(isSuper);
+            // If super admin, immediately grant permissions
+            if (isSuper) {
+              setCan(true);
+              setIsLoading(false);
+              setError(null);
+            }
+          }
+        } catch (err) {
+          if (!cancelled) {
+            const elapsed = Date.now() - startTime;
+            console.error('[useCan] Error checking super admin', {
+              userId,
+              error: err,
+              elapsedMs: elapsed,
+            });
+            setIsSuperAdmin(false);
+          }
+        }
+      };
+
+      checkSuperAdmin();
+      return () => {
+        cancelled = true;
+      };
+    }
+  }, [userId, precomputedSuperAdmin]);
+
+  // Add timeout for missing organisation context (3 seconds)
+  // Only apply timeout for resource-level permissions, not page-level (which can handle null orgs)
+  // Super admins bypass this check
+  useEffect(() => {
+    const isPagePermission = permission.includes(':page.') || !!pageId;
+    const requiresOrgId = !isPagePermission;
+
+    // Don't block if user is super-admin (they bypass context requirements)
+    if (isSuperAdmin === true) {
+      return;
+    }
+
+    if (requiresOrgId && (!isValidScope || !organisationId || organisationId === null || (typeof organisationId === 'string' && organisationId.trim() === ''))) {
+      const timeoutId = setTimeout(() => {
+        setError(new Error('Organisation context is required for permission checks'));
+        setIsLoading(false);
+        setCan(false);
+      }, 3000); // 3 seconds - typical permission check is < 1 second
+
+      return () => clearTimeout(timeoutId);
+    }
+    // Clear error if organisation context becomes available
+    if (error?.message === 'Organisation context is required for permission checks') {
+      setError(null);
+    }
+  }, [isValidScope, organisationId, error, permission, pageId, isSuperAdmin]);
+
+  // Use refs to track the last values to prevent unnecessary re-runs
+  const lastUserIdRef = useRef<UUID | null>(null);
+  const lastScopeRef = useRef<string | null>(null);
+  const lastPermissionRef = useRef<Permission | null>(null);
+  const lastPageIdRef = useRef<UUID | undefined | null>(null);
+  const lastUseCacheRef = useRef<boolean | null>(null);
+  const lastIsSuperAdminRef = useRef<boolean | null>(null);
+
+  // Create a stable scope object for comparison
+  const stableScope = useMemo(() => {
+    if (!isValidScope) {
+      return null;
+    }
+    return {
+      organisationId,
+      eventId,
+      appId,
+    };
+  }, [isValidScope, organisationId, eventId, appId]);
+
+  // Track previous scope for deep equality comparison
+  const prevScopeRef = useRef<Scope | null>(null);
+
+  useEffect(() => {
+    // Use deep equality check for scope to prevent unnecessary re-runs
+    const scopeChanged = !scopeEqual(prevScopeRef.current, stableScope);
+
+    // Only run if something has actually changed
+    // CRITICAL: Also check if isSuperAdmin changed - super admins bypass all checks
+    const isSuperAdminChanged = lastIsSuperAdminRef.current !== isSuperAdmin;
+    
+    if (
+      lastUserIdRef.current !== userId ||
+      scopeChanged ||
+      lastPermissionRef.current !== permission ||
+      lastPageIdRef.current !== pageId ||
+      lastUseCacheRef.current !== useCache ||
+      isSuperAdminChanged
+    ) {
+      lastIsSuperAdminRef.current = isSuperAdmin;
+      lastUserIdRef.current = userId;
+      prevScopeRef.current = stableScope;
+      lastPermissionRef.current = permission;
+      lastPageIdRef.current = pageId;
+      lastUseCacheRef.current = useCache;
+
+      // Inline the permission check logic to avoid useCallback dependency issues
+      const checkPermission = async () => {
+        if (!userId) {
+          setCan(false);
+          setIsLoading(false);
+          return;
+        }
+
+        // CRITICAL: Super admins bypass all permission checks - grant immediately
+        // This must be checked BEFORE any other validation to avoid unnecessary API calls
+        if (isSuperAdmin === true) {
+          setCan(true);
+          setIsLoading(false);
+          setError(null);
+          return;
+        }
+
+        // If super admin status is still being checked (null), wait for it to complete
+        // Don't proceed with permission check until we know if user is super admin
+        if (isSuperAdmin === null) {
+          setIsLoading(true);
+          setCan(false);
+          setError(null);
+          return;
+        }
+
+        // Validate scope before accessing properties
+        if (!isValidScope) {
+          setIsLoading(true);
+          setCan(false);
+          setError(null);
+          // Timeout is handled in separate useEffect
+          return;
+        }
+
+        // For page-level permissions, allow undefined/null organisationId (database function handles it)
+        // For resource-level permissions, organisationId is required
+        const isPagePermission = permission.includes(':page.') || !!pageId;
+        const requiresOrgId = !isPagePermission;
+
+        // Check if pageId is a pageName (not a UUID) - if so, we need appId to resolve it
+        const isPageName = pageId && typeof pageId === 'string' && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(pageId);
+        const needsAppIdForPageName = isPagePermission && isPageName;
+
+        // Don't check permissions if scope is invalid and orgId is required
+        // Wait for organisation context to resolve (unless it's a page permission that can handle null orgs)
+        if (requiresOrgId && (!organisationId || organisationId === null || (typeof organisationId === 'string' && organisationId.trim() === ''))) {
+          // Not super-admin (already checked above) - wait for org context
+          setIsLoading(true);
+          setCan(false);
+          setError(null);
+          // Timeout is handled in separate useEffect (Phase 1.4)
+          return;
+        }
+
+        // For page-level permissions with pageName (not UUID), we need appId to resolve the pageName to pageId
+        // Wait for appId to be available before checking permissions
+        if (needsAppIdForPageName && (!appId || appId === null || (typeof appId === 'string' && appId.trim() === ''))) {
+          setIsLoading(true);
+          setCan(false);
+          setError(null);
+          // Will re-run when appId becomes available (via scope change detection)
+          return;
+        }
+
+        try {
+          setIsLoading(true);
+          setError(null);
+
+          // Create a valid scope object for the API call
+          // For page-level permissions, organisationId can be undefined (database handles it)
+          const validScope: Scope = {
+            ...(organisationId ? { organisationId } : {}),
+            ...(eventId ? { eventId } : {}),
+            ...(appId ? { appId } : {})
+          };
+
+          // Pass super admin status to avoid duplicate check in isPermitted
+          // Note: isPermittedCached doesn't support precomputedSuperAdmin, but the check will be cached
+          // If we know user is NOT super admin (isSuperAdmin === false), pass false to skip the check
+          const result = useCache
+            ? await isPermittedCached({ userId, scope: validScope, permission, pageId }, appName)
+            : await isPermitted({ userId, scope: validScope, permission, pageId }, appName, isSuperAdmin === false ? false : null);
+
+          setCan(result);
+        } catch (err) {
+          const logger = getRBACLogger();
+          logger.error('Permission check error:', { permission, error: err });
+          console.error('[useCan] Permission check error', { userId, permission, error: err });
+          setError(err instanceof Error ? err : new Error('Failed to check permission'));
+          setCan(false);
+        } finally {
+          setIsLoading(false);
+        }
+      };
+
+      checkPermission();
+    }
+  }, [userId, stableScope, permission, pageId, useCache, appName, isSuperAdmin]);
+
+  const refetch = useCallback(async () => {
+    if (!userId) {
+      setCan(false);
+      setIsLoading(false);
+      return;
+    }
+
+    // Validate scope before accessing properties
+    if (!isValidScope) {
+      setCan(false);
+      setIsLoading(true);
+      setError(null);
+      return;
+    }
+
+    // For page-level permissions, allow undefined/null organisationId (database function handles it)
+    // For resource-level permissions, organisationId is required
+    const isPagePermission = permission.includes(':page.') || !!pageId;
+    const requiresOrgId = !isPagePermission;
+
+    // Don't check permissions if scope is invalid and orgId is required
+    if (requiresOrgId && (!organisationId || organisationId === null || (typeof organisationId === 'string' && organisationId.trim() === ''))) {
+      setCan(false);
+      setIsLoading(true);
+      setError(null);
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      // Create a valid scope object for the API call
+      // For page-level permissions, organisationId can be undefined (database handles it)
+      const validScope: Scope = {
+        ...(organisationId ? { organisationId } : {}),
+        ...(eventId ? { eventId } : {}),
+        ...(appId ? { appId } : {})
+      };
+
+      const result = useCache
+        ? await isPermittedCached({ userId, scope: validScope, permission, pageId }, appName)
+        : await isPermitted({ userId, scope: validScope, permission, pageId }, appName, null);
+
+      setCan(result);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to check permission'));
+      setCan(false);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [userId, isValidScope, organisationId, eventId, appId, permission, pageId, useCache, appName]);
+
+  // Memoize the return object to prevent unnecessary re-renders
+  return useMemo(() => ({
+    can,
+    isLoading,
+    error,
+    refetch
+  }), [can, isLoading, error, refetch]);
+}

package/src/rbac/hooks/permissions/useHasAllPermissions.ts

@@ -0,0 +1,90 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { isPermitted, isPermittedCached } from '../../api';
+import { Permission, Scope, UUID } from '../../types';
+
+/**
+ * Hook to check if user has all of the specified permissions
+ *
+ * @param userId - User ID
+ * @param scope - Scope for permission checking
+ * @param permissions - Array of permissions to check
+ * @param useCache - Whether to use cached results
+ * @returns Whether user has all of the permissions
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { hasAll, isLoading, error } = useHasAllPermissions(
+ *     userId,
+ *     scope,
+ *     ['read:users', 'create:users', 'update:users']
+ *   );
+ *
+ *   if (isLoading) return <div>Checking permissions...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return hasAll ? <FullUserManagementPanel /> : <div>Insufficient permissions</div>;
+ * }
+ * ```
+ */
+export function useHasAllPermissions(
+  userId: UUID,
+  scope: Scope,
+  permissions: Permission[],
+  useCache: boolean = true
+): {
+  hasAll: boolean;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+} {
+  const [hasAll, setHasAll] = useState<boolean>(false);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const checkAllPermissions = useCallback(async () => {
+    if (!userId || permissions.length === 0) {
+      setHasAll(false);
+      setIsLoading(false);
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      let hasAllPermissions = true;
+
+      for (const permission of permissions) {
+        const result = useCache
+          ? await isPermittedCached({ userId, scope, permission })
+          : await isPermitted({ userId, scope, permission });
+
+        if (!result) {
+          hasAllPermissions = false;
+          break;
+        }
+      }
+
+      setHasAll(hasAllPermissions);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to check permissions'));
+      setHasAll(false);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [userId, scope.organisationId, scope.eventId, scope.appId, permissions, useCache]);
+
+  useEffect(() => {
+    checkAllPermissions();
+  }, [checkAllPermissions]);
+
+  // Memoize the return object to prevent unnecessary re-renders
+  return useMemo(() => ({
+    hasAll,
+    isLoading,
+    error,
+    refetch: checkAllPermissions
+  }), [hasAll, isLoading, error, checkAllPermissions]);
+}

package/src/rbac/hooks/permissions/useHasAnyPermission.ts

@@ -0,0 +1,90 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { isPermitted, isPermittedCached } from '../../api';
+import { Permission, Scope, UUID } from '../../types';
+
+/**
+ * Hook to check if user has any of the specified permissions
+ *
+ * @param userId - User ID
+ * @param scope - Scope for permission checking
+ * @param permissions - Array of permissions to check
+ * @param useCache - Whether to use cached results
+ * @returns Whether user has any of the permissions
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { hasAny, isLoading, error } = useHasAnyPermission(
+ *     userId,
+ *     scope,
+ *     ['read:users', 'create:users']
+ *   );
+ *
+ *   if (isLoading) return <div>Checking permissions...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return hasAny ? <UserManagementPanel /> : <div>No user permissions</div>;
+ * }
+ * ```
+ */
+export function useHasAnyPermission(
+  userId: UUID,
+  scope: Scope,
+  permissions: Permission[],
+  useCache: boolean = true
+): {
+  hasAny: boolean;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+} {
+  const [hasAny, setHasAny] = useState<boolean>(false);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const checkAnyPermission = useCallback(async () => {
+    if (!userId || permissions.length === 0) {
+      setHasAny(false);
+      setIsLoading(false);
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      let hasAnyPermission = false;
+
+      for (const permission of permissions) {
+        const result = useCache
+          ? await isPermittedCached({ userId, scope, permission })
+          : await isPermitted({ userId, scope, permission });
+
+        if (result) {
+          hasAnyPermission = true;
+          break;
+        }
+      }
+
+      setHasAny(hasAnyPermission);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to check permissions'));
+      setHasAny(false);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [userId, scope.organisationId, scope.eventId, scope.appId, permissions, useCache]);
+
+  useEffect(() => {
+    checkAnyPermission();
+  }, [checkAnyPermission]);
+
+  // Memoize the return object to prevent unnecessary re-renders
+  return useMemo(() => ({
+    hasAny,
+    isLoading,
+    error,
+    refetch: checkAnyPermission
+  }), [hasAny, isLoading, error, checkAnyPermission]);
+}

package/src/rbac/hooks/permissions/useMultiplePermissions.ts

@@ -0,0 +1,93 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { isPermitted, isPermittedCached } from '../../api';
+import { Permission, Scope, UUID } from '../../types';
+
+/**
+ * Hook to check multiple permissions at once
+ *
+ * @param userId - User ID
+ * @param scope - Scope for permission checking
+ * @param permissions - Array of permissions to check
+ * @param useCache - Whether to use cached results
+ * @returns Multiple permission check results
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { results, isLoading, error } = useMultiplePermissions(
+ *     userId,
+ *     scope,
+ *     ['read:users', 'create:users', 'update:users']
+ *   );
+ *
+ *   if (isLoading) return <div>Checking permissions...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {results['read:users'] && <UserList />}
+ *       {results['create:users'] && <CreateUserButton />}
+ *       {results['update:users'] && <EditUserButton />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useMultiplePermissions(
+  userId: UUID,
+  scope: Scope,
+  permissions: Permission[],
+  useCache: boolean = true
+): {
+  results: Record<Permission, boolean>;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+} {
+  const [results, setResults] = useState<Record<Permission, boolean>>({} as Record<Permission, boolean>);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const checkPermissions = useCallback(async () => {
+    if (!userId || permissions.length === 0) {
+      setResults({} as Record<Permission, boolean>);
+      setIsLoading(false);
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      const permissionResults: Record<Permission, boolean> = {} as Record<Permission, boolean>;
+
+      // Check each permission
+      for (const permission of permissions) {
+        const result = useCache
+          ? await isPermittedCached({ userId, scope, permission })
+          : await isPermitted({ userId, scope, permission });
+        permissionResults[permission] = result;
+      }
+
+      setResults(permissionResults);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to check permissions'));
+      setResults({} as Record<Permission, boolean>);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [userId, scope.organisationId, scope.eventId, scope.appId, permissions, useCache]);
+
+  useEffect(() => {
+    checkPermissions();
+  }, [checkPermissions]);
+
+  // Memoize the return object to prevent unnecessary re-renders
+  return useMemo(() => ({
+    results,
+    isLoading,
+    error,
+    refetch: checkPermissions
+  }), [results, isLoading, error, checkPermissions]);
+}