[Security] The cluster `hello` identity is not bound to the TLS peer certificate, so mTLS admits a node but never verifies which node it is

[pathosDev]

Component: src/cluster/Transport.ts
Severity (assessment): MEDIUM — see the note at the end, it is arguable
CWE: CWE-287 (improper authentication)

The hello frame carries a NodeAddress and nothing else. Even on a fully
mTLS-configured cluster, nothing ties the identity a peer claims in hello
to the identity its certificate proves. mTLS answers "is this peer allowed
in the cluster"; it never answers "is this peer the node it says it is".

Why this matters now

The gossip-authority rules landed in #562/#564/#572 are all keyed on the
connection's peer — deliberately, because the payload's from is the one
field an attacker fully controls. Those rules are exactly as strong as the
connection identity underneath them, and today that identity is self-declared.

So a single compromised or malicious CA-signed node can still:

• announce itself under another member's address and, once the leader
  promotes it, satisfy the "sender must be an active member" rule for
  third-party claims;
• receive traffic addressed to the impersonated node, because
  TcpTransport.byPeer is keyed on the claimed address.

The duplicate-identity guard (Transport.ts:299-313) only blocks claiming an
address that is already mapped. A fresh claim, or a claim made after the
real holder's connection drops, is accepted.

Evidence

src/cluster/Transport.ts — onMessage accepts any hello and registers it:

if (message.kind === 'hello') {
  const peer = NodeAddress.fromJSON(message.self);
  const peerKey = peer.toString();
  // ... hijack guard: only rejects an ALREADY-mapped peerKey ...
  connection.peer = peer;
  this.byPeer.set(peerKey, connection);

TcpSocketLike (src/runtime/tcp/TcpBackend.ts:44-48) exposes only
write / end / remoteAddress — the peer certificate is not surfaced by
the abstraction at all, so no code above the adapters could check it today.

This is also stated as a known residual in the #565 verifier notes ("the only
check is a duplicate-identity guard … not a fresh claimed identity") but was
never filed on its own.

Proposed approach

1. Surface the verified peer certificate on TcpSocketLike — Node exposes
   tlsSocket.getPeerCertificate(), Bun has an equivalent; on Deno the
   listener half of mTLS is unavailable anyway ([Security] DenoTcpBackend silently drops ca, requestClientCert and the client cert/key — cluster mTLS cannot be enabled at all on Deno #576), so the field is
   undefined there and the check degrades to today's behaviour.
2. When the listener required a client certificate, reject a hello whose
   claimed systemName@host is not covered by the certificate's CN or a SAN
   entry. Log and drop the connection, the same way the frame guards do.
3. Leave plain-TCP clusters as they are — the transport is documented as
   unauthenticated there, and this check has nothing to work with.

Acceptance criteria

• A peer presenting a valid CA-signed certificate for node-a cannot
  complete a hello claiming to be node-b.
• A matching certificate still completes the handshake unchanged.
• With no client certificate required, behaviour is unchanged.
• docs/.../operations/security/cluster-security.mdx (EN + DE) drops the
  "This is not authentication" caveat added alongside the gossip-authority
  rules, since it would no longer be true for mTLS clusters.

Severity note

Filed medium to match how the tracker already calibrates "one authenticated
member can impersonate another" (#574, #582, #719 are all medium). An argument
for high exists: this is the assumption every one of the new authority rules
rests on, so it is less a finding of its own than the floor beneath several
others. Retag if you read the boundary that way.

Related

• [Security] Cluster TLS listener never requests a client certificate — requestClientCert defaults to false, so the documented mTLS recipe gives zero peer authentication #565 — made the listener actually request a client certificate (closed); this
  is the half that verifies what the certificate says.
• [Security] mergeMember lets any peer assert any status for any node, including the receiver's own record — no origin/authority rule on gossip #562, [Security] Forged leave frame lets any unauthenticated wire peer tombstone (evict) any cluster member for 24 h, and the eviction spreads via gossip #564, [Security] Forged heartbeat.from keeps a dead node "healthy" forever (blocks singleton/shard failover) and makes the node dial an attacker-chosen host:port #572 — the authority rules that depend on the connection identity.
• [Security] DenoTcpBackend silently drops ca, requestClientCert and the client cert/key — cluster mTLS cannot be enabled at all on Deno #576 — Deno cannot host an mTLS listener, so step 1 is a no-op there.
• [Feature] Cluster wire-protocol versioning + mixed-version handshake (rolling-upgrade safety) #823 — wire-protocol versioning; a credential-bearing hello is a protocol
  change and should be sequenced with it.

[pathosDev]

Course notes — the scope was wider than the report, two runtime facts contradicted the obvious design, and my first matching rule had a hole.

1. There was nothing to read the certificate with. The report treats this as a check to add in Transport.onMessage. But TcpSocketLike (src/runtime/tcp/TcpBackend.ts:44) carried only remoteAddress — no peer-certificate accessor existed at any layer. The fix therefore needed a new accessor across all three backends first, landed as its own commit so it changes no behaviour on its own.

2. Two runtime facts, measured against a generated CA rather than assumed — both would have been wrong guesses:

• Bun fires open before the TLS handshake completes. At that point authorized is false and getPeerCertificate() returns nothing; the certificate only appears in the handshake callback. Node, by contrast, hands tls.createServer's listener a socket that is already secure. So an accessor read eagerly at onOpen works on Node and silently returns nothing on Bun — the worst kind of difference. It has to be a lazily-read method, and the transport reads it when a frame arrives, which necessarily post-dates the handshake.
• Deno exposes no peer certificate at all. Deno.TlsConn has no accessor and handshake() resolves to { alpnProtocol: null } on both ends. So the method is optional and Deno omits it — a caller can then tell "no certificate presented" from "this runtime cannot say". Collapsing those two would turn a Deno node into one that either rejects every peer or believes every claim.

3. My first matching rule was exploitable, and my own test caught it. The rule accepts either the address's host or the full systemName@host. I applied leftmost-label wildcards to both. That is wrong: matching *.internal against the composite reads node-b@node-a as a single dotless "label", so a wildcard host certificate would have vouched for node-b@node-a.internal — reinstating exactly the impersonation this issue is about.

Wildcards now apply to the host only. systemName@host is not a DNS name — it is an identity string this project composes — so it is exact-match. Both arms are pinned by tests.

4. No configuration key, deliberately. The check is skipped exactly when there is nothing to check: plain TCP, one-way TLS, and Deno. A tri-state or a require flag was considered and dropped — it would be a knob left off on precisely the deployments that most believe they have mTLS, and it would drag in ConfigKeys and the NoDeadConfigKeys gate for no gain.

5. Stated limit rather than a hidden one. Two nodes presenting the same host certificate are indistinguishable to this check, and no certificate-based rule could separate them. Deployments needing node-level identity must issue per-node certificates naming systemName@host. Documented in both languages and pinned by a test, so it cannot quietly be assumed away.

Verification: unit tests cover the matching rule; the binding itself was checked end to end on Bun against a generated CA — a dialer whose certificate names node-b and whose hello claims 127.0.0.1 is refused with the connection closed and no peer registered, while one carrying IP:127.0.0.1 completes the handshake unchanged.

[pathosDev]

Re-derived independently in the production-readiness review tracked in #913, which folded a broader finding into this issue rather than duplicating it.

Two additions to the scope here:

1. The plaintext case. This issue is framed around mTLS, but the identity is self-declared whether or not TLS is configured — and remote.tcp.host defaults to 0.0.0.0 (src/config/reference.ts:40). With TLS off, anyone who can reach the port completes hello with an address of their choosing. The mTLS binding is the fix for the configured case; the unconfigured case needs a credential of some kind (a pre-shared cluster secret HMAC'd over a server nonce, in the Erlang-cookie shape) or it is open by construction.

2. remoteAddress is already available and is read nowhere. All three TCP backends expose it — src/runtime/tcp/TcpBackend.ts:47, NodeTcpBackend.ts:122, BunTcpBackend.ts:79, DenoTcpBackend.ts:137 — and a repo-wide grep finds no reader in src/cluster/. So the non-TLS half of the binding is available today at the cost of one comparison in TcpTransport.onMessage.

Worth stating explicitly for anyone triaging: maySpeakFor's JSDoc says it "deliberately keys on the connection, not on message.from: a payload field is the one thing an attacker fully controls". That is true of the code and false of the guarantee, because the connection's identity is itself a payload field. Every rule built on it (#562, #564, #572, #574, #582) is exactly as strong as this issue.

[pathosDev]

Course note on the fourth acceptance criterion — it was met differently than written, deliberately.

The criterion asked to drop the "This is not authentication" caveat from cluster-security.mdx (EN + DE), on the reasoning that it "would no longer be true for mTLS clusters". e017be48 instead narrowed it to the non-mTLS case rather than removing it, and that is the better answer: the binding it adds is conditional on a certificate being presented (Transport.ts:402-403 — if (certificate === undefined) return true;), so on a cluster with no peer certificates the hello handshake still carries no credential. Dropping the block outright would have made the page wrong for the default configuration.

The caveat now reads, in relevant part:

…on a cluster with no peer certificates the hello handshake carries no credential, so an attacker can announce itself, wait to be promoted, and then satisfy the second rule. Run mTLS if the network is not fully trusted — under mTLS the claimed address must match the peer's certificate, which is what gives these rules a real subject.

That is accurate for both configurations, and the commit additionally added a new "The certificate also decides which node" section plus an aside on what a shared host certificate cannot separate. So the intent behind the criterion — the page must not overstate what the gossip-authority rules provide — is satisfied; only its literal wording is not.

Recording this rather than silently ticking the box, per the rule added in 790fd726. Nothing is outstanding on this issue.

The residual scope the criterion's original wording gestures at — that a plaintext or one-way-TLS cluster has no admission credential at all, and that dispatchEnvelope resolves any to path from the root cell regardless — is out of scope here and is tracked separately as #964.