Flujo de Autenticación Web

Resumen

El login web sigue siendo dual: Zauru autentica al usuario y BoostAPI valida la pertenencia real, roles, permisos y entidad activa del CRM.

Desde esta fase, la sesión Zauru es backend-owned. Web ya no resuelve graphql.json, ya no construye graphql_jwt/graphql_url, y solo consume:

• POST /api/auth/login con zauru_session en la respuesta;
• GET /api/auth/zauru-session como snapshot oficial;
• POST /api/auth/zauru-session/sync como force reconcile server-side;
• DELETE /api/auth/zauru-session para limpieza explícita.

La sesión Zauru sigue siendo separada de la sesión general del CRM:

• no guarda el JWT crudo de GraphQL en la [REDACTED] web;
• no invalida por sí sola toda la sesión del CRM;
• sí gobierna módulos como Facturas, Pagos, catálogos y futuros slices Zauru-backed.

Pasos

1. Usuario entra a /login.
2. Web redirige al proveedor OAuth.
3. Zauru devuelve code.
4. Web consulta GET {AUTH_ZAURU}/api/userinfo con ese code.
5. Web extrae desde Zauru:
   • email
   • api_key
   • selected_entity
6. Web valida contra BoostAPI con POST {BOOST_API_BASE_URL}/api/auth/login.
7. Si ambos pasos son exitosos, crea sesión dual con:
   • grantIds
   • schemaVersion
   • capabilities
   • accessContext
   • permissions solo como fallback transicional
   • boostUserId
   • roleName
   • boostRoleId
   • employeeRoleId
   • userRoleId
   • roleSource
   • boostEmployeeId
   • zauruEmployeeId
   • boostEntityId
   • clientKind = "web"
   • zauruSession si BoostAPI ya pudo reconciliarla en login
8. Web obtiene o reutiliza GET /api/permissions/schema.
9. Web trata GET /api/permissions/me como fuente principal para grants y refresco.
10. Web navega a /auth/zauru-session/finish.
11. Si session.zauruSession.status llega ready|expiring_soon, la pantalla intermedia redirige de inmediato al destino final.
12. Si llega missing|expired|entity_mismatch, la pantalla intermedia llama:

• POST /api/auth/zauru-session/sync

13. Web lee el snapshot oficial:

• GET /api/auth/zauru-session

14. Solo si el snapshot queda ready o expiring_soon, entra a la app.

Regla de responsabilidades

Monorepo web

• hace login;
• usa GET /api/permissions/schema para labels y agrupaciones;
• usa GET /api/permissions/me para grants efectivos y capacidades;
• persiste zauru_session devuelto por BoostAPI;
• usa GET /api/auth/zauru-session como snapshot operativo;
• dispara POST /api/auth/zauru-session/sync cuando necesita forzar reconcile;
• decide cuándo reintentar o bloquear UX, sin ejecutar GraphQL ni graphql.json.

BoostAPI

• valida pertenencia, identidad y entidad;
• resuelve server-side /profile.json y /apps/graphql.json;
• persiste la sesión Zauru por user + entity + client_kind;
• decide el acceso real a módulos Zauru-backed;
• usa la sesión guardada como fuente de verdad runtime.

Contrato operativo de sesión Zauru

Endpoints consumidos por web:

• POST /api/auth/zauru-session/sync
• GET /api/auth/zauru-session
• DELETE /api/auth/zauru-session

Snapshot operativo esperado:

• status
• entity_id
• client_kind
• selected_entity_id
• selected_entity_name
• selected_entity_logo
• zauru_user_id
• zauru_employee_id
• graphql_jwt_expires_at
• refresh_after
• checked_at
• synced_at

Reglas:

• el JWT GraphQL de Zauru vive solo server-side en BoostAPI;
• web solo guarda metadata normalizada de estado;
• web ya no resuelve graphql.json ni envía graphql_jwt/graphql_url;
• 401/428/409 en módulos Zauru-backed activan reconciliación controlada;
• SSR debe degradar con estado controlado, no destruir la sesión global del CRM.

Variables mínimas de web

Happy path oficial:

• APP_RUNTIME_MODE (dev|preview|prod)
• AUTH_ZAURU
• CLIENT_ID
• REDIRECT_URL
• BOOST_API_BASE_URL
• SESSION_SECRET

Valores operativos:

• dev: AUTH_ZAURU=https://zauru-oauth-staging.herokuapp.com
• preview: AUTH_ZAURU=https://zauru-oauth-staging.herokuapp.com (o base OAuth Heroku de pruebas) + APP_RUNTIME_MODE=preview
• prod: AUTH_ZAURU debe apuntar a la base OAuth productiva aprobada

Nota de runtime:

• preview debe comportarse como prod-like en web ([REDACTED]s seguras, sin fallback de permisos dev), aunque use endpoints de prueba.

Nota:

• aunque en staging el login visible pueda verse como https://zauru-oauth-staging.herokuapp.com/login, en .env guardamos la base del proveedor porque web construye /dialog/authorize, /api/userinfo y /logout a partir de AUTH_ZAURU.

Puntos críticos

• redirect_uri debe coincidir exactamente con la configuración del proveedor.
• SESSION_SECRET debe tener longitud/entropía adecuada.
• BOOST_API_BASE_URL debe apuntar al backend BoostAPI operativo.
• La sesión Zauru es una capacidad por módulo, no el criterio de validez total del CRM.
• El flujo web real ya no entra directo a /dashboard; debe pasar por auth/zauru-session/finish.
• Web ya no resuelve ni ejecuta GraphQL de Zauru; solo consume snapshots/reconcile de BoostAPI.
• Si falla solo la sesión Zauru, la UI debe permitir retry o realineación sin destruir automáticamente la sesión Boost.
• [REDACTED] no debe guardar schema ni árboles de permisos.