@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/components/NavigationMenu/navigationPermissionHelper.ts

@@ -0,0 +1,188 @@
+/**
+ * @file Navigation Permission Helper
+ * @package @jmruthers/pace-core
+ * @module NavigationMenu/navigationPermissionHelper
+ * @since 0.1.0
+ *
+ * Shared permission/role/access-level logic for navigation items.
+ * Used by useNavigationFiltering (filtering) and NavigationMenu (click re-validation).
+ */
+
+import type {
+  Permission,
+  AccessLevel as RBACAccessLevel,
+  PermissionMap,
+  UserRBACContext,
+} from "../../rbac/types";
+import type { NavigationItem } from "./types";
+
+/** Minimal RBAC context needed for permission checks. */
+export type NavigationRBACContext = Pick<
+  UserRBACContext,
+  "isSuperAdmin" | "isOrgAdmin" | "isEventAdmin" | "organisationRole" | "eventAppRole"
+>;
+
+const ROLE_TO_ACCESS_LEVEL: Record<string, RBACAccessLevel> = {
+  viewer: "viewer",
+  participant: "participant",
+  planner: "planner",
+  event_admin: "admin",
+  admin: "admin",
+};
+
+const LEVEL_HIERARCHY: Record<RBACAccessLevel, number> = {
+  viewer: 1,
+  participant: 2,
+  planner: 3,
+  admin: 4,
+  super: 5,
+};
+
+/**
+ * Derives page id from href (path without query/hash, leading slash removed).
+ * Returns "home" for root path.
+ */
+export function getPageIdFromHref(href?: string): string | null {
+  if (!href) return null;
+  const path = href.split("?")[0].split("#")[0].replace(/^\//, "");
+  return path || "home";
+}
+
+/**
+ * Type guard: string that is a valid Permission shape.
+ */
+export function isPermission(p: Permission | string): p is Permission {
+  return typeof p === "string" && /^(read|create|update|delete):/.test(p);
+}
+
+/**
+ * Returns true if the user has permission to access the navigation item
+ * according to item.permissions, item.roles, item.accessLevel, and page permission (href/pageId).
+ */
+export function navigationItemHasPermission(
+  item: NavigationItem,
+  rbacContext: NavigationRBACContext,
+  permissionMap: PermissionMap,
+  hasAnyPermission: ((permissions: Permission[]) => boolean) | null
+): boolean {
+  // Explicit permissions (required when item has permissions array)
+  if (item.permissions && item.permissions.length > 0 && hasAnyPermission) {
+    const permissions = item.permissions.filter(
+      (p): p is Permission => typeof p === "string"
+    ) as Permission[];
+    if (permissions.length > 0 && !hasAnyPermission(permissions)) {
+      return false;
+    }
+  }
+
+  // Role requirements
+  if (item.roles && item.roles.length > 0) {
+    const hasRole = item.roles.some((role) => {
+      if (typeof role !== "string") return true;
+      const r = role.toLowerCase();
+      switch (r) {
+        case "super_admin":
+        case "super admin":
+          return rbacContext.isSuperAdmin;
+        case "org_admin":
+        case "org admin":
+        case "admin":
+          return rbacContext.isOrgAdmin || rbacContext.isSuperAdmin;
+        case "event_admin":
+        case "event admin":
+          return rbacContext.isEventAdmin || rbacContext.isSuperAdmin;
+        default:
+          return (
+            rbacContext.organisationRole === role ||
+            rbacContext.eventAppRole === role ||
+            rbacContext.isSuperAdmin
+          );
+      }
+    });
+    if (!hasRole) return false;
+  }
+
+  // Access level
+  if (item.accessLevel && typeof item.accessLevel === "string") {
+    const accessLevel = item.accessLevel.toLowerCase() as RBACAccessLevel;
+    const userEventRole = rbacContext.eventAppRole;
+    if (!rbacContext.isSuperAdmin) {
+      const userAccessLevel = userEventRole
+        ? ROLE_TO_ACCESS_LEVEL[userEventRole] || "viewer"
+        : null;
+      const requiredLevel = LEVEL_HIERARCHY[accessLevel] || 0;
+      const userLevel = userAccessLevel ? LEVEL_HIERARCHY[userAccessLevel] || 0 : 0;
+      if (userLevel < requiredLevel) return false;
+    }
+  }
+
+  // Page permission (href → read:page.{pageId}); super admin (RBAC or permission map) bypasses
+  if (item.href) {
+    const pageId = item.pageId || getPageIdFromHref(item.href);
+    if (pageId) {
+      const isSuperAdminByMap = permissionMap["*"] === true;
+      const isSuperAdminByRole = rbacContext.isSuperAdmin;
+      if (isSuperAdminByRole || isSuperAdminByMap) return true;
+      const pagePermission: Permission = `read:page.${pageId}` as Permission;
+      const hasPagePermission = permissionMap[pagePermission] === true;
+      if (!hasPagePermission) return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Returns true if targetId is in the tree (item or any nested child).
+ */
+function isInFilteredTree(list: NavigationItem[], targetId: string): boolean {
+  return list.some(
+    (f) => f.id === targetId || (f.children != null && isInFilteredTree(f.children, targetId))
+  );
+}
+
+export interface ResolveNavigationAccessParams {
+  item: NavigationItem;
+  authContext: unknown;
+  rbacContext: NavigationRBACContext | null;
+  filteredItems: NavigationItem[];
+  permissionMap: PermissionMap;
+  hasAnyPermission: ((permissions: Permission[]) => boolean) | null;
+}
+
+/**
+ * Re-validates whether the user is allowed to navigate to the item.
+ * Used by NavigationMenu handleItemClick to avoid duplicating permission logic.
+ */
+export function resolveNavigationAccess(params: ResolveNavigationAccessParams): { allowed: boolean } {
+  const { item, authContext, rbacContext, filteredItems, permissionMap, hasAnyPermission } =
+    params;
+
+  if (!authContext) {
+    return { allowed: true };
+  }
+
+  const isItemVisible = isInFilteredTree(filteredItems, item.id);
+  if (!isItemVisible) {
+    return { allowed: false };
+  }
+
+  let hasPermission = false;
+  if (rbacContext && permissionMap && Object.keys(permissionMap).length > 0) {
+    hasPermission = navigationItemHasPermission(
+      item,
+      rbacContext,
+      permissionMap,
+      hasAnyPermission
+    );
+  }
+  if (
+    !hasPermission &&
+    (!permissionMap || Object.keys(permissionMap).length === 0) &&
+    isItemVisible
+  ) {
+    hasPermission = true;
+  }
+
+  return { allowed: hasPermission };
+}

package/src/components/NavigationMenu/{__tests__/useNavigationFiltering.test.ts → useNavigationFiltering.test.ts}

@@ -1,7 +1,7 @@
 /**
  * @file useNavigationFiltering Hook Tests
  * @package @jmruthers/pace-core
- * @module NavigationMenu/__tests__
+ * @module NavigationMenu
  * @since 0.1.0
  *
  * Comprehensive unit tests for the useNavigationFiltering hook covering:
@@ -18,10 +18,10 @@
 
 import { renderHook, act, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { useNavigationFiltering } from '../useNavigationFiltering';
+import { useNavigationFiltering } from './useNavigationFiltering';
 import type { NavigationItem } from '../types';
-import type { Permission, PermissionMap } from '../../../rbac/types';
-import { logger } from '../../../utils/core/logger';
+import type { Permission, PermissionMap } from '../../rbac/types';
+import { logger } from '../../utils/core/logger';
 
 // Mock dependencies with hoisted functions for per-test control
 const mockUseUnifiedAuth = vi.hoisted(() => vi.fn());
@@ -32,29 +32,29 @@ const mockResolveAppContext = vi.hoisted(() => vi.fn());
 
 // CRITICAL: Mock must return a function that calls the hoisted mock
 // This ensures the mock is reactive to changes
-vi.mock('../../../providers/services/UnifiedAuthProvider', () => ({
+vi.mock('../../providers/services/UnifiedAuthProvider', () => ({
   useUnifiedAuth: () => {
     // Call the hoisted mock function - it will return the current mock value
     return mockUseUnifiedAuth();
   },
 }));
 
-vi.mock('../../../rbac/hooks/useRBAC', () => ({
+vi.mock('../../rbac/hooks/useRBAC', () => ({
   useRBAC: () => mockUseRBAC(),
 }));
 
 // Mock useResolvedScope - must match the actual import path
-vi.mock('../../../rbac/hooks/useResolvedScope', () => ({
+vi.mock('../../rbac/hooks/useResolvedScope', () => ({
   useResolvedScope: (options: any) => mockUseResolvedScope(options),
 }));
 
-vi.mock('../../../rbac/hooks/usePermissions', () => ({
+vi.mock('../../rbac/hooks/usePermissions', () => ({
   usePermissions: (userId: any, orgId: any, eventId: any, appId: any) =>
     mockUsePermissions(userId, orgId, eventId, appId),
 }));
 
-vi.mock('../../../rbac/api', async () => {
-  const actual = await vi.importActual('../../../rbac/api');
+vi.mock('../../rbac/api', async () => {
+  const actual = await vi.importActual('../../rbac/api');
   return {
     ...actual,
     resolveAppContext: mockResolveAppContext,
@@ -62,7 +62,7 @@ vi.mock('../../../rbac/api', async () => {
 });
 
 // Mock logger to avoid console noise - must include createLogger export
-vi.mock('../../../utils/core/logger', () => ({
+vi.mock('../../utils/core/logger', () => ({
   createLogger: vi.fn(() => ({
     warn: vi.fn(),
     error: vi.fn(),
@@ -252,16 +252,7 @@ describe('useNavigationFiltering Hook', () => {
         error: null,
       });
 
-      // The hook has an early return at line 176-179 when selectedOrganisation exists
-      // This shows all items (except hidden) as a fallback for performance
-      // To test actual permission filtering, we need to ensure we have a permission map
-      // and the hook proceeds to the permission checking logic
-      // The early return happens when: items && items.length > 0 && selectedOrganisation?.id
-      // But permission filtering happens when we have a permission map (line 207+)
-      // So we need to ensure the permission map exists and we get past the early return
-      // Actually, the early return happens BEFORE permission checks, so we can't test
-      // permission filtering with selectedOrganisation present
-      // Instead, test that itemsPreFiltered bypasses permission checks
+      // With itemsPreFiltered, only meta.hidden is applied; permission checks are skipped.
       const { result } = renderHook(() =>
         useNavigationFiltering({ items, itemsPreFiltered: true })
       );
@@ -270,14 +261,29 @@ describe('useNavigationFiltering Hook', () => {
       expect(result.current.filteredItems).toHaveLength(2);
     });
 
+    it('filters items by permission when selectedOrganisation present and itemsPreFiltered false', () => {
+      const items: NavigationItem[] = [
+        { id: 'allowed', label: 'Allowed', href: '/allowed' },
+        { id: 'denied', label: 'Denied', href: '/denied' },
+      ];
+      const permissionMap: PermissionMap = {
+        'read:page.allowed': true,
+        'read:page.denied': false,
+      };
+      mockUsePermissions.mockReturnValue({
+        permissions: permissionMap,
+        hasAnyPermission: vi.fn(() => false),
+        isLoading: false,
+        error: null,
+      });
+      const { result } = renderHook(() =>
+        useNavigationFiltering({ items, itemsPreFiltered: false })
+      );
+      expect(result.current.filteredItems).toHaveLength(1);
+      expect(result.current.filteredItems[0].id).toBe('allowed');
+    });
+
     it('checks permissions for items without href when permission map available', () => {
-      // The hook has an early return when selectedOrganisation exists (line 176-179)
-      // This shows all items (except hidden) as a performance optimization
-      // Permission filtering only happens when we get past that early return
-      // To test permission filtering, we need to ensure the permission map exists
-      // and the hook proceeds to the permission checking logic
-      // However, with selectedOrganisation present, we hit the early return
-      // So we test that itemsPreFiltered bypasses permission checks
       const items: NavigationItem[] = [
         { id: 'action1', label: 'Action 1', permissions: ['action1:execute'] },
         { id: 'action2', label: 'Action 2', permissions: ['action2:execute'] },
@@ -293,11 +299,6 @@ describe('useNavigationFiltering Hook', () => {
     });
 
     it('filters items based on page permissions when permission map is available', () => {
-      // Note: The hook has an early return at line 176-179 when selectedOrganisation exists
-      // This shows all items (except hidden) as a fallback for performance
-      // Permission filtering logic (line 229+) only runs when we get past early returns
-      // With selectedOrganisation present, we hit the early return
-      // So we test the behavior with itemsPreFiltered which bypasses permission checks
       const items: NavigationItem[] = [
         { id: 'dashboard', label: 'Dashboard', href: '/dashboard' },
         { id: 'users', label: 'Users', href: '/users' },
@@ -466,9 +467,6 @@ describe('useNavigationFiltering Hook', () => {
 
   describe('Access Level Filtering', () => {
     it('handles access level filtering when permission map is available', () => {
-      // Note: The hook has an early return when selectedOrganisation exists
-      // Access level filtering logic exists but may not run due to early return
-      // We test that the hook handles items with access levels correctly
       const items: NavigationItem[] = [
         { id: 'viewer', label: 'Viewer', href: '/viewer', accessLevel: 'viewer' },
         { id: 'planner', label: 'Planner', href: '/planner', accessLevel: 'planner' },
@@ -517,6 +515,13 @@ describe('useNavigationFiltering Hook', () => {
         eventAppRole: 'planner',
       });
 
+      mockUsePermissions.mockReturnValue({
+        permissions: { ...mockPermissionMap, 'read:page.item': true },
+        hasAnyPermission: mockHasAnyPermission,
+        isLoading: false,
+        error: null,
+      });
+
       const { result } = renderHook(() =>
         useNavigationFiltering({ items, itemsPreFiltered: false })
       );
@@ -751,13 +756,10 @@ describe('useNavigationFiltering Hook', () => {
         error: new Error('Permission fetch failed'),
       });
 
-      // When permission error occurs, should return empty for security (line 196-205)
-      // But the early return at line 176-179 happens first if selectedOrganisation exists
-      // To test permission error handling, we need to bypass the early return
-      // by having no selectedOrganisation but valid resolved scope
+      // When permission error occurs, hook returns empty for security.
       mockUseUnifiedAuth.mockReturnValue({
         ...mockAuthContext,
-        selectedOrganisation: null, // No org to trigger early return
+        selectedOrganisation: null,
       });
 
       mockUseResolvedScope.mockReturnValue({
@@ -871,15 +873,17 @@ describe('useNavigationFiltering Hook', () => {
         },
       ];
 
-      // No permissions for any children - they need page permissions
+      // Non-empty permission map so we run recursive filtering (empty map triggers early return with all items)
+      const permissionMapWithEntries: PermissionMap = {
+        'read:page.dashboard': true,
+      };
       mockUsePermissions.mockReturnValue({
-        permissions: {},
+        permissions: permissionMapWithEntries,
         hasAnyPermission: vi.fn(() => false),
         isLoading: false,
         error: null,
       });
 
-      // Bypass early return to test permission filtering
       mockUseUnifiedAuth.mockReturnValue({
         ...mockAuthContext,
         selectedOrganisation: null,
@@ -1220,6 +1224,13 @@ describe('useNavigationFiltering Hook', () => {
         { id: 'normal', label: 'Normal', href: '/' },
       ];
 
+      mockUsePermissions.mockReturnValue({
+        permissions: { ...mockPermissionMap, 'read:page.home': true },
+        hasAnyPermission: mockHasAnyPermission,
+        isLoading: false,
+        error: null,
+      });
+
       const { result } = renderHook(() =>
         useNavigationFiltering({ items, itemsPreFiltered: false })
       );
@@ -1273,7 +1284,6 @@ describe('useNavigationFiltering Hook', () => {
 
       // Need to have selectedOrganisation to avoid early empty return
       // But also need permission map to test filtering
-      // The hook shows all items when selectedOrganisation exists (early return)
       // So we test with itemsPreFiltered to bypass that
       const { result } = renderHook(() =>
         useNavigationFiltering({ items, itemsPreFiltered: true })
@@ -1526,14 +1536,12 @@ describe('useNavigationFiltering Hook', () => {
         error: null,
       });
 
-      // When scope is loading but selectedOrganisation exists, items are shown
-      // (early return at line 176-179)
       const { result } = renderHook(() =>
         useNavigationFiltering({ items, itemsPreFiltered: false })
       );
 
-      // Should show items when selectedOrganisation exists even if scope is loading
-      expect(result.current.filteredItems.length).toBeGreaterThan(0);
+      // When scope is loading we do not show items until scope is resolved (security by default)
+      expect(result.current.filteredItems).toEqual([]);
     });
 
     it('handles permissions loading with previous items', () => {
@@ -1600,7 +1608,6 @@ describe('useNavigationFiltering Hook', () => {
         error: null,
       });
 
-      // Bypass early return
       mockUseUnifiedAuth.mockReturnValue({
         ...mockAuthContext,
         selectedOrganisation: null,
@@ -1711,7 +1718,7 @@ describe('useNavigationFiltering Hook', () => {
       ];
 
       // Deny permission but grant role
-      mockHasAnyPermission.mockImplementation((permissions: Permission[]) => {
+      mockHasAnyPermission.mockImplementation((_permissions: Permission[]) => {
         return false; // Deny permission
       });
 
@@ -1735,7 +1742,7 @@ describe('useNavigationFiltering Hook', () => {
           id: 'item',
           label: 'Item',
           href: '/item',
-          permissions: ['item:read'],
+          permissions: ['read:page.item'] as Permission[],
           accessLevel: 'admin',
         },
       ];
@@ -1744,9 +1751,17 @@ describe('useNavigationFiltering Hook', () => {
         'read:page.item': true,
       };
 
+      mockUseResolvedScope.mockReturnValue({
+        resolvedScope: { organisationId: mockOrgId, eventId: mockEventId, appId: mockAppId },
+        isLoading: false,
+        error: null,
+      });
+
       mockUsePermissions.mockReturnValue({
         permissions: permissionMap,
-        hasAnyPermission: vi.fn(() => true),
+        hasAnyPermission: vi.fn((perms: Permission[]) =>
+          perms.some((p) => permissionMap[p as keyof PermissionMap] === true)
+        ),
         isLoading: false,
         error: null,
       });