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

The complete, detailed API definition is available in the OpenAPI 3.0 Specification (YAML) file or can be explored in the Interactive API Reference.

Route Method Description Role Required
/api/agent POST Infrastructure chatbot integration Any Authenticated
/api/issues GET List open GitHub issues Any Authenticated
/api/issues POST Create a new GitHub issue Any Authenticated
/api/terraform/validate POST Validates custom Terraform code Any Authenticated
/api/terraform/plan POST Generates a Terraform execution dry-run Editor / Admin
/api/terraform/apply POST Executes terraform apply in chunked streams Editor / Admin
/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/state PUT Controls container/VM power state (start/stop/etc.) Editor / Admin
/api/instances/:name/files GET Downloads a file from the instance filesystem Editor / Admin
/api/instances/:name/files POST Uploads/Overwrites a file on the instance filesystem Editor / Admin
/api/networks/reserved-ips GET Lists available and reserved IPs in the uplink pool Any Authenticated
/api/networks/reserved-ips PUT Deprecated configuration placeholder Editor / Admin
/api/networks/reserved-ips/reserve POST Allocates public IP to a running instance Editor / Admin
/api/networks/reserved-ips/release POST Releases public IP back to the uplink pool Editor / Admin
/api/networks/reserved-ips/ports PUT Modifies port forwarding (DNAT) mapping rules Editor / Admin
/api/images GET Lists remote system images (Ubuntu, etc.) Any Authenticated
/metrics GET Exposes Prometheus runtime instrumentation Prometheus Scraper
/terminal WS Establishes interactive terminal WebSocket stream Any Authenticated