bakery-ia/docs/ROLES_AND_PERMISSIONS_SYSTEM.md

# Roles and Permissions System

## Overview

The Bakery IA platform implements a **dual role system** that provides fine-grained access control across both platform-wide and organization-specific operations.

## Architecture

### Two Distinct Role Systems

#### 1. Global User Roles (Auth Service)

**Purpose:** System-wide permissions across the entire platform
**Service:** Auth Service
**Storage:** `User` model
**Scope:** Cross-tenant, platform-level access control

**Roles:**
- `super_admin` - Full platform access, can perform any operation
- `admin` - System administrator, platform management capabilities
- `manager` - Mid-level management access
- `user` - Basic authenticated user

**Use Cases:**
- Platform administration
- Cross-tenant operations
- System-wide features
- User management at platform level

#### 2. Tenant-Specific Roles (Tenant Service)

**Purpose:** Organization/tenant-level permissions
**Service:** Tenant Service
**Storage:** `TenantMember` model
**Scope:** Per-tenant access control

**Roles:**
- `owner` - Full control of the tenant, can transfer ownership, manage all aspects
- `admin` - Tenant administrator, can manage team members and most operations
- `member` - Standard team member, regular operational access
- `viewer` - Read-only observer, view-only access to tenant data

**Use Cases:**
- Team management
- Organization-specific operations
- Resource access within a tenant
- Most application features

## Role Mapping

When users are created through tenant management (pilot phase), tenant roles are automatically mapped to appropriate global roles:

```
Tenant Role    →    Global Role    │ Rationale
─────────────────────────────────────────────────
admin         →     admin          │ Administrative access
member        →     manager        │ Management-level access
viewer        →     user           │ Basic user access
owner         →     (no mapping)   │ Owner is tenant-specific only
```

**Implementation:**
- Frontend: `frontend/src/types/roles.ts`
- Backend: `services/tenant/app/api/tenant_members.py` (lines 68-76)

## Permission Checking

### Unified Permission System

Location: `frontend/src/utils/permissions.ts`

The unified permission system provides centralized functions for checking permissions:

#### Functions

1. **`checkGlobalPermission(user, options)`**
   - Check platform-wide permissions
   - Used for: System settings, platform admin features

2. **`checkTenantPermission(tenantAccess, options)`**
   - Check tenant-specific permissions
   - Used for: Team management, tenant resources

3. **`checkCombinedPermission(user, tenantAccess, options)`**
   - Check either global OR tenant permissions
   - Used for: Mixed access scenarios

4. **Helper Functions:**
   - `canManageTeam()` - Check team management permission
   - `isTenantOwner()` - Check if user is tenant owner
   - `canPerformAdminActions()` - Check admin permissions
   - `getEffectivePermissions()` - Get all permission flags

### Usage Examples

```typescript
// Check if user can manage platform users (global only)
checkGlobalPermission(user, { requiredRole: 'admin' })

// Check if user can manage tenant team (tenant only)
checkTenantPermission(tenantAccess, { requiredRole: 'owner' })

// Check if user can access a feature (either global admin OR tenant owner)
checkCombinedPermission(user, tenantAccess, {
  globalRoles: ['admin', 'super_admin'],
  tenantRoles: ['owner']
})
```

## Route Protection

### Protected Routes

Location: `frontend/src/router/ProtectedRoute.tsx`

All protected routes now use the unified permission system:

```typescript
// Admin Route: Global admin OR tenant owner/admin
<AdminRoute>
  <Component />
</AdminRoute>

// Manager Route: Global admin/manager OR tenant admin/owner/member
<ManagerRoute>
  <Component />
</ManagerRoute>

// Owner Route: Super admin OR tenant owner only
<OwnerRoute>
  <Component />
</OwnerRoute>
```

## Team Management

### Core Features

#### 1. Add Team Members
- **Permission Required:** Tenant Owner or Admin
- **Options:**
  - Add existing user to tenant
  - Create new user and add to tenant (pilot phase)
- **Subscription Limits:** Checked before adding members

#### 2. Update Member Roles
- **Permission Required:** Context-dependent
  - Viewer → Member: Any admin
  - Member → Admin: Owner only
  - Admin → Member: Owner only
- **Restrictions:** Cannot change Owner role via standard UI

#### 3. Remove Members
- **Permission Required:** Owner only
- **Restrictions:** Cannot remove the Owner

#### 4. Transfer Ownership
- **Permission Required:** Owner only
- **Requirements:**
  - New owner must be an existing Admin
  - Two-step confirmation process
  - Irreversible operation
- **Changes:**
  - New user becomes Owner
  - Previous owner becomes Admin

### Team Page

Location: `frontend/src/pages/app/settings/team/TeamPage.tsx`

**Features:**
- Team member list with role indicators
- Filter by role
- Search by name/email
- Member details modal
- Activity tracking
- Transfer ownership modal
- Error recovery for missing user data

**Security:**
- Removed insecure owner_id fallback
- Proper access validation through backend
- Permission-based UI rendering

## Backend Implementation

### Tenant Member Endpoints

Location: `services/tenant/app/api/tenant_members.py`

**Endpoints:**
1. `POST /tenants/{tenant_id}/members/with-user` - Add member with optional user creation
2. `POST /tenants/{tenant_id}/members` - Add existing user
3. `GET /tenants/{tenant_id}/members` - List members
4. `PUT /tenants/{tenant_id}/members/{user_id}/role` - Update role
5. `DELETE /tenants/{tenant_id}/members/{user_id}` - Remove member
6. `POST /tenants/{tenant_id}/transfer-ownership` - Transfer ownership
7. `GET /tenants/{tenant_id}/admins` - Get tenant admins
8. `DELETE /tenants/user/{user_id}/memberships` - Delete user memberships (internal)

### Member Enrichment

The backend enriches tenant members with user data from the Auth service:
- User full name
- Email
- Phone
- Last login
- Language/timezone preferences

**Error Handling:**
- Graceful degradation if Auth service unavailable
- Fallback to user_id if enrichment fails
- Frontend displays warning for incomplete data

## Best Practices

### When to Use Which Permission Check

1. **Global Permission Check:**
   - Platform administration
   - Cross-tenant operations
   - System-wide features
   - User management at platform level

2. **Tenant Permission Check:**
   - Team management
   - Organization-specific resources
   - Tenant settings
   - Most application features

3. **Combined Permission Check:**
   - Features requiring elevated access
   - Admin-only operations that can be done by either global or tenant admins
   - Owner-specific operations with super_admin override

### Security Considerations

1. **Never use client-side owner_id comparison as fallback**
   - Always validate through backend
   - Use proper access endpoints

2. **Always validate permissions on the backend**
   - Frontend checks are for UX only
   - Backend is source of truth

3. **Use unified permission system**
   - Consistent permission checking
   - Clear documentation
   - Type-safe

4. **Audit critical operations**
   - Log role changes
   - Track ownership transfers
   - Monitor member additions/removals

## Future Enhancements

### Planned Features

1. **Role Change History**
   - Audit trail for role changes
   - Display who changed roles and when
   - Integrated into member details modal

2. **Fine-grained Permissions**
   - Custom permission sets
   - Permission groups
   - Resource-level permissions

3. **Invitation Flow**
   - Replace direct user creation
   - Email-based invitations
   - Invitation expiration

4. **Member Status Management**
   - Activate/deactivate members
   - Suspend access temporarily
   - Bulk status updates

5. **Advanced Team Features**
   - Sub-teams/departments
   - Role templates
   - Bulk role assignments

## Troubleshooting

### Common Issues

#### "Permission Denied" Errors
- **Cause:** User lacks required role or permission
- **Solution:** Verify user's tenant membership and role
- **Check:** `currentTenantAccess` in tenant store

#### Missing User Data in Team List
- **Cause:** Auth service enrichment failed
- **Solution:** Check Auth service connectivity
- **Workaround:** Frontend displays warning and fallback data

#### Cannot Transfer Ownership
- **Cause:** No eligible admins
- **Solution:** Promote a member to admin first
- **Requirement:** New owner must be an existing admin

#### Access Validation Stuck Loading
- **Cause:** Tenant access endpoint not responding
- **Solution:** Reload page or check backend logs
- **Prevention:** Backend health monitoring

## API Reference

### Frontend

**Permission Functions:** `frontend/src/utils/permissions.ts`
**Protected Routes:** `frontend/src/router/ProtectedRoute.tsx`
**Role Types:** `frontend/src/types/roles.ts`
**Team Management:** `frontend/src/pages/app/settings/team/TeamPage.tsx`
**Transfer Modal:** `frontend/src/components/domain/team/TransferOwnershipModal.tsx`

### Backend

**Tenant Members API:** `services/tenant/app/api/tenant_members.py`
**Tenant Models:** `services/tenant/app/models/tenants.py`
**Tenant Service:** `services/tenant/app/services/tenant_service.py`

## Migration Notes

### From Single Role System

If migrating from a single role system:

1. **Audit existing roles**
   - Map old roles to new structure
   - Identify tenant vs global roles

2. **Update permission checks**
   - Replace old checks with unified system
   - Test all protected routes

3. **Migrate user data**
   - Set appropriate global roles
   - Create tenant memberships
   - Ensure owners are properly set

4. **Update frontend components**
   - Use new permission functions
   - Update route guards
   - Test all scenarios

## Support

For issues or questions about the roles and permissions system:

1. **Check this documentation**
2. **Review code comments** in permission utilities
3. **Check backend logs** for permission errors
4. **Verify tenant membership** in database
5. **Test with different user roles** to isolate issues

---

**Last Updated:** 2025-10-31
**Version:** 1.0.0
**Status:** ✅ Production Ready