@jmruthers/pace-core 0.6.9 → 0.6.11

package/src/rbac/api.ts

@@ -24,15 +24,27 @@ import {
 import { createRBACEngine, RBACEngine } from './engine';
 import { createAuditManager, setGlobalAuditManager } from './audit';
 import { rbacCache, RBACCache, CACHE_PATTERNS } from './cache';
-import { createRBACConfig, RBACConfig, getRBACLogger } from './config';
+import { createRBACConfig, RBACConfig } from './config';
 import { SecurityContext } from './security';
 import { createLogger } from '../utils/core/logger';
 import { enablePerformanceMonitoring } from './performance';
 import { getOrCreateRequest } from './request-deduplication';
 import { ContextValidator } from './utils/contextValidator';
+import { ok, err, type ApiResult, type ApiError } from '../types/api-result';
 
 const log = createLogger('RBACAPI');
 
+function toApiError(error: unknown): ApiError {
+  if (error instanceof RBACNotInitializedError) {
+    return { code: 'RBAC_NOT_INITIALIZED', message: error.message };
+  }
+  if (error instanceof OrganisationContextRequiredError) {
+    return { code: 'ORGANISATION_CONTEXT_REQUIRED', message: error.message };
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return { code: 'RBAC_ERROR', message };
+}
+
 // Global engine instance
 let globalEngine: RBACEngine | null = null;
 
@@ -43,7 +55,6 @@ let globalEngine: RBACEngine | null = null;
  * @param config - Optional configuration
  */
 export function setupRBAC(supabase: SupabaseClient<Database>, config?: Partial<RBACConfig>): void {
-  const logger = getRBACLogger();
   
   // Create full config
   const isDevelopment = import.meta.env.MODE === 'development';
@@ -135,14 +146,14 @@ export async function getAccessLevel(
     scope: Scope;
   },
   appName?: string
-): Promise<AccessLevel> {
+): Promise<ApiResult<AccessLevel>> {
   try {
     const engine = getEngine();
     
     // Check super admin status first - super admins bypass context requirements
     const isSuperAdminUser = await engine['checkSuperAdmin'](input.userId);
     if (isSuperAdminUser) {
-      return 'super';
+      return ok('super');
     }
     
     // For functions without pageId, default to organisation scope validation
@@ -159,13 +170,13 @@ export async function getAccessLevel(
     }
     
     // Use resolved scope
-    return engine.getAccessLevel({
+    const accessLevel = await engine.getAccessLevel({
       ...input,
       scope: validation.resolvedScope
     });
+    return ok(accessLevel);
   } catch (error) {
-    // Re-throw the error - this is an API function that should propagate errors
-    throw error;
+    return err(toApiError(error));
   }
 }
 
@@ -195,7 +206,7 @@ export async function getPermissionMap(
     scope: Scope;
   },
   appName?: string
-): Promise<PermissionMap> {
+): Promise<ApiResult<PermissionMap>> {
   try {
     const engine = getEngine();
     
@@ -213,26 +224,26 @@ export async function getPermissionMap(
     }
     
     // Use resolved scope
-    return engine.getPermissionMap({
+    const permissionMap = await engine.getPermissionMap({
       ...input,
       scope: validation.resolvedScope
     });
+    return ok(permissionMap);
   } catch (error) {
-    // Re-throw the error - this is an API function that should propagate errors
-    throw error;
+    return err(toApiError(error));
   }
 }
 
 export async function resolveAppContext(input: {
   userId: UUID;
   appName: string;
-}): Promise<RBACAppContext | null> {
+}): Promise<ApiResult<RBACAppContext | null>> {
   try {
     const engine = getEngine();
-    return await engine.resolveAppContext(input);
+    const context = await engine.resolveAppContext(input);
+    return ok(context);
   } catch (error) {
-    // Re-throw the error - this is an API function that should propagate errors
-    throw error;
+    return err(toApiError(error));
   }
 }
 
@@ -242,26 +253,31 @@ export async function getRoleContext(
     scope: Scope;
   },
   appName?: string
-): Promise<RBACRoleContext> {
-  const engine = getEngine();
-  
-  // For functions without pageId, default to organisation scope validation
-  const validation = await ContextValidator.resolveScopeForPage(
-    input.scope,
-    'organisation', // Default to organisation scope when no page context
-    appName,
-    engine['supabase']
-  );
-  
-  if (!validation.isValid || !validation.resolvedScope) {
-    throw validation.error || new OrganisationContextRequiredError();
+): Promise<ApiResult<RBACRoleContext>> {
+  try {
+    const engine = getEngine();
+    
+    // For functions without pageId, default to organisation scope validation
+    const validation = await ContextValidator.resolveScopeForPage(
+      input.scope,
+      'organisation', // Default to organisation scope when no page context
+      appName,
+      engine['supabase']
+    );
+    
+    if (!validation.isValid || !validation.resolvedScope) {
+      throw validation.error || new OrganisationContextRequiredError();
+    }
+    
+    // Use resolved scope
+    const roleContext = await engine.getRoleContext({
+      ...input,
+      scope: validation.resolvedScope
+    });
+    return ok(roleContext);
+  } catch (error) {
+    return err(toApiError(error));
   }
-  
-  // Use resolved scope
-  return engine.getRoleContext({
-    ...input,
-    scope: validation.resolvedScope
-  });
 }
 
 /**
@@ -292,154 +308,148 @@ export async function isPermitted(
    * @default null
    */
   precomputedSuperAdmin: boolean | null = null
-): Promise<boolean> {
-  const engine = getEngine();
-  
-  // Check super admin status first - super admins bypass context requirements
-  // Super admins have access to all permissions regardless of organisation context
-  // PERFORMANCE: Use precomputed value if provided to avoid duplicate checks
-  if (precomputedSuperAdmin === true) {
-    return true;
-  }
-  
-  // If null, check super admin status
-  if (precomputedSuperAdmin === null) {
-    const isSuperAdminUser = await engine['checkSuperAdmin'](input.userId);
-    if (isSuperAdminUser) {
-      return true;
+): Promise<ApiResult<boolean>> {
+  try {
+    const engine = getEngine();
+    
+    // Check super admin status first - super admins bypass context requirements
+    // Super admins have access to all permissions regardless of organisation context
+    // PERFORMANCE: Use precomputed value if provided to avoid duplicate checks
+    if (precomputedSuperAdmin === true) {
+      return ok(true);
     }
-  }
-  // If precomputedSuperAdmin === false, skip check and proceed with permission check
-  
-  // Get app name if not provided (for PORTAL/ADMIN special case)
-  let resolvedAppName = appName;
-  if (!resolvedAppName && input.scope.appId) {
-    try {
-      const { data } = await engine['supabase']
-        .from('rbac_apps')
-        .select('name')
-        .eq('id', input.scope.appId)
-        .eq('is_active', true)
-        .single() as { data: { name: string } | null };
-      if (data) {
-        resolvedAppName = data.name;
+    
+    // If null, check super admin status
+    if (precomputedSuperAdmin === null) {
+      const isSuperAdminUser = await engine['checkSuperAdmin'](input.userId);
+      if (isSuperAdminUser) {
+        return ok(true);
       }
-    } catch (err) {
-      // Ignore errors - appName is optional
     }
-  }
-  
-  // Get page scope type (required for all permission checks)
-  // All pages must have scope_type set - this is the single source of truth
-  let pageScopeType: 'event' | 'organisation' | 'both';
-  if (input.pageId) {
-    try {
-      const scopeType = await getPageScopeType(
+    // If precomputedSuperAdmin === false, skip check and proceed with permission check
+    
+    // Get app name if not provided (for PORTAL/ADMIN special case)
+    let resolvedAppName = appName;
+    if (!resolvedAppName && input.scope.appId) {
+      try {
+        const { data } = await engine['supabase']
+          .from('rbac_apps')
+          .select('name')
+          .eq('id', input.scope.appId)
+          .eq('is_active', true)
+          .single() as { data: { name: string } | null };
+        if (data) {
+          resolvedAppName = data.name;
+        }
+      } catch (_err) {
+        // Ignore errors - appName is optional
+      }
+    }
+    
+    // Get page scope type (required for all permission checks)
+    // All pages must have scope_type set - this is the single source of truth
+    let pageScopeType: 'event' | 'organisation' | 'both';
+    if (input.pageId) {
+      const scopeResult = await getPageScopeType(
         input.pageId,
         input.scope.appId,
         resolvedAppName
       );
-      if (!scopeType) {
-        throw new Error(`Page ${input.pageId} does not have scope_type set`);
+      if (!scopeResult.ok) {
+        log.error('Failed to get page scope type:', scopeResult.error);
+        return err(scopeResult.error);
+      }
+      if (!scopeResult.data) {
+        return err({ code: 'PAGE_SCOPE_TYPE_MISSING', message: `Page ${input.pageId} does not have scope_type set` });
       }
-      pageScopeType = scopeType;
-    } catch (err) {
-      log.error('Failed to get page scope type:', err);
-      throw new Error(`Failed to determine page scope type: ${err instanceof Error ? err.message : String(err)}`);
+      pageScopeType = scopeResult.data;
+    } else {
+      // No pageId provided - default to organisation scope
+      // This should rarely happen, but provides a safe fallback
+      pageScopeType = 'organisation';
     }
-  } else {
-    // No pageId provided - default to organisation scope
-    // This should rarely happen, but provides a safe fallback
-    pageScopeType = 'organisation';
-  }
-  
-  // Validate context using page-level scope (single source of truth)
-  const validation = await ContextValidator.resolveScopeForPage(
-    input.scope,
-    pageScopeType,
-    resolvedAppName,
-    engine['supabase']
-  );
-  
-  if (!validation.isValid || !validation.resolvedScope) {
-    throw validation.error || new OrganisationContextRequiredError();
-  }
-  
-  // Use resolved scope for permission check
-  const validatedScope = validation.resolvedScope;
-  
-  // Handle 'both' scope pages - check both scopes and return union
-  if (pageScopeType === 'both' && input.pageId) {
-    // Check permission with event scope
-    const eventScope: Scope = {
-      organisationId: validatedScope.organisationId, // Org derived from event
-      eventId: validatedScope.eventId,
-      appId: validatedScope.appId
-    };
-    
-    // Check permission with organisation scope (if org is available separately)
-    // For 'both' pages, we check the permission in both contexts and return the union
-    // Higher permission wins (true > false, admin > user, etc.)
     
-    const eventSecurityContext: SecurityContext = {
-      userId: input.userId,
-      organisationId: eventScope.organisationId || null,
-      timestamp: new Date(),
-    };
+    // Validate context using page-level scope (single source of truth)
+    const validation = await ContextValidator.resolveScopeForPage(
+      input.scope,
+      pageScopeType,
+      resolvedAppName,
+      engine['supabase']
+    );
     
-    const eventInput: PermissionCheck = {
-      ...input,
-      scope: eventScope
-    };
+    if (!validation.isValid || !validation.resolvedScope) {
+      throw validation.error || new OrganisationContextRequiredError();
+    }
     
-    const hasEventPermission = await engine.isPermitted(eventInput, eventSecurityContext);
+    // Use resolved scope for permission check
+    const validatedScope = validation.resolvedScope;
     
-    // Also check with organisation scope if we have a separate org context
-    // (This handles cases where user has org permissions separate from event)
-    if (validatedScope.organisationId && validatedScope.eventId) {
-      const orgScope: Scope = {
-        organisationId: validatedScope.organisationId,
-        eventId: undefined, // Clear event for org-only check
+    // Handle 'both' scope pages - check both scopes and return union
+    if (pageScopeType === 'both' && input.pageId) {
+      // Check permission with event scope
+      const eventScope: Scope = {
+        organisationId: validatedScope.organisationId, // Org derived from event
+        eventId: validatedScope.eventId,
         appId: validatedScope.appId
       };
       
-      const orgSecurityContext: SecurityContext = {
+      const eventSecurityContext: SecurityContext = {
         userId: input.userId,
-        organisationId: orgScope.organisationId || null,
+        organisationId: eventScope.organisationId || null,
         timestamp: new Date(),
       };
       
-      const orgInput: PermissionCheck = {
+      const eventInput: PermissionCheck = {
         ...input,
-        scope: orgScope
+        scope: eventScope
       };
       
-      const hasOrgPermission = await engine.isPermitted(orgInput, orgSecurityContext);
+      const hasEventPermission = await engine.isPermitted(eventInput, eventSecurityContext);
       
-      // Return union (true if either scope grants permission)
-      // For access levels, the database function handles the "higher wins" logic
-      return hasEventPermission || hasOrgPermission;
+      // Also check with organisation scope if we have a separate org context
+      if (validatedScope.organisationId && validatedScope.eventId) {
+        const orgScope: Scope = {
+          organisationId: validatedScope.organisationId,
+          eventId: undefined, // Clear event for org-only check
+          appId: validatedScope.appId
+        };
+        
+        const orgSecurityContext: SecurityContext = {
+          userId: input.userId,
+          organisationId: orgScope.organisationId || null,
+          timestamp: new Date(),
+        };
+        
+        const orgInput: PermissionCheck = {
+          ...input,
+          scope: orgScope
+        };
+        
+        const hasOrgPermission = await engine.isPermitted(orgInput, orgSecurityContext);
+        
+        return ok(hasEventPermission || hasOrgPermission);
+      }
+      
+      return ok(hasEventPermission);
     }
     
-    // If only event scope available, return event permission
-    return hasEventPermission;
+    // Standard permission check for single-scope pages
+    const securityContext: SecurityContext = {
+      userId: input.userId,
+      organisationId: validatedScope.organisationId || null,
+      timestamp: new Date(),
+    };
+    
+    const validatedInput: PermissionCheck = {
+      ...input,
+      scope: validatedScope
+    };
+    
+    const permitted = await engine.isPermitted(validatedInput, securityContext);
+    return ok(permitted);
+  } catch (error) {
+    return err(toApiError(error));
   }
-  
-  // Standard permission check for single-scope pages
-  const securityContext: SecurityContext = {
-    userId: input.userId,
-    organisationId: validatedScope.organisationId || null,
-    timestamp: new Date(),
-    // Optional fields can be omitted
-  };
-  
-  // Create new input with validated scope
-  const validatedInput: PermissionCheck = {
-    ...input,
-    scope: validatedScope
-  };
-  
-  return engine.isPermitted(validatedInput, securityContext);
 }
 
 /**
@@ -455,7 +465,7 @@ export async function isPermitted(
 export async function isPermittedCached(
   input: PermissionCheck,
   appName?: string
-): Promise<boolean> {
+): Promise<ApiResult<boolean>> {
   const { userId, scope, permission, pageId } = input;
   
   // Check cache first (checks both short-term and session cache)
@@ -470,23 +480,20 @@ export async function isPermittedCached(
   
   const cached = rbacCache.get<boolean>(cacheKey, true);
   if (cached !== null) {
-    return cached;
+    return ok(cached);
   }
 
   // Use request deduplication - if same request is in-flight, share the promise
   return getOrCreateRequest(input, async (checkInput) => {
-    // Check permission with context validation
-    // Note: We can't pass precomputedSuperAdmin here because getOrCreateRequest doesn't support it
-    // The super admin check in isPermitted will be cached, so it's not a huge performance hit
     const result = await isPermitted(checkInput, appName, null);
-    
+    if (!result.ok) {
+      return result;
+    }
     // Determine if this is a page-level check (has pageId or permission contains 'page.')
     const isPageLevelCheck = !!pageId || permission.includes('page.');
-    
     // Cache result - use session cache for page-level checks
-    rbacCache.set(cacheKey, result, undefined, isPageLevelCheck);
-    
-    return result;
+    rbacCache.set(cacheKey, result.data, undefined, isPageLevelCheck);
+    return ok(result.data);
   });
 }
 
@@ -501,21 +508,23 @@ export async function hasAnyPermission(input: {
   scope: Scope;
   permissions: Permission[];
   pageId?: UUID;
-}): Promise<boolean> {
+}): Promise<ApiResult<boolean>> {
   const { permissions, ...baseInput } = input;
   
   for (const permission of permissions) {
-    const hasPermission = await isPermitted({
+    const result = await isPermitted({
       ...baseInput,
       permission,
     });
-    
-    if (hasPermission) {
-      return true;
+    if (!result.ok) {
+      return result;
+    }
+    if (result.data) {
+      return ok(true);
     }
   }
   
-  return false;
+  return ok(false);
 }
 
 /**
@@ -529,21 +538,23 @@ export async function hasAllPermissions(input: {
   scope: Scope;
   permissions: Permission[];
   pageId?: UUID;
-}): Promise<boolean> {
+}): Promise<ApiResult<boolean>> {
   const { permissions, ...baseInput } = input;
   
   for (const permission of permissions) {
-    const hasPermission = await isPermitted({
+    const result = await isPermitted({
       ...baseInput,
       permission,
     });
-    
-    if (!hasPermission) {
-      return false;
+    if (!result.ok) {
+      return result;
+    }
+    if (!result.data) {
+      return ok(false);
     }
   }
   
-  return true;
+  return ok(true);
 }
 
 /**
@@ -552,9 +563,14 @@ export async function hasAllPermissions(input: {
  * @param userId - User ID
  * @returns Promise resolving to super admin status
  */
-export async function isSuperAdmin(userId: UUID): Promise<boolean> {
-  const engine = getEngine();
-  return engine['checkSuperAdmin'](userId);
+export async function isSuperAdmin(userId: UUID): Promise<ApiResult<boolean>> {
+  try {
+    const engine = getEngine();
+    const value = await engine['checkSuperAdmin'](userId);
+    return ok(value);
+  } catch (error) {
+    return err(toApiError(error));
+  }
 }
 
 
@@ -573,68 +589,91 @@ export async function getPageScopeType(
   pageId: UUID | string,
   appId?: UUID,
   appName?: string
-): Promise<'event' | 'organisation' | 'both'> {
-  const engine = getEngine();
-  
+): Promise<ApiResult<'event' | 'organisation' | 'both'>> {
   try {
+    const engine = getEngine();
+    
     // Resolve appId if not provided
     let resolvedAppId = appId;
     if (!resolvedAppId && appName) {
-      // Get appId directly from app name
-      const { data: app } = await engine['supabase']
+      const { data: app, error: appError } = await engine['supabase']
         .from('rbac_apps')
-        .select('id')
+        .select('id, name, is_active')
         .eq('name', appName)
         .eq('is_active', true)
-        .single() as { data: { id: UUID } | null; error: any };
-      resolvedAppId = app?.id;
+        .maybeSingle() as { data: { id: UUID; name: string; is_active: boolean } | null; error: unknown | null };
+      
+      if (appError) {
+        log.error('Error resolving appId from appName', { 
+          appName, 
+          pageId, 
+          error: appError,
+          errorMessage: appError instanceof Error ? appError.message : String(appError)
+        });
+        return err({ code: 'APP_RESOLVE_FAILED', message: `Failed to resolve appId from appName "${appName}": ${appError instanceof Error ? appError.message : String(appError)}` });
+      }
+      
+      if (!app) {
+        log.error('App not found or inactive', { appName, pageId });
+        return err({ code: 'APP_NOT_FOUND', message: `Could not resolve appId for appName "${appName}" - app not found or not active` });
+      }
+      
+      resolvedAppId = app.id;
     }
     
     if (!resolvedAppId) {
-      throw new Error(`Could not resolve appId for page ${pageId}`);
+      log.error('No appId resolved', { pageId, appId, appName });
+      return err({ code: 'APP_ID_REQUIRED', message: `Could not resolve appId for page ${pageId} - appId and appName both missing or invalid` });
     }
     
-    // Resolve pageId if it's a page name
     let resolvedPageId: UUID | string = pageId;
     const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
     if (!uuidRegex.test(pageId)) {
-      // It's a page name, resolve to UUID
-      const { data: page } = await engine['supabase']
+      const { data: page, error: pageError } = await engine['supabase']
         .from('rbac_app_pages')
-        .select('id')
+        .select('id, page_name, app_id')
         .eq('app_id', resolvedAppId)
         .eq('page_name', pageId)
-        .maybeSingle() as { data: { id: UUID } | null; error: any };
-      resolvedPageId = page?.id || pageId;
+        .maybeSingle() as { data: { id: UUID; page_name: string; app_id: UUID } | null; error: unknown | null };
+      
+      if (pageError) {
+        log.error('Error resolving pageId from page_name', { pageId, appId: resolvedAppId, appName, error: pageError });
+        return err({ code: 'PAGE_RESOLVE_FAILED', message: `Failed to resolve pageId "${pageId}" for appId ${resolvedAppId}: ${pageError instanceof Error ? pageError.message : String(pageError)}` });
+      }
+      
+      if (!page) {
+        log.error('Page not found in database', { pageId, appId: resolvedAppId, appName });
+        return err({ code: 'PAGE_NOT_FOUND', message: `Could not resolve pageId "${pageId}" to a valid UUID - page not found for appId ${resolvedAppId}` });
+      }
+      
+      resolvedPageId = page.id;
     }
     
-    // If still not a UUID, can't proceed
     if (!uuidRegex.test(resolvedPageId)) {
-      throw new Error(`Could not resolve pageId ${pageId} to a valid UUID`);
+      log.error('PageId resolution failed - not a valid UUID', { originalPageId: pageId, resolvedPageId, appId: resolvedAppId, appName });
+      return err({ code: 'PAGE_ID_INVALID', message: `Could not resolve pageId ${pageId} to a valid UUID` });
     }
     
-    // Query scope type directly from rbac_app_pages (removed legacy RPC get_page_scope_type)
     const { data: pageData, error } = await engine['supabase']
       .from('rbac_app_pages')
-      .select('scope_type')
+      .select('scope_type, page_name, app_id')
       .eq('id', resolvedPageId)
       .single();
     
     if (error) {
-      log.error('Error fetching page scope type:', { pageId, appId, error });
-      throw new Error(`Failed to get page scope type: ${error.message}`);
+      log.error('Error fetching page scope type from database', { pageId: resolvedPageId, originalPageId: pageId, appId: resolvedAppId, appName, error });
+      return err({ code: 'PAGE_SCOPE_FETCH_FAILED', message: `Failed to get page scope type: ${error instanceof Error ? error.message : String(error)}` });
     }
     
     if (!pageData || !pageData.scope_type) {
-      throw new Error(`Page ${resolvedPageId} does not have scope_type set`);
+      log.error('Page found but scope_type is missing', { pageId: resolvedPageId, originalPageId: pageId, appId: resolvedAppId, appName, pageData });
+      return err({ code: 'PAGE_SCOPE_TYPE_MISSING', message: `Page ${resolvedPageId} does not have scope_type set` });
     }
     
-    // Type assertion to narrow string to the specific union type
-    // The database constraint ensures it's one of these values
-    return pageData.scope_type as 'event' | 'organisation' | 'both';
-  } catch (err) {
-    log.error('Error fetching page scope type:', err);
-    throw err instanceof Error ? err : new Error(`Failed to get page scope type: ${String(err)}`);
+    return ok(pageData.scope_type as 'event' | 'organisation' | 'both');
+  } catch (error) {
+    log.error('Error fetching page scope type (catch block)', { pageId, appId, appName, error });
+    return err(toApiError(error));
   }
 }
 
@@ -645,13 +684,15 @@ export async function getPageScopeType(
  * @param organisationId - Organisation ID
  * @returns Promise resolving to organisation admin status
  */
-export async function isOrganisationAdmin(userId: UUID, organisationId: UUID): Promise<boolean> {
-  const accessLevel = await getAccessLevel({
+export async function isOrganisationAdmin(userId: UUID, organisationId: UUID): Promise<ApiResult<boolean>> {
+  const result = await getAccessLevel({
     userId,
     scope: { organisationId },
   });
-  
-  return accessLevel === 'admin' || accessLevel === 'super';
+  if (!result.ok) {
+    return result;
+  }
+  return ok(result.data === 'admin' || result.data === 'super');
 }
 
 /**
@@ -661,13 +702,16 @@ export async function isOrganisationAdmin(userId: UUID, organisationId: UUID): P
  * @param scope - Permission scope with eventId and appId
  * @returns Promise resolving to event admin status
  */
-export async function isEventAdmin(userId: UUID, scope: Scope): Promise<boolean> {
+export async function isEventAdmin(userId: UUID, scope: Scope): Promise<ApiResult<boolean>> {
   if (!scope.eventId || !scope.appId) {
-    return false;
+    return ok(false);
   }
   
-  const accessLevel = await getAccessLevel({ userId, scope });
-  return accessLevel === 'admin' || accessLevel === 'super';
+  const result = await getAccessLevel({ userId, scope });
+  if (!result.ok) {
+    return result;
+  }
+  return ok(result.data === 'admin' || result.data === 'super');
 }
 
 /**