ips-nodo-dominio/bus-gateway/README.md

bus-gateway

Gateway de interoperabilidad FHIR que expone los perfiles IHE MHD y PDQm/PMIR como fachada hacia un Bus de Interoperabilidad (Federador MSAL) y un servidor HAPI FHIR local.

Descripción

El componente actúa exclusivamente como gateway: no contiene lógica de negocio propia. Su responsabilidad es:

• Obtener el token de autenticación del Bus.
• Redirigir las llamadas entrantes al servicio de backend correspondiente (MPI, Document Registry o HAPI FHIR).
• Devolver los resultados al cliente tal como los retornan los servicios subyacentes.

Transacciones IHE implementadas

Transacción	Método	Ruta	Descripción
ITI-65	POST	/fhir/Bundle	Provide Document Bundle: almacena el Bundle en HAPI FHIR, resuelve el ID nacional del paciente vía $match en el Bus y registra el DocumentReference en el Document Registry.
ITI-67	GET	/fhir/DocumentReference	Find Document References: busca el paciente por ID local en el MPI para obtener su ID nacional y consulta los DocumentReferences en el Document Registry.
ITI-78	GET	/fhir/Patient	Patient Demographics Query: búsqueda de pacientes en el MPI.
ITI-78	GET	/fhir/Patient/:id	Patient Demographics Query: obtención de un paciente por ID en el MPI.
ITI-104	POST	/fhir/Patient	Patient Identity Feed: alta de paciente en el MPI.
ITI-104	PUT	/fhir/Patient/:id	Patient Identity Feed: actualización de paciente en el MPI.
—	GET	/fhir/Bundle/:id/$ddcc	Obtiene el Bundle IPS del HAPI FHIR local y delega la transformación DDCC al nodo nacional (bundle-signer).
—	GET	/fhir/Bundle/:id/$dvc	Obtiene el Bundle IPS del HAPI FHIR local y delega la transformación DVC al nodo nacional (bundle-signer).
—	GET	/fhir/Bundle/:id/$icvp2	Obtiene el Bundle IPS del HAPI FHIR local y delega la transformación ICVP (HCERT) al nodo nacional (bundle-signer).
—	GET	/fhir/Bundle/:id/$meow	Obtiene el Bundle del HAPI FHIR local y delega la transformación MeOW (HCERT) al nodo nacional (bundle-signer).

Variables de entorno

Copiá .env.example a .env y completá los valores:

cp .env.example .env

Variable	Requerida	Descripción
BUS_URL	Sí	URL base del Bus. Se usa para autenticación y como fallback si no se definen MPI_URL ni DOCUMENT_REGISTRY_URL.
BUS_JWT_SECRET	Sí	Secreto compartido para firmar el JWT de autenticación contra el Bus.
BUS_ISSUER	Sí	Issuer del JWT (URL del repositorio).
MPI_SCOPE	Sí	Scopes OAuth para el MPI (ej: Patient/*.read,Patient/*.write).
DOCUMENT_REGISTRY_SCOPE	Sí	Scopes OAuth para el Document Registry (ej: DocumentReference/*.read,DocumentReference/*.write).
MPI_URL	No	URL base del servicio MPI (Master Patient Index). Si no se define, usa BUS_URL.
DOCUMENT_REGISTRY_URL	No	URL base del Document Registry. Si no se define, usa BUS_URL.
FHIR_URL	Sí	URL base del servidor HAPI FHIR local.
BUNDLE_SIGNER_URL	Sí	URL base del nodo nacional (bundle-signer) donde se ejecutan las transformaciones IPS ($ddcc, $dvc, $icvp2, $meow).
PORT	No	Puerto en que escucha el servidor. Por defecto 3000.

Usar la misma URL para todos los servicios del Bus

Si el MPI y el Document Registry están expuestos bajo la misma URL que el Bus, alcanza con omitir MPI_URL y DOCUMENT_REGISTRY_URL:

BUS_URL=http://bus-host:8080
BUS_JWT_SECRET=your-shared-secret
BUS_ISSUER=https://your-repositorio-url
MPI_SCOPE=Patient/*.read,Patient/*.write
DOCUMENT_REGISTRY_SCOPE=DocumentReference/*.read,DocumentReference/*.write

FHIR_URL=http://hapi-fhir-host:8080/fhir

MPI_URL y DOCUMENT_REGISTRY_URL toman el valor de BUS_URL automáticamente.

Usar URLs diferentes por servicio

Si cada servicio está en un host o contexto distinto:

BUS_URL=http://bus-host:8080
BUS_JWT_SECRET=your-shared-secret
BUS_ISSUER=https://your-repositorio-url
MPI_SCOPE=Patient/*.read,Patient/*.write
DOCUMENT_REGISTRY_SCOPE=DocumentReference/*.read,DocumentReference/*.write

MPI_URL=http://mpi-host:8080
DOCUMENT_REGISTRY_URL=http://document-registry-host:8080

FHIR_URL=http://hapi-fhir-host:8080/fhir

Ejecución local (sin Docker)

Requisitos

• Node.js 20+
• Acceso al Bus de Interoperabilidad y al servidor HAPI FHIR

Instalación

npm install

Inicio

cp .env.example .env   # completar las variables
npm start

El servidor queda disponible en http://localhost:3000.

Para usar un puerto diferente:

PORT=8080 npm start

Tests

npm test

Para correr un archivo específico:

npm test tests/utils/busAuth.test.js
npm test tests/services/patient.test.js
npm test tests/services/documentReference.test.js

Ejecución con Docker

cp .env.example .env   # configurar variables
docker compose up -d

Para ver los logs:

docker compose logs -f

Headers requeridos por transacción

ITI-65 POST /fhir/Bundle

Header	Descripción
x-custodian-id	Identificador del efector en el sistema Federador MSAL.
Content-Type	application/fhir+json

Estructura del proyecto

bin/          Entrypoint del servidor Express
config/       Carga y validación de variables de entorno
controllers/  Lógica de cada transacción IHE
routes/       Definición de rutas HTTP por transacción
services/     Clientes de los servicios externos (MPI, Document Registry)
utils/        Autenticación contra el Bus (JWT + token)