rdp-proxy/docs/architecture/WEB_INGRESS_AND_ADMIN_UI_MODEL.md

Web Ingress and Admin UI Model

Status: target architecture clarification. Documentation only.

This document defines how HTTP/HTTPS web entry, Admin UI, dynamic page composition, and cluster configuration responsibilities are separated in the Secure Access Fabric.

It does not implement code, APIs, UI pages, mesh runtime, VPN runtime, or RDP changes.

Purpose

The platform needs a clear distinction between:

• Web Service as the HTTP/HTTPS entry layer
• Control Plane as the owner of cluster configuration and policy
• Admin UI as a safe, scoped user interface over Control Plane APIs

The Web layer must never become the owner of cluster state, policy, topology, secrets, node identity, or routing authority.

Layer Ownership

Web Service / Web Ingress

Web Service is an edge service.

Suggested role names:

• web-ingress
• admin-web-entry
• admin-web-shell

Responsibilities:

• accept HTTP/HTTPS
• terminate TLS or sit behind the approved TLS terminator
• serve Admin UI shell/static assets
• proxy browser/API traffic to Control API
• apply edge controls such as headers, rate limits, request size limits, and future WAF rules
• expose only approved public/admin endpoints

Web Service must not:

• own cluster configuration
• directly mutate PostgreSQL
• store durable topology or policy
• store secrets
• store node identity or certificates as source of truth
• expose internal mesh topology to browser clients
• execute cluster decisions locally

Control Plane

Control Plane owns all durable cluster configuration and policy.

Responsibilities:

• clusters
• nodes
• node enrollment and approval
• role assignments
• organization and tenant policy
• service desired state
• service endpoint visibility
• signed scoped snapshots
• config distribution rules
• audit
• high-risk action authorization
• step-up authentication requirements

PostgreSQL remains the durable source of truth. Redis remains live coordination only.

Cluster configuration is changed only through Control Plane services and APIs. The Web layer is a presentation and ingress layer over those APIs.

Admin UI

Admin UI is a client application served through Web Ingress.

It renders safe Control Plane projections and submits user actions to Control Plane APIs.

Admin UI must not:

• contain embedded internal topology
• contain secrets
• contain raw credential references beyond safe indicators
• contain peer cache data
• contain route cache data
• contain private node-to-node endpoints unless explicitly authorized for the viewer
• contain executable cluster logic

Admin Endpoint Placement

Admin UI endpoint placement is explicit and must not be inferred from storage.

Scopes:

• Platform Owner Console: global platform-owner scope. It may aggregate multiple clusters through Control Plane APIs according to platform policy and audit.
• Cluster Admin Endpoint: cluster-local admin/web ingress endpoint for a single cluster. It is hosted only by nodes explicitly assigned an approved admin/web ingress role.
• Organization Admin Panel: tenant-safe projection for one organization. It must expose only allowed resources, service endpoints, sessions, policies, and safe status.

Rules:

• Fabric Storage / Config Storage nodes do not automatically host Admin UI.
• Adding a storage node to a new cluster does not move the cluster panel.
• Storage nodes distribute/cache scoped configuration and snapshots only.
• Admin/web ingress is a separate service role and requires explicit Control Plane assignment.
• Cluster-local admin endpoints require valid TLS/cert policy, signed scoped snapshots, current node health, and sufficient role coverage.
• Platform Owner Console remains the owner-level view even when cluster-local admin endpoints exist.
• Organization Admin Panel must never expose intermediate mesh topology, storage shards, peer caches, route caches, or unrelated cluster data.

Request Flow

Admin Browser
  -> Web Ingress / Admin Web Shell
  -> Control API
  -> PostgreSQL source of truth
  -> signed scoped snapshots / config distribution
  -> rap-node-agent

Web Ingress may cache static assets and safe UI manifests, but it must not become a second source of truth.

Dynamic Admin Pages

Admin pages may be dynamically composed, but they must be generated from safe metadata and scoped projections.

The recommended model is:

Admin Web Shell
  -> UI Manifest / Page Definition endpoint
  -> Scoped Control API endpoints

Dynamic pages are allowed for:

• platform admin sections
• cluster admin sections
• node detail sections
• service adapter safe configuration sections
• future organization admin sections

Dynamic pages must be declarative. They must not inject arbitrary executable code from the backend into the browser.

UI Manifest Model

The Control Plane may provide a ui_manifest or page definition for a specific viewer context.

Viewer context includes:

• user id
• platform role
• organization memberships
• cluster access scope
• device trust state
• MFA / step-up state
• feature flags
• service availability

The manifest may include:

• visible navigation sections
• page ids
• component ids from an approved component registry
• form schemas
• table schemas
• safe field labels and message keys
• allowed actions
• action risk level
• API route references
• required permissions
• required step-up authentication flags
• audit event category
• refresh hints

The manifest must not include:

• secrets
• raw credentials
• private keys
• full mesh topology
• full peer cache
• route cache
• unrelated organization data
• unrelated cluster data
• internal node-to-node route details
• arbitrary JavaScript or executable code

Page Definition Safety Rules

Dynamic pages are schema-driven views over safe data.

Rules:

• page definitions are data, not code
• page definitions must use an approved component registry
• fields must be explicitly typed
• actions must map to known Control Plane operations
• every action must be permission checked server-side
• high-risk actions must declare step-up requirements
• all mutations must be audited
• UI labels should use localization message keys with English fallback text
• sensitive responses should use Cache-Control: no-store

Client-side hiding is not authorization. The Control Plane must enforce all permissions and policies even if a browser crafts a request manually.

Safe Data Projection

The Control Plane should expose different projections for different audiences.

Platform owner/admin may see:

• clusters
• nodes
• join requests
• role assignments
• safe topology summaries
• service placement
• health and audit
• partition/recovery status
• active node for cluster-managed services where allowed

Organization admin may see only:

• organization resources
• organization users/groups where authorized
• organization policies
• active sessions
• allowed ingress endpoints
• allowed egress/service endpoints
• safe VPN/connector status
• organization audit

Organization admin must not see:

• intermediate core mesh topology
• other organizations
• peer caches
• route caches
• unrelated nodes
• platform trust roots
• raw node certificates
• secrets
• unrelated cluster internals

Service Adapter UI Extensions

Service adapters may need configuration UI.

Examples:

• RDP resource settings
• VNC resource settings
• SSH resource settings
• VPN/IP tunnel connection settings
• file policy settings
• video/audio policy settings

Adapter UI extensions must be registered as safe schema descriptors through the Control Plane. Adapters must not directly publish arbitrary browser code.

Allowed extension content:

• field schema
• validation hints
• policy options
• message keys
• safe help text
• action ids mapped to Control Plane APIs

Disallowed extension content:

• executable code
• protocol secrets
• internal adapter memory/state
• raw target credentials
• unrestricted backend endpoints

Cluster Configuration Ownership

Cluster configuration belongs to Control Plane.

Examples:

• cluster creation and disablement
• node approval
• node role assignment
• service desired state
• VPN connection desired state
• allowed node policy
• route policy
• QoS policy
• signed snapshot generation
• storage/config distribution scope

Admin UI may present these controls, but it does not own the decisions.

The authoritative path is:

Admin action
  -> Control API authorization
  -> policy validation
  -> PostgreSQL mutation
  -> audit event
  -> snapshot/config distribution update
  -> node-agent consumption

Security Requirements

Web/Admin security requirements:

• TLS for all browser traffic
• secure cookies or approved token storage model
• CSRF protection where cookie auth is used
• CSP for Admin UI
• no secrets in HTML or JavaScript bundles
• no internal topology embedded in static assets
• no arbitrary backend-provided JavaScript
• strict server-side authorization
• risk-based admin access
• MFA/2FA and step-up for high-risk actions
• audit every mutation
• short-lived UI manifests where sensitive
• no-store cache headers for sensitive API responses

High-risk actions include:

• node approval
• role assignment
• cluster trust changes
• cross-cluster trust changes
• partition promotion
• secrets access
• update policy changes
• VPN credential/config resolver access

Deployment Model

Possible deployment modes:

• Web Ingress and Control API in the same deployment for small/test installs
• Web Ingress separated from Control API for production
• multiple Web Ingress nodes for regional/admin access
• Web Ingress behind Caddy/Nginx/enterprise ingress
• Admin UI shell served from Web Ingress while APIs remain on Control API

Even when deployed together, ownership remains separate:

• Web Ingress is entry/presentation
• Control API is authorization/domain logic
• PostgreSQL is source of truth
• Fabric Storage/Config Storage is scoped distribution/cache
• node-agent consumes scoped desired state

Future Stages

Suggested staged work:

WEB-1: Document Web Ingress and Admin UI ownership model.

WEB-2: Define ui_manifest schema and approved component registry.

WEB-3: Add platform-admin Admin Web Shell that consumes scoped manifests. Initial Platform Owner Control Panel is implemented and build-verified in web-admin. Report: artifacts/web-admin-platform-owner-control-panel-report.md.

WEB-4: Add cluster admin pages using Control Plane projections.

WEB-5: Add organization admin pages using tenant-safe projections.

WEB-6: Add high-risk action step-up and device-trust UI flows.

WEB-7: Add service-adapter UI extension registry.

WEB-8: Add signed/versioned UI manifest distribution if needed for offline or edge-served admin shells.

Non-Goals

This document does not authorize:

• implementation of new UI pages
• changing existing Windows client behavior
• changing RDP runtime
• mesh runtime
• VPN runtime
• node-agent service execution changes
• storing cluster configuration inside Web Service
• exposing internal topology to organizations

Result / Decision

WEB is an ingress and presentation layer, not a cluster configuration owner. Cluster configuration belongs to the Control Plane and is persisted in PostgreSQL. Dynamic admin pages are allowed only as safe, scoped, schema-driven projections over Control Plane APIs. They must not embed secrets, internal topology, peer caches, route caches, or arbitrary executable code.

Admin endpoint placement is explicit. A Fabric Storage / Config Storage node does not automatically become a cluster panel. Platform Owner Console remains global platform-owner scope; Cluster Admin Endpoint is a separate cluster-local admin/web ingress role; Organization Admin Panel remains a tenant-safe projection.