Initial project snapshot
This commit is contained in:
@@ -0,0 +1,429 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user