Permissions System - Quick Reference

{module}.{entity}.{action}

// Hook for permission checks
import { useHasPermission } from '@/platform/permissions';
const canView = useHasPermission('hr.employees.view');

// Conditional rendering
import { PermissionGate } from '@/platform/permissions';
<PermissionGate permission="hr.employees.edit">
  <EditButton />
</PermissionGate>

// Page-level protection
import { RequirePermission } from '@/platform/permissions';
<RequirePermission permission="hr.employees.view">
  <EmployeesPage />
</RequirePermission>

{
 label: 'Employees',
 path: '/hr/employees',
 permission: 'hr.employees.view', // ✅ Use this
 // minRole: 'staff' // ❌ Don't use (V1 deprecated)
}

-- ✅ CORRECT: Use SECURITY DEFINER function
CREATE POLICY "users_can_view_employees" ON hr_employees
FOR SELECT
USING (
  pf_has_permission(auth.uid(), organization_id, 'hr.employees.view')
);

-- ❌ WRONG: Direct role check (V1 deprecated)
USING (has_role(auth.uid(), 'staff'));

// ❌ Before (V1)
{ label: 'Employees', path: '/hr/employees', minRole: 'staff' }

// ✅ After (V2)
{ label: 'Employees', path: '/hr/employees', permission: 'hr.employees.view' }

// ❌ Before (V1)
import { useUserRole } from '@/platform/modules/useUserRole';
const { role } = useUserRole();
if (role === 'org_admin') { ... }

// ✅ After (V2)
import { useHasPermission } from '@/platform/permissions';
const canAdmin = useHasPermission('system.platform.admin');
if (canAdmin) { ... }

-- ❌ Before (V1)
CREATE POLICY "org_admins_can_edit" ON some_table
FOR UPDATE
USING (has_role(auth.uid(), 'org_admin'));

-- ✅ After (V2)
CREATE POLICY "org_admins_can_edit" ON some_table
FOR UPDATE
USING (pf_has_permission(auth.uid(), organization_id, 'module.entity.edit'));

// ❌ WRONG
if (user.role === 'org_admin') { ... }

// ✅ CORRECT
const canAdmin = useHasPermission('system.platform.admin');
if (canAdmin) { ... }

// ❌ WRONG
const { data } = await supabase
  .from('pf_role_permissions')
  .select('*')
  .eq('permission_key', 'hr.employees.view');

// ✅ CORRECT
const canView = useHasPermission('hr.employees.view');

// ❌ WRONG (V1 deprecated)
import { useUserRole } from '@/platform/modules/useUserRole';
const { role } = useUserRole();
if (hasMinimumRole(role, 'staff')) { ... }

// ✅ CORRECT (V2)
import { useHasPermission } from '@/platform/permissions';
const canView = useHasPermission('hr.employees.view');

-- ❌ WRONG (Causes infinite recursion)
CREATE POLICY "document_org_access" ON pf_documents
FOR SELECT USING (
 organization_id IN (
 SELECT organization_id FROM pf_user_role_assignments 
 WHERE user_id = auth.uid() -- This table also has RLS!
 )
);

-- ✅ CORRECT (Use SECURITY DEFINER function with V2 permissions)
CREATE POLICY "document_org_access" ON pf_documents
FOR SELECT USING (
  pf_has_permission(auth.uid(), organization_id, 'pf.documents.view')
);