erp-core/docs/01-fase-foundation/MGN-003-roles/historias-usuario/US-MGN003-004.md

US-MGN003-004: Control de Acceso RBAC

Identificacion

Campo	Valor
ID	US-MGN003-004
Modulo	MGN-003 Roles/RBAC
Sprint	Sprint 2
Prioridad	P0 - Critica
Story Points	8
Estado	Ready
Autor	System
Fecha	2025-12-05

---

Historia de Usuario

Como desarrollador del sistema Quiero que el sistema valide automaticamente los permisos en cada request Para garantizar que los usuarios solo accedan a funcionalidades autorizadas

---

Criterios de Aceptacion

Escenario 1: Acceso con permiso valido

Given un usuario con permiso "users:read"
  And endpoint GET /api/v1/users requiere "users:read"
When el usuario hace la solicitud
Then el sistema permite el acceso
  And retorna status 200 con los datos

Escenario 2: Acceso denegado

Given un usuario con permiso "users:read" solamente
  And endpoint DELETE /api/v1/users/:id requiere "users:delete"
When el usuario intenta eliminar
Then el sistema retorna status 403
  And el mensaje es "No tienes permiso para realizar esta accion"
  And NO revela que permiso falta (seguridad)

Escenario 3: Wildcard permite acceso

Given un usuario con permiso "users:*"
  And endpoint requiere "users:delete"
When el usuario hace la solicitud
Then el sistema permite el acceso
  And wildcard cubre el permiso especifico

Escenario 4: Super Admin bypass

Given un usuario con rol "super_admin"
  And endpoint requiere "cualquier:permiso"
When el usuario hace la solicitud
Then el sistema permite el acceso
  And no valida permisos especificos

Escenario 5: Permisos alternativos (OR)

Given endpoint con @AnyPermission('users:update', 'users:admin')
  And usuario tiene solo "users:admin"
When el usuario hace la solicitud
Then el sistema permite el acceso
  And basta con tener UNO de los permisos

Escenario 6: Owner puede acceder

Given endpoint PATCH /api/v1/users/:id con @OwnerOrPermission('users:update')
  And usuario accede a su propio perfil (id = su id)
  And usuario NO tiene permiso "users:update"
When el usuario actualiza su perfil
Then el sistema permite el acceso
  And ser owner del recurso es suficiente

Escenario 7: Cache de permisos

Given permisos de usuario cacheados
When el admin cambia roles del usuario
Then el cache se invalida inmediatamente
  And siguiente request recalcula permisos

---

Mockup / Wireframe

Flujo de validacion (interno del sistema):

┌─────────────────────────────────────────────────────────────────┐
│                    Request HTTP                                  │
│                         │                                        │
│                         ▼                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  1. JwtAuthGuard                                         │   │
│  │     - Valida token JWT                                   │   │
│  │     - Extrae usuario del token                           │   │
│  └─────────────────────────────────────────────────────────┘   │
│                         │                                        │
│                         ▼                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  2. TenantGuard                                          │   │
│  │     - Verifica tenant del usuario                        │   │
│  │     - Aplica contexto de tenant                          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                         │                                        │
│                         ▼                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  3. RbacGuard                                            │   │
│  │     - Lee decoradores @Permissions, @Roles               │   │
│  │     - Obtiene permisos efectivos (cache 5min)            │   │
│  │     - Valida segun modo (AND/OR)                         │   │
│  │     - Super Admin bypass                                 │   │
│  └─────────────────────────────────────────────────────────┘   │
│                         │                                        │
│                         ▼                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  4. Controller                                           │   │
│  │     - Ejecuta logica de negocio                          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

Notas Tecnicas

Decoradores Disponibles

// Requiere TODOS los permisos (AND)
@Permissions('users:read', 'users:update')

// Requiere AL MENOS UNO (OR)
@AnyPermission('users:update', 'users:admin')

// Requiere uno de los roles
@Roles('admin', 'manager')

// Ruta publica (sin auth)
@Public()

// Owner o permiso
@OwnerOrPermission('users:update')

Uso en Controllers

@Controller('api/v1/users')
@UseGuards(JwtAuthGuard, TenantGuard, RbacGuard)
export class UsersController {

  @Get()
  @Permissions('users:read')
  findAll() { }

  @Delete(':id')
  @Permissions('users:delete')
  remove() { }

  @Patch(':id')
  @OwnerOrPermission('users:update')
  update() { }
}

Cache de Permisos

// TTL: 5 minutos
// Key: rbac:permissions:{userId}
// Invalidacion: al cambiar roles del usuario

---

Definicion de Done

• Decoradores @Permissions, @AnyPermission, @Roles
• Decorador @Public para rutas sin auth
• Decorador @OwnerOrPermission
• RbacGuard implementado
• OwnerGuard implementado
• Cache de permisos en Redis
• Invalidacion de cache automatica
• Log de accesos denegados
• Tests unitarios para guards
• Tests de integracion RBAC
• Code review aprobado

---

Estimacion

Tarea	Horas
Backend: Decoradores	2h
Backend: RbacGuard	4h
Backend: OwnerGuard	2h
Backend: Cache service	2h
Backend: Invalidacion cache	2h
Backend: Tests guards	3h
Backend: Tests integracion	3h
Total	18h

---

Historial

Version	Fecha	Autor	Cambios
1.0	2025-12-05	System	Creacion inicial