@jmruthers/pace-core 0.6.5 → 0.6.7

package/docs/standards/{07-rbac-and-rls-standard.md → 6-security-rbac-standards.md}

@@ -1,15 +1,13 @@
----
-lastUpdated: 2025-01-02T00:00:00+11:00
-version: 0.5.182
-reviewedBy: rls-audit-and-fixes
----
+# Security & RBAC Standards
 
-# RBAC and RLS Standard
+**🤖 Cursor Rule**: See [06-security-rbac.mdc](../../cursor-rules/06-security-rbac.mdc) for AI-optimized directives that automatically enforce RBAC contract compliance (ESLint-enforced).
 
 ## Purpose
 
 Define standards for Row-Level Security (RLS) policies and Role-Based Access Control (RBAC) integration to ensure security, performance, and maintainability.
 
+**Note:** General performance optimization patterns (React, caching, bundle size) are covered in [Operations Standards](./9-operations-standards.md). This document focuses on RLS-specific performance requirements.
+
 ## Principles
 
 - **Performance First**: All RLS policies must use optimized helper functions
@@ -101,16 +99,36 @@ FOR SELECT USING (
 );
 ```
 
+## Helper Selection Quick Guide
+
+| Scenario | Helper(s) to use | Notes |
+|----------|------------------|-------|
+| Organisation-scoped rows | `check_user_organisation_access(organisation_id)` | Always check `organisation_id IS NOT NULL` first. |
+| Page-permission checks | `check_rbac_permission_with_context(..., get_app_id('APP'))` | Use the wrapper instead of inline `rbac_check_permission_simplified` + `auth.uid()`. |
+| Event-scoped rows | `check_user_event_access(event_id)` | Combine with permission wrapper when pages require it. |
+| Public rows | `check_public_event_access(event_id)` or `is_public = true` | Keep anonymous and authenticated policies separate. |
+| User-owned rows | `get_effective_user_id() = user_id` | Use when `organisation_id IS NULL`. |
+| Service role bypass | `is_service_role()` | Put first in OR chains; use sparingly. |
+
+## RLS Helper Requirements (enforced)
+
+- Helper functions **must** be `STABLE`, `SECURITY DEFINER`, and `SET search_path TO public`.
+- **Never** inline `auth.uid()`, `auth.role()`, or `current_setting()` inside policies.
+- Use `get_app_id()` for app UUIDs (do not hardcode UUIDs or call legacy getters).
+- Avoid subqueries inside policies; move lookups into helpers.
+
 ## Standard Helper Functions
 
 ### Core Helper Functions
 
 These functions are available for use in RLS policies:
 
-#### `is_super_admin()`
+#### `is_super_admin(p_user_id UUID)`
 - **Returns**: `boolean`
-- **Purpose**: Checks if current user is a super admin
-- **Usage**: `is_super_admin()`
+- **Purpose**: Checks if the specified user is a super admin
+- **Usage**: `is_super_admin(safe_get_user_id_for_rls())`
+- **⚠️ CRITICAL**: Always pass an explicit user ID parameter. Never call without parameters.
+- **Security**: This function requires an explicit parameter to prevent fallback strategy vulnerabilities. Use `safe_get_user_id_for_rls()` to get the user ID in RLS policies.
 
 #### `check_user_organisation_access(p_organisation_id UUID)`
 - **Returns**: `boolean`
@@ -212,7 +230,7 @@ FOR SELECT TO authenticated
 USING (
   organisation_id IS NOT NULL
   AND (
-    is_super_admin()
+    is_super_admin(safe_get_user_id_for_rls())
     OR check_user_organisation_access(organisation_id)
   )
 );
@@ -223,6 +241,7 @@ USING (
 **Notes:**
 - Always check `organisation_id IS NOT NULL` first
 - Super admin check comes before organisation access check
+- **MUST** use `is_super_admin(safe_get_user_id_for_rls())` with explicit parameter
 - Use `check_user_organisation_access()` for basic membership checks
 
 ### RBAC Permission-Based Policy
@@ -236,7 +255,7 @@ FOR SELECT TO authenticated
 USING (
   organisation_id IS NOT NULL
   AND (
-    is_super_admin()
+    is_super_admin(safe_get_user_id_for_rls())
     OR check_rbac_permission_with_context(
       'read:page.table_name',
       'table_name',
@@ -258,7 +277,7 @@ FOR SELECT TO authenticated
 USING (
   organisation_id IS NOT NULL
   AND (
-    is_super_admin()
+    is_super_admin(safe_get_user_id_for_rls())
     OR check_rbac_permission_with_context(
       'read:page.table_name',
       'table_name',
@@ -275,7 +294,7 @@ FOR INSERT TO authenticated
 WITH CHECK (
   organisation_id IS NOT NULL
   AND (
-    is_super_admin()
+    is_super_admin(safe_get_user_id_for_rls())
     OR check_rbac_permission_with_context(
       'create:page.table_name',
       'table_name',
@@ -292,7 +311,7 @@ FOR UPDATE TO authenticated
 USING (
   organisation_id IS NOT NULL
   AND (
-    is_super_admin()
+    is_super_admin(safe_get_user_id_for_rls())
     OR check_rbac_permission_with_context(
       'update:page.table_name',
       'table_name',
@@ -305,7 +324,7 @@ USING (
 WITH CHECK (
   organisation_id IS NOT NULL
   AND (
-    is_super_admin()
+    is_super_admin(safe_get_user_id_for_rls())
     OR check_rbac_permission_with_context(
       'update:page.table_name',
       'table_name',
@@ -322,7 +341,7 @@ FOR DELETE TO authenticated
 USING (
   organisation_id IS NOT NULL
   AND (
-    is_super_admin()
+    is_super_admin(safe_get_user_id_for_rls())
     OR check_rbac_permission_with_context(
       'delete:page.table_name',
       'table_name',
@@ -351,7 +370,7 @@ FOR SELECT TO authenticated
 USING (
   organisation_id IS NOT NULL
   AND (
-    is_super_admin()
+    is_super_admin(safe_get_user_id_for_rls())
     OR check_user_event_access(event_id)
   )
 );
@@ -387,7 +406,7 @@ USING (
     organisation_id IS NOT NULL
     AND is_authenticated_user()
     AND (
-      is_super_admin()
+      is_super_admin(safe_get_user_id_for_rls())
       OR check_user_organisation_access(organisation_id)
     )
   )
@@ -403,6 +422,52 @@ USING (
 
 **Example:** `file_references`, `pace_address` (can be either organisation or user-scoped)
 
+**Real-World Example: File References Table**
+
+```sql
+-- Real-world example: file_references table supports both organisation and user-scoped files
+CREATE POLICY "rbac_select_file_references" ON file_references
+FOR SELECT
+USING (
+  -- Service role can access all files (for system operations)
+  is_service_role()
+  OR
+  -- Organisation-scoped files (shared within organisation)
+  (
+    organisation_id IS NOT NULL
+    AND is_authenticated_user()
+    AND (
+      is_super_admin(safe_get_user_id_for_rls())
+      OR check_user_organisation_access(organisation_id)
+    )
+  )
+  OR
+  -- User-scoped files (personal files)
+  (
+    organisation_id IS NULL
+    AND is_authenticated_user()
+    AND get_effective_user_id() = user_id
+  )
+);
+
+-- INSERT policy: Users can upload files to their organisation or personal storage
+CREATE POLICY "rbac_insert_file_references" ON file_references
+FOR INSERT TO authenticated
+WITH CHECK (
+  -- Organisation-scoped: Must have organisation access
+  (
+    organisation_id IS NOT NULL
+    AND check_user_organisation_access(organisation_id)
+  )
+  OR
+  -- User-scoped: Must be own user_id
+  (
+    organisation_id IS NULL
+    AND get_effective_user_id() = user_id
+  )
+);
+```
+
 ### Service Role Policy
 
 **Use Case:** Allow service_role to bypass RLS for system operations.
@@ -453,6 +518,66 @@ USING (
 
 **Example:** `event` (public events), `forms` (published forms)
 
+**Real-World Example: Public Event Registration**
+
+```sql
+-- Real-world example: Events table with public registration
+-- Public users can view and register for public events
+-- Authenticated users can view all events in their organisation
+
+-- Public access: Anonymous users can view public events
+CREATE POLICY "public_select_events" ON events
+FOR SELECT TO anon
+USING (
+  is_public = true
+  AND organisation_id IS NOT NULL
+  AND status = 'published'
+);
+
+-- Authenticated access: Users can view events in their organisation
+CREATE POLICY "rbac_select_events" ON events
+FOR SELECT TO authenticated
+USING (
+  -- Public events (anyone can see)
+  (is_public = true AND organisation_id IS NOT NULL)
+  OR
+  -- Organisation events (members can see)
+  (
+    organisation_id IS NOT NULL
+    AND (
+      is_super_admin(safe_get_user_id_for_rls())
+      OR check_user_organisation_access(organisation_id)
+    )
+  )
+);
+
+-- Public registration: Anonymous users can create registrations for public events
+CREATE POLICY "public_insert_event_registrations" ON event_registrations
+FOR INSERT TO anon
+WITH CHECK (
+  -- Only for public events
+  event_id IN (
+    SELECT id FROM events
+    WHERE is_public = true AND status = 'published'
+  )
+);
+
+-- Authenticated registration: Users can register for events in their organisation
+CREATE POLICY "rbac_insert_event_registrations" ON event_registrations
+FOR INSERT TO authenticated
+WITH CHECK (
+  -- Must have access to the event's organisation
+  event_id IN (
+    SELECT id FROM events
+    WHERE organisation_id IS NOT NULL
+    AND (
+      is_super_admin(safe_get_user_id_for_rls())
+      OR check_user_organisation_access(organisation_id)
+    )
+  )
+);
+```
+
 **Combined Public + Authenticated Pattern:**
 ```sql
 -- Public access
@@ -471,7 +596,7 @@ USING (
   OR (
     organisation_id IS NOT NULL
     AND (
-      is_super_admin()
+      is_super_admin(safe_get_user_id_for_rls())
       OR check_user_organisation_access(organisation_id)
     )
   )
@@ -496,7 +621,7 @@ USING (
     is_authenticated_user()
     AND organisation_id IS NOT NULL
     AND (
-      is_super_admin()
+      is_super_admin(safe_get_user_id_for_rls())
       OR check_user_organisation_access(organisation_id)
     )
   )
@@ -542,7 +667,7 @@ USING (is_authenticated_user());
 ```sql
 CREATE POLICY "rbac_select_table_name" ON table_name
 FOR SELECT TO authenticated
-USING (is_super_admin());
+USING (is_super_admin(safe_get_user_id_for_rls()));
 ```
 
 **Example:** `rbac_global_roles`, `rbac_policy_configs`
@@ -552,20 +677,20 @@ USING (is_super_admin());
 -- All operations restricted to super admin
 CREATE POLICY "rbac_select_table_name" ON table_name
 FOR SELECT TO authenticated
-USING (is_super_admin());
+USING (is_super_admin(safe_get_user_id_for_rls()));
 
 CREATE POLICY "rbac_insert_table_name" ON table_name
 FOR INSERT TO authenticated
-WITH CHECK (is_super_admin());
+WITH CHECK (is_super_admin(safe_get_user_id_for_rls()));
 
 CREATE POLICY "rbac_update_table_name" ON table_name
 FOR UPDATE TO authenticated
-USING (is_super_admin())
-WITH CHECK (is_super_admin());
+USING (is_super_admin(safe_get_user_id_for_rls()))
+WITH CHECK (is_super_admin(safe_get_user_id_for_rls()));
 
 CREATE POLICY "rbac_delete_table_name" ON table_name
 FOR DELETE TO authenticated
-USING (is_super_admin());
+USING (is_super_admin(safe_get_user_id_for_rls()));
 ```
 
 ### Common Patterns Summary
@@ -579,19 +704,122 @@ USING (is_super_admin());
 | Service Role | System operations | `is_service_role()` |
 | Public Access | Anonymous users | `check_public_event_access()` or `is_public` flag |
 | Read-Only Types | Reference tables | `is_authenticated_user()` |
-| Super Admin Only | Admin-only tables | `is_super_admin()` |
+| Super Admin Only | Admin-only tables | `is_super_admin(safe_get_user_id_for_rls())` |
 
 ### Policy Best Practices
 
 1. **Always use helper functions** - Never inline `auth.uid()`, `auth.role()`, or `current_setting()`
 2. **Check NULL first** - Always check `organisation_id IS NOT NULL` before using it
-3. **Super admin first** - Super admin checks should come before other checks in OR conditions
+3. **Super admin first** - Super admin checks should come before other checks in OR conditions. **MUST** use `is_super_admin(safe_get_user_id_for_rls())` with explicit parameter - never call without parameters.
 4. **Service role first** - Service role checks should be the first condition in multi-condition policies
 5. **Consistent naming** - Follow the naming convention: `rbac_{operation}_{table}_{scope}`
 6. **Document exceptions** - If a policy deviates from standard patterns, add a comment explaining why
 7. **Test thoroughly** - Test with different user roles (super_admin, org_admin, member, anon)
 8. **Avoid `true OR ...`** - Never use `true OR ...` conditions as they bypass all security checks
 
+## Edge Functions and Serverless Functions
+
+**Edge Functions (Deno serverless functions) MUST use pace-core's `isPermitted()` API function.** Edge Functions cannot use React hooks, but pace-core provides programmatic APIs that work outside React.
+
+### ✅ CORRECT - Edge Function Pattern
+
+```typescript
+// supabase/functions/my-function/index.ts
+import { createClient } from 'jsr:@supabase/supabase-js@2';
+import { setupRBAC, isPermitted } from 'npm:@jmruthers/pace-core@^0.6.0/rbac';
+
+Deno.serve(async (req: Request) => {
+  // 1. Create Supabase client from request headers
+  const authHeader = req.headers.get('Authorization');
+  if (!authHeader) {
+    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
+  }
+
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL') ?? '',
+    Deno.env.get('SUPABASE_ANON_KEY') ?? '',
+    {
+      global: {
+        headers: { Authorization: authHeader },
+      },
+    }
+  );
+
+  // 2. Get user from session
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) {
+    return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
+  }
+
+  // 3. Setup RBAC (required before using isPermitted)
+  setupRBAC(supabase);
+
+  // 4. Extract organisation context from request
+  const organisationId = req.headers.get('x-organisation-id') || 
+                         (await req.json()).organisationId;
+
+  if (!organisationId) {
+    return new Response(JSON.stringify({ error: 'Organisation context required' }), { status: 400 });
+  }
+
+  // 5. Check permission using pace-core API
+  const hasPermission = await isPermitted({
+    userId: user.id,
+    scope: { organisationId },
+    permission: 'read:dashboard',
+    pageId: 'dashboard'
+  });
+
+  if (!hasPermission) {
+    return new Response(JSON.stringify({ error: 'Permission denied' }), { status: 403 });
+  }
+
+  // 6. Proceed with function logic
+  return new Response(JSON.stringify({ success: true }));
+});
+```
+
+### ❌ FORBIDDEN - Custom RBAC Helper in Edge Functions
+
+**Creating custom RBAC helper functions in Edge Functions is FORBIDDEN.** pace-core provides all necessary APIs.
+
+```typescript
+// ❌ FORBIDDEN - Custom RBAC helper
+// supabase/functions/_shared/rbac.ts
+export async function checkPermission(userId: string, permission: string) {
+  // Custom logic that bypasses pace-core
+  const { data } = await supabase.rpc('rbac_check_permission_simplified', {
+    p_user_id: userId,
+    p_permission: permission
+  });
+  return data;
+}
+```
+
+### Why No Exceptions
+
+- pace-core provides `isPermitted()` API that works outside React
+- `setupRBAC()` initializes the engine with a Supabase client
+- No custom helpers needed - use pace-core APIs directly
+- Custom helpers bypass security validation, caching, and audit logging
+
+### Edge Function Requirements
+
+1. **MUST** call `setupRBAC(supabase)` before using `isPermitted()`
+2. **MUST** extract `userId` from Supabase auth session
+3. **MUST** extract `organisationId` from request (headers, body, or query params)
+4. **MUST** use `isPermitted()` with complete `PermissionCheck` input
+5. **MUST NOT** create custom RBAC helper functions
+6. **MUST NOT** call `rbac_check_permission_simplified` RPC directly
+
+## Security Baseline
+
+- Never bypass RLS; validate all inputs and sanitize logs (no tokens/PII).
+- Use safe, user-friendly error messaging.
+- Prefer pace-core security helpers and secure clients (`useSecureSupabase`, RBAC helpers) over custom implementations.
+- Monitor RLS performance (avoid subqueries/InitPlan); keep helpers `STABLE SECURITY DEFINER` with `SET search_path TO public`.
+- **Edge Functions MUST use pace-core `isPermitted()` API - no exceptions allowed.**
+
 ### Common Pitfalls to Avoid
 
 **❌ DON'T:**
@@ -648,29 +876,23 @@ Tables are assigned to specific apps for RBAC permission checking:
 
 ### 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**:
+1. **Run Supabase Advisors**:
    ```bash
    supabase advisors performance
    supabase advisors security
    ```
 
-3. **Run Database Tests**:
+2. **Run Database Tests**:
    ```bash
    timeout 120 npm run test:db
    ```
 
-4. **Run Application Tests**:
+3. **Run Application Tests**:
    ```bash
    timeout 60 npm run test
    ```
 
-5. **Verify Performance**:
+4. **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
@@ -686,32 +908,9 @@ Tables are assigned to specific apps for RBAC permission checking:
 
 ### 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 Supabase advisors regularly** to catch any rogue policies that violate standards:
 
-Run weekly:
 ```bash
-# RLS compliance audit
-npm run audit:rls
-
 # Performance advisors
 supabase advisors performance
 
@@ -772,8 +971,12 @@ date +"%Y%m%d%H%M%S"
 
 ## 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)
+- [Standards Overview](./0-standards-overview.md) - Standards system overview
+- [pace-core Compliance](./1-pace-core-compliance-standards.md) - Secure Supabase client usage
+- [Operations](./9-operations-standards.md) - General performance patterns (React, caching, etc.)
+
+---
 
+**Last Updated:** 2025-01-28  
+**Version:** 2.0.0  
+**Applies to:** All pace-core and consuming apps