Direct Worker WSS TLS / PKI

Archived status: this document captures a direct-worker WSS trust design track and is no longer the primary reference for node-to-node transport. The active fabric transport model is QUIC-only between nodes; see docs/architecture/DISTRIBUTED_FABRIC_NODE_PROTOCOL_PLAN.md, docs/architecture/FABRIC_FIRST_TRANSPORT_AND_STRESS_PLAN.md, and docs/architecture/SECURE_ACCESS_FABRIC_TARGET.md.

Status: P3.4 trust-model design/prep complete.

This document defines the production trust model for direct worker WSS. It does not implement mesh, relay nodes, VPN, QUIC, WebRTC, or a new RDP runtime.

Detailed P3.4 production certificate lifecycle, worker identity binding, client trust, rotation, revocation, and future smoke plan are defined in docs/architecture/PRODUCTION_DIRECT_WORKER_WSS_TRUST.md.

Goal

Direct worker WSS is the preferred RDP realtime data-plane path. In production, the Access Client must only use direct worker WSS when both conditions are true:

the backend advertises the candidate as production trusted
normal TLS certificate validation succeeds

The backend gateway remains the safe fallback/debug path.

Trust Modes

Backend config DATA_PLANE_DIRECT_WORKER_TLS_TRUST_MODE supports:

smoke_insecure: development/smoke only; candidate metadata is smoke_only=true and production_trusted=false
public_ca: worker certificate chains to an OS/publicly trusted CA; candidate metadata is production_trusted=true
platform_ca: worker certificate chains to a platform-managed CA; candidate metadata is production_trusted=true

Optional DATA_PLANE_DIRECT_WORKER_TLS_CA_REF labels the platform CA or trust bundle version in candidate metadata, for example rap-platform-ca:v1.

Backend Enforcement

In production (APP_ENV=production or APP_ENV=prod):

backend must not advertise direct_worker_wss candidates when DATA_PLANE_DIRECT_WORKER_TLS_TRUST_MODE=smoke_insecure
backend still advertises backend_gateway fallback when configured
direct candidates include trust metadata only when they are data-capable

Candidate metadata:

{
  "runtime_transport": "json_v1",
  "traffic_ready": true,
  "tls_trust_mode": "platform_ca",
  "production_trusted": true,
  "smoke_only": false,
  "tls_ca_ref": "rap-platform-ca:v1"
}

Windows Client Enforcement

Client config environment=production or prod means:

smoke-only direct candidates are skipped
candidates without production trust metadata are skipped
allow_insecure_direct_data_plane_tls_for_smoke is ignored for direct worker WSS
the client falls back to backend gateway instead of weakening TLS

In development/smoke:

allow_insecure_direct_data_plane_tls_for_smoke=true may bypass certificate validation only for smoke-only direct candidates
this bypass must not be used as a production trust mechanism

Worker Requirements

The worker direct WSS endpoint already requires:

RDP_WORKER_DATA_PLANE_TLS_CERT_FILE
RDP_WORKER_DATA_PLANE_TLS_KEY_FILE
RDP_WORKER_DATA_PLANE_PUBLIC_KEY_FILE or RDP_WORKER_DATA_PLANE_PUBLIC_KEY_PEM

Production workers should use certificates issued for their advertised direct WSS hostname/IP subject alternative names. Platform-managed deployments should prefer a dedicated platform CA and rotation workflow.

Remaining Work

implement app-local platform CA trust bundle handling in Windows clients
automate worker certificate issuance/rotation
rotate backend data-plane signing keys
add live test-stand proof with platform_ca production-trusted direct WSS
later integrate node-agent certificate enrollment

3.6 KiB Raw Permalink Blame History