@jmruthers/pace-core 0.6.1 → 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/docs/standards/README.md

@@ -57,6 +57,7 @@ The cursor rules cover:
 - **05-bug-reports-and-features** - Templates for issue reporting
 - **06-code-quality** - Enforce code quality standards
 - **07-tech-stack-compliance** - Enforce tech stack versions
+- **08-markup-quality** - Enforce clean markup standards, semantic HTML usage, and pace-core component patterns
 
 ### Audit Tool
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {
@@ -73,6 +73,7 @@
     "./core-usage-manifest.json": "./core-usage-manifest.json",
     "./cursor-rules": "./cursor-rules",
     "./scripts/install-cursor-rules": "./scripts/install-cursor-rules.cjs",
+    "./scripts/audit": "./scripts/audit/index.cjs",
     "./scripts/audit-consuming-app": "./scripts/audit-consuming-app.cjs",
     "./source": {
       "import": "./src/index.ts",
@@ -237,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/accessibility.cjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+/**
+ * Accessibility Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Accessibility
+ * 
+ * Checks for:
+ * - Missing aria-* attributes
+ * - Missing keyboard navigation
+ * - Missing focus management
+ * - Missing alt text on images
+ */
+
+const fs = require('fs');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const accessibilityCheck = {
+  name: 'accessibility',
+  description: 'Accessibility checks (aria attributes, keyboard navigation, alt text)',
+  severity: 'warning',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    for (const filePath of files) {
+      try {
+        // Only check React component files
+        if (!filePath.match(/\.(tsx|jsx)$/)) {
+          continue;
+        }
+        
+        const content = fs.readFileSync(filePath, 'utf8');
+        const relativePath = getRelativePath(filePath, projectRoot);
+        const normalizedPath = relativePath.replace(/\\/g, '/');
+        
+        // Skip root-level src directory - in pace-core repository, this is a demo/showcase app
+        // Note: We DO check packages/core/ files because accessibility issues (missing alt attributes, missing form labels) are real issues that should be fixed
+        const isRootSrc = normalizedPath.startsWith('src/') && !normalizedPath.includes('packages/');
+        if (isRootSrc) {
+          continue; // Skip demo app files
+        }
+        
+        // Skip scripts directory - utility scripts don't need accessibility validation
+        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+        if (isScript) {
+          continue; // Skip script files
+        }
+        
+        // Skip pace-core library components and examples - these are designed to accept accessibility props
+        // Library components accept id, aria-label, etc. via props spread
+        // Examples are demonstration code, not production code
+        const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+        const isExample = normalizedPath.includes('/examples/');
+        const isLibraryComponent = isPaceCorePackage && !isExample;
+        
+        // Check for images without alt text
+        // Skip library components - they accept alt as a prop
+        if (!isLibraryComponent) {
+          const imgPattern = /<img[^>]*>/g;
+          let imgMatch;
+          while ((imgMatch = imgPattern.exec(content)) !== null) {
+            const imgTag = imgMatch[0];
+            // Check for alt attribute, including React props (alt=, alt =, alt={)
+            const hasAlt = imgTag.includes('alt=') || imgTag.includes('alt =') || imgTag.includes('alt={');
+            if (!hasAlt) {
+              warnings.push({
+                type: 'missing-alt-text',
+                file: relativePath,
+                line: getLineNumber(content, imgMatch.index),
+                message: 'Image element missing alt attribute',
+                recommendation: 'Add alt text to all images for accessibility: <img alt="description" ... />'
+              });
+            }
+          }
+        }
+        
+        // Check for buttons/clickable elements without aria-label or accessible text
+        const buttonPattern = /<(button|a|div)\s+[^>]*(onClick|role=["']button["'])[^>]*>/g;
+        let buttonMatch;
+        while ((buttonMatch = buttonPattern.exec(content)) !== null) {
+          const buttonTag = buttonMatch[0];
+          const hasAriaLabel = buttonTag.includes('aria-label=') || buttonTag.includes('ariaLabel=');
+          const hasAccessibleText = buttonTag.includes('>') && content.substring(buttonMatch.index).match(/<[^>]*>([^<]+)</);
+          
+          if (!hasAriaLabel && !hasAccessibleText) {
+            warnings.push({
+              type: 'missing-aria-label',
+              file: relativePath,
+              line: getLineNumber(content, buttonMatch.index),
+              message: 'Interactive element missing accessible label',
+              recommendation: 'Add aria-label or ensure element contains accessible text content'
+            });
+          }
+        }
+        
+        // Check for form inputs without labels
+        // Skip library components - they accept id, aria-label, etc. via props spread
+        // Skip examples - they're demonstration code
+        if (!isLibraryComponent && !isExample) {
+          const inputPattern = /<input[^>]*>/g;
+          let inputMatch;
+          while ((inputMatch = inputPattern.exec(content)) !== null) {
+            // Get the full input tag including multi-line attributes
+            const inputStart = inputMatch.index;
+            const afterInput = content.substring(inputStart, Math.min(content.length, inputStart + 500));
+            const inputTagEnd = afterInput.indexOf('>');
+            const fullInputTag = inputTagEnd !== -1 ? afterInput.substring(0, inputTagEnd + 1) : inputMatch[0];
+            
+            // Check for id (including React props)
+            const hasId = /id=["']([^"']+)["']|id=\{/.test(fullInputTag);
+            // Check for aria-label (including React props)
+            const hasAriaLabel = /aria-label=["']|ariaLabel=|aria-label=\{/.test(fullInputTag);
+            
+            if (hasId) {
+              const idMatch = fullInputTag.match(/id=["']([^"']+)["']/);
+              if (idMatch) {
+                const id = idMatch[1];
+                // Check if there's a corresponding label
+                const beforeInput = content.substring(Math.max(0, inputMatch.index - 200), inputMatch.index);
+                const hasLabel = new RegExp(`<label[^>]*for=["']${id}["']`, 'i').test(beforeInput);
+                
+                if (!hasLabel && !hasAriaLabel) {
+                  warnings.push({
+                    type: 'missing-input-label',
+                    file: relativePath,
+                    line: getLineNumber(content, inputMatch.index),
+                    message: 'Form input missing associated label',
+                    recommendation: 'Add a <label> element with for attribute matching input id, or use aria-label'
+                  });
+                }
+              }
+            } else if (!hasAriaLabel) {
+              warnings.push({
+                type: 'missing-input-label',
+                file: relativePath,
+                line: getLineNumber(content, inputMatch.index),
+                message: 'Form input missing id and label',
+                recommendation: 'Add id to input and corresponding label, or use aria-label'
+              });
+            }
+          }
+        }
+        
+        // Check for missing focus management in modals/dialogs
+        const dialogPattern = /<Dialog|<dialog/gi;
+        if (dialogPattern.test(content)) {
+          // Skip Dialog.tsx itself - it IS the Dialog component
+          if (normalizedPath.includes('/Dialog/Dialog.tsx') || normalizedPath.includes('/Dialog/Dialog.jsx')) {
+            continue; // Skip the Dialog component file itself
+          }
+          
+          // Check if Dialog from pace-core is used (which handles focus automatically)
+          // Check for both published package import and relative imports (within pace-core repo)
+          const usesPaceCoreDialog = content.includes('from \'@jmruthers/pace-core\'') ||
+                                    content.includes('from "@jmruthers/pace-core"') ||
+                                    content.includes('from \'../Dialog') ||
+                                    content.includes('from "../Dialog') ||
+                                    content.includes('from \'../../Dialog') ||
+                                    content.includes('from "../../Dialog') ||
+                                    content.includes('from \'../../../Dialog') ||
+                                    content.includes('from "../../../Dialog') ||
+                                    content.includes('from \'./Dialog') ||
+                                    content.includes('from "./Dialog');
+          
+          if (!usesPaceCoreDialog) {
+            suggestions.push({
+              type: 'dialog-focus-management',
+              file: relativePath,
+              message: 'Custom dialog implementation detected',
+              recommendation: 'Use Dialog component from @jmruthers/pace-core which handles focus management automatically'
+            });
+          }
+        }
+        
+        // Check for color contrast issues (heuristic - check for color props without sufficient contrast)
+        const colorPattern = /(?:color|bg-|text-)=["']([^"']+)["']/g;
+        // This is a simplified check - full implementation would need color contrast calculation
+        // For now, just suggest using pace-core components which handle contrast
+        
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = accessibilityCheck;