@jmruthers/pace-core 0.5.189 → 0.5.190

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

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-01-28T00:00:00+11:00
-version: 0.5.181
-reviewedBy: database-performance-audit
+lastUpdated: 2025-01-02T00:00:00+11:00
+version: 0.5.182
+reviewedBy: rls-audit-and-fixes
 ---
 
 # RBAC and RLS Standard
@@ -138,6 +138,24 @@ These functions are available for use in RLS policies:
 - **Purpose**: Returns the current organisation context from the session
 - **Usage**: `get_organisation_context()`
 
+#### `is_authenticated_user()`
+- **Returns**: `boolean`
+- **Purpose**: Checks if the current user is authenticated (not anonymous)
+- **Usage**: `is_authenticated_user()`
+- **Note**: Use this instead of `(SELECT auth.role()) = 'authenticated'` in policies
+
+#### `is_service_role()`
+- **Returns**: `boolean`
+- **Purpose**: Checks if the current user has service_role
+- **Usage**: `is_service_role()`
+- **Note**: Use this instead of `(SELECT auth.role()) = 'service_role'` in policies
+
+#### `get_effective_user_id()`
+- **Returns**: `UUID`
+- **Purpose**: Returns the current user ID (auth.uid()) in a STABLE function
+- **Usage**: `get_effective_user_id()`
+- **Note**: Use this instead of `(SELECT auth.uid())` or inline `auth.uid()` in policies
+
 ### Event Helper Functions
 
 #### `get_unit_event_id(p_unit_id TEXT)`
@@ -170,8 +188,24 @@ These functions are available for use in RLS policies:
 
 ## RLS Policy Patterns
 
+This section documents the standard RLS policy patterns used throughout the codebase. All patterns follow the principles of using helper functions, enforcing security by default, and maintaining consistent structure.
+
+### Policy Naming Convention
+
+Policies follow this naming pattern:
+- `rbac_{operation}_{table_name}_{scope}` for authenticated policies
+- `{operation}_{table_name}_{scope}` for public/anonymous policies
+
+Examples:
+- `rbac_select_cake_dish_authenticated` - Authenticated SELECT policy
+- `event_public_select` - Public SELECT policy for events
+- `rbac_insert_file_references` - INSERT policy (no scope suffix if only one)
+
 ### Standard Organisation-Scoped Policy
 
+**Use Case:** Tables where rows belong to an organisation and access is controlled by organisation membership.
+
+**Pattern:**
 ```sql
 CREATE POLICY "rbac_select_table_name" ON table_name
 FOR SELECT TO authenticated
@@ -184,8 +218,18 @@ USING (
 );
 ```
 
-### Standard Event-Scoped Policy
+**Example:** `organisations`, `organisation_app_access`
+
+**Notes:**
+- Always check `organisation_id IS NOT NULL` first
+- Super admin check comes before organisation access check
+- Use `check_user_organisation_access()` for basic membership checks
 
+### RBAC Permission-Based Policy
+
+**Use Case:** Tables that require specific page-level permissions (most common pattern for app tables).
+
+**Pattern:**
 ```sql
 CREATE POLICY "rbac_select_table_name" ON table_name
 FOR SELECT TO authenticated
@@ -193,14 +237,22 @@ USING (
   organisation_id IS NOT NULL
   AND (
     is_super_admin()
-    OR check_user_event_access(event_id)
+    OR check_rbac_permission_with_context(
+      'read:page.table_name',
+      'table_name',
+      organisation_id,
+      event_id,  -- NULL if not event-scoped
+      get_app_id('APP_NAME')
+    )
   )
 );
 ```
 
-### RBAC Permission-Based Policy
+**Example:** `cake_dish`, `cake_item`, `base_application`
 
+**Full CRUD Example:**
 ```sql
+-- SELECT
 CREATE POLICY "rbac_select_table_name" ON table_name
 FOR SELECT TO authenticated
 USING (
@@ -216,12 +268,171 @@ USING (
     )
   )
 );
+
+-- INSERT
+CREATE POLICY "rbac_insert_table_name" ON table_name
+FOR INSERT TO authenticated
+WITH CHECK (
+  organisation_id IS NOT NULL
+  AND (
+    is_super_admin()
+    OR check_rbac_permission_with_context(
+      'create:page.table_name',
+      'table_name',
+      organisation_id,
+      event_id,
+      get_app_id('APP_NAME')
+    )
+  )
+);
+
+-- UPDATE
+CREATE POLICY "rbac_update_table_name" ON table_name
+FOR UPDATE TO authenticated
+USING (
+  organisation_id IS NOT NULL
+  AND (
+    is_super_admin()
+    OR check_rbac_permission_with_context(
+      'update:page.table_name',
+      'table_name',
+      organisation_id,
+      event_id,
+      get_app_id('APP_NAME')
+    )
+  )
+)
+WITH CHECK (
+  organisation_id IS NOT NULL
+  AND (
+    is_super_admin()
+    OR check_rbac_permission_with_context(
+      'update:page.table_name',
+      'table_name',
+      organisation_id,
+      event_id,
+      get_app_id('APP_NAME')
+    )
+  )
+);
+
+-- DELETE
+CREATE POLICY "rbac_delete_table_name" ON table_name
+FOR DELETE TO authenticated
+USING (
+  organisation_id IS NOT NULL
+  AND (
+    is_super_admin()
+    OR check_rbac_permission_with_context(
+      'delete:page.table_name',
+      'table_name',
+      organisation_id,
+      event_id,
+      get_app_id('APP_NAME')
+    )
+  )
+);
+```
+
+**Notes:**
+- 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
+- Permission format: `{operation}:page.{page_name}` (e.g., `'read:page.dishes'`, `'create:page.items'`)
+- Use `get_app_id('APP_NAME')` to get the app UUID (never hardcode)
+
+### Standard Event-Scoped Policy
+
+**Use Case:** Tables where rows belong to an event and access is controlled by event membership.
+
+**Pattern:**
+```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)
+  )
+);
+```
+
+**Example:** Event-specific data that doesn't require page-level permissions
+
+**Note:** For event-scoped data that also requires page permissions, combine with RBAC permission pattern.
+
+### User-Scoped Data Policy
+
+**Use Case:** Tables where rows belong to individual users (organisation_id IS NULL) and users can only access their own data.
+
+**Pattern:**
+```sql
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  organisation_id IS NULL
+  AND get_effective_user_id() = user_id
+);
+```
+
+**Example:** User profile data, user-scoped file references
+
+**Multi-Condition Pattern (Organisation OR User-Scoped):**
+```sql
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT
+USING (
+  -- Organisation-scoped access
+  (
+    organisation_id IS NOT NULL
+    AND is_authenticated_user()
+    AND (
+      is_super_admin()
+      OR check_user_organisation_access(organisation_id)
+    )
+  )
+  OR
+  -- User-scoped access
+  (
+    organisation_id IS NULL
+    AND is_authenticated_user()
+    AND get_effective_user_id() = user_id
+  )
+);
+```
+
+**Example:** `file_references`, `pace_address` (can be either organisation or user-scoped)
+
+### Service Role Policy
+
+**Use Case:** Allow service_role to bypass RLS for system operations.
+
+**Pattern:**
+```sql
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT
+USING (
+  is_service_role()
+  OR (
+    -- Other conditions for authenticated users
+    is_authenticated_user()
+    AND ...
+  )
+);
 ```
 
-**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.
+**Example:** `file_references` (service_role can access all files for system operations)
+
+**Notes:**
+- Service role check should be first in OR conditions
+- Service role bypasses all other security checks
+- Use sparingly - only for tables that need system-level access
 
 ### Public Access Policy
 
+**Use Case:** Tables where some data should be publicly accessible (anonymous users).
+
+**Pattern:**
 ```sql
 CREATE POLICY "public_select_table_name" ON table_name
 FOR SELECT TO anon
@@ -230,6 +441,195 @@ USING (
 );
 ```
 
+**Alternative Pattern (Simple Public Flag):**
+```sql
+CREATE POLICY "public_select_table_name" ON table_name
+FOR SELECT TO anon
+USING (
+  is_public = true
+  AND organisation_id IS NOT NULL
+);
+```
+
+**Example:** `event` (public events), `forms` (published forms)
+
+**Combined Public + Authenticated Pattern:**
+```sql
+-- Public access
+CREATE POLICY "public_select_table_name" ON table_name
+FOR SELECT TO anon
+USING (
+  is_public = true
+  AND organisation_id IS NOT NULL
+);
+
+-- Authenticated access (with additional permissions)
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  (is_public = true AND organisation_id IS NOT NULL)
+  OR (
+    organisation_id IS NOT NULL
+    AND (
+      is_super_admin()
+      OR check_user_organisation_access(organisation_id)
+    )
+  )
+);
+```
+
+### Complex Multi-Condition Policy
+
+**Use Case:** Tables that need multiple access patterns (service role, public, organisation-scoped, user-scoped).
+
+**Pattern:**
+```sql
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT
+USING (
+  -- Service role can access all
+  is_service_role()
+  -- Public access
+  OR (is_public = true)
+  -- Organisation-scoped authenticated access
+  OR (
+    is_authenticated_user()
+    AND organisation_id IS NOT NULL
+    AND (
+      is_super_admin()
+      OR check_user_organisation_access(organisation_id)
+    )
+  )
+  -- User-scoped authenticated access
+  OR (
+    is_authenticated_user()
+    AND organisation_id IS NULL
+    AND get_effective_user_id() = user_id
+  )
+);
+```
+
+**Example:** `file_references` (supports all access patterns)
+
+**Notes:**
+- Order matters: most permissive first (service_role), then public, then authenticated
+- Each condition should be mutually exclusive where possible
+- Use helper functions for all checks (never inline auth calls)
+
+### Read-Only Type Table Policy
+
+**Use Case:** Reference/lookup tables that authenticated users should be able to read but not modify.
+
+**Pattern:**
+```sql
+CREATE POLICY "read_table_name" ON table_name
+FOR SELECT
+USING (is_authenticated_user());
+```
+
+**Example:** `pace_gender_type`, `pace_phone_type`, `medi_condition_type`
+
+**Notes:**
+- No INSERT/UPDATE/DELETE policies needed
+- Super simple - just check if user is authenticated
+- These tables typically don't have organisation_id
+
+### Super Admin Only Policy
+
+**Use Case:** Tables that only super admins should access.
+
+**Pattern:**
+```sql
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (is_super_admin());
+```
+
+**Example:** `rbac_global_roles`, `rbac_policy_configs`
+
+**Full CRUD Example:**
+```sql
+-- All operations restricted to super admin
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (is_super_admin());
+
+CREATE POLICY "rbac_insert_table_name" ON table_name
+FOR INSERT TO authenticated
+WITH CHECK (is_super_admin());
+
+CREATE POLICY "rbac_update_table_name" ON table_name
+FOR UPDATE TO authenticated
+USING (is_super_admin())
+WITH CHECK (is_super_admin());
+
+CREATE POLICY "rbac_delete_table_name" ON table_name
+FOR DELETE TO authenticated
+USING (is_super_admin());
+```
+
+### Common Patterns Summary
+
+| Pattern | Use Case | Key Helper Functions |
+|---------|----------|---------------------|
+| Organisation-Scoped | Basic org membership | `check_user_organisation_access()` |
+| RBAC Permission-Based | Page-level permissions | `check_rbac_permission_with_context()`, `get_app_id()` |
+| Event-Scoped | Event membership | `check_user_event_access()` |
+| User-Scoped | Personal data | `get_effective_user_id()` |
+| 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()` |
+
+### 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
+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
+
+### Common Pitfalls to Avoid
+
+**❌ DON'T:**
+```sql
+-- Inline auth calls
+USING (user_id = auth.uid())
+
+-- Security bypass
+USING (true OR check_user_organisation_access(organisation_id))
+
+-- Missing NULL check
+USING (check_user_organisation_access(organisation_id))
+
+-- Direct current_setting
+USING (organisation_id = current_setting('app.organisation_id')::UUID)
+
+-- Public policy without proper checks
+USING (true)  -- Allows anyone!
+```
+
+**✅ DO:**
+```sql
+-- Use helper functions
+USING (get_effective_user_id() = user_id)
+
+-- Proper security checks
+USING (check_user_organisation_access(organisation_id))
+
+-- NULL check first
+USING (organisation_id IS NOT NULL AND check_user_organisation_access(organisation_id))
+
+-- Use helper function
+USING (organisation_id = get_organisation_context())
+
+-- Proper public policy
+USING (is_public = true AND organisation_id IS NOT NULL)
+```
+
 ## App Ownership
 
 Tables are assigned to specific apps for RBAC permission checking:
@@ -333,6 +733,29 @@ Monitor:
 
 ## Migration Guidelines
 
+### Migration Filename Requirements
+
+**CRITICAL**: Migration filenames **MUST** use real timestamps, not guessed or placeholder dates.
+
+1. **Always use the current timestamp** when creating migration files
+2. **Format**: `YYYYMMDDHHMMSS_descriptive_name.sql`
+3. **How to get the timestamp**:
+   ```bash
+   date +"%Y%m%d%H%M%S"
+   ```
+4. **Never guess or use placeholder dates** - This causes migration ordering issues and conflicts
+5. **Verify the timestamp is after the latest migration** in `supabase/migrations/`
+
+**Example**:
+```bash
+# Get current timestamp
+date +"%Y%m%d%H%M%S"
+# Output: 20251201124800
+
+# Use it in filename
+20251201124800_allow_medi_action_plan_null_condition_id.sql
+```
+
 ### Creating New RLS Policies
 
 1. **Use helper functions** - Never inline `auth.uid()` or `current_setting()`

package/docs/troubleshooting/README.md

@@ -413,7 +413,7 @@ npm run build -- --debug
 // Verify environment variables
 console.log('Environment:', {
   supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
-  supabaseKey: import.meta.env.VITE_SUPABASE_ANON_KEY,
+  supabaseKey: import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY,
   appName: import.meta.env.VITE_APP_NAME,
 });
 ```
@@ -431,7 +431,7 @@ console.log('Environment:', {
 # Example deployment config
 env:
   VITE_SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
-  VITE_SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
+  VITE_SUPABASE_PUBLISHABLE_KEY: ${{ secrets.SUPABASE_PUBLISHABLE_KEY }}
   VITE_APP_NAME: "My App"
 ```
 

package/docs/troubleshooting/migration.md

@@ -403,7 +403,7 @@ VITE_DEBUG_MODE=true
 
 # New environment variables
 VITE_SUPABASE_URL=https://your-project.supabase.co
-VITE_SUPABASE_ANON_KEY=your-anon-key
+VITE_SUPABASE_PUBLISHABLE_KEY=your-publishable-key
 VITE_APP_ENV=development
 VITE_DEBUG=false
 
@@ -420,7 +420,7 @@ cp .env .env.backup
 cat > .env << EOF
 # Supabase Configuration
 VITE_SUPABASE_URL=${VITE_SUPABASE_URL:-https://your-project.supabase.co}
-VITE_SUPABASE_ANON_KEY=${VITE_SUPABASE_ANON_KEY:-your-anon-key}
+VITE_SUPABASE_PUBLISHABLE_KEY=${VITE_SUPABASE_PUBLISHABLE_KEY:-your-publishable-key}
 
 # Application Configuration
 VITE_APP_ENV=${VITE_APP_ENV:-development}
@@ -706,7 +706,7 @@ export class MigrationValidation {
   static validateConfiguration(config: any) {
     const required = [
       'VITE_SUPABASE_URL',
-      'VITE_SUPABASE_ANON_KEY',
+      'VITE_SUPABASE_PUBLISHABLE_KEY',
     ];
     
     const warnings = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.189",
+  "version": "0.5.190",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {
@@ -155,7 +155,6 @@
     "clean": "rimraf dist",
     "_comment_test": "Test suite with various configurations",
     "test": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=128\" vitest run --config ../../vitest.config.ts",
-    "test:memory-optimized": "node ../../scripts/run-tests-memory-optimized.js",
     "test:watch": "vitest --watch --config ../../vitest.config.ts",
     "test:coverage": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=128\" vitest run --coverage --config ../../vitest.config.ts --reporter=dot",
     "test:ui": "vitest --ui --config ../../vitest.config.ts",
@@ -200,7 +199,6 @@
     "@radix-ui/react-checkbox": "^1.0.0",
     "@radix-ui/react-dialog": "^1.0.0",
     "@radix-ui/react-label": "^2.0.0",
-    "@radix-ui/react-progress": "^1.0.0",
     "@radix-ui/react-slot": "^1.0.0",
     "@radix-ui/react-switch": "^1.1.0",
     "@radix-ui/react-tabs": "^1.0.0",

package/scripts/check-pace-core-compliance.cjs

@@ -567,7 +567,7 @@ function scanFile(filePath, manifest) {
   // - Using in createClient
   // - Comments/documentation
   const supabaseUrlPattern = /(SUPABASE_URL|VITE_SUPABASE_URL|NEXT_PUBLIC_SUPABASE_URL|REACT_APP_SUPABASE_URL)/g;
-  const supabaseKeyPattern = /(SUPABASE_ANON_KEY|VITE_SUPABASE_ANON_KEY|NEXT_PUBLIC_SUPABASE_ANON_KEY|REACT_APP_SUPABASE_ANON_KEY)/g;
+  const supabaseKeyPattern = /(SUPABASE_ANON_KEY|VITE_SUPABASE_PUBLISHABLE_KEY|NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY|REACT_APP_SUPABASE_PUBLISHABLE_KEY)/g;
   const urlMatches = content.match(supabaseUrlPattern);
   const keyMatches = content.match(supabaseKeyPattern);
   

package/scripts/check-pace-core-compliance.js

@@ -213,7 +213,7 @@ function scanFile(filePath, manifest) {
   
   // Check for Supabase URL/key configuration in multiple places
   const supabaseUrlPattern = /(SUPABASE_URL|VITE_SUPABASE_URL|NEXT_PUBLIC_SUPABASE_URL|REACT_APP_SUPABASE_URL)/g;
-  const supabaseKeyPattern = /(SUPABASE_ANON_KEY|VITE_SUPABASE_ANON_KEY|NEXT_PUBLIC_SUPABASE_ANON_KEY|REACT_APP_SUPABASE_ANON_KEY)/g;
+  const supabaseKeyPattern = /(SUPABASE_ANON_KEY|VITE_SUPABASE_PUBLISHABLE_KEY|NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY|REACT_APP_SUPABASE_PUBLISHABLE_KEY)/g;
   const urlMatches = content.match(supabaseUrlPattern);
   const keyMatches = content.match(supabaseKeyPattern);