@jmruthers/pace-core 0.6.2 → 0.6.3

package/docs/rbac/secure-client-protection.md

@@ -0,0 +1,330 @@
+# Secure Supabase Client Protection
+
+This document describes the multi-layered protection system to prevent consuming apps from using insecure Supabase clients that bypass organisation context and RLS policies.
+
+## Problem
+
+Using `createClient()` from `@supabase/supabase-js` directly bypasses:
+- Organisation context enforcement
+- RLS (Row Level Security) policies
+- Event and app context injection
+- Security safeguards built into pace-core
+
+This can lead to:
+- **Cross-organisation data access** - Users accessing data from organisations they shouldn't
+- **Security vulnerabilities** - Bypassing permission checks
+- **Data leakage** - Accidental exposure of sensitive data
+
+## Protection Layers
+
+### 1. ESLint Rule: `no-direct-supabase-client`
+
+**Location**: `packages/core/src/eslint-rules/pace-core-compliance.cjs`
+
+**What it does**:
+- Detects `createClient` imports from `@supabase/supabase-js`
+- Detects `createClient()` function calls
+- Reports errors with helpful suggestions
+
+**How to use**:
+```js
+// In your consuming app's eslint.config.js:
+import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
+
+export default [
+  ...paceCoreConfig,
+  // pace-core-compliance/no-direct-supabase-client is automatically enabled
+];
+```
+
+**Example violations**:
+```tsx
+// ❌ ERROR: Direct import detected
+import { createClient } from '@supabase/supabase-js';
+
+// ❌ ERROR: Direct client creation
+const supabase = createClient(url, key);
+```
+
+### 2. Runtime Detection: `warnIfInsecureClient()`
+
+**Location**: `packages/core/src/rbac/utils/clientSecurity.ts`
+
+**What it does**:
+- Checks if a client is marked as secure
+- Warns in development mode when insecure clients are detected
+- Provides helpful error messages with fix suggestions
+
+**How to use**:
+```tsx
+import { warnIfInsecureClient } from '@jmruthers/pace-core/rbac';
+
+function MyComponent() {
+  const supabase = useSecureSupabase();
+  
+  // Optional: Warn if client is insecure (development only)
+  warnIfInsecureClient(supabase, 'MyComponent');
+  
+  // Use supabase...
+}
+```
+
+**Output** (development mode only):
+```
+[pace-core Security Warning] Non-secure Supabase client detected in MyComponent.
+You are using a Supabase client created with createClient() instead of useSecureSupabase().
+This bypasses organisation context enforcement and RLS policies...
+```
+
+### 3. Type Safety: `isSecureClient()`
+
+**Location**: `packages/core/src/rbac/utils/clientSecurity.ts`
+
+**What it does**:
+- Type guard to check if a client is secure
+- Returns `true` only for clients created via `useSecureSupabase()` or `createSecureClient()`
+- Can be used for runtime checks and TypeScript narrowing
+
+**How to use**:
+```tsx
+import { isSecureClient } from '@jmruthers/pace-core/rbac';
+
+function MyComponent() {
+  const supabase = useSecureSupabase();
+  
+  if (isSecureClient(supabase)) {
+    // TypeScript knows supabase is secure here
+    // Safe to use for database operations
+  } else {
+    // Client is not secure - handle error
+    console.error('Insecure client detected!');
+  }
+}
+```
+
+### 4. Automatic Client Marking
+
+**Location**: `packages/core/src/rbac/secureClient.ts`
+
+**What it does**:
+- Automatically marks clients created via `SecureSupabaseClient` as secure
+- Uses a Symbol (`SECURE_CLIENT_SYMBOL`) to mark secure clients
+- Works transparently - no action needed from developers
+
+**How it works**:
+```tsx
+// When you use useSecureSupabase():
+const supabase = useSecureSupabase();
+// Client is automatically marked as secure internally
+
+// When you use createSecureClient():
+const secureClient = createSecureClient(url, key, orgId);
+const supabase = secureClient.getClient();
+// Client is automatically marked as secure internally
+```
+
+## Correct Usage
+
+### ✅ Use `useSecureSupabase()` Hook
+
+```tsx
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+
+function MyComponent() {
+  const supabase = useSecureSupabase();
+  
+  if (!supabase) {
+    return <div>Loading...</div>;
+  }
+  
+  // Organisation context is automatically enforced
+  const { data } = await supabase.from('users').select('*');
+}
+```
+
+### ✅ Use `createSecureClient()` for Non-React Code
+
+```tsx
+import { createSecureClient } from '@jmruthers/pace-core/rbac';
+
+// For server-side or non-React code
+const secureClient = createSecureClient(
+  url,
+  key,
+  organisationId,
+  eventId,
+  appId,
+  isSuperAdmin
+);
+const supabase = secureClient.getClient();
+```
+
+### ✅ Verify Client Security (Optional)
+
+```tsx
+import { useSecureSupabase, isSecureClient, warnIfInsecureClient } from '@jmruthers/pace-core/rbac';
+
+function MyComponent() {
+  const supabase = useSecureSupabase();
+  
+  // Development-only warning
+  warnIfInsecureClient(supabase, 'MyComponent');
+  
+  // Runtime check
+  if (!isSecureClient(supabase)) {
+    throw new Error('Insecure client detected!');
+  }
+  
+  // Use supabase...
+}
+```
+
+## Incorrect Usage (Will Be Detected)
+
+### ❌ Direct `createClient()` Import
+
+```tsx
+// ESLint will report error
+import { createClient } from '@supabase/supabase-js';
+const supabase = createClient(url, key);
+```
+
+### ❌ Direct `createClient()` Call
+
+```tsx
+// ESLint will report error
+const supabase = createClient(url, key);
+```
+
+### ❌ Using Base Client for Queries
+
+```tsx
+// Even if imported from config file, using for queries is wrong
+import { supabase } from './lib/supabase'; // Base client
+const { data } = await supabase.from('users').select('*'); // ❌ Bypasses security
+```
+
+## Configuration Files Exception
+
+The ESLint rule allows `createClient()` in configuration files (files matching `supabase*.ts/js` or `*client*.ts/js`). This is intentional because:
+
+1. Base clients are needed for authentication setup
+2. Base clients should only be used for auth operations
+3. Base clients should be passed to `useSecureSupabase()` as fallback
+
+**Example of acceptable config file**:
+```tsx
+// supabaseClient.ts - Config file (allowed)
+import { createClient } from '@supabase/supabase-js';
+
+export const supabase = createClient(url, key);
+
+// Then in components:
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+import { supabase } from './supabaseClient';
+
+function MyComponent() {
+  // ✅ Correct: Pass base client as fallback
+  const secureSupabase = useSecureSupabase(supabase);
+}
+```
+
+## Audit Script Detection
+
+The pace-core audit script comprehensively detects insecure client usage:
+
+```bash
+npm run audit
+```
+
+The audit will report violations including:
+- ✅ Direct `createClient` imports from `@supabase/supabase-js`
+- ✅ Direct `createClient()` function calls
+- ✅ Usage of non-secure clients for database queries (`.from()` calls)
+- ✅ Files that import `createClient` but don't use `useSecureSupabase()`
+- ✅ Variables created with `createClient()` that are used for queries
+
+**Example audit output**:
+```
+❌ Direct Supabase client usage detected
+   File: src/components/UserList.tsx
+   Line: 15
+   Variable: supabase
+   Table: users
+   Reason: Direct Supabase client usage detected. Variable 'supabase' is created with createClient() and used for database queries. You MUST use useSecureSupabase() instead to ensure RLS policies and organisation context are enforced.
+   Recommendation: Replace with: import { useSecureSupabase } from '@jmruthers/pace-core/rbac'; const supabase = useSecureSupabase();
+```
+
+The audit tool provides the same level of detection as the ESLint rule, making it useful for:
+- Pre-commit checks
+- CI/CD pipelines
+- Code reviews
+- Migration validation
+
+## Best Practices
+
+1. **Always use `useSecureSupabase()`** in React components
+2. **Use `createSecureClient()`** for server-side or non-React code
+3. **Never import `createClient`** from `@supabase/supabase-js` in component files
+4. **Verify client security** in critical code paths (optional but recommended)
+5. **Run ESLint** regularly to catch violations early
+6. **Run audit script** before deploying to catch any missed violations
+
+## Troubleshooting
+
+### "ESLint reports error but I need createClient for auth"
+
+**Solution**: Create a config file (e.g., `supabaseClient.ts`) and use `useSecureSupabase()` with the base client as fallback:
+
+```tsx
+// supabaseClient.ts
+import { createClient } from '@supabase/supabase-js';
+export const supabase = createClient(url, key);
+
+// MyComponent.tsx
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+import { supabase } from './supabaseClient';
+
+function MyComponent() {
+  const secureSupabase = useSecureSupabase(supabase);
+  // Use secureSupabase for all database operations
+}
+```
+
+### "I'm getting runtime warnings in development"
+
+**Solution**: Ensure you're using `useSecureSupabase()` instead of a base client:
+
+```tsx
+// ❌ Wrong
+const supabase = createClient(url, key);
+
+// ✅ Correct
+const supabase = useSecureSupabase();
+```
+
+### "How do I check if my client is secure?"
+
+**Solution**: Use `isSecureClient()`:
+
+```tsx
+import { isSecureClient } from '@jmruthers/pace-core/rbac';
+
+if (isSecureClient(supabase)) {
+  console.log('Client is secure!');
+} else {
+  console.error('Client is NOT secure!');
+}
+```
+
+## Summary
+
+The protection system provides:
+- ✅ **ESLint rules** to catch violations at development time
+- ✅ **Runtime warnings** to alert developers in development mode
+- ✅ **Type safety** to verify client security
+- ✅ **Automatic marking** of secure clients
+- ✅ **Audit scripts** to catch violations before deployment
+
+By following these guidelines, you ensure that all database operations respect organisation context and RLS policies, preventing security vulnerabilities and data leakage.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {
@@ -238,10 +238,10 @@
     "globals": "^16.3.0",
     "jsdom": "^25.0.1",
     "react-router-dom": "^6.26.2",
-    "typedoc": "^0.25.13",
+    "tsup": "^8.5.0",
+    "typedoc": "^0.26.11",
     "typedoc-plugin-markdown": "^3.17.1",
     "typedoc-plugin-merge-modules": "^5.1.0",
-    "tsup": "^8.5.0",
     "typescript": "^5.4.0",
     "typescript-eslint": "^8.39.0",
     "vite": "^6.0.3"

package/scripts/audit/core/checks/compliance.cjs

@@ -2306,6 +2306,78 @@ function scanFile(filePath, manifest, projectRoot) {
         }
       }
     }
+    
+    // Check for createClient imports even without immediate query usage
+    // This catches cases where createClient is imported but may be used later
+    if (hasCreateClientImport && !usesSecureSupabase) {
+      const isConfigFile = /config|supabase|client/i.test(relativePath) && 
+                          (relativePath.includes('supabase.ts') || 
+                           relativePath.includes('supabase.js') ||
+                           relativePath.includes('client.ts') ||
+                           relativePath.includes('client.js'));
+      
+      if (!isConfigFile) {
+        // Find the line number of the import
+        const importMatch = content.match(/import\s+{\s*createClient\s*}\s+from\s+['"]@supabase\/supabase-js['"]/);
+        if (importMatch) {
+          const lineNumber = content.substring(0, importMatch.index).split('\n').length;
+          
+          // Check if this violation is already reported
+          const alreadyReported = violations.directSupabaseClient.some(v => 
+            v.file === relativePath && 
+            v.variable === 'createClient' &&
+            Math.abs(v.line - lineNumber) <= 2
+          );
+          
+          if (!alreadyReported) {
+            violations.directSupabaseClient.push({
+              file: relativePath,
+              line: lineNumber,
+              variable: 'createClient',
+              table: 'none',
+              reason: 'Direct import of createClient from @supabase/supabase-js detected. You MUST use useSecureSupabase() from @jmruthers/pace-core/rbac instead to ensure organisation context and RLS policies are enforced.',
+              recommendation: 'Remove this import and use: import { useSecureSupabase } from \'@jmruthers/pace-core/rbac\'; const supabase = useSecureSupabase();'
+            });
+          }
+        }
+      }
+    }
+    
+    // Check for createClient() calls even when variable isn't used for queries yet
+    // This catches potential security issues early
+    if (hasCreateClientUsage && !usesSecureSupabase) {
+      const isConfigFile = /config|supabase|client/i.test(relativePath) && 
+                          (relativePath.includes('supabase.ts') || 
+                           relativePath.includes('supabase.js') ||
+                           relativePath.includes('client.ts') ||
+                           relativePath.includes('client.js'));
+      
+      if (!isConfigFile) {
+        // Find all createClient() calls
+        const createClientCallPattern = /createClient\s*\(/g;
+        let callMatch;
+        while ((callMatch = createClientCallPattern.exec(content)) !== null) {
+          const lineNumber = content.substring(0, callMatch.index).split('\n').length;
+          
+          // Check if this violation is already reported
+          const alreadyReported = violations.directSupabaseClient.some(v => 
+            v.file === relativePath && 
+            Math.abs(v.line - lineNumber) <= 2
+          );
+          
+          if (!alreadyReported) {
+            violations.directSupabaseClient.push({
+              file: relativePath,
+              line: lineNumber,
+              variable: 'unknown',
+              table: 'none',
+              reason: 'Direct createClient() call detected. You MUST use useSecureSupabase() from @jmruthers/pace-core/rbac instead to ensure organisation context and RLS policies are enforced.',
+              recommendation: 'Replace with: import { useSecureSupabase } from \'@jmruthers/pace-core/rbac\'; const supabase = useSecureSupabase();'
+            });
+          }
+        }
+      }
+    }
   }
   
   // ============================================