Autenticacion y RBAC

Flujo de autenticacion

Login (desde el frontend)

1. El usuario inicia sesion en la web via Zauru OAuth.
2. El frontend recibe un code de Zauru y lo valida con /api/userinfo.
3. El frontend envia email, password y entity_id a POST /api/auth/login en BoostAPI.
4. BoostAPI verifica el password contra bcrypt en la tabla users.
5. Se resuelven los permisos efectivos del usuario (ver RBAC abajo).
6. Se devuelve un JWT con 8 horas de expiracion con el payload:

{
  "id": 1,
  "email": "usuario@empresa.com",
  "zauru_user_id": 42,
  "role_id": 3,
  "role_name": "vendedor",
  "entity_id": 1,
  "employee_role_id": 5,
  "user_role_id": null,
  "role_source": "employee",
  "employee_id": 7,
  "zauru_employee_id": 100,
  "client_kind": "web"
}

7. Se reconcilia la sesion Zauru del usuario (perfil, GraphQL JWT) y se almacenan credenciales cifradas.

Bootstrap de password (temporal)

Durante rollout inicial, si AUTH_ALLOW_FIRST_LOGIN_PASSWORD_BOOTSTRAP=true, el primer login de un usuario puede establecer su password automaticamente validando contra la API key de Zauru.

Cambio de entidad

POST /api/auth/change-entity permite cambiar de empresa sin cerrar sesion. Devuelve un nuevo JWT con la entidad actualizada.

Sistema RBAC (Control de Acceso Basado en Roles)

Tres capas de suscripciones

Los permisos se resuelven desde tres niveles de suscripcion, en orden de prioridad:

Nivel	Busqueda	Descripcion
1. Employee subscription	employee_id + entity_id	Permisos del empleado en esta empresa
2. User-entity subscription	user_id + entity_id	Permisos del usuario en esta empresa
3. User-global subscription	user_id + entity_id=NULL	Permisos globales del usuario

Resolucion de permisos

1. Si la suscripcion global tiene rol super_admin, el usuario obtiene TODOS los permisos.
2. Si no, se combinan los permisos base del rol + overrides por suscripcion.
3. Los overrides pueden ser ALLOW (agregar permiso) o DENY (quitar permiso) por codigo.
4. Los permisos soportan implicaciones (ej: leads.create implica leads.view).

Catalogo de permisos (44 codigos)

Organizados en 5 modulos:

Cartera (8 permisos)

• cartera.leads_list.view – Ver lista de leads
• cartera.clients_list.view – Ver lista de clientes
• cartera.lead_detail.view / .edit – Ver/editar detalle de lead
• cartera.client_detail.view / .edit – Ver/editar detalle de cliente
• cartera.seller_assignment – Asignar vendedor
• cartera.export_excel – Exportar a Excel

Registros (15 permisos)

• groups.view / .create / .edit
• leads.view / .create / .edit
• contacts.view / .create / .edit
• group_assignments.manage / lead_assignments.manage / contact_assignments.manage
• entity_channel_accounts.view / .create / .edit

Catalogo (5 permisos)

• catalog.view – Ver catalogo de productos
• catalog.seller_change – Cambiar vendedor en catalogo
• orders.view / .create
• quotes.view / .create

Configuracion (7 permisos)

• custom_field_types.view
• custom_field_groups.view / .create / .edit
• custom_fields.view / .create / .edit

Administracion (5 permisos)

• roles.view / .create / .edit
• subscriptions.view / .create / .edit
• permissions.catalog.view
• communications.command_palette.view

Uso en controladores

// Solo autenticacion (cualquier usuario logueado)
@Authentication()

// Autenticacion + permiso especifico
@Authentication('leads.create')

// Acceder al usuario en el handler
@GetUser() user: JwtPayload

Verificacion en cada request

El JWT Strategy re-resuelve los permisos desde la base de datos en cada request (no se cachean en el token). Esto garantiza que cambios de permisos se aplican inmediatamente.

Endpoints de auth

Metodo	Ruta	Auth	Descripcion
POST	/api/auth/login	No	Login con email + password + entity_id
POST	/api/auth/change-entity	JWT	Cambiar entidad activa
GET	/api/auth/my-entities	JWT	Listar entidades del usuario
POST	/api/auth/zauru-session/sync	JWT	Forzar reconciliacion de sesion Zauru
GET	/api/auth/zauru-session	JWT	Obtener snapshot de sesion Zauru
DELETE	/api/auth/zauru-session	JWT	Limpiar sesion Zauru

Endpoints de permisos

Metodo	Ruta	Auth	Descripcion
GET	/api/permissions/schema	JWT	Schema completo de permisos (cacheable con ETag)
GET	/api/permissions/me	JWT	Permisos efectivos del usuario actual
GET	/api/permissions	permissions.catalog.view	Registros de permisos en BD

Referencia privada: Ver BoostAPI/docs/auth-rbac-contract.md y BoostAPI/docs/permissions-schema-and-grants.md para contratos detallados.