clusterer_controller: document node_id allocation and trust-model limits

Add two paragraphs to the Security Architecture section:

  - Node identity and node_id allocation: ids are master-allocated,
    stable across restart (same IP reuses the id), and never collide
    during the failure-detection window since a failed-but-not-timed-out
    node keeps its slot. States the deployment requirement that each node
    present a stable, unique source IP (peers are keyed by IP; nodes
    sharing an address via NAT would share a slot/node_id).

  - Trust model: the cluster is a single shared-secret trust domain, so a
    party holding the password can legitimately win the election and take
    master. Rogue outsiders cannot (AEAD + per-source sequence check drop
    forged/replayed election packets). The residual risk is a malicious
    insider; per-node identity with revocation is noted as future work.

Regenerated README from the docbook source.

Author: Yury Kirsanov

modules/clusterer_controller/README

@@ -450,6 +450,43 @@ on-key")
    line, a refused join, or a self-correction rather than a
    hard-to-diagnose HA failure.
 
+   Node identity and node_id allocation: node_id values are
+   allocated exclusively by the current master, serialised under
+   the peer-table lock, and a joining node never picks its own id.
+   The master hands out the lowest unused id by scanning the live
+   peer table, so a node that has failed but is not yet timed out
+   still occupies its slot and its id is never handed to a
+   different joiner — new nodes always receive a distinct id even
+   during the failure-detection window. A node that restarts and
+   rejoins from the same address reuses its previous id (and has
+   its replay counter reset), so ids stay stable across restarts.
+   Because peers are keyed by source IP address, every node in a
+   cluster must present a stable, unique source IP: two distinct
+   nodes that appear behind the same address (for example through
+   NAT) would share a single peer slot and node_id. Deploy the
+   cluster on a network where each member has its own routable
+   address on the BIN/multicast interface.
+
+   Trust model — shared secret, not per-node identity: the cluster
+   is a single shared-secret trust domain. Authentication proves
+   only that a peer holds the cluster password; it does not bind a
+   cryptographic identity to an individual node, and there is no
+   per-node authorisation or revocation. Consequently any party in
+   possession of the password is a fully trusted member and can
+   legitimately win the highest-IP master election and assume the
+   master role — there is no distinction between "may be a member"
+   and "may be master". An attacker without the password cannot
+   affect the election at all: forged or replayed MASTER_ALIVE and
+   beacon packets fail AEAD authentication (or the strict
+   per-source sequence check) and are dropped before any election
+   logic runs. The residual exposure is therefore a malicious or
+   compromised insider that already holds the shared key. Protect
+   the password accordingly, and rotate it if a node is
+   decommissioned or suspected compromised. Removing this
+   limitation — per-node keypairs with enrolment and revocation,
+   so a single node can be distrusted without re-keying the whole
+   cluster — is planned future work.
+
 1.5. Dependencies
 
 1.5.1. OpenSIPS Modules

modules/clusterer_controller/doc/clusterer_controller_admin.xml

@@ -446,6 +446,43 @@
 	refused join, or a self-correction rather than a hard-to-diagnose HA
 	failure.
     </para>
+    <para>
+	<emphasis role="bold">Node identity and node_id allocation:</emphasis>
+	<varname>node_id</varname> values are allocated exclusively by the current
+	master, serialised under the peer-table lock, and a joining node never
+	picks its own id. The master hands out the lowest unused id by scanning
+	the live peer table, so a node that has failed but is not yet timed out
+	still occupies its slot and its id is never handed to a different joiner —
+	new nodes always receive a distinct id even during the failure-detection
+	window. A node that restarts and rejoins from the same address reuses its
+	previous id (and has its replay counter reset), so ids stay stable across
+	restarts. Because peers are keyed by source IP address, every node in a
+	cluster must present a stable, unique source IP: two distinct nodes that
+	appear behind the same address (for example through NAT) would share a
+	single peer slot and <varname>node_id</varname>. Deploy the cluster on a
+	network where each member has its own routable address on the
+	BIN/multicast interface.
+    </para>
+    <para>
+	<emphasis role="bold">Trust model — shared secret, not per-node
+	identity:</emphasis> the cluster is a single shared-secret trust domain.
+	Authentication proves only that a peer holds the cluster password; it does
+	not bind a cryptographic identity to an individual node, and there is no
+	per-node authorisation or revocation. Consequently any party in possession
+	of the password is a fully trusted member and can legitimately win the
+	highest-IP master election and assume the master role — there is no
+	distinction between "may be a member" and "may be master". An attacker
+	<emphasis>without</emphasis> the password cannot affect the election at
+	all: forged or replayed <emphasis>MASTER_ALIVE</emphasis> and beacon
+	packets fail AEAD authentication (or the strict per-source sequence check)
+	and are dropped before any election logic runs. The residual exposure is
+	therefore a malicious or compromised <emphasis>insider</emphasis> that
+	already holds the shared key. Protect the password accordingly, and rotate
+	it if a node is decommissioned or suspected compromised. Removing this
+	limitation — per-node keypairs with enrolment and revocation, so a single
+	node can be distrusted without re-keying the whole cluster — is planned
+	future work.
+    </para>
     </section>
 
     <section id="dependencies" xreflabel="Dependencies">