# 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 ```text 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: ```text 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: ```text 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.