@jmruthers/pace-core 0.6.10 → 0.6.12

package/src/rbac/api.ts

@@ -25,14 +25,47 @@ import { createRBACEngine, RBACEngine } from './engine';
 import { createAuditManager, setGlobalAuditManager } from './audit';
 import { rbacCache, RBACCache, CACHE_PATTERNS } from './cache';
 import { createRBACConfig, RBACConfig } from './config';
-import { SecurityContext } from './security';
+import { RBACSecurityValidator, 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';
+import { getCurrentAppName } from '../utils/app/appNameResolver';
 
 const log = createLogger('RBACAPI');
 
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Normalise scope so the engine never sees empty strings (avoids invalid_input on every page).
+ * Call before engine.isPermitted so validateScope always passes when we call.
+ */
+function normalizeScope(scope: Scope): Scope {
+  const org = scope.organisationId;
+  const ev = scope.eventId;
+  const app = scope.appId;
+  const hasOrg = typeof org === 'string' && org.trim() !== '';
+  const hasEv = typeof ev === 'string' && ev.trim() !== '';
+  const hasApp = typeof app === 'string' && app.trim() !== '';
+  return {
+    ...(hasOrg ? { organisationId: org } : {}),
+    ...(hasEv ? { eventId: ev } : {}),
+    ...(hasApp ? { appId: app } : {}),
+  };
+}
+
+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;
 
@@ -134,14 +167,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
@@ -158,13 +191,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));
   }
 }
 
@@ -194,7 +227,7 @@ export async function getPermissionMap(
     scope: Scope;
   },
   appName?: string
-): Promise<PermissionMap> {
+): Promise<ApiResult<PermissionMap>> {
   try {
     const engine = getEngine();
     
@@ -212,26 +245,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));
   }
 }
 
@@ -241,26 +274,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
-  });
 }
 
 /**
@@ -291,154 +329,197 @@ 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();
+
+    // Early guard: never run with invalid scope (avoids invalid_input and DB calls)
+    if (!input.scope || typeof input.scope !== 'object') {
+      return ok(false);
     }
-  }
-  // 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;
+    const normalizedInputScope = normalizeScope(input.scope);
+    if (!RBACSecurityValidator.validateScope(normalizedInputScope)) {
+      return ok(false);
+    }
+    let inputWithNormalizedScope: PermissionCheck = { ...input, scope: normalizedInputScope };
+
+    // 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 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
+
+    // Resolve appId when eventId present but appId missing (event-scoped page name check).
+    // Backend returns event-role permissions only when both p_event_id and p_app_id are set.
+    let scopeForCheck = inputWithNormalizedScope.scope;
+    const isPageName =
+      input.pageId &&
+      typeof input.pageId === 'string' &&
+      !UUID_REGEX.test(input.pageId);
+    const hasEventId =
+      typeof scopeForCheck.eventId === 'string' && scopeForCheck.eventId.trim() !== '';
+    const noAppId =
+      !scopeForCheck.appId ||
+      (typeof scopeForCheck.appId === 'string' && scopeForCheck.appId.trim() === '');
+    if (isPageName && hasEventId && noAppId) {
+      const currentAppName = getCurrentAppName();
+      if (currentAppName) {
+        try {
+          const { data: app } = (await engine['supabase']
+            .from('rbac_apps')
+            .select('id')
+            .eq('name', currentAppName)
+            .eq('is_active', true)
+            .maybeSingle()) as { data: { id: UUID } | null };
+          if (app) {
+            scopeForCheck = { ...scopeForCheck, appId: app.id };
+            inputWithNormalizedScope = { ...inputWithNormalizedScope, scope: scopeForCheck };
+          }
+        } catch (_err) {
+          // Ignore — getPageScopeType will fail with APP_ID_REQUIRED if needed
+        }
+      }
+    }
+
+    // Get app name if not provided (for PORTAL/ADMIN special case)
+    let resolvedAppName = appName;
+    if (!resolvedAppName && inputWithNormalizedScope.scope.appId) {
+      try {
+        const { data } = await engine['supabase']
+          .from('rbac_apps')
+          .select('name')
+          .eq('id', inputWithNormalizedScope.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,
+        inputWithNormalizedScope.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);
       }
-      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)}`);
+      if (!scopeResult.data) {
+        return err({ code: 'PAGE_SCOPE_TYPE_MISSING', message: `Page ${input.pageId} does not have scope_type set` });
+      }
+      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(
+      inputWithNormalizedScope.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);
+    // Normalise scope (strip empty strings) so engine never sees invalid scope → no invalid_input
+    const validatedScope = normalizeScope(validation.resolvedScope);
+    if (!RBACSecurityValidator.validateScope(validatedScope)) {
+      log.warn('Scope has no valid identifier after normalisation — skipping engine call', {
+        permission: input.permission,
+        pageId: input.pageId,
+      });
+      return ok(false);
+    }
     
-    // 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);
 }
 
 /**
@@ -454,7 +535,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)
@@ -469,23 +550,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);
   });
 }
 
@@ -500,21 +578,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);
 }
 
 /**
@@ -528,21 +608,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);
 }
 
 /**
@@ -551,9 +633,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));
+  }
 }
 
 
@@ -572,14 +659,13 @@ 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, error: appError } = await engine['supabase']
         .from('rbac_apps')
         .select('id, name, is_active')
@@ -594,12 +680,12 @@ export async function getPageScopeType(
           error: appError,
           errorMessage: appError instanceof Error ? appError.message : String(appError)
         });
-        throw new Error(`Failed to resolve appId from appName "${appName}": ${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 });
-        throw new Error(`Could not resolve appId for appName "${appName}" - app not found or not active`);
+        return err({ code: 'APP_NOT_FOUND', message: `Could not resolve appId for appName "${appName}" - app not found or not active` });
       }
       
       resolvedAppId = app.id;
@@ -607,14 +693,12 @@ export async function getPageScopeType(
     
     if (!resolvedAppId) {
       log.error('No appId resolved', { pageId, appId, appName });
-      throw new Error(`Could not resolve appId for page ${pageId} - appId and appName both missing or invalid`);
+      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, error: pageError } = await engine['supabase']
         .from('rbac_app_pages')
         .select('id, page_name, app_id')
@@ -623,42 +707,23 @@ export async function getPageScopeType(
         .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,
-          errorMessage: pageError instanceof Error ? pageError.message : String(pageError),
-          errorCode: (pageError as { code?: string })?.code
-        });
-        throw new Error(`Failed to resolve pageId "${pageId}" for appId ${resolvedAppId}: ${pageError instanceof Error ? pageError.message : String(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,
-          note: 'Page may not exist in rbac_app_pages table or may be for a different app'
-        });
-        throw new Error(`Could not resolve pageId "${pageId}" to a valid UUID - page not found for appId ${resolvedAppId}`);
+        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)) {
-      log.error('PageId resolution failed - not a valid UUID', { 
-        originalPageId: pageId, 
-        resolvedPageId, 
-        appId: resolvedAppId, 
-        appName 
-      });
-      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, page_name, app_id')
@@ -666,44 +731,19 @@ export async function getPageScopeType(
       .single();
     
     if (error) {
-      log.error('Error fetching page scope type from database', { 
-        pageId: resolvedPageId, 
-        originalPageId: pageId,
-        appId: resolvedAppId, 
-        appName,
-        error,
-        errorMessage: error instanceof Error ? error.message : String(error),
-        errorCode: (error as { code?: string })?.code,
-        errorDetails: (error as { details?: string })?.details,
-        errorHint: (error as { hint?: string })?.hint
-      });
-      throw new Error(`Failed to get page scope type: ${error instanceof Error ? error.message : String(error)}`);
+      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) {
-      log.error('Page found but scope_type is missing', { 
-        pageId: resolvedPageId, 
-        originalPageId: pageId,
-        appId: resolvedAppId,
-        appName,
-        pageData 
-      });
-      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 (catch block)', { 
-      pageId, 
-      appId, 
-      appName,
-      error: err,
-      errorMessage: err instanceof Error ? err.message : String(err),
-      errorStack: err instanceof Error ? err.stack : undefined
-    });
-    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));
   }
 }
 
@@ -714,13 +754,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');
 }
 
 /**
@@ -730,13 +772,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');
 }
 
 /**