ci-validation

API de Validación de Cédulas Uruguayas

⚠️ ACTUALIZACIÓN CRÍTICA 13/08/2025 - SOLUCIÓN MEF Y NUEVA VULNERABILIDAD ANV:

✅❌ SOLUCIÓN MEF CON PROBLEMA OPERACIONAL:

• MEF: Vulnerabilidad eliminada mediante remoción del endpoint de autocompletado
• Consecuencia: Todos los formularios MEF que dependían del autocompletado ahora están rotos
• Estado: Seguro pero no funcional - usuarios deben ingresar datos manualmente
• Impacto: Pérdida de conveniencia y eficiencia en trámites gubernamentales

🆘 NUEVA VULNERABILIDAD CRÍTICA DETECTADA:

• ANV: Aplicación móvil oficial expone nombres completos, apellidos y fecha de nacimiento por autocompletado de cédula
• La app está disponible en Apple Store y Google Play Store para todos los ciudadanos
• Cualquier persona puede descargar la aplicación y acceder a datos personales de otros ciudadanos
• Sin autenticación: La aplicación no requiere verificación de identidad para mostrar datos sensibles
• Contexto sensible: Exposición de datos en trámites de vivienda social

🚨 ESTADO ACTUAL DE VULNERABILIDADES GUBERNAMENTALES:

• MEF: ✅ VULNERABILIDAD SOLUCIONADA - Endpoint removido, pero ❌ FORMULARIOS ROTOS - Autocompletado no funciona
• AIN: Vulnerabilidad considerada solucionada ha resurgido, autocompletado activo nuevamente
• CGN: Formularios judiciales exponen información personal sin verificación de autorización
• ANV: NUEVA - Aplicación móvil oficial expone información personal completa sin autenticación
• Impacto operacional: Remoción del endpoint MEF rompió funcionalidad de autocompletado en formularios gubernamentales
• Sin verificación de identidad: Sistemas restantes no verifican si el trámite se realiza para uno mismo o para terceros
• Crisis dual: MEF ahora seguro pero no funcional, otros organismos funcionales pero vulnerables

📊 Estado crítico: Solución de seguridad MEF causó crisis operacional en formularios gubernamentales.

📅 ACTUALIZACIÓN DE SEGURIDAD 07/08/2025:

⚠️ VULNERABILIDAD MEF RESURGIÓ: La vulnerabilidad en el formulario https://www.tramitesenlinea.mef.gub.uy/Apia/portal/tramite.jsp?id=2629 volvió a resurgir. El sistema de autenticación implementado no verifica correctamente la autenticación y permite el acceso anónimo exponiendo:

• Fecha de nacimiento completa
• Nombre completo de cualquier ciudadano

⚠️ VULNERABILIDAD AIN RESURGIÓ: La vulnerabilidad en el formulario https://tramites.ain.gub.uy que se consideraba solucionada ha vuelto a aparecer, exponiendo nuevamente:

• Primer nombre del titular
• Primer apellido del titular
• Autocompletado automático sin autenticación efectiva

⚠️ VULNERABILIDAD CGN ACTIVA: El formulario de devolución de timbre judicial https://www.cgn.gub.uy ahora funciona pero con vulnerabilidades:

• Autocompletado no autorizado en contexto judicial
• Exposición de datos en procesos legales sensibles

� PROBLEMA DE SEGURIDAD CRÍTICO:

• El sistema permite autocompletar datos personales sensibles con solo ingresar una cédula
• No valida si el usuario está autenticado correctamente con el gobierno
• No verifica si el trámite se realiza para uno mismo o para terceros
• Expone información personal sin autorización adecuada

✅ MEJORAS TÉCNICAS IMPLEMENTADAS:

• ✅ Extracción de datos mejorada: Soporte para el nuevo formato de formularios AIN_FRM_GRAL_DATOS_PERSONALES
• ✅ Información adicional: Tipo de documento, país emisor, y componentes individuales de nombres y apellidos
• ✅ Manejo de errores optimizado: Mensajes más descriptivos y manejo específico por tipo de error
• ✅ Validación mejorada: Verificación de formato de cédula antes del procesamiento
• ✅ Compatibilidad dual: Funciona con formatos antiguos y nuevos de formularios gubernamentales
• ✅ Logging mejorado: Mayor detalle en los logs para debugging y monitoreo

📊 ESTADO ACTUAL DE SERVICIOS GUBERNAMENTALES:

• ✅❌ Formulario MEF SOLUCIONADO PERO ROTO: Vulnerabilidad eliminada mediante remoción del endpoint, pero formularios no funcionan
• ⚠️ Formulario AIN VULNERABILIDAD RESURGIÓ: https://tramites.ain.gub.uy autocompletado de primer nombre y primer apellido activo nuevamente
• ❌ Formularios de Lotería inoperativos: Todos los formularios que requieren cédula permanecen fuera de servicio desde 31/07/2025
• ⚠️ Formulario CGN VULNERABLE: Devolución de timbre judicial funciona con autocompletado no autorizado
• 🆘 Aplicación ANV VULNERABILIDAD CRÍTICA: App móvil oficial expone nombres, apellidos y fecha de nacimiento por autocompletado

📊 Estado crítico: Solución MEF creó crisis operacional - formularios seguros pero inutilizables. Otros servicios mantienen vulnerabilidades activas.

Ver reporte completo actualizado para detalles técnicos.

📋 Contexto de Seguridad Pública

⚠️ Información para Ciudadanos Uruguayos

Este proyecto surge del análisis de seguridad en sistemas públicos debido a:

🔍 Ausencia de programas de recompensas por reportes de seguridad en entidades públicas
🔍 Falta de canales formales para reportar vulnerabilidades en sistemas gubernamentales
🔍 Necesidad de transparencia en el estado de la ciberseguridad pública
🔍 Importancia de la educación ciudadana sobre protección de datos personales

🎯 Objetivo: Informar sobre el estado de los sistemas informáticos públicos y promover mejores prácticas de seguridad en el manejo de información ciudadana.

📋 Este proyecto contribuye a:

• Generar conciencia sobre la importancia de la ciberseguridad pública
• Documentar el estado actual de los sistemas gubernamentales
• Promover la transparencia en la gestión de sistemas públicos
• Educar sobre buenas prácticas de protección de datos

Consulte el 📄 Reporte de Vulnerabilidades para información técnica detallada.

Una API RESTful construida con TypeScript y Express siguiendo los principios SOLID para validar cédulas de identidad uruguayas y consultar información a través del formulario oficial del MEF (Ministerio de Economía y Finanzas).

🆕 Nuevas Características (Agosto 2025)

📋 Extracción de Datos Mejorada

• Tipo de documento: Identifica si es Cédula de Identidad, Pasaporte u Otro
• País emisor: Detecta el país que emitió el documento (Uruguay, Argentina, etc.)
• Componentes individuales: Extrae primer nombre, segundo nombre, primer apellido, segundo apellido por separado
• Compatibilidad dual: Funciona con formatos antiguos y nuevos de formularios

🔧 Mejoras Técnicas

• Validación previa: Verifica formato de cédula antes del procesamiento
• Manejo de errores optimizado: Mensajes específicos por tipo de error
• Logging avanzado: Mayor detalle para debugging y monitoreo
• Performance mejorado: Tiempos de procesamiento optimizados
• Configuración validada: Verificación automática de configuración del servicio

📊 Datos Adicionales Extraídos

{
  "success": true,
  "data": {
    "persona": {
      "nombre": "EDELMA",
      "apellido": "de SOUZA", 
      "cedula": "14115499",
      "tipoDocumento": "Cédula de Identidad",
      "paisEmisor": "URUGUAY",
      "primerNombre": "EDELMA",
      "primerApellido": "de SOUZA",
      "processingTime": 1250,
      "hasSession": true
    }
  }
}

📦 Paquete NPM Disponible

¡Esta funcionalidad también está disponible como paquete npm!

# Instalar el paquete
npm install ci-validation

# Uso básico
import { validateCIAndQuery } from 'ci-validation';
const result = await validateCIAndQuery('19119365');
console.log(result);
// Output (solo validación local - servicios gubernamentales con vulnerabilidades):
// {        
//   "success": true,
//   "data": {
//     "ci": "19119365",
//     "isValid": true,
//     "normalizedCi": "19119365",
//     "info": "Validación local únicamente - Servicios gubernamentales presentan vulnerabilidades desde 07/08/2025"
//   }
// }

🔗 Enlaces del paquete:

• npm: https://www.npmjs.com/package/ci-validation
• Documentación completa: NPM_README.md
• Guía de publicación: NPM_PUBLISHING.md

🚀 Características

• 📦 Paquete NPM: Disponible como librería independiente para proyectos TypeScript/JavaScript
• 🔧 CLI incluido: Herramienta de línea de comandos para validación rápida
• Validación de CI: Valida el formato y dígito verificador de cédulas uruguayas
• Consulta de datos: Obtiene información oficial a través del formulario del MEF
• Arquitectura SOLID: Implementa los 5 principios SOLID para código mantenible
• TypeScript: Tipado estático para mayor robustez
• Express.js: Framework web rápido y minimalista
• Middlewares de seguridad: CORS, Helmet, Rate Limiting
• Listo para Vercel: Configuración optimizada para deployment

📋 Principios SOLID Implementados

S - Single Responsibility Principle (SRP)

• CiValidator: Solo se encarga de validar cédulas
• CiService: Solo maneja las consultas a la API externa
• CiController: Solo maneja las peticiones HTTP

O - Open/Closed Principle (OCP)

• Interfaces extensibles para validadores y servicios
• Nuevos tipos de validación pueden agregarse sin modificar código existente

L - Liskov Substitution Principle (LSP)

• Las implementaciones de interfaces pueden intercambiarse sin afectar el funcionamiento

I - Interface Segregation Principle (ISP)

• Interfaces específicas y pequeñas
• No hay dependencias en métodos no utilizados

D - Dependency Inversion Principle (DIP)

• Dependencias por inyección de dependencias
• Código de alto nivel no depende de implementaciones concretas

🛠️ Instalación

Como Paquete NPM (Recomendado)

# Instalar la librería
npm install ci-validation

# Uso básico
import { validateCI, validateCIAndQuery } from 'ci-validation';

// Validación simple
console.log(validateCI('19119365')); // true

// Validación con consulta (servicios gubernamentales con disponibilidad limitada)
const result = await validateCIAndQuery('19119365');
console.log(result);

Instalación Global (CLI)

# Instalar globalmente para usar desde línea de comandos
npm install -g ci-validation

```bash
# Usar el CLI
ci-validate 19119365
ci-validate 19119365 --query  # Consulta a servicios gubernamentales (disponibilidad limitada)

Clonar el Repositorio (Desarrollo)

# Clonar repositorio
git clone <url-del-repo>
cd ci-validation-api

# Instalar dependencias
npm install

# Modo desarrollo
npm run dev

# Construir para producción
npm run build

# Iniciar en producción
npm start

📡 Endpoints

GET /health

Verifica el estado de la API

Respuesta:

{
  "status": "ok",
  "timestamp": "2025-07-30T12:00:00.000Z"
}

POST /api/ci/validate

Valida una cédula de identidad uruguaya

Request Body:

{
  "ci": "19119365"
}

Respuesta exitosa:

{
  "success": true,
  "data": {
    "ci": "19119365",
    "isValid": true,
    "info": "Información obtenida del formulario oficial del MEF..."
  }
}

Respuesta con error:

{
  "success": false,
  "error": "Cédula inválida: formato incorrecto"
}

POST /api/ci/smi

Consulta información específica de SMI (Sociedad de Medicina del Interior) por cédula

Request Body:

{
  "ci": "19119365"
}

También disponible como GET:

GET /api/ci/smi?ci=19119365

Respuesta exitosa (usuario registrado):

{
  "success": true,
  "data": {
    "success": true,
    "hasUser": true,
    "member": {
      "ci": "19119365",
      "status": "registered",
      "executionTime": 1250,
      "userData": {
        "perID": "12345",
        "perCI": "19119365",
        "perMail": "[e-mail]",
        "domicTel": "099123456",
        "isValidUser": true
      }
    }
  },
  "timestamp": "2025-08-13T12:00:00.000Z",
  "executionTime": {
    "total": 1300,
    "validation": 5,
    "query": 1250
  }
}

Respuesta exitosa (usuario no registrado):

{
  "success": true,
  "data": {
    "success": true,
    "hasUser": false,
    "error": "Usuario no registrado en SMI"
  },
  "timestamp": "2025-08-13T12:00:00.000Z",
  "executionTime": {
    "total": 800,
    "validation": 5,
    "query": 750
  }
}

Respuesta con error:

{
  "success": false,
  "error": "Cédula inválida: formato incorrecto",
  "code": "INVALID_FORMAT"
}

GET /api/ci/demo

Endpoint de demostración con una cédula de ejemplo

GET /demo

Página web interactiva para probar la API

La página de demostración incluye:

• Interfaz amigable: Formulario simple para ingresar cédulas
• Validación en tiempo real: Feedback inmediato sobre errores de formato
• Respuesta dual: Muestra tanto la respuesta JSON como un resultado amigable
• Persistencia en URL: La cédula se mantiene en la URL al recargar
• Ejemplos: Botones para probar cédulas de ejemplo
• Responsive: Funciona en dispositivos móviles y desktop
• Indicadores visuales: Animaciones y colores para success/error

Características técnicas:

• Uso de Tailwind CSS para estilos
• JavaScript vanilla para máximo rendimiento
• Font Awesome para iconos
• Manejo de errores robusto
• Validación del lado cliente antes de enviar

🧪 Testing

# Ejecutar tests
npm test

# Ejecutar linting
npm run lint

# Corregir problemas de linting
npm run lint:fix

🚀 Deployment en Vercel

• Conecta tu repositorio con Vercel
• Vercel detectará automáticamente la configuración
• Las variables de entorno se configuran en el dashboard de Vercel

Configuración para Vercel

El proyecto está optimizado para deployment serverless en Vercel:

• Funciones serverless: Los endpoints están en la carpeta /api/
• Archivos estáticos: La página demo está en /public/
• Configuración automática: vercel.json maneja el routing
• Build automático: TypeScript se compila automáticamente

Estructura de Deployment

api/
├── index.ts          # Endpoint raíz (GET /)
├── health.ts         # Health check (GET /health)
├── validate.ts       # Validación (POST /api/ci/validate)
├── smi.ts           # Consulta SMI (POST /api/ci/smi)
└── demo.ts          # Demo API (GET /api/ci/demo)
public/
└── index.html       # Página demo (GET /demo)

URLs en Producción

• API Root: https://ci-validation.vercel.app/
• Health Check: https://ci-validation.vercel.app/health
• Validación: https://ci-validation.vercel.app/api/ci/validate
• Demo Page: https://ci-validation.vercel.app/demo

Variables de Entorno

• NODE_ENV: production
• PORT: Puerto del servidor (automático en Vercel)

Configuración de Proxy SMI (Opcional)

Para usar un proxy externo para las consultas SMI (útil cuando no se puede acceder directamente a SMI):

• SMI_PROXY: URL completa del servidor proxy que tiene acceso a SMI (ej: https://xxxxxx.com)

Ejemplo de configuración en .env:

# Usar proxy externo para SMI
SMI_PROXY=https://xxxx.com

Nota: Cuando se configura SMI_PROXY, el servicio hará peticiones a {SMI_PROXY}/api/smi?ci=xxx en lugar de conectar directamente a SMI.

Configuración de Proxy (Opcional)

Para enrutar las peticiones HTTP a través de un servidor proxy, puedes usar cualquiera de estos métodos:

Método 1: URL completa (recomendado)

• PROXY: URL completa del proxy (ej: http://179.27.158.18:80)

Método 2: Variables individuales (para compatibilidad)

• PROXY_HOST: Dirección del servidor proxy (ej: proxy.empresa.com)
• PROXY_PORT: Puerto del proxy (ej: 8080)
• PROXY_PROTOCOL: Protocolo del proxy (http o https, por defecto http)
• PROXY_USERNAME: Usuario para autenticación del proxy (opcional)
• PROXY_PASSWORD: Contraseña para autenticación del proxy (opcional)

Ejemplos de configuración en .env:

# Método simple (recomendado)
PROXY=http://179.27.158.18:80

# Con autenticación
PROXY=http://usuario:contraseñ[e-mail]:8080

# Método alternativo (variables individuales)
PROXY_HOST=proxy.empresa.com
PROXY_PORT=8080
PROXY_PROTOCOL=http
PROXY_USERNAME=mi_usuario
PROXY_PASSWORD=mi_contraseña

Nota: El soporte de proxy está disponible para todas las consultas a servicios externos (SMI, lotería, etc.)

📁 Estructura del Proyecto

src/
├── controllers/          # Controladores HTTP
│   └── CiController.ts
├── services/            # Servicios de negocio
│   └── CiService.ts
├── validators/          # Validadores
│   └── CiValidator.ts
├── interfaces/          # Definiciones de tipos
│   ├── ICiValidator.ts
│   ├── ICiService.ts
│   └── ApiResponse.ts
├── middleware/          # Middlewares personalizados
│   └── errorHandler.ts
├── routes/             # Definición de rutas
│   └── ciRoutes.ts
├── utils/              # Utilidades
│   └── dependencyContainer.ts
└── index.ts            # Punto de entrada

🔒 Seguridad

• CORS: Configurado para permitir requests desde dominios específicos
• Helmet: Headers de seguridad automáticos
• Rate Limiting: Límite de requests por IP
• Validación de entrada: Validación estricta de datos de entrada

📝 Algoritmo de Validación de CI

La validación sigue el algoritmo oficial uruguayo:

• Verificar que tenga 7-8 dígitos
• Calcular dígito verificador usando el algoritmo oficial
• Comparar con el último dígito de la cédula

🤝 Contribución

• Fork el proyecto
• Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
• Commit tus cambios (git commit -m 'Add some AmazingFeature')
• Push a la rama (git push origin feature/AmazingFeature)
• Abre un Pull Request

📦 Publicar el Paquete NPM

Si tienes permisos de publicación:

# Verificar build
npm run build

# Dry run
npm run publish:dry

# Publicar
npm run publish:npm

# O incrementar versión y publicar
npm version patch  # o minor/major
npm run publish:npm

Ver guía completa de publicación para más detalles.

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

🔗 Enlaces Útiles

📖 Documentación Técnica

• Documentación de Express
• TypeScript Handbook
• Principios SOLID
• Vercel Documentation

📦 Paquete NPM

• 📚 Documentación del Paquete NPM - Guía completa de uso de la librería
• 🚀 Guía de Publicación NPM - Instrucciones para publicar actualizaciones
• npm Package - Página oficial del paquete

⚠️ Seguridad

• ⚠️ Reporte de Vulnerabilidad de Seguridad - Información sobre la vulnerabilidad encontrada en servicios gubernamentales
• 🔍 Informe Técnico de Vulnerabilidad IDOR - Análisis técnico detallado de la vulnerabilidad
• 🛡️ Política de Seguridad y VDP - Programa de Divulgación Responsable de Vulnerabilidades