MUM/DISCORD_RBAC_IMPLEMENTATION.md

🎯 Discord-Style RBAC Implementation

Overview

We've successfully implemented a Discord-style Role-Based Access Control (RBAC) system with hierarchical permissions, replacing the simple role system with a sophisticated many-to-many relationship structure.

🗄️ Database Schema

Core Tables

1. admin_permissions - Individual permissions

   • id (UUID) - Primary key
   • name (String) - Permission name (e.g., 'manage_users')
   • description (Text) - Human-readable description

2. admins_roles - Admin roles with hierarchy

   • id (UUID) - Primary key
   • name (String) - Role name (e.g., 'Master', 'Admin', 'Moderator')
   • description (String) - Role description
   • position (Integer) - Hierarchy value (higher = more powerful)
   • color (String) - Hex color for UI display
   • icon (String) - FontAwesome icon class

3. users_roles - Visual user roles (labels)

   • id (UUID) - Primary key
   • name (String) - Role name (e.g., 'Friend', 'Family', 'VIP')
   • description (Text) - Role description
   • color (String) - Hex color for UI display
   • icon (String) - FontAwesome icon class

Junction Tables

4. admin_role_permissions - Links roles to permissions

   • role_id (UUID) → admins_roles.id
   • permission_id (UUID) → admin_permissions.id

5. admin_user_roles_assignments - Links users to admin roles

   • user_id (UUID) → users.uuid
   • role_id (UUID) → admins_roles.id

6. users_roles_assignments - Links users to visual roles

   • user_id (UUID) → users.uuid
   • visual_role_id (UUID) → users_roles.id

🔑 Key Features

Discord-Style Hierarchy

• Position-based hierarchy: Higher position values = more powerful roles
• Role management restrictions: Users can only manage roles with lower positions
• Owner supremacy: Owners bypass all hierarchy restrictions

Many-to-Many Relationships

• Multiple admin roles per user: Users can have several admin roles simultaneously
• Multiple visual roles per user: Users can have multiple cosmetic labels
• Permission union: User's effective permissions = union of all their roles' permissions

Permission System

• Granular permissions: Individual permissions like 'manage_users', 'manage_roles'
• Role-based assignment: Permissions are assigned to roles, not directly to users
• Hierarchical management: Users can only manage roles below their highest position

🏗️ Model Classes

AdminPermission

- Individual permissions that can be assigned to roles
- Methods: Standard CRUD operations

AdminRole

- Admin roles with hierarchy and permissions
- Methods:
  - has_permission(permission_name) - Check if role has specific permission
  - can_manage_role(other_role) - Check hierarchy permissions
  - get_users_with_role(role_id) - Get all users with this role

UserRole

- Visual roles for user organization/labeling
- Methods:
  - get_users_with_role(role_id) - Get all users with this visual role

User (Enhanced)

- Enhanced with RBAC methods
- Admin Role Methods:
  - get_admin_roles() - Get all admin roles
  - has_admin_role(role_id) - Check specific admin role
  - add_admin_role(role) - Add admin role
  - remove_admin_role(role) - Remove admin role
  - set_admin_roles(roles) - Replace all admin roles
  - clear_admin_roles() - Remove all admin roles

- Visual Role Methods:
  - get_visual_roles() - Get all visual roles
  - has_visual_role(role_id) - Check specific visual role
  - add_visual_role(role) - Add visual role
  - remove_visual_role(role) - Remove visual role

- Permission Methods:
  - has_permission(permission_name) - Check permission across all roles
  - get_all_permissions() - Get unique permissions from all roles
  - get_highest_role_position() - Get highest hierarchy position
  - can_manage_role(target_role) - Check if can manage specific role

📋 Default Permissions

The system includes these default admin permissions:

• manage_users - Create, edit, and delete users
• manage_roles - Create, edit, and delete admin roles
• manage_permissions - Assign permissions to roles
• manage_settings - Access and modify application settings
• view_logs - View application logs and audit trails
• manage_invites - Create and manage user invitations
• manage_servers - Configure media servers
• manage_plugins - Install and configure plugins

🔄 Migration Status

✅ Migration created: implement_discord_style_rbac.py ✅ Models updated: All RBAC models implemented ✅ Relationships established: Many-to-many tables created ✅ Legacy compatibility: Old methods maintained for backward compatibility ✅ Default data: Default permissions will be inserted on migration

🚀 Next Steps

1. Run the migration: flask db upgrade
2. Create default roles: Set up Master, Admin, Moderator roles with appropriate positions
3. Update templates: Modify admin interface to use new role system
4. Update routes: Ensure all permission checks use new RBAC methods
5. Test hierarchy: Verify role management restrictions work correctly

💡 Usage Examples

# Check permission
if current_user.has_permission('manage_users'):
    # User can manage users

# Add admin role
master_role = AdminRole.query.filter_by(name='Master').first()
user.add_admin_role(master_role)

# Check role hierarchy
if current_user.can_manage_role(target_role):
    # User can manage this role

# Add visual role
friend_role = UserRole.query.filter_by(name='Friend').first()
user.add_visual_role(friend_role)

This implementation provides a robust, Discord-style RBAC system that's both powerful and flexible for managing complex permission scenarios.