IAM (Identity & Access Management)

El módulo IAM es el guardia de seguridad de Yastubo. Gestiona el registro de usuarios, la persistencia de sesiones en Redis y la jerarquía de permisos mediante RBAC.

🔐 Autenticación y Sesiones

1. Registro de Usuarios

POST /api/v1/auth/register Público. Crea un usuario base con estado is_verified: False. Todos los usuarios nuevos reciben por defecto el rol de CLIENTE.

POST /api/v1/auth/login Genera un par de tokens (Access & Refresh). La sesión se registra en Redis para permitir la invalidación remota (Logout Global).

👑 Gestión de Roles y Permisos (RBAC)

Yastubo utiliza una arquitectura de roles granulares. Cada acción en la API está protegida por una validación de permisos específicos.

3. Asignación de Roles (Administrativo)

POST /api/v1/auth/roles/assign

Role: ADMIN

Permite elevar el rango de un usuario o cambiar sus permisos operativos.

Esquema de Petición (`RoleAssign`)

{
  "user_id": "uuid-del-usuario",
  "role_id": "uuid-del-rol"
}

Catálogo de Roles por Defecto

Rol	Nivel	Permisos Clave	Descripción
`ADMIN`	100	`users:manage`, `plans:write`, `audit:read`	Control total del sistema e infraestructura.
`VENDEDOR`	50	`plans:read`, `emission:write`	Puede cotizar y emitir pólizas.
`CLIENTE`	10	`portal:read`, `plans:read`	Acceso a su propio perfil y certificados.

🛠️ Bootstrapping: Inicialización de Permisos

Para que el sistema de permisos funcione correctamente en una base de datos nueva, se debe ejecutar el script de seeding de roles:

uv run python scripts/seed_roles.py

Efecto: Crea los roles ADMIN, VENDEDOR y CLIENTE y les asigna sus permisos técnicos base en la base de datos.

🛡️ Políticas de Seguridad Actuarial

Validación de Contraseñas (Password History)

El sistema implementa una política de no reutilización de contraseñas.

Regla: Un usuario no puede cambiar su contraseña a ninguna de las últimas 5 contraseñas utilizadas anteriormente.
Falla: Retorna 400 Bad Request con el mensaje: "New password cannot be one of the last 5 passwords used".

Seguridad de Refresh Tokens

Los tokens de refresco son de un solo uso. Al generar un nuevo access_token mediante /refresh, el refresh_token anterior queda invalidado en la base de datos y en Redis para prevenir ataques de replay.

🔍 Consulta de Perfil (Self-Service)

4. Obtener mi información (Me)

GET /api/v1/auth/me Retorna el perfil completo del usuario autenticado, incluyendo su lista de roles activos y permisos calculados.