[Security] `remote.tls.enabled` HOCON key is documented but dead — nothing in src/ reads it, so operators believe TLS is on when it is not

[pathosDev]

Component: src/config/reference.ts
Severity (assessment): LOW
CWE: CWE-1053 (missing documentation for design) / misleading security control

actor-ts.remote.tls.enabled is defined in the reference config and documented in the
configuration table, but nothing in src/ ever reads it. An operator who sets it to
true gets no TLS and no error — the cluster transport stays plaintext.

Exploit walkthrough

This is a misleading-control finding rather than a directly exploitable one, but the
outcome is a real production exposure: an operator hardening a deployment finds
remote.tls.enabled in the documented configuration reference, sets it to true,
sees the cluster come up healthy, and concludes the cluster transport is encrypted.
It is not. All gossip, heartbeats and actor envelopes — including message payloads —
continue in cleartext, and the node accepts unauthenticated hello frames from anyone
who can reach the port.

There is no warning, no validation error and no log line. The only way to discover the
truth is to packet-capture the transport or read the source. Combined with the fact that
TLS is only reachable by constructing TcpTransport yourself and passing it via
ClusterOptions.withTransport(...), an operator following the config reference alone
cannot enable TLS at all.

Evidence

The key exists in the reference config:

// src/config/reference.ts:37-47
  remote {
    transport = "tcp"
    tcp {
      hostname = "0.0.0.0"
      port = 2552
    }
    tls {
      enabled = false
    }
    max-frame-size = 1M
  }

It is documented as a real knob:

docs/src/content/docs/reference/configuration.mdx:107
| remote.tls.enabled | false | Toggle TLS on the cluster transport. |

(German mirror: docs/src/content/docs/de/reference/configuration.mdx:108.)

But it is absent from the typed key tree — src/config/ConfigKeys.ts has no remote.*
subtree at all (the only cluster-transport entry is transport: 'actor-ts.transport'),
and a repo-wide grep for remote.tls matches only the two documentation pages. There
is no reader in src/.

Why the existing guard does not cover it

ClusterOptionsValidator (src/cluster/ClusterOptions.ts:155-173) validates host, port
and the various interval fields; it has no visibility into transport TLS, and
ClusterOptionsType has no tls field. TcpTransport takes TLS as a positional
constructor argument (src/cluster/Transport.ts:69-83) and has no validator at all, so
nothing anywhere can notice that a HOCON TLS toggle was set but never honoured.

Suggested fix

Pick one and make it true:

1. Wire it up — add the remote.tls.* keys to ConfigKeys.ts (enabled, cert,
   key, ca, requestClientCert, rejectUnauthorized), read them where the default
   TcpTransport is constructed (src/cluster/Cluster.ts:124), and give TcpTransport
   an options object with a validator so the combination can be checked. This is the
   option that matches what the docs already promise.
2. Or remove it — drop the block from src/config/reference.ts and both
   configuration tables, and state plainly that cluster TLS is configured by constructing
   TcpTransport with a TlsTransportOptionsType and passing it via
   ClusterOptions.withTransport(...).

Leaving a documented security toggle that silently does nothing is the one option that
should not survive triage. Whichever route is taken, it interacts directly with the
requestClientCert finding — the two should land together.

Verification status

Found while planning the remediation of the 2026-08-01 security audit, not by the audit
sweep itself. Verified by direct inspection: the key is present in
src/config/reference.ts:44, documented at configuration.mdx:107, and a repo-wide
grep for remote.tls returns only the two doc pages — no consumer in src/.

[pathosDev]

Config-shape proposal captured while sweeping the configuration surface for the reference.conf expansion batch (#887):

actor-ts.remote.tls {
  enabled = off
  key-file = ""            # PEM, file-path indirection — secrets never inline
  cert-file = ""
  ca-cert-file = ""
  require-mutual-authentication = on
  hostname-verification = on
  context-cache-ttl = 5m    # re-read cert material on expiry -> cheap rotation
}

File-path + cache-TTL gives rotation without a restart; mutual auth on by default matches the cluster's peer model. When the implementation lands, these keys leave the KNOWN_DEAD_KEYS exception list in NoDeadConfigKeys.test.ts.