@jmruthers/pace-core 0.6.1 → 0.6.2

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

@@ -0,0 +1,105 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { getAccessLevel } from '../../api';
+import { OrganisationContextRequiredError } from '../../types';
+import type { AccessLevel as AccessLevelType, Scope, UUID } from '../../types';
+import { useAppConfig } from '../../../hooks/useAppConfig';
+
+/**
+ * Hook to get user's access level in a scope
+ *
+ * @param userId - User ID
+ * @param scope - Scope for access level checking
+ * @returns Access level state and methods
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { accessLevel, isLoading, error } = useAccessLevel(userId, scope);
+ *
+ *   if (isLoading) return <div>Loading access level...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       Access Level: {accessLevel}
+ *       {accessLevel >= AccessLevel.ADMIN && <AdminPanel />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useAccessLevel(userId: UUID, scope: Scope): {
+  accessLevel: AccessLevelType;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+} {
+  const [accessLevel, setAccessLevel] = useState<AccessLevelType>('viewer');
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Get appName from context if available (safely handles missing context)
+  let appName: string | undefined;
+  try {
+    const { appName: contextAppName } = useAppConfig();
+    appName = contextAppName;
+  } catch {
+    // Not available, will use undefined
+  }
+
+  const fetchAccessLevel = useCallback(async () => {
+    if (!userId) {
+      setAccessLevel('viewer');
+      setIsLoading(false);
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      // Check super admin status first - super admins bypass context requirements
+      // This allows super admins to check their access level without organisation context
+      const { isSuperAdmin: checkSuperAdmin } = await import('../../api');
+      const isSuperAdminUser = await checkSuperAdmin(userId);
+
+      if (isSuperAdminUser) {
+        setAccessLevel('super');
+        setIsLoading(false);
+        return;
+      }
+
+      // Early validation: check if scope has required context
+      // PORTAL/ADMIN apps allow both contexts to be optional
+      if (appName !== 'PORTAL' && appName !== 'ADMIN' && !scope.organisationId && !scope.eventId) {
+        const orgError = new OrganisationContextRequiredError();
+        setError(orgError);
+        setAccessLevel('viewer');
+        setIsLoading(false);
+        return;
+      }
+
+      const level = await getAccessLevel({ userId, scope }, null, appName);
+      setAccessLevel(level);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error('Failed to fetch access level');
+      setError(error);
+      setAccessLevel('viewer');
+    } finally {
+      setIsLoading(false);
+    }
+  }, [userId, scope.organisationId, scope.eventId, scope.appId, appName]);
+
+  useEffect(() => {
+    fetchAccessLevel();
+  }, [fetchAccessLevel]);
+
+  // Memoize the return object to prevent unnecessary re-renders
+  return useMemo(() => ({
+    accessLevel,
+    isLoading,
+    error,
+    refetch: fetchAccessLevel
+  }), [accessLevel, isLoading, error, fetchAccessLevel]);
+}

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

@@ -0,0 +1,79 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { getPermissionMap } from '../../api';
+import { PermissionMap, Scope, UUID } from '../../types';
+
+/**
+ * Hook to get cached permissions with TTL management
+ *
+ * @param userId - User ID
+ * @param scope - Scope for permission checking
+ * @returns Cached permission state and methods
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { permissions, isLoading, error, invalidateCache } = useCachedPermissions(userId, scope);
+ *
+ *   if (isLoading) return <div>Loading cached permissions...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {permissions['read:users'] && <UserList />}
+ *       <button onClick={invalidateCache}>Refresh Permissions</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useCachedPermissions(userId: UUID, scope: Scope): {
+  permissions: PermissionMap;
+  isLoading: boolean;
+  error: Error | null;
+  invalidateCache: () => void;
+  refetch: () => Promise<void>;
+} {
+  const [permissions, setPermissions] = useState<PermissionMap>({} as PermissionMap);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchCachedPermissions = useCallback(async () => {
+    if (!userId) {
+      setPermissions({} as PermissionMap);
+      setIsLoading(false);
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      const permissionMap = await getPermissionMap({ userId, scope });
+      setPermissions(permissionMap);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('Failed to fetch cached permissions'));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [userId, scope.organisationId, scope.eventId, scope.appId]);
+
+  const invalidateCache = useCallback(() => {
+    // This would typically invalidate the cache in the actual implementation
+    // For now, we'll just refetch
+    fetchCachedPermissions();
+  }, [fetchCachedPermissions]);
+
+  useEffect(() => {
+    fetchCachedPermissions();
+  }, [fetchCachedPermissions]);
+
+  // Memoize the return object to prevent unnecessary re-renders
+  return useMemo(() => ({
+    permissions,
+    isLoading,
+    error,
+    invalidateCache,
+    refetch: fetchCachedPermissions
+  }), [permissions, isLoading, error, invalidateCache, fetchCachedPermissions]);
+}

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

@@ -0,0 +1,347 @@
+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,
+) {
+  const [can, setCan] = useState<boolean>(false);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [isSuperAdmin, setIsSuperAdmin] = useState<boolean | null>(precomputedSuperAdmin ?? 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;
+
+  // 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);
+          }
+        } 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;
+      };
+    } else {
+      // Precomputed value provided (true/false) - use it directly, no check needed
+      setIsSuperAdmin(precomputedSuperAdmin);
+    }
+  }, [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);
+
+  // 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
+    if (
+      lastUserIdRef.current !== userId ||
+      scopeChanged ||
+      lastPermissionRef.current !== permission ||
+      lastPageIdRef.current !== pageId ||
+      lastUseCacheRef.current !== useCache
+    ) {
+      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 }, undefined, appName)
+            : await isPermitted({ userId, scope: validScope, permission, pageId }, undefined, 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 }, undefined, appName)
+        : await isPermitted({ userId, scope: validScope, permission, pageId }, undefined, 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 }, null, undefined, null);
+
+        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]);
+}