Frontend → Cloud¶

La frontera más transitada del sistema: todo lo que una persona hace en la aplicación la cruza. Y la única donde el consumidor no es un programa de planta sino un navegador.

Dos cosas la definen: el navegador nunca habla con la API, y los contratos que documentan esta frontera no se verifican.

El navegador no llama a la API, y no puede¶

Entre el navegador y la API hay un intermediario que corre en el servidor: el BFF, un conjunto de manejadores de ruta del frontend. El navegador le pide a su propio servidor, y ese servidor le pide a la API.

No es solo una convención. La dirección de la API nunca se le entrega al navegador: se configura en una variable sin el prefijo que la publicaría del lado del cliente, y el archivo de ejemplo lo deja escrito como requisito, no como detalle.

sequenceDiagram
    participant N as Navegador
    participant B as BFF (servidor del frontend)
    participant P as Proveedor de identidad
    participant C as API (Cloud)

    N->>B: pedido a /api/... con cookie de sesión
    B->>P: ¿esta sesión es auténtica?
    P-->>B: usuario verificado
    B->>B: inyecta credencial y empresa
    B->>C: mismo pedido, ya autenticado
    C->>C: valida membresía y permisos
    C-->>B: respuesta
    B-->>N: respuesta, con los errores traducidos

Esto tiene una consecuencia que conviene decir porque se malinterpreta: la política de CORS abierta de la API —ver seguridad— es menos grave de lo que parece justamente por acá. Ningún navegador tiene la dirección de la API, así que no hay sesión de usuario que un sitio de terceros pueda reutilizar.

Qué agrega el BFF a cada petición¶

Qué	Cómo
Verificación de la sesión	Pregunta al proveedor de identidad si la sesión es auténtica antes de leer la credencial que va a reenviar. No confía en la cookie por sí sola
Credencial	La inyecta del lado del servidor, y gana sobre cualquier cabecera que haya puesto el llamador: no se puede sobrescribir desde afuera
Empresa	Viaja en una cabecera propia. Si llega un alias, lo resuelve al identificador real
Traducción de errores	Convierte el error de la API en una forma estable para la interfaz

Las dos primeras son propiedades de seguridad reales, y vale nombrarlas: una sesión vencida o falsa no llega a la API, y una petición no puede inyectarse una credencial ajena pasándola por cabecera.

La empresa sobre la que se opera la elige el navegador¶

Salvo que la ruta la fije, el BFF toma la empresa de una cabecera que manda el navegador y la reenvía tal cual. El BFF no verifica que quien llama pertenezca a esa empresa.

Lo único que lo impide es que la API valida la membresía contra la base en cada petición. Esa validación es, literalmente, la frontera del aislamiento entre clientes: leyendo solo el frontend se concluye que la empresa es un dato del cliente, y leyendo solo la API, que es confiable porque viene validada. Ver seguridad.

La frontera no tiene verificación automática¶

Ningún proceso compara lo que el BFF le pide a la API con lo que la API ofrece. No hay contratos que se verifiquen, ni tests de integración del BFF contra la API real, y el CI del Cloud no comprueba nada del lado del proveedor.

Es una decisión registrada en FE-ADR-013, no una omisión: el frontend llegó a tener 13 archivos Pact escritos a mano, y se eliminaron porque un pact vale cuando lo emite el consumidor al ejercitar su propio código. Escrito a mano, un contrato solo repite lo que su autor creía, y verificarlo comprueba esa creencia, no el comportamiento del frontend. Uno de los trece describía un servicio de reportes que la API no tiene.

Lo que cubriría esta frontera es un test de integración del BFF contra la API. No existe.

Lo que más pesa que quede sin cubrir son las rutas de métricas del dashboard —catálogo, consulta y consulta en lote—: son las que llevan las mediciones de la planta al tablero, y de ellas depende todo lo demás.

Dónde está implementado¶

Dirección de la API deliberadamente fuera del cliente, con su nota: .env.example del frontend
Verificación de la sesión antes de reenviar la credencial, y precedencia de la credencial sobre las cabeceras del llamador: src/lib/backend-fetch.ts
Origen de la empresa y su reenvío sin verificación propia: src/lib/bff-handler.ts
Validación de membresía y carga de permisos por petición del lado de la API: internal/api/middleware/middleware.go del Cloud
Las 65 rutas del BFF: el árbol src/app/api/ del frontend

Relacionado¶

Integraciones — el estado de la verificación en las cinco fronteras
Casos de uso — la maqueta de reportes, del otro lado del contrato sin proveedor
Seguridad — qué sostiene el aislamiento que esta frontera atraviesa