@jmruthers/pace-core 0.5.186 → 0.5.188

package/docs/standards/07-rbac-and-rls-standard.md

@@ -0,0 +1,356 @@
+---
+lastUpdated: 2025-01-28T00:00:00+11:00
+version: 0.5.181
+reviewedBy: database-performance-audit
+---
+
+# RBAC and RLS Standard
+
+## Purpose
+
+Define standards for Row-Level Security (RLS) policies and Role-Based Access Control (RBAC) integration to ensure security, performance, and maintainability.
+
+## Principles
+
+- **Performance First**: All RLS policies must use optimized helper functions
+- **Security by Default**: Deny access unless explicitly allowed
+- **Consistent Patterns**: Use standardized helper functions across all policies
+- **Performance Monitoring**: Regular validation of query performance
+
+## RLS Policy Performance Requirements
+
+### Helper Function Requirements
+
+All helper functions used in RLS policies **MUST** have these attributes:
+
+| Requirement | Why | Example |
+|------------|-----|---------|
+| `STABLE` | Prevents re-evaluation for each row | `STABLE` |
+| `SECURITY DEFINER` | Bypass RLS to avoid recursion | `SECURITY DEFINER` |
+| `SET search_path TO 'public'` | Prevent search path injection | `SET search_path TO 'public'` |
+| No inline `auth.uid()` | Causes InitPlan nodes, severe performance degradation | Use helper function instead |
+
+### Helper Function Template
+
+```sql
+CREATE OR REPLACE FUNCTION function_name(parameters)
+RETURNS return_type
+LANGUAGE plpgsql
+STABLE                    -- ✅ Required
+SECURITY DEFINER          -- ✅ Required
+SET search_path TO public -- ✅ Required
+AS $$
+DECLARE
+  -- Declarations
+BEGIN
+  -- Function body
+  RETURN result;
+END;
+$$;
+```
+
+### Forbidden Patterns
+
+**❌ NEVER use these patterns in RLS policies:**
+
+```sql
+-- ❌ BAD: Inline auth.uid() call
+CREATE POLICY "bad_policy" ON table_name
+FOR SELECT USING (
+  user_id = auth.uid()  -- Called for every row!
+);
+
+-- ❌ BAD: Subquery in policy
+CREATE POLICY "bad_policy" ON table_name
+FOR SELECT USING (
+  organisation_id IN (
+    SELECT organisation_id FROM rbac_organisation_roles 
+    WHERE user_id = auth.uid()  -- Executes for every row!
+  )
+);
+
+-- ❌ BAD: current_setting in policy
+CREATE POLICY "bad_policy" ON table_name
+FOR SELECT USING (
+  organisation_id = current_setting('app.organisation_id')::UUID  -- Called for every row!
+);
+```
+
+### Required Patterns
+
+**✅ ALWAYS use these patterns:**
+
+```sql
+-- ✅ GOOD: Use helper function
+CREATE POLICY "good_policy" ON table_name
+FOR SELECT USING (
+  check_user_organisation_access(organisation_id)  -- Single function call per row
+);
+
+-- ✅ GOOD: Use helper function for app ID
+CREATE POLICY "good_policy" ON table_name
+FOR SELECT USING (
+  rbac_check_permission_simplified(
+    auth.uid(),
+    'read:page.table_name',
+    organisation_id,
+    event_id,
+    get_app_id('APP_NAME'),  -- ✅ Helper function
+    'table_name'
+  )
+);
+```
+
+## Standard Helper Functions
+
+### Core Helper Functions
+
+These functions are available for use in RLS policies:
+
+#### `is_super_admin()`
+- **Returns**: `boolean`
+- **Purpose**: Checks if current user is a super admin
+- **Usage**: `is_super_admin()`
+
+#### `check_user_organisation_access(p_organisation_id UUID)`
+- **Returns**: `boolean`
+- **Purpose**: Checks if current user has access to the specified organisation
+- **Usage**: `check_user_organisation_access(organisation_id)`
+
+#### `check_user_event_access(p_event_id TEXT)`
+- **Returns**: `boolean`
+- **Purpose**: Checks if current user has access to the specified event
+- **Usage**: `check_user_event_access(event_id)`
+
+#### `check_public_event_access(p_event_id TEXT)`
+- **Returns**: `boolean`
+- **Purpose**: Checks if the specified event is publicly accessible
+- **Usage**: `check_public_event_access(event_id)`
+
+#### `get_app_id(p_app_name TEXT)`
+- **Returns**: `UUID`
+- **Purpose**: Returns the UUID for any registered app
+- **Usage**: `get_app_id('BASE')`, `get_app_id('PACE')`, `get_app_id('CAKE')`
+- **Note**: Replaces `get_base_app_id()`, `get_pace_app_id()`, `util_get_cake_app_id()`
+
+#### `get_organisation_context()`
+- **Returns**: `UUID`
+- **Purpose**: Returns the current organisation context from the session
+- **Usage**: `get_organisation_context()`
+
+### Event Helper Functions
+
+#### `get_unit_event_id(p_unit_id TEXT)`
+- **Returns**: `TEXT`
+- **Purpose**: Returns the event_id for a given unit_id
+- **Usage**: `get_unit_event_id(unit_id)`
+
+#### `get_form_event_id(p_form_id UUID)`
+- **Returns**: `TEXT`
+- **Purpose**: Returns the event_id for a given form_id
+- **Usage**: `get_form_event_id(form_id)`
+
+#### `get_form_response_event_id(p_response_id UUID)`
+- **Returns**: `TEXT`
+- **Purpose**: Returns the event_id for a given form_response_id
+- **Usage**: `get_form_response_event_id(response_id)`
+
+#### `get_event_organisation_id(p_event_id TEXT)`
+- **Returns**: `UUID`
+- **Purpose**: Returns the organisation_id for a given event_id
+- **Usage**: `get_event_organisation_id(event_id)`
+
+### RBAC Permission Helper Functions
+
+#### `check_rbac_permission_with_context(p_permission TEXT, p_page_name TEXT, p_organisation_id UUID, p_event_id TEXT, p_app_id UUID)`
+- **Returns**: `boolean`
+- **Purpose**: STABLE SECURITY DEFINER wrapper for `rbac_check_permission_simplified()`. Use this in RLS policies instead of calling `rbac_check_permission_simplified()` with `auth.uid()` directly.
+- **Usage**: `check_rbac_permission_with_context('read:page.table_name', 'table_name', organisation_id, NULL, get_app_id('APP_NAME'))`
+- **Note**: This wrapper ensures `auth.uid()` is called once per function invocation (not per row) and the function is STABLE for RLS policy performance.
+
+## RLS Policy Patterns
+
+### Standard Organisation-Scoped Policy
+
+```sql
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  organisation_id IS NOT NULL
+  AND (
+    is_super_admin()
+    OR check_user_organisation_access(organisation_id)
+  )
+);
+```
+
+### Standard Event-Scoped Policy
+
+```sql
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  organisation_id IS NOT NULL
+  AND (
+    is_super_admin()
+    OR check_user_event_access(event_id)
+  )
+);
+```
+
+### RBAC Permission-Based Policy
+
+```sql
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  organisation_id IS NOT NULL
+  AND (
+    is_super_admin()
+    OR check_rbac_permission_with_context(
+      'read:page.table_name',
+      'table_name',
+      organisation_id,
+      event_id,
+      get_app_id('APP_NAME')
+    )
+  )
+);
+```
+
+**Note**: Always use `check_rbac_permission_with_context()` instead of calling `rbac_check_permission_simplified()` with `auth.uid()` directly. The wrapper function is STABLE SECURITY DEFINER and ensures optimal performance.
+
+### Public Access Policy
+
+```sql
+CREATE POLICY "public_select_table_name" ON table_name
+FOR SELECT TO anon
+USING (
+  check_public_event_access(event_id)
+);
+```
+
+## App Ownership
+
+Tables are assigned to specific apps for RBAC permission checking:
+
+| App | Tables |
+|-----|--------|
+| **BASE** | `base_application`, `base_questions` |
+| **PACE** | `pace_*` tables, `form_*` tables |
+| **CAKE** | `cake_*` tables |
+| **TRAC** | `trac_*` tables |
+| **MEDI** | `medi_*` tables |
+| **MINT** | `mint_*` tables (handled separately) |
+| **PORTAL** | `form_context_types` (shared with PACE) |
+
+## Testing Requirements
+
+### Before Merging RLS Changes
+
+1. **Run RLS Compliance Audit**:
+   ```bash
+   npm run audit:rls
+   ```
+   This checks for violations and should pass with zero violations.
+
+2. **Run Supabase Advisors**:
+   ```bash
+   supabase advisors performance
+   supabase advisors security
+   ```
+
+3. **Run Database Tests**:
+   ```bash
+   timeout 120 npm run test:db
+   ```
+
+4. **Run Application Tests**:
+   ```bash
+   timeout 60 npm run test
+   ```
+
+5. **Verify Performance**:
+   - Use EXPLAIN ANALYZE to verify no InitPlan nodes
+   - Verify queries complete in < 1 second
+   - Check Supabase Advisors show zero `auth_rls_initplan` warnings
+
+### Test Coverage Requirements
+
+- [ ] Policy coverage: All tables (except mint_*) have RLS enabled and policies
+- [ ] Performance: Queries complete in < 1 second
+- [ ] Security: Cross-organisation access is blocked
+- [ ] Helper functions: All are STABLE SECURITY DEFINER
+
+## Maintenance
+
+### Ongoing RLS Compliance Monitoring
+
+**Run RLS audit regularly** to catch any rogue policies that violate standards:
+
+```bash
+# Quick audit (recommended before merging PRs)
+npm run audit:rls
+
+# Or use test database
+npm run audit:rls:test
+
+# For CI/CD (fails on violations)
+npm run audit:rls:ci
+```
+
+The audit checks for:
+- Tables with RLS enabled but no policies
+- Policies using inline `auth.uid()` calls
+- Policies using `current_setting()` directly
+- Helper functions missing STABLE/SECURITY DEFINER
+
+### Weekly Health Checks
+
+Run weekly:
+```bash
+# RLS compliance audit
+npm run audit:rls
+
+# Performance advisors
+supabase advisors performance
+
+# Security advisors
+supabase advisors security
+
+# Review slow queries
+# (configure log_min_duration_statement = 1000)
+```
+
+### Monitoring
+
+Monitor:
+- Query duration > 5 seconds
+- Connection pool exhaustion (>80% utilization)
+- CPU usage > 80%
+- Memory usage > 80%
+- `auth_rls_initplan` advisor warnings > 0
+
+## Migration Guidelines
+
+### Creating New RLS Policies
+
+1. **Use helper functions** - Never inline `auth.uid()` or `current_setting()`
+2. **Test with EXPLAIN ANALYZE** - Verify no InitPlan nodes
+3. **Load test** - Test with realistic data volumes
+4. **Run Supabase Advisors** - Verify no new warnings
+
+### Updating Existing Policies
+
+1. **Backup existing policies** before changes
+2. **Test in development** first
+3. **Monitor performance** after deployment
+4. **Rollback plan** ready if issues occur
+
+## Related Documentation
+
+- [Security Standard](./05-security-standard.md)
+- [RLS Policy Remediation Plan](../troubleshooting/rls-policy-remediation-plan-combined.md)
+- [Database Unhealthiness Diagnosis](../troubleshooting/database-unhealthiness-diagnosis.md)
+- [RBAC-RLS Integration Guide](../rbac/rbac-rls-integration.md)
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.186",
+  "version": "0.5.188",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {

package/src/__tests__/public-recipe-view.test.ts

@@ -0,0 +1,199 @@
+/**
+ * @file Public Recipe View Tests
+ * @package @jmruthers/pace-core
+ * @module RLS/Tests/PublicViews
+ * @since 0.5.181
+ * 
+ * Regression tests for the public_recipe_details view to verify:
+ * - Anonymous access works only when event.public_readable = true
+ * - View exposes only expected columns
+ * - Respects diet/meal filters
+ * - Performance is acceptable (< 500ms)
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { createClient, SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/database';
+
+const TEST_TIMEOUT = 5000;
+const PERFORMANCE_THRESHOLD = 500; // 500ms for public view queries
+
+// Check if we're using real test-db (via environment variables)
+const USE_REAL_DB = !!(process.env.SUPABASE_URL && process.env.VITE_SUPABASE_ANON_KEY);
+const TEST_SUPABASE_URL = process.env.SUPABASE_URL || process.env.VITE_SUPABASE_URL;
+const TEST_SUPABASE_ANON_KEY = process.env.TEST_SUPABASE_ANON_KEY || process.env.VITE_SUPABASE_ANON_KEY;
+const TEST_SUPABASE_SERVICE_ROLE_KEY = process.env.TEST_SUPABASE_SERVICE_ROLE_KEY;
+
+let anonClient: SupabaseClient<Database>;
+let authenticatedClient: SupabaseClient<Database>;
+
+const publicEvent = {
+  event_id: 'public-event-1',
+  event_name: 'Public Event',
+  public_readable: true,
+  is_visible: true,
+  organisation_id: 'org-1' as any
+};
+
+const privateEvent = {
+  event_id: 'private-event-1',
+  event_name: 'Private Event',
+  public_readable: false,
+  is_visible: true,
+  organisation_id: 'org-1' as any
+};
+
+describe.skipIf(!USE_REAL_DB || !TEST_SUPABASE_URL || !TEST_SUPABASE_ANON_KEY)('Public Recipe View - Anonymous Access', () => {
+  beforeEach(() => {
+    if (USE_REAL_DB && TEST_SUPABASE_URL && TEST_SUPABASE_ANON_KEY) {
+      anonClient = createClient<Database>(TEST_SUPABASE_URL, TEST_SUPABASE_ANON_KEY);
+      authenticatedClient = createClient<Database>(TEST_SUPABASE_URL, TEST_SUPABASE_SERVICE_ROLE_KEY || TEST_SUPABASE_ANON_KEY);
+    } else {
+      // This should not happen due to skipIf, but provide fallback
+      throw new Error('Test database credentials not available. Set SUPABASE_URL and VITE_SUPABASE_ANON_KEY environment variables.');
+    }
+  });
+
+  describe('Public Event Access', () => {
+    it('should allow anonymous access when event.public_readable = true', async () => {
+      const start = Date.now();
+      const { data, error } = await anonClient
+        .from('public_recipe_details')
+        .select('*')
+        .eq('event_id', publicEvent.event_id);
+      const duration = Date.now() - start;
+
+      expect(error).toBeNull();
+      expect(data).toBeDefined();
+      expect(duration).toBeLessThan(PERFORMANCE_THRESHOLD);
+    }, TEST_TIMEOUT);
+
+    it('should block anonymous access when event.public_readable = false', async () => {
+      const { data, error } = await anonClient
+        .from('public_recipe_details')
+        .select('*')
+        .eq('event_id', privateEvent.event_id);
+
+      // Should return empty (view filters by public_readable = true)
+      expect(data).toEqual([]);
+    }, TEST_TIMEOUT);
+
+    it('should block anonymous access when event.is_visible = false', async () => {
+      const { data, error } = await anonClient
+        .from('public_recipe_details')
+        .select('*')
+        .eq('event_id', 'hidden-event-1');
+
+      // Should return empty (view filters by is_visible = true)
+      expect(data).toEqual([]);
+    }, TEST_TIMEOUT);
+  });
+
+  describe('View Column Exposure', () => {
+    it('should expose only expected columns', async () => {
+      const { data, error } = await anonClient
+        .from('public_recipe_details')
+        .select('*')
+        .eq('event_id', publicEvent.event_id)
+        .limit(1)
+        .single();
+
+      expect(error).toBeNull();
+      if (data) {
+        // Verify expected columns exist
+        expect(data).toHaveProperty('dish_id');
+        expect(data).toHaveProperty('dish_name');
+        expect(data).toHaveProperty('dish_code');
+        expect(data).toHaveProperty('event_id');
+        expect(data).toHaveProperty('organisation_id');
+        
+        // Verify sensitive columns are NOT exposed
+        // (adjust based on actual view definition)
+        // expect(data).not.toHaveProperty('created_by');
+        // expect(data).not.toHaveProperty('updated_by');
+      }
+    }, TEST_TIMEOUT);
+  });
+
+  describe('Diet/Meal Filters', () => {
+    it('should filter by meal type', async () => {
+      const start = Date.now();
+      const { data, error } = await anonClient
+        .from('public_recipe_details')
+        .select('*')
+        .eq('event_id', publicEvent.event_id)
+        .eq('mealtype_name', 'Breakfast');
+      const duration = Date.now() - start;
+
+      expect(error).toBeNull();
+      expect(data).toBeDefined();
+      expect(duration).toBeLessThan(PERFORMANCE_THRESHOLD);
+    }, TEST_TIMEOUT);
+
+    it('should filter by diet requirements', async () => {
+      // This test would verify that diet filters work correctly
+      // Adjust based on actual view structure
+      const { data, error } = await anonClient
+        .from('public_recipe_details')
+        .select('*')
+        .eq('event_id', publicEvent.event_id)
+        .eq('dish_dietnote', 'Vegetarian');
+
+      expect(error).toBeNull();
+      expect(data).toBeDefined();
+    }, TEST_TIMEOUT);
+  });
+
+  describe('Performance', () => {
+    it('should complete view queries in < 500ms', async () => {
+      const start = Date.now();
+      await anonClient
+        .from('public_recipe_details')
+        .select('*')
+        .eq('event_id', publicEvent.event_id)
+        .limit(100);
+      const duration = Date.now() - start;
+
+      expect(duration).toBeLessThan(PERFORMANCE_THRESHOLD);
+    }, TEST_TIMEOUT);
+
+    it('should handle filtered queries efficiently', async () => {
+      const start = Date.now();
+      await anonClient
+        .from('public_recipe_details')
+        .select('*')
+        .eq('event_id', publicEvent.event_id)
+        .eq('mealtype_name', 'Breakfast')
+        .limit(50);
+      const duration = Date.now() - start;
+
+      expect(duration).toBeLessThan(PERFORMANCE_THRESHOLD);
+    }, TEST_TIMEOUT);
+  });
+});
+
+describe.skipIf(!USE_REAL_DB || !TEST_SUPABASE_URL || !TEST_SUPABASE_ANON_KEY)('Public Recipe View - Authenticated Access', () => {
+  it('should allow authenticated users to view public recipes', async () => {
+    const { data, error } = await authenticatedClient
+      .from('public_recipe_details')
+      .select('*')
+      .eq('event_id', publicEvent.event_id);
+
+    expect(error).toBeNull();
+    expect(data).toBeDefined();
+  }, TEST_TIMEOUT);
+
+  it('should allow authenticated users to view private events they have access to', async () => {
+    // Authenticated users with organisation access should be able to view
+    // recipes from events in their organisation, even if not public_readable
+    // (This depends on the view definition and RLS policies)
+    const { data, error } = await authenticatedClient
+      .from('public_recipe_details')
+      .select('*')
+      .eq('event_id', privateEvent.event_id);
+
+    // Result depends on RLS policies and view definition
+    expect(error).toBeNull();
+  }, TEST_TIMEOUT);
+});
+