aloux-iam

Librería Node.js para gestión de identidad y acceso (IAM) en APIs Express + MongoDB.

Instalación y configuración

1. Instalar

npm install aloux-iam

2. Registrar en Express

const express = require('express')
const mongoose = require('mongoose')
const cookieParser = require('cookie-parser')
const { IAMRouter } = require('aloux-iam')

const app = express()

app.use(express.json())
app.use(cookieParser())
app.use(IAMRouter)          // monta todos los endpoints /iam/*

mongoose.connect(process.env.MONGO_URI)
app.listen(3000)

3. Usar el middleware en tus propias rutas

const { IAMAuth } = require('aloux-iam')

// Protege cualquier ruta tuya con el mismo middleware
app.get('/api/mi-recurso', IAMAuth, (req, res) => {
  // req.user  → usuario autenticado con funciones/permisos
  // req.token → JWT string
  res.json({ user: req.user })
})

4. Usar los modelos de Mongoose

const { IAMUserModel, IAMFunctionsModel, IAMPermissionModel, IAMMenuModel } = require('aloux-iam')

// Consulta directa al modelo de usuario
const users = await IAMUserModel.find({ status: 'Activo' })

Variables de entorno

Configura estas variables en tu archivo .env antes de iniciar el servidor.

Autenticación y sesión

Emails y notificaciones

AWS Storage

Google Cloud / BigQuery

Historial y observabilidad

Multi-app y branding

Exportaciones de la librería

Configurar control de acceso

Para proteger tus propios endpoints con aloux-iam, sigue estos pasos:

Ejemplo completo

// 1. Crear el permiso
POST /iam/permission
{
  "description": "Ver productos",
  "method":      "GET",
  "api":         "productos",
  "endpoint":    "/api/productos",
  "auth":        1,
  "status":      "Activo"
}
// → { _id: "abc123", ... }

// 2. Crear la función con ese permiso
POST /iam/functions
{
  "name":         "Catálogo",
  "_permissions": ["abc123"],
  "_menus":       []
}
// → { _id: "fun456", ... }

// 3. Asignar función al usuario
PATCH /iam/user/:USER_ID
{ "_functions": ["fun456"] }

// 4. Tu endpoint protegido
const { IAMAuth } = require('aloux-iam')

app.get('/api/productos', IAMAuth, (req, res) => {
  res.json({ productos: [] })
})

Permisos default

Si un permiso tiene "default": true, cualquier usuario autenticado puede acceder al endpoint sin importar sus funciones. Útil para endpoints compartidos como perfil propio, listado de menú, etc.

POST /iam/permission
{
  "description": "Ver perfil propio",
  "method":      "GET",
  "api":         "perfil",
  "endpoint":    "/api/mi-perfil",
  "auth":        1,
  "default":     true,
  "status":      "Activo"
}

Flujo de autenticación

Cada request a un endpoint protegido pasa por el siguiente flujo:

Respuesta de error estándar

{
  "code":       401,
  "title":      "Error de autenticación",
  "detail":     "No se encontró el usuario",
  "suggestion": "Vuelve a iniciar sesión"
}

Endpoints de autenticación — sin token

Ejemplo: Login

// Request
POST /iam/auth/login
{
  "email": "usuario@email.com",
  "pwd":   "MiContraseña123!"
}

// Response 200 — login exitoso
{
  "token":     "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "changePwd": false
}

// Response 200 — requiere 2FA
{
  "requires2FA": true,
  "needsSetup":  false,
  "tempToken":   "eyJ..."
}

Ejemplo: Verificar email

POST /iam/auth/email
{ "email": "usuario@email.com" }

// Response 200 — email existe
{ "email": true, "name": "Juan", "lastName": "Pérez" }

// Response 201 — email nuevo (se creó UserProvisional)
{ "email": false, "name": null, "_id": "..." }

Endpoints de autenticación — con token

2FA / TOTP

aloux-iam soporta autenticación de dos factores compatible con Google Authenticator, Authy y cualquier app TOTP.

Flujo de activación

Flujo de login con 2FA activo

Endpoints TOTP

Rate limiting

Los endpoints de login están protegidos con un rate limiter in-memory sin dependencias externas.

// Response 429
{
  "code":       429,
  "title":      "Demasiados intentos",
  "detail":     "Has superado el límite de intentos permitidos.",
  "suggestion": "Espera unos minutos antes de intentarlo nuevamente."
}

Además, si un usuario falla FAILED_ATTEMPS veces su contraseña, su cuenta cambia a estado Bloqueado en la base de datos. Para desbloquearlo se usa la opción de recuperación de contraseña.

Usuarios

Paginación (request)

POST /iam/user/pages
{
  "config": {
    "page":         1,
    "itemsPerPage": 10,
    "sort":         { "createdAt": -1 }
  },
  "filter": {
    "search": "juan"   // busca en name y lastName
  }
}

// Response
{
  "currentPage":   1,
  "totalPages":    5,
  "perPage":       10,
  "count":         48,
  "remainingPages": 4,
  "items":         [ ... ]
}

Tipos de usuario

Crear una cuenta de servicio

Omite email y pwd en el body. El sistema detecta automáticamente que es una cuenta de servicio y genera el token en la respuesta:

POST /iam/user
Authorization: Bearer <tu-token-admin>

{
  "name": "mi-servicio",
  "_functions": [],
  "_company": ["<COMPANY_ID>"]
}

// Response 201
{
  "_id": "64a1...",
  "name": "mi-servicio",
  "tokens": [
    {
      "token": "eyJhbGci...",   // guárdalo, no se muestra de nuevo
      "type":  "api"
    }
  ]
}

Usar el token de servicio

Incluye el token en el header Authorization de cada request, igual que un usuario normal:

Authorization: Bearer eyJhbGci...

Asignar permisos a una cuenta de servicio

En lugar de Funciones, las cuentas de servicio usan el campo data.apis: un arreglo de IDs de Permiso a los que tiene acceso. Actualiza el usuario con PATCH /iam/user/:USER_ID:

PATCH /iam/user/<SERVICE_USER_ID>
Authorization: Bearer <tu-token-admin>

{
  "data": {
    "apis": [
      "<PERMISSION_ID_1>",
      "<PERMISSION_ID_2>"
    ]
  }
}

Funciones

Las Funciones agrupan conjuntos de Permisos y Menús. Se asignan a usuarios para controlar su acceso.

Permisos

Cada permiso representa un endpoint específico. El middleware los valida en cada request.

Estructura de un permiso

{
  "description": "Ver lista de usuarios",
  "method":      "GET",
  "api":         "user",
  "endpoint":    "/iam/user",
  "auth":        1,       // 1 = requiere autenticación
  "default":     false,  // true = accesible sin verificar función
  "status":      "Activo"
}

Menús

Estructura de navegación configurable. Las Funciones incluyen una lista de menús que se expone al frontend.

Empresas (Companies)

Negocios (Businesses)

Los negocios pertenecen a una empresa y pueden tener su propia Google Key para BigQuery/Storage.

Etiquetas (Labels)

Logs

Sistema de log para registrar eventos de negocio asociados a usuarios, empresas y negocios.

Historial de acciones

Registro automático de requests. Se activa por endpoint mediante variables de entorno.

Cada registro contiene: método HTTP, path, payload enviado, respuesta del endpoint, usuario responsable y timestamp.

Modelo: User

Campos principales

Modelo: Functions

Modelo: Permission

Modelo: Menu

Modelo: Company

Modelo: Business

AWS — S3, SES, SNS

Disponible como AlouxAWS en las exportaciones. Requiere credenciales AWS configuradas en el entorno (AWS_REGION, AWS_BUCKET, AWS_EMAIL_SENDER).

S3 — Subir archivos al bucket

El router incluye express-fileupload de forma automática. Desde tus endpoints puedes acceder a los archivos via req.files y pasarlos directamente a AlouxAWS.upload().

const { AlouxAWS } = require('aloux-iam')

app.post('/api/upload', IAMAuth, async (req, res) => {
  const file = req.files?.archivo   // campo del form-data
  if (!file) return res.status(400).send({ error: 'No se recibió archivo' })

  // Ruta dentro del bucket (sin slash inicial)
  const path = `uploads/${Date.now()}-${file.name}`

  const url = await AlouxAWS.upload(path, file)
  // url → URL pública del archivo en S3

  res.json({ url })
})

S3 — Eliminar archivos

// Eliminar un archivo (pasa la ruta dentro del bucket)
await AlouxAWS.delete('uploads/archivo.jpg')

// Eliminar varios archivos de una sola llamada
await AlouxAWS.deleteMany([
  'uploads/foto1.jpg',
  'uploads/foto2.png'
])

SES — Enviar email con template

El método send() lee un archivo HTML desde la ruta definida en la variable de entorno indicada, reemplaza los placeholders de marca y lo envía via AWS SES.

const { AlouxAWS } = require('aloux-iam')

// Leer template y enviar
const html = fs.readFileSync(process.env.TEMPLATE_ACCOUNT, 'utf8')
await AlouxAWS.send(
  'destinatario@email.com',  // para
  html,                        // contenido HTML
  'Bienvenido a la plataforma' // asunto
)

SES — Enviar email personalizado

Usa sendCustom() cuando quieras enviar HTML propio sin usar el sistema de templates de la librería.

const html = `
<h1>Hola, </h1>
<p>Tu pedido #12345 fue confirmado.</p>
`

await AlouxAWS.sendCustom(
  'cliente@email.com',
  html,
  'Confirmación de pedido'
)

SNS — Enviar SMS

await AlouxAWS.sendMessagePhone(
  '+521234567890',       // número en formato E.164
  'Tu código es: 4821'  // mensaje de texto
)

Templates de email — placeholders

Los archivos HTML de templates pueden usar estos tokens que se reemplazan automáticamente al enviar:

Variables de entorno requeridas para AWS

Google BigQuery

Disponible como AlouxBQ.

const { AlouxBQ } = require('aloux-iam')

// Insertar fila en una tabla
await AlouxBQ.callAppendRows({ name: 'Juan', email: 'juan@email.com' }, 'mi_tabla')

// Convertir timestamp a formato BigQuery
const dt = AlouxBQ.factoryDateTime(Date.now()) // "2026-05-25 12:00:00"

Generador de contraseñas

GET /iam/generatePassword?length=16

// Response
{ "password": "aB3!xK9@mN2#pQ7$" }

Garantiza al menos una letra minúscula, una mayúscula, un número y un carácter especial.

Utils

const utils = require('aloux-iam/lib/config/utils')

// Escapa metacaracteres de regex en un string
utils.escapeRegex('hola (mundo)')

// Genera objeto de respuesta paginada
utils.generatePaginationResponse(count, page, itemsPerPage, items)

// Formatea y envía respuesta de error estándar
utils.responseError(res, error)

// Resuelve Google Key del negocio
utils.resolveGkey(business) // → { gkey, source }

Seguridad

Medidas aplicadas en la versión actual: