Initial project snapshot

2026-04-28 22:29:50 +03:00
commit 8ba0561f4f
365 changed files with 91832 additions and 0 deletions
@@ -0,0 +1,93 @@
+# Direct Worker WSS TLS / PKI
+
+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:
+
+```json
+{
+  "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