Skip to main content

medOS Gateway

Internal scope: ever-api-gateway  ·  Port: 3001  ·  Tier: core

The single ingress for all REST traffic into the medOS backend. The gateway terminates HTTP, verifies the caller's bearer token, and translates each request into a NATS / Moleculer service-mesh call — routing to the right microservice, aggregating multi-service responses, and applying global concerns (auth, CORS, body limits, request enrichment). No other service is exposed to the public network directly; everything reaches the mesh through here.

3001
Default HTTP port
/api/v2
Primary route prefix
NATS
Mesh transport
JWT
Bearer auth scheme

What it owns​

The gateway is a thin but security-critical edge. It owns the HTTP surface, the route whitelist (which mesh actions are reachable from outside), the authentication handshake, and the OpenAPI documentation endpoints. Business logic lives downstream — the gateway's job is to admit, authenticate, and dispatch.

Responsibilities​

  • HTTP → NATS translation — incoming REST calls become Moleculer action calls over the broker.
  • Route whitelisting — an explicit per-route allow-list controls exactly which service.entity.* actions are reachable; anything not listed stays internal.
  • Authentication — dual-mode bearer verification (see below), with the resolved user, roles, and token propagated into request context (ctx.meta).
  • Authorization hook — a route-level authorize step gates protected prefixes before the request fans out.
  • CORS, body parsing & limits — permissive CORS for the SPA plus per-route JSON / urlencoded body-size caps (20 MB on data routes, 1 MB on AI routes).
  • OpenAPI surface — auto-generated API docs and a Swagger-style UI.
  • Request enrichment & telemetry — client-IP resolution, geo lookup, and behavioral signal emission feeding downstream detection.

Authentication: dual-mode​

The gateway accepts two token families on the standard Authorization: Bearer ... header and selects a path per request:

ModeBehavior
Keycloak (OIDC)Tokens recognized as Keycloak are validated against the IdP's JWKS, then mapped to medOS users and roles.
Legacy JWTNon-Keycloak tokens are verified via the auth service action aaa.auth.verifyToken.

An AUTH_MODE flag selects policy: keycloak accepts only OIDC tokens, legacy accepts only the classic JWT path, and the default dual mode admits either. The resolved identity is attached to ctx.meta (user, roles, token, and an authSource marker) so downstream services never re-parse the token. Failures fail closed with an Unauthorized response rather than crashing the gateway.

Route map​

client (HTTPS, SPA / external)
        │  Authorization: Bearer <jwt|oidc>
        ▼
┌─────────────────────────────────────────────┐
│  medOS Gateway  (:3001, Moleculer-Web)       │
│                                              │
│  /api          internal node + api.* actions │
│  /api/openapi  spec + assets + UI            │
│  /api/v2       authorized, whitelisted mesh  │
│  /api/v2/ai    auth'd AI proxy (voice order) │
└───────────────┬──────────────────────────────┘
                │  ctx.call over NATS
                ▼
   ┌──────────┬──────────┬───────────┬─────────┐
   │  aaa     │ clinical │ financial │ medication ... │
   │ (auth)   │          │           │         │
   └──────────┴──────────┴───────────┴─────────┘

The bulk of the public API lives under /api/v2, whose whitelist enumerates the reachable actions per service (for example aaa.auth.*, administration.patient.*, administration.encounter.*, medication.consultRequest.*). Adding a new externally callable action means adding it to this list — a deliberate allow-list, not auto-exposure.

Major modules​

edge

API Gateway service

The core Moleculer-Web mixin: route table, CORS, body parsers, the whitelist, and the authenticate / authorize hooks. The heart of the service.

auth

Keycloak validator

OIDC token validation against the IdP JWKS, plus mapping of Keycloak claims to medOS users and roles.

docs

OpenAPI service

Auto-generated OpenAPI spec, served assets, and a browsable docs UI under /api/openapi.

ai

Voice-order proxy

A guarded /api/v2/ai route that forwards authenticated voice-order requests into the assistant pipeline.

signals

RUDS enrichment

Client-IP, geo resolution, event enrichment and scoring that emit behavioral signals for rogue-user / threat detection.

ops

Moleculer Labs

Optional broker introspection / dashboard mixin for observing mesh traffic in non-prod environments.

ModuleSourcePurpose
API Gateway serviceApiGatewayService.tsRoute table, CORS, body limits, whitelist, authenticate / authorize hooks
Keycloak validatorkeycloak/OIDC token validation (JWKS) and claim → medOS user/role mapping
OpenAPI serviceOpenApiService.tsAuto-generated spec + assets + docs UI
Voice-order proxyai/voiceOrderProxy.tsAuthenticated AI voice-order route forwarding
RUDS enrichmentruds/Client-IP, geo lookup, event enrichment, scoring & signal emission
Moleculer LabsMoleculerLabsService.tsBroker dashboard / introspection mixin

Config flags​

FlagEffect
API_GATEWAY_PORTHTTP listen port (defaults to 3001).
AUTH_MODEkeycloak | legacy | unset (dual). Controls which token families are accepted.

CORS is intentionally open at the gateway because TLS termination and origin policy are handled by the reverse proxy / load balancer in front of it.

Integration notes​

  • Identity — delegates legacy verification to the auth service (aaa.auth.*) and OIDC to the external IdP. See Auth service.
  • Mesh — every downstream call travels over NATS via ctx.call; the gateway holds no domain data of its own.
  • Telemetry — enrichment signals emitted here feed platform-wide behavioral threat detection. See Architecture.
Public ingressJWT + OIDC authAction whitelistingOpenAPI docs
  • SYS-2 — API Gateway
  • ST-7 — Third-Party Access (OAuth)