@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/rbac/errors.ts

@@ -34,73 +34,89 @@ function normalize(value: unknown): string {
   return String(value).toLowerCase();
 }
 
-export function categorizeError(error: unknown): RBACErrorCategory {
+function categorizeByErrorClass(error: unknown): RBACErrorCategory | null {
   if (error instanceof PermissionDeniedError) {
     return RBACErrorCategory.AUTHORIZATION;
   }
-
   if (error instanceof OrganisationContextRequiredError || error instanceof InvalidScopeError) {
     return RBACErrorCategory.VALIDATION;
   }
-
   if (error instanceof MissingUserContextError) {
     return RBACErrorCategory.AUTHENTICATION;
   }
+  return null;
+}
+
+function categorizeByRBACErrorCode(error: unknown): RBACErrorCategory | null {
+  if (!(error instanceof RBACError)) {
+    return null;
+  }
+  switch (error.code) {
+    case 'PERMISSION_DENIED':
+      return RBACErrorCategory.AUTHORIZATION;
+    case 'ORGANISATION_CONTEXT_REQUIRED':
+    case 'INVALID_SCOPE':
+      return RBACErrorCategory.VALIDATION;
+    case 'MISSING_USER_CONTEXT':
+      return RBACErrorCategory.AUTHENTICATION;
+    default:
+      return null;
+  }
+}
+
+function categorizeByHttpStatus(error: unknown): RBACErrorCategory | null {
+  if (!error || typeof error !== 'object') {
+    return null;
+  }
+  const status = (error as { status?: number }).status;
+  if (typeof status !== 'number') {
+    return null;
+  }
+  if (RATE_LIMIT_STATUS_CODES.has(status)) {
+    return RBACErrorCategory.RATE_LIMIT;
+  }
+  if (AUTH_STATUS_CODES.has(status)) {
+    return RBACErrorCategory.AUTHENTICATION;
+  }
+  if (AUTHZ_STATUS_CODES.has(status)) {
+    return RBACErrorCategory.AUTHORIZATION;
+  }
+  if (status >= 500) {
+    return RBACErrorCategory.DATABASE;
+  }
+  return null;
+}
 
-  if (error instanceof RBACError) {
-    switch (error.code) {
-      case 'PERMISSION_DENIED':
-        return RBACErrorCategory.AUTHORIZATION;
-      case 'ORGANISATION_CONTEXT_REQUIRED':
-      case 'INVALID_SCOPE':
-        return RBACErrorCategory.VALIDATION;
-      case 'MISSING_USER_CONTEXT':
-        return RBACErrorCategory.AUTHENTICATION;
-      default:
-        break;
-    }
-  }
-
-  if (error && typeof error === 'object') {
-    const status = (error as { status?: number }).status;
-    if (typeof status === 'number') {
-      if (RATE_LIMIT_STATUS_CODES.has(status)) {
-        return RBACErrorCategory.RATE_LIMIT;
-      }
-      if (AUTH_STATUS_CODES.has(status)) {
-        return RBACErrorCategory.AUTHENTICATION;
-      }
-      if (AUTHZ_STATUS_CODES.has(status)) {
-        return RBACErrorCategory.AUTHORIZATION;
-      }
-      if (status >= 500) {
-        return RBACErrorCategory.DATABASE;
-      }
-    }
-
-    const codeValue = normalize((error as { code?: string }).code);
-    if (codeValue) {
-      if (codeValue.includes('network')) {
-        return RBACErrorCategory.NETWORK;
-      }
-      if (codeValue.includes('postgres') || codeValue.includes('database') || codeValue.includes('db')) {
-        return RBACErrorCategory.DATABASE;
-      }
-      if (codeValue.includes('rate')) {
-        return RBACErrorCategory.RATE_LIMIT;
-      }
-      if (codeValue.includes('auth')) {
-        return RBACErrorCategory.AUTHENTICATION;
-      }
-      if (codeValue.includes('permission')) {
-        return RBACErrorCategory.AUTHORIZATION;
-      }
-      if (codeValue.includes('scope') || codeValue.includes('invalid')) {
-        return RBACErrorCategory.VALIDATION;
-      }
-    }
+function categorizeByCodeString(error: unknown): RBACErrorCategory | null {
+  if (!error || typeof error !== 'object') {
+    return null;
   }
+  const codeValue = normalize((error as { code?: string }).code);
+  if (!codeValue) {
+    return null;
+  }
+  if (codeValue.includes('network')) {
+    return RBACErrorCategory.NETWORK;
+  }
+  if (codeValue.includes('postgres') || codeValue.includes('database') || codeValue.includes('db')) {
+    return RBACErrorCategory.DATABASE;
+  }
+  if (codeValue.includes('rate')) {
+    return RBACErrorCategory.RATE_LIMIT;
+  }
+  if (codeValue.includes('auth')) {
+    return RBACErrorCategory.AUTHENTICATION;
+  }
+  if (codeValue.includes('permission')) {
+    return RBACErrorCategory.AUTHORIZATION;
+  }
+  if (codeValue.includes('scope') || codeValue.includes('invalid')) {
+    return RBACErrorCategory.VALIDATION;
+  }
+  return null;
+}
 
+function categorizeByMessage(error: unknown): RBACErrorCategory | null {
   const message = normalize(error);
   if (message.includes('timeout') || message.includes('network') || message.includes('fetch')) {
     return RBACErrorCategory.NETWORK;
@@ -120,6 +136,24 @@ export function categorizeError(error: unknown): RBACErrorCategory {
   if (message.includes('invalid') || message.includes('scope') || message.includes('validation')) {
     return RBACErrorCategory.VALIDATION;
   }
+  return null;
+}
+
+export function categorizeError(error: unknown): RBACErrorCategory {
+  const byClass = categorizeByErrorClass(error);
+  if (byClass !== null) return byClass;
+
+  const byCode = categorizeByRBACErrorCode(error);
+  if (byCode !== null) return byCode;
+
+  const byStatus = categorizeByHttpStatus(error);
+  if (byStatus !== null) return byStatus;
+
+  const byCodeString = categorizeByCodeString(error);
+  if (byCodeString !== null) return byCodeString;
+
+  const byMessage = categorizeByMessage(error);
+  if (byMessage !== null) return byMessage;
 
   return RBACErrorCategory.UNKNOWN;
 }

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

@@ -0,0 +1,77 @@
+import type { ApiResult } from '../../../types/api-result';
+import type { Permission, Scope, UUID } from '../../types';
+import { isPermitted, isPermittedCached } from '../../api';
+
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function isEmptyString(s: string | undefined | null): boolean {
+  return s === null || s === undefined || (typeof s === 'string' && s.trim() === '');
+}
+
+/**
+ * Pure async helper: validates scope/context and runs isPermitted or isPermittedCached.
+ * Returns ok(false) when context is invalid or "wait for context" (caller keeps loading).
+ */
+export async function runPermissionCheck(params: {
+  userId: UUID;
+  scope: Scope | null;
+  permission: Permission;
+  pageId?: UUID;
+  useCache: boolean;
+  appName?: string;
+  isSuperAdmin: boolean | null;
+}): Promise<ApiResult<boolean>> {
+  const { userId, scope, permission, pageId, useCache, appName, isSuperAdmin } = params;
+
+  if (!userId) {
+    return { ok: true, data: false };
+  }
+
+  if (isSuperAdmin === true) {
+    return { ok: true, data: true };
+  }
+
+  if (isSuperAdmin === null) {
+    return { ok: true, data: false };
+  }
+
+  if (!scope || typeof scope !== 'object') {
+    return { ok: true, data: false };
+  }
+
+  const organisationId = scope.organisationId;
+  const eventId = scope.eventId;
+  const appId = scope.appId;
+
+  const isPagePermission = permission.includes(':page.') || !!pageId;
+  const requiresOrgId = !isPagePermission;
+
+  if (requiresOrgId && isEmptyString(organisationId)) {
+    return { ok: true, data: false };
+  }
+
+  const isPageName =
+    pageId &&
+    typeof pageId === 'string' &&
+    !UUID_REGEX.test(pageId);
+  const needsAppIdForPageName = isPagePermission && !!isPageName;
+
+  if (needsAppIdForPageName && isEmptyString(appId)) {
+    return { ok: true, data: false };
+  }
+
+  const validScope: Scope = {
+    ...(organisationId ? { organisationId } : {}),
+    ...(eventId ? { eventId } : {}),
+    ...(appId ? { appId } : {}),
+  };
+
+  if (useCache) {
+    return isPermittedCached({ userId, scope: validScope, permission, pageId }, appName);
+  }
+  return isPermitted(
+    { userId, scope: validScope, permission, pageId },
+    appName,
+    isSuperAdmin === false ? false : null
+  );
+}

package/src/rbac/hooks/permissions/{__tests__/useAccessLevel.test.ts → useAccessLevel.test.ts}

@@ -15,12 +15,12 @@
 
 import { renderHook, waitFor } from '@testing-library/react';
 import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { useAccessLevel } from '../useAccessLevel';
-import { OrganisationContextRequiredError } from '../../../types';
+import { useAccessLevel } from './useAccessLevel';
+import { OrganisationContextRequiredError } from '../../types';
 
 // Mock the RBAC API - use async factory to support dynamic imports
-vi.mock('../../../api', async () => {
-  const actual = await vi.importActual('../../../api');
+vi.mock('../../api', async () => {
+  const actual = await vi.importActual('../../api');
   return {
     ...actual,
     getAccessLevel: vi.fn(),
@@ -29,14 +29,14 @@ vi.mock('../../../api', async () => {
 });
 
 // Mock useAppConfig
-vi.mock('../../../../hooks/useAppConfig', () => ({
+vi.mock('../../../hooks/useAppConfig', () => ({
   useAppConfig: vi.fn(() => ({
     appName: 'test-app',
   })),
 }));
 
-import { getAccessLevel, isSuperAdmin } from '../../../api';
-import { useAppConfig } from '../../../../hooks/useAppConfig';
+import { getAccessLevel, isSuperAdmin } from '../../api';
+import { useAppConfig } from '../../../hooks/useAppConfig';
 
 const mockUserId = 'user-123';
 const mockScope = {
@@ -52,8 +52,8 @@ describe('useAccessLevel Hook', () => {
 
   beforeEach(() => {
     vi.clearAllMocks();
-    mockGetAccessLevel.mockResolvedValue('viewer');
-    mockIsSuperAdmin.mockResolvedValue(false);
+    mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
+    mockIsSuperAdmin.mockResolvedValue({ ok: true, data: false });
     mockUseAppConfig.mockReturnValue({
       appName: 'test-app',
       isLoading: false,
@@ -66,7 +66,7 @@ describe('useAccessLevel Hook', () => {
 
   describe('Access Level Fetching', () => {
     it('fetches access level for valid user', async () => {
-      mockGetAccessLevel.mockResolvedValue('admin');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'admin' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 
@@ -108,7 +108,7 @@ describe('useAccessLevel Hook', () => {
 
   describe('Super Admin Handling', () => {
     it('returns super access level for super admin users', async () => {
-      mockIsSuperAdmin.mockResolvedValue(true);
+      mockIsSuperAdmin.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 
@@ -123,7 +123,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('bypasses context requirements for super admins', async () => {
-      mockIsSuperAdmin.mockResolvedValue(true);
+      mockIsSuperAdmin.mockResolvedValue({ ok: true, data: true });
       const emptyScope = {};
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, emptyScope));
@@ -158,7 +158,7 @@ describe('useAccessLevel Hook', () => {
         appName: 'PORTAL',
         isLoading: false,
       });
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
       const emptyScope = {};
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, emptyScope));
@@ -174,7 +174,7 @@ describe('useAccessLevel Hook', () => {
         appName: 'ADMIN',
         isLoading: false,
       });
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
       const emptyScope = {};
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, emptyScope));
@@ -186,7 +186,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('accepts scope with only organisationId', async () => {
-      mockGetAccessLevel.mockResolvedValue('admin');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'admin' });
       const orgOnlyScope = { organisationId: 'org-123' };
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, orgOnlyScope));
@@ -198,7 +198,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('accepts scope with only eventId', async () => {
-      mockGetAccessLevel.mockResolvedValue('participant');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'participant' });
       const eventOnlyScope = { eventId: 'event-123' };
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, eventOnlyScope));
@@ -213,8 +213,8 @@ describe('useAccessLevel Hook', () => {
   describe('Refetch Functionality', () => {
     it('refetches access level when refetch is called', async () => {
       mockGetAccessLevel
-        .mockResolvedValueOnce('viewer')
-        .mockResolvedValueOnce('admin');
+        .mockResolvedValueOnce({ ok: true, data: 'viewer' })
+        .mockResolvedValueOnce({ ok: true, data: 'admin' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 
@@ -233,7 +233,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('refetches when scope changes', async () => {
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
 
       const { result, rerender } = renderHook(
         ({ userId, scope }) => useAccessLevel(userId, scope),
@@ -255,7 +255,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('refetches when userId changes', async () => {
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
 
       const { result, rerender } = renderHook(
         ({ userId, scope }) => useAccessLevel(userId, scope),
@@ -278,7 +278,7 @@ describe('useAccessLevel Hook', () => {
 
   describe('Access Level Values', () => {
     it('handles viewer access level', async () => {
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 
@@ -288,7 +288,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles participant access level', async () => {
-      mockGetAccessLevel.mockResolvedValue('participant');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'participant' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 
@@ -298,7 +298,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles planner access level', async () => {
-      mockGetAccessLevel.mockResolvedValue('planner');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'planner' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 
@@ -308,7 +308,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles admin access level', async () => {
-      mockGetAccessLevel.mockResolvedValue('admin');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'admin' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 
@@ -318,7 +318,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles super access level', async () => {
-      mockGetAccessLevel.mockResolvedValue('super');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'super' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 
@@ -390,7 +390,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles scope with undefined values', async () => {
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
       const scopeWithUndefined = {
         organisationId: undefined,
         eventId: undefined,
@@ -405,7 +405,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles rapid refetch calls', async () => {
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 
@@ -427,7 +427,7 @@ describe('useAccessLevel Hook', () => {
 
   describe('Performance', () => {
     it('maintains stable references for same inputs', async () => {
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
 
       const { result, rerender } = renderHook(
         ({ userId, scope }) => useAccessLevel(userId, scope),
@@ -459,7 +459,7 @@ describe('useAccessLevel Hook', () => {
         appName: 'PORTAL',
         isLoading: false,
       });
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, {
         organisationId: undefined,
@@ -480,7 +480,7 @@ describe('useAccessLevel Hook', () => {
         appName: 'ADMIN',
         isLoading: false,
       });
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, {
         organisationId: undefined,
@@ -512,7 +512,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles access level fetch error gracefully', async () => {
-      mockIsSuperAdmin.mockResolvedValue(false);
+      mockIsSuperAdmin.mockResolvedValue({ ok: true, data: false });
       mockGetAccessLevel.mockRejectedValue(new Error('Access level fetch failed'));
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
@@ -525,8 +525,8 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles rapid scope changes without crashing', async () => {
-      mockIsSuperAdmin.mockResolvedValue(false);
-      mockGetAccessLevel.mockResolvedValue('viewer');
+      mockIsSuperAdmin.mockResolvedValue({ ok: true, data: false });
+      mockGetAccessLevel.mockResolvedValue({ ok: true, data: 'viewer' });
 
       const { result, rerender } = renderHook(
         ({ scope }) => useAccessLevel(mockUserId, scope),
@@ -549,10 +549,10 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles refetch correctly', async () => {
-      mockIsSuperAdmin.mockResolvedValue(false);
+      mockIsSuperAdmin.mockResolvedValue({ ok: true, data: false });
       mockGetAccessLevel
-        .mockResolvedValueOnce('viewer')
-        .mockResolvedValueOnce('admin');
+        .mockResolvedValueOnce({ ok: true, data: 'viewer' })
+        .mockResolvedValueOnce({ ok: true, data: 'admin' });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 
@@ -570,9 +570,9 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles refetch error gracefully', async () => {
-      mockIsSuperAdmin.mockResolvedValue(false);
+      mockIsSuperAdmin.mockResolvedValue({ ok: true, data: false });
       mockGetAccessLevel
-        .mockResolvedValueOnce('viewer')
+        .mockResolvedValueOnce({ ok: true, data: 'viewer' })
         .mockRejectedValueOnce(new Error('Refetch error'));
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
@@ -592,7 +592,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles non-Error exceptions in fetchAccessLevel', async () => {
-      mockIsSuperAdmin.mockResolvedValue(false);
+      mockIsSuperAdmin.mockResolvedValue({ ok: true, data: false });
       mockGetAccessLevel.mockRejectedValue('String error');
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
@@ -605,7 +605,7 @@ describe('useAccessLevel Hook', () => {
     });
 
     it('handles super admin returning super access level', async () => {
-      mockIsSuperAdmin.mockResolvedValue(true);
+      mockIsSuperAdmin.mockResolvedValue({ ok: true, data: true });
 
       const { result } = renderHook(() => useAccessLevel(mockUserId, mockScope));
 

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

@@ -55,11 +55,15 @@ export function useAccessLevel(userId: UUID, scope: Scope): {
       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) {
+      const superResult = await checkSuperAdmin(userId);
+      if (!superResult.ok) {
+        setError(new Error(superResult.error.message));
+        setAccessLevel('viewer');
+        setIsLoading(false);
+        return;
+      }
+      if (superResult.data) {
         setAccessLevel('super');
         setIsLoading(false);
         return;
@@ -75,8 +79,14 @@ export function useAccessLevel(userId: UUID, scope: Scope): {
         return;
       }
 
-      const level = await getAccessLevel({ userId, scope }, appName);
-      setAccessLevel(level);
+      const result = await getAccessLevel({ userId, scope }, appName);
+      if (!result.ok) {
+        setError(new Error(result.error.message));
+        setAccessLevel('viewer');
+        setIsLoading(false);
+        return;
+      }
+      setAccessLevel(result.data);
     } catch (err) {
       const error = err instanceof Error ? err : new Error('Failed to fetch access level');
       setError(error);