@jmruthers/pace-core 0.6.10 → 0.6.11

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

@@ -42,15 +42,15 @@ describe('useCan Hook', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     // Reset mocks to return resolved promises by default
-    mockIsPermitted.mockResolvedValue(true);
-    mockIsPermittedCached.mockResolvedValue(true);
+    mockIsPermitted.mockResolvedValue({ ok: true, data: true });
+    mockIsPermittedCached.mockResolvedValue({ ok: true, data: true });
     // Default to not super admin for most tests
-    mockIsSuperAdmin.mockResolvedValue(false);
+    mockIsSuperAdmin.mockResolvedValue({ ok: true, data: false });
   });
 
       describe('Permission Checking', () => {
     it('returns true for allowed permissions', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, undefined, false, false)
@@ -67,7 +67,7 @@ describe('useCan Hook', () => {
     });
 
     it('returns false for denied permissions', async () => {
-      mockIsPermitted.mockResolvedValue(false);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: false });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, undefined, false, false)
@@ -110,7 +110,7 @@ describe('useCan Hook', () => {
 
   describe('Caching', () => {
     it('uses cache when useCache is true', async () => {
-      mockIsPermittedCached.mockResolvedValue(true);
+      mockIsPermittedCached.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, mockPageId, true, false)
@@ -133,7 +133,7 @@ describe('useCan Hook', () => {
     });
 
     it('does not use cache when useCache is false', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, mockPageId, false, false)
@@ -157,7 +157,7 @@ describe('useCan Hook', () => {
     });
 
     it('defaults to not using cache', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, mockPageId, false, false)
@@ -173,7 +173,7 @@ describe('useCan Hook', () => {
 
   describe('Page ID Handling', () => {
     it('uses provided pageId', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, 'custom-page', false, false)
@@ -195,7 +195,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles undefined pageId', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, undefined, false, false)
@@ -219,7 +219,7 @@ describe('useCan Hook', () => {
 
   describe('Dependency Changes', () => {
     it('refetches when userId changes', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result, rerender } = renderHook(
         ({ userId, scope, permission }) => useCan(userId, scope, permission, undefined, false, false),
@@ -259,7 +259,7 @@ describe('useCan Hook', () => {
     });
 
     it('refetches when scope changes', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result, rerender } = renderHook(
         ({ userId, scope, permission }) => useCan(userId, scope, permission, undefined, false, false),
@@ -300,7 +300,7 @@ describe('useCan Hook', () => {
     });
 
     it('refetches when permission changes', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result, rerender } = renderHook(
         ({ userId, scope, permission }) => useCan(userId, scope, permission, undefined, false, false),
@@ -357,7 +357,7 @@ describe('useCan Hook', () => {
     it('clears error on successful refetch', async () => {
       mockIsPermitted
         .mockRejectedValueOnce(new Error('Initial error'))
-        .mockResolvedValueOnce(true);
+        .mockResolvedValueOnce({ ok: true, data: true });
 
       const { result, rerender } = renderHook(
         ({ userId, scope, permission }) => useCan(userId, scope, permission, undefined, false, false),
@@ -407,7 +407,7 @@ describe('useCan Hook', () => {
     });
 
     it('denies super admin permissions for regular users', async () => {
-      mockIsPermitted.mockResolvedValue(false);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: false });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, 'super_admin', undefined, false, false)
@@ -421,7 +421,7 @@ describe('useCan Hook', () => {
     });
 
     it('allows organisation admin permissions', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, 'org_admin', undefined, false, false)
@@ -435,7 +435,7 @@ describe('useCan Hook', () => {
     });
 
     it('denies organisation admin permissions for members', async () => {
-      mockIsPermitted.mockResolvedValue(false);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: false });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, 'org_admin', undefined, false, false)
@@ -449,7 +449,7 @@ describe('useCan Hook', () => {
     });
 
     it('allows event admin permissions', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, 'event_admin', undefined, false, false)
@@ -463,7 +463,7 @@ describe('useCan Hook', () => {
     });
 
     it('denies event admin permissions for participants', async () => {
-      mockIsPermitted.mockResolvedValue(false);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: false });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, 'event_admin', undefined, false, false)
@@ -477,7 +477,7 @@ describe('useCan Hook', () => {
     });
 
     it('allows member permissions', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, 'read:users', undefined, false, false)
@@ -491,7 +491,7 @@ describe('useCan Hook', () => {
     });
 
     it('denies member permissions for participants', async () => {
-      mockIsPermitted.mockResolvedValue(false);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: false });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, 'read:users', undefined, false, false)
@@ -505,7 +505,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles participant-only permissions', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, 'participant', undefined, false, false)
@@ -522,7 +522,7 @@ describe('useCan Hook', () => {
   describe('Fallback Scenarios', () => {
     it('falls back to cached permissions when API fails', async () => {
       mockIsPermitted.mockRejectedValue(new Error('API Error'));
-      mockIsPermittedCached.mockResolvedValue(true);
+      mockIsPermittedCached.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, mockPageId, true, false)
@@ -546,8 +546,8 @@ describe('useCan Hook', () => {
     });
 
     it('handles permission denied with fallback to false', async () => {
-      mockIsPermitted.mockResolvedValue(false);
-      mockIsPermittedCached.mockResolvedValue(false);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: false });
+      mockIsPermittedCached.mockResolvedValue({ ok: true, data: false });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, mockPageId, true, false)
@@ -599,7 +599,7 @@ describe('useCan Hook', () => {
 
   describe('Edge Cases', () => {
     it('handles empty userId', async () => {
-      mockIsPermitted.mockResolvedValue(false);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: false });
 
       const { result } = renderHook(() => 
         useCan('', mockScope, mockPermission, undefined, false, false)
@@ -613,7 +613,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles empty permission', async () => {
-      mockIsPermitted.mockResolvedValue(false);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: false });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, '', undefined, false, false)
@@ -754,7 +754,7 @@ describe('useCan Hook', () => {
 
   describe('Performance', () => {
     it('maintains stable references for same inputs', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result, rerender } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, undefined, false, false)
@@ -774,7 +774,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles rapid dependency changes efficiently', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result, rerender } = renderHook(
         ({ userId, scope, permission }) => useCan(userId, scope, permission, undefined, false, false),
@@ -819,7 +819,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles precomputedSuperAdmin=false correctly', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, undefined, false, false) // precomputedSuperAdmin = false
@@ -835,8 +835,8 @@ describe('useCan Hook', () => {
     });
 
     it('handles precomputedSuperAdmin=null (checking)', async () => {
-      mockIsSuperAdmin.mockResolvedValue(false);
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsSuperAdmin.mockResolvedValue({ ok: true, data: false });
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, undefined, false, null) // precomputedSuperAdmin = null
@@ -853,7 +853,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles page-level permission without organisationId', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const pageScope = {
         organisationId: undefined,
@@ -875,7 +875,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles pageName (not UUID) requiring appId', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const scopeWithoutAppId = {
         organisationId: 'org-123',
@@ -898,7 +898,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles UUID pageId not requiring appId', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const uuidPageId = '123e4567-e89b-12d3-a456-426614174000';
       const scopeWithoutAppId = {
@@ -922,7 +922,7 @@ describe('useCan Hook', () => {
 
     it('handles super admin check error gracefully', async () => {
       mockIsSuperAdmin.mockRejectedValue(new Error('Super admin check failed'));
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, undefined, false, null)
@@ -965,7 +965,7 @@ describe('useCan Hook', () => {
       }, { timeout: 4000 });
 
       // Provide organisation context
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
       rerender({ orgId: 'org-123' });
 
       await waitFor(() => {
@@ -1011,7 +1011,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles refetch with page-level permission', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, 'read:page.dashboard' as any, 'dashboard', false, false)
@@ -1030,7 +1030,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles useCache=false correctly', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, undefined, false, false) // useCache = false
@@ -1047,7 +1047,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles useCache=true correctly', async () => {
-      mockIsPermittedCached.mockResolvedValue(true);
+      mockIsPermittedCached.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, undefined, true, false) // useCache = true
@@ -1063,7 +1063,7 @@ describe('useCan Hook', () => {
     });
 
     it('handles appName parameter correctly', async () => {
-      mockIsPermitted.mockResolvedValue(true);
+      mockIsPermitted.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => 
         useCan(mockUserId, mockScope, mockPermission, undefined, false, false, 'PORTAL')
@@ -1097,7 +1097,7 @@ describe('useCan Hook', () => {
 
     it('handles refetch error gracefully', async () => {
       mockIsPermitted
-        .mockResolvedValueOnce(true)
+        .mockResolvedValueOnce({ ok: true, data: true })
         .mockRejectedValueOnce(new Error('Refetch error'));
 
       const { result } = renderHook(() => 

package/src/rbac/hooks/usePageAccessLogging.ts

@@ -0,0 +1,160 @@
+/**
+ * @file usePageAccessLogging Hook
+ * @package @jmruthers/pace-core
+ * @module RBAC/Hooks
+ * @since 2.0.0
+ *
+ * Handles permission-check completion, audit logging, strict-mode violations,
+ * debug logging, timeout warning, and super-admin access logging for PagePermissionGuard.
+ */
+
+import { useEffect, useRef } from 'react';
+import { getRBACLogger } from '../config';
+import type { Scope } from '../types';
+
+const logger = getRBACLogger();
+
+export interface UsePageAccessLoggingOptions {
+  setHasChecked: (value: boolean) => void;
+  hasChecked: boolean;
+  isLoading: boolean;
+  error: Error | null;
+  effectiveCan: boolean;
+  pageName: string;
+  operation: string;
+  onDenied?: (pageName: string, operation: string) => void;
+  auditLog: boolean;
+  userId: string | undefined;
+  effectiveScope: Scope | null;
+  isSuperAdmin: boolean | null;
+  strictMode: boolean;
+  shouldBypassScopeForSuperAdmin: boolean;
+  effectivePageId: string;
+  allowsOptionalContexts: boolean;
+  checkError: Error | null;
+  canError: Error | null;
+  scopeLoading: boolean;
+  canIsLoading: boolean;
+  hasValidUser: boolean;
+  stableScope: Scope | null;
+  appName: string;
+}
+
+/**
+ * Runs all side effects for page permission guard: completion callback,
+ * audit log, strict-mode violation log, debug log, timeout warning, super-admin log.
+ */
+export function usePageAccessLogging(options: UsePageAccessLoggingOptions): void {
+  const {
+    setHasChecked,
+    hasChecked,
+    isLoading,
+    error,
+    effectiveCan,
+    pageName,
+    operation,
+    onDenied,
+    auditLog: _auditLog,
+    userId,
+    effectiveScope,
+    isSuperAdmin,
+    strictMode,
+    shouldBypassScopeForSuperAdmin,
+    effectivePageId,
+    allowsOptionalContexts,
+    checkError,
+    canError,
+    scopeLoading,
+    canIsLoading,
+    hasValidUser,
+    stableScope,
+    appName
+  } = options;
+
+  // Permission check completion
+  useEffect(() => {
+    if (!isLoading && !error) {
+      setHasChecked(true);
+      if (!effectiveCan && onDenied) onDenied(pageName, operation);
+    } else if (error) {
+      setHasChecked(true);
+    }
+  }, [effectiveCan, isLoading, error, pageName, operation, onDenied, setHasChecked]);
+
+  // Strict mode violation
+  useEffect(() => {
+    if (strictMode && hasChecked && !isLoading && !effectiveCan && !shouldBypassScopeForSuperAdmin) {
+      logger.error('STRICT MODE VIOLATION: User attempted to access protected page without permission', {
+        pageName,
+        operation,
+        permission: `${operation}:page.${pageName}`,
+        pageId: effectivePageId,
+        userId,
+        scope: effectiveScope,
+        scopeValid: allowsOptionalContexts ? true : effectiveScope !== null,
+        checkError,
+        canError,
+        isSuperAdmin,
+        timestamp: new Date().toISOString()
+      });
+    }
+  }, [
+    strictMode,
+    hasChecked,
+    isLoading,
+    effectiveCan,
+    shouldBypassScopeForSuperAdmin,
+    pageName,
+    operation,
+    effectivePageId,
+    userId,
+    effectiveScope,
+    allowsOptionalContexts,
+    checkError,
+    canError,
+    isSuperAdmin
+  ]);
+
+
+  // Timeout warning
+  useEffect(() => {
+    if (isLoading && isSuperAdmin === null && hasValidUser) {
+      const timeout = setTimeout(() => {
+        logger.warn('Permission check taking longer than expected', {
+          pageName,
+          userId,
+          isSuperAdmin,
+          scopeLoading,
+          canIsLoading,
+          hasChecked,
+          stableScope,
+          effectiveScope,
+          appName
+        });
+      }, 5000);
+      return () => clearTimeout(timeout);
+    }
+  }, [
+    isLoading,
+    isSuperAdmin,
+    hasValidUser,
+    pageName,
+    userId,
+    scopeLoading,
+    canIsLoading,
+    hasChecked,
+    stableScope,
+    effectiveScope,
+    appName
+  ]);
+
+  // Super admin access log (once)
+  const hasLoggedSuperAdminRef = useRef(false);
+  useEffect(() => {
+    if (isSuperAdmin === true && hasValidUser && !hasLoggedSuperAdminRef.current && process.env.NODE_ENV === 'development') {
+      hasLoggedSuperAdminRef.current = true;
+      logger.debug('Super admin access granted - bypassing all checks', { pageName, userId, operation });
+    }
+    if (isSuperAdmin !== true) hasLoggedSuperAdminRef.current = false;
+  }, [isSuperAdmin, hasValidUser, pageName, userId, operation]);
+}

package/src/rbac/hooks/usePageGuardScope.ts

@@ -0,0 +1,117 @@
+/**
+ * @file usePageGuardScope Hook
+ * @package @jmruthers/pace-core
+ * @module RBAC/Hooks
+ * @since 2.0.0
+ *
+ * Resolves and stabilizes scope for page-level permission checks.
+ * Used by PagePermissionGuard to compute effectiveScope, stableScope,
+ * and scopeForPermissionCheck.
+ */
+
+import { useMemo, useRef } from 'react';
+import { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/database';
+import { useResolvedScope } from './useResolvedScope';
+import type { Scope } from '../types';
+import { scopeEqual } from '../utils/deep-equal';
+
+export interface UsePageGuardScopeOptions {
+  supabase: SupabaseClient<Database> | null;
+  selectedOrganisationId: string | null;
+  selectedEventId: string | null;
+  selectedEventOrganisationId: string | null;
+  scope: Scope | undefined;
+  contextAppId: string | undefined;
+  appName: string;
+  isSuperAdmin: boolean | null;
+}
+
+export interface UsePageGuardScopeReturn {
+  effectiveScope: Scope | null;
+  stableScope: Scope | null;
+  scopeForPermissionCheck: Scope | null;
+  scopeLoading: boolean;
+  scopeError: Error | null;
+  allowsOptionalContexts: boolean;
+}
+
+export function usePageGuardScope({
+  supabase,
+  selectedOrganisationId,
+  selectedEventId,
+  selectedEventOrganisationId,
+  scope,
+  contextAppId,
+  appName,
+  isSuperAdmin
+}: UsePageGuardScopeOptions): UsePageGuardScopeReturn {
+  const { resolvedScope: hookResolvedScope, isLoading: scopeLoading, error: scopeError } = useResolvedScope({
+    supabase,
+    selectedOrganisationId,
+    selectedEventId,
+    selectedEventOrganisationId
+  });
+
+  const allowsOptionalContexts = useMemo(() => appName === 'PORTAL' || appName === 'ADMIN', [appName]);
+
+  const effectiveScope: Scope | null = useMemo(
+    () =>
+      scope ||
+      (hookResolvedScope
+        ? {
+            ...hookResolvedScope,
+            appId: hookResolvedScope.appId || (allowsOptionalContexts ? contextAppId : undefined)
+          }
+        : allowsOptionalContexts && contextAppId
+          ? { organisationId: undefined, eventId: undefined, appId: contextAppId }
+          : selectedEventId
+            ? { organisationId: undefined, eventId: selectedEventId, appId: contextAppId || undefined }
+            : null),
+    [scope, hookResolvedScope, allowsOptionalContexts, contextAppId, selectedEventId]
+  );
+
+  const prevScopeRef = useRef<Scope | null>(null);
+  const stableScope = useMemo(() => {
+    if (allowsOptionalContexts && effectiveScope) {
+      const newScope: Scope = {
+        organisationId: effectiveScope.organisationId,
+        appId: effectiveScope.appId || contextAppId || undefined,
+        eventId: effectiveScope.eventId
+      };
+      if (scopeEqual(prevScopeRef.current, newScope)) return prevScopeRef.current!;
+      prevScopeRef.current = newScope;
+      return newScope;
+    }
+    const newScope: Scope =
+      effectiveScope && effectiveScope.organisationId
+        ? {
+            organisationId: effectiveScope.organisationId,
+            appId: effectiveScope.appId || contextAppId || undefined,
+            eventId: effectiveScope.eventId || undefined
+          }
+        : {
+            organisationId: effectiveScope?.organisationId || undefined,
+            appId: effectiveScope?.appId || contextAppId || undefined,
+            eventId: effectiveScope?.eventId || selectedEventId || undefined
+          };
+    if (scopeEqual(prevScopeRef.current, newScope)) return prevScopeRef.current!;
+    prevScopeRef.current = newScope;
+    return newScope;
+  }, [effectiveScope, contextAppId, selectedEventId, allowsOptionalContexts]);
+
+  const shouldBypassScopeForSuperAdmin = isSuperAdmin === true;
+  const scopeForPermissionCheck =
+    shouldBypassScopeForSuperAdmin && !stableScope?.organisationId
+      ? { organisationId: undefined, appId: contextAppId || undefined, eventId: selectedEventId || undefined }
+      : stableScope;
+
+  return {
+    effectiveScope,
+    stableScope,
+    scopeForPermissionCheck,
+    scopeLoading,
+    scopeError: scopeError ?? null,
+    allowsOptionalContexts
+  };
+}

package/src/rbac/hooks/usePagePermissionCheck.ts

@@ -0,0 +1,67 @@
+/**
+ * @file usePagePermissionCheck Hook
+ * @package @jmruthers/pace-core
+ * @module RBAC/Hooks
+ * @since 2.0.0
+ *
+ * Wraps useCan for page-level permission checks and derives effective can/loading.
+ * Used by PagePermissionGuard to avoid duplicating useCan + override logic.
+ */
+
+import { useCan } from './usePermissions';
+import type { Permission, Scope } from '../types';
+
+export interface UsePagePermissionCheckOptions {
+  userId: string;
+  scopeForPermissionCheck: Scope | null;
+  shouldSkipPermissionCheck: boolean;
+  contextAppId: string | undefined;
+  permission: Permission;
+  effectivePageId: string;
+  isSuperAdmin: boolean | null;
+  appName: string;
+}
+
+export interface UsePagePermissionCheckReturn {
+  can: boolean;
+  effectiveCan: boolean;
+  canIsLoading: boolean;
+  canError: Error | null;
+}
+
+const dummyScope: Scope = { organisationId: undefined, appId: undefined, eventId: undefined };
+
+/**
+ * Runs useCan with the appropriate scope (dummy when skipping) and returns
+ * can, effectiveCan (true when skipping), canIsLoading, canError.
+ */
+export function usePagePermissionCheck({
+  userId,
+  scopeForPermissionCheck,
+  shouldSkipPermissionCheck,
+  contextAppId,
+  permission,
+  effectivePageId,
+  isSuperAdmin,
+  appName
+}: UsePagePermissionCheckOptions): UsePagePermissionCheckReturn {
+  const scope =
+    shouldSkipPermissionCheck
+      ? { ...dummyScope, appId: contextAppId }
+      : (scopeForPermissionCheck ?? dummyScope);
+
+  const { can, isLoading: canIsLoading, error: canError } = useCan(
+    userId,
+    scope,
+    permission,
+    effectivePageId,
+    true,
+    isSuperAdmin,
+    appName
+  );
+
+  const effectiveCan = shouldSkipPermissionCheck ? true : can;
+  const effectiveIsLoading = shouldSkipPermissionCheck ? false : canIsLoading;
+
+  return { can, effectiveCan, canIsLoading: effectiveIsLoading, canError: canError ?? null };
+}