@jmruthers/pace-core 0.6.4 → 0.6.6

package/cursor-rules/09-rbac-compliance.mdc

@@ -0,0 +1,462 @@
+---
+description: Enforce RBAC contract compliance - strict rules for permission checking, page protection, and RBAC usage patterns
+globs: ["src/**/*.{ts,tsx,js,jsx}"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# RBAC Compliance Guide
+
+**📚 Human-Readable Standard**: See [09-rbac-compliance.md](../../packages/core/docs/standards/09-rbac-compliance.md) for complete documentation including RLS policy patterns, helper functions, and security requirements.
+
+This guide enforces the **mandatory RBAC contract** between pace-core and consuming apps. These rules are **enforced by ESLint** and violations will result in build errors.
+
+**⚠️ CRITICAL**: This contract is **non-negotiable**. See [RBAC Contract](../../packages/core/docs/rbac/RBAC_CONTRACT.md) for complete documentation.
+
+## MUST: Use PagePermissionGuard for All Protected Pages
+
+**MUST wrap all protected pages with `PagePermissionGuard`:**
+
+```tsx
+// ✅ CORRECT
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function DashboardPage() {
+  return (
+    <PagePermissionGuard pageName="dashboard" operation="read">
+      <DashboardContent />
+    </PagePermissionGuard>
+  );
+}
+```
+
+**MUST NOT:**
+- Render protected content without `PagePermissionGuard`
+- Create wrapper components around `PagePermissionGuard`
+- Bypass page-level permission checks
+
+```tsx
+// ❌ FORBIDDEN - No guard
+function DashboardPage() {
+  return <DashboardContent />;  // ERROR: Unprotected page
+}
+
+// ❌ FORBIDDEN - Wrapper component
+function EventPageGuard({ pageName, children }) {
+  return <PagePermissionGuard pageName={pageName}>{children}</PagePermissionGuard>;
+}
+```
+
+## MUST: Use pace-core Permission Hooks Directly
+
+**MUST use pace-core hooks directly without wrappers:**
+
+```tsx
+// ✅ CORRECT
+import { useCan, useResourcePermissions } from '@jmruthers/pace-core/rbac';
+import { RESOURCE_NAMES } from '@/config/resource-names';
+
+function MyComponent() {
+  const { canUpdate, canDelete } = useResourcePermissions(RESOURCE_NAMES.JOURNAL);
+  const canEdit = useCan(userId, scope, 'update:users');
+  // Use canUpdate, canDelete, canEdit directly
+}
+```
+
+**MUST NOT:**
+- Create wrapper functions around permission hooks
+- Create custom permission utility functions
+- Use string literals in `useResourcePermissions` calls
+
+```tsx
+// ❌ FORBIDDEN - Wrapper function
+const canEdit = (postId: string) => {
+  const hasPermission = canUpdate('journal');
+  const post = posts.find(p => p.id === postId);
+  return hasPermission && !!post;
+};
+
+// ❌ FORBIDDEN - Custom utility
+function checkPermission(permission: string) {
+  // Custom logic...
+}
+
+// ❌ FORBIDDEN - String literal
+const { canUpdate } = useResourcePermissions('journal');
+```
+
+## MUST: Use RESOURCE_NAMES Constants
+
+**MUST use `RESOURCE_NAMES` constant object for all resource permission checks:**
+
+```tsx
+// ✅ CORRECT
+import { RESOURCE_NAMES } from '@/config/resource-names';
+const { canCreate, canUpdate, canDelete } = useResourcePermissions(RESOURCE_NAMES.JOURNAL);
+```
+
+**MUST NOT:**
+- Use string literals in `useResourcePermissions` calls
+- Hardcode resource names
+
+```tsx
+// ❌ FORBIDDEN - String literal
+const { canUpdate } = useResourcePermissions('journal');
+```
+
+## MUST: Use Standard AccessDenied Component
+
+**MUST use `AccessDenied` from pace-core for all access denied scenarios:**
+
+```tsx
+// ✅ CORRECT
+import { AccessDenied } from '@jmruthers/pace-core/rbac';
+
+<PagePermissionGuard 
+  pageName="dashboard" 
+  operation="read"
+  fallback={<AccessDenied />}
+>
+  <DashboardContent />
+</PagePermissionGuard>
+```
+
+**MUST NOT:**
+- Create custom access denied components
+- Use custom permission denied components
+
+```tsx
+// ❌ FORBIDDEN - Custom component
+function CustomAccessDenied() {
+  return <div>Access Denied</div>;
+}
+```
+
+## MUST: Use pace-core API for Permission Checks
+
+**MUST use pace-core API functions for programmatic permission checks:**
+
+```tsx
+// ✅ CORRECT
+import { isPermitted, isPermittedCached } from '@jmruthers/pace-core/rbac';
+
+const hasAccess = await isPermitted({
+  userId: 'user-123',
+  scope: { organisationId: 'org-456' },
+  permission: 'read:dashboard',
+  pageId: 'dashboard'
+});
+```
+
+**MUST NOT:**
+- Call RBAC RPC functions directly
+- Query RBAC tables directly (without `useSecureSupabase`)
+- Create custom RBAC helper functions
+
+```tsx
+// ❌ FORBIDDEN - Direct RPC call
+const { data } = await supabase.rpc('rbac_check_permission_simplified', {
+  p_user_id: userId,
+  p_permission: 'read:dashboard'
+});
+
+// ❌ FORBIDDEN - Direct table query
+const { data } = await supabase
+  .from('rbac_user_profiles')
+  .select('*');
+
+// ❌ FORBIDDEN - Custom RBAC helper
+function checkPermission(userId: string, permission: string) {
+  // Custom logic that bypasses pace-core
+}
+```
+
+## MUST: Use pace-core API in Edge Functions (No Exceptions)
+
+**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 (headers, body, or query params)
+  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:**
+
+```typescript
+// ❌ FORBIDDEN - Creating 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
+
+## MUST: Use useSecureSupabase for RBAC Table Queries
+
+**If you must query RBAC tables (rare), MUST use `useSecureSupabase`:**
+
+```tsx
+// ✅ CORRECT
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+
+function MyComponent() {
+  const secureSupabase = useSecureSupabase();
+  // If your hook signature requires a client argument, pass ONLY the pace-core-provided client (never a local createClient()).
+  const { data } = await secureSupabase
+    .from('rbac_user_profiles')  // Allowed through secure client
+    .select('*');
+}
+```
+
+**MUST NOT query these tables directly:**
+- `rbac_organisation_roles`
+- `rbac_event_app_roles`
+- `rbac_global_roles`
+- `rbac_apps`
+- `rbac_app_pages`
+- `rbac_page_permissions`
+- `rbac_user_profiles`
+
+## MUST NOT: Use Hardcoded Role Checks
+
+**MUST NOT compare roles directly:**
+
+```tsx
+// ❌ FORBIDDEN - Hardcoded role check
+if (user.role === 'admin') {
+  // ...
+}
+```
+
+**MUST use pace-core APIs:**
+
+```tsx
+// ✅ CORRECT
+import { useAccessLevel, getRoleContext } from '@jmruthers/pace-core/rbac';
+
+const { accessLevel } = useAccessLevel(userId, scope);
+const roleContext = await getRoleContext({ userId, scope });
+```
+
+## MUST: Configure enforcePermissions Correctly
+
+**For event-based apps (where pages handle their own checks):**
+
+```tsx
+// ✅ CORRECT - Event-based app pattern
+<PaceAppLayout 
+  appName="MyApp"
+  enforcePermissions={false}  // Pages handle checks via PagePermissionGuard
+  // ...
+>
+```
+
+**For organisation-based apps (where layout handles checks):**
+
+```tsx
+// ✅ CORRECT - Organisation-based app pattern
+<PaceAppLayout 
+  appName="MyApp"
+  enforcePermissions={true}  // Layout handles checks
+  defaultPermission="read"
+  // ...
+>
+```
+
+## MUST: Setup RBAC Before Use
+
+**MUST call `setupRBAC()` before any RBAC usage:**
+
+```tsx
+// main.tsx - MUST be first
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+setupRBAC(supabase);
+// Then render app
+```
+
+## Enforcement
+
+These rules are enforced by ESLint rules (all ERROR severity):
+
+1. **`no-direct-rbac-rpc`** - Detects direct calls to `rbac_check_permission_simplified`
+2. **`no-direct-rbac-tables`** - Detects direct queries to RBAC tables
+3. **`no-bypass-page-guard`** - Detects routes without `PagePermissionGuard`
+4. **`no-custom-access-denied`** - Detects custom access denied components
+5. **`no-hardcoded-role-checks`** - Detects hardcoded role comparisons
+6. **`no-custom-permission-utilities`** - Detects custom permission utility functions
+7. **`no-resource-permission-string-literals`** - Detects string literals in `useResourcePermissions` calls
+8. **`no-permission-wrapper-functions`** - Detects wrapper functions around pace-core permission hooks
+
+## Compliance Checklist
+
+Before committing RBAC-related code, verify:
+
+- [ ] All protected pages use `PagePermissionGuard`
+- [ ] No wrapper components around `PagePermissionGuard`
+- [ ] No wrapper functions around permission hooks
+- [ ] All `useResourcePermissions` calls use `RESOURCE_NAMES` constants
+- [ ] No direct RPC calls to `rbac_check_permission_simplified`
+- [ ] No direct queries to RBAC tables (use `useSecureSupabase` if needed)
+- [ ] No hardcoded role checks (use `useAccessLevel` or `getRoleContext`)
+- [ ] No custom permission utility functions
+- [ ] All access denied scenarios use `AccessDenied` from pace-core
+- [ ] `enforcePermissions` configured correctly for app type
+- [ ] `setupRBAC()` called before any RBAC usage
+- [ ] Edge Functions use `isPermitted()` API (no custom RBAC helpers)
+- [ ] All RLS policies for authenticated users include super-admin checks
+- [ ] All `is_super_admin()` calls use explicit parameter (`safe_get_user_id_for_rls()`)
+- [ ] No security-critical functions use fallback strategies
+- [ ] ESLint rules pass without errors
+
+## MUST: Include Super-Admin Checks in RLS Policies
+
+**MUST include super-admin bypass in all RLS policies for authenticated users:**
+
+```sql
+-- ✅ CORRECT: Super-admin check included
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  organisation_id IS NOT NULL
+  AND (
+    is_super_admin(safe_get_user_id_for_rls())
+    OR check_user_organisation_access(organisation_id)
+  )
+);
+```
+
+**MUST NOT:**
+- Create RLS policies without super-admin checks (except for public/anonymous policies)
+- Use `is_super_admin()` without a parameter (relies on fallback strategies)
+- Create security-critical functions with fallback strategies
+
+```sql
+-- ❌ FORBIDDEN: Missing super-admin check
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  check_user_organisation_access(organisation_id)
+);
+
+-- ❌ FORBIDDEN: is_super_admin() without parameter
+CREATE POLICY "rbac_select_table_name" ON table_name
+FOR SELECT TO authenticated
+USING (
+  is_super_admin()  -- Missing parameter, uses fallback strategies
+  OR check_user_organisation_access(organisation_id)
+);
+```
+
+**MUST use explicit parameter passing:**
+
+```sql
+-- ✅ CORRECT: Explicit user ID parameter
+is_super_admin(safe_get_user_id_for_rls())
+```
+
+**MUST NOT create security-critical functions with fallback strategies:**
+
+```sql
+-- ❌ FORBIDDEN: Multiple fallback strategies
+CREATE FUNCTION is_super_admin(p_user_id UUID DEFAULT NULL)
+RETURNS boolean AS $$
+BEGIN
+  IF p_user_id IS NOT NULL THEN
+    v_user_id := p_user_id;
+  ELSE
+    v_user_id := auth.uid();  -- Fallback 1
+  END IF;
+  -- More fallbacks...
+END;
+$$;
+
+-- ✅ CORRECT: Required parameter, no fallbacks
+CREATE FUNCTION is_super_admin(p_user_id UUID)
+RETURNS boolean AS $$
+BEGIN
+  IF p_user_id IS NULL THEN
+    RETURN false;  -- Fail secure
+  END IF;
+  -- Check super-admin status
+END;
+$$;
+```
+
+## Reference
+
+- **RBAC Contract**: `packages/core/docs/rbac/RBAC_CONTRACT.md` - Complete contract documentation
+- **Migration Guide**: `packages/core/docs/rbac/MIGRATION_GUIDE.md` - Migrating to RBAC Contract v2.0.0
+- **Quick Start**: `packages/core/docs/rbac/quick-start.md` - Getting started guide
+- **API Reference**: `packages/core/docs/rbac/api-reference.md` - Complete API documentation
+- **RLS Standards**: `packages/core/docs/standards/09-rbac-compliance.md` - RLS policy patterns and super-admin requirements

package/cursor-rules/10-error-handling-patterns.mdc

@@ -0,0 +1,179 @@
+---
+description: Enforce consistent error handling patterns including type-safe errors, user-friendly messages, and proper logging
+globs: ["src/**/*.{ts,tsx,js,jsx}"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# Error Handling Patterns Guide
+
+**📚 Human-Readable Standard**: See [10-error-handling-patterns.md](../../packages/core/docs/standards/10-error-handling-patterns.md) for complete documentation.
+
+This guide enforces consistent error handling patterns to ensure user-friendly errors, type-safe handling, and proper logging.
+
+**AI Agent Instructions**: When writing error handling code, ALWAYS follow these patterns. Never expose internal details to users. Always use type-safe error handling.
+
+## MUST: Use Type-Safe Error Handling
+
+**MUST use type guards or Result types, NEVER use `any`:**
+
+```tsx
+// ❌ WRONG: Using any
+catch (error: any) {
+  console.log(error.message);
+}
+
+// ✅ CORRECT: Type guard
+function isApiError(error: unknown): error is ApiError {
+  return typeof error === 'object' && error !== null && 'ok' in error && (error as ApiError).ok === false;
+}
+catch (error) {
+  if (isApiError(error)) {
+    handleApiError(error);
+  } else {
+    handleUnknownError(error);
+  }
+}
+
+// ✅ CORRECT: Result type
+type Result<T> = { ok: true; data: T } | { ok: false; error: ApiError };
+const result = await fetchData();
+if (result.ok) {
+  useData(result.data);
+} else {
+  showError(result.error.message);
+}
+```
+
+## MUST: Never Expose Internal Details
+
+**MUST NOT expose SQL, stack traces, file paths, or internal errors to users:**
+
+```tsx
+// ❌ WRONG: Exposing internal details
+toast.error(error.message); // May contain SQL, stack traces
+
+// ✅ CORRECT: User-friendly message
+toast.error('Unable to save changes. Please try again.');
+logger.error('Save failed', { error: error.message, context: 'saveUser' });
+```
+
+## MUST: Use Consistent Error Shapes
+
+**MUST use ApiResult shape for API errors:**
+
+```tsx
+// ✅ CORRECT: Consistent error shape
+type ApiError = {
+  ok: false;
+  error: {
+    code: string;
+    message: string; // User-friendly
+    details?: object; // Non-sensitive context
+  };
+};
+```
+
+## MUST: Log Errors with Context
+
+**MUST log errors with context, but NEVER log sensitive data:**
+
+```tsx
+// ✅ CORRECT: Log with context, no sensitive data
+logger.error('Failed to save user', {
+  userId: user.id,
+  operation: 'updateUser',
+  errorCode: error.code,
+});
+
+// ❌ WRONG: Logging sensitive data
+logger.error('Failed to save user', {
+  password: user.password, // NEVER
+  token: authToken,        // NEVER
+  ssn: user.ssn,          // NEVER
+});
+```
+
+## SHOULD: Provide Recovery Paths
+
+**SHOULD provide retry logic or fallback values when appropriate:**
+
+```tsx
+// ✅ CORRECT: Retry with exponential backoff
+async function fetchWithRetry<T>(fn: () => Promise<Result<T>>, maxRetries = 3): Promise<Result<T>> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    const result = await fn();
+    if (result.ok) return result;
+    if (result.error.code?.startsWith('4')) return result; // Don't retry 4xx
+    await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
+  }
+  return { ok: false, error: { code: 'MAX_RETRIES', message: 'Operation failed after retries' } };
+}
+
+// ✅ CORRECT: Fallback values
+const preferences = await fetchPreferences().catch(() => ({ theme: 'light', language: 'en' }));
+```
+
+## SHOULD: Use Error Boundaries for React
+
+**SHOULD use ErrorBoundary for React component errors:**
+
+```tsx
+// ✅ CORRECT: Error boundary
+import { ErrorBoundary } from '@jmruthers/pace-core';
+<ErrorBoundary fallback={<ErrorFallback />} onError={(error, errorInfo) => logger.error('React error', { error, errorInfo })}>
+  <YourApp />
+</ErrorBoundary>
+```
+
+## Decision Tree: Error Handling
+
+**ALWAYS follow this decision tree:**
+
+```
+1. What type of error is this?
+   ├─ API Error → Use ApiResult shape, user-friendly message
+   ├─ Validation Error → Use Zod errors, field-specific messages
+   ├─ Network Error → Retry logic, connection message
+   └─ Unknown Error → Generic user message, detailed log
+
+2. Should user see this error?
+   ├─ YES → User-friendly message (no internals)
+   └─ NO → Log only, show generic message
+
+3. Can we recover?
+   ├─ YES → Retry logic or fallback value
+   └─ NO → Show error, allow user to retry
+
+4. Is this sensitive data?
+   ├─ YES → Never log (passwords, tokens, PII)
+   └─ NO → Log with context
+```
+
+## Error Handling Checklist
+
+Before committing error handling code, verify:
+
+- [ ] Type-safe error handling (no `any`)
+- [ ] User-friendly error messages (no internals)
+- [ ] Errors logged with context (no sensitive data)
+- [ ] Recovery paths provided when possible
+- [ ] Consistent error shapes used
+- [ ] Error boundaries for React components
+- [ ] Async operations have proper error handling
+- [ ] Validation errors use Zod
+- [ ] Network errors handled gracefully
+
+## Common Mistakes to Avoid
+
+1. **Exposing internal details** - Never show SQL, stack traces, file paths
+2. **Using `any` for errors** - Always use type guards or Result types
+3. **Logging sensitive data** - Never log passwords, tokens, PII
+4. **Ignoring errors** - Always handle errors, even if just logging
+5. **Generic error messages** - Provide specific, actionable messages
+
+## Reference
+
+- **Standard**: `packages/core/docs/standards/10-error-handling-patterns.md`
+- **Code Quality**: See `06-code-quality.mdc` for TypeScript standards
+- **Security**: See `01-standards-compliance.mdc` for security requirements