@jmruthers/pace-core 0.6.4 → 0.6.6

package/docs/standards/{07-rbac-and-rls-standard.md → 09-rbac-compliance.md}

@@ -1,11 +1,13 @@
 ---
-lastUpdated: 2025-01-02T00:00:00+11:00
+lastUpdated: 2025-01-28T00:00:00+11:00
 version: 0.5.182
 reviewedBy: rls-audit-and-fixes
 ---
 
 # RBAC and RLS Standard
 
+**🤖 Cursor Rule**: See [09-rbac-compliance.mdc](../../cursor-rules/09-rbac-compliance.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.
@@ -101,16 +103,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 +234,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 +245,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 +259,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 +281,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 +298,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 +315,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 +328,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 +345,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 +374,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 +410,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)
     )
   )
@@ -542,7 +565,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 +575,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 +602,121 @@ 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 (aligns with Security Standard)
+- 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,13 +773,7 @@ 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
@@ -686,32 +805,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:
+**Run Supabase advisors 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
 
@@ -772,8 +868,7 @@ date +"%Y%m%d%H%M%S"
 
 ## Related Documentation
 
-- [Security Standard](./05-security-standard.md)
+- Security baseline (see section above)
 - [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)
-