Module join 

Authenticated cluster join through seed members (issue #988, ADR 0030).

Join is the explicit admission flow a candidate runs to become an authorized cluster member. The glossary fixes the steps: “a candidate member authenticates against seed members, verifies cluster identity, downloads global control-plane state, and only then becomes an authorized cluster member.” Until that completes, a node is just a reachable network peer — not a member, and not something autodetect will adopt.

The handshake, structurally

A seed member holds a SeedAuthority: the cluster’s ClusterId, an operator-provisioned allowlist of which identities may join (and as what kind), and the current MembershipCatalog. A candidate sends a JoinRequest carrying the cluster id it believes it is joining, its authenticated NodeIdentity, and the kind it intends to be. The seed:

1. Verifies cluster identity. A request that names a different cluster is JoinRejection::WrongCluster — authenticating correctly to the wrong cluster is still a rejection.
2. Authorizes the peer. An identity absent from the allowlist is an unknown/unauthorized peer: JoinRejection::UnauthorizedPeer. This is what stops “anyone who can open a connection” from joining.
3. Checks the declared kind. A peer allow-listed as a witness that asks to join as a data member (or vice versa) is JoinRejection::KindMismatch.
4. Admits and snapshots. The candidate is added to the catalog as a joined-empty member — no user ranges — and the seed returns a ControlPlaneSnapshot of the now-current membership for the candidate to adopt.

Authentication itself is mTLS: the NodeIdentity in a request is the validated X.509 subject of the peer certificate. JoinRequest::authenticated is the only constructor, so a request cannot exist without a proven identity — there is no “anonymous join” shape to defend against.

Structs

ControlPlaneSnapshot

The global control-plane state a freshly admitted member downloads — the authorized membership it should adopt as its starting view.

JoinGrant

A successful admission: the outcome (newly admitted vs. already a member) and the control-plane snapshot the candidate adopts.

JoinRequest

A candidate’s request to join a cluster through a seed member.

SeedAuthority

A seed member’s authority to admit join candidates.

Enums

JoinRejection

Why a join was refused. Each variant maps to one of the seed’s checks.