@jmruthers/pace-core 0.2.4

package/docs/rbac/quick-start.md

@@ -0,0 +1,619 @@
+# RBAC Quick Start
+
+> **⚠️ CRITICAL**: This guide is designed to be impossible to get wrong. Follow every step exactly as written, and your RBAC system will work perfectly.
+
+Build your first RBAC-enabled application in under 10 minutes.
+
+## 🎯 What We'll Build
+
+A simple user management app that demonstrates:
+- Permission-based UI rendering
+- Component-level access control
+- Proper app ID resolution (fixes "Access Denied" errors)
+- Correct provider setup (fixes 400/406 database errors)
+- App context requirements (organisation vs event-based)
+
+## 🚨 Critical Rules (Follow These or It Won't Work)
+
+1. **Never make direct database queries** to `rbac_apps`, `rbac_global_roles`, or other RBAC tables
+2. **Always use `PagePermissionGuard`** for page-level permissions (not manual permission checks)
+3. **Always set up providers correctly** in the exact order shown
+4. **Use the exact app name** from your environment variable (must match database exactly)
+
+## 🚀 Step-by-Step Implementation
+
+### 1. Project Setup
+
+If you don't have a project yet:
+
+```bash
+npx create-react-app user-manager --template typescript
+cd user-manager
+```
+
+### 2. Install Dependencies
+
+**CRITICAL**: Use the exact versions specified to avoid compatibility issues.
+
+```bash
+npm install @jmruthers/pace-core@^0.4.1 @supabase/supabase-js@^2.38.0
+npm install -D tailwindcss @types/react @types/react-dom
+```
+
+### 3. Configure Tailwind CSS v4
+
+Install Tailwind CSS v4:
+```bash
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+```
+
+Update `vite.config.ts`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      // CRITICAL: Include pace-core components for scanning
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+### 4. Set Up Environment Variables
+
+Create `.env.local`:
+
+```bash
+# .env.local
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key-here
+VITE_APP_NAME=user-manager
+```
+
+**CRITICAL**: 
+- Use `VITE_` prefix for Vite projects
+- Use `NEXT_PUBLIC_` prefix for Next.js projects
+- The `VITE_APP_NAME` must match exactly what you have in the `rbac_apps` table
+
+### 5. Database Setup (CRITICAL)
+
+**CRITICAL**: Your app must be registered in the database before you can use RBAC.
+
+#### 5.1 Register Your App
+
+Run this SQL in your Supabase SQL editor:
+
+```sql
+-- Replace 'user-manager' with your actual app name (must match VITE_APP_NAME)
+INSERT INTO rbac_apps (name, display_name, requires_event, is_active) 
+VALUES ('user-manager', 'User Manager', false, true)
+ON CONFLICT (name) DO UPDATE SET
+  display_name = EXCLUDED.display_name,
+  requires_event = EXCLUDED.requires_event,
+  is_active = EXCLUDED.is_active;
+```
+
+#### 5.2 Create App Pages
+
+```sql
+-- Create pages for your app (replace 'user-manager' with your actual app name)
+INSERT INTO rbac_app_pages (app_id, page_name, page_description)
+SELECT 
+  a.id,
+  unnest(ARRAY['dashboard', 'users', 'settings', 'admin']),
+  unnest(ARRAY['Main Dashboard', 'User Management', 'App Settings', 'Admin Panel'])
+FROM rbac_apps a 
+WHERE a.name = 'user-manager';
+```
+
+#### 5.3 Set Up Page Permissions
+
+```sql
+-- Set up basic permissions for each page (replace 'user-manager' with your actual app name)
+WITH app_pages AS (
+  SELECT ap.id as page_id, ap.page_name, a.id as app_id
+  FROM rbac_app_pages ap
+  JOIN rbac_apps a ON ap.app_id = a.id
+  WHERE a.name = 'user-manager'
+)
+INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed, organisation_id)
+SELECT 
+  ap.page_id,
+  op.operation,
+  role.role_name,
+  CASE 
+    WHEN role.role_name = 'org_admin' THEN true
+    WHEN role.role_name = 'leader' AND ap.page_name != 'admin' THEN true
+    WHEN role.role_name = 'member' AND ap.page_name IN ('dashboard', 'users') THEN true
+    ELSE false
+  END,
+  '00000000-0000-0000-0000-000000000000'::uuid -- Replace with your organisation ID
+FROM app_pages ap
+CROSS JOIN (SELECT unnest(ARRAY['read', 'create', 'update', 'delete']) as operation) op
+CROSS JOIN (SELECT unnest(ARRAY['org_admin', 'leader', 'member']) as role_name) role;
+```
+
+#### 5.4 Assign User Roles
+
+```sql
+-- Grant a user the org_admin role (replace with actual user and organisation IDs)
+INSERT INTO rbac_organisation_roles (user_id, organisation_id, role, status, granted_at)
+VALUES (
+  'your-user-id'::uuid,
+  'your-organisation-id'::uuid,
+  'org_admin',
+  'active',
+  NOW()
+)
+ON CONFLICT (user_id, organisation_id) DO UPDATE SET
+  role = EXCLUDED.role,
+  status = EXCLUDED.status,
+  updated_at = NOW();
+```
+
+### 6. App Context Requirements
+
+The RBAC system supports two types of apps based on their context requirements:
+
+#### Organisation-Based App (Default)
+- **Context**: Requires `organisationId` in scope
+- **Use case**: User management, organisation settings, general dashboards
+- **Database**: `rbac_apps.requires_event = false`
+
+#### Event-Based App
+- **Context**: Requires `eventId` in scope, automatically resolves `organisationId` from event
+- **Use case**: Event registration, event management, event-specific reporting
+- **Database**: `rbac_apps.requires_event = true`
+
+### 7. Create Supabase Client
+
+Create `src/lib/supabase.ts`:
+
+```typescript
+// src/lib/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+
+const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
+const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
+
+if (!supabaseUrl || !supabaseAnonKey) {
+  throw new Error('Missing Supabase environment variables')
+}
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+```
+
+### 8. App Setup (CRITICAL)
+
+Create `src/App.tsx` with this EXACT structure:
+
+```typescript
+// src/App.tsx
+import React from 'react'
+import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
+import { 
+  UnifiedAuthProvider, 
+  OrganisationProvider,
+  EventProvider 
+} from '@jmruthers/pace-core/providers'
+import { setRBACAppName } from '@jmruthers/pace-core/utils'
+import { supabase } from './lib/supabase'
+import { Dashboard } from './pages/Dashboard'
+import { Users } from './pages/Users'
+import { Login } from './pages/Login'
+
+// CRITICAL: Set the app name for RBAC resolution
+const APP_NAME = import.meta.env.VITE_APP_NAME
+
+if (!APP_NAME) {
+  throw new Error('VITE_APP_NAME environment variable is required')
+}
+
+// CRITICAL: Set the app name globally for RBAC
+setRBACAppName(APP_NAME)
+
+function App() {
+  return (
+    <UnifiedAuthProvider 
+      supabaseClient={supabase}
+    >
+      <OrganisationProvider>
+        <EventProvider>
+          <Router>
+            <Routes>
+              <Route path="/login" element={<Login />} />
+              <Route path="/" element={<Dashboard />} />
+              <Route path="/users" element={<Users />} />
+            </Routes>
+          </Router>
+        </EventProvider>
+      </OrganisationProvider>
+    </UnifiedAuthProvider>
+  )
+}
+
+export default App
+```
+
+### 9. Create Login Page
+
+Create `src/pages/Login.tsx`:
+
+```typescript
+// src/pages/Login.tsx
+import React, { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { supabase } from '../lib/supabase'
+
+export function Login() {
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+  const [loading, setLoading] = useState(false)
+  const navigate = useNavigate()
+
+  const handleLogin = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setLoading(true)
+
+    try {
+      const { data, error } = await supabase.auth.signInWithPassword({
+        email,
+        password
+      })
+
+      if (error) {
+        alert('Login failed: ' + error.message)
+        return
+      }
+
+      if (data.user) {
+        navigate('/')
+      }
+    } catch (error) {
+      alert('Login failed: ' + (error as Error).message)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-50">
+      <div className="max-w-md w-full space-y-8">
+        <div>
+          <h2 className="mt-6 text-center text-3xl font-extrabold text-gray-900">
+            Sign in to your account
+          </h2>
+        </div>
+        <form className="mt-8 space-y-6" onSubmit={handleLogin}>
+          <div>
+            <label htmlFor="email" className="sr-only">
+              Email address
+            </label>
+            <input
+              id="email"
+              name="email"
+              type="email"
+              required
+              className="appearance-none rounded-md relative block w-full px-3 py-2 border border-gray-300 placeholder-gray-500 text-gray-900 focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 focus:z-10 sm:text-sm"
+              placeholder="Email address"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+            />
+          </div>
+          <div>
+            <label htmlFor="password" className="sr-only">
+              Password
+            </label>
+            <input
+              id="password"
+              name="password"
+              type="password"
+              required
+              className="appearance-none rounded-md relative block w-full px-3 py-2 border border-gray-300 placeholder-gray-500 text-gray-900 focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 focus:z-10 sm:text-sm"
+              placeholder="Password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+            />
+          </div>
+          <div>
+            <button
+              type="submit"
+              disabled={loading}
+              className="group relative w-full flex justify-center py-2 px-4 border border-transparent text-sm font-medium rounded-md text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 disabled:opacity-50"
+            >
+              {loading ? 'Signing in...' : 'Sign in'}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  )
+}
+```
+
+### 10. Create Dashboard Page
+
+Create `src/pages/Dashboard.tsx`:
+
+```typescript
+// src/pages/Dashboard.tsx
+import React from 'react'
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers'
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac'
+import { Link } from 'react-router-dom'
+import { supabase } from '../lib/supabase'
+
+export function Dashboard() {
+  const { user, selectedOrganisationId } = useUnifiedAuth()
+
+  if (!user) {
+    return <div>Please log in</div>
+  }
+
+  return (
+    <div className="min-h-screen bg-gray-50">
+      <nav className="bg-white shadow">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <div className="flex justify-between h-16">
+            <div className="flex items-center">
+              <h1 className="text-xl font-semibold">Dashboard</h1>
+            </div>
+            <div className="flex items-center space-x-4">
+              <span className="text-sm text-gray-700">
+                {user.email} | Org: {selectedOrganisationId}
+              </span>
+              <button
+                onClick={() => supabase.auth.signOut()}
+                className="text-sm text-gray-500 hover:text-gray-700"
+              >
+                Sign out
+              </button>
+            </div>
+          </div>
+        </div>
+      </nav>
+
+      <main className="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">
+        <div className="px-4 py-6 sm:px-0">
+          <div className="border-4 border-dashed border-gray-200 rounded-lg h-96 p-8">
+            <h2 className="text-2xl font-bold mb-4">Welcome to your Dashboard</h2>
+            
+            {/* CRITICAL: Use PagePermissionGuard for page-level permissions */}
+            <PagePermissionGuard
+              pageName="dashboard"
+              operation="read"
+              fallback={<div>You don't have permission to view the dashboard</div>}
+            >
+              <div className="space-y-4">
+                <p>You have access to the dashboard!</p>
+                
+                <div className="space-x-4">
+                  <Link 
+                    to="/users" 
+                    className="bg-blue-500 text-white px-4 py-2 rounded hover:bg-blue-600"
+                  >
+                    View Users
+                  </Link>
+                </div>
+              </div>
+            </PagePermissionGuard>
+          </div>
+        </div>
+      </main>
+    </div>
+  )
+}
+```
+
+### 11. Create Users Page
+
+Create `src/pages/Users.tsx`:
+
+```typescript
+// src/pages/Users.tsx
+import React from 'react'
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers'
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac'
+import { Link } from 'react-router-dom'
+import { supabase } from '../lib/supabase'
+
+export function Users() {
+  const { user, selectedOrganisationId } = useUnifiedAuth()
+
+  if (!user) {
+    return <div>Please log in</div>
+  }
+
+  return (
+    <div className="min-h-screen bg-gray-50">
+      <nav className="bg-white shadow">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+          <div className="flex justify-between h-16">
+            <div className="flex items-center">
+              <Link to="/" className="text-blue-600 hover:text-blue-800 mr-4">
+                ← Back to Dashboard
+              </Link>
+              <h1 className="text-xl font-semibold">Users</h1>
+            </div>
+            <div className="flex items-center space-x-4">
+              <span className="text-sm text-gray-700">
+                {user.email} | Org: {selectedOrganisationId}
+              </span>
+              <button
+                onClick={() => supabase.auth.signOut()}
+                className="text-sm text-gray-500 hover:text-gray-700"
+              >
+                Sign out
+              </button>
+            </div>
+          </div>
+        </div>
+      </nav>
+
+      <main className="max-w-7xl mx-auto py-6 sm:px-6 lg:px-8">
+        <div className="px-4 py-6 sm:px-0">
+          <div className="border-4 border-dashed border-gray-200 rounded-lg h-96 p-8">
+            <h2 className="text-2xl font-bold mb-4">User Management</h2>
+            
+            {/* CRITICAL: Use PagePermissionGuard for page-level permissions */}
+            <PagePermissionGuard
+              pageName="users"
+              operation="read"
+              fallback={<div>You don't have permission to view users</div>}
+            >
+              <div className="space-y-4">
+                <p>You have access to the users page!</p>
+                <p>This means your RBAC system is working correctly.</p>
+                
+                <div className="bg-green-100 border border-green-400 text-green-700 px-4 py-3 rounded">
+                  <strong>Success!</strong> Your RBAC setup is working correctly.
+                </div>
+              </div>
+            </PagePermissionGuard>
+          </div>
+        </div>
+      </main>
+    </div>
+  )
+}
+```
+
+## 🧪 Test Your Setup
+
+1. **Start your development server**:
+   ```bash
+   npm run dev
+   ```
+
+2. **Navigate to your app** (usually `http://localhost:3000` or `http://localhost:5173`)
+
+3. **You should see the login page**
+
+4. **Log in with a user that has the `org_admin` role**
+
+5. **You should be redirected to the dashboard**
+
+6. **Click "View Users" - you should see the users page**
+
+7. **If you see "You don't have permission" messages, check the troubleshooting section below**
+
+## 🎉 Success Checklist
+
+Your RBAC setup is working correctly if:
+
+- [ ] You can log in successfully
+- [ ] You see the dashboard without "Access Denied" messages
+- [ ] You can navigate to the users page
+- [ ] You see "Success! Your RBAC setup is working correctly" on the users page
+- [ ] No 400/406 errors in the browser console
+- [ ] No "App not found" errors in the console
+
+## 🚨 Troubleshooting
+
+### Issue: "Access Denied" on all pages
+
+**Check these in order:**
+
+1. **Verify your app is registered**:
+   ```sql
+   SELECT * FROM rbac_apps WHERE name = 'user-manager';
+   ```
+
+2. **Check your environment variable**:
+   ```typescript
+   console.log('App name:', import.meta.env.VITE_APP_NAME);
+   ```
+
+3. **Verify user has roles**:
+   ```sql
+   SELECT * FROM rbac_organisation_roles WHERE user_id = 'your-user-id';
+   ```
+
+4. **Check page permissions exist**:
+   ```sql
+   SELECT pp.*, ap.page_name, a.name as app_name
+   FROM rbac_page_permissions pp
+   JOIN rbac_app_pages ap ON pp.app_page_id = ap.id
+   JOIN rbac_apps a ON ap.app_id = a.id
+   WHERE a.name = 'user-manager';
+   ```
+
+### Issue: 400/406 Database Errors
+
+**This means your app is making incorrect database queries. Check:**
+
+1. **You're using the providers correctly** (Step 8)
+2. **You're not making direct database queries to RBAC tables**
+3. **You're using the PagePermissionGuard component** (not manual permission checks)
+
+### Issue: "App not found or inactive"
+
+**Check:**
+
+1. **Your app name in the database matches your environment variable exactly**
+2. **Your app is marked as active** (`is_active = true`)
+3. **You're using the correct app name in the UnifiedAuthProvider**
+
+### Issue: Components not rendering
+
+**Check:**
+
+1. **You're using PagePermissionGuard (not manual permission checks)**
+2. **You're providing the correct pageName and operation**
+3. **The page exists in rbac_app_pages table**
+
+## 🏢 App Context Requirements
+
+Your app is configured as an **organisation-based app** by default. This means:
+
+- ✅ Requires `organisationId` in permission scope
+- ✅ Works with organisation-level permissions
+- ✅ Automatically enforces organisation context
+
+### Switching to Event-Based App
+
+If you want to create an event-based app instead:
+
+1. **Update Database**:
+```sql
+UPDATE rbac_apps 
+SET requires_event = true 
+WHERE name = 'user-manager';
+```
+
+2. **Update Frontend**:
+```tsx
+// Event-based app requires eventId instead of organisationId
+const scope = { eventId: selectedEventId, appId: 'user-manager' };
+```
+
+3. **Automatic Organisation Resolution**:
+The system will automatically resolve the organisation ID from the event context.
+
+## 🚀 Next Steps
+
+- **[API Reference](./api-reference.md)** - Complete API documentation
+- **[Examples](./examples.md)** - More complex usage patterns
+- **[Troubleshooting](./troubleshooting.md)** - Advanced troubleshooting
+- **[Migration Guide](../migration/rbac-migration.md)** - If migrating from legacy RBAC
+
+## 🆘 Still Having Issues?
+
+If you're still having problems after following this guide exactly:
+
+1. **Check the browser console** for specific error messages
+2. **Verify your database setup** matches the SQL commands exactly
+3. **Make sure your environment variables** are set correctly
+4. **Check that your user has the correct roles** in the database
+
+This guide is designed to be foolproof - if you follow it exactly, your RBAC system will work correctly.