@jmruthers/pace-core 0.5.189 → 0.5.190

package/src/rbac/secureClient.ts

@@ -18,6 +18,9 @@ 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.
  */
 export class SecureSupabaseClient {
   private supabase: SupabaseClient<Database>;
@@ -27,19 +30,22 @@ export class SecureSupabaseClient {
   private organisationId: UUID;
   private eventId?: string;
   private appId?: UUID;
+  private isSuperAdmin: boolean;
 
   constructor(
     supabaseUrl: string,
     supabaseKey: string,
     organisationId: UUID,
     eventId?: string,
-    appId?: UUID
+    appId?: UUID,
+    isSuperAdmin: boolean = false
   ) {
     this.supabaseUrl = supabaseUrl;
     this.supabaseKey = supabaseKey;
     this.organisationId = organisationId;
     this.eventId = eventId;
     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
@@ -75,8 +81,11 @@ export class SecureSupabaseClient {
       // Type assertion needed because table is a string but Supabase expects specific table names
       const query = originalFrom(table as any);
       
+      // Store table name on query object so we can access it in filter methods
+      (query as any)._tableName = table;
+      
       // Inject organisation context into all queries
-      return this.injectContext(query);
+      return this.injectContext(query, table);
     };
 
     const originalRpc = this.supabase.rpc.bind(this.supabase);
@@ -129,7 +138,7 @@ export class SecureSupabaseClient {
   /**
    * Inject organisation context into a query
    */
-  private injectContext(query: any) {
+  private injectContext(query: any, tableName: string) {
     const originalSelect = query.select.bind(query);
     const originalInsert = query.insert.bind(query);
     const originalUpdate = query.update.bind(query);
@@ -138,11 +147,26 @@ export class SecureSupabaseClient {
     // Override select to add organisation filter
     query.select = (columns?: string) => {
       const result = originalSelect(columns);
-      return this.addOrganisationFilter(result);
+      return this.addOrganisationFilter(result, tableName);
     };
 
     // Override insert to add organisation context
     query.insert = (values: any) => {
+      // For rbac_user_profiles, only add organisation_id if not super admin
+      // Super admins can create users in any org, non-super-admins are restricted
+      if (tableName === 'rbac_user_profiles') {
+        if (this.isSuperAdmin) {
+          // Super admin: Don't force organisation_id (can be set explicitly if needed)
+          return originalInsert(values);
+        }
+        // Non-super-admin: Add organisation_id as defense in depth
+        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
       const contextValues = Array.isArray(values) 
         ? values.map(v => ({ ...v, organisation_id: this.organisationId }))
         : { ...values, organisation_id: this.organisationId };
@@ -153,13 +177,13 @@ export class SecureSupabaseClient {
     // Override update to add organisation filter
     query.update = (values: any) => {
       const result = originalUpdate(values);
-      return this.addOrganisationFilter(result);
+      return this.addOrganisationFilter(result, tableName);
     };
 
     // Override delete to add organisation filter
     query.delete = () => {
       const result = originalDelete();
-      return this.addOrganisationFilter(result);
+      return this.addOrganisationFilter(result, tableName);
     };
 
     return query;
@@ -167,9 +191,40 @@ export class SecureSupabaseClient {
 
   /**
    * Add organisation filter to a query
+   * 
+   * Defense in depth strategy:
+   * - RLS policies are the primary security layer (cannot be bypassed)
+   * - Application-level filtering adds an additional layer of protection
+   * 
+   * For rbac_user_profiles:
+   * - 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 other tables:
+   * - Always apply org filter unless super admin bypasses it
    */
-  private addOrganisationFilter(query: any) {
-    // Add organisation_id filter to all queries
+  private addOrganisationFilter(query: any, tableName: string) {
+    // 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 all other tables, apply organisation filter
+    // Super admins can still bypass via RLS if needed, but we filter at app level too
+    if (this.isSuperAdmin) {
+      // Super admins might want to see cross-org data, but for most tables
+      // we still apply the filter as a safety measure (they can override if needed)
+      // For now, we'll apply it - super admins can use direct queries if they need cross-org access
+      return query.eq('organisation_id', this.organisationId);
+    }
+    
+    // Non-super-admins: Always apply org filter
     return query.eq('organisation_id', this.organisationId);
   }
 
@@ -210,13 +265,15 @@ export class SecureSupabaseClient {
     organisationId?: UUID;
     eventId?: string;
     appId?: UUID;
+    isSuperAdmin?: boolean;
   }): SecureSupabaseClient {
     return new SecureSupabaseClient(
       this.supabaseUrl,
       this.supabaseKey,
       updates.organisationId || this.organisationId,
       updates.eventId !== undefined ? updates.eventId : this.eventId,
-      updates.appId !== undefined ? updates.appId : this.appId
+      updates.appId !== undefined ? updates.appId : this.appId,
+      updates.isSuperAdmin !== undefined ? updates.isSuperAdmin : this.isSuperAdmin
     );
   }
 
@@ -249,6 +306,7 @@ export class SecureSupabaseClient {
  * @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
@@ -258,7 +316,8 @@ export class SecureSupabaseClient {
  *   'your-publishable-key-or-anon-key',
  *   'org-123',
  *   'event-456',
- *   'app-789'
+ *   'app-789',
+ *   false // isSuperAdmin
  * );
  * ```
  */
@@ -267,9 +326,10 @@ export function createSecureClient(
   supabaseKey: string,
   organisationId: UUID,
   eventId?: string,
-  appId?: UUID
+  appId?: UUID,
+  isSuperAdmin: boolean = false
 ): SecureSupabaseClient {
-  return new SecureSupabaseClient(supabaseUrl, supabaseKey, organisationId, eventId, appId);
+  return new SecureSupabaseClient(supabaseUrl, supabaseKey, organisationId, eventId, appId, isSuperAdmin);
 }
 
 /**

package/src/rbac/security.ts

@@ -9,6 +9,8 @@
 
 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');
 
@@ -162,25 +164,17 @@ export class RBACSecurityValidator {
   /**
    * Validate context requirements for security
    * @param scope - Scope object
-   * @param appId - Application ID
+   * @param appConfig - App configuration
+   * @param appName - App name (for PORTAL special case)
    * @returns True if context is valid, false otherwise
    */
-  static validateContextRequirements(scope: Scope, appId?: UUID): boolean {
-    // Organisation context is always required
-    if (!scope.organisationId) {
-      return false;
-    }
-
-    // If app requires event, event context must be provided
-    if (appId && scope.appId === appId) {
-      // This would need to check app configuration
-      // For now, we'll assume event context is required if appId is provided
-      if (!scope.eventId) {
-        return false;
-      }
-    }
-
-    return true;
+  static async validateContextRequirements(
+    scope: Scope,
+    appConfig?: AppConfig | null,
+    appName?: string
+  ): Promise<boolean> {
+    const validation = await ContextValidator.validateScope(scope, appConfig || null, appName);
+    return validation.isValid;
   }
 
   /**
@@ -309,7 +303,7 @@ export const DEFAULT_SECURITY_CONFIG: RBACSecurityConfig = {
  */
 export interface SecurityContext {
   userId: UUID;
-  organisationId: UUID; // Required - can always be derived from event context
+  organisationId: UUID | null; // Required for resource-level permissions, null for page-level permissions (database handles NULL)
   ipAddress?: string;
   userAgent?: string;
   timestamp: Date;
@@ -353,11 +347,23 @@ export class RBACSecurityMiddleware {
       errors.push('Invalid user ID format');
     }
 
-    // OrganisationId is required
-    if (!context.organisationId) {
-      errors.push('Organisation ID is required');
-    } else if (!RBACSecurityValidator.validateUUID(context.organisationId)) {
-      errors.push('Invalid organisation ID format');
+    // For page-level permissions, organisationId can be null (database handles it)
+    // For resource-level permissions, organisationId is required
+    const isPagePermission = input.permission?.includes(':page.') || !!input.pageId;
+    const requiresOrgId = !isPagePermission;
+
+    // OrganisationId validation - only required for resource-level permissions
+    if (requiresOrgId) {
+      if (!context.organisationId) {
+        errors.push('Organisation ID is required for resource-level permissions');
+      } else if (!RBACSecurityValidator.validateUUID(context.organisationId)) {
+        errors.push('Invalid organisation ID format');
+      }
+    } else {
+      // For page-level permissions, organisationId can be null, but if provided, it must be valid
+      if (context.organisationId && !RBACSecurityValidator.validateUUID(context.organisationId)) {
+        errors.push('Invalid organisation ID format');
+      }
     }
 
     if (input.permission && !RBACSecurityValidator.validatePermission(input.permission)) {

package/src/rbac/types.ts

@@ -322,6 +322,16 @@ export class OrganisationContextRequiredError extends RBACError {
   }
 }
 
+export class EventContextRequiredError extends RBACError {
+  constructor() {
+    super(
+      'Event context is required for this operation',
+      'EVENT_CONTEXT_REQUIRED'
+    );
+    this.name = 'EventContextRequiredError';
+  }
+}
+
 export class RBACNotInitializedError extends RBACError {
   constructor() {
     super(

package/src/rbac/utils/__tests__/contextValidator.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { ContextValidator, type AppConfig } from '../contextValidator';
+import { EventContextRequiredError, OrganisationContextRequiredError, type Scope } from '../../types';
+import type { Database } from '../../../types/database';
+
+describe('ContextValidator', () => {
+  const eventRequiredConfig: AppConfig = { requires_event: true };
+  const orgRequiredConfig: AppConfig = { requires_event: false };
+  const scopeWithOrg: Scope = { organisationId: 'org-1', eventId: 'event-1', appId: 'app-1' };
+
+  const createSupabaseMock = () => ({}) as SupabaseClient<Database>;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('validateScope', () => {
+    it('treats PORTAL and ADMIN apps as always valid', async () => {
+      const baseScope: Scope = { appId: 'portal-app' };
+      const result = await ContextValidator.validateScope(baseScope, eventRequiredConfig, 'PORTAL');
+
+      expect(result).toEqual({
+        isValid: true,
+        resolvedScope: { organisationId: undefined, eventId: undefined, appId: 'portal-app' },
+        error: null
+      });
+    });
+
+    it('requires organisation context when no app config exists', async () => {
+      const baseScope: Scope = { eventId: 'event-1' };
+      const result = await ContextValidator.validateScope(baseScope, null);
+
+      expect(result.isValid).toBe(false);
+      expect(result.error).toBeInstanceOf(OrganisationContextRequiredError);
+    });
+
+    it('requires event context for event-based apps', async () => {
+      const baseScope: Scope = { organisationId: 'org-1' };
+      const result = await ContextValidator.validateScope(baseScope, eventRequiredConfig);
+
+      expect(result.isValid).toBe(false);
+      expect(result.error).toBeInstanceOf(EventContextRequiredError);
+    });
+
+    it('accepts scopes that satisfy event-based requirements', async () => {
+      const result = await ContextValidator.validateScope({ eventId: 'event-1' }, eventRequiredConfig);
+
+      expect(result.isValid).toBe(true);
+      expect(result.resolvedScope?.eventId).toBe('event-1');
+    });
+
+    it('enforces organisation requirements for org-based apps', async () => {
+      const result = await ContextValidator.validateScope({ eventId: 'event-1' }, orgRequiredConfig);
+
+      expect(result.isValid).toBe(false);
+      expect(result.error).toBeInstanceOf(OrganisationContextRequiredError);
+    });
+  });
+
+  describe('resolveRequiredContext', () => {
+    it('passes through scope for optional contexts', async () => {
+      const baseScope: Scope = { appId: 'admin-app' };
+      const result = await ContextValidator.resolveRequiredContext(baseScope, eventRequiredConfig, 'ADMIN');
+
+      expect(result).toEqual({
+        isValid: true,
+        resolvedScope: { organisationId: undefined, eventId: undefined, appId: 'admin-app' },
+        error: null
+      });
+    });
+
+    it('returns organisation error when no app config and org is missing', async () => {
+      const result = await ContextValidator.resolveRequiredContext({ eventId: 'event-1' }, null);
+
+      expect(result.isValid).toBe(false);
+      expect(result.error).toBeInstanceOf(OrganisationContextRequiredError);
+    });
+
+    it('derives organisation id for event-required apps when missing', async () => {
+      const supabase = createSupabaseMock();
+      const deriveSpy = vi.spyOn(ContextValidator, 'deriveOrgFromEvent').mockResolvedValue('derived-org');
+
+      const result = await ContextValidator.resolveRequiredContext({ eventId: 'event-1' }, eventRequiredConfig, undefined, supabase);
+
+      expect(deriveSpy).toHaveBeenCalledWith(supabase, 'event-1');
+      expect(result).toEqual({
+        isValid: true,
+        resolvedScope: { organisationId: 'derived-org', eventId: 'event-1', appId: undefined },
+        error: null
+      });
+    });
+
+    it('surfaces derivation failures when supabase is unavailable', async () => {
+      const result = await ContextValidator.resolveRequiredContext({ eventId: 'event-1' }, eventRequiredConfig, undefined, null);
+
+      expect(result.isValid).toBe(false);
+      expect(result.error?.message).toContain('supabase client not available');
+    });
+
+    it('returns derivation error messages when fetch fails', async () => {
+      const supabase = createSupabaseMock();
+      vi.spyOn(ContextValidator, 'deriveOrgFromEvent').mockRejectedValue(new Error('network down'));
+
+      const result = await ContextValidator.resolveRequiredContext({ eventId: 'event-1' }, eventRequiredConfig, undefined, supabase);
+
+      expect(result.isValid).toBe(false);
+      expect(result.error).toBeInstanceOf(Error);
+      expect(result.error?.message).toContain('network down');
+    });
+
+    it('enforces organisation requirement for org-based apps', async () => {
+      const result = await ContextValidator.resolveRequiredContext({ eventId: 'event-1' }, orgRequiredConfig);
+
+      expect(result.isValid).toBe(false);
+      expect(result.error).toBeInstanceOf(OrganisationContextRequiredError);
+    });
+
+    it('returns valid result when org context is present', async () => {
+      const result = await ContextValidator.resolveRequiredContext(scopeWithOrg, orgRequiredConfig);
+
+      expect(result).toEqual({ isValid: true, resolvedScope: scopeWithOrg, error: null });
+    });
+  });
+
+  describe('isContextReady', () => {
+    it('is always ready for PORTAL/ADMIN apps', () => {
+      expect(ContextValidator.isContextReady({}, eventRequiredConfig, 'PORTAL')).toBe(true);
+    });
+
+    it('checks event selection for event-required apps', () => {
+      expect(ContextValidator.isContextReady({}, eventRequiredConfig, undefined, true)).toBe(true);
+      expect(ContextValidator.isContextReady({}, eventRequiredConfig, undefined, false)).toBe(false);
+    });
+
+    it('checks organisation selection for org-required apps', () => {
+      expect(ContextValidator.isContextReady({}, orgRequiredConfig, undefined, false, true)).toBe(true);
+      expect(ContextValidator.isContextReady({}, orgRequiredConfig, undefined, false, false)).toBe(false);
+    });
+
+    it('defaults to organisation requirement when no config', () => {
+      expect(ContextValidator.isContextReady({}, null, undefined, false, true)).toBe(true);
+      expect(ContextValidator.isContextReady({}, null, undefined, false, false)).toBe(false);
+    });
+  });
+});

package/src/rbac/utils/__tests__/deep-equal.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { deepEqual, scopeEqual } from '../deep-equal';
+import type { Scope } from '../../types';
+
+describe('deepEqual', () => {
+  it('returns true for identical primitives and references', () => {
+    expect(deepEqual(5, 5)).toBe(true);
+    expect(deepEqual('test', 'test')).toBe(true);
+    const obj = { value: 1 };
+    expect(deepEqual(obj, obj)).toBe(true);
+  });
+
+  it('returns false for different primitive values or types', () => {
+    expect(deepEqual(5, 6)).toBe(false);
+    expect(deepEqual(5, '5')).toBe(false);
+    expect(deepEqual(null, undefined)).toBe(false);
+  });
+
+  it('compares arrays by value and order', () => {
+    expect(deepEqual([1, 2, 3], [1, 2, 3])).toBe(true);
+    expect(deepEqual([1, 2, 3], [3, 2, 1])).toBe(false);
+    expect(deepEqual([1, 2], [1, 2, 3])).toBe(false);
+  });
+
+  it('performs deep comparisons on nested objects', () => {
+    const left = { id: 1, nested: { active: true, tags: ['a', 'b'] } };
+    const right = { nested: { tags: ['a', 'b'], active: true }, id: 1 };
+    expect(deepEqual(left, right)).toBe(true);
+  });
+
+  it('detects differences in object structure or values', () => {
+    const base = { id: 1, nested: { active: true } };
+    expect(deepEqual(base, { id: 1, nested: { active: false } })).toBe(false);
+    expect(deepEqual(base, { id: 1, nested: { active: true }, extra: 'field' })).toBe(false);
+    expect(deepEqual(base, { id: 1, other: { active: true } })).toBe(false);
+  });
+});
+
+describe('scopeEqual', () => {
+  it('returns true for identical scopes including nulls', () => {
+    const scope: Scope = { organisationId: 'org', eventId: 'event', appId: 'app' };
+    expect(scopeEqual(scope, { ...scope })).toBe(true);
+    expect(scopeEqual(null, null)).toBe(true);
+    expect(scopeEqual(undefined, undefined)).toBe(true);
+  });
+
+  it('returns false when any scope property differs', () => {
+    const base: Scope = { organisationId: 'org', eventId: 'event', appId: 'app' };
+    expect(scopeEqual(base, { ...base, eventId: 'other' })).toBe(false);
+    expect(scopeEqual(base, { organisationId: 'org', eventId: 'event' })).toBe(false);
+    expect(scopeEqual(base, null)).toBe(false);
+  });
+});

package/src/rbac/utils/__tests__/eventContext.test.ts

@@ -15,7 +15,8 @@ import {
   getOrganisationFromEvent,
   createScopeFromEvent,
   isEventBasedScope,
-  isValidEventBasedScope
+  isValidEventBasedScope,
+  clearAllOrgDerivationCache
 } from '../eventContext';
 
 // Mock Supabase client
@@ -37,11 +38,15 @@ describe('Event Context Utilities', () => {
   let mockQuery: any;
 
   beforeEach(() => {
+    // Clear cache before each test to prevent test interference
+    clearAllOrgDerivationCache();
     mockSupabase = createMockSupabaseClient();
     mockQuery = mockSupabase.from('event');
   });
 
   afterEach(() => {
+    // Clear cache after each test
+    clearAllOrgDerivationCache();
     vi.clearAllMocks();
   });