# 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:

```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