# 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

```gherkin
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

```gherkin
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

```gherkin
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

```gherkin
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)

```gherkin
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

```gherkin
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

```gherkin
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

```typescript
// 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

```typescript
@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

```typescript
// 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 |