Seguridad

Zentto implementa un modelo de seguridad por capas que cubre autenticacion, autorizacion granular (RBAC), auditoria automatica y controles de precio/aprobacion.

Autenticacion JWT

Flujo de login

1. POST /v1/auth/login  { username, password }
2. API verifica credenciales contra sec.User (bcrypt en Node.js)
3. Si valido, genera JWT con claims del usuario
4. Cliente almacena JWT y lo envia en header Authorization

Token JWT

El token incluye los siguientes claims:

Claim	Descripcion
userId	ID del usuario
username	Nombre de usuario
companyId	Empresa activa
branchId	Sucursal activa
isAdmin	Flag de administrador
roles	Array de roles asignados

Verificacion de password

La verificacion de passwords se realiza en Node.js usando bcrypt, no en SQL. La tabla sec.User almacena el hash bcrypt del password.

const isValid = await bcrypt.compare(plainPassword, user.PasswordHash);

Refresh token

El endpoint POST /v1/auth/refresh permite renovar el JWT sin re-autenticar, siempre que el token actual no haya expirado.

Proteccion de rutas

Todas las rutas bajo /v1/* (excepto /v1/auth/login) requieren JWT valido. El middleware de autenticacion verifica:

1. Presencia del header Authorization: Bearer <token>
2. Validez del JWT (firma + expiracion)
3. Existencia del usuario en BD

RBAC (Control de Acceso Basado en Roles)

Estructura de permisos

El sistema RBAC se basa en tres tablas principales:

sec.Permission             -- Catalogo de permisos (ModuleCode.ActionCode)
sec.RolePermission         -- Permisos asignados a cada rol
sec.UserPermissionOverride -- Overrides especificos por usuario

Catalogo de permisos

Cada permiso sigue el formato {ModuleCode}.{ActionCode}. El catalogo cubre 15 modulos con 8 acciones cada uno:

ModuleCode	Modulo
ventas	Ventas y facturacion
compras	Compras
inventario	Inventario
bancos	Bancos y finanzas
contabilidad	Contabilidad
nomina	Nomina
rrhh	Recursos humanos
pos	Punto de venta
restaurante	Restaurante
auditoria	Auditoria
crm	CRM
manufactura	Manufactura
flota	Flota
logistica	Logistica
permisos	Administracion de permisos

ActionCode	Descripcion
VIEW	Ver/listar registros
CREATE	Crear nuevos registros
EDIT	Editar registros existentes
DELETE	Eliminar registros
VOID	Anular documentos
APPROVE	Aprobar documentos/solicitudes
EXPORT	Exportar datos
ADMIN	Administracion del modulo

Resolucion de permisos

El middleware RBAC resuelve permisos con la siguiente prioridad:

1. Si el usuario es admin     --> PERMITIR (siempre)
2. Si existe Override usuario  --> usar ese valor
3. Si existe RolePermission    --> usar valor del rol
4. Si no hay configuracion     --> PERMITIR (graceful degradation)

Middleware RBAC

Zentto ofrece dos formas de aplicar RBAC:

1. requirePermission(module, action) — Por ruta

import { requirePermission } from "../../middleware/rbac.js";

router.post("/", requirePermission("ventas", "CREATE"), async (req, res) => {
  // Solo usuarios con permiso ventas.CREATE llegan aqui
});

2. autoRbac — Global automatico

Resuelve modulo y accion automaticamente desde el path y metodo HTTP:

• POST /v1/ventas/... verifica ventas.CREATE
• PUT /v1/inventario/... verifica inventario.EDIT
• POST /v1/contabilidad/.../anular verifica contabilidad.VOID

El autoRbac solo verifica en metodos que modifican datos (POST/PUT/PATCH/DELETE). Los GET pasan sin verificacion.

Cache de permisos

Los resultados de verificacion se cachean en memoria con TTL de 5 minutos para evitar consultas repetitivas a la BD.

API de permisos

La gestion de permisos se realiza desde /v1/permisos:

GET  /v1/permisos/permisos                          -- Catalogo completo
GET  /v1/permisos/roles/:roleId/permisos            -- Permisos de un rol
POST /v1/permisos/roles/:roleId/permisos/bulk       -- Asignar permisos masivamente
POST /v1/permisos/usuarios/:userId/permisos/override -- Override por usuario
GET  /v1/permisos/usuarios/:userId/verificar/:code  -- Verificar permiso especifico

Auditoria automatica

Middleware audit-trail

El middleware de auditoria intercepta automaticamente todas las operaciones POST, PUT, PATCH y DELETE exitosas y registra en audit.AuditLog.

Caracteristicas:

• Best-effort: nunca bloquea la respuesta al cliente
• Fire-and-forget: usa setImmediate() para no impactar latencia
• Solo exitosas: solo registra respuestas con status 2xx
• Auto-resolucion: detecta modulo, entidad, accion e ID automaticamente

Datos registrados

Campo	Descripcion	Ejemplo
UserId	ID del usuario	42
UserName	Nombre de usuario	admin
ModuleName	Modulo afectado	ventas
EntityName	Entidad	documentos-venta
EntityId	ID de la entidad	FAC-0001
ActionType	Tipo de accion	CREATE, UPDATE, DELETE, VOID
Summary	Resumen legible	CREATE documentos-venta #FAC-0001
NewValues	Body del request (truncado a 2000 chars)	{"customerId": 5, ...}
IPAddress	IP del cliente	192.168.1.100

Rutas excluidas

No se auditan operaciones en:

• /health — health checks
• /sistema/notificaciones — polling de notificaciones
• /auditoria/ — evitar recursion
• /config, /settings — configuracion
• /auth/refresh — renovacion de token

Consulta de auditoria

GET /v1/auditoria/logs?module=ventas&from=2026-01-01&to=2026-03-31
GET /v1/auditoria/logs?userId=42&actionType=DELETE

Restricciones de precio

El sistema permite configurar restricciones de descuento y precio por rol o usuario:

Restriccion	Descripcion
MaxDiscountPercent	Descuento maximo permitido (ej: 15%)
MinPricePercent	Precio minimo como % del precio lista (ej: 85%)
MaxCreditLimit	Limite de credito maximo otorgable
RequiresApprovalAbove	Monto a partir del cual requiere aprobacion

API de restricciones

GET  /v1/permisos/precios                   -- Listar restricciones
POST /v1/permisos/precios                   -- Crear/actualizar restriccion
GET  /v1/permisos/precios/verificar/:userId -- Verificar restriccion del usuario

Flujo de verificacion

1. Vendedor aplica descuento del 20%
2. Frontend consulta /v1/permisos/precios/verificar/:userId
3. Si MaxDiscountPercent = 15% --> bloquear o solicitar aprobacion
4. Si RequiresApprovalAbove y monto > umbral --> crear solicitud de aprobacion

Flujo de aprobacion

Para operaciones que superan los umbrales configurados, se activa un flujo de aprobacion:

Reglas de aprobacion

Configuracion en sec.ApprovalRule:

Campo	Descripcion
ModuleCode	Modulo (ej: ventas)
DocumentType	Tipo de documento (ej: FACTURA)
MinAmount	Monto minimo para activar la regla
MaxAmount	Monto maximo (opcional)
RequiredRoleId	Rol requerido para aprobar
ApprovalLevels	Niveles de aprobacion requeridos

Ciclo de vida de una solicitud

PENDING --> APPROVED
        --> REJECTED

1. El sistema detecta que la operacion requiere aprobacion
2. Crea una solicitud con estado PENDING
3. Un usuario con el rol requerido aprueba o rechaza
4. Si se aprueba, la operacion procede

API de aprobaciones

GET  /v1/permisos/aprobaciones             -- Listar solicitudes
POST /v1/permisos/aprobaciones             -- Crear solicitud
GET  /v1/permisos/aprobaciones/:id         -- Detalle
POST /v1/permisos/aprobaciones/:id/accion  -- Aprobar/rechazar

Basic Auth para documentacion API

La documentacion de la API (Swagger/OpenAPI) esta protegida con Basic Auth separado del JWT, para permitir acceso a desarrolladores sin necesidad de un usuario del sistema.

Resumen de capas de seguridad

Capa	Mecanismo	Scope
Autenticacion	JWT + bcrypt	Todas las rutas /v1/*
Autorizacion	RBAC (Permission + Role + Override)	Operaciones de escritura
Auditoria	Middleware automatico best-effort	POST/PUT/PATCH/DELETE exitosos
Restricciones	Price restrictions + approval workflows	Descuentos y montos altos
Multi-tenant	CompanyId + BranchId en JWT	Aislamiento de datos