PANEL_BASES_ANEXO24/INSTALACION_USUARIOS.md

🚀 Sistema Completo de Gestión de Usuarios y Permisos

✅ ¿Qué se ha implementado?

1. Sistema de Autenticación

• ✅ Login con usuario y contraseña
• ✅ Tokens JWT seguros
• ✅ Cookies HTTP-only
• ✅ Sesiones persistentes (7 días)
• ✅ Logout seguro
• ✅ Protección de rutas

2. Gestión de Usuarios (Solo Admins)

• ✅ Crear nuevos usuarios
• ✅ Editar usuarios existentes
• ✅ Activar/desactivar usuarios
• ✅ Eliminar usuarios
• ✅ Asignar rol de administrador

3. Sistema de Permisos

• ✅ Permisos granulares por base de datos
• ✅ Asignación/revocación de permisos
• ✅ Filtrado automático de bases de datos según permisos
• ✅ Administradores con acceso total

4. Base de Datos PostgreSQL

• ✅ Tabla de usuarios
• ✅ Tabla de permisos
• ✅ Tabla de sesiones
• ✅ Índices para rendimiento
• ✅ Constraints de integridad

5. Seguridad

• ✅ Contraseñas hasheadas con bcrypt
• ✅ Validación de contraseñas fuertes
• ✅ Tokens JWT con expiración
• ✅ Protección contra SQL injection
• ✅ Sanitización de entradas

📦 Archivos Creados

Backend (Server)

src/lib/server/
├── auth.ts              # Utilidades de autenticación JWT y bcrypt
├── users.ts             # CRUD de usuarios y permisos
└── db.ts                # Conexión a PostgreSQL (actualizado)

src/routes/
├── login/
│   ├── +page.svelte         # Interfaz de login
│   └── +page.server.ts      # Lógica de autenticación
├── logout/
│   └── +server.ts           # Cerrar sesión
├── usuarios/
│   ├── +page.svelte         # Gestión de usuarios (UI)
│   ├── +page.server.ts      # CRUD y permisos
│   └── api/permissions/
│       └── +server.ts       # API de permisos
└── +page.server.ts          # Panel principal (actualizado con filtros)

Base de Datos

database/
└── schema.sql           # Script de creación de tablas

Documentación

docs/
└── USUARIOS.md          # Guía completa del sistema

scripts/
├── generate-password-hash.js    # Generar hash de contraseñas
└── init-users.sh                # Script de inicialización

Configuración

.env.example             # Variables de entorno de ejemplo

🛠️ Instalación y Configuración

Paso 1: Instalar Dependencias

npm install

Las dependencias ya están en package.json:

• bcrypt - Hash de contraseñas
• jsonwebtoken - Tokens JWT
• pg - Cliente PostgreSQL
• @types/pg, @types/bcrypt, @types/jsonwebtoken - Tipos TypeScript

Paso 2: Configurar PostgreSQL

Opción A: Desde la línea de comandos

psql -h 10.0.20.152 -U postgres -d CONTROLDESK -f database/schema.sql

Opción B: Desde pgAdmin o DBeaver

1. Abre el archivo database/schema.sql
2. Copia todo el contenido
3. Pégalo en la consola SQL
4. Ejecuta el script

Paso 3: Generar Contraseña del Admin

node scripts/generate-password-hash.js

Este script generará un hash para la contraseña Admin123!.

IMPORTANTE: Copia el hash generado y actualiza el archivo database/schema.sql en la línea del INSERT del usuario admin, reemplazando el hash temporal.

Luego vuelve a ejecutar el INSERT en PostgreSQL:

INSERT INTO usuarios (username, email, password_hash, nombre_completo, es_admin, activo)
VALUES (
    'admin',
    'admin@aduanasoft.com',
    'EL_HASH_QUE_GENERASTE',  -- <-- Pega aquí el hash
    'Administrador del Sistema',
    true,
    true
)
ON CONFLICT (username) DO UPDATE SET
    password_hash = EXCLUDED.password_hash;

Paso 4: Configurar Variables de Entorno

cp .env.example .env

Edita .env y actualiza los valores:

# PostgreSQL
DB_POSTGRES_HOST=10.0.20.152
DB_POSTGRES_PORT=5432
DB_POSTGRES_USER=postgres
DB_POSTGRES_PASS=Control.
DB_POSTGRES_DB=CONTROLDESK

# JWT Secret (¡CÁMBIALO!)
JWT_SECRET=un-secreto-muy-largo-y-aleatorio-para-produccion

⚠️ IMPORTANTE: En producción, genera un JWT_SECRET aleatorio y seguro:

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

Paso 5: Iniciar el Servidor

npm run dev

Paso 6: Primer Login

1. Ve a http://localhost:5173/login
2. Usuario: admin
3. Contraseña: Admin123! (o la que configuraste)

📖 Uso del Sistema

Para Administradores

1. Crear un Nuevo Usuario

1. Ve a "Gestión de Usuarios" en el sidebar
2. Haz clic en "Nuevo Usuario"
3. Completa el formulario:
   • Usuario: Nombre de usuario único
   • Email: Correo electrónico
   • Nombre Completo: Nombre real
   • Contraseña: Mínimo 8 caracteres con mayúsculas, minúsculas, números y símbolos
   • Es Administrador: Marca si quieres que sea admin
4. Haz clic en "Crear Usuario"

2. Asignar Permisos de Bases de Datos

1. En la lista de usuarios, haz clic en el ícono 🔒 (candado)
2. Verás todas las bases de datos disponibles
3. Haz clic en "Sin Acceso" para otorgar acceso
4. Haz clic en "Con Acceso" para revocar acceso
5. Los cambios se guardan automáticamente

3. Editar un Usuario

1. Haz clic en el ícono ✏️ (editar)
2. Modifica los campos que necesites
3. Para cambiar la contraseña, escribe una nueva (si dejas vacío, no se cambia)
4. Haz clic en "Guardar Cambios"

4. Desactivar un Usuario

1. Haz clic en el ícono de toggle (activar/desactivar)
2. Confirma la acción
3. El usuario no podrá iniciar sesión, pero sus datos se conservan

5. Eliminar un Usuario

1. Haz clic en el ícono 🗑️ (eliminar)
2. Confirma la acción
3. ¡CUIDADO! Esta acción es permanente

Para Usuarios Normales

Los usuarios normales solo verán:

• Las bases de datos que les han sido asignadas
• No tendrán acceso a "Gestión de Usuarios"
• El resto del panel funciona igual

🔒 Cómo Funciona la Seguridad

Flujo de Autenticación

1. Usuario ingresa credenciales
   ↓
2. Servidor verifica con bcrypt
   ↓
3. Se genera token JWT
   ↓
4. Token se guarda en cookie HTTP-only
   ↓
5. Cada petición verifica el token
   ↓
6. Se aplican filtros de permisos

Filtrado de Bases de Datos

// En +page.server.ts (líneas 376-379)
if (!currentUser.es_admin) {
    // Filtra solo las bases de datos que el usuario puede ver
    databaseRows = await filterDatabasesByUserPermissions(currentUser.id, databaseRows);
    alertsData = await filterDatabasesByUserPermissions(currentUser.id, alertsData);
}

📊 Estructura de la Base de Datos

Tabla usuarios

Almacena información de los usuarios del sistema.

Campo	Tipo	Descripción
id	SERIAL	ID único
username	VARCHAR(50)	Nombre de usuario único
email	VARCHAR(100)	Email único
password_hash	VARCHAR(255)	Contraseña hasheada
nombre_completo	VARCHAR(100)	Nombre completo
activo	BOOLEAN	Si el usuario está activo
es_admin	BOOLEAN	Si es administrador
fecha_creacion	TIMESTAMP	Fecha de creación
ultimo_acceso	TIMESTAMP	Último login

Tabla usuario_base_datos

Relaciona usuarios con bases de datos y sus permisos.

Campo	Tipo	Descripción
id	SERIAL	ID único
usuario_id	INTEGER	FK a usuarios
base_datos_nombre	VARCHAR(255)	Nombre de la BD
puede_ver	BOOLEAN	Permiso de visualización
puede_descargar_backup	BOOLEAN	Permiso de descarga (futuro)
puede_restaurar	BOOLEAN	Permiso de restauración (futuro)
fecha_asignacion	TIMESTAMP	Fecha de asignación

🐛 Solución de Problemas

"No puedo iniciar sesión"

1. Verifica que el hash de contraseña sea correcto en la BD
2. Revisa los logs del servidor (terminal donde corre npm run dev)
3. Asegúrate de que PostgreSQL esté corriendo
4. Verifica las credenciales en .env

"No veo ninguna base de datos"

1. Si eres admin, deberías ver todas
2. Si eres usuario normal, verifica que tengas permisos asignados:

   SELECT * FROM usuario_base_datos WHERE usuario_id = TU_ID;
   

"Error de conexión a PostgreSQL"

1. Verifica que PostgreSQL esté corriendo:

   psql -h 10.0.20.152 -U postgres -c "SELECT version();"
   

2. Revisa el firewall del servidor
3. Verifica las credenciales en .env

"Invalid token" o "Session expired"

1. Cierra sesión y vuelve a iniciar
2. Limpia las cookies del navegador
3. Verifica que JWT_SECRET sea el mismo en .env

🎯 Próximos Pasos Recomendados

1. Cambiar el JWT_SECRET en .env a un valor aleatorio y seguro
2. Actualizar la contraseña del admin después del primer login
3. Crear usuarios para tu equipo
4. Asignar permisos según las responsabilidades de cada usuario
5. Probar el sistema con diferentes usuarios
6. Configurar backups de la base de datos PostgreSQL
7. Documentar los usuarios y sus permisos para tu organización

📞 Soporte

Para preguntas o problemas, contacta al equipo de desarrollo.

---

Desarrollado para Aduanasoft - Panel de Gestión de Bases de Datos SCAII