Progressive Web App

1. Proposito

La PWA resuelve una brecha critica en la distribución: los invitados y anfitriones no siempre quieren o pueden instalar la app nativa. La PWA ofrece la misma funcionalidad accesible desde cualquier navegador moderno via URL.

Coexistencia con la app nativa: La PWA no reemplaza a nvito-client. Ambas apps comparten los mismos 33 endpoints moviles (/v1/mobile/*) del backend.

2. Arquitectura BFF (Backend For Frontend)

La PWA implementa un patrón BFF donde los JWT tokens nunca llegan al JavaScript del browser:

Browser → /api/proxy/* (BFF) → Authorization: Bearer <jwt> → nvito-api

Flujo de autenticación

1. Usuario ingresa credenciales en el formulario de login
2. Browser envía POST a /api/auth/login (BFF route handler)
3. BFF valida con Zod, aplica rate limiting, forward a nvito-api /v1/mobile/auth/login
4. BFF recibe JWT tokens de la respuesta
5. BFF encripta tokens con AES-256-GCM y los almacena en cookies HttpOnly
6. BFF retorna al browser solo metadata de sesion (role, eventId) — SIN tokens

Flujo proxy (cada request)

1. Browser → GET /api/proxy/events/:id (con cookie HttpOnly automática)
2. BFF valida CSRF (si es mutacion), desencripta JWT de la cookie
3. Si JWT expira en < 2 minutos → refresh proactivo transparente
4. Forward a nvito-api /v1/mobile/events/:id con Authorization: Bearer <jwt>
5. Si 401 → refresh → retry una vez → si falla → clear cookies → 401 al browser

3. Seguridad

Cookies encriptadas

• Prefijo __Host-: Previene ataques de subdomain cookie injection
• AES-256-GCM: Encriptacion de tokens con IV aleatorio de 12 bytes
• CSRF doble submit: Token en cookie no-HttpOnly + firma en cookie HttpOnly, verificacion timing-safe

Headers de seguridad (CSP)

default-src 'self';
script-src 'self' 'unsafe-inline';
style-src 'self' 'unsafe-inline';
connect-src 'self';                    ← Bloquea llamadas directas a nvito-api
frame-src 'none';
frame-ancestors 'none';

Rate limiting

• Login: 5 requests / IP / 15 minutos
• Implementación in-memory con limpieza periodica

Middleware

• Rutas bajo (app)/* requieren cookie __Host-nvito-at
• Rutas públicas: /login, /join/*, /api/auth/*, assets estáticos
• Redireccion automática a /login si no hay sesion

4. Estructura de archivos

5. Pantallas HOST (12)

6. Pantallas GUEST (8)

7. Features nativas web

8. Soporte offline

• IndexedDB: 3 stores (offline-queue, event-cache, qr-passes)
• Cola FIFO: Solo operación CHECK_IN se encola offline
• Sincronización: Al reconectar, procesa cola y actualiza React Query cache
• Banner visual: Indicador amarillo cuando no hay conexión

9. API Services y React Query

Servicios (6 módulos)

Query Key Factory

Centralizado en lib/hooks/queries/keys.ts. Patron identico a nvito-client.

Polling

• Stats del evento: cada 30 segundos (refetchInterval: 30_000)
• QR passes: staleTime: 10min, gcTime: 7 dias (cache largo para offline)

10. Testing

Coverage thresholds: 80% statements, 70% branches, 75% functions, 80% lines

11. Diferencias clave vs nvito-client

12. Variables de entorno

# Server-side only (NUNCA exponer al browser)
NVITO_API_URL=http://localhost:3000
COOKIE_ENCRYPTION_KEY=<64 hex chars>    # AES-256-GCM key
CSRF_SECRET=<64 hex chars>              # HMAC secret

# Web Push
VAPID_PUBLIC_KEY=<public key>
VAPID_PRIVATE_KEY=<private key>

# Public
NEXT_PUBLIC_APP_URL=http://localhost:3002

13. Desarrollo local

# Clonar y configurar
cd nvito-pwa
npm install
cp .env.local.example .env.local    # Editar variables

# Desarrollo
npm run dev                          # http://localhost:3002

# Testing
npm run test:run                     # Vitest
npm run build                        # Build de producción

Prerequisito: nvito-api corriendo en :3000 (o la URL configurada en NVITO_API_URL).