@jmruthers/pace-core 0.6.1 → 0.6.3

package/src/rbac/secureClient.ts

@@ -12,6 +12,7 @@ import { createClient, SupabaseClient } from '@supabase/supabase-js';
 import { Database } from '../types/database';
 import { UUID } from './types';
 import { OrganisationContextRequiredError } from './types';
+import { markClientAsSecure } from './utils/clientSecurity';
 
 /**
  * Secure Supabase Client that enforces organisation context
@@ -19,26 +20,48 @@ import { OrganisationContextRequiredError } from './types';
  * This client automatically injects organisation context into all requests
  * and prevents queries that don't have the required context.
  * 
- * Note: Callers should derive organisationId from eventId before creating this client
- * if working with event-required apps. The client requires organisationId.
+ * Note: For non-super-admins, organisationId is required. Super-admins can operate
+ * without organisationId to access system-wide tables (like core_organisations).
+ * Callers should derive organisationId from eventId before creating this client
+ * if working with event-required apps.
  */
 export class SecureSupabaseClient {
   private supabase: SupabaseClient<Database>;
   private edgeFunctionClient: SupabaseClient<Database> | null = null;
   private supabaseUrl: string;
   private supabaseKey: string;
-  private organisationId: UUID;
+  private organisationId: UUID | null;
   private eventId?: string;
   private appId?: UUID;
   private isSuperAdmin: boolean;
+  private usesExistingClient: boolean = false;
+  
+  // Cache for RPC function signatures to avoid repeated database queries
+  // Maps function name -> Set of parameter names it accepts
+  private static rpcSignatureCache = new Map<string, Set<string>>();
+
+  /**
+   * RPC functions that are safe to call without organisation context.
+   *
+   * These functions must:
+   * - rely on JWT context (auth.uid()) for authentication
+   * - not read or write organisation-scoped data
+   *
+   * This allowlist enables compliant consuming apps to use `secureSupabase.rpc(...)`
+   * even before an organisation is selected (common during initial page load/refresh).
+   */
+  private static readonly GLOBAL_RPC_ALLOWLIST = new Set<string>([
+    'data_rbac_apps_list',
+  ]);
 
   constructor(
     supabaseUrl: string,
     supabaseKey: string,
-    organisationId: UUID,
+    organisationId: UUID | null,
     eventId?: string,
     appId?: UUID,
-    isSuperAdmin: boolean = false
+    isSuperAdmin: boolean = false,
+    existingClient?: SupabaseClient<Database>
   ) {
     this.supabaseUrl = supabaseUrl;
     this.supabaseKey = supabaseKey;
@@ -47,18 +70,25 @@ export class SecureSupabaseClient {
     this.appId = appId;
     this.isSuperAdmin = isSuperAdmin;
 
-    // Create the base Supabase client with context headers
-    // Note: We'll override functions.invoke to exclude headers for Edge Functions
-    // as they may not have CORS configured to accept custom headers
-    this.supabase = createClient<Database>(supabaseUrl, supabaseKey, {
-      global: {
-        headers: {
-          'x-organisation-id': organisationId,
-          'x-event-id': eventId || '',
-          'x-app-id': appId || '',
+    // Prefer reusing an existing authenticated client (avoids multiple GoTrue instances
+    // and ensures auth context is present for RLS policies).
+    if (existingClient) {
+      this.supabase = existingClient;
+      this.usesExistingClient = true;
+    } else {
+      // Create the base Supabase client with context headers
+      // Note: We'll override functions.invoke to exclude headers for Edge Functions
+      // as they may not have CORS configured to accept custom headers
+      this.supabase = createClient<Database>(supabaseUrl, supabaseKey, {
+        global: {
+          headers: {
+            'x-organisation-id': organisationId || '',
+            'x-event-id': eventId || '',
+            'x-app-id': appId || '',
+          },
         },
-      },
-    });
+      });
+    }
 
     // Override the auth methods to inject context
     this.setupContextInjection();
@@ -66,6 +96,9 @@ export class SecureSupabaseClient {
     // Override functions.invoke to exclude custom headers for Edge Functions
     // Edge Functions may not have CORS configured to accept custom headers
     this.setupEdgeFunctionHandling();
+    
+    // Mark the client as secure
+    markClientAsSecure(this.supabase);
   }
 
   /**
@@ -75,8 +108,10 @@ export class SecureSupabaseClient {
     const originalFrom = this.supabase.from.bind(this.supabase);
     
     (this.supabase as any).from = (table: string): any => {
-      // Validate context before allowing any database operations
-      this.validateContext();
+      // Validate context before allowing database operations.
+      // Some tables are not organisation-scoped (e.g. rbac_apps) and must be queryable
+      // without organisation context for initial bootstrapping.
+      this.validateContextForTable(table);
       
       // Type assertion needed because table is a string but Supabase expects specific table names
       const query = originalFrom(table as any);
@@ -94,16 +129,46 @@ export class SecureSupabaseClient {
     // Type assertion needed because we're wrapping the generic rpc method
     // The fn parameter is typed as string to match Supabase's rpc signature
     (this.supabase as any).rpc = (fn: string, args?: any, options?: any): any => {
-      // Validate context before allowing any RPC calls
-      this.validateContext();
+      // Validate context before allowing RPC calls.
+      // Some RPCs are global (not organisation-scoped) but still require auth.uid() from JWT.
+      // Allow these even without organisation context.
+      this.validateContextForRpc(fn);
+
+      // SYSTEMIC FIX: Use opt-in whitelist approach instead of brittle blacklist.
+      // PostgREST matches RPCs by *exact* parameter signature; sending unexpected params results in:
+      // - HTTP 404 + PGRST202 "Could not find the function ... with parameters ..."
+      //
+      // By default, we don't inject context unless the function is explicitly whitelisted.
+      // This prevents PGRST202 errors and makes the system more maintainable.
+      const acceptedParams = this.getRpcAcceptedParams(fn);
+      
+      // Only inject context parameters that:
+      // 1. The function accepts (according to our whitelist)
+      // 2. Are not already explicitly provided
+      // 3. We have values for
+      // IMPORTANT: Do NOT overwrite explicitly provided RPC parameters.
+      // Some RPCs legitimately take `p_app_id`/`p_event_id` as the *target* entity,
+      // which may differ from the current RBAC scope app/event.
+      const safeArgs = (args ?? {}) as Record<string, unknown>;
+      const contextArgs: Record<string, unknown> = { ...safeArgs };
+      
+      if (acceptedParams.has('p_organisation_id') && 
+          this.organisationId && 
+          safeArgs.p_organisation_id === undefined) {
+        contextArgs.p_organisation_id = this.organisationId;
+      }
+      
+      if (acceptedParams.has('p_event_id') && 
+          this.eventId && 
+          safeArgs.p_event_id === undefined) {
+        contextArgs.p_event_id = this.eventId;
+      }
       
-      // Inject context into RPC calls
-      const contextArgs = {
-        ...args,
-        p_organisation_id: this.organisationId,
-        p_event_id: this.eventId,
-        p_app_id: this.appId,
-      };
+      if (acceptedParams.has('p_app_id') && 
+          this.appId && 
+          safeArgs.p_app_id === undefined) {
+        contextArgs.p_app_id = this.appId;
+      }
       
       return originalRpc(fn as any, contextArgs, options);
     };
@@ -119,10 +184,19 @@ export class SecureSupabaseClient {
    * This avoids interfering with the main client's operations.
    */
   private setupEdgeFunctionHandling() {
-    // Create a separate client without custom headers for Edge Functions
-    // This prevents CORS errors when Edge Functions don't accept custom headers
-    // Store it as an instance variable to avoid creating multiple clients
-    // We'll use this client directly for Edge Function calls instead of overriding
+    // IMPORTANT:
+    // Do not create a second Supabase client when we are already reusing an authenticated
+    // base client (this triggers "Multiple GoTrueClient instances" warnings and can cause
+    // session/auth desync that breaks RLS-protected reads).
+    //
+    // If we're using an existing client, just use it for Edge Functions too.
+    if (this.usesExistingClient) {
+      this.edgeFunctionClient = null;
+      return;
+    }
+
+    // Otherwise, create a separate client without the custom RBAC headers for Edge Functions.
+    // This prevents CORS errors when Edge Functions don't accept custom headers.
     this.edgeFunctionClient = createClient<Database>(this.supabaseUrl, this.supabaseKey);
   }
 
@@ -147,6 +221,8 @@ export class SecureSupabaseClient {
     // Override select to add organisation filter
     query.select = (columns?: string) => {
       const result = originalSelect(columns);
+      // Store table name on query object so we can access it in filter methods
+      (result as any)._tableName = tableName;
       return this.addOrganisationFilter(result, tableName);
     };
 
@@ -173,13 +249,28 @@ export class SecureSupabaseClient {
           return originalInsert(values);
         }
         // Non-super-admin: Add organisation_id as defense in depth
+        // organisationId should always be available for non-super-admins (validateContext ensures this)
+        if (!this.organisationId) {
+          throw new OrganisationContextRequiredError();
+        }
         const contextValues = Array.isArray(values) 
           ? values.map(v => ({ ...v, organisation_id: this.organisationId }))
           : { ...values, organisation_id: this.organisationId };
         return originalInsert(contextValues);
       }
       
-      // For other tables, always add organisation_id
+      // For other tables, add organisation_id if available
+      // Super-admins might not have organisationId set, so allow them to set it explicitly
+      if (this.isSuperAdmin && !this.organisationId) {
+        // Super admin without organisationId: Don't force it (can be set explicitly if needed)
+        return originalInsert(values);
+      }
+      
+      // Non-super-admin or super-admin with organisationId: Add organisation_id
+      // organisationId should always be available for non-super-admins (validateContext ensures this)
+      if (!this.organisationId) {
+        throw new OrganisationContextRequiredError();
+      }
       const contextValues = Array.isArray(values) 
         ? values.map(v => ({ ...v, organisation_id: this.organisationId }))
         : { ...values, organisation_id: this.organisationId };
@@ -213,6 +304,10 @@ export class SecureSupabaseClient {
    * - Super admins: No org filter (see all users) - RLS will allow access
    * - Non-super-admins: Apply org filter as defense in depth - RLS will also filter
    * 
+   * For system-wide tables (like core_organisations):
+   * - Super admins: No org filter (see all records) - RLS will allow access
+   * - Non-super-admins: Apply org filter as defense in depth - RLS will also filter
+   * 
    * For other tables:
    * - Always apply org filter unless super admin bypasses it
    */
@@ -247,15 +342,29 @@ export class SecureSupabaseClient {
       return query;
     }
     
+    // System-wide tables that super-admins should be able to query without organisation filters
+    // These tables have organisation_id but super-admins need to see all records
+    const systemWideTablesForSuperAdmins = [
+      'core_organisations', // Super-admins need to see all organisations
+    ];
+    
+    // For system-wide tables, super-admins bypass organisation filter
+    if (systemWideTablesForSuperAdmins.includes(tableName) && this.isSuperAdmin) {
+      return query; // No filter - RLS handles access control
+    }
+    
     // For rbac_user_profiles, use conditional filtering based on super admin status
     if (tableName === 'rbac_user_profiles') {
       // Super admins: No org filter (see all users via RLS)
-      // Non-super-admins: Apply org filter as defense in depth (RLS also filters)
       if (this.isSuperAdmin) {
         return query; // No filter - RLS handles access control
       }
-      // Apply org filter for non-super-admins as additional security layer
-      return query.eq('organisation_id', this.organisationId);
+      
+      // For non-super-admins: Apply org filter, but allow NULL organisation_id
+      // User profiles can have organisation_id = NULL (users not yet assigned to an org)
+      // We use .or() to allow either matching organisation_id OR NULL
+      // RLS policies will still enforce access control
+      return query.or(`organisation_id.eq.${this.organisationId},organisation_id.is.null`);
     }
     
     // For all other tables, apply organisation filter
@@ -273,17 +382,69 @@ export class SecureSupabaseClient {
 
   /**
    * Validate that required context is present
+   * Super-admins can operate without organisation context
    */
   private validateContext() {
+    // Super-admins can operate without organisation context
+    if (this.isSuperAdmin) {
+      return;
+    }
+    
     if (!this.organisationId) {
       throw new OrganisationContextRequiredError();
     }
   }
 
+  /**
+   * Determine whether a table requires organisation context.
+   * Tables without an organisation_id column (or global configuration tables) are safe without org context.
+   */
+  private tableRequiresOrganisationContext(tableName: string): boolean {
+    // Keep this list aligned with the tables handled in `addOrganisationFilter` / `injectContext`.
+    const tablesWithoutOrganisationId = new Set<string>([
+      'core_organisations',
+      'rbac_apps',
+      'rbac_app_pages',
+      'rbac_global_roles',
+      'core_person',
+      'core_member',
+      'core_contact',
+      'core_consent',
+      'core_identification',
+      'core_qualification',
+      'medi_profile',
+      'medi_condition',
+      'medi_diet',
+      'medi_action_plan',
+      'medi_profile_versions',
+    ]);
+
+    return !tablesWithoutOrganisationId.has(tableName);
+  }
+
+  /**
+   * Validate context for a specific table operation.
+   */
+  private validateContextForTable(tableName: string) {
+    if (this.isSuperAdmin) return;
+    if (!this.organisationId && this.tableRequiresOrganisationContext(tableName)) {
+      throw new OrganisationContextRequiredError();
+    }
+  }
+
+  /**
+   * Validate context for a specific RPC call.
+   */
+  private validateContextForRpc(fn: string) {
+    if (this.isSuperAdmin) return;
+    if (SecureSupabaseClient.GLOBAL_RPC_ALLOWLIST.has(fn)) return;
+    this.validateContext();
+  }
+
   /**
    * Get the current organisation ID
    */
-  getOrganisationId(): UUID {
+  getOrganisationId(): UUID | null {
     return this.organisationId;
   }
 
@@ -305,7 +466,7 @@ export class SecureSupabaseClient {
    * Create a new client with updated context
    */
   withContext(updates: {
-    organisationId?: UUID;
+    organisationId?: UUID | null;
     eventId?: string;
     appId?: UUID;
     isSuperAdmin?: boolean;
@@ -313,7 +474,7 @@ export class SecureSupabaseClient {
     return new SecureSupabaseClient(
       this.supabaseUrl,
       this.supabaseKey,
-      updates.organisationId || this.organisationId,
+      updates.organisationId !== undefined ? updates.organisationId : this.organisationId,
       updates.eventId !== undefined ? updates.eventId : this.eventId,
       updates.appId !== undefined ? updates.appId : this.appId,
       updates.isSuperAdmin !== undefined ? updates.isSuperAdmin : this.isSuperAdmin
@@ -327,7 +488,7 @@ export class SecureSupabaseClient {
   getClient(): SupabaseClient<Database> {
     // Return a proxy that intercepts functions.invoke calls to use edge function client
     // This avoids CORS issues with Edge Functions while keeping the main client intact
-    return new Proxy(this.supabase, {
+    const proxiedClient = new Proxy(this.supabase, {
       get: (target, prop) => {
         if (prop === 'functions' && this.edgeFunctionClient) {
           // Return the edge function client's functions for invoke calls
@@ -338,36 +499,100 @@ export class SecureSupabaseClient {
         return (target as any)[prop];
       }
     }) as SupabaseClient<Database>;
+    
+    // Mark the proxied client as secure
+    markClientAsSecure(proxiedClient);
+    
+    return proxiedClient;
+  }
+
+  /**
+   * Get the set of parameter names that an RPC function accepts.
+   * Uses a static whitelist of RPCs that we know accept context parameters.
+   * 
+   * This is an opt-in approach: by default, we don't inject context unless
+   * the function is explicitly whitelisted. This prevents PGRST202 errors from
+   * injecting unexpected parameters.
+   * 
+   * @param fn - The RPC function name
+   * @returns Set of parameter names the function accepts
+   */
+  private getRpcAcceptedParams(fn: string): Set<string> {
+    // Check cache first
+    if (SecureSupabaseClient.rpcSignatureCache.has(fn)) {
+      return SecureSupabaseClient.rpcSignatureCache.get(fn)!;
+    }
+
+    // Whitelist of RPCs that accept context parameters
+    // Format: function name -> Set of parameters it accepts
+    // 
+    // SYSTEMIC FIX: This is an opt-in approach. By default, we don't inject context
+    // unless the function is explicitly whitelisted. This prevents PGRST202 errors
+    // from injecting unexpected parameters.
+    //
+    // To add a new RPC:
+    // 1. Check the function signature in the database: 
+    //    SELECT pg_get_function_identity_arguments(oid) FROM pg_proc WHERE proname = 'function_name';
+    // 2. Add it here with the parameters it accepts
+    const rpcContextWhitelist: Record<string, Set<string>> = {
+      // RPCs that accept all three context parameters
+      'rbac_roles_list': new Set(['p_organisation_id', 'p_event_id', 'p_app_id']),
+      
+      // RPCs that accept only p_organisation_id (not p_app_id or p_event_id)
+      'data_file_reference_by_category_list': new Set(['p_organisation_id']),
+      
+      // Add more RPCs here as we discover them
+      // Format: 'function_name': new Set(['p_organisation_id', 'p_event_id', 'p_app_id']),
+    };
+
+    // Default: empty set (no context injection) unless whitelisted
+    // This is the safe default - prevents PGRST202 errors
+    const acceptedParams = rpcContextWhitelist[fn] || new Set<string>();
+    
+    // Cache the result to avoid repeated lookups
+    SecureSupabaseClient.rpcSignatureCache.set(fn, acceptedParams);
+    
+    return acceptedParams;
   }
 }
 
-/**
- * Create a secure Supabase client with organisation context
- * 
- * @param supabaseUrl - Supabase project URL
- * @param supabaseKey - Supabase publishable key or anon key (accepts both legacy anon keys and modern publishable keys)
- * @param organisationId - Required organisation ID
- * @param eventId - Optional event ID
- * @param appId - Optional app ID
- * @param isSuperAdmin - Optional super admin flag (defaults to false)
- * @returns SecureSupabaseClient instance
- * 
- * @example
- * ```typescript
- * const client = createSecureClient(
- *   'https://your-project.supabase.co',
- *   'your-publishable-key-or-anon-key',
- *   'org-123',
- *   'event-456',
- *   'app-789',
- *   false // isSuperAdmin
- * );
- * ```
- */
+  /**
+   * Create a secure Supabase client with organisation context
+   * 
+   * @param supabaseUrl - Supabase project URL
+   * @param supabaseKey - Supabase publishable key or anon key (accepts both legacy anon keys and modern publishable keys)
+   * @param organisationId - Organisation ID (optional for super-admins)
+   * @param eventId - Optional event ID
+   * @param appId - Optional app ID
+   * @param isSuperAdmin - Optional super admin flag (defaults to false). When true, organisationId can be null.
+   * @returns SecureSupabaseClient instance
+   * 
+   * @example
+   * ```typescript
+   * const client = createSecureClient(
+   *   'https://your-project.supabase.co',
+   *   'your-publishable-key-or-anon-key',
+   *   'org-123',
+   *   'event-456',
+   *   'app-789',
+   *   false // isSuperAdmin
+   * );
+   * 
+   * // For super-admins, organisationId can be null
+   * const superAdminClient = createSecureClient(
+   *   'https://your-project.supabase.co',
+   *   'your-publishable-key-or-anon-key',
+   *   null, // organisationId not required for super-admins
+   *   undefined,
+   *   undefined,
+   *   true // isSuperAdmin
+   * );
+   * ```
+   */
 export function createSecureClient(
   supabaseUrl: string,
   supabaseKey: string,
-  organisationId: UUID,
+  organisationId: UUID | null,
   eventId?: string,
   appId?: UUID,
   isSuperAdmin: boolean = false
@@ -386,11 +611,12 @@ export function createSecureClient(
  */
 export function fromSupabaseClient(
   client: SupabaseClient<Database>,
-  organisationId: UUID,
+  organisationId: UUID | null,
   eventId?: string,
-  appId?: UUID
+  appId?: UUID,
+  isSuperAdmin: boolean = false
 ): SecureSupabaseClient {
-  // We need the URL and key to create a new client, but they're not accessible
-  // This function should be used with createSecureClient instead
-  throw new Error('fromSupabaseClient is not supported. Use createSecureClient instead.');
+  // Wrap the existing client to reuse auth/session while enforcing organisation/event/app context.
+  // URL/key are unused in this mode.
+  return new SecureSupabaseClient('', '', organisationId, eventId, appId, isSuperAdmin, client);
 }

package/src/rbac/security.ts

@@ -9,8 +9,6 @@
 
 import { UUID, Permission, Scope } from './types';
 import { createLogger } from '../utils/core/logger';
-import { ContextValidator } from './utils/contextValidator';
-import type { AppConfig } from './utils/contextValidator';
 
 const log = createLogger('RBACSecurity');
 
@@ -161,21 +159,6 @@ export class RBACSecurityValidator {
     return true;
   }
 
-  /**
-   * Validate context requirements for security
-   * @param scope - Scope object
-   * @param appConfig - App configuration
-   * @param appName - App name (for PORTAL special case)
-   * @returns True if context is valid, false otherwise
-   */
-  static async validateContextRequirements(
-    scope: Scope,
-    appConfig?: AppConfig | null,
-    appName?: string
-  ): Promise<boolean> {
-    const validation = await ContextValidator.validateScope(scope, appConfig || null, appName);
-    return validation.isValid;
-  }
 
   /**
    * Log security event for monitoring

package/src/rbac/types.ts

@@ -28,12 +28,20 @@ export type AccessLevel =
   | 'admin'
   | 'super';
 
+/**
+ * Scope defines the context for permission checks.
+ * Can include organisation, event, and/or app identifiers.
+ */
 export type Scope = {
   organisationId?: UUID;
   eventId?: string; // event_id is text/varchar
   appId?: AppId | UUID;
 };
 
+/**
+ * Permission check request parameters.
+ * Defines who (userId) is checking what permission in what context (scope).
+ */
 export type PermissionCheck = {
   userId: UUID;
   scope: Scope;
@@ -118,6 +126,7 @@ export interface RBACAppPage {
   created_by: UUID | null;
   updated_by: UUID | null;
   app_id: UUID;
+  scope_type: 'event' | 'organisation' | 'both'; // Required - single source of truth for page scoping
 }
 
 export interface RBACApp {