Add package-lock.json and localization files for English and Spanish

[drakkomaximo]

Informe de Implementación - Zikuani Boilerplate

Resumen Ejecutivo

Este proyecto implementa un boilerplate completo para integrar los servicios de autenticación de Zikuani como proveedor de terceros. La aplicación permite a los usuarios autenticarse de forma privada utilizando dos métodos principales: firma digital y verificación de pasaporte, con soporte completo para internacionalización (español e inglés).

Arquitectura del Sistema

Tecnologías Utilizadas

• Backend: Node.js con Express.js
• Frontend: HTML5 con Bootstrap 5.3.2
• Autenticación: OAuth 2.0 con Zikuani
• Contenedores: Docker
• Orquestación: Docker Compose y Kubernetes
• Internacionalización: Sistema de traducciones JSON

Estructura del Proyecto

zikuani-boilerplate/
├── src/
│   ├── client.js              # Servidor principal de la aplicación
│   ├── client_passport.js     # Cliente de prueba para pasaporte
│   └── locales/
│       ├── en.json           # Traducciones en inglés
│       └── es.json           # Traducciones en español
├── compose/
│   └── compose.yaml          # Configuración Docker Compose
├── kubernetes/
│   ├── deployment-web.yml    # Despliegue en Kubernetes
│   ├── service-web.yml       # Servicio Kubernetes
│   └── ingress-web.yml       # Ingress con Traefik
├── Dockerfile                # Imagen Docker
├── package.json              # Dependencias y scripts
└── README.md                 # Documentación básica

Funcionalidades Implementadas

1. Sistema de Autenticación Dual

🔐 Firma Digital

• Flujo OAuth 2.0 completo con Zikuani
• Scope: zk-firma-digital
• Redirección directa al servidor de autorización
• Generación de estado aleatorio para seguridad

🛂 Verificación de Pasaporte

• Flujo avanzado con generación de QR
• Scope: zk-passport
• Verificación de nacionalidad con múltiples países soportados
• Validación de edad mínima (18 años)
• Verificación de unicidad del usuario
• Generación de event_id único

2. Interfaz de Usuario

Características Principales

• Diseño responsivo con Bootstrap 5.3.2
• Selector de idioma dinámico (Español/Inglés)
• Formulario intuitivo para selección de método de autenticación
• Selector de país con banderas y códigos ISO
• Generación de QR para autenticación móvil
• Feedback visual en tiempo real

Países Soportados

• 🇨🇷 Costa Rica (CRI)
• 🇺🇸 Estados Unidos (USA)
• 🇪🇸 España (ESP)
• 🇩🇪 Alemania (DEU)
• 🇦🇷 Argentina (ARG)
• 🇧🇷 Brasil (BRA)
• 🇨🇴 Colombia (COL)
• 🇲🇽 México (MEX)
• 🇵🇪 Perú (PER)
• 🇨🇱 Chile (CHL)

3. Sistema de Internacionalización

Implementación

• Archivos JSON separados por idioma
• Función de traducción con fallback a español
• Cambio dinámico de idioma sin recarga
• Soporte completo para todos los textos de la interfaz

Idiomas Soportados

• Español (idioma por defecto)
• Inglés (traducción completa)

4. Gestión de Tokens y Credenciales

Procesamiento de JWT

• Función parseJwt() para decodificar tokens
• Manejo de errores robusto
• Visualización estructurada del payload

Credenciales Verificables

• Pruebas ZK (Zero-Knowledge)
• Visualización JSON formateada
• Información de sesión (tiempo de expiración)

5. Configuración y Variables de Entorno

Variables Configurables

CLIENT_ID              // Identificador del cliente
CLIENT_SECRET          // Secreto del cliente
REDIRECT_URI           // URI de redirección
AUTH_SERVER_URL        // URL del servidor de autenticación
COUNTRY               // País por defecto
PORT                  // Puerto del servidor

Valores por Defecto

• Servidor: https://app.sakundi.io
• Puerto: 3000
• País: CRI (Costa Rica)
• Redirección: http://localhost:3000/callback

Despliegue y Contenedores

1. Docker

Dockerfile

• Base: Node.js 20
• Directorio de trabajo: /usr/src/app
• Puerto expuesto: 3000
• Comando: yarn start

Características

• Multi-stage build optimizado
• Caché de dependencias eficiente
• Imagen ligera y segura

2. Docker Compose

Configuración

services:
  web:
    image: zikuani-boilerplate
    restart: always
    build: ../
    ports:
      - 3000:3000

Características

• Reinicio automático en caso de fallo
• Mapeo de puertos directo
• Build automático desde el directorio padre

3. Kubernetes

Deployment

• Replicas: 1
• Imagen: registry.gitlab.com/sakundi/zikuani-boilerplate:dev
• ConfigMap: boilerplate-config
• ImagePullSecrets: regcred

Service

• Tipo: ClusterIP
• Puerto: 3000
• Selector: app: boilerplate

Ingress (Traefik)

• Dominio: demo.sakundi.io
• Protocolos: HTTP y HTTPS
• Certificado SSL: Automático con Let's Encrypt
• Resolver: myresolver

Flujos de Autenticación

1. Flujo de Firma Digital

sequenceDiagram
    participant U as Usuario
    participant A as Aplicación
    participant Z as Zikuani Server
    
    U->>A: Selecciona "Firma Digital"
    A->>Z: Redirect con scope "zk-firma-digital"
    Z->>U: Proceso de autenticación
    U->>Z: Confirma identidad
    Z->>A: Callback con código
    A->>Z: Intercambia código por token
    Z->>A: Retorna JWT + credencial
    A->>U: Muestra resultado

Loading

2. Flujo de Pasaporte

sequenceDiagram
    participant U as Usuario
    participant A as Aplicación
    participant Z as Zikuani Server
    participant M as App Móvil
    
    U->>A: Selecciona "Pasaporte" + país
    A->>Z: Solicita link de verificación
    Z->>A: Retorna link + QR
    A->>U: Muestra QR
    U->>M: Escanea QR
    M->>Z: Verifica pasaporte
    U->>A: Confirma autenticación
    A->>Z: Verifica estado
    Z->>A: Confirma verificación
    A->>Z: Intercambia por token
    Z->>A: Retorna JWT + credencial
    A->>U: Muestra resultado

Loading

Endpoints de la API

1. Página Principal

• Ruta: GET /
• Parámetros: lang (opcional)
• Función: Muestra formulario de autenticación

2. Inicio de Autenticación

• Ruta: GET /login
• Parámetros: method, user, country, lang
• Función: Inicia flujo de autenticación

3. Callback OAuth

• Ruta: GET /callback
• Parámetros: code, state, scope, lang
• Función: Procesa respuesta de autenticación

Seguridad Implementada

1. OAuth 2.0

• Estado aleatorio para prevenir CSRF
• Scopes específicos por tipo de autenticación
• Validación de códigos de autorización

2. Manejo de Errores

• Try-catch en todas las operaciones asíncronas
• Validación de parámetros requeridos
• Mensajes de error localizados

3. Variables de Entorno

• Configuración externa de credenciales
• Valores por defecto para desarrollo
• Separación de configuración y código

Pruebas y Validación

1. Cliente de Prueba

• Archivo: src/client_passport.js
• Función: Prueba directa de API de pasaporte
• Endpoint: https://passport-dev.sakundi.io

2. Casos de Prueba

• Autenticación exitosa con ambos métodos
• Manejo de errores de red y validación
• Cambio de idioma dinámico
• Generación de QR funcional

Configuración de Producción

1. Variables de Entorno Requeridas

REACT_APP_CLIENT_ID=tu_client_id
REACT_APP_CLIENT_SECRET=tu_client_secret
REACT_APP_REDIRECT_URI=https://tu-dominio.com/callback
REACT_APP_AUTH_SERVER_URL=https://app.sakundi.io
REACT_APP_COUNTRY=CRI
PORT=3000

2. Despliegue en Kubernetes

1. Crear ConfigMap con variables de entorno
2. Aplicar deployment con kubectl apply
3. Configurar Ingress para acceso externo
4. Verificar certificados SSL automáticos

Características Técnicas Destacadas

1. Modularidad

• Separación clara de responsabilidades
• Archivos de configuración independientes
• Sistema de traducciones escalable

2. Escalabilidad

• Arquitectura stateless para Kubernetes
• Configuración externa para diferentes entornos
• Soporte para múltiples replicas

3. Mantenibilidad

• Código documentado y estructurado
• Manejo de errores consistente
• Configuración centralizada

Próximos Pasos Recomendados

1. Mejoras de Seguridad

• Implementar rate limiting
• Añadir validación de CORS
• Implementar logging de auditoría

2. Funcionalidades Adicionales

• Soporte para más países
• Integración con más métodos de autenticación
• Dashboard de administración

3. Optimizaciones

• Implementar caché de traducciones
• Optimizar imágenes Docker
• Añadir health checks

Conclusión

El boilerplate de Zikuani implementa una solución completa y robusta para la integración de servicios de autenticación privada. La aplicación demuestra las mejores prácticas en:

• Arquitectura de microservicios
• Seguridad OAuth 2.0
• Internacionalización
• Contenedores y orquestación
• Experiencia de usuario

El código está listo para producción y puede ser utilizado como base para implementaciones más complejas que requieran autenticación privada con verificación de identidad.

---

2025-09-23.16-10-10.mp4