imansi-auth-node

Servidor de autenticación completo para Node.js: registro, login, 2FA, OAuth (GitHub y Google), sesiones multi-dispositivo y correos transaccionales.

---

¿Qué es?

imansi-auth-node es el servidor de autenticación del ecosistema Imansi. Montás un router en tu app de Express y tenés todos los endpoints de autenticación funcionando: registro, login, 2FA, OAuth, sesiones, recuperación de contraseña y más.

Está diseñado para funcionar en conjunto con imansi-auth-react en el frontend.

---

Características

• Registro y login con email y contraseña (bcrypt)
• Verificación en dos pasos (2FA) por consola o email
• OAuth con GitHub y Google (login social)
• Refresh tokens con rotación automática
• Sesiones multi-dispositivo con revocación individual
• Cookies httpOnly para máxima seguridad contra XSS
• Recuperación de contraseña por correo electrónico
• Cambio de contraseña estando logueado
• Correos transaccionales integrados con imansi-correos-node
• Rate limiting para evitar fuerza bruta
• CLI integrado con verificación automática del sistema
• PostgreSQL como única dependencia de base de datos

---

Instalación

npm install imansi-auth-node

Requiere Node.js 18+ y PostgreSQL 12+.

---

Uso rápido

1. Configurar el .env

Copiá el archivo de ejemplo:

cp node_modules/imansi-auth-node/.env.example .env

Configurá las variables obligatorias:

PUERTO=3000
URL_FRONTEND=http://localhost:5173

PG_HOST=localhost
PG_PUERTO=5432
PG_USUARIO=postgres
PG_CONTRASENA=tu-contraseña
PG_BASE_DE_DATOS=miapp

JWT_SECRETO=generá-una-cadena-larga-y-aleatoria
JWT_EXPIRACION=15m

Generá un JWT_SECRETO seguro con:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

2. Verificar que todo esté bien

npx imansi-auth-node iniciar

Ese comando verifica el .env, la conexión a PostgreSQL, las tablas y el SMTP.

3. Montar el servidor

import express from 'express';
import 'dotenv/config';
import { crearServidorAutenticacion } from 'imansi-auth-node';

const app = express();

// Tu app
app.get('/api/productos', (req, res) => res.json([]));

// 🔐 Montar la autenticación
app.use('/', crearServidorAutenticacion());

app.listen(3000, () => {
  console.log('Servidor corriendo en http://localhost:3000');
});

Con esas 4 líneas tenés todos los endpoints de autenticación funcionando.

---

Endpoints

Autenticación básica

Método	Endpoint	Descripción
POST	/auth/registro	Crea un usuario nuevo
POST	/auth/login	Inicia sesión
POST	/auth/logout	Cierra sesión
POST	/auth/refrescar	Renueva el access token
GET	/auth/usuario	Devuelve el usuario actual

Verificación en dos pasos (2FA)

Método	Endpoint	Descripción
POST	/auth/verificar-2fa	Verifica el código recibido
POST	/auth/reenviar-2fa	Reenvía el código

Recuperación de contraseña

Método	Endpoint	Descripción
POST	/auth/solicitar-recuperacion	Envía un email con el link
POST	/auth/restablecer-contrasena	Restablece la contraseña

Cuenta (logueado)

Método	Endpoint	Descripción
POST	/auth/cambiar-contrasena	Cambia la contraseña actual
PATCH	/auth/perfil	Edita el nombre del usuario

Sesiones

Método	Endpoint	Descripción
GET	/auth/sesiones	Lista las sesiones activas
DELETE	/auth/sesiones/:id	Revoca una sesión específica

OAuth

Método	Endpoint	Descripción
GET	/auth/oauth/github	Inicia OAuth con GitHub
GET	/auth/oauth/google	Inicia OAuth con Google

Healthcheck

Método	Endpoint	Descripción
GET	/salud	Comprueba que el servidor esté vivo

---

Verificación en dos pasos (2FA)

Activala en el .env:

DOS_FACTORES_ACTIVADO=true
DOS_FACTORES_METODO=consola

Métodos disponibles:

Método	Comportamiento
consola	Imprime el código en la terminal (desarrollo)
email	Envía el código por SMTP
auto	Consola en desarrollo, email en producción

Cuando el 2FA está activado, el login devuelve:

{
  "requiere2fa": true,
  "idPendiente": "eyJhbGc..."
}

El cliente debe llamar a /auth/verificar-2fa con ese idPendiente y el código.

---

OAuth (GitHub y Google)

Configurar GitHub

1. Andá a github.com/settings/developers
2. Creá una OAuth App
3. Homepage URL: http://localhost:5173
4. Callback URL: http://localhost:3000/auth/oauth/github/callback
5. Copiá el Client ID y generá un Client Secret

GITHUB_CLIENT_ID=tu_client_id
GITHUB_CLIENT_SECRET=tu_client_secret
GITHUB_CALLBACK_URL=http://localhost:3000/auth/oauth/github/callback

Configurar Google

1. Andá a console.cloud.google.com/apis/credentials
2. Creá un OAuth 2.0 Client ID (tipo "Aplicación web")
3. Authorized origins: http://localhost:5173
4. Redirect URIs: http://localhost:3000/auth/oauth/google/callback

GOOGLE_CLIENT_ID=tu_client_id
GOOGLE_CLIENT_SECRET=tu_client_secret
GOOGLE_CALLBACK_URL=http://localhost:3000/auth/oauth/google/callback

---

API pública

Servidor y rutas

import {
  crearServidorAutenticacion,
  crearRutasAutenticacion,
  crearRutasOAuth,
} from 'imansi-auth-node';

Middlewares

import { requerirAutenticacion, cargarUsuarioOpcional } from 'imansi-auth-node';

app.get('/api/perfil', requerirAutenticacion(), (req, res) => {
  // req.usuario está disponible
  res.json(req.usuario);
});

Servicios individuales

import {
  crearUsuario,
  validarCredenciales,
  firmarToken,
  verificarToken,
  buscarPorId,
} from 'imansi-auth-node';

---

CLI integrado

Verificar el sistema

npx imansi-auth-node iniciar

Wizard interactivo que verifica los 8 puntos críticos.

Correr migraciones

npx imansi-auth-node migrar

Crea todas las tablas necesarias.

Reiniciar la base de datos

npx imansi-auth-node reiniciar

⚠️ Destructivo. Borra TODAS las tablas. Solo para desarrollo.

---

Para producción

ENTORNO=produccion
COOKIE_SEGURA=true
COOKIE_MISMO_SITIO=none
COOKIE_REFRESH_SEGURA=true
JWT_SECRETO=una-cadena-larga-y-única-de-48-bytes-o-más

---

Próximos pasos

• imansi-auth-react — Los hooks del frontend
• imansi-correos-node — Plantillas de correo
• Quickstart — Empezá tu primer proyecto