Deprecation Plan: pf_user_roles Table

​

Overview

• pf_user_role_assignments - User role assignments with site scoping
• pf_role_permissions - Permission mappings for system and custom roles
• pf_custom_roles - Organization-defined custom roles
• pf_module_permissions - Granular permission definitions

​

Deprecation Timeline

​

Phase 1: Soft Deprecation (COMPLETE)

​

Phase 2: Hard Deprecation (COMPLETE)

• ✅ Removed all minRole checks from code
• ✅ Removed hasMinimumRole() usage from components
• ✅ All organizations have V2 enabled (mandatory)
• ✅ Removed usePermissionsV2Enabled hook
• ✅ Removed isV2Enabled() from PermissionService
• ✅ Updated documentation to reflect V2 is mandatory

​

Phase 3: Removal

• Final migration verification
• Archive pf_user_roles to pf_user_roles_archive
• Remove minRole from all navigation item definitions
• Clean up V1 compatibility code from codebase

​

Tables Affected

​

Migration Checklist

​

For Developers

​

Code Changes

• Replace user.role === 'admin' with useHasPermission('module.entity.admin')
• Replace hasMinimumRole(role, 'staff') with hasPermission('module.entity.view')
• Add permission property to all navigation items
• Update RLS policies to use pf_has_permission() helper
• Remove direct references to pf_user_roles table

​

Navigation Items

• Add permission property to module nav items
• Add permission property to nav groups
• Keep minRole as fallback (Phase 1 only)
• Test navigation filtering with V2 enabled

​

Testing

• Update unit tests to mock V2 permission hooks
• Add RLS tests for permission-based policies
• Test navigation visibility for different roles
• Verify custom roles work correctly

​

For Org Admins

• Enable V2 in Organization Settings → Security → Permissions
• Verify all users can access expected features
• Create custom roles if specialized access needed
• Assign permissions to custom roles
• Review audit logs for permission denials

​

Rollback Procedure

​

Quick Rollback (Disable V2) - NO LONGER SUPPORTED

​

Full Rollback (Admin Only)

-- Run the rollback function
SELECT pf_rollback_v2_migration();

• Delete all pf_user_role_assignments records tagged with _migrated_from_v1
• Delete all system role permission mappings from pf_role_permissions
• NOT delete records from the original pf_user_roles table (preserved for safety)

​

Re-Migrate After Rollback

-- Re-run the migration
SELECT pf_migrate_to_v2_permissions();

-- Verify the migration
SELECT pf_verify_v2_migration();

​

Compatibility Matrix

​

Code Examples

​

Before (V1)

// Component
if (hasMinimumRole(userRole, 'org_admin')) {
  return <AdminPanel />;
}

// Navigation
{
  label: 'Settings',
  path: '/settings',
  minRole: 'org_admin',
}

// RLS Policy
CREATE POLICY "admin_access" ON some_table
USING (pf_get_user_role(auth.uid()) IN ('org_admin', 'platform_admin'));

​

After (V2)

// Component
import { useHasPermission, PermissionGate } from '@/platform/permissions';

const hasAdminAccess = useHasPermission('module.admin');
if (hasAdminAccess) {
  return <AdminPanel />;
}

// Or using PermissionGate
<PermissionGate permission="module.admin">
  <AdminPanel />
</PermissionGate>

// Navigation
{
  label: 'Settings',
  path: '/settings',
  permission: 'system.settings.admin',
  minRole: 'org_admin', // Fallback for V1 orgs
}

// RLS Policy
CREATE POLICY "admin_access" ON some_table
USING (pf_has_permission(auth.uid(), organization_id, 'module.admin'));

​

Monitoring

​

Key Metrics to Track

1. Permission check latency - V2 should be <50ms
2. V1 fallback rate - Should decrease over time
3. Permission denial rate - Watch for unexpected increases
4. Custom role adoption - Measure V2 feature usage

​

Telemetry Events

​

Contact

• Spec Owner: Platform Foundation Team
• Documentation: See specs/pf/permissions-v2-migration.md
• Rollout Guide: See specs/pf/permissions-v2-rollout.md

​

Changelog