Skip to content

Proxy Server API Gateway

The Proxy Server acts as the centralized API gateway, security boundary, and service orchestrator of the Intelligence Cloud Platform.

1. Technology Stack

  • Runtime: Node.js (Express framework)
  • Auth Verification: jsonwebtoken, jwks-rsa
  • Agent Integration: @google/generative-ai (Gemini API) and @modelcontextprotocol/sdk (Model Context Protocol client/server)
  • WebSocket Server: ws for streaming terminal connections
  • Telemetry: prom-client (scrapes default process & custom request metrics)

2. Core Responsibilities

                                      +------------------+
                                      |   LXD Daemon     |
                                      +------------------+
                                                ^
                                                | HTTPS Client Cert
  [ Client Request ] --> [ Proxy Server ] ------+
                               |
                               +---> [ Terraform Service ] (REST/Chunked)
                               |
                               +---> [ Gemini AI / MCP ] (LLM Automation)

OIDC Token Validation & RBAC

The server validates incoming JWT tokens statelessly. In auth.js: * Fetches public signing keys dynamically from the internal Keycloak endpoint. * Verifies signature (RS256), issuer, expiration, and audience claims. * Extracts client-level roles (editor, viewer, admin) to restrict WRITE routes.

Multi-Tenancy LXD Projects Enforcer

In lxd.js: * Derives the unique tenant ID u-${user.sub} from the verified OIDC payload. * Automatically creates a dedicated LXD project if one doesn't exist (ensureProjectExists). * Restricts LXD API routing to the user's project container by appending the project query parameter, shielding separate tenant resource states.

Isolated Terminal Websocket Proxying

The server provides interactive TTY access to dynamic containers/VMs through terminal.js: 1. Captures /terminal WS requests from authenticated clients. 2. Performs handshake with the LXD Daemon at https://<LXD_HOST>:8443/1.0/instances/<instance>/exec?project=<project>&wait-for-websocket=true. 3. Tunnels data bi-directionally, managing standard xterm resize control messages.

AI Infrastructure Agent (Gemini & MCP Integration)

Through agent.js and mcp-server.js: * Sets up a local Model Context Protocol (MCP) server running via stdio transport. * Discovers tools (create_instance, report_problem). * Utilizes the Gemini model to translate natural language inputs ("I want a new Ubuntu container named server-1") into structured API actions, injecting OIDC client roles to filter unauthorized tasks.

3. Key REST API Endpoints

Route Method Description Role Required
/api/agent POST Infrastructure chatbot integration Any Authenticated
/api/instances GET Lists LXD containers/VMs in user's project Any Authenticated
/api/instances/:name DELETE Deletes a stopped container/VM Editor / Admin
/api/instances/:name/files GET/POST Downloads/Uploads files to/from container Editor / Admin
/api/networks/reserved-ips GET/PUT/POST Port forwarding & static routing control Editor / Admin
/api/terraform/validate POST Validates custom Terraform code Any Authenticated
/api/terraform/apply POST Executes terraform apply in chunked streams Editor / Admin
/metrics GET Exposes Prometheus runtime instrumentation Prometheus Scraper